diff --git a/.acrolinx-config.edn b/.acrolinx-config.edn index f6076b51964..78cdd0e4df0 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 d6a22e7b7ef..00000000000 --- 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 189349bd9ab..00000000000 --- 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 7231cf6266e..00000000000 --- 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 35de11091d9..00000000000 --- 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 b27ff51d563..00000000000 --- 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 7f86f82da5e..00000000000 --- 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 00000000000..6498b2c6631 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,186 @@ +# Copilot Instructions for `cpp-docs-pr` + +## Introduction + +This document contains general and repository-specific instructions for GitHub Copilot when assisting with the `cpp-docs-pr` repository. + +## Priority Levels + +This document uses the following markers to indicate instruction priority: + +- **[REQUIRED]** - Must be followed. May cause build failures or PR blocks if violated +- **[STYLE]** - Microsoft Writing Style Guide requirement for consistency +- **[C++-SPECIFIC]** - C++ documentation convention that overrides general guidance +- No marker - Best practice recommendation; use judgment based on context + +## General Guidelines + +### Using MCP tools +If the user intent relates to Azure Devops, make sure to prioritize the Azure DevOps MCP server tools. + +### 1. Issue Handling +When creating a PR for an issue: +- [ ] Read the full issue and all linked references + - [ ] **new-feature:** State which version introduced the feature + - [ ] **bug:** Focus on correcting technical inaccuracies +- [ ] When you're assigned an issue, after you've completed your work and the workflows (status checks) have run, ensure there are no build warnings under the OpenPublishing.Build status check. If there are, open the build report (under View Details) and resolve any build warnings you introduced. +- [ ] When starting work on an issue, document your understanding in a comment: state the issue's purpose, expected outcome, and your implementation approach. + +### 2. Issue Discussion Analysis +When working on an issue: +- [ ] **Read the complete issue discussion** - Don't rely solely on the initial issue description +- [ ] **Prioritize maintainer guidance** - Comments from repository maintainers (especially those with "MEMBER" association) should take precedence over the original issue description +- [ ] **Look for updated analysis** - Later comments may contain revised understanding, additional context, or modified resolution approaches +- [ ] **Check for explicit instructions** - Look for phrases like "Action required by GitHub Copilot" or direct "@copilot" mentions that provide specific guidance +- [ ] **Validate your understanding** - If the discussion seems to contradict the initial issue description, follow the most recent maintainer guidance + +### 3. File Naming and Organization +**Naming conventions:** +- [ ] Name new Markdown files in all lowercase with hyphens separating words +- [ ] Omit filler words like "the" or "a" from file names + +**Folder structure:** +- [ ] Linux topics → `docs/linux/` +- [ ] C++ STL → `docs/standard-library/` +- [ ] C runtime → `docs/c-runtime-library/` +- [ ] C++ language → `docs/cpp/` +- [ ] Visual Studio IDE features → `docs/ide/` +- [ ] Build process/modules → `docs/build/reference/` +- [ ] Build Insights → `docs/build-insights/` + +### 4. Links and References +- [ ] Add links to related topics and resources where appropriate. +- [ ] Use relative links for files in this repo +- [ ] **[REQUIRED]** 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. +- [ ] **[REQUIRED]** Links to bookmarks within the same article should be relative and start with `#`. +- [ ] **[REQUIRED]** Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here". +- [ ] **[STYLE]** 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. +- [ ] For external links to non-Microsoft sites: + - [ ] **[REQUIRED]** Use absolute URLs + - [ ] **[REQUIRED]** Remove any language or culture segment from the URL path (such as `/en-us/`, `/fr-fr/`, `/en/`, etc.) + - [ ] Example (MDN): + - [ ] Original: `https://developer.mozilla.org/en-US/docs/Web/API/Element/click_event` + - [ ] Correct: `https://developer.mozilla.org/docs/Web/API/Element/click_event` + +- [ ] For links to Microsoft Learn content in other repositories: + - [ ] **[REQUIRED]** Use the relative URL starting with a forward slash + - [ ] Don't include the scheme and the host (example: `https://learn.microsoft.com`) and don't include the locale (example: `en-us`) + - [ ] Example: For the target Learn website URL `https://learn.microsoft.com/en-us/dotnet/core/introduction`, use the relative URL `/dotnet/core/introduction` for the link destination + +## Repository-Specific Guidelines +- [ ] **[REQUIRED]** Follow the [Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/) + - [ ] Use contractions following the guidance in [Use contractions](https://learn.microsoft.com/en-us/style-guide/word-choice/use-contractions) +- [ ] **Repository Exceptions**: + - [ ] **[REQUIRED]** Use **bold** text for UI elements like menu items, dialog names, and names of text boxes. + - [ ] **[REQUIRED]** Number ordered lists as "1." for every item (don't use sequential numbers) + - [ ] **[REQUIRED]** Use backticks around content specifically for file names (`file.txt`), folders (`folder`), file paths (`folder/file.txt`), custom types (`myVariable`, `MyClass`), raw URLs in the text (`https://www.contoso.com`), file extensions (`.cpp`), and code like method names, property names, and language keywords. Also use for text that should never be localized. + - [ ] **[REQUIRED]** Use `code style` for resource names (like virtual machine names) that shouldn't be localized. + - [ ] **[C++-SPECIFIC]** Use `code style` for command-line commands. The style in some articles uses **bold** for command-line commands, but use `code style` instead. + - [ ] **[STYLE]** Use placeholders with braces in the format `{PLACEHOLDER NAME}` when used code examples and other contexts where placeholders are used. Use uppercase letters with spaces between words for the placeholder name inside the braces. + - [ ] Wrong: "Launch the app and navigate to `https://localhost:/openapi/v1.json` to view the generated OpenAPI document." + - [ ] Correct: "Launch the app and navigate to `https://localhost:{PORT}/openapi/v1.json` to view the generated OpenAPI document, where the `{PORT}` placeholder is the port." + - [ ] For any new or updated .md file added to the repository, ensure the following frontmatter (metadata) is included as specified in [Metadata for Microsoft Learn documentation.](https://learn.microsoft.com/en-us/contribute/content/metadata): + - [ ] **[REQUIRED]** Metadata `ai-usage: ai-assisted` if any AI assistance was used. + - [ ] **[REQUIRED]** When updating a topic that has the ms.assetid: metadata, remove the entire ms.assetid line. + - [ ] **[REQUIRED]** Place the title metadata first, followed by the remaining metadata lines as shown in the following example: +**Example:** + ```yaml + --- + title: "Understanding C++ modules" + description: "Learn how to use C++ modules in Visual Studio" + author: github-username + ms.author: ms-alias + ms.date: 12/11/2025 + ms.topic: concept-article + ai-usage: ai-assisted + --- + ``` + +### 5. Content Writing Guidelines +- [ ] **[STYLE]** Get to the point fast. Be concise and clear. +- [ ] **[STYLE]** Talk like a person. +- [ ] **[STYLE]** Simpler is better. +- [ ] **[STYLE]** Be brief. Give customers just enough information to make decisions confidently. Prune excess words. +- [ ] **[STYLE]** Break up long sentences. +- [ ] **[STYLE]** 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." +- [ ] **[STYLE]** Write factual statements and direct commands. Avoid hypotheticals. +- [ ] **[STYLE]** Use active voice where the subject performs the action. +- [ ] **[STYLE]** Write in second person (you) to speak directly to readers. +- [ ] **[STYLE]** Use gender-neutral language. +- [ ] **[STYLE]** Avoid multiple -ing words that could create ambiguity. +- [ ] **[STYLE]** Keep prepositional phrases simple and clear. +- [ ] **[STYLE]** Place modifiers close to what they modify. +- [ ] **[STYLE]** Use a conversational tone with contractions. +- [ ] **[STYLE]** Don't use "we" or "our" to refer to the authors of the documentation. +- [ ] **[STYLE]** Use the imperative mood for instructions. For example, "Call the method" instead of "You should call the method." +- [ ] **[STYLE]** Use "might" instead of "may" to indicate possibility. For example, "This method might throw an exception" instead of "This method may throw an exception." +- [ ] **[STYLE]** Use the Oxford comma in lists of three or more items. +- [ ] Introductory paragraph: + - [ ] When drafting the first paragraph of any new article, or when significantly updating an existing article: + - [ ] Explain why and when the topic matters in practical C++ development scenarios. + - [ ] Give a concise summary of what the article covers or enables, so readers know what to expect. + - [ ] When significantly updating, revise the introductory paragraph to match the new scope and content. + +### 6. PR Description Requirements +- [ ] ALWAYS include "Fixes #[issue-number]" in the PR description, at the first line of the description to link back to the original issue +- [ ] Include a clear summary of changes made +- [ ] List all files that were modified with brief descriptions + +## 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 + +The following does NOT apply to step numbers but applies to all other 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 sequentially as 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. + +## 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. + +## 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/.github/copilot-issue-verification-action-plan.md b/.github/copilot-issue-verification-action-plan.md new file mode 100644 index 00000000000..3f6d7e270e6 --- /dev/null +++ b/.github/copilot-issue-verification-action-plan.md @@ -0,0 +1,220 @@ +--- +ai-usage: ai-assisted +author: TylerMSFT +ms.author: twhitney +ms.date: 11/13/2025 +--- + +# GitHub issue analysis and action plan prompt for C++ documentation + +## Goal +Analyze the GitHub issue and provide a **structured report** determining: +1. Whether the issue is valid and actionable. +2. Whether the issue is within scope of the articles the issue relates to, or if a new article is needed. +3. The exact documentation changes required (if applicable). +4. A clear action plan that can guide PR creation. + +The report should be suitable for posting directly in the issue discussion. + +--- + +## Analysis Steps + +### 1. Information Gathering +Collect and review: +* The **issue title, description, and all comments**. +* The **published documentation** (via the provided URL). +* The **source file(s)** in the repository. +* Any **linked issues, PRs, or external references**. +* **Environment details**: .NET version, tooling versions (VS, VS Code, CLI, EF Core, etc.). +* **Code samples or error messages** mentioned in the issue. + +### 1.5 Source File Analysis +When examining source files: +* **Provide direct GitHub permalinks** to specific lines or sections. +* **Note exact line numbers** for proposed changes. +* **Include line number ranges** in GitHub URLs using `#L-L` format. +* **Quote current content** from specific lines before proposing changes. +* **Use permalinks with commit SHA** when referencing specific versions. + +Example format for file references: +* Single line: `https://github.com/owner/repo/blob/main/file.md#L123`. +* Line range: `https://github.com/owner/repo/blob/main/file.md#L123-L145`. +* Permalink: `https://github.com/owner/repo/blob//file.md#L123`. + +### 2. Validation Criteria +Determine if the issue is: +* **In scope**: Related to ASP.NET Core documentation (not product bugs). +* **Accurate**: The reported problem genuinely exists. +* **Clear**: Sufficient information to take action. +* **Current**: Applies to supported .NET versions. + +### 3. Translation Requirements +If any content is not in English: +* Include the original text in a quote block. +* Provide complete English translation. +* Label clearly as "Original" and "Translation". + +--- + +## Output Format + +### File Naming +`-analysis-report.md` + +### Report Structure + +#### Header +```markdown +## AI Analysis Report +**Analyzed by:** @ +**Date:** +**Issue:** # +**Model:** GitHub Copilot +--- +``` + +#### For Valid Issues + +```markdown +# Issue Analysis: + +## ✅ Issue Validation +**Status:** Valid and actionable + +## 📋 Issue Summary + + +## 📁 Affected Files +| File | Path | Lines | Section | +|------|------|-------|---------| +| Main article | [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) | 123-145 | "Section Heading" | +| Code sample | [`aspnetcore/path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/sample.cs#L45-L67) | 45-67 | `MethodName()` method | + +## 📝 Proposed Changes + +### Documentation Updates +**File:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123-L145) +**Location:** Lines 123-145 (after the paragraph containing "[specific anchor text]") +**Type:** [New paragraph / Note block / Code example / Replacement] + +**Current content (lines 123-125):** +```markdown +[Current text that will be replaced or followed] +``` + +**Proposed change:** +```markdown +[Proposed documentation text here] +``` + +### Code Sample Updates (if applicable) +**File:** [`sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) +**Lines:** 45-67 +**Change:** [Add/Modify/Remove] + +**Current code:** +```csharp +// Current code at specified lines +``` + +**Proposed code:** +```csharp +// Proposed code changes +``` + +## 🎯 Action Plan +1. **Edit file:** [`aspnetcore/path/to/file.md`](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md) + * Navigate to: [Line 123](https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/path/to/file.md#L123) + * Find section: "Exact Section Heading" + * After text: "last sentence before insertion point" + * Insert: [!NOTE] block with explanation + +2. **Update sample:** [`path/to/sample.cs`](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs) + * Navigate to: [Lines 45-67](https://github.com/dotnet/AspNetCore.Docs/blob/main/path/to/sample.cs#L45-L67) + * Modify method: `MethodName()` + * Change: Update to use new pattern + +## ⚠️ Considerations +* Verify change applies to .NET [version] +* Check if similar updates needed in related articles +* Consider adding cross-references to [related topic] + +## 🔗 References +* Published article: [URL] +* Related issue: #[number] +* Microsoft Learn docs: [relevant MS docs link] +``` + +#### For Invalid Issues + +```markdown +# Issue Analysis: + +## ❌ Issue Validation +**Status:** Not actionable as is +**Reason:** [Out of scope / Insufficient information / Product issue / Already addressed] + +## 📋 Explanation + + +## 💡 Recommendation +* [Close with explanation] +* [Redirect to appropriate repository] +* [Request additional information] +* [Convert to discussion] + +## 🔗 Alternative Resources +* [Link to relevant documentation] +* [Link to appropriate repository for product issues] +``` + +--- + +## Special Instructions + +### Line Number Guidelines +* **Always inspect the actual source file** to determine accurate line numbers. +* **Provide line ranges** rather than single lines when changes affect multiple lines. +* **Use GitHub's line highlighting** format in URLs (#L123 for single, #L123-L145 for range). +* **Quote the existing content** at those lines to confirm accuracy. +* **Consider context lines** - include a few lines before/after for clarity. +* **Update line numbers** if the file has changed since issue creation. + +### Content Block Usage +Only recommend using special blocks when truly appropriate, they should not be overused: +* `[!IMPORTANT]`: Security issues, breaking changes, data loss risks +* `[!WARNING]`: Common mistakes, deprecation notices +* `[!NOTE]`: Helpful clarifications, version-specific info +* `[!TIP]`: Best practices, productivity hints + +### Code Samples +* Use appropriate language identifier for syntax highlighting. +* Include necessary `using` statements or imports. +* Add comments for complex logic. +* Ensure samples are complete and runnable. + +### Scope Boundaries +**DO:** +* Focus on documentation clarity and accuracy. +* Address missing information. +* Fix technical inaccuracies. +* Improve code samples. + +**DON'T:** +* Attempt to fix product bugs through documentation. +* Make architectural recommendations. +* Add opinions or preferences. +* Modify unrelated sections. + +## Issue labels +* Upon completion of the report, set the `ai-reviewed-issue-reported-action-plan` label for the issue. + +### Common Issue Types +1. **Missing information**: Add clarifying content +2. **Outdated content**: Update to current version +3. **Broken samples**: Fix or replace code +4. **Unclear instructions**: Rewrite for clarity +5. **Missing prerequisites**: Add setup steps + +--- \ No newline at end of file diff --git a/.gitignore b/.gitignore index 50628e8f13d..de09a544e84 100644 --- a/.gitignore +++ b/.gitignore @@ -7,9 +7,10 @@ _themes.MSDN.Modern/ _themes.VS.Modern/ # Ignore local configuration changes -.github/ +#.github/ .openpublishing.buildcore.ps1 .vscode/ +.squad/ # Documentation build /docs/vcppdocs diff --git a/.openpublishing.build.ps1 b/.openpublishing.build.ps1 deleted file mode 100644 index aadef762022..00000000000 --- 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 0096e57d7ce..296bfe4f38b 100644 --- a/.openpublishing.publish.config.json +++ b/.openpublishing.publish.config.json @@ -25,14 +25,11 @@ } ], "notification_subscribers": [], - "sync_notification_subscribers": null, + "sync_notification_subscribers": [], "branches_to_filter": [], - "git_repository_url_open_to_public_contributors": "https://github.com/Microsoft/cpp-docs", + "git_repository_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 2491e656491..717a62c31c1 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -1,5 +1,2810 @@ { "redirections": [ + { + "source_path": "docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-overview.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-overview", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/graphics-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/graphics-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-accelerator-and-accelerator-view-objects", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-cpp-amp-in-windows-store-apps", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-lambdas-function-objects-and-restricted-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/using-tiles.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-tiles", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-debugging-a-cpp-amp-application", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-matrix-multiplication.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-matrix-multiplication", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-removed-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-removed-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/adopt-d3d-access-lock-t-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/completion-future-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/completion-future-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-enums", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-constants-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-constants-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-enums-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-enums-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-operators-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-operators-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/invalid-compute-domain-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/invalid-compute-domain-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/out-of-memory-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/out-of-memory-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/reference-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/reference-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/runtime-exception-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/runtime-exception-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/sampler-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/sampler-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/scoped-d3d-access-lock-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/scoped-d3d-access-lock-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-traits-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-traits-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tile-barrier-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tile-barrier-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uninitialized-object-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uninitialized-object-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unsupported-feature-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unsupported-feature-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/reference/writeonly-texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/writeonly-texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-160" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-overview.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-overview", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/graphics-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/graphics-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-accelerator-and-accelerator-view-objects", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-cpp-amp-in-windows-store-apps", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-lambdas-function-objects-and-restricted-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/using-tiles.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-tiles", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-debugging-a-cpp-amp-application", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-matrix-multiplication.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-matrix-multiplication", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-removed-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-removed-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/adopt-d3d-access-lock-t-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/completion-future-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/completion-future-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-enums", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-constants-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-constants-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-enums-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-enums-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-operators-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-operators-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/invalid-compute-domain-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/invalid-compute-domain-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/out-of-memory-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/out-of-memory-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/reference-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/reference-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/runtime-exception-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/runtime-exception-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/sampler-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/sampler-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/scoped-d3d-access-lock-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/scoped-d3d-access-lock-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-traits-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-traits-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tile-barrier-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tile-barrier-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uninitialized-object-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uninitialized-object-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unsupported-feature-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unsupported-feature-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/reference/writeonly-texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/writeonly-texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-150" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-overview.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-overview", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/graphics-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/graphics-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-accelerator-and-accelerator-view-objects", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-cpp-amp-in-windows-store-apps", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-lambdas-function-objects-and-restricted-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/using-tiles.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-tiles", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-debugging-a-cpp-amp-application", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-matrix-multiplication.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-matrix-multiplication", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-removed-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-removed-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/adopt-d3d-access-lock-t-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/completion-future-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/completion-future-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-enums", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-constants-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-constants-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-enums-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-enums-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-operators-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-operators-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/invalid-compute-domain-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/invalid-compute-domain-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/out-of-memory-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/out-of-memory-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/reference-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/reference-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/runtime-exception-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/runtime-exception-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/sampler-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/sampler-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/scoped-d3d-access-lock-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/scoped-d3d-access-lock-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-traits-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-traits-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tile-barrier-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tile-barrier-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uninitialized-object-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uninitialized-object-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unsupported-feature-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unsupported-feature-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/reference/writeonly-texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/writeonly-texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-140" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-overview.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-overview", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/graphics-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/graphics-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-accelerator-and-accelerator-view-objects", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-cpp-amp-in-windows-store-apps", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-lambdas-function-objects-and-restricted-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/using-tiles.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-tiles", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-debugging-a-cpp-amp-application", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-matrix-multiplication.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-matrix-multiplication", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-removed-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-removed-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/adopt-d3d-access-lock-t-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/completion-future-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/completion-future-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-enums", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-constants-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-constants-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-enums-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-enums-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-operators-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-operators-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/invalid-compute-domain-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/invalid-compute-domain-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/out-of-memory-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/out-of-memory-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/reference-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/reference-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/runtime-exception-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/runtime-exception-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/sampler-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/sampler-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/scoped-d3d-access-lock-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/scoped-d3d-access-lock-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-traits-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-traits-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tile-barrier-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tile-barrier-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uninitialized-object-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uninitialized-object-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unsupported-feature-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unsupported-feature-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/reference/writeonly-texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/writeonly-texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-180" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/cpp-amp-overview.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/cpp-amp-overview", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/graphics-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/graphics-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-accelerator-and-accelerator-view-objects", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-cpp-amp-in-windows-store-apps", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-lambdas-function-objects-and-restricted-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/using-tiles.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/using-tiles", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-debugging-a-cpp-amp-application", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/walkthrough-matrix-multiplication.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/walkthrough-matrix-multiplication", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/accelerator-view-removed-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/accelerator-view-removed-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/adopt-d3d-access-lock-t-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/array-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/array-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/completion-future-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/completion-future-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-fast-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-fast-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-direct3d-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-enums", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-graphics-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-graphics-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-constants-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-constants-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-enums-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-enums-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-functions-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-functions-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-namespace-operators-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-namespace-operators-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace-functions", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/concurrency-precise-math-namespace.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/concurrency-precise-math-namespace", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/double-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/double-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/float-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/float-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/int-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/int-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/invalid-compute-domain-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/invalid-compute-domain-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/norm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/norm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/out-of-memory-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/out-of-memory-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/reference-cpp-amp.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/reference-cpp-amp", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/runtime-exception-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/runtime-exception-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/sampler-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/sampler-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/scoped-d3d-access-lock-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/scoped-d3d-access-lock-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/short-vector-traits-structure.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/short-vector-traits-structure", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tile-barrier-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tile-barrier-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-extent-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-extent-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/tiled-index-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/tiled-index-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uint-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uint-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/uninitialized-object-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/uninitialized-object-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-2-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-2-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-3-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-3-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-4-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-4-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unorm-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unorm-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/unsupported-feature-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/unsupported-feature-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "source_path": "docs/parallel/amp/reference/writeonly-texture-view-class.md", + "redirect_url": "/previous-versions/cpp/parallel/amp/reference/writeonly-texture-view-class", + "redirect_document_id": false, + "monikers": [ + "msvc-170" + ] + }, + { + "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", @@ -16,7 +2821,7 @@ "redirect_document_id": true }, { - "source_path": "docs/supported-platforms-visual-cpp.md.md", + "source_path": "docs/supported-platforms-visual-cpp.md", "redirect_url": "/cpp/overview/supported-platforms-visual-cpp", "redirect_document_id": true }, @@ -7431,7 +10236,7 @@ "redirect_document_id": false }, { - "source_path": "docs/dotnet/how-to-enumerate-data-types-in-assemblies-using-reflection-cpp-cli.md.md", + "source_path": "docs/dotnet/how-to-enumerate-data-types-in-assemblies-using-reflection-cpp-cli.md", "redirect_url": "/cpp/dotnet/reflection-cpp-cli#enumerate", "redirect_document_id": false }, @@ -7745,6 +10550,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", @@ -13732,12 +16552,187 @@ }, { "source_path": "docs/c-runtime-library/operator-delete-crt.md", - "redirect_url": "docs/c-runtime-library/delete-operator-crt", + "redirect_url": "/cpp/c-runtime-library/delete-operator-crt", "redirect_document_id": false }, { "source_path": "docs/c-runtime-library/operator-new-crt.md", - "redirect_url": "docs/c-runtime-library/new-operator-crt", + "redirect_url": "/cpp/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 + }, + { + "source_path": "docs/standard-library/sample-container.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/sample-container-class.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/sample-container-classes.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/sample-container-member-functions.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/sample-container-members.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/sample-container-operators.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/sample-container-specialized-template-functions.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/sample-container-typedefs.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/operator-equality-sample-container.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/operator-greater-than-sample-container.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/operator-less-or-equal-sample-container.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/operator-less-than-sample-container.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/swap-sample-container.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/operator-greater-or-equal.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/operator-inequality.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-begin.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-clear.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-const-iterator.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-const-reference.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-const-reverse-iterator.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-difference-type.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-empty.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-end.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-erase.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-iterator.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-max-size.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-rbegin.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-reference.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-rend.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-reverse-iterator.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-size.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-size-type.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-swap.md", + "redirect_url": "/cpp/standard-library/stl-containers", + "redirect_document_id": false + }, + { + "source_path": "docs/standard-library/container-class-value-type.md", + "redirect_url": "/cpp/standard-library/stl-containers", "redirect_document_id": false } ] diff --git a/.vscode/settings.json b/.vscode/settings.json index 7eaad279a3d..60de5be0fe6 100644 --- a/.vscode/settings.json +++ b/.vscode/settings.json @@ -13,5 +13,8 @@ "Makefile", "VB.NET", "XML" - ] + ], + "python-envs.defaultEnvManager": "ms-python.python:conda", + "python-envs.defaultPackageManager": "ms-python.python:conda", + "python-envs.pythonProjects": [] } \ No newline at end of file diff --git a/.whatsnew.json b/.whatsnew.json index 6c3360626cc..a5807f933e9 100644 --- a/.whatsnew.json +++ b/.whatsnew.json @@ -1,5 +1,5 @@ { - "$schema": "https://whatsnewapi.azurewebsites.net/schema", + "$schema": "https://github.com/dotnet/docs-tools/blob/main/WhatsNew.Infrastructure/Configuration/reposettings.schema.json", "docSetProductName": "C++, C, and Assembler", "rootDirectory": "docs/", "docLinkSettings": { @@ -10,10 +10,18 @@ "minAdditionsToFile": 2, "pullRequestTitlesToIgnore": [ "^Confirm merge from FromPublicMasterBranch", - "^Repo sync for protected CLA branch" + "^Repo sync for protected CLA branch", + "^Repo sync for protected branch" ], "omitPullRequestTitles": false }, + "navigationOptions": { + "maximumNumberOfArticles": 2, + "tocParentNode": " ", + "repoTocFolder": " ", + "indexParentNode": " ", + "repoIndexFolder": " " + }, "areas": [ {"names": ["assembler", "intrinsics"], "heading": "C/C++ compiler intrinsics and assembly language"}, {"names": ["atl", "atl-mfc-shared", "mfc"], "heading": "Active Template Library (ATL), Microsoft Foundation Classes (MFC)"}, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a52d3bc599d..1fed536772c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,29 +1,26 @@ # Contributing -Thank you for your interest in contributing to the Visual C++ documentation! +Thank you for your interest in contributing to the Microsoft C++ documentation! -In this topic, you'll see the basic process for adding or updating content in the [Visual C++ documentation site](https://docs.microsoft.com/cpp). +In this topic, you'll see the basic process for adding or updating content in the [Microsoft C++ documentation site](https://learn.microsoft.com/cpp/). In this topic, we'll cover: - [Process for contributing](#process-for-contributing) - [DOs and DON'Ts](#dos-and-donts) -- [Building the docs](#building-the-docs) +- [Building the documentation](#building-the-documentation) - [Contributing to samples](#contributing-to-samples) - [Contributor license agreement](#contributor-license-agreement) ## Process for contributing -**Step 1:** Open an issue describing the article you wish to write and how it relates to existing content. -The content inside the **docs** folder is organized into sections that are organized by content area (e.g., debugger). Try to determine the correct folder for your new content. Get feedback on your proposal. - -You can skip this first step for small changes. +**Step 1:** The content inside the **docs** folder is organized into sections that are organized by content area (e.g., debugger). Try to determine the correct folder for your changes. **Step 2:** Fork the `MicrosoftDocs/cpp-docs` repository. -**Step 3:** Create a `branch` for your article. +**Step 3:** Create a `branch` for your changes. -**Step 4:** Write your article. +**Step 4:** Make your edits and commit. If it's a new topic, you can use this [template file](./styleguide/template.md) as your starting point. It contains the writing guidelines and also explains the metadata required for each article, such as author information. @@ -44,23 +41,21 @@ docs wstring-conversion.png ``` -**Step 5:** Submit a Pull Request (PR) from your branch to `MicrosoftDocs/cpp-docs/master`. - -If your PR is addressing an existing issue, add the `Fixes #Issue_Number` keyword to the commit message or PR description, so the issue can be automatically closed when the PR is merged. For more information, see [Closing issues via commit messages](https://help.github.com/articles/closing-issues-via-commit-messages/). +**Step 5:** Submit a Pull Request (PR) from your branch to `MicrosoftDocs/cpp-docs/main`. -The Visual Studio team will review your PR and let you know if the change looks good or if there are any other updates/changes necessary in order to approve it. +The Microsoft C++ docs team will review your PR and let you know if the change looks good or if there are any other updates/changes necessary in order to approve it. **Step 6:** Make any necessary updates to your branch as discussed with the team. -The maintainers will merge your PR into the master branch once feedback has been applied and your change looks good. +The maintainers will merge your PR into the main branch once feedback has been applied and your change looks good. -On a certain cadence, we push all commits from master branch into the live branch and then you'll be able to see your contribution live on [docs.microsoft.com](https://docs.microsoft.com/cpp/). +On a certain cadence, we push all commits from main branch into the live branch and then you'll be able to see your contribution on [Microsoft Learn](https://learn.microsoft.com/cpp/). ## DOs and DON'Ts -Below is a short list of guiding rules that you should keep in mind when you are contributing to the .NET documentation. +Below is a short list of guiding rules that you should keep in mind when you are contributing to the Microsoft C++ documentation. -- **DON'T** surprise us with big pull requests. Instead, file an issue and start a discussion so we can agree on a direction before you invest a large amount of time. +- **DON'T** surprise us with big pull requests. - **DO** read the [style guide](./styleguide/template.md) and [voice and tone](./styleguide/voice-tone.md) guidelines. - **DO** use the [template](./styleguide/template.md) file as the starting point of your work. - **DO** create a separate branch on your fork before working on the articles. @@ -68,13 +63,13 @@ Below is a short list of guiding rules that you should keep in mind when you are - **DO** blog and tweet (or whatever) about your contributions, frequently! > [!NOTE] -> You might notice that some of the topics are not currently following all the guidelines specified here and on the [style guide](./styleguide/template.md) as well. We're working towards achieving consistency throughout the site. Check the list of [open issues](https://github.com/MicrosoftDocs/cpp-docs/issues?q=is%3Aissue+is%3Aopen+label%3Aguidelines-adherence) we're currently tracking for that specific goal. +> You might notice that some of the topics are not currently following all the guidelines specified here and on the [style guide](./styleguide/template.md) as well. We're working towards achieving consistency throughout the site. -## Building the docs +## Building the documentation -The documentation is written in [GitHub Flavored Markdown](https://help.github.com/categories/writing-on-github/) and built using [DocFX](https://dotnet.github.io/docfx/) and other internal publishing/building tools. It is hosted at [docs.microsoft.com](https://docs.microsoft.com/). +The documentation is written in [GitHub-Flavored Markdown](https://help.github.com/categories/writing-on-github/) and built using [DocFX](https://dotnet.github.io/docfx/) and other internal publishing and build tools. It's published to [Microsoft Learn](https://learn.microsoft.com/). -If you want to build the docs locally, you need to install [DocFX](https://dotnet.github.io/docfx/); latest versions are the best. +If you want to build the documentation locally, you need to install the latest version of [DocFX](https://dotnet.github.io/docfx/). There are several ways to use DocFX, and most of them are covered in the [DocFX getting started guide](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html). The following instructions use the [command-line based](https://dotnet.github.io/docfx/tutorial/docfx_getting_started.html#2-use-docfx-as-a-command-line-tool) version of the tool. If you are comfortable with other ways listed on the link above, feel free to use those. @@ -94,6 +89,6 @@ For now, include required sample code as inline code blocks in your article. The ## Contributor license agreement -You must sign the [Contribution License Agreement (CLA)](LICENSE) before your PR is merged. This is a one-time requirement for projects in docs.microsoft.com. You can read more about [Contribution License Agreements (CLA)](https://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. +You must sign the [Contribution License Agreement (CLA)](LICENSE) before your PR is merged. This is a one-time requirement for projects on Microsoft Learn. You can read more about [Contribution License Agreements (CLA)](https://en.wikipedia.org/wiki/Contributor_License_Agreement) on Wikipedia. You don't have to sign the agreement up-front. You can clone, fork, and submit your PR as usual. When your PR is created, it is classified by a CLA bot. If the change is trivial (for example, you fixed a typo), then the PR is labeled with CLA-not-required. Otherwise, it's classified as CLA-required. Once you signed the CLA, the current and all future pull requests are labeled as CLA-signed. diff --git a/README.md b/README.md index a02389709b3..816a2293bf9 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,14 @@ -# Visual Studio documentation for Microsoft C++ +# Microsoft C++, C, and Assembler documentation -Welcome! This repository contains source files for the work-in-progress Microsoft C++ (MSVC or Visual C++) technical documentation. The articles are published on the [C++ in Visual Studio documentation site](https://docs.microsoft.com/cpp). +Welcome! This repository contains source files for the technical documentation published on [https://learn.microsoft.com/cpp](https://learn.microsoft.com/cpp). -The documentation for Visual Basic and Visual C# are located in a separate repository at [https://github.com/dotnet/core-docs](https://github.com/dotnet/core-docs), and the Visual Studio documentation is located in the repository located at [https://github.com/Microsoft/visualstudio-docs](https://github.com/Microsoft/visualstudio-docs). +The documentation for [.NET](https://github.com/dotnet/docs) and [Visual Studio](https://github.com/MicrosoftDocs/visualstudio-docs) are located in separate repositories. ## Contributing to the documentation -We welcome your contributions to help us improve the MSVC docs. For a comprehensive guide to contributing to docs.microsoft.com, see the [Microsoft Docs contributor guide overview](https://docs.microsoft.com/contribute). For details on how to make a contribution to the MSVC documentation, see the [Contributing guide](CONTRIBUTING.md). +We welcome your contributions to help us improve the MSVC docs. For a comprehensive guide to contributing, see the [Microsoft Docs contributor guide](https://learn.microsoft.com/contribute). For details on how to make a contribution to the MSVC documentation, see our [Contributing guidance](CONTRIBUTING.md). -Several feature areas of MSVC have their own folders in this repository, such as `standard-library` for articles on the C++ Standard Library, `ide` for C++-specific articles on the Visual Studio interactive development environment (IDE), and so forth. The `/media` subfolder in each folder contains art files for the articles. The [Contributing guide](CONTRIBUTING.md) has more information. +Several feature areas of MSVC have their own folders in this repository, such as `standard-library` for articles on the C++ Standard Library, `ide` for C++-specific articles on the Visual Studio integrated development environment (IDE), and so forth. The `/media` subfolder in each folder contains art files for the articles. The [Contributing guide](CONTRIBUTING.md) has more information. ## Microsoft Open Source Code of Conduct diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000000..675ad2a2156 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,41 @@ + + +## Security + +Microsoft takes the security of our software products and services seriously, which includes all source code repositories managed through our GitHub organizations, such as [Microsoft](https://github.com/microsoft), [Azure](https://github.com/Azure), [DotNet](https://github.com/dotnet), [AspNet](https://github.com/aspnet), and [our GitHub organizations](https://opensource.microsoft.com/). + +If you believe you have found a security vulnerability in any Microsoft-owned repository that meets [Microsoft's definition of a security vulnerability](https://aka.ms/opensource/security/definition), please report it to us as described below. + +## Reporting Security Issues + +**Please do not report security vulnerabilities through public GitHub issues.** + +Instead, please report them to the Microsoft Security Response Center (MSRC) at [https://msrc.microsoft.com/create-report](https://aka.ms/opensource/security/create-report). + +If you prefer to submit without logging in, send email to [secure@microsoft.com](mailto:secure@microsoft.com). If possible, encrypt your message with our PGP key; please download it from the [Microsoft Security Response Center PGP Key page](https://aka.ms/opensource/security/pgpkey). + +You should receive a response within 24 hours. If for some reason you do not, please follow up via email to ensure we received your original message. Additional information can be found at [microsoft.com/msrc](https://aka.ms/opensource/security/msrc). + +Please include the requested information listed below (as much as you can provide) to help us better understand the nature and scope of the possible issue: + + * Type of issue (e.g. buffer overflow, SQL injection, cross-site scripting, etc.) + * Full paths of source file(s) related to the manifestation of the issue + * The location of the affected source code (tag/branch/commit or direct URL) + * Any special configuration required to reproduce the issue + * Step-by-step instructions to reproduce the issue + * Proof-of-concept or exploit code (if possible) + * Impact of the issue, including how an attacker might exploit the issue + +This information will help us triage your report more quickly. + +If you are reporting for a bug bounty, more complete reports can contribute to a higher bounty award. Please visit our [Microsoft Bug Bounty Program](https://aka.ms/opensource/security/bounty) page for more details about our active programs. + +## Preferred Languages + +We prefer all communications to be in English. + +## Policy + +Microsoft follows the principle of [Coordinated Vulnerability Disclosure](https://aka.ms/opensource/security/cvd). + + diff --git a/docs/_breadcrumb/toc.yml b/docs/_breadcrumb/toc.yml index efaed4b8a9e..363d1dad6bd 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 daed637d1e8..a686553e861 100644 --- a/docs/assembler/arm/arm-assembler-command-line-reference.md +++ b/docs/assembler/arm/arm-assembler-command-line-reference.md @@ -2,11 +2,10 @@ 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 -The Microsoft ARM assemblers, **armasm** and **armasm64**, support several command-line options. By default, **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The **armasm64** assembler creates COFF object code for ARM64 and ARM64EC targets. The linker can link COFF code objects produced by both the ARM assembler and the C/C++ compiler. It can link either together with object libraries created by the librarian. +The Microsoft ARM assemblers, **armasm** and **armasm64**, support several command-line options. By default, **armasm** assembles ARMv7 Thumb assembly language into the Microsoft implementation of the Common Object File Format (COFF). The **armasm64** assembler creates COFF object code for ARM64 and ARM64EC targets. The linker can link COFF code objects produced by both the ARM assembler and the MSVC compiler. It can link either together with object libraries created by the librarian. ## Syntax @@ -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/accessing-c-or-cpp-data-in-asm-blocks.md b/docs/assembler/inline/accessing-c-or-cpp-data-in-asm-blocks.md index c2018570a2a..8dab8e0883c 100644 --- a/docs/assembler/inline/accessing-c-or-cpp-data-in-asm-blocks.md +++ b/docs/assembler/inline/accessing-c-or-cpp-data-in-asm-blocks.md @@ -4,6 +4,7 @@ title: "Accessing C or C++ Data in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["data members [C++], in __asm blocks", "data access [C++], in __asm blocks", "__asm keyword [C++], data members", "structure types in __asm blocks"] ms.assetid: e99f5a28-0381-4090-8ece-6af8f2436a49 +ms.topic: concept-article --- # Accessing C or C++ Data in __asm Blocks diff --git a/docs/assembler/inline/asm.md b/docs/assembler/inline/asm.md index edc958759c1..78787c9492b 100644 --- a/docs/assembler/inline/asm.md +++ b/docs/assembler/inline/asm.md @@ -1,33 +1,33 @@ --- -description: "Learn more about: `__asm`" title: "__asm" -ms.date: "10/09/2018" +description: "Learn more about: `__asm`" +ms.date: 10/09/2018 +ms.topic: reference f1_keywords: ["__asm", "_asm", "__asm_cpp"] helpviewer_keywords: ["__asm keyword [C++], vs. asm blocks", "__asm keyword [C++]"] -ms.assetid: 77ff3bc9-a492-4b5e-85e1-fa4e414e79cd --- # `__asm` **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`**. +> MSVC 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 -If used without braces, the **`__asm`** keyword means that the rest of the line is an assembly-language statement. If used with braces, it means that each line between the braces is an assembly-language statement. For compatibility with previous versions, **`_asm`** is a synonym for **`__asm`**. +If used without braces, the **`__asm`** keyword means that the rest of the line is an assembly-language statement. If used with braces, it means that each line between the braces is an assembly-language statement. For compatibility with previous versions, **`_asm`** is a synonym for **`__asm`** unless compiler option [`/Za` (Disable language extensions)](../../build/reference/za-ze-disable-language-extensions.md) is specified. Since the **`__asm`** keyword is a statement separator, you can put assembly instructions on the same line. @@ -37,12 +37,10 @@ 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). -For compatibility with previous versions, **`_asm`** is a synonym for **`__asm`** unless compiler option [/Za \(Disable language extensions)](../../build/reference/za-ze-disable-language-extensions.md) is specified. - ## Example The following code fragment is a simple **`__asm`** block enclosed in braces: @@ -69,9 +67,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/calling-c-functions-in-inline-assembly.md b/docs/assembler/inline/calling-c-functions-in-inline-assembly.md index 151a29d5a53..74bf5c40de2 100644 --- a/docs/assembler/inline/calling-c-functions-in-inline-assembly.md +++ b/docs/assembler/inline/calling-c-functions-in-inline-assembly.md @@ -4,6 +4,7 @@ title: "Calling C Functions in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["function calls, C functions", "function calls, in inline assembly", "functions [C], calling in inline assembly", "Visual C, functions", "inline assembly, calling functions", "__asm keyword [C++], calling functions"] ms.assetid: f8a8d568-d175-4e23-9b24-36ef60a4cab3 +ms.topic: concept-article --- # Calling C Functions in Inline Assembly diff --git a/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md b/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md index 4189da24ae8..11c2763e438 100644 --- a/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md +++ b/docs/assembler/inline/calling-cpp-functions-in-inline-assembly.md @@ -4,6 +4,7 @@ title: "Calling C++ Functions in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["functions [C++], calling in inline assembly", "function calls, C++ functions", "function calls, in inline assembly", "Visual C++, functions", "inline assembly, calling functions", "__asm keyword [C++], calling functions"] ms.assetid: 1f0d1eb3-54cf-45d5-838d-958188616b38 +ms.topic: concept-article --- # Calling C++ Functions in Inline Assembly diff --git a/docs/assembler/inline/debugging-and-listings-for-inline-assembly.md b/docs/assembler/inline/debugging-and-listings-for-inline-assembly.md index 5ad6409390b..dbe6f30b37a 100644 --- a/docs/assembler/inline/debugging-and-listings-for-inline-assembly.md +++ b/docs/assembler/inline/debugging-and-listings-for-inline-assembly.md @@ -4,6 +4,7 @@ title: "Debugging and Listings for Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["source level debugger", "__asm keyword [C++], debugging", "inline assembly, listings", "bugs, __asm blocks", "debugging [C++], inline assembly code", "inline assembly, debugging"] ms.assetid: 69266930-6f9a-433d-b704-f4f44e7b2583 +ms.topic: concept-article --- # Debugging and Listings for Inline Assembly 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 0a5d4df1279..ebea4aa8da3 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,9 @@ --- -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 +ms.topic: concept-article --- # Defining __asm Blocks as C Macros @@ -15,7 +15,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 +39,7 @@ The third and fourth **`__asm`** keywords are needed as statement separators. Th The braces are essential as well. If you omit them, the compiler can be confused by C or C++ statements on the same line to the right of the macro invocation. Without the closing brace, the compiler cannot tell where assembly code stops, and it sees C or C++ statements after the **`__asm`** block as assembly instructions. -Assembly-style comments that start with a semicolon (**;**) continue to the end of the line. This causes problems in macros because the compiler ignores everything after the comment, all the way to the end of the logical line. The same is true of single-line C or C++ comments ( `// comment`). To prevent errors, use old-style C comments ( `/* comment */`) in **`__asm`** blocks defined as macros. +Assembly-style comments that start with a semicolon (**;**) continue to the end of the line. This causes problems in macros because the compiler ignores everything after the comment, all the way to the end of the logical line. The same is true of single-line C or C++ comments (`// comment`). To prevent errors, use old-style C comments (`/* comment */`) in **`__asm`** blocks defined as macros. An **`__asm`** block written as a C macro can take arguments. Unlike an ordinary C macro, however, an **`__asm`** macro cannot return a value. So you cannot use such macros in C or C++ expressions. diff --git a/docs/assembler/inline/emit-pseudoinstruction.md b/docs/assembler/inline/emit-pseudoinstruction.md index 201c775fd0e..b736701ca0b 100644 --- a/docs/assembler/inline/emit-pseudoinstruction.md +++ b/docs/assembler/inline/emit-pseudoinstruction.md @@ -5,6 +5,7 @@ ms.date: "08/30/2018" f1_keywords: ["_emit"] helpviewer_keywords: ["byte defining (inline assembly)", "_emit pseudoinstruction"] ms.assetid: 004c48f3-364c-4e82-9a51-e326f9cc7b2b +ms.topic: reference --- # _emit Pseudoinstruction diff --git a/docs/assembler/inline/even-and-align-directives.md b/docs/assembler/inline/even-and-align-directives.md index 648f5367903..d98adc4b440 100644 --- a/docs/assembler/inline/even-and-align-directives.md +++ b/docs/assembler/inline/even-and-align-directives.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: EVEN and ALIGN Directives" title: "EVEN and ALIGN Directives" -ms.date: "08/30/2018" +description: "Learn more about: EVEN and ALIGN Directives" +ms.date: 08/30/2018 helpviewer_keywords: ["EVEN directive", "directives, MASM", "MASM (Microsoft Macro Assembler), directives", "NOP (no operation instruction)", "ALIGN directive"] -ms.assetid: 7357ab2d-4a5c-43ca-accb-a5f21cdfcde5 --- -# EVEN and ALIGN Directives +# `EVEN` and `ALIGN` Directives **Microsoft Specific** -Although the inline assembler doesn't support most MASM directives, it does support `EVEN` and **ALIGN**. These directives put **NOP** (no operation) instructions in the assembly code as needed to align labels to specific boundaries. This makes instruction-fetch operations more efficient for some processors. +Although the inline assembler doesn't support most MASM directives, it does support [`EVEN`](../masm/even.md) and [`ALIGN`](../masm/align-masm.md). These directives put `NOP` (no operation) instructions in the assembly code as needed to align labels to specific boundaries. This makes instruction-fetch operations more efficient for some processors. **END Microsoft Specific** ## See also -[Using Assembly Language in __asm Blocks](../../assembler/inline/using-assembly-language-in-asm-blocks.md)
+[Using Assembly Language in `__asm` Blocks](using-assembly-language-in-asm-blocks.md) diff --git a/docs/assembler/inline/inline-assembler-overview.md b/docs/assembler/inline/inline-assembler-overview.md index 25141761486..3b97cd70431 100644 --- a/docs/assembler/inline/inline-assembler-overview.md +++ b/docs/assembler/inline/inline-assembler-overview.md @@ -4,6 +4,7 @@ title: "Inline Assembler Overview" ms.date: "08/30/2018" helpviewer_keywords: ["inline assembler", "__asm keyword [C++], invoking inline assembler", "invoking inline assembler", "inline assembly, inline assembler"] ms.assetid: d990331a-0e33-4760-8d7a-b720b0288335 +ms.topic: concept-article --- # Inline Assembler Overview diff --git a/docs/assembler/inline/instruction-set-for-inline-assembly.md b/docs/assembler/inline/instruction-set-for-inline-assembly.md index 13b356b5264..bbcdcbd635e 100644 --- a/docs/assembler/inline/instruction-set-for-inline-assembly.md +++ b/docs/assembler/inline/instruction-set-for-inline-assembly.md @@ -10,7 +10,7 @@ ms.assetid: a45b5b22-9b5f-4545-81ec-70eb8ea2ef9b **Microsoft Specific** -The Microsoft C++ compiler supports all opcodes through the Pentium 4 and AMD Athlon. Additional instructions supported by the target processor can be created with the [_emit Pseudoinstruction](../../assembler/inline/emit-pseudoinstruction.md). +The MSVC compiler supports all opcodes through the Pentium 4 and AMD Athlon. Additional instructions supported by the target processor can be created with the [_emit Pseudoinstruction](../../assembler/inline/emit-pseudoinstruction.md). **END Microsoft Specific** diff --git a/docs/assembler/inline/intel-s-mmx-instruction-set.md b/docs/assembler/inline/intel-s-mmx-instruction-set.md index eb492df28df..c66d08a1255 100644 --- a/docs/assembler/inline/intel-s-mmx-instruction-set.md +++ b/docs/assembler/inline/intel-s-mmx-instruction-set.md @@ -10,7 +10,7 @@ ms.assetid: 705deb2d-c3fd-4696-9e22-8bcf25866daf **Microsoft Specific** -The Microsoft C++ compiler allows you to use Intel's MMX (multimedia extension) instruction set in the inline assembler. The MMX instructions are also supported by the debugger disassembly. The compiler generates a warning message if the function contains MMX instructions but does not contain an EMMS instruction to empty the multimedia state. For more information, see the Intel Web site. +The MSVC compiler allows you to use Intel's MMX (multimedia extension) instruction set in the inline assembler. The MMX instructions are also supported by the debugger disassembly. The compiler generates a warning message if the function contains MMX instructions but does not contain an EMMS instruction to empty the multimedia state. For more information, see the Intel Web site. **END Microsoft Specific** diff --git a/docs/assembler/inline/jumping-to-labels-in-inline-assembly.md b/docs/assembler/inline/jumping-to-labels-in-inline-assembly.md index 0146414b364..69529719664 100644 --- a/docs/assembler/inline/jumping-to-labels-in-inline-assembly.md +++ b/docs/assembler/inline/jumping-to-labels-in-inline-assembly.md @@ -4,6 +4,7 @@ title: "Jumping to Labels in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["inline assembly, jumping to labels", "labels, in inline assembly", "__asm keyword [C++], labels", "case sensitivity, labels in inline assembly", "labels, in __asm blocks", "jumping to labels in inline assembly"] ms.assetid: 36c18b97-8981-4631-9dfd-af6c14a04297 +ms.topic: concept-article --- # Jumping to Labels in Inline Assembly diff --git a/docs/assembler/inline/optimizing-inline-assembly.md b/docs/assembler/inline/optimizing-inline-assembly.md index 726c242a525..7330cf7156e 100644 --- a/docs/assembler/inline/optimizing-inline-assembly.md +++ b/docs/assembler/inline/optimizing-inline-assembly.md @@ -4,6 +4,7 @@ title: "Optimizing Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["storage, optimizing in inline assembly", "optimization, inline assembly", "inline assembly, optimizing", "optimizing performance, inline assembly", "__asm keyword [C++], optimizing"] ms.assetid: 52a7ec83-9782-4d96-94c1-53bb2ac9e8c8 +ms.topic: concept-article --- # Optimizing Inline Assembly diff --git a/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md b/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md index 30dae26e22c..b488b9fc601 100644 --- a/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md +++ b/docs/assembler/inline/using-and-preserving-registers-in-inline-assembly.md @@ -4,6 +4,7 @@ title: "Using and Preserving Registers in Inline Assembly" ms.date: "08/30/2018" helpviewer_keywords: ["__asm keyword [C++], register values", "inline assembly, registers", "registers, inline assembly", "preserving registers"] ms.assetid: dbcd7360-6f3e-4b22-9ee2-9f65ca6f2543 +ms.topic: concept-article --- # Using and Preserving Registers in Inline Assembly diff --git a/docs/assembler/inline/using-assembly-language-in-asm-blocks.md b/docs/assembler/inline/using-assembly-language-in-asm-blocks.md index 2e80f379517..c2a33f53b50 100644 --- a/docs/assembler/inline/using-assembly-language-in-asm-blocks.md +++ b/docs/assembler/inline/using-assembly-language-in-asm-blocks.md @@ -4,6 +4,7 @@ title: "Using Assembly Language in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["assembly language [C++], features", "assembly language [C++]", "__asm keyword [C++], assembly language in"] ms.assetid: ad699356-1d16-4984-871f-c5fd7797c1fb +ms.topic: concept-article --- # Using Assembly Language in __asm Blocks diff --git a/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md b/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md index 60fbff35486..0a56b28c8fc 100644 --- a/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md +++ b/docs/assembler/inline/using-c-or-cpp-in-asm-blocks.md @@ -4,6 +4,7 @@ title: "Using C or C++ in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["inline assembly, mixing instructions with C/C++ statements", "symbols, in __asm blocks", "macros, __asm blocks", "preprocessor directives, used in __asm blocks", "type names, used in __asm blocks", "preprocessor directives", "preprocessor, directives", "constants, in __asm blocks", "comments, in __asm blocks", "typedef names, used in __asm blocks", "__asm keyword [C++], C/C++ elements in"] ms.assetid: ae8b2b52-6b75-42e3-ac0c-ad02d922ed97 +ms.topic: concept-article --- # Using C or C++ in __asm Blocks diff --git a/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md b/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md index 7b4602352c2..8dc38e5868e 100644 --- a/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md +++ b/docs/assembler/inline/using-c-or-cpp-symbols-in-asm-blocks.md @@ -4,6 +4,7 @@ title: "Using C or C++ Symbols in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["__asm keyword [C++], syntax", "symbols, in __asm blocks", "Visual C, symbols in __asm blocks", "__asm keyword [C++], C/C++ elements in", "Visual C++, in __asm blocks"] ms.assetid: 0758ffdc-dfe9-41c8-a5e1-fd395bcac328 +ms.topic: concept-article --- # Using C or C++ Symbols in __asm Blocks diff --git a/docs/assembler/inline/using-operators-in-asm-blocks.md b/docs/assembler/inline/using-operators-in-asm-blocks.md index dbda9a8fd39..b629032f997 100644 --- a/docs/assembler/inline/using-operators-in-asm-blocks.md +++ b/docs/assembler/inline/using-operators-in-asm-blocks.md @@ -4,6 +4,7 @@ title: "Using Operators in __asm Blocks" ms.date: "08/30/2018" helpviewer_keywords: ["brackets [ ]", "brackets [ ], __asm blocks", "__asm keyword [C++], operators", "square brackets [ ], __asm blocks", "operators [C++], using in __asm blocks", "square brackets [ ]"] ms.assetid: a26ccfd4-40ae-4a61-952f-c417982aa8dd +ms.topic: concept-article --- # Using Operators in __asm Blocks diff --git a/docs/assembler/inline/writing-functions-with-inline-assembly.md b/docs/assembler/inline/writing-functions-with-inline-assembly.md index 65e852819fc..d1082cff37d 100644 --- a/docs/assembler/inline/writing-functions-with-inline-assembly.md +++ b/docs/assembler/inline/writing-functions-with-inline-assembly.md @@ -4,6 +4,7 @@ title: "Writing functions with inline assembly" ms.date: 02/11/2022 helpviewer_keywords: ["functions [C++], inline assembly", "inline assembly [C++], writing functions", "assembler [C++], writing functions", "__asm keyword [C++], in functions"] ms.assetid: b5df8a04-fdc7-4622-8c9e-e4b618927497 +ms.topic: concept-article --- # Writing functions with inline assembly diff --git a/docs/assembler/masm/at-unwindversion.md b/docs/assembler/masm/at-unwindversion.md new file mode 100644 index 00000000000..388cfd802e7 --- /dev/null +++ b/docs/assembler/masm/at-unwindversion.md @@ -0,0 +1,60 @@ +--- +description: "Learn more about: @UnwindVersion" +title: "@UnwindVersion" +ms.date: 05/07/2026 +f1_keywords: ["@UnwindVersion"] +helpviewer_keywords: ["@UnwindVersion symbol"] +ai-usage: ai-assisted +--- +# \@UnwindVersion + +A predefined macro that returns the unwind version the `.asm` file is being assembled with. + +## Syntax + +> **\@UnwindVersion** + +## Remarks + +> [!IMPORTANT] +> This symbol is experimental and is subject to change. Enable Unwind Version 3 with `ml64.exe /unwindv3`. + +**\@UnwindVersion** is set to the unwind version used by the assembler. When `/unwindv3` is passed to `ml64.exe`, **\@UnwindVersion** is set to `3`; otherwise it's set to `1`. + +Use this macro with conditional assembly directives such as `IF` to assemble different code paths depending on the unwind version. + +This example is intended to be assembled only as it doesn't define an application entry point: + +## Example for unwindv3 + +```asm +; ml64 /c /unwindv3 ex1.asm +.code + +IF @UnwindVersion EQ 3 + +foo PROC FRAME + .pushreg r12 + push r12 + + .endprolog + + mov rax, 0 + + .beginepilog + .popreg r12 + pop r12 + .endepilog + ret +foo ENDP +ELSE + .ERR <@UnwindVersion should be 3> +ENDIF + +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/directives-reference.md b/docs/assembler/masm/directives-reference.md index c9f7208c7d7..97de3fcad7a 100644 --- a/docs/assembler/masm/directives-reference.md +++ b/docs/assembler/masm/directives-reference.md @@ -4,7 +4,7 @@ title: "Directives Reference" ms.date: 07/15/2020 f1_keywords: ["Directives Reference"] helpviewer_keywords: ["MASM (Microsoft Macro Assembler), directives reference"] -ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 +ai-usage: ai-assisted --- # Directives Reference @@ -27,6 +27,49 @@ ms.assetid: da6efcd1-18f7-41de-81cd-a002a02f9a22 :::column-end::: :::row-end::: +## x64 Unwind Version 3 (experimental) + +The following directives are used with `ml64.exe` when the `/unwindv3` option is enabled. Unwind Version 3 is experimental and is subject to change. + +**Prologue directives** + +:::row::: + :::column span=""::: + [`.ALLOCSTACK`](dot-allocstack.md)\ + [`.ENDPROLOG`](dot-endprolog.md)\ + [`.PUSH2REG`](dot-push2reg.md) + :::column-end::: + :::column span=""::: + [`.PUSHFRAME`](dot-pushframe.md)\ + [`.PUSHREG`](dot-pushreg.md)\ + [`.SAVEREG`](dot-savereg.md) + :::column-end::: + :::column span=""::: + [`.SAVEXMM128`](dot-savexmm128.md)\ + [`.SETFRAME`](dot-setframe.md) + :::column-end::: +:::row-end::: + +**Epilogue directives** + +:::row::: + :::column span=""::: + [`.BEGINEPILOG`](dot-beginepilog.md)\ + [`.ENDEPILOG`](dot-endepilog.md)\ + [`.FREESTACK`](dot-freestack.md) + :::column-end::: + :::column span=""::: + [`.POP2REG`](dot-pop2reg.md)\ + [`.POPFRAME`](dot-popframe.md)\ + [`.POPREG`](dot-popreg.md)\ + [`.RESTOREREG`](dot-restorereg.md) + :::column-end::: + :::column span=""::: + [`.RESTOREXMM128`](dot-restorexmm128.md)\ + [`.UNSETFRAME`](dot-unsetframe.md) + :::column-end::: +:::row-end::: + ## Code Labels :::row::: diff --git a/docs/assembler/masm/dot-allocstack.md b/docs/assembler/masm/dot-allocstack.md index 13c5e6e1146..6d0881627bd 100644 --- a/docs/assembler/masm/dot-allocstack.md +++ b/docs/assembler/masm/dot-allocstack.md @@ -1,39 +1,41 @@ --- description: "Learn more about: .ALLOCSTACK" title: ".ALLOCSTACK" -ms.date: "12/17/2019" +ms.date: 05/11/2026 f1_keywords: [".ALLOCSTACK"] helpviewer_keywords: [".ALLOCSTACK directive"] -ms.assetid: 9801594b-7ac2-4df2-a49d-07d9dd9af99e +ai-usage: ai-assisted --- # .ALLOCSTACK -Generates a **UWOP_ALLOC_SMALL** or a **UWOP_ALLOC_LARGE** with the specified size for the current offset in the prologue. +`.ALLOCSTACK` generates a **UWOP_ALLOC_SMALL** or a **UWOP_ALLOC_LARGE** with the specified size for the current offset in the prologue. ## Syntax -> **.ALLOCSTACK** *size* +> `.ALLOCSTACK` *size* ## Remarks -MASM will choose the most efficient encoding for a given size. +Microsoft Assembler (MASM) chooses the most efficient encoding for a given size. -**.ALLOCSTACK** allows ml64.exe users to specify how a frame function unwinds and is only allowed within the prologue, which extends from the [PROC](proc.md) FRAME declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives do not generate code; they only generate `.xdata` and `.pdata`. **.ALLOCSTACK** should be preceded by instructions that actually implement the actions to be unwound. It is a good practice to wrap both the unwind directives and the code they are meant to unwind in a macro to ensure agreement. +`.ALLOCSTACK` allows `ml64.exe` users to specify how a frame function unwinds and is only allowed within the prologue, which extends from the [PROC](proc.md) `FRAME` declaration to the [.ENDPROLOG](dot-endprolog.md) directive. +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- Precede `.ALLOCSTACK` with the instructions that actually implement the actions to be unwound. Wrap both the unwind directives and the code they're meant to unwind in a macro to ensure agreement. The *size* operand must be a multiple of 8. -For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md). +The epilogue counterpart is [.FREESTACK](dot-freestack.md). -## Sample +## Example: specify an unwind version 3 unwind/exception handler The following sample shows how to specify an unwind/exception handler: ```asm -; ml64 ex3.asm /link /entry:Example1 /SUBSYSTEM:Console +; ml64 ex3.asm /link /entry:Example3 /SUBSYSTEM:Console text SEGMENT PUBLIC Example3 PUBLIC Example3_UW -Example3_UW PROC NEAR +Example3_UW PROC ; exception/unwind handler body ret 0 @@ -56,7 +58,61 @@ text ENDS END ``` +## Unwind Version 3 behavior + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. Enable it by using `ml64.exe /unwindv3`. + +`.ALLOCSTACK` generates a `WOD_ALLOC_SMALL`, `WOD_ALLOC_LARGE`, or `WOD_ALLOC_HUGE` Unwind Version 3 unwind code entry with the specified size for the current offset in the prolog. + +`.ALLOCSTACK` must appear **before** the `sub rsp, N` instruction it describes. This requirement is the opposite of Version 1, where the directive follows the instruction. + +MASM emits one of three unwind codes depending on the allocation size: + +| Unwind code | Condition | +|---|---| +| `WOD_ALLOC_SMALL` | *size* ≤ 128 bytes | +| `WOD_ALLOC_LARGE` | *size* ≤ 32 KB | +| `WOD_ALLOC_HUGE` | *size* > 32 KB | + +Version 1 generates only `UWOP_ALLOC_SMALL` or `UWOP_ALLOC_LARGE`. Version 3 adds a third variant, `WOD_ALLOC_HUGE`, for allocations larger than 32 KB. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +### Example for unwindv3 + +```asm +; ml64 ex3.asm /unwindv3 /link /entry:Example3 /SUBSYSTEM:Console +text SEGMENT +PUBLIC Example3 +PUBLIC Example3_UW +Example3_UW PROC + ; exception/unwind handler body + + ret 0 + +Example3_UW ENDP + +Example3 PROC FRAME : Example3_UW + +.allocstack 16 + sub rsp, 16 + +.endprolog + + ; function body + add rsp, 16 + ret 0 + +Example3 ENDP +text ENDS +END +``` + ## See also +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ [Directives Reference](directives-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF Grammar](masm-bnf-grammar.md)\ +[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md) \ No newline at end of file diff --git a/docs/assembler/masm/dot-beginepilog.md b/docs/assembler/masm/dot-beginepilog.md new file mode 100644 index 00000000000..9f05bcdaf1d --- /dev/null +++ b/docs/assembler/masm/dot-beginepilog.md @@ -0,0 +1,59 @@ +--- +description: "Learn more about: .BEGINEPILOG" +title: ".BEGINEPILOG" +ms.date: 05/04/2026 +ai-usage: ai-assisted +f1_keywords: [".BEGINEPILOG"] +helpviewer_keywords: [".BEGINEPILOG directive"] +--- +# .BEGINEPILOG + +Marks the start of an epilogue unwind region. This directive doesn't emit an Unwind Operation Descriptors (WOD) code. + +## Syntax + +> `.BEGINEPILOG` + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. +> Enable Unwind Version 3 by using `ml64.exe /unwindv3`. + +`.BEGINEPILOG` is only valid in Unwind Version 3. + +- It marks the start of an epilogue region where epilogue unwind operations are recorded. Pair `.BEGINEPILOG` with a closing [.ENDEPILOG](dot-endepilog.md) or no epilog unwind codes are emitted. +- In Unwind Version 3, epilog directives are mandatory for epilog unwind code generation. +- Epilogues must contain at least one directive. +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .allocstack 16 + sub rsp, 16 +.endprolog + ; function body + .beginepilog + .freestack 16 + add rsp, 16 + .endepilog + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.ENDEPILOG](dot-endepilog.md)\ +[.ENDPROLOG](dot-endprolog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-code.md b/docs/assembler/masm/dot-code.md index c8167f89f3b..9bf447e91b3 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 cf080270da7..c36eb3fee16 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-endepilog.md b/docs/assembler/masm/dot-endepilog.md new file mode 100644 index 00000000000..af9383ae19e --- /dev/null +++ b/docs/assembler/masm/dot-endepilog.md @@ -0,0 +1,60 @@ +--- +description: "Learn more about: .ENDEPILOG" +title: ".ENDEPILOG" +ms.date: "04/29/2026" +ai-usage: ai-assisted +f1_keywords: [".ENDEPILOG"] +helpviewer_keywords: [".ENDEPILOG directive"] +--- +# .ENDEPILOG + +Marks the end of an epilogue unwind region. This directive doesn't emit a Windows unwind data (WOD) unwind code. + +## Syntax + +> **.ENDEPILOG** + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. +> Enable Unwind Version 3 by using `ml64.exe /unwindv3`. + +**.ENDEPILOG** is only valid in Unwind Version 3. + +- It marks the end of an epilogue region started by [.BEGINEPILOG](dot-beginepilog.md). +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- Epilogues must contain at least one directive. +- Epilogue directives are mandatory for epilogue unwind code generation. No epilogue unwind codes are emitted without a `.BEGINEPILOG`/`.ENDEPILOG` pair. +- It's an error to use epilogue directives outside of the region between [.BEGINEPILOG](dot-beginepilog.md) and **.ENDEPILOG**. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .allocstack 16 + sub rsp, 16 +.endprolog + ; function body + .beginepilog + .freestack 16 + add rsp, 16 + .endepilog + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[.ENDPROLOG](dot-endprolog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-endprolog.md b/docs/assembler/masm/dot-endprolog.md index c864e0c8494..bc366ab72e5 100644 --- a/docs/assembler/masm/dot-endprolog.md +++ b/docs/assembler/masm/dot-endprolog.md @@ -1,14 +1,14 @@ --- description: "Learn more about: .ENDPROLOG" title: ".ENDPROLOG" -ms.date: "12/17/2019" +ms.date: 05/06/2026 f1_keywords: [".ENDPROLOG"] helpviewer_keywords: [".ENDPROLOG directive"] -ms.assetid: 61a2474c-9527-46e6-9f9d-bc4b42c10f35 +ai-usage: ai-assisted --- # .ENDPROLOG -Signals the end of the prologue declarations. +Marks the end of the prologue declarations. ## Syntax @@ -16,11 +16,22 @@ Signals the end of the prologue declarations. ## Remarks -It is an error to use any of the prologue declarations outside of the region between [PROC](proc.md) **FRAME** and **.ENDPROLOG**. +It's an error to use any of the prologue declarations outside of the region between [PROC](proc.md) `FRAME` and **.ENDPROLOG**. For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md). +## Unwind Version 3 behavior + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. +> Enable it with `ml64.exe /unwindv3`. + +`.ENDPROLOG` is also used in Unwind Version 3 and continues to mark the end of the function prologue. It doesn't generate a Windows unwind data (WOD) unwind code entry. + +It's an error to use any prologue directive outside the region between `PROC FRAME` and `.ENDPROLOG`. + ## See also +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ [Directives Reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-fpo.md b/docs/assembler/masm/dot-fpo.md index 0e523fb9bf1..7c70aab623a 100644 --- a/docs/assembler/masm/dot-fpo.md +++ b/docs/assembler/masm/dot-fpo.md @@ -4,35 +4,34 @@ title: ".FPO" ms.date: "11/05/2019" f1_keywords: [".FPO"] helpviewer_keywords: [".FPO directive"] -ms.assetid: 35f4cd61-32f9-4262-b657-73f04f775d09 --- # .FPO (32-bit MASM) -The **.FPO** directive controls the emission of debug records to the .debug$F segment or section. (32-bit MASM only.) +The `.FPO` directive controls the emission of debug records to the `.debug$F` segment or section. Use this directive with 32-bit MASM only. ## Syntax -> **.FPO** (*cdwLocals*, *cdwParams*, *cbProlog*, *cbRegs*, *fUseBP*, *cbFrame*) +> `.FPO` (*`cdwLocals`*, *`cdwParams`*, *`cbProlog`*, *`cbRegs`*, *`fUseBP`*, *`cbFrame`*) ### Parameters -*cdwLocals*\ -Number of local variables, an unsigned 32 bit value. +*`cdwLocals`*\ +Number of local variables, an unsigned 32-bit value. -*cdwParams*\ -Size of the parameters in DWORDS, an unsigned 16 bit value. +*`cdwParams`*\ +Size of the parameters in DWORDS, an unsigned 16-bit value. -*cbProlog*\ -Number of bytes in the function prolog code, an unsigned 8 bit value. +*`cbProlog`*\ +Number of bytes in the function prolog code, an unsigned 8-bit value. -*cbRegs*\ +*`cbRegs`*\ Number registers saved. -*fUseBP*\ -Indicates whether the EBP register has been allocated. either 0 or 1. +*`fUseBP`*\ +Indicates whether the EBP register is allocated. Use either 0 or 1. -*cbFrame*\ -Indicates the frame type. See [FPO_DATA](/windows/win32/api/winnt/ns-winnt-fpo_data) for more information. +*`cbFrame`*\ +Indicates the frame type. For more information, see [`FPO_DATA`](/windows/win32/api/winnt/ns-winnt-fpo_data). ## See also diff --git a/docs/assembler/masm/dot-freestack.md b/docs/assembler/masm/dot-freestack.md new file mode 100644 index 00000000000..bf80a2be682 --- /dev/null +++ b/docs/assembler/masm/dot-freestack.md @@ -0,0 +1,74 @@ +--- +description: "Learn more about: .FREESTACK" +title: ".FREESTACK" +ms.date: 05/06/2026 +f1_keywords: [".FREESTACK"] +helpviewer_keywords: [".FREESTACK directive"] +ai-usage: ai-assisted +--- +# .FREESTACK + +Generates a **WOD_ALLOC_SMALL**, **WOD_ALLOC_LARGE**, or **WOD_ALLOC_HUGE** unwind code entry with the specified size for the current offset in the epilogue. + +## Syntax + +> **.FREESTACK** *size* + +## Parameters + +*size*\ +The number of bytes to deallocate from the stack. Must be a multiple of 8. + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. +> Enable Unwind Version 3 by using `ml64.exe /unwindv3`. + +- You can use **.FREESTACK** only in Unwind Version 3. It's the epilogue counterpart to [.ALLOCSTACK](dot-allocstack.md). +- You can use **.FREESTACK** only within an epilogue region, between [.BEGINEPILOG](dot-beginepilog.md) and [.ENDEPILOG](dot-endepilog.md). +- In Unwind Version 3, **.FREESTACK** must appear **before** the `add rsp, N` instruction that implements the stack deallocation. +- To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- Microsoft Assembler (MASM) chooses the most efficient encoding for a given size. + +MASM emits one of three unwind codes depending on the size: + +| Unwind code | Condition | +|---|---| +| `WOD_ALLOC_SMALL` | *size* ≤ 128 bytes | +| `WOD_ALLOC_LARGE` | *size* ≤ 32 KB | +| `WOD_ALLOC_HUGE` | *size* > 32 KB | + +In Unwind Version 3, epilogue directives are mandatory for epilogue unwind code generation. The assembler doesn't emit epilogue unwind codes without a `.BEGINEPILOG`/`.ENDEPILOG` pair. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .allocstack 16 + sub rsp, 16 +.endprolog + ; function body + .beginepilog + .freestack 16 + add rsp, 16 + .endepilog + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.ALLOCSTACK](dot-allocstack.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-nolistif.md b/docs/assembler/masm/dot-nolistif.md index bb4996f2add..37703a53fb2 100644 --- a/docs/assembler/masm/dot-nolistif.md +++ b/docs/assembler/masm/dot-nolistif.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: .NOLISTIF" title: ".NOLISTIF" +description: "Learn more about: .NOLISTIF" ms.date: "12/16/2019" f1_keywords: [".NOLISTIF"] helpviewer_keywords: [".NOLISTIF directive"] -ms.assetid: 9243af7a-7221-4531-bbc3-281b6b292bfd --- # .NOLISTIF @@ -20,5 +19,5 @@ This is the default. Same as [.SFCOND](dot-sfcond.md). ## See also -[Directives reference](directives-reference.md) +[Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-pop2reg.md b/docs/assembler/masm/dot-pop2reg.md new file mode 100644 index 00000000000..56dbdff4b52 --- /dev/null +++ b/docs/assembler/masm/dot-pop2reg.md @@ -0,0 +1,76 @@ +--- +description: "Learn more about: .POP2REG" +title: ".POP2REG" +ms.date: 05/04/2026 +f1_keywords: [".POP2REG"] +helpviewer_keywords: [".POP2REG directive"] +ai-usage: ai-assisted +--- +# .POP2REG + +Generates a two-register pop unwind code entry for the specified register pair using the current offset in the epilogue. + +## Syntax + +> **.POP2REG** *register1*, *register2* + +## Parameters + +*register1*\ +The first register to pop. Must be a general-purpose 64-bit register. + +*register2*\ +The second register to pop. Must be a general-purpose 64-bit register. + +*register1* and *register2* may each be one of:\ +`RAX, RCX, RDX, RBX, RDI, RSI, RBP, R8, R9, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31`. + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. Enable Unwind Version 3 with `ml64.exe /unwindv3`. + +- **.POP2REG** is only valid in Unwind Version 3. It's the epilogue counterpart to [.PUSH2REG](dot-push2reg.md). +- **.POP2REG** is only allowed within an epilogue region, between [.BEGINEPILOG](dot-beginepilog.md) and [.ENDEPILOG](dot-endepilog.md). +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- In Unwind Version 3, **.POP2REG** must appear **before** the instruction that actually implements the action to be unwound. +- In Unwind Version 3, epilogue directives are mandatory for epilogue unwind code generation. No epilogue unwind codes are emitted without a `.BEGINEPILOG`/`.ENDEPILOG` pair. +- To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. + +If *register1* and *register2* are consecutive and in increasing order, MASM emits a `WOD_PUSH_CONSECUTIVE_2` unwind code. Otherwise, MASM emits a `WOD_PUSH2` unwind code. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .push2reg rbx, rsi + push2 rbx, rsi + .push2reg r10, r11 + push2 r10, r11 +.endprolog + ; rest of function ... + .beginepilog + .pop2reg r10, r11 + pop2 r10, r11 + .pop2reg rbx, rsi + pop2 rbx, rsi + .endepilog + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.PUSH2REG](dot-push2reg.md)\ +[.POPREG](dot-popreg.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-popframe.md b/docs/assembler/masm/dot-popframe.md new file mode 100644 index 00000000000..6f0d869f13d --- /dev/null +++ b/docs/assembler/masm/dot-popframe.md @@ -0,0 +1,74 @@ +--- +description: "Learn more about: .POPFRAME" +title: ".POPFRAME" +ms.date: 05/01/2026 +f1_keywords: [".POPFRAME"] +helpviewer_keywords: [".POPFRAME directive"] +ai-usage: ai-assisted +--- +# .POPFRAME + +Generates a `WOD_PUSH_CANONICAL_FRAME` Windows unwind data (WOD) unwind code entry in the epilogue. + +## Syntax + +> **.POPFRAME** ⟦**CODE** | *value*⟧ + +## Parameters + +*value*\ +An optional numeric modifier in the range 0–255.\ +Mutually exclusive with **CODE**. If you specify the optional **CODE** keyword, the unwind code entry receives a modifier of 1.\ +If you specify an optional numeric *value* instead, it receives the specified value.\ +If you don't pass an argument, the value is 0. + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. Enable Unwind Version 3 with `ml64.exe /unwindv3`. + +The **.POPFRAME** directive lets `ml64.exe` users specify how a frame function unwinds in an epilog. You can only use it within an epilog region, between [.BEGINEPILOG](dot-beginepilog.md) and [.ENDEPILOG](dot-endepilog.md). + +- **.POPFRAME** is only valid in Unwind Version 3. It's the epilog counterpart of [.PUSHFRAME](dot-pushframe.md). The operand value should match the corresponding **.PUSHFRAME** in the prologue. +- In Unwind Version 3, **.POPFRAME** must appear **before** the instruction that implements the action to be unwound. To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. +- In Unwind Version 3, epilogue directives are mandatory for epilogue unwind code generation. No epilogue unwind codes are emitted without a `.BEGINEPILOG`/`.ENDEPILOG` pair. +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. + +> [!NOTE] +> In Unwind Version 1, directives appear after the corresponding instruction. In Unwind Version 3, directives appear **before** the instruction. + +## Example for unwindv3 + +The following example shows how to use **.POPFRAME** in an epilogue to indicate an interrupt handler that pushes and pops a canonical machine frame. + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .pushframe + .pushreg rbx + push rbx + .allocstack 32 + sub rsp, 32 +.endprolog + ; interrupt handler body ... + .beginepilog + .freestack 32 + add rsp, 32 + .popreg rbx + pop rbx + .popframe + .endepilog + iretq +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[.PUSHFRAME](dot-pushframe.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[.ENDEPILOG](dot-endepilog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-popreg.md b/docs/assembler/masm/dot-popreg.md new file mode 100644 index 00000000000..963e7de0f48 --- /dev/null +++ b/docs/assembler/masm/dot-popreg.md @@ -0,0 +1,70 @@ +--- +description: "Learn more about: .POPREG" +title: ".POPREG" +ms.date: 05/04/2026 +f1_keywords: [".POPREG"] +helpviewer_keywords: [".POPREG directive"] +ai-usage: ai-assisted +--- +# .POPREG + +Generates a `WOD_PUSH` unwind code entry for the specified register using the current offset in the epilogue. + +## Syntax + +> .POPREG *register* + +## Parameters + +*register*\ +The register to pop. Must be a general-purpose 64-bit register. + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. Enable Unwind Version 3 by using the `/unwindv3` option in ml64.exe. + +`.POPREG` is only valid in Unwind Version 3. It's the epilogue counterpart to [.PUSHREG](dot-pushreg.md). + +`.POPREG` is only allowed within an epilogue region, between [.BEGINEPILOG](dot-beginepilog.md) and [.ENDEPILOG](dot-endepilog.md). These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. In Unwind Version 3, `.POPREG` must appear **before** the `pop` instruction that implements the register restore. To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. + +*register* may be one of:\ +`RAX, RCX, RDX, RBX, RDI, RSI, RBP, R8, R9, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31` + +In Unwind Version 3, epilogue directives are mandatory for epilogue unwind code generation. The assembler doesn't emit epilogue unwind codes without a `.BEGINEPILOG`/`.ENDEPILOG` pair. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .pushreg rbx + push rbx + .pushreg rsi + push rsi +.endprolog + ; rest of function ... + .beginepilog + .popreg rsi + pop rsi + .popreg rbx + pop rbx + .endepilog + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.PUSHREG](dot-pushreg.md)\ +[.POP2REG](dot-pop2reg.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-push2reg.md b/docs/assembler/masm/dot-push2reg.md new file mode 100644 index 00000000000..d43e1113271 --- /dev/null +++ b/docs/assembler/masm/dot-push2reg.md @@ -0,0 +1,65 @@ +--- +description: "Learn more about: .PUSH2REG" +title: ".PUSH2REG" +ms.date: 05/04/2026 +f1_keywords: [".PUSH2REG"] +helpviewer_keywords: [".PUSH2REG directive"] +ai-usage: ai-assisted +--- +# .PUSH2REG + +Generates a two-register push unwind code entry for the specified register pair using the current offset in the prologue. + +## Syntax + +> `.PUSH2REG` *register1*, *register2* + +## Parameters + +*register1*\ +The first register to push. Must be a general-purpose 64-bit register. + +*register2*\ +The second register to push. Must be a general-purpose 64-bit register. + +*register1* and *register2* may each be one of:\ +`RAX, RCX, RDX, RBX, RDI, RSI, RBP, R8, R9, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31.` + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. Enable Unwind Version 3 by using `ml64.exe /unwindv3`. + +- Use `.PUSH2REG` to specify how a frame function unwinds. You can only use this directive within the prologue, which extends from the [PROC](proc.md) `FRAME` declaration to the [.ENDPROLOG](dot-endprolog.md) directive. +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. In Unwind Version 3, `.PUSH2REG` must appear **before** the instruction that actually implements the action to be unwound. To ensure agreement, it's a good practice to wrap both the unwind directives and the code they're meant to unwind in a macro. +- If *register1* and *register2* are consecutive and in increasing order, MASM emits a `WOD_PUSH_CONSECUTIVE_2` unwind code. Otherwise, MASM emits a `WOD_PUSH2` unwind code. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .push2reg r10, r11 + push2 r10, r11 + .push2reg rbx, rsi + push2 rbx, rsi +.endprolog + ; rest of function ... + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.POP2REG](dot-pop2reg.md)\ +[.PUSHREG](dot-pushreg.md)\ +[.ENDPROLOG](dot-endprolog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-pushframe.md b/docs/assembler/masm/dot-pushframe.md index 07dc3972dfc..da3d77c596f 100644 --- a/docs/assembler/masm/dot-pushframe.md +++ b/docs/assembler/masm/dot-pushframe.md @@ -4,23 +4,58 @@ description: "Describes the .PUSHFRAME MASM directive, used to specify how to un ms.date: "12/06/2019" f1_keywords: [".PUSHFRAME"] helpviewer_keywords: [".PUSHFRAME directive"] -ms.assetid: 17b123d0-4c6d-4fd2-85eb-798e8ad0a73c +ai-usage: ai-assisted --- # .PUSHFRAME -Generates a `UWOP_PUSH_MACHFRAME` unwind code entry. If the optional **CODE** keyword is specified, the unwind code entry is given a modifier of 1. Otherwise the modifier is 0. +Generates a `UWOP_PUSH_MACHFRAME` unwind code entry. If you specify the optional **CODE** keyword, the unwind code entry gets a modifier of 1. Otherwise, the modifier is 0. ## Syntax -> **.PUSHFRAME** ⟦**CODE**⟧;; +> `.PUSHFRAME` ⟦**CODE**⟧ ;Prior to Unwind Version 3 +> `.PUSHFRAME` ⟦**CODE**⟧ | [0-255] ;Unwind Version 3 specific ## Remarks -.PUSHFRAME allows ml64.exe users to specify how a frame function unwinds. It's only allowed within the prologue, which extends from the [PROC](proc.md) FRAME declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives don't generate code; they only generate `.xdata` and `.pdata`. **.PUSHFRAME** should be preceded by instructions that actually implement the actions to be unwound. It's a good practice to wrap both the unwind directives and the code they're meant to unwind in a macro to ensure agreement. +Use `.PUSHFRAME` with `ml64.exe` to specify how a frame function unwinds. You can only use it within the prologue, which extends from the [PROC](proc.md) `FRAME` declaration to the [.ENDPROLOG](dot-endprolog.md) directive. +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- Precede `.PUSHFRAME` with the instructions that implement the actions to be unwound. +- To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. -For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md). +## Unwind Version 3 behavior + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. Enable it by using `ml64.exe /unwindv3`. + +In Unwind Version 3, `.PUSHFRAME` emits a `WOD_PUSH_CANONICAL_FRAME` unwind code entry.\ +When you specify the optional **CODE** keyword, the unwind code entry modifier value is 1.\ +If you specify an optional *value*, the directive uses it directly.\ +If you don't pass an argument, the value is 0. The *value* must be in the range 0–255. + +> **Note:** In Unwind Version 1 the directives come after the instruction. In Unwind Version 3, the directives come before the instruction. +> `.PUSHFRAME` must appear **before** the instruction it describes. This behavior is the opposite of Version 1, where the directive follows the instruction. + +### Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .pushframe CODE +.endprolog + ; interrupt handler body ... + iretq +Example1 ENDP +_text ENDS +END +``` + +The epilogue counterpart is [.POPFRAME](dot-popframe.md). ## See also +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ [Directives reference](directives-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[.POPFRAME](dot-popframe.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md)\ +[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md) diff --git a/docs/assembler/masm/dot-pushreg.md b/docs/assembler/masm/dot-pushreg.md index a433f688d6e..d6a48cb5227 100644 --- a/docs/assembler/masm/dot-pushreg.md +++ b/docs/assembler/masm/dot-pushreg.md @@ -1,10 +1,10 @@ --- description: "Learn more about: .PUSHREG" title: ".PUSHREG" -ms.date: "12/16/2019" +ms.date: 05/04/2026 f1_keywords: [".PUSHREG"] helpviewer_keywords: [".PUSHREG directive"] -ms.assetid: e0c83758-dfed-40ea-afe6-cb833c8d2d30 +ai-usage: ai-assisted --- # .PUSHREG @@ -14,23 +14,20 @@ Generates a `UWOP_PUSH_NONVOL` unwind code entry for the specified register numb > .PUSHREG *register* -## Remarks - -**.PUSHREG** allows ml64.exe users to specify how a frame function unwinds, and is only allowed within the prologue, which extends from the [PROC](proc.md) **FRAME** declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives do not generate code; they only generate `.xdata` and `.pdata`. **.PUSHREG** should be preceded by instructions that actually implement the actions to be unwound. It is a good practice to wrap both the unwind directives and the code they are meant to unwind in a macro to ensure agreement. - *register* may be one of:\ -RAX | RCX | RDX | RBX | RDI | RSI | RBP | R8 | R9 | R10 | R11 | R12 | R13 | R14 | R15. - -For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md). +`RAX, RCX, RDX, RBX, RDI, RSI, RBP, R8, R9, R10, R11, R12, R13, R14, R15` -## Sample +Unwind Version 3 extends register support to include R16–R31. *register* may be one of:\ +`RAX, RCX, RDX, RBX, RDI, RSI, RBP, R8, R9, R10, R11, R12, R13, R14, R15, R16, R17, R18, R19, R20, R21, R22, R23, R24, R25, R26, R27, R28, R29, R30, R31` -### Description +## Remarks -The following sample shows how to push non-volatile registers. +Use `.PUSHREG` with `ml64.exe` to specify how a frame function unwinds. You can only use `.PUSHREG` within the prologue, which extends from the [PROC](proc.md) `FRAME` declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. Precede `.PUSHREG` with the instructions that actually implement the actions to be unwound. To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. ### Code +The following sample shows how to push nonvolatile registers. + ```asm ; ml64 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE _text SEGMENT @@ -51,7 +48,42 @@ _text ENDS END ``` +## Unwind Version 3 behavior + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. Enable it by using `ml64.exe /unwindv3`. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. +> In Unwind Version 3, `.PUSHREG` generates a `WOD_PUSH` unwind code entry and must appear **before** the `push reg` instruction it describes. This requirement is the opposite of Version 1, where the directive follows the instruction. + +### Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .pushreg r10 + push r10 + .pushreg r15 + push r15 + .pushreg rbx + push rbx + .pushreg rsi + push rsi +.endprolog + ; rest of function ... + ret +Example1 ENDP +_text ENDS +END +``` + +The epilogue counterpart is [.POPREG](dot-popreg.md). + ## See also +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ [Directives reference](directives-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF Grammar](masm-bnf-grammar.md)\ +[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md) \ No newline at end of file diff --git a/docs/assembler/masm/dot-restorereg.md b/docs/assembler/masm/dot-restorereg.md new file mode 100644 index 00000000000..94836c8da74 --- /dev/null +++ b/docs/assembler/masm/dot-restorereg.md @@ -0,0 +1,77 @@ +--- +description: "Learn more about: .RESTOREREG" +title: ".RESTOREREG" +ms.date: 05/04/2026 +f1_keywords: [".RESTOREREG"] +helpviewer_keywords: [".RESTOREREG directive"] +ai-usage: ai-assisted +--- +# .RESTOREREG + +Generates either a `WOD_SAVE_NONVOL` or a `WOD_SAVE_NONVOL_FAR` unwind code entry for the specified register and offset, using the current epilogue offset. + +## Syntax + +> `.RESTOREREG` *reg*, *offset* + +## Parameters + +*reg*\ +The nonvolatile register to restore. + +*offset*\ +The stack offset from which the register is restored. + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. Enable Unwind Version 3 by using `ml64.exe /unwindv3`. + +`.RESTOREREG` is only valid in Unwind Version 3. It's the epilogue counterpart to [.SAVEREG](dot-savereg.md). + +Microsoft Assembler (MASM) chooses the most efficient encoding for a given offset. + +- `.RESTOREREG` is only allowed within an epilogue region, between [.BEGINEPILOG](dot-beginepilog.md) and [.ENDEPILOG](dot-endepilog.md). +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- In Unwind Version 3, `.RESTOREREG` must appear **before** the instruction that loads the register from the stack. +- To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. +- In Unwind Version 3, epilogue directives are mandatory for epilogue unwind code generation. No epilogue unwind codes are emitted without a `.BEGINEPILOG`/`.ENDEPILOG` pair. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .allocstack 020h + sub rsp, 020h + .savereg rbx, 0 + mov [rsp], rbx + .savereg rsi, 8 + mov [rsp+8], rsi +.endprolog + ; rest of function ... + .beginepilog + .restorereg rsi, 8 + mov rsi, [rsp+8] + .restorereg rbx, 0 + mov rbx, [rsp] + .freestack 020h + add rsp, 020h + .endepilog + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.SAVEREG](dot-savereg.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-restorexmm128.md b/docs/assembler/masm/dot-restorexmm128.md new file mode 100644 index 00000000000..03d1bc27750 --- /dev/null +++ b/docs/assembler/masm/dot-restorexmm128.md @@ -0,0 +1,77 @@ +--- +description: "Learn more about: .RESTOREXMM128" +title: ".RESTOREXMM128" +ms.date: 05/06/2026 +f1_keywords: [".RESTOREXMM128"] +helpviewer_keywords: [".RESTOREXMM128 directive"] +ai-usage: ai-assisted +--- +# .RESTOREXMM128 + +Generates either a `WOD_SAVE_XMM128` or a `WOD_SAVE_XMM128_FAR` Unwind Version 3 unwind code entry for the specified XMM register and offset using the current epilogue offset. + +## Syntax + +> `.RESTOREXMM128` *xmmreg*, *offset* + +## Parameters + +*xmmreg*\ +The XMM register to restore. + +*offset*\ +The stack offset from which the register is restored. Must be a multiple of 16. + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. Enable Unwind Version 3 with `ml64.exe /unwindv3`. + +`.RESTOREXMM128` is only valid in Unwind Version 3. It's the epilogue counterpart to [.SAVEXMM128](dot-savexmm128.md). + +Microsoft Assembler (MASM) chooses the most efficient encoding for a given offset. + +- `.RESTOREXMM128` is only allowed within an epilogue region, between [.BEGINEPILOG](dot-beginepilog.md) and [.ENDEPILOG](dot-endepilog.md). +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- In Unwind Version 3, `.RESTOREXMM128` must appear **before** the instruction that loads the XMM register from the stack. +- To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. +- In Unwind Version 3, epilogue directives are mandatory for epilogue unwind code generation. No epilogue unwind codes are emitted without a `.BEGINEPILOG`/`.ENDEPILOG` pair. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .allocstack 030h + sub rsp, 030h + .savexmm128 xmm6, 0 + movdqa [rsp], xmm6 + .savexmm128 xmm7, 010h + movdqa [rsp+010h], xmm7 +.endprolog + ; rest of function ... + .beginepilog + .restorexmm128 xmm7, 010h + movdqa xmm7, [rsp+010h] + .restorexmm128 xmm6, 0 + movdqa xmm6, [rsp] + .freestack 030h + add rsp, 030h + .endepilog + ret +Example1 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.SAVEXMM128](dot-savexmm128.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-savereg.md b/docs/assembler/masm/dot-savereg.md index a786f88777f..654d19cfe57 100644 --- a/docs/assembler/masm/dot-savereg.md +++ b/docs/assembler/masm/dot-savereg.md @@ -1,26 +1,70 @@ --- description: "Learn more about: .SAVEREG" title: ".SAVEREG" -ms.date: "12/16/2019" +ms.date: 05/06/2026 f1_keywords: [".SAVEREG"] helpviewer_keywords: [".SAVEREG directive"] -ms.assetid: 1dbc2ef6-a197-40e7-9e55-fddcae8cef29 +ai-usage: ai-assisted --- # .SAVEREG -Generates either a `UWOP_SAVE_NONVOL` or a `UWOP_SAVE_NONVOL_FAR` unwind code entry for the specified register (*reg*) and offset (*offset*) using the current prologue offset. MASM will choose the most efficient encoding. +Generates either a `UWOP_SAVE_NONVOL` or a `UWOP_SAVE_NONVOL_FAR` unwind code entry for the specified register (*reg*) and offset (*offset*) using the current prologue offset. Microsoft Assembler (MASM) chooses the most efficient encoding. ## Syntax -> **.SAVEREG** *reg*__,__ *offset* +> `.SAVEREG` *reg*__,__ *offset* ## Remarks -**.SAVEREG** allows ml64.exe users to specify how a frame function unwinds and is only allowed within the prologue, which extends from the [PROC](proc.md) FRAME declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives do not generate code; they only generate `.xdata` and `.pdata`. **.SAVEREG** should be preceded by instructions that actually implement the actions to be unwound. It is a good practice to wrap both the unwind directives and the code they are meant to unwind in a macro to ensure agreement. +Use `.SAVEREG` with `ml64.exe` to specify how a frame function unwinds. You can only use it within the prologue, which extends from the [`PROC`](proc.md) `FRAME` declaration to the [.ENDPROLOG](dot-endprolog.md) directive. +- These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. +- Precede `.SAVEREG` with instructions that actually implement the actions to be unwound. +- To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. -For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md). +## Unwind Version 3 behavior + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. Enable it by using `ml64.exe /unwindv3`. + +In Unwind Version 3, `.SAVEREG` emits either a `WOD_SAVE_NONVOL` or a `WOD_SAVE_NONVOL_FAR` unwind code entry. MASM selects the most efficient encoding based on the size of *offset*: + +| Unwind code | Condition | +|---|---| +| `WOD_SAVE_NONVOL` | *offset* can be encoded as a scaled 16-bit value | +| `WOD_SAVE_NONVOL_FAR` | *offset* requires a full 32-bit value | + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. +> `.SAVEREG` must appear **before** the instruction it describes. This requirement is the opposite of Version 1, where the directive follows the instruction. + +### Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .allocstack 020h + sub rsp, 020h + .savereg rbx, 0 + mov [rsp], rbx + .savereg rsi, 8 + mov [rsp+8], rsi +.endprolog + ; rest of function ... + mov rsi, [rsp+8] + mov rbx, [rsp] + add rsp, 020h + ret +Example1 ENDP +_text ENDS +END +``` + +The epilogue counterpart is [.RESTOREREG](dot-restorereg.md). ## See also +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ [Directives reference](directives-reference.md)\ +[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-savexmm128.md b/docs/assembler/masm/dot-savexmm128.md index 6a914c5547f..ed2fae15341 100644 --- a/docs/assembler/masm/dot-savexmm128.md +++ b/docs/assembler/masm/dot-savexmm128.md @@ -1,28 +1,69 @@ --- description: "Learn more about: .SAVEXMM128" title: ".SAVEXMM128" -ms.date: "12/17/2019" +ms.date: 05/04/2026 f1_keywords: [".SAVEXMM128"] helpviewer_keywords: [".SAVEXMM128 directive"] -ms.assetid: 551eb472-b8d0-47b1-8d82-995d1f485723 +ai-usage: ai-assisted --- # .SAVEXMM128 -Generates either a `UWOP_SAVE_XMM128` or a `UWOP_SAVE_XMM128_FAR` unwind code entry for the specified XMM register and offset using the current prologue offset. MASM will choose the most efficient encoding. +Generates either a `UWOP_SAVE_XMM128` or a `UWOP_SAVE_XMM128_FAR` unwind code entry for the specified XMM register and offset using the current prologue offset. Microsoft Assembler (MASM) chooses the most efficient encoding. ## Syntax -> **.SAVEXMM128** *xmmreg* , *offset* +> `.SAVEXMM128` *xmmreg* , *offset* ## Remarks -**.SAVEXMM128** allows ml64.exe users to specify how a frame function unwinds, and is only allowed within the prologue, which extends from the [PROC](proc.md) FRAME declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives do not generate code; they only generate `.xdata` and `.pdata`. .SAVEXMM128 should be preceded by instructions that actually implement the actions to be unwound. It is a good practice to wrap both the unwind directives and the code they are meant to unwind in a macro to ensure agreement. +Use `.SAVEXMM128` with `ml64.exe` to specify how a frame function unwinds. You can only use it within the prologue, which extends from the [`PROC`](proc.md) `FRAME` declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. Precede `.SAVEXMM128` by the instructions that actually implement the actions to be unwound. To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. *offset* must be a multiple of 16. -For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md). +## Unwind Version 3 behavior + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. Enable it by using `ml64.exe /unwindv3`. + +In Unwind Version 3, `.SAVEXMM128` emits either a `WOD_SAVE_XMM128` or a `WOD_SAVE_XMM128_FAR` unwind code entry. Microsoft Assembler (MASM) selects the most efficient encoding based on the size of *offset*: + +| Unwind code | Condition | +|---|---| +| `WOD_SAVE_XMM128` | *offset* can be encoded as a scaled 16-bit value | +| `WOD_SAVE_XMM128_FAR` | *offset* requires a full 32-bit value | + +> [!NOTE] +> In Unwind Version 1 the directives come after the instruction. In Unwind Version 3, the directives come before the instruction. +> `.SAVEXMM128` must appear **before** the instruction it describes. This requirement is the opposite of Version 1, where the directive follows the instruction. + +### Example for unwindv3 + +```asm +; ml64 /unwindv3 ex1.asm /link /entry:Example1 /SUBSYSTEM:CONSOLE +_text SEGMENT +Example1 PROC FRAME + .allocstack 030h + sub rsp, 030h + .savexmm128 xmm6, 0 + movdqa [rsp], xmm6 + .savexmm128 xmm7, 010h + movdqa [rsp+010h], xmm7 +.endprolog + ; rest of function ... + movdqa xmm7, [rsp+010h] + movdqa xmm6, [rsp] + add rsp, 030h + ret +Example1 ENDP +_text ENDS +END +``` + +The epilogue counterpart is [.RESTOREXMM128](dot-restorexmm128.md). ## See also +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ [Directives reference](directives-reference.md)\ -[MASM BNF Grammar](masm-bnf-grammar.md) +[MASM BNF Grammar](masm-bnf-grammar.md)\ +[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md) diff --git a/docs/assembler/masm/dot-setframe.md b/docs/assembler/masm/dot-setframe.md index d33281ed97a..7eeec50f330 100644 --- a/docs/assembler/masm/dot-setframe.md +++ b/docs/assembler/masm/dot-setframe.md @@ -1,10 +1,10 @@ --- description: "Learn more about: .SETFRAME" title: ".SETFRAME" -ms.date: "12/17/2019" +ms.date: 05/04/2026 f1_keywords: [".SETFRAME"] helpviewer_keywords: [".SETFRAME directive"] -ms.assetid: eaa9b5ed-4daa-4f1e-bdb6-100758007ab3 +ai-usage: ai-assisted --- # .SETFRAME @@ -12,13 +12,11 @@ Fills in the frame register field and offset in the unwind information using the ## Syntax -> **.SETFRAME** *reg*, *offset* +> `.SETFRAME` *reg*, *offset* ## Remarks -**.SETFRAME** allows ml64.exe users to specify how a frame function unwinds, and is only allowed within the prologue, which extends from the [PROC](proc.md) FRAME declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives do not generate code; they only generate `.xdata` and `.pdata`. **.SETFRAME** should be preceded by instructions that actually implement the actions to be unwound. It is a good practice to wrap both the unwind directives and the code they are meant to unwind in a macro to ensure agreement. - -For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md). +Use `.SETFRAME` to specify how a frame function unwinds. You can only use it within the prologue, which extends from the [`PROC`](proc.md) `FRAME` declaration to the [.ENDPROLOG](dot-endprolog.md) directive. These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code. Precede `.SETFRAME` with instructions that implement the actions to be unwound. To ensure agreement, wrap both the unwind directives and the code they're meant to unwind in a macro. ## Sample @@ -55,7 +53,51 @@ _text ENDS END ``` +## Unwind Version 3 behavior + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. Enable it by using `ml64.exe /unwindv3`. + +In Unwind Version 3, `.SETFRAME` emits a `WOD_SET_FPREG` unwind code entry for the specified register using the current prologue offset. It also fills in the frame register field and offset in the unwind information. The *offset* must be a multiple of 16 and less than or equal to 240. + +> [!NOTE] +> In Unwind Version 1 the directives come after the instruction. In Unwind Version 3, the directives come before the instruction. +> `.SETFRAME` must appear **before** the instruction it describes. This requirement is the opposite of Version 1, where the directive follows the instruction. + +### Example for unwindv3 + +```asm +; ml64 /unwindv3 frmex2.asm /link /entry:frmex2 /SUBSYSTEM:CONSOLE +_text SEGMENT +frmex2 PROC FRAME + .pushreg rbp + push rbp + .allocstack 010h + sub rsp, 010h + .setframe rbp, 0 + mov rbp, rsp +.endprolog + ; modify the stack pointer outside of the prologue (similar to alloca) + sub rsp, 060h + + ; we can unwind from the following AV because of the frame pointer + mov rax, 0 + mov rax, [rax] ; AV! + + add rsp, 060h + add rsp, 010h + pop rbp + ret +frmex2 ENDP +_text ENDS +END +``` + +The epilogue counterpart is [.UNSETFRAME](dot-unsetframe.md). + ## See also +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md)\ [Directives reference](directives-reference.md)\ [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-unsetframe.md b/docs/assembler/masm/dot-unsetframe.md new file mode 100644 index 00000000000..10b55371053 --- /dev/null +++ b/docs/assembler/masm/dot-unsetframe.md @@ -0,0 +1,82 @@ +--- +description: "Learn more about: .UNSETFRAME" +title: ".UNSETFRAME" +ms.date: 05/04/2026 +f1_keywords: [".UNSETFRAME"] +helpviewer_keywords: [".UNSETFRAME directive"] +ai-usage: ai-assisted +--- +# .UNSETFRAME + +Generates a `WOD_SET_FPREG` unwind code entry for the specified register and offset using the current offset in the epilogue. + +## Syntax + +> `.UNSETFRAME` *reg*, *offset* + +## Parameters + +*reg*\ +The frame pointer register to unset. + +*offset*\ +The offset into the stack frame where the frame pointer was established. + +## Remarks + +> [!IMPORTANT] +> This directive is experimental and is subject to change. Enable Unwind Version 3 with `ml64.exe /unwindv3`. + +`.UNSETFRAME` is only valid in Unwind Version 3. It's the epilogue counterpart to [.SETFRAME](dot-setframe.md). + +`.UNSETFRAME` is only allowed within an epilogue region, between [.BEGINEPILOG](dot-beginepilog.md) and [.ENDEPILOG](dot-endepilog.md). These directives generate unwind metadata (`.xdata` and `.pdata` sections) but don't produce executable code.\ +In Unwind Version 3, `.UNSETFRAME` must appear **before** the instruction that restores the stack pointer from the frame pointer register.\ +It's a good practice to wrap both the unwind directives and the code they're meant to unwind in a macro to ensure agreement. + +In Unwind Version 3, epilogue directives are mandatory for epilogue unwind code generation. No epilogue unwind codes are emitted without a `.BEGINEPILOG`/`.ENDEPILOG` pair. + +> [!NOTE] +> In Unwind Version 1, the directive appears after the corresponding instruction. In Unwind Version 3, the directive appears **before** the instruction. + +## Example for unwindv3 + +```asm +; ml64 /unwindv3 frmex2.asm /link /entry:frmex2 /SUBSYSTEM:CONSOLE +_text SEGMENT +frmex2 PROC FRAME + .pushreg rbp + push rbp + .allocstack 010h + sub rsp, 010h + .setframe rbp, 0 + mov rbp, rsp +.endprolog + ; modify the stack pointer outside of the prologue (similar to alloca) + sub rsp, 060h + + ; we can unwind from the following AV because of the frame pointer + mov rax, 0 + mov rax, [rax] ; AV! + + add rsp, 060h + .beginepilog + .unsetframe rbp, 0 + mov rsp, rbp + .freestack 010h + add rsp, 010h + .popreg rbp + pop rbp + .endepilog + ret +frmex2 ENDP +_text ENDS +END +``` + +## See also + +[x64 Unwind Version 3 (experimental)](directives-reference.md#x64-unwind-version-3-experimental)\ +[Directives Reference](directives-reference.md)\ +[.SETFRAME](dot-setframe.md)\ +[.BEGINEPILOG](dot-beginepilog.md)\ +[MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/dot-xmm.md b/docs/assembler/masm/dot-xmm.md index 72b1af9e0a2..9c0eae78b0f 100644 --- a/docs/assembler/masm/dot-xmm.md +++ b/docs/assembler/masm/dot-xmm.md @@ -8,7 +8,7 @@ ms.assetid: db3062b6-8b2f-469b-aa02-df6571eab3ba --- # .XMM (32-bit MASM) -Enables assembly of Internet Streaming SIMD Extension instructions. (32-bit MASM only.) +Enables assembly of Streaming SIMD Extension instructions. (32-bit MASM only.) ## Syntax diff --git a/docs/assembler/masm/even.md b/docs/assembler/masm/even.md index a8123b72031..f7b6a209b92 100644 --- a/docs/assembler/masm/even.md +++ b/docs/assembler/masm/even.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: EVEN" title: "EVEN" -ms.date: "12/17/2019" +description: "Learn more about: EVEN" +ms.date: 12/17/2019 f1_keywords: ["EVEN"] helpviewer_keywords: ["EVEN directive"] -ms.assetid: 68938ba4-8cb9-44d4-914e-9f9fee6bcbf4 --- -# EVEN +# `EVEN` Aligns the next variable or instruction on an even byte. @@ -16,5 +15,6 @@ Aligns the next variable or instruction on an even byte. ## See also +[`ALIGN`](align-masm.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 dc0325534e4..d261390d68c 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 d725146caf5..65eea98ce08 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 95c7e531492..6abb9b44993 100644 --- a/docs/assembler/masm/masm-for-x64-ml64-exe.md +++ b/docs/assembler/masm/masm-for-x64-ml64-exe.md @@ -1,13 +1,13 @@ --- description: "Learn more about: Microsoft Macro Assembler (MASM) for x64 (ml64.exe)" title: "MASM for x64 (ml64.exe)" -ms.date: 09/21/2021 +ms.date: 05/07/2026 helpviewer_keywords: ["ml64", "ml64.exe", "masm for x64"] -ms.assetid: 89059103-f372-4968-80ea-0c7f90bb9c91 +ai-usage: ai-assisted --- # 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). @@ -22,34 +22,54 @@ The Visual Studio project system supports assembler-language files built by usin ### To add an assembler-language file to an existing Visual Studio C++ project 1. Select the project in **Solution Explorer**. On the menu bar, choose **Project**, **Build Customizations**. - 1. In the **Visual C++ Build Customization Files** dialog box, check the checkbox next to **masm(.targets,.props)**. Choose **OK** to save your selection and close the dialog box. - 1. On the menu bar, choose **Project**, **Add New Item**. - 1. In the **Add New Item** dialog box, select **C++ file (.cpp)** in the center pane. In the **Name** edit control, enter a new file name that has a *`.asm`* extension instead of *`.cpp`*. Choose **Add** to add the file to your project and close the dialog box. Create your assembler-language code in the *`.asm`* file you added. When you build your solution, the MASM assembler is invoked to assemble the *`.asm`* file into an object file that is then linked into your project. To make symbol access easier, declare your assembler functions as `extern "C"` in your C++ source code, rather than using the C++ name decoration conventions in your assembler-language source files. -## ml64-Specific Directives +## ml64-specific directives You can use the following ml64-specific directives in your assembler-language source code that targets x64: - [`.ALLOCSTACK`](dot-allocstack.md) - - [`.ENDPROLOG`](dot-endprolog.md) - - [`.PUSHFRAME`](dot-pushframe.md) - - [`.PUSHREG`](dot-pushreg.md) - - [`.SAVEREG`](dot-savereg.md) - - [`.SAVEXMM128`](dot-savexmm128.md) - - [`.SETFRAME`](dot-setframe.md) -The [`PROC`](proc.md) directive has also been updated for use with ml64.exe. +The [`PROC`](proc.md) directive is also updated for use with ml64.exe. + +## Unwind Version 3 directives (experimental) + +> [!IMPORTANT] +> Unwind Version 3 support is experimental and is subject to change. + +Unwind Version 3 is an updated unwind code scheme for x64 that generates richer stack unwind metadata. It introduces new epilogue directives, extends register support, and changes the directive ordering model. + +### Enable Unwind Version 3 + +Assemble with the `/unwindv3` option: `ml64 /unwindv3 filename.asm /link /entry:FunctionName` + +### Key differences from Version 1 + +| Feature | Version 1 | Version 3 | +|---|---|---| +| Directive ordering | Directive follows instruction | Directive precedes instruction | +| Unwind codes | `UWOP_*` | `WOD_*` | +| `.ALLOCSTACK` size variants | 2 (`UWOP_ALLOC_SMALL`, `UWOP_ALLOC_LARGE`) | 3 (adds `WOD_ALLOC_HUGE` for > 32 KB) | +| `.PUSHREG` register range | R0–R15 | R0–R31 | +| Epilogue recording | Optional | Mandatory (`.BEGINEPILOG`/`.ENDEPILOG` required) | +| Register-pair push/pop | Not supported | `.PUSH2REG`/`.POP2REG` directives | + +Epilogue recording is mandatory in Version 3: `.BEGINEPILOG` and `.ENDEPILOG` must surround the epilogue instructions. Without them, no epilogue unwind codes are emitted. + +> [!NOTE] +> In Unwind Version 1 the directives come after the instruction. In Unwind Version 3, the directives come before the instruction. + +For a complete list of Version 3 directives, see [x64 Unwind Version 3 directives](directives-reference.md) and [@UnwindVersion](at-unwindversion.md). ## 32-Bit Address Mode (Address Size Override) diff --git a/docs/assembler/masm/microsoft-macro-assembler-reference.md b/docs/assembler/masm/microsoft-macro-assembler-reference.md index 57653862314..1cf7f094616 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 1f62e48b557..ab91d77ce37 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,10 @@ --- 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 -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 +ms.date: 05/25/2026 +ai-usage: ai-assisted +f1_keywords: ["ML", "/unwindv3"] +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", "/unwindv3 MASM compiler option"] --- # ML and ML64 command-line reference @@ -45,12 +45,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. | @@ -61,6 +62,7 @@ The options listed in the following table: | **`/St`** *`text`* | Specifies title for source listing. Same as [`TITLE`](title.md) text. | | **`/Sx`** | Turns on false conditionals in listing. | | **`/Ta`** *`filename`* | Assembles source file whose name doesn't end with the *`.asm`* extension. | +| **`/unwindv3`** | Enables experimental Unwind Version 3 unwind directive support. When specified, V3 unwind directives must appear *before* their associated instruction (the reverse of V1 behavior), epilogue recording via [`.BEGINEPILOG`](dot-beginepilog.md)/[`.ENDEPILOG`](dot-endepilog.md) is required, and the predefined macro [`@UnwindVersion`](at-unwindversion.md) returns `3`. For more information, see [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md).
Only available in ml64.exe. | | **`/w`** | Same as **`/W0 /WX`**. | | **`/W`** *`level`* | Sets the warning level, where *`level`* = 0, 1, 2, or 3. | | **`/WX`** | If warnings are generated, returns an error code. | @@ -69,12 +71,16 @@ The options listed in the following table: | **`/Zf`** | Makes all symbols public. | | **`/ZH:MD5`** | Use MD5 for checksum in debug info. | | **`/ZH:SHA_256`** | Use SHA256 for checksum in debug info (default in Visual Studio 2022 version 17.0 and later). | +| **`/ZH:SHA384`** | Use SHA384 for checksum in debug info.18.6.0 | +| **`/ZH:SHA512`** | Use SHA512 for checksum in debug info.18.6.0 | | **`/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. | +18.6.0 This option is available starting in Visual Studio 2026 version 18.6.0 and MSVC version 14.51. + *`filename`*\ The name of the file. diff --git a/docs/assembler/masm/ml-error-messages.md b/docs/assembler/masm/ml-error-messages.md index fa05763b6c5..60ef6633352 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 58b8730b208..64c18b9e37a 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 8dbccfde317..26a5522b820 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 dddac877491..8f6c7940ef2 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 64c30f7b550..c18d2492c96 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 b3395c7b590..23fe9aee2ce 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 7c0b1733fc5..0229ad31366 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 e64d7bef966..6a5e3ea9200 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 c0281f0d1c7..193e1af425c 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 024e05953ad..186314b2806 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 c6b906e5628..cb40f2e8d3d 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 43c8f5a8604..5eb17a38e6c 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 fe1bb274882..b648e40ee57 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 81f89fb5e89..0037f313775 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 ba6c9f21dd1..90bd405bec9 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 df9fae28918..8751e3f61ef 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 f82a717e439..ca2b604bdc2 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 2fd878773bb..3f39de593f1 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 38416a396a2..8f3aa5c8826 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 e80aebd1bb4..cc8d4dc9649 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 f281ad154fc..055cb0540a3 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 bd6b47e17f3..0997887d027 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 31611b75c22..6896fe85923 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 dba465efd86..924f38d3f93 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 d4b0d750d7b..febf4f6c4e4 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 057ed4ca3bb..54e57104a9a 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 39029959c4c..98ba11536aa 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 aa648c99092..4f563d54ac0 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 eb4c2bca212..3e74b864854 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 ad369aba9e1..2da91f339bc 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 21bf975dca9..ed06a377377 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 336fdc4b633..316f95333ec 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 529b93d4f79..f1583f30b52 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 7403f746f14..5ebda337f11 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 0ceafc257eb..2267b0ccdd9 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 d3fd8fe842c..50f575f954b 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 636fed78329..0b287e79bd3 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 cc2dd601f5d..f04053fcc43 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 6d5a9e08985..0e852033cdc 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 78664076a60..70def6928dc 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 100cf675960..f670b73aca6 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 9f35dcdc761..abeea9f8f9d 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 5f26d5f2e6d..0c7b3ad230a 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 e487e732159..e19e92eb193 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 69b444fba79..fa9872a2133 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 a06ef7e2182..d9c908f94f9 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 4b5ed1af16b..2fca4c0dc4d 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 688342d02b8..8a1264fe6c1 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 efe52667e4e..7d6dc6b457f 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 d1631f84d92..ee4e7df8257 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 bb5ff35a537..52fe3645e83 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 9550b5f0421..dbecdeb23cd 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/mmword.md b/docs/assembler/masm/mmword.md index 563ae8e444f..98ca8629498 100644 --- a/docs/assembler/masm/mmword.md +++ b/docs/assembler/masm/mmword.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: MMWORD" title: "MMWORD" -ms.date: "12/17/2019" +description: "Learn more about: MMWORD" +ms.date: 12/17/2019 f1_keywords: ["MMWORD"] helpviewer_keywords: ["MMWORD directive"] -ms.assetid: b4c5a104-9078-4fb4-afc3-d1e63abe562a --- # MMWORD @@ -32,6 +31,6 @@ While both instructions work on 64-bit operands, **QWORD** is the type for 64-bi movq mm0, mmword ptr [ebx] ``` -## See Also +## See also [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/masm/option-avxencoding-masm.md b/docs/assembler/masm/option-avxencoding-masm.md index c019dc5f8cb..806b205a3bf 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/option-language-masm.md b/docs/assembler/masm/option-language-masm.md index bc258e08f1b..1ba3c6cd7d6 100644 --- a/docs/assembler/masm/option-language-masm.md +++ b/docs/assembler/masm/option-language-masm.md @@ -1,6 +1,6 @@ --- -description: Learn more about the alternatives for the OPTION LANGUAGE directive title: "OPTION LANGUAGE" +description: "Learn more about the alternatives for the OPTION LANGUAGE directive" ms.date: 09/21/2021 f1_keywords: ["language"] helpviewer_keywords: ["OPTION LANGUAGE directive"] @@ -20,11 +20,11 @@ Available languages include: :::row::: :::column span=""::: **`C`**\ - **`SYSCALL`**\ + **`SYSCALL`** :::column-end::: :::column span=""::: **`STDCALL`**\ - **`PASCAL`**\ + **`PASCAL`** :::column-end::: :::column span=""::: **`FORTRAN`**\ diff --git a/docs/assembler/masm/proc.md b/docs/assembler/masm/proc.md index 9eb65fc3770..222b437a4a9 100644 --- a/docs/assembler/masm/proc.md +++ b/docs/assembler/masm/proc.md @@ -12,8 +12,8 @@ Marks start and end of a procedure block called *label*. The statements in the b ## Syntax -> *label* **PROC** ⟦*distance*⟧ ⟦*language-type*⟧ ⟦ **PUBLIC** | **PRIVATE** | **EXPORT** ⟧ ⟦__\<__*prologuearg*__>__⟧ ⟦**USES** *reglist*⟧ ⟦__,__ *parameter* ⟦__:__*tag*⟧ ...⟧\ -> ⟦**FRAME** ⟦__:__*ehandler-address*⟧ ⟧\ +> *label* `PROC` ⟦*distance*⟧ ⟦*language-type*⟧ ⟦ `PUBLIC` | `PRIVATE` | `EXPORT` ⟧ ⟦__\<__*prologuearg*__>__⟧ ⟦`USES` *reglist*⟧ ⟦__,__ *parameter* ⟦__:__*tag*⟧ ...⟧\ +> ⟦`FRAME` ⟦__:__*ehandler-address*⟧ ⟧\ > *statements*\ > *label* **ENDP** @@ -21,9 +21,9 @@ Marks start and end of a procedure block called *label*. The statements in the b The ⟦*distance*⟧ and ⟦*language-type*⟧ arguments are valid only in 32-bit MASM. -⟦**FRAME** ⟦__:__*ehandler-address*⟧ ⟧ is only valid with ml64.exe, and causes MASM to generate a function table entry in .pdata and unwind information in .xdata for a function's structured exception handling unwind behavior. +⟦`FRAME` ⟦__:__*ehandler-address*⟧ ⟧ is only valid with ml64.exe, and causes MASM to generate a function table entry in .pdata and unwind information in .xdata for a function's structured exception handling unwind behavior. -When the **FRAME** attribute is used, it must be followed by an [.ENDPROLOG](dot-endprolog.md) directive. +When the `FRAME` attribute is used, it must be followed by an [.ENDPROLOG](dot-endprolog.md) directive. See [MASM for x64 (ml64.exe)](masm-for-x64-ml64-exe.md) for more information on using ml64.exe. @@ -49,7 +49,7 @@ _text ENDS END ``` -The above code will emit the following function table and unwind information: +The above code emits the following function table and unwind information: ```Output FileHeader->Machine 34404 diff --git a/docs/assembler/masm/processor-manufacturer-programming-manuals.md b/docs/assembler/masm/processor-manufacturer-programming-manuals.md index 1414153abd0..4774fdeeb77 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 2e19584edd1..9051b7fae9b 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 b59e41f2247..a119b8eb142 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/assembler/masm/symbols-reference.md b/docs/assembler/masm/symbols-reference.md index c7fd4af9f81..a6c296fc5c1 100644 --- a/docs/assembler/masm/symbols-reference.md +++ b/docs/assembler/masm/symbols-reference.md @@ -1,9 +1,9 @@ --- description: "Learn more about: Symbols reference" title: "Symbols reference" -ms.date: 07/15/2020 +ms.date: 05/04/2026 helpviewer_keywords: ["MASM (Microsoft Macro Assembler), symbols reference"] -ms.assetid: 96ed59cc-dafa-4299-bb2e-9c7c3f496491 +ai-usage: ai-assisted --- # Symbols reference @@ -30,6 +30,9 @@ ms.assetid: 96ed59cc-dafa-4299-bb2e-9c7c3f496491 :::column span=""::: [`@Interface`](at-interface.md) :::column-end::: + :::column span=""::: + [`@UnwindVersion`](at-unwindversion.md) + :::column-end::: :::column span=""::: [`@Version`](at-version.md) :::column-end::: diff --git a/docs/assembler/masm/xmmword.md b/docs/assembler/masm/xmmword.md index 3722fd23f48..9e4ef7c064e 100644 --- a/docs/assembler/masm/xmmword.md +++ b/docs/assembler/masm/xmmword.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: XMMWORD" title: "XMMWORD" -ms.date: "12/17/2019" +description: "Learn more about: XMMWORD" +ms.date: 12/17/2019 f1_keywords: ["XMMWORD"] helpviewer_keywords: ["XMMWORD directive"] -ms.assetid: 18026d32-5cab-403e-ad7e-382fb41aa9b8 --- # XMMWORD @@ -24,6 +23,6 @@ Used for 128-bit multimedia operands with MMX and SSE (XMM) instructions. movdqa xmm0, xmmword ptr [ebx] ``` -## See Also +## See also [MASM BNF Grammar](masm-bnf-grammar.md) diff --git a/docs/assembler/toc.yml b/docs/assembler/toc.yml index 8f8b923a9c3..1e90a1e19d3 100644 --- a/docs/assembler/toc.yml +++ b/docs/assembler/toc.yml @@ -117,6 +117,8 @@ items: href: ../assembler/masm/dot-alpha.md - name: ASSUME href: ../assembler/masm/assume.md + - name: .BEGINEPILOG + href: ../assembler/masm/dot-beginepilog.md - name: .BREAK href: ../assembler/masm/dot-break.md - name: BYTE @@ -171,6 +173,8 @@ items: href: ../assembler/masm/end-masm.md - name: .ENDIF href: ../assembler/masm/dot-endif.md + - name: .ENDEPILOG + href: ../assembler/masm/dot-endepilog.md - name: ENDM href: ../assembler/masm/endm.md - name: ENDP @@ -225,6 +229,8 @@ items: href: ../assembler/masm/forc.md - name: .FPO href: ../assembler/masm/dot-fpo.md + - name: .FREESTACK + href: ../assembler/masm/dot-freestack.md - name: FWORD href: ../assembler/masm/fword.md - name: GOTO @@ -315,8 +321,14 @@ items: href: ../assembler/masm/oword.md - name: PAGE href: ../assembler/masm/page.md + - name: .POP2REG + href: ../assembler/masm/dot-pop2reg.md - name: POPCONTEXT href: ../assembler/masm/popcontext.md + - name: .POPREG + href: ../assembler/masm/dot-popreg.md + - name: .POPFRAME + href: ../assembler/masm/dot-popframe.md - name: PROC href: ../assembler/masm/proc.md - name: PROTO @@ -325,6 +337,8 @@ items: href: ../assembler/masm/public-masm.md - name: PURGE href: ../assembler/masm/purge.md + - name: .PUSH2REG + href: ../assembler/masm/dot-push2reg.md - name: PUSHCONTEXT href: ../assembler/masm/pushcontext.md - name: .PUSHFRAME @@ -349,6 +363,10 @@ items: href: ../assembler/masm/repeat.md - name: REPT href: ../assembler/masm/rept.md + - name: .RESTOREREG + href: ../assembler/masm/dot-restorereg.md + - name: .RESTOREXMM128 + href: ../assembler/masm/dot-restorexmm128.md - name: .SAFESEH href: ../assembler/masm/dot-safeseh.md - name: .SALL @@ -401,6 +419,8 @@ items: href: ../assembler/masm/typedef-masm.md - name: UNION href: ../assembler/masm/union.md + - name: .UNSETFRAME + href: ../assembler/masm/dot-unsetframe.md - name: .UNTIL href: ../assembler/masm/dot-until.md - name: .UNTILCXZ @@ -479,6 +499,8 @@ items: href: ../assembler/masm/at-substr.md - name: "@Time" href: ../assembler/masm/at-time.md + - name: "@UnwindVersion" + href: ../assembler/masm/at-unwindversion.md - name: "@Version" href: ../assembler/masm/at-version.md - name: "@WordSize" diff --git a/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md b/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md index 73a93334f33..d1c1db36c70 100644 --- a/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md +++ b/docs/atl-mfc-shared/allocating-and-releasing-memory-for-a-bstr.md @@ -4,10 +4,11 @@ title: "Allocating and Releasing Memory for a BSTR" ms.date: "11/04/2016" f1_keywords: ["bstr"] helpviewer_keywords: ["BSTRs, memory allocation", "memory deallocation, string memory", "memory [C++], releasing", "memory allocation, BSTRs", "memory deallocation, BSTR memory", "strings [C++], releasing"] -ms.assetid: 98041e29-3442-4a02-b425-7a4a13e9cc84 --- # Allocating and Releasing Memory for a `BSTR` +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + When you create `BSTR`s and pass them between COM objects, you must take care in treating the memory they use in order to avoid memory leaks. When a `BSTR` stays within an interface, you must free its memory when you are done with it. However, when a `BSTR` passes out of an interface, the receiving object takes responsibility for its memory management. In general, the rules for allocating and releasing memory allocated for `BSTR`s are as follows: @@ -15,13 +16,13 @@ In general, the rules for allocating and releasing memory allocated for `BSTR`s - When you call into a function that expects a `BSTR` argument, you must allocate the memory for the `BSTR` before the call and release it afterwards. For example: [!code-cpp[NVC_ATLMFC_Utilities#192](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_1.cpp)] - +   [!code-cpp[NVC_ATLMFC_Utilities#193](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_2.cpp)] - When you call into a function that returns a `BSTR`, you must free the string yourself. For example: [!code-cpp[NVC_ATLMFC_Utilities#194](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_3.cpp)] - +   [!code-cpp[NVC_ATLMFC_Utilities#195](../atl-mfc-shared/codesnippet/cpp/allocating-and-releasing-memory-for-a-bstr_4.cpp)] - When you implement a function that returns a `BSTR`, allocate the string but do not free it. The receiving function releases the memory. For example: diff --git a/docs/atl-mfc-shared/atl-mfc-concepts.md b/docs/atl-mfc-shared/atl-mfc-concepts.md index 6227696c2bb..c2d4845da77 100644 --- a/docs/atl-mfc-shared/atl-mfc-concepts.md +++ b/docs/atl-mfc-shared/atl-mfc-concepts.md @@ -3,15 +3,16 @@ description: "Learn more about: ATL/MFC Concepts" title: "ATL-MFC Concepts" ms.date: "11/04/2016" helpviewer_keywords: ["MFC", "ATL"] -ms.assetid: 4d973f56-8730-4e0b-9522-b5f43bc4548d --- # ATL/MFC Concepts +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + This section provides conceptual and task-based topics to help you program using the classes shared between Active Template Library (ATL) and Microsoft Foundation Class (MFC) Library. ## In This Section -[Strings (ATL/MFC)](../atl-mfc-shared/strings-atl-mfc.md)
+[Strings (ATL/MFC)](../atl-mfc-shared/strings-atl-mfc.md)\ Describes how to manage string data in applications. ## See also diff --git a/docs/atl-mfc-shared/atl-mfc-shared-classes.md b/docs/atl-mfc-shared/atl-mfc-shared-classes.md index 4a0a3edbac8..52b69d1e957 100644 --- a/docs/atl-mfc-shared/atl-mfc-shared-classes.md +++ b/docs/atl-mfc-shared/atl-mfc-shared-classes.md @@ -3,13 +3,14 @@ description: "Learn more about: ATL/MFC Shared Classes" title: "ATL-MFC Shared Classes" ms.custom: "index-page" ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: ["vc.classes.shared"] helpviewer_keywords: ["CPoint class, shared class", "CFileTimeSpan class, shared class", "COleDateTime class, shared class", "CFixedStringT class, shared class", "CStrBufT class, shared class", "CFileTime class, shared class", "CRect class, shared class", "CSimpleStringT class, shared class", "CStringT class, shared class", "CSize class, shared class", "CStringData class, shared class", "IAtlStringMgr class, shared class", "shared classes, MFC and ATL", "COleDateTimeSpan class, shared class", "CString objects, shared class", "shared classes"] -ms.assetid: e13aaac3-21ec-4f4d-8834-432b40fde544 --- # ATL/MFC Shared Classes +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + These utility classes can be used in any native C++ project without requiring any MFC DLL. ## In This Section diff --git a/docs/atl-mfc-shared/avoidance-of-heap-contention.md b/docs/atl-mfc-shared/avoidance-of-heap-contention.md index 6639bbbe493..aec032124dc 100644 --- a/docs/atl-mfc-shared/avoidance-of-heap-contention.md +++ b/docs/atl-mfc-shared/avoidance-of-heap-contention.md @@ -3,10 +3,11 @@ description: "Learn more about: Avoidance of Heap Contention" title: "Avoidance of Heap Contention" ms.date: "11/04/2016" helpviewer_keywords: ["heap contention"] -ms.assetid: 797129d7-5f8c-4b0e-8974-bb93217e9ab5 --- # Avoidance of Heap Contention +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + The default string managers provided by MFC and ATL are simple wrappers on top of a global heap. This global heap is fully thread-safe, meaning that multiple threads can allocate and free memory from it simultaneously without corrupting the heap. To help provide thread safety, the heap has to serialize access to itself. This is usually accomplished with a critical section or similar locking mechanism. Whenever two threads try to access the heap simultaneously, one thread is blocked until the other thread's request is finished. For many applications, this situation rarely occurs and the performance impact of the heap's locking mechanism is negligible. However, for applications that frequently access the heap from multiple threads contention for the heap's lock can cause the application to run slower than if it were single-threaded (even on machines with multiple CPUs). Applications that use [CStringT](../atl-mfc-shared/reference/cstringt-class.md) are especially susceptible to heap contention because operations on `CStringT` objects frequently require reallocation of the string buffer. diff --git a/docs/atl-mfc-shared/basic-cstring-operations.md b/docs/atl-mfc-shared/basic-cstring-operations.md index 41926fe05be..243f52b3271 100644 --- a/docs/atl-mfc-shared/basic-cstring-operations.md +++ b/docs/atl-mfc-shared/basic-cstring-operations.md @@ -1,12 +1,13 @@ --- -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 +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + This topic explains the following basic [CString](../atl-mfc-shared/reference/cstringt-class.md) operations: - [Creating CString objects from standard C literal strings](#_core_creating_cstring_objects_from_standard_c_literal_strings) @@ -19,7 +20,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/cfixedstringt-example-of-a-custom-string-manager.md b/docs/atl-mfc-shared/cfixedstringt-example-of-a-custom-string-manager.md index 11094716d1b..b525fdae33f 100644 --- a/docs/atl-mfc-shared/cfixedstringt-example-of-a-custom-string-manager.md +++ b/docs/atl-mfc-shared/cfixedstringt-example-of-a-custom-string-manager.md @@ -3,10 +3,11 @@ description: "Learn more about: CFixedStringT: Example of a Custom String Manage title: "CFixedStringT: Example of a Custom String Manager" ms.date: "11/04/2016" helpviewer_keywords: ["CFixedStringT class, using a custom string manager"] -ms.assetid: 1cf11fd7-51b8-4b94-87af-02bc25f47dd6 --- # CFixedStringT: Example of a Custom String Manager +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + The ATL library implements one example of a custom string manager used by class [CFixedStringT](../atl-mfc-shared/reference/cfixedstringt-class.md), called **CFixedStringMgr**. `CFixedStringT` is derived from [CStringT](../atl-mfc-shared/reference/cstringt-class.md) and implements a string that allocates its character data as part of the `CFixedStringT` object itself as long as the string is less than the length specified by the `t_nChars` template parameter of `CFixedStringT`. With this approach, the string does not need the heap at all, unless the length of the string grows beyond the size of the fixed buffer. Because `CFixedStringT` does not always use a heap to allocate its string data, it cannot use `CAtlStringMgr` as its string manager. It uses a custom string manager (`CFixedStringMgr`), implementing the [IAtlStringMgr](../atl-mfc-shared/reference/iatlstringmgr-class.md) interface. This interface is discussed in [Implementation of a Custom String Manager (Advanced Method)](../atl-mfc-shared/implementation-of-a-custom-string-manager-advanced-method.md). The constructor for `CFixedStringMgr` takes three parameters: diff --git a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp index 78a3ad3444f..2b6ff825fd2 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_2.cpp @@ -1,5 +1,5 @@ // OEM character 252 on most IBM-compatible computers in - // Western countries/regions is superscript n, as in 2^n. + // many countries/regions is superscript n, as in 2^n. // Converting it to the ANSI English charset results in a // normal character 'n', which is the closest possible // representation. @@ -14,4 +14,4 @@ // the character's value truly was. str.AnsiToOem(); ASSERT(str[0] != 252); - ASSERT(str[0] == 'n'); \ No newline at end of file + ASSERT(str[0] == 'n'); diff --git a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_37.cpp index e9d808179ae..2dd71b86509 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/codesnippet/CPP/cstringt-class_39.cpp b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_39.cpp index d2b2eb6cf39..8886e69d9f7 100644 --- a/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_39.cpp +++ b/docs/atl-mfc-shared/codesnippet/CPP/cstringt-class_39.cpp @@ -8,4 +8,4 @@ { _tprintf_s(_T("Resulting token: %s\n"), resToken); resToken = str.Tokenize(_T("% #"), curPos); - }; \ No newline at end of file + } \ 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 7c5a6a469e3..23f1483655f 100644 --- a/docs/atl-mfc-shared/cstring-argument-passing.md +++ b/docs/atl-mfc-shared/cstring-argument-passing.md @@ -6,6 +6,8 @@ helpviewer_keywords: ["strings [C++], as function input/output", "argument passi --- # `CString` Argument Passing +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + This article explains how to pass [`CString`](../atl-mfc-shared/reference/cstringt-class.md) objects to functions and how to return `CString` objects from functions. ## `CString` Argument-Passing Conventions @@ -14,7 +16,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. @@ -25,7 +27,7 @@ If the string contents are to be changed by a function, declare the parameter as Typically you can return `CString` objects from functions because `CString` objects follow value semantics like primitive types. To return a read-only string, use a constant `CString` reference (`const CString&`). The following example illustrates the use of `CString` parameters and return types: [!code-cpp[NVC_ATLMFC_Utilities#197](../atl-mfc-shared/codesnippet/cpp/cstring-argument-passing_1.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#198](../atl-mfc-shared/codesnippet/cpp/cstring-argument-passing_2.cpp)] ## See also diff --git a/docs/atl-mfc-shared/cstring-exception-cleanup.md b/docs/atl-mfc-shared/cstring-exception-cleanup.md index f9571eb6993..3a5273217b2 100644 --- a/docs/atl-mfc-shared/cstring-exception-cleanup.md +++ b/docs/atl-mfc-shared/cstring-exception-cleanup.md @@ -3,10 +3,11 @@ description: "Learn more about: CString Exception Cleanup" title: "CString Exception Cleanup" ms.date: "11/04/2016" helpviewer_keywords: ["CString objects, exceptions", "exception handling, cleanup code"] -ms.assetid: 28b9ce70-be63-4a0d-92a8-44bbfbc95e83 --- # CString Exception Cleanup +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + In previous versions of MFC, it was important that you clean up [CString](../atl-mfc-shared/reference/cstringt-class.md) objects after use. With MFC version 3.0 and later, explicit cleanup is no longer necessary. Under the C++ exception handling mechanism that MFC now uses, you do not have to worry about cleanup after an exception. For a description of how C++ "unwinds" the stack after an exception is caught, see [the try, catch, and throw statements](../cpp/try-throw-and-catch-statements-cpp.md). Even if you use the MFC **TRY**/**CATCH** macros instead of the C++ keywords **`try`** and **`catch`**, MFC uses the C++ exception mechanism underneath, so you still do not need to clean up explicitly. diff --git a/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md b/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md index c90c04bf1b1..8629690cd0a 100644 --- a/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md +++ b/docs/atl-mfc-shared/cstring-operations-relating-to-c-style-strings.md @@ -3,10 +3,11 @@ description: "Learn more about: CString Operations Relating to C-Style Strings" title: "CString Operations Relating to C-Style Strings" ms.date: "11/04/2016" helpviewer_keywords: ["CString objects, basic operations", "MFC [C++], string handling class", "string conversion [C++], C-style strings", "strings [C++], string operations", "standard run-time library string functions", "null values, Null-terminated string conversion", "string functions", "strings [C++], in C", "string arguments", "C-style strings", "strings [C++], class CString", "casting CString objects"] -ms.assetid: 5048de8a-5298-4891-b8a0-c554b5a3ac1b --- # `CString` Operations Relating to C-Style Strings +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + A [`CString`](../atl-mfc-shared/using-cstring.md) object contains character string data. `CString` inherits the set of the [methods and operators](../atl-mfc-shared/reference/cstringt-class.md) that are defined in the class template [`CStringT`](../atl-mfc-shared/reference/cstringt-class.md) to work with string data. (`CString` is a **`typedef`** that specializes `CStringT` to work with the kind of character data that `CString` supports.) `CString` does not store character data internally as a C-style null-terminated string. Instead, `CString` tracks the length of character data so that it can more securely watch the data and the space it requires. diff --git a/docs/atl-mfc-shared/cstring-semantics.md b/docs/atl-mfc-shared/cstring-semantics.md index a8b283511b6..a978cc1e251 100644 --- a/docs/atl-mfc-shared/cstring-semantics.md +++ b/docs/atl-mfc-shared/cstring-semantics.md @@ -3,10 +3,11 @@ description: "Learn more about: CString Semantics" title: "CString Semantics" ms.date: "11/04/2016" helpviewer_keywords: ["semantics in Cstring", "CString objects, assignment semantics", "assignment statements, assigning CString objects"] -ms.assetid: d4023480-526f-499a-85f6-324b4de5b85f --- # CString Semantics +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + Even though [CString](../atl-mfc-shared/reference/cstringt-class.md) objects are dynamic objects that can grow, they act like built-in primitive types and simple classes. Each `CString` object represents a unique value. `CString` objects should be thought of as the actual strings rather than as pointers to strings. You can assign one `CString` object to another. However, when you modify one of the two `CString` objects, the other `CString` object is not modified, as shown by the following example: diff --git a/docs/atl-mfc-shared/date-and-time.md b/docs/atl-mfc-shared/date-and-time.md index 6285d86cb2f..9f7eec080cc 100644 --- a/docs/atl-mfc-shared/date-and-time.md +++ b/docs/atl-mfc-shared/date-and-time.md @@ -6,6 +6,8 @@ helpviewer_keywords: ["time, MFC programming", "time", "MFC, date and time", "da --- # Date and Time +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + MFC supports several different ways of working with dates and times: - Support for the Automation [`DATE` data type](../atl-mfc-shared/date-type.md). `DATE` supports date, time, and date/time values. The [`COleDateTime`](../atl-mfc-shared/reference/coledatetime-class.md) and [`COleDateTimeSpan`](../atl-mfc-shared/reference/coledatetimespan-class.md) classes encapsulate this functionality. They work with the [`COleVariant`](../mfc/reference/colevariant-class.md) class using Automation support. diff --git a/docs/atl-mfc-shared/date-type.md b/docs/atl-mfc-shared/date-type.md index 51909869c5b..6c9e9c6c7fb 100644 --- a/docs/atl-mfc-shared/date-type.md +++ b/docs/atl-mfc-shared/date-type.md @@ -4,10 +4,11 @@ title: "DATE Type" ms.date: "11/04/2016" f1_keywords: ["DATE"] helpviewer_keywords: ["Date data type, implementing", "Date data type", "DATE type", "Date data type, about Date data type", "MFC, date and time", "hour values representation"] -ms.assetid: 695853ed-b614-4575-b793-b8c287372038 --- # DATE Type +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + The DATE type is implemented using an 8-byte floating-point number. Days are represented by whole number increments starting with 30 December 1899, midnight as time zero. Hour values are expressed as the absolute value of the fractional part of the number. The following table illustrates several dates along with their DATE type numeric equivalent: |Date and time|Representation| 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 43fae08362e..c8e98da7fe7 100644 --- a/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md +++ b/docs/atl-mfc-shared/exporting-string-classes-using-cstringt.md @@ -3,10 +3,11 @@ description: "Learn more about: Exporting String Classes Using CStringT" title: "Exporting String Classes Using CStringT" ms.date: "11/04/2016" helpviewer_keywords: ["CStringT class, exporting strings"] -ms.assetid: bdfc441e-8d2a-461c-9885-46178066c09f --- # Exporting String Classes Using CStringT +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + In the past, MFC developers have derived from `CString` to specialize their own string classes. In Microsoft Visual C++.NET (MFC 8.0), the [CString](../atl-mfc-shared/using-cstring.md) class was superseded by a template class called [CStringT](../atl-mfc-shared/reference/cstringt-class.md). This provided several benefits: - It allowed the MFC `CString` class to be used in ATL projects without linking in the larger MFC static library or DLL. @@ -27,7 +28,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/implementation-of-a-custom-string-manager-advanced-method.md b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-advanced-method.md index 55fe40e157f..0ea1922d71c 100644 --- a/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-advanced-method.md +++ b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-advanced-method.md @@ -3,10 +3,11 @@ description: "Learn more about: Implementation of a Custom String Manager (Advan title: "Implementation of a Custom String Manager (Advanced Method)" ms.date: "11/04/2016" helpviewer_keywords: ["IAtlStringMgr class, using"] -ms.assetid: 64ab7da9-47c1-4c4a-9cd7-4cc37e7f3f57 --- # Implementation of a Custom String Manager (Advanced Method) +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + In specialized situations, you might want to implement a custom string manager that does more than just change which heap is used to allocate memory. In this situation, you must manually implement the [IAtlStringMgr](../atl-mfc-shared/reference/iatlstringmgr-class.md) interface as your custom string manager. In order to do this, it is important to first understand how [CStringT](../atl-mfc-shared/reference/cstringt-class.md) uses that interface to manage its string data. Every instance of `CStringT` has a pointer to a [CStringData](../atl-mfc-shared/reference/cstringdata-class.md) structure. This variable-length structure contains important information about the string (such as length), as well as the actual character data for the string. Every custom string manager is responsible for allocating and freeing these structures at the request of `CStringT`. diff --git a/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md index 2e91251aaa2..ff0ead0d8cd 100644 --- a/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md +++ b/docs/atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md @@ -3,10 +3,11 @@ description: "Learn more about: Implementation of a Custom String Manager (Basic title: "Implementation of a Custom String Manager (Basic Method)" ms.date: "11/04/2016" helpviewer_keywords: ["IAtlStringMgr class, using"] -ms.assetid: eac5d13e-cbb4-4e82-b01e-f5f2dbcb962a --- # Implementation of a Custom String Manager (Basic Method) +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + The easiest way to customize the memory allocation scheme for string data is to use the ATL-provided `CAtlStringMgr` class but provide your own memory allocation routines. The constructor for `CAtlStringMgr` takes a single parameter: a pointer to an `IAtlMemMgr` object. `IAtlMemMgr` is an abstract base class that provides a generic interface to a heap. Using the `IAtlMemMgr` interface, the `CAtlStringMgr` allocates, reallocates, and frees the memory used to store string data. You can either implement the `IAtlMemMgr` interface yourself, or use one of the five ATL-provided memory manager classes. The ATL-provided memory managers simply wrap existing memory allocation facilities: - [CCRTHeap](../atl/reference/ccrtheap-class.md) Wraps the standard CRT heap functions ([malloc](../c-runtime-library/reference/malloc.md), [free](../c-runtime-library/reference/free.md), and [realloc](../c-runtime-library/reference/realloc.md)) diff --git a/docs/atl-mfc-shared/includes/lifecycle-note.md b/docs/atl-mfc-shared/includes/lifecycle-note.md new file mode 100644 index 00000000000..6725bfc524e --- /dev/null +++ b/docs/atl-mfc-shared/includes/lifecycle-note.md @@ -0,0 +1,2 @@ +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library and Active Template Library (ATL) continue to be supported. However, we're no longer adding features or updating the documentation. \ No newline at end of file diff --git a/docs/atl-mfc-shared/memory-management-with-cstringt.md b/docs/atl-mfc-shared/memory-management-with-cstringt.md index c0df6f2ceb3..104e67a46e7 100644 --- a/docs/atl-mfc-shared/memory-management-with-cstringt.md +++ b/docs/atl-mfc-shared/memory-management-with-cstringt.md @@ -3,10 +3,11 @@ description: "Learn more about: Memory Management with CStringT" title: "Memory Management with CStringT" ms.date: "11/04/2016" helpviewer_keywords: ["CString objects, memory management", "memory [C++], usage", "IAtlStringMgr class, using", "strings [C++], custom memory management", "CFixedStringT class, description of", "strings [C++], memory management", "CStringT class, memory management"] -ms.assetid: 88b8342d-19b5-48c4-9cf6-e4c44cece21e --- # Memory Management with CStringT +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + Class [CStringT](../atl-mfc-shared/reference/cstringt-class.md) is a template class used to manipulate variable-length character strings. The memory to hold these strings is allocated and released through a string manager object, associated with each instance of `CStringT`. MFC and ATL provide default instantiations of `CStringT`, called `CString`, `CStringA`, and `CStringW`, which manipulate strings of different character types. These character types are of type TCHAR, **`char`**, and **`wchar_t`**, respectively. These default string types use a string manager that allocates memory from the process heap (in ATL) or the CRT heap (in MFC). For typical applications, this memory allocation scheme is sufficient. However, for code making intensive use of strings (or multithreaded code) the default memory managers may not perform optimally. This topic describes how to override the default memory management behavior of `CStringT`, creating allocators specifically optimized for the task at hand. - [Implementation of a Custom String Manager (Basic Method)](../atl-mfc-shared/implementation-of-a-custom-string-manager-basic-method.md) diff --git a/docs/atl-mfc-shared/reference/cfiletime-class.md b/docs/atl-mfc-shared/reference/cfiletime-class.md index 35d7d8dc48e..abc271c7199 100644 --- a/docs/atl-mfc-shared/reference/cfiletime-class.md +++ b/docs/atl-mfc-shared/reference/cfiletime-class.md @@ -4,10 +4,11 @@ title: "CFileTime class" ms.date: "10/18/2018" f1_keywords: ["CFileTime", "ATLTIME/ATL::CFileTime", "ATLTIME/ATL::CFileTime::CFileTime", "ATLTIME/ATL::CFileTime::GetCurrentTime", "ATLTIME/ATL::CFileTime::GetTime", "ATLTIME/ATL::CFileTime::LocalToUTC", "ATLTIME/ATL::CFileTime::SetTime", "ATLTIME/ATL::CFileTime::UTCToLocal", "ATLTIME/ATL::CFileTime::Day", "ATLTIME/ATL::CFileTime::Hour", "ATLTIME/ATL::CFileTime::Millisecond", "ATLTIME/ATL::CFileTime::Minute", "ATLTIME/ATL::CFileTime::Second", "ATLTIME/ATL::CFileTime::Week"] helpviewer_keywords: ["CFileTime class", "shared classes, CFileTime"] -ms.assetid: 1a358a65-1383-4124-b0d4-59b026e6860f --- # `CFileTime` class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for managing the date and time values associated with a file. ## Syntax diff --git a/docs/atl-mfc-shared/reference/cfiletimespan-class.md b/docs/atl-mfc-shared/reference/cfiletimespan-class.md index 62a26f382ec..b972803f581 100644 --- a/docs/atl-mfc-shared/reference/cfiletimespan-class.md +++ b/docs/atl-mfc-shared/reference/cfiletimespan-class.md @@ -4,10 +4,11 @@ description: "The Active Template Library (ATL) and Microsoft Foundation Classes ms.date: "01/10/2020" f1_keywords: ["CFileTimeSpan", "ATLTIME/ATL::CFileTimeSpan", "ATLTIME/ATL::CFileTimeSpan::CFileTimeSpan", "ATLTIME/ATL::CFileTimeSpan::GetTimeSpan", "ATLTIME/ATL::CFileTimeSpan::SetTimeSpan"] helpviewer_keywords: ["shared classes, CFileTimeSpan", "CFileTimeSpan class"] -ms.assetid: 5856fb39-9c82-4027-8ccf-8760890491ec --- # `CFileTimeSpan` class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for managing relative date and time values associated with a file. ## Syntax diff --git a/docs/atl-mfc-shared/reference/cfixedstringt-class.md b/docs/atl-mfc-shared/reference/cfixedstringt-class.md index f550ca44b9d..6109dc0c1a6 100644 --- a/docs/atl-mfc-shared/reference/cfixedstringt-class.md +++ b/docs/atl-mfc-shared/reference/cfixedstringt-class.md @@ -4,15 +4,16 @@ title: "CFixedStringT Class" ms.date: "03/27/2019" f1_keywords: ["CFixedStringT", "CSTRINGT/ATL::CFixedStringT", "CSTRINGT/ATL::CFixedStringT::CFixedStringT"] helpviewer_keywords: ["CFixedStringT class", "shared classes, CFixedStringT"] -ms.assetid: 6d4171ba-3104-493a-a6cc-d515f4ba9a4b --- # CFixedStringT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a string object with a fixed character buffer. ## Syntax -``` +```cpp template class CFixedStringT : private CFixedStringMgr, public StringType ``` @@ -69,7 +70,7 @@ For more information on the customization of `CFixedStringT` and memory manageme Constructs a `CFixedStringT` object. -``` +```cpp CFixedStringT() throw(); explicit CFixedStringT(IAtlStringMgr* pStringMgr) throw(); CFixedStringT(const CFixedStringT& strSrc); @@ -98,7 +99,7 @@ Because the constructors copy the input data into new allocated storage, you sho Reinitializes an existing `CFixedStringT` object with new data. -``` +```cpp CFixedStringT& operator=( const CFixedStringT& strSrc); CFixedStringT& operator=(const char* pszSrc); diff --git a/docs/atl-mfc-shared/reference/cimage-class.md b/docs/atl-mfc-shared/reference/cimage-class.md index b8a69263d2b..311a44e2811 100644 --- a/docs/atl-mfc-shared/reference/cimage-class.md +++ b/docs/atl-mfc-shared/reference/cimage-class.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: CImage Class" title: "CImage Class" -ms.date: "08/19/2019" +description: "Learn more about: CImage Class" +ms.date: 08/19/2019 f1_keywords: ["CImage", "ATLIMAGE/ATL::CImage", "ATLIMAGE/ATL::CImage::CImage", "ATLIMAGE/ATL::CImage::AlphaBlend", "ATLIMAGE/ATL::CImage::Attach", "ATLIMAGE/ATL::CImage::BitBlt", "ATLIMAGE/ATL::CImage::Create", "ATLIMAGE/ATL::CImage::CreateEx", "ATLIMAGE/ATL::CImage::Destroy", "ATLIMAGE/ATL::CImage::Detach", "ATLIMAGE/ATL::CImage::Draw", "ATLIMAGE/ATL::CImage::GetBits", "ATLIMAGE/ATL::CImage::GetBPP", "ATLIMAGE/ATL::CImage::GetColorTable", "ATLIMAGE/ATL::CImage::GetDC", "ATLIMAGE/ATL::CImage::GetExporterFilterString", "ATLIMAGE/ATL::CImage::GetHeight", "ATLIMAGE/ATL::CImage::GetImporterFilterString", "ATLIMAGE/ATL::CImage::GetMaxColorTableEntries", "ATLIMAGE/ATL::CImage::GetPitch", "ATLIMAGE/ATL::CImage::GetPixel", "ATLIMAGE/ATL::CImage::GetPixelAddress", "ATLIMAGE/ATL::CImage::GetTransparentColor", "ATLIMAGE/ATL::CImage::GetWidth", "ATLIMAGE/ATL::CImage::IsDIBSection", "ATLIMAGE/ATL::CImage::IsIndexed", "ATLIMAGE/ATL::CImage::IsNull", "ATLIMAGE/ATL::CImage::IsTransparencySupported", "ATLIMAGE/ATL::CImage::Load", "ATLIMAGE/ATL::CImage::LoadFromResource", "ATLIMAGE/ATL::CImage::MaskBlt", "ATLIMAGE/ATL::CImage::PlgBlt", "ATLIMAGE/ATL::CImage::ReleaseDC", "ATLIMAGE/ATL::CImage::ReleaseGDIPlus", "ATLIMAGE/ATL::CImage::Save", "ATLIMAGE/ATL::CImage::SetColorTable", "ATLIMAGE/ATL::CImage::SetPixel", "ATLIMAGE/ATL::CImage::SetPixelIndexed", "ATLIMAGE/ATL::CImage::SetPixelRGB", "ATLIMAGE/ATL::CImage::SetTransparentColor", "ATLIMAGE/ATL::CImage::StretchBlt", "ATLIMAGE/ATL::CImage::TransparentBlt"] helpviewer_keywords: ["jpeg files", "bitmaps [C++], ATL and MFC support for", "images [C++], ATL and MFC support for", "gif files, ATL and MFC support", ".gif files, ATL and MFC support", "PNG files, ATL and MFC support", "CImage class", "transparent color"] -ms.assetid: 52861e3d-bf7e-481f-a240-90e88f76c490 --- # `CImage` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + `CImage` provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats. > [!IMPORTANT] @@ -15,7 +16,7 @@ ms.assetid: 52861e3d-bf7e-481f-a240-90e88f76c490 ## Syntax -``` +```cpp class CImage ``` @@ -148,7 +149,7 @@ You can use `CImage` from either MFC or ATL. Displays bitmaps that have transparent or semitransparent pixels. -``` +```cpp BOOL AlphaBlend( HDC hDestDC, int xDest, @@ -267,7 +268,7 @@ The bitmap can be either a non-DIB section bitmap or a DIB section bitmap. See [ Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL BitBlt( HDC hDestDC, int xDest, @@ -343,7 +344,7 @@ For more information, see [`BitBlt`](/windows/win32/api/wingdi/nf-wingdi-bitblt) Constructs a `CImage` object. -``` +```cpp CImage() throw(); ``` @@ -359,7 +360,7 @@ Using global `CImage` objects in a DLL is not recommended. If you need to use a Creates a `CImage` bitmap and attach it to the previously constructed `CImage` object. -``` +```cpp BOOL Create( int nWidth, int nHeight, @@ -394,7 +395,7 @@ Nonzero if successful; otherwise 0. Creates a `CImage` bitmap and attach it to the previously constructed `CImage` object. -``` +```cpp BOOL CreateEx( int nWidth, int nHeight, @@ -458,7 +459,7 @@ void Destroy() throw(); Detaches a bitmap from a `CImage` object. -``` +```cpp HBITMAP Detach() throw(); ``` @@ -470,7 +471,7 @@ A handle to the bitmap detached, or `NULL` if no bitmap is attached. Copies a bitmap from the source device context to the current device context. -``` +```cpp BOOL Draw( HDC hDestDC, int xDest, @@ -579,7 +580,7 @@ Using this pointer, along with the value returned by [`GetPitch`](#getpitch), yo Retrieves the bits-per-pixel value. -``` +```cpp int GetBPP() const throw(); ``` @@ -619,7 +620,7 @@ A pointer to the array of [`RGBQUAD`](/windows/win32/api/wingdi/ns-wingdi-rgbqua Retrieves the device context that currently has the image selected into it. -``` +```cpp HDC GetDC() const throw(); ``` @@ -635,7 +636,7 @@ For each call to `GetDC`, you must have a subsequent call to [`ReleaseDC`](#rele Finds image formats available for saving images. -``` +```cpp static HRESULT GetExporterFilterString( CSimpleString& strExporters, CSimpleArray& aguidFileTypes, @@ -718,7 +719,7 @@ Use the default separator `|` if you pass this string to an MFC `CFileDialog` ob Retrieves the height, in pixels, of an image. -``` +```cpp int GetHeight() const throw(); ``` @@ -730,7 +731,7 @@ The height, in pixels, of an image. Finds image formats available for loading images. -``` +```cpp static HRESULT GetImporterFilterString( CSimpleString& strImporters, CSimpleArray& aguidFileTypes, @@ -745,7 +746,7 @@ static HRESULT GetImporterFilterString( A reference to a `CSimpleString` object. See **Remarks** for more information. *`aguidFileTypes`*
-An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in *`pszAllFilesDescription`* below, *`aguidFileTypes[0]*` is `GUID_NULL` with the remaining array values are the image file formats supported by the current operating system. +An array of GUIDs, with each element corresponding to one of the file types in the string. In the example in *`pszAllFilesDescription`* below, *`aguidFileTypes[0]`* is `GUID_NULL` with the remaining array values are the image file formats supported by the current operating system. > [!NOTE] > For a complete list of constants, see **Image File Format Constants** in the Windows SDK. @@ -809,7 +810,7 @@ Use the default separator `|` if you pass this string to an MFC `CFileDialog` ob Retrieves the maximum number of entries in the color table. -``` +```cpp int GetMaxColorTableEntries() const throw(); ``` @@ -825,7 +826,7 @@ This method supports only DIB section bitmaps. Retrieves the pitch of an image. -``` +```cpp int GetPitch() const throw(); ``` @@ -846,7 +847,7 @@ Use `GetPitch` with [`GetBits`](#getbits) to find individual pixels of an image. Retrieves the color of the pixel at the location specified by *x* and *y*. -``` +```cpp COLORREF GetPixel(int x, int y) const throw(); ``` @@ -891,7 +892,7 @@ For formats that have less than 8 bits per pixel, this method returns the addres Retrieves the indexed location of the transparent color in the color palette. -``` +```cpp LONG GetTransparentColor() const throw(); ``` @@ -903,7 +904,7 @@ The index of the transparent color. Retrieves the width, in pixels, of an image. -``` +```cpp int GetWidth() const throw(); ``` @@ -915,7 +916,7 @@ The width of the bitmap, in pixels. Determines if the attached bitmap is a DIB section. -``` +```cpp bool IsDIBSection() const throw(); ``` @@ -945,7 +946,7 @@ If the bitmap is not a DIB section, you cannot use the following `CImage` method Determines whether a bitmap's pixels are mapped to a color palette. -``` +```cpp bool IsIndexed() const throw(); ``` @@ -964,7 +965,7 @@ This method returns `TRUE` only if the bitmap is 8-bit (256 colors) or less. Determines if a bitmap is currently loaded. -``` +```cpp bool IsNull() const throw(); ``` @@ -976,7 +977,7 @@ This method returns `TRUE` if a bitmap is not currently loaded; otherwise `FALSE Indicates whether the application supports transparent bitmaps. -``` +```cpp static BOOL IsTransparencySupported() throw(); ``` @@ -992,7 +993,7 @@ If the return value is nonzero, and transparency is supported, a call to [`Alpha Loads an image. -``` +```cpp HRESULT Load(LPCTSTR pszFileName) throw(); HRESULT Load(IStream* pStream) throw(); ``` @@ -1048,7 +1049,7 @@ The resource must be of type `BITMAP`. Combines the color data for the source and destination bitmaps using the specified mask and raster operation. -``` +```cpp BOOL MaskBlt( HDC hDestDC, int xDest, @@ -1147,7 +1148,7 @@ Use this operator to get the attached Windows GDI handle of the `CImage` object. Performs a bit-block transfer from a rectangle in a source device context into a parallelogram in a destination device context. -``` +```cpp BOOL PlgBlt( HDC hDestDC, const POINT* pPoints, @@ -1245,7 +1246,7 @@ This method must be called to free resources allocated by a global `CImage` obje Saves an image to the specified stream or file on disk. -``` +```cpp HRESULT Save( IStream* pStream, REFGUID guidFileType) const throw(); @@ -1391,7 +1392,7 @@ The red, green, and blue parameters are each represented by a number between 0 a Sets a color at a given indexed location as transparent. -``` +```cpp LONG SetTransparentColor(LONG iTransparentColor) throw(); ``` @@ -1408,7 +1409,7 @@ The index of the color previously set as transparent. Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL StretchBlt( HDC hDestDC, int xDest, @@ -1491,7 +1492,7 @@ For more information, see [`StretchBlt`](/windows/win32/api/wingdi/nf-wingdi-str Copies a bitmap from the source device context to this current device context. -``` +```cpp BOOL TransparentBlt( HDC hDestDC, int xDest, diff --git a/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md b/docs/atl-mfc-shared/reference/classes-shared-by-mfc-and-atl.md index dd93cb77f4a..6fb01f6e90c 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 @@ -3,10 +3,11 @@ description: "Learn more about: Classes Shared by MFC and ATL" title: "Classes Shared by MFC and ATL" ms.date: "11/04/2016" helpviewer_keywords: ["shared classes, classes"] -ms.assetid: ca8b4b6b-744d-430b-b31f-d5b2f17bf210 --- # Classes Shared by MFC and ATL +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The following table lists the classes shared between MFC and ATL. |Class|Description|Header file| @@ -21,7 +22,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 69b8fc155de..9c7f028ed78 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 0747ec07ed6..98a888a14f1 100644 --- a/docs/atl-mfc-shared/reference/coledatetime-class.md +++ b/docs/atl-mfc-shared/reference/coledatetime-class.md @@ -1,18 +1,19 @@ --- 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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Encapsulates the `DATE` data type that is used in OLE automation. ## Syntax -``` +```cpp class COleDateTime ``` @@ -109,7 +110,7 @@ For more information about the `COleDateTime` and `COleDateTimeSpan` classes, se Comparison operators. -``` +```cpp bool operator==(const COleDateTime& date) const throw(); bool operator!=(const COleDateTime& date) const throw(); bool operator<(const COleDateTime& date) const throw(); @@ -140,7 +141,7 @@ The operators **>=**, **\<=**, **>**, and **<**, will assert if the `COleDateTim Constructs a `COleDateTime` object. -``` +```cpp COleDateTime() throw(); COleDateTime(const VARIANT& varSrc) throw(); COleDateTime(DATE dtSrc) throw(); @@ -211,7 +212,7 @@ Following is a brief description of each constructor: - `COleDateTime(` `dateSrc` **)** Constructs a `COleDateTime` object from an existing `COleDateTime` object. -- `COleDateTime(` *varSrc* **)** Constructs a `COleDateTime` object. Attempts to convert a `VARIANT` structure or [COleVariant](../../mfc/reference/colevariant-class.md) object to a date/time ( `VT_DATE`) value. If this conversion is successful, the converted value is copied into the new `COleDateTime` object. If it is not, the value of the `COleDateTime` object is set to 0 (midnight, 30 December 1899) and its status to invalid. +- `COleDateTime(` *varSrc* **)** Constructs a `COleDateTime` object. Attempts to convert a `VARIANT` structure or [COleVariant](../../mfc/reference/colevariant-class.md) object to a date/time (`VT_DATE`) value. If this conversion is successful, the converted value is copied into the new `COleDateTime` object. If it is not, the value of the `COleDateTime` object is set to 0 (midnight, 30 December 1899) and its status to invalid. - `COleDateTime(` `dtSrc` **)** Constructs a `COleDateTime` object from a `DATE` value. @@ -242,7 +243,7 @@ For more information about the bounds for `COleDateTime` values, see the article Creates a formatted representation of the date/time value. -``` +```cpp CString Format(DWORD dwFlags = 0, LCID lcid = LANG_USER_DEFAULT) const; CString Format(LPCTSTR lpszFormat) const; CString Format(UINT nFormatID) const; @@ -263,7 +264,7 @@ Indicates one of the following locale flags: Indicates locale ID to use for the conversion. For more information about language identifiers, see [Language Identifiers](/windows/win32/Intl/language-identifiers). *lpszFormat*
-A formatting string similar to the `printf` formatting string. Each formatting code, preceded by a percent ( `%`) sign, is replaced by the corresponding `COleDateTime` component. Other characters in the formatting string are copied unchanged to the returned string. For more information, see the run-time function [strftime](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md). The value and meaning of the formatting codes for `Format` are: +A formatting string similar to the `printf` formatting string. Each formatting code, preceded by a percent (`%`) sign, is replaced by the corresponding `COleDateTime` component. Other characters in the formatting string are copied unchanged to the returned string. For more information, see the run-time function [strftime](../../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md). The value and meaning of the formatting codes for `Format` are: - `%H` Hours in the current day @@ -303,7 +304,7 @@ This form formats the value by using the format string which contains special fo Call this method to obtain the time in the `COleDateTime` object as a `DBTIMESTAMP` data structure. -``` +```cpp bool GetAsDBTIMESTAMP(DBTIMESTAMP& timeStamp) const throw(); ``` @@ -328,7 +329,7 @@ Stores the resulting time in the referenced *timeStamp* structure. The `DBTIMEST Call this method to obtain the time in the `COleDateTime` object as a `SYSTEMTIME` data structure. -``` +```cpp bool GetAsSystemTime(SYSTEMTIME& sysTime) const throw(); ``` @@ -351,7 +352,7 @@ For more information on the status information held in a `COleDateTime` object, Call this method to obtain the time in the `COleDateTime` object as a `UDATE` data structure. -``` +```cpp bool GetAsUDATE(UDATE& uDate) const throw(); ``` @@ -372,7 +373,7 @@ A `UDATE` structure represents an "unpacked" date. Call this static member function to return the current date/time value. -``` +```cpp static COleDateTime WINAPI GetCurrentTime() throw(); ``` @@ -384,7 +385,7 @@ static COleDateTime WINAPI GetCurrentTime() throw(); Gets the day of the month represented by this date/time value. -``` +```cpp int GetDay() const throw(); ``` @@ -420,7 +421,7 @@ For information on other member functions that query the value of this `COleDate Gets the day of the week represented by this date/time value. -``` +```cpp int GetDayOfWeek() const throw(); ``` @@ -456,7 +457,7 @@ For information on other member functions that query the value of this `COleDate Gets the day of the year represented by this date/time value. -``` +```cpp int GetDayOfYear() const throw(); ``` @@ -492,7 +493,7 @@ For information on other member functions that query the value of this `COleDate Gets the hour represented by this date/time value. -``` +```cpp int GetHour() const throw(); ``` @@ -528,7 +529,7 @@ For information on other member functions that query the value of this `COleDate Gets the minute represented by this date/time value. -``` +```cpp int GetMinute() const throw(); ``` @@ -564,7 +565,7 @@ See the example for [GetHour](#gethour). Gets the month represented by this date/time value. -``` +```cpp int GetMonth() const throw(); ``` @@ -600,7 +601,7 @@ See the example for [GetDay](#getday). Gets the second represented by this date/time value. -``` +```cpp int GetSecond() const throw(); ``` @@ -641,7 +642,7 @@ See the example for [GetHour](#gethour). Gets the status (validity) of a given `COleDateTime` object. -``` +```cpp DateTimeStatus GetStatus() const throw(); ``` @@ -653,7 +654,7 @@ Returns the status of this `COleDateTime` value. If you call `GetStatus` on a `C The return value is defined by the `DateTimeStatus` enumerated type, which is defined within the `COleDateTime` class. -``` +```cpp enum DateTimeStatus { error = -1, @@ -707,7 +708,7 @@ For more information about the bounds for `COleDateTime` values, see the article Gets the year represented by this date/time value. -``` +```cpp int GetYear() const throw(); ``` @@ -745,7 +746,7 @@ See the example for [GetDay](#getday). The underlying `DATE` structure for this `COleDateTime` object. -``` +```cpp DATE m_dt; ``` @@ -760,7 +761,7 @@ For more information about the implementation of the `DATE` object, see the arti Contains the status of this `COleDateTime` object. -``` +```cpp DateTimeStatus m_status; ``` @@ -775,7 +776,7 @@ The type of this data member is the enumerated type `DateTimeStatus`, which is d Copies a `COleDateTime` value. -``` +```cpp COleDateTime& operator=(const VARIANT& varSrc) throw(); COleDateTime& operator=(DATE dtSrc) throw(); COleDateTime& operator=(const time_t& timeSrc) throw(); @@ -815,7 +816,7 @@ For more information about the bounds for `COleDateTime` values, see the article Add and subtract `ColeDateTime` values. -``` +```cpp COleDateTime operator+(COleDateTimeSpan dateSpan) const throw(); COleDateTime operator-(COleDateTimeSpan dateSpan) const throw(); COleDateTimeSpan operator-(const COleDateTime& date) const throw(); @@ -845,7 +846,7 @@ For more information about the bounds for `COleDateTime` values, see the article Add and subtract a `ColeDateTime` value from this `COleDateTime` object. -``` +```cpp COleDateTime& operator+=(COleDateTimeSpan dateSpan) throw(); COleDateTime& operator-=(COleDateTimeSpan dateSpan) throw(); ``` @@ -868,7 +869,7 @@ For more information about the bounds for `COleDateTime` values, see the article Converts a `ColeDateTime` value into a `DATE`. -``` +```cpp operator DATE() const throw(); ``` @@ -882,7 +883,7 @@ The `DATE` operator will assert if the `COleDateTime` object is set to null. See Parses a string to read a date/time value. -``` +```cpp bool ParseDateTime( LPCTSTR lpszDate, DWORD dwFlags = 0, @@ -943,7 +944,7 @@ For more information about the bounds and implementation for `COleDateTime` valu Sets the date of this `COleDateTime` object. -``` +```cpp int SetDate( int nYear, int nMonth, @@ -1020,7 +1021,7 @@ For more information about the bounds for `COleDateTime` values, see the article Sets the date and time of this `COleDateTime` object. -``` +```cpp int SetDateTime( int nYear, int nMonth, @@ -1128,7 +1129,7 @@ See the example for [GetStatus](#getstatus). Sets the time of this `COleDateTime` object. -``` +```cpp int SetTime( int nHour, int nMin, diff --git a/docs/atl-mfc-shared/reference/coledatetimespan-class.md b/docs/atl-mfc-shared/reference/coledatetimespan-class.md index 41f2f693c96..04701fb7ddc 100644 --- a/docs/atl-mfc-shared/reference/coledatetimespan-class.md +++ b/docs/atl-mfc-shared/reference/coledatetimespan-class.md @@ -4,15 +4,16 @@ title: "COleDateTimeSpan Class" ms.date: "03/27/2019" f1_keywords: ["COleDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan::COleDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan::Format", "ATLCOMTIME/ATL::COleDateTimeSpan::GetDays", "ATLCOMTIME/ATL::COleDateTimeSpan::GetHours", "ATLCOMTIME/ATL::COleDateTimeSpan::GetMinutes", "ATLCOMTIME/ATL::COleDateTimeSpan::GetSeconds", "ATLCOMTIME/ATL::COleDateTimeSpan::GetStatus", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalDays", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalHours", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalMinutes", "ATLCOMTIME/ATL::COleDateTimeSpan::GetTotalSeconds", "ATLCOMTIME/ATL::COleDateTimeSpan::SetDateTimeSpan", "ATLCOMTIME/ATL::COleDateTimeSpan::SetStatus", "ATLCOMTIME/ATL::COleDateTimeSpan::m_span", "ATLCOMTIME/ATL::COleDateTimeSpan::m_status"] helpviewer_keywords: ["timespan", "time span", "shared classes, COleDateTimeSpan", "Date data type, MFC encapsulation of", "COleDateTimeSpan class"] -ms.assetid: 7441526d-a30a-4019-8fb3-3fee6f897cbe --- # COleDateTimeSpan Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Represents a relative time, a time span. ## Syntax -``` +```cpp class COleDateTimeSpan ``` @@ -76,7 +77,7 @@ For more information on the `COleDateTime` and `COleDateTimeSpan` classes, see t Comparison operators. -``` +```cpp bool operator==(const COleDateTimeSpan& dateSpan) const throw(); bool operator!=(const COleDateTimeSpan& dateSpan) const throw(); bool operator<(const COleDateTimeSpan& dateSpan) const throw(); @@ -102,14 +103,14 @@ These operators compare two date/time-span values and return TRUE if the conditi ### Example [!code-cpp[NVC_ATLMFC_Utilities#25](../../atl-mfc-shared/codesnippet/cpp/coledatetimespan-class_1.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#26](../../atl-mfc-shared/codesnippet/cpp/coledatetimespan-class_2.cpp)] ## COleDateTimeSpan::COleDateTimeSpan Constructs a `COleDateTimeSpan` object. -``` +```cpp COleDateTimeSpan() throw(); COleDateTimeSpan(double dblSpanSrc) throw(); COleDateTimeSpan(LONG lDays, int nHours, int nMins, int nSecs) throw(); @@ -145,7 +146,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Generates a formatted string representation of a `COleDateTimeSpan` object. -``` +```cpp CString Format(LPCTSTR pFormat) const; CString Format(UINT nID) const; ``` @@ -194,7 +195,7 @@ This form formats the value using the format string that contains special format Retrieves the day portion of this date/time-span value. -``` +```cpp LONG GetDays() const throw(); ``` @@ -230,7 +231,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the hour portion of this date/time-span value. -``` +```cpp LONG GetHours() const throw(); ``` @@ -266,7 +267,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the minute portion of this date/time-span value. -``` +```cpp LONG GetMinutes() const throw(); ``` @@ -302,7 +303,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves the second portion of this date/time-span value. -``` +```cpp LONG GetSeconds() const throw(); ``` @@ -338,7 +339,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Gets the status (validity) of this `COleDateTimeSpan` object. -``` +```cpp DateTimeSpanStatus GetStatus() const throw(); ``` @@ -350,7 +351,7 @@ The status of this `COleDateTimeSpan` value. The return value is defined by the `DateTimeSpanStatus` enumerated type, which is defined within the `COleDateTimeSpan` class. -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, @@ -382,7 +383,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Retrieves this date/time-span value expressed in days. -``` +```cpp double GetTotalDays() const throw(); ``` @@ -418,7 +419,7 @@ For other functions that query the value of a `COleDateTimeSpan` object, see the Retrieves this date/time-span value expressed in hours. -``` +```cpp double GetTotalHours() const throw(); ``` @@ -454,7 +455,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in minutes. -``` +```cpp double GetTotalMinutes() const throw(); ``` @@ -490,7 +491,7 @@ See the example for [GetTotalDays](#gettotaldays). Retrieves this date/time-span value expressed in seconds. -``` +```cpp double GetTotalSeconds() const throw(); ``` @@ -526,7 +527,7 @@ See the example for [GetTotalDays](#gettotaldays). The underlying **`double`** value for this `COleDateTime` object. -``` +```cpp double m_span; ``` @@ -541,13 +542,13 @@ This value expresses the date/time-span in days. The type for this data member is the enumerated type `DateTimeSpanStatus`, which is defined within the `COleDateTimeSpan` class. -``` +```cpp DateTimeSpanStatus m_status; ``` ### Remarks -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, @@ -582,7 +583,7 @@ For more information about the bounds for `COleDateTimeSpan` values, see the art Copies a `COleDateTimeSpan` value. -``` +```cpp COleDateTimeSpan& operator=(double dblSpanSrc) throw(); ``` @@ -594,7 +595,7 @@ This overloaded assignment operator copies the source date/time-span value into Add, subtract, and change sign for `COleDateTimeSpan` values. -``` +```cpp COleDateTimeSpan operator+(const COleDateTimeSpan& dateSpan) const throw(); COleDateTimeSpan operator-(const COleDateTimeSpan& dateSpan) const throw(); COleDateTimeSpan operator-() const throw(); @@ -618,7 +619,7 @@ For more information on the valid, invalid, and null status values, see the [m_s Add and subtract a `COleDateTimeSpan` value from this `COleDateTimeSpan` value. -``` +```cpp COleDateTimeSpan& operator+=(const COleDateTimeSpan dateSpan) throw(); COleDateTimeSpan& operator-=(const COleDateTimeSpan dateSpan) throw(); ``` @@ -639,7 +640,7 @@ For more information on the valid, invalid, and null status values, see the [m_s Converts this `COleDateTimeSpan` value to a **`double`**. -``` +```cpp operator double() const throw(); ``` @@ -701,7 +702,7 @@ The new status value for this `COleDateTimeSpan` object. The *Status* parameter value is defined by the `DateTimeSpanStatus` enumerated type, which is defined within the `COleDateTimeSpan` class. -``` +```cpp enum DateTimeSpanStatus{ valid = 0, invalid = 1, diff --git a/docs/atl-mfc-shared/reference/cpoint-class.md b/docs/atl-mfc-shared/reference/cpoint-class.md index 40a5ef14ef7..d153efe18e5 100644 --- a/docs/atl-mfc-shared/reference/cpoint-class.md +++ b/docs/atl-mfc-shared/reference/cpoint-class.md @@ -7,11 +7,13 @@ helpviewer_keywords: ["LPPOINT structure", "POINT structure", "CPoint class"] --- # `CPoint` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Similar to the Windows `POINT` structure. ## Syntax -``` +```cpp class CPoint : public tagPOINT ``` @@ -66,7 +68,7 @@ A `CPoint` object can be used wherever a `POINT` structure is used. The operator Constructs a `CPoint` object. -``` +```cpp CPoint() throw(); CPoint(int initX, int initY) throw(); CPoint(POINT initPt) throw(); @@ -154,7 +156,7 @@ Specifies the amount ([`SIZE`](/windows/win32/api/windef/ns-windef-size) or [`CS Checks for equality between two `POINT`s. -``` +```cpp BOOL operator==(POINT point) const throw(); ``` @@ -254,7 +256,7 @@ For example, subtracting `CPoint(5, -7)` from a variable that contains `CPoint(3 Use this operator to offset `CPoint` by a `CPoint` or `CSize` object, or to offset a `CRect` by a `CPoint`. -``` +```cpp CPoint operator+(SIZE size) const throw(); CPoint operator+(POINT point) const throw(); CRect operator+(const RECT* lpRect) const throw(); @@ -289,7 +291,7 @@ Adding a `CRect` to a `POINT` returns the `CRect` after being offset by the `x` Use one of the first two overloads to subtract a `CPoint` or `CSize` object from `CPoint`. -``` +```cpp CSize operator-(POINT point) const throw(); CPoint operator-(SIZE size) const throw(); CRect operator-(const RECT* lpRect) const throw(); diff --git a/docs/atl-mfc-shared/reference/crect-class.md b/docs/atl-mfc-shared/reference/crect-class.md index 6cadba4e4a6..2ccae83333a 100644 --- a/docs/atl-mfc-shared/reference/crect-class.md +++ b/docs/atl-mfc-shared/reference/crect-class.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: CRect Class" title: "CRect Class" -ms.date: "11/06/2018" +description: "Learn more about: CRect Class" +ms.date: 11/06/2018 f1_keywords: ["CRect", "ATLTYPES/ATL::CRect", "ATLTYPES/ATL::CRect::CRect", "ATLTYPES/ATL::CRect::BottomRight", "ATLTYPES/ATL::CRect::CenterPoint", "ATLTYPES/ATL::CRect::CopyRect", "ATLTYPES/ATL::CRect::DeflateRect", "ATLTYPES/ATL::CRect::EqualRect", "ATLTYPES/ATL::CRect::Height", "ATLTYPES/ATL::CRect::InflateRect", "ATLTYPES/ATL::CRect::IntersectRect", "ATLTYPES/ATL::CRect::IsRectEmpty", "ATLTYPES/ATL::CRect::IsRectNull", "ATLTYPES/ATL::CRect::MoveToX", "ATLTYPES/ATL::CRect::MoveToXY", "ATLTYPES/ATL::CRect::MoveToY", "ATLTYPES/ATL::CRect::NormalizeRect", "ATLTYPES/ATL::CRect::OffsetRect", "ATLTYPES/ATL::CRect::PtInRect", "ATLTYPES/ATL::CRect::SetRect", "ATLTYPES/ATL::CRect::SetRectEmpty", "ATLTYPES/ATL::CRect::Size", "ATLTYPES/ATL::CRect::SubtractRect", "ATLTYPES/ATL::CRect::TopLeft", "ATLTYPES/ATL::CRect::UnionRect", "ATLTYPES/ATL::CRect::Width"] helpviewer_keywords: ["LPCRECT data type", "CRect class", "LPRECT operator", "RECT structure"] -ms.assetid: dee4e752-15d6-4db4-b68f-1ad65b2ed6ca --- # `CRect` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Similar to a Windows [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. ## Syntax -``` +```cpp class CRect : public tagRECT ``` @@ -428,7 +429,7 @@ ASSERT(rect1.EqualRect(&test)); Calculates the height of `CRect` by subtracting the top value from the bottom value. -``` +```cpp int Height() const throw(); ``` @@ -510,7 +511,7 @@ ASSERT(rect == CRect(-50, -200, 350, 500)); Makes a `CRect` equal to the intersection of two existing rectangles. -``` +```cpp BOOL IntersectRect(LPCRECT lpRect1, LPCRECT lpRect2) throw(); ``` @@ -553,7 +554,7 @@ ASSERT(rectInter2 == CRect(125, 75, 150, 95)); Determines whether `CRect` is empty. -``` +```cpp BOOL IsRectEmpty() const throw(); ``` @@ -583,7 +584,7 @@ ASSERT(rectEmpty.IsRectEmpty()); Determines whether the top, left, bottom, and right values of `CRect` are all equal to 0. -``` +```cpp BOOL IsRectNull() const throw(); ``` @@ -745,9 +746,11 @@ rect.OffsetRect(230, 230); ASSERT(rect == CRect(230, 230, 265, 265)); ``` -## `CRect::operator LPCRECT` Converts a `CRect` to an [`LPCRECT`](../../mfc/reference/data-types-mfc.md). +## `CRect::operator LPCRECT` -``` +Converts a `CRect` to an [`LPCRECT`](../../mfc/reference/data-types-mfc.md). + +```cpp operator LPCRECT() const throw(); ``` @@ -759,7 +762,7 @@ When you use this function, you don't need the address-of (**`&`**) operator. Th Converts a `CRect` to an [`LPRECT`](../../mfc/reference/data-types-mfc.md). -``` +```cpp operator LPRECT() throw(); ``` @@ -798,7 +801,7 @@ ASSERT(rect2 == CRect(0, 0, 127, 168)); Determines whether `rect` is equal to `CRect` by comparing the coordinates of their upper-left and lower-right corners. -``` +```cpp BOOL operator==(const RECT& rect) const throw(); ``` @@ -838,7 +841,7 @@ ASSERT(rect1 == test); Determines whether *`rect`* is not equal to `CRect` by comparing the coordinates of their upper-left and lower-right corners. -``` +```cpp BOOL operator!=(const RECT& rect) const throw(); ``` @@ -1009,7 +1012,7 @@ ASSERT(rectResult == rect1); The first two overloads return a `CRect` object that is equal to `CRect` displaced by the specified offsets. -``` +```cpp CRect operator+(POINT point) const throw(); CRect operator+(LPCRECT lpRect) const throw(); CRect operator+(SIZE size) const throw(); @@ -1052,7 +1055,7 @@ ASSERT(rectResult == rect2); The first two overloads return a `CRect` object that is equal to `CRect` displaced by the specified offsets. -``` +```cpp CRect operator-(POINT point) const throw(); CRect operator-(SIZE size) const throw(); CRect operator-(LPCRECT lpRect) const throw(); @@ -1095,7 +1098,7 @@ ASSERT(rect2 == rectResult); Returns a `CRect` that is the intersection of `CRect` and *rect2*. -``` +```cpp CRect operator&(const RECT& rect2) const throw(); ``` @@ -1131,7 +1134,7 @@ ASSERT(rectResult == rect3); Returns a `CRect` that is the union of `CRect` and *`rect2`*. -``` +```cpp CRect operator|(const RECT& rect2) const throw(); ``` @@ -1168,7 +1171,7 @@ ASSERT(rectResult == rect3); Determines whether the specified point lies within `CRect`. -``` +```cpp BOOL PtInRect(POINT point) const throw(); ``` @@ -1295,7 +1298,7 @@ ASSERT(sz.cx == 40 && sz.cy == 40); Makes the dimensions of the `CRect` equal to the subtraction of `lpRectSrc2` from `lpRectSrc1`. -``` +```cpp BOOL SubtractRect(LPCRECT lpRectSrc1, LPCRECT lpRectSrc2) throw(); ``` @@ -1362,7 +1365,7 @@ ASSERT(rectResult == rectOut); The coordinates are returned as a reference to a [`CPoint`](cpoint-class.md) object that is contained in `CRect`. -``` +```cpp CPoint& TopLeft() throw(); const CPoint& TopLeft() const throw(); ``` @@ -1383,7 +1386,7 @@ See the example for [`CRect::CenterPoint`](#centerpoint). Makes the dimensions of `CRect` equal to the union of the two source rectangles. -``` +```cpp BOOL UnionRect(LPCRECT lpRect1, LPCRECT lpRect2) throw(); ``` @@ -1424,7 +1427,7 @@ ASSERT(rectResult == rect3); Calculates the width of `CRect` by subtracting the left value from the right value. -``` +```cpp int Width() const throw(); ``` diff --git a/docs/atl-mfc-shared/reference/csimplestringt-class.md b/docs/atl-mfc-shared/reference/csimplestringt-class.md index 98a3d829467..cda69f67bea 100644 --- a/docs/atl-mfc-shared/reference/csimplestringt-class.md +++ b/docs/atl-mfc-shared/reference/csimplestringt-class.md @@ -1,12 +1,14 @@ --- -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"] --- # `CSimpleStringT` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a `CSimpleStringT` object. ## Syntax @@ -18,7 +20,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 +447,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 +493,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 +504,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 +517,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 +718,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 +1142,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 +1190,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 e807aab4326..458de4f0ed0 100644 --- a/docs/atl-mfc-shared/reference/csize-class.md +++ b/docs/atl-mfc-shared/reference/csize-class.md @@ -1,18 +1,19 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Similar to the Windows [SIZE](/windows/win32/api/windef/ns-windef-size) structure, which implements a relative coordinate or position. ## Syntax -``` +```cpp class CSize : public tagSIZE ``` @@ -58,7 +59,7 @@ The `cx` and `cy` members of `SIZE` (and `CSize`) are public. In addition, `CSiz Constructs a `CSize` object. -``` +```cpp CSize() throw(); CSize( int initCX, int initCY) throw(); CSize( SIZE initSize) throw(); @@ -95,13 +96,13 @@ If no arguments are given, `cx` and `cy` are initialized to zero. Checks for equality between two sizes. -``` +```cpp BOOL operator==(SIZE size) const throw(); ``` ### Remarks -Returns nonzero if the sizes are equal, otherwize 0. +Returns nonzero if the sizes are equal, otherwise 0. ### Example @@ -111,7 +112,7 @@ Returns nonzero if the sizes are equal, otherwize 0. Checks for inequality between two sizes. -``` +```cpp BOOL operator!=(SIZE size) const throw(); ``` @@ -151,7 +152,7 @@ void operator-=(SIZE size) throw(); These operators add this `CSize` value to the value of parameter. -``` +```cpp CSize operator+(SIZE size) const throw(); CPoint operator+(POINT point) const throw(); CRect operator+(const RECT* lpRect) const throw(); @@ -181,7 +182,7 @@ See the following descriptions of the individual operators: The first three of these operators subtract this `CSize` value to the value of parameter. -``` +```cpp CSize operator-(SIZE size) const throw(); CPoint operator-(POINT point) const throw(); CRect operator-(const RECT* lpRect) const throw(); diff --git a/docs/atl-mfc-shared/reference/cstrbuft-class.md b/docs/atl-mfc-shared/reference/cstrbuft-class.md index 4f6f092b913..ed385faa03d 100644 --- a/docs/atl-mfc-shared/reference/cstrbuft-class.md +++ b/docs/atl-mfc-shared/reference/cstrbuft-class.md @@ -4,15 +4,16 @@ title: "CStrBufT Class" ms.date: "10/18/2018" f1_keywords: ["CStrBufT", "ATLSIMPSTR/ATL::CStrBufT", "ATLSIMPSTR/ATL::CStrBufT::CStrBufT", "ATLSIMPSTR/ATL::CStrBufT::SetLength", "ATLSIMPSTR/ATL::CStrBufT::AUTO_LENGTH", "ATLSIMPSTR/ATL::CStrBufT::SET_LENGTH"] helpviewer_keywords: ["strings [C++], custom memory management", "CStrBufT class", "shared classes, CStrBufT"] -ms.assetid: 6b50fa8f-87e8-4ed4-a229-157ce128710f --- # CStrBufT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides automatic resource cleanup for `GetBuffer` and `ReleaseBuffer` calls on an existing `CStringT` object. ## Syntax -``` +```cpp template class CStrBufT ``` @@ -26,7 +27,7 @@ The character type of the `CStrBufT` class. Can be one of the following: - **`wchar_t`** (for Unicode character strings) -- TCHAR (for both ANSI and Unicode character strings) +- **`TCHAR`** (for both ANSI and Unicode character strings) ## Members @@ -34,8 +35,8 @@ The character type of the `CStrBufT` class. Can be one of the following: |Name|Description| |----------|-----------------| -|PCXSTR|A pointer to a constant string.| -|PXSTR|A pointer to a string.| +|`PCXSTR`|A pointer to a constant string.| +|`PXSTR`|A pointer to a string.| |`StringType`|The string type whose buffer is to be manipulated by specializations of this class template.| ### Public Constructors @@ -78,7 +79,7 @@ Primarily designed as a helper class, `CStrBufT` provides a convenient way for a Automatically determine the new length of the string at release. -``` +```cpp static const DWORD AUTO_LENGTH = 0x01; ``` @@ -90,7 +91,7 @@ Automatically determine the new length of the string at release. The string must Constructs a buffer object. -``` +```cpp CStrBufT(StringType& str, int nMinLength, DWORD dwFlags = AUTO_LENGTH) throw(...); explicit CStrBufT(StringType& str) throw(...); ``` @@ -120,7 +121,7 @@ Note that the copy constructor is **`private`**. Directly accesses characters stored in the associated string object as a C-style string. -``` +```cpp operator PCXSTR() const throw(); ``` @@ -136,7 +137,7 @@ Call this function to return a pointer to the character buffer of a string objec Directly accesses characters stored in the associated string object as a C-style string. -``` +```cpp operator PXSTR() throw(); ``` @@ -152,7 +153,7 @@ Call this function to return a pointer to the character buffer of a string objec A pointer to a constant string. -``` +```cpp typedef CSimpleStringT::PCXSTR PCXSTR; ``` @@ -160,7 +161,7 @@ typedef CSimpleStringT::PCXSTR PCXSTR; A pointer to a string. -``` +```cpp typedef CSimpleStringT::PXSTR PXSTR; ``` @@ -168,7 +169,7 @@ typedef CSimpleStringT::PXSTR PXSTR; Set the length of the string object at `GetBuffer` time. -``` +```cpp static const DWORD SET_LENGTH = 0x02; ``` @@ -202,7 +203,7 @@ Call this function to set the length of the string represented by the buffer obj The string type whose buffer is to be manipulated by specializations of this class template. -``` +```cpp typedef CSimpleStringT StringType; ``` diff --git a/docs/atl-mfc-shared/reference/cstringdata-class.md b/docs/atl-mfc-shared/reference/cstringdata-class.md index 03da39cca62..8db5939672f 100644 --- a/docs/atl-mfc-shared/reference/cstringdata-class.md +++ b/docs/atl-mfc-shared/reference/cstringdata-class.md @@ -4,15 +4,16 @@ title: "CStringData Class" ms.date: "11/04/2016" f1_keywords: ["CStringData", "ATLSIMPSTR/ATL::CStringData", "ATLSIMPSTR/ATL::AddRef", "ATLSIMPSTR/ATL::data", "ATLSIMPSTR/ATL::IsLocked", "ATLSIMPSTR/ATL::IsShared", "ATLSIMPSTR/ATL::Lock", "ATLSIMPSTR/ATL::Release", "ATLSIMPSTR/ATL::Unlock", "ATLSIMPSTR/ATL::nAllocLength", "ATLSIMPSTR/ATL::nDataLength", "ATLSIMPSTR/ATL::nRefs", "ATLSIMPSTR/ATL::pStringMgr"] helpviewer_keywords: ["CStringData class", "shared classes, CStringData"] -ms.assetid: 4e31b5ca-3dbe-4fd5-b692-8211fbfb2593 --- # CStringData Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents the data of a string object. ## Syntax -``` +```cpp struct CStringData ``` @@ -105,7 +106,7 @@ Call this function to return the current character buffer of the associated stri Determines if the character buffer is locked. -``` +```cpp bool IsLocked() const throw(); ``` @@ -121,7 +122,7 @@ Call this function to determine if the character buffer of a string object is cu Determines if the character buffer is shared. -``` +```cpp bool IsShared() const throw(); ``` @@ -152,7 +153,7 @@ Call this function to lock the character buffer of the string data object. Locki Length of the allocated character buffer. -``` +```cpp int nAllocLength; ``` @@ -164,7 +165,7 @@ Stores the length of the allocated data buffer in `XCHAR`s (not including termin Current length of the string object. -``` +```cpp int nDataLength; ``` @@ -176,7 +177,7 @@ Stores the length of currently used data in `XCHAR`s (not including terminating Reference count of the string data object. -``` +```cpp long nRefs; ``` @@ -188,7 +189,7 @@ Stores the reference count of the string data object. This count indicates the n The memory manager of the associated string object. -``` +```cpp IAtlStringMgr* pStringMgr; ``` diff --git a/docs/atl-mfc-shared/reference/cstringt-class.md b/docs/atl-mfc-shared/reference/cstringt-class.md index 6921e0fded0..d22cac3373a 100644 --- a/docs/atl-mfc-shared/reference/cstringt-class.md +++ b/docs/atl-mfc-shared/reference/cstringt-class.md @@ -7,6 +7,8 @@ helpviewer_keywords: ["strings [C++], in ATL", "shared classes, CStringT", "CStr --- # `CStringT` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a **`CStringT`** object. ## Syntax @@ -486,11 +488,11 @@ A handle for a **`CStringT`** object. Because the constructors copy the input data into new allocated storage, memory exceptions may result. Some of these constructors act as conversion functions. This allows you to substitute, for example, an **`LPTSTR`** where a **`CStringT`** object is expected. -- **`CStringT`**( `LPCSTR` `lpsz` ): Constructs a Unicode **`CStringT`** from an ANSI string. You can also use this constructor to load a string resource as shown in the example below. +- **`CStringT`**(`LPCSTR` `lpsz`): Constructs a Unicode **`CStringT`** from an ANSI string. You can also use this constructor to load a string resource as shown in the example below. -- `CStringT(` `LPCWSTR` `lpsz` ): Constructs a **`CStringT`** from a Unicode string. +- **`CStringT`**(`LPCWSTR` `lpsz`): Constructs a **`CStringT`** from a Unicode string. -- **`CStringT`**( `const unsigned char*` `psz` ): Allows you to construct a **`CStringT`** from a pointer to **`unsigned char`**. +- **`CStringT`**(`const unsigned char*` `psz`): Allows you to construct a **`CStringT`** from a pointer to **`unsigned char`**. > [!NOTE] > Define the `_CSTRING_DISABLE_NARROW_WIDE_CONVERSION` macro to turn off implicit string conversion between ANSI and Unicode strings. The macro excludes from compilation constructors that support conversion. @@ -725,7 +727,7 @@ Writes a formatted string and a variable list of arguments to a **`CStringT`** s ### Example [!code-cpp[NVC_ATLMFC_Utilities#119](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_14.cpp)] - +  [!code-cpp[NVC_ATLMFC_Utilities#120](../../atl-mfc-shared/codesnippet/cpp/cstringt-class_15.cpp)] ## `CStringT::GetEnvironmentVariable` @@ -998,11 +1000,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 +1104,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 +1146,8 @@ friend bool operator!=(const CStringT& str1, PCXSTR psz2) throw(); friend bool operator!=(const CStringT& str1, PCYSTR psz2) throw(); friend bool operator!=(const CStringT& str1, XCHAR ch2) throw(); friend bool operator!=(PCXSTR psz1, const CStringT& str2) throw(); -friend bool operator!=(PCYSTR psz1, const CStringT& str2,) throw(); -friend bool operator!=(XCHAR ch1, const CStringT& str2,) throw(); +friend bool operator!=(PCYSTR psz1, const CStringT& str2) throw(); +friend bool operator!=(XCHAR ch1, const CStringT& str2) throw(); ``` ### Parameters diff --git a/docs/atl-mfc-shared/reference/ctime-class.md b/docs/atl-mfc-shared/reference/ctime-class.md index 0fbc79bb4d6..9c5623b02f3 100644 --- a/docs/atl-mfc-shared/reference/ctime-class.md +++ b/docs/atl-mfc-shared/reference/ctime-class.md @@ -4,15 +4,16 @@ title: "CTime Class" ms.date: "10/18/2018" f1_keywords: ["ATLTIME/ATL::CTime", "ATLTIME/ATL::CTime::CTime", "ATLTIME/ATL::CTime::Format", "ATLTIME/ATL::CTime::FormatGmt", "ATLTIME/ATL::CTime::GetAsDBTIMESTAMP", "ATLTIME/ATL::CTime::GetAsSystemTime", "ATLTIME/ATL::CTime::GetCurrentTime", "ATLTIME/ATL::CTime::GetDay", "ATLTIME/ATL::CTime::GetDayOfWeek", "ATLTIME/ATL::CTime::GetGmtTm", "ATLTIME/ATL::CTime::GetHour", "ATLTIME/ATL::CTime::GetLocalTm", "ATLTIME/ATL::CTime::GetMinute", "ATLTIME/ATL::CTime::GetMonth", "ATLTIME/ATL::CTime::GetSecond", "ATLTIME/ATL::CTime::GetTime", "ATLTIME/ATL::CTime::GetYear", "ATLTIME/ATL::CTime::Serialize64"] helpviewer_keywords: ["CTime class", "shared classes, CTime"] -ms.assetid: 0a299544-485b-48dc-9d3c-fdc30f57d612 --- # CTime Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Represents an absolute time and date. ## Syntax -``` +```cpp class CTime ``` @@ -82,7 +83,7 @@ For more information about using `CTime`, see the articles [Date and Time](../.. Comparison operators. -``` +```cpp bool operator==(CTime time) const throw(); bool operator!=(CTime time) const throw(); bool operator<(CTime time) const throw(); @@ -108,7 +109,7 @@ These operators compare two absolute times and return TRUE if the condition is t Creates a new `CTime` object initialized with the specified time. -``` +```cpp CTime() throw(); CTime(__time64_t time) throw(); CTime(int nYear, int nMonth, int nDay, @@ -193,7 +194,7 @@ For more information, see the [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minw Call this member function to create a formatted representation of the date-time value. -``` +```cpp CString Format(LPCTSTR pszFormat) const; CString Format(UINT nFormatID) const; ``` @@ -224,7 +225,7 @@ This method throws an exception if the date-time value to format does not range Generates a formatted string that corresponds to this `CTime` object. -``` +```cpp CString FormatGmt(LPCTSTR pszFormat) const; CString FormatGmt(UINT nFormatID) const; ``` @@ -255,7 +256,7 @@ See the example for [CTime::Format](#format). Call this member function to convert the time information stored in the `CTime` object to a Win32-compatible DBTIMESTAMP structure. -``` +```cpp bool GetAsDBTIMESTAMP(DBTIMESTAMP& dbts) const throw(); ``` @@ -280,7 +281,7 @@ Stores the resulting time in the referenced *dbts* structure. The `DBTIMESTAMP` Call this member function to convert the time information stored in the `CTime` object to a Win32-compatible [SYSTEMTIME](/windows/win32/api/minwinbase/ns-minwinbase-systemtime) structure. -``` +```cpp bool GetAsSystemTime(SYSTEMTIME& st) const throw(); ``` @@ -305,7 +306,7 @@ TRUE if successful; otherwise FALSE. Returns a `CTime` object that represents the current time. -``` +```cpp static CTime WINAPI GetCurrentTime() throw(); ``` @@ -321,7 +322,7 @@ Returns the current system date and time in Coordinated Universal Time (UTC). Returns the day represent by the `CTime` object. -``` +```cpp int GetDay() const throw(); ``` @@ -341,7 +342,7 @@ This function calls `GetLocalTm`, which uses an internal, statically allocated b Returns the day of the week represented by the `CTime` object. -``` +```cpp int GetDayOfWeek() const throw(); ``` @@ -361,7 +362,7 @@ This function calls `GetLocalTm`, which uses an internal statically allocated bu Gets a **struct tm** that contains a decomposition of the time contained in this `CTime` object. -``` +```cpp struct tm* GetGmtTm(struct tm* ptm) const; ``` @@ -388,7 +389,7 @@ A pointer to a filled-in **struct tm** as defined in the include file TIME.H. Se Returns the hour represented by the `CTime` object. -``` +```cpp int GetHour() const throw(); ``` @@ -408,7 +409,7 @@ This function calls `GetLocalTm`, which uses an internal statically allocated bu Gets a **struct tm** containing a decomposition of the time contained in this `CTime` object. -``` +```cpp struct tm* GetLocalTm(struct tm* ptm) const; ``` @@ -435,7 +436,7 @@ A pointer to a filled-in **struct tm** as defined in the include file TIME.H. Se Returns the minute represented by the `CTime` object. -``` +```cpp int GetMinute() const throw(); ``` @@ -455,7 +456,7 @@ See the example for [GetHour](#gethour). Returns the month represented by the `CTime` object. -``` +```cpp int GetMonth() const throw(); ``` @@ -475,7 +476,7 @@ See the example for [GetDay](#getday). Returns the second represented by the `CTime` object. -``` +```cpp int GetSecond() const throw(); ``` @@ -495,7 +496,7 @@ See the example for [GetHour](#gethour). Returns a **__time64_t** value for the given `CTime` object. -``` +```cpp __time64_t GetTime() const throw(); ``` @@ -511,7 +512,7 @@ __time64_t GetTime() const throw(); Returns the year represented by the `CTime` object. -``` +```cpp int GetYear(); ``` @@ -531,7 +532,7 @@ See the example for [GetDay](#getday). The assignment operator. -``` +```cpp CTime& operator=(__time64_t time) throw(); ``` @@ -552,7 +553,7 @@ This overloaded assignment operator copies the source time into this `CTime` obj These operators add and subtract `CTimeSpan` and `CTime` objects. -``` +```cpp CTime operator+(CTimeSpan timeSpan) const throw(); CTime operator-(CTimeSpan timeSpan) const throw(); CTimeSpan operator-(CTime time) const throw(); @@ -582,7 +583,7 @@ A `CTime` or `CTimeSpan` object representing the result of the operation. These operators add and subtract a `CTimeSpan` object to and from this `CTime` object. -``` +```cpp CTime& operator+=(CTimeSpan span) throw(); CTime& operator-=(CTimeSpan span) throw(); ``` @@ -611,7 +612,7 @@ These operators allow you to add and subtract a `CTimeSpan` object to and from t Serializes the data associated with the member variable to or from an archive. -``` +```cpp CArchive& Serialize64(CArchive& ar); ``` diff --git a/docs/atl-mfc-shared/reference/ctimespan-class.md b/docs/atl-mfc-shared/reference/ctimespan-class.md index e05a4cc0fe5..df669d06353 100644 --- a/docs/atl-mfc-shared/reference/ctimespan-class.md +++ b/docs/atl-mfc-shared/reference/ctimespan-class.md @@ -7,11 +7,13 @@ helpviewer_keywords: ["elapsed time, CTimeSpan object", "timespan", "time span", --- # `CTimeSpan` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + An amount of time, which is internally stored as the number of seconds in the time span. ## Syntax -``` +```cpp class CTimeSpan ``` @@ -68,7 +70,7 @@ For more information on using `CTimeSpan`, see the articles [Date and Time](../. Comparison operators. -``` +```cpp bool operator==(CTimeSpan span) const throw(); bool operator!=(CTimeSpan span) const throw(); bool operator<(CTimeSpan span) const throw(); @@ -94,7 +96,7 @@ These operators compare two relative time values. They return `TRUE` if the cond Constructs `CTimeSpan` objects in various ways. -``` +```cpp CTimeSpan() throw(); CTimeSpan(__time64_t time) throw(); @@ -145,7 +147,7 @@ Note that the Debug version of the Microsoft Foundation Class Library asserts if Generates a formatted string that corresponds to this `CTimeSpan`. -``` +```cpp CString Format(LPCSTR pFormat) const; CString Format(LPCTSTR pszFormat) const; CString Format(UINT nID) const; @@ -185,7 +187,7 @@ The Debug version of the library checks the formatting codes and asserts if the Returns a value that represents the number of complete days in this `CTimeSpan`. -``` +```cpp LONGLONG GetDays() const throw(); ``` @@ -205,7 +207,7 @@ Note that Daylight Savings Time (DST) can cause `GetDays` to return a potentiall Returns a value that represents the number of hours in the current day (-23 through 23). -``` +```cpp LONG GetHours() const throw(); ``` @@ -221,7 +223,7 @@ Returns the number of hours in the current day. The range is -23 through 23. Returns a value that represents the number of minutes in the current hour (-59 through 59). -``` +```cpp LONG GetMinutes() const throw(); ``` @@ -237,7 +239,7 @@ See the example for [`GetHours`](#gethours). Returns a value that represents the number of seconds in the current minute (-59 through 59). -``` +```cpp LONG GetSeconds() const throw(); ``` @@ -253,7 +255,7 @@ See the example for [`GetHours`](#gethours). Returns the value of the `CTimeSpan` object. -``` +```cpp __ time64_t GetTimeSpan() const throw(); ``` @@ -265,7 +267,7 @@ Returns the current value of the `CTimeSpan` object. Returns a value that represents the total number of complete hours in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalHours() const throw(); ``` @@ -281,7 +283,7 @@ Returns the total number of complete hours in this `CTimeSpan`. Returns a value that represents the total number of complete minutes in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalMinutes() const throw(); ``` @@ -297,7 +299,7 @@ See the example for [`GetTotalHours`](#gettotalhours). Returns a value that represents the total number of complete seconds in this `CTimeSpan`. -``` +```cpp LONGLONG GetTotalSeconds() const throw(); ``` @@ -313,7 +315,7 @@ See the example for [`GetTotalHours`](#gettotalhours). Adds and subtracts `CTimeSpan` objects. -``` +```cpp CTimeSpan operator+(CTimeSpan span) const throw(); CTimeSpan operator-(CTimeSpan span) const throw(); ``` @@ -339,7 +341,7 @@ These two operators allow you to add and subtract `CTimeSpan` objects to and fro Adds and subtracts a `CTimeSpan` object to and from this `CTimeSpan`. -``` +```cpp CTimeSpan& operator+=(CTimeSpan span) throw(); CTimeSpan& operator-=(CTimeSpan span) throw(); ``` @@ -368,7 +370,7 @@ These operators allow you to add and subtract a `CTimeSpan` object to and from t Serializes the data associated with the member variable to or from an archive. -``` +```cpp CArchive& Serialize64(CArchive& ar); ``` diff --git a/docs/atl-mfc-shared/reference/iatlstringmgr-class.md b/docs/atl-mfc-shared/reference/iatlstringmgr-class.md index cbf301b82b6..c94ac02b615 100644 --- a/docs/atl-mfc-shared/reference/iatlstringmgr-class.md +++ b/docs/atl-mfc-shared/reference/iatlstringmgr-class.md @@ -4,15 +4,16 @@ title: "IAtlStringMgr Class" ms.date: "10/18/2018" f1_keywords: ["IAtlStringMgr", "ATLSIMPSTR/ATL::IAtlStringMgr", "ATLSIMPSTR/ATL::Allocate", "ATLSIMPSTR/ATL::Clone", "ATLSIMPSTR/ATL::Free", "ATLSIMPSTR/ATL::GetNilString", "ATLSIMPSTR/ATL::Reallocate"] helpviewer_keywords: ["shared classes, IAtlStringMgr", "memory, managing", "IAtlStringMgr class"] -ms.assetid: 722f0346-a770-4aa7-8f94-177be8dba823 --- # IAtlStringMgr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents the interface to a `CStringT` memory manager. ## Syntax -``` +```cpp __interface IAtlStringMgr ``` @@ -42,7 +43,7 @@ You can also use this class to implement a custom memory manager for your custom Allocates a new string data structure. -``` +```cpp CStringData* Allocate(int nAllocLength,int nCharSize) throw(); ``` @@ -72,7 +73,7 @@ Call [IAtlStringMgr::Free](#free) or [IAtlStringMgr::ReAllocate](#reallocate) to Returns a pointer to a new string manager for use with another instance of `CSimpleStringT`. -``` +```cpp IAtlStringMgr* Clone() throw(); ``` @@ -113,7 +114,7 @@ Frees the specified memory block previously allocated by [Allocate](#allocate) o Returns a pointer to a string data structure for an empty string. -``` +```cpp CStringData* GetNilString() throw(); ``` @@ -135,7 +136,7 @@ Call this function to return a representation of an empty string. Reallocates a string data structure. -``` +```cpp CStringData* Reallocate( CStringData* pData, int nAllocLength, diff --git a/docs/atl-mfc-shared/string-data-management.md b/docs/atl-mfc-shared/string-data-management.md index b48c6a636da..c30b096c6ec 100644 --- a/docs/atl-mfc-shared/string-data-management.md +++ b/docs/atl-mfc-shared/string-data-management.md @@ -6,6 +6,8 @@ helpviewer_keywords: ["Unicode, string objects"] --- # String Data Management +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + Visual C++ provides several ways to manage string data: - [String Manipulation](../c-runtime-library/string-manipulation-crt.md) for working with C-style `NULL`-terminated strings diff --git a/docs/atl-mfc-shared/strings-atl-mfc.md b/docs/atl-mfc-shared/strings-atl-mfc.md index 1c0b4515fa4..a497b8ec3a7 100644 --- a/docs/atl-mfc-shared/strings-atl-mfc.md +++ b/docs/atl-mfc-shared/strings-atl-mfc.md @@ -6,6 +6,8 @@ helpviewer_keywords: ["const char pointers", "strings [C++], in ATL", "MFC [C++] --- # Strings (ATL/MFC) +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + Nearly all programs work with string data. Visual C++ provides several ways to manage this string data. ## In This Section 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 094c1d037a1..b6ca21a7e14 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 @@ -6,13 +6,18 @@ helpviewer_keywords: ["MFC [C++], character set support", "MBCS [C++], strings a --- # Unicode and Multibyte Character Set (MBCS) Support +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + 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 +56,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 +82,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-mfc-shared/using-cstring.md b/docs/atl-mfc-shared/using-cstring.md index f6a99466fcc..829888fc125 100644 --- a/docs/atl-mfc-shared/using-cstring.md +++ b/docs/atl-mfc-shared/using-cstring.md @@ -3,10 +3,11 @@ description: "Learn more about: Using CString" title: "Using CString" ms.date: "06/18/2018" helpviewer_keywords: ["CString objects, C++ string manipulation", "CString objects, reference counting", "CString class (Visual C++)"] -ms.assetid: ed018aaf-8b10-46f9-828c-f9c092dc7609 --- # Using `CString` +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + The topics in this section describe how to program with `CString`. For reference documentation about the `CString` class, see the documentation for [`CStringT`](../atl-mfc-shared/reference/cstringt-class.md). To use `CString`, include the `atlstr.h` header. diff --git a/docs/atl-mfc-shared/using-cstringt.md b/docs/atl-mfc-shared/using-cstringt.md index e7232579f8a..6e322077aef 100644 --- a/docs/atl-mfc-shared/using-cstringt.md +++ b/docs/atl-mfc-shared/using-cstringt.md @@ -3,10 +3,11 @@ description: "Learn more about: Using CStringT" title: "Using CStringT" ms.date: "11/04/2016" helpviewer_keywords: ["CStringT class, using"] -ms.assetid: 3a9fffb1-6f90-482a-ab69-4003e6084cb5 --- # Using CStringT +[!INCLUDE[product-lifecycle-status](./includes/lifecycle-note.md)] + The topics in this section describe programming using the template class [CStringT](../atl-mfc-shared/reference/cstringt-class.md). ## In This Section diff --git a/docs/atl/active-template-library-atl-concepts.md b/docs/atl/active-template-library-atl-concepts.md index bf9f677b9a1..ba5f6335bbc 100644 --- a/docs/atl/active-template-library-atl-concepts.md +++ b/docs/atl/active-template-library-atl-concepts.md @@ -3,10 +3,12 @@ description: "Learn more about: Active Template Library (ATL) Concepts" title: "Active Template Library (ATL) Concepts" ms.date: "05/06/2019" helpviewer_keywords: ["ATL, about ATL"] -ms.assetid: a3960991-4d76-4da5-9568-3fa7fde53ff4 +ms.topic: concept-article --- # Active Template Library (ATL) Concepts +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The Active Template Library (ATL) is a set of template-based C++ classes that let you create small, fast Component Object Model (COM) objects. It has special support for key COM features, including stock implementations, dual interfaces, standard COM enumerator interfaces, connection points, tear-off interfaces, and ActiveX controls. If you do a lot of ATL programming, you will want to learn more about COM and .NET attributes, which is designed to simplify COM programming. For more information, see [Attributed Programming](../windows/attributes/cpp-attributes-com-net.md). (COM and .NET attributes are not to be confused with the \[\[attribute]] feature in the C++ standard.) diff --git a/docs/atl/active-template-library-atl-tutorial.md b/docs/atl/active-template-library-atl-tutorial.md index 52c536ff965..e8054c8897f 100644 --- a/docs/atl/active-template-library-atl-tutorial.md +++ b/docs/atl/active-template-library-atl-tutorial.md @@ -4,10 +4,12 @@ description: "Create an ActiveX control using Microsoft C++ and the Active Templ ms.custom: "get-started-article" ms.date: "05/03/2019" helpviewer_keywords: ["ATL projects, tutorials", "controls [ATL], tutorials", "ATL tutorial", "tutorials [ATL]", "ATL, tutorials"] -ms.assetid: f921a121-09c8-4812-9317-e15b2f1471fa +ms.topic: tutorial --- # Active Template Library (ATL) Tutorial +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL is designed to simplify the process of creating efficient, flexible, lightweight controls. This tutorial leads you through the creation of an ActiveX control, demonstrating many ATL and COM fundamentals. By following this tutorial, you will learn how to add a control to an ATL project that draws a circle and a filled polygon. You will then add a property to indicate how many sides the polygon will have and create drawing code for updating the control when the property changes. The control will then be displayed on a Web page using some VBScript to make it respond to events. diff --git a/docs/atl/adding-a-control-atl-tutorial-part-2.md b/docs/atl/adding-a-control-atl-tutorial-part-2.md index 64913399d10..f0cdb0d25aa 100644 --- a/docs/atl/adding-a-control-atl-tutorial-part-2.md +++ b/docs/atl/adding-a-control-atl-tutorial-part-2.md @@ -3,10 +3,12 @@ description: "Learn more about: Adding a Control (ATL Tutorial, Part 2)" title: "Adding a Control (ATL Tutorial, Part 2)" ms.custom: "get-started-article" ms.date: "08/19/2019" -ms.assetid: c9575a75-1064-41f1-9697-7aada560c669 +ms.topic: tutorial --- # Adding a Control (ATL Tutorial, Part 2) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + In this step, you add a control to your project, build it, and test it on a Web page. ## Procedures diff --git a/docs/atl/adding-a-property-page-atl-tutorial-part-6.md b/docs/atl/adding-a-property-page-atl-tutorial-part-6.md index 77ab6f873a6..1d169bed706 100644 --- a/docs/atl/adding-a-property-page-atl-tutorial-part-6.md +++ b/docs/atl/adding-a-property-page-atl-tutorial-part-6.md @@ -3,10 +3,12 @@ description: "Learn more about: Adding a Property Page (ATL Tutorial, Part 6)" title: "Adding a Property Page (ATL Tutorial, Part 6)" ms.custom: "get-started-article" ms.date: "09/27/2018" -ms.assetid: df80d255-e7ea-49d9-b940-3f012e90cf9b +ms.topic: tutorial --- # Adding a Property Page (ATL Tutorial, Part 6) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + > [!NOTE] > The ATL OLE DB Provider wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md b/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md index eae5f195dd7..852dd925637 100644 --- a/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md +++ b/docs/atl/adding-a-property-to-the-control-atl-tutorial-part-3.md @@ -3,10 +3,12 @@ description: "Learn more about: Adding a Property to the Control (ATL Tutorial, title: "Adding a Property to the Control (ATL Tutorial, Part 3)" ms.custom: "get-started-article" ms.date: "09/26/2018" -ms.assetid: f775fe34-103b-4f07-9999-400e987ee030 +ms.topic: tutorial --- # Adding a Property to the Control (ATL Tutorial, Part 3) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + `IPolyCtl` is the interface that contains the control's custom methods and properties, and you will add a property to it. ### To add the property definitions to your project diff --git a/docs/atl/adding-an-atl-message-handler.md b/docs/atl/adding-an-atl-message-handler.md index e7dd2532992..178eb55484c 100644 --- a/docs/atl/adding-an-atl-message-handler.md +++ b/docs/atl/adding-an-atl-message-handler.md @@ -3,10 +3,12 @@ description: "Learn more about: Adding an ATL Message Handler" title: "Adding an ATL Message Handler" ms.date: "11/04/2016" helpviewer_keywords: ["message handlers [C++]", "ATL, windows", "message handling [C++], ATL message handler", "windows [C++], ATL", "ATL, message handlers"] -ms.assetid: cdea38a1-0d9b-4f8d-bbd5-b4f063fb3eeb +ms.topic: concept-article --- # Adding an ATL Message Handler +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + To add a message handler (a member function that handles Windows messages) to a control, first select the control in the Class View. Then open the **Properties** window, select the **Messages** icon, and click the drop-down control in the box opposite the required message. This will add a declaration for the message handler in the control's header file and a skeleton implementation of the handler in the control's .cpp file. It will also add the message map and add an entry for the handler. Adding a message handler in ATL is similar to adding a message handler to an MFC class. See [Adding an MFC Message Handler](../mfc/reference/adding-an-mfc-message-handler.md) for more information. diff --git a/docs/atl/adding-an-event-atl-tutorial-part-5.md b/docs/atl/adding-an-event-atl-tutorial-part-5.md index 18306b8df03..ed1690d4df0 100644 --- a/docs/atl/adding-an-event-atl-tutorial-part-5.md +++ b/docs/atl/adding-an-event-atl-tutorial-part-5.md @@ -3,10 +3,12 @@ description: "Learn more about: Adding an Event (ATL Tutorial, Part 5)" title: "Adding an Event (ATL Tutorial, Part 5)" ms.custom: "get-started-article" ms.date: "09/27/2018" -ms.assetid: 2de12022-3148-4ce3-8606-8a9d4274f0e9 +ms.topic: tutorial --- # Adding an Event (ATL Tutorial, Part 5) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + In this step, you will add a `ClickIn` and a `ClickOut` event to your ATL control. You will fire the `ClickIn` event if the user clicks within the polygon and fire `ClickOut` if the user clicks outside. The tasks to add an event are as follows: - Adding the `ClickIn` and `ClickOut` methods diff --git a/docs/atl/adding-connection-points-to-an-object.md b/docs/atl/adding-connection-points-to-an-object.md index 671460f394d..732d3688c9c 100644 --- a/docs/atl/adding-connection-points-to-an-object.md +++ b/docs/atl/adding-connection-points-to-an-object.md @@ -1,58 +1,57 @@ --- -description: "Learn more about: Adding Connection Points to an Object" title: "Adding Connection Points to an Object" -ms.date: "11/04/2016" +description: "Learn more about: Adding Connection Points to an Object" +ms.date: 11/04/2016 helpviewer_keywords: ["connection points [C++], adding to ATL objects", "Implement Connection Point ATL wizard"] -ms.assetid: 843531be-4a36-4db0-9d54-e029b1a72a8b +ms.topic: how-to --- # Adding Connection Points to an Object -The [ATL Tutorial](../atl/active-template-library-atl-tutorial.md) demonstrates how to create a control with support for connection points, how to add events, and then how to implement the connection point. ATL implements connection points with the [IConnectionPointImpl](../atl/reference/iconnectionpointimpl-class.md) class. +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + +The [ATL Tutorial](active-template-library-atl-tutorial.md) demonstrates how to create a control with support for connection points, how to add events, and then how to implement the connection point. ATL implements connection points with the [`IConnectionPointImpl`](reference/iconnectionpointimpl-class.md) class. To implement a connection point, you have two choices: - Implement your own outgoing event source, by adding a connection point to the control or object. - - Reuse a connection point interface defined in another type library. -In either case, the Implement Connection Point Wizard uses a type library to do its work. +In either case, the **Implement Connection Point Wizard** uses a type library to do its work. -### To add a connection point to a control or object +### Add a connection point to a control or object -1. Define a dispinterface in the library block of the .idl file. If you enabled support for connection points when you created the control with the ATL Control Wizard, the dispinterface will already be created. If you did not enable support for connection points when you created the control, you must manually add a dispinterface to the .idl file. The following is an example of a dispinterface. Outgoing interfaces are not required to be dispatch interfaces but many scripting languages such as VBScript and JScript require this, so this example uses two dispinterfaces: +1. Define a dispinterface in the library block of the `.idl` file. If you enabled support for connection points when you created the control with the **ATL Control Wizard**, the dispinterface will already be created. If you did not enable support for connection points when you created the control, you must manually add a dispinterface to the `.idl` file. The following is an example of a dispinterface. Outgoing interfaces are not required to be dispatch interfaces but many scripting languages such as VBScript and JScript require this, so this example uses two dispinterfaces: - [!code-cpp[NVC_ATL_Windowing#81](../atl/codesnippet/cpp/adding-connection-points-to-an-object_1.idl)] + [!code-cpp[NVC_ATL_Windowing#81](codesnippet/cpp/adding-connection-points-to-an-object_1.idl)] - Use either the uuidgen.exe or guidgen.exe utility to generate a GUID. + Use either the `uuidgen.exe` or `guidgen.exe` utility to generate a GUID. -2. Add the dispinterface as the `[default,source]` interface in the coclass for the object in the project's .idl file. Again, if you enabled support for connection points when you created the control, the ATL Control Wizard will create the `[default,source`] entry. To manually add this entry, add the line in bold: +2. Add the dispinterface as the `[default,source]` interface in the coclass for the object in the project's `.idl` file. Again, if you enabled support for connection points when you created the control, the ATL Control Wizard will create the `[default,source]` entry. To manually add this entry, add the line in bold: - [!code-cpp[NVC_ATL_Windowing#82](../atl/codesnippet/cpp/adding-connection-points-to-an-object_2.idl)] + [!code-cpp[NVC_ATL_Windowing#82](codesnippet/cpp/adding-connection-points-to-an-object_2.idl)] - See the .idl file in the [Circ](../overview/visual-cpp-samples.md) ATL sample for an example. + See the `.idl` file in the [Circ](../overview/visual-cpp-samples.md) ATL sample for an example. -3. Use Class View to add methods and properties to the event interface. Right-click the class in Class View, point to **Add** on the shortcut menu, and click **Add Connection Point**. +3. Use **Class View** to add methods and properties to the event interface. Right-click the class in **Class View**, point to **Add** on the shortcut menu, and select **Add Connection Point**. -4. In the **Source Interfaces** list box of the Implement Connection Point Wizard, select **Project's interfaces**. If you choose an interface for your control and press **OK**, you will: +4. In the **Source Interfaces** list box of the **Implement Connection Point Wizard**, select **Project's interfaces**. If you choose an interface for your control and select **OK**, you: - Generate a header file with an event proxy class that implements the code that will make the outgoing calls for the event. - - Add an entry to the connection point map. - You will also see a list of all of the type libraries on your computer. You should only use one of these other type libraries to define your connection point if you want to implement the exact same outgoing interface found in another type library. - -### To reuse a connection point interface defined in another type library + You also see a list of all of the type libraries on your computer. Only use one of these other type libraries to define your connection point if you want to implement the exact same outgoing interface found in another type library. -1. In Class View, right-click a class that implements a **BEGIN_COM_MAP** macro, point to **Add** on the shortcut menu, and click **Add Connection Point**. +### Reuse a connection point interface defined in another type library -2. In the Implement Connection Point Wizard, select a type library and an interface in the type library and click **Add**. +1. In **Class View**, right-click a class that implements a `BEGIN_COM_MAP` macro, point at **Add** on the shortcut menu, and select **Add Connection Point**. -3. Edit the .idl file to either: +2. In the **Implement Connection Point Wizard**, select a type library and an interface in the type library and select **Add**. - - Copy the dispinterface from the .idl file for the object whose event-source is being used. +3. Edit the `.idl` file to either: + - Copy the dispinterface from the `.idl` file for the object whose event-source is being used. - Use the **importlib** instruction on that type library. ## See also -[Connection Point](../atl/atl-connection-points.md) +[Connection Point](atl-connection-points.md) diff --git a/docs/atl/adding-functionality-to-the-composite-control.md b/docs/atl/adding-functionality-to-the-composite-control.md index 77ef261e3b0..f32c146abd8 100644 --- a/docs/atl/adding-functionality-to-the-composite-control.md +++ b/docs/atl/adding-functionality-to-the-composite-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Adding Functionality to the Composite Control" title: "Adding Functionality to the Composite Control" ms.date: "11/04/2016" helpviewer_keywords: ["event handlers [C++], ActiveX controls", "composite controls, handling events", "ActiveX controls [C++], events"] -ms.assetid: 98f85681-9564-480d-af38-03f9733fe58b +ms.topic: concept-article --- # Adding Functionality to the Composite Control +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Once you have inserted any necessary controls into the composite control, the next step involves adding new functionality. This new functionality usually falls into two categories: - Supporting additional interfaces and customizing the behavior of your composite control with additional, specific features. diff --git a/docs/atl/aggregation.md b/docs/atl/aggregation.md index 36c510daf37..e1b0448277a 100644 --- a/docs/atl/aggregation.md +++ b/docs/atl/aggregation.md @@ -3,10 +3,11 @@ description: "Learn more about: Aggregation" title: "Aggregation" ms.date: "11/04/2016" helpviewer_keywords: ["aggregation [C++]", "aggregate objects [C++]"] -ms.assetid: 7125bb8e-b269-4b50-9bba-295b467a54cc --- # Aggregation +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + There are times when an object's implementor would like to take advantage of the services offered by another, prebuilt object. Furthermore, it would like this second object to appear as a natural part of the first. COM achieves both of these goals through containment and aggregation. Aggregation means that the containing (outer) object creates the contained (inner) object as part of its creation process and the interfaces of the inner object are exposed by the outer. An object allows itself to be aggregatable or not. If it is, then it must follow certain rules for aggregation to work properly. diff --git a/docs/atl/atl-and-the-free-threaded-marshaler.md b/docs/atl/atl-and-the-free-threaded-marshaler.md index 5d5e78c8a63..b496b5b4fc8 100644 --- a/docs/atl/atl-and-the-free-threaded-marshaler.md +++ b/docs/atl/atl-and-the-free-threaded-marshaler.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL and the Free Threaded Marshaler" title: "ATL and the Free Threaded Marshaler" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, free threaded marshaler", "free threaded marshaler", "threading [C++], marshaler in ATL", "threading [ATL], free threaded marshaler", "FTM in ATL"] -ms.assetid: 2db88a13-2217-4ebc-aa7e-432d5da902eb --- # ATL and the Free Threaded Marshaler +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The ATL Simple Object Wizard's Attributes page provides an option that allows your class to aggregate the free threaded marshaler (FTM). The wizard generates code to create an instance of the free threaded marshaler in `FinalConstruct` and release that instance in `FinalRelease`. A COM_INTERFACE_ENTRY_AGGREGATE macro is automatically added to the COM map to ensure that `QueryInterface` requests for [IMarshal](/windows/win32/api/objidlbase/nn-objidlbase-imarshal) are handled by the free threaded marshaler. diff --git a/docs/atl/atl-class-overview.md b/docs/atl/atl-class-overview.md index 5b028118055..bf22cf76fca 100644 --- a/docs/atl/atl-class-overview.md +++ b/docs/atl/atl-class-overview.md @@ -3,10 +3,12 @@ description: "Learn more about: ATL class overview" title: "ATL class overview" ms.date: "11/04/2016" helpviewer_keywords: ["classes [C++], ATL", "ATL, class reference"] -ms.assetid: c38ac93d-c3a2-4ce7-8153-f1d34c0f0fa6 +ms.topic: concept-article --- # ATL class overview +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Classes in the Active Template Library (ATL) can be categorized as follows: [Class factories](../atl/class-factories-classes.md)\ diff --git a/docs/atl/atl-collection-and-enumerator-classes.md b/docs/atl/atl-collection-and-enumerator-classes.md index d96c74e5703..b887eabdb83 100644 --- a/docs/atl/atl-collection-and-enumerator-classes.md +++ b/docs/atl/atl-collection-and-enumerator-classes.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Collection and Enumerator Classes" title: "ATL Collection and Enumerator Classes" ms.date: "11/04/2016" helpviewer_keywords: ["enumerators, ATL classes", "collection classes, ATL"] -ms.assetid: 6818db73-7094-48d8-a0ca-18147beec362 --- # ATL Collection and Enumerator Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL provides the following classes to help you implement collections and enumerators. |Class|Description| diff --git a/docs/atl/atl-collection-classes.md b/docs/atl/atl-collection-classes.md index 7545e6d6906..bd9c02edc03 100644 --- a/docs/atl/atl-collection-classes.md +++ b/docs/atl/atl-collection-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: ATL Collection Classes" title: "ATL collection class overview" ms.date: "11/19/2018" helpviewer_keywords: ["DestructElements function", "collection classes, choosing", "ConstructElements function", "SerializeElements function", "traits classes", "collection classes, about collection classes", "CTraits classes", "collection classes"] -ms.assetid: 4d619d46-5b4e-41dd-b9fd-e86b1fbc00b5 +ms.topic: concept-article --- # ATL Collection Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL provides many classes for storing and accessing data. Which class you decide to use depends on several factors, including: - The amount of data to be stored diff --git a/docs/atl/atl-collections-and-enumerators.md b/docs/atl/atl-collections-and-enumerators.md index 68eea6e6f86..ba991026b3c 100644 --- a/docs/atl/atl-collections-and-enumerators.md +++ b/docs/atl/atl-collections-and-enumerators.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Collections and Enumerators" title: "ATL Collections and Enumerators" ms.date: "11/04/2016" helpviewer_keywords: ["enumerator interfaces", "collections, ATL classes", "enumerators, ATL classes", "collection interfaces"] -ms.assetid: b2d37119-3ab2-4e0a-b65b-f377f07e4098 --- # ATL Collections and Enumerators +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A `collection` is a COM object that provides an interface that allows access to a group of data items (raw data or other objects). An interface that follows the standards for providing access to a group of objects is known as a *collection interface*. At a minimum, collection interfaces must provide a `Count` property that returns the number of items in the collection, an `Item` property that returns an item from the collection based on an index, and a `_NewEnum` property that returns an enumerator for the collection. Optionally, collection interfaces can provide `Add` and `Remove` methods to allow items to be inserted into or deleted from the collection, and a `Clear` method to remove all items. diff --git a/docs/atl/atl-com-desktop-components.md b/docs/atl/atl-com-desktop-components.md index 3d5d2ad0c96..e12f41f8be4 100644 --- a/docs/atl/atl-com-desktop-components.md +++ b/docs/atl/atl-com-desktop-components.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL COM Desktop Components" title: "ATL COM Desktop Components" ms.date: "10/19/2018" helpviewer_keywords: ["ATL, reference", "ATL, about ATL"] -ms.assetid: 291f38d1-d2de-4687-86a9-99b4fd35706c --- # ATL COM Desktop Components +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The ATL Reference documents the Active Template Library (ATL), a set of template-based C++ classes that simplify the programming of Component Object Model (COM) objects. COM is a binary specification for creating and consuming software components on Windows. To fully take advantage of ATL, a working familiarity with COM is highly recommended. For more information about COM, see [Component Object Model (COM)](/windows/win32/com/component-object-model--com--portal). ## In This Section diff --git a/docs/atl/atl-com-property-pages.md b/docs/atl/atl-com-property-pages.md index 109d83b95c0..3b84ea0421e 100644 --- a/docs/atl/atl-com-property-pages.md +++ b/docs/atl/atl-com-property-pages.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL COM Property Pages" title: "ATL COM Property Pages" ms.date: "11/04/2016" helpviewer_keywords: ["property pages, COM", "ATL COM objects", "COM property pages", "property pages, ATL", "COM objects, ATL", "ATL property pages"] -ms.assetid: 663c7caa-2e5e-4b5c-b8ea-fd434ceb1654 --- # ATL COM Property Pages +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + COM property pages provide a user interface for setting the properties (or calling the methods) of one or more COM objects. Property pages are used extensively by ActiveX controls for providing rich user interfaces that allow control properties to be set at design time. Property pages are COM objects that implement the [IPropertyPage](/windows/win32/api/ocidl/nn-ocidl-ipropertypage) or [IPropertyPage2](/windows/win32/api/ocidl/nn-ocidl-ipropertypage2) interface. These interfaces provide methods that allow the page to be associated with a `site` (a COM object representing the container of the page) and a number of *objects* (COM objects whose methods will be called in response to changes made by the user of the property page). The property page container is responsible for calling methods on the property page interface to tell the page when to show or hide its user interface, and when to apply the changes made by the user to the underlying objects. diff --git a/docs/atl/atl-composite-control-fundamentals.md b/docs/atl/atl-composite-control-fundamentals.md index 99d5bc76e01..c96615a0bd2 100644 --- a/docs/atl/atl-composite-control-fundamentals.md +++ b/docs/atl/atl-composite-control-fundamentals.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Composite Control Fundamentals" title: "ATL Composite Control Fundamentals" ms.date: "11/04/2016" helpviewer_keywords: ["composite controls, about composite controls"] -ms.assetid: 2ac78cdd-1ec4-4d78-871c-1bcc23b5253e --- # ATL Composite Control Fundamentals +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A composite control is a type of ActiveX control that can contain (similar to a dialog box) other ActiveX controls or Windows controls. Once the composite control is built, it can be inserted anywhere an ActiveX control can be hosted. The ATL Project Wizard and **Add Class** dialog box automate the process of creating and implementing a composite control project, similar to the result of running the Application Wizard to create an MFC application framework. The development process consists of five steps: diff --git a/docs/atl/atl-connection-point-classes.md b/docs/atl/atl-connection-point-classes.md index 9de4d1eaf44..21d955c22e5 100644 --- a/docs/atl/atl-connection-point-classes.md +++ b/docs/atl/atl-connection-point-classes.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Connection Point Classes" title: "ATL Connection Point Classes" ms.date: "11/04/2016" helpviewer_keywords: ["CFirePropNotifyEvent class, connection point classes", "connection points [C++], ATL classes", "ATL, connection points", "CComDynamicUnkArray class, connection point classes", "CFirePropNotifyEvent class", "CComUnkArray class, connection point classes"] -ms.assetid: 9582ba71-7ace-4df4-9c9b-1b0636953efc --- # ATL Connection Point Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL uses the following classes to support connection points: - [IConnectionPointImpl](../atl/reference/iconnectionpointimpl-class.md) implements a connection point. The IID of the outgoing interface it represents is passed as a template parameter. diff --git a/docs/atl/atl-connection-point-example.md b/docs/atl/atl-connection-point-example.md index 0a7cf22ac7a..c837053c9e1 100644 --- a/docs/atl/atl-connection-point-example.md +++ b/docs/atl/atl-connection-point-example.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Connection Point Example" title: "ATL Connection Point Example" ms.date: "11/04/2016" helpviewer_keywords: ["connection points [C++], examples", "examples [ATL]"] -ms.assetid: a49721b7-f308-43de-8868-f662a94bc81a --- # ATL Connection Point Example +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + This example shows an object that supports [IPropertyNotifySink](/windows/win32/api/ocidl/nn-ocidl-ipropertynotifysink) as an outgoing interface: [!code-cpp[NVC_ATL_Windowing#84](../atl/codesnippet/cpp/atl-connection-point-example_1.h)] diff --git a/docs/atl/atl-connection-points.md b/docs/atl/atl-connection-points.md index 9bad34db0b4..cb3f08ffa9f 100644 --- a/docs/atl/atl-connection-points.md +++ b/docs/atl/atl-connection-points.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Connection Points" title: "ATL Connection Points" ms.date: "11/04/2016" helpviewer_keywords: ["connections, connection points", "ATL, connection points", "connection points [C++], about connection points"] -ms.assetid: 17d76165-5f83-4f95-b36d-483821c247a1 --- # ATL Connection Points +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A connectable object is one that supports outgoing interfaces. An outgoing interface allows the object to communicate with a client. For each outgoing interface, the connectable object exposes a connection point. Each outgoing interface is implemented by a client on an object called a sink. ![Diagram that shows the connection points on a client object and a connectable object.](../atl/media/vc2zw31.gif "Connection points") diff --git a/docs/atl/atl-copy-policy-classes.md b/docs/atl/atl-copy-policy-classes.md index 08787e3fe9b..0c2aad5b629 100644 --- a/docs/atl/atl-copy-policy-classes.md +++ b/docs/atl/atl-copy-policy-classes.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Copy Policy Classes" title: "ATL Copy Policy Classes" ms.date: "11/04/2016" helpviewer_keywords: ["data [C++], ATL", "classes [C++], copy policy", "copy policy classes [C++]", "_Copy class", "_CopyInterface class"] -ms.assetid: 06704b68-d318-4c5d-a65b-71457fe9d00d --- # ATL Copy Policy Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Copy policy classes are [utility classes](../atl/utility-classes.md) used to initialize, copy, and delete data. Copy policy classes allow you to define copy semantics for any type of data, and to define conversions between different data types. ATL uses copy policy classes in its implementations of the following templates: diff --git a/docs/atl/atl-encoding-reference.md b/docs/atl/atl-encoding-reference.md index e7153b05201..36787474f2a 100644 --- a/docs/atl/atl-encoding-reference.md +++ b/docs/atl/atl-encoding-reference.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Encoding Reference" title: "ATL Encoding Reference" ms.date: "11/04/2016" helpviewer_keywords: ["encoding", "encoding, functions"] -ms.assetid: 82d4fdf3-3c4a-4fe2-b297-8ffb4714406f --- # ATL Encoding Reference +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Encoding in a range of common Internet standards such as uuencode, hexadecimal, and UTF8 is supported by the code found in *`atlenc.h`*. ### Functions diff --git a/docs/atl/atl-event-handling-summary.md b/docs/atl/atl-event-handling-summary.md index 166f1d40284..55d8eabacca 100644 --- a/docs/atl/atl-event-handling-summary.md +++ b/docs/atl/atl-event-handling-summary.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Event Handling Summary" title: "ATL Event Handling Summary" ms.date: "11/04/2016" helpviewer_keywords: ["event handling, implementing"] -ms.assetid: e8b47ef0-0bdc-47ff-9dd6-34df11dde9a2 --- # ATL Event Handling Summary +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + In general, handling COM events is a relatively simple process. There are three main steps: - Implement the event interface on your object. diff --git a/docs/atl/atl-module-classes.md b/docs/atl/atl-module-classes.md index 4613d5af005..512b96192d5 100644 --- a/docs/atl/atl-module-classes.md +++ b/docs/atl/atl-module-classes.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Module Classes" title: "ATL Module Classes" ms.date: "11/04/2016" helpviewer_keywords: ["CComModule class, what's changed", "ATL, module classes", "module classes"] -ms.assetid: fd75382d-c955-46ba-a38e-37728b7fa00f --- # ATL Module Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + This topic discusses the module classes that were new in ATL 7.0. ## CComModule Replacement Classes diff --git a/docs/atl/atl-registry-component-registrar.md b/docs/atl/atl-registry-component-registrar.md index 6fc68ca1fc2..3615ba7fc45 100644 --- a/docs/atl/atl-registry-component-registrar.md +++ b/docs/atl/atl-registry-component-registrar.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Registry Component (Registrar)" title: "ATL Registry Component (Registrar)" ms.date: "11/04/2016" helpviewer_keywords: ["scripting, registry scripting", "ATL, registry", "registrar scripts [ATL]", "registry, accessing", "ATL Registrar", "scripts, Registrar scripts", "registry, Registrar"] -ms.assetid: 106752ae-4cfc-4030-8cb2-d36a1d635a2e --- # ATL Registry Component (Registrar) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The ATL Registrar provides optimized access to the system registry through a custom interface. The Registrar is free-threaded and allows static linking of code for C++ clients. > [!NOTE] diff --git a/docs/atl/atl-services.md b/docs/atl/atl-services.md index 4acde07ca7e..591a7222173 100644 --- a/docs/atl/atl-services.md +++ b/docs/atl/atl-services.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Services" title: "ATL Services" ms.date: "11/04/2016" helpviewer_keywords: ["CServiceModule class", "COM objects, ATL", "services, ATL", "ATL services"] -ms.assetid: 8c09d1a8-7548-4d2c-947c-9d795a81659b --- # ATL Services +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + To create your ATL COM object so that it runs in a service, simply select Service (EXE) from the list of server options in the ATL Project Wizard. The wizard will then create a class derived from `CAtlServiceModuleT` to implement the service. When the ATL COM object is built as a service, it will only be registered as a local server, and it will not appear in the list of services in Control Panel. This is because it is easier to debug the service as a local server than as a service. To install it as a service, run the following at the command prompt: diff --git a/docs/atl/atl-support-for-dhtml-controls.md b/docs/atl/atl-support-for-dhtml-controls.md index eca0e2fe0b1..2a2f8c091f8 100644 --- a/docs/atl/atl-support-for-dhtml-controls.md +++ b/docs/atl/atl-support-for-dhtml-controls.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Support for DHTML Controls" title: "ATL Support for DHTML Controls" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, ATL support", "DHTML controls, ATL support", "DHTML controls"] -ms.assetid: 4ba98098-da5d-4362-96ad-8372f816c307 --- # ATL Support for DHTML Controls +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Using ATL, you can create a control with Dynamic HTML (DHTML) capability. An ATL DHTML control: - Hosts the WebBrowser control. diff --git a/docs/atl/atl-utilities-reference.md b/docs/atl/atl-utilities-reference.md index 1fe2da43038..19120124b84 100644 --- a/docs/atl/atl-utilities-reference.md +++ b/docs/atl/atl-utilities-reference.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: ATL utilities reference" title: "ATL utilities reference" -ms.date: "11/04/2016" -ms.assetid: dd8a2888-34f4-461e-9bf4-834218f9b95b +description: "Learn more about: ATL utilities reference" +ms.date: 11/04/2016 --- # ATL utilities reference +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl/reference/cpatht-class.md) and [CUrl](../atl/reference/curl-class.md). A thread pool, [CThreadPool](../atl/reference/cthreadpool-class.md), can be used in your applications. This code can be found in atlpath.h and atlutil.h. ## Classes -|   |   | +| Name | Description | |--|--| | [CPathT class](../atl/reference/cpatht-class.md) | This class represents a path. | | [CDebugReportHook class](../atl/reference/cdebugreporthook-class.md) | Use this class to send debug reports to a named pipe. | @@ -22,7 +23,7 @@ ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl ## Typedefs -|   |   | +| Name | Description | |--|--| | [CPath](../atl/reference/atl-typedefs.md#cpath) | A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CString`. | | [CPathA](../atl/reference/atl-typedefs.md#cpatha) | A specialization of [CPathT](../atl/reference/cpatht-class.md) using `CStringA`. | @@ -31,13 +32,13 @@ ATL provides code for manipulating paths and URLs in the form of [CPathT](../atl ## Enums -|   |   | +| Name | Description | |--|--| | [ATL_URL_SCHEME](../atl/reference/atl-url-scheme-enum.md) | The members of this enumeration provide constants for the schemes understood by [CUrl](../atl/reference/curl-class.md). | ## Functions -|   |   | +| Name | Description | |--|--| | [AtlCanonicalizeUrl](../atl/reference/atl-http-utility-functions.md#atlcanonicalizeurl) | Call this function to canonicalize a URL, which includes converting unsafe characters and spaces into escape sequences. | | [AtlCombineUrl](../atl/reference/atl-http-utility-functions.md#atlcombineurl) | Call this function to combine a base URL and a relative URL into a single, canonical URL. | @@ -47,8 +48,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 +87,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/atl-window-classes.md b/docs/atl/atl-window-classes.md index bf9968a0313..92c7c453843 100644 --- a/docs/atl/atl-window-classes.md +++ b/docs/atl/atl-window-classes.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Window Classes" title: "ATL Window Classes" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "windows [C++], subclassing", "windows [C++], superclassing", "windows [C++], ATL", "subclassing ATL window classes", "superclassing", "superclassing, ATL"] -ms.assetid: 1d12b708-de3e-49d5-9e41-42fe4769fa62 --- # ATL Window Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL includes several classes that allow you to use and implement windows. These classes, like other ATL classes, provide an efficient implementation that does not impose an overhead on your code. This section describes the ATL window classes and explains how to use them. diff --git a/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md b/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md index d84c7e8e639..3c3d0fe0276 100644 --- a/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md +++ b/docs/atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md @@ -3,10 +3,11 @@ description: "Learn more about: Benefits and Tradeoffs of the Method Used to Lin title: "Benefits and Tradeoffs of the Method Used to Link to the CRT" ms.date: "05/06/2019" helpviewer_keywords: ["_ATL_MIN_CRT macro"] -ms.assetid: 49b485f7-9487-49e4-b12a-0f710b620e2b --- # Benefits and Tradeoffs of the Method Used to Link to the CRT +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Your project can link with the CRT either dynamically or statically. The table below outlines the benefits and tradeoffs involved in choosing which method to use. |Method|Benefit|Tradeoff| diff --git a/docs/atl/building-and-testing-the-atl-project.md b/docs/atl/building-and-testing-the-atl-project.md index 9a5c30dd382..53aebdcc5e4 100644 --- a/docs/atl/building-and-testing-the-atl-project.md +++ b/docs/atl/building-and-testing-the-atl-project.md @@ -3,10 +3,12 @@ description: "Learn more about: Building and Testing the ATL Project" title: "Building and Testing the ATL Project" ms.date: "11/04/2016" helpviewer_keywords: ["composite controls, building and testing the project", "composite controls, containers for"] -ms.assetid: 5c1541f8-f6cb-4c22-bd22-c66bcfbaa077 +ms.topic: concept-article --- # Building and Testing the ATL Project +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + As mentioned in [Inserting a Composite Control](../atl/inserting-a-composite-control.md), one of the initial components of the project is a default HTML page that hosts your new composite control. After you finish modifying the composite control, click **Build Solution** or **Rebuild Solution** from the **Build** menu. Once the project successfully builds, load the HTML page, located in the root directory of your composite control project, into Internet Explorer or another browser and test the functionality of your control. You can also test your composite control using the Test Container tool, or any other application that can host an ActiveX control. See [Testing Properties and Events with Test Container](../mfc/testing-properties-and-events-with-test-container.md) for information on how to access the test container. diff --git a/docs/atl/calling-cpp-code-from-dhtml.md b/docs/atl/calling-cpp-code-from-dhtml.md index 64b57d32b47..03f3e87a0d4 100644 --- a/docs/atl/calling-cpp-code-from-dhtml.md +++ b/docs/atl/calling-cpp-code-from-dhtml.md @@ -3,10 +3,12 @@ description: "Learn more about: Calling C++ Code from DHTML" title: "Calling C++ Code from DHTML" ms.date: "11/04/2016" helpviewer_keywords: ["DHTML, calling C++ code from"] -ms.assetid: 37329acd-4c22-40ca-a85a-b7480748f75f +ms.topic: concept-article --- # Calling C++ Code from DHTML +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A DHTML control can be hosted in a container, such as Test Container or Internet Explorer. See [Testing Properties and Events with Test Container](../mfc/testing-properties-and-events-with-test-container.md) for information on how to access Test Container. The container hosting the control communicates with the control using the normal control interfaces. DHTML uses the dispatch interface that ends with "UI" to communicate with your C++ code and your HTML resource. In [Modifying the ATL DHTML Control](../atl/modifying-the-atl-dhtml-control.md), you can practice adding the methods to be called by these different interfaces. diff --git a/docs/atl/catlservicemodulet-handler-function.md b/docs/atl/catlservicemodulet-handler-function.md index a2da13bec83..c21778eec43 100644 --- a/docs/atl/catlservicemodulet-handler-function.md +++ b/docs/atl/catlservicemodulet-handler-function.md @@ -3,10 +3,11 @@ description: "Learn more about: CAtlServiceModuleT::Handler Function" title: "CAtlServiceModuleT::Handler Function" ms.date: "11/04/2016" helpviewer_keywords: ["Handler method"] -ms.assetid: 14db5f2a-be87-4774-a296-445cb6fc7b2e --- # CAtlServiceModuleT::Handler Function +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + `CAtlServiceModuleT::Handler` is the routine that the service control manager (SCM) calls to retrieve the status of the service and give it various instructions (such as stopping or pausing). The SCM passes an operation code to `Handler` to indicate what the service should do. A default ATL-generated service only handles the stop instruction. If the SCM passes the stop instruction, the service tells the SCM that the program is about to stop. The service then calls `PostThreadMessage` to post a quit message to itself. This terminates the message loop and the service will ultimately close. To handle more instructions, you need to change the `m_status` data member initialized in the `CAtlServiceModuleT` constructor. This data member tells the SCM which buttons to enable when the service is selected in the Services Control Panel application. diff --git a/docs/atl/catlservicemodulet-run-function.md b/docs/atl/catlservicemodulet-run-function.md index 9471ee390a8..e9aadfc95c2 100644 --- a/docs/atl/catlservicemodulet-run-function.md +++ b/docs/atl/catlservicemodulet-run-function.md @@ -3,10 +3,11 @@ description: "Learn more about: CAtlServiceModuleT::Run Function" title: "CAtlServiceModuleT::Run Function" ms.date: "11/04/2016" helpviewer_keywords: ["ATL services, security"] -ms.assetid: 42c010f0-e60e-459c-a63b-a53a24cda93b --- # CAtlServiceModuleT::Run Function +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + `Run` contains calls to `PreMessageLoop`, `RunMessageLoop`, and `PostMessageLoop`. After being called, `PreMessageLoop` first stores the service's thread ID. The service will use this ID to close itself by sending a WM_QUIT message using the Win32 API function, [PostThreadMessage](/windows/win32/api/winuser/nf-winuser-postthreadmessagew). `PreMessageLoop` then calls `InitializeSecurity`. By default, `InitializeSecurity` calls [CoInitializeSecurity](/windows/win32/api/combaseapi/nf-combaseapi-coinitializesecurity) with the security descriptor set to NULL, which means that any user has access to your object. diff --git a/docs/atl/catlservicemodulet-servicemain-function.md b/docs/atl/catlservicemodulet-servicemain-function.md index f3cfffa7fd3..f037a2ca6ae 100644 --- a/docs/atl/catlservicemodulet-servicemain-function.md +++ b/docs/atl/catlservicemodulet-servicemain-function.md @@ -3,10 +3,11 @@ description: "Learn more about: CAtlServiceModuleT::ServiceMain Function" title: "CAtlServiceModuleT::ServiceMain Function" ms.date: "11/04/2016" helpviewer_keywords: ["ServiceMain method"] -ms.assetid: f21408c1-1919-4dec-88d8-bf5b39ac9808 --- # CAtlServiceModuleT::ServiceMain Function +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The service control manager (SCM) calls `ServiceMain` when you open the Services Control Panel application, select the service, and click **Start**. After the SCM calls `ServiceMain`, a service must give the SCM a handler function. This function lets the SCM obtain the service's status and pass specific instructions (such as pausing or stopping). The SCM gets this function when the service passes `_Handler` to the Win32 API function, [RegisterServiceCtrlHandler](/windows/win32/api/winsvc/nf-winsvc-registerservicectrlhandlerw). (`_Handler` is a static member function that calls the non-static member function [Handler](../atl/reference/catlservicemodulet-class.md#handler).) diff --git a/docs/atl/catlservicemodulet-start-function.md b/docs/atl/catlservicemodulet-start-function.md index 920857413d4..670a2023aee 100644 --- a/docs/atl/catlservicemodulet-start-function.md +++ b/docs/atl/catlservicemodulet-start-function.md @@ -3,10 +3,11 @@ description: "Learn more about: CAtlServiceModuleT::Start Function" title: "CAtlServiceModuleT::Start Function" ms.date: "11/04/2016" helpviewer_keywords: ["Start method"] -ms.assetid: b5193a23-41bc-42d2-8d55-3eb43dc62238 --- # CAtlServiceModuleT::Start Function +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + When the service is run, `_tWinMain` calls `CAtlServiceModuleT::WinMain`, which in turn calls `CAtlServiceModuleT::Start`. `CAtlServiceModuleT::Start` sets up an array of `SERVICE_TABLE_ENTRY` structures that map each service to its startup function. This array is then passed to the Win32 API function, [StartServiceCtrlDispatcher](/windows/win32/api/winsvc/nf-winsvc-startservicectrldispatcherw). In theory, one EXE could handle multiple services and the array could have multiple `SERVICE_TABLE_ENTRY` structures. Currently, however, an ATL-generated service supports only one service per EXE. Therefore, the array has a single entry that contains the service name and `_ServiceMain` as the startup function. `_ServiceMain` is a static member function of `CAtlServiceModuleT` that calls the non-static member function, `ServiceMain`. diff --git a/docs/atl/changing-the-default-class-factory-and-aggregation-model.md b/docs/atl/changing-the-default-class-factory-and-aggregation-model.md index 5cc79f13e54..31cf67c1254 100644 --- a/docs/atl/changing-the-default-class-factory-and-aggregation-model.md +++ b/docs/atl/changing-the-default-class-factory-and-aggregation-model.md @@ -3,10 +3,12 @@ description: "Learn more about: Changing the Default Class Factory and Aggregati title: "Changing the Default Class Factory and Aggregation Model" ms.date: "11/04/2016" helpviewer_keywords: ["CComClassFactory class, making the default", "aggregation [C++], using ATL", "aggregation [C++], aggregation models", "defaults [C++], aggregation model in ATL", "default class factory", "class factories, changing default", "CComCoClass class, default class factory and aggregation model", "default class factory, ATL", "defaults [C++], class factory"] -ms.assetid: 6e040e95-0f38-4839-8a8b-c9800dd47e8c +ms.topic: concept-article --- # Changing the Default Class Factory and Aggregation Model +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL uses [CComCoClass](../atl/reference/ccomcoclass-class.md) to define the default class factory and aggregation model for your object. `CComCoClass` specifies the following two macros: - [DECLARE_CLASSFACTORY](reference/aggregation-and-class-factory-macros.md#declare_classfactory) Declares the class factory to be [CComClassFactory](../atl/reference/ccomclassfactory-class.md). diff --git a/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md b/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md index ae8149664e8..d835f00e7d9 100644 --- a/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md +++ b/docs/atl/changing-the-drawing-code-atl-tutorial-part-4.md @@ -4,10 +4,12 @@ title: "Changing the Drawing Code (ATL Tutorial, Part 4)" ms.custom: "get-started-article" ms.date: "09/26/2018" helpviewer_keywords: ["_ATL_MIN_CRT macro"] -ms.assetid: 08ff14e8-aa49-4139-a110-5d071939cf1e +ms.topic: tutorial --- # Changing the Drawing Code (ATL Tutorial, Part 4) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + By default, the control's drawing code displays a square and the text **PolyCtl**. In this step, you will change the code to display something more interesting. The following tasks are involved: - Modifying the Header File diff --git a/docs/atl/class-factories-classes.md b/docs/atl/class-factories-classes.md index 15bda12d380..a0e9bdb8927 100644 --- a/docs/atl/class-factories-classes.md +++ b/docs/atl/class-factories-classes.md @@ -4,10 +4,11 @@ title: " ATL Class Factories Classes" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["class factories", "class factories, ATL classes"] -ms.assetid: 1d8c2ae2-2c37-452c-a02d-1ecbdd309f84 --- # Class Factories Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes implement or support a class factory: - [CComClassFactory](../atl/reference/ccomclassfactory-class.md) Provides a default class factory for object creation. diff --git a/docs/atl/class-information-classes.md b/docs/atl/class-information-classes.md index 4f4b3f3158e..b1854183884 100644 --- a/docs/atl/class-information-classes.md +++ b/docs/atl/class-information-classes.md @@ -4,10 +4,11 @@ title: "Class Information Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["class information, retrieving"] -ms.assetid: 39365025-f24a-41ae-87ab-4ae8ed085b98 --- # Class Information Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class provides support for retrieving class information: - [IProvideClassInfo2Impl](../atl/reference/iprovideclassinfo2impl-class.md) Provides access to type information. Retrieves the outgoing IID for the object's default event set. diff --git a/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp b/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp index 876ad2f58cf..baa1deb220f 100644 --- a/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp +++ b/docs/atl/codesnippet/CPP/atl-collection-classes_1.cpp @@ -29,7 +29,7 @@ class MyTraits : public CElementTraits< MyData > return true; else return false; - }; + } }; void DoAtlCustomTraitsList() diff --git a/docs/atl/collection-classes.md b/docs/atl/collection-classes.md index 0545b6d29b0..5702e9832d1 100644 --- a/docs/atl/collection-classes.md +++ b/docs/atl/collection-classes.md @@ -4,10 +4,11 @@ title: "Collection classes in ATL" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["collection classes"] -ms.assetid: eff95de6-78ef-4212-9d7d-1dacbdd4cc58 --- # Collection Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide support for arrays, lists, maps, and also traits methods for helping with comparisons and element access. - [CAtlArray](../atl/reference/catlarray-class.md) This class implements an array object. diff --git a/docs/atl/com-modules-classes.md b/docs/atl/com-modules-classes.md index 4c4671f1231..768c712e943 100644 --- a/docs/atl/com-modules-classes.md +++ b/docs/atl/com-modules-classes.md @@ -4,10 +4,11 @@ title: "COM Modules Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["COM modules classes"] -ms.assetid: 0a8a82dd-a153-47cd-9bbe-1a1ad5d1a6ff --- # COM Modules Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide support for a COM module: - [CAtlBaseModule](../atl/reference/catlbasemodule-class.md) This class is instantiated in every ATL project. diff --git a/docs/atl/commandhandler.md b/docs/atl/commandhandler.md index 6ad29accfb3..2a299bfa7d7 100644 --- a/docs/atl/commandhandler.md +++ b/docs/atl/commandhandler.md @@ -4,10 +4,11 @@ title: "CommandHandler" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["CommandHandler function"] -ms.assetid: 662bc7bf-4a10-42b3-986d-d8bae4f63551 --- # CommandHandler +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + `CommandHandler` is the function identified by the third parameter of the COMMAND_HANDLER macro in your message map. ## Syntax diff --git a/docs/atl/composite-controls-classes.md b/docs/atl/composite-controls-classes.md index 0e45651cc80..42f653e0cbb 100644 --- a/docs/atl/composite-controls-classes.md +++ b/docs/atl/composite-controls-classes.md @@ -4,10 +4,11 @@ title: "Composite Controls Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["composite controls, C++", "composite controls classes"] -ms.assetid: 9e8d65c4-d631-4500-a28b-6d42c35aba26 --- # Composite Controls Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class provides support for creating composite controls - [CComCompositeControl](../atl/reference/ccomcompositecontrol-class.md) ActiveX controls derived from `CComCompositeControl` are hosted by a standard dialog box. These types of controls are called composite controls because they are able to host other controls (native Windows controls and ActiveX controls). diff --git a/docs/atl/connection-points-classes.md b/docs/atl/connection-points-classes.md index 52b73a0103c..4903c12022e 100644 --- a/docs/atl/connection-points-classes.md +++ b/docs/atl/connection-points-classes.md @@ -4,10 +4,11 @@ title: "Connection Points Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["classes [C++], connection points", "connection points classes"] -ms.assetid: 076365fa-299a-4dce-84c3-a5dff0e0da1f --- # Connection Points Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide support for connection points: - [IConnectionPointContainerImpl](../atl/reference/iconnectionpointcontainerimpl-class.md) Implements a connection point container. diff --git a/docs/atl/control-containment-classes.md b/docs/atl/control-containment-classes.md index 1446101b696..8eb055a2cbf 100644 --- a/docs/atl/control-containment-classes.md +++ b/docs/atl/control-containment-classes.md @@ -4,10 +4,11 @@ title: "Control Containment Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["control containment classes"] -ms.assetid: e0812aee-c078-4ced-b967-247976552b9a --- # Control Containment Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide containment support for hosting controls: - [CAxWindow](../atl/reference/caxwindow-class.md) Provides methods for manipulating a window that hosts an ActiveX control. diff --git a/docs/atl/controls-general-support-classes.md b/docs/atl/controls-general-support-classes.md index fdb016140e0..2bcaa142937 100644 --- a/docs/atl/controls-general-support-classes.md +++ b/docs/atl/controls-general-support-classes.md @@ -4,10 +4,11 @@ title: "ATL Controls: General Support Classes" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["controls [ATL]", "general support classes"] -ms.assetid: cf73f1d2-7542-48e3-b8c8-9d3abf29f85b --- # Controls: General Support Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide general support for ATL controls: - [CComControl](../atl/reference/ccomcontrol-class.md) Consists of helper functions and data members that are essential to ATL controls. diff --git a/docs/atl/creating-an-aggregated-object.md b/docs/atl/creating-an-aggregated-object.md index ea3e0cb8d69..e6e24a5bf08 100644 --- a/docs/atl/creating-an-aggregated-object.md +++ b/docs/atl/creating-an-aggregated-object.md @@ -3,10 +3,12 @@ description: "Learn more about: Creating an Aggregated Object" title: "Creating an Aggregated Object" ms.date: "11/04/2016" helpviewer_keywords: ["aggregation [C++], creating aggregated objects", "aggregate objects [C++], creating"] -ms.assetid: fc29d7aa-fd53-4276-9c2f-37379f71b179 +ms.topic: how-to --- # Creating an Aggregated Object +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Aggregation delegates `IUnknown` calls, providing a pointer to the outer object's `IUnknown` to the inner object. ## To create an aggregated object diff --git a/docs/atl/creating-an-atl-dhtml-control.md b/docs/atl/creating-an-atl-dhtml-control.md index 8a6d94f04e1..c6c4f9c846b 100644 --- a/docs/atl/creating-an-atl-dhtml-control.md +++ b/docs/atl/creating-an-atl-dhtml-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Creating an ATL DHTML Control" title: "Creating an ATL DHTML Control" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, creating", "DHTML controls", "DHTML controls, creating"] -ms.assetid: 1d8f0ede-7d8b-4959-976e-b4d0e2a87f5a +ms.topic: how-to --- # Creating an ATL DHTML Control +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The ATL Control Wizard automates the process of creating a DHTML control. It generates the necessary resource files, including an HTML file containing sample code. ## To create an ATL DHTML control diff --git a/docs/atl/creating-registrar-scripts.md b/docs/atl/creating-registrar-scripts.md index e4a6c996184..9e9e8eb0ca2 100644 --- a/docs/atl/creating-registrar-scripts.md +++ b/docs/atl/creating-registrar-scripts.md @@ -3,10 +3,12 @@ description: "Learn more about: Creating Registrar scripts" title: "Creating scripts for ATL Registrar" ms.date: "05/14/2014" helpviewer_keywords: ["scripting, registry scripting", "ATL, registry", "registrar scripts [ATL]", "scripts, Registrar scripts", "scripts, creating"] -ms.assetid: cbd5024b-8061-4a71-be65-7fee90374a35 +ms.topic: concept-article --- # Creating Registrar scripts +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A registrar script provides data-driven, rather than API-driven, access to the system registry. Data-driven access is typically more efficient since it takes only one or two lines in a script to add a key to the registry. The [ATL Control Wizard](../atl/reference/atl-control-wizard.md) automatically generates a registrar script for your COM server. You can find this script in the .rgs file associated with your object. diff --git a/docs/atl/creating-the-project-atl-tutorial-part-1.md b/docs/atl/creating-the-project-atl-tutorial-part-1.md index 9326e91f39d..c7aa2721438 100644 --- a/docs/atl/creating-the-project-atl-tutorial-part-1.md +++ b/docs/atl/creating-the-project-atl-tutorial-part-1.md @@ -3,10 +3,12 @@ description: "Learn more about: Creating the Project (ATL Tutorial, Part 1)" title: "Creating the Project (ATL Tutorial, Part 1)" ms.custom: "get-started-article" ms.date: "08/19/2019" -ms.assetid: f6b727d1-390a-4b27-b82f-daadcd9fc059 +ms.topic: tutorial --- # Creating the Project (ATL Tutorial, Part 1) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + This tutorial walks you step-by-step through a non-attributed ATL project that creates an ActiveX object that displays a polygon. The object includes options for allowing the user to change the number of sides making up the polygon, and code to refresh the display. > [!NOTE] diff --git a/docs/atl/data-transfer-classes.md b/docs/atl/data-transfer-classes.md index 67709a809cd..c3515d329ca 100644 --- a/docs/atl/data-transfer-classes.md +++ b/docs/atl/data-transfer-classes.md @@ -4,10 +4,11 @@ title: "Data Transfer Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["data transfer [C++]", "data transfer [C++], classes", "data transfer classes [C++]"] -ms.assetid: c10bcdc8-b90c-4c2a-9179-fd3de80461da --- # Data Transfer Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes support various types of data transfer: - [IDataObjectImpl](../atl/reference/idataobjectimpl-class.md) Supports Uniform Data Transfer by using standard formats to retrieve and set data. Handles data change notifications by managing connections to advise sinks. diff --git a/docs/atl/data-types-classes.md b/docs/atl/data-types-classes.md index 85d986bad81..c636b279ff2 100644 --- a/docs/atl/data-types-classes.md +++ b/docs/atl/data-types-classes.md @@ -4,10 +4,11 @@ title: "Data Types Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["data types classes [C++]", "data types [C++], classes"] -ms.assetid: 29882bab-9174-4dfa-8227-ccfeba80b865 --- # Data Types Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes wrap C++ data types: - [CComBSTR](../atl/reference/ccombstr-class.md) Wraps the `BSTR` data type. diff --git a/docs/atl/dcomcnfg.md b/docs/atl/dcomcnfg.md index 0a0468d6a57..ac312effae9 100644 --- a/docs/atl/dcomcnfg.md +++ b/docs/atl/dcomcnfg.md @@ -3,10 +3,11 @@ description: "Learn more about: DCOMCNFG" title: "DCOMCNFG" ms.date: "11/04/2016" helpviewer_keywords: ["DCOMCNFG utility", "DCOM, configuring in ATL"] -ms.assetid: 5a8126e9-ef27-40fb-a66e-9dce8d1a7e80 --- # DCOMCNFG +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + DCOMCNFG is a Windows NT 4.0 utility that allows you to configure various DCOM-specific settings in the registry. The DCOMCNFG window has three pages: Default Security, Default Properties, and Applications. Under Windows 2000 a fourth page, Default Protocols, is present. ## Default Security Page diff --git a/docs/atl/debugging-and-exceptions-classes.md b/docs/atl/debugging-and-exceptions-classes.md index 703972808b0..c8a8205fa2c 100644 --- a/docs/atl/debugging-and-exceptions-classes.md +++ b/docs/atl/debugging-and-exceptions-classes.md @@ -4,10 +4,11 @@ title: "Debugging and Exceptions Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["debugging and exceptions classes"] -ms.assetid: d42d7649-9721-4a1a-8b38-d983a649fdb9 --- # Debugging and Exceptions Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + These classes provide support for exception handling and debugging. - [CAtlDebugInterfacesModule](../atl/reference/catldebuginterfacesmodule-class.md) This class provides support for debugging interfaces. diff --git a/docs/atl/debugging-tips.md b/docs/atl/debugging-tips.md index 986845b3192..f5680d207ed 100644 --- a/docs/atl/debugging-tips.md +++ b/docs/atl/debugging-tips.md @@ -3,10 +3,12 @@ description: "Learn more about: Debugging Tips" title: "Debugging Tips (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, debugging", "services, debugging"] -ms.assetid: 48c60244-d0ce-4466-85fa-6fa65fcfe86c +ms.topic: concept-article --- # Debugging Tips +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following topics outline some useful steps for debugging your service: - [Using Task Manager](../atl/using-task-manager.md) diff --git a/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md b/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md index 84783f4e5a0..7f9b5386a3b 100644 --- a/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md +++ b/docs/atl/design-principles-for-collection-and-enumerator-interfaces.md @@ -3,10 +3,12 @@ description: "Learn more about: Design Principles for Collection and Enumerator title: "Designing Collection and Enumerator Interfaces (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["enumerator interfaces", "collection interfaces"] -ms.assetid: ea19a39e-6333-41a1-be62-5435c236640e +ms.topic: concept-article --- # Design Principles for Collection and Enumerator Interfaces +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + There are different design principles behind each type of interface: - A collection interface provides *random* access to a *single* item in the collection via the `Item` method, it lets clients discover how many items are in the collection via the `Count` property, and often allows clients to add and remove items. diff --git a/docs/atl/displaying-assertions.md b/docs/atl/displaying-assertions.md index 8f1863b3718..e4ffc2a6420 100644 --- a/docs/atl/displaying-assertions.md +++ b/docs/atl/displaying-assertions.md @@ -3,10 +3,12 @@ description: "Learn more about: Displaying Assertions" title: "Displaying Assertions" ms.date: "05/05/2019" helpviewer_keywords: ["debugging [ATL], displaying assertions", "assertions, displaying", "debugging assertions", "assertions, debugging"] -ms.assetid: fa353fe8-4656-4384-a5d2-8866bc977f06 +ms.topic: concept-article --- # Displaying Assertions +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + If the client connected to your service appears to stop responding, the service may have asserted and displayed a message box that you are not able to see. You can confirm this by using the Visual Studio debugger to debug your code (see [Using Task Manager](../atl/using-task-manager.md) earlier in this section). If you determine that your service is displaying a message box that you cannot see, you may want to set the **Allow Service to Interact with Desktop** option before using the service again. This option is a startup parameter that permits any message boxes displayed by the service to appear on the desktop. To set this option, open the Services Control Panel application, select the service, click **Startup**, and then select the **Allow Service to Interact with Desktop** option. diff --git a/docs/atl/dual-interfaces-and-atl.md b/docs/atl/dual-interfaces-and-atl.md index 2039cb3e12e..38dcc7d2888 100644 --- a/docs/atl/dual-interfaces-and-atl.md +++ b/docs/atl/dual-interfaces-and-atl.md @@ -3,10 +3,11 @@ description: "Learn more about: Dual Interfaces and ATL" title: "Dual Interfaces and ATL" ms.date: "11/04/2016" helpviewer_keywords: ["COM, and ATL", "ATL, dual interfaces", "dual interfaces, about dual interfaces"] -ms.assetid: 5a390e89-d2c4-41f0-8538-cab2c5e5d4c8 --- # Dual Interfaces and ATL +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A dual interface allows its methods to be accessed as dispinterface methods or as vtable methods. This section covers some of the features of dual interfaces from an ATL perspective. ## In This Section diff --git a/docs/atl/dual-interfaces-and-events.md b/docs/atl/dual-interfaces-and-events.md index a0a520b396a..5e5fc2bc5e1 100644 --- a/docs/atl/dual-interfaces-and-events.md +++ b/docs/atl/dual-interfaces-and-events.md @@ -3,10 +3,11 @@ description: "Learn more about: Dual Interfaces and Events" title: "Dual Interfaces and Events" ms.date: "11/04/2016" helpviewer_keywords: ["events [C++], dual interfaces", "dual interfaces, events"] -ms.assetid: bb382f7c-e885-4274-bf07-83f3602615d2 --- # Dual Interfaces and Events +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + While it is possible to design an event interface as a dual, there are a number of good design reasons not to do so. The fundamental reason is that the source of the event will only fire the event via the vtable or via `Invoke`, not both. If the event source fires the event as a direct vtable method call, the `IDispatch` methods will never be used and it's clear that the interface should have been a pure vtable interface. If the event source fires the event as a call to `Invoke`, the vtable methods will never be used and it's clear that the interface should have been a dispinterface. If you define your event interfaces as duals, you'll be requiring clients to implement part of an interface that will never be used. > [!NOTE] diff --git a/docs/atl/dual-interfaces-classes.md b/docs/atl/dual-interfaces-classes.md index b6755655498..c66bd005920 100644 --- a/docs/atl/dual-interfaces-classes.md +++ b/docs/atl/dual-interfaces-classes.md @@ -4,10 +4,11 @@ title: "Dual Interfaces Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["dual interfaces, classes", "dual interfaces"] -ms.assetid: c2b1b165-ff39-4e4a-a683-91eca9158304 --- # Dual Interfaces Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class provides support for dual interfaces: - [IDispatchImpl](../atl/reference/idispatchimpl-class.md) Implements the `IDispatch` portion of a dual interface. For more information, see [Implementing the IDispatch Interface](/previous-versions/windows/desktop/automat/implementing-the-idispatch-interface). diff --git a/docs/atl/enumerators-and-collections-classes.md b/docs/atl/enumerators-and-collections-classes.md index 6ccef203df3..1362c008dee 100644 --- a/docs/atl/enumerators-and-collections-classes.md +++ b/docs/atl/enumerators-and-collections-classes.md @@ -4,10 +4,11 @@ title: "Enumerators and Collections Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["enumerators, ATL classes"] -ms.assetid: fcd093b2-98bf-444d-94ab-9a55520a5051 --- # Enumerators and Collections Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide support for COM collections and enumerations: - [CComEnum](../atl/reference/ccomenum-class.md) Defines a COM enumerator object based on an array. diff --git a/docs/atl/error-information-classes.md b/docs/atl/error-information-classes.md index 5a2a987385b..bea5c2cbbe2 100644 --- a/docs/atl/error-information-classes.md +++ b/docs/atl/error-information-classes.md @@ -4,10 +4,11 @@ title: "Error Information Classe (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["error handling, error information classes", "error handling, classes", "error information, classes"] -ms.assetid: ba40c8fb-81fd-4f61-8f47-fa2cb540e274 --- # Error Information Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class indicates how error information is handled: - [ISupportErrorInfoImpl](../atl/reference/isupporterrorinfoimpl-class.md) Determines whether the object supports the [IErrorInfo](/windows/win32/api/oaidl/nn-oaidl-ierrorinfo) interface. `IErrorInfo` allows error information to be propagated back to the client. diff --git a/docs/atl/event-handling-and-atl.md b/docs/atl/event-handling-and-atl.md index 649b68042c1..9a06e07a6a7 100644 --- a/docs/atl/event-handling-and-atl.md +++ b/docs/atl/event-handling-and-atl.md @@ -3,10 +3,11 @@ description: "Learn more about: Event Handling and ATL" title: "Event Handling and ATL" ms.date: "11/04/2016" helpviewer_keywords: ["event handling, about event handling"] -ms.assetid: e4812b0d-6fdd-4e8c-bdb8-378a25c7bde2 --- # Event Handling and ATL +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + This section shows how to sink events using ATL. It covers the principles of COM event handling and the specifics of sinking events using the support provided by ATL. For information on how to fire events and implement connection points, read [ATL Connection Points](../atl/atl-connection-points.md). diff --git a/docs/atl/event-handling-principles.md b/docs/atl/event-handling-principles.md index 41c766a5e7a..4aba9a8917b 100644 --- a/docs/atl/event-handling-principles.md +++ b/docs/atl/event-handling-principles.md @@ -3,10 +3,11 @@ description: "Learn more about: Event Handling Principles" title: "Event Handling Principles (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["event handling, implementing", "event handling, advising event sources", "interfaces, event and event sink", "dual interfaces, event interfaces", "event handling, dual event interfaces"] -ms.assetid: d17ca7cb-54f2-4658-ab8b-b721ac56801d --- # Event Handling Principles +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + There are three steps common to all event handling. You will need to: - Implement the event interface on your object. diff --git a/docs/atl/example-implementing-a-property-page.md b/docs/atl/example-implementing-a-property-page.md index c6e44f85f6f..57f0ba62255 100644 --- a/docs/atl/example-implementing-a-property-page.md +++ b/docs/atl/example-implementing-a-property-page.md @@ -3,10 +3,12 @@ description: "Learn more about: Example: Implementing a Property Page" title: "Implementing a Property Page (ATL)" ms.date: "05/09/2019" helpviewer_keywords: ["property pages, implementing"] -ms.assetid: c30b67fe-ce08-4249-ae29-f3060fa8d61e +ms.topic: how-to --- # Example: Implementing a Property Page +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/file-handling-classes.md b/docs/atl/file-handling-classes.md index 22602083ecb..da26a0af03f 100644 --- a/docs/atl/file-handling-classes.md +++ b/docs/atl/file-handling-classes.md @@ -4,10 +4,11 @@ title: "File Handling Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["file classes [C++]"] -ms.assetid: 94355eb1-daa3-4825-b183-7392b3899561 --- # File Handling Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + These classes provide methods for handling files, temporary files, and memory-mapped files. - [CAtlFile](../atl/reference/catlfile-class.md) This class provides a thin wrapper around the Windows file-handling API. diff --git a/docs/atl/fundamentals-of-atl-com-objects.md b/docs/atl/fundamentals-of-atl-com-objects.md index afc7adb434f..336b93f9f20 100644 --- a/docs/atl/fundamentals-of-atl-com-objects.md +++ b/docs/atl/fundamentals-of-atl-com-objects.md @@ -3,10 +3,11 @@ description: "Learn more about: Fundamentals of ATL COM Objects" title: "Fundamentals of ATL COM Objects" ms.date: "11/19/2018" helpviewer_keywords: ["COM, and ATL", "ATL, COM", "ATL COM objects", "COM objects, ATL"] -ms.assetid: 0f9c9d98-cc28-45da-89ac-dc94cee422fe --- # Fundamentals of ATL COM Objects +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following illustration depicts the relationship among the classes and interfaces that are used to define an ATL COM object. ![Diagram of the classes and interfaces used to define an A T L object.](../atl/media/vc307y1.gif "ATL structure") diff --git a/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md b/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md index dcf9ebc388c..563f6a8ec03 100644 --- a/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md +++ b/docs/atl/identifying-the-elements-of-the-dhtml-control-project.md @@ -3,10 +3,12 @@ description: "Learn more about: Identifying the Elements of the DHTML Control Pr title: "Identifying the Elements of the DHTML Control Project" ms.date: "11/19/2018" helpviewer_keywords: ["HTML controls, ATL support", "DHTML controls, ATL support"] -ms.assetid: b627547a-3768-4346-9900-4b7a21fb8e27 +ms.topic: concept-article --- # Identifying the Elements of the DHTML Control Project +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Most DHTML control code is exactly like that created for any ATL control. For a basic understanding of the generic code, work through the [ATL tutorial](../atl/active-template-library-atl-tutorial.md), and read the sections [Creating an ATL Project](../atl/reference/creating-an-atl-project.md) and [Fundamentals of ATL COM Objects](../atl/fundamentals-of-atl-com-objects.md). A DHTML control is similar to any ATL control, except: diff --git a/docs/atl/implementing-a-dialog-box.md b/docs/atl/implementing-a-dialog-box.md index b07f0570b52..a416d87a717 100644 --- a/docs/atl/implementing-a-dialog-box.md +++ b/docs/atl/implementing-a-dialog-box.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing a Dialog Box" title: "Implementing a Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["CSimpleDialog class, implementing dialog boxes in ATL", "dialog boxes, ATL", "CAxDialogImpl class, implementing dialog boxes in ATL", "ATL, dialog boxes"] -ms.assetid: 478525f2-aa6a-435a-b162-68fc8aa98a8e +ms.topic: how-to --- # Implementing a Dialog Box +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + There are two ways to add a dialog box to your ATL project: use the ATL Dialog Wizard or add it manually. ## Adding a Dialog Box with the ATL Dialog Wizard diff --git a/docs/atl/implementing-a-dual-interface.md b/docs/atl/implementing-a-dual-interface.md index 0dd114236ca..fc2afff4195 100644 --- a/docs/atl/implementing-a-dual-interface.md +++ b/docs/atl/implementing-a-dual-interface.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing a Dual Interface" title: "Implementing a Dual Interface (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["IDispatchImpl class, implementing dual interfaces", "dual interfaces, implementing"] -ms.assetid: d1da3633-b445-4dcd-8a0a-3efdafada3ea +ms.topic: concept-article --- # Implementing a Dual Interface +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + You can implement a dual interface using the [IDispatchImpl](../atl/reference/idispatchimpl-class.md) class, which provides a default implementation of the `IDispatch` methods in a dual interface. For more information, see [Implementing the IDispatch Interface](/previous-versions/windows/desktop/automat/implementing-the-idispatch-interface). To use this class: diff --git a/docs/atl/implementing-a-window-with-cwindowimpl.md b/docs/atl/implementing-a-window-with-cwindowimpl.md index ec6725d6e06..aaad98298e0 100644 --- a/docs/atl/implementing-a-window-with-cwindowimpl.md +++ b/docs/atl/implementing-a-window-with-cwindowimpl.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing a Window with CWindowImpl" title: "Implementing a Window with CWindowImpl" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "windows [C++], subclassing", "windows [C++], superclassing", "windows [C++], ATL", "subclassing ATL window classes", "superclassing, ATL"] -ms.assetid: 3fc40550-f1d6-4702-8b7c-4cf682b6a855 +ms.topic: how-to --- # Implementing a Window with CWindowImpl +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + To implement a window, derive a class from `CWindowImpl`. In your derived class, declare a message map and the message handler functions. You can now use your class in three different ways: - [Create a window based on a new Windows class](#_atl_creating_a_window_based_on_a_new_windows_class) diff --git a/docs/atl/implementing-a-window.md b/docs/atl/implementing-a-window.md index 6f4137ced3c..478f0fa5750 100644 --- a/docs/atl/implementing-a-window.md +++ b/docs/atl/implementing-a-window.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing a Window" title: "Implementing a Window (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "CWindowImpl class, using", "windows [C++], implementing in ATL"] -ms.assetid: eb1ce8d6-72f9-4894-aae7-e60a61665628 +ms.topic: concept-article --- # Implementing a Window +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Class [CWindowImpl](../atl/reference/cwindowimpl-class.md) allows you to implement a window and handle its messages. Message handing in ATL is based on a message map. This section explains: - How to [add a message handler](../atl/adding-an-atl-message-handler.md) to a control. diff --git a/docs/atl/implementing-an-stl-based-collection.md b/docs/atl/implementing-an-stl-based-collection.md index a01de0c2ba4..5670f233a3b 100644 --- a/docs/atl/implementing-an-stl-based-collection.md +++ b/docs/atl/implementing-an-stl-based-collection.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing a C++ Standard Library-Based Collec title: "Implementing a C++ Standard Library-Based Collection" ms.date: "11/04/2016" helpviewer_keywords: ["ICollectionOnSTLImpl interface"] -ms.assetid: 6d49f819-1957-4813-b074-3f12c494d8ca +ms.topic: how-to --- # Implementing a C++ Standard Library-Based Collection +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL provides the `ICollectionOnSTLImpl` interface to enable you to quickly implement C++ Standard Library-based collection interfaces on your objects. To understand how this class works, you will work through a simple example (below) that uses this class to implement a read-only collection aimed at Automation clients. The sample code is from the [ATLCollections sample](../overview/visual-cpp-samples.md). diff --git a/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md b/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md index c3016ec9b81..1248dc40715 100644 --- a/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md +++ b/docs/atl/implementing-ccomobject-ccomaggobject-and-ccompolyobject.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing CComObject, CComAggObject, and CCom title: "Implementing CComObject, CComAggObject, and CComPolyObject" ms.date: "11/04/2016" helpviewer_keywords: ["CComPolyObject class, implementing", "CreateInstance method", "CComAggObject class", "CComObject class, implementing"] -ms.assetid: 5aabe938-104d-492e-9c41-9f7fb1c62098 +ms.topic: concept-article --- # Implementing CComObject, CComAggObject, and CComPolyObject +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The template classes [CComObject](../atl/reference/ccomobject-class.md), [CComAggObject](../atl/reference/ccomaggobject-class.md), and [CComPolyObject](../atl/reference/ccompolyobject-class.md) are always the most derived classes in the inheritance chain. It is their responsibility to handle all of the methods in `IUnknown`: `QueryInterface`, `AddRef`, and `Release`. In addition, `CComAggObject` and `CComPolyObject` (when used for aggregated objects) provide the special reference counting and `QueryInterface` semantics required for the inner unknown. Whether `CComObject`, `CComAggObject`, or `CComPolyObject` is used depends on whether you declare one (or none) of the following macros: diff --git a/docs/atl/implementing-ccomobjectrootex.md b/docs/atl/implementing-ccomobjectrootex.md index 1c4395557b7..48a7ab9b4de 100644 --- a/docs/atl/implementing-ccomobjectrootex.md +++ b/docs/atl/implementing-ccomobjectrootex.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing CComObjectRootEx" title: "Implementing CComObjectRootEx" ms.date: "11/04/2016" helpviewer_keywords: ["CComObjectRoot class, implementing", "CComObjectRootEx class"] -ms.assetid: 79630c44-f2df-4e9e-b730-400a0ebfbd2b +ms.topic: concept-article --- # Implementing CComObjectRootEx +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + [CComObjectRootEx](../atl/reference/ccomobjectrootex-class.md) is essential; all ATL objects must have one instance of `CComObjectRootEx` or [CComObjectRoot](../atl/reference/ccomobjectroot-class.md) in their inheritance. `CComObjectRootEx` provides the default `QueryInterface` mechanism based on COM map entries. Through its COM map, an object's interfaces are exposed to a client when the client queries for an interface. The query is performed through `CComObjectRootEx::InternalQueryInterface`. `InternalQueryInterface` only handles interfaces in the COM map table. diff --git a/docs/atl/implementing-property-pages.md b/docs/atl/implementing-property-pages.md index 3dcdced9d07..b6fb0ecf5ee 100644 --- a/docs/atl/implementing-property-pages.md +++ b/docs/atl/implementing-property-pages.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing Property Pages" title: "Implementing Property Pages" ms.date: "11/04/2016" helpviewer_keywords: ["IPropertyPage2 class", "IPropertyPage class", "property pages, implementing"] -ms.assetid: 62f29440-33a7-40eb-a1ef-3634c95f640c +ms.topic: how-to --- # Implementing Property Pages +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/implementing-the-event-handling-interface.md b/docs/atl/implementing-the-event-handling-interface.md index 2be79a7b89d..121be8961ce 100644 --- a/docs/atl/implementing-the-event-handling-interface.md +++ b/docs/atl/implementing-the-event-handling-interface.md @@ -3,10 +3,12 @@ description: "Learn more about: Implementing the Event Handling Interface" title: "Implementing the Event Handling Interface" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, event handling", "event handling, ATL", "interfaces, event and event sink"] -ms.assetid: eb2a5b33-88dc-4ce3-bee0-c5c38ea050d7 +ms.topic: concept-article --- # Implementing the Event Handling Interface +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL helps you with all three elements required for handling events: implementing the event interface, advising the event source, and unadvising the event source. The precise steps you'll need to take depend on the type of the event interface and the performance requirements of your application. The most common ways of implementing an interface using ATL are: diff --git a/docs/atl/includes/lifecycle-note.md b/docs/atl/includes/lifecycle-note.md new file mode 100644 index 00000000000..7d403694aaa --- /dev/null +++ b/docs/atl/includes/lifecycle-note.md @@ -0,0 +1,3 @@ +>[!NOTE] +> The Active Template Library (ATL) continues to be supported. However, we're no longer adding features or updating the documentation. + diff --git a/docs/atl/inserting-a-composite-control.md b/docs/atl/inserting-a-composite-control.md index 2a3375c05a9..78e2ee55f0d 100644 --- a/docs/atl/inserting-a-composite-control.md +++ b/docs/atl/inserting-a-composite-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Inserting a Composite Control" title: "Inserting a Composite Control" ms.date: "11/04/2016" helpviewer_keywords: ["composite controls, inserting with ATL Object Wizard", "composite controls", "ATL Control Wizard"] -ms.assetid: f10b1927-9fc6-40a7-ac29-efdac70584fe +ms.topic: how-to --- # Inserting a Composite Control +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The **Add Class** dialog box allows you to insert an ATL object into a project. Access this dialog box by right-clicking the project name in Solution Explorer, pointing to **Add**, and then clicking **Add Class**. In the **Add Class** dialog box, choose **ATL Control**. This will start the [ATL Control Wizard](../atl/reference/atl-control-wizard.md). To create a composite control, select the **Options** tab, and click the **Composite control** check box. diff --git a/docs/atl/interface-pointers-classes.md b/docs/atl/interface-pointers-classes.md index d54f0ad4aa5..06f9c44a043 100644 --- a/docs/atl/interface-pointers-classes.md +++ b/docs/atl/interface-pointers-classes.md @@ -4,10 +4,11 @@ title: "Interface Pointers Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["pointers, to interfaces", "interfaces, pointers classes", "interface pointers classes"] -ms.assetid: 712617a1-17ae-4b5c-a32c-a48b758df7a6 --- # Interface Pointers Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes manage a given interface pointer: - [CComPtr](../atl/reference/ccomptr-class.md) Performs automatic reference counting. diff --git a/docs/atl/interfaces-atl.md b/docs/atl/interfaces-atl.md index 93422d3cd23..1b36fe72cec 100644 --- a/docs/atl/interfaces-atl.md +++ b/docs/atl/interfaces-atl.md @@ -4,10 +4,11 @@ title: "Interfaces (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["COM interfaces", "interfaces, COM"] -ms.assetid: de6c8b12-6230-4fdc-af66-a28b91d5ee55 --- # Interfaces (ATL) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + An interface is the way in which an object exposes its functionality to the outside world. In COM, an interface is a table of pointers (like a C++ vtable) to functions implemented by the object. The table represents the interface, and the functions to which it points are the methods of that interface. An object can expose as many interfaces as it chooses. Each interface is based on the fundamental COM interface, [IUnknown](../atl/iunknown.md). The methods of `IUnknown` allow navigation to other interfaces exposed by the object. diff --git a/docs/atl/introduction-to-atl-window-classes.md b/docs/atl/introduction-to-atl-window-classes.md index a4593ae915b..6c245514d51 100644 --- a/docs/atl/introduction-to-atl-window-classes.md +++ b/docs/atl/introduction-to-atl-window-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Introduction to ATL Window Classes" title: "Introduction to ATL Window Classes" ms.date: "11/04/2016" helpviewer_keywords: ["window classes"] -ms.assetid: 503efc2c-a269-495d-97cf-3fb300d52f3d +ms.topic: concept-article --- # Introduction to ATL Window Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following ATL classes are designed to implement and manipulate windows: - [CWindow](../atl/reference/cwindow-class.md) allows you to attach a window handle to the `CWindow` object. You then call `CWindow` methods to manipulate the window. diff --git a/docs/atl/introduction-to-atl.md b/docs/atl/introduction-to-atl.md index 104ef1d2749..0a62bded508 100644 --- a/docs/atl/introduction-to-atl.md +++ b/docs/atl/introduction-to-atl.md @@ -4,10 +4,12 @@ title: "Introduction to ATL" ms.custom: "index-page" ms.date: "11/04/2016" helpviewer_keywords: ["COM objects, creating in ATL", "ATL"] -ms.assetid: 77f565e8-c4ec-4a80-af4b-7278fcfe5c98 +ms.topic: concept-article --- # Introduction to ATL +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL is the Active Template Library, a set of template-based C++ classes with which you can easily create small, fast Component Object Model (COM) objects. It has special support for key COM features including: stock implementations of [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown), [IClassFactory](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory), [IClassFactory2](/windows/win32/api/ocidl/nn-ocidl-iclassfactory2), and `IDispatch`; dual interfaces; standard COM enumerator interfaces; connection points; tear-off interfaces; and ActiveX controls. ATL code can be used to create single-threaded objects, apartment-model objects, free-threaded model objects, or both free-threaded and apartment-model objects. diff --git a/docs/atl/introduction-to-com-and-atl.md b/docs/atl/introduction-to-com-and-atl.md index 8cb151d30af..47447c9ebdb 100644 --- a/docs/atl/introduction-to-com-and-atl.md +++ b/docs/atl/introduction-to-com-and-atl.md @@ -4,10 +4,12 @@ title: "Introduction to COM and ATL" ms.custom: "index-page" ms.date: "11/04/2016" helpviewer_keywords: ["COM, and ATL", "ATL, COM", "COM objects, ATL"] -ms.assetid: 35d6ae9c-abbb-42f0-9344-33f3c19ac3ce +ms.topic: concept-article --- # Introduction to COM and ATL +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + This section provides a brief introduction to COM and ATL. ## In This Section diff --git a/docs/atl/introduction-to-com.md b/docs/atl/introduction-to-com.md index c90f0c03ce3..8b192520ef9 100644 --- a/docs/atl/introduction-to-com.md +++ b/docs/atl/introduction-to-com.md @@ -4,10 +4,12 @@ title: "Introduction to COM" ms.custom: "index-page" ms.date: "11/04/2016" helpviewer_keywords: ["COM"] -ms.assetid: 120735d9-db71-4ad3-a730-ce576ea2354e +ms.topic: concept-article --- # Introduction to COM +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + COM is the fundamental "object model" on which ActiveX Controls and OLE are built. COM allows an object to expose its functionality to other components and to host applications. It defines both how the object exposes itself and how this exposure works across processes and across networks. COM also defines the object's life cycle. Fundamental to COM are these concepts: diff --git a/docs/atl/invoking-scripts.md b/docs/atl/invoking-scripts.md index 459197b82d0..3cc906049fc 100644 --- a/docs/atl/invoking-scripts.md +++ b/docs/atl/invoking-scripts.md @@ -3,10 +3,12 @@ description: "Learn more about: Invoking Scripts" title: "Invoking Scripts (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["StringRegister method", "scripts, invoking registry in ATL"] -ms.assetid: eabd41ee-586b-4266-9e92-5aaad04b73a4 +ms.topic: concept-article --- # Invoking Scripts +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + [Using Replaceable Parameters (The Registrar's Preprocessor)](../atl/using-replaceable-parameters-the-registrar-s-preprocessor.md) discusses replacement maps and mentions the Registrar method **AddReplacement**. The Registrar has eight other methods specific to scripting, and all are described in the following table. |Method|Syntax/Description| diff --git a/docs/atl/iunknown-implementation-classes.md b/docs/atl/iunknown-implementation-classes.md index 7721fad35c6..a64a723fe84 100644 --- a/docs/atl/iunknown-implementation-classes.md +++ b/docs/atl/iunknown-implementation-classes.md @@ -4,10 +4,11 @@ title: "IUnknown Implementation Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["IUnknown implementation classes"] -ms.assetid: 47b69bb5-69d8-4a9c-84a8-329bdde2bb3f --- # IUnknown Implementation Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes implement `IUnknown` and related methods: - [CComObjectRootEx](../atl/reference/ccomobjectrootex-class.md) Manages reference counting for both aggregated and nonaggregated objects. Allows you to specify a threading model. diff --git a/docs/atl/iunknown.md b/docs/atl/iunknown.md index ee1578aa31f..e466a86e6a5 100644 --- a/docs/atl/iunknown.md +++ b/docs/atl/iunknown.md @@ -4,10 +4,11 @@ title: "IUnknown" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["COM interfaces, base interface", "IUnknown interface"] -ms.assetid: e6b85472-e54b-4b8c-b19f-4454d6c05a8f --- # IUnknown +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) is the base interface of every other COM interface. This interface defines three methods: [QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)), [AddRef](/windows/win32/api/unknwn/nf-unknwn-iunknown-addref), and [Release](/windows/win32/api/unknwn/nf-unknwn-iunknown-release). [QueryInterface](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)) allows an interface user to ask the object for a pointer to another of its interfaces. [AddRef](/windows/win32/api/unknwn/nf-unknwn-iunknown-addref) and [Release](/windows/win32/api/unknwn/nf-unknwn-iunknown-release) implement reference counting on the interface. ## See also diff --git a/docs/atl/linking-to-the-crt-in-your-atl-project.md b/docs/atl/linking-to-the-crt-in-your-atl-project.md index d67da0b10b4..3e5d84ca794 100644 --- a/docs/atl/linking-to-the-crt-in-your-atl-project.md +++ b/docs/atl/linking-to-the-crt-in-your-atl-project.md @@ -3,10 +3,12 @@ description: "Learn more about: Linking to the CRT in Your ATL Project" title: "Linking to the CRT in Your ATL Project" ms.date: "11/04/2016" helpviewer_keywords: ["CRT, linking with ATL", "WinMainCRTStartup method", "DllMainCRTStartup method", "wWinMainCRTStartup method", "ATL, C Run-Time library (CRT)"] -ms.assetid: 650957ae-362c-4ecf-8b03-5d49138e8b5b +ms.topic: concept-article --- # Linking to the CRT in Your ATL Project +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The [C Run-Time Libraries](../c-runtime-library/crt-library-features.md) (CRT) provide many useful functions that can make programming much easier during ATL development. All ATL projects link to the CRT library. You can see the advantages and disadvantages of linking method in [Benefits and Tradeoffs of the Method Used to Link to the CRT](../atl/benefits-and-tradeoffs-of-the-method-used-to-link-to-the-crt.md). ## Effects of Linking to the CRT on Your Program Image diff --git a/docs/atl/marshaling.md b/docs/atl/marshaling.md index 03501d803f1..28f1c0f3582 100644 --- a/docs/atl/marshaling.md +++ b/docs/atl/marshaling.md @@ -3,10 +3,12 @@ description: "Learn more about: Marshaling" title: "Marshaling" ms.date: "11/04/2016" helpviewer_keywords: ["marshaling, COM interop", "marshaling", "COM interfaces, marshaling"] -ms.assetid: 40644b0a-1106-4fc8-9dfb-9bee9915d825 +ms.topic: concept-article --- # Marshaling +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The COM technique of marshaling allows interfaces exposed by an object in one process to be used in another process. In marshaling, COM provides code (or uses code provided by the interface implementor) both to pack a method's parameters into a format that can be moved across processes (as well as, across the wire to processes running on other machines) and to unpack those parameters at the other end. Likewise, COM must perform these same steps on the return from the call. > [!NOTE] diff --git a/docs/atl/memory-management-classes.md b/docs/atl/memory-management-classes.md index 680e61f19de..89bea5d1d08 100644 --- a/docs/atl/memory-management-classes.md +++ b/docs/atl/memory-management-classes.md @@ -4,10 +4,11 @@ title: "Memory Management Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["memory, managing"] -ms.assetid: be564a5e-577e-40a7-bfe3-25ad21e57270 --- # Memory Management Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + These classes provide support for heap pointers, smart pointers, and other memory allocation routines. - [CAutoPtr](../atl/reference/cautoptr-class.md) This class represents a smart pointer object. diff --git a/docs/atl/message-handler-functions.md b/docs/atl/message-handler-functions.md index a37dc85d188..e478109d521 100644 --- a/docs/atl/message-handler-functions.md +++ b/docs/atl/message-handler-functions.md @@ -4,10 +4,11 @@ title: "Message Handler Functions" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["MESSAGE_HANDLER macro", "COMMAND_HANDLER macro", "CommandHandler method", "MessageHandler method", "NotifyHandler method", "message maps, ATL", "NOTIFY_HANDLER macro, message handler functions", "ATL, message handlers"] -ms.assetid: 2007a8c5-0143-42f1-91ab-809f235f9d50 --- # Message Handler Functions +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL provides three types of message handler functions: |Type of message handler|Corresponding message macro| diff --git a/docs/atl/message-maps-atl.md b/docs/atl/message-maps-atl.md index 0ab8a690a8f..6b0ab765a4d 100644 --- a/docs/atl/message-maps-atl.md +++ b/docs/atl/message-maps-atl.md @@ -4,10 +4,11 @@ title: "Message Maps (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["message maps, ATL", "ATL, message handlers"] -ms.assetid: 9e100400-65c7-4a85-8857-4e6cb6dd7340 --- # Message Maps (ATL) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A message map associates a handler function with a particular message, command, or notification. By using ATL's [message map macros](../atl/reference/message-map-macros-atl.md), you can specify a message map for a window. The window procedures in `CWindowImpl`, `CDialogImpl`, and `CContainedWindowT` direct a window's messages to its message map. The [message handler functions](../atl/message-handler-functions.md) accept an additional argument of type `BOOL&`. This argument indicates whether a message has been processed, and it is set to TRUE by default. A handler function can then set the argument to FALSE to indicate that it has not handled a message. In this case, ATL will continue to look for a handler function further in the message map. By setting this argument to FALSE, you can first perform some action in response to a message and then allow the default processing or another handler function to finish handling the message. diff --git a/docs/atl/messagehandler.md b/docs/atl/messagehandler.md index 4fcdaad53bd..4fa25ca0ead 100644 --- a/docs/atl/messagehandler.md +++ b/docs/atl/messagehandler.md @@ -4,10 +4,11 @@ title: "MessageHandler" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["MessageHandler function"] -ms.assetid: 8a0acf97-1b0d-4226-91b9-75446634a03c --- # MessageHandler +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + `MessageHandler` is the name of the function identified by the second parameter of the MESSAGE_HANDLER macro in your message map. ## Syntax diff --git a/docs/atl/mmc-snap-in-classes.md b/docs/atl/mmc-snap-in-classes.md index 140e10dc5e1..62c9af27f64 100644 --- a/docs/atl/mmc-snap-in-classes.md +++ b/docs/atl/mmc-snap-in-classes.md @@ -4,10 +4,11 @@ title: "MMC Snap-In Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["MMC Snap-In classes"] -ms.assetid: 4af1d5af-687f-48b1-b2c5-fa252241b4d6 --- # MMC Snap-In Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide support for developing Microsoft Management Console (MMC) snap-in components: - [CSnapInItemImpl](../atl/reference/csnapinitemimpl-class.md) Implements a snap-in node object, such as adding menu items and toolbars, and forwarding commands for the snap-in node to the appropriate handler function. diff --git a/docs/atl/modifying-the-atl-dhtml-control.md b/docs/atl/modifying-the-atl-dhtml-control.md index 559c5470378..34fab00665a 100644 --- a/docs/atl/modifying-the-atl-dhtml-control.md +++ b/docs/atl/modifying-the-atl-dhtml-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Modifying the ATL DHTML Control" title: "Modifying the ATL DHTML Control" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, modifying", "DHTML controls", "DHTML controls, modifying"] -ms.assetid: c053f35f-8629-4600-9595-721f5956777a +ms.topic: how-to --- # Modifying the ATL DHTML Control +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The ATL Control Wizard provides starter code so you can build and run the control, and so you can see how the methods are written in the project files and how the DHTML calls into the control's C++ code using the dispatch methods. You can add any dispatch method to the interface. Then, you can call the methods in the HTML resource. ## To modify the ATL DHTML control diff --git a/docs/atl/modifying-the-atl-project.md b/docs/atl/modifying-the-atl-project.md index b2a4b44bc82..7b87fb2adbf 100644 --- a/docs/atl/modifying-the-atl-project.md +++ b/docs/atl/modifying-the-atl-project.md @@ -3,10 +3,12 @@ description: "Learn more about: Modifying the ATL Project" title: "Modifying the ATL Project" ms.date: "11/04/2016" helpviewer_keywords: ["controls [ATL], adding to composite controls", "Dialog editor, working with composite controls", "composite controls, adding controls"] -ms.assetid: 59984518-748f-4b8b-875f-3e97d22d0b0f +ms.topic: concept-article --- # Modifying the ATL Project +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + At this point, your composite control project implements the necessary objects for your composite control. The next step is to add any controls that the composite control will contain and handle any necessary events. To add additional ActiveX or Windows controls, add a new resource script and then use the Dialog editor. For more information on adding controls (and related tasks), see [Dialog Editor](../windows/dialog-editor.md). diff --git a/docs/atl/multiple-dual-interfaces.md b/docs/atl/multiple-dual-interfaces.md index 99c43025249..52b22900163 100644 --- a/docs/atl/multiple-dual-interfaces.md +++ b/docs/atl/multiple-dual-interfaces.md @@ -4,10 +4,11 @@ title: "Multiple Dual Interfaces" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["multiple dual interfaces", "COM_INTERFACE_ENTRY2 macro", "dual interfaces, exposing multiple", "multiple dual interfaces, exposing with ATL", "IDispatchImpl class, multiple dual interfaces", "COM_INTERFACE_ENTRY_IID macro"] -ms.assetid: 7fea86e6-247f-4063-be6e-85588a9e3719 --- # Multiple Dual Interfaces +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + You may want to combine the advantages of a dual interface (that is, the flexibility of both vtable and late binding, thus making the class available to scripting languages as well as C++) with the techniques of multiple inheritance. Although it is possible to expose multiple dual interfaces on a single COM object, it is not recommended. If there are multiple dual interfaces, there must be only one `IDispatch` interface exposed. The techniques available to ensure that this is the case carry penalties such as loss of function or increased code complexity. The developer considering this approach should carefully weigh the advantages and disadvantages. diff --git a/docs/atl/nonextensible-attribute.md b/docs/atl/nonextensible-attribute.md index 08a854a4873..517f6ad1da7 100644 --- a/docs/atl/nonextensible-attribute.md +++ b/docs/atl/nonextensible-attribute.md @@ -3,10 +3,11 @@ description: "Learn more about: nonextensible Attribute" title: "nonextensible Attribute" ms.date: "11/04/2016" helpviewer_keywords: ["nonextensible attribute", "dual interfaces, nonextensible attribute"] -ms.assetid: 02a4a18b-ffd3-4d53-8fd1-feb1c05ad5ac --- # nonextensible Attribute +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + If a dual interface will not be extended at run time (that is, you won't provide methods or properties via `IDispatch::Invoke` that are not available via the vtable), you should apply the **nonextensible** attribute to your interface definition. This attribute provides information to client languages (such as Visual Basic) that can be used to enable full code verification at compile time. If this attribute is not supplied, bugs may remain hidden in the client code until run time. For more information on the **nonextensible** attribute and an example, see [nonextensible](../windows/attributes/nonextensible.md). diff --git a/docs/atl/notifyhandler.md b/docs/atl/notifyhandler.md index adb1d4a0db6..deaf83115cf 100644 --- a/docs/atl/notifyhandler.md +++ b/docs/atl/notifyhandler.md @@ -4,10 +4,11 @@ title: "NotifyHandler" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["NotifyHandler function"] -ms.assetid: 5ff953ec-de35-42bc-8b3c-d384d636c139 --- # NotifyHandler +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The name of the function identified by the third parameter of the NOTIFY_HANDLER macro in your message map. ## Syntax diff --git a/docs/atl/object-safety-classes.md b/docs/atl/object-safety-classes.md index 29b2fbdcae9..69ec66cf8eb 100644 --- a/docs/atl/object-safety-classes.md +++ b/docs/atl/object-safety-classes.md @@ -1,13 +1,14 @@ --- 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"] -ms.assetid: 00060b28-49e2-4ec1-9a22-f501e07821d6 --- # Object Safety Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class provides support for object safety: - [IObjectSafetyImpl](../atl/reference/iobjectsafetyimpl-class.md) Allows an object to be marked as safe for initialization or safe for scripting. diff --git a/docs/atl/persistence-classes.md b/docs/atl/persistence-classes.md index bce7966eb71..18d1a4e3826 100644 --- a/docs/atl/persistence-classes.md +++ b/docs/atl/persistence-classes.md @@ -4,10 +4,11 @@ title: "Persistence Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["persistence classes", "persistence, classes"] -ms.assetid: a6a2b6b2-52bc-471c-b78a-de58363128bb --- # Persistence Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes implement object persistence: - [IPersistPropertyBagImpl](../atl/reference/ipersistpropertybagimpl-class.md) Allows a client to load and save an object's properties to a property bag. diff --git a/docs/atl/programming-with-atl-and-c-run-time-code.md b/docs/atl/programming-with-atl-and-c-run-time-code.md index 697a3c67502..804e19a5600 100644 --- a/docs/atl/programming-with-atl-and-c-run-time-code.md +++ b/docs/atl/programming-with-atl-and-c-run-time-code.md @@ -3,10 +3,12 @@ description: "Learn more about: Programming with ATL and C Run-Time Code" title: "Programming with ATL and C Run-Time Code" ms.date: "11/04/2016" helpviewer_keywords: ["ATL_MIN_CRT macro", "CRT, using with ATL", "_ATL_MIN_CRT macro", "ATL, C Run-Time library (CRT)"] -ms.assetid: 20f03b66-1eb7-4add-84a2-6047db0911eb +ms.topic: concept-article --- # Programming with ATL and C Run-Time Code +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + This section discusses the benefits of using the C Run-Time Library (CRT) with either static or dynamic linking. ## In This Section diff --git a/docs/atl/programming-with-ccombstr-atl.md b/docs/atl/programming-with-ccombstr-atl.md index 74c5c544656..c1b044ae46b 100644 --- a/docs/atl/programming-with-ccombstr-atl.md +++ b/docs/atl/programming-with-ccombstr-atl.md @@ -3,10 +3,12 @@ description: "Learn more about: Programming with CComBSTR (ATL)" title: "Programming with CComBSTR (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["CComBSTR class, programming with", "Unicode, using CComBSTR [ATL]"] -ms.assetid: d3bd0851-d132-4be9-9c4c-6ccba17acb2b +ms.topic: concept-article --- # Programming with CComBSTR (ATL) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The ATL class [CComBSTR](../atl/reference/ccombstr-class.md) provides a wrapper around the BSTR data type. While `CComBSTR` is a useful tool, there are several situations that require caution. - [Conversion Issues](#programmingwithccombstr_conversionissues) diff --git a/docs/atl/properties-and-property-pages-classes.md b/docs/atl/properties-and-property-pages-classes.md index 17e8307bb07..9fafa9baf65 100644 --- a/docs/atl/properties-and-property-pages-classes.md +++ b/docs/atl/properties-and-property-pages-classes.md @@ -4,10 +4,11 @@ title: "Properties and Property Pages Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["property pages, classes", "properties [ATL], classes", "properties [ATL]"] -ms.assetid: 31616f98-69f8-48b2-8d58-b8e7d1c2b2d8 --- # Properties and Property Pages Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes support properties and property pages: - [CComDispatchDriver](../atl/reference/atl-typedefs.md#ccomdispatchdriver) Retrieves or sets an object's properties through an `IDispatch` pointer. diff --git a/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md b/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md index 9bfba0d8732..b191688f163 100644 --- a/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md +++ b/docs/atl/putting-the-control-on-a-web-page-atl-tutorial-part-7.md @@ -3,10 +3,12 @@ description: "Learn more about: Putting the Control on a Web Page (ATL Tutorial, title: "Putting the Control on a Web Page (ATL Tutorial, Part 7)" ms.custom: "get-started-article" ms.date: "05/06/2019" -ms.assetid: 50dc4c95-c95b-4006-b88a-9826f7bdb222 +ms.topic: tutorial --- # Putting the Control on a Web Page (ATL Tutorial, Part 7) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Your control is now finished. To see your control work in a real-world situation, put it on a Web page. An HTML file that contains the control was created when you defined your control. Open the PolyCtl.htm file from **Solution Explorer**, and you can see your control on a Web page. In this step, you add functionality to the control and script the Web page to respond to events. You'll also modify the control to let Internet Explorer know the control is safe for scripting. @@ -15,30 +17,30 @@ In this step, you add functionality to the control and script the Web page to re ### To add control features -1. Open PolyCtl.cpp and replace the following code: - - ```cpp - if (PtInRegion(hRgn, xPos, yPos)) - Fire_ClickIn(xPos, yPos); - else - Fire_ClickOut(xPos, yPos); - ``` - - with - - ```cpp - short temp = m_nSides; - if (PtInRegion(hRgn, xPos, yPos)) - { - Fire_ClickIn(xPos, yPos); - put_Sides(++temp); - } - else - { - Fire_ClickOut(xPos, yPos); - put_Sides(--temp); - } - ``` +Open PolyCtl.cpp and replace the following code: + +```cpp +if (PtInRegion(hRgn, xPos, yPos)) + Fire_ClickIn(xPos, yPos); +else + Fire_ClickOut(xPos, yPos); +``` + +with + +```cpp +short temp = m_nSides; +if (PtInRegion(hRgn, xPos, yPos)) +{ + Fire_ClickIn(xPos, yPos); + put_Sides(++temp); +} +else +{ + Fire_ClickOut(xPos, yPos); + put_Sides(--temp); +} +``` The shape will now add or remove sides depending on where you click. diff --git a/docs/atl/queryinterface.md b/docs/atl/queryinterface.md index 3d982e0e938..6849e52d2cd 100644 --- a/docs/atl/queryinterface.md +++ b/docs/atl/queryinterface.md @@ -4,10 +4,11 @@ title: "QueryInterface" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["interfaces, pointers", "interfaces, availability", "QueryInterface method"] -ms.assetid: 62fce95e-aafa-4187-b50b-e6611b74c3b3 --- # `QueryInterface` +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Although there are mechanisms by which an object can express the functionality it provides statically (before it is instantiated), the fundamental COM mechanism is to use the `IUnknown` method called [`QueryInterface`](/windows/win32/api/unknwn/nf-unknwn-iunknown-queryinterface(q)). Every interface is derived from `IUnknown`, so every interface has an implementation of `QueryInterface`. Regardless of implementation, this method queries an object using the `IID` of the interface to which the caller wants a pointer. If the object supports that interface, `QueryInterface` retrieves a pointer to the interface, while also calling `AddRef`. Otherwise, it returns the `E_NOINTERFACE` error code. diff --git a/docs/atl/recommendations-for-choosing-between-atl-and-mfc.md b/docs/atl/recommendations-for-choosing-between-atl-and-mfc.md index 2fc4145a2b8..f52522b644c 100644 --- a/docs/atl/recommendations-for-choosing-between-atl-and-mfc.md +++ b/docs/atl/recommendations-for-choosing-between-atl-and-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Recommendations for Choosing Between ATL and MFC title: "Recommendations for Choosing Between ATL and MFC" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, ATL support", "ATL, vs. MFC"] -ms.assetid: 269325bb-11a8-4330-ad2b-a14a2458679e --- # Recommendations for Choosing Between ATL and MFC +>[!NOTE] +> The Microsoft Foundation Classes library (MFC) and Active Template Library (ATL) continue to be supported. However, we're no longer adding features or updating the documentation. + When developing components and applications, you can choose between two approaches — ATL and MFC (the Microsoft Foundation Class Library). ## Using ATL diff --git a/docs/atl/reference-counting.md b/docs/atl/reference-counting.md index db71a9ca66c..594cc68c495 100644 --- a/docs/atl/reference-counting.md +++ b/docs/atl/reference-counting.md @@ -3,10 +3,11 @@ description: "Learn more about: Reference Counting" title: "Reference Counting (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["AddRef method [C++], reference counting", "reference counting", "AddRef method [C++]", "reference counts", "references, counting"] -ms.assetid: b1fd4514-6de6-429f-9e60-2777c0d07a3d --- # Reference Counting +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + COM itself does not automatically try to remove an object from memory when it thinks the object is no longer being used. Instead, the object programmer must remove the unused object. The programmer determines whether an object can be removed based on a reference count. COM uses the `IUnknown` methods, [AddRef](/windows/win32/api/unknwn/nf-unknwn-iunknown-addref) and [Release](/windows/win32/api/unknwn/nf-unknwn-iunknown-release), to manage the reference count of interfaces on an object. The general rules for calling these methods are: diff --git a/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md b/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md index f9b927b58c0..04bda95f84c 100644 --- a/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md +++ b/docs/atl/reference/adding-a-new-interface-in-an-atl-project.md @@ -4,10 +4,11 @@ title: "Adding a New Interface in an ATL Project" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.ATL.interface"] helpviewer_keywords: ["interfaces, adding to ATL objects", "Implement Interface ATL wizard", "controls [ATL], interfaces", "ATL projects, adding interfaces"] -ms.assetid: 7d34b023-2c6b-4155-aca3-d47a40968063 --- # Adding a New Interface in an ATL Project +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + When you add an interface to your object or control, you create stubbed-out functions for each method in that interface. In your object or control, you can add only interfaces currently found in an existing type library. Also, the class in which you add the interface must implement the [BEGIN_COM_MAP](com-map-macros.md#begin_com_map) macro or, if the project is attributed, it must have the `coclass` attribute. You can add a new interface to your control in one of two ways: manually or using code wizards in Class View. diff --git a/docs/atl/reference/adding-an-atl-active-server-page-component.md b/docs/atl/reference/adding-an-atl-active-server-page-component.md index 508bf1fbfca..9b0aa9b0b73 100644 --- a/docs/atl/reference/adding-an-atl-active-server-page-component.md +++ b/docs/atl/reference/adding-an-atl-active-server-page-component.md @@ -2,10 +2,11 @@ description: "Learn more about: Adding an ATL Active Server Page Component" title: "Adding an ATL Active Server Page Component" ms.date: "05/09/2019" -ms.assetid: 7be2204c-6e58-4099-8892-001b848c8987 --- # Adding an ATL Active Server Page Component +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL Active Server Pages component wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md b/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md index 6df0a367ba5..b04378c1ea7 100644 --- a/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md +++ b/docs/atl/reference/adding-an-atl-com-plus-1-0-component.md @@ -2,10 +2,11 @@ description: "Learn more about: Adding an ATL COM+ 1.0 Component" title: "Adding an ATL COM+ 1.0 Component" ms.date: "05/09/2019" -ms.assetid: c6c95e64-9ee4-4a6e-8804-5930202ce1b9 --- # Adding an ATL COM+ 1.0 Component +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL COM+ 1.0 Component wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/adding-an-atl-control.md b/docs/atl/reference/adding-an-atl-control.md index c9a01745336..e62a42cd078 100644 --- a/docs/atl/reference/adding-an-atl-control.md +++ b/docs/atl/reference/adding-an-atl-control.md @@ -3,10 +3,11 @@ description: "Learn more about: Adding an ATL Control" title: "Adding an ATL Control" ms.date: "11/04/2016" helpviewer_keywords: ["ATL projects, adding controls", "controls [ATL], adding to projects"] -ms.assetid: 10223e7e-fdb7-4163-80c6-44aeafa8e6ce --- # Adding an ATL Control +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this wizard to add a user interface object to a project that supports interfaces for all potential containers. To support these interfaces, the project must have been created as an ATL application or as an MFC application that contains ATL support. You can use the [ATL Project Wizard](../../atl/reference/atl-project-wizard.md) to create an ATL application, or [add an ATL object to your MFC application](../../mfc/reference/adding-atl-support-to-your-mfc-project.md) to implement ATL support for an MFC application. ## To add an ATL control to your project diff --git a/docs/atl/reference/adding-an-atl-dialog-box.md b/docs/atl/reference/adding-an-atl-dialog-box.md index 928fd204304..e7519718ea2 100644 --- a/docs/atl/reference/adding-an-atl-dialog-box.md +++ b/docs/atl/reference/adding-an-atl-dialog-box.md @@ -3,10 +3,11 @@ description: "Learn more about: Adding an ATL Dialog Box" title: "Adding an ATL Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["ATL projects, adding dialog resources", "MFC dialog boxes, ATL dialogs", "dialog boxes, ATL"] -ms.assetid: 152a378f-7b24-4f66-aeba-c740973f03a6 --- # Adding an ATL Dialog Box +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + To add an ATL dialog to your project, your project must be either an ATL project or an MFC project that includes ATL support. You can use the [ATL Project Wizard](../../atl/reference/atl-project-wizard.md) to create an ATL application, or [add an ATL object to your MFC application](../../mfc/reference/adding-atl-support-to-your-mfc-project.md) to implement ATL support for an MFC application. By default, the ATL Dialog Wizard implements a dialog box derived from [CAxDialogImpl](../../atl/reference/caxdialogimpl-class.md). This class includes support for hosting ActiveX and Windows controls. If you do not want the overhead of ActiveX control support, once the wizard has generated your code, replace all instances of `CAxDialogImpl` with either [CSimpleDialog](../../atl/reference/csimpledialog-class.md) or [CDialogImpl](../../atl/reference/cdialogimpl-class.md) as your base class. diff --git a/docs/atl/reference/adding-an-atl-ole-db-consumer.md b/docs/atl/reference/adding-an-atl-ole-db-consumer.md index 52b1acc39ab..52b42c75ed2 100644 --- a/docs/atl/reference/adding-an-atl-ole-db-consumer.md +++ b/docs/atl/reference/adding-an-atl-ole-db-consumer.md @@ -3,10 +3,11 @@ description: "Learn more about: Adding an ATL OLE DB Consumer" title: "Adding an ATL OLE DB Consumer" ms.date: "05/09/2019" helpviewer_keywords: ["ATL OLE DB consumers"] -ms.assetid: f940a513-4e42-4148-b521-dd0d7dc89fa2 --- # Adding an ATL OLE DB Consumer +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL OLE DB Consumer wizard is not available in Visual Studio 2019 and later. You can still add the functionality manually. For more information, see [Creating a Consumer Without Using a Wizard](../../data/oledb/creating-a-consumer-without-using-a-wizard.md). diff --git a/docs/atl/reference/adding-an-atl-ole-db-provider.md b/docs/atl/reference/adding-an-atl-ole-db-provider.md index 3aba76e606f..908e53502a3 100644 --- a/docs/atl/reference/adding-an-atl-ole-db-provider.md +++ b/docs/atl/reference/adding-an-atl-ole-db-provider.md @@ -3,10 +3,11 @@ description: "Learn more about: Adding an ATL OLE DB Provider" title: "Adding an ATL OLE DB Provider" ms.date: "05/09/2019" helpviewer_keywords: ["OLE DB, adding ATL OLE DB provider to projects", "ATL projects, adding ATL OLE DB providers", "ATL OLE DB providers"] -ms.assetid: 26fba1e3-880f-4bc6-90e5-2096a48a3a6c --- # Adding an ATL OLE DB Provider +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL OLE DB Provider wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/adding-an-atl-property-page.md b/docs/atl/reference/adding-an-atl-property-page.md index 376b4875a7f..543c72db463 100644 --- a/docs/atl/reference/adding-an-atl-property-page.md +++ b/docs/atl/reference/adding-an-atl-property-page.md @@ -3,10 +3,11 @@ description: "Learn more about: Adding an ATL Property Page" title: "Adding an ATL Property Page" ms.date: "05/09/2019" helpviewer_keywords: ["property pages, adding", "ATL projects, adding property pages", "controls [ATL], property pages"] -ms.assetid: ddf92b49-42a2-46d2-b6b8-d37baedebeca --- # Adding an ATL Property Page +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + > [!NOTE] > The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/adding-an-atl-simple-object.md b/docs/atl/reference/adding-an-atl-simple-object.md index 91e8e2ddac4..53c4b37fd33 100644 --- a/docs/atl/reference/adding-an-atl-simple-object.md +++ b/docs/atl/reference/adding-an-atl-simple-object.md @@ -4,10 +4,11 @@ title: "Adding an ATL Simple Object" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.classes.adding.atl"] helpviewer_keywords: ["ATL projects, adding objects", "objects [ATL]", "ATL, simple objects"] -ms.assetid: 9c57d2ef-0447-4c84-8982-3304b8e49847 --- # Adding an ATL Simple Object +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + To add an ATL (Active Template Library) object to your project, your project must have been created as an ATL application or as an MFC application that contains ATL support. You can use the [ATL Project Wizard](../../atl/reference/atl-project-wizard.md) to create an ATL application, or [add an ATL object to your MFC application](../../mfc/reference/adding-atl-support-to-your-mfc-project.md) to implement ATL support for an MFC application. You can define COM interfaces for your new ATL object when you first create it, or add them later by using the [Implement Interface](../../ide/implementing-an-interface-visual-cpp.md#implement-interface-wizard) command from the **Class View** shortcut menu. diff --git a/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md b/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md index 036b72dc54c..f77dfceb83e 100644 --- a/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md +++ b/docs/atl/reference/adding-objects-and-controls-to-an-atl-project.md @@ -4,10 +4,11 @@ title: "Adding Objects and Controls to an ATL Project" ms.date: "05/09/2019" f1_keywords: ["vc.appwiz.ATL.controls"] helpviewer_keywords: ["ATL projects, adding objects", "wizards [C++], ATL projects", "ATL projects, adding controls", "controls [ATL], adding to projects", "objects [C++], adding to ATL projects", "ATL Control Wizard"] -ms.assetid: c0adcbd0-07fe-4c55-a8fd-8c2c65ecdaad --- # Adding Objects and Controls to an ATL Project +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + > [!NOTE] > The ATL COM+ 1.0 Component Wizard, ATL OLE DB Consumer wizard, and ATL Active Server Page Component wizard are not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/aggregation-and-class-factory-macros.md b/docs/atl/reference/aggregation-and-class-factory-macros.md index b6dacd4282f..7520e67a5f9 100644 --- a/docs/atl/reference/aggregation-and-class-factory-macros.md +++ b/docs/atl/reference/aggregation-and-class-factory-macros.md @@ -4,10 +4,11 @@ title: "Aggregation and Class Factory Macros" ms.date: 08/12/2020 f1_keywords: ["ATLCOM/ATL::DECLARE_AGGREGATABLE", "ATLCOM/ATL::DECLARE_CLASSFACTORY", "ATLCOM/ATL::DECLARE_CLASSFACTORY_EX", "ATLCOM/ATL::DECLARE_CLASSFACTORY_AUTO_THREAD", "ATLCOM/ATL::DECLARE_CLASSFACTORY_SINGLETON", "ATLCOM/ATL::DECLARE_GET_CONTROLLING_UNKNOWN", "ATLCOM/ATL::DECLARE_NOT_AGGREGATABLE", "ATLCOM/ATL::DECLARE_ONLY_AGGREGATABLE", "ATLCOM/ATL::DECLARE_POLY_AGGREGATABLE", "ATLCOM/ATL::DECLARE_PROTECT_FINAL_CONSTRUCT", "ATLCOM/ATL::DECLARE_VIEW_STATUS", "ATLDEF/ATL::DECLARE_AGGREGATABLE", "ATLDEF/ATL::DECLARE_CLASSFACTORY", "ATLDEF/ATL::DECLARE_CLASSFACTORY_EX", "ATLDEF/ATL::DECLARE_CLASSFACTORY_AUTO_THREAD", "ATLDEF/ATL::DECLARE_CLASSFACTORY_SINGLETON", "ATLDEF/ATL::DECLARE_GET_CONTROLLING_UNKNOWN", "ATLDEF/ATL::DECLARE_NOT_AGGREGATABLE", "ATLDEF/ATL::DECLARE_ONLY_AGGREGATABLE", "ATLDEF/ATL::DECLARE_POLY_AGGREGATABLE", "ATLDEF/ATL::DECLARE_PROTECT_FINAL_CONSTRUCT", "ATLDEF/ATL::DECLARE_VIEW_STATUS", "ATLCOM/DECLARE_AGGREGATABLE", "ATLCOM/DECLARE_CLASSFACTORY", "ATLCOM/DECLARE_CLASSFACTORY_EX", "ATLCOM/DECLARE_CLASSFACTORY_AUTO_THREAD", "ATLCOM/DECLARE_CLASSFACTORY_SINGLETON", "ATLCOM/DECLARE_GET_CONTROLLING_UNKNOWN", "ATLCOM/DECLARE_NOT_AGGREGATABLE", "ATLCOM/DECLARE_ONLY_AGGREGATABLE", "ATLCOM/DECLARE_POLY_AGGREGATABLE", "ATLCOM/DECLARE_PROTECT_FINAL_CONSTRUCT", "ATLCOM/DECLARE_VIEW_STATUS", "ATL::DECLARE_AGGREGATABLE", "ATL::DECLARE_CLASSFACTORY", "ATL::DECLARE_CLASSFACTORY_EX", "ATL::DECLARE_CLASSFACTORY_AUTO_THREAD", "ATL::DECLARE_CLASSFACTORY_SINGLETON", "ATL::DECLARE_GET_CONTROLLING_UNKNOWN", "ATL::DECLARE_NOT_AGGREGATABLE", "ATL::DECLARE_ONLY_AGGREGATABLE", "ATL::DECLARE_POLY_AGGREGATABLE", "ATL::DECLARE_PROTECT_FINAL_CONSTRUCT", "ATL::DECLARE_VIEW_STATUS", "DECLARE_AGGREGATABLE", "DECLARE_CLASSFACTORY", "DECLARE_CLASSFACTORY_EX", "DECLARE_CLASSFACTORY_AUTO_THREAD", "DECLARE_CLASSFACTORY_SINGLETON", "DECLARE_GET_CONTROLLING_UNKNOWN", "DECLARE_NOT_AGGREGATABLE", "DECLARE_ONLY_AGGREGATABLE", "DECLARE_POLY_AGGREGATABLE", "DECLARE_PROTECT_FINAL_CONSTRUCT", "DECLARE_VIEW_STATUS"] helpviewer_keywords: ["class factories, ATL macros", "aggregation [C++], ATL macros", "ATL::DECLARE_AGGREGATABLE", "ATL::DECLARE_CLASSFACTORY", "ATL::DECLARE_CLASSFACTORY_EX", "ATL::DECLARE_CLASSFACTORY_AUTO_THREAD", "ATL::DECLARE_CLASSFACTORY_SINGLETON", "ATL::DECLARE_GET_CONTROLLING_UNKNOWN", "ATL::DECLARE_NOT_AGGREGATABLE", "ATL::DECLARE_ONLY_AGGREGATABLE", "ATL::DECLARE_POLY_AGGREGATABLE", "ATL::DECLARE_PROTECT_FINAL_CONSTRUCT", "ATL::DECLARE_VIEW_STATUS"] -ms.assetid: d99d379a-0eec-481f-8daa-252dac18f163 --- # Aggregation and Class Factory Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros provide ways of controlling aggregation and of declaring class factories. | Macro | Description | diff --git a/docs/atl/reference/appearance-atl-control-wizard.md b/docs/atl/reference/appearance-atl-control-wizard.md index 5a28f5a572e..2f305fd5e95 100644 --- a/docs/atl/reference/appearance-atl-control-wizard.md +++ b/docs/atl/reference/appearance-atl-control-wizard.md @@ -4,10 +4,11 @@ title: "Appearance, ATL Control Wizard" ms.date: "08/31/2018" f1_keywords: ["vc.codewiz.class.atl.control.misc"] helpviewer_keywords: ["ATL Control Wizard, appearance"] -ms.assetid: cc16d7ff-74d7-4c15-9ebd-4b19201ff457 --- # Appearance, ATL Control Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this page of the wizard to identify additional user element options for the control. This page is available for controls identified as **Standard controls** under **Control type** on the [Options, ATL Control Wizard](../../atl/reference/options-atl-control-wizard.md) page. ## UIElement List diff --git a/docs/atl/reference/application-settings-atl-project-wizard.md b/docs/atl/reference/application-settings-atl-project-wizard.md index 03b0fade12f..6922ea0313c 100644 --- a/docs/atl/reference/application-settings-atl-project-wizard.md +++ b/docs/atl/reference/application-settings-atl-project-wizard.md @@ -4,10 +4,11 @@ title: "Application Settings, ATL Project Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.atl.com.appset"] helpviewer_keywords: ["ATL Project Wizard, application settings"] -ms.assetid: d48c9fc5-f439-49fd-884c-8bcfa7d52991 --- # Application Settings, ATL Project Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use the **Application Settings** page of the ATL Project Wizard to design and add basic features to a new ATL project. ## Server type diff --git a/docs/atl/reference/asp-atl-active-server-page-component-wizard.md b/docs/atl/reference/asp-atl-active-server-page-component-wizard.md index efb54c5bbfa..3a9dd3f5419 100644 --- a/docs/atl/reference/asp-atl-active-server-page-component-wizard.md +++ b/docs/atl/reference/asp-atl-active-server-page-component-wizard.md @@ -4,10 +4,11 @@ title: "ASP, ATL Active Server Page Component Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.asp.asp"] helpviewer_keywords: ["ATL Active Server Page Component Wizard, ASP"] -ms.assetid: 4d8cafd6-5e12-4461-8911-29288896af3c --- # ASP, ATL Active Server Page Component Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this page of the ATL Active Server Page Component Wizard to specify optional settings for handling information and state related to your ASP component. - **Optional methods** diff --git a/docs/atl/reference/atl-active-server-page-component-wizard.md b/docs/atl/reference/atl-active-server-page-component-wizard.md index ceab8c73f93..410c00ddb87 100644 --- a/docs/atl/reference/atl-active-server-page-component-wizard.md +++ b/docs/atl/reference/atl-active-server-page-component-wizard.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Active Server Page Component Wizard" title: "ATL Active Server Page Component Wizard" ms.date: "05/09/2019" helpviewer_keywords: ["ASP components, creating in ATL"] -ms.assetid: 5a5cb904-dbbf-44ea-ad3d-2ddd14c1d3c5 --- # ATL Active Server Page Component Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-base-module70-structure.md b/docs/atl/reference/atl-base-module70-structure.md index 78cbd738768..004ec92a8bd 100644 --- a/docs/atl/reference/atl-base-module70-structure.md +++ b/docs/atl/reference/atl-base-module70-structure.md @@ -4,10 +4,11 @@ title: "_ATL_BASE_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::_ATL_BASE_MODULE70", "ATL._ATL_BASE_MODULE70", "_ATL_BASE_MODULE70"] helpviewer_keywords: ["ATL_BASE_MODULE70 structure", "_ATL_BASE_MODULE70 structure"] -ms.assetid: 4539282f-15b8-4d7c-aafa-a85dc56f4980 --- # _ATL_BASE_MODULE70 Structure +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Used by any project that uses ATL. ## Syntax diff --git a/docs/atl/reference/atl-classes.md b/docs/atl/reference/atl-classes.md index e7c285dc49f..836fa1aa854 100644 --- a/docs/atl/reference/atl-classes.md +++ b/docs/atl/reference/atl-classes.md @@ -1,11 +1,13 @@ --- 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"] --- # ATL classes and structs +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The Active Template Library (ATL) includes the following classes and structs. To find a particular class by category, see the [ATL Class Overview](../../atl/atl-class-overview.md). |Class / struct|Description|Header file| diff --git a/docs/atl/reference/atl-com-module70-structure.md b/docs/atl/reference/atl-com-module70-structure.md index 3f37add4ec9..424d68a7e57 100644 --- a/docs/atl/reference/atl-com-module70-structure.md +++ b/docs/atl/reference/atl-com-module70-structure.md @@ -4,10 +4,11 @@ title: "_ATL_COM_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::_ATL_COM_MODULE70", "ATL._ATL_COM_MODULE70", "_ATL_COM_MODULE70"] helpviewer_keywords: ["_ATL_COM_MODULE70 structure", "ATL_COM_MODULE70 structure"] -ms.assetid: 5b0b2fd0-bdeb-4c7e-8870-78fa69ace6e6 --- # _ATL_COM_MODULE70 Structure +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Used by COM-related code in ATL. ## Syntax diff --git a/docs/atl/reference/atl-com-plus-1-0-component-wizard.md b/docs/atl/reference/atl-com-plus-1-0-component-wizard.md index 4f342caa931..a72c326005e 100644 --- a/docs/atl/reference/atl-com-plus-1-0-component-wizard.md +++ b/docs/atl/reference/atl-com-plus-1-0-component-wizard.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL COM+ 1.0 Component Wizard" title: "ATL COM+ 1.0 Component Wizard" ms.date: "05/08/2019" helpviewer_keywords: ["ATL projects, adding components"] -ms.assetid: 11670681-8671-4122-96a4-2e52f8dadce0 --- # ATL COM+ 1.0 Component Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-control-wizard.md b/docs/atl/reference/atl-control-wizard.md index f1ba09a54dd..1c7f40ee9f4 100644 --- a/docs/atl/reference/atl-control-wizard.md +++ b/docs/atl/reference/atl-control-wizard.md @@ -4,10 +4,11 @@ title: "ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.overview"] helpviewer_keywords: ["ATL projects, adding controls", "controls [ATL], adding to projects", "ATL Control Wizard"] -ms.assetid: 991f8e72-ffbc-4382-a4ce-e255acfba5b6 --- # ATL Control Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Inserts into an ATL project (or an MFC project with ATL support) an ATL control. You can use this wizard to insert one of three kinds of controls: - Standard control diff --git a/docs/atl/reference/atl-dialog-wizard.md b/docs/atl/reference/atl-dialog-wizard.md index c2908571e3c..862cb038b71 100644 --- a/docs/atl/reference/atl-dialog-wizard.md +++ b/docs/atl/reference/atl-dialog-wizard.md @@ -4,10 +4,11 @@ title: "ATL Dialog Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.dlg.overview"] helpviewer_keywords: ["ATL projects, adding dialog resources", "ATL Dialog Wizard"] -ms.assetid: b0b9ace5-83c9-40d3-82c3-eb6293f10583 --- # ATL Dialog Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This wizard inserts into the project an ATL dialog box object, derived from [CAxDialogImpl](../../atl/reference/caxdialogimpl-class.md). A dialog box derived from `CAxDialogImpl` can host ActiveX controls. The wizard creates a dialog resource with default **OK** and **Cancel** buttons. You can edit the dialog resource and add ActiveX controls using the [Dialog Editor](../../windows/dialog-editor.md) in Resource View. diff --git a/docs/atl/reference/atl-drawinfo-structure.md b/docs/atl/reference/atl-drawinfo-structure.md index 8c44e5e231a..971943f6209 100644 --- a/docs/atl/reference/atl-drawinfo-structure.md +++ b/docs/atl/reference/atl-drawinfo-structure.md @@ -4,10 +4,11 @@ title: "ATL_DRAWINFO Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::ATL_DRAWINFO", "ATL_DRAWINFO", "ATL.ATL_DRAWINFO"] helpviewer_keywords: ["ATL_DRAWINFO structure"] -ms.assetid: dd2e2aa8-e8c5-403b-b4df-35c0f6f57fb7 --- # ATL_DRAWINFO Structure +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Contains information used for rendering to various targets, such as a printer, metafile, or ActiveX control. ## Syntax diff --git a/docs/atl/reference/atl-func-info-structure.md b/docs/atl/reference/atl-func-info-structure.md index 2be432a32d9..7f3e2b1dc1d 100644 --- a/docs/atl/reference/atl-func-info-structure.md +++ b/docs/atl/reference/atl-func-info-structure.md @@ -4,10 +4,11 @@ title: "_ATL_FUNC_INFO Structure" ms.date: "11/04/2016" f1_keywords: ["_ATL_FUNC_INFO", "ATL::_ATL_FUNC_INFO", "ATL._ATL_FUNC_INFO"] helpviewer_keywords: ["_ATL_FUNC_INFO structure", "ATL_FUNC_INFO structure"] -ms.assetid: 441ebe2c-f971-47de-9f52-a258e8d6f88e --- # _ATL_FUNC_INFO Structure +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Contains type information used to describe a method or property on a dispinterface. ## Syntax diff --git a/docs/atl/reference/atl-functions.md b/docs/atl/reference/atl-functions.md index f32f42b2041..96a93f09150 100644 --- a/docs/atl/reference/atl-functions.md +++ b/docs/atl/reference/atl-functions.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Functions" title: "ATL Functions" ms.date: "11/04/2016" helpviewer_keywords: ["functions [ATL]", "ATL, global functions"] -ms.assetid: 69db0cb2-de1d-445b-b692-020d6e8c2173 --- # ATL Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + To find an ATL function by category, see the following topics. [ATL Path Functions](../../atl/reference/com-map-global-functions.md)
diff --git a/docs/atl/reference/atl-global-variables.md b/docs/atl/reference/atl-global-variables.md index 68a23951c11..553aec1f266 100644 --- a/docs/atl/reference/atl-global-variables.md +++ b/docs/atl/reference/atl-global-variables.md @@ -4,10 +4,11 @@ title: "ATL Global Variables" ms.date: "12/06/2017" f1_keywords: ["ATLBASE/_pAtlModule"] helpviewer_keywords: ["global variables, ATL", "_pAtlModule"] -ms.assetid: e881a319-99ca-4f5d-8a0b-34b3dcd0f37f --- # ATL Global Variables +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ## _pAtlModule A global variable storing a pointer to the current module. diff --git a/docs/atl/reference/atl-http-utility-functions.md b/docs/atl/reference/atl-http-utility-functions.md index 47f78813f00..6980b30e704 100644 --- a/docs/atl/reference/atl-http-utility-functions.md +++ b/docs/atl/reference/atl-http-utility-functions.md @@ -2,10 +2,11 @@ description: "Learn more about: ATL HTTP Utility Functions" title: "ATL HTTP Utility Functions" ms.date: "11/04/2016" -ms.assetid: 4db57ef2-31fa-4696-bbeb-79a9035033ed --- # ATL HTTP Utility Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions support manipulation of URLs. |Function|Description| diff --git a/docs/atl/reference/atl-macros.md b/docs/atl/reference/atl-macros.md index 28f62b30117..d660507aeb8 100644 --- a/docs/atl/reference/atl-macros.md +++ b/docs/atl/reference/atl-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Macros" title: "ATL Macros" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, macros", "macros, ATL"] -ms.assetid: 788bd803-e7dc-4dc5-9e8d-31649471415b --- # ATL Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + To find an ATL macro by category, see the following topics. [Aggregation and Class Factory Macros](../../atl/reference/aggregation-and-class-factory-macros.md)
diff --git a/docs/atl/reference/atl-module70-structure.md b/docs/atl/reference/atl-module70-structure.md index eeee4263273..642c262492a 100644 --- a/docs/atl/reference/atl-module70-structure.md +++ b/docs/atl/reference/atl-module70-structure.md @@ -4,10 +4,11 @@ title: "_ATL_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["_ATL_MODULE70", "ATL::_ATL_MODULE70", "ATL._ATL_MODULE70"] helpviewer_keywords: ["ATL_MODULE70 structure", "_ATL_MODULE70 structure"] -ms.assetid: b059b2c8-dfd1-4ac9-b07d-39df638cc7b3 --- # _ATL_MODULE70 Structure +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Contains data used by every ATL module. ## Syntax diff --git a/docs/atl/reference/atl-ole-db-consumer-wizard.md b/docs/atl/reference/atl-ole-db-consumer-wizard.md index da09ffeebbb..8192655ec73 100644 --- a/docs/atl/reference/atl-ole-db-consumer-wizard.md +++ b/docs/atl/reference/atl-ole-db-consumer-wizard.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL OLE DB Consumer Wizard" title: "ATL OLE DB Consumer Wizard" ms.date: "07/02/2019" helpviewer_keywords: ["ATL projects, adding ATL OLE DB consumers"] -ms.assetid: dcb68ed1-2224-422f-9f7b-108a74864204 --- # ATL OLE DB Consumer Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-ole-db-provider-wizard.md b/docs/atl/reference/atl-ole-db-provider-wizard.md index 29417f6f85d..e0d73a85994 100644 --- a/docs/atl/reference/atl-ole-db-provider-wizard.md +++ b/docs/atl/reference/atl-ole-db-provider-wizard.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL OLE DB Provider Wizard" title: "ATL OLE DB Provider Wizard" ms.date: "05/09/2019" helpviewer_keywords: ["ATL projects, adding ATL OLE DB providers"] -ms.assetid: cf91ba78-01d1-4d12-b673-e95d96bfbebe --- # ATL OLE DB Provider Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-operators.md b/docs/atl/reference/atl-operators.md index 85beb951ab3..2e16c36d15a 100644 --- a/docs/atl/reference/atl-operators.md +++ b/docs/atl/reference/atl-operators.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Operators" title: "ATL Operators" ms.date: "11/04/2016" helpviewer_keywords: ["operators [ATL]"] -ms.assetid: 58ccd252-2869-45ee-8a5c-3ca40ee7f8a2 --- # ATL Operators +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This section contains the reference topics for the ATL global operators. |Operator|Description| diff --git a/docs/atl/reference/atl-path-functions.md b/docs/atl/reference/atl-path-functions.md index 33562d071a8..709a5e9f82a 100644 --- a/docs/atl/reference/atl-path-functions.md +++ b/docs/atl/reference/atl-path-functions.md @@ -4,10 +4,11 @@ title: "ATL Path functions" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, path"] f1_keywords: ["ATLPATH/ATL::ATLPath::AddBackslash", "ATLPATH/ATL::ATLPath::AddExtension", "ATLPATH/ATL::ATLPath::Append", "ATLPATH/ATL::ATLPath::BuildRoot", "ATLPATH/ATL::ATLPath::Canonicalize", "ATLPATH/ATL::ATLPath::Combine", "ATLPATH/ATL::ATLPath::CommonPrefix", "ATLPATH/ATL::ATLPath::CompactPath", "ATLPATH/ATL::ATLPath::CompactPathEx", "ATLPATH/ATL::ATLPath::FileExists", "ATLPATH/ATL::ATLPath::FindExtension", "ATLPATH/ATL::ATLPath::FindFileName", "ATLPATH/ATL::ATLPath::GetDriveNumber", "ATLPATH/ATL::ATLPath::IsDirectory", "ATLPATH/ATL::ATLPath::IsFileSpec", "ATLPATH/ATL::ATLPath::IsPrefix", "ATLPATH/ATL::ATLPath::IsRelative", "ATLPATH/ATL::ATLPath::IsRoot", "ATLPATH/ATL::ATLPath::IsSameRoot", "ATLPATH/ATL::ATLPath::IsUNC", "ATLPATH/ATL::ATLPath::IsUNCServer", "ATLPATH/ATL::ATLPath::IsUNCServerShare", "ATLPATH/ATL::ATLPath::MakePretty", "ATLPATH/ATL::ATLPath::MatchSpec", "ATLPATH/ATL::ATLPath::QuoteSpaces", "ATLPATH/ATL::ATLPath::RelativePathTo", "ATLPATH/ATL::ATLPath::RemoveArgs", "ATLPATH/ATL::ATLPath::RemoveBackslash", "ATLPATH/ATL::ATLPath::RemoveBlanks", "ATLPATH/ATL::ATLPath::RemoveExtension", "ATLPATH/ATL::ATLPath::RemoveFileSpec", "ATLPATH/ATL::ATLPath::RenameExtension", "ATLPATH/ATL::ATLPath::SkipRoot", "ATLPATH/ATL::ATLPath::StripPath", "ATLPATH/ATL::ATLPath::StripToRoot", "ATLPATH/ATL::ATLPath::UnquoteSpaces"] -ms.assetid: d1ec2b8d-7ec7-43ea-90dd-0a740d2a742b --- # ATL Path functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ATL provides the ATLPath class for manipulating paths in the form of [CPathT](cpatht-class.md). This code can be found in atlpath.h. ## Related Classes diff --git a/docs/atl/reference/atl-project-wizard.md b/docs/atl/reference/atl-project-wizard.md index 54180ade5d1..f0ceeb5726f 100644 --- a/docs/atl/reference/atl-project-wizard.md +++ b/docs/atl/reference/atl-project-wizard.md @@ -4,10 +4,11 @@ title: "ATL Project Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.atl.com.overview"] helpviewer_keywords: ["ATL projects, creating", "ATL Project Wizard"] -ms.assetid: 564d2aaf-5b8e-4c2a-a925-ca40a283ea34 --- # ATL Project Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The Active Template Library (ATL) is a set of template-based C++ classes that simplify writing small and fast COM objects. The ATL Project Wizard creates a project with the structures to contain COM objects. ## Overview diff --git a/docs/atl/reference/atl-property-page-wizard.md b/docs/atl/reference/atl-property-page-wizard.md index 16c00456903..4d7eb8263ac 100644 --- a/docs/atl/reference/atl-property-page-wizard.md +++ b/docs/atl/reference/atl-property-page-wizard.md @@ -4,10 +4,11 @@ title: "ATL Property Page Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.ppg.overview"] helpviewer_keywords: ["ATL projects, adding property pages", "ATL Property Page Wizard"] -ms.assetid: 6113e325-facd-4f68-b491-144d75209922 --- # ATL Property Page Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/atl-simple-object-wizard.md b/docs/atl/reference/atl-simple-object-wizard.md index 23a819b1bf8..392f374f655 100644 --- a/docs/atl/reference/atl-simple-object-wizard.md +++ b/docs/atl/reference/atl-simple-object-wizard.md @@ -4,10 +4,11 @@ title: "ATL Simple Object Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.simple.overview"] helpviewer_keywords: ["ATL projects, adding objects", "ATL Simple Object Wizard"] -ms.assetid: f7f85741-9aad-4543-a917-a29b996364da --- # ATL Simple Object Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This wizard inserts into the project a minimal COM object. Use this page of the wizard to specify the names that identify the C++ class and files for your object and its COM functionality. Use the [Options](../../atl/reference/options-atl-simple-object-wizard.md) page of this wizard to specify the object's threading model, its aggregation support, and whether it supports dual interfaces and Automation. You can also indicate support for the error information interface, connection points, Internet Explorer support, and free-threaded marshaling. diff --git a/docs/atl/reference/atl-text-encoding-functions.md b/docs/atl/reference/atl-text-encoding-functions.md index aa50e31f2ef..6afe2a4900b 100644 --- a/docs/atl/reference/atl-text-encoding-functions.md +++ b/docs/atl/reference/atl-text-encoding-functions.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Text Encoding Functions" title: "ATL Text Encoding Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlGetHexValue", "atlbase/ATL::AtlGetVersion", "atlenc/ATL::AtlHexDecode", "atlenc/ATL::AtlHexDecodeGetRequiredLength", "atlenc/ATL::AtlHexEncode", "atlenc/ATL::AtlHexEncodeGetRequiredLength", "atlenc/ATL::AtlHexValue", "atlenc/ATL::BEncode", "atlenc/ATL::BEncodeGetRequiredLength", "atlenc/ATL::EscapeXML", "atlenc/ATL::GetExtendedChars", "atlenc/ATL::IsExtendedChar", "atlenc/ATL::QEncode", "atlenc/ATL::QEncodeGetRequiredLength", "atlenc/ATL::QPDecode", "atlenc/ATL::QPDecodeGetRequiredLength", "atlenc/ATL::QPEncode", "atlenc/ATL::QPEncodeGetRequiredLength", "atlenc/ATL::UUDecode", "atlenc/ATL::UUDecodeGetRequiredLength", "atlenc/ATL::UUEncode", "atlenc/ATL::UUEncodeGetRequiredLength"] -ms.assetid: 2ae1648b-2b87-4112-92aa-0069fcfd23da --- # ATL Text Encoding Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions support text encoding and decoding. |Function|Description| diff --git a/docs/atl/reference/atl-typedefs.md b/docs/atl/reference/atl-typedefs.md index 471587e3278..28f4a79773f 100644 --- a/docs/atl/reference/atl-typedefs.md +++ b/docs/atl/reference/atl-typedefs.md @@ -4,10 +4,11 @@ title: "ATL Typedefs" ms.date: "11/04/2016" f1_keywords: ["atlcore/ATL::_ATL_BASE_MODULE", "atlbase/ATL::_ATL_COM_MODULE", "atlbase/ATL::_ATL_MODULE", "atlbase/ATL::_ATL_WIN_MODULE", "atlutil/ATL::ATL_URL_PORT", "atlbase/ATL::CComDispatchDriver", "atlbase/ATL::CComGlobalsThreadModel", "atlbase/ATL::CComObjectThreadModel", "atlwin/ATL::CContainedWindow", "atlpath/ATL::CPath", "atlpath/ATL::CPathA", "atlpath/ATL::CPathW", " atlsimpcoll/ATL::CSimpleValArray", " atlutil/ATL::LPCURL", "atlbase/ATL::DefaultThreadTraits", "atlutil/ATL::LPURL"] helpviewer_keywords: ["typedefs, ATL", "typedefs", "ATL, typedefs"] -ms.assetid: 7dd05baa-3efb-4e3b-af23-793c610f4560 --- # ATL Typedefs +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The Active Template Library includes the following typedefs. |Typedef|Description| diff --git a/docs/atl/reference/atl-url-scheme-enum.md b/docs/atl/reference/atl-url-scheme-enum.md index fbed95cb013..8c6df2df608 100644 --- a/docs/atl/reference/atl-url-scheme-enum.md +++ b/docs/atl/reference/atl-url-scheme-enum.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL_URL_SCHEME" title: "ATL_URL_SCHEME enumeration" ms.date: "11/04/2016" helpviewer_keywords: ["ATLUTIL/ATL::ATL_URL_SCHEME"] -ms.assetid: f4131046-8ba0-4ec1-8209-84203f05d20e --- # ATL_URL_SCHEME +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The members of this enumeration provide constants for the schemes understood by [CUrl](curl-class.md). ## Syntax diff --git a/docs/atl/reference/atl-win-module70-structure.md b/docs/atl/reference/atl-win-module70-structure.md index 4a053f0aecd..b5e717cbc3a 100644 --- a/docs/atl/reference/atl-win-module70-structure.md +++ b/docs/atl/reference/atl-win-module70-structure.md @@ -4,10 +4,11 @@ title: "_ATL_WIN_MODULE70 Structure" ms.date: "11/04/2016" f1_keywords: ["_ATL_WIN_MODULE70", "ATL::_ATL_WIN_MODULE70", "ATL._ATL_WIN_MODULE70"] helpviewer_keywords: ["_ATL_WIN_MODULE70 structure", "ATL_WIN_MODULE70 structure"] -ms.assetid: a0aaf3ea-ca77-46ec-bd53-4dfb61dffbea --- # _ATL_WIN_MODULE70 Structure +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Used by windowing code in ATL. ## Syntax diff --git a/docs/atl/reference/atl-wizards-and-dialog-boxes.md b/docs/atl/reference/atl-wizards-and-dialog-boxes.md index 0632227a113..0b3400f14d8 100644 --- a/docs/atl/reference/atl-wizards-and-dialog-boxes.md +++ b/docs/atl/reference/atl-wizards-and-dialog-boxes.md @@ -3,10 +3,11 @@ description: "Learn more about: ATL Wizards and Dialog Boxes" title: "ATL Wizards and Dialog Boxes" ms.date: "06/26/2020" helpviewer_keywords: ["ATL, class wizards"] -ms.assetid: 51cf002a-83bc-41ba-aeb8-364ea2331375 --- # ATL Wizards and Dialog Boxes +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The Active Template Library (ATL) wizards generate boilerplate code for various kinds of COM objects. You can run the wizards by opening the shortcut menu for a project in **Solution Explorer** and choosing **Add**, **Class**. ## Related Articles diff --git a/docs/atl/reference/atlcreatewnddata-structure.md b/docs/atl/reference/atlcreatewnddata-structure.md index ab5f1b3cf66..ccef921db99 100644 --- a/docs/atl/reference/atlcreatewnddata-structure.md +++ b/docs/atl/reference/atlcreatewnddata-structure.md @@ -4,10 +4,11 @@ title: "_AtlCreateWndData Structure" ms.date: "11/04/2016" f1_keywords: ["ATL::_AtlCreateWndData", "ATL._AtlCreateWndData", "_AtlCreateWndData"] helpviewer_keywords: ["_AtlCreateWndData structure", "AtlCreateWndData structure"] -ms.assetid: 76ed5382-bfbf-4b8b-8a29-912688dfd2ae --- # _AtlCreateWndData Structure +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This structure contains class instance data in windowing code in ATL. ## Syntax diff --git a/docs/atl/reference/ca2aex-class.md b/docs/atl/reference/ca2aex-class.md index 17184ac1d4a..17355a4e6d8 100644 --- a/docs/atl/reference/ca2aex-class.md +++ b/docs/atl/reference/ca2aex-class.md @@ -4,10 +4,11 @@ title: "CA2AEX Class" ms.date: "11/04/2016" f1_keywords: ["CA2AEX", "ATLCONV/ATL::CA2AEX", "ATLCONV/ATL::CA2AEX::CA2AEX", "ATLCONV/ATL::CA2AEX::m_psz", "ATLCONV/ATL::CA2AEX::m_szBuffer"] helpviewer_keywords: ["CA2AEX class"] -ms.assetid: 57dc65df-d9cf-4a84-99d3-6e031dde3664 --- # CA2AEX Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is used by the string conversion macros CA2TEX and CT2AEX, and the typedef CA2A. > [!IMPORTANT] diff --git a/docs/atl/reference/ca2caex-class.md b/docs/atl/reference/ca2caex-class.md index 384efbd5ea5..74d94867f69 100644 --- a/docs/atl/reference/ca2caex-class.md +++ b/docs/atl/reference/ca2caex-class.md @@ -4,10 +4,11 @@ title: "CA2CAEX Class" ms.date: "11/04/2016" f1_keywords: ["CA2CAEX", "ATLCONV/ATL::CA2CAEX", "ATLCONV/ATL::CA2CAEX::CA2CAEX", "ATLCONV/ATL::CA2CAEX::m_psz"] helpviewer_keywords: ["CA2CAEX class"] -ms.assetid: 388e7c1d-a144-474c-a182-b15f69a74bd8 --- # CA2CAEX Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is used by string conversion macros CA2CTEX and CT2CAEX, and the typedef CA2CA. > [!IMPORTANT] diff --git a/docs/atl/reference/ca2wex-class.md b/docs/atl/reference/ca2wex-class.md index 6b350dc68cf..efe52c7c486 100644 --- a/docs/atl/reference/ca2wex-class.md +++ b/docs/atl/reference/ca2wex-class.md @@ -4,10 +4,11 @@ title: "CA2WEX Class" ms.date: "11/04/2016" f1_keywords: ["CA2WEX", "ATLCONV/ATL::CA2WEX", "ATLCONV/ATL::CA2WEX::CA2WEX", "ATLCONV/ATL::CA2WEX::m_psz", "ATLCONV/ATL::CA2WEX::m_szBuffer"] helpviewer_keywords: ["CA2WEX class"] -ms.assetid: 317d9ffb-e84f-47e8-beda-57e28fb19124 --- # CA2WEX Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is used by the string conversion macros CA2TEX, CA2CTEX, CT2WEX, and CT2CWEX, and the typedef CA2W. > [!IMPORTANT] diff --git a/docs/atl/reference/caccesstoken-class.md b/docs/atl/reference/caccesstoken-class.md index 49272bfcd4a..6cd58e432ee 100644 --- a/docs/atl/reference/caccesstoken-class.md +++ b/docs/atl/reference/caccesstoken-class.md @@ -4,10 +4,11 @@ title: "CAccessToken Class" ms.date: "07/02/2019" f1_keywords: ["CAccessToken", "ATLSECURITY/ATL::CAccessToken", "ATLSECURITY/ATL::CAccessToken::Attach", "ATLSECURITY/ATL::CAccessToken::CheckTokenMembership", "ATLSECURITY/ATL::CAccessToken::CreateImpersonationToken", "ATLSECURITY/ATL::CAccessToken::CreatePrimaryToken", "ATLSECURITY/ATL::CAccessToken::CreateProcessAsUser", "ATLSECURITY/ATL::CAccessToken::CreateRestrictedToken", "ATLSECURITY/ATL::CAccessToken::Detach", "ATLSECURITY/ATL::CAccessToken::DisablePrivilege", "ATLSECURITY/ATL::CAccessToken::DisablePrivileges", "ATLSECURITY/ATL::CAccessToken::EnablePrivilege", "ATLSECURITY/ATL::CAccessToken::EnablePrivileges", "ATLSECURITY/ATL::CAccessToken::GetDefaultDacl", "ATLSECURITY/ATL::CAccessToken::GetEffectiveToken", "ATLSECURITY/ATL::CAccessToken::GetGroups", "ATLSECURITY/ATL::CAccessToken::GetHandle", "ATLSECURITY/ATL::CAccessToken::GetImpersonationLevel", "ATLSECURITY/ATL::CAccessToken::GetLogonSessionId", "ATLSECURITY/ATL::CAccessToken::GetLogonSid", "ATLSECURITY/ATL::CAccessToken::GetOwner", "ATLSECURITY/ATL::CAccessToken::GetPrimaryGroup", "ATLSECURITY/ATL::CAccessToken::GetPrivileges", "ATLSECURITY/ATL::CAccessToken::GetProcessToken", "ATLSECURITY/ATL::CAccessToken::GetProfile", "ATLSECURITY/ATL::CAccessToken::GetSource", "ATLSECURITY/ATL::CAccessToken::GetStatistics", "ATLSECURITY/ATL::CAccessToken::GetTerminalServicesSessionId", "ATLSECURITY/ATL::CAccessToken::GetThreadToken", "ATLSECURITY/ATL::CAccessToken::GetTokenId", "ATLSECURITY/ATL::CAccessToken::GetType", "ATLSECURITY/ATL::CAccessToken::GetUser", "ATLSECURITY/ATL::CAccessToken::HKeyCurrentUser", "ATLSECURITY/ATL::CAccessToken::Impersonate", "ATLSECURITY/ATL::CAccessToken::ImpersonateLoggedOnUser", "ATLSECURITY/ATL::CAccessToken::IsTokenRestricted", "ATLSECURITY/ATL::CAccessToken::LoadUserProfile", "ATLSECURITY/ATL::CAccessToken::LogonUser", "ATLSECURITY/ATL::CAccessToken::OpenCOMClientToken", "ATLSECURITY/ATL::CAccessToken::OpenNamedPipeClientToken", "ATLSECURITY/ATL::CAccessToken::OpenRPCClientToken", "ATLSECURITY/ATL::CAccessToken::OpenThreadToken", "ATLSECURITY/ATL::CAccessToken::PrivilegeCheck", "ATLSECURITY/ATL::CAccessToken::Revert", "ATLSECURITY/ATL::CAccessToken::SetDefaultDacl", "ATLSECURITY/ATL::CAccessToken::SetOwner", "ATLSECURITY/ATL::CAccessToken::SetPrimaryGroup"] helpviewer_keywords: ["CAccessToken class"] -ms.assetid: bb5c5945-56a5-4083-b442-76573cee83ab --- # CAccessToken Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for an access token. > [!IMPORTANT] diff --git a/docs/atl/reference/cacl-class.md b/docs/atl/reference/cacl-class.md index 1521ad15fe8..49733e001d4 100644 --- a/docs/atl/reference/cacl-class.md +++ b/docs/atl/reference/cacl-class.md @@ -4,10 +4,11 @@ title: "CAcl Class" ms.date: "11/04/2016" f1_keywords: ["CAcl", "ATLSECURITY/ATL::CAcl", "ATLSECURITY/ATL::CAcl::CAccessMaskArray", "ATLSECURITY/ATL::CAcl::CAceFlagArray", "ATLSECURITY/ATL::CAcl::CAceTypeArray", "ATLSECURITY/ATL::CAcl::CAcl", "ATLSECURITY/ATL::CAcl::GetAceCount", "ATLSECURITY/ATL::CAcl::GetAclEntries", "ATLSECURITY/ATL::CAcl::GetAclEntry", "ATLSECURITY/ATL::CAcl::GetLength", "ATLSECURITY/ATL::CAcl::GetPACL", "ATLSECURITY/ATL::CAcl::IsEmpty", "ATLSECURITY/ATL::CAcl::IsNull", "ATLSECURITY/ATL::CAcl::RemoveAce", "ATLSECURITY/ATL::CAcl::RemoveAces", "ATLSECURITY/ATL::CAcl::SetEmpty", "ATLSECURITY/ATL::CAcl::SetNull"] helpviewer_keywords: ["CAcl class"] -ms.assetid: 20bcb9af-dc1c-4737-b923-3864776680d6 --- # CAcl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for an `ACL` (access-control list) structure. > [!IMPORTANT] diff --git a/docs/atl/reference/cadapt-class.md b/docs/atl/reference/cadapt-class.md index e3596e34f0d..010fa0f3f7f 100644 --- a/docs/atl/reference/cadapt-class.md +++ b/docs/atl/reference/cadapt-class.md @@ -4,10 +4,11 @@ title: "CAdapt Class" ms.date: "11/04/2016" f1_keywords: ["CAdapt", "ATLCOMCLI/ATL::CAdapt", "ATLCOMCLI/ATL::CAdapt::CAdapt", "ATLCOMCLI/ATL::CAdapt::m_T"] helpviewer_keywords: ["address-of operator", "adapter objects", "& operator, address-of operator", "CAdapt class"] -ms.assetid: 0bb695a5-72fe-43d1-8f39-7e4da6e34765 --- # CAdapt Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This template is used to wrap classes that redefine the address-of operator to return something other than the address of the object. ## Syntax diff --git a/docs/atl/reference/category-macros.md b/docs/atl/reference/category-macros.md index 2520af59602..c6339244da1 100644 --- a/docs/atl/reference/category-macros.md +++ b/docs/atl/reference/category-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: Category Macros" title: "Category Macros" ms.date: "11/04/2016" f1_keywords: ["ATLCOM/BEGIN_CATEGORY_MAP", "ATLCOM/END_CATEGORY_MAP", "ATLCOM/IMPLEMENTED_CATEGORY", "ATLCOM/REQUIRED_CATEGORY", "atlcom/ATL::BEGIN_CATEGORY_MAP", "atlcom/ATL::END_CATEGORY_MAP", "atlcom/ATL::IMPLEMENTED_CATEGORY", "atlcom/ATL::REQUIRED_CATEGORY"] -ms.assetid: 223578cb-6180-4787-a8d8-ba3787a5d3ee --- # Category Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define category maps. |Macro|Description| diff --git a/docs/atl/reference/catlarray-class.md b/docs/atl/reference/catlarray-class.md index e2ff7b40f54..9a7af00b550 100644 --- a/docs/atl/reference/catlarray-class.md +++ b/docs/atl/reference/catlarray-class.md @@ -4,10 +4,11 @@ title: "CAtlArray Class" ms.date: "11/04/2016" f1_keywords: ["CAtlArray", "ATLCOLL/ATL::CAtlArray", "ATLCOLL/ATL::Add", "ATLCOLL/ATL::Append", "ATLCOLL/ATL::AssertValid", "ATLCOLL/ATL::Copy", "ATLCOLL/ATL::FreeExtra", "ATLCOLL/ATL::GetAt", "ATLCOLL/ATL::GetCount", "ATLCOLL/ATL::GetData", "ATLCOLL/ATL::InsertArrayAt", "ATLCOLL/ATL::InsertAt", "ATLCOLL/ATL::IsEmpty", "ATLCOLL/ATL::RemoveAll", "ATLCOLL/ATL::RemoveAt", "ATLCOLL/ATL::SetAt", "ATLCOLL/ATL::SetAtGrow", "ATLCOLL/ATL::SetCount", "ATLCOLL/ATL::INARGTYPE", "ATLCOLL/ATL::OUTARGTYPE"] helpviewer_keywords: ["CAtlArray class"] -ms.assetid: 0b503aa8-2357-40af-a326-6654bf1da098 --- # CAtlArray Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements an array object. ## Syntax diff --git a/docs/atl/reference/catlautothreadmodule-class.md b/docs/atl/reference/catlautothreadmodule-class.md index ad171cbf113..fde8b27ac04 100644 --- a/docs/atl/reference/catlautothreadmodule-class.md +++ b/docs/atl/reference/catlautothreadmodule-class.md @@ -4,10 +4,11 @@ title: "CAtlAutoThreadModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlAutoThreadModule", "atlbase/ATL::CAtlAutoThreadModule"] helpviewer_keywords: ["CAtlAutoThreadModule class"] -ms.assetid: 3be834aa-55ef-403e-94ae-41979691b15f --- # CAtlAutoThreadModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a thread-pooled, apartment-model COM server. > [!IMPORTANT] diff --git a/docs/atl/reference/catlautothreadmodulet-class.md b/docs/atl/reference/catlautothreadmodulet-class.md index b3551f67c25..fdc99205556 100644 --- a/docs/atl/reference/catlautothreadmodulet-class.md +++ b/docs/atl/reference/catlautothreadmodulet-class.md @@ -4,10 +4,11 @@ title: "CAtlAutoThreadModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlAutoThreadModuleT", "ATLBASE/ATL::CAtlAutoThreadModuleT", "ATLBASE/ATL::CAtlAutoThreadModuleT::GetDefaultThreads"] helpviewer_keywords: ["CAtlAutoThreadModuleT class"] -ms.assetid: ae1667c6-3fb8-47bc-b35d-9ea5e9896d7f --- # CAtlAutoThreadModuleT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for implementing a thread-pooled, apartment-model COM server. > [!IMPORTANT] diff --git a/docs/atl/reference/catlbasemodule-class.md b/docs/atl/reference/catlbasemodule-class.md index ca75cf7b50b..1126d5109ea 100644 --- a/docs/atl/reference/catlbasemodule-class.md +++ b/docs/atl/reference/catlbasemodule-class.md @@ -4,10 +4,11 @@ title: "CAtlBaseModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlBaseModule", "ATLCORE/ATL::CAtlBaseModule", "ATLCORE/ATL::CAtlBaseModule::CAtlBaseModule", "ATLCORE/ATL::CAtlBaseModule::AddResourceInstance", "ATLCORE/ATL::CAtlBaseModule::GetHInstanceAt", "ATLCORE/ATL::CAtlBaseModule::GetModuleInstance", "ATLCORE/ATL::CAtlBaseModule::GetResourceInstance", "ATLCORE/ATL::CAtlBaseModule::RemoveResourceInstance", "ATLCORE/ATL::CAtlBaseModule::SetResourceInstance", "ATLCORE/ATL::CAtlBaseModule::m_bInitFailed"] helpviewer_keywords: ["CAtlBaseModule class"] -ms.assetid: 55ade80c-9b0c-4c51-933e-2158436c1096 --- # CAtlBaseModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is instantiated in every ATL project. ## Syntax diff --git a/docs/atl/reference/catlcommodule-class.md b/docs/atl/reference/catlcommodule-class.md index ec1824a9769..cb307e817bc 100644 --- a/docs/atl/reference/catlcommodule-class.md +++ b/docs/atl/reference/catlcommodule-class.md @@ -4,10 +4,11 @@ title: "CAtlComModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlComModule", "ATLBASE/ATL::CAtlComModule", "ATLBASE/ATL::CAtlComModule::CAtlComModule", "ATLBASE/ATL::CAtlComModule::RegisterServer", "ATLBASE/ATL::CAtlComModule::RegisterTypeLib", "ATLBASE/ATL::CAtlComModule::UnregisterServer", "ATLBASE/ATL::CAtlComModule::UnRegisterTypeLib"] helpviewer_keywords: ["CAtlComModule class"] -ms.assetid: af5dd71a-a0d1-4a2e-9a24-154a03381c75 --- # CAtlComModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a COM server module. ## Syntax diff --git a/docs/atl/reference/catldebuginterfacesmodule-class.md b/docs/atl/reference/catldebuginterfacesmodule-class.md index 38a674b3e7c..ff00c86e3c5 100644 --- a/docs/atl/reference/catldebuginterfacesmodule-class.md +++ b/docs/atl/reference/catldebuginterfacesmodule-class.md @@ -4,10 +4,11 @@ title: "CAtlDebugInterfacesModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlDebugInterfacesModule", "atlbase/ATL::CAtlDebugInterfacesModule"] helpviewer_keywords: ["_ATL_DEBUG_QI macro", "CAtlDebugInterfacesModule class"] -ms.assetid: a193b567-8191-4115-a963-a10805972bac --- # CAtlDebugInterfacesModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides support for debugging interfaces. ## Syntax diff --git a/docs/atl/reference/catldllmodulet-class.md b/docs/atl/reference/catldllmodulet-class.md index af960db0ee0..95c947d68cd 100644 --- a/docs/atl/reference/catldllmodulet-class.md +++ b/docs/atl/reference/catldllmodulet-class.md @@ -4,10 +4,11 @@ title: "CAtlDllModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlDllModuleT", "ATLBASE/ATL::CAtlDllModuleT", "ATLBASE/ATL::CAtlDllModuleT::CAtlDllModuleT", "ATLBASE/ATL::CAtlDllModuleT::DllCanUnloadNow", "ATLBASE/ATL::CAtlDllModuleT::DllGetClassObject", "ATLBASE/ATL::CAtlDllModuleT::DllMain", "ATLBASE/ATL::CAtlDllModuleT::DllRegisterServer", "ATLBASE/ATL::CAtlDllModuleT::DllUnregisterServer", "ATLBASE/ATL::CAtlDllModuleT::GetClassObject"] helpviewer_keywords: ["CAtlDllModuleT class"] -ms.assetid: 351d5767-8257-4878-94be-45a85e31a72d --- # CAtlDllModuleT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents the module for a DLL. ## Syntax diff --git a/docs/atl/reference/catlexception-class.md b/docs/atl/reference/catlexception-class.md index 5549aa2ab77..584270063fc 100644 --- a/docs/atl/reference/catlexception-class.md +++ b/docs/atl/reference/catlexception-class.md @@ -4,10 +4,11 @@ title: "CAtlException Class" ms.date: "11/04/2016" f1_keywords: ["CAtlException", "ATLEXCEPT/ATL::CAtlException", "ATLEXCEPT/ATL::CAtlException::CAtlException", "ATLEXCEPT/ATL::CAtlException::m_hr"] helpviewer_keywords: ["CAtlException class"] -ms.assetid: 3fd7b041-f70d-4292-b947-0d70781d95a8 --- # CAtlException Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class defines an ATL exception. ## Syntax diff --git a/docs/atl/reference/catlexemodulet-class.md b/docs/atl/reference/catlexemodulet-class.md index 9d191306d99..fa15ff7dee1 100644 --- a/docs/atl/reference/catlexemodulet-class.md +++ b/docs/atl/reference/catlexemodulet-class.md @@ -4,10 +4,11 @@ title: "CAtlExeModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlExeModuleT", "ATLBASE/ATL::CAtlExeModuleT", "ATLBASE/ATL::CAtlExeModuleT::CAtlExeModuleT", "ATLBASE/ATL::CAtlExeModuleT::InitializeCom", "ATLBASE/ATL::CAtlExeModuleT::ParseCommandLine", "ATLBASE/ATL::CAtlExeModuleT::PostMessageLoop", "ATLBASE/ATL::CAtlExeModuleT::PreMessageLoop", "ATLBASE/ATL::CAtlExeModuleT::RegisterClassObjects", "ATLBASE/ATL::CAtlExeModuleT::RevokeClassObjects", "ATLBASE/ATL::CAtlExeModuleT::Run", "ATLBASE/ATL::CAtlExeModuleT::RunMessageLoop", "ATLBASE/ATL::CAtlExeModuleT::UninitializeCom", "ATLBASE/ATL::CAtlExeModuleT::Unlock", "ATLBASE/ATL::CAtlExeModuleT::WinMain", "ATLBASE/ATL::CAtlExeModuleT::m_bDelayShutdown", "ATLBASE/ATL::CAtlExeModuleT::m_dwPause", "ATLBASE/ATL::CAtlExeModuleT::m_dwTimeOut"] helpviewer_keywords: ["CAtlExeModuleT class"] -ms.assetid: 82245f3d-91d4-44fa-aa86-7cc7fbd758d9 --- # CAtlExeModuleT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents the module for an application. ## Syntax diff --git a/docs/atl/reference/catlfile-class.md b/docs/atl/reference/catlfile-class.md index bbc448b9790..d959d4b8c38 100644 --- a/docs/atl/reference/catlfile-class.md +++ b/docs/atl/reference/catlfile-class.md @@ -4,10 +4,11 @@ title: "CAtlFile Class" ms.date: "11/04/2016" f1_keywords: ["CAtlFile", "ATLFILE/ATL::CAtlFile", "ATLFILE/ATL::CAtlFile::CAtlFile", "ATLFILE/ATL::CAtlFile::Create", "ATLFILE/ATL::CAtlFile::Flush", "ATLFILE/ATL::CAtlFile::GetOverlappedResult", "ATLFILE/ATL::CAtlFile::GetPosition", "ATLFILE/ATL::CAtlFile::GetSize", "ATLFILE/ATL::CAtlFile::LockRange", "ATLFILE/ATL::CAtlFile::Read", "ATLFILE/ATL::CAtlFile::Seek", "ATLFILE/ATL::CAtlFile::SetSize", "ATLFILE/ATL::CAtlFile::UnlockRange", "ATLFILE/ATL::CAtlFile::Write", "ATLFILE/ATL::CAtlFile::m_pTM"] helpviewer_keywords: ["CAtlFile class"] -ms.assetid: 93ed160b-af2a-448c-9cbe-e5fa46c199bb --- # CAtlFile Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a thin wrapper around the Windows file-handling API. > [!IMPORTANT] diff --git a/docs/atl/reference/catlfilemapping-class.md b/docs/atl/reference/catlfilemapping-class.md index 8eebfc290c1..db442ec69fb 100644 --- a/docs/atl/reference/catlfilemapping-class.md +++ b/docs/atl/reference/catlfilemapping-class.md @@ -4,10 +4,11 @@ title: "CAtlFileMapping Class" ms.date: "11/04/2016" f1_keywords: ["CAtlFileMapping", "atlfile/ATL::CAtlFileMapping"] helpviewer_keywords: ["CAtlFileMapping class"] -ms.assetid: 899fc058-e05e-48b5-aca9-340403bb9e26 --- # CAtlFileMapping Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a memory-mapped file, adding a cast operator to the methods of [CAtlFileMappingBase](../../atl/reference/catlfilemappingbase-class.md). > [!IMPORTANT] diff --git a/docs/atl/reference/catlfilemappingbase-class.md b/docs/atl/reference/catlfilemappingbase-class.md index f7084aa9571..b2bc6e3c4e5 100644 --- a/docs/atl/reference/catlfilemappingbase-class.md +++ b/docs/atl/reference/catlfilemappingbase-class.md @@ -4,10 +4,11 @@ title: "CAtlFileMappingBase Class" ms.date: "11/04/2016" f1_keywords: ["CAtlFileMappingBase", "ATLFILE/ATL::CAtlFileMappingBase", "ATLFILE/ATL::CAtlFileMappingBase::CAtlFileMappingBase", "ATLFILE/ATL::CAtlFileMappingBase::CopyFrom", "ATLFILE/ATL::CAtlFileMappingBase::GetData", "ATLFILE/ATL::CAtlFileMappingBase::GetHandle", "ATLFILE/ATL::CAtlFileMappingBase::GetMappingSize", "ATLFILE/ATL::CAtlFileMappingBase::MapFile", "ATLFILE/ATL::CAtlFileMappingBase::MapSharedMem", "ATLFILE/ATL::CAtlFileMappingBase::OpenMapping", "ATLFILE/ATL::CAtlFileMappingBase::Unmap"] helpviewer_keywords: ["CAtlFileMappingBase class"] -ms.assetid: be555723-2790-4f57-a8fb-be4d68460775 --- # CAtlFileMappingBase Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a memory-mapped file. > [!IMPORTANT] diff --git a/docs/atl/reference/catllist-class.md b/docs/atl/reference/catllist-class.md index 6b1fc2ce91e..a5cada88bd7 100644 --- a/docs/atl/reference/catllist-class.md +++ b/docs/atl/reference/catllist-class.md @@ -4,10 +4,11 @@ title: "CAtlList Class" ms.date: "11/04/2016" f1_keywords: ["CAtlList", "ATLCOLL/ATL::CAtlList", "ATLCOLL/ATL::CAtlList::INARGTYPE", "ATLCOLL/ATL::CAtlList::CAtlList", "ATLCOLL/ATL::CAtlList::AddHead", "ATLCOLL/ATL::CAtlList::AddHeadList", "ATLCOLL/ATL::CAtlList::AddTail", "ATLCOLL/ATL::CAtlList::AddTailList", "ATLCOLL/ATL::CAtlList::AssertValid", "ATLCOLL/ATL::CAtlList::Find", "ATLCOLL/ATL::CAtlList::FindIndex", "ATLCOLL/ATL::CAtlList::GetAt", "ATLCOLL/ATL::CAtlList::GetCount", "ATLCOLL/ATL::CAtlList::GetHead", "ATLCOLL/ATL::CAtlList::GetHeadPosition", "ATLCOLL/ATL::CAtlList::GetNext", "ATLCOLL/ATL::CAtlList::GetPrev", "ATLCOLL/ATL::CAtlList::GetTail", "ATLCOLL/ATL::CAtlList::GetTailPosition", "ATLCOLL/ATL::CAtlList::InsertAfter", "ATLCOLL/ATL::CAtlList::InsertBefore", "ATLCOLL/ATL::CAtlList::IsEmpty", "ATLCOLL/ATL::CAtlList::MoveToHead", "ATLCOLL/ATL::CAtlList::MoveToTail", "ATLCOLL/ATL::CAtlList::RemoveAll", "ATLCOLL/ATL::CAtlList::RemoveAt", "ATLCOLL/ATL::CAtlList::RemoveHead", "ATLCOLL/ATL::CAtlList::RemoveHeadNoReturn", "ATLCOLL/ATL::CAtlList::RemoveTail", "ATLCOLL/ATL::CAtlList::RemoveTailNoReturn", "ATLCOLL/ATL::CAtlList::SetAt", "ATLCOLL/ATL::CAtlList::SwapElements"] helpviewer_keywords: ["CAtlList class"] -ms.assetid: 09e98053-64b2-4efa-99ab-d0542caaf981 --- # CAtlList Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating and managing a list object. ## Syntax diff --git a/docs/atl/reference/catlmap-class.md b/docs/atl/reference/catlmap-class.md index b9273b02c8e..1801355e86b 100644 --- a/docs/atl/reference/catlmap-class.md +++ b/docs/atl/reference/catlmap-class.md @@ -4,10 +4,11 @@ title: "CAtlMap Class" ms.date: "11/04/2016" f1_keywords: ["CAtlMap", "ATLCOLL/ATL::CAtlMap", "ATLCOLL/ATL::CAtlMap::KINARGTYPE", "ATLCOLL/ATL::CAtlMap::KOUTARGTYPE", "ATLCOLL/ATL::CAtlMap::VINARGTYPE", "ATLCOLL/ATL::CAtlMap::VOUTARGTYPE", "ATLCOLL/ATL::CPair::m_key", "ATLCOLL/ATL::CPair::m_value", "ATLCOLL/ATL::CAtlMap::CAtlMap", "ATLCOLL/ATL::CAtlMap::AssertValid", "ATLCOLL/ATL::CAtlMap::DisableAutoRehash", "ATLCOLL/ATL::CAtlMap::EnableAutoRehash", "ATLCOLL/ATL::CAtlMap::GetAt", "ATLCOLL/ATL::CAtlMap::GetCount", "ATLCOLL/ATL::CAtlMap::GetHashTableSize", "ATLCOLL/ATL::CAtlMap::GetKeyAt", "ATLCOLL/ATL::CAtlMap::GetNext", "ATLCOLL/ATL::CAtlMap::GetNextAssoc", "ATLCOLL/ATL::CAtlMap::GetNextKey", "ATLCOLL/ATL::CAtlMap::GetNextValue", "ATLCOLL/ATL::CAtlMap::GetStartPosition", "ATLCOLL/ATL::CAtlMap::GetValueAt", "ATLCOLL/ATL::CAtlMap::InitHashTable", "ATLCOLL/ATL::CAtlMap::IsEmpty", "ATLCOLL/ATL::CAtlMap::Lookup", "ATLCOLL/ATL::CAtlMap::Rehash", "ATLCOLL/ATL::CAtlMap::RemoveAll", "ATLCOLL/ATL::CAtlMap::RemoveAtPos", "ATLCOLL/ATL::CAtlMap::RemoveKey", "ATLCOLL/ATL::CAtlMap::SetAt", "ATLCOLL/ATL::CAtlMap::SetOptimalLoad", "ATLCOLL/ATL::CAtlMap::SetValueAt"] helpviewer_keywords: ["CAtlMap class"] -ms.assetid: 5e2fe028-8e6d-4686-93df-1433d2080ec3 --- # CAtlMap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating and managing a map object. ## Syntax diff --git a/docs/atl/reference/catlmodule-class.md b/docs/atl/reference/catlmodule-class.md index 637193f3c88..2136b7f2d94 100644 --- a/docs/atl/reference/catlmodule-class.md +++ b/docs/atl/reference/catlmodule-class.md @@ -4,10 +4,11 @@ title: "CAtlModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlModule", "ATLBASE/ATL::CAtlModule", "ATLBASE/ATL::CAtlModule::CAtlModule", "ATLBASE/ATL::CAtlModule::AddCommonRGSReplacements", "ATLBASE/ATL::CAtlModule::AddTermFunc", "ATLBASE/ATL::CAtlModule::GetGITPtr", "ATLBASE/ATL::CAtlModule::GetLockCount", "ATLBASE/ATL::CAtlModule::Lock", "ATLBASE/ATL::CAtlModule::Term", "ATLBASE/ATL::CAtlModule::Unlock", "ATLBASE/ATL::CAtlModule::UpdateRegistryFromResourceD", "ATLBASE/ATL::CAtlModule::UpdateRegistryFromResourceDHelper", "ATLBASE/ATL::CAtlModule::UpdateRegistryFromResourceS", "ATLBASE/ATL::CAtlModule::m_libid", "ATLBASE/ATL::CAtlModule::m_pGIT"] helpviewer_keywords: ["CAtlModule class"] -ms.assetid: 63fe02f1-4c4b-4e7c-ae97-7ad7b4252415 --- # CAtlModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods used by several ATL module classes. ## Syntax diff --git a/docs/atl/reference/catlmodulet-class.md b/docs/atl/reference/catlmodulet-class.md index aeddee3c887..d8cc2b1db58 100644 --- a/docs/atl/reference/catlmodulet-class.md +++ b/docs/atl/reference/catlmodulet-class.md @@ -4,10 +4,11 @@ title: "CAtlModuleT Class" ms.date: "11/04/2016" f1_keywords: ["CAtlModuleT", "ATLBASE/ATL::CAtlModuleT", "ATLBASE/ATL::CAtlModuleT::CAtlModuleT", "ATLBASE/ATL::CAtlModuleT::InitLibId", "ATLBASE/ATL::CAtlModuleT::RegisterAppId", "ATLBASE/ATL::CAtlModuleT::RegisterServer", "ATLBASE/ATL::CAtlModuleT::UnregisterAppId", "ATLBASE/ATL::CAtlModuleT::UnregisterServer", "ATLBASE/ATL::CAtlModuleT::UpdateRegistryAppId"] helpviewer_keywords: ["CAtlModuleT class"] -ms.assetid: 9b74d02f-9117-47b1-a05e-c5945f83dd2b --- # CAtlModuleT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements an ATL module. ## Syntax diff --git a/docs/atl/reference/catlpreviewctrlimpl-class.md b/docs/atl/reference/catlpreviewctrlimpl-class.md index 2f2fc09617b..c5e24db6ba6 100644 --- a/docs/atl/reference/catlpreviewctrlimpl-class.md +++ b/docs/atl/reference/catlpreviewctrlimpl-class.md @@ -4,10 +4,11 @@ title: "CAtlPreviewCtrlImpl Class" ms.date: "11/04/2016" f1_keywords: ["CAtlPreviewCtrlImpl", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::CAtlPreviewCtrlImpl", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Create", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Destroy", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Focus", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::OnPaint", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::Redraw", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::SetHost", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::SetPreviewVisuals", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::SetRect", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::DoPaint", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::m_plf", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::m_clrBack", "ATLPREVIEWCTRLIMPL/ATL::CAtlPreviewCtrlImpl::m_clrText"] helpviewer_keywords: ["CAtlPreviewCtrlImpl class"] -ms.assetid: 39b3299e-07e4-4abc-9b6e-b54bfa3b0802 --- # CAtlPreviewCtrlImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is an ATL implementation of a window that is placed on a host window provided by the Shell for Rich Preview. > [!IMPORTANT] diff --git a/docs/atl/reference/catlservicemodulet-class.md b/docs/atl/reference/catlservicemodulet-class.md index 8931b815121..19c51da62bc 100644 --- a/docs/atl/reference/catlservicemodulet-class.md +++ b/docs/atl/reference/catlservicemodulet-class.md @@ -4,10 +4,11 @@ title: "CAtlServiceModuleT Class" ms.date: "05/06/2019" f1_keywords: ["CAtlServiceModuleT", "ATLBASE/ATL::CAtlServiceModuleT", "ATLBASE/ATL::CAtlServiceModuleT::CAtlServiceModuleT", "ATLBASE/ATL::CAtlServiceModuleT::Handler", "ATLBASE/ATL::CAtlServiceModuleT::InitializeSecurity", "ATLBASE/ATL::CAtlServiceModuleT::Install", "ATLBASE/ATL::CAtlServiceModuleT::IsInstalled", "ATLBASE/ATL::CAtlServiceModuleT::LogEvent", "ATLBASE/ATL::CAtlServiceModuleT::OnContinue", "ATLBASE/ATL::CAtlServiceModuleT::OnInterrogate", "ATLBASE/ATL::CAtlServiceModuleT::OnPause", "ATLBASE/ATL::CAtlServiceModuleT::OnShutdown", "ATLBASE/ATL::CAtlServiceModuleT::OnStop", "ATLBASE/ATL::CAtlServiceModuleT::OnUnknownRequest", "ATLBASE/ATL::CAtlServiceModuleT::ParseCommandLine", "ATLBASE/ATL::CAtlServiceModuleT::PreMessageLoop", "ATLBASE/ATL::CAtlServiceModuleT::RegisterAppId", "ATLBASE/ATL::CAtlServiceModuleT::Run", "ATLBASE/ATL::CAtlServiceModuleT::ServiceMain", "ATLBASE/ATL::CAtlServiceModuleT::SetServiceStatus", "ATLBASE/ATL::CAtlServiceModuleT::Start", "ATLBASE/ATL::CAtlServiceModuleT::Uninstall", "ATLBASE/ATL::CAtlServiceModuleT::Unlock", "ATLBASE/ATL::CAtlServiceModuleT::UnregisterAppId", "ATLBASE/ATL::CAtlServiceModuleT::WinMain", "ATLBASE/ATL::CAtlServiceModuleT::m_bService", "ATLBASE/ATL::CAtlServiceModuleT::m_dwThreadID", "ATLBASE/ATL::CAtlServiceModuleT::m_hServiceStatus", "ATLBASE/ATL::CAtlServiceModuleT::m_status", "ATLBASE/ATL::CAtlServiceModuleT::m_szServiceName"] helpviewer_keywords: ["CAtlServiceModuleT class"] -ms.assetid: 8fc753ce-4a50-402b-9b4a-0a4ce5dd496c --- # CAtlServiceModuleT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a service. > [!IMPORTANT] diff --git a/docs/atl/reference/catltemporaryfile-class.md b/docs/atl/reference/catltemporaryfile-class.md index ac4ae6210e7..597aaba7e09 100644 --- a/docs/atl/reference/catltemporaryfile-class.md +++ b/docs/atl/reference/catltemporaryfile-class.md @@ -1,13 +1,14 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for the creation and use of a temporary file. > [!IMPORTANT] @@ -357,7 +358,7 @@ Returns the LPCTSTR pointing to the file name. ### Remarks -The file name is generated in [CAtlTemporaryFile::CAtlTemporaryFile](#catltemporaryfile) with a call to the [GetTempFile](/windows/win32/api/fileapi/nf-fileapi-gettempfilenamew)Windows SDK function. The file extension will always be "TFR" for the temporary file. +The file name is generated in [CAtlTemporaryFile::CAtlTemporaryFile](#catltemporaryfile) with a call to the [GetTempFile](/windows/win32/api/fileapi/nf-fileapi-gettempfilenamew) Windows SDK function. The file extension will always be "TFR" for the temporary file. ## CAtlTemporaryFile::UnlockRange diff --git a/docs/atl/reference/catltransactionmanager-class.md b/docs/atl/reference/catltransactionmanager-class.md index 3b7a42f2746..4eec9cfe549 100644 --- a/docs/atl/reference/catltransactionmanager-class.md +++ b/docs/atl/reference/catltransactionmanager-class.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: CAtlTransactionManager Class" title: "CAtlTransactionManager Class" -ms.date: "11/04/2016" +description: "Learn more about: CAtlTransactionManager Class" +ms.date: 11/04/2016 f1_keywords: ["CAtlTransactionManager", "ATLTRANSACTIONMANAGER/ATL::CAtlTransactionManager", "ATLTRANSACTIONMANAGER/ATL::Close", "ATLTRANSACTIONMANAGER/ATL::Commit", "ATLTRANSACTIONMANAGER/ATL::Create", "ATLTRANSACTIONMANAGER/ATL::CreateFile", "ATLTRANSACTIONMANAGER/ATL::DeleteFile", "ATLTRANSACTIONMANAGER/ATL::FindFirstFile", "ATLTRANSACTIONMANAGER/ATL::GetFileAttributes", "ATLTRANSACTIONMANAGER/ATL::GetFileAttributesEx", "ATLTRANSACTIONMANAGER/ATL::GetHandle", "ATLTRANSACTIONMANAGER/ATL::IsFallback", "ATLTRANSACTIONMANAGER/ATL::MoveFile", "ATLTRANSACTIONMANAGER/ATL::RegCreateKeyEx", "ATLTRANSACTIONMANAGER/ATL::RegDeleteKey", "ATLTRANSACTIONMANAGER/ATL::RegOpenKeyEx", "ATLTRANSACTIONMANAGER/ATL::Rollback", "ATLTRANSACTIONMANAGER/ATL::SetFileAttributes", "ATLTRANSACTIONMANAGER/ATL::m_bFallback", "ATLTRANSACTIONMANAGER/ATL::m_hTransaction"] helpviewer_keywords: ["CAtlTransactionManager class"] -ms.assetid: b01732dc-1d16-4b42-bfac-b137fca2b740 --- # CAtlTransactionManager Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + CAtlTransactionManager class provides a wrapper to Kernel Transaction Manager (KTM) functions. > [!IMPORTANT] @@ -66,7 +67,7 @@ class CAtlTransactionManager; **Header:** atltransactionmanager.h -## ~CAtlTransactionManager +## ~CAtlTransactionManager CAtlTransactionManager destructor. diff --git a/docs/atl/reference/catlwinmodule-class.md b/docs/atl/reference/catlwinmodule-class.md index fe46bab7a8f..dfd3f356a9a 100644 --- a/docs/atl/reference/catlwinmodule-class.md +++ b/docs/atl/reference/catlwinmodule-class.md @@ -4,10 +4,11 @@ title: "CAtlWinModule Class" ms.date: "11/04/2016" f1_keywords: ["CAtlWinModule", "ATLBASE/ATL::CAtlWinModule", "ATLBASE/ATL::CAtlWinModule::CAtlWinModule", "ATLBASE/ATL::CAtlWinModule::AddCreateWndData", "ATLBASE/ATL::CAtlWinModule::ExtractCreateWndData"] helpviewer_keywords: ["CAtlWinModule class"] -ms.assetid: 7ec844af-0f68-4a34-b0c8-9de50a025df0 --- # CAtlWinModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides support for ATL windowing components. > [!IMPORTANT] diff --git a/docs/atl/reference/cautoptr-class.md b/docs/atl/reference/cautoptr-class.md index ec51839b4b2..69c6edfac9f 100644 --- a/docs/atl/reference/cautoptr-class.md +++ b/docs/atl/reference/cautoptr-class.md @@ -4,10 +4,11 @@ title: "CAutoPtr class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtr", "ATLBASE/ATL::CAutoPtr", "ATLBASE/ATL::CAutoPtr::CAutoPtr", "ATLBASE/ATL::CAutoPtr::Attach", "ATLBASE/ATL::CAutoPtr::Detach", "ATLBASE/ATL::CAutoPtr::Free", "ATLBASE/ATL::CAutoPtr::m_p"] helpviewer_keywords: ["CAutoPtr class"] -ms.assetid: 08988d53-4fb0-4711-bdfc-8ac29c63f410 --- # `CAutoPtr` class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a smart pointer object. > [!IMPORTANT] diff --git a/docs/atl/reference/cautoptrarray-class.md b/docs/atl/reference/cautoptrarray-class.md index cadb53e14a1..ab3616b4920 100644 --- a/docs/atl/reference/cautoptrarray-class.md +++ b/docs/atl/reference/cautoptrarray-class.md @@ -4,10 +4,11 @@ title: "CAutoPtrArray Class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtrArray", "ATLCOLL/ATL::CAutoPtrArray", "ATLCOLL/ATL::CAutoPtrArray::CAutoPtrArray"] helpviewer_keywords: ["CAutoPtrArray class"] -ms.assetid: 880a70da-8c81-4427-8ac6-49aa8d424244 --- # CAutoPtrArray Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods useful when constructing an array of smart pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/cautoptrelementtraits-class.md b/docs/atl/reference/cautoptrelementtraits-class.md index 90b8dbbea8c..5d2f5125152 100644 --- a/docs/atl/reference/cautoptrelementtraits-class.md +++ b/docs/atl/reference/cautoptrelementtraits-class.md @@ -4,10 +4,11 @@ title: "CAutoPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtrElementTraits", "ATLCOLL/ATL::CAutoPtrElementTraits", "ATLCOLL/ATL::CAutoPtrElementTraits::INARGTYPE", "ATLCOLL/ATL::CAutoPtrElementTraits::OUTARGTYPE"] helpviewer_keywords: ["CAutoPtrElementTraits class"] -ms.assetid: 777c1b14-6ab7-491f-b9a5-be149e71d4a2 --- # CAutoPtrElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods, static functions, and typedefs useful when creating collections of smart pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/cautoptrlist-class.md b/docs/atl/reference/cautoptrlist-class.md index c2b8e2a7d2a..9f1ae599de9 100644 --- a/docs/atl/reference/cautoptrlist-class.md +++ b/docs/atl/reference/cautoptrlist-class.md @@ -4,10 +4,11 @@ title: "CAutoPtrList Class" ms.date: "11/04/2016" f1_keywords: ["CAutoPtrList", "ATLCOLL/ATL::CAutoPtrList", "ATLCOLL/ATL::CAutoPtrList::CAutoPtrList"] helpviewer_keywords: ["CAutoPtrList class"] -ms.assetid: 11de4aca-28b0-4ff2-a74a-cb602312ffbd --- # CAutoPtrList Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods useful when constructing a list of smart pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/cautorevertimpersonation-class.md b/docs/atl/reference/cautorevertimpersonation-class.md index 6f63d124513..0999a258299 100644 --- a/docs/atl/reference/cautorevertimpersonation-class.md +++ b/docs/atl/reference/cautorevertimpersonation-class.md @@ -4,10 +4,11 @@ title: "CAutoRevertImpersonation Class" ms.date: "11/04/2016" f1_keywords: ["CAutoRevertImpersonation", "ATLSECURITY/ATL::CAutoRevertImpersonation", "ATLSECURITY/ATL::CAutoRevertImpersonation::CAutoRevertImpersonation", "ATLSECURITY/ATL::CAutoRevertImpersonation::Attach", "ATLSECURITY/ATL::CAutoRevertImpersonation::Detach", "ATLSECURITY/ATL::CAutoRevertImpersonation::GetAccessToken"] helpviewer_keywords: ["CAutoRevertImpersonation class"] -ms.assetid: 43732849-1940-4bd4-9d52-7a5698bb8838 --- # CAutoRevertImpersonation Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class reverts [CAccessToken](../../atl/reference/caccesstoken-class.md) objects to a nonimpersonating state when it goes out of scope. ## Syntax diff --git a/docs/atl/reference/cautovectorptr-class.md b/docs/atl/reference/cautovectorptr-class.md index be4c474bcce..e53ebac6abb 100644 --- a/docs/atl/reference/cautovectorptr-class.md +++ b/docs/atl/reference/cautovectorptr-class.md @@ -4,10 +4,11 @@ title: "CAutoVectorPtr Class" ms.date: "11/04/2016" f1_keywords: ["CAutoVectorPtr", "ATLBASE/ATL::CAutoVectorPtr", "ATLBASE/ATL::CAutoVectorPtr::CAutoVectorPtr", "ATLBASE/ATL::CAutoVectorPtr::Allocate", "ATLBASE/ATL::CAutoVectorPtr::Attach", "ATLBASE/ATL::CAutoVectorPtr::Detach", "ATLBASE/ATL::CAutoVectorPtr::Free", "ATLBASE/ATL::CAutoVectorPtr::m_p"] helpviewer_keywords: ["CAutoVectorPtr class"] -ms.assetid: 0030362b-6bc4-4a47-9b5b-3c3899dceab4 --- # CAutoVectorPtr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a smart pointer object using vector new and delete operators. > [!IMPORTANT] diff --git a/docs/atl/reference/cautovectorptrelementtraits-class.md b/docs/atl/reference/cautovectorptrelementtraits-class.md index 86e766db0b2..7a18d053716 100644 --- a/docs/atl/reference/cautovectorptrelementtraits-class.md +++ b/docs/atl/reference/cautovectorptrelementtraits-class.md @@ -4,10 +4,11 @@ title: "CAutoVectorPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CAutoVectorPtrElementTraits", "ATLCOLL/ATL::CAutoVectorPtrElementTraits", "ATLCOLL/ATL::CAutoVectorPtrElementTraits::INARGTYPE", "ATLCOLL/ATL::CAutoVectorPtrElementTraits::OUTARGTYPE"] helpviewer_keywords: ["CAutoVectorPtrElementTraits class"] -ms.assetid: 16b81a56-55fb-46ca-b376-66a1884231a6 --- # CAutoVectorPtrElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods, static functions, and typedefs useful when creating collections of smart pointers using vector new and delete operators. > [!IMPORTANT] diff --git a/docs/atl/reference/caxdialogimpl-class.md b/docs/atl/reference/caxdialogimpl-class.md index 76937ed12b0..8e536aadf64 100644 --- a/docs/atl/reference/caxdialogimpl-class.md +++ b/docs/atl/reference/caxdialogimpl-class.md @@ -4,10 +4,11 @@ title: "CAxDialogImpl Class" ms.date: "11/04/2016" f1_keywords: ["CAxDialogImpl", "ATLWIN/ATL::CAxDialogImpl", "ATLWIN/ATL::CAxDialogImpl::AdviseSinkMap", "ATLWIN/ATL::CAxDialogImpl::Create", "ATLWIN/ATL::CAxDialogImpl::DestroyWindow", "ATLWIN/ATL::CAxDialogImpl::DoModal", "ATLWIN/ATL::CAxDialogImpl::EndDialog", "ATLWIN/ATL::CAxDialogImpl::GetDialogProc", "ATLWIN/ATL::CAxDialogImpl::GetIDD", "ATLWIN/ATL::CAxDialogImpl::IsDialogMessage", "ATLWIN/ATL::CAxDialogImpl::m_bModal"] helpviewer_keywords: ["CAxDialogImpl class", "ATL, dialog boxes"] -ms.assetid: 817df483-3fa8-44e7-8487-72ba0881cd27 --- # CAxDialogImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a dialog box (modal or modeless) that hosts ActiveX controls. > [!IMPORTANT] diff --git a/docs/atl/reference/caxwindow-class.md b/docs/atl/reference/caxwindow-class.md index 4c266ad417c..6a8268eb678 100644 --- a/docs/atl/reference/caxwindow-class.md +++ b/docs/atl/reference/caxwindow-class.md @@ -4,10 +4,17 @@ title: "CAxWindow Class" 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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for manipulating a window hosting an ActiveX control. > [!IMPORTANT] diff --git a/docs/atl/reference/caxwindow2t-class.md b/docs/atl/reference/caxwindow2t-class.md index 866f52ad95f..b8ed27afc15 100644 --- a/docs/atl/reference/caxwindow2t-class.md +++ b/docs/atl/reference/caxwindow2t-class.md @@ -4,10 +4,11 @@ title: "CAxWindow2T Class" ms.date: "11/04/2016" f1_keywords: ["CAxWindow2T", "ATLWIN/ATL::CAxWindow2T", "ATLWIN/ATL::CAxWindow2T::CAxWindow2T", "ATLWIN/ATL::CAxWindow2T::Create", "ATLWIN/ATL::CAxWindow2T::CreateControlLic", "ATLWIN/ATL::CAxWindow2T::CreateControlLicEx", "ATLWIN/ATL::CAxWindow2T::GetWndClassName"] helpviewer_keywords: ["CAxWindow2 class"] -ms.assetid: b87bc943-7991-4537-b902-2138d7f4d837 --- # CAxWindow2T Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for manipulating a window that hosts an ActiveX control, and also has support for hosting licensed ActiveX controls. > [!IMPORTANT] diff --git a/docs/atl/reference/cbindstatuscallback-class.md b/docs/atl/reference/cbindstatuscallback-class.md index 1de6349c0cc..795c96c8517 100644 --- a/docs/atl/reference/cbindstatuscallback-class.md +++ b/docs/atl/reference/cbindstatuscallback-class.md @@ -4,10 +4,11 @@ title: "CBindStatusCallback Class" ms.date: "11/04/2016" f1_keywords: ["CBindStatusCallback", "ATLCTL/ATL::CBindStatusCallback", "ATLCTL/ATL::CBindStatusCallback::CBindStatusCallback", "ATLCTL/ATL::CBindStatusCallback::Download", "ATLCTL/ATL::CBindStatusCallback::GetBindInfo", "ATLCTL/ATL::CBindStatusCallback::GetPriority", "ATLCTL/ATL::CBindStatusCallback::OnDataAvailable", "ATLCTL/ATL::CBindStatusCallback::OnLowResource", "ATLCTL/ATL::CBindStatusCallback::OnObjectAvailable", "ATLCTL/ATL::CBindStatusCallback::OnProgress", "ATLCTL/ATL::CBindStatusCallback::OnStartBinding", "ATLCTL/ATL::CBindStatusCallback::OnStopBinding", "ATLCTL/ATL::CBindStatusCallback::StartAsyncDownload", "ATLCTL/ATL::CBindStatusCallback::m_dwAvailableToRead", "ATLCTL/ATL::CBindStatusCallback::m_dwTotalRead", "ATLCTL/ATL::CBindStatusCallback::m_pFunc", "ATLCTL/ATL::CBindStatusCallback::m_pT", "ATLCTL/ATL::CBindStatusCallback::m_spBindCtx", "ATLCTL/ATL::CBindStatusCallback::m_spBinding", "ATLCTL/ATL::CBindStatusCallback::m_spMoniker", "ATLCTL/ATL::CBindStatusCallback::m_spStream"] helpviewer_keywords: ["asynchronous data transfer [C++]", "data transfer [C++]", "data transfer [C++], asynchronous", "CBindStatusCallback class"] -ms.assetid: 0f5da276-6031-4418-b2a9-a4750ef29e77 --- # CBindStatusCallback Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements the `IBindStatusCallback` interface. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomaggobject-class.md b/docs/atl/reference/ccomaggobject-class.md index b6eefe72330..f3401c8642f 100644 --- a/docs/atl/reference/ccomaggobject-class.md +++ b/docs/atl/reference/ccomaggobject-class.md @@ -4,10 +4,11 @@ title: "CComAggObject Class" ms.date: "11/04/2016" f1_keywords: ["CComAggObject", "ATLCOM/ATL::CComAggObject", "ATLCOM/ATL::CComAggObject::CComAggObject", "ATLCOM/ATL::CComAggObject::AddRef", "ATLCOM/ATL::CComAggObject::CreateInstance", "ATLCOM/ATL::CComAggObject::FinalConstruct", "ATLCOM/ATL::CComAggObject::FinalRelease", "ATLCOM/ATL::CComAggObject::QueryInterface", "ATLCOM/ATL::CComAggObject::Release", "ATLCOM/ATL::CComAggObject::m_contained"] helpviewer_keywords: ["aggregate objects [C++], in ATL", "aggregation [C++], ATL objects", "CComAggObject class"] -ms.assetid: 7aa90d69-d399-477b-880d-e2cdf0ef7881 --- # CComAggObject Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements the [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface for an aggregated object. By definition, an aggregated object is contained within an outer object. The `CComAggObject` class is similar to the [CComObject Class](../../atl/reference/ccomobject-class.md), except that it exposes an interface that is directly accessible to external clients. ## Syntax diff --git a/docs/atl/reference/ccomallocator-class.md b/docs/atl/reference/ccomallocator-class.md index c29ebdbe019..83af39f1631 100644 --- a/docs/atl/reference/ccomallocator-class.md +++ b/docs/atl/reference/ccomallocator-class.md @@ -4,10 +4,11 @@ title: "CComAllocator Class" ms.date: "11/04/2016" f1_keywords: ["CComAllocator", "ATLBASE/ATL::CComAllocator", "ATLBASE/ATL::CComAllocator::Allocate", "ATLBASE/ATL::CComAllocator::Free", "ATLBASE/ATL::CComAllocator::Reallocate"] helpviewer_keywords: ["CComAllocator class"] -ms.assetid: 0cd706fd-0c7b-42d3-9054-febe2966fc8e --- # CComAllocator Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for managing memory using COM memory routines. ## Syntax diff --git a/docs/atl/reference/ccomapartment-class.md b/docs/atl/reference/ccomapartment-class.md index b49417cff84..f1b11e286b0 100644 --- a/docs/atl/reference/ccomapartment-class.md +++ b/docs/atl/reference/ccomapartment-class.md @@ -4,10 +4,11 @@ title: "CComApartment Class" ms.date: "11/04/2016" f1_keywords: ["CComApartment", "ATLBASE/ATL::CComApartment", "ATLBASE/ATL::CComApartment::CComApartment", "ATLBASE/ATL::CComApartment::Apartment", "ATLBASE/ATL::CComApartment::GetLockCount", "ATLBASE/ATL::CComApartment::Lock", "ATLBASE/ATL::CComApartment::Unlock", "ATLBASE/ATL::CComApartment::m_dwThreadID", "ATLBASE/ATL::CComApartment::m_hThread", "ATLBASE/ATL::CComApartment::m_nLockCnt"] helpviewer_keywords: ["apartments in ATL EXE modules", "CComApartment class"] -ms.assetid: dbc177d7-7ee4-45f2-b563-d578a467ca93 --- # CComApartment Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides support for managing an apartment in a thread-pooled EXE module. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomautocriticalsection-class.md b/docs/atl/reference/ccomautocriticalsection-class.md index 1307f3e999d..a2f558a71ac 100644 --- a/docs/atl/reference/ccomautocriticalsection-class.md +++ b/docs/atl/reference/ccomautocriticalsection-class.md @@ -4,10 +4,11 @@ title: "CComAutoCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComAutoCriticalSection", "ATLCORE/ATL::CComAutoCriticalSection", "ATLCORE/ATL::CComAutoCriticalSection::CComAutoCriticalSection"] helpviewer_keywords: ["CComAutoCriticalSection class"] -ms.assetid: 491a9d90-3398-4f90-88f5-fd2172a46b30 --- # CComAutoCriticalSection Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + `CComAutoCriticalSection` provides methods for obtaining and releasing ownership of a critical section object. ## Syntax diff --git a/docs/atl/reference/ccomautodeletecriticalsection-class.md b/docs/atl/reference/ccomautodeletecriticalsection-class.md index b7ab596a45f..61c39b5626b 100644 --- a/docs/atl/reference/ccomautodeletecriticalsection-class.md +++ b/docs/atl/reference/ccomautodeletecriticalsection-class.md @@ -4,10 +4,11 @@ title: "CComAutoDeleteCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComAutoDeleteCriticalSection", "atlcore/ATL::CComAutoDeleteCriticalSection"] helpviewer_keywords: ["CComAutoDeleteCriticalSection class"] -ms.assetid: 2396dbea-1c60-4841-b50e-c4e18af311a3 --- # CComAutoDeleteCriticalSection Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for obtaining and releasing ownership of a critical section object. ## Syntax diff --git a/docs/atl/reference/ccomautothreadmodule-class.md b/docs/atl/reference/ccomautothreadmodule-class.md index 4cff4d76b9d..2c6e947a2fe 100644 --- a/docs/atl/reference/ccomautothreadmodule-class.md +++ b/docs/atl/reference/ccomautothreadmodule-class.md @@ -4,10 +4,11 @@ title: "CComAutoThreadModule Class" ms.date: "11/04/2016" f1_keywords: ["CComAutoThreadModule", "ATLBASE/ATL::CComAutoThreadModule", "ATLBASE/ATL::CreateInstance", "ATLBASE/ATL::GetDefaultThreads", "ATLBASE/ATL::Init", "ATLBASE/ATL::Lock", "ATLBASE/ATL::Unlock", "ATLBASE/ATL::dwThreadID", "ATLBASE/ATL::m_Allocator", "ATLBASE/ATL::m_nThreads", "ATLBASE/ATL::m_pApartments"] helpviewer_keywords: ["CComAutoThreadModule class", "apartment model modules"] -ms.assetid: 13063ea5-a57e-4aac-97d3-227137262811 --- # CComAutoThreadModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + As of ATL 7.0, `CComAutoThreadModule` is obsolete: see [ATL Module Classes](../../atl/atl-module-classes.md) for more details. > [!IMPORTANT] diff --git a/docs/atl/reference/ccombstr-class.md b/docs/atl/reference/ccombstr-class.md index 14c7a7e8d83..7062d1d7d9c 100644 --- a/docs/atl/reference/ccombstr-class.md +++ b/docs/atl/reference/ccombstr-class.md @@ -4,10 +4,11 @@ title: "CComBSTR Class" ms.date: "11/04/2016" f1_keywords: ["CComBSTR", "ATLBASE/ATL::CComBSTR", "ATLBASE/ATL::CComBSTR::CComBSTR", "ATLBASE/ATL::CComBSTR::Append", "ATLBASE/ATL::CComBSTR::AppendBSTR", "ATLBASE/ATL::CComBSTR::AppendBytes", "ATLBASE/ATL::CComBSTR::ArrayToBSTR", "ATLBASE/ATL::CComBSTR::AssignBSTR", "ATLBASE/ATL::CComBSTR::Attach", "ATLBASE/ATL::CComBSTR::BSTRToArray", "ATLBASE/ATL::CComBSTR::ByteLength", "ATLBASE/ATL::CComBSTR::Copy", "ATLBASE/ATL::CComBSTR::CopyTo", "ATLBASE/ATL::CComBSTR::Detach", "ATLBASE/ATL::CComBSTR::Empty", "ATLBASE/ATL::CComBSTR::Length", "ATLBASE/ATL::CComBSTR::LoadString", "ATLBASE/ATL::CComBSTR::ReadFromStream", "ATLBASE/ATL::CComBSTR::ToLower", "ATLBASE/ATL::CComBSTR::ToUpper", "ATLBASE/ATL::CComBSTR::WriteToStream", "ATLBASE/ATL::CComBSTR::m_str"] helpviewer_keywords: ["BSTRs, wrapper", "CComBSTR class", "CComBSTR"] -ms.assetid: 8fea1879-a05e-47a5-a803-8dec60eaa534 --- # `CComBSTR` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for [`BSTR`](/previous-versions/windows/desktop/automat/bstr)s. ## Syntax diff --git a/docs/atl/reference/ccomcachedtearoffobject-class.md b/docs/atl/reference/ccomcachedtearoffobject-class.md index 26e8f9526df..bfeda509925 100644 --- a/docs/atl/reference/ccomcachedtearoffobject-class.md +++ b/docs/atl/reference/ccomcachedtearoffobject-class.md @@ -4,10 +4,11 @@ title: "CComCachedTearOffObject Class" ms.date: "11/04/2016" f1_keywords: ["CComCachedTearOffObject", "ATLCOM/ATL::CComCachedTearOffObject", "ATLCOM/ATL::CComCachedTearOffObject::CComCachedTearOffObject", "ATLCOM/ATL::CComCachedTearOffObject::AddRef", "ATLCOM/ATL::CComCachedTearOffObject::FinalConstruct", "ATLCOM/ATL::CComCachedTearOffObject::FinalRelease", "ATLCOM/ATL::CComCachedTearOffObject::QueryInterface", "ATLCOM/ATL::CComCachedTearOffObject::Release", "ATLCOM/ATL::CComCachedTearOffObject::m_contained"] helpviewer_keywords: ["cache, ATL cached tear-off objects", "CComCachedTearOffObject class"] -ms.assetid: ae19507d-a1de-4dbc-a988-da9f75a50c95 --- # CComCachedTearOffObject Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) for a tear-off interface. ## Syntax diff --git a/docs/atl/reference/ccomclassfactory-class.md b/docs/atl/reference/ccomclassfactory-class.md index 02636d54b19..8ffc9ddddb9 100644 --- a/docs/atl/reference/ccomclassfactory-class.md +++ b/docs/atl/reference/ccomclassfactory-class.md @@ -4,10 +4,11 @@ title: "CComClassFactory Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactory", "ATLCOM/ATL::CComClassFactory", "ATLCOM/ATL::CComClassFactory::CreateInstance", "ATLCOM/ATL::CComClassFactory::LockServer"] helpviewer_keywords: ["CComClassFactory class"] -ms.assetid: e56dacf7-d5c4-4c42-aef4-a86d91981a1b --- # CComClassFactory Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements the [IClassFactory](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface. ## Syntax diff --git a/docs/atl/reference/ccomclassfactory2-class.md b/docs/atl/reference/ccomclassfactory2-class.md index 6a40fbd71ed..b96614dc260 100644 --- a/docs/atl/reference/ccomclassfactory2-class.md +++ b/docs/atl/reference/ccomclassfactory2-class.md @@ -4,10 +4,11 @@ title: "CComClassFactory2 Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactory2", "ATLCOM/ATL::CComClassFactory2", "ATLCOM/ATL::CComClassFactory2::CreateInstance", "ATLCOM/ATL::CComClassFactory2::CreateInstanceLic", "ATLCOM/ATL::CComClassFactory2::GetLicInfo", "ATLCOM/ATL::CComClassFactory2::LockServer", "ATLCOM/ATL::CComClassFactory2::RequestLicKey"] helpviewer_keywords: ["CComClassFactory2 class"] -ms.assetid: 19b66fd6-b9ed-47a0-822c-8132184f5a3e --- # CComClassFactory2 Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements the [IClassFactory2](/windows/win32/api/ocidl/nn-ocidl-iclassfactory2) interface. ## Syntax diff --git a/docs/atl/reference/ccomclassfactoryautothread-class.md b/docs/atl/reference/ccomclassfactoryautothread-class.md index af076db252a..39c4c45f686 100644 --- a/docs/atl/reference/ccomclassfactoryautothread-class.md +++ b/docs/atl/reference/ccomclassfactoryautothread-class.md @@ -4,10 +4,11 @@ title: "CComClassFactoryAutoThread Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactoryAutoThread", "ATLCOM/ATL::CComClassFactoryAutoThread", "ATLCOM/ATL::CComClassFactoryAutoThread::CreateInstance", "ATLCOM/ATL::CComClassFactoryAutoThread::LockServer"] helpviewer_keywords: ["CComClassFactoryAutoThread class"] -ms.assetid: 22008042-533f-4dd9-bf7e-191ee571f9a1 --- # CComClassFactoryAutoThread Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements the [IClassFactory](/windows/win32/api/unknwnbase/nn-unknwnbase-iclassfactory) interface, and allows objects to be created in multiple apartments. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomclassfactorysingleton-class.md b/docs/atl/reference/ccomclassfactorysingleton-class.md index 7559d27a594..a2eb6745545 100644 --- a/docs/atl/reference/ccomclassfactorysingleton-class.md +++ b/docs/atl/reference/ccomclassfactorysingleton-class.md @@ -4,10 +4,11 @@ title: "CComClassFactorySingleton Class" ms.date: "11/04/2016" f1_keywords: ["CComClassFactorySingleton", "ATLCOM/ATL::CComClassFactorySingleton", "ATLCOM/ATL::CComClassFactorySingleton::CreateInstance", "ATLCOM/ATL::CComClassFactorySingleton::m_spObj"] helpviewer_keywords: ["CComClassFactorySingleton class"] -ms.assetid: debb983c-382b-487b-8d42-7ea26dc158b8 --- # CComClassFactorySingleton Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class derives from [CComClassFactory](../../atl/reference/ccomclassfactory-class.md) and uses [CComObjectGlobal](../../atl/reference/ccomobjectglobal-class.md) to construct a single object. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomcoclass-class.md b/docs/atl/reference/ccomcoclass-class.md index 1cea7aa58c6..c9ccbbc5100 100644 --- a/docs/atl/reference/ccomcoclass-class.md +++ b/docs/atl/reference/ccomcoclass-class.md @@ -1,40 +1,41 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating instances of a class, and obtaining its properties. ## 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 +59,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 +102,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 +131,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 +144,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 +171,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 +179,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 +191,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/ccomcompositecontrol-class.md b/docs/atl/reference/ccomcompositecontrol-class.md index d2899ea4afc..09bdc9f10a2 100644 --- a/docs/atl/reference/ccomcompositecontrol-class.md +++ b/docs/atl/reference/ccomcompositecontrol-class.md @@ -4,10 +4,11 @@ title: "CComCompositeControl Class" ms.date: "11/04/2016" f1_keywords: ["CComCompositeControl", "ATLCTL/ATL::CComCompositeControl", "ATLCTL/ATL::CComCompositeControl::CComCompositeControl", "ATLCTL/ATL::CComCompositeControl::AdviseSinkMap", "ATLCTL/ATL::CComCompositeControl::CalcExtent", "ATLCTL/ATL::CComCompositeControl::Create", "ATLCTL/ATL::CComCompositeControl::CreateControlWindow", "ATLCTL/ATL::CComCompositeControl::SetBackgroundColorFromAmbient", "ATLCTL/ATL::CComCompositeControl::m_hbrBackground", "ATLCTL/ATL::CComCompositeControl::m_hWndFocus"] helpviewer_keywords: ["CComCompositeControl class", "composite controls, CComCompositeControl class"] -ms.assetid: 1304b931-27e8-4fbc-be8e-bb226ad887fb --- # CComCompositeControl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides the methods required to implement a composite control. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomcontainedobject-class.md b/docs/atl/reference/ccomcontainedobject-class.md index 1f6f7008ce7..47a9a11db59 100644 --- a/docs/atl/reference/ccomcontainedobject-class.md +++ b/docs/atl/reference/ccomcontainedobject-class.md @@ -4,10 +4,11 @@ title: "CComContainedObject Class" ms.date: "11/04/2016" f1_keywords: ["CComContainedObject", "ATLCOM/ATL::CComContainedObject", "ATLCOM/ATL::CComContainedObject::CComContainedObject", "ATLCOM/ATL::CComContainedObject::AddRef", "ATLCOM/ATL::CComContainedObject::GetControllingUnknown", "ATLCOM/ATL::CComContainedObject::QueryInterface", "ATLCOM/ATL::CComContainedObject::Release"] helpviewer_keywords: ["aggregate objects [C++], in ATL", "aggregation [C++], ATL objects", "CComContainedObject class"] -ms.assetid: e8616b41-c200-47b8-bf2c-fb9f713ebdad --- # CComContainedObject Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) by delegating to the owner object's `IUnknown`. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomcontrol-class.md b/docs/atl/reference/ccomcontrol-class.md index 4c3cba00c3e..ef8078200c8 100644 --- a/docs/atl/reference/ccomcontrol-class.md +++ b/docs/atl/reference/ccomcontrol-class.md @@ -4,10 +4,11 @@ title: "CComControl Class" ms.date: "11/04/2016" f1_keywords: ["CComControl", "ATLCTL/ATL::CComControl", "ATLCTL/ATL::CComControl::CComControl", "ATLCTL/ATL::CComControl::ControlQueryInterface", "ATLCTL/ATL::CComControl::CreateControlWindow", "ATLCTL/ATL::CComControl::FireOnChanged", "ATLCTL/ATL::CComControl::FireOnRequestEdit", "ATLCTL/ATL::CComControl::MessageBox"] helpviewer_keywords: ["control flags", "CComControlBase class, CComControl class", "stock properties, ATL", "CComControl class", "controls [ATL], control helper functions", "ambient properties", "controls [ATL], properties"] -ms.assetid: 55368c27-bd16-45a7-b701-edb36157c8e8 --- # CComControl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating and managing ATL controls. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomcontrolbase-class.md b/docs/atl/reference/ccomcontrolbase-class.md index f6b457426fc..82c638b2f4b 100644 --- a/docs/atl/reference/ccomcontrolbase-class.md +++ b/docs/atl/reference/ccomcontrolbase-class.md @@ -4,10 +4,11 @@ title: "CComControlBase Class" ms.date: "11/04/2016" f1_keywords: ["CComControlBase", "ATLCTL/ATL::CComControlBase", "ATLCTL/ATL::CComControlBase::AppearanceType", "ATLCTL/ATL::CComControlBase::CComControlBase", "ATLCTL/ATL::CComControlBase::ControlQueryInterface", "ATLCTL/ATL::CComControlBase::DoesVerbActivate", "ATLCTL/ATL::CComControlBase::DoesVerbUIActivate", "ATLCTL/ATL::CComControlBase::DoVerbProperties", "ATLCTL/ATL::CComControlBase::FireViewChange", "ATLCTL/ATL::CComControlBase::GetAmbientAppearance", "ATLCTL/ATL::CComControlBase::GetAmbientAutoClip", "ATLCTL/ATL::CComControlBase::GetAmbientBackColor", "ATLCTL/ATL::CComControlBase::GetAmbientCharSet", "ATLCTL/ATL::CComControlBase::GetAmbientCodePage", "ATLCTL/ATL::CComControlBase::GetAmbientDisplayAsDefault", "ATLCTL/ATL::CComControlBase::GetAmbientDisplayName", "ATLCTL/ATL::CComControlBase::GetAmbientFont", "ATLCTL/ATL::CComControlBase::GetAmbientFontDisp", "ATLCTL/ATL::CComControlBase::GetAmbientForeColor", "ATLCTL/ATL::CComControlBase::GetAmbientLocaleID", "ATLCTL/ATL::CComControlBase::GetAmbientMessageReflect", "ATLCTL/ATL::CComControlBase::GetAmbientPalette", "ATLCTL/ATL::CComControlBase::GetAmbientProperty", "ATLCTL/ATL::CComControlBase::GetAmbientRightToLeft", "ATLCTL/ATL::CComControlBase::GetAmbientScaleUnits", "ATLCTL/ATL::CComControlBase::GetAmbientShowGrabHandles", "ATLCTL/ATL::CComControlBase::GetAmbientShowHatching", "ATLCTL/ATL::CComControlBase::GetAmbientSupportsMnemonics", "ATLCTL/ATL::CComControlBase::GetAmbientTextAlign", "ATLCTL/ATL::CComControlBase::GetAmbientTopToBottom", "ATLCTL/ATL::CComControlBase::GetAmbientUIDead", "ATLCTL/ATL::CComControlBase::GetAmbientUserMode", "ATLCTL/ATL::CComControlBase::GetDirty", "ATLCTL/ATL::CComControlBase::GetZoomInfo", "ATLCTL/ATL::CComControlBase::InPlaceActivate", "ATLCTL/ATL::CComControlBase::InternalGetSite", "ATLCTL/ATL::CComControlBase::OnDraw", "ATLCTL/ATL::CComControlBase::OnDrawAdvanced", "ATLCTL/ATL::CComControlBase::OnKillFocus", "ATLCTL/ATL::CComControlBase::OnMouseActivate", "ATLCTL/ATL::CComControlBase::OnPaint", "ATLCTL/ATL::CComControlBase::OnSetFocus", "ATLCTL/ATL::CComControlBase::PreTranslateAccelerator", "ATLCTL/ATL::CComControlBase::SendOnClose", "ATLCTL/ATL::CComControlBase::SendOnDataChange", "ATLCTL/ATL::CComControlBase::SendOnRename", "ATLCTL/ATL::CComControlBase::SendOnSave", "ATLCTL/ATL::CComControlBase::SendOnViewChange", "ATLCTL/ATL::CComControlBase::SetControlFocus", "ATLCTL/ATL::CComControlBase::SetDirty", "ATLCTL/ATL::CComControlBase::m_bAutoSize", "ATLCTL/ATL::CComControlBase::m_bDrawFromNatural", "ATLCTL/ATL::CComControlBase::m_bDrawGetDataInHimetric", "ATLCTL/ATL::CComControlBase::m_bInPlaceActive", "ATLCTL/ATL::CComControlBase::m_bInPlaceSiteEx", "ATLCTL/ATL::CComControlBase::m_bNegotiatedWnd", "ATLCTL/ATL::CComControlBase::m_bRecomposeOnResize", "ATLCTL/ATL::CComControlBase::m_bRequiresSave", "ATLCTL/ATL::CComControlBase::m_bResizeNatural", "ATLCTL/ATL::CComControlBase::m_bUIActive", "ATLCTL/ATL::CComControlBase::m_bUsingWindowRgn", "ATLCTL/ATL::CComControlBase::m_bWasOnceWindowless", "ATLCTL/ATL::CComControlBase::m_bWindowOnly", "ATLCTL/ATL::CComControlBase::m_bWndLess", "ATLCTL/ATL::CComControlBase::m_hWndCD", "ATLCTL/ATL::CComControlBase::m_nFreezeEvents", "ATLCTL/ATL::CComControlBase::m_rcPos", "ATLCTL/ATL::CComControlBase::m_sizeExtent", "ATLCTL/ATL::CComControlBase::m_sizeNatural", "ATLCTL/ATL::CComControlBase::m_spAdviseSink", "ATLCTL/ATL::CComControlBase::m_spAmbientDispatch", "ATLCTL/ATL::CComControlBase::m_spClientSite", "ATLCTL/ATL::CComControlBase::m_spDataAdviseHolder", "ATLCTL/ATL::CComControlBase::m_spInPlaceSite", "ATLCTL/ATL::CComControlBase::m_spOleAdviseHolder"] helpviewer_keywords: ["CComControlBase class"] -ms.assetid: 3d1bf022-acf2-4092-8283-ff8cee6332f3 --- # CComControlBase Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating and managing ATL controls. > [!IMPORTANT] @@ -252,7 +253,7 @@ One of the standard HRESULT values. ### Example [!code-cpp[NVC_ATL_COM#19](../../atl/codesnippet/cpp/ccomcontrolbase-class_2.cpp)] - +  [!code-cpp[NVC_ATL_COM#20](../../atl/codesnippet/cpp/ccomcontrolbase-class_3.h)] ## CComControlBase::FireViewChange diff --git a/docs/atl/reference/ccomcriticalsection-class.md b/docs/atl/reference/ccomcriticalsection-class.md index 7ee8d73ac54..dc63e60f1ee 100644 --- a/docs/atl/reference/ccomcriticalsection-class.md +++ b/docs/atl/reference/ccomcriticalsection-class.md @@ -4,10 +4,11 @@ title: "CComCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComCriticalSection", "ATLCORE/ATL::CComCriticalSection", "ATLCORE/ATL::CComCriticalSection::CComCriticalSection", "ATLCORE/ATL::CComCriticalSection::Init", "ATLCORE/ATL::CComCriticalSection::Lock", "ATLCORE/ATL::CComCriticalSection::Term", "ATLCORE/ATL::CComCriticalSection::Unlock", "ATLCORE/ATL::CComCriticalSection::m_sec"] helpviewer_keywords: ["CComCriticalSection class"] -ms.assetid: 44e1edd2-90be-4bfe-9739-58e8b419e7d1 --- # CComCriticalSection Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for obtaining and releasing ownership of a critical section object. ## Syntax diff --git a/docs/atl/reference/ccomcritseclock-class.md b/docs/atl/reference/ccomcritseclock-class.md index 726f3bc79c4..2b05e7b608c 100644 --- a/docs/atl/reference/ccomcritseclock-class.md +++ b/docs/atl/reference/ccomcritseclock-class.md @@ -4,10 +4,11 @@ title: "CComCritSecLock Class" ms.date: "11/04/2016" f1_keywords: ["CComCritSecLock", "ATLBASE/ATL::CComCritSecLock", "ATLBASE/ATL::CComCritSecLock::CComCritSecLock", "ATLBASE/ATL::CComCritSecLock::Lock", "ATLBASE/ATL::CComCritSecLock::Unlock"] helpviewer_keywords: ["CComCritSecLock class"] -ms.assetid: 223152a1-86c3-4ef9-89a7-f455fe791b0e --- # CComCritSecLock Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for locking and unlocking a critical section object. ## Syntax diff --git a/docs/atl/reference/ccomcurrency-class.md b/docs/atl/reference/ccomcurrency-class.md index b51cb2e04a2..ba76d99a06d 100644 --- a/docs/atl/reference/ccomcurrency-class.md +++ b/docs/atl/reference/ccomcurrency-class.md @@ -1,13 +1,14 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + `CComCurrency` has methods and operators for creating and managing a `CURRENCY` object. ## Syntax @@ -563,7 +564,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 19adbd15a52..f81b285a499 100644 --- a/docs/atl/reference/ccomdynamicunkarray-class.md +++ b/docs/atl/reference/ccomdynamicunkarray-class.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: CComDynamicUnkArray Class" title: "CComDynamicUnkArray Class" -ms.date: "11/04/2016" +description: "Learn more about: CComDynamicUnkArray Class" +ms.date: 11/04/2016 f1_keywords: ["CComDynamicUnkArray", "ATLCOM/ATL::CComDynamicUnkArray", "ATLCOM/ATL::CComDynamicUnkArray::CComDynamicUnkArray", "ATLCOM/ATL::CComDynamicUnkArray::Add", "ATLCOM/ATL::CComDynamicUnkArray::begin", "ATLCOM/ATL::CComDynamicUnkArray::clear", "ATLCOM/ATL::CComDynamicUnkArray::end", "ATLCOM/ATL::CComDynamicUnkArray::GetAt", "ATLCOM/ATL::CComDynamicUnkArray::GetCookie", "ATLCOM/ATL::CComDynamicUnkArray::GetSize", "ATLCOM/ATL::CComDynamicUnkArray::GetUnknown", "ATLCOM/ATL::CComDynamicUnkArray::Remove"] helpviewer_keywords: ["connection points [C++], managing", "CComDynamicUnkArray class"] -ms.assetid: 202470d7-9a1b-498f-b96d-659d681acd65 --- # CComDynamicUnkArray Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class stores an array of `IUnknown` pointers. ## Syntax @@ -35,7 +36,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 +70,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 +98,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 +130,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 +158,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 +183,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,7 +193,7 @@ int GetSize() const; ### Return Value -The length of the array. +The number of elements the array can store. `GetSize() == end() - begin()`. ## CComDynamicUnkArray::GetUnknown @@ -206,6 +216,8 @@ Returns the `IUnknown` pointer, or NULL if no matching cookie is found. Call this method to remove an `IUnknown` pointer from the array. +All other elements are unchanged and retain their index and cookie. + ``` BOOL Remove(DWORD dwCookie); ``` diff --git a/docs/atl/reference/ccomenum-class.md b/docs/atl/reference/ccomenum-class.md index 8ca27ce7d66..d8c54423b54 100644 --- a/docs/atl/reference/ccomenum-class.md +++ b/docs/atl/reference/ccomenum-class.md @@ -4,10 +4,11 @@ title: "CComEnum Class" ms.date: "11/04/2016" f1_keywords: ["CComEnum", "atlcom/ATL::CComEnum"] helpviewer_keywords: ["CComEnum class"] -ms.assetid: bff7dd7b-eb6e-4d6e-96ed-2706e66c8b3b --- # CComEnum Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class defines a COM enumerator object based on an array. ## Syntax @@ -76,7 +77,7 @@ The code shown below provides a reusable function for creating and initializing [!code-cpp[NVC_ATL_COM#32](../../atl/codesnippet/cpp/ccomenum-class_1.h)] -This template function can be used to implement the `_NewEnum` property of a collection interface as shown below: +This function template can be used to implement the `_NewEnum` property of a collection interface as shown below: [!code-cpp[NVC_ATL_COM#33](../../atl/codesnippet/cpp/ccomenum-class_2.h)] diff --git a/docs/atl/reference/ccomenumimpl-class.md b/docs/atl/reference/ccomenumimpl-class.md index 904acfd49b9..221edcb1d4a 100644 --- a/docs/atl/reference/ccomenumimpl-class.md +++ b/docs/atl/reference/ccomenumimpl-class.md @@ -4,10 +4,11 @@ title: "CComEnumImpl Class" ms.date: "11/04/2016" f1_keywords: ["CComEnumImpl", "ATLCOM/ATL::CComEnumImpl", "ATLCOM/ATL::CComEnumImpl::CComEnumImpl", "ATLCOM/ATL::CComEnumImpl::Clone", "ATLCOM/ATL::CComEnumImpl::Init", "ATLCOM/ATL::CComEnumImpl::Next", "ATLCOM/ATL::CComEnumImpl::Reset", "ATLCOM/ATL::CComEnumImpl::Skip", "ATLCOM/ATL::CComEnumImpl::m_begin", "ATLCOM/ATL::CComEnumImpl::m_dwFlags", "ATLCOM/ATL::CComEnumImpl::m_end", "ATLCOM/ATL::CComEnumImpl::m_iter", "ATLCOM/ATL::CComEnumImpl::m_spUnk"] helpviewer_keywords: ["CComEnumImpl class"] -ms.assetid: cc0d8e76-e608-46db-87cd-4c7161fe32d2 --- # CComEnumImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides the implementation for a COM enumerator interface where the items being enumerated are stored in an array. ## Syntax diff --git a/docs/atl/reference/ccomenumonstl-class.md b/docs/atl/reference/ccomenumonstl-class.md index c84d245c6b8..9d581e4f87c 100644 --- a/docs/atl/reference/ccomenumonstl-class.md +++ b/docs/atl/reference/ccomenumonstl-class.md @@ -4,10 +4,11 @@ title: "CComEnumOnSTL Class" ms.date: "11/04/2016" f1_keywords: ["CComEnumOnSTL", "atlcom/ATL::CComEnumOnSTL"] helpviewer_keywords: ["CComEnumOnSTL class"] -ms.assetid: befe1a44-7a00-4f28-9a2e-cc0fa526643c --- # CComEnumOnSTL Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class defines a COM enumerator object based on a C++ Standard Library collection. ## Syntax @@ -85,7 +86,7 @@ The code shown below provides a generic function to handle the creation and init [!code-cpp[NVC_ATL_COM#34](../../atl/codesnippet/cpp/ccomenumonstl-class_1.h)] -This template function can be used to implement the `_NewEnum` property of a collection interface as shown below: +This function template can be used to implement the `_NewEnum` property of a collection interface as shown below: [!code-cpp[NVC_ATL_COM#35](../../atl/codesnippet/cpp/ccomenumonstl-class_2.h)] diff --git a/docs/atl/reference/ccomfakecriticalsection-class.md b/docs/atl/reference/ccomfakecriticalsection-class.md index 087bc175ffb..9d146470b88 100644 --- a/docs/atl/reference/ccomfakecriticalsection-class.md +++ b/docs/atl/reference/ccomfakecriticalsection-class.md @@ -4,10 +4,11 @@ title: "CComFakeCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComFakeCriticalSection", "ATLCORE/ATL::CComFakeCriticalSection", "ATLCORE/ATL::CComFakeCriticalSection::Init", "ATLCORE/ATL::CComFakeCriticalSection::Lock", "ATLCORE/ATL::CComFakeCriticalSection::Term", "ATLCORE/ATL::CComFakeCriticalSection::Unlock"] helpviewer_keywords: ["CComFakeCriticalSection class"] -ms.assetid: a4811b97-96bb-493b-ab9f-62822aeddb10 --- # CComFakeCriticalSection Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides the same methods as [CComCriticalSection](../../atl/reference/ccomcriticalsection-class.md) but does not provide a critical section. ## Syntax diff --git a/docs/atl/reference/ccomgitptr-class.md b/docs/atl/reference/ccomgitptr-class.md index 1cc42d0b166..e2478fd7faf 100644 --- a/docs/atl/reference/ccomgitptr-class.md +++ b/docs/atl/reference/ccomgitptr-class.md @@ -4,10 +4,11 @@ title: "CComGITPtr Class" ms.date: "11/04/2016" f1_keywords: ["CComGITPtr", "ATLBASE/ATL::CComGITPtr", "ATLBASE/ATL::CComGITPtr::CComGITPtr", "ATLBASE/ATL::CComGITPtr::Attach", "ATLBASE/ATL::CComGITPtr::CopyTo", "ATLBASE/ATL::CComGITPtr::Detach", "ATLBASE/ATL::CComGITPtr::GetCookie", "ATLBASE/ATL::CComGITPtr::Revoke", "ATLBASE/ATL::CComGITPtr::m_dwCookie"] helpviewer_keywords: ["CComGITPtr class"] -ms.assetid: af895acb-525a-4555-bb67-b241b7df515b --- # CComGITPtr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for dealing with interface pointers and the global interface table (GIT). ## Syntax diff --git a/docs/atl/reference/ccomheap-class.md b/docs/atl/reference/ccomheap-class.md index f561ecf30de..f4446ee0ef4 100644 --- a/docs/atl/reference/ccomheap-class.md +++ b/docs/atl/reference/ccomheap-class.md @@ -4,10 +4,11 @@ title: "CComHeap Class" ms.date: "11/04/2016" f1_keywords: ["CComHeap", "ATLCOMMEM/ATL::CComHeap", "ATLCOMMEM/ATL::CComHeap::Allocate", "ATLCOMMEM/ATL::CComHeap::Free", "ATLCOMMEM/ATL::CComHeap::GetSize", "ATLCOMMEM/ATL::CComHeap::Reallocate"] helpviewer_keywords: ["CComHeap class"] -ms.assetid: c74183ce-98ae-46fb-b186-93ea4cf0222b --- # `CComHeap` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements [`IAtlMemMgr`](../../atl/reference/iatlmemmgr-class.md) using the COM memory allocation functions. > [!IMPORTANT] diff --git a/docs/atl/reference/ccomheapptr-class.md b/docs/atl/reference/ccomheapptr-class.md index 0edb83160e8..16767755ff6 100644 --- a/docs/atl/reference/ccomheapptr-class.md +++ b/docs/atl/reference/ccomheapptr-class.md @@ -4,10 +4,11 @@ title: "CComHeapPtr Class" ms.date: "11/04/2016" f1_keywords: ["CComHeapPtr", "ATLBASE/ATL::CComHeapPtr", "ATLBASE/ATL::CComHeapPtr::CComHeapPtr"] helpviewer_keywords: ["CComHeapPtr class"] -ms.assetid: bd08b53d-da2b-43ab-a79c-e7c8dbbc5994 --- # CComHeapPtr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + A smart pointer class for managing heap pointers. ## Syntax diff --git a/docs/atl/reference/ccommodule-class.md b/docs/atl/reference/ccommodule-class.md index eb17faf3c4e..0d8c58b4f6f 100644 --- a/docs/atl/reference/ccommodule-class.md +++ b/docs/atl/reference/ccommodule-class.md @@ -4,10 +4,11 @@ title: "CComModule Class" ms.date: "08/19/2019" f1_keywords: ["CComModule", "ATLBASE/ATL::CComModule", "ATLBASE/ATL::CComModule::GetClassObject", "ATLBASE/ATL::CComModule::GetModuleInstance", "ATLBASE/ATL::CComModule::GetResourceInstance", "ATLBASE/ATL::CComModule::GetTypeLibInstance", "ATLBASE/ATL::CComModule::Init", "ATLBASE/ATL::CComModule::RegisterClassHelper", "ATLBASE/ATL::CComModule::RegisterClassObjects", "ATLBASE/ATL::CComModule::RegisterServer", "ATLBASE/ATL::CComModule::RegisterTypeLib", "ATLBASE/ATL::CComModule::RevokeClassObjects", "ATLBASE/ATL::CComModule::Term", "ATLBASE/ATL::CComModule::UnregisterClassHelper", "ATLBASE/ATL::CComModule::UnregisterServer", "ATLBASE/ATL::CComModule::UpdateRegistryClass", "ATLBASE/ATL::CComModule::UpdateRegistryFromResourceD", "ATLBASE/ATL::CComModule::UpdateRegistryFromResourceS", "ATLBASE/ATL::CComModule::m_csObjMap", "ATLBASE/ATL::CComModule::m_csTypeInfoHolder", "ATLBASE/ATL::CComModule::m_csWindowCreate", "ATLBASE/ATL::CComModule::m_hInst", "ATLBASE/ATL::CComModule::m_hInstResource", "ATLBASE/ATL::CComModule::m_hInstTypeLib", "ATLBASE/ATL::CComModule::m_pObjMap"] helpviewer_keywords: ["CComModule class", "DLL modules [C++], ATL"] -ms.assetid: f5face2c-8fd8-40e6-9ec3-54ab74701769 --- # CComModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + As of ATL 7.0, `CComModule` is deprecated: see [ATL Module Classes](../../atl/atl-module-classes.md) for more details. > [!IMPORTANT] diff --git a/docs/atl/reference/ccommultithreadmodel-class.md b/docs/atl/reference/ccommultithreadmodel-class.md index 167fe9c3c73..56e99deb92b 100644 --- a/docs/atl/reference/ccommultithreadmodel-class.md +++ b/docs/atl/reference/ccommultithreadmodel-class.md @@ -1,18 +1,19 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + `CComMultiThreadModel` provides thread-safe methods for incrementing and decrementing the value of a variable. ## Syntax -``` +```cpp class CComMultiThreadModel ``` @@ -35,7 +36,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 +55,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 +121,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 +145,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 +166,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 +187,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 +209,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/ccommultithreadmodelnocs-class.md b/docs/atl/reference/ccommultithreadmodelnocs-class.md index 9a116848eab..b5af9c08403 100644 --- a/docs/atl/reference/ccommultithreadmodelnocs-class.md +++ b/docs/atl/reference/ccommultithreadmodelnocs-class.md @@ -4,10 +4,11 @@ title: "CComMultiThreadModelNoCS Class" ms.date: "11/04/2016" f1_keywords: ["CComMultiThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModelNoCS::AutoCriticalSection", "ATLBASE/ATL::CComMultiThreadModelNoCS::CriticalSection", "ATLBASE/ATL::CComMultiThreadModelNoCS::ThreadModelNoCS", "ATLBASE/ATL::CComMultiThreadModelNoCS::Decrement", "ATLBASE/ATL::CComMultiThreadModelNoCS::Increment"] helpviewer_keywords: ["ATL, multithreading", "CComMultiThreadModelNoCS class", "threading [ATL]"] -ms.assetid: 2b3f7a45-fd72-452c-aaf3-ccdaa621c821 --- # CComMultiThreadModelNoCS Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + `CComMultiThreadModelNoCS` provides thread-safe methods for incrementing and decrementing the value of a variable, without critical section locking or unlocking functionality. ## Syntax diff --git a/docs/atl/reference/ccomobject-class.md b/docs/atl/reference/ccomobject-class.md index 7c63e2eca1f..9e209ec6239 100644 --- a/docs/atl/reference/ccomobject-class.md +++ b/docs/atl/reference/ccomobject-class.md @@ -4,10 +4,11 @@ title: "CComObject Class" ms.date: "11/04/2016" f1_keywords: ["CComObject", "ATLCOM/ATL::CComObject", "ATLCOM/ATL::CComObject::CComObject", "ATLCOM/ATL::CComObject::AddRef", "ATLCOM/ATL::CComObject::CreateInstance", "ATLCOM/ATL::CComObject::QueryInterface", "ATLCOM/ATL::CComObject::Release"] helpviewer_keywords: ["CComObject class"] -ms.assetid: e2b6433b-6349-4749-b4bc-acbd7a22c8b0 --- # CComObject Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` for a nonaggregated object. ## Syntax @@ -125,7 +126,7 @@ If you do not need direct access to the object, but still want to create a new o ### Example [!code-cpp[NVC_ATL_COM#38](../../atl/codesnippet/cpp/ccomobject-class_1.h)] - +  [!code-cpp[NVC_ATL_COM#39](../../atl/codesnippet/cpp/ccomobject-class_2.cpp)] ## CComObject::QueryInterface diff --git a/docs/atl/reference/ccomobjectglobal-class.md b/docs/atl/reference/ccomobjectglobal-class.md index 14afcb2e9d4..345291d1d39 100644 --- a/docs/atl/reference/ccomobjectglobal-class.md +++ b/docs/atl/reference/ccomobjectglobal-class.md @@ -4,10 +4,11 @@ title: "CComObjectGlobal Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectGlobal", "ATLCOM/ATL::CComObjectGlobal", "ATLCOM/ATL::CComObjectGlobal::CComObjectGlobal", "ATLCOM/ATL::CComObjectGlobal::AddRef", "ATLCOM/ATL::CComObjectGlobal::QueryInterface", "ATLCOM/ATL::CComObjectGlobal::Release", "ATLCOM/ATL::CComObjectGlobal::m_hResFinalConstruct"] helpviewer_keywords: ["CComObjectGlobal class"] -ms.assetid: 79bdee55-66e4-4536-b5b3-bdf09f78b9a6 --- # CComObjectGlobal Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class manages a reference count on the module containing your `Base` object. ## Syntax diff --git a/docs/atl/reference/ccomobjectnolock-class.md b/docs/atl/reference/ccomobjectnolock-class.md index e98933f3641..91009986913 100644 --- a/docs/atl/reference/ccomobjectnolock-class.md +++ b/docs/atl/reference/ccomobjectnolock-class.md @@ -4,10 +4,11 @@ title: "CComObjectNoLock Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectNoLock", "ATLCOM/ATL::CComObjectNoLock", "ATLCOM/ATL::CComObjectNoLock::CComObjectNoLock", "ATLCOM/ATL::CComObjectNoLock::AddRef", "ATLCOM/ATL::CComObjectNoLock::QueryInterface", "ATLCOM/ATL::CComObjectNoLock::Release"] helpviewer_keywords: ["CComObjectNoLock class"] -ms.assetid: 288c6506-7da8-4127-8d58-7f4bd779539a --- # CComObjectNoLock Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` for a nonaggregated object, but does not increment the module lock count in the constructor. ## Syntax diff --git a/docs/atl/reference/ccomobjectroot-class.md b/docs/atl/reference/ccomobjectroot-class.md index 5a34267e8d9..e12f04a372f 100644 --- a/docs/atl/reference/ccomobjectroot-class.md +++ b/docs/atl/reference/ccomobjectroot-class.md @@ -4,10 +4,11 @@ title: "CComObjectRoot Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectRoot", "atlcom/ATL::CComObjectRoot"] helpviewer_keywords: ["CComObjectRoot class"] -ms.assetid: f8797c38-6e73-4f67-85c2-71654cffa8eb --- # CComObjectRoot Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This typedef of [CComObjectRootEx](../../atl/reference/ccomobjectrootex-class.md) is templatized on the default threading model of the server. ## Syntax diff --git a/docs/atl/reference/ccomobjectrootex-class.md b/docs/atl/reference/ccomobjectrootex-class.md index d28e79d4906..4b7181dd07d 100644 --- a/docs/atl/reference/ccomobjectrootex-class.md +++ b/docs/atl/reference/ccomobjectrootex-class.md @@ -4,10 +4,11 @@ title: "CComObjectRootEx Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectRootEx", "ATLCOM/ATL::CComObjectRootEx", "ATLCOM/ATL::InternalAddRef", "ATLCOM/ATL::InternalRelease", "ATLCOM/ATL::Lock", "ATLCOM/ATL::Unlock", "ATLCOM/ATL::FinalConstruct", "ATLCOM/ATL::FinalRelease", "ATLCOM/ATL::OuterAddRef", "ATLCOM/ATL::OuterQueryInterface", "ATLCOM/ATL::OuterRelease", "ATLCOM/ATL::InternalQueryInterface", "ATLCOM/ATL::ObjectMain", "ATLCOM/ATL::m_dwRef", "ATLCOM/ATL::m_pOuterUnknown"] helpviewer_keywords: ["reference counting"] -ms.assetid: 894a3d7c-2daf-4fd0-8fa4-e6a05bcfb631 --- # CComObjectRootEx Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods to handle object reference count management for both nonaggregated and aggregated objects. ## Syntax diff --git a/docs/atl/reference/ccomobjectstack-class.md b/docs/atl/reference/ccomobjectstack-class.md index 946beb5b66c..3e109aa93a3 100644 --- a/docs/atl/reference/ccomobjectstack-class.md +++ b/docs/atl/reference/ccomobjectstack-class.md @@ -4,10 +4,11 @@ title: "CComObjectStack Class" ms.date: "11/04/2016" f1_keywords: ["CComObjectStack", "ATLCOM/ATL::CComObjectStack", "ATLCOM/ATL::CComObjectStack::CComObjectStack", "ATLCOM/ATL::CComObjectStack::AddRef", "ATLCOM/ATL::CComObjectStack::QueryInterface", "ATLCOM/ATL::CComObjectStack::Release", "ATLCOM/ATL::CComObjectStack::m_hResFinalConstruct"] helpviewer_keywords: ["CComObjectStack class"] -ms.assetid: 3da72c40-c834-45f6-bb76-6ac204028d80 --- # CComObjectStack Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class creates a temporary COM object and provides it with a skeletal implementation of `IUnknown`. ## Syntax diff --git a/docs/atl/reference/ccompolyobject-class.md b/docs/atl/reference/ccompolyobject-class.md index d3632a52837..42991caee8d 100644 --- a/docs/atl/reference/ccompolyobject-class.md +++ b/docs/atl/reference/ccompolyobject-class.md @@ -4,10 +4,11 @@ title: "CComPolyObject Class" ms.date: "11/04/2016" f1_keywords: ["CComPolyObject", "ATLCOM/ATL::CComPolyObject", "ATLCOM/ATL::CComPolyObject::CComPolyObject", "ATLCOM/ATL::CComPolyObject::AddRef", "ATLCOM/ATL::CComPolyObject::CreateInstance", "ATLCOM/ATL::CComPolyObject::FinalConstruct", "ATLCOM/ATL::CComPolyObject::FinalRelease", "ATLCOM/ATL::CComPolyObject::QueryInterface", "ATLCOM/ATL::CComPolyObject::Release", "ATLCOM/ATL::CComPolyObject::m_contained"] helpviewer_keywords: ["aggregate objects [C++], in ATL", "aggregation [C++], ATL objects", "CComPolyObject class"] -ms.assetid: eaf67c18-e855-48ca-9b15-f1df3106121b --- # CComPolyObject Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` for an aggregated or nonaggregated object. ## Syntax diff --git a/docs/atl/reference/ccomptr-class.md b/docs/atl/reference/ccomptr-class.md index ab102f9213e..9be4578c843 100644 --- a/docs/atl/reference/ccomptr-class.md +++ b/docs/atl/reference/ccomptr-class.md @@ -4,10 +4,11 @@ description: "Reference guide to the Microsoft C++ Active Template Library (ATL) ms.date: "02/07/2020" f1_keywords: ["CComPtr", "ATLBASE/ATL::CComPtr", "ATLBASE/ATL::CComPtr::CComPtr"] helpviewer_keywords: ["CComPtr class"] -ms.assetid: 22d9ea8d-ed66-4c34-940f-141db11e83bd --- # `CComPtr` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + A smart pointer class for managing COM interface pointers. ## Syntax @@ -43,7 +44,7 @@ ATL uses `CComPtr` and [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) to The `CComPtr` and [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) classes can help eliminate memory leaks by performing automatic reference counting. The following functions both do the same logical operations. However, the second version may be less error-prone because it uses the `CComPtr` class: [!code-cpp[NVC_ATL_Utilities#130](../../atl/codesnippet/cpp/ccomptr-class_1.cpp)] - +  [!code-cpp[NVC_ATL_Utilities#131](../../atl/codesnippet/cpp/ccomptr-class_2.cpp)] In Debug builds, link atlsd.lib for code tracing. diff --git a/docs/atl/reference/ccomptrbase-class.md b/docs/atl/reference/ccomptrbase-class.md index c2363d848e2..c1653b2a447 100644 --- a/docs/atl/reference/ccomptrbase-class.md +++ b/docs/atl/reference/ccomptrbase-class.md @@ -4,10 +4,11 @@ title: "CComPtrBase Class" ms.date: "11/04/2016" f1_keywords: ["CComPtrBase", "ATLCOMCLI/ATL::CComPtrBase", "ATLCOMCLI/ATL::CComPtrBase::Advise", "ATLCOMCLI/ATL::CComPtrBase::Attach", "ATLCOMCLI/ATL::CComPtrBase::CoCreateInstance", "ATLCOMCLI/ATL::CComPtrBase::CopyTo", "ATLCOMCLI/ATL::CComPtrBase::Detach", "ATLCOMCLI/ATL::CComPtrBase::IsEqualObject", "ATLCOMCLI/ATL::CComPtrBase::QueryInterface", "ATLCOMCLI/ATL::CComPtrBase::Release", "ATLCOMCLI/ATL::CComPtrBase::SetSite", "ATLCOMCLI/ATL::CComPtrBase::p"] helpviewer_keywords: ["CComPtrBase class"] -ms.assetid: 6dbe9543-dee8-4a97-b02f-dd3a25f4a1a0 --- # `CComPtrBase` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a basis for smart pointer classes using COM-based memory routines. ## Syntax diff --git a/docs/atl/reference/ccomqiptr-class.md b/docs/atl/reference/ccomqiptr-class.md index 03490efe16e..23c87d54f7e 100644 --- a/docs/atl/reference/ccomqiptr-class.md +++ b/docs/atl/reference/ccomqiptr-class.md @@ -4,10 +4,11 @@ title: "CComQIPtr Class" ms.date: "11/04/2016" f1_keywords: ["CComQIPtr", "ATLCOMCLI/ATL::CComQIPtr", "ATLCOMCLI/ATL::CComQIPtr::CComQIPtr"] helpviewer_keywords: ["CComQIPtr class"] -ms.assetid: 969cacb5-05b6-4af4-b683-24911d70242d --- # CComQIPtr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + A smart pointer class for managing COM interface pointers. ## Syntax diff --git a/docs/atl/reference/ccomqiptrelementtraits-class.md b/docs/atl/reference/ccomqiptrelementtraits-class.md index c81c56e55e6..9d739a9404c 100644 --- a/docs/atl/reference/ccomqiptrelementtraits-class.md +++ b/docs/atl/reference/ccomqiptrelementtraits-class.md @@ -4,10 +4,11 @@ title: "CComQIPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CComQIPtrElementTraits", "ATLCOLL/ATL::CComQIPtrElementTraits", "ATLCOLL/ATL::CComQIPtrElementTraits::INARGTYPE"] helpviewer_keywords: ["CComQIPtrElementTraits class"] -ms.assetid: 9df9250a-5413-4362-b133-332932a597c4 --- # CComQIPtrElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods, static functions, and typedefs useful when creating collections of COM interface pointers. ## Syntax diff --git a/docs/atl/reference/ccomsafearray-class.md b/docs/atl/reference/ccomsafearray-class.md index a1f79d65d6c..e8b65490485 100644 --- a/docs/atl/reference/ccomsafearray-class.md +++ b/docs/atl/reference/ccomsafearray-class.md @@ -7,6 +7,8 @@ helpviewer_keywords: ["CComSafeArray class"] --- # `CComSafeArray` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for the `SAFEARRAY` structure. ## Syntax @@ -526,7 +528,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/ccomsafearraybound-class.md b/docs/atl/reference/ccomsafearraybound-class.md index fa65d7b399d..2d1ea111408 100644 --- a/docs/atl/reference/ccomsafearraybound-class.md +++ b/docs/atl/reference/ccomsafearraybound-class.md @@ -4,10 +4,11 @@ title: "CComSafeArrayBound Class" ms.date: "05/06/2019" f1_keywords: ["CComSafeArrayBound", "ATLSAFE/ATL::CComSafeArrayBound", "ATLSAFE/ATL::GetCount", "ATLSAFE/ATL::GetLowerBound", "ATLSAFE/ATL::GetUpperBound", "ATLSAFE/ATL::SetCount", "ATLSAFE/ATL::SetLowerBound"] helpviewer_keywords: ["CComSafeArrayBound class"] -ms.assetid: dd6299db-5f84-4630-bbf0-f5add5318437 --- # CComSafeArrayBound Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for a [SAFEARRAYBOUND](/windows/win32/api/oaidl/ns-oaidl-safearraybound) structure. ## Syntax diff --git a/docs/atl/reference/ccomsafedeletecriticalsection-class.md b/docs/atl/reference/ccomsafedeletecriticalsection-class.md index 1ece1377c38..c4e8ec088ea 100644 --- a/docs/atl/reference/ccomsafedeletecriticalsection-class.md +++ b/docs/atl/reference/ccomsafedeletecriticalsection-class.md @@ -4,10 +4,11 @@ title: "CComSafeDeleteCriticalSection Class" ms.date: "11/04/2016" f1_keywords: ["CComSafeDeleteCriticalSection", "ATLCORE/ATL::CComSafeDeleteCriticalSection", "ATLCORE/ATL::CComSafeDeleteCriticalSection::CComSafeDeleteCriticalSection", "ATLCORE/ATL::CComSafeDeleteCriticalSection::Init", "ATLCORE/ATL::CComSafeDeleteCriticalSection::Lock", "ATLCORE/ATL::CComSafeDeleteCriticalSection::Term", "ATLCORE/ATL::m_bInitialized"] helpviewer_keywords: ["CComSafeDeleteCriticalSection class"] -ms.assetid: 4d2932c4-ba8f-48ec-8664-1db8bed01314 --- # CComSafeDeleteCriticalSection Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for obtaining and releasing ownership of a critical section object. ## Syntax diff --git a/docs/atl/reference/ccomsimplethreadallocator-class.md b/docs/atl/reference/ccomsimplethreadallocator-class.md index 3ba04a9ad2d..1d3b4a19f4b 100644 --- a/docs/atl/reference/ccomsimplethreadallocator-class.md +++ b/docs/atl/reference/ccomsimplethreadallocator-class.md @@ -4,10 +4,11 @@ title: "CComSimpleThreadAllocator Class" ms.date: "11/04/2016" f1_keywords: ["CComSimpleThreadAllocator", "ATLBASE/ATL::CComSimpleThreadAllocator", "ATLBASE/ATL::CComSimpleThreadAllocator::GetThread"] helpviewer_keywords: ["threading [ATL], selecting threads", "ATL threads", "CComSimpleThreadAllocator class", "ATL threads, allocating"] -ms.assetid: 66b2166a-8c50-49fd-b8e4-7f293470327d --- # CComSimpleThreadAllocator Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class manages thread selection for the class `CComAutoThreadModule`. ## Syntax diff --git a/docs/atl/reference/ccomsinglethreadmodel-class.md b/docs/atl/reference/ccomsinglethreadmodel-class.md index 1fdb2f95db5..d81455f0ca3 100644 --- a/docs/atl/reference/ccomsinglethreadmodel-class.md +++ b/docs/atl/reference/ccomsinglethreadmodel-class.md @@ -4,10 +4,11 @@ title: "CComSingleThreadModel Class" ms.date: "2/29/2020" f1_keywords: ["CComSingleThreadModel", "ATLBASE/ATL::CComSingleThreadModel", "ATLBASE/ATL::CComSingleThreadModel::AutoCriticalSection", "ATLBASE/ATL::CComSingleThreadModel::CriticalSection", "ATLBASE/ATL::CComSingleThreadModel::ThreadModelNoCS", "ATLBASE/ATL::CComSingleThreadModel::Decrement", "ATLBASE/ATL::CComSingleThreadModel::Increment"] helpviewer_keywords: ["single-threaded applications", "CComSingleThreadModel class", "single-threaded applications, ATL"] -ms.assetid: e5dc30c7-405a-4ba4-8ae9-51937243fce8 --- # CComSingleThreadModel Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for incrementing and decrementing the value of a variable. ## Syntax diff --git a/docs/atl/reference/ccomtearoffobject-class.md b/docs/atl/reference/ccomtearoffobject-class.md index 42f6daf5171..a1813b71e2d 100644 --- a/docs/atl/reference/ccomtearoffobject-class.md +++ b/docs/atl/reference/ccomtearoffobject-class.md @@ -4,10 +4,11 @@ title: "CComTearOffObject Class" ms.date: "11/04/2016" f1_keywords: ["CComTearOffObject", "ATLCOM/ATL::CComTearOffObject", "ATLCOM/ATL::CComTearOffObject::CComTearOffObject", "ATLCOM/ATL::CComTearOffObject::AddRef", "ATLCOM/ATL::CComTearOffObject::QueryInterface", "ATLCOM/ATL::CComTearOffObject::Release", "ATLCOM/ATL::CComTearOffObjectBase", "ATLCOM/ATL::m_pOwner"] helpviewer_keywords: ["tear-off interfaces, ATL", "tear-off interfaces", "CComTearOffObject class"] -ms.assetid: d974b598-c6b2-42b1-8360-9190d9d0fbf3 --- # CComTearOffObject Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a tear-off interface. ## Syntax diff --git a/docs/atl/reference/ccomunkarray-class.md b/docs/atl/reference/ccomunkarray-class.md index dcdc5ecd76d..2232eea84ef 100644 --- a/docs/atl/reference/ccomunkarray-class.md +++ b/docs/atl/reference/ccomunkarray-class.md @@ -4,10 +4,11 @@ title: "CComUnkArray Class" ms.date: "11/04/2016" f1_keywords: ["CComUnkArray", "ATLCOM/ATL::CComUnkArray", "ATLCOM/ATL::CComUnkArray::CComUnkArray", "ATLCOM/ATL::CComUnkArray::Add", "ATLCOM/ATL::CComUnkArray::begin", "ATLCOM/ATL::CComUnkArray::end", "ATLCOM/ATL::CComUnkArray::GetCookie", "ATLCOM/ATL::CComUnkArray::GetUnknown", "ATLCOM/ATL::CComUnkArray::Remove"] helpviewer_keywords: ["connection points [C++], managing", "CComUnkArray class"] -ms.assetid: 5fd4b378-a7b5-4cc1-8866-8ab72a73639e --- # CComUnkArray Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class stores `IUnknown` pointers, and is designed to be used as a parameter to the [IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md) template class. ## Syntax diff --git a/docs/atl/reference/ccomvariant-class.md b/docs/atl/reference/ccomvariant-class.md index f53db737df1..b7387eaed95 100644 --- a/docs/atl/reference/ccomvariant-class.md +++ b/docs/atl/reference/ccomvariant-class.md @@ -7,6 +7,8 @@ helpviewer_keywords: ["VARIANT macro", "CComVariant class", "VARIANT macro, ATL" --- # `CComVariant` class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class wraps the `VARIANT` type, providing a member indicating the type of data stored. ## Syntax @@ -283,7 +285,7 @@ The size in bytes of the current contents of the `CComVariant` object. If the `VARIANT` contains an interface pointer, `GetSize` queries for `IPersistStream` or `IPersistStreamInit`. If successful, the return value is the low-order 32 bits of the value returned by `GetSizeMax` plus `sizeof(CLSID)` and `sizeof(VARTYPE)`. If the interface pointer is `NULL`, `GetSize` returns `sizeof(CLSID)` plus `sizeof(VARTYPE)`. If the total size is larger than `ULONG_MAX`, `GetSize` returns `sizeof(VARTYPE)`, which indicates an error. -In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the `NULL` character plus `sizeof(VARTYPE)`. If the `VARIANT` can’t be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. +In all other cases, a temporary `VARIANT` of type `VT_BSTR` is coerced from the current `VARIANT`. The length of this `BSTR` is calculated as the size of the length of the string plus the length of the string itself plus the size of the `NULL` character plus `sizeof(VARTYPE)`. If the `VARIANT` can't be coerced to a `VARIANT` of type `VT_BSTR`, `GetSize` returns `sizeof(VARTYPE)`. The size returned by this method matches the number of bytes used by [`CComVariant::WriteToStream`](#writetostream) under successful conditions. diff --git a/docs/atl/reference/ccontainedwindowt-class.md b/docs/atl/reference/ccontainedwindowt-class.md index 66ea867c296..a3bd317fda7 100644 --- a/docs/atl/reference/ccontainedwindowt-class.md +++ b/docs/atl/reference/ccontainedwindowt-class.md @@ -4,10 +4,11 @@ title: "CContainedWindowT Class" ms.date: "11/04/2016" f1_keywords: ["CContainedWindowT", "ATLWIN/ATL::CContainedWindowT", "ATLWIN/ATL::CContainedWindowT::CContainedWindowT", "ATLWIN/ATL::CContainedWindowT::Create", "ATLWIN/ATL::CContainedWindowT::DefWindowProc", "ATLWIN/ATL::CContainedWindowT::GetCurrentMessage", "ATLWIN/ATL::CContainedWindowT::RegisterWndSuperclass", "ATLWIN/ATL::CContainedWindowT::SubclassWindow", "ATLWIN/ATL::CContainedWindowT::SwitchMessageMap", "ATLWIN/ATL::CContainedWindowT::UnsubclassWindow", "ATLWIN/ATL::CContainedWindowT::WindowProc", "ATLWIN/ATL::CContainedWindowT::m_dwMsgMapID", "ATLWIN/ATL::CContainedWindowT::m_lpszClassName", "ATLWIN/ATL::CContainedWindowT::m_pfnSuperWindowProc", "ATLWIN/ATL::CContainedWindowT::m_pObject"] helpviewer_keywords: ["CContainedWindow class", "contained windows", "CContainedWindowT class"] -ms.assetid: cde0ca36-9347-4068-995a-d294dae57ca9 --- # CContainedWindowT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a window contained within another object. > [!IMPORTANT] @@ -75,9 +76,9 @@ A traits class that defines styles for your window. The default is `CControlWinT When you use the **Add control based on** option in the ATL Project Wizard, the wizard will automatically add a `CContainedWindowT` data member to the class implementing the control. The following example shows how the contained window is declared: [!code-cpp[NVC_ATL_Windowing#38](../../atl/codesnippet/cpp/ccontainedwindowt-class_1.h)] - +  [!code-cpp[NVC_ATL_Windowing#39](../../atl/codesnippet/cpp/ccontainedwindowt-class_2.h)] - +  [!code-cpp[NVC_ATL_Windowing#40](../../atl/codesnippet/cpp/ccontainedwindowt-class_3.h)] |For more information about|See| diff --git a/docs/atl/reference/ccrtallocator-class.md b/docs/atl/reference/ccrtallocator-class.md index 782c70f47f4..6df2c1e8ef6 100644 --- a/docs/atl/reference/ccrtallocator-class.md +++ b/docs/atl/reference/ccrtallocator-class.md @@ -4,10 +4,11 @@ title: "CCRTAllocator Class" ms.date: "11/04/2016" f1_keywords: ["CCRTAllocator", "ATLCORE/ATL::CCRTAllocator", "ATLCORE/ATL::CCRTAllocator::Allocate", "ATLCORE/ATL::CCRTAllocator::Free", "ATLCORE/ATL::CCRTAllocator::Reallocate"] helpviewer_keywords: ["CCRTAllocator class"] -ms.assetid: 3e1b8cb0-859a-41ab-8e93-6f0b5ceca49d --- # CCRTAllocator Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for managing memory using CRT memory routines. ## Syntax diff --git a/docs/atl/reference/ccrtheap-class.md b/docs/atl/reference/ccrtheap-class.md index 2c032d979d5..e1437bf729f 100644 --- a/docs/atl/reference/ccrtheap-class.md +++ b/docs/atl/reference/ccrtheap-class.md @@ -4,10 +4,11 @@ title: "CCRTHeap Class" ms.date: "11/04/2016" f1_keywords: ["CCRTHeap", "ATLMEM/ATL::CCRTHeap", "ATLMEM/ATL::CCRTHeap::Allocate", "ATLMEM/ATL::CCRTHeap::Free", "ATLMEM/ATL::CCRTHeap::GetSize", "ATLMEM/ATL::CCRTHeap::Reallocate"] helpviewer_keywords: ["CCRTHeap class"] -ms.assetid: 321bd6c5-1856-4ff7-8590-95044a1209f7 --- # CCRTHeap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the CRT heap functions. ## Syntax diff --git a/docs/atl/reference/cdacl-class.md b/docs/atl/reference/cdacl-class.md index dcd93c40d51..d3efde58ccc 100644 --- a/docs/atl/reference/cdacl-class.md +++ b/docs/atl/reference/cdacl-class.md @@ -4,10 +4,11 @@ title: "CDacl Class" ms.date: "11/04/2016" f1_keywords: ["CDacl", "ATLSECURITY/ATL::CDacl", "ATLSECURITY/ATL::CDacl::CDacl", "ATLSECURITY/ATL::CDacl::AddAllowedAce", "ATLSECURITY/ATL::CDacl::AddDeniedAce", "ATLSECURITY/ATL::CDacl::GetAceCount", "ATLSECURITY/ATL::CDacl::RemoveAce", "ATLSECURITY/ATL::CDacl::RemoveAllAces"] helpviewer_keywords: ["CDacl class"] -ms.assetid: 2dc76616-6362-4967-b6cf-e2d39ca37ddd --- # CDacl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for a DACL (discretionary access-control list) structure. > [!IMPORTANT] diff --git a/docs/atl/reference/cdebugreporthook-class.md b/docs/atl/reference/cdebugreporthook-class.md index a525a352572..5226a4b5a71 100644 --- a/docs/atl/reference/cdebugreporthook-class.md +++ b/docs/atl/reference/cdebugreporthook-class.md @@ -4,10 +4,11 @@ title: "CDebugReportHook Class" ms.date: "11/04/2016" f1_keywords: ["CDebugReportHook", "ATLUTIL/ATL::CDebugReportHook", "ATLUTIL/ATL::CDebugReportHook::CDebugReportHook", "ATLUTIL/ATL::CDebugReportHook::CDebugReportHookProc", "ATLUTIL/ATL::CDebugReportHook::RemoveHook", "ATLUTIL/ATL::CDebugReportHook::SetHook", "ATLUTIL/ATL::CDebugReportHook::SetPipeName", "ATLUTIL/ATL::CDebugReportHook::SetTimeout"] helpviewer_keywords: ["CDebugReportHook class"] -ms.assetid: 798076c3-6e63-4286-83b8-aa1bbcd0c20c --- # CDebugReportHook Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this class to send debug reports to a named pipe. ## Syntax diff --git a/docs/atl/reference/cdefaultchartraits-class.md b/docs/atl/reference/cdefaultchartraits-class.md index 6d941499c6e..af31367ac79 100644 --- a/docs/atl/reference/cdefaultchartraits-class.md +++ b/docs/atl/reference/cdefaultchartraits-class.md @@ -4,10 +4,11 @@ title: "CDefaultCharTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultCharTraits", "ATLCOLL/ATL::CDefaultCharTraits", "ATLCOLL/ATL::CDefaultCharTraits::CharToLower", "ATLCOLL/ATL::CDefaultCharTraits::CharToUpper"] helpviewer_keywords: ["CDefaultCharTraits class"] -ms.assetid: f94a3934-597f-401d-8513-ed6924ae069a --- # CDefaultCharTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides two static functions for converting characters between uppercase and lowercase. ## Syntax diff --git a/docs/atl/reference/cdefaultcomparetraits-class.md b/docs/atl/reference/cdefaultcomparetraits-class.md index ba680d50619..214e82b226e 100644 --- a/docs/atl/reference/cdefaultcomparetraits-class.md +++ b/docs/atl/reference/cdefaultcomparetraits-class.md @@ -4,10 +4,11 @@ title: "CDefaultCompareTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultCompareTraits", "ATLCOLL/ATL::CDefaultCompareTraits", "ATLCOLL/ATL::CDefaultCompareTraits::CompareElements", "ATLCOLL/ATL::CDefaultCompareTraits::CompareElementsOrdered"] helpviewer_keywords: ["CDefaultCompareTraits class"] -ms.assetid: a17e2740-e7b4-48f2-aeb7-c80ce84b63f7 --- # CDefaultCompareTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides default element comparison functions. ## Syntax diff --git a/docs/atl/reference/cdefaultelementtraits-class.md b/docs/atl/reference/cdefaultelementtraits-class.md index ee35bca2b36..7f33e07d8f3 100644 --- a/docs/atl/reference/cdefaultelementtraits-class.md +++ b/docs/atl/reference/cdefaultelementtraits-class.md @@ -4,10 +4,11 @@ title: "CDefaultElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultElementTraits", "atlcoll/ATL::CDefaultElementTraits"] helpviewer_keywords: ["CDefaultElementTraits class"] -ms.assetid: ac5ee610-7957-4b7c-92b6-38ff72e4118e --- # CDefaultElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides default methods and functions for a collection class. ## Syntax diff --git a/docs/atl/reference/cdefaulthashtraits-class.md b/docs/atl/reference/cdefaulthashtraits-class.md index 8c626840a95..562b6da25a7 100644 --- a/docs/atl/reference/cdefaulthashtraits-class.md +++ b/docs/atl/reference/cdefaulthashtraits-class.md @@ -4,10 +4,11 @@ title: "CDefaultHashTraits Class" ms.date: "11/04/2016" f1_keywords: ["CDefaultHashTraits", "ATLCOLL/ATL::CDefaultHashTraits", "ATLCOLL/ATL::CDefaultHashTraits::Hash"] helpviewer_keywords: ["CDefaultHashTraits class"] -ms.assetid: d8ec4b37-6d58-447b-a0c1-8580c5b1ab85 --- # CDefaultHashTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a static function for calculating hash values. ## Syntax diff --git a/docs/atl/reference/cdialogimpl-class.md b/docs/atl/reference/cdialogimpl-class.md index 56a1d4713c2..322ce2b5812 100644 --- a/docs/atl/reference/cdialogimpl-class.md +++ b/docs/atl/reference/cdialogimpl-class.md @@ -4,10 +4,11 @@ title: "CDialogImpl Class" ms.date: "11/04/2016" f1_keywords: ["CDialogImpl", "ATLWIN/ATL::CDialogImpl", "ATLWIN/ATL::Create", "ATLWIN/ATL::DestroyWindow", "ATLWIN/ATL::DoModal", "ATLWIN/ATL::EndDialog", "ATLWIN/ATL::GetDialogProc", "ATLWIN/ATL::MapDialogRect", "ATLWIN/ATL::OnFinalMessage", "ATLWIN/ATL::DialogProc", "ATLWIN/ATL::StartDialogProc"] helpviewer_keywords: ["dialog boxes, ATL", "CDialogImpl class"] -ms.assetid: d430bc7b-8a28-4ad3-9507-277bdd2c2c2e --- # CDialogImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating a modal or modeless dialog box. > [!IMPORTANT] diff --git a/docs/atl/reference/cdynamicchain-class.md b/docs/atl/reference/cdynamicchain-class.md index 27e0374b8f9..b3095ff263e 100644 --- a/docs/atl/reference/cdynamicchain-class.md +++ b/docs/atl/reference/cdynamicchain-class.md @@ -4,10 +4,11 @@ title: "CDynamicChain Class" ms.date: "11/04/2016" f1_keywords: ["CDynamicChain", "ATLWIN/ATL::CDynamicChain", "ATLWIN/ATL::CDynamicChain::CDynamicChain", "ATLWIN/ATL::CDynamicChain::CallChain", "ATLWIN/ATL::CDynamicChain::RemoveChainEntry", "ATLWIN/ATL::CDynamicChain::SetChainEntry"] helpviewer_keywords: ["message maps, chaining", "chaining message maps", "CDynamicChain class"] -ms.assetid: f084b2be-0e77-4836-973d-ae278a1e9da8 --- # CDynamicChain Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods supporting the dynamic chaining of message maps. > [!IMPORTANT] diff --git a/docs/atl/reference/celementtraits-class.md b/docs/atl/reference/celementtraits-class.md index 067c69927e0..69ba5045e2b 100644 --- a/docs/atl/reference/celementtraits-class.md +++ b/docs/atl/reference/celementtraits-class.md @@ -4,10 +4,11 @@ title: "CElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CElementTraits", "atlcoll/ATL::CElementTraits"] helpviewer_keywords: ["CElementTraits class"] -ms.assetid: 496528e5-7f80-4b45-be0c-6f646feb43c5 --- # CElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is used by collection classes to provide methods and functions for moving, copying, comparison, and hashing operations. ## Syntax diff --git a/docs/atl/reference/celementtraitsbase-class.md b/docs/atl/reference/celementtraitsbase-class.md index 8bf122174c6..569f754e6b2 100644 --- a/docs/atl/reference/celementtraitsbase-class.md +++ b/docs/atl/reference/celementtraitsbase-class.md @@ -4,10 +4,11 @@ title: "CElementTraitsBase Class" ms.date: "11/04/2016" f1_keywords: ["CElementTraitsBase", "ATLCOLL/ATL::CElementTraitsBase", "ATLCOLL/ATL::CElementTraitsBase::INARGTYPE", "ATLCOLL/ATL::CElementTraitsBase::OUTARGTYPE", "ATLCOLL/ATL::CElementTraitsBase::CopyElements", "ATLCOLL/ATL::CElementTraitsBase::RelocateElements"] helpviewer_keywords: ["CElementTraitsBase class"] -ms.assetid: 75284caf-347e-4355-a7d8-efc708dd514a --- # CElementTraitsBase Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides default copy and move methods for a collection class. ## Syntax diff --git a/docs/atl/reference/cfirepropnotifyevent-class.md b/docs/atl/reference/cfirepropnotifyevent-class.md index 76834b9a5ed..a9058036f19 100644 --- a/docs/atl/reference/cfirepropnotifyevent-class.md +++ b/docs/atl/reference/cfirepropnotifyevent-class.md @@ -4,10 +4,11 @@ title: "CFirePropNotifyEvent Class" ms.date: "11/04/2016" f1_keywords: ["CFirePropNotifyEvent", "ATLCTL/ATL::CFirePropNotifyEvent", "ATLCTL/ATL::CFirePropNotifyEvent::FireOnChanged", "ATLCTL/ATL::CFirePropNotifyEvent::FireOnRequestEdit"] helpviewer_keywords: ["sinks, notifying of ATL events", "CFirePropNotifyEvent class", "connection points [C++], notifying of events"] -ms.assetid: eb7a563e-6bce-4cdf-8d20-8c6a5307781b --- # CFirePropNotifyEvent Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for notifying the container's sink regarding control property changes. > [!IMPORTANT] diff --git a/docs/atl/reference/cglobalheap-class.md b/docs/atl/reference/cglobalheap-class.md index 426101159d7..38fe72d252b 100644 --- a/docs/atl/reference/cglobalheap-class.md +++ b/docs/atl/reference/cglobalheap-class.md @@ -4,10 +4,11 @@ title: "CGlobalHeap Class" ms.date: "11/04/2016" f1_keywords: ["CGlobalHeap", "ATLMEM/ATL::CGlobalHeap", "ATLMEM/ATL::CGlobalHeap::Allocate", "ATLMEM/ATL::CGlobalHeap::Free", "ATLMEM/ATL::CGlobalHeap::GetSize", "ATLMEM/ATL::CGlobalHeap::Reallocate"] helpviewer_keywords: ["CGlobalHeap class"] -ms.assetid: e348d838-3aa7-4bee-a1b3-cd000c99f834 --- # CGlobalHeap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 global heap functions. > [!IMPORTANT] diff --git a/docs/atl/reference/chandle-class.md b/docs/atl/reference/chandle-class.md index 237fa0cd883..54f0095d210 100644 --- a/docs/atl/reference/chandle-class.md +++ b/docs/atl/reference/chandle-class.md @@ -4,10 +4,11 @@ title: "CHandle Class" ms.date: "07/09/2019" f1_keywords: ["CHandle", "ATLBASE/ATL::CHandle", "ATLBASE/ATL::CHandle::CHandle", "ATLBASE/ATL::CHandle::Attach", "ATLBASE/ATL::CHandle::Close", "ATLBASE/ATL::CHandle::Detach", "ATLBASE/ATL::CHandle::m_h"] helpviewer_keywords: ["CHandle class"] -ms.assetid: 883e9db5-40ec-4e29-9c74-4dd2ddd2e35d --- # CHandle Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating and using a handle object. ## Syntax diff --git a/docs/atl/reference/cheapptr-class.md b/docs/atl/reference/cheapptr-class.md index c7888bfbccd..53580613dcc 100644 --- a/docs/atl/reference/cheapptr-class.md +++ b/docs/atl/reference/cheapptr-class.md @@ -4,10 +4,11 @@ title: "CHeapPtr Class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtr", "ATLCORE/ATL::CHeapPtr", "ATLCORE/ATL::CHeapPtr::CHeapPtr", "ATLCORE/ATL::CHeapPtr::Allocate", "ATLCORE/ATL::CHeapPtr::Reallocate"] helpviewer_keywords: ["CHeapPtr class"] -ms.assetid: e5c5bfd4-9bf1-4164-8a83-8155fe253454 --- # CHeapPtr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + A smart pointer class for managing heap pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/cheapptrbase-class.md b/docs/atl/reference/cheapptrbase-class.md index 8ba15f0fb65..a756cc99bc3 100644 --- a/docs/atl/reference/cheapptrbase-class.md +++ b/docs/atl/reference/cheapptrbase-class.md @@ -4,10 +4,11 @@ title: "CHeapPtrBase class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtrBase", "ATLCORE/ATL::CHeapPtrBase", "ATLCORE/ATL::CHeapPtrBase::AllocateBytes", "ATLCORE/ATL::CHeapPtrBase::Attach", "ATLCORE/ATL::CHeapPtrBase::Detach", "ATLCORE/ATL::CHeapPtrBase::Free", "ATLCORE/ATL::CHeapPtrBase::ReallocateBytes", "ATLCORE/ATL::CHeapPtrBase::m_pData"] helpviewer_keywords: ["CHeapPtrBase class"] -ms.assetid: 501ac1b2-fb34-4c72-b7e6-a4f1fc8fda21 --- # `CHeapPtrBase` class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class forms the basis for several smart heap pointer classes. > [!IMPORTANT] diff --git a/docs/atl/reference/cheapptrelementtraits-class.md b/docs/atl/reference/cheapptrelementtraits-class.md index 3ff0b3f44d1..5fb6c021ad1 100644 --- a/docs/atl/reference/cheapptrelementtraits-class.md +++ b/docs/atl/reference/cheapptrelementtraits-class.md @@ -4,10 +4,11 @@ title: "CHeapPtrElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtrElementTraits", "ATLCOLL/ATL::CHeapPtrElementTraits", "ATLCOLL/ATL::CHeapPtrElementTraits::INARGTYPE", "ATLCOLL/ATL::CHeapPtrElementTraits::OUTARGTYPE"] helpviewer_keywords: ["CHeapPtrElementTraits class"] -ms.assetid: 910e0e06-3c8b-4242-bf00-b57eb74fbc77 --- # CHeapPtrElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods, static functions, and typedefs useful when creating collections of heap pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/cheapptrlist-class.md b/docs/atl/reference/cheapptrlist-class.md index 591c5787727..4513428fcb8 100644 --- a/docs/atl/reference/cheapptrlist-class.md +++ b/docs/atl/reference/cheapptrlist-class.md @@ -4,10 +4,11 @@ title: "CHeapPtrList Class" ms.date: "11/04/2016" f1_keywords: ["CHeapPtrList", "ATLCOLL/ATL::CHeapPtrList", "ATLCOLL/ATL::CHeapPtrList::CHeapPtrList"] helpviewer_keywords: ["CHeapPtrList class"] -ms.assetid: cc70e585-362a-4007-81db-c705eb181226 --- # CHeapPtrList Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods useful when constructing a list of heap pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/cinterfacearray-class.md b/docs/atl/reference/cinterfacearray-class.md index 3a6ec0bc1df..d7c378a72a9 100644 --- a/docs/atl/reference/cinterfacearray-class.md +++ b/docs/atl/reference/cinterfacearray-class.md @@ -4,10 +4,11 @@ title: "CInterfaceArray Class" ms.date: "11/04/2016" f1_keywords: ["CInterfaceArray", "ATLCOLL/ATL::CInterfaceArray", "ATLCOLL/ATL::CInterfaceArray::CInterfaceArray"] helpviewer_keywords: ["CInterfaceArray class"] -ms.assetid: 1f29cf66-a086-4a7b-b6a8-64f73da39f79 --- # CInterfaceArray Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods useful when constructing an array of COM interface pointers. ## Syntax diff --git a/docs/atl/reference/cinterfacelist-class.md b/docs/atl/reference/cinterfacelist-class.md index e5aae7bdce7..f445de12465 100644 --- a/docs/atl/reference/cinterfacelist-class.md +++ b/docs/atl/reference/cinterfacelist-class.md @@ -4,10 +4,11 @@ title: "CInterfaceList Class" ms.date: "11/04/2016" f1_keywords: ["CInterfaceList", "ATLCOLL/ATL::CInterfaceList", "ATLCOLL/ATL::CInterfaceList::CInterfaceList"] helpviewer_keywords: ["CInterfaceList class"] -ms.assetid: 2077764d-25e5-4b3d-96c8-08a287bbcd25 --- # CInterfaceList Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods useful when constructing a list of COM interface pointers. ## Syntax diff --git a/docs/atl/reference/clocalheap-class.md b/docs/atl/reference/clocalheap-class.md index 32ff5c199e4..9d597b0d29c 100644 --- a/docs/atl/reference/clocalheap-class.md +++ b/docs/atl/reference/clocalheap-class.md @@ -4,10 +4,11 @@ title: "CLocalHeap Class" ms.date: "11/04/2016" f1_keywords: ["CLocalHeap", "ATLMEM/ATL::CLocalHeap", "ATLMEM/ATL::CLocalHeap::Allocate", "ATLMEM/ATL::CLocalHeap::Free", "ATLMEM/ATL::CLocalHeap::GetSize", "ATLMEM/ATL::CLocalHeap::Reallocate"] helpviewer_keywords: ["CLocalHeap class"] -ms.assetid: 1ffa87a5-5fc8-4f8d-8809-58e87e963bd2 --- # CLocalHeap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 local heap functions. > [!IMPORTANT] diff --git a/docs/atl/reference/cmessagemap-class.md b/docs/atl/reference/cmessagemap-class.md index 1f8f30e7429..3e9c87e6d8e 100644 --- a/docs/atl/reference/cmessagemap-class.md +++ b/docs/atl/reference/cmessagemap-class.md @@ -4,10 +4,11 @@ title: "CMessageMap Class" ms.date: "11/04/2016" f1_keywords: ["CMessageMap", "ATLWIN/ATL::CMessageMap", "ATLWIN/ATL::CMessageMap::ProcessWindowMessage"] helpviewer_keywords: ["CMessageMap class", "message maps, ATL", "ATL, message handlers"] -ms.assetid: 1f97bc16-a8a0-4cf0-b90f-1778813a5c8e --- # CMessageMap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class allows an object's message maps to be access by another object. > [!IMPORTANT] diff --git a/docs/atl/reference/cnonstatelessworker-class.md b/docs/atl/reference/cnonstatelessworker-class.md index 014cd170ab8..c11f44e5cf6 100644 --- a/docs/atl/reference/cnonstatelessworker-class.md +++ b/docs/atl/reference/cnonstatelessworker-class.md @@ -4,10 +4,11 @@ title: "CNonStatelessWorker Class" ms.date: "11/04/2016" f1_keywords: ["CNonStatelessWorker", "ATLUTIL/ATL::CNonStatelessWorker", "ATLUTIL/ATL::CNonStatelessWorker::RequestType", "ATLUTIL/ATL::CNonStatelessWorker::Execute", "ATLUTIL/ATL::CNonStatelessWorker::Initialize", "ATLUTIL/ATL::CNonStatelessWorker::Terminate"] helpviewer_keywords: ["CNonStatelessWorker class"] -ms.assetid: d00936c6-9e7d-49fb-b87d-417b963367d1 --- # CNonStatelessWorker Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Receives requests from a thread pool and passes them on to a worker object that is created and destroyed on each request. > [!IMPORTANT] diff --git a/docs/atl/reference/cnoworkerthread-class.md b/docs/atl/reference/cnoworkerthread-class.md index 69c725ddc5e..a46f79dd47f 100644 --- a/docs/atl/reference/cnoworkerthread-class.md +++ b/docs/atl/reference/cnoworkerthread-class.md @@ -4,10 +4,11 @@ title: "CNoWorkerThread Class" ms.date: "11/04/2016" f1_keywords: ["CNoWorkerThread", "ATLUTIL/ATL::CNoWorkerThread", "ATLUTIL/ATL::CNoWorkerThread::AddHandle", "ATLUTIL/ATL::CNoWorkerThread::AddTimer", "ATLUTIL/ATL::CNoWorkerThread::GetThreadHandle", "ATLUTIL/ATL::CNoWorkerThread::GetThreadId", "ATLUTIL/ATL::CNoWorkerThread::Initialize", "ATLUTIL/ATL::CNoWorkerThread::RemoveHandle", "ATLUTIL/ATL::CNoWorkerThread::Shutdown"] helpviewer_keywords: ["CNoWorkerThread class"] -ms.assetid: 29f06bae-b658-4aac-9c14-331e996d25d1 --- # CNoWorkerThread Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this class as the argument for the `MonitorClass` template parameter to cache classes if you want to disable dynamic cache maintenance. > [!IMPORTANT] diff --git a/docs/atl/reference/com-interface-entry-macros.md b/docs/atl/reference/com-interface-entry-macros.md index 83a187ec491..dd365f7d09d 100644 --- a/docs/atl/reference/com-interface-entry-macros.md +++ b/docs/atl/reference/com-interface-entry-macros.md @@ -4,10 +4,11 @@ title: "COM Interface Entry Macros" ms.date: "03/28/2017" f1_keywords: ["atlcom/ATL::COM_INTERFACE_ENTRY", "atlcom/ATL::COM_INTERFACE_ENTRY_IID", "atlcom/ATL::COM_INTERFACE_ENTRY_AGGREGATE", "atlcom/ATL::COM_INTERFACE_ENTRY_AGGREGATE_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_AUTOAGGREGATE", "atlcom/ATL::COM_INTERFACE_ENTRY_AUTOAGGREGATE_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_BREAK", "atlcom/ATL::COM_INTERFACE_ENTRY_CACHED_TEAR_OFF", "atlcom/ATL::COM_INTERFACE_ENTRY_TEAR_OFF", "atlcom/ATL::COM_INTERFACE_ENTRY_CHAIN", "atlcom/ATL::COM_INTERFACE_ENTRY_FUNC", "atlcom/ATL::COM_INTERFACE_ENTRY_FUNC_BLIND", "atlcom/ATL::COM_INTERFACE_ENTRY_NOINTERFACE"] helpviewer_keywords: ["COM interfaces, COM interface entry macros"] -ms.assetid: 19dcb768-2e1f-4b8d-a618-453a01a4bd00 --- # COM_INTERFACE_ENTRY Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros enter an object's interfaces into its COM map so that they can be accessed by `QueryInterface`. The order of entries in the COM map is the order interfaces will be checked for a matching IID during `QueryInterface`. |Macro|Description| diff --git a/docs/atl/reference/com-map-global-functions.md b/docs/atl/reference/com-map-global-functions.md index 97e19802646..e7ebb9ed76d 100644 --- a/docs/atl/reference/com-map-global-functions.md +++ b/docs/atl/reference/com-map-global-functions.md @@ -4,10 +4,11 @@ title: "COM Map Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlInternalQueryInterface", "atlbase/ATL::InlineIsEqualIUnknown"] helpviewer_keywords: ["COM interfaces, COM map global functions"] -ms.assetid: b9612d30-eb23-46ef-8093-d56f237d3cf1 --- # COM Map Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for COM Map `IUnknown` implementations. |Function|Description| diff --git a/docs/atl/reference/com-map-macros.md b/docs/atl/reference/com-map-macros.md index 6734604721d..93d4b26bb69 100644 --- a/docs/atl/reference/com-map-macros.md +++ b/docs/atl/reference/com-map-macros.md @@ -4,10 +4,11 @@ title: "COM Map Macros" ms.date: "11/04/2016" f1_keywords: ["atlcom/ATL::BEGIN_COM_MAP", "atlcom/ATL::END_COM_MAP", "ATLCOM/BEGIN_COM_MAP", "ATLCOM/END_COM_MAP"] helpviewer_keywords: ["COM interfaces, COM map macros"] -ms.assetid: 0f33656d-321f-4996-90cc-9a7f21ab73c3 --- # COM Map Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define COM interface maps. |Macro|Description| diff --git a/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md b/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md index 0a125245518..37826eba5b2 100644 --- a/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md +++ b/docs/atl/reference/com-plus-1-0-atl-com-plus-1-0-component-wizard.md @@ -3,10 +3,11 @@ description: "Learn more about: COM+ 1.0, ATL COM+ 1.0 Component Wizard" title: "COM+ 1.0, ATL COM+ 1.0 Component Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.mts.options"] -ms.assetid: 2fbe259c-6be1-4d0e-9cfe-721c75c97cb1 --- # COM+ 1.0, ATL COM+ 1.0 Component Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md b/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md index ae0f296311b..72d9e7e0ff7 100644 --- a/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md +++ b/docs/atl/reference/com-plus-1-0-support-in-atl-projects.md @@ -4,10 +4,11 @@ title: "COM+ 1.0 Support in ATL Projects" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.ATL.MTS"] helpviewer_keywords: ["ATL projects, COM+ 1.0 support"] -ms.assetid: 51fb08ac-d632-4657-a4e0-d3f989f0b6f8 --- # COM+ 1.0 Support in ATL Projects +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + You can use the [ATL Project Wizard](../../atl/reference/creating-an-atl-project.md) to create a project with basic support for COM+ 1.0 components. COM+ 1.0 is designed for developing distributed component-based applications. It also provides a run-time infrastructure for deploying and managing these applications. diff --git a/docs/atl/reference/compiler-options-macros.md b/docs/atl/reference/compiler-options-macros.md index b88df25cda7..465fd84fab8 100644 --- a/docs/atl/reference/compiler-options-macros.md +++ b/docs/atl/reference/compiler-options-macros.md @@ -1,34 +1,36 @@ --- 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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + 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 +54,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 +62,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 +74,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 +100,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 +112,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 +124,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 +142,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 +154,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 +164,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 +174,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 +194,14 @@ A symbol that indicates a function shouldn't be inlined. ### Parameters -*myfunction*
-The function that should not be inlined. +*`myfunction`*\ +The function that shouldn't be inlined. ### Remarks -Use this symbol if you want to ensure a function does not get inlined by the compiler, even though it must be declared as inline so that it can be placed in a header file. Expands to **`__declspec(noinline)`**. +Use this symbol if you want to ensure a function doesn't get inlined by the compiler, even though it must be declared as inline so that it can be placed in a header file. Expands to `__declspec(noinline)`. -## _ATL_SINGLE_THREADED +## `_ATL_SINGLE_THREADED` Define if all of your objects use the single threading model diff --git a/docs/atl/reference/composite-control-global-functions.md b/docs/atl/reference/composite-control-global-functions.md index b55042bb271..b14dc283be1 100644 --- a/docs/atl/reference/composite-control-global-functions.md +++ b/docs/atl/reference/composite-control-global-functions.md @@ -4,10 +4,11 @@ title: "Composite Control Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlhost/ATL::AtlAxDialogBox", "atlhost/ATL::AtlAxCreateDialog", "atlhost/ATL::AtlAxCreateControl", "atlhost/ATL::AtlAxCreateControlEx", "atlhost/ATL::AtlAxCreateControlLic", "atlhost/ATL::AtlAxCreateControlLicEx", "atlhost/ATL::AtlAxAttachControl", "atlhost/ATL::AtlAxGetHost", "atlhost/ATL::AtlAxGetControl", "atlhost/ATL::AtlSetChildSite", "atlhost/ATL::AtlAxWinInit", "atlhost/ATL::AtlAxWinTerm", "atlhost/ATL::AtlGetObjectSourceInterface"] helpviewer_keywords: ["composite controls, global functions"] -ms.assetid: 536884cd-e863-4c7a-ab0a-604dc60a0bbe --- # Composite Control Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for creating dialog boxes, and for creating, hosting and licensing ActiveX controls. > [!IMPORTANT] diff --git a/docs/atl/reference/composite-control-macros.md b/docs/atl/reference/composite-control-macros.md index 9721f16031c..94620901dbc 100644 --- a/docs/atl/reference/composite-control-macros.md +++ b/docs/atl/reference/composite-control-macros.md @@ -4,10 +4,11 @@ title: "Composite Control Macros" ms.date: "05/06/2019" f1_keywords: ["atlcom/ATL::BEGIN_SINK_MAP", "atlcom/ATL::END_SINK_MAP", "atlcom/ATL::SINK_ENTRY", "ATLCOM/BEGIN_SINK_MAP", "ATLCOM/END_SINK_MAP", "ATLCOM/SINK_ENTRY", "ATLCOM/SINK_ENTRY_EX", "ATLCOM/SINK_ENTRY_EX_P", "ATLCOM/SINK_ENTRY_INFO", "ATLCOM/SINK_ENTRY_INFO_P", "BEGIN_SINK_MAP", "END_SINK_MAP", "SINK_ENTRY", "SINK_ENTRY_EX", "SINK_ENTRY_EX_P", "SINK_ENTRY_INFO", "SINK_ENTRY_INFO_P"] helpviewer_keywords: ["composite controls, macros"] -ms.assetid: 17f2dd5e-07e6-4aa6-b965-7a361c78c45e --- # Composite Control Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define event sink maps and entries. |Macro|Description| diff --git a/docs/atl/reference/connection-point-global-functions.md b/docs/atl/reference/connection-point-global-functions.md index be49a8643a4..27a14e4ca41 100644 --- a/docs/atl/reference/connection-point-global-functions.md +++ b/docs/atl/reference/connection-point-global-functions.md @@ -4,10 +4,11 @@ title: "Connection Point Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlAdvise", "atlbase/ATL::AtlUnadvise", "atlbase/ATL::AtlAdviseSinkMap"] helpviewer_keywords: ["connection points [C++], global functions"] -ms.assetid: bcb4bf50-2155-4e20-b8bb-f2908b03a6e7 --- # Connection Point Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for connection points and sink maps. > [!IMPORTANT] diff --git a/docs/atl/reference/connection-point-macros.md b/docs/atl/reference/connection-point-macros.md index 490abb2c387..5bdfd5b0491 100644 --- a/docs/atl/reference/connection-point-macros.md +++ b/docs/atl/reference/connection-point-macros.md @@ -4,10 +4,11 @@ title: "Connection Point Macros" ms.date: "11/04/2016" f1_keywords: ["atlcom/ATL::BEGIN_CONNECTION_POINT_MAP", "atlcom/ATL::END_CONNECTION_POINT_MAP", "ATLCOM/BEGIN_CONNECTION_POINT_MAP", "ATLCOM/END_CONNECTION_POINT_MAP", "ATLCOM/CONNECTION_POINT_ENTRY", "ATLCOM/CONNECTION_POINT_ENTRY_P", "BEGIN_CONNECTION_POINT_MAP", "END_CONNECTION_POINT_MAP", "CONNECTION_POINT_ENTRY", "CONNECTION_POINT_ENTRY_P"] helpviewer_keywords: ["connection points [C++], macros"] -ms.assetid: cc3a6dd3-5538-45df-b027-1f34963c31e5 --- # Connection Point Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define connection point maps and entries. |Macro|Description| diff --git a/docs/atl/reference/cpatht-class.md b/docs/atl/reference/cpatht-class.md index 32b31a3db12..93adf44cd29 100644 --- a/docs/atl/reference/cpatht-class.md +++ b/docs/atl/reference/cpatht-class.md @@ -4,10 +4,11 @@ title: "CPathT Class" ms.date: "03/27/2019" f1_keywords: ["CPathT", "ATLPATH/ATL::CPathT", "ATLPATH/ATL::CPathT::PCXSTR", "ATLPATH/ATL::CPathT::PXSTR", "ATLPATH/ATL::CPathT::XCHAR", "ATLPATH/ATL::CPathT::CPathT", "ATLPATH/ATL::CPathT::AddBackslash", "ATLPATH/ATL::CPathT::AddExtension", "ATLPATH/ATL::CPathT::Append", "ATLPATH/ATL::CPathT::BuildRoot", "ATLPATH/ATL::CPathT::Canonicalize", "ATLPATH/ATL::CPathT::Combine", "ATLPATH/ATL::CPathT::CommonPrefix", "ATLPATH/ATL::CPathT::CompactPath", "ATLPATH/ATL::CPathT::CompactPathEx", "ATLPATH/ATL::CPathT::FileExists", "ATLPATH/ATL::CPathT::FindExtension", "ATLPATH/ATL::CPathT::FindFileName", "ATLPATH/ATL::CPathT::GetDriveNumber", "ATLPATH/ATL::CPathT::GetExtension", "ATLPATH/ATL::CPathT::IsDirectory", "ATLPATH/ATL::CPathT::IsFileSpec", "ATLPATH/ATL::CPathT::IsPrefix", "ATLPATH/ATL::CPathT::IsRelative", "ATLPATH/ATL::CPathT::IsRoot", "ATLPATH/ATL::CPathT::IsSameRoot", "ATLPATH/ATL::CPathT::IsUNC", "ATLPATH/ATL::CPathT::IsUNCServer", "ATLPATH/ATL::CPathT::IsUNCServerShare", "ATLPATH/ATL::CPathT::MakePretty", "ATLPATH/ATL::CPathT::MatchSpec", "ATLPATH/ATL::CPathT::QuoteSpaces", "ATLPATH/ATL::CPathT::RelativePathTo", "ATLPATH/ATL::CPathT::RemoveArgs", "ATLPATH/ATL::CPathT::RemoveBackslash", "ATLPATH/ATL::CPathT::RemoveBlanks", "ATLPATH/ATL::CPathT::RemoveExtension", "ATLPATH/ATL::CPathT::RemoveFileSpec", "ATLPATH/ATL::CPathT::RenameExtension", "ATLPATH/ATL::CPathT::SkipRoot", "ATLPATH/ATL::CPathT::StripPath", "ATLPATH/ATL::CPathT::StripToRoot", "ATLPATH/ATL::CPathT::UnquoteSpaces", "ATLPATH/ATL::CPathT::m_strPath"] helpviewer_keywords: ["CPathT class"] -ms.assetid: eba4137d-1fd2-4b44-a2e1-0944db64df3c --- # CPathT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a path. > [!IMPORTANT] diff --git a/docs/atl/reference/cprimitiveelementtraits-class.md b/docs/atl/reference/cprimitiveelementtraits-class.md index 7a0da283d47..efbb2c1caff 100644 --- a/docs/atl/reference/cprimitiveelementtraits-class.md +++ b/docs/atl/reference/cprimitiveelementtraits-class.md @@ -4,10 +4,11 @@ title: "CPrimitiveElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CPrimitiveElementTraits", "ATLCOLL/ATL::CPrimitiveElementTraits", "ATLCOLL/ATL::CPrimitiveElementTraits::INARGTYPE", "ATLCOLL/ATL::CPrimitiveElementTraits::OUTARGTYPE"] helpviewer_keywords: ["CPrimitiveElementTraits class"] -ms.assetid: 21c1cea8-2c5a-486c-b65c-85490f3ed4e6 --- # CPrimitiveElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides default methods and functions for a collection class composed of primitive data types. ## Syntax diff --git a/docs/atl/reference/cprivateobjectsecuritydesc-class.md b/docs/atl/reference/cprivateobjectsecuritydesc-class.md index 8d18a4cef84..b3e8123fd32 100644 --- a/docs/atl/reference/cprivateobjectsecuritydesc-class.md +++ b/docs/atl/reference/cprivateobjectsecuritydesc-class.md @@ -4,10 +4,11 @@ title: "CPrivateObjectSecurityDesc Class" ms.date: "11/04/2016" f1_keywords: ["CPrivateObjectSecurityDesc", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::CPrivateObjectSecurityDesc", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::ConvertToAutoInherit", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::Create", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::Get", "ATLSECURITY/ATL::CPrivateObjectSecurityDesc::Set"] helpviewer_keywords: ["CPrivateObjectSecurityDesc class"] -ms.assetid: 2c4bbb13-bf99-4833-912a-197f6815bb5d --- # CPrivateObjectSecurityDesc Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a private object security descriptor object. ## Syntax diff --git a/docs/atl/reference/crbmap-class.md b/docs/atl/reference/crbmap-class.md index 4617fc49e3c..3a09ccf6c49 100644 --- a/docs/atl/reference/crbmap-class.md +++ b/docs/atl/reference/crbmap-class.md @@ -4,10 +4,11 @@ title: "CRBMap Class" ms.date: "11/04/2016" f1_keywords: ["CRBMap", "ATLCOLL/ATL::CRBMap", "ATLCOLL/ATL::CRBMap::CRBMap", "ATLCOLL/ATL::CRBMap::Lookup", "ATLCOLL/ATL::CRBMap::RemoveKey", "ATLCOLL/ATL::CRBMap::SetAt"] helpviewer_keywords: ["CRBMap class"] -ms.assetid: 658e94dc-e835-4356-aed1-1513e1f66969 --- # CRBMap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a mapping structure, using a Red-Black binary tree. ## Syntax diff --git a/docs/atl/reference/crbmultimap-class.md b/docs/atl/reference/crbmultimap-class.md index 3788491f6d5..c50ea797627 100644 --- a/docs/atl/reference/crbmultimap-class.md +++ b/docs/atl/reference/crbmultimap-class.md @@ -4,10 +4,11 @@ title: "CRBMultiMap Class" ms.date: "11/04/2016" f1_keywords: ["CRBMultiMap", "ATLCOLL/ATL::CRBMultiMap", "ATLCOLL/ATL::CRBMultiMap::CRBMultiMap", "ATLCOLL/ATL::CRBMultiMap::FindFirstWithKey", "ATLCOLL/ATL::CRBMultiMap::GetNextValueWithKey", "ATLCOLL/ATL::CRBMultiMap::GetNextWithKey", "ATLCOLL/ATL::CRBMultiMap::Insert", "ATLCOLL/ATL::CRBMultiMap::RemoveKey"] helpviewer_keywords: ["CRBMultiMap class"] -ms.assetid: 94d3ec0c-3e30-4ab7-a101-d8da4fb8add3 --- # CRBMultiMap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a mapping structure that allows each key can be associated with more than one value, using a Red-Black binary tree. ## Syntax diff --git a/docs/atl/reference/crbtree-class.md b/docs/atl/reference/crbtree-class.md index 1b37d5c41ee..d755ed2a10c 100644 --- a/docs/atl/reference/crbtree-class.md +++ b/docs/atl/reference/crbtree-class.md @@ -4,10 +4,11 @@ title: "CRBTree Class" ms.date: "11/04/2016" f1_keywords: ["CRBTree", "ATLCOLL/ATL::CRBTree", "ATLCOLL/ATL::CRBTree::KINARGTYPE", "ATLCOLL/ATL::CRBTree::KOUTARGTYPE", "ATLCOLL/ATL::CRBTree::VINARGTYPE", "ATLCOLL/ATL::CRBTree::VOUTARGTYPE", "ATLCOLL/ATL::CRBTree::FindFirstKeyAfter", "ATLCOLL/ATL::CRBTree::GetAt", "ATLCOLL/ATL::CRBTree::GetCount", "ATLCOLL/ATL::CRBTree::GetHeadPosition", "ATLCOLL/ATL::CRBTree::GetKeyAt", "ATLCOLL/ATL::CRBTree::GetNext", "ATLCOLL/ATL::CRBTree::GetNextAssoc", "ATLCOLL/ATL::CRBTree::GetNextKey", "ATLCOLL/ATL::CRBTree::GetNextValue", "ATLCOLL/ATL::CRBTree::GetPrev", "ATLCOLL/ATL::CRBTree::GetTailPosition", "ATLCOLL/ATL::CRBTree::GetValueAt", "ATLCOLL/ATL::CRBTree::IsEmpty", "ATLCOLL/ATL::CRBTree::RemoveAll", "ATLCOLL/ATL::CRBTree::RemoveAt", "ATLCOLL/ATL::CRBTree::SetValueAt"] helpviewer_keywords: ["CRBTree class"] -ms.assetid: a1b1cb63-38e4-4fc2-bb28-f774d1721760 --- # CRBTree Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for creating and utilizing a Red-Black tree. ## Syntax diff --git a/docs/atl/reference/creating-an-atl-project.md b/docs/atl/reference/creating-an-atl-project.md index 0e82550faf9..2b8d1914bda 100644 --- a/docs/atl/reference/creating-an-atl-project.md +++ b/docs/atl/reference/creating-an-atl-project.md @@ -4,10 +4,11 @@ title: "Creating an ATL Project" ms.date: "05/06/2019" f1_keywords: ["vc.appwiz.ATL.project"] helpviewer_keywords: ["ATL projects, creating", "ATL70.DLL", "_ATL_MIN_CRT macro", "distributing files with ATL components"] -ms.assetid: 061d5f98-f669-440e-9380-42f017a0f9e8 --- # Creating an ATL Project +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The easiest way to create an ATL project is to use the ATL Project Wizard, located in the **Win32 Projects** folder of the **New Project** dialog box. ## To create an ATL project using the ATL Project Wizard diff --git a/docs/atl/reference/cregkey-class.md b/docs/atl/reference/cregkey-class.md index 0b7bb612a0c..d2510be3e45 100644 --- a/docs/atl/reference/cregkey-class.md +++ b/docs/atl/reference/cregkey-class.md @@ -7,6 +7,8 @@ helpviewer_keywords: ["CRegKey class", "ATL, registry", "registry, deleting valu --- # `CRegKey` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for manipulating entries in the system registry. > [!IMPORTANT] @@ -151,7 +153,7 @@ Options for the key. The default value is `REG_OPTION_NON_VOLATILE`. For a list The security access for the key. The default value is `KEY_READ | KEY_WRITE`. For a list of possible values and descriptions, see `RegCreateKeyEx`. *`lpSecAttr`*\ -A pointer to a [`SECURITY_ATTRIBUTES`](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that indicates whether the handle of the key can be inherited by a child process. By default, this parameter is `NULL` (meaning the handle can’t be inherited). +A pointer to a [`SECURITY_ATTRIBUTES`](/previous-versions/windows/desktop/legacy/aa379560\(v=vs.85\)) structure that indicates whether the handle of the key can be inherited by a child process. By default, this parameter is `NULL` (meaning the handle can't be inherited). *`lpdwDisposition`*\ [out] If non-`NULL`, retrieves either `REG_CREATED_NEW_KEY` (if the key didn't exist and was created) or `REG_OPENED_EXISTING_KEY` (if the key existed and was opened). @@ -381,7 +383,7 @@ Specifies a set of flags that control which changes should be reported. This par Handle to an event. If the *`bAsync`* parameter is `TRUE`, the method returns immediately and changes are reported by signaling this event. If *`bAsync`* is `FALSE`, *`hEvent`* is ignored. *`bAsync`*\ -Specifies a flag that indicates how the method reports changes. If this parameter is `TRUE`, the method returns immediately and reports changes by signaling the specified event. When this parameter is `FALSE`, the method doesn't return until a change has occurred. If *`hEvent`* doesn't specify a valid event, the *`bAsync`* parameter can’t be `TRUE`. +Specifies a flag that indicates how the method reports changes. If this parameter is `TRUE`, the method returns immediately and reports changes by signaling the specified event. When this parameter is `FALSE`, the method doesn't return until a change has occurred. If *`hEvent`* doesn't specify a valid event, the *`bAsync`* parameter can't be `TRUE`. ### Return Value diff --git a/docs/atl/reference/crtthreadtraits-class.md b/docs/atl/reference/crtthreadtraits-class.md index de1edbf63f5..3703ee3ee16 100644 --- a/docs/atl/reference/crtthreadtraits-class.md +++ b/docs/atl/reference/crtthreadtraits-class.md @@ -4,10 +4,11 @@ title: "CRTThreadTraits Class" ms.date: "11/04/2016" f1_keywords: ["CRTThreadTraits", "ATLBASE/ATL::CRTThreadTraits", "ATLBASE/ATL::CRTThreadTraits::CreateThread"] helpviewer_keywords: ["CRTThreadTraits class", "threading [ATL], creation functions", "threading [ATL], CRT threads"] -ms.assetid: eb6e20b0-c2aa-4170-8e34-aaeeacc86343 --- # CRTThreadTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides the creation function for a CRT thread. Use this class if the thread will use CRT functions. > [!IMPORTANT] diff --git a/docs/atl/reference/csacl-class.md b/docs/atl/reference/csacl-class.md index 47717cec068..12157beccdf 100644 --- a/docs/atl/reference/csacl-class.md +++ b/docs/atl/reference/csacl-class.md @@ -4,10 +4,11 @@ title: "CSacl Class" ms.date: "11/04/2016" f1_keywords: ["CSacl", "ATLSECURITY/ATL::CSacl", "ATLSECURITY/ATL::CSacl::CSacl", "ATLSECURITY/ATL::CSacl::AddAuditAce", "ATLSECURITY/ATL::CSacl::GetAceCount", "ATLSECURITY/ATL::CSacl::RemoveAce", "ATLSECURITY/ATL::CSacl::RemoveAllAces"] helpviewer_keywords: ["CSacl class"] -ms.assetid: 8624889b-aebc-4183-9d29-a20f07837f05 --- # CSacl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for a SACL (system access-control list) structure. > [!IMPORTANT] diff --git a/docs/atl/reference/csecurityattributes-class.md b/docs/atl/reference/csecurityattributes-class.md index 7ba2de9becc..ffb68f7fe43 100644 --- a/docs/atl/reference/csecurityattributes-class.md +++ b/docs/atl/reference/csecurityattributes-class.md @@ -4,10 +4,11 @@ title: "CSecurityAttributes Class" ms.date: "11/04/2016" f1_keywords: ["CSecurityAttributes", "ATLSECURITY/ATL::CSecurityAttributes", "ATLSECURITY/ATL::CSecurityAttributes::CSecurityAttributes", "ATLSECURITY/ATL::CSecurityAttributes::Set"] helpviewer_keywords: ["CSecurityAttributes class"] -ms.assetid: a094880c-52e1-4a28-97ff-752d5869908e --- # CSecurityAttributes Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a thin wrapper for the security attributes structure. > [!IMPORTANT] diff --git a/docs/atl/reference/csecuritydesc-class.md b/docs/atl/reference/csecuritydesc-class.md index d5042907684..67f652293ec 100644 --- a/docs/atl/reference/csecuritydesc-class.md +++ b/docs/atl/reference/csecuritydesc-class.md @@ -4,10 +4,11 @@ title: "CSecurityDesc Class" ms.date: "11/04/2016" f1_keywords: ["CSecurityDesc", "ATLSECURITY/ATL::CSecurityDesc", "ATLSECURITY/ATL::CSecurityDesc::CSecurityDesc", "ATLSECURITY/ATL::CSecurityDesc::FromString", "ATLSECURITY/ATL::CSecurityDesc::GetControl", "ATLSECURITY/ATL::CSecurityDesc::GetDacl", "ATLSECURITY/ATL::CSecurityDesc::GetGroup", "ATLSECURITY/ATL::CSecurityDesc::GetOwner", "ATLSECURITY/ATL::CSecurityDesc::GetPSECURITY_DESCRIPTOR", "ATLSECURITY/ATL::CSecurityDesc::GetSacl", "ATLSECURITY/ATL::CSecurityDesc::IsDaclAutoInherited", "ATLSECURITY/ATL::CSecurityDesc::IsDaclDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsDaclPresent", "ATLSECURITY/ATL::CSecurityDesc::IsDaclProtected", "ATLSECURITY/ATL::CSecurityDesc::IsGroupDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsOwnerDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsSaclAutoInherited", "ATLSECURITY/ATL::CSecurityDesc::IsSaclDefaulted", "ATLSECURITY/ATL::CSecurityDesc::IsSaclPresent", "ATLSECURITY/ATL::CSecurityDesc::IsSaclProtected", "ATLSECURITY/ATL::CSecurityDesc::IsSelfRelative", "ATLSECURITY/ATL::CSecurityDesc::MakeAbsolute", "ATLSECURITY/ATL::CSecurityDesc::MakeSelfRelative", "ATLSECURITY/ATL::CSecurityDesc::SetControl", "ATLSECURITY/ATL::CSecurityDesc::SetDacl", "ATLSECURITY/ATL::CSecurityDesc::SetGroup", "ATLSECURITY/ATL::CSecurityDesc::SetOwner", "ATLSECURITY/ATL::CSecurityDesc::SetSacl", "ATLSECURITY/ATL::CSecurityDesc::ToString"] helpviewer_keywords: ["CSecurityDesc class"] -ms.assetid: 3767a327-378f-4690-ba40-4d9f6a1f5ee4 --- # CSecurityDesc Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for the `SECURITY_DESCRIPTOR` structure. > [!IMPORTANT] diff --git a/docs/atl/reference/csid-class.md b/docs/atl/reference/csid-class.md index 49be86aa613..064eaa6ad79 100644 --- a/docs/atl/reference/csid-class.md +++ b/docs/atl/reference/csid-class.md @@ -4,10 +4,11 @@ title: "CSid class" ms.date: "03/27/2019" f1_keywords: ["CSid", "ATLSECURITY/ATL::CSid", "ATLSECURITY/ATL::CSid::CSidArray", "ATLSECURITY/ATL::CSid::CSid", "ATLSECURITY/ATL::CSid::AccountName", "ATLSECURITY/ATL::CSid::Domain", "ATLSECURITY/ATL::CSid::EqualPrefix", "ATLSECURITY/ATL::CSid::GetLength", "ATLSECURITY/ATL::CSid::GetPSID", "ATLSECURITY/ATL::CSid::GetPSID_IDENTIFIER_AUTHORITY", "ATLSECURITY/ATL::CSid::GetSubAuthority", "ATLSECURITY/ATL::CSid::GetSubAuthorityCount", "ATLSECURITY/ATL::CSid::IsValid", "ATLSECURITY/ATL::CSid::LoadAccount", "ATLSECURITY/ATL::CSid::Sid", "ATLSECURITY/ATL::CSid::SidNameUse"] helpviewer_keywords: ["CSid class"] -ms.assetid: be58b7ca-5958-49c3-a833-ca341aaaf753 --- # `CSid` class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for a `SID` (security identifier) structure. > [!IMPORTANT] diff --git a/docs/atl/reference/csimplearray-class.md b/docs/atl/reference/csimplearray-class.md index b79b7e57abb..c9393a904da 100644 --- a/docs/atl/reference/csimplearray-class.md +++ b/docs/atl/reference/csimplearray-class.md @@ -4,10 +4,11 @@ title: "CSimpleArray Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleArray", "ATLSIMPCOLL/ATL::CSimpleArray", "ATLSIMPCOLL/ATL::CSimpleArray::CSimpleArray", "ATLSIMPCOLL/ATL::CSimpleArray::Add", "ATLSIMPCOLL/ATL::CSimpleArray::Find", "ATLSIMPCOLL/ATL::CSimpleArray::GetData", "ATLSIMPCOLL/ATL::CSimpleArray::GetSize", "ATLSIMPCOLL/ATL::CSimpleArray::Remove", "ATLSIMPCOLL/ATL::CSimpleArray::RemoveAll", "ATLSIMPCOLL/ATL::CSimpleArray::RemoveAt", "ATLSIMPCOLL/ATL::CSimpleArray::SetAtIndex"] helpviewer_keywords: ["CSimpleArray class"] -ms.assetid: ee0c9f39-b61c-4c18-bc43-4eada21dca3a --- # CSimpleArray Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for managing a simple array. ## Syntax @@ -252,7 +253,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/csimplearrayequalhelper-class.md b/docs/atl/reference/csimplearrayequalhelper-class.md index e88c64cd44f..dd20404054a 100644 --- a/docs/atl/reference/csimplearrayequalhelper-class.md +++ b/docs/atl/reference/csimplearrayequalhelper-class.md @@ -4,10 +4,11 @@ title: "CSimpleArrayEqualHelper Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleArrayEqualHelper", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelper", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelper::IsEqual"] helpviewer_keywords: ["CSimpleArrayEqualHelper class"] -ms.assetid: a2b55d89-78c9-42ef-842c-5304c6d20ad6 --- # CSimpleArrayEqualHelper Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a helper for the [CSimpleArray](../../atl/reference/csimplearray-class.md) class. ## Syntax diff --git a/docs/atl/reference/csimplearrayequalhelperfalse-class.md b/docs/atl/reference/csimplearrayequalhelperfalse-class.md index 9b66910ec4e..36ad6022a6d 100644 --- a/docs/atl/reference/csimplearrayequalhelperfalse-class.md +++ b/docs/atl/reference/csimplearrayequalhelperfalse-class.md @@ -4,10 +4,11 @@ title: "CSimpleArrayEqualHelperFalse Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleArrayEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleArrayEqualHelperFalse::IsEqual"] helpviewer_keywords: ["CSimpleArrayEqualHelperFalse class"] -ms.assetid: 6918af6f-d23d-49eb-8482-c44272f5ffeb --- # CSimpleArrayEqualHelperFalse Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a helper for the [CSimpleArray](../../atl/reference/csimplearray-class.md) class. ## Syntax diff --git a/docs/atl/reference/csimpledialog-class.md b/docs/atl/reference/csimpledialog-class.md index 9650d3ce7c3..ea993e768cc 100644 --- a/docs/atl/reference/csimpledialog-class.md +++ b/docs/atl/reference/csimpledialog-class.md @@ -4,10 +4,11 @@ title: "CSimpleDialog Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleDialog", "ATLWIN/ATL::CSimpleDialog", "ATLWIN/ATL::CSimpleDialog::DoModal"] helpviewer_keywords: ["CSimpleDialog class", "CSimpleDialog class, modal dialog boxes in ATL", "dialog boxes, modal", "modal dialog boxes, ATL"] -ms.assetid: 2ae65cc9-4f32-4168-aecd-200b4a480fdf --- # CSimpleDialog Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a basic modal dialog box. ## Syntax diff --git a/docs/atl/reference/csimplemap-class.md b/docs/atl/reference/csimplemap-class.md index 50f20403759..ce0d4f90990 100644 --- a/docs/atl/reference/csimplemap-class.md +++ b/docs/atl/reference/csimplemap-class.md @@ -4,10 +4,11 @@ title: "CSimpleMap Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleMap", "ATLSIMPCOLL/ATL::CSimpleMap", "ATLSIMPCOLL/ATL::CSimpleMap::_ArrayElementType", "ATLSIMPCOLL/ATL::CSimpleMap::_ArrayKeyType", "ATLSIMPCOLL/ATL::CSimpleMap::CSimpleMap", "ATLSIMPCOLL/ATL::CSimpleMap::Add", "ATLSIMPCOLL/ATL::CSimpleMap::FindKey", "ATLSIMPCOLL/ATL::CSimpleMap::FindVal", "ATLSIMPCOLL/ATL::CSimpleMap::GetKeyAt", "ATLSIMPCOLL/ATL::CSimpleMap::GetSize", "ATLSIMPCOLL/ATL::CSimpleMap::GetValueAt", "ATLSIMPCOLL/ATL::CSimpleMap::Lookup", "ATLSIMPCOLL/ATL::CSimpleMap::Remove", "ATLSIMPCOLL/ATL::CSimpleMap::RemoveAll", "ATLSIMPCOLL/ATL::CSimpleMap::RemoveAt", "ATLSIMPCOLL/ATL::CSimpleMap::ReverseLookup", "ATLSIMPCOLL/ATL::CSimpleMap::SetAt", "ATLSIMPCOLL/ATL::CSimpleMap::SetAtIndex"] helpviewer_keywords: ["CSimpleMap class"] -ms.assetid: 61b06eb4-ae73-44b0-a305-0afb5a33e8b1 --- # CSimpleMap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides support for a simple mapping array. ## Syntax diff --git a/docs/atl/reference/csimplemapequalhelper-class.md b/docs/atl/reference/csimplemapequalhelper-class.md index 05c3178fdaa..ad384ff61db 100644 --- a/docs/atl/reference/csimplemapequalhelper-class.md +++ b/docs/atl/reference/csimplemapequalhelper-class.md @@ -4,10 +4,11 @@ title: "CSimpleMapEqualHelper Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleMapEqualHelper", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelper", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelper::IsEqualKey", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelper::IsEqualValue"] helpviewer_keywords: ["CSimpleMapEqualHelper class"] -ms.assetid: 9bb2968a-d609-405c-8272-ff3b42df6164 --- # CSimpleMapEqualHelper Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a helper for the [CSimpleMap](../../atl/reference/csimplemap-class.md) class. ## Syntax diff --git a/docs/atl/reference/csimplemapequalhelperfalse-class.md b/docs/atl/reference/csimplemapequalhelperfalse-class.md index 97e43c2e59e..0be6f6a9539 100644 --- a/docs/atl/reference/csimplemapequalhelperfalse-class.md +++ b/docs/atl/reference/csimplemapequalhelperfalse-class.md @@ -4,10 +4,11 @@ title: "CSimpleMapEqualHelperFalse Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleMapEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelperFalse", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelperFalse::IsEqualKey", "ATLSIMPCOLL/ATL::CSimpleMapEqualHelperFalse::IsEqualValue"] helpviewer_keywords: ["CSimpleMapEqualHelperFalse class"] -ms.assetid: a873eea3-e130-45cc-a476-61ee79511c3b --- # CSimpleMapEqualHelperFalse Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a helper for the [CSimpleMap](../../atl/reference/csimplemap-class.md) class. ## Syntax diff --git a/docs/atl/reference/csnapinitemimpl-class.md b/docs/atl/reference/csnapinitemimpl-class.md index b302a376c2c..b9c745e5ff1 100644 --- a/docs/atl/reference/csnapinitemimpl-class.md +++ b/docs/atl/reference/csnapinitemimpl-class.md @@ -4,10 +4,11 @@ title: "CSnapInItemImpl Class" ms.date: "11/04/2016" f1_keywords: ["CSnapInItemImpl", "ATLSNAP/ATL::CSnapInItemImpl", "ATLSNAP/ATL::CSnapInItemImpl::CSnapInItemImpl", "ATLSNAP/ATL::CSnapInItemImpl::AddMenuItems", "ATLSNAP/ATL::CSnapInItemImpl::Command", "ATLSNAP/ATL::CSnapInItemImpl::CreatePropertyPages", "ATLSNAP/ATL::CSnapInItemImpl::FillData", "ATLSNAP/ATL::CSnapInItemImpl::GetResultPaneInfo", "ATLSNAP/ATL::CSnapInItemImpl::GetResultViewType", "ATLSNAP/ATL::CSnapInItemImpl::GetScopePaneInfo", "ATLSNAP/ATL::CSnapInItemImpl::Notify", "ATLSNAP/ATL::CSnapInItemImpl::QueryPagesFor", "ATLSNAP/ATL::CSnapInItemImpl::SetMenuInsertionFlags", "ATLSNAP/ATL::CSnapInItemImpl::SetToolbarButtonInfo", "ATLSNAP/ATL::CSnapInItemImpl::UpdateMenuState", "ATLSNAP/ATL::CSnapInItemImpl::UpdateToolbarButton", "ATLSNAP/ATL::CSnapInItemImpl::m_bstrDisplayName", "ATLSNAP/ATL::CSnapInItemImpl::m_resultDataItem", "ATLSNAP/ATL::CSnapInItemImpl::m_scopeDataItem"] helpviewer_keywords: ["snap-ins, data items", "snap-ins, ATL support for", "CSnapInItemImpl class", "snap-ins"] -ms.assetid: 52caefbd-9eae-49b0-add2-d55524271aa7 --- # CSnapInItemImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for implementing a snap-in node object. > [!IMPORTANT] diff --git a/docs/atl/reference/csnapinpropertypageimpl-class.md b/docs/atl/reference/csnapinpropertypageimpl-class.md index 5bbd52fce69..ab78fc1e15c 100644 --- a/docs/atl/reference/csnapinpropertypageimpl-class.md +++ b/docs/atl/reference/csnapinpropertypageimpl-class.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: CSnapInPropertyPageImpl Class" title: "CSnapInPropertyPageImpl Class" -ms.date: "11/04/2016" +description: "Learn more about: CSnapInPropertyPageImpl Class" +ms.date: 11/04/2016 f1_keywords: ["CSnapInPropertyPageImpl", "ATLSNAP/ATL::CSnapInPropertyPageImpl", "ATLSNAP/ATL::CSnapInPropertyPageImpl::CSnapInPropertyPageImpl", "ATLSNAP/ATL::CSnapInPropertyPageImpl::CancelToClose", "ATLSNAP/ATL::CSnapInPropertyPageImpl::Create", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnApply", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnHelp", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnKillActive", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnQueryCancel", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnReset", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnSetActive", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnWizardBack", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnWizardFinish", "ATLSNAP/ATL::CSnapInPropertyPageImpl::OnWizardNext", "ATLSNAP/ATL::CSnapInPropertyPageImpl::QuerySiblings", "ATLSNAP/ATL::CSnapInPropertyPageImpl::SetModified", "ATLSNAP/ATL::CSnapInPropertyPageImpl::m_psp"] helpviewer_keywords: ["snap-ins, property pages", "snap-ins", "property pages, ATL", "CSnapInPropertyPageImpl class"] -ms.assetid: 75bdce5a-985e-4166-bd44-493132e023c4 --- # CSnapInPropertyPageImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for implementing a snap-in property page object. > [!IMPORTANT] @@ -15,8 +16,9 @@ This class provides methods for implementing a snap-in property page object. ## Syntax -``` -CSnapInPropertyPageImpl : public CDialogImplBase +```cpp +template +class ATL_NO_VTABLE CSnapInPropertyPageImpl : public CDialogImplBase ``` ## Members diff --git a/docs/atl/reference/csocketaddr-class.md b/docs/atl/reference/csocketaddr-class.md index de051c6ae62..5a186823dce 100644 --- a/docs/atl/reference/csocketaddr-class.md +++ b/docs/atl/reference/csocketaddr-class.md @@ -4,10 +4,11 @@ title: "CSocketAddr Class" ms.date: "10/22/2018" f1_keywords: ["CSocketAddr", "ATLSOCKET/ATL::CSocketAddr", "ATLSOCKET/ATL::CSocketAddr::CSocketAddr", "ATLSOCKET/ATL::CSocketAddr::FindAddr", "ATLSOCKET/ATL::CSocketAddr::FindINET4Addr", "ATLSOCKET/ATL::CSocketAddr::FindINET6Addr", "ATLSOCKET/ATL::CSocketAddr::GetAddrInfo", "ATLSOCKET/ATL::CSocketAddr::GetAddrInfoList"] helpviewer_keywords: ["CSocketAddr class"] -ms.assetid: 2fb2d8a7-899e-4a36-a342-cc9f4fcdd68c --- # CSocketAddr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for converting host names to host addresses, supporting both IPv4 and IPV6 formats. ## Syntax diff --git a/docs/atl/reference/cstockpropimpl-class.md b/docs/atl/reference/cstockpropimpl-class.md index 29b1619156d..0b5fc8d9fc6 100644 --- a/docs/atl/reference/cstockpropimpl-class.md +++ b/docs/atl/reference/cstockpropimpl-class.md @@ -1,13 +1,14 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for supporting stock property values. > [!IMPORTANT] @@ -607,7 +608,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 +1101,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/cstringelementtraits-class.md b/docs/atl/reference/cstringelementtraits-class.md index d314865a597..93cb8ccf5a2 100644 --- a/docs/atl/reference/cstringelementtraits-class.md +++ b/docs/atl/reference/cstringelementtraits-class.md @@ -4,10 +4,11 @@ title: "CStringElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CStringElementTraits", "CSTRINGT/ATL::CStringElementTraits", "CSTRINGT/ATL::CStringElementTraits::INARGTYPE", "CSTRINGT/ATL::CStringElementTraits::OUTARGTYPE", "CSTRINGT/ATL::CStringElementTraits::CompareElements", "CSTRINGT/ATL::CStringElementTraits::CompareElementsOrdered", "CSTRINGT/ATL::CStringElementTraits::CopyElements", "CSTRINGT/ATL::CStringElementTraits::Hash", "CSTRINGT/ATL::CStringElementTraits::RelocateElements"] helpviewer_keywords: ["CStringElementTraits class"] -ms.assetid: 74d7134b-099d-4455-bf91-3e68ccbf95bc --- # CStringElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides static functions used by collection classes storing `CString` objects. ## Syntax diff --git a/docs/atl/reference/cstringelementtraitsi-class.md b/docs/atl/reference/cstringelementtraitsi-class.md index 089e89ec285..41f472f6925 100644 --- a/docs/atl/reference/cstringelementtraitsi-class.md +++ b/docs/atl/reference/cstringelementtraitsi-class.md @@ -4,10 +4,11 @@ title: "CStringElementTraitsI Class" ms.date: "11/04/2016" f1_keywords: ["CStringElementTraitsI", "ATLCOLL/ATL::CStringElementTraitsI", "ATLCOLL/ATL::CStringElementTraitsI::INARGTYPE", "ATLCOLL/ATL::CStringElementTraitsI::OUTARGTYPE", "ATLCOLL/ATL::CStringElementTraitsI::CompareElements", "ATLCOLL/ATL::CStringElementTraitsI::CompareElementsOrdered", "ATLCOLL/ATL::CStringElementTraitsI::Hash"] helpviewer_keywords: ["CStringElementTraitsI class"] -ms.assetid: c23f92b1-91e5-400f-96ed-258b02622b7a --- # CStringElementTraitsI Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides static functions related to strings stored in collection class objects. It is similar to [CStringElementTraits](../../atl/reference/cstringelementtraits-class.md), but performs case-insensitive comparisons. ## Syntax diff --git a/docs/atl/reference/cstringrefelementtraits-class.md b/docs/atl/reference/cstringrefelementtraits-class.md index ed14c61490e..1973a6ed2fb 100644 --- a/docs/atl/reference/cstringrefelementtraits-class.md +++ b/docs/atl/reference/cstringrefelementtraits-class.md @@ -4,10 +4,11 @@ title: "CStringRefElementTraits Class" ms.date: "11/04/2016" f1_keywords: ["CStringRefElementTraits", "ATLCOLL/ATL::CStringRefElementTraits", "ATLCOLL/ATL::CStringRefElementTraits::CompareElements", "ATLCOLL/ATL::CStringRefElementTraits::CompareElementsOrdered", "ATLCOLL/ATL::CStringRefElementTraits::Hash"] helpviewer_keywords: ["CStringRefElementTraits class"] -ms.assetid: cc15062d-5627-46cc-ac2b-1744afdc2dbd --- # CStringRefElementTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides static functions related to strings stored in collection class objects. The string objects are dealt with as references. ## Syntax diff --git a/docs/atl/reference/cthreadpool-class.md b/docs/atl/reference/cthreadpool-class.md index e5834d8409c..a9760e62914 100644 --- a/docs/atl/reference/cthreadpool-class.md +++ b/docs/atl/reference/cthreadpool-class.md @@ -1,13 +1,14 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a pool of worker threads that process a queue of work items. ## Syntax @@ -265,7 +266,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/ctokengroups-class.md b/docs/atl/reference/ctokengroups-class.md index 50ca0053c9b..08dfba3fbf9 100644 --- a/docs/atl/reference/ctokengroups-class.md +++ b/docs/atl/reference/ctokengroups-class.md @@ -4,10 +4,11 @@ title: "CTokenGroups Class" ms.date: "11/04/2016" f1_keywords: ["CTokenGroups", "ATLSECURITY/ATL::CTokenGroups", "ATLSECURITY/ATL::CTokenGroups::CTokenGroups", "ATLSECURITY/ATL::CTokenGroups::Add", "ATLSECURITY/ATL::CTokenGroups::Delete", "ATLSECURITY/ATL::CTokenGroups::DeleteAll", "ATLSECURITY/ATL::CTokenGroups::GetCount", "ATLSECURITY/ATL::CTokenGroups::GetLength", "ATLSECURITY/ATL::CTokenGroups::GetPTOKEN_GROUPS", "ATLSECURITY/ATL::CTokenGroups::GetSidsAndAttributes", "ATLSECURITY/ATL::CTokenGroups::LookupSid"] helpviewer_keywords: ["CTokenGroups class"] -ms.assetid: 2ab08076-4b08-4487-bc70-ec6dee304190 --- # CTokenGroups Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for the `TOKEN_GROUPS` structure. > [!IMPORTANT] diff --git a/docs/atl/reference/ctokenprivileges-class.md b/docs/atl/reference/ctokenprivileges-class.md index df23437d13c..43abc2e7c6c 100644 --- a/docs/atl/reference/ctokenprivileges-class.md +++ b/docs/atl/reference/ctokenprivileges-class.md @@ -4,10 +4,11 @@ title: "CTokenPrivileges Class" ms.date: "11/04/2016" f1_keywords: ["CTokenPrivileges", "ATLSECURITY/ATL::CTokenPrivileges", "ATLSECURITY/ATL::CTokenPrivileges::CTokenPrivileges", "ATLSECURITY/ATL::CTokenPrivileges::Add", "ATLSECURITY/ATL::CTokenPrivileges::Delete", "ATLSECURITY/ATL::CTokenPrivileges::DeleteAll", "ATLSECURITY/ATL::CTokenPrivileges::GetCount", "ATLSECURITY/ATL::CTokenPrivileges::GetDisplayNames", "ATLSECURITY/ATL::CTokenPrivileges::GetLength", "ATLSECURITY/ATL::CTokenPrivileges::GetLuidsAndAttributes", "ATLSECURITY/ATL::CTokenPrivileges::GetNamesAndAttributes", "ATLSECURITY/ATL::CTokenPrivileges::GetPTOKEN_PRIVILEGES", "ATLSECURITY/ATL::CTokenPrivileges::LookupPrivilege"] helpviewer_keywords: ["CTokenPrivileges class"] -ms.assetid: 89590105-f001-4014-870d-142926091231 --- # CTokenPrivileges Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is a wrapper for the `TOKEN_PRIVILEGES` structure. > [!IMPORTANT] diff --git a/docs/atl/reference/curl-class.md b/docs/atl/reference/curl-class.md index ff1a201f3fc..1676b7244ed 100644 --- a/docs/atl/reference/curl-class.md +++ b/docs/atl/reference/curl-class.md @@ -4,10 +4,11 @@ title: "CUrl Class" ms.date: "05/06/2019" f1_keywords: ["CUrl", "ATLUTIL/ATL::CUrl", "ATLUTIL/ATL::CUrl::CUrl", "ATLUTIL/ATL::CUrl::Canonicalize", "ATLUTIL/ATL::CUrl::Clear", "ATLUTIL/ATL::CUrl::CrackUrl", "ATLUTIL/ATL::CUrl::CreateUrl", "ATLUTIL/ATL::CUrl::GetExtraInfo", "ATLUTIL/ATL::CUrl::GetExtraInfoLength", "ATLUTIL/ATL::CUrl::GetHostName", "ATLUTIL/ATL::CUrl::GetHostNameLength", "ATLUTIL/ATL::CUrl::GetPassword", "ATLUTIL/ATL::CUrl::GetPasswordLength", "ATLUTIL/ATL::CUrl::GetPortNumber", "ATLUTIL/ATL::CUrl::GetScheme", "ATLUTIL/ATL::CUrl::GetSchemeName", "ATLUTIL/ATL::CUrl::GetSchemeNameLength", "ATLUTIL/ATL::CUrl::GetUrlLength", "ATLUTIL/ATL::CUrl::GetUrlPath", "ATLUTIL/ATL::CUrl::GetUrlPathLength", "ATLUTIL/ATL::CUrl::GetUserName", "ATLUTIL/ATL::CUrl::GetUserNameLength", "ATLUTIL/ATL::CUrl::SetExtraInfo", "ATLUTIL/ATL::CUrl::SetHostName", "ATLUTIL/ATL::CUrl::SetPassword", "ATLUTIL/ATL::CUrl::SetPortNumber", "ATLUTIL/ATL::CUrl::SetScheme", "ATLUTIL/ATL::CUrl::SetSchemeName", "ATLUTIL/ATL::CUrl::SetUrlPath", "ATLUTIL/ATL::CUrl::SetUserName"] helpviewer_keywords: ["CUrl class"] -ms.assetid: b3894d34-47b9-4961-9719-4197153793da --- # CUrl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents a URL. It allows you to manipulate each element of the URL independently of the others whether parsing an existing URL string or building a string from scratch. > [!IMPORTANT] diff --git a/docs/atl/reference/cw2aex-class.md b/docs/atl/reference/cw2aex-class.md index 9029cccbe76..ef2b3d63263 100644 --- a/docs/atl/reference/cw2aex-class.md +++ b/docs/atl/reference/cw2aex-class.md @@ -7,6 +7,8 @@ helpviewer_keywords: ["CW2AEX class"] --- # `CW2AEX` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is used by the string conversion macros `CT2AEX`, `CW2TEX`, `CW2CTEX`, and `CT2CAEX`, and the typedef `CW2A`. > [!IMPORTANT] diff --git a/docs/atl/reference/cw2cwex-class.md b/docs/atl/reference/cw2cwex-class.md index 58df28f8f63..c00e6ef2143 100644 --- a/docs/atl/reference/cw2cwex-class.md +++ b/docs/atl/reference/cw2cwex-class.md @@ -4,10 +4,11 @@ title: "CW2CWEX Class" ms.date: "11/04/2016" f1_keywords: ["CW2CWEX", "ATLCONV/ATL::CW2CWEX", "ATLCONV/ATL::CW2CWEX::CW2CWEX", "ATLCONV/ATL::CW2CWEX::m_psz"] helpviewer_keywords: ["CW2CWEX class"] -ms.assetid: d654b22b-05a6-410f-a0ec-9a2cbbb4cca7 --- # CW2CWEX Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is used by the string conversion macros CW2CTEX and CT2CWEX, and the typedef CW2W. > [!IMPORTANT] diff --git a/docs/atl/reference/cw2wex-class.md b/docs/atl/reference/cw2wex-class.md index 3c0cfb09467..7148e484e49 100644 --- a/docs/atl/reference/cw2wex-class.md +++ b/docs/atl/reference/cw2wex-class.md @@ -1,13 +1,14 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class is used by the string conversion macros CW2TEX and CT2WEX, and the typedef CW2W. > [!IMPORTANT] @@ -100,7 +101,7 @@ Creates the buffer required for the translation. ## CW2WEX::~CW2WEX -The destructor.. +The destructor. ``` ~CW2WEX() throw(); @@ -140,9 +141,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/cwin32heap-class.md b/docs/atl/reference/cwin32heap-class.md index 8c69f91f153..0076ab7e2c0 100644 --- a/docs/atl/reference/cwin32heap-class.md +++ b/docs/atl/reference/cwin32heap-class.md @@ -4,10 +4,11 @@ title: "CWin32Heap Class" ms.date: "11/04/2016" f1_keywords: ["CWin32Heap", "ATLMEM/ATL::CWin32Heap", "ATLMEM/ATL::CWin32Heap::CWin32Heap", "ATLMEM/ATL::CWin32Heap::Allocate", "ATLMEM/ATL::CWin32Heap::Attach", "ATLMEM/ATL::CWin32Heap::Detach", "ATLMEM/ATL::CWin32Heap::Free", "ATLMEM/ATL::CWin32Heap::GetSize", "ATLMEM/ATL::CWin32Heap::Reallocate", "ATLMEM/ATL::CWin32Heap::m_bOwnHeap", "ATLMEM/ATL::CWin32Heap::m_hHeap"] helpviewer_keywords: ["CWin32Heap class"] -ms.assetid: 69176022-ed98-4e3b-96d8-116b0c58ac95 --- # CWin32Heap Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements [IAtlMemMgr](../../atl/reference/iatlmemmgr-class.md) using the Win32 heap allocation functions. > [!IMPORTANT] diff --git a/docs/atl/reference/cwindow-class.md b/docs/atl/reference/cwindow-class.md index ec8e1f2c778..99016859b08 100644 --- a/docs/atl/reference/cwindow-class.md +++ b/docs/atl/reference/cwindow-class.md @@ -7,6 +7,8 @@ helpviewer_keywords: ["CWindow class"] --- # `CWindow` Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for manipulating a window. > [!IMPORTANT] @@ -781,7 +783,7 @@ HRESULT GetDlgControl( ### Return Value -Returns `S_OK` on success or any valid error `HRESULT`. For example, the function returns `E_FAIL` if the control specified by *`nID`* can’t be found and it returns `E_NOINTERFACE` if the control can be found, but it doesn't support the interface specified by *`iid`*. +Returns `S_OK` on success or any valid error `HRESULT`. For example, the function returns `E_FAIL` if the control specified by *`nID`* can't be found and it returns `E_NOINTERFACE` if the control can be found, but it doesn't support the interface specified by *`iid`*. ### Remarks diff --git a/docs/atl/reference/cwindowimpl-class.md b/docs/atl/reference/cwindowimpl-class.md index d2041bc669a..bfd4e676f0c 100644 --- a/docs/atl/reference/cwindowimpl-class.md +++ b/docs/atl/reference/cwindowimpl-class.md @@ -4,10 +4,11 @@ title: "CWindowImpl Class" ms.date: "11/04/2016" f1_keywords: ["CWindowImpl", "ATLWIN/ATL::CWindowImpl", "ATLWIN/ATL::CWindowImpl::Create", "ATLWIN/ATL::CWindowImpl::DefWindowProc", "ATLWIN/ATL::CWindowImpl::GetCurrentMessage", "ATLWIN/ATL::CWindowImpl::GetWindowProc", "ATLWIN/ATL::CWindowImpl::OnFinalMessage", "ATLWIN/ATL::CWindowImpl::SubclassWindow", "ATLWIN/ATL::CWindowImpl::UnsubclassWindow", "ATLWIN/ATL::CWindowImpl::GetWndClassInfo", "ATLWIN/ATL::CWindowImpl::WindowProc", "ATLWIN/ATL::CWindowImpl::m_pfnSuperWindowProc"] helpviewer_keywords: ["CWindowImpl class", "subclassing windows, ATL"] -ms.assetid: 02eefd45-a0a6-4d1b-99f6-dbf627e2cc2f --- # CWindowImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Provides methods for creating or subclassing a window. > [!IMPORTANT] diff --git a/docs/atl/reference/cwintraits-class.md b/docs/atl/reference/cwintraits-class.md index e7d7b65eabc..123d908d88a 100644 --- a/docs/atl/reference/cwintraits-class.md +++ b/docs/atl/reference/cwintraits-class.md @@ -4,10 +4,11 @@ title: "CWinTraits Class" ms.date: "11/04/2016" f1_keywords: ["CWinTraits", "ATLWIN/ATL::CWinTraits", "ATLWIN/ATL::CWinTraits::GetWndExStyle", "ATLWIN/ATL::CWinTraits::GetWndStyle"] helpviewer_keywords: ["CMDIChildWinTraits class", "window styles, default values for ATL", "CWinTraits class", "CFrameWinTraits class", "CControlWinTraits class"] -ms.assetid: f78f486e-6d9c-42c6-8e86-371e05aa7e59 --- # CWinTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a method for standardizing the styles used when creating a window object. > [!IMPORTANT] diff --git a/docs/atl/reference/cwintraitsor-class.md b/docs/atl/reference/cwintraitsor-class.md index fbc54c0034a..8f6c147d330 100644 --- a/docs/atl/reference/cwintraitsor-class.md +++ b/docs/atl/reference/cwintraitsor-class.md @@ -4,10 +4,11 @@ title: "CWinTraitsOR Class" ms.date: "11/04/2016" f1_keywords: ["CWinTraitsOR", "ATLWIN/ATL::CWinTraitsOR", "ATLWIN/ATL::CWinTraitsOR::GetWndExStyle", "ATLWIN/ATL::CWinTraitsOR::GetWndStyle"] helpviewer_keywords: ["CWinTraitsOR class", "window styles, default values for ATL"] -ms.assetid: 1eb7b1e8-a9bd-411b-a30a-35a8a10af989 --- # CWinTraitsOR Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a method for standardizing the styles used when creating a window object. > [!IMPORTANT] diff --git a/docs/atl/reference/cwndclassinfo-class.md b/docs/atl/reference/cwndclassinfo-class.md index 0ac47624556..4cbf31cfbf4 100644 --- a/docs/atl/reference/cwndclassinfo-class.md +++ b/docs/atl/reference/cwndclassinfo-class.md @@ -4,10 +4,11 @@ title: "CWndClassInfo Class" ms.date: "11/04/2016" f1_keywords: ["CWndClassInfo", "ATLWIN/ATL::CWndClassInfo", "ATLWIN/ATL::Register", "ATLWIN/ATL::m_atom", "ATLWIN/ATL::m_bSystemCursor", "ATLWIN/ATL::m_lpszCursorID", "ATLWIN/ATL::m_lpszOrigName", "ATLWIN/ATL::m_szAutoName", "ATLWIN/ATL::m_wc", "ATLWIN/ATL::pWndProc"] helpviewer_keywords: ["CWndClassInfo class"] -ms.assetid: c36fe7e1-75f1-4cf5-a06f-9f59c43fe6fb --- # CWndClassInfo Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for registering information for a window class. > [!IMPORTANT] diff --git a/docs/atl/reference/cworkerthread-class.md b/docs/atl/reference/cworkerthread-class.md index a0171833ba9..8e3c4e5cbb1 100644 --- a/docs/atl/reference/cworkerthread-class.md +++ b/docs/atl/reference/cworkerthread-class.md @@ -4,10 +4,11 @@ title: "CWorkerThread Class" ms.date: "11/04/2016" f1_keywords: ["CWorkerThread", "ATLUTIL/ATL::CWorkerThread", "ATLUTIL/ATL::CWorkerThread::CWorkerThread", "ATLUTIL/ATL::CWorkerThread::AddHandle", "ATLUTIL/ATL::CWorkerThread::AddTimer", "ATLUTIL/ATL::CWorkerThread::GetThreadHandle", "ATLUTIL/ATL::CWorkerThread::GetThreadId", "ATLUTIL/ATL::CWorkerThread::Initialize", "ATLUTIL/ATL::CWorkerThread::RemoveHandle", "ATLUTIL/ATL::CWorkerThread::Shutdown"] helpviewer_keywords: ["CWorkerThread class"] -ms.assetid: be79a832-1345-4a36-a13e-a406cc65286f --- # CWorkerThread Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class creates a worker thread or uses an existing one, waits on one or more kernel object handles, and executes a specified client function when one of the handles is signaled. > [!IMPORTANT] diff --git a/docs/atl/reference/debugging-and-error-reporting-global-functions.md b/docs/atl/reference/debugging-and-error-reporting-global-functions.md index defba9ea3c3..0d293887fd6 100644 --- a/docs/atl/reference/debugging-and-error-reporting-global-functions.md +++ b/docs/atl/reference/debugging-and-error-reporting-global-functions.md @@ -4,10 +4,11 @@ title: "Debugging and Error Reporting Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlcomcli/ATL::AtlHresultFromLastError", "atlcom/ATL::AtlReportError", "atldef/ATL::AtlThrow"] helpviewer_keywords: ["functions [ATL], error reporting"] -ms.assetid: 11339c02-98cd-428d-b3b9-7deeb155a6a3 --- # Debugging and Error Reporting Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide useful debugging and trace facilities. |Name|Description| diff --git a/docs/atl/reference/debugging-and-error-reporting-macros.md b/docs/atl/reference/debugging-and-error-reporting-macros.md index 463ef4c0072..c5d43762cfc 100644 --- a/docs/atl/reference/debugging-and-error-reporting-macros.md +++ b/docs/atl/reference/debugging-and-error-reporting-macros.md @@ -4,10 +4,11 @@ title: "Debugging and Error Reporting Macros" ms.date: "05/06/2019" f1_keywords: ["atldef/ATL::_ATL_DEBUG_INTERFACES", "atldef/ATL::_ATL_DEBUG_QI", "atldef/ATL::ATLASSERT", "afx/ATL::ATLENSURE", "atltrace/ATL::ATLTRACENOTIMPL", "atltrace/ATL::ATLTRACE", "ATLDEF/_ATL_DEBUG_INTERFACES", "ATLDEF/_ATL_DEBUG_QI", "ATLDEF/ATLASSERT", "AFX/ATLENSURE", "ATLTRACE/ATLTRACENOTIMPL", "ATLTRACE/ATLTRACE", "ATLDEF/ATLSTATIC_ASSERT"] helpviewer_keywords: ["macros, error reporting"] -ms.assetid: 4da9b87f-ec5c-4a32-ab93-637780909b9d --- # Debugging and Error Reporting Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros provide useful debugging and trace facilities. |Name|Description| diff --git a/docs/atl/reference/default-atl-project-configurations.md b/docs/atl/reference/default-atl-project-configurations.md index 0b8caec7af5..bca92e9bb53 100644 --- a/docs/atl/reference/default-atl-project-configurations.md +++ b/docs/atl/reference/default-atl-project-configurations.md @@ -3,10 +3,11 @@ description: "Learn more about: Default ATL Project Configurations" title: "Default ATL Project Configurations" ms.date: "10/20/2017" helpviewer_keywords: ["ATL projects, default configurations"] -ms.assetid: 7e272722-41af-4330-b965-a6d74ec16880 --- # Default ATL Project Configurations +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + The ATL Project Wizard creates two project configurations by default: |Configuration|Character set|Use of ATL| diff --git a/docs/atl/reference/device-context-global-functions.md b/docs/atl/reference/device-context-global-functions.md index 7ef43f0431e..0720fd8042b 100644 --- a/docs/atl/reference/device-context-global-functions.md +++ b/docs/atl/reference/device-context-global-functions.md @@ -3,10 +3,11 @@ description: "Learn more about: Device Context Global Functions" title: "Device Context Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlwin/ATL::AtlCreateTargetDC"] -ms.assetid: 08ec28f6-daff-4882-9544-e8a4639d05c4 --- # Device Context Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This function creates a device context for a given device. |Name|Description| diff --git a/docs/atl/reference/event-handling-global-functions.md b/docs/atl/reference/event-handling-global-functions.md index 69c6f619b65..f5948e23c2d 100644 --- a/docs/atl/reference/event-handling-global-functions.md +++ b/docs/atl/reference/event-handling-global-functions.md @@ -4,10 +4,11 @@ title: "Event Handling Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlWaitWithMessageLoop"] helpviewer_keywords: ["event handling, global functions", "global functions, event handling"] -ms.assetid: fd674470-3def-47c3-be1c-894fa85f13e8 --- # Event Handling Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This function provides an event handler. > [!IMPORTANT] diff --git a/docs/atl/reference/exception-handling-macros.md b/docs/atl/reference/exception-handling-macros.md index 44f99934523..fe201b9e3a1 100644 --- a/docs/atl/reference/exception-handling-macros.md +++ b/docs/atl/reference/exception-handling-macros.md @@ -4,10 +4,11 @@ title: "Exception Handling Macros" ms.date: "11/04/2016" f1_keywords: ["atldef/ATL::_ATLCATCH", "atldef/ATL::_ATLCATCHALL", "atldef/ATL::_ATLTRY", "ATLDEF/_ATLCATCH", "ATLDEF/_ATLCATCHALL", "ATLDEF/_ATLTRY"] helpviewer_keywords: ["exception handling, macros", "C++ exception handling, macros"] -ms.assetid: a8385d34-3fb0-4006-a42a-de045cacf0f4 --- # Exception Handling Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros provide support for exception handling. |Name|Description| diff --git a/docs/atl/reference/iatlautothreadmodule-class.md b/docs/atl/reference/iatlautothreadmodule-class.md index 42df620330a..f83105ba786 100644 --- a/docs/atl/reference/iatlautothreadmodule-class.md +++ b/docs/atl/reference/iatlautothreadmodule-class.md @@ -4,10 +4,11 @@ title: "IAtlAutoThreadModule Class" ms.date: "11/04/2016" f1_keywords: ["IAtlAutoThreadModule", "atlbase/ATL::IAtlAutoThreadModule"] helpviewer_keywords: ["IAtlAutoThreadModule class"] -ms.assetid: fcb58cf9-a427-4be9-89eb-04e1ab5cc3a1 --- # IAtlAutoThreadModule Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents an interface to a `CreateInstance` method. > [!IMPORTANT] diff --git a/docs/atl/reference/iatlmemmgr-class.md b/docs/atl/reference/iatlmemmgr-class.md index 46acd301740..5df51a5cfc1 100644 --- a/docs/atl/reference/iatlmemmgr-class.md +++ b/docs/atl/reference/iatlmemmgr-class.md @@ -4,10 +4,11 @@ title: "IAtlMemMgr Class" ms.date: "11/04/2016" f1_keywords: ["IAtlMemMgr", "ATLMEM/ATL::IAtlMemMgr", "ATLMEM/ATL::Allocate", "ATLMEM/ATL::Free", "ATLMEM/ATL::GetSize", "ATLMEM/ATL::Reallocate"] helpviewer_keywords: ["IAtlMemMgr class", "memory, managing", "memory, memory manager"] -ms.assetid: 18b2c569-25fe-4464-bdb6-3b1abef7154a --- # IAtlMemMgr Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class represents the interface to a memory manager. ## Syntax diff --git a/docs/atl/reference/iaxwinambientdispatch-interface.md b/docs/atl/reference/iaxwinambientdispatch-interface.md index f1799cf5b26..4810d037297 100644 --- a/docs/atl/reference/iaxwinambientdispatch-interface.md +++ b/docs/atl/reference/iaxwinambientdispatch-interface.md @@ -4,10 +4,11 @@ title: "IAxWinAmbientDispatch Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinAmbientDispatch", "ATLIFACE/ATL::IAxWinAmbientDispatch", "ATLIFACE/ATL::get_AllowContextMenu", "ATLIFACE/ATL::get_AllowShowUI", "ATLIFACE/ATL::get_AllowWindowlessActivation", "ATLIFACE/ATL::get_BackColor", "ATLIFACE/ATL::get_DisplayAsDefault", "ATLIFACE/ATL::get_DocHostDoubleClickFlags", "ATLIFACE/ATL::get_DocHostFlags", "ATLIFACE/ATL::get_Font", "ATLIFACE/ATL::get_ForeColor", "ATLIFACE/ATL::get_LocaleID", "ATLIFACE/ATL::get_MessageReflect", "ATLIFACE/ATL::get_OptionKeyPath", "ATLIFACE/ATL::get_ShowGrabHandles", "ATLIFACE/ATL::get_ShowHatching", "ATLIFACE/ATL::get_UserMode", "ATLIFACE/ATL::put_AllowContextMenu", "ATLIFACE/ATL::put_AllowShowUI", "ATLIFACE/ATL::put_AllowWindowlessActivation", "ATLIFACE/ATL::put_BackColor", "ATLIFACE/ATL::put_DisplayAsDefault", "ATLIFACE/ATL::put_DocHostDoubleClickFlags", "ATLIFACE/ATL::put_DocHostFlags", "ATLIFACE/ATL::put_Font", "ATLIFACE/ATL::put_ForeColor", "ATLIFACE/ATL::put_LocaleID", "ATLIFACE/ATL::put_MessageReflect", "ATLIFACE/ATL::put_OptionKeyPath", "ATLIFACE/ATL::put_UserMode"] helpviewer_keywords: ["IAxWinAmbientDispatch interface"] -ms.assetid: 55ba6f7b-7a3c-4792-ae47-c8a84b683ca9 --- # IAxWinAmbientDispatch Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This interface provides methods for specifying characteristics of the hosted control or container. > [!IMPORTANT] diff --git a/docs/atl/reference/iaxwinambientdispatchex-interface.md b/docs/atl/reference/iaxwinambientdispatchex-interface.md index 4df19f4e982..45190ff5ecb 100644 --- a/docs/atl/reference/iaxwinambientdispatchex-interface.md +++ b/docs/atl/reference/iaxwinambientdispatchex-interface.md @@ -4,10 +4,11 @@ title: "IAxWinAmbientDispatchEx Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinAmbientDispatchEx", "ATLIFACE/ATL::IAxWinAmbientDispatchEx", "ATLIFACE/ATL::SetAmbientDispatch"] helpviewer_keywords: ["IAxWinAmbientDispatchEx interface"] -ms.assetid: 2c25e079-6128-4278-bc72-b2c6195ba7ef --- # IAxWinAmbientDispatchEx Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This interface implements supplemental ambient properties for a hosted control. > [!IMPORTANT] diff --git a/docs/atl/reference/iaxwinhostwindow-interface.md b/docs/atl/reference/iaxwinhostwindow-interface.md index 38ea65043d6..9b981a96ee3 100644 --- a/docs/atl/reference/iaxwinhostwindow-interface.md +++ b/docs/atl/reference/iaxwinhostwindow-interface.md @@ -4,10 +4,11 @@ title: "IAxWinHostWindow Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinHostWindow", "ATLIFACE/ATL::IAxWinHostWindow", "ATLIFACE/ATL::AttachControl", "ATLIFACE/ATL::CreateControl", "ATLIFACE/ATL::CreateControlEx", "ATLIFACE/ATL::QueryControl", "ATLIFACE/ATL::SetExternalDispatch", "ATLIFACE/ATL::SetExternalUIHandler"] helpviewer_keywords: ["IAxWinHostWindow interface"] -ms.assetid: 9821c035-cd52-4c46-b58a-9278064f09b4 --- # IAxWinHostWindow Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This interface provides methods for manipulating a control and its host object. > [!IMPORTANT] diff --git a/docs/atl/reference/iaxwinhostwindowlic-interface.md b/docs/atl/reference/iaxwinhostwindowlic-interface.md index e2d65671f24..49479516988 100644 --- a/docs/atl/reference/iaxwinhostwindowlic-interface.md +++ b/docs/atl/reference/iaxwinhostwindowlic-interface.md @@ -4,10 +4,11 @@ title: "IAxWinHostWindowLic Interface" ms.date: "11/04/2016" f1_keywords: ["IAxWinHostWindowLic", "ATLIFACE/ATL::IAxWinHostWindowLic", "ATLIFACE/ATL::CreateControlLic", "ATLIFACE/ATL::CreateControlLicEx"] helpviewer_keywords: ["IAxWinHostWindowLic interface"] -ms.assetid: 750f1520-6bce-428c-aca0-fccbe3f063c7 --- # IAxWinHostWindowLic Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This interface provides methods for manipulating a licensed control and its host object. ## Syntax diff --git a/docs/atl/reference/icollectiononstlimpl-class.md b/docs/atl/reference/icollectiononstlimpl-class.md index 58c7584c398..54377d23a95 100644 --- a/docs/atl/reference/icollectiononstlimpl-class.md +++ b/docs/atl/reference/icollectiononstlimpl-class.md @@ -4,10 +4,11 @@ title: "ICollectionOnSTLImpl Class" ms.date: "11/04/2016" f1_keywords: ["ICollectionOnSTLImpl", "ATLCOM/ATL::ICollectionOnSTLImpl", "ATLCOM/ATL::ICollectionOnSTLImpl::get__NewEnum", "ATLCOM/ATL::ICollectionOnSTLImpl::getcount", "ATLCOM/ATL::ICollectionOnSTLImpl::get_Item", "ATLCOM/ATL::ICollectionOnSTLImpl::m_coll"] helpviewer_keywords: ["ICollectionOnSTLImpl class"] -ms.assetid: 683c88b0-0d97-4779-a762-e493334ba7f9 --- # ICollectionOnSTLImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods used by a collection class. ## Syntax diff --git a/docs/atl/reference/iconnectionpointcontainerimpl-class.md b/docs/atl/reference/iconnectionpointcontainerimpl-class.md index fd6e2362ee3..e7575eb5862 100644 --- a/docs/atl/reference/iconnectionpointcontainerimpl-class.md +++ b/docs/atl/reference/iconnectionpointcontainerimpl-class.md @@ -4,10 +4,11 @@ title: "IConnectionPointContainerImpl Class" ms.date: "11/04/2016" f1_keywords: ["IConnectionPointContainerImpl", "ATLCOM/ATL::IConnectionPointContainerImpl", "ATLCOM/ATL::IConnectionPointContainerImpl::EnumConnectionPoints", "ATLCOM/ATL::IConnectionPointContainerImpl::FindConnectionPoint"] helpviewer_keywords: ["connectable objects", "connection points [C++], container", "IConnectionPointContainerImpl class"] -ms.assetid: 10db5a8d-8be9-4d9d-8a82-8ab9ffe3e9d6 --- # IConnectionPointContainerImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a connection point container to manage a collection of [IConnectionPointImpl](../../atl/reference/iconnectionpointimpl-class.md) objects. ## Syntax diff --git a/docs/atl/reference/iconnectionpointimpl-class.md b/docs/atl/reference/iconnectionpointimpl-class.md index 2b51b7bc46c..01653837946 100644 --- a/docs/atl/reference/iconnectionpointimpl-class.md +++ b/docs/atl/reference/iconnectionpointimpl-class.md @@ -4,10 +4,11 @@ title: "IConnectionPointImpl Class" ms.date: "11/04/2016" f1_keywords: ["IConnectionPointImpl", "ATLCOM/ATL::IConnectionPointImpl", "ATLCOM/ATL::IConnectionPointImpl::Advise", "ATLCOM/ATL::IConnectionPointImpl::EnumConnections", "ATLCOM/ATL::IConnectionPointImpl::GetConnectionInterface", "ATLCOM/ATL::IConnectionPointImpl::GetConnectionPointContainer", "ATLCOM/ATL::IConnectionPointImpl::Unadvise", "ATLCOM/ATL::IConnectionPointImpl::m_vec"] helpviewer_keywords: ["connection points [C++], implementing", "IConnectionPointImpl class"] -ms.assetid: 27992115-3b86-45dd-bc9e-54f32876c557 --- # IConnectionPointImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements a connection point. ## Syntax diff --git a/docs/atl/reference/idataobjectimpl-class.md b/docs/atl/reference/idataobjectimpl-class.md index 3ebc3c44024..66da64d27e2 100644 --- a/docs/atl/reference/idataobjectimpl-class.md +++ b/docs/atl/reference/idataobjectimpl-class.md @@ -4,10 +4,11 @@ title: "IDataObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IDataObjectImpl", "ATLCTL/ATL::IDataObjectImpl", "ATLCTL/ATL::IDataObjectImpl::DAdvise", "ATLCTL/ATL::IDataObjectImpl::DUnadvise", "ATLCTL/ATL::IDataObjectImpl::EnumDAdvise", "ATLCTL/ATL::IDataObjectImpl::EnumFormatEtc", "ATLCTL/ATL::IDataObjectImpl::FireDataChange", "ATLCTL/ATL::IDataObjectImpl::GetCanonicalFormatEtc", "ATLCTL/ATL::IDataObjectImpl::GetData", "ATLCTL/ATL::IDataObjectImpl::GetDataHere", "ATLCTL/ATL::IDataObjectImpl::QueryGetData", "ATLCTL/ATL::IDataObjectImpl::SetData"] helpviewer_keywords: ["data transfer [C++]", "data transfer [C++], Uniform Data Transfer", "IDataObjectImpl class", "IDataObject, ATL implementation"] -ms.assetid: b680f0f7-7795-40a1-a0f6-f48768201c89 --- # IDataObjectImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for supporting Uniform Data Transfer and managing connections. > [!IMPORTANT] diff --git a/docs/atl/reference/idispatchimpl-class.md b/docs/atl/reference/idispatchimpl-class.md index e44623c7625..ee9891c47fb 100644 --- a/docs/atl/reference/idispatchimpl-class.md +++ b/docs/atl/reference/idispatchimpl-class.md @@ -4,10 +4,11 @@ title: "IDispatchImpl Class" ms.date: "11/04/2016" f1_keywords: ["IDispatchImpl", "ATLCOM/ATL::IDispatchImpl", "ATLCOM/ATL::IDispatchImpl::IDispatchImpl", "ATLCOM/ATL::IDispatchImpl::GetIDsOfNames", "ATLCOM/ATL::IDispatchImpl::GetTypeInfo", "ATLCOM/ATL::IDispatchImpl::GetTypeInfoCount", "ATLCOM/ATL::IDispatchImpl::Invoke"] helpviewer_keywords: ["dual interfaces, classes", "IDispatchImpl class", "IDispatch class support in ATL"] -ms.assetid: 8108eb36-1228-4127-a203-3ab5ba488892 --- # IDispatchImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Provides a default implementation for the `IDispatch` part of a dual interface. > [!IMPORTANT] diff --git a/docs/atl/reference/idispeventimpl-class.md b/docs/atl/reference/idispeventimpl-class.md index 74fd3e72c26..fe3cb6578ab 100644 --- a/docs/atl/reference/idispeventimpl-class.md +++ b/docs/atl/reference/idispeventimpl-class.md @@ -1,12 +1,13 @@ --- -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 + +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] This class provides implementations of the `IDispatch` methods. @@ -15,7 +16,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 +55,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 +79,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 +98,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 +120,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 +151,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 +188,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 +200,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 +224,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/idispeventsimpleimpl-class.md b/docs/atl/reference/idispeventsimpleimpl-class.md index c76ceee1297..4224ca90998 100644 --- a/docs/atl/reference/idispeventsimpleimpl-class.md +++ b/docs/atl/reference/idispeventsimpleimpl-class.md @@ -4,10 +4,11 @@ title: "IDispEventSimpleImpl Class" ms.date: "11/04/2016" f1_keywords: ["IDispEventSimpleImpl", "ATLCOM/ATL::IDispEventSimpleImpl", "ATLCOM/ATL::IDispEventSimpleImpl::Advise", "ATLCOM/ATL::IDispEventSimpleImpl::DispEventAdvise", "ATLCOM/ATL::IDispEventSimpleImpl::DispEventUnadvise", "ATLCOM/ATL::IDispEventSimpleImpl::GetIDsOfNames", "ATLCOM/ATL::IDispEventSimpleImpl::GetTypeInfo", "ATLCOM/ATL::IDispEventSimpleImpl::GetTypeInfoCount", "ATLCOM/ATL::IDispEventSimpleImpl::Invoke", "ATLCOM/ATL::IDispEventSimpleImpl::Unadvise"] helpviewer_keywords: ["IDispEventSimpleImpl class"] -ms.assetid: 971d82b7-a921-47fa-a4d8-909bed377ab0 --- # IDispEventSimpleImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides implementations of the `IDispatch` methods, without getting type information from a type library. > [!IMPORTANT] diff --git a/docs/atl/reference/idochostuihandlerdispatch-interface.md b/docs/atl/reference/idochostuihandlerdispatch-interface.md index d748d3e3df2..35749bfb535 100644 --- a/docs/atl/reference/idochostuihandlerdispatch-interface.md +++ b/docs/atl/reference/idochostuihandlerdispatch-interface.md @@ -4,10 +4,11 @@ title: "IDocHostUIHandlerDispatch Interface" ms.date: "07/02/2019" f1_keywords: ["IDocHostUIHandlerDispatch", "atlbase/ATL::IDocHostUIHandlerDispatch"] helpviewer_keywords: ["IDocHostUIHandlerDispatch interface"] -ms.assetid: 6963a301-601a-4ac3-8bef-f7b252ea2fc6 --- # IDocHostUIHandlerDispatch Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + An interface to the Microsoft HTML parsing and rendering engine. > [!IMPORTANT] diff --git a/docs/atl/reference/ienumonstlimpl-class.md b/docs/atl/reference/ienumonstlimpl-class.md index c8c694372a0..99b2f3ab0b2 100644 --- a/docs/atl/reference/ienumonstlimpl-class.md +++ b/docs/atl/reference/ienumonstlimpl-class.md @@ -4,10 +4,11 @@ title: "IEnumOnSTLImpl Class" ms.date: "11/04/2016" f1_keywords: ["IEnumOnSTLImpl", "ATLCOM/ATL::IEnumOnSTLImpl", "ATLCOM/ATL::IEnumOnSTLImpl::Clone", "ATLCOM/ATL::IEnumOnSTLImpl::Init", "ATLCOM/ATL::IEnumOnSTLImpl::Next", "ATLCOM/ATL::IEnumOnSTLImpl::Reset", "ATLCOM/ATL::IEnumOnSTLImpl::Skip", "ATLCOM/ATL::IEnumOnSTLImpl::m_iter", "ATLCOM/ATL::IEnumOnSTLImpl::m_pcollection", "ATLCOM/ATL::IEnumOnSTLImpl::m_spUnk"] helpviewer_keywords: ["IEnumOnSTLImpl class"] -ms.assetid: 1789e77b-88b8-447d-a490-806b918912ce --- # IEnumOnSTLImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class defines an enumerator interface based on a C++ Standard Library collection. ## Syntax diff --git a/docs/atl/reference/interfaces-atl-control-wizard.md b/docs/atl/reference/interfaces-atl-control-wizard.md index 97794e03f9b..f27b167effe 100644 --- a/docs/atl/reference/interfaces-atl-control-wizard.md +++ b/docs/atl/reference/interfaces-atl-control-wizard.md @@ -4,10 +4,11 @@ title: "Interfaces, ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.interfaces"] helpviewer_keywords: ["ATL Control Wizard, interfaces"] -ms.assetid: 971eadcd-6a1e-46f2-b8fe-ee6b53dfe3ea --- # Interfaces, ATL Control Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This page of the wizard identifies the interfaces that the control supports. By default, the supported interfaces are those typically used by most containers. > [!NOTE] diff --git a/docs/atl/reference/iobjectsafetyimpl-class.md b/docs/atl/reference/iobjectsafetyimpl-class.md index dee092995fc..61f7cf4f394 100644 --- a/docs/atl/reference/iobjectsafetyimpl-class.md +++ b/docs/atl/reference/iobjectsafetyimpl-class.md @@ -4,10 +4,11 @@ title: "IObjectSafetyImpl Class" ms.date: "11/04/2016" f1_keywords: ["IObjectSafetyImpl", "ATLCTL/ATL::IObjectSafetyImpl", "ATLCTL/ATL::IObjectSafetyImpl::GetInterfaceSafetyOptions", "ATLCTL/ATL::IObjectSafetyImpl::SetInterfaceSafetyOptions", "ATLCTL/ATL::IObjectSafetyImpl::m_dwCurrentSafety"] helpviewer_keywords: ["controls [ATL], safe", "safe for scripting and initialization (controls)", "IObjectSafety, ATL implementation", "IObjectSafetyImpl class"] -ms.assetid: 64e32082-d910-4a8a-a5bf-ebed9145359d --- # IObjectSafetyImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a default implementation of the `IObjectSafety` interface to allow a client to retrieve and set an object's safety levels. > [!IMPORTANT] diff --git a/docs/atl/reference/iobjectwithsiteimpl-class.md b/docs/atl/reference/iobjectwithsiteimpl-class.md index 5ae9a4b8d7c..3d686a03d63 100644 --- a/docs/atl/reference/iobjectwithsiteimpl-class.md +++ b/docs/atl/reference/iobjectwithsiteimpl-class.md @@ -4,10 +4,11 @@ title: "IObjectWithSiteImpl Class" ms.date: "11/04/2016" f1_keywords: ["IObjectWithSiteImpl", "ATLCOM/ATL::IObjectWithSiteImpl", "ATLCOM/ATL::IObjectWithSiteImpl::GetSite", "ATLCOM/ATL::IObjectWithSiteImpl::SetChildSite", "ATLCOM/ATL::IObjectWithSiteImpl::SetSite", "ATLCOM/ATL::IObjectWithSiteImpl::m_spUnkSite"] helpviewer_keywords: ["IObjectWithSiteImpl class"] -ms.assetid: 4e1f774f-bc3d-45ee-9a1c-c3533a511588 --- # IObjectWithSiteImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods allowing an object to communicate with its site. ## Syntax diff --git a/docs/atl/reference/iolecontrolimpl-class.md b/docs/atl/reference/iolecontrolimpl-class.md index 6dc7d0f8a80..d1e7e97f595 100644 --- a/docs/atl/reference/iolecontrolimpl-class.md +++ b/docs/atl/reference/iolecontrolimpl-class.md @@ -1,13 +1,14 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a default implementation of the `IOleControl` interface and implements `IUnknown`. > [!IMPORTANT] @@ -22,7 +23,7 @@ class IOleControlImpl #### Parameters -*T*
+*T*\ Your class, derived from `IOleControlImpl`. ## Members @@ -76,7 +77,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 +117,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/ioleinplaceactiveobjectimpl-class.md b/docs/atl/reference/ioleinplaceactiveobjectimpl-class.md index 64fcdcd25bf..b275380a09b 100644 --- a/docs/atl/reference/ioleinplaceactiveobjectimpl-class.md +++ b/docs/atl/reference/ioleinplaceactiveobjectimpl-class.md @@ -4,10 +4,11 @@ title: "IOleInPlaceActiveObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleInPlaceActiveObjectImpl", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::ContextSensitiveHelp", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::EnableModeless", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::GetWindow", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::OnDocWindowActivate", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::OnFrameWindowActivate", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::ResizeBorder", "ATLCTL/ATL::IOleInPlaceActiveObjectImpl::TranslateAccelerator"] helpviewer_keywords: ["IOleInPlaceActiveObjectImpl class", "ActiveX controls [C++], communication between container and control", "IOleInPlaceActiveObject, ATL implementation"] -ms.assetid: 44e6cc6d-a2dc-4187-98e3-73cf0320dea9 --- # IOleInPlaceActiveObjectImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides methods for assisting communication between an in-place control and its container. > [!IMPORTANT] diff --git a/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md b/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md index d34f0d80b9b..d4307e69f4c 100644 --- a/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md +++ b/docs/atl/reference/ioleinplaceobjectwindowlessimpl-class.md @@ -4,10 +4,11 @@ title: "IOleInPlaceObjectWindowlessImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleInPlaceObjectWindowlessImpl", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::ContextSensitiveHelp", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::GetDropTarget", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::GetWindow", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::InPlaceDeactivate", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::OnWindowMessage", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::ReactivateAndUndo", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::SetObjectRects", "ATLCTL/ATL::IOleInPlaceObjectWindowlessImpl::UIDeactivate"] helpviewer_keywords: ["IOleInPlaceObjectWindowless, ATL implementation", "activation [C++], ATL", "IOleInPlaceObjectWindowlessImpl class", "ActiveX controls [C++], communication between container and control", "controls [ATL], windowless", "deactivating ATL"] -ms.assetid: a2e0feb4-bc59-4adf-aab2-105457bbdbb4 --- # IOleInPlaceObjectWindowlessImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and provides methods that enable a windowless control to receive window messages and to participate in drag-and-drop operations. > [!IMPORTANT] diff --git a/docs/atl/reference/ioleobjectimpl-class.md b/docs/atl/reference/ioleobjectimpl-class.md index 888f9c0db98..42349e85a20 100644 --- a/docs/atl/reference/ioleobjectimpl-class.md +++ b/docs/atl/reference/ioleobjectimpl-class.md @@ -4,10 +4,11 @@ title: "IOleObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IOleObjectImpl", "ATLCTL/ATL::IOleObjectImpl", "ATLCTL/ATL::IOleObjectImpl::Advise", "ATLCTL/ATL::IOleObjectImpl::Close", "ATLCTL/ATL::IOleObjectImpl::DoVerb", "ATLCTL/ATL::IOleObjectImpl::DoVerbDiscardUndo", "ATLCTL/ATL::IOleObjectImpl::DoVerbHide", "ATLCTL/ATL::IOleObjectImpl::DoVerbInPlaceActivate", "ATLCTL/ATL::IOleObjectImpl::DoVerbOpen", "ATLCTL/ATL::IOleObjectImpl::DoVerbPrimary", "ATLCTL/ATL::IOleObjectImpl::DoVerbShow", "ATLCTL/ATL::IOleObjectImpl::DoVerbUIActivate", "ATLCTL/ATL::IOleObjectImpl::EnumAdvise", "ATLCTL/ATL::IOleObjectImpl::EnumVerbs", "ATLCTL/ATL::IOleObjectImpl::GetClientSite", "ATLCTL/ATL::IOleObjectImpl::GetClipboardData", "ATLCTL/ATL::IOleObjectImpl::GetExtent", "ATLCTL/ATL::IOleObjectImpl::GetMiscStatus", "ATLCTL/ATL::IOleObjectImpl::GetMoniker", "ATLCTL/ATL::IOleObjectImpl::GetUserClassID", "ATLCTL/ATL::IOleObjectImpl::GetUserType", "ATLCTL/ATL::IOleObjectImpl::InitFromData", "ATLCTL/ATL::IOleObjectImpl::IsUpToDate", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbDiscardUndo", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbHide", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbInPlaceActivate", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbOpen", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbShow", "ATLCTL/ATL::IOleObjectImpl::OnPostVerbUIActivate", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbDiscardUndo", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbHide", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbInPlaceActivate", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbOpen", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbShow", "ATLCTL/ATL::IOleObjectImpl::OnPreVerbUIActivate", "ATLCTL/ATL::IOleObjectImpl::SetClientSite", "ATLCTL/ATL::IOleObjectImpl::SetColorScheme", "ATLCTL/ATL::IOleObjectImpl::SetExtent", "ATLCTL/ATL::IOleObjectImpl::SetHostNames", "ATLCTL/ATL::IOleObjectImpl::SetMoniker", "ATLCTL/ATL::IOleObjectImpl::Unadvise", "ATLCTL/ATL::IOleObjectImpl::Update"] helpviewer_keywords: ["ActiveX controls [C++], communication between container and control", "IOleObject, ATL implementation", "IOleObjectImpl class"] -ms.assetid: 59750b2d-1633-4a51-a4c2-6455b6b90c45 --- # IOleObjectImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and is the principal interface through which a container communicates with a control. > [!IMPORTANT] diff --git a/docs/atl/reference/iperpropertybrowsingimpl-class.md b/docs/atl/reference/iperpropertybrowsingimpl-class.md index f81692daec9..c1ca3e087dc 100644 --- a/docs/atl/reference/iperpropertybrowsingimpl-class.md +++ b/docs/atl/reference/iperpropertybrowsingimpl-class.md @@ -4,10 +4,11 @@ title: "IPerPropertyBrowsingImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPerPropertyBrowsingImpl", "ATLCTL/ATL::IPerPropertyBrowsingImpl", "ATLCTL/ATL::IPerPropertyBrowsingImpl::GetDisplayString", "ATLCTL/ATL::IPerPropertyBrowsingImpl::GetPredefinedStrings", "ATLCTL/ATL::IPerPropertyBrowsingImpl::GetPredefinedValue", "ATLCTL/ATL::IPerPropertyBrowsingImpl::MapPropertyToPage"] helpviewer_keywords: ["IPerPropertyBrowsingImpl class", "property pages, accessing information", "IPerPropertyBrowsing, ATL implementation"] -ms.assetid: 0b1a9be3-d242-4767-be69-663a21e4b728 --- # IPerPropertyBrowsingImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and allows a client to access the information in an object's property pages. > [!IMPORTANT] @@ -16,7 +17,6 @@ This class implements `IUnknown` and allows a client to access the information i ## Syntax ``` - template class ATL_NO_VTABLE IPerPropertyBrowsingImpl : public IPerPropertyBrowsing diff --git a/docs/atl/reference/ipersistpropertybagimpl-class.md b/docs/atl/reference/ipersistpropertybagimpl-class.md index b9029c339df..84fb6c38136 100644 --- a/docs/atl/reference/ipersistpropertybagimpl-class.md +++ b/docs/atl/reference/ipersistpropertybagimpl-class.md @@ -4,10 +4,11 @@ title: "IPersistPropertyBagImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPersistPropertyBagImpl", "ATLCOM/ATL::IPersistPropertyBagImpl", "ATLCOM/ATL::IPersistPropertyBagImpl::GetClassID", "ATLCOM/ATL::IPersistPropertyBagImpl::InitNew", "ATLCOM/ATL::IPersistPropertyBagImpl::Load", "ATLCOM/ATL::IPersistPropertyBagImpl::Save"] helpviewer_keywords: ["IPersistPropertyBagImpl class"] -ms.assetid: 712af24d-99f8-40f2-9811-53b3ff6e5b19 --- # IPersistPropertyBagImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and allows an object to save its properties to a client-supplied property bag. > [!IMPORTANT] diff --git a/docs/atl/reference/ipersiststorageimpl-class.md b/docs/atl/reference/ipersiststorageimpl-class.md index 9b8e3de9858..ae95395147b 100644 --- a/docs/atl/reference/ipersiststorageimpl-class.md +++ b/docs/atl/reference/ipersiststorageimpl-class.md @@ -1,13 +1,14 @@ --- -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 +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements the [IPersistStorage](/windows/win32/api/objidl/nn-objidl-ipersiststorage) interface. > [!IMPORTANT] @@ -22,7 +23,7 @@ class ATL_NO_VTABLE IPersistStorageImpl : public IPersistStorage #### Parameters -*T*
+*T*\ Your class, derived from `IPersistStorageImpl`. ## Members @@ -97,7 +98,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 +112,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 +126,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 +140,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 +156,11 @@ Returns S_OK. ### Remarks -See [IPersistStorage:SaveCompleted](/windows/win32/api/objidl/nf-objidl-ipersiststorage-savecompleted) in the Windows SDK. +See [IPersistStorage::SaveCompleted](/windows/win32/api/objidl/nf-objidl-ipersiststorage-savecompleted) in the Windows SDK. ## See also -[Storages and Streams](/windows/win32/Stg/storages-and-streams)
-[IPersistStreamInitImpl Class](../../atl/reference/ipersiststreaminitimpl-class.md)
-[IPersistPropertyBagImpl Class](../../atl/reference/ipersistpropertybagimpl-class.md)
+[Storages and Streams](/windows/win32/Stg/storages-and-streams)\ +[IPersistStreamInitImpl Class](../../atl/reference/ipersiststreaminitimpl-class.md)\ +[IPersistPropertyBagImpl Class](../../atl/reference/ipersistpropertybagimpl-class.md)\ [Class Overview](../../atl/atl-class-overview.md) diff --git a/docs/atl/reference/ipersiststreaminitimpl-class.md b/docs/atl/reference/ipersiststreaminitimpl-class.md index 3eab5ba63c0..cf426de9552 100644 --- a/docs/atl/reference/ipersiststreaminitimpl-class.md +++ b/docs/atl/reference/ipersiststreaminitimpl-class.md @@ -4,10 +4,11 @@ title: "IPersistStreamInitImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPersistStreamInitImpl", "ATLCOM/ATL::IPersistStreamInitImpl", "ATLCOM/ATL::IPersistStreamInitImpl::GetClassID", "ATLCOM/ATL::IPersistStreamInitImpl::GetSizeMax", "ATLCOM/ATL::IPersistStreamInitImpl::InitNew", "ATLCOM/ATL::IPersistStreamInitImpl::IsDirty", "ATLCOM/ATL::IPersistStreamInitImpl::Load", "ATLCOM/ATL::IPersistStreamInitImpl::Save"] helpviewer_keywords: ["IPersistStreamInit ATL implementation", "IPersistStreamInitImpl class", "streams, ATL"] -ms.assetid: ef217c3c-020f-4cf8-871e-ef68e57865b8 --- # IPersistStreamInitImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and provides a default implementation of the [IPersistStreamInit](/windows/win32/api/ocidl/nn-ocidl-ipersiststreaminit) interface. > [!IMPORTANT] diff --git a/docs/atl/reference/ipointerinactiveimpl-class.md b/docs/atl/reference/ipointerinactiveimpl-class.md index 71189491246..ed5fa3495e3 100644 --- a/docs/atl/reference/ipointerinactiveimpl-class.md +++ b/docs/atl/reference/ipointerinactiveimpl-class.md @@ -4,10 +4,11 @@ title: "IPointerInactiveImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPointerInactiveImpl", "ATLCTL/ATL::IPointerInactiveImpl", "ATLCTL/ATL::IPointerInactiveImpl::GetActivationPolicy", "ATLCTL/ATL::IPointerInactiveImpl::OnInactiveMouseMove", "ATLCTL/ATL::IPointerInactiveImpl::OnInactiveSetCursor"] helpviewer_keywords: ["IPointerInactive ATL implementation", "inactive objects", "IPointerInactiveImpl class"] -ms.assetid: e1fe9ea6-d38a-4527-9112-eb344771e0b7 --- # IPointerInactiveImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and the [IPointerInactive](/windows/win32/api/ocidl/nn-ocidl-ipointerinactive) interface methods. > [!IMPORTANT] diff --git a/docs/atl/reference/ipropertynotifysinkcp-class.md b/docs/atl/reference/ipropertynotifysinkcp-class.md index b02d41d33b0..d4a74b402a9 100644 --- a/docs/atl/reference/ipropertynotifysinkcp-class.md +++ b/docs/atl/reference/ipropertynotifysinkcp-class.md @@ -4,10 +4,11 @@ title: "IPropertyNotifySinkCP Class" ms.date: "11/04/2016" f1_keywords: ["IPropertyNotifySinkCP", "atlctl/ATL::IPropertyNotifySinkCP"] helpviewer_keywords: ["connection points [C++], managing", "sinks, notifying of changes", "IPropertyNotifySinkCP class"] -ms.assetid: 1b41445e-bc88-4fa6-bb62-d68aacec2bd5 --- # IPropertyNotifySinkCP Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class exposes [IPropertyNotifySink](/windows/win32/api/ocidl/nn-ocidl-ipropertynotifysink) interface as an outgoing interface on a connectable object. > [!IMPORTANT] diff --git a/docs/atl/reference/ipropertypage2impl-class.md b/docs/atl/reference/ipropertypage2impl-class.md index f39eac4e87e..412048f8778 100644 --- a/docs/atl/reference/ipropertypage2impl-class.md +++ b/docs/atl/reference/ipropertypage2impl-class.md @@ -4,10 +4,11 @@ title: "IPropertyPage2Impl Class" ms.date: "11/04/2016" f1_keywords: ["IPropertyPage2Impl", "ATLCTL/ATL::IPropertyPage2Impl", "ATLCTL/ATL::IPropertyPage2Impl::EditProperty"] helpviewer_keywords: ["property pages", "IPropertyPage2 ATL implementation", "IPropertyPage2Impl class"] -ms.assetid: e89fbe90-203a-47f0-a5de-23616697e1ce --- # IPropertyPage2Impl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and inherits the default implementation of [IPropertyPageImpl](../../atl/reference/ipropertypageimpl-class.md). > [!IMPORTANT] diff --git a/docs/atl/reference/ipropertypageimpl-class.md b/docs/atl/reference/ipropertypageimpl-class.md index 8b217ed0d02..0cd5e4d87bf 100644 --- a/docs/atl/reference/ipropertypageimpl-class.md +++ b/docs/atl/reference/ipropertypageimpl-class.md @@ -4,10 +4,11 @@ title: "IPropertyPageImpl Class" ms.date: "11/04/2016" f1_keywords: ["IPropertyPageImpl", "ATLCTL/ATL::IPropertyPageImpl", "ATLCTL/ATL::IPropertyPageImpl::IPropertyPageImpl", "ATLCTL/ATL::IPropertyPageImpl::Activate", "ATLCTL/ATL::IPropertyPageImpl::Apply", "ATLCTL/ATL::IPropertyPageImpl::Deactivate", "ATLCTL/ATL::IPropertyPageImpl::GetPageInfo", "ATLCTL/ATL::IPropertyPageImpl::Help", "ATLCTL/ATL::IPropertyPageImpl::IsPageDirty", "ATLCTL/ATL::IPropertyPageImpl::Move", "ATLCTL/ATL::IPropertyPageImpl::SetDirty", "ATLCTL/ATL::IPropertyPageImpl::SetObjects", "ATLCTL/ATL::IPropertyPageImpl::SetPageSite", "ATLCTL/ATL::IPropertyPageImpl::Show", "ATLCTL/ATL::IPropertyPageImpl::TranslateAccelerator", "ATLCTL/ATL::IPropertyPageImpl::m_bDirty", "ATLCTL/ATL::IPropertyPageImpl::m_dwDocString", "ATLCTL/ATL::IPropertyPageImpl::m_dwHelpContext", "ATLCTL/ATL::IPropertyPageImpl::m_dwHelpFile", "ATLCTL/ATL::IPropertyPageImpl::m_dwTitle", "ATLCTL/ATL::IPropertyPageImpl::m_nObjects", "ATLCTL/ATL::IPropertyPageImpl::m_pPageSite", "ATLCTL/ATL::IPropertyPageImpl::m_ppUnk", "ATLCTL/ATL::IPropertyPageImpl::m_size"] helpviewer_keywords: ["property pages", "IPropertyPage ATL implementation", "IPropertyPageImpl class"] -ms.assetid: f9b7c8b1-7a04-4eab-aa63-63efddb740fa --- # IPropertyPageImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and provides a default implementation of the [IPropertyPage](/windows/win32/api/ocidl/nn-ocidl-ipropertypage) interface. > [!IMPORTANT] diff --git a/docs/atl/reference/iprovideclassinfo2impl-class.md b/docs/atl/reference/iprovideclassinfo2impl-class.md index c700c6a2809..3115d96f8e1 100644 --- a/docs/atl/reference/iprovideclassinfo2impl-class.md +++ b/docs/atl/reference/iprovideclassinfo2impl-class.md @@ -4,10 +4,11 @@ title: "IProvideClassInfo2Impl Class" ms.date: "11/04/2016" f1_keywords: ["IProvideClassInfo2Impl", "ATLCOM/ATL::IProvideClassInfo2Impl", "ATLCOM/ATL::IProvideClassInfo2Impl::IProvideClassInfo2Impl", "ATLCOM/ATL::IProvideClassInfo2Impl::GetClassInfo", "ATLCOM/ATL::IProvideClassInfo2Impl::GetGUID", "ATLCOM/ATL::IProvideClassInfo2Impl::_tih"] helpviewer_keywords: ["IProvideClassInfo2Impl class", "IProvideClassInfo2 ATL implementation", "class information, ATL"] -ms.assetid: d74956e8-9c69-4cba-b99d-ca1ac031bb9d --- # IProvideClassInfo2Impl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a default implementation of the [IProvideClassInfo](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo) and [IProvideClassInfo2](/windows/win32/api/ocidl/nn-ocidl-iprovideclassinfo2) methods. ## Syntax diff --git a/docs/atl/reference/iquickactivateimpl-class.md b/docs/atl/reference/iquickactivateimpl-class.md index 55d408feadc..88ea87bc8d8 100644 --- a/docs/atl/reference/iquickactivateimpl-class.md +++ b/docs/atl/reference/iquickactivateimpl-class.md @@ -4,10 +4,11 @@ title: "IQuickActivateImpl Class" ms.date: "11/04/2016" f1_keywords: ["IQuickActivateImpl", "ATLCTL/ATL::IQuickActivateImpl", "ATLCTL/ATL::IQuickActivateImpl::GetContentExtent", "ATLCTL/ATL::IQuickActivateImpl::QuickActivate", "ATLCTL/ATL::IQuickActivateImpl::SetContentExtent"] helpviewer_keywords: ["activating ATL controls", "controls [ATL], activating", "IQuickActivateImpl class", "IQuickActivate ATL implementation"] -ms.assetid: aa80c056-1041-494e-b21d-2acca7dc27ea --- # IQuickActivateImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class combines containers' control initialization into a single call. > [!IMPORTANT] diff --git a/docs/atl/reference/iregistrar-class.md b/docs/atl/reference/iregistrar-class.md index 9c3ca2a9805..5f8c8909e23 100644 --- a/docs/atl/reference/iregistrar-class.md +++ b/docs/atl/reference/iregistrar-class.md @@ -4,10 +4,11 @@ title: "IRegistrar Interface" ms.date: "02/01/2017" f1_keywords: ["IRegistrar", "ATLIFASE/ATL::IRegistrar", "ATLIFASE/ATL::IRegistrar::ResourceRegisterSz", "ATLIFASE/ATL::IRegistrar::ResourceUnregisterSz", "ATLIFASE/ATL::IRegistrar::FileRegister", "ATLIFASE/ATL::IRegistrar::FileUnregister", "ATLIFASE/ATL::IRegistrar::StringRegister", "ATLIFASE/ATL::IRegistrar::StringUnregister", "ATLIFASE/ATL::IRegistrar::ResourceRegister", "ATLIFASE/ATL::IRegistrar::ResourceUnregister"] helpviewer_keywords: ["Iregistrar Interface"] -ms.assetid: e88c04b7-0c93-4ae8-aeb9-ecd78f87421e --- # IRegistrar Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This interface is defined in atliface.h and is used internally by CAtlModule member functions such as [UpdateRegistryFromResourceD](catlmodule-class.md#updateregistryfromresourced). ## Syntax diff --git a/docs/atl/reference/irunnableobjectimpl-class.md b/docs/atl/reference/irunnableobjectimpl-class.md index 77b26a50729..ad0058aeb3c 100644 --- a/docs/atl/reference/irunnableobjectimpl-class.md +++ b/docs/atl/reference/irunnableobjectimpl-class.md @@ -4,10 +4,11 @@ title: "IRunnableObjectImpl Class" ms.date: "11/04/2016" f1_keywords: ["IRunnableObjectImpl", "ATLCTL/ATL::IRunnableObjectImpl", "ATLCTL/ATL::IRunnableObjectImpl::GetRunningClass", "ATLCTL/ATL::IRunnableObjectImpl::IsRunning", "ATLCTL/ATL::IRunnableObjectImpl::LockRunning", "ATLCTL/ATL::IRunnableObjectImpl::Run", "ATLCTL/ATL::IRunnableObjectImpl::SetContainedObject"] helpviewer_keywords: ["containers, running controls", "IRunnableObjectImpl class", "IRunnableObject, ATL implementation", "controls [ATL], running", "controls [C++], container running in ATL"] -ms.assetid: 305c7c3b-889e-49dd-aca1-34379c1b9931 --- # IRunnableObjectImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and provides a default implementation of the [IRunnableObject](/windows/win32/api/objidl/nn-objidl-irunnableobject) interface. > [!IMPORTANT] diff --git a/docs/atl/reference/iserviceproviderimpl-class.md b/docs/atl/reference/iserviceproviderimpl-class.md index 6cd8822fddc..682901b2c7d 100644 --- a/docs/atl/reference/iserviceproviderimpl-class.md +++ b/docs/atl/reference/iserviceproviderimpl-class.md @@ -4,10 +4,11 @@ title: "IServiceProviderImpl Class" ms.date: "11/04/2016" f1_keywords: ["IServiceProviderImpl", "ATLCOM/ATL::IServiceProviderImpl", "ATLCOM/ATL::IServiceProviderImpl::QueryService"] helpviewer_keywords: ["IServiceProviderImpl class", "IServiceProvider interface, ATL implementation"] -ms.assetid: 251254d3-c4ce-40d7-aee0-3d676d1d72f2 --- # IServiceProviderImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a default implementation of the `IServiceProvider` interface. ## Syntax diff --git a/docs/atl/reference/ispecifypropertypagesimpl-class.md b/docs/atl/reference/ispecifypropertypagesimpl-class.md index ae7b4481938..5549949feed 100644 --- a/docs/atl/reference/ispecifypropertypagesimpl-class.md +++ b/docs/atl/reference/ispecifypropertypagesimpl-class.md @@ -4,10 +4,11 @@ title: "ISpecifyPropertyPagesImpl Class" ms.date: "11/04/2016" f1_keywords: ["ISpecifyPropertyPagesImpl", "ATLCOM/ATL::ISpecifyPropertyPagesImpl", "ATLCOM/ATL::ISpecifyPropertyPagesImpl::GetPages"] helpviewer_keywords: ["property pages, CLSIDs associated with", "ISpecifyPropertyPages", "ISpecifyPropertyPagesImpl class"] -ms.assetid: 4e4b9795-b656-4d56-9b8c-85941e7731f9 --- # ISpecifyPropertyPagesImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and provides a default implementation of the [ISpecifyPropertyPages](/windows/win32/api/ocidl/nn-ocidl-ispecifypropertypages) interface. > [!IMPORTANT] diff --git a/docs/atl/reference/isupporterrorinfoimpl-class.md b/docs/atl/reference/isupporterrorinfoimpl-class.md index b9146cc6cf8..b9b4bcdb872 100644 --- a/docs/atl/reference/isupporterrorinfoimpl-class.md +++ b/docs/atl/reference/isupporterrorinfoimpl-class.md @@ -4,10 +4,11 @@ title: "ISupportErrorInfoImpl Class" ms.date: "06/13/2019" f1_keywords: ["ISupportErrorInfoImpl", "ATLCOM/ATL::ISupportErrorInfoImpl", "ATLCOM/ATL::ISupportErrorInfoImpl::InterfaceSupportsErrorInfo"] helpviewer_keywords: ["ISupportErrorInfo ATL implementation", "ISupportErrorInfoImpl class", "error information, ATL"] -ms.assetid: e33a4b11-a123-41cf-bcea-7b19743902af --- # ISupportErrorInfoImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides a default implementation of the [ISupportErrorInfo Interface](/windows/win32/api/oaidl/nn-oaidl-isupporterrorinfo) and can be used when only a single interface generates errors on an object. > [!IMPORTANT] diff --git a/docs/atl/reference/ithreadpoolconfig-interface.md b/docs/atl/reference/ithreadpoolconfig-interface.md index 3a3411e1366..1061b138d72 100644 --- a/docs/atl/reference/ithreadpoolconfig-interface.md +++ b/docs/atl/reference/ithreadpoolconfig-interface.md @@ -4,10 +4,11 @@ title: "IThreadPoolConfig Interface" ms.date: "11/04/2016" f1_keywords: ["IThreadPoolConfig", "ATLUTIL/ATL::IThreadPoolConfig", "ATLUTIL/ATL::GetSize", "ATLUTIL/ATL::GetTimeout", "ATLUTIL/ATL::SetSize", "ATLUTIL/ATL::SetTimeout"] helpviewer_keywords: ["IThreadPoolConfig interface"] -ms.assetid: 69e642bf-6925-46e6-9a37-cce52231b1cc --- # IThreadPoolConfig Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This interface provides methods for configuring a thread pool. > [!IMPORTANT] diff --git a/docs/atl/reference/iviewobjecteximpl-class.md b/docs/atl/reference/iviewobjecteximpl-class.md index ad03e3ac103..b2faac4bb81 100644 --- a/docs/atl/reference/iviewobjecteximpl-class.md +++ b/docs/atl/reference/iviewobjecteximpl-class.md @@ -4,10 +4,11 @@ title: "IViewObjectExImpl Class" ms.date: "11/04/2016" f1_keywords: ["IViewObjectExImpl", "ATLCTL/ATL::IViewObjectExImpl", "ATLCTL/ATL::IViewObjectExImpl::Draw", "ATLCTL/ATL::IViewObjectExImpl::Freeze", "ATLCTL/ATL::IViewObjectExImpl::GetAdvise", "ATLCTL/ATL::IViewObjectExImpl::GetColorSet", "ATLCTL/ATL::IViewObjectExImpl::GetExtent", "ATLCTL/ATL::IViewObjectExImpl::GetNaturalExtent", "ATLCTL/ATL::IViewObjectExImpl::GetRect", "ATLCTL/ATL::IViewObjectExImpl::GetViewStatus", "ATLCTL/ATL::IViewObjectExImpl::QueryHitPoint", "ATLCTL/ATL::IViewObjectExImpl::QueryHitRect", "ATLCTL/ATL::IViewObjectExImpl::SetAdvise", "ATLCTL/ATL::IViewObjectExImpl::Unfreeze"] helpviewer_keywords: ["ActiveX controls [C++], drawing", "IViewObjectEx ATL implementation", "advise sinks", "IViewObjectExImpl class"] -ms.assetid: ad6de760-1ee5-4883-b033-ae57beffc369 --- # IViewObjectExImpl Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class implements `IUnknown` and provides default implementations of the [IViewObject](/windows/win32/api/oleidl/nn-oleidl-iviewobject), [IViewObject2](/windows/win32/api/oleidl/nn-oleidl-iviewobject2), and [IViewObjectEx](/windows/win32/api/ocidl/nn-ocidl-iviewobjectex) interfaces. > [!IMPORTANT] diff --git a/docs/atl/reference/iworkerthreadclient-interface.md b/docs/atl/reference/iworkerthreadclient-interface.md index c962eb0cdf8..46cf241e897 100644 --- a/docs/atl/reference/iworkerthreadclient-interface.md +++ b/docs/atl/reference/iworkerthreadclient-interface.md @@ -4,10 +4,11 @@ title: "IWorkerThreadClient Interface" ms.date: "11/04/2016" f1_keywords: ["IWorkerThreadClient", "ATLUTIL/ATL::IWorkerThreadClient", "ATLUTIL/ATL::CloseHandle", "ATLUTIL/ATL::Execute"] helpviewer_keywords: ["IWorkerThreadClient interface"] -ms.assetid: 56f4a2f5-007e-4a33-9e20-05187629f715 --- # IWorkerThreadClient Interface +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + `IWorkerThreadClient` is the interface implemented by clients of the [CWorkerThread](../../atl/reference/cworkerthread-class.md) class. > [!IMPORTANT] diff --git a/docs/atl/reference/making-an-atl-object-noncreatable.md b/docs/atl/reference/making-an-atl-object-noncreatable.md index 6a144323321..cda5e5b2a71 100644 --- a/docs/atl/reference/making-an-atl-object-noncreatable.md +++ b/docs/atl/reference/making-an-atl-object-noncreatable.md @@ -4,10 +4,11 @@ title: "Making an ATL Object Noncreatable" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.ATL.objects"] helpviewer_keywords: ["noncreatable ATL objects", "ATL projects, noncreatable objects"] -ms.assetid: 80d0bca2-dea0-4801-9a85-6243124437f6 --- # Making an ATL Object Noncreatable +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + You can change the attributes of an ATL-based COM object so that a client cannot directly create the object. In this case, the object would be returned through a method call on another object rather than created directly. ## To make an object noncreatable diff --git a/docs/atl/reference/marshaling-global-functions.md b/docs/atl/reference/marshaling-global-functions.md index 74ec8bf7143..721a8e52101 100644 --- a/docs/atl/reference/marshaling-global-functions.md +++ b/docs/atl/reference/marshaling-global-functions.md @@ -3,10 +3,11 @@ description: "Learn more about: Marshaling Global Functions" title: "Marshaling Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlFreeMarshalStream", "atlbase/ATL::AtlMarshalPtrInProc", "atlbase/ATL::AtlUnmarshalPtr"] -ms.assetid: 877100b5-6ad9-44c5-a2e0-09414f1720d0 --- # Marshaling Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for marshaling and converting marshaling data into interface pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/message-map-macros-atl.md b/docs/atl/reference/message-map-macros-atl.md index 99775caee56..b94fb021afd 100644 --- a/docs/atl/reference/message-map-macros-atl.md +++ b/docs/atl/reference/message-map-macros-atl.md @@ -3,10 +3,11 @@ description: "Learn more about: Message Map Macros (ATL)" title: "Message Map Macros (ATL)" ms.date: "11/04/2016" f1_keywords: ["atlwin/ATL::ALT_MSG_MAP", "atlwin/ATL::BEGIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_ALT", "atlwin/ATL::CHAIN_MSG_MAP_ALT_MEMBER", "atlwin/ATL::CHAIN_MSG_MAP", "atlwin/ATL::CHAIN_MSG_MAP_DYNAMIC", "atlwin/ATL::CHAIN_MSG_MAP_MEMBER", "atlwin/ATL::COMMAND_CODE_HANDLER", "atlwin/ATL::COMMAND_HANDLER", "atlwin/ATL::COMMAND_ID_HANDLER", "atlwin/ATL::COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::COMMAND_RANGE_HANDLER", "atlwin/ATL::DECLARE_EMPTY_MSG_MAP", "atlwin/ATL::DEFAULT_REFLECTION_HANDLER", "atlwin/ATL::END_MSG_MAP", "atlwin/ATL::FORWARD_NOTIFICATIONS", "atlwin/ATL::MESSAGE_HANDLER", "atlwin/ATL::MESSAGE_RANGE_HANDLER", "atlwin/ATL::NOTIFY_CODE_HANDLER", "atlwin/ATL::NOTIFY_HANDLER", "atlwin/ATL::NOTIFY_ID_HANDLER", "atlwin/ATL::NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::NOTIFY_RANGE_HANDLER", "atlwin/ATL::REFLECT_NOTIFICATIONS", "atlwin/ATL::REFLECTED_COMMAND_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_ID_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_COMMAND_RANGE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_ID_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "atlwin/ATL::REFLECTED_NOTIFY_RANGE_HANDLER", "ATLWIN/ALT_MSG_MAP", "ATLWIN/BEGIN_MSG_MAP", "ATLWIN/CHAIN_MSG_MAP_ALT", "ATLWIN/CHAIN_MSG_MAP_ALT_MEMBER", "ATLWIN/CHAIN_MSG_MAP", "ATLWIN/CHAIN_MSG_MAP_DYNAMIC", "ATLWIN/CHAIN_MSG_MAP_MEMBER", "ATLWIN/COMMAND_CODE_HANDLER", "ATLWIN/COMMAND_HANDLER", "ATLWIN/COMMAND_ID_HANDLER", "ATLWIN/COMMAND_RANGE_CODE_HANDLER", "ATLWIN/COMMAND_RANGE_HANDLER", "ATLWIN/DECLARE_EMPTY_MSG_MAP", "ATLWIN/DEFAULT_REFLECTION_HANDLER", "ATLWIN/END_MSG_MAP", "ATLWIN/FORWARD_NOTIFICATIONS", "ATLWIN/MESSAGE_HANDLER", "ATLWIN/MESSAGE_RANGE_HANDLER", "ATLWIN/NOTIFY_CODE_HANDLER", "ATLWIN/NOTIFY_HANDLER", "ATLWIN/NOTIFY_ID_HANDLER", "ATLWIN/NOTIFY_RANGE_CODE_HANDLER", "ATLWIN/NOTIFY_RANGE_HANDLER", "ATLWIN/REFLECT_NOTIFICATIONS", "ATLWIN/REFLECTED_COMMAND_CODE_HANDLER", "ATLWIN/REFLECTED_COMMAND_HANDLER", "ATLWIN/REFLECTED_COMMAND_ID_HANDLER", "ATLWIN/REFLECTED_COMMAND_RANGE_CODE_HANDLER", "ATLWIN/REFLECTED_COMMAND_RANGE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_CODE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_HANDLER", "ATLWIN/REFLECTED_NOTIFY_ID_HANDLER", "ATLWIN/REFLECTED_NOTIFY_RANGE_CODE_HANDLER", "ATLWIN/REFLECTED_NOTIFY_RANGE_HANDLER"] -ms.assetid: eefdd546-8934-4a30-b263-9c06a8addcbd --- # Message Map Macros (ATL) +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define message maps and entries. |Name|Description| diff --git a/docs/atl/reference/mfc-support-in-atl-projects.md b/docs/atl/reference/mfc-support-in-atl-projects.md index c02e7ad566b..faa1b174097 100644 --- a/docs/atl/reference/mfc-support-in-atl-projects.md +++ b/docs/atl/reference/mfc-support-in-atl-projects.md @@ -4,10 +4,12 @@ title: "MFC Support in ATL Projects" ms.date: "11/04/2016" f1_keywords: ["vc.atl.addmfc"] helpviewer_keywords: ["ATL projects, MFC support"] -ms.assetid: f90b4276-cb98-4c11-902c-9ebcfe6f954b --- # MFC Support in ATL Projects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library and Active Template Library (ATL) continue to be supported. However, we're no longer adding features or updating the documentation. + If you select **Support MFC** in the ATL Project Wizard, your project declares the application as an MFC application object (class). The project initializes the MFC library and instantiates a class (class *ProjName*) that is derived from [CWinApp](../../mfc/reference/cwinapp-class.md). This option is available for nonattributed ATL DLL projects only. diff --git a/docs/atl/reference/object-map-macros.md b/docs/atl/reference/object-map-macros.md index e0d53e8236d..aec214fd6db 100644 --- a/docs/atl/reference/object-map-macros.md +++ b/docs/atl/reference/object-map-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: Object Map Macros" title: "Object Map Macros" ms.date: "11/04/2016" f1_keywords: ["atlcom/ATL::DECLARE_OBJECT_DESCRIPTION", "atlcom/ATL::OBJECT_ENTRY_AUTO", "atlcom/ATL::OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO", "ATLCOM/DECLARE_OBJECT_DESCRIPTION", "ATLCOM/OBJECT_ENTRY_AUTO", "ATLCOM/OBJECT_ENTRY_NON_CREATEABLE_EX_AUTO"] -ms.assetid: 680087f4-9894-41dd-a79c-6f337e1f13c1 --- # Object Map Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define object maps and entries. |Name|Description| diff --git a/docs/atl/reference/object-status-macros.md b/docs/atl/reference/object-status-macros.md index 06a9bdb39fc..124d32d8e17 100644 --- a/docs/atl/reference/object-status-macros.md +++ b/docs/atl/reference/object-status-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: Object Status Macros" title: "Object Status Macros" ms.date: "11/04/2016" f1_keywords: ["atlcom/ATL::DECLARE_OLEMISC_STATUS", "ATLCOM/DECLARE_OLEMISC_STATUS"] -ms.assetid: 727dbef2-a342-4157-9d64-a421805d9747 --- # Object Status Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This macro sets flags belonging to ActiveX controls. |Name|Description| diff --git a/docs/atl/reference/options-atl-active-server-page-component-wizard.md b/docs/atl/reference/options-atl-active-server-page-component-wizard.md index ee4d74799fe..7def4310f65 100644 --- a/docs/atl/reference/options-atl-active-server-page-component-wizard.md +++ b/docs/atl/reference/options-atl-active-server-page-component-wizard.md @@ -4,10 +4,11 @@ title: "Options, ATL Active Server Page Component Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.asp.options"] helpviewer_keywords: ["ATL Active Server Page Component Wizard, options"] -ms.assetid: 54f34e26-53c7-4456-9675-cb86e356bde0 --- # Options, ATL Active Server Page Component Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this page of the ATL Active Server Page Component Wizard to design for increased efficiency and error support for the object. For more information on ATL projects and ATL COM classes, see [ATL COM Desktop Components](../../atl/atl-com-desktop-components.md). diff --git a/docs/atl/reference/options-atl-control-wizard.md b/docs/atl/reference/options-atl-control-wizard.md index b6ec7ec9d06..b2656d02218 100644 --- a/docs/atl/reference/options-atl-control-wizard.md +++ b/docs/atl/reference/options-atl-control-wizard.md @@ -4,10 +4,11 @@ title: "Options, ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.options"] helpviewer_keywords: ["ATL Control Wizard, options"] -ms.assetid: 4607c51a-992d-433e-9281-919c6f519a3d --- # Options, ATL Control Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this page of the wizard to define the type of control you are creating and the level of interface support it contains. ## UIElement List diff --git a/docs/atl/reference/options-atl-property-page-wizard.md b/docs/atl/reference/options-atl-property-page-wizard.md index a49caf9d072..cbf30f158dc 100644 --- a/docs/atl/reference/options-atl-property-page-wizard.md +++ b/docs/atl/reference/options-atl-property-page-wizard.md @@ -4,10 +4,11 @@ title: "Options, ATL Property Page Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.ppg.options"] helpviewer_keywords: ["ATL Property Page Wizard, options"] -ms.assetid: a7107779-b2ea-4f99-b84b-7f3e0c504bc8 --- # Options, ATL Property Page Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/options-atl-simple-object-wizard.md b/docs/atl/reference/options-atl-simple-object-wizard.md index a15ab0eccc0..b3e62ebf15c 100644 --- a/docs/atl/reference/options-atl-simple-object-wizard.md +++ b/docs/atl/reference/options-atl-simple-object-wizard.md @@ -4,10 +4,11 @@ title: "Options, ATL Simple Object Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.simple.options"] helpviewer_keywords: ["ATL Simple Object Wizard, options"] -ms.assetid: 125fe179-942d-4181-8b82-33e92e1fd779 --- # Options, ATL Simple Object Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Use this page of the ATL Simple Object Wizard to design for increased efficiency and error support for the object. For more information on ATL projects and ATL COM classes, see [ATL COM Desktop Components](../../atl/atl-com-desktop-components.md). diff --git a/docs/atl/reference/pixel-himetric-conversion-global-functions.md b/docs/atl/reference/pixel-himetric-conversion-global-functions.md index 3e1c7e9264d..19634eccdff 100644 --- a/docs/atl/reference/pixel-himetric-conversion-global-functions.md +++ b/docs/atl/reference/pixel-himetric-conversion-global-functions.md @@ -3,10 +3,11 @@ description: "Learn more about: Pixel/HIMETRIC Conversion Global Functions" title: "Pixel-HIMETRIC Conversion Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlwin/ATL::AtlHiMetricToPixel", "atlwin/ATL::AtlPixelToHiMetric"] -ms.assetid: ecb1b1b2-7e9d-4fbc-a855-16252d2d794c --- # Pixel/HIMETRIC Conversion Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for converting to and from pixel and HIMETRIC units. > [!IMPORTANT] diff --git a/docs/atl/reference/property-map-macros.md b/docs/atl/reference/property-map-macros.md index a871dd49ab6..1556a46baaf 100644 --- a/docs/atl/reference/property-map-macros.md +++ b/docs/atl/reference/property-map-macros.md @@ -4,10 +4,11 @@ title: "Property Map Macros" ms.date: "11/04/2016" f1_keywords: ["atlcom/ATL::BEGIN_PROP_MAP", "atlcom/ATL::PROP_DATA_ENTRY", "atlcom/ATL::PROP_ENTRY_TYPE", "atlcom/ATL::PROP_ENTRY_TYPE_EX", "atlcom/ATL::PROP_PAGE", "atlcom/ATL::END_PROP_MAP", "ATLCOM/BEGIN_PROP_MAP", "ATLCOM/PROP_DATA_ENTRY", "ATLCOM/PROP_ENTRY_TYPE", "ATLCOM/PROP_ENTRY_TYPE_EX", "ATLCOM/PROP_PAGE", "ATLCOM/END_PROP_MAP"] helpviewer_keywords: ["property maps"] -ms.assetid: 128bc742-2b98-4b97-a243-684dbb83db77 --- # Property Map Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define property maps and entries. |Name|Description| @@ -78,7 +79,7 @@ When you create an ActiveX control, the wizard inserts this macro after the prop In the following example, the extent of the object (`m_sizeExtent`) is being persisted. [!code-cpp[NVC_ATL_Windowing#131](../../atl/codesnippet/cpp/property-map-macros_2.h)] - +  [!code-cpp[NVC_ATL_Windowing#132](../../atl/codesnippet/cpp/property-map-macros_3.h)] ## PROP_ENTRY_TYPE diff --git a/docs/atl/reference/registry-and-typelib-global-functions.md b/docs/atl/reference/registry-and-typelib-global-functions.md index c97812f48d0..74287bfd26f 100644 --- a/docs/atl/reference/registry-and-typelib-global-functions.md +++ b/docs/atl/reference/registry-and-typelib-global-functions.md @@ -4,10 +4,11 @@ title: "Registry and TypeLib Global Functions" ms.date: "03/27/2019" f1_keywords: ["atlbase/ATL::AtlGetPerUserRegistration", "afxpriv/ATL::AfxRegCreateKey", "afxpriv/ATL::AfxRegDeleteKey", "atlbase/ATL::AtlRegisterTypeLib", "afxpriv/ATL::AfxRegOpenKey", "afxpriv/ATL::AfxRegOpenKeyEx", "afxdisp/ATL::AfxUnregisterPreviewHandler", "atlbase/ATL::AtlSetPerUserRegistration", "atlbase/ATL::AtlUnRegisterTypeLib", "atlbase/ATL::AtlLoadTypeLib", "atlbase/ATL::AtlUpdateRegistryFromResourceD", "atlbase/ATL::RegistryDataExchange"] helpviewer_keywords: ["RegistryDataExchange function, global functions"] -ms.assetid: d58b8a4e-975c-4417-8b34-d3c847f679b3 --- # Registry and TypeLib Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for loading and registering a type library. > [!IMPORTANT] diff --git a/docs/atl/reference/registry-data-exchange-macros.md b/docs/atl/reference/registry-data-exchange-macros.md index 98857707a31..76afbece908 100644 --- a/docs/atl/reference/registry-data-exchange-macros.md +++ b/docs/atl/reference/registry-data-exchange-macros.md @@ -4,10 +4,11 @@ title: "Registry Data Exchange Macros" ms.date: "11/04/2016" f1_keywords: ["atlplus/ATL::BEGIN_RDX_MAP", "atlplus/ATL::END_RDX_MAP", "atlplus/ATL::RDX_BINARY", "atlplus/ATL::RDX_CSTRING_TEXT", "atlplus/ATL::RDX_DWORD", "atlplus/ATL::RDX_TEXT", "ATLPLUS/BEGIN_RDX_MAP", "ATLPLUS/END_RDX_MAP", "ATLPLUS/RDX_BINARY", "ATLPLUS/RDX_CSTRING_TEXT", "ATLPLUS/RDX_DWORD", "ATLPLUS/RDX_TEXT"] helpviewer_keywords: ["RegistryDataExchange function, macros"] -ms.assetid: c1bc5e79-2307-43d2-9d10-3a62ffadf473 --- # Registry Data Exchange Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros perform Registry Data Exchange operations. |Name|Description| diff --git a/docs/atl/reference/registry-macros.md b/docs/atl/reference/registry-macros.md index f18617f0fe5..1d5b75f746f 100644 --- a/docs/atl/reference/registry-macros.md +++ b/docs/atl/reference/registry-macros.md @@ -4,10 +4,11 @@ title: "Registry Macros" ms.date: "08/19/2019" f1_keywords: ["ATLBASE/_ATL_STATIC_REGISTRY", "ATLBASE/DECLARE_LIBID", "ATLBASE/DECLARE_NO_REGISTRY", "ATLBASE/DECLARE_REGISTRY", "ATLBASE/DECLARE_REGISTRY_APPID_RESOURCEID", "ATLBASE/DECLARE_REGISTRY_RESOURCE", "ATLBASE/DECLARE_REGISTRY_RESOURCEID", "_ATL_STATIC_REGISTRY", "DECLARE_LIBID", "DECLARE_NO_REGISTRY", "DECLARE_REGISTRY", "DECLARE_REGISTRY_APPID_RESOURCEID", "DECLARE_REGISTRY_RESOURCE", "DECLARE_REGISTRY_RESOURCEID"] helpviewer_keywords: ["registry, ATL macros"] -ms.assetid: 3ee041da-c63b-42a4-89cf-2a4b2a6f81ae --- # Registry Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define useful type library and registry facilities. |Name|Description| diff --git a/docs/atl/reference/security-global-functions.md b/docs/atl/reference/security-global-functions.md index e42bcb30f72..25ea04d962f 100644 --- a/docs/atl/reference/security-global-functions.md +++ b/docs/atl/reference/security-global-functions.md @@ -4,10 +4,11 @@ title: "Security Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlsecurity/ATL::AtlGetDacl", "atlsecurity/ATL::AtlSetDacl", "atlsecurity/ATL::AtlGetGroupSid", "atlsecurity/ATL::AtlSetGroupSid", "atlsecurity/ATL::AtlGetOwnerSid", "atlsecurity/ATL::AtlSetOwnerSid", "atlsecurity/ATL::AtlGetSacl", "atlsecurity/ATL::AtlSetSacl", "atlsecurity/ATL::AtlGetSecurityDescriptor"] helpviewer_keywords: ["SIDs [C++], modifying SID objects", "ACL object global functions", "security IDs [C++]"] -ms.assetid: 6a584bfe-16b7-47f4-8439-9c789c41567a --- # Security Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for modifying SID and ACL objects. > [!IMPORTANT] diff --git a/docs/atl/reference/security-identifier-global-functions.md b/docs/atl/reference/security-identifier-global-functions.md index d429e27b2a4..c390c7f3951 100644 --- a/docs/atl/reference/security-identifier-global-functions.md +++ b/docs/atl/reference/security-identifier-global-functions.md @@ -4,10 +4,11 @@ title: "Security Identifier Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlsecurity/ATL::Sids::AccountOps", "atlsecurity/ATL::Sids::Admins", "atlsecurity/ATL::Sids::AnonymousLogon", "atlsecurity/ATL::Sids::AuthenticatedUser", "atlsecurity/ATL::Sids::BackupOps", "atlsecurity/ATL::Sids::Batch", "atlsecurity/ATL::Sids::CreatorGroup", "atlsecurity/ATL::Sids::CreatorGroupServer", "atlsecurity/ATL::Sids::CreatorOwner", "atlsecurity/ATL::Sids::CreatorOwnerServer", "atlsecurity/ATL::Sids::Dialup", "atlsecurity/ATL::Sids::Guests", "atlsecurity/ATL::Sids::Interactive", "atlsecurity/ATL::Sids::Local", "atlsecurity/ATL::Sids::Network", "atlsecurity/ATL::Sids::NetworkService", "atlsecurity/ATL::Sids::Null", "atlsecurity/ATL::Sids::PowerUsers", "atlsecurity/ATL::Sids::PrintOps", "atlsecurity/ATL::Sids::Proxy", "atlsecurity/ATL::Sids::RasServers", "atlsecurity/ATL::Sids::Replicator", "atlsecurity/ATL::Sids::RestrictedCode", "atlsecurity/ATL::Sids::Self", "atlsecurity/ATL::Sids::ServerLogon", "atlsecurity/ATL::Sids::Service", "atlsecurity/ATL::Sids::System", "atlsecurity/ATL::Sids::SystemOps", "atlsecurity/ATL::Sids::TerminalServer", "atlsecurity/ATL::Sids::Users", "atlsecurity/ATL::Sids::World"] helpviewer_keywords: ["security IDs [C++]", "SIDs [C++], returning SID objects"] -ms.assetid: 85404dcb-c59b-4535-ab3d-66cfa37e87de --- # Security Identifier Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions return common well-known SID objects. > [!IMPORTANT] diff --git a/docs/atl/reference/server-registration-global-functions.md b/docs/atl/reference/server-registration-global-functions.md index 4277c7c13a8..084c2b5257e 100644 --- a/docs/atl/reference/server-registration-global-functions.md +++ b/docs/atl/reference/server-registration-global-functions.md @@ -3,10 +3,11 @@ description: "Learn more about: Server Registration Global Functions" title: "Server Registration Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlComModuleRegisterServer", "atlbase/ATL::AtlComModuleUnregisterServer", "atlbase/ATL::AtlComModuleRegisterClassObjects", "atlbase/ATL::AtlComModuleRevokeClassObjects", "atlbase/ATL::AtlComModuleGetClassObject"] -ms.assetid: c2f0a35d-857c-4538-a44d-c4ea0db63b06 --- # Server Registration Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for registering and unregistering server objects in the object map. > [!IMPORTANT] diff --git a/docs/atl/reference/service-map-macros.md b/docs/atl/reference/service-map-macros.md index b42010306af..923b3b80708 100644 --- a/docs/atl/reference/service-map-macros.md +++ b/docs/atl/reference/service-map-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: Service Map Macros" title: "Service Map Macros" ms.date: "11/04/2016" f1_keywords: ["atlcom/ATL::BEGIN_SERVICE_MAP", "atlcom/ATL::END_SERVICE_MAP", "atlcom/ATL::SERVICE_ENTRY", "atlcom/ATL::SERVICE_ENTRY_CHAIN", "ATLCOM/BEGIN_SERVICE_MAP", "ATLCOM/END_SERVICE_MAP", "ATLCOM/SERVICE_ENTRY", "ATLCOM/SERVICE_ENTRY_CHAIN"] -ms.assetid: ca02a125-454a-4cf6-aac2-1c5585025ed4 --- # Service Map Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define service maps and entries. |Name|Description| diff --git a/docs/atl/reference/snap-in-object-macros.md b/docs/atl/reference/snap-in-object-macros.md index 380f4cf1169..d4a210f6777 100644 --- a/docs/atl/reference/snap-in-object-macros.md +++ b/docs/atl/reference/snap-in-object-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: Snap-In Object Macros" title: "Snap-In Object Macros" ms.date: "11/04/2016" f1_keywords: ["atlsnap/ATL::BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::BEGIN_SNAPINTOOLBARID_MAP", "atlsnap/ATL::END_EXTENSION_SNAPIN_NODEINFO_MAP", "atlsnap/ATL::END_SNAPINTOOLBARID_MAP", "atlsnap/ATL::EXTENSION_SNAPIN_DATACLASS", "atlsnap/ATL::EXTENSION_SNAPIN_NODEINFO_ENTRY", "atlsnap/ATL::SNAPINMENUID", "atlsnap/ATL::SNAPINTOOLBARID_ENTRY", "ATLSNAP/BEGIN_EXTENSION_SNAPIN_NODEINFO_MAP", "ATLSNAP/BEGIN_SNAPINTOOLBARID_MAP", "ATLSNAP/END_EXTENSION_SNAPIN_NODEINFO_MAP", "ATLSNAP/END_SNAPINTOOLBARID_MAP", "ATLSNAP/EXTENSION_SNAPIN_DATACLASS", "ATLSNAP/EXTENSION_SNAPIN_NODEINFO_ENTRY", "ATLSNAP/SNAPINMENUID", "ATLSNAP/SNAPINTOOLBARID_ENTRY"] -ms.assetid: 4e9850c0-e395-4929-86c9-584a81828053 --- # Snap-In Object Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros provide support for snap-in extensions. |Name|Description| diff --git a/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md b/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md index c59923486a7..faaa0a50052 100644 --- a/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md +++ b/docs/atl/reference/specifying-compiler-optimization-for-an-atl-project.md @@ -4,10 +4,11 @@ title: "Specifying Compiler Optimization for an ATL Project" ms.date: "08/19/2019" f1_keywords: ["vc.appwiz.ATL.optimization", "vc.appwiz.ATL.vtable"] helpviewer_keywords: ["ATL_DISABLE_NO_VTABLE macro", "ATL projects, compiler optimization", "ATL_NO_VTABLE macro"] -ms.assetid: 7f379318-66d5-43dd-a53d-530758d3a228 --- # Specifying Compiler Optimization for an ATL Project +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + By default, the [ATL Control Wizard](../../atl/reference/atl-control-wizard.md) generates new classes with the ATL_NO_VTABLE macro, as follows: ``` diff --git a/docs/atl/reference/stock-properties-atl-control-wizard.md b/docs/atl/reference/stock-properties-atl-control-wizard.md index d71b29f1d24..b5e748c87a7 100644 --- a/docs/atl/reference/stock-properties-atl-control-wizard.md +++ b/docs/atl/reference/stock-properties-atl-control-wizard.md @@ -3,10 +3,11 @@ description: "Learn more about: Stock Properties, ATL Control Wizard" title: "Stock Properties, ATL Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.class.atl.control.stockprops"] -ms.assetid: b27b0e60-08a6-43f4-ba6e-0a4e45147693 --- # Stock Properties, ATL Control Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This page of the wizard identifies the stock properties supported for the control. By default, no properties are identified. - **Not supported** diff --git a/docs/atl/reference/string-conversion-macros.md b/docs/atl/reference/string-conversion-macros.md index 9b67e45e5f2..34e484087c7 100644 --- a/docs/atl/reference/string-conversion-macros.md +++ b/docs/atl/reference/string-conversion-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: String Conversion Macros" title: "String Conversion Macros" ms.date: "11/04/2016" f1_keywords: ["atlconv/ATL::DEVMODEA2W", "atlconv/ATL::TEXTMETRICA2W", "atlconv/ATL::DEVMODEOLE2T", "atlconv/ATL::TEXTMETRICOLE2T", "atlconv/ATL::DEVMODET2OLE", "atlconv/ATL::TEXTMETRICT2OLE", "atlconv/ATL::DEVMODEW2A", "atlconv/ATL::TEXTMETRICW2A", "ATLCONV/DEVMODEA2W", "ATLCONV/TEXTMETRICA2W", "ATLCONV/DEVMODEOLE2T", "ATLCONV/TEXTMETRICOLE2T", "ATLCONV/DEVMODET2OLE", "ATLCONV/TEXTMETRICT2OLE", "ATLCONV/DEVMODEW2A", "ATLCONV/TEXTMETRICW2A"] -ms.assetid: 2ff7c0b6-2bde-45fe-897f-6128e18e0c27 --- # String Conversion Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros provide string conversion features. ## ATL and MFC String Conversion Macros diff --git a/docs/atl/reference/strings-atl-property-page-wizard.md b/docs/atl/reference/strings-atl-property-page-wizard.md index af7682dd9f2..c9ed6e81a2a 100644 --- a/docs/atl/reference/strings-atl-property-page-wizard.md +++ b/docs/atl/reference/strings-atl-property-page-wizard.md @@ -4,10 +4,11 @@ title: "Strings, ATL Property Page Wizard" ms.date: "05/09/2019" f1_keywords: ["vc.codewiz.class.atl.ppg.strings"] helpviewer_keywords: ["ATL Property Page Wizard, strings"] -ms.assetid: 00547db6-911f-49eb-92e1-2ba67079d4df --- # Strings, ATL Property Page Wizard +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + ::: moniker range=">=msvc-160" The ATL Property Page wizard is not available in Visual Studio 2019 and later. diff --git a/docs/atl/reference/u-menuorid-class.md b/docs/atl/reference/u-menuorid-class.md index cd2b60ec3e5..f20de6ecfa3 100644 --- a/docs/atl/reference/u-menuorid-class.md +++ b/docs/atl/reference/u-menuorid-class.md @@ -4,10 +4,11 @@ title: "_U_MENUorID Class" ms.date: "11/04/2016" f1_keywords: ["ATL._U_MENUorID", "ATL::_U_MENUorID", "_U_MENUorID"] helpviewer_keywords: ["U_MENUorID class", "_U_MENUorID class"] -ms.assetid: cfc8032b-61b4-4a68-ba3a-92b82500ccae --- # _U_MENUorID Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides wrappers for `CreateWindow` and `CreateWindowEx`. > [!IMPORTANT] diff --git a/docs/atl/reference/u-rect-class.md b/docs/atl/reference/u-rect-class.md index 515c8add351..2a86016dd22 100644 --- a/docs/atl/reference/u-rect-class.md +++ b/docs/atl/reference/u-rect-class.md @@ -4,10 +4,11 @@ title: "_U_RECT Class" ms.date: "11/04/2016" f1_keywords: ["ATL::_U_RECT", "_U_RECT", "ATL._U_RECT"] helpviewer_keywords: ["U_RECT class", "_U_RECT class"] -ms.assetid: 5f880a2d-09cf-4327-bf32-a3519c4dcd63 --- # _U_RECT Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This argument adapter class allows either `RECT` pointers or references to be passed to a function that is implemented in terms of pointers. > [!IMPORTANT] diff --git a/docs/atl/reference/u-stringorid-class.md b/docs/atl/reference/u-stringorid-class.md index d7148ff89ca..84488cd8aea 100644 --- a/docs/atl/reference/u-stringorid-class.md +++ b/docs/atl/reference/u-stringorid-class.md @@ -4,10 +4,11 @@ title: "_U_STRINGorID Class" ms.date: "11/04/2016" f1_keywords: ["ATL._U_STRINGorID", "ATL::_U_STRINGorID", "_U_STRINGorID"] helpviewer_keywords: ["_U_STRINGorID class", "U_STRINGorID class"] -ms.assetid: 443cdc00-d265-4b27-8ef3-2feb95f3e5e3 --- # _U_STRINGorID Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This argument adapter class allows either resource names (LPCTSTRs) or resource IDs (UINTs) to be passed to a function without requiring the caller to convert the ID to a string using the MAKEINTRESOURCE macro. > [!IMPORTANT] diff --git a/docs/atl/reference/win32threadtraits-class.md b/docs/atl/reference/win32threadtraits-class.md index 2d4f1fa008f..321d51e832c 100644 --- a/docs/atl/reference/win32threadtraits-class.md +++ b/docs/atl/reference/win32threadtraits-class.md @@ -4,10 +4,11 @@ title: "Win32ThreadTraits Class" ms.date: "11/04/2016" f1_keywords: ["Win32ThreadTraits", "ATLBASE/ATL::Win32ThreadTraits", "ATLBASE/ATL::Win32ThreadTraits::CreateThread"] helpviewer_keywords: ["threading [ATL], Windows threads", "threading [ATL], creation functions", "Win32ThreadTraits class"] -ms.assetid: 50279c38-eae1-4301-9ea6-97ccea580f3e --- # Win32ThreadTraits Class +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This class provides the creation function for a Windows thread. Use this class if the thread will not use CRT functions. > [!IMPORTANT] diff --git a/docs/atl/reference/window-class-macros.md b/docs/atl/reference/window-class-macros.md index 4804e4b723c..13224f77bbc 100644 --- a/docs/atl/reference/window-class-macros.md +++ b/docs/atl/reference/window-class-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: Window Class Macros" title: "Window Class Macros" ms.date: "11/04/2016" f1_keywords: ["atlwin/ATL::DECLARE_WND_CLASS", "atlwin/ATL::DECLARE_WND_SUPERCLASS", "atlwin/ATL::DECLARE_WND_CLASS_EX", "ATLWIN/DECLARE_WND_CLASS", "ATLWIN/DECLARE_WND_SUPERCLASS", "ATLWIN/DECLARE_WND_CLASS_EX"] -ms.assetid: ce18681a-2bab-4453-9895-0f3ea47c2b24 --- # Window Class Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These macros define window class utilities. |Name|Description| diff --git a/docs/atl/reference/windows-messages-macros.md b/docs/atl/reference/windows-messages-macros.md index 06753053208..222363698ed 100644 --- a/docs/atl/reference/windows-messages-macros.md +++ b/docs/atl/reference/windows-messages-macros.md @@ -3,10 +3,11 @@ description: "Learn more about: Windows Messages Macros" title: "Windows Messages Macros" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::WM_FORWARDMSG", "ATLBASE/WM_FORWARDMSG"] -ms.assetid: 63abd22c-372d-4148-bb04-c605950ae64f --- # Windows Messages Macros +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + This macro forwards window messages. |Name|Description| diff --git a/docs/atl/reference/winmodule-global-functions.md b/docs/atl/reference/winmodule-global-functions.md index c0708a6a568..2523f806fc7 100644 --- a/docs/atl/reference/winmodule-global-functions.md +++ b/docs/atl/reference/winmodule-global-functions.md @@ -3,10 +3,11 @@ description: "Learn more about: WinModule Global Functions" title: "WinModule Global Functions" ms.date: "11/04/2016" f1_keywords: ["atlbase/ATL::AtlWinModuleAddCreateWndData", "atlbase/ATL::AtlWinModuleExtractCreateWndData"] -ms.assetid: 8ce45a5b-26a7-491f-9096-c09ceca5f2c2 --- # WinModule Global Functions +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + These functions provide support for `_AtlCreateWndData` structure operations. > [!IMPORTANT] diff --git a/docs/atl/reference/worker-archetype.md b/docs/atl/reference/worker-archetype.md index e4a36e9702a..ec8e422243c 100644 --- a/docs/atl/reference/worker-archetype.md +++ b/docs/atl/reference/worker-archetype.md @@ -3,10 +3,11 @@ description: "Learn more about: Worker Archetype" title: "Worker Archetype" ms.date: "11/04/2016" helpviewer_keywords: ["Worker archetype"] -ms.assetid: 834145cd-09d3-4149-bc99-620e1871cbfb --- # Worker Archetype +[!INCLUDE[product-lifecycle-status](../includes/lifecycle-note.md)] + Classes that conform to the *worker* archetype provide the code to process work items queued on a thread pool. **Implementation** diff --git a/docs/atl/registry-entries.md b/docs/atl/registry-entries.md index 30fd6299398..2f59a898775 100644 --- a/docs/atl/registry-entries.md +++ b/docs/atl/registry-entries.md @@ -3,10 +3,11 @@ description: "Learn more about: Registry Entries" title: "Registry Entries (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["registry, ATL services entries", "registry, application IDs"] -ms.assetid: 881989b7-61bb-459a-a13e-3bfcb33e184e --- # Registry Entries +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + DCOM introduced the concept of Application IDs (AppIDs), which group configuration options for one or more DCOM objects into a centralized location in the registry. You specify an AppID by indicating its value in the AppID named value under the object's CLSID. By default, an ATL-generated service uses its CLSID as the GUID for its AppID. Under `HKEY_CLASSES_ROOT\AppID`, you can specify DCOM-specific entries. Initially, two entries exist: diff --git a/docs/atl/registry-scripting-examples.md b/docs/atl/registry-scripting-examples.md index 605b92f0df0..55053c58db8 100644 --- a/docs/atl/registry-scripting-examples.md +++ b/docs/atl/registry-scripting-examples.md @@ -3,10 +3,11 @@ description: "Learn more about: Registry Scripting Examples" title: "Registry Scripting Examples" ms.date: "11/04/2016" helpviewer_keywords: ["scripting, examples", "registrar scripts [ATL]", "scripts, Registrar scripts", "registry, Registrar"] -ms.assetid: b6df80e1-e08b-40ee-9243-9b381b172460 --- # Registry Scripting Examples +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The scripting examples in this topic demonstrate how to add a key to the system registry, register the Registrar COM server, and specify multiple parse trees. ## Add a Key to HKEY_CURRENT_USER diff --git a/docs/atl/registry-support-classes.md b/docs/atl/registry-support-classes.md index 1aafad7ccfc..2e0b86bd46e 100644 --- a/docs/atl/registry-support-classes.md +++ b/docs/atl/registry-support-classes.md @@ -4,10 +4,11 @@ title: "Registry Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["registry support classes, ATL", "ATL, registry", "registry support classes"] -ms.assetid: 4203c346-77a9-42bf-8683-a3c3351cc490 --- # Registry Support Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class provides registry support: - [CRegKey](../atl/reference/cregkey-class.md) Contains methods for manipulating values in the system registry. diff --git a/docs/atl/running-objects-classes.md b/docs/atl/running-objects-classes.md index 8d7c92b99fe..f621bae5721 100644 --- a/docs/atl/running-objects-classes.md +++ b/docs/atl/running-objects-classes.md @@ -4,10 +4,11 @@ title: "Running Objects Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["object classes, running", "objects [C++], running objects classes"] -ms.assetid: b4d63c41-81fd-4000-96c5-ea0a011f4308 --- # Running Objects Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class provides support for running objects: - [IRunnableObjectImpl](../atl/reference/irunnableobjectimpl-class.md) Determines if an object is running, forces it to run, or locks it into the running state. diff --git a/docs/atl/running-the-program-as-a-local-server.md b/docs/atl/running-the-program-as-a-local-server.md index 5c063f70987..4d1bc97c64e 100644 --- a/docs/atl/running-the-program-as-a-local-server.md +++ b/docs/atl/running-the-program-as-a-local-server.md @@ -3,10 +3,12 @@ description: "Learn more about: Running the Program as a Local Server" title: "Running the Program as a Local Server" ms.date: "11/04/2016" helpviewer_keywords: ["debugging [ATL], running services as local server", "ATL services, running as local servers"] -ms.assetid: eb9701e6-e2a8-4666-897f-0c893aec8ac7 +ms.topic: concept-article --- # Running the Program as a Local Server +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + If running the program as a service is inconvenient, you can temporarily change the registry so that the program is run as a normal local server. Simply rename the `LocalService` value under your AppID to `_LocalService` and ensure the `LocalServer32` key under your CLSID is set correctly. (Note that using DCOMCNFG to specify that your application should be run on a different computer renames your `LocalServer32` key to `_LocalServer32`.) Running your program as a local server takes a few more seconds on startup because the call to `StartServiceCtrlDispatcher` in `CAtlServiceModuleT::Start` takes a few seconds before it fails. ## See also diff --git a/docs/atl/scope-of-atl.md b/docs/atl/scope-of-atl.md index bf84207f3b3..34b054cdbb3 100644 --- a/docs/atl/scope-of-atl.md +++ b/docs/atl/scope-of-atl.md @@ -3,10 +3,11 @@ description: "Learn more about: Scope of ATL" title: "Scope of ATL" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, scope"] -ms.assetid: 381adf50-3cb0-4d0f-a79a-07da093bc280 --- # Scope of ATL +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL allows you to easily create COM objects, Automation servers, and ActiveX controls. ATL provides built-in support for many of the fundamental COM interfaces. ATL is shipped as source code which you include in your application. ATL also makes a DLL available (atl90.dll), which contains code that can be shared across components. However, this DLL is not necessary. diff --git a/docs/atl/security-classes.md b/docs/atl/security-classes.md index c4d3e1acab7..e44ab3c8040 100644 --- a/docs/atl/security-classes.md +++ b/docs/atl/security-classes.md @@ -4,10 +4,11 @@ title: "Security Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["security classes [C++]"] -ms.assetid: 0477f1a4-c1af-4c4f-bbca-08f7b844e028 --- # Security Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + These classes are wrappers for common Win32 security classes and objects. - [CAccessToken](../atl/reference/caccesstoken-class.md) This class is a wrapper for an access token. diff --git a/docs/atl/service-provider-support-classes.md b/docs/atl/service-provider-support-classes.md index 9cce29b4cd7..a46d539dbf4 100644 --- a/docs/atl/service-provider-support-classes.md +++ b/docs/atl/service-provider-support-classes.md @@ -4,10 +4,11 @@ title: "Service Provider Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["service provider support classes"] -ms.assetid: 190f598e-fb32-4d37-adf1-21de395b04d9 --- # Service Provider Support Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following class provides support for service providers: - [IServiceProviderImpl](../atl/reference/iserviceproviderimpl-class.md) Locates a service specified by its GUID and returns the interface pointer for the requested interface on the service. diff --git a/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md b/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md index ef4dd01f189..6b56f346110 100644 --- a/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md +++ b/docs/atl/setting-up-a-static-link-to-the-registrar-code-cpp-only.md @@ -3,10 +3,12 @@ title: "Setting up a static link to the Registrar code (C++ only)" description: "How to statically link C++ code to the ATL Registrar code." ms.date: 09/03/2020 helpviewer_keywords: ["statically linking to ATL Registrar code", "linking [C++], to ATL Registrar code"] -ms.assetid: 835f5885-87a6-48fa-91e6-60988ee65538 +ms.topic: how-to --- # Setting up a static link to the Registrar code (C++ Only) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + C++ clients can create a static link to the Registrar's code. Static linking of the Registrar's parser adds approximately 5K to a release build. The simplest way to set up static linking assumes you have specified [`DECLARE_REGISTRY_RESOURCEID`](reference/registry-macros.md#declare_registry_resourceid) in your object's declaration. (It's the default specification used by the ATL.) diff --git a/docs/atl/site-information-classes.md b/docs/atl/site-information-classes.md index 4ece835b060..620d587be46 100644 --- a/docs/atl/site-information-classes.md +++ b/docs/atl/site-information-classes.md @@ -4,10 +4,11 @@ title: "Site Information Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["site information classes"] -ms.assetid: 102eae20-7953-4efb-b27b-409885c9c064 --- # Site Information Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes allow an object to communicate with its site: - [IObjectWithSiteImpl](../atl/reference/iobjectwithsiteimpl-class.md) Retrieves and sets a pointer to an object's site. Used for objects that are not controls. diff --git a/docs/atl/specifying-property-pages.md b/docs/atl/specifying-property-pages.md index 25dd74d4e22..507024c56c7 100644 --- a/docs/atl/specifying-property-pages.md +++ b/docs/atl/specifying-property-pages.md @@ -3,10 +3,12 @@ description: "Learn more about: Specifying Property Pages" title: "Specifying Property Pages (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ISpecifyPropertyPages method", "property pages, specifying"] -ms.assetid: ee8678cf-c708-49ab-b0ad-fc2db31f1ac3 +ms.topic: how-to --- # Specifying Property Pages +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + When you create an ActiveX control, you will often want to associate it with property pages that can be used to set the properties of your control. Control containers use the `ISpecifyPropertyPages` interface to find out which property pages can be used to set your control's properties. You will need to implement this interface on your control. To implement `ISpecifyPropertyPages` using ATL, take the following steps: diff --git a/docs/atl/specifying-the-threading-model-for-a-project-atl.md b/docs/atl/specifying-the-threading-model-for-a-project-atl.md index 70c3d124dd4..690bb8c1a1e 100644 --- a/docs/atl/specifying-the-threading-model-for-a-project-atl.md +++ b/docs/atl/specifying-the-threading-model-for-a-project-atl.md @@ -3,10 +3,12 @@ description: "Learn more about: Specifying the Threading Model for a Project (AT title: "Specifying the Threading Model for a Project (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["_ATL_FREE_THREADED macro", "_ATL_APARTMENT_THREADED macro", "ATL, multithreading", "threading [ATL], models", "_ATL_SINGLE_THREADED macro"] -ms.assetid: 6b571078-521c-4f3e-9f08-482aa235a822 +ms.topic: concept-article --- # Specifying the Threading Model for a Project (ATL) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following macros are available to specify the threading model of an ATL project: |Macro|Guidelines for using| diff --git a/docs/atl/string-and-text-classes.md b/docs/atl/string-and-text-classes.md index 3810a64d0d8..01bf9dde0e9 100644 --- a/docs/atl/string-and-text-classes.md +++ b/docs/atl/string-and-text-classes.md @@ -4,10 +4,11 @@ title: "ATL String and Text Classes" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["string conversion, ATL", "string classes [ATL]"] -ms.assetid: aa0cdc41-c953-4b17-82b6-59b908545571 --- # String and Text Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + These classes provide support for strings and text string conversions. - [CA2AEX](../atl/reference/ca2aex-class.md) This class is used by the string conversion macros CA2TEX and CT2AEX, and the typedef CA2A. diff --git a/docs/atl/supporting-idispatch-and-ierrorinfo.md b/docs/atl/supporting-idispatch-and-ierrorinfo.md index 177b65623fa..97d5c06785d 100644 --- a/docs/atl/supporting-idispatch-and-ierrorinfo.md +++ b/docs/atl/supporting-idispatch-and-ierrorinfo.md @@ -3,13 +3,15 @@ description: "Learn more about: Supporting IDispatch and IErrorInfo" title: "Supporting IDispatch and IErrorInfo" ms.date: "11/04/2016" helpviewer_keywords: ["ISupportErrorInfoImpl method", "IErrorInfo class suppor in ATL", "IDispatchImpl class", "IDispatch class support in ATL"] -ms.assetid: 7db2220f-319d-4ce9-9382-d340019f14f7 +ms.topic: concept-article --- # Supporting IDispatch and IErrorInfo +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + 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/atl/supporting-idispeventimpl.md b/docs/atl/supporting-idispeventimpl.md index 008def002d0..dde4fa8ab69 100644 --- a/docs/atl/supporting-idispeventimpl.md +++ b/docs/atl/supporting-idispeventimpl.md @@ -3,10 +3,12 @@ description: "Learn more about: Supporting IDispEventImpl" title: "Supporting IDispEventImpl" ms.date: "11/04/2016" helpviewer_keywords: ["event sink maps, declaring", "IDispEventImpl class, advising and unadvising", "SINK_ENTRY macro", "type libraries, importing", "ATL, IDispEventImpl support in COM objects", "BEGIN_SINK_MAP macro", "IDispEventImpl class, declaring"] -ms.assetid: b957f930-6a5b-4598-8e4d-8027759957e7 +ms.topic: concept-article --- # Supporting IDispEventImpl +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The template class [IDispEventImpl](../atl/reference/idispeventimpl-class.md) can be used to provide support for connection point sinks in your ATL class. A connection point sink allows your class to handle events fired from external COM objects. These connection point sinks are mapped with an event sink map, provided by your class. To properly implement a connection point sink for your class, the following steps must be completed: diff --git a/docs/atl/tear-off-interfaces-classes.md b/docs/atl/tear-off-interfaces-classes.md index 0f6c3667bd5..9de3758a0d8 100644 --- a/docs/atl/tear-off-interfaces-classes.md +++ b/docs/atl/tear-off-interfaces-classes.md @@ -4,10 +4,11 @@ title: "Tear-Off Interfaces Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["interfaces, tear-off", "tear-off interfaces classes"] -ms.assetid: 14e4ab01-9213-43e5-bef5-78af1e6206ff --- # Tear-Off Interfaces Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide support for tear-off interfaces: - [CComTearOffObject](../atl/reference/ccomtearoffobject-class.md) Implements `IUnknown` for a tear-off interface. diff --git a/docs/atl/testing-the-atl-dhtml-control.md b/docs/atl/testing-the-atl-dhtml-control.md index f148c3fe6d0..32fe9fae2ff 100644 --- a/docs/atl/testing-the-atl-dhtml-control.md +++ b/docs/atl/testing-the-atl-dhtml-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Testing the ATL DHTML Control" title: "Testing the ATL DHTML Control" ms.date: "11/04/2016" helpviewer_keywords: ["HTML controls, testing", "testing controls", "DHTML controls", "DHTML controls, testing"] -ms.assetid: 0e4b4358-80ce-4505-8b06-ef4f30b1d1f0 +ms.topic: how-to --- # Testing the ATL DHTML Control +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Once you have created your project, you can build and test the sample control. Before you do this, use **Class View** and **Solution Explorer** to examine the project. The elements of your project are described in greater detail in [Identifying the Elements of the DHTML Control Project](../atl/identifying-the-elements-of-the-dhtml-control-project.md). ## To build and test the ATL DHTML control diff --git a/docs/atl/testing-the-modified-atl-dhtml-control.md b/docs/atl/testing-the-modified-atl-dhtml-control.md index 71a65367b2e..b120c2d27bf 100644 --- a/docs/atl/testing-the-modified-atl-dhtml-control.md +++ b/docs/atl/testing-the-modified-atl-dhtml-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Testing the Modified ATL DHTML Control" title: "Testing the Modified ATL DHTML Control" ms.date: "11/06/2018" helpviewer_keywords: ["HTML controls, testing", "testing controls", "DHTML controls, testing"] -ms.assetid: 42316118-9433-410f-9d8a-0efcc1eff824 +ms.topic: how-to --- # Testing the Modified ATL DHTML Control +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Try out your new control to see how it works now. ## To build and test the modified control diff --git a/docs/atl/thread-pooling-classes.md b/docs/atl/thread-pooling-classes.md index ff62fdc9f8c..d78f5b29aa5 100644 --- a/docs/atl/thread-pooling-classes.md +++ b/docs/atl/thread-pooling-classes.md @@ -4,10 +4,11 @@ title: "Thread Pooling Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["thread pooling, classes", "threading [ATL], pooling", "pooling worker threads"] -ms.assetid: 01fa2c1c-12ae-4781-b772-0a74b6365a8c --- # Thread Pooling Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes support thread pooling: - [CComAutoThreadModule](../atl/reference/ccomautothreadmodule-class.md) Implements an EXE module, with support for multiple thread-pooled apartments. diff --git a/docs/atl/threading-models-and-critical-sections-classes.md b/docs/atl/threading-models-and-critical-sections-classes.md index cd8a516c145..21ebb6aafcb 100644 --- a/docs/atl/threading-models-and-critical-sections-classes.md +++ b/docs/atl/threading-models-and-critical-sections-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Threading Models and Critical Sections Classes" title: "Threading Models and Critical Sections Classes (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, critical sections", "ATL, multithreading", "threading [ATL], models", "critical sections"] -ms.assetid: 759f05ef-6285-4be6-a2cc-78572dd75146 +ms.topic: concept-article --- # Threading Models and Critical Sections Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes define a threading model and critical section: - [CAtlAutoThreadModule](../atl/reference/catlautothreadmodule-class.md) Implements a thread-pooled, apartment-model COM server. diff --git a/docs/atl/ui-support-classes.md b/docs/atl/ui-support-classes.md index 8e5f56f4c4c..53a4941d0a5 100644 --- a/docs/atl/ui-support-classes.md +++ b/docs/atl/ui-support-classes.md @@ -4,10 +4,11 @@ title: "UI Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["user interfaces, support classes", "user interfaces, ATL classes"] -ms.assetid: 313dfc95-308a-4118-b919-5a3c3673b865 --- # UI Support Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide general UI support: - [IDocHostUIHandlerDispatch](../atl/reference/idochostuihandlerdispatch-interface.md) An interface to the Microsoft HTML parsing and rendering engine. diff --git a/docs/atl/understanding-backus-naur-form-bnf-syntax.md b/docs/atl/understanding-backus-naur-form-bnf-syntax.md index 1422e4379ce..3e218f2ade2 100644 --- a/docs/atl/understanding-backus-naur-form-bnf-syntax.md +++ b/docs/atl/understanding-backus-naur-form-bnf-syntax.md @@ -3,10 +3,12 @@ description: "Learn more about: Understanding Backus-Naur form (BNF) syntax" title: "ATL Registrar and Backus-Naur form (BNF) syntax" ms.date: "05/14/2019" helpviewer_keywords: ["BNF notation", "Backus-Naur form (BNF) syntax"] -ms.assetid: 994bbef0-9077-4aa8-bdfe-b7e830af9acc +ms.topic: concept-article --- # Understanding Backus-Naur form (BNF) syntax +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The scripts used by the ATL Registrar are described in this topic using BNF syntax, which uses the notation shown in the following table. |Convention/symbol|Meaning| diff --git a/docs/atl/understanding-parse-trees.md b/docs/atl/understanding-parse-trees.md index 3f10cd3fbce..75544ab3c4e 100644 --- a/docs/atl/understanding-parse-trees.md +++ b/docs/atl/understanding-parse-trees.md @@ -3,9 +3,12 @@ description: "Learn more about: Understanding parse trees" title: "ATL Registrar and Parse Trees" ms.date: 04/15/2021 helpviewer_keywords: ["parse trees"] +ms.topic: concept-article --- # Understanding parse trees +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + You can define one or more parse trees in your registrar script, where each parse tree has the following form: > \{\}+ diff --git a/docs/atl/understanding-window-traits.md b/docs/atl/understanding-window-traits.md index 25564c04ec7..a6a391133f6 100644 --- a/docs/atl/understanding-window-traits.md +++ b/docs/atl/understanding-window-traits.md @@ -3,10 +3,12 @@ description: "Learn more about: Understanding Window Traits" title: "ATL Window Traits" ms.date: "11/04/2016" helpviewer_keywords: ["window traits"] -ms.assetid: c90cf850-9e91-49da-9cf3-ad4efb30347d +ms.topic: concept-article --- # Understanding Window Traits +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Window traits classes provide a simple method for standardizing the styles used for the creation of an ATL window object. Window traits are accepted as template parameters by [CWindowImpl](../atl/reference/cwindowimpl-class.md) and other ATL window classes as a way of providing default window styles at the class level. If the creator of a window instance doesn't provide styles explicitly in the call to [Create](../atl/reference/cwindowimpl-class.md#create), you can use a traits class to ensure that the window is still created with the correct styles. You can even ensure that certain styles are set for all instances of that window class while permitting other styles to be set on a per-instance basis. diff --git a/docs/atl/using-a-template-library.md b/docs/atl/using-a-template-library.md index 36b56c57a1f..7fae7aa5932 100644 --- a/docs/atl/using-a-template-library.md +++ b/docs/atl/using-a-template-library.md @@ -3,10 +3,12 @@ description: "Learn more about: Using a Template Library" title: "Using a Template Library (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["template libraries"] -ms.assetid: 5e80ec6e-a61c-41ce-b34b-9a6252c46265 +ms.topic: concept-article --- # Using a Template Library +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + A template is somewhat like a macro. As with a macro, invoking a template causes it to expand (with appropriate parameter substitution) to code you have written. However, a template goes further than this to allow the creation of new classes based on types that you pass as parameters. These new classes implement type-safe ways of performing the operation expressed in your template code. Template libraries such as ATL differ from traditional C++ class libraries in that they are typically supplied only as source code (or as source code with a little, supporting run time) and are not inherently or necessarily hierarchical in nature. Rather than deriving from a class to get the functionality you desire, you instantiate a class from a template. diff --git a/docs/atl/using-a-window.md b/docs/atl/using-a-window.md index f79ec47eb93..99a3e945018 100644 --- a/docs/atl/using-a-window.md +++ b/docs/atl/using-a-window.md @@ -3,10 +3,12 @@ description: "Learn more about: Using a Window" title: "Using a Window (ATL)" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "CWindow class, about CWindow class", "windows [C++], ATL"] -ms.assetid: b3b9cc8e-4287-486b-b080-38852bc2943a +ms.topic: concept-article --- # Using a Window +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Class [CWindow](../atl/reference/cwindow-class.md) allows you to use a window. Once you attach a window to a `CWindow` object, you can then call `CWindow` methods to manipulate the window. `CWindow` also contains an HWND operator to convert a `CWindow` object to an HWND. Thus you can pass a `CWindow` object to any function that requires a handle to a window. You can easily mix `CWindow` method calls and Win32 function calls, without creating any temporary objects. Because `CWindow` has only two data member (a window handle and the default dimensions), it does not impose an overhead on your code. In addition, many of the `CWindow` methods simply wrap corresponding Win32 API functions. By using `CWindow`, the HWND member is automatically passed to the Win32 function. diff --git a/docs/atl/using-contained-windows.md b/docs/atl/using-contained-windows.md index 62451849278..9de7cffd6db 100644 --- a/docs/atl/using-contained-windows.md +++ b/docs/atl/using-contained-windows.md @@ -3,10 +3,12 @@ description: "Learn more about: Using Contained Windows" title: "Using Contained Windows" ms.date: "11/04/2016" helpviewer_keywords: ["ATL, windows", "windows [C++], ATL", "contained windows in ATL"] -ms.assetid: 7b3d79e5-b569-413f-9b98-df4f14efbe2b +ms.topic: concept-article --- # Using Contained Windows +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + ATL implements contained windows with [CContainedWindowT](../atl/reference/ccontainedwindowt-class.md). A contained window represents a window that delegates its messages to a container object instead of handling them in its own class. > [!NOTE] diff --git a/docs/atl/using-idispeventimpl.md b/docs/atl/using-idispeventimpl.md index d15678d3b64..10a6ef481e5 100644 --- a/docs/atl/using-idispeventimpl.md +++ b/docs/atl/using-idispeventimpl.md @@ -3,10 +3,12 @@ description: "Learn more about: Using IDispEventImpl" title: "Using IDispEventImpl (ATL)" ms.date: "08/19/2019" helpviewer_keywords: ["IDispEventImpl class, using"] -ms.assetid: 82d53b61-9d0d-45c5-aff9-2fafa468a9ca +ms.topic: how-to --- # Using IDispEventImpl +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + When using `IDispEventImpl` to handle events, you will need to: - Derive your class from [IDispEventImpl](../atl/reference/idispeventimpl-class.md). diff --git a/docs/atl/using-idispeventsimpleimpl.md b/docs/atl/using-idispeventsimpleimpl.md index 2c0ee8349f1..875fb0cd26c 100644 --- a/docs/atl/using-idispeventsimpleimpl.md +++ b/docs/atl/using-idispeventsimpleimpl.md @@ -3,10 +3,12 @@ description: "Learn more about: Using IDispEventSimpleImpl" title: "Using IDispEventSimpleImpl (ATL)" ms.date: "08/19/2019" helpviewer_keywords: ["IDispEventSimpleImpl class, using"] -ms.assetid: 8640ad1a-4bd0-40a5-b5e4-7322685d7aab +ms.topic: concept-article --- # Using IDispEventSimpleImpl +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + When using `IDispEventSimpleImpl` to handle events, you will need to: - Derive your class from [IDispEventSimpleImpl](../atl/reference/idispeventsimpleimpl-class.md). diff --git a/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md b/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md index 1b9ef3d2d45..ea68a8f0ef7 100644 --- a/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md +++ b/docs/atl/using-replaceable-parameters-the-registrar-s-preprocessor.md @@ -3,10 +3,12 @@ description: "Learn more about: Using Replaceable Parameters (The Registrar's Pr title: "Using Replaceable Parameters (ATL Registrar)" ms.date: "11/04/2016" helpviewer_keywords: ["%MODULE%"] -ms.assetid: 0b376994-84a6-4967-8d97-8c01dfc94efe +ms.topic: concept-article --- # Using Replaceable Parameters (The Registrar's Preprocessor) +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + Replaceable parameters allow a Registrar's client to specify run-time data. To do this, the Registrar maintains a replacement map into which it enters the values associated with the replaceable parameters in your script. The Registrar makes these entries at run time. ## Using %MODULE% diff --git a/docs/atl/using-task-manager.md b/docs/atl/using-task-manager.md index 626e5525990..37a86152888 100644 --- a/docs/atl/using-task-manager.md +++ b/docs/atl/using-task-manager.md @@ -3,10 +3,12 @@ description: "Learn more about: Using Task Manager" title: "Using Task Manager" ms.date: "11/04/2016" helpviewer_keywords: ["Task Manager", "breakpoints, Task Manager", "debugging [ATL], using Task Manager"] -ms.assetid: 773fccd5-308d-42c2-a17f-60ae94989062 +ms.topic: how-to --- # Using Task Manager +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + One of the simplest ways to debug a service is through the use of the Task Manager. While the service is running, start the Task Manager and click the **Processes** tab. Right-click the name of the EXE and then click **Debug**. This launches Visual C++ attached to that running process. Now, click **Break** on the **Debug** menu to allow you to set breakpoints in your code. Click **Run** to run to your selected breakpoints. ## See also diff --git a/docs/atl/utility-classes.md b/docs/atl/utility-classes.md index df1f4375949..b454bb01a80 100644 --- a/docs/atl/utility-classes.md +++ b/docs/atl/utility-classes.md @@ -4,10 +4,11 @@ title: "Utility Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["utility classes"] -ms.assetid: 33d5da9d-89a5-49f9-a873-a26499299d17 --- # Utility Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following MFC-independent utility classes are provided: - [CImage](../atl-mfc-shared/reference/cimage-class.md) Provides enhanced bitmap support, including the ability to load and save images in JPEG, GIF, BMP, and Portable Network Graphics (PNG) formats. diff --git a/docs/atl/windows-support-classes.md b/docs/atl/windows-support-classes.md index caa906a9fb4..a8f615fa208 100644 --- a/docs/atl/windows-support-classes.md +++ b/docs/atl/windows-support-classes.md @@ -4,10 +4,11 @@ title: "Windows Support Classes (ATL)" ms.date: "11/04/2016" ms.topic: "reference" helpviewer_keywords: ["ATL, windows", "windows [C++], ATL"] -ms.assetid: 750b14d5-d787-4d2b-9728-ac199ccad489 --- # Windows Support Classes +[!INCLUDE[product-lifecycle-status](includes/lifecycle-note.md)] + The following classes provide support for windows: - [_U_MENUorID](../atl/reference/u-menuorid-class.md) Provides wrappers for `CreateWindow` and `CreateWindowEx`. diff --git a/docs/build-insights/build-performance.md b/docs/build-insights/build-performance.md new file mode 100644 index 00000000000..13a51332376 --- /dev/null +++ b/docs/build-insights/build-performance.md @@ -0,0 +1,183 @@ +--- +title: "Get Started with GitHub Copilot build performance for Windows" +description: "Learn how to use GitHub Copilot to improve build times." +ms.date: 01/21/2026 +helpviewer_keywords: ["GitHub Copilot build performance", "C++ Build Insights", "build time optimization", "header file analysis", "template instantiation", "Visual Studio build performance"] +ms.topic: how-to +--- + +# Get started with GitHub Copilot build performance for Windows  + +The GitHub Copilot build performance for Windows helps you make your builds faster. It finds expensive headers, template instantiations, and functions and can automatically make your builds more efficient. GitHub Copilot is integrated with Visual Studio. + +## Prerequisites  + +- Visual Studio 2026 version 18.3 Insiders 4, or later. +- MSVC Build Tools version 14.50 or later. +- An MSBuild or CMake project. +- Windows 10 or later. + +### Before you begin  + +In the Visual Studio 2026 Installer, ensure the following components are selected in the **Desktop development with C++** [workload](/visualstudio/install/install-visual-studio#step-4---choose-workloads): + +:::image type="complex" source="./media/vs-installer-options.png" alt-text="Screenshot of the Visual Studio installer."::: +The desktop development with C++ section is highlighted and C++ Build Insights, C++ profiling tools, and C++ CMake tools for Windows are selected. +:::image-end::: + +### Verify your GitHub Copilot subscription + +To use GitHub Copilot build performance for Windows, you need a GitHub Copilot Pro, Pro+, Business, or Enterprise subscription. + +Verify your GitHub Copilot subscription on GitHub, and then sign in to your GitHub account in Visual Studio 2026. + +1. Verify your GitHub Copilot subscription by signing in to [https://github.com](https://github.com/). Select your profile picture and then [Copilot settings](https://github.com/settings/copilot/features). Your plan type appears near the top of the page: + + :::image type="complex" source="./media/copilot-subscription.png" alt-text="Screenshot showing the user's GitHub Copilot information."::: + The Copilot settings page shows the type of subscription. In this case, the user has GitHub Copilot Enterprise. + :::image-end::: +1. In Visual Studio, sign in to your GitHub account: + - If you're not signed in to GitHub in Visual Studio, open the GitHub Copilot Chat and follow the sign-in instructions in the pop-up window. + - Confirm your GitHub sign-in status by selecting your profile picture in Visual Studio. You should see that your GitHub account is **Active**: + + :::image type="complex" source="./media/vs-account-authentication.png" alt-text="Screenshot of the account dropdown in Visual Studio."::: + The account dropdown shows that a Microsoft account and a GitHub account are both signed in and active. + :::image-end::: + +### Enable template collection + +To minimize analysis overhead, the template instantiation time collection is off by default. Turn it on: + + 1. In Visual Studio, go to **Tools** > **Options**. + 1. In the **Options** dialog, expand **Build Insights**. + 1. Select **Collect Template Instantiation**. + +:::image type="complex" source="./media/build-insights-options.png" alt-text="Screenshot of the Build Insights settings page in Visual Studio Options with the Collect template instantiation checkbox enabled, displaying trace collection configurations for analysis."::: +The dialog shows trace collection settings with the Collect template instantiation checkbox selected. +:::image-end::: + +For more information about template instantiation on build time, see [Troubleshoot template instantiation impact on build time | Microsoft Learn](/cpp/build-insights/tutorials/build-insights-template-view) + +## Troubleshoot build performance with GitHub Copilot + +To start the GitHub Copilot build performance agent: + +1. Open the GitHub Copilot chat pane and type '@'. One of the options is **@BuildPerfCpp**. Select it: + + :::image type="complex" source="./media/copilot-build-perf-select.png" alt-text="Screenshot of the GitHub Copilot chat pane."::: + The GitHub Copilot chat pane shows a list of agents to choose from. Build Perf C p p (optimize your c + + build) is selected. + :::image-end::: + +1. Select your preferred model in the model drop down menu: + + :::image type="complex" source="./media/model-select.png" alt-text="Screenshot of the model selection menu in the Copilot Chat window."::: + This dropdown lists various models like GPT-5, CLaude Sonnet 4, Gemini 3 Pro, and others. + :::image-end::: + +1. Instruct GitHub Copilot to improve the build performance of your selected project by typing something like **Help me improve the build performance of this project**. You can add extra context so that GitHub Copilot can better make suggestions to match the needs of your project. + + :::image type="complex" source="./media/copilot-build-request.png" alt-text="Screenshot of the GitHub Copilot Chat window."::: + The GitHub Copilot chat window shows @ Build Per Cpp: Help me improve the build performance of this project. + :::image-end::: + +### Permissions + +The first time you use GitHub Copilot build performance for Windows, you may need to enable Build Insights and grant elevated permissions to collect MSVC compiler traces. + +Visual Studio needs elevated permissions to analyze build performance and the Build Insights tool needs to be enabled. It stays enabled until you disable it. For more information about these permissions, see [Build Insights needs additional permissions](/cpp/build-insights/elevate-note). + +If GitHub Copilot prompts you to enable Build Insights and grant elevated permissions, choose **Confirm**: + +:::image type="complex" source="./media/build-insights-permission.png" alt-text="Screenshot of a GitHub Copilot dialog asking to elevate permissions."::: +The dialog indicates that Build Insights (vcperf) needs additional permissions to capture MSVC compiler traces. There are Confirm and Deny buttons. +:::image-end::: + +A Visual Studio dialog then appears prompting you to allow a one-time elevated request: + +:::image type="complex" source="./media/msvc-elevation.png" alt-text="Screenshot of a Microsoft Visual Studio prompt requesting elevated permissions."::: +The elevation prompt says: Build Insights (vcperf) needs additional permissions to capture MSVC compiler traces. Allow this one-time elevated request? There are Yes and No buttons. +:::image-end::: + +Choose **Yes**. The Windows User Account Control dialog then appears: + +:::image type="complex" source="./media/windows-user-account-control.png" alt-text="Screenshot of the User Account Control dialog."::: +The dialog asks for permission for the Windows Command Processor, verified publisher Microsoft, to allow this app to make changes to your device. There are Yes and No buttons. +:::image-end::: + +Choose **Yes** to grant permission to capture the MSVC compiler traces. Denying the elevated request cancels the build analysis. + +## Guide GitHub Copilot through the process of improving the build time + +As you guide GitHub Copilot through the process of improving the build time, it may ask you to provide permission to run tools such as PowerShell scripts: + +:::image type="complex" source="./media/terminal-permission.png" alt-text="Screenshot of a Copilot Chat notification."::: +The prompt asks the user to authorize running the command: ls ../src/ in the terminal. The Confirm dropdown offers: Always allow and Allow in this session. There's also a Deny button. +:::image-end::: + +Choose the level of permission you are comfortable with. If you deny the request, GitHub Copilot can't proceed with the build performance analysis. + +Copilot may go through multiple iterations to find the best way to make the build faster. In this chat example, Copilot made its first build performance improvement but recognizes more areas to optimize. + +:::image type="complex" source="./media/build-analysis-complete.png" alt-text="Screenshot of a message in the GitHub Copilot chat window."::: +The message indicates that analysis is complete and the build time improved from 78.6 seconds to 70.5 seconds (8.1 seconds faster, ~10.3% improvement). It indicates there's still room for improvement. +:::image-end::: + +When the analysis is done, GitHub Copilot displays a summary of the changes and build performance impact for that iteration: + +:::image type="complex" source="./media/build-summary.png" alt-text="Screenshot of the build performance summary."::: +The summary shows a before and after optimization summary indicating build time, the top bottleneck, and the top five headers that contributed the most to the build time. The report shows build time dropping from 110.7 seconds to 34.1 seconds. It highlights a 69.2% overall improvement and faster incremental rebuilds after enabling precompiled headers. +:::image-end::: + +In this example, build time dropped from **110.7s to 34.1s** after enabling precompiled headers for costly includes. A **69% improvement** and **3.2× faster builds** with near-instant incremental rebuilds. + +### Other ways to access GitHub Copilot build performance for Windows + +You can access the GitHub Copilot build performance for Windows in other ways: + +The **Build** menu: + + :::image type="complex" source="./media/build-menu-improve.png" alt-text="Screenshot of the Build menu."::: + The Build menu option Run Build Insights is expanded to show Build All, Rebuild All, and Improve Build Performance. The latter is selected. + :::image-end::: + + Select **Improve build performance on Solution** to open the GitHub Copilot chat window, which prompts you to optimize the build performance of your project. + :::image type="complex" source="./media/copilot-improve-prompt.png" alt-text="Screenshot of the Copilot chat window."::: + The chat window shows a prompt to Improve Build Performance. + :::image-end::: + +Or use the **Solution** window context menu which you can access by right-clicking the solution node: + + :::image type="complex" source="./media/solution-menu-improve.png" alt-text="A screenshot of the Solution explorer."::: + The context menu shows Build Solution, Build Solution, and so on. Improve build performance on Solution is highlighted. + :::image-end::: + + Select **Improve build performance on Solution** to open the GitHub Copilot chat window, which prompts you to optimize the build performance of your project. + + :::image type="complex" source="./media/copilot-improve-prompt.png" alt-text="Screenshot of the Copilot chat window."::: + The chat window shows a prompt to Improve Build Performance. + :::image-end::: + +Or from the **Build Insights** view: + + Select **Improve** from the Build Insights diagnostics session view to open the GitHub Copilot chat window, which prompts you to optimize the build performance of your project. This button uses data from the existing build insights trace results. It doesn't do a new analysis until the current changes are processed. + + :::image type="complex" source="./media/insights-improve-button.png" alt-text="Screenshot of the Build Insights view window."::: + The Improve link is highlighted. + :::image-end::: + + The GitHub Copilot chat window is prompted to optimize the build performance of your project, focusing on includes. + + :::image type="complex" source="./media/copilot-improve-includes.png" alt-text="Screenshot of the Copilot chat window with focusing on includes prompt."::: + The chat window shows a prompt to Improve Build Performance, focusing on includes. + :::image-end::: + +## Summary + +By combining MSVC Build Insights with GitHub Copilot, you can identify build bottlenecks and apply fixes without manually analyzing trace data or configuring precompiled headers yourself. The workflow handles trace collection, analysis, and code changes in an iterative loop until build times are reduced to your satisfaction. + +## See also + +[Build Insights function view](/cpp/build-insights/tutorials/build-insights-function-view)\ +[Build Insights included files view](/cpp/build-insights/tutorials/build-insights-included-files-view)\ +[vcperf and Windows Performance Analyzer](/cpp/build-insights/tutorials/vcperf-and-wpa)\ +[Windows Performance Analyzer basics](/cpp/build-insights/tutorials/wpa-basics) \ No newline at end of file diff --git a/docs/build-insights/elevate-note.md b/docs/build-insights/elevate-note.md new file mode 100644 index 00000000000..f13849c4b32 --- /dev/null +++ b/docs/build-insights/elevate-note.md @@ -0,0 +1,22 @@ +--- +title: "Build Insights needs additional permissions" +description: "To capture trace files, Build Insights needs additional permissions as described in this topic." +ms.topic: concept-article +ms.date: 12/9/2025 +ms.update-cycle: 3650-days +f1_keywords: + - bi_permissions +--- +# Build Insights needs additional permissions + +Starting with Visual Studio 2026, Build Insights and `vcperf` need extra permissions to capture traces. + +To allow `vcperf` to capture build traces, please accept the one time, per user, elevated prompt that appears when you first attempt to capture a trace: + +:::image type="content" source="./media/elevation-prompt.png" alt-text="A screenshot of the elevation prompt. It says: To capture trace files, Build Insights needs additional permissions. Allow this one-time elevated request?"::: + +Once you accept this elevation request, you can capture trace files with `vcperf`. You won't be prompted again to elevate permissions again. Accepting this request doesn't elevate permissions for Visual Studio--only for `vcperf` so it can to capture traces. + +## See also + +[Get started with C++ Build Insights](get-started-with-cpp-build-insights.md) \ No newline at end of file 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 038b948e192..fccaa5d7f91 100644 --- a/docs/build-insights/get-started-with-cpp-build-insights.md +++ b/docs/build-insights/get-started-with-cpp-build-insights.md @@ -4,6 +4,7 @@ description: "A high-level overview of C++ Build Insights." ms.date: "11/03/2019" helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"] ms.custom: intro-get-started +ms.topic: how-to --- # Get started with C++ Build Insights @@ -14,7 +15,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 +23,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 +42,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 7a68551902e..bf11ccdb5e3 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 @@ -17,7 +17,7 @@ landingContent: # Cards and links should be based on top customer tasks or top subjects # Start card title with a verb # Card (optional) - - title: Learn how your build performs + - title: Learn how your build performs linkLists: - linkListType: overview links: @@ -25,6 +25,12 @@ landingContent: url: get-started-with-cpp-build-insights.md - linkListType: tutorial links: + - text: Get started with GitHub Copilot build performance for Windows + url: build-performance.md + - 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/media/build-analysis-complete.png b/docs/build-insights/media/build-analysis-complete.png new file mode 100644 index 00000000000..18857c6d623 Binary files /dev/null and b/docs/build-insights/media/build-analysis-complete.png differ diff --git a/docs/build-insights/media/build-insights-options.png b/docs/build-insights/media/build-insights-options.png new file mode 100644 index 00000000000..e8fce846167 Binary files /dev/null and b/docs/build-insights/media/build-insights-options.png differ diff --git a/docs/build-insights/media/build-insights-permission.png b/docs/build-insights/media/build-insights-permission.png new file mode 100644 index 00000000000..4a54a2c87d1 Binary files /dev/null and b/docs/build-insights/media/build-insights-permission.png differ diff --git a/docs/build-insights/media/build-menu-improve.png b/docs/build-insights/media/build-menu-improve.png new file mode 100644 index 00000000000..14fd3cbe2fa Binary files /dev/null and b/docs/build-insights/media/build-menu-improve.png differ diff --git a/docs/build-insights/media/build-summary.png b/docs/build-insights/media/build-summary.png new file mode 100644 index 00000000000..fc7e0a51bff Binary files /dev/null and b/docs/build-insights/media/build-summary.png differ diff --git a/docs/build-insights/media/copilot-build-perf-select.png b/docs/build-insights/media/copilot-build-perf-select.png new file mode 100644 index 00000000000..4bda984a9ca Binary files /dev/null and b/docs/build-insights/media/copilot-build-perf-select.png differ diff --git a/docs/build-insights/media/copilot-build-request.png b/docs/build-insights/media/copilot-build-request.png new file mode 100644 index 00000000000..325ec315daa Binary files /dev/null and b/docs/build-insights/media/copilot-build-request.png differ diff --git a/docs/build-insights/media/copilot-improve-includes.png b/docs/build-insights/media/copilot-improve-includes.png new file mode 100644 index 00000000000..2a398182634 Binary files /dev/null and b/docs/build-insights/media/copilot-improve-includes.png differ diff --git a/docs/build-insights/media/copilot-improve-prompt.png b/docs/build-insights/media/copilot-improve-prompt.png new file mode 100644 index 00000000000..43a5194dc4a Binary files /dev/null and b/docs/build-insights/media/copilot-improve-prompt.png differ diff --git a/docs/build-insights/media/copilot-subscription.png b/docs/build-insights/media/copilot-subscription.png new file mode 100644 index 00000000000..9147ff7177c Binary files /dev/null and b/docs/build-insights/media/copilot-subscription.png differ diff --git a/docs/build-insights/media/elevation-prompt.png b/docs/build-insights/media/elevation-prompt.png new file mode 100644 index 00000000000..619c2999d87 Binary files /dev/null and b/docs/build-insights/media/elevation-prompt.png differ diff --git a/docs/build-insights/media/insights-improve-button.png b/docs/build-insights/media/insights-improve-button.png new file mode 100644 index 00000000000..ba4a0383b82 Binary files /dev/null and b/docs/build-insights/media/insights-improve-button.png differ diff --git a/docs/build-insights/media/model-select.png b/docs/build-insights/media/model-select.png new file mode 100644 index 00000000000..4c3db683c85 Binary files /dev/null and b/docs/build-insights/media/model-select.png differ diff --git a/docs/build-insights/media/msvc-elevation.png b/docs/build-insights/media/msvc-elevation.png new file mode 100644 index 00000000000..7404b6f41ab Binary files /dev/null and b/docs/build-insights/media/msvc-elevation.png differ diff --git a/docs/build-insights/media/solution-menu-improve.png b/docs/build-insights/media/solution-menu-improve.png new file mode 100644 index 00000000000..8b52818c8bb Binary files /dev/null and b/docs/build-insights/media/solution-menu-improve.png differ diff --git a/docs/build-insights/media/terminal-permission.png b/docs/build-insights/media/terminal-permission.png new file mode 100644 index 00000000000..4baf7683bf5 Binary files /dev/null and b/docs/build-insights/media/terminal-permission.png differ diff --git a/docs/build-insights/media/vs-account-authentication.png b/docs/build-insights/media/vs-account-authentication.png new file mode 100644 index 00000000000..3e62cf49c70 Binary files /dev/null and b/docs/build-insights/media/vs-account-authentication.png differ diff --git a/docs/build-insights/media/vs-installer-options.png b/docs/build-insights/media/vs-installer-options.png new file mode 100644 index 00000000000..6bd7c59e9f8 Binary files /dev/null and b/docs/build-insights/media/vs-installer-options.png differ diff --git a/docs/build-insights/media/windows-user-account-control.png b/docs/build-insights/media/windows-user-account-control.png new file mode 100644 index 00000000000..7bee87290d7 Binary files /dev/null and b/docs/build-insights/media/windows-user-account-control.png differ 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 b98998fd390..5fc55fa2aba 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 7265d140e1f..133484cb32b 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 0329689f4c0..6eeabda6f45 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 7b642755497..e206d537cfb 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 f8f89269172..e4518cef9e0 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 74ba8fc4ce6..16078024104 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 6772fe813e9..f339588c6e5 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 edd2ae4ddf3..ee9bac8bc6f 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 0006c06a835..3dc40659f7b 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 2d767ed2805..ef78df1ffc9 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 98b10ece5b7..a172bccaea6 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 3729c2bebd0..b73bc7f4fbb 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/thread.md b/docs/build-insights/reference/sdk/cpp-event-data-types/thread.md index 290d7e82754..1e850cafb6f 100644 --- a/docs/build-insights/reference/sdk/cpp-event-data-types/thread.md +++ b/docs/build-insights/reference/sdk/cpp-event-data-types/thread.md @@ -3,6 +3,7 @@ title: "Thread class" description: "The C++ Build Insights SDK Thread class reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Thread", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # Thread class 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 918f0ecba93..0d7d0284f48 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/relog-a.md b/docs/build-insights/reference/sdk/functions/relog-a.md index ca57d0fdb68..36ec0048ec6 100644 --- a/docs/build-insights/reference/sdk/functions/relog-a.md +++ b/docs/build-insights/reference/sdk/functions/relog-a.md @@ -1,10 +1,10 @@ --- title: "RelogA" description: "The C++ Build Insights SDK RelogA function reference." -ms.date: "02/12/2020" +ms.date: 02/12/2020 helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RelogA", "throughput analysis", "build time analysis", "vcperf.exe"] --- -# RelogA +# `RelogA` ::: moniker range="<=msvc-140" @@ -26,17 +26,17 @@ enum RESULT_CODE RelogA( ### Parameters -*inputLogFile*\ +*`inputLogFile`*\ The input ETW trace that you wish to read events from. -*outputLogFile*\ +*`outputLogFile`*\ The file in which to write the new events. -*relogDescriptor*\ -Pointer to a [RELOG_DESCRIPTOR](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. +*`relogDescriptor`*\ +Pointer to a [`RELOG_DESCRIPTOR`](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. ### Return Value -A result code from the [RESULT_CODE](../other-types/result-code-enum.md) enum. +A result code from the [`RESULT_CODE`](../other-types/result-code-enum.md) enum. ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/relog-w.md b/docs/build-insights/reference/sdk/functions/relog-w.md index c4ed0ad3d9b..d042d6ce853 100644 --- a/docs/build-insights/reference/sdk/functions/relog-w.md +++ b/docs/build-insights/reference/sdk/functions/relog-w.md @@ -1,10 +1,10 @@ --- title: "RelogW" description: "The C++ Build Insights SDK RelogW function reference." -ms.date: "02/12/2020" +ms.date: 02/12/2020 helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RelogW", "throughput analysis", "build time analysis", "vcperf.exe"] --- -# RelogW +# `RelogW` ::: moniker range="<=msvc-140" @@ -26,17 +26,17 @@ enum RESULT_CODE RelogW( ### Parameters -*inputLogFile*\ +*`inputLogFile`*\ The input ETW trace that you wish to read events from. -*outputLogFile*\ +*`outputLogFile`*\ The file in which to write the new events. -*relogDescriptor*\ -Pointer to a [RELOG_DESCRIPTOR](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. +*`relogDescriptor`*\ +Pointer to a [`RELOG_DESCRIPTOR`](../other-types/relog-descriptor-struct.md) object. Use this object to configure the relogging session. ### Return Value -A result code from the [RESULT_CODE](../other-types/result-code-enum.md) enum. +A result code from the [`RESULT_CODE`](../other-types/result-code-enum.md) enum. ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/relog.md b/docs/build-insights/reference/sdk/functions/relog.md index 53fe924c8cd..c68f319545d 100644 --- a/docs/build-insights/reference/sdk/functions/relog.md +++ b/docs/build-insights/reference/sdk/functions/relog.md @@ -1,10 +1,10 @@ --- title: "Relog" description: "The C++ Build Insights SDK Relog function reference." -ms.date: "02/12/2020" +ms.date: 02/12/2020 helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "Relog", "throughput analysis", "build time analysis", "vcperf.exe"] --- -# Relog +# `Relog` ::: moniker range="<=msvc-140" @@ -41,40 +41,44 @@ RESULT_CODE Relog( StaticReloggerGroup reloggerGroup); ``` -### Parameters +### Template parameters + +*`TAnalyzerGroupMembers`*\ +This template parameter pack is always deduced. -*TAnalyzerGroupMembers*\ -This parameter is always deduced. +*`TReloggerGroupMembers`*\ +This template parameter pack is always deduced. -*TReloggerGroupMembers*\ -This parameter is always deduced. +### Parameters -*inputLogFile*\ +*`inputLogFile`*\ The input ETW trace that you wish to read events from. -*outputLogFile*\ +*`outputLogFile`*\ The file in which to write the new events. -*numberOfAnalysisPasses*\ +*`numberOfAnalysisPasses`*\ The number of analysis passes to run on the input trace. The trace gets passed through the provided analyzer group once per analysis pass. -*systemEventsRetentionFlags*\ -A bitmask that specifies which system ETW events to keep in the relogged trace. For more information, see [RELOG_RETENTION_SYSTEM_EVENT_FLAGS](../other-types/relog-retention-system-event-flags-constants.md). +*`systemEventsRetentionFlags`*\ +A bitmask that specifies which system ETW events to keep in the relogged trace. For more information, see [`RELOG_RETENTION_SYSTEM_EVENT_FLAGS`](../other-types/relog-retention-system-event-flags-constants.md). -*analyzerGroup*\ -The analyzer group used for the analysis phase of the relogging session. Call [MakeStaticAnalyzerGroup](make-static-analyzer-group.md) to create an analyzer group. To use a dynamic analyzer group obtained from [MakeDynamicAnalyzerGroup](make-dynamic-analyzer-group.md), first encapsulate it inside a static analyzer group by passing its address to `MakeStaticAnalyzerGroup`. +*`analyzerGroup`*\ +The analyzer group used for the analysis phase of the relogging session. Call [`MakeStaticAnalyzerGroup`](make-static-analyzer-group.md) to create an analyzer group. To use a dynamic analyzer group obtained from [`MakeDynamicAnalyzerGroup`](make-dynamic-analyzer-group.md), first encapsulate it inside a static analyzer group by passing its address to `MakeStaticAnalyzerGroup`. -*reloggerGroup*\ -The relogger group that relogs events into the trace file specified in *outputLogFile*. Call [MakeStaticReloggerGroup](make-static-relogger-group.md) to create a relogger group. To use a dynamic relogger group obtained from [MakeDynamicReloggerGroup](make-dynamic-relogger-group.md), first encapsulate it inside a static relogger group by passing its address to `MakeStaticReloggerGroup`. +*`reloggerGroup`*\ +The relogger group that relogs events into the trace file specified in *`outputLogFile`*. Call [`MakeStaticReloggerGroup`](make-static-relogger-group.md) to create a relogger group. To use a dynamic relogger group obtained from [`MakeDynamicReloggerGroup`](make-dynamic-relogger-group.md), first encapsulate it inside a static relogger group by passing its address to `MakeStaticReloggerGroup`. ### Return Value -A result code from the [RESULT_CODE](../other-types/result-code-enum.md) enum. +A result code from the [`RESULT_CODE`](../other-types/result-code-enum.md) enum. + +### Remarks -### Remark +The input trace is passed through the analyzer group *`numberOfAnalysisPasses`* times. There's no similar option for relogging passes. The trace is passed through the relogger group only once, after all analysis passes are complete. -The input trace is passed through the analyzer group *numberOfAnalysisPasses* times. There's no similar option for relogging passes. The trace is passed trough the relogger group only once, after all analysis passes are complete. +The relogging of system events like CPU samples from within a relogger class isn't supported. Use the *`systemEventsRetentionFlags`* parameter to decide which system events to keep in the output trace. -The relogging of system events like CPU samples from within a relogger class isn't supported. Use the *systemEventsRetentionFlags* parameter to decide which system events to keep in the output trace. +The `relog` function depends on the COM API. You must call [`CoInitialize`](/windows/win32/api/objbase/nf-objbase-coinitialize) before you call `relog`. Call [`CoUninitialize`](/windows/win32/api/combaseapi/nf-combaseapi-couninitialize) once `relog` has finished. If you call `relog` without a call to `CoInitialize` first, you'll get error code 9 (`RESULT_CODE_FAILURE_START_RELOGGER`). ::: moniker-end diff --git a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md index b89dc7f62f5..10f6b58ae14 100644 --- a/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md +++ b/docs/build-insights/reference/sdk/functions/stop-and-relog-tracing-session.md @@ -72,7 +72,7 @@ A result code from the [RESULT_CODE](../other-types/result-code-enum.md) enum. ### Remarks -The input trace is passed through the analyzer group *numberOfAnalysisPasses* times. There's no similar option for relogging passes. The trace is passed trough the relogger group only once, after all analysis passes are complete. +The input trace is passed through the analyzer group *numberOfAnalysisPasses* times. There's no similar option for relogging passes. The trace is passed through the relogger group only once, after all analysis passes are complete. The relogging of system events like CPU samples from within a relogger class isn't supported. Use the *systemEventsRetentionFlags* parameter to decide which system events to keep in the output trace. 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 46dedc00da0..39ac969bab5 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 a050b60ed3b..32e05f8ce83 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 ca9bea6c23f..9e52425ed8a 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/sdk/other-types/analysis-callbacks-struct.md b/docs/build-insights/reference/sdk/other-types/analysis-callbacks-struct.md index 2957df07f10..348969f6fd6 100644 --- a/docs/build-insights/reference/sdk/other-types/analysis-callbacks-struct.md +++ b/docs/build-insights/reference/sdk/other-types/analysis-callbacks-struct.md @@ -3,6 +3,7 @@ title: "ANALYSIS_CALLBACKS structure" description: "The C++ Build Insights SDK ANALYSIS_CALLBACKS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ANALYSIS_CALLBACKS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # ANALYSIS_CALLBACKS structure diff --git a/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md b/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md index 73012b0d9ac..d18e384ca27 100644 --- a/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md +++ b/docs/build-insights/reference/sdk/other-types/analysis-descriptor-struct.md @@ -3,6 +3,7 @@ title: "ANALYSIS_DESCRIPTOR structure" description: "The C++ Build Insights SDK ANALYSIS_DESCRIPTOR structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "ANALYSIS_DESCRIPTOR", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # ANALYSIS_DESCRIPTOR structure diff --git a/docs/build-insights/reference/sdk/other-types/callback-code-enum.md b/docs/build-insights/reference/sdk/other-types/callback-code-enum.md index 157b5e45345..85cbc687ae1 100644 --- a/docs/build-insights/reference/sdk/other-types/callback-code-enum.md +++ b/docs/build-insights/reference/sdk/other-types/callback-code-enum.md @@ -3,6 +3,7 @@ title: "CALLBACK_CODE enum" description: "The C++ Build Insights SDK CALLBACK_CODE enum reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "CALLBACK_CODE", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # CALLBACK_CODE enum diff --git a/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md b/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md index 4232ac43f4a..d3173d03ac4 100644 --- a/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md +++ b/docs/build-insights/reference/sdk/other-types/relog-callbacks-struct.md @@ -3,6 +3,7 @@ title: "RELOG_CALLBACKS structure" description: "The C++ Build Insights SDK RELOG_CALLBACKS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_CALLBACKS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RELOG_CALLBACKS structure diff --git a/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md b/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md index 756616dbbc5..36fa65c7679 100644 --- a/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md +++ b/docs/build-insights/reference/sdk/other-types/relog-descriptor-struct.md @@ -3,6 +3,7 @@ title: "RELOG_DESCRIPTOR structure" description: "The C++ Build Insights SDK RELOG_DESCRIPTOR structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_DESCRIPTOR", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RELOG_DESCRIPTOR structure diff --git a/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md b/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md index 103d7f456bc..c82f194f460 100644 --- a/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md +++ b/docs/build-insights/reference/sdk/other-types/relog-retention-system-event-flags-constants.md @@ -3,6 +3,7 @@ title: "RELOG_RETENTION_SYSTEM_EVENT_FLAGS constants" description: "The C++ Build Insights SDK RELOG_RETENTION_SYSTEM_EVENT_FLAGS constants reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RELOG_RETENTION_SYSTEM_EVENT_FLAGS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RELOG_RETENTION_SYSTEM_EVENT_FLAGS constants diff --git a/docs/build-insights/reference/sdk/other-types/result-code-enum.md b/docs/build-insights/reference/sdk/other-types/result-code-enum.md index 6cc9ba32d44..d6ac44cca2b 100644 --- a/docs/build-insights/reference/sdk/other-types/result-code-enum.md +++ b/docs/build-insights/reference/sdk/other-types/result-code-enum.md @@ -3,6 +3,7 @@ title: "RESULT_CODE enum" description: "The C++ Build Insights SDK RESULT_CODE enum reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "RESULT_CODE", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # RESULT_CODE enum diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md b/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md index f54881ad7f1..5bc47f3b439 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-msvc-event-flags-constants.md @@ -3,6 +3,7 @@ title: "TRACING_SESSION_MSVC_EVENT_FLAGS constants" description: "The C++ Build Insights SDK TRACING_SESSION_MSVC_EVENT_FLAGS constants reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_MSVC_EVENT_FLAGS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_MSVC_EVENT_FLAGS constants diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md b/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md index 88116edfe19..f087e51bf38 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-options-struct.md @@ -3,6 +3,7 @@ title: "TRACING_SESSION_OPTIONS structure" description: "Learn about the C++ Build Insights SDK TRACING_SESSION_OPTIONS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_OPTIONS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_OPTIONS structure diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md b/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md index 67374d0acfe..80b32daa9d1 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-statistics-struct.md @@ -3,6 +3,7 @@ title: "TRACING_SESSION_STATISTICS structure" description: "Learn about the C++ Build Insights SDK TRACING_SESSION_STATISTICS structure reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_STATISTICS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_STATISTICS structure diff --git a/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md b/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md index 4e24aea5d9b..129d27038f3 100644 --- a/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md +++ b/docs/build-insights/reference/sdk/other-types/tracing-session-system-event-flags-constants.md @@ -3,6 +3,7 @@ title: "TRACING_SESSION_SYSTEM_EVENT_FLAGS constants" description: "The C++ Build Insights SDK TRACING_SESSION_SYSTEM_EVENT_FLAGS constants reference." ms.date: "02/12/2020" helpviewer_keywords: ["C++ Build Insights", "C++ Build Insights SDK", "TRACING_SESSION_SYSTEM_EVENT_FLAGS", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: reference --- # TRACING_SESSION_SYSTEM_EVENT_FLAGS constants diff --git a/docs/build-insights/reference/vcperf-commands.md b/docs/build-insights/reference/vcperf-commands.md index 1a7924241b4..ed8342bf1b3 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 30f047a6e9d..f9c51225e1d 100644 --- a/docs/build-insights/toc.yml +++ b/docs/build-insights/toc.yml @@ -6,6 +6,16 @@ items: - name: "Tutorials" expanded: true items: + - name: "Get started with GitHub Copilot build performance for Windows" + href: ../build-insights/build-performance.md + - name: "Troubleshoot function inlining impact on build time" + href: ../build-insights/tutorials/build-insights-function-view.md + - name: "Troubleshoot template instantiation impact on build time" + href: ../build-insights/tutorials/build-insights-template-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 00000000000..ac5368e0961 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-function-view.md @@ -0,0 +1,152 @@ +--- +title: "Troubleshoot function inlining impact 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"] +ms.topic: troubleshooting-general +--- +# Troubleshoot function inlining impact 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/o1-o2-minimize-size-maximize-speed.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 that 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 doesn'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 and 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 the 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::: + +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 executes 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 that 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 to 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 + +- Use **File** > **Save As** to save the ETL file to a more permanent location to keep a record of the build time information. You can then compare it to future builds to see how your changes are improving things. +- If you 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](/shows/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 00000000000..3d4422e5572 --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-included-files-view.md @@ -0,0 +1,189 @@ +--- +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"] +ms.topic: how-to +--- +# 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](/shows/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) diff --git a/docs/build-insights/tutorials/build-insights-template-view.md b/docs/build-insights/tutorials/build-insights-template-view.md new file mode 100644 index 00000000000..47382cff0bd --- /dev/null +++ b/docs/build-insights/tutorials/build-insights-template-view.md @@ -0,0 +1,235 @@ +--- +title: "Troubleshoot template instantiation impact on build time" +description: "Tutorial for how to use Build Insights template view to analyze and optimize the impact of template instantiations on build time in your C++ projects." +ms.date: 07/17/2025 +helpviewer_keywords: ["C++ Build Insights", "template instantiation analysis", "build time analysis"] +ms.topic: troubleshooting-general +ai-usage: ai-assisted +--- + +# Troubleshoot template instantiation impact on build time + +Use the Build Insights **Templates** view to see how template instantiation affects C++ build time. It's especially helpful for projects that use lots of templates, like those with template metaprogramming or large generic libraries. + +The **Templates** view works like the Build Insights [Functions view](build-insights-function-view.md). + +## Prerequisites + +- Visual Studio 2022 version 17.10 or later. +- The **C++ Build Insights** component must be installed. Either the Desktop development with C++ workload or the Game development with C++ workload includes it. To check if it's installed, follow these steps: + 1. Open the Visual Studio Installer. + 1. Select **Modify** to change your Visual Studio installation. + 1. On the **Individual components** tab, search for and select **C++ Build Insights**, then select **Close** to finish installing the component. + :::image type="content" source="./media/installer-build-insights.png" alt-text="Screenshot of the Visual Studio Installer. The search box contains C++ Build Insights. The item C++ Build Insights is visible and selected."::: + +## Overview + +Build Insights, integrated into Visual Studio, helps you optimize your build times--especially for large projects like AAA games. Build Insights provides analytics such as the **Templates** view, which shows the time it takes to instantiate each template and which template instantiations add the most to your build time. + +In general, C++ template instantiation happens quickly. In rare cases, some template instantiations can noticeably slow down your build. + +In this article, you create a project that shows how template instantiation affects build time, run Build Insights to analyze the impact, and use those insights to make the build faster. + +## Create a test project + +1. Open Visual Studio and create a new **C++ Console App** project. Name it `TemplateAnalysis`. +1. Create a header file named `Templates.h`, then replace its contents with the following code: + + ```cpp + #pragma once + + #include + #include + + template struct S1 {}; + template using type = std::vector>; + + template struct S2 {}; + + template struct S3 {}; + + template + struct S3> + { + using type = S2)...>; + }; + + inline size_t LargeValue() + { + return sizeof(S3>); + } + + inline size_t SmallValue() + { + return sizeof(S1<5>); + } + ``` + +1. Create a source file named `LargeValue.cpp`, then replace its contents with the following code: + + ```cpp + #include "Templates.h" + + size_t GetLargeValue() + { + return LargeValue(); + } + ``` + +1. Replace the contents of the `TemplateAnalysis.cpp` file with the following code: + + ```cpp + #include "Templates.h" + + extern size_t GetLargeValue(); + + size_t GetSmallValue() + { + return SmallValue(); + } + + int main() + { + size_t largeValue = GetLargeValue(); + size_t smallValue = GetSmallValue(); + return 0; + } + ``` + +## Enable build time data collection + +Template instantiation time collection is off by default to minimize build overhead. To turn it on: + +1. In Visual Studio, go to **Tools** > **Options**. +1. In the **Options** dialog, expand **Build Insights** in the left navigation. +1. Select **Collect Template Instantiation**. +1. To choose where to save the report, select **Store Build Insights reports in this directory** and enter a directory. By default, it's saved in the folder pointed to by the Windows `TEMP` environment variable. +1. Select **OK**. + +:::image type="content" source="./media/tools-options-build-insights.png" alt-text="Screenshot of the project property pages dialog. The settings are open to Build Insights > Trace Collection. The Collect Template Instantiation checkbox is selected."::: + +> [!NOTE] +> Collecting template instantiation times increases build time due to the extra data collected. Only enable it when you want to analyze template instantiation bottlenecks. + +## Run Build Insights to get template instantiation data + +From the main menu, select **Build** > **Run Build Insights on Solution** > **Rebuild**. You can also right-click a project in Solution Explorer and select **Run Build Insights** > **Rebuild**. Choose **Rebuild** instead of **Build** to measure the build time for the entire project. + +:::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. The file name is based on the collection time. + +## Use Templates view to optimize build time + +The **Templates** view lists the template instantiations that contributed significantly to build time. The columns provide information about: + +- **Time [sec, %]** shows how long it takes to instantiate each template 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 template instantiations based on their use of parallel compiler threads. +- **Specialization Name** shows each template instantiation, including the template arguments used. This helps you find which template specializations are most expensive. +- **Translation Unit** shows the source files where each template instantiation happens. Different files can cause the same template instantiation if they include the same header with the template definition. +- **Instantiation File Name** shows where the template is defined. + +:::image type="complex" source="./media/templates-view-before-fix.png" alt-text="Screenshot of the Build Insights Templates view showing expensive template instantiations." lightbox="./media/templates-view-before-fix.png"::: +The Templates view shows two template instantiations of struct S3 taking most (79.448 percent) of the build time. The Translation Unit column shows that both LargeValue.cpp and TemplateAnalysis.cpp are affected. The build time is 4.966 seconds. +:::image-end::: + +- Sort by **Time** to find the templates that take the longest to instantiate. +- Expand a template to see its instantiations and where they happened. +- Use the search box to focus on specific templates. + +### Understanding Templates view results + +To interpret the **Templates** view results: + +- **Empty view**: If nothing shows up in the **Templates** view, template instantiations don't dominate your build time. That's good news because your templates aren't a build bottleneck. +- **Duplicate instantiations**: If the same template instantiation appears multiple times across different translation units, different source files are causing the same expensive instantiation. This is often the biggest optimization opportunity. +- **Threshold filtering**: The view only shows instantiations whose contribution exceeds a certain threshold, so you can focus on the most impactful ones and avoid noise from trivial instantiations. +- **Time aggregation**: The time shown is the total time spent on that specific template instantiation, including any nested instantiations. + +## Improve build time by optimizing template instantiations + +In the example, two template instantiations of `S3` take 79 percent of the build time. The **Translation Unit** column shows that both `LargeValue.cpp` and `TemplateAnalysis.cpp` cause this template instantiation. + +The **Instantiation File Name** and the **Specialization Name** are the same for both entries, which means one expensive template instantiation that affects both source files. That's why the time for each of the two template instantiations is roughly equal. Including `Templates.h` in both source files causes one template instantiation to add significant time to the build. + +From the **Specialization Name** column, the expensive instantiation is `S3>`, which is instantiated in this code in `Templates.h`: + +```cpp +inline size_t LargeValue() +{ + return sizeof(S3>); +} +``` + +There are three main ways to decrease the cost of template instantiations. + +### Remove unused templates + +Check if the expensive template is used. If it isn't, the easiest solution is to remove the function or template. In the example, `LargeValue()` is used in `LargeValue.cpp`, so you can't remove it. + +Consider removing include directives that bring in unnecessary template instantiations. It's easy to forget to remove header files when you aren't using them, and unused includes can significantly affect build time. + +### Move template instantiations to source files + +In this example, rely on the third approach: move the definition that causes the expensive template instantiation to a source file. + +Because `LargeValue.cpp` is the only source file that calls `LargeValue()`, move the definition to `LargeValue.cpp`. This change prevents the template instantiation from happening in every file that includes `Templates.h`. Remove the current definition of `LargeValue()` from `Templates.h` and replace it with a declaration: + +```cpp +size_t LargeValue(); +``` + +Inside `LargeValue.cpp` add the definition: + +```cpp +size_t LargeValue() +{ + return sizeof(S3>); +} +``` + +Rebuild the project and run Build Insights again from the main menu. Select **Build** > **Run Build Insights on Selection** > **Rebuild**. + +The build time decreases. While the template instantiation of `S3` still contributes to the build time, including only necessary template instantiations cuts the build time nearly in half. The count of `S3` instantiations is now one instead of two. + +:::image type="complex" source="./media/templates-view-after-fix.png" alt-text="Screenshot of the Build Insights Templates view after optimization. The view shows reduced template instantiation time." lightbox="./media/templates-view-after-fix.png"::: +The Templates view now shows only one instantiation of S3 instead of two, and the total build time is significantly less at 3.152 seconds. +:::image-end::: + +This technique works well for larger projects. If multiple files include `Templates.h`, each file adds the instantiation time of `LargeValue()` to the total build time. By moving the definition of `LargeValue()` to a dedicated source file, you minimize build time. + +### Optimize the template implementation + +Other optimization techniques include: + +- Use simpler template patterns +- Use `if constexpr` instead of Substitution Failure Is Not An Error (SFINAE) when possible +- Avoid recursive template instantiation patterns that lead to exponential growth + +For more advanced template optimization techniques, see [Build Throughput Series: More Efficient Template Metaprogramming](https://devblogs.microsoft.com/cppblog/build-throughput-series-more-efficient-template-metaprogramming/), which provides detailed examples of reducing template instantiation overhead. + +## Tips + +- Use **File** > **Save As** to save the ETL file to a more permanent location to keep a record of the build time information. You can then compare it to future builds to see how your changes are improving things. +- If you close the Build Insights window, reopen it by finding the *dateandtime*.etl file either where you specified it should be saved, or in your temporary folder. The `TEMP` Windows environment variable provides the path of your temporary files folder. +- Drag columns to change the order of the columns. For example, you might want to move the **Wall Time Responsibility** column to the first column. You can add or hide columns by right-clicking the column header and selecting or deselecting the columns you want. +- The **Templates** view has a filter box to help you find a specific template instantiation. It does partial matches on the name you provide. + +## Troubleshooting + +**Templates view is empty**: This can mean: + +- Your build time isn't dominated by template instantiations. +- Template data collection isn't enabled. To turn it on, see [Enable build time data collection](#enable-build-time-data-collection). +- Do a rebuild instead of a build. The Build Insights window doesn't appear if nothing builds, which can be the case if no files changed since the last build. +- Make sure you're using Visual Studio 2022 17.10 or later, and that the C++ Build Insights component is installed. + +**Build is much slower with Templates view enabled:** This is expected because of the extra data collection. Turn off template instantiation collection when you don't need it. For more information, see [Enable build time data collection](#enable-build-time-data-collection). + +## See also + +- [Build Insights tips and tricks](build-insights-tips.md) +- [#include cleanup in Visual Studio](https://devblogs.microsoft.com/cppblog/include-cleanup-in-visual-studio) +- [Troubleshoot header file impact on build time](build-insights-included-files-view.md) +- [Troubleshoot function inlining on build time](build-insights-function-view.md) +- [Build Insights now available in Visual Studio 2022](https://devblogs.microsoft.com/cppblog/build-insights-now-available-in-visual-studio-2022) +- [Build throughput series: More efficient template metaprogramming](https://devblogs.microsoft.com/cppblog/build-throughput-series-more-efficient-template-metaprogramming) 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 00000000000..45b4517777f --- /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: concept-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](/shows/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 00000000000..4a2f9020811 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 00000000000..98395c240ff 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 00000000000..fcd96f050e7 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 00000000000..e9c751814fe 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 00000000000..1a5c0f85564 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 00000000000..3b33e677bc3 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 00000000000..156abb7646c 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 00000000000..2fe4589daf8 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 00000000000..9df70ef0b9c 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 00000000000..109d81e391d 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 00000000000..9f0483a4cf5 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 00000000000..378c3357819 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 00000000000..d011bb41eef 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 00000000000..629ad3f1258 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 00000000000..42691ef4b66 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 00000000000..e4eee66cf00 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 00000000000..75df957eb5a 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 00000000000..65ad65bcaae 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-build-insights.png b/docs/build-insights/tutorials/media/installer-build-insights.png new file mode 100644 index 00000000000..55e1ec52cf8 Binary files /dev/null and b/docs/build-insights/tutorials/media/installer-build-insights.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 00000000000..152ce06514b 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 00000000000..3eaa8c2df1c 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 00000000000..78510f0af38 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 00000000000..f53b2faf6a5 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 00000000000..4198430bce4 Binary files /dev/null and b/docs/build-insights/tutorials/media/precompiled-header-settings.png differ diff --git a/docs/build-insights/tutorials/media/templates-view-after-fix.png b/docs/build-insights/tutorials/media/templates-view-after-fix.png new file mode 100644 index 00000000000..7acc1cf276c Binary files /dev/null and b/docs/build-insights/tutorials/media/templates-view-after-fix.png differ diff --git a/docs/build-insights/tutorials/media/templates-view-before-fix.png b/docs/build-insights/tutorials/media/templates-view-before-fix.png new file mode 100644 index 00000000000..22bd3ba5fd4 Binary files /dev/null and b/docs/build-insights/tutorials/media/templates-view-before-fix.png differ diff --git a/docs/build-insights/tutorials/media/tools-options-build-insights.png b/docs/build-insights/tutorials/media/tools-options-build-insights.png new file mode 100644 index 00000000000..b0317d247da Binary files /dev/null and b/docs/build-insights/tutorials/media/tools-options-build-insights.png differ diff --git a/docs/build-insights/tutorials/vcperf-and-wpa.md b/docs/build-insights/tutorials/vcperf-and-wpa.md index e4bf41a1e1e..0b8b278a8aa 100644 --- a/docs/build-insights/tutorials/vcperf-and-wpa.md +++ b/docs/build-insights/tutorials/vcperf-and-wpa.md @@ -3,6 +3,7 @@ title: "Tutorial: vcperf and Windows Performance Analyzer" description: "Tutorial on how to use vcperf and WPA for analyzing C++ build traces." ms.date: "11/03/2019" helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: tutorial --- # Tutorial: vcperf and Windows Performance Analyzer diff --git a/docs/build-insights/tutorials/wpa-basics.md b/docs/build-insights/tutorials/wpa-basics.md index 9ac76d830c9..35ad6fe727b 100644 --- a/docs/build-insights/tutorials/wpa-basics.md +++ b/docs/build-insights/tutorials/wpa-basics.md @@ -3,6 +3,7 @@ title: "Tutorial: Windows Performance Analyzer basics" description: "Tutorial on how to complete basic operations in Windows Performance Analyzer." ms.date: "11/03/2019" helpviewer_keywords: ["C++ Build Insights", "throughput analysis", "build time analysis", "vcperf.exe"] +ms.topic: tutorial --- # Tutorial: Windows Performance Analyzer basics diff --git a/docs/build/adding-references-in-visual-cpp-projects.md b/docs/build/adding-references-in-visual-cpp-projects.md index 52d5de1c219..41de401156b 100644 --- a/docs/build/adding-references-in-visual-cpp-projects.md +++ b/docs/build/adding-references-in-visual-cpp-projects.md @@ -4,7 +4,7 @@ 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 +ms.topic: how-to --- # Consuming libraries and components @@ -12,19 +12,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 +162,5 @@ The following properties exist on COM and .NET assembly references, and aren't m ## See also -[C++ project property page reference](reference/property-pages-visual-cpp.md)
+[C++ project property page reference](reference/property-pages-visual-cpp.md)\ [Set C++ compiler and build properties in Visual Studio](working-with-project-properties.md) diff --git a/docs/build/arm-exception-handling.md b/docs/build/arm-exception-handling.md index f2f9b9a13e6..b7cc353313d 100644 --- a/docs/build/arm-exception-handling.md +++ b/docs/build/arm-exception-handling.md @@ -1,8 +1,8 @@ --- -description: "Learn more about: ARM Exception Handling" title: "ARM Exception Handling" +description: "Learn more about: ARM Exception Handling" ms.date: 12/15/2021 -ms.assetid: fe0e615f-c033-4ad5-97f4-ff96af45b201 +ms.topic: concept-article --- # ARM Exception Handling @@ -166,7 +166,7 @@ When the packed unwind format is insufficient to describe the unwinding of a fun |0|20|*X* is a 1-bit field that indicates the presence (1) or absence (0) of exception data.| |0|21|*`E`* is a 1-bit field that indicates that information that describes a single epilogue is packed into the header (1) rather than requiring additional scope words later (0).| |0|22|*F* is a 1-bit field that indicates that this record describes a function fragment (1) or a full function (0). A fragment implies that there's no prologue and that all prologue processing should be ignored.| - |0|23-27|*Epilogue Count* is a 5-bit field that has two meanings, depending on the state of the *`E`* bit:

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

- If *`E`* is 0, this field is a count of the total number of epilogue scopes described in section 2. If more than 31 scopes exist in the function, then this field and the *Code Words* field must both be set to 0 to indicate that an extension word is required.
- If *`E`* is 1, this field specifies the index of the first unwind code that describes the only epilogue.| |0|28-31|*Code Words* is a 4-bit field that specifies the number of 32-bit words required to contain all of the unwind codes in section 4. If more than 15 words are required for more than 63 unwind code bytes, this field and the *Epilogue Count* field must both be set to 0 to indicate that an extension word is required.| |1|0-15|*Extended Epilogue Count* is a 16-bit field that provides more space for encoding an unusually large number of epilogues. The extension word that contains this field is only present if the *Epilogue Count* and *Code Words* fields in the first header word are both set to 0.| |1|16-23|*Extended Code Words* is an 8-bit field that provides more space for encoding an unusually large number of unwind code words. The extension word that contains this field is only present if the *Epilogue Count* and *Code Words* fields in the first header word are both set to 0.| diff --git a/docs/build/arm64-exception-handling.md b/docs/build/arm64-exception-handling.md index f7af2187255..dc383c44181 100644 --- a/docs/build/arm64-exception-handling.md +++ b/docs/build/arm64-exception-handling.md @@ -1,7 +1,7 @@ --- title: "ARM64 exception handling" -description: Describes the exception handling conventions and data used by windows on ARM64. -ms.date: 04/07/2022 +description: "Describes the exception handling conventions and data used by windows on ARM64." +ms.date: 01/13/2023 --- # ARM64 exception handling @@ -39,9 +39,9 @@ These assumptions are made in the exception handling description: - There's no conditional code in epilogs. -- Dedicated frame pointer register: If the sp is saved in another register (x29) in the prolog, that register remains untouched throughout the function. It means the original sp may be recovered at any time. +- Dedicated frame pointer register: If the `sp` is saved in another register (`x29`) in the prolog, that register remains untouched throughout the function. It means the original `sp` may be recovered at any time. -- Unless the sp is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog. +- Unless the `sp` is saved in another register, all manipulation of the stack pointer occurs strictly within the prolog and epilog. - The stack frame layout is organized as described in the next section. @@ -49,7 +49,7 @@ These assumptions are made in the exception handling description: ![Diagram that shows the stack frame layout for functions.](media/arm64-exception-handling-stack-frame.png "stack frame layout") -For frame chained functions, the fp and lr pair can be saved at any position in the local variable area, depending on optimization considerations. The goal is to maximize the number of locals that can be reached by a single instruction based on the frame pointer (x29) or stack pointer (sp). However, for `alloca` functions, it must be chained, and x29 must point to the bottom of stack. To allow for better register-pair-addressing-mode coverage, nonvolatile register save areas are positioned at the top of the Local area stack. Here are examples that illustrate several of the most efficient prolog sequences. For the sake of clarity and better cache locality, the order of storing callee-saved registers in all canonical prologs is in "growing up" order. `#framesz` below represents the size of entire stack (excluding alloca area). `#localsz` and `#outsz` denote local area size (including the save area for the \ pair) and outgoing parameter size, respectively. +For frame chained functions, the `fp` and `lr` pair can be saved at any position in the local variable area, depending on optimization considerations. The goal is to maximize the number of locals that can be reached by a single instruction based on the frame pointer (`x29`) or stack pointer (`sp`). However, for `alloca` functions, it must be chained, and `x29` must point to the bottom of stack. To allow for better register-pair-addressing-mode coverage, nonvolatile register save areas are positioned at the top of the Local area stack. Here are examples that illustrate several of the most efficient prolog sequences. For the sake of clarity and better cache locality, the order of storing callee-saved registers in all canonical prologs is in "growing up" order. `#framesz` below represents the size of entire stack (excluding `alloca` area). `#localsz` and `#outsz` denote local area size (including the save area for the `` pair) and outgoing parameter size, respectively. 1. Chained, #localsz \<= 512 @@ -79,7 +79,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in add x29,sp,#outsz // setup x29 points to bottom of local area ``` -1. Unchained, leaf functions (lr unsaved) +1. Unchained, leaf functions (`lr` unsaved) ```asm stp x19,x20,[sp,#-80]! // pre-indexed, save in 1st FP/INT reg-pair @@ -90,9 +90,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - All locals are accessed based on SP. \ points to the previous frame. For frame size \<= 512, the "sub sp, ..." can be optimized away if the regs saved area is moved to the bottom of stack. The downside is that it's not consistent with other layouts above. And, saved regs take part of the range for pair-regs and pre- and post-indexed offset addressing mode. + All locals are accessed based on `sp`. `` points to the previous frame. For frame size \<= 512, the `sub sp, ...` can be optimized away if the regs saved area is moved to the bottom of stack. The downside is that it's not consistent with other layouts above. And, saved regs take part of the range for pair-regs and pre- and post-indexed offset addressing mode. -1. Unchained, non-leaf functions (lr is saved in Int saved area) +1. Unchained, non-leaf functions (saves `lr` in Int saved area) ```asm stp x19,x20,[sp,#-80]! // pre-indexed, save in 1st FP/INT reg-pair @@ -114,7 +114,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - Only x19 saved: + Only `x19` saved: ```asm sub sp,sp,#16 // reg save area allocation* @@ -122,9 +122,9 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-16) // allocate the remaining local area ``` - \* The reg save area allocation isn't folded into the stp because a pre-indexed reg-lr stp can't be represented with the unwind codes. + \* The reg save area allocation isn't folded into the `stp` because a pre-indexed reg-lr `stp` can't be represented with the unwind codes. - All locals are accessed based on SP. \ points to the previous frame. + All locals are accessed based on `sp`. `` points to the previous frame. 1. Chained, #framesz \<= 512, #outsz = 0 @@ -135,7 +135,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in stp d8,d9,[sp,#(framesz-16)] // save FP pair ``` - Compared to the first prolog example above, this example has an advantage: all register save instructions are ready to execute after only one stack allocation instruction. That means there's no anti-dependence on sp that prevents instruction level parallelism. + Compared to the first prolog example above, this example has an advantage: all register save instructions are ready to execute after only one stack allocation instruction. That means there's no anti-dependence on `sp` that prevents instruction level parallelism. 1. Chained, frame size > 512 (optional for functions without `alloca`) @@ -149,7 +149,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in sub sp,sp,#(framesz-80) // allocate the remaining local area ``` - For optimization purpose, x29 can be put at any position in local area to provide a better coverage for "reg-pair" and pre-/post-indexed offset addressing mode. Locals below frame pointers can be accessed based on SP. + For optimization purpose, `x29` can be put at any position in local area to provide a better coverage for "reg-pair" and pre-/post-indexed offset addressing mode. Locals below frame pointers can be accessed based on `sp`. 1. Chained, frame size > 4K, with or without alloca(), @@ -178,7 +178,7 @@ For frame chained functions, the fp and lr pair can be saved at any position in ### `.pdata` records -The `.pdata` records are an ordered array of fixed-length items that describe every stack-manipulating function in a PE binary. The phrase "stack-manipulating" is significant: leaf functions that don't require any local storage, and don't need to save/restore non-volatile registers, don't require a `.pdata` record. These records should be explicitly omitted to save space. An unwind from one of these functions can get the return address directly from LR to move up to the caller. +The `.pdata` records are an ordered array of fixed-length items that describe every stack-manipulating function in a PE binary. The phrase "stack-manipulating" is significant: leaf functions that don't require any local storage, and don't need to save/restore non-volatile registers, don't require a `.pdata` record. These records should be explicitly omitted to save space. An unwind from one of these functions can get the return address directly from `lr` to move up to the caller. Each `.pdata` record for ARM64 is 8 bytes in length. The general format of each record places the 32-bit RVA of the function start in the first word, followed by a second word that contains either a pointer to a variable-length `.xdata` block, or a packed word describing a canonical function unwinding sequence. @@ -202,7 +202,7 @@ When the packed unwind format is insufficient to describe the unwinding of a fun This data is broken into four sections: -1. A 1 or 2-word header describing the overall size of the structure and providing key function data. The second word is only present if both the **Epilog Count** and **Code Words** fields are set to 0. The header has these bit fields: +1. A 1-word or 2-word header describing the overall size of the structure and providing key function data. The second word is only present if both the **Epilog Count** and **Code Words** fields are set to 0. The header has these bit fields: a. **Function Length** is an 18-bit field. It indicates the total length of the function in bytes, divided by 4. If a function is larger than 1M, then multiple `.pdata` and `.xdata` records must be used to describe the function. For more information, see the [Large functions](#large-functions) section. @@ -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. @@ -271,7 +271,7 @@ Although the prolog and each epilog has its own index into the unwind codes, the ### Unwind codes -The array of unwind codes is a pool of sequences that describe exactly how to undo the effects of the prolog. They're stored in the same order the operations need to be undone. The unwind codes can be thought of as a small instruction set, encoded as a string of bytes. When execution is complete, the return address to the calling function is in the lr register. And, all non-volatile registers are restored to their values at the time the function was called. +The array of unwind codes is a pool of sequences that describe exactly how to undo the effects of the prolog. They're stored in the same order the operations need to be undone. The unwind codes can be thought of as a small instruction set, encoded as a string of bytes. When execution is complete, the return address to the calling function is in the `lr` register. And, all non-volatile registers are restored to their values at the time the function was called. If exceptions were guaranteed to only ever occur within a function body, and never within a prolog or any epilog, then only a single sequence would be necessary. However, the Windows unwinding model requires that code can unwind from within a partially executed prolog or epilog. To meet this requirement, the unwind codes have been carefully designed so they unambiguously map 1:1 to each relevant opcode in the prolog and epilog. This design has several implications: @@ -281,48 +281,66 @@ If exceptions were guaranteed to only ever occur within a function body, and nev - By counting the number of instructions before the end of the prolog, it's possible to skip the equivalent number of unwind codes. We can execute the rest of the sequence to undo only those parts of the prolog that have completed execution. -The unwind codes are encoded according to the table below. All unwind codes are a single/double byte, except the one that allocates a huge stack. There are 21 unwind codes in total. Each unwind code maps exactly one instruction in the prolog/epilog, to allow for unwinding of partially executed prologs and epilogs. +The unwind codes are encoded according to the table below. All unwind codes are a single/double byte, except the one that allocates a huge stack (`alloc_l`). There are 22 unwind codes in total. Each unwind code maps exactly one instruction in the prolog/epilog, to allow for unwinding of partially executed prologs and epilogs. | Unwind code | Bits and interpretation | |--|--| | `alloc_s` | 000xxxxx: allocate small stack with size \< 512 (2^5 * 16). | -| `save_r19r20_x` | 001zzzzz: save \ pair at `[sp-#Z*8]!`, pre-indexed offset >= -248 | -| `save_fplr` | 01zzzzzz: save \ pair at `[sp+#Z*8]`, offset \<= 504. | -| `save_fplr_x` | 10zzzzzz: save \ pair at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -| `alloc_m` | 11000xxx'xxxxxxxx: allocate large stack with size \< 16k (2^11 * 16). | -| `save_regp` | 110010xx'xxzzzzzz: save x(19+#X) pair at `[sp+#Z*8]`, offset \<= 504 | -| `save_regp_x` | 110011xx'xxzzzzzz: save pair x(19+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -| `save_reg` | 110100xx'xxzzzzzz: save reg x(19+#X) at `[sp+#Z*8]`, offset \<= 504 | -| `save_reg_x` | 1101010x'xxxzzzzz: save reg x(19+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | -| `save_lrpair` | 1101011x'xxzzzzzz: save pair \ at `[sp+#Z*8]`, offset \<= 504 | -| `save_fregp` | 1101100x'xxzzzzzz: save pair d(8+#X) at `[sp+#Z*8]`, offset \<= 504 | -| `save_fregp_x` | 1101101x'xxzzzzzz: save pair d(8+#X), at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | -| `save_freg` | 1101110x'xxzzzzzz: save reg d(8+#X) at `[sp+#Z*8]`, offset \<= 504 | -| `save_freg_x` | 11011110'xxxzzzzz: save reg d(8+#X) at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | +| `save_r19r20_x` | 001zzzzz: save `` pair at `[sp-#Z*8]!`, pre-indexed offset >= -248 | +| `save_fplr` | 01zzzzzz: save `` pair at `[sp+#Z*8]`, offset \<= 504. | +| `save_fplr_x` | 10zzzzzz: save `` pair at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `alloc_m` | 11000xxx'xxxxxxxx: allocate large stack with size \< 32K (2^11 * 16). | +| `save_regp` | 110010xx'xxzzzzzz: save `x(19+#X)` pair at `[sp+#Z*8]`, offset \<= 504 | +| `save_regp_x` | 110011xx'xxzzzzzz: save pair `x(19+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `save_reg` | 110100xx'xxzzzzzz: save reg `x(19+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_reg_x` | 1101010x'xxxzzzzz: save reg `x(19+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | +| `save_lrpair` | 1101011x'xxzzzzzz: save pair `` at `[sp+#Z*8]`, offset \<= 504 | +| `save_fregp` | 1101100x'xxzzzzzz: save pair `d(8+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_fregp_x` | 1101101x'xxzzzzzz: save pair `d(8+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -512 | +| `save_freg` | 1101110x'xxzzzzzz: save reg `d(8+#X)` at `[sp+#Z*8]`, offset \<= 504 | +| `save_freg_x` | 11011110'xxxzzzzz: save reg `d(8+#X)` at `[sp-(#Z+1)*8]!`, pre-indexed offset >= -256 | +| `alloc_z` | 11011111'zzzzzzzz: allocate stack with size `z * SVE-VL` | | `alloc_l` | 11100000'xxxxxxxx'xxxxxxxx'xxxxxxxx: allocate large stack with size \< 256M (2^24 * 16) | -| `set_fp` | 11100001: set up x29: with: `mov x29,sp` | -| `add_fp` | 11100010'xxxxxxxx: set up x29 with: `add x29,sp,#x*8` | +| `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` | 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 | -| | 11101010: Custom stack for MSFT_OP_CONTEXT | -| | 11101100: Custom stack for MSFT_OP_CLEAR_UNWOUND_TO_CALL | -| | 1111xxxx: reserved | +| | 11101000: Custom stack for `MSFT_OP_TRAP_FRAME` | +| | 11101001: Custom stack for `MSFT_OP_MACHINE_FRAME` | +| | 11101010: Custom stack for `MSFT_OP_CONTEXT` | +| | 11101011: Custom stack for `MSFT_OP_EC_CONTEXT` | +| | 11101100: Custom stack for `MSFT_OP_CLEAR_UNWOUND_TO_CALL` | +| | 11101101: reserved | +| | 11101110: reserved | +| | 11101111: reserved | +| | 11110xxx: reserved | +| | 11111000'yyyyyyyy : reserved | +| | 11111001'yyyyyyyy'yyyyyyyy : reserved | +| | 11111010'yyyyyyyy'yyyyyyyy'yyyyyyyy : reserved | +| | 11111011'yyyyyyyy'yyyyyyyy'yyyyyyyy'yyyyyyyy : reserved | +| `pac_sign_lr` | 11111100: sign the return address in `lr` with `pacibsp` | +| | 11111101: reserved | +| | 11111110: reserved | +| | 11111111: reserved | In instructions with large values covering multiple bytes, the most significant bits are stored first. This design makes it possible to find the total size in bytes of the unwind code by looking up only the first byte of the code. Since each unwind code is exactly mapped to an instruction in a prolog or epilog, you can compute the size of the prolog or epilog. Walk from the sequence start to the end, and use a lookup table or similar device to determine the length of the corresponding opcode. -Post-indexed offset addressing isn't allowed in a prolog. All offset ranges (#Z) match the encoding of STP/STR addressing except `save_r19r20_x`, in which 248 is sufficient for all save areas (10 Int registers + 8 FP registers + 8 input registers). +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 of a separated `end` unwind code for tail-call scenarios. +Since the sizes of regular return and jump instructions are the same, there's no need for a separated `end` unwind code in tail-call scenarios. -`end_c` is designed to handle noncontiguous function fragments for optimization purposes. An `end_c` that indicates the end of unwind codes in the current scope must be followed by another series of unwind code ended with a real `end`. The unwind codes between `end_c` and `end` represent the prolog operations in the parent region ("phantom" prolog). More details and examples are described in the section below. +`end_c` is designed to handle noncontiguous function fragments for optimization purposes. An `end_c` that indicates the end of unwind codes in the current scope must be followed by another series of unwind codes ending with a real `end`. The unwind codes between `end_c` and `end` represent the prolog operations in the parent region (a "phantom" prolog). More details and examples are described in the section below. ### Packed unwind data @@ -343,10 +361,10 @@ The fields are as follows: - **Function Length** is an 11-bit field providing the length of the entire function in bytes, divided by 4. If the function is larger than 8k, a full `.xdata` record must be used instead. - **Frame Size** is a 9-bit field indicating the number of bytes of stack that is allocated for this function, divided by 16. Functions that allocate greater than (8k-16) bytes of stack must use a full `.xdata` record. It includes the local variable area, outgoing parameter area, callee-saved Int and FP area, and home parameter area. It excludes the dynamic allocation area. - **CR** is a 2-bit flag indicating whether the function includes extra instructions to set up a frame chain and return link: - - 00 = unchained function, \ pair isn't saved in stack. - - 01 = unchained function, \ is saved in stack - - 10 = reserved; - - 11 = chained function, a store/load pair instruction is used in prolog/epilog \ + - 00 = unchained function, `` pair isn't saved in stack + - 01 = unchained function, `` is saved in stack + - 10 = chained function with a `pacibsp` signed return address + - 11 = chained function, a store/load pair instruction is used in prolog/epilog `` - **H** is a 1-bit flag indicating whether the function homes the integer parameter registers (x0-x7) by storing them at the very start of the function. (0 = doesn't home registers, 1 = homes registers). - **RegI** is a 4-bit field indicating the number of non-volatile INT registers (x19-x28) saved in the canonical stack location. - **RegF** is a 3-bit field indicating the number of non-volatile FP registers (d8-d15) saved in the canonical stack location. (RegF=0: no FP register is saved; RegF>0: RegF+1 FP registers are saved). Packed unwind data can't be used for function that save only one FP register. @@ -355,38 +373,41 @@ Canonical prologs that fall into categories 1, 2 (without outgoing parameter are Step 0: Pre-compute of the size of each area. -Step 1: Save Int callee-saved registers. +Step 1: Sign the return address. -Step 2: This step is specific for type 4 in early sections. lr is saved at the end of Int area. +Step 2: Save Int callee-saved registers. -Step 3: Save FP callee-saved registers. +Step 3: This step is specific for type 4 in early sections. `lr` is saved at the end of Int area. -Step 4: Save input arguments in the home parameter area. +Step 4: Save FP callee-saved registers. -Step 5: Allocate remaining stack, including local area, \ pair, and outgoing parameter area. 5a corresponds to canonical type 1. 5b and 5c are for canonical type 2. 5d and 5e are for both type 3 and type 4. +Step 5: Save input arguments in the home parameter area. + +Step 6: Allocate remaining stack, including local area, `` pair, and outgoing parameter area. 6a corresponds to canonical type 1. 6b and 6c are for canonical type 2. 6d and 6e are for both type 3 and type 4. | Step # | Flag values | # of instructions | Opcode | Unwind code | |--|--|--|--|--| | 0 | | | `#intsz = RegI * 8;`
`if (CR==01) #intsz += 8; // lr`
`#fpsz = RegF * 8;`
`if(RegF) #fpsz += 8;`
`#savsz=((#intsz+#fpsz+8*8*H)+0xf)&~0xf)`
`#locsz = #famsz - #savsz` | -| 1 | 0 < **RegI** <= 10 | **RegI** / 2 +
**RegI** % 2 | `stp x19,x20,[sp,#savsz]!`
`stp x21,x22,[sp,#16]`
`...` | `save_regp_x`
`save_regp`
`...` | -| 2 | **CR** == 01\* | 1 | `str lr,[sp,#(intsz-8)]`\* | `save_reg` | -| 3 | 0 < **RegF** <= 7 | (**RegF** + 1) / 2 +
(**RegF** + 1) % 2) | `stp d8,d9,[sp,#intsz]`\*\*
`stp d10,d11,[sp,#(intsz+16)]`
`...`
`str d(8+RegF),[sp,#(intsz+fpsz-8)]` | `save_fregp`
`...`
`save_freg` | -| 4 | **H** == 1 | 4 | `stp x0,x1,[sp,#(intsz+fpsz)]`
`stp x2,x3,[sp,#(intsz+fpsz+16)]`
`stp x4,x5,[sp,#(intsz+fpsz+32)]`
`stp x6,x7,[sp,#(intsz+fpsz+48)]` | `nop`
`nop`
`nop`
`nop` | -| 5a | **CR** == 11 &&
`#locsz` <= 512 | 2 | `stp x29,lr,[sp,#-locsz]!`
`mov x29,sp`\*\*\* | `save_fplr_x`
`set_fp` | -| 5b | **CR** == 11 &&
512 < `#locsz` <= 4080 | 3 | `sub sp,sp,#locsz`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`save_fplr`
`set_fp` | -| 5c | **CR** == 11 &&
`#locsz` > 4080 | 4 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`alloc_s`/`alloc_m`
`save_fplr`
`set_fp` | -| 5d | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` <= 4080 | 1 | `sub sp,sp,#locsz` | `alloc_s`/`alloc_m` | -| 5e | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` > 4080 | 2 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)` | `alloc_m`
`alloc_s`/`alloc_m` | +| 1 | **CR** == 10 | 1 | `pacibsp` | `pac_sign_lr` | +| 2 | 0 < **RegI** <= 10 | **RegI** / 2 +
**RegI** % 2 | `stp x19,x20,[sp,#savsz]!`
`stp x21,x22,[sp,#16]`
`...` | `save_regp_x`
`save_regp`
`...` | +| 3 | **CR** == 01\* | 1 | `str lr,[sp,#(intsz-8)]`\* | `save_reg` | +| 4 | 0 < **RegF** <= 7 | (**RegF** + 1) / 2 +
(**RegF** + 1) % 2) | `stp d8,d9,[sp,#intsz]`\*\*
`stp d10,d11,[sp,#(intsz+16)]`
`...`
`str d(8+RegF),[sp,#(intsz+fpsz-8)]` | `save_fregp`
`...`
`save_freg` | +| 5 | **H** == 1 | 4 | `stp x0,x1,[sp,#(intsz+fpsz)]`
`stp x2,x3,[sp,#(intsz+fpsz+16)]`
`stp x4,x5,[sp,#(intsz+fpsz+32)]`
`stp x6,x7,[sp,#(intsz+fpsz+48)]` | `nop`
`nop`
`nop`
`nop` | +| 6a | (**CR** == 10 \|\| **CR** == 11) &&
`#locsz` <= 512 | 2 | `stp x29,lr,[sp,#-locsz]!`
`mov x29,sp`\*\*\* | `save_fplr_x`
`set_fp` | +| 6b | (**CR** == 10 \|\| **CR** == 11) &&
512 < `#locsz` <= 4080 | 3 | `sub sp,sp,#locsz`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`save_fplr`
`set_fp` | +| 6c | (**CR** == 10 \|\| **CR** == 11) &&
`#locsz` > 4080 | 4 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)`
`stp x29,lr,[sp,0]`
`add x29,sp,0` | `alloc_m`
`alloc_s`/`alloc_m`
`save_fplr`
`set_fp` | +| 6d | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` <= 4080 | 1 | `sub sp,sp,#locsz` | `alloc_s`/`alloc_m` | +| 6e | (**CR** == 00 \|\| **CR** == 01) &&
`#locsz` > 4080 | 2 | `sub sp,sp,4080`
`sub sp,sp,#(locsz-4080)` | `alloc_m`
`alloc_s`/`alloc_m` | -\* If **CR** == 01 and **RegI** is an odd number, Step 2 and 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. +\*\* If **RegI** == 0, **CR** != 01, and **RegF** != 0, the first `stp` for the floating-point does the predecrement to adjust sp to allocate space for the FP/SIMD save area. -\*\*\* No instruction corresponding to `mov x29,sp` is present in the epilog. Packed unwind data can't be used if a function requires restoration of sp from x29. +\*\*\* No instruction corresponding to `mov x29,sp` is present in the epilog. Packed unwind data can't be used if a function requires restoration of `sp` from `x29`. ### Unwinding partial prologs and epilogs -In the most common unwinding situations, the exception or call occurs in the body of the function, away from the prolog and all epilogs. In these situations, unwinding is straightforward: the unwinder simply executes the codes in the unwind array. It begins at index 0 and continues until an end opcode is detected. +In the most common unwinding situations, the exception or call occurs in the body of the function, away from the prolog and all epilogs. In these situations, unwinding is straightforward: the unwinder simply executes the codes in the unwind array. It begins at index 0 and continues until an `end` opcode is detected. It's more difficult to correctly unwind in the case where an exception or interrupt occurs while executing a prolog or epilog. In these situations, the stack frame is only partially constructed. The problem is to determine exactly what's been done, to correctly undo it. @@ -413,11 +434,11 @@ So, for both the prolog and epilog, we're left with a common set of unwind codes The epilog case is straightforward, since it's in normal order. Starting at offset 0 within the epilog (which starts at offset 0x100 in the function), we'd expect the full unwind sequence to execute, as no cleanup has yet been done. If we find ourselves one instruction in (at offset 2 in the epilog), we can successfully unwind by skipping the first unwind code. We can generalize this situation, and assume a 1:1 mapping between opcodes and unwind codes. Then, to start unwinding from instruction *n* in the epilog, we should skip the first *n* unwind codes, and begin executing from there. -It turns out that a similar logic works for the prolog, except in reverse. If we start unwinding from offset 0 in the prolog, we want to execute nothing. If we unwind from offset 2, which is one instruction in, then we want to start executing the unwind sequence one unwind code from the end. (Remember, the codes are stored in reverse order.) And here too, we can generalize: if we start unwinding from instruction n in the prolog, we should start executing n unwind codes from the end of the list of codes. +It turns out that a similar logic works for the prolog, except in reverse. If we start unwinding from offset 0 in the prolog, we want to execute nothing. If we unwind from offset 2, which is one instruction in, then we want to start executing the unwind sequence one unwind code from the end. (Remember, the codes are stored in reverse order.) And here too, we can generalize: if we start unwinding from instruction *n* in the prolog, we should start executing *n* unwind codes from the end of the list of codes. Prolog and epilog codes don't always match exactly, which is why the unwind array may need to contain several sequences of codes. To determine the offset of where to begin processing codes, use the following logic: -1. If unwinding from within the body of the function, begin executing unwind codes at index 0 and continue until hitting an "end" opcode. +1. If unwinding from within the body of the function, begin executing unwind codes at index 0 and continue until hitting an `end` opcode. 1. If unwinding from within an epilog, use the epilog-specific starting index provided with the epilog scope as a starting point. Compute how many bytes the PC in question is from the start of the epilog. Then advance forward through the unwind codes, skipping unwind codes until all of the already-executed instructions are accounted for. Then execute starting at that point. @@ -427,11 +448,11 @@ These rules mean the unwind codes for the prolog must always be the first in the ### Function fragments -For code optimization purposes and other reasons, it may be preferable to split a function into separated fragments (also called regions). When split, each resulting function fragment requires its own separate `.pdata` (and possibly `.xdata`) record. +For code optimization purposes and other reasons, it may be preferable to split a function into separated fragments (also called *regions*). When split, each resulting function fragment requires its own separate `.pdata` (and possibly `.xdata`) record. For each separated secondary fragment that has its own prolog, it's expected that no stack adjustment is done in its prolog. All stack space required by a secondary region must be pre-allocated by its parent region (or called host region). This preallocation keeps stack pointer manipulation strictly in the function's original prolog. -A typical case of function fragments is "code separation" with that compiler may move a region of code out of its host function. There are three unusual cases that could be resulted by code separation. +A typical case of function fragments is "code separation", where the compiler may move a region of code out of its host function. There are three unusual cases that could result from code separation. #### Example @@ -474,7 +495,7 @@ A typical case of function fragments is "code separation" with that compiler may 1. Epilogs only (region 2: prolog is in host region) - It's assumed that by the time control jumping into this region, all prolog codes have been executed. Partial unwind can happen in epilogs the same way as in a normal function. This type of region can't be represented by compact `.pdata`. In full `.xdata` record, it can be encoded with a "phantom" prolog, bracketed by an `end_c` and `end` unwind code pair. The leading `end_c` indicates the size of prolog is zero. Epilog start index of the single epilog points to `set_fp`. + It's assumed that by the time control jumps into this region, all prolog codes have been executed. Partial unwind can happen in epilogs the same way as in a normal function. This type of region can't be represented by compact `.pdata`. In a full `.xdata` record, it can be encoded with a "phantom" prolog, bracketed by an `end_c` and `end` unwind code pair. The leading `end_c` indicates the size of prolog is zero. Epilog start index of the single epilog points to `set_fp`. Unwind code for region 2: `end_c`, `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. @@ -515,7 +536,7 @@ Another more complicated case of function fragments is "shrink wrapping." The co In the prolog of region 1, stack space is pre-allocated. You can see that region 2 will have the same unwind code even it's moved out of its host function. -Region 1: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end` with Epilog Start Index points to `set_fp` as usual. +Region 1: `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. Epilog Start Index points to `set_fp` as usual. Region 2: `save_regp 2, 224`, `end_c`, `set_fp`, `save_regp 0,240`, `save_fplr_x_256`, `end`. Epilog Start Index points to first unwind code `save_regp 2, 224`. @@ -538,7 +559,7 @@ If a fragment has no prolog and no epilog, it still requires its own `.pdata` (a sub sp,sp,#0x810 // alloc_m stp fp,lr,[sp] // save_fplr mov fp,sp // set_fp - // end of prolog + // end of prolog ... |$pdata$Foo| diff --git a/docs/build/arm64-windows-abi-conventions.md b/docs/build/arm64-windows-abi-conventions.md index e3fb94d10ca..0d4f98ff387 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" +description: "Learn more about: Overview of ARM64 ABI conventions" +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`](../c-runtime-library/reference/controlfp-s.md) 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,9 +256,9 @@ 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 -[Common Visual C++ ARM Migration Issues](common-visual-cpp-arm-migration-issues.md)
+[Common Microsoft C++ ARM Migration Issues](common-visual-cpp-arm-migration-issues.md)
[ARM64 exception handling](arm64-exception-handling.md) diff --git a/docs/build/arm64ec-windows-abi-conventions.md b/docs/build/arm64ec-windows-abi-conventions.md index 23baee4aaee..4cd9117c777 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 @@ -9,7 +9,7 @@ ARM64EC is an application binary interface (ABI) that enables ARM64 binaries to For more information on the x64 and ARM64 ABIs, see [Overview of x64 ABI conventions](x64-software-conventions.md) and [Overview of ARM64 ABI conventions](arm64-windows-abi-conventions.md). -ARM64EC doesn't solve memory model differences between x64 and ARM based architectures. For more information, see [Common Visual C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md). +ARM64EC doesn't solve memory model differences between x64 and ARM based architectures. For more information, see [Common Microsoft C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md). ## Definitions @@ -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. @@ -166,12 +172,6 @@ When the helper then returns to the thunk, the thunk: 1. Pops the ARM64EC `lr` register 1. Executes an ARM64 `ret lr` instruction. -## x64 Unwinding of an ARM64EC function - -### Recovering the return address - -At the beginning of an x64 function, the stack pointer points to the return address that was pushed onto the stack by the caller's `call` instruction. In contrast, at the beginning of an ARM64EC function, the return address is in the `lr` register, set by the caller's `bl` instruction. Therefore, when unwinding the deepest frame of a stack, if the frame corresponds to an ARM64EC function, the x64 unwinder must recreate the value of ARM64EC `lr` by reading the value stashed in the x87 registers when the exception occurred. In addition, the new x64 unwind code `UWOP_SAVE_RET` handles the prolog saving ARM64EC `lr` to the stack. - ## ARM64EC function name decoration An ARM64EC function name has a secondary decoration applied after any language-specific decoration. For functions with C linkage (whether compiled as C or by using `extern "C"`), a `#` is prepended to the name. For C++ decorated functions, a `$$h` tag is inserted into the name. @@ -188,5 +188,5 @@ The ARM64EC toolchain currently doesn't support `__vectorcall`. The compiler emi ## See also [Understanding ARM64EC ABI and assembly code](/windows/arm/arm64ec-abi)\ -[Common Visual C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md)\ +[Common Microsoft C++ ARM migration issues](common-visual-cpp-arm-migration-issues.md)\ [Decorated names](./reference/decorated-names.md) diff --git a/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md b/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md index 6d15a9df762..8a247863e48 100644 --- a/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md +++ b/docs/build/building-c-cpp-isolated-applications-and-side-by-side-assemblies.md @@ -4,14 +4,15 @@ title: "Building C/C++ Isolated Applications and Side-by-side Assemblies" ms.date: "05/06/2019" helpviewer_keywords: ["isolated applications [C++]", "WinSxS [C++]", "native assembly cache [C++]", "builds [C++], isolated applications", "side-by-side applications [C++]", "builds [C++], side-by-side assemblies"] ms.assetid: 9465904e-76f7-48bd-bb3f-c55d8f1699b6 +ms.topic: concept-article --- # Building C/C++ Isolated Applications and Side-by-side Assemblies Visual Studio supports a deployment model for Windows client applications based on the idea of [isolated applications](/windows/win32/SbsCs/isolated-applications) and [side-by-side assemblies](/windows/win32/SbsCs/about-side-by-side-assemblies-). By default, Visual Studio builds all native C/C++ applications as isolated applications that use [manifests](/windows/win32/sbscs/manifests) to describe their dependencies on Visual C++ libraries. -Building C/C++ programs as isolated applications presents a range of advantages. For example, an isolated application is unaffected when other C/C++ applications install or uninstall Visual C++ libraries. Visual C++ libraries used by isolated applications may still be redistributed in either the application's local folder, or by installation to the native assembly cache (WinSxS); however, servicing of Visual C++ libraries for already deployed applications can be simplified by using a [publisher configuration file](/windows/win32/SbsCs/publisher-configuration). The isolated application deployment model makes it easier to ensure that C/C++ applications that are running on a specific computer use the most recent version of Visual C++ libraries, while still leaving open the possibility for system administrators and application authors to control explicit version binding of applications to their dependent DLLs. +Building C/C++ programs as isolated applications presents a range of advantages. For example, an isolated application is unaffected when other C/C++ applications install or uninstall Microsoft C++ libraries. Microsoft C++ libraries used by isolated applications may still be redistributed in either the application's local folder, or by installation to the native assembly cache (WinSxS); however, servicing of Microsoft C++ libraries for already deployed applications can be simplified by using a [publisher configuration file](/windows/win32/SbsCs/publisher-configuration). The isolated application deployment model makes it easier to ensure that C/C++ applications that are running on a specific computer use the most recent version of Microsoft C++ libraries, while still leaving open the possibility for system administrators and application authors to control explicit version binding of applications to their dependent DLLs. -This section discusses how you can build your C/C++ application as an isolated application and ensure that it binds to Visual C++ libraries using a manifest. The information in this section primarily applies to native, or unmanaged, C++ applications. For information about deploying native C++ applications built with Visual Studio, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). +This section discusses how you can build your C/C++ application as an isolated application and ensure that it binds to Microsoft C++ libraries using a manifest. The information in this section primarily applies to native, or unmanaged, C++ applications. For information about deploying native C++ applications built with Visual Studio, see [Redistributing Microsoft C++ Files](../windows/redistributing-visual-cpp-files.md). ## In This Section diff --git a/docs/build/building-c-cpp-isolated-applications.md b/docs/build/building-c-cpp-isolated-applications.md index 6494e2dd386..8724e842f8c 100644 --- a/docs/build/building-c-cpp-isolated-applications.md +++ b/docs/build/building-c-cpp-isolated-applications.md @@ -4,6 +4,7 @@ title: "Building C/C++ Isolated Applications" ms.date: "05/06/2019" helpviewer_keywords: ["isolated applications [C++]"] ms.assetid: 8a2fe4fa-0489-433e-bfc6-495844d8d73a +ms.topic: concept-article --- # Building C/C++ Isolated Applications diff --git a/docs/build/building-c-cpp-side-by-side-assemblies.md b/docs/build/building-c-cpp-side-by-side-assemblies.md index 615b2c1d3bb..29478d8b6ed 100644 --- a/docs/build/building-c-cpp-side-by-side-assemblies.md +++ b/docs/build/building-c-cpp-side-by-side-assemblies.md @@ -4,6 +4,7 @@ title: "Building C/C++ Side-by-side Assemblies" ms.date: "11/04/2016" helpviewer_keywords: ["side-by-side applications [C++]"] ms.assetid: 7fa20b16-3737-4f76-a0b5-1dacea19a1e8 +ms.topic: concept-article --- # Building C/C++ Side-by-side Assemblies diff --git a/docs/build/building-on-the-command-line.md b/docs/build/building-on-the-command-line.md index 39ca5932e69..5f7a2fdff45 100644 --- a/docs/build/building-on-the-command-line.md +++ b/docs/build/building-on-the-command-line.md @@ -1,14 +1,14 @@ --- -title: "Use the Microsoft C++ toolset from the command line" -description: "Use the Microsoft C++ (MSVC) compiler toolset from the command line outside of the Visual Studio IDE." +title: "Use the Microsoft C++ Build Tools from the command line" +description: "Use the Microsoft C++ (MSVC) Build Tools from the command line outside of the Visual Studio IDE." ms.custom: "conceptual" ms.date: 04/07/2022 +ms.topic: how-to helpviewer_keywords: ["command-line builds [C++]", "compiling source code [C++], command line", "builds [C++], command-line", "command line [C++], building from", "command line [C++], compilers"] -ms.assetid: 7ca9daed-a003-4162-842d-908f79058365 --- -# Use the Microsoft C++ toolset from the command line +# Use the Microsoft C++ Build Tools from the command line -You can build C and C++ applications on the command line by using tools that are included in Visual Studio. The Microsoft C++ (MSVC) compiler toolset is also downloadable as a standalone package. You don't need to install the Visual Studio IDE if you don't plan to use it. +You can build C and C++ applications on the command line by using tools that are included in Visual Studio. The Microsoft C++ (MSVC) Build Tools are also downloadable as a standalone package. You don't need to install the Visual Studio IDE if you don't plan to use it. > [!NOTE] > This article is about how to set up an environment to use the individual compilers, linkers, librarian, and other basic tools. The native project build system in Visual Studio, based on MSBuild, doesn't use the environment as described in this article. For more information on how to use MSBuild from the command line, see [MSBuild on the command line - C++](msbuild-visual-cpp.md). @@ -17,18 +17,18 @@ You can build C and C++ applications on the command line by using tools that are ::: moniker range=">=msvc-160" -If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015, 2017, or 2019 toolsets, select the optional MSVC v140, v141, or v142 build tools. When you're satisfied with your selections, choose **Install**. +If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/). On the downloads page, expand the **Tools for Visual Studio** section to find the Build Tools download. When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015, 2017, or 2019 toolsets, select the optional MSVC v140, v141, or v142 build tools. When you're satisfied with your selections, choose **Install**. ::: moniker-end ::: moniker range="<=msvc-150" -If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio 2017](https://my.visualstudio.com/Downloads?q=2017). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Visual C++ build tools** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 toolset, select the optional MSVC v140 build tools. When you're satisfied with your selections, choose **Install**. +If you've installed Visual Studio and a C++ workload, you have all the command-line tools. For information on how to install C++ and Visual Studio, see [Install C++ support in Visual Studio](vscpp-step-0-installation.md). If you only want the command-line toolset, download the [Build Tools for Visual Studio 2017](https://my.visualstudio.com/Downloads?q=2017). When you run the downloaded executable, it updates and runs the Visual Studio Installer. To install only the tools you need for C++ development, select the **Desktop development with C++** workload. You can select optional libraries and toolsets to include under **Installation details**. To build code by using the Visual Studio 2015 toolset, select the optional MSVC v140 build tools. When you're satisfied with your selections, choose **Install**. ::: moniker-end ## How to use the command-line tools -When you choose one of the C++ workloads in the Visual Studio Installer, it installs the Visual Studio *platform toolset*. A platform toolset has all the C and C++ tools for a specific Visual Studio version. The tools include the C/C++ compilers, linkers, assemblers, and other build tools, and matching libraries and header files. You can use all of these tools at the command line. They're also used internally by the Visual Studio IDE. There are separate x86-hosted and x64-hosted compilers and tools to build code for x86, x64, ARM, and ARM64 targets. Each set of tools for a particular host and target build architecture is stored in its own directory. +When you choose one of the C++ workloads in the Visual Studio Installer, by default, it installs a particular version of the MSVC Build Tools package. For Visual Studio 2022 and earlier, this is organized by a *platform toolset* (v### version format) that has all the C and C++ tools for a specific version of Visual Studio. For Visual Studio 2026 and later, this consists of the MSVC version (v##.## version format), which has all the C and C++ tools for that particular MSVC package. The MSVC version is decoupled from the Visual Studio version. The tools include the C/C++ compilers, linkers, assemblers, and other build tools, and matching libraries and header files. You can use all of these tools at the command-line. They're also used internally by the Visual Studio IDE. There are separate x86-hosted and x64-hosted compilers and tools that build code for x86, x64, ARM, and ARM64 targets. Each set of tools for a particular host and target build architecture is stored in its own directory. To work correctly, the tools require several specific environment variables to be set. These variables are used to add the tools to the path, and to set the locations of include files, library files, and SDKs. To make it easy to set these environment variables, the installer creates customized *command files*, or batch files, during installation. You can run one of these command files to set a specific host and target build architecture, Windows SDK version, and platform toolset. For convenience, the installer also creates shortcuts in your Start menu. The shortcuts open developer command prompt windows by using these command files for specific combinations of host and target. These shortcuts ensure all the required environment variables are set and ready to use. @@ -79,13 +79,16 @@ 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. ::: moniker range=">= msvc-170" -The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2019, the typical installation location on a 64-bit system is in *`\Program Files\Microsoft Visual Studio\2022\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. +The command file location depends on the version of Visual Studio you installed, and on choices you made during installation. For Visual Studio 2022, the typical installation location on a 64-bit system is in *`\Program Files\Microsoft Visual Studio\2022\`*. The *``* may be Community, Professional, Enterprise, BuildTools, or another nickname you supplied. ::: moniker-end ::: moniker range="= msvc-160" @@ -108,12 +111,12 @@ The primary developer command prompt command file, *`VsDevCmd.bat`*, is located ::: moniker range=">= msvc-150" -More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2017 and Visual Studio 2019, you'll find them in the VC\\Auxiliary\\Build subdirectory. +More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2017 and Visual Studio 2019, you'll find them in the *`VC\Auxiliary\Build`* subdirectory. ::: moniker-end ::: moniker range="< msvc-150" -More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2015, they're located in the VC, VC\\bin, or VC\\bin\\*architecture* subdirectories, where *architecture* is one of the native or cross-compiler options. +More command files are available to set up specific build architectures. The command files available depend on the Visual Studio workloads and options you've installed. In Visual Studio 2015, they're located in the *`VC`*, *`VC\bin`*, or *`VC\bin\`* subdirectories, where *``* is one of the native or cross-compiler options. ::: moniker-end @@ -144,10 +147,10 @@ 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: +*`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: | *`architecture`* | Compiler | Host computer architecture | Build output (target) architecture | |--|--|--|--| @@ -160,13 +163,13 @@ This optional argument specifies the host and target architecture to use. If *ar | `amd64_arm` or `x64_arm` | ARM on x64 cross | x64 | ARM | | `amd64_arm64` or `x64_arm64` | ARM64 on x64 cross | x64 | ARM64 | -*`platform_type`*
+*`platform_type`*\ This optional argument allows you to specify **`store`** or **`uwp`** as the platform type. By default, the environment is set to build desktop or console apps. -*`winsdk_version`*
+*`winsdk_version`*\ Optionally specifies the version of the Windows SDK to use. By default, the latest installed Windows SDK is used. To specify the Windows SDK version, you can use a full Windows SDK number such as **`10.0.10240.0`**, or specify **`8.1`** to use the Windows 8.1 SDK. -*`vcversion`*
+*`vcversion`*\ Optionally specifies the Visual Studio compiler toolset to use. By default, the environment is set to use the current Visual Studio compiler toolset. ::: moniker range=">= msvc-160" @@ -191,11 +194,13 @@ Leave this parameter out to use libraries without Spectre mitigations. Use the v #### To set up the build environment in an existing command prompt window -1. At the command prompt, use the CD command to change to the Visual Studio installation directory. Then, use CD again to change to the subdirectory that contains the configuration-specific command files. For Visual Studio 2019 and Visual Studio 2017, use the *VC\\Auxiliary\\Build* subdirectory. For Visual Studio 2015, use the *VC* subdirectory. +1. At the command prompt, use the `CD` command to change to the Visual Studio installation directory. Then, use `CD` again to change to the subdirectory that contains the configuration-specific command files. For Visual Studio 2019 and Visual Studio 2017, use the *`VC\Auxiliary\Build`* subdirectory. For Visual Studio 2015, use the *`VC`* subdirectory. 1. Enter the command for your preferred developer environment. For example, to build ARM code for UWP on a 64-bit platform, using the latest Windows SDK and Visual Studio compiler toolset, use this command line: - `vcvarsall.bat amd64_arm uwp` + ```cmd + vcvarsall.bat amd64_arm uwp + ``` ## Create your own command prompt shortcut @@ -203,21 +208,27 @@ Leave this parameter out to use libraries without Spectre mitigations. Use the v Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **x64 Native Tools Command Prompt for VS 2019** shortcut is something similar to: -`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat"` +```cmd +%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvars64.bat" +``` ::: moniker-end ::: moniker range="= msvc-150" Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **x64 Native Tools Command Prompt for VS 2017** shortcut is something similar to: -`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat"` +```cmd +%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvars64.bat" +``` ::: moniker-end ::: moniker range="< msvc-150" Open the Properties dialog for a developer command prompt shortcut to see the command target used. For example, the target for the **VS2015 x64 Native Tools Command Prompt** shortcut is something similar to: -`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64` +```cmd +%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 +``` ::: moniker-end @@ -225,49 +236,55 @@ The architecture-specific batch files set the *`architecture`* parameter and cal ::: moniker range=">= msvc-160" -`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.29` +```cmd +%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2019\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.29 +``` ::: moniker-end ::: moniker range="= msvc-150" -`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.19` +```cmd +%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio\2017\Community\VC\Auxiliary\Build\vcvarsall.bat" amd64_arm uwp -vcvars_ver=14.19 +``` ::: moniker-end ::: moniker range="< msvc-150" -`%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 -vcvars_ver=14.0` +```cmd +%comspec% /k "C:\Program Files (x86)\Microsoft Visual Studio 14.0\VC\vcvarsall.bat" amd64 -vcvars_ver=14.0 +``` ::: moniker-end -Adjust the path to reflect your Visual Studio installation directory. The vcvarsall.bat file has additional information about specific version numbers. +Adjust the path to reflect your Visual Studio installation directory. The *`vcvarsall.bat`* file has additional information about specific version numbers. ## Command-line tools To build a C/C++ project at a command prompt, Visual Studio provides these command-line tools: -[`CL`](reference/compiling-a-c-cpp-program.md)
-Use the compiler (cl.exe) to compile and link source code files into apps, libraries, and DLLs. +[`CL`](reference/compiling-a-c-cpp-program.md)\ +Use the compiler (`cl.exe`) to compile and link source code files into apps, libraries, and DLLs. -[`Link`](reference/linking.md)
-Use the linker (link.exe) to link compiled object files and libraries into apps and DLLs. +[`Link`](reference/linking.md)\ +Use the linker (`link.exe`) to link compiled object files and libraries into apps and DLLs. -When you build on the command line, the F1 command isn't available for instant help. Instead, you can use a search engine to get information about warnings, errors, and messages. You can also download and use the offline help files. To use the search in docs.microsoft.com, enter your query in the search box at the top of any article. +When you build on the command line, the F1 command isn't available for instant help. Instead, you can use a search engine to get information about warnings, errors, and messages. You can also download and use the offline help files. To use the search in Microsoft Learn, enter your query in the search box at the top of any article. ## Command-line project management tools By default, the Visual Studio IDE uses native project build systems based on MSBuild. You can invoke MSBuild directly to build projects without using the IDE. You can also use the `devenv` command to use Visual Studio to build projects and solutions. Visual Studio also supports build systems based on CMake or NMake. [`MSBuild`](msbuild-visual-cpp.md)\ -Use MSBuild (msbuild.exe) and a project file (.vcxproj) to configure a build and invoke the toolset without loading the Visual Studio IDE. It's equivalent to running the **Build** project or **Build Solution** command in the Visual Studio IDE. MSBuild has advantages over the IDE when you build at the command line. You don't have to install the full IDE on all your build servers and build pipelines. You avoid the extra overhead of the IDE. MSBuild runs in containerized build environments, and supports a [binary logger](https://msbuildlog.com/). +Use MSBuild (`msbuild.exe`) and a project file (`.vcxproj`) to configure a build and invoke the toolset without loading the Visual Studio IDE. It's equivalent to running the **Build** project or **Build Solution** command in the Visual Studio IDE. MSBuild has advantages over the IDE when you build at the command line. You don't have to install the full IDE on all your build servers and build pipelines. You avoid the extra overhead of the IDE. MSBuild runs in containerized build environments, and supports a [binary logger](https://msbuildlog.com/). [`DEVENV`](/visualstudio/ide/reference/devenv-command-line-switches)\ -Use DEVENV (devenv.exe) combined with a command-line switch such as **`/Build`** or **`/Clean`** to execute certain build commands without displaying the Visual Studio IDE. +Use DEVENV (`devenv.exe`) combined with a command-line switch such as **`/Build`** or **`/Clean`** to execute certain build commands without displaying the Visual Studio IDE. [`CMake`](../build/cmake-projects-in-visual-studio.md)\ -CMake (cmake.exe) is a cross-platform, open-source tool for defining build processes that run on multiple platforms. CMake can configure and control native build tools for its supported platforms, such as MSBuild and Make. For more information about CMake, see the [CMake documentation](https://cmake.org/cmake/help/latest/index.html#). +CMake (`cmake.exe`) is a cross-platform, open-source tool for defining build processes that run on multiple platforms. CMake can configure and control native build tools for its supported platforms, such as MSBuild and Make. For more information about CMake, see the [CMake documentation](https://cmake.org/cmake/help/latest/index.html#). [`NMAKE`](reference/nmake-reference.md)\ -Use NMAKE (nmake.exe) to build C++ projects by using a traditional makefile. +Use NMAKE (`nmake.exe`) to build C++ projects by using a traditional makefile. > [!NOTE] > Starting in Visual Studio 2019 version 16.5, MSBuild and DEVENV don't use the command-line environment to control the toolset and libraries used. @@ -276,36 +293,36 @@ Use NMAKE (nmake.exe) to build C++ projects by using a traditional makefile. These articles show how to build apps on the command line, and describe how to customize the command-line build environment. Some show how to use 64-bit toolsets, and target x86, x64, ARM, and ARM64 platforms. They also describe use of the command-line build tools MSBuild and NMAKE. -[Walkthrough: Compiling a native C++ program on the command line](walkthrough-compiling-a-native-cpp-program-on-the-command-line.md)
+[Walkthrough: Compiling a native C++ program on the command line](walkthrough-compiling-a-native-cpp-program-on-the-command-line.md)\ Gives an example that shows how to create and compile a C++ program on the command line. -[Walkthrough: Compile a C program on the command line](walkthrough-compile-a-c-program-on-the-command-line.md)
+[Walkthrough: Compile a C program on the command line](walkthrough-compile-a-c-program-on-the-command-line.md)\ Describes how to compile a program written in the C programming language. -[Walkthrough: Compiling a C++/CLI program on the command line](walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md)
+[Walkthrough: Compiling a C++/CLI program on the command line](walkthrough-compiling-a-cpp-cli-program-on-the-command-line.md)\ Describes how to create and compile a C++/CLI program that uses the .NET Framework. -[Walkthrough: Compiling a C++/CX program on the command line](walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md)
+[Walkthrough: Compiling a C++/CX program on the command line](walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md)\ Describes how to create and compile a C++/CX program that uses the Windows Runtime. -[NMAKE reference](reference/nmake-reference.md)
-Provides links to articles that describe the Microsoft Program Maintenance Utility (NMAKE.EXE). +[NMAKE reference](reference/nmake-reference.md)\ +Provides links to articles that describe the Microsoft Program Maintenance Utility (`NMAKE.EXE`). -[MSBuild on the command line - C++](msbuild-visual-cpp.md)
-Provides links to articles that discuss how to use msbuild.exe from the command line. +[MSBuild on the command line - C++](msbuild-visual-cpp.md)\ +Provides links to articles that discuss how to use `msbuild.exe` from the command line. ## Related sections -[/MD, /MT, /LD (Use run-time library)](reference/md-mt-ld-use-run-time-library.md)
+[`/MD`, `/MT`, `/LD` (Use run-time library)](reference/md-mt-ld-use-run-time-library.md)\ Describes how to use these compiler options to use a Debug or Release run-time library. -[C/C++ compiler options](reference/compiler-options.md)
-Provides links to articles that discuss the C and C++ compiler options and CL.exe. +[C/C++ compiler options](reference/compiler-options.md)\ +Provides links to articles that discuss the C and C++ compiler options and `CL.exe`. -[MSVC linker options](reference/linker-options.md)
-Provides links to articles that discuss the linker options and LINK.exe. +[MSVC linker options](reference/linker-options.md)\ +Provides links to articles that discuss the linker options and `LINK.exe`. -[Additional MSVC build tools](reference/c-cpp-build-tools.md)
+[Additional MSVC build tools](reference/c-cpp-build-tools.md)\ Provides links to the C/C++ build tools that are included in Visual Studio. ## See also diff --git a/docs/build/calling-dll-functions-from-visual-basic-applications.md b/docs/build/calling-dll-functions-from-visual-basic-applications.md index bf6850d0f5b..38bcce3a900 100644 --- a/docs/build/calling-dll-functions-from-visual-basic-applications.md +++ b/docs/build/calling-dll-functions-from-visual-basic-applications.md @@ -4,6 +4,7 @@ title: "Calling DLL Functions from Visual Basic Applications" ms.date: "11/04/2016" helpviewer_keywords: ["functions [C++], calling DLL functions from Visual Basic", "DLL functions [C++]", "function calls [C++], DLL functions", "DLLs [C++], calling", "calling DLL functions from VB applications [C++]", "__stdcall keyword [C++]", "DLL functions [C++], calling"] ms.assetid: 282f7fbf-a0f2-4b9f-b277-1982710be56c +ms.topic: concept-article --- # Calling DLL Functions from Visual Basic Applications diff --git a/docs/build/checking-for-memory-overwrites.md b/docs/build/checking-for-memory-overwrites.md index 786540319e2..5c8869aca10 100644 --- a/docs/build/checking-for-memory-overwrites.md +++ b/docs/build/checking-for-memory-overwrites.md @@ -4,6 +4,7 @@ title: "Checking for Memory Overwrites" ms.date: "11/04/2016" helpviewer_keywords: ["memory, overwrites"] ms.assetid: da7c5d77-a267-415f-a8ab-ee5ce5bfc286 +ms.topic: concept-article --- # Checking for Memory Overwrites diff --git a/docs/build/clang-support-cmake.md b/docs/build/clang-support-cmake.md index 6ae9039afb1..4b74bd679fc 100644 --- a/docs/build/clang-support-cmake.md +++ b/docs/build/clang-support-cmake.md @@ -21,22 +21,23 @@ You can use Visual Studio with Clang to edit and debug C++ CMake projects that t **Linux**: For Linux CMake projects, no special Visual Studio support is required. You can install Clang using your distro's package manager, and add the appropriate commands in the CMakeLists.txt file. ## Install - ::: moniker-end ::: moniker range="msvc-160" -For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. When using a custom Clang installation, check the **C++ Clang-cl for v142 build tools** component. +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **C++ Clang-cl for v142 build tools** or **C++ Clang-cl for v143 build tools** component. + +:::image type="content" source="media/clang-install-vs2019.png" alt-text="Screenshot of the Visual Studio Installer Individual Components page. C++ Clang Compiler For Windows and C++ Clang-cl for v142 build tools are selected."::: ::: moniker-end ::: moniker range="msvc-170" -For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. When using a custom Clang installation, check the **C++ Clang-cl for v143 build tools** component. +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have those, you can install them by opening the Visual Studio Installer and choosing **C++ Clang compiler for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose the **MSBuild support for LLVM (clang-cl) toolset** component. + +:::image type="content" source="media/clang-install-vs2022.png" alt-text="Screenshot of the Visual Studio Installer Individual Components page. C++ Clang Compiler For Windows and MSBuild support for LLVM are selected."::: ::: moniker-end ::: moniker range=">=msvc-160" -![Screenshot of the Visual Studio Installer Individual Components page that shows Clang components available for installation.](media/clang-install-vs2019.png) - ## Create a new configuration To add a new Clang configuration to a CMake project: @@ -45,11 +46,11 @@ To add a new Clang configuration to a CMake project: 1. Under **Configurations**, press the **Add Configuration** button: - ![Screenshot of the controls at the top of the C Make Settings dialog, with the Add Configuration control highlighted.](media/cmake-add-config-icon.png) + :::image type="content" source="media/cmake-add-config-icon.png" alt-text="Screenshot of the controls at the top of the C Make Settings dialog. The Add Configuration button is highlighted."::: 1. Choose the desired Clang configuration (note that separate Clang configurations are provided for Windows and Linux), then press **Select**: - ![Screenshot of the Add Configuration to C Make Settings dialog for Clang configuration.](media/cmake-clang-configuration.png) + :::image type="content" source="media/cmake-clang-configuration.png" alt-text="Screenshot of the Add Configuration to C Make Settings dialog for Clang configuration. Contains entries such as Mingw64-Release, x86-Debug, x64-Debug, x86-Clang Debug, and so on."::: 1. To make modifications to this configuration, use the **CMake Settings Editor**. For more information, see [Customize CMake build settings in Visual Studio](customize-cmake-settings.md). @@ -61,7 +62,7 @@ To modify an existing configuration to use Clang, follow these steps: 1. Under **General** select the **Toolset** dropdown and choose the desired Clang toolset: - ![Screenshot of the General dialog box showing that the Toolset is selected and clang cl x 86 is highlighted.](media/cmake-clang-toolset.png) + ![Screenshot of the General dialog box showing the Toolset drop-down and clang cl x 86 is highlighted.](media/cmake-clang-toolset.png) ## Custom Clang locations @@ -72,7 +73,7 @@ By default, Visual Studio looks for Clang in two places: You can specify another location by setting the **CMAKE_C_COMPILER** and **CMAKE_CXX_COMPILER** CMake variables in **CMake Settings**: -![Screenshot of the C Make Settings dialog box with the C Make C X X Compiler highlighted.](media/clang-location-cmake.png) +:::image type="content" source="media/clang-location-cmake.png" alt-text="Screenshot of the C Make Settings dialog box with the C Make C X X Compiler highlighted. C Make configurations are listed such as x64-Clang-Debug, Linux-Clang-Release, and so on." Lightbox="media/clang-location-cmake.png"::: ## Clang compatibility modes @@ -82,10 +83,10 @@ You can modify these values in **CMake Settings** under **CMake variables and ca ## Edit, build, and debug -After you have set up a Clang configuration, you can build and debug the project. Visual Studio detects that you are using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. +After you have set up a Clang configuration, you can build and debug the project. Visual Studio detects that you're using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. -When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue are not available for Clang configurations. +When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. Some compiler-dependent features such as Edit and Continue aren't available for Clang configurations. -![Screenshot of the Visual Studio debugger debugging a CMake Clang project.](media/clang-debug-visualize.png) +:::image type="content" source="media/clang-debug-visualize.png" alt-text="Screenshot of the Visual Studio debugger debugging a CMake Clang project."::: ::: moniker-end diff --git a/docs/build/clang-support-msbuild.md b/docs/build/clang-support-msbuild.md index 87b4dad496c..8741b608e9b 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: 06/29/2022 +description: "Learn more about: Clang/LLVM support in Visual Studio projects" +ms.date: 12/11/2025 ms.description: "Configure a Visual Studio MSBuild project to use the Clang/LLVM toolchain." helpviewer_keywords: ["Clang support for C++ MSBuild projects"] --- @@ -9,31 +9,59 @@ helpviewer_keywords: ["Clang support for C++ MSBuild projects"] ::: moniker range="<=msvc-150" -Clang support for both CMake and MSBuild projects is available in Visual Studio 2019. +Clang/LLVM support for both CMake and MSBuild projects is available in Visual Studio 2019 and Visual Studio 2022. ::: moniker-end - ::: moniker range=">=msvc-160" -You can use Visual Studio 2019 version 16.2 and later with Clang to edit, build, and debug C++ Visual Studio projects (MSBuild) that target Windows or Linux. +You can use Visual Studio 2019 version 16.2 and later with Clang/LLVM to edit, build, and debug C++ Visual Studio projects (MSBuild) that target Windows or Linux. + +::: moniker-end +::: moniker range="=msvc-160" ## Install -For best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **C++ Clang-cl for v142 build tools**. +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **C++ Clang-cl for v142 build tools** or **C++ Clang-cl for v143 build tools**. +::: moniker-end +::: moniker range=">=msvc-170" +## Install + +For the best IDE support in Visual Studio, we recommend using the latest Clang compiler tools for Windows. If you don't already have the tools, you can install them by opening the Visual Studio Installer and choosing **C++ Clang tools for Windows** under **Desktop development with C++** optional components. You may prefer to use an existing Clang installation on your machine; if so, choose **MSBuild support for LLVM (clang-cl) toolset**. +::: moniker-end +::: moniker range=">=msvc-160" The Microsoft C++ Standard Library requires at least Clang 8.0.0. +::: moniker-end + +::: moniker range="=msvc-160" +:::image type="complex" source="media/clang-install-vs2019.png" alt-text="Screenshot of the Visual Studio 2019 installer"::: +The Individual components tab is selected in the installer. C++ Clang Compiler for Windows is selected. C++ Clang-cl for v142 build tools (x64/x86) is also selected. +:::image-end::: + +::: moniker-end +::: moniker range=">=msvc-170" +:::image type="complex" source="media/clang-install-vs2022.png" alt-text="Screenshot of the Visual Studio 2022 installer." +The Individual components tab is selected in the installer. C++ Clang Compiler for Windows is selected. MSBuild support for LLVM (clang-cl) toolset is also selected. +::: image-end ::: + +::: moniker-end + +::: moniker range=">=msvc-160" +Later versions of Visual Studio provide newer versions of the Clang toolset. The bundled version of Clang gets updated automatically to stay current with updates in the Microsoft implementation of the Standard Library. For example, Visual Studio 2019 version 16.11 includes Clang v12. -![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) +The LLVM experience in Visual Studio delivers seamless build support, project system integration, and design-time features that work with your choice of LLVM distributions. For acquisition convenience, we provide an optional LLVM binary distribution with Visual Studio. This LLVM toolset is provided as-is, sourced directly from the [LLVM Foundation’s release page](https://github.com/llvm/llvm-project/releases) without modifications by Microsoft. The installed binaries are digitally signed with a third-party Microsoft code signing certificate to mark their third-party status and to confirm that they were obtained from the LLVM Foundation’s release page. -Later versions of Visual Studio provide newer versions of the Clang toolset. The bundled version of Clang gets updated automatically to stay current with updates in the Microsoft implementation of the Standard Library. For example, Visual Studio 2019 version 16.9 includes Clang v11. +LLVM updates in Visual Studio are typically aligned with major LLVM releases ahead of a Visual Studio general release. However, if the community or partners report security or critical blocking issues addressed in a minor LLVM release, we prioritize updating the bundled LLVM toolset to a newer minor version containing the fix. Visual Studio’s build and project system supports using your own custom LLVM installation if needed. ## Configure a Windows project to use Clang tools To configure a Visual Studio project to use Clang, right-click on the project node in **Solution Explorer** and choose **Properties**. Typically, you should first choose **All configurations** at the top of the dialog. Then, under **General** > **Platform Toolset**, choose **LLVM (clang-cl)** and then **OK**. -![Screenshot of the Property Pages dialog box with Configuration Properties > General selected and the Platform Toolset and LLVM (clang-cl) option highlighted.](media/llvm-msbuild-prop-page.png) +:::image type="complex" source="media/llvm-msbuild-prop-page.png" alt-text="Screenshot of the Visual Studio project Property Pages dialog box."::: +The project properties page is open to the Configuration Properties > General page. The Platform Toolset dropdown is selected, on which LLVM (clang-cl) is selected. +:::image-end::: -If you're using the Clang tools that are bundled with Visual Studio, no extra steps are required. For Windows projects, Visual Studio by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode. It links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in *%VCINSTALLDIR%\\Tools\\Llvm\\bin\\* and *%VCINSTALLDIR%\\Tools\\Llvm\\x64\\bin\\*. +If you're using the Clang tools that are bundled with Visual Studio, no extra steps are required. For Windows projects, Visual Studio by default invokes Clang in [clang-cl](https://llvm.org/devmtg/2014-04/PDFs/Talks/clang-cl.pdf) mode. It links with the Microsoft implementation of the Standard Library. By default, **clang-cl.exe** is located in *`%VCINSTALLDIR%\Tools\Llvm\bin\`* and *`%VCINSTALLDIR%\Tools\Llvm\x64\bin\`*. If you're using a custom Clang installation, you can change the value of the `LLVMInstallDir` property. For more information, see [Set a custom LLVM location](#custom_llvm_location). @@ -48,33 +76,34 @@ To configure a Visual Studio Linux project to use Clang: 1. Under **General** > **Platform Toolset**, choose **Clang for Windows Subsystem for Linux** if you're using Windows Subsystem for Linux (WSL). Choose **Clang for Remote Linux** if you're using a remote machine or VM. 1. Press **OK**. -![Screenshot of the Console App clang Visual Studio 2019 Property Pages dialog box with Configuration Properties > General selected and the Platform Toolset and L L V M (clang c l) options highlighted.](media/clang-msbuild-prop-page.png) +:::image type="complex" source="media/clang-msbuild-prop-page.png" alt-text="Screenshot of the Visual Studio 2019 project Property Pages dialog box"::: +The project properties page is open to the Configuration Properties > General page. Platform Toolset is selected and from the list of options, LLVM (clang- c l) is selected." +:::image-end::: On Linux, Visual Studio by default uses the first Clang location that it finds in the PATH environment property. If you're using a custom Clang installation, then either change the value of the `LLVMInstallDir` property or else enter the path under **Project** > **Properties** > **Configuration Properties** > **VC++ DIrectories** > **Executable Directories**. For more information, see [Set a custom LLVM location](#custom_llvm_location). -## Set a custom LLVM location +## Set a custom LLVM location and toolset -You can set a custom path to LLVM for one or more projects by creating a *Directory.build.props* file. Then, add that file to the root folder of any project. You can add it to the root solution folder to apply it to all projects in the solution. The file should look like this (but use your actual LLVM path): +To set a custom path to LLVM and set a custom LLVM toolset version for one or more projects, create a *Directory.build.props* file. Then, add that file to the root folder of any project. You can add it to the root solution folder to apply it to all projects in the solution. The file should look like this example (but use your actual LLVM path and version number): ```xml C:\MyLLVMRootDir + 15.0.0 ``` -You can combine this property with a custom LLVM toolset version. For more information, see [Set a custom LLVM toolset version](#custom_llvm_toolset). +## Set a custom LLVM toolset version in the IDE -## Set a custom LLVM toolset version +Starting in Visual Studio 2019 version 16.9, you can set a custom toolset version for LLVM in Visual Studio. To set this property in a project: -Starting in Visual Studio 2019 version 16.9, you can set a custom toolset version for LLVM. To set this property in a project in Visual Studio: - -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](./working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties](./working-with-project-properties.md). 1. Select the **Configuration Properties** > **General** property page. -1. Modify the **Platform Toolset** property to *LLVM (clang-cl)*, if it isn't already set. +1. Modify the **Platform Toolset** property to *LLVM (clang-cl)*, if it isn't already set. Choose **Apply** to save your changes. 1. Select the **Configuration Properties** > **Advanced** property page. @@ -82,35 +111,16 @@ Starting in Visual Studio 2019 version 16.9, you can set a custom toolset versio The **LLVM Toolset Version** property only appears when the LLVM platform toolset is selected. -You can set the toolset version for one or more projects by creating a *Directory.build.props* file. Then, add that file to the root folder of any project. Add it to the root solution folder to apply it to all projects in the solution. The file should look like this (but use your actual LLVM path): - -```xml - - - 11.0.0 - - -``` - -You can also combine this property with a custom LLVM location. For example, your *Directory.build.props* file could look like: - -```xml - - - C:\MyLLVMRootDir - 11.0.0 - - -``` - -When you add a *Directory.build.props* file, the settings appear as the default in the project Property Pages dialog. However, changes to these properties in Visual Studio override the settings in the *Directory.build.props* file. +When you add a `Directory.build.props` file to a project or solution, the settings appear as the default in the project Property Pages dialog. However, changes to these properties in Visual Studio override the settings in the `Directory.build.props` file. -## Set additional properties, edit, build, and debug +## Set properties, edit, build, and debug -After you have set up a Clang configuration, right-click again on the project node and choose **Reload project**. You can now build and debug the project using the Clang tools. Visual Studio detects that you're using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. The project property pages for a Clang configuration are similar to the ones for MSVC. However, some compiler-dependent features such as Edit and Continue aren't available for Clang configurations. You can set a Clang compiler or linker option that isn't available in the property pages. Add it manually in the property pages under **Configuration Properties** > **C/C++ (or Linker)** > **Command Line** > **Additional Options**. +After you set up a Clang configuration, right-click again on the project node and choose **Reload project**. You can now build and debug the project using the Clang tools. Visual Studio detects that you're using the Clang compiler and provides IntelliSense, highlighting, navigation, and other editing features. Errors and warnings are displayed in the **Output Window**. The project property pages for a Clang configuration are similar to the ones for MSVC. However, some compiler-dependent features such as Edit and Continue aren't available for Clang configurations. You can set a Clang compiler or linker option that isn't available in the property pages. Add it manually in the property pages under **Configuration Properties** > **C/C++ (or Linker)** > **Command Line** > **Additional Options**. When debugging, you can use breakpoints, memory and data visualization, and most other debugging features. -![Screenshot of Visual Studio showing Clang debugging.](media/clang-debug-msbuild.png) +:::image type="complex" source="media/clang-debug-msbuild.png" alt-text="Screenshot of Visual Studio debugging a sample app"::: +The portion of the app that's visible creates a string vector and adds some strings to it. Execution stopped on a breakpoint for the code v.push_back("Clang/LLVM");. +:::image-end::: ::: moniker-end diff --git a/docs/build/cmake-predefined-configuration-reference.md b/docs/build/cmake-predefined-configuration-reference.md index d9597573d8d..36e2fa06ee1 100644 --- a/docs/build/cmake-predefined-configuration-reference.md +++ b/docs/build/cmake-predefined-configuration-reference.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: CMake predefined build configurations" title: "CMake predefined configuration reference" +description: "Learn more about: CMake predefined build configurations" ms.description: "Visual Studio provides several predefined build configurations for CMake projects on Linux, Windows, ARM, and IoT." ms.date: 08/03/2021 helpviewer_keywords: ["CMake redefined configurations"] @@ -30,7 +30,7 @@ In a CMake project, build configurations are stored in a *`CMakeSettings.json`* When you choose a configuration, it's added to the *`CMakeSettings.json`* file in the project's root folder. You can then use it to build your project. For information about the configuration properties, see [CMakeSettings reference](cmakesettings-reference.md). -## Linux predefined build configurations: +## Linux predefined build configurations ```json { diff --git a/docs/build/cmake-presets-vs.md b/docs/build/cmake-presets-vs.md index 4835e4feba0..62d80010a54 100644 --- a/docs/build/cmake-presets-vs.md +++ b/docs/build/cmake-presets-vs.md @@ -1,8 +1,10 @@ --- title: Configure and build with CMake Presets description: "Reference for using CMake Presets to configure and build CMake projects." -ms.date: 04/07/2022 +ms.date: 06/09/2023 ms.topic: reference +ms.custom: sfi-image-nochange +ai-usage: ai-assisted --- # Configure and build with CMake Presets in Visual Studio @@ -19,24 +21,33 @@ This article contains information about *`CMakePresets.json`* integration with V We recommend *`CMakePresets.json`* as an alternative to *`CMakeSettings.json`*. Visual Studio never reads from both *`CMakePresets.json`* and *`CMakeSettings.json`* at the same time. To enable or disable *`CMakePresets.json`* integration in Visual Studio, see [Enable `CMakePresets.json` in Visual Studio 2019](#enable-cmakepresets-json-integration). -## Supported CMake and *`CMakePresets.json`* versions +## Supported CMake and *`CMakePresets.json`* versions -Visual Studio supports version 2 or later for the *`CMakePresets.json`* and *`CMakeUserPresets.json`* files. You can update your file version by incrementing the version field in the root object. For an example and more information, see [`CMakePresets.json` format](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#format). +The supported *`CMakePresets.json`* and *`CMakeUserPresets.json`* schema versions depend on your version of Visual Studio: +- Visual Studio 2019 version 16.10 and later support schema versions 2 and 3. +- Visual Studio 2022 version 17.4 preview 1 adds support for schema version 4. +- Visual Studio 2022 version 17.5 preview 1 adds support for schema version 5. -CMake version 3.20 or later is required when you're invoking CMake with *`CMakePresets.json`* (version 2 or later) from the command line. However, Visual Studio reads and evaluates *`CMakePresets.json`* and *`CMakeUserPresets.json`* itself and doesn't invoke CMake directly with the `--preset` option. So, CMake version 3.20 or later isn't strictly required when you're building with *`CMakePresets.json`* inside Visual Studio. We recommend using CMake version 3.14 or later. +You can update the version by changing the `"version"` field in the root object. For an example and more information, see [`CMakePresets.json` format](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html#format). -## Enable *`CMakePresets.json`* integration in Visual Studio +CMake version 3.20 or later is required when you're invoking CMake with *`CMakePresets.json`* from the command line. However, Visual Studio reads and evaluates *`CMakePresets.json`* and *`CMakeUserPresets.json`* itself and doesn't invoke CMake directly with the `--preset` option. So, CMake version 3.20 or later isn't strictly required when you're building with *`CMakePresets.json`* inside Visual Studio. + +We recommend using at least CMake version 3.14 or later. + +## Enable *`CMakePresets.json`* integration in Visual Studio *`CMakePresets.json`* integration isn't enabled by default in Visual Studio. You can enable it in **Tools** > **Options** > **CMake** > **General**: -![Screenshot showing the checkbox to enable CMakePresets.json on the CMake General page of the Tools Options dialog in Visual Studio 2022 version 17.1.](./media/enable-cmakepresets-new.png) +:::image type="complex" source="./media/enable-cmakepresets-new.png" alt-text="Screenshot showing 'Always use CMakePresets.json' selected."::: +This screen is reached from the Visual Studio 2022 menu: Tools > Options > CMake > General. The option is under the CMake configure file section. +:::image-end::: -> [!Important] +> [!IMPORTANT] > Close and reopen the folder in Visual Studio to activate the integration. In 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 +121,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 +190,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). @@ -193,29 +206,33 @@ The official [CMake documentation](https://cmake.org/cmake/help/latest/manual/cm ### Select your compilers -You can set C and C++ compilers by using `cacheVariables.CMAKE_C_COMPILER` and `cacheVariables.CMAKE_CXX_COMPILER` in a Configure Preset. It's equivalent to passing `-D CMAKE_C_COMPILER=` and `-D CMAKE_CXX_COMPILER=` to CMake from the command line. For more information, see [`CMAKE__COMPILER`](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_COMPILER.html#cmake-lang-compiler). +You can set C and C++ compilers by using `environment.CC` and `environment.CXX` in a Configure Preset. For more information, see [`CC`](https://cmake.org/cmake/help/latest/envvar/CC.html)/[`CXX`](https://cmake.org/cmake/help/latest/envvar/CXX.html). Use the following examples to build with `cl.exe` and `clang-cl.exe` from Visual Studio. The C++ Clang tools for Windows components must be installed for you to build with `clang-cl`. Build with `cl.exe`: ```json +"environment": { + "CC": "cl", + "CXX": "cl" +}, "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug", - "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}", - "CMAKE_C_COMPILER": "cl", - "CMAKE_CXX_COMPILER": "cl" + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}" }, ``` Build with `clang`: ```json +"environment": { + "CC": "clang-cl", + "CXX": "clang-cl" +}, "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug", "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}", - "CMAKE_C_COMPILER": "clang-cl", - "CMAKE_CXX_COMPILER": "clang-cl" }, "vendor": { @@ -249,14 +266,16 @@ For more information on generators that support the `toolset` specification, see To reproduce these builds outside Visual Studio, see [Run CMake from the command line or a CI pipeline](#run-cmake-from-the-command-line-or-a-ci-pipeline). -To build on Linux or without the Visual C++ toolset, specify the name of a compiler on your `PATH` instance, or an environment variable that evaluates to the full path of a compiler. Full paths are discouraged so that the file can remain shareable. A preset that builds with GCC version 8 might look like this: +To build on Linux or without the Microsoft C++ (MSVC) Build Tools, specify the name of a compiler on your `PATH` instance, or an environment variable that evaluates to the full path of a compiler. Full paths are discouraged so that the file can remain shareable. A preset that builds with GCC version 8 might look like this: ```json +"environment": { + "CC": "gcc-8", + "CXX": "g++-8" +}, "cacheVariables": { "CMAKE_BUILD_TYPE": "Debug", - "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}", - "CMAKE_C_COMPILER": "gcc-8", - "CMAKE_CXX_COMPILER": "g++-8" + "CMAKE_INSTALL_PREFIX": "${sourceDir}/out/install/${presetName}" }, ``` @@ -272,7 +291,7 @@ Set `architecture.strategy` and `toolset.strategy` to `set` when you're building You can set the configuration type (`Debug` or `Release`) for single configuration generators by using `cacheVariables.CMAKE_BUILD_TYPE`. It's equivalent to passing `-D CMAKE_BUILD_TYPE=` to CMake from the command line. For more information, see [`CMAKE_BUILD_TYPE`](https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html). -### Select your target and host architecture when building with the Visual C++ toolset +### Select your target and host architecture when building with the Microsoft C++ Build Tools You can set the target architecture (x64, Win32, ARM64, or ARM) by using `architecture.value`. It's equivalent to passing `-A` to CMake from the command line. For more information, see [Platform Selection](https://cmake.org/cmake/help/latest/generator/Visual%20Studio%2016%202019.html#platform-selection). @@ -376,11 +395,11 @@ 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`* +## Variable substitution in *`launch.vs.json`* and *`tasks.vs.json`* *`CMakePresets.json`* supports variable substitution in *`launch.vs.json`* and *`tasks.vs.json`*. Here are some considerations: @@ -425,7 +444,7 @@ Instead, enable and disable AddressSanitizer by setting the required compiler an You can add the following sample to *`CMakeLists.txt`* to enable or disable AddressSanitizer for a target: -```cmd +```txt option(ASAN_ENABLED "Build this target with AddressSanitizer" ON) if(ASAN_ENABLED) @@ -442,13 +461,45 @@ The `` part lists other compilation flags, like `"-fno-omit- Pass runtime flags to AddressSanitizer by using the `ASAN_OPTIONS` field in *`launch.vs.json`*. `ASAN_OPTIONS` defaults to `detect_leaks=0` when no other runtime options are specified because LeakSanitizer isn't supported in Visual Studio. +## Enable Segment Heap + +The Segment Heap is a Windows heap implementation that reduces memory usage and fragmentation. Visual Studio ships a CMake script that enables Segment Heap for your project by adding the required manifest settings. New C++ CMake projects enable Segment Heap by default. + +To enable Segment Heap, set `CMAKE_PROJECT_TOP_LEVEL_INCLUDES` in the `cacheVariables` map of your Configure Preset in *`CMakePresets.json`*. Optionally, set the `VS_SEGMENT_HEAP_ALLOWLIST` and `VS_SEGMENT_HEAP_EXCLUDE` environment variables to control which targets in the project use Segment Heap. Separate target names with semicolons: + + ```json +{ + "configurePresets": [ + { + // ... + "environment": { + "VS_SEGMENT_HEAP_ALLOWLIST": "target1;target2;", + "VS_SEGMENT_HEAP_EXCLUDE": "target3;" + }, + "cacheVariables": { + "CMAKE_PROJECT_TOP_LEVEL_INCLUDES": "$env{VSINSTALLDIR}Common7/IDE/CommonExtensions/Microsoft/CMake/cmake/Microsoft/SegmentHeap.cmake" + } + } + ] +} + +``` + +> [!NOTE] +> `CMAKE_PROJECT_TOP_LEVEL_INCLUDES` is available in CMake 3.24 or later. + +- `VS_SEGMENT_HEAP_ALLOWLIST` — Apply the Segment Heap manifest entry only to the listed targets. Exclude all other targets. +- `VS_SEGMENT_HEAP_EXCLUDE` — Exclude the listed targets from using the Segment Heap. + +In this example, `CMAKE_PROJECT_TOP_LEVEL_INCLUDES` points to the Visual Studio-provided `SegmentHeap.cmake` script. The optional `VS_SEGMENT_HEAP_ALLOWLIST` and `VS_SEGMENT_HEAP_EXCLUDE` variables show how to include or exclude specific targets. If neither variable is set, Visual Studio enables Segment Heap for all targets. If both variables are set, `VS_SEGMENT_HEAP_ALLOWLIST` takes precedence. + ## Run CMake from the command line or a CI pipeline You can use the same *`CMakePresets.json`* and *`CMakeUserPresets.json`* files to invoke CMake in Visual Studio and from the command line. The [CMake](https://cmake.org/cmake/help/latest/manual/cmake.1.html) and [CTest](https://cmake.org/cmake/help/latest/manual/ctest.1.html) documentation are the best resources for invoking CMake and CTest with `--preset`. CMake version 3.20 or later is required. ### Sourcing the environment when building with command-line generators on Windows -It's up to the user to configure the environment before CMake is invoked in building with a command-line generator. If you're building with Ninja and the Visual C++ toolset on Windows, set the environment before CMake is called to generate the build system. You can do it by calling *`vcvarsall.bat`* with the `architecture` argument. The `architecture` argument specifies the host and target architecture to use. For more information, see [`vcvarsall` syntax](./building-on-the-command-line.md#vcvarsall-syntax). If you build on Linux or on Windows with a Visual Studio Generator, you don't need to take this step. +It's up to the user to configure the environment before CMake is invoked in building with a command-line generator. If you're building with Ninja and the Microsoft C++ Build Tools on Windows, set the environment before CMake is called to generate the build system. You can do it by calling *`vcvarsall.bat`* with the `architecture` argument. The `architecture` argument specifies the host and target architecture to use. For more information, see [`vcvarsall` syntax](./building-on-the-command-line.md#vcvarsall-syntax). If you build on Linux or on Windows with a Visual Studio Generator, you don't need to take this step. It's the same step that Visual Studio takes for you when the IDE invokes CMake. Visual Studio parses the active Configure Preset for the host and target architecture specified by `toolset` and `architecture`. Visual Studio then sources the specified environment from *`vcvarsall.bat`*. When you build from the Windows command line with Ninja, you'll need to take this step yourself. @@ -467,15 +518,15 @@ cmake --build --preset ## Example *`CMakePresets.json`* file -The *`CMakePresets.json`* file in [box2d-lite](https://github.com/esweet431/box2d-lite/blob/vs-launch/CMakePresets.json) contains examples of Configure Presets, Build Presets, and Test Presets. +The *`CMakePresets.json`* file in [box2d-lite](https://github.com/esweet431/box2d-lite/blob/vs-launch/CMakePresets.json) contains examples of Configure Presets, Build Presets, and Test Presets. For more information about this example, see the presentation [An Introduction to CMakePresets.json](/shows/cpp-pure-virtual-cpp-2021/an-introduction-to-cmakepresetsjson). You can see another example in the [DirectXTK](https://github.com/microsoft/DirectXTK/blob/main/CMakePresets.json) project, which shows many build targets in its `configurePresets` section. ## Next steps Learn more about configuring and debugging CMake projects in Visual Studio: > [!div class="nextstepaction"] -> [CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)

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

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

+> [CMake Projects in Visual Studio](cmake-projects-in-visual-studio.md)\ +> [Customize CMake build settings](customize-cmake-settings.md)\ +> [Configure CMake debugging sessions](configure-cmake-debugging-sessions.md)\ > [CMake predefined configuration reference](cmake-predefined-configuration-reference.md) > diff --git a/docs/build/cmake-projects-in-visual-studio.md b/docs/build/cmake-projects-in-visual-studio.md index 5caf892144e..5dcd6b75af3 100644 --- a/docs/build/cmake-projects-in-visual-studio.md +++ b/docs/build/cmake-projects-in-visual-studio.md @@ -1,26 +1,30 @@ --- 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"] +ms.custom: sfi-image-nochange --- + # 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 +32,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 +45,15 @@ 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."::: + +You can also switch views by right-clicking on any file or folder in your Solution Explorer and selecting **Switch to CMake Targets View**. + +![A screenshot of right-clicking a file or folder in the Solution explorer. The context menu item to Switch to CMake Targets View is visible.](media/visual-studio-switch-cmake-targets-view.png) 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 +66,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 +95,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 +125,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,47 +135,53 @@ 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 Microsoft C++ (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 When you build for Windows with the MSVC compiler, CMake projects have support for Edit and Continue. Add the following code to your *`CMakeLists.txt`* file to enable Edit and Continue. -``` +```txt if(MSVC) target_compile_options( PUBLIC "/ZI") target_link_options( PUBLIC "/INCREMENTAL") 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 +200,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 +212,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 +252,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 +283,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 +299,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,21 +320,21 @@ 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. @@ -306,27 +342,31 @@ Not everything in the cache is imported. Properties such as the generator and t 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 +376,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 +402,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 +416,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 +436,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 da1c2c77745..41645840b36 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 16d3566c71f..274b0237bf1 100644 --- a/docs/build/cmakesettings-reference.md +++ b/docs/build/cmakesettings-reference.md @@ -122,7 +122,7 @@ By default, when the active configuration specifies a Visual Studio generator, i - `remotePreGenerateCommand`: Specifies the command to run before running CMake to parse the *`CMakeLists.txt`* file. - `remotePrebuildCommand`: Specifies the command to run on the remote machine before building. - `remotePostbuildCommand`: Specifies the command to run on the remote machine after building. -- `variables`: Contains a name-value pair of CMake variables that get passed as **`-D name=value`** to CMake. If your CMake project build instructions specify the addition of any variables directly to the *`CMakeCache.txt`* file, we recommend you add them here instead. This example shows how to specify the name-value pairs to use the 14.14.26428 MSVC toolset: +- `variables`: Contains a name-value pair of CMake variables that get passed as **`-D name=value`** to CMake. If your CMake project build instructions specify the addition of any variables directly to the *`CMakeCache.txt`* file, we recommend you add them here instead. This example shows how to specify the name-value pairs to use the 14.14.26428 MSVC Build Tools: ```json "variables": [ @@ -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-64-bit-migration-issues.md b/docs/build/common-visual-cpp-64-bit-migration-issues.md index 531a59ee624..7d8603ea722 100644 --- a/docs/build/common-visual-cpp-64-bit-migration-issues.md +++ b/docs/build/common-visual-cpp-64-bit-migration-issues.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: Common Visual C++ 64-bit Migration Issues" -title: "Common Visual C++ 64-bit Migration Issues" +description: "Learn more about: Common Microsoft C++ 64-bit Migration Issues" +title: "Common Microsoft C++ 64-bit Migration Issues" ms.date: "05/06/2019" helpviewer_keywords: ["64-bit programming [C++], migration", "64-bit compiler [C++], migration", "porting 32-bit code to 64-bit code", "migration [C++], 64-bit code issues", "32-bit code porting [C++]", "64-bit applications [C++]", "64-bit compiler [C++], porting 32-bit code", "Win64 [C++]"] ms.assetid: d17fb838-7513-4e2d-8b27-a1666f17ad76 --- -# Common Visual C++ 64-bit Migration Issues +# Common Microsoft C++ 64-bit Migration Issues -When you use the Microsoft C++ compiler (MSVC) to create applications to run on a 64-bit Windows operating system, you should be aware of the following issues: +When you use the Microsoft C++ (MSVC) compiler to create applications to run on a 64-bit Windows operating system, you should be aware of the following issues: - An **`int`** and a **`long`** are 32-bit values on 64-bit Windows operating systems. For programs that you plan to compile for 64-bit platforms, you should be careful not to assign pointers to 32-bit variables. Pointers are 64-bit on 64-bit platforms, and you will truncate the pointer value if you assign it to a 32-bit variable. @@ -34,4 +34,4 @@ For more information, see: ## See also [Configure C++ projects for 64-bit, x64 targets](configuring-programs-for-64-bit-visual-cpp.md)
-[Visual C++ Porting and Upgrading Guide](../porting/visual-cpp-porting-and-upgrading-guide.md) +[Microsoft C++ Porting and Upgrading Guide](../porting/visual-cpp-porting-and-upgrading-guide.md) diff --git a/docs/build/common-visual-cpp-arm-migration-issues.md b/docs/build/common-visual-cpp-arm-migration-issues.md index 93805a8ab7d..bd39965f08d 100644 --- a/docs/build/common-visual-cpp-arm-migration-issues.md +++ b/docs/build/common-visual-cpp-arm-migration-issues.md @@ -1,29 +1,31 @@ --- -description: "Learn more about: Common Visual C++ ARM Migration Issues" -title: "Common Visual C++ ARM Migration Issues" +description: "Learn more about: Common Microsoft C++ ARM Migration Issues" +title: "Common Microsoft C++ ARM Migration Issues" ms.date: "05/06/2019" -ms.assetid: 0f4c434e-0679-4331-ba0a-cc15dd435a46 --- -# Common Visual C++ ARM Migration Issues +# Common Microsoft 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,16 +85,16 @@ 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. +The Microsoft C++ (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 -[Configure Visual C++ for ARM processors](configuring-programs-for-arm-processors-visual-cpp.md) +[Configure Microsoft C++ for ARM processors](configuring-programs-for-arm-processors-visual-cpp.md) diff --git a/docs/build/compare-inclusion-methods.md b/docs/build/compare-inclusion-methods.md new file mode 100644 index 00000000000..2f8c25c5b6a --- /dev/null +++ b/docs/build/compare-inclusion-methods.md @@ -0,0 +1,43 @@ +--- +description: "Learn about the different ways to include library headers in C++: header files vs modules vs header units vs precompiled headers." +title: "Compare header units, modules, and precompiled headers" +ms.date: 11/30/2022 +f1_keywords: ["#include", "header file", "header unit", "module", "named module", "PCH", "precompiled header file", "IFC"] +helpviewer_keywords: ["headers, C++ library", "libraries, Standard C++", "C++ Standard Library, headers", "STL", "Standard template library, headers", "precompiled header files, creating", "PCH files, creating", "import", "header unit", "ifc", "modules [C++]", "named modules [C++]", "import standard library (STL) using named modules"] +--- +# Compare header units, modules, and precompiled headers + +Historically, you'd include the standard library with a directive like `#include `. However, it's expensive to include header files because they're reprocessed by every source file that includes them. + +Precompiled headers (PCH) were introduced to speed compilation by translating them once and reusing the result. But precompiled headers can be difficult to maintain. + +In C++20, modules were introduced as a significant improvement on header files and precompiled headers. + +Header units were introduced in C++20 as a way to temporarily bridge the gap between header files and modules. They provide some of the speed and robustness benefits of modules, while you migrate your code to use modules. + +Then, the C++23 standard library introduced support for importing the standard library as named modules. This is the fastest and most robust way to consume the standard library. + +To help you sort out the different options, this article compares the traditional `#include` method against precompiled headers, header units, and importing named modules. + +The following table is arranged by compiler processing speed and robustness, with `#include` being the slowest and least robust, and `import` being the fastest and most robust. + +| Method | Summary | +|---|---| +| `#include` | One disadvantage is that they expose macros and internal implementation. Internal implementation is often exposed as functions and types that start with an underscore. That's a convention to indicate that something is part of the internal implementation and shouldn't be used.

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

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

PCH files have restrictions that make them difficult to maintain.

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

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

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

Header units are slower than importing a named module.

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

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

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

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

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

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

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

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

Precompiled headers, which are compiler memory snapshots, can mitigate those costs, but not as well as named modules. | + +If you can use C++20 features and the C++23 standard library in your app, use named modules. + +If you can use C++20 features but want to transition over time to modules, use header units in the interim. + +If you can't use C++20 features, use `#include` and consider precompiled headers. + +## See also + +[Precompiled header files](creating-precompiled-header-files.md)\ +[Overview of modules in C++](../cpp/modules-cpp.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)\ +[Walkthrough: Build and import header units in your Microsoft C++ projects](walkthrough-header-units.md) \ No newline at end of file diff --git a/docs/build/concepts-of-isolated-applications-and-side-by-side-assemblies.md b/docs/build/concepts-of-isolated-applications-and-side-by-side-assemblies.md index 7b3b78360bf..2993d7abb37 100644 --- a/docs/build/concepts-of-isolated-applications-and-side-by-side-assemblies.md +++ b/docs/build/concepts-of-isolated-applications-and-side-by-side-assemblies.md @@ -4,6 +4,7 @@ title: "Concepts of Isolated Applications and Side-by-side Assemblies" ms.date: "05/06/2019" helpviewer_keywords: ["side-by-side assemblies [C++]", "isolated assemblies [C++]"] ms.assetid: 945a885f-cb3e-4c8a-a0b9-2c2e3e02cc50 +ms.topic: concept-article --- # Concepts of Isolated Applications and Side-by-side Assemblies @@ -23,9 +24,9 @@ At execution time, Windows uses assembly information from the application manife You can change side-by-side assembly dependencies after an application has been deployed by modifying the [Publisher Configuration Files](/windows/win32/SbsCs/publisher-configuration-files) and [Application Configuration Files](/windows/win32/SbsCs/application-configuration-files). A publisher configuration file, also known as a publisher policy file, is an XML file that globally redirects applications and assemblies from using one version of a side-by-side assembly to using another version of the same assembly. For example, you could change a dependency when a bug fix or security fix is deployed for a side-by-side assembly and you want to redirect all applications to use the fixed version. An application configuration file is an XML file that redirects a specific application from using one version of a side-by-side assembly to using another version of the same assembly. You can use an application configuration file to redirect a particular application to use a version of a side-by-side assembly that's different from the one that's defined in the publisher configuration file. For more information, see [Configuration](/windows/win32/SbsCs/configuration). -## Visual C++ libraries +## Microsoft C++ libraries -In Visual Studio 2005 and Visual Studio 2008, redistributable libraries such as ATL, MFC, CRT, Standard C++, OpenMP, and MSDIA were deployed as shared side-by-side assemblies to the native assembly cache. In the current version, the redistributable libraries use central deployment. By default, all applications that are built by using Visual Studio are built with the manifest embedded in the final binary, and the manifest describes the dependencies of the binary on the Visual C++ libraries. To understand manifest generation for C++ applications, see [Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md). A manifest is not required for applications that are statically linked to the libraries that they use, or that use local deployment. For more information about deployment, see [Deployment in Visual C++](../windows/deployment-in-visual-cpp.md). +In Visual Studio 2005 and Visual Studio 2008, redistributable libraries such as ATL, MFC, CRT, Standard C++, OpenMP, and MSDIA were deployed as shared side-by-side assemblies to the native assembly cache. In the current version, the redistributable libraries use central deployment. By default, all applications that are built by using Visual Studio are built with the manifest embedded in the final binary, and the manifest describes the dependencies of the binary on the Microsoft C++ libraries. To understand manifest generation for C++ applications, see [Understanding Manifest Generation for C/C++ Programs](understanding-manifest-generation-for-c-cpp-programs.md). A manifest is not required for applications that are statically linked to the libraries that they use, or that use local deployment. For more information about deployment, see [Deployment in Microsoft C++](../windows/deployment-in-visual-cpp.md). ## See also diff --git a/docs/build/configure-cmake-debugging-sessions.md b/docs/build/configure-cmake-debugging-sessions.md index 724048132ef..a16c9e0f9b8 100644 --- a/docs/build/configure-cmake-debugging-sessions.md +++ b/docs/build/configure-cmake-debugging-sessions.md @@ -1,8 +1,9 @@ --- 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"] +ms.topic: how-to --- # Configure CMake debugging sessions @@ -16,14 +17,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 +126,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-64-bit-visual-cpp.md b/docs/build/configuring-programs-for-64-bit-visual-cpp.md index e922af4027d..845be402593 100644 --- a/docs/build/configuring-programs-for-64-bit-visual-cpp.md +++ b/docs/build/configuring-programs-for-64-bit-visual-cpp.md @@ -7,15 +7,15 @@ ms.assetid: cb99f72b-8c74-48f4-846a-8921b37b97e9 --- # Configure C++ projects for 64-bit, x64 targets -This section contains topics about targeting 64-bit x64 hardware with the Visual C++ build tools. +This section contains topics about targeting 64-bit x64 hardware with the Microsoft C++ (MSVC) Build Tools. ## In This Section -- [How to: Configure Visual C++ Projects to Target 64-Bit, x64 Platforms](how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md) +- [How to: Configure Microsoft C++ Projects to Target 64-Bit, x64 Platforms](how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md) - [How to: Enable a 64-bit, x64-hosted MSVC toolset on the command line](how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md) -- [Common Visual C++ 64-bit Migration Issues](common-visual-cpp-64-bit-migration-issues.md) +- [Common Microsoft C++ 64-bit Migration Issues](common-visual-cpp-64-bit-migration-issues.md) - [x64 Software Conventions](x64-software-conventions.md) 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 4379cb9a7a1..bb6e7c40dc9 100644 --- a/docs/build/configuring-programs-for-arm-processors-visual-cpp.md +++ b/docs/build/configuring-programs-for-arm-processors-visual-cpp.md @@ -2,11 +2,10 @@ 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 -This section of the documentation contains information about how to use the MSVC build tools to target ARM hardware. +This section of the documentation contains information about how to use the Microsoft C++ (MSVC) Build Tools to target ARM hardware. ## In This Section @@ -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/configuring-programs-for-windows-xp.md b/docs/build/configuring-programs-for-windows-xp.md index 3e96c4f48ed..629e6b7230e 100644 --- a/docs/build/configuring-programs-for-windows-xp.md +++ b/docs/build/configuring-programs-for-windows-xp.md @@ -3,6 +3,7 @@ title: "Configuring Programs for Windows XP" description: "How to install and use the C++ Windows XP toolsets in Visual Studio." ms.date: 09/17/2021 ms.assetid: 1e4487b3-d815-4123-878b-5718b22f0fd5 +ms.topic: how-to --- # Configuring Programs for Windows XP diff --git a/docs/build/cppproperties-schema-reference.md b/docs/build/cppproperties-schema-reference.md index ba601ed4316..8ab040779a0 100644 --- a/docs/build/cppproperties-schema-reference.md +++ b/docs/build/cppproperties-schema-reference.md @@ -1,28 +1,28 @@ --- description: "Learn more about: CppProperties.json reference" title: "CppProperties.json reference" -ms.date: "08/09/2019" +ms.date: 09/19/2022 helpviewer_keywords: ["CppProperties.json file [C++]"] --- -# CppProperties.json reference +# `CppProperties.json` reference -Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a *CppProperties.json* file. (CMake projects use a [CMakeSettings.json](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. For more information about how to add configurations in an Open Folder project, see [Open Folder projects for C++](open-folder-projects-cpp.md). The following sections summarize the various settings. For a complete description of the schema, navigate to *CppProperties_schema.json*, whose full path is given at the top of the code editor when *CppProperties.json* is open. +Open Folder projects that don't use CMake can store project configuration settings for IntelliSense in a *`CppProperties.json`* file. (CMake projects use a [`CMakeSettings.json`](customize-cmake-settings.md) file.) A configuration consists of name/value pairs and defines #include paths, compiler switches, and other parameters. For more information about how to add configurations in an Open Folder project, see [Open Folder projects for C++](open-folder-projects-cpp.md). The following sections summarize the various settings. For a complete description of the schema, navigate to *CppProperties_schema.json*, whose full path is given at the top of the code editor when *`CppProperties.json`* is open. ## Configuration properties A configuration may have any of the following properties: -|Name|Description| -|-|-| -|`inheritEnvironments`| Specifies which environments apply to this configuration.| -|`name`|The configuration name that will appear in the C++ configuration dropdown| -|`includePath`|A comma-separated list of folders that should be specified in the include path (maps to /I for most compilers)| -|`defines`|The list of macros that should be defined (maps to /D for most compilers)| -|`compilerSwitches`|One or more additional switches that can influence IntelliSense behavior| -|`forcedInclude`|Header to be automatically included in every compilation unit (maps to /FI for MSVC or -include for clang)| -|`undefines`|The list of macros to be undefined (maps to /U for MSVC)| -|`intelliSenseMode`|The IntelliSense engine to be used. You can specify one of the predefined architecture-specific variants for MSVC, gcc, or Clang.| -|`environments`|User-defined sets of variables that behave like environment variables in a command prompt and are accessed with the ${env.\} macro.| +| Name | Description | +|--|--| +| `inheritEnvironments` | Specifies which environments apply to this configuration. | +| `name` | The configuration name that will appear in the C++ configuration dropdown | +| `includePath` | A comma-separated list of folders that should be specified in the include path (maps to `/I` for most compilers) | +| `defines` | The list of macros that should be defined (maps to `/D` for most compilers) | +| `compilerSwitches` | One or more additional switches that can influence IntelliSense behavior | +| `forcedInclude` | Header to be automatically included in every compilation unit (maps to `/FI` for MSVC or `-include` for clang) | +| `undefines` | The list of macros to be undefined (maps to `/U` for MSVC) | +| `intelliSenseMode` | The IntelliSense engine to be used. You can specify one of the predefined architecture-specific variants for MSVC, gcc, or Clang. | +| `environments` | User-defined sets of variables that behave like environment variables in a command prompt and are accessed with the `${env.VARIABLE}` macro. | ### intelliSenseMode values @@ -30,58 +30,58 @@ The code editor shows the available options when you start to type: ![Screenshot of the IntelliSense pop-up in the editor.](media/open-folder-intellisense-mode.png "Open Folder IntelliSense") -These are the supported values: - -- windows-msvc-x86 -- windows-msvc-x64 -- windows-msvc-arm -- windows-msvc-arm64 -- android-clang-x86 -- android-clang-x64 -- android-clang-arm -- android-clang-arm64 -- ios-clang-x86 -- ios-clang-x64 -- ios-clang-arm -- ios-clang-arm64 -- windows-clang-x86 -- windows-clang-x64 -- windows-clang-arm -- windows-clang-arm64 -- linux-gcc-x86 -- linux-gcc-x64 -- linux-gcc-arm +This list shows the supported values: + +- `windows-msvc-x86` +- `windows-msvc-x64` +- `windows-msvc-arm` +- `windows-msvc-arm64` +- `android-clang-x86` +- `android-clang-x64` +- `android-clang-arm` +- `android-clang-arm64` +- `ios-clang-x86` +- `ios-clang-x64` +- `ios-clang-arm` +- `ios-clang-arm64` +- `windows-clang-x86` +- `windows-clang-x64` +- `windows-clang-arm` +- `windows-clang-arm64` +- `linux-gcc-x86` +- `linux-gcc-x64` +- `linux-gcc-arm` Note: The values `msvc-x86` and `msvc-x64` are supported for legacy reasons only. Use the `windows-msvc-*` variants instead. ## Pre-defined Environments -Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using the global property `env` with this macro syntax: ${env.\}. +Visual Studio provides the following predefined environments for Microsoft C++ which map to the corresponding Developer Command Prompt. When you inherit one of these environments, you can refer to any of the environment variables by using the global property `env` with this macro syntax: `${env.VARIABLE}`. -|Variable Name|Description| -|-----------|-----------------| -|vsdev|The default Visual Studio environment| -|msvc_x86|Compile for x86 using x86 tools| -|msvc_x64|Compile for AMD64 using 64-bit tools| -|msvc_arm|Compile for ARM using x86 tools| -|msvc_arm64|Compile for ARM64 using x86 tools| -|msvc_x86_x64|Compile for AMD64 using x86 tools| -|msvc_arm_x64|Compile for ARM using 64-bit tools| -|msvc_arm64_x64|Compile for ARM64 using 64-bit tools| +| Variable Name | Description | +|--|--| +| `vsdev` | The default Visual Studio environment | +| `msvc_x86` | Compile for x86 using x86 tools | +| `msvc_x64` | Compile for AMD64 using 64-bit tools | +| `msvc_arm` | Compile for ARM using x86 tools | +| `msvc_arm64` | Compile for ARM64 using x86 tools | +| `msvc_x86_x64` | Compile for AMD64 using x86 tools | +| `msvc_arm_x64` | Compile for ARM using 64-bit tools | +| `msvc_arm64_x64` | Compile for ARM64 using 64-bit tools | When the Linux workload is installed, the following environments are available for remotely targeting Linux and WSL: -|Variable Name|Description| -|-----------|-----------------| -|linux_x86|Target x86 Linux remotely| -|linux_x64|Target x64 Linux remotely| -|linux_arm|Target ARM Linux remotely| +| Variable Name | Description | +|--|--| +| `linux_x86` | Target x86 Linux remotely | +| `linux_x64` | Target x64 Linux remotely | +| `linux_arm` | Target ARM Linux remotely | ## User-defined environments -You can optionally use the `environments` property to define sets of variables in *CppProperties.json* either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project and can be accessed with the ${env.\} syntax from *tasks.vs.json* and *launch.vs.json* after they are defined here. However, they are not necessarily set as actual environment variables in any command prompt that Visual Studio uses internally. +You can optionally use the `environments` property to define sets of variables in *`CppProperties.json`* either globally or per-configuration. These variables behave like environment variables in the context of an Open Folder project. You can access them with the `${env.VARIABLE}` syntax from *`tasks.vs.json`* and *`launch.vs.json`* after they're defined here. However, they aren't necessarily set as actual environment variables in any command prompt that Visual Studio uses internally. -**Visual Studio 2019 version 16.4 and later:** Configuration-specific variables defined in *CppProperties.json* are automatically picked up by debug targets and tasks without the need to set `inheritEnvironments`. Debug targets are launched automatically with the environment you specify in *CppProperties.json*. +**Visual Studio 2019 version 16.4 and later:** Configuration-specific variables defined in *`CppProperties.json`* are automatically picked up by debug targets and tasks without the need to set `inheritEnvironments`. Debug targets are launched automatically with the environment you specify in *`CppProperties.json`*. **Visual Studio 2019 version 16.3 and earlier:** When you consume an environment, then you have to specify it in the `inheritsEnvironments` property even if the environment is defined as part of the same configuration; the `environment` property specifies the name of the environment. The following example shows a sample configuration for enabling IntelliSense for GCC in an MSYS2 installation. Note how the configuration both defines and inherits the `mingw_64` environment, and how the `includePath` property can access the `INCLUDE` variable. @@ -93,7 +93,7 @@ You can optionally use the `environments` property to define sets of variables i "mingw_64" ], "name": "Mingw64", - "includePath ,": [ + "includePath": [ "${env.INCLUDE}", "${workspaceRoot}\\**", ], @@ -113,21 +113,21 @@ You can optionally use the `environments` property to define sets of variables i ] ``` -When you define an **environments** property inside a configuration, it overrides any global variables of the same name. +When you define an `"environments"` property inside a configuration, it overrides any global variables that have the same names. ## Built-in macros -You have access to the following built-in macros inside *CppProperties.json*: +You have access to the following built-in macros inside *`CppProperties.json`*: -|Macro|Description| -|-|-| -|`${workspaceRoot}`| The full path to the workspace folder| -|`${projectRoot}`| The full path to the folder where *CppProperties.json* is placed| -|`${env.vsInstallDir}`| The full path to the folder where the running instance of Visual Studio is installed| +| Macro | Description | +|--|--| +| `${workspaceRoot}` | The full path to the workspace folder | +| `${projectRoot}` | The full path to the folder where *`CppProperties.json`* is placed | +| `${env.vsInstallDir}` | The full path to the folder where the running instance of Visual Studio is installed | ### Example -If your project has an include folder and also includes *windows.h* and other common headers from the Windows SDK, you may want to update your *CppProperties.json* configuration file with the following includes: +If your project has an include folder and also includes `*windows.h`* and other common headers from the Windows SDK, you may want to update your *`CppProperties.json`* configuration file with the following includes: ```json { @@ -136,28 +136,28 @@ If your project has an include folder and also includes *windows.h* and other co "name": "Windows", "includePath": [ // local include folder - "${workspaceRoot}\include", + "${workspaceRoot}\\include", // Windows SDK and CRT headers - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\ucrt", - "${env.NETFXSDKDir}\include\um", - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\um", - "${env.WindowsSdkDir}\include\${env.WindowsSDKVersion}\shared", - "${env.VCToolsInstallDir}\include" + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\ucrt", + "${env.NETFXSDKDir}\\include\\um", + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\um", + "${env.WindowsSdkDir}\\include\\${env.WindowsSDKVersion}\\shared", + "${env.VCToolsInstallDir}\\include" ] } ] } ``` -> [!Note] -> `%WindowsSdkDir%` and `%VCToolsInstallDir%` are not set as global environment variables so make sure you start devenv.exe from a Developer Command Prompt that defines these variables. (Type "developer" in the Windows Start Menu.) +> [!NOTE] +> `%WindowsSdkDir%` and `%VCToolsInstallDir%` are not set as global environment variables. Make sure you start *`devenv.exe`* from a Developer Command Prompt that defines these variables. (Type "developer" in the Windows Start Menu to find a Developer Command Prompt shortcut.) ## Troubleshoot IntelliSense errors -If you are not seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **`true`**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8. +If you aren't seeing the IntelliSense that you expect, you can troubleshoot by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Advanced** and setting **Enable Logging** to **`true`**. To start with, try setting **Logging Level** to 5, and **Logging Filters** to 8. ![Screenshot of the Diagnostic logging settings in the Options dialog.](media/diagnostic-logging.png) -Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log**. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths do not match the ones in *CppProperties.json*, try closing the folder and deleting the *.vs* sub-folder which contains cached browsing data. +Output is piped to the **Output Window** and is visible when you choose **Show Output From: Visual C++ Log**. The output contains, among other things, the list of actual include paths that IntelliSense is trying to use. If the paths don't match the ones in *`CppProperties.json`*, try closing the folder and deleting the *`.vs`* subfolder that contains cached browsing data. -To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** and filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...". +To troubleshoot IntelliSense errors caused by missing include paths, open the **Error List** tab, and then filter its output to "IntelliSense only" and error code E1696 "cannot open source file ...". diff --git a/docs/build/create-reusable-property-configurations.md b/docs/build/create-reusable-property-configurations.md index d046426504a..52af28e0f40 100644 --- a/docs/build/create-reusable-property-configurations.md +++ b/docs/build/create-reusable-property-configurations.md @@ -3,6 +3,7 @@ description: "Learn more about: Share or reuse Visual Studio project settings" title: "Share or reuse Visual Studio project settings - C++" ms.date: 02/07/2022 helpviewer_keywords: ["project properties [C++], reusable"] +ms.topic: how-to --- # Share or reuse Visual Studio project settings diff --git a/docs/build/creating-a-resource-only-dll.md b/docs/build/creating-a-resource-only-dll.md index e054108b83b..664e45250de 100644 --- a/docs/build/creating-a-resource-only-dll.md +++ b/docs/build/creating-a-resource-only-dll.md @@ -5,6 +5,7 @@ ms.date: "01/27/2020" helpviewer_keywords: ["resource-only DLLs [C++], creating", "DLLs [C++], creating"] ms.assetid: e6b1d4da-7275-467f-a58c-a0a8a5835199 no-loc: [noentry] +ms.topic: how-to --- # Creating a resource-only DLL diff --git a/docs/build/creating-and-managing-visual-cpp-projects.md b/docs/build/creating-and-managing-visual-cpp-projects.md index d8014dfeff2..2441a8b327e 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 f48ec8b0104..ec450093ce7 100644 --- a/docs/build/creating-precompiled-header-files.md +++ b/docs/build/creating-precompiled-header-files.md @@ -1,9 +1,8 @@ --- -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"] -ms.assetid: e2cdb404-a517-4189-9771-c869c660cb1b --- # Precompiled header files @@ -21,7 +20,7 @@ Precompiled code is useful during the development cycle to reduce compilation ti - You always use a large body of code that changes infrequently. -- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. +- Your program comprises multiple modules, all of which use a standard set of include files and the same compilation options. In this case, all include files can be precompiled into one precompiled header. For more information about newer ways to handle include files, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md). The first compilation (the one that creates the precompiled header file) takes a bit longer than subsequent compilations. Subsequent compilations can proceed more quickly by including the precompiled code. @@ -141,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. | @@ -162,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 @@ -256,7 +258,7 @@ Source file `ANOTHER.H`: // #ifndef __ANOTHER_H #define __ANOTHER_H -#include +#include void savemoretime( void ); #endif // __ANOTHER_H ``` @@ -270,7 +272,7 @@ Source file `STABLE.H`: // #ifndef __STABLE_H #define __STABLE_H -#include +#include void savetime( void ); #endif // __STABLE_H ``` @@ -286,7 +288,7 @@ Source file `UNSTABLE.H`: // #ifndef __UNSTABLE_H #define __UNSTABLE_H -#include +#include void notstable( void ); #endif // __UNSTABLE_H ``` @@ -298,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 @@ -328,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(); @@ -341,5 +343,10 @@ int main( void ) ## See also +[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 Microsoft C++ projects](walkthrough-header-units.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) diff --git a/docs/build/customize-cmake-settings.md b/docs/build/customize-cmake-settings.md index 222c2e4a83c..5c8cd24cf4a 100644 --- a/docs/build/customize-cmake-settings.md +++ b/docs/build/customize-cmake-settings.md @@ -3,10 +3,21 @@ description: "Learn more about: Customize CMake build settings" title: "Customize CMake build settings in Visual Studio" ms.date: 12/15/2021 helpviewer_keywords: ["CMake build settings"] +ms.topic: how-to --- # Customize CMake build settings -::: moniker range=">=msvc-160" +::: moniker range=">=msvc-180" + +The CMake settings editor has been deprecated in Visual Studio 2026. + +To learn about changing the *`CMakePresets.json`* file, see [CMakePresets.json and CMakeUserPresets.json Microsoft vendor maps](/cpp/build/cmake-presets-json-reference). + +For Visual Studio 2019 to 2022, select your version by using the version selector in the sidebar menu. + +::: moniker-end + +::: moniker range=">=msvc-160 <=msvc-170" 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). @@ -14,11 +25,17 @@ 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::: + +> [!NOTE] +> If a JSON editor opens instead of the **Settings Editor** when you select **Manage Configurations**, you need to enable the CMakeSettings mode. Under **Tools** > **Options** > **CMake**, select **Never use CMake Presets**, and then close and reopen your CMake project. Alternatively, you can choose **Use CMake Presets if available, otherwise use CMakeSettings.json**, and then delete the *CMakePresets.json* file from the project folder. +> :::image type="content" source="media/options-configuration-file.png" alt-text="Screenshot of the C make options pane."::: 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 +51,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 +59,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 +87,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 +113,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,17 +207,19 @@ 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 -## See also +## Related content -[CMake Projects in Visual Studio](cmake-projects-in-visual-studio.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)
-[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) +- [CMake Projects in Visual Studio](cmake-projects-in-visual-studio.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) +- [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) diff --git a/docs/build/determining-which-exporting-method-to-use.md b/docs/build/determining-which-exporting-method-to-use.md index 58d6c4432c2..f34d60e3e3b 100644 --- a/docs/build/determining-which-exporting-method-to-use.md +++ b/docs/build/determining-which-exporting-method-to-use.md @@ -19,7 +19,7 @@ Exporting functions in a .def file gives you control over the export ordinals. W Another advantage to using a .def file is that you can use the `NONAME` attribute to export a function. This puts only the ordinal in the exports table in the DLL. For DLLs that have a large number of exported functions, using the `NONAME` attribute can reduce the size of the DLL file. For information about how to write a module definition statement, see [Rules for Module-Definition Statements](reference/rules-for-module-definition-statements.md). For information about ordinal export, see [Exporting Functions from a DLL by Ordinal Rather Than by Name](exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md). -A disadvantage of using a .def file is that if you are exporting functions in a C++ file, you either have to put the decorated names in the .def file or define the exported functions by using extern "C" to avoid the name decoration that's done by the MSVC compiler. +A disadvantage of using a .def file is that if you are exporting functions in a C++ file, you either have to put the decorated names in the .def file or define the exported functions by using extern "C" to avoid the name decoration that's done by the Microsoft C++ (MSVC) compiler. If you put the decorated names in the .def file, you can obtain them by using the [DUMPBIN](reference/dumpbin-reference.md) tool or by using the linker [/MAP](reference/map-generate-mapfile.md) option. The decorated names that are produced by the compiler are compiler-specific; therefore, if you put the decorated names that are produced by the compiler into a .def file, the applications that link to the DLL must also be built by using the same version of the compiler so that the decorated names in the calling application match the exported names in the .def file of the DLL. diff --git a/docs/build/dlls-in-visual-cpp.md b/docs/build/dlls-in-visual-cpp.md index a1974a8268a..cf7683b6c21 100644 --- a/docs/build/dlls-in-visual-cpp.md +++ b/docs/build/dlls-in-visual-cpp.md @@ -68,7 +68,7 @@ Describes explicit and implicit linking to a DLL. [Initialize a DLL](run-time-library-behavior.md#initializing-a-dll)\ Discusses DLL initialization code that must execute when your DLL loads. -[DLLs and Visual C++ run-time library behavior](run-time-library-behavior.md)\ +[DLLs and Microsoft C++ run-time library behavior](run-time-library-behavior.md)\ Describes the run-time library DLL startup sequence. [LoadLibrary and AfxLoadLibrary](loadlibrary-and-afxloadlibrary.md)\ diff --git a/docs/build/exception-handling-x64.md b/docs/build/exception-handling-x64.md index 41a6e29b6e4..efb1eac2d73 100644 --- a/docs/build/exception-handling-x64.md +++ b/docs/build/exception-handling-x64.md @@ -7,29 +7,33 @@ ms.assetid: 41fecd2d-3717-4643-b21c-65dcd2f18c93 --- # x64 exception handling -An overview of structured exception handling and C++ exception handling coding conventions and behavior on the x64. For general information on exception handling, see [Exception Handling in Visual C++](../cpp/exception-handling-in-visual-cpp.md). +An overview of structured exception handling and C++ exception handling coding conventions and behavior on the x64. For general information on exception handling, see [Exception Handling in Microsoft C++](../cpp/exception-handling-in-visual-cpp.md). -## Unwind data for exception handling, debugger support +## Unwind data for exception handling and debugger support -Several data structures are required for exception handling and debugging support. +To recover nonvolatile registers when an exception is handled, nonleaf functions are annotated with static data. This data, commonly referred to as "Function Unwind Information", 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 Function Unwind Information is composed of several data structures, described next. + +For Unwind Information supporting the Intel APX (Advanced Performance Extensions), see the [Unwind V3 Preview Specification](../build/x64-unwind-information-v3.md). ### struct RUNTIME_FUNCTION Table-based exception handling requires a table entry for all functions that allocate stack space or call another function (for example, nonleaf functions). Function table entries have the format: -|Size|Value| +| Size | Value | |-|-| |ULONG|Function start address| |ULONG|Function end address| |ULONG|Unwind info address| -The RUNTIME_FUNCTION structure must be DWORD aligned in memory. All addresses are image relative, that is, they're 32-bit offsets from the starting address of the image that contains the function table entry. These entries are sorted, and put in the .pdata section of a PE32+ image. For dynamically generated functions [JIT compilers], the runtime to support these functions must either use RtlInstallFunctionTableCallback or RtlAddFunctionTable to provide this information to the operating system. Failure to do so will result in unreliable exception handling and debugging of processes. +The `RUNTIME_FUNCTION` structure must be `DWORD` aligned in memory. All addresses are image relative, that is, they're 32-bit offsets from the starting address of the image that contains the function table entry. These entries are sorted, and put in the `.pdata` section of a PE32+ image. For dynamically generated functions [JIT compilers], the runtime to support these functions must either use `RtlInstallFunctionTableCallback` or `RtlAddFunctionTable` to provide this information to the operating system. Failure to do so results in unreliable exception handling and debugging of processes. ### struct UNWIND_INFO -The unwind data info structure is used to record the effects a function has on the stack pointer, and where the nonvolatile registers are saved on the stack: +The unwind data info structure records the effects a function has on the stack pointer and where the nonvolatile registers are saved on the stack: -|Size|Value| +| Size | Value | |-|-| |UBYTE: 3|Version| |UBYTE: 5|Flags| @@ -42,20 +46,20 @@ The unwind data info structure is used to record the effects a function has on t (1) Exception Handler -|Size|Value| +| Size | Value | |-|-| |ULONG|Address of exception handler| |variable|Language-specific handler data (optional)| (2) Chained Unwind Info -|Size|Value| +| Size | Value | |-|-| |ULONG|Function start address| |ULONG|Function end address| |ULONG|Unwind info address| -The UNWIND_INFO structure must be DWORD aligned in memory. Here's what each field means: +The `UNWIND_INFO` structure must be `DWORD` aligned in memory. Here's what each field means: - **Version** @@ -67,9 +71,9 @@ The UNWIND_INFO structure must be DWORD aligned in memory. Here's what each fiel |Flag|Description| |-|-| - |`UNW_FLAG_EHANDLER`| The function has an exception handler that should be called when looking for functions that need to examine exceptions.| - |`UNW_FLAG_UHANDLER`| The function has a termination handler that should be called when unwinding an exception.| - |`UNW_FLAG_CHAININFO`| This unwind info structure is not the primary one for the procedure. Instead, the chained unwind info entry is the contents of a previous RUNTIME_FUNCTION entry. For information, see [Chained unwind info structures](#chained-unwind-info-structures). If this flag is set, then the UNW_FLAG_EHANDLER and UNW_FLAG_UHANDLER flags must be cleared. Also, the frame register and fixed-stack allocation fields must have the same values as in the primary unwind info.| + |`UNW_FLAG_EHANDLER`| The function has an exception handler that the operating system calls to examine the state of the exception and potentially handle it. Language features such as the C `__try` clause register such a handler.| + |`UNW_FLAG_UHANDLER`| The function has a termination handler that the operation system calls when unwinding the stack. This handler could release resources allocated by the function in exception safe code. Language features such as local C++ object destructors and C `__finally` clauses register such a termination handler. | + |`UNW_FLAG_CHAININFO`| This unwind info structure isn't the primary one for the procedure. Instead, the chained unwind info entry is the contents of a previous `RUNTIME_FUNCTION` entry. For information, see [Chained unwind info structures](#chained-unwind-info-structures). If this flag is set, then the `UNW_FLAG_EHANDLER` and `UNW_FLAG_UHANDLER` flags must be cleared. Also, the frame register and fixed-stack allocation fields must have the same values as in the primary unwind info.| - **Size of prolog** @@ -77,23 +81,23 @@ The UNWIND_INFO structure must be DWORD aligned in memory. Here's what each fiel - **Count of unwind codes** - The number of slots in the unwind codes array. Some unwind codes, for example, UWOP_SAVE_NONVOL, require more than one slot in the array. + The number of slots in the unwind codes array. Some unwind codes, such as `UWOP_SAVE_NONVOL`, require more than one slot in the array. - **Frame register** - If nonzero, then the function uses a frame pointer (FP), and this field is the number of the nonvolatile register used as the frame pointer, using the same encoding for the operation info field of UNWIND_CODE nodes. + If nonzero, the function uses a frame pointer (FP), and this field is the number of the nonvolatile register used as the frame pointer, using the same encoding for the operation info field of `UNWIND_CODE` nodes. - **Frame register offset (scaled)** - If the frame register field is nonzero, this field is the scaled offset from RSP that is applied to the FP register when it's established. The actual FP register is set to RSP + 16 \* this number, allowing offsets from 0 to 240. This offset permits pointing the FP register into the middle of the local stack allocation for dynamic stack frames, allowing better code density through shorter instructions. (That is, more instructions can use the 8-bit signed offset form.) + This field is a scaled offset between the `RSP` register value and the selected Frame Pointer (FP) register value. The selected FP register is set to `RSP` + 16 * this number, which means you can use offsets from 0 to 240. This offset points the FP register into the middle of the local stack allocation for dynamic stack frames, so you get better code density through shorter instructions. (That is, more instructions can use the 8-bit signed offset form.) - **Unwind codes array** - An array of items that explains the effect of the prolog on the nonvolatile registers and RSP. See the section on UNWIND_CODE for the meanings of individual items. For alignment purposes, this array always has an even number of entries, and the final entry is potentially unused. In that case, the array is one longer than indicated by the count of unwind codes field. + An array of items that explains the effect of the prolog on the nonvolatile registers and `RSP`. See the section on [Unwind operations code](#unwind-operation-code) for the meanings of individual items. To maintain proper data alignment, this array always contains an even number of entries, and the final entry may be unused. In that case, the array is one longer than indicated by the count of unwind codes field. - **Address of exception handler** - An image-relative pointer to either the function's language-specific exception or termination handler, if flag UNW_FLAG_CHAININFO is clear and one of the flags UNW_FLAG_EHANDLER or UNW_FLAG_UHANDLER is set. + An image-relative pointer to either the function's language-specific exception or termination handler, if flag `UNW_FLAG_CHAININFO` is clear and one of the flags `UNW_FLAG_EHANDLER` or `UNW_FLAG_UHANDLER` is set. - **Language-specific handler data** @@ -101,13 +105,13 @@ The UNWIND_INFO structure must be DWORD aligned in memory. Here's what each fiel - **Chained Unwind Info** - If flag UNW_FLAG_CHAININFO is set, then the UNWIND_INFO structure ends with three UWORDs. These UWORDs represent the RUNTIME_FUNCTION information for the function of the chained unwind. + If flag `UNW_FLAG_CHAININFO` is set, the `UNWIND_INFO` structure ends with three `UWORD`s. These `UWORD`s represent the `RUNTIME_FUNCTION` information for the function of the chained unwind. ### struct UNWIND_CODE -The unwind code array is used to record the sequence of operations in the prolog that affect the nonvolatile registers and RSP. Each code item has this format: +Use the unwind code array to record the sequence of operations in the prolog that affect the nonvolatile registers and `RSP`. Each code item has this format: -|Size|Value| +| Size | Value | |-|-| |UBYTE|Offset in prolog| |UBYTE: 4|Unwind operation code| @@ -121,17 +125,17 @@ Offset (from the beginning of the prolog) of the end of the instruction that per #### Unwind operation code -Note: Certain operation codes require an unsigned offset to a value in the local stack frame. This offset is from the start, that is, the lowest address of the fixed stack allocation. If the Frame Register field in the UNWIND_INFO is zero, this offset is from RSP. If the Frame Register field is nonzero, this offset is from where RSP was located when the FP register was established. It equals the FP register minus the FP register offset (16 \* the scaled frame register offset in the UNWIND_INFO). If an FP register is used, then any unwind code taking an offset must only be used after the FP register is established in the prolog. +Certain operation codes require an unsigned offset to a value in the local stack frame. This offset is from the start, that is, the lowest address of the fixed stack allocation. If the Frame Register field in the `UNWIND_INFO` is zero, this offset is from `RSP`. If the Frame Register field is nonzero, this offset is from where `RSP` was located when the FP register was established. It equals the FP register minus the FP register offset (16 \* the scaled frame register offset in the `UNWIND_INFO`). If an FP register is used, then any unwind code taking an offset must only be used after the FP register is established in the prolog. -For all opcodes except `UWOP_SAVE_XMM128` and `UWOP_SAVE_XMM128_FAR`, the offset is always a multiple of 8, because all stack values of interest are stored on 8-byte boundaries (the stack itself is always 16-byte aligned). For operation codes that take a short offset (less than 512K), the final USHORT in the nodes for this code holds the offset divided by 8. For operation codes that take a long offset (512K <= offset < 4GB), the final two USHORT nodes for this code hold the offset (in little-endian format). +For all opcodes except `UWOP_SAVE_XMM128` and `UWOP_SAVE_XMM128_FAR`, the offset is always a multiple of 8, because all stack values of interest are stored on 8-byte boundaries (the stack itself is always 16-byte aligned). For operation codes that take a short offset (less than 512K), the final `USHORT` in the nodes for this code holds the offset divided by 8. For operation codes that take a long offset (512K <= offset < 4GB), the final two `USHORT` nodes for this code hold the offset (in little-endian format). -For the opcodes `UWOP_SAVE_XMM128` and `UWOP_SAVE_XMM128_FAR`, the offset is always a multiple of 16, since all 128-bit XMM operations must occur on 16-byte aligned memory. Therefore, a scale factor of 16 is used for `UWOP_SAVE_XMM128`, permitting offsets of less than 1M. +For the opcodes `UWOP_SAVE_XMM128` and `UWOP_SAVE_XMM128_FAR`, the offset is always a multiple of 16, since all 128-bit `XMM` operations must occur on 16-byte aligned memory. Therefore, a scale factor of 16 is used for `UWOP_SAVE_XMM128`, permitting offsets of less than 1M. The unwind operation code is one of these values: - `UWOP_PUSH_NONVOL` (0) 1 node - Push a nonvolatile integer register, decrementing RSP by 8. The operation info is the number of the register. Because of the constraints on epilogs, `UWOP_PUSH_NONVOL` unwind codes must appear first in the prolog and correspondingly, last in the unwind code array. This relative ordering applies to all other unwind codes except `UWOP_PUSH_MACHFRAME`. + Push a nonvolatile integer register, decrementing `RSP` by 8. The operation info is the number of the register. Because of the constraints on epilogs, `UWOP_PUSH_NONVOL` unwind codes must appear first in the prolog and correspondingly, last in the unwind code array. This relative ordering applies to all other unwind codes except `UWOP_PUSH_MACHFRAME`. - `UWOP_ALLOC_LARGE` (1) 2 or 3 nodes @@ -151,7 +155,7 @@ The unwind operation code is one of these values: - `UWOP_SET_FPREG` (3) 1 node - Establish the frame pointer register by setting the register to some offset of the current RSP. The offset is equal to the Frame Register offset (scaled) field in the UNWIND_INFO \* 16, allowing offsets from 0 to 240. The use of an offset permits establishing a frame pointer that points to the middle of the fixed stack allocation, helping code density by allowing more accesses to use short instruction forms. The operation info field is reserved and shouldn't be used. + Establish the frame pointer register by setting the register to some offset of the current `RSP`. The offset is equal to the Frame Register offset (scaled) field in the `UNWIND_INFO` \* 16, allowing offsets from 0 to 240. The use of an offset permits establishing a frame pointer that points to the middle of the fixed stack allocation, helping code density by allowing more accesses to use short instruction forms. The operation info field is reserved and shouldn't be used. - `UWOP_SAVE_NONVOL` (4) 2 nodes @@ -163,52 +167,52 @@ The unwind operation code is one of these values: - `UWOP_SAVE_XMM128` (8) 2 nodes - Save all 128 bits of a nonvolatile XMM register on the stack. The operation info is the number of the register. The scaled-by-16 stack offset is recorded in the next slot. + Save all 128 bits of a nonvolatile `XMM` register on the stack. The operation info is the number of the register. The scaled-by-16 stack offset is recorded in the next slot. - `UWOP_SAVE_XMM128_FAR` (9) 3 nodes - Save all 128 bits of a nonvolatile XMM register on the stack with a long offset. The operation info is the number of the register. The unscaled stack offset is recorded in the next two slots. + Save all 128 bits of a nonvolatile `XMM` register on the stack with a long offset. The operation info is the number of the register. The unscaled stack offset is recorded in the next two slots. - `UWOP_PUSH_MACHFRAME` (10) 1 node - Push a machine frame. This unwind code is used to record the effect of a hardware interrupt or exception. There are two forms. If the operation info equals 0, one of these frames has been pushed on the stack: + Push a machine frame. This unwind code records the effect of a hardware interrupt or exception. It has two forms. A value of 0, indicates hardware has pushed a frame such as this on the stack: |Location|Value| |-|-| - |RSP+32|SS| - |RSP+24|Old RSP| - |RSP+16|EFLAGS| - |RSP+8|CS| - |RSP|RIP| + |`RSP`+32|`SS`| + |`RSP`+24|Old `RSP`| + |`RSP`+16|`EFLAGS`| + |`RSP`+8|`CS`| + |`RSP`|`RIP`| - If the operation info equals 1, then one of these frames has been pushed: + A value of 1, indicates hardware has pushed a frame such as this on the stack: |Location|Value| |-|-| - |RSP+40|SS| - |RSP+32|Old RSP| - |RSP+24|EFLAGS| - |RSP+16|CS| - |RSP+8|RIP| - |RSP|Error code| + |`RSP`+40|`SS`| + |`RSP`+32|Old `RSP`| + |`RSP`+24|`EFLAGS`| + |`RSP`+16|`CS`| + |`RSP`+8|`RIP`| + |`RSP`|Error code| This unwind code always appears in a dummy prolog, which is never actually executed, but instead appears before the real entry point of an interrupt routine, and exists only to provide a place to simulate the push of a machine frame. `UWOP_PUSH_MACHFRAME` records that simulation, which indicates the machine has conceptually done this operation: - 1. Pop RIP return address from top of stack into *Temp* + 1. Pop `RIP` return address from top of stack into *Temp* - 1. Push SS + 1. Push `SS` - 1. Push old RSP + 1. Push old `RSP` - 1. Push EFLAGS + 1. Push `EFLAGS` - 1. Push CS + 1. Push `CS` 1. Push *Temp* 1. Push Error Code (if op info equals 1) - The simulated `UWOP_PUSH_MACHFRAME` operation decrements RSP by 40 (op info equals 0) or 48 (op info equals 1). + The simulated `UWOP_PUSH_MACHFRAME` operation decrements `RSP` by 40 (if op info equals 0) or 48 (if op info equals 1). #### Operation info @@ -216,57 +220,57 @@ The meaning of the operation info bits depends upon the operation code. To encod |Bit|Register| |-|-| -|0|RAX| -|1|RCX| -|2|RDX| -|3|RBX| -|4|RSP| -|5|RBP| -|6|RSI| -|7|RDI| -|8 to 15|R8 to R15| +|0|`RAX`| +|1|`RCX`| +|2|`RDX`| +|3|`RBX`| +|4|`RSP`| +|5|`RBP`| +|6|`RSI`| +|7|`RDI`| +|8 to 15|`R8` to `R15`| ### Chained unwind info structures -If the UNW_FLAG_CHAININFO flag is set, then an unwind info structure is a secondary one, and the shared exception-handler/chained-info address field contains the primary unwind information. This sample code retrieves the primary unwind information, assuming that `unwindInfo` is the structure that has the UNW_FLAG_CHAININFO flag set. +If the `UNW_FLAG_CHAININFO` flag is set, then an unwind info structure is a secondary one, and the shared exception-handler/chained-info address field contains the primary unwind information. This sample code retrieves the primary unwind information, assuming that `unwindInfo` is the structure that has the `UNW_FLAG_CHAININFO` flag set. ```cpp PRUNTIME_FUNCTION primaryUwindInfo = (PRUNTIME_FUNCTION)&(unwindInfo->UnwindCode[( unwindInfo->CountOfCodes + 1 ) & ~1]); ``` -Chained info is useful in two situations. First, it can be used for noncontiguous code segments. By using chained info, you can reduce the size of the required unwind information, because you do not have to duplicate the unwind codes array from the primary unwind info. +Chained info is useful in two situations. First, it can be used for noncontiguous code segments. By using chained info, you can reduce the size of the required unwind information, because you don't have to duplicate the unwind codes array from the primary unwind info. -You can also use chained info to group volatile register saves. The compiler may delay saving some volatile registers until it is outside of the function entry prolog. You can record them by having primary unwind info for the portion of the function before the grouped code, and then setting up chained info with a non-zero size of prolog, where the unwind codes in the chained info reflect saves of the nonvolatile registers. In that case, the unwind codes are all instances of UWOP_SAVE_NONVOL. A grouping that saves nonvolatile registers by using a PUSH or modifies the RSP register by using an additional fixed stack allocation is not supported. +You can also use chained info to group volatile register saves. The compiler might delay saving some volatile registers until it is outside of the function entry prolog. You can record them by having primary unwind info for the portion of the function before the grouped code, and then setting up chained info with a nonzero size of prolog, where the unwind codes in the chained info reflect saves of the nonvolatile registers. In that case, the unwind codes are all instances of `UWOP_SAVE_NONVOL`. A grouping that saves nonvolatile registers by using a `PUSH` or modifies the `RSP` register by using an additional fixed stack allocation isn't supported. -An UNWIND_INFO item that has UNW_FLAG_CHAININFO set can contain a RUNTIME_FUNCTION entry whose UNWIND_INFO item also has UNW_FLAG_CHAININFO set, sometimes called *multiple shrink-wrapping*. Eventually, the chained unwind info pointers arrive at an UNWIND_INFO item that has UNW_FLAG_CHAININFO cleared. This item is the primary UNWIND_INFO item, which points to the actual procedure entry point. +An `UNWIND_INFO` item that has `UNW_FLAG_CHAININFO` set can contain a `RUNTIME_FUNCTION` entry whose `UNWIND_INFO` item also has `UNW_FLAG_CHAININFO` set, sometimes called *multiple shrink-wrapping*. Eventually, the chained unwind info pointers arrive at an `UNWIND_INFO` item that has `UNW_FLAG_CHAININFO` cleared. This item is the primary `UNWIND_INFO` item, which points to the actual procedure entry point. ## Unwind procedure -The unwind code array is sorted into descending order. When an exception occurs, the complete context is stored by the operating system in a context record. The exception dispatch logic is then invoked, which repeatedly executes these steps to find an exception handler: +The unwind code array is sorted into descending order. When an exception occurs, the operating system stores the complete context in a context record. The exception dispatch logic is then invoked, which repeatedly executes these steps to find an exception handler: -1. Use the current RIP stored in the context record to search for a RUNTIME_FUNCTION table entry that describes the current function (or function portion, for chained UNWIND_INFO entries). +1. Use the current `RIP` stored in the context record to search for a `RUNTIME_FUNCTION` table entry that describes the current function (or function portion, for chained `UNWIND_INFO` entries). -1. If no function table entry is found, then it's in a leaf function, and RSP directly addresses the return pointer. The return pointer at [RSP] is stored in the updated context, the simulated RSP is incremented by 8, and step 1 is repeated. +1. If the search doesn't find a function table entry, the code is assumed to be part of a leaf function, and `RSP` directly addresses the return pointer. The return pointer at [`RSP`] is stored in the updated context, the simulated `RSP` is incremented by 8, and step 1 is repeated. -1. If a function table entry is found, RIP can lie within three regions: a) in an epilog, b) in the prolog, or c) in code that may be covered by an exception handler. +1. If the search finds a function table entry, `RIP` can lie within three regions: a) in an epilog, b) in the prolog, or c) in code that might be covered by an exception handler. - - Case a) If the RIP is within an epilog, then control is leaving the function, there can be no exception handler associated with this exception for this function, and the effects of the epilog must be continued to compute the context of the caller function. To determine if the RIP is within an epilog, the code stream from RIP onward is examined. If that code stream can be matched to the trailing portion of a legitimate epilog, then it's in an epilog, and the remaining portion of the epilog is simulated, with the context record updated as each instruction is processed. After this processing, step 1 is repeated. + - Case a) If the `RIP` is within an epilog, control is leaving the function. There can be no exception handler associated with this exception for this function. The effects of the epilog must continue to compute the context of the caller function. To determine if the `RIP` is within an epilog, the code stream from `RIP` onward is examined. If that code stream matches the trailing portion of a legitimate epilog, it's in an epilog. The remaining portion of the epilog is simulated, with the context record updated as each instruction is processed. After this processing, step 1 is repeated. - - Case b) If the RIP lies within the prologue, then control hasn't entered the function, there can be no exception handler associated with this exception for this function, and the effects of the prolog must be undone to compute the context of the caller function. The RIP is within the prolog if the distance from the function start to the RIP is less than or equal to the prolog size encoded in the unwind info. The effects of the prolog are unwound by scanning forward through the unwind codes array for the first entry with an offset less than or equal to the offset of the RIP from the function start, then undoing the effect of all remaining items in the unwind code array. Step 1 is then repeated. + - Case b) If the `RIP` lies within the prolog, control hasn't entered the function. There can be no exception handler associated with this exception for this function. The effects of the prolog must be undone to compute the context of the caller function. The `RIP` is within the prolog if the distance from the function start to the `RIP` is less than or equal to the prolog size encoded in the unwind info. The unwinder scans forward through the unwind codes array for the first entry with an offset less than or equal to the offset of the `RIP` from the function start, then undoes the effect of all remaining items in the unwind code array. Step 1 is then repeated. - - Case c) If the RIP isn't within a prolog or epilog, and the function has an exception handler (UNW_FLAG_EHANDLER is set), then the language-specific handler is called. The handler scans its data and calls filter functions as appropriate. The language-specific handler can return that the exception was handled or that the search is to be continued. It can also initiate an unwind directly. + - Case c) If the `RIP` isn't within a prolog or epilog, and the function has an exception handler (`UNW_FLAG_EHANDLER` is set), the language-specific handler is called. The handler scans its data and calls filter functions as appropriate. The language-specific handler can return that the exception was handled or that the search is to be continued. It can also initiate an unwind directly. -1. If the language-specific handler returns a handled status, then execution is continued using the original context record. +1. If the language-specific handler returns a handled status, execution continues by using the original context record. -1. If there's no language-specific handler or the handler returns a "continue search" status, then the context record must be unwound to the state of the caller. It's done by processing all of the unwind code array elements, undoing the effect of each. Step 1 is then repeated. +1. If there's no language-specific handler or the handler returns a "continue search" status, the context record must be unwound to the state of the caller. The unwinder undoes the effect of each element in the unwind code array. Step 1 is then repeated. -When chained unwind info is involved, these basic steps are still followed. The only difference is that, while walking the unwind code array to unwind a prolog's effects, once the end of the array is reached, it's then linked to the parent unwind info and the entire unwind code array found there is walked. This linking continues until arriving at an unwind info without the UNW_CHAINED_INFO flag, and then it finishes walking its unwind code array. +When chained unwind info is involved, these basic steps are still followed. The only difference is that, while walking the unwind code array to unwind a prolog's effects, once the process reaches the end of the array, it links to the parent unwind info and walks the entire unwind code array found there. This linking continues until arriving at an unwind info without the `UNW_CHAINED_INFO` flag, and then it finishes walking its unwind code array. -The smallest set of unwind data is 8 bytes. This would represent a function that only allocated 128 bytes of stack or less, and possibly saved one nonvolatile register. It's also the size of a chained unwind info structure for a zero-length prolog with no unwind codes. +The smallest set of unwind data is 8 bytes. Such set represents a function that only allocated 128 bytes of stack or less, and possibly saved one nonvolatile register. It's also the size of a chained unwind info structure for a zero-length prolog with no unwind codes. ## Language-specific handler -The relative address of the language-specific handler is present in the UNWIND_INFO whenever flags UNW_FLAG_EHANDLER or UNW_FLAG_UHANDLER are set. As described in the previous section, the language-specific handler is called as part of the search for an exception handler or as part of an unwind. It has this prototype: +The `UNWIND_INFO` structure provides the relative address of the language-specific handler when either `UNW_FLAG_EHANDLER` or `UNW_FLAG_UHANDLER` flags are set. As described in the previous section, the search for an exception handler or the process of unwinding calls the language-specific handler. The handler uses this prototype: ```cpp typedef EXCEPTION_DISPOSITION (*PEXCEPTION_ROUTINE) ( @@ -298,15 +302,15 @@ typedef struct _DISPATCHER_CONTEXT { } DISPATCHER_CONTEXT, *PDISPATCHER_CONTEXT; ``` -**ControlPc** is the value of RIP within this function. This value is either an exception address or the address at which control left the establishing function. The RIP is used to determine if control is within some guarded construct inside this function, for example, a **`__try`** block for **`__try`**/**`__except`** or **`__try`**/**`__finally`**. +**ControlPc** is the value of `RIP` within this function. This value is either an exception address or the address at which control left the establishing function. The `RIP` is used to determine if control is within some guarded construct inside this function, for example, a **`__try`** block for **`__try`**/**`__except`** or **`__try`**/**`__finally`**. -**ImageBase** is the image base (load address) of the module containing this function, to be added to the 32-bit offsets used in the function entry and unwind info to record relative addresses. +**ImageBase** is the image base (load address) of the module containing this function. The 32-bit offsets used in the function entry and unwind info should be added to the ImageBase obtain the final address. -**FunctionEntry** supplies a pointer to the RUNTIME_FUNCTION function entry holding the function and unwind info image-base relative addresses for this function. +**FunctionEntry** supplies a pointer to the `RUNTIME_FUNCTION` function entry holding the function and unwind info image-base relative addresses for this function. **EstablisherFrame** is the address of the base of the fixed stack allocation for this function. -**TargetIp** Supplies an optional instruction address that specifies the continuation address of the unwind. This address is ignored if **EstablisherFrame** isn't specified. +**TargetIp** supplies an optional instruction address that specifies the continuation address of the unwind. This address is ignored if **EstablisherFrame** isn't specified. **ContextRecord** points to the exception context, for use by the system exception dispatch/unwind code. @@ -316,19 +320,19 @@ typedef struct _DISPATCHER_CONTEXT { ## Unwind helpers for MASM -In order to write proper assembly routines, there's a set of pseudo-operations that can be used in parallel with the actual assembly instructions to create the appropriate .pdata and .xdata. And, there's a set of macros that provide simplified use of the pseudo-operations for their most common uses. +To write proper assembly routines, use a set of pseudo-operations alongside the actual assembly instructions. These pseudo-operations create the appropriate `.pdata` and `.xdata`. Also, use a set of macros that simplify the use of these pseudo-operations for their most common uses. ### Raw pseudo-operations |Pseudo operation|Description| |-|-| -|PROC FRAME \[:*ehandler*]|Causes MASM to generate a function table entry in .pdata and unwind information in .xdata for a function's structured exception handling unwind behavior. If *ehandler* is present, this proc is entered in the .xdata as the language-specific handler.

When the FRAME attribute is used, it must be followed by an .ENDPROLOG directive. If the function is a leaf function (as defined in [Function types](../build/stack-usage.md#function-types)) the FRAME attribute is unnecessary, as are the remainder of these pseudo-operations.| -|.PUSHREG *register*|Generates a UWOP_PUSH_NONVOL unwind code entry for the specified register number using the current offset in the prologue.

Only use it with nonvolatile integer registers. For pushes of volatile registers, use an .ALLOCSTACK 8, instead| -|.SETFRAME *register*, *offset*|Fills in the frame register field and offset in the unwind information using the specified register and offset. The offset must be a multiple of 16 and less than or equal to 240. This directive also generates a UWOP_SET_FPREG unwind code entry for the specified register using the current prologue offset.| -|.ALLOCSTACK *size*|Generates a UWOP_ALLOC_SMALL or a UWOP_ALLOC_LARGE with the specified size for the current offset in the prologue.

The *size* operand must be a multiple of 8.| -|.SAVEREG *register*, *offset*|Generates either a UWOP_SAVE_NONVOL or a UWOP_SAVE_NONVOL_FAR unwind code entry for the specified register and offset using the current prologue offset. MASM chooses the most efficient encoding.

*offset* must be positive, and a multiple of 8. *offset* is relative to the base of the procedure's frame, which is generally in RSP, or, if using a frame pointer, the unscaled frame pointer.| -|.SAVEXMM128 *register*, *offset*|Generates either a UWOP_SAVE_XMM128 or a UWOP_SAVE_XMM128_FAR unwind code entry for the specified XMM register and offset using the current prologue offset. MASM chooses the most efficient encoding.

*offset* must be positive, and a multiple of 16. *offset* is relative to the base of the procedure's frame, which is generally in RSP, or, if using a frame pointer, the unscaled frame pointer.| -|.PUSHFRAME \[*code*]|Generates a UWOP_PUSH_MACHFRAME unwind code entry. If the optional *code* is specified, the unwind code entry is given a modifier of 1. Otherwise the modifier is 0.| +|PROC FRAME \[:*ehandler*]|Causes MASM to generate a function table entry in `.pdata` and unwind information in `.xdata` for a function's structured exception handling unwind behavior. If *ehandler* is present, this proc is entered in the .xdata as the language-specific handler.

When you use the FRAME attribute, follow it with an .ENDPROLOG directive. If the function is a leaf function (as defined in [Function types](../build/stack-usage.md#function-types)), the FRAME attribute is unnecessary, as are the remainder of these pseudo-operations.| +|.PUSHREG *register*|Generates a `UWOP_PUSH_NONVOL` unwind code entry for the specified register number using the current offset in the prologue.

Only use it with nonvolatile integer registers. For pushes of volatile registers, use an .ALLOCSTACK 8, instead.| +|.SETFRAME *register*, *offset*|Fills in the frame register field and offset in the unwind information using the specified register and offset. The offset must be a multiple of 16 and less than or equal to 240. This directive also generates a `UWOP_SET_FPREG` unwind code entry for the specified register using the current prologue offset.| +|.ALLOCSTACK *size*|Generates a `UWOP_ALLOC_SMALL` or a `UWOP_ALLOC_LARGE` with the specified size for the current offset in the prologue.

The *size* operand must be a multiple of 8.| +|.SAVEREG *register*, *offset*|Generates either a `UWOP_SAVE_NONVOL` or a `UWOP_SAVE_NONVOL_FAR` unwind code entry for the specified register and offset using the current prologue offset. MASM chooses the most efficient encoding.

*offset* must be positive, and a multiple of 8. *offset* is relative to the base of the procedure's frame, which is generally in `RSP`, or, if using a frame pointer, the unscaled frame pointer.| +|.SAVEXMM128 *register*, *offset*|Generates either a `UWOP_SAVE_XMM128` or a `UWOP_SAVE_XMM128_FAR` unwind code entry for the specified `XMM` register and offset using the current prologue offset. MASM chooses the most efficient encoding.

*offset* must be positive, and a multiple of 16. *offset* is relative to the base of the procedure's frame, which is generally in `RSP`, or, if using a frame pointer, the unscaled frame pointer.| +|.PUSHFRAME \[*code*]|Generates a `UWOP_PUSH_MACHFRAME` unwind code entry. If you specify the optional *code*, the unwind code entry gets a modifier of 1. Otherwise the modifier is 0.| |.ENDPROLOG|Signals the end of the prologue declarations. Must occur in the first 255 bytes of the function.| Here's a sample function prolog with proper usage of most of the opcodes: @@ -384,19 +388,19 @@ For more information about the epilog example, see [Epilog code](prolog-and-epil ### MASM macros -In order to simplify the use of the [Raw pseudo-operations](#raw-pseudo-operations), there's a set of macros, defined in ksamd64.inc, which can be used to create typical procedure prologues and epilogues. +To simplify the use of [Raw pseudo-operations](#raw-pseudo-operations), use the set of macros defined in `ksamd64.inc`. These macros help you create typical procedure prologues and epilogues. |Macro|Description| |-|-| -|alloc_stack(n)|Allocates a stack frame of n bytes (using `sub rsp, n`), and emits the appropriate unwind information (.allocstack n)| -|save_reg *reg*, *loc*|Saves a nonvolatile register *reg* on the stack at RSP offset *loc*, and emits the appropriate unwind information. (.savereg reg, loc)| -|push_reg *reg*|Pushes a nonvolatile register *reg* on the stack, and emits the appropriate unwind information. (.pushreg reg)| -|rex_push_reg *reg*|Saves a nonvolatile register on the stack using a 2-byte push, and emits the appropriate unwind information (.pushreg reg). Use this macro if the push is the first instruction in the function, to ensure that the function is hot-patchable.| -|save_xmm128 *reg*, *loc*|Saves a nonvolatile XMM register *reg* on the stack at RSP offset *loc*, and emits the appropriate unwind information (.savexmm128 reg, loc)| -|set_frame *reg*, *offset*|Sets the frame register *reg* to be the RSP + *offset* (using a `mov`, or an `lea`), and emits the appropriate unwind information (.set_frame reg, offset)| -|push_eflags|Pushes the eflags with a `pushfq` instruction, and emits the appropriate unwind information (.alloc_stack 8)| - -Here's a sample function prolog with proper usage of the macros: +|alloc_stack(n)|Allocates a stack frame of *n* bytes (using `sub rsp, n`), and emits the appropriate unwind information (.allocstack n)| +|save_reg *reg*, *loc*|Saves a nonvolatile register *reg* on the stack at `RSP` offset *loc*, and emits the appropriate unwind information (.savereg reg, loc)| +|push_reg *reg*|Pushes a nonvolatile register *reg* on the stack, and emits the appropriate unwind information (.pushreg reg)| +|rex_push_reg *reg*|Saves a nonvolatile register on the stack by using a 2-byte push, and emits the appropriate unwind information (.pushreg reg). Use this macro if the push is the first instruction in the function, to ensure that the function is hot-patchable.| +|save_xmm128 *reg*, *loc*|Saves a nonvolatile `XMM` register *reg* on the stack at `RSP` offset *loc*, and emits the appropriate unwind information (.savexmm128 reg, loc)| +|set_frame *reg*, *offset*|Sets the frame register *reg* to be the `RSP` + *offset* (using a `mov` or an `lea`), and emits the appropriate unwind information (.set_frame reg, offset)| +|push_eflags|Pushes the eflags by using a `pushfq` instruction, and emits the appropriate unwind information (.alloc_stack 8)| + +Here's a sample function prologue with proper usage of the macros: ```MASM sampleFrame struct diff --git a/docs/build/exporting-and-importing-using-afx-ext-class.md b/docs/build/exporting-and-importing-using-afx-ext-class.md index 0d16f63d7b8..e47b06663e8 100644 --- a/docs/build/exporting-and-importing-using-afx-ext-class.md +++ b/docs/build/exporting-and-importing-using-afx-ext-class.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" f1_keywords: ["afx_ext_class"] helpviewer_keywords: ["AFX_EXT_CLASS macro", "exporting classes [C++]", "importing DLLs [C++]", "extension DLLs [C++], exporting classes", "executable files [C++], importing classes", "exporting DLLs [C++], AFX_EXT_CLASS macro"] ms.assetid: 6b72cb2b-e92e-4ecd-bcab-c335e1d1cfde +ms.topic: concept-article --- # Exporting and Importing Using AFX_EXT_CLASS diff --git a/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md b/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md index 2386881514b..4096be3e6e2 100644 --- a/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md +++ b/docs/build/exporting-c-functions-for-use-in-c-or-cpp-language-executables.md @@ -4,6 +4,7 @@ title: "Export C functions for use in C or C++ language executables" ms.date: 05/24/2022 helpviewer_keywords: ["functions [C], exporting", "functions [C], C or C++ executables and", "__cplusplus macro", "exporting DLLs [C++], C functions in C++ executables", "exporting functions [C++], C functions in C++ executables"] ms.assetid: b51d6e5e-37cf-4c1c-b0bf-fcf188c82f00 +ms.topic: how-to --- # Export C functions for use in C or C++ language executables diff --git a/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md b/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md index decb3fd8916..d44fe579a36 100644 --- a/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md +++ b/docs/build/exporting-cpp-functions-for-use-in-c-language-executables.md @@ -4,6 +4,7 @@ title: "Exporting C++ Functions for Use in C-Language Executables" ms.date: "11/04/2016" helpviewer_keywords: ["functions [C++], C++ functions in C executables", "exporting DLLs [C++], C++ functions in C executables", "exporting functions [C++], C++ functions in C executables", "functions [C++], exporting"] ms.assetid: 80b9e982-f52d-4312-a891-f73cc69f3c2b +ms.topic: concept-article --- # Exporting C++ Functions for Use in C-Language Executables diff --git a/docs/build/exporting-from-a-dll-using-declspec-dllexport.md b/docs/build/exporting-from-a-dll-using-declspec-dllexport.md index 46f17afc299..674c52fb8dd 100644 --- a/docs/build/exporting-from-a-dll-using-declspec-dllexport.md +++ b/docs/build/exporting-from-a-dll-using-declspec-dllexport.md @@ -5,6 +5,7 @@ ms.date: "05/06/2019" f1_keywords: ["dllexport"] helpviewer_keywords: ["__declspec(dllexport) keyword [C++]", "names [C++], DLL exports by", "export directives [C++]", "exporting DLLs [C++], __declspec(dllexport) keyword"] ms.assetid: a35e25e8-7263-4a04-bad4-00b284458679 +ms.topic: how-to --- # Exporting from a DLL Using __declspec(dllexport) diff --git a/docs/build/exporting-from-a-dll-using-def-files.md b/docs/build/exporting-from-a-dll-using-def-files.md index c0cabdb87a1..653273a5fe2 100644 --- a/docs/build/exporting-from-a-dll-using-def-files.md +++ b/docs/build/exporting-from-a-dll-using-def-files.md @@ -4,6 +4,7 @@ title: "Exporting from a DLL Using DEF Files" ms.date: "05/06/2019" helpviewer_keywords: ["def files [C++], exporting from DLLs", ".def files [C++], exporting from DLLs", "exporting DLLs [C++], DEF files"] ms.assetid: 9d31eda2-184e-47de-a2ee-a93ebd603f8e +ms.topic: concept-article --- # Exporting from a DLL Using DEF Files @@ -28,7 +29,7 @@ EXPORTS If you use the [MFC DLL Wizard](../mfc/reference/mfc-dll-wizard.md) to create an MFC DLL, the wizard creates a skeleton DEF file for you and automatically adds it to your project. Add the names of the functions to be exported to this file. For non-MFC DLLs, create the DEF file yourself and add it to your project. Then go to **Project** > **Properties** > **Linker** > **Input** > **Module Definition File** and enter the name of the DEF file. Repeat this step for each configuration and platform, or do it all at once by selecting **Configuration = All Configurations**, and **Platform = All Platforms**. -If you are exporting functions in a C++ file, you have to either place the decorated names in the DEF file or define your exported functions with standard C linkage by using extern "C". If you need to place the decorated names in the DEF file, you can obtain them by using the [DUMPBIN](../build/reference/dumpbin-reference.md) tool or by using the linker [/MAP](../build/reference/map-generate-mapfile.md) option. Note that the decorated names produced by the compiler are compiler specific. If you place the decorated names produced by the Microsoft C++ compiler (MSVC) into a DEF file, applications that link to your DLL must also be built using the same version of MSVC so that the decorated names in the calling application match the exported names in the DLL's DEF file. +If you are exporting functions in a C++ file, you have to either place the decorated names in the DEF file or define your exported functions with standard C linkage by using extern "C". If you need to place the decorated names in the DEF file, you can obtain them by using the [DUMPBIN](../build/reference/dumpbin-reference.md) tool or by using the linker [/MAP](../build/reference/map-generate-mapfile.md) option. Note that the decorated names produced by the compiler are compiler specific. If you place the decorated names produced by the Microsoft C++ (MSVC) compiler into a DEF file, applications that link to your DLL must also be built using the same version of MSVC so that the decorated names in the calling application match the exported names in the DLL's DEF file. > [!NOTE] > A DLL built with Visual Studio 2015 can be consumed by applications built with Visual Studio 2017 or Visual Studio 2019. diff --git a/docs/build/exporting-from-a-dll.md b/docs/build/exporting-from-a-dll.md index b05991ac322..d7513fc4776 100644 --- a/docs/build/exporting-from-a-dll.md +++ b/docs/build/exporting-from-a-dll.md @@ -4,6 +4,7 @@ title: "Exporting from a DLL" ms.date: "11/04/2016" helpviewer_keywords: ["exporting DLLs [C++], about exporting from DLLs", "exporting functions [C++], DLLs (exporting from)", "exporting DLLs [C++]", "DLLs [C++], exporting from", "DLL exports [C++]", "functions [C++], exporting", "exports table [C++]"] ms.assetid: a08f86c4-5996-460b-ae54-da2b764045f0 +ms.topic: concept-article --- # Exporting from a DLL diff --git a/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md b/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md index 1a3e10eeaeb..d5911954fb9 100644 --- a/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md +++ b/docs/build/exporting-functions-from-a-dll-by-ordinal-rather-than-by-name.md @@ -4,6 +4,7 @@ title: "Exporting Functions from a DLL by Ordinal Rather Than by Name" ms.date: "11/04/2016" helpviewer_keywords: ["exporting functions [C++], ordinal values", "ordinal exports [C++]", "exporting DLLs [C++], ordinal values", "NONAME attribute"] ms.assetid: 679719fd-d965-4df3-9f7a-7d86ad831702 +ms.topic: concept-article --- # Exporting Functions from a DLL by Ordinal Rather Than by Name diff --git a/docs/build/extension-dlls-overview.md b/docs/build/extension-dlls-overview.md index 9efaa880faa..b43f909510c 100644 --- a/docs/build/extension-dlls-overview.md +++ b/docs/build/extension-dlls-overview.md @@ -4,6 +4,7 @@ title: "Extension DLLs: Overview" ms.date: "05/06/2019" helpviewer_keywords: ["AFXDLL library", "MFC DLLs [C++], MFC extension DLLs", "DLLs [C++], extension", "shared DLL versions [C++]", "extension DLLs [C++], about MFC extension DLLs"] ms.assetid: eb5e10b7-d615-4bc7-908d-e3e99b7b1d5f +ms.topic: concept-article --- # MFC extension DLLs: Overview diff --git a/docs/build/fixing-release-build-problems.md b/docs/build/fixing-release-build-problems.md index b329363dc97..f10be40f3e4 100644 --- a/docs/build/fixing-release-build-problems.md +++ b/docs/build/fixing-release-build-problems.md @@ -4,6 +4,7 @@ title: "Fixing Release Build Problems" ms.date: "11/04/2016" helpviewer_keywords: ["release builds, troubleshooting", "debug builds, memory overwrites", "memory, overwrites", "troubleshooting Visual C++, release builds", "troubleshooting release builds"] ms.assetid: a0c0818e-4c47-4fe0-a611-50d61a41bd88 +ms.topic: concept-article --- # Fixing Release Build Problems diff --git a/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md b/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md index 938dc064259..b8c2ff6f181 100644 --- a/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md +++ b/docs/build/formatting-the-output-of-a-custom-build-step-or-build-event.md @@ -4,6 +4,7 @@ title: "Formatting the output of a custom build step or build event" ms.date: 03/15/2022 helpviewer_keywords: ["builds [C++], build events", "custom build steps [C++], output format", "events [C++], build", "build events [C++], output format", "build steps [C++], output format", "builds [C++], custom build steps"] ms.assetid: 92ad3e38-24d7-4b89-90e6-5a16f5f998da +ms.topic: concept-article --- # Formatting the output of a custom build step or build event diff --git a/docs/build/get-started-linux-cmake.md b/docs/build/get-started-linux-cmake.md index 693ada2f60a..b2f59a73810 100644 --- a/docs/build/get-started-linux-cmake.md +++ b/docs/build/get-started-linux-cmake.md @@ -3,6 +3,7 @@ title: Create C++ cross-platform projects in Visual Studio description: "How to set up, compile, and debug a C++ open-source CMake project in Visual Studio that targets both Linux and Windows." ms.topic: tutorial ms.date: 02/07/2022 +ms.custom: sfi-image-nochange --- # Tutorial: Create C++ cross-platform projects in Visual Studio @@ -21,11 +22,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 +52,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 +100,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 +124,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 +146,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 +170,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 +180,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 +208,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 338beeacb2c..7d4b11a4b26 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 bb260ccf93e..3063cfc32b2 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 1c061847d22..e551b430faf 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 @@ -26,7 +27,7 @@ Any of the native or cross compiler tools build configurations can be used on th > [!NOTE] > For information about the specific tools that are included with each Visual Studio edition, see [Visual C++ Tools and Features in Visual Studio Editions](../overview/visual-cpp-tools-and-features-in-visual-studio-editions.md). > -> For information about how to use the Visual Studio IDE to create 64-bit applications, see [How to: Configure Visual C++ Projects to Target 64-Bit, x64 Platforms](how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md). +> For information about how to use the Visual Studio IDE to create 64-bit applications, see [How to: Configure Microsoft C++ Projects to Target 64-Bit, x64 Platforms](how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md). When you install a C++ workload in the Visual Studio installer, it always installs 32-bit, x86-hosted, native and cross compiler tools to build x86 and x64 code. If you include the Universal Windows Platform workload, it also installs x86-hosted cross compiler tools to build ARM code. If you install these workloads on a 64-bit, x64 processor, you also get 64-bit native and cross compiler tools to build x86, x64, and ARM code. The 32-bit and 64-bit tools generate identical code, but the 64-bit tools support more memory for precompiled header symbols and the Whole Program Optimization ([/GL](reference/gl-whole-program-optimization.md) and [/LTCG](reference/ltcg-link-time-code-generation.md)) options. If you run into memory limits when you use the 32-bit tools, try the 64-bit tools. 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 b85c149a468..3c80c787b4a 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"] --- @@ -11,7 +10,7 @@ You can edit a Visual Studio C++ project file to target different versions of th ## Platform toolset -The platform toolset consists of the C++ compiler (cl.exe) and linker (link.exe), along with the C/C++ standard libraries. Visual Studio 2015, Visual Studio 2017, and Visual Studio 2019 are binary-compatible. It's shown by the major version of the toolset, which has remained at 14. Projects compiled in Visual Studio 2019 or Visual Studio 2017 are ABI-backwards-compatible with 2017 and 2015 projects. The minor version has updated by 1 for each version since Visual Studio 2015: +The platform toolset consists of the Microsoft C++ (MSVC) compiler (cl.exe) and linker (link.exe), along with the C/C++ standard libraries. Visual Studio 2015, Visual Studio 2017, and Visual Studio 2019 are binary-compatible. It's shown by the major version of the toolset, which has remained at 14. Projects compiled in Visual Studio 2019 or Visual Studio 2017 are ABI-backwards-compatible with 2017 and 2015 projects. The minor version has updated by 1 for each version since Visual Studio 2015: - Visual Studio 2015: v140 - Visual Studio 2017: v141 @@ -24,9 +23,9 @@ 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. +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 Microsoft C++ Team blog. ### To change the target Framework 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 c747397334d..72aea3d96ac 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/image.png b/docs/build/image.png new file mode 100644 index 00000000000..f892839fa3f Binary files /dev/null and b/docs/build/image.png differ diff --git a/docs/build/importing-and-exporting-inline-functions.md b/docs/build/importing-and-exporting-inline-functions.md index ec71f01e74a..c34b0859a15 100644 --- a/docs/build/importing-and-exporting-inline-functions.md +++ b/docs/build/importing-and-exporting-inline-functions.md @@ -4,6 +4,7 @@ title: "Importing and exporting inline functions" ms.date: "11/04/2016" helpviewer_keywords: ["exporting functions [C++], inline functions", "inline functions [C++], importing", "DLLs [C++], importing", "importing functions [C++]", "DLLs [C++], exporting from", "importing inline functions [C++]", "inline functions [C++], exporting", "functions [C++], importing", "functions [C++], exporting"] ms.assetid: 89f488f8-b078-40fe-afd7-80bd7840057b +ms.topic: concept-article --- # Importing and exporting inline functions diff --git a/docs/build/importing-and-exporting.md b/docs/build/importing-and-exporting.md index 322232d23b8..87ecffe0203 100644 --- a/docs/build/importing-and-exporting.md +++ b/docs/build/importing-and-exporting.md @@ -4,6 +4,7 @@ title: "Importing and Exporting" ms.date: "05/06/2019" helpviewer_keywords: ["DLLs [C++], importing", "exporting DLLs [C++]", "importing DLLs [C++]", "DLLs [C++], exporting from", "__declspec(dllimport) keyword [C++]"] ms.assetid: 7c44c2aa-2117-4cec-9615-a65bfd3f8f7b +ms.topic: concept-article --- # Importing and Exporting diff --git a/docs/build/importing-data-using-declspec-dllimport.md b/docs/build/importing-data-using-declspec-dllimport.md index bfe281afe38..eeec7bf2ffe 100644 --- a/docs/build/importing-data-using-declspec-dllimport.md +++ b/docs/build/importing-data-using-declspec-dllimport.md @@ -4,6 +4,7 @@ description: "How to use __declspec(dllimport) to import DLL data." ms.date: 09/03/2020 helpviewer_keywords: ["importing data [C++]", "dllimport attribute [C++], data imports", "__declspec(dllimport) keyword [C++]", "importing DLLs [C++], __declspec(dllimport)"] ms.assetid: 0ae70b39-87c7-4181-8be9-e786e0db60b0 +ms.topic: concept-article --- # Importing data using `__declspec(dllimport)` diff --git a/docs/build/importing-function-calls-using-declspec-dllimport.md b/docs/build/importing-function-calls-using-declspec-dllimport.md index e275b0ec866..4d4472780a7 100644 --- a/docs/build/importing-function-calls-using-declspec-dllimport.md +++ b/docs/build/importing-function-calls-using-declspec-dllimport.md @@ -4,6 +4,7 @@ description: "How and why to use __declspec(dllimport) when calling DLL data and ms.date: "05/03/2020" helpviewer_keywords: ["importing function calls [C++]", "dllimport attribute [C++], function call imports", "__declspec(dllimport) keyword [C++]", "function calls [C++], importing"] ms.assetid: 6b53c616-0c6d-419a-8e2a-d2fff20510b3 +ms.topic: concept-article --- # Importing function calls using `__declspec(dllimport)` diff --git a/docs/build/importing-into-an-application-using-declspec-dllimport.md b/docs/build/importing-into-an-application-using-declspec-dllimport.md index 7b8247460ee..c50718d79d0 100644 --- a/docs/build/importing-into-an-application-using-declspec-dllimport.md +++ b/docs/build/importing-into-an-application-using-declspec-dllimport.md @@ -4,6 +4,7 @@ title: "Import into an application using __declspec(dllimport)" ms.date: "11/04/2016" helpviewer_keywords: ["__declspec(dllimport) keyword [C++]", "importing DLLs [C++], __declspec(dllimport)"] ms.assetid: edb4da4e-f83a-44cf-a668-9239d49dbe42 +ms.topic: how-to --- # Import into an application using __declspec(dllimport) diff --git a/docs/build/importing-into-an-application.md b/docs/build/importing-into-an-application.md index f2458e128f9..c944f53c123 100644 --- a/docs/build/importing-into-an-application.md +++ b/docs/build/importing-into-an-application.md @@ -4,6 +4,7 @@ title: "Importing into an Application" ms.date: "11/04/2016" helpviewer_keywords: ["DLLs [C++], importing", "importing DLLs [C++], applications", "applications [C++], importing into"] ms.assetid: 9d646466-e12e-4710-8ad9-c819c0375fcc +ms.topic: concept-article --- # Importing into an Application diff --git a/docs/build/importing-using-def-files.md b/docs/build/importing-using-def-files.md index e52767c7695..f8cd00daca4 100644 --- a/docs/build/importing-using-def-files.md +++ b/docs/build/importing-using-def-files.md @@ -4,6 +4,7 @@ title: "Importing Using DEF Files" ms.date: "11/04/2016" helpviewer_keywords: ["importing DLLs [C++], DEF files", "def files [C++], importing with", ".def files [C++], importing with", "dllimport attribute [C++], DEF files", "DLLs [C++], DEF files"] ms.assetid: aefdbf50-f603-488a-b0d7-ed737bae311d +ms.topic: concept-article --- # Importing Using DEF Files @@ -49,7 +50,7 @@ if (ulDataInDll == 0L) /*sample code fragment*/ Using CONSTANT is more risky because if you forget to use the extra level of indirection, you could potentially access the import address table's pointer to the variable — not the variable itself. This type of problem can often manifest as an access violation because the import address table is currently made read-only by the compiler and linker. -The current MSVC linker issues a warning if it sees CONSTANT in the .def file to account for this case. The only real reason to use CONSTANT is if you cannot recompile some object file where the header file did not list **`__declspec(dllimport)`** on the prototype. +The current Microsoft C++ (MSVC) linker issues a warning if it sees CONSTANT in the .def file to account for this case. The only real reason to use CONSTANT is if you cannot recompile some object file where the header file did not list **`__declspec(dllimport)`** on the prototype. ## See also diff --git a/docs/build/improving-compiler-throughput.md b/docs/build/improving-compiler-throughput.md index c71675de078..3da2de62fc5 100644 --- a/docs/build/improving-compiler-throughput.md +++ b/docs/build/improving-compiler-throughput.md @@ -4,6 +4,7 @@ title: "Improving Compiler Throughput" ms.date: "11/04/2016" helpviewer_keywords: ["throughput, C++ compiler", "cl.exe compiler, performance", "performance, compiler", "cl.exe compiler, throughput"] ms.assetid: ba5f884e-9037-4a92-b10e-fc2a3836c5bf +ms.topic: concept-article --- # Improving Compiler Throughput diff --git a/docs/build/launch-vs-schema-reference-cpp.md b/docs/build/launch-vs-schema-reference-cpp.md index ca7dcc9b704..e7d4f24ef18 100644 --- a/docs/build/launch-vs-schema-reference-cpp.md +++ b/docs/build/launch-vs-schema-reference-cpp.md @@ -17,8 +17,8 @@ To create the file, right-click on an executable file in **Solution Explorer** a | `args` | array | Specifies the command-line arguments passed to the launched program. | | `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"`. | +| `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"`. | | `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. | @@ -27,9 +27,9 @@ To create the file, right-click on an executable file in **Solution Explorer** a | `program` | string | The debug command to execute. Defaults to `"${debugInfo.fullTargetPath}"`. | | `project` | string | Specifies the relative path to the project file. Normally, you don't need to change this value when debugging a CMake project. | | `projectTarget` | string | Specifies the optional target invoked when building `project`. The target must match the name in the **Startup Item** dropdown. | -| `stopOnEntry` | boolean | Specifies whether to break a soon as the process is launched and the debugger attaches. The default value for this parameter is **`false`**. | +| `stopOnEntry` | boolean | Specifies whether to break as soon as the process is launched and the debugger attaches. The default value for this parameter is **`false`**. | | `remoteMachine` | string | Specifies the name of the remote machine where the program is launched. | -| `type` | string | Specifies whether the project is a `dll` or `exe` Defaults to .exe | +| `type` | string | Specifies whether the project is a `dll` or `exe`. Defaults to `"exe"`. | ## C++ Linux properties @@ -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 @@ -64,7 +64,7 @@ The following macros provide information about the debugging environment. They'r | Macro | Description | Example | |--|--|--| -| `addressSanitizerRuntimeFlags` | Runtime flags used to customize behavior of the address sanitizer. Used to set the environment variable `"ASAN_OPTIONS"`. | `"env": {"ASAN_OPTIONS": "${addressSanitizerRuntimeFlags}:anotherFlag=true"`} | +| `addressSanitizerRuntimeFlags` | Runtime flags used to customize behavior of the address sanitizer. Used to set the environment variable `"ASAN_OPTIONS"`. | `"env": {"ASAN_OPTIONS": "${addressSanitizerRuntimeFlags}:anotherFlag=true"}` | | `defaultWorkingDirectory` | Set to the directory part of `"fullTargetPath"`. If the CMake variable `VS_DEBUGGER_WORKING_DIRECTORY` is defined, then `defaultWorkingDirectory` is set to that value, instead. | `"cwd":"${debugInfo.defaultWorkingDirectory}"` | | `fullTargetPath` | The full path to the binary being debugged. | `"program": "${debugInfo.fullTargetPath}"` | | `linuxNatvisPath` | The full windows path to the VS linux `.natvis` file. Usually appears as the value `"visualizerFile"`. | | @@ -98,7 +98,7 @@ The pipeTransport example below shows how to use some of the `debugInfo` macros "/c", "${debuggerCommand}" ] - } +} ``` ## C++ Windows remote debug and deploy properties @@ -109,8 +109,8 @@ Used when debugging and deploying an app on a remote machine. |--|--|--| | `cwd` | string | The working directory of the target on the remote machine. When using CMake, the macro `${debugInfo.defaultWorkingDirectory}` can be used as the value of this field. The default value is the directory of the debug program/command. | | `deploy` | string | Specifies extra files or directories to deploy. For example:
`"deploy": {"sourcePath":"", "targetPath":""}` | -| `deployDirectory` | string | The location on the remote machine where project outputs are automatically deployed to. Defaults to "`C:\Windows Default Deploy Directory\` | -| `deployDebugRuntimeLibraries` | string | Specifies whether to deploy the debug runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"Debug"` | +| `deployDirectory` | string | The location on the remote machine where project outputs are automatically deployed to. Defaults to `"C:\Windows Default Deploy Directory\"`. | +| `deployDebugRuntimeLibraries` | string | Specifies whether to deploy the debug runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"Debug"`. | | `deployRuntimeLibraries` | string | Specifies whether to deploy the runtime libraries for the active platform. Defaults to `"true"` if the active configurationType is `"MinSizeRel"`, `"RelWithDebInfo"`, or `"Release"`. | | `disableDeploy` | boolean | Specifies whether files should be deployed. | | `remoteMachineName` | string | Specifies the name of the remote ARM64 Windows machine where the program is launched. May be the server name or the remote machine's IP address. | diff --git a/docs/build/media/add-configure-preset-to-cmakepresets.png b/docs/build/media/add-configure-preset-to-cmakepresets.png index 343e8a85ed6..47d963209c0 100644 Binary files a/docs/build/media/add-configure-preset-to-cmakepresets.png and b/docs/build/media/add-configure-preset-to-cmakepresets.png differ diff --git a/docs/build/media/clang-install-vs2022.png b/docs/build/media/clang-install-vs2022.png new file mode 100644 index 00000000000..cd97b752d3a Binary files /dev/null and b/docs/build/media/clang-install-vs2022.png differ diff --git a/docs/build/media/cmake-build-errors.png b/docs/build/media/cmake-build-errors.png index 089db013a3a..80127fdebdb 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 afdedb01e33..345ec7ec4b2 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 6601ecbed34..5c0877845bb 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 f957bb6c1d5..58f47297791 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 00000000000..0f7eae51a24 Binary files /dev/null and b/docs/build/media/cmake-debugger-entry.png differ diff --git a/docs/build/media/cmake-general-prefer-cmake-presets.png b/docs/build/media/cmake-general-prefer-cmake-presets.png index 4cb0c1ac64c..10268170756 100644 Binary files a/docs/build/media/cmake-general-prefer-cmake-presets.png and b/docs/build/media/cmake-general-prefer-cmake-presets.png differ diff --git a/docs/build/media/cmake-install-2022.png b/docs/build/media/cmake-install-2022.png new file mode 100644 index 00000000000..870db48e1c9 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 f7560472056..ac9dab9002f 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 04ae1e2a13e..673ddd555bf 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 00000000000..881cbe8a367 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 00000000000..a9ba70b3c5c 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 a46faeb9477..00000000000 Binary files a/docs/build/media/desktop-app-project-run-150.gif and /dev/null differ diff --git a/docs/build/media/desktop-development-cpp-workload.png b/docs/build/media/desktop-development-cpp-workload.png new file mode 100644 index 00000000000..a321200feb5 Binary files /dev/null and b/docs/build/media/desktop-development-cpp-workload.png differ diff --git a/docs/build/media/github-copilot-fix-warning-accept.png b/docs/build/media/github-copilot-fix-warning-accept.png new file mode 100644 index 00000000000..bb8f3ded876 Binary files /dev/null and b/docs/build/media/github-copilot-fix-warning-accept.png differ diff --git a/docs/build/media/github-copilot-fix-warning.png b/docs/build/media/github-copilot-fix-warning.png new file mode 100644 index 00000000000..4751bafdf01 Binary files /dev/null and b/docs/build/media/github-copilot-fix-warning.png differ diff --git a/docs/build/media/github-copilot-open-chat.png b/docs/build/media/github-copilot-open-chat.png new file mode 100644 index 00000000000..c89019f9abc Binary files /dev/null and b/docs/build/media/github-copilot-open-chat.png differ diff --git a/docs/build/media/life-exe.png b/docs/build/media/life-exe.png new file mode 100644 index 00000000000..94bad16e7d6 Binary files /dev/null and b/docs/build/media/life-exe.png differ diff --git a/docs/build/media/new-dropdowns.png b/docs/build/media/new-dropdowns.png new file mode 100644 index 00000000000..47a83973c60 Binary files /dev/null and b/docs/build/media/new-dropdowns.png differ diff --git a/docs/build/media/normal-build-process.png b/docs/build/media/normal-build-process.png new file mode 100644 index 00000000000..fbf6c0d1796 Binary files /dev/null and b/docs/build/media/normal-build-process.png differ diff --git a/docs/build/media/options-configuration-file.png b/docs/build/media/options-configuration-file.png new file mode 100644 index 00000000000..2a22a033a17 Binary files /dev/null and b/docs/build/media/options-configuration-file.png differ diff --git a/docs/build/media/sample-profile-guided-optimization-build-process.png b/docs/build/media/sample-profile-guided-optimization-build-process.png new file mode 100644 index 00000000000..9de3effdc4b Binary files /dev/null and b/docs/build/media/sample-profile-guided-optimization-build-process.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 00000000000..455bbfebc9c 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 430fd309e72..80f0d633ed3 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 3b3db949ce5..659946ac9c2 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 57e12a44190..521ba2fec9d 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 763a22945ab..39ff39170dc 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/visual-studio-switch-cmake-targets-view.png b/docs/build/media/visual-studio-switch-cmake-targets-view.png new file mode 100644 index 00000000000..781528af193 Binary files /dev/null and b/docs/build/media/visual-studio-switch-cmake-targets-view.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 10d887cbcb4..00000000000 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 ac088d3aa2c..bc48f40b7a5 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 55a167526fc..3cba0d0efad 100644 --- a/docs/build/modify-project-properties-without-changing-project-file.md +++ b/docs/build/modify-project-properties-without-changing-project-file.md @@ -1,8 +1,9 @@ --- 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"] +ms.topic: how-to --- # How to: Modify C++ project properties and targets without changing the project file @@ -13,27 +14,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/msbuild-visual-cpp.md b/docs/build/msbuild-visual-cpp.md index 0066c81f6d9..858b524a7e4 100644 --- a/docs/build/msbuild-visual-cpp.md +++ b/docs/build/msbuild-visual-cpp.md @@ -44,7 +44,7 @@ Lists the MSBuild XML Schema elements, together with their attributes, and paren Describes the command-line arguments and options that you can use with msbuild.exe. - [Task Reference](/visualstudio/msbuild/msbuild-task-reference) -Describes MSBuild tasks. Especially note these tasks, which are specific to Visual C++: [BscMake Task](/visualstudio/msbuild/bscmake-task), [CL Task](/visualstudio/msbuild/cl-task), [CPPClean Task](/visualstudio/msbuild/cppclean-task), [LIB Task](/visualstudio/msbuild/lib-task), [Link Task](/visualstudio/msbuild/link-task), [MIDL Task](/visualstudio/msbuild/midl-task), [MT Task](/visualstudio/msbuild/mt-task), [RC Task](/visualstudio/msbuild/rc-task), [SetEnv Task](/visualstudio/msbuild/setenv-task), [VCMessage Task](/visualstudio/msbuild/vcmessage-task) +Describes MSBuild tasks. Especially note these tasks, which are specific to Microsoft C++: [BscMake Task](/visualstudio/msbuild/bscmake-task), [CL Task](/visualstudio/msbuild/cl-task), [CPPClean Task](/visualstudio/msbuild/cppclean-task), [LIB Task](/visualstudio/msbuild/lib-task), [Link Task](/visualstudio/msbuild/link-task), [MIDL Task](/visualstudio/msbuild/midl-task), [MT Task](/visualstudio/msbuild/mt-task), [RC Task](/visualstudio/msbuild/rc-task), [SetEnv Task](/visualstudio/msbuild/setenv-task), [VCMessage Task](/visualstudio/msbuild/vcmessage-task) ## In This Section diff --git a/docs/build/non-mfc-dlls-overview.md b/docs/build/non-mfc-dlls-overview.md index f77fbcf3057..ff377f90b10 100644 --- a/docs/build/non-mfc-dlls-overview.md +++ b/docs/build/non-mfc-dlls-overview.md @@ -4,6 +4,7 @@ title: "Non-MFC DLLs: Overview" ms.date: "11/04/2016" helpviewer_keywords: ["non-MFC DLLs [C++]", "DLLs [C++], non-MFC"] ms.assetid: 1ed5d1ee-e20c-47d7-801d-87ea26a73842 +ms.topic: concept-article --- # Non-MFC DLLs: Overview diff --git a/docs/build/open-folder-projects-cpp.md b/docs/build/open-folder-projects-cpp.md index 7e49f70c104..006635d28b2 100644 --- a/docs/build/open-folder-projects-cpp.md +++ b/docs/build/open-folder-projects-cpp.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Open Folder support for C++ build systems in Visual Studio" title: "Open Folder support for C++ build systems in Visual Studio" -ms.date: "12/02/2019" +description: "Learn more about: Open Folder support for C++ build systems in Visual Studio" +ms.date: 12/02/2019 helpviewer_keywords: ["Open Folder Projects in Visual Studio"] -ms.assetid: abd1985e-3717-4338-9e80-869db5435175 +ms.topic: how-to --- # Open Folder support for C++ build systems in Visual Studio @@ -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 { @@ -105,7 +105,7 @@ If you add the MinGW-W64 configuration, the JSON looks this this: } ``` -Note the `environments` block. It defines properties that behave like environment variables and are available not only in the *CppProperties.json* file, but also in the other configuration files *task.vs.json* and *launch.vs.json*. The `Mingw64` configuration inherits the `mingw_w64` environment, and uses its `INCLUDE` property to specify the value for `includePath`. You can add other paths to this array property as needed.` +Note the `environments` block. It defines properties that behave like environment variables and are available not only in the *CppProperties.json* file, but also in the other configuration files *task.vs.json* and *launch.vs.json*. The `Mingw64` configuration inherits the `mingw_w64` environment, and uses its `INCLUDE` property to specify the value for `includePath`. You can add other paths to this array property as needed. The `intelliSenseMode` property is set to a value appropriate for GCC. For more information on all these properties, see [CppProperties schema reference](cppproperties-schema-reference.md). @@ -147,7 +147,6 @@ This creates (or opens) the *tasks.vs.json* file in the .vs folder which Visual } ] } - ``` The JSON file is placed in the *.vs* subfolder. To see that folder, click on the **Show All Files** button at the top of **Solution Explorer**. You can run this task by right-clicking on the root node in **Solution Explorer** and choosing **build hello**. When the task completes you should see a new file, *hello.exe* in **Solution Explorer**. @@ -194,7 +193,6 @@ To customize your program's command line arguments and debugging instructions, r } ] } - ``` To start debugging, choose the executable in the debug dropdown, then click the green arrow: diff --git a/docs/build/optimization-best-practices.md b/docs/build/optimization-best-practices.md index ce428f701b4..b0530ca07e9 100644 --- a/docs/build/optimization-best-practices.md +++ b/docs/build/optimization-best-practices.md @@ -4,6 +4,7 @@ title: "Optimization best practices" ms.date: "05/06/2019" helpviewer_keywords: ["C++, optimization", "optimization, best practices"] ms.assetid: f3433148-7255-4ca6-8a4f-7c31aac88508 +ms.topic: best-practice --- # Optimization best practices diff --git a/docs/build/optimizing-your-code.md b/docs/build/optimizing-your-code.md index a30267f3823..590f7b8faec 100644 --- a/docs/build/optimizing-your-code.md +++ b/docs/build/optimizing-your-code.md @@ -3,6 +3,7 @@ description: "Learn more about: Optimizing your code" title: "Optimizing Your Code" ms.date: "05/06/2019" helpviewer_keywords: ["performance, optimizing code", "optimization", "cl.exe compiler, performance", "optimization, C++ code", "code, optimizing", "performance, compiler"] +ms.topic: concept-article --- # Optimizing your code diff --git a/docs/build/overview-of-arm-abi-conventions.md b/docs/build/overview-of-arm-abi-conventions.md index 3e61981e84e..0b80497f7ac 100644 --- a/docs/build/overview-of-arm-abi-conventions.md +++ b/docs/build/overview-of-arm-abi-conventions.md @@ -2,12 +2,14 @@ description: "Learn more about: Overview of ARM32 ABI Conventions" title: "Overview of ARM ABI Conventions" ms.date: "07/11/2018" -ms.assetid: 23f4ae8c-3148-4657-8c47-e933a9f387de --- # Overview of ARM32 ABI Conventions The application binary interface (ABI) for code compiled for Windows on ARM processors is based on the standard ARM EABI. This article highlights key differences between Windows on ARM and the standard. This document covers the ARM32 ABI. For information about the ARM64 ABI, see [Overview of ARM64 ABI conventions](arm64-windows-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). +> [!NOTE] +> Using the Microsoft C++ (MSVC) Build Tools to target ARM32 is deprecated starting with Visual Studio 2026. If you need to target ARM32, use the Visual Studio 2022 v143 build tools. + ## Base Requirements Windows on ARM always presumes that it's running on an ARMv7 architecture. Floating-point support in the form of VFPv3-D32 or later must be present in hardware. The VFP must support both single-precision and double-precision floating-point in hardware. The Windows runtime doesn't support emulation of floating-point to enable running on non-VFP hardware. @@ -124,7 +126,7 @@ Initialization is performed exactly once, before argument processing begins: For each argument in the list, the first matching rule from the following list is applied: -1. If the argument is a composite type whose size cannot be statically determined by both the caller and the callee, the argument is copied to memory and replaced by a pointer to the copy. +1. If the argument is a composite type whose size can't be statically determined by both the caller and the callee, the argument is copied to memory and replaced by a pointer to the copy. 1. If the argument is a byte or 16-bit half-word, then it is zero-extended or sign-extended to a 32-bit full word and treated as a 4-byte argument. @@ -136,11 +138,11 @@ For each argument in the list, the following rules are applied in turn until the 1. If the argument is a VFP type and there are enough consecutive unallocated VFP registers of the appropriate type, then the argument is allocated to the lowest-numbered sequence of such registers. -1. If the argument is a VFP type, all remaining unallocated registers are marked as unavailable. The NSAA is adjusted upwards until it is correctly aligned for the argument type and the argument is copied to the stack at the adjusted NSAA. The NSAA is then incremented by the size of the argument. +1. If the argument is a VFP type, all remaining unallocated registers are marked as unavailable. The NSAA is adjusted upwards until it's correctly aligned for the argument type and the argument is copied to the stack at the adjusted NSAA. The NSAA is then incremented by the size of the argument. 1. If the argument requires 8-byte alignment, the NCRN is rounded up to the next even register number. -1. If the size of the argument in 32-bit words is not more than r4 minus NCRN, the argument is copied into core registers, starting at the NCRN, with the least significant bits occupying the lower-numbered registers. The NCRN is incremented by the number of registers used. +1. If the size of the argument in 32-bit words isn't more than r4 minus NCRN, the argument is copied into core registers, starting at the NCRN, with the least significant bits occupying the lower-numbered registers. The NCRN is incremented by the number of registers used. 1. If the NCRN is less than r4 and the NSAA is equal to the SP, the argument is split between core registers and the stack. The first part of the argument is copied into the core registers, starting at the NCRN, up to and including r3. The rest of the argument is copied onto the stack, starting at the NSAA. The NCRN is set to r4 and the NSAA is incremented by the size of the argument minus the amount passed in registers. @@ -148,7 +150,7 @@ For each argument in the list, the following rules are applied in turn until the 1. The argument is copied into memory at the NSAA. The NSAA is incremented by the size of the argument. -The VFP registers aren't used for variadic functions, and Stage C rules 1 and 2 are ignored. It means that a variadic function can begin with an optional push {r0-r3} to prepend the register arguments to any additional arguments passed by the caller, and then access the entire argument list directly from the stack. +The VFP registers aren't used for variadic functions, and Stage C rules 1 and 2 are ignored. It means that a variadic function can begin with an optional push {r0-r3} to prepend the register arguments to any other arguments passed by the caller, and then access the entire argument list directly from the stack. Integer type values are returned in r0, optionally extended to r1 for 64-bit return values. VFP/NEON floating-point or SIMD type values are returned in s0, d0, or q0, as appropriate. @@ -158,7 +160,7 @@ The stack must always remain 4-byte aligned, and must be 8-byte aligned at any f Functions that have to use a frame pointer—for example, functions that call `alloca` or that change the stack pointer dynamically—must set up the frame pointer in r11 in the function prologue and leave it unchanged until the epilogue. Functions that don't require a frame pointer must perform all stack updates in the prologue and leave the stack pointer unchanged until the epilogue. -Functions that allocate 4 KB or more on the stack must ensure that each page prior to the final page is touched in order. This order ensures that no code can "leap over" the guard pages that Windows uses to expand the stack. Typically, the expansion is done by the `__chkstk` helper, which is passed the total stack allocation in bytes divided by 4 in r4, and which returns the final stack allocation amount in bytes back in r4. +Functions that allocate 4 KB or more on the stack must ensure that each page before the final page is touched in order. This order ensures that no code can "leap over" the guard pages that Windows uses to expand the stack. Typically, the expansion is done by the `__chkstk` helper, which is passed the total stack allocation in bytes divided by 4 in r4, and which returns the final stack allocation amount in bytes back in r4. ### Red zone @@ -194,5 +196,5 @@ The counter is a true cycle counter, not a clock; therefore, the counting freque ## See also -[Common Visual C++ ARM Migration Issues](common-visual-cpp-arm-migration-issues.md)
+[Common Microsoft C++ ARM Migration Issues](common-visual-cpp-arm-migration-issues.md)
[ARM Exception Handling](arm-exception-handling.md) diff --git a/docs/build/profile-guided-optimizations.md b/docs/build/profile-guided-optimizations.md index 4c6cdc579dc..2da31ddff99 100644 --- a/docs/build/profile-guided-optimizations.md +++ b/docs/build/profile-guided-optimizations.md @@ -1,18 +1,20 @@ --- description: "Learn more about: Profile-guided optimizations" title: "Profile-guided optimizations" -ms.date: "04/23/2019" +ms.date: 05/11/2026 helpviewer_keywords: ["profile-guided optimizations", "optimization, profile-guided [C++]"] -ms.assetid: 2225c307-d3ae-42c1-8345-a5a959d132dc --- # Profile-guided optimizations -Profile-guided optimization (PGO) lets you optimize a whole executable file, where the optimizer uses data from test runs of the .exe or .dll file. The data represents the likely performance of the program in a production environment. +Profile-guided optimization (PGO) lets you optimize a whole executable file. The optimizer uses data from test runs of the .exe or .dll file. The data represents the likely performance of the program in a production environment. -Profile-guided optimizations are only available for x86 or x64 native targets. Profile-guided optimizations aren't available for executable files that run on the common language runtime. Even if you produce an assembly with mixed native and managed code (by using the **/clr** compiler option), you can't use profile-guided optimization on just the native code. If you attempt to build a project with these options set in the IDE, a build error results. +> [!NOTE] +> SPGO (Sample Profile-Guided Optimization) is an alternative approach that uses hardware CPU Windows Performance Counters instead of instrumentation. SPGO requires no instrumented build - you profile an existing release binary by using `xperf`. For more information, see [Introducing Sample Profile Guided Optimization in MSVC](https://devblogs.microsoft.com/cppblog/introducing-sample-profile-guided-optimization-in-msvc/) and [Sample Profile-Guided Optimization (SPGO) tutorial](sample-profile-guided-optimization.md). + +Profile-guided optimizations are only available for x86, x64, or ARM64 native targets. Profile-guided optimizations aren't available for executable files that run on the common language runtime. Even if you produce an assembly with mixed native and managed code (by using the **/clr** compiler option), you can't use profile-guided optimization on just the native code. If you attempt to build a project with these options set in the IDE, a build error results. > [!NOTE] -> Information that's gathered from profiling test runs overrides optimizations that would otherwise be in effect if you specify **/Ob**, **/Os**, or **/Ot**. For more information, see [/Ob (Inline Function Expansion)](reference/ob-inline-function-expansion.md) and [/Os, /Ot (Favor Small Code, Favor Fast Code)](reference/os-ot-favor-small-code-favor-fast-code.md). +> Information gathered from profiling test runs overrides optimizations that would otherwise be in effect if you specify **/Ob**, **/Os**, or **/Ot**. For more information, see [/Ob (Inline Function Expansion)](reference/ob-inline-function-expansion.md) and [/Os, /Ot (Favor Small Code, Favor Fast Code)](reference/os-ot-favor-small-code-favor-fast-code.md). ## Steps to optimize your app @@ -20,36 +22,36 @@ To use profile-guided optimization, follow these steps to optimize your app: - Compile one or more source code files with [/GL](reference/gl-whole-program-optimization.md). - Each module built with **/GL** can be examined during profile-guided optimization test runs to capture run-time behavior. Every module in a profile-guided optimization build doesn't have to be compiled with **/GL**. However, only those modules compiled with **/GL** are instrumented and later available for profile-guided optimizations. + The compiler examines each module built with **/GL** during profile-guided optimization test runs to capture run-time behavior. You don't need to compile every module in a profile-guided optimization build with **/GL**. However, only modules compiled with **/GL** are instrumented and later available for profile-guided optimizations. -- Link using [/LTCG](reference/ltcg-link-time-code-generation.md) and [/GENPROFILE or /FASTGENPROFILE](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md). +- Link by using [/LTCG](reference/ltcg-link-time-code-generation.md) and [/GENPROFILE or /FASTGENPROFILE](reference/genprofile-fastgenprofile-generate-profiling-instrumented-build.md). - Using both **/LTCG** and **/GENPROFILE** or **/FASTGENPROFILE** creates a `.pgd` file when the instrumented app is run. After test-run data is added to the `.pgd` file, it can be used as input to the next link step (creating the optimized image). When specifying **/GENPROFILE**, you can optionally add a **PGD=**_filename_ argument to specify a nondefault name or location for the `.pgd` file. The combination of **/LTCG** and **/GENPROFILE** or **/FASTGENPROFILE** linker options replaces the deprecated **/LTCG:PGINSTRUMENT** linker option. + When you use both **/LTCG** and **/GENPROFILE** or **/FASTGENPROFILE**, the instrumented app creates a `.pgd` file when it runs. After test-run data is added to the `.pgd` file, you can use it as input to the next link step (creating the optimized image). When you specify **/GENPROFILE**, you can optionally add a **PGD=**_filename_ argument to specify a nondefault name or location for the `.pgd` file. The combination of **/LTCG** and **/GENPROFILE** or **/FASTGENPROFILE** linker options replaces the deprecated **/LTCG:PGINSTRUMENT** linker option. - Profile the application. - Each time a profiled EXE session ends, or a profiled DLL is unloaded, a `appname!N.pgc` file is created. A `.pgc` file contains information about a particular application test run. *appname* is the name of your app, and *N* is a number starting with 1 that's incremented based on the number of other `appname!N.pgc` files in the directory. You can delete a `.pgc` file if the test run doesn't represent a scenario you want to optimize. + Each time a profiled EXE session ends, or a profiled DLL unloads, the process creates an `appname!N.pgc` file. A `.pgc` file contains information about a particular application test run. *appname* is the name of your app, and *N* is a number starting with 1. It increments based on the number of other `appname!N.pgc` files in the directory. You can delete a `.pgc` file if the test run doesn't represent a scenario you want to optimize. - During a test run, you can force closure of the currently open `.pgc` file and the creation of a new `.pgc` file with the [pgosweep](pgosweep.md) utility (for example, when the end of a test scenario doesn't coincide with application shutdown). + During a test run, you can force closure of the currently open `.pgc` file and the creation of a new `.pgc` file by using the [pgosweep](pgosweep.md) utility (for example, when the end of a test scenario doesn't coincide with application shutdown). Your application can also directly invoke a PGO function, [PgoAutoSweep](pgoautosweep.md), to capture the profile data at the point of the call as a `.pgc` file. It can give you finer control over the code covered by the captured data in your `.pgc` files. For an example of how to use this function, see the [PgoAutoSweep](pgoautosweep.md) documentation. When you create your instrumented build, by default, data collection is done in non-thread-safe mode, which is faster but may be imprecise. By using the **EXACT** argument to **/GENPROFILE** or **/FASTGENPROFILE**, you can specify data collection in thread-safe mode, which is more precise, but slower. This option is also available if you set the deprecated [PogoSafeMode](environment-variables-for-profile-guided-optimizations.md#pogosafemode) environment variable, or the deprecated **/POGOSAFEMODE** linker option, when you create your instrumented build. -- Link using **/LTCG** and **/USEPROFILE**. +- Link by using **/LTCG** and **/USEPROFILE**. - Use both the **/LTCG** and [/USEPROFILE](reference/useprofile.md) linker options to create the optimized image. This step takes as input the `.pgd` file. When you specify **/USEPROFILE**, you can optionally add a **PGD=**_filename_ argument to specify a non-default name or location for the `.pgd` file. You can also specify this name by using the deprecated **/PGD** linker option. The combination of **/LTCG** and **/USEPROFILE** replaces the deprecated **/LTCG:PGOPTIMIZE** and **/LTCG:PGUPDATE** linker options. + Use both the **/LTCG** and [/USEPROFILE](reference/useprofile.md) linker options to create the optimized image. This step takes the `.pgd` file as input. When you specify **/USEPROFILE**, you can optionally add a **PGD=**_filename_ argument to specify a nondefault name or location for the `.pgd` file. You can also specify this name by using the deprecated **/PGD** linker option. The combination of **/LTCG** and **/USEPROFILE** linker options replaces the deprecated **/LTCG:PGOPTIMIZE** and **/LTCG:PGUPDATE** linker options. -It's even possible to create the optimized executable file and later determine that additional profiling would be useful to create a more optimized image. If the instrumented image and its `.pgd` file are available, you can do additional test runs and rebuild the optimized image with the newer `.pgd` file, by using the same **/LTCG** and **/USEPROFILE** linker options. +It's even possible to create the optimized executable file and later determine that more profiling would be useful to create a more optimized image. If the instrumented image and its `.pgd` file are available, you can do more test runs and rebuild the optimized image with the newer `.pgd` file by using the same **/LTCG** and **/USEPROFILE** linker options. > [!NOTE] -> Both `.pgc` and `.pgd` files are binary file types. If stored in a source control system, avoid any automatic transformation that may be made to text files. +> Both `.pgc` and `.pgd` files are binary file types. If you store them in a source control system, avoid any automatic transformation that might be made to text files. ## Optimizations performed by PGO -The profile-guided optimizations include these checks and improvements: +Profile-guided optimizations include these checks and improvements: -- **Inlining** - For example, if a function A frequently calls function B, and function B is relatively small, then profile-guided optimizations inline function B in function A. +- **Inlining** - For example, if function A frequently calls function B, and function B is relatively small, the profile-guided optimizations inline function B in function A. - **Virtual Call Speculation** - If a virtual call, or other call through a function pointer, frequently targets a certain function, a profile-guided optimization can insert a conditionally executed direct call to the frequently targeted function, and the direct call can be inlined. @@ -61,33 +63,36 @@ The profile-guided optimizations include these checks and improvements: - **Function Layout** - Based on the call graph and profiled caller/callee behavior, functions that tend to be along the same execution path are placed in the same section. -- **Conditional Branch Optimization** - With the value probes, profile-guided optimizations can find if a given value in a switch statement is used more often than other values. This value can then be pulled out of the switch statement. The same can be done with **`if`**...**`else`** instructions where the optimizer can order the **`if`**...**`else`** so that either the **`if`** or **`else`** block is placed first, depending on which block is more frequently true. +- **Conditional Branch Optimization** - With the value probes, profile-guided optimizations can find if a given value in a switch statement is used more often than other values. This value can then be pulled out of the switch statement. The same optimization can be done with **`if`**...**`else`** instructions where the optimizer can order the **`if`**...**`else`** so that either the **`if`** or **`else`** block is placed first, depending on which block is more frequently true. -- **Dead Code Separation** - Code that isn't called during profiling is moved to a special section that's appended to the end of the set of sections. It effectively keeps this section out of the often-used pages. +- **Dead Code Separation** - Profile-guided optimization moves code that isn't called during profiling to a special section at the end of the section set. It effectively keeps this section out of the often-used pages. -- **EH Code Separation** - Because EH code is only exceptionally executed, it can often be moved to a separate section. It's moved when profile-guided optimizations can determine that the exceptions occur only on exceptional conditions. +- **EH Code Separation** - Because EH code is only exceptionally executed, it can often be moved to a separate section. Profile-guided optimizations move it when they determine that the exceptions occur only on exceptional conditions. -- **Memory Intrinsics** - Whether to expand an intrinsic or not depends on whether it's called frequently. An intrinsic can also be optimized based on the block size of moves or copies. +- **Memory Intrinsics** - Whether to expand an intrinsic or not depends on whether it gets called frequently. An intrinsic can also be optimized based on the block size of moves or copies. ## Next steps -Read more about these environment variables, functions, and tools you can use in profile-guided optimizations: +To learn more about these environment variables, functions, and tools you can use in profile-guided optimizations, see the following resources: -[Environment variables for profile-guided optimizations](environment-variables-for-profile-guided-optimizations.md)
-These variables were used to specify run-time behavior of testing scenarios. They're now deprecated and replaced by new linker options. This document shows you how to move from the environment variables to the linker options. +[Environment variables for profile-guided optimizations](environment-variables-for-profile-guided-optimizations.md)\ +These variables specify the run-time behavior of testing scenarios. They're now deprecated and replaced by new linker options. This document shows you how to move from the environment variables to the linker options. -[PgoAutoSweep](pgoautosweep.md)
+[PgoAutoSweep](pgoautosweep.md)\ A function you can add to your app to provide fine-grained `.pgc` file data capture control. -[pgosweep](pgosweep.md)
+[pgosweep](pgosweep.md)\ A command-line utility that writes all profile data to the `.pgc` file, closes the `.pgc` file, and opens a new `.pgc` file. -[pgomgr](pgomgr.md)
+[pgomgr](pgomgr.md)\ A command-line utility that adds profile data from one or more `.pgc` files to the `.pgd` file. -[How to: Merge multiple PGO profiles into a single profile](how-to-merge-multiple-pgo-profiles-into-a-single-profile.md)
+[How to: Merge multiple PGO profiles into a single profile](how-to-merge-multiple-pgo-profiles-into-a-single-profile.md)\ Examples of **pgomgr** usage. +[Sample Profile-Guided Optimization (SPGO) tutorial](sample-profile-guided-optimization.md)\ +Use CPU hardware performance counters instead of instrumentation. No instrumented build required - profile your existing release binary with `xperf`. + ## See also [Additional MSVC build tools](reference/c-cpp-build-tools.md) diff --git a/docs/build/project-property-inheritance.md b/docs/build/project-property-inheritance.md index cccf6e6fbe4..3456a292903 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/projects-and-build-systems-cpp.md b/docs/build/projects-and-build-systems-cpp.md index 156cd4acfd8..0e429325991 100644 --- a/docs/build/projects-and-build-systems-cpp.md +++ b/docs/build/projects-and-build-systems-cpp.md @@ -1,37 +1,36 @@ --- title: "C/C++ projects and build systems in Visual Studio" description: "Use Visual Studio to compile and build C++ projects for Windows, ARM, or Linux based on any project system." -ms.date: "07/17/2019" -helpviewer_keywords: ["builds [C++]", "C++ projects, building", "projects [C++], building", "builds [C++], options", "C++, build options"] -ms.assetid: fa6ed4ff-334a-4d99-b5e2-a1f83d2b3008 +ms.date: 07/17/2019 ms.topic: "overview" ms.custom: intro-overview +helpviewer_keywords: ["builds [C++]", "C++ projects, building", "projects [C++], building", "builds [C++], options", "C++, build options"] --- # C/C++ projects and build systems in Visual Studio -You can use Visual Studio to edit, compile, and build any C++ code base with full IntelliSense support without having to convert that code into a Visual Studio project or compile with the MSVC toolset. For example, you can edit a cross-platform CMake project in Visual Studio on a Windows machine, then compile it for Linux using g++ on a remote Linux machine. +You can use Visual Studio to edit, compile, and build any C++ code base with full IntelliSense support without having to convert that code into a Visual Studio project or compile with the Microsoft C++ (MSVC) Build Tools. For example, you can edit a cross-platform CMake project in Visual Studio on a Windows machine, then compile it for Linux using g++ on a remote Linux machine. ## C++ compilation -To *build* a C++ program means to compile source code from one or more files and then link those files into an executable file (.exe), a dynamic-load library (.dll) or a static library (.lib). +To *build* a C++ program means to compile source code from one or more files and then link those files into an executable file (`.exe`), a dynamic-link library (`.dll`) or a static library (`.lib`). Basic C++ compilation involves three main steps: - The C++ preprocessor transforms all the #directives and macro definitions in each source file. This creates a *translation unit*. -- The C++ compiler compiles each translation unit into object files (.obj), applying whatever compiler options have been set. +- The C++ compiler compiles each translation unit into object files (`.obj`), applying whatever compiler options have been set. - The *linker* merges the object files into a single executable, applying the linker options that have been set. -## The MSVC toolset +## The Microsoft C++ (MSVC) Build Tools -The Microsoft C++ compiler, linker, standard libraries, and related utilities make up the MSVC compiler toolset (also called a toolchain or "build tools"). These are included in Visual Studio. You can also download and use the command-line toolset as a free standalone package. For more information, see [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) on the Visual Studio Downloads page. +The Microsoft C++ compiler, linker, standard libraries, and related utilities make up the Microsoft C++ (MSVC) Build Tools (also called a toolchain or toolset). These are included in Visual Studio. You can also download and use the command-line toolset as a free standalone package. For more information, see [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) on the Visual Studio Downloads page. -You can build simple programs by invoking the MSVC compiler (cl.exe) directly from the command line. The following command accepts a single source code file, and invokes cl.exe to build an executable called *hello.exe*: +You can build simple programs by invoking the MSVC compiler (`cl.exe`) directly from the command line. The following command accepts a single source code file, and invokes `cl.exe` to build an executable called *`hello.exe`*: ```cmd cl /EHsc hello.cpp ``` -Here the compiler (cl.exe) automatically invokes the C++ preprocessor and the linker to produce the final output file. For more information, see [Building on the command line](building-on-the-command-line.md). +Here the compiler (`cl.exe`) automatically invokes the C++ preprocessor and the linker to produce the final output file. For more information, see [Building on the command line](building-on-the-command-line.md). ## Build systems and projects @@ -39,19 +38,19 @@ Most real-world programs use some kind of *build system* to manage complexities The following list shows various options for Visual Studio Projects - C++: -- create a Visual Studio project by using the Visual Studio IDE and configure it by using property pages. Visual Studio projects produce programs that run on Windows. For an overview, see [Compiling and Building](/visualstudio/ide/compiling-and-building-in-visual-studio) in the Visual Studio documentation. +- Create a Visual Studio project by using the Visual Studio IDE and configure it by using property pages. Visual Studio projects produce programs that run on Windows. For an overview, see [Compiling and Building](/visualstudio/ide/compiling-and-building-in-visual-studio) in the Visual Studio documentation. -- open a folder that contains a CMakeLists.txt file. CMake support is integrated into Visual Studio. You can use the IDE to edit, test, and debug without modifying the CMake files in any way. This enables you to work in the same CMake project as others who might be using different editors. CMake is the recommended approach for cross-platform development. For more information, see [CMake projects](cmake-projects-in-visual-studio.md). +- Open a folder that contains a `CMakeLists.txt` file. CMake support is integrated into Visual Studio. You can use the IDE to edit, test, and debug without modifying the CMake files in any way. This enables you to work in the same CMake project as others who might be using different editors. CMake is the recommended approach for cross-platform development. For more information, see [CMake projects](cmake-projects-in-visual-studio.md). -- open a loose folder of source files with no project file. Visual Studio will use heuristics to build the files. This is an easy way to compile and run small console applications. For more information, see [Open Folder projects](open-folder-projects-cpp.md). +- Open a loose folder of source files with no project file. Visual Studio will use heuristics to build the files. This is an easy way to compile and run small console applications. For more information, see [Open Folder projects](open-folder-projects-cpp.md). -- open a folder that contains a makefile, or any other build system configuration file. You can configure Visual Studio to invoke any arbitrary build commands by adding JSON files to the folder. For more information, see [Open Folder projects](open-folder-projects-cpp.md). +- Open a folder that contains a makefile, or any other build system configuration file. You can configure Visual Studio to invoke any arbitrary build commands by adding JSON files to the folder. For more information, see [Open Folder projects](open-folder-projects-cpp.md). - Open a Windows makefile in Visual Studio. For more information, see [NMAKE Reference](reference/nmake-reference.md). ## MSBuild from the command line -You can invoke MSBuild from the command line by passing it a .vcxproj file along with command-line options. This approach requires a good understanding of MSBuild, and is recommended only when necessary. For more information, see [MSBuild](msbuild-visual-cpp.md). +You can invoke MSBuild from the command line by passing it a `.vcxproj` file along with command-line options. This approach requires a good understanding of MSBuild, and is recommended only when necessary. For more information, see [MSBuild](msbuild-visual-cpp.md). ## In This Section @@ -74,7 +73,7 @@ Discusses how to use the C/C++ compiler and build tools directly from the comman How to create, debug, and deploy C/C++ DLLs (shared libraries) in Visual Studio. [Walkthrough: Creating and Using a Static Library](walkthrough-creating-and-using-a-static-library-cpp.md)\ -How to create a **.lib** binary file. +How to create a `.lib` binary file. [Building C/C++ Isolated Applications and Side-by-side Assemblies](building-c-cpp-isolated-applications-and-side-by-side-assemblies.md)\ Describes the deployment model for Windows Desktop applications, based on the idea of isolated applications and side-by-side assemblies. @@ -83,10 +82,10 @@ Describes the deployment model for Windows Desktop applications, based on the id How to target 64-bit x64 hardware with the MSVC build tools. [Configure C++ projects for ARM processors](configuring-programs-for-arm-processors-visual-cpp.md)\ -How to use the MSVC build tools to target ARM hardware. +How to use the MSVC Build Tools to target ARM hardware. [Optimizing Your Code](optimizing-your-code.md)\ -How to optimize your code in various ways including program guided optimizations. +How to optimize your code in various ways including profile-guided optimization (PGO). [Configuring Programs for Windows XP](configuring-programs-for-windows-xp.md)\ How to target Windows XP with the MSVC build tools. diff --git a/docs/build/prolog-and-epilog.md b/docs/build/prolog-and-epilog.md index eb6f1ad9723..56b27b056b1 100644 --- a/docs/build/prolog-and-epilog.md +++ b/docs/build/prolog-and-epilog.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: x64 prolog and epilog" title: "x64 prolog and epilog" -ms.date: "12/17/2018" -ms.assetid: 0453ed1a-3ff1-4bee-9cc2-d6d3d6384984 +description: "Learn more about: x64 prolog and epilog" +ms.date: 12/17/2018 --- # x64 prolog and epilog diff --git a/docs/build/reference/advanced-property-page.md b/docs/build/reference/advanced-property-page.md index 10eb28b56e4..f119173610e 100644 --- a/docs/build/reference/advanced-property-page.md +++ b/docs/build/reference/advanced-property-page.md @@ -1,9 +1,10 @@ --- description: "Use the Advanced property page in Visual Studio 2019 to set various properties for C++ projects." title: "Advanced Property Page (Project)" -ms.date: 11/22/2021 +ms.date: 08/31/2022 f1_keywords: ["VC.Project.VCConfiguration.TargetExt", "VC.Project.VCConfiguration.DeleteExtensionsOnClean", "VC.Project.VCConfiguration.BuildLogFile", "VC.Project.VCConfiguration.PreferredToolArchitecture", "VC.Project.VCConfiguration.UseDebugLibraries", "VC.Project.VCConfiguration.EnableUnitySupport", "VC.Project.VCConfiguration.CopyLocalDeploymentContent", "VC.Project.VCConfiguration.CopyLocalProjectReference", "VC.Project.VCConfiguration.CopyLocalDebugSymbols", "VC.Project.VCConfiguration.CopyCppRuntimeToOutputDir", "VC.Project.VCConfiguration.useOfMfc", "VC.Project.VCConfiguration.CharacterSet", "VC.Project.VCConfiguration.WholeProgramOptimization", "VC.Project.VCConfiguration.VCToolsVersion", "VC.Project.VCConfiguration.LLVMToolsVersion", "VC.Project.VCConfiguration.ManagedExtensions", "VC.Project.TargetFrameworkVersion", "VC.Project.VCConfiguration.EnableManagedIncrementalBuild", "VC.Project.VCConfiguration.ManagedAssembly"] --- + # Advanced Property Page ::: moniker range="<=msvc-150" @@ -50,7 +51,7 @@ Specifies whether to use the x86 or x64 build tools. ### Use Debug Libraries -Specifies whether to create a Debug or Release build. +Specifies whether to create a Debug or Release build. Despite the name, **Use Debug Libraries** is a build system-specific property that is effectively shorthand for "Make a Debug build" or "Make a Release build". It sets several compiler and linker properties for Debug or Release builds, including the library settings. You can use it to create Debug or Release configurations for a new platform or in a new template. We don't recommend you change this property in an existing configuration. Use the individual compiler and linker properties instead. ### Enable Unity (JUMBO) build @@ -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`** or **`/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 -The `_M_ARM64` macro is defined by default when compiling for an ARM64 target. For more information, see [Predefined Macros](../../preprocessor/predefined-macros.md). +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. -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 `_M_ARM64` macro is defined by default when compiling for an ARM64 target. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). + +The `__ARM_ARCH` macro is defined for `/arch:ARMv8.0` and higher. It indicates the ARM architecture extension level that the compiler is targeting. For more information, see [Predefined macros](../../preprocessor/predefined-macros.md). + +```cpp +#if __ARM_ARCH >= 802 + // code that requires ARMv8.2... +#endif +``` + +**`/arch`** only affects code generation for native functions. When you use [`/clr`](clr-common-language-runtime-compilation.md) to compile, **`/arch`** has no effect on code generation for managed functions. ### To set the `/arch` compiler option in Visual Studio @@ -28,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 *`/arch:armv8.8`*. 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 6c944400a66..da9e57733f8 100644 --- a/docs/build/reference/arch-x64.md +++ b/docs/build/reference/arch-x64.md @@ -1,31 +1,44 @@ --- description: "Learn more about: /arch (x64)" title: "/arch (x64)" -ms.date: 06/30/2022 -ms.assetid: ecda22bf-5bed-43f4-99fb-88aedd83d9d8 +ms.date: 10/21/2025 +f1_keywords: ["/arch:SSE2", "/arch:SSE4.2", "/arch:AVX", "/arch:AVX2", "/arch:AVX512", "/arch:AVX10.1", "/arch:AVX10.2"] +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:AVX10.2 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`**|**`AVX10.2`**] ## 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. + +**`/arch:AVX10.2`**\ +Enables Intel Advanced Vector Extensions 10 version 2. ## 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 +46,36 @@ 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. This option was introduced in Visual Studio 2022 17.13. + +- **`AVX10.2`** expands the instruction set introduced in `AVX10.1`. The default vector length for **`AVX10.2`** is 256 bits and can be increased to 512 bits using the [`/vlen`](vlen.md) flag. +`AVX10.2` adds instructions that are enhancements of legacy instructions and media acceleration instructions. For more information about the new instructions, see section 3.1.4 in the [Intel Advanced Vector Extensions 10.2 Architecture Specification](https://www.intel.com/content/www/us/en/content-details/856721/intel-advanced-vector-extensions-10-2-intel-avx10-2-architecture-specification.html). The AI related instructions in that document are supported via MSVC intrinsics instead of being directly emitted because MSVC doesn't support their data types. This compiler option was introduced in Visual Studio 2026. -Each **`/arch`** option may also enable the use of other non-vector instructions that are associated with that option. An example is the use of certain BMI instructions when **`/arch:AVX2`** is specified. +Each **`/arch`** option may also enable the use of other nonvector 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`**, **`/arch:AVX10.1`**, or **`/arch:AVX10.2`** compiler option is specified. +The `__AVX2__` preprocessor symbol is defined when the **`/arch:AVX2`**, **`/arch:AVX512`**, **`/arch:AVX10.1`**, or **`/arch:AVX10.2`** compiler option is specified. +The `__AVX512F__`, `__AVX512CD__`, `__AVX512BW__`, `__AVX512DQ__`, and `__AVX512VL__` preprocessor symbols are defined when the **`/arch:AVX512`**, **`/arch:AVX10.1`**, or **`/arch:AVX10.2`** compiler option is specified. +The `__AVX10_VER__` preprocessor symbol is defined when the **`/arch:AVX10.1`** or **`/arch:AVX10.2`** 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. Support for **`/arch:AVX10.2`** was added in Visual Studio 2026. -### 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 @@ -58,5 +84,6 @@ The `__AVX__` preprocessor symbol is defined when the **`/arch:AVX`**, **`/arch: ## See also [`/arch` (Minimum CPU Architecture)](arch-minimum-cpu-architecture.md)\ +[`/feature` (x64)](feature-x64.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/arch-x86.md b/docs/build/reference/arch-x86.md index 1c5ae3c178f..a133eda92db 100644 --- a/docs/build/reference/arch-x86.md +++ b/docs/build/reference/arch-x86.md @@ -1,15 +1,17 @@ --- description: "Learn more about: /arch (x86)" title: "/arch (x86)" -ms.date: 06/30/2022 +ms.date: 10/21/2025 +f1_keywords: ["/arch:IA32", "/arch:SSE", "/arch:SSE2", "/arch:AVX", "/arch:AVX2", "/arch:AVX512", "/arch:AVX10.1", /arch:AVX10.2"] +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:AVX10.2 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`**|**`AVX10.2`**] ## Arguments @@ -17,23 +19,29 @@ 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. + +**`/arch:AVX10.2`**\ +Enables Intel Advanced Vector Extensions 10 version 2. ## 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,11 +57,16 @@ 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. This option was introduced in Visual Studio 2022 17.13. + +- **`AVX10.2`** expands the instruction set introduced in `AVX10.1`. The default vector length for **`AVX10.2`** is 256 bits and can be increased to 512 bits using the [`/vlen`](vlen.md) flag. +`AVX10.2` adds instructions that are enhancements of legacy instructions and media acceleration instructions. For more information about the new instructions, see section 3.1.4 in the [Intel Advanced Vector Extensions 10.2 Architecture Specification](https://www.intel.com/content/www/us/en/content-details/856721/intel-advanced-vector-extensions-10-2-intel-avx10-2-architecture-specification.html) The AI related instructions in that document are supported via MSVC intrinsics instead of being directly emitted because MSVC doesn't support their data types. This compiler option was introduced in Visual Studio 2026. -The optimizer chooses when and how to use vector instructions depending on which **`/arch`** is specified. Scalar floating-point computations are performed with SSE or AVX instructions when available. Some calling conventions specify passing floating-point arguments on the x87 stack, and as a result, your code may use a mixture of both x87 and SSE/AVX instructions for floating-point computations. Integer vector instructions can also be used for some 64-bit integer operations when available. +The optimizer chooses when and how to use vector instructions depending on which **`/arch`** is specified. Scalar floating-point computations are usually performed with SSE or AVX instructions when available. Some calling conventions specify passing floating-point arguments on the x87 stack, and as a result, your code may use a mixture of both x87 and SSE/AVX instructions for floating-point computations. Integer vector instructions can also be used for some 64-bit integer operations when available. -In addition to the vector and floating-point scalar instructions, each **`/arch`** option may also enable the use of other non-vector instructions that are associated with that option. An example is the CMOVcc instruction family that first appeared on the Intel Pentium Pro processors. Because SSE instructions were introduced with the subsequent Intel Pentium III processor, CMOVcc instructions may be generated except when **`/arch:IA32`** is specified. +In addition to the vector and floating-point scalar instructions, each **`/arch`** option may also enable the use of other nonvector instructions that are associated with that option. An example is the CMOVcc instruction family that first appeared on the Intel Pentium Pro processors. Because SSE instructions were introduced with the subsequent Intel Pentium III processor, CMOVcc instructions may be generated except when **`/arch:IA32`** is specified. Floating-point operations are normally rounded to double-precision (64-bit) in x87 code, but you can use `_controlfp` to modify the FP control word, including setting the precision control to extended precision (80-bit) or single-precision (32-bit). For more information, see [`_control87`, `_controlfp`, `__control87_2`](../../c-runtime-library/reference/control87-controlfp-control87-2.md). SSE and AVX have separate single-precision and double-precision instructions for each operation, so there's no equivalent for SSE/AVX code. It can change how results are rounded when the result of a floating-point operation is used directly in further calculation instead of assigning it to a user variable. Consider the following operations: @@ -69,7 +82,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 +94,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 00000000000..28fabf8505d --- /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/atl-program-or-control-source-and-header-files.md b/docs/build/reference/atl-program-or-control-source-and-header-files.md index 827a02bd71c..5057444504e 100644 --- a/docs/build/reference/atl-program-or-control-source-and-header-files.md +++ b/docs/build/reference/atl-program-or-control-source-and-header-files.md @@ -1,26 +1,60 @@ --- -description: "Learn more about: ATL Program or Control Source and Header Files" -title: "ATL Program or Control Source and Header Files" -ms.date: "11/04/2016" +description: "Learn more about: ATL program or control source and header files" +title: "ATL program or control source and header files" +ms.date: 09/27/2022 helpviewer_keywords: ["file types [C++], ATL source and headers"] ms.assetid: cb65372f-4880-4007-b582-a52eaa568fd1 --- -# ATL Program or Control Source and Header Files +# ATL program or control source and header files -The following files are created when you create an ATL project in Visual Studio, depending on the options you select for the project you create. +The following files are created when you create an ATL project in Visual Studio, depending on the options you select for the project you create. The file names depend on the name you choose for your project, which we'll call *`ProjectName`*. -All of these files are located in the *Projname* directory, and in either the Header Files (.h files) folder or Source Files (.cpp files) folder in Solution Explorer. +All of the files created by the project template are located in the *`ProjectName`* and *`ProjectNamePS`* project directories. In Solution Explorer, the *`ProjectName`* files are located in the **Generated Files**, **Header Files**, **Resource Files**, and **Source Files** folders. The *`ProjectNamePS`* files are in the **Generated Files** and **Source Files** folders. Not all files listed here are generated for every project type. Files in the **Generated Files** folder are generated automatically by the MIDL compiler; they shouldn't be edited directly. -|File name|Description| -|---------------|-----------------| -|*Projname*.h|The main include file containing the C++ interface definitions and GUID declarations of the items defined in ATLSample.idl. It is regenerated by MIDL during compilation.| -|*Projname*.cpp|The main program source file. It contains the implementation of your DLL's exports for an in-process server and the implementation of `WinMain` for a local server. For a service, this additionally implements all the service management functions.| -|Resource.h|The header file for the resource file.| -|StdAfx.cpp|Includes the files StdAfx.h and Atlimpl.cpp.| -|StdAfx.h|Includes the ATL header files.| +::: moniker range=">=msvc-150" + +| File name | Description | +|--|--| +| *`ProjectName_i.c`* | The generated source file containing the C++ IID and CLSID definitions and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Link this file with the server and any clients. | +| *`ProjectName_i.h`* | The generated include file containing the C++ interface declarations and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Include this file in source files for the server and any clients. | +| *`ProjectName.rc`* | The main program resource file. | +| *`ProjectName.rgs`* | The main program registration file. | +| *`ProjectName.cpp`* | The main program source file. In DLL projects, it contains the implementation of your DLL's exports for an in-process server. In EXE projects, it contains the implementation of `WinMain` for a local server. For a service, this file implements all the service management functions. | +| *`ProjectName.def`* | In DLL projects, the definitions for your DLL's exports. | +| *`ProjectName.idl`* | The IDL source for your project. The MIDL tool processes this file to produce the type library (*`.tlb`*) and marshaling code. | +| *`framework.h`* | Sets preprocessor macros and includes the ATL header files, the *`targetver.h`* version support header, and the *`Resource.h`* resource file header. | +| *`dllmain.h`* | In DLL projects, the header file for the module class. | +| *`dllmain.cpp`* | In DLL projects, the source file for the `DllMain` function. | +| *`Resource.h`* | The header file for the resource file. | +| *`targetver.h`* | Includes *`SDKDDKVer.h`*. To build your application for a previous Windows platform, include *`WinSDKVer.h`* and set the `_WIN32_WINNT` macro to the platform you wish to support before including *`SDKDDKVer.h`*. | +| *`pch.cpp`* | Includes the file *`pch.h`*. | +| *`pch.h`* | Includes the *`framework.h`* header file. | + +::: moniker-end + +::: moniker range="msvc-140" + +| File name | Description | +|--|--| +| *`ProjectName_i.c`* | The generated source file containing the C++ IID and CLSID definitions and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Link this file with the server and any clients. | +| *`ProjectName_i.h`* | The generated include file containing the C++ interface declarations and GUID declarations of the items defined in *`ProjectName.idl`*. Don't edit this file; it's regenerated by MIDL during compilation. Include this file in source files for the server and any clients. | +| *`ProjectName.rc`* | The main program resource file. | +| *`ProjectName.rgs`* | The main program registration file. | +| *`ProjectName.cpp`* | The main program source file. In DLL projects, it contains the implementation of your DLL's exports for an in-process server. In EXE projects, it contains the implementation of `WinMain` for a local server. For a service, this file implements all the service management functions. | +| *`ProjectName.def`* | In DLL projects, the definitions for your DLL's exports. | +| *`ProjectName.idl`* | The IDL source for your project. The MIDL tool processes this file to produce the type library (*`.tlb`*) and marshaling code. | +| *`dllmain.h`* | In DLL projects, the header file for the module class. | +| *`dllmain.cpp`* | In DLL projects, the source file for the `DllMain` function. | +| *`resource.h`* | The header file for the resource file. | +| *`targetver.h`* | Includes *`SDKDDKVer.h`*. To build your application for a previous Windows platform, include *`WinSDKVer.h`* and set the `_WIN32_WINNT` macro to the platform you wish to support before including *`SDKDDKVer.h`*. | +| *`stdafx.cpp`* | Includes the file *`stdafx.h`*. | +| *`stdafx.h`* | Sets preprocessor macros and includes the ATL header files, the *`targetver.h`* version support header, and the *`resource.h`* resource file header. | + +::: moniker-end ## See also -[File Types Created for Visual Studio C++ projects](file-types-created-for-visual-cpp-projects.md)
-[MFC Program or Control Source and Header Files](mfc-program-or-control-source-and-header-files.md)
-[CLR Projects](files-created-for-clr-projects.md) +[File types created for Visual Studio C++ projects](file-types-created-for-visual-cpp-projects.md)\ +[MFC program or control source and header files](mfc-program-or-control-source-and-header-files.md)\ +[Add ATL support to an existing MFC executable or DLL](../../mfc/reference/adding-atl-support-to-your-mfc-project.md)\ +[CLR projects](files-created-for-clr-projects.md) diff --git a/docs/build/reference/await-enable-coroutine-support.md b/docs/build/reference/await-enable-coroutine-support.md index 9595a434ffc..6ce254876f8 100644 --- a/docs/build/reference/await-enable-coroutine-support.md +++ b/docs/build/reference/await-enable-coroutine-support.md @@ -1,15 +1,17 @@ --- description: "Learn more about: /await (Enable coroutine support)" title: "/await (Enable coroutine support)" -ms.date: "08/15/2017" +ms.date: 09/08/2025 f1_keywords: ["/await", "-await"] helpviewer_keywords: ["/await enable coroutine support [C++]", "-await enable coroutine support [C++]", "await enable coroutine support [C++]"] -ms.assetid: 302c8e69-09b6-4c58-bcdd-0a6a8713a8df --- -# `/await` (Enable coroutine support) +# `/await` (Enable coroutine support) Deprecated. Use the **`/await`** compiler option to enable compiler support for coroutines. +> [!NOTE] +> The **`/await`** option is deprecated starting with Visual Studio 2026 and will be removed in a future release. Standard C++ coroutines are available by default in C++20 or later. Or use **`/await:strict`** option when using earlier versions of the C++ language. + ## Syntax > **`/await`**\ @@ -19,7 +21,7 @@ Use the **`/await`** compiler option to enable compiler support for coroutines. The **`/await`** compiler option enables compiler support for C++ coroutines and the keywords **`co_await`**, **`co_yield`**, and **`co_return`**. This option is off by default. For information about support for coroutines in Visual Studio, see the [Visual Studio Team Blog](https://devblogs.microsoft.com/cppblog/category/coroutine/). For more information about the coroutines standard proposal, see [N4628 Working Draft, Technical Specification for C++ Extensions for Coroutines](https://wg21.link/n4628). -The **`/await`** option is available beginning in Visual Studio 2015. +The **`/await`** option is available beginning in Visual Studio 2015 and is deprecated starting with Visual Studio 2026. Starting in Visual Studio 2019 version 16.10, the **`/await:strict`** option can be used in place of **`/await`**. The option provides C++20-compatible coroutine support in projects that build in C++14 or C++17 mode. In **`/await:strict`** mode, library support is provided in \ and in the `std` namespace. diff --git a/docs/build/reference/base-base-address.md b/docs/build/reference/base-base-address.md index a78fb4117b3..1728032bacc 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 4a881375b4b..e1d07952322 100644 --- a/docs/build/reference/c-compile-without-linking.md +++ b/docs/build/reference/c-compile-without-linking.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /c (Compile Without Linking)" title: "/c (Compile Without Linking)" -ms.date: "11/04/2016" +description: "Learn more about: /c (Compile Without Linking)" +ms.date: 11/04/2016 f1_keywords: ["/c"] helpviewer_keywords: ["suppress link", "cl.exe compiler, compiling without linking", "-c compiler option [C++]", "c compiler option [C++]", "/c compiler option [C++]"] -ms.assetid: 8017fc3d-e5dd-4668-a1f7-3120daa95d20 --- # /c (Compile Without Linking) @@ -34,14 +33,14 @@ Any internal project created in the development environment uses the **/c** opti The following command line creates the object files FIRST.obj and SECOND.obj. THIRD.obj is ignored. -``` +```cmd 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 +```cmd +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 16d52595785..dce5341a0ff 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: 06/30/2022 +ms.date: 3/26/2026 ms.topic: "article" f1_keywords: ["VC.Project.VCCLCompilerTool.AdditionalModuleDirectories", "VC.Project.VCCLCompilerTool.ScanSourceForModuleDependencies"] -ms.assetid: 16375038-4917-4bd0-9a2a-26343c1708b7 --- # C/C++ Property Pages @@ -36,7 +35,7 @@ Specifies one or more header units to use to resolve names passed to an `import` When set to **Yes**, the compiler scans all C++ sources, not just module interface and header unit sources, for module and header units dependencies. The build system builds the full dependencies graph, which ensures that all imported modules and header units are built before compiling the files that depend on them. When combined with **Translate Includes to Imports**, any header file that's specified in a [`header-units.json`](header-unit-json-reference.md) file in the same directory as the header file is compiled into a header unit. -Files that have the extension *`.ixx`*, and files that have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/export)**, are always scanned. +Files that have the extension *`.ixx`*, and files that have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/exportHeader)**, are always scanned. ### Translate Includes to Imports @@ -48,15 +47,19 @@ Specifies the type of debugging information generated by the compiler. This pro #### Choices -- **None** - Produces no debugging information, so compilation may be faster. -- **C7 compatible** - Select the type of debugging information created for your program and whether this information is kept in object (.obj) files or in a program database (PDB). -- **Program Database** - Produces a program database (PDB) that contains type information and symbolic debugging information for use with the debugger. The symbolic debugging information includes the names and types of variables and functions, and line numbers. -- **Program Database for Edit And Continue** - Produces a program database, as described above, in a format that supports the [Edit and Continue](/visualstudio/debugger/edit-and-continue) feature. +- **None** (`None`) - Produces no debugging information, so compilation may be faster. +- **C7 compatible** (`OldStyle`) - Produces object files that contain full symbolic debugging information. No PDB file is produced. +- **Program Database** (`ProgramDatabase`) - 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** (`EditAndContinue`) - 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 Adds supporting code for enabling [Just My Code](/visualstudio/debugger/just-my-code) debugging in this compilation unit. Sets [`/JMC`](jmc.md). +### Support C++ Dynamic Debugging + +(Preview) Sets compiler flag [`/dynamicdeopt`](dynamic-deopt.md) to turn on [C++ Dynamic Debugging](/visualstudio/debugger/cpp-dynamic-debugging). Place deoptimized breakpoints and step in anywhere with on-demand function deoptimization. Use this mode for debugging optimized code. + ### Common Language RunTime Support Use the .NET runtime service. This switch is incompatible with some other switches; see the documentation on the [`/clr`](clr-common-language-runtime-compilation.md) family of switches for details. @@ -119,6 +122,10 @@ Enable multi-processor compilation. Sets the [`/MP`](mp-build-with-multiple-proc Compiles and links the program with AddressSanitizer instrumentation. This property currently supports x86 and x64 target builds. Sets the [`/fsanitize`](fsanitize.md) compiler option. +### Enable Fuzzer Support (Experimental) + +Compiles programs with the Fuzzer. Enable AddressSanitizer for best results. Currently available for x86 and x64 builds. Sets [`/fsanitize=fuzzer`](fsanitize.md). + ## C/C++ Optimization Properties ### Optimization @@ -142,7 +149,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 @@ -200,6 +207,10 @@ Preprocess without #line directives. Suppresses comment strip from source code; requires setting at least one of the **Preprocessing** options. Sets [`/C`](c-preserve-comments-during-preprocessing.md). +### Use Standard Conforming Preprocessor + +Use a standard conforming preprocessor ([`/Zc:preprocessor`](zc-preprocessor.md)). Currently implied by [`/std:c11`](std-specify-language-standard-version.md) and later versions. To use legacy preprocessor set this property to 'No'. + ## C/C++ Code Generation Properties ### Enable String Pooling @@ -243,9 +254,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 +264,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 +299,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 @@ -299,6 +310,10 @@ Enable use of instructions found on processors that support enhanced instruction - **No Enhanced Instructions** - No Enhanced Instructions. Sets **`/arch:IA32`** - **Not Set** - Not Set. +### Enable Vector Length + +Enable choosing vector length for [`/arch:AVX512`](arch-x86.md) and [`/arch:AVX10.x`](arch-x86.md) flags. Allowed values are 256 and 512 bits (X86/X64). + ### Floating Point Model Sets the floating point model. Sets [`/fp:precise`, `/fp:strict`, `/fp:fast`](fp-specify-floating-point-behavior.md). @@ -326,17 +341,25 @@ Spectre mitigations for CVE 2017-5753. Sets [`/Qspectre`](qspectre.md). - **Enabled** - Enable Spectre mitigation feature for CVE 2017-5753 - **Disabled** - Not Set. +### Enable Intel JCC Erratum Mitigation + +Software mitigation for the performance impact caused by the Intel JCC erratum microcode update. Sets [`/QIntel-jcc-erratum`](qintel-jcc-erratum.md). + +### Enable EH Continuation Metadata + +Generates a sorted list of all the valid exception handling continuation targets for a binary, used during runtime for RIP validation. Currently available for x64 builds. Sets [`/guard:ehcont`](guard-enable-eh-continuation-metadata.md). + +### Enable Signed Returns + +Enables signed returns which help detect and prevent attempts to dispatch to illegal blocks from function returns. Currently available for ARM64 builds. Sets `/guard:signret`. + ## C/C++ Language Properties ### Disable Language Extensions 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 +383,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 @@ -370,12 +393,32 @@ Determines the C++ language standard the compiler enables. The default value doe - **ISO C++14 Standard (/std:c++14)** - **ISO C++17 Standard (/std:c++17)** - **ISO C++20 Standard (/std:c++20)** -- **Preview - Features from the Latest C++ Working Draft (/std:c++latest)** +- **Preview - ISO C++23 Standard (/std:c++23preview)** +- **Preview - Features from the Latest C++ Working Draft (/std:c++latest)** + +### C Language Standard -### Enable C++ Modules (experimental) +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)** +- **Preview - Features from the Latest C Working Draft (/std:clatest)** + +### 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`, Microsoft 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 @@ -422,6 +465,14 @@ Causes the output file to be created in UTF-8 format. Specifies relative path or name for ASM listing file; can be file or directory name. Sets [`/Fa`](fa-fa-listing-file.md). +### Module Output File Name + +Module or header unit output (BMI) file location; can be file or directory name. Sets [`/ifcOutput[name]`](ifc-output.md). + +### Module Dependencies File Name + +Specifies the path and/or name of the generated module dependencies file. Sets [`/scanDependencies[path]`](scandependencies.md). + ### Object File Name Specifies a name to override the default object file name; can be file or directory name. Sets [`/Fo`](fo-object-file-name.md). @@ -438,6 +489,14 @@ Specifies that the compiler should generate XML documentation comment files (.XD Specifies the name of the generated XML documentation files; can be file or directory name. Sets [`/doc:`\](doc-process-documentation-comments-c-cpp.md). +### Generate Source Dependencies File + +Generates a json file with the list of all files the compiler used for the compilation of the source. Sets [`/sourceDependencies`](sourcedependencies.md). + +### Source Dependencies File Name + +Specifies the path and/or name of the generated source dependencies file. Sets [`/sourceDependencies[path]`](sourcedependencies.md). + ## C/C++ Browse Information Properties ### Enable Browse Information @@ -448,7 +507,7 @@ Specifies level of browse information in *`.bsc`* file. Sets [`/FR`](fr-fr-creat Specifies optional name for browser information file. Sets [`/FR`\](fr-fr-create-dot-sbr-file.md). -## External Includes +## C/C++ External Includes Properties ### Treat Files Included with Angle Brackets as External @@ -485,13 +544,16 @@ Select the default calling convention for your application (can be overridden by ### Compile As -Select compile language option for *`.c`* and *`.cpp`* files. Sets [`/TC`, `/TP`](tc-tp-tc-tp-specify-source-file-type.md). +Select compile language option for source files. Sets [`/TC`, `/TP`](tc-tp-tc-tp-specify-source-file-type.md), [/interface](./interface.md), [`/internalPartition`](./internal-partition.md), or [`/exportHeader`](./module-exportheader.md) options. #### Choices - **Default** - Default. -- **Compile as C Code** - Compile as C Code. -- **Compile as C++ Code** - Compile as C++ Code. +- **Compile as C Code ([`/TC`](./tc-tp-tc-tp-specify-source-file-type.md))** - Compile specified source files as C code. By default, files with a *`.c`* extension are compiled as C. +- **Compile as C++ Code ([`/TP`](./tc-tp-tc-tp-specify-source-file-type.md))** - Compile specified source files as C++ code. By default, all source files that don't have a *`.c`*, *`.ixx`*, *`.cppm`*, *`.h`*, or no extension are compiled as C++. +- **Compile as C++ Module Code ([`/interface`](./interface.md))** - Compile specified source files as C++ module code. By default, files with a *`.ixx`* or *`.cppm`* extension are compiled as C++ module code. +- **Compile as C++ Module Internal Partition ([`/internalPartition`](./internal-partition.md))** - Compile specified source files as C++ module internal partition. +- **Compile as C++ Header Unit ([`/exportHeader`](./module-exportheader.md))** - Compile specified source files as C++ header unit. By default, files with a *`.h`* extension or no extension are compiled as header units. ### Disable Specific Warnings diff --git a/docs/build/reference/cetcompat.md b/docs/build/reference/cetcompat.md index 3eb8eecd940..984e60d83ad 100644 --- a/docs/build/reference/cetcompat.md +++ b/docs/build/reference/cetcompat.md @@ -2,12 +2,12 @@ description: "Learn more about: /CETCOMPAT (CET Shadow Stack compatible)" title: "/CETCOMPAT (CET Shadow Stack compatible)" ms.date: 09/22/2021 -f1_keywords: ["/CETCOMPAT"] +f1_keywords: ["VC.Project.VCLinkerTool.CETCompat", "/CETCOMPAT"] helpviewer_keywords: ["/CETCOMPAT linker option", "/CETCOMPAT"] --- -# /CETCOMPAT (CET Shadow Stack compatible) +# `/CETCOMPAT` (CET Shadow Stack compatible) -Specifies whether to mark an executable image as compatible with Control-flow Enforcement Technology (CET) Shadow Stack. +Specifies whether the linker marks an executable image as compatible with Control-flow Enforcement Technology (CET) Shadow Stack. ## Syntax @@ -21,9 +21,9 @@ Specifies that the executable shouldn't be marked compatible with CET Shadow Sta ## Remarks -Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature. It provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [A Technical Look at Intel’s Control-flow Enforcement Technology](https://software.intel.com/content/www/us/en/develop/articles/technical-look-control-flow-enforcement-technology.html). +Control-flow Enforcement Technology (CET) Shadow Stack is a computer processor feature. It provides capabilities to defend against return-oriented programming (ROP) based malware attacks. For more information, see [A Technical Look at Intel's Control-flow Enforcement Technology](https://software.intel.com/content/www/us/en/develop/articles/technical-look-control-flow-enforcement-technology.html). -The **`/CETCOMPAT`** linker option tells the linker to mark the binary as CET Shadow Stack-compatible. **`/CETCOMPAT:NO`** marks the binary as not compatible with CET Shadow Stack. If both options are specified on the command line, the last one specified is used. This switch is currently only applicable to x86 and x64 architectures. +The **`/CETCOMPAT`** linker option tells the linker to mark the binary as CET Shadow Stack-compatible. **`/CETCOMPAT:NO`** marks the binary as not compatible with CET Shadow Stack. If both options are specified on the command line, the last one specified is used. This switch is currently only applicable to the x64 architecture. The **`/CETCOMPAT`** option is available beginning in Visual Studio 2019. @@ -31,7 +31,7 @@ The **`/CETCOMPAT`** option is available beginning in Visual Studio 2019. Starting in Visual Studio 2019 version 16.7: -1. Open the **Property Pages** dialog box for the project. For more information, see [Working with Project Properties](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. @@ -41,7 +41,7 @@ Starting in Visual Studio 2019 version 16.7: In previous versions of Visual Studio 2019: -1. Open the **Property Pages** dialog box for the project. For more information, see [Working with Project Properties](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. diff --git a/docs/build/reference/cgthreads-code-generation-threads.md b/docs/build/reference/cgthreads-code-generation-threads.md index d169b1d3419..20091542bd9 100644 --- a/docs/build/reference/cgthreads-code-generation-threads.md +++ b/docs/build/reference/cgthreads-code-generation-threads.md @@ -4,11 +4,10 @@ title: "/cgthreads (Code generation threads)" ms.date: 07/31/2020 f1_keywords: ["/cgthreads"] helpviewer_keywords: ["/cgthreads compiler option (C++)", "-cgthreads compiler option (C++)", "cgthreads compiler option (C++)", "cgthreads"] -ms.assetid: 64bc768c-6caa-4baf-9dea-7cfa1ffb01c2 --- # `/cgthreads` (Code generation threads) -Sets number of cl.exe threads to use for optimization and code generation. +Sets number of `cl.exe` threads to use for optimization and code generation. ## Syntax @@ -24,20 +23,18 @@ Sets number of cl.exe threads to use for optimization and code generation. ## Arguments **`cgthreadsN`**\ -The maximum number of threads for cl.exe to use, where *N* is a number in the range 1 to 8. +The maximum number of threads for `cl.exe` to use, where *N* is a number in the range 1 to 8. ## Remarks -The **`cgthreads`** option specifies the maximum number of threads cl.exe uses in parallel for the optimization and code generation phases of compilation. Notice that there can be no space between **`cgthreads`** and the *number* argument. By default, cl.exe uses four threads, as if **`/cgthreads4`** were specified. If more processor cores are available, a larger *number* value can improve build times. This option is especially useful when it's combined with [`/GL` (Whole Program Optimization)](gl-whole-program-optimization.md). +The **`cgthreads`** option specifies the maximum number of threads `cl.exe` uses in parallel for the optimization and code generation phases of compilation. Notice that there can be no space between **`cgthreads`** and the *number* argument. By default, `cl.exe` uses four threads, as if **`/cgthreads4`** were specified. If more processor cores are available, a larger *number* value can improve build times. This option is especially useful when it's combined with [`/GL` (Whole Program Optimization)](gl-whole-program-optimization.md). -Multiple levels of parallelism can be specified for a build. The msbuild.exe switch **`/maxcpucount`** specifies the number of MSBuild processes that can be run in parallel. The [`/MP` (Build with Multiple Processes)](mp-build-with-multiple-processes.md) compiler flag specifies the number of cl.exe processes that simultaneously compile the source files. The **`cgthreads`** option specifies the number of threads used by each cl.exe process. The processor can only run as many threads at the same time as there are processor cores. It's not useful to specify larger values for all of these options at the same time, and it can be counterproductive. For more information about how to build projects in parallel, see [Building Multiple Projects in Parallel](/visualstudio/msbuild/building-multiple-projects-in-parallel-with-msbuild). +Multiple levels of parallelism can be specified for a build. The msbuild.exe switch **`/maxcpucount`** specifies the number of MSBuild processes that can be run in parallel. The [`/MP` (Build with Multiple Processes)](mp-build-with-multiple-processes.md) compiler flag specifies the number of `cl.exe` processes that simultaneously compile the source files. The **`cgthreads`** option specifies the number of threads used by each `cl.exe` process. The processor can only run as many threads at the same time as there are processor cores. It's not useful to specify larger values for all of these options at the same time, and it can be counterproductive. For more information about how to build projects in parallel, see [Building Multiple Projects in Parallel](/visualstudio/msbuild/building-multiple-projects-in-parallel-with-msbuild). ### 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 **`cgthreadsN`**, where *`N`* is a value from 1 to 8, and then select **OK**. ### To set this compiler option programmatically @@ -46,5 +43,5 @@ Multiple levels of parallelism can be specified for a build. The msbuild.exe swi ## 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/choosing-the-format-of-netmodule-input-files.md b/docs/build/reference/choosing-the-format-of-netmodule-input-files.md index 708f741e6a0..86c167a0fb5 100644 --- a/docs/build/reference/choosing-the-format-of-netmodule-input-files.md +++ b/docs/build/reference/choosing-the-format-of-netmodule-input-files.md @@ -2,32 +2,31 @@ description: "Learn more about: Choosing the Format of .netmodule Input Files" title: "Choosing the Format of .netmodule Input Files" ms.date: "11/04/2016" -ms.assetid: 4653d1bd-300f-4083-86f5-d1a06f44e61c --- -# Choosing the Format of .netmodule Input Files +# Choosing the format of .netmodule input files -An MSIL .obj file (compiled with [/clr](clr-common-language-runtime-compilation.md)) can also be used as a .netmodule file. .obj files contain metadata and native symbols. .netmodules only contain metadata. +You can use an MSIL `.obj` file (compiled with [`/clr`](clr-common-language-runtime-compilation.md)) as a `.netmodule` file. `.obj` files contain metadata and native symbols. `.netmodules` only contain metadata. -You can pass an MSIL .obj file to any other Visual Studio compiler via the /addmodule compiler option (but be aware that the .obj file becomes part of the resulting assembly and must be shipped with the assembly). For example, Visual C# and Visual Basic have the /addmodule compiler option. +Pass an MSIL `.obj` file to any other Visual Studio compiler with the `/addmodule` compiler option. The `.obj` file becomes part of the resulting assembly and must be shipped with the assembly. For example, Visual C# and Visual Basic have the `/addmodule` compiler option. > [!NOTE] -> In most cases, you will need to pass to the linker the .obj file from the compilation that created the .net module. Passing a .dll or .netmodule MSIL module file to the linker may result in LNK1107. +> In most cases, you need to pass to the linker the `.obj` file from the compilation that created the .net module. Passing a `.dll` or `.netmodule` MSIL module file to the linker might result in LNK1107. -.obj files, along with their associated .h files, which you reference via #include in source, allow C++ applications to consume the native types in the module, whereas in a .netmodule file, only the managed types can be consumed by a C++ application. If you attempt to pass a .obj file to #using, information about native types will not be available; #include the .obj file's .h file instead. +`.obj` files, along with their associated `.h` files, which you reference via #include in source, allow C++ applications to consume the native types in the module. In a `.netmodule` file, only the managed types can be consumed by a C++ application. If you attempt to pass a `.obj` file to #using, information about native types isn't available. Instead, #include the `.obj` file's `.h` file. Other Visual Studio compilers can only consume managed types from a module. -Use the following to determine whether you need to use a .netmodule or a .obj file as module input to the MSVC linker: +Use the following guidance to determine whether you need to use a `.netmodule` or a `.obj` file as module input to the MSVC linker: -- If you are building with a Visual Studio compiler other than Visual C++, produce a .netmodule and use the .netmodule as input to the linker. +- If you're building with a Visual Studio compiler other than Visual C++, produce a `.netmodule` and use the `.netmodule` as input to the linker. -- If you are using the MSVC compiler to produce modules and if the module(s) will be used to build something other than a library, use the .obj files produced by the compiler as module input to the linker; do not use the .netmodule file as input. +- If you're using the MSVC compiler to produce modules and if the modules are used to build something other than a library, use the `.obj` files produced by the compiler as module input to the linker. Don't use the `.netmodule` file as input. -- If your modules will be used to build a native (not a managed) library, use .obj files as module input to the linker and generate a .lib library file. +- If your modules are used to build a native (not a managed) library, use `.obj` files as module input to the linker and generate a `.lib` library file. -- If your modules will be used to build a managed library, and if all module input to the linker will be verifiable (produced with /clr:safe), use .obj files as module input to the linker and generate a .dll (assembly) or .netmodule (module) library file. +- If your modules are used to build a managed library, and if all module input to the linker is verifiable (produced with `/clr:safe`), use `.obj` files as module input to the linker and generate a `.dll` (assembly) or `.netmodule` (module) library file. -- If your modules will be used to build a managed library, and if one or more modules input to the linker will be produced with just /clr, use .obj files as module input to the linker and generate a .dll (assembly). If you want to expose managed types from the library and if you also want C++ applications to consume the native types in the library, your library will consist of the .obj files for the libraries component modules (you will also want to ship the .h files for each module, so they can be referenced with #include from source code). +- If your modules are used to build a managed library, and if one or more modules input to the linker are produced with just `/clr`, use `.obj` files as module input to the linker and generate a `.dll` (assembly). If you want to expose managed types from the library and if you also want C++ applications to consume the native types in the library, your library consists of the `.obj` files for the libraries component modules. You also want to ship the `.h` files for each module, so they can be referenced with #include from source code. ## See also diff --git a/docs/build/reference/cl-invokes-the-linker.md b/docs/build/reference/cl-invokes-the-linker.md index 8f01f044f2d..df402a70150 100644 --- a/docs/build/reference/cl-invokes-the-linker.md +++ b/docs/build/reference/cl-invokes-the-linker.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: CL Invokes the Linker" title: "CL Invokes the Linker" -ms.date: "11/04/2016" +description: "Learn more about: CL Invokes the Linker" +ms.date: 11/04/2016 helpviewer_keywords: ["compiling source code [C++], without linking", "invoking linker from the compiler", "LINK tool [C++], invoking from CL compiler", "cl.exe compiler [C++], compiling without linking", "cl.exe compiler [C++], controlling linker"] -ms.assetid: eae47ef7-09eb-40c9-b318-7c714cd452fc --- # CL Invokes the Linker @@ -30,7 +29,7 @@ Assume that you are compiling three C source files: MAIN.c, MOD1.c, and MOD2.c. To build this program, compile with the following command line: -``` +```cmd CL MAIN.c MOD1.C MOD2.C MYGRAPH.lib ``` diff --git a/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md b/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md index ef9e5e1e0d7..7ab680d3cf5 100644 --- a/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md +++ b/docs/build/reference/clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md @@ -1,39 +1,39 @@ --- description: "Learn more about: /CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls)" title: "/CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls)" -ms.date: "11/04/2016" -f1_keywords: ["/CLRSUPPORTLASTERROR"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.CLRSupportLastError", "/CLRSUPPORTLASTERROR"] helpviewer_keywords: ["/CLRSUPPORTLASTERROR linker option", "-CLRSUPPORTLASTERROR linker option"] ms.assetid: b7057990-4154-4b1d-9fc9-6236f7be7575 --- -# /CLRSUPPORTLASTERROR (Preserve Last Error Code for PInvoke Calls) +# `/CLRSUPPORTLASTERROR` (Preserve Last Error Code for PInvoke Calls) -**/CLRSUPPORTLASTERROR**, which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **/clr**. +**`/CLRSUPPORTLASTERROR`**, which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **`/clr`**. ## Syntax -``` -/CLRSUPPORTLASTERROR{:NO | SYSTEMDLL} -``` +> **`/CLRSUPPORTLASTERROR`**\ +> **`/CLRSUPPORTLASTERROR:NO`**\ +> **`/CLRSUPPORTLASTERROR:SYSTEMDLL`** ## Remarks -Preserving the last error code implies a decrease in performance. If you do not want to incur the performance impact of preserving the last error code, link with **/CLRSUPPORTLASTERROR:NO**. +Preserving the last error code implies a decrease in performance. If you don't want to incur the performance cost of preserving the last error code, link by using **`/CLRSUPPORTLASTERROR:NO`**. -You can minimize the performance impact by linking with **/CLRSUPPORTLASTERROR:SYSTEMDLL**, which only preserves the last error code for functions in system DLLs. +You can minimize the performance penalty by linking with **`/CLRSUPPORTLASTERROR:SYSTEMDLL`**, which only preserves the last error code for functions in system DLLs. > [!NOTE] -> Preserving the last error is not supported for unmanaged functions that are consumed by CLR code, in the same module. +> Preserving the last error isn't supported for unmanaged functions that are consumed by CLR code in the same module. -- For more information, see [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md). +- For more information, see [`/clr` (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md). ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option into the **Additional Options** box. +1. Modify the **Preserve Last Error Code for PInvoke Calls** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -56,7 +56,7 @@ __declspec(dllexport) double MySqrt(__int64 n) { } ``` -The following sample consumes the DLL, demonstrating how to use **/CLRSUPPORTLASTERROR**. +The following sample consumes the DLL, demonstrating how to use **`/CLRSUPPORTLASTERROR`**. ```cpp // CLRSUPPORTLASTERROR_client.cpp @@ -109,5 +109,5 @@ GetLastError for system call succeeded (183). ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md index fe8ce160d24..ffc60a41e9a 100644 --- a/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md +++ b/docs/build/reference/clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md @@ -1,37 +1,38 @@ --- description: "Learn more about: /CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute)" title: "/CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute)" -ms.date: "05/16/2019" +ms.date: 09/19/2022 ms.topic: "reference" -f1_keywords: ["/CLRUNMANAGEDCODECHECK"] +f1_keywords: ["VC.Project.VCLinkerTool.CLRUnmanagedCodeCheck", "/CLRUNMANAGEDCODECHECK"] helpviewer_keywords: ["-CLRUNMANAGEDCODECHECK linker option", "/CLRUNMANAGEDCODECHECK linker option"] ms.assetid: 73abc426-dab0-45e2-be85-0f9a14206cc2 -author: "corob-msft" -ms.author: "corob" +author: "tylermsft" +ms.author: "twhitney" --- -# /CLRUNMANAGEDCODECHECK (Remove SuppressUnmanagedCodeSecurityAttribute) +# `/CLRUNMANAGEDCODECHECK` (Remove SuppressUnmanagedCodeSecurityAttribute) -**/CLRUNMANAGEDCODECHECK** specifies that the linker does not apply to linker-generated `PInvoke` calls from managed code into native DLLs. +**`/CLRUNMANAGEDCODECHECK`** specifies that the linker doesn't apply to linker-generated `PInvoke` calls from managed code into native DLLs. ## Syntax -> **/CLRUNMANAGEDCODECHECK**[**:NO**] +> **`/CLRUNMANAGEDCODECHECK`**\ +> **`/CLRUNMANAGEDCODECHECK:NO`** ## Remarks -By default, the linker applies the **SuppressUnmanagedCodeSecurityAttribute** to linker-generated `PInvoke` calls. When **/CLRUNMANAGEDCODECHECK** is in effect, **SuppressUnmanagedCodeSecurityAttribute** is removed. To explicitly apply the **SuppressUnmanagedCodeSecurityAttribute** to linker-generated `PInvoke` calls, you can use **/CLRUNMANAGEDCODECHECK:NO**. +By default, the linker applies the `SuppressUnmanagedCodeSecurityAttribute` attribute to linker-generated `PInvoke` calls. When **`/CLRUNMANAGEDCODECHECK`** is in effect, `SuppressUnmanagedCodeSecurityAttribute` is removed. To explicitly apply the `SuppressUnmanagedCodeSecurityAttribute` attribute to linker-generated `PInvoke` calls, you can use **`/CLRUNMANAGEDCODECHECK:NO`**. -The linker only adds the attribute to objects that are compiled using **/clr** or **/clr:pure**. However, the **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. +The linker only adds the attribute to objects that are compiled using **`/clr`** or **`/clr:pure`**. However, the **`/clr:pure`** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. -A `PInvoke` call is generated by the linker when the linker cannot find a managed symbol to satisfy a reference from a managed caller but can find a native symbol to satisfy that reference. For more information about `PInvoke`, see [Calling Native Functions from Managed Code](../../dotnet/calling-native-functions-from-managed-code.md). +A `PInvoke` call is generated by the linker when the linker can't find a managed symbol to satisfy a reference from a managed caller but can find a native symbol to satisfy that reference. For more information about `PInvoke`, see [Calling Native Functions from Managed Code](../../dotnet/calling-native-functions-from-managed-code.md). -Note that if you use in your code, you should explicitly set **/CLRUNMANAGEDCODECHECK** to remove the **SuppressUnmanagedCodeSecurity** attribute. It is a potential security vulnerability if an image contains both the **SuppressUnmanagedCodeSecurity** and **AllowPartiallyTrustedCallers** attributes. +If you use in your code, you should explicitly set **`/CLRUNMANAGEDCODECHECK`** to remove the `SuppressUnmanagedCodeSecurity` attribute. It's a potential security vulnerability if an image contains both the `SuppressUnmanagedCodeSecurity` and `AllowPartiallyTrustedCallers` attributes. -See [Secure Coding Guidelines for Unmanaged Code](/previous-versions/dotnet/framework/windows-identity-foundation/secure-coding-guidelines-for-unmanaged-code) for more information about the implications of using **SuppressUnmanagedCodeSecurityAttribute**. +For more information about the implications of using `SuppressUnmanagedCodeSecurityAttribute`, see [Secure Coding Guidelines for Unmanaged Code](/previous-versions/dotnet/framework/windows-identity-foundation/secure-coding-guidelines-for-unmanaged-code). ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. @@ -43,5 +44,5 @@ See [Secure Coding Guidelines for Unmanaged Code](/previous-versions/dotnet/fram ## See also -- [MSVC linker reference](linking.md) -- [MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/command-line-property-pages.md b/docs/build/reference/command-line-property-pages.md index 9f7efcc20a5..3e5ab9a2c5b 100644 --- a/docs/build/reference/command-line-property-pages.md +++ b/docs/build/reference/command-line-property-pages.md @@ -1,20 +1,33 @@ --- -description: "Learn more about: Command Line Property Pages" -title: "Command Line Property Pages" -ms.date: "11/04/2016" +description: "Learn more about: Command line property pages" +title: "Command line property pages" +ms.date: 09/21/2022 f1_keywords: ["vc.project.AdditionalOptionsPage", "vc.project.CommandLinePage"] helpviewer_keywords: ["Command Line property pages"] ms.assetid: e1721b6c-8b39-4b44-a41e-69b5bb470cc9 --- -# Command Line Property Pages +# Command line property pages -Most property page folders contain a **Command Line** property page. This page displays which properties are set in the folder. The **Command Line** property page also contains an **Additional Options** box where you can specify properties that are valid for the tool but for which there is no property in the folder. +Most property page folders that correspond with a command-line tool contain a **Command Line** property page. For information on how to access the **Command Line** property pages, see [Set compiler and build properties](../working-with-project-properties.md). -Any command that you enter in the edit box will be passed through to the tool for the folder. No verification or checks will be done on the input, nor will there be any dependency checking. +## Command Line property page -For information on how to access the **Command Line** property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +### All Options + +The **All Options** display-only control shows the tool command line created by the properties set in the folder. + +### Additional Options + +This property's edit control lets you specify other command-line options that are valid for the tool but that don't have a corresponding property. + +The options that you enter in the edit box are passed through to the tool for the folder after the options listed in **All Options**. No verification or validity checks are done on the options you enter, and there's no dependency checking. ## See also -[C++ project property page reference](property-pages-visual-cpp.md)
-[.Lib Files as Linker Input](dot-lib-files-as-linker-input.md) +[Windows C++ project property page reference](property-pages-visual-cpp.md)\ +[Linux C++ property page reference](../../linux/prop-pages-linux.md)\ +[Linker property pages](./linker-property-pages.md)\ +[Manifest tool property pages](manifest-tool-property-pages.md)\ +[MIDL property pages](midl-property-pages.md)\ +[NMake property page](nmake-property-page.md)\ +[XML document generator tool property pages](xml-document-generator-tool-property-pages.md) diff --git a/docs/build/reference/commands-in-a-makefile.md b/docs/build/reference/commands-in-a-makefile.md index 05a0f36f148..9929e2f05b1 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 17c26d9a7e0..5f3cd0fc40d 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 -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 +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)", "ShortProjectName macro $(ShortProjectName)"] --- # 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,45 +31,46 @@ 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. | +| **`$(ShortProjectName)`** | Shortened project name used when `IntDir` is unset; defaults to `$(ProjectName)` but truncates long names to `ProjectName.Substring(0,8).ProjectGuid.Substring(1,8)` to keep intermediate paths short and unique. | | **`$(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. | | **`$(TargetPath)`** | The absolute path name of the primary output file for the build (defined as drive + path + base name + file extension). | -| **`$(VCInstallDir)`** | The directory that contains the C++ content of your Visual Studio installation. This property contains the version of the targeted Microsoft C++ (MSVC) toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v140`, **`$(VCInstallDir)`** contains the path to the Visual Studio 2015 installation. | -| **`$(VSInstallDir)`** | The directory into which you installed Visual Studio. This property contains the version of the targeted Visual Studio toolset, which might be different that the host Visual Studio. For example, when building with `$(PlatformToolset) = v110`, **`$(VSInstallDir)`** contains the path to the Visual Studio 2012 installation. | +| **`$(VCInstallDir)`** | The directory that contains the C++ content of your Visual Studio installation. This property contains the version of the targeted Microsoft C++ (MSVC) toolset, which might be different than the host Visual Studio. For example, when building with `$(PlatformToolset) = v140`, **`$(VCInstallDir)`** contains the path to the Visual Studio 2015 installation. | +| **`$(VSInstallDir)`** | The directory into which you installed Visual Studio. This property contains the version of the targeted Visual Studio toolset, which might be different than the host Visual Studio. For example, when building with `$(PlatformToolset) = v110`, **`$(VSInstallDir)`** contains the path to the Visual Studio 2012 installation. | | **`$(WebDeployPath)`** | The relative path from the web deployment root to where the project outputs belong. | | **`$(WebDeployRoot)`** | The absolute path to the location of **``**. For example, *`c:\inetpub\wwwroot`*. | ## Obsolete macros -The build system for C++ was 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 +78,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 6936391ed25..e34ddaab592 100644 --- a/docs/build/reference/compiler-command-line-syntax.md +++ b/docs/build/reference/compiler-command-line-syntax.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Compiler Command-Line Syntax" title: "MSVC Compiler Command-Line Syntax" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Command-Line Syntax" +ms.date: 11/04/2016 helpviewer_keywords: ["syntax, CL compiler command line", "cl.exe compiler, command-line syntax"] -ms.assetid: acba2c1c-0803-4a3a-af25-63e849b930a2 --- # Compiler Command-Line Syntax The CL command line uses the following syntax: -``` +```cmd CL [option...] file... [option | file]... [lib...] [@command-file] [/link link-opt...] ``` @@ -17,7 +16,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 e0a22b76fb4..8e2d8e81772 100644 --- a/docs/build/reference/compiler-options-listed-alphabetically.md +++ b/docs/build/reference/compiler-options-listed-alphabetically.md @@ -1,7 +1,8 @@ --- title: "Compiler options listed alphabetically" description: "Reference listing in alphabetical order of the Microsoft C/C++ compiler command-line options." -ms.date: 04/15/2022 +ms.date: 05/25/2026 +ai-usage: ai-assisted helpviewer_keywords: ["compiler options, C++"] --- # Compiler options listed alphabetically @@ -16,7 +17,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. | @@ -34,8 +36,9 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/clr:safe`](clr-common-language-runtime-compilation.md) | Produce an IL-only verifiable output file. | | [`/constexpr:backtrace`](constexpr-control-constexpr-evaluation.md) | Show N `constexpr` evaluations in diagnostics (default: 10). | | [`/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) | +| [`/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 +49,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 +67,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-enable-architecture-features.md) | Enable architecture features. | +| [`/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 +86,7 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/fsanitize`](fsanitize.md) | Enables compilation of sanitizer instrumentation such as AddressSanitizer. | | [`/fsanitize-coverage`](fsanitize-coverage.md) | Enables compilation of code coverage instrumentation for libraries such as LibFuzzer. | | `/Ft` | Location of the header files generated for `#import`. | -| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name, as if it had been passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | +| [`/FU`](fu-name-forced-hash-using-file.md) | Forces the use of a file name, as if it were passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. | | [`/Fx`](fx-merge-injected-code.md) | Merges injected code with the source file. | | [`/GA`](ga-optimize-for-windows-application.md) | Optimizes for Windows applications. | | [`/Gd`](gd-gr-gv-gz-calling-convention.md) | Uses the **`__cdecl`** calling convention. (x86 only) | @@ -111,12 +117,13 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/homeparams`](homeparams-copy-register-parameters-to-stack.md) | Forces parameters passed in registers to be written to their locations on the stack upon function entry. This compiler option is only for the x64 compilers (native and cross compile). | | [`/hotpatch`](hotpatch-create-hotpatchable-image.md) | Creates a hotpatchable image. | | [`/I`](i-additional-include-directories.md) | Searches a directory for include files. | -| **`/ifcOutput`** | Specify output file or directory for *`.ifc`* files. | +| [`/ifcOutput`](ifc-output.md) | Specify output file name or directory for built *`.ifc`* files. | | [`/interface`](interface.md) | Treat the input file as a module interface unit. | | [`/internalPartition`](internal-partition.md) | Treat the input file as an internal partition unit. | | [`/J`](j-default-char-type-is-unsigned.md) | Changes the default **`char`** type. | +| [`/jumptablerdata`](jump-table-rdata.md) | Put switch case statement jump tables in the `.rdata` section. | | [`/JMC`](jmc.md) | Supports native C++ Just My Code debugging. | -| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker will create a binary that can be executed in the Windows kernel. | +| [`/kernel`](kernel-create-kernel-mode-binary.md) | The compiler and linker create a binary that can be executed in the Windows kernel. | | [`/LD`](md-mt-ld-use-run-time-library.md) | Creates a dynamic-link library. | | [`/LDd`](md-mt-ld-use-run-time-library.md) | Creates a debug dynamic-link library. | | [`/link`](link-pass-options-to-linker.md) | Passes the specified option to LINK. | @@ -174,6 +181,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 +193,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 +201,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. | @@ -212,42 +221,50 @@ This table contains an alphabetical list of compiler options. For a list of comp | [`/Z7`](z7-zi-zi-debug-information-format.md) | Generates C 7.0-compatible debugging information. | | [`/Za`](za-ze-disable-language-extensions.md) | Disables some C89 language extensions in C code. | | [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported (off by default). | | [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | | [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | | [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for `enum` type deduction (off by default). | | [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | | [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | | [`/Zc:forScope[-]`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | -| [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | +| [`/Zc:gotoScope`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization (implied by **`/permissive-`**). | +| [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**). | | [`/Zc:implicitNoexcept[-]`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | | [`/Zc:inline[-]`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | | [`/Zc:lambda[-]`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | | [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions (on by default under **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later). | | [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | | [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | | [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | | [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | | [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules (off by default). | | [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | | [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | | [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | -| `/Zc:tlsGuards[-]` | Generate runtime checks for TLS variable initialization (on by default). | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization (on by default). | | [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | -| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use non-conforming template parsing behavior (conforming by default). | +| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use nonconforming template parsing behavior (conforming by default). | | [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | -| `/Zc:zeroSizeArrayNew[-]` | Call member `new`/`delete` for 0-size arrays of objects (on by default). | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for zero-size arrays of objects (on by default). | | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables C89 language extensions. | | [`/Zf`](zf.md) | Improves PDB generation time in parallel builds. | -| [`/ZH:[MD5|SHA1|SHA_256]`](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | +| [`/ZH:[MD5|SHA1|SHA_256|SHA384|SHA512]`](zh.md) | Specifies MD5, SHA-1, SHA-256, SHA-38418.6.0, or SHA-51218.6.0 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. | | [`/Zm`](zm-specify-precompiled-header-memory-allocation-limit.md) | Specifies the precompiled header memory allocation limit. | | [`/Zo[-]`](zo-enhance-optimized-debugging.md) | Generate richer debugging information for optimized code. | -| [`/Zp[n]`](zp-struct-member-alignment.md) *n* | Packs structure members. | +| [`/Zp[n]`](zp-struct-member-alignment.md) | Packs structure members. | | [`/Zs`](zs-syntax-check-only.md) | Checks syntax only. | | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. | +17.14 This option is available starting in Visual Studio 2022 version 17.14.\ +18.6.0 This option is available starting in Visual Studio 2026 version 18.6.0 and MSVC version 14.51. + ## 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 fc2cfa8c447..2636a52da0e 100644 --- a/docs/build/reference/compiler-options-listed-by-category.md +++ b/docs/build/reference/compiler-options-listed-by-category.md @@ -1,9 +1,9 @@ --- title: "Compiler Options Listed by Category" description: "Reference listing by category of the Microsoft C/C++ compiler command-line options." -ms.date: 04/15/2022 +ms.date: 05/25/2026 +ai-usage: ai-assisted helpviewer_keywords: ["compiler options, C++"] -ms.assetid: c4750dcf-dba0-4229-99b6-45cdecc11729 --- # Compiler options listed by category @@ -13,6 +13,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 +30,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 +44,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-enable-architecture-features.md) | Enable architecture features. | +| [`/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 +79,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 +95,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. | @@ -137,7 +142,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/exportHeader`](module-exportheader.md) | Create the header units files (*`.ifc`*) specified by the input arguments. | | [`/headerUnit`](headerunit.md) | Specify where to find the header unit file (*`.ifc`*) for the specified header. | | [`/headerName`](headername.md) | Build a header unit from the specified header. | -| **`/ifcOutput`** | Specify output file or directory for *`.ifc`* files. | +| [`/ifcOutput`](ifc-output.md) | Specify the output file name or directory for built *`.ifc`* files. | | [`/interface`](interface.md) | Treat the input file as a module interface unit. | | [`/internalPartition`](internal-partition.md) | Treat the input file as an internal partition unit. | | [`/reference`](module-reference.md) | Use named module IFC. | @@ -154,7 +159,7 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/await:strict`](await-enable-coroutine-support.md) | Enable standard C++20 coroutine support with earlier language versions. | | [`/constexpr:backtrace`](constexpr-control-constexpr-evaluation.md) | Show N `constexpr` evaluations in diagnostics (default: 10). | | [`/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) | +| [`/constexpr:steps`](constexpr-control-constexpr-evaluation.md) | Terminate `constexpr` evaluation after N steps (default: 100000). | | [`/openmp`](openmp-enable-openmp-2-0-support.md) | Enables [`#pragma omp`](../../preprocessor/omp.md) in source code. | | [`/openmp:experimental`](openmp-enable-openmp-2-0-support.md) | Enable OpenMP 2.0 language extensions plus select OpenMP 3.0+ language extensions. | | [`/openmp:llvm`](openmp-enable-openmp-2-0-support.md) | OpenMP language extensions using LLVM runtime. | @@ -165,6 +170,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. | @@ -173,42 +179,49 @@ This article contains a categorical list of compiler options. For an alphabetica | [`/vmv`](vmm-vms-vmv-general-purpose-representation.md) | Declares virtual inheritance. | | [`/Z7`](z7-zi-zi-debug-information-format.md) | Generates C 7.0-compatible debugging information. | | [`/Za`](za-ze-disable-language-extensions.md) | Disables some C89 language extensions in C code. | +| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported (off by default). | | [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | | [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | | [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | -| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for inferred `enum` base types (Off by default, not implied by **`/permissive-`**). | | [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | | [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | | [`/Zc:forScope[-]`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | -| [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | +| [`/Zc:gotoScope`](zc-gotoscope.md) | Enforce Standard C++ **`goto`** rules around local variable initialization (implied by **`/permissive-`**). | +| [`/Zc:hiddenFriend[-]`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**). | | [`/Zc:implicitNoexcept[-]`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | | [`/Zc:inline[-]`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | | [`/Zc:lambda[-]`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | | [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions (on by default under **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later). | | [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | | [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | | [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | | [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | | [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules (off by default). | | [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | | [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | | [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization (on by default). | | [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | -| `/Zc:tlsGuards[-]` | Generate runtime checks for TLS variable initialization (on by default). | -| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use non-conforming template parsing behavior (conforming by default). | +| [`/Zc:twoPhase[-]`](zc-twophase.md) | Use nonconforming template parsing behavior (conforming by default). | | [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | -| `/Zc:zeroSizeArrayNew[-]` | Call member `new`/`delete` for 0-size arrays of objects (on by default). | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for 0-size arrays of objects (on by default). | | [`/Ze`](za-ze-disable-language-extensions.md) | Deprecated. Enables C89 language extensions. | | [`/Zf`](zf.md) | Improves PDB generation time in parallel builds. | -| [`/ZH:[MD5|SHA1|SHA_256]`](zh.md) | Specifies MD5, SHA-1, or SHA-256 for checksums in debug info. | +| [`/ZH`:[MD5|SHA1|SHA_256|SHA384|SHA512]](zh.md) | Specifies MD5, SHA-1, SHA-256, SHA-38418.6.0, or SHA-51218.6.0 for checksums in debug info. | | [`/ZI`](z7-zi-zi-debug-information-format.md) | Includes debug information in a program database compatible with Edit and Continue. (x86 only) | | [`/Zi`](z7-zi-zi-debug-information-format.md) | Generates complete debugging information. | | [`/Zl`](zl-omit-default-library-name.md) | Removes the default library name from the *`.obj`* file. | | [`/Zo[-]`](zo-enhance-optimized-debugging.md) | Generate richer debugging information for optimized code. | -| [`/Zp[n]`](zp-struct-member-alignment.md) *n* | Packs structure members. | +| [`/Zp[n]`](zp-struct-member-alignment.md) | Packs structure members. | | [`/Zs`](zs-syntax-check-only.md) | Checks syntax only. | | [`/ZW`](zw-windows-runtime-compilation.md) | Produces an output file to run on the Windows Runtime. | +18.6.0 This option is available starting in Visual Studio 2026 version 18.6.0 and MSVC version 14.51. + ## Linking | Option | Purpose | @@ -233,7 +246,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. | @@ -242,7 +255,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. | @@ -255,7 +268,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. | @@ -294,6 +307,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 @@ -302,7 +316,7 @@ Experimental options may only be supported by certain versions of the compiler. |--|--| | [`/clr:noAssembly`](clr-common-language-runtime-compilation.md) | Deprecated. Use [`/LN` (Create MSIL Module)](ln-create-msil-module.md) instead. | | [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. | -| [`/experimental:preprocessor`](experimental-preprocessor.md) | Deprecated. Enables experimental conforming preprocessor support. Use [`/Zc:preprocessor`](zc-preprocessor.md) | +| [`/experimental:preprocessor`](experimental-preprocessor.md) | Deprecated. Enables experimental conforming preprocessor support. Use [`/Zc:preprocessor`](zc-preprocessor.md) instead. | | [`/Fr`](fr-fr-create-dot-sbr-file.md) | Deprecated. Creates a browse information file without local variables. | | [`/Ge`](ge-enable-stack-probes.md) | Deprecated. Activates stack probes. On by default. | | [`/Gm`](gm-enable-minimal-rebuild.md) | Deprecated. Enables minimal rebuild. | @@ -318,6 +332,8 @@ 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.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 6bee6fa00a3..9052345e64e 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 943a29c9168..8883cd8cc71 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 2d60b22066c..566ed5e134c 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. @@ -30,7 +30,13 @@ The output file that you specify in the project has no effect on the name that t ### To create a makefile project in Visual Studio -1. From the Visual Studio main menu, choose **File** > **New** > **Project** and type "makefile" into the search box. If you see more than one project template, select from the options depending on your target platform. +1. From the Visual Studio main menu, choose **File** > **New** > **Project/Solution**. + + :::image type="content" source="media/file-new-project.png" alt-text="Screenshot of the File > New > Project/Solution menu item."::: + +1. Type *makefile* into the search box. If you see more than one project template, select the option for your target platform. + + :::image type="content" source="media/create-project.png" alt-text="Screenshot of the Create a new project dialog. The Create a new project text field text box contains the text: makefile."::: 1. **Windows only**: In the Makefile project **Debug Configuration Settings** page, provide the command, output, clean, and rebuild information for debug and retail builds. Choose **Next** if you want to specify different settings for a Release configuration. diff --git a/docs/build/reference/creating-an-dot-sbr-file.md b/docs/build/reference/creating-an-dot-sbr-file.md index 47312c2da98..37096da3b13 100644 --- a/docs/build/reference/creating-an-dot-sbr-file.md +++ b/docs/build/reference/creating-an-dot-sbr-file.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Creating an .Sbr File" title: "Creating an .Sbr File" +description: "Learn more about: Creating an .Sbr File" ms.date: "11/04/2016" helpviewer_keywords: ["SBR files", "BSCMAKE, input files", ".sbr files", "source browser files", "local symbols in browse information", "symbols"] -ms.assetid: bdb4b93c-a88a-441a-84fd-01087d03be25 --- # Creating an .Sbr File @@ -14,7 +13,7 @@ The input files for BSCMAKE are .sbr files. The compiler creates an .sbr file fo To create an .sbr file with all possible information, specify [/FR](fr-fr-create-dot-sbr-file.md). -To create an .sbr file that doesn't contain local symbols, specify [/Fr](fr-fr-create-dot-sbr-file.md). If the .sbr files contain local symbols, you can still omit them from the .bsc file by using BSCMAKE's [/El option](bscmake-options.md)`.` +To create an .sbr file that doesn't contain local symbols, specify [/Fr](fr-fr-create-dot-sbr-file.md). If the .sbr files contain local symbols, you can still omit them from the .bsc file by using BSCMAKE's [/El option](bscmake-options.md). You can create an .sbr file without performing a full compile. For example, you can specify the /Zs option to the compiler to perform a syntax check and still generate an .sbr file if you specify /FR or /Fr. diff --git a/docs/build/reference/debug-generate-debug-info.md b/docs/build/reference/debug-generate-debug-info.md old mode 100755 new mode 100644 index 7bc0fcc21b0..9716f477b56 --- a/docs/build/reference/debug-generate-debug-info.md +++ b/docs/build/reference/debug-generate-debug-info.md @@ -1,52 +1,52 @@ --- -description: "Learn more about: /DEBUG (Generate Debug Info)" +description: "Learn more about: /DEBUG (Generate debug info)" title: "/DEBUG (Generate Debug Info)" -ms.date: "05/16/2019" +ms.date: 09/08/2025 f1_keywords: ["VC.Project.VCLinkerTool.GenerateDebugInformation", "/debug"] helpviewer_keywords: ["DEBUG linker option", "/DEBUG linker option", "-DEBUG linker option", "PDB files", "debugging [C++], debug information files", "generate debug info linker option", "pdb files, generating debug info", ".pdb files, generating debug info", "debugging [C++], linker option", "program databases [C++]"] ms.assetid: 1af389ae-3f8b-4d76-a087-1cdf861e9103 --- -# /DEBUG (Generate Debug Info) +# `/DEBUG` (Generate debug info) -``` -/DEBUG[:{FASTLINK|FULL|NONE}] -``` +The **`/DEBUG`** linker option creates a debugging information file for the executable. -## Remarks +## Syntax -The **/DEBUG** option creates debugging information for the executable. +> **`/DEBUG`**\[**`:`**{**`FASTLINK`**|**`FULL`**|**`NONE`**}] -The linker puts the debugging information into a program database (PDB) file. It updates the PDB during subsequent builds of the program. +## Remarks -An executable (.exe file or DLL) created for debugging contains the name and path of the corresponding PDB. The debugger reads the embedded name and uses the PDB when you debug the program. The linker uses the base name of the program and the extension .pdb to name the program database, and embeds the path where it was created. To override this default, set [/PDB](pdb-use-program-database.md) and specify a different file name. +The **`/DEBUG`** option puts the debugging information from linked object and library files into a program database (PDB) file. It updates the PDB during subsequent builds of the program. -The **/DEBUG:FASTLINK** option is available in Visual Studio 2017 and later. This option leaves private symbol information in the individual compilation products used to build the executable. It generates a limited PDB that indexes into the debug information in the object files and libraries used to build the executable instead of making a full copy. This option can link from two to four times as fast as full PDB generation, and is recommended when you are debugging locally and have the build products available. This limited PDB can't be used for debugging when the required build products are not available, such as when the executable is deployed on another computer. In a developer command prompt, you can use the mspdbcmf.exe tool to generate a full PDB from this limited PDB. In Visual Studio, use the Project or Build menu items for generating a full PDB file to create a full PDB for the project or solution. +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:FULL** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. +> [!Note] +> The **`/DEBUG:FASTLINK`** option is **deprecated and removed** starting in Visual Studio 2026. It was available in Visual Studio 2017 through Visual Studio 2022. -The **/DEBUG:NONE** option does not generate a PDB. +**`/DEBUG:FASTLINK`** generated 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, and is removed in Visual Studio 2026. Prefer using **`/DEBUG:FULL`**. -When you specify **/DEBUG** with no additional options, the linker defaults to **/DEBUG:FULL** for command line and makefile builds, for release builds in the Visual Studio IDE, and for both debug and release builds in Visual Studio 2015 and earlier versions. Beginning in Visual Studio 2017, the build system in the IDE defaults to **/DEBUG:FASTLINK** when you specify the **/DEBUG** option for debug builds. Other defaults are unchanged to maintain backward compatibility. +A **`/DEBUG:FASTLINK`** PDB can be converted to a full PDB that you can deploy to a test machine for local debugging. In Visual Studio, use the **Property Pages** dialog as described below to create a full PDB for the project or solution. In a developer command prompt, you can use the `mspdbcmf.exe` tool to create a full PDB. -The compiler's [C7 Compatible](z7-zi-zi-debug-information-format.md) (/Z7) option causes the compiler to leave the debugging information in the .obj files. You can also use the [Program Database](z7-zi-zi-debug-information-format.md) (/Zi) compiler option to store the debugging information in a PDB for the .obj file. The linker looks for the object's PDB first in the absolute path written in the .obj file, and then in the directory that contains the .obj file. You cannot specify an object's PDB file name or location to the linker. +The **`/DEBUG:FULL`** option moves all private symbol information from individual compilation products (object files and libraries) into a single PDB, and can be the most time-consuming part of the link. However, the full PDB can be used to debug the executable when no other build products are available, such as when the executable is deployed. -[/INCREMENTAL](incremental-link-incrementally.md) is implied when /DEBUG is specified. +The **`/DEBUG:NONE`** option doesn't generate a PDB. -/DEBUG changes the defaults for the [/OPT](opt-optimizations.md) option from REF to NOREF and from ICF to NOICF, so if you want the original defaults, you must explicitly specify /OPT:REF or /OPT:ICF. +Specifying **`/DEBUG`** with no extra arguments is equivalent to specifying **`/DEBUG:FULL`**. -It is not possible to create an .exe or .dll that contains debug information. Debug information is always placed in a .obj or .pdb file. +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. -### To set this linker option in the Visual Studio development environment +[`/INCREMENTAL`](incremental-link-incrementally.md) is implied when **`/DEBUG`** is specified. -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). +**`/DEBUG`** changes the defaults for the [`/OPT`](opt-optimizations.md) option from **`REF`** to **`NOREF`** and from **`ICF`** to **`NOICF`**, so if you want the original defaults, you must explicitly specify **`/OPT:REF`** or **`/OPT:ICF`** after the **`/DEBUG`** option. -1. Click the **Linker** folder. +It isn't possible to create an EXE or DLL that contains debug information. Debug information is always placed in an OBJ or PDB file. -1. Click the **Debugging** property page. - -1. Modify the **Generate Debug Info** property to enable PDB generation. This enables /DEBUG:FASTLINK by default in Visual Studio 2017 and later. +### To set this linker option in the Visual Studio development environment -1. Modify the **Generate Full Program Database File** property to enable /DEBUG:FULL for full PDB generation for every incremental build. +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. +1. Modify the **Generate Debug Info** property to enable or disable PDB generation. This property enables **`/DEBUG:FASTLINK`** by default in Visual Studio 2017 and later. +1. Modify the **Generate Full Program Database File** property to enable **`/DEBUG:FULL`** for full PDB generation for every incremental build. ### To set this linker option programmatically @@ -54,5 +54,5 @@ It is not possible to create an .exe or .dll that contains debug information. De ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/decorated-names.md b/docs/build/reference/decorated-names.md index 6370302c0d6..4b5a674a640 100644 --- a/docs/build/reference/decorated-names.md +++ b/docs/build/reference/decorated-names.md @@ -53,10 +53,11 @@ The form of decoration for a C function depends on the calling convention used i | Calling convention | Decoration | |--|--| -| **`__cdecl`** | Leading underscore (**`_`**) | -| **`__stdcall`** | Leading underscore (**`_`**) and a trailing at sign (**`@`**) followed by the number of bytes in the parameter list in decimal | -| **`__fastcall`** | Leading and trailing at signs (**`@`**) followed by a decimal number representing the number of bytes in the parameter list | -| **`__vectorcall`** | Two trailing at signs (**`@@`**) followed by a decimal number of bytes in the parameter list | +| [**`__cdecl`**](../../cpp/cdecl.md) | Leading underscore (**`_`**) | +| [**`__stdcall`**](../../cpp/stdcall.md) | Leading underscore (**`_`**) and a trailing at sign (**`@`**) followed by the number of bytes in the parameter list in decimal | +| [**`__fastcall`**](../../cpp/fastcall.md) | Leading and trailing at signs (**`@`**) followed by a decimal number representing the number of bytes in the parameter list | +| [**`__vectorcall`**](../../cpp/vectorcall.md) | Two trailing at signs (**`@@`**) followed by a decimal number of bytes in the parameter list | +| [**`__preserve_none`**](../../cpp/preserve-none.md) | Two trailing at signs, an underscore and the 'A' character (**`@@_A`**) | For ARM64EC functions with C linkage (whether compiled as C or by using `extern "C"`), a **`#`** is prepended to the decorated name. diff --git a/docs/build/reference/def-specify-module-definition-file.md b/docs/build/reference/def-specify-module-definition-file.md index ad5e6a38fad..42e938c3ff6 100644 --- a/docs/build/reference/def-specify-module-definition-file.md +++ b/docs/build/reference/def-specify-module-definition-file.md @@ -1,37 +1,34 @@ --- -description: "Learn more about: /DEF (Specify Module-Definition File)" -title: "/DEF (Specify Module-Definition File)" -ms.date: "11/04/2016" +description: "Learn more about: /DEF (Specify module-definition file)" +title: "/DEF (Specify module-definition file)" +ms.date: 03/27/2025 f1_keywords: ["VC.Project.VCLinkerTool.ModuleDefinitionFile", "/def"] helpviewer_keywords: ["module definition files, specifying", "DEF linker option", "-DEF linker option", "module definition files", "/DEF linker option"] -ms.assetid: 6497fa68-65f0-48ca-8f66-b87166fc631a --- -# /DEF (Specify Module-Definition File) +# `/DEF` (Specify module-definition file) -``` -/DEF:filename -``` +Specifies a module-definition file to the linker. -## Arguments +## Syntax -*filename*
-The name of a module-definition file (.def) to be passed to the linker. +> **`/DEF:`***`filename`* -## Remarks +## Arguments -The /DEF option passes a module-definition file (.def) to the linker. Only one .def file can be specified to LINK. For details about .def files, see [Module-Definition Files](module-definition-dot-def-files.md). +*`filename`*\ +The name of a module-definition file (*`.def`*) to be passed to the linker. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). -### To set this linker option in the Visual Studio development environment - -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +## Remarks -1. Click the **Linker** folder. +The **`/DEF`** linker option passes a module-definition file (*`.def`*) to the linker. Only one *`.def`* file can be specified to LINK. For details about *`.def`* files, see [Module-definition files](module-definition-dot-def-files.md). -1. Click the **Input** property page. +To specify a *`.def`* file from within the development environment, add it to the project along with your other source files and then specify the file in the project's **Property Pages** dialog. -1. Modify the **Module Definition File** property. +### To set this linker option in the Visual Studio development environment -To specify a .def file from within the development environment, you should add it to the project along with other files and then specify the file to the /DEF option. +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **Input** property page. +1. Modify the **Module Definition File** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -39,5 +36,5 @@ To specify a .def file from within the development environment, you should add i ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/defining-an-nmake-macro.md b/docs/build/reference/defining-an-nmake-macro.md index e503302651e..dd09538893e 100644 --- a/docs/build/reference/defining-an-nmake-macro.md +++ b/docs/build/reference/defining-an-nmake-macro.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Defining an NMAKE Macro" title: "Define an NMAKE Macro" +description: "Learn more about: Defining an NMAKE Macro" ms.date: 09/30/2021 helpviewer_keywords: ["macros, NMAKE", "defining NMAKE macros", "NMAKE macros, defining", "defining macros", "NMAKE program, defining macros", "NMAKE program, undefined macros", "Null macros in NMAKE", "macros, null and undefined", "undefined macros and NMAKE", "NMAKE program, null macros", "special characters, in NMAKE macros"] --- @@ -16,7 +16,7 @@ The *macro_name* is a case-sensitive combination of letters, digits, and undersc The *string* can be any sequence of zero or more characters. A *null* string contains zero characters or only spaces or tabs. The *string* can contain a macro invocation. -## Special characters in macros +## Special characters in macros A number sign (**`#`**) after a definition specifies a comment. To specify a literal number sign in a macro, use a caret (**`^`**) to escape it, as in **`^#`**. @@ -31,11 +31,11 @@ CMDS = cls^ dir ``` -## Null and undefined macros +## Null and undefined macros Both null and undefined macros expand to null strings, but a macro defined as a null string is considered defined in preprocessing expressions. To define a macro as a null string, specify no characters except spaces or tabs after the equal sign (**`=`**) in a command line or command file, and enclose the null string or definition in double quotation marks (**`" "`**). To undefine a macro, use **`!UNDEF`**. For more information, see [Makefile preprocessing directives](makefile-preprocessing.md#makefile-preprocessing-directives). -## Where to define macros +## Where to define macros Define macros in a command line, command file, makefile, or the *`Tools.ini`* file. @@ -43,7 +43,7 @@ In a makefile or the *`Tools.ini`* file, each macro definition must appear on a In a command line or command file, spaces and tabs delimit arguments and can't surround the equal sign. If *string* has embedded spaces or tabs, enclose either the string itself or the entire macro in double quotation marks (**`" "`**). -## Precedence in macro definitions +## Precedence in macro definitions If a macro has multiple definitions, NMAKE uses the highest-precedence definition. The following list shows the order of precedence, from highest to lowest: diff --git a/docs/build/reference/delay-delay-load-import-settings.md b/docs/build/reference/delay-delay-load-import-settings.md index 07856d7724f..a1054d65b84 100644 --- a/docs/build/reference/delay-delay-load-import-settings.md +++ b/docs/build/reference/delay-delay-load-import-settings.md @@ -1,8 +1,8 @@ --- description: "Learn more about: /DELAY (Delay load import settings)" title: "/DELAY (Delay load import settings)" -ms.date: 01/28/2021 -f1_keywords: ["/delay", "VC.Project.VCLinkerTool.DelayNoBind", "VC.Project.VCLinkerTool.SupportUnloadOfDelayLoadedDLL", "VC.Project.VCLinkerTool.DelayUnload"] +ms.date: 09/19/2022 +f1_keywords: ["/delay", "VC.Project.VCLinkerTool.DelayNoBind", "VC.Project.VCLinkerTool.SupportUnloadOfDelayLoadedDLL", "VC.Project.VCLinkerTool.DelayUnload", "VC.Project.VCLinkerTool.SupportNobindOfDelayLoadedDLL"] helpviewer_keywords: ["delayed loading of DLLs, /DELAY option", "DELAY linker option", "/DELAY linker option", "-DELAY linker option"] --- # `/DELAY` (Delay load import settings) @@ -32,15 +32,15 @@ To specify DLLs to delay load, use the [`/DELAYLOAD`](delayload-delay-load-impor ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Modify the **Delay Loaded DLL** property. Choose **OK** to save your changes. +1. Modify the **Unload delay loaded DLL** property or the **Unbind delay loaded DLL** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -- See . +- See . ## See also diff --git a/docs/build/reference/description-blocks.md b/docs/build/reference/description-blocks.md index 6175063ce7b..3f457021464 100644 --- a/docs/build/reference/description-blocks.md +++ b/docs/build/reference/description-blocks.md @@ -156,7 +156,7 @@ In this example, UPDATE is a pseudotarget. ```makefile UPDATE : *.* -!COPY $** c:\product\release +COPY $** c:\product\release ``` When UPDATE is evaluated, NMAKE copies all files in the current directory to the specified drive and directory. diff --git a/docs/build/reference/dot-ilk-files-as-linker-input.md b/docs/build/reference/dot-ilk-files-as-linker-input.md index e53baf1be62..5e5e761ff8a 100644 --- a/docs/build/reference/dot-ilk-files-as-linker-input.md +++ b/docs/build/reference/dot-ilk-files-as-linker-input.md @@ -1,15 +1,19 @@ --- -description: "Learn more about: .Ilk Files as Linker Input" -title: ".Ilk Files as Linker Input" -ms.date: "11/04/2016" -helpviewer_keywords: ["ILK files", ".ilk files"] +description: "Learn more about: .ilk files as linker input" +title: ".ilk files as linker input" +ms.date: 09/07/2022 +helpviewer_keywords: [".ilk files", ".ilk files"] ms.assetid: 7324c104-9e5d-423d-b268-b59f92607bf2 --- -# .Ilk Files as Linker Input +# `.ilk` files as linker input -When linking incrementally, LINK updates the .ilk status file that it created during the first incremental link. This file has the same base name as the .exe file or the .dll file, and it has the extension .ilk. During subsequent incremental links, LINK updates the .ilk file. If the .ilk file is missing, LINK performs a full link and creates a new .ilk file. If the .ilk file is unusable, LINK performs a nonincremental link. For details about incremental linking, see the [Link Incrementally (/INCREMENTAL)](incremental-link-incrementally.md) option. +The linker creates and uses a *`.ilk`* database file for incremental link information. + +## Remarks + +When linking incrementally, LINK updates the *`.ilk`* status file that it created during the first incremental link. This file has the same base name as the target EXE or DLL file, and it has the extension *`.ilk`*. During subsequent incremental links, LINK updates the *`.ilk`* file. If the *`.ilk`* file is missing, LINK performs a full link and creates a new *`.ilk`* file. If the *`.ilk`* file is unusable, LINK performs a non-incremental link. For more information about incremental linking, see the [`/INCREMENTAL` (Link incrementally)](incremental-link-incrementally.md) linker option. For information about how to specify the name and location of the file, see [`/ILK` (Name incremental database file)](./ilk-name-incremental-database-file.md). ## See also -[LINK Input Files](link-input-files.md)
-[MSVC Linker Options](linker-options.md) +[LINK input files](link-input-files.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dot-lib-files-as-linker-input.md b/docs/build/reference/dot-lib-files-as-linker-input.md index dc12e4a0bb8..875c8694c9a 100644 --- a/docs/build/reference/dot-lib-files-as-linker-input.md +++ b/docs/build/reference/dot-lib-files-as-linker-input.md @@ -1,32 +1,36 @@ --- -description: "Learn more about: .Lib Files as Linker Input" -title: ".Lib Files as Linker Input" -ms.date: "11/04/2016" +description: "Learn more about: .lib files as linker input" +title: ".lib files as linker input" +ms.date: 09/09/2022 f1_keywords: ["VC.Project.VCLinkerTool.AdditionalDependencies"] helpviewer_keywords: ["OMF libraries", "linking [C++], OMF libraries", "import libraries, linker files", "libraries [C++], .lib files as linker input", "COFF files, import libraries", "default libraries [C++], linker output", "default libraries [C++]", "defaults [C++], libraries", ".lib files"] ms.assetid: dc5d2b1c-2487-41fa-aa71-ad1e0647958b --- -# .Lib Files as Linker Input +# `.lib` files as linker input -LINK accepts COFF standard libraries and COFF import libraries, both of which usually have the extension .lib. Standard libraries contain objects and are created by the LIB tool. Import libraries contain information about exports in other programs and are created either by LINK when it builds a program that contains exports or by the LIB tool. For information on using LIB to create standard or import libraries, see [LIB Reference](lib-reference.md). For details on using LINK to create an import library, see the [/DLL](dll-build-a-dll.md) option. +LINK accepts COFF standard libraries and COFF import libraries, both of which usually have the extension *`.lib`*. Standard libraries contain objects and are created by the LIB tool. Import libraries contain information about exports in other programs and are created either by LINK when it builds a program that contains exports or by the LIB tool. For information on using LIB to create standard or import libraries, see [LIB Reference](lib-reference.md). For details on using LINK to create an import library, see the [`/DLL`](dll-build-a-dll.md) option. -A library is specified to LINK as either a file name argument or a default library. LINK resolves external references by searching first in libraries specified on the command line, then in default libraries specified with the [/DEFAULTLIB](defaultlib-specify-default-library.md) option, and then in default libraries named in .obj files. If a path is specified with the library name, LINK looks for the library in that directory. If no path is specified, LINK looks first in the directory that LINK is running from, and then in any directories specified in the LIB environment variable. +A library is specified to LINK as either a file name argument or a default library. LINK resolves external references by searching first in libraries specified on the command line, then in default libraries specified with the [`/DEFAULTLIB`](defaultlib-specify-default-library.md) option, and then in default libraries named in *`.obj`* files. If a path is specified with the library name, LINK looks for the library in that directory. If no path is specified, LINK looks first in the directory that LINK is running from, and then in any directories specified in the `LIB` environment variable. -## To add .lib files as linker input in the development environment +## To add `.lib` files as linker input in the development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Input** property page in the **Linker** folder. +1. Choose the **Configuration Properties** > **Linker** > **Input** property page. -1. Modify the **Additional Dependencies** property to add the .lib files. +1. Modify the **Additional Dependencies** property to add the *`.lib`* files. -## To programmatically add .lib files as linker input +1. Choose **OK** or **Apply** to save your changes. -- See [AdditionalDependencies](/dotnet/api/microsoft.visualstudio.vcprojectengine.vclinkertool.additionaldependencies). +## To programmatically add `.lib` files as linker input + +- See . ## Example -The following sample shows how to build and use a .lib file. First, build a .lib file: +The following sample shows how to build and use a *`.lib`* file. + +First, build the *`.lib`* file: ```cpp // lib_link_input_1.cpp @@ -36,7 +40,7 @@ __declspec(dllexport) int Test() { } ``` -And then, compile this sample by using the .lib file you just created: +And then, compile this sample by using the *`.lib`* file you just created: ```cpp // lib_link_input_2.cpp @@ -54,5 +58,5 @@ int main() { ## See also -[LINK Input Files](link-input-files.md)
-[MSVC Linker Options](linker-options.md) +[LINK input files](link-input-files.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/dumpbin-options.md b/docs/build/reference/dumpbin-options.md index 2bedc34b9e1..71bd3a9c66a 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 00000000000..6d4602acfc5 --- /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 00000000000..33edd942e31 --- /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/e-preprocess-to-stdout.md b/docs/build/reference/e-preprocess-to-stdout.md index c2e2f9d98f1..7426af03468 100644 --- a/docs/build/reference/e-preprocess-to-stdout.md +++ b/docs/build/reference/e-preprocess-to-stdout.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /E (Preprocess to stdout)" title: "/E (Preprocess to stdout)" -ms.date: "11/04/2016" +description: "Learn more about: /E (Preprocess to stdout)" +ms.date: 11/04/2016 f1_keywords: ["/e"] helpviewer_keywords: ["-E compiler option [C++]", "/E compiler option [C++]", "preprocessor output, copy to stdout", "preprocessor output"] -ms.assetid: ddbb1725-d950-4978-ab2f-30a5cd7b778c --- # /E (Preprocess to stdout) @@ -44,7 +43,7 @@ m(int)main( ) However, if you compile with: -``` +```cmd cl -E test.cpp > test2.cpp ``` @@ -66,7 +65,7 @@ cl -E test.cpp > test2.cpp The following command line preprocesses `ADD.C`, preserves comments, adds `#line` directives, and displays the result on the standard output device: -``` +```cmd CL /E /C ADD.C ``` diff --git a/docs/build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md b/docs/build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md index 0c1deff9db2..61d030c0814 100644 --- a/docs/build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md +++ b/docs/build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /EP (Preprocess to stdout Without #line Directives)" title: "/EP (Preprocess to stdout Without #line Directives)" -ms.date: "11/04/2016" +description: "Learn more about: /EP (Preprocess to stdout Without #line Directives)" +ms.date: 11/04/2016 f1_keywords: ["/ep", "VC.Project.VCCLCompilerTool.GeneratePreprocessedFileNoLines"] helpviewer_keywords: ["copy preprocessor output to stdout", "preprocessor output, copy to stdout", "-EP compiler option [C++]", "EP compiler option [C++]", "/EP compiler option [C++]"] -ms.assetid: 6ec411ae-e33d-4ef5-956e-0054635eabea --- # /EP (Preprocess to stdout Without #line Directives) @@ -46,7 +45,7 @@ You cannot use precompiled headers with the **/EP** option. The following command line preprocesses file `ADD.C`, preserves comments, and displays the result on the standard output device: -``` +```cmd CL /EP /C ADD.C ``` 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 1bfa82a706b..2d67217025f 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 00000000000..413151fd864 --- /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 bd1c16ed79e..bfbcec74a89 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/fd-program-database-file-name.md b/docs/build/reference/fd-program-database-file-name.md index 7bc387dcf56..c9027012f28 100644 --- a/docs/build/reference/fd-program-database-file-name.md +++ b/docs/build/reference/fd-program-database-file-name.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /Fd (Program Database File Name)" title: "/Fd (Program Database File Name)" -ms.date: "11/04/2016" +description: "Learn more about: /Fd (Program Database File Name)" +ms.date: 11/04/2016 f1_keywords: ["/FD", "VC.Project.VCCLWCECompilerTool.ProgramDataBaseFileName", "VC.Project.VCCLCompilerTool.ProgramDataBaseFileName"] helpviewer_keywords: ["/FD compiler option [C++]", "program database file name [C++]", "-FD compiler option [C++]", "PDB files, creating", "program database compiler option [C++]", ".pdb files, creating", "FD compiler option [C++]"] -ms.assetid: 3977a9ed-f0ac-45df-bf06-01cedd2ba85a --- # /Fd (Program Database File Name) @@ -42,7 +41,7 @@ This option also names the state (.idb) file used for minimal rebuild and increm This command line creates a .pdb file named PROG.pdb and an .idb file named PROG.idb: -``` +```cmd CL /DDEBUG /Zi /FdPROG.PDB PROG.CPP ``` diff --git a/docs/build/reference/fe-name-exe-file.md b/docs/build/reference/fe-name-exe-file.md index 3defab99e37..02c71317a58 100644 --- a/docs/build/reference/fe-name-exe-file.md +++ b/docs/build/reference/fe-name-exe-file.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /Fe (Name EXE File)" title: "/Fe (Name EXE File)" -ms.date: "11/04/2016" +description: "Learn more about: /Fe (Name EXE File)" +ms.date: 11/04/2016 f1_keywords: ["/fe"] helpviewer_keywords: ["-Fe compiler option [C++]", "executable files, renaming", "rename file compiler option [C++]", "/Fe compiler option [C++]", "Fe compiler option [C++]"] -ms.assetid: 49f594fd-5e94-45fe-a1bf-7c9f2abb6437 --- # /Fe (Name EXE File) @@ -44,13 +43,13 @@ If you specify the [/c (Compile Without Linking)](c-compile-without-linking.md) The following command line compiles and links all C source files in the current directory. The resulting executable file is named PROCESS.exe and is created in the directory "C:\Users\User Name\repos\My Project\bin". -``` +```cmd CL /Fe"C:\Users\User Name\repos\My Project\bin\PROCESS" *.C ``` The following command line creates an executable file in `C:\BIN` with the same base name as the first source file in the current directory: -``` +```cmd CL /FeC:\BIN\ *.C ``` diff --git a/docs/build/reference/feature-arm64.md b/docs/build/reference/feature-arm64.md new file mode 100644 index 00000000000..2954b4fed11 --- /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/feature-enable-architecture-features.md b/docs/build/reference/feature-enable-architecture-features.md new file mode 100644 index 00000000000..b9ca7324c68 --- /dev/null +++ b/docs/build/reference/feature-enable-architecture-features.md @@ -0,0 +1,23 @@ +--- +description: "Learn more about: /feature (Enable architecture features)" +title: "/feature (Enable architecture features)" +ms.date: 05/11/2026 +f1_keywords: ["/feature"] +helpviewer_keywords: ["-feature compiler option [C++]", "/feature compiler option [C++]", "feature compiler option [C++]"] +--- +# `/feature` (Enable architecture features) + +The **`/feature`** option enables specific architecture features for code generation. Select the target platform you're working with to see **`/feature`** options for that platform. + +- [`/feature` (ARM64)](feature-arm64.md)17.10 + +- [`/feature` (x64)](feature-x64.md)14.51 + +17.10 This option is available starting in Visual Studio 2022 version 17.10.\ +14.51 This option ships with MSVC Build Tools version 14.51. Available as part of Visual Studio starting with version 18.6. + +## 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/feature-x64.md b/docs/build/reference/feature-x64.md new file mode 100644 index 00000000000..676648ce4b5 --- /dev/null +++ b/docs/build/reference/feature-x64.md @@ -0,0 +1,57 @@ +--- +description: "Learn more about: /feature (x64)" +title: "/feature (x64)" +ms.date: 05/21/2026 +--- +# `/feature` (x64) + +Enable one or more architecture features for x64 code generation. + +> [!NOTE] +> **`/feature:APX`** support is experimental and subject to change. + +## Syntax + +> **`/feature:`** + +## Arguments + +To enable one or more features the x64 target supports, specify one or more of the following feature arguments: + +| Feature argument | Description | Supported in version | +|--|--|--| +| **`APX`** | Enables preview support for Intel APX (Advanced Performance Extensions). Enables the compiler to target various APX features like Extended General-Purpose Registers (EGPRs), New Data Destination (NDD), No-Flags Update (NF), new conditional ISA and optimized registers save/restore operations. For more information, see [Intel Advanced Performance Extensions (APX)](https://www.intel.com/content/www/us/en/developer/articles/technical/advanced-performance-extensions-apx.html). | MSVC Build Tools 14.51 (Preview Support) | + +## Remarks + +Example usage: to enable APX, specify **`/feature:APX`**. + +When **`/feature:APX`** is specified, the following preprocessor macros are defined: `__APX_F__`, `__CCMP__`, `__CF__`, `__EGPR__`, `__NDD__`, `__NF__`, `__PPX__`, `__PUSH2POP2__`, and `__ZU__`. For more information, see [Microsoft-specific predefined macros](../../preprocessor/predefined-macros.md). + +APX extends the x64 architecture with new registers and instructions, which affects how the compiler generates calls, preserves state across function boundaries, and emits unwind metadata. The following articles describe the x64 conventions and unwind information related to APX: + +- [Caller/callee saved registers](../x64-calling-convention.md#callercallee-saved-registers)\ + Describes which registers a callee must preserve and which the caller is responsible for saving across a call on x64. +- [setjmp/longjmp](../x64-calling-convention.md#setjmplongjmp)\ + Explains how nonlocal jumps capture and restore nonvolatile register state on x64, including the registers that participate in the jump buffer. +- [Register volatility and preservation](../x64-software-conventions.md#register-volatility-and-preservation)\ + Summarizes the x64 software conventions for volatile and nonvolatile general-purpose, `XMM`, `YMM`, and `ZMM` registers, and the rules callees must follow to preserve them. +- [Exception handling unwind information V3](../x64-unwind-information-v3.md)\ + Preview specification of the V3 unwind information format used to describe prologs, epilogs, and frame layout for x64 code, including the extended state introduced by APX. + +### 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:APX`*. Choose **OK** to save your changes. + +### To set this compiler option programmatically + +- See . + +## See also + +[`/arch` (x64)](arch-x64.md)\ +[`/arch` (Minimum CPU architecture)](arch-minimum-cpu-architecture.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/filealign.md b/docs/build/reference/filealign.md index 31f8c859d1c..1e794ab0e11 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/files-created-for-clr-projects.md b/docs/build/reference/files-created-for-clr-projects.md index 8864195572c..1aa648278b1 100644 --- a/docs/build/reference/files-created-for-clr-projects.md +++ b/docs/build/reference/files-created-for-clr-projects.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Files Created for CLR Projects" title: "Files Created for CLR Projects" -ms.date: "11/04/2016" +description: "Learn more about: Files Created for CLR Projects" +ms.date: 11/04/2016 helpviewer_keywords: ["Visual Studio C++ projects, CLR programming", ".NET applications, C++"] -ms.assetid: 59ae9020-5f26-4ad0-bbdd-97c2e2023a20 --- # Files Created for CLR Projects @@ -11,7 +10,7 @@ When you use Visual C++ templates to create your projects, several files are cre |File name|File description| |---------------|----------------------| -|AssemblyInfo.cpp|The file that contains information (that is, attributes, files, resources, types, versioning information, signing information, and so on) for modifying the project's assembly metadata. For more information see [Assembly Concepts](/dotnet/framework/app-domains/assembly-contents).| +|AssemblyInfo.cpp|The file that contains information (that is, attributes, files, resources, types, versioning information, signing information, and so on) for modifying the project's assembly metadata. For more information, see [Assembly Concepts](/dotnet/framework/app-domains/assembly-contents).| |*projname*.asmx|A text file that references managed classes that encapsulate the functionality of the XML Web service.| |*projname*.cpp|The main source file and entry point into the application that Visual Studio created for you. Identifies the project .dll file and the project namespace. Provide your own code in this file.| |*projname*.vsdisco|An XML deployment file containing links to other resources that describe the XML Web service.| diff --git a/docs/build/reference/fo-object-file-name.md b/docs/build/reference/fo-object-file-name.md index ea784342979..a0be19b4475 100644 --- a/docs/build/reference/fo-object-file-name.md +++ b/docs/build/reference/fo-object-file-name.md @@ -1,35 +1,47 @@ --- title: "/Fo (Object file name)" description: "Reference guide to the Microsoft C++ /Fo (Object file name) compiler option in Visual Studio." -ms.date: "04/20/2020" +ms.date: 01/29/2024 f1_keywords: ["/Fo", "VC.Project.VCCLCompilerTool.ObjectFile", "VC.Project.VCCLWCECompilerTool.ObjectFile"] helpviewer_keywords: ["Fo compiler option [C++]", "object files, naming", "/Fo compiler option [C++]", "-Fo compiler option [C++]"] -ms.assetid: 0e6d593e-4e7f-4990-9e6e-92e1dcbcf6e6 --- -# /Fo (Object File Name) +# `/Fo` (Object File Name) Specifies an object (*`.obj`*) file name or directory to be used instead of the default. ## Syntax -> **`/Fo`**_pathname_ +> **`/Fo"pathname"`**\ +> **`/Fo:[ ]"pathname"`** ## Remarks -You can use the **`/Fo`** compiler option to set an output directory for all the object files generated by the CL compiler command. Or, you can use it to rename a single object file. +You can use the **`/Fo`** compiler option to set an output directory for all the object files generated by the CL compiler command. Or, you can use it to rename a single object file. Don't put a space between the **`/Fo`** option and the *`pathname`* argument. By default, the object files generated by the compiler are placed in the current directory. They're given the base name of the source file and a *`.obj`* extension. -To use the **`/Fo`** option to rename an object file, specify the output filename as the *pathname* argument. When you rename an object file, you can use any name and extension you want, but the recommended convention is to use *`.obj`*. The compiler generates command line error D8036 if you specify a filename to **`/Fo`** when you've specified more than one source file to compile. +To use the **`/Fo`** option to rename an object file, specify the output filename as the *`pathname`* argument. When you rename an object file, you can use any name and extension you want, but the recommended convention is to use an *`.obj`* extension. The compiler generates command line error D8036 if you specify a filename to **`/Fo`** when you've specified more than one source file to compile. -To use the **`/Fo`** option to set an output directory for all object files created by the CL command, specify the directory as the *pathname* argument. A directory is indicated by a trailing slash in the *pathname* argument. The specified directory must exist; it's not created automatically. +To use the **`/Fo`** option to set an output directory for all object files created by the CL command, specify the directory as the *`pathname`* argument. A directory is indicated by a trailing slash or backslash in the *`pathname`* argument. Use an escaped backslash (a double backslash), if you're using a quoted path. The directory path can be absolute, or relative to the source directory. The specified directory must exist, or the compiler reports error D8003. The directory isn't created automatically. ## Example -The following command line creates an object file named *sample.obj* in an existing directory, *\\intermediate*, on drive D. +This command line demonstrates the format that allows for an optional space between the `/Fo` option and the *`pathname`* argument. It creates an object file named *`test.obj`* in the current directory. ```cmd -CL /Fo"D:\intermediate\" /EHsc /c sample.cpp +CL /Fo: "test" /EHsc /c sample1.cpp +``` + +The following command line creates object files named *`sample1.obj`* and *`sample2.obj`* in an existing directory, *`D:\intermediate\`*. It uses escaped backslash characters as path segment separators in a quoted path: + +```cmd +CL /Fo"D:\\intermediate\\" /EHsc /c sample1.cpp sample2.cpp +``` + +This command line creates object files named *`sample1.obj`* and *`sample2.obj`* in an existing directory, *`output\`*, relative to the source directory. + +```cmd +CL /Fooutput\ /EHsc /c sample1.cpp sample2.cpp ``` ## Set the option in Visual Studio or programmatically @@ -40,7 +52,7 @@ CL /Fo"D:\intermediate\" /EHsc /c sample.cpp 1. Select the **Configuration Properties** > **C/C++** > **Output Files** property page. -1. Modify the **Object File Name** property to set the output directory. In the IDE, the object file must have an extension of *`.obj`*. +1. Modify the **Object File Name** property to set the output directory. In the IDE, the object files must have an extension of *`.obj`*. ### To set this compiler option programmatically @@ -48,7 +60,7 @@ CL /Fo"D:\intermediate\" /EHsc /c sample.cpp ## See also -[Output-File (/F) Options](output-file-f-options.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[Specifying the Pathname](specifying-the-pathname.md) +[Output-file (`/F`) options](output-file-f-options.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[Specifying the pathname](specifying-the-pathname.md) diff --git a/docs/build/reference/force-force-file-output.md b/docs/build/reference/force-force-file-output.md index 1e013395bba..0df90153e1e 100644 --- a/docs/build/reference/force-force-file-output.md +++ b/docs/build/reference/force-force-file-output.md @@ -1,44 +1,45 @@ --- -description: "Learn more about: /FORCE (Force File Output)" -title: "/FORCE (Force File Output)" -ms.date: "07/19/2019" -f1_keywords: ["VC.Project.VCLinkerTool.ForceLink", "/force"] +description: "Learn more about: /FORCE (Force file output)" +title: "/FORCE (Force file output)" +ms.date: 09/08/2022 +f1_keywords: ["VC.Project.VCLinkerTool.ForceFileOutput", "VC.Project.VCLinkerTool.ForceLink", "/force"] helpviewer_keywords: ["FORCE linker option", "file output in linker", "/FORCE linker option", "-FORCE linker option"] ms.assetid: b1e9a218-a5eb-4e60-a4a4-65b4be15e5da --- -# /FORCE (Force File Output) +# `/FORCE` (Force file output) -``` -/FORCE:[MULTIPLE|UNRESOLVED] -``` +Tells the linker to create an executable even if symbols are undefined or multiply defined. -## Remarks +## Syntax -The /FORCE option tells the linker to create a valid .exe file or DLL even if a symbol is referenced but not defined or is multiply defined. +> **`/FORCE`**\[**`:MULTIPLE`**\|**`:UNRESOLVED`**] -The /FORCE option can take an optional argument: +## Remarks -- Use /FORCE:MULTIPLE to create an output file whether or not LINK finds more than one definition for a symbol. +The **`/FORCE`** linker option tells the linker to create an executable image (EXE file or DLL) even if a symbol is referenced but not defined or is defined more than once. -- Use /FORCE:UNRESOLVED to create an output file whether or not LINK finds an undefined symbol. /FORCE:UNRESOLVED is ignored if the entry point symbol is unresolved. +> [!IMPORTANT] +> The **`/FORCE`** option can create an executable that crashes or misbehaves at runtime if it references an undefined symbol or, when a multiply defined symbol has different definitions, if it invokes an unexpected definition in context. -/FORCE with no arguments implies both multiple and unresolved. +The **`/FORCE`** option can take an optional argument: -A file created with this option may not run as expected. The linker will not link incrementally when the /FORCE option is specified. +- Use **`/FORCE:MULTIPLE`** to create an output file whether or not LINK finds more than one definition for a symbol. -If a module is compiled with **/clr**, **/FORCE** will not create an image. +- Use **`/FORCE:UNRESOLVED`** to create an output file whether or not LINK finds an undefined symbol. **`/FORCE:UNRESOLVED`** is ignored if the entry point symbol is unresolved. -### To set this linker option in the Visual Studio development environment +**`/FORCE`** with no arguments implies both **`/FORCE:MULTIPLE`** and **`/FORCE:UNRESOLVED`**. -1. Right-click on the project in **Solution Explorer** and choose **Properties**. +The linker won't link incrementally when the **`/FORCE`** option is specified. -1. Click the **Linker** folder. +If a module is compiled with **`/clr`**, the linker ignores the **`/FORCE`** option. + +### To set this linker option in the Visual Studio development environment -1. Click the **Command Line** property page. +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Type the option into the **Additional Options** box. +1. Select the **Configuration Properties** > **Linker** > **General** property page. -For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Modify the **Force File Output** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -46,5 +47,5 @@ For more information, see [Set C++ compiler and build properties in Visual Studi ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/force-interlocked-functions.md b/docs/build/reference/force-interlocked-functions.md new file mode 100644 index 00000000000..be8e5769db8 --- /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/fpcvt.md b/docs/build/reference/fpcvt.md index 8661d649c92..f1277402674 100644 --- a/docs/build/reference/fpcvt.md +++ b/docs/build/reference/fpcvt.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: /fpcvt (Floating-point to integer conversion compatibility)" title: "/fpcvt (Floating-point to unsigned integer conversion compatibility)" +description: "Learn more about: /fpcvt (Floating-point to integer conversion compatibility)" ms.date: 11/03/2021 f1_keywords: ["/fpcvt", "-fpcvt"] helpviewer_keywords: ["-fpcvt compiler option [C++]", "/fpcvt compiler option [C++]"] @@ -30,6 +30,8 @@ In Visual Studio 2019 version 16.8 and later versions, the **`/fpcvt`** compiler For Visual Studio 2019, the default behavior for x64 targets is consistent with **`/fpcvt:BC`** unless **`/arch:AVX512`** is specified. Usually, the behavior for x86 targets is consistent with **`/fpcvt:IA`**, except under **`/arch:IA32`**, **`/arch:SSE`**, or sometimes where the result of a function call is directly converted to an unsigned integer. Use of **`/fpcvt`** overrides the default, so all conversions are handled consistently on either target. The behavior of conversions for ARM and ARM64 targets isn't consistent with either **`/fpcvt:BC`** or **`/fpcvt:IA`**. +Starting with Visual Studio 2022, the default behavior for x64 targets is consistent with `/fpcvt:BC` even when `/arch:AVX512` is specified. To use AVX512 conversion behavior with `/arch:AVX512`, specify `/fpcvt:IA`. + Standard C++ specifies that if a truncated floating-point value is exactly representable in an integer type, it must have that value when converted to that type. Otherwise, any behavior at all is allowed. Both **`/fpcvt`** options conform with Standard C++. The only difference is in what values are returned for invalid source values. The **`/fpcvt:IA`** option causes any invalid conversion to return a single *sentinel* value, which is the destination value farthest from zero. For conversion to signed types, the sentinel is the minimum value for that type. Unsigned types use the maximum value. Floating-point operations may return a Not-a-Number (NaN) value to indicate an invalid operation. That indicator isn't an option for conversion to integer types, which don't have NaN values. The sentinel is used as a proxy for a NaN value, although it can also be the result of a valid conversion. @@ -40,7 +42,7 @@ The **`/fpcvt`** options are new in Visual Studio 2019 version 16.8. If you spec ### Intrinsic functions for conversions -You can specify the behavior of a specific conversion independently of the **`/fpcvt `** option, which applies globally. The compiler provides intrinsic sentinel conversion functions for conversions compatible with **`/fpcvt:IA`**. For more information, see [Sentinel conversion functions](../../intrinsics/sentinel-conversion-functions.md). The compiler also provides saturation conversion functions compatible with conversions on ARM or ARM64 target architectures. For more information, see [Saturation conversion functions](../../intrinsics/saturation-conversion-functions.md). +You can specify the behavior of a specific conversion independently of the **`/fpcvt`** option, which applies globally. The compiler provides intrinsic sentinel conversion functions for conversions compatible with **`/fpcvt:IA`**. For more information, see [Sentinel conversion functions](../../intrinsics/sentinel-conversion-functions.md). The compiler also provides saturation conversion functions compatible with conversions on ARM or ARM64 target architectures. For more information, see [Saturation conversion functions](../../intrinsics/saturation-conversion-functions.md). The compiler also supports intrinsic conversion functions that execute as quickly as possible for valid conversions. These functions may generate any value or throw an exception for an invalid conversion. The results depend on the target platform, compiler options, and context. They're useful for handling values that have already been range-checked, or values generated in a way that can't cause an invalid conversion. For more information, see [Fast conversion functions](../../intrinsics/fast-conversion-functions.md). diff --git a/docs/build/reference/fr-fr-create-dot-sbr-file.md b/docs/build/reference/fr-fr-create-dot-sbr-file.md index 18ee204b7fa..4090865e8f7 100644 --- a/docs/build/reference/fr-fr-create-dot-sbr-file.md +++ b/docs/build/reference/fr-fr-create-dot-sbr-file.md @@ -1,39 +1,40 @@ --- -description: "Learn more about: /FR, /Fr (Create .Sbr File)" -title: "/FR, /Fr (Create .Sbr File)" -ms.date: "11/04/2016" +description: "Learn more about: /FR, /Fr (Name SBR file)" +title: "/FR, /Fr (Name SBR file)" +ms.date: 08/30/2022 f1_keywords: ["VC.Project.VCCLWCECompilerTool.BrowseInformation", "VC.Project.VCCLCompilerTool.BrowseInformation", "/fr", "VC.Project.VCCLCompilerTool.BrowseInformationFile", "VC.Project.VCCLWCECompilerTool.BrowseInformationFile"] helpviewer_keywords: ["/FR compiler option [C++]", "-FR compiler option [C++]", "FR compiler option [C++]", "symbolic browser information"] ms.assetid: 3fd8f88b-3924-4feb-9393-287036a28896 --- -# /FR, /Fr (Create .Sbr File) +# `/FR`, `/Fr` (Name SBR file) -Creates .sbr files. +Creates *`.sbr`* (source browser) files, used by [Code maps](/visualstudio/modeling/code-maps-for-cpp), BSCMAKE, and some third-party code browsing tools. ## Syntax -``` -/FR[pathname[\filename]] -/Fr[pathname[\filename]] -``` +> **`/FR`**\[*`pathname`*\[*`\filename`*]]\ +> **`/Fr`**\[*`pathname`*\[*`\filename`*]] -## Remarks +### Arguments + +*`pathname`*\ +The optional destination directory for the generated *`.sbr`* files. If this value isn't specified, the files are created in the default output directory. For more information, see [Specifying the pathname](specifying-the-pathname.md). -> [!WARNING] -> Although BSCMAKE is still installed with Visual Studio, it is no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server .sdf file in the solution folder. +*`filename`*\ +An optional filename for the generated *`.sbr`* file. If this value isn't specified, the compiler uses the base name of the source file with a *`.sbr`* extension. For more information, see [Specifying the pathname](specifying-the-pathname.md). -During the build process, the Microsoft Browse Information File Maintenance Utility (BSCMAKE) uses these files to create a .BSC file, which is used to display browse information. +## Remarks -**/FR** creates an .sbr file with complete symbolic information. +**`/FR`** creates an *`.sbr`* file with complete symbolic information. -**/Fr** creates an .sbr file without information on local variables. +**`/Fr`** creates an *`.sbr`* file without information on local variables. **`/Fr`** is deprecated; use **`/FR`** instead. For more information, see the Deprecated and removed compiler options section in [Compiler options listed by category](compiler-options-listed-by-category.md). -If you do not specify `filename`, the .sbr file gets the same base name as the source file. +The Visual Studio [Code Maps](/visualstudio/modeling/code-maps-for-cpp) feature requires the *`.sbr`* files generated by **`/FR`**. -**/Fr** is deprecated; use **/FR** instead. For more information, see Deprecated and Removed Compiler Options in [Compiler Options Listed by Category](compiler-options-listed-by-category.md). +The Microsoft Browse Information File Maintenance Utility (BSCMAKE) uses *`.sbr`* files to create a *`.bsc`* file, used to display browse information in some third-party tools. For more information, see [BSCMAKE reference](bscmake-reference.md). > [!NOTE] -> Do not change the .sbr extension. BSCMAKE requires the intermediary files to have that extension. +> Although BSCMAKE is still installed with Visual Studio, it's no longer used by the IDE. Since Visual Studio 2008, browse and symbol information is stored automatically in a SQL Server SDF file in the solution folder. If you use BSCMAKE, don't change the *`.sbr`* extension. BSCMAKE requires the intermediate files to have that extension. ### To set this compiler option in the Visual Studio development environment @@ -49,7 +50,7 @@ If you do not specify `filename`, the .sbr file gets the same base name as the s ## See also -[Output-File (/F) Options](output-file-f-options.md)
-[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md)
-[Specifying the Pathname](specifying-the-pathname.md) +[Output-File (`/F`) options](output-file-f-options.md)\ +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ +[Specifying the pathname](specifying-the-pathname.md) diff --git a/docs/build/reference/fsanitize.md b/docs/build/reference/fsanitize.md index be1a27702fb..e1eef40728d 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=fuzzer`** compiler option enables experimental support for [LibFuzzer](https://releases.llvm.org/3.8.0/docs/LibFuzzer.html). LibFuzzer is a coverage-guided fuzzing library that can be used to find bugs and crashes caused by user-provided input. We recommended you use **`/fsanitize=address`** with LibFuzzer. This option is useful for fuzzing tools such as OneFuzz. For more information, see the [OneFuzz documentation](https://www.microsoft.com/research/project/project-onefuzz/) and [OneFuzz GitHub project](https://github.com/microsoft/onefuzz). Support for the **`/fsanitize=fuzzer`** option is available starting in Visual Studio 2022 version 17.0. +The **`/fsanitize=kernel-address`** compiler option enables [Kernel AddressSanitizer (KASan)](/windows-hardware/drivers/devtest/kasan). KASan is the kernel-mode variant of AddressSanitizer, available starting in Visual Studio 2022 version 17.11. KASan is only supported on Windows 11 24H2 or Windows Server 2025 and higher, and requires building using a Windows SDK 10.0.26100.2161 and higher. Building with KASan also implies the **`/fsanitize-address-asan-compat-lib`** compiler option. + +The **`/fsanitize=fuzzer`** compiler option enables experimental support for [LibFuzzer](https://llvm.org/docs/LibFuzzer.html). LibFuzzer is a coverage-guided fuzzing library that can be used to find bugs and crashes caused by user-provided input. We recommended you use **`/fsanitize=address`** with LibFuzzer. This option is useful for fuzzing tools such as OneFuzz. For more information, see the [OneFuzz documentation](https://www.microsoft.com/research/project/project-onefuzz/) and [OneFuzz GitHub project](https://github.com/microsoft/onefuzz). Support for the **`/fsanitize=fuzzer`** option is available starting in Visual Studio 2022 version 17.0. The **`/fsanitize`** option doesn't allow comma-separated syntax, for example: **`/fsanitize=address,fuzzer`**. These options must be specified individually. -The **`/fsanitize-address-use-after-return`** and **`/fno-sanitize-address-vcasan-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md). +The **`/fsanitize-address-use-after-return`**, **`/fno-sanitize-address-vcasan-lib`**, **`/fsanitize-address-asan-compat-lib`**, and **`/fno-sanitize-address-asan-compat-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md). ### To set the **`/fsanitize=address`** compiler option in the Visual Studio development environment @@ -32,7 +37,7 @@ The **`/fsanitize-address-use-after-return`** and **`/fno-sanitize-address-vcasa 1. Select the **Configuration Properties** > **C/C++** > **General** property page. -1. Modify the **Enable Address Sanitizer** property. To enable it, choose **Yes (/fsanitize=address)**. +1. Modify the **Enable AddressSanitizer** property. To enable it, choose **Yes (/fsanitize=address)**. 1. Choose **OK** or **Apply** to save your changes. diff --git a/docs/build/reference/functionpadmin-create-hotpatchable-image.md b/docs/build/reference/functionpadmin-create-hotpatchable-image.md index 3795500ad19..98057d1ebdd 100644 --- a/docs/build/reference/functionpadmin-create-hotpatchable-image.md +++ b/docs/build/reference/functionpadmin-create-hotpatchable-image.md @@ -1,37 +1,37 @@ --- -description: "Learn more about: /FUNCTIONPADMIN (Create Hotpatchable Image)" -title: "/FUNCTIONPADMIN (Create Hotpatchable Image)" -ms.date: "03/09/2018" -f1_keywords: ["/functionpadmin"] +description: "Learn more about: /FUNCTIONPADMIN (Create hotpatchable image)" +title: "/FUNCTIONPADMIN (Create hotpatchable image)" +ms.date: 09/09/2022 +f1_keywords: ["VC.Project.VCLinkerTool.CreateHotPatchableImage", "/functionpadmin"] helpviewer_keywords: ["-FUNCTIONPADMIN linker option", "/FUNCTIONPADMIN linker option"] ms.assetid: 25b02c13-1add-4fbd-add9-fcb30eb2cae7 --- -# /FUNCTIONPADMIN (Create Hotpatchable Image) +# `/FUNCTIONPADMIN` (Create hotpatchable image) -Prepares an image for hotpatching. +Tells the linker to prepare an executable image for hot patching. ## Syntax -> **/FUNCTIONPADMIN**[**:**_space_] +> **`/FUNCTIONPADMIN`**[**`:`***`size`*] ### Arguments -*space*
-The amount of padding to add to the beginning of each function in bytes. On x86 this defaults to 5 bytes of padding and on x64 this defaults to 6 bytes. On other targets a value must be provided. +*`size`*\ +The amount of padding to add to the beginning of each function in bytes. On x86 the default is 5 bytes of padding and on x64 the default is 6 bytes. On other targets a value must be provided. ## Remarks -In order for the linker to produce a hotpatchable image, the .obj files must have been compiled with [/hotpatch (Create Hotpatchable Image)](hotpatch-create-hotpatchable-image.md). +In order for the linker to produce a hotpatchable image, the *`.obj`* files must be compiled by using the [`/hotpatch` (Create hotpatchable image)](hotpatch-create-hotpatchable-image.md) compiler option. -When you compile and link an image with a single invocation of cl.exe, **/hotpatch** implies **/functionpadmin**. +When you compile and link an image with a single invocation of cl.exe, **`/hotpatch`** implies **`/FUNCTIONPADMIN`**. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **General** property page. -1. Enter the **/FUNCTIONPADMIN** option in **Additional Options**. Choose **OK** to save your changes. +1. Modify the **Create Hot Patchable Image** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -39,5 +39,5 @@ When you compile and link an image with a single invocation of cl.exe, **/hotpat ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/gd-gr-gv-gz-calling-convention.md b/docs/build/reference/gd-gr-gv-gz-calling-convention.md index 834a53189cf..50380ebb09d 100644 --- a/docs/build/reference/gd-gr-gv-gz-calling-convention.md +++ b/docs/build/reference/gd-gr-gv-gz-calling-convention.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /Gd, /Gr, /Gv, /Gz (Calling Convention)" title: "/Gd, /Gr, /Gv, /Gz (Calling Convention)" -ms.date: "09/05/2018" +description: "Learn more about: /Gd, /Gr, /Gv, /Gz (Calling Convention)" +ms.date: 09/05/2018 f1_keywords: ["/Gr", "/Gv", "/Gd", "VC.Project.VCCLCompilerTool.CallingConvention"] helpviewer_keywords: ["-Gd compiler option [C++]", "-Gv compiler option [C++]", "/Gv compiler option [C++]", "-Gr compiler option [C++]", "Gd compiler option [C++]", "Gr compiler option [C++]", "/Gz compiler option [C++]", "-Gz compiler option [C++]", "/Gd compiler option [C++]", "Gz compiler option [C++]", "Gv compiler option [C++]", "/Gr compiler option [C++]"] -ms.assetid: fd3110cb-2d77-49f2-99cf-a03f9ead00a3 --- # /Gd, /Gr, /Gv, /Gz (Calling Convention) @@ -44,7 +43,7 @@ For more information about calling conventions, see [Calling Conventions](../../ On x86 processors, all function arguments are passed on the stack from right to left. On ARM and x64 architectures, some arguments are passed by register and the rest are passed on the stack from right to left. The calling routine pops the arguments from the stack. -For C, the **`__cdecl`** naming convention uses the function name preceded by an underscore ( `_` ); no case translation is performed. Unless declared as `extern "C"`, C++ functions use a different name-decorating scheme. For more information, see [Decorated Names](decorated-names.md). +For C, the **`__cdecl`** naming convention uses the function name preceded by an underscore (`_`); no case translation is performed. Unless declared as `extern "C"`, C++ functions use a different name-decorating scheme. For more information, see [Decorated Names](decorated-names.md). ## __fastcall Specifics diff --git a/docs/build/reference/general-property-page-project.md b/docs/build/reference/general-property-page-project.md index 5fd0640279f..b06af7088be 100644 --- a/docs/build/reference/general-property-page-project.md +++ b/docs/build/reference/general-property-page-project.md @@ -77,7 +77,7 @@ You can use project macros to change the directory location. For more informatio ### Platform Toolset -Specifies the toolset used for building the current configuration. This property allows the project to target a different version of the Visual C++ libraries and compiler. By default, Visual Studio C++ projects target the latest toolset installed by Visual Studio. You can choose one of the toolsets installed by several previous versions of Visual Studio instead. Some older toolsets can create executables that run on Windows XP or Vista. For more information on how to change the platform toolset, see [How to: Modify the target framework and platform toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). +Specifies the toolset used for building the current configuration. This property allows the project to target a different version of the Microsoft C++ libraries and compiler. By default, Visual Studio C++ projects target the latest toolset installed by Visual Studio. You can choose one of the toolsets installed by several previous versions of Visual Studio instead. Some older toolsets can create executables that run on Windows XP or Vista. For more information on how to change the platform toolset, see [How to: Modify the target framework and platform toolset](../how-to-modify-the-target-framework-and-platform-toolset.md). ### Enable Managed Incremental Build 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 e77bc2bfd9c..37657efee2b 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/gm-enable-minimal-rebuild.md b/docs/build/reference/gm-enable-minimal-rebuild.md index f0ec29080de..392220656af 100644 --- a/docs/build/reference/gm-enable-minimal-rebuild.md +++ b/docs/build/reference/gm-enable-minimal-rebuild.md @@ -1,14 +1,13 @@ --- description: "Learn more about: /Gm (Enable Minimal Rebuild)" title: "/Gm (Enable Minimal Rebuild)" -ms.date: "11/12/2018" +ms.date: 04/14/2026 f1_keywords: ["VC.Project.VCCLCompilerTool.MinimalRebuild", "/Gm", "VC.Project.VCCLWCECompilerTool.MinimalRebuild"] helpviewer_keywords: ["/Gm compiler option [C++]", "minimal rebuild", "enable minimal rebuild compiler option [C++]", "Gm compiler option [C++]", "-Gm compiler option [C++]"] -ms.assetid: d8869ce0-d2ea-40eb-8dae-6d2cdb61dd59 --- # /Gm (Enable Minimal Rebuild) -Deprecated. Enables minimal rebuild, which determines whether C++ source files that include changed C++ class definitions (stored in header (.h) files) need to be recompiled. +Deprecated in Visual Studio 2019 version 16.0. Enables minimal rebuild, which determines whether C++ source files that include changed C++ class definitions (stored in header (.h) files) need to be recompiled. ## Syntax @@ -18,7 +17,7 @@ Deprecated. Enables minimal rebuild, which determines whether C++ source files t ## Remarks -**/Gm** is deprecated. It may not trigger a build for certain kinds of header file changes. You may safely remove this option from your projects. To improve build times, we recommend you use precompiled headers and incremental and parallel build options instead. For a list of deprecated compiler options, see the **Deprecated and Removed Compiler Options** section in [Compiler Options Listed by Category](compiler-options-listed-by-category.md). +**/Gm** is deprecated as of Visual Studio 2019 version 16.0. Using it produces compiler warning D9035. It may not trigger a build for certain kinds of header file changes. You may safely remove this option from your projects. To improve build times, we recommend you use precompiled headers and incremental and parallel build options instead. For a list of deprecated compiler options, see the **Deprecated and Removed Compiler Options** section in [Compiler Options Listed by Category](compiler-options-listed-by-category.md). The compiler stores dependency information between source files and class definitions in the project's .idb file during the first compile. (Dependency information tells which source file is dependent on which class definition, and which .h file the definition is located in.) Subsequent compiles use the information stored in the .idb file to determine whether a source file needs to be compiled, even if it includes a modified .h file. @@ -30,9 +29,7 @@ Because the incremental linker does not support the Windows metadata included in ### 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 **Enable Minimal Rebuild** property. ### To set this compiler option programmatically @@ -41,5 +38,5 @@ Because the incremental linker does not support the Windows metadata included in ## 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-buffer-security-check.md b/docs/build/reference/gs-buffer-security-check.md index 227124b8142..41fe1b082cf 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 f681a54a156..4e1ff0eb873 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 b4d970ac8ca..1da0931bd13 100644 --- a/docs/build/reference/guard-enable-control-flow-guard.md +++ b/docs/build/reference/guard-enable-control-flow-guard.md @@ -1,47 +1,48 @@ --- -description: "Learn more about: /guard (Enable Control Flow Guard)" title: "/guard (Enable Control Flow Guard)" -ms.date: "11/04/2016" +description: "Learn more about: /guard (Enable Control Flow Guard)" +ms.date: 2/24/2025 f1_keywords: ["/guard", "VC.Project.VCCLCompilerTool.ControlFlowGuard"] -ms.assetid: be495323-f59f-4cf3-a6b6-8ee69e6a19dd --- -# /guard (Enable Control Flow Guard) +# `/guard` (Enable Control Flow Guard) Enable compiler generation of Control Flow Guard security checks. ## Syntax -``` -/guard:cf[-] -``` +> **`/guard:cf`**\ +> **`/guard:cf-`** ## Remarks -The **/guard:cf** option causes the compiler to analyze control flow for indirect call targets at compile time, and then to insert code to verify the targets at runtime. By default, **/guard:cf** is off and must be explicitly enabled. To explicitly disable this option, use **/guard:cf-**. +The **`/guard:cf`** option causes the compiler to analyze control flow for indirect call targets at compile time, and inserts code at runtime to verify the targets. By default, **`/guard:cf`** is off and must be explicitly enabled. To explicitly disable this option, use **`/guard:cf-`**. **Visual Studio 2017 and later**: This option adds guards for **`switch`** statements that generate jump tables. -When the **/guard:cf** Control Flow Guard (CFG) option is specified, the compiler and linker insert extra runtime security checks to detect attempts to compromise your code. During compiling and linking, all indirect calls in your code are analyzed to find every location that the code can reach when it runs correctly. This information is stored in extra structures in the headers of your binaries. The compiler also injects a check before every indirect call in your code that ensures the target is one of the verified locations. If the check fails at runtime on a CFG-aware operating system, the operating system closes the program. +When the **`/guard:cf`** Control Flow Guard (CFG) option is specified, the compiler and linker insert extra runtime security checks to detect attempts to compromise your code. During compiling and linking, all indirect calls in your code are analyzed to find every location that the code can reach when it runs correctly. This information is stored in extra structures in the headers of your binaries. The compiler also injects a check before every indirect call in your code that ensures the target is one of the verified locations. If the check fails at runtime on a CFG-aware operating system, the operating system closes the program. -A common attack on software takes advantage of bugs in handling extreme or unexpected inputs. Carefully crafted input to the application may overwrite a location that contains a pointer to executable code. This can be used to redirect control flow to code controlled by the attacker. The CFG runtime checks do not fix the data corruption bugs in your executable. They instead make it more difficult for an attacker to use them to execute arbitrary code. CFG is a mitigation tool that prevents calls to locations other than function entry points in your code. It's similar to how Data Execution Prevention (DEP), [/GS](gs-buffer-security-check.md) stack checks, and [/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md) and [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) address space layout randomization (ASLR) lower the chances that your code becomes an exploit vector. +A common attack on software takes advantage of bugs in handling extreme or unexpected inputs. Carefully crafted input to the application may overwrite a location that contains a pointer to executable code. This technique can be used to redirect control flow to code controlled by the attacker. The CFG runtime checks don't fix the data corruption bugs in your executable. They instead make it more difficult for an attacker to use them to execute arbitrary code. CFG is a mitigation tool that prevents calls to locations other than function entry points in your code. It's similar to how Data Execution Prevention (DEP), [/GS](gs-buffer-security-check.md) stack checks, and [`/DYNAMICBASE`](dynamicbase-use-address-space-layout-randomization.md) and [/HIGHENTROPYVA](highentropyva-support-64-bit-aslr.md) address space layout randomization (ASLR) lower the chances that your code becomes an exploit vector. -The **/guard:cf** option must be passed to both the compiler and linker to build code that uses the CFG exploit mitigation technique. If your binary is built by using a single `cl` command, the compiler passes the option to the linker. If you compile and link separately, the option must be set on both the compiler and linker commands. The /DYNAMICBASE linker option is also required. To verify that your binary has CFG data, use the `dumpbin /headers /loadconfig` command. CFG-enabled binaries have `Guard` in the list of EXE or DLL characteristics, and Guard Flags include `CF Instrumented` and `FID table present`. +To use the CFG exploit mitigation technique, pass **`/guard:cf`** to the compiler and **`/GUARD:CF`** to the linker. -The **/guard:cf** option is incompatible with [/ZI](z7-zi-zi-debug-information-format.md) (Edit and Continue debug information) or [/clr](clr-common-language-runtime-compilation.md) (Common Language Runtime Compilation). +To disable the CFG exploit mitigation technique, pass **`/guard:cf-`** to the compiler **`/GUARD:NO`** to the linker. -Code compiled by using **/guard:cf** can be linked to libraries and object files that are not compiled by using the option. Only this code, when also linked by using the **/guard:cf** option and run on a CFG-aware operating system, has CFG protection. Because code compiled without the option will not stop an attack, we recommend that you use the option on all the code you compile. There is a small runtime cost for CFG checks, but the compiler analysis attempts to optimize away the checks on indirect jumps that can be proven to be safe. +If you build using a single `cl` command, the compiler passes the option to the linker. If you compile and link separately, set the option for both the compiler and linker commands. The `/DYNAMICBASE` linker option is also required. -### To set this compiler option in the Visual Studio development environment +To verify that your binary has CFG data, use the `dumpbin /headers /loadconfig` command. CFG-enabled binaries have `Guard` in the list of EXE or DLL characteristics, and Guard Flags include `CF Instrumented` and `FID table present`. -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +The **`/guard:cf`** option is incompatible with [`/ZI`](z7-zi-zi-debug-information-format.md) (Edit and Continue debug information) or [`/clr`](clr-common-language-runtime-compilation.md) (Common Language Runtime Compilation). -1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. +Code compiled by using **`/guard:cf`** can be linked to libraries and object files that aren't compiled by using the option. Only this code, when also linked by using the **`/guard:cf`** option and run on a CFG-aware operating system, has CFG protection. Because code compiled without the option won't stop an attack, we recommend that you use the option on all the code you compile. There's a small runtime cost for CFG checks, but the compiler analysis attempts to optimize away the checks on indirect jumps that can be proven to be safe. -1. Select the **Control Flow Guard** property. +### To set this compiler option in the Visual Studio development environment +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **C/C++** > **Code Generation** property page. +1. Select the **Control Flow Guard** property. 1. In the dropdown control, choose **Yes** to enable Control Flow Guard, or **No** to disable it. ## See also -[MSVC Compiler Options](compiler-options.md)
-[MSVC Compiler Command-Line Syntax](compiler-command-line-syntax.md) +[MSVC compiler options](compiler-options.md)\ +[MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/guard-enable-guard-checks.md b/docs/build/reference/guard-enable-guard-checks.md index 85afea2c3c0..3df932fa317 100644 --- a/docs/build/reference/guard-enable-guard-checks.md +++ b/docs/build/reference/guard-enable-guard-checks.md @@ -1,37 +1,41 @@ --- -description: "Learn more about: /GUARD (Enable Guard Checks)" +description: "Learn more about: /GUARD (Enable Guard Checks) linker option" title: "/GUARD (Enable Guard Checks)" -ms.date: "11/04/2016" +ms.date: 09/21/2022 +f1_keywords: ["VC.Project.VCCLCompilerTool.LinkControlFlowGuard"] ms.assetid: 72758e23-70ac-4616-94d7-d767477406d1 --- -# /GUARD (Enable Guard Checks) +# `/GUARD` (Enable Guard Checks) -Specifies support for Control Flow Guard checks in the executable image. +Tells the linker whether to support Control Flow Guard checks in the executable image. ## Syntax -``` -/GUARD:{CF|NO} -``` +> **`/GUARD:CF`**\ +> **`/GUARD:NO`** ## Remarks -When /GUARD:CF is specified, the linker modifies the header of a .dll or .exe to indicate support for Control Flow Guard (CFG) runtime checks. The linker also adds the required control flow target address data to the header. By default, /GUARD:CF is disabled. It can be explicitly disabled by using /GUARD:NO. To be effective, /GUARD:CF also requires the [/DYNAMICBASE (Use address space layout randomization)](dynamicbase-use-address-space-layout-randomization.md) linker option, which is on by default. +The **`/GUARD:CF`** linker option modifies the header of a DLL or EXE file to indicate support for Control Flow Guard (CFG) runtime checks. The linker also adds the required control flow target address data to the header. By default, **`/GUARD:CF`** is disabled. It can be explicitly disabled by using **`/GUARD:NO`**. To be effective, **`/GUARD:CF`** also requires the [`/DYNAMICBASE` (Use address space layout randomization)](dynamicbase-use-address-space-layout-randomization.md) linker option, which is on by default. -When source code is compiled by using the [/guard:cf](guard-enable-control-flow-guard.md) option, the compiler analyzes the control flow by examining all indirect calls for possible target addresses. The compiler inserts code to verify the target address of an indirect call instruction is in the list of known target addresses at runtime. Operating systems that support CFG stop a program that fails a CFG runtime check. This makes it more difficult for an attacker to execute malicious code by using data corruption to change a call target. +When source code is compiled by using the [`/guard:cf`](guard-enable-control-flow-guard.md) compiler option, the compiler analyzes the control flow by examining all indirect calls for possible target addresses. The compiler inserts code to verify the target address of an indirect call instruction is in the list of known target addresses at runtime. Operating systems that support CFG stop a program that fails a CFG runtime check. This check makes it more difficult for an attacker to execute malicious code by using data corruption to change a call target. -The /GUARD:CF option must be specified to both the compiler and linker to create CFG-enabled executable images. Code compiled but not linked by using /GUARD:CF incurs the cost of runtime checks, but does not enable CFG protection. When the /GUARD:CF option is specified to the `cl` command to compile and link in one step, the compiler passes the flag to the linker. When the **Control Flow Guard** property is set in Visual Studio, the /GUARD:CF option is passed to both the compiler and linker. When object files or libraries have been compiled separately, the option must be explicitly specified in the `link` command. +The **`/GUARD:CF`** option must be specified to both the compiler and linker to create CFG-enabled executable images. Code compiled but not linked by using **`/GUARD:CF`** incurs the cost of runtime checks, but doesn't enable CFG protection. When the **`/guard:cf`** option is specified to the `cl` command to compile and link in one step, the compiler passes the flag to the linker. When the **Control Flow Guard** property is set in Visual Studio, the **`/GUARD:CF`** option is passed to both the compiler and linker. When object files or libraries have been compiled separately, the option must be explicitly specified in the `link` command. ### To set this linker option in Visual Studio -1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter `/GUARD:CF`. +1. In **Additional Options**, enter *`/GUARD:CF`*. Choose **OK** or **Apply** to save your changes. + +### To set this linker option programmatically + +- See . ## See also -[/guard (Enable Control Flow Guard)](guard-enable-control-flow-guard.md)
-[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[`/guard` (Enable Control Flow Guard)](guard-enable-control-flow-guard.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/header-unit-json-reference.md b/docs/build/reference/header-unit-json-reference.md index f5fa4fa46eb..cc0a1bf2c56 100644 --- a/docs/build/reference/header-unit-json-reference.md +++ b/docs/build/reference/header-unit-json-reference.md @@ -1,11 +1,12 @@ --- description: "Reference for header-units.json file" title: "C++ header unit.json reference" -ms.date: 02/11/2022 +ms.date: 11/09/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["header-units.json"] helpviewer_keywords: ["header-units.json", "header unit"] +monikerRange: '>=msvc-160' --- # C++ header-units.json reference @@ -44,9 +45,9 @@ The `header-units.json` in this directory can contain `a.h` and `b.h`, but not ` } ``` -The reason `macros.h` can't be listed in this `header-units.json` file is that during the scan phase, the header unit (`.ifc`) might not be compiled yet for `macros.h`. In that case, `MACRO` won't be defined when `a.h` is compiled. That means `b.h` will be missing from the list of dependencies for `a.h`. Because it isn't in the list of dependencies, the build system won't build a header unit for `b.h` despite it being listed in the `header-units.json` file. +The reason `macros.h` can't be listed in this `header-units.json` file is that during the scan phase, the header unit (`.ifc`) might not be compiled yet for `macros.h`. In that case, `MACRO` won't be defined when `a.h` is compiled. That means `b.h` will be missing from the list of dependencies for `a.h`. Since it isn't in the list of dependencies, the build system won't build a header unit for `b.h` despite it being listed in the `header-units.json` file. -To avoid this problem when there's a dependency on a macro in another header file, the header file that defines the macro is excluded from the list of files that can be compiled into a header unit. This way the header file that defines the macro is treated as an `#include` and `MACRO` will be visible so that `b.h` is included and listed as one of the dependencies. +To avoid this problem, when there's a dependency on a macro in another header file, the header file that defines the macro is excluded from the list of files that can be compiled into a header unit. This way the header file that defines the macro is treated as a normal `#include` and `MACRO` will be visible so that `b.h` is included and listed as one of the dependencies. ### Preventing duplicated symbols @@ -68,7 +69,7 @@ import "c.h"; If the compiler built header units for `a.h`, `b.h` and `c.h`, then the compiled header units `a.h.ifc`, `b.h.ifc`, and `c.h.ifc` would each contain all of the types from `b.h`. Compiling `Source.cpp`, which imports both `a.h` and `c.h`, would require the compiler to deduplicate the `b.h` types, which would impact build performance. -But if there's a `header-units.json` in the `b.h` directory, and `/translateInclude` is specified, the following happens: +But if there's a `header-units.json` in the `b.h` directory, and `/translateInclude` is specified, then the following happens: 1. The scan of `a.h` and `c.h` lists `b.h` as a header unit import in the dependency scan files generated by the compiler. 1. The build system reads the dependency scan files and determines to build `b.h.ifc` first. diff --git a/docs/build/reference/headername.md b/docs/build/reference/headername.md index 3082639be63..2f7824ddfb8 100644 --- a/docs/build/reference/headername.md +++ b/docs/build/reference/headername.md @@ -1,7 +1,7 @@ --- title: "/headerName (Build a header unit from the specified header)" description: "Use the /headerName compiler option to establish a mapping between a header file and the header unit to build." -ms.date: 04/21/2022 +ms.date: 11/16/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/headerName"] @@ -23,30 +23,32 @@ The name of a header file that the compiler should compile into a header unit (* ## Remarks -The **`/headerName`** compiler option is available starting in Visual Studio 2019 version 16.10. +The **`/headerName:quote`** and **`/headerName:angle`** compiler options are available starting in Visual Studio 2019 version 16.10. -The **`/headerName`** compiler option, in all its forms, requires the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**).\ -If you specify **`/headerName:{quote,angle}`**, you must also specify [`/exportHeader`](module-exportheader.md). +The **`/headerName`** compiler options, in all their forms, require the [`/std:c++20`](std-specify-language-standard-version.md) or later compiler option (such as **`/std:c++latest`**).\ +If you specify a **`/headerName`** option, you must also specify [`/exportHeader`](module-exportheader.md). -**`/headerName:quote`** looks up *`header-filename`* using the same rules as `#include "header-name"` and builds it as a header unit (*`.ifc`* file).\ -**`/headerName:angle`** looks up *`header-filename`* using the same rules as `#include ` and builds it as a header unit (*`.ifc`* file). +- **`/headerName:quote`** looks up *`header-filename`* using the same rules as `#include "header-filename"` and builds it as a header unit (*`.ifc`* file). +- **`/headerName:angle`** looks up *`header-filename`* using the same rules as `#include ` and builds it as a header unit (*`.ifc`* file). + +For more information about the path searching rules for included files in quotes or angle brackets, see [`#include` directive](../../preprocessor/hash-include-directive-c-cpp.md). ### Examples -Given a project that references a header file it defines called `m.h`, the compiler option to compile it into a header unit looks similar to this: +Given a project that references a header file it defines called *`m.h`*, the compiler option to compile it into a header unit looks similar to this example: -```Bash +```bash cl /std:c++latest /exportHeader /headerName:quote m.h /Fom.h.obj ``` -The `/headerName:{quote,angle}` option acts like a flag and doesn't need an argument. The following examples are valid: +The **`/headerName:quote`** and **`/headerName:angle`** options act like a flag and don't need an argument. The following examples are valid: -```Bash +```bash cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm cl /std:c++latest /exportHeader /headerName:quote /MP /Fo.\ my-utilities.h a/b/my-core.h ``` -You can specify multiple `/headerName` options on the same command line, and every argument after that option will be processed with the specified *`header-filename`* lookup rules. The following example processes all the headers as the previous two command line examples in the same way. It looks up the headers using the lookup rules applied as if they had been specified as: `#include `, `#include "my-utilties.h"`, and `#include "a/b/my-core.h"`: +You can specify multiple **`/headerName`** options on the same command line. Every argument after a **`/headerName`** option is processed with the specified include file lookup rules for quotes or angle brackets until the next **`/headerName`** option. The following example processes all the headers as the previous two command line examples in the same way as before. It looks up the headers using the lookup rules applied as if they had been specified as: `#include `, `#include `, `#include `, `#include "my-utilties.h"`, and `#include "a/b/my-core.h"`: ```bash cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algorithm /headerName:quote my-utilities.h a/b/my-core.h @@ -55,15 +57,15 @@ cl /std:c++latest /exportHeader /headerName:angle /MP /Fo.\ vector iostream algo ### To set this compiler option in the Visual Studio development environment > [!NOTE] -> Users don't typically set this command line option. It's set by the build system. +> You normally shouldn't set this option in the Visual Studio development environment. It's set by the build system. 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -1. Set the **Configuration** drop-down to **All Configurations**. +1. Set the **Configuration** drop-down to **All Configurations**. Set the **Platform** drop-down to **All Platforms**. 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to add the *`/headerName`* options and arguments. Then, choose **OK** or **Apply** to save your changes. +1. Modify the **Additional Options** property to add the *`/headerName:quote`* or *`/headerName:angle`* options and the header filenames the options apply to. Then, choose **OK** or **Apply** to save your changes. ## See also diff --git a/docs/build/reference/headerunit.md b/docs/build/reference/headerunit.md index bd107a20832..6ee2d635545 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/help-compiler-command-line-help.md b/docs/build/reference/help-compiler-command-line-help.md index 8b03e638c82..673fc125b1b 100644 --- a/docs/build/reference/help-compiler-command-line-help.md +++ b/docs/build/reference/help-compiler-command-line-help.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /HELP (Compiler Command-Line Help)" title: "/HELP (Compiler Command-Line Help)" -ms.date: "11/04/2016" +description: "Learn more about: /HELP (Compiler Command-Line Help)" +ms.date: 11/04/2016 f1_keywords: ["/help"] helpviewer_keywords: ["HELP compiler option [C++]", "Help, for compiler command line", "/HELP compiler option [C++]", "/? compiler option [C++]", "-HELP compiler option [C++]", "-? compiler option [C++]", "cl.exe compiler, command-line syntax"] -ms.assetid: 192533e7-86f2-48e0-a08f-b5e4e3a4e784 --- # /HELP (Compiler Command-Line Help) @@ -18,8 +17,6 @@ Displays a listing of compiler options to standard output. /? ``` -## Remarks - ### To set this compiler option in the Visual Studio development environment - This compiler option should only be accessed from the command line. diff --git a/docs/build/reference/hint-files.md b/docs/build/reference/hint-files.md index 374b605e6f9..b292dfffa36 100644 --- a/docs/build/reference/hint-files.md +++ b/docs/build/reference/hint-files.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Hint Files" title: "Hint Files" -ms.date: "02/26/2019" +description: "Learn more about: Hint Files" +ms.date: 02/26/2019 f1_keywords: ["cpp.hint", "vc.hint.file"] helpviewer_keywords: ["stop file", "cpp.hint", "hint file", "cpp.stop", "Class View, hint file"] -ms.assetid: 17194f66-cf62-4523-abec-77db0675ab65 --- # Hint Files @@ -133,7 +132,7 @@ For a depiction of how hints are gathered, see the [Example](#example) section. You create and delete hints by using the same syntax as the preprocessor directives to create and delete macros. In fact, the parsing system uses the C/C++ preprocessor to evaluate the hints. For more information about the preprocessor directives, see [#define Directive (C/C++)](../../preprocessor/hash-define-directive-c-cpp.md) and [#undef Directive (C/C++)](../../preprocessor/hash-undef-directive-c-cpp.md). -The only unusual syntax elements are the `@<`, `@=`, and `@>` replacement strings. These hint-file specific replacement strings are only used in *map* macros. A map is a set of macros that relate data, functions, or events to other data, functions, or event handlers. For example, `MFC` uses maps to create [message maps](../../mfc/reference/message-maps-mfc.md), and `ATL` uses maps to create [object maps](../../atl/reference/object-map-macros.md). The hint-file specific replacement strings mark the starting, intermediate, and ending elements of a map. Only the name of a map macro is significant. Therefore, each replacement string intentionally hides the implementation of the macro. +The only unusual syntax elements are the `@<`, `@=`, and `@>` replacement strings. These hint-file specific replacement strings are only used in *map* macros. A map is a set of macros that relate data, functions, or events to other data, functions, or event handlers. For example, MFC uses maps to create [message maps](../../mfc/reference/message-maps-mfc.md), and ATL uses maps to create [object maps](../../atl/reference/object-map-macros.md). The hint-file specific replacement strings mark the starting, intermediate, and ending elements of a map. Only the name of a map macro is significant. Therefore, each replacement string intentionally hides the implementation of the macro. Hints use this syntax: diff --git a/docs/build/reference/homeparams-copy-register-parameters-to-stack.md b/docs/build/reference/homeparams-copy-register-parameters-to-stack.md index bb498d1bfef..9a9b9b1119a 100644 --- a/docs/build/reference/homeparams-copy-register-parameters-to-stack.md +++ b/docs/build/reference/homeparams-copy-register-parameters-to-stack.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /homeparams (Copy Register Parameters to Stack)" title: "/homeparams (Copy Register Parameters to Stack)" -ms.date: "12/17/2018" +description: "Learn more about: /homeparams (Copy Register Parameters to Stack)" +ms.date: 12/17/2018 f1_keywords: ["/homeparams"] helpviewer_keywords: ["/homeparams compiler option [C++]", "-homeparams compiler option [C++]"] -ms.assetid: 51067de4-24f7-436b-b8d9-bc867a7d53aa --- # /homeparams (Copy Register Parameters to Stack) diff --git a/docs/build/reference/hotpatch-create-hotpatchable-image.md b/docs/build/reference/hotpatch-create-hotpatchable-image.md index ecd2b6467e5..011a1b31280 100644 --- a/docs/build/reference/hotpatch-create-hotpatchable-image.md +++ b/docs/build/reference/hotpatch-create-hotpatchable-image.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: /hotpatch (Create Hotpatchable Image)" -title: "/hotpatch (Create Hotpatchable Image)" -ms.date: "12/7/2021" +description: "Learn more about: /hotpatch (Create hotpatchable image)" +title: "/hotpatch (Create hotpatchable image)" +ms.date: "9/4/2025" f1_keywords: ["/hotpatch", "VC.Project.VCCLCompilerTool.CreateHotpatchableImage"] -helpviewer_keywords: ["hot patching", "-hotpatch compiler option [C++]", "/hotpatch compiler option [C++]", "hotpatching"] -ms.assetid: aad539b6-c053-4c78-8682-853d98327798 +helpviewer_keywords: ["hot patching", "hotpatching", "-hotpatch compiler option [C++]", "/hotpatch compiler option [C++]"] --- -# /hotpatch (Create Hotpatchable Image) +# /hotpatch (Create hotpatchable image) -Prepares an image for hot patching. +Prepares an image for hotpatching. ## Syntax @@ -16,20 +15,22 @@ Prepares an image for hot patching. /hotpatch ``` +> [!NOTE] +> This option is only available for x86 + ## Remarks -When **/hotpatch** is used in a compilation, the compiler ensures that the first instruction of each function is at least two bytes, and no jump within the function goes to the first instruction. These conditions are required for hot patching. +When `/hotpatch` is used during compilation, the compiler ensures that the first instruction of each function is at least 2 bytes long and that no jump within the function goes to the first instruction. These conditions are required for hotpatching. -To complete the preparation for making an image hotpatchable, after you use **/hotpatch** to compile, you must use [/FUNCTIONPADMIN (Create Hotpatchable Image)](functionpadmin-create-hotpatchable-image.md) to link. When you compile and link an image by using one invocation of cl.exe, **/hotpatch** implies **/functionpadmin**. +To complete the preparation for making an image hotpatchable, after you compile with `/hotpatch`, use [`/functionpadmin`](functionpadmin-create-hotpatchable-image.md) to link. When you compile and link an image using one invocation of `cl.exe`, `/hotpatch` implies `/functionpadmin`. -Because instructions are always two bytes or larger on the ARM architecture, and because x64 compilation is always treated as if **/hotpatch** has been specified, you don't have to specify **/hotpatch** when you compile for these targets; however, you must still link by using **/functionpadmin** to create hotpatchable images for them. The **/hotpatch** compiler option only affects x86 compilation. +> [!TIP] +> Arm64 and x64 architectures are always treated as hotpatchable. But you must still link by using `/functionpadmin` to create hotpatchable images for them. ### 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. Add the compiler option to the **Additional Options** box. ### To set this compiler option programmatically @@ -38,5 +39,5 @@ Because instructions are always two bytes or larger on the ARM architecture, and ## 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/idlout-name-midl-output-files.md b/docs/build/reference/idlout-name-midl-output-files.md index 38b277f76df..3c182933069 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 00000000000..7466fd2b000 --- /dev/null +++ b/docs/build/reference/ifc-map.md @@ -0,0 +1,88 @@ +--- +title: "/ifcMap" +description: "Map named modules and header units to IFC files." +ms.date: 10/16/2023 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/ifcMap"] +helpviewer_keywords: ["/ifcMap", "Specify named module and header unit mappings to IFC files."] +--- +# `/ifcMap` + +This switch tells the compiler where to find the IFC reference map file, which maps references to named modules and header units to their corresponding IFC (`.ifc`) files. + +## Syntax + +> **`/ifcMap`** *`filename`* + +## Remarks + +The *`filename`* argument specifies the IFC reference map file. It can be relative to the compiler's working directory, or an absolute path. + +You can provide multiple `/ifcMap` arguments to the compiler. + +The IFC reference map file format is a subset of the [TOML](https://toml.io/en/) file format. The IFC reference map file can contain a mix of `[[module]]` and `[[header-unit]]` references. + +Syntax errors or unrecognized table names result in compiler error `C7696` (TOML parse error). + +### Map named modules + +The format of the IFC reference map file for named modules is: + +``` +# Using literal strings +[[module]] +name = 'M' +ifc = 'C:\modules\M.ifc' + +# Using basic strings +[[module]] +name = "N" +ifc = "C:\\modules\\N.ifc" +``` + +This IFC reference map file maps the named modules `'M'` and `'N'` to their respective IFC files. The equivalent [`/reference`](module-reference.md) is: + +```cmd +/reference M=C:\modules\M.ifc /reference N=C:\modules\N.ifc +``` + +For more information about what types of module names are valid for the `name` field, see [`/reference remarks`](module-reference.md#remarks). + +### Map header units + +The format of the IFC reference map file for header units is: + +``` +# Using literal strings +[[header-unit]] +name = ['quote', 'my-utility.h'] +ifc = 'C:\header-units\my-utility.h.ifc' + +[[header-unit]] +name = ['angle', 'vector'] +ifc = 'C:\header-units\vector.ifc' + +# Using basic strings +[[header-unit]] +name = ["quote", "my-engine.h"] +ifc = "C:\\header-units\\my-engine.h.ifc" + +[[header-unit]] +name = ["angle", "algorithm"] +ifc = "C:\\header-units\\algorithm.ifc" +``` + +This IFC reference map file maps `"my-utility.h"` to `C:\header-units\my-utility.h.ifc`, and `` to `C:\header-units\vector.ifc`, and so on. The equivalent [`/headerUnit`](headerunit.md) is: + +```cmd +/headerUnit:quote my-utility=C:\header-units\my-utility.h.ifc /headerUnit:angle vector=C:\header-units\vector.ifc /headerUnit:quote my-engine.h=C:\header-units\my-engine.h.ifc /headerUnit:angle algorithm=C:\header-units\algorithm.ifc +``` + +When `[[header-unit]]` is specified in an IFC reference map file, the compiler implicitly enables [`/Zc:preprocessor`](zc-preprocessor.md), just as it's implicitly enabled when [`/headerUnit`](headerunit.md) is used. For more information about the behavior of the `angle` and `quote` lookup methods, see [/headerUnit remarks](headerunit.md#remarks). + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Walkthrough: Build and import header units in Visual C++ projects](../walkthrough-header-units.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/ifc-output.md b/docs/build/reference/ifc-output.md new file mode 100644 index 00000000000..2fd60fcca20 --- /dev/null +++ b/docs/build/reference/ifc-output.md @@ -0,0 +1,56 @@ +--- +title: "/ifcOutput" +description: "Specify output file or directory for `.ifc` files." +ms.date: 11/21/2022 +author: "tylermsft" +ms.author: "twhitney" +f1_keywords: ["/ifcOutput", "VC.Project.VCCLCompilerTool.ifcOutput"] +helpviewer_keywords: ["/ifcOutput", "Specify where the compiled `.ifc` should go"] +--- +# `/ifcOutput` + +This switch tells the compiler where to output built *`.ifc`* files. If the destination is a directory, then the compiler generates the name of each `.ifc` file based on the interface name or the header unit name. + +## Syntax + +> **`/ifcOutput`** *`filename`*\ +> **`/ifcOutput`** *`directory\`* + +## Remarks + +By default, the compiler derives the name for each generated *`.ifc`* file from the module interface name. For example, given a module name `MyModule`, the generated *`.ifc`* will be named *`MyModule.ifc`*, unless you override the name with the `/ifcOutput` switch. + +Use this switch to specify an alternative *`.ifc`* filename or directory. If you want to use the default built *`.ifc`* filenames, but specify a directory where they should be built, ensure that you add a trailing backslash (`\`) to the directory name. + +When you're building multiple *`.ifc`* files, only use the directory form of the `/ifcOutput` switch. If you provide multiple `/ifcOutput` switches, the compiler only uses the last one. + +If you build with the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) switch, we recommend that you use the directory form of the `/ifcOutput` switch if you have multiple input module files. + +In the following example, the *`.ifc`* file for module `m` defined in *`m.ixx`* is built as `c:\example\m.ifc`. + +```bash +cl ... /c /std:c++latest m.ixx /ifcOutput c:\example\ +``` + +In the following example, the built *`.ifc`* file for module `m` defined in *`m.ixx`** is built as `c:\example\MyModule.ifc`: + +```bash +cl ... /c /std:c++latest m.ixx /ifcOutput c:\example\MyModule.ifc +``` + +### To set this compiler option in the Visual Studio development environment + +1. To apply the **`/ifcOutput`** option to one file in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the **Property Pages** dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Output Files** property page. + +1. Use the dropdown control to modify the **Module Output File Name** property to a directory name (ending in `\`) or an alternate file name. Or you can specify a directory + file name, for example, `c:\example\mymodule.ifc`. Choose **OK** or **Apply** to save your changes. + +Alternatively, you can specify the `/ifcOutput` switch with a right-click on the project name in the **Solution Explorer** > **Configuration Properties** > **C/C++** > **Command Line**. + +## See also + +[Overview of modules in C++](../../cpp/modules-cpp.md)\ +[Using C++ Modules in MSVC from the Command Line](https://devblogs.microsoft.com/cppblog/using-cpp-modules-in-msvc-from-the-command-line-part-1/) \ No newline at end of file diff --git a/docs/build/reference/ilk-name-incremental-database-file.md b/docs/build/reference/ilk-name-incremental-database-file.md new file mode 100644 index 00000000000..ab1d1d456e7 --- /dev/null +++ b/docs/build/reference/ilk-name-incremental-database-file.md @@ -0,0 +1,39 @@ +--- +title: "/ILK (Name incremental database file)" +description: "The MSVC linker option /ILK specifies the incremental link database file pathname." +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.IncrementalLinkDatabaseFile", "/ilk", "ilk"] +helpviewer_keywords: ["Name incremental database file in C++ linker", "/ILK linker option", "-ILK linker option", "ILK linker option"] +--- +# `/ILK` (Name incremental database file) + +The **`/ILK`** linker option tells the linker where to put the *`.ilk`* database file for incremental link information ([`/INCREMENTAL`](./incremental-link-incrementally.md)). + +## Syntax + +> **`/ILK:`**\[*`pathname`*] + +### Arguments + +*`pathname`*\ +The destination directory and filename for the generated *`.ilk`* file. If the **`/ILK`** option isn't specified when **`/INCREMENTAL`** is used, the filename is created by appending *`.ilk`* to the target base filename. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). + +## Remarks + +The **`/ILK`** linker option tells the linker the path and filename to use for the *`.ilk`* incremental database file when you specify [`/INCREMENTAL`](./incremental-link-incrementally.md). + +### To set this compiler option in the Visual Studio development environment + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). +1. Select the **Configuration Properties** > **Linker** > **General** property page. +1. Modify the **Incremental Link Database File** property. The default value is `$(IntDir)$(TargetName).ilk`. + +### To set this compiler option programmatically + +- See . + +## See also + +[`/INCREMENTAL`](./incremental-link-incrementally.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) \ No newline at end of file diff --git a/docs/build/reference/implib-name-import-library.md b/docs/build/reference/implib-name-import-library.md index 9bf0f23ef31..93ad9b6efb6 100644 --- a/docs/build/reference/implib-name-import-library.md +++ b/docs/build/reference/implib-name-import-library.md @@ -1,38 +1,35 @@ --- description: "Learn more about: /IMPLIB (Name Import Library)" title: "/IMPLIB (Name Import Library)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["/implib", "VC.Project.VCLinkerTool.ImportLIbrary"] helpviewer_keywords: ["IMPLIB linker option", "/IMPLIB linker option", "-IMPLIB linker option", "import libraries, overriding default name"] -ms.assetid: fe8f71ab-7055-41b5-8ef8-2b97cfa4a432 --- -# /IMPLIB (Name Import Library) +# `/IMPLIB` (Name Import Library) + +## Syntax > /IMPLIB:*filename* -## Parameters +## Argument -*filename*
-A user-specified name for the import library. It replaces the default name. +*`filename`*\ +A user-specified name for the import library. It replaces the default name. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /IMPLIB option overrides the default name for the import library that LINK creates when it builds a program that contains exports. The default name is formed from the base name of the main output file and the extension .lib. A program contains exports if one or more of the following are specified: +The `/IMPLIB` option overrides the default name for the import library that LINK creates when it builds a program that contains exports. The default name is formed from the base name of the main output file and the extension `.lib`. A program contains exports if one or more of the following are specified: - The [__declspec(dllexport)](../../cpp/dllexport-dllimport.md) keyword in the source code - - [EXPORTS](exports.md) statement in a .def file - - An [/EXPORT](export-exports-a-function.md) specification in a LINK command -LINK ignores /IMPLIB when an import library is not being created. If no exports are specified, LINK does not create an import library. If an export file is used in the build, LINK assumes that an import library already exists and does not create one. For information on import libraries and export files, see [LIB Reference](lib-reference.md). +LINK ignores `/IMPLIB` when an import library isn't being created. If no exports are specified, LINK doesn't create an import library. If an export file is used in the build, LINK assumes that an import library already exists and doesn't create one. For information on import libraries and export files, see [LIB Reference](lib-reference.md). ### To set this linker option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. - 1. Modify the **Import Library** property. ### To set this linker option programmatically @@ -41,5 +38,5 @@ LINK ignores /IMPLIB when an import library is not being created. If no exports ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/incremental-link-incrementally.md b/docs/build/reference/incremental-link-incrementally.md index ef569a12463..581ba2ccd82 100644 --- a/docs/build/reference/incremental-link-incrementally.md +++ b/docs/build/reference/incremental-link-incrementally.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: /INCREMENTAL (Link Incrementally)" -title: "/INCREMENTAL (Link Incrementally)" -ms.date: "11/04/2016" +description: "Learn more about: /INCREMENTAL (Link incrementally)" +title: "/INCREMENTAL (Link incrementally)" +ms.date: 09/07/2022 f1_keywords: ["/incremental", "VC.Project.VCLinkerTool.LinkIncremental"] helpviewer_keywords: ["/INCREMENTAL linker option", "-INCREMENTAL linker option", "INCREMENTAL linker option", "link incrementally option", "LINK tool [C++], options for full linking", "incremental linking"] ms.assetid: 135656ff-94fa-4ad4-a613-22e1a2a5d16b --- -# /INCREMENTAL (Link Incrementally) +# `/INCREMENTAL` (Link incrementally) -``` -/INCREMENTAL[:NO] -``` +Specifies whether to link incrementally or always perform a full link. + +## Syntax + +> **`/INCREMENTAL`**\[**`:NO`**] ## Remarks -Controls how the linker handles incremental linking. +The **`/INCREMENTAL`** linker option controls how the linker handles incremental linking. -By default, the linker runs in incremental mode. To override a default incremental link, specify /INCREMENTAL:NO. +By default, the linker runs in incremental mode. To override a default incremental link, specify **`/INCREMENTAL:NO`**. -An incrementally linked program is functionally equivalent to a program that is non-incrementally linked. However, because it is prepared for subsequent incremental links, an incrementally linked executable, static library, or dynamic-link library file: +An incrementally linked program is functionally equivalent to a program that is non-incrementally linked. However, because it's prepared for subsequent incremental links, an incrementally linked executable, static library, or dynamic-link library file: - Is larger than a non-incrementally linked program because of padding of code and data. Padding enables the linker to increase the size of functions and data without recreating the file. @@ -27,35 +29,37 @@ An incrementally linked program is functionally equivalent to a program that is > [!NOTE] > To ensure that your final release build does not contain padding or thunks, link your program non-incrementally. -To link incrementally regardless of the default, specify /INCREMENTAL. When this option is selected, the linker issues a warning if it cannot link incrementally, and then links the program non-incrementally. Certain options and situations override /INCREMENTAL. +To link incrementally regardless of the default, specify **`/INCREMENTAL`**. When this option is selected, the linker issues a warning if it can't link incrementally, and then links the program non-incrementally. Certain options and situations override **`/INCREMENTAL`**. Most programs can be linked incrementally. However, some changes are too great, and some options are incompatible with incremental linking. LINK performs a full link if any of the following options are specified: -- Link Incrementally is not selected (/INCREMENTAL:NO) +- Link Incrementally isn't selected (**`/INCREMENTAL:NO`**) -- /OPT:REF is selected +- **`/OPT:REF`** is selected -- /OPT:ICF is selected +- **`/OPT:ICF`** is selected -- /OPT:LBR is selected +- **`/OPT:LBR`** is selected -- /ORDER is selected +- **`/ORDER`** is selected -/INCREMENTAL is implied when [/DEBUG](debug-generate-debug-info.md) is specified. +**`/INCREMENTAL`** is implied when [`/DEBUG`](debug-generate-debug-info.md) is specified. Additionally, LINK performs a full link if any of the following situations occur: -- The incremental status (.ilk) file is missing. (LINK creates a new .ilk file in preparation for subsequent incremental linking.) +- The incremental status (*`.ilk`*) file is missing. (LINK creates a new *`.ilk`* file in preparation for subsequent incremental linking.) -- There is no write permission for the .ilk file. (LINK ignores the .ilk file and links non-incrementally.) +- There's no write permission for the *`.ilk`* file. (LINK ignores the *`.ilk`* file and links non-incrementally.) -- The .exe or .dll output file is missing. +- The *`.exe`* or *`.dll`* output file is missing. -- The timestamp of the .ilk, .exe, or .dll is changed. +- The timestamp of the *`.ilk`*, *`.exe`*, or *`.dll`* is changed. - A LINK option is changed. Most LINK options, when changed between builds, cause a full link. -- An object (.obj) file is added or omitted. +- An object (*`.obj`*) file is added or omitted. + +An incremental link creates or updates an incremental link database *`.ilk`* file. You can specify the name and location of this file by using the [`/ILK` (Name incremental database file)](./ilk-name-incremental-database-file.md) linker option. For more information about the *`.ilk`* file, see [`.ilk` files as linker input](./dot-ilk-files-as-linker-input.md). ### To set this linker option in the Visual Studio development environment @@ -71,5 +75,6 @@ Additionally, LINK performs a full link if any of the following situations occur ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`.ilk` files as linker input](./dot-ilk-files-as-linker-input.md) diff --git a/docs/build/reference/inference-rules.md b/docs/build/reference/inference-rules.md index 593b8b2bbb5..ebb37cb5577 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 5e2e03c1b2d..b18211ffdc5 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 e8786d6bd63..0820e55c26c 100644 --- a/docs/build/reference/integritycheck-require-signature-check.md +++ b/docs/build/reference/integritycheck-require-signature-check.md @@ -1,23 +1,23 @@ --- description: "Learn more about: /INTEGRITYCHECK (Require signature check)" title: "/INTEGRITYCHECK (Require signature check)" -ms.date: 04/21/2021 +ms.date: 08/29/2023 --- # `/INTEGRITYCHECK` (Require signature check) Specifies that the digital signature of the binary image must be checked at load time. -> **`/INTEGRITYCHECK`**[**`:NO`**] +> **`/INTEGRITYCHECK`** ## Remarks By default, **`/INTEGRITYCHECK`** is off. -The **`/INTEGRITYCHECK`** linker option sets a flag, `IMAGE_DLLCHARACTERISTICS_FORCE_INTEGRITY`, in the PE header of the DLL file or executable file. This flag tells the memory manager to check for a digital signature in order to load the image in Windows. This option must be set for both 32-bit and 64-bit DLLs that implement kernel-mode code loaded by certain Windows features. It's recommended for all device drivers on Windows Vista, Windows Server 2008, and all later versions of Windows and Windows Server. Versions of Windows prior to Windows Vista ignore this flag. For more information, see [Forced Integrity Signing of Portable Executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx). +The **`/INTEGRITYCHECK`** linker option sets a flag, `IMAGE_DLLCHARACTERISTICS_FORCE_INTEGRITY`, in the PE header of the DLL file or executable file. This flag tells the memory manager to check for a digital signature in order to load the image in Windows. This option must be set for both 32-bit and 64-bit DLLs that certain Windows features load. It's recommended for all device drivers on Windows Vista, Windows Server 2008, and all later versions of Windows and Windows Server. Versions of Windows prior to Windows Vista ignore this flag. For more information, see [Forced Integrity Signing of Portable Executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx). ### Signing `/INTEGRITYCHECK` files -Microsoft has new signing guidance for DLL and executable files linked by using **`/INTEGRITYCHECK`**. The guidance used to recommend a cross-signed certificate from the [cross-signing program](/windows-hardware/drivers/install/cross-certificates-for-kernel-mode-code-signing). However, the [cross-signing program is now deprecated](/windows-hardware/drivers/install/deprecation-of-software-publisher-certificates-and-commercial-release-certificates). We recommend you sign your **`/INTEGRITYCHECK`** files by using the Microsoft [Azure Code Signing](https://techcommunity.microsoft.com/t5/video-hub/reduce-developer-friction-with-azure-code-signing/m-p/1698637) program instead. +Microsoft has new signing guidance for DLL and executable files linked by using **`/INTEGRITYCHECK`**. The guidance used to recommend a cross-signed certificate from the [cross-signing program](/windows-hardware/drivers/install/cross-certificates-for-kernel-mode-code-signing). However, the [cross-signing program is now deprecated](/windows-hardware/drivers/install/deprecation-of-software-publisher-certificates-and-commercial-release-certificates). You must now sign your **`/INTEGRITYCHECK`** files by using the [Azure Artifact Signing service](https://azure.microsoft.com/products/artifact-signing) program instead. ### To set this linker option in Visual Studio @@ -25,12 +25,14 @@ Microsoft has new signing guidance for DLL and executable files linked by using 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. In **Additional Options**, enter *`/INTEGRITYCHECK`* or *`/INTEGRITYCHECK:NO`*. Choose **OK** to save your changes. +1. To create a digitally signed image, include `/INTEGRITYCHECK` in the **Additional Options** command line. A digitally signed image must pass a verification check before it's loaded. This feature is disabled by default. + +1. Choose **OK** to save your changes. ## See also -[MSVC linker reference](linking.md)
-[MSVC linker options](linker-options.md)
-[Forced integrity signing of portable executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx)
-[Kernel-mode code signing requirements](/windows-hardware/drivers/install/kernel-mode-code-signing-requirements--windows-vista-and-later-)
+[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[Forced integrity signing of portable executable (PE) files](https://social.technet.microsoft.com/wiki/contents/articles/255.forced-integrity-signing-of-portable-executable-pe-files.aspx)\ +[Kernel-mode code signing requirements](/windows-hardware/drivers/install/kernel-mode-code-signing-requirements--windows-vista-and-later-)\ [AppInit DLLs and Secure Boot](/windows/win32/dlls/secure-boot-and-appinit-dlls) diff --git a/docs/build/reference/interface.md b/docs/build/reference/interface.md index 0db19ebb9cf..743215fc739 100644 --- a/docs/build/reference/interface.md +++ b/docs/build/reference/interface.md @@ -1,7 +1,7 @@ --- title: "/interface" description: "Use the /interface compiler option to treat the input file as a module interface unit." -ms.date: 04/15/2022 +ms.date: 11/16/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/interface", "VC.Project.VCCLCompilerTool.Interface"] @@ -32,6 +32,18 @@ This switch must be used in with the [`/TP` (Specify source file type)](tc-tp-tc **`/interface`** is available in Visual Studio 2019 version 16.10, or later.\ **`/interface`** requires [/std:c++20](std-specify-language-standard-version.md) or later. +### To set this compiler option in the Visual Studio development environment + +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your module interface files. By default, the build system applies this option to files that have a *`.ixx`** extension. + +1. To apply the **`/interface`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Module Code (/interface)**. Choose **OK** or **Apply** to save your changes. + ## See also [Overview of modules in C++](../../cpp/modules-cpp.md)\ diff --git a/docs/build/reference/internal-partition.md b/docs/build/reference/internal-partition.md index e3fa22ee3f4..393c44956ac 100644 --- a/docs/build/reference/internal-partition.md +++ b/docs/build/reference/internal-partition.md @@ -1,7 +1,7 @@ --- title: "/internalPartition" description: "Use the /internalPartition compiler option to treat the input file as an internal partition unit." -ms.date: 06/29/2022 +ms.date: 11/16/2022 author: "tylermsft" ms.author: "twhitney" f1_keywords: ["/internalPartition", "VC.Project.VCCLCompilerTool.Interface"] @@ -50,6 +50,18 @@ This option can't be used with the [`/interface`](interface.md) compiler option. **`/internalPartition`** is available in Visual Studio 2019 version 16.10, or later.\ **`/internalPartition`** requires [/std:c++20](std-specify-language-standard-version.md) or later. +### To set this compiler option in the Visual Studio development environment + +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your partition files. By default, the build system applies this option to files that have a *`.ixx`** extension. + +1. To apply the **`/internalPartition`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Module Internal Partition (/internalPartition)**. Choose **OK** or **Apply** to save your changes. + ## See also [Overview of modules in C++](../../cpp/modules-cpp.md)\ diff --git a/docs/build/reference/jump-table-rdata.md b/docs/build/reference/jump-table-rdata.md new file mode 100644 index 00000000000..9cb7dd4fdc6 --- /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 2ef01ea5436..3d1a74d531c 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 e63c9bf10e1..4d3910054e8 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 1ac84a54858..64cfdd3f947 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 00000000000..6a9d5e39011 --- /dev/null +++ b/docs/build/reference/link-code-for-kernel-mode.md @@ -0,0 +1,34 @@ +--- +description: "Learn more about: /KERNEL (Create kernel mode binary)." +title: /KERNEL +ms.date: "08/25/2023" +--- +# /KERNEL (Create kernel mode binary) + +Create a binary that is suitable for running in kernel mode. + +## Syntax + +> **`/KERNEL`** + +## Remarks + +Causes the linker to emit a warning if any object file or library linked in the binary wasn't compiled with [/kernel](kernel-create-kernel-mode-binary.md). + +Code that can run in kernel mode must be compiled with the **`/kernel`** option. If you link a binary that contains code that wasn't compiled with **`/kernel`**, the binary might not run correctly in kernel mode. + +Code for kernel mode is compiled with a simplified set of C++ language features that are specific to code that runs in kernel mode. The compiler produces warnings for C++ language features that are potentially disruptive but can't be disabled. For more information about compiling code in kernel mode, see [/kernel (Create kernel mode binary)](kernel-create-kernel-mode-binary.md). + +### To set this linker option in Visual Studio + +1. Open the project **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. + +1. In **Additional Options**, enter `/KERNELMODE`. + +## See also + +- [MSVC linker reference](linking.md) +- [MSVC linker options](linker-options.md) +- [Compiler options: /kernel](kernel-create-kernel-mode-binary.md) \ No newline at end of file diff --git a/docs/build/reference/link-input-files.md b/docs/build/reference/link-input-files.md index 793f81974a0..80664636c6a 100644 --- a/docs/build/reference/link-input-files.md +++ b/docs/build/reference/link-input-files.md @@ -1,42 +1,42 @@ --- description: "Learn more about: LINK Input Files" title: "LINK Input Files" -ms.date: "11/04/2016" +ms.date: 09/01/2022 helpviewer_keywords: ["files [C++], LINK", "module definition files", "resources [C++], linker files", "LINK tool [C++], input files", "module definition files, linker files", "input files [C++], LINK", "linker [C++], input files", "import libraries [C++], linker files", "command input to linker files [C++]"] ms.assetid: bb26fcc5-509a-4620-bc3e-b6c6e603a412 --- -# LINK Input Files +# LINK input files -You provide the linker with files that contain objects, import and standard libraries, resources, module definitions, and command input. LINK does not use file extensions to make assumptions about the contents of a file. Instead, LINK examines each input file to determine what kind of file it is. +You provide the linker with files that contain objects, import and standard libraries, resources, module definitions, and command input. LINK doesn't use file extensions to make assumptions about the contents of a file. Instead, LINK examines each input file to determine what kind of file it is. -Object files on the command line are processed in the order they appear on the command line. Libraries are searched in command line order as well, with the following caveat: Symbols that are unresolved when bringing in an object file from a library are searched for in that library first, and then the following libraries from the command line and [/DEFAULTLIB (Specify Default Library)](defaultlib-specify-default-library.md) directives, and then to any libraries at the beginning of the command line. +Object files on the command line are processed in the order they appear on the command line. Libraries are searched in command line order as well, with the following caveat: Symbols that are unresolved when bringing in an object file from a library are searched for in that library first, and then the following libraries from the command line and [`/DEFAULTLIB` (Specify default library)](defaultlib-specify-default-library.md) directives, and then to any libraries at the beginning of the command line. > [!NOTE] -> LINK no longer accepts a semicolon (or any other character) as the start of a comment in response files and order files. Semicolons are recognized only as the start of comments in module-definition files (.def). +> LINK no longer accepts a semicolon (or any other character) as the start of a comment in response files and order files. Semicolons are recognized only as the start of comments in module-definition files (`.def`). LINK uses the following types of input files: -- [.obj files](dot-obj-files-as-linker-input.md) +- [`.obj` files](dot-obj-files-as-linker-input.md) -- [.netmodule files](netmodule-files-as-linker-input.md) +- [`.netmodule` files](netmodule-files-as-linker-input.md) -- [.lib files](dot-lib-files-as-linker-input.md) +- [`.lib` files](dot-lib-files-as-linker-input.md) -- [.exp files](dot-exp-files-as-linker-input.md) +- [`.exp` files](dot-exp-files-as-linker-input.md) -- [.def files](dot-def-files-as-linker-input.md) +- [`.def` files](dot-def-files-as-linker-input.md) -- [.pdb files](dot-pdb-files-as-linker-input.md) +- [`.pdb` files](dot-pdb-files-as-linker-input.md) -- [.res files](dot-res-files-as-linker-input.md) +- [`.res` files](dot-res-files-as-linker-input.md) -- [.exe files](dot-exe-files-as-linker-input.md) +- [`.exe` files](dot-exe-files-as-linker-input.md) -- [.txt files](dot-txt-files-as-linker-input.md) +- [`.txt` files](dot-txt-files-as-linker-input.md) -- [.ilk files](dot-ilk-files-as-linker-input.md) +- [`.ilk` files](dot-ilk-files-as-linker-input.md) ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/link-repro-full-path-rsp.md b/docs/build/reference/link-repro-full-path-rsp.md new file mode 100644 index 00000000000..c08892e4c70 --- /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 87fcbaf4722..a647917101a 100644 --- a/docs/build/reference/linker-options.md +++ b/docs/build/reference/linker-options.md @@ -1,28 +1,24 @@ --- title: "MSVC Linker options" description: "A list of the options supported by the Microsoft LINK linker." -ms.date: 05/11/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). +`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. +Use the [`comment`](../../preprocessor/comment-c-cpp.md) pragma to specify some linker options. ## Linker options listed alphabetically @@ -33,6 +29,7 @@ You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify | [`/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 specify | [`/CLRIMAGETYPE`](clrimagetype-specify-type-of-clr-image.md) | Sets the type (IJW, pure, or safe) of a CLR image. | | [`/CLRSUPPORTLASTERROR`](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md) | Preserves the last error code of functions that are called through the P/Invoke mechanism. | | [`/CLRTHREADATTRIBUTE`](clrthreadattribute-set-clr-thread-attribute.md) | Specifies the threading attribute to apply to the entry point of your CLR program. | -| [`/CLRUNMANAGEDCODECHECK`](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) | Specifies whether the linker will apply the SuppressUnmanagedCodeSecurity attribute to linker-generated PInvoke stubs that call from managed code into native DLLs. | +| [`/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 specify | [`/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. | @@ -69,16 +67,19 @@ You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify | [`/IDLOUT`](idlout-name-midl-output-files.md) | Specifies the name of the *`.idl`* file and other MIDL output files. | | [`/IGNORE`](ignore-ignore-specific-warnings.md) | Suppresses output of specified linker warnings. | | [`/IGNOREIDL`](ignoreidl-don-t-process-attributes-into-midl.md) | Prevents the processing of attribute information into an *`.idl`* file. | +| [`/ILK`](ilk-name-incremental-database-file.md) | Overrides the default incremental database file name. | | [`/IMPLIB`](implib-name-import-library.md) | Overrides the default import library name. | | [`/INCLUDE`](include-force-symbol-references.md) | Forces symbol references. | | [`/INCREMENTAL`](incremental-link-incrementally.md) | Controls incremental linking. | | [`/INFERASANLIBS`](inferasanlibs.md) | Uses inferred sanitizer libraries. | | [`/INTEGRITYCHECK`](integritycheck-require-signature-check.md) | Specifies that the module requires a signature check at load time. | +| [`/KERNEL`](link-code-for-kernel-mode.md) | Create a kernel mode binary. | | [`/KEYCONTAINER`](keycontainer-specify-a-key-container-to-sign-an-assembly.md) | Specifies a key container to sign an assembly. | | [`/KEYFILE`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md) | Specifies a key or key pair to sign an assembly. | | [`/LARGEADDRESSAWARE`](largeaddressaware-handle-large-addresses.md) | Tells the compiler that the application supports addresses larger than 2 gigabytes | | [`/LIBPATH`](libpath-additional-libpath.md) | Specifies a path to search before the environmental library path. | | [`/LINKREPRO`](linkrepro.md) | Specifies a path to generate link repro artifacts in. | +| [`/LINKREPROFULLPATHRSP`](link-repro-full-path-rsp.md) | Generates a response file containing the absolute paths to all the files that the linker took as input. | | [`/LINKREPROTARGET`](linkreprotarget.md) | Generates a link repro only when producing the specified target.16.1 | | [`/LTCG`](ltcg-link-time-code-generation.md) | Specifies link-time code generation. | | [`/MACHINE`](machine-specify-target-platform.md) | Specifies the target platform. | @@ -95,6 +96,7 @@ You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify | [`/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. | @@ -110,6 +112,10 @@ You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify | [`/SAFESEH`](safeseh-image-has-safe-exception-handlers.md) | Specifies that the image will contain a table of safe exception handlers. | | [`/SECTION`](section-specify-section-attributes.md) | Overrides the attributes of a section. | | [`/SOURCELINK`](sourcelink.md) | Specifies a SourceLink file to add to the PDB. | +| [`/SPD`](spd-specify-sample-profile-database.md) | Specifies the name and location of the *`.spd`* file for Sample Profile-Guided Optimization. | +| [`/SPDEMBED`](spdembed-embed-sample-profile-database.md) | Embeds the Sample Profile Database into the PDB file during a Sample Profile-Guided Optimization (SPGO) build. | +| [`/SPDIN`](spdin-use-sample-profile-database.md) | Specifies a *`.spd`* file containing profiling data for an optimized Sample Profile-Guided Optimization (SPGO) build. | +| [`/SPGO`](spgo-enable-sample-profile-guided-optimization.md) | Enables Sample Profile-Guided Optimization and creates an empty *`.spd`* file. | | [`/STACK`](stack-stack-allocations.md) | Sets the size of the stack in bytes. | | [`/STUB`](stub-ms-dos-stub-file-name.md) | Attaches an MS-DOS stub program to a Win32 program. | | [`/SUBSYSTEM`](subsystem-specify-subsystem.md) | Tells the operating system how to run the *`.exe`* file. | @@ -126,10 +132,11 @@ You can use the [comment](../../preprocessor/comment-c-cpp.md) pragma to specify | [`/WINMDFILE`](winmdfile-specify-winmd-file.md) | Specifies the file name for the Windows Runtime Metadata (winmd) output file that's generated by the [`/WINMD`](winmd-generate-windows-metadata.md) linker option. | | [`/WINMDKEYFILE`](winmdkeyfile-specify-winmd-key-file.md) | Specifies a key or key pair to sign a Windows Runtime Metadata file. | | [`/WINMDKEYCONTAINER`](winmdkeycontainer-specify-key-container.md) | Specifies a key container to sign a Windows Metadata file. | -| [`/WINMDDELAYSIGN`](winmddelaysign-partially-sign-a-winmd.md) | Partially signs a Windows Runtime Metadata (.winmd) file by placing the public key in the winmd file. | +| [`/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 b198808f57f..316eb3ed75d 100644 --- a/docs/build/reference/linker-property-pages.md +++ b/docs/build/reference/linker-property-pages.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Linker Property Pages" title: "Linker Property Pages" -ms.date: "07/24/2019" +description: "Learn more about: Linker Property Pages" +ms.date: 09/07/2022 ms.topic: "article" -ms.assetid: 7e7671e5-a35a-4e67-9bdb-661d75c4d11e +f1_keywords: ["VC.Project.VCLinkerTool.IgnoreImportLibrary", "VC.Project.VCLinkerTool.RegisterOutput", "VC.Project.VCLinkerTool.PerUserRedirection", "VC.Project.VCLinkerTool.LinkLibraryDependencies", "VC.Project.VCLinkerTool.UseLibraryDependencyInputs"] --- # Linker Property Pages @@ -13,7 +13,7 @@ The following properties are found under **Project** > **Properties** > **Config ### Output File -The [/OUT](out-output-file-name.md) option overrides the default name and location of the program that the linker creates. +The [`/OUT`](out-output-file-name.md) option overrides the default name and location of the program that the linker creates. ### Show Progress @@ -31,150 +31,154 @@ Prints Linker Progress Messages ### Version -The [/VERSION](version-version-information.md) option tells the linker to put a version number in the header of the .exe or .dll file. Use DUMPBIN /HEADERS to see the image version field of the OPTIONAL HEADER VALUES to see the effect of **/VERSION**. +The [`/VERSION`](version-version-information.md) option tells the linker to put a version number in the header of the *`.exe`* or *`.dll`* file. Use `DUMPBIN /HEADERS` to see the image version field of the `OPTIONAL HEADER VALUES` to see the effect of **`/VERSION`**. ### Enable Incremental Linking -Enables incremental linking. ([/INCREMENTAL](incremental-link-incrementally.md), /INCREMENTAL:NO) +Enables incremental linking. ([`/INCREMENTAL, /INCREMENTAL:NO`](incremental-link-incrementally.md)) + +### Incremental Link Database File + +Specifies incremental link database file location. ([`/ILK:[name]`](ilk-name-incremental-database-file.md)) ### Suppress Startup Banner -The [/NOLOGO](nologo-suppress-startup-banner-linker.md) option prevents display of the copyright message and version number. +The [`/NOLOGO`](nologo-suppress-startup-banner-linker.md) option prevents display of the copyright message and version number. ### Ignore Import Library -This property tells the linker not to link any .lib output generated from this build into any dependent project. It allows the project system to handle .dll files that don't produce a .lib file when built. If a project depends on another project that produces a DLL, the project system automatically links the .lib file produced by that child project. This property may be unnecessary in projects that produce COM DLLs or resource-only DLLs, because these DLLs don't have any meaningful exports. If a DLL has no exports, the linker doesn't generate a .lib file. If no export .lib file is present, and the project system tells the linker to link with the missing DLL, the link fails. Use the **Ignore Import Library** property to resolve this problem. When set to **Yes**, the project system ignores the presence or absence of the .lib file, and causes any project that depends on this project to not link with the nonexistent .lib file. +This property tells the linker not to link any *`.lib`* output generated from this build into any dependent project. It allows the project system to handle *`.dll`* files that don't produce a *`.lib`* file when built. If a project depends on another project that produces a DLL, the project system automatically links the *`.lib`* file produced by that child project. This property may be unnecessary in projects that produce COM DLLs or resource-only DLLs, because these DLLs don't have any meaningful exports. If a DLL has no exports, the linker doesn't generate a *`.lib`* file. If no export *`.lib`* file is present, and the project system tells the linker to link with the missing DLL, the link fails. Use the **Ignore Import Library** property to resolve this problem. When set to **Yes**, the project system ignores the presence or absence of the *`.lib`* file, and causes any project that depends on this project to not link with the nonexistent *`.lib`* file. To programmatically access this property, see . ### Register Output -Runs `regsvr32.exe /s $(TargetPath)` on the build output, which is valid only on .dll projects. For .exe projects, this property is ignored. To register an .exe output, set a postbuild event on the configuration to do the custom registration that is always required for registered .exe files. +Runs `regsvr32.exe /s $(TargetPath)` on the build output, which is valid only on *`.dll`* projects. For *`.exe`* projects, this property is ignored. To register an *`.exe`* output, set a postbuild event on the configuration to do the custom registration that is always required for registered *`.exe`* files. To programmatically access this property, see . ### Per-user Redirection -Registration in Visual Studio has traditionally been done in HKEY_CLASSES_ROOT (HKCR). With Windows Vista and later operating systems, to access HKCR you must run Visual Studio in elevated mode. Developers don't always want to run in elevated mode but still must work with registration. Per-user redirection allows you to register without having to run in elevated mode. +Registration in Visual Studio has traditionally been done in `HKEY_CLASSES_ROOT` (HKCR). With Windows Vista and later operating systems, to access HKCR you must run Visual Studio in elevated mode. Developers don't always want to run in elevated mode but still must work with registration. Per-user redirection allows you to register without having to run in elevated mode. -Per-user redirection forces any writes to HKCR to be redirected to HKEY\_CURRENT\_USER (HKCU). If per-user redirection is turned off, it can cause [Project Build Error PRJ0050](../../error-messages/tool-errors/project-build-error-prj0050.md) when the program tries to write to HKCR. +Per-user redirection forces any writes to HKCR to be redirected to `HKEY_CURRENT_USER` (HKCU). If per-user redirection is turned off, it can cause [Project Build Error PRJ0050](../../error-messages/tool-errors/project-build-error-prj0050.md) when the program tries to write to HKCR. ### Additional Library Directories -Allows the user to override the environmental library path. ([/LIBPATH](libpath-additional-libpath.md):folder) +Allows the user to override the environment's library path. ([`/LIBPATH:folder`](libpath-additional-libpath.md)) ### Link Library Dependencies -Specifies whether to link the .lib files that are produced by dependent projects. Typically, you want to link in the .lib files, but it may not be the case for certain DLLs. +Specifies whether to link the *`.lib`* files that are produced by dependent projects. Typically, you want to link in the *`.lib`* files, but it may not be the case for certain DLLs. -You can also specify a .obj file by providing the file name and relative path, for example "..\\..\MyLibProject\MyObjFile.obj". If the source code for the .obj file #includes a precompiled header, for example pch.h, then the pch.obj file is located in the same folder as MyObjFile.obj. You must also add pch.obj as an additional dependency. +You can also specify a *`.obj`* file by providing the file name and relative path, for example, *`..\..\MyLibProject\MyObjFile.obj`*. If the source code for the *`.obj`* file has a `#include` for a precompiled header, for example, *`pch.h`*, then the *`pch.obj`* file is located in the same folder as *`MyObjFile.obj`*. You must also add *`pch.obj`* as an additional dependency. ### Use Library Dependency Inputs -Specifies whether to use the inputs to the librarian tool, rather than the library file itself, when linking in library outputs of project dependencies. In a large project, when a dependent project produces a .lib file, incremental linking is disabled. If there are many dependent projects that produce .lib files, building the application can take a long time. When this property is set to **Yes**, the project system links in the .obj files for .libs produced by dependent projects, enabling incremental linking. +Specifies whether to use the inputs to the librarian tool, rather than the library file itself, when linking in library outputs of project dependencies. In a large project, when a dependent project produces a *`.lib`* file, incremental linking is disabled. If there are many dependent projects that produce *`.lib`* files, building the application can take a long time. When this property is set to **Yes**, the project system links in the *`.obj`* files for *`.lib`* files produced by dependent projects, enabling incremental linking. -For information about how to access the **General** linker property page, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +For information about how to access the **General** linker property page, see [Set compiler and build properties](../working-with-project-properties.md). ### Link Status -Specifies whether the linker should display a progress indicator showing what percentage of the link is complete. The default is to not display this status information. ([/LTCG](ltcg-link-time-code-generation.md):STATUS|LTCG:NOSTATUS) +Specifies whether the linker should display a progress indicator showing what percentage of the link is complete. The default is to not display this status information. ([`/LTCG:STATUS|LTCG:NOSTATUS`](ltcg-link-time-code-generation.md)) ### Prevent DLL Binding -[/ALLOWBIND](allowbind-prevent-dll-binding.md):NO sets a bit in a DLL's header that indicates to Bind.exe that the image isn't allowed to be bound. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). +[`/ALLOWBIND:NO`](allowbind-prevent-dll-binding.md) sets a bit in a DLL's header that indicates to *`Bind.exe`* that binding the image isn't allowed. You may not want a DLL to be bound if it has been digitally signed (binding invalidates the signature). ### Treat Linker Warning As Errors -[/WX](wx-treat-linker-warnings-as-errors.md) causes no output file to be generated if the linker generates a warning. +[`/WX`](wx-treat-linker-warnings-as-errors.md) causes no output file to be generated if the linker generates a warning. ### Force File Output -The [/FORCE](force-force-file-output.md) option tells the linker to create an .exe file or DLL even if a symbol is referenced but not defined, or is multiply defined. It may create invalid .exe file. +The [`/FORCE`](force-force-file-output.md) option tells the linker to create an *`.exe`* file or DLL even if a symbol is referenced but not defined (**`UNRESOLVED`**), or is defined multiple times (**`MULTIPLE`**). It may create an invalid *`.exe`* file. **Choices** -- **Enabled** - /FORCE with no arguments implies both multiple and unresolved. -- **Multiply Defined Symbol Only** - Use /FORCE:MULTIPLE to create an output file, even if LINK finds more than one definition for a symbol. -- **Undefined Symbol Only** - Use /FORCE:UNRESOLVED to create an output file whether or not LINK finds an undefined symbol. /FORCE:UNRESOLVED is ignored if the entry point symbol is unresolved. +- **Enabled** - **`/FORCE`** with no arguments implies both **`/FORCE:MULTIPLE`** and **`/FORCE:UNRESOLVED`**. +- **Multiply Defined Symbol Only** - Use **`/FORCE:MULTIPLE`** to create an output file, even if LINK finds more than one definition for a symbol. +- **Undefined Symbol Only** - Use **`/FORCE:UNRESOLVED`** to create an output file whether or not LINK finds an undefined symbol. **`/FORCE:UNRESOLVED`** is ignored if the entry point symbol is unresolved. ### Create Hot Patchable Image -Prepares an image for hotpatching. +Prepares an image for hot patching. **Choices** -- **Enabled** - Prepares an image for hotpatching. -- **X86 Image Only** - Prepares an X86 image for hotpatching. -- **X64 Image Only** - Prepares an X64 image for hotpatching. -- **Itanium Image Only** - Prepares an Itanium image for hotpatching. +- **Enabled** - Prepares an image for hot patching. +- **X86 Image Only** - Prepares an X86 image for hot patching. +- **X64 Image Only** - Prepares an X64 image for hot patching. +- **Itanium Image Only** - Prepares an Itanium image for hot patching. ### Specify Section Attributes -The [/SECTION](section-specify-section-attributes.md) option changes the attributes of a section, overriding the attributes set when the .obj file for the section was compiled. +The [`/SECTION`](section-specify-section-attributes.md) option changes the attributes of a section, overriding the attributes set when the *`.obj`* file for the section was compiled. ## Input Property Page ### Additional Dependencies -Specifies additional items to add to the link command line, for example *kernel32.lib*. +Specifies extra dependency items to add to the link command line, for example *`kernel32.lib`*. ### Ignore All Default Libraries -The [/NODEFAULTLIB](nodefaultlib-ignore-libraries.md) option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. +The [`/NODEFAULTLIB`](nodefaultlib-ignore-libraries.md) option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. ### Ignore Specific Default Libraries -Specifies one or more names of default libraries to ignore. Separate multiple libraries with semi-colons. (/NODEFAULTLIB:[name, name, ...]) +Specifies one or more names of default libraries to ignore. Separate multiple libraries with semi-colons. ([`/NODEFAULTLIB:[name, name, ...]`](nodefaultlib-ignore-libraries.md)) ### Module Definition File -The [/DEF](def-specify-module-definition-file.md) option passes a module-definition file (.def) to the linker. Only one .def file can be specified to LINK. +The [`/DEF`](def-specify-module-definition-file.md) option passes a module-definition file (*`.def`*) to the linker. Only one *`.def`* file can be specified to LINK. ### Add Module to Assembly -The [/ASSEMBLYMODULE](assemblymodule-add-a-msil-module-to-the-assembly.md) option allows you to add a module reference to an assembly. Type information in the module will not be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. +The [`/ASSEMBLYMODULE`](assemblymodule-add-a-msil-module-to-the-assembly.md) option allows you to add a module reference to an assembly. Type information in the module won't be available to the assembly program that added the module reference. However, type information in the module will be available to any program that references the assembly. ### Embed Managed Resource File -[/ASSEMBLYRESOURCE](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. +[`/ASSEMBLYRESOURCE`](assemblyresource-embed-a-managed-resource.md) embeds a resource file in the output file. ### Force Symbol References -The [/INCLUDE](include-force-symbol-references.md) option tells the linker to add a specified symbol to the symbol table. +The [`/INCLUDE`](include-force-symbol-references.md) option tells the linker to add a specified symbol to the symbol table. ### Delay Loaded DLLs -The [/DELAYLOAD](delayload-delay-load-import.md) option causes delayed loading of DLLs. The dll name specifies a DLL to delay load. +The [`/DELAYLOAD`](delayload-delay-load-import.md) option causes delayed loading of DLLs. The dll name specifies a DLL to delay load. ### Assembly Link Resource -The [/ASSEMBLYLINKRESOURCE](assemblylinkresource-link-to-dotnet-framework-resource.md) option creates a link to a .NET Framework resource in the output file; the resource file is not placed in the output file. +The [`/ASSEMBLYLINKRESOURCE`](assemblylinkresource-link-to-dotnet-framework-resource.md) option creates a link to a .NET Framework resource in the output file. The linker doesn't place the resource file in the output file. ## Manifest File Property Page ### Generate Manifest -[/MANIFEST](manifest-create-side-by-side-assembly-manifest.md) specifies that the linker should create a side-by-side manifest file. +[`/MANIFEST`](manifest-create-side-by-side-assembly-manifest.md) specifies that the linker should create a side-by-side manifest file. ### Manifest File -[/MANIFESTFILE](manifestfile-name-manifest-file.md) lets you change the default name of the manifest file. The default name of the manifest file is the file name with .manifest appended. +[`/MANIFESTFILE`](manifestfile-name-manifest-file.md) lets you change the default name of the manifest file. The default name of the manifest file is the file name with *`.manifest`* appended. ### Additional Manifest Dependencies -[/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md) lets you specify attributes that will be placed in the dependency section of the manifest file. +[`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) lets you specify attributes that will be placed in the dependency section of the manifest file. ### Allow Isolation -Specifies behavior for manifest lookup. ([/ALLOWISOLATION](allowisolation-manifest-lookup.md):NO) +Specifies behavior for manifest lookup. ([`/ALLOWISOLATION:NO`](allowisolation-manifest-lookup.md)) ### Enable User Account Control (UAC) -Specifies whether or not User Account Control is enabled. ([/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md), /MANIFESTUAC:NO) +Specifies whether or not User Account Control is enabled. ([`/MANIFESTUAC, /MANIFESTUAC:NO`](manifestuac-embeds-uac-information-in-manifest.md)) ### UAC Execution Level -Specifies the requested execution level for the application when running with User Account Control. (/MANIFESTUAC:level=[value]) +Specifies the requested execution level for the application when running with User Account Control. ([`/MANIFESTUAC:level=[value]`](manifestuac-embeds-uac-information-in-manifest.md)) **Choices** @@ -184,32 +188,32 @@ Specifies the requested execution level for the application when running with Us ### UAC Bypass UI Protection -Specifies whether or not to bypass user interface protection levels for other windows on the desktop. Set this property to 'Yes' only for accessibility applications. ([/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md):uiAccess=[true | false]) +Specifies whether or not to bypass user interface protection levels for other windows on the desktop. Set this property to 'Yes' only for accessibility applications. ([`/MANIFESTUAC:uiAccess=[true | false]`](manifestuac-embeds-uac-information-in-manifest.md)) ## Debugging Property Page ### Generate Debug Info -This option enables creation of debugging information for the .exe file or the DLL. +This option enables creation of debugging information for the *`.exe`* file or the DLL. **Choices** - **No** - Produces no debugging information. - **Generate Debug Information** - Create a complete Program Database (PDB) ideal for distribution to Microsoft Symbol Server. -- **Generate Debug Information optimized for faster links** - Produces a program database (PDB) ideal for edit-link-debug cycle. -- **Generate Debug Information optimized for sharing and publishing** - Produces a program database (PDB) ideal for edit-link-debug cycle. +- **Generate Debug Information optimized for faster links** - Produces a program database (PDB) ideal for a fast edit-link-debug cycle. +- **Generate Debug Information optimized for sharing and publishing** - Produces a program database (PDB) ideal for a shared edit-link-debug cycle. ### Generate Program Database File -By default, when [/DEBUG](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension .pdb. +By default, when [`/DEBUG`](debug-generate-debug-info.md) is specified, the linker creates a program database (PDB) which holds debugging information. The default file name for the PDB has the base name of the program and the extension *`.pdb`*. ### Strip Private Symbols -The [/PDBSTRIPPED](pdbstripped-strip-private-symbols.md) option creates a second program database (PDB) file when you build your program image with any of the compiler or linker options that generate a PDB file (/DEBUG, /Z7, /Zd, or /Zi). +The [`/PDBSTRIPPED`](pdbstripped-strip-private-symbols.md) option creates a second program database (PDB) file when you build your program image with any of the compiler or linker options that generate a PDB file (**`/DEBUG`**, **`/Z7`**, **`/Zd`**, or **`/Zi`**). ### Generate Map File -The [/MAP](map-generate-mapfile.md) option tells the linker to create a mapfile. +The [`/MAP`](map-generate-mapfile.md) option tells the linker to create a mapfile. ### Map File Name @@ -217,24 +221,28 @@ A user-specified name for the mapfile. It replaces the default name. ### Map Exports -The [/MAPINFO](mapinfo-include-information-in-mapfile.md) option tells the linker to include the specified information in a mapfile, which is created if you specify the /MAP option. EXPORTS tells the linker to include exported functions. +The [`/MAPINFO`](mapinfo-include-information-in-mapfile.md) option tells the linker to include the specified information in a mapfile, which is created if you specify the **`/MAP`** option. **`EXPORTS`** tells the linker to include exported functions. ### Debuggable Assembly -[/ASSEMBLYDEBUG](assemblydebug-add-debuggableattribute.md) emits the DebuggableAttribute attribute with debug information tracking and disables JIT optimizations. +[`/ASSEMBLYDEBUG`](assemblydebug-add-debuggableattribute.md) emits the `DebuggableAttribute` attribute with debug information tracking and disables JIT optimizations. + +### Support C++ Dynamic Debugging + +(Preview) Set linker flag [`/DYNAMICDEOPT`](dynamic-deopt-linker.md) to turn on [C++ Dynamic Debugging](/visualstudio/debugger/cpp-dynamic-debugging). Place deoptimized breakpoints and step in anywhere with on-demand function deoptimization. Use this mode for debugging optimized code. ## System Property Page ### SubSystem -The [/SUBSYSTEM](subsystem-specify-subsystem.md) option tells the operating system how to run the .exe file. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will choose. +The [`/SUBSYSTEM`](subsystem-specify-subsystem.md) option tells the operating system how to run the *`.exe`* file. The choice of subsystem affects the entry point symbol (or entry point function) that the linker will choose. **Choices** - **Not Set** - No subsystem set. -- **Console** - Win32 character-mode application. Console applications are given a console by the operating system. If main or wmain is defined, CONSOLE is the default. -- **Windows** - Application does not require a console, probably because it creates its own windows for interaction with the user. If WinMain or wWinMain is defined, WINDOWS is the default. -- **Native** - Device drivers for Windows NT. If /DRIVER:WDM is specified, NATIVE is the default. +- **Console** - Win32 character-mode application. Console applications are given a console by the operating system. If `main` or `wmain` is defined, `CONSOLE` is the default. +- **Windows** - Application doesn't require a console, probably because it creates its own windows for interaction with the user. If `WinMain` or `wWinMain` is defined, `WINDOWS` is the default. +- **Native** - Device drivers for Windows NT. If **`/DRIVER:WDM`** is specified, `NATIVE` is the default. - **EFI Application** - EFI Application. - **EFI Boot Service Driver** - EFI Boot Service Driver. - **EFI ROM** - EFI ROM. @@ -243,109 +251,113 @@ The [/SUBSYSTEM](subsystem-specify-subsystem.md) option tells the operating syst ### Minimum Required Version -Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65,535. +Specify the minimum required version of the subsystem. The arguments are decimal numbers in the range 0 through 65535. ### Heap Reserve Size -Specifies total heap allocation size in virtual memory. Default is 1 MB. ([/HEAP](heap-set-heap-size.md):reserve) +Specifies total heap allocation size in virtual memory. Default is 1 MB. ([`/HEAP:reserve`](heap-set-heap-size.md)) ### Heap Commit Size -Specifies total heap allocation size in physical memory. Default is 4 KB. ([/HEAP](heap-set-heap-size.md):reserve,commit) +Specifies total heap allocation size in physical memory. Default is 4 KB. ([`/HEAP:reserve,commit`](heap-set-heap-size.md)) ### Stack Reserve Size -Specifies the total stack allocation size in virtual memory. Default is 1 MB. ([/STACK](stack-stack-allocations.md):reserve) +Specifies the total stack allocation size in virtual memory. Default is 1 MB. ([`/STACK:reserve`](stack-stack-allocations.md)) ### Stack Commit Size -Specifies the total stack allocation size in physical memory. Default is 4 KB. ([/STACK](stack-stack-allocations.md):reserve,commit) +Specifies the total stack allocation size in physical memory. Default is 4 KB. ([`/STACK:reserve,commit`](stack-stack-allocations.md)) ### Enable Large Addresses -The [/LARGEADDRESSAWARE](largeaddressaware-handle-large-addresses.md) option tells the linker that the application can handle addresses larger than 2 gigabytes. By default, /LARGEADDRESSAWARE:NO is enabled if /LARGEADDRESSAWARE is not otherwise specified on the linker line. +The [`/LARGEADDRESSAWARE`](largeaddressaware-handle-large-addresses.md) option tells the linker that the application can handle addresses larger than 2 gigabytes. By default, **`/LARGEADDRESSAWARE:NO`** is enabled if **`/LARGEADDRESSAWARE`** isn't otherwise specified on the linker line. ### Terminal Server -The [/TSAWARE](tsaware-create-terminal-server-aware-application.md) option sets a flag in the IMAGE_OPTIONAL_HEADER DllCharacteristics field in the program image's optional header. When this flag is set, Terminal Server will not make certain changes to the application. +The [`/TSAWARE`](tsaware-create-terminal-server-aware-application.md) option sets a flag in the `IMAGE_OPTIONAL_HEADER` `DllCharacteristics` field in the program image's optional header. When this flag is set, Terminal Server won't make certain changes to the application. ### Swap Run From CD -The [/SWAPRUN](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. When **CD** is specified, the operating system will copy the image on a removable disk to a page file and then load it. +The [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. When **`CD`** is specified, the operating system will copy the image on a removable disk to a page file, and then load it. ### Swap Run From Network -The [/SWAPRUN](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. If **NET** is specified, the operating system will first copy the binary image from the network to a swap file and load it from there. This option is useful for running applications over the network. +The [`/SWAPRUN`](swaprun-load-linker-output-to-swap-file.md) option tells the operating system to first copy the linker output to a swap file, and then run the image from there. This option is a Windows NT 4.0 (and later) feature. If **`NET`** is specified, the operating system will first copy the binary image from the network to a swap file and load it from there. This option is useful for running applications over the network. ### Driver -Use the [/DRIVER](driver-windows-nt-kernel-mode-driver.md) linker option to build a Windows NT kernel mode driver. +Use the [`/DRIVER`](driver-windows-nt-kernel-mode-driver.md) linker option to build a Windows NT kernel mode driver. **Choices** - **Not Set** - Default driver setting. - **Driver** - Driver -- **UP Only** - /DRIVER:UPONLY causes the linker to add the IMAGE_FILE_UP_SYSTEM_ONLY bit to the characteristics in the output header to specify that it is a uniprocessor (UP) driver. The operating system will refuse to load a UP driver on a multiprocessor (MP) system. -- **WDM** - /DRIVER:WDM causes the linker to set the IMAGE_DLLCHARACTERISTICS_WDM_DRIVER bit in the optional header's DllCharacteristics field. +- **UP Only** - **`/DRIVER:UPONLY`** causes the linker to add the `IMAGE_FILE_UP_SYSTEM_ONLY` bit to the characteristics in the output header to specify that it's a uniprocessor (UP) driver. The operating system will refuse to load a UP driver on a multiprocessor (MP) system. +- **WDM** - **`/DRIVER:WDM`** causes the linker to set the `IMAGE_DLLCHARACTERISTICS_WDM_DRIVER` bit in the optional header's `DllCharacteristics` field. ## Optimization Property Page ### References -[/OPT](opt-optimizations.md):REF eliminates functions and/or data that's never referenced while /OPT:NOREF keeps functions and/or data that's never referenced. +[`/OPT:REF`](opt-optimizations.md) eliminates functions and/or data that's never referenced while **`/OPT:NOREF`** keeps functions and/or data that's never referenced. ### Enable COMDAT Folding -Use [/OPT](opt-optimizations.md):ICF\[=iterations] to perform identical COMDAT folding. +Use [`/OPT:ICF[=iterations]`](opt-optimizations.md) to perform identical COMDAT folding. ### Function Order -The [/ORDER](order-put-functions-in-order.md)option tells LINK to optimize your program by placing certain COMDATs into the image in a predetermined order. LINK places the functions in the specified order within each section in the image. +The [`/ORDER`](order-put-functions-in-order.md) option tells LINK to optimize your program by placing certain COMDATs into the image in a predetermined order. LINK places the functions in the specified order within each section in the image. ### Profile Guided Database -Specify .pgd file for profile guided optimizations. ([/PGD](pgd-specify-database-for-profile-guided-optimizations.md)) +Specify the *`.pgd`* file for profile guided optimizations. ([`/PGD`](pgd-specify-database-for-profile-guided-optimizations.md)) ### Link Time Code Generation -Specifies link-time code generation. ([/LTCG](ltcg-link-time-code-generation.md)) +Specifies link-time code generation. ([`/LTCG`](ltcg-link-time-code-generation.md)) **Choices** - **Default** - Default LTCG setting. -- **Use Fast Link Time Code Generation** - Use Link Time Code Generation with [/FASTGENPROFILE](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). +- **Use Fast Link Time Code Generation** - Use Link Time Code Generation with [`/FASTGENPROFILE`](genprofile-fastgenprofile-generate-profiling-instrumented-build.md). - **Use Link Time Code Generation** - Use [Link Time Code Generation](ltcg-link-time-code-generation.md). -- **Profile Guided Optimization - Instrument** - Use [profile guided optimization](../profile-guided-optimizations.md) with :PGINSTRUMENT. +- **Profile Guided Optimization - Instrument** - Use [profile guided optimization](../profile-guided-optimizations.md) with `:PGINSTRUMENT`. - **Profile Guided Optimization - Optimization** - Specifies that the linker should use the profile data created after running the instrumented binary to create an optimized image. -- **Profile Guided Optimization - Update** - Allows and tracks list of input files to be added or modified from what was specified in the :PGINSTRUMENT phase. +- **Profile Guided Optimization - Update** - Allows and tracks list of input files to be added or modified from what was specified in the `:PGINSTRUMENT` phase. + +### Link Time Code Generation Object File + +Specifies *`.iobj`* file location. ([`/LTCGOUT:[name]`](ltcgout.md)) ## Embedded IDL Property Page ### MIDL Commands -Specify MIDL command line Options. ([/MIDL](midl-specify-midl-command-line-options.md):@responsefile) +Specify MIDL command line options. ([`/MIDL:@responsefile`](midl-specify-midl-command-line-options.md)) ### Ignore Embedded IDL -The [/IGNOREIDL](ignoreidl-don-t-process-attributes-into-midl.md) option specifies that any IDL attributes in source code should not be processed into an .idl file. +The [`/IGNOREIDL`](ignoreidl-don-t-process-attributes-into-midl.md) option specifies that any IDL attributes in source code shouldn't be processed into an *`.idl`* file. ### Merged IDL Base File Name -The [/IDLOUT](idlout-name-midl-output-files.md) option specifies the name and extension of the .idl file. +The [`/IDLOUT`](idlout-name-midl-output-files.md) option specifies the name and extension of the *`.idl`* file. ### Type Library -The [/TLBOUT](tlbout-name-dot-tlb-file.md) option specifies the name and extension of the .tlb file. +The [`/TLBOUT`](tlbout-name-dot-tlb-file.md) option specifies the name and extension of the *`.tlb`* file. ### TypeLib Resource ID -Allows you to specify the resource ID of the linker-generated type library. ([/TLBID](tlbid-specify-resource-id-for-typelib.md):id) +Allows you to specify the resource ID of the linker-generated type library. ([`/TLBID:id`](tlbid-specify-resource-id-for-typelib.md)) ## Windows Metadata Property Page ### Generate Windows Metadata -Enables or disable generation of Windows Metadata. +Enables or disables generation of Windows Metadata. **Choices** @@ -354,73 +366,73 @@ Enables or disable generation of Windows Metadata. ### Windows Metadata File -The [/WINMDFILE](winmdfile-specify-winmd-file.md) option switch. +The [`/WINMDFILE`](winmdfile-specify-winmd-file.md) option switch. ### Windows Metadata Key File -Specify key or key pair to sign an Windows Metadata. ([/WINMDKEYFILE](winmdkeyfile-specify-winmd-key-file.md):filename) +Specify a key or key pair to sign the Windows Metadata. ([`/WINMDKEYFILE:filename`](winmdkeyfile-specify-winmd-key-file.md)) ### Windows Metadata Key Container -Specify a key container to sign an Windows Metadata. ([/WINMDKEYCONTAINER](winmdkeycontainer-specify-key-container.md):name) +Specify a key container to sign the Windows Metadata. ([`/WINMDKEYCONTAINER:name`](winmdkeycontainer-specify-key-container.md)) ### Windows Metadata Delay Sign -Partially sign an Windows Metadata. Use [/WINMDDELAYSIGN](winmddelaysign-partially-sign-a-winmd.md) if you only want to place the public key in the Windows Metadata. The default is /WINMDDELAYSIGN:NO. +Partially sign the Windows Metadata. Use [`/WINMDDELAYSIGN`](winmddelaysign-partially-sign-a-winmd.md) if you only want to place the public key in the Windows Metadata. The default is **`/WINMDDELAYSIGN:NO`**. ## Advanced Property Page ### Entry Point -The [/ENTRY](entry-entry-point-symbol.md) option specifies an entry point function as the starting address for an .exe file or DLL. +The [`/ENTRY`](entry-entry-point-symbol.md) option specifies an entry point function as the starting address for an *`.exe`* file or DLL. ### No Entry Point -The [/NOENTRY](noentry-no-entry-point.md)option is required for creating a resource-only DLL.Use this option to prevent LINK from linking a reference to `_main` into the DLL. +The [`/NOENTRY`](noentry-no-entry-point.md) option is required for creating a resource-only DLL. Use this option to prevent LINK from linking a reference to `_main` into the DLL. ### Set Checksum -The [/RELEASE](release-set-the-checksum.md) option sets the Checksum in the header of an .exe file. +The [`/RELEASE`](release-set-the-checksum.md) option sets the Checksum in the header of an *`.exe`* file. ### Base Address -Sets a base address for the program. ([/BASE](base-base-address.md):{address\[,size] | @filename,key}) +Sets a base address for the program. ([`/BASE:{address[,size] | @filename,key}`](base-base-address.md)) ### Randomized Base Address -Randomized Base Address. ([/DYNAMICBASE](dynamicbase-use-address-space-layout-randomization.md)\[:NO]) +Randomized Base Address. ([`/DYNAMICBASE[:NO]`](dynamicbase-use-address-space-layout-randomization.md)) ### Fixed Base Address -Creates a program that can be loaded only at its preferred base address. ([/FIXED](fixed-fixed-base-address.md)\[:NO]) +Creates a program that can be loaded only at its preferred base address. ([`/FIXED[:NO]`](fixed-fixed-base-address.md)) ### Data Execution Prevention (DEP) -Marks an executable as having been tested to be compatible with Windows Data Execution Prevention feature. ([/NXCOMPAT](nxcompat-compatible-with-data-execution-prevention.md)\[:NO]) +Marks an executable as having been tested to be compatible with Windows Data Execution Prevention feature. ([`/NXCOMPAT[:NO]`](nxcompat-compatible-with-data-execution-prevention.md)) ### Turn Off Assembly Generation -The [/NOASSEMBLY](noassembly-create-a-msil-module.md) option tells the linker to create an image for the current output file without a .NET Framework assembly. +The [`/NOASSEMBLY`](noassembly-create-a-msil-module.md) option tells the linker to create an image for the current output file without a .NET Framework assembly. ### Unload delay loaded DLL -The **UNLOAD** qualifier tells the delay-load helper function to support explicit unloading of the DLL. ([/DELAY](delay-delay-load-import-settings.md):UNLOAD) +The **`UNLOAD`** qualifier tells the delay-load helper function to support explicit unloading of the DLL. ([`/DELAY:UNLOAD`](delay-delay-load-import-settings.md)) ### Nobind delay loaded DLL -The **NOBIND** qualifier tells the linker not to include a bindable IAT in the final image. The default is to create the bindable IAT for delay-loaded DLLs. ([/DELAY](delay-delay-load-import-settings.md):NOBIND) +The **`NOBIND`** qualifier tells the linker not to include a bindable Import Address Table (IAT) in the final image. The default is to create the bindable IAT for delay-loaded DLLs. ([`/DELAY:NOBIND`](delay-delay-load-import-settings.md)) ### Import Library -Overrides the default import library name. ([/IMPLIB](implib-name-import-library.md):filename) +Overrides the default import library name. ([`/IMPLIB:filename`](implib-name-import-library.md)) ### Merge Sections -The [/MERGE](merge-combine-sections.md) option combines the first section (from) with the second section (to), naming the resulting section to. For example, /merge:.rdata=.text. +The [`/MERGE`](merge-combine-sections.md) option combines the first section with the second section, and gives the resulting section the second section name. For example, `/merge:.rdata=.text` merges the `.rdata` section with the `.text` section, and names the combined section `.text`. ### Target Machine -The [/MACHINE](machine-specify-target-platform.md) option specifies the target platform for the program. +The [`/MACHINE`](machine-specify-target-platform.md) option specifies the target platform for the program. **Choices** @@ -440,7 +452,7 @@ The [/MACHINE](machine-specify-target-platform.md) option specifies the target p ### Profile -Produces an output file that can be used with the Performance Tools profiler. Requires GenerateDebugInformation (/[/DEBUG](debug-generate-debug-info.md)) to be set. ([/PROFILE](profile-performance-tools-profiler.md)) +Produces an output file that can be used with the Performance Tools profiler. Requires the **Generate Debug Info** property be set to **GenerateDebugInformation (/DEBUG)**. ([`/PROFILE`](profile-performance-tools-profiler.md)) ### CLR Thread Attribute @@ -450,7 +462,7 @@ Explicitly specify the threading attribute for the entry point of your CLR progr - **MTA threading attribute** - Applies the MTAThreadAttribute attribute to the entry point of your program. - **STA threading attribute** - Applies the STAThreadAttribute attribute to the entry point of your program. -- **Default threading attribute** - Same as not specifying [/CLRTHREADATTRIBUTE](clrthreadattribute-set-clr-thread-attribute.md). Lets the Common Language Runtime (CLR) set the default threading attribute. +- **Default threading attribute** - Same as not specifying [`/CLRTHREADATTRIBUTE`](clrthreadattribute-set-clr-thread-attribute.md). Lets the Common Language Runtime (CLR) set the default threading attribute. ### CLR Image Type @@ -465,45 +477,49 @@ Sets the type (IJW, pure, or safe) of a CLR image. ### Key File -Specify key or key pair to sign an assembly. ([/KEYFILE](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md):filename) +Specify key or key pair to sign an assembly. ([`/KEYFILE:filename`](keyfile-specify-key-or-key-pair-to-sign-an-assembly.md)) ### Key Container -Specify a key container to sign an assembly. ([/KEYCONTAINER](keycontainer-specify-a-key-container-to-sign-an-assembly.md):name) +Specify a key container to sign an assembly. ([`/KEYCONTAINER:name`](keycontainer-specify-a-key-container-to-sign-an-assembly.md)) ### Delay Sign -Partially sign an assembly. Use [/DELAYSIGN](delaysign-partially-sign-an-assembly.md) if you only want to place the public key in the assembly. The default is /DELAYSIGN:NO. +Partially sign an assembly. Use [`/DELAYSIGN`](delaysign-partially-sign-an-assembly.md) if you only want to place the public key in the assembly. The default is **`/DELAYSIGN:NO`**. ### CLR Unmanaged Code Check -[/CLRUNMANAGEDCODECHECK](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) specifies whether the linker will apply SuppressUnmanagedCodeSecurityAttribute to linker-generated PInvoke calls from managed code into native DLLs. +[`/CLRUNMANAGEDCODECHECK`](clrunmanagedcodecheck-add-suppressunmanagedcodesecurityattribute.md) specifies whether the linker will apply `SuppressUnmanagedCodeSecurityAttribute` to linker-generated P/Invoke calls from managed code into native DLLs. ### Error Reporting -Allows you to provide internal compiler error (ICE) information directly to the Visual C++ team. +Allows you to provide internal compiler error (ICE) information directly to the Visual Studio C++ team. **Choices** - **PromptImmediately** - Prompt immediately. -- **Queue For Next Login** - Queue for next login. +- **Queue For Next Login** - Queue for next sign-in. - **Send Error Report** - Send error report. - **No Error Report** - No error report. ### SectionAlignment -The [/ALIGN](align-section-alignment.md) option specifies the alignment of each section within the linear address space of the program. The number argument is in bytes and must be a power of two. +The [`/ALIGN`](align-section-alignment.md) option specifies the alignment of each section within the linear address space of the program. The number argument is in bytes and must be a power of two. ### Preserve Last Error Code for PInvoke Calls -[/CLRSUPPORTLASTERROR](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md), which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with /clr. +[`/CLRSUPPORTLASTERROR`](clrsupportlasterror-preserve-last-error-code-for-pinvoke-calls.md), which is on by default, preserves the last error code of functions called through the P/Invoke mechanism, which allows you to call native functions in DLLS, from code compiled with **`/clr`**. **Choices** -- **Enabled** - Enable CLRSupportLastError. -- **Disabled** - Disable CLRSupportLastError. -- **System Dlls Only** - Enable CLRSupportLastError for system dlls only. +- **Enabled** - Enable **`/CLRSupportLastError`**. +- **Disabled** - Disable **`/CLRSupportLastError`**. +- **System DLLs Only** - Enable **`/CLRSupportLastError`** for system DLLs only. + +### CET Shadow Stack Compatible + +Specifies whether to mark an executable image as compatible with Control-flow Enforcement Technology (CET) Shadow Stack. ([`/CETCOMPAT`](cetcompat.md)) ### Image Has Safe Exception Handlers -When [/SAFESEH](safeseh-image-has-safe-exception-handlers.md) is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. +When [`/SAFESEH`](safeseh-image-has-safe-exception-handlers.md) is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. diff --git a/docs/build/reference/linking.md b/docs/build/reference/linking.md index 3cc16467a72..1934bea919d 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 Microsoft 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 Microsoft 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 9d00525a14d..a106200fdc4 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/ln-create-msil-module.md b/docs/build/reference/ln-create-msil-module.md index c1a892c54b2..4ec40b38bd7 100644 --- a/docs/build/reference/ln-create-msil-module.md +++ b/docs/build/reference/ln-create-msil-module.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: /LN (Create MSIL Module)" title: "/LN (Create MSIL Module)" -ms.date: "11/04/2016" +description: "Learn more about: /LN (Create MSIL Module)" +ms.date: 11/04/2016 f1_keywords: ["/LN"] helpviewer_keywords: ["-LN compiler option [C++]", "/LN compiler option [C++]"] -ms.assetid: 4f38f4f4-3176-4caf-8200-5c7585dc1ed3 --- # /LN (Create MSIL Module) -Specifies that an assembly manifest should not be inserted into the output file. +Specifies that the compiler shouldn't insert an assembly manifest into the output file. ## Syntax @@ -18,27 +17,27 @@ Specifies that an assembly manifest should not be inserted into the output file. ## Remarks -By default, **/LN** is not in effect (an assembly manifest is inserted into the output file). +By default, `/LN` isn't in effect, and the compiler inserts an assembly manifest into the output file. -When **/LN** is used, one of the [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md) options must also be used. +When you use `/LN`, you must also use one of the [/clr (Common Language Runtime Compilation)](clr-common-language-runtime-compilation.md) options. -A managed program that does not have an assembly metadata in the manifest is called a module. If you compile with [/c (Compile Without Linking)](c-compile-without-linking.md) and **/LN**, specify [/NOASSEMBLY (Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. +A managed program that doesn't have assembly metadata in the manifest is called a module. If you compile with [/c (Compile Without Linking)](c-compile-without-linking.md) and `/LN`, specify [`/NOASSEMBLY` (Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. -You may want to create modules if you want to take a component-based approach to building assemblies. That is, you can author types and compile them into modules. Then, you can generate an assembly from one or more modules. For more information on creating assemblies from modules, see [.netmodule Files as Linker Input](netmodule-files-as-linker-input.md) or [Al.exe (Assembly Linker)](/dotnet/framework/tools/al-exe-assembly-linker). +Create modules if you want to take a component-based approach to building assemblies. You can author types and compile them into modules. Then, you can generate an assembly from one or more modules. For more information on creating assemblies from modules, see [`.netmodule` Files as Linker Input](netmodule-files-as-linker-input.md) or [`Al.exe` (Assembly Linker)](/dotnet/framework/tools/al-exe-assembly-linker). -The default file extension for a module is .netmodule. +The default file extension for a module is `.netmodule`. -In releases before Visual Studio 2005, a module was created with **/clr:noAssembly**. +In releases before Visual Studio 2005, you created a module with `/clr:noAssembly`. -The MSVC linker accepts .netmodule files as input and the output file produced by the linker will be an assembly or .netmodule with no run-time dependence on any of the .netmodules that were input to the linker. For more information, see [.netmodule Files as Linker Input](netmodule-files-as-linker-input.md). +The MSVC linker accepts `.netmodule` files as input. The output file produced by the linker is an assembly or `.netmodule` with no run-time dependence on any of the `.netmodule`s that you input to the linker. For more information, see [`.netmodule` Files as Linker Input](netmodule-files-as-linker-input.md). ### To set this compiler option in the Visual Studio development environment -- Specify [/NOASSEMBLY (Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. +- Specify [`/NOASSEMBLY` (Create a MSIL Module)](noassembly-create-a-msil-module.md) in the linker phase to create the output file. ### To set this compiler option programmatically -- This compiler option cannot be changed programmatically. +- You can't change this compiler option programmatically. ## See also diff --git a/docs/build/reference/ltcg-link-time-code-generation.md b/docs/build/reference/ltcg-link-time-code-generation.md index a1869302fd7..1a220708551 100644 --- a/docs/build/reference/ltcg-link-time-code-generation.md +++ b/docs/build/reference/ltcg-link-time-code-generation.md @@ -1,8 +1,8 @@ --- title: "/LTCG (Link-time code generation)" description: "The MSVC linker option /LTCG enables link-time code generation for whole-program optimization." -ms.date: 07/08/2020 -f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGeneration", "VC.Project.VCCLWCECompilerTool.WholeProgramOptimization", "/ltcg", "VC.Project.VCCLCompilerTool.WholeProgramOptimization"] +ms.date: 09/08/2022 +f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGeneration", "VC.Project.VCCLWCECompilerTool.WholeProgramOptimization", "/ltcg", "VC.Project.VCCLCompilerTool.WholeProgramOptimization", "VC.Project.VCLinkerTool.LinkStatus"] helpviewer_keywords: ["link-time code generation in C++ linker", "/LTCG linker option", "-LTCG linker option", "LTCG linker option"] ms.assetid: 788c6f52-fdb8-40c2-90af-4026ea2cf2e2 --- @@ -76,7 +76,7 @@ The rest of this article discusses the link-time code generation done by **`/LTC The linker invokes link-time code generation if it's passed a module that was compiled by using **`/GL`** or an MSIL module (see [`.netmodule` Files as Linker Input](netmodule-files-as-linker-input.md)). If you don't explicitly specify **`/LTCG`** when you pass **`/GL`** or MSIL modules to the linker, the linker eventually detects this situation and restarts the link by using **`/LTCG`**. Explicitly specify **`/LTCG`** when you pass **`/GL`** and MSIL modules to the linker for the fastest possible build performance. -For even faster performance, use **`/LTCG:INCREMENTAL`**. This option tells the linker to reoptimize only the files affected by a source file change, instead of the entire project. This option can significantly reduce the link time required. This option isn't the same option as [incremental linking](incremental-link-incrementally.md). +For even faster performance, use **`/LTCG:INCREMENTAL`**. This option tells the linker to reoptimize only the files affected by a source file change, instead of the entire project. This option can significantly reduce the link time required. This option isn't the same option as [incremental linking](incremental-link-incrementally.md). If you remove the **`/LTCG:INCREMENTAL`** option, also remove any [`/LTCGOUT`](./ltcgout.md) option to improve build times and disk utilization. **`/LTCG`** isn't valid for use with [`/INCREMENTAL`](incremental-link-incrementally.md). @@ -101,7 +101,7 @@ Using **`/LTCG`** and **`/O2`** causes double-alignment optimization. If **`/LTCG`** and **`/O1`** are specified, double alignment isn't performed. If most of the functions in an application are compiled for speed, with a few functions compiled for size (for example, by using the [`optimize`](../../preprocessor/optimize.md) pragma), the compiler double-aligns the functions that are optimized for size if they call functions that require double alignment. -If the compiler can identify all of the call sites of a function, the compiler ignores explicit calling-convention modifiers on a function and tries to optimize the function's calling convention: +If the compiler can identify all of the call sites of a function, the compiler ignores explicit calling-convention modifiers, and tries to optimize the function's calling convention: - pass parameters in registers @@ -124,14 +124,40 @@ Modules that are compiled by using [`/GL`](gl-whole-program-optimization.md) and ### To set this compiler option in the Visual Studio development environment +The Whole Program Optimization property sets several compiler and linker options, including **`/LTCG`**. We recommend you use this property to change the settings for an entire build configuration. To set Whole Program Optimization for your project: + 1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **General** property page. -1. Modify the **Whole Program Optimization** property. +1. Modify the **Whole Program Optimization** property. Choose **OK** or **Apply** to save your changes. You can also apply **`/LTCG`** to specific builds by choosing **Build** > **Profile Guided Optimization** on the menu bar, or by choosing one of the Profile Guided Optimization options on the shortcut menu for the project. +To enable Link Time Code Generation separately or set a specific Link Time Code Generation option: + +1. Open the project **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **Linker** > **Optimization** property page. + +1. Modify the **Link Time Code Generation** property to one of the following options: + - **Default** + - **Use Fast Link Time Code Generation (LTCG:incremental)** + - **Use Link Time Code Generation (LTCG)** + - **Profile Guided Optimization - Instrument (LTCG:PGInstrument)** + - **Profile Guided Optimization - Optimization (LTCG:PGOptimize)** + - **Profile Guided Optimization - Update (LTCG:PGUpdate)** + +1. Choose **OK** or **Apply** to save your changes. + +To specify whether the linker displays a progress indicator for Link Time Code Generation: + +1. Open the project **Property Pages** dialog box. + +1. Select the **Configuration Properties** > **Linker** > **General** property page. + +1. Modify the **Link Status** property. Choose **OK** or **Apply** to save your changes. + ### To set this compiler option programmatically - See . diff --git a/docs/build/reference/ltcgout.md b/docs/build/reference/ltcgout.md new file mode 100644 index 00000000000..6a02243c24f --- /dev/null +++ b/docs/build/reference/ltcgout.md @@ -0,0 +1,40 @@ +--- +title: "/LTCGOUT (Name LTCG incremental object file)" +description: "The MSVC linker option /LTCGOUT names the incremental link-time code generation object file." +ms.date: 08/31/2022 +f1_keywords: ["VC.Project.VCLinkerTool.LinkTimeCodeGenerationObjectFile", "/ltcgout", "ltcgout"] +helpviewer_keywords: ["Name link-time code generation file in C++ linker", "/LTCGOUT linker option", "-LTCGOUT linker option", "LTCGOUT linker option"] +--- +# `/LTCGOUT` (Name LTCG incremental object file) + +The **`/LTCGOUT`** linker option tells the linker where to put the intermediate *`.iobj`* object file for incremental link-time code generation (**`/LTCG:INCREMENTAL`**). + +## Syntax + +> **`/LTCGOUT:`**\[*`pathname`*] + +### Arguments + +*`pathname`*\ +The optional destination directory and filename for the generated *`.iobj`* file. If the **`/LTCGOUT`** option isn't specified when **`/LTCG:INCREMENTAL`** is used, the filename is created by appending *`.iobj`* to the target base filename. If the **`/LTCGOUT`** option is specified with an empty *`pathname`* when **`/LTCG:INCREMENTAL`** isn't used, no *`.iobj`* file is generated. + +## Remarks + +The **`/LTCGOUT`** linker option tells the linker the path and filename to use for the intermediate *`.iobj`* object file when you specify [`/LTCG:INCREMENTAL`](./ltcg-link-time-code-generation.md). If you remove the **`/LTCG:INCREMENTAL`** option from your project, you should also remove any **`/LTCGOUT`** option. + +### To set this compiler option in the Visual Studio development environment + +1. Open the project **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **Linker** > **Optimization** property page. + +1. Modify the **Link Time Code Generation Object File** property. The option isn't set if this property is empty. + +### To set this compiler option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/makefile-preprocessing.md b/docs/build/reference/makefile-preprocessing.md index ea2e4ada348..7092de7a26c 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/manifest-create-side-by-side-assembly-manifest.md b/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md index 6b8a9ce9ea6..0cfe26b687d 100644 --- a/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md +++ b/docs/build/reference/manifest-create-side-by-side-assembly-manifest.md @@ -1,44 +1,46 @@ --- -description: "Learn more about: /MANIFEST (Create Side-by-Side Assembly Manifest)" -title: "/MANIFEST (Create Side-by-Side Assembly Manifest)" +description: "Learn more about: /MANIFEST (Create side-by-side assembly manifest)" +title: "/MANIFEST (Create side-by-side assembly manifest)" ms.date: "11/04/2016" -f1_keywords: ["VC.Project.VCLinkerTool.GenerateManifest"] +f1_keywords: ["VC.Project.VCLinkerTool.GenerateManifest", "VC.Project.VCLinkerTool.ManifestEmbed"] helpviewer_keywords: ["-MANIFEST linker option", "/MANIFEST linker option", "MANIFEST linker option"] ms.assetid: 98c52e1e-712c-4f49-b149-4d0a3501b600 --- -# /MANIFEST (Create Side-by-Side Assembly Manifest) +# `/MANIFEST` (Create side-by-side assembly manifest) -``` -/MANIFEST[:{EMBED[,ID=#]|NO}] -``` +Specifies whether the linker should create a side-by-side manifest file. + +## Syntax + +> **`/MANIFEST`**\[**`:`**{**`EMBED`**\[**`,ID=`***`resource_id`*]\|**`NO`**}] ## Remarks -/MANIFEST specifies that the linker should create a side-by-side manifest file. For more information about manifest files, see [Manifest Files Reference](/windows/win32/SbsCs/manifest-files-reference). +The **`/MANIFEST`** linker option tells the linker to create a side-by-side manifest file. For more information about manifest files, see [Manifest files reference](/windows/win32/SbsCs/manifest-files-reference). -The default is /MANIFEST. +The default is **`/MANIFEST`**. -The /MANIFEST:EMBED option specifies that the linker should embed the manifest file in the image as a resource of type RT_MANIFEST. The optional `ID` parameter is the resource ID to use for the manifest. Use a value of 1 for an executable file. Use a value of 2 for a DLL to enable it to specify private dependencies. If the `ID` parameter is not specified, the default value is 2 if the /DLL option is set; otherwise, the default value is 1. +The **`/MANIFEST:EMBED`** option specifies that the linker should embed the manifest file in the image as a resource of type `RT_MANIFEST`. The optional `ID` parameter sets the resource ID to use for the manifest. Use a *`resource_id`* value of 1 for an executable file. Use a value of 2 for a DLL to enable it to specify private dependencies. If the `ID` parameter isn't specified, the default value is 2 if the **`/DLL`** option is set; otherwise, the default value is 1. -Beginning with Visual Studio 2008, manifest files for executables contain a section that specifies User Account Control (UAC) information. If you specify /MANIFEST but specify neither [/MANIFESTUAC](manifestuac-embeds-uac-information-in-manifest.md) nor [/DLL](dll-build-a-dll.md), a default UAC fragment that has the UAC level set to *asInvoker* is inserted into the manifest. For more information about UAC levels, see [/MANIFESTUAC (Embeds UAC information in manifest)](manifestuac-embeds-uac-information-in-manifest.md). +Beginning with Visual Studio 2008, manifest files for executables contain a section that specifies User Account Control (UAC) information. If you specify **`/MANIFEST`** but don't specify either [`/MANIFESTUAC`](manifestuac-embeds-uac-information-in-manifest.md) or [`/DLL`](dll-build-a-dll.md), a default UAC fragment that has the UAC level set to *`asInvoker`* is inserted into the manifest. For more information about UAC levels, see [`/MANIFESTUAC` (Embeds UAC information in manifest)](manifestuac-embeds-uac-information-in-manifest.md). -To change the default behavior for UAC, do one of these: +To change the default behavior for UAC, set one of these options: -- Specify the /MANIFESTUAC option and set the UAC level to the desired value. +- Specify the **`/MANIFESTUAC`** option and set the UAC level to the desired value. -- Or specify the /MANIFESTUAC:NO option if you do not want to generate a UAC fragment in the manifest. +- Or, specify the **`/MANIFESTUAC:NO`** option if you don't want to generate a UAC fragment in the manifest. -If you do not specify /MANIFEST but do specify [/MANIFESTDEPENDENCY](manifestdependency-specify-manifest-dependencies.md) comments, a manifest file is created. A manifest file is not created if you specify /MANIFEST:NO. +If you don't specify **`/MANIFEST`** but do specify [`/MANIFESTDEPENDENCY`](manifestdependency-specify-manifest-dependencies.md) attributes, a manifest file is created. A manifest file isn't created if you specify **`/MANIFEST:NO`**. -If you specify /MANIFEST, the name of the manifest file is the same as the name of your output file, but with .manifest appended to the file name. For example, if your output file name is MyFile.exe, the manifest file name is MyFile.exe.manifest. If you specify /MANIFESTFILE:*name*, the name of the manifest is what you specify in *name*. +If you specify **`/MANIFEST`**, the name of the manifest file is the same as the full name of your output file, but with *`.manifest`* appended to the file name. For example, if your output file name is *`MyFile.exe`*, the manifest file name is *`MyFile.exe.manifest`*. If you specify **`/MANIFESTFILE:`***`name`*, the name of the manifest is what you specify in *`name`*. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Manifest File** property page. -1. Modify the **Generate Manifest** property. +1. Modify the **Generate Manifest** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -46,5 +48,9 @@ If you specify /MANIFEST, the name of the manifest file is the same as the name ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[Manifest files reference](/windows/win32/SbsCs/manifest-files-reference)\ +[`/MANIFESTDEPENDENCY` (Specify manifest dependencies)](./manifestdependency-specify-manifest-dependencies.md)\ +[`/MANIFESTFILE` (Name manifest file)](./manifestfile-name-manifest-file.md)\ +[`/MANIFESTUAC` (Embeds UAC information in manifest)](./manifestuac-embeds-uac-information-in-manifest.md)\ +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/manifest-tool-property-pages.md b/docs/build/reference/manifest-tool-property-pages.md index 144a37acfb9..fc70cc16669 100644 --- a/docs/build/reference/manifest-tool-property-pages.md +++ b/docs/build/reference/manifest-tool-property-pages.md @@ -22,7 +22,7 @@ f1_keywords: - VC.Project.VCManifestTool.ReplacementsFile - VC.Project.VCManifestTool.UpdateFileHashes - VC.Project.VCManifestTool.UpdateFileHashesSearchPath - - vc.project.AdditionalOptionsPage + - VC.Project.VCManifestTool.EnableSegmentHeap --- # Manifest Tool Property Pages @@ -98,6 +98,10 @@ Specifies whether the application is DPI-aware. By default, the setting is **Yes - **High DPI Aware** - **Per Monitor High DPI Aware** +### Segment Heap + +Specifies whether the application utilizes the Segment Heap. When enabled, applications benefit from improved memory efficiency, reduced fragmentation, and enhanced memory security. For new C++ projects, the setting is **Yes** by default. + ## Isolated COM Property Page For more information about isolated COM, see [Isolated applications](/windows/win32/SbsCs/isolated-applications) and [How to: Build isolated applications to consume COM components](../how-to-build-isolated-applications-to-consume-com-components.md). diff --git a/docs/build/reference/manifestfile-name-manifest-file.md b/docs/build/reference/manifestfile-name-manifest-file.md index acd17845b98..32a06f368ed 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 3b71cd47dfa..df8b326f7d6 100644 --- a/docs/build/reference/manifestinput-specify-manifest-input.md +++ b/docs/build/reference/manifestinput-specify-manifest-input.md @@ -1,8 +1,8 @@ --- description: "Learn more about: /MANIFESTINPUT (Specify Manifest Input)" title: "/MANIFESTINPUT (Specify Manifest Input)" -ms.date: "07/24/2019" -ms.assetid: a0b0c21e-1f9b-4d8c-bb3f-178f57fa7f1b +ms.date: 03/27/2025 +f1_keywords: ["VC.Project.VCLinkerTool.ManifestInput"] --- # /MANIFESTINPUT (Specify Manifest Input) @@ -10,22 +10,20 @@ Specifies a manifest input file to include in the manifest that's embedded in th ## Syntax -``` -/MANIFESTINPUT:filename -``` +> `/MANIFESTINPUT:`*filename* ### Parameters -*filename*
-The manifest file to include in the embedded manifest. +*filename*\ +The manifest file to include in the embedded manifest. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The **/MANIFESTINPUT** option specifies the path of an input file to use to create the embedded manifest in an executable image. If you have multiple manifest input files, use the switch multiple times—once for each input file. The manifest input files are merged to create the embedded manifest. This option requires the **/MANIFEST:EMBED** option. +The **`/MANIFESTINPUT`** option specifies the path of an input file to use to create the embedded manifest in an executable image. If you have multiple manifest input files, use the switch multiple times: once for each input file. The manifest input files are merged to create the embedded manifest. This option requires the **`/MANIFEST:EMBED`** option. -This option can't be set directly in Visual Studio. Instead, use the **Additional Manifest Files** property of the project to specify additional manifest files to include. For more information, see [Manifest Tool Property Pages](manifest-tool-property-pages.md). +This option can't be set directly in Visual Studio. Instead, use the **Additional Manifest Files** property of the project to specify other manifest files to include. For more information, see [Manifest Tool Property Pages](manifest-tool-property-pages.md). ## See also -[MSVC linker reference](linking.md)
+[MSVC linker reference](linking.md)\ [MSVC Linker Options](linker-options.md) diff --git a/docs/build/reference/md-mt-ld-use-run-time-library.md b/docs/build/reference/md-mt-ld-use-run-time-library.md index 0db8d589cbe..0867d33ed05 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/media/create-project.png b/docs/build/reference/media/create-project.png new file mode 100644 index 00000000000..e3398e80f7d Binary files /dev/null and b/docs/build/reference/media/create-project.png differ diff --git a/docs/build/reference/media/file-new-project.png b/docs/build/reference/media/file-new-project.png new file mode 100644 index 00000000000..d42284e46a5 Binary files /dev/null and b/docs/build/reference/media/file-new-project.png differ 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 a8599cceffd..57eab588697 100644 --- a/docs/build/reference/microsoft-extensions-to-c-and-cpp.md +++ b/docs/build/reference/microsoft-extensions-to-c-and-cpp.md @@ -6,7 +6,7 @@ helpviewer_keywords: ["or_eq operator", "~ operator, extensions to C/C++", "& op --- # Microsoft extensions to C and C++ -Microsoft Visual C++ (MSVC) extends the C and C++ language standards in several ways, detailed in this article. +Microsoft C++ (MSVC) extends the C and C++ language standards in several ways, detailed in this article. The MSVC C++ compiler defaults to support for ISO C++14 with some ISO C++17 features and some Microsoft-specific language extensions. For more information on supported features, see [Microsoft C/C++ language conformance by Visual Studio version](../../overview/visual-cpp-language-conformance.md). You can use the **`/std`** compiler option to enable full support for ISO C++17 and ISO C++20 language features. For more information, see [`/std` (Specify language standard version)](std-specify-language-standard-version.md). @@ -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/midl-property-pages.md b/docs/build/reference/midl-property-pages.md index 612fa243071..24a198a8284 100644 --- a/docs/build/reference/midl-property-pages.md +++ b/docs/build/reference/midl-property-pages.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: MIDL Property Pages" title: "MIDL Compiler Property Pages" -ms.date: "07/24/2019" +description: "Learn more about: MIDL Property Pages" +ms.date: 07/24/2019 ms.topic: "article" -ms.assetid: 57498a01-fccc-4a0e-a036-6ff702f83126 f1_keywords: - VC.Project.VCMidlTool.PreprocessorDefinitions - VC.Project.VCMidlTool.AdditionalIncludeDirectories @@ -47,7 +46,6 @@ f1_keywords: - VC.Project.VCMidlTool.StructMemberAlignment - VC.Project.VCMidlTool.RedirectOutputAndErrors - VC.Project.VCMidlTool.MinimumTargetSystem - - vc.project.AdditionalOptionsPage --- # MIDL Property Pages @@ -113,6 +111,9 @@ Specifies the default character type of the C compiler that will be used to comp Specifies which environment to target ([/env](/windows/win32/midl/-env) arm32|win32|ia64|x64). +> [!NOTE] +> Starting with Visual Studio 2026, the **`/env:arm32`** option is deprecated and removed. If you need to target ARM32, use the Visual Studio 2022 v143 build tools. + **Choices** - **Not Set** - Win32 @@ -124,7 +125,7 @@ Specifies which environment to target ([/env](/windows/win32/midl/-env) arm32|wi ### Generate Stubless Proxies -Generate fully interpreted stubs with extensions and stubless proxies for object interfaces ([/Oicf](/windows/win32/midl/-oi), [/Oif](/windows/win32/midl/-oi) ). +Generate fully interpreted stubs with extensions and stubless proxies for object interfaces ([/Oicf](/windows/win32/midl/-oi), [/Oif](/windows/win32/midl/-oi)). ### Suppress Compiler Warnings diff --git a/docs/build/reference/module-exportheader.md b/docs/build/reference/module-exportheader.md index a6e1cc2cf3d..f4f558ca283 100644 --- a/docs/build/reference/module-exportheader.md +++ b/docs/build/reference/module-exportheader.md @@ -19,7 +19,7 @@ Tells the compiler to create the header units specified by the input arguments. ### Arguments -The argument to `/exportHeader` is a `/headerName` command-line option that specifies the name, *`header-name`*, of the header file to export. +The argument to `/exportHeader` is a `/headerName` command-line option that specifies the name, *`header-name`*, of the header file to export. ## Remarks @@ -53,11 +53,19 @@ cl . . . /std:c++latest /exportHeader /headerName:quote util/util.h ### To set this compiler option in the Visual Studio development environment -You normally shouldn't set this in the Visual Studio development environment. It is set by the build system. +You normally shouldn't set this option in the Visual Studio development environment unless you use a different extension for your header files. By default, the build system applies this option to compiled files that have a *`.h`* extension, or no extension. + +1. To apply the **`/exportHeader`** option to a file explicitly in the IDE, select the file in **Solution Explorer**. Right-click to open the context menu and select **Properties** to open the Property Pages dialog. + +1. Set the **Configuration** dropdown to **All Configurations**. Set the **Platform** dropdown to **All Platforms**. + +1. Open the **Configuration Properties** > **C/C++** > **Advanced** property page. + +1. Use the dropdown control to modify the **Compile As** property to **Compile as C++ Header Unit (/exportHeader)**. Choose **OK** or **Apply** to save your changes. ## See also -[`/headerName (Build a header unit from the specified header)`](headername.md)\ +[`/headerName` (Build a header unit from the specified header)](headername.md)\ [`/headerUnit` (Use header unit IFC)](headerunit.md)\ [`/reference` (Use named module IFC)](module-reference.md)\ [`/translateInclude` (Translate include directives into import directives)](translateinclude.md) diff --git a/docs/build/reference/msbuild-reference-cpp.md b/docs/build/reference/msbuild-reference-cpp.md index e779a699b25..bbc889a922d 100644 --- a/docs/build/reference/msbuild-reference-cpp.md +++ b/docs/build/reference/msbuild-reference-cpp.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: MSBuild reference for C++ projects" title: "MSBuild reference for C++ projects in Visual Studio" -ms.date: "12/08/2018" +description: "Learn more about: MSBuild reference for C++ projects" +ms.date: 12/08/2018 helpviewer_keywords: ["MSBuild reference [C++]"] --- # MSBuild reference for C++ projects @@ -12,25 +12,25 @@ If for some reason you wish to use MSBuild directly from the command line, see [ ## In this section -[MSBuild internals for C++ projects](msbuild-visual-cpp-overview.md)
+[MSBuild internals for C++ projects](msbuild-visual-cpp-overview.md)\ Information about how properties and targets are stored and consumed. -[Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md)
+[Common macros for build commands and properties](common-macros-for-build-commands-and-properties.md)\ Describes macros (compile-time constants) that can be used to define properties such as paths and product versions. -[File types created for C++ projects](file-types-created-for-visual-cpp-projects.md)
+[File types created for C++ projects](file-types-created-for-visual-cpp-projects.md)\ Describes the various kinds of files that Visual Studio creates for different project types. -[Visual Studio C++ project templates](visual-cpp-project-types.md)
+[Visual Studio C++ project templates](visual-cpp-project-types.md)\ Describes the MSBuild-based project types that are available for C++. -[C++ new item templates](using-visual-cpp-add-new-item-templates.md)
+[C++ new item templates](using-visual-cpp-add-new-item-templates.md)\ Describes source files and other items you can add to a Visual Studio project. -[Precompiled header files](../creating-precompiled-header-files.md) +[Precompiled header files](../creating-precompiled-header-files.md)\ How to use precompiled header files and how to create your own custom precompiled code to speed up build times. -[Visual Studio project property reference](property-pages-visual-cpp.md)
+[Visual Studio project property reference](property-pages-visual-cpp.md)\ Reference documentation for project properties that are set in the Visual Studio IDE. ## See also diff --git a/docs/build/reference/msbuild-visual-cpp-overview.md b/docs/build/reference/msbuild-visual-cpp-overview.md index e614f2f98a6..7ea809fa747 100644 --- a/docs/build/reference/msbuild-visual-cpp-overview.md +++ b/docs/build/reference/msbuild-visual-cpp-overview.md @@ -84,7 +84,7 @@ To use MSBuild effectively, it helps to know which properties and targets are us ### `PlatformToolset` property -The `PlatformToolset` property determines which MSVC toolset is used in the build. By default, the current toolset is used. When this property is set, its value gets concatenated with literal strings to form the path. It's the directory that contains the property and target files required to build a project for a particular platform. The platform toolset must be installed to build by using that platform toolset version. +The `PlatformToolset` property determines which Microsoft C++ (MSVC) toolset is used in the build. By default, the current toolset is used. When this property is set, its value gets concatenated with literal strings to form the path. It's the directory that contains the property and target files required to build a project for a particular platform. The platform toolset must be installed to build by using that platform toolset version. For example, set the `PlatformToolset` property to `v140` to use Visual Studio 2015 tools and libraries to build your application: diff --git a/docs/build/reference/natvis-add-natvis-to-pdb.md b/docs/build/reference/natvis-add-natvis-to-pdb.md index 326072d5fa4..dbc59b4eb04 100644 --- a/docs/build/reference/natvis-add-natvis-to-pdb.md +++ b/docs/build/reference/natvis-add-natvis-to-pdb.md @@ -1,39 +1,43 @@ --- description: "Learn more about: /NATVIS (Add Natvis to PDB)" title: "/NATVIS (Add Natvis to PDB)" -ms.date: "08/10/2017" -f1_keywords: ["/natvis"] +ms.date: 09/08/2022 +f1_keywords: ["/natvis", "natvis"] helpviewer_keywords: ["NATVIS linker option", "/NATVIS linker option", "-NATVIS linker option", "Add Natvis file to PDB"] ms.assetid: 8747fc0c-701a-4796-bb4d-818ab4465cca --- -# /NATVIS (Add Natvis to PDB) +# `/NATVIS` (Add Natvis to PDB) -> /NATVIS:*filename* +Specifies a debugger visualization file (a Natvis file) to embed in the PDB file generated by the linker. + +## Syntax + +> **`/NATVIS:`***`filename`* ## Parameters -*filename*
-A Natvis file to add to the PDB file. It embeds the debugger visualizations in the Natvis file into the PDB. +*`filename`*\ +The pathname for a Natvis file to add to the PDB file. It embeds the debugger visualizations in the Natvis file into the PDB. ## Remarks -The /NATVIS option embeds the debugger visualizations defined in the Natvis file *filename* into the PDB file generated by LINK. This allows the debugger to display the visualizations independently of the .natvis file. You can use multiple /NATVIS options to embed more than one Natvis file in the generated PDB file. +The **`/NATVIS`** linker option embeds the debugger visualizations defined in the Natvis file *`filename`* into the PDB file generated by LINK. A Natvis file has a *`.natvis`* extension. Embedding the information allows the debugger to display the visualizations independently of the Natvis file. You can use multiple **`/NATVIS`** options to embed more than one Natvis file in the generated PDB file. For more information on how to create and use Natvis files, see [Create custom views of native objects in the Visual Studio debugger](/visualstudio/debugger/create-custom-views-of-native-objects). -LINK ignores /NATVIS when a PDB file is not created by using a [/DEBUG](debug-generate-debug-info.md) option. For information on creation and use of .natvis files, see [Create custom views of native objects in the Visual Studio debugger](/visualstudio/debugger/create-custom-views-of-native-objects). +LINK ignores **`/NATVIS`** when a PDB file isn't created by using a [`/DEBUG`](debug-generate-debug-info.md) option. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Add the *`/NATVIS`* option to the **Additional Options** text box. +1. Add the *`/NATVIS`* option to the **Additional Options** text box. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -- This option does not have a programmatic equivalent. +- See . ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/netmodule-files-as-linker-input.md b/docs/build/reference/netmodule-files-as-linker-input.md index 6b5af46bb6b..5bd54dc8df8 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 c44c478a155..d726226b5a1 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 00000000000..a63675b5cde --- /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 f5c94dc4a63..646e515a1e3 100644 --- a/docs/build/reference/nodefaultlib-ignore-libraries.md +++ b/docs/build/reference/nodefaultlib-ignore-libraries.md @@ -1,41 +1,41 @@ --- -description: "Learn more about: /NODEFAULTLIB (Ignore Libraries)" -title: "/NODEFAULTLIB (Ignore Libraries)" -ms.date: "03/26/2019" -f1_keywords: ["VC.Project.VCLinkerTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLinkerTool.OVERWRITEDefaultLibraryNames", "/nodefaultlib"] +description: "Learn more about: /NODEFAULTLIB (Ignore libraries)" +title: "/NODEFAULTLIB (Ignore libraries)" +ms.date: 04/16/2025 +f1_keywords: ["VC.Project.VCLinkerTool.IgnoreAllDefaultLibraries", "VC.Project.VCLinkerTool.IgnoreDefaultLibraryNames", "VC.Project.VCLinkerTool.OVERWRITEAllDefaultLibraries", "VC.Project.VCLinkerTool.OVERWRITEDefaultLibraryNames", "/nodefaultlib"] helpviewer_keywords: ["default libraries, removing", "-NODEFAULTLIB linker option", "libraries, ignore", "NODEFAULTLIB linker option", "/NODEFAULTLIB linker option", "ignore libraries linker option"] -ms.assetid: 7270b673-6711-468e-97a7-c2925ac2be6e --- -# /NODEFAULTLIB (Ignore Libraries) +# `/NODEFAULTLIB` (Ignore Libraries) -> **/NODEFAULTLIB**[__:__*library*] +Unless an optional library name is provided, the `/NODEFAULTLIB` linker option removes all libraries not explicitly specified on the linker command-line. This also includes `#pragma`, `cl.exe` command-line switches, libs referenced by other libs, and so on. + +## Syntax + +> **`/NODEFAULTLIB`**\[**`:`***`library`*] ## Arguments -*library*
-A library that you want the linker to ignore when it resolves external references. +*`library`*\ +An optional library name that you want the linker to ignore when it resolves external references. ## Remarks -The /NODEFAULTLIB option tells the linker to remove one or more default libraries from the list of libraries it searches when resolving external references. - -To create an .obj file that contains no references to default libraries, use [/Zl (Omit Default Library Name)](zl-omit-default-library-name.md). +To create an *`.obj`* file that contains no references to default libraries, use [`/Zl` (Omit default library name)](zl-omit-default-library-name.md). -By default, /NODEFAULTLIB removes all default libraries from the list of libraries it searches when resolving external references. The optional *library* parameter lets you remove a specified library from the list of libraries it searches when resolving external references. Specify one /NODEFAULTLIB option for each library you want to exclude. +By default, **`/NODEFAULTLIB`** removes all default libraries from the list of libraries it searches when resolving external references. The optional *`library`* parameter lets you remove a specified library from the list of libraries it searches when resolving external references. Specify one **`/NODEFAULTLIB`** option for each library you want to exclude. -The linker resolves references to external definitions by searching first in libraries that you explicitly specify, then in default libraries specified with the [/DEFAULTLIB:](defaultlib-specify-default-library.md) option, and then in default libraries named in .obj files. +The linker resolves references to external definitions by searching first in libraries that you explicitly specify, then in default libraries specified by the [`/DEFAULTLIB`](defaultlib-specify-default-library.md) option, and then in default libraries named in *`.obj`* files. -/NODEFAULTLIB:*library* overrides /DEFAULTLIB:*library* when the same *library* name is specified in both. +**`/NODEFAULTLIB:`***`library`* overrides **`/DEFAULTLIB:`***`library`* when the same *`library`* name is specified in both. -If you use /NODEFAULTLIB to build your program without the C run-time library, you may have to also use [/ENTRY](entry-entry-point-symbol.md) to specify the entry-point function in your program. For more information, see [CRT Library Features](../../c-runtime-library/crt-library-features.md). +If you use **`/NODEFAULTLIB`** to build your program without the C run-time library, you may also have to use the [`/ENTRY`](entry-entry-point-symbol.md) option to specify the entry-point function in your program. For more information, see [CRT library features](../../c-runtime-library/crt-library-features.md). ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **Linker** > **Input** property page. - -1. Select the **Ignore All Default Libraries** property. Or, specify a semicolon-separated list of the libraries you want to ignore in the **Ignore Specific Default Libraries** property. The **Command Line** property page shows the effect of the changes you make to these properties. +1. Modify the **Ignore All Default Libraries** property. Or, specify a semicolon-separated list of the libraries you want to ignore in the **Ignore Specific Default Libraries** property. The **Linker** > **Command Line** property page shows the effect of the changes you make to these properties. +1. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -43,5 +43,5 @@ If you use /NODEFAULTLIB to build your program without the C run-time library, y ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md b/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md index df6bf589671..d4dce169d76 100644 --- a/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md +++ b/docs/build/reference/nologo-suppress-startup-banner-c-cpp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /nologo (Suppress Startup Banner) (C/C++)" title: "/nologo (Suppress Startup Banner) (C/C++)" -ms.date: "11/04/2016" +description: "Learn more about: /nologo (Suppress Startup Banner) (C/C++)" +ms.date: 11/04/2016 f1_keywords: ["VC.Project.VCCLWCECompilerTool.SuppressStartupBanner", "VC.Project.VCCLCompilerTool.SuppressStartupBanner"] helpviewer_keywords: ["-nologo compiler option [C++]", "/nologo compiler option [C++]", "nologo compiler option [C++]", "banners, suppressing startup"] -ms.assetid: 75930d8b-b11c-4db8-99e5-b52f97da0693 --- # /nologo (Suppress Startup Banner) (C/C++) @@ -16,8 +15,6 @@ Suppresses the display of the copyright banner when the compiler starts up and d /nologo ``` -## Remarks - ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). diff --git a/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md b/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md index c723f7ca02d..b8497a078d6 100644 --- a/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md +++ b/docs/build/reference/nxcompat-compatible-with-data-execution-prevention.md @@ -1,23 +1,23 @@ --- title: "/NXCOMPAT (Compatible with Data Execution Prevention)" description: "Describes the Microsoft C/C++ (MSVC) /NXCOMPAT linker option, which marks an executable as compatible with Data Execution Prevention (DEP)." -ms.date: "12/17/2019" -f1_keywords: ["/NXCOMPAT"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.DataExecutionPrevention", "/NXCOMPAT"] helpviewer_keywords: ["/NXCOMPAT linker option", "-NXCOMPAT linker option", "NXCOMPAT linker option"] --- -# /NXCOMPAT (Compatible with Data Execution Prevention) +# `/NXCOMPAT` (Compatible with Data Execution Prevention) Indicates that an executable is compatible with the Windows Data Execution Prevention feature. ## Syntax -> **/NXCOMPAT**[**:NO**] +> **`/NXCOMPAT`**[**`:NO`**] ## Remarks -By default, **/NXCOMPAT** is on. +By default, **`/NXCOMPAT`** is on. -**/NXCOMPAT:NO** can be used to explicitly specify an executable as incompatible with Data Execution Prevention. +**`/NXCOMPAT:NO`** can be used to explicitly specify an executable as incompatible with Data Execution Prevention. For more information about Data Execution Prevention, see these articles: @@ -27,17 +27,17 @@ For more information about Data Execution Prevention, see these articles: ### To set this linker option in Visual Studio -1. Open the project **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Choose the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option in the **Additional Options** box. Choose **OK** or **Apply** to apply the change. +1. Modify the **Data Execution Prevention (DEP)** property. Choose **OK** or **Apply** to apply the change. ### To set this linker option programmatically -- See . +- See . ## See also [MSVC linker reference](linking.md)\ -[MSVC Linker Options](linker-options.md) +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/oi-generate-intrinsic-functions.md b/docs/build/reference/oi-generate-intrinsic-functions.md index 7eb1b3e971b..6903538cac1 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,37 +17,34 @@ 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** +You can use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic functions, or [function (C/C++)](../../preprocessor/function-c-cpp.md) to explicitly force a function call. -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. +### x86-specific remarks -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. +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. -**END x86 Specific** +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 also use [intrinsic](../../preprocessor/intrinsic.md) to create intrinsic functions, or [function (C/C++)](../../preprocessor/function-c-cpp.md) to explicitly force a function call. - -### To set this compiler option in the Visual Studio development environment +## 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 +## To set this compiler option programmatically - See . ## 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 388695f4262..3e1687f5a20 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 f43bb724dc7..f671586c63d 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/output-file-f-options.md b/docs/build/reference/output-file-f-options.md index 601eba50f41..da20a94a487 100644 --- a/docs/build/reference/output-file-f-options.md +++ b/docs/build/reference/output-file-f-options.md @@ -1,37 +1,40 @@ --- +title: "Output-File (/F) Options" description: "Learn more about: Output-File (/F) Options" -title: "Output-File (-F) Options" -ms.date: "11/04/2016" +ms.date: 11/04/2016 helpviewer_keywords: ["output files", "output files, compiler options [C++]", "cl.exe compiler, output files"] -ms.assetid: f6367f30-2710-4178-b43a-639eed824acb --- -# Output-File (/F) Options +# Output-File (`/F`) Options The output-file options create or rename output files. They affect all C or C++ source files specified in the CL environment variable, on the command line, or in any command file. -- [/FA, /Fa (Listing File)](fa-fa-listing-file.md) +- [`/FA`, `/Fa` (Listing File)](fa-fa-listing-file.md) - [Specifying the Pathname](specifying-the-pathname.md) -- [/Fd (Name PDB File)](fd-program-database-file-name.md) +- [`/FD` (IDE Minimal Rebuild)](fd-ide-minimal-rebuild.md) -- [/Fe (Name EXE File)](fe-name-exe-file.md) +- [`/Fd` (Name PDB File)](fd-program-database-file-name.md) -- [/FI (Name Forced Include File)](fi-name-forced-include-file.md) +- [`/Fe` (Name EXE File)](fe-name-exe-file.md) -- [/Fm (Name Mapfile)](fm-name-mapfile.md) +- [`/Fi` (Preprocess output file name)](fi-preprocess-output-file-name.md) -- [/Fo (Name Object File)](fo-object-file-name.md) +- [`/FI` (Name Forced Include File)](fi-name-forced-include-file.md) -- [/Fp (Name .pch File)](fp-name-dot-pch-file.md) +- [`/Fm` (Name Mapfile)](fm-name-mapfile.md) -- [/FR, /Fr (Create .sbr File)](fr-fr-create-dot-sbr-file.md) +- [`/Fo` (Name Object File)](fo-object-file-name.md) -- [/FU (Name Forced #using File)](fu-name-forced-hash-using-file.md) +- [`/Fp` (Name .pch File)](fp-name-dot-pch-file.md) -- [/Fx (Merge Injected Code)](fx-merge-injected-code.md) +- [`/FR`, `/Fr` (Create .sbr File)](fr-fr-create-dot-sbr-file.md) + +- [`/FU` (Name Forced #using File)](fu-name-forced-hash-using-file.md) + +- [`/Fx` (Merge Injected Code)](fx-merge-injected-code.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/p-preprocess-to-a-file.md b/docs/build/reference/p-preprocess-to-a-file.md index e65e5a00d03..3f8c51279bc 100644 --- a/docs/build/reference/p-preprocess-to-a-file.md +++ b/docs/build/reference/p-preprocess-to-a-file.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /P (Preprocess to a File)" title: "/P (Preprocess to a File)" -ms.date: "11/04/2016" +description: "Learn more about: /P (Preprocess to a File)" +ms.date: 11/04/2016 f1_keywords: ["VC.Project.VCCLCompilerTool.GeneratePreprocessedFile", "/p", "VC.Project.VCCLWCECompilerTool.GeneratePreprocessedFile"] helpviewer_keywords: ["/P compiler option [C++]", "-P compiler option [C++]", "P compiler option [C++]", "output files, preprocessor", "preprocessing output files"] -ms.assetid: 123ee54f-8219-4a6f-9876-4227023d83fc --- # /P (Preprocess to a File) @@ -40,7 +39,7 @@ The **/P** option suppresses compilation. It does not produce an .obj file, even The following command line preprocesses `ADD.C`, preserves comments, adds `#line` directives, and writes the result to a file, `ADD.I`: -``` +```cmd CL /P /C ADD.C ``` diff --git a/docs/build/reference/pdb-use-program-database.md b/docs/build/reference/pdb-use-program-database.md index 3801076b0d2..9d61dad7b18 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 654278e5378..6c198f78155 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 f97ea479135..b88420f081d 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 c301dcc58ed..3a182cb84d7 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: 06/29/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. @@ -52,27 +53,45 @@ void func(int default); // Error C2321: 'default' is a keyword, and ```cpp template -struct B { - void f(); +struct B +{ + void f() {} + template + struct S { void operator()(){ return; } }; }; template struct D : public B // B is a dependent base because its type // depends on the type of T. { - // One possible fix is to uncomment the following line. - // If this is a type, don't forget the 'typename' keyword. + // One possible fix for non-template members and function + // template members is a using statement: // using B::f; + // If it's a type, don't forget the 'typename' keyword. - void g() { + void g() + { f(); // error C3861: 'f': identifier not found - // Another fix is to change it to 'this->f();' + // Another fix is to change the call to 'this->f();' + } + + void h() + { + S s; // C2065 or C3878 + // Since template S is dependent, the type must be qualified + // with the `typename` keyword. + // To fix, replace the declaration of s with: + // typename B::template S s; + // Or, use this: + // typename D::template S s; + s(); } }; void h() { D d; d.g(); + d.h(); } ``` 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 219bd6b0231..746755ec18f 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" +description: "Learn more about: /PGD (Specify Database for Profile-Guided Optimizations)" +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/profile-performance-tools-profiler.md b/docs/build/reference/profile-performance-tools-profiler.md index d1273f084d1..bff93bcfd78 100644 --- a/docs/build/reference/profile-performance-tools-profiler.md +++ b/docs/build/reference/profile-performance-tools-profiler.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: /PROFILE (Performance Tools Profiler)" title: "/PROFILE (Performance Tools Profiler)" +description: "Learn more about: /PROFILE (Performance Tools Profiler)" ms.date: 10/13/2021 f1_keywords: ["VC.Project.VCLinkerTool.Profile"] helpviewer_keywords: ["-PROFILE linker option", "/PROFILE linker option"] @@ -57,7 +57,7 @@ Because a **CMake** project doesn't have the usual **Property Pages** support, t 1. Rebuild your solution. -## See Also +## See also [MSVC linker reference](linking.md)\ [MSVC linker options](linker-options.md) diff --git a/docs/build/reference/property-page-xml-files.md b/docs/build/reference/property-page-xml-files.md index b7d32df9fbf..7ed46f8cc98 100644 --- a/docs/build/reference/property-page-xml-files.md +++ b/docs/build/reference/property-page-xml-files.md @@ -128,7 +128,7 @@ A **``** element is the root node in the XML file. It can have many attrib - `Label=""` indicates that when the properties are written as `ItemDefinition` metadata, the label of the parent ItemDefinitionGroup will be empty (every MSBuild element can have a Label). Visual Studio 2017 and later use labeled groups to navigate the .vcxproj project file. The groups that contain most `Rule` properties have an empty string as a label. - - `HasConfigurationCondition="true"` tells the project system to affix a configuration condition to the value so that it takes effect only for the current project configuration (the condition could be affixed to the parent group or the value itself). For example, open the property pages off the project node and set the value of the property **Treat Warnings As Error** under **Configuration Properties > C/C++ General** to "Yes". The following value is written to the project file. Notice the configuration condition attached to the parent ItemDefinitionGroup. + - `HasConfigurationCondition="true"` tells the project system to affix a configuration condition to the value so that it takes effect only for the current project configuration (the condition could be affixed to the parent group or the value itself). For example, open the property pages off the project node and set the value of the property **Treat Warnings As Error** under **Configuration Properties > C/C++ General** to "Yes". The following value is written to the project file. Notice the configuration condition attached to the parent ItemDefinitionGroup. ```xml diff --git a/docs/build/reference/qspectre-jmp.md b/docs/build/reference/qspectre-jmp.md new file mode 100644 index 00000000000..b04d970480a --- /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 063058a2648..0d0640ab814 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 6d37e74ffdd..728c2cad9b3 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 c8d209b16c2..2eace5222a8 100644 --- a/docs/build/reference/qspectre.md +++ b/docs/build/reference/qspectre.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: /Qspectre" title: "/Qspectre" +description: "Learn more about: /Qspectre" ms.date: 07/02/2021 f1_keywords: ["VC.Project.VCCLCompilerTool.SpectreMitigation"] helpviewer_keywords: ["/Qspectre"] --- -# /Qspectre +# `/Qspectre` Specifies compiler generation of instructions to mitigate certain Spectre variant 1 security vulnerabilities. @@ -23,7 +23,7 @@ The **`/Qspectre`** option is off by default. In its initial release, the **`/Qspectre`** option only worked on optimized code. Starting in Visual Studio 2017 version 15.7, the **`/Qspectre`** option is supported at all optimization levels. -Several Microsoft C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ Runtime Libraries Redistributable haven't been modified. +Several Microsoft C++ libraries are also available in versions with Spectre mitigation. The Spectre-mitigated libraries for Visual Studio can be downloaded in the Visual Studio Installer. They're found in the **Individual Components** tab under **Compilers, build tools, and runtimes**, and have "Libs for Spectre" in the name. Both DLL and static runtime libraries with mitigation enabled are available for a subset of the Visual C++ runtimes: VC++ start-up code, vcruntime140, msvcp140, concrt140, and vcamp140. The DLLs are supported for application-local deployment only. The contents of the Visual C++ Runtime Libraries Redistributable are unmodified. You can also install Spectre-mitigated libraries for MFC and ATL. They're found in the **Individual Components** tab under **SDKs, libraries, and frameworks**. @@ -38,7 +38,7 @@ If your code operates on data that crosses a trust boundary, then we recommend y The **`/Qspectre`** option is available starting in Visual Studio 2017 version 15.5.5, and in all updates to Microsoft C/C++ compilers (MSVC) made on or after January 23, 2018. Use the Visual Studio Installer to update the compiler, and to install the Spectre-mitigated libraries as individual components. The **`/Qspectre`** option is also available in Visual Studio 2015 Update 3 through a patch. For more information, see [KB 4338871](https://support.microsoft.com/help/4338871). -All versions of Visual Studio 2017 version 15.5, and all Previews of Visual Studio 2017 version 15.6. include an undocumented option, **/`d2guardspecload`**. It's equivalent to the initial behavior of **`/Qspectre`**. You can use **`/d2guardspecload`** to apply the same mitigations to your code in these versions of the compiler. We recommend you update your build to use **`/Qspectre`** in compilers that support the option. The **`/Qspectre`** option may also support new mitigations in later versions of the compiler. +All versions of Visual Studio 2017 version 15.5, and all Previews of Visual Studio 2017 version 15.6. include an undocumented option, **`/d2guardspecload`**. It's equivalent to the initial behavior of **`/Qspectre`**. You can use **`/d2guardspecload`** to apply the same mitigations to your code in these versions of the compiler. We recommend you update your build to use **`/Qspectre`** in compilers that support the option. The **`/Qspectre`** option may also support new mitigations in later versions of the compiler. ### Effect @@ -72,7 +72,7 @@ The default MSBuild-based project system in the Visual Studio IDE lets you speci ::: moniker range="msvc-150" -The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found". If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause. +The default MSBuild-based project system in the Visual Studio IDE lets you specify a [Spectre Mitigation](./c-cpp-prop-page.md#spectre-mitigation) property for your projects. This property sets the **`/Qspectre`** compiler option and changes the library paths to link the Spectre-mitigated runtime libraries. If these libraries aren't installed when you build your code, the build system reports warning MSB8038: "Spectre mitigation is enabled but Spectre mitigated libraries are not found." If your MFC or ATL code fails to build, and the linker reports an error such as "fatal error LNK1104: cannot open file 'oldnames.lib'", these missing libraries may be the cause. ::: moniker-end @@ -134,6 +134,9 @@ For an overview of Spectre vulnerabilities addressed by the MSVC mitigations, se ## See also +[`/Qspectre-jmp`](qspectre-jmp.md)\ +[`/Qspectre-load`](qspectre-load.md)\ +[`/Qspectre-load-cf`](qspectre-load-cf.md)\ [`/Q` options (Low-level operations)](q-options-low-level-operations.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/resources-property-pages.md b/docs/build/reference/resources-property-pages.md index 0f09208f2b8..cea6e5ba335 100644 --- a/docs/build/reference/resources-property-pages.md +++ b/docs/build/reference/resources-property-pages.md @@ -14,7 +14,6 @@ f1_keywords: - VC.Project.VCResourceCompilerTool.SuppressStartupBanner - VC.Project.VCResourceCompilerTool.ResourceOutputFileName - VC.Project.VCResourceCompilerTool.NullTerminateStrings - - vc.project.AdditionalOptionsPage --- # Resources property page diff --git a/docs/build/reference/return-value-of-cl-exe.md b/docs/build/reference/return-value-of-cl-exe.md index ceb9ff7972d..26806b0ec0c 100644 --- a/docs/build/reference/return-value-of-cl-exe.md +++ b/docs/build/reference/return-value-of-cl-exe.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Return Value of cl.exe" title: "Return Value of cl.exe" -ms.date: "09/05/2018" +description: "Learn more about: Return Value of cl.exe" +ms.date: 09/05/2018 helpviewer_keywords: ["cl.exe compiler, return value"] -ms.assetid: 7c2d7f33-ee0d-4199-8ef4-75fe2b007670 --- # Return Value of cl.exe @@ -13,7 +12,7 @@ The return value of cl.exe can be useful if you are compiling from a script, pow There are too many possible error exit codes for cl.exe to list them all. You can look up an error code in the winerror.h or ntstatus.h files included in the Windows Software Development Kit in the %ProgramFiles(x86)%\Windows Kits\\version\Include\shared\ directory. Error codes returned in decimal must be converted to hexadecimal for search. For example, an error code of -1073741620 converted to hexadecimal is 0xC00000CC. This error is found in ntstatus.h, where the corresponding message is "The specified share name cannot be found on the remote server." For a downloadable list of Windows error codes, see [`[MS-ERREF]` Windows Error Codes](/openspecs/windows_protocols/MS-ERREF). -You can also use the error lookup utility in Visual Studio to find out what a compiler error message means. In a Visual Studio command shell, enter **errlook.exe** to start the utility; or in the Visual Studio IDE, on the menu bar, choose **Tools**, **Error Lookup**. Enter the error value to find the descriptive text associated with the error. For more information see [ERRLOOK Reference](errlook-reference.md). +You can also use the error lookup utility in Visual Studio to find out what a compiler error message means. In a Visual Studio command shell, enter **errlook.exe** to start the utility; or in the Visual Studio IDE, on the menu bar, choose **Tools**, **Error Lookup**. Enter the error value to find the descriptive text associated with the error. For more information, see [ERRLOOK Reference](errlook-reference.md). ## Remarks diff --git a/docs/build/reference/rtc-run-time-error-checks.md b/docs/build/reference/rtc-run-time-error-checks.md index 265e61d945e..0bff5139a6e 100644 --- a/docs/build/reference/rtc-run-time-error-checks.md +++ b/docs/build/reference/rtc-run-time-error-checks.md @@ -42,7 +42,7 @@ int main() { } ``` -Because **`/RTCc`** rejects code that conforms to the standard, it's not supported by the C++ Standard Library. Code that uses **`/RTCc`** and the C++ Standard Library may cause compiler error [C1189](../../error-messages/compiler-errors-1/fatal-error-c1189.md). You can define `_ALLOW_RTCc_IN_STL` to silence the warning and use the **`/RTCc`** option. +Because **`/RTCc`** rejects code that conforms to the standard, it's not supported by the C++ Standard Library. Code that uses **`/RTCc`** and the C++ Standard Library may cause compiler error [C1189](../../error-messages/compiler-errors-1/fatal-error-c1189.md) or [C2338](../../error-messages/compiler-errors-1/compiler-error-c2338.md). Remove the **`/RTCc`** option to use the C++ Standard Library. **`/RTCs`**
Enables stack frame run-time error checking, as follows: diff --git a/docs/build/reference/running-nmake.md b/docs/build/reference/running-nmake.md index ad7fa7d7b79..e9633b59a9c 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/safeseh-image-has-safe-exception-handlers.md b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md index 76d3f2d7ee7..40de4d33be2 100644 --- a/docs/build/reference/safeseh-image-has-safe-exception-handlers.md +++ b/docs/build/reference/safeseh-image-has-safe-exception-handlers.md @@ -1,20 +1,25 @@ --- description: "Learn more about: /SAFESEH (Image has Safe Exception Handlers)" title: "/SAFESEH (Image has Safe Exception Handlers)" -ms.date: 03/02/2022 -f1_keywords: ["/SAFESEH"] +ms.date: 09/19/2022 +f1_keywords: ["VC.Project.VCLinkerTool.ImageHasSafeExceptionHandlers", "/SAFESEH"] helpviewer_keywords: ["/SAFESEH linker option", "-SAFESEH linker option", "SAFESEH linker option"] ms.assetid: 7722ff99-b833-4c65-a855-aaca902ffcb7 --- # `/SAFESEH` (Image has Safe Exception Handlers) -> **`/SAFESEH`**[**`:NO`**] +When **`/SAFESEH`** is specified, the linker only produces an image if it can also produce a table of the image's safe exception handlers. This table specifies to the operating system which exception handlers are valid for the image. -When **`/SAFESEH`** is specified, the linker will only produce an image if it can also produce a table of the image's safe exception handlers. This table specifies for the operating system which exception handlers are valid for the image. +## Syntax + +> **`/SAFESEH`**\ +> **`/SAFESEH:NO`** + +## Remarks **`/SAFESEH`** is only valid when linking for x86 targets. **`/SAFESEH`** isn't supported for platforms that already have the exception handlers noted. For example, on x64 and ARM, all exception handlers are noted in the PDATA. ML64.exe has support for adding annotations that emit SEH information (XDATA and PDATA) into the image, allowing you to unwind through ml64 functions. For more information, see [MASM for x64 (ml64.exe)](../../assembler/masm/masm-for-x64-ml64-exe.md). -If **`/SAFESEH`** isn't specified, the linker will produce an image with a table of safe exceptions handlers if all code segments are compatible with the safe exception handling feature. If any code segments weren't compatible with the safe exception handling feature, the resulting image won't contain a table of safe exception handlers. If [`/SUBSYSTEM`](subsystem-specify-subsystem.md) specifies WINDOWSCE or one of the `EFI_*` options, the linker won't attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. +If **`/SAFESEH`** isn't specified, the linker will produce an image with a table of safe exceptions handlers if all code segments are compatible with the safe exception handling feature. If any code segments weren't compatible with the safe exception handling feature, the resulting image won't contain a table of safe exception handlers. If [`/SUBSYSTEM`](subsystem-specify-subsystem.md) specifies `WINDOWSCE` or one of the `EFI_*` options, the linker won't attempt to produce an image with a table of safe exceptions handlers, as neither of those subsystems can make use of the information. If **`/SAFESEH:NO`** is specified, the linker won't produce an image with a table of safe exceptions handlers even if all code segments are compatible with the safe exception handling feature. @@ -87,13 +92,11 @@ const IMAGE_LOAD_CONFIG_DIRECTORY32_2 _load_config_used = { ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - -1. Select the **Linker** folder. +1. Open the **Property Pages** dialog box for the project. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Select the **Command Line** property page. +1. Select the **Configuration Properties** > **Linker** > **Advanced** property page. -1. Enter the option into the **Additional Options** box. +1. Modify the **Image Has Safe Exception Handlers** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically @@ -102,4 +105,4 @@ const IMAGE_LOAD_CONFIG_DIRECTORY32_2 _load_config_used = { ## See also [MSVC linker reference](linking.md)\ -[MSVC Linker Options](linker-options.md) +[MSVC linker options](linker-options.md) diff --git a/docs/build/reference/sarif-output.md b/docs/build/reference/sarif-output.md new file mode 100644 index 00000000000..29e608baa88 --- /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 8fd8012a8d4..d7a6f2f99c3 100644 --- a/docs/build/reference/scandependencies.md +++ b/docs/build/reference/scandependencies.md @@ -1,26 +1,15 @@ --- title: "/scanDependencies (List module and header unit dependencies per Standard)" description: "Reference guide to the /scanDependencies compiler option in Microsoft C++." -ms.date: 05/19/2022 -author: "corob-msft" -ms.author: "corob" +ms.date: 09/21/2022 +author: "tylermsft" +ms.author: "twhitney" f1_keywords: ["/scanDependencies"] helpviewer_keywords: ["/scanDependencies compiler option", "/scanDependencies"] --- # `/scanDependencies` (List module dependencies in standard form) -This compiler option generates a JSON file that lists module and header-unit dependencies according to C++ Standard proposal [`P1689R4 Format for describing dependencies of source files`](https://wg21.link/P1689r4). - -The **`/scanDependencies`** compiler option identifies which modules and header units need to be compiled before you can compile the project that uses them. For instance, it lists `import ;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. The intent is to provide this information in a common format consumable by build tools such as CMake. - -This command-line option is similar to [`/sourceDependencies:directives`](sourcedependencies-directives.md) and [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways: - -- The output uses the [`P1689R4`](https://wg21.link/P1689r4) schema, instead of the Microsoft-specific schema generated by **`/sourceDependencies:directives`**. -- Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced. -- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option only scans the project files. There are no built modules or header units to list. -- Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves. -- Textually included header files such as `#include ` or `#include "file"` aren't listed as dependencies unless translated to a header unit by using the [`/translateInclude`](translateinclude.md) option. -- **`/scanDependencies`** is meant to be used before *`.ifc`* files are built. +This compiler option generates a JSON file that lists module and header-unit dependencies according to C++ Standard proposal [`P1689R5 Format for describing dependencies of source files`](https://wg21.link/P1689r5). ## Syntax @@ -41,37 +30,48 @@ If the argument is a directory, the compiler generates source dependency files i ## Remarks -**`/scanDependencies`** is available starting in Visual Studio 2022 version 17.2 preview 1. It's not enabled by default. +The **`/scanDependencies`** compiler option identifies which dependencies, modules, and header units must be compiled before you can compile the project that uses them. For instance, it lists `import ;` or `import "library";` as a header unit dependency, and `import name;` as a module dependency. The intent is to provide this information in a common format consumable by build tools such as CMake. To report module and header unit dependencies, you must also compile by using [`/std:c++20`](std-specify-language-standard-version.md) or later. + +This command-line option is similar to [`/sourceDependencies:directives`](sourcedependencies-directives.md) and [`/sourceDependencies`](sourcedependencies.md), but differs in the following ways: + +- The output uses the [`P1689R5`](https://wg21.link/P1689r5) schema, instead of the Microsoft-specific schema generated by **`/sourceDependencies:directives`**. +- Unlike **`/sourceDependencies`**, the compiler doesn't produce compiled output. Instead, the files are scanned for module directives. No compiled code, modules, or header units are produced. +- The output JSON file doesn't list imported modules and imported header units (*`.ifc`* files) because this option only scans the project files. There are no built modules or header units to list. +- Only directly imported modules or header units are listed. It doesn't list the dependencies of the imported modules or header units themselves. +- Textually included header files such as `#include ` or `#include "file"` aren't listed as dependencies unless translated to a header unit by using the [`/translateInclude`](translateinclude.md) option. +- **`/scanDependencies`** is meant to be used before *`.ifc`* files are built. -When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend you use **`/scanDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/scanDependencies-`** to send output to `stdout` could cause interleaved results. +**`/scanDependencies`** is available starting in Visual Studio 2022 version 17.2. It's not enabled by default. + +When you specify the [`/MP` (Build with multiple processes)](mp-build-with-multiple-processes.md) compiler option, we recommend that you use **`/scanDependencies`** with a directory argument. If you provide a single filename argument, two instances of the compiler may attempt to open the output file simultaneously and cause an error. Use of **`/MP`** with **`/scanDependencies-`** to send output to `stdout` could cause interleaved results. When a non-fatal compiler error occurs, the dependency information still gets written to the output file. All file paths appear as absolute paths in the output. -For details on the format and schema used in the output JSON file, see [`P1689R4`](https://wg21.link/P1689r4#_format) section 6. +For details on the format and schema used in the output JSON file, see [`P1689R5`](https://wg21.link/P1689r5#_format) section 6. ### Examples -Given the following sample code: +Consider the following sample code: ```cpp //app.cpp: #include import other.module; -import std.core; - +import std; import "t.h"; - import ; int main() {} ``` +You can use this command line to report dependencies in *`app.cpp`*: + > `cl /std:c++latest /scanDependencies output.json app.cpp` -This command line produces a JSON file *`output.json`* with content similar to: +The compiler produces a JSON file, *`output.json`*, with content similar to: ```JSON { @@ -81,14 +81,14 @@ This command line 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", @@ -114,24 +114,28 @@ 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. The compiler doesn't generate object files when you set this option, which makes the link step fail and report an error. +You normally shouldn't set the **`/scanDependencies`** option in the Visual Studio development environment. The compiler doesn't generate object files when you set this option, which makes the link step fail and report an error. -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to add **`/scanDependencies -`** or **`/scanDependencies "pathname"`**, where `pathname` refers to a directory for output. +1. Modify the **Additional Options** property to add *`/scanDependencies-`* or *`/scanDependencies "pathname"`*, where *`"pathname"`* refers to a directory for output. 1. Choose **OK** to save your changes. +To report module and header unit dependencies, you must also set the **Configuration Properties** > **General** > **C++ Language Standard** property to **ISO C++20 Standard** or later. + ### To set this compiler option programmatically - See . ## See also +[Import the C++ standard library using modules](../../cpp/tutorial-import-stl-named-module.md)\ [MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md)\ [`/sourceDependencies:directives`](sourcedependencies-directives.md)\ [`/sourceDependencies`](sourcedependencies.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md)\ [`/translateInclude`](translateinclude.md) diff --git a/docs/build/reference/section-specify-section-attributes.md b/docs/build/reference/section-specify-section-attributes.md index e658b0c901f..c994dd47993 100644 --- a/docs/build/reference/section-specify-section-attributes.md +++ b/docs/build/reference/section-specify-section-attributes.md @@ -1,19 +1,19 @@ --- description: "Learn more about: /SECTION (Specify Section Attributes)" title: "/SECTION (Specify Section Attributes)" -ms.date: 03/02/2022 -f1_keywords: ["/section"] +ms.date: 09/09/2022 +f1_keywords: ["VC.Project.VCLinkerTool.SpecifySectionAttributes", "/section"] helpviewer_keywords: ["SECTION linker option", "-SECTION linker option", "section attributes", "/SECTION linker option"] --- # `/SECTION` (Specify Section Attributes) -> **`/SECTION:`***`name`***`,`**[[**`!`**]{**`D`**\|**`E`**\|**`K`**\|**`P`**\|**`R`**\|**`S`**\|**`W`**}][**`,ALIGN=`***`number`*] +> **`/SECTION:`***`name`***`,`**\[\[**`!`**]{**`D`**\|**`E`**\|**`K`**\|**`P`**\|**`R`**\|**`S`**\|**`W`**}]\[**`,ALIGN=`***`number`*] ## Remarks The **`/SECTION`** option changes the attributes of a section, overriding the attributes set when the *`.obj`* file for the section was compiled. -A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly. Other data sections are created for you by the linker and library manager (*`lib.exe`*) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). +A *section* in a portable executable (PE) file is a named contiguous block of memory that contains either code or data. Some sections contain code or data that your program declared and uses directly. Other data sections are created for you by the linker and library manager (LIB) and contain information vital to the operating system. For more information, see [PE Format](/windows/win32/Debug/pe-format). Specify a colon (**`:`**) and a section name *`name`*. The *`name`* is case sensitive. @@ -69,11 +69,11 @@ The **`ALIGN=`***`number`* argument lets you specify an alignment value for a pa ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). -1. Choose the **Configuration Properties** > **Linker** > **Command Line** property page. +1. Choose the **Configuration Properties** > **Linker** > **General** property page. -1. Enter the option in the **Additional Options** box. Choose **OK** or **Apply** to apply the change. +1. Modify the **Specify Section Attributes** property. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically diff --git a/docs/build/reference/sourcedependencies-directives.md b/docs/build/reference/sourcedependencies-directives.md index 7f1e9efe388..25cfd5f1925 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 c0ae01daa1a..e789466f8b3 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 1e9b7002ed1..2240b03d4b5 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/spd-specify-sample-profile-database.md b/docs/build/reference/spd-specify-sample-profile-database.md new file mode 100644 index 00000000000..f6afb2d2407 --- /dev/null +++ b/docs/build/reference/spd-specify-sample-profile-database.md @@ -0,0 +1,46 @@ +--- +title: "/SPD (Specify Sample Profile Database)" +description: "Learn more about: /SPD (Specify Sample Profile Database)" +ms.date: 05/05/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["/SPD linker option", "-SPD linker option", "sample profile-guided optimization, /SPD"] +--- +# /SPD (Specify Sample Profile Database) + +Specifies the name and location of the Sample Profile Database (SPD) file used by the Sample Profile-Guided Optimization (SPGO) workflow. + +## Syntax + +> **/SPD:**_filename_ + +## Argument + +`filename`\ +Specifies the name of the `.spd` file. When expanded, the fully qualified path must not exceed `MAX_PATH` (260 characters). + +## Remarks + +When you build with [`/SPGO`](spgo-enable-sample-profile-guided-optimization.md), the linker creates an empty SPD file alongside the output binary. By default, the SPD file uses the same base name as the output file and is created in the directory where you invoked the link. Use `/SPD` to specify a different name or path. + +When linking with [`/SPDIN`](spdin-use-sample-profile-database.md), use `/SPDIN` to specify the input SPD file and `/SPD` to specify the output SPD file. + +For more information about the SPGO workflow, see [Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.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. Add `/SPD:filename` to the **Additional Options** box. Choose **OK** to save your changes. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/SPDEMBED (Embed Sample Profile Database)](spdembed-embed-sample-profile-database.md)\ +[/SPDIN (Use Sample Profile Database)](spdin-use-sample-profile-database.md)\ +[/SPGO (Enable Sample Profile-Guided Optimization)](spgo-enable-sample-profile-guided-optimization.md)\ +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.md) \ No newline at end of file diff --git a/docs/build/reference/spdembed-embed-sample-profile-database.md b/docs/build/reference/spdembed-embed-sample-profile-database.md new file mode 100644 index 00000000000..db91e8359f1 --- /dev/null +++ b/docs/build/reference/spdembed-embed-sample-profile-database.md @@ -0,0 +1,41 @@ +--- +title: "/SPDEMBED (Embed Sample Profile Database)" +description: "Learn more about: /SPDEMBED (Embed Sample Profile Database)" +ms.date: 05/05/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["/SPDEMBED linker option", "-SPDEMBED linker option", "sample profile-guided optimization, /SPDEMBED"] +--- +# /SPDEMBED (Embed Sample Profile Database) + +Embeds the Sample Profile Database (SPD) data into the Program Database (PDB) file during a Sample Profile-Guided Optimization (SPGO) build. + +## Syntax + +> **/SPDEMBED** + +## Remarks + +When you build with [`/SPDIN`](spdin-use-sample-profile-database.md), the linker uses the profile data in the SPD file to make optimization decisions. Use `/SPDEMBED` together with `/SPGO` to embed the SPD data into the PDB file produced by the build. Embedding the SPD in the PDB keeps the profile data together with the debug symbols, which simplifies distribution and archiving of build artifacts. + +To extract an SPD file that you embedded in a PDB, use [`SPDConvert /extract`](../spdconvert.md). + +For more information about the SPGO workflow, see [Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.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. Add `/SPDEMBED` to the **Additional Options** box. Choose **OK** to save your changes. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/SPD (Specify Sample Profile Database)](spd-specify-sample-profile-database.md)\ +[/SPDIN (Use Sample Profile Database)](spdin-use-sample-profile-database.md)\ +[/SPGO (Enable Sample Profile-Guided Optimization)](spgo-enable-sample-profile-guided-optimization.md)\ +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.md) \ No newline at end of file diff --git a/docs/build/reference/spdin-use-sample-profile-database.md b/docs/build/reference/spdin-use-sample-profile-database.md new file mode 100644 index 00000000000..b8ba7989923 --- /dev/null +++ b/docs/build/reference/spdin-use-sample-profile-database.md @@ -0,0 +1,52 @@ +--- +title: "/SPDIN (Use Sample Profile Database)" +description: "Learn more about linker option: /SPDIN (Use Sample Profile Database)" +ms.date: 05/05/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["/SPDIN linker option", "-SPDIN linker option", "sample profile-guided optimization, /SPDIN"] +--- +# /SPDIN (Use Sample Profile Database) + +Specifies a Sample Profile Database (SPD) file that contains profiling data for use in a Sample Profile-Guided Optimization (SPGO) build. +Also used to override the default or file specified with `/SPD` for reading the sample profile database. + +## Syntax + +> **/SPDIN:**_filename_ + +## Argument + +`filename`\ +Specifies the path to the `.spd` file that contains the profiling data to use for optimization. When expanded, the fully qualified path must not exceed `MAX_PATH` (260 characters).\ +If the file doesn't exist, the linker creates an empty file that will be used to collect data. + +## Remarks + +After collecting a performance trace by using `xperf`, converting it by using [`SPTAggregate`](../sptaggregate.md), and importing the data into an SPD file by using [`SPDConvert`](../spdconvert.md), use `/SPDIN` and [`/SPGO`](spgo-enable-sample-profile-guided-optimization.md) to produce an optimized binary. + +The GUID and age of the binary recorded in the SPD file must match the SPT file. If they don't match, you may see a "SPD version incompatible" error. To diagnose this error, use [`SPTDump /progid`](../sptdump.md) to inspect the binary identifiers in the SPT file, and [`SPDDump /header`](../spddump.md) to inspect the SPD file. The linker uses a valid SPD file to the extent possible. Minor updates to the code that don't alter the program's control flow are tolerated. Unchanged functions also use the data for optimization. If you provide a valid, but otherwise unrelated SPD, the process works, but likely no data is usable for optimization. + +Use [`/SPDEMBED`](spdembed-embed-sample-profile-database.md) together with `/SPGO` to embed the SPD data into the PDB file produced by the build. + +Use [`/SPD`](spd-specify-sample-profile-database.md) to specify a nondefault name or location for the SPD file. `/SPDIN` overrides this option, if specified. + +For more information about the SPGO workflow, see [Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.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. Add `/SPDIN:filename` to the **Additional Options** box. Choose **OK** to save your changes. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/SPD (Specify Sample Profile Database)](spd-specify-sample-profile-database.md)\ +[/SPDEMBED (Embed Sample Profile Database)](spdembed-embed-sample-profile-database.md)\ +[/SPGO (Enable Sample Profile-Guided Optimization)](spgo-enable-sample-profile-guided-optimization.md)\ +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.md) \ No newline at end of file diff --git a/docs/build/reference/special-nmake-macros.md b/docs/build/reference/special-nmake-macros.md index 26f1428da78..93dcf23449e 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/specifying-the-pathname.md b/docs/build/reference/specifying-the-pathname.md index 98293ee2a43..55be6dfec95 100644 --- a/docs/build/reference/specifying-the-pathname.md +++ b/docs/build/reference/specifying-the-pathname.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Specifying the Pathname" title: "Specifying the Pathname" -ms.date: "11/04/2016" +description: "Learn more about: Specifying the Pathname" +ms.date: 11/04/2016 helpviewer_keywords: ["names [C++], compiler output files", "cl.exe compiler, output files", "output files, specifying pathnames"] -ms.assetid: 7a6595ce-3383-44ae-957a-466bfa29c343 --- # Specifying the Pathname @@ -24,7 +23,7 @@ Alternatively, the *pathname* argument can be a device name (AUX, CON, PRN, or N The following command line sends a mapfile to the printer: -``` +```cmd CL /FmPRN HELLO.CPP ``` diff --git a/docs/build/reference/spgo-enable-sample-profile-guided-optimization.md b/docs/build/reference/spgo-enable-sample-profile-guided-optimization.md new file mode 100644 index 00000000000..e2eeaa48ed2 --- /dev/null +++ b/docs/build/reference/spgo-enable-sample-profile-guided-optimization.md @@ -0,0 +1,51 @@ +--- +title: "/SPGO (Enable Sample Profile-Guided Optimization)" +description: "Learn more about: /SPGO (Enable Sample Profile-Guided Optimization)" +ms.date: 05/05/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["/SPGO linker option", "-SPGO linker option", "sample profile-guided optimization, /SPGO"] +--- +# /SPGO (Enable Sample Profile-Guided Optimization) + +Enables Sample Profile-Guided Optimization (SPGO) and creates an empty Sample Profile Database (SPD) file alongside the output binary. + +## Syntax + +> **/SPGO** + +## Remarks + +The `/SPGO` linker option starts the SPGO workflow. It directs the linker to create an empty `.spd` file that acts as a placeholder for profiling data. After building with `/SPGO`, you collect a performance trace by using `xperf`, convert it to an SPT file by using [`SPTAggregate`](../sptaggregate.md), and then import the data into the SPD file by using [`SPDConvert`](../spdconvert.md). Once the SPD file contains profile data, rebuild by using the SPD file to produce an optimized binary. The compiler and linker look for an SPD input file, either default or specified by [`/SPD`](spd-specify-sample-profile-database.md). The [/SPDIN (Use Sample Profile Database)](spdin-use-sample-profile-database.md) option is available as a convenience when the input file is over-written and that isn't desirable. + +When you build by using `/SPGO` but the SPD file contains no profile data yet, you see a message such as: + +``` +Result: SPD .spd does not contain sample profile, compiling without profile guided optimizations +``` + +This message is expected on the first build and indicates that the SPD file is ready to receive profiling data. + +By default, the build process creates the SPD file with the same base name as the output file in the directory from which the link was invoked. Use [`/SPD`](spd-specify-sample-profile-database.md) to specify a different name or location. + +Use [`/SPDEMBED`](spdembed-embed-sample-profile-database.md) to embed the SPD data into the PDB file after profile data is collected. Ensure that the linker is producing a PDB file by specifying the `/DEBUG` option. + +For more information about the SPGO workflow, see [Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.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. Add `/SPGO` to the **Additional Options** box. Choose **OK** to save your changes. + +### To set this linker option programmatically + +- See . + +## See also + +[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/SPD (Specify Sample Profile Database)](spd-specify-sample-profile-database.md)\ +[/SPDEMBED (Embed Sample Profile Database)](spdembed-embed-sample-profile-database.md)\ +[/SPDIN (Use Sample Profile Database)](spdin-use-sample-profile-database.md)\ +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](../sample-profile-guided-optimization.md) \ No newline at end of file diff --git a/docs/build/reference/std-specify-language-standard-version.md b/docs/build/reference/std-specify-language-standard-version.md index 9aac61f438e..c9eeb3f5443 100644 --- a/docs/build/reference/std-specify-language-standard-version.md +++ b/docs/build/reference/std-specify-language-standard-version.md @@ -1,8 +1,8 @@ --- title: "/std (Specify Language Standard Version)" description: "The MSVC compiler option /std specifies the C or C++ language standard supported by the compiler." -ms.date: 10/22/2021 -f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c11", "/std:c17", "VC.Project.VCCLCompilerTool.CppLanguageStandard"] +ms.date: 1/29/2025 +f1_keywords: ["/std", "-std", "/std:c++14", "/std:c++17", "/std:c++20", "/std:c++23preview", "/std:c++latest", "/std:c11", "/std:c17", "/std:clatest", "VC.Project.VCCLCompilerTool.CppLanguageStandard"] --- # `/std` (Specify Language Standard Version) @@ -13,24 +13,32 @@ Enable supported C and C++ language features from the specified version of the C > **`/std:c++14`**\ > **`/std:c++17`**\ > **`/std:c++20`**\ +> **`/std:c++23preview`**\ > **`/std:c++latest`**\ > **`/std:c11`**\ -> **`/std:c17`** +> **`/std:c17`**\ +> **`/std:clatest`** ## Remarks The **`/std`** options are available in Visual Studio 2017 and later. They're used to control the version-specific ISO C or C++ programming language standard features enabled during compilation of your code. The options allow you to disable support for certain new language and library features: ones that may break your existing code that conforms to a particular version of the language standard. -### C++ standards support +The Microsoft C++ compiler in Visual Studio 2017 and later versions doesn't support C++ standards modes earlier than C++14 (**`/std:c++14`**). Such support isn't planned. As an imperfect workaround, it's possible to use older Visual C++ compiler toolsets that didn't implement features from later standards. For more information on how to install and use older compiler toolsets in Visual Studio, see [Use native multi-targeting in Visual Studio to build old projects](../../porting/use-native-multi-targeting.md). -The **`/std`** option in effect during a C++ compilation can be detected by use of the [`_MSVC_LANG`](../../preprocessor/predefined-macros.md) preprocessor macro. For more information, see [Preprocessor Macros](../../preprocessor/predefined-macros.md). +## C++ standards support -**`/std:c++14`**\ -The **`/std:c++14`** option enables C++14 standard-specific features implemented by the MSVC compiler. This option is the default for code compiled as C++. It's available starting in Visual Studio 2015 Update 3. +Detect whether the **`/std`** option is in effect during a C++ compilation with the [`_MSVC_LANG`](../../preprocessor/predefined-macros.md) preprocessor macro. For more information, see [Preprocessor Macros](../../preprocessor/predefined-macros.md). + +> [!IMPORTANT] +> Because some existing code depends on the value of the macro `__cplusplus` being `199711L`, the MSVC compiler doesn't change the value of this macro unless you explicitly opt in by setting [`/Zc:__cplusplus`](zc-cplusplus.md). Specify `/Zc:__cplusplus` and the **`/std`** option to set `__cplusplus` to the appropriate value. + +### `/std:c++14` + +Enables C++14 standard-specific features implemented by the MSVC compiler. This option is the default for code compiled as C++. It's available starting in Visual Studio 2015 Update 3. This option disables compiler and standard library support for features that are changed or new in more recent versions of the language standard. However, it doesn't disable some C++17 features already implemented in previous releases of the MSVC compiler. For more information, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). The tables indicate which C++17 features are enabled when you specify **`/std:c++14`**. -The following features remain enabled when the **`/std:c++14`** option is specified to avoid breaking changes for users who have already taken dependencies on the features available in or before Visual Studio 2015 Update 2: +The following features remain enabled when the **`/std:c++14`** option is specified to avoid breaking changes for users who took dependencies on features available in or before Visual Studio 2015 Update 2: - [Rules for `auto` with braced-init-lists](https://wg21.link/n3922) - [`typename` in template template-parameters](https://wg21.link/n4051) @@ -38,39 +46,52 @@ The following features remain enabled when the **`/std:c++14`** option is specif - [Attributes for namespaces and enumerators](https://wg21.link/n4266) - [u8 character literals](https://wg21.link/n4267) -**`/std:c++17`**\ -The **`/std:c++17`** option enables C++17 standard-specific features and behavior. It enables the full set of C++17 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are new or changed after C++17. It specifically disables post-C++17 changes in the C++ Standard and versions of the Working Draft. It does not disable retroactive defect updates of the C++ Standard. This option is available starting in Visual Studio 2017 version 15.3. +### `/std:c++17` + +Enables C++17 standard-specific features and behavior. It enables the full set of C++17 features implemented by the MSVC compiler. This option disables compiler and standard library support for features that are new or changed after C++17. It specifically disables post-C++17 changes in the C++ Standard and versions of the Working Draft. It doesn't disable retroactive defect updates of the C++ Standard. This option is available starting in Visual Studio 2017 version 15.3. Depending on the MSVC compiler version or update level, C++17 features may not be fully implemented or fully conforming when you specify the **`/std:c++17`** option. For an overview of C++ language conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). -**`/std:c++20`**\ -The **`/std:c++20`** option enables C++20 standard-specific features and behavior. Available starting in Visual Studio 2019 version 16.11, it enables the full set of C++20 features implemented by the MSVC compiler, with the exception of `std::format`, the C++20 `` formatting extensions, and the range factories and range adaptors from ``. These features are still only available under **`/std:c++latest`**. +### `/std:c++20` + +Enables C++20 standard-specific features and behavior. + +Enables the standard conformance mode provided by [**`/permissive-`**](./permissive-standards-conformance.md) unless explicitly overridden with **`/permissive`**. -The **`/std:c++20`** option disables compiler and standard library support for features that are new or changed after C++20. It specifically disables post-C++20 changes in the C++ Standard and versions of the Working Draft. It doesn't disable retroactive defect updates of the C++ Standard. +### `/std:c++23preview` -**`/std:c++latest`**\ -The **`/std:c++latest`** option enables all currently implemented compiler and standard library features proposed for the next draft standard, as well as some in-progress and experimental features. This option is available starting in Visual Studio 2015 Update 3. +Enables preview C++23 standard-specific features and behavior. Available starting in Visual Studio 2022 version 17.13 Preview 4. Preview features may change and may not be ABI compatible across releases. -Depending on the MSVC compiler version or update level, C++17, C++20, or proposed C++23 features may not be fully implemented or fully conforming when you specify the **`/std:c++latest`** option. We recommend you use the latest version of Visual Studio for maximum standards conformance. For an overview of C++ language and library conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). +This switch will be removed when the `/std:c++23` switch is implemented--at which point C++23 features will be fully implemented and ABI stable. If in project properties **C/C++** > **Language** you specify **Preview - ISO C++ 23 Standard (/std:c++preview)**, it will automatically change to mean `/std:c++23` once the new switch is implemented. -In versions of Visual Studio 2019 before version 16.11, **`/std:c++latest`** is required to enable all the compiler and standard library features of C++20. +This switch differs from `/std:c++latest` in that it only enables features that are part of the C++23 standard. It doesn't enable experimental or in-progress features. + +### `/std:c++latest` + +Enables all currently implemented compiler and standard library features proposed in the next ISO C++ working draft, as well as some in-progress and experimental features. This option is available starting with Visual Studio 2015 Update 3. + +Depending on the MSVC compiler version or update level, features from published C++ standards or proposed features in the current C++ working draft, may not be fully implemented or fully conforming when you specify the **`/std:c++latest`** option. We recommend you use the latest version of Visual Studio for maximum standards conformance. For an overview of C++ language and library conformance in Visual C++ by release version, see [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). + +Since Visual Studio 2019 version 16.8, the **`/std:c++latest`** option has enabled the standard conformance mode provided by [**`/permissive-`**](./permissive-standards-conformance.md) unless explicitly overridden with **`/permissive`**. For a list of supported language and library features, see [What's New for C++ in Visual Studio](../../overview/what-s-new-for-visual-cpp-in-visual-studio.md). The **`/std:c++latest`** option doesn't enable features guarded by the **`/experimental`** switch, but may be required to enable them. > [!NOTE] -> The compiler and library features enabled by **`/std:c++latest`** may appear in a future C++ standard. Features that have not been approved are subject to breaking changes or removal without notice and are provided on an as-is basis. +> The compiler and library features enabled by **`/std:c++latest`** may appear in a future C++ standard. Features that haven't been approved are subject to breaking changes or removal without notice and are provided on an as-is basis. -### C standards support +## C standards support You can invoke the Microsoft C compiler by using the [`/TC` or `/Tc`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. It's used by default for code that has a *`.c`* file extension, unless overridden by a **`/TP`** or **`/Tp`** option. The default C compiler (that is, the compiler when **`/std:c11`** or **`/std:c17`** isn't specified) implements ANSI C89, but includes several Microsoft extensions, some of which are part of ISO C99. Some Microsoft extensions to C89 can be disabled by using the [`/Za`](za-ze-disable-language-extensions.md) compiler option, but others remain in effect. It isn't possible to specify strict C89 conformance. The compiler doesn't implement several required features of C99, so it isn't possible to specify C99 conformance, either. -**`/std:c11`**\ -The **`/std:c11`** option enables ISO C11 conformance. It's available starting in Visual Studio 2019 version 16.8. +### `/std:c11` + +Enables ISO C11 conformance. It's available starting in Visual Studio 2019 version 16.8. -**`/std:c17`**\ -The **`/std:c17`** option enables ISO C17 conformance. It's available starting in Visual Studio 2019 version 16.8. +### `/std:c17` + +Enables ISO C17 conformance. It's available starting in Visual Studio 2019 version 16.8. Because the new preprocessor is needed to support these standards, the **`/std:c11`** and **`/std:c17`** compiler options set the [`/Zc:preprocessor`](zc-preprocessor.md) option automatically. If you want to use the traditional (legacy) preprocessor for C11 or C17, you must set the **`/Zc:preprocessor-`** compiler option explicitly. Setting the **`/Zc:preprocessor-`** option may lead to unexpected behavior, and isn't recommended. @@ -80,15 +101,10 @@ Because the new preprocessor is needed to support these standards, the **`/std:c When you specify **`/std:c11`** or **`/std:c17`**, MSVC supports all the features of C11 and C17 required by the standards. The **`/std:c11`** and **`/std:c17`** compiler options enable support for these functionalities: - [`_Pragma`](../../preprocessor/pragma-directives-and-the-pragma-keyword.md#the-pragma-preprocessing-operator) - - [`restrict`](../../c-language/type-qualifiers.md#restrict) - - [`_Noreturn`](../../c-language/noreturn.md) and \ - - [`_Alignas`, `_Alignof`](../../c-language/alignment-c.md) and \ - - [`_Generic`](../../c-language/generic-selection.md) and \ - - [`_Static_assert`](../../c-language/static-assert-c.md) The IDE uses C settings for IntelliSense and code highlighting when your source files have a *`.c`* file extension, or when you specify the [`/TC` or `/Tc`](tc-tp-tc-tp-specify-source-file-type.md) compiler option. Currently, IntelliSense in C highlights keywords `_Alignas`, `_Alignof`, `_Noreturn`, and `_Static_assert`, but not the equivalent macros defined in the standard headers: `alignas`, `alignof`, `noreturn`, and `static_assert`. @@ -101,21 +117,24 @@ The compiler doesn't support most optional features of ISO C11. Several of these - `aligned_alloc` support is missing, because of the Windows heap implementation. The alternative is to use [`_aligned_malloc`](../../c-runtime-library/reference/aligned-malloc.md). -- [DR 400](https://wg14.link/n2148#dr_400) support is currently unimplemented for `realloc`, because this change would break the ABI. +- [Defect report 400](https://www.open-std.org/jtc1/sc22/wg14/www/docs/n2148.htm#dr_400) support is currently unimplemented for `realloc` because this change would break the ABI. - Variable length array (VLA) support isn't planned. VLAs provide attack vectors comparable to [`gets`](../../c-runtime-library/gets-getws.md), which is deprecated and planned for removal. +### `/std:clatest` + +The **`/std:clatest`** option behaves like the `/std:c++latest` switch for the C++ compiler. The switch enables all currently implemented compiler and standard library features proposed in the next draft C standard, as well as some in-progress and experimental features. + For more information, see the C Standard library features section of [Microsoft C/C++ language conformance](../../overview/visual-cpp-language-conformance.md). ### To set this compiler option in the Visual Studio development environment 1. Open the project's **Property Pages** dialog box. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). - 1. Select the **Configuration Properties** > **C/C++** > **Language** property page. - 1. In **C++ Language Standard** (or for C, **C Language Standard**), choose the language standard to support from the dropdown control, then choose **OK** or **Apply** to save your changes. ## See also -[MSVC compiler options](compiler-options.md)
+[`/Zc:__cplusplus[-]`](zc-cplusplus.md)\ +[MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/subsystem-specify-subsystem.md b/docs/build/reference/subsystem-specify-subsystem.md index 661d84a9f2e..5669fa0e8bf 100644 --- a/docs/build/reference/subsystem-specify-subsystem.md +++ b/docs/build/reference/subsystem-specify-subsystem.md @@ -1,8 +1,8 @@ --- description: "Learn more about: /SUBSYSTEM (Specify Subsystem)" title: "/SUBSYSTEM (Specify Subsystem)" -ms.date: 02/07/2022 -f1_keywords: ["/subsystem", "VC.Project.VCLinkerTool.SubSystem", "VC.Project.VCLinkerTool.SubSystemVersion"] +ms.date: 09/09/2022 +f1_keywords: ["/subsystem", "VC.Project.VCLinkerTool.SubSystem", "VC.Project.VCLinkerTool.SubSystemVersion", "VC.Project.VCLinkerTool.MinimumRequiredVersion"] helpviewer_keywords: ["/SUBSYSTEM linker option", "SUBSYSTEM linker option", "-SUBSYSTEM linker option", "subsystem specifications"] ms.assetid: d7b133cf-cf22-4da8-ab46-6552702c0b9b --- @@ -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 a9fde3067bb..3daba013801 100644 --- a/docs/build/reference/tlbout-name-dot-tlb-file.md +++ b/docs/build/reference/tlbout-name-dot-tlb-file.md @@ -1,32 +1,31 @@ --- description: "Learn more about: /TLBOUT (Name .TLB File)" title: "/TLBOUT (Name .TLB File)" -ms.date: "11/04/2016" +ms.date: 03/24/2025 f1_keywords: ["VC.Project.VCLinkerTool.TypeLibraryFile", "/tlbout"] helpviewer_keywords: ["tlb files, renaming", "TLBOUT linker option", "/TLBOUT linker option", ".tlb files, renaming", "-TLBOUT linker option"] -ms.assetid: 0df6d078-2e48-46c9-a1a5-02674d85dce8 --- -# /TLBOUT (Name .TLB File) +# `/TLBOUT` (Name .TLB File) -``` +```cmd /TLBOUT:[path\]filename ``` ## Arguments -*path*
+*`path`*\ An absolute or relative path specification for where the .tlb file should be created. -*filename*
-Specifies the name of the .tlb file created by the MIDL compiler. No file extension is assumed; specify *filename*.tlb if you want a .tlb extension. +*`filename`* +Specifies the name of the .tlb file created by the MIDL compiler. No file extension is assumed; specify *filename*.tlb if you want a .tlb extension. When expanded, the fully qualified filename must not exceed `MAX_PATH` (260 characters). ## Remarks -The /TLBOUT option specifies the name and extension of the .tlb file. +The `/TLBOUT` option specifies the name and extension of the .tlb file. The MIDL compiler is called by the MSVC linker when linking projects that have the [module](../../windows/attributes/module-cpp.md) attribute. -If /TLBOUT is not specified, the .tlb file will get its name from [/IDLOUT](idlout-name-midl-output-files.md) *filename*. If /IDLOUT is not specified, the .tlb file will be called vc70.tlb. +If `/TLBOUT` is not specified, the .tlb file will get its name from [/IDLOUT](idlout-name-midl-output-files.md) *filename*. If /IDLOUT is not specified, the .tlb file will be called vc70.tlb. ### To set this linker option in the Visual Studio development environment @@ -42,8 +41,8 @@ If /TLBOUT is not specified, the .tlb file will get its name from [/IDLOUT](idlo ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md)
-[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)
-[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)
+[MSVC linker reference](linking.md)\ +[MSVC Linker Options](linker-options.md)\ +[/IGNOREIDL (Don't Process Attributes into MIDL)](ignoreidl-don-t-process-attributes-into-midl.md)\ +[/MIDL (Specify MIDL Command Line Options)](midl-specify-midl-command-line-options.md)\ [Building an Attributed Program](../../windows/attributes/cpp-attributes-com-net.md) diff --git a/docs/build/reference/translateinclude.md b/docs/build/reference/translateinclude.md index fa5cadac9e8..814d97b06fc 100644 --- a/docs/build/reference/translateinclude.md +++ b/docs/build/reference/translateinclude.md @@ -13,7 +13,7 @@ This switch instructs the compiler to treat `#include` as `import` for header fi When used with [`/scanDependencies`](scandependencies.md) or [`/sourceDependencies-directives`](sourcedependencies-directives.md), the compiler lists as imported header units in the generated dependency file those headers that are both included in the source and have a corresponding entry in a `header-units.json` file. This dependency info is used by the build system to generate compiled header unit `.ifc` files. Once the header units are built, they're treated by the compiler as an `import` instead of an `#include`. -The `header-units.json` file is only consulted when `/translateInclude` is specified. For more information about the format and purpose of the `header-units.json` file, see [`header-units.json`](header-unit-json-reference.md). +The `header-units.json` file is only consulted when `/translateInclude` is specified. For more information about the format and purpose of the `header-units.json` file, see [`header-units.json`](header-unit-json-reference.md). If an `#include` file isn't listed in the `header-units.json` file, it's treated as a normal `#include`. diff --git a/docs/build/reference/u-u-undefine-symbols.md b/docs/build/reference/u-u-undefine-symbols.md index 816c7045274..cdc3cdd3ba2 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 9efe9965292..9a9fde9e724 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 e0a21eadbc5..f4b418744bd 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 524918f3808..4b5daa513b8 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-file-structure.md b/docs/build/reference/vcxproj-file-structure.md index 0f0cd77c754..2071e7e393d 100644 --- a/docs/build/reference/vcxproj-file-structure.md +++ b/docs/build/reference/vcxproj-file-structure.md @@ -1,23 +1,23 @@ --- title: ".vcxproj and .props file structure" description: "How the C++ native MSBuild project system .vcxproj and .props files store project information." -ms.date: 09/30/2020 +ms.date: 11/14/2022 helpviewer_keywords: [".vcxproj file structure"] ms.assetid: 14d0c552-29db-480e-80c1-7ea89d6d8e9c --- # `.vcxproj` and `.props` file structure -[MSBuild](../msbuild-visual-cpp.md) is the default project system in Visual Studio; when you choose **File** > **New Project** in Visual C++ you're creating an MSBuild project whose settings are stored in an XML project file that has the extension *`.vcxproj`*. The project file may also import *`.props`* files and *`.targets`* files where settings can be stored. +[MSBuild](../msbuild-visual-cpp.md) is the default project system in Visual Studio; when you choose **File** > **New Project**, in most cases you're creating an MSBuild project whose settings are stored in an XML project file that has the extension *`.vcxproj`*. The project file may also import *`.props`* files and *`.targets`* files where settings can be stored. -We recommend you only create and modify *`.vcxproj`* projects in the IDE, and avoid manual editing as much as possible. In most cases, you never need to manually edit the project file. Whenever possible you should use the Visual Studio property pages to modify project settings. For more information, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +If you intend to maintain your project properties in the IDE, we recommend you only create and modify your *`.vcxproj`* projects in the IDE, and avoid manual edits to the files. In most cases, you never need to manually edit the project file. Manual edits may break the project connections required to modify project settings in the Visual Studio property pages, and can cause build errors that are difficult to debug and repair. For more information about using the property pages, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). -If you need customizations that aren't possible in the IDE, we recommend you add custom props or targets. Handy places to insert customizations are the *`Directory.Build.props`* and *`Directory.Build.targets`* files, which are automatically imported in all MSBuild-based projects. +At scale, managing many individual projects in the IDE becomes tedious and error-prone. It's hard to maintain consistency or enforce standardization across tens or hundreds of projects. In these cases, it's worthwhile to edit your project files to use customized *`.props`* or *`.targets`* files for common properties across many projects. You may also use these files when you require customizations that aren't possible in the IDE. Handy places to insert customizations are the *`Directory.Build.props`* and *`Directory.Build.targets`* files, which are automatically imported in all MSBuild-based projects. -In some cases, you may still need to modify a *`.vcxproj`* project file or property sheet manually. We don't recommend you edit it manually unless you have a good understanding of MSBuild, and follow the guidelines in this article. In order for the IDE to load and update *`.vcxproj`* files automatically, these files have several restrictions that don't apply to other MSBuild project files. They weren't designed for manual editing. Mistakes can cause the IDE to crash or behave in unexpected ways. +In some cases, customized *`.props`* or *`.targets`* files alone may not be sufficient for your project management needs. You may still need to modify *`.vcxproj`* project files or property sheets manually. Manual editing requires a good understanding of MSBuild, and must follow the guidelines in this article. In order for the IDE to load and update *`.vcxproj`* files automatically, these files have several restrictions that don't apply to other MSBuild project files. Mistakes can cause the IDE to crash or behave in unexpected ways. For manual editing scenarios, this article contains basic information about the structure of *`.vcxproj`* and related files. -**Important:** +## Important considerations If you choose to manually edit a *`.vcxproj`* file, be aware of these facts: @@ -42,7 +42,7 @@ If you choose to manually edit a *`.vcxproj`* file, be aware of these facts: ``` - "Not supported" means that macros aren't guaranteed to work for all operations in the IDE. Macros that don't change their value in different configurations should work, but might not be preserved if an item is moved to a different filter or project. Macros that change their value for different configurations will cause problems. That's because the IDE doesn't expect project item paths to be different for different project configurations. + "Not supported" means that macros aren't guaranteed to work for all operations in the IDE. Macros that don't change their value in different configurations should work, but might not be preserved if an item is moved to a different filter or project. Macros that change their value for different configurations will cause problems. The IDE doesn't expect project item paths to be different for different project configurations. - To add, remove, or modify project properties correctly when you edit them in the **Project Properties** dialog, the file must contain separate groups for each project configuration. The conditions must be in this form: @@ -125,18 +125,11 @@ The following snippet shows a project configuration. In this example, 'Debug|x64 The IDE expects to find a project configuration for any combination of `Configuration` and `Platform` values used in all `ProjectConfiguration` items. Often, it means that a project might have meaningless project configurations to fulfill this requirement. For instance, if a project has these configurations: - Debug|Win32 - -- Retail|Win32 - -- Special 32-bit Optimization|Win32 - -then it must also have these configurations, even though "Special 32-bit Optimization" is meaningless for x64: - -- Debug|x64 - - Retail|x64 +- Debug|x64 +- Retail|Win32 -- Special 32-bit Optimization|x64 +Then if you add a new configuration to the project, say "Special 32-bit Optimization|Win32", then you must also add the configuration "Special 32-bit Optimization|x64", even though "Special 32-bit Optimization" is meaningless for x64. You can disable the build and deploy commands for any configuration in the **Solution Configuration Manager**. @@ -195,7 +188,7 @@ The `PropertySheets` group contains the imports for user property sheets. These ``` -`UserMacros` contains properties you create as variables that are used to customize your build process. For example, you can define a user macro to define your custom output path as $(CustomOutputPath) and use it to define other variables. This property group houses such properties. In Visual Studio, this group isn't populated in the project file because Visual C++ doesn't support user macros for configurations. User macros are supported in property sheets. +`UserMacros` contains properties you create as variables that are used to customize your build process. For example, you can define a user macro to define your custom output path as $(CustomOutputPath) and use it to define other variables. This property group houses such properties. In Visual Studio, this group isn't populated in the project file because Microsoft C++ doesn't support user macros for configurations. User macros are supported in property sheets. ### Per-configuration PropertyGroup elements @@ -272,7 +265,7 @@ Defines (directly or through imports) C++ targets such as build, clean, and so o This group contains imports for the Build Customization target files. -## Impact of incorrect ordering +## Consequences of incorrect ordering The Visual Studio IDE depends on the project file having the ordering described previously. For example, when you define a property value in the property pages, the IDE will generally place the property definition in the property group with the empty label. This ordering ensures that default values brought in the system property sheets are overridden by user-defined values. Similarly, the target files are imported at the end since they consume the properties defined before, and since they generally don't define properties themselves. Likewise, user property sheets are imported after the system property sheets (included by *`Microsoft.Cpp.props`*). This order ensures that the user can override any defaults brought in by the system property sheets. diff --git a/docs/build/reference/vcxproj-filters-files.md b/docs/build/reference/vcxproj-filters-files.md index 53893c7a644..f03ac67005c 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/visual-cpp-project-types.md b/docs/build/reference/visual-cpp-project-types.md index 41e998d56e9..baebf7c6045 100644 --- a/docs/build/reference/visual-cpp-project-types.md +++ b/docs/build/reference/visual-cpp-project-types.md @@ -1,6 +1,6 @@ --- description: "Learn more about: C++ project templates" -title: "Visual C++ Project Types" +title: "Microsoft C++ Project Types" ms.date: "08/13/2019" helpviewer_keywords: ["programs [C++], projects", "project templates [Visual Studio], C++", "TODO comments [C++]", "projects [C++], types", "templates [C++], projects", "applications [C++], projects", "C++ projects, types"] ms.assetid: 7337987e-1e7b-4120-9a4b-94f0401f15e7 diff --git a/docs/build/reference/vlen.md b/docs/build/reference/vlen.md new file mode 100644 index 00000000000..fbc7abdf60e --- /dev/null +++ b/docs/build/reference/vlen.md @@ -0,0 +1,55 @@ +--- +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 autovectorization and other optimizations. + +**`/vlen=512`**\ +Specify a vector length of 512 bits for autovectorization and other optimizations. + +**`/vlen`**\ +Specify the default vector length for the selected **`/arch`** setting. + +## Remarks + +This compiler option was introduced in Visual Studio 2022 17.13. + +If a specific **`/vlen`** value isn't specified, the default vector length depends on the **`/arch`** compiler option setting. The **`/vlen`** compiler option can override the default vector length specified by **`/arch:AVX512`**, **`/arch:AVX10.1`**, or **`/arch:AVX10.2`** compiler option. 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`** compiler option, 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. A 256-bit vector length 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 00000000000..fb3cced8479 --- /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 4a1addad374..dafe4bcd5f0 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 d87f06e1555..4694f1f3174 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 fb489848b54..69f135c446f 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 0d1b027b344..881a1ae174b 100644 --- a/docs/build/reference/wx-treat-linker-warnings-as-errors.md +++ b/docs/build/reference/wx-treat-linker-warnings-as-errors.md @@ -1,38 +1,50 @@ --- -description: "Learn more about: /WX (Treat Linker Warnings as Errors)" -title: "/WX (Treat Linker Warnings as Errors)" -ms.date: "11/04/2016" -f1_keywords: ["/WX"] +description: "Learn more about: /WX (Treat linker warnings as errors)" +title: "/WX (Treat linker warnings as errors)" +ms.date: 02/02/2023 +f1_keywords: ["VC.Project.VCLinkerTool.TreatLinkerWarningsAsErrors"] helpviewer_keywords: ["/WX linker option", "-WX linker option", "WX linker option"] ms.assetid: e4ba97c7-93f7-43ae-a4bb-d866790926c9 --- -# /WX (Treat Linker Warnings as Errors) +# `/WX` (Treat linker warnings as errors) -``` -/WX[:NO] -``` +Specifies whether to treat linker warnings as errors. + +## Syntax + +> **`/WX`**\[**`:NO`**]\ +> **`/WX`**\[**`:`***`nnnn`*\[**`,`***`nnnn`*...]] ## Remarks -/WX causes no output file to be generated if the linker generates a warning. +The **`/WX`** linker option causes no output file to be generated if the linker generates a warning. + +This option is similar to **`/WX`** for the compiler. For more information, see [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](compiler-option-warning-level.md). However, specifying **`/WX`** for the compilation doesn't imply that **`/WX`** will also be in effect for the link phase; you must explicitly specify **`/WX`** for each tool. -This option is similar to **/WX** for the compiler. For more information, see [/w, /W0, /W1, /W2, /W3, /W4, /w1, /w2, /w3, /w4, /Wall, /wd, /we, /wo, /Wv, /WX (Warning Level)](compiler-option-warning-level.md). However, specifying **/WX** for the compilation doesn't imply that **/WX** will also be in effect for the link phase; you must explicitly specify **/WX** for each tool. +In Visual Studio 2022 and later versions, you can specify **`/WX`** with one or more comma-separated *`nnnn`* arguments, where *`nnnn`* is a number between 4000 and 4999. The linker treats the corresponding *`LNKnnnn`* warnings as errors. -By default, **/WX** is not in effect. To treat linker warnings as errors, specify **/WX**. **/WX:NO** is the same as not specifying **/WX**. +By default, **`/WX`** isn't in effect. To treat linker warnings as errors, specify a **`/WX`** option. **`/WX:NO`** is the same as not specifying **`/WX`**, and overrides any previous **`/WX`** linker option. ### To set this linker option in the Visual Studio development environment -1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). +1. Open the project's **Property Pages** dialog box. For more information, see [Set compiler and build properties](../working-with-project-properties.md). + +1. To set or unset all warnings as errors, select the **Configuration Properties** > **Linker** > **General** property page. + +1. Modify the **Treat Linker Warnings as Errors** property. + +1. To set specific warnings as errors, select the **Configuration Properties** > **Linker** > **Command Line** property page. -1. Select the **Configuration Properties** > **Linker** > **Command Line** property page. +1. In the **Additional Options** edit control, add *`/WX:warnings`*, where *`warnings`* is a comma-separated list of linker warning numbers. -1. Enter the option into the **Additional Options** box. +1. Choose **OK** or **Apply** to save your changes. ### To set this linker option programmatically -1. See . +- See . ## See also -[MSVC linker reference](linking.md)
-[MSVC Linker Options](linker-options.md) +[MSVC linker reference](linking.md)\ +[MSVC linker options](linker-options.md)\ +[`/WX` compiler option](./compiler-option-warning-level.md) diff --git a/docs/build/reference/yd-place-debug-information-in-object-file.md b/docs/build/reference/yd-place-debug-information-in-object-file.md index b3e9699bb7c..ced560abe33 100644 --- a/docs/build/reference/yd-place-debug-information-in-object-file.md +++ b/docs/build/reference/yd-place-debug-information-in-object-file.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /Yd (Place Debug Information in Object File)" title: "/Yd (Place Debug Information in Object File)" -ms.date: "11/04/2016" +description: "Learn more about: /Yd (Place Debug Information in Object File)" +ms.date: 11/04/2016 f1_keywords: ["/yd"] helpviewer_keywords: ["/Yd compiler option [C++]", "-Yd compiler option [C++]", "debugging [C++], debug information files", "Yd compiler option [C++]"] -ms.assetid: c5a699fe-65ce-461e-964c-7f5eb2a8320a --- # /Yd (Place Debug Information in Object File) @@ -55,13 +54,13 @@ Suppose you have two base files, F.cpp and G.cpp, each containing these **#inclu The following command creates the precompiled header file ETC.pch and the object file F.obj: -``` +```cmd CL /YcETC.H /Z7 F.CPP ``` The object file F.obj includes type and symbol information for WINDOWS.h and ETC.h (and any other header files they include). Now you can use the precompiled header ETC.pch to compile the source file G.cpp: -``` +```cmd CL /YuETC.H /Z7 G.CPP ``` diff --git a/docs/build/reference/z7-zi-zi-debug-information-format.md b/docs/build/reference/z7-zi-zi-debug-information-format.md index 6cc70e4d4c8..4cf63809f02 100644 --- a/docs/build/reference/z7-zi-zi-debug-information-format.md +++ b/docs/build/reference/z7-zi-zi-debug-information-format.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /Z7, /Zi, /ZI (Debug Information Format)" title: "/Z7, /Zi, /ZI (Debug Information Format)" -ms.date: 12/09/2021 +ms.date: 3/26/2026 f1_keywords: ["VC.Project.VCCLCompilerTool.DebugInformationFormat", "/ZI", "/Zi", "/Z7", "VC.Project.VCCLWCECompilerTool.DebugInformationFormat"] helpviewer_keywords: ["C7 compatible compiler option [C++]", "Debug Information Format compiler option", "ZI compiler option", "-Zi compiler option [C++]", "/ZI compiler option [C++]", "Z7 compiler option [C++]", "debugging [C++], debug information files", "Zi compiler option [C++]", "/Zi compiler option [C++]", "program database compiler option [C++]", "full symbolic debugging information", "/Z7 compiler option [C++]", "line numbers only compiler option [C++]", "cl.exe compiler, debugging options", "-Z7 compiler option [C++]"] --- @@ -62,6 +62,27 @@ The **`/ZI`** option forces both the [`/Gy` (Enable Function-Level Linking)](gy- 1. Modify the **Debug Information Format** property. Choose **OK** to save your changes. +### To set this compiler option in a project file + +To set the debug information format in a `.vcxproj` project file, use the `` property within a `` item definition. The following table shows the MSBuild XML values and their corresponding compiler options: + +| MSBuild XML value | Compiler option | Description | +|---|---|---| +| `None` | *(none)* | No debug information | +| `OldStyle` | **`/Z7`** | Full symbolic debug information embedded in .obj files, no PDB | +| `ProgramDatabase` | **`/Zi`** | Program database (PDB) | +| `EditAndContinue` | **`/ZI`** | PDB with Edit and Continue support | + +For example, to set the debug information format to program database in a release configuration: + +```xml + + + ProgramDatabase + + +``` + ### To set this compiler option programmatically - See . diff --git a/docs/build/reference/zc-alignednew.md b/docs/build/reference/zc-alignednew.md index c8a583964a7..c591923268d 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 00000000000..2bec0383a7c --- /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 10c457b8d17..77534192bb9 100644 --- a/docs/build/reference/zc-conformance.md +++ b/docs/build/reference/zc-conformance.md @@ -1,12 +1,12 @@ --- title: "/Zc (Conformance)" description: "The /Zc conformance compiler options enable or disable support for conforming or backward-compatible behavior." -ms.date: 12/02/2021 +ms.date: 08/31/2023 helpviewer_keywords: ["/Zc compiler options [C++]", "-Zc compiler options [C++]", "Conformance compiler options", "Zc compiler options [C++]"] --- # `/Zc` (Conformance) -You can use the **`/Zc`** compiler options to specify standard or Microsoft-specific compiler behavior. +Use the **`/Zc`** compiler options to specify standard or Microsoft-specific compiler behavior. ## Syntax @@ -22,34 +22,42 @@ Here are the **`/Zc`** compiler options: | Option | Behavior | |--|--| -| [`/Zc:alignedNew`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation (on by default in C++17). | -| [`/Zc:auto`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`** (on by default). | -| [`/Zc:char8_t`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t` (off by default, except under **`/std:c++20`**). | -| [`/Zc:__cplusplus`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard (off by default). | -| [`/Zc:externC`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions (implied by **`/permissive-`**). | -| [`/Zc:externConstexpr`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables (off by default). | -| [`/Zc:forScope`](zc-forscope-force-conformance-in-for-loop-scope.md) | Enforce Standard C++ **`for`** scoping rules (on by default). | -| [`/Zc:hiddenFriend`](zc-hiddenfriend.md) | Enforce Standard C++ hidden friend rules (implied by **`/permissive-`**) | -| [`/Zc:implicitNoexcept`](zc-implicitnoexcept-implicit-exception-specifiers.md) | Enable implicit **`noexcept`** on required functions (on by default). | -| [`/Zc:inline`](zc-inline-remove-unreferenced-comdat.md) | Remove unreferenced functions or data if they're COMDAT or have internal linkage only (off by default). | -| [`/Zc:lambda`](zc-lambda.md) | Enable new lambda processor for conformance-mode syntactic checks in generic lambdas. | -| [`/Zc:noexceptTypes`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules (on by default in C++17 or later). | -| [`/Zc:preprocessor`](zc-preprocessor.md) | Use the new conforming preprocessor (off by default, except in C11/C17). | -| [`/Zc:referenceBinding`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a non-const lvalue reference (off by default). | -| [`/Zc:rvalueCast`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules (off by default). | -| [`/Zc:sizedDealloc`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions (on by default). | -| [`/Zc:strictStrings`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion (off by default). | -| [`/Zc:static_assert`](zc-static-assert.md) | strict handling of `static_assert` (implied by **`/permissive-`**). | -| [`/Zc:ternary`](zc-ternary.md) | Enforce conditional operator rules on operand types (off by default). | -| [`/Zc:threadSafeInit`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization (on by default). | -| [`/Zc:throwingNew`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure (off by default). | -| [`/Zc:trigraphs`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | -| [`/Zc:twoPhase`](zc-twophase.md) | Use non-conforming template parsing behavior (conforming by default). | -| [`/Zc:wchar_t`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef (on by default). | +| [`/Zc:__cplusplus[-]`](zc-cplusplus.md) | Enable the `__cplusplus` macro to report the supported standard. Off by default. | +| [`/Zc:__STDC__`](zc-stdc.md) | Enable the `__STDC__` macro to report the C standard is supported. Off by default. | +| [`/Zc:alignedNew[-]`](zc-alignednew.md) | Enable C++17 over-aligned dynamic allocation. Off by default unless **`/std:c++17`** or later is specified. | +| [`/Zc:auto[-]`](zc-auto-deduce-variable-type.md) | Enforce the new Standard C++ meaning for **`auto`**. On by default. | +| [`/Zc:char8_t[-]`](zc-char8-t.md) | Enable or disable C++20 native `u8` literal support as `const char8_t`. Off by default unless **`/std:c++20`** or later is specified. | +| [`/Zc:checkGwOdr[-]`](zc-check-gwodr.md) | Enforce Standard C++ ODR violations under `/Gw`. | +| [`/Zc:enumTypes[-]`](zc-enumtypes.md) | Enable Standard C++ rules for `enum` type deduction. Off by default. | +| [`/Zc:externC[-]`](zc-externc.md) | Enforce Standard C++ rules for `extern "C"` functions. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:externConstexpr[-]`](zc-externconstexpr.md) | Enable external linkage for **`constexpr`** variables. Off by default unless **`/permissive-`** is specified. | +| [`/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 **`/permissive-`** or **`/std:c++20`** or later is specified. | +| [`/Zc:noexceptTypes[-]`](zc-noexcepttypes.md) | Enforce C++17 **`noexcept`** rules. Off by default unless **`/std:c++17`** or later is specified. | +| [`/Zc:nrvo[-]`](zc-nrvo.md) | Enable optional copy and move elisions. Off by default unless **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later is specified. | +| [`/Zc:preprocessor[-]`](zc-preprocessor.md) | Use the new conforming preprocessor. Off by default unless **`/std:c11`** or later is specified. | +| [`/Zc:referenceBinding[-]`](zc-referencebinding-enforce-reference-binding-rules.md) | A UDT temporary won't bind to a nonconst lvalue reference. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:rvalueCast[-]`](zc-rvaluecast-enforce-type-conversion-rules.md) | Enforce Standard C++ explicit type conversion rules. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:sizedDealloc[-]`](zc-sizeddealloc-enable-global-sized-dealloc-functions.md) | Enable C++14 global sized deallocation functions. On by default. | +| [`/Zc:strictStrings[-]`](zc-strictstrings-disable-string-literal-type-conversion.md) | Disable string-literal to `char*` or `wchar_t*` conversion. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:static_assert[-]`](zc-static-assert.md) | strict handling of `static_assert`. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:templateScope[-]`](zc-templatescope.md) | Enforce Standard C++ template parameter shadowing rules. Off by default. | +| [`/Zc:ternary[-]`](zc-ternary.md) | Enforce conditional operator rules on operand types. Off by default unless **`/permissive-`** is specified. | +| [`/Zc:threadSafeInit[-]`](zc-threadsafeinit-thread-safe-local-static-initialization.md) | Enable thread-safe local static initialization. On by default. | +| [`/Zc:throwingNew[-]`](zc-throwingnew-assume-operator-new-throws.md) | Assume **`operator new`** throws on failure. Off by default. | +| [`/Zc:tlsGuards[-]`](zc-tlsguards.md) | Generate runtime checks for TLS variable initialization. On by default. | +| [`/Zc:trigraphs[-]`](zc-trigraphs-trigraphs-substitution.md) | Enable trigraphs (obsolete, off by default). | +| [`/Zc:twoPhase-`](zc-twophase.md) | Use nonconforming template parsing behavior (only applicable when **`/permissive-`** is specified, which defaults to conforming). | +| [`/Zc:wchar_t[-]`](zc-wchar-t-wchar-t-is-native-type.md) | **`wchar_t`** is a native type, not a typedef. On by default. | +| [`/Zc:zeroSizeArrayNew[-]`](zc-zerosizearraynew.md) | Call member `new`/`delete` for 0-size arrays of objects. On by default. | For more information about conformance issues in MSVC, see [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ## See also -[MSVC compiler options](compiler-options.md)
+[MSVC compiler options](compiler-options.md)\ [MSVC compiler command-line syntax](compiler-command-line-syntax.md) diff --git a/docs/build/reference/zc-enumtypes.md b/docs/build/reference/zc-enumtypes.md new file mode 100644 index 00000000000..7c2f590e2fc --- /dev/null +++ b/docs/build/reference/zc-enumtypes.md @@ -0,0 +1,88 @@ +--- +description: "Learn more about the /Zc:enumTypes (Enable enum type deduction) compiler option." +title: "/Zc:enumTypes (Enable enum type deduction)" +ms.date: 11/07/2022 +f1_keywords: ["/Zc:enumTypes"] +helpviewer_keywords: ["-Zc:enumTypes compiler option (C++)", "/Zc:enumTypes compiler option (C++)"] +--- +# `/Zc:enumTypes` (Enable enum type deduction) + +The **`/Zc:enumTypes`** compiler option enables C++ conforming **`enum`** underlying type and enumerator type deduction. + +## Syntax + +> **`/Zc:enumTypes`**\[**`-`**] + +## Remarks + +The **`/Zc:enumTypes`** compiler option implements Standard C++ conforming behavior for deduction of enumeration base types and the types of enumerators. + +The **`/Zc:enumTypes`** option is new in Visual Studio 2022 version 17.4. This option is off by default, and isn't enabled by **`/permissive-`**. To explicitly disable the option, use **`/Zc:enumTypes-`**. + +When enabled, the **`/Zc:enumTypes`** option is a potential source and binary breaking change. Some enumeration types change size when the conforming **`/Zc:enumTypes`** option is enabled. Certain Windows SDK headers include such enumeration definitions. + +The C++ Standard requires that the underlying type of an enumeration is large enough to hold all enumerators declared in it. Sufficiently large enumerators can set the underlying type of the **`enum`** to **`unsigned int`**, **`long long`**, or **`unsigned long long`**. Previously, such enumeration types always had an underlying type of **`int`** in the Microsoft compiler, regardless of enumerator values. + +The C++ Standard also specifies that, within an enumeration definition that has no fixed underlying type, the types of enumerators are determined by their initializers. Or, for the enumerators with no initializer, by the type of the previous enumerator (accounting for overflow). Previously, such enumerators were always given the deduced type of the enumeration, with a placeholder for the underlying type (typically **`int`**). + +In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ compiler didn't correctly determine the underlying type of an unscoped enumeration with no fixed base type. The compiler also didn't correctly model the types of enumerators. It could assume an incorrect type in enumerations without a fixed underlying type before the closing brace of the enumeration. Under **`/Zc:enumTypes`**, the compiler correctly implements the standard behavior. + +### Example: Underlying type of unscoped `enum` with no fixed type + +```cpp +enum Unsigned +{ + A = 0xFFFFFFFF // Value 'A' does not fit in 'int'. +}; + +// Previously, this static_assert failed. It passes with /Zc:enumTypes. +static_assert(std::is_same_v, unsigned int>); + +template +void f(T x) +{ +} + +int main() +{ + // Previously called f, now calls f. + f(+A); +} + +// Previously, this enum would have an underlying type of `int`, +// but Standard C++ requires this to have a 64-bit underlying type. +// The /Zc:enumTypes option changes the size of this enum from 4 to 8, +// which could impact binary compatibility with code compiled with an +// earlier compiler version, or without the switch. +enum Changed +{ + X = -1, + Y = 0xFFFFFFFF +}; +``` + +### Example: Enumerators within an `enum` definition with no fixed underlying type + +```cpp +enum Enum { + A = 'A', + B = sizeof(A) +}; + +static_assert(B == 1); // previously failed, now succeeds under /Zc:enumTypes +``` + +In this example the enumerator `A` should have type **`char`** prior to the closing brace of the enumeration, so `B` should be initialized using `sizeof(char)`. Before the **`/Zc:enumTypes`** fix, `A` had enumeration type `Enum` with a deduced underlying type **`int`**, and `B` was initialized using `sizeof(Enum)`, or 4. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:enumTypes`* or *`/Zc:enumTypes-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-externconstexpr.md b/docs/build/reference/zc-externconstexpr.md index c689fee737b..ee9c10b5022 100644 --- a/docs/build/reference/zc-externconstexpr.md +++ b/docs/build/reference/zc-externconstexpr.md @@ -1,10 +1,9 @@ --- description: "Learn more about: `/Zc:externConstexpr` (Enable extern constexpr variables)" title: "/Zc:externConstexpr (Enable extern constexpr variables)" -ms.date: "02/28/2018" +ms.date: 10/12/2023 f1_keywords: ["/Zc:externConstexpr"] helpviewer_keywords: ["-Zc:externConstexpr compiler option (C++)", "extern constexpr variables (C++)"] -ms.assetid: 4da5e33a-2e4d-4ed2-8616-bd8f43265c27 --- # `/Zc:externConstexpr` (Enable extern constexpr variables) @@ -16,9 +15,13 @@ The **`/Zc:externConstexpr`** compiler option tells the compiler to conform to t ## Remarks -The **`/Zc:externConstexpr`** compiler option causes the compiler to apply external linkage to variables declared by using `extern constexpr`. In earlier versions of Visual Studio, and by default or if **`/Zc:externConstexpr-`** is specified, Visual Studio applies internal linkage to **`constexpr`** variables even if the **`extern`** keyword is used. The **`/Zc:externConstexpr`** option is available starting in Visual Studio 2017 Update 15.6. and is off by default. The [`/permissive-`](permissive-standards-conformance.md) option does not enable **`/Zc:externConstexpr`**. +The **`/Zc:externConstexpr`** compiler option causes the compiler to apply external linkage to variables declared by using `extern constexpr`. -If a header file contains a variable declared `extern constexpr`, it must be marked [`__declspec(selectany)`](../../cpp/selectany.md) in order to merge the duplicate declarations into a single instance in the linked binary. Otherwise you may see linker errors, for example, LNK2005, for violations of the one-definition rule. +In earlier versions of Visual Studio, by default or if **`/Zc:externConstexpr-`** is specified, Visual Studio applies internal linkage to **`constexpr`** variables even if the **`extern`** keyword is used. The **`/Zc:externConstexpr`** option is available starting in Visual Studio 2017 Update 15.6. and is off by default. + +As of Visual Studio 2022 Update 17.6, the **`/permissive-`** option enables both **`/Zc:externConstexpr`** and [`/Zc:lambda`](zc-lambda.md). In prior versions, **`/permissive-`** didn't enable either one. + +If a header file contains a variable declared **`extern constexpr`**, it must be marked [`__declspec(selectany)`](../../cpp/selectany.md) in order to merge the duplicate declarations into a single instance in the linked binary. Otherwise you may see linker errors, for example, LNK2005, for violations of the one-definition rule. ### To set this compiler option in Visual Studio @@ -30,5 +33,6 @@ If a header file contains a variable declared `extern constexpr`, it must be mar ## See also -[`/Zc` (Conformance)](zc-conformance.md)
-[`auto` Keyword](../../cpp/auto-cpp.md) +[`auto` Keyword](../../cpp/auto-cpp.md)\ +[`permissive`](permissive-standards-conformance.md)\ +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-gotoscope.md b/docs/build/reference/zc-gotoscope.md new file mode 100644 index 00000000000..e71d6071423 --- /dev/null +++ b/docs/build/reference/zc-gotoscope.md @@ -0,0 +1,93 @@ +--- +description: "Learn more about the /Zc:gotoScope (Enforce conformance in goto scope) compiler option." +title: "/Zc:gotoScope (Enforce conformance in goto scope)" +ms.date: 11/11/2022 +f1_keywords: ["/Zc:gotoScope"] +helpviewer_keywords: ["-Zc:gotoScope compiler option (C++)", "/Zc:gotoScope compiler option (C++)"] +--- +# `/Zc:gotoScope` (Enforce conformance in goto scope) + +The **`/Zc:gotoScope`** compiler option enables checks for Standard C++ behavior around **`goto`** statements that jump over the initialization of local variables. + +## Syntax + +> **`/Zc:gotoScope`**\[**`-`**] + +## Remarks + +The **`/Zc:gotoScope`** compiler option enforces C++ Standard behavior around **`goto`** statements that jump over the initialization of one or more local variables. The compiler emits error [C2362](../../error-messages/compiler-errors-1/compiler-error-c2362.md) in all such cases when **`/Zc:gotoScope`** is specified. The **`/Zc:gotoScope-`** relaxes this check, but the compiler still emits an error if a **`goto`** skips initialization of a local variable that has a non-trivial destructor. + +The intent of the **`/Zc:gotoScope-`** option is to help ease the migration of older code bases to more conformant code. You may use it to suppress certain errors until you've updated the non-conforming code. + +The **`/Zc:gotoScope`** compiler option is new in Visual Studio 2022 version 17.4. The option is off by default. It's enabled automatically by the **`/permissive-`** option (or an option that implies **`/permissive-`**, such as **`/std:c++20`** or **`/std:c++latest`**). To enable the error check explicitly, add **`/Zc:gotoScope`** to the compiler command line. To explicitly disable the check, use the **`/Zc:gotoScope-`** option. The **`/Zc:gotoScope-`** must appear after the **`/permissive-`** option or any option that implies **`/permissive-`**. + +### Example + +This sample generates an error message when compiled using **`/Zc:gotoScope`**: + +```cpp +int g(int*); +bool failed(int); + +int f() { + int v1; + auto result = g(&v1); + if (failed(result)) + goto OnError; + int v2 = v1 + 2; + return v2; +OnError: + return -1; +} + +/* Output: +t.cpp(9): error C2362: initialization of 'v2' is skipped by 'goto OnError' +*/ +``` + +If the code is compiled with **`/Zc:gotoScope-`**, the compiler doesn't emit the error. + +Even when **`/Zc:gotoScope-`** is specified, the compiler still emits an error if the local variable has a non-trivial destructor. For example: + +```cpp +int g(int*); +bool failed(int); + +class S { +public: + S(int); + ~S(); + int mf() const; +}; + +int f() +{ + int v1; + auto result = g(&v1); + if (failed(result)) + goto OnError; + S s(v1); + return s.mf(); + +OnError: + return -1; +} + +/* Output: +t.cpp(17): error C2362: initialization of 's' is skipped by 'goto OnError' +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:gotoScope`* or *`/Zc:gotoScope-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-lambda.md b/docs/build/reference/zc-lambda.md index 6c2e3080ec3..6081969b7cc 100644 --- a/docs/build/reference/zc-lambda.md +++ b/docs/build/reference/zc-lambda.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /Zc:lambda (Enable updated lambda processor)" title: "/Zc:lambda (Enable updated lambda processor)" -ms.date: 08/11/2021 +ms.date: 06/01/2023 f1_keywords: ["/Zc:lambda"] helpviewer_keywords: ["-Zc:lambda compiler option (C++)", "/Zc:lambda compiler option (C++)"] --- @@ -17,7 +17,7 @@ The **`/Zc:lambda`** compiler option enables conforming lambda grammar and proce The **`/Zc:lambda`** compiler option enables the conforming lambda processor. It parses and implements lambda code according to the C++ standard. This option is off by default, which uses the legacy lambda processor. Use this option to enable conformance-mode syntax checks of generic lambdas when you use the default [`/std:c++14`](std-specify-language-standard-version.md) or the [`/std:c++17`](std-specify-language-standard-version.md) compiler options. -**`/Zc:lambda`** is automatically enabled by the [`/std:c++20`](std-specify-language-standard-version.md), [`/std:c++latest`](std-specify-language-standard-version.md), and [`/experimental:module`](experimental-module.md) options. You can disable it explicitly by using **`/Zc:lambda-`**. The [`/permissive-`](permissive-standards-conformance.md) option doesn't enable **`/Zc:lambda`**. +**`/Zc:lambda`** is automatically enabled by the [`/std:c++20`](std-specify-language-standard-version.md), [`/std:c++latest`](std-specify-language-standard-version.md), [`/permissive-`](permissive-standards-conformance.md), and [`/experimental:module`](experimental-module.md) options. You can disable it explicitly by using **`/Zc:lambda-`**. The **`/Zc:lambda`** option is available starting in Visual Studio 2019 version 16.8. It's available as **`/experimental:newLambdaProcessor`** starting in Visual Studio 2019 version 16.3, but this spelling is now deprecated. diff --git a/docs/build/reference/zc-nrvo.md b/docs/build/reference/zc-nrvo.md new file mode 100644 index 00000000000..1248f10e14d --- /dev/null +++ b/docs/build/reference/zc-nrvo.md @@ -0,0 +1,49 @@ +--- +description: "Learn more about the /Zc:nrvo (Control optional NRVO) compiler option." +title: "/Zc:nrvo (Control optional NRVO)" +ms.date: 11/10/2022 +f1_keywords: ["/Zc:nrvo"] +helpviewer_keywords: ["-Zc:nrvo compiler option (C++)", "/Zc:nrvo compiler option (C++)"] +--- +# `/Zc:nrvo` (Control optional NRVO) + +The **`/Zc:nrvo`** compiler option controls Standard C++ optional named return value optimization (NRVO) copy or move elision behavior. + +## Syntax + +> **`/Zc:nrvo`**\[**`-`**] + +## Remarks + +In Visual Studio 2022 version 17.4 and later, you can explicitly enable optional copy or move elision behavior by using the **`/Zc:nrvo`** compiler option. This option is off by default, but is set automatically when you compile using the **`/O2`** option, the **`/permissive-`** option, or **`/std:c++20`** or later. Under **`/Zc:nrvo`**, copy and move elision is performed wherever possible. Optional copy or move elision can also be explicitly disabled by using the **`/Zc:nrvo-`** option. These compiler options only control optional copy or move elision. Mandatory copy or move elision (specified by the C++ Standard) can't be disabled. + +### Mandatory copy and move elision + +The C++ standard requires copy or move elision when the returned value is initialized as part of the return statement. For example, it's required when a function returns an `ExampleType` returned by using `return ExampleType();`. The MSVC compiler always performs copy and move elision for **`return`** statements when it's required, even under **`/Zc:nrvo-`**. + +### Optional copy and move elision + +When a **`return`** statement contains an expression of non-primitive type, its execution copies the expression result into the return slot of the calling function. The compiler invokes the copy or move constructor of the returned type. Then, as the function is exited, destructors for function-local variables are called, which includes any variables named in the expression. + +The C++ standard allows (but doesn't require) the compiler to optionally construct the returned object directly in the return slot of the calling function. This construction skips (or *elides*) the copy or move constructor executed as part of the **`return`** statement. Unlike most other optimizations, this transformation is allowed to have an observable effect on the program's output. Namely, the copy or move constructor and associated destructor are called one less time. The standard still requires that the named returned variable has a defined copy or move constructor, even if the compiler elides the constructor in all cases. + +In versions before Visual Studio 2022 version 17.4, when optimizations are disabled (such as under **`/Od`** or in functions marked `#pragma optimize("", off)`) the compiler only performs mandatory copy and move elision. Under **`/O2`**, the older compilers perform optional copy or move elision on return of a named variable in an optimized function when all of these conditions are met: it has no loops or exception handling, it doesn't return multiple symbols with overlapping lifetimes, the type's copy or move constructor doesn't have default arguments. + +Visual Studio 2022 version 17.4 increases the number of places where the compiler does optional copy or move elisions under **`/Zc:nrvo`**, whether enabled explicitly, or automatically by using the **`/O2`**, **`/permissive-`**, or **`/std:c++20`** or later options. Under **`/Zc:nrvo`**, the compiler performs optional copy or move elision on return of a named variable for any function when: it has no loops or exception handling (as before); it returns the variable from a loop; it has exception handling; the returned type's copy or move constructor has default arguments. Optional copy or move elisions are never done when **`/Zc:nrvo-`** is applied, or when the function returns multiple symbols with overlapping lifetimes, or for a throw of a named variable. + +For more information and examples of mandatory and optional copy elision under **`/Zc:nrvo`**, see [Improving Copy and Move Elision](https://devblogs.microsoft.com/cppblog/improving-copy-and-move-elision) in the C++ Team Blog. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:nrvo`* or *`/Zc:nrvo-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/O2`](./o1-o2-minimize-size-maximize-speed.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-static-assert.md b/docs/build/reference/zc-static-assert.md index 78276252a83..9eb98b94a5f 100644 --- a/docs/build/reference/zc-static-assert.md +++ b/docs/build/reference/zc-static-assert.md @@ -1,7 +1,7 @@ --- description: "Learn more about: /Zc:static_assert (Strict static_assert handling)" title: "/Zc:static_assert (Strict static_assert handling)" -ms.date: 12/15/2021 +ms.date: 1/15/2025 f1_keywords: ["/Zc:static_assert"] helpviewer_keywords: ["/Zc:static_assert compiler option (C++)"] --- @@ -16,7 +16,9 @@ The **`/Zc:static_assert`** compiler option tells the compiler to evaluate `stat ## Remarks -The **`/Zc:static_assert`** compiler option tells the compiler to evaluate a `static_assert` in the body of a function template or in the body of a class template member function when first parsed, if the test expression isn't dependent. If the non-dependent test expression isn't `false`, the compiler emits an error immediately. When the test expression is dependent, the `static_assert` isn't evaluated until the template is instantiated. +Starting with Visual Studio 17.10, `/Zc:static_assert` and `/Zc:static_assert-` have no effect. Both options are ignored to avoid breaking builds that use them. `static_assert` is now never evaluated when parsing class or function templates. + +The **`/Zc:static_assert`** compiler option tells the compiler to evaluate a `static_assert` in the body of a function template or in the body of a class template member function when first parsed, if the test expression isn't dependent. If the non-dependent test expression is `false`, the compiler emits an error immediately. When the test expression is dependent, the `static_assert` isn't evaluated until the template is instantiated. The **`/Zc:static_assert`** option is available starting in Visual Studio 2022 version 17.1. In earlier versions of Visual Studio, or if **`/Zc:static_assert-`** is specified, Visual Studio doesn't do dependent analysis if the `static_assert` is within the body of a function template or within the body of a member function of a class template. Instead, it only evaluates the `static_assert` when a template is instantiated. diff --git a/docs/build/reference/zc-stdc.md b/docs/build/reference/zc-stdc.md new file mode 100644 index 00000000000..7a55aafc980 --- /dev/null +++ b/docs/build/reference/zc-stdc.md @@ -0,0 +1,60 @@ +--- +description: "Learn more about the /Zc:__STDC__ (Enable __STDC__ macro) compiler option." +title: "/Zc:__STDC__ (Enable __STDC__ macro)" +ms.date: 11/07/2022 +f1_keywords: ["/Zc:__STDC__"] +helpviewer_keywords: ["-Zc:__STDC__ compiler option (C++)", "/Zc:__STDC__ compiler option (C++)"] +--- +# `/Zc:__STDC__` (Enable `__STDC__` macro) + +The **`/Zc:__STDC__`** compiler option defines the built-in `__STDC__` preprocessor macro as 1 in C code. + +## Syntax + +> **`/Zc:__STDC__`** + +## Remarks + +The **`/Zc:__STDC__`** compiler option implements Standard C conforming behavior for the `__STDC__` preprocessor macro, setting it to 1 when compiling C11 and C17 code. + +The **`/Zc:__STDC__`** option is new in Visual Studio 2022 version 17.2. This option is off by default, but can be enabled explicitly when **`/std:c11`** or **`/std:c17`** is specified. There's no negative version of the option. + +This option is a source breaking change. Due to the behavior of the UCRT, which doesn't expose POSIX functions when `__STDC__` is `1`, it isn't possible to define this macro for C by default without introducing breaking changes to the stable language versions. + +### Example + +```c +// test__STDC__.c +#include +#include +#include + +int main() { +#if __STDC__ + int f = _open("file.txt", _O_RDONLY); + _close(f); +#else + int f = open("file.txt", O_RDONLY); + close(f); +#endif +} + +/* Command line behavior + +C:\Temp>cl /EHsc /W4 /Zc:__STDC__ test__STDC__.c && test__STDC__ + +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:__STDC__`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-templatescope.md b/docs/build/reference/zc-templatescope.md new file mode 100644 index 00000000000..a6ca453833f --- /dev/null +++ b/docs/build/reference/zc-templatescope.md @@ -0,0 +1,49 @@ +--- +description: "Learn more about the /Zc:templateScope (Check template parameter shadowing) compiler option." +title: "/Zc:templateScope (Check template parameter shadowing)" +ms.date: 11/11/2022 +f1_keywords: ["/Zc:templateScope"] +helpviewer_keywords: ["-Zc:templateScope compiler option (C++)", "/Zc:templateScope compiler option (C++)"] +--- +# `/Zc:templateScope` (Check template parameter shadowing) + +The **`/Zc:templateScope`** compiler option enables checks for Standard C++ behavior around shadowing of template parameters. + +## Syntax + +> **`/Zc:templateScope`**\[**`-`**] + +## Remarks + +The C++ Standard doesn't allow the reuse of a template parameter's name (or *shadowing*) for another declaration within the scope of the template. The **`/Zc:templateScope`** compiler option enables an error check for such shadowing. + +The **`/Zc:templateScope`** option is new in Visual Studio 2022 version 17.5 preview 1. The option is off by default even when the code is compiled using the **`/permissive-`** option (or an option that implies **`/permissive-`**, such as **`/std:c++20`** or **`/std:c++latest`**). To enable the error check, you must explicitly add **`/Zc:templateScope`** to the compiler command line. To explicitly disable the check, use the **`/Zc:templateScope-`** option. + +### Example + +Under **`/Zc:templateScope`**, this sample code produces an error: + +```cpp +template +void f(T&& t) { + int T = 13; +} + +/* Output: +t.cpp(3): error C7527: 'T': a template parameter name cannot be reused within its scope +*/ +``` + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:templateScope`* or *`/Zc:templateScope-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md)\ +[`/permissive-`](./permissive-standards-conformance.md)\ +[`/std` (Specify language standard version)](std-specify-language-standard-version.md) diff --git a/docs/build/reference/zc-ternary.md b/docs/build/reference/zc-ternary.md index 61d8b6a0585..b77f0d7739f 100644 --- a/docs/build/reference/zc-ternary.md +++ b/docs/build/reference/zc-ternary.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: `/Zc:ternary` (Enforce conditional operator rules)" title: "/Zc:ternary (Enforce conditional operator rules)" -ms.date: "09/12/2019" +description: "Learn more about: `/Zc:ternary` (Enforce conditional operator rules)" +ms.date: 09/12/2019 f1_keywords: ["/Zc:ternary"] helpviewer_keywords: ["/Zc:ternary", "Zc:ternary", "-Zc:ternary"] --- @@ -23,7 +23,7 @@ The **`/Zc:ternary`** option is off by default in Visual Studio 2017. Use **`/Zc ### Examples -This sample shows how a class that provides both non-explicit initialization from a type, and conversion to a type, can lead to ambiguous conversions. This code is accepted by the compiler by default, but rejected when **/`Zc:ternary`** or **`/permissive-`** is specified. +This sample shows how a class that provides both non-explicit initialization from a type, and conversion to a type, can lead to ambiguous conversions. This code is accepted by the compiler by default, but rejected when **`/Zc:ternary`** or **`/permissive-`** is specified. ```cpp // zcternary1.cpp diff --git a/docs/build/reference/zc-tlsguards.md b/docs/build/reference/zc-tlsguards.md new file mode 100644 index 00000000000..15c36abf138 --- /dev/null +++ b/docs/build/reference/zc-tlsguards.md @@ -0,0 +1,32 @@ +--- +title: "/Zc:tlsGuards (Check TLS initialization)" +description: "Learn more about the /Zc:tlsGuards (Check TLS initialization) compiler option." +ms.date: 11/08/2022 +f1_keywords: ["/Zc:tlsGuards"] +helpviewer_keywords: ["-Zc:tlsGuards compiler option (C++)", "/Zc:tlsGuards compiler option (C++)"] +--- +# `/Zc:tlsGuards` (Check TLS initialization) + +The **`/Zc:tlsGuards`** compiler option generates runtime checks for thread local storage (TLS) initialization in DLLs. + +## Syntax + +> **`/Zc:tlsGuards`**\[**`-`**] + +## Remarks + +The **`/Zc:tlsGuards`** compiler option enables checks for initialization of thread-local variables in DLLs. Previously, thread-local variables in DLLs weren't correctly initialized. Other than on the thread that loaded the DLL, they weren't initialized before first use on threads that existed before the DLL was loaded. The **`/Zc:tlsGuards`** option enables code that corrects this defect. Thread-local variables in such a DLL get initialized immediately before their first use on such threads. + +The **`/Zc:tlsGuards`** option is new in Visual Studio 2019 version 16.5. This option is on by default in all compiler modes. The new behavior of testing for initialization on uses of thread-local variables may be disabled by using the **`/Zc:tlsGuards-`** compiler option. To disable checks for specific thread-local variables, use the [`[[msvc::no_tls_guard]]`](../../cpp/attributes.md) attribute. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:tlsGuards`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-twophase.md b/docs/build/reference/zc-twophase.md index d4e1d5506bc..56752563138 100644 --- a/docs/build/reference/zc-twophase.md +++ b/docs/build/reference/zc-twophase.md @@ -1,29 +1,29 @@ --- title: "/Zc:twoPhase- (disable two-phase name lookup)" description: "Explains how /Zc:twoPhase- disables two-phase name lookup when /permissive- is specified." -ms.date: "12/03/2019" +ms.date: 09/27/2022 f1_keywords: ["twoPhase", "/Zc:twoPhase"] helpviewer_keywords: ["twoPhase", "disable two-phase name lookup", "/Zc:twoPhase"] --- -# /Zc:twoPhase- (disable two-phase name lookup) +# `/Zc:twoPhase-` (disable two-phase name lookup) -The **/Zc:twoPhase-** option, under **/permissive-**, tells the compiler to use the original, non-conforming Microsoft C++ compiler behavior to parse and instantiate class templates and function templates. +The **`/Zc:twoPhase-`** option, under **`/permissive-`**, tells the compiler to use the original, non-conforming Microsoft C++ compiler behavior to parse and instantiate class templates and function templates. ## Syntax -> **/Zc:twoPhase-** +> **`/Zc:twoPhase-`** ## Remarks -Visual Studio 2017 version 15.3 and later: Under [/permissive-](permissive-standards-conformance.md), the compiler uses two-phase name lookup for template name resolution. If you also specify **/Zc:twoPhase-**, the compiler reverts to its previous non-conforming class template and function template name resolution and substitution behavior. When **/permissive-** isn't specified, the non-conforming behavior is the default. +Visual Studio 2017 version 15.3 and later: Under [`/permissive-`](permissive-standards-conformance.md), the compiler uses two-phase name lookup for template name resolution. If you also specify **`/Zc:twoPhase-`**, the compiler reverts to its previous non-conforming class template and function template name resolution and substitution behavior. When **`/permissive-`** isn't specified, the non-conforming behavior is the default. -The Windows SDK header files in version 10.0.15063.0 (Creators Update or RS2) and earlier don't work in conformance mode. **/Zc:twoPhase-** is required to compile code for those SDK versions when you use **/permissive-**. Versions of the Windows SDK starting with version 10.0.15254.0 (Fall Creators Update or RS3) work correctly in conformance mode. They don't require the **/Zc:twoPhase-** option. +The Windows SDK header files in version 10.0.15063.0 (Creators Update or RS2) and earlier don't work in conformance mode. **`/Zc:twoPhase-`** is required to compile code for those SDK versions when you use **`/permissive-`**. Versions of the Windows SDK starting with version 10.0.15254.0 (Fall Creators Update or RS3) work correctly in conformance mode. They don't require the **`/Zc:twoPhase-`** option. -Use **/Zc:twoPhase-** if your code requires the old behavior to compile correctly. Strongly consider updating your code to conform to the standard. +Use **`/Zc:twoPhase-`** if your code requires the old behavior to compile correctly. Strongly consider updating your code to conform to the standard. -### Compiler behavior under /Zc:twoPhase- +### Compiler behavior under `/Zc:twoPhase-` -By default, or in Visual Studio 2017 version 15.3 and later when you specify both **/permissive-** and **/Zc:twoPhase-**, the compiler uses this behavior: +By default, or in Visual Studio 2017 version 15.3 and later when you specify both **`/permissive-`** and **`/Zc:twoPhase-`**, the compiler uses this behavior: - It parses only the template declaration, the class head, and the base class list. The template body is captured as a token stream. No function bodies, initializers, default arguments, or noexcept arguments are parsed. The class template is pseudo-instantiated on a tentative type to validate that the declarations in the class template are correct. Consider this class template: @@ -33,7 +33,7 @@ By default, or in Visual Studio 2017 version 15.3 and later when you specify bot The template declaration, `template `, the class head `class Derived`, and the base-class list `public Base` are parsed, but the template body is captured as a token stream. -- When parsing a function template, the compiler parses only the function signature. The function body is never parsed. Instead, it's captured as a token stream. +- When it parses a function template, the compiler parses only the function signature. The function body is never parsed. Instead, it's captured as a token stream. As a result, if the template body has syntax errors, but the template never gets instantiated, the compiler doesn't diagnose the errors. @@ -65,7 +65,7 @@ int main() } ``` -Here's the output when you use the default mode, conformance mode, and conformance mode with **/Zc:twoPhase-** compiler options: +Here's the output when you use the default mode, conformance mode, and conformance mode with **`/Zc:twoPhase-`** compiler options: ```cmd C:\Temp>cl /EHsc /nologo /W4 zctwophase.cpp && zctwophase @@ -81,11 +81,11 @@ zctwophase.cpp Microsoft one-phase ``` -When compiled in conformance mode under **/permissive-**, this program prints "`Standard two-phase`", because the second overload of `func` isn't visible when the compiler reaches the template. If you add **/Zc:twoPhase-**, the program prints "`Microsoft one-phase`". The output is the same as when you don't specify **/permissive-**. +When compiled in conformance mode under **`/permissive-`**, this program prints "`Standard two-phase`", because the second overload of `func` isn't visible when the compiler reaches the template. If you add **`/Zc:twoPhase-`**, the program prints "`Microsoft one-phase`". The output is the same as when you don't specify **`/permissive-`**. -*Dependent names* are names that depend on a template parameter. These names have lookup behavior that is also different under **/Zc:twoPhase-**. In conformance mode, dependent names aren't bound at the point of the template's definition. Instead, the compiler looks them up when it instantiates the template. For function calls with a dependent function name, the name gets bound to functions visible at the call site in the template definition. Additional overloads from argument-dependent lookup are added, both at the point of the template definition, and at the point of template instantiation. +*Dependent names* are names that depend on a template parameter. These names have lookup behavior that is also different under **`/Zc:twoPhase-`**. In conformance mode, dependent names aren't bound at the point of the template's definition. Instead, the compiler looks them up when it instantiates the template. For function calls with a dependent function name, the name gets bound to functions visible at the call site in the template definition. Other overloads from argument-dependent lookup are added, both at the point of the template definition, and at the point of template instantiation. -Two-phase lookup consists of two parts: The lookup for non-dependent names during template definition, and the lookup for dependent names during template instantiation. Under **/Zc:twoPhase-**, the compiler doesn't do argument-dependent lookup separately from unqualified lookup. That is, it doesn't do two-phase lookup, so the results of overload resolution may be different. +Two-phase lookup consists of two parts: The lookup for non-dependent names during template definition, and the lookup for dependent names during template instantiation. Under **`/Zc:twoPhase-`**, the compiler doesn't do argument-dependent lookup separately from unqualified lookup. That is, it doesn't do two-phase lookup, so the results of overload resolution may be different. Here's another example: @@ -118,28 +118,28 @@ int main() { } ``` -When compiled without **/permissive-**, this code prints: +When compiled without **`/permissive-`**, this code prints: ```Output func(int) NS::func(NS::S) ``` -When compiled with **/permissive-**, but without **/Zc:twoPhase-**, this code prints: +When compiled with **`/permissive-`**, but without **`/Zc:twoPhase-`**, this code prints: ```Output func(long) NS::func(NS::S) ``` -When compiled with both **/permissive-** and **/Zc:twoPhase-**, this code prints: +When compiled with both **`/permissive-`** and **`/Zc:twoPhase-`**, this code prints: ```Output func(int) NS::func(NS::S) ``` -In conformance mode under **/permissive-**, the call `tfunc(1729)` resolves to the `void func(long)` overload. It doesn't resolve to the `void func(int)` overload, as under **/Zc:twoPhase-**. That's because the unqualified `func(int)` is declared after the definition of the template, and it isn't found through argument-dependent lookup. But `void func(S)` does participate in argument-dependent lookup, so it's added to the overload set for the call `tfunc(s)`, even though it's declared after the template function. +In conformance mode under **`/permissive-`**, the call `tfunc(1729)` resolves to the `void func(long)` overload. It doesn't resolve to the `void func(int)` overload, as under **`/Zc:twoPhase-`**. The reason is, the unqualified `func(int)` is declared after the definition of the template, and it isn't found through argument-dependent lookup. But `void func(S)` does participate in argument-dependent lookup, so it's added to the overload set for the call `tfunc(s)`, even though it's declared after the function template. ### Update your code for two-phase conformance @@ -151,7 +151,7 @@ A conforming compiler parses `Foo` as a variable in the scope of `T`, meaning th `T::template Foo(c);` -In versions Visual Studio 2017 version 15.3 and later, when **/permissive-** and **/Zc:twoPhase-** are specified, the compiler allows this code without the **`template`** keyword. It interprets the code as a call to a function template with an argument of `a || b`, because it only parses templates in a limited fashion. The code above isn't parsed at all in the first phase. During the second phase, there's enough context to tell that `T::Foo` is a template rather than a variable, so the compiler doesn't enforce use of the keyword. +In versions Visual Studio 2017 version 15.3 and later, when **`/permissive-`** and **`/Zc:twoPhase-`** are specified, the compiler allows this code without the **`template`** keyword. It interprets the code as a call to a function template with an argument of `a || b`, because it only parses templates in a limited fashion. The code above isn't parsed at all in the first phase. During the second phase, there's enough context to tell that `T::Foo` is a template rather than a variable, so the compiler doesn't enforce use of the keyword. This behavior can also be seen by eliminating the keyword **`typename`** before names in function template bodies, initializers, default arguments, and noexcept arguments. For example: @@ -163,7 +163,7 @@ typename T::TYPE func(typename T::TYPE*) } ``` -If you don't use the keyword **`typename`** in the function body, this code compiles under **/permissive- /Zc:twoPhase-**, but not under **/permissive-** alone. The **`typename`** keyword is required to indicate that the `TYPE` is dependent. Because the body isn't parsed under **/Zc:twoPhase-**, the compiler does't require the keyword. In **/permissive-** conformance mode, code without the **`typename`** keyword generates errors. To migrate your code to conformance in Visual Studio 2017 version 15.3 and beyond, insert the **`typename`** keyword where it's missing. +If you don't use the keyword **`typename`** in the function body, this code compiles under **`/permissive- /Zc:twoPhase-`**, but not under **`/permissive-`** alone. The **`typename`** keyword is required to indicate that the `TYPE` is dependent. Because the body isn't parsed under **`/Zc:twoPhase-`**, the compiler doesn't require the keyword. In **`/permissive-`** conformance mode, code without the **`typename`** keyword generates errors. To migrate your code to conformance in Visual Studio 2017 version 15.3 and beyond, insert the **`typename`** keyword where it's missing. Similarly, consider this code sample: @@ -175,9 +175,9 @@ typename T::template X::TYPE func(typename T::TYPE) } ``` -Under **/permissive- /Zc:twoPhase-** and in older compilers, the compiler only requires the **`template`** keyword on line 2. In conformance mode, the compiler now also requires the **`template`** keyword on line 4 to indicate that `T::X` is a template. Look for code that is missing this keyword, and supply it to make your code conform to the standard. +Under **`/permissive- /Zc:twoPhase-`** and in older compilers, the compiler only requires the **`template`** keyword on line 2. In conformance mode, the compiler now also requires the **`template`** keyword on line 4 to indicate that `T::X` is a template. Look for code that is missing this keyword, and supply it to make your code conform to the standard. -For more information about conformance issues, see [C++ conformance improvements in Visual Studio](../../overview/cpp-conformance-improvements.md) and [Nonstandard Behavior](../../cpp/nonstandard-behavior.md). +For more information about conformance issues, see [C++ conformance improvements in Visual Studio](../../overview/cpp-conformance-improvements.md) and [Nonstandard behavior](../../cpp/nonstandard-behavior.md). ### To set this compiler option in the Visual Studio development environment @@ -185,8 +185,8 @@ For more information about conformance issues, see [C++ conformance improvements 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. -1. Modify the **Additional Options** property to include **/Zc:twoPhase-** and then choose **OK**. +1. Modify the **Additional Options** property to include *`/Zc:twoPhase-`* and then choose **OK**. ## See also -[/Zc (Conformance)](zc-conformance.md) +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zc-zerosizearraynew.md b/docs/build/reference/zc-zerosizearraynew.md new file mode 100644 index 00000000000..05abb101da0 --- /dev/null +++ b/docs/build/reference/zc-zerosizearraynew.md @@ -0,0 +1,32 @@ +--- +title: "/Zc:zeroSizeArrayNew (Call member new/delete on arrays)" +description: "Learn more about the /Zc:zeroSizeArrayNew (Call member new/delete on arrays) compiler option." +ms.date: 11/08/2022 +f1_keywords: ["/Zc:zeroSizeArrayNew"] +helpviewer_keywords: ["-Zc:zeroSizeArrayNew compiler option (C++)", "/Zc:zeroSizeArrayNew compiler option (C++)"] +--- +# `/Zc:zeroSizeArrayNew` (Call member new/delete on arrays) + +The **`/Zc:zeroSizeArrayNew`** compiler option calls member `new` and `delete` for zero-length arrays of objects. + +## Syntax + +> **`/Zc:zeroSizeArrayNew`**\[**`-`**] + +## Remarks + +The **`/Zc:zeroSizeArrayNew`** compiler option enables calls to member `new` and `delete` for zero-length arrays of objects of class types with virtual destructors. This behavior conforms to the standard. This compiler option is new in Visual Studio 2019 version 16.9 and is enabled by default in all compiler modes. Previously, in code compiled by versions before Visual Studio 2019 version 16.9, the compiler invoked global `new` and `delete` on zero-length arrays of objects of class types with virtual destructors. + +The **`/Zc:zeroSizeArrayNew`** option may cause a breaking change in code that relied on the previous non-conforming behavior. To restore the previous behavior, use the **`/Zc:zeroSizeArrayNew-`** compiler option. + +### To set this compiler option in Visual Studio + +1. Open the project's **Property Pages** dialog box. For details, see [Set C++ compiler and build properties in Visual Studio](../working-with-project-properties.md). + +1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. + +1. In **Additional options**, add *`/Zc:zeroSizeArrayNew`* or *`/Zc:zeroSizeArrayNew-`*. Choose **OK** or **Apply** to save your changes. + +## See also + +[`/Zc` (Conformance)](zc-conformance.md) diff --git a/docs/build/reference/zf.md b/docs/build/reference/zf.md index d15547b2e8c..cb7b1c17ec3 100644 --- a/docs/build/reference/zf.md +++ b/docs/build/reference/zf.md @@ -19,7 +19,7 @@ The **/Zf** option enables compiler support for faster generation of PDB files w Because the **/Zf** option only applies to PDB generation, it requires the [/Zi](z7-zi-zi-debug-information-format.md) or [/ZI](z7-zi-zi-debug-information-format.md) option. -The **/Zf** option is available beginning in Visual Studio 2017 version 15.1, where it is off by default. Starting in Visual Studio 2017 version 15.7, this option is on by default when the **/Zi** or **/ZI** option is enabled. +The **/Zf** option is available beginning in Visual Studio 2017 version 15.1, where it is off by default. Starting in Visual Studio 2017 version 15.7, this option is on by default when the **/Zi** or **/ZI** option is enabled. To explicitly disable this option, use **/Zf-**. ### To set this compiler option in the Visual Studio development environment diff --git a/docs/build/reference/zh.md b/docs/build/reference/zh.md index 3cefaf8e712..3cfa06349a0 100644 --- a/docs/build/reference/zh.md +++ b/docs/build/reference/zh.md @@ -1,20 +1,37 @@ --- title: "/ZH (Hash algorithm for calculation of file checksum in debug info)" -description: "Use the /ZH compiler option to enable MD5, SHA-1, or SHA-256 source file checksums in debug info" -ms.date: 02/01/2022 -f1_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256"] -helpviewer_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256", "/ZH compiler option", "/ZH:MD5 compiler option", "/ZH:SHA1 compiler option", "/ZH:SHA_256 compiler option", "Hash algorithm for file checksum in debug info"] +description: "Use the /ZH compiler option to enable source file checksums in debug info" +ms.date: 05/25/2026 +f1_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256", "/ZH:SHA384", "/ZH:SHA512"] +helpviewer_keywords: ["/ZH", "/ZH:MD5", "/ZH:SHA1", "/ZH:SHA_256", "/ZH:SHA384", "/ZH:SHA512", "/ZH compiler option", "/ZH:MD5 compiler option", "/ZH:SHA1 compiler option", "/ZH:SHA_256 compiler option", "/ZH:SHA384 compiler option", "/ZH:SHA512 compiler option", "Hash algorithm for file checksum in debug info"] --- # `/ZH` (Hash algorithm for calculation of file checksum in debug info) Specifies which cryptographic hash algorithm to use to generate a checksum of each source file. +> [!NOTE] +> The **`/ZH`** option is available in Visual Studio 2019 version 16.4 and later. + ## Syntax +::: moniker range="<=msvc-170" + > **`/ZH:MD5`**\ > **`/ZH:SHA1`**\ > **`/ZH:SHA_256`** +::: moniker-end + +::: moniker range=">=msvc-180" + +> **`/ZH:MD5`**\ +> **`/ZH:SHA1`**\ +> **`/ZH:SHA_256`**\ +> **`/ZH:SHA384`**\ +> **`/ZH:SHA512`** + +::: moniker-end + ## Arguments **`/ZH:MD5`**\ @@ -26,15 +43,36 @@ Use an SHA-1 hash for the checksum. **`/ZH:SHA_256`**\ Use an SHA-256 hash for the checksum. This option is the default in Visual Studio 2022 version 17.0 and later. +::: moniker range=">=msvc-180" + +**`/ZH:SHA384`**\ +Use an SHA-384 hash for the checksum. + +**`/ZH:SHA512`**\ +Use an SHA-512 hash for the checksum. + +::: moniker-end + ## Remarks -PDB files store a checksum for each source file, compiled into the object code in the associated executable. The checksum allows the debugger to verify that the source code it loads matches the executable. The compiler and debugger support MD5, SHA-1, and SHA-256 hash algorithms. By default, in Visual Studio 2019 the compiler uses an MD5 hash to generate the checksum. To specify this hash algorithm explicitly, use the **`/ZH:MD5`** option. +::: moniker range="<=msvc-170" -Because of a risk of collision problems in MD5 and SHA-1, Microsoft recommends you use the **`/ZH:SHA_256`** option. The SHA-256 hash might result in a small increase in compile times. The **`/ZH:SHA_256`** option is the default in Visual Studio 2022 version 17.0 and later. +PDB files store a checksum for each source file, compiled into the object code in the associated executable. The checksum allows the debugger to verify that the source code it loads matches the executable. The compiler and debugger support MD5, SHA-1, and SHA-256 hash algorithms. +Because of a risk of collision problems in MD5 and SHA-1, use the **`/ZH:SHA_256`** option or stronger. -When more than one **`/ZH`** option is specified, the last option is used. +::: moniker-end + +::: moniker range=">=msvc-180" + +PDB files store a checksum for each source file, compiled into the object code in the associated executable. The checksum allows the debugger to verify that the source code it loads matches the executable. The compiler and debugger support MD5, SHA-1, SHA-256, SHA-384, and SHA-512 hash algorithms. +Because of a risk of collision problems in MD5 and SHA-1, use the **`/ZH:SHA_256`** option or a stronger algorithm. SHA-384 and SHA-512 provide stronger checksums, but they can increase compile time. -The **`/ZH`** option is available in Visual Studio 2019 version 16.4 and later. +> [!NOTE] +> The **`/ZH:SHA384`** and **`/ZH:SHA512`** options aren't supported for IFC (module interface) files. If you compile modules with one of these options, the compiler emits [fatal error C1029](../../error-messages/compiler-errors-1/fatal-error-c1029.md). Use **`/ZH:SHA_256`** or a smaller hash algorithm when you compile C++ modules. + +::: moniker-end + +When more than one **`/ZH`** option is specified, the last option is used. ### To set this compiler option in the Visual Studio development environment @@ -44,9 +82,20 @@ The **`/ZH`** option is available in Visual Studio 2019 version 16.4 and later. 1. Select the **Configuration Properties** > **C/C++** > **Command Line** property page. +::: moniker range=">=msvc-180" + +1. Modify the **Additional options** property to add a **`/ZH:MD5`**, **`/ZH:SHA1`**, **`/ZH:SHA_256`**, **`/ZH:SHA384`**, or **`/ZH:SHA512`** option, and then choose **OK**. + +::: moniker-end + +::: moniker range=">=msvc-160 <=msvc-170" + 1. Modify the **Additional options** property to add a **`/ZH:MD5`**, **`/ZH:SHA1`**, or **`/ZH:SHA_256`** option, and then choose **OK**. +::: moniker-end + ## See also [Compiler options](compiler-options.md)\ +[Debug Interface Access SDK - IDiaSourceFile::get_checksumType](/visualstudio/debugger/debug-interface-access/idiasourcefile-get-checksumtype)\ [Source server](/windows/win32/debug/source-server-and-source-indexing) diff --git a/docs/build/reference/zp-struct-member-alignment.md b/docs/build/reference/zp-struct-member-alignment.md index cfb89975b24..f9bd480e318 100644 --- a/docs/build/reference/zp-struct-member-alignment.md +++ b/docs/build/reference/zp-struct-member-alignment.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: /Zp (Struct Member Alignment)" title: "/Zp (Struct Member Alignment)" -ms.date: "01/08/2021" +description: "Learn more about: /Zp (Struct Member Alignment)" +ms.date: 01/08/2021 f1_keywords: ["/zp", "VC.Project.VCCLCompilerTool.StructMemberAlignment", "VC.Project.VCCLWCECompilerTool.StructMemberAlignment"] helpviewer_keywords: ["Struct Member Alignment compiler option", "Zp compiler option", "/Zp compiler option [C++]", "-Zp compiler option [C++]"] -ms.assetid: 5242f656-ed9b-48a3-bc73-cfcf3ed2520f --- # /Zp (Struct Member Alignment) diff --git a/docs/build/reference/zw-windows-runtime-compilation.md b/docs/build/reference/zw-windows-runtime-compilation.md index b93a6d5745c..b535b3e7c78 100644 --- a/docs/build/reference/zw-windows-runtime-compilation.md +++ b/docs/build/reference/zw-windows-runtime-compilation.md @@ -1,44 +1,42 @@ --- -description: "Learn more about: /ZW (Windows Runtime Compilation)" title: "/ZW (Windows Runtime Compilation)" -ms.date: "04/08/2019" +description: "Learn more about: /ZW (Windows Runtime Compilation)" +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`](eh-exception-handling-model.md) as well.\ +**`/ZW`** isn't compatible with [`/std:c++20`](std-specify-language-standard-version.md) or later. ## Syntax -```cpp +``` /ZW /EHsc /ZW:nostdlib /EHsc ``` ## 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**. - -For more information, see [Visual C++ Language Reference](../../cppcx/visual-c-language-reference-c-cx.md). +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`**. -## Requirements +For more information, see [C++/CX Language Reference](../../cppcx/visual-c-language-reference-c-cx.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/regular-dlls-statically-linked-to-mfc.md b/docs/build/regular-dlls-statically-linked-to-mfc.md index d3d90f05184..4faae4e7bb4 100644 --- a/docs/build/regular-dlls-statically-linked-to-mfc.md +++ b/docs/build/regular-dlls-statically-linked-to-mfc.md @@ -9,7 +9,7 @@ ms.assetid: 2eed531c-726a-4b8a-b936-f721dc00a7fa A regular MFC DLL statically linked to MFC is a DLL that uses MFC internally, and the exported functions in the DLL can be called by either MFC or non-MFC executables. As the name describes, this kind of DLL is built using the static link library version of MFC. Functions are usually exported from a regular MFC DLL using the standard C interface. For an example of how to write, build, and use a regular MFC DLL, see the sample [DLLScreenCap](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/advanced/DllScreenCap). -Note that the term USRDLL is no longer used in the Visual C++ documentation. A regular MFC DLL that is statically linked to MFC has the same characteristics as the former USRDLL. +Note that the term USRDLL is no longer used in the Microsoft C++ documentation. A regular MFC DLL that is statically linked to MFC has the same characteristics as the former USRDLL. A regular MFC DLL, statically linked to MFC, has the following features: diff --git a/docs/build/run-time-library-behavior.md b/docs/build/run-time-library-behavior.md index 1a85ae8d849..1b755df2623 100644 --- a/docs/build/run-time-library-behavior.md +++ b/docs/build/run-time-library-behavior.md @@ -1,31 +1,30 @@ --- -description: "Learn more about: DLLs and Visual C++ run-time library behavior" -title: "DLLs and Visual C++ run-time library behavior" -ms.date: "08/19/2019" +description: "Learn more about: DLLs and Microsoft C++ runtime library behavior" +title: "DLLs and Visual C++ runtime library behavior" +ms.date: 02/23/2026 f1_keywords: ["_DllMainCRTStartup", "CRT_INIT"] helpviewer_keywords: ["DLLs [C++], entry point function", "process detach [C++]", "process attach [C++]", "DLLs [C++], run-time library behavior", "DllMain function", "_CRT_INIT macro", "_DllMainCRTStartup method", "run-time [C++], DLL startup sequence", "DLLs [C++], startup sequence"] -ms.assetid: e06f24ab-6ca5-44ef-9857-aed0c6f049f2 --- -# DLLs and Visual C++ run-time library behavior +# DLLs and Visual C++ runtime library behavior -When you build a Dynamic-link Library (DLL) by using Visual Studio, by default, the linker includes the Visual C++ run-time library (VCRuntime). The VCRuntime contains code required to initialize and terminate a C/C++ executable. When linked into a DLL, the VCRuntime code provides an internal DLL entry-point function called `_DllMainCRTStartup` that handles Windows OS messages to the DLL to attach to or detach from a process or thread. The `_DllMainCRTStartup` function performs essential tasks such as stack buffer security set up, C run-time library (CRT) initialization and termination, and calls to constructors and destructors for static and global objects. `_DllMainCRTStartup` also calls hook functions for other libraries such as WinRT, MFC, and ATL to perform their own initialization and termination. Without this initialization, the CRT and other libraries, as well as your static variables, would be left in an uninitialized state. The same VCRuntime internal initialization and termination routines are called whether your DLL uses a statically linked CRT or a dynamically linked CRT DLL. +When you build a Dynamic-link Library (DLL) using Visual Studio, by default, the linker includes the Visual C++ runtime library (VCRuntime). The VCRuntime contains code required to initialize and terminate a C/C++ executable. When linked into a DLL, the VCRuntime code provides an internal DLL entry-point function called `_DllMainCRTStartup` that handles Windows OS messages to the DLL to attach to or detach from a process or thread. The `_DllMainCRTStartup` function performs essential tasks such as stack buffer security setup, C runtime library (CRT) initialization and termination, and calls to constructors and destructors for static and global objects. `_DllMainCRTStartup` also calls hook functions for other libraries such as WinRT, MFC, and ATL to perform their own initialization and termination. Without this initialization, the CRT and other libraries, and your static variables, would be left in an uninitialized state. The same VCRuntime internal initialization and termination routines are called whether your DLL uses a statically linked CRT or a dynamically linked CRT DLL. ## Default DLL entry point _DllMainCRTStartup -In Windows, all DLLs can contain an optional entry-point function, usually called `DllMain`, that is called for both initialization and termination. This gives you an opportunity to allocate or release additional resources as needed. Windows calls the entry-point function in four situations: process attach, process detach, thread attach, and thread detach. When a DLL is loaded into a process address space, either when an application that uses it is loaded, or when the application requests the DLL at runtime, the operating system creates a separate copy of the DLL data. This is called *process attach*. *Thread attach* occurs when the process the DLL is loaded in creates a new thread. *Thread detach* occurs when the thread terminates, and *process detach* is when the DLL is no longer required and is released by an application. The operating system makes a separate call to the DLL entry point for each of these events, passing a *reason* argument for each event type. For example, the OS sends `DLL_PROCESS_ATTACH` as the *reason* argument to signal process attach. +In Windows, all DLLs can contain an optional entry-point function, usually called `DllMain`, that is called for both initialization and termination. This gives you an opportunity to allocate or release other resources as needed. Windows calls the entry-point function in four situations: process attach, process detach, thread attach, and thread detach. When a DLL is loaded into a process address space, either when an application that uses it's loaded, or when the application requests the DLL at runtime, the operating system creates a separate copy of the DLL data. This is called *process attach*. *Thread attach* occurs when the process the DLL is loaded in creates a new thread. *Thread detach* occurs when the thread terminates, and *process detach* is when the DLL is no longer required and is released by an application. The operating system makes a separate call to the DLL entry point for each of these events, passing a *reason* argument for each event type. For example, the OS sends `DLL_PROCESS_ATTACH` as the *reason* argument to signal process attach. -The VCRuntime library provides an entry-point function called `_DllMainCRTStartup` to handle default initialization and termination operations. On process attach, the `_DllMainCRTStartup` function sets up buffer security checks, initializes the CRT and other libraries, initializes run-time type information, initializes and calls constructors for static and non-local data, initializes thread-local storage, increments an internal static counter for each attach, and then calls a user- or library-supplied `DllMain`. On process detach, the function goes through these steps in reverse. It calls `DllMain`, decrements the internal counter, calls destructors, calls CRT termination functions and registered `atexit` functions, and notifies any other libraries of termination. When the attachment counter goes to zero, the function returns `FALSE` to indicate to Windows that the DLL can be unloaded. The `_DllMainCRTStartup` function is also called during thread attach and thread detach. In these cases, the VCRuntime code does no additional initialization or termination on its own, and just calls `DllMain` to pass the message along. If `DllMain` returns `FALSE` from process attach, signaling failure, `_DllMainCRTStartup` calls `DllMain` again and passes `DLL_PROCESS_DETACH` as the *reason* argument, then goes through the rest of the termination process. +The VCRuntime library provides an entry-point function called `_DllMainCRTStartup` to handle default initialization and termination operations. On process attach, the `_DllMainCRTStartup` function sets up buffer security checks, initializes the CRT and other libraries, initializes runtime type information, initializes and calls constructors for static and nonlocal data, initializes thread-local storage, increments an internal static counter for each attach, and then calls a user- or library-supplied `DllMain`. On process detach, the function goes through these steps in reverse. It calls `DllMain`, decrements the internal counter, calls destructors, calls CRT termination functions and registered `atexit` functions, and notifies any other libraries of termination. When the attachment counter goes to zero, the function returns `FALSE` to indicate to Windows that the DLL can be unloaded. The `_DllMainCRTStartup` function is also called during thread attach and thread detach. In these cases, the VCRuntime code does no other initialization or termination on its own, and just calls `DllMain` to pass the message along. If `DllMain` returns `FALSE` from process attach, signaling failure, `_DllMainCRTStartup` calls `DllMain` again and passes `DLL_PROCESS_DETACH` as the *reason* argument, then goes through the rest of the termination process. -When building DLLs in Visual Studio, the default entry point `_DllMainCRTStartup` supplied by VCRuntime is linked in automatically. You do not need to specify an entry-point function for your DLL by using the [/ENTRY (Entry point symbol)](reference/entry-entry-point-symbol.md) linker option. +When building DLLs in Visual Studio, the default entry point `_DllMainCRTStartup` supplied by VCRuntime is linked in automatically. You don't need to specify an entry-point function for your DLL by using the [`/ENTRY` (Entry point symbol)](reference/entry-entry-point-symbol.md) linker option. > [!NOTE] -> While it is possible to specify another entry-point function for a DLL by using the /ENTRY: linker option, we do not recommend it, because your entry-point function would have to duplicate everything that `_DllMainCRTStartup` does, in the same order. The VCRuntime provides functions that allow you to duplicate its behavior. For example, you can call [__security_init_cookie](../c-runtime-library/reference/security-init-cookie.md) immediately on process attach to support the [/GS (Buffer security check)](reference/gs-buffer-security-check.md) buffer checking option. You can call the `_CRT_INIT` function, passing the same parameters as the entry point function, to perform the rest of the DLL initialization or termination functions. +> While it's possible to specify another entry-point function for a DLL by using the `/ENTRY`: linker option, we don't recommend it, because your entry-point function would have to duplicate everything that `_DllMainCRTStartup` does, in the same order. The VCRuntime provides functions that allow you to duplicate its behavior. For example, you can call [__security_init_cookie](../c-runtime-library/reference/security-init-cookie.md) immediately on process attach to support the [/GS (Buffer security check)](reference/gs-buffer-security-check.md) buffer checking option. You can call the `_CRT_INIT` function, passing the same parameters as the entry point function, to perform the rest of the DLL initialization or termination functions. ## Initialize a DLL -Your DLL may have initialization code that must execute when your DLL loads. In order for you to perform your own DLL initialization and termination functions, `_DllMainCRTStartup` calls a function called `DllMain` that you can provide. Your `DllMain` must have the signature required for a DLL entry point. The default entry point function `_DllMainCRTStartup` calls `DllMain` using the same parameters passed by Windows. By default, if you do not provide a `DllMain` function, Visual Studio provides one for you and links it in so that `_DllMainCRTStartup` always has something to call. This means that if you do not need to initialize your DLL, there is nothing special you have to do when building your DLL. +Your DLL may have initialization code that must execute when your DLL loads. In order for you to perform your own DLL initialization and termination functions, `_DllMainCRTStartup` calls a function called `DllMain` that you can provide. Your `DllMain` must have the signature required for a DLL entry point. The default entry point function `_DllMainCRTStartup` calls `DllMain` using the same parameters passed by Windows. By default, if you don't provide a `DllMain` function, Visual Studio provides one for you and links it in so that `_DllMainCRTStartup` always has something to call. This means that if you don't need to initialize your DLL, there's nothing special you have to do when building your DLL. This is the signature used for `DllMain`: @@ -38,10 +37,10 @@ extern "C" BOOL WINAPI DllMain ( LPVOID const reserved); // reserved ``` -Some libraries wrap the `DllMain` function for you. For example, in a regular MFC DLL, implement the `CWinApp` object's `InitInstance` and `ExitInstance` member functions to perform initialization and termination required by your DLL. For more details, see the [Initialize regular MFC DLLs](#initializing-regular-dlls) section. +Some libraries wrap the `DllMain` function for you. For example, in a regular MFC DLL, implement the `CWinApp` object's `InitInstance` and `ExitInstance` member functions to perform initialization and termination required by your DLL. For more information, see the [Initialize regular MFC DLLs](#initializing-regular-dlls) section. > [!WARNING] -> There are significant limits on what you can safely do in a DLL entry point. For more information about specific Windows APIs that are unsafe to call in `DllMain`, see [General Best Practices](/windows/win32/Dlls/dynamic-link-library-best-practices). If you need anything but the simplest initialization then do that in an initialization function for the DLL. You can require applications to call the initialization function after `DllMain` has run and before they call any other functions in the DLL. +> There are significant limits on what you can safely do in a DLL entry point. For more information about specific Windows APIs that are unsafe to call in `DllMain`, see [General Best Practices](/windows/win32/Dlls/dynamic-link-library-best-practices). If you need anything but the simplest initialization, then do that in an initialization function for the DLL. You can require applications to call the initialization function after `DllMain` has run and before they call any other functions in the DLL. @@ -82,17 +81,64 @@ extern "C" BOOL WINAPI DllMain ( ``` > [!NOTE] -> Older Windows SDK documentation says that the actual name of the DLL entry-point function must be specified on the linker command-line with the /ENTRY option. With Visual Studio, you do not need to use the /ENTRY option if the name of your entry-point function is `DllMain`. In fact, if you use the /ENTRY option and name your entry-point function something other than `DllMain`, the CRT does not get initialized properly unless your entry-point function makes the same initialization calls that `_DllMainCRTStartup` makes. +> Older Windows SDK documentation says that the actual name of the DLL entry-point function must be specified on the linker command-line with the `/ENTRY` option. With Visual Studio, you don't need to use the `/ENTRY` option if the name of your entry-point function is `DllMain`. In fact, if you use the `/ENTRY` option and name your entry-point function something other than `DllMain`, the CRT doesn't get initialized properly unless your entry-point function makes the same initialization calls that `_DllMainCRTStartup` makes. + +### Manual CRT initialization with `_CRT_INIT` + +When building a DLL that uses any of the C runtime libraries, in order to ensure that the CRT is properly initialized, either: + +- The initialization function must be named `DllMain()` and the entry point must be specified with the linker option `-entry:_DllMainCRTStartup@12` This is the default behavior when building a DLL (the `@12` is x86-only because that platform uses `stdcall`), or +- The DLL's entry point must explicitly call `_CRT_INIT()` on process attach and process detach. This is only relevant if you are using `/NOENTRY` or have a custom entry point. We don't recommend using `/NOENTRY` or a custom entry point, if possible, because you would have to duplicate all of the initialization and termination code that `_DllMainCRTStartup` provides, in the same order. + +This permits the C runtime libraries to properly allocate and initialize C runtime data when a process or thread is attaching to the DLL, to properly clean up C runtime data when a process is detaching from the DLL, and for global C++ objects in the DLL to be properly constructed and destructed. + +The Win32 SDK samples all use the first method. Refer to the Win32 Programmer's Reference for `DllEntryPoint()` and the Visual C++ documentation for `DllMain()`. `DllMainCRTStartup()` calls `_CRT_INIT()` and `_CRT_INIT()` calls your application's `DllMain()`, if it exists. + +If you wish to use the second method and call the CRT initialization code yourself, instead of using `DllMainCRTStartup()` and `DllMain()`, there are two techniques: + +1. If you do have your own DLL entry point, do the following in the entry point: + + a. Use this prototype (defined in `process.h` when `_DECL_DLLMAIN` is defined) for `_CRT_INIT()`: `BOOL WINAPI _CRT_INIT(HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpReserved);` + + For information on `_CRT_INIT()` return values, see the documentation for `DllEntryPoint`; the same values are returned. + + b. On `DLL_PROCESS_ATTACH` and `DLL_THREAD_ATTACH`, call `_CRT_INIT()` first, before any C runtime functions are called or any floating-point operations are performed. + + c. Call your own process/thread initialization/termination code. + + d. On `DLL_PROCESS_DETACH` and `DLL_THREAD_DETACH`, call `_CRT_INIT()` last, after all C runtime functions have been called and all floating-point operations are completed. + +Be sure to pass on to `_CRT_INIT()` all of the parameters of the entry point; `_CRT_INIT()` expects those parameters, so things may not work reliably if they're omitted (in particular, `fdwReason` is required to determine whether process initialization or termination is needed). + +Below is a skeleton sample entry point function that shows when and how to make these calls to `_CRT_INIT()` in the DLL entry point: + +```cpp +BOOL WINAPI DllEntryPoint(HINSTANCE hinstDLL, DWORD fdwReason, LPVOID lpReserved) +{ + if (fdwReason == DLL_PROCESS_ATTACH || fdwReason == DLL_THREAD_ATTACH) + if (!_CRT_INIT(hinstDLL, fdwReason, lpReserved)) + return(FALSE); + + if (fdwReason == DLL_PROCESS_DETACH || fdwReason == DLL_THREAD_DETACH) + if (!_CRT_INIT(hinstDLL, fdwReason, lpReserved)) + return(FALSE); + + return(TRUE); +} +``` + +> [!NOTE] +> This isn't necessary if you're using `DllMain()` and `-entry:_DllMainCRTStartup@12`. ### Initialize regular MFC DLLs -Because regular MFC DLLs have a `CWinApp` object, they should perform their initialization and termination tasks in the same location as an MFC application: in the `InitInstance` and `ExitInstance` member functions of the DLL's `CWinApp`-derived class. Because MFC provides a `DllMain` function that is called by `_DllMainCRTStartup` for `DLL_PROCESS_ATTACH` and `DLL_PROCESS_DETACH`, you should not write your own `DllMain` function. The MFC-provided `DllMain` function calls `InitInstance` when your DLL is loaded and it calls `ExitInstance` before the DLL is unloaded. +Because regular MFC DLLs have a `CWinApp` object, they should perform their initialization and termination tasks in the same location as an MFC application: in the `InitInstance` and `ExitInstance` member functions of the DLL's `CWinApp`-derived class. Because MFC provides a `DllMain` function that is called by `_DllMainCRTStartup` for `DLL_PROCESS_ATTACH` and `DLL_PROCESS_DETACH`, you shouldn't write your own `DllMain` function. The MFC-provided `DllMain` function calls `InitInstance` when your DLL is loaded and it calls `ExitInstance` before the DLL is unloaded. A regular MFC DLL can keep track of multiple threads by calling [TlsAlloc](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsalloc) and [TlsGetValue](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsgetvalue) in its `InitInstance` function. These functions allow the DLL to track thread-specific data. -In your regular MFC DLL that dynamically links to MFC, if you are using any MFC OLE, MFC Database (or DAO), or MFC Sockets support, respectively, the debug MFC extension DLLs MFCO*version*D.dll, MFCD*version*D.dll, and MFCN*version*D.dll (where *version* is the version number) are linked in automatically. You must call one of the following predefined initialization functions for each of these DLLs that you are using in your regular MFC DLL's `CWinApp::InitInstance`. +In your regular MFC DLL that dynamically links to MFC, if you're using any MFC OLE, MFC Database (or DAO), or MFC Sockets support, respectively, the debug MFC extension DLLs MFCO*version*D.dll, MFCD*version*D.dll, and MFCN*version*D.dll (where *version* is the version number) are linked in automatically. You must call one of the following predefined initialization functions for each of these DLLs that you're using in your regular MFC DLL's `CWinApp::InitInstance`. |Type of MFC support|Initialization function to call| |-------------------------|-------------------------------------| @@ -104,7 +150,7 @@ In your regular MFC DLL that dynamically links to MFC, if you are using any MFC ### Initialize MFC extension DLLs -Because MFC extension DLLs do not have a `CWinApp`-derived object (as do regular MFC DLLs), you should add your initialization and termination code to the `DllMain` function that the MFC DLL Wizard generates. +Because MFC extension DLLs don't have a `CWinApp`-derived object (as do regular MFC DLLs), you should add your initialization and termination code to the `DllMain` function that the MFC DLL Wizard generates. The wizard provides the following code for MFC extension DLLs. In the code, `PROJNAME` is a placeholder for the name of your project. @@ -143,27 +189,27 @@ DllMain(HINSTANCE hInstance, DWORD dwReason, LPVOID lpReserved) Creating a new `CDynLinkLibrary` object during initialization allows the MFC extension DLL to export `CRuntimeClass` objects or resources to the client application. -If you are going to use your MFC extension DLL from one or more regular MFC DLLs, you must export an initialization function that creates a `CDynLinkLibrary` object. That function must be called from each of the regular MFC DLLs that use the MFC extension DLL. An appropriate place to call this initialization function is in the `InitInstance` member function of the regular MFC DLL's `CWinApp`-derived object before using any of the MFC extension DLL's exported classes or functions. +If you're going to use your MFC extension DLL from one or more regular MFC DLLs, you must export an initialization function that creates a `CDynLinkLibrary` object. That function must be called from each of the regular MFC DLLs that use the MFC extension DLL. An appropriate place to call this initialization function is in the `InitInstance` member function of the regular MFC DLL's `CWinApp`-derived object before using any of the MFC extension DLL's exported classes or functions. -In the `DllMain` that the MFC DLL Wizard generates, the call to `AfxInitExtensionModule` captures the module's run-time classes (`CRuntimeClass` structures) as well as its object factories (`COleObjectFactory` objects) for use when the `CDynLinkLibrary` object is created. You should check the return value of `AfxInitExtensionModule`; if a zero value is returned from `AfxInitExtensionModule`, return zero from your `DllMain` function. +In the `DllMain` that the MFC DLL Wizard generates, the call to `AfxInitExtensionModule` captures the module's runtime classes (`CRuntimeClass` structures) and its object factories (`COleObjectFactory` objects) for use when the `CDynLinkLibrary` object is created. You should check the return value of `AfxInitExtensionModule`; if a zero value is returned from `AfxInitExtensionModule`, return zero from your `DllMain` function. -If your MFC extension DLL will be explicitly linked to an executable (meaning the executable calls `AfxLoadLibrary` to link to the DLL), you should add a call to `AfxTermExtensionModule` on `DLL_PROCESS_DETACH`. This function allows MFC to clean up the MFC extension DLL when each process detaches from the MFC extension DLL (which happens when the process exits or when the DLL is unloaded as a result of a `AfxFreeLibrary` call). If your MFC extension DLL will be linked implicitly to the application, the call to `AfxTermExtensionModule` is not necessary. +If your MFC extension DLL is explicitly linked to an executable (meaning the executable calls `AfxLoadLibrary` to link to the DLL), you should add a call to `AfxTermExtensionModule` on `DLL_PROCESS_DETACH`. This function allows MFC to clean up the MFC extension DLL when each process detaches from the MFC extension DLL (which happens when the process exits or when the DLL is unloaded as a result of a `AfxFreeLibrary` call). If your MFC extension DLL is linked implicitly to the application, the call to `AfxTermExtensionModule` isn't necessary. -Applications that explicitly link to MFC extension DLLs must call `AfxTermExtensionModule` when freeing the DLL. They should also use `AfxLoadLibrary` and `AfxFreeLibrary` (instead of the Win32 functions `LoadLibrary` and `FreeLibrary`) if the application uses multiple threads. Using `AfxLoadLibrary` and `AfxFreeLibrary` ensures that the startup and shutdown code that executes when the MFC extension DLL is loaded and unloaded does not corrupt the global MFC state. +Applications that explicitly link to MFC extension DLLs must call `AfxTermExtensionModule` when freeing the DLL. They should also use `AfxLoadLibrary` and `AfxFreeLibrary` (instead of the Win32 functions `LoadLibrary` and `FreeLibrary`) if the application uses multiple threads. Using `AfxLoadLibrary` and `AfxFreeLibrary` ensures that the startup and shutdown code that executes when the MFC extension DLL is loaded and unloaded doesn't corrupt the global MFC state. Because the MFCx0.dll is fully initialized by the time `DllMain` is called, you can allocate memory and call MFC functions within `DllMain` (unlike the 16-bit version of MFC). -Extension DLLs can take care of multithreading by handling the `DLL_THREAD_ATTACH` and `DLL_THREAD_DETACH` cases in the `DllMain` function. These cases are passed to `DllMain` when threads attach and detach from the DLL. Calling [TlsAlloc](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsalloc) when a DLL is attaching allows the DLL to maintain thread local storage (TLS) indexes for every thread attached to the DLL. +Extension DLLs can take care of multithreading by handling the `DLL_THREAD_ATTACH` and `DLL_THREAD_DETACH` cases in the `DllMain` function. These cases are passed to `DllMain` when threads attach and detach from the DLL. Calling [`TlsAlloc`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-tlsalloc) when a DLL is attaching allows the DLL to maintain thread local storage (TLS) indexes for every thread attached to the DLL. -Note that the header file Afxdllx.h contains special definitions for structures used in MFC extension DLLs, such as the definition for `AFX_EXTENSION_MODULE` and `CDynLinkLibrary`. You should include this header file in your MFC extension DLL. +The header file `Afxdllx.h` contains special definitions for structures used in MFC extension DLLs, such as the definition for `AFX_EXTENSION_MODULE` and `CDynLinkLibrary`. You should include this header file in your MFC extension DLL. > [!NOTE] -> It is important that you neither define nor undefine any of the `_AFX_NO_XXX` macros in *pch.h* (*stdafx.h* in Visual Studio 2017 and earlier). These macros exist only for the purpose of checking whether a particular target platform supports that feature or not. You can write your program to check these macros (for example, `#ifndef _AFX_NO_OLE_SUPPORT`), but your program should never define or undefine these macros. +> It's important that you don't define or undefine any of the `_AFX_NO_XXX` macros in `pch.h` (`stdafx.h` in Visual Studio 2017 and earlier). These macros exist only to check whether a particular target platform supports that feature or not. You can write your program to check these macros (for example, `#ifndef _AFX_NO_OLE_SUPPORT`), but your program should never define or undefine these macros. -A sample initialization function that handles multithreading is included in [Using Thread Local Storage in a Dynamic-Link Library](/windows/win32/Dlls/using-thread-local-storage-in-a-dynamic-link-library) in the Windows SDK. Note that the sample contains an entry-point function called `LibMain`, but you should name this function `DllMain` so that it works with the MFC and C run-time libraries. +A sample initialization function that handles multithreading is included in [Using Thread Local Storage in a Dynamic-Link Library](/windows/win32/Dlls/using-thread-local-storage-in-a-dynamic-link-library) in the Windows SDK. Note that the sample contains an entry-point function called `LibMain`, but you should name this function `DllMain` so that it works with the MFC and C runtime libraries. ## See also -[Create C/C++ DLLs in Visual Studio](dlls-in-visual-cpp.md)
-[DllMain entry point](/windows/win32/Dlls/dllmain)
+[Create C/C++ DLLs in Visual Studio](dlls-in-visual-cpp.md)\ +[DllMain entry point](/windows/win32/Dlls/dllmain)\ [Dynamic-link Library Best Practices](/windows/win32/Dlls/dynamic-link-library-best-practices) diff --git a/docs/build/sample-profile-guided-optimization.md b/docs/build/sample-profile-guided-optimization.md new file mode 100644 index 00000000000..9a9b7babe60 --- /dev/null +++ b/docs/build/sample-profile-guided-optimization.md @@ -0,0 +1,715 @@ +--- +description: "Learn how to use Sample Profile-Guided Optimization (SPGO) to improve the performance of C and C++ applications." +title: "Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve C++ performance" +ms.date: 05/20/2026 +ms.topic: tutorial +ai-usage: ai-assisted +helpviewer_keywords: ["SPGO", "sample profile-guided optimization", "profiling, SPGO", "SPDConvert", "SPTAggregate"] +--- +# Use Sample Profile Guided Optimization (SPGO) to improve C++ performance + +Profile-Guided Optimization (PGO) uses runtime data to help the compiler make better optimization decisions. By using execution profile data collected from representative workloads, PGO enables the compiler to make smarter decisions about inlining, code layout, and hot/cold code separation. These decisions are impossible to make from static analysis alone. + +SPGO takes a different approach. Instead of instrumenting your binary and running it through synthetic training scenarios, SPGO uses hardware performance counter sampling collected from your actual release binaries. Modern processors provide hardware sampling capabilities. You can collect these samples with negligible runtime overhead, making it practical to gather runtime profiles directly from production code. + +Because SPGO profiles release bits instead of instrumented builds, it enables much more flexibility in where and how you collect data. You can gather runtime profiles from production servers, developer machines, performance labs, or any combination. The result is a binary that runs hot paths more efficiently, with a typical performance speedup of 5-15% depending on the quality of the profile data. + +For more information about Sample Profile‑Guided Optimization (PGO) in MSVC and how it improves performance using sampling‑based profiling, see [Introducing Sample Profile Guided Optimization in MSVC](https://devblogs.microsoft.com/cppblog/introducing-sample-profile-guided-optimization-in-msvc/) + +In this tutorial, you walk through the complete SPGO workflow: build a sample app, profile it by using `xperf`, prepare the profile data, and rebuild with the profile data. When you finish, you can apply the same process to your own projects. + +## Prerequisites + +Before you start, make sure you have the following software and hardware. + +### Software + +- **MSVC build tools for x64/x86/ARM64 v14.51 or later**—Install them through the Visual Studio Installer. Under **Individual Components**, search for "MSVC build tools." +- **Windows Performance Toolkit (xperf.exe)**—The `xperf` profiler collects sample data during your program's execution. Download the Windows Assessment and Deployment Kit (ADK) from [ADK install](/windows-hardware/get-started/adk-install). When you run the ADK installer, select the **Windows Performance Toolkit** component to get `xperf`. You don't need to install the full ADK. +- **War and Peace text file**—Used as the sample workload to generate profiling data. Download it from Project Gutenberg: [https://www.gutenberg.org/ebooks/2600](https://www.gutenberg.org/ebooks/2600). Save it as a plain text file in your working directory. + +### Hardware requirements + +The tutorial has three profiling paths. Which path you use depends on your hardware. You run detection commands in [Choose your profiling method](#choose-your-profiling-method) to find out which path your machine supports. For now, use this table to confirm you meet at least one of the requirements. + +| Path | CPU requirement | Notes | +|------|----------------|-------| +| **LBR** (best results) | Last Branch Records (LBR) are performance counters provided on Intel Haswell CPUs (4th gen Core, 2013) or later; AMD Zen 4 (2022) or later, ARM64 ARMv9.2-A (2020) or later | Provides the best branch data. For more information about LBR, see [An introduction to last branch records](https://lwn.net/Articles/680985/) | +| **PMC/IP mode** (good results) | Performance Monitoring Counters (PMC) are supported on any x64 CPU with a performance monitoring unit (PMU) | Works on most modern CPUs where LBR is unavailable. For more information about PMC, see [Recording Hardware Performance (PMU) Events](/windows-hardware/test/wpt/recording-pmu-events) and [Recording Hardware Performance (PMU) Events with Complete Examples](https://devblogs.microsoft.com/performance-diagnostics/recording-hardware-performance-pmu-events-with-complete-examples/#configuring-extended-pmu-counter-configurations5) | +| **OS timer** (works everywhere) | Any x64 or ARM64 CPU, including Azure VMs and virtual machines | Lower-fidelity samples, but always available | + +Most developers on modern x64 desktop hardware have LBR support. VMs and some older hardware have PMC or an OS timer. + +## How SPGO works + +SPGO collects profile data from your running binary and feeds it back to the compiler when you next build. The compiler uses that data to make better decisions about inlining, code layout, and branch prediction. A convenience is that no instrumentation is required. + +The workflow is: + +1. Build your binary with the [/spgo](./reference/spgo-enable-sample-profile-guided-optimization.md) linker flag. This step creates an empty **sample profile database** (`.spd` file). +1. Profile the binary by using `xperf` to produce an ETL trace file. +1. Convert the ETL to an **SPT** file by using [`SPTAggregate.exe`](sptaggregate.md), then convert the SPT to an **SPD** file by using [`SPDConvert.exe`](spdconvert.md). +1. Rebuild with the [/spdin](./reference/spdin-use-sample-profile-database.md) linker flag pointing to the populated sample profile database (SPD). The linker applies SPGO optimizations. + +The optimizer uses the SPD to answer questions like: which branches are taken most often? Which functions are called in hot loops? This process produces better code layout and inlining decisions than static analysis alone. + +SPGO works with both C and C++. The workflow and flags are identical for both languages. + +**Best candidates for SPGO:** Large, branch-filled C/C++ applications with tight inner loops. Gains scale with codebase size and branch complexity. The small sample in this tutorial shows around 7% improvement. Larger production codebases often see more improvement. + +## Build Process Comparison + +This section covers how SPGO fits into the build pipeline if you want to understand the mechanics. + +### Normal build process + +In a standard C/C++ release build: + +- **Inputs:** Source code files (`.cpp`, `.h`) and release-mode compiler flags (`/O2`, `/GL`, and so on). +- **Process:** The compiler applies standard optimizations such as inlining heuristics, branch prediction assumptions, and code layout decisions based on static analysis alone. It has no data about how the program actually behaves when it runs. +- **Output:** Executable (`.exe`), DLL files (`.dll`), debug information (`.pdb`). + +:::image type="content" source="media/normal-build-process.png" alt-text="Diagram of the normal release build process showing source code files and example compiler switch /GL as inputs flowing to a build step, which produces .exe, .dll, and .pdb outputs." lightbox="media/normal-build-process.png"::: + +Without runtime data, hot paths and cold paths receive similar treatment. + +### SPGO-enabled build process + +SPGO adds profiling data as a new input to the build pipeline: + +- **Inputs:** Source code, the `.spd` profile file (sample counts from a profiling run), release-mode compiler flags, `/link /spgo`, and `/spdin:` to specify an input SPD file (if not specified, defaults to a .spd using the binary name and located in the obj folder). +- **Process:** The linker reads the SPD alongside the intermediate code. It uses branch-frequency data to make better inlining, code layout, and branch-ordering decisions. Hot functions get laid out for fast access; cold code moves out of the critical path. +- **Output:** Optimized executable (`.exe`), optimized DLL files (`.dll`), debug information (`.pdb`), **and a new `.spd` file** for future profiling iterations. + +:::image type="content" source="media/sample-profile-guided-optimization-build-process.png" alt-text="Diagram of the SPGO-enabled build process showing source code and profile data files (.spd) as inputs to the build step with an additional linker switch /spgo. The build process outputs optimized .exe, .dll, debug information (.pdb), and new profile data files (.spd)." lightbox="media/sample-profile-guided-optimization-build-process.png"::: + +The key insight: SPGO moves optimization decisions from compiler and linker heuristics to data-driven choices based on real execution. + +### Key flags + +| Flag | Type | Purpose | +|------|------|---------| +| [`/spgo`](./reference/spgo-enable-sample-profile-guided-optimization.md) | Linker | Enables SPGO. Embeds SPGO metadata in the binary and creates an empty `.spd` output file unless `/spdin` is specified, in which case the specified `.spd` file is used as input. | +| [`/spdin:`](./reference/spdin-use-sample-profile-database.md) | Linker | Input SPD - provides profile data to the linker for optimization | +| [`/spd:`](./reference/spd-specify-sample-profile-database.md) | Linker | Output SPD path - specifies where the new SPD is written (optional; defaults to the same directory as the binary). Serves as the input SPD path if `/spdin` isn't specified. | +| [`/GL`](./reference/gl-whole-program-optimization.md) | Compiler | Whole-program optimization-required for SPGO to work across translation units | +| [`/O1`, `/O2` (Minimize Size, Maximize Speed)](./reference/o1-o2-minimize-size-maximize-speed.md) | Compiler | Optimize for speed; enables aggressive optimizations that SPGO can enhance | + +### How SPGO differs from PGO + +PGO (Profile-Guided Optimization) requires you to compile your binary with instrumentation flags (`/GENPROFILE`), run the slower instrumented binary to collect `.pgc` execution count files, then relink with `/USEPROFILE`. The compiler gets exact execution counts but you have to instrument the code first. For more information about this process, see [Profile-guided optimizations](profile-guided-optimizations.md). + +SPGO uses hardware CPU performance counters to collect statistical samples from your uninstrumented release binary. Run your existing binary, profile it by using `xperf`, convert the trace to an SPD file, and rebuild. There's no instrumented build and no slowdown during profiling. The compiler gets statistical sampling data instead of exact counts, which is less precise but easier to get and requires no code changes. It also allows profiling of system components or realtime components that are difficult to collect data for with an instrumented approach. You can also profile final/shipping binaries. + +This tutorial covers three profiling methods: LBR, PMC, and OS timer. You choose your method in [Choose your profiling method](#choose-your-profiling-method). For a detailed comparison of the normal build process versus the SPGO build process, including a flag reference table, see [Build Process Comparison](#build-process-comparison). + +## Configure `perfcore.ini` + +> **⚠️ Required:** Without this step, `xperf` doesn't provide the necessary profiling data. Complete this step before running `xperf`. + +The Windows Performance Toolkit (WPT) uses `perfcore.ini`, located if you installed the WPT in the default location at `C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\perfcore.ini`, to register the DLL providers it needs for SPGO. + +Open Windows Notepad as Administrator. Then open `perfcore.ini`. Find the DLL list section and add the following entries, one per line: + +``` +perf_lbr.dll +perf_spt.dll +perf_hv.dll +``` + +If `xperf.exe` isn't installed, see [General issues](#general-issues-all-paths) to install it. + +Save and close `perfcore.ini`. The DLL files already ship in the same directory as `xperf.exe` so you don't need to copy them anywhere. You're only registering them in `perfcore.ini`. Ensure that `xperf` is in your path. + +## Create the sample app + +The sample app for this tutorial is a C++ program that reads text from standard input and produces a line count, word count, total character count, a character frequency table, and elapsed time to process the file in milliseconds. It's written in C++, but SPGO also works with C. The workflow is identical for C projects. + +Create a file named `textCount.cpp` in your working directory and add the following source code: + +```cpp +// textCount.cpp : Text Statistics Counter +// Counts words, lines, and character frequencies from standard input +// Usage: textCount < file.txt + +#include +#include +#include +#include +#include + +int main() +{ + auto start = std::chrono::steady_clock::now(); + + std::map charFrequency; + int wordCount = 0; + int lineCount = 0; + int totalChars = 0; + + std::string line; + bool inWord = false; + + while (std::getline(std::cin, line)) + { + lineCount++; + + for (char c : line) + { + totalChars++; + unsigned char uc = static_cast(c); + charFrequency[uc]++; + + if (std::isspace(static_cast(c))) + { + inWord = false; + } + else + { + if (!inWord) + { + wordCount++; + inWord = true; + } + } + } + + inWord = false; + } + + std::cout << "\n=== TEXT STATISTICS ===" << std::endl; + std::cout << "Lines: " << lineCount << std::endl; + std::cout << "Words: " << wordCount << std::endl; + std::cout << "Total Characters: " << totalChars << std::endl; + + std::cout << "\n=== CHARACTER FREQUENCIES ===" << std::endl; + + std::cout << "\nLetters:" << std::endl; + for (unsigned char ch = 'a'; ch <= 'z'; ch++) + { + unsigned char upperCh = static_cast(std::toupper(ch)); + int count = charFrequency[ch] + charFrequency[upperCh]; + if (count > 0) + { + std::cout << static_cast(ch) << ": " << count << std::endl; + } + } + + std::cout << "\nDigits:" << std::endl; + for (unsigned char ch = '0'; ch <= '9'; ch++) + { + if (charFrequency[ch] > 0) + { + std::cout << static_cast(ch) << ": " << charFrequency[ch] << std::endl; + } + } + + std::cout << "\nSpecial Characters:" << std::endl; + for (const auto& pair : charFrequency) + { + unsigned char ch = pair.first; + if (!std::isalnum(ch)) + { + std::string displayChar; + switch (ch) + { + case ' ': displayChar = "[space]"; break; + case '\t': displayChar = "[tab]"; break; + case '\n': displayChar = "[newline]"; break; + case '\r': displayChar = "[return]"; break; + default: + if (ch >= 32 && ch < 127) + { + displayChar = std::string(1, static_cast(ch)); + } + else + { + displayChar = "[byte:" + std::to_string(static_cast(ch)) + "]"; + } + break; + } + std::cout << displayChar << ": " << pair.second << std::endl; + } + } + + auto end = std::chrono::steady_clock::now(); + + auto elapsed = std::chrono::duration(end - start); + std::cout << "Elapsed time: " << std::fixed; + std::cout.precision(3); + std::cout << elapsed.count() << " ms\n"; + + return 0; +} +``` + +## Build and run the sample to get a baseline + +Before applying SPGO, build `textCount` and run it against a large text file, such as *War and Peace* (you can download it from Project Gutenberg), to see how fast it runs. This step shows you the performance before you optimize it by using SPGO: + +**Build:** + +```cmd +cl /Zi /EHsc /GL /O2 textCount.cpp /link /debug +``` + +**Run:** + +```cmd +textCount.exe < warAndPeace.txt +``` + +You see output similar to: + +``` +=== TEXT STATISTICS === +Lines: 66041 +Words: 566333 +Total Characters: 3227531 + +=== CHARACTER FREQUENCIES === + +Letters: +a: 202719 +... + +Elapsed time: 512.000 ms +``` + +Record the `Elapsed time` value. You'll compare it to the SPGO-optimized time in [Measure the results](#measure-the-results). + +## Build textCount with /spgo + +Now build textCount with SPGO enabled. This step lays the groundwork to gather profiling data. + +```cmd +cl /Zi /EHsc /GL /O2 textCount.cpp /link /debug /spgo +``` + +When the build finishes, you see a message like: + +``` +SPD textCount.spd not found, compiling without profile guided optimizations +``` + +This message appears on the first `/spgo` build. The linker creates the SPD file but it's still empty, so it doesn't apply any SPGO optimizations yet. After you run the binary, collect profile data, and convert it to SPD, you won't see this message. + +**Flag explanations:** + +| Flag | Purpose | +|------|---------| +| `/Zi` | Generate complete debugging information. This is necessary for SPGO to map profiling samples to source code. | +| `/EHsc` | Enable C++ exception handling | +| `/GL` | Whole-program optimization — required for SPGO. Defers final optimization to link time, enabling cross-module inlining, code layout, and dead code elimination decisions. | +| `/O2` | Optimize for speed — enables aggressive inlining, loop optimization, dead code removal, and related transforms. | +| `/link /debug` | Pass `/debug` to the linker to generate debug information (`.pdb`), which xperf uses to map profiling samples to source code. | +| `/spgo` | SPGO linker flag—embeds SPGO metadata in the binary and creates an empty `textCount.spd` file alongside the executable. | + +> [!NOTE] +> `/spgo` is a linker flag. Pass it to the linker via `/link /spgo` in the `cl` command. + +The `/spgo` flag doesn't optimize the binary yet. It prepares it for profiling. The optimization happens in [Rebuild textCount with /spdin](#rebuild-textcount-with-spdin) after the SPD is populated with real runtime data. + +> [!NOTE] +> To write the SPD to a specific location, add the optional `/spd:` linker flag. For example: `/link /debug /spgo /spd:.\profiles\textCount.spd`. If you omit this flag, the SPD is created alongside the `.exe`. + +## Choose your profiling method + +SPGO supports three profiling methods. Which method you use depends on your hardware. + +### The three profiling methods + +| Method | Sample quality | Hardware requirement | Best for | +|--------|----------------|---------------------|----------| +| **LBR** (Last Branch Record) | Highest—records sequences of recently taken branches, giving the optimizer rich control-flow data per sample | Intel Haswell (2013) or later; AMD Zen 4 (2022) or later; ARM64 ARMv9.2-A (2020) or later | Most modern desktop hardware | +| **PMC / IP mode** (Performance Monitoring Counter/Instruction pointer mode) | Good. Captures instruction-pointer samples with call stacks using the CPU's Performance Monitoring Unit (PMU), collected through Event Tracing for Windows (ETW) | Any x64 or ARM64 CPU with a PMU | Hardware without LBR support | +| **OS timer** | Basic—timer-based samples | Any x64 or ARM64 CPU, VMs without PMU passthrough | VMs and older hardware | + +With PMC / IP mode, each hardware interrupt gives you just one data point: "the CPU was at address 0x1A2B3C4D when the interrupt fired". With LBR, each interrupt gives you a stack of the last 16–32 branches the CPU took before the interrupt fired. The optimizer gets better control-flow data and can make better inlining and layout decisions. + +### Detect your path + +Run the following two commands to determine which profiling path your machine supports. These commands don't require an elevated prompt. + +**Step 1: Check for LBR support. This test works on Intel/AMD/ARM64.** + +Run the following from an **administrator** Visual Studio developer command prompt: + +```cmd +xperf.exe -on PMC_PROFILE -pmcprofile TotalIssues -LastBranch PmcInterrupt -setProfInt TotalIssues 2560000 +xperf -stop -d lbrtest.etl +xperf -tle -i lbrtest.etl -a dumper | findstr "LBR, TimeStamp" +``` + +- If this command finds a line containing `LBR, TimeStamp`, then your machine supports LBR. **Use the LBR path.** +- Otherwise, continue to Step 2. + +**Step 2: Check for PMC support (no LBR)** + +```cmd +xperf.exe -pmcsources | findstr TotalIssues +``` + +- If this command produces output, then your machine supports PMC counters but not LBR. **Use the PMC path.** +- If this command produces no output, then **Use the OS timer path.** + +For more information about PMU event collection with xperf, see [Recording hardware PMU events with xperf](https://devblogs.microsoft.com/performance-diagnostics/recording-hardware-performance-pmu-events-with-complete-examples/#configuring-extended-pmu-counter-configurations5). + +### Decision table + +| `LBR, TimeStamp` output | `TotalIssues` output | Your path | +|---------------------|-----------------------------|-----------| +| Not empty | (not checked) | LBR | +| Empty | Not empty | PMC | +| Empty | Empty | OS timer | +| ARM64 processor | N/A | PMC (if PMU available) or OS timer | + +### Choose your approach + +Decide whether to use the LBR, PMC, or OS timer path based on the detection results. Each path has different `xperf` start parameters to collect the appropriate profiling data. Follow the path that matches your hardware capabilities. + +> **Your path:** +> - **LBR users** (LBR detected in Step 1): Go to [LBR path](#lbr-path). +> - **PMC users** (InstructionRetired detected in Step 2): Go to [PMC path (no LBR)](#pmc-path-no-lbr). +> - **OS timer users** (VM or hardware without PMU): Go to [OS timer path](#os-timer-path). +> +> All paths rejoin at [Run the workload and stop xperf](#run-the-workload-and-stop-xperf-all-paths). + +The commands in this section depend on the profiling path you identified in [Choose your profiling method](#choose-your-profiling-method). Find the subsection that matches your path, run the `xperf` start command, and then continue to [Run the workload and stop xperf](#run-the-workload-and-stop-xperf-all-paths) to run the workload and stop xperf. + +> **⚠️ Run as Administrator:** `xperf` requires an elevated (Administrator) developer command prompt. Without elevation, `xperf` returns `"failed to configure counters"`. + +### LBR path + +Start `xperf` with LBR collection: + +```cmd +xperf -on LOADER+PROC_THREAD+PMC_PROFILE -MinBuffers 4096 -MaxBuffers 4096 -BufferSize 4096 -pmcprofile BranchInstructionRetired -LastBranch PmcInterrupt -setProfInt BranchInstructionRetired 16384 +``` + +**Parameter explanation:** + +| Parameter | Purpose | +|-----------|---------| +| `LOADER+PROC_THREAD+PMC_PROFILE` | Kernel providers: loader events (module mapping), process/thread events (execution context), and PMC profiling events | +| `-MinBuffers 4096 -MaxBuffers 4096 -BufferSize 4096` | Large ring buffers to avoid dropped samples during a full War and Peace run | +| `-pmcprofile BranchInstructionRetired` | PMC event trigger: generate a sample on every Nth retired branch instruction | +| `-LastBranch PmcInterrupt` | Enables LBR hardware recording: on each PMC interrupt, capture the hardware last-branch record stack | +| `-setProfInt BranchInstructionRetired 16384` | Sample interval: fire an interrupt every 16,384 retired branch instructions | + +After starting xperf, continue to [Run the workload and stop xperf](#run-the-workload-and-stop-xperf-all-paths). + +### PMC path (no LBR) + +Start `xperf` with PMC / IP-mode collection: + +```cmd +xperf -on LOADER+PROC_THREAD+PMC_PROFILE+PROFILE -MinBuffers 4096 -BufferSize 4096 -pmcprofile InstructionRetired -setProfInt InstructionRetired 16384 -stackwalk profile +``` + +**Parameter explanation:** + +| Parameter | Purpose | +|-----------|---------| +| `LOADER+PROC_THREAD+PMC_PROFILE+PROFILE` | Adds `PROFILE` (CPU sampling) and `PMC_PROFILE` for PMC events; no `-LastBranch` | +| `-pmcprofile InstructionRetired` | PMC event trigger: sample on retired instructions (instruction pointer mode) | +| `-setProfInt InstructionRetired 16384` | Fire an interrupt every 16,384 retired instructions | +| `-stackwalk profile` | Capture a call stack on each profile interrupt, providing call-chain data instead of branch sequences | + +Compared to LBR: no `-LastBranch` flag; uses `InstructionRetired` instead of `BranchInstructionRetired`. The result is instruction-pointer samples with call stacks, not branch sequences. This path still provides effective data for the optimizer, but it's slightly less rich. + +After starting `xperf`, continue to [Run the workload and stop xperf](#run-the-workload-and-stop-xperf-all-paths). + +### OS timer path + +Start xperf with OS timer-based sampling: + +```cmd +xperf -on LOADER+PROC_THREAD+PROFILE -MinBuffers 4096 -BufferSize 4096 -setProfInt Timer 1221 -stackwalk profile +``` + +**Parameter explanation:** + +| Parameter | Purpose | +|-----------|---------| +| `LOADER+PROC_THREAD+PROFILE` | No PMC events; CPU sampling via OS timer interrupt only | +| `-setProfInt Timer 1221` | Fire on the OS timer interrupt every 1,221 timer ticks (approximately 1 kHz) | +| `-stackwalk profile` | Capture a call stack on each timer interrupt | + +Compared to LBR and PMC, this method doesn't use hardware performance counters. The OS timer fires at roughly fixed time intervals regardless of CPU activity. Samples are less densely correlated to hot code but still provide useful control-flow data for the optimizer. + +### Run the workload and stop xperf (all paths) + +With `xperf` running, run `textCount` against War and Peace: + +```cmd +textCount.exe < warAndPeace.txt +``` + +After `textCount` finishes, stop `xperf` and write the trace file. Letting other processes run during profiling dilutes sample quality. For best results, close unnecessary applications before running the workload. + +```cmd +xperf -stop -d textCount.etl +``` + +After stopping `xperf` (it can take a while to write out the etl file), confirm that `textCount.etl` was created in the current directory. + +## Convert the ETL file to SPT + +This step is the same for all three profiling paths. + +Run `SPTAggregate.exe` to process the raw ETL trace and create an SPT profile file: + +```cmd +SPTAggregate.exe /binary textCount.exe /etl textCount.etl textCount.spt +``` + +**Parameter explanation:** + +| Parameter | Purpose | +|-----------|---------| +| `/binary textCount.exe` | The binary to extract samples from. The ETL might contain samples from all processes that ran during profiling | +| `/etl textCount.etl` | Input ETL trace file | +| `textCount.spt` | Output SPT profile file | + +`SPTAggregate` outputs a summary that shows how many samples it collected. This summary is your first confirmation that profiling worked. + +Check the output from `SPTAggregate` against the path you took: + +- **LBR path:** Look for a nonzero Used LBR Samples count. +- **PMC path:** Look for a nonzero PMC or stack sample count. +- **OS timer path:** Look for a nonzero used stack samples count. + +If all counts are zero, see [Troubleshooting](#troubleshooting) before continuing. + +## Convert the SPT file to SPD + +> **Your path:** +> - **LBR users** (use `/mode:LBR`): [LBR mode](#lbr-mode) +> - **PMC users** (use `/mode:IP`): [IP mode (PMC and OS timer)](#ip-mode-pmc-and-os-timer) +> - **OS timer users** (use `/mode:IP`): [IP mode (PMC and OS timer)](#ip-mode-pmc-and-os-timer) +> +> Both PMC and OS timer paths use `/mode:IP` because both produce instruction-pointer samples. + +The next step branches by profiling path, specifically on the `/mode` flag passed to `SPDConvert.exe`. + +### LBR mode + +```cmd +SPDConvert.exe /mode:LBR textCount.spd textCount.spt +``` + +`/mode:LBR` tells `SPDConvert` to interpret the SPT as containing LBR branch sequence data. + +### IP mode (PMC and OS timer) + +Both PMC and OS timer produce instruction-pointer samples, so both use the same conversion command: + +```cmd +SPDConvert.exe /mode:IP textCount.spd textCount.spt +``` + +`/mode:IP` tells `SPDConvert` to interpret the SPT as containing instruction-pointer samples. + +> [!WARNING] +> Using the wrong mode for your data type can produce an empty or malformed SPD. If you profiled with LBR, use `/mode:LBR`. +> If you profiled with PMC or OS timer, use `/mode:IP`. The `SPTAggregate` summary output from [Convert the ETL file to SPT](#convert-the-etl-file-to-spt) shows which sample types were collected and confirms the correct mode to use. + +After running `SPDConvert`, confirm that `textCount.spd` was created (or updated) in the current directory. + +### Interpreting SPDConvert output + +The command `SPDConvert textCount.spd textCount.spt` prints a before-and-after block coverage summary, for example: + +``` +Block coverage (before) : 33.90% ( 4507/ 13294) +Block coverage (after) : 45.64% ( 6067/ 13294) +``` + +This summary shows the percentage of the binary's code blocks that have associated profile data. A higher percentage is better. Coverage above 70% is excellent, while coverage below 40% might limit optimization effectiveness. If coverage is low, run the profiling workload longer or combine multiple SPT files from separate runs with different workloads. For example, you could run `textCount` against multiple text files to exercise different code paths. + +You might see a warning from `SPDConvert` like the following: + +``` +Compiler may be conservative on some hot functions due to sparse sample coverage. +SPGO is estimated to optimize better if sample density is increased to 5.4x of current level. +Sample density can be increased by sampling for longer period, or increasing sample rate. +``` + +This warning means your profiling run didn't collect enough samples for the optimizer to confidently optimize all hot functions. The SPD is still usable, but you can improve results by: + +- Running the workload longer (for example, 5 or more minutes instead of 1 minute) or using different workloads. +- Lowering the `-setProfInt` value in the `xperf` command to increase the sampling rate. The tradeoff is that this change produces a larger ETL file, which takes longer to process. +- Combining multiple SPT files from separate profiling runs by passing them all to `SPDConvert`. + +The SPT file is a binary format. To inspect its contents, you can run `SPTDump.exe textCount.spt`. Similarly, `PTDump.exe textCount.spt` shows the compiled profile data after running `SPDConvert`. Both tools are useful for verifying nonzero samples before proceeding. + +## Rebuild textCount with /spdin + +Rebuild `textCount` by using the populated SPD file. The linker reads the profile data and applies SPGO optimizations. + +This step is the same for all three profiling paths. + +```cmd +cl /Zi /EHsc /GL /O2 textCount.cpp /link /debug /spgo /spdin:textCount.spd +``` + +**New flag (compared to [Build textCount with /spgo](#build-textcount-with-spgo)):** + +| Flag | Purpose | +|------|---------| +| `/spdin:textCount.spd` | Provide the SPD profile data to the linker for optimization | + +The command still includes `/spgo`. It generates a new SPD file alongside the optimized binary, which you can use as the starting point for subsequent profiling iterations. + +> [!WARNING] +> The SPD file is associated with the exact binary it profiles against. If you rebuild `textCount` without `/spdin`, or rebuild from changed source, you must generate a new SPD file. The existing one doesn't match the new binary's GUID, and the linker won't use it. + +After the rebuild with `/spdin`, the linker outputs statistics about how much of your code was optimized using profile data. For example: + +``` +221 of 221 (100.00%) profiled functions will be compiled for speed +201 of 1383 inline instances were from dead/cold paths +474 of 474 profiled functions (100.0%) were optimized using profile data +202738780 of 202738780 instructions (100.0%) were optimized using profile data +``` + +A high percentage means the SPD covers your binary well. If the percentage is low (for example, below 90%), either the profiling workload didn't exercise enough of the binary, or the binary has changed significantly since the profile was collected. In both cases, reprofile against the current binary. + +### What SPGO does with your profile data + +SPGO uses the collected sample data to populate counts on each block and edge in the program's control flow graph. These counts drive optimizations such as: +- **Profile-guided inlining**: Aggressively inline hot call sites while avoiding code bloat from inlining cold paths. +- **Hot/cold code separation**: Move rarely executed code to separate sections of the binary, improving instruction cache utilization and paging behavior. +- **Function layout**: Place functions that call each other frequently near each other in the binary, reducing page faults and improving locality. Optimized functions are organized into high affinity COFF groups in the binary. +- **Size/speed decisions**: Compile hot functions for speed and cold functions for size. Routines with no observed profile hits might be compiled for size rather than speed, limiting optimizations like inlining and loop unrolling in those cold paths. +- **Speculative devirtualization**: When sampling reveals that an indirect call consistently targets the same function, SPGO can speculate on that target and inline it, with a fallback for the uncommon case. + +## Measure the results + +Run `textCount` again and compare elapsed times. + +```cmd +textCount.exe < warAndPeace.txt +``` + +Collect multiple runs for each configuration and use the median. A single run isn't reliable because OS scheduling and system noise can skew individual measurements. + +| Build | Representative elapsed time | +|-------|-----------------------------| +| Baseline (`cl /Zi /EHsc /O2 /link /debug`) | *(your measurement)* | +| `/spgo` build (no profile data yet) | *(should be close to baseline)* | +| SPGO-optimized (`/spdin`) | *(should show improvement)* | + +In one test, SPGO using the LBR method delivered approximately 7% reduction in elapsed time. Your results might vary with your own projects because SPGO gains depend on how well the profiling workload represents typical execution. Larger, branch filled codebases tend to see more improvement within the 5–10% range. The profiling method affects optimization quality. LBR typically produces better results than PMC, which produces better results than OS timer. If you're on the OS timer path, expect smaller gains. + +The LBR path followed in this tutorial was applied to the [SQLite](https://github.com/sqlite/sqlite) project, which is a production database library. The SPGO-optimized SQLite binary showed approximately a 7% improvement. + +## Apply SPGO to your own project + +Use this checklist to apply SPGO to your own C or C++ application. + +1. **Add `/Zi /link /debug /spgo` to your existing release build command.** Modify your build script or project file: + + ```cmd + cl /Zi /EHsc /GL /O2 myapp.cpp /link /debug /spgo + ``` + +1. **Choose a representative workload.** Select a real usage scenario that exercises the hot paths of your application. Use production-like data. Avoid the following as your primary profiling workload: code coverage tests (they don't stress performance bottlenecks), uncommon error paths, startup and shutdown phases, and deprecated code paths. This workload drives the profile that feeds the optimizer. +1. **Run xperf using your detected path.** Use the path you identified in [Choose your profiling method](#choose-your-profiling-method) (LBR, PMC, or OS timer). Start `xperf`, run the workload once, stop `xperf`, and capture the ETL file. +1. For the PMC or OS timer path, **run SPTAggregate and SPDConvert with the correct `/mode` flag.** Convert ETL to SPT then to SPD. Use `/mode:LBR` for LBR data; use `/mode:IP` for PMC or OS timer data. +1. **Rebuild with `/spdin:`.** Compile your application with the populated SPD: + + ```cmd + cl /Zi /EHsc /GL /O2 yourApp.cpp /link /debug /spgo /spdin:yourApp.spd + ``` + +1. **Measure before and after.** Run your workload with both the nonoptimized and SPGO-optimized binaries. Collect the **median of multiple runs** for each configuration. A single run isn't reliable for benchmarking. +1. **Store the `.spd` file in source control.** Check the `.spd` file into your source control system alongside your source code. +1. **Enable SPGO in developer Release builds.** Have your team's Release builds use the same SPGO-optimized binaries as production. This helps catch performance regressions early. +1. Disable SPGO in Debug builds. +1. **Watch the linker's profile completeness statistics.** After each build with `/spgo`, note the percentage of profiled functions optimized using profile data. If this drops significantly (below 90%), reprofile the current binary. Code changes accumulate and the SPD can become stale. + +### Alternative to using `xperf` + +Another way to gather profile data is to use a sampling profiler like Windows Performance Recorder (WPR). WPR is installed by default on Windows 10 and later. It collects similar data to `xperf`. You can configure WPR to collect CPU samples with call stacks, and then export the data to an ETL file that you can process with `SPTAggregate` and `SPDConvert` like the `xperf` ETL. Here's an example of using WPR to collect profile data: + +```cmd +wpr -start CPU.light -filemode +textCount.exe < warAndPeace.txt +wpr -stop spgo_data.etl +``` +For more information on using WPR, see [Using Windows Performance Recorder](/windows-hardware/test/wpt/recording-pmu-events). + +### SPD distribution + +You can: + +- Check the `.spd` file directly into source control alongside your source code. +- Share the `.spd` file with teammates so they can build with SPGO optimizations without reprofiling. +- Package the `.spd` file with your binaries as a versioned artifact (for example, a NuGet package) and record which version corresponds to which binary. +- Regenerate the `.spd` file at any time by repeating the profiling workflow. + +The SPD ties to the exact binary it was built from. After significant code changes, reprofile to generate a fresh SPD. During the `/spdin` build, the compiler also produces a new `.spd` file. Save this new SPD as a build artifact - it's the starting point for your next profiling iteration. + +## Reusing SPD information across builds + +The "carry forward" concept in SPGO allows you to add profiling data to an existing SPD file without profiling all your scenarios over again from scratch and without losing existing profile information. You can also adjust how much weight to give to older profile data. This flexibility is useful when there might be behavioral changes over time and you don't want to completely lose the profiling information from earlier scenario runs. For instance, a DLL might see different APIs called as the application that calls it evolves. You still want the optimizations from how it used to behave, but want to mix in optimization opportunities for how it sometimes behaves differently now. You can evolve the profile over time by mixing old and new data. + +When you run `SPDConvert` with a new SPT file, pass the name of the existing SPD file. Then use the `/retire:N` option to control how aggressively `SPDConvert` de-emphasizes older profile data when you add new SPT files: +- The default (`/retire:8`) weights newer data more heavily. +- Use `/retire:0` to give equal weight to all runs. +- Use `/retire:16` to let only the newest data count. + +## Troubleshooting + +> **Find your issue:** +> - **LBR path problems:** [LBR path problems](#lbr-path-problems) +> - **PMC path problems:** [PMC path problems](#pmc-path-problems) +> - **OS timer problems:** [OS timer path problems](#os-timer-path-problems) +> - **Issues affecting all paths:** [General issues](#general-issues-all-paths) + +### LBR path problems + +| Problem | Likely cause | Fix | +|---------|-------------|-----| +| Zero LBR samples in `SPTAggregate` output | CPU doesn't support LBR, or VM doesn't expose LBR | Run the detection command from [Detect your path](#detect-your-path). If in a Hyper-V VM, run `Set-VMProcessor MyVMName -Perfmon @("pmu", "lbr")` on the host. If LBR isn't available, switch to the PMC or OS timer path. | +| Processor supports LBR but `SPTAggregate` shows 0 LBR samples | `perfcore.ini` DLL registration incomplete | Complete the `perfcore.ini` setup in [Configure perfcore.ini](#configure-perfcoreini). Ensure `perf_lbr.dll` is registered. | +| `SPDConvert` fails or produces an empty SPD | Wrong `/mode` flag, or SPT contains only IP-mode samples | Confirm `SPTAggregate` output showed LBR samples. If the output shows only IP-mode samples, switch to `/mode:IP`. | + +### PMC path problems + +| Problem | Likely cause | Fix | +|---------|-------------|-----| +| Zero PMC samples in `SPTAggregate` output | `perfcore.ini` DLL registration incorrect | Complete the `perfcore.ini` setup in [Configure perfcore.ini](#configure-perfcoreini). Ensure `perf_spt.dll` is registered. Without this DLL, `xperf` produces zero PMC samples without an error message.
Run `xperf.exe -pmcsources` to see the list of Performance Counters sources available on your CPU. If you don't see entries like `SPT_OP_RETIRE_INSTR` or `SPT_OP_RETIRE_BR_INSTR` or `SPT_OP_ETW_INSTR`, then the DLL registration in `perfcore.ini` might be incomplete or your CPU might not support PMC. If you can't resolve the DLL registration, try the OS timer path, instead. | +| `findstr InstructionRetired` returns output but `xperf` produces no samples | VM masking PMC counters | Check if running in a VM. Enable PMU in Hyper-V with `Set-VMProcessor`, or switch to the OS timer path. | +| `SPDConvert` fails on PMC path | Using `/mode:LBR` on an IP-only SPT | Switch to `/mode:IP`. | + +### OS timer path problems + +| Problem | Likely cause | Fix | +|---------|-------------|-----| +| Less improvement than expected | Expected - OS timer is lower fidelity | This is normal. The optimizer has less branch-flow information from timer samples than from LBR or PMC. Performance gains are smaller. Consider upgrading to PMC or LBR if hardware supports it. | +| Zero timer samples | `xperf` wasn't run in an elevated prompt, or `PROFILE` provider missing | Confirm running as Administrator. Confirm `-stackwalk profile` was provided to the `xperf` command. | + +### General issues (all paths) + +| Problem | Likely cause | Fix | +|---------|-------------|-----| +| `"failed to configure counters"` error | `xperf` not running as administrator | Restart the command prompt as **Administrator** (right-click > Run as administrator). xperf requires elevated privileges to configure hardware performance counters. | +| `xperf` not found | `xperf.exe` not on PATH | Confirm the Windows ADK is installed. Check `C:\Program Files (x86)\Windows Kits\10\Windows Performance Toolkit\`. Add that directory to your PATH, or run xperf from it directly. | +| `textCount.etl` not created | xperf failed silently | Confirm running as administrator. Rerun the xperf start command and check for error output. | +| `SPTAggregate` fails with "binary not found" | `textCount.exe` not in current directory or wrong path | Confirm you're in the same directory as `textCount.exe`, or provide the full path to the `/binary` parameter. | +| SPD file not created | `SPDConvert` failed | Check that `textCount.spt` size is nonzero. Run `SPTDump.exe textCount.spt` to inspect its contents. | +| `/spdin` build produces no improvement | GUID/age mismatch between SPD and binary | The SPD was built from a different `textCount.exe`. Profile the current build again to generate a fresh SPD. | +| MSVC version error on `/spgo` | MSVC toolset earlier than v14.51 | Open the Visual Studio Installer > **Individual Components** > install **MSVC v14.51** or later. Reopen the Developer Command Prompt. | + +## Next steps + +After completing this tutorial, explore these capabilities to get more from SPGO: + +- **Profile blending:** Run multiple workloads, accumulate SPT files from each run, and pass all of them to `SPDConvert`. A blended SPD reflects the full range of real usage patterns and produces better optimizations than a single-scenario profile. Use the `/retire:N` option to control how aggressively `SPDConvert` de-emphasizes older profile data when you add new SPT files. The default (`/retire:8`) weights newer data more heavily. Use `/retire:0` to give equal weight to all runs; use `/retire:16` to let only the newest data count. +- The best results come from blending profiles from multiple sources such as benchmarks that stress key scenarios plus real-world data (where available). Pass SPT files from all sources to `SPDConvert`. Repeat an SPT file in the argument list to give it more weight (for example, `SPDConvert myapp.spd critical.spt critical.spt common.spt` weights `critical.spt` twice as heavily as `common.spt`). +- **Iterative optimization:** Each rebuild with `/spdin` produces a new SPD. You can repeat the run, profile, rebuild cycle. Later iterations might show diminishing returns, but a second pass can sometimes capture patterns the first missed. +- **Code changes:** After significant source changes, recollect profile data. The existing SPD is tied to the binary it was profiled against. It won't match a substantially rebuilt binary. +- **Profile freshness:** The linker reports the percentage of profiled functions optimized using profile data after each `/spdin` build. If this percentage drops significantly, it's a signal that the code has diverged from the profile. Reprofile the current binary. \ No newline at end of file diff --git a/docs/build/spdconvert.md b/docs/build/spdconvert.md new file mode 100644 index 00000000000..e886c1e1846 --- /dev/null +++ b/docs/build/spdconvert.md @@ -0,0 +1,119 @@ +--- +description: "Learn more about: SPDConvert" +title: "SPDConvert" +ms.date: 05/08/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["SPDConvert program", "sample profile-guided optimizations, SPDConvert", "SPGO"] +--- +# SPDConvert + +Use `SPDConvert` to prepare and manage sample profile data for Sample Profile-Guided Optimization (SPGO). + +This tool correlates the raw hardware samples in SPT files against the code structure in the SPD. This step performs sample correlation, flow smoothing, and size/speed decisions, and produces an enriched SPD file with execution counts annotated on the flow graph. + +You can combine data from multiple sources such as lab benchmarks, internal monitoring, and production telemetry, in a single conversion. To emphasize the importance of a particular scenario, you can specify its SPT file multiple times. Listing a critical benchmark SPT three times effectively triples its weight. + +This tool operates in three modes: + +- *import* .SPT data into an .SPD file for [/SPGO](sample-profile-guided-optimization.md) builds +- *extract* an embedded .SPD file from a .PDB +- *merge* multiple .SPD files from separate profiling runs + +`SPDConvert` works with three file types: +- **ETL** (Event Trace Log) Raw hardware performance events recorded by `xperf` +- **SPT** (Sample Profile Trace) Packaged sample events produced by [`SPTAggregate`](sptaggregate.md) from ETL files +- **SPD** (Sample Profile Database) Processed profile data used by the compiler during an optimized build. You can also embed SPD files in PDB symbol files during a `/spdembed` build + +## Syntax + +Import SPT data into an existing SPD file: + +> `SPDConvert` [*options*] *spdfile* *sptfile(s)* + +Extract an embedded SPD file from a PDB: + +> `SPDConvert` **/extract** *pdbfile* *spdfile* + +Merge multiple SPD files into one: + +> `SPDConvert` **/merge** *outputspdfile* *spdfile(s)* + +### Parameters + +**IMPORT MODE** + +*options*\ +Specify the following options in import mode: + +- **/mode:**\<**IP**\|**LBR**\> Select the profile mode. Use **IP** for instruction pointer profile data (default) or **LBR** for last branch record profile data. +- **/reset:** Reset the count to 0. This action ignores SPTs. Use this option to reset an SPD file before importing new data, or to create an empty SPD file if the specified file doesn't exist. +- **/sptlist:**\<*file*\> Specify SPT file names in a text file, with one file name per line. +- **/summary** Print a summary of the SPD file. +- **/help** Display help information. + +*spdfile*\ +The SPD file to import sample data into. + +*sptfiles*\ +One or more SPT files to import. SPT files are produced by [SPTAggregate](sptaggregate.md). + +**EXTRACT MODE (/extract)** + +*pdbfile*\ +The PDB file that contains an embedded SPD. + +*spdfile*\ +The output SPD file to create. + +**MERGE MODE (/merge)** + +*outputspdfile*\ +The output SPD file to create. + +**/retire:**\<*N*\> Set the profile data retire rate to *N*/16, where 0 ≤ *N* ≤ 16. The default is 8. This value controls how much of the existing data in an SPD to delete when adding new SPT data. For example, `/retire:8` deletes 8/16 (half) of the existing data before adding new SPT data. This setting weights newer profile data more heavily because it discards half of the older data. The two most common usages are `/retire:0` which gives equal weight to all profile runs, or `/retire:16` to make only the newest data count because it deletes all the old data. Use `/retire:N` to control how aggressively `SPDConvert` de-emphasizes older profile data. This "carry forward" concept allows you to refresh a profile using existing SPD data without starting over with new profiling data, which is time-consuming. This concept is discussed more in the [SPGO tutorial - Reusing SPD information across builds](sample-profile-guided-optimization.md#reusing-spd-information-across-builds). + +*spdfiles*\ +One or more SPD files to merge. + +## Remarks + +> [!NOTE] +> Run this tool from a Visual Studio developer command prompt. + +`SPDConvert` is the main conversion tool in the SPGO workflow. After collecting a trace by using `xperf` and converting it to an SPT file by using [`SPTAggregate`](sptaggregate.md), use `SPDConvert` to import the sample data into an SPD file. Pass the resulting SPD file to the compiler by using the [`/SPGO`](sample-profile-guided-optimization.md) flag to build an optimized binary. + +Use `/extract` to recover an SPD file that was embedded in a PDB during a `/SPGO` build. +Use `/merge` to combine SPD files from multiple profiling sessions before rebuilding. + +The GUID and age of a binary must match between the SPT and SPD files. If they don't match, `SPDConvert` reports an "SPD version incompatible" error. Use [`SPTDump /progid`](sptdump.md) to check the binary identifiers in the SPT file, and [`SPDDump /header`](spddump.md) to check the SPD file. + +The GUID and age of the binary recorded in the SPD file must match the SPT file. To diagnose this error, use [`SPTDump /progid`](sptdump.md) to inspect the binary identifiers in the SPT file, and [`SPDDump /header`](spddump.md) to inspect the SPD file. A valid SPD file is used to the extent possible. Minor updates to the code that don't alter the program's control flow are tolerated. Unchanged functions also use the data for optimization. If you provide a valid, but otherwise unrelated SPD, the process works, but likely no data is usable for optimization. + +## Example + +This example imports LBR profile data from an SPT file into an SPD file: + +`SPDConvert /mode:LBR sample.spd sample.spt` + +This example imports IP profile data by using a list of SPT files: + +`SPDConvert /mode:IP /sptlist:mysptfiles.txt sample.spd` + +This example prints a summary of the profile data in an SPD file: + +`SPDConvert /summary sample.spd` + +This example extracts the embedded SPD from a PDB file: + +`SPDConvert /extract sample.pdb sample_extracted.spd` + +This example merges two SPD files from different profiling runs: + +`SPDConvert /merge combined.spd run1.spd run2.spd` + +## See also + +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](sample-profile-guided-optimization.md)\ +[`SPDDump`](spddump.md)\ +[`SPTAggregate`](sptaggregate.md)\ +[`SPTDump`](sptdump.md) diff --git a/docs/build/spddump.md b/docs/build/spddump.md new file mode 100644 index 00000000000..f3cfdade2b3 --- /dev/null +++ b/docs/build/spddump.md @@ -0,0 +1,68 @@ +--- +description: "Learn more about: SPDDump" +title: "SPDDump" +ms.date: 04/30/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["SPDDump program", "sample profile-guided optimizations, SPDDump", "SPGO"] +--- +# SPDDump + +Use `SPDDump` to inspect Sample Profile Database (SPD) files and object files that contain sample profile data for Sample Profile-Guided Optimization (SPGO). Use this tool to verify SPD contents, troubleshoot SPD/PDB compatibility problems, and view profile details such as functions, flow graphs, coverage, and dynamic instruction estimates. Run `SPDDump` from a Visual Studio Developer Command Prompt. + +An SPD file contains processed profile data that the compiler uses to make optimization decisions during a build. + +## Syntax + +> `SPDDump` [*options*] *spdfile* + +### Parameters + +*options*\ +Specify the following options for `SPDDump`: + +- **/all** Output the entire SPD file. This option is the default. +- **/header** Output the SPD file header. +- **/module** Output the module header in the SPD file. Implies **/header**. +- **/symbol** Output the module symbol table. Implies **/module**. +- **/func** Output the function profile. Implies **/module**. +- **/funcid:**\<*fid*\> Output the function profile for the function with the given function ID. +- **/cg** Include callee information in function profile output. Implies **/func**. +- **/fg** Include the flow graph in function profile output. Implies **/func**. +- **/data** Output the data profile. Implies **/module**. +- **/minidump** Exclude sample correlation information such as RVA ranges from output. +- **/coverage** Output basic block coverage information. +- **/dyninst**[**:**\<*n*\>] Output a dynamic instruction estimate for the top 50 functions, or the top *n* functions if specified. +- **/help** Display help information. + +*spdfile*\ +The path to the SPD file or object file to inspect. + +## Remarks + +> [!NOTE] +> Run this tool from a Visual Studio developer command prompt. + +Use `SPDDump` to inspect the contents of a Sample Profile Database (SPD) file. [`SPDConvert`](spdconvert.md) produces SPD files. The build process that uses [`/SPGO`](sample-profile-guided-optimization.md) embeds these files in PDB files. + +To diagnose an "SPD version incompatible" error, use `/header` to examine the PDB GUID and age stored in the SPD file. Then, compare those values against the SPT file by using [`SPTDump /progid`](sptdump.md). + +## Example + +This example outputs estimated basic block coverage information for an SPD file: + +`SPDDump /coverage filename.spd` + +This example outputs the SPD header to check the PDB GUID and age: + +`SPDDump /header filename.spd` + +This example outputs a dynamic instruction estimate for the top 10 functions: + +`SPDDump /dyninst:10 filename.spd` + +## See also + +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](sample-profile-guided-optimization.md)\ +[SPDConvert](spdconvert.md)\ +[SPTDump](sptdump.md)\ +[SPTAggregate](sptaggregate.md) diff --git a/docs/build/specifying-build-events.md b/docs/build/specifying-build-events.md index 5490fb70902..25f79a10762 100644 --- a/docs/build/specifying-build-events.md +++ b/docs/build/specifying-build-events.md @@ -5,6 +5,7 @@ ms.date: "12/28/2017" f1_keywords: ["VC.Project.IVCEventTool.CommandLine", "VC.Project.IVCEventTool.ExcludedFromBuild", "VC.Project.IVCEventTool.Description"] helpviewer_keywords: ["Pre-Link event", "build events [C++], specifying", "custom build steps [C++], build events", "builds [C++], events", "events [C++], build", "builds [C++], customizing C++", "build events [C++]", "post-build events"] ms.assetid: 788a6c18-2dbe-4a49-8cd6-86c1ad7a95cc +ms.topic: how-to --- # Specifying build events diff --git a/docs/build/specifying-custom-build-tools.md b/docs/build/specifying-custom-build-tools.md index 197908e3e4a..251433fada8 100644 --- a/docs/build/specifying-custom-build-tools.md +++ b/docs/build/specifying-custom-build-tools.md @@ -4,6 +4,7 @@ title: "Specifying Custom Build Tools" ms.date: "06/05/2018" f1_keywords: ["VC.Project.VCCustomBuildTool.CustomBuildToolBeforeTargets", "VC.Project.VCCustomBuildTool.Outputs", "VC.Project.VCCustomBuildTool.Command", "VC.Project.VCCustomBuildTool.CommandLine", "VC.Project.VCCustomBuildTool.AdditionalDependencies", "VC.Project.VCCustomBuildTool.Message", "VC.Project.VCCustomBuildTool.CustomBuildToolAfterTargets", "VC.Project.VCCustomBuildTool.Description", "VC.Project.VCCustomBuildTool.AdditionalInputs"] helpviewer_keywords: ["build tools (C++), specifying", "custom build tools (C++), specifying", "builds (C++), custom build tools"] +ms.topic: how-to --- # Specify custom build tools diff --git a/docs/build/sptaggregate.md b/docs/build/sptaggregate.md new file mode 100644 index 00000000000..1d5a67e8a6b --- /dev/null +++ b/docs/build/sptaggregate.md @@ -0,0 +1,69 @@ +--- +description: "Learn more about: SPTAggregate" +title: "SPTAggregate" +ms.date: 05/01/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["SPTAggregate program", "sample profile-guided optimizations, SPTAggregate", "SPGO"] +--- +# SPTAggregate + +`SPTAggregate` is a command-line tool for Sample Profile-Guided Optimization (SPGO). Use it to combine one or more ETL (Event Trace Log) files that `xperf` collects into a single SPT (Sample Profile Trace) file. You can optionally filter data by process or binary name and exclude kernel events. After you create the SPT file, use [SPDConvert](spdconvert.md) to import it into an SPD (Sample Profile Database) file for optimization workflows. + +ETL (Event Trace Log) files contain raw hardware performance events that `xperf` records. `SPTAggregate` converts those ETL files into SPT format, which packages the sample events for import into an SPD (Sample Profile Database) file by [SPDConvert](spdconvert.md). + +## Syntax + +> `SPTAggregate` [*options*] **/etl** *etlfiles* *sptfile* + +### Parameters + +*options*\ +Specify the following options to `SPTAggregate`: + +- **/process:**\<*processes*\> Filter events by process name. Specify one or more process names as a comma-separated list.\ + Example: `/process:myapp.exe` +- **/binary:**\<*binaries*\> Filter events by binary name. Specify one or more binary names as a comma-separated list.\ + Example: `/binary:mylib.dll,myapp.exe` +- **/nokernel** Exclude OS kernel events. +- **/help** Display help information. + +*etlfiles*\ +A comma-separated list of ETL (Event Trace Log) files to process. Collect ETL files by using `xperf`. + +*sptfile*\ +The output SPT file to create. + +## Remarks + +> [!NOTE] +> Run this tool from a Visual Studio developer command prompt. + +Use `SPTAggregate` to convert one or more ETL files collected by `xperf` into an SPT file. The `/etl` flag is required and must precede the list of ETL files. You can import the resulting SPT file into an SPD file by using [`SPDConvert`](spdconvert.md). + +`SPTAggregate` uses `xperf`, which must be in your path and set up with the `perfcore.ini` changes as described in [Configure perfcore.ini](sample-profile-guided-optimization.md#configure-perfcoreini). + +When `SPTAggregate` runs `xperf`, it uses parameters like: `xperf -a spt -genSPT outputfile.spt -binary application.exe,support.dll,companion.dll` where `-a spt` specifies generate a sample profile trace analysis report, `-genSPT` specifies the output SPT file, and `-binary` focuses analysis on the specified binaries. + +For more information about `xperf` flags, see the [Xperf Command-Line Reference](/windows-hardware/test/wpt/xperf-command-line-reference) documentation. + +## Example + +This example converts a single ETL file into an SPT file: + +`SPTAggregate /etl filename.etl filename.spt` + +This example filters events to a specific process: + +`SPTAggregate /process:filename.exe /etl filename.etl filename.spt` + +This example aggregates two ETL files and excludes kernel events: + +`SPTAggregate /nokernel /etl run1.etl,run2.etl filename.spt` + +## See also + +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](sample-profile-guided-optimization.md)\ +[Profile-Guided Optimizations](profile-guided-optimizations.md)\ +[`SPDConvert`](spdconvert.md)\ +[`SPDDump`](spddump.md)\ +[`SPTDump`](sptdump.md) diff --git a/docs/build/sptdump.md b/docs/build/sptdump.md new file mode 100644 index 00000000000..7ba096eee51 --- /dev/null +++ b/docs/build/sptdump.md @@ -0,0 +1,110 @@ +--- +description: "Learn more about: SPTDump" +title: "SPTDump" +ms.date: 05/05/2026 +ai-usage: ai-assisted +helpviewer_keywords: ["SPTDump program", "sample profile-guided optimizations, SPTDump", "SPGO"] +--- +# SPTDump + +`SPTDump` is a command-line tool for inspecting Sample Profile Trace (SPT) files used in Sample Profile-Guided Optimization (SPGO) workflows. Use it to view SPT metadata and sample data. Validate trace contents before conversion to SPD, and troubleshoot issues such as SPD version mismatches. + +An SPT file contains raw hardware performance sample events collected from an application workload. + +## Syntax + +> `SPTDump` [*options*] *sptfile* + +### Parameters + +*options*\ +Specify the following options to `SPTDump`: + +- **/all** Output the entire SPT file. This option is the default. +- **/header** Output the SPT file header. +- **/progid** Output program IDs (GUID and age for each binary). +- **/strtab** Output the string table. +- **/event** Output sample events. +- **/help** Display help information. + +*sptfile*\ +The path to the SPT file to inspect. + +## Remarks + +> [!NOTE] +> Start this tool from a Visual Studio developer command prompt. + +Use `SPTDump` to inspect the contents of a Sample Profile Trace (SPT) file. [SPTAggregate](sptaggregate.md) produces SPT files from ETL event trace logs collected by `xperf`. Import SPT files into an SPD file (Sample Profile Database) by using [SPDConvert](spdconvert.md). + +To diagnose an "SPD version incompatible" error, use `/progid` to display the GUID and age for each binary in the SPT file, and then compare those values against the SPD file by using [`SPDDump /header`](spddump.md). + +## Example + +This example outputs the full contents of an SPT file: + +`SPTDump sample.spt` + +This example outputs only the program IDs (GUID and age) for binaries in an SPT file: + +`SPTDump /progid sample.spt` + +## SPT header format + +SPT file is a binary format with a 32-byte header, string table, program ID table, and sample event data stream. This document describes version 1 of the format. The version field updates if the layout changes in the future. + +The SPT header is 32 bytes: + +- `[0x00-0x03]` Signature (uint32 LE) = 0x5350543A ("SPT:") +- `[0x04-0x07]` Version (uint32 LE) = 1 +- `[0x08-0x0B]` RawDataId (uint32 LE) = 0 (unused/reserved) +- `[0x0C-0x0F]` TargetArch (uint32 LE) = 0 (unused/reserved) +- `[0x10-0x13]` StringTableOffset (uint32 LE) = offset to binary name string table (typically 0x20) +- `[0x14-0x17]` ProgramIdTableOffset (uint32 LE) = offset to RSDSKEY table (typically StringTableOffset+StringTableCapacity) +- `[0x18-0x19]` StringTableUsed (uint16 LE) = bytes used in string table +- `[0x1A-0x1B]` StringTableCapacity (uint16 LE) = bytes allocated in string table (typically 0x4000) +- `[0x1C-0x1D]` ProgramIdsUsed (uint16 LE) = number of program IDs (often just 1) +- `[0x1E-0x1F]` ProgramIdCapacity (uint16 LE) = capacity in count (not bytes) for program IDs (typically 0x100) + +The StringTable immediately follows the header at the specified offset. It contains a null-terminated UTF-8 binary filename. + +The ProgramIdTable follows the StringTable at the specified offset. Each entry is 24 bytes: 16-byte Rich Signature Data Stream (RSDS) GUID + 4-byte age + 4-byte string index into StringTable. + +The data stream starts at `ProgramIdTableOffset + (ProgramIdCapacity * 24)`, and starts with a `SPT_OP_BINARY_ID` opcode. + +**SPT Opcodes** + +In the following descriptions: +- RVA means the 32-bit relative virtual address of an instruction in the binary, that is, it's offset in the module. +- LE means little-endian byte order. + +`SPT_OP_REPEAT` (0x82)\ +Repeat the next record for the specified number of times. A repeat count of 2 means that there are 3 identical records in total. The repeat count resets after processing it.\ +Layout: 1 byte: opcode 0x82. 1 byte: padding. 8 bytes: repeat count (uint64 LE) + +`SPT_OP_UNHALT_CYCLE`, `SPT_OP_RETIRE_INSTR`, `SPT_OP_RETIRE_BR_INSTR`, `SPT_OP_L1_ICACHE_MISS`, `SPT_OP_L1_DCACHE_MISS`, `SPT_OP_ETW_INSTR` (0x01, 0x02, 0x03, 0x04, 0x05, 0x41)\ +Layout: 1 byte: opcode. 1 byte: RVA count (N). 4N bytes: N RVAs (uint32 LE each)\ +Each RVA represents an IP sample hit count = 1 + repeat count. + +`SPT_OP_LBR` (0x10)\ +Layout: 1 byte: opcode 0x10. 1 byte: event count (N). 8N bytes: N LBR pairs, each pair is: 4 bytes: To RVA (uint32 LE), 4 bytes: From RVA (uint32 LE)\ +Each pair represents a branch arc with hit count = 1 + repeat count. + +`SPT_OP_ETW_CALLSTACK` (0x42)\ +Layout: 1 byte: opcode 0x42. 1 byte: RVA count (N). 4N bytes: N RVAs (uint32 LE each, representing stack frames).\ +When: +- N = 2: Two RVAs form a single stack arc (RVA[0], RVA[1]) +- N > 2: Creates N-1 arcs from consecutive pairs: (RVA[0]->RVA[1]), (RVA[1]->RVA[2]), ..., (RVA[N-2]->RVA[N-1]) +Each series, whether it's a single arc or consecutive pairs, has hit count = 1 + repeat count. + +`SPT_OP_BINARY_ID` (0x81)\ +Layout: 1 byte: opcode 0x81. 1 byte: padding. 2 bytes: program ID (uint16 LE). 4 bytes: total data length in this segment (uint32 LE).\ +Marks the start of data records for a specific binary specified by an index ID. The index ID refers back to the RSDSKey and binary name string table in the SPT header.\ +The data length includes the 4-byte length field itself. This opcode can occur multiple times in a data stream. + +## See also + +[Tutorial: Use Sample Profile-Guided Optimization (SPGO) to improve performance](sample-profile-guided-optimization.md)\ +[`SPDConvert`](spdconvert.md)\ +[`SPDDump`](spddump.md)\ +[`SPTAggregate`](sptaggregate.md) \ No newline at end of file diff --git a/docs/build/stack-usage.md b/docs/build/stack-usage.md index 8bbec4908e8..59c102e5ec9 100644 --- a/docs/build/stack-usage.md +++ b/docs/build/stack-usage.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: x64 stack usage" title: "x64 stack usage" -ms.date: "12/17/2018" -ms.assetid: 383f0072-0438-489f-8829-cca89582408c +description: "Learn more about: x64 stack usage" +ms.date: 12/17/2018 --- # x64 stack usage @@ -42,7 +41,7 @@ A leaf function is one that does not require a function table entry. It can't ma ## malloc alignment -[malloc](../c-runtime-library/reference/malloc.md) is guaranteed to return memory that's suitably aligned for storing any object that has a fundamental alignment and that could fit in the amount of memory that's allocated. A *fundamental alignment* is an alignment that's less than or equal to the largest alignment that's supported by the implementation without an alignment specification. (In Visual C++, this is the alignment that's required for a **`double`**, or 8 bytes. In code that targets 64-bit platforms, it's 16 bytes.) For example, a four-byte allocation would be aligned on a boundary that supports any four-byte or smaller object. +[malloc](../c-runtime-library/reference/malloc.md) is guaranteed to return memory that's suitably aligned for storing any object that has a fundamental alignment and that could fit in the amount of memory that's allocated. A *fundamental alignment* is an alignment that's less than or equal to the largest alignment that's supported by the implementation without an alignment specification. (In Microsoft C++, this is the alignment that's required for a **`double`**, or 8 bytes. In code that targets 64-bit platforms, it's 16 bytes.) For example, a four-byte allocation would be aligned on a boundary that supports any four-byte or smaller object. Visual C++ permits types that have *extended alignment*, which are also known as *over-aligned* types. For example, the SSE types [__m128](../cpp/m128.md) and `__m256`, and types that are declared by using `__declspec(align( n ))` where `n` is greater than 8, have extended alignment. Memory alignment on a boundary that's suitable for an object that requires extended alignment is not guaranteed by `malloc`. To allocate memory for over-aligned types, use [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) and related functions. diff --git a/docs/build/tips-for-improving-time-critical-code.md b/docs/build/tips-for-improving-time-critical-code.md index 822661efc89..aa3481e9e26 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 0d847bcb63a..639c828118b 100644 --- a/docs/build/toc.yml +++ b/docs/build/toc.yml @@ -9,7 +9,7 @@ items: - name: Set C++ compiler and build properties in Visual Studio expanded: false items: - - name: Set C++ compiler and build properties in Visual Studio + - name: Set C++ compiler and build properties href: ../build/working-with-project-properties.md - name: Share or reuse Visual Studio project settings href: ../build/create-reusable-property-configurations.md @@ -78,10 +78,12 @@ items: href: ../build/cmake-predefined-configuration-reference.md - name: "C++ Build Insights" href: ../build-insights/get-started-with-cpp-build-insights.md -- name: "Build and import header units" +- name: "Compare header units, modules, and precompiled headers" + href: ../build/compare-inclusion-methods.md +- name: "Header units" expanded: false items: - - name: "Walkthrough: Build and import header units in Visual C++ projects" + - name: "Walkthrough: Build and import header units in Microsoft C++ projects" href: ../build/walkthrough-header-units.md - name: "Walkthrough: Import STL libraries as header units" href: ../build/walkthrough-import-stl-header-units.md @@ -135,6 +137,8 @@ items: items: - name: Profile-guided optimizations href: ../build/profile-guided-optimizations.md + - name: Sample profile-guided optimization tutorial + href: ../build/sample-profile-guided-optimization.md - name: Environment variables for profile-guided optimizations href: ../build/environment-variables-for-profile-guided-optimizations.md - name: PgoAutoSweep @@ -143,6 +147,14 @@ items: href: ../build/pgomgr.md - name: pgosweep href: ../build/pgosweep.md + - name: SPDConvert + href: ../build/spdconvert.md + - name: SPDDump + href: ../build/spddump.md + - name: SPTAggregate + href: ../build/sptaggregate.md + - name: SPTDump + href: ../build/sptdump.md - name: "How to: Merge multiple PGO profiles into a single profile" href: ../build/how-to-merge-multiple-pgo-profiles-into-a-single-profile.md - name: Use the MSVC toolset from the command line @@ -312,6 +324,8 @@ items: href: ../build/prolog-and-epilog.md - name: x64 exception handling href: ../build/exception-handling-x64.md + - name: x64 Unwind Information V3 + href: ../build/x64-unwind-information-v3.md - name: Configure C++ projects for ARM processors expanded: false items: @@ -372,7 +386,7 @@ items: href: ../build/reference/help-files-html-help.md - name: Winhelp help files href: ../build/reference/help-files-winhelp.md - - name: Hint files for Intellisense + - name: Hint files for IntelliSense href: ../build/reference/hint-files.md - name: Property page XML files href: ../build/reference/property-page-xml-files.md @@ -406,7 +420,7 @@ items: - name: Command line property pages href: ../build/reference/command-line-property-pages.md - name: NMake property page - href: ../build/reference/nmake-property-page.md + href: ../build/reference/nmake-property-page.md - name: Manifest Tool property pages href: ../build/reference/manifest-tool-property-pages.md - name: Resources property pages @@ -513,6 +527,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 @@ -548,7 +564,7 @@ items: href: ../build/reference/fp-name-dot-pch-file.md - name: /FR, /Fr (Create .Sbr file) href: ../build/reference/fr-fr-create-dot-sbr-file.md - - name: /FU (Name forced + - name: "/FU (Name forced #using file)" href: ../build/reference/fu-name-forced-hash-using-file.md - name: /Fx (Merge injected code) href: ../build/reference/fx-merge-injected-code.md @@ -556,6 +572,16 @@ 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-enable-architecture-features.md + items: + - name: /feature (ARM64) + href: ../build/reference/feature-arm64.md + - name: /feature (x64) + href: ../build/reference/feature-x64.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) @@ -616,14 +642,20 @@ items: href: ../build/reference/hotpatch-create-hotpatchable-image.md - name: /I (Additional include directories) href: ../build/reference/i-additional-include-directories.md - - name: /interface (treat input file as a module interface unit) + - 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) @@ -690,6 +722,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 @@ -726,12 +760,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) @@ -767,22 +805,30 @@ items: - name: /Zc (Conformance) expanded: false items: - - name: /Zc (Conformance) + - name: "/Zc (Conformance)" href: ../build/reference/zc-conformance.md + - name: "/Zc:__cplusplus (Enable updated __cplusplus macro)" + href: ../build/reference/zc-cplusplus.md + - name: "/Zc:__STDC__ (Enable __STDC__ macro)" + href: ../build/reference/zc-stdc.md - name: "/Zc:alignedNew (C++17 over-aligned allocation)" href: ../build/reference/zc-alignednew.md - name: "/Zc:auto (Deduce variable type)" href: ../build/reference/zc-auto-deduce-variable-type.md - name: "/Zc:char8_t (Enable C++20 char8_t type)" href: ../build/reference/zc-char8-t.md - - name: "/Zc:__cplusplus (Enable updated __cplusplus macro)" - href: ../build/reference/zc-cplusplus.md + - name: "/Zc:checkGwOdr (Enforce Standard C++ ODR violations under /Gw)" + href: ../build/reference/zc-check-gwodr.md + - name: "/Zc:enumTypes (Enable enum type deduction)" + href: ../build/reference/zc-enumtypes.md - name: '/Zc:externC (Use Standard C++ extern "C" rules)' href: ../build/reference/zc-externc.md - name: "/Zc:externConstexpr (Enable extern constexpr variables)" href: ../build/reference/zc-externconstexpr.md - name: "/Zc:forScope (Force conformance in for loop scope)" href: ../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md + - name: "/Zc:gotoScope (Enforce conformance in goto scope)" + href: ../build/reference/zc-gotoscope.md - name: "/Zc:hiddenFriend (Enforce Standard C++ hidden friend rules)" href: ../build/reference/zc-hiddenfriend.md - name: "/Zc:implicitNoexcept (Implicit exception specifiers)" @@ -793,6 +839,8 @@ items: href: ../build/reference/zc-lambda.md - name: "/Zc:noexceptTypes (C++17 noexcept rules)" href: ../build/reference/zc-noexcepttypes.md + - name: "/Zc:nrvo (Control optional NRVO)" + href: ../build/reference/zc-nrvo.md - name: "/Zc:preprocessor (Enable preprocessor conformance mode)" href: ../build/reference/zc-preprocessor.md - name: "/Zc:referenceBinding (Enforce reference binding rules)" @@ -805,18 +853,24 @@ items: href: ../build/reference/zc-static-assert.md - name: "/Zc:strictStrings (Disable string literal type conversion)" href: ../build/reference/zc-strictstrings-disable-string-literal-type-conversion.md + - name: "/Zc:templateScope (Check template parameter shadowing)" + href: ../build/reference/zc-templatescope.md - name: "/Zc:ternary (Enforce conditional operator rules)" href: ../build/reference/zc-ternary.md - - name: "/Zc:threadSafeInit (Thread-safe local static initialization)" + - name: "/Zc:threadSafeInit (Thread-safe local static initialization)" href: ../build/reference/zc-threadsafeinit-thread-safe-local-static-initialization.md - name: "/Zc:throwingNew (Assume operator new throws)" href: ../build/reference/zc-throwingnew-assume-operator-new-throws.md + - name: "/Zc:tlsGuards (Check TLS initialization)" + href: ../build/reference/zc-tlsguards.md - name: "/Zc:trigraphs (Trigraphs substitution)" href: ../build/reference/zc-trigraphs-trigraphs-substitution.md - name: "/Zc:twoPhase- (disable two-phase name lookup)" href: ../build/reference/zc-twophase.md - name: "/Zc:wchar_t (wchar_t is native type)" href: ../build/reference/zc-wchar-t-wchar-t-is-native-type.md + - name: "/Zc:zeroSizeArrayNew (Call member new/delete on arrays)" + href: ../build/reference/zc-zerosizearraynew.md - name: /Zf (Faster PDB generation) href: ../build/reference/zf.md - name: /Zg (Generate function prototypes) @@ -835,6 +889,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 @@ -893,6 +949,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) @@ -965,16 +1023,20 @@ items: href: ../build/reference/ignore-ignore-specific-warnings.md - name: /IGNOREIDL (Don't process attributes into MIDL) href: ../build/reference/ignoreidl-don-t-process-attributes-into-midl.md - - name: /INFERASANLIBS (Use inferred sanitizer libs) - href: ../build/reference/inferasanlibs.md + - name: /ILK (Name incremental database file) + href: ../build/reference/ilk-name-incremental-database-file.md - name: /IMPLIB (Name import library) href: ../build/reference/implib-name-import-library.md - name: /INCLUDE (Force symbol references) href: ../build/reference/include-force-symbol-references.md - name: /INCREMENTAL (Link incrementally) href: ../build/reference/incremental-link-incrementally.md + - name: /INFERASANLIBS (Use inferred sanitizer libs) + href: ../build/reference/inferasanlibs.md - name: /INTEGRITYCHECK (Require signature check) href: ../build/reference/integritycheck-require-signature-check.md + - name: /KERNEL (Create a kernel mode binary) + href: ../build/reference/link-code-for-kernel-mode.md - name: /KEYCONTAINER (Specify a key container to sign an assembly) href: ../build/reference/keycontainer-specify-a-key-container-to-sign-an-assembly.md - name: /KEYFILE (Specify key or key pair to sign an assembly) @@ -985,10 +1047,14 @@ items: href: ../build/reference/libpath-additional-libpath.md - name: /LINKREPRO (Link repro directory name) href: ../build/reference/linkrepro.md + - name: /LINKREPROFULLPATHRSP (Generate file containing absolute paths of linked files) + href: ../build/reference/link-repro-full-path-rsp.md - name: /LINKREPROTARGET (Link repro file name) href: ../build/reference/linkreprotarget.md - name: /LTCG (Link-time code generation) href: ../build/reference/ltcg-link-time-code-generation.md + - name: /LTCGOUT (Name LTCG .iobj file) + href: ../build/reference/ltcgout.md - name: /MACHINE (Specify target platform) href: ../build/reference/machine-specify-target-platform.md - name: /MANIFEST (Create side-by-side assembly manifest) @@ -1017,6 +1083,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) @@ -1047,6 +1115,14 @@ items: href: ../build/reference/section-specify-section-attributes.md - name: /SOURCELINK (Include Sourcelink file in PDB) href: ../build/reference/sourcelink.md + - name: /SPD + href: ../build/reference/spd-specify-sample-profile-database.md + - name: /SPDEMBED + href: ../build/reference/spdembed-embed-sample-profile-database.md + - name: /SPDIN + href: ../build/reference/spdin-use-sample-profile-database.md + - name: /SPGO + href: ../build/reference/spgo-enable-sample-profile-guided-optimization.md - name: /STACK (Stack allocations) href: ../build/reference/stack-stack-allocations.md - name: /STUB (MS-DOS stub file name) @@ -1130,7 +1206,7 @@ items: href: ../build/reference/nmake-reference.md - name: NMAKE projects in Visual Studio href: ../build/reference/creating-a-makefile-project.md - - name: Running NMAKE + - name: Running NMAKE href: ../build/reference/running-nmake.md - name: Makefile contents and features href: ../build/reference/contents-of-a-makefile.md diff --git a/docs/build/troubleshooting-build-customizations.md b/docs/build/troubleshooting-build-customizations.md index a7608815cf8..f97a61e9d37 100644 --- a/docs/build/troubleshooting-build-customizations.md +++ b/docs/build/troubleshooting-build-customizations.md @@ -4,6 +4,7 @@ title: "Troubleshooting Build Customizations" ms.date: "11/04/2016" helpviewer_keywords: ["build events [C++], troubleshooting", "builds [C++], build events", "troubleshooting [C++], builds", "build steps [C++], troubleshooting", "events [C++], build", "builds [C++], troubleshooting", "custom build steps [C++], troubleshooting"] ms.assetid: e4ceb177-fbee-4ed3-a7d7-80f0d78c1d07 +ms.topic: troubleshooting-general --- # Troubleshooting Build Customizations diff --git a/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md b/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md index cef9d627e62..77c17b97ece 100644 --- a/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md +++ b/docs/build/troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md @@ -4,6 +4,7 @@ title: "Troubleshooting C/C++ Isolated Applications and Side-by-side Assemblies" ms.date: "11/04/2016" helpviewer_keywords: ["troubleshooting side-by-side assemblies", "troubleshooting isolated applications", "troubleshooting Visual C++"] ms.assetid: 3257257a-1f0b-4ede-8564-9277a7113a35 +ms.topic: troubleshooting-general --- # Troubleshooting C/C++ Isolated Applications and Side-by-side Assemblies @@ -23,7 +24,7 @@ If your application has no manifest and depends on a DLL that Windows can't find If your application is deployed on a computer that doesn't have Visual Studio, and it crashes with error messages that resemble the previous ones, check these things: -1. Follow the steps that are described in [Understanding the Dependencies of a Visual C++ Application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md). The dependency walker can show most dependencies for an application or DLL. If you observe that some DLLs are missing, install them on the computer on which you are trying to run your application. +1. Follow the steps that are described in [Understanding the Dependencies of a Microsoft C++ Application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md). The dependency walker can show most dependencies for an application or DLL. If you observe that some DLLs are missing, install them on the computer on which you are trying to run your application. 1. The operating system loader uses the application manifest to load assemblies that the application depends on. The manifest can either be embedded in the binary as a resource, or installed as a separate file in the application folder. To check whether the manifest is embedded in the binary, open the binary in Visual Studio and look for RT_MANIFEST in its list of resources. If you can't find an embedded manifest, look in the application folder for a file that's named something like .\.manifest. @@ -40,7 +41,7 @@ If your application is deployed on a computer that doesn't have Visual Studio, a ## Example -Assume we have an application, appl.exe, that's built by using Visual C++. The application manifest either is embedded in appl.exe as the binary resource RT_MANIFEST, which has an ID equal to 1, or is stored as the separate file appl.exe.manifest. The content of this manifest resembles this: +Assume we have an application, appl.exe, that's built using Microsoft C++ Build Tools. The application manifest either is embedded in appl.exe as the binary resource RT_MANIFEST, which has an ID equal to 1, or is stored as the separate file appl.exe.manifest. The content of this manifest resembles this: ``` diff --git a/docs/build/understanding-custom-build-steps-and-build-events.md b/docs/build/understanding-custom-build-steps-and-build-events.md index e468fb7224c..78632dad4e1 100644 --- a/docs/build/understanding-custom-build-steps-and-build-events.md +++ b/docs/build/understanding-custom-build-steps-and-build-events.md @@ -4,10 +4,11 @@ title: "Understanding Custom Build Steps and Build Events" ms.date: "08/29/2019" helpviewer_keywords: ["builds [C++], events", "custom build steps [C++], customizing builds", "events [C++], build", "custom build steps [C++]", "build steps [C++]", "build events [C++], order of events and build steps", "build steps [C++], build events", "builds [C++], custom build steps"] ms.assetid: beb2f017-3e9f-4b2c-9b57-2572fd2628e4 +ms.topic: how-to --- # Understanding Custom Build Steps and Build Events -From within the Visual C++ development environment, there are three basic ways to customize the build process: +Within the C++ development environment, there are three basic ways to customize the build process: - **Custom Build Steps** 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 9caa9820971..0db61f8486a 100644 --- a/docs/build/understanding-manifest-generation-for-c-cpp-programs.md +++ b/docs/build/understanding-manifest-generation-for-c-cpp-programs.md @@ -1,15 +1,15 @@ --- -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 +ms.topic: how-to --- # Understanding manifest generation for C/C++ programs A [manifest](/windows/win32/sbscs/manifests) is an XML document that uniquely identifies an assembly. It contains information used for binding and activation, such as COM classes, interfaces, and type libraries. A manifest can be an external XML file or a resource embedded inside an application or an assembly. The manifest of an [isolated application](/windows/win32/SbsCs/isolated-applications) is used to manage the names and versions of shared side-by-side assemblies the application should bind to at run time. The manifest of a side-by-side assembly specifies its dependencies on names, versions, resources, and other assemblies. -There are two ways to create a manifest for an isolated application or a side-by-side assembly. First, the author of the assembly can manually create a manifest file by following the rules and naming requirements. For more information, see [Manifest files reference](/windows/win32/sbscs/manifest-files-reference). Alternatively, if a program only depends on MSVC assemblies such as CRT, MFC, ATL or others, then the linker can generate a manifest automatically. +There are two ways to create a manifest for an isolated application or a side-by-side assembly. First, the author of the assembly can manually create a manifest file by following the rules and naming requirements. For more information, see [Manifest files reference](/windows/win32/sbscs/manifest-files-reference). Alternatively, if a program only depends on Microsoft C++ (MSVC) assemblies such as CRT, MFC, ATL or others, then the linker can generate a manifest automatically. The headers of MSVC libraries contain assembly information, and when the libraries are included in application code, this assembly information is used by the linker to form a manifest for the final binary. By default, the linker doesn't embed the manifest file inside the binary. Having a manifest as an external file may not work for all scenarios. For example, it's recommended that private assemblies have embedded manifests. In command line builds such as ones that use NMAKE to build code, you can use the [`/MANIFEST:EMBED`](./reference/manifest-create-side-by-side-assembly-manifest.md) linker option to embed the manifest. Alternatively, a manifest can be embedded using the manifest tool. For more information, see [Manifest generation at the command line](#manifest-generation-at-the-command-line). When you build in Visual Studio, a manifest can be embedded by setting a property for the manifest tool in the **Project Properties** dialog, as described in the next section. @@ -29,7 +29,7 @@ The build system in Visual Studio allows the manifest to be embedded in the fina 1. If the manifest embedded in the binary is the same as the manifest generated by the manifest tool, the build continues to the next build steps. -The manifest is embedded inside the final binary as a text resource. You can view it by opening the final binary as a file in Visual Studio. To ensure that the manifest points to the correct libraries, follow the steps described in [Understanding the dependencies of a Visual C++ application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md). Or, follow the suggestions described in the [Troubleshooting](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md) article. +The manifest is embedded inside the final binary as a text resource. You can view it by opening the final binary as a file in Visual Studio. To ensure that the manifest points to the correct libraries, follow the steps described in [Understanding the dependencies of a Microsoft C++ application](../windows/understanding-the-dependencies-of-a-visual-cpp-application.md). Or, follow the suggestions described in the [Troubleshooting](troubleshooting-c-cpp-isolated-applications-and-side-by-side-assemblies.md) article. ## Manifest generation at the command line @@ -181,7 +181,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/use-github-copilot-create-cpp-console-app.md b/docs/build/use-github-copilot-create-cpp-console-app.md new file mode 100644 index 00000000000..ab3637cfa2b --- /dev/null +++ b/docs/build/use-github-copilot-create-cpp-console-app.md @@ -0,0 +1,251 @@ +--- +title: Use AI to create a C++ console application in Visual Studio +description: "Learn how to use GitHub Copilot to create a C++ app using Microsoft C++ in Visual Studio." +ms.date: 10/24/2025 +ms.topic: "tutorial" +ms.collection: ce-skilling-ai-copilot +ms.custom: + - ai-assisted + - copilot-scenario-highlight +ms.update-cycle: 180-days +--- + +# Use AI to create a C++ console application in Visual Studio + +This tutorial shows you how to use GitHub Copilot to quickly create a C++ console application in Visual Studio. You create a console version of Conway's Game of Life, a classic cellular automaton. + +Conway's Game of Life was devised by mathematician John Conway. It consists of a grid of cells that can be either alive or dead. The game evolves automatically based on simple rules and produces complex, evolving patterns that demonstrate how intricate behavior can emerge from basic mathematical rules. + +GitHub Copilot is an AI-powered coding assistant that helps you write code faster, reduce errors, and explore new solutions. Some benefits of using Copilot when coding in C++: +- Generate entire C++ functions or classes as you type. +- Suggest code completions based on plain-language comments or prompts. +- Get help with complex algorithms, data structures, and standard library usage. +- Learn new APIs and modern C++ patterns through in-context examples. +- Receive context-aware suggestions based on your comments or code. +- Debug errors in your code. +- Simplify and refactor existing code. + +## Prerequisites + +- Visual Studio 2022 or later with the **Desktop development with C++** workload installed. +- GitHub Copilot. For more information, see [Get started with GitHub Copilot](/visualstudio/ide/visual-studio-github-copilot-get-started). + +To verify you have the C++ workload installed: +1. Open Visual Studio Installer +1. Select **Modify** next to your Visual Studio installation +1. Ensure **Desktop development with C++** is checked: + + :::image type="content" source="media/desktop-development-cpp-workload.png" alt-text="Screenshot of the Visual Studio Installer with the Workloads tab selected. Desktop development with c++ is selected."::: + +1. If it isn't installed, select it and choose **Modify**. + +For more information about installing Copilot, see [Manage GitHub Copilot installation and state](/visualstudio/ide/visual-studio-github-copilot-install-and-states). + +## Create a 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, create a new project and solution. + +1. Open Visual Studio and select **Create a new project**. +1. Search for "Console App" and select the **Console App** template for C++. + + :::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 is shown with the Console App template selected. The template says: Run code in a windows terminal. Prints hello world by default. Has the tags c++, Windows, and Console. + :::image-end::: + +1. Select **Next**. +1. Set the project name to **Life** and choose the location for the project. +1. Select **Create**. +1. Once the project opens, find the `Life.cpp` file in Solution Explorer. +1. Open `Life.cpp` and delete the default "Hello, World!" code to start with a clean slate. + +## Use Copilot to create an app + +You prompt Copilot by describing the functionality you want. In this section, you'll learn how to prompt Copilot to generate an implementation of Conway's Game of Life. + +1. Open the Copilot chat window by selecting the Copilot icon in the toolbar: + + :::image type="content" source="media/github-copilot-open-chat.png" alt-text="Screenshot of the GitHub icon dropdown. Open Chat Window is selected."::: + +1. In the chat window, enter the following prompt: + ```copilot-prompt + Create a C++ console application that implements Conway's Game of Life. The program should: + - Use a 40x20 grid displayed with asterisks (*) for live cells and spaces for dead cells + - Start with a random initial pattern + - Display each generation for 500ms before showing the next + - Allow the user to press any key to exit the program + - Include proper headers and use standard C++ practices + - Clear the console between generations to provide an animation effect + ``` +1. Copilot generates C++ code for Conway's Game of Life. +1. Copy the generated code and paste it into your empty `Life.cpp` file. +1. Build the project by pressing **F6** or selecting **Build > Build Solution**. +1. Run the program by pressing **F5** or **Ctrl+F5**. + +> [!NOTE] +> The exact code generated by Copilot may vary slightly from run to run and model to model, but the core functionality should be consistent. If the generated code doesn't compile immediately, you can ask Copilot to fix any compilation errors. Copilot is powered by AI, so surprises and mistakes are possible. For more information, see [Copilot FAQs](https://aka.ms/copilot-general-use-faqs). + +### Example of typical generated code structure + +Your generated code will likely include these key components: + +- Headers for console manipulation, random number generation, and timing +- A 2D array or vector to represent the game grid +- Functions to initialize the grid, apply Conway's rules, and display the current state +- A main loop that continues until a key is pressed + +Here's an example of the code that Copilot generated using the previous prompt: + +```cpp +// Code generated by GitHub Copilot +#include +#include +#include +#include // for _kbhit and _getch + +using namespace std; + +int step = 0; +const int rows = 20; +const int cols = 40; + +void printGrid(int grid[rows][cols]) +{ + cout << "Step: " << step << endl; + for (int i = 0; i < rows; ++i) + { + for (int j = 0; j < cols; ++j) + { + cout << (grid[i][j] ? '*' : ' '); + } + cout << endl; + } +} + +int countNeighbors(int grid[rows][cols], int x, int y) +{ + int count = 0; + for (int i = -1; i <= 1; ++i) + { + for (int j = -1; j <= 1; ++j) + { + if (i == 0 && j == 0) + { + continue; + } + + int ni = x + i; + int nj = y + j; + if (ni >= 0 && ni < rows && nj >= 0 && nj < cols) + { + count += grid[ni][nj]; + } + } + } + return count; +} + +void updateGrid(int grid[rows][cols]) +{ + int newGrid[rows][cols] = { 0 }; + for (int i = 0; i < rows; ++i) + { + for (int j = 0; j < cols; ++j) + { + int neighbors = countNeighbors(grid, i, j); + if (grid[i][j] == 1) + { + newGrid[i][j] = (neighbors < 2 || neighbors > 3) ? 0 : 1; + } + else + { + newGrid[i][j] = (neighbors == 3) ? 1 : 0; + } + } + } + // Copy newGrid back to grid + for (int i = 0; i < rows; ++i) + { + for (int j = 0; j < cols; ++j) + { + grid[i][j] = newGrid[i][j]; + } + } +} + +int main() +{ + int grid[rows][cols] = { 0 }; + + // Initial configuration (a simple glider) + grid[1][2] = 1; + grid[2][3] = 1; + grid[3][1] = 1; + grid[3][2] = 1; + grid[3][3] = 1; + + while (true) + { + if (_kbhit()) // Check if a key has been pressed + { + _getch(); // Consume the key + break; // Exit the loop + } + printGrid(grid); + updateGrid(grid); + std::this_thread::sleep_for(std::chrono::milliseconds(100)); + cout << "\033[H\033[J"; // Clear the screen + step++; + } + + return 0; +} +``` +When you run the application, you should see an animated display of Conway's Game of Life with patterns evolving over time. To exit the program, press a key. + +:::image type="content" source="./media/life-exe.png" alt-text="Screenshot of Conway Life running in a command window, displaying the evolving grid of cells."::: + +In the preceding code example, the code generates a warning: `Return value ignored: '_getch'`. You can ask Copilot to fix it. Select the code editor and press **Alt+/** (Windows) to open the Copilot chat, then enter: + +:::image type="content" source="./media/github-copilot-fix-warning.png" alt-text="Screenshot of the Copilot chat window. The text: Fix warning C6031 is in the chat window."::: + +Copilot suggests a fix to handle the return value properly. To accept the changes, select **Tab**: + +:::image type="content" source="./media/github-copilot-fix-warning-accept.png" alt-text="Screenshot of the Copilot proposed changes. Tab to accept. Alt+Del to discard."::: + +Congratulations! You successfully used GitHub Copilot to create a fully functional Conway's Game of Life console application in C++. You learned how to: + +- Craft an effective prompt to generate C++ code +- Use Copilot's chat interface to create an entire application from scratch +- Fix compilation warnings with AI assistance + +## Improve your prompting skills + +For better results with Copilot, see these prompting resources: + +- [GitHub Copilot documentation](https://docs.github.com/en/copilot) - Official best practices and tips +- [OpenAI's GPT best practices](https://platform.openai.com/docs/guides/prompt-engineering) - General AI prompting techniques +- [Copilot prompting guide](https://github.blog/2023-06-20-how-to-write-better-prompts-for-github-copilot/) - Specific guidance for code generation + +## Troubleshooting + +### Missing console app template + +The **New Project** dialog should show a **Console App** template that has **C++**, **Windows**, and **Console** tags. If you don't see it, it might be filtered out of the list, or it might not be installed. First, check the filter dropdowns at the top of the list of templates. Set them to **C++**, **Windows**, and **Console**. The C++ **Console App** template should appear; otherwise, the **Desktop development with C++** workload isn't installed. + +To install **Desktop development with C++**, you can run the installer right from the **Create a new project** dialog. Choose the **Install more tools and features** link at the bottom of the **Create a new project** dialog, beneath the list of templates. 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. + +### Copilot not responding + +- Ensure you have an active GitHub Copilot subscription. +- Try signing out and back into your GitHub account in Visual Studio + +### Generated code doesn't compile + +- Ask Copilot to fix specific compilation errors by pasting the error message into Copilot chat. +- Try refining your prompt to be more specific about what you want the app to do. + +## Next steps + +- [GitHub Copilot in Visual Studio](/visualstudio/ide/visual-studio-github-copilot-install-and-states) +- [GitHub Copilot documentation](https://docs.github.com/en/copilot) - Dive deeper into AI-assisted development +- [Awesome ChatGPT Prompts](https://github.com/f/awesome-chatgpt-prompts) - Community-driven prompting examples for inspiration \ No newline at end of file diff --git a/docs/build/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md b/docs/build/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md index 72f1bb24f21..08d3cbd88f5 100644 --- a/docs/build/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md +++ b/docs/build/using-database-ole-and-sockets-extension-dlls-in-regular-dlls.md @@ -3,6 +3,7 @@ title: "Using Database, OLE, and Sockets MFC extension DLLs in regular MFC DLLs" description: "Shows how to use the Database, OLE, and Sockets MFC extension DLLs in regular MFC DLLs." ms.date: 11/30/2020 helpviewer_keywords: ["DLLs [C++], initializing", "DLLs [C++], extension", "DLLs [C++], regular"] +ms.topic: concept-article --- # Using Database, OLE, and Sockets MFC extension DLLs in regular MFC DLLs diff --git a/docs/build/using-function-name-without-parens-produces-no-code.md b/docs/build/using-function-name-without-parens-produces-no-code.md index 29d218d3c2d..8b08e80798e 100644 --- a/docs/build/using-function-name-without-parens-produces-no-code.md +++ b/docs/build/using-function-name-without-parens-produces-no-code.md @@ -4,6 +4,7 @@ title: "Using Function Name Without () Produces No Code" ms.date: "11/04/2016" helpviewer_keywords: ["functions [C++], without parentheses"] ms.assetid: edf4a177-a160-44aa-8436-e077b5b27809 +ms.topic: concept-article --- # Using Function Name Without () Produces No Code diff --git a/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md b/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md index d7d94003455..36aae3bdec7 100644 --- a/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md +++ b/docs/build/using-the-debug-build-to-check-for-memory-overwrite.md @@ -4,6 +4,7 @@ title: "Using the Debug Build to Check for Memory Overwrite" ms.date: "11/04/2016" helpviewer_keywords: ["memory, overwrites"] ms.assetid: 1345eb4d-24ba-4595-b1cc-2da66986311e +ms.topic: how-to --- # Using the Debug Build to Check for Memory Overwrite diff --git a/docs/build/using-verify-instead-of-assert.md b/docs/build/using-verify-instead-of-assert.md index 225a1f9d07f..f9e9350bc05 100644 --- a/docs/build/using-verify-instead-of-assert.md +++ b/docs/build/using-verify-instead-of-assert.md @@ -4,6 +4,7 @@ title: "Using VERIFY Instead of ASSERT" ms.date: "05/06/2019" helpviewer_keywords: ["ASSERT statements", "debugging [MFC], ASSERT statements", "VERIFY macro", "assertions, troubleshooting ASSERT statements", "debugging assertions", "assertions, debugging"] ms.assetid: 4c46397b-3fb1-49c1-a09b-41a72fae3797 +ms.topic: concept-article --- # Using VERIFY Instead of ASSERT diff --git a/docs/build/vscpp-step-0-installation.md b/docs/build/vscpp-step-0-installation.md index f36a65840b9..903016883ab 100644 --- a/docs/build/vscpp-step-0-installation.md +++ b/docs/build/vscpp-step-0-installation.md @@ -1,30 +1,33 @@ --- 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." -ms.custom: vs-acquisition, intro-installation -ms.date: 11/08/2021 -ms.topic: "tutorial" +description: "Learn how to install Visual Studio with support for Microsoft C and C++ and related workloads." +ms.date: 09/09/2025 +ms.topic: tutorial ms.devlang: "cpp" -ms.assetid: 45138d70-719d-42dc-90d7-1d0ca31a2f54 +ms.custom: + - vs-acquisition + - intro-installation + - sfi-image-nochange + - copilot-scenario-highlight --- # 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 +35,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) + :::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"::: - 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 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,28 +109,43 @@ 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! +### Step 9 - Install GitHub Copilot + +You can use GitHub Copilot in Visual Studio to help with your C++ development. Copilot is an AI-powered coding assistant that helps you write code faster, reduce errors, and explore new solutions. + +Some benefits of using Copilot for your C++ coding scenarios: +- Generate entire C++ functions or classes as you type. +- Suggest code completions based on plain-language comments or prompts. +- Get help with complex algorithms, data structures, and standard library usage. +- Learn new APIs and modern C++ patterns through in-context examples. +- Receive context-aware suggestions based on your comments or code. +- Debug errors in your code. +- Simplify and refactor existing code. + +To try GitHub copilot to create a C++ app, follow the instructions in [Use AI to create a C++ console application in Visual Studio](../build/use-github-copilot-create-cpp-console-app.md). + ::: moniker-end ::: 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 +153,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) - - 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/vs-installer-workloads.png" alt-text="Screenshot of the Visual Studio 2019 installer." lightbox="../get-started/media/vs-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 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. @@ -212,12 +225,10 @@ You can reduce the installation footprint of Visual Studio on your system drive. ### Step 8 - Start developing 1. After Visual Studio installation is complete, choose the **Launch** button to get started developing with Visual Studio. - 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 workloads 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 workload(s) 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 +236,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 +250,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. - - >[!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. 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. -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. +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. - ![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 +280,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 af10d950ea4..1337c29d018 100644 --- a/docs/build/vscpp-step-1-create.md +++ b/docs/build/vscpp-step-1-create.md @@ -1,36 +1,45 @@ --- 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 +ms.custom: + - "mvc" + - sfi-image-nochange --- # 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 +57,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 +71,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 +83,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 +103,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 +111,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 +128,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 +142,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 f77e62bf303..174615c346b 100644 --- a/docs/build/vscpp-step-2-build.md +++ b/docs/build/vscpp-step-2-build.md @@ -1,63 +1,78 @@ --- title: Build and run a C++ console app project -description: "Build and run a Hello World console app in Visual C++" +description: "Build and run a Hello World console app in Microsoft C++" ms.custom: "mvc" -ms.date: 04/20/2020 +ms.date: 06/28/2024 ms.topic: "tutorial" ms.devlang: "cpp" -ms.assetid: 45138d71-719d-42dc-90d7-1d0ca31a2f55 --- # Build and run a C++ console app project -You've created a C++ console app project and entered your code. Now you can build and run it within Visual Studio. Then, run it as a stand-alone app from the command line. +In [Create a C++ console app project](vscpp-step-1-create.md) you created a C++ console app project and entered your code. Now you can build and run it within Visual Studio. Then, run it as a stand-alone app from the command line. ## Prerequisites -- Have Visual Studio with the Desktop development with C++ workload installed and running on your computer. If it's not installed yet, follow the steps in [Install C++ support in Visual Studio](vscpp-step-0-installation.md). - -- Create a "Hello, World!" project and enter its source code. If you haven't done this step yet, follow the steps in [Create a C++ console app project](vscpp-step-1-create.md). +- Have Visual Studio with the Desktop development with C++ workload installed and running on your computer. If it's not installed, follow the steps in [Install C++ support in Visual Studio](vscpp-step-0-installation.md). +- Create a "Hello, World!" project. By default, it contains code to print `Hello World!`. If you haven't done this step yet, follow the steps in [Create a C++ console app project](vscpp-step-1-create.md). If Visual Studio looks like this, you're ready to build and run your app: - ![Screenshot of Visual Studio showing the Hello World source code in the editor.](media/vscpp-ready-to-build.png "Ready to build the new project") + :::image type="complex" source="media/vscpp-ready-to-build.png" alt-text="Screenshot of the Hello World source code in the Visual Studio editor."::: + The source consists of #include \ and a main function that does std::cout hello world and returns 0 from the function. + :::image-end::: ## Build and run your code in Visual Studio -1. To build your project, choose **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. +1. To build your project, from the main menu choose **Build** > **Build Solution**. The **Output** window shows the results of the build process. - ![View of the sequence of actions you take to build the project.](media/vscpp-build-solution.gif "Build the project") + :::image type="complex" source="media/vscpp-build-solution.gif" alt-text="Animated screenshot showing the sequence of actions taken to build a project in Visual Studio."::: + First, Build is selected from the main menu. Then Build Solution is selected. The Output window shows the build output messages, including that the build is successful. + :::image-end::: 1. To run the code, on the menu bar, choose **Debug**, **Start without debugging**. - ![View of the actions you take to start the project.](media/vscpp-start-without-debugging.gif "Start the project") + :::image type="complex" source="media/vscpp-start-without-debugging.gif" alt-text="Video showing the actions taken to start a project in Visual Studio."::: + First, Debug is selected from the main menu. Then 'Start without debugging' is selected. A console window appears with the output of the program: Hello, World! + :::image-end::: A console window opens and then runs your app. When you start a console app in Visual Studio, it runs your code, then prints "Press any key to continue . . ." to give you a chance to see the output. -Congratulations! You've created your first "Hello, world!" console app in Visual Studio! Press a key to dismiss the console window and return to Visual Studio. +Congratulations! You created your first "Hello, world!" console app in Visual Studio! Press a key to dismiss the console window and return to Visual Studio. [I ran into a problem.](#build-and-run-your-code-in-visual-studio-issues) ## Run your code in a command window -Normally, you run console apps at the command prompt, not in Visual Studio. Once your app is built by Visual Studio, you can run it from any command window. Here's how to find and run your new app in a command prompt window. +Normally, you run console apps at the command prompt, not in Visual Studio. Once Visual Studio builds your app, you can run it from a command window. Here's how to find and run your new app in a command prompt window. 1. In **Solution Explorer**, select the HelloWorld solution (not the HelloWorld project) and right-click to open the context menu. Choose **Open Folder in File Explorer** to open a **File Explorer** window in the HelloWorld solution folder. -1. In the **File Explorer** window, open the Debug folder. This folder contains your app, *HelloWorld.exe*, and a couple of other debugging files. Hold down the **Shift** key and right-click on *HelloWorld.exe* to open the context menu. Choose **Copy as path** to copy the path to your app to the clipboard. +::: moniker range=" **Options** > **CMake** > **General**. Select **Prefer using CMake Presets for configure, build, and test**, then select **OK**. Instead, you could have added a `CMakePresets.json` file to the root of the project. For more information, see [Enable CMake Presets integration](cmake-presets-vs.md#-enable--cmakepresetsjson-integration-in-visual-studio). +1. Enable Visual Studio's CMake Presets integration. Select **Tools** > **Options** > **CMake** > **General**. Select **Prefer using CMake Presets for configure, build, and test**, then select **OK**. Alternatively, you could add a `CMakePresets.json` file to the root of the project. For more information, see [Enable CMake Presets integration](cmake-presets-vs.md#enable-cmakepresets-json-integration). - ![Screenshot of CMake general options screen with Prefer using CMake Presets for configure, build, and test highlighted and selected](media/cmake-general-prefer-cmake-presets.png) + :::image type="complex" source="media/cmake-general-prefer-cmake-presets.png" alt-text="Screenshot of the Visual Studio project options. Cmake > General is selected."::: + In the CMake configuration file group, 'Use CMake Presets if available, otherwise use CMakeSettings.json' is called out and is selected. + :::image-end::: -6. To activate the integration: from the main menu, select **File** > **Close Folder**. The **Get started** page appears. Under **Open recent**, select the folder you just closed to reopen the folder. +1. 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**. +1. There are three dropdowns across the Visual Studio main menu bar. Use the dropdown on the left to select your active target system. This is the system where CMake is invoked to configure and build the project. Visual Studio queries for WSL installations with `wsl -l -v`. In the following image, **WSL2: Ubuntu-20.04** is shown selected as the **Target System**. - ![Target system dropdown displaying WSL2: Ubuntu-20.04 as being selected](media/vs2022-target-system-dropdown.png) + :::image type="content" source="media/vs2022-target-system-dropdown.png" alt-text="Screenshot of the Visual Studio target system dropdown. WSL2: Ubuntu-20.04 is the selected."::: > [!NOTE] - > If Visual Studio starts to configure your project automatically, read step 11 to manage CMake binary deployment, and then continue to the step below. To customize this behavior, see [Modify automatic configuration and cache notifications](cmake-presets-vs.md#modify-automatic-configuration-and-cache-notifications). + > If Visual Studio starts to configure your project automatically, read step 11 to manage CMake binary deployment, and then continue to the following step. 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). +1. 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). +1. 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* +1. 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. +1. 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. +1. 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. +1. 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: +1. 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: +1. Select **Debug** > **Start**, or press **F5**. Your project builds, the executable launches on your WSL 2 distro, and Visual Studio halts execution at the breakpoint. The output of your program (in this case, `"Hello CMake."`) is visible in the Linux Console Window: - ![Linux console window, displaying the text "Hello Cmake." Also shows the sample program with a breakpoint on the line following cout << "Hello CMake."](media/walkthrough-build-debug-wsl2-breakpoint.png) + :::image type="complex" source="media/walkthrough-build-debug-wsl2-breakpoint.png" alt-text="Screenshot of a running hello world program."::: + The Visual Studio Linux console window displays the output of the program: 'Hello C Make.' The editor window shows the hello world program. Execution stopped at a breakpoint on the line that says return 0;." + :::image-end::: You've now built and debugged a C++ app with WSL 2 and Visual Studio 2022. ## Advanced WSL 2 and CMake projects considerations -Visual Studio only provides native support for WSL 2 for CMake projects that use `CMakePresets.json` as the active configuration file. To migrate from `CMakeSettings.json` to `CMakePresets.json`, see [Enable CMake Presets integration in Visual Studio](cmake-presets-vs.md#-enable--cmakepresetsjson-integration-in-visual-studio). +Visual Studio only provides native support for WSL 2 for CMake projects that use `CMakePresets.json` as the active configuration file. To migrate from `CMakeSettings.json` to `CMakePresets.json`, see [Enable CMake Presets integration in Visual Studio](cmake-presets-vs.md#enable-cmakepresets-json-integration). If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in the Visual Studio Remote Settings vendor map in `CMakePresets.json`, set **forceWSL1Toolset** to **true** . For more information, see [Visual Studio Remote Settings vendor map](cmake-presets-json-reference.md#visual-studio-remote-settings-vendor-map). -If **forceWSL1Tooslet** is set to **true**, then Visual Studio won't maintain a copy of your source files in the WSL file system. Instead, it will access source files in the mounted Windows drive (`/mnt/`…). +If **forceWSL1Tooslet** is set to **true**, then Visual Studio doesn't maintain a copy of your source files in the WSL file system. Instead, it accesses source files in the mounted Windows drive (`/mnt/`…). -In most cases, it’s best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are instead stored in the Windows file system. To learn more about file system performance in WSL 2, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). +In most cases, it's best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are instead stored in the Windows file system. To learn more about file system performance in WSL 2, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). -Specify advanced settings such as the path to the directory on WSL 2 where the project will be copied, copy source options, and rsync command arguments, in the Visual Studio Remote Settings vendor map in `CMakePresets.json`. 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`. @@ -118,13 +126,17 @@ You can change the IntelliSense mode, or specify other IntelliSense options, in ## WSL 2 and MSBuild-based Linux projects -CMake is recommended for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems. If you're already using a MSBuild-based Linux project, then you can upgrade to the WSL 2 toolset in Visual Studio via **Property pages** > **General** > **Platform Toolset**: +CMake is recommended for all C++ cross-platform development with Visual Studio because it allows you to build and debug the same project on Windows, WSL, and remote systems. -![A screenshot of a dropdown with Platform Toolset selected, and to the right, another dropdown with WSL2 Toolset selected](media/wsl-platform-toolset-selection.png) +But you may have a MSBuild-based Linux project. -If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in **Property Pages** > **General** > **Platform Toolset**, select the **GCC for Windows Subsystem for Linux** or **Clang for Windows Subsystem for Linux** toolset. If either of these toolsets are selected, Visual Studio won't maintain a copy of your source files in the WSL file system and will instead access source files over the mounted Windows drive (`/mnt/`…). System headers are still automatically copied to the Windows file system to provide a native IntelliSense experience. Customize the headers that are included or excluded from this copy in **Property Pages** > **General**. +If you have a MSBuild-based Linux project, then you can upgrade to the WSL 2 toolset in Visual Studio. Right-click the project in the solution explorer, then choose **Properties** > **General** > **Platform Toolset**: -In most cases, it’s best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are stored in the Windows file system. To to learn more, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). +:::image type="content" source="media/wsl-platform-toolset-selection.png" alt-text="Screenshot of a Visual Studio dropdown with Platform Toolset selected, and to the right, another dropdown with WSL2 Toolset selected."::: + +If you're targeting a WSL 2 distribution and you don't want to use the WSL 2 toolset, then in the **Platform Toolset** dropdown, select the **GCC for Windows Subsystem for Linux** or **Clang for Windows Subsystem for Linux** toolset. If either of these toolsets are selected, Visual Studio doesn't maintain a copy of your source files in the WSL file system, and instead accesses source files over the mounted Windows drive (`/mnt/`…). System headers are still automatically copied to the Windows file system to provide a native IntelliSense experience. Customize the headers that are included or excluded from this copy in **Property Pages** > **General**. + +In most cases, it's best to use the WSL 2 toolset with WSL 2 distributions because WSL 2 is slower when project files are stored in the Windows file system. To learn more, see [Comparing WSL 1 and WSL 2](/windows/wsl/compare-versions). ## See also diff --git a/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md b/docs/build/walkthrough-compile-a-c-program-on-the-command-line.md index 1edfba8ac35..ab7d92e680f 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,37 @@ --- -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 +ms.topic: how-to --- # 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++ (MSVC) Build Tools contains 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 +39,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 +47,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 +55,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 +71,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 +122,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 +138,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 +152,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 +164,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 6e37f2a46ca..f450214e366 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 @@ -6,7 +6,7 @@ ms.assetid: cef41c88-faf9-439d-8423-25aa3f5674dd --- # Walkthrough: Compiling a C++/CLI Program on the Command Line -You can create Visual C++ programs that target the Common Language Runtime (CLR) and use the .NET Framework, and build them on the command line. Visual C++ supports the C++/CLI programming language, which has additional types and operators to target the .NET programming model. For general information about the C++/CLI language, see [.NET Programming with C++/CLI (Visual C++)](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md). +You can create Microsoft C++ programs that target the Common Language Runtime (CLR) and use the .NET Framework, and build them on the command line. Microsoft C++ supports the C++/CLI programming language, which has additional types and operators to target the .NET programming model. For general information about the C++/CLI language, see [.NET Programming with C++/CLI (Visual C++)](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md). In this walkthrough, you use a text editor to create a basic C++/CLI program, and then compile it on the command line. (You can use your own C++/CLI program instead of typing the one that's shown, or you can use a C++/CLI code sample from another help article. This technique is useful for building and testing small modules that have no UI elements.) @@ -18,7 +18,7 @@ You understand the fundamentals of the C++ language. The following steps show how to compile a C++/CLI console application that uses .NET Framework classes. -To enable compilation for C++/CLI, you must use the [/clr](reference/clr-common-language-runtime-compilation.md) compiler option. The MSVC compiler generates an .exe file that contains MSIL code—or mixed MSIL and native code—and links to the required .NET Framework libraries. +To enable compilation for C++/CLI, you must use the [/clr](reference/clr-common-language-runtime-compilation.md) compiler option. The Microsoft C++ (MSVC) compiler generates an .exe file that contains MSIL code—or mixed MSIL and native code—and links to the required .NET Framework libraries. ### To compile a C++/CLI application on the command line @@ -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. @@ -41,7 +43,7 @@ To enable compilation for C++/CLI, you must use the [/clr](reference/clr-common- 1. On the menu bar, choose **File** > **Save**. - You've created a Visual C++ source file that uses a .NET Framework class () in the namespace. + You've created a C++ source file that uses a .NET Framework class () in the namespace. 1. At the command prompt, enter `cl /clr basicclr.cpp`. The cl.exe compiler compiles the source code into an .obj file that contains MSIL, and then runs the linker to generate an executable program named basicclr.exe. 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 474a424a2d3..8ab636443f2 100644 --- a/docs/build/walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md +++ b/docs/build/walkthrough-compiling-a-cpp-cx-program-on-the-command-line.md @@ -26,9 +26,11 @@ To enable compilation for C++/CX, you must use the [/ZW](reference/zw-windows-ru #### To compile a C++/CX application on the command line -1. Open a **Developer Command Prompt** window. (On the **Start** window, open **Apps**. Open the **Visual Studio Tools** folder under your version of Visual Studio, and then choose the **Developer Command Prompt** shortcut.) For more information about how to open a Developer Command Prompt window, see [Use the MSVC toolset from the command line](building-on-the-command-line.md). +1. Open a **Developer Command Prompt** window. For specific instructions, see [To open a developer command prompt window](building-on-the-command-line.md#developer_command_prompt). - Administrator credentials may be required to successfully compile the code, depending on the computer's operating system and configuration. To run the Command Prompt window as an administrator, open the shortcut menu for **Developer Command Prompt** and then choose **Run as administrator**. + Administrator credentials may be required to successfully compile the code, depending on the computer's operating system and configuration. To run the command prompt window as an administrator, right-click to open the shortcut menu for the command prompt and then choose **More** > **Run as administrator**. + +1. Change the current working directory in the command prompt window to a directory you can write to, such as your Documents directory. 1. At the command prompt, enter **notepad basiccx.cpp**. @@ -49,7 +51,7 @@ To enable compilation for C++/CX, you must use the [/ZW](reference/zw-windows-ru You've created a C++ source file that uses the Windows Runtime [Platform namespace](../cppcx/platform-namespace-c-cx.md) namespace. -1. At the command prompt, enter **cl /EHsc /ZW basiccx.cpp /link /SUBSYSTEM:CONSOLE**. The cl.exe compiler compiles the source code into an .obj file, and then runs the linker to generate an executable program named basiccx.exe. (The [/EHsc](reference/eh-exception-handling-model.md) compiler option specifies the C++ exception-handling model, and the [/link](reference/link-pass-options-to-linker.md) flag specifies a console application.) +1. At the command prompt, enter `cl /EHsc /ZW basiccx.cpp /link /SUBSYSTEM:CONSOLE`. The `cl.exe` compiler compiles the source code into an `.obj` file, and then runs the linker to generate an executable program named basiccx.exe. The [/EHsc](reference/eh-exception-handling-model.md) compiler option specifies the C++ exception-handling model, and the [/link](reference/link-pass-options-to-linker.md) flag specifies a console application. 1. To run the basiccx.exe program, at the command prompt, enter **basiccx**. diff --git a/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md b/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md index 5cd2502e96e..f2bf932a35e 100644 --- a/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md +++ b/docs/build/walkthrough-compiling-a-native-cpp-program-on-the-command-line.md @@ -22,7 +22,7 @@ Visual Studio is an *integrated development environment* (IDE). It supports a fu The Build Tools for Visual Studio installs only the command-line 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 tools, look for Build Tools for Visual Studio on the [Visual Studio Downloads](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) page. -Before you can build a C or C++ program on the command line, verify that the tools are installed, and you can access them from the command line. Visual C++ has complex requirements for the command-line environment to find the tools, headers, and libraries it uses. **You can't use Visual C++ in a plain command prompt window** without doing some preparation. Fortunately, Visual C++ installs shortcuts for you to launch a developer command prompt that has the environment set up for command line builds. Unfortunately, the names of the developer command prompt shortcuts and where they're located are different in almost every version of Visual C++ and on different versions of Windows. Your first walkthrough task is finding the right one to use. +Before you can build a C or C++ program on the command line, verify that the tools are installed, and you can access them from the command line. Microsoft C++ (MSVC) has complex requirements for the command-line environment to find the tools, headers, and libraries it uses. **You can't use Microsoft C++ in a plain command prompt window** without doing some preparation. Fortunately, Microsoft C++ installs shortcuts for you to launch a developer command prompt that has 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 finding the right one 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. You must set these environment values yourself if you use a regular **Command Prompt** window. For more information, see [Use the MSVC toolset from the command line](./building-on-the-command-line.md). We recommend you use a developer command prompt shortcut instead of building your own. @@ -31,11 +31,11 @@ Before you can build a C or C++ program on the command line, verify that the too 1. If you have installed Visual Studio 2017 or later on Windows 10 or later, open the Start menu and choose **All apps**. Scroll down and open the **Visual Studio** folder (not the Visual Studio application). Choose **Developer Command Prompt for VS** to open the command prompt window. - If you have installed Microsoft Visual C++ Build Tools 2015 on Windows 10 or later, open the **Start** menu and choose **All apps**. 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 have installed Microsoft Visual Studio Build Tools 2015 on Windows 10 or later, open the **Start** menu and choose **All apps**. Scroll down and open the **Visual Studio Build Tools** folder. Choose **x86 Native Tools Command Prompt** to open the command prompt window. 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. -1. Next, verify that the Visual C++ developer command prompt is set up correctly. In the command prompt window, enter `cl` and verify that the output looks something like this: +1. Next, verify that the C++ developer command prompt is set up correctly. In the command prompt window, enter `cl` and verify that the output looks something like this: ```Output C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise>cl @@ -45,17 +45,17 @@ Before you can build a C or C++ program on the command line, verify that the too usage: cl [ option... ] filename... [ /link linkoption... ] ``` - There may be differences in the current directory or version numbers. These values depend on the version of Visual C++ and any updates installed. If the above output is similar to what you see, then you're ready to build C or C++ programs at the command line. + There may be differences in the current directory or version numbers. These values depend on the version of MSVC 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. > [!NOTE] - > If you get an error such as "'cl' is not recognized as an internal or external command, operable program or batch file," error C1034, or error LNK1104 when you run the **`cl`** command, then either you are not using a developer command prompt, or something is wrong with your installation of Visual C++. You must fix this issue before you can continue. + > If you get an error such as "'cl' is not recognized as an internal or external command, operable program or batch file," error C1034, or error LNK1104 when you run the **`cl`** command, then either you are not using a developer command prompt, or something is wrong with your installation of MSVC. You must fix this issue before you can continue. - If you can't find the developer command prompt shortcut, or if you get an error message when you enter `cl`, then your Visual C++ installation may have a problem. Try reinstalling the Visual C++ component in Visual Studio, or reinstall the Microsoft Visual C++ Build Tools. Don't go on to the next section until the **`cl`** command works. For more information about installing and troubleshooting Visual C++, 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 MSVC installation may have a problem. Try reinstalling the MSVC component in Visual Studio or Visual Studio Build Tools. Don't go on to the next section until the **`cl`** command works. For more information about installing and troubleshooting MSVC, 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. -### Create a Visual C++ source file and compile it on the command line +### Create a C++ source file and compile it on the command line 1. In the developer command prompt window, enter `md c:\hello` to create a directory, and then enter `cd c:\hello` to change to that directory. This directory is where both your source file and the compiled program get created. @@ -70,7 +70,7 @@ Before you can build a C or C++ program on the command line, verify that the too using namespace std; int main() { - cout << "Hello, world, from Visual C++!" << endl; + cout << "Hello, world, from Microsoft C++!" << endl; } ``` @@ -130,7 +130,7 @@ Before you can build a C or C++ program on the command line, verify that the too The program displays this text and exits: ```Output - Hello, world, from Visual C++! + Hello, world, from Microsoft C++! ``` Congratulations, you've compiled and run a C++ program by using the command-line tools. 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 0228b1f0475..ac858bc073f 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,56 @@ --- -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"] +ms.custom: sfi-image-nochange --- -# 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 +61,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 +81,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 +93,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 +111,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 +135,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 +192,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 +263,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 +326,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 +377,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 +395,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 +409,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 +427,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 +435,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 +467,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 +495,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 +549,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,14 +565,14 @@ 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. Now that you've created a DLL and a client application, you can experiment. Try setting breakpoints in the code of the client app, and run the app in the debugger. See what happens when you step into a library call. Add other functions to the library, or write another client app that uses your DLL. -When you deploy your app, you must also deploy the DLLs it uses. The simplest way to make the DLLs that you build, or that you include from third parties, available is to put them in the same directory as your app. It's known as *app-local deployment*. For more information about deployment, see [Deployment in Visual C++](../windows/deployment-in-visual-cpp.md). +When you deploy your app, you must also deploy the DLLs it uses. The simplest way to make the DLLs that you build, or that you include from third parties, available is to put them in the same directory as your app. It's known as *app-local deployment*. For more information about deployment, see [Deployment in Microsoft C++](../windows/deployment-in-visual-cpp.md). ## 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 d8f66d6f61a..6ca15699093 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 8c22eaaa39e..4e7de18c974 100644 --- a/docs/build/walkthrough-header-units.md +++ b/docs/build/walkthrough-header-units.md @@ -1,19 +1,21 @@ --- description: "Learn more about C++ header units. Convert a header file to a header unit using Visual Studio 2022." -title: "Walkthrough: Build and import header units in Visual C++ projects" -ms.date: 05/12/2022 +title: "Walkthrough: Build and import header units in Microsoft C++ projects" +ms.date: 09/29/2022 ms.custom: "conceptual" author: "tylermsft" ms.author: "twhitney" helpviewer_keywords: ["import", "header unit", "ifc"] +monikerRange: '>=msvc-160' --- -# Walkthrough: Build and import header units in Microsoft Visual C++ +# Walkthrough: Build and import header units in Microsoft C++ -This article is about building and importing header units with Visual Studio 2022. To learn how to import Standard Template Library headers as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md). +This article is about building and importing header units with Visual Studio 2022. To learn how to import C++ standard library headers as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md). For an even faster and more robust way to import the standard library, see [Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md). Header units are the recommended alternative to [precompiled header files](creating-precompiled-header-files.md) (PCH). Header units are easier to set up and use, are significantly smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio). +To contrast header units with other ways to include functionality in your programs, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md). ## Prerequisites To use header units, you need Visual Studio 2019 16.10 or later. @@ -22,35 +24,35 @@ To use header units, you need Visual Studio 2019 16.10 or later. A header unit is a binary representation of a header file. A header unit ends with an *`.ifc`* extension. The same format is used for named modules. -An important difference between a header unit and a header file is that a header unit isn't affected by macro definitions outside of the header unit. That is, you can't `#define` a symbol that causes the header unit to behave differently. By the time you import the header unit, the header unit is already compiled. This is different than how an `#include` file is treated because the included file can be affected by a macro definition outside of the header file. This is because the header file isn't compiled yet. It will go through the preprocessor when the source file that includes it is compiled. +An important difference between a header unit and a header file is that a header unit isn't affected by macro definitions outside of the header unit. That is, you can't define a preprocessor symbol that causes the header unit to behave differently. By the time you import the header unit, the header unit is already compiled. That's different from how an `#include` file is treated. An included file can be affected by a macro definition outside of the header file because the header file goes through the preprocessor when you compile the source file that includes it. -Header units can be imported in any order. This isn't true of header files because macro definitions defined in one header file might affect a subsequent header file. Macro definitions in one header unit can't affect another header unit. +Header units can be imported in any order, which isn't true of header files. Header file order matters because macro definitions defined in one header file might affect a subsequent header file. Macro definitions in one header unit can't affect another header unit. Everything visible from a header file is also visible from a header unit, including macros defined within the header unit. -A header file must be translated into a header unit before it can be imported. An advantage of header units over PCH is that they can be used in distributed builds. For example, as long as you compile the *`.ifc`* and the program that imports it with the same compiler, and target the same platform and architecture, a header unit produced on one computer can be consumed on another. Unlike a PCH, when a header unit changes only it and what depends on it rebuild. Header units can be up to a magnitude smaller in size than a traditional `.pch`. +A header file must be translated into a header unit before it can be imported. An advantage of header units over precompiled header files (PCH) is that they can be used in distributed builds. As long as you compile the *`.ifc`* and the program that imports it with the same compiler, and target the same platform and architecture, a header unit produced on one computer can be consumed on another. Unlike a PCH, when a header unit changes, only it and what depends on it are rebuilt. Header units can be up to an order of magnitude smaller in size than a `.pch`. -Header units impose fewer constraints on the parity of compiler switches used to create the header unit and to compile the code that consumes it than a PCH does. However, some switch combinations and macro definitions might create one definition rule (ODR) violations between various translation units. +Header units impose fewer constraints on the required similarities of compiler switch combinations used to create the header unit and to compile the code that consumes it than a PCH does. However, some switch combinations and macro definitions might create violations of the one definition rule (ODR) between various translation units. Finally, header units are more flexible than a PCH. With a PCH, you can't choose to bring in only one of the headers in the PCH--the compiler processes all of them. With header units, even when you compile them together into a static library, you only bring the contents of the header unit you import into your application. -Header units are a step 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 without affecting each other. And the compiler can process them faster than header files. But they don't have all of the advantages of modules because they expose the macros defined within them (modules don't) and unlike modules there's no way to hide private implementation. 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 PCH implementation with header units. You get the same speed advantage, but other code hygiene and flexibility benefits as well. +Consider replacing your precompiled headers with header units. You get the same speed advantage, but with other code hygiene and flexibility benefits as well. ## Ways to compile a header unit There are several ways to compile a file into a header unit: -- **Choose individual files to translate into header units**. This approach gives you file-by-file control over what is treated as a header unit. It's also useful when you must compile a file as a header unit that, because it doesn't have the default extension (`.ixx`, `.cppm`, `.h`, `.hpp`), wouldn't normally be compiled into a header unit. This approach is demonstrated in this walkthrough. To get started, see [Approach 1: Choose individual header units to build](#approach1). +- **Build a shared header unit project**. We recommend this approach because it provides more control over the organization and reuse of the imported header units. Create a static library project that contains the header units that you want, and then reference it to import the header units. For a walkthrough of this approach, see [Build a header unit static library project for header units](walkthrough-import-stl-header-units.md#approach2). -- **Build a shared header unit project**. This is the recommended approach and provides more control over the organization and reuse of the imported header units. Create a static library project that contains the header units that you want and then reference it to import the header units. For a walkthrough of this approach, see [Build a header unit static library project for header units](walkthrough-import-stl-header-units.md#approach2). +- **Choose individual files to translate into header units**. This approach gives you file-by-file control over what is treated as a header unit. It's also useful when you must compile a file as a header unit that, because it doesn't have the default extension (`.ixx`, `.cppm`, `.h`, `.hpp`), wouldn't normally be compiled into a header unit. This approach is demonstrated in this walkthrough. To get started, see [Approach 1: Translate a specific file into a header unit](#approach1). - **Automatically scan for and build header units**. This approach is convenient, but is best suited to smaller projects because it doesn't guarantee optimal build throughput. For details about this approach, see [Approach 2: Automatically scan for header units](#approach2). -- As mentioned in the introduction, you can build and import STL header files as header units and automatically treat `#include` for STL library headers as `import` without rewriting your code. To see how, visit [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md). +- As mentioned in the introduction, you can build and import STL header files as header units, and automatically treat `#include` for STL library headers as `import` without rewriting your code. To see how, visit [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md). -## Approach 1: Choose header units to build +## Approach 1: Translate a specific file into a header unit This section shows how to choose a specific file to translate into a header unit. Compile a header file as a header unit using the following steps in Visual Studio: @@ -84,7 +86,7 @@ This section shows how to choose a specific file to translate into a header unit ### Set project properties -To enable header units, first set the **C++ Language Standard** to [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later by using the following steps: +To enable header units, first set the **C++ Language Standard** to [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later with the following steps: 1. In **Solution Explorer**, right-click the project name and choose **Properties**. 1. In the left pane of the project property pages window, select **Configuration Properties** > **General**. @@ -97,32 +99,32 @@ Compile the header file as a header unit: :::image type="content" source="media/change-item-type.png" alt-text="Screenshot that shows changing the item type to C/C++ compiler."::: -Later in this walkthrough, when you build this project, `Pythagorean.h` will be translated into a header unit. That's because the item type for this header file is set to **C/C++ compiler**, and because the default action for `.h` and `.hpp` files set this way is to translate the file into a header unit. +When you build this project later in this walkthrough, `Pythagorean.h` will be translated into a header unit. It's translated into a header unit because the item type for this header file is set to **C/C++ compiler**, and because the default action for `.h` and `.hpp` files set this way is to translate the file into a header unit. > [!NOTE] > This isn't required for this walkthrough, but is provided for your information. To compile a file as a header unit that doesn't have a default header unit file extension, like `.cpp` for example, set **Configuration properties** > **C/C++** > **Advanced** > **Compile As** to **Compile as C++ Header Unit (/exportHeader)**: > :::image type="content" source="media/change-compile-as.png" alt-text="Screenshot that shows changing Configuration properties > C/C++ > Advanced > Compile As to Compile as C++ Header Unit (/exportHeader)."::: -### Change your code to import a header unit +### Change your code to import the header unit -1. In the source file for the example project, change `#include "Pythagorean.h"` to `import "Pythagorean.h";` Don't forget the trailing semicolon that's required for `import` statements. Because it's a header file in a directory local to the project, we used quotes with the `import` statement, that is: `import "file";` In your own projects, to compile a header unit from a system header, use angle brackets: `import ;` +1. In the source file for the example project, change `#include "Pythagorean.h"` to `import "Pythagorean.h";` Don't forget the trailing semicolon. It's required for `import` statements. Because it's a header file in a directory local to the project, we used quotes with the `import` statement: `import "file";`. In your own projects, to compile a header unit from a system header, use angle brackets: `import ;` 1. Build the solution by selecting **Build** > **Build Solution** on the main menu. Run it to see that it produces the expected output: `Pythagorean triple a:2 b:3 c:13` In your own projects, repeat this process to compile the header files you want to import as header units. -If you want to convert only a few header files to header units, this approach is good. But if you have many header files that you want to compile, and the convenience of having the build system automatically handle it outweighs the potential impact on build performance, see the following section. +If you want to convert only a few header files to header units, this approach is good. But if you have many header files that you want to compile, and the potential loss of build performance is outweighed by the convenience of having the build system handle them automatically, see the following section. If you're interested in specifically importing STL library headers as header units, see [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1). ## Approach 2: Automatically scan for and build header units -Due to scanning all of your source files to find and build header units, this approach is best suited for smaller projects because it doesn't guarantee optimal build throughput. +Because it takes time to scan all of your source files for header units, and time to build them, the following approach is best suited for smaller projects. It doesn't guarantee optimal build throughput. This approach combines two Visual Studio project settings: -- **Scan Sources for Module Dependencies** causes the build system to call the compiler to ensure that all imported modules and header units are built before compiling the files that depend on them. When combined with **Translate Includes to Imports**, header files included in your source, that are also specified in a [`header-units.json`](./reference/header-unit-json-reference.md) file in the same directory as the header file, are compiled into header units. -- **Translate Includes to Imports** treats a header file as an `import` if the `#include` refers to a header file that can be compiled as a header unit (as specified in a `header-units.json` file), and a compiled header unit is available for the header file. Otherwise, the header file is treated as a normal `#include`. The [`header-units.json`](./reference/header-unit-json-reference.md) file is used to automatically build header units for each `#include` without symbol duplication. +- **Scan Sources for Module Dependencies** causes the build system to call the compiler to ensure that all imported modules and header units are built before compiling the files that depend on them. When combined with **Translate Includes to Imports**, any header files included in your source that are also specified in a [`header-units.json`](./reference/header-unit-json-reference.md) file located in the same directory as the header file, are compiled into header units. +- **Translate Includes to Imports** treats a header file as an `import` if the `#include` refers to a header file that can be compiled as a header unit (as specified in a `header-units.json` file), and a compiled header unit is available for the header file. Otherwise, the header file is treated as a normal `#include`. The [`header-units.json`](./reference/header-unit-json-reference.md) file is used to automatically build header units for each `#include`, without symbol duplication. You can turn on these settings in the properties for your project. To do so, right-click the project in the **Solution Explorer** and choose **Properties**. Then choose **Configuration Properties** > **C/C++** > **General**. @@ -132,7 +134,7 @@ You can turn on these settings in the properties for your project. To do so, rig These settings work together to automatically build and import header units under these conditions: -- **Scan Sources for Module Dependencies** scans your sources for files, and their dependencies, that can be treated as header units. Files that have the extension `.ixx`, and those which have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/export)**, are always scanned regardless of this setting. The compiler also looks for `import` statements to identify header unit dependencies. If `/translateInclude` is specified, the compiler also scans for `#include` directives that are also specified in a `header-units.json` file to treat as header units. A dependency graph is built of all the modules and header units in your project. +- **Scan Sources for Module Dependencies** scans your sources for the files and their dependencies that can be treated as header units. Files that have the extension `.ixx`, and files that have their **File properties** > **C/C++** > **Compile As** property set to **Compile as C++ Header Unit (/export)**, are always scanned regardless of this setting. The compiler also looks for `import` statements to identify header unit dependencies. If `/translateInclude` is specified, the compiler also scans for `#include` directives that are also specified in a `header-units.json` file to treat as header units. A dependency graph is built of all the modules and header units in your project. - **Translate Includes to Imports** When the compiler encounters an `#include` statement, and a matching header unit file (`.ifc`) exists for the specified header file, the compiler imports the header unit instead of treating the header file as an `#include`. When combined with **Scan for dependencies**, the compiler finds all of the header files that can be compiled into header units. An allowlist is consulted by the compiler to decide which header files can compile into header units. This list is stored in a [`header-units.json`](./reference/header-unit-json-reference.md) file that must be in the same directory as the included file. You can see an example of a `header-units.json` file under the installation directory for Visual Studio. For example, `%ProgramFiles%\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.30.30705\include\header-units.json` is used by the compiler to determine whether a Standard Template Library header can be compiled into a header unit. This functionality exists to serve as a bridge with legacy code to get some benefits of header units. The `header-units.json` file serves two purposes. In addition to specifying which header files can be compiled into header units, it minimizes duplicated symbols to increase build throughput. For more information about symbol duplication, see [C++ header-units.json reference](reference/header-unit-json-reference.md#preventing-duplicated-symbols). @@ -145,9 +147,9 @@ For an example of how this technique is used to import STL header files as heade ## Preprocessor implications -The standard C99/C++11 conforming preprocessor is required to create and use header units. The compiler enables the new C99/C++11 conforming preprocessor when compiling header units by implicitly adding [`/Zc:preprocessor`](/cpp/build/reference/zc-preprocessor) to the command line whenever any form of `/exportHeader` is used. Attempting to turn it off will result in a compilation error. +The standard C99/C++11 conforming preprocessor is required to create and use header units. The compiler enables the new C99/C++11 conforming preprocessor when compiling header units by implicitly adding [`/Zc:preprocessor`](./reference/zc-preprocessor.md) to the command line whenever any form of `/exportHeader` is used. Attempting to turn it off will result in a compilation error. -Enabling the new preprocessor affects the processing of variadic macros. For more information, see the [Variadic macros](/cpp/preprocessor/variadic-macros#remarks) remarks section. +Enabling the new preprocessor affects the processing of variadic macros. For more information, see the [Variadic macros](../preprocessor/variadic-macros.md#remarks) remarks section. ## See also @@ -155,5 +157,7 @@ Enabling the new preprocessor affects the processing of variadic macros. For mor [`/exportHeader`](./reference/module-exportheader.md)\ [`/headerUnit`](./reference/headerunit.md)\ [`header-units.json`](./reference/header-unit-json-reference.md)\ +[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\ [Overview of modules in C++](../cpp/modules-cpp.md)\ -[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) \ No newline at end of file +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1) diff --git a/docs/build/walkthrough-import-stl-header-units.md b/docs/build/walkthrough-import-stl-header-units.md index 18b142ba503..1f50e2518f9 100644 --- a/docs/build/walkthrough-import-stl-header-units.md +++ b/docs/build/walkthrough-import-stl-header-units.md @@ -1,45 +1,46 @@ --- -description: "Learn to use header units to import C++ Standard Template Library (STL) libraries in Visual Studio." title: "Walkthrough: Import STL libraries as header units" -ms.date: 02/03/2022 +description: "Learn to use header units to import C++ Standard Template Library (STL) libraries in Visual Studio." +ms.date: 10/15/2022 ms.custom: "conceptual" author: "tylermsft" ms.author: "twhitney" helpviewer_keywords: ["import", "header unit", "ifc", "stl"] +monikerRange: '>=msvc-160' --- # Walkthrough: Import STL libraries as header units -This walkthrough shows how to import C++ Standard Template Library (STL) libraries as header units in Visual Studio. +This walkthrough shows how to import C++ Standard Template Library (STL) libraries as header units in Visual Studio. For an even faster and more robust way to import the standard library, see [Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md). -Importing a STL header as a header unit is simpler than using [precompiled header files](creating-precompiled-header-files.md). Header units are easier to set up and use, are significantly smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio). +Importing an STL header as a header unit is simpler than using [precompiled header files](creating-precompiled-header-files.md). Header units are easier to set up and use, are substantially smaller on disk, provide similar performance benefits, and are more flexible than a [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio). -For more detailed information about what header units are and the benefits they provide, see [What is a header unit?](walkthrough-header-units.md#what-is-a-header-unit) +For more detailed information about what header units are and the benefits they provide, see [What is a header unit?](walkthrough-header-units.md#what-is-a-header-unit). To contrast header units with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](compare-inclusion-methods.md). ## Prerequisites -To use header units, use Visual Studio 2019 16.10 or later. +To use header units, use Visual Studio 2022 or later, or Visual Studio 2019 version 16.11 or later. The [`/std:c++20`](./reference/std-specify-language-standard-version.md) option (or later) is required to use header units. ## Two approaches to import STL headers as header units Before you can import an STL header, it must be compiled into a header unit. A header unit is a binary representation of a header file. It has an *`.ifc`* extension. -The recommended approach is to create a static library that contains the built header units for the STL headers you want to use. Then reference that library and `import` its header units. This can result in faster builds and better reuse. To try out this approach, see [Approach 1: Create a static library of STL library header units](#approach1). +The recommended approach is to create a static library that contains the built header units for the STL headers you want to use. Then reference that library and `import` its header units. This approach can result in faster builds and better reuse. To try out this approach, see [Approach 1: Create a static library of STL library header units](#approach1). -Another approach is to have Visual Studio scan for the STL headers you `#include` in your project, compile them into header units, and `import` rather than `#include` those headers. This is useful if you have a large codebase because you don't have to change your source code. This approach is less flexible than the static library approach because it doesn't lend itself to reusing the built header units in other projects. But you still get the performance advantage of importing individual STL libraries as header units. To try out this approach, see [Approach 2: Scan includes for STL headers to import](#approach2). +Another approach is to have Visual Studio scan for the STL headers you `#include` in your project, compile them into header units, and `import` rather than `#include` those headers. This approach is useful if you have a large codebase, because you don't have to change your source code. This approach is less flexible than the static library approach, because it doesn't lend itself to reusing the built header units in other projects. But, you still get the performance advantage of importing individual STL libraries as header units. To try out this approach, see [Approach 2: Scan includes for STL headers to import](#approach2). ## Approach 1: Create a static library of STL library header units -The recommended way to consume STL libraries as header units is to create one or more static library projects that consist of the STL library header units that you want to use. Then, reference the library project to consume those STL header units. It's similar to using [shared precompiled headers](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio/), but easier. +The recommended way to consume STL libraries as header units is to create one or more static library projects. These projects should consist of the STL library header units that you want to use. Then, reference the library projects to consume those STL header units. It's similar to using [shared precompiled headers](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio/), but easier. Header units (and modules) built in a static library project are automatically available to referencing projects because the project system automatically adds the appropriate [`/headerUnit`](./reference/headerunit.md) command-line option to the compiler so that referencing projects can import the header units. This approach ensures that the header unit for a particular header is built only once. It allows you to import some or all of the header units, which isn't possible with a PCH. You can include header units in any order. -In the following example, you create a static library project consisting of the `` and `` header units. After the solution is built, you'll reference this shared header unit project from another C++ project. Everywhere `import ;` or `import ;` is found, the built header unit for that library is used instead of translating the header with the preprocessor. This improves build performance, like PCH files do, when the same header is included in multiple files. The header won't have to be processed over and over by the files that include it. Instead, the already processed compiled header unit is imported. +In the following example, you create a static library project consisting of the `` and `` header units. After the solution is built, you'll reference this shared header unit project from another C++ project. Everywhere `import ;` or `import ;` is found, the built header unit for that library is used instead of translating the header with the preprocessor. It improves build performance, like PCH files do, when the same header is included in multiple files. The header won't have to be processed over and over by the files that include it. Instead, the already processed compiled header unit is imported. To create a static library that contains the STL libraries `` and ``, follow these steps: -1. Create an empty C++ project. Call it **SharedPrj**.\ +1. Create an empty C++ project. Name it *SharedPrj*.\ Select **Empty Project** for C++ from the project types available in the **Create a new project** window: :::image type="content" source="media/empty-project-option.png" alt-text="Screenshot that shows creating a new empty C++ project."::: 1. Add a new C++ file to the project. Change the file's content to: @@ -53,24 +54,25 @@ To create a static library that contains the STL libraries `` and ` **Properties**. The project property pages dialog opens: +1. On the Visual Studio main menu, select **Project** > **SharedPrj Properties** to open the project Property Pages dialog: :::image type="content" source="media/set-header-unit-library-settings.png" alt-text="Screenshot that shows settings for Configuration Type and C++ Language Standard."::: -2. Select **All Configurations** in the **Configuration** list, and then **All Platforms** in the **Platform** list. Doing so ensures the settings that you change apply whether you're building for debug or retail. -1. In the left pane of the project property pages dialog, select **General**. +1. Select **All Configurations** in the **Configuration** dropdown list, and then select **All Platforms** in the **Platform** dropdown list. These settings ensure that your changes apply whether you're building for debug or release. +1. In the left pane of the project Property Pages dialog, select **Configuration Properties** > **General**. 1. Change the **Configuration Type** option to **Static library (.lib)**. -1. Change **C++ Language Standard** to **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview - Features from the Latest C++ Working Draft (/std:c++latest)**. -1. In the left pane of the project property pages dialog, select **C/C++** > **General**. -1. In the **Scan Sources for Module Dependencies** list, select **Yes** (this causes the compiler to scan your code for dependencies that can be built into header units): +1. Change **C++ Language Standard** to **ISO C++20 Standard (/std:c++20)** (or later). +1. In the left pane of the project Property Pages dialog, select **Configuration Properties** > **C/C++** > **General**. +1. In the **Scan Sources for Module Dependencies** dropdown list, select **Yes**. (This option causes the compiler to scan your code for dependencies that can be built into header units): :::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the scan module dependencies property setting."::: -1. Choose **OK** to close the project property pages dialog. Build the solution by selecting **Build** > **Build Solution** on the main menu. +1. Choose **OK** to close the project Property Pages dialog. Build the solution by selecting **Build** > **Build Solution** on the main menu. ### Reference the header unit library To import `` and `` as header units from the static library, create a project that references the static library as follows: 1. With the current solution still open, on the Visual Studio menu, select **File** > **Add** > **New Project**. -1. Add a C++ console app project. Call it **Walkthrough**. -1. Change the content of its source file as follows: +1. In the **Create a new project** wizard, select the C++ **Console App** template and choose **Next**. +1. Name the new project *Walkthrough*. Change the **Solution** dropdown to **Add to solution**. Choose **Create** to create the project and add it to your solution. +1. Change the content of the *Walkthrough.cpp* source file as follows: ```cpp import ; @@ -83,22 +85,22 @@ To import `` and `` as header units from the static library, c } ``` -To use header units, you need the [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later option. If you're using Visual Studio 2019 version 16.10, use **`/std:c++latest`**. Set the language standard by using the following steps: +Header units require the [`/std:c++20`](./reference/std-specify-language-standard-version.md) option (or later). Set the language standard by using the following steps: -1. In **Solution Explorer**, right-click the **Walkthrough** project and select **Properties**. The project property pages dialog opens: +1. In **Solution Explorer**, right-click the **Walkthrough** project and select **Properties** to open the project Property Pages dialog: :::image type="content" source="media/set-cpp-language-latest.png" alt-text="Screenshot that shows setting the language standard to the preview version."::: -1. In the left pane of the **Walkthrough** project property pages dialog, select **Configuration Properties** > **General**. -1. In the **C++ Language Standard** list, select **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview-Features from the Latest C++ Working Draft (/std:c++latest)**. -1. Select **OK** to close the project property pages dialog. +1. In the left pane of the **Walkthrough** project Property Pages dialog, select **Configuration Properties** > **General**. +1. In the **C++ Language Standard** dropdown, select **ISO C++20 Standard (/std:c++20)** (or later). +1. Choose **OK** to close the project Property Pages dialog. In the **Walkthrough** project, add a reference to the **SharedPrj** project with the following steps: 1. In the **Walkthrough** project, select the **References** node, and then select **Add Reference**. Select **SharedPrj** in the list of projects: :::image type="content" source="./media/add-reference-to-walkthrough.png" alt-text="Screenshot that shows the Add Reference dialog. It's used to add a reference to the Walkthrough project."::: Adding this reference causes the build system to use the header units built by **SharedPrj** whenever an `import` in the **Walkthrough** project matches one of the built header units in **SharedPrj**. -1. Select **OK** to close the **Add Reference** dialog. +1. Choose **OK** to close the **Add Reference** dialog. 1. Right-click the **Walkthrough** project and select **Set as Startup Project**. -1. Build the solution. (**Build** > **Build Solution** on the main menu.) Run it to see that it produces the expected output: `1` +1. Build the solution. (Use **Build** > **Build Solution** on the main menu.) Run it to see that it produces the expected output: `1` The advantage of this approach is that you can reference the static library project from any project to reuse the header units in it. In this example, the static library contains the `` and `` header units. @@ -108,11 +110,11 @@ The result should be increased build throughput because importing a header unit When you use this approach with your own projects, build the static library project with compiler options that are compatible with the project that references it. For example, STL projects should be built with the **`/EHsc`** compiler option to turn on exception handling, and so should the projects that reference the static library project. -### `/translateInclude` +### Use `/translateInclude` -The [`/translateInclude`](./reference/translateinclude.md) compiler option (available in the project properties dialog under **C/C++** > **General** > **Translate Includes to Imports**) makes it easier for you to use a header unit library in older projects projects that `#include` the STL libraries. It makes it unnecessary to change `#include` directives to `import` in your project, while still giving you the advantage of importing the header units instead of including them. +The [`/translateInclude`](./reference/translateinclude.md) compiler option (available in the project Property Pages dialog under **C/C++** > **General** > **Translate Includes to Imports**) makes it easier for you to use a header unit library in older projects that `#include` the STL libraries. It makes it unnecessary to change `#include` directives to `import` in your project, while still giving you the advantage of importing the header units instead of including them. -For example, if you have `#include ` in your project and you reference a static library that contains a header unit for ``, you don't need to manually change `#include ` to `import ;` in your source code. Instead, the compiler automatically treats `#include ` as `import ;` To see this explored in detail, visit [Approach 2: Scan includes for STL headers to import](#approach2) in this topic. Not all STL header files can be compiled to a header unit. The `header-units.json` shipped with Visual Studio lists which STL header files can be compiled into header units. A header that relies on macros to specify its behavior often can't be compiled into a header unit. +For example, if you have `#include ` in your project and you reference a static library that contains a header unit for ``, you don't need to manually change `#include ` to `import ;` in your source code. Instead, the compiler automatically treats `#include ` as `import ;`. For more information in detail on this approach, see [Approach 2: Scan includes for STL headers to import](#approach2). Not all STL header files can be compiled to a header unit. The `header-units.json` shipped with Visual Studio lists which STL header files can be compiled into header units. A header that relies on macros to specify its behavior often can't be compiled into a header unit. An `#include` statement that doesn't refer to a header unit is treated as a normal `#include`. @@ -120,15 +122,15 @@ An `#include` statement that doesn't refer to a header unit is treated as a norm Header units built by a static library project are automatically available to all directly and indirectly referencing projects. There are project settings that allow you to select which header units should be automatically available to all referencing projects. The settings are in project settings under **VC++ Directories**. -1. In **Solution Explorer**, right-click the project and select **Properties**. -1. In the left pane of the project properties page, select **VC++ Directories**: +1. In **Solution Explorer**, right-click the project and select **Properties** to open the project Property Pages dialog. +1. In the left pane of the dialog, select **Configuration Properties** > **VC++ Directories**: :::image type="content" source="media/public-include-module-directories-setting.png" alt-text="Screenshot that shows public project content properties, like Public Include Directories and All Header Files are Public."::: -The following settings control the visibility of header units to the build system: +The following properties control the visibility of header units to the build system: - **Public Include Directories** specifies project directories for header units that should be automatically added to the include path in referencing projects. -- **Public C++ Module Directories** specifies which project directories contain header units that should be available to referencing projects. This setting allows you to make some header units public. It's visible to other projects so this is where you put header units that you want to share. If you use this setting, for convenience, specify **Public Include Directories** to automatically add your public headers to the include path in referencing projects. -- **All Modules are Public**: when you use header units built as a part of a DLL project, the symbols have to be exported from the DLL. To do so, set this property to **Yes**. +- **Public C++ Module Directories** specifies which project directories contain header units that should be available to referencing projects. This property allows you to make some header units public. It's visible to other projects, so put header units that you want to share here. If you use this setting, for convenience, specify **Public Include Directories** to automatically add your public headers to the Include path in referencing projects. +- **All Modules are Public**: when you use header units built as a part of a DLL project, the symbols have to be exported from the DLL. To export module symbols automatically, set this property to **Yes**. ### Use a prebuilt module file @@ -136,23 +138,23 @@ Typically, the easiest way to reuse header units among solutions is to reference If you must use a built header unit that you don't have the project for, you can specify where the built *`.ifc`* file is so you can import it in your solution. To access this setting: -1. On the main menu, select **Project** > **Properties**. The project properties dialog opens. -1. In the left pane of the project properties page, select **C/C++** > **General**. -1. In the **Additional Module Dependencies** list, add the modules to reference. Here's an example of the format to use for **Additional Module Dependencies**: `ModuleName1=Path\To\ModuleName1.ifc; ModuleName2=Path\To\ModuleName2.ifc` -:::image type="content" source="media/vs2019-additional-module-dependencies.png" alt-text="Screenshot showing project properties under C/C++, General, which Additional Module Dependencies selected."::: +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. In the left pane of the dialog, select **Configuration Properties** > **C/C++** > **General**. +1. In **Additional Module Dependencies**, add the modules to reference, separated by semicolons. Here's an example of the format to use for **Additional Module Dependencies**: `ModuleName1=Path\To\ModuleName1.ifc; ModuleName2=Path\To\ModuleName2.ifc` +:::image type="content" source="media/vs2019-additional-module-dependencies.png" alt-text="Screenshot showing project Property Pages properties under Configuration Properties, C/C++, General, with Additional Module Dependencies selected."::: ### Select among multiple copies of a header unit -If you reference two or more projects that build two or more header units with the same name, or that build two or more header units for the same header file, there are multiple header units to choose from for the same import. You might have different versions of the header unit built with different compiler settings, for example, and must specify which one to use. +If you reference projects that build multiple header units, either with the same name or for the same header file, you must specify which one to use. You might have different versions of the header unit built with different compiler settings, for example, and must specify the one that matches your project settings. -Use the project properties **C/C++** > **Additional Header Unit Dependencies** setting to resolve collisions by specifying which header unit to use. Otherwise, it isn't possible to predict which one is picked. +Use the project's **Additional Header Unit Dependencies** property to resolve collisions by specifying which header unit to use. Otherwise, it isn't possible to predict which one is picked. -To access this setting: +To set the **Additional Header Unit Dependencies** property: -1. On the main menu, select **Project** > **Properties**. The project properties dialog opens. -1. In the left pane of the project properties page, select **C/C++** > **General**. -1. Use **Additional Header Unit Dependencies** to resolve collisions by specifying which module or header unit should be used for the project. Use this format for **Additional Header Unit Dependencies**: `Path\To\Header1.h= Path\To\HeaderUnit1.ifc;Path\To\Header2.h= Path\To\ HeaderUnit2.ifc` -:::image type="content" source="media/additional-header-unit-dependencies-setting.png" alt-text="Screenshot that shows the Additional Header Unit Dependencies setting in the project properties page."::: +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. In the left pane of the dialog, select **Configuration Properties** > **C/C++** > **General**. +1. Specify which modules or header unit files to use in **Additional Header Unit Dependencies** to resolve collisions. Use this format for **Additional Header Unit Dependencies**: `Path\To\Header1.h= Path\To\HeaderUnit1.ifc;Path\To\Header2.h= Path\To\ HeaderUnit2.ifc` +:::image type="content" source="media/additional-header-unit-dependencies-setting.png" alt-text="Screenshot that shows the Additional Header Unit Dependencies setting in the project Property Pages dialog."::: > [!IMPORTANT] > Ensure that projects that share header units are built with compatible compilation options. If you use compilation options when you implement the header unit that are different from the ones you used when you created it, the compiler will issue warnings. @@ -164,13 +166,13 @@ To access this setting: Another way to import STL libraries is to have Visual Studio scan for the STL headers you `#include` in your project and compile them into header units. The compiler then imports rather than includes those headers. -This option is convenient when your project includes many STL header files across many files, or when build throughput isn't critical. This option doesn't guarantee that a header unit for a particular header file is built only once. But it's useful if you have a large codebase because you don't have to change your source code to take advantage of the benefits of header units for many of the STL libraries you use. +This option is convenient when your project includes many STL header files across many files, or when build throughput isn't critical. This option doesn't guarantee that a header unit for a particular header file is built only once. However, it's useful if you have a large codebase: You don't have to change your source code to take advantage of the benefits of header units for many of the STL libraries you use. -This approach is less flexible than the static library approach because it doesn't lend itself towards reusing the built header units in other projects. This approach might not be appropriate for larger projects because it doesn't guarantee an optimal build time since all of the sources must be scanned for `#include` statements. +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 and then change the project properties so that it imports the libraries as header units instead of including them, as described in the next section. +To try out this approach, create a project that includes two STL libraries. Then, change the project's properties so that it imports the libraries as header units instead of including them, as described in the next section. ### Create a C++ console app project @@ -180,8 +182,8 @@ Follow these steps to create a project that includes two STL libraries: `; - #include ; + #include + #include int main() { @@ -194,20 +196,21 @@ Follow these steps to create a project that includes two STL libraries: ` **Properties**. The project property pages dialog opens: -:::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the scan module dependencies property setting in the project property pages."::: -1. Select **All Configurations** in the **Configuration** list and **All Platforms** in the **Platform** list. Doing so ensures the settings that you change apply whether you're building for debug or release, and other configurations. -1. In the left pane of the project property pages dialog, select **C/C++** > **General**. -1. Set **Scan Sources for Module Dependencies** to **Yes**. This setting ensures that all files that can be compiled into a header unit will be. -1. Set **Translate Includes to Imports** to **Yes** This setting causes included STL header files that are on the allowlist (that is, in the `header-unit.json` file) to be compiled and then imported as header units instead of going through the preprocessor as an `#include`. - -:::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the Scan Sources for Module Dependencies, and Translate Includes to Imports settings, in the project properties page under Configuration Properties > C/C++ > General."::: - -The [`/std:c++20`](./reference/std-specify-language-standard-version.md) or later option is required to use header units. Change the C++ language standard used by the compiler: - -1. In the left pane of the project property pages dialog, select **Configuration Properties** > **General**. -1. In the **C++ Language Standard** list, select **ISO C++20 Standard (/std:c++20)** or later. In versions before Visual Studio 2019 version 16.11, select **Preview-Features from the Latest C++ Working Draft (/std:c++latest)**. -1. Choose **OK** to close the project property pages dialog. +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. Select **All Configurations** in the **Configuration** dropdown list, and then select **All Platforms** in the **Platform** dropdown list. These settings ensure that your changes apply whether you're building for debug or release, and other configurations. +1. In the left pane of the dialog, select **Configuration Properties** > **C/C++** > **General**. +1. Set **Scan Sources for Module Dependencies** to **Yes**. This setting ensures that all compatible header files compile into header units. +1. Set **Translate Includes to Imports** to **Yes**. This setting compiles the STL header files listed in the `header-unit.json` file as header units, and then imports them instead of using the preprocessor to `#include` them. +:::image type="content" source="media/vs2019-scan-module-dependencies.png" alt-text="Screenshot that shows the scan module dependencies property setting in the project Property Pages."::: +1. Choose **OK** to save your changes and close the project Property Pages dialog. + +The [`/std:c++20`](./reference/std-specify-language-standard-version.md) option or later is required to use header units. To change the C++ language standard used by the compiler: + +1. On the main menu, select **Project** > **Properties** to open the project Property Pages dialog. +1. Select **All Configurations** in the **Configuration** dropdown list, and then select **All Platforms** in the **Platform** dropdown list. These settings ensure that your changes apply whether you're building for debug or release, and other configurations. +1. In the left pane of the project Property Pages dialog, select **Configuration Properties** > **General**. +1. In the **C++ Language Standard** dropdown list, select **ISO C++20 Standard (/std:c++20)** (or later). +1. Choose **OK** to save your changes and close the project Property Pages dialog. 1. From the main menu, build the solution by selecting **Build** > **Build Solution**. Run the solution to verify that it produces the expected output: `1` @@ -216,5 +219,7 @@ The main consideration for whether to use this approach is the balance between c ## See also -[Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md) \ +[Compare header units, modules, and precompiled headers](compare-inclusion-methods.md)\ +[Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\ +[Walkthrough: Build and import header units in your Microsoft C++ projects](walkthrough-header-units.md)\ [`/translateInclude`](./reference/translateinclude.md) diff --git a/docs/build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md b/docs/build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md index cdfa078819b..b96564b5d3c 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 @@ -4,9 +4,9 @@ description: "A walkthrough that shows how to create a command-line MSBuild C++ ms.date: 10/08/2020 helpviewer_keywords: ["MSBuild (C++), walkthrough: create a project"] --- -# Walkthrough: Using MSBuild to Create a Visual C++ Project +# Walkthrough: Using MSBuild to Create a Visual Studio C++ Project -This walkthrough demonstrates how to use MSBuild in a command prompt to build a Visual Studio C++ project. You'll learn how to create an XML-based *`.vcxproj`* project file for a Visual C++ console application. After building the project, you'll learn how to customize the build process. +This walkthrough demonstrates how to use MSBuild in a command prompt to build a Visual Studio C++ project. You'll learn how to create an XML-based *`.vcxproj`* project file for a C++ console application. After building the project, you'll learn how to customize the build process. > [!IMPORTANT] > Don't use this approach if you intend to edit the project file later by using the Visual Studio IDE. If you create a *`.vcxproj`* file manually, the Visual Studio IDE might not be able to edit or load it, especially if the project uses wildcards in project items. For more information, see [`.vcxproj` and `.props` file structure](./reference/vcxproj-file-structure.md) and [`.vcxproj` files and wildcards](./reference/vcxproj-files-and-wildcards.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. - +- Three import tags (``) that specify the location of Microsoft 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 @@ -260,7 +249,7 @@ At the command prompt, enter this command to use the 64-bit tools to build your ### Using MSBuild with a different toolset -If you have the toolsets and libraries for other versions of Visual C++ installed, MSBuild can build applications for either the current Visual C++ version or for the other installed versions. For example, if you have installed Visual Studio 2012, to specify the Visual C++ 11.0 toolset for Windows XP, add this property group element to the *`Myproject.vcxproj`* project file after the *`Microsoft.Cpp.props`* file `` element: +If you have the toolsets and libraries for other versions of Microsoft C++ (MSVC) installed, MSBuild can build applications for either the current MSVC version or for the other installed versions. For example, if you have installed Visual Studio 2012, to specify the Visual C++ 11.0 toolset for Windows XP, add this property group element to the *`Myproject.vcxproj`* project file after the *`Microsoft.Cpp.props`* file `` element: ```xml @@ -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/why-floating-point-numbers-may-lose-precision.md b/docs/build/why-floating-point-numbers-may-lose-precision.md index 7fc2eb91e9a..45605f0aa43 100644 --- a/docs/build/why-floating-point-numbers-may-lose-precision.md +++ b/docs/build/why-floating-point-numbers-may-lose-precision.md @@ -17,7 +17,7 @@ This behavior is the result of one of the following: To resolve the behavior, most programmers either ensure that the value is greater or less than what is needed, or they get and use a Binary Coded Decimal (BCD) library that will maintain the precision. -Binary representation of floating-point values affects the precision and accuracy of floating-point calculations. Microsoft Visual C++ uses [IEEE floating-point format](ieee-floating-point-representation.md). +Binary representation of floating-point values affects the precision and accuracy of floating-point calculations. Microsoft C++ uses [IEEE floating-point format](ieee-floating-point-representation.md). ## Example diff --git a/docs/build/working-with-project-properties.md b/docs/build/working-with-project-properties.md index 9a6b533a192..b6ca518f4c8 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 x64 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(x64), and the setting in the Solutions platform dropdown on the toolbar, which is set to x64. +:::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). @@ -37,42 +41,44 @@ For more information about setting properties for a Debug build, see: - [Project settings for a C++ debug configuration](/visualstudio/debugger/project-settings-for-a-cpp-debug-configuration) - [Debugger Settings and Preparation](/visualstudio/debugger/debugger-settings-and-preparation) -- [Debugging Preparation: Visual C++ Project Types](/visualstudio/debugger/debugging-preparation-visual-cpp-project-types) +- [Debugging Preparation: Microsoft C++ Project Types](/visualstudio/debugger/debugging-preparation-visual-cpp-project-types) - [Specify symbol (.pdb) and source files in the Visual Studio debugger](/visualstudio/debugger/specify-symbol-dot-pdb-and-source-files-in-the-visual-studio-debugger) ## 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 c03fee57e91..a1265ca7cfc 100644 --- a/docs/build/x64-calling-convention.md +++ b/docs/build/x64-calling-convention.md @@ -1,21 +1,25 @@ --- -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). +For more information about the `__preserve_none` calling convention, see [__preserve_none](../cpp/preserve-none.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). +Integer arguments are passed in registers `RCX`, `RDX`, `R8`, and `R9`. Floating point arguments are passed in `XMM0L`, `XMM1L`, `XMM2L`, and `XMM3L`. 16-byte arguments are passed by reference. Parameter passing is described in detail in [Parameter passing](#parameter-passing). These registers, and `RAX`, `R10`, `R11`, `XMM4`, and `XMM5`, are considered *volatile*, or potentially changed by a callee on return. Register usage is documented in detail in [x64 register usage](x64-software-conventions.md#x64-register-usage) and [Caller/callee saved registers](#callercallee-saved-registers). For prototyped functions, all arguments are converted to the expected callee types before passing. The caller is responsible for allocating space for the callee's parameters. The caller must always allocate sufficient space to store four register parameters, even if the callee doesn't take that many parameters. This convention simplifies support for unprototyped C-language functions and vararg C/C++ functions. For vararg or unprototyped functions, any floating point values must be duplicated in the corresponding general-purpose register. Any parameters beyond the first four must be stored on the stack after the shadow store before the call. Vararg function details can be found in [Varargs](#varargs). Unprototyped function information is detailed in [Unprototyped functions](#unprototyped-functions). @@ -25,17 +29,17 @@ 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 are passed on the stack in right-to-left order. The caller reserves the required stack space and writes these arguments to stack memory using store or move instructions, maintaining 8-byte alignment for each argument. -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. +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. -Any floating-point and double-precision arguments in the first four parameters are passed in XMM0 - XMM3, depending on position. Floating-point values are only placed in the integer registers RCX, RDX, R8, and R9 when there are varargs arguments. For details, see [Varargs](#varargs). Similarly, the XMM0 - XMM3 registers are ignored when the corresponding argument is an integer or pointer type. +Any floating-point and double-precision arguments in the first four parameters are passed in `XMM0` - `XMM3`, depending on position. Floating-point values are only placed in the integer registers `RCX`, `RDX`, `R8`, and `R9` when there are varargs arguments. For details, see [Varargs](#varargs). Similarly, the `XMM0` - `XMM3` registers are ignored when the corresponding argument is an integer or pointer type. [`__m128`](../cpp/m128.md) types, arrays, and strings are never passed by immediate value. Instead, a pointer is passed to memory allocated by the caller. Structs and unions of size 8, 16, 32, or 64 bits, and **`__m64`** types, are passed as if they were integers of the same size. Structs or unions of other sizes are passed as a pointer to memory allocated by the caller. For these aggregate types passed as a pointer, including **`__m128`**, the caller-allocated temporary memory must be 16-byte aligned. @@ -47,31 +51,31 @@ The following table summarizes how parameters are passed, by type and position f | Parameter type | fifth and higher | fourth | third | second | leftmost | |-|-|-|-|-|-| -| floating-point | stack | XMM3 | XMM2 | XMM1 | XMM0 | -| integer | stack | R9 | R8 | RDX | RCX | -| Aggregates (8, 16, 32, or 64 bits) and **`__m64`** | stack | R9 | R8 | RDX | RCX | -| Other aggregates, as pointers | stack | R9 | R8 | RDX | RCX | -| **`__m128`**, as a pointer | stack | R9 | R8 | RDX | RCX | +| floating-point | stack | `XMM3` | `XMM2` | `XMM1` | `XMM0` | +| integer | stack | `R9` | `R8` | `RDX` | `RCX` | +| Aggregates (8, 16, 32, or 64 bits) and **`__m64`** | stack | `R9` | `R8` | `RDX` | `RCX` | +| Other aggregates, as pointers | stack | `R9` | `R8` | `RDX` | `RCX` | +| **`__m128`**, as a pointer | stack | `R9` | `R8` | `RDX` | `RCX` | ### Example of argument passing 1 - all integers ```cpp func1(int a, int b, int c, int d, int e, int f); -// a in RCX, b in RDX, c in R8, d in R9, f then e pushed on stack +// a in RCX, b in RDX, c in R8, d in R9, f then e passed on stack ``` ### Example of argument passing 2 - all floats ```cpp func2(float a, double b, float c, double d, float e, float f); -// a in XMM0, b in XMM1, c in XMM2, d in XMM3, f then e pushed on stack +// a in XMM0, b in XMM1, c in XMM2, d in XMM3, f then e passed on stack ``` ### Example of argument passing 3 - mixed ints and floats ```cpp func3(int a, double b, int c, float d, int e, float f); -// a in RCX, b in XMM1, c in R8, d in XMM3, f then e pushed on stack +// a in RCX, b in XMM1, c in R8, d in XMM3, f then e passed on stack ``` ### Example of argument passing 4 - `__m64`, `__m128`, and aggregates @@ -79,7 +83,7 @@ func3(int a, double b, int c, float d, int e, float f); ```cpp func4(__m64 a, __m128 b, struct c, float d, __m128 e, __m128 f); // a in RCX, ptr to b in RDX, ptr to c in R8, d in XMM3, -// ptr to f pushed on stack, then ptr to e pushed on stack +// ptr to f passed on stack, then ptr to e passed on stack ``` ## Varargs @@ -90,7 +94,7 @@ If parameters are passed via varargs (for example, ellipsis arguments), then the For functions not fully prototyped, the caller passes integer values as integers and floating-point values as double precision. For floating-point values only, both the integer register and the floating-point register contain the float value in case the callee expects the value in the integer registers. -```cpp +```c func1(); func2() { // RCX = 2, RDX = XMM1 = 1.0, and R8 = 7 func1(2, 1.0, 7); @@ -99,23 +103,23 @@ 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, +// Caller passes a in RCX, b in XMM1, c in R8, d in R9, e passed on stack, // callee returns __int64 result in RAX. ``` ### 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,19 +127,19 @@ __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. }; Struct1 func3(int a, double b, int c, float d); // Caller allocates memory for Struct1 returned and passes pointer in RCX, -// a in RDX, b in XMM2, c in R9, d pushed on the stack; +// a in RDX, b in XMM2, c in R9, d passed on the stack; // callee returns pointer to Struct1 result in RAX. ``` ### 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. }; @@ -146,9 +150,11 @@ Struct2 func4(int a, double b, int c, float d); ## Caller/callee saved registers -The x64 ABI considers the registers RAX, RCX, RDX, R8, R9, R10, R11, and XMM0-XMM5 volatile. When present, the upper portions of YMM0-YMM15 and ZMM0-ZMM15 are also volatile. On AVX512VL, the ZMM, YMM, and XMM registers 16-31 are also volatile. When AMX support is present, the TMM tile registers are volatile. Consider volatile registers destroyed on function calls unless otherwise safety-provable by analysis such as whole program optimization. +The x64 ABI considers the registers `RAX`, `RCX`, `RDX`, `R8`, `R9`, `R10`, `R11`, and `XMM0`-`XMM5` volatile. When present, the upper portions of `YMM0`-`YMM15` and `ZMM0`-`ZMM15` are also volatile. On AVX512VL, the `ZMM`, `YMM`, and `XMM` registers 16-31 are also volatile. When AMX support is present, the `TMM` tile registers are volatile. Consider volatile registers destroyed on function calls unless otherwise safety-provable by analysis such as whole program optimization. -The x64 ABI considers registers RBX, RBP, RDI, RSI, RSP, R12, R13, R14, R15, and XMM6-XMM15 nonvolatile. They must be saved and restored by a function that uses them. +The x64 ABI considers registers `RBX`, `RBP`, `RDI`, `RSI`, `RSP`, `R12`, `R13`, `R14`, `R15`, and `XMM6`-`XMM15` nonvolatile. They must be saved and restored by a function that uses them. + +When APX support is present, registers `R16`-`R29` are volatile. `R30` and `R31` are nonvolatile. ## Function pointers @@ -156,7 +162,7 @@ Function pointers are simply pointers to the label of the respective function. T ## Floating-point support for older code -The MMX and floating-point stack registers (MM0-MM7/ST0-ST7) are preserved across context switches. There's no explicit calling convention for these registers. The use of these registers is strictly prohibited in kernel mode code. +The MMX and floating-point stack registers (`MM0`-`MM7`/`ST0`-`ST7`) are preserved across context switches. There's no explicit calling convention for these registers. The use of these registers is strictly prohibited in kernel mode code. ## FPCSR @@ -166,49 +172,85 @@ 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\[7] | Reserved - 0 | -| FPCSR\[8:9] | Precision Control - 10B (double precision) | -| FPCSR\[10:11] | Rounding control - 0 (round to nearest) | -| FPCSR\[12] | Infinity control - 0 (not used) | +| `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) | +| `FPCSR\[12]` | Infinity control - 0 (not used) | -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. +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. +- In functions where the documented purpose of the given function is to modify the nonvolatile `FPCSR` flags. - When it's provably correct that the violation of these rules results in a program that behaves the same as a program that doesn't violate the rules, for example, through whole-program analysis. +Despite being considered nonvolatile, there is no static unwind descriptor describing where it was saved and where it should be restored from. Exception-safe code which modifies `FPCSR` should resort to an exception finalizer (e.g. C++ destructor or a `__finally` clause) to restore it explicitly, when unwinding the stack. + ## MXCSR -The register state also includes MXCSR. The calling convention divides this register into a volatile portion and a nonvolatile portion. The volatile portion consists of the six status flags, in MXCSR\[0:5], while the rest of the register, MXCSR\[6:15], is considered nonvolatile. +The register state also includes `MXCSR`. The calling convention divides this register into a volatile portion and a nonvolatile portion. The volatile portion consists of the six status flags, in `MXCSR\[0:5]`, while the rest of the register, `MXCSR\[6:15]`, is considered nonvolatile. The nonvolatile portion is set to the following standard values at the start of program execution: | Register\[bits] | Setting | |-|-| -| MXCSR\[6] | Denormals are zeros - 0 | -| MXCSR\[7:12] | Exception masks all 1's (all exceptions masked) | -| MXCSR\[13:14] | Rounding control - 0 (round to nearest) | -| MXCSR\[15] | Flush to zero for masked underflow - 0 (off) | +| `MXCSR\[6]` | Denormals are zeros - 0 | +| `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. +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. +- In functions where the documented purpose of the given function is to modify the nonvolatile `MXCSR` flags. - When it's provably correct that the violation of these rules results in a program that behaves the same as a program that doesn't violate the rules, for example, through whole-program analysis. -Make no assumptions about the MXCSR register's volatile portion state across a function boundary, unless the function documentation explicitly describes it. +Make no assumptions about the `MXCSR` register's volatile portion state across a function boundary, unless the function documentation explicitly describes it. + +Despite parts of `MXCSR` being considered nonvolatile, there is no static unwind descriptor describing where it was saved and where it should be restored from. Exception-safe code which modifies the nonvolatile portions of `MXCSR` should resort to an exception finalizer (e.g. C++ destructor or a `__finally` clause) to restore it explicitly, when unwinding the stack. ## 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, 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. + +If APX is supported, `R30` and `R31` should not be modified in a function from the point `setjmp` is called to the point where the call which ultimately results in `longjmp` is made. This limitation is the result of `R30` and `R31` not being saved as part of `jmp_buf` - this structure definition cannot change. Instead, they are restored via the unwinder. The following example demonstrates how the difference on how the data is restored influences this restriction: + +```c +jmp_buf jmpbuffer; + +void function_a() { + ... + + int val = setjmp(jmpbuffer); // At this time R30 is 10 + + ... + + if (val == 0) { + function_b(); // At this time R30 is 20 + } + + ... +} + +void function_b() { + ... + + longjmp(jmpbuffer, 1); + + ... +} +``` + +In this example, the value of `R30` changes from the point where `setjmp` is called to the point `function_b` is called. In `function_b`, `longjmp` unwinds the stack until it reaches the function which called `setjmp` (`function_a` in this case). The value restored for `R30` will be `20` (the value at the point `function_b` was called), not `10` (the value at which `setjmp` was called). This means that when `setjmp` returns for the second time (as the result of `longjmp`) the value of `R30` will be set to `20` instead of `10`, which is incorrect. This is why compilers must ensure `R30` and `R31` remain constant from the point `setjmp` is called to the last place in the function which could ultimately result in `longjmp` being called. -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. +Since `longjmp` can be called from an exception filter (not just a sub-routine), this effectively dictates that `R30` and `R31` should remain constant from the point `setjmp` is called through the rest of the function. ## 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 d1136eff592..fdb9f859bd9 100644 --- a/docs/build/x64-software-conventions.md +++ b/docs/build/x64-software-conventions.md @@ -1,8 +1,9 @@ --- 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"] +ms.topic: concept-article --- # Overview of x64 ABI conventions @@ -11,13 +12,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 +118,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 +132,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 +149,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 +165,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 @@ -177,7 +187,7 @@ If you require more strict alignment, use `__declspec(align(N))` on your variabl ## x64 register usage -The x64 architecture provides for 16 general-purpose registers (hereafter referred to as integer registers) as well as 16 XMM/YMM registers available for floating-point use. Volatile registers are scratch registers presumed by the caller to be destroyed across a call. Nonvolatile registers are required to retain their values across a function call and must be saved by the callee if used. +The x64 architecture provides for 16 general-purpose registers (hereafter referred to as integer registers) as well as 16 `XMM`/`YMM` registers available for floating-point use. Volatile registers are scratch registers presumed by the caller to be destroyed across a call. Nonvolatile registers are required to retain their values across a function call and must be saved by the callee if used. ### Register volatility and preservation @@ -185,31 +195,33 @@ The following table describes how each register is used across function calls: |Register|Status|Use| |-|-|-| -|RAX|Volatile|Return value register| -|RCX|Volatile|First integer argument| -|RDX|Volatile|Second integer argument| -|R8|Volatile|Third integer argument| -|R9|Volatile|Fourth integer argument| -|R10:R11|Volatile|Must be preserved as needed by caller; used in syscall/sysret instructions| -|R12:R15|Nonvolatile|Must be preserved by callee| -|RDI|Nonvolatile|Must be preserved by callee| -|RSI|Nonvolatile|Must be preserved by callee| -|RBX|Nonvolatile|Must be preserved by callee| -|RBP|Nonvolatile|May be used as a frame pointer; must be preserved by callee| -|RSP|Nonvolatile|Stack pointer| -|XMM0, YMM0|Volatile|First FP argument; first vector-type argument when **`__vectorcall`** is used| -|XMM1, YMM1|Volatile|Second FP argument; second vector-type argument when **`__vectorcall`** is used| -|XMM2, YMM2|Volatile|Third FP argument; third vector-type argument when **`__vectorcall`** is used| -|XMM3, YMM3|Volatile|Fourth FP argument; fourth vector-type argument when **`__vectorcall`** is used| -|XMM4, YMM4|Volatile|Must be preserved as needed by caller; fifth vector-type argument when **`__vectorcall`** is used| -|XMM5, YMM5|Volatile|Must be preserved as needed by caller; sixth vector-type argument when **`__vectorcall`** is used| -|XMM6:XMM15, YMM6:YMM15|Nonvolatile (XMM), Volatile (upper half of YMM)|Must be preserved by callee. YMM registers must be preserved as needed by caller.| +|`RAX`|Volatile|Return value register| +|`RCX`|Volatile|First integer argument| +|`RDX`|Volatile|Second integer argument| +|`R8`|Volatile|Third integer argument| +|`R9`|Volatile|Fourth integer argument| +|`R10`:`R11`|Volatile|Must be preserved as needed by caller; used in syscall/sysret instructions| +|`R12`:`R15`|Nonvolatile|Must be preserved by callee| +|`R16`:`R29`|Volatile|Must be preserved by callee (APX Register)| +|`R30`:`R31`|Nonvolatile|Must be preserved by callee (APX Register)| +|`RDI`|Nonvolatile|Must be preserved by callee| +|`RSI`|Nonvolatile|Must be preserved by callee| +|`RBX`|Nonvolatile|Must be preserved by callee| +|`RBP`|Nonvolatile|May be used as a frame pointer; must be preserved by callee| +|`RSP`|Nonvolatile|Stack pointer| +|`XMM0`, `YMM0`|Volatile|First FP argument; first vector-type argument when **`__vectorcall`** is used| +|`XMM1`, `YMM1`|Volatile|Second FP argument; second vector-type argument when **`__vectorcall`** is used| +|`XMM2`, `YMM2`|Volatile|Third FP argument; third vector-type argument when **`__vectorcall`** is used| +|`XMM3`, `YMM3`|Volatile|Fourth FP argument; fourth vector-type argument when **`__vectorcall`** is used| +|`XMM4`, `YMM4`|Volatile|Must be preserved as needed by caller; fifth vector-type argument when **`__vectorcall`** is used| +|`XMM5`, `YMM5`|Volatile|Must be preserved as needed by caller; sixth vector-type argument when **`__vectorcall`** is used| +|`XMM6`:`XMM15`, `YMM6`:`YMM15`|Nonvolatile (`XMM`), Volatile (upper half of `YMM`)|Must be preserved by callee. `YMM` registers must be preserved as needed by caller.| On function exit and on function entry to C Runtime Library calls and Windows system calls, the direction flag in the CPU flags register is expected to be cleared. ## 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/build/x64-unwind-information-v3.md b/docs/build/x64-unwind-information-v3.md new file mode 100644 index 00000000000..246d81ca455 --- /dev/null +++ b/docs/build/x64-unwind-information-v3.md @@ -0,0 +1,422 @@ +--- +title: x64 Unwind Information V3 +description: Exception Handling Unwind Information V3 - Preview Specification +ms.date: 05/18/2026 +author: pmsjt +ms.author: pedrot +ms.reviewer: pedrot +--- + +# Exception Handling Unwind Information V3 + +## Scope + +Unwind Information V3 adds support for the Intel APX (Advanced Performance Extensions). It also brings additional flexibility to the code generation allowed in both function prologues and epilogues, enabling compilers to better optimize functions as a whole. + +Unwind V3 is required for code supporting APX. Non-APX enabled code should still use the [conventional (pre-V3) Unwind Information](../build/exception-handling-x64.md). + +> [!WARNING] +> Unwind Information V3 is a preview specification. There's still a risk of breaking changes or omissions. Code produced under this guidance should itself be considered preview code. + +## Terminology + +| Term | Definition | +|------|------------| +| **Fragment** | A contiguous region of machine code described by a single `RUNTIME_FUNCTION` / `UNWIND_INFO_V3` pair. A function might consist of a *main fragment* and zero or more *subfragments* chained together. For more information, see [Chained unwind info structures](../build/exception-handling-x64.md#chained-unwind-info-structures). | +| **WOD** | The Winding Operation Descriptor is a variable-length packed encoding of a single unwind operation (push, alloc, save, and so on). | +| **WOD pool** | The byte array within the payload that stores all WODs for a fragment's prolog and epilog(s). | +| **IP Offset** | The unsigned byte offset of an instruction relative to the start of the prolog or epilog. | +| **Payload** | The variable-length region immediately after the 4-byte `UNWIND_INFO_V3` header, sized by `PayloadWords` 16-bit words. Contains the large prolog extension, prolog IP offsets, epilog descriptors (with their IP offsets), and the WOD pool. | +| **RVA** | Relative Virtual Address is the offset from the base address of the image at load time. | + +## Overall Object-File Layout + +Unwind V3 reuses the existing PE/COFF `.pdata` and `.xdata` section conventions unchanged: + +``` +.pdata - sorted array of IMAGE_AMD64_RUNTIME_FUNCTION_ENTRY (12 bytes each) +.xdata - UNWIND_INFO_V3 structures referenced by .pdata entries +``` + +Each `RUNTIME_FUNCTION` entry is: + +| Offset | Size | Field | +|--------|------|-------| +| 0 | 4 | `BeginAddress` - RVA of fragment start | +| 4 | 4 | `EndAddress` - RVA of first byte past fragment end | +| 8 | 4 | `UnwindInfoAddress` - RVA of `UNWIND_INFO_V3` in `.xdata` | + +No changes from V1 or V2. + +## `UNWIND_INFO_V3` Header + +All multi-byte fields are little-endian. Bit 0 is the LSB of each byte. + +| Byte | Bits | Field | Width | +|------|------|-------|-------| +| 0 | [2:0] | `Version` (= 3) | 3 bits | +| 0 | [7:3] | `Flags` | 5 bits | +| 1 | [7:0] | `SizeOfProlog` | 8 bits | +| 2 | [7:0] | `PayloadWords` | 8 bits | +| 3 | [4:0] | `NumberOfOps` | 5 bits | +| 3 | [7:5] | `NumberOfEpilogs` | 3 bits | + +### Field Semantics + +| Field | Description | +|-------|-------------| +| `Version` | Must be `3`. | +| `Flags` | Same flag definitions as V1 or V2: `UNW_FLAG_EHANDLER` (0x01), `UNW_FLAG_UHANDLER` (0x02), `UNW_FLAG_CHAININFO` (0x04). New in V3: `UNW_FLAG_LARGE` (0x08). Bit 4 reserved (zero). | +| `SizeOfProlog` | Byte offset to the start of the first instruction that isn't part of the prolog. When `UNW_FLAG_LARGE` is set, this 8-bit field is the low byte of a 16-bit prolog size. For more information on the 16-bit form, see [`UNW_FLAG_LARGE` and `UNWIND_INFO_LARGE_V3`](#unw_flag_large-and-unwind_info_large_v3). | +| `PayloadWords` | Number of 16-bit words of payload following this header. The payload contains prolog IP offsets, all epilog descriptors (including their IP offsets), and the WOD pool. Doesn't include the exception-handler RVA or chained `RUNTIME_FUNCTION` that might follow. The algorithm to locate the handler/chain data is the same as V1 or V2: `header + 4 + PayloadWords * 2`, DWORD-aligned. | +| `NumberOfOps` | Count of WODs in the prolog (0–31). Zero means no prolog. If a function needs more than 31 prolog operations, use a subfragment. | +| `NumberOfEpilogs` | Count of `EPILOG_INFO_V3` descriptors that follow the prolog IP offsets (0–7). Zero means no epilogs in this fragment. If more than 7 are needed, use a subfragment. | + +### `UNW_FLAG_LARGE` and `UNWIND_INFO_LARGE_V3` + +When `UNW_FLAG_LARGE` is set in the header `Flags`, the first byte of the payload is a 1-byte `UNWIND_INFO_LARGE_V3` extension: + +| Byte | Bits | Field | Width | +|------|------|-------|-------| +| 0 | [7:0] | `SizeOfPrologHighByte` | 8 bits | + +`SizeOfPrologHighByte` is combined with `UNWIND_INFO_V3.SizeOfProlog` to form a 16-bit prolog size: `SizeOfProlog16 = (SizeOfPrologHighByte << 8) | SizeOfProlog`. + +Additionally, when `UNW_FLAG_LARGE` is set: + +- Prolog IP offset entries are 16-bit unsigned (2 bytes each) instead of 8-bit. + +The `UNWIND_INFO_LARGE_V3` byte is part of the payload and is included in `PayloadWords`. The handler-offset formula remains unchanged. + +This flag is only necessary for prologs exceeding 255 bytes. + +### Locating Exception Handler / Chain Info + +Identical to V1 or V2: + +``` +handler_offset = ALIGN_UP(sizeof(UNWIND_INFO_V3) + PayloadWords * 2, 4) +``` + +If `UNW_FLAG_EHANDLER` or `UNW_FLAG_UHANDLER` is set, a 4-byte handler RVA is at `handler_offset`, followed by language-specific handler data. + +If `UNW_FLAG_CHAININFO` is set, a 12-byte `RUNTIME_FUNCTION` is at `handler_offset`. + +## Payload Layout + +Immediately after the 4-byte header, the payload is arranged in the following order (all packed, `#pragma pack(1)` semantics): + +1. `UNWIND_INFO_LARGE_V3` - 1 byte, present only if `UNW_FLAG_LARGE` is set. +1. Prolog IP Offsets - `NumberOfOps` bytes (or 16-bit words if `UNW_FLAG_LARGE`). +1. For each epilog (repeated `NumberOfEpilogs` times): + - `EPILOG_INFO_V3` descriptor. + - `EPILOG_INFO_EX_V3` or `EPILOG_INFO_LARGE_EX_V3` extended descriptor (present only when `NumberOfOps > 0`). + - IP Offset array - `NumberOfOps` bytes (or 16-bit words if `EPILOG_INFO_LARGE`). +1. WOD Pool - remaining bytes. + +Total size = `PayloadWords` × 2 bytes (may include padding to fill words). + +### Prolog IP Offsets + +An array of `NumberOfOps` entries. Each entry is an unsigned byte giving the IP offset from the start of the fragment of the instruction that performs the corresponding unwind operation. When `UNW_FLAG_LARGE` is set, each entry is an unsigned 16-bit word instead. + +**Ordering:** The first entry corresponds to the operation closest to the function body (the *last* prolog instruction with an unwind effect). The last entry corresponds to the operation closest to the function entry point (the *first* prolog instruction). This matches the V1 or V2 convention of listing unwind codes in reverse execution order. The prolog WODs always start at byte offset zero of the WOD pool, and this same ordering applies. + +### Epilog Descriptors + +Zero or more `EPILOG_INFO_V3` structures follow the prolog IP offsets. Each can have an optional `EPILOG_INFO_EX_V3` (or `EPILOG_INFO_LARGE_EX_V3` when the `EPILOG_INFO_LARGE` flag is set) plus its own variable-size IP offset array, of size `NumberOfOps`: + +#### When `NumberOfOps > 0` (full descriptor) + +**Standard form** (`EPILOG_INFO_LARGE` not set): + +`EPILOG_INFO_V3`: + +| Byte | Bits | Field | Width | +|------|------|-------|-------| +| 0 | [2:0] | `Flags` | 3 bits | +| 0 | [7:3] | `NumberOfOps` | 5 bits | +| 1–2 | [15:0] | `EpilogOffset` | 16-bit signed | + +`EPILOG_INFO_EX_V3`: + +| Byte | Bits | Field | Width | +|------|------|-------|-------| +| 0–1 | [15:0] | `FirstOp` | 16-bit unsigned | +| 2 | [7:0] | `IpOffsetOfLastInstruction` | 8 bits unsigned | +| 3 .. | - | IP Offset array | `NumberOfOps` bytes, unsigned | + +**Large form** (`EPILOG_INFO_LARGE` set): + +`EPILOG_INFO_V3`: + +| Byte | Bits | Field | Width | +|------|------|-------|-------| +| 0 | [2:0] | `Flags` | 3 bits | +| 0 | [7:3] | `NumberOfOps` | 5 bits | +| 1–2 | [15:0] | `EpilogOffset` | 16-bit signed | + +`EPILOG_INFO_LARGE_EX_V3`: + +| Byte | Bits | Field | Width | +|------|------|-------|-------| +| 0–1 | [15:0] | `FirstOp` | 16-bit unsigned | +| 2–3 | [15:0] | `IpOffsetOfLastInstruction` | 16 bits unsigned | +| 4 .. | - | IP Offset array | `NumberOfOps` × 2 bytes, unsigned 16-bit | + +#### When `NumberOfOps == 0` (inherited descriptor) + +`EPILOG_INFO_V3`: + +| Byte | Bits | Field | Width | +|------|------|-------|-------| +| 0 | [2:0] | `Flags` | 3 bits | +| 0 | [7:3] | `NumberOfOps` (= 0) | 5 bits | +| 1–2 | [15:0] | `EpilogOffset` | 16-bit signed | + +The `Flags` bits 0 and 1, `FirstOp`, `IpOffsetOfLastInstruction`, and IP offset array are inherited from the immediately preceding `EPILOG_INFO_V3`. + +#### Epilog Field Semantics + +| Field | Description | +|-------|-------------| +| `Flags` | Bit 0: `EPILOG_INFO_PARENT_FRAGMENT_TRANSFER` - set if this epilog transfers control back to the parent fragment (for example, via JMP) rather than returning to the caller. Bit 1: `EPILOG_INFO_LARGE` - when set, the extended descriptor uses `EPILOG_INFO_LARGE_EX_V3` (16-bit `IpOffsetOfLastInstruction`) and each IP offset entry is 16-bit, accommodating epilogs exceeding 255 bytes. Bit 2: reserved (zero). | +| `NumberOfOps` | Number of WODs for this epilog (0–31). Zero is a special value meaning "inherit from previous epilog descriptor." | +| `EpilogOffset` | 16-bit signed displacement to the first instruction of this epilog. For the first epilog descriptor: positive values are byte offsets from the fragment start, and negative values are byte offsets from the fragment tail, that is, the first byte past the end. For subsequent epilog descriptors: delta from the start of the previous epilog. All epilogs must use the same sign - either all sorted ascending from start, or all sorted descending from tail. | +| `FirstOp` | Byte index into the WOD pool where the first WOD for this epilog resides. This is a byte offset, not a WOD index. Epilogs may share WODs with the prolog or with each other by pointing into the same pool region. | +| `IpOffsetOfLastInstruction` | Unsigned byte offset from the epilog start of the last instruction in the epilog, typically RET, or JMP. 8-bit in `EPILOG_INFO_EX_V3`; 16-bit in `EPILOG_INFO_LARGE_EX_V3`. The unwinder uses this value to determine where the epilog ends and the function body resumes. | + +#### Epilog IP Offsets + +Immediately after each full epilog descriptor (when `NumberOfOps > 0`), an array of `NumberOfOps` entries gives the IP offset of each epilog instruction that has a corresponding WOD. Each entry is an unsigned byte, or an unsigned 16-bit word when `EPILOG_INFO_LARGE` is set. Ordering: first entry = operation closest to the body (first epilog instruction with an unwind effect), last entry = operation closest to the control-transfer instruction. + +### WOD Pool + +The remaining bytes in the payload form the WOD pool. The prolog's WODs implicitly start at byte offset 0 of this pool. Each epilog's WOD list start at the byte offset given by its `FirstOp` field. WODs are packed with no alignment or padding between them. + +The number of WODs consumed for the prolog is `UNWIND_INFO_V3.NumberOfOps`. The number consumed for each epilog is its respective `EPILOG_INFO_V3.NumberOfOps` (or inherited). + +## WOD Encoding Reference + +WODs are variable-length (1–5 bytes), packed with `#pragma pack(1)`. The opcode is encoded in the **low-order bits** of the first byte. Decoding requires multi-level bit inspection. + +### Opcode Dispatch Table + +To decode a WOD, read the first byte and test its low bits in the following order: + +| Test | Opcode Value | WOD Type | Size | +|------|--------------|----------|------| +| `byte[0] == 0x00` | 0 | `WOD_SET_FPREG` | 2 bytes | +| `byte[0] == 0x01` | 1 | `WOD_ALLOC_HUGE` | 5 bytes | +| `byte[0] == 0x02` | 2 | `WOD_ALLOC_LARGE` | 3 bytes | +| `byte[0] == 0x03` | 3 | `WOD_PUSH_CANONICAL_FRAME` | 2 bytes | +| `(byte[0] & 0x07) == 0x04` | 4 | `WOD_PUSH` | 1 byte | +| `(byte[0] & 0x07) == 0x05` | 5 | `WOD_SAVE_NONVOL_FAR` | 5 bytes | +| `(byte[0] & 0x07) == 0x06` | 6 | `WOD_SAVE_NONVOL` | 3 bytes | +| `(byte[0] & 0x07) == 0x07` | 7 | `WOD_PUSH_CONSECUTIVE_2` | 1 byte | +| `(byte[0] & 0x0F) == 0x08` | 8 | `WOD_ALLOC_SMALL` | 1 byte | +| `(byte[0] & 0x0F) == 0x09` | 9 | `WOD_SAVE_XMM128_FAR` | 5 bytes | +| `(byte[0] & 0x0F) == 0x0A` | 10 | `WOD_SAVE_XMM128` | 3 bytes | +| `(byte[0] & 0x3F) == 0x20` | 32 | `WOD_PUSH2` | 2 bytes | + +** WOD decoding algorithm (pseudocode):** + +```c +uint8_t b0 = pool[offset]; +uint8_t op3 = b0 & 0x07; + +switch (op3) +{ +case 4: return WOD_PUSH; // 3-bit opcode = 100b +case 5: return WOD_SAVE_NONVOL_FAR;// 3-bit opcode = 101b +case 6: return WOD_SAVE_NONVOL; // 3-bit opcode = 110b +case 7: return WOD_PUSH_CONSECUTIVE_2; // 3-bit opcode = 111b +default: break; // bits[2:0] are 0b000, 0b001, 0b010, or 0b011 +} + +uint8_t op4 = b0 & 0x0F; +switch (op4) +{ +case 0x08: return WOD_ALLOC_SMALL; +case 0x09: return WOD_SAVE_XMM128_FAR; +case 0x0A: return WOD_SAVE_XMM128; +default: break; +} + +uint8_t op6 = b0 & 0x3F; +if (op6 == 0x20) return WOD_PUSH2; + +// 8-bit opcode (full byte match) +switch (b0) +{ +case 0x00: return WOD_SET_FPREG; +case 0x01: return WOD_ALLOC_HUGE; +case 0x02: return WOD_ALLOC_LARGE; +case 0x03: return WOD_PUSH_CANONICAL_FRAME; +default: return INVALID; +} +``` + +### WOD layouts (Bit-Level) + +All bit positions are numbered LSB-first within each byte. Multi-byte integer fields are little-endian. + +#### `WOD_PUSH` - 1 byte + +``` +Byte 0: [2:0] = 100b (opcode 4) + [7:3] = Register (5 bits, AMD64 integer register number) +``` + +**Effect:** `PUSH ` adjusts RSP by 8 and stores register. + +#### `WOD_PUSH2` - 2 bytes + +``` +Byte 0: [5:0] = 100000b (opcode 32) + [7:6] = Register1[1:0] (low 2 bits) +Byte 1: [2:0] = Register1[4:2] (high 3 bits) + [7:3] = Register2 (5 bits) +``` + +**Effect:** `PUSH2 , ` pushes two registers with a single instruction (APX). Adjusts RSP by 16. + +#### `WOD_PUSH_CONSECUTIVE_2` - 1 byte + +``` +Byte 0: [2:0] = 111b (opcode 7) + [7:3] = Register (5 bits) +``` + +**Effect:** Pushes `Register` and `Register+1` consecutively. Adjusts `RSP` by 16 total. `Register` value must be limited to [0, 30], as value of 31 would place `Register+1` out of bounds. + +#### `WOD_ALLOC_SMALL` - 1 byte + +``` +Byte 0: [3:0] = 1000b (opcode 8) + [7:4] = Size (4 bits) +``` + +**Actual allocation:** `(Size + 1) * 8` bytes. Range: 8–128 bytes in steps +of 8. + +#### `WOD_ALLOC_LARGE` - 3 bytes + +``` +Byte 0: [7:0] = 0x02 (opcode 2) +Bytes 1–2: Size (16-bit unsigned, little-endian) +``` + +**Actual allocation:** `Size * 8` bytes. Range: up to 524,280 bytes. + +#### `WOD_ALLOC_HUGE` - 5 bytes + +``` +Byte 0: [7:0] = 0x01 (opcode 1) +Bytes 1–4: Size (32-bit unsigned, little-endian) +``` + +**Actual allocation:** Raw byte count (no scaling). Range: up to 4 GiB. + +#### `WOD_SET_FPREG` - 2 bytes + +``` +Byte 0: [7:0] = 0x00 (opcode 0) +Byte 1: [3:0] = Register (4 bits, 0–15) + [7:4] = Offset (4 bits) +``` + +**Effect:** Establishes a frame pointer. ` = RSP + Offset * 16`. + +#### `WOD_SAVE_NONVOL` - 3 bytes + +``` +Byte 0: [2:0] = 110b (opcode 6) + [7:3] = Register (5 bits) +Bytes 1–2: Displacement (16-bit unsigned, little-endian) +``` + +**Effect:** `MOV [RSP + Displacement * 8], ` saves a nonvolatile +integer register to the stack. + +#### `WOD_SAVE_NONVOL_FAR` - 5 bytes + +``` +Byte 0: [2:0] = 101b (opcode 5) + [7:3] = Register (5 bits) +Bytes 1–4: Displacement (32-bit unsigned, little-endian) +``` + +**Effect:** Same as `WOD_SAVE_NONVOL` but with a 32-bit unscaled byte displacement. Used when the offset doesn't fit in 16 bits scaled by 8. + +#### `WOD_SAVE_XMM128` - 3 bytes + +``` +Byte 0: [3:0] = 1010b (opcode 10) + [7:4] = Register (4 bits, XMM0–XMM15) +Bytes 1–2: Displacement (16-bit unsigned, little-endian) +``` + +**Effect:** `MOVAPS [RSP + Displacement * 16], ` saves a 128-bit +XMM register. + +#### `WOD_SAVE_XMM128_FAR` - 5 bytes + +``` +Byte 0: [3:0] = 1001b (opcode 9) + [7:4] = Register (4 bits, XMM0–XMM15) +Bytes 1–4: Displacement (32-bit unsigned, little-endian) +``` + +**Effect:** Same as `WOD_SAVE_XMM128` but with a 32-bit unscaled byte displacement. + +#### `WOD_PUSH_CANONICAL_FRAME` - 2 bytes + +``` +Byte 0: [7:0] = 0x03 (opcode 3) +Byte 1: [7:0] = Type (8 bits) +``` + +**Effect:** Indicates the hardware/OS pushed a canonical frame onto the stack. Type values distinguish: +- Machine frame without error code +- Machine frame with error code +- Machine frame with shadow-stack push +- Context record + +(Exact type values are defined by the OS; consult the Windows SDK headers.) + +### Opcode Constant Summary + +```c +#define WOD_OP_SET_FPREG 0 // 8-bit opcode, 2 bytes +#define WOD_OP_ALLOC_HUGE 1 // 8-bit opcode, 5 bytes +#define WOD_OP_ALLOC_LARGE 2 // 8-bit opcode, 3 bytes +#define WOD_OP_PUSH_CANONICAL_FRAME 3 // 8-bit opcode, 2 bytes +#define WOD_OP_PUSH 4 // 3-bit opcode, 1 byte +#define WOD_OP_SAVE_NONVOL_FAR 5 // 3-bit opcode, 5 bytes +#define WOD_OP_SAVE_NONVOL 6 // 3-bit opcode, 3 bytes +#define WOD_OP_PUSH_CONSECUTIVE_2 7 // 3-bit opcode, 1 byte +#define WOD_OP_ALLOC_SMALL 8 // 4-bit opcode, 1 byte +#define WOD_OP_SAVE_XMM128_FAR 9 // 4-bit opcode, 5 bytes +#define WOD_OP_SAVE_XMM128 10 // 4-bit opcode, 3 bytes +#define WOD_OP_PUSH2 32 // 6-bit opcode, 2 bytes +``` + +### Register Encoding + +Integer registers use the standard AMD64 numbering (5 bits, 0–31): + +| Value | Register | +|-------|----------| +| 0 | RAX | +| 1 | RCX | +| 2 | RDX | +| 3 | RBX | +| 4 | RSP | +| 5 | RBP | +| 6 | RSI | +| 7 | RDI | +| 8 - 15 | R8 - R15 +| 16 - 31 | R16 - R31 (APX) | + +XMM register fields are 4 bits (0–15), mapping directly to XMM0–XMM15. diff --git a/docs/c-language/argument-description.md b/docs/c-language/argument-description.md index 876403b8650..e8f007f13cf 100644 --- a/docs/c-language/argument-description.md +++ b/docs/c-language/argument-description.md @@ -1,28 +1,28 @@ --- description: "Learn more about: Argument Description" title: "Argument Description" -ms.date: "11/04/2016" +ms.date: 09/28/2022 helpviewer_keywords: ["envp argument", "main function, syntax", "arguments [C++], for main function", "argv argument", "argc argument"] ms.assetid: 91c2cbe3-9aca-4277-afa1-6137eb8fb704 --- -# Argument Description +# Argument description -The `argc` parameter in the **main** and **wmain** functions is an integer specifying how many arguments are passed to the program from the command line. Since the program name is considered an argument, the value of `argc` is at least one. +The *`argc`* parameter in the `main` and `wmain` functions is an integer specifying how many arguments are passed to the program from the command line. Since the program name is considered an argument, the value of *`argc`* is at least one. ## Remarks -The `argv` parameter is an array of pointers to null-terminated strings representing the program arguments. Each element of the array points to a string representation of an argument passed to **main** (or **wmain**). (For information about arrays, see [Array Declarations](../c-language/array-declarations.md).) The `argv` parameter can be declared either as an array of pointers to type **`char`** (`char *argv[]`) or as a pointer to pointers to type **`char`** (`char **argv`). For **wmain**, the `argv` parameter can be declared either as an array of pointers to type **`wchar_t`** (`wchar_t *argv[]`) or as a pointer to pointers to type **`wchar_t`** (`wchar_t **argv`). +The *`argv`* parameter is an array of pointers to null-terminated strings representing the program arguments. Each element of the array points to a string representation of an argument passed to `main` (or `wmain`). (For information about arrays, see [Array declarations](../c-language/array-declarations.md).) The *`argv`* parameter can be declared either as an array of pointers to type **`char`** (`char *argv[]`) or as a pointer to pointers to type **`char`** (`char **argv`). For `wmain`, the *`argv`* parameter can be declared either as an array of pointers to type **`wchar_t`** (`wchar_t *argv[]`) or as a pointer to pointers to type **`wchar_t`** (`wchar_t **argv`). -By convention, `argv`**[0]** is the command with which the program is invoked. However, it is possible to spawn a process using [CreateProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) and if you use both the first and second arguments (`lpApplicationName` and `lpCommandLine`), `argv`**[0]** may not be the executable name; use [GetModuleFileName](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew) to retrieve the executable name. +By convention, `argv[0]` is the command with which the program is invoked. However, it's possible to spawn a process using [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) and if you use both the first and second arguments (`lpApplicationName` and `lpCommandLine`), `argv[0]` may not be the executable name; use [`GetModuleFileName`](/windows/win32/api/libloaderapi/nf-libloaderapi-getmodulefilenamew) to retrieve the executable name. -The last pointer (`argv[argc]`) is **NULL**. (See [getenv](../c-runtime-library/reference/getenv-wgetenv.md) in the *Run-Time Library Reference* for an alternative method for getting environment variable information.) +The last pointer (`argv[argc]`) is `NULL`. (See [`getenv`](../c-runtime-library/reference/getenv-wgetenv.md) in the *Run-Time Library Reference* for an alternative method for getting environment variable information.) **Microsoft Specific** -The `envp` parameter is a pointer to an array of null-terminated strings that represent the values set in the user's environment variables. The `envp` parameter can be declared as an array of pointers to **`char`** (`char *envp[]`) or as a pointer to pointers to **`char`** (`char **envp`). In a **wmain** function, the `envp` parameter can be declared as an array of pointers to **`wchar_t`** (`wchar_t *envp[]`) or as a pointer to pointers to **`wchar_t`** (`wchar_t **envp`). The end of the array is indicated by a **NULL** \*pointer. Note that the environment block passed to **main** or **wmain** is a "frozen" copy of the current environment. If you subsequently change the environment via a call to _**putenv** or `_wputenv`, the current environment (as returned by `getenv`/`_wgetenv` and the `_environ` or `_wenviron` variables) will change, but the block pointed to by `envp` will not change. The `envp` parameter is ANSI compatible in C, but not in C++. +The *`envp`* parameter is a pointer to an array of null-terminated strings that represent the values set in the user's environment variables. The *`envp`* parameter can be declared as an array of pointers to **`char`** (`char *envp[]`) or as a pointer to pointers to **`char`** (`char **envp`). In a `wmain` function, the *`envp`* parameter can be declared as an array of pointers to **`wchar_t`** (`wchar_t *envp[]`) or as a pointer to pointers to **`wchar_t`** (`wchar_t **envp`). The end of the array is indicated by a `NULL*` pointer. The environment block passed to `main` or `wmain` is a "frozen" copy of the current environment. If you later change the environment via a call to `_putenv` or `_wputenv`, the current environment (as returned by `getenv`/`_wgetenv` and the `_environ` or `_wenviron` variables) will change, but the block pointed to by *`envp`* won't change. The *`envp`* parameter is ANSI/ISO C89 compatible in C, but is a Microsoft extension in C++. **END Microsoft Specific** ## See also -[main Function and Program Execution](../c-language/main-function-and-program-execution.md) +[`main` function and program execution](../c-language/main-function-and-program-execution.md) diff --git a/docs/c-language/arguments-to-main.md b/docs/c-language/arguments-to-main.md index 1c09eb08f89..844ed2be7c6 100644 --- a/docs/c-language/arguments-to-main.md +++ b/docs/c-language/arguments-to-main.md @@ -1,32 +1,32 @@ --- description: "Learn more about: Arguments to main" title: "Arguments to main" -ms.date: "11/04/2016" +ms.date: 09/28/2022 ms.assetid: 39824fef-05ad-461d-ae82-49447dda8060 --- # Arguments to main **ANSI 2.1.2.2.1** The semantics of the arguments to main -In Microsoft C, the function called at program startup is called **main**. There is no prototype declared for **main**, and it can be defined with zero, two, or three parameters: +In Microsoft C, the function called at program startup is called **`main`**. There's no prototype declared for **`main`**, and it can be defined with zero, two, or three parameters: -``` +```C int main( void ) int main( int argc, char *argv[] ) int main( int argc, char *argv[], char *envp[] ) ``` -The third line above, where **main** accepts three parameters, is a Microsoft extension to the ANSI C standard. The third parameter, **envp**, is an array of pointers to environment variables. The **envp** array is terminated by a null pointer. See [The main Function and Program Execution](../c-language/main-function-and-program-execution.md) for more information about **main** and **envp**. +The third line above, where **`main`** accepts three parameters, is a Microsoft extension to the ANSI C standard. The third parameter, *`envp`*, is an array of pointers to environment variables. The *`envp`* array is terminated by a null pointer. For more information about **`main`** and *`envp`*, see [The `main` function and program execution](../c-language/main-function-and-program-execution.md). -The variable **argc** never holds a negative value. +The variable *`argc`* never holds a negative value. -The array of strings ends with **argv[argc]**, which contains a null pointer. +The array of strings ends with `argv[argc]`, which contains a null pointer. -All elements of the **argv** array are pointers to strings. +All elements of the *`argv`* array are pointers to strings. -A program invoked with no command-line arguments will receive a value of one for **argc**, as the name of the executable file is placed in **argv[0]**. (In MS-DOS versions prior to 3.0, the executable-file name is not available. The letter "C" is placed in **argv[0]**.) Strings pointed to by **argv[1]** through **argv[argc - 1]** represent program parameters. +A program invoked with no command-line arguments will receive a value of 1 for *`argc`*, as the name of the executable file is placed in `argv[0]`. (In MS-DOS versions prior to 3.0, the executable-file name isn't available. The letter "C" is placed in `argv[0]`.) Strings pointed to by `argv[1]` through `argv[argc - 1]` represent program parameters. -The parameters **argc** and **argv** are modifiable and retain their last-stored values between program startup and program termination. +The parameters *`argc`* and *`argv`* are modifiable and retain their last-stored values between program startup and program termination. ## See also diff --git a/docs/c-language/array-declarations.md b/docs/c-language/array-declarations.md index bf6e678fa31..cf593aeb028 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 69596997f4c..1e2d2e35de3 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 61b11671208..470da893c54 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 2fcedeb2ec4..3766b3dd90b 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 f3f9aaa6f52..13d26b72381 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 f2f2ad8b858..c42d7402c8b 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 f581def8fc8..ddd8fac1af9 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 dc7bf20e970..e96fe00a6fb 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 cb2d216b87a..bae13131370 100644 --- a/docs/c-language/c-comments.md +++ b/docs/c-language/c-comments.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C Comments" title: "C Comments" -ms.date: "06/25/2018" +description: "Learn more about: C Comments" +ms.date: 06/25/2018 helpviewer_keywords: ["code comments, C code", "comments, documenting code", "comments, C code", "/* */ comment delimiters", "comments"] -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 +31,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 +50,13 @@ While you can use comments to render certain lines of code inactive for test pur **Microsoft Specific** -The Microsoft compiler also supports single-line comments preceded by two forward slashes (__//__). If you compile with /Za (ANSI standard), these comments generate errors. These comments cannot extend to a second line. +The Microsoft compiler also supports single-line comments preceded by two forward slashes (**`//`**). These comments can't extend to a second line. ```C // This is a valid comment ``` -Comments beginning with two forward slashes (__//__) are terminated by the next newline character that is not preceded by an escape character. In the next example, the newline character is preceded by a backslash (**\\**), creating an "escape sequence." This escape sequence causes the compiler to treat the next line as part of the previous line. (For more information, see [Escape Sequences](../c-language/escape-sequences.md).) +Comments beginning with two forward slashes (**`//`**) are terminated by the next newline character that isn't preceded by an escape character. In the next example, the newline character is preceded by a backslash (**`\`**), creating an "escape sequence." This escape sequence causes the compiler to treat the next line as part of the previous line. For more information, see [Escape Sequences](../c-language/escape-sequences.md). ```C // my comment \ diff --git a/docs/c-language/c-enumeration-declarations.md b/docs/c-language/c-enumeration-declarations.md index 6f9153022e2..08d1312b461 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 fc0a4780327..544263691b6 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 f95d2948520..98876f7e43d 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 e0808d14906..91f45c71fb7 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 4cc86b8a4c6..56a44d534e9 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 d552935d9b8..03a08c77eaa 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 7ab089e3970..37810945be6 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 72b67af5833..986ee8c86cb 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 da10c1a8b0e..a80001ce714 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-pragmas.md b/docs/c-language/c-pragmas.md index e98dccbd721..bb5cb70aee4 100644 --- a/docs/c-language/c-pragmas.md +++ b/docs/c-language/c-pragmas.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: C Pragmas" title: "C Pragmas" +description: "Learn more about: C Pragmas" ms.date: 07/26/2020 helpviewer_keywords: ["pragmas, C/C++"] -ms.assetid: 3d6d36b4-d565-4632-a4cd-e39aeaded5ad --- # C Pragmas @@ -59,7 +58,7 @@ A *pragma* instructs the compiler to perform a particular action at compile time :::column-end::: :::row-end::: -See [Pragma Directives and the `__Pragma` Keyword](../preprocessor/pragma-directives-and-the-pragma-keyword.md) for a description of the Microsoft C compiler pragmas. +See [Pragma directives and the `__pragma` and `_Pragma` keywords](../preprocessor/pragma-directives-and-the-pragma-keyword.md) for a description of the Microsoft C compiler pragmas. **END Microsoft Specific** diff --git a/docs/c-language/c-primary-expressions.md b/docs/c-language/c-primary-expressions.md index 81a50ee1150..b2939192a28 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 7451821364e..d0a11781039 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 d558b04a56e..7ad68fdbfb8 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 247e0a3707b..54b5432c767 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 7e39df41447..d00556d9fa6 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 0cffa4a1bd2..a8ba159155f 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 104e0f38aea..b62c8f56fc4 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 57df56958f6..237a207f9f7 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 f3c48a567a3..f395a11aa11 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 e427bcfc9f9..4dfba70eff3 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 5cb99ac73d0..7804883b742 100644 --- a/docs/c-language/continue-statement-c.md +++ b/docs/c-language/continue-statement-c.md @@ -11,7 +11,7 @@ The **`continue`** statement passes control to the next iteration of the nearest ## Syntax -*`jump-statement`*:
+*`jump-statement`*:\  **`continue ;`** The next iteration of a **`do`**, **`for`**, or **`while`** statement is determined as follows: diff --git a/docs/c-language/conversions-from-signed-integral-types.md b/docs/c-language/conversions-from-signed-integral-types.md index 12027dad246..607b4314572 100644 --- a/docs/c-language/conversions-from-signed-integral-types.md +++ b/docs/c-language/conversions-from-signed-integral-types.md @@ -1,13 +1,13 @@ --- description: "Learn more about: Conversions from signed integral types" title: "Conversions from signed integral types" -ms.date: "10/02/2019" +ms.date: 12/06/2022 helpviewer_keywords: ["integral conversions, from signed", "integers, converting", "conversions [C++], integral", "data type conversion [C++], signed and unsigned integers", "type conversion [C++], signed and unsigned integers"] ms.assetid: 5eea32f8-8b14-413d-acac-c063b3d118d7 --- # Conversions from signed integral types -When a signed integer is converted to an integer or a floating-point type, if the original value is representable in the result type, the value is unchanged. +When a signed integer is converted to an integer or a floating-point type, the value is unchanged if it's representable in the result type. When a signed integer is converted to an integer of greater size, the value is sign-extended. When converted to an integer of smaller size, the high-order bits are truncated. The result is interpreted using the result type, as shown in this example: @@ -19,7 +19,7 @@ u = i; printf_s( "%hu\n", u ); // Prints 65533 ``` -When converting a signed integer to a floating-point type, if the original value isn't representable exactly in the result type, the result is the next higher or lower representable value. +When the compiler converts a signed integer to a floating-point type, if the original value isn't representable exactly in the result type, the result is the next higher or lower representable value. For information about the sizes of integral and floating-point types, see [Storage of basic types](../c-language/storage-of-basic-types.md). @@ -33,48 +33,48 @@ In the Microsoft compiler, **`int`** and **`long`** are distinct but equivalent ## Table of conversions from signed integral types -|From|To|Method| -|----------|--------|------------| -|**`char`**1|**`short`**|Sign-extend| -|**`char`**|**`long`**|Sign-extend| -|**`char`**|**`long long`**|Sign-extend| -|**`char`**|**`unsigned char`**|Preserve pattern; high-order bit loses function as sign bit| -|**`char`**|**`unsigned short`**|Sign-extend to **`short`**; convert **`short`** to **`unsigned short`**| -|**`char`**|**`unsigned long`**|Sign-extend to **`long`**; convert **`long`** to **`unsigned long`**| -|**`char`**|**`unsigned long long`**|Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`**| -|**`char`**|**`float`**|Sign-extend to **`long`**; convert **`long`** to **`float`**| -|**`char`**|**`double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`char`**|**`long double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`short`**|**`char`**|Preserve low-order byte| -|**`short`**|**`long`**|Sign-extend| -|**`short`**|**`long long`**|Sign-extend| -|**`short`**|**`unsigned char`**|Preserve low-order byte| -|**`short`**|**`unsigned short`**|Preserve bit pattern; high-order bit loses function as sign bit| -|**`short`**|**`unsigned long`**|Sign-extend to **`long`**; convert **`long`** to **`unsigned long`**| -|**`short`**|**`unsigned long long`**|Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`**| -|**`short`**|**`float`**|Sign-extend to **`long`**; convert **`long`** to **`float`**| -|**`short`**|**`double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`short`**|**`long double`**|Sign-extend to **`long`**; convert **`long`** to **`double`**| -|**`long`**|**`char`**|Preserve low-order byte| -|**`long`**|**`short`**|Preserve low-order word| -|**`long`**|**`long long`**|Sign-extend| -|**`long`**|**`unsigned char`**|Preserve low-order byte| -|**`long`**|**`unsigned short`**|Preserve low-order word| -|**`long`**|**`unsigned long`**|Preserve bit pattern; high-order bit loses function as sign bit| -|**`long`**|**`unsigned long long`**|Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`**| -|**`long`**|**`float`**|Represent as **`float`**. If **`long`** can't be represented exactly, some precision is lost.| -|**`long`**|**`double`**|Represent as **`double`**. If **`long`** can't be represented exactly as a **`double`**, some precision is lost.| -|**`long`**|**`long double`**|Represent as **`double`**. If **`long`** can't be represented exactly as a **`double`**, some precision is lost.| -|**`long long`**|**`char`**|Preserve low-order byte| -|**`long long`**|**`short`**|Preserve low-order word| -|**`long long`**|**`long`**|Preserve low-order dword| -|**`long long`**|**`unsigned char`**|Preserve low-order byte| -|**`long long`**|**`unsigned short`**|Preserve low-order word| -|**`long long`**|**`unsigned long`**|Preserve low-order dword| -|**`long long`**|**`unsigned long long`**|Preserve bit pattern; high-order bit loses function as sign bit| -|**`long long`**|**`float`**|Represent as **`float`**. If **`long long`** can't be represented exactly, some precision is lost.| -|**`long long`**|**`double`**|Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost.| -|**`long long`**|**`long double`**|Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost.| +| From | To | Method | +|---|---|---| +| **`char`**1 | **`short`** | Sign-extend | +| **`char`** | **`long`** | Sign-extend | +| **`char`** | **`long long`** | Sign-extend | +| **`char`** | **`unsigned char`** | Preserve pattern; high-order bit loses function as sign bit | +| **`char`** | **`unsigned short`** | Sign-extend to **`short`**; convert **`short`** to **`unsigned short`** | +| **`char`** | **`unsigned long`** | Sign-extend to **`long`**; convert **`long`** to **`unsigned long`** | +| **`char`** | **`unsigned long long`** | Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`** | +| **`char`** | **`float`** | Represent exactly as **`float`** | +| **`char`** | **`double`** | Represent exactly as **`double`** | +| **`char`** | **`long double`** | Represent exactly as **`long double`** | +| **`short`** | **`char`** | Preserve low-order byte | +| **`short`** | **`long`** | Sign-extend | +| **`short`** | **`long long`** | Sign-extend | +| **`short`** | **`unsigned char`** | Preserve low-order byte | +| **`short`** | **`unsigned short`** | Preserve bit pattern; high-order bit loses function as sign bit | +| **`short`** | **`unsigned long`** | Sign-extend to **`long`**; convert **`long`** to **`unsigned long`** | +| **`short`** | **`unsigned long long`** | Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`** | +| **`short`** | **`float`** | Represent exactly as **`float`** | +| **`short`** | **`double`** | Represent exactly as **`double`** | +| **`short`** | **`long double`** | Represent exactly as **`long double`** | +| **`long`** | **`char`** | Preserve low-order byte | +| **`long`** | **`short`** | Preserve low-order word | +| **`long`** | **`long long`** | Sign-extend | +| **`long`** | **`unsigned char`** | Preserve low-order byte | +| **`long`** | **`unsigned short`** | Preserve low-order word | +| **`long`** | **`unsigned long`** | Preserve bit pattern; high-order bit loses function as sign bit | +| **`long`** | **`unsigned long long`** | Sign-extend to **`long long`**; convert **`long long`** to **`unsigned long long`** | +| **`long`** | **`float`** | Represent as **`float`**. If **`long`** can't be represented exactly, some precision is lost. | +| **`long`** | **`double`** | Represent exactly as **`double`** | +| **`long`** | **`long double`** | Represent exactly as **`long double`** | +| **`long long`** | **`char`** | Preserve low-order byte | +| **`long long`** | **`short`** | Preserve low-order word | +| **`long long`** | **`long`** | Preserve low-order dword | +| **`long long`** | **`unsigned char`** | Preserve low-order byte | +| **`long long`** | **`unsigned short`** | Preserve low-order word | +| **`long long`** | **`unsigned long`** | Preserve low-order dword | +| **`long long`** | **`unsigned long long`** | Preserve bit pattern; high-order bit loses function as sign bit | +| **`long long`** | **`float`** | Represent as **`float`**. If **`long long`** can't be represented exactly, some precision is lost. | +| **`long long`** | **`double`** | Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost. | +| **`long long`** | **`long double`** | Represent as **`double`**. If **`long long`** can't be represented exactly as a **`double`**, some precision is lost. | 1 All **`char`** entries assume that the **`char`** type is signed by default. diff --git a/docs/c-language/conversions-from-unsigned-integral-types.md b/docs/c-language/conversions-from-unsigned-integral-types.md index df5f8de7643..4330ab68512 100644 --- a/docs/c-language/conversions-from-unsigned-integral-types.md +++ b/docs/c-language/conversions-from-unsigned-integral-types.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Conversions from unsigned integral types" title: "Conversions from unsigned integral types" -ms.date: "10/02/2019" +ms.date: 12/06/2022 helpviewer_keywords: ["integers, converting", "type casts, involving integers", "data type conversion [C++], signed and unsigned integers", "type conversion [C++], signed and unsigned integers", "integral conversions, from unsigned"] ms.assetid: 60fb7e10-bff9-4a13-8a48-e19f25a36a02 --- @@ -9,7 +9,7 @@ ms.assetid: 60fb7e10-bff9-4a13-8a48-e19f25a36a02 When an unsigned integer is converted to an integer or floating-point type, if the original value is representable in the result type the value is unchanged. -When converting an unsigned integer to an integer of greater size, the value is zero-extended. When converting to an integer of smaller size, the high-order bits are truncated. The result is interpreted using the result type, as shown in this example. +When the compiler converts an unsigned integer to an integer of greater size, the value is zero-extended. When converted to an integer of smaller size, the high-order bits are truncated. The result is interpreted using the result type, as shown in this example: ```C unsigned k = 65533; @@ -19,7 +19,7 @@ j = k; printf_s( "%hd\n", j ); // Prints -3 ``` -When converting an unsigned integer to a floating-point type, if the original value can't be represented exactly in the result type, the result is the next higher or lower representable value. +When the compiler converts an unsigned integer to a floating-point type, if the original value isn't representable exactly in the result type, the result is the next higher or lower representable value. See [Storage of basic types](../c-language/storage-of-basic-types.md) for information about the sizes of integral and floating-point types. @@ -33,48 +33,48 @@ The following table summarizes conversions from unsigned integral types. ## Table of conversions from unsigned integral types -|From|To|Method| -|----------|--------|------------| -|**`unsigned char`**|**`char`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned char`**|**`short`**|Zero-extend| -|**`unsigned char`**|**`long`**|Zero-extend| -|**`unsigned char`**|**`long long`**|Zero-extend| -|**`unsigned char`**|**`unsigned short`**|Zero-extend| -|**`unsigned char`**|**`unsigned long`**|Zero-extend| -|**`unsigned char`**|**`unsigned long long`**|Zero-extend| -|**`unsigned char`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned char`**|**`double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned char`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned short`**|**`char`**|Preserve low-order byte| -|**`unsigned short`**|**`short`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned short`**|**`long`**|Zero-extend| -|**`unsigned short`**|**`long long`**|Zero-extend| -|**`unsigned short`**|**`unsigned char`**|Preserve low-order byte| -|**`unsigned short`**|**`unsigned long`**|Zero-extend| -|**`unsigned short`**|**`unsigned long long`**|Zero-extend| -|**`unsigned short`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned short`**|**`double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned short`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned long`**|**`char`**|Preserve low-order byte| -|**`unsigned long`**|**`short`**|Preserve low-order word| -|**`unsigned long`**|**`long`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned long`**|**`long long`**|Zero-extend| -|**`unsigned long`**|**`unsigned char`**|Preserve low-order byte| -|**`unsigned long`**|**`unsigned short`**|Preserve low-order word| -|**`unsigned long`**|**`unsigned long long`**|Zero-extend| -|**`unsigned long`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned long`**|**`double`**|Convert directly to **`double`**| -|**`unsigned long`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| -|**`unsigned long long`**|**`char`**|Preserve low-order byte| -|**`unsigned long long`**|**`short`**|Preserve low-order word| -|**`unsigned long long`**|**`long`**|Preserve low-order dword| -|**`unsigned long long`**|**`long long`**|Preserve bit pattern; high-order bit becomes sign bit| -|**`unsigned long long`**|**`unsigned char`**|Preserve low-order byte| -|**`unsigned long long`**|**`unsigned short`**|Preserve low-order word| -|**`unsigned long long`**|**`unsigned long`**|Preserve low-order dword| -|**`unsigned long long`**|**`float`**|Convert to **`long`**; convert **`long`** to **`float`**| -|**`unsigned long long`**|**`double`**|Convert directly to **`double`**| -|**`unsigned long long`**|**`long double`**|Convert to **`long`**; convert **`long`** to **`double`**| +| From | To | Method | +|---|---|---| +| **`unsigned char`** | **`char`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned char`** | **`short`** | Zero-extend | +| **`unsigned char`** | **`long`** | Zero-extend | +| **`unsigned char`** | **`long long`** | Zero-extend | +| **`unsigned char`** | **`unsigned short`** | Zero-extend | +| **`unsigned char`** | **`unsigned long`** | Zero-extend | +| **`unsigned char`** | **`unsigned long long`** | Zero-extend | +| **`unsigned char`** | **`float`** | Convert exactly to **`float`** | +| **`unsigned char`** | **`double`** | Convert exactly to **`double`** | +| **`unsigned char`** | **`long double`** | Convert exactly to **`long double`** | +| **`unsigned short`** | **`char`** | Preserve low-order byte | +| **`unsigned short`** | **`short`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned short`** | **`long`** | Zero-extend | +| **`unsigned short`** | **`long long`** | Zero-extend | +| **`unsigned short`** | **`unsigned char`** | Preserve low-order byte | +| **`unsigned short`** | **`unsigned long`** | Zero-extend | +| **`unsigned short`** | **`unsigned long long`** | Zero-extend | +| **`unsigned short`** | **`float`** | Convert exactly to **`float`** | +| **`unsigned short`** | **`double`** | Convert exactly to **`double`** | +| **`unsigned short`** | **`long double`** | Convert exactly to **`long double`** | +| **`unsigned long`** | **`char`** | Preserve low-order byte | +| **`unsigned long`** | **`short`** | Preserve low-order word | +| **`unsigned long`** | **`long`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned long`** | **`long long`** | Zero-extend | +| **`unsigned long`** | **`unsigned char`** | Preserve low-order byte | +| **`unsigned long`** | **`unsigned short`** | Preserve low-order word | +| **`unsigned long`** | **`unsigned long long`** | Zero-extend | +| **`unsigned long`** | **`float`** | Convert to nearest representable **`float`** | +| **`unsigned long`** | **`double`** | Convert exactly to **`double`** | +| **`unsigned long`** | **`long double`** | Convert exactly to **`long double`** | +| **`unsigned long long`** | **`char`** | Preserve low-order byte | +| **`unsigned long long`** | **`short`** | Preserve low-order word | +| **`unsigned long long`** | **`long`** | Preserve low-order dword | +| **`unsigned long long`** | **`long long`** | Preserve bit pattern; high-order bit becomes sign bit | +| **`unsigned long long`** | **`unsigned char`** | Preserve low-order byte | +| **`unsigned long long`** | **`unsigned short`** | Preserve low-order word | +| **`unsigned long long`** | **`unsigned long`** | Preserve low-order dword | +| **`unsigned long long`** | **`float`** | Convert to nearest representable **`float`** | +| **`unsigned long long`** | **`double`** | Convert to nearest representable **`double`** | +| **`unsigned long long`** | **`long double`** | Convert to nearest representable **`long double`** | ## See also diff --git a/docs/c-language/conversions-to-and-from-pointer-types.md b/docs/c-language/conversions-to-and-from-pointer-types.md index 6980b48742f..f14c6a2fb7c 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 82ebf2660ef..c860fb23360 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 c6c50541cdf..d8c27aab0aa 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 47dc3a7f246..672aee22223 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 f64f4104f9a..5cc14b16953 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 ca9fac1f5af..96fcb629259 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 e32b34331d2..eee10f7ed6e 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 3b4b7b76a76..e1d271617f4 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 0ab152e3971..36c21bc202f 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 749c6227aee..fc532686093 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 aeab60394f6..59f32728304 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 67579fbef55..c92740fedac 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 aae08b367c6..352ae7c97ea 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 dd14511130b..8d977b17188 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 85a4cdeff47..01f8a0cbd6f 100644 --- a/docs/c-language/function-prototypes.md +++ b/docs/c-language/function-prototypes.md @@ -11,32 +11,32 @@ A function declaration precedes the function definition and specifies the name, ## Syntax -*declaration*:
-    *declaration-specifiers* *attribute-seq*opt *init-declarator-list*opt **;** +*`declaration`*:\ + *`declaration-specifiers`* *`attribute-seq`*opt *`init-declarator-list`*opt **`;`** -/\* *attribute-seq*opt is Microsoft-specific \*/ +/\* *`attribute-seq`*opt is Microsoft-specific \*/ -*declaration-specifiers*:
-    *storage-class-specifier* *declaration-specifiers*opt
-    *type-specifier* *declaration-specifiers*opt
-    *type-qualifier* *declaration-specifiers*opt +*`declaration-specifiers`*:\ + *`storage-class-specifier`* *`declaration-specifiers`*opt \ + *`type-specifier`* *`declaration-specifiers`*opt \ + *`type-qualifier`* *`declaration-specifiers`*opt -*init-declarator-list*:
-    *init-declarator*
-    *init-declarator-list* **,** *init-declarator* +*`init-declarator-list`*:\ + *`init-declarator`*\ + *`init-declarator-list`* **`,`** *`init-declarator`* -*init-declarator*:
-    *declarator*
-    *declarator* **=** *initializer* +*`init-declarator`*:\ + *`declarator`*\ + *`declarator`* **`=`** *`initializer`* -*declarator*:
-    *pointer*opt *direct-declarator* +*`declarator`*:\ + *`pointer`*opt *`direct-declarator`* -*direct-declarator*: /\* A function declarator \*/
-    *direct-declarator* **(** *parameter-type-list* **)** /\* New-style declarator \*/
-    *direct-declarator* **(** *identifier-list*opt **)** /\* Obsolete-style declarator \*/ +*`direct-declarator`*: /\* A function declarator \*/\ + *`direct-declarator`* **`(`** *`parameter-type-list`* **`)`** /\* New-style declarator \*/\ + *`direct-declarator`* **`(`** *`identifier-list`*opt **`)`** /\* Obsolete-style declarator \*/ -The prototype has the same form as the function definition, except that it is terminated by a semicolon immediately following the closing parenthesis and therefore has no body. In either case, the return type must agree with the return type specified in the function definition. +The prototype has the same form as the function definition, except that it's terminated by a semicolon immediately following the closing parenthesis and therefore has no body. In either case, the return type must agree with the return type specified in the function definition. Function prototypes have the following important uses: @@ -48,7 +48,7 @@ Function prototypes have the following important uses: - The parameter list is used to check that arguments in the function call match the parameters in the function definition. -The converted type of each parameter determines the interpretation of the arguments that the function call places on the stack. A type mismatch between an argument and a parameter may cause the arguments on the stack to be misinterpreted. For example, on a 16-bit computer, if a 16-bit pointer is passed as an argument, then declared as a **`long`** parameter, the first 32 bits on the stack are interpreted as a **`long`** parameter. This error creates problems not only with the **`long`** parameter, but with any parameters that follow it. You can detect errors of this kind by declaring complete function prototypes for all functions. +The converted type of each parameter determines the interpretation of the arguments that the function call places on the stack. A type mismatch between an argument and a parameter may cause the arguments on the stack to be misinterpreted. For example, on a 16-bit computer, if a 16-bit pointer is passed as an argument, then declared as a **`long`** parameter, the first 32 bits on the stack are interpreted as a **`long`** parameter. This error creates problems not only with the **`long`** parameter, but with all the subsequent parameters. You can detect errors of this kind by declaring complete function prototypes for all functions. A prototype establishes the attributes of a function. Then, function calls that precede the function definition (or that occur in other source files) can be checked for argument-type and return-type mismatches. For example, if you specify the **`static`** storage-class specifier in a prototype, you must also specify the **`static`** storage class in the function definition. @@ -73,7 +73,7 @@ struct S; void func1( struct S * ); ``` -Under **/Ze**, the tag is still entered at global scope. +Under **`/Ze`**, the tag is still entered at global scope. ## See also diff --git a/docs/c-language/generic-selection.md b/docs/c-language/generic-selection.md index f5c1edd6c38..0eba6388e33 100644 --- a/docs/c-language/generic-selection.md +++ b/docs/c-language/generic-selection.md @@ -1,7 +1,7 @@ --- title: "Generic selection (C11)" description: "Describes the C11 _Generic keyword used in the Microsoft Visual C compiler" -ms.date: "6/29/2021" +ms.date: 6/29/2021 helpviewer_keywords: ["_Generic keyword [C]"] --- @@ -26,7 +26,7 @@ For example, the expression `_Generic(42, int: "integer", char: "character", def The first *`assignment-expression`* is called the controlling expression. The type of the controlling expression is determined at compile time and matched against the *`assoc-list`* to find which expression to evaluate and return. The controlling expression isn't evaluated. For example, `_Generic(intFunc(), int: "integer", default: "error");` doesn't result in a call at runtime to `intFunc`. -When the type of the controlling expression is determined, `const`, `volatile`, and `restrict` are removed before matching against *`assoc-list`*. +When the type of the controlling expression is determined, `const`, `volatile`, and `restrict` are removed before matching against *`assoc-list`*. Entries in the `assoc-list` that aren't chosen aren't evaluated. @@ -67,7 +67,6 @@ int main() /* Output: Type name: double */ - ``` ## Requirements diff --git a/docs/c-language/goto-and-labeled-statements-c.md b/docs/c-language/goto-and-labeled-statements-c.md index 799303884ed..712deb1f115 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 068726e077a..31ab1348987 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 feb5f6855ef..3f038a096b9 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 4b1c2b75535..b842ad54b30 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 ee4b75ca482..bcd7ca93c1f 100644 --- a/docs/c-language/initializing-scalar-types.md +++ b/docs/c-language/initializing-scalar-types.md @@ -1,46 +1,45 @@ --- -description: "Learn more about: Initializing Scalar Types" title: "Initializing Scalar Types" -ms.date: "11/04/2016" +description: "Learn more about: Initializing Scalar Types" +ms.date: 11/04/2016 helpviewer_keywords: ["initializing scalar types", "register variables", "initialization, scalar types", "initializing variables, scalar types", "scalar types", "static variables, initializing", "automatic storage class, initializing scalar types", "automatic storage class", "types [C], initializing"] -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 +61,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 +73,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 +87,7 @@ int function( void ) } ``` -The global variable `GLOBAL` is declared at the external level, so it has global lifetime. The local variable `LOCAL` has **`auto`** storage class and only has an address during the execution of the function in which it is declared. Therefore, attempting to initialize the **`static`** pointer variable `lp` with the address of `LOCAL` is not permitted. The **`static`** pointer variable `gp` can be initialized to the address of `GLOBAL` because that address is always the same. Similarly, `*rp` can be initialized because `rp` is a local variable and can have a non-constant initializer. Each time the block is entered, `LOCAL` has a new address, which is then assigned to `rp`. +The global variable `GLOBAL` is declared at the external level, so it has global lifetime. The local variable `LOCAL` has **`auto`** storage class and only has an address during the execution of the function in which it's declared. Therefore, attempting to initialize the **`static`** pointer variable `lp` with the address of `LOCAL` isn't permitted. The **`static`** pointer variable `gp` can be initialized to the address of `GLOBAL` because that address is always the same. Similarly, `*rp` can be initialized because `rp` is a local variable and can have a non-constant initializer. Each time the block is entered, `LOCAL` has a new address, which is then assigned to `rp`. ## See also diff --git a/docs/c-language/inline-functions.md b/docs/c-language/inline-functions.md index a9dbbdae814..86dae219ef5 100644 --- a/docs/c-language/inline-functions.md +++ b/docs/c-language/inline-functions.md @@ -1,15 +1,13 @@ --- description: "Learn more about: Inline Functions" title: "Inline Functions" -ms.date: 05/17/2022 +ms.date: 08/24/2022 helpviewer_keywords: ["fast code", "inline functions, __inline keyword", "functions [C++], inline functions"] ms.assetid: 00f4b2ff-8ad0-4165-9f4c-2ef157d03f31 --- # Inline functions -**Microsoft specific** - -The **`__inline`** keyword tells the compiler to substitute the code within the function definition for every instance of a function call. +The **`inline`** keyword is a function specifier that tells the compiler to substitute the code within the function definition for every instance of a function call. ## Remarks @@ -19,7 +17,7 @@ For a function to be considered as a candidate for inlining, it must use the new Use this form to specify an inline function: -> **`__inline`** *function-definition* +> **`inline`** *function-definition* Inline functions generate faster and sometimes smaller code than the equivalent function call: @@ -29,7 +27,13 @@ Inline functions generate faster and sometimes smaller code than the equivalent - The compiler can optimize functions generated inline in ways that aren't available to normal functions. The compiler doesn't usually perform optimizations between different procedures. -Don't confuse functions that use **`__inline`** with inline assembler code. For more information about inline assembler, see [Inline assembler](../c-language/inline-assembler-c.md). +Don't confuse functions that use **`inline`** with inline assembler code. For more information about inline assembler, see [Inline assembler](../c-language/inline-assembler-c.md). + +**Microsoft specific** + +Microsoft also supports **`__inline`** and **`__forceinline`** keywords to tell the compiler to substitute the code within the function definition for every instance of a function call. The **`__inline`** keyword is a synonym for **`inline`**. The **`__forceinline`** keyword tells the compiler to relax the heuristics on whether to inline the function, though it doesn't guarantee a function will be inlined. + +For compatibility with previous versions, **`_inline`** and **`_forceinline`** are synonyms for **`__inline`** and **`__forceinline`**, respectively, unless compiler option [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. **END Microsoft specific** diff --git a/docs/c-language/interpreting-more-complex-declarators.md b/docs/c-language/interpreting-more-complex-declarators.md index d780d03e134..938504a3815 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 90ee5316734..5a646ce54db 100644 --- a/docs/c-language/l-value-and-r-value-expressions.md +++ b/docs/c-language/l-value-and-r-value-expressions.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: L-Value and R-Value Expressions" title: "L-Value and R-Value Expressions" -ms.date: "11/04/2016" +description: "Learn more about: L-Value and R-Value Expressions" +ms.date: 11/04/2016 helpviewer_keywords: ["L-values", "member-selection expressions", "R-value expressions", "subscript expressions"] -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 +16,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 +30,7 @@ The term "r-value" is sometimes used to describe the value of an expression and **Microsoft Specific** -Microsoft C includes an extension to the ANSI C standard that allows casts of l-values to be used as l-values, as long as the size of the object is not lengthened through the cast. (See [Type-Cast Conversions](../c-language/type-cast-conversions.md) for more information.) The following example illustrates this feature: +Microsoft C includes an extension to the ANSI C standard that allows casts of l-values to be used as l-values, as long as the size of the object isn't lengthened through the cast. For more information, see [Type-Cast Conversions](../c-language/type-cast-conversions.md). The following example illustrates this feature: ``` char *p ; diff --git a/docs/c-language/lexical-grammar.md b/docs/c-language/lexical-grammar.md index 5a7a9e3bf7f..70757f0cf6c 100644 --- a/docs/c-language/lexical-grammar.md +++ b/docs/c-language/lexical-grammar.md @@ -187,7 +187,7 @@ For a list of additional Microsoft-specific keywords, see [C keywords](./c-keywo  *`c-char-sequence`* *`c-char`* *`c-char`*:\ - Any member of the source character set except the single quotation mark (**`'`**), backslash (**`\`**), or newline character\ + Any member of the source character set except the single quotation mark (**`'`**), backslash (**`\`**), or new-line character\  *`escape-sequence`* *`escape-sequence`*:\ @@ -225,7 +225,7 @@ For a list of additional Microsoft-specific keywords, see [C keywords](./c-keywo  *`s-char-sequence`* *`s-char`* *`s-char`*:\ - any member of the source character set except the double-quotation mark (**`"`**), backslash (**`\`**), or newline character\ + any member of the source character set except the double-quotation mark (**`"`**), backslash (**`\`**), or new-line character\  *`escape-sequence`* ## Punctuators diff --git a/docs/c-language/main-function-and-program-execution.md b/docs/c-language/main-function-and-program-execution.md index f4b6cd1e8f6..c12de71ba2b 100644 --- a/docs/c-language/main-function-and-program-execution.md +++ b/docs/c-language/main-function-and-program-execution.md @@ -1,31 +1,48 @@ --- -description: "Learn more about: main Function and Program Execution" -title: "main Function and Program Execution" -ms.date: "11/04/2016" +description: "Learn more about: main function and program execution" +title: "main function and program execution" +ms.date: 09/28/2022 helpviewer_keywords: ["program startup [C++]", "entry points, program", "main function, program execution", "startup code, main function", "main function", "programs [C++], terminating"] ms.assetid: 5984f1bd-072d-4e06-8640-122fb1454401 --- -# main Function and Program Execution +# `main` function and program execution -Every C program has a primary (main) function that must be named **main**. If your code adheres to the Unicode programming model, you can use the wide-character version of **main**, **wmain**. The **main** function serves as the starting point for program execution. It usually controls program execution by directing the calls to other functions in the program. A program usually stops executing at the end of **main**, although it can terminate at other points in the program for a variety of reasons. At times, perhaps when a certain error is detected, you may want to force the termination of a program. To do so, use the **exit** function. See the *Run-Time Library Reference* for information on and an example using the [exit](../c-runtime-library/reference/exit-exit-exit.md) function. +Every C program has a primary function that must be named `main`. The `main` function serves as the starting point for program execution. It usually controls program execution by directing the calls to other functions in the program. -## Syntax +Several restrictions apply to the `main` function that don't apply to any other C functions. The `main` function: -``` -main( int argc, char *argv[ ], char *envp[ ] ) +- Can't be declared as **`inline`**. +- Can't be declared as **`static`**. +- Can't have its address taken. +- Can't be called from your program. + +## The `main` function signature + +The `main` function doesn't have a declaration, because it's built into the language. If it did, the declaration syntax for `main` would look like this: + +```C +int main( void ); +int main( int argc, char *argv[ ] ); +int main( int argc, char *argv[ ], char *envp[ ] ); ``` +The `main` function is declared implicitly by using one of these signatures. You may use any of these signatures when you define your `main` function. The Microsoft compiler also allows `main` to have a return type of **`void`** when no value is returned. The *`argv`* and *`envp`* parameters to `wmain` can also be defined as type `char**`. For more information about the arguments, see [Argument description](./argument-description.md). + ## Remarks -Functions within the source program perform one or more specific tasks. The **main** function can call these functions to perform their respective tasks. When **main** calls another function, it passes execution control to the function, so that execution begins at the first statement in the function. A function returns control to **main** when a **`return`** statement is executed or when the end of the function is reached. +Functions within the source program perform one or more specific tasks. The `main` function can call these functions to perform their respective tasks. When `main` calls another function, it passes execution control to the function, so that execution begins at the first statement in the function. A function returns control to `main` when a **`return`** statement is executed or when the end of the function is reached. + +You can declare any function, including `main`, to have parameters. The term "parameter" or "formal parameter" refers to the identifier that receives a value passed to a function. See [Parameters](../c-language/parameters.md) for information on passing arguments to parameters. When one function calls another, the called function receives values for its parameters from the calling function. These values are called *arguments*. You can declare formal parameters to `main` so that it can receive arguments from the command line using the format shown in the function signature. + +When you want to pass information to the `main` function, the parameters are traditionally named *`argc`* and *`argv`*, although the C compiler doesn't require these names. Traditionally, if a third parameter is passed to `main`, that parameter is named *`envp`*. The types for *`argc`*, *`argv`*, and *`envp`* are defined by the C language. You can also declare *`argv`* as `char** argv` and *`envp`* as `char** envp`. Examples later in this section show how to use these three parameters to access command-line arguments. The following sections explain these parameters. -You can declare any function, including **main**, to have parameters. The term "parameter" or "formal parameter" refers to the identifier that receives a value passed to a function. See [Parameters](../c-language/parameters.md) for information on passing arguments to parameters. When one function calls another, the called function receives values for its parameters from the calling function. These values are called "arguments." You can declare formal parameters to **main** so that it can receive arguments from the command line using this format: +If your code adheres to the Unicode programming model, you can use the Microsoft-specific wide-character version of **`main`**, **`wmain`**, as your program's entry point. For more information about this wide-character version of **`main`**, see [Using `wmain`](../c-language/using-wmain.md). -When you want to pass information to the **main** function, the parameters are traditionally named `argc` and `argv`, although the C compiler does not require these names. The types for `argc` and `argv` are defined by the C language. Traditionally, if a third parameter is passed to **main**, that parameter is named `envp`. Examples later in this section show how to use these three parameters to access command-line arguments. The following sections explain these parameters. +## `main` termination -See [Using wmain](../c-language/using-wmain.md) for a description of the wide-character version of **main**. +A program usually stops executing when it returns from or reaches the end of `main`, although it can terminate at other points in the program for various reasons. For example, you may want to force the termination of your program when some error condition is detected. To do so, you can use the `exit` function. For more information on `exit` and an example of usage, see [`exit`](../c-runtime-library/reference/exit-exit-exit.md). ## See also -[main function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ -[Parsing C Command-Line Arguments](../c-language/parsing-c-command-line-arguments.md) +[`main` function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ +[Parsing C command-line arguments](../c-language/parsing-c-command-line-arguments.md) diff --git a/docs/c-language/multidimensional-arrays-c.md b/docs/c-language/multidimensional-arrays-c.md index 06fedbf4a4e..3aa1d2768be 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 f41ec42a2a5..7d525866b36 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 d0bdc880cf4..f436a95cb81 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 d3e6525bb39..8608b7ba86c 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 8e99b63b82c..131cec5c23f 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 8e5c6eefc27..f2eb26888e8 100644 --- a/docs/c-language/parameters.md +++ b/docs/c-language/parameters.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Parameters" title: "Parameters" -ms.date: "11/04/2016" +description: "Learn more about: Parameters" +ms.date: 11/04/2016 helpviewer_keywords: ["arguments [C++], function", "function parameters", "parameters [C++]", "function arguments, vs. parameters", "parameters [C++], function", "functions [C], parameters", "function parameters, syntax", "ellipsis (...), parameters", "... ellipsis"] -ms.assetid: 8f2b8026-78b5-4e21-86a3-bf0f91f05689 --- # Parameters @@ -11,29 +10,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: @@ -50,7 +49,7 @@ void new( double x, double y, double z ) } ``` -If at least one parameter occurs in the parameter list, the list can end with a comma followed by three periods (**`, ...`**). This construction, called the "ellipsis notation," indicates a variable number of arguments to the function. (For more information, see [Calls with a Variable Number of Arguments](../c-language/calls-with-a-variable-number-of-arguments.md).) However, a call to the function must have at least as many arguments as there are parameters before the last comma. +If at least one parameter occurs in the parameter list, the list can end with a comma followed by three periods (**`, ...`**). This construction, called the "ellipsis notation," indicates a variable number of arguments to the function. For more information, see [Calls with a Variable Number of Arguments](../c-language/calls-with-a-variable-number-of-arguments.md). However, a call to the function must have at least as many arguments as there are parameters before the last comma. If no arguments are to be passed to the function, the list of parameters is replaced by the keyword **`void`**. This use of **`void`** is distinct from its use as a type specifier. diff --git a/docs/c-language/pointer-declarations.md b/docs/c-language/pointer-declarations.md index 022967a4143..b189f3cd6f2 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 a862e108272..9f2aa682696 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 57eb60e450c..e5f0d686d0f 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 05297d66d15..653e79678b0 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 179defafeb3..8f61550b6cb 100644 --- a/docs/c-language/scope-and-visibility.md +++ b/docs/c-language/scope-and-visibility.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Scope and Visibility" title: "Scope and Visibility" -ms.date: "11/04/2016" +description: "Learn more about: Scope and Visibility" +ms.date: 11/04/2016 helpviewer_keywords: ["scope, levels", "visibility", "file scope [C++]"] -ms.assetid: a019eb7c-66ed-46a7-bc9f-89a963930a56 --- # Scope and Visibility @@ -11,16 +10,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 -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).) +**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 5860fb88f2d..992ccf4363c 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 daaa2158835..895313b2985 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 225e7f01e55..240db4af66e 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 dc8ab22981c..99455cab88f 100644 --- a/docs/c-language/static-assert-c.md +++ b/docs/c-language/static-assert-c.md @@ -42,7 +42,7 @@ In C, when you don't include ``, the Microsoft compiler treats **`stat In the following example, **`static_assert`** and **`_Static_assert`** are used to verify how many elements are in an enum and that integers are 32 bits wide. ```C -// requires /std:c11 or higher +// requires /std:c11 or later #include enum Items @@ -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 1032e70a321..e48c280822a 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 7eb9b1d56b1..c4b93d2c53d 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 21c75e6b9c3..273a8e7977e 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 98fbb1ef453..3660b1788f5 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 a1b6811b90d..e0bc7d54927 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 df8e11d5203..975beb742bc 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 **`;`**\ @@ -21,7 +21,7 @@ ms.assetid: 53a5e9e5-1a33-40b5-9dea-7f669b479329  *`attribute`*1 *`attribute-seq`*opt1 *`attribute`*1, 2: one of\ - **`__asm`** **`__based`** **`__cdecl`** **`__clrcall`** **`__fastcall`** **`__inline`** **`__stdcall`** **`__thiscall`** **`__vectorcall`** + **`__asm`** **`__based`** **`__cdecl`** **`__clrcall`** **`__fastcall`** **`__inline`** **`__stdcall`** **`__thiscall`** **`__vectorcall`** **`__preserve_none`** *`init-declarator-list`*:\  *`init-declarator`*\ @@ -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), [`__preserve_none`](../cpp/preserve-none.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 be4e226df08..6e6e98aa362 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 414efdeed77..8f9394ed80f 100644 --- a/docs/c-language/switch-statement-c.md +++ b/docs/c-language/switch-statement-c.md @@ -13,12 +13,12 @@ The **`switch`** and **`case`** statements help control complex conditional and ## Syntax -> *`selection-statement`*:\ ->      **`switch (`** *`expression`*  **`)`** *`statement`* +*`selection-statement`*:\ +  **`switch (`** *`expression`* **`)`** *`statement`* -> *`labeled-statement`*:\ ->      **`case`** *`constant-expression`* **`:`** *`statement`*\ ->      **`default`** **`:`** *`statement`* +*`labeled-statement`*:\ +  **`case`** *`constant-expression`* **`:`** *`statement`*\ +  **`default`** **`:`** *`statement`* ## Remarks @@ -103,7 +103,7 @@ switch( c ) } ``` -In this example, if *constant-expression* equals any letter between `'a'` and `'f'`, the `convert_hex` function is called. +In this example, if *`constant-expression`* equals any letter between `'a'` and `'f'`, the `convert_hex` function is called. ### Microsoft-specific diff --git a/docs/c-language/system-function.md b/docs/c-language/system-function.md index 95609210cf4..35ef3def660 100644 --- a/docs/c-language/system-function.md +++ b/docs/c-language/system-function.md @@ -9,9 +9,9 @@ ms.assetid: 0786ccdc-20cd-4d96-b3d8-3230507c3066 **ANSI 4.10.4.5** The contents and mode of execution of the string by the **system** function -The **system** function executes an internal operating system command, or an .EXE, .COM (.CMD in Windows NT) or .BAT file from within a C program rather than from the command line. +The **system** function executes an internal operating system command, or an .EXE, .COM, .CMD, or .BAT file from within a C program rather than from the command line. -The system function finds the command interpreter, which is typically CMD.EXE in the Windows NT operating system or COMMAND.COM in Windows. The system function then passes the argument string to the command interpreter. +The system function finds the command interpreter, which is typically CMD.EXE in the Windows operating system. The system function then passes the argument string to the command interpreter. For more information, see [system, _wsystem](../c-runtime-library/reference/system-wsystem.md). diff --git a/docs/c-language/toc.yml b/docs/c-language/toc.yml index bdec148f7a9..13334cd6b4e 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 @@ -440,7 +444,7 @@ items: - name: Inline assembler (C) href: ../c-language/inline-assembler-c.md - name: _Noreturn (C) - href: ../c-language/noreturn.md + href: ../c-language/noreturn.md - name: DLL import and export functions items: - name: DLL import and export functions diff --git a/docs/c-language/type-cast-conversions.md b/docs/c-language/type-cast-conversions.md index 925ddeba367..f73cde27f3d 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 898ab631bd3..b503212b6c4 100644 --- a/docs/c-language/typedef-declarations.md +++ b/docs/c-language/typedef-declarations.md @@ -1,49 +1,48 @@ --- -description: "Learn more about: Typedef Declarations" title: "Typedef Declarations" -ms.date: "11/04/2016" +description: "Learn more about: Typedef Declarations" +ms.date: 11/04/2016 helpviewer_keywords: ["declarations, typedef", "typedef declarations", "types [C], declarations"] -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 +57,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 +70,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 +82,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 +102,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 +112,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 +125,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 00000000000..15376699428 --- /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 00000000000..7786d9ecb8b --- /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 03f8d046bc7..7a0a0cd01e3 100644 --- a/docs/c-language/union-declarations.md +++ b/docs/c-language/union-declarations.md @@ -5,42 +5,42 @@ ms.date: "11/04/2016" helpviewer_keywords: ["unions", "union keyword [C], declarations", "variant records"] ms.assetid: 978c6165-e0ae-4196-afa7-6d94e24f62f7 --- -# Union Declarations +# `union` Declarations A "union declaration" specifies a set of variable values and, optionally, a tag naming the union. The variable values are called "members" of the union and can have different types. Unions are similar to "variant records" in other languages. ## Syntax -*struct-or-union-specifier*:
-    *struct-or-union* *identifier*opt **{** *struct-declaration-list* **}**
-    *struct-or-union* *identifier* +*`struct-or-union-specifier`*:\ + *`struct-or-union`* *`identifier`*opt **`{`** *`struct-declaration-list`* **`}`**\ + *`struct-or-union`* *`identifier`* -*struct-or-union*:
-    **`struct`**
-    **`union`** +*`struct-or-union`*:\ + **`struct`**\ + **`union`** -*struct-declaration-list*:
-    *struct-declaration*
-    *struct-declaration-list* *struct-declaration* +*`struct-declaration-list`*:\ + *`struct-declaration`*\ + *`struct-declaration-list`* *`struct-declaration`* The union content is defined to be -*struct-declaration*:
-    *specifier-qualifier-list* *struct-declarator-list* **;** +*`struct-declaration`*:\ + *`specifier-qualifier-list`* *`struct-declarator-list`* **`;`** -*specifier-qualifier-list*:
-    *type-specifier* *specifier-qualifier-list*opt
-    *type-qualifier* *specifier-qualifier-list*opt +*`specifier-qualifier-list`*:\ + *`type-specifier`* *`specifier-qualifier-list`*opt \ + *`type-qualifier`* *`specifier-qualifier-list`*opt -*struct-declarator-list*:
-    *struct-declarator*
-    *struct-declarator-list* **,** *struct-declarator* +*`struct-declarator-list`*:\ + *`struct-declarator`*\ + *`struct-declarator-list`* **`,`** *`struct-declarator`* A variable with **`union`** type stores one of the values defined by that type. The same rules govern structure and union declarations. Unions can also have bit fields. -Members of unions cannot have an incomplete type, type **`void`**, or function type. Therefore members cannot be an instance of the union but can be pointers to the union type being declared. +Members of unions can't have an incomplete type, type **`void`**, or function type. Therefore members can't be an instance of the union but can be pointers to the union type being declared. -A union type declaration is a template only. Memory is not reserved until the variable is declared. +A union type declaration is a template only. Memory isn't reserved until the variable is declared. > [!NOTE] > If a union of two types is declared and one value is stored, but the union is accessed with the other type, the results are unreliable. For example, a union of **`float`** and **`int`** is declared. A **`float`** value is stored, but the program later accesses the value as an **`int`**. In such a situation, the value would depend on the internal storage of **`float`** values. The integer value would not be reliable. @@ -75,13 +75,13 @@ The `screen` array contains 2,000 elements. Each element of the array is an indi **Microsoft Specific** -Nested unions can be declared anonymously when they are members of another structure or union. This is an example of a nameless union: +Nested unions can be declared anonymously when they're members of another structure or union. Here's an example of a nameless union: ```C struct str { int a, b; - union / * Unnamed union */ + union /* Unnamed union */ { char c[4]; long l; @@ -95,7 +95,7 @@ struct str my_str.l == 0L; /* A reference to a field in the my_str union */ ``` -Unions are often nested within a structure that includes a field giving the type of data contained in the union at any particular time. This is an example of a declaration for such a union: +Unions are often nested within a structure that includes a field giving the type of data contained in the union at any particular time. Here's an example of a declaration for such a union: ```C struct x diff --git a/docs/c-language/using-wmain.md b/docs/c-language/using-wmain.md index 6d6844dae0a..a3c80968332 100644 --- a/docs/c-language/using-wmain.md +++ b/docs/c-language/using-wmain.md @@ -1,34 +1,45 @@ --- description: "Learn more about: Using wmain" title: "Using wmain" -ms.date: "11/04/2016" +ms.date: 09/27/2022 helpviewer_keywords: ["wmain function"] ms.assetid: d0300812-adc4-40c6-bba3-b2da25468c80 --- -# Using wmain +# Using `wmain` **Microsoft Specific** -In the Unicode programming model, you can define a wide-character version of the **main** function. Use **wmain** instead of **main** if you want to write portable code that adheres to the Unicode programming model. +In the Unicode programming model, you can define a wide-character version of the `main` function. Use `wmain` instead of `main` if you want to write portable code that adheres to the Unicode programming model. -## Syntax +Like `main`, several restrictions apply to the `wmain` function that don't apply to any other C functions. The `wmain` function: -``` -wmain( int argc, wchar_t *argv[ ], wchar_t *envp[ ] ) +- Can't be declared as **`inline`**. +- Can't be declared as **`static`**. +- Can't have its address taken. +- Can't be called from your program. + +## The `wmain` function signature + +The `wmain` function doesn't have a declaration, because it's built into the language. If it did, the declaration syntax for `wmain` would look like this: + +```C +int wmain( void ); +int wmain( int argc, wchar_t *argv[ ] ); +int wmain( int argc, wchar_t *argv[ ], wchar_t *envp[ ] ); ``` -## Remarks +The `wmain` function is declared implicitly by using one of these signatures. You may use any of these signatures when you define your `wmain` function. You can then pass wide-character arguments and, optionally, a wide-character environment pointer to the program. The Microsoft compiler also allows `wmain` to have a return type of **`void`** when no value is returned. The *`argv`* and *`envp`* parameters to `wmain` can also be defined as type `wchar_t**`. For more information about the arguments, see [Argument description](./argument-description.md). -You declare formal parameters to **wmain** using a similar format to **main**. You can then pass wide-character arguments and, optionally, a wide-character environment pointer to the program. The `argv` and `envp` parameters to **wmain** are of type `wchar_t*`. For example: +## The `envp` environment -If your program uses a **main** function, the multibyte-character environment is created by the run-time library at program startup. A wide-character copy of the environment is created only when needed (for example, by a call to the `_wgetenv` or `_wputenv` functions). On the first call to `_wputenv`, or on the first call to `_wgetenv` if an MBCS environment already exists, a corresponding wide-character string environment is created and is then pointed to by the `_wenviron` global variable, which is a wide-character version of the `_environ` global variable. At this point, two copies of the environment (MBCS and Unicode) exist simultaneously and are maintained by the operating system throughout the life of the program. +If your program uses a `main` function, the multibyte-character environment is created by the run-time library at program startup. A wide-character copy of the environment is created only when needed (for example, by a call to the `_wgetenv` or `_wputenv` functions). On the first call to `_wputenv`, or on the first call to `_wgetenv` if an MBCS environment already exists, a corresponding wide-character string environment is created and is then pointed to by the `_wenviron` global variable, which is a wide-character version of the `_environ` global variable. At this point, two copies of the environment (MBCS and Unicode) exist simultaneously and are maintained by the operating system throughout the life of the program. -Similarly, if your program uses a **wmain** function, a wide-character environment is created at program startup and is pointed to by the `_wenviron` global variable. An MBCS (ASCII) environment is created on the first call to `_putenv` or `getenv`, and is pointed to by the `_environ` global variable. +Similarly, if your program uses a `wmain` function, a wide-character environment is created at program startup and is pointed to by the `_wenviron` global variable. An MBCS (ASCII) environment is created on the first call to `_putenv` or `getenv`, and is pointed to by the `_environ` global variable. -For more information on the MBCS environment, see [Internationalization](../c-runtime-library/internationalization.md) in the *Run-Time Library Reference.* +For more information on the MBCS environment, see [Internationalization](../c-runtime-library/internationalization.md). **END Microsoft Specific** ## See also -[main Function and Program Execution](../c-language/main-function-and-program-execution.md) +[`main` function and program execution](../c-language/main-function-and-program-execution.md) diff --git a/docs/c-language/while-statement-c.md b/docs/c-language/while-statement-c.md index 462f57070c8..5035e2c114b 100644 --- a/docs/c-language/while-statement-c.md +++ b/docs/c-language/while-statement-c.md @@ -6,26 +6,26 @@ f1_keywords: ["while"] helpviewer_keywords: ["while keyword [C]", "while keyword [C], syntax"] ms.assetid: d0c970b8-12a9-4827-afb2-a051111834b7 --- -# while Statement (C) +# `while` Statement (C) The **`while`** statement lets you repeat a statement until a specified expression becomes false. ## Syntax -*iteration-statement*:
-    **while (** *expression* **)** *statement* +*`iteration-statement`*:\ + **`while (`** *`expression`* **`)`** *`statement`* -The *expression* must have arithmetic or pointer type. Execution proceeds as follows: +The *`expression`* must have arithmetic or pointer type. Execution proceeds as follows: -1. The *expression* is evaluated. +1. The *`expression`* is evaluated. -1. If *expression* is initially false, the body of the **`while`** statement is never executed, and control passes from the **`while`** statement to the next statement in the program. +1. If *`expression`* is initially false, the body of the **`while`** statement is never executed, and control passes from the **`while`** statement to the next statement in the program. - If *expression* is true (nonzero), the body of the statement is executed and the process is repeated beginning at step 1. + If *`expression`* is true (nonzero), the body of the statement is executed and the process is repeated beginning at step 1. The **`while`** statement can also terminate when a **`break`**, **`goto`**, or **`return`** within the statement body is executed. Use the **`continue`** statement to terminate an iteration without exiting the **`while`** loop. The **`continue`** statement passes control to the next iteration of the **`while`** statement. -This is an example of the **`while`** statement: +Here's an example of the **`while`** statement: ```C while ( i >= 0 ) @@ -35,8 +35,8 @@ while ( i >= 0 ) } ``` -This example copies characters from `string2` to `string1`. If `i` is greater than or equal to 0, `string2[i]` is assigned to `string1[i]` and `i` is decremented. When `i` reaches or falls below 0, execution of the **`while`** statement terminates. +This example copies characters from `string2` to `string1`. If `i` is greater than or equal to 0, then `string2[i]` is assigned to `string1[i]` and `i` is decremented. When `i` reaches or falls below 0, execution of the **`while`** statement terminates. ## See also -[while Statement (C++)](../cpp/while-statement-cpp.md) +[`while` Statement (C++)](../cpp/while-statement-cpp.md) diff --git a/docs/c-runtime-library/32-bit-windows-time-date-formats.md b/docs/c-runtime-library/32-bit-windows-time-date-formats.md index bb77e184b1e..dfe8f3f72eb 100644 --- a/docs/c-runtime-library/32-bit-windows-time-date-formats.md +++ b/docs/c-runtime-library/32-bit-windows-time-date-formats.md @@ -6,27 +6,27 @@ f1_keywords: ["vc.time"] helpviewer_keywords: ["32-bit Windows"] ms.assetid: ef1589db-84d7-4b24-8799-7c7a22cfe2bf --- -# 32-Bit Windows Time/Date Formats +# 32-Bit Windows time/date formats The file time and the date are stored individually, using unsigned integers as bit fields. File time and date are packed as follows: ### Time -|Bit position:|0 1 2 3 4|5 6 7 8 9 A|B C D E F| -|-------------------|-----------------------|---------------------------|-----------------------| -|Length:|5|6|5| -|Contents:|hours|minutes|2-second increments| -|Value Range:|0-23|0-59|0-29 in 2-second intervals| +| Bit position: | 0 1 2 3 4 | 5 6 7 8 9 A | B C D E F | +|---|---|---|---| +| Length: | 5 | 6 | 5 | +| Contents: | hours | minutes | 2-second increments | +| Value Range: | 0-23 | 0-59 | 0-29 in 2-second intervals | ### Date -|Bit position:|0 1 2 3 4 5 6|7 8 9 A|B C D E F| -|-------------------|-------------------------------|-------------------|-----------------------| -|Length:|7|4|5| -|Contents:|year|month|day| -|Value Range:|0-119|1-12|1-31| -||(relative to 1980)||| +| Bit position: | 0 1 2 3 4 5 6 | 7 8 9 A | B C D E F | +|---|---|---|---| +| Length: | 7 | 4 | 5 | +| Contents: | year | month | day | +| Value Range: | 0-119 | 1-12 | 1-31 | +| | (relative to 1980) | | | ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/a-sample-generic-text-program.md b/docs/c-runtime-library/a-sample-generic-text-program.md index 0cf11e3a3d1..95628a223a2 100644 --- a/docs/c-runtime-library/a-sample-generic-text-program.md +++ b/docs/c-runtime-library/a-sample-generic-text-program.md @@ -5,7 +5,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["_TCHAR type", "mappings, TCHAR.H data types", "generic-text example [CRT]", "TCHAR type", "TCHAR.H data types, mapping"] ms.assetid: a03de0db-8118-4bd9-a03f-640e8dfc5ed3 --- -# A Sample Generic-Text Program +# A sample generic-text program **Microsoft Specific** @@ -87,7 +87,7 @@ int __cdecl main(int argc, char **argv, char **envp) } ``` -If `_UNICODE` has been defined, GENTEXT.C maps to the following Unicode version of the program. For more information about using `wmain` in Unicode programs as a replacement for `main`, see [Using wmain](../c-language/using-wmain.md) in *C Language Reference*. +If `_UNICODE` has been defined, GENTEXT.C maps to the following Unicode version of the program. For more information about using `wmain` in Unicode programs as a replacement for `main`, see [Using `wmain`](../c-language/using-wmain.md) in *C Language Reference*. ```C // crt_unicgtxt.c @@ -125,7 +125,7 @@ int __cdecl wmain(int argc, wchar_t **argv, wchar_t **envp) } ``` -If neither `_MBCS` nor `_UNICODE` has been defined, GENTEXT.C maps to single-byte ASCII code, as follows: +If `_MBCS` or `_UNICODE` hasn't been defined, GENTEXT.C maps to single-byte ASCII code, as follows: ```C // crt_sbcsgtxt.c @@ -166,8 +166,8 @@ int __cdecl main(int argc, char **argv, char **envp) ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[Constant and Global Variable Mappings](../c-runtime-library/constant-and-global-variable-mappings.md)
-[Routine Mappings](../c-runtime-library/routine-mappings.md)
-[Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Data type mappings](./data-type-mappings.md)\ +[Constant and global variable mappings](./constant-and-global-variable-mappings.md)\ +[Routine mappings](./routine-mappings.md)\ +[Using generic-text mappings](./using-generic-text-mappings.md) diff --git a/docs/c-runtime-library/abnormal-termination.md b/docs/c-runtime-library/abnormal-termination.md index 7bbfc9cb6ad..f513fc45d1d 100644 --- a/docs/c-runtime-library/abnormal-termination.md +++ b/docs/c-runtime-library/abnormal-termination.md @@ -6,11 +6,11 @@ api_name: ["_abnormal_termination"] api_location: ["msvcr110.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr120.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_abnormal_termination"] +f1_keywords: ["_abnormal_termination", "EXCPT/_abnormal_termination"] helpviewer_keywords: ["_abnormal_termination"] ms.assetid: 952970a4-9586-4c3d-807a-db729448c91c --- -# _abnormal_termination +# `_abnormal_termination` Indicates whether the **`__finally`** block of a [try-finally statement](../cpp/try-finally-statement.md) is entered while the system is executing an internal list of termination handlers. @@ -21,19 +21,19 @@ int _abnormal_termination( ); ``` -## Return Value +## Return value -**`true`** if the system is *unwinding* the stack; otherwise, **`false`**. +**`true`** if the system is unwinding the stack; otherwise, **`false`**. ## Remarks -This is an internal function used to manage unwinding exceptions, and is not intended to be called from user code. +**`_abnormal_termination`** is an internal function used to manage unwinding exceptions, and isn't intended to be called from user code. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|_abnormal_termination|excpt.h| +| Routine | Required header | +|---|---| +| **`_abnormal_termination`** | `` | ## See also diff --git a/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md b/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md index b4c49e9ae36..45d1630a097 100644 --- a/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md +++ b/docs/c-runtime-library/acmdln-tcmdln-wcmdln.md @@ -1,22 +1,21 @@ --- -description: "Learn more about: _acmdln, _tcmdln, _wcmdln" title: "_acmdln, _tcmdln, _wcmdln" -ms.date: "11/04/2016" +description: "Learn more about: _acmdln, _tcmdln, _wcmdln" +ms.date: 11/04/2016 api_name: ["_wcmdln", "_acmdln"] api_location: ["msvcrt.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_acmdln", "acmdln", "_wcmdln", "wcmdln", "_tcmdln", "tcmdln"] +f1_keywords: ["_acmdln", "_wcmdln", "_tcmdln"] helpviewer_keywords: ["_wcmdln global variable", "wcmdln global variable", "_acmdln global variable", "_tcmdln global variable", "tcmdln global variable", "acmdln global variable"] -ms.assetid: 4fc0a6a0-3f93-420a-a19f-5276061ba539 --- -# _acmdln, _tcmdln, _wcmdln +# `_acmdln`, `_tcmdln`, `_wcmdln` Internal CRT global variable. The command line. ## Syntax -``` +```C char * _acmdln; wchar_t * _wcmdln; @@ -24,12 +23,13 @@ wchar_t * _wcmdln; #define _tcmdln _wcmdln #else #define _tcmdln _acmdln +#endif ``` ## Remarks -These CRT internal variables store the complete command line. They are exposed in the exported symbols for the CRT, but are not intended for use in your code. `_acmdln` stores the data as a character string. `_wcmdln` stores the data as a wide character string. `_tcmdln` can be defined as either `_acmdln` or `_wcmdln`, depending on which is appropriate. +These CRT internal variables store the complete command line. They're exposed in the exported symbols for the CRT, but aren't intended for use in your code. `_acmdln` stores the data as a character string. `_wcmdln` stores the data as a wide character string. `_tcmdln` can be defined as either `_acmdln` or `_wcmdln`, depending on which is appropriate. ## See also -[Global Variables](../c-runtime-library/global-variables.md) +[Global variables](global-variables.md) diff --git a/docs/c-runtime-library/ansi-c-compliance.md b/docs/c-runtime-library/ansi-c-compliance.md index 2d748a75e95..67c65fbd7c2 100644 --- a/docs/c-runtime-library/ansi-c-compliance.md +++ b/docs/c-runtime-library/ansi-c-compliance.md @@ -2,8 +2,7 @@ title: "ANSI C Conformance" description: "An overview of Microsoft C runtime naming conventions for ANSI C conformance." ms.date: "11/04/2016" -ms.topic: "conceptual" -f1_keywords: ["Ansi"] +ms.topic: "concept-article" helpviewer_keywords: ["underscores, leading", "compatibility [C++], ANSI C", "conformance with ANSI C", "conventions [C++], Microsoft extensions", "underscores", "naming conventions [C++], Microsoft library", "ANSI [C++], C standard", "Microsoft extensions naming conventions"] ms.assetid: 6be271bf-eecf-491a-a928-0ee2dd60e3b9 --- @@ -13,8 +12,8 @@ The naming convention for all Microsoft-specific identifiers in the run-time sys The names of Microsoft-specific functions and global variables begin with a single underscore. These names can be overridden only locally, within the scope of your code. For example, when you include Microsoft run-time header files, you can still locally override the Microsoft-specific function named `_open` by declaring a local variable of the same name. However, you can't use this name for your own global function or global variable. -The names of Microsoft-specific macros and manifest constants begin with two underscores, or with a single leading underscore immediately followed by an uppercase letter. The scope of these identifiers is absolute. For example, you can't use the Microsoft-specific identifier **_UPPER** for this reason. +The names of Microsoft-specific macros and manifest constants begin with two underscores, or with a single leading underscore immediately followed by an uppercase letter. The scope of such identifiers is absolute. For example, you can't use the Microsoft-specific identifier `_UPPER` for this reason. ## See also -[Compatibility](../c-runtime-library/compatibility.md) +[Compatibility](./compatibility.md) diff --git a/docs/c-runtime-library/argc-argv-wargv.md b/docs/c-runtime-library/argc-argv-wargv.md index 4142ddbab82..776f920bae5 100644 --- a/docs/c-runtime-library/argc-argv-wargv.md +++ b/docs/c-runtime-library/argc-argv-wargv.md @@ -6,14 +6,14 @@ api_name: ["__wargv", "__argv", "__argc"] api_location: ["msvcrt120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__argv", "__argc", "__wargv"] +f1_keywords: ["__argc", "STDLIB/__argc", "__argv", "STDLIB/__argv", "__wargv", "STDLIB/__wargv"] helpviewer_keywords: ["__argv", "__wargv", "__argc"] ms.assetid: 17001b0a-04ad-4762-b3a6-c54847f02d7c no-loc: [__argc, __argv, __wargv, main, wmain] --- -# __argc, __argv, __wargv +# `__argc`, `__argv`, `__wargv` -The `__argc` global variable is a count of the number of command-line arguments passed to the program. `__argv` is a pointer to an array of single-byte-character or multi-byte-character strings that contain the program arguments, and `__wargv` is a pointer to an array of wide-character strings that contain the program arguments. These global variables provide the arguments to `main` or `wmain`. +The **`__argc`** global variable is a count of the number of command-line arguments passed to the program. **`__argv`** is a pointer to an array of single-byte-character or multi-byte-character strings that contain the program arguments, and **`__wargv`** is a pointer to an array of wide-character strings that contain the program arguments. These global variables provide the arguments to `main` or `wmain`. ## Syntax @@ -25,26 +25,26 @@ extern wchar_t ** __wargv; ## Remarks -In a program that uses the `main` function, `__argc` and `__argv` are initialized at program startup by using the command line that's used to start the program. The command line is parsed into individual arguments, and wildcards are expanded. The count of arguments is assigned to `__argc` and the argument strings are allocated on the heap, and a pointer to the array of arguments is assigned to `__argv`. In a program compiled to use wide characters and a `wmain` function, the arguments are parsed and wildcards are expanded as wide-character strings, and a pointer to the array of argument strings is assigned to `__wargv`. +In a program that uses the `main` function, **`__argc`** and **`__argv`** are initialized at program startup by using the command line that's used to start the program. The command line is parsed into individual arguments, and wildcards are expanded. The count of arguments is assigned to **`__argc`** and the argument strings are allocated on the heap, and a pointer to the array of arguments is assigned to **`__argv`**. In a program compiled to use wide characters and a `wmain` function, the arguments are parsed and wildcards are expanded as wide-character strings, and a pointer to the array of argument strings is assigned to **`__wargv`**. For portable code, we recommend you use the arguments passed to `main` to get the command-line arguments in your program. ### Generic-text routine mappings -|Tchar.h routine|_UNICODE not defined|_UNICODE defined| -|---------------------|---------------------------|-----------------------| -|`__targv`|`__argv`|`__wargv`| +| Tchar.h routine | `_UNICODE` not defined | `_UNICODE` defined | +|---|---|---| +| `__targv` | **`__argv`** | **`__wargv`** | ## Requirements -|Global variable|Required header| -|---------------------|---------------------| -|`__argc`, `__argv`, `__wargv`|\, \ (C++)| +| Global variable | Required header | +|---|---| +| **`__argc`**, **`__argv`**, **`__wargv`** | \, \ (C++) | -`__argc`, `__argv`, and `__wargv` are Microsoft extensions. For compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +**`__argc`**, **`__argv`**, and **`__wargv`** are Microsoft extensions. For compatibility information, see [Compatibility](./compatibility.md). ## See also -[Global variables](../c-runtime-library/global-variables.md)\ -[main function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ -[Using wmain Instead of main](../cpp/main-function-command-line-args.md) +[Global variables](./global-variables.md)\ +[`main` function and command-line arguments (C++)](../cpp/main-function-command-line-args.md)\ +[Using `wmain` instead of `main`](../cpp/main-function-command-line-args.md) diff --git a/docs/c-runtime-library/argument-access.md b/docs/c-runtime-library/argument-access.md index 0f31799ba6f..a596c13d288 100644 --- a/docs/c-runtime-library/argument-access.md +++ b/docs/c-runtime-library/argument-access.md @@ -8,16 +8,16 @@ ms.assetid: 7046ae34-a0ec-44f0-815d-3209492a3e19 --- # Argument access -The **va_arg**, **va_end**, and **va_start** macros provide access to function arguments when the number of arguments is variable. These macros are defined in \ for ANSI/ISO C compatibility and in \ for compatibility with UNIX System V. +The `va_arg`, `va_end`, and `va_start` macros provide access to function arguments when the number of arguments is variable. These macros are defined in \ for ANSI/ISO C compatibility and in \ for compatibility with UNIX System V. ## Argument-access macros -|Macro|Use| -|-----------|-------------------------------| -|[va_arg](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md)|Retrieve argument from list| -|[va_end](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md)|Reset pointer| -|[va_start](../c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md)|Set pointer to beginning of argument list| +| Macro | Use | +|---|---| +| [`va_arg`](./reference/va-arg-va-copy-va-end-va-start.md) | Retrieve argument from list | +| [`va_end`](./reference/va-arg-va-copy-va-end-va-start.md) | Reset pointer | +| [`va_start`](./reference/va-arg-va-copy-va-end-va-start.md) | Set pointer to beginning of argument list | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/backward-compatibility.md b/docs/c-runtime-library/backward-compatibility.md index 91183173c4f..c96ccb67787 100644 --- a/docs/c-runtime-library/backward-compatibility.md +++ b/docs/c-runtime-library/backward-compatibility.md @@ -2,20 +2,20 @@ title: "Backward Compatibility" description: "How to use the Microsoft OLDNAMES.LIB library to map function names for backwards compatibility." ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["CRT, compatibility", "backward compatibility, C run-time libraries", "compatibility, C run-time libraries", "backward compatibility"] ms.assetid: cc3175cf-97fd-492f-b329-5791aea63090 --- -# Backward Compatibility +# Backward compatibility For compatibility between product versions, the library OLDNAMES.LIB maps old names to new names. For instance, `open` maps to `_open`. You must explicitly link with OLDNAMES.LIB only when you compile with the following combinations of command-line options: -- `/Zl` (omit default library name from object file) and `/Ze` (the default — use Microsoft extensions) +- `/Zl` (omit default library name from object file) and `/Ze` (the default: use Microsoft extensions) - `/link` (linker-control), `/NOD` (no default-library search), and `/Ze` -For more information about compiler command-line options, see [Compiler Reference](../build/reference/compiler-options.md). +For more information about compiler command-line options, see [Compiler options](../build/reference/compiler-options.md). ## See also -[Compatibility](../c-runtime-library/compatibility.md) +[Compatibility](./compatibility.md) diff --git a/docs/c-runtime-library/buffer-manipulation.md b/docs/c-runtime-library/buffer-manipulation.md index fb2d1941a0d..7fce41ba6c2 100644 --- a/docs/c-runtime-library/buffer-manipulation.md +++ b/docs/c-runtime-library/buffer-manipulation.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Buffer manipulation" title: "Buffer manipulation" -ms.date: "04/04/2018" +description: "Learn more about: Buffer manipulation" +ms.date: 04/04/2018 helpviewer_keywords: ["buffers, manipulation routines", "buffers"] -ms.assetid: 164f4860-ce66-412c-8291-396fbd70f03e --- # Buffer manipulation @@ -11,19 +10,19 @@ Use these routines to work with areas of memory on a byte-by-byte basis. ## Buffer-manipulation routines -|Routine|Use| -|-------------|---------| -|[_memccpy](../c-runtime-library/reference/memccpy.md)|Copy characters from one buffer to another until given character or given number of characters has been copied| -|[memchr, wmemchr](../c-runtime-library/reference/memchr-wmemchr.md)|Return pointer to first occurrence, within specified number of characters, of given character in buffer| -|[memcmp, wmemcmp](../c-runtime-library/reference/memcmp-wmemcmp.md)|Compare specified number of characters from two buffers| -|[memcpy, wmemcpy](../c-runtime-library/reference/memcpy-wmemcpy.md), [memcpy_s, wmemcpy_s](../c-runtime-library/reference/memcpy-s-wmemcpy-s.md)|Copy specified number of characters from one buffer to another| -|[_memicmp, _memicmp_l](../c-runtime-library/reference/memicmp-memicmp-l.md)|Compare specified number of characters from two buffers without regard to case| -|[memmove, wmemmove](../c-runtime-library/reference/memmove-wmemmove.md),[memmove_s, wmemmove_s](../c-runtime-library/reference/memmove-s-wmemmove-s.md)|Copy specified number of characters from one buffer to another| -|[memset, wmemset](../c-runtime-library/reference/memset-wmemset.md)|Use given character to initialize specified number of bytes in the buffer| -|[_swab](../c-runtime-library/reference/swab.md)|Swap bytes of data and store them at specified location| +| Routine | Use | +|---|---| +| [`_memccpy`](reference/memccpy.md) | Copy characters from one buffer to another until given character or given number of characters has been copied | +| [`memchr`, `wmemchr`](reference/memchr-wmemchr.md) | Return pointer to first occurrence, within specified number of characters, of given character in buffer | +| [`memcmp`, `wmemcmp`](reference/memcmp-wmemcmp.md) | Compare specified number of characters from two buffers | +| [`memcpy`, `wmemcpy`](reference/memcpy-wmemcpy.md), [`memcpy_s`, `wmemcpy_s`](reference/memcpy-s-wmemcpy-s.md) | Copy specified number of characters from one buffer to another | +| [`_memicmp`, `_memicmp_l`](reference/memicmp-memicmp-l.md) | Compare specified number of characters from two buffers without regard to case | +| [`memmove`, `wmemmove`](reference/memmove-wmemmove.md), [`memmove_s`, `wmemmove_s`](reference/memmove-s-wmemmove-s.md) | Copy specified number of characters from one buffer to another | +| [`memset`, `wmemset`](reference/memset-wmemset.md) | Use given character to initialize specified number of bytes in the buffer | +| [`_swab`](reference/swab.md) | Swap bytes of data and store them at specified location | -When the source and target areas overlap, only **memmove** is guaranteed to copy the full source properly. +When the source and target areas overlap, only `memmove` is guaranteed to copy the full source properly. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/bufsiz.md b/docs/c-runtime-library/bufsiz.md index d42cf2cf325..35fcf77acfe 100644 --- a/docs/c-runtime-library/bufsiz.md +++ b/docs/c-runtime-library/bufsiz.md @@ -2,23 +2,23 @@ description: "Learn more about: BUFSIZ" title: "BUFSIZ" ms.date: "11/04/2016" -f1_keywords: ["BUFSIZ"] +f1_keywords: ["BUFSIZ", "STDIO/BUFSIZ"] helpviewer_keywords: ["BUFSIZ constant"] ms.assetid: 94ac04a3-d154-476b-bd89-eefbc7b949ae --- -# BUFSIZ +# `BUFSIZ` ## Syntax -``` +```C #include ``` ## Remarks -`BUFSIZ` is the required user-allocated buffer for the [setvbuf](../c-runtime-library/reference/setvbuf.md) routine. +`BUFSIZ` is the required user-allocated buffer for the [`setvbuf`](./reference/setvbuf.md) routine. ## See also -[Stream I/O](../c-runtime-library/stream-i-o.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Stream I/O](./stream-i-o.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/byte-and-wide-streams.md b/docs/c-runtime-library/byte-and-wide-streams.md index 840a11276cc..bc5ab7e6fbe 100644 --- a/docs/c-runtime-library/byte-and-wide-streams.md +++ b/docs/c-runtime-library/byte-and-wide-streams.md @@ -2,20 +2,18 @@ title: "Byte and Wide Streams" description: "An overview of byte streams in the Microsoft C runtime library." ms.date: "11/04/2016" -ms.topic: "conceptual" -f1_keywords: ["Byte and Wide Streams"] +ms.topic: "concept-article" helpviewer_keywords: ["byte streams", "wide streams"] -ms.assetid: 61ef0587-4cbc-4eb8-aae5-4c298dbbc6f9 --- -# Byte and Wide Streams +# Byte and wide streams A byte stream treats a file as a sequence of bytes. Within the program, the stream is the identical sequence of bytes. -By contrast, a wide stream treats a file as a sequence of generalized multibyte characters, which can have a broad range of encoding rules. (Text and binary files are still read and written as previously described.) Within the program, the stream looks like the corresponding sequence of wide characters. Conversions between the two representations occur within the Standard C Library. The conversion rules can, in principle, be altered by a call to [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) that alters the category `LC_CTYPE`. Each wide stream determines its conversion rules at the time it becomes wide oriented, and retains these rules even if the category `LC_CTYPE` subsequently changes. +By contrast, a wide stream treats a file as a sequence of generalized multibyte characters, which can have a broad range of encoding rules. (Text and binary files are still read and written as previously described.) Within the program, the stream looks like the corresponding sequence of wide characters. Conversions between the two representations occur within the Standard C Library. The conversion rules can, in principle, be altered by a call to [`setlocale`](./reference/setlocale-wsetlocale.md) that alters the category `LC_CTYPE`. Each wide stream determines its conversion rules at the time it becomes wide oriented, and retains these rules even if the category `LC_CTYPE` later changes. -Positioning within a wide stream suffers the same limitations as for text steams. Moreover, the file-position indicator may well have to deal with a state-dependent encoding. Typically, it includes both a byte offset within the stream and an object of type `mbstate_t`. Thus, the only reliable way to obtain a file position within a wide stream is by calling [fgetpos](../c-runtime-library/reference/fgetpos.md), and the only reliable way to restore a position obtained this way is by calling [fsetpos](../c-runtime-library/reference/fsetpos.md). +Positioning within a wide stream suffers the same limitations as for text streams. Moreover, the file-position indicator may well have to deal with a state-dependent encoding. Typically, it includes both a byte offset within the stream and an object of type `mbstate_t`. Thus, the only reliable way to obtain a file position within a wide stream is by calling [`fgetpos`](./reference/fgetpos.md), and the only reliable way to restore a position obtained this way is by calling [`fsetpos`](./reference/fsetpos.md). ## See also -[Files and Streams](../c-runtime-library/files-and-streams.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) +[Files and streams](./files-and-streams.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/byte-classification.md b/docs/c-runtime-library/byte-classification.md index d42e37c2df3..46fd6bbbac1 100644 --- a/docs/c-runtime-library/byte-classification.md +++ b/docs/c-runtime-library/byte-classification.md @@ -8,7 +8,7 @@ ms.assetid: 1cb52d71-fb0c-46ca-aad7-6472c1103370 --- # Byte classification -Each of these routines tests a specified byte of a multibyte character for satisfaction of a condition. Except where specified otherwise, the output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. +Each of these routines tests a specified byte of a multibyte character for satisfaction of a condition. Except where specified otherwise, the output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. > [!NOTE] > By definition, the ASCII characters between 0 and 127 are a subset of all multibyte-character sets. For example, the Japanese katakana character set includes ASCII as well as non-ASCII characters. @@ -19,26 +19,26 @@ The predefined constants in the following table are defined in ``. | Routine | Byte Test Condition | |--|--| -| [`isleadbyte`, `_isleadbyte_l`](../c-runtime-library/reference/isleadbyte-isleadbyte-l.md) | Lead byte; test result depends on `LC_CTYPE` category setting of current locale | -| [`_ismbbalnum`, `_ismbbalnum_l`](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md) | `isalnum || _ismbbkalnum` | -| [`_ismbbalpha`, `_ismbbalpha_l`](../c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md) | `isalpha || _ismbbkalpha` | -| [`_ismbbgraph`, `_ismbbgraph_l`](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md) | Same as `_ismbbprint`, but `_ismbbgraph` does not include the space character (0x20) | -| [`_ismbbkalnum`, `_ismbbkalnum_l`](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md) | Non-ASCII text symbol other than punctuation. For example, in code page 932 only, `_ismbbkalnum` tests for katakana alphanumeric | -| [`_ismbbkana`, `_ismbbkana_l`](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md) | Katakana (0xA1 - 0xDF), code page 932 only | -| [`_ismbbkprint`, `_ismbbkprint_l`](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md) | Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, `_ismbbkprint` tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF). | -| [`_ismbbkpunct`, `_ismbbkpunct_l`](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md) | Non-ASCII punctuation. For example, in code page 932 only, `_ismbbkpunct` tests for katakana punctuation. | -| [`_ismbblead`, `_ismbblead_l`](../c-runtime-library/reference/ismbblead-ismbblead-l.md) | First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC. | -| [`_ismbbprint`, `_ismbbprint_l`](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md) | `isprint || _ismbbkprint`. `ismbbprint` includes the space character (0x20) | -| [`_ismbbpunct`, `_ismbbpunct_l`](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md) | `ispunct || _ismbbkpunct` | -| [`_ismbbtrail`, `_ismbbtrail_l`](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md) | Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC. | -| [`_ismbslead`, `_ismbslead_l`](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md) | Lead byte (in string context) | -| [`ismbstrail`, `_ismbstrail_l`](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md) | Trail byte (in string context) | -| [`_mbbtype`, `_mbbtype_l`](../c-runtime-library/reference/mbbtype-mbbtype-l.md) | Return byte type based on previous byte | -| [`_mbsbtype`, `_mbsbtype_l`](../c-runtime-library/reference/mbsbtype-mbsbtype-l.md) | Return type of byte within string | -| [`mbsinit`](../c-runtime-library/reference/mbsinit.md) | Tracks the state of a multibyte character conversion. | +| [`isleadbyte`, `_isleadbyte_l`](./reference/isleadbyte-isleadbyte-l.md) | Lead byte; test result depends on `LC_CTYPE` category setting of current locale | +| [`_ismbbalnum`, `_ismbbalnum_l`](./reference/ismbbalnum-ismbbalnum-l.md) | `isalnum || _ismbbkalnum` | +| [`_ismbbalpha`, `_ismbbalpha_l`](./reference/ismbbalpha-ismbbalpha-l.md) | `isalpha || _ismbbkalpha` | +| [`_ismbbgraph`, `_ismbbgraph_l`](./reference/ismbbgraph-ismbbgraph-l.md) | Same as `_ismbbprint`, but `_ismbbgraph` doesn't include the space character (0x20) | +| [`_ismbbkalnum`, `_ismbbkalnum_l`](./reference/ismbbkalnum-ismbbkalnum-l.md) | Non-ASCII text symbol other than punctuation. For example, in code page 932 only, `_ismbbkalnum` tests for katakana alphanumeric | +| [`_ismbbkana`, `_ismbbkana_l`](./reference/ismbbkana-ismbbkana-l.md) | Katakana (0xA1 - 0xDF), code page 932 only | +| [`_ismbbkprint`, `_ismbbkprint_l`](./reference/ismbbkprint-ismbbkprint-l.md) | Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, `_ismbbkprint` tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF). | +| [`_ismbbkpunct`, `_ismbbkpunct_l`](./reference/ismbbkpunct-ismbbkpunct-l.md) | Non-ASCII punctuation. For example, in code page 932 only, `_ismbbkpunct` tests for katakana punctuation. | +| [`_ismbblead`, `_ismbblead_l`](./reference/ismbblead-ismbblead-l.md) | First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC. | +| [`_ismbbprint`, `_ismbbprint_l`](./reference/ismbbprint-ismbbprint-l.md) | `isprint || _ismbbkprint`. `ismbbprint` includes the space character (0x20) | +| [`_ismbbpunct`, `_ismbbpunct_l`](./reference/ismbbpunct-ismbbpunct-l.md) | `ispunct || _ismbbkpunct` | +| [`_ismbbtrail`, `_ismbbtrail_l`](./reference/ismbbtrail-ismbbtrail-l.md) | Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC. | +| [`_ismbslead`, `_ismbslead_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md) | Lead byte (in string context) | +| [`ismbstrail`, `_ismbstrail_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md) | Trail byte (in string context) | +| [`_mbbtype`, `_mbbtype_l`](./reference/mbbtype-mbbtype-l.md) | Return byte type based on previous byte | +| [`_mbsbtype`, `_mbsbtype_l`](./reference/mbsbtype-mbsbtype-l.md) | Return type of byte within string | +| [`mbsinit`](./reference/mbsinit.md) | Tracks the state of a multibyte character conversion. | The `MB_LEN_MAX` macro, defined in ``, expands to the maximum length in bytes that any multibyte character can have. `MB_CUR_MAX`, defined in ``, expands to the maximum length in bytes of any multibyte character in the current locale. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/c-run-time-library-reference.md b/docs/c-runtime-library/c-run-time-library-reference.md index 269e399f150..192b1df77e6 100644 --- a/docs/c-runtime-library/c-run-time-library-reference.md +++ b/docs/c-runtime-library/c-run-time-library-reference.md @@ -7,11 +7,11 @@ helpviewer_keywords: ["CRT", "runtime libraries", "CRT, reference"] --- # Microsoft C runtime library (CRT) reference -The Microsoft runtime library provides routines for programming the Microsoft Windows operating system. These routines automate many common programming tasks that are not provided by the C and C++ languages. +The Microsoft runtime library provides routines for programming the Microsoft Windows operating system. These routines automate many common programming tasks that aren't provided by the C and C++ languages. -Sample programs are included in the individual reference topics for most routines in the library. +Sample programs are included in the individual reference articles for most routines in the library. -## In This Section +## In this section [Universal C runtime routines by category](run-time-routines-by-category.md)\ Provides links to the runtime library by category. @@ -40,7 +40,7 @@ Describes how to use the `setlocale` function to set the language and Country/Re [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](crt-library-features.md)\ List of `.lib` files that make up the C runtime libraries and their associated compiler options and preprocessor directives. -## Related Sections +## Related sections [Debug routines](debug-routines.md)\ Provides links to the debug versions of the runtime library routines. diff --git a/docs/c-runtime-library/cgets-cgetws.md b/docs/c-runtime-library/cgets-cgetws.md index d50430497c3..04390142f6d 100644 --- a/docs/c-runtime-library/cgets-cgetws.md +++ b/docs/c-runtime-library/cgets-cgetws.md @@ -1,28 +1,27 @@ --- -description: "Learn more about: _cgets, _cgetws" title: "_cgets, _cgetws" -ms.date: "4/2/2020" +description: "Learn more about: _cgets, _cgetws" +ms.date: 4/2/2020 api_name: ["_cgetws", "_cgets", "_o__cgets", "_o__cgetws"] -api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["cgetws", "_cgetws", "_cgets"] helpviewer_keywords: ["_cgetws function", "strings [C++], getting from console", "console, getting strings from", "_cgets function", "cgetws function", "cgets function"] -ms.assetid: 4d5e134a-58c3-4f62-befd-5d235b0212f4 --- -# _cgets, _cgetws +# `_cgets`, `_cgetws` -Gets a character string from the console. More secure versions of these functions are available; see [_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md). +Gets a character string from the console. More secure versions of these functions are available; see [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md). > [!IMPORTANT] -> These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT. The secure versions of these functions, _cgets_s and _cgetws_s, are still available. For information on these alternative functions, see [_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md). +> These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT. The secure versions of these functions, _cgets_s and _cgetws_s, are still available. For information on these alternative functions, see [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax -``` +```C char *_cgets( char *buffer ); @@ -41,37 +40,37 @@ wchar_t *_cgetws( #### Parameters -*buffer*
+*`buffer`*\ Storage location for data. -## Return Value +## Return value -`_cgets` and `_cgetws` return a pointer to the start of the string, at `buffer[2]`. If `buffer` is **NULL**, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../c-runtime-library/parameter-validation.md). If execution is allowed to continue, they return **NULL** and set `errno` to `EINVAL`. +**`_cgets`** and **`_cgetws`** return a pointer to the start of the string, at `buffer[2]`. If *`buffer`* is `NULL`, these functions invoke the invalid parameter handler, as described in [Parameter validation](./parameter-validation.md). If execution is allowed to continue, they return `NULL` and set `errno` to `EINVAL`. ## Remarks -These functions read a string of characters from the console and store the string and its length in the location pointed to by `buffer`. The `buffer` parameter must be a pointer to a character array. The first element of the array, `buffer[0]`, must contain the maximum length (in characters) of the string to be read. The array must contain enough elements to hold the string, a terminating null character ('\0'), and 2 additional bytes. The function reads characters until a carriage return-line feed (CR-LF) combination or the specified number of characters is read. The string is stored starting at `buffer[2]`. If the function reads a CR-LF, it stores the null character ('\0'). The function then stores the actual length of the string in the second array element, `buffer[1]`. +These functions read a string of characters from the console and store the string and its length in the location pointed to by *`buffer`*. The *`buffer`* parameter must be a pointer to a character array. The first element of the array, `buffer[0]`, must contain the maximum length (in characters) of the string to be read. The array must contain enough elements to hold the string, a terminating null character ('\0'), and 2 extra bytes. The function reads characters until a carriage return-line feed (CR-LF) combination or the specified number of characters is read. The string is stored starting at `buffer[2]`. If the function reads a CR-LF, it stores the null character ('\0'). The function then stores the actual length of the string in the second array element, `buffer[1]`. -Because all editing keys are active when `_cgets` or `_cgetws` is called while in a console window, pressing the F3 key repeats the last entered entry. +Because all editing keys are active when **`_cgets`** or **`_cgetws`** is called while in a console window, pressing the F3 key repeats the last entered entry. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](./secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_cgetts`|`_cgets`|`_cgets`|`_cgetws`| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_cgetts` | **`_cgets`** | **`_cgets`** | **`_cgetws`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_cgets`|\| -|`_cgetws`|\ or \| +| Routine | Required header | +|---|---| +| **`_cgets`** | \ | +| **`_cgetws`** | \ or \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](./compatibility.md). ## Example @@ -119,5 +118,5 @@ Text = A line of input. ## See also -[Console and Port I/O](../c-runtime-library/console-and-port-i-o.md)
-[_getch, _getwch](../c-runtime-library/reference/getch-getwch.md) +[Console and port I/O](./console-and-port-i-o.md)\ +[`_getch`, `_getwch`](./reference/getch-getwch.md) diff --git a/docs/c-runtime-library/character-classification.md b/docs/c-runtime-library/character-classification.md index db0eff2bc30..3a040c99cc1 100644 --- a/docs/c-runtime-library/character-classification.md +++ b/docs/c-runtime-library/character-classification.md @@ -6,11 +6,11 @@ f1_keywords: ["c.types.character"] helpviewer_keywords: ["character classification routines", "characters, testing"] ms.assetid: 3b6c8f0b-9701-407a-b384-9086698773f5 --- -# Character Classification +# Character classification -Each of these routines tests a specified single-byte character, wide character, or multibyte character for satisfaction of a condition. (By definition, the ASCII character set between 0 and 127 are a subset of all multibyte-character sets. For example, Japanese katakana includes ASCII as well as non-ASCII characters.) +Each of these routines tests a specified single-byte character, wide character, or multibyte character for satisfaction of a condition. (By definition, the ASCII character set between 0 and 127 are a subset of all multibyte-character sets. For example, Japanese katakana includes both ASCII and non-ASCII characters.) -The test conditions are affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. +The test conditions are affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. Generally these routines execute faster than tests you might write and should be favored over. For example, the following code executes slower than a call to `isalpha(c)`: @@ -19,36 +19,36 @@ if ((c >= 'A') && (c <= 'Z')) || ((c >= 'a') && (c <= 'z')) return TRUE; ``` -## Character-Classification Routines - -|Routine|Character test condition| -|-------------|------------------------------| -|[isalnum, iswalnum, _isalnum_l, _iswalnum_l](../c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphanumeric| -|[_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Multibyte alphanumeric| -|[isalpha, iswalpha, _isalpha_l, _iswalpha_l](../c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md), [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphabetic| -|[isascii, __isascii, iswascii](../c-runtime-library/reference/isascii-isascii-iswascii.md)|ASCII| -|[isblank, iswblank, _isblank_l, _iswblank_l](../c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md), [_ismbcsblank, _ismbcsblank_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Blank (space or horizontal tab)| -|[iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l](../c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md)|Control| -|[iscsym, iscsymf, __iscsym, \__iswcsym, \__iscsymf, \__iswcsymf, _iscsym_l, _iswcsym_l, _iscsymf_l, _iswcsymf_l](../c-runtime-library/reference/iscsym-functions.md)|Letter, underscore, or digit| -|[iscsym, iscsymf, __iscsym, \__iswcsym, \__iscsymf, \__iswcsymf, _iscsym_l, _iswcsym_l, _iscsymf_l, _iswcsymf_l](../c-runtime-library/reference/iscsym-functions.md)|Letter or underscore| -|[isdigit, iswdigit, _isdigit_l, _iswdigit_l](../c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Decimal digit| -|[isgraph, iswgraph, _isgraph_l, _iswgraph_l](../c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Printable other than space| -|[islower, iswlower, _islower_l, _iswlower_l](../c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md), [_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Lowercase| -|[_ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Hiragana| -|[_ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Katakana| -|[_ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Legal multibyte character| -|[_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|Japan-level 0 multibyte character| -|[_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|Japan-level 1 multibyte character| -|[_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|Japan-level 2 multibyte character| -|[_ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Non-alphanumeric multibyte character| -|[isprint, iswprint, _isprint_l, _iswprint_l](../c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Printable| -|[ispunct, iswpunct, _ispunct_l, _iswpunct_l](../c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Punctuation| -|[isspace, iswspace, _isspace_l, _iswspace_l](../c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md), [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|White-space| -|[isupper, iswupper](../c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md), [_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Uppercase| -|[_isctype, iswctype, _isctype_l, _iswctype_l](../c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md)|Property specified by *desc* argument| -|[isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l](../c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md)|Hexadecimal digit| -|[_mbclen, mblen, _mblen_l](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)|Return length of valid multibyte character; result depends on **LC_CTYPE** category setting of current locale| +## Character-classification routines + +| Routine | Character test condition | +|---|---| +| [`isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l`](./reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Alphanumeric | +| [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Multibyte alphanumeric | +| [`isalpha`, `iswalpha`, `_isalpha_l`, `_iswalpha_l`](./reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md), [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Alphabetic | +| [`isascii`, `__isascii`, `iswascii`](./reference/isascii-isascii-iswascii.md) | ASCII | +| [`isblank`, `iswblank`, `_isblank_l`, `_iswblank_l`](./reference/isblank-iswblank-isblank-l-iswblank-l.md), [`_ismbcsblank`, `_ismbcsblank_l`](./reference/ismbcgraph-functions.md) | Blank (space or horizontal tab) | +| [`iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l`](./reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md) | Control | +| [`iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l`](./reference/iscsym-functions.md) | Letter, underscore, or digit | +| [`iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l`](./reference/iscsym-functions.md) | Letter or underscore | +| [`isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l`](./reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](./reference/ismbcalnum-functions.md) | Decimal digit | +| [`isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l`](./reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | Printable other than space | +| [`islower`, `iswlower`, `_islower_l`, `_iswlower_l`](./reference/islower-iswlower-islower-l-iswlower-l.md), [`_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l`](./reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Lowercase | +| [`_ismbchira`, `_ismbchira_l`, `_ismbckata`, `_ismbckata_l`](./reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Hiragana | +| [`_ismbchira`, `_ismbchira_l`, `_ismbckata`, `_ismbckata_l`](./reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Katakana | +| [`_ismbclegal`, `_ismbclegal_l`, `_ismbcsymbol`, `_ismbcsymbol_l`](./reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Legal multibyte character | +| [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](./reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | Japan-level 0 multibyte character | +| [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](./reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | Japan-level 1 multibyte character | +| [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](./reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | Japan-level 2 multibyte character | +| [`_ismbclegal`, `_ismbclegal_l`, `_ismbcsymbol`, `_ismbcsymbol_l`](./reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Non-alphanumeric multibyte character | +| [`isprint`, `iswprint`, `_isprint_l`, `_iswprint_l`](./reference/isprint-iswprint-isprint-l-iswprint-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | Printable | +| [`ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l`](./reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | Punctuation | +| [`isspace`, `iswspace`, `_isspace_l`, `_iswspace_l`](./reference/isspace-iswspace-isspace-l-iswspace-l.md), [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](./reference/ismbcgraph-functions.md) | White-space | +| [`isupper`, `iswupper`](./reference/isupper-isupper-l-iswupper-iswupper-l.md), [`_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l`](./reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Uppercase | +| [`_isctype`, `iswctype`, `_isctype_l`, `_iswctype_l`](./reference/isctype-iswctype-isctype-l-iswctype-l.md) | Property specified by *`desc`* argument | +| [`isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l`](./reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md) | Hexadecimal digit | +| [`_mbclen`, `mblen`, `_mblen_l`](./reference/mbclen-mblen-mblen-l.md) | Return length of valid multibyte character; result depends on `LC_CTYPE` category setting of current locale | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/ciatan.md b/docs/c-runtime-library/ciatan.md index 73494e71d95..35d6549103c 100644 --- a/docs/c-runtime-library/ciatan.md +++ b/docs/c-runtime-library/ciatan.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIatan" title: "_CIatan" ms.date: "4/2/2020" api_name: ["_CIatan", "_o__CIatan"] -api_location: ["msvcr120.dll", "msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIatan", "CIatan"] helpviewer_keywords: ["CIatan intrinsic", "_CIatan intrinsic"] ms.assetid: 3baa0429-fe46-4bab-8b00-868e2186dc8c --- -# _CIatan +# `_CIatan` Calculates the arctangent of the top value on the stack. @@ -26,7 +26,7 @@ This version of the `atan` function has a specialized calling convention that th The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[atan, atanf, atanl, atan2, atan2f, atan2l](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](./reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) diff --git a/docs/c-runtime-library/ciatan2.md b/docs/c-runtime-library/ciatan2.md index 832d7261ac3..d0f9ab04c69 100644 --- a/docs/c-runtime-library/ciatan2.md +++ b/docs/c-runtime-library/ciatan2.md @@ -3,16 +3,16 @@ description: "Learn more about: _CIatan2" title: "_CIatan2" ms.date: "4/2/2020" api_name: ["_CIatan2", "_o__CIatan2"] -api_location: ["msvcr80.dll", "msvcrt.dll", "msvcr120.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr80.dll", "msvcrt.dll", "msvcr120.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIatan2", "_CIatan2"] helpviewer_keywords: ["_CIatan2 intrinsic", "CIatan2 intrinsic"] ms.assetid: 31f8cc78-b79f-4576-b73b-8add18e08680 --- -# _CIatan2 +# `_CIatan2` -Calculates the arctangent of *x* / *y* where *x* and *y* are values on the top of the stack. +Calculates the arctangent of *`x`* / *`y`* where *`x`* and *`y`* are values on the top of the stack. ## Syntax @@ -26,7 +26,7 @@ This version of the `atan2` function has a specialized calling convention that t The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[atan, atanf, atanl, atan2, atan2f, atan2l](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](./reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) diff --git a/docs/c-runtime-library/cicos.md b/docs/c-runtime-library/cicos.md index e9e4751094f..d84df026806 100644 --- a/docs/c-runtime-library/cicos.md +++ b/docs/c-runtime-library/cicos.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIcos" title: "_CIcos" ms.date: "4/2/2020" api_name: ["_CIcos", "_o__CIcos"] -api_location: ["msvcr90.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIcos", "_CIcos"] helpviewer_keywords: ["_CIcos intrinsic", "CIcos intrinsic"] ms.assetid: 6fc203fb-66f3-4ead-9784-f85833c26f1b --- -# _CIcos +# `_CIcos` Calculates the cosine of the top value in the floating-point stack. @@ -22,11 +22,11 @@ void __cdecl _CIcos(); ## Remarks -This version of the [cos](../c-runtime-library/reference/cos-cosf-cosl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. +This version of the [`cos`](./reference/cos-cosf-cosl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. The resulting value is pushed onto the top of the floating-point stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[cos, cosf, cosl](../c-runtime-library/reference/cos-cosf-cosl.md)
+[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`cos`, `cosf`, `cosl`](./reference/cos-cosf-cosl.md) diff --git a/docs/c-runtime-library/ciexp.md b/docs/c-runtime-library/ciexp.md index 9b2004f03a9..0fd7e1227ae 100644 --- a/docs/c-runtime-library/ciexp.md +++ b/docs/c-runtime-library/ciexp.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIexp" title: "_CIexp" ms.date: "4/2/2020" api_name: ["_CIexp", "_o__CIexp"] -api_location: ["msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIexp", "_CIexp"] helpviewer_keywords: ["CIexp intrinsic", "_CIexp intrinsic"] ms.assetid: f8a3e3b7-fa57-41a3-9983-6c81914cbb55 --- -# _CIexp +# `_CIexp` Calculates the exponential of the top value on the stack. @@ -26,7 +26,7 @@ This version of the `exp` function has a specialized calling convention that the The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[exp, expf, expl](../c-runtime-library/reference/exp-expf.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`exp`, `expf`, `expl`](./reference/exp-expf.md) diff --git a/docs/c-runtime-library/cifmod.md b/docs/c-runtime-library/cifmod.md index 3637973196b..660a17bcb98 100644 --- a/docs/c-runtime-library/cifmod.md +++ b/docs/c-runtime-library/cifmod.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIfmod" title: "_CIfmod" ms.date: "4/2/2020" api_name: ["_CIfmod", "_o__CIfmod"] -api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIfmod", "CIfmod"] helpviewer_keywords: ["CIfmod intrinsic", "_CIfmod intrinsic"] ms.assetid: 7c050653-7ec6-4810-b3a7-7a0057ea65ed --- -# _CIfmod +# `_CIfmod` Calculates the floating-point remainder of the top two values on the stack. @@ -26,7 +26,7 @@ This version of the `fmod` function has a specialized calling convention that th The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[fmod, fmodf](../c-runtime-library/reference/fmod-fmodf.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`fmod`, `fmodf`](./reference/fmod-fmodf.md) diff --git a/docs/c-runtime-library/cilog.md b/docs/c-runtime-library/cilog.md index 5071a255ebf..229d1fb8346 100644 --- a/docs/c-runtime-library/cilog.md +++ b/docs/c-runtime-library/cilog.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIlog" title: "_CIlog" ms.date: "4/2/2020" api_name: ["_CIlog", "_o__CIlog"] -api_location: ["msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIlog", "CIlog"] helpviewer_keywords: ["_CIlog intrinsic", "CIlog intrinsic"] ms.assetid: 23503854-ddaa-4fe0-a4a3-7fbb3a43bdec --- -# _CIlog +# `_CIlog` Calculates the natural logarithm of the top value in the stack. @@ -26,7 +26,7 @@ This version of the `log` function has a specialized calling convention that the The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[log, logf, log10, log10f](../c-runtime-library/reference/log-logf-log10-log10f.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`log`, `logf`, `log10`, `log10f`](./reference/log-logf-log10-log10f.md) diff --git a/docs/c-runtime-library/cilog10.md b/docs/c-runtime-library/cilog10.md index be7c4fcf927..1c1447da3b6 100644 --- a/docs/c-runtime-library/cilog10.md +++ b/docs/c-runtime-library/cilog10.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIlog10" title: "_CIlog10" ms.date: "4/2/2020" api_name: ["_CIlog10", "_o__CIlog10"] -api_location: ["msvcr100.dll", "msvcr120.dll", "msvcr80.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr120.dll", "msvcr80.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr110.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIlog10", "_CIlog10"] helpviewer_keywords: ["_CIlog10 intrinsic", "CIlog10 intrinsic"] ms.assetid: 05d7fcaa-3cff-4cc5-8d44-015e7cacba24 --- -# _CIlog10 +# `_CIlog10` Performs a `log10` operation on the top value in the stack. @@ -26,7 +26,7 @@ This version of the `log10` function has a specialized calling convention that t The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[log, logf, log10, log10f](../c-runtime-library/reference/log-logf-log10-log10f.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`log`, `logf`, `log10`, `log10f`](./reference/log-logf-log10-log10f.md) diff --git a/docs/c-runtime-library/cipow.md b/docs/c-runtime-library/cipow.md index e375a887d1b..6fe366afcae 100644 --- a/docs/c-runtime-library/cipow.md +++ b/docs/c-runtime-library/cipow.md @@ -3,16 +3,16 @@ description: "Learn more about: _CIpow" title: "_CIpow" ms.date: "4/2/2020" api_name: ["_CIpow", "_o__CIpow"] -api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr110.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr90.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIpow", "_CIpow"] helpviewer_keywords: ["CIpow intrinsic", "_CIpow intrinsic"] ms.assetid: 477aaf0c-ac58-4252-89dd-9f3e35d47536 --- -# _CIpow +# `_CIpow` -Calculates *x* raised to the *y* power based on the top values in the stack. +Calculates *`x`* raised to the *`y`* power based on the top values in the stack. ## Syntax @@ -26,7 +26,7 @@ This version of the `pow` function has a specialized calling convention that the The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[pow, powf, powl](../c-runtime-library/reference/pow-powf-powl.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`pow`, `powf`, `powl`](./reference/pow-powf-powl.md) diff --git a/docs/c-runtime-library/cisin.md b/docs/c-runtime-library/cisin.md index 10b73f0b9bd..6eb5cf8f266 100644 --- a/docs/c-runtime-library/cisin.md +++ b/docs/c-runtime-library/cisin.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIsin" title: "_CIsin" ms.date: "4/2/2020" api_name: ["_CIsin", "_o__CIsin"] -api_location: ["msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CIsin", "_CIsin"] helpviewer_keywords: ["_CIsin intrinsic", "CIsin intrinsic"] ms.assetid: f215f39a-2341-4f1c-ba8e-cb522451ceb2 --- -# _CIsin +# `_CIsin` Calculates the sine of the top value in the floating-point stack. @@ -22,11 +22,11 @@ void __cdecl _CIsin(); ## Remarks -This intrinsic version of the [sin](../c-runtime-library/reference/sin-sinf-sinl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. +This intrinsic version of the [`sin`](./reference/sin-sinf-sinl.md) function has a specialized calling convention that the compiler understands. It speeds up the execution because it prevents copies from being generated and helps with register allocation. The resulting value is pushed onto the top of the floating-point stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[sin, sinf, sinl](../c-runtime-library/reference/sin-sinf-sinl.md)
+[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`sin`, `sinf`, `sinl`](./reference/sin-sinf-sinl.md) diff --git a/docs/c-runtime-library/cisqrt.md b/docs/c-runtime-library/cisqrt.md index a45c65c4c3b..ab5f5e0a729 100644 --- a/docs/c-runtime-library/cisqrt.md +++ b/docs/c-runtime-library/cisqrt.md @@ -3,14 +3,14 @@ description: "Learn more about: _CIsqrt" title: "_CIsqrt" ms.date: "4/2/2020" api_name: ["_CIsqrt", "_o__CIsqrt"] -api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CIsqrt", "CIsqrt"] helpviewer_keywords: ["CIsqrt intrinsic", "_CIsqrt intrinsic"] ms.assetid: 663548ea-398c-48ee-8397-a787c6ebb937 --- -# _CIsqrt +# `_CIsqrt` Calculates the square root of the top value in the stack. @@ -26,7 +26,7 @@ This version of the `sqrt` function has a specialized calling convention that th The resulting value is pushed onto the top of the stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[sqrt, sqrtf, sqrtl](../c-runtime-library/reference/sqrt-sqrtf-sqrtl.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`sqrt`, `sqrtf`, `sqrtl`](./reference/sqrt-sqrtf-sqrtl.md) diff --git a/docs/c-runtime-library/citan.md b/docs/c-runtime-library/citan.md index efd56c6653e..25708828fe3 100644 --- a/docs/c-runtime-library/citan.md +++ b/docs/c-runtime-library/citan.md @@ -3,14 +3,14 @@ description: "Learn more about: _CItan" title: "_CItan" ms.date: "4/2/2020" api_name: ["_CItan", "_o__CItan"] -api_location: ["msvcr100.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcrt.dll", "msvcr110.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr100.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcrt.dll", "msvcr110.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_CItan", "CItan"] helpviewer_keywords: ["CItan intrinsic", "_CItan intrinsic"] ms.assetid: d1ea3113-50a2-45a6-b6bc-680fcdcc0928 --- -# _CItan +# `_CItan` Calculates the tangent of the top value on the floating-point stack. @@ -22,11 +22,11 @@ void __cdecl _CItan(); ## Remarks -This version of the [tan](../c-runtime-library/reference/tan-tanf-tanl.md) function has a specialized calling convention that the compiler understands. The function speeds up the execution because it prevents copies from being generated and helps with register allocation. +This version of the [`tan`](./reference/tan-tanf-tanl.md) function has a specialized calling convention that the compiler understands. The function speeds up the execution because it prevents copies from being generated and helps with register allocation. The resulting value is pushed onto the top of the floating-point stack. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements @@ -34,5 +34,5 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[tan, tanf, tanl](../c-runtime-library/reference/tan-tanf-tanl.md)
+[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`tan`, `tanf`, `tanl`](./reference/tan-tanf-tanl.md) diff --git a/docs/c-runtime-library/clocks-per-sec-clk-tck.md b/docs/c-runtime-library/clocks-per-sec-clk-tck.md index 4c16e39eb3d..927a19ef920 100644 --- a/docs/c-runtime-library/clocks-per-sec-clk-tck.md +++ b/docs/c-runtime-library/clocks-per-sec-clk-tck.md @@ -2,15 +2,15 @@ description: "Learn more about: CLOCKS_PER_SEC, CLK_TCK" title: "CLOCKS_PER_SEC, CLK_TCK" ms.date: "11/04/2016" -f1_keywords: ["CLOCKS_PER_SEC", "CLK_TCK"] +f1_keywords: ["CLOCKS_PER_SEC", "TIME/CLOCKS_PER_SEC", "CLK_TCK", "TIME/CLK_TCK"] helpviewer_keywords: ["CLOCKS_PER_SEC", "CLK_TCK constant"] ms.assetid: bc285106-383d-44cb-91bf-276ad7de57bf --- -# CLOCKS_PER_SEC, CLK_TCK +# `CLOCKS_PER_SEC`, `CLK_TCK` ## Syntax -``` +```C #include ``` @@ -20,5 +20,5 @@ The time in seconds is the value returned by the `clock` function, divided by `C ## See also -[clock](../c-runtime-library/reference/clock.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`clock`](./reference/clock.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/code-pages.md b/docs/c-runtime-library/code-pages.md index 677ae946126..25a6e84f5df 100644 --- a/docs/c-runtime-library/code-pages.md +++ b/docs/c-runtime-library/code-pages.md @@ -1,12 +1,11 @@ --- title: "Code Pages" description: "A description of code page support in the Microsoft C runtime." -ms.topic: "conceptual" -ms.date: "11/04/2016" +ms.date: 11/04/2016 +ms.topic: "concept-article" helpviewer_keywords: ["character sets [C++], code pages", "ANSI [C++], code pages", "system-default code page", "multibyte code pages [C++]", "localization [C++], code pages", "code pages [C++], types of", "locale code pages [C++]"] -ms.assetid: 4a26fc42-185a-4add-98bf-a7b314ae6186 --- -# Code Pages +# Code pages A *code page* is a character set, which can include numbers, punctuation marks, and other glyphs. Different languages and locales may use different code pages. For example, ANSI code page 1252 is used for English and most European languages; OEM code page 932 is used for Japanese Kanji. @@ -14,7 +13,7 @@ A code page can be represented in a table as a mapping of characters to single-b The Microsoft runtime library uses the following types of code pages: -- System-default ANSI code page. By default, at startup the runtime system automatically sets the multibyte code page to the system-default ANSI code page, which is obtained from the operating system. The call: +- System-default ANSI code page. By default, at startup, the runtime system automatically sets the multibyte code page to the system-default ANSI code page, which is obtained from the operating system. The call: ```C setlocale ( LC_ALL, "" ); @@ -22,13 +21,13 @@ The Microsoft runtime library uses the following types of code pages: also sets the locale to the system-default ANSI code page. -- Locale code page. The behavior of a number of run-time routines is dependent on the current locale setting, which includes the locale code page. (For more information, see [Locale-Dependent Routines](../c-runtime-library/locale.md).) By default, all locale-dependent routines in the Microsoft run-time library use the code page that corresponds to the "C" locale. At run time, you can change or query the locale code page in use with a call to [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md). +- Locale code page. The behavior of several run-time routines is dependent on the current locale setting, which includes the locale code page. For more information, see [Locale](./locale.md). By default, all locale-dependent routines in the Microsoft run-time library use the code page that corresponds to the "C" locale. At run time, you can change or query the locale code page in use with a call to [`setlocale`](./reference/setlocale-wsetlocale.md). -- Multibyte code page. The behavior of most of the multibyte-character routines in the run-time library depends on the current multibyte code page setting. By default, these routines use the system-default ANSI code page. At run-time you can query and change the multibyte code page with [_getmbcp](../c-runtime-library/reference/getmbcp.md) and [_setmbcp](../c-runtime-library/reference/setmbcp.md), respectively. +- Multibyte code page. The behavior of most of the multibyte-character routines in the run-time library depends on the current multibyte code page setting. By default, these routines use the system-default ANSI code page. At run-time you can query and change the multibyte code page with [`_getmbcp`](./reference/getmbcp.md) and [`_setmbcp`](./reference/setmbcp.md), respectively. -- The "C" locale is defined by ANSI to correspond to the locale in which C programs have traditionally executed. The code page for the "C" locale ("C" code page) corresponds to the ASCII character set. For example, in the "C" locale, **islower** returns true for the values 0x61 - 0x7A only. In another locale, **islower** may return `true` for these and other values, as defined by that locale. +- The "C" locale is defined by ANSI to correspond to the locale in which C programs have traditionally executed. The code page for the "C" locale ("C" code page) corresponds to the ASCII character set. For example, in the "C" locale, `islower` returns true for the values 0x61 - 0x7A only. In another locale, `islower` may return `true` for these and other values, as defined by that locale. ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/commit-to-disk-constants.md b/docs/c-runtime-library/commit-to-disk-constants.md index 5ab2a097bcc..9b0fd03de3f 100644 --- a/docs/c-runtime-library/commit-to-disk-constants.md +++ b/docs/c-runtime-library/commit-to-disk-constants.md @@ -6,13 +6,13 @@ f1_keywords: ["vc.constants"] helpviewer_keywords: ["commit-to-disk constants"] ms.assetid: 0b903b23-b4fa-431e-a937-51d95f695ecf --- -# Commit-To-Disk Constants +# Commit-to-disk constants **Microsoft Specific** ## Syntax -``` +```C #include ``` @@ -24,7 +24,7 @@ The commit-to-disk modes are as follows: - **c** - Writes the unwritten contents of the specified buffer to disk. This commit-to-disk functionality only occurs at explicit calls to either the [fflush](../c-runtime-library/reference/fflush.md) or the [_flushall](../c-runtime-library/reference/flushall.md) function. This mode is useful when dealing with sensitive data. For example, if your program terminates after a call to `fflush` or `_flushall`, you can be sure that your data reached the operating system's buffers. However, unless a file is opened with the **c** option, the data might never make it to disk if the operating system also terminates. + Writes the unwritten contents of the specified buffer to disk. This commit-to-disk functionality only occurs at explicit calls to either the [`fflush`](./reference/fflush.md) or the [`_flushall`](./reference/flushall.md) function. This mode is useful when dealing with sensitive data. For example, if your program terminates after a call to `fflush` or `_flushall`, you can be sure that your data reached the operating system's buffers. However, unless a file is opened with the **c** option, the data might never make it to disk if the operating system also terminates. - **n** @@ -33,9 +33,9 @@ The commit-to-disk modes are as follows: > [!NOTE] > The **c** and **n** options are not part of the ANSI standard for `fopen`, but are Microsoft extensions and should not be used where ANSI portability is desired. -## Using the Commit-to-Disk Feature with Existing Code +## Using the commit-to-disk feature with existing code -By default, calls to the [fflush](../c-runtime-library/reference/fflush.md) or [_flushall](../c-runtime-library/reference/flushall.md) library functions write data to buffers maintained by the operating system. The operating system determines the optimal time to actually write the data to disk. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system's buffers. You can give this capability to an existing program without rewriting it by linking its object files with COMMODE.OBJ. +By default, calls to the [`fflush`](./reference/fflush.md) or [`_flushall`](./reference/flushall.md) library functions write data to buffers maintained by the operating system. The operating system determines the optimal time to actually write the data to disk. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system's buffers. You can give this capability to an existing program without rewriting it by linking its object files with COMMODE.OBJ. In the resulting executable file, calls to `fflush` write the contents of the buffer directly to disk, and calls to `_flushall` write the contents of all buffers to disk. These two functions are the only ones affected by COMMODE.OBJ. @@ -43,7 +43,7 @@ In the resulting executable file, calls to `fflush` write the contents of the bu ## See also -[Stream I/O](../c-runtime-library/stream-i-o.md)
-[_fdopen, _wfdopen](../c-runtime-library/reference/fdopen-wfdopen.md)
-[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Stream I/O](./stream-i-o.md)\ +[`_fdopen`, `_wfdopen`](./reference/fdopen-wfdopen.md)\ +[`fopen`, `_wfopen`](./reference/fopen-wfopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/compatibility.md b/docs/c-runtime-library/compatibility.md index 124a06492e2..0b56d4e3d82 100644 --- a/docs/c-runtime-library/compatibility.md +++ b/docs/c-runtime-library/compatibility.md @@ -2,7 +2,7 @@ title: "Compatibility" description: "Describes the compatibility of the Microsoft Universal C runtime library (UCRT) with the Standard C library, POSIX, the Safe CRT, and Store apps." ms.date: 1/19/2022 -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["CRT, compatibility", "compatibility, C runtime libraries", "compatibility"] ms.assetid: 346709cb-edda-4909-9a19-3d253eddb6b7 --- @@ -20,19 +20,19 @@ The UCRT also implements a large subset of the POSIX.1 (ISO/IEC 9945-1:1996, the Functions specific to the Microsoft implementation of Visual C++ are found in the vcruntime library. Many of these functions are for internal use and can't be called by user code. Some are documented for use in debugging and implementation compatibility. -The C++ standard reserves names that begin with an underscore in the global namespace to the implementation. Both the POSIX functions and Microsoft-specific runtime library functions are in the global namespace, but aren't part of the standard C runtime library. That's why the preferred Microsoft implementations of these functions have a leading underscore. For portability, the UCRT also supports the default names, but the Microsoft C++ compiler issues a deprecation warning when code that uses them is compiled. Only the default names are deprecated, not the functions themselves. To suppress the warning, define `_CRT_NONSTDC_NO_WARNINGS` before including any headers in code that uses the original POSIX names. Because the C standard doesn't allow non-standard names in header files, by default [`/std:c11`](../build/reference/std-specify-language-standard-version.md) and [`/std:c17`](../build/reference/std-specify-language-standard-version.md) don't expose the default names for POSIX functions, types, and macros. If these names are necessary, define `_CRT_DECLARE_NONSTDC_NAMES` to expose them. +The C++ standard reserves names that begin with an underscore in the global namespace to the implementation. Both the POSIX functions and Microsoft-specific runtime library functions are in the global namespace, but aren't part of the standard C runtime library. It's why the preferred Microsoft implementations of these functions have a leading underscore. For portability, the UCRT also supports the default names, but the Microsoft C++ compiler issues a deprecation warning when code that uses them is compiled. Only the default names are deprecated, not the functions themselves. To suppress the warning, define `_CRT_NONSTDC_NO_WARNINGS` before including any headers in code that uses the original POSIX names. Because the C standard doesn't allow non-standard names in header files, by default [`/std:c11`](../build/reference/std-specify-language-standard-version.md) and [`/std:c17`](../build/reference/std-specify-language-standard-version.md) don't expose the default names for POSIX functions, types, and macros. If these names are necessary, define `_CRT_DECLARE_NONSTDC_NAMES` to expose them. -Certain functions in the standard C library have a history of unsafe usage, because of misused parameters and unchecked buffers. These functions are often the source of security issues in code. Microsoft created a set of safer versions of these functions that verify parameter usage. They invoke the invalid parameter handler when an issue is detected at runtime. By default, the Microsoft C++ compiler issues a deprecation warning when a function is used that has a safer variant available. When you compile your code as C++, you can define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 to eliminate most warnings. This macro enables template overloads to call the safer variants while maintaining portable source code. To suppress the warning, define `_CRT_SECURE_NO_WARNINGS` before including any headers in code that uses these functions. For more information, see [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). +Certain functions in the standard C library have a history of unsafe usage, because of misused parameters and unchecked buffers. These functions are often the source of security issues in code. Microsoft created a set of safer versions of these functions that verify parameter usage. They invoke the invalid parameter handler when an issue is detected at runtime. By default, the Microsoft C++ compiler issues a deprecation warning when a function is used that has a safer variant available. When you compile your code as C++, you can define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 to eliminate most warnings. This macro enables template overloads to call the safer variants while maintaining portable source code. To suppress the warning, define `_CRT_SECURE_NO_WARNINGS` before including any headers in code that uses these functions. For more information, see [Security features in the CRT](./security-features-in-the-crt.md). Except as noted within the documentation for specific functions, the UCRT is compatible with the Windows API. Certain functions aren't supported in Windows Store or Universal Windows Platform ([UWP](/uwp)) apps. These functions are listed in [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). -## Related Articles +## Related articles -|Title|Description| -|-----------|-----------------| -|[UWP Apps, the Windows Runtime, and the C runtime](../c-runtime-library/windows-store-apps-the-windows-runtime-and-the-c-run-time.md)|Describes when UCRT routines aren't compatible with Universal Windows apps or Microsoft Store apps.| -|[ANSI C Conformance](../c-runtime-library/ansi-c-compliance.md)|Describes standard-conforming names in the UCRT.| -|[UNIX](../c-runtime-library/unix.md)|Provides guidelines for porting programs to UNIX.| -|[Windows Platforms (CRT)](../c-runtime-library/windows-platforms-crt.md)|Lists the operating systems that are the CRT supports.| -|[Backward Compatibility](../c-runtime-library/backward-compatibility.md)|Describes how to map old CRT names to the new ones.| -|[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md)|Provides an overview of the CRT library (.lib) files and the associated compiler options.| +| Title | Description | +|---|---| +| [UWP apps, the Windows Runtime, and the C runtime](./windows-store-apps-the-windows-runtime-and-the-c-run-time.md) | Describes when UCRT routines aren't compatible with Universal Windows apps or Microsoft Store apps. | +| [ANSI C conformance](./ansi-c-compliance.md) | Describes standard-conforming names in the UCRT. | +| [UNIX](./unix.md) | Provides guidelines for porting programs to UNIX. | +| [Windows platforms (CRT)](./windows-platforms-crt.md) | Lists the operating systems that CRT supports. | +| [Backward compatibility](./backward-compatibility.md) | Describes how to map old CRT names to the new ones. | +| [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) | Provides an overview of the CRT library (.lib) files and the associated compiler options. | diff --git a/docs/c-runtime-library/complex-math-support.md b/docs/c-runtime-library/complex-math-support.md index c158dc5752c..218495fa17b 100644 --- a/docs/c-runtime-library/complex-math-support.md +++ b/docs/c-runtime-library/complex-math-support.md @@ -7,23 +7,23 @@ helpviewer_keywords: ["complex numbers, math routines", "math routines", "comple --- # C complex math support -The Microsoft C Runtime library (CRT) provides complex math library functions, including all of those required by ISO C99. The compiler doesn't directly support a **`complex`** or **`_Complex`** keyword, therefore the Microsoft implementation uses structure types to represent complex numbers. +The Microsoft C Runtime library (CRT) provides complex math library functions, including all of the ones required by ISO C99. The compiler doesn't directly support a **`complex`** or **`_Complex`** keyword, therefore the Microsoft implementation uses structure types to represent complex numbers. -These functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 ulp of the correctly rounded result, though there may be cases where there's greater inaccuracy. +These functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 unit of least precision (ULP) of the correctly rounded result, though there may be cases where there's greater inaccuracy. -The complex math routines rely on the floating point math library functions for their implementation. These functions have different implementations for different CPU architectures. For example, the 32-bit x86 CRT may have a different implementation than the 64-bit x64 CRT. In addition, some of the functions may have multiple implementations for a given CPU architecture. The most efficient implementation is selected dynamically at run-time depending on the instruction sets supported by the CPU. For example, in the 32-bit x86 CRT, some functions have both an x87 implementation and an SSE2 implementation. When running on a CPU that supports SSE2, the faster SSE2 implementation is used. When running on a CPU that 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. +The complex math routines rely on the floating point math library functions for their implementation. These functions have different implementations for different CPU architectures. For example, the 32-bit x86 CRT may have a different implementation than the 64-bit x64 CRT. In addition, some of the functions may have multiple implementations for a given CPU architecture. The most efficient implementation is selected dynamically at run-time depending on the instruction sets supported by the CPU. For example, in the 32-bit x86 CRT, some functions have both an x87 implementation and an SSE2 implementation. When running on a CPU that supports SSE2, the faster SSE2 implementation is used. When running on a CPU that doesn't support SSE2, the slower x87 implementation is used. Because different implementations of the math library functions may use different CPU instructions and different algorithms to produce their results, the functions may produce different results across CPUs. In most cases, the results are within +/-1 ULP of the correctly rounded result, but the actual results may vary across CPUs. ## Types used in complex math The Microsoft implementation of the `complex.h` header defines these types as equivalents for the C99 standard native complex types: -|Standard type|Microsoft type| -|-|-| -|**`float complex`** or **`float _Complex`**|**`_Fcomplex`**| -|**`double complex`** or **`double _Complex`**|**`_Dcomplex`**| -|**`long double complex`** or **`long double _Complex`**|**`_Lcomplex`**| +| Standard type | Microsoft type | +|---|---| +| **`float complex`** or **`float _Complex`** | **`_Fcomplex`** | +| **`double complex`** or **`double _Complex`** | **`_Dcomplex`** | +| **`long double complex`** or **`long double _Complex`** | **`_Lcomplex`** | -The `math.h` header defines a separate type, **`struct _complex`**, used for the [`_cabs`](../c-runtime-library/reference/cabs.md) function. The **`struct _complex`** type isn't used by the equivalent complex math functions [`cabs`, `cabsf`, `cabsl`](../c-runtime-library/reference/cabs-cabsf-cabsl.md). +The `math.h` header defines a separate type, **`struct _complex`**, used for the [`_cabs`](./reference/cabs.md) function. The **`struct _complex`** type isn't used by the equivalent complex math functions [`cabs`, `cabsf`, `cabsl`](./reference/cabs-cabsf-cabsl.md). ## Complex constants and macros @@ -31,64 +31,64 @@ The `math.h` header defines a separate type, **`struct _complex`**, used for the ## Trigonometric functions -|Function|Description| -|-|-| -|[`cacos`, `cacosf`, `cacosl`](../c-runtime-library/reference/cacos-cacosf-cacosl.md)|Compute the complex arc cosine of a complex number| -|[`casin`, `casinf`, `casinl`](../c-runtime-library/reference/casin-casinf-casinl.md)|Compute the complex arc sine of a complex number| -|[`catan`, `catanf`, `catanl`](../c-runtime-library/reference/catan-catanf-catanl.md)|Compute the complex arc tangent of a complex number| -|[`ccos`, `ccosf`, `ccosl`](../c-runtime-library/reference/ccos-ccosf-ccosl.md)|Compute the complex cosine of a complex number| -|[`csin`, `csinf`, `csinl`](../c-runtime-library/reference/csin-csinf-csinl.md)|Compute the complex sine of a complex number| -|[`ctan`, `ctanf`, `ctanl`](../c-runtime-library/reference/ctan-ctanf-ctanl.md)|Compute the complex tangent of a complex number| +| Function | Description | +|---|---| +| [`cacos`, `cacosf`, `cacosl`](./reference/cacos-cacosf-cacosl.md) | Compute the complex arc cosine of a complex number | +| [`casin`, `casinf`, `casinl`](./reference/casin-casinf-casinl.md) | Compute the complex arc sine of a complex number | +| [`catan`, `catanf`, `catanl`](./reference/catan-catanf-catanl.md) | Compute the complex arc tangent of a complex number | +| [`ccos`, `ccosf`, `ccosl`](./reference/ccos-ccosf-ccosl.md) | Compute the complex cosine of a complex number | +| [`csin`, `csinf`, `csinl`](./reference/csin-csinf-csinl.md) | Compute the complex sine of a complex number | +| [`ctan`, `ctanf`, `ctanl`](./reference/ctan-ctanf-ctanl.md) | Compute the complex tangent of a complex number | ## Hyperbolic functions -|Function|Description| -|-|-| -|[`cacosh`, `cacoshf`, `cacoshl`](../c-runtime-library/reference/cacosh-cacoshf-cacoshl.md)|Compute the complex arc hyperbolic cosine of a complex number| -|[`casinh`, `casinhf`, `casinhl`](../c-runtime-library/reference/casinh-casinhf-casinhl.md)|Compute the complex arc hyperbolic sine of a complex number| -|[`catanh`, `catanhf`, `catanhl`](../c-runtime-library/reference/catanh-catanhf-catanhl.md)|Compute the complex arc hyperbolic tangent of a complex number| -|[`ccosh`, `ccoshf`, `ccoshl`](../c-runtime-library/reference/ccosh-ccoshf-ccoshl.md)|Compute the complex hyperbolic cosine of a complex number| -|[`csinh`, `csinhf`, `csinhl`](../c-runtime-library/reference/csinh-csinhf-csinhl.md)|Compute the complex hyperbolic sine of a complex number| -|[`ctanh`, `ctanhf`, `ctanhl`](../c-runtime-library/reference/ctanh-ctanhf-ctanhl.md)|Compute the complex hyperbolic tangent of a complex number| +| Function | Description | +|---|---| +| [`cacosh`, `cacoshf`, `cacoshl`](./reference/cacosh-cacoshf-cacoshl.md) | Compute the complex arc hyperbolic cosine of a complex number | +| [`casinh`, `casinhf`, `casinhl`](./reference/casinh-casinhf-casinhl.md) | Compute the complex arc hyperbolic sine of a complex number | +| [`catanh`, `catanhf`, `catanhl`](./reference/catanh-catanhf-catanhl.md) | Compute the complex arc hyperbolic tangent of a complex number | +| [`ccosh`, `ccoshf`, `ccoshl`](./reference/ccosh-ccoshf-ccoshl.md) | Compute the complex hyperbolic cosine of a complex number | +| [`csinh`, `csinhf`, `csinhl`](./reference/csinh-csinhf-csinhl.md) | Compute the complex hyperbolic sine of a complex number | +| [`ctanh`, `ctanhf`, `ctanhl`](./reference/ctanh-ctanhf-ctanhl.md) | Compute the complex hyperbolic tangent of a complex number | ## Exponential and logarithmic functions -|Function|Description| -|-|-| -|[`cexp`, `cexpf`, `cexpl`](../c-runtime-library/reference/cexp-cexpf-cexpl.md)|Compute the complex base-*e* exponential of a complex number| -|[`clog`, `clogf`, `clogl`](../c-runtime-library/reference/clog-clogf-clogl.md)|Compute the complex natural (base-*e*) logarithm of a complex number| -|[`clog10`, `clog10f`, `clog10l`](../c-runtime-library/reference/clog10-clog10f-clog10l.md)|Compute the complex base-10 logarithm of a complex number| +| Function | Description | +|---|---| +| [`cexp`, `cexpf`, `cexpl`](./reference/cexp-cexpf-cexpl.md) | Compute the complex base-*e* exponential of a complex number | +| [`clog`, `clogf`, `clogl`](./reference/clog-clogf-clogl.md) | Compute the complex natural (base-*e*) logarithm of a complex number | +| [`clog10`, `clog10f`, `clog10l`](./reference/clog10-clog10f-clog10l.md) | Compute the complex base-10 logarithm of a complex number | ## Power and absolute-value functions -|Function|Description| -|-|-| -|[`cabs`, `cabsf`, `cabsl`](../c-runtime-library/reference/cabs-cabsf-cabsl.md)|Compute the complex absolute value (also called the norm, modulus, or magnitude) of a complex number| -|[`cpow`, `cpowf`, `cpowl`](../c-runtime-library/reference/cpow-cpowf-cpowl.md)|Compute the complex power function xy| -|[`csqrt`, `csqrtf`, `csqrtl`](../c-runtime-library/reference/csqrt-csqrtf-csqrtl.md)|Compute the complex square root of a complex number| +| Function | Description | +|---|---| +| [`cabs`, `cabsf`, `cabsl`](./reference/cabs-cabsf-cabsl.md) | Compute the complex absolute value (also called the norm, modulus, or magnitude) of a complex number | +| [`cpow`, `cpowf`, `cpowl`](./reference/cpow-cpowf-cpowl.md) | Compute the complex power function | +| [`csqrt`, `csqrtf`, `csqrtl`](./reference/csqrt-csqrtf-csqrtl.md) | Compute the complex square root of a complex number | ## Manipulation functions -|Function|Description| -|-|-| -|[`_Cbuild`, `_FCbuild`, `_LCbuild`](../c-runtime-library/reference/cbuild-fcbuild-lcbuild.md)|Construct a complex number from real and imaginary parts| -|[`carg`, `cargf`, `cargl`](../c-runtime-library/reference/carg-cargf-cargl.md)|Compute the argument (also called the phase angle) of a complex number| -|[`cimag`, `cimagf`, `cimagl`](../c-runtime-library/reference/cimag-cimagf-cimagl.md)|Compute the imaginary part of a complex number| -|[`conj`, `conjf`, `conjl`](../c-runtime-library/reference/conj-conjf-conjl.md)|Compute the complex conjugate of a complex number| -|[`cproj`, `cprojf`, `cprojl`](../c-runtime-library/reference/cproj-cprojf-cprojl.md)|Compute a projection of a complex number onto the Riemann sphere| -|[`creal`, `crealf`, `creall`](../c-runtime-library/reference/creal-crealf-creall.md)|Compute the real part of a complex number| -|[`norm`, `normf`, `norml`](../c-runtime-library/reference/norm-normf-norml1.md)|Compute the squared magnitude of a complex number| +| Function | Description | +|---|---| +| [`_Cbuild`, `_FCbuild`, `_LCbuild`](./reference/cbuild-fcbuild-lcbuild.md) | Construct a complex number from real and imaginary parts | +| [`carg`, `cargf`, `cargl`](./reference/carg-cargf-cargl.md) | Compute the argument (also called the phase angle) of a complex number | +| [`cimag`, `cimagf`, `cimagl`](./reference/cimag-cimagf-cimagl.md) | Compute the imaginary part of a complex number | +| [`conj`, `conjf`, `conjl`](./reference/conj-conjf-conjl.md) | Compute the complex conjugate of a complex number | +| [`cproj`, `cprojf`, `cprojl`](./reference/cproj-cprojf-cprojl.md) | Compute a projection of a complex number onto the Riemann sphere | +| [`creal`, `crealf`, `creall`](./reference/creal-crealf-creall.md) | Compute the real part of a complex number | +| [`norm`, `normf`, `norml`](./reference/norm-normf-norml1.md) | Compute the squared magnitude of a complex number | ## Operation functions Because complex numbers aren't a native type in the Microsoft compiler, the standard arithmetic operators aren't defined on complex types. For convenience, these complex math library functions are provided to enable limited manipulation of complex numbers in user code: -|Function|Description| -|-|-| -|[`_Cmulcc`, `_FCmulcc`, `_LCmulcc`](../c-runtime-library/reference/cmulcc-fcmulcc-lcmulcc.md)|Multiply two complex numbers| -|[`_Cmulcr`, `_FCmulcr`, `_LCmulcr`](../c-runtime-library/reference/cmulcr-fcmulcr-lcmulcr.md)|Multiply a complex and a floating-point number| +| Function | Description | +|---|---| +| [`_Cmulcc`, `_FCmulcc`, `_LCmulcc`](./reference/cmulcc-fcmulcc-lcmulcc.md) | Multiply two complex numbers | +| [`_Cmulcr`, `_FCmulcr`, `_LCmulcr`](./reference/cmulcr-fcmulcr-lcmulcr.md) | Multiply a complex and a floating-point number | ## See also [Type-generic math](tgmath.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/console-and-port-i-o.md b/docs/c-runtime-library/console-and-port-i-o.md index 311cc2eebf1..df8063f3005 100644 --- a/docs/c-runtime-library/console-and-port-i-o.md +++ b/docs/c-runtime-library/console-and-port-i-o.md @@ -4,31 +4,31 @@ title: "Console and Port I/O" ms.date: "11/04/2016" helpviewer_keywords: ["routines, console and port I/O", "routines", "ports, I/O routines", "I/O [CRT], console", "I/O [CRT], port", "I/O routines, console and port I/O"] --- -# Console and Port I/O +# Console and port I/O -These routines read and write on your console or on the specified port. The console I/O routines aren't compatible with stream I/O or low-level I/O library routines. The console or port doesn't have to be opened or closed before I/O is performed, so there are no open or close routines in this category. In the Windows operating systems, the output from these functions is always directed to the console and can’t be redirected. +These routines read and write on your console or on the specified port. The console I/O routines aren't compatible with stream I/O or low-level I/O library routines. The console or port doesn't have to be opened or closed before I/O is performed, so there are no open or close routines in this category. In the Windows operating systems, the output from these functions is always directed to the console and can't be redirected. -## Console and Port I/O Routines +## Console and port I/O routines -|Routine|Use| -|-------------|---------| -|[`_cgets`, `_cgetws`](../c-runtime-library/cgets-cgetws.md), [`_cgets_s`, `_cgetws_s`](../c-runtime-library/reference/cgets-s-cgetws-s.md)|Read string from console| -|[`_cprintf`, `_cwprintf`](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md), [`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](../c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)|Write formatted data to console| -|[`_cputs`](../c-runtime-library/reference/cputs-cputws.md)|Write string to console| -|[`_cscanf`, `_cwscanf`](../c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md), [`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](../c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)|Read formatted data from console| -|[`_getch`, `_getwch`](../c-runtime-library/reference/getch-getwch.md)|Read character from console| -|[`_getche`, `_getwche`](../c-runtime-library/reference/getch-getwch.md)|Read character from console and echo it| -|[`_inp`](../c-runtime-library/inp-inpw-inpd.md)|Read one byte from specified I/O port| -|[`_inpd`](../c-runtime-library/inp-inpw-inpd.md)|Read double word from specified I/O port| -|[`_inpw`](../c-runtime-library/inp-inpw-inpd.md)|Read 2-byte word from specified I/O port| -|[`_kbhit`](../c-runtime-library/reference/kbhit.md)|Check for keystroke at console; use before attempting to read from console| -|[`_outp`](../c-runtime-library/outp-outpw-outpd.md)|Write one byte to specified I/O port| -|[`_outpd`](../c-runtime-library/outp-outpw-outpd.md)|Write double word to specified I/O port| -|[`_outpw`](../c-runtime-library/outp-outpw-outpd.md)|Write word to specified I/O port| -|[`_putch`, `_putwch`](../c-runtime-library/reference/putch-putwch.md)|Write character to console| -|[`_ungetch`, `_ungetwch`](../c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md)|"Unget" last character read from console so it becomes next character read| +| Routine | Use | +|---|---| +| [`_cgets`, `_cgetws`](./cgets-cgetws.md), [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md) | Read string from console | +| [`_cprintf`, `_cwprintf`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md), [`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](./reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md) | Write formatted data to console | +| [`_cputs`](./reference/cputs-cputws.md) | Write string to console | +| [`_cscanf`, `_cwscanf`](./reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md), [`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](./reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md) | Read formatted data from console | +| [`_getch`, `_getwch`](./reference/getch-getwch.md) | Read character from console | +| [`_getche`, `_getwche`](./reference/getch-getwch.md) | Read character from console and echo it | +| [`_inp`](./inp-inpw-inpd.md) | Read a byte from the specified I/O port | +| [`_inpd`](./inp-inpw-inpd.md) | Read double word from specified I/O port | +| [`_inpw`](./inp-inpw-inpd.md) | Read 2-byte word from specified I/O port | +| [`_kbhit`](./reference/kbhit.md) | Check for keystroke at console; use before attempting to read from console | +| [`_outp`](./outp-outpw-outpd.md) | Write a byte to the specified I/O port | +| [`_outpd`](./outp-outpw-outpd.md) | Write double word to specified I/O port | +| [`_outpw`](./outp-outpw-outpd.md) | Write word to specified I/O port | +| [`_putch`, `_putwch`](./reference/putch-putwch.md) | Write character to console | +| [`_ungetch`, `_ungetwch`](./reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) | "Unget" last character read from console so it becomes next character read | ## See also -[Input and Output](../c-runtime-library/input-and-output.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Input and output](./input-and-output.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/constant-and-global-variable-mappings.md b/docs/c-runtime-library/constant-and-global-variable-mappings.md index 1a99b8b9215..92f33e1dd75 100644 --- a/docs/c-runtime-library/constant-and-global-variable-mappings.md +++ b/docs/c-runtime-library/constant-and-global-variable-mappings.md @@ -2,26 +2,26 @@ description: "Learn more about: Constant and Global Variable Mappings" title: "Constant and Global Variable Mappings" ms.date: "11/04/2016" -f1_keywords: ["_tenviron", "_TEOF", "_tfinddata_t"] -helpviewer_keywords: ["tfinddatat function", "tenviron function", "TEOF type", "_TEOF type", "generic-text mappings", "_tenviron function", "_tfinddata_t function"] +f1_keywords: ["_tenviron", "TCHAR/_tenviron", "_TEOF", "TCHAR/_TEOF", "_tpgmptr", "TCHAR/_tpgmptr"] +helpviewer_keywords: ["_tenviron global constant", "_TEOF global constant", "_tpgmptr global constant"] ms.assetid: 3af4fd3e-9ed5-4ed9-96fd-7031e5126fd1 --- -# Constant and Global Variable Mappings +# Constant and global variable mappings These generic-text constant, global variable, and standard-type mappings are defined in TCHAR.H and depend on whether the constant `_UNICODE` or `_MBCS` has been defined in your program. -### Generic-Text Constant and Global Variable Mappings +### Generic-text constant and global variable mappings -|Generic-text - object name|SBCS (_UNICODE, _MBCS not defined)|_MBCS defined|_UNICODE defined| -|----------------------------------|--------------------------------------------|--------------------|-----------------------| -|`_TEOF`|`EOF`|`EOF`|`WEOF`| -|`_tenviron`|`_environ`|`_environ`|`_wenviron`| -|`_tpgmptr`|`_pgmptr`|`_pgmptr`|`_wpgmptr`| +| Generic-text - object name | SBCS (`_UNICODE`, `_MBCS` not defined) | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_TEOF` | `EOF` | `EOF` | `WEOF` | +| `_tenviron` | `_environ` | `_environ` | `_wenviron` | +| `_tpgmptr` | `_pgmptr` | `_pgmptr` | `_wpgmptr` | ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[Routine Mappings](../c-runtime-library/routine-mappings.md)
-[A Sample Generic-Text Program](../c-runtime-library/a-sample-generic-text-program.md)
-[Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Data type mappings](./data-type-mappings.md)\ +[Routine mappings](./routine-mappings.md)\ +[A sample generic-text program](./a-sample-generic-text-program.md)\ +[Using generic-text mappings](./using-generic-text-mappings.md) diff --git a/docs/c-runtime-library/control-flags.md b/docs/c-runtime-library/control-flags.md index 39bd64088d3..5ba1384bfc2 100644 --- a/docs/c-runtime-library/control-flags.md +++ b/docs/c-runtime-library/control-flags.md @@ -6,18 +6,18 @@ f1_keywords: ["c.flags"] helpviewer_keywords: ["flags, control", "heap allocation, control flags", "debug heap, control flags"] ms.assetid: 8dbd24a5-0633-42d1-9771-776db338465f --- -# Control Flags +# Control flags -The debug version of the Microsoft C run-time library uses the following flags to control the heap allocation and reporting process. For more information, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +The debug version of the Microsoft C run-time library uses the following flags to control the heap allocation and reporting process. For more information, see [CRT debugging techniques](./crt-debugging-techniques.md). -|Flag|Description| -|----------|-----------------| -|[_CRTDBG_MAP_ALLOC](../c-runtime-library/crtdbg-map-alloc.md)|Maps the base heap functions to their debug version counterparts| -|[_DEBUG](../c-runtime-library/debug.md)|Enables the use of the debugging versions of the run-time functions| -|[_crtDbgFlag](../c-runtime-library/crtdbgflag.md)|Controls how the debug heap manager tracks allocations| +| Flag | Description | +|---|---| +| [`_CRTDBG_MAP_ALLOC`](./crtdbg-map-alloc.md) | Maps the base heap functions to their debug version counterparts | +| [`_DEBUG`](./debug.md) | Enables the use of the debugging versions of the run-time functions | +| [`_crtDbgFlag`](./crtdbgflag.md) | Controls how the debug heap manager tracks allocations | -These flags can be defined with a /D command-line option or with a `#define` directive. When the flag is defined with `#define`, the directive must appear before the header file include statement for the routine declarations. +These flags can be defined with a /D command-line option or with a `#define` directive. When the flag is defined with `#define`, the directive must appear before the header file `#include` directive for the routine declarations. ## See also -[Global Variables and Standard Types](../c-runtime-library/global-variables-and-standard-types.md) +[Global variables and standard types](./global-variables-and-standard-types.md) diff --git a/docs/c-runtime-library/controlling-streams.md b/docs/c-runtime-library/controlling-streams.md index 995d1e12d57..43c00a11a4c 100644 --- a/docs/c-runtime-library/controlling-streams.md +++ b/docs/c-runtime-library/controlling-streams.md @@ -2,16 +2,15 @@ title: "Controlling Streams" description: "An overview of working with streams in the Microsoft C runtime library." ms.date: "11/04/2016" -ms.topic: "conceptual" -f1_keywords: ["Controlling Streams"] +ms.topic: "concept-article" helpviewer_keywords: ["streams, controlling", "controlling streams", "streams"] ms.assetid: 267e9013-9afc-45f6-91e3-ca093230d9d9 --- -# Controlling Streams +# Controlling streams -[fopen](../c-runtime-library/reference/fopen-wfopen.md) returns the address of an object of type `FILE`. You use this address as the `stream` argument to several library functions to perform various operations on an open file. For a byte stream, all input takes place as if each character is read by calling [fgetc](../c-runtime-library/reference/fgetc-fgetwc.md), and all output takes place as if each character is written by calling [fputc](../c-runtime-library/reference/fputc-fputwc.md). For a wide stream, all input takes place as if each character is read by calling [fgetwc](../c-runtime-library/reference/fgetc-fgetwc.md), and all output takes place as if each character is written by calling [fputwc](../c-runtime-library/reference/fputc-fputwc.md). +[`fopen`](./reference/fopen-wfopen.md) returns the address of an object of type `FILE`. You use this address as the `stream` argument to several library functions to perform various operations on an open file. For a byte stream, all input takes place as if each character is read by calling [`fgetc`](./reference/fgetc-fgetwc.md). All output takes place as if each character is written by calling [`fputc`](./reference/fputc-fputwc.md). For a wide stream, all input takes place as if each character is read by calling [`fgetwc`](./reference/fgetc-fgetwc.md). All output takes place as if each character is written by calling [`fputwc`](./reference/fputc-fputwc.md). -You can close a file by calling [fclose](../c-runtime-library/reference/fclose-fcloseall.md), after which the address of the `FILE` object is invalid. +You can close a file by calling [`fclose`](./reference/fclose-fcloseall.md), after which the address of the `FILE` object is invalid. A `FILE` object stores the state of a stream, including: @@ -21,14 +20,14 @@ A `FILE` object stores the state of a stream, including: - A file-position indicator specifies the next byte in the stream to read or write, if the file can support positioning requests. -- A [stream state](../c-runtime-library/stream-states.md) specifies whether the stream will accept reads and/or writes and whether the stream is unbound, byte oriented, or wide oriented. +- A [stream state](./stream-states.md) specifies whether the stream will accept reads and/or writes and whether the stream is unbound, byte oriented, or wide oriented. -- A conversion state remembers the state of any partly assembled or generated generalized multibyte character, as well as any shift state for the sequence of bytes in the file). +- A conversion state remembers the state of any partly assembled or generated generalized multibyte character, and any shift state for the sequence of bytes in the file). -- A file buffer specifies the address and size of an array object that library functions can use to improve the performance of read and write operations to the stream. +- A file buffer specifies the address and size of an array object. Library functions can use it to improve the performance of read and write operations to the stream. -Do not alter any value stored in a `FILE` object or in a file buffer that you specify for use with that object. You cannot copy a `FILE` object and portably use the address of the copy as a `stream` argument to a library function. +Don't alter any value stored in a `FILE` object or in a file buffer that you specify for use with that object. You can't copy a `FILE` object and portably use the address of the copy as a `stream` argument to a library function. ## See also -[Files and Streams](../c-runtime-library/files-and-streams.md) +[Files and streams](./files-and-streams.md) diff --git a/docs/c-runtime-library/country-region-strings.md b/docs/c-runtime-library/country-region-strings.md index 2f44a1e86ad..30b8889911b 100644 --- a/docs/c-runtime-library/country-region-strings.md +++ b/docs/c-runtime-library/country-region-strings.md @@ -4,45 +4,45 @@ description: "Learn more about: Country/Region Strings" ms.date: "1/29/2020" helpviewer_keywords: ["country/region strings"] --- -# Country/Region Strings +# Country/region strings Country and region strings can be combined with a language string to create a locale specification for the `setlocale`, `_wsetlocale`, `_create_locale`, and `_wcreate_locale` functions. For lists of country and region names that are supported by various Windows operating system versions, see the **Language**, **Location**, and **Language tag** columns of the table in [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. For an example of code that enumerates available locale names and related values, see [NLS: Name-based APIs Sample](/windows/win32/intl/nls--name-based-apis-sample). -## Additional supported country and region strings +## Other supported country and region strings -The Microsoft C run-time library implementation also supports the following additional country/region strings and abbreviations: +The Microsoft C run-time library implementation also supports the following country/region strings and abbreviations: -|Country/region string|Abbreviation|Equivalent locale name| -|----------------------------|------------------|----------------------------| -|`america`|`USA`|`en-US`| -|`britain`|`GBR`|`en-GB`| -|`china`|`CHN`|`zh-CN`| -|`czech`|`CZE`|`cs-CZ`| -|`england`|`GBR`|`en-GB`| -|`great britain`|`GBR`|`en-GB`| -|`holland`|`NLD`|`nl-NL`| -|`hong-kong`|`HKG`|`zh-HK`| -|`new-zealand`|`NZL`|`en-NZ`| -|`nz`|`NZL`|`en-NZ`| -|`pr china`|`CHN`|`zh-CN`| -|`pr-china`|`CHN`|`zh-CN`| -|`puerto-rico`|`PRI`|`es-PR`| -|`slovak`|`SVK`|`sk-SK`| -|`south africa`|`ZAF`|`af-ZA`| -|`south korea`|`KOR`|`ko-KR`| -|`south-africa`|`ZAF`|`af-ZA`| -|`south-korea`|`KOR`|`ko-KR`| -|`trinidad & tobago`|`TTO`|`en-TT`| -|`uk`|`GBR`|`en-GB`| -|`united-kingdom`|`GBR`|`en-GB`| -|`united-states`|`USA`|`en-US`| -|`us`|`USA`|`en-US`| +| Country/region string | Abbreviation | Equivalent locale name | +|---|---|---| +| `america` | `USA` | `en-US` | +| `britain` | `GBR` | `en-GB` | +| `china` | `CHN` | `zh-CN` | +| `czech` | `CZE` | `cs-CZ` | +| `england` | `GBR` | `en-GB` | +| `great britain` | `GBR` | `en-GB` | +| `holland` | `NLD` | `nl-NL` | +| `hong-kong` | `HKG` | `zh-HK` | +| `new-zealand` | `NZL` | `en-NZ` | +| `nz` | `NZL` | `en-NZ` | +| `pr china` | `CHN` | `zh-CN` | +| `pr-china` | `CHN` | `zh-CN` | +| `puerto-rico` | `PRI` | `es-PR` | +| `slovak` | `SVK` | `sk-SK` | +| `south africa` | `ZAF` | `af-ZA` | +| `south korea` | `KOR` | `ko-KR` | +| `south-africa` | `ZAF` | `af-ZA` | +| `south-korea` | `KOR` | `ko-KR` | +| `trinidad & tobago` | `TTO` | `en-TT` | +| `uk` | `GBR` | `en-GB` | +| `united-kingdom` | `GBR` | `en-GB` | +| `united-states` | `USA` | `en-US` | +| `us` | `USA` | `en-US` | ## See also -[Locale Names, Languages, and Country/Region Strings](../c-runtime-library/locale-names-languages-and-country-region-strings.md)
-[Language Strings](../c-runtime-library/language-strings.md)
-[`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[`_create_locale`, `_wcreate_locale`](../c-runtime-library/reference/create-locale-wcreate-locale.md) +[Locale names, Languages, and Country/Region strings](./locale-names-languages-and-country-region-strings.md)\ +[Language strings](./language-strings.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md) diff --git a/docs/c-runtime-library/crt-debug-heap-details.md b/docs/c-runtime-library/crt-debug-heap-details.md new file mode 100644 index 00000000000..5a0d180c7d8 --- /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 00000000000..fd4c975e460 --- /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`](../build/reference/debug-generate-debug-info.md) and compile with [`/MDd`, `/MTd`, or `/LDd`](../build/reference/md-mt-ld-use-run-time-library.md). + +The main definitions and macros for CRT debugging can be found in the `` header file. + +The functions in the CRT debug libraries are compiled with debug information ([/Z7, /Zd, /Zi, /ZI (Debug Information Format)](../build/reference/z7-zi-zi-debug-information-format.md)) and without optimization. Some functions contain assertions to verify parameters that are passed to them, and source code is provided. With this source code, you can step into CRT functions to confirm that the functions are working as you expect and check for bad parameters or memory states. (Some CRT technology is proprietary and doesn't provide source code for exception handling, floating point, and a few other routines.) + +For more information on the various run-time libraries you can use, see [C Run-Time Libraries](./crt-library-features.md). + +## Macros for reporting + +For debugging, you can use the `_RPTn` and `_RPTFn` macros, defined in ``, to replace the use of `printf` statements. You don't need to enclose them in `#ifdef` directives, because they automatically disappear in your release build when `_DEBUG` isn't defined. + +| Macro | Description | +|---|---| +| `_RPT0`, `_RPT1`, `_RPT2`, `_RPT3`, `_RPT4` | Outputs a message string and zero to four arguments. For `_RPT1` through `_RPT4`, the message string serves as a printf-style formatting string for the arguments. | +| `_RPTF0`, `_RPTF1`, `_RPTF2`, `_RPTF3`, `_RPTF4` | Same as `_RPTn`, but these macros also output the file name and line number where the macro is located. | + +Consider the following example: + +```cpp +#ifdef _DEBUG + if ( someVar > MAX_SOMEVAR ) + printf( "OVERFLOW! In NameOfThisFunc( ), + someVar=%d, otherVar=%d.\n", + someVar, otherVar ); +#endif +``` + +This code outputs the values of `someVar` and `otherVar` to `stdout`. You can use the following call to `_RPTF2` to report these same values and, additionally, the file name and line number: + +```cpp +if (someVar > MAX_SOMEVAR) _RPTF2(_CRT_WARN, "In NameOfThisFunc( ), someVar= %d, otherVar= %d\n", someVar, otherVar ); +``` + +Some applications may need debug reporting that the macros supplied with the C run-time library don't provide. For these cases, you can write a macro designed specifically to fit your own requirements. In one of your header files, for example, you could include code like the following to define a macro called `ALERT_IF2`: + +```cpp +#ifndef _DEBUG /* For RELEASE builds */ +#define ALERT_IF2(expr, msg, arg1, arg2) do {} while (0) +#else /* For DEBUG builds */ +#define ALERT_IF2(expr, msg, arg1, arg2) \ + do { \ + if ((expr) && \ + (1 == _CrtDbgReport(_CRT_ERROR, \ + __FILE__, __LINE__, msg, arg1, arg2))) \ + _CrtDbgBreak( ); \ + } while (0) +#endif +``` + +One call to `ALERT_IF2` could do all the functions of the `printf` code: + +```cpp +ALERT_IF2(someVar > MAX_SOMEVAR, "OVERFLOW! In NameOfThisFunc( ), +someVar=%d, otherVar=%d.\n", someVar, otherVar ); +``` + +You can easily change a custom macro to report more or less information to different destinations. This approach is useful as your debugging requirements evolve. + +## Debug hook function writing + +You can write several kinds of custom debug hook functions that allow you to insert your code into some predefined points inside the debugger's normal processing. + +### Client block hook functions + +If you want to validate or report the contents of the data stored in `_CLIENT_BLOCK` blocks, you can write a function specifically for this purpose. The function that you write must have a prototype similar to the following, as defined in ``: + +```cpp +void YourClientDump(void *, size_t) +``` + +In other words, your hook function should accept a `void` pointer to the beginning of the allocation block, together with a `size_t` type value indicating the size of the allocation, and return `void`. Otherwise, its contents are up to you. + +Once you've installed your hook function using [_CrtSetDumpClient](./reference/crtsetdumpclient.md), it will be called every time a `_CLIENT_BLOCK` block is dumped. You can then use [_CrtReportBlockType](./reference/crtreportblocktype.md) to get information on the type or subtype of dumped blocks. + +The pointer to your function that you pass to `_CrtSetDumpClient` is of type `_CRT_DUMP_CLIENT`, as defined in ``: + +```cpp +typedef void (__cdecl *_CRT_DUMP_CLIENT) + (void *, size_t); +``` + +### Allocation hook functions + +An allocation hook function, installed using [`_CrtSetAllocHook`](./reference/crtsetallochook.md), is called every time memory is allocated, reallocated, or freed. You can use this type of hook for many different purposes. Use it to test how an application handles insufficient memory situations, such as to examine allocation patterns, or log allocation information for later analysis. + +> [!NOTE] +> Be aware of the restriction about using C runtime library functions in an allocation hook function, described in [Allocation hooks and crt memory allocations](#allocation-hooks-and-crt-memory-allocations). + +An allocation hook function should have a prototype like the following example: + +```cpp +int YourAllocHook(int nAllocType, void *pvData, + size_t nSize, int nBlockUse, long lRequest, + const unsigned char * szFileName, int nLine ) +``` + +The pointer that you pass to [`_CrtSetAllocHook`](./reference/crtsetallochook.md) is of type `_CRT_ALLOC_HOOK`, as defined in ``: + +```cpp +typedef int (__cdecl * _CRT_ALLOC_HOOK) + (int, void *, size_t, int, long, const unsigned char *, int); +``` + +When the run-time library calls your hook, the *`nAllocType`* argument indicates what allocation operation is about to be made (`_HOOK_ALLOC`, `_HOOK_REALLOC`, or `_HOOK_FREE`). In a free or in a reallocation, `pvData` has a pointer to the user article of the block about to be freed. However for an allocation, this pointer is null, because the allocation hasn't occurred. The remaining arguments contain the size of the allocation, its block type, a sequential request number, and a pointer to the file name. If available, the arguments also include the line number in which the allocation was made. After the hook function performs whatever analysis and other tasks its author wants, it must return either `TRUE`, indicating that the allocation operation can continue, or `FALSE`, indicating that the operation should fail. A simple hook of this type might check the amount of memory allocated so far, and return `FALSE` if that amount exceeded a small limit. The application would then experience the kind of allocation errors that would normally occur only when available memory was low. More complex hooks might keep track of allocation patterns, analyze memory use, or report when specific situations occur. + +### Allocation hooks and CRT memory allocations + +An important restriction on allocation hook functions is that they must explicitly ignore `_CRT_BLOCK` blocks. These blocks are the memory allocations made internally by C run-time library functions if they make any calls to C run-time library functions that allocate internal memory. You can ignore `_CRT_BLOCK` blocks by including the following code at the beginning of your allocation hook function: + +```cpp +if ( nBlockUse == _CRT_BLOCK ) + return( TRUE ); +``` + +If your allocation hook doesn't ignore `_CRT_BLOCK` blocks, then any C run-time library function called in your hook can trap the program in an endless loop. For example, `printf` makes an internal allocation. If your hook code calls `printf`, then the resulting allocation will cause your hook to be called again, which will call `printf` again, and so on, until the stack overflows. If you need to report `_CRT_BLOCK` allocation operations, one way to circumvent this restriction is to use Windows API functions, rather than C run-time functions, for formatting and output. Because the Windows APIs don't use the C run-time library heap, they won't trap your allocation hook in an endless loop. + +If you examine the run-time library source files, you'll see that the default allocation hook function, `_CrtDefaultAllocHook` (which simply returns `TRUE`), is located in a separate file of its own, *`debug_heap_hook.cpp`*. If you want your allocation hook to be called even for the allocations made by the run-time startup code that is executed before your application's `main` function, you can replace this default function with one of your own, instead of using [`_CrtSetAllocHook`](./reference/crtsetallochook.md). + +### Report hook functions + +A report hook function, installed using [`_CrtSetReportHook`](./reference/crtsetreporthook.md), is called every time [`_CrtDbgReport`](./reference/crtdbgreport-crtdbgreportw.md) generates a debug report. You can use it, among other things, for filtering reports to focus on specific types of allocations. A report hook function should have a prototype like this example: + +```cpp +int AppReportHook(int nRptType, char *szMsg, int *retVal); +``` + +The pointer that you pass to `_CrtSetReportHook` is of type `_CRT_REPORT_HOOK`, as defined in ``: + +```cpp +typedef int (__cdecl *_CRT_REPORT_HOOK)(int, char *, int *); +``` + +When the run-time library calls your hook function, the *`nRptType`* argument contains the category of the report (`_CRT_WARN`, `_CRT_ERROR`, or `_CRT_ASSERT`), *`szMsg`* contains a pointer to a fully assembled report message string, and *`retVal`* specifies whether `_CrtDbgReport` should continue normal execution after generating the report or start the debugger. (A *`retVal`* value of zero continues execution, a value of 1 starts the debugger.) + +If the hook handles the message in question completely, so that no further reporting is required, it should return `TRUE`. If it returns `FALSE`, `_CrtDbgReport` will report the message normally. + +## In this section + +- [Debug versions of heap allocation functions](./debug-versions-of-heap-allocation-functions.md) + + Discusses the special Debug versions of the heap allocation functions, including: how the CRT maps calls, the benefits of calling them explicitly, how to avoid conversion, tracking the separate types of allocations in client blocks, and the results of not defining `_DEBUG`. + +- [CRT debug heap details](./crt-debug-heap-details.md) + + Describes memory management and the debug heap, the types of blocks on the debug heap, heap state reporting functions, and how to use the debug heap to track allocation requests. + +- [Find memory leaks using the CRT library](./find-memory-leaks-using-the-crt-library.md) + + Covers techniques for detecting and isolating memory leaks by using the debugger and the C Run-Time Library. + +## See also + +- [Debugging Native Code](/visualstudio/debugger/debugging-native-code) +- [Debugger Security](/visualstudio/debugger/debugger-security) diff --git a/docs/c-runtime-library/crt-disable-perfcrit-locks.md b/docs/c-runtime-library/crt-disable-perfcrit-locks.md index c6d776a32c1..bd9a092c1be 100644 --- a/docs/c-runtime-library/crt-disable-perfcrit-locks.md +++ b/docs/c-runtime-library/crt-disable-perfcrit-locks.md @@ -2,24 +2,24 @@ description: "Learn more about: _CRT_DISABLE_PERFCRIT_LOCKS" title: "_CRT_DISABLE_PERFCRIT_LOCKS" ms.date: "11/04/2016" -f1_keywords: ["_CRT_DISABLE_PERFCRIT_LOCKS", "CRT_DISABLE_PERFCRIT_LOCKS"] +f1_keywords: ["_CRT_DISABLE_PERFCRIT_LOCKS"] helpviewer_keywords: ["CRT_DISABLE_PERFCRIT_LOCKS constant", "_CRT_DISABLE_PERFCRIT_LOCKS constant"] ms.assetid: 36cc2d86-cdb1-4b2b-a03c-c0d3818e7c6f --- -# _CRT_DISABLE_PERFCRIT_LOCKS +# `_CRT_DISABLE_PERFCRIT_LOCKS` Disables performance-critical locking in I/O operations. ## Syntax -``` +```C #define _CRT_DISABLE_PERFCRIT_LOCKS ``` ## Remarks -Defining this symbol can improve performance in single-threaded I/O-bound programs by forcing all I/O operations to assume a single-threaded I/O model. For more information, see [Multithreaded Libraries Performance](../c-runtime-library/multithreaded-libraries-performance.md). +Defining this symbol can improve performance in single-threaded I/O-bound programs by forcing all I/O operations to assume a single-threaded I/O model. For more information, see [Multithreaded libraries performance](./multithreaded-libraries-performance.md). ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/crt-initialization.md b/docs/c-runtime-library/crt-initialization.md index d426c7aee0c..be30e01238f 100644 --- a/docs/c-runtime-library/crt-initialization.md +++ b/docs/c-runtime-library/crt-initialization.md @@ -1,12 +1,11 @@ --- title: "CRT Initialization" description: "Describes how the CRT initializes global state in native code." -ms.topic: "conceptual" +ms.topic: "concept-article" ms.date: 08/02/2021 helpviewer_keywords: ["CRT initialization [C++]"] -ms.assetid: e7979813-1856-4848-9639-f29c86b74ad7 --- -# CRT Initialization +# CRT initialization This article describes how the CRT initializes global state in native code. @@ -14,11 +13,11 @@ By default, the linker includes the CRT library, which provides its own startup It's possible, though not recommended, to take advantage of Microsoft-specific linker behavior to insert your own global initializers in a specific order. This code isn't portable, and comes with some important caveats. -## Initializing a Global Object +## Initializing a global object -Consider the following code: +Consider the following C++ code (C won't allow this code because it doesn't allow a function call in a constant expression). -``` +```cpp int func(void) { return 3; @@ -69,7 +68,6 @@ Offset Type Applied To Index Name The CRT defines two pointers: - `__xc_a` in `.CRT$XCA` - - `__xc_z` in `.CRT$XCZ` Neither group has any other symbols defined except `__xc_a` and `__xc_z`. @@ -88,7 +86,7 @@ The section should resemble this example: __xc_z ``` -So, the CRT library uses both `__xc_a` and `__xc_z` to determine the start and end of the global initializers list because of the way in which they're laid out in memory after the image is loaded. +The CRT library uses both `__xc_a` and `__xc_z` to determine the start and end of the global initializers list because of the way in which they're laid out in memory after the image is loaded. ## Linker features for initialization @@ -112,4 +110,5 @@ The names `.CRT$XCT` and `.CRT$XCV` aren't used by either the compiler or the CR ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[`_initterm, _initterm_e`](./reference/initterm-initterm-e.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/crt-library-features.md b/docs/c-runtime-library/crt-library-features.md index 8d5d337794a..165f5090864 100644 --- a/docs/c-runtime-library/crt-library-features.md +++ b/docs/c-runtime-library/crt-library-features.md @@ -1,24 +1,28 @@ --- -title: "C runtime (CRT) and C++ Standard Library .lib files" -description: "List of Microsoft C runtime and C++ Standard Library .lib files that you can link against and their associated compiler options and preprocessor directives." +title: "C runtime (CRT) and C++ standard library (STL) lib files" +description: "List of Microsoft C runtime and C++ standard library (STL) lib files that you can link against and their associated compiler options and preprocessor directives." ms.date: "3/5/2021" ms.topic: "reference" -ms.custom: contperf-fy21q3 -helpviewer_keywords: ["MSVCR71.dll", "libraries [C++], multithreaded", "library files, run-time", "LIBCMT.lib", "LIBCP.lib", "LIBCPMT.lib", "run-time libraries, C", "CRT, release versions", "MSVCP71.dll", "LIBC.lib", "libraries [C++]", "libraries [C++], run-time", "linking [C++], libraries"] +helpviewer_keywords: ["MSVCR71.dll", "libraries [C++], multithreaded", "library files, run-time", "LIBCMT.lib", "LIBCP.lib", "LIBCPMT.lib", "run-time libraries, C", "CRT, release versions", "MSVCP71.dll", "LIBC.lib", "libraries [C++]", "libraries [C++], run-time", "linking [C++], libraries", "STL libraries", "Microsoft standard template libraries"] --- -# C runtime (CRT) and C++ Standard Library (STL) `.lib` files +# C runtime (CRT) and C++ standard library (STL) `.lib` files -This topic lists the Microsoft C runtime library `.lib` files that you can link against when you develop your application, and their associated compiler options and preprocessor directives. +This article lists the Microsoft C runtime library `.lib` files that you can link against when you develop your application, and their associated compiler options and preprocessor directives. See [Redistributing Visual C++ files](../windows/redistributing-visual-cpp-files.md) if you're looking for information about deploying the C runtime files necessary to support your application. -See [C runtime library reference](../c-runtime-library/c-run-time-library-reference.md) if you're looking for API reference for the C runtime library. +See [C runtime library reference](./c-run-time-library-reference.md) if you're looking for API reference for the C runtime library. + +>[!NOTE] +> Microsoft's implementation of the C++ standard library is often referred to as the *STL* or *Standard Template Library*. Although *C++ standard library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation. + +From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ standard library. The standard library also incorporates the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is used to refer to the containers and algorithms parts of the C++ standard library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ standard library as a whole. ## C runtime `.lib` files -The C runtime Library (CRT) is the part of the C++ Standard Library that incorporates the ISO C standard library. The Visual C++ libraries that implement the CRT support native code development, and both mixed native and managed code. All versions of the CRT support multi-threaded development. Most of the libraries support both static linking, to link the library directly into your code, or dynamic linking to let your code use common DLL files. +The ISO C standard library is part of the C++ standard library. The Visual C++ libraries that implement the CRT support native code development, and both mixed native and managed code. All versions of the CRT support multi-threaded development. Most of the libraries support both static linking, to link the library directly into your code, or dynamic linking to let your code use common DLL files. -Starting in Visual Studio 2015, the CRT has been refactored into new binaries. The Universal CRT (UCRT) contains the functions and globals exported by the standard C99 CRT library. The UCRT is now a Windows component, and ships as part of Windows 10 and later versions. The static library, DLL import library, and header files for the UCRT are now found in the Windows SDK. When you install Visual C++, Visual Studio setup installs the subset of the Windows SDK required to use the UCRT. You can use the UCRT on any version of Windows supported by Visual Studio 2015 and later versions. You can redistribute it using vcredist for supported versions of Windows other than Windows 10 or later. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). +In Visual Studio 2015, the CRT was refactored into new binaries. The Universal CRT (UCRT) contains the functions and globals exported by the standard C99 CRT library. The UCRT is now a Windows component, and ships as part of Windows 10 and later versions. The static library, DLL import library, and header files for the UCRT are now found in the Windows SDK. When you install Visual C++, Visual Studio setup installs the subset of the Windows SDK required to use the UCRT. You can use the UCRT on any version of Windows supported by Visual Studio 2015 and later versions. You can redistribute it using vcredist for supported versions of Windows other than Windows 10 or later. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). The following table lists the libraries that implement the UCRT. @@ -29,7 +33,7 @@ The following table lists the libraries that implement the UCRT. | *`ucrt.lib`* | *`ucrtbase.dll`* | DLL import library for the UCRT. | **`/MD`** | `_MT`, `_DLL` | | *`ucrtd.lib`* | *`ucrtbased.dll`* | DLL import library for the Debug version of the UCRT. Not redistributable. | **`/MDd`** | `_DEBUG`, `_MT`, `_DLL` | -The vcruntime library contains Visual C++ CRT implementation-specific code, such as exception handling and debugging support, runtime checks and type information, implementation details and certain extended library functions. The vcruntime library version needs to match the version of the compiler you're using. +The vcruntime library contains Visual C++ CRT implementation-specific code: exception handling and debugging support, runtime checks and type information, implementation details, and certain extended library functions. The vcruntime library version needs to match the version of the compiler you're using. This table lists the libraries that implement the vcruntime library. @@ -42,7 +46,7 @@ This table lists the libraries that implement the vcruntime library. > [!NOTE] > When the UCRT was refactored, the Concurrency Runtime functions were moved into -*`concrt140.dll`*, which was added to the C++ redistributable package. This DLL is required for C++ parallel containers and algorithms such as `concurrency::parallel_for`. In addition, the C++ Standard Library requires this DLL on Windows XP to support synchronization primitives, because Windows XP doesn't have condition variables. +*`concrt140.dll`*, which was added to the C++ redistributable package. This DLL is required for C++ parallel containers and algorithms such as `concurrency::parallel_for`. In addition, the C++ standard library requires this DLL on Windows XP to support synchronization primitives, because Windows XP doesn't have condition variables. The code that initializes the CRT is in one of several libraries, based on whether the CRT library is statically or dynamically linked, or native, managed, or mixed code. This code handles CRT startup, internal per-thread data initialization, and termination. It's specific to the version of the compiler used. This library is always statically linked, even when using a dynamically linked UCRT. @@ -61,46 +65,46 @@ This table lists the libraries that implement CRT initialization and termination If you link your program from the command line without a compiler option that specifies a C runtime library, the linker will use the statically linked CRT libraries: *`libcmt.lib`*, *`libvcruntime.lib`*, and *`libucrt.lib`*. -Using the statically linked CRT implies that any state information saved by the C runtime library will be local to that instance of the CRT. For example, if you use [`strtok`](../c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) when using a statically linked CRT, the position of the `strtok` parser is unrelated to the `strtok` state used in code in the same process (but in a different DLL or EXE) that is linked to another instance of the static CRT. In contrast, the dynamically linked CRT shares state for all code within a process that is dynamically linked to the CRT. This concern doesn't apply if you use the new more secure versions of these functions; for example, `strtok_s` doesn't have this problem. +Using the statically linked CRT implies that any state information saved by the C runtime library will be local to that instance of the CRT. For example, if you use [`strtok`](./reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) when using a statically linked CRT, the position of the `strtok` parser is unrelated to the `strtok` state used in code in the same process (but in a different DLL or EXE) that is linked to another instance of the static CRT. In contrast, the dynamically linked CRT shares state for all code within a process that is dynamically linked to the CRT. This concern doesn't apply if you use the new more secure versions of these functions; for example, `strtok_s` doesn't have this problem. -Because a DLL built by linking to a static CRT has its own CRT state, it isn't recommended to link statically to the CRT in a DLL unless the consequences of this are specifically desired and understood. For example, if you call [`_set_se_translator`](../c-runtime-library/reference/set-se-translator.md) in an executable that loads the DLL linked to its own static CRT, any hardware exceptions generated by the code in the DLL will not be caught by the translator, but hardware exceptions generated by code in the main executable will be caught. +Because a DLL built by linking to a static CRT has its own CRT state, we don't recommend you link statically to the CRT in a DLL unless the consequences are understood and desired. For example, if you call [`_set_se_translator`](./reference/set-se-translator.md) in an executable that loads the DLL linked to its own static CRT, any hardware exceptions generated by the code in the DLL won't be caught by the translator, but hardware exceptions generated by code in the main executable will be caught. -If you're using the **`/clr`** compiler switch, your code will be linked with a static library, `msvcmrt.lib`. The static library provides a proxy between your managed code and the native CRT. You cannot use the statically linked CRT ( **`/MT`** or **`/MTd`** options) with **`/clr`**. Use the dynamically-linked libraries (**`/MD`** or **`/MDd`**) instead. The pure managed CRT libraries are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. +If you're using the **`/clr`** compiler switch, your code will be linked with a static library, `msvcmrt.lib`. The static library provides a proxy between your managed code and the native CRT. You can't use the statically linked CRT ( **`/MT`** or **`/MTd`** options) with **`/clr`**. Use the dynamically linked libraries (**`/MD`** or **`/MDd`**) instead. The pure managed CRT libraries are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. For more information on using the CRT with **`/clr`**, see [Mixed (Native and Managed) Assemblies](../dotnet/mixed-native-and-managed-assemblies.md). -To build a debug version of your application, the [`_DEBUG`](../c-runtime-library/debug.md) flag must be defined and the application must be linked with a debug version of one of these libraries. For more information about using the debug versions of the library files, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +To build a debug version of your application, the [`_DEBUG`](./debug.md) flag must be defined and the application must be linked with a debug version of one of these libraries. For more information about using the debug versions of the library files, see [CRT debugging techniques](./crt-debugging-techniques.md). This version of the CRT isn't fully conformant with the C99 standard. In versions before Visual Studio 2019 version 16.8, the `` header isn't supported. In all versions, the `CX_LIMITED_RANGE` and `FP_CONTRACT` pragma macros aren't supported. Certain elements such as the meaning of parameter specifiers in standard IO functions use legacy interpretations by default. You can use **`/Zc`** compiler conformance options and specify linker options to control some aspects of library conformance. -## C++ Standard Library `.lib` files +## C++ standard library (STL) `.lib` files -| C++ Standard Library | Characteristics | Option | Preprocessor directives | +| C++ standard library | Characteristics | Option | Preprocessor directives | |--|--|--|--| | *`libcpmt.lib`* | Multithreaded, static link | **`/MT`** | `_MT` | | *`msvcprt.lib`* | Multithreaded, dynamic link (import library for *`msvcp.dll`*) | **`/MD`** | `_MT`, `_DLL` | | *`libcpmtd.lib`* | Multithreaded, static link | **`/MTd`** | `_DEBUG`, `_MT` | | *`msvcprtd.lib`* | Multithreaded, dynamic link (import library for *`msvcpd.dll`*) | **`/MDd`** | `_DEBUG`, `_MT`, `_DLL` | -When you build a release version of your project, one of the basic C runtime libraries (*`libcmt.lib`*, *`msvcmrt.lib`*, *`msvcrt.lib`*) is linked by default, depending on the compiler option you choose (multithreaded, DLL, **`/clr`**). If you include one of the [C++ Standard Library header files](../standard-library/cpp-standard-library-header-files.md) in your code, a C++ Standard Library will be linked automatically by Visual C++ at compile time. For example: +When you build a release version of your project, one of the basic C runtime libraries (*`libcmt.lib`*, *`msvcmrt.lib`*, *`msvcrt.lib`*) is linked by default, depending on the compiler option you choose (multithreaded, DLL, **`/clr`**). If you include one of the [C++ standard library header files](../standard-library/cpp-standard-library-header-files.md) in your code, a C++ standard library will be linked automatically by Visual C++ at compile time. For example: ```cpp #include ``` -For binary compatibility, more than one DLL file may be specified by a single import library. Version updates may introduce *dot libraries*, separate DLLs that introduce new library functionality. For example, Visual Studio 2017 version 15.6 introduced *`msvcp140_1.dll`* to support additional standard library functionality without breaking the Application Binary Interface (ABI) supported by *`msvcp140.dll`*. The *`msvcprt.lib`* import library included in the toolset for Visual Studio 2017 version 15.6 supports both DLLs, and the vcredist for this version installs both DLLs. Once shipped, a dot library has a fixed ABI, and will never have a dependency on a later dot library. +For binary compatibility, more than one DLL file may be specified by a single import library. Version updates may introduce *dot libraries*, separate DLLs that introduce new library functionality. For example, Visual Studio 2017 version 15.6 introduced *`msvcp140_1.dll`* to support more standard library functionality without breaking the Application Binary Interface (ABI) supported by *`msvcp140.dll`*. The *`msvcprt.lib`* import library included in the toolset for Visual Studio 2017 version 15.6 supports both DLLs, and the vcredist for this version installs both DLLs. Once shipped, a dot library has a fixed ABI, and will never have a dependency on a later dot library. ## What problems exist if an application uses more than one CRT version? -Every executable image (EXE or DLL) can have its own statically linked CRT, or can dynamically link to a CRT. The version of the CRT statically included in or dynamically loaded by a particular image depends on the version of the tools and libraries it was built with. A single process may load multiple EXE and DLL images, each with its own CRT. Each of those CRTs may use a different allocator, may have different internal structure layouts, and may use different storage arrangements. This means allocated memory, CRT resources, or classes passed across a DLL boundary can cause problems in memory management, internal static usage, or layout interpretation. For example, if a class is allocated in one DLL but passed to and deleted by another, which CRT deallocator is used? The errors caused can range from the subtle to the immediately fatal, and therefore direct transfer of such resources is strongly discouraged. +Every executable image (EXE or DLL) can have its own statically linked CRT, or can dynamically link to a CRT. The version of the CRT statically included in or dynamically loaded by a particular image depends on the version of the tools and libraries it was built with. A single process may load multiple EXE and DLL images, each with its own CRT. Each of those CRTs may use a different allocator, may have different internal structure layouts, and may use different storage arrangements. It means allocated memory, CRT resources, or classes passed across a DLL boundary can cause problems in memory management, internal static usage, or layout interpretation. For example, if a class is allocated in one DLL but passed to and deleted by another, which CRT deallocator is used? The errors caused can range from the subtle to the immediately fatal, and therefore direct transfer of such resources is discouraged. -You can avoid many of these issues by using Application Binary Interface (ABI) technologies instead, as they are designed to be stable and versionable. Design your DLL export interfaces to pass information by value, or to work on memory that is passed in by the caller rather than allocated locally and returned to the caller. Use marshaling techniques to copy structured data between executable images. Encapsulate resources locally and only allow manipulation through handles or functions you expose to clients. +You can avoid many of these issues by using Application Binary Interface (ABI) technologies instead, as they're designed to be stable and versionable. Design your DLL export interfaces to pass information by value, or to work on memory that is passed in by the caller rather than allocated locally and returned to the caller. Use marshaling techniques to copy structured data between executable images. Encapsulate resources locally and only allow manipulation through handles or functions you expose to clients. It's also possible to avoid some of these issues if all of the images in your process use the same dynamically loaded version of the CRT. To ensure that all components use the same DLL version of the CRT, build them by using the **`/MD`** option, and use the same compiler toolset and property settings. -Be careful if your program passes certain CRT resources across DLL boundaries. Resources such as file handles, locales, and environment variables can cause problems, even when using the same version of the CRT. For more information on the issues involved and how to resolve them, see [Potential Errors Passing CRT Objects Across DLL Boundaries](../c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md). +Be careful if your program passes certain CRT resources across DLL boundaries. Resources such as file handles, locales, and environment variables can cause problems, even when using the same version of the CRT. For more information on the issues involved and how to resolve them, see [Potential errors passing CRT objects across DLL boundaries](./potential-errors-passing-crt-objects-across-dll-boundaries.md). ## See also -[C runtime library reference](../c-runtime-library/c-run-time-library-reference.md)\ +[C runtime library reference](./c-run-time-library-reference.md)\ [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md) diff --git a/docs/c-runtime-library/crtdbg-map-alloc.md b/docs/c-runtime-library/crtdbg-map-alloc.md index 106781b49d5..b2b1cfec571 100644 --- a/docs/c-runtime-library/crtdbg-map-alloc.md +++ b/docs/c-runtime-library/crtdbg-map-alloc.md @@ -6,12 +6,12 @@ f1_keywords: ["CRTDBG_MAP_ALLOC", "_CRTDBG_MAP_ALLOC"] helpviewer_keywords: ["_CRTDBG_MAP_ALLOC macro", "memory allocation, in debug builds", "CRTDBG_MAP_ALLOC macro"] ms.assetid: 435242b8-caea-4063-b765-4a608200312b --- -# _CRTDBG_MAP_ALLOC +# `_CRTDBG_MAP_ALLOC` -When the **_CRTDBG_MAP_ALLOC** flag is defined in the debug version of an application, the base version of the heap functions are directly mapped to their debug versions. The flag is used in Crtdbg.h to do the mapping. This flag is only available when the [_DEBUG](../c-runtime-library/debug.md) flag has been defined in the application. +When the `_CRTDBG_MAP_ALLOC` flag is defined in the debug version of an application, the base versions of the heap functions are directly mapped to their debug versions. The flag is used in Crtdbg.h to do the mapping. This flag is only available when the [`_DEBUG`](./debug.md) flag has been defined in the application. -For more information about using the debug version versus the base version of a heap function, see [Using the Debug Version Versus the Base Version](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For more information about using the debug version versus the base version of a heap function, see [Debug versions of heap allocation functions](./debug-versions-of-heap-allocation-functions.md). ## See also -[Control Flags](../c-runtime-library/control-flags.md) +[Control flags](./control-flags.md) diff --git a/docs/c-runtime-library/crtdbgflag.md b/docs/c-runtime-library/crtdbgflag.md index f300ca39ede..6617f29a185 100644 --- a/docs/c-runtime-library/crtdbgflag.md +++ b/docs/c-runtime-library/crtdbgflag.md @@ -2,16 +2,16 @@ description: "Learn more about: _crtDbgFlag" title: "_crtDbgFlag" ms.date: "11/04/2016" -f1_keywords: ["_crtDbgFlag", "crtDbgFlag"] +f1_keywords: ["_crtDbgFlag", "CRTDBG/_crtDbgFlag"] helpviewer_keywords: ["memory allocation, tracking flag", "crtDbgFlag constant", "_crtDbgFlag constant", "debug heap, tracking memory on", "debug heap, control flags", "enable memory allocation tracking flag", "memory, tracking on the debug heap"] ms.assetid: 9e7adb47-8ab9-4e19-81d5-e2f237979973 --- -# _crtDbgFlag +# `_crtDbgFlag` -The **_crtDbgFlag** flag consists of five bit fields that control how memory allocations on the debug version of the heap are tracked, verified, reported, and dumped. The bit fields of the flag are set using the [_CrtSetDbgFlag](../c-runtime-library/reference/crtsetdbgflag.md) function. This flag and its bit fields are declared in Crtdbg.h. This flag is only available when the [_DEBUG](../c-runtime-library/debug.md) flag has been defined in the application. +The **`_crtDbgFlag`** flag consists of five bit-fields that control how memory allocations on the debug version of the heap are tracked, verified, reported, and dumped. The bit fields of the flag are set using the [`_CrtSetDbgFlag`](./reference/crtsetdbgflag.md) function. This flag and its bit fields are declared in Crtdbg.h. This flag is only available when the [`_DEBUG`](./debug.md) flag has been defined in the application. -For more information about using this flag in conjunction with other debug functions, see [Heap State Reporting Functions](/visualstudio/debugger/crt-debug-heap-details). +For more information about using this flag along with other debug functions, see [Heap state reporting functions](./crt-debug-heap-details.md#heap-state-reporting-functions). ## See also -[Control Flags](../c-runtime-library/control-flags.md) +[Control flags](./control-flags.md) diff --git a/docs/c-runtime-library/crtlcmapstringw.md b/docs/c-runtime-library/crtlcmapstringw.md index 1a127c9d1c9..c75880b05f6 100644 --- a/docs/c-runtime-library/crtlcmapstringw.md +++ b/docs/c-runtime-library/crtlcmapstringw.md @@ -10,7 +10,7 @@ f1_keywords: ["__crtLCMapStringW"] helpviewer_keywords: ["__crtLCMapStringW"] ms.assetid: 45b4ac0e-438c-4fa3-b4d1-34195f4467d9 --- -# __crtLCMapStringW +# `__crtLCMapStringW` Maps one character string to another, performing a specified locale-dependent transformation. This function can also be used to generate a sort key for the input string. @@ -28,27 +28,27 @@ int __crtLCMapStringW( #### Parameters -*Locale*
-Locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the `MAKELCID` macro to create a locale identifier. +*`Locale`*\ +The locale identifier. The locale provides a context for the string mapping or sort key generation. An application can use the `MAKELCID` macro to create a locale identifier. -*dwMapFlags*
+*`dwMapFlags`*\ The type of transformation to be used during string mapping or sort key generation. -*lpSrcStr*
+*`lpSrcStr`*\ Pointer to a source string that the function maps or uses for sort key generation. This parameter is assumed to be a Unicode string. -*cchSrc*
+*`cchSrc`*\ Size, in characters, of the string pointed to by the `lpSrcStr` parameter. This count can include the null terminator, or not include it. -A `cchSrc` value of -1 specifies that the string pointed to by `lpSrcStr` is null-terminated. If this is the case, and this function is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into `*lpDestStr`. +A `cchSrc` value of -1 specifies that the string pointed to by `lpSrcStr` is null-terminated. If so, and this function is being used in its string-mapping mode, the function calculates the string's length itself, and null-terminates the mapped string stored into `*lpDestStr`. -*lpDestStr*
+*`lpDestStr`*\ Long pointer to a buffer into which the function stores the mapped string or sort key. -*cchDest*
+*`cchDest`*\ Size, in characters, of the buffer pointed to by `lpDestStr`. -## Return Value +## Return value If the value of `cchDest` is nonzero, the number of characters, or bytes if `LCMAP_SORTKEY` is specified, written to the buffer indicates success. This count includes room for a null terminator. @@ -58,10 +58,10 @@ Zero indicates failure. To get extended error information, call the `GetLastErro ## Remarks -If `cchSrc` is greater than zero and `lpSrcStr` is a null-terminated string, `__crtLCMapStringW` sets `cchSrc` to the length of the string. Then `__crtLCMapStringW` calls the wide string (Unicode) version of the `LCMapString` function with the specified parameters. For more information about the parameters and return value of this function, see the [LCMapString](/windows/win32/api/winnls/nf-winnls-lcmapstringw). +If `cchSrc` is greater than zero and `lpSrcStr` is a null-terminated string, **`__crtLCMapStringW`** sets `cchSrc` to the length of the string. Then **`__crtLCMapStringW`** calls the wide string (Unicode) version of the `LCMapString` function with the specified parameters. For more information about the parameters and return value of this function, see the [`LCMapString`](/windows/win32/api/winnls/nf-winnls-lcmapstringw). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__crtLCMapStringW|awint.h| +| Routine | Required header | +|---|---| +| **`__crtLCMapStringW`** | `` | diff --git a/docs/c-runtime-library/cxxframehandler.md b/docs/c-runtime-library/cxxframehandler.md index 8f6e9df406c..7883ff1adac 100644 --- a/docs/c-runtime-library/cxxframehandler.md +++ b/docs/c-runtime-library/cxxframehandler.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: __CxxFrameHandler" title: "__CxxFrameHandler" -ms.date: "1/14/2021" +description: "Learn more about: __CxxFrameHandler" +ms.date: 1/14/2021 api_name: ["__CxxFrameHandler"] -api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr80.dll", "msvcr100.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__CxxFrameHandler"] helpviewer_keywords: ["__CxxFrameHandler"] -ms.assetid: b79ac97f-425a-42ae-9b91-8beaef935333 --- -# __CxxFrameHandler +# `__CxxFrameHandler` Internal CRT function. Used by the CRT to handle structured exception frames. @@ -22,31 +21,29 @@ EXCEPTION_DISPOSITION __CxxFrameHandler( EHRegistrationNode *pRN, void *pContext, DispatcherContext *pDC - ) + ); ``` #### Parameters -*pExcept*
+*`pExcept`*\ Exception record that is passed to the possible **`catch`** statements. -*pRN*
+*`pRN`*\ Dynamic information about the stack frame that is used to handle the exception. For more information, see ehdata.h. -*pContext*
+*`pContext`*\ Context. (Not used on Intel processors.) -*pDC*
+*`pDC`*\ Additional information about the function entry and stack frame. -## Return Value +## Return value One of the *filter expression* values used by the [try-except Statement](../cpp/try-except-statement.md). -## Remarks - ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__CxxFrameHandler|excpt.h, ehdata.h| +| Routine | Required header | +|---|---| +| **`__CxxFrameHandler`** | ``, `` | diff --git a/docs/c-runtime-library/data-alignment.md b/docs/c-runtime-library/data-alignment.md index 9cb5bfe0ee3..97b03773fba 100644 --- a/docs/c-runtime-library/data-alignment.md +++ b/docs/c-runtime-library/data-alignment.md @@ -1,36 +1,35 @@ --- -description: "Learn more about: Data Alignment" title: "Data Alignment" -ms.date: "11/04/2016" +description: "Learn more about: Data Alignment" +ms.date: 11/04/2016 f1_keywords: ["data.alignment"] helpviewer_keywords: ["data alignment [C++]"] -ms.assetid: 35ac3d2d-a4b3-421b-954f-b7372b1f18e1 --- -# Data Alignment +# Data alignment The following C run-time functions support data alignment. -## Data-Alignment Routines +## Data-alignment routines -|Routine|Use| -|-------------|---------| -|[_aligned_free](../c-runtime-library/reference/aligned-free.md)|Frees a block of memory that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md)or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md).| -|[_aligned_free_dbg](../c-runtime-library/reference/aligned-free-dbg.md)|Frees a block of memory that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) (debug only).| -|[_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md)|Allocates memory on a specified alignment boundary.| -|[_aligned_malloc_dbg](../c-runtime-library/reference/aligned-malloc-dbg.md)|Allocates memory on a specified alignment boundary with additional space for a debugging header and overwrite buffers (debug version only).| -|[_aligned_msize](../c-runtime-library/reference/aligned-msize.md)|Returns the size of a memory block allocated in the heap.| -|[_aligned_msize_dbg](../c-runtime-library/reference/aligned-msize-dbg.md)|Returns the size of a memory block allocated in the heap (debug version only).| -|[_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md)|Allocates memory on a specified alignment boundary.| -|[_aligned_offset_malloc_dbg](../c-runtime-library/reference/aligned-offset-malloc-dbg.md)|Allocates memory on a specified alignment boundary (debug version only).| -|[_aligned_offset_realloc](../c-runtime-library/reference/aligned-offset-realloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md).| -|[_aligned_offset_realloc_dbg](../c-runtime-library/reference/aligned-offset-realloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) (debug version only).| -|[_aligned_offset_recalloc](../c-runtime-library/reference/aligned-offset-recalloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0.| -|[_aligned_offset_recalloc_dbg](../c-runtime-library/reference/aligned-offset-recalloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only).| -|[_aligned_realloc](../c-runtime-library/reference/aligned-realloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md).| -|[_aligned_realloc_dbg](../c-runtime-library/reference/aligned-realloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) (debug version only).| -|[_aligned_recalloc](../c-runtime-library/reference/aligned-recalloc.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0.| -|[_aligned_recalloc_dbg](../c-runtime-library/reference/aligned-recalloc-dbg.md)|Changes the size of a memory block that was allocated with [_aligned_malloc](../c-runtime-library/reference/aligned-malloc.md) or [_aligned_offset_malloc](../c-runtime-library/reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only).| +| Routine | Use | +|---|---| +| [`_aligned_free`](./reference/aligned-free.md) | Frees a block of memory that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md). | +| [`_aligned_free_dbg`](./reference/aligned-free-dbg.md) | Frees a block of memory that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) (debug only). | +| [`_aligned_malloc`](./reference/aligned-malloc.md) | Allocates memory on a specified alignment boundary. | +| [`_aligned_malloc_dbg`](./reference/aligned-malloc-dbg.md) | Allocates memory on a specified alignment boundary with extra space for a debugging header and overwrite buffers (debug version only). | +| [`_aligned_msize`](./reference/aligned-msize.md) | Returns the size of a memory block allocated in the heap. | +| [`_aligned_msize_dbg`](./reference/aligned-msize-dbg.md) | Returns the size of a memory block allocated in the heap (debug version only). | +| [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) | Allocates memory on a specified alignment boundary. | +| [`_aligned_offset_malloc_dbg`](./reference/aligned-offset-malloc-dbg.md) | Allocates memory on a specified alignment boundary (debug version only). | +| [`_aligned_offset_realloc`](./reference/aligned-offset-realloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md). | +| [`_aligned_offset_realloc_dbg`](./reference/aligned-offset-realloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) (debug version only). | +| [`_aligned_offset_recalloc`](./reference/aligned-offset-recalloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0. | +| [`_aligned_offset_recalloc_dbg`](./reference/aligned-offset-recalloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). | +| [`_aligned_realloc`](./reference/aligned-realloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md). | +| [`_aligned_realloc_dbg`](./reference/aligned-realloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) (debug version only). | +| [`_aligned_recalloc`](./reference/aligned-recalloc.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0. | +| [`_aligned_recalloc_dbg`](./reference/aligned-recalloc-dbg.md) | Changes the size of a memory block that was allocated with [`_aligned_malloc`](./reference/aligned-malloc.md) or [`_aligned_offset_malloc`](./reference/aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/data-conversion.md b/docs/c-runtime-library/data-conversion.md index 080128dfe81..5c3c7b5b610 100644 --- a/docs/c-runtime-library/data-conversion.md +++ b/docs/c-runtime-library/data-conversion.md @@ -5,51 +5,51 @@ ms.date: "03/21/2018" f1_keywords: ["c.conversions"] helpviewer_keywords: ["data conversion routines [C++]", "converting data"] --- -# Data Conversion +# Data conversion -These routines convert data from one form to another. Generally these routines execute faster than conversions you might write. Each routine that begins with a *to* prefix is implemented as a function and as a macro. See [Choosing Between Functions and Macros](../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md) for information about choosing an implementation. +These routines convert data from one form to another. Generally these routines execute faster than conversions you might write. Each routine that begins with a `to` prefix is implemented as a function and as a macro. See [Recommendations for choosing between functions and macros](./recommendations-for-choosing-between-functions-and-macros.md) for information about choosing an implementation. ## Data-conversion routines -|Routine|Use| -|-------------|---------| -|[`abs`](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Find absolute value of integer| -|[`atof`, `_atof_l`](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Convert string to **`float`**| -|[`atoi`, `_atoi_l`](../c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md)|Convert string to **`int`**| -|[`_atoi64`, `_atoi64_l`](../c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md)|Convert string to **`__int64`** or **`long long`**| -|[`atol`, `_atol_l`](../c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md)|Convert string to **`long`**| -|[`c16rtomb`, `c32rtomb`](../c-runtime-library/reference/c16rtomb-c32rtomb1.md)|Convert UTF-16 or UTF-32 character to equivalent multibyte character| -|[`_ecvt`](../c-runtime-library/reference/ecvt.md), [`_ecvt_s`](../c-runtime-library/reference/ecvt-s.md)|Convert **`double`** to string of specified length| -|[`_fcvt`](../c-runtime-library/reference/fcvt.md), [`_fcvt_s`](../c-runtime-library/reference/fcvt-s.md)|Convert **`double`** to string with specified number of digits following decimal point| -|[`_gcvt`](../c-runtime-library/reference/gcvt.md), [`_gcvt_s`](../c-runtime-library/reference/gcvt-s.md)|Convert **`double`** number to string; store string in buffer| -|[`_itoa`, `_ltoa`, `_ultoa`, `_i64toa`, `_ui64toa`, `_itow`, `_ltow`, `ultow`, `_i64tow`, `_ui64tow`](../c-runtime-library/reference/itoa-itow.md), [`_itoa_s`, `_ltoa_s`, `_ultoa_s`, `_i64toa_s`, `_ui64toa_s`, `_itow_s`, `_ltow_s`, `_ultow_s`, `_i64tow_s`, `_ui64tow_s`](../c-runtime-library/reference/itoa-s-itow-s.md)|Convert integer types to string| -|[`labs`](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Find absolute value of **`long`** integer| -|[`llabs`](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Find absolute value of **`long long`** integer| -|[`_mbbtombc`, `_mbbtombc_l`](../c-runtime-library/reference/mbbtombc-mbbtombc-l.md)|Convert 1-byte multibyte character to corresponding 2-byte multibyte character| -|[`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](../c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)|Convert Japan Industry Standard (JIS) character to Japan Microsoft (JMS) character| -|[`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](../c-runtime-library/reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md)|Convert JMS character to JIS character| -|[`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](../c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)|Convert multibyte character to 1-byte hiragana code| -|[`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](../c-runtime-library/reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md)|Convert multibyte character to 1-byte katakana code| -|[`_mbctombb`, `_mbctombb_l`](../c-runtime-library/reference/mbctombb-mbctombb-l.md)|Convert 2-byte multibyte character to corresponding 1-byte multibyte character| -|[`mbrtoc16`, `mbrtoc32`](../c-runtime-library/reference/mbrtoc16-mbrtoc323.md)|Convert multibyte character to equivalent UTF-16 or UTF-32 character| -|[`mbstowcs`, `_mbstowcs_l`](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md), [`mbstowcs_s`, `_mbstowcs_s_l`](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert sequence of multibyte characters to corresponding sequence of wide characters| -|[`mbtowc`, `_mbtowc_l`](../c-runtime-library/reference/mbtowc-mbtowc-l.md)|Convert multibyte character to corresponding wide character| -|[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](../c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md)|Convert string to **`double`**| -|[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](../c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md)|Convert string to **`long`** integer| -|[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](../c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md)|Convert string to **`unsigned long`** integer| -|[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)|Transform string into collated form based on locale-specific information| -|[`toascii`, `__toascii`](../c-runtime-library/reference/toascii-toascii.md)|Convert character to ASCII code| -|[`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Test character and convert to lowercase if currently uppercase| -|[`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md)|Convert character to lowercase unconditionally| -|[`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Test character and convert to uppercase if currently lowercase| -|[`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md)|Convert character to uppercase unconditionally| -|[`wcstombs`, `_wcstombs_l`](../c-runtime-library/reference/wcstombs-wcstombs-l.md), [`wcstombs_s`, `_wcstombs_s_l`](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert sequence of wide characters to corresponding sequence of multibyte characters| -|[`wctomb`, `_wctomb_l`](../c-runtime-library/reference/wctomb-wctomb-l.md), [`wctomb_s`, `_wctomb_s_l`](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert wide character to corresponding multibyte character| -|[`_wtof`, `_wtof_l`](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Convert wide-character string to a **`double`**| -|[`_wtoi`, `_wtoi_l`](../c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md)|Convert wide-character string to **`int`**| -|[`_wtoi64`, `_wtoi64_l`](../c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md)|Convert wide-character string to **`__int64`** or **`long long`**| -|[`_wtol`, `_wtol_l`](../c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md)|Convert wide-character string to **`long`**| +| Routine | Use | +|---|---| +| [`abs`](./reference/abs-labs-llabs-abs64.md) | Find absolute value of integer | +| [`atof`, `_atof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Convert string to **`float`** | +| [`atoi`, `_atoi_l`](./reference/atoi-atoi-l-wtoi-wtoi-l.md) | Convert string to **`int`** | +| [`_atoi64`, `_atoi64_l`](./reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md) | Convert string to **`__int64`** or **`long long`** | +| [`atol`, `_atol_l`](./reference/atol-atol-l-wtol-wtol-l.md) | Convert string to **`long`** | +| [`c16rtomb`, `c32rtomb`](./reference/c16rtomb-c32rtomb1.md) | Convert UTF-16 or UTF-32 character to equivalent multibyte character | +| [`_ecvt`](./reference/ecvt.md), [`_ecvt_s`](./reference/ecvt-s.md) | Convert **`double`** to string of specified length | +| [`_fcvt`](./reference/fcvt.md), [`_fcvt_s`](./reference/fcvt-s.md) | Convert **`double`** to string with specified number of digits following decimal point | +| [`_gcvt`](./reference/gcvt.md), [`_gcvt_s`](./reference/gcvt-s.md) | Convert **`double`** number to string; store string in buffer | +| [`_itoa`, `_ltoa`, `_ultoa`, `_i64toa`, `_ui64toa`, `_itow`, `_ltow`, `ultow`, `_i64tow`, `_ui64tow`](./reference/itoa-itow.md), [`_itoa_s`, `_ltoa_s`, `_ultoa_s`, `_i64toa_s`, `_ui64toa_s`, `_itow_s`, `_ltow_s`, `_ultow_s`, `_i64tow_s`, `_ui64tow_s`](./reference/itoa-s-itow-s.md) | Convert integer types to string | +| [`labs`](./reference/abs-labs-llabs-abs64.md) | Find absolute value of **`long`** integer | +| [`llabs`](./reference/abs-labs-llabs-abs64.md) | Find absolute value of **`long long`** integer | +| [`_mbbtombc`, `_mbbtombc_l`](./reference/mbbtombc-mbbtombc-l.md) | Convert 1-byte multibyte character to corresponding 2-byte multibyte character | +| [`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](./reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md) | Convert Japan Industry Standard (JIS) character to Japan Microsoft (JMS) character | +| [`_mbcjistojms`, `_mbcjistojms_l`, `_mbcjmstojis`, `_mbcjmstojis_l`](./reference/mbcjistojms-mbcjistojms-l-mbcjmstojis-mbcjmstojis-l.md) | Convert JMS character to JIS character | +| [`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](./reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md) | Convert multibyte character to 1-byte hiragana code | +| [`_mbctohira`, `_mbctohira_l`, `_mbctokata`, `_mbctokata_l`](./reference/mbctohira-mbctohira-l-mbctokata-mbctokata-l.md) | Convert multibyte character to 1-byte katakana code | +| [`_mbctombb`, `_mbctombb_l`](./reference/mbctombb-mbctombb-l.md) | Convert 2-byte multibyte character to corresponding 1-byte multibyte character | +| [`mbrtoc16`, `mbrtoc32`](./reference/mbrtoc16-mbrtoc323.md) | Convert multibyte character to equivalent UTF-16 or UTF-32 character | +| [`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md), [`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) | Convert sequence of multibyte characters to corresponding sequence of wide characters | +| [`mbtowc`, `_mbtowc_l`](./reference/mbtowc-mbtowc-l.md) | Convert multibyte character to corresponding wide character | +| [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](./reference/strtod-strtod-l-wcstod-wcstod-l.md) | Convert string to **`double`** | +| [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](./reference/strtol-wcstol-strtol-l-wcstol-l.md) | Convert string to **`long`** integer | +| [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](./reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md) | Convert string to **`unsigned long`** integer | +| [`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](./reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) | Transform string into collated form based on locale-specific information | +| [`toascii`, `__toascii`](./reference/toascii-toascii.md) | Convert character to ASCII code | +| [`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](./reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Test character and convert to lowercase if currently uppercase | +| [`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md) | Convert character to lowercase unconditionally | +| [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](./reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Test character and convert to uppercase if currently lowercase | +| [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md) | Convert character to uppercase unconditionally | +| [`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md), [`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) | Convert sequence of wide characters to corresponding sequence of multibyte characters | +| [`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md), [`wctomb_s`, `_wctomb_s_l`](./reference/wctomb-s-wctomb-s-l.md) | Convert wide character to corresponding multibyte character | +| [`_wtof`, `_wtof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Convert wide-character string to a **`double`** | +| [`_wtoi`, `_wtoi_l`](./reference/atoi-atoi-l-wtoi-wtoi-l.md) | Convert wide-character string to **`int`** | +| [`_wtoi64`, `_wtoi64_l`](./reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md) | Convert wide-character string to **`__int64`** or **`long long`** | +| [`_wtol`, `_wtol_l`](./reference/atol-atol-l-wtol-wtol-l.md) | Convert wide-character string to **`long`** | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/data-type-constants.md b/docs/c-runtime-library/data-type-constants.md index e69c292b9bb..1c631e5b87e 100644 --- a/docs/c-runtime-library/data-type-constants.md +++ b/docs/c-runtime-library/data-type-constants.md @@ -2,10 +2,10 @@ description: "Learn more about: Data Type Constants" title: "Data Type Constants" ms.date: "06/25/2018" -f1_keywords: ["FLT_MIN", "SHRT_MAX", "CHAR_MIN", "MB_LEN_MAX", "DBL_EPSILON", "SHRT_MIN", "_FLT_RADIX", "FLT_DIG", "FLT_MAX_10_EXP", "FLT_MANT_DIG", "DBL_MAX_EXP", "SCHAR_MIN", "SCHAR_MAX", "DBL_MIN", "FLT_MIN_10_EXP", "_DBL_ROUNDS", "USHRT_MAX", "FLT_MAX_EXP", "LONG_MAX", "DBL_MAX", "DBL_DIG", "FLT_MIN_EXP", "INT_MIN", "DBL_MIN_10_EXP", "CHAR_BIT", "INT_MAX", "ULONG_MAX", "DBL_MIN_EXP", "LONG_MIN", "_FLT_ROUNDS", "DBL_MANT_DIG", "_DBL_RADIX", "CHAR_MAX", "FLT_MAX", "DBL_MAX_10_EXP", "UCHAR_MAX", "FLT_EPSILON", "UINT_MAX", "LLONG_MIN", "LLONG_MAX", "ULLONG_MAX", "_I8_MIN", "_I8_MAX", "_UI8_MAX", "_I16_MIN", "_I16_MAX", "_UI16_MAX", "_I32_MIN", "_I32_MAX", "_UI32_MAX", "_I64_MIN", "_I64_MAX", "_UI64_MAX", "_I128_MIN", "_I128_MAX", "_UI128_MAX", "SIZE_MAX", "RSIZE_MAX", "LDBL_DIG", "LDBL_EPSILON", "LDBL_HAS_SUBNORM", "LDBL_MANT_DIG", "LDBL_MAX", "LDBL_MAX_10_EXP", "LDBL_MAX_EXP", "LDBL_MIN", "LDBL_MIN_10_EXP", "LDBL_MIN_EXP", "_LDBL_RADIX", "LDBL_TRUE_MIN", "DECIMAL_DIG"] +f1_keywords: ["CHAR_BIT", "SCHAR_MIN", "SCHAR_MAX", "UCHAR_MAX", "CHAR_MIN", "CHAR_MAX", "MB_LEN_MAX", "SHRT_MIN", "SHRT_MAX", "USHRT_MAX", "INT_MIN", "INT_MAX", "UINT_MAX", "LONG_MIN", "LONG_MAX", "ULONG_MAX", "LLONG_MIN", "LLONG_MAX", "ULLONG_MAX", "_I8_MIN", "_I8_MAX", "_UI8_MAX", "_I16_MIN", "_I16_MAX", "_UI16_MAX", "_I32_MIN", "_I32_MAX", "_UI32_MAX", "_I64_MIN", "_I64_MAX", "_UI64_MAX", "_I128_MIN", "_I128_MAX", "_UI128_MAX", "SIZE_MAX", "RSIZE_MAX", "LIMITS/CHAR_BIT", "LIMITS/SCHAR_MIN", "LIMITS/SCHAR_MAX", "LIMITS/UCHAR_MAX", "LIMITS/CHAR_MIN", "LIMITS/CHAR_MAX", "LIMITS/MB_LEN_MAX", "LIMITS/SHRT_MIN", "LIMITS/SHRT_MAX", "LIMITS/USHRT_MAX", "LIMITS/INT_MIN", "LIMITS/INT_MAX", "LIMITS/UINT_MAX", "LIMITS/LONG_MIN", "LIMITS/LONG_MAX", "LIMITS/ULONG_MAX", "LIMITS/LLONG_MIN", "LIMITS/LLONG_MAX", "LIMITS/ULLONG_MAX", "LIMITS/_I8_MIN", "LIMITS/_I8_MAX", "LIMITS/_UI8_MAX", "LIMITS/_I16_MIN", "LIMITS/_I16_MAX", "LIMITS/_UI16_MAX", "LIMITS/_I32_MIN", "LIMITS/_I32_MAX", "LIMITS/_UI32_MAX", "LIMITS/_I64_MIN", "LIMITS/_I64_MAX", "LIMITS/_UI64_MAX", "LIMITS/_I128_MIN", "LIMITS/_I128_MAX", "LIMITS/_UI128_MAX", "LIMITS/SIZE_MAX", "LIMITS/RSIZE_MAX", "DBL_DECIMAL_DIG", "DBL_DIG", "DBL_EPSILON", "DBL_HAS_SUBNORM", "DBL_MANT_DIG", "DBL_MAX", "DBL_MAX_10_EXP", "DBL_MAX_EXP", "DBL_MIN", "DBL_MIN_10_EXP", "DBL_MIN_EXP", "_DBL_RADIX", "DBL_TRUE_MIN", "FLT_DECIMAL_DIG", "FLT_DIG", "FLT_EPSILON", "FLT_HAS_SUBNORM", "FLT_MANT_DIG", "FLT_MAX", "FLT_MAX_10_EXP", "FLT_MAX_EXP", "FLT_MIN", "FLT_MIN_10_EXP", "FLT_MIN_EXP", "FLT_RADIX", "FLT_TRUE_MIN", "LDBL_DIG", "LDBL_EPSILON", "LDBL_HAS_SUBNORM", "LDBL_MANT_DIG", "LDBL_MAX", "LDBL_MAX_10_EXP", "LDBL_MAX_EXP", "LDBL_MIN", "LDBL_MIN_10_EXP", "LDBL_MIN_EXP", "_LDBL_RADIX", "LDBL_TRUE_MIN", "DECIMAL_DIG", "FLOAT/DBL_DECIMAL_DIG", "FLOAT/DBL_DIG", "FLOAT/DBL_EPSILON", "FLOAT/DBL_HAS_SUBNORM", "FLOAT/DBL_MANT_DIG", "FLOAT/DBL_MAX", "FLOAT/DBL_MAX_10_EXP", "FLOAT/DBL_MAX_EXP", "FLOAT/DBL_MIN", "FLOAT/DBL_MIN_10_EXP", "FLOAT/DBL_MIN_EXP", "FLOAT/_DBL_RADIX", "FLOAT/DBL_TRUE_MIN", "FLOAT/FLT_DECIMAL_DIG", "FLOAT/FLT_DIG", "FLOAT/FLT_EPSILON", "FLOAT/FLT_HAS_SUBNORM", "FLOAT/FLT_MANT_DIG", "FLOAT/FLT_MAX", "FLOAT/FLT_MAX_10_EXP", "FLOAT/FLT_MAX_EXP", "FLOAT/FLT_MIN", "FLOAT/FLT_MIN_10_EXP", "FLOAT/FLT_MIN_EXP", "FLOAT/FLT_RADIX", "FLOAT/FLT_TRUE_MIN", "FLOAT/LDBL_DIG", "FLOAT/LDBL_EPSILON", "FLOAT/LDBL_HAS_SUBNORM", "FLOAT/LDBL_MANT_DIG", "FLOAT/LDBL_MAX", "FLOAT/LDBL_MAX_10_EXP", "FLOAT/LDBL_MAX_EXP", "FLOAT/LDBL_MIN", "FLOAT/LDBL_MIN_10_EXP", "FLOAT/LDBL_MIN_EXP", "FLOAT/_LDBL_RADIX", "FLOAT/LDBL_TRUE_MIN", "FLOAT/DECIMAL_DIG"] helpviewer_keywords: ["DBL_MAX_EXP constant", "_DBL_RADIX constant", "FLT_MIN_EXP constant", "DBL_EPSILON constant", "INT_MIN constant", "FLT_EPSILON constant", "DBL_MANT_DIG constant", "_FLT_RADIX constant", "DBL_MIN constant", "USHRT_MAX constant", "FLT_MAX_10_EXP constant", "_FLT_ROUNDS constant", "data type constants [C++]", "_DBL_ROUNDS constant", "CHAR_MAX constant", "FLT_MAX_EXP constant", "FLT_MIN constant", "CHAR_MIN constant", "FLT_MIN_10_EXP constant", "DBL_MIN_EXP constant", "SCHAR_MAX constant", "FLT_RADIX constant", "CHAR_BIT constant", "UCHAR_MAX constant", "DBL_RADIX constant", "FLT_ROUNDS constant", "LONG_MIN constant", "SHRT_MAX constant", "LONG_MAX constant", "DBL_MAX_10_EXP constant", "DBL_MIN_10_EXP constant", "INT_MAX constant", "constants [C++], data type", "ULONG_MAX constant", "FLT_DIG constant", "MB_LEN_MAX constant", "DBL_DIG constant", "SHRT_MIN constant", "DBL_MAX constant", "DBL_ROUNDS constant", "FLT_MAX constant", "UINT_MAX constant", "FLT_MANT_DIG constant", "SCHAR_MIN constant", "LLONG_MIN constant", "LLONG_MAX constant", "ULLONG_MAX constant", "_I8_MIN constant", "_I8_MAX constant", "_UI8_MAX constant", "_I16_MIN constant", "_I16_MAX constant", "_UI16_MAX constant", "_I32_MIN constant", "_I32_MAX constant", "_UI32_MAX constant", "_I64_MIN constant", "_I64_MAX constant", "_UI64_MAX constant", "_I128_MIN constant", "_I128_MAX constant", "_UI128_MAX constant", "SIZE_MAX constant", "RSIZE_MAX constant"] --- -# Data Type Constants +# Data type constants Data type constants are implementation-dependent ranges of values allowed for integral and floating-point data types. @@ -20,44 +20,44 @@ These constants give the ranges for the integral data types. To use these consta > [!NOTE] > The [`/J`](../build/reference/j-default-char-type-is-unsigned.md) compiler option changes the default **`char`** type from **`signed char`** to **`unsigned char`**. -|Constant|Value|Description| -|--------------|-----------|-------------| -|**`CHAR_BIT`**|8|Number of bits in a **`char`**| -|**`SCHAR_MIN`**|(-128)|Minimum **`signed char`** value| -|**`SCHAR_MAX`**|127|Maximum **`signed char`** value| -|**`UCHAR_MAX`**|255 (0xff)|Maximum **`unsigned char`** value| -|**`CHAR_MIN`**|(-128) (0 if **`/J`** option used)|Minimum **`char`** value| -|**`CHAR_MAX`**|127 (255 if **`/J`** option used)|Maximum **`char`** value| -|**`MB_LEN_MAX`**|5|Maximum number of bytes in multibyte **`char`**| -|**`SHRT_MIN`**|-32768|Minimum **`signed short`** value| -|**`SHRT_MAX`**|32767|Maximum **`signed short`** value| -|**`USHRT_MAX`**|65535 (0xffff)|Maximum **`unsigned short`** value| -|**`INT_MIN`**|(-2147483647 - 1)|Minimum **`signed int`** value| -|**`INT_MAX`**|2147483647|Maximum **`signed int`** value| -|**`UINT_MAX`**|4294967295 (0xffffffff)|Maximum **`unsigned int`** value| -|**`LONG_MIN`**|(-2147483647L - 1)|Minimum **`signed long`** value| -|**`LONG_MAX`**|2147483647L|Maximum **`signed long`** value| -|**`ULONG_MAX`**|4294967295UL (0xfffffffful)|Maximum **`unsigned long`** value| -|**`LLONG_MIN`**|(-9223372036854775807LL - 1)|Minimum **`signed long long`** or **`__int64`** value| -|**`LLONG_MAX`**|9223372036854775807LL|Maximum **`signed long long`** or **`__int64`** value| -|**`ULLONG_MAX`**|0xffffffffffffffffull|Maximum **`unsigned long long`** value| -|**`_I8_MIN`**|(-127i8 - 1)|Minimum signed 8-bit value| -|**`_I8_MAX`**|127i8|Maximum signed 8-bit value| -|**`_UI8_MAX`**|0xffui8|Maximum unsigned 8-bit value| -|**`_I16_MIN`**|(-32767i16 - 1)|Minimum signed 16-bit value| -|**`_I16_MAX`**|32767i16|Maximum signed 16-bit value| -|**`_UI16_MAX`**|0xffffui16|Maximum unsigned 16-bit value| -|**`_I32_MIN`**|(-2147483647i32 - 1)|Minimum signed 32-bit value| -|**`_I32_MAX`**|2147483647i32|Maximum signed 32-bit value| -|**`_UI32_MAX`**|0xffffffffui32|Maximum unsigned 32-bit value| -|**`_I64_MIN`**|(-9223372036854775807 - 1)|Minimum signed 64-bit value| -|**`_I64_MAX`**|9223372036854775807|Maximum signed 64-bit value| -|**`_UI64_MAX`**|0xffffffffffffffffui64|Maximum unsigned 64-bit value| -|**`_I128_MIN`**|(-170141183460469231731687303715884105727i128 - 1)|Minimum signed 128-bit value| -|**`_I128_MAX`**|170141183460469231731687303715884105727i128|Maximum signed 128-bit value| -|**`_UI128_MAX`**|0xffffffffffffffffffffffffffffffffui128|Maximum unsigned 128-bit value| -|**`SIZE_MAX`**|same as **`_UI64_MAX`** if **`_WIN64`** is defined, or **`UINT_MAX`**|Maximum native integer size| -|**`RSIZE_MAX`**|same as (**`SIZE_MAX`** >> 1)|Maximum secure library integer size| +| Constant | Value | Description | +|---|---|---| +| `CHAR_BIT` | 8 | Number of bits in a **`char`** | +| `SCHAR_MIN` | (-128) | Minimum **`signed char`** value | +| `SCHAR_MAX` | 127 | Maximum **`signed char`** value | +| `UCHAR_MAX` | 255 (0xff) | Maximum **`unsigned char`** value | +| `CHAR_MIN` | (-128) (0 if **`/J`** option used) | Minimum **`char`** value | +| `CHAR_MAX` | 127 (255 if **`/J`** option used) | Maximum **`char`** value | +| `MB_LEN_MAX` | 5 | Maximum number of bytes in multibyte **`char`** | +| `SHRT_MIN` | -32768 | Minimum **`signed short`** value | +| `SHRT_MAX` | 32767 | Maximum **`signed short`** value | +| `USHRT_MAX` | 65535 (0xffff) | Maximum **`unsigned short`** value | +| `INT_MIN` | (-2147483647 - 1) | Minimum **`signed int`** value | +| `INT_MAX` | 2147483647 | Maximum **`signed int`** value | +| `UINT_MAX` | 4294967295 (0xffffffff) | Maximum **`unsigned int`** value | +| `LONG_MIN` | (-2147483647L - 1) | Minimum **`signed long`** value | +| `LONG_MAX` | 2147483647L | Maximum **`signed long`** value | +| `ULONG_MAX` | 4294967295UL (0xfffffffful) | Maximum **`unsigned long`** value | +| `LLONG_MIN` | (-9223372036854775807LL - 1) | Minimum **`signed long long`** or **`__int64`** value | +| `LLONG_MAX` | 9223372036854775807LL | Maximum **`signed long long`** or **`__int64`** value | +| `ULLONG_MAX` | 0xffffffffffffffffull | Maximum **`unsigned long long`** value | +| `_I8_MIN` | (-127i8 - 1) | Minimum signed 8-bit value | +| `_I8_MAX` | 127i8 | Maximum signed 8-bit value | +| `_UI8_MAX` | 0xffui8 | Maximum unsigned 8-bit value | +| `_I16_MIN` | (-32767i16 - 1) | Minimum signed 16-bit value | +| `_I16_MAX` | 32767i16 | Maximum signed 16-bit value | +| `_UI16_MAX` | 0xffffui16 | Maximum unsigned 16-bit value | +| `_I32_MIN` | (-2147483647i32 - 1) | Minimum signed 32-bit value | +| `_I32_MAX` | 2147483647i32 | Maximum signed 32-bit value | +| `_UI32_MAX` | 0xffffffffui32 | Maximum unsigned 32-bit value | +| `_I64_MIN` | (-9223372036854775807 - 1) | Minimum signed 64-bit value | +| `_I64_MAX` | 9223372036854775807 | Maximum signed 64-bit value | +| `_UI64_MAX` | 0xffffffffffffffffui64 | Maximum unsigned 64-bit value | +| `_I128_MIN` | (-170141183460469231731687303715884105727i128 - 1) | Minimum signed 128-bit value | +| `_I128_MAX` | 170141183460469231731687303715884105727i128 | Maximum signed 128-bit value | +| `_UI128_MAX` | 0xffffffffffffffffffffffffffffffffui128 | Maximum unsigned 128-bit value | +| `SIZE_MAX` | same as `_UI64_MAX` if `_WIN64` is defined, or `UINT_MAX` | Maximum native integer size | +| `RSIZE_MAX` | same as (`SIZE_MAX` >> 1) | Maximum secure library integer size | ## Floating-point type constants @@ -67,48 +67,48 @@ The following constants give the range and other characteristics of the **`long #include ``` -|Constant|Value|Description| -|--------------|-----------|-----------------| -|**`DBL_DECIMAL_DIG`**|17|# of decimal digits of rounding precision| -|**`DBL_DIG`**|15|# of decimal digits of precision| -|**`DBL_EPSILON`**|2.2204460492503131e-016|Smallest such that 1.0 + **`DBL_EPSILON`** != 1.0| -|**`DBL_HAS_SUBNORM`**|1|Type supports subnormal (denormal) numbers| -|**`DBL_MANT_DIG`**|53|# of bits in significand (mantissa)| -|**`DBL_MAX`**|1.7976931348623158e+308|Maximum value| -|**`DBL_MAX_10_EXP`**|308|Maximum decimal exponent| -|**`DBL_MAX_EXP`**|1024|Maximum binary exponent| -|**`DBL_MIN`**|2.2250738585072014e-308|Minimum normalized positive value| -|**`DBL_MIN_10_EXP`**|(-307)|Minimum decimal exponent| -|**`DBL_MIN_EXP`**|(-1021)|Minimum binary exponent| -|**`_DBL_RADIX`**|2|Exponent radix| -|**`DBL_TRUE_MIN`**|4.9406564584124654e-324|Minimum positive subnormal value| -|**`FLT_DECIMAL_DIG`**|9|Number of decimal digits of rounding precision| -|**`FLT_DIG`**|6|Number of decimal digits of precision| -|**`FLT_EPSILON`**|1.192092896e-07F|Smallest such that 1.0 + **`FLT_EPSILON`** != 1.0| -|**`FLT_HAS_SUBNORM`**|1|Type supports subnormal (denormal) numbers| -|**`FLT_MANT_DIG`**|24|Number of bits in significand (mantissa)| -|**`FLT_MAX`**|3.402823466e+38F|Maximum value| -|**`FLT_MAX_10_EXP`**|38|Maximum decimal exponent| -|**`FLT_MAX_EXP`**|128|Maximum binary exponent| -|**`FLT_MIN`**|1.175494351e-38F|Minimum normalized positive value| -|**`FLT_MIN_10_EXP`**|(-37)|Minimum decimal exponent| -|**`FLT_MIN_EXP`**|(-125)|Minimum binary exponent| -|**`FLT_RADIX`**|2|Exponent radix| -|**`FLT_TRUE_MIN`**|1.401298464e-45F|Minimum positive subnormal value| -|**`LDBL_DIG`**|15|# of decimal digits of precision| -|**`LDBL_EPSILON`**|2.2204460492503131e-016|Smallest such that 1.0 + **`LDBL_EPSILON`** != 1.0| -|**`LDBL_HAS_SUBNORM`**|1|Type supports subnormal (denormal) numbers| -|**`LDBL_MANT_DIG`**|53|# of bits in significand (mantissa)| -|**`LDBL_MAX`**|1.7976931348623158e+308|Maximum value| -|**`LDBL_MAX_10_EXP`**|308|Maximum decimal exponent| -|**`LDBL_MAX_EXP`**|1024|Maximum binary exponent| -|**`LDBL_MIN`**|2.2250738585072014e-308|Minimum normalized positive value| -|**`LDBL_MIN_10_EXP`**|(-307)|Minimum decimal exponent| -|**`LDBL_MIN_EXP`**|(-1021)|Minimum binary exponent| -|**`_LDBL_RADIX`**|2|Exponent radix| -|**`LDBL_TRUE_MIN`**|4.9406564584124654e-324|Minimum positive subnormal value| -|**`DECIMAL_DIG`**|same as **`DBL_DECIMAL_DIG`**|Default (double) decimal digits of rounding precision| +| Constant | Value | Description | +|---|---|---| +| `DBL_DECIMAL_DIG` | 17 | # of decimal digits of rounding precision | +| `DBL_DIG` | 15 | # of decimal digits of precision | +| `DBL_EPSILON` | 2.2204460492503131e-016 | Smallest such that 1.0 + `DBL_EPSILON` != 1.0 | +| `DBL_HAS_SUBNORM` | 1 | Type supports subnormal (denormal) numbers | +| `DBL_MANT_DIG` | 53 | # of bits in significand (mantissa) | +| `DBL_MAX` | 1.7976931348623158e+308 | Maximum value | +| `DBL_MAX_10_EXP` | 308 | Maximum decimal exponent | +| `DBL_MAX_EXP` | 1024 | Maximum binary exponent | +| `DBL_MIN` | 2.2250738585072014e-308 | Minimum normalized positive value | +| `DBL_MIN_10_EXP` | (-307) | Minimum decimal exponent | +| `DBL_MIN_EXP` | (-1021) | Minimum binary exponent | +| `_DBL_RADIX` | 2 | Exponent radix | +| `DBL_TRUE_MIN` | 4.9406564584124654e-324 | Minimum positive subnormal value | +| `FLT_DECIMAL_DIG` | 9 | Number of decimal digits of rounding precision | +| `FLT_DIG` | 6 | Number of decimal digits of precision | +| `FLT_EPSILON` | 1.192092896e-07F | Smallest such that 1.0 + `FLT_EPSILON` != 1.0 | +| `FLT_HAS_SUBNORM` | 1 | Type supports subnormal (denormal) numbers | +| `FLT_MANT_DIG` | 24 | Number of bits in significand (mantissa) | +| `FLT_MAX` | 3.402823466e+38F | Maximum value | +| `FLT_MAX_10_EXP` | 38 | Maximum decimal exponent | +| `FLT_MAX_EXP` | 128 | Maximum binary exponent | +| `FLT_MIN` | 1.175494351e-38F | Minimum normalized positive value | +| `FLT_MIN_10_EXP` | (-37) | Minimum decimal exponent | +| `FLT_MIN_EXP` | (-125) | Minimum binary exponent | +| `FLT_RADIX` | 2 | Exponent radix | +| `FLT_TRUE_MIN` | 1.401298464e-45F | Minimum positive subnormal value | +| `LDBL_DIG` | 15 | # of decimal digits of precision | +| `LDBL_EPSILON` | 2.2204460492503131e-016 | Smallest such that 1.0 + `LDBL_EPSILON` != 1.0 | +| `LDBL_HAS_SUBNORM` | 1 | Type supports subnormal (denormal) numbers | +| `LDBL_MANT_DIG` | 53 | # of bits in significand (mantissa) | +| `LDBL_MAX` | 1.7976931348623158e+308 | Maximum value | +| `LDBL_MAX_10_EXP` | 308 | Maximum decimal exponent | +| `LDBL_MAX_EXP` | 1024 | Maximum binary exponent | +| `LDBL_MIN` | 2.2250738585072014e-308 | Minimum normalized positive value | +| `LDBL_MIN_10_EXP` | (-307) | Minimum decimal exponent | +| `LDBL_MIN_EXP` | (-1021) | Minimum binary exponent | +| `_LDBL_RADIX` | 2 | Exponent radix | +| `LDBL_TRUE_MIN` | 4.9406564584124654e-324 | Minimum positive subnormal value | +| `DECIMAL_DIG` | same as `DBL_DECIMAL_DIG` | Default (double) decimal digits of rounding precision | ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/data-type-mappings.md b/docs/c-runtime-library/data-type-mappings.md index aa0d1a52f0b..3ae69e97e5c 100644 --- a/docs/c-runtime-library/data-type-mappings.md +++ b/docs/c-runtime-library/data-type-mappings.md @@ -2,34 +2,34 @@ description: "Learn more about: Data Type Mappings" title: "Data Type Mappings" ms.date: "11/04/2016" -f1_keywords: ["_TXCHAR", "_TUCHAR", "_TINT", "_TSCHAR", "_TCHAR", "TCHAR::H", "TCHAR", "_T", "_TEXT"] +f1_keywords: ["_TXCHAR", "_TUCHAR", "_TINT", "_TSCHAR", "_TCHAR", "TCHAR", "_T", "_TEXT"] helpviewer_keywords: ["_TXCHAR type", "TINT type", "_TCHAR type", "TSCHAR type", "TEXT type", "TCHAR type", "TCHAR.H data types, mappings defined in", "generic-text data types", "_TINT type", "TUCHAR type", "TXCHAR type", "_TSCHAR type", "T type", "_TUCHAR type", "_TEXT type", "_T type"] ms.assetid: 4e573c05-8800-468b-ae5f-76ff7409835e --- -# Data Type Mappings +# Data type mappings These data-type mappings are defined in TCHAR.H and depend on whether the constant `_UNICODE` or `_MBCS` has been defined in your program. For related information, see [Using TCHAR.H Data Types with _MBCS Code](../text/using-tchar-h-data-types-with-mbcs-code.md). -### Generic-Text Data Type Mappings +### Generic-text data type mappings -|Generic-text

data type name|SBCS (_UNICODE,

_MBCS not

defined)|_MBCS

defined|_UNICODE

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

data type name | SBCS (_UNICODE,

_MBCS not

defined) | _MBCS

defined | _UNICODE

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

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

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

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

The error can also occur in an attempt to rename a file or directory or to remove an existing directory. | 13 | +| `EAGAIN` | No more processes or not enough memory or maximum nesting level reached. An attempt to create a new process failed because there are no more process slots, or there isn't enough memory, or the maximum nesting level has been reached. | 11 | +| `EBADF` | Bad file number. There are two possible causes: 1) The specified file descriptor isn't a valid value or doesn't refer to an open file. 2) An attempt was made to write to a file or device opened for read-only access. | 9 | | `EBUSY` | Device or resource busy. | 16 | | `ECHILD` | No spawned processes. | 10 | | `EDEADLK` | Resource deadlock would occur. | 36 | | `EDEADLOCK` | Same as `EDEADLK` for compatibility with older Microsoft C versions. | 36 | -| `EDOM` | Math argument. The argument to a math function is not in the domain of the function. | 33 | -| `EEXIST` | Files exists. An attempt has been made to create a file that already exists. For example, the `_O_CREAT` and `_O_EXCL` flags are specified in an `_open` call, but the named file already exists. | 17 | +| `EDOM` | Math argument. The argument to a math function isn't in the domain of the function. | 33 | +| `EEXIST` | File exists. An attempt has been made to create a file that already exists. For example, the `_O_CREAT` and `_O_EXCL` flags are specified in an `_open` call, but the named file already exists. | 17 | | `EFAULT` | Bad address. | 14 | | `EFBIG` | File too large. | 27 | | `EILSEQ` | Illegal sequence of bytes (for example, in an `MBCS` string). | 42 | | `EINTR` | Interrupted function. | 4 | -| `EINVAL` | Invalid argument. An invalid value was given for one of the arguments to a function. For example, the value given for the origin when positioning a file pointer (by means of a call to `fseek`) is before the beginning of the file. | 22 | +| `EINVAL` | Invalid argument. An invalid value was given for one of the arguments to a function. For example, the value given for the origin when positioning a file pointer (by a call to `fseek`) is before the beginning of the file. | 22 | | `EIO` | I/O error. | 5 | | `EISDIR` | Is a directory. | 21 | | `EMFILE` | Too many open files. No more file descriptors are available, so no more files can be opened. | 24 | @@ -47,10 +47,10 @@ The following **`errno`** values are supported: | `ENAMETOOLONG` | Filename too long. | 38 | | `ENFILE` | Too many files open in system. | 23 | | `ENODEV` | No such device. | 19 | -| `ENOENT` | No such file or directory. The specified file or directory does not exist or cannot be found. This message can occur whenever a specified file does not exist or a component of a path does not specify an existing directory. | 2 | -| `ENOEXEC` | Exec format error. An attempt was made to execute a file that is not executable or that has an invalid executable-file format. | 8 | +| `ENOENT` | No such file or directory. The specified file or directory doesn't exist or can't be found. This message can occur whenever a specified file doesn't exist or a component of a path doesn't specify an existing directory. | 2 | +| `ENOEXEC` | Exec format error. An attempt was made to execute a file that isn't executable or that has an invalid executable-file format. | 8 | | `ENOLCK` | No locks available. | 39 | -| `ENOMEM` | Not enough memory is available for the attempted operator. For example, this message can occur when insufficient memory is available to execute a child process, or when the allocation request in a `_getcwd` call cannot be satisfied. | 12 | +| `ENOMEM` | Not enough memory is available for the attempted operation. For example, this message can occur when insufficient memory is available to execute a child process, or when the allocation request in a `_getcwd` call can't be satisfied. | 12 | | `ENOSPC` | No space left on device. No more space for writing is available on the device (for example, when the disk is full). | 28 | | `ENOSYS` | Function not supported. | 40 | | `ENOTDIR` | Not a directory. | 20 | @@ -60,11 +60,11 @@ The following **`errno`** values are supported: | `EPERM` | Operation not permitted. | 1 | | `EPIPE` | Broken pipe. | 32 | | `ERANGE` | Result too large. An argument to a math function is too large, resulting in partial or total loss of significance in the result. This error can also occur in other functions when an argument is larger than expected (for example, when the *`buffer`* argument to `_getcwd` is longer than expected). | 34 | -| `EROFS` | Read only file system. | 30 | +| `EROFS` | Read-only file system. | 30 | | `ESPIPE` | Invalid seek. | 29 | | `ESRCH` | No such process. | 3 | | `EXDEV` | Cross-device link. An attempt was made to move a file to a different device (using the `rename` function). | 18 | -| `STRUNCATE` | A string copy or concatenation resulted in a truncated string. See [`_TRUNCATE`](../c-runtime-library/truncate.md). | 80 | +| `STRUNCATE` | A string copy or concatenation resulted in a truncated string. See [`_TRUNCATE`](truncate.md). | 80 | The following values are supported for compatibility with POSIX: @@ -84,8 +84,8 @@ The following values are supported for compatibility with POSIX: | `EIDRM` | Identifier removed. | 111 | | `EINPROGRESS` | Operation in progress. | 112 | | `EISCONN` | Already connected. | 113 | -| `ELOOP` | Too many symbolic link levels. | 114 | -| `EMSGSIZE` | Message size. | 115 | +| `ELOOP` | Too many levels of symbolic links. | 114 | +| `EMSGSIZE` | Message too long. | 115 | | `ENETDOWN` | Network down. | 116 | | `ENETRESET` | Network reset. | 117 | | `ENETUNREACH` | Network unreachable. | 118 | @@ -114,4 +114,4 @@ The following values are supported for compatibility with POSIX: ## See also -[Global constants](../c-runtime-library/global-constants.md) +[Global constants](global-constants.md) diff --git a/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md b/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md index fa0c677d3f8..e614373d8ca 100644 --- a/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md +++ b/docs/c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md @@ -2,11 +2,7 @@ description: "Learn more about: errno, _doserrno, _sys_errlist, and _sys_nerr" title: "errno, _doserrno, _sys_errlist, and _sys_nerr" ms.date: "11/04/2016" -api_name: ["_errno"] -api_location: ["msvcrt.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["_sys_errlist", "errno", "_sys_nerr", "_doserrno"] +f1_keywords: ["errno", "ERRNO/errno", "_doserrno", "ERRNO/_doserrno", "_sys_errlist", "STDLIB/_sys_errlist", "_sys_nerr", "STDLIB/_sys_nerr"] helpviewer_keywords: ["error codes, printing", "sys_errlist global variable", "doserrno global variable", "errno global variable", "_doserrno global variable", "_sys_errlist global variable", "_sys_nerr global variable", "sys_nerr global variable"] ms.assetid: adbec641-6d91-4e19-8398-9a34046bd369 --- @@ -16,7 +12,7 @@ Global macros that hold error codes that are set during program execution, and s ## Syntax -``` +```C #define errno (*_errno()) #define _doserrno (*__doserrno()) #define _sys_errlist (__sys_errlist()) @@ -25,39 +21,39 @@ Global macros that hold error codes that are set during program execution, and s ## Remarks -Both `errno` and `_doserrno` are set to 0 by the runtime during program startup. `errno` is set on an error in a system-level call. Because `errno` holds the value for the last call that set it, this value may be changed by succeeding calls. Run-time library calls that set `errno` on an error do not clear `errno` on success. Always clear `errno` by calling `_set_errno(0)` immediately before a call that may set it, and check it immediately after the call. +Both **`errno`** and **`_doserrno`** are set to 0 by the runtime during program startup. **`errno`** is set on an error in a system-level call. Because **`errno`** holds the value for the last call that set it, this value may be changed by succeeding calls. Run-time library calls that set **`errno`** on an error don't clear **`errno`** on success. Always clear **`errno`** by calling `_set_errno(0)` immediately before a call that may set it, and check it immediately after the call. -On an error, `errno` is not necessarily set to the same value as the error code returned by a system call. For I/O operations, `_doserrno` stores the operating-system error-code equivalents of `errno` codes. For most non-I/O operations, the value of `_doserrno` is not set. +On an error, **`errno`** isn't necessarily set to the same value as the error code returned by a system call. For I/O operations, **`_doserrno`** stores the operating-system error-code equivalents of **`errno`** codes. For most non-I/O operations, the value of **`_doserrno`** isn't set. -Each `errno` value is associated with an error message in `_sys_errlist` that can be printed by using one of the [`perror`](../c-runtime-library/reference/perror-wperror.md) functions, or stored in a string by using one of the [`strerror`](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md) or [`strerror_s`](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) functions. The `perror` and `strerror` functions use the `_sys_errlist` array and `_sys_nerr`—the number of elements in `_sys_errlist`—to process error information. Direct access to `_sys_errlist` and `_sys_nerr` is deprecated for code-security reasons. We recommend that you use the more secure, functional versions instead of the global macros, as shown here: +Each **`errno`** value is associated with an error message in **`_sys_errlist`** that can be printed by using one of the [`perror`](./reference/perror-wperror.md) functions, or stored in a string by using one of the [`strerror`](./reference/strerror-strerror-wcserror-wcserror.md) or [`strerror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) functions. The `perror` and `strerror` functions use the **`_sys_errlist`** array and **`_sys_nerr`**—the number of elements in **`_sys_errlist`**—to process error information. Direct access to **`_sys_errlist`** and **`_sys_nerr`** is deprecated for code-security reasons. We recommend that you use the more secure, functional versions instead of the global macros, as shown here: -|Global Macro|Functional Equivalents| -|------------------|----------------------------| -|`_doserrno`|[`_get_doserrno`](../c-runtime-library/reference/get-doserrno.md), [`_set_doserrno`](../c-runtime-library/reference/set-doserrno.md)| -|`errno`|[`_get_errno`](../c-runtime-library/reference/get-errno.md), [`_set_errno`](../c-runtime-library/reference/set-errno.md)| -|`_sys_errlist`, `_sys_nerr`|[`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)| +| Global macro | Functional equivalents | +|---|---| +| **`_doserrno`** | [`_get_doserrno`](./reference/get-doserrno.md), [`_set_doserrno`](./reference/set-doserrno.md) | +| **`errno`** | [`_get_errno`](./reference/get-errno.md), [`_set_errno`](./reference/set-errno.md) | +| **`_sys_errlist`**, **`_sys_nerr`** | [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) | -Library math routines set `errno` by calling [`_matherr`](../c-runtime-library/reference/matherr.md). To handle math errors differently, write your own routine according to the `_matherr` reference description and name it `_matherr`. +Library math routines set **`errno`** by calling [`_matherr`](./reference/matherr.md). To handle math errors differently, write your own routine according to the `_matherr` reference description and name it `_matherr`. -All `errno` values are predefined constants in ``, and are UNIX-compatible. Only `ERANGE`, `EILSEQ`, and `EDOM` are specified in the ISO C99 standard. For a complete list, see [errno Constants](../c-runtime-library/errno-constants.md). +All **`errno`** values are predefined constants in ``, and are UNIX-compatible. Only `ERANGE`, `EILSEQ`, and `EDOM` are specified in the ISO C99 standard. For a complete list, see [`errno` constants](./errno-constants.md). ## Requirements -|Global macro|Required header|Optional header| -|------------------|---------------------|---------------------| -|`errno`|`` or ``, `` or `` (C++)|| -|`_doserrno`, `_sys_errlist`, `_sys_nerr`|``, `` (C++)|``, `` (C++)| +| Global macro | Required header | Optional header | +|---|---|---| +| `errno` | `` or ``, `` or `` (C++) | | +| `_doserrno`, `_sys_errlist`, `_sys_nerr` | ``, `` (C++) | ``, `` (C++) | -The `_doserrno`, `_sys_errlist`, and `_sys_nerr` macros are Microsoft extensions. For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +The `_doserrno`, `_sys_errlist`, and `_sys_nerr` macros are Microsoft extensions. For more compatibility information, see [Compatibility](./compatibility.md). ## See also -[Global Variables](../c-runtime-library/global-variables.md)
-[`errno` Constants](../c-runtime-library/errno-constants.md)
-[`perror`, `_wperror`](../c-runtime-library/reference/perror-wperror.md)
-[`strerror`, `_strerror`, `_wcserror`, `__wcserror`](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md)
-[`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)
-[`_get_doserrno`](../c-runtime-library/reference/get-doserrno.md)
-[`_set_doserrno`](../c-runtime-library/reference/set-doserrno.md)
-[`_get_errno`](../c-runtime-library/reference/get-errno.md)
-[`_set_errno`](../c-runtime-library/reference/set-errno.md) +[Global variables](./global-variables.md)\ +[`errno` constants](./errno-constants.md)\ +[`perror`, `_wperror`](./reference/perror-wperror.md)\ +[`strerror`, `_strerror`, `_wcserror`, `__wcserror`](./reference/strerror-strerror-wcserror-wcserror.md)\ +[`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)\ +[`_get_doserrno`](./reference/get-doserrno.md)\ +[`_set_doserrno`](./reference/set-doserrno.md)\ +[`_get_errno`](./reference/get-errno.md)\ +[`_set_errno`](./reference/set-errno.md) diff --git a/docs/c-runtime-library/error-handling-crt.md b/docs/c-runtime-library/error-handling-crt.md index e0316576265..e2eca821d5e 100644 --- a/docs/c-runtime-library/error-handling-crt.md +++ b/docs/c-runtime-library/error-handling-crt.md @@ -11,18 +11,18 @@ Use these routines to handle program errors. ## Error-handling routines -|Routine|Use| -|-------------|---------| -|[assert](../c-runtime-library/reference/assert-macro-assert-wassert.md) macro|Test for programming logic errors; available in both the release and debug versions of the run-time library.| -|[_ASSERT, _ASSERTE](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) macros|Similar to **assert**, but only available in the debug versions of the run-time library.| -|[clearerr](../c-runtime-library/reference/clearerr.md)|Reset error indicator. Calling **rewind** or closing a stream also resets the error indicator.| -|[_eof](../c-runtime-library/reference/eof.md)|Check for end of file in low-level I/O.| -|[feof](../c-runtime-library/reference/feof.md)|Test for end of file. End of file is also indicated when **_read** returns 0.| -|[ferror](../c-runtime-library/reference/ferror.md)|Test for stream I/O errors.| -|[_RPT, _RPTF](../c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md) macros|Generate a report similar to **printf**, but only available in the debug versions of the run-time library.| -|[_set_error_mode](../c-runtime-library/reference/set-error-mode.md)|Modifies **__error_mode** to determine a non-default location where the C run time writes an error message for an error that will possibly end the program.| -|[_set_purecall_handler](../c-runtime-library/reference/get-purecall-handler-set-purecall-handler.md)|Sets the handler for a pure virtual function call.| +| Routine | Use | +|---|---| +| [`assert`](./reference/assert-macro-assert-wassert.md) macro | Test for programming logic errors; available in both the release and debug versions of the run-time library. | +| [`_ASSERT`, `_ASSERTE`](./reference/assert-asserte-assert-expr-macros.md) macros | Similar to `assert`, but only available in the debug versions of the run-time library. | +| [`clearerr`](./reference/clearerr.md) | Reset error indicator. Calling `rewind` or closing a stream also resets the error indicator. | +| [`_eof`](./reference/eof.md) | Check for end of file in low-level I/O. | +| [`feof`](./reference/feof.md) | Test for end of file. End of file is also indicated when `_read` returns 0. | +| [`ferror`](./reference/ferror.md) | Test for stream I/O errors. | +| [`_RPT`, `_RPTF`](./reference/rpt-rptf-rptw-rptfw-macros.md) macros | Generate a report similar to `printf`, but only available in the debug versions of the run-time library. | +| [`_set_error_mode`](./reference/set-error-mode.md) | Modifies `__error_mode` to determine a non-default location where the C run time writes an error message for an error that will possibly end the program. | +| [`_set_purecall_handler`](./reference/get-purecall-handler-set-purecall-handler.md) | Sets the handler for a pure virtual function call. | ## See also -- [Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +- [Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/except-handler3.md b/docs/c-runtime-library/except-handler3.md index 0e1ce4b6bff..c40b47cbad1 100644 --- a/docs/c-runtime-library/except-handler3.md +++ b/docs/c-runtime-library/except-handler3.md @@ -3,20 +3,20 @@ description: "Learn more about: _except_handler3" title: "_except_handler3" ms.date: "1/14/2021" api_name: ["_except_handler3"] -api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr100.dll", "msvcr110.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr100.dll", "msvcr110.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_except_handler3", "except_handler3"] helpviewer_keywords: ["_except_handler3 function", "except_handler3 function"] ms.assetid: b0c64898-0ae5-48b7-9724-80135a0813e2 --- -# _except_handler3 +# `_except_handler3` Internal CRT function. Used by a framework to find the appropriate exception handler to process the current exception. ## Syntax -``` +```C int _except_handler3( PEXCEPTION_RECORD exception_record, PEXCEPTION_REGISTRATION registration, @@ -27,26 +27,26 @@ int _except_handler3( #### Parameters -*exception_record*
+*`exception_record`*\ [in] Information about the specific exception. -*registration*
+*`registration`*\ [in] The record that indicates which scope table should be used to find the exception handler. -*context*
+*`context`*\ [in] Reserved. -*dispatcher*
+*`dispatcher`*\ [in] Reserved. -## Return Value +## Return value If an exception should be dismissed, returns `DISPOSITION_DISMISS`. If the exception should be passed up a level to the encapsulating exception handlers, returns `DISPOSITION_CONTINUE_SEARCH`. ## Remarks -If this method finds an appropriate exception handler, it passes the exception to the handler. In this situation, this method does not return to the code that called it and the return value is irrelevant. +If this method finds an appropriate exception handler, it passes the exception to the handler. In this situation, this method doesn't return to the code that called it and the return value is irrelevant. ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/exception-handling-constants.md b/docs/c-runtime-library/exception-handling-constants.md index 6bdc7e47489..3ea54bfa938 100644 --- a/docs/c-runtime-library/exception-handling-constants.md +++ b/docs/c-runtime-library/exception-handling-constants.md @@ -2,14 +2,14 @@ description: "Learn more about: Exception-Handling Constants" title: "Exception-Handling Constants" ms.date: "11/04/2016" -f1_keywords: ["EXCEPTION_CONTINUE_SEARCH", "EXCEPTION_CONTINUE_EXECUTION", "EXCEPTION_EXECUTE_HANDLER"] +f1_keywords: ["EXCEPTION_CONTINUE_SEARCH", "EXCEPTION_CONTINUE_EXECUTION", "EXCEPTION_EXECUTE_HANDLER", "EXCPT/EXCEPTION_CONTINUE_SEARCH", "EXCPT/EXCEPTION_CONTINUE_EXECUTION", "EXCPT/EXCEPTION_EXECUTE_HANDLER"] helpviewer_keywords: ["exception handling, constants", "EXCEPTION_CONTINUE_SEARCH constant", "EXCEPTION_EXECUTE_HANDLER constant", "EXCEPTION_CONTINUE_EXECUTION constant", "EH constants"] ms.assetid: e1870f41-be9e-46a3-a2ea-830dfbaa18fb --- -# Exception-Handling Constants +# Exception-handling constants The constant `EXCEPTION_CONTINUE_SEARCH`, `EXCEPTION_CONTINUE_EXECUTION`, or `EXCEPTION_EXECUTE_HANDLER` is returned when an exception occurs during execution of the guarded section of a **try-except** statement. The return value determines how the exception is handled. For more information, see [try-except Statement](../cpp/try-except-statement.md) in the *C++ Language Reference*. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/exception-handling-routines.md b/docs/c-runtime-library/exception-handling-routines.md index 1de3f22da43..c9755f8bf90 100644 --- a/docs/c-runtime-library/exception-handling-routines.md +++ b/docs/c-runtime-library/exception-handling-routines.md @@ -6,20 +6,20 @@ f1_keywords: ["c.exceptions"] helpviewer_keywords: ["exception handling, routines"] ms.assetid: f60548c6-850a-4e1e-a79b-a2a6a541ab62 --- -# Exception Handling Routines +# Exception handling routines Use the C++ exception-handling functions to recover from unexpected events during program execution. -## Exception-Handling Functions +## Exception-handling functions -|Function|Use| -|--------------|---------| -|[_set_se_translator](../c-runtime-library/reference/set-se-translator.md)|Handle Win32 exceptions (C structured exceptions) as C++ typed exceptions| -|[set_terminate](../c-runtime-library/reference/set-terminate-crt.md)|Install your own termination routine to be called by **terminate**| -|[set_unexpected](../c-runtime-library/reference/set-unexpected-crt.md)|Install your own termination function to be called by **unexpected**| -|[terminate](../c-runtime-library/reference/terminate-crt.md)|Called automatically under certain circumstances after exception is thrown. The **terminate** function calls **abort** or a function you specify using **set_terminate**| -|[unexpected](../c-runtime-library/reference/unexpected-crt.md)|Calls **terminate** or a function you specify using **set_unexpected**. The **unexpected** function is not used in current Microsoft C++ exception-handling implementation| +| Function | Use | +|---|---| +| [`_set_se_translator`](./reference/set-se-translator.md) | Handle Win32 exceptions (C structured exceptions) as C++ typed exceptions | +| [`set_terminate`](./reference/set-terminate-crt.md) | Install your own termination routine to be called by `terminate` | +| [`set_unexpected`](./reference/set-unexpected-crt.md) | Install your own termination function to be called by `unexpected` | +| [`terminate`](./reference/terminate-crt.md) | Called automatically under certain circumstances after exception is thrown. The `terminate` function calls `abort` or a function you specify using `set_terminate` | +| [`unexpected`](./reference/unexpected-crt.md) | Calls `terminate` or a function you specify using `set_unexpected`. The `unexpected` function isn't used in current Microsoft C++ exception-handling implementation | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/exec-wexec-functions.md b/docs/c-runtime-library/exec-wexec-functions.md index 7227f245fc6..9b9921f56fb 100644 --- a/docs/c-runtime-library/exec-wexec-functions.md +++ b/docs/c-runtime-library/exec-wexec-functions.md @@ -14,48 +14,48 @@ Each function in this family loads and executes a new process: :::row::: :::column span=""::: - [`_execl`, `_wexecl`](../c-runtime-library/reference/execl-wexecl.md)\ - [`_execv`, `_wexecv`](../c-runtime-library/reference/execv-wexecv.md)\ - [`_execle`, `_wexecle`](../c-runtime-library/reference/execle-wexecle.md) + [`_execl`, `_wexecl`](./reference/execl-wexecl.md)\ + [`_execv`, `_wexecv`](./reference/execv-wexecv.md)\ + [`_execle`, `_wexecle`](./reference/execle-wexecle.md) :::column-end::: :::column span=""::: - [`_execve`, `_wexecve`](../c-runtime-library/reference/execve-wexecve.md)\ - [`_execlp`, `_wexeclp`](../c-runtime-library/reference/execlp-wexeclp.md)\ - [`_execvp`, `_wexecvp`](../c-runtime-library/reference/execvp-wexecvp.md) + [`_execve`, `_wexecve`](./reference/execve-wexecve.md)\ + [`_execlp`, `_wexeclp`](./reference/execlp-wexeclp.md)\ + [`_execvp`, `_wexecvp`](./reference/execvp-wexecvp.md) :::column-end::: :::column span=""::: - [`_execlpe`, `_wexeclpe`](../c-runtime-library/reference/execlpe-wexeclpe.md)\ - [`_execvpe`, `_wexecvpe`](../c-runtime-library/reference/execvpe-wexecvpe.md) + [`_execlpe`, `_wexeclpe`](./reference/execlpe-wexeclpe.md)\ + [`_execvpe`, `_wexecvpe`](./reference/execvpe-wexecvpe.md) :::column-end::: :::row-end::: The letter at the end of the function name determines the variation. -|_exec function suffix|Description| -|----------------------------|-----------------| -|`e`|`envp`, array of pointers to environment settings, is passed to the new process.| -|`l`|Command-line arguments are passed individually to `_exec` function. Typically used when the number of parameters to the new process is known in advance.| -|`p`|`PATH` environment variable is used to find the file to execute.| -|`v`|`argv`, array of pointers to command-line arguments, is passed to `_exec`. Typically used when the number of parameters to the new process is variable.| +| `_exec` function suffix | Description | +|---|---| +| `e` | `envp`, array of pointers to environment settings, is passed to the new process. | +| `l` | Command-line arguments are passed individually to `_exec` function. Typically used when the number of parameters to the new process is known in advance. | +| `p` | `PATH` environment variable is used to find the file to execute. | +| `v` | `argv`, array of pointers to command-line arguments, is passed to `_exec`. Typically used when the number of parameters to the new process is variable. | ## Remarks Each `_exec` function loads and executes a new process. All `_exec` functions use the same operating-system function ([`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw)). The `_exec` functions automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. The `_wexec` functions are wide-character versions of the `_exec` functions. The `_wexec` functions behave identically to their `_exec` family counterparts except that they don't handle multibyte-character strings. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE and _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_texecl`|`_execl`|`_execl`|`_wexecl`| -|`_texecle`|`_execle`|`_execle`|`_wexecle`| -|`_texeclp`|`_execlp`|`_execlp`|`_wexeclp`| -|`_texeclpe`|`_execlpe`|`_execlpe`|`_wexeclpe`| -|`_texecv`|`_execv`|`_execv`|`_wexecv`| -|`_texecve`|`_execve`|`_execve`|`_wexecve`| -|`_texecvp`|`_execvp`|`_execvp`|`_wexecvp`| -|`_texecvpe`|`_execvpe`|`_execvpe`|`_wexecvpe`| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_texecl` | **`_execl`** | **`_execl`** | **`_wexecl`** | +| `_texecle` | **`_execle`** | **`_execle`** | **`_wexecle`** | +| `_texeclp` | **`_execlp`** | **`_execlp`** | **`_wexeclp`** | +| `_texeclpe` | **`_execlpe`** | **`_execlpe`** | **`_wexeclpe`** | +| `_texecv` | **`_execv`** | **`_execv`** | **`_wexecv`** | +| `_texecve` | **`_execve`** | **`_execve`** | **`_wexecve`** | +| `_texecvp` | **`_execvp`** | **`_execvp`** | **`_wexecvp`** | +| `_texecvpe` | **`_execvpe`** | **`_execvpe`** | **`_wexecvpe`** | -The `cmdname` parameter specifies the file to be executed as the new process. It can specify a full path (from the root), a partial path (from the current working directory), or a file name. If `cmdname` doesn't have a file name extension or doesn't end with a period (.), the `_exec` function searches for the named file. If the search is unsuccessful, it tries the same base name with the .com file name extension and then with the .exe, .bat, and .cmd file name extensions. If `cmdname` has a file name extension, only that extension is used in the search. If `cmdname` ends with a period, the `_exec` function searches for `cmdname` with no file name extension. `_execlp`, `_execlpe`, `_execvp`, and `_execvpe` search for `cmdname` (using the same procedures) in the directories specified by the `PATH` environment variable. If `cmdname` contains a drive specifier or any slashes (that is, if it's a relative path), the `_exec` call searches only for the specified file; the path isn't searched. +The `cmdname` parameter specifies the file to be executed as the new process. It can specify a full path (from the root), a partial path (from the current working directory), or a file name. If `cmdname` doesn't have a file name extension or doesn't end with a period (.), the `_exec` function searches for the named file. If the search is unsuccessful, it tries the same base name with the .com file name extension and then with the .exe, .bat, and .cmd file name extensions. If `cmdname` has a file name extension, only that extension is used in the search. If `cmdname` ends with a period, the `_exec` function searches for `cmdname` with no file name extension. **`_execlp`**, **`_execlpe`**, **`_execvp`**, and **`_execvpe`** search for `cmdname` (using the same procedures) in the directories specified by the `PATH` environment variable. If `cmdname` contains a drive specifier or any slashes (that is, if it's a relative path), the `_exec` call searches only for the specified file; the path isn't searched. Parameters are passed to the new process by giving one or more pointers to character strings as parameters in the `_exec` call. These character strings form the parameter list for the new process. The combined length of the inherited environment settings and the strings forming the parameter list for the new process must not exceed 32 kilobytes. The terminating `NULL` character (`\0`) for each string isn't included in the count, but space characters (inserted automatically to separate the parameters) are counted. @@ -65,19 +65,19 @@ Parameters are passed to the new process by giving one or more pointers to chara > [!IMPORTANT] > Do not pass user input to `_exec` without explicitly checking its content. `_exec` will result in a call to [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw) so keep in mind that unqualified path names could lead to potential security vulnerabilities. -The `_exec` functions validate their parameters. If expected parameters are null pointers, empty strings, or omitted, the `_exec` functions invoke the invalid parameter handler as described in [Parameter Validation](../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is executed. +The `_exec` functions validate their parameters. If expected parameters are null pointers, empty strings, or omitted, the `_exec` functions invoke the invalid parameter handler as described in [Parameter validation](./parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is executed. -The argument pointers can be passed as separate parameters (in `_execl`, `_execle`, `_execlp`, and `_execlpe`) or as an array of pointers (in `_execv`, `_execve`, `_execvp`, and `_execvpe`). At least one parameter, `arg0`, must be passed to the new process; this parameter is `argv[0]` of the new process. Usually, this parameter is a copy of `cmdname`. (A different value doesn't produce an error.) +The argument pointers can be passed as separate parameters (in **`_execl`**, **`_execle`**, **`_execlp`**, and **`_execlpe`**) or as an array of pointers (in **`_execv`**, **`_execve`**, **`_execvp`**, and **`_execvpe`**). At least one parameter, `arg0`, must be passed to the new process; this parameter is `argv[0]` of the new process. Usually, this parameter is a copy of `cmdname`. (A different value doesn't produce an error.) -The `_execl`, `_execle`, `_execlp`, and `_execlpe` calls are typically used when the number of parameters is known in advance. The parameter `arg0` is usually a pointer to `cmdname`. The parameters `arg1` through `argn` point to the character strings forming the new parameter list. A null pointer must follow `argn` to mark the end of the parameter list. +The **`_execl`**, **`_execle`**, **`_execlp`**, and **`_execlpe`** calls are typically used when the number of parameters is known in advance. The parameter `arg0` is usually a pointer to `cmdname`. The parameters `arg1` through `argn` point to the character strings forming the new parameter list. A null pointer must follow `argn` to mark the end of the parameter list. -The `_execv`, `_execve`, `_execvp`, and `_execvpe` calls are useful when the number of parameters to the new process is variable. Pointers to the parameters are passed as an array, `argv`. The parameter `argv[0]` is usually a pointer to `cmdname`. The parameters `argv[1]` through `argv[n]` point to the character strings forming the new parameter list. The parameter `argv[n+1]` must be a **`NULL`** pointer to mark the end of the parameter list. +The **`_execv`**, **`_execve`**, **`_execvp`**, and **`_execvpe`** calls are useful when the number of parameters to the new process is variable. Pointers to the parameters are passed as an array, `argv`. The parameter `argv[0]` is usually a pointer to `cmdname`. The parameters `argv[1]` through `argv[n]` point to the character strings forming the new parameter list. The parameter `argv[n+1]` must be a `NULL` pointer to mark the end of the parameter list. -Files that are open when an `_exec` call is made remain open in the new process. In `_execl`, `_execlp`, `_execv`, and `_execvp` calls, the new process inherits the environment of the calling process. `_execle`, `_execlpe`, `_execve`, and `_execvpe` calls alter the environment for the new process by passing a list of environment settings through the `envp` parameter. `envp` is an array of character pointers, each element of which (except for the final element) points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME=value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (Note that `value` isn't enclosed in double quotation marks.) The final element of the `envp` array should be **`NULL`**. When `envp` itself is **`NULL`**, the new process inherits the environment settings of the calling process. +Files that are open when an `_exec` call is made remain open in the new process. In **`_execl`**, **`_execlp`**, **`_execv`**, and **`_execvp`** calls, the new process inherits the environment of the calling process. **`_execle`**, **`_execlpe`**, **`_execve`**, and **`_execvpe`** calls alter the environment for the new process by passing a list of environment settings through the `envp` parameter. `envp` is an array of character pointers, each element of which (except for the final element) points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME=value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (The `value` isn't enclosed in double quotation marks.) The final element of the `envp` array should be `NULL`. When `envp` itself is `NULL`, the new process inherits the environment settings of the calling process. A program executed with one of the `_exec` functions is always loaded into memory as if the maximum allocation field in the program's .exe file header were set to the default value of `0xFFFFH`. -The `_exec` calls don't preserve the translation modes of open files. If the new process must use files inherited from the calling process, use the [`_setmode`](../c-runtime-library/reference/setmode.md) routine to set the translation mode of these files to the desired mode. You must explicitly flush (using `fflush` or `_flushall`) or close any stream before the `_exec` function call. Signal settings aren't preserved in new processes that are created by calls to `_exec` routines. The signal settings are reset to the default in the new process. +The `_exec` calls don't preserve the translation modes of open files. If the new process must use files inherited from the calling process, use the [`_setmode`](./reference/setmode.md) routine to set the translation mode of these files to the desired mode. You must explicitly flush (using `fflush` or `_flushall`) or close any stream before the `_exec` function call. Signal settings aren't preserved in new processes that are created by calls to `_exec` routines. The signal settings are reset to the default in the new process. ## Example @@ -193,10 +193,10 @@ int main( int ac, char* av[] ) ## See also -[Process and Environment Control](../c-runtime-library/process-and-environment-control.md)\ -[`abort`](../c-runtime-library/reference/abort.md)\ -[`atexit`](../c-runtime-library/reference/atexit.md)\ -[`exit`, `_Exit`, `_exit`](../c-runtime-library/reference/exit-exit-exit.md)\ -[`_onexit`, `_onexit_m`](../c-runtime-library/reference/onexit-onexit-m.md)\ -[`_spawn`, `_wspawn` Functions](../c-runtime-library/spawn-wspawn-functions.md)\ -[`system`, `_wsystem`](../c-runtime-library/reference/system-wsystem.md) +[Process and environment control](./process-and-environment-control.md)\ +[`abort`](./reference/abort.md)\ +[`atexit`](./reference/atexit.md)\ +[`exit`, `_Exit`, `_exit`](./reference/exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](./spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](./reference/system-wsystem.md) diff --git a/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md b/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md index c142484008c..d03b81c3894 100644 --- a/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md +++ b/docs/c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md @@ -3,20 +3,20 @@ description: "Learn more about: _execute_onexit_table, _initialize_onexit_table, title: "_execute_onexit_table, _initialize_onexit_table, _register_onexit_function" ms.date: "4/2/2020" api_name: ["_execute_onexit_table", "_initialize_onexit_table", "_register_onexit_function", "_o__execute_onexit_table", "_o__initialize_onexit_table", "_o__register_onexit_function"] -api_location: ["api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_execute_onexit_table", "process/_execute_onexit_table", "_initialize_onexit_table", "process/_initialize_onexit_table", "_register_onexit_function", "process/_register_onexit_function"] helpviewer_keywords: ["_execute_onexit_table function", "_initialize_onexit_table function", "_register_onexit_function function"] ms.assetid: ad9e4149-d4ad-4fdf-aaaf-cf786fcb4473 --- -# _execute_onexit_table, _initialize_onexit_table, _register_onexit_function +# `_execute_onexit_table`, `_initialize_onexit_table`, `_register_onexit_function` Manages the routines to be called at exit time. ## Syntax -``` +```C int _initialize_onexit_table( _onexit_table_t* table ); @@ -33,38 +33,38 @@ int _execute_onexit_table( #### Parameters -*table*
-[in, out] Pointer to the onexit function table. +*`table`*\ +[in, out] Pointer to the `onexit` function table. -*function*
-[in] Pointer to a function to add to the onexit function table. +*`function`*\ +[in] Pointer to a function to add to the `onexit` function table. -## Return Value +## Return value -If successful, returns 0. Otherwise, returns a negative value. +If successful, the function returns 0. Otherwise, it returns a negative value. ## Remarks -These functions are infrastructure implementation details used to support the C runtime, and should not be called directly from your code. The C runtime uses an *onexit function table* to represent the sequence of functions registered by calls to `atexit`, `at_quick_exit`, and `_onexit`. The onexit function table data structure is an opaque implementation detail of the C runtime; the order and meaning of its data members may change. They should not be inspected by external code. +These functions are infrastructure implementation details used to support the C runtime, and shouldn't be called directly from your code. The C runtime uses an `onexit` function table to represent the sequence of functions registered by calls to `atexit`, `at_quick_exit`, and `_onexit`. The `onexit` function table data structure is an opaque implementation detail of the C runtime; the order and meaning of its data members may change. They shouldn't be inspected by external code. -The `_initialize_onexit_table` function initializes the onexit function table to its initial value. This function must be called before the onexit function table is passed to either `_register_onexit_function` or `_execute_onexit_table`. +The **`_initialize_onexit_table`** function initializes the `onexit` function table to its initial value. This function must be called before the `onexit` function table is passed to either **`_register_onexit_function`** or **`_execute_onexit_table`**. -The `_register_onexit_function` function appends a function to the end of the onexit function table. +The **`_register_onexit_function`** function appends a function to the end of the `onexit` function table. -The `_execute_onexit_table` function executes all of the functions in the onexit function table, clears the table, and then returns. After a call to `_execute_onexit_table`, the table is in a non-valid state; it must be reinitialized by a call to `_initialize_onexit_table` before it is used again. +The **`_execute_onexit_table`** function executes all of the functions in the `onexit` function table, clears the table, and then returns. After a call to **`_execute_onexit_table`**, the table is in a non-valid state; it must be reinitialized by a call to **`_initialize_onexit_table`** before it's used again. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_initialize_onexit_table function`, `_register_onexit_function`, `_execute_onexit_table`|C, C++: \| +| Routine | Required header | +|---|---| +| **`_initialize_onexit_table`**, **`_register_onexit_function`**, **`_execute_onexit_table`** | C, C++: \ | -The `_initialize_onexit_table`, `_register_onexit_function`, and `_execute_onexit_table` functions are Microsoft-specific. For compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +The **`_initialize_onexit_table`**, **`_register_onexit_function`**, and **`_execute_onexit_table`** functions are Microsoft-specific. For compatibility information, see [Compatibility](./compatibility.md). ## See also -[atexit](../c-runtime-library/reference/atexit.md)
-[exit, _Exit, _exit](../c-runtime-library/reference/exit-exit-exit.md)
-[_onexit, _onexit_m](../c-runtime-library/reference/onexit-onexit-m.md) +[`atexit`](./reference/atexit.md)\ +[`exit`, `_Exit`, `_exit`](./reference/exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md) diff --git a/docs/c-runtime-library/exit-success-exit-failure.md b/docs/c-runtime-library/exit-success-exit-failure.md index af56fa001c4..ddedc9aa4cd 100644 --- a/docs/c-runtime-library/exit-success-exit-failure.md +++ b/docs/c-runtime-library/exit-success-exit-failure.md @@ -2,7 +2,7 @@ description: "Learn more about: EXIT_SUCCESS, EXIT_FAILURE" title: "EXIT_SUCCESS, EXIT_FAILURE" ms.date: "06/25/2018" -f1_keywords: ["EXIT_FAILURE", "EXIT_SUCCESS"] +f1_keywords: ["EXIT_FAILURE", "EXIT_SUCCESS", "STDLIB/EXIT_FAILURE", "STDLIB/EXIT_SUCCESS"] helpviewer_keywords: ["EXIT_SUCCESS constant", "EXIT_FAILURE constant"] --- # `EXIT_SUCCESS`, `EXIT_FAILURE` @@ -15,13 +15,13 @@ helpviewer_keywords: ["EXIT_SUCCESS constant", "EXIT_FAILURE constant"] ## Remarks -These are arguments for the [`exit`](reference/exit-exit-exit.md) and [`_exit`](reference/exit-exit-exit.md) functions, and the return values for the [`atexit`](reference/atexit.md) and [`_onexit`](reference/onexit-onexit-m.md) functions. +The **`EXIT_SUCCESS`** and `EXIT_FAILURE` constants are arguments for the [`exit`](reference/exit-exit-exit.md) and [`_exit`](reference/exit-exit-exit.md) functions, and the return values for the [`atexit`](reference/atexit.md) and [`_onexit`](reference/onexit-onexit-m.md) functions. -|Constant|Defined value| -|-|-| -|`EXIT_SUCCESS`|0| -|`EXIT_FAILURE`|1| +| Constant | Defined value | +|---|---| +| **`EXIT_SUCCESS`** | 0 | +| **`EXIT_FAILURE`** | 1 | ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-attribute-constants.md b/docs/c-runtime-library/file-attribute-constants.md index be625bb0b8f..a7d89dbfd8d 100644 --- a/docs/c-runtime-library/file-attribute-constants.md +++ b/docs/c-runtime-library/file-attribute-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: File Attribute Constants" title: "File Attribute Constants" ms.date: "11/04/2016" -f1_keywords: ["A_HIDDEN", "_A_NORMAL", "_A_SUBDIR", "_A_RDONLY", "A_NORMAL", "A_SUBDIR", "_A_SYSTEM", "c.constants.file", "_A_HIDDEN", "A_RDONLY", "_A_ARCH", "A_ARCH"] +f1_keywords: ["_A_ARCH", "_A_HIDDEN", "_A_NORMAL", "_A_RDONLY", "_A_SUBDIR", "_A_SYSTEM", "CORECRT_IO/_A_ARCH", "CORECRT_IO/_A_HIDDEN", "CORECRT_IO/_A_NORMAL", "CORECRT_IO/_A_RDONLY", "CORECRT_IO/_A_SUBDIR", "CORECRT_IO/_A_SYSTEM", "c.constants.file"] helpviewer_keywords: ["constants [C++], file attributes", "file attribute constants [C++]", "_A_SYSTEM constant", "files [C++], file attribute constants", "_A_SUBDIR constant", "_A_ARCH constant", "_A_NORMAL constant", "_A_HIDDEN constant", "_A_RDONLY constant"] ms.assetid: 8dc8ccb9-99f5-446b-876c-7ebecc2f764f --- -# File Attribute Constants +# File attribute constants ## Syntax -``` +```C #include ``` @@ -20,18 +20,18 @@ These constants specify the current attributes of the file or directory specifie The attributes are represented by the following manifest constants: -|Constant|Description| -|-|-| -|`_A_ARCH`| Archive. Set whenever the file is changed, and cleared by the BACKUP command. Value: 0x20| -|`_A_HIDDEN`| Hidden file. Not normally seen with the DIR command, unless the /AH option is used. Returns information about normal files as well as files with this attribute. Value: 0x02| -|`_A_NORMAL`| Normal. File can be read or written to without restriction. Value: 0x00| -|`_A_RDONLY`| Read-only. File cannot be opened for writing, and a file with the same name cannot be created. Value: 0x01| -|`_A_SUBDIR`| Subdirectory. Value: 0x10| -|`_A_SYSTEM`| System file. Not normally seen with the DIR command, unless the /AS option is used. Value: 0x04| +| Constant | Description | +|---|---| +| `_A_ARCH` | Archive. Set whenever the file is changed, and cleared by the BACKUP command. Value: 0x20 | +| `_A_HIDDEN` | Hidden file. Not normally seen with the DIR command, unless the /AH option is used. Returns information about both normal files and files with this attribute. Value: 0x02 | +| `_A_NORMAL` | Normal. File can be read or written to without restriction. Value: 0x00 | +| `_A_RDONLY` | Read-only. File can't be opened for writing, and a file with the same name can't be created. Value: 0x01 | +| `_A_SUBDIR` | Subdirectory. Value: 0x10 | +| `_A_SYSTEM` | System file. Not normally seen with the DIR command, unless the /AS option is used. Value: 0x04 | Multiple constants can be combined with the OR operator (`|`). ## See also -[Filename Search Functions](../c-runtime-library/filename-search-functions.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Filename search functions](./filename-search-functions.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-constants.md b/docs/c-runtime-library/file-constants.md index 0e8b4eca683..2d129f4ee1b 100644 --- a/docs/c-runtime-library/file-constants.md +++ b/docs/c-runtime-library/file-constants.md @@ -2,36 +2,36 @@ description: "Learn more about: File Constants" title: "File Constants" ms.date: "11/04/2016" -f1_keywords: ["_O_EXCL", "_O_RDWR", "_O_APPEND", "_O_RDONLY", "_O_TRUNC", "_O_CREAT", "_O_WRONLY"] +f1_keywords: ["_O_APPEND", "_O_CREAT", "_O_EXCL", "_O_RDONLY", "_O_RDWR", "_O_TRUNC", "_O_WRONLY", "FCNTL/_O_APPEND", "FCNTL/_O_CREAT", "FCNTL/_O_EXCL", "FCNTL/_O_RDONLY", "FCNTL/_O_RDWR", "FCNTL/_O_TRUNC", "FCNTL/_O_WRONLY"] helpviewer_keywords: ["_O_RDWR constant", "O_EXCL constant", "O_RDWR constant", "O_WRONLY constant", "O_APPEND constant", "O_CREAT constant", "_O_CREAT constant", "_O_APPEND constant", "_O_EXCL constant", "O_TRUNC constant", "_O_RDONLY constant", "_O_TRUNC constant", "O_RDONLY constant", "_O_WRONLY constant"] ms.assetid: c8fa5548-9ac2-4217-801d-eb45e86f2fa4 --- -# File Constants +# File constants ## Syntax -``` +```C #include ``` ## Remarks -The integer expression formed from one or more of these constants determines the type of reading or writing operations permitted. It is formed by combining one or more constants with a translation-mode constant. +The integer expression formed from one or more of these constants determines the type of reading or writing operations permitted. It's formed by combining one or more constants with a translation-mode constant. The file constants are as follows: -|Constant|Description| -|-|-| -| `_O_APPEND` | Repositions the file pointer to the end of the file before every write operation. | -| `_O_CREAT` | Creates and opens a new file for writing; this has no effect if the file specified by *filename* exists. | -| `_O_EXCL` | Returns an error value if the file specified by *filename* exists. Only applies when used with `_O_CREAT`. | -| `_O_RDONLY` | Opens file for reading only; if this flag is given, neither `_O_RDWR` nor `_O_WRONLY` can be given. | -| `_O_RDWR` | Opens file for both reading and writing; if this flag is given, neither `_O_RDONLY` nor `_O_WRONLY` can be given. | -| `_O_TRUNC` | Opens and truncates an existing file to zero length; the file must have write permission. The contents of the file are destroyed. If this flag is given, you cannot specify `_O_RDONLY`. | -| `_O_WRONLY` | Opens file for writing only; if this flag is given, neither `_O_RDONLY` nor `_O_RDWR` can be given. | +| Constant | Description | +|---|---| +| `_O_APPEND` | Repositions the file pointer to the end of the file before every write operation. | +| `_O_CREAT` | Creates and opens a new file for writing; the constant has no effect if the file specified by *`filename`* exists. | +| `_O_EXCL` | Returns an error value if the file specified by *`filename`* exists. Only applies when used with `_O_CREAT`. | +| `_O_RDONLY` | Opens file for reading only; if this flag is given, `_O_RDWR` and `_O_WRONLY` can't be given. | +| `_O_RDWR` | Opens file for both reading and writing; if this flag is given, `_O_RDONLY` and `_O_WRONLY` can't be given. | +| `_O_TRUNC` | Opens and truncates an existing file to zero length; the file must have write permission. The contents of the file are destroyed. If this flag is given, you can't specify `_O_RDONLY`. | +| `_O_WRONLY` | Opens file for writing only; if this flag is given, `_O_RDONLY` and `_O_RDWR` can't be given. | ## See also -[_open, _wopen](../c-runtime-library/reference/open-wopen.md)
-[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_open`, `_wopen`](./reference/open-wopen.md)\ +[`_sopen`, `_wsopen`](./reference/sopen-wsopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-handling.md b/docs/c-runtime-library/file-handling.md index 5da950aeef3..661f7a0fb39 100644 --- a/docs/c-runtime-library/file-handling.md +++ b/docs/c-runtime-library/file-handling.md @@ -1,82 +1,79 @@ --- -description: "Learn more about: File Handling" title: "File Handling" -ms.date: "11/04/2016" +description: "Learn more about: File Handling" +ms.date: 11/04/2016 f1_keywords: ["c.files"] helpviewer_keywords: ["files [C++], handling", "files [C++], opening", "files [C++], manipulating"] -ms.assetid: 48119e2e-e94f-4602-b08b-b72440f731d8 --- -# File Handling +# File handling Use these routines to create, delete, and manipulate files and to set and check file-access permissions. -The C run-time libraries have a 512 limit for the number of files that can be open at any one time. Attempting to open more than the maximum number of file descriptors or file streams causes program failure. Use [`_setmaxstdio`](../c-runtime-library/reference/setmaxstdio.md) to change this number. +The C run-time libraries have a 512 limit for the number of files that can be open at any one time. Attempting to open more than the maximum number of file descriptors or file streams causes program failure. Use [`_setmaxstdio`](reference/setmaxstdio.md) to change this number. -## File-Handling Routines (File Descriptor) +## File-handling routines (file descriptor) These routines operate on files designated by a file descriptor. -|Routine|Use| -|-------------|---------| -|[`_chsize`](../c-runtime-library/reference/chsize.md),[`_chsize_s`](../c-runtime-library/reference/chsize-s.md)|Change file size| -|[`_filelength`, `_filelengthi64`](../c-runtime-library/reference/filelength-filelengthi64.md)|Get file length| -|[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](../c-runtime-library/reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)|Get file-status information on descriptor| -|[`_get_osfhandle`](../c-runtime-library/reference/get-osfhandle.md)|Return operating-system file handle associated with existing C run-time file descriptor| -|[`_isatty`](../c-runtime-library/reference/isatty.md)|Check for character device| -|[`_locking`](../c-runtime-library/reference/locking.md)|Lock areas of file| -|[`_open_osfhandle`](../c-runtime-library/reference/open-osfhandle.md)|Associate C run-time file descriptor with existing operating-system file handle| -|[`_setmode`](../c-runtime-library/reference/setmode.md)|Set file-translation mode| +| Routine | Use | +|---|---| +| [`_chsize`](reference/chsize.md), [`_chsize_s`](reference/chsize-s.md) | Change file size | +| [`_filelength`, `_filelengthi64`](reference/filelength-filelengthi64.md) | Get file length | +| [`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](reference/fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md) | Get file-status information on descriptor | +| [`_get_osfhandle`](reference/get-osfhandle.md) | Return operating-system file handle associated with existing C run-time file descriptor | +| [`_isatty`](reference/isatty.md) | Check for character device | +| [`_locking`](reference/locking.md) | Lock areas of file | +| [`_open_osfhandle`](reference/open-osfhandle.md) | Associate C run-time file descriptor with existing operating-system file handle | +| [`_setmode`](reference/setmode.md) | Set file-translation mode | ## File-Handling Routines (Path or Filename) These routines operate on files specified by a path or filename. -|Routine|Use| -|-------------|---------| -|[`_access`, `_waccess`](../c-runtime-library/reference/access-waccess.md), [`_access_s`, `_waccess_s`](../c-runtime-library/reference/access-s-waccess-s.md)|Check file-permission setting| -|[`_chmod`, `_wchmod`](../c-runtime-library/reference/chmod-wchmod.md)|Change file-permission setting| -|[`_fullpath`, `_wfullpath`](../c-runtime-library/reference/fullpath-wfullpath.md)|Expand a relative path to its absolute path name| -|[`_makepath`, `_wmakepath`](../c-runtime-library/reference/makepath-wmakepath.md), [`_makepath_s`, `_wmakepath_s`](../c-runtime-library/reference/makepath-s-wmakepath-s.md)|Merge path components into single, full path| -|[`_mktemp`, `_wmktemp`](../c-runtime-library/reference/mktemp-wmktemp.md), [`_mktemp_s`, `_wmktemp_s`](../c-runtime-library/reference/mktemp-s-wmktemp-s.md)|Create unique filename| -|[`remove`, `_wremove`](../c-runtime-library/reference/remove-wremove.md)|Delete file| -|[`rename`, `_wrename`](../c-runtime-library/reference/rename-wrename.md)|Rename file| -|[`_splitpath`, `_wsplitpath`](../c-runtime-library/reference/splitpath-wsplitpath.md), [`_splitpath_s`, `_wsplitpath_s`](../c-runtime-library/reference/splitpath-s-wsplitpath-s.md)|Parse path into components| -|[`_stat`, `_stat64`, `_stati64`, `_wstat`, `_wstat64`, `_wstati64`](../c-runtime-library/reference/stat-functions.md)|Get file-status information on named file| -|[`_umask`](../c-runtime-library/reference/umask.md), [`_umask_s`](../c-runtime-library/reference/umask-s.md)|Set default permission mask for new files created by program| -|[`_unlink`, `_wunlink`](../c-runtime-library/reference/unlink-wunlink.md)|Delete file| +| Routine | Use | +|---|---| +| [`_access`, `_waccess`](reference/access-waccess.md), [`_access_s`, `_waccess_s`](reference/access-s-waccess-s.md) | Check file-permission setting | +| [`_chmod`, `_wchmod`](reference/chmod-wchmod.md) | Change file-permission setting | +| [`_fullpath`, `_wfullpath`](reference/fullpath-wfullpath.md) | Expand a relative path to its absolute path name | +| [`_makepath`, `_wmakepath`](reference/makepath-wmakepath.md), [`_makepath_s`, `_wmakepath_s`](reference/makepath-s-wmakepath-s.md) | Merge path components into single, full path | +| [`_mktemp`, `_wmktemp`](reference/mktemp-wmktemp.md), [`_mktemp_s`, `_wmktemp_s`](reference/mktemp-s-wmktemp-s.md) | Create unique filename | +| [`remove`, `_wremove`](reference/remove-wremove.md) | Delete file | +| [`rename`, `_wrename`](reference/rename-wrename.md) | Rename file | +| [`_splitpath`, `_wsplitpath`](reference/splitpath-wsplitpath.md), [`_splitpath_s`, `_wsplitpath_s`](reference/splitpath-s-wsplitpath-s.md) | Parse path into components | +| [`_stat`, `_stat64`, `_stati64`, `_wstat`, `_wstat64`, `_wstati64`](reference/stat-functions.md) | Get file-status information on named file | +| [`_umask`](reference/umask.md), [`_umask_s`](reference/umask-s.md) | Set default permission mask for new files created by program | +| [`_unlink`, `_wunlink`](reference/unlink-wunlink.md) | Delete file | ## File-Handling Routines (Open File) These routines open files. -|Routine|Use| -|-------------|---------| -|[`fopen`, `_wfopen`](../c-runtime-library/reference/fopen-wfopen.md), [`fopen_s`, `_wfopen_s`](../c-runtime-library/reference/fopen-s-wfopen-s.md)|Opens a file and returns a pointer to the open file.| -|[`_fsopen`, `_wfsopen`](../c-runtime-library/reference/fsopen-wfsopen.md)|Open a stream with file sharing and returns a pointer to the open file.| -|[`_open`, `_wopen`](../c-runtime-library/reference/open-wopen.md)|Opens a file and returns a file descriptor to the opened file.| -|[`_sopen`, `_wsopen`](../c-runtime-library/reference/sopen-wsopen.md), [`_sopen_s`, `_wsopen_s`](../c-runtime-library/reference/sopen-s-wsopen-s.md)|Open a file with file sharing and returns a file descriptor to the open file.| -|[`_pipe`](../c-runtime-library/reference/pipe.md)|Creates a pipe for reading and writing.| -|[`freopen`, `_wfreopen`](../c-runtime-library/reference/freopen-wfreopen.md), [`freopen_s`, `_wfreopen_s`](../c-runtime-library/reference/freopen-s-wfreopen-s.md)|Reassign a file pointer.| +| Routine | Use | +|---|---| +| [`fopen`, `_wfopen`](reference/fopen-wfopen.md), [`fopen_s`, `_wfopen_s`](reference/fopen-s-wfopen-s.md) | Opens a file and returns a pointer to the open file. | +| [`_fsopen`, `_wfsopen`](reference/fsopen-wfsopen.md) | Open a stream with file sharing and returns a pointer to the open file. | +| [`_open`, `_wopen`](reference/open-wopen.md) | Opens a file and returns a file descriptor to the opened file. | +| [`_sopen`, `_wsopen`](reference/sopen-wsopen.md), [`_sopen_s`, `_wsopen_s`](reference/sopen-s-wsopen-s.md) | Open a file with file sharing and returns a file descriptor to the open file. | +| [`_pipe`](reference/pipe.md) | Creates a pipe for reading and writing. | +| [`freopen`, `_wfreopen`](reference/freopen-wfreopen.md), [`freopen_s`, `_wfreopen_s`](reference/freopen-s-wfreopen-s.md) | Reassign a file pointer. | These routines provide a way to change the representation of the file between a `FILE` structure, a file descriptor, and a Win32 file handle. -|Routine|Use| -|-------------|---------| -|[`_fdopen`, `_wfdopen`](../c-runtime-library/reference/fdopen-wfdopen.md)|Associates a stream with a file that was previously opened for low-level I/O and returns a pointer to the open stream.| -|[`_fileno`](../c-runtime-library/reference/fileno.md)|Gets the file descriptor associated with a stream.| -|[`_get_osfhandle`](../c-runtime-library/reference/get-osfhandle.md)|Return operating-system file handle associated with existing C run-time file descriptor| -|[`_open_osfhandle`](../c-runtime-library/reference/open-osfhandle.md)|Associates C run-time file descriptor with an existing operating-system file handle.| +| Routine | Use | +|---|---| +| [`_fdopen`, `_wfdopen`](reference/fdopen-wfdopen.md) | Associates a stream with a file that was previously opened for low-level I/O and returns a pointer to the open stream. | +| [`_fileno`](reference/fileno.md) | Gets the file descriptor associated with a stream. | +| [`_get_osfhandle`](reference/get-osfhandle.md) | Return operating-system file handle associated with existing C run-time file descriptor | +| [`_open_osfhandle`](reference/open-osfhandle.md) | Associates C run-time file descriptor with an existing operating-system file handle. | The following Win32 functions also open files and pipes: - [`CreateFile`](/windows/win32/api/fileapi/nf-fileapi-createfilew) - - [`CreatePipe`](/windows/win32/api/namedpipeapi/nf-namedpipeapi-createpipe) - - [`CreateNamedPipe`](/windows/win32/api/winbase/nf-winbase-createnamedpipea) ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[Directory Control](../c-runtime-library/directory-control.md)
-[System Calls](../c-runtime-library/system-calls.md)
+[Universal C runtime routines by category](run-time-routines-by-category.md)\ +[Directory control](directory-control.md)\ +[System calls](system-calls.md) diff --git a/docs/c-runtime-library/file-permission-constants.md b/docs/c-runtime-library/file-permission-constants.md index 2e82e29c601..cf520324849 100644 --- a/docs/c-runtime-library/file-permission-constants.md +++ b/docs/c-runtime-library/file-permission-constants.md @@ -5,11 +5,11 @@ ms.date: "11/04/2016" helpviewer_keywords: ["S_IWRITE constant", "constants [C++], file attributes", "S_IREAD constant", "file permissions [C++]", "_S_IWRITE constant", "_S_IREAD constant"] ms.assetid: 593cad33-31d1-44d2-8941-8af7d210c88c --- -# File Permission Constants +# File permission constants ## Syntax -``` +```C #include ``` @@ -19,24 +19,24 @@ One of these constants is required when `_O_CREAT` (`_open`, `_sopen`) is specif The `pmode` argument specifies the file's permission settings as follows. -|Constant|Meaning| -|--------------|-------------| -|`_S_IREAD`|Reading permitted| -|`_S_IWRITE`|Writing permitted| -|`_S_IREAD | _S_IWRITE`|Reading and writing permitted| +| Constant | Meaning | +|---|---| +| `_S_IREAD` | Reading permitted | +| `_S_IWRITE` | Writing permitted | +| `_S_IREAD | _S_IWRITE` | Reading and writing permitted | When used as the `pmode` argument for `_umask`, the manifest constant sets the permission setting, as follows. -|Constant|Meaning| -|--------------|-------------| -|`_S_IREAD`|Writing not permitted (file is read-only)| -|`_S_IWRITE`|Reading not permitted (file is write-only)| -|`_S_IREAD | _S_IWRITE`|Neither reading nor writing permitted| +| Constant | Meaning | +|---|---| +| `_S_IREAD` | Writing not permitted (file is read-only) | +| `_S_IWRITE` | Reading not permitted (file is write-only) | +| `_S_IREAD | _S_IWRITE` | Both reading and writing not permitted | ## See also -[_open, _wopen](../c-runtime-library/reference/open-wopen.md)
-[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)
-[_umask](../c-runtime-library/reference/umask.md)
-[Standard Types](../c-runtime-library/standard-types.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_open`, `_wopen`](./reference/open-wopen.md)\ +[`_sopen`, `_wsopen`](./reference/sopen-wsopen.md)\ +[`_umask`](./reference/umask.md)\ +[Standard types](./standard-types.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-read-write-access-constants.md b/docs/c-runtime-library/file-read-write-access-constants.md index 61bd1908038..ebb65e68dd4 100644 --- a/docs/c-runtime-library/file-read-write-access-constants.md +++ b/docs/c-runtime-library/file-read-write-access-constants.md @@ -5,36 +5,36 @@ ms.date: "11/04/2016" helpviewer_keywords: ["read/write access constants", "write access constants", "access constants for file read/write", "constants [C++], file attributes", "file read/write access constants"] ms.assetid: 56cd1d22-39a5-4fcf-bea2-7046d249e8ee --- -# File Read/Write Access Constants +# File read/write access constants ## Syntax -``` +```C #include ``` ## Remarks -These constants specify the access type ("a", "r", or "w") requested for the file. Both the [translation mode](../c-runtime-library/file-translation-constants.md) ("b" or "t") and the [commit-to-disk mode](../c-runtime-library/commit-to-disk-constants.md) ("c" or "n") can be specified with the type of access. +These constants specify the access type ("a", "r", or "w") requested for the file. Both the [translation mode](./file-translation-constants.md) ("b" or "t") and the [commit-to-disk mode](./commit-to-disk-constants.md) ("c" or "n") can be specified with the type of access. The access types are described in this table: -|Access type|Description| -|----------|----------------| -|**"r"**|Opens for reading. If the file does not exist or cannot be found, the call to open the file fails.| -|**"w"**|Opens an empty file for writing. If the given file exists, its contents are destroyed.| -|**"a"**|Opens for writing at the end of the file (appending); creates the file first if it does not exist. All write operations occur at the end of the file. Although the file pointer can be repositioned using `fseek` or `rewind`, it is always moved back to the end of the file before any write operation is carried out. | -|**"r+"**|Opens for both reading and writing. If the file does not exist or cannot be found, the call to open the file fails.| -|**"w+"**|Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed.| -|**"a+"**|The same as **"a"** but also allows reading.| +| Access type | Description | +|---|---| +| **"`r`"** | Opens for reading. If the file doesn't exist or can't be found, the call to open the file fails. | +| **"`w`"** | Opens an empty file for writing. If the given file exists, its contents are destroyed. | +| **"`a`"** | Opens for writing at the end of the file (appending); creates the file first if it doesn't exist. All write operations occur at the end of the file. Although the file pointer can be repositioned using `fseek` or `rewind`, it's always moved back to the end of the file before any write operation is carried out. | +| **"`r+`"** | Opens for both reading and writing. If the file doesn't exist or can't be found, the call to open the file fails. | +| **"`w+`"** | Opens an empty file for both reading and writing. If the given file exists, its contents are destroyed. | +| **"`a+`"** | The same as **"`a`"** but also allows reading. | When the "r+", "w+", or "a+" type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening `fflush`, `fsetpos`, `fseek`, or `rewind` operation. The current position can be specified for the `fsetpos` or `fseek` operation. ## See also -[_fdopen, _wfdopen](../c-runtime-library/reference/fdopen-wfdopen.md)
-[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)
-[freopen, _wfreopen](../c-runtime-library/reference/freopen-wfreopen.md)
-[_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md)
-[_popen, _wpopen](../c-runtime-library/reference/popen-wpopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_fdopen`, `_wfdopen`](./reference/fdopen-wfdopen.md)\ +[`fopen`, `_wfopen`](./reference/fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](./reference/freopen-wfreopen.md)\ +[`_fsopen`, `_wfsopen`](./reference/fsopen-wfsopen.md)\ +[`_popen`, `_wpopen`](./reference/popen-wpopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/file-translation-constants.md b/docs/c-runtime-library/file-translation-constants.md index 92f8263ea70..74ecd23f242 100644 --- a/docs/c-runtime-library/file-translation-constants.md +++ b/docs/c-runtime-library/file-translation-constants.md @@ -5,11 +5,11 @@ ms.date: "11/04/2016" helpviewer_keywords: ["translation constants", "file translation [C++], constants", "translation, file translation constants", "translation, constants", "constants [C++], file translation mode", "file translation [C++]"] ms.assetid: 49b13bf3-442e-4d19-878b-bd1029fa666a --- -# File Translation Constants +# File translation constants ## Syntax -``` +```C #include ``` @@ -21,7 +21,7 @@ The translation modes are as follows: - **t** - Opens in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input, and LF characters are translated into CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or reading and writing, `fopen` checks for CTRL+Z at the end of the file and removes it, if possible. This is done because using the `fseek` and `ftell` functions to move within a file ending with CTRL+Z may cause `fseek` to behave improperly near the end of the file. + Opens in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into single line feeds (LF) on input, and LF characters are translated into CR-LF combinations on output. Also, CTRL+Z is interpreted as an end-of-file character on input. In files opened for reading or reading and writing, `fopen` checks for CTRL+Z at the end of the file and removes it, if possible. It's removed because using the `fseek` and `ftell` functions to move within a file ending with CTRL+Z may cause `fseek` to behave improperly near the end of the file. > [!NOTE] > The **t** option is not part of the ANSI standard for `fopen` and `freopen`. It is a Microsoft extension and should not be used where ANSI portability is desired. @@ -30,12 +30,12 @@ The translation modes are as follows: Opens in binary (untranslated) mode. The above translations are suppressed. -If **t** or **b** is not given in *mode*, the translation mode is defined by the default-mode variable [_fmode](../c-runtime-library/fmode.md). For more information about using text and binary modes, see [Text and Binary Mode File I/O](../c-runtime-library/text-and-binary-mode-file-i-o.md). +If **t** or **b** isn't given in *`mode`*, the translation mode is defined by the default-mode variable [`_fmode`](./fmode.md). For more information about using text and binary modes, see [Text and binary mode file I/O](./text-and-binary-mode-file-i-o.md). ## See also -[_fdopen, _wfdopen](../c-runtime-library/reference/fdopen-wfdopen.md)
-[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)
-[freopen, _wfreopen](../c-runtime-library/reference/freopen-wfreopen.md)
-[_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_fdopen`, `_wfdopen`](./reference/fdopen-wfdopen.md)\ +[`fopen`, `_wfopen`](./reference/fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](./reference/freopen-wfreopen.md)\ +[`_fsopen`, `_wfsopen`](./reference/fsopen-wfsopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/filename-max.md b/docs/c-runtime-library/filename-max.md index 15923f7b07c..81d0ddb93ac 100644 --- a/docs/c-runtime-library/filename-max.md +++ b/docs/c-runtime-library/filename-max.md @@ -2,21 +2,21 @@ description: "Learn more about: FILENAME_MAX" title: "FILENAME_MAX" ms.date: "11/04/2016" -f1_keywords: ["FILENAME_MAX"] +f1_keywords: ["STDIO/FILENAME_MAX", "FILENAME_MAX"] helpviewer_keywords: ["FILENAME_MAX constant"] ms.assetid: fe368d24-3f31-42d6-859c-cbd84f446ee5 --- -# FILENAME_MAX +# `FILENAME_MAX` The maximum permissible length for a `filename` string buffer size. ## Syntax -``` +```C #include ``` ## See also -[Path Field Limits](../c-runtime-library/path-field-limits.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Path field limits](./path-field-limits.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/filename-search-functions.md b/docs/c-runtime-library/filename-search-functions.md index b3d10297dd8..fd8726e2d6c 100644 --- a/docs/c-runtime-library/filename-search-functions.md +++ b/docs/c-runtime-library/filename-search-functions.md @@ -7,15 +7,15 @@ api_type: ["DLLExport"] topic_type: ["apiref"] helpviewer_keywords: ["file names [C++], searching for", "_find function", "wfind function", "find function", "_wfind function"] --- -# Filename Search Functions +# Filename search functions These functions search for and close searches for specified file names: -- [`_findnext`, `_wfindnext`](../c-runtime-library/reference/findnext-functions.md) +- [`_findnext`, `_wfindnext`](./reference/findnext-functions.md) -- [`_findfirst`, `_wfindfirst`](../c-runtime-library/reference/findfirst-functions.md) +- [`_findfirst`, `_wfindfirst`](./reference/findfirst-functions.md) -- [`_findclose`](../c-runtime-library/reference/findclose.md) +- [`_findclose`](./reference/findclose.md) ## Remarks @@ -27,7 +27,7 @@ The functions return file information in a `_finddata_t` structure, which is def File attribute. `time_t time_create`\ -Time of file creation (`-1L` for FAT file systems). This time is stored in UTC format. To convert to the local time, use [`localtime_s`](../c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md). +Time of file creation (`-1L` for FAT file systems). This time is stored in UTC format. To convert to the local time, use [`localtime_s`](./reference/localtime-s-localtime32-s-localtime64-s.md). `time_t time_access`\ Time of the last file access (`-1L` for FAT file systems). This time is stored in UTC format. To convert to the local time, use `localtime_s`. @@ -45,19 +45,19 @@ In file systems that don't support the creation and last access times of a file, `_MAX_PATH` is defined in `Stdlib.h` as 260 bytes. -You can’t specify target attributes (such as `_A_RDONLY`) to limit the find operation. These attributes are returned in the `attrib` field of the `_finddata_t` structure and can have the following values (defined in `IO.h`). Users shouldn't rely on these being the only values possible for the `attrib` field. +You can't specify target attributes (such as `_A_RDONLY`) to limit the find operation. These attributes are returned in the `attrib` field of the `_finddata_t` structure and can have the following values (defined in `IO.h`). Users shouldn't rely on these attributes being the only values possible for the `attrib` field. `_A_ARCH`\ Archive. Set whenever the file is changed and cleared by the **`BACKUP`** command. Value: `0x20`. `_A_HIDDEN`\ -Hidden file. Not generally seen with the `DIR` command, unless you use the **`/AH`** option. Returns information about normal files and files that have this attribute. Value: `0x02`. +Hidden file. Not often seen with the `DIR` command, unless you use the **`/AH`** option. Returns information about normal files and files that have this attribute. Value: `0x02`. `_A_NORMAL`\ Normal. File has no other attributes set and can be read or written to without restriction. Value: `0x00`. `_A_RDONLY`\ -Read-only. File can’t be opened for writing and a file that has the same name can’t be created. Value: `0x01`. +Read-only. File can't be opened for writing and a file that has the same name can't be created. Value: `0x01`. `_A_SUBDIR`\ Subdirectory. Value: `0x10`. @@ -69,21 +69,21 @@ System file. Not ordinarily seen with the **`DIR`** command, unless the **`/A`** You can nest the `_find` functions. For example, if a call to `_findfirst` or `_findnext` finds the file that is a subdirectory, a new search can be initiated with another call to `_findfirst` or `_findnext`. -`_wfindfirst` and `_wfindnext` are wide-character versions of `_findfirst` and `_findnext`. The structure argument of the wide-character versions has the `_wfinddata_t` data type, which is defined in `IO.h` and in `Wchar.h`. The fields of this data type are the same as those of the `_finddata_t` data type, except that in `_wfinddata_t` the name field is of type **`wchar_t`** instead of type **`char`**. Otherwise `_wfindfirst` and `_wfindnext` behave identically to `_findfirst` and `_findnext`. +`_wfindfirst` and `_wfindnext` are wide-character versions of `_findfirst` and `_findnext`. The structure argument of the wide-character versions has the `_wfinddata_t` data type, which is defined in `IO.h` and in `Wchar.h`. The fields of this data type are the same as the fields of the `_finddata_t` data type, except that in `_wfinddata_t` the `name` field is of type **`wchar_t`** instead of type **`char`**. Otherwise, `_wfindfirst` and `_wfindnext` behave identically to `_findfirst` and `_findnext`. -`_findfirst` and `_findnext` use the 64-bit time type. If you must use the old 32-bit time type, you can define `_USE_32BIT_TIME_T`. The versions of these functions that have the `32` suffix in their names use the 32-bit time type, and those with the `64` suffix use the 64-bit time type. +`_findfirst` and `_findnext` use the 64-bit time type. If you must use the old 32-bit time type, you can define `_USE_32BIT_TIME_T`. The versions of these functions that have the `32` suffix in their names use the 32-bit time type, and the ones with the `64` suffix use the 64-bit time type. Functions `_findfirst32i64`, `_findnext32i64`, `_wfindfirst32i64`, and `_wfindnext32i64` also behave identically to the 32-bit time type versions of these functions except they use and return 64-bit file lengths. Functions `_findfirst64i32`, `_findnext64i32`, `_wfindfirst64i32`, and `_wfindnext64i32` use the 64-bit time type but use 32-bit file lengths. These functions use appropriate variations of the `_finddata_t` type in which the fields have different types for the time and the file size. `_finddata_t` is actually a macro that evaluates to `_finddata64i32_t` (or `_finddata32_t` if `_USE_32BIT_TIME_T` is defined). The following table summarizes the variations on `_finddata_t`: -|Structure|Time type|File size type| -|---------------|---------------|--------------------| -|`_finddata_t`, `_wfinddata_t`|`__time64_t`|`_fsize_t`| -|`_finddata32_t`, `_wfinddata32_t`|`__time32_t`|`_fsize_t`| -|`__finddata64_t`, `__wfinddata64_t`|`__time64_t`|**`__int64`**| -|`_finddata32i64_t`, `_wfinddata32i64_t`|`__time32_t`|**`__int64`**| -|`_finddata64i32_t`, `_wfinddata64i32_t`|`__time64_t`|`_fsize_t`| +| Structure | Time type | File size type | +|---|---|---| +| `_finddata_t`, `_wfinddata_t` | `__time64_t` | `_fsize_t` | +| `_finddata32_t`, `_wfinddata32_t` | `__time32_t` | `_fsize_t` | +| `__finddata64_t`, `_wfinddata64_t` | `__time64_t` | **`__int64`** | +| `_finddata32i64_t`, `_wfinddata32i64_t` | `__time32_t` | **`__int64`** | +| `_finddata64i32_t`, `_wfinddata64i32_t` | `__time64_t` | `_fsize_t` | `_fsize_t` is a **`typedef`** for **`unsigned long`** (32 bits). @@ -139,4 +139,4 @@ N N N Y test.c Wed Feb 06 14:30:44 2002 312 ## See also -[System Calls](../c-runtime-library/system-calls.md) +[System calls](./system-calls.md) diff --git a/docs/c-runtime-library/files-and-streams.md b/docs/c-runtime-library/files-and-streams.md index 9d4ea210d19..99c256fc55a 100644 --- a/docs/c-runtime-library/files-and-streams.md +++ b/docs/c-runtime-library/files-and-streams.md @@ -2,11 +2,11 @@ title: "Files and Streams" description: "An overview of files and streams in the Microsoft C runtime library." ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["files [C++]", "streams"] ms.assetid: f61e712b-eac9-4c28-bb18-97c3786ef387 --- -# Files and Streams +# Files and streams A program communicates with the target environment by reading and writing files. A file can be: @@ -16,27 +16,27 @@ A program communicates with the target environment by reading and writing files. - A stream of bytes received from or sent to a peripheral device. -The last two items are interactive files. Files are typically the principal means by which to interact with a program. You manipulate all these kinds of files in much the same way — by calling library functions. You include the standard header STDIO.H to declare most of these functions. +The last two items are interactive files. Files are typically the principal means by which to interact with a program. You manipulate all these kinds of files in much the same way: by calling library functions. You include the standard header STDIO.H to declare most of these functions. Before you can perform many of the operations on a file, the file must be opened. Opening a file associates it with a stream, a data structure within the Standard C Library that glosses over many differences among files of various kinds. The library maintains the state of each stream in an object of type FILE. -The target environment opens three files before program startup. You can open a file by calling the library function [fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md) with two arguments. (The `fopen` function has been deprecated, use [fopen_s, _wfopen_s](../c-runtime-library/reference/fopen-s-wfopen-s.md) instead.) The first argument is a filename. The second argument is a C string that specifies: +The target environment opens three files before program startup. You can open a file by calling the library function [`fopen`, `_wfopen`](./reference/fopen-wfopen.md) with two arguments. (The `fopen` function has been deprecated, use [`fopen_s`, `_wfopen_s`](./reference/fopen-s-wfopen-s.md) instead.) The first argument is a filename. The second argument is a C string that specifies: - Whether you intend to read data from the file or write data to it or both. -- Whether you intend to generate new contents for the file (or create a file if it did not previously exist) or leave the existing contents in place. +- Whether you intend to generate new contents for the file (or create a file if it didn't previously exist) or leave the existing contents in place. - Whether writes to a file can alter existing contents or should only append bytes at the end of the file. - Whether you want to manipulate a text stream or a binary stream. -Once the file is successfully opened, you can then determine whether the stream is byte oriented (a byte stream) or wide oriented (a wide stream). A stream is initially unbound. Calling certain functions to operate on the stream makes it byte oriented, while certain other functions make it wide oriented. Once established, a stream maintains its orientation until it is closed by a call to [fclose](../c-runtime-library/reference/fclose-fcloseall.md) or [freopen](../c-runtime-library/reference/freopen-wfreopen.md). +Once the file is successfully opened, you can then determine whether the stream is byte oriented (a byte stream) or wide oriented (a wide stream). A stream is initially unbound. Calling certain functions to operate on the stream makes it byte oriented, while certain other functions make it wide oriented. Once established, a stream maintains its orientation until it's closed by a call to [`fclose`](./reference/fclose-fcloseall.md) or [`freopen`](./reference/freopen-wfreopen.md). © 1989-2001 by P.J. Plauger and Jim Brodie. All rights reserved. ## See also -[Text and Binary Streams](../c-runtime-library/text-and-binary-streams.md)
-[Byte and Wide Streams](../c-runtime-library/byte-and-wide-streams.md)
-[Controlling Streams](../c-runtime-library/controlling-streams.md)
-[Stream States](../c-runtime-library/stream-states.md) +[Text and binary streams](./text-and-binary-streams.md)\ +[Byte and wide streams](./byte-and-wide-streams.md)\ +[Controlling streams](./controlling-streams.md)\ +[Stream states](./stream-states.md) diff --git a/docs/c-runtime-library/find-memory-leaks-using-the-crt-library.md b/docs/c-runtime-library/find-memory-leaks-using-the-crt-library.md new file mode 100644 index 00000000000..1e78d27ce57 --- /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 3fdee3416f6..7f4ac7bc98c 100644 --- a/docs/c-runtime-library/floating-point-support.md +++ b/docs/c-runtime-library/floating-point-support.md @@ -7,127 +7,129 @@ helpviewer_keywords: ["floating-point numbers, math routines", "math routines", --- # Math and floating-point support -The Universal C Runtime library (UCRT) provides many integral and floating-point math library functions, including all of those required by ISO C99. The floating-point functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 ulp of the correctly rounded result, though there may be cases where there is greater inaccuracy. +The Universal C Runtime library (UCRT) provides many integral and floating-point math library functions, including all of the functions required by ISO C99. The floating-point functions are implemented to balance performance with correctness. Because producing the correctly rounded result may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 ULP (unit of least precision) of the correctly rounded result, though there may be cases where there's greater inaccuracy. For ISO C Standard 11 (C11) and later, the `` header, in addition to including `` and ``, provides macros that invoke a corresponding math function based on the types of the parameters. See [Type-generic math](tgmath.md) for details. -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. ## Supported math and floating-point routines -|Routine|Use| -|-|-| -[`abs`, `labs`, `llabs`, `_abs64`](../c-runtime-library/reference/abs-labs-llabs-abs64.md)|Computes the absolute value of an integer type -[`acos`, `acosf`, `acosl`](../c-runtime-library/reference/acos-acosf-acosl.md)|Computes the arc cosine -[`acosh`, `acoshf`, `acoshl`](../c-runtime-library/reference/acosh-acoshf-acoshl.md)|Computes the hyperbolic arc cosine -[`asin`, `asinf`, `asinl`](../c-runtime-library/reference/asin-asinf-asinl.md)|Computes the arc sine -[`asinh`, `asinhf`, `asinhl`](../c-runtime-library/reference/asinh-asinhf-asinhl.md)|Computes the hyperbolic arc sine -[`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)|Computes the arc tangent -[`atanh`, `atanhf`, `atanhl`](../c-runtime-library/reference/atanh-atanhf-atanhl.md)|Computes the hyperbolic arc tangent -[`_atodbl`, `_atodbl_l`](../c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)|Converts a locale-specific string to a **`double`** -[`atof`, `_atof_l`](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Converts a string to a **`double`** -[`_atoflt`, `_atoflt_l`, `_atoldbl`, `_atoldbl_l`](../c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)|Converts a locale-specific string to a **`float`** or **`long double`** -[`cbrt`, `cbrtf`, `cbrtl`](../c-runtime-library/reference/cbrt-cbrtf-cbrtl.md)|Computes the cube root -[`ceil`, `ceilf`, `ceill`](../c-runtime-library/reference/ceil-ceilf-ceill.md)|Computes the ceiling -[`_chgsign`, `_chgsignf`, `_chgsignl`](../c-runtime-library/reference/chgsign-chgsignf-chgsignl.md)|Computes the additive inverse -[`_clear87`, `_clearfp`](../c-runtime-library/reference/clear87-clearfp.md)|Gets and clears the floating-point status register -[`_control87`, `\__control87_2`, `_controlfp`](../c-runtime-library/reference/control87-controlfp-control87-2.md)|Gets and sets the floating-point control word -[`_controlfp_s`](../c-runtime-library/reference/controlfp-s.md)|Secure version of **`_controlfp`** -[`copysign`, `copysignf`, `copysignl`, `_copysign`, `_copysignf`, `_copysignl`](../c-runtime-library/reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md)|Returns a value that has the magnitude of one argument and the sign of another -[`cos`, `cosf`, `cosl`](../c-runtime-library/reference/cos-cosf-cosl.md)|Computes the sine -[`cosh`, `coshf`, `coshl`](../c-runtime-library/reference/cosh-coshf-coshl.md)|Computes the hyperbolic sine -[`div`, `ldiv`, `lldiv`](../c-runtime-library/reference/div.md)|Computes the quotient and the remainder of two integer values -[`_ecvt`](../c-runtime-library/reference/ecvt.md), [`ecvt`](../c-runtime-library/reference/posix-ecvt.md)|Converts a **`double`** to a string -[`_ecvt_s`](../c-runtime-library/reference/ecvt-s.md)|Secure version of **`_ecvt`** -[`erf`, `erff`, `erfl`](../c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md)|Computes the error function -[`erfc`, `erfcf`, `erfcl`](../c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md)|Computes the complementary error function -[`exp`, `expf`, `expl`](../c-runtime-library/reference/exp-expf.md)|Computes the exponential *e*x -[`exp2`, `exp2f`, `exp2l`](../c-runtime-library/reference/exp2-exp2f-exp2l.md)|Computes the exponential 2x -[`expm1`, `expm1f`, `expm1l`](../c-runtime-library/reference/expm1-expm1f-expm1l.md)|Computes *e*x-1 -[`fabs`, `fabsf`, `fabsl`](../c-runtime-library/reference/fabs-fabsf-fabsl.md)|Computes the absolute value of a floating-point type -[`_fcvt`](../c-runtime-library/reference/fcvt.md), [`fcvt`](../c-runtime-library/reference/posix-fcvt.md)|Converts a floating-point number to a string -[_fcvt_s](../c-runtime-library/reference/fcvt-s.md)|Secure version of **`_fcvt`** -[`fdim`, `fdimf`, `fdiml`](../c-runtime-library/reference/fdim-fdimf-fdiml.md)|Determines the positive difference between two values -[`feclearexcept`](../c-runtime-library/reference/feclearexcept1.md)|Clears specified floating-point exceptions -[`fegetenv`](../c-runtime-library/reference/fegetenv1.md)|Stores the current floating-point environment -[`fegetexceptflag`](../c-runtime-library/reference/fegetexceptflag2.md)|Gets the specified floating-point exception status -[`fegetround`](../c-runtime-library/reference/fegetround-fesetround2.md)|Gets the floating-point rounding mode -[`feholdexcept`](../c-runtime-library/reference/feholdexcept2.md)|Sets non-stop floating-point exception mode -[`feraiseexcept`](../c-runtime-library/reference/feraiseexcept.md)|Raises the specified floating-point exceptions -[`fesetenv`](../c-runtime-library/reference/fesetenv1.md)|Sets the current floating-point environment -[`fesetexceptflag`](../c-runtime-library/reference/fesetexceptflag2.md)|Sets the specified floating-point status flags -[`fesetround`](../c-runtime-library/reference/fegetround-fesetround2.md)|Sets the specified floating-point rounding mode -[`fetestexcept`](../c-runtime-library/reference/fetestexcept1.md)|Determines which floating-point exception status flags are set -[`feupdateenv`](../c-runtime-library/reference/feupdateenv.md)|Restores a floating-point environment then raises previous exceptions -[`floor`, `floorf`, `floorl`](../c-runtime-library/reference/floor-floorf-floorl.md)|Computes the floor -[`fma`, `fmaf`, `fmal`](../c-runtime-library/reference/fma-fmaf-fmal.md)|Computes a fused multiply-add -[`fmax`, `fmaxf`, `fmaxl`](../c-runtime-library/reference/fmax-fmaxf-fmaxl.md)|Computes the maximum of the arguments -[`fmin`, `fminf`, `fminl`](../c-runtime-library/reference/fmin-fminf-fminl.md)|Computes the minimum of the arguments -[`fmod`, `fmodf`, `fmodl`](../c-runtime-library/reference/fmod-fmodf.md)|Computes the floating-point remainder -[`_fpclass`, `_fpclassf`](../c-runtime-library/reference/fpclass-fpclassf.md)|Returns the classification of a floating-point value -[`fpclassify`](../c-runtime-library/reference/fpclassify.md)|Returns the classification of a floating-point value -[`_fpieee_flt`](../c-runtime-library/reference/fpieee-flt.md)|Sets a handler for floating-point exceptions -[`_fpreset`](../c-runtime-library/reference/fpreset.md)|Resets the floating-point environment -[`frexp`, `frexpf`, `frexpl`](../c-runtime-library/reference/frexp.md)|Gets the mantissa and exponent of a floating-point number -[`_gcvt`](../c-runtime-library/reference/gcvt.md), [`gcvt`](../c-runtime-library/reference/posix-gcvt.md)|Converts a floating-point number to a string -[`_gcvt_s`](../c-runtime-library/reference/gcvt-s.md)|Secure version of **`_gcvt`** -[`_get_FMA3_enable`, `_set_FMA3_enable`](../c-runtime-library/reference/get-fma3-enable-set-fma3-enable.md)|Gets or sets a flag for use of FMA3 instructions on x64 -[`hypot`, `hypotf`, `hypotl`, `_hypot`, `_hypotf`, `_hypotl`](../c-runtime-library/reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md)|Computes the hypotenuse -[`ilogb`, `ilogbf`, `ilogbl`](../c-runtime-library/reference/ilogb-ilogbf-ilogbl2.md)|Computes the integer base-2 exponent -[`imaxabs`](../c-runtime-library/reference/imaxabs.md)|Computes the absolute value of an integer type -[`imaxdiv`](../c-runtime-library/reference/imaxdiv.md)|Computes the quotient and the remainder of two integer values -[`isfinite`, `_finite`, `_finitef`](../c-runtime-library/reference/finite-finitef.md)|Determines whether a value is finite -[`isgreater`, `isgreaterequal`, `isless`, `islessequal`, `islessgreater`, `isunordered`](../c-runtime-library/reference/floating-point-ordering.md)|Compare the order of two floating point values -[`isinf`](../c-runtime-library/reference/isinf.md)|Determines whether a floating-point value is infinite -[`isnan`, `_isnan`, `_isnanf`](../c-runtime-library/reference/isnan-isnan-isnanf.md)|Tests a floating-point value for NaN -[`isnormal`](../c-runtime-library/reference/isnormal.md)|Tests whether a floating-point value is both finite and not subnormal -[`_j0`, `_j1`, `_jn`](../c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md)|Computes the Bessel function -[`ldexp`, `ldexpf`, `ldexpl`](../c-runtime-library/reference/ldexp.md)|Computes x*2n -[`lgamma`, `lgammaf`, `lgammal`](../c-runtime-library/reference/lgamma-lgammaf-lgammal.md)|Computes the natural logarithm of the absolute value of the gamma function -[`llrint`, `llrintf`, `llrintl`](../c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)|Rounds a floating-point value to the nearest **`long long`** value -[`llround`, `llroundf`, `llroundl`](../c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md)|Rounds a floating-point value to the nearest **`long long`** value -[`log`, `logf`, `logl`, `log10`, `log10f`, `log10l`](../c-runtime-library/reference/log-logf-log10-log10f.md)|Computes the natural or base-10 logarithm -[`log1p`, `log1pf`, `log1pl`](../c-runtime-library/reference/log1p-log1pf-log1pl2.md)|Computes the natural logarithm of 1+x -[`log2`, `log2f`, `log2l`](../c-runtime-library/reference/log2-log2f-log2l.md)|Computes the base-2 logarithm -[`logb`, `logbf`, `logbl`, `_logb`, `_logbf`](../c-runtime-library/reference/logb-logbf-logbl-logb-logbf.md)|Returns the exponent of a floating-point value -[`lrint`, `lrintf`, `lrintl`](../c-runtime-library/reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)|Rounds a floating-point value to the nearest **`long`** value -[`_lrotl`, `_lrotr`](../c-runtime-library/reference/lrotl-lrotr.md)|Rotates an integer value left or right -[`lround`, `lroundf`, `lroundl`](../c-runtime-library/reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md)|Rounds a floating-point value to the nearest **`long`** value -[`_matherr`](../c-runtime-library/reference/matherr.md)|The default math error handler -[`__max`](../c-runtime-library/reference/max.md)|Macro that returns the larger of two values -[`__min`](../c-runtime-library/reference/min.md)|Macro that returns the smaller of two values -[`modf`, `modff`, `modfl`](../c-runtime-library/reference/modf-modff-modfl.md)|Splits a floating-point value into fractional and integer parts -[`nan`, `nanf`, `nanl`](../c-runtime-library/reference/nan-nanf-nanl.md)|Returns a quiet NaN value -[`nearbyint`, `nearbyintf`, `nearbyintl`](../c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md)|Returns the rounded value -[`nextafter`, `nextafterf`, `nextafterl`, `_nextafter`, `_nextafterf`](../c-runtime-library/reference/nextafter-functions.md)|Returns the next representable floating-point value -[`nexttoward`, `nexttowardf`, `nexttowardl`](../c-runtime-library/reference/nextafter-functions.md)|Returns the next representable floating-point value -[`pow`, `powf`, `powl`](../c-runtime-library/reference/pow-powf-powl.md)|Returns the value of *x**y* -[`remainder`, `remainderf`, `remainderl`](../c-runtime-library/reference/remainder-remainderf-remainderl.md)|Computes the remainder of the quotient of two floating-point values -[`remquo`, `remquof`, `remquol`](../c-runtime-library/reference/remquo-remquof-remquol.md)|Computes the remainder of two integer values -[`rint`, `rintf`, `rintl`](../c-runtime-library/reference/rint-rintf-rintl.md)|Rounds a floating-point value -[`_rotl`, `_rotl64`, `_rotr`, `_rotr64`](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md)|Rotates bits in integer types -[`round`, `roundf`, `roundl`](../c-runtime-library/reference/round-roundf-roundl.md)|Rounds a floating-point value -[`_scalb`, `_scalbf`](../c-runtime-library/reference/scalb.md)|Scales argument by a power of 2 -[`scalbn`, `scalbnf`, `scalbnl`, `scalbln`, `scalblnf`, `scalblnl`](../c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md)|Multiplies a floating-point number by an integral power of **`FLT_RADIX`** -[`_set_controlfp`](../c-runtime-library/reference/set-controlfp.md)|Sets the floating-point control word -[`_set_SSE2_enable`](../c-runtime-library/reference/set-sse2-enable.md)|Enables or disables SSE2 instructions -[`signbit`](../c-runtime-library/reference/signbit.md)|Tests the sign bit of a floating-point value -[`sin`, `sinf`, `sinl`](../c-runtime-library/reference/sin-sinf-sinl.md)|Computes the sine -[`sinh`, `sinhf`, `sinhl`](../c-runtime-library/reference/sinh-sinhf-sinhl.md)|Computes the hyperbolic sine -[`sqrt`, `sqrtf`, `sqrtl`](../c-runtime-library/reference/sqrt-sqrtf-sqrtl.md)|Computes the square root -[`_status87`, `_statusfp`, `_statusfp2`](../c-runtime-library/reference/status87-statusfp-statusfp2.md)|Gets the floating-point status word -[`strtof`, `_strtof_l`](../c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md)|Converts a string to a **`float`** -[`strtold`, `_strtold_l`](../c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md)|Converts a string to a **`long double`** -[`tan`, `tanf`, `tanl`](../c-runtime-library/reference/tan-tanf-tanl.md)|Computes the tangent -[`tanh`, `tanhf`, `tanhl`](../c-runtime-library/reference/tanh-tanhf-tanhl.md)|Computes the hyperbolic tangent -[`tgamma`, `tgammaf`, `tgammal`](../c-runtime-library/reference/tgamma-tgammaf-tgammal.md)|Computes the gamma function -[`trunc`, `truncf`, `truncl`](../c-runtime-library/reference/trunc-truncf-truncl.md)|Truncates the fractional part -[`_wtof`, `_wtof_l`](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Converts a wide string to a **`double`** -[`_y0`, `_y1`, `_yn`](../c-runtime-library/reference/bessel-functions-j0-j1-jn-y0-y1-yn.md)|Computes the Bessel function +| Routine | Use | +|---|---| +| [`abs`, `labs`, `llabs`, `_abs64`](./reference/abs-labs-llabs-abs64.md) | Computes the absolute value of an integer type | +| [`acos`, `acosf`, `acosl`](./reference/acos-acosf-acosl.md) | Computes the arc cosine | +| [`acosh`, `acoshf`, `acoshl`](./reference/acosh-acoshf-acoshl.md) | Computes the hyperbolic arc cosine | +| [`asin`, `asinf`, `asinl`](./reference/asin-asinf-asinl.md) | Computes the arc sine | +| [`asinh`, `asinhf`, `asinhl`](./reference/asinh-asinhf-asinhl.md) | Computes the hyperbolic arc sine | +| [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](./reference/atan-atanf-atanl-atan2-atan2f-atan2l.md) | Computes the arc tangent | +| [`atanh`, `atanhf`, `atanhl`](./reference/atanh-atanhf-atanhl.md) | Computes the hyperbolic arc tangent | +| [`_atodbl`, `_atodbl_l`](./reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) | Converts a locale-specific string to a **`double`** | +| [`atof`, `_atof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Converts a string to a **`double`** | +| [`_atoflt`, `_atoflt_l`, `_atoldbl`, `_atoldbl_l`](./reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) | Converts a locale-specific string to a **`float`** or **`long double`** | +| [`cbrt`, `cbrtf`, `cbrtl`](./reference/cbrt-cbrtf-cbrtl.md) | Computes the cube root | +| [`ceil`, `ceilf`, `ceill`](./reference/ceil-ceilf-ceill.md) | Computes the ceiling | +| [`_chgsign`, `_chgsignf`, `_chgsignl`](./reference/chgsign-chgsignf-chgsignl.md) | Computes the additive inverse | +| [`_clear87`, `_clearfp`](./reference/clear87-clearfp.md) | Gets and clears the floating-point status register | +| [`_control87`, `_controlfp`, `__control87_2`](./reference/control87-controlfp-control87-2.md) | Gets and sets the floating-point control word | +| [`_controlfp_s`](./reference/controlfp-s.md) | Secure version of **`_controlfp`** | +| [`copysign`, `copysignf`, `copysignl`, `_copysign`, `_copysignf`, `_copysignl`](./reference/copysign-copysignf-copysignl-copysign-copysignf-copysignl.md) | Returns a value that has the magnitude of one argument and the sign of another | +| [`cos`, `cosf`, `cosl`](./reference/cos-cosf-cosl.md) | Computes the sine | +| [`cosh`, `coshf`, `coshl`](./reference/cosh-coshf-coshl.md) | Computes the hyperbolic sine | +| [`div`, `ldiv`, `lldiv`](./reference/div.md) | Computes the quotient and the remainder of two integer values | +| [`_ecvt`](./reference/ecvt.md), [`ecvt`](./reference/posix-ecvt.md) | Converts a **`double`** to a string | +| [`_ecvt_s`](./reference/ecvt-s.md) | Secure version of **`_ecvt`** | +| [`erf`, `erff`, `erfl`](./reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | Computes the error function | +| [`erfc`, `erfcf`, `erfcl`](./reference/erf-erff-erfl-erfc-erfcf-erfcl.md) | Computes the complementary error function | +| [`exp`, `expf`, `expl`](./reference/exp-expf.md) | Computes the exponential *e*x | +| [`exp2`, `exp2f`, `exp2l`](./reference/exp2-exp2f-exp2l.md) | Computes the exponential 2x | +| [`expm1`, `expm1f`, `expm1l`](./reference/expm1-expm1f-expm1l.md) | Computes *e*x-1 | +| [`fabs`, `fabsf`, `fabsl`](./reference/fabs-fabsf-fabsl.md) | Computes the absolute value of a floating-point type | +| [`_fcvt`](./reference/fcvt.md), [`fcvt`](./reference/posix-fcvt.md) | Converts a floating-point number to a string | +| [`_fcvt_s`](./reference/fcvt-s.md) | Secure version of **`_fcvt`** | +| [`fdim`, `fdimf`, `fdiml`](./reference/fdim-fdimf-fdiml.md) | Determines the positive difference between two values | +| [`feclearexcept`](./reference/feclearexcept1.md) | Clears specified floating-point exceptions | +| [`fegetenv`](./reference/fegetenv1.md) | Stores the current floating-point environment | +| [`fegetexceptflag`](./reference/fegetexceptflag2.md) | Gets the specified floating-point exception status | +| [`fegetround`](./reference/fegetround-fesetround2.md) | Gets the floating-point rounding mode | +| [`feholdexcept`](./reference/feholdexcept2.md) | Sets non-stop floating-point exception mode | +| [`feraiseexcept`](./reference/feraiseexcept.md) | Raises the specified floating-point exceptions | +| [`fesetenv`](./reference/fesetenv1.md) | Sets the current floating-point environment | +| [`fesetexceptflag`](./reference/fesetexceptflag2.md) | Sets the specified floating-point status flags | +| [`fesetround`](./reference/fegetround-fesetround2.md) | Sets the specified floating-point rounding mode | +| [`fetestexcept`](./reference/fetestexcept1.md) | Determines which floating-point exception status flags are set | +| [`feupdateenv`](./reference/feupdateenv.md) | Restores a floating-point environment then raises previous exceptions | +| [`floor`, `floorf`, `floorl`](./reference/floor-floorf-floorl.md) | Computes the floor | +| [`fma`, `fmaf`, `fmal`](./reference/fma-fmaf-fmal.md) | Computes a fused multiply-add | +| [`fmax`, `fmaxf`, `fmaxl`](./reference/fmax-fmaxf-fmaxl.md) | Computes the maximum of the arguments | +| [`fmin`, `fminf`, `fminl`](./reference/fmin-fminf-fminl.md) | Computes the minimum of the arguments | +| [`fmod`, `fmodf`, `fmodl`](./reference/fmod-fmodf.md) | Computes the floating-point remainder | +| [`_fpclass`, `_fpclassf`](./reference/fpclass-fpclassf.md) | Returns the classification of a floating-point value | +| [`fpclassify`](./reference/fpclassify.md) | Returns the classification of a floating-point value | +| [`_fpieee_flt`](./reference/fpieee-flt.md) | Sets a handler for floating-point exceptions | +| [`_fpreset`](./reference/fpreset.md) | Resets the floating-point environment | +| [`frexp`, `frexpf`, `frexpl`](./reference/frexp.md) | Gets the mantissa and exponent of a floating-point number | +| [`_gcvt`](./reference/gcvt.md), [`gcvt`](./reference/posix-gcvt.md) | Converts a floating-point number to a string | +| [`_gcvt_s`](./reference/gcvt-s.md) | Secure version of **`_gcvt`** | +| [`_get_FMA3_enable`, `_set_FMA3_enable`](./reference/get-fma3-enable-set-fma3-enable.md) | Gets or sets a flag for use of FMA3 instructions on x64 | +| [`hypot`, `hypotf`, `hypotl`, `_hypot`, `_hypotf`, `_hypotl`](./reference/hypot-hypotf-hypotl-hypot-hypotf-hypotl.md) | Computes the hypotenuse | +| [`ilogb`, `ilogbf`, `ilogbl`](./reference/ilogb-ilogbf-ilogbl2.md) | Computes the integer base-2 exponent | +| [`imaxabs`](./reference/imaxabs.md) | Computes the absolute value of an integer type | +| [`imaxdiv`](./reference/imaxdiv.md) | Computes the quotient and the remainder of two integer values | +| [`isfinite`, `_finite`, `_finitef`](./reference/finite-finitef.md) | Determines whether a value is finite | +| [`isgreater`, `isgreaterequal`, `isless`, `islessequal`, `islessgreater`, `isunordered`](./reference/floating-point-ordering.md) | Compare the order of two floating-point values | +| [`isinf`](./reference/isinf.md) | Determines whether a floating-point value is infinite | +| [`isnan`, `_isnan`, `_isnanf`](./reference/isnan-isnan-isnanf.md) | Tests a floating-point value for NaN | +| [`isnormal`](./reference/isnormal.md) | Tests whether a floating-point value is both finite and not subnormal | +| [`_j0`, `_j1`, `_jn`](./reference/bessel-functions-j0-j1-jn-y0-y1-yn.md) | Computes the Bessel function | +| [`ldexp`, `ldexpf`, `ldexpl`](./reference/ldexp.md) | Computes x*2n | +| [`lgamma`, `lgammaf`, `lgammal`](./reference/lgamma-lgammaf-lgammal.md) | Computes the natural logarithm of the absolute value of the gamma function | +| [`llrint`, `llrintf`, `llrintl`](./reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | Rounds a floating-point value to the nearest **`long long`** value | +| [`llround`, `llroundf`, `llroundl`](./reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | Rounds a floating-point value to the nearest **`long long`** value | +| [`log`, `logf`, `logl`, `log10`, `log10f`, `log10l`](./reference/log-logf-log10-log10f.md) | Computes the natural or base-10 logarithm | +| [`log1p`, `log1pf`, `log1pl`](./reference/log1p-log1pf-log1pl2.md) | Computes the natural logarithm of 1+x | +| [`log2`, `log2f`, `log2l`](./reference/log2-log2f-log2l.md) | Computes the base-2 logarithm | +| [`logb`, `logbf`, `logbl`, `_logb`, `_logbf`](./reference/logb-logbf-logbl-logb-logbf.md) | Returns the exponent of a floating-point value | +| [`lrint`, `lrintf`, `lrintl`](./reference/lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) | Rounds a floating-point value to the nearest **`long`** value | +| [`_lrotl`, `_lrotr`](./reference/lrotl-lrotr.md) | Rotates an integer value left or right | +| [`lround`, `lroundf`, `lroundl`](./reference/lround-lroundf-lroundl-llround-llroundf-llroundl.md) | Rounds a floating-point value to the nearest **`long`** value | +| [`_matherr`](./reference/matherr.md) | The default math error handler | +| [`__max`](./reference/max.md) | Macro that returns the larger of two values | +| [`__min`](./reference/min.md) | Macro that returns the smaller of two values | +| [`modf`, `modff`, `modfl`](./reference/modf-modff-modfl.md) | Splits a floating-point value into fractional and integer parts | +| [`nan`, `nanf`, `nanl`](./reference/nan-nanf-nanl.md) | Returns a quiet NaN value | +| [`nearbyint`, `nearbyintf`, `nearbyintl`](./reference/nearbyint-nearbyintf-nearbyintl1.md) | Returns the rounded value | +| [`nextafter`, `nextafterf`, `nextafterl`, `_nextafter`, `_nextafterf`](./reference/nextafter-functions.md) | Returns the next representable floating-point value | +| [`nexttoward`, `nexttowardf`, `nexttowardl`](./reference/nextafter-functions.md) | Returns the next representable floating-point value | +| [`pow`, `powf`, `powl`](./reference/pow-powf-powl.md) | Returns the value of *`x`**`y`* | +| [`remainder`, `remainderf`, `remainderl`](./reference/remainder-remainderf-remainderl.md) | Computes the remainder of the quotient of two floating-point values | +| [`remquo`, `remquof`, `remquol`](./reference/remquo-remquof-remquol.md) | Computes the remainder of two integer values | +| [`rint`, `rintf`, `rintl`](./reference/rint-rintf-rintl.md) | Rounds a floating-point value | +| [`_rotl`, `_rotl64`, `_rotr`, `_rotr64`](./reference/rotl-rotl64-rotr-rotr64.md) | Rotates bits in integer types | +| [`round`, `roundf`, `roundl`](./reference/round-roundf-roundl.md) | Rounds a floating-point value | +| [`_scalb`, `_scalbf`](./reference/scalb.md) | Scales argument by a power of 2 | +| [`scalbn`, `scalbnf`, `scalbnl`, `scalbln`, `scalblnf`, `scalblnl`](./reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md) | Multiplies a floating-point number by an integral power of `FLT_RADIX` | +| [`_set_controlfp`](./reference/set-controlfp.md) | Sets the floating-point control word | +| [`_set_SSE2_enable`](./reference/set-sse2-enable.md) | Enables or disables SSE2 instructions | +| [`signbit`](./reference/signbit.md) | Tests the sign bit of a floating-point value | +| [`sin`, `sinf`, `sinl`](./reference/sin-sinf-sinl.md) | Computes the sine | +| [`sinh`, `sinhf`, `sinhl`](./reference/sinh-sinhf-sinhl.md) | Computes the hyperbolic sine | +| [`sqrt`, `sqrtf`, `sqrtl`](./reference/sqrt-sqrtf-sqrtl.md) | Computes the square root | +| [`_status87`, `_statusfp`, `_statusfp2`](./reference/status87-statusfp-statusfp2.md) | Gets the floating-point status word | +| [`strtof`, `_strtof_l`](./reference/strtof-strtof-l-wcstof-wcstof-l.md) | Converts a string to a **`float`** | +| [`strtold`, `_strtold_l`](./reference/strtold-strtold-l-wcstold-wcstold-l.md) | Converts a string to a **`long double`** | +| [`tan`, `tanf`, `tanl`](./reference/tan-tanf-tanl.md) | Computes the tangent | +| [`tanh`, `tanhf`, `tanhl`](./reference/tanh-tanhf-tanhl.md) | Computes the hyperbolic tangent | +| [`tgamma`, `tgammaf`, `tgammal`](./reference/tgamma-tgammaf-tgammal.md) | Computes the gamma function | +| [`trunc`, `truncf`, `truncl`](./reference/trunc-truncf-truncl.md) | Truncates the fractional part | +| [`_wtof`, `_wtof_l`](./reference/atof-atof-l-wtof-wtof-l.md) | Converts a wide string to a **`double`** | +| [`_y0`, `_y1`, `_yn`](./reference/bessel-functions-j0-j1-jn-y0-y1-yn.md) | Computes the Bessel function | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)\ -[Floating-point primitives](../c-runtime-library/reference/floating-point-primitives.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[Floating-point primitives](./reference/floating-point-primitives.md) diff --git a/docs/c-runtime-library/fmode.md b/docs/c-runtime-library/fmode.md index 308b112b321..9bc5cb02e4a 100644 --- a/docs/c-runtime-library/fmode.md +++ b/docs/c-runtime-library/fmode.md @@ -2,17 +2,17 @@ description: "Learn more about: _fmode" title: "_fmode" ms.date: "11/04/2016" -f1_keywords: ["fmode", "_fmode"] -helpviewer_keywords: ["file translation [C++], default mode", "fmode function", "_fmode function"] +f1_keywords: ["_fmode", "STDLIB/_fmode"] +helpviewer_keywords: ["file translation [C++], default mode", "_fmode global variable"] ms.assetid: ac6df9eb-e5cc-4c54-aff3-373c21983118 --- -# _fmode +# `_fmode` -The `_fmode` variable sets the default file-translation mode for text or binary translation. This global variable has been deprecated for the more secure functional versions [_get_fmode](../c-runtime-library/reference/get-fmode.md) and [_set_fmode](../c-runtime-library/reference/set-fmode.md), which should be used in place of the global variable. It is declared in Stdlib.h as follows. +The `_fmode` variable sets the default file-translation mode for text or binary translation. This global variable has been deprecated for the more secure functional versions [`_get_fmode`](./reference/get-fmode.md) and [`_set_fmode`](./reference/set-fmode.md), which should be used in place of the global variable. It's declared in Stdlib.h as follows. ## Syntax -``` +```C extern int _fmode; ``` @@ -22,7 +22,7 @@ The default setting of `_fmode` is `_O_TEXT` for text-mode translation. `_O_BINA You can change the value of `_fmode` in three ways: -- Link with Binmode.obj. This changes the initial setting of `_fmode` to `_O_BINARY`, causing all files except `stdin`, `stdout`, and `stderr` to be opened in binary mode. +- Link with Binmode.obj. This object file changes the initial setting of `_fmode` to `_O_BINARY`, causing all files except `stdin`, `stdout`, and `stderr` to be opened in binary mode. - Make a call to `_get_fmode` or `_set_fmode` to get or set the `_fmode` global variable, respectively. @@ -30,6 +30,6 @@ You can change the value of `_fmode` in three ways: ## See also -[Global Variables](../c-runtime-library/global-variables.md)
-[_get_fmode](../c-runtime-library/reference/get-fmode.md)
-[_set_fmode](../c-runtime-library/reference/set-fmode.md) +[Global variables](./global-variables.md)\ +[`_get_fmode`](./reference/get-fmode.md)\ +[`_set_fmode`](./reference/set-fmode.md) diff --git a/docs/c-runtime-library/fopen-max-sys-open.md b/docs/c-runtime-library/fopen-max-sys-open.md index 2c9b6fd3a5d..80769240891 100644 --- a/docs/c-runtime-library/fopen-max-sys-open.md +++ b/docs/c-runtime-library/fopen-max-sys-open.md @@ -2,22 +2,22 @@ description: "Learn more about: FOPEN_MAX, _SYS_OPEN" title: "FOPEN_MAX, _SYS_OPEN" ms.date: "11/04/2016" -f1_keywords: ["_SYS_OPEN", "FOPEN_MAX"] +f1_keywords: ["STDIO/_SYS_OPEN", "STDIO/FOPEN_MAX", "_SYS_OPEN", "FOPEN_MAX"] helpviewer_keywords: ["SYS_OPEN constant", "_SYS_OPEN constant", "FOPEN_MAX constant", "files [C++], maximum open", "maximum number of files", "open files, maximum"] ms.assetid: 39cf5196-250a-459d-ae90-ce3d99f79039 --- -# FOPEN_MAX, _SYS_OPEN +# `FOPEN_MAX`, `_SYS_OPEN` ## Syntax -``` +```C #include ``` ## Remarks -This is the maximum number of files that can be opened simultaneously. `FOPEN_MAX` is the ANSI-compatible name. `_SYS_OPEN` is provided for compatibility with existing code. + `FOPEN_MAX` and `_SYS_OPEN` are the maximum number of files that can be opened simultaneously. `FOPEN_MAX` is the ANSI-compatible name. `_SYS_OPEN` is provided for compatibility with existing code. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md b/docs/c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md index 50f9cc1e4bd..ee57428b23d 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 @@ -22,7 +21,7 @@ The `format` argument is a string that specifies the interpretation of the input > **`%`**\[**`*`**]\[***`width`***]\[{**`h`**\|**`l`**\|**`ll`**\|**`I64`**\|**`L`**}]***`type`*** - Here, ***`width`***, **`h`**, **`l`**, **`ll`**, **`I64`**, and **`L`** represent a `scanf` [width specification](../c-runtime-library/scanf-width-specification.md), and ***`type`*** represents a `scanf` [type field character](../c-runtime-library/scanf-type-field-characters.md). + Here, ***`width`***, **`h`**, **`l`**, **`ll`**, **`I64`**, and **`L`** represent a `scanf` [width specification](./scanf-width-specification.md), and ***`type`*** represents a `scanf` [type field character](./scanf-type-field-characters.md). The `format` argument string is read from left to right. Characters outside format specifications are expected to match the sequence of characters in the input stream. The matching characters in the input stream are scanned but not stored. If a character in the input stream conflicts with the format specification, `scanf` terminates, and the character is left in the input stream as if it hadn't been read. @@ -36,11 +35,11 @@ The simplest format specification contains only the percent sign and a `type` ch An asterisk (`*`) following the percent sign suppresses assignment of the next input field, which is interpreted as a field of the specified type. The field is scanned but not stored in an argument. -The secure versions (the ones with the `_s` suffix) of the `scanf` family of functions require each parameter of type `c`, `C`, `s`, `S` or `[` to have a buffer size parameter passed immediately following. For more information on the secure versions of the `scanf` family of functions, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). +The secure versions (the ones with the `_s` suffix) of the `scanf` family of functions require each parameter of type `c`, `C`, `s`, `S` or `[` to have a buffer size parameter passed immediately following. For more information on the secure versions of the `scanf` family of functions, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). ## See also -[`scanf` Width specification](../c-runtime-library/scanf-width-specification.md)\ -[`scanf` Type field characters](../c-runtime-library/scanf-type-field-characters.md)\ -[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)\ -[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) +[`scanf` Width specification](./scanf-width-specification.md)\ +[`scanf` Type field characters](./scanf-type-field-characters.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) diff --git a/docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md b/docs/c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md index 3e089295b4f..c6b482f1f36 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 @@ -1,24 +1,23 @@ --- title: "Format Specification Syntax: `printf` and `wprintf` Functions" -description: "Describes the format specifier syntax for the Microsoft C runtime `printf` and `wprintf` functions" -ms.date: "10/26/2020" +description: "Describes the format specifier syntax for the Microsoft C runtime `printf` and `wprintf` functions" +ms.date: 10/26/2020 helpviewer_keywords: ["format specification fields for printf function", "printf function format specification fields", "flag directives, printf function", "type fields, printf function", "width fields, printf function", "precision fields, printf function"] -ms.assetid: 664b1717-2760-4c61-bd9c-22eee618d825 --- # Format specification syntax: `printf` and `wprintf` functions -The various `printf` and `wprintf` functions take a format string and optional arguments and produce a formatted sequence of characters for output. The format string contains zero or more *directives*, which are either literal characters for output or encoded *conversion specifications* that describe how to format an argument in the output. This article describes the syntax used to encode conversion specifications in the format string. For a listing of these functions, see [Stream I/O](../c-runtime-library/stream-i-o.md). +The various `printf` and `wprintf` functions take a format string and optional arguments and produce a formatted sequence of characters for output. The format string contains zero or more *directives*, which are either literal characters for output or encoded *conversion specifications* that describe how to format an argument in the output. This article describes the syntax used to encode conversion specifications in the format string. For a listing of these functions, see [Stream I/O](./stream-i-o.md). A conversion specification consists of optional and required fields in this form: -**%**[[*flags*](#flags)][[*width*](#width)][.[*precision*](#precision)][[*size*](#size)][*type*](#type) +> **%**\[[*flags*](#flags)\]\[[*width*](#width)\]\[.[*precision*](#precision)\]\[[*size*](#size)\][*type*](#type) -Each field of the conversion specification is a character or a number that signifies a particular format option or conversion specifier. The required *type* field specifies the kind of conversion to be applied to an argument. The optional *flags*, *width*, and *precision* fields control additional format aspects such as leading spaces or zeroes, justification, and displayed precision. The *size* field specifies the size of the argument consumed and converted. +Each field of the conversion specification is a character or a number that signifies a particular format option or conversion specifier. The required *type* field specifies the kind of conversion to be applied to an argument. The optional *flags*, *width*, and *precision* fields control other format aspects such as leading spaces or zeroes, justification, and displayed precision. The *size* field specifies the size of the argument consumed and converted. -A basic conversion specification contains only the percent sign and a *type* character. For example, `%s` specifies a string conversion. To print a percent-sign character, use `%%`. If a percent sign is followed by a character that has no meaning as a format field, the invalid parameter handler is invoked. For more information, see [Parameter Validation](../c-runtime-library/parameter-validation.md). +A basic conversion specification contains only the percent sign and a *type* character. For example, `%s` specifies a string conversion. To print a percent-sign character, use `%%`. If a percent sign is followed by a character that has no meaning as a format field, the invalid parameter handler is invoked. For more information, see [Parameter validation](./parameter-validation.md). > [!IMPORTANT] -> For security and stability, ensure that conversion specification strings are not user-defined. For example, consider a program that prompts the user to enter a name and stores the input in a string variable that's named `user_name`. To print `user_name`, do not do this: +> For security and stability, ensure that format conversion specification strings aren't end-user defined. For example, consider a program that prompts the user to enter a name and stores the input in a string variable that's named `user_name`. To print `user_name`, never do this: > > `printf( user_name ); /* Danger! If user_name contains "%s", program will crash */` > @@ -26,18 +25,16 @@ A basic conversion specification contains only the percent sign and a *type* cha > > `printf( "%s", user_name );` - - > [!NOTE] -> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see *LNK2019* in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). +> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see LNK2019 in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). -## Type conversion specifier +## Type conversion specifier The *type* conversion specifier character specifies whether to interpret the corresponding argument as a character, a string, a pointer, an integer, or a floating-point number. The *type* character is the only required conversion specification field, and it appears after any optional fields. -The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [size](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific. +The arguments that follow the format string are interpreted according to the corresponding *type* character and the optional [*size*](#size) prefix. Conversions for character types `char` and `wchar_t` are specified by using **`c`** or **`C`**, and single-byte and multi-byte or wide character strings are specified by using **`s`** or **`S`**, depending on which formatting function is being used. Character and string arguments that are specified by using **`c`** and **`s`** are interpreted as `char` and `char*` by `printf` family functions, or as `wchar_t` and `wchar_t*` by `wprintf` family functions. Character and string arguments that are specified by using **`C`** and **`S`** are interpreted as `wchar_t` and `wchar_t*` by `printf` family functions, or as `char` and `char*` by `wprintf` family functions. This behavior is Microsoft-specific. For historical reasons, the `wprintf` functions use **`c`** and **`s`** to refer to `wchar_t` characters, and **`C`** and **`S`** specify narrow characters. -Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` variants, are specified by using **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, and **`X`**. Floating-point types such as `float`, `double`, and **`long double`**, are specified by using **`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, and **`G`**. By default, unless they're modified by a *size* prefix, integer arguments are coerced to `int` type, and floating-point arguments are coerced to `double`. On 64-bit systems, an `int` is a 32-bit value; so, 64-bit integers will be truncated when they're formatted for output unless a *size* prefix of **ll** or **I64** is used. Pointer types that are specified by **`p`** use the default pointer size for the platform. +Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` variants, are specified by using **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, and **`X`**. Floating-point types such as `float`, `double`, and `long double`, are specified by using **`a`**, **`A`**, **`e`**, **`E`**, **`f`**, **`F`**, **`g`**, and **`G`**. By default, unless they're modified by a *size* prefix, integer arguments are coerced to `int` type, and floating-point arguments are coerced to `double`. On 64-bit systems, an `int` is a 32-bit value; so, 64-bit integers will be truncated when they're formatted for output unless a *size* prefix of **`ll`** or **`I64`** is used. Pointer types that are specified by **`p`** use the default pointer size for the platform. > [!NOTE] > **Microsoft-specific:**\ @@ -45,82 +42,78 @@ Integer types such as `short`, `int`, `long`, `long long`, and their `unsigned` ### Type field characters -|Type character|Argument|Output format| -|--------------------|--------------|-------------------| -|**`c`**|Character|When used with `printf` functions, specifies a single-byte character; when used with `wprintf` functions, specifies a wide character.| -|**`C`**|Character|When used with `printf` functions, specifies a wide character; when used with `wprintf` functions, specifies a single-byte character.| -|**`d`**|Integer|Signed decimal integer.| -|**`i`**|Integer|Signed decimal integer.| -|**`o`**|Integer|Unsigned octal integer.| -|**`u`**|Integer|Unsigned decimal integer.| -|**`x`**|Integer|Unsigned hexadecimal integer; uses "`abcdef`".| -|**`X`**|Integer|Unsigned hexadecimal integer; uses "`ABCDEF`".| -|**`e`**|Floating-point|Signed value that has the form [-]*`d.dddd`*__e±__*`dd`*\[*`d`*], where *`d`* is one decimal digit, *`dddd`* is one or more decimal digits depending on the specified precision, or six by default, and *`dd`*\[*`d`*] is two or three decimal digits depending on the [output format](../c-runtime-library/set-output-format.md) and size of the exponent.| -|**`E`**|Floating-point|Identical to the **`e`** format except that **`E`** rather than **`e`** introduces the exponent.| -|**`f`**|Floating-point|Signed value that has the form [-]*`dddd`*__.__*`dddd`*, where *`dddd`* is one or more decimal digits. The number of digits before the decimal point depends on the magnitude of the number, and the number of digits after the decimal point depends on the requested precision, or six by default.| -|**`F`**|Floating-point|Identical to the **`f`** format except that infinity and nan output is capitalized.| -|**`g`**|Floating-point|Signed values are displayed in **`f`** or **`e`** format, whichever is more compact for the given value and precision. The **`e`** format is used only when the exponent of the value is less than -4 or greater than or equal to the *precision* argument. Trailing zeros are truncated, and the decimal point appears only if one or more digits follow it.| -|**`G`**|Floating-point|Identical to the **`g`** format, except that **`E`**, rather than **`e`**, introduces the exponent (where appropriate).| -|**`a`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form *[-]0xh.hhhh*__p±__*`dd`*, where *h.hhhh* are the hex digits (using lower case letters) of the mantissa, and *`dd`* are one or more digits for the exponent. The precision specifies the number of digits after the point.| -|**`A`**|Floating-point|Signed hexadecimal double-precision floating-point value that has the form *[-]0Xh.hhhh*__P±__*`dd`*, where *h.hhhh* are the hex digits (using capital letters) of the mantissa, and *dd* are one or more digits for the exponent. The precision specifies the number of digits after the point.| -|**`n`**|Pointer to integer|Number of characters that are successfully written so far to the stream or buffer. This value is stored in the integer whose address is given as the argument. The size of the integer pointed at can be controlled by an argument size specification prefix. The **`n`** specifier is disabled by default; for information see the important security note.| -|**`p`**|Pointer type|Display the argument as an address in hexadecimal digits.| -|**`s`**|String|When used with `printf` functions, specifies a single-byte or multi-byte character string; when used with `wprintf` functions, specifies a wide-character string. Characters are displayed up to the first null character or until the *precision* value is reached.| -|**`S`**|String|When used with `printf` functions, specifies a wide-character string; when used with `wprintf` functions, specifies a single-byte or multi-byte character string. Characters are displayed up to the first null character or until the *precision* value is reached.| -|**`Z`**|`ANSI_STRING` or `UNICODE_STRING` structure|When the address of an [`ANSI_STRING`](/windows/win32/api/ntdef/ns-ntdef-string) or [`UNICODE_STRING`](/windows/win32/api/ntdef/ns-ntdef-_unicode_string) structure is passed as the argument, display the string contained in the buffer pointed to by the `Buffer` field of the structure. Use a *size* modifier prefix of **`w`** to specify a `UNICODE_STRING` argument—for example, `%wZ`. The `Length` field of the structure must be set to the length, in bytes, of the string. The `MaximumLength` field of the structure must be set to the length, in bytes, of the buffer.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Based on how the program is invoked, the runtime initializes these values at program startup: either to the fully qualified or relative path of the program, the full program name, or the program name without its file name extension. | ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
-[Global Constants](../c-runtime-library/global-constants.md)
-[__argc, \__argv, \__wargv](../c-runtime-library/argc-argv-wargv.md)
-[_get_daylight](../c-runtime-library/reference/get-daylight.md)
-[_get_dstbias](../c-runtime-library/reference/get-dstbias.md)
-[_get_timezone](../c-runtime-library/reference/get-timezone.md)
-[_get_tzname](../c-runtime-library/reference/get-tzname.md)
-[perror](../c-runtime-library/reference/perror-wperror.md)
-[strerror](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md)
-[_get_doserrno](../c-runtime-library/reference/get-doserrno.md)
-[_set_doserrno](../c-runtime-library/reference/set-doserrno.md)
-[_get_errno](../c-runtime-library/reference/get-errno.md)
-[_set_errno](../c-runtime-library/reference/set-errno.md)
-[_dupenv_s, _wdupenv_s](../c-runtime-library/reference/dupenv-s-wdupenv-s.md)
-[getenv, _wgetenv](../c-runtime-library/reference/getenv-wgetenv.md)
-[getenv_s, _wgetenv_s](../c-runtime-library/reference/getenv-s-wgetenv-s.md)
-[_putenv, _wputenv](../c-runtime-library/reference/putenv-wputenv.md)
-[_putenv_s, _wputenv_s](../c-runtime-library/reference/putenv-s-wputenv-s.md)
-[_get_fmode](../c-runtime-library/reference/get-fmode.md)
-[_set_fmode](../c-runtime-library/reference/set-fmode.md) +[C runtime library reference](./c-run-time-library-reference.md)\ +[Global constants](./global-constants.md)\ +[`__argc`, `__argv`, `__wargv`](./argc-argv-wargv.md)\ +[`_get_daylight`](./reference/get-daylight.md)\ +[`_get_dstbias`](./reference/get-dstbias.md)\ +[`_get_timezone`](./reference/get-timezone.md)\ +[`_get_tzname`](./reference/get-tzname.md)\ +[`perror`](./reference/perror-wperror.md)\ +[`strerror`](./reference/strerror-strerror-wcserror-wcserror.md)\ +[`_get_doserrno`](./reference/get-doserrno.md)\ +[`_set_doserrno`](./reference/set-doserrno.md)\ +[`_get_errno`](./reference/get-errno.md)\ +[`_set_errno`](./reference/set-errno.md)\ +[`_dupenv_s`, `_wdupenv_s`](./reference/dupenv-s-wdupenv-s.md)\ +[`getenv`, `_wgetenv`](./reference/getenv-wgetenv.md)\ +[`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md)\ +[`_putenv`, `_wputenv`](./reference/putenv-wputenv.md)\ +[`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md)\ +[`_get_fmode`](./reference/get-fmode.md)\ +[`_set_fmode`](./reference/set-fmode.md) diff --git a/docs/c-runtime-library/heap-constants.md b/docs/c-runtime-library/heap-constants.md index ec7e079d881..71ae99a4684 100644 --- a/docs/c-runtime-library/heap-constants.md +++ b/docs/c-runtime-library/heap-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: Heap Constants" title: "Heap Constants" ms.date: "11/04/2016" -f1_keywords: ["_HEAPBADPTR", "_HEAPEMPTY", "_HEAPBADBEGIN", "_HEAPOK", "_HEAPBADNODE", "_HEAPEND"] +f1_keywords: ["MALLOC/_HEAPBADPTR", "MALLOC/_HEAPEMPTY", "MALLOC/_HEAPBADBEGIN", "MALLOC/_HEAPOK", "MALLOC/_HEAPBADNODE", "MALLOC/_HEAPEND", "_HEAPBADPTR", "_HEAPEMPTY", "_HEAPBADBEGIN", "_HEAPOK", "_HEAPBADNODE", "_HEAPEND"] helpviewer_keywords: ["_HEAPOK constants", "_HEAPEND constants", "HEAPBADBEGIN constants", "_HEAPBADNODE constants", "HEAPBADNODE constants", "HEAPBADPTR constants", "_HEAPEMPTY constants", "HEAPEND constants", "HEAPOK constants", "HEAPEMPTY constants", "_HEAPBADBEGIN constants", "_HEAPBADPTR constants", "heap constants"] ms.assetid: 3f751bb9-2dc4-486f-b5f5-9061c96d3754 --- -# Heap Constants +# Heap constants ## Syntax -``` +```C #include ``` @@ -18,18 +18,18 @@ ms.assetid: 3f751bb9-2dc4-486f-b5f5-9061c96d3754 These constants give the return value indicating status of the heap. -|Constant|Meaning| -|--------------|-------------| -|`_HEAPBADBEGIN`|Initial header information was not found or was invalid.| -|`_HEAPBADNODE`|Bad node was found, or heap is damaged.| -|`_HEAPBADPTR`|**_pentry** field of **_HEAPINFO** structure does not contain valid pointer into heap (`_heapwalk` routine only).| -|`_HEAPEMPTY`|Heap has not been initialized.| -|`_HEAPEND`|End of heap was reached successfully (`_heapwalk` routine only).| -|`_HEAPOK`|Heap is consistent (`_heapset` and `_heapchk` routines only). No errors so far; **_HEAPINFO** structure contains information about next entry (`_heapwalk` routine only).| +| Constant | Meaning | +|---|---| +| `_HEAPBADBEGIN` | Initial header information wasn't found or was invalid. | +| `_HEAPBADNODE` | Bad node was found, or heap is damaged. | +| `_HEAPBADPTR` | `_pentry` field of `_HEAPINFO` structure doesn't contain valid pointer into heap (`_heapwalk` routine only). | +| `_HEAPEMPTY` | Heap hasn't been initialized. | +| `_HEAPEND` | End of heap was reached successfully (`_heapwalk` routine only). | +| `_HEAPOK` | Heap is consistent (`_heapset` and `_heapchk` routines only). No errors so far; `_HEAPINFO` structure contains information about next entry (`_heapwalk` routine only). | ## See also -[_heapchk](../c-runtime-library/reference/heapchk.md)
-[_heapset](../c-runtime-library/heapset.md)
-[_heapwalk](../c-runtime-library/reference/heapwalk.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_heapchk`](./reference/heapchk.md)\ +[`_heapset`](./heapset.md)\ +[`_heapwalk`](./reference/heapwalk.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/heap-maxreq.md b/docs/c-runtime-library/heap-maxreq.md index e4688366f27..e0b29182302 100644 --- a/docs/c-runtime-library/heap-maxreq.md +++ b/docs/c-runtime-library/heap-maxreq.md @@ -2,15 +2,15 @@ description: "Learn more about: _HEAP_MAXREQ" title: "_HEAP_MAXREQ" ms.date: "11/04/2016" -f1_keywords: ["HEAP_MAXREQ", "_HEAP_MAXREQ"] +f1_keywords: ["HEAP_MAXREQ", "MALLOC/_HEAP_MAXREQ", "_HEAP_MAXREQ"] helpviewer_keywords: ["HEAP_MAXREQ constants", "_HEAP_MAXREQ constants", "heap constants"] ms.assetid: c2dbc2ea-35ad-45d8-b459-d76ba0089ff7 --- -# _HEAP_MAXREQ +# `_HEAP_MAXREQ` ## Syntax -``` +```C #include ``` @@ -20,6 +20,6 @@ The maximum size of a user request for memory that can be granted. ## See also -[malloc](../c-runtime-library/reference/malloc.md)
-[calloc](../c-runtime-library/reference/calloc.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`malloc`](./reference/malloc.md)\ +[`calloc`](./reference/calloc.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/heapadd.md b/docs/c-runtime-library/heapadd.md index f5aadfdcc1e..737e7991fe3 100644 --- a/docs/c-runtime-library/heapadd.md +++ b/docs/c-runtime-library/heapadd.md @@ -10,7 +10,7 @@ f1_keywords: ["heapadd", "_heapadd"] helpviewer_keywords: ["_heapadd function", "memory, adding to heaps", "heaps, adding memory", "heapadd function"] ms.assetid: 4d691fe2-2763-49f4-afb1-62738b7cd3ff --- -# _heapadd +# `_heapadd` Adds memory to the heap. @@ -19,46 +19,46 @@ Adds memory to the heap. ## Syntax -``` +```C int _heapadd( void *memblock, size_t size ); ``` -#### Parameters +### Parameters -*memblock*
+*`memblock`*\ Pointer to the heap memory. -*size*
+*`size`*\ Size of memory to add, in bytes. -## Return Value +## Return value -If successful, `_heapadd` returns 0; otherwise, the function returns -1 and sets `errno` to `ENOSYS`. +If successful, **`_heapadd`** returns 0; otherwise, the function returns -1 and sets `errno` to `ENOSYS`. -For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](./errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Beginning with Visual C++ version 4.0, the underlying heap structure was moved to the C run-time libraries to support the new debugging features. As a result, `_heapadd` is no longer supported on any platform that is based on the Win32 API. +Beginning with Visual C++ version 4.0, the underlying heap structure was moved to the C run-time libraries to support the new debugging features. As a result, **`_heapadd`** is no longer supported on any platform that is based on the Win32 API. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|`_heapadd`|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_heapadd`** | \ | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md) in the Introduction. +For more compatibility information, see [Compatibility](./compatibility.md) in the Introduction. ## See also -[Memory Allocation](../c-runtime-library/memory-allocation.md)
-[free](../c-runtime-library/reference/free.md)
-[_heapchk](../c-runtime-library/reference/heapchk.md)
-[_heapmin](../c-runtime-library/reference/heapmin.md)
-[_heapset](../c-runtime-library/heapset.md)
-[_heapwalk](../c-runtime-library/reference/heapwalk.md)
-[malloc](../c-runtime-library/reference/malloc.md)
-[realloc](../c-runtime-library/reference/realloc.md) +[Memory allocation](./memory-allocation.md)\ +[`free`](./reference/free.md)\ +[`_heapchk`](./reference/heapchk.md)\ +[`_heapmin`](./reference/heapmin.md)\ +[`_heapset`](./heapset.md)\ +[`_heapwalk`](./reference/heapwalk.md)\ +[`malloc`](./reference/malloc.md)\ +[`realloc`](./reference/realloc.md) diff --git a/docs/c-runtime-library/heapset.md b/docs/c-runtime-library/heapset.md index 5b1adc0b612..71dcd097259 100644 --- a/docs/c-runtime-library/heapset.md +++ b/docs/c-runtime-library/heapset.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _heapset" title: "_heapset" +description: "Learn more about: _heapset" ms.date: "11/04/2016" api_name: ["_heapset"] api_location: ["msvcr90.dll", "msvcr80.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcrt.dll", "msvcr120.dll", "msvcr100.dll"] @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_heapset", "heapset"] helpviewer_keywords: ["checking heap", "heapset function", "heaps, checking", "debugging [CRT], heap-related problems", "_heapset function"] -ms.assetid: 9667eeb0-55bc-4c19-af5f-d1fd0a142b3c --- -# _heapset +# `_heapset` Checks heaps for minimal consistency and sets the free entries to a specified value. @@ -19,7 +18,7 @@ Checks heaps for minimal consistency and sets the free entries to a specified va ## Syntax -``` +```C int _heapset( unsigned int fill ); @@ -27,35 +26,35 @@ int _heapset( #### Parameters -*fill*
+*`fill`*\ Fill character. -## Return Value +## Return value -`_heapset` returns one of the following integer manifest constants defined in Malloc.h. +**`_heapset`** returns one of the following integer manifest constants defined in Malloc.h. -|Value|Description| -|-|-| -| `_HEAPBADBEGIN` | Initial header information invalid or not found. | -| `_HEAPBADNODE` | Heap damaged or bad node found. | -| `_HEAPEMPTY` | Heap not initialized. | -| `_HEAPOK` | Heap appears to be consistent. | +| Value | Description | +|---|---| +| `_HEAPBADBEGIN` | Initial header information invalid or not found. | +| `_HEAPBADNODE` | Heap damaged or bad node found. | +| `_HEAPEMPTY` | Heap not initialized. | +| `_HEAPOK` | Heap appears to be consistent. | -In addition, if an error occurs, `_heapset` sets `errno` to `ENOSYS`. +In addition, if an error occurs, **`_heapset`** sets `errno` to `ENOSYS`. ## Remarks -The `_heapset` function shows free memory locations or nodes that have been unintentionally overwritten. +The **`_heapset`** function shows free memory locations or nodes that have been unintentionally overwritten. -`_heapset` checks for minimal consistency on the heap and then sets each byte of the heap's free entries to the `fill` value. This known value shows which memory locations of the heap contain free nodes and which contain data that were unintentionally written to freed memory. If the operating system does not support `_heapset`(for example, Windows 98), the function returns `_HEAPOK` and sets `errno` to `ENOSYS`. +**`_heapset`** checks for minimal consistency on the heap and then sets each byte of the heap's free entries to the `fill` value. This known value shows which memory locations of the heap contain free nodes and which contain data that were unintentionally written to freed memory. If the operating system doesn't support **`_heapset`** (for example, Windows 98), the function returns `_HEAPOK` and sets `errno` to `ENOSYS`. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|`_heapset`|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_heapset`** | \ | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md) in the Introduction. +For more compatibility information, see [Compatibility](./compatibility.md) in the Introduction. ## Example @@ -101,8 +100,8 @@ OK - heap is fine ## See also -[Memory Allocation](../c-runtime-library/memory-allocation.md)
-[_heapadd](../c-runtime-library/heapadd.md)
-[_heapchk](../c-runtime-library/reference/heapchk.md)
-[_heapmin](../c-runtime-library/reference/heapmin.md)
-[_heapwalk](../c-runtime-library/reference/heapwalk.md) +[Memory allocation](./memory-allocation.md)\ +[`_heapadd`](./heapadd.md)\ +[`_heapchk`](./reference/heapchk.md)\ +[`_heapmin`](./reference/heapmin.md)\ +[`_heapwalk`](./reference/heapwalk.md) diff --git a/docs/c-runtime-library/huge-val-huge.md b/docs/c-runtime-library/huge-val-huge.md index be0042e116b..98eaf2b2eaf 100644 --- a/docs/c-runtime-library/huge-val-huge.md +++ b/docs/c-runtime-library/huge-val-huge.md @@ -6,22 +6,22 @@ api_name: ["_HUGE"] api_location: ["msvcrt.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_HUGE", "HUGE_VAL"] +f1_keywords: ["CORECRT_MATH/HUGE_VAL", "CORECRT_MATH/HUGE_VALF", "CORECRT_MATH/HUGE_VALL", "CORECRT_MATH/HUGE", "CORECRT_MATH/_HUGE", "HUGE_VAL", "HUGE_VALF", "HUGE_VALL", "HUGE", "_HUGE"] helpviewer_keywords: ["_HUGE constant", "HUGE_VAL constant", "double value"] ms.assetid: 3f044b45-02cd-46b2-b1de-87fd0441dd6a --- -# HUGE_VAL, _HUGE +# `HUGE_VAL`, `_HUGE` ## Syntax -``` +```C #include ``` ## Remarks -`HUGE_VAL` is the largest representable double value. This value is returned by many run-time math functions when an error occurs. For some functions, -`HUGE_VAL` is returned. `HUGE_VAL` is defined as `_HUGE`, but run-time math functions return `HUGE_VAL`. You should also use `HUGE_VAL` in your code for consistency. +`HUGE_VAL` is the largest representable double value. This value is returned by many run-time math functions when an error occurs. For some functions, `-HUGE_VAL` is returned. `HUGE_VAL` is defined as the result of a floating-point product that is guaranteed to overflow. `HUGE_VALF` and `HUGE_VALL` are the largest representable `float` and `long double` typed values, respectively. The internal value `_HUGE` and the synonymous `HUGE` are defined similarly, but run-time math functions return `HUGE_VAL`. You should also use `HUGE_VAL` in your code for consistency. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/inp-inpw-inpd.md b/docs/c-runtime-library/inp-inpw-inpd.md index 8b690315e4d..3e98fc33a2c 100644 --- a/docs/c-runtime-library/inp-inpw-inpd.md +++ b/docs/c-runtime-library/inp-inpw-inpd.md @@ -10,13 +10,13 @@ f1_keywords: ["inp", "inpw", "_inp", "_inpw", "_inpd"] helpviewer_keywords: ["inp function", "inpw function", "ports, I/O routines", "inpd function", "_inp function", "_inpd function", "I/O [CRT], port", "_inpw function"] ms.assetid: 5d9c2e38-fc85-4294-86d5-7282cc02d1b3 --- -# inp, _inp, inpw, _inpw, _inpd +# `inp`, `_inp`, `inpw`, `_inpw`, `_inpd` -Inputs, from a port, a byte (`inp`, `_inp`), a word (`inpw`, `_inpw`), or a double word (`_inpd`). +Inputs, from a port, a byte (**`inp`**, **`_inp`**), a word (**`inpw`**, **`_inpw`**), or a double word (**`_inpd`**). > [!IMPORTANT] > These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT.\ -> This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> This API can't be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -34,36 +34,36 @@ unsigned long _inpd( ### Parameters -*port*\ +*`port`*\ I/O port number. -## Return Value +## Return value -The functions return the byte, word, or double word read from `port`. There's no error return. +The functions return the byte, word, or double word read from *`port`*. There's no error return. ## Remarks -The `_inp`, `_inpw`, and `_inpd` functions read a byte, a word, and a double word, respectively, from the specified input port. The input value can be any unsigned short integer in the range 0 - 65,535. +The **`_inp`**, **`_inpw`**, and **`_inpd`** functions read a byte, a word, and a double word, respectively, from the specified input port. The input value can be any unsigned short integer in the range 0 - 65,535. -Because these functions read directly from an I/O port, they cannot be used in user code. +Because these functions read directly from an I/O port, they can't be used in user code. -The `inp` and `inpw` names are older, deprecated names for the `_inp` and `_inpw` functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +The **`inp`** and **`inpw`** names are older, deprecated names for the **`_inp`** and **`_inpw`** functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_inp`|\| -|`_inpw`|\| -|`_inpd`|\| +| Routine | Required header | +|---|---| +| **`_inp`** | \ | +| **`_inpw`** | \ | +| **`_inpd`** | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](./compatibility.md). ## Libraries -All versions of the [C run-time libraries](../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](./crt-library-features.md). ## See also -[Console and Port I/O](../c-runtime-library/console-and-port-i-o.md)\ -[outp, outpw, _outp, _outpw, _outpd](../c-runtime-library/outp-outpw-outpd.md) +[Console and port I/O](./console-and-port-i-o.md)\ +[`outp`, `outpw`, `_outp`, `_outpw`, `_outpd`](./outp-outpw-outpd.md) diff --git a/docs/c-runtime-library/input-and-output.md b/docs/c-runtime-library/input-and-output.md index 10be91539a8..d459ce63c10 100644 --- a/docs/c-runtime-library/input-and-output.md +++ b/docs/c-runtime-library/input-and-output.md @@ -5,19 +5,19 @@ ms.date: "11/04/2016" f1_keywords: ["c.io"] helpviewer_keywords: ["input routines", "I/O [CRT]", "I/O routines", "I/O [CRT], routines", "output routines"] --- -# Input and Output +# Input and output The I/O functions read and write data to and from files and devices. File I/O operations take place in text mode or binary mode. The Microsoft run-time library has three types of I/O functions: -- [Stream I/O](../c-runtime-library/stream-i-o.md) functions treat data as a stream of individual characters. +- [Stream I/O](./stream-i-o.md) functions treat data as a stream of individual characters. -- [Low-level I/O](../c-runtime-library/low-level-i-o.md) functions invoke the operating system directly for lower-level operation than that provided by stream I/O. +- [Low-level I/O](./low-level-i-o.md) functions invoke the operating system directly for lower-level operation than that provided by stream I/O. -- [Console and port I/O](../c-runtime-library/console-and-port-i-o.md) functions read or write directly to a console (keyboard and screen) or an I/O port (such as a printer port). +- [Console and port I/O](./console-and-port-i-o.md) functions read or write directly to a console (keyboard and screen) or an I/O port (such as a printer port). > [!NOTE] > Because stream functions are buffered and low-level functions are not, these two types of functions are generally incompatible. For processing a particular file, use either stream or low-level functions exclusively. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/internal-crt-globals-and-functions.md b/docs/c-runtime-library/internal-crt-globals-and-functions.md index baad53841bc..e9b6ae617b2 100644 --- a/docs/c-runtime-library/internal-crt-globals-and-functions.md +++ b/docs/c-runtime-library/internal-crt-globals-and-functions.md @@ -2,348 +2,346 @@ description: "Learn more about: Internal CRT Globals and Functions" title: "Internal CRT Globals and Functions" ms.date: "1/14/2021" -api_name: ["__acrt_iob_func", "__AdjustPointer", "_assert", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__daylight", "_dclass", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_dpcomp", "_dsign", "__dstbias", "_dtest", "_EH_prolog", "_errno", "_except_handler2", "_except_handler4_common", "_except1", "_fdclass", "_fdpcomp", "_fdsign", "_fdtest", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "_ldclass", "_ldpcomp", "_ldsign", "_ldtest", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "_pctype", "__pioinfo", "_pwctype", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__std_type_info_name", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_wassert", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error", "_o__CIacos", "_o__CIasin", "_o__CIcosh", "_o__CIsinh", "_o__CItanh", "_o__Getdays", "_o__Getmonths", "_o__Gettnames", "_o__Strftime", "_o__W_Getdays", "_o__W_Getmonths", "_o__Wcsftime", "_o___acrt_iob_func", "_o___conio_common_vcprintf", "_o___conio_common_vcprintf_p", "_o___conio_common_vcprintf_s", "_o___conio_common_vcscanf", "_o___conio_common_vcwprintf", "_o___conio_common_vcwprintf_p", "_o___conio_common_vcwprintf_s", "_o___conio_common_vcwscanf", "_o___fpe_flt_rounds", "_o___libm_sse2_acos", "_o___libm_sse2_acosf", "_o___libm_sse2_asin", "_o___libm_sse2_asinf", "_o___libm_sse2_atan", "_o___libm_sse2_atan2", "_o___libm_sse2_atanf", "_o___libm_sse2_cos", "_o___libm_sse2_cosf", "_o___libm_sse2_exp", "_o___libm_sse2_expf", "_o___libm_sse2_log", "_o___libm_sse2_log10", "_o___libm_sse2_log10f", "_o___libm_sse2_logf", "_o___libm_sse2_pow", "_o___libm_sse2_powf", "_o___libm_sse2_sin", "_o___libm_sse2_sinf", "_o___libm_sse2_tan", "_o___libm_sse2_tanf", "_o___p___argc", "_o___p___argv", "_o___p___wargv", "_o___p__acmdln", "_o___p__environ", "_o___p__mbcasemap", "_o___p__mbctype", "_o___p__pgmptr", "_o___p__wcmdln", "_o___p__wenviron", "_o___p__wpgmptr", "_o___pwctype_func", "_o___std_exception_copy", "_o___std_exception_destroy", "_o___std_type_info_destroy_list", "_o___stdio_common_vfprintf", "_o___stdio_common_vfprintf_p", "_o___stdio_common_vfprintf_s", "_o___stdio_common_vfscanf", "_o___stdio_common_vfwprintf", "_o___stdio_common_vfwprintf_p", "_o___stdio_common_vfwprintf_s", "_o___stdio_common_vfwscanf", "_o___stdio_common_vsnprintf_s", "_o___stdio_common_vsnwprintf_s", "_o___stdio_common_vsprintf", "_o___stdio_common_vsprintf_p", "_o___stdio_common_vsprintf_s", "_o___stdio_common_vsscanf", "_o___stdio_common_vswprintf", "_o___stdio_common_vswprintf_p", "_o___stdio_common_vswprintf_s", "_o___stdio_common_vswscanf", "_o___timezone", "_o___tzname", "_o__calloc_base", "_o__configure_narrow_argv", "_o__configure_wide_argv", "_o__crt_atexit", "_o__errno", "_o__except1", "_o__free_base", "_o__get_initial_narrow_environment", "_o__get_initial_wide_environment", "_o__get_narrow_winmain_command_line", "_o__get_stream_buffer_pointers", "_o__get_wide_winmain_command_line", "_o__initialize_narrow_environment", "_o__initialize_wide_environment", "_o__libm_sse2_acos_precise", "_o__libm_sse2_asin_precise", "_o__libm_sse2_atan_precise", "_o__libm_sse2_cos_precise", "_o__libm_sse2_exp_precise", "_o__libm_sse2_log10_precise", "_o__libm_sse2_log_precise", "_o__libm_sse2_pow_precise", "_o__libm_sse2_sin_precise", "_o__libm_sse2_sqrt_precise", "_o__libm_sse2_tan_precise", "_o__malloc_base", "_o__realloc_base", "_o__sopen_dispatch", "_o__wsopen_dispatch"] -api_location: ["api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-core-crt-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-conio-l1-1-0.dll", "vcruntime140_app.dll", "msvcp140_app.dll", "ntdll.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-environment-l1-1-0.dll"] +api_name: ["__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__std_type_info_name", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error", "_o__CIacos", "_o__CIasin", "_o__CIcosh", "_o__CIsinh", "_o__CItanh", "_o__Getdays", "_o__Getmonths", "_o__Gettnames", "_o__Strftime", "_o__W_Getdays", "_o__W_Getmonths", "_o__Wcsftime", "_o___acrt_iob_func", "_o___conio_common_vcprintf", "_o___conio_common_vcprintf_p", "_o___conio_common_vcprintf_s", "_o___conio_common_vcscanf", "_o___conio_common_vcwprintf", "_o___conio_common_vcwprintf_p", "_o___conio_common_vcwprintf_s", "_o___conio_common_vcwscanf", "_o___fpe_flt_rounds", "_o___libm_sse2_acos", "_o___libm_sse2_acosf", "_o___libm_sse2_asin", "_o___libm_sse2_asinf", "_o___libm_sse2_atan", "_o___libm_sse2_atan2", "_o___libm_sse2_atanf", "_o___libm_sse2_cos", "_o___libm_sse2_cosf", "_o___libm_sse2_exp", "_o___libm_sse2_expf", "_o___libm_sse2_log", "_o___libm_sse2_log10", "_o___libm_sse2_log10f", "_o___libm_sse2_logf", "_o___libm_sse2_pow", "_o___libm_sse2_powf", "_o___libm_sse2_sin", "_o___libm_sse2_sinf", "_o___libm_sse2_tan", "_o___libm_sse2_tanf", "_o___p___argc", "_o___p___argv", "_o___p___wargv", "_o___p__acmdln", "_o___p__environ", "_o___p__mbcasemap", "_o___p__mbctype", "_o___p__pgmptr", "_o___p__wcmdln", "_o___p__wenviron", "_o___p__wpgmptr", "_o___pwctype_func", "_o___std_exception_copy", "_o___std_exception_destroy", "_o___std_type_info_destroy_list", "_o___stdio_common_vfprintf", "_o___stdio_common_vfprintf_p", "_o___stdio_common_vfprintf_s", "_o___stdio_common_vfscanf", "_o___stdio_common_vfwprintf", "_o___stdio_common_vfwprintf_p", "_o___stdio_common_vfwprintf_s", "_o___stdio_common_vfwscanf", "_o___stdio_common_vsnprintf_s", "_o___stdio_common_vsnwprintf_s", "_o___stdio_common_vsprintf", "_o___stdio_common_vsprintf_p", "_o___stdio_common_vsprintf_s", "_o___stdio_common_vsscanf", "_o___stdio_common_vswprintf", "_o___stdio_common_vswprintf_p", "_o___stdio_common_vswprintf_s", "_o___stdio_common_vswscanf", "_o___timezone", "_o___tzname", "_o__calloc_base", "_o__configure_narrow_argv", "_o__configure_wide_argv", "_o__crt_atexit", "_o__errno", "_o__except1", "_o__free_base", "_o__get_initial_narrow_environment", "_o__get_initial_wide_environment", "_o__get_narrow_winmain_command_line", "_o__get_stream_buffer_pointers", "_o__get_wide_winmain_command_line", "_o__initialize_narrow_environment", "_o__initialize_wide_environment", "_o__libm_sse2_acos_precise", "_o__libm_sse2_asin_precise", "_o__libm_sse2_atan_precise", "_o__libm_sse2_cos_precise", "_o__libm_sse2_exp_precise", "_o__libm_sse2_log10_precise", "_o__libm_sse2_log_precise", "_o__libm_sse2_pow_precise", "_o__libm_sse2_sin_precise", "_o__libm_sse2_sqrt_precise", "_o__libm_sse2_tan_precise", "_o__malloc_base", "_o__realloc_base", "_o__sopen_dispatch", "_o__wsopen_dispatch"] +api_location: ["api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-core-crt-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-conio-l1-1-0.dll", "vcruntime140_app.dll", "msvcp140_app.dll", "ntdll.dll", "ntoskrnl.exe", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "__CxxUnregisterExceptionObject", "__daylight", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_free_base", "_freea_s", "_freefls", "_ftol", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "_pwctype", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] -helpviewer_keywords: ["__acrt_iob_func", "__AdjustPointer", "_assert", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__daylight", "_dclass", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_dpcomp", "_dsign", "__dstbias", "_dtest", "_EH_prolog", "_errno", "_except_handler2", "_except_handler4_common", "_except1", "_fdclass", "_fdpcomp", "_fdsign", "_fdtest", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "_ldclass", "_ldpcomp", "_ldsign", "_ldtest", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "_pctype", "__pioinfo", "_pwctype", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_wassert", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] +f1_keywords: ["CORECRT_WSTDIO/__acrt_iob_func", "EXCPT/__C_specific_handler", "CORECRT_MALLOC/_calloc_base", "CTYPE/_chvalidator", "CTYPE/_chvalidator_l", "STDIO/_commode", "CORECRT_STARTUP/_configure_narrow_argv", "CORECRT_STARTUP/_configure_wide_argv", "CONIO/__conio_common_vcprintf", "CONIO/__conio_common_vcprintf_p", "CONIO/__conio_common_vcprintf_s", "CONIO/__conio_common_vcscanf", "CONIO/__conio_common_vcwprintf", "CONIO/__conio_common_vcwprintf_p", "CONIO/__conio_common_vcwprintf_s", "CONIO/__conio_common_vcwscanf", "CORECRT_STARTUP/_crt_at_quick_exit", "CORECRT_STARTUP/_crt_atexit", "CRTDBG/_crtAssertBusy", "CRTDBG/_crtBreakAlloc", "STDLIB/__doserrno", "STDDEF/_errno", "EXCPT/_except_handler", "FLOAT/__fpe_flt_rounds", "FLOAT/__fpecode", "CORECRT_MALLOC/_free_base", "CORECRT_STARTUP/_get_initial_narrow_environment", "CORECRT_STARTUP/_get_initial_wide_environment", "CORECRT_STARTUP/_get_narrow_winmain_command_line", "CORECRT_STARTUP/_get_wide_winmain_command_line", "STDIO/_get_stream_buffer_pointers", "LOCALE/_Getdays", "LOCALE/_Getmonths", "LOCALE/_Gettnames", "CORECRT_STARTUP/_initialize_narrow_environment", "CORECRT_STARTUP/_initialize_wide_environment", "LOCALE/_lock_locales", "CORECRT_MALLOC/_malloc_base", "STDLIB/__p___argc", "STDLIB/__p___argv", "STDLIB/__p___wargv", "CORECRT_STARTUP/__p__acmdln", "CRTDBG/__p__crtBreakAlloc", "CRTDBG/__p__crtDbgFlag", "STDLIB/__p__environ", "MBCTYPE/__p__mbcasemap", "MBCTYPE/__p__mbctype", "STDLIB/__p__pgmptr", "CORECRT_STARTUP/__p__wcmdln", "STDLIB/__p__wenviron", "STDLIB/__p__wpgmptr", "CORECRT_WCTYPE/__pwctype_func", "SIGNAL/__pxcptinfoptrs", "CORECRT_STARTUP/_query_app_type", "CORECRT_MALLOC/_realloc_base", "PROCESS/_register_thread_local_exe_atexit_callback", "VCRUNTIME/__report_gsfailure", "RTTIDATA/__RTCastToVoid", "RTTIDATA/__RTtypeid", "CORECRT_IO/_sopen_dispatch", "VCRUNTIME_EXCEPTION/__std_exception_copy", "VCRUNTIME_EXCEPTION/__std_exception_destroy", "STDIO/__stdio_common_vfprintf", "STDIO/__stdio_common_vfprintf_p", "STDIO/__stdio_common_vfprintf_s", "STDIO/__stdio_common_vfscanf", "STDIO/__stdio_common_vfwprintf", "STDIO/__stdio_common_vfwprintf_p", "STDIO/__stdio_common_vfwprintf_s", "STDIO/__stdio_common_vfwscanf", "STDIO/__stdio_common_vsnprintf_s", "STDIO/__stdio_common_vsnwprintf_s", "STDIO/__stdio_common_vsprintf", "STDIO/__stdio_common_vsprintf_p", "STDIO/__stdio_common_vsprintf_s", "STDIO/__stdio_common_vsscanf", "STDIO/__stdio_common_vswprintf", "STDIO/__stdio_common_vswprintf_p", "STDIO/__stdio_common_vswprintf_s", "STDIO/__stdio_common_vswscanf", "LOCALE/_Strftime", "STRING/__strncnt", "STDDEF/__threadhandle", "STDDEF/__threadid", "TIME/__timezone", "TIME/__tzname", "LOCALE/_unlock_locales", "CRTDBG/_VCrtDbgReportA", "CRTDBG/_VCrtDbgReportW", "LOCALE/_W_Getdays", "LOCALE/_W_Getmonths", "LOCALE/_W_Getgnames", "LOCALE/_Wcsftime", "TCHAR/__wcsncnt", "CORECRT_WIO/_wsopen_dispatch", "__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "__CxxUnregisterExceptionObject", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_free_base", "_freea_s", "_freefls", "_ftol", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] +helpviewer_keywords: ["__acrt_iob_func", "__AdjustPointer", "__badioinfo", "__BuildCatchObject", "__BuildCatchObjectHelper", "__C_specific_handler", "_calloc_base", "_chkesp", "__chkstk", "_chkstk", "_chvalidator", "_chvalidator_l", "_CIacos", "_CIasin", "_CIcosh", "_CIsinh", "_CItanh", "__clean_type_info_names_internal", "_commode", "_configure_narrow_argv", "_configure_wide_argv", "__conio_common_vcprintf", "__conio_common_vcprintf_p", "__conio_common_vcprintf_s", "__conio_common_vcscanf", "__conio_common_vcwprintf", "__conio_common_vcwprintf_p", "__conio_common_vcwprintf_s", "__conio_common_vcwscanf", "__CppXcptFilter", "__create_locale", "_crt_at_quick_exit", "_crt_atexit", "_crtAssertBusy", "_crtBreakAlloc", "__crtCompareStringA", "__crtCompareStringEx", "__crtCompareStringW", "__crtCreateEventExW", "__crtCreateSemaphoreExW", "__crtCreateSymbolicLinkW", "_crt_debugger_hook", "__crtEnumSystemLocalesEx", "__crtFlsAlloc", "__crtFlsFree", "__crtFlsGetValue", "__crtFlsSetValue", "_CrtGetCheckCount", "__crtGetDateFormatEx", "__crtGetFileInformationByHandleEx", "__crtGetLocaleInfoEx", "__crtGetShowWindowMode", "__crtGetTickCount64", "__crtGetTimeFormatEx", "__crtGetUserDefaultLocaleName", "__crtInitializeCriticalSectionEx", "__crtIsPackagedApp", "__crtIsValidLocaleName", "__crtLCMapStringA", "__crtLCMapStringEx", "_CrtSetCheckCount", "_CrtSetDbgBlockType", "__crtSetFileInformationByHandle", "__crtSetThreadStackGuarantee", "__crtSetUnhandledExceptionFilter", "__crtSleep", "__crtTerminateProcess", "__crtUnhandledException", "__CxxDetectRethrow", "__CxxExceptionFilter", "__CxxFrameHandler2", "__CxxFrameHandler3", "__CxxLongjmpUnwind", "__CxxQueryExceptionSize", "__CxxRegisterExceptionObject", "_CxxThrowException", "__CxxUnregisterExceptionObject", "__DestructExceptionObject", "__doserrno", "_dosmaperr", "_EH_prolog", "_errno", "_except_handler", "_except_handler2", "_except_handler4_common", "_except1", "_filbuf", "_FindAndUnlinkFrame", "_flsbuf", "__fpe_flt_rounds", "_FPE_Raise", "__fpecode", "__FrameUnwindFilter", "_fread_nolock_s", "_free_base", "__free_locale", "_freea_s", "_freefls", "_ftol", "__get_current_locale", "__get_flsindex", "_get_initial_narrow_environment", "_get_initial_wide_environment", "_get_narrow_winmain_command_line", "_get_stream_buffer_pointers", "__get_tlsindex", "_get_wide_winmain_command_line", "_Getdays", "_Getmonths", "__GetPlatformExceptionInfo", "_getptd", "_Gettnames", "_global_unwind2", "_inconsistency", "__initenv", "_initialize_lconv_for_unsigned_char", "_initialize_narrow_environment", "_initialize_wide_environment", "_initptd", "_invalid_parameter", "_invoke_watson", "__iob_func", "_IsExceptionObjectToBeDestroyed", "__lconv", "__lconv_init", "__libm_sse2_acos", "_libm_sse2_acos_precise", "__libm_sse2_acosf", "__libm_sse2_asin", "_libm_sse2_asin_precise", "__libm_sse2_asinf", "__libm_sse2_atan", "_libm_sse2_atan_precise", "__libm_sse2_atan2", "__libm_sse2_atanf", "__libm_sse2_cos", "_libm_sse2_cos_precise", "__libm_sse2_cosf", "__libm_sse2_exp", "_libm_sse2_exp_precise", "__libm_sse2_expf", "__libm_sse2_log", "_libm_sse2_log_precise", "__libm_sse2_log10", "_libm_sse2_log10_precise", "__libm_sse2_log10f", "__libm_sse2_logf", "__libm_sse2_pow", "_libm_sse2_pow_precise", "__libm_sse2_powf", "__libm_sse2_sin", "_libm_sse2_sin_precise", "__libm_sse2_sinf", "_libm_sse2_sqrt_precise", "__libm_sse2_tan", "_libm_sse2_tan_precise", "__libm_sse2_tanf", "_local_unwind4", "_lock_locales", "_longjmpex", "_malloc_base", "_mbctype", "_NLG_Dispatch2", "_NLG_Return", "_NLG_Return2", "__p___argc", "__p___argv", "__p___initenv", "__p___wargv", "__p___winitenv", "__p__acmdln", "__p__crtAssertBusy", "__p__crtBreakAlloc", "__p__crtDbgFlag", "__p__daylight", "__p__dstbias", "__p__environ", "__p__iob", "__p__mbcasemap", "__p__mbctype", "__p__pctype", "__p__pgmptr", "__p__pwctype", "__p__timezone", "__p__tzname", "__p__wcmdln", "__p__wenviron", "__p__wpgmptr", "__pioinfo", "__pwctype_func", "__pxcptinfoptrs", "_query_app_type", "_realloc_base", "_register_thread_local_exe_atexit_callback", "__report_gsfailure", "__RTCastToVoid", "__RTtypeid", "_seh_filter_dll", "_seh_filter_exe", "_seh_longjmp_unwind", "_seh_longjmp_unwind4", "_set_malloc_crt_max_wait", "__setlc_active", "_SetWinRTOutOfMemoryExceptionCallback", "_sopen_dispatch", "__std_exception_copy", "__std_exception_destroy", "__std_type_info_destroy_list", "__stdio_common_vfprintf", "__stdio_common_vfprintf_p", "__stdio_common_vfprintf_s", "__stdio_common_vfscanf", "__stdio_common_vfwprintf", "__stdio_common_vfwprintf_p", "__stdio_common_vfwprintf_s", "__stdio_common_vfwscanf", "__stdio_common_vsnprintf_s", "__stdio_common_vsnwprintf_s", "__stdio_common_vsprintf", "__stdio_common_vsprintf_p", "__stdio_common_vsprintf_s", "__stdio_common_vsscanf", "__stdio_common_vswprintf", "__stdio_common_vswprintf_p", "__stdio_common_vswprintf_s", "__stdio_common_vswscanf", "_Strftime", "__STRINGTOLD", "__STRINGTOLD_L", "__strncnt", "__sys_errlist", "__sys_nerr", "__threadhandle", "__threadid", "__timezone", "__TypeMatch", "__tzname", "__unDName", "__unDNameEx", "__unDNameHelper", "__unguarded_readlc_active", "_unloaddll", "_unlock_locales", "_vacopy", "_ValidateExecute", "_ValidateRead", "_ValidateWrite", "_VCrtDbgReportA", "_VCrtDbgReportW", "_W_Getdays", "_W_Getmonths", "_W_Getnames", "_W_Gettnames", "_Wcsftime", "__wcsncnt", "__winitenv", "_wsopen_dispatch", "_Xbad_alloc", "_Xlength_error"] --- -# Internal CRT Globals and Functions +# Internal CRT globals and functions The C runtime (CRT) library contains functions and global variables that are used only to support the public library interface. Some of them are exposed in public headers as implementation details. Although these functions and global variables are accessible through public exports, they're not intended for use by your code. We recommend that you change any code that uses these functions and variables to use public library equivalents instead. These functions may change from version to version. They're listed here to help you identify them. Links are provided when other documentation exists, but in general, these implementation details aren't documented. -## Internal CRT Globals and Value Macros +## Internal CRT globals and value macros These global variables and macro definitions are used to implement the CRT. -|Name| -|----------| -|`__badioinfo`| -|[`_acmdln`](../c-runtime-library/acmdln-tcmdln-wcmdln.md)| -|`_commode`| -|`_crtAssertBusy`| -|`_crtBreakAlloc`| -|`__initenv`| -|`__lconv`| -|[`__mb_cur_max`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|`__pioinfo`| -|`__unguarded_readlc_active`| -|[`_wcmdln`](../c-runtime-library/acmdln-tcmdln-wcmdln.md)| -|`__winitenv`| +| Name | +|---| +| `__badioinfo` | +| [`_acmdln`](./acmdln-tcmdln-wcmdln.md) | +| `_commode` | +| `_crtAssertBusy` | +| `_crtBreakAlloc` | +| `__initenv` | +| `__lconv` | +| [`__mb_cur_max`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| `__pioinfo` | +| `__unguarded_readlc_active` | +| [`_wcmdln`](./acmdln-tcmdln-wcmdln.md) | +| `__winitenv` | -## Internal CRT Functions and Function Macros +## Internal CRT functions and function macros These functions and function macros are used to implement the CRT and the C++ Standard Library. -|Name| -|----------| -|`__acrt_iob_func`| -|`__AdjustPointer`| -|`_assert`| -|`__BuildCatchObject`| -|`__BuildCatchObjectHelper`| -|`__C_specific_handler`| -|`_calloc_base`| -|`_chkesp`| -|`__chkstk`| -|`_chkstk`| -|`_chvalidator`| -|`_chvalidator_l`| -|`_CIacos`| -|`_CIasin`| -|[`_CIatan`](../c-runtime-library/ciatan.md)| -|[`_CIatan2`](../c-runtime-library/ciatan2.md)| -|[`_CIcos`](../c-runtime-library/cicos.md)| -|`_CIcosh`| -|[`_CIexp`](../c-runtime-library/ciexp.md)| -|[`_CIfmod`](../c-runtime-library/cifmod.md)| -|[`_CIlog`](../c-runtime-library/cilog.md)| -|[`_CIlog10`](../c-runtime-library/cilog10.md)| -|[`_CIpow`](../c-runtime-library/cipow.md)| -|[`_CIsin`](../c-runtime-library/cisin.md)| -|`_CIsinh`| -|[`_CIsqrt`](../c-runtime-library/cisqrt.md)| -|[`_CItan`](../c-runtime-library/citan.md)| -|`_CItanh`| -|`__clean_type_info_names_internal`| -|`_configure_narrow_argv`| -|`_configure_wide_argv`| -|`__conio_common_vcprintf`| -|`__conio_common_vcprintf_p`| -|`__conio_common_vcprintf_s`| -|`__conio_common_vcscanf`| -|`__conio_common_vcwprintf`| -|`__conio_common_vcwprintf_p`| -|`__conio_common_vcwprintf_s`| -|`__conio_common_vcwscanf`| -|`__CppXcptFilter`| -|`__create_locale`| -|`_crt_atexit`| -|`_crt_at_quick_exit`| -|`__crtCompareStringA`| -|`__crtCompareStringEx`| -|`__crtCompareStringW`| -|`__crtCreateEventExW`| -|`__crtCreateSemaphoreExW`| -|`__crtCreateSymbolicLinkW`| -|`_crt_debugger_hook`| -|`__crtEnumSystemLocalesEx`| -|`__crtFlsAlloc`| -|`__crtFlsFree`| -|`__crtFlsGetValue`| -|`__crtFlsSetValue`| -|`_CrtGetCheckCount`| -|`__crtGetDateFormatEx`| -|`__crtGetFileInformationByHandleEx`| -|`__crtGetLocaleInfoEx`| -|`__crtGetShowWindowMode`| -|`__crtGetTickCount64`| -|`__crtGetTimeFormatEx`| -|`__crtGetUserDefaultLocaleName`| -|`__crtInitializeCriticalSectionEx`| -|`__crtIsPackagedApp`| -|`__crtIsValidLocaleName`| -|`__crtLCMapStringA`| -|`__crtLCMapStringEx`| -|[`__crtLCMapStringW`](../c-runtime-library/crtlcmapstringw.md)| -|`_CrtSetCheckCount`| -|`_CrtSetDbgBlockType`| -|`__crtSetFileInformationByHandle`| -|`__crtSetThreadStackGuarantee`| -|`__crtSetUnhandledExceptionFilter`| -|`__crtSleep`| -|`__crtTerminateProcess`| -|`__crtUnhandledException`| -|`__CxxDetectRethrow`| -|`__CxxExceptionFilter`| -|[`__CxxFrameHandler`](../c-runtime-library/cxxframehandler.md)| -|`__CxxFrameHandler2`| -|`__CxxFrameHandler3`| -|`__CxxLongjmpUnwind`| -|`__CxxQueryExceptionSize`| -|`__CxxRegisterExceptionObject`| -|`_CxxThrowException`| -|`__CxxUnregisterExceptionObject`| -|`__daylight`| -|`_dclass`| -|`__DestructExceptionObject`| -|[`__dllonexit`](../c-runtime-library/dllonexit.md)| -|`__doserrno`| -|`_dosmaperr`| -|`_dpcomp`| -|`_dsign`| -|`__dstbias`| -|`_dtest`| -|`_EH_prolog`| -|`_errno`| -|`_except_handler2`| -|[`_except_handler3`](../c-runtime-library/except-handler3.md)| -|`_except_handler4_common`| -|`_except1`| -|[`_execute_onexit_table`](../c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md)| -|`_fdclass`| -|`_fdpcomp`| -|`_fdsign`| -|`_fdtest`| -|`_filbuf`| -|`_FindAndUnlinkFrame`| -|`_flsbuf`| -|`__fpe_flt_rounds`| -|`_FPE_Raise`| -|`__fpecode`| -|`__FrameUnwindFilter`| -|`_fread_nolock_s`| -|`_free_base`| -|`__free_locale`| -|`_freea_s`| -|`_freefls`| -|`_ftol`| -|`__get_current_locale`| -|`__get_flsindex`| -|`_get_initial_narrow_environment`| -|`_get_initial_wide_environment`| -|`_get_narrow_winmain_command_line`| -|`_get_stream_buffer_pointers`| -|`__get_tlsindex`| -|`_get_wide_winmain_command_line`| -|`_Getdays`| -|[`__getmainargs`](../c-runtime-library/getmainargs-wgetmainargs.md)| -|`_Getmonths`| -|`__GetPlatformExceptionInfo`| -|`_getptd`| -|`_Gettnames`| -|`_global_unwind2`| -|`_inconsistency`| -|`_initialize_lconv_for_unsigned_char`| -|`_initialize_narrow_environment`| -|[`_initialize_onexit_table`](../c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md)| -|`_initialize_wide_environment`| -|`_initptd`| -|`_invalid_parameter`| -|`_invoke_watson`| -|`__iob_func`| -|`_IsExceptionObjectToBeDestroyed`| -|[`___lc_codepage_func`](../c-runtime-library/lc-codepage-func.md)| -|[`___lc_collate_cp_func`](../c-runtime-library/lc-collate-cp-func.md)| -|[`___lc_locale_name_func`](../c-runtime-library/lc-locale-name-func.md)| -|`__lconv_init`| -|`_ldclass`| -|`_ldpcomp`| -|`_ldsign`| -|`_ldtest`| -|`__libm_sse2_acos`| -|`_libm_sse2_acos_precise`| -|`__libm_sse2_acosf`| -|`__libm_sse2_asin`| -|`_libm_sse2_asin_precise`| -|`__libm_sse2_asinf`| -|`__libm_sse2_atan`| -|`_libm_sse2_atan_precise`| -|`__libm_sse2_atan2`| -|`__libm_sse2_atanf`| -|`__libm_sse2_cos`| -|`_libm_sse2_cos_precise`| -|`__libm_sse2_cosf`| -|`__libm_sse2_exp`| -|`_libm_sse2_exp_precise`| -|`__libm_sse2_expf`| -|`__libm_sse2_log`| -|`_libm_sse2_log_precise`| -|`__libm_sse2_log10`| -|`_libm_sse2_log10_precise`| -|`__libm_sse2_log10f`| -|`__libm_sse2_logf`| -|`__libm_sse2_pow`| -|`_libm_sse2_pow_precise`| -|`__libm_sse2_powf`| -|`__libm_sse2_sin`| -|`_libm_sse2_sin_precise`| -|`__libm_sse2_sinf`| -|`_libm_sse2_sqrt_precise`| -|`__libm_sse2_tan`| -|`_libm_sse2_tan_precise`| -|`__libm_sse2_tanf`| -|[`_local_unwind2`](../c-runtime-library/local-unwind2.md)| -|`_local_unwind4`| -|`_lock_locales`| -|`_longjmpex`| -|`_malloc_base`| -|[`___mb_cur_max_func`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|[`___mb_cur_max_l_func`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|`_mbctype`| -|`_NLG_Dispatch2`| -|`_NLG_Return`| -|`_NLG_Return2`| -|`__p___argc`| -|`__p___argv`| -|`__p___initenv`| -|[`__p___mb_cur_max`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)| -|`__p___wargv`| -|`__p___winitenv`| -|`__p__acmdln`| -|[`__p__commode`](../c-runtime-library/p-commode.md)| -|`__p__crtAssertBusy`| -|`__p__crtBreakAlloc`| -|`__p__crtDbgFlag`| -|`__p__daylight`| -|`__p__dstbias`| -|`__p__environ`| -|[`__p__fmode`](../c-runtime-library/p-fmode.md)| -|`__p__iob`| -|`__p__mbcasemap`| -|`__p__mbctype`| -|`__p__pctype`| -|`__p__pgmptr`| -|`__p__pwctype`| -|`__p__timezone`| -|`__p__tzname`| -|`__p__wcmdln`| -|`__p__wenviron`| -|`__p__wpgmptr`| -|`_pctype`| -|[`__pctype_func`](../c-runtime-library/pctype-func.md)| -|`_pwctype`| -|`__pwctype_func`| -|`__pxcptinfoptrs`| -|`_query_app_type`| -|`_realloc_base`| -|[`_register_onexit_function`](../c-runtime-library/execute-onexit-table-initialize-onexit-table-register-onexit-function.md)| -|`_register_thread_local_exe_atexit_callback`| -|`__report_gsfailure`| -|`__RTCastToVoid`| -|[`__RTDynamicCast`](../c-runtime-library/rtdynamiccast.md)| -|`__RTtypeid`| -|`_seh_filter_dll`| -|`_seh_filter_exe`| -|`_seh_longjmp_unwind`| -|`_seh_longjmp_unwind4`| -|[`__set_app_type`](../c-runtime-library/internal-set-app-type.md)| -|`_set_malloc_crt_max_wait`| -|[`_setjmp3`](../c-runtime-library/setjmp3.md)| -|`__setlc_active`| -|[`___setlc_active_func`](../c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md)| -|[`__setusermatherr`](../c-runtime-library/setusermatherr.md)| -|`_SetWinRTOutOfMemoryExceptionCallback`| -|`_sopen_dispatch`| -|`__std_exception_copy`| -|`__std_exception_destroy`| -|`__std_type_info_destroy_list`| -|`__std_type_info_name`| -|`__stdio_common_vfprintf`| -|`__stdio_common_vfprintf_p`| -|`__stdio_common_vfprintf_s`| -|`__stdio_common_vfscanf`| -|`__stdio_common_vfwprintf`| -|`__stdio_common_vfwprintf_p`| -|`__stdio_common_vfwprintf_s`| -|`__stdio_common_vfwscanf`| -|`__stdio_common_vsnprintf_s`| -|`__stdio_common_vsnwprintf_s`| -|`__stdio_common_vsprintf`| -|`__stdio_common_vsprintf_p`| -|`__stdio_common_vsprintf_s`| -|`__stdio_common_vsscanf`| -|`__stdio_common_vswprintf`| -|`__stdio_common_vswprintf_p`| -|`__stdio_common_vswprintf_s`| -|`__stdio_common_vswscanf`| -|`_Strftime`| -|`__STRINGTOLD`| -|`__STRINGTOLD_L`| -|`__strncnt`| -|`__sys_errlist`| -|`__sys_nerr`| -|`__threadhandle`| -|`__threadid`| -|`__timezone`| -|`__TypeMatch`| -|`__tzname`| -|`__unDName`| -|`__unDNameEx`| -|`__unDNameHelper`| -|`__unguarded_readlc_active`| -|[`___unguarded_readlc_active_add_func`](../c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md)| -|`_unloaddll`| -|`_unlock_locales`| -|`_vacopy`| -|`_ValidateExecute`| -|`_ValidateRead`| -|`_ValidateWrite`| -|`_VCrtDbgReportA`| -|`_VCrtDbgReportW`| -|`_W_Getdays`| -|`_W_Getmonths`| -|`_W_Getnames`| -|`_W_Gettnames`| -|`_wassert`| -|`_Wcsftime`| -|`__wcsncnt`| -|[`__wgetmainargs`](../c-runtime-library/getmainargs-wgetmainargs.md)| -|`_wsopen_dispatch`| -|`_Xbad_alloc`| -|`_Xlength_error`| +| Name | +|---| +| `__acrt_iob_func` | +| `__AdjustPointer` | +| `__BuildCatchObject` | +| `__BuildCatchObjectHelper` | +| [`__C_specific_handler`](/windows/win32/devnotes/--c-specific-handler2) | +| `_calloc_base` | +| `_chkesp` | +| `__chkstk` | +| `_chkstk` | +| `_chvalidator` | +| `_chvalidator_l` | +| `_CIacos` | +| `_CIasin` | +| [`_CIatan`](./ciatan.md) | +| [`_CIatan2`](./ciatan2.md) | +| [`_CIcos`](./cicos.md) | +| `_CIcosh` | +| [`_CIexp`](./ciexp.md) | +| [`_CIfmod`](./cifmod.md) | +| [`_CIlog`](./cilog.md) | +| [`_CIlog10`](./cilog10.md) | +| [`_CIpow`](./cipow.md) | +| [`_CIsin`](./cisin.md) | +| `_CIsinh` | +| [`_CIsqrt`](./cisqrt.md) | +| [`_CItan`](./citan.md) | +| `_CItanh` | +| `__clean_type_info_names_internal` | +| `_configure_narrow_argv` | +| `_configure_wide_argv` | +| `__conio_common_vcprintf` | +| `__conio_common_vcprintf_p` | +| `__conio_common_vcprintf_s` | +| `__conio_common_vcscanf` | +| `__conio_common_vcwprintf` | +| `__conio_common_vcwprintf_p` | +| `__conio_common_vcwprintf_s` | +| `__conio_common_vcwscanf` | +| `__CppXcptFilter` | +| `__create_locale` | +| `_crt_atexit` | +| `_crt_at_quick_exit` | +| `__crtCompareStringA` | +| `__crtCompareStringEx` | +| `__crtCompareStringW` | +| `__crtCreateEventExW` | +| `__crtCreateSemaphoreExW` | +| `__crtCreateSymbolicLinkW` | +| `_crt_debugger_hook` | +| `__crtEnumSystemLocalesEx` | +| `__crtFlsAlloc` | +| `__crtFlsFree` | +| `__crtFlsGetValue` | +| `__crtFlsSetValue` | +| `_CrtGetCheckCount` | +| `__crtGetDateFormatEx` | +| `__crtGetFileInformationByHandleEx` | +| `__crtGetLocaleInfoEx` | +| `__crtGetShowWindowMode` | +| `__crtGetTickCount64` | +| `__crtGetTimeFormatEx` | +| `__crtGetUserDefaultLocaleName` | +| `__crtInitializeCriticalSectionEx` | +| `__crtIsPackagedApp` | +| `__crtIsValidLocaleName` | +| `__crtLCMapStringA` | +| `__crtLCMapStringEx` | +| [`__crtLCMapStringW`](./crtlcmapstringw.md) | +| `_CrtSetCheckCount` | +| `_CrtSetDbgBlockType` | +| `__crtSetFileInformationByHandle` | +| `__crtSetThreadStackGuarantee` | +| `__crtSetUnhandledExceptionFilter` | +| `__crtSleep` | +| `__crtTerminateProcess` | +| `__crtUnhandledException` | +| `__CxxDetectRethrow` | +| `__CxxExceptionFilter` | +| [`__CxxFrameHandler`](./cxxframehandler.md) | +| `__CxxFrameHandler2` | +| `__CxxFrameHandler3` | +| `__CxxLongjmpUnwind` | +| `__CxxQueryExceptionSize` | +| `__CxxRegisterExceptionObject` | +| `_CxxThrowException` | +| `__CxxUnregisterExceptionObject` | +| [`_dclass`](./reference/floating-point-primitives.md) | +| `__DestructExceptionObject` | +| [`__dllonexit`](./dllonexit.md) | +| `__doserrno` | +| `_dosmaperr` | +| [`_dpcomp`](./reference/floating-point-primitives.md) | +| [`_dsign`](./reference/floating-point-primitives.md) | +| [`__dstbias`](./reference/get-dstbias.md) | +| [`_dtest`](./reference/floating-point-primitives.md) | +| `_EH_prolog` | +| [`_errno`](./errno-doserrno-sys-errlist-and-sys-nerr.md) | +| `_except_handler` | +| `_except_handler2` | +| [`_except_handler3`](./except-handler3.md) | +| `_except_handler4_common` | +| `_except1` | +| [`_execute_onexit_table`](./execute-onexit-table-initialize-onexit-table-register-onexit-function.md) | +| [`_fdclass`](./reference/floating-point-primitives.md) | +| [`_fdpcomp`](./reference/floating-point-primitives.md) | +| [`_fdsign`](./reference/floating-point-primitives.md) | +| [`_fdtest`](./reference/floating-point-primitives.md) | +| `_filbuf` | +| `_FindAndUnlinkFrame` | +| `_flsbuf` | +| `__fpe_flt_rounds` | +| `_FPE_Raise` | +| `__fpecode` | +| `__FrameUnwindFilter` | +| `_fread_nolock_s` | +| `_free_base` | +| `__free_locale` | +| `_freea_s` | +| `_freefls` | +| `_ftol` | +| `__get_current_locale` | +| `__get_flsindex` | +| `_get_initial_narrow_environment` | +| `_get_initial_wide_environment` | +| `_get_narrow_winmain_command_line` | +| `_get_stream_buffer_pointers` | +| `__get_tlsindex` | +| `_get_wide_winmain_command_line` | +| `_Getdays` | +| [`__getmainargs`](./getmainargs-wgetmainargs.md) | +| `_Getmonths` | +| `__GetPlatformExceptionInfo` | +| `_getptd` | +| `_Gettnames` | +| `_global_unwind2` | +| `_inconsistency` | +| `_initialize_lconv_for_unsigned_char` | +| `_initialize_narrow_environment` | +| [`_initialize_onexit_table`](./execute-onexit-table-initialize-onexit-table-register-onexit-function.md) | +| `_initialize_wide_environment` | +| `_initptd` | +| `_invalid_parameter` | +| `_invoke_watson` | +| `__iob_func` | +| `_IsExceptionObjectToBeDestroyed` | +| [`___lc_codepage_func`](./lc-codepage-func.md) | +| [`___lc_collate_cp_func`](./lc-collate-cp-func.md) | +| [`___lc_locale_name_func`](./lc-locale-name-func.md) | +| `__lconv_init` | +| [`_ldclass`](./reference/floating-point-primitives.md) | +| [`_ldpcomp`](./reference/floating-point-primitives.md) | +| [`_ldsign`](./reference/floating-point-primitives.md) | +| [`_ldtest`](./reference/floating-point-primitives.md) | +| `__libm_sse2_acos` | +| `_libm_sse2_acos_precise` | +| `__libm_sse2_acosf` | +| `__libm_sse2_asin` | +| `_libm_sse2_asin_precise` | +| `__libm_sse2_asinf` | +| `__libm_sse2_atan` | +| `_libm_sse2_atan_precise` | +| `__libm_sse2_atan2` | +| `__libm_sse2_atanf` | +| `__libm_sse2_cos` | +| `_libm_sse2_cos_precise` | +| `__libm_sse2_cosf` | +| `__libm_sse2_exp` | +| `_libm_sse2_exp_precise` | +| `__libm_sse2_expf` | +| `__libm_sse2_log` | +| `_libm_sse2_log_precise` | +| `__libm_sse2_log10` | +| `_libm_sse2_log10_precise` | +| `__libm_sse2_log10f` | +| `__libm_sse2_logf` | +| `__libm_sse2_pow` | +| `_libm_sse2_pow_precise` | +| `__libm_sse2_powf` | +| `__libm_sse2_sin` | +| `_libm_sse2_sin_precise` | +| `__libm_sse2_sinf` | +| `_libm_sse2_sqrt_precise` | +| `__libm_sse2_tan` | +| `_libm_sse2_tan_precise` | +| `__libm_sse2_tanf` | +| [`_local_unwind2`](./local-unwind2.md) | +| `_local_unwind4` | +| `_lock_locales` | +| `_longjmpex` | +| `_malloc_base` | +| [`___mb_cur_max_func`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| [`___mb_cur_max_l_func`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| `_mbctype` | +| `_NLG_Dispatch2` | +| `_NLG_Return` | +| `_NLG_Return2` | +| `__p___argc` | +| `__p___argv` | +| `__p___initenv` | +| [`__p___mb_cur_max`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md) | +| `__p___wargv` | +| `__p___winitenv` | +| `__p__acmdln` | +| [`__p__commode`](./p-commode.md) | +| `__p__crtAssertBusy` | +| `__p__crtBreakAlloc` | +| `__p__crtDbgFlag` | +| `__p__daylight` | +| `__p__dstbias` | +| `__p__environ` | +| [`__p__fmode`](./p-fmode.md) | +| `__p__iob` | +| `__p__mbcasemap` | +| `__p__mbctype` | +| `__p__pctype` | +| `__p__pgmptr` | +| `__p__pwctype` | +| `__p__timezone` | +| `__p__tzname` | +| `__p__wcmdln` | +| `__p__wenviron` | +| `__p__wpgmptr` | +| [`_pctype`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) | +| [`__pctype_func`](./pctype-func.md) | +| [`_pwctype`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) | +| `__pwctype_func` | +| `__pxcptinfoptrs` | +| `_query_app_type` | +| `_realloc_base` | +| [`_register_onexit_function`](./execute-onexit-table-initialize-onexit-table-register-onexit-function.md) | +| `_register_thread_local_exe_atexit_callback` | +| `__report_gsfailure` | +| `__RTCastToVoid` | +| [`__RTDynamicCast`](./rtdynamiccast.md) | +| `__RTtypeid` | +| `_seh_filter_dll` | +| `_seh_filter_exe` | +| `_seh_longjmp_unwind` | +| `_seh_longjmp_unwind4` | +| [`__set_app_type`](./internal-set-app-type.md) | +| `_set_malloc_crt_max_wait` | +| [`_setjmp3`](./setjmp3.md) | +| `__setlc_active` | +| [`___setlc_active_func`](./setlc-active-func-unguarded-readlc-active-add-func.md) | +| [`__setusermatherr`](./setusermatherr.md) | +| `_SetWinRTOutOfMemoryExceptionCallback` | +| `_sopen_dispatch` | +| `__std_exception_copy` | +| `__std_exception_destroy` | +| `__std_type_info_destroy_list` | +| `__std_type_info_name` | +| `__stdio_common_vfprintf` | +| `__stdio_common_vfprintf_p` | +| `__stdio_common_vfprintf_s` | +| `__stdio_common_vfscanf` | +| `__stdio_common_vfwprintf` | +| `__stdio_common_vfwprintf_p` | +| `__stdio_common_vfwprintf_s` | +| `__stdio_common_vfwscanf` | +| `__stdio_common_vsnprintf_s` | +| `__stdio_common_vsnwprintf_s` | +| `__stdio_common_vsprintf` | +| `__stdio_common_vsprintf_p` | +| `__stdio_common_vsprintf_s` | +| `__stdio_common_vsscanf` | +| `__stdio_common_vswprintf` | +| `__stdio_common_vswprintf_p` | +| `__stdio_common_vswprintf_s` | +| `__stdio_common_vswscanf` | +| `_Strftime` | +| `__STRINGTOLD` | +| `__STRINGTOLD_L` | +| `__strncnt` | +| `__sys_errlist` | +| `__sys_nerr` | +| `__threadhandle` | +| `__threadid` | +| `__timezone` | +| `__TypeMatch` | +| `__tzname` | +| `__unDName` | +| `__unDNameEx` | +| `__unDNameHelper` | +| `__unguarded_readlc_active` | +| [`___unguarded_readlc_active_add_func`](./setlc-active-func-unguarded-readlc-active-add-func.md) | +| `_unloaddll` | +| `_unlock_locales` | +| `_vacopy` | +| `_ValidateExecute` | +| `_ValidateRead` | +| `_ValidateWrite` | +| `_VCrtDbgReportA` | +| `_VCrtDbgReportW` | +| `_W_Getdays` | +| `_W_Getmonths` | +| `_W_Getnames` | +| `_W_Gettnames` | +| `_Wcsftime` | +| `__wcsncnt` | +| [`__wgetmainargs`](./getmainargs-wgetmainargs.md) | +| `_wsopen_dispatch` | +| `_Xbad_alloc` | +| `_Xlength_error` | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/internal-set-app-type.md b/docs/c-runtime-library/internal-set-app-type.md index 9a86584f3ab..bdf12cb0d35 100644 --- a/docs/c-runtime-library/internal-set-app-type.md +++ b/docs/c-runtime-library/internal-set-app-type.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: __set_app_type" title: "__set_app_type" -ms.date: "11/04/2016" +description: "Learn more about: __set_app_type" +ms.date: 11/04/2016 api_name: ["__set_app_type", "_set_app_type"] api_location: ["msvcr90.dll", "msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcrt.dll", "msvcr120.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__set_app_type"] helpviewer_keywords: ["__set_app_type"] -ms.assetid: f0ac0f4d-70e6-4e96-9e43-eb9d1515490c --- -# __set_app_type +# `__set_app_type` -Sets the current application type. +Sets the current application type. This internal function is obsolete. ## Syntax @@ -22,21 +21,19 @@ void __set_app_type ( ) ``` -#### Parameters +### Parameters -*at*
+*`at`*\ A value that indicates the application type. The possible values are: -|Value|Description| -|-----------|-----------------| -|_UNKNOWN_APP|Unknown application type.| -|_CONSOLE_APP|Console (command-line) application.| -|_GUI_APP|GUI (Windows) application.| - -## Remarks +| Value | Description | +|---|---| +| `_UNKNOWN_APP` | Unknown application type. | +| `_CONSOLE_APP` | Console (command-line) application. | +| `_GUI_APP` | GUI (Windows) application. | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__set_app_type|internal.h| +| Routine | Required header | +|---|---| +| **`__set_app_type`** | `internal.h` | diff --git a/docs/c-runtime-library/internationalization.md b/docs/c-runtime-library/internationalization.md index e22e1915491..93d47d0e917 100644 --- a/docs/c-runtime-library/internationalization.md +++ b/docs/c-runtime-library/internationalization.md @@ -2,7 +2,7 @@ title: "Internationalization" ms.date: "09/29/2020" description: "A description of Microsoft runtime library support for writing apps for international markets." -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["localization, routines for", "locale-dependent routines", "internationalization routines", "international applications, run-time routines for"] ms.assetid: ee536a04-3558-4729-8e10-6dabcde055fd --- @@ -11,7 +11,7 @@ ms.assetid: ee536a04-3558-4729-8e10-6dabcde055fd The Microsoft runtime library provides many routines that you can use to customize your app for international markets such as: -- [locale-related routines](../c-runtime-library/locale.md) +- [locale-related routines](./locale.md) - wide-character routines - multibyte-character routines - generic-text routines @@ -24,4 +24,4 @@ ISO646 operator alternatives are also included. ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md b/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md index d33d043d0ec..63a877ee60b 100644 --- a/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md +++ b/docs/c-runtime-library/interpretation-of-multibyte-character-sequences.md @@ -8,27 +8,27 @@ ms.assetid: da9150de-70ea-4d2f-90e6-ddb9202dd80b --- # Interpretation of multibyte-character sequences -Most multibyte-character routines in the Microsoft run-time library recognize multibyte-character sequences relating to a multibyte code page. The output value is affected by the setting of the **LC_CTYPE** category setting of the locale. For more information, see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior. The versions with the **_l** suffix are identical, except they use the locale parameter instead of the current locale. +Most multibyte-character routines in the Microsoft run-time library recognize multibyte-character sequences relating to a multibyte code page. The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior. The versions with the `_l` suffix are identical, except they use the locale parameter instead of the current locale. ## Locale-dependent multibyte routines -|Routine|Use| -|-------------|---------| -|[_mbclen, mblen, _mblen_l](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)|Validate and return number of bytes in multibyte character| -|[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)|For multibyte character strings: validate each character in string; return string length. For wide character strings: return string length.| -|[mbstowcs, _mbstowcs_l](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md), [mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert sequence of multibyte characters to corresponding sequence of wide characters| -|[mbtowc, _mbtowc_l](../c-runtime-library/reference/mbtowc-mbtowc-l.md)|Convert multibyte character to corresponding wide character| -|[wcstombs, _wcstombs_l](../c-runtime-library/reference/wcstombs-wcstombs-l.md), [wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert sequence of wide characters to corresponding sequence of multibyte characters| -|[wctomb, _wctomb_l](../c-runtime-library/reference/wctomb-wctomb-l.md), [wctomb_s, _wctomb_s_l](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert wide character to corresponding multibyte character| +| Routine | Use | +|---|---| +| [`_mbclen`, `mblen`, `_mblen_l`](./reference/mbclen-mblen-mblen-l.md) | Validate and return number of bytes in multibyte character | +| [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](./reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) | For multibyte character strings: validate each character in string; return string length. For wide character strings: return string length. | +| [`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md), [`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) | Convert sequence of multibyte characters to corresponding sequence of wide characters | +| [`mbtowc`, `_mbtowc_l`](./reference/mbtowc-mbtowc-l.md) | Convert multibyte character to corresponding wide character | +| [`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md), [`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) | Convert sequence of wide characters to corresponding sequence of multibyte characters | +| [`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md), [`wctomb_s`, `_wctomb_s_l`](./reference/wctomb-s-wctomb-s-l.md) | Convert wide character to corresponding multibyte character | ## Locale-independent multibyte routines -|Routine|Use| -|-------------|---------| -|[mbrtoc16, mbrtoc32](../c-runtime-library/reference/mbrtoc16-mbrtoc323.md)|Convert multibyte UTF-8 character to equivalent UTF-16 or UTF-32 character| -|[c16rtomb, c32rtomb](../c-runtime-library/reference/c16rtomb-c32rtomb1.md)|Convert UTF-16 or UTF-32 character to equivalent UTF-8 multibyte character| +| Routine | Use | +|---|---| +| [`mbrtoc16`, `mbrtoc32`](./reference/mbrtoc16-mbrtoc323.md) | Convert multibyte UTF-8 character to equivalent UTF-16 or UTF-32 character | +| [`c16rtomb`, `c32rtomb`](./reference/c16rtomb-c32rtomb1.md) | Convert UTF-16 or UTF-32 character to equivalent UTF-8 multibyte character | ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/iob.md b/docs/c-runtime-library/iob.md index 14418570e93..9341f6b617d 100644 --- a/docs/c-runtime-library/iob.md +++ b/docs/c-runtime-library/iob.md @@ -1,29 +1,32 @@ --- description: "Learn more about: _iob" title: "_iob" -ms.date: "11/04/2016" +ms.date: 07/10/2023 api_name: ["_iob"] api_location: ["msvcrt.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_iob", "iob"] +f1_keywords: ["_iob", "_IOB_ENTRIES", "STDIO/_IOB_ENTRIES"] helpviewer_keywords: ["_iob global variable", "iob global variable"] -ms.assetid: 008ed376-8078-4bbd-bc6c-0677c63d0ff1 --- -# _iob +# `_iob` -The array of stdio control structures. +The array of `stdio` control structures. ## Syntax -``` +```C FILE _iob[_IOB_ENTRIES]; ``` ## Remarks -`IOB_ENTRIES` is defined as 20 in stdio.h. +Starting with Visual Studio 2015, `_IOB_ENTRIES` is defined as 3 with the introduction of the Universal CRT. +It was previously defined as 20. + +Defined in `stdio.h`. ## See also -[Global Variables](../c-runtime-library/global-variables.md) +[Global variables](./global-variables.md)\ +[Introducing the Universal CRT](https://devblogs.microsoft.com/cppblog/introducing-the-universal-crt/) diff --git a/docs/c-runtime-library/is-isw-routines.md b/docs/c-runtime-library/is-isw-routines.md index 96e98fcb4ff..84eb09729b9 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"] --- @@ -8,22 +8,22 @@ helpviewer_keywords: ["is routines", "isw routines"] :::row::: :::column span=""::: - [`isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l`](../c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md)\ - [`isalpha`, `iswalpha`, `_isalpha_l`, `_iswalpha_l`](../c-runtime-library/reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md)\ - [`isascii`, _`_isascii`, `iswascii`](../c-runtime-library/reference/isascii-isascii-iswascii.md)\ - [`isblank`, `iswblank`, `_isblank_l`, `_iswblank_l`](../c-runtime-library/reference/isblank-iswblank-isblank-l-iswblank-l.md)\ - [`iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l`](../c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md)\ - [`iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l`](../c-runtime-library/reference/iscsym-functions.md)\ - [`_isctype`, `iswctype`, `_isctype_l`, `_iswctype_l`](../c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md)\ - [`isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l`](../c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md) - [`isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l`](../c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md)\ - [`isleadbyte`, `_isleadbyte_l`](../c-runtime-library/reference/isleadbyte-isleadbyte-l.md)\ - [`islower`, `iswlower`, `_islower_l`, `_iswlower_l`](../c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md)\ - [`isprint`, `iswprint`, `_isprint_l`, `_iswprint_l`](../c-runtime-library/reference/isprint-iswprint-isprint-l-iswprint-l.md)\ - [`ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l`](../c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md)\ - [`isspace`, `iswspace`, `_isspace_l`, `_iswspace_l`](../c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md)\ - [`isupper`, `_isupper_l`, `iswupper`, `_iswupper_l`](../c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md)\ - [`isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l`](../c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md) + [`isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l`](./reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md)\ + [`isalpha`, `iswalpha`, `_isalpha_l`, `_iswalpha_l`](./reference/isalpha-iswalpha-isalpha-l-iswalpha-l.md)\ + [`isascii`, `__isascii`, `iswascii`](./reference/isascii-isascii-iswascii.md)\ + [`isblank`, `iswblank`, `_isblank_l`, `_iswblank_l`](./reference/isblank-iswblank-isblank-l-iswblank-l.md)\ + [`iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l`](./reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md)\ + [`iscsym`, `iscsymf`, `__iscsym`, `__iswcsym`, `__iscsymf`, `__iswcsymf`, `_iscsym_l`, `_iswcsym_l`, `_iscsymf_l`, `_iswcsymf_l`](./reference/iscsym-functions.md)\ + [`_isctype`, `iswctype`, `_isctype_l`, `_iswctype_l`](./reference/isctype-iswctype-isctype-l-iswctype-l.md)\ + [`isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l`](./reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md)\ + [`isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l`](./reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md)\ + [`isleadbyte`, `_isleadbyte_l`](./reference/isleadbyte-isleadbyte-l.md)\ + [`islower`, `iswlower`, `_islower_l`, `_iswlower_l`](./reference/islower-iswlower-islower-l-iswlower-l.md)\ + [`isprint`, `iswprint`, `_isprint_l`, `_iswprint_l`](./reference/isprint-iswprint-isprint-l-iswprint-l.md)\ + [`ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l`](./reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md)\ + [`isspace`, `iswspace`, `_isspace_l`, `_iswspace_l`](./reference/isspace-iswspace-isspace-l-iswspace-l.md)\ + [`isupper`, `_isupper_l`, `iswupper`, `_iswupper_l`](./reference/isupper-isupper-l-iswupper-iswupper-l.md)\ + [`isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l`](./reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md) :::column-end::: :::row-end::: @@ -38,7 +38,7 @@ The `is` routines produce meaningful results for any integer argument from -1 (` The `isw` routines produce meaningful results for any integer value from -1 (`WEOF`) to 0xFFFF, inclusive. The `wint_t` data type is defined in `` as an **`unsigned short`**. It can hold any wide character or the wide-character end-of-file (`WEOF`) value. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. In the "C" locale, the test conditions for the `is` routines are as follows: @@ -126,7 +126,6 @@ Character has property specified by the `desc` argument. For each valid value of | `_LOWER` | `iswlower(c)` | | `_ALPHA | _BLANK | _DIGIT | _PUNCT` | `iswprint(c)` | | `_PUNCT` | `iswpunct(c)` | -| `_BLANK` | `iswblank(c)` | | `_SPACE` | `iswspace(c)` | | `_UPPER` | `iswupper(c)` | | `_HEX` | `iswxdigit(c)` | @@ -328,8 +327,8 @@ int main( void ) ## See also -[Character classification](../c-runtime-library/character-classification.md)\ -[Locale](../c-runtime-library/locale.md)\ -[`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md)\ -[Interpretation of multibyte-character sequences](../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ -[`to` Functions](../c-runtime-library/to-functions.md) +[Character classification](./character-classification.md)\ +[Locale](./locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[Interpretation of multibyte-character sequences](./interpretation-of-multibyte-character-sequences.md)\ +[`to` functions](./to-functions.md) diff --git a/docs/c-runtime-library/ismbb-routines.md b/docs/c-runtime-library/ismbb-routines.md index 38b9d7044b4..328cb2d6977 100644 --- a/docs/c-runtime-library/ismbb-routines.md +++ b/docs/c-runtime-library/ismbb-routines.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _ismbb routines" title: "_ismbb routines" +description: "Learn more about: _ismbb routines" ms.date: 01/11/2022 helpviewer_keywords: ["ismbb routines", "_ismbb routines"] --- @@ -10,43 +10,43 @@ Tests the given integer value `c` for a particular condition, by using the curre :::row::: :::column span=""::: - [`_ismbbalnum`, `_ismbbalnum_l`](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md)\ - [`_ismbbalpha`, `_ismbbalpha_l`](../c-runtime-library/reference/ismbbalpha-ismbbalpha-l.md)\ - [`_ismbbblank`, `_ismbbblank_l`](../c-runtime-library/reference/ismbbblank-ismbbblank-l.md)\ - [`_ismbbgraph`, `_ismbbgraph_l`](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md)\ - [`_ismbbkalnum`, `_ismbbkalnum_l`](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md)\ - [`_ismbbkana`, `_ismbbkana_l`](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md)\ - [`_ismbbkprint`, `_ismbbkprint_l`](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md)\ - [`_ismbbkpunct`, `_ismbbkpunct_l`](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md)\ - [`_ismbblead`, `_ismbblead_l`](../c-runtime-library/reference/ismbblead-ismbblead-l.md)\ - [`_ismbbprint`, `_ismbbprint_l`](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md)\ - [`_ismbbpunct`, `_ismbbpunct_l`](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md)\ - [`_ismbbtrail`, `_ismbbtrail_l`](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md)\ + [`_ismbbalnum`, `_ismbbalnum_l`](./reference/ismbbalnum-ismbbalnum-l.md)\ + [`_ismbbalpha`, `_ismbbalpha_l`](./reference/ismbbalpha-ismbbalpha-l.md)\ + [`_ismbbblank`, `_ismbbblank_l`](./reference/ismbbblank-ismbbblank-l.md)\ + [`_ismbbgraph`, `_ismbbgraph_l`](./reference/ismbbgraph-ismbbgraph-l.md)\ + [`_ismbbkalnum`, `_ismbbkalnum_l`](./reference/ismbbkalnum-ismbbkalnum-l.md)\ + [`_ismbbkana`, `_ismbbkana_l`](./reference/ismbbkana-ismbbkana-l.md)\ + [`_ismbbkprint`, `_ismbbkprint_l`](./reference/ismbbkprint-ismbbkprint-l.md)\ + [`_ismbbkpunct`, `_ismbbkpunct_l`](./reference/ismbbkpunct-ismbbkpunct-l.md)\ + [`_ismbblead`, `_ismbblead_l`](./reference/ismbblead-ismbblead-l.md)\ + [`_ismbbprint`, `_ismbbprint_l`](./reference/ismbbprint-ismbbprint-l.md)\ + [`_ismbbpunct`, `_ismbbpunct_l`](./reference/ismbbpunct-ismbbpunct-l.md)\ + [`_ismbbtrail`, `_ismbbtrail_l`](./reference/ismbbtrail-ismbbtrail-l.md) :::column-end::: :::row-end::: ## Remarks -Every routine in the `_ismbb` family tests the given integer value `c` for a particular condition. The test result depends on the multibyte code page that's in effect. By default, the multibyte code page is set to the ANSI code page that's obtained from the operating system at program startup. You can use [`_getmbcp`](../c-runtime-library/reference/getmbcp.md) to query for the multibyte code page that's in use, or [`_setmbcp`](../c-runtime-library/reference/setmbcp.md) to change it. +Every routine in the `_ismbb` family tests the given integer value `c` for a particular condition. The test result depends on the multibyte code page that's in effect. By default, the multibyte code page is set to the ANSI code page that's obtained from the operating system at program startup. You can use [`_getmbcp`](./reference/getmbcp.md) to query for the multibyte code page that's in use, or [`_setmbcp`](./reference/setmbcp.md) to change it. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md). The versions of these functions that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions that do have the **`_l`** suffix are identical except that instead they use the locale parameter that's passed in. +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md). The versions of these functions that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions that do have the **`_l`** suffix are identical except that instead they use the locale parameter that's passed in. The routines in the `_ismbb` family test the given integer `c` as follows. | Routine | Byte test condition | |--|--| -| [`_ismbbalnum`](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md) | `isalnum(c) || _ismbbkalnum(c)` | +| [`_ismbbalnum`](./reference/ismbbalnum-ismbbalnum-l.md) | `isalnum(c) || _ismbbkalnum(c)` | | [`_ismbbalpha`](reference/ismbbalpha-ismbbalpha-l.md) | `isalpha(c) || _ismbbkalpha(c)` | -| [`_ismbbblank`](../c-runtime-library/reference/ismbbblank-ismbbblank-l.md) | `isblank(c)` | -| [`_ismbbgraph`](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md) | Same as `_ismbbprint`, but `_ismbbgraph` doesn't include the space character (0x20) | -| [`_ismbbkalnum`](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md) | Non-ASCII text symbol other than punctuation. For example, in code page 932 only, `_ismbbkalnum` tests for katakana alphanumeric | -| [`_ismbbkana`](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md) | Katakana (0xA1 - 0xDF). Specific to code page 932 | -| [`_ismbbkprint`](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md) | Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, `_ismbbkprint` tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF) | -| [`_ismbbkpunct`](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md) | Non-ASCII punctuation. For example, in code page 932 only, `_ismbbkpunct` tests for katakana punctuation | -| [`_ismbblead`](../c-runtime-library/reference/ismbblead-ismbblead-l.md) | First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC | -| [`_ismbbprint`](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md) | `isprint(c) || _ismbbkprint(c)`. `ismbbprint` includes the space character (0x20) | -| [`_ismbbpunct`](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md) | `ispunct(c) || _ismbbkpunct(c)`. | -| [`_ismbbtrail`](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md) | Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC | +| [`_ismbbblank`](./reference/ismbbblank-ismbbblank-l.md) | `isblank(c)` | +| [`_ismbbgraph`](./reference/ismbbgraph-ismbbgraph-l.md) | Same as `_ismbbprint`, but `_ismbbgraph` doesn't include the space character (0x20) | +| [`_ismbbkalnum`](./reference/ismbbkalnum-ismbbkalnum-l.md) | Non-ASCII text symbol other than punctuation. For example, in code page 932 only, `_ismbbkalnum` tests for katakana alphanumeric | +| [`_ismbbkana`](./reference/ismbbkana-ismbbkana-l.md) | Katakana (0xA1 - 0xDF). Specific to code page 932 | +| [`_ismbbkprint`](./reference/ismbbkprint-ismbbkprint-l.md) | Non-ASCII text or non-ASCII punctuation symbol. For example, in code page 932 only, `_ismbbkprint` tests for katakana alphanumeric or katakana punctuation (range: 0xA1 - 0xDF) | +| [`_ismbbkpunct`](./reference/ismbbkpunct-ismbbkpunct-l.md) | Non-ASCII punctuation. For example, in code page 932 only, `_ismbbkpunct` tests for katakana punctuation | +| [`_ismbblead`](./reference/ismbblead-ismbblead-l.md) | First byte of multibyte character. For example, in code page 932 only, valid ranges are 0x81 - 0x9F, 0xE0 - 0xFC | +| [`_ismbbprint`](./reference/ismbbprint-ismbbprint-l.md) | `isprint(c) || _ismbbkprint(c)`. `ismbbprint` includes the space character (0x20) | +| [`_ismbbpunct`](./reference/ismbbpunct-ismbbpunct-l.md) | `ispunct(c) || _ismbbkpunct(c)`. | +| [`_ismbbtrail`](./reference/ismbbtrail-ismbbtrail-l.md) | Second byte of multibyte character. For example, in code page 932 only, valid ranges are 0x40 - 0x7E, 0x80 - 0xEC | The following table shows the `|`-combined values that compose the test conditions for these routines. The manifest constants `_BLANK`, `_DIGIT`, `_LOWER`, `_PUNCT`, and `_UPPER` are defined in *`ctype.h`*. @@ -62,11 +62,11 @@ The following table shows the `|`-combined values that compose the test conditio | `_ismbbprint` | x | x | x | x | x | x | x | | `_ismbbpunct` | — | — | — | x | — | — | x | -The `_ismbb` routines are implemented both as functions and as macros. For more information about how to choose either implementation, see [Recommendations for choosing between functions and macros](../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md). +The `_ismbb` routines are implemented both as functions and as macros. For more information about how to choose either implementation, see [Recommendations for choosing between functions and macros](./recommendations-for-choosing-between-functions-and-macros.md). ## See also -[Byte classification](../c-runtime-library/byte-classification.md)\ -[`is`, `isw` routines](../c-runtime-library/is-isw-routines.md)\ -[`_mbbtombc`, `_mbbtombc_l`](../c-runtime-library/reference/mbbtombc-mbbtombc-l.md)\ -[`_mbctombb`, `_mbctombb_l`](../c-runtime-library/reference/mbctombb-mbctombb-l.md) +[Byte classification](./byte-classification.md)\ +[`is`, `isw` routines](./is-isw-routines.md)\ +[`_mbbtombc`, `_mbbtombc_l`](./reference/mbbtombc-mbbtombc-l.md)\ +[`_mbctombb`, `_mbctombb_l`](./reference/mbctombb-mbctombb-l.md) diff --git a/docs/c-runtime-library/ismbc-routines.md b/docs/c-runtime-library/ismbc-routines.md index 84105455001..7c7a33362cb 100644 --- a/docs/c-runtime-library/ismbc-routines.md +++ b/docs/c-runtime-library/ismbc-routines.md @@ -1,68 +1,59 @@ --- -description: "Learn more about: _ismbc Routines" title: "_ismbc Routines" +description: "Learn more about: _ismbc Routines" ms.date: "11/04/2016" -api_location: ["msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcrt.dll", "msvcr90.dll", "msvcr120.dll", "msvcr80.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] -f1_keywords: ["_ismbc"] helpviewer_keywords: ["ismbc routines", "_ismbc routines"] -ms.assetid: b8995391-7857-4ac3-9a1e-de946eb4464d --- -# _ismbc Routines +# `_ismbc` routines -Each **_ismbc** routine tests a given multibyte character `c` for a particular condition. +Each `_ismbc` routine tests a given multibyte character `c` for a particular condition. -:::row::: - :::column span=""::: - [_ismbcalnum, _ismbcalnum_l, _ismbcalpha, _ismbcalpha_l, _ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)\ - [_ismbcl0, _ismbcl0_l, _ismbcl1, _ismbcl1_l, _ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)\ - [_ismbcgraph, _ismbcgraph_l, _ismbcprint, _ismbcprint_l, _ismbcpunct, _ismbcpunct_l, _ismbcblank, _ismbcblank_l, _ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)\ - [_ismbclegal, _ismbclegal_l, _ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)\ - [_ismbchira, _ismbchira_l, _ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)\ - [_ismbclower, _ismbclower_l, _ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) - :::column-end::: -:::row-end::: +- [`_ismbcalnum`, `_ismbcalnum_l`, `_ismbcalpha`, `_ismbcalpha_l`, `_ismbcdigit`, `_ismbcdigit_l`](reference/ismbcalnum-functions.md) +- [`_ismbcl0`, `_ismbcl0_l`, `_ismbcl1`, `_ismbcl1_l`, `_ismbcl2`, `_ismbcl2_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) +- [`_ismbcgraph`, `_ismbcgraph_l`, `_ismbcprint`, `_ismbcprint_l`, `_ismbcpunct`, `_ismbcpunct_l`, `_ismbcblank`, `_ismbcblank_l`, `_ismbcspace`, `_ismbcspace_l`](reference/ismbcgraph-functions.md) +- [`_ismbclegal`, `_ismbclegal_l`, `_ismbcsymbol`, `_ismbcsymbol_l`](reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) +- [`_ismbchira`, `_ismbchira_l`, `_ismbckata`, `_ismbckata_l`](reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) +- [`_ismbclower`, `_ismbclower_l`, `_ismbcupper`, `_ismbcupper_l`](reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) ## Remarks -The test result of each **_ismbc** routine depends on the multibyte code page in effect. Multibyte code pages have single-byte alphabetic characters. By default, the multibyte code page is set to the system-default ANSI code page obtained from the operating system at program startup. You can query or change the multibyte code page in use with [_getmbcp](../c-runtime-library/reference/getmbcp.md) or [_setmbcp](../c-runtime-library/reference/setmbcp.md), respectively. - -The output value is affected by the `LC_CTYPE` category setting of the locale; see [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. - -|Routine|Test condition|Code page 932 example| -|-------------|--------------------|---------------------------| -|[_ismbcalnum, _ismbcalnum_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphanumeric|Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcdigit` and `_ismbcalpha`.| -|[_ismbcalpha, _ismbcalpha_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Alphabetic|Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcupper` and `_ismbclower`; or a katakana letter: 0xA6<=`c`<=0xDF.| -|[_ismbcdigit, _ismbcdigit_l](../c-runtime-library/reference/ismbcalnum-functions.md)|Digit|Returns nonzero if and only if `c` is a single-byte representation of an ASCII digit: 0x30<=`c`<=0x39.| -|[_ismbcgraph, _ismbcgraph_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Graphic|Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character except a white space ( ). See examples for `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`.| -|[_ismbclegal, _ismbclegal_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Valid multibyte character|Returns nonzero if and only if the first byte of `c` is within ranges 0x81 - 0x9F or 0xE0 - 0xFC, while the second byte is within ranges 0x40 - 0x7E or 0x80 - FC.| -|[_ismbclower, _ismbclower_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Lowercase alphabetic|Returns nonzero if and only if `c` is a single-byte representation of an ASCII lowercase English letter: 0x61<=`c`<=0x7A.| -|[_ismbcprint, _ismbcprint_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Printable|Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character including a white space ( ): See examples for `_ismbcspace`, `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`.| -|[_ismbcpunct, _ismbcpunct_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Punctuation|Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana punctuation character.| -|[_ismbcblank, _ismbcblank_l,](../c-runtime-library/reference/ismbcgraph-functions.md)|Space or horizontal tab|Returns nonzero if and only if `c` is a single-byte representation of a space character or a horizontal tab character: `c`=0x20 or `c`=0x09.| -|[_ismbcspace, _ismbcspace_l](../c-runtime-library/reference/ismbcgraph-functions.md)|Whitespace|Returns nonzero if and only if `c` is a white space character: `c`=0x20 or 0x09<=`c`<=0x0D.| -|[_ismbcsymbol, _ismbcsymbol_l](../c-runtime-library/reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md)|Multibyte symbol|Returns nonzero if and only if 0x8141<=`c`<=0x81AC.| -|[_ismbcupper, _ismbcupper_l](../c-runtime-library/reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md)|Uppercase alphabetic|Returns nonzero if and only if `c` is a single-byte representation of an ASCII uppercase English letter: 0x41<=`c`<=0x5A.| +The test result of each `_ismbc` routine depends on the multibyte code page in effect. Multibyte code pages have single-byte alphabetic characters. By default, the multibyte code page is set to the system-default ANSI code page obtained from the operating system at program startup. You can query or change the multibyte code page in use with [`_getmbcp`](reference/getmbcp.md) or [`_setmbcp`](reference/setmbcp.md), respectively. + +The output value is affected by the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](reference/setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. + +| Routine | Test condition | Code page 932 example | +|---|---|---| +| [`_ismbcalnum`, `_ismbcalnum_l`](reference/ismbcalnum-functions.md) | Alphanumeric | Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcdigit` and `_ismbcalpha`. | +| [`_ismbcalpha`, `_ismbcalpha_l`](reference/ismbcalnum-functions.md) | Alphabetic | Returns nonzero if and only if `c` is a single-byte representation of an ASCII English letter: See examples for `_ismbcupper` and `_ismbclower`; or a katakana letter: 0xA6<=`c`<=0xDF. | +| [`_ismbcdigit`, `_ismbcdigit_l`](reference/ismbcalnum-functions.md) | Digit | Returns nonzero if and only if `c` is a single-byte representation of an ASCII digit: 0x30<=`c`<=0x39. | +| [`_ismbcgraph`, `_ismbcgraph_l`](reference/ismbcgraph-functions.md) | Graphic | Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character except a white space ( ). See examples for `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`. | +| [`_ismbclegal`, `_ismbclegal_l`](reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Valid multibyte character | Returns nonzero if and only if the first byte of `c` is within ranges 0x81 - 0x9F or 0xE0 - 0xFC, while the second byte is within ranges 0x40 - 0x7E or 0x80 - FC. | +| [`_ismbclower`, `_ismbclower_l`](reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Lowercase alphabetic | Returns nonzero if and only if `c` is a single-byte representation of an ASCII lowercase English letter: 0x61<=`c`<=0x7A. | +| [`_ismbcprint`, `_ismbcprint_l`](reference/ismbcgraph-functions.md) | Printable | Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana printable character including a white space ( ): See examples for `_ismbcspace`, `_ismbcdigit`, `_ismbcalpha`, and `_ismbcpunct`. | +| [`_ismbcpunct`, `_ismbcpunct_l`](reference/ismbcgraph-functions.md) | Punctuation | Returns nonzero if and only if `c` is a single-byte representation of any ASCII or katakana punctuation character. | +| [`_ismbcblank`, `_ismbcblank_l`](reference/ismbcgraph-functions.md) | Space or horizontal tab | Returns nonzero if and only if `c` is a single-byte representation of a space character or a horizontal tab character: `c`=0x20 or `c`=0x09. | +| [`_ismbcspace`, `_ismbcspace_l`](reference/ismbcgraph-functions.md) | Whitespace | Returns nonzero if and only if `c` is a white space character: `c`=0x20 or 0x09<=`c`<=0x0D. | +| [`_ismbcsymbol`, `_ismbcsymbol_l`](reference/ismbclegal-ismbclegal-l-ismbcsymbol-ismbcsymbol-l.md) | Multibyte symbol | Returns nonzero if and only if 0x8141<=`c`<=0x81AC. | +| [`_ismbcupper`, `_ismbcupper_l`](reference/ismbclower-ismbclower-l-ismbcupper-ismbcupper-l.md) | Uppercase alphabetic | Returns nonzero if and only if `c` is a single-byte representation of an ASCII uppercase English letter: 0x41<=`c`<=0x5A. | **Code Page 932 Specific** The following routines are specific to code page 932. -|Routine|Test condition (code page 932 only)| -|-------------|-------------------------------------------| -|[_ismbchira, _ismbchira_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Double-byte Hiragana: 0x829F<=`c`<=0x82F1.| -|[_ismbckata, _ismbckata_l](../c-runtime-library/reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md)|Double-byte katakana: 0x8340<=`c`<=0x8396.| -|[_ismbcl0, _ismbcl0_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|JIS non-Kanji: 0x8140<=`c`<=0x889E.| -|[_ismbcl1, _ismbcl1_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|JIS level-1: 0x889F<=`c`<=0x9872.| -|[_ismbcl2, _ismbcl2_l](../c-runtime-library/reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md)|JIS level-2: 0x989F<=`c`<=0xEA9E.| +| Routine | Test condition (code page 932 only) | +|---|---| +| [`_ismbchira`, `_ismbchira_l`](reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Double-byte Hiragana: 0x829F<=`c`<=0x82F1. | +| [`_ismbckata`, `_ismbckata_l`](reference/ismbchira-ismbchira-l-ismbckata-ismbckata-l.md) | Double-byte katakana: 0x8340<=`c`<=0x8396. | +| [`_ismbcl0`, `_ismbcl0_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | JIS non-Kanji: 0x8140<=`c`<=0x889E. | +| [`_ismbcl1`, `_ismbcl1_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | JIS level-1: 0x889F<=`c`<=0x9872. | +| [`_ismbcl2`, `_ismbcl2_l`](reference/ismbcl0-ismbcl0-l-ismbcl1-ismbcl1-l-ismbcl2-ismbcl2-l.md) | JIS level-2: 0x989F<=`c`<=0xEA9E. | -`_ismbcl0`, `_ismbcl1`, and `_ismbcl2` check that the specified value `c` matches the test conditions described in the preceding table, but do not check that `c` is a valid multibyte character. If the lower byte is in the ranges 0x00 - 0x3F, 0x7F, or 0xFD - 0xFF, these functions return a nonzero value, indicating that the character satisfies the test condition. Use [_ismbbtrail, _ismbbtrail_l](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md) to test whether the multibyte character is defined. +`_ismbcl0`, `_ismbcl1`, and `_ismbcl2` check that the specified value `c` matches the test conditions described in the preceding table, but don't check that `c` is a valid multibyte character. If the lower byte is in the ranges 0x00 - 0x3F, 0x7F, or 0xFD - 0xFF, these functions return a nonzero value, indicating that the character satisfies the test condition. Use [`_ismbbtrail`, `_ismbbtrail_l`](reference/ismbbtrail-ismbbtrail-l.md) to test whether the multibyte character is defined. **END Code Page 932 Specific** ## See also -[Character Classification](../c-runtime-library/character-classification.md)
-[is, isw Routines](../c-runtime-library/is-isw-routines.md)
-[_ismbb Routines](../c-runtime-library/ismbb-routines.md) +[Character classification](character-classification.md)\ +[`is`, `isw` routines](is-isw-routines.md)\ +[`_ismbb` routines](ismbb-routines.md) diff --git a/docs/c-runtime-library/iso646-operators.md b/docs/c-runtime-library/iso646-operators.md index f41faff7834..8e0225b114e 100644 --- a/docs/c-runtime-library/iso646-operators.md +++ b/docs/c-runtime-library/iso646-operators.md @@ -4,7 +4,7 @@ title: "ISO646 Operators" ms.date: "04/11/2018" ms.assetid: 93e6d3e7-4889-4d8e-8dcb-c1a6b9bbe0f5 --- -# ISO646 Operators +# ISO646 operators Provides readable alternatives to certain operators or punctuators. The standard header \ is available even in a freestanding implementation. @@ -12,19 +12,19 @@ Provides readable alternatives to certain operators or punctuators. The standard | Name | Description | |--|--| -| [`and`](../c-runtime-library/reference/and.md) | An alternative to the `&&` operator. | -| [`and_eq`](../c-runtime-library/reference/and-eq.md) | An alternative to the `&=` operator. | -| [`bitand`](../c-runtime-library/reference/bitand.md) | An alternative to the `&` operator. | -| [`bitor`](../c-runtime-library/reference/bitor.md) | An alternative to the `|` operator. | -| [`compl`](../c-runtime-library/reference/compl.md) | An alternative to the `~` operator. | -| [`not`](../c-runtime-library/reference/not.md) | An alternative to the `!` operator. | -| [`not_eq`](../c-runtime-library/reference/not-eq.md) | An alternative to the `!=` operator. | -| [`or`](../c-runtime-library/reference/or.md) | An alternative to the `||` operator. | -| [`or_eq`](../c-runtime-library/reference/or-eq.md) | An alternative to the `|=` operator. | -| [`xor`](../c-runtime-library/reference/xor.md) | An alternative to the `^` operator. | -| [`xor_eq`](../c-runtime-library/reference/xor-eq.md) | An alternative to the `^=` operator. | +| [`and`](./reference/and.md) | An alternative to the `&&` operator. | +| [`and_eq`](./reference/and-eq.md) | An alternative to the `&=` operator. | +| [`bitand`](./reference/bitand.md) | An alternative to the `&` operator. | +| [`bitor`](./reference/bitor.md) | An alternative to the `|` operator. | +| [`compl`](./reference/compl.md) | An alternative to the `~` operator. | +| [`not`](./reference/not.md) | An alternative to the `!` operator. | +| [`not_eq`](./reference/not-eq.md) | An alternative to the `!=` operator. | +| [`or`](./reference/or.md) | An alternative to the `||` operator. | +| [`or_eq`](./reference/or-eq.md) | An alternative to the `|=` operator. | +| [`xor`](./reference/xor.md) | An alternative to the `^` operator. | +| [`xor_eq`](./reference/xor-eq.md) | An alternative to the `^=` operator. | ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/language-strings.md b/docs/c-runtime-library/language-strings.md index 26dc512fd94..99b9af3a157 100644 --- a/docs/c-runtime-library/language-strings.md +++ b/docs/c-runtime-library/language-strings.md @@ -4,85 +4,85 @@ description: "Learn more about: Language Strings" ms.date: "1/12/2021" helpviewer_keywords: ["language strings"] --- -# Language Strings +# Language strings -The [`setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md) and [`_create_locale`](../c-runtime-library/reference/create-locale-wcreate-locale.md) functions can use the Windows NLS API supported languages on operating systems that don't use the Unicode code page. For a list of supported languages by operating system version, see [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. The language string can be any of the values in the **Language** and **Language tag** columns of the list of supported languages. For example code that enumerates available locale names and related values, see [NLS: Name-based APIs Sample](/windows/win32/intl/nls--name-based-apis-sample). +The [`setlocale`](reference/setlocale-wsetlocale.md) and [`_create_locale`](reference/create-locale-wcreate-locale.md) functions can use the Windows NLS API supported languages on operating systems that don't use the Unicode code page. For a list of supported languages by operating system version, see [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. The language string can be any of the values in the **Language** and **Language tag** columns of the list of supported languages. For example code that enumerates available locale names and related values, see [NLS: Name-based APIs Sample](/windows/win32/intl/nls--name-based-apis-sample). ## Supported language strings The Microsoft C run-time library implementation also supports these language strings: -|Language string|Equivalent Locale Name| -|---------------------|----------------------------| -|`american`|`en-US`| -|`american english`|`en-US`| -|`american-english`|`en-US`| -|`australian`|`en-AU`| -|`belgian`|`nl-BE`| -|`canadian`|`en-CA`| -|`chh`|`zh-HK`| -|`chi`|`zh-SG`| -|`chinese`|`zh`| -|`chinese-hongkong`|`zh-HK`| -|`chinese-simplified`|`zh-CN`| -|`chinese-singapore`|`zh-SG`| -|`chinese-traditional`|`zh-TW`| -|`dutch-belgian`|`nl-BE`| -|`english-american`|`en-US`| -|`english-aus`|`en-AU`| -|`english-belize`|`en-BZ`| -|`english-can`|`en-CA`| -|`english-caribbean`|`en-029`| -|`english-ire`|`en-IE`| -|`english-jamaica`|`en-JM`| -|`english-nz`|`en-NZ`| -|`english-south africa`|`en-ZA`| -|`english-trinidad y tobago`|`en-TT`| -|`english-uk`|`en-GB`| -|`english-us`|`en-US`| -|`english-usa`|`en-US`| -|`french-belgian`|`fr-BE`| -|`french-canadian`|`fr-CA`| -|`french-luxembourg`|`fr-LU`| -|`french-swiss`|`fr-CH`| -|`german-austrian`|`de-AT`| -|`german-lichtenstein`|`de-LI`| -|`german-luxembourg`|`de-LU`| -|`german-swiss`|`de-CH`| -|`irish-english`|`en-IE`| -|`italian-swiss`|`it-CH`| -|`norwegian`|`no`| -|`norwegian-bokmal`|`nb-NO`| -|`norwegian-nynorsk`|`nn-NO`| -|`portuguese-brazilian`|`pt-BR`| -|`spanish-argentina`|`es-AR`| -|`spanish-bolivia`|`es-BO`| -|`spanish-chile`|`es-CL`| -|`spanish-colombia`|`es-CO`| -|`spanish-costa rica`|`es-CR`| -|`spanish-dominican republic`|`es-DO`| -|`spanish-ecuador`|`es-EC`| -|`spanish-el salvador`|`es-SV`| -|`spanish-guatemala`|`es-GT`| -|`spanish-honduras`|`es-HN`| -|`spanish-mexican`|`es-MX`| -|`spanish-modern`|`es-ES`| -|`spanish-nicaragua`|`es-NI`| -|`spanish-panama`|`es-PA`| -|`spanish-paraguay`|`es-PY`| -|`spanish-peru`|`es-PE`| -|`spanish-puerto rico`|`es-PR`| -|`spanish-uruguay`|`es-UY`| -|`spanish-venezuela`|`es-VE`| -|`swedish-finland`|`sv-FI`| -|`swiss`|`de-CH`| -|`uk`|`en-GB`| -|`us`|`en-US`| -|`usa`|`en-US`| +| Language string | Equivalent Locale Name | +|---|---| +| `american` | `en-US` | +| `american english` | `en-US` | +| `american-english` | `en-US` | +| `australian` | `en-AU` | +| `belgian` | `nl-BE` | +| `canadian` | `en-CA` | +| `chh` | `zh-HK` | +| `chi` | `zh-SG` | +| `chinese` | `zh` | +| `chinese-hongkong` | `zh-HK` | +| `chinese-simplified` | `zh-CN` | +| `chinese-singapore` | `zh-SG` | +| `chinese-traditional` | `zh-TW` | +| `dutch-belgian` | `nl-BE` | +| `english-american` | `en-US` | +| `english-aus` | `en-AU` | +| `english-belize` | `en-BZ` | +| `english-can` | `en-CA` | +| `english-caribbean` | `en-029` | +| `english-ire` | `en-IE` | +| `english-jamaica` | `en-JM` | +| `english-nz` | `en-NZ` | +| `english-south africa` | `en-ZA` | +| `english-trinidad y tobago` | `en-TT` | +| `english-uk` | `en-GB` | +| `english-us` | `en-US` | +| `english-usa` | `en-US` | +| `french-belgian` | `fr-BE` | +| `french-canadian` | `fr-CA` | +| `french-luxembourg` | `fr-LU` | +| `french-swiss` | `fr-CH` | +| `german-austrian` | `de-AT` | +| `german-lichtenstein` | `de-LI` | +| `german-luxembourg` | `de-LU` | +| `german-swiss` | `de-CH` | +| `irish-english` | `en-IE` | +| `italian-swiss` | `it-CH` | +| `norwegian` | `no` | +| `norwegian-bokmal` | `nb-NO` | +| `norwegian-nynorsk` | `nn-NO` | +| `portuguese-brazilian` | `pt-BR` | +| `spanish-argentina` | `es-AR` | +| `spanish-bolivia` | `es-BO` | +| `spanish-chile` | `es-CL` | +| `spanish-colombia` | `es-CO` | +| `spanish-costa rica` | `es-CR` | +| `spanish-dominican republic` | `es-DO` | +| `spanish-ecuador` | `es-EC` | +| `spanish-el salvador` | `es-SV` | +| `spanish-guatemala` | `es-GT` | +| `spanish-honduras` | `es-HN` | +| `spanish-mexican` | `es-MX` | +| `spanish-modern` | `es-ES` | +| `spanish-nicaragua` | `es-NI` | +| `spanish-panama` | `es-PA` | +| `spanish-paraguay` | `es-PY` | +| `spanish-peru` | `es-PE` | +| `spanish-puerto rico` | `es-PR` | +| `spanish-uruguay` | `es-UY` | +| `spanish-venezuela` | `es-VE` | +| `swedish-finland` | `sv-FI` | +| `swiss` | `de-CH` | +| `uk` | `en-GB` | +| `us` | `en-US` | +| `usa` | `en-US` | ## See also -- [Locale Names, Languages, and Country/Region Strings](../c-runtime-library/locale-names-languages-and-country-region-strings.md)\ -- [Country/Region Strings](../c-runtime-library/country-region-strings.md)\ -- [`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md)\ -- [`_create_locale`, `_wcreate_locale`](../c-runtime-library/reference/create-locale-wcreate-locale.md) +- [Locale names, Languages, and Country/Region strings](locale-names-languages-and-country-region-strings.md) +- [Country/Region strings](country-region-strings.md) +- [`setlocale`, `_wsetlocale`](reference/setlocale-wsetlocale.md) +- [`_create_locale`, `_wcreate_locale`](reference/create-locale-wcreate-locale.md) diff --git a/docs/c-runtime-library/lc-codepage-func.md b/docs/c-runtime-library/lc-codepage-func.md index 2e7ea34bc5e..21d5dd56409 100644 --- a/docs/c-runtime-library/lc-codepage-func.md +++ b/docs/c-runtime-library/lc-codepage-func.md @@ -3,14 +3,14 @@ description: "Learn more about: ___lc_codepage_func" title: "___lc_codepage_func" ms.date: "1/14/2021" api_name: ["___lc_codepage_func", "_o____lc_codepage_func"] -api_location: ["msvcr120.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110.dll", "msvcrt.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcr110_clr0400.dll", "msvcr80.dll", "msvcr100.dll", "msvcr90.dll", "msvcr110.dll", "msvcrt.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["lc_codepage_func", "___lc_codepage_func"] +f1_keywords: ["lc_codepage_func", "LOCALE/___lc_codepage_func", "___lc_codepage_func"] helpviewer_keywords: ["___lc_codepage_func"] ms.assetid: 6a663bd0-5a63-4a2f-9507-872ec1582aae --- -# ___lc_codepage_func +# `___lc_codepage_func` Internal CRT function. Retrieves the current code page of the thread. @@ -20,29 +20,29 @@ Internal CRT function. Retrieves the current code page of the thread. UINT ___lc_codepage_func(void); ``` -## Return Value +## Return value The current code page of the thread. ## Remarks -`___lc_codepage_func` is an internal CRT function that is used by other CRT functions to get the current code page from the thread local storage for CRT data. This information is also available by using the [_get_current_locale](../c-runtime-library/reference/get-current-locale.md) function. +**`___lc_codepage_func`** is an internal CRT function that is used by other CRT functions to get the current code page from the thread local storage for CRT data. This information is also available by using the [`_get_current_locale`](./reference/get-current-locale.md) function. -A *code page* is a mapping of single-byte or double-byte codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. For more information about code pages, see [Code Pages](../c-runtime-library/code-pages.md). +A *code page* is a mapping of single-byte or double-byte codes to individual characters. Different code pages include different special characters, typically customized for a language or a group of languages. For more information about code pages, see [Code pages](./code-pages.md). Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___lc_codepage_func`|crt\src\setlocal.h| +| Routine | Required header | +|---|---| +| **`___lc_codepage_func`** | `crt\src\setlocal.h` | ## See also -[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[_free_locale](../c-runtime-library/reference/free-locale.md) +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[`_free_locale`](./reference/free-locale.md) diff --git a/docs/c-runtime-library/lc-collate-cp-func.md b/docs/c-runtime-library/lc-collate-cp-func.md index 056692ffa69..e507776555b 100644 --- a/docs/c-runtime-library/lc-collate-cp-func.md +++ b/docs/c-runtime-library/lc-collate-cp-func.md @@ -3,14 +3,14 @@ description: "Learn more about: ___lc_collate_cp_func" title: "___lc_collate_cp_func" ms.date: "1/14/2021" api_name: ["___lc_collate_cp_func", "_o____lc_collate_cp_func"] -api_location: ["msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr90.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr90.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["___lc_collate_cp_func"] +f1_keywords: ["LOCALE/___lc_collate_cp_func", "___lc_collate_cp_func"] helpviewer_keywords: ["___lc_collate_cp_func"] ms.assetid: 46ccc084-7ac9-4e5d-9138-e12cb5845615 --- -# ___lc_collate_cp_func +# `___lc_collate_cp_func` Internal CRT function. Retrieves the current collation code page of the thread. @@ -20,27 +20,27 @@ Internal CRT function. Retrieves the current collation code page of the thread. UINT ___lc_codepage_func(void); ``` -## Return Value +## Return value The current collation code page of the thread. ## Remarks -`___lc_collate_cp_func` is an internal CRT function that is used by other CRT functions to get the current collation code page from the thread local storage for CRT data. This information is also available by using the [_get_current_locale](../c-runtime-library/reference/get-current-locale.md) function. +**`___lc_collate_cp_func`** is an internal CRT function that is used by other CRT functions to get the current collation code page from the thread local storage for CRT data. This information is also available by using the [`_get_current_locale`](./reference/get-current-locale.md) function. Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___lc_collate_cp_func`|crt\src\setlocal.h| +| Routine | Required header | +|---|---| +| **`___lc_collate_cp_func`** | crt\src\setlocal.h | ## See also -[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[_free_locale](../c-runtime-library/reference/free-locale.md) +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[`_free_locale`](./reference/free-locale.md) diff --git a/docs/c-runtime-library/lc-locale-name-func.md b/docs/c-runtime-library/lc-locale-name-func.md index 8f19df313b0..0fbf0416f28 100644 --- a/docs/c-runtime-library/lc-locale-name-func.md +++ b/docs/c-runtime-library/lc-locale-name-func.md @@ -3,14 +3,14 @@ description: "Learn more about: ___lc_locale_name_func" title: "___lc_locale_name_func" ms.date: "1/14/2021" api_name: ["___lc_locale_name_func", "_o____lc_locale_name_func"] -api_location: ["msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr110.dll", "msvcr100.dll", "msvcr90.dll", "msvcr120.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["___lc_locale_name_func"] +f1_keywords: ["LOCALE/___lc_locale_name_func", "___lc_locale_name_func"] helpviewer_keywords: ["___lc_locale_name_func"] ms.assetid: ef858308-872e-43de-95e0-9b1b4084343e --- -# ___lc_locale_name_func +# `___lc_locale_name_func` Internal CRT function. Retrieves the current locale name of the thread. @@ -20,27 +20,27 @@ Internal CRT function. Retrieves the current locale name of the thread. wchar_t** ___lc_locale_name_func(void); ``` -## Return Value +## Return value A pointer to a string that contains the current locale name of the thread. ## Remarks -`___lc_locale_name_func` is an internal CRT function that is used by other CRT functions to get the current locale name from the thread local storage for CRT data. This information is also available by using the [_get_current_locale](../c-runtime-library/reference/get-current-locale.md) function or the [setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) functions. +**`___lc_locale_name_func`** is an internal CRT function that is used by other CRT functions to get the current locale name from the thread local storage for CRT data. This information is also available by using the [`_get_current_locale`](./reference/get-current-locale.md) function or the [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) functions. Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___lc_locale_name_func`|crt\src\setlocal.h| +| Routine | Required header | +|---|---| +| **`___lc_locale_name_func`** | `crt\src\setlocal.h` | ## See also -[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[_free_locale](../c-runtime-library/reference/free-locale.md) +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[`_free_locale`](./reference/free-locale.md) diff --git a/docs/c-runtime-library/link-options.md b/docs/c-runtime-library/link-options.md index a321a157bde..7f27f9a1784 100644 --- a/docs/c-runtime-library/link-options.md +++ b/docs/c-runtime-library/link-options.md @@ -1,35 +1,34 @@ --- -description: "Learn more about: Link Options" -title: "Link Options" +title: "Link options" +description: "Learn more about: Link options" ms.date: "11/04/2016" helpviewer_keywords: ["nothrownew.obj", "newmode.obj", "noenv.obj", "psetargv.obj", "legacy_stdio_float_rounding.obj", "loosefpmath.obj", "smallheap.obj", "fp10.obj", "nochkclr.obj", "chkstk.obj", "pcommode.obj", "pnoenv.obj", "link options [C++]", "invalidcontinue.obj", "pnothrownew.obj", "pwsetargv.obj", "pinvalidcontinue.obj", "wsetargv.obj", "binmode.obj", "setargv.obj", "noarg.obj", "pnewmode.obj", "commode.obj", "pthreadlocale.obj", "pbinmode.obj", "threadlocale.obj", "pnoarg.obj"] -ms.assetid: 05b5a77b-9dd1-494b-ae46-314598c770bb --- -# Link Options +# Link options -The CRT lib directory includes a number of small object files that enable specific CRT features without any code change. These are called "link options" since you just have to add them to the linker command line to use them. +The CRT lib directory includes several small object files that enable specific CRT features without code changes. These object files are called "link options" because you only have to add them to the linker command line to use them. To do this from Visual Studio, in the Solution Explorer right-click your project and choose **Properties**. Under **Configuration Properties**, choose **Linker** > **Input** > **Additional Dependencies** and specify the additional items to add to the link command line. -CLR pure mode versions of these objects are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. Use the regular versions for native and /clr code. +CLR pure mode versions of these objects are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. Use the regular versions for native and [`/clr`](../build/reference/clr-common-language-runtime-compilation.md) code. -|Native and /clr|Pure mode|Description| -|----------------------|---------------|-----------------| -|binmode.obj|pbinmode.obj|Sets the default file-translation mode to binary. See [_fmode](../c-runtime-library/fmode.md).| -|chkstk.obj|n/a|Provides stack-checking and alloca support when not using the CRT.| -|commode.obj|pcommode.obj|Sets the global commit flag to "commit". See [fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md) and [fopen_s, _wfopen_s](../c-runtime-library/reference/fopen-s-wfopen-s.md).| -|exe_initialize_mta.lib|n/a|Initializes the MTA apartment during EXE startup, which allows the use of COM objects in global smart pointers. Because this option leaks an MTA apartment reference during shutdown, do not use it for DLLs. Linking to this is equivalent to including combase.h and defining _EXE_INITIALIZE_MTA. Using this link option adds [onecore.lib](/windows/win32/apiindex/windows-umbrella-libraries) to the default library list. If this is undesirable (such as using onecore_apiset.lib or other umbrella library), use [/NODEFAULTLIB](../build/reference/nodefaultlib-ignore-libraries.md) to override this and provide an alternative. | -|fp10.obj|n/a|Changes the default precision control to 64 bits. See [Floating-Point Support](../c-runtime-library/floating-point-support.md).| -|invalidcontinue.obj|pinvalidcontinue.obj|Sets a default invalid parameter handler that does nothing, meaning that invalid parameters passed to CRT functions will just set errno and return an error result.| -|legacy_stdio_float_rounding.obj|n/a|Printing floating-point values (for example, when using [printf](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)) with the Windows 10 19041 Universal C Runtime has been fixed. It now properly rounds exactly representable floating-point numbers, and respects the floating-point rounding requested by [fesetround](../c-runtime-library/reference/fegetround-fesetround2.md). This behavior update is available in Visual Studio 2019 version 16.2 and later. Legacy behavior is used in earlier versions of Visual Studio, or by providing this link option.| -|loosefpmath.obj|n/a|Ensures that floating point code tolerates denormal values.| -|newmode.obj|pnewmode.obj|Causes [malloc](../c-runtime-library/reference/malloc.md) to call the new handler on failure. See [_set_new_mode](../c-runtime-library/reference/set-new-mode.md), [_set_new_handler](../c-runtime-library/reference/set-new-handler.md), [calloc](../c-runtime-library/reference/calloc.md), and [realloc](../c-runtime-library/reference/realloc.md).| -|noarg.obj|pnoarg.obj|Disables all processing of argc and argv.| -|nochkclr.obj|n/a|Does nothing. Remove from your project.| -|noenv.obj|pnoenv.obj|Disables the creation of a cached environment for the CRT.| -|nothrownew.obj|pnothrownew.obj|Enables the non-throwing version of new in the CRT. See [new and delete Operators](../cpp/new-and-delete-operators.md).| -|setargv.obj|psetargv.obj|Enables command-line argument wildcard expansion. See [Expanding Wildcard Arguments](../c-language/expanding-wildcard-arguments.md).| -|threadlocale.obj|pthreadlocale.obj|Enables per-thread locale for all new threads by default.| -|wsetargv.obj|pwsetargv.obj|Enables command-line argument wildcard expansion. See [Expanding Wildcard Arguments](../c-language/expanding-wildcard-arguments.md).| +| Native and /clr | Pure mode | Description | +|---|---|---| +| `binmode.obj` | `pbinmode.obj` | Sets the default file-translation mode to binary. See [`_fmode`](fmode.md). | +| `chkstk.obj` | n/a | Provides stack-checking and alloca support when not using the CRT. | +| `commode.obj` | `pcommode.obj` | Sets the global commit flag to "commit". See [`fopen`, `_wfopen`](reference/fopen-wfopen.md) and [`fopen_s`, `_wfopen_s`](reference/fopen-s-wfopen-s.md). | +| `exe_initialize_mta.lib` | n/a | Initializes the MTA apartment during EXE startup, which allows the use of COM objects in global smart pointers. Because this option leaks an MTA apartment reference during shutdown, don't use it for DLLs. Linking to this file is equivalent to including `combase.h` and defining `_EXE_INITIALIZE_MTA`. Using this link option adds [`onecore.lib`](/windows/win32/apiindex/windows-umbrella-libraries) to the default library list. If this effect is undesirable (such as using onecore_apiset.lib or other umbrella library), use [`/NODEFAULTLIB`](../build/reference/nodefaultlib-ignore-libraries.md) to override this behavior and provide an alternative. | +| `fp10.obj` | n/a | Changes the default precision control to 64 bits. See [Math and floating-point support](floating-point-support.md). | +| `invalidcontinue.obj` | `pinvalidcontinue.obj` | Sets a default invalid parameter handler that does nothing, meaning that invalid parameters passed to CRT functions will just set errno and return an error result. | +| `legacy_stdio_float_rounding.obj` | n/a | The printing of floating-point values (for example, when using [`printf`](reference/printf-printf-l-wprintf-wprintf-l.md)) with the Windows 10 19041 Universal C Runtime has been fixed. It now properly rounds exactly representable floating-point numbers, and respects the floating-point rounding requested by [`fesetround`](reference/fegetround-fesetround2.md). This behavior update is available in Visual Studio 2019 version 16.2 and later. Legacy behavior is used in earlier versions of Visual Studio, or by providing this link option. | +| `loosefpmath.obj` | n/a | Ensures that floating point code tolerates denormal values. | +| `newmode.obj` | `pnewmode.obj` | Causes [`malloc`](reference/malloc.md) to call the new handler on failure. See [`_set_new_mode`](reference/set-new-mode.md), [`_set_new_handler`](reference/set-new-handler.md), [`calloc`](reference/calloc.md), and [`realloc`](reference/realloc.md). | +| `noarg.obj` | `pnoarg.obj` | Disables all processing of argc and argv. | +| `nochkclr.obj` | n/a | Does nothing. Remove from your project. | +| `noenv.obj` | `pnoenv.obj` | Disables the creation of a cached environment for the CRT. | +| `nothrownew.obj` | `pnothrownew.obj` | Enables the non-throwing version of new in the CRT. See [new and delete Operators](../cpp/new-and-delete-operators.md). | +| `setargv.obj` | `psetargv.obj` | Enables command-line argument wildcard expansion. See [Expanding wildcard arguments](../c-language/expanding-wildcard-arguments.md). | +| `threadlocale.obj` | `pthreadlocale.obj` | Enables per-thread locale for all new threads by default. | +| `wsetargv.obj` | `pwsetargv.obj` | Enables command-line argument wildcard expansion. See [Expanding wildcard arguments](../c-language/expanding-wildcard-arguments.md). | ## See also -- [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +- [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](crt-library-features.md) diff --git a/docs/c-runtime-library/local-unwind2.md b/docs/c-runtime-library/local-unwind2.md index f3f84e1b0e2..d3f4fcc87d0 100644 --- a/docs/c-runtime-library/local-unwind2.md +++ b/docs/c-runtime-library/local-unwind2.md @@ -3,14 +3,14 @@ description: "Learn more about: _local_unwind2" title: "_local_unwind2" ms.date: "1/14/2021" api_name: ["_local_unwind2"] -api_location: ["msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110_clr0400.dll", "msvcrt.dll", "msvcr100.dll", "msvcr110.dll", "msvcr80.dll", "msvcr90.dll", "msvcr120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_local_unwind2", "local_unwind2"] helpviewer_keywords: ["_local_unwind2 function", "local_unwind2 function"] ms.assetid: 44f1fa82-e01e-490f-a6e6-18fc6811c28c --- -# _local_unwind2 +# `_local_unwind2` Internal CRT Function. Runs all termination handlers that are listed in the indicated scope table. @@ -25,18 +25,18 @@ void _local_unwind2( #### Parameters -*xr*
+*`xr`*\ [in] A registration record that is associated with one scope table. -*stop*
+*`stop`*\ [in] The lexical level that indicates where `_local_unwind2` should stop. ## Remarks -This method is used only by the run-time environment. Do not call the method in your code. +This method is used only by the run-time environment. Don't call the method in your code. -When this method executes termination handlers, it starts at the current lexical level and works its way up in lexical levels until it reaches the level that is indicated by `stop`. It does not execute termination handlers at the level that is indicated by `stop`. +When this method executes termination handlers, it starts at the current lexical level, and works upward in lexical levels until it reaches the level that's indicated by `stop`. It doesn't execute termination handlers at the level that's indicated by `stop`. ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/locale-categories.md b/docs/c-runtime-library/locale-categories.md index 9a17ab8f5f8..891ebbf4d1d 100644 --- a/docs/c-runtime-library/locale-categories.md +++ b/docs/c-runtime-library/locale-categories.md @@ -2,15 +2,15 @@ description: "Learn more about: Locale Categories" title: "Locale Categories" ms.date: "11/04/2016" -f1_keywords: ["LC_MAX", "LC_MIN", "LC_MONETARY", "LC_TIME", "LC_NUMERIC", "LC_COLLATE", "LC_CTYPE", "LC_ALL"] +f1_keywords: ["LOCALE/LC_MAX", "LOCALE/LC_MIN", "LOCALE/LC_MONETARY", "LOCALE/LC_TIME", "LOCALE/LC_NUMERIC", "LOCALE/LC_COLLATE", "LOCALE/LC_CTYPE", "LOCALE/LC_ALL", "LC_MAX", "LC_MIN", "LC_MONETARY", "LC_TIME", "LC_NUMERIC", "LC_COLLATE", "LC_CTYPE", "LC_ALL"] helpviewer_keywords: ["LC_MIN constant", "LC_MONETARY constant", "LC_CTYPE constant", "locale constants", "LC_MAX constant", "LC_ALL constant", "LC_TIME constant", "LC_NUMERIC constant", "LC_COLLATE constant"] ms.assetid: 868f1493-fe5d-4722-acab-bfcd374a063a --- -# Locale Categories +# Locale categories ## Syntax -``` +```C #include ``` @@ -18,24 +18,24 @@ ms.assetid: 868f1493-fe5d-4722-acab-bfcd374a063a Locale categories are manifest constants used by the localization routines to specify which portion of a program's locale information will be used. The locale refers to the locality (or Country/Region) for which certain aspects of your program can be customized. Locale-dependent areas include, for example, the formatting of dates or the display format for monetary values. -|Locale category|Parts of program affected| -|---------------------|-------------------------------| -|`LC_ALL`|All locale-specific behavior (all categories)| -|`LC_COLLATE`|Behavior of `strcoll` and `strxfrm` functions| -|`LC_CTYPE`|Behavior of character-handling functions (except `isdigit`, `isxdigit`, `mbstowcs`, and `mbtowc`, which are unaffected)| -|`LC_MAX`|Same as `LC_TIME`| -|`LC_MIN`|Same as `LC_ALL`| -|`LC_MONETARY`|Monetary formatting information returned by the `localeconv` function| -|`LC_NUMERIC`|Decimal-point character for formatted output routines (for example, `printf`), data conversion routines, and nonmonetary formatting information returned by `localeconv` function| -|`LC_TIME`|Behavior of `strftime` function| +| Locale category | Parts of program affected | +|---|---| +| `LC_ALL` | All locale-specific behavior (all categories) | +| `LC_COLLATE` | Behavior of `strcoll` and `strxfrm` functions | +| `LC_CTYPE` | Behavior of character-handling functions (except `isdigit`, `isxdigit`, `mbstowcs`, and `mbtowc`, which are unaffected) | +| `LC_MAX` | Same as `LC_TIME` | +| `LC_MIN` | Same as `LC_ALL` | +| `LC_MONETARY` | Monetary formatting information returned by the `localeconv` function | +| `LC_NUMERIC` | Decimal-point character for formatted output routines (for example, `printf`), data conversion routines, and nonmonetary formatting information returned by `localeconv` function | +| `LC_TIME` | Behavior of `strftime` function | -See [setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) for an example. +See [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) for an example. ## See also -[localeconv](../c-runtime-library/reference/localeconv.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[strcoll Functions](../c-runtime-library/strcoll-functions.md)
-[strftime, wcsftime, _strftime_l, _wcsftime_l](../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`localeconv`](./reference/localeconv.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`strcoll` functions](./strcoll-functions.md)\ +[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](./reference/strftime-wcsftime-strftime-l-wcsftime-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](./reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md b/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md index fd9ee6817aa..ae687afb430 100644 --- a/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md +++ b/docs/c-runtime-library/locale-names-languages-and-country-region-strings.md @@ -1,38 +1,38 @@ --- title: "Locale Names, Languages, and Country-Region Strings" description: "An overview of using Microsoft Universal CRT locale, language, and country and region strings." -ms.topic: "conceptual" +ms.topic: "concept-article" ms.date: "12/10/2018" helpviewer_keywords: ["country/region strings", "localization, locale", "locales", "setlocale function", "language strings"] ms.assetid: a0e5a0c5-5602-4da0-b65f-de3d6c8530a2 --- # UCRT Locale names, Languages, and Country/Region strings -The *locale* argument to the [setlocale, \_wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md), [\_create\_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md), and [\_wcreate\_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md) functions can be set by using the locale names, languages, country/region codes, and code pages that are supported by the Windows NLS API. The *locale* argument takes the following form: +You can set the *`locale`* argument to the [`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md), [`_create_locale`](./reference/create-locale-wcreate-locale.md), and [`_wcreate_locale`](./reference/create-locale-wcreate-locale.md) functions in several ways. The locale can be set by using the locale names, languages, country/region codes, and code pages that are supported by the Windows NLS API. The *`locale`* argument takes one of the following forms: -> *locale* :: "*locale-name*"
-    \| "*language*\[**\_**_country-region_\[__.__*code-page*]]"
-    \| "__.__*code-page*"
-    \| "C"
-    \| ""
-    \| NULL +> *`locale`* :: "*locale-name*"\ + \| "*language*\[_*country-region*\[.*code-page*]]"\ + \| ".*code-page*"\ + \| "C"\ + \| ""\ + \| NULL -The *locale-name* form is a short, IETF-standardized string; for example, `en-US` for English (United States) or `bs-Cyrl-BA` for Bosnian (Cyrillic, Bosnia and Herzegovina). These forms are preferred. For a list of supported locale names by Windows operating system version, see the **Language tag** column of the table in [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. This resource lists the supported language, script, and region parts of the locale names. For information about the supported locale names that have non-default sort orders, see the **Locale name** column in [Sort Order Identifiers](/windows/win32/Intl/sort-order-identifiers). Under Windows 10 or later, locale names that correspond to valid [BCP-47](https://tools.ietf.org/html/bcp47) language tags are allowed. For example, `jp-US` is a valid BCP-47 tag, but it is effectively only `US` for locale functionality. +The *locale-name* form is a short, IETF-standardized string; for example, `en-US` for English (United States) or `bs-Cyrl-BA` for Bosnian (Cyrillic, Bosnia and Herzegovina). These forms are preferred. For a list of supported locale names by Windows operating system version, see the **Language tag** column of the table in [Appendix A: Product Behavior](/openspecs/windows_protocols/ms-lcid/a9eac961-e77d-41a6-90a5-ce1a8b0cdb9c) in \[MS-LCID]: Windows Language Code Identifier (LCID) Reference. This resource lists the supported language, script, and region parts of the locale names. For information about the supported locale names that have non-default sort orders, see the **Locale name** column in [Sort order identifiers](/windows/win32/Intl/sort-order-identifiers). Under Windows 10 or later, locale names that correspond to valid [BCP-47](https://tools.ietf.org/html/bcp47) language tags are allowed. For example, `jp-US` is a valid BCP-47 tag, but it's effectively only `US` for locale functionality. -The *language*\[**\_**_country-region_\[__.__*code-page*]] form is stored in the locale setting for a category when a language string, or language string and country or region string, is used to create the locale. The set of supported language strings is described in [Language Strings](../c-runtime-library/language-strings.md), and the list of supported country and region strings is listed in [Country/Region Strings](../c-runtime-library/country-region-strings.md). If the specified language is not associated with the specified country or region, the default language for the specified country or region is stored in the locale setting. We do not recommend this form for locale strings embedded in code or serialized to storage, because these strings are more likely to be changed by an operating system update than the locale name form. +The *language*\[**\_**_country-region_\[__.__*code-page*]] form is stored in the locale setting for a category when a language string, or language string and country or region string, is used to create the locale. The set of supported language strings is described in [Language strings](./language-strings.md), and the list of supported country and region strings is listed in [Country/Region strings](./country-region-strings.md). If the specified language isn't associated with the specified country or region, the default language for the specified country or region is stored in the locale setting. We don't recommend this form for locale strings embedded in code or serialized to storage: These strings are more likely to be changed by an operating system update than the locale name form. -The *code-page* is the ANSI/OEM code page that's associated with the locale. The code page is determined for you when you specify a locale by language or by language and country/region alone. The special value `.ACP` specifies the ANSI code page for the country/region. The special value `.OCP` specifies the OEM code page for the country/region. For example, if you specify `"Greek_Greece.ACP"` as the locale, the locale is stored as `Greek_Greece.1253` (the ANSI code page for Greek), and if you specify `"Greek_Greece.OCP"` as the locale, it is stored as `Greek_Greece.737` (the OEM code page for Greek). For more information about code pages, see [Code Pages](../c-runtime-library/code-pages.md). For a list of supported code pages on Windows, see [Code Page Identifiers](/windows/win32/Intl/code-page-identifiers). +The *code-page* is the ANSI/OEM code page that's associated with the locale. The code page is determined for you when you specify a locale by language or by language and country/region alone. The special value `.ACP` specifies the ANSI code page for the country/region. The special value `.OCP` specifies the OEM code page for the country/region. For example, if you specify `"Greek_Greece.ACP"` as the locale, the locale is stored as `Greek_Greece.1253` (the ANSI code page for Greek), and if you specify `"Greek_Greece.OCP"` as the locale, it's stored as `Greek_Greece.737` (the OEM code page for Greek). For more information about code pages, see [Code pages](./code-pages.md). For a list of supported code pages on Windows, see [Code page identifiers](/windows/win32/Intl/code-page-identifiers). -If you use only the code page to specify the locale, the user's default language and country/region as reported by [GetUserDefaultLocaleName](/windows/win32/api/winnls/nf-winnls-getuserdefaultlocalename) are used. For example, if you specify `".1254"` (ANSI Turkish) as the locale for a user that's configured for English (United States), the locale that's stored is `English_United States.1254`. We do not recommend this form, because it could lead to inconsistent behavior. +If you use only the code page to specify the locale, the user's default language and country/region as reported by [`GetUserDefaultLocaleName`](/windows/win32/api/winnls/nf-winnls-getuserdefaultlocalename) are used. For example, if you specify `".1254"` (ANSI Turkish) as the locale for a user that's configured for English (United States), the locale that's stored is `English_United States.1254`. We don't recommend this form, because it could lead to inconsistent behavior. -A *locale* argument value of `C` specifies the minimal ANSI conforming environment for C translation. The `C` locale assumes that every **`char`** data type is 1 byte and its value is always less than 256. If *locale* points to an empty string, the locale is the implementation-defined native environment. +A *`locale`* argument value of `C` specifies the minimal ANSI conforming environment for C translation. The `C` locale assumes that every **`char`** data type is 1 byte and its value is always less than 256. If *`locale`* points to an empty string, the locale is the implementation-defined native environment. You can specify all of the locale categories at the same time for the `setlocale` and `_wsetlocale` functions by using the `LC_ALL` category. The categories can all be set to the same locale, or you can set each category individually by using a locale argument that has this form: -> *LC-ALL-specifier* :: *locale*
-    \| \[**LC_COLLATE=**_locale_]\[**;LC_CTYPE=**_locale_]\[**;LC_MONETARY=**_locale_]\[**;LC_NUMERIC=**_locale_]\[**;LC_TIME=**_locale_] +> *`LC-ALL-specifier`* :: *`locale`*\ + \| \[**`LC_COLLATE=`***`locale`*]\[**`;LC_CTYPE=`***`locale`*]\[**`;LC_MONETARY=`***`locale`*]\[**`;LC_NUMERIC=`***`locale`*]\[**`;LC_TIME=`***`locale`*] -You can specify multiple category types, separated by semicolons. Category types that are not specified use the current locale setting. For example, this code snippet sets the current locale for all categories to `de-DE`, and then sets the categories `LC_MONETARY` to `en-GB` and `LC_TIME` to `es-ES`: +You can specify multiple category types, separated by semicolons. Category types that aren't specified use the current locale setting. For example, this code snippet sets the current locale for all categories to `de-DE`, and then sets the categories `LC_MONETARY` to `en-GB` and `LC_TIME` to `es-ES`: ```C _wsetlocale(LC_ALL, L"de-DE"); @@ -41,13 +41,13 @@ _wsetlocale(LC_ALL, L"LC_MONETARY=en-GB;LC_TIME=es-ES"); ## UTF-8 Support -UTF-8 support can be enabled by using the UTF-8 code page in your locale string. See the [UTF-8 Support section of `setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md#utf-8-support) for more information. +UTF-8 support can be enabled by using the UTF-8 code page in your locale string. For more information, see the [UTF-8 support section of `setlocale`](./reference/setlocale-wsetlocale.md#utf-8-support). ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
-[_get_current_locale](../c-runtime-library/reference/get-current-locale.md)
-[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
-[_create_locale, _wcreate_locale](../c-runtime-library/reference/create-locale-wcreate-locale.md)
-[Language Strings](../c-runtime-library/language-strings.md)
-[Country/Region Strings](../c-runtime-library/country-region-strings.md) +[C runtime library reference](./c-run-time-library-reference.md)\ +[`_get_current_locale`](./reference/get-current-locale.md)\ +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md)\ +[`_create_locale`, `_wcreate_locale`](./reference/create-locale-wcreate-locale.md)\ +[Language strings](./language-strings.md)\ +[Country/Region strings](./country-region-strings.md) diff --git a/docs/c-runtime-library/locale.md b/docs/c-runtime-library/locale.md index 75f7d9a8451..5801ca774ee 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 information", "language information routines", "setlocale function", "locale routines"] +helpviewer_keywords: ["localization, locale", "country/region information", "language information routines", "setlocale function", "locale routines"] --- # Locale -*Locale* refers to country/region and language settings that you can use to customize your program. Some locale-dependent categories include the display formats for dates and monetary values. For more information, see [Locale Categories](../c-runtime-library/locale-categories.md). - -Use the [`setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md) function to change or query some or all of the current program or thread locale information while using functions without the **`_l`** suffix. The functions with the **`_l`** suffix will use the locale parameter passed in for their locale information during the execution of that specific function only. To create a locale for use with a function with a **`_l`** suffix, use [`_create_locale`](../c-runtime-library/reference/create-locale-wcreate-locale.md). To free this locale, use [`_free_locale`](../c-runtime-library/reference/free-locale.md). To get the current locale, use [`_get_current_locale`](../c-runtime-library/reference/get-current-locale.md). - -Use [`_configthreadlocale`](../c-runtime-library/reference/configthreadlocale.md) to control whether each thread has its own locale, or all threads in a program share the same locale. For more information, see [Locales and Code Pages](../text/locales-and-code-pages.md). - -More secure versions of the functions in the following table are available, indicated by the **`_s`** ("secure") suffix. For more information, see [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). - -## Locale-Dependent Routines - -|Routine|Use|**`setlocale`** category setting dependence| -|-------------|---------|---------------------------------------------| -|[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](../c-runtime-library/reference/atof-atof-l-wtof-wtof-l.md)|Convert character to floating-point value|**`LC_NUMERIC`**| -|[`atoi`, `_atoi_l`, `_wtoi`, `_wtoi_l`](../c-runtime-library/reference/atoi-atoi-l-wtoi-wtoi-l.md)|Convert character to integer value|**`LC_NUMERIC`**| -|[`_atoi64`, `_atoi64_l`, `_wtoi64`, `_wtoi64_l`](../c-runtime-library/reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md)|Convert character to 64-bit integer value|**`LC_NUMERIC`**| -|[`atol`, `_atol_l`, `_wtol`, `_wtol_l`](../c-runtime-library/reference/atol-atol-l-wtol-wtol-l.md)|Convert character to long value|**`LC_NUMERIC`**| -|[`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](../c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md)|Convert character to double-long value|**`LC_NUMERIC`**| -|[`is` Routines](../c-runtime-library/is-isw-routines.md)|Test given integer for particular condition.|**`LC_CTYPE`**| -|[`isleadbyte`, `_isleadbyte_l`](../c-runtime-library/reference/isleadbyte-isleadbyte-l.md)|Test for lead byte|**`LC_CTYPE`**| -|[`localeconv`](../c-runtime-library/reference/localeconv.md)|Read appropriate values for formatting numeric quantities|`LC_MONETARY, LC_NUMERIC`| -|[`MB_CUR_MAX`](../c-runtime-library/mb-cur-max.md)|Maximum length in bytes of any multibyte character in current locale (macro defined in `STDLIB.H`)|**`LC_CTYPE`**| -|[`_mbccpy`, `_mbccpy_l`](../c-runtime-library/reference/mbccpy-mbccpy-l.md),[`_mbccpy_s`, `_mbccpy_s_l`](../c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md)|Copy one multibyte character|**`LC_CTYPE`**| -|[`_mbclen`, `mblen`, `_mblen_l`](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)|Validate and return number of bytes in multibyte character|**`LC_CTYPE`**| -|[`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)|For multibyte-character strings: validate each character in string; return string length|**`LC_CTYPE`**| -|[`mbstowcs`, `_mbstowcs_l`](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md),[`mbstowcs_s`, `_mbstowcs_s_l`](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert sequence of multibyte characters to corresponding sequence of wide characters|**`LC_CTYPE`**| -|[`mbtowc`, `_mbtowc_l`](../c-runtime-library/reference/mbtowc-mbtowc-l.md)|Convert multibyte character to corresponding wide character|**`LC_CTYPE`**| -|[`printf`](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) functions|Write formatted output|**`LC_NUMERIC`** (determines radix character output)| -|[`scanf`](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md) functions|Read formatted input|**`LC_NUMERIC`** (determines radix character recognition)| -|[`setlocale`, `_wsetlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md)|Select locale for program|Not applicable| -|[`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](../c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md)|Compare characters of two strings|**`LC_COLLATE`**| -|[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](../c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)|Compare two strings without regard to case|**`LC_CTYPE`**| -|[`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](../c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md)|Compare characters of two strings (case insensitive)|**`LC_COLLATE`**| -|[`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](../c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md)|Compare first **`n`** characters of two strings|**`LC_COLLATE`**| -|[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](../c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)|Compare characters of two strings without regard to case.|**`LC_CTYPE`**| -|[`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](../c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md)|Compare first **`n`** characters of two strings (case insensitive)|**`LC_COLLATE`**| -|[`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](../c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md)|Format date and time value according to supplied **`format`** argument|**`LC_TIME`**| -|[`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](../c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md),[`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](../c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)|Convert, in place, each uppercase letter in given string to lowercase|**`LC_CTYPE`**| -|[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](../c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md)|Convert character string to **`double`** value|**`LC_NUMERIC`** (determines radix character recognition)| -|[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](../c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md)|Convert character string to **`long`** value|**`LC_NUMERIC`** (determines radix character recognition)| -|[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](../c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md)|Convert character string to unsigned long value|**`LC_NUMERIC`** (determines radix character recognition)| -|[`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](../c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md),[`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](../c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)|Convert, in place, each lowercase letter in string to uppercase|**`LC_CTYPE`**| -|[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](../c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)|Transform string into collated form according to locale|**`LC_COLLATE`**| -|[`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md),[`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Convert given character to corresponding lowercase character|**`LC_CTYPE`**| -|[`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md),[`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](../c-runtime-library/reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md)|Convert given character to corresponding uppercase letter|**`LC_CTYPE`**| -|[`wcstombs`, `_wcstombs_l`](../c-runtime-library/reference/wcstombs-wcstombs-l.md),[`wcstombs_s`, `_wcstombs_s_l`](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert sequence of wide characters to corresponding sequence of multibyte characters|**`LC_CTYPE`**| -|[`wctomb`, `_wctomb_l`](../c-runtime-library/reference/wctomb-wctomb-l.md),[`wctomb_s`, `_wctomb_s_l`](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert wide character to corresponding multibyte character|**`LC_CTYPE`**| +*Locale* refers to country/region and language settings that you can use to customize your program. Some locale-dependent categories include the display formats for dates and monetary values. For more information, see [Locale categories](locale-categories.md). + +Use the [`setlocale`](reference/setlocale-wsetlocale.md) function to change or query some or all of the current program or thread locale information while using functions without the **`_l`** suffix. The functions with the **`_l`** suffix will use the locale parameter passed in for their locale information during the execution of that specific function only. To create a locale for use with a function with a **`_l`** suffix, use [`_create_locale`](reference/create-locale-wcreate-locale.md). To free this locale, use [`_free_locale`](reference/free-locale.md). To get the current locale, use [`_get_current_locale`](reference/get-current-locale.md). + +Use [`_configthreadlocale`](reference/configthreadlocale.md) to control whether each thread has its own locale, or all threads in a program share the same locale. For more information, see [Locales and code pages](../text/locales-and-code-pages.md). + +More secure versions of the functions in the following table are available, indicated by the **`_s`** ("secure") suffix. For more information, see [Security features in the CRT](security-features-in-the-crt.md). + +## Locale-dependent routines + +| Routine | Use | **`setlocale`** category setting dependence | +|---|---|---| +| [`atof`, `_atof_l`, `_wtof`, `_wtof_l`](reference/atof-atof-l-wtof-wtof-l.md) | Convert character to floating-point value | `LC_NUMERIC` | +| [`atoi`, `_atoi_l`, `_wtoi`, `_wtoi_l`](reference/atoi-atoi-l-wtoi-wtoi-l.md) | Convert character to integer value | `LC_NUMERIC` | +| [`_atoi64`, `_atoi64_l`, `_wtoi64`, `_wtoi64_l`](reference/atoi64-atoi64-l-wtoi64-wtoi64-l.md) | Convert character to 64-bit integer value | `LC_NUMERIC` | +| [`atol`, `_atol_l`, `_wtol`, `_wtol_l`](reference/atol-atol-l-wtol-wtol-l.md) | Convert character to long value | `LC_NUMERIC` | +| [`_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l`](reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md) | Convert character to double-long value | `LC_NUMERIC` | +| [`is`, `isw` routines](is-isw-routines.md) | Test given integer for particular condition. | `LC_CTYPE` | +| [`isleadbyte`, `_isleadbyte_l`](reference/isleadbyte-isleadbyte-l.md) | Test for lead byte | `LC_CTYPE` | +| [`localeconv`](reference/localeconv.md) | Read appropriate values for formatting numeric quantities | `LC_MONETARY, LC_NUMERIC` | +| [`MB_CUR_MAX`](mb-cur-max.md) | Maximum length in bytes of any multibyte character in current locale (macro defined in `STDLIB.H`) | `LC_CTYPE` | +| [`_mbccpy`, `_mbccpy_l`](reference/mbccpy-mbccpy-l.md), [`_mbccpy_s`, `_mbccpy_s_l`](reference/mbccpy-s-mbccpy-s-l.md) | Copy one multibyte character | `LC_CTYPE` | +| [`_mbclen`, `mblen`, `_mblen_l`](reference/mbclen-mblen-mblen-l.md) | Validate and return number of bytes in multibyte character | `LC_CTYPE` | +| [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) | For multibyte-character strings: validate each character in string; return string length | `LC_CTYPE` | +| [`mbstowcs`, `_mbstowcs_l`](reference/mbstowcs-mbstowcs-l.md), [`mbstowcs_s`, `_mbstowcs_s_l`](reference/mbstowcs-s-mbstowcs-s-l.md) | Convert sequence of multibyte characters to corresponding sequence of wide characters | `LC_CTYPE` | +| [`mbtowc`, `_mbtowc_l`](reference/mbtowc-mbtowc-l.md) | Convert multibyte character to corresponding wide character | `LC_CTYPE` | +| [`printf`](reference/printf-printf-l-wprintf-wprintf-l.md) functions | Write formatted output | `LC_NUMERIC` (determines radix character output) | +| [`scanf`](reference/scanf-scanf-l-wscanf-wscanf-l.md) functions | Read formatted input | `LC_NUMERIC` (determines radix character recognition) | +| [`setlocale`, `_wsetlocale`](reference/setlocale-wsetlocale.md) | Select locale for program | Not applicable | +| [`strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l`](reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md) | Compare characters of two strings | `LC_COLLATE` | +| [`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) | Compare two strings without regard to case | `LC_CTYPE` | +| [`_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l`](reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) | Compare characters of two strings (case insensitive) | `LC_COLLATE` | +| [`_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l`](reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md) | Compare first **`n`** characters of two strings | `LC_COLLATE` | +| [`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) | Compare characters of two strings without regard to case. | `LC_CTYPE` | +| [`_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l`](reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md) | Compare first **`n`** characters of two strings (case insensitive) | `LC_COLLATE` | +| [`strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l`](reference/strftime-wcsftime-strftime-l-wcsftime-l.md) | Format date and time value according to supplied **`format`** argument | `LC_TIME` | +| [`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md), [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) | Convert, in place, each uppercase letter in given string to lowercase | `LC_CTYPE` | +| [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](reference/strtod-strtod-l-wcstod-wcstod-l.md) | Convert character string to **`double`** value | `LC_NUMERIC` (determines radix character recognition) | +| [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](reference/strtol-wcstol-strtol-l-wcstol-l.md) | Convert character string to **`long`** value | `LC_NUMERIC` (determines radix character recognition) | +| [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md) | Convert character string to unsigned long value | `LC_NUMERIC` (determines radix character recognition) | +| [`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md), [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) | Convert, in place, each lowercase letter in string to uppercase | `LC_CTYPE` | +| [`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) | Transform string into collated form according to locale | `LC_COLLATE` | +| [`tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l`](reference/tolower-tolower-towlower-tolower-l-towlower-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Convert given character to corresponding lowercase character | `LC_CTYPE` | +| [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [`_mbctolower`, `_mbctolower_l`, `_mbctoupper`, `_mbctoupper_l`](reference/mbctolower-mbctolower-l-mbctoupper-mbctoupper-l.md) | Convert given character to corresponding uppercase letter | `LC_CTYPE` | +| [`wcstombs`, `_wcstombs_l`](reference/wcstombs-wcstombs-l.md), [`wcstombs_s`, `_wcstombs_s_l`](reference/wcstombs-s-wcstombs-s-l.md) | Convert sequence of wide characters to corresponding sequence of multibyte characters | `LC_CTYPE` | +| [`wctomb`, `_wctomb_l`](reference/wctomb-wctomb-l.md), [`wctomb_s`, `_wctomb_s_l`](reference/wctomb-s-wctomb-s-l.md) | Convert wide character to corresponding multibyte character | `LC_CTYPE` | > [!NOTE] -> For multibyte routines, the multibyte code page must be equivalent to the locale set with [`setlocale`](../c-runtime-library/reference/setlocale-wsetlocale.md). [`_setmbcp`](../c-runtime-library/reference/setmbcp.md), with an argument of **`_MB_CP_LOCALE`** makes the multibyte code page the same as the **`setlocale`** code page. +> For multibyte routines, the multibyte code page must be equivalent to the locale set with [`setlocale`](reference/setlocale-wsetlocale.md). [`_setmbcp`](reference/setmbcp.md), with an argument of `_MB_CP_LOCALE` makes the multibyte code page the same as the **`setlocale`** code page. ## See also -[Internationalization](../c-runtime-library/internationalization.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Internationalization](internationalization.md)\ +[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/lock.md b/docs/c-runtime-library/lock.md index 087babd8002..19562f13ef8 100644 --- a/docs/c-runtime-library/lock.md +++ b/docs/c-runtime-library/lock.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _lock" title: "_lock" -ms.date: "11/04/2016" +description: "Learn more about: _lock" +ms.date: 11/04/2016 api_name: ["_lock"] api_location: ["msvcr110_clr0400.dll", "msvcr120.dll", "msvcr100.dll", "msvcr90.dll", "msvcr80.dll", "msvcr110.dll", "msvcrt.dll", "msvcr120_clr0400.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["lock", "_lock"] +f1_keywords: ["_lock"] helpviewer_keywords: ["lock function", "_lock function"] -ms.assetid: 29f77c37-30de-4b3d-91b6-030216e645a6 --- -# _lock +# `_lock` Acquires a multi-thread lock. @@ -20,19 +19,19 @@ Acquires a multi-thread lock. ## Syntax ```cpp -void __cdecl _lock +void __cdecl _lock( int locknum ); ``` #### Parameters -*locknum*
+*`locknum`*\ [in] The identifier of the lock to acquire. ## Remarks -If the lock has already been acquired, this method acquires the lock anyway and causes an internal C run-time (CRT) error. If the method cannot acquire a lock, it exits with a fatal error and sets the error code to `_RT_LOCK`. +If the lock has already been acquired, this method acquires the lock anyway and causes an internal C run-time (CRT) error. If the method can't acquire a lock, it exits with a fatal error and sets the error code to `_RT_LOCK`. ## Requirements @@ -40,5 +39,5 @@ If the lock has already been acquired, this method acquires the lock anyway and ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)
-[_unlock](../c-runtime-library/unlock.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`_unlock`](./unlock.md) diff --git a/docs/c-runtime-library/locking-constants.md b/docs/c-runtime-library/locking-constants.md index 392f25237d9..3951399044b 100644 --- a/docs/c-runtime-library/locking-constants.md +++ b/docs/c-runtime-library/locking-constants.md @@ -2,33 +2,33 @@ description: "Learn more about: _locking Constants" title: "_locking Constants" ms.date: "11/04/2016" -f1_keywords: ["_LK_RLCK", "_LK_NBLCK", "_LK_LOCK", "_LK_NBRLCK", "_LK_UNLCK"] +f1_keywords: ["LOCKING/_LK_RLCK", "LOCKING/_LK_NBLCK", "LOCKING/_LK_LOCK", "LOCKING/_LK_NBRLCK", "LOCKING/_LK_UNLCK", "LOCKING/LK_RLCK", "LOCKING/LK_NBLCK", "LOCKING/LK_LOCK", "LOCKING/LK_NBRLCK", "LOCKING/LK_UNLCK", "_LK_RLCK", "_LK_NBLCK", "_LK_LOCK", "_LK_NBRLCK", "_LK_UNLCK", "LK_RLCK", "LK_NBLCK", "LK_LOCK", "LK_NBRLCK", "LK_UNLCK"] helpviewer_keywords: ["LK_UNLCK constant", "LK_NBRLCK constant", "_LK_NBRLCK constant", "_LK_NBLCK constant", "_LK_LOCK constant", "LK_NBLCK constant", "_LK_UNLCK constant", "LK_RLCK constant", "_LK_RLCK constant", "LK_LOCK constant"] ms.assetid: c3dc92c8-60e3-4d29-9f50-5d217627c8ad --- -# _locking Constants +# `_locking` constants ## Syntax -``` +```C #include ``` ## Remarks -The *mode* argument in the call to the `_locking` function specifies the locking action to be performed. +The *`mode`* argument in the call to the `_locking` function specifies the locking action to be performed. -The *mode* argument must be one of the following manifest constants. +The *`mode`* argument must be one of the following manifest constants. -|Value|Description| -|-|-| -| `_LK_LOCK` | Locks the specified bytes. If the bytes cannot be locked, the function tries again after 1 second. If, after 10 attempts, the bytes cannot be locked, the function returns an error. | -| `_LK_RLCK` | Same as `_LK_LOCK`. | -|`_LK_NBLCK` | Locks the specified bytes. If bytes cannot be locked, the function returns an error. | -| `_LK_NBRLCK` | Same as `_LK_NBLCK`. | -| `_LK_UNLCK` | Unlocks the specified bytes. (The bytes must have been previously locked.) | +| Value | Description | +|---|---| +| `_LK_LOCK` | Locks the specified bytes. If the bytes can't be locked, the function tries again after 1 second. If the bytes can't be locked after 10 attempts, the function returns an error. | +| `_LK_RLCK` | Same as `_LK_LOCK`. | +| `_LK_NBLCK` | Locks the specified bytes. If bytes can't be locked, the function returns an error. | +| `_LK_NBRLCK` | Same as `_LK_NBLCK`. | +| `_LK_UNLCK` | Unlocks the specified bytes. (The bytes must have been previously locked.) | ## See also -[_locking](../c-runtime-library/reference/locking.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_locking`](./reference/locking.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/low-level-i-o.md b/docs/c-runtime-library/low-level-i-o.md index c1228d636ab..b08223be75f 100644 --- a/docs/c-runtime-library/low-level-i-o.md +++ b/docs/c-runtime-library/low-level-i-o.md @@ -4,42 +4,42 @@ title: "Low-Level I/O" ms.date: "11/04/2016" helpviewer_keywords: ["I/O [CRT], low-level", "I/O [CRT], functions", "low-level I/O routines", "file handles [C++]", "file handles [C++], I/O functions"] --- -# Low-Level I/O +# Low-level I/O -These functions invoke the operating system directly for lower-level operation than that provided by stream I/O. Low-level input and output calls do not buffer or format data. +These functions invoke the operating system directly for lower-level operation than that provided by stream I/O. Low-level input and output calls don't buffer or format data. Low-level routines can access the standard streams opened at program startup using the following predefined file descriptors. -|Stream|File Descriptor| -|------------|---------------------| -|**`stdin`**|0| -|**`stdout`**|1| -|**`stderr`**|2| - -Low-level I/O routines set the [`errno`](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) global variable when an error occurs. You must include `STDIO.H` when you use low-level functions only if your program requires a constant that is defined in `STDIO.H`, such as the end-of-file indicator (**`EOF`**). - -## Low-Level I/O Functions - -|Function|Use| -|--------------|---------| -|[`_close`](../c-runtime-library/reference/close.md)|Close file| -|[`_commit`](../c-runtime-library/reference/commit.md)|Flush file to disk| -|[`_creat`, `_wcreat`](../c-runtime-library/reference/creat-wcreat.md)|Create file| -|[`_dup`](../c-runtime-library/reference/dup-dup2.md)|Return next available file descriptor for given file| -|[`_dup2`](../c-runtime-library/reference/dup-dup2.md)|Create second descriptor for given file| -|[`_eof`](../c-runtime-library/reference/eof.md)|Test for end of file| -|[`_lseek`, `_lseeki64`](../c-runtime-library/reference/lseek-lseeki64.md)|Reposition file pointer to given location| -|[`_open`, `_wopen`](../c-runtime-library/reference/open-wopen.md)|Open file| -|[`_read`](../c-runtime-library/reference/read.md)|Read data from file| -|[`_sopen`, `_wsopen`](../c-runtime-library/reference/sopen-wsopen.md), [`_sopen_s`, `_wsopen_s`](../c-runtime-library/reference/sopen-s-wsopen-s.md)|Open file for file sharing| -|[`_tell`, `_telli64`](../c-runtime-library/reference/tell-telli64.md)|Get current file-pointer position| -|[`_umask`](../c-runtime-library/reference/umask.md), [`_umask_s`](../c-runtime-library/reference/umask-s.md)|Set file-permission mask| -|[`_write`](../c-runtime-library/reference/write.md)|Write data to file| - -**`_dup`** and **`_dup2`** are typically used to associate the predefined file descriptors with different files. +| Stream | File Descriptor | +|---|---| +| **`stdin`** | 0 | +| **`stdout`** | 1 | +| **`stderr`** | 2 | + +Low-level I/O routines set the [`errno`](./errno-doserrno-sys-errlist-and-sys-nerr.md) global variable when an error occurs. You must include `STDIO.H` when you use low-level functions only if your program requires a constant that is defined in `STDIO.H`, such as the end-of-file indicator (`EOF`). + +## Low-level I/O functions + +| Function | Use | +|---|---| +| [`_close`](./reference/close.md) | Close file | +| [`_commit`](./reference/commit.md) | Flush file to disk | +| [`_creat`, `_wcreat`](./reference/creat-wcreat.md) | Create file | +| [`_dup`](./reference/dup-dup2.md) | Return next available file descriptor for given file | +| [`_dup2`](./reference/dup-dup2.md) | Create second descriptor for given file | +| [`_eof`](./reference/eof.md) | Test for end of file | +| [`_lseek`, `_lseeki64`](./reference/lseek-lseeki64.md) | Reposition file pointer to given location | +| [`_open`, `_wopen`](./reference/open-wopen.md) | Open file | +| [`_read`](./reference/read.md) | Read data from file | +| [`_sopen`, `_wsopen`](./reference/sopen-wsopen.md), [`_sopen_s`, `_wsopen_s`](./reference/sopen-s-wsopen-s.md) | Open file for file sharing | +| [`_tell`, `_telli64`](./reference/tell-telli64.md) | Get current file-pointer position | +| [`_umask`](./reference/umask.md), [`_umask_s`](./reference/umask-s.md) | Set file-permission mask | +| [`_write`](./reference/write.md) | Write data to file | + +`_dup` and `_dup2` are typically used to associate the predefined file descriptors with different files. ## See also -[Input and Output](../c-runtime-library/input-and-output.md)\ -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)\ -[System Calls](../c-runtime-library/system-calls.md) +[Input and output](./input-and-output.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[System calls](./system-calls.md) diff --git a/docs/c-runtime-library/math-constants.md b/docs/c-runtime-library/math-constants.md index 50afa4a9e6d..61b129659a0 100644 --- a/docs/c-runtime-library/math-constants.md +++ b/docs/c-runtime-library/math-constants.md @@ -2,15 +2,17 @@ description: "Learn more about: Math Constants" title: "Math Constants" ms.date: "11/04/2016" -f1_keywords: ["c.constants.math"] +f1_keywords: ["c.constants.math", "_USE_MATH_DEFINES", "CORECRT_MATH_DEFINES/M_E", "CORECRT_MATH_DEFINES/M_LOG2E", "CORECRT_MATH_DEFINES/M_LOG10E", "CORECRT_MATH_DEFINES/M_LN2", "CORECRT_MATH_DEFINES/M_LN10", "CORECRT_MATH_DEFINES/M_PI", "CORECRT_MATH_DEFINES/M_PI_2", "CORECRT_MATH_DEFINES/M_PI_4", "CORECRT_MATH_DEFINES/M_1_PI", "CORECRT_MATH_DEFINES/M_2_PI", "CORECRT_MATH_DEFINES/M_2_SQRTPI", "CORECRT_MATH_DEFINES/M_SQRT2", "CORECRT_MATH_DEFINES/M_SQRT1_2", "M_E", "M_LOG2E", "M_LOG10E", "M_LN2", "M_LN10", "M_PI", "M_PI_2", "M_PI_4", "M_1_PI", "M_2_PI", "M_2_SQRTPI", "M_SQRT2", "M_SQRT1_2"] helpviewer_keywords: ["M_PI constant", "M_PI_2 constant", "math constants", "M_2_PI constant", "M_1_PI constant", "M_E constant", "USE_MATH_DEFINES constant", "M_LOG2E constant", "M_LOG10E constant", "M_LN10 constant", "M_SQRT1_2 constant", "_USE_MATH_DEFINES constant", "M_PI_4 constant", "constants, math", "M_2_SQRTPI constant", "M_SQRT2 constant", "M_LN2 constant"] ms.assetid: db533c3f-6ae8-4520-9d35-c8fabbef3529 --- -# Math Constants +# Math constants + +Microsoft provides several predefined preprocessor macros for common math constants. ## Syntax -``` +```cpp #define _USE_MATH_DEFINES // for C++ #include @@ -22,26 +24,26 @@ ms.assetid: db533c3f-6ae8-4520-9d35-c8fabbef3529 The following symbols are defined for the values of their indicated expressions: -|Symbol|Expression|Value| -|------------|----------------|-----------| -|`M_E`|e|2.71828182845904523536| -|`M_LOG2E`|log2(e)|1.44269504088896340736| -|`M_LOG10E`|log10(e)|0.434294481903251827651| -|`M_LN2`|ln(2)|0.693147180559945309417| -|`M_LN10`|ln(10)|2.30258509299404568402| -|`M_PI`|pi|3.14159265358979323846| -|`M_PI_2`|pi/2|1.57079632679489661923| -|`M_PI_4`|pi/4|0.785398163397448309616| -|`M_1_PI`|1/pi|0.318309886183790671538| -|`M_2_PI`|2/pi|0.636619772367581343076| -|`M_2_SQRTPI`|2/sqrt(pi)|1.12837916709551257390| -|`M_SQRT2`|sqrt(2)|1.41421356237309504880| -|`M_SQRT1_2`|1/sqrt(2)|0.707106781186547524401| - -Math Constants are not defined in Standard C/C++. To use them, you must first define `_USE_MATH_DEFINES` and then include cmath or *`math.h`*. - -The file *`ATLComTime.h`* includes *`math.h`* when your project is built in Release mode. If you use one or more of the math constants in a project that also includes *`ATLComTime.h`*, you must define `_USE_MATH_DEFINES` before you include *`ATLComTime.h`*. +| Symbol | Expression | Value | +|---|---|---| +| `M_E` | e | 2.71828182845904523536 | +| `M_LOG2E` | log2(e) | 1.44269504088896340736 | +| `M_LOG10E` | log10(e) | 0.434294481903251827651 | +| `M_LN2` | ln(2) | 0.693147180559945309417 | +| `M_LN10` | ln(10) | 2.30258509299404568402 | +| `M_PI` | pi | 3.14159265358979323846 | +| `M_PI_2` | pi/2 | 1.57079632679489661923 | +| `M_PI_4` | pi/4 | 0.785398163397448309616 | +| `M_1_PI` | 1/pi | 0.318309886183790671538 | +| `M_2_PI` | 2/pi | 0.636619772367581343076 | +| `M_2_SQRTPI` | 2/sqrt(pi) | 1.12837916709551257390 | +| `M_SQRT2` | sqrt(2) | 1.41421356237309504880 | +| `M_SQRT1_2` | 1/sqrt(2) | 0.707106781186547524401 | + +The math constants aren't defined in Standard C/C++. To use them, you must first define `_USE_MATH_DEFINES`, and then include `` or ``. + +The file `` includes `` when your project is built in Release mode. If you use one or more of the math constants in a project that also includes ``, you must define `_USE_MATH_DEFINES` before you include ``. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/math-error-constants.md b/docs/c-runtime-library/math-error-constants.md index 394f6be7e7b..78d42192294 100644 --- a/docs/c-runtime-library/math-error-constants.md +++ b/docs/c-runtime-library/math-error-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: Math Error Constants" title: "Math Error Constants" ms.date: "11/04/2016" -f1_keywords: ["_PLOSS", "_UNDERFLOW", "_TLOSS", "_SING", "_DOMAIN", "_OVERFLOW"] +f1_keywords: ["CORECRT_MATH/_PLOSS", "CORECRT_MATH/_UNDERFLOW", "CORECRT_MATH/_TLOSS", "CORECRT_MATH/_SING", "CORECRT_MATH/_DOMAIN", "CORECRT_MATH/_OVERFLOW", "_PLOSS", "_UNDERFLOW", "_TLOSS", "_SING", "_DOMAIN", "_OVERFLOW"] helpviewer_keywords: ["_TLOSS constant", "_SING constant", "PLOSS constant", "UNDERFLOW constant", "_UNDERFLOW constant", "_OVERFLOW constant", "DOMAIN constant", "OVERFLOW constant", "TLOSS constant", "SING constant", "_DOMAIN constant", "_PLOSS constant", "math error constants"] ms.assetid: 4be933a6-674e-45a5-8ac9-090023542f5b --- -# Math Error Constants +# Math error constants ## Syntax -``` +```C #include ``` @@ -20,16 +20,16 @@ The math routines of the run-time library can generate math error constants. These errors, described as follows, correspond to the exception types defined in MATH.H and are returned by the `_matherr` function when a math error occurs. -|Constant|Meaning| -|--------------|-------------| -|`_DOMAIN`|Argument to function is outside domain of function.| -|`_OVERFLOW`|Result is too large to be represented in function's return type.| -|`_PLOSS`|Partial loss of significance occurred.| -|`_SING`|Argument singularity: argument to function has illegal value. (For example, value 0 is passed to function that requires nonzero value.)| -|`_TLOSS`|Total loss of significance occurred.| -|`_UNDERFLOW`|Result is too small to be represented.| +| Constant | Meaning | +|---|---| +| `_DOMAIN` | Argument to function is outside domain of function. | +| `_OVERFLOW` | Result is too large to be represented in function's return type. | +| `_PLOSS` | Partial loss of significance occurred. | +| `_SING` | Argument singularity: argument to function has illegal value. (For example, value 0 is passed to function that requires nonzero value.) | +| `_TLOSS` | Total loss of significance occurred. | +| `_UNDERFLOW` | Result is too small to be represented. | ## See also -[_matherr](../c-runtime-library/reference/matherr.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_matherr`](./reference/matherr.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/max-env.md b/docs/c-runtime-library/max-env.md index 040f8e0d817..8c4c735c43b 100644 --- a/docs/c-runtime-library/max-env.md +++ b/docs/c-runtime-library/max-env.md @@ -2,21 +2,21 @@ description: "Learn more about: _MAX_ENV" title: "_MAX_ENV" ms.date: "11/04/2016" -f1_keywords: ["_MAX_ENV", "MAX_ENV"] -helpviewer_keywords: ["MAX_ENV constant", "_MAX_ENV constant"] +f1_keywords: ["_MAX_ENV", "STDLIB/_MAX_ENV"] +helpviewer_keywords: ["_MAX_ENV constant"] ms.assetid: 66f0683e-6132-4297-b99b-6940534898b5 --- -# _MAX_ENV +# `_MAX_ENV` The maximum permissible string length of an environmental variable. ## Syntax -``` +```C #include ``` ## See also -[Environmental Constants](../c-runtime-library/environmental-constants.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[Environmental constants](./environmental-constants.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md b/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md index 166fd485fed..4c8ff5a4abf 100644 --- a/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md +++ b/docs/c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md @@ -3,14 +3,14 @@ description: "Learn more about: ___mb_cur_max_func, ___mb_cur_max_l_func, __p___ title: "___mb_cur_max_func, ___mb_cur_max_l_func, __p___mb_cur_max, __mb_cur_max" ms.date: "4/2/2020" api_name: ["___mb_cur_max_l_func", "__p___mb_cur_max", "___mb_cur_max_func", "__mb_cur_max", "_o____mb_cur_max_func"] -api_location: ["msvcr110_clr0400.dll", "msvcr110.dll", "msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-locale-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110_clr0400.dll", "msvcr110.dll", "msvcr80.dll", "msvcr100.dll", "msvcrt.dll", "msvcr90.dll", "msvcr120.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["___mb_cur_max_func", "___mb_cur_max_l_func", "__p___mb_cur_max", "__mb_cur_max"] +f1_keywords: ["STDLIB/___mb_cur_max_func", "STDLIB/___mb_cur_max_l_func", "STDLIB/__mb_cur_max", "___mb_cur_max_func", "___mb_cur_max_l_func", "__p___mb_cur_max", "__mb_cur_max"] helpviewer_keywords: ["__mb_cur_max", "___mb_cur_max_func", "___mb_cur_max_l_func", "__p___mb_cur_max"] ms.assetid: 60d36108-1ca7-45a6-8ce7-68a91f13e3a1 --- -# ___mb_cur_max_func, ___mb_cur_max_l_func, __p___mb_cur_max, __mb_cur_max +# `___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`, `__mb_cur_max` Internal CRT function. Retrieves the maximum number of bytes in a multibyte character for the current or specified locale. @@ -25,29 +25,29 @@ int * __p___mb_cur_max(void); #### Parameters -locale +*`locale`*\ The locale structure to retrieve the result from. If this value is null, the current thread locale is used. -## Return Value +## Return value The maximum number of bytes in a multibyte character for the current thread locale or the specified locale. ## Remarks -This is an internal function that the CRT uses to retrieve the current value of the [MB_CUR_MAX](../c-runtime-library/mb-cur-max.md) macro from thread local storage. We recommend that you use the `MB_CUR_MAX` macro in your code for portability. +**`___mb_cur_max_func`** is an internal function that the CRT uses to retrieve the current value of the [`MB_CUR_MAX`](./mb-cur-max.md) macro from thread local storage. We recommend that you use the `MB_CUR_MAX` macro in your code for portability. -The `__mb_cur_max` macro is a convenient way to call the `___mb_cur_max_func()` function. The `__p___mb_cur_max` function is defined for compatibility with Visual C++ 5.0 and earlier versions. +The **`__mb_cur_max`** macro is a convenient way to call the **`___mb_cur_max_func`** function. The **`__p___mb_cur_max`** function is defined for compatibility with Visual C++ 5.0 and earlier versions. Internal CRT functions are implementation-specific and subject to change with each release. We don't recommend their use in your code. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`|\, \| +| Routine | Required header | +|---|---| +| **`___mb_cur_max_func`**, **`___mb_cur_max_l_func`**, **`__p___mb_cur_max`** | \, \ | ## See also -[MB_CUR_MAX](../c-runtime-library/mb-cur-max.md) +[`MB_CUR_MAX`](./mb-cur-max.md) diff --git a/docs/c-runtime-library/mb-cur-max.md b/docs/c-runtime-library/mb-cur-max.md index 259ce065457..28e22034bae 100644 --- a/docs/c-runtime-library/mb-cur-max.md +++ b/docs/c-runtime-library/mb-cur-max.md @@ -2,7 +2,7 @@ description: "Learn more about: MB_CUR_MAX" title: "MB_CUR_MAX" ms.date: "10/18/2017" -f1_keywords: ["MB_CUR_MAX"] +f1_keywords: ["MB_CUR_MAX", "CTYPE/MB_CUR_MAX"] helpviewer_keywords: ["MB_CUR_MAX constant"] ms.assetid: fab22609-c14d-4c19-991c-bd09ff30e604 --- @@ -24,12 +24,12 @@ The value of `MB_CUR_MAX` is the maximum number of bytes in a multibyte characte ## See also -[`_mbclen`, `mblen`, `_mblen_l`](../c-runtime-library/reference/mbclen-mblen-mblen-l.md)
-[`mbstowcs`, `_mbstowcs_l`](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md)
-[`mbtowc`, `_mbtowc_l`](../c-runtime-library/reference/mbtowc-mbtowc-l.md)
-[`___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`, `__mb_cur_max`](../c-runtime-library/mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)
-[Standard Types](../c-runtime-library/standard-types.md)
-[`wcstombs`, `_wcstombs_l`](../c-runtime-library/reference/wcstombs-wcstombs-l.md)
-[`wctomb`, `_wctomb_l`](../c-runtime-library/reference/wctomb-wctomb-l.md)
-[Data Type Constants](../c-runtime-library/data-type-constants.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_mbclen`, `mblen`, `_mblen_l`](./reference/mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](./reference/mbtowc-mbtowc-l.md)\ +[`___mb_cur_max_func`, `___mb_cur_max_l_func`, `__p___mb_cur_max`, `__mb_cur_max`](./mb-cur-max-func-mb-cur-max-l-func-p-mb-cur-max-mb-cur-max.md)\ +[Standard types](./standard-types.md)\ +[`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md)\ +[`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md)\ +[Data type constants](./data-type-constants.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/memory-allocation.md b/docs/c-runtime-library/memory-allocation.md index 09a9aeca3c5..605cf305cb0 100644 --- a/docs/c-runtime-library/memory-allocation.md +++ b/docs/c-runtime-library/memory-allocation.md @@ -11,35 +11,35 @@ These routines allocate, free, and reallocate memory. ## Memory-allocation routines -|Routine|Use| -|-------------|---------| -|[`_alloca`](../c-runtime-library/reference/alloca.md), [`_malloca`](../c-runtime-library/reference/malloca.md)|Allocate memory from the stack| -|[`calloc`](../c-runtime-library/reference/calloc.md)|Allocate an array and initialize its elements to 0 (zero)| -|[`_calloc_dbg`](../c-runtime-library/reference/calloc-dbg.md)|Debug version of **`calloc`**. Only available in the debug versions of the run-time libraries| -|[`operator delete`, `operator delete[]`](../c-runtime-library/delete-operator-crt.md)|Free memory allocated on the heap | -|[`_expand`](../c-runtime-library/reference/expand.md)|Expand or shrink a block of memory without moving it| -|[`_expand_dbg`](../c-runtime-library/reference/expand-dbg.md)|Debug version of **`_expand`**. Only available in the debug versions of the run-time libraries| -|[`free`](../c-runtime-library/reference/free.md)|Free memory allocated on the heap| -|[`_free_dbg`](../c-runtime-library/reference/free-dbg.md)|Debug version of **`free`**. Only available in the debug versions of the run-time libraries| -|[`_freea`](../c-runtime-library/reference/freea.md)|Free memory allocated on the stack| -|[`_get_heap_handle`](../c-runtime-library/reference/get-heap-handle.md)|Get a Win32 `HANDLE` to the C runtime (CRT) heap.| -|[`_heapadd`](../c-runtime-library/heapadd.md)|Add memory to the heap| -|[`_heapchk`](../c-runtime-library/reference/heapchk.md)|Check the heap for consistency| -|[`_heapmin`](../c-runtime-library/reference/heapmin.md)|Release unused memory in the heap| -|[`_heapset`](../c-runtime-library/heapset.md)|Fill free heap entries with a value| -|[`_heapwalk`](../c-runtime-library/reference/heapwalk.md)|Get info about each entry in the heap| -|[`malloc`](../c-runtime-library/reference/malloc.md)|Allocate memory from the heap| -|[`_malloc_dbg`](../c-runtime-library/reference/malloc-dbg.md)|Debug version of **`malloc`**; only available in the debug versions of the run-time libraries| -|[`_msize`](../c-runtime-library/reference/msize.md)|Return the size of an allocated block of memory| -|[`_msize_dbg`](../c-runtime-library/reference/msize-dbg.md)|Debug version of **`_msize`**; only available in the debug versions of the run-time libraries| -|[`new`, `new[]`](../c-runtime-library/new-operator-crt.md)|Allocate a block of memory from the heap| -|[`_query_new_handler`](../c-runtime-library/reference/query-new-handler.md)|Get the address of the current new handler routine set by **`_set_new_handler`**| -|[`_query_new_mode`](../c-runtime-library/reference/query-new-mode.md)|Get the new handler mode set by **`_set_new_mode`** for **`malloc`**| -|[`realloc`](../c-runtime-library/reference/realloc.md)|Reallocate a block to a new size| -|[`_realloc_dbg`](../c-runtime-library/reference/realloc-dbg.md)|Debug version of **`realloc`**; only available in the debug versions of the run-time libraries| -|[`_set_new_handler`](../c-runtime-library/reference/set-new-handler.md)|Enable error-handling mechanism when the **`new`** operator fails to allocate memory, and enable compilation of the C++ Standard Libraries| -|[`_set_new_mode`](../c-runtime-library/reference/set-new-mode.md)|Set the new handler mode for **`malloc`**| +| Routine | Use | +|---|---| +| [`_alloca`](./reference/alloca.md), [`_malloca`](./reference/malloca.md) | Allocate memory from the stack | +| [`calloc`](./reference/calloc.md) | Allocate an array and initialize its elements to 0 (zero) | +| [`_calloc_dbg`](./reference/calloc-dbg.md) | Debug version of **`calloc`**. Only available in the debug versions of the run-time libraries | +| [`operator delete`, `operator delete[]`](./delete-operator-crt.md) | Free memory allocated on the heap | +| [`_expand`](./reference/expand.md) | Expand or shrink a block of memory without moving it | +| [`_expand_dbg`](./reference/expand-dbg.md) | Debug version of **`_expand`**. Only available in the debug versions of the run-time libraries | +| [`free`](./reference/free.md) | Free memory allocated on the heap | +| [`_free_dbg`](./reference/free-dbg.md) | Debug version of **`free`**. Only available in the debug versions of the run-time libraries | +| [`_freea`](./reference/freea.md) | Free memory allocated on the stack | +| [`_get_heap_handle`](./reference/get-heap-handle.md) | Get a Win32 `HANDLE` to the C runtime (CRT) heap. | +| [`_heapadd`](./heapadd.md) | Add memory to the heap | +| [`_heapchk`](./reference/heapchk.md) | Check the heap for consistency | +| [`_heapmin`](./reference/heapmin.md) | Release unused memory in the heap | +| [`_heapset`](./heapset.md) | Fill free heap entries with a value | +| [`_heapwalk`](./reference/heapwalk.md) | Get info about each entry in the heap | +| [`malloc`](./reference/malloc.md) | Allocate memory from the heap | +| [`_malloc_dbg`](./reference/malloc-dbg.md) | Debug version of **`malloc`**; only available in the debug versions of the run-time libraries | +| [`_msize`](./reference/msize.md) | Return the size of an allocated block of memory | +| [`_msize_dbg`](./reference/msize-dbg.md) | Debug version of **`_msize`**; only available in the debug versions of the run-time libraries | +| [`new`, `new[]`](./new-operator-crt.md) | Allocate a block of memory from the heap | +| [`_query_new_handler`](./reference/query-new-handler.md) | Get the address of the current new handler routine set by **`_set_new_handler`** | +| [`_query_new_mode`](./reference/query-new-mode.md) | Get the new handler mode set by **`_set_new_mode`** for **`malloc`** | +| [`realloc`](./reference/realloc.md) | Reallocate a block to a new size | +| [`_realloc_dbg`](./reference/realloc-dbg.md) | Debug version of **`realloc`**; only available in the debug versions of the run-time libraries | +| [`_set_new_handler`](./reference/set-new-handler.md) | Enable error-handling mechanism when the **`new`** operator fails to allocate memory, and enable compilation of the C++ Standard Libraries | +| [`_set_new_mode`](./reference/set-new-mode.md) | Set the new handler mode for **`malloc`** | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/multithreaded-libraries-performance.md b/docs/c-runtime-library/multithreaded-libraries-performance.md index d8aa90c5021..d1f3cc03464 100644 --- a/docs/c-runtime-library/multithreaded-libraries-performance.md +++ b/docs/c-runtime-library/multithreaded-libraries-performance.md @@ -2,30 +2,30 @@ title: "Multithreaded Libraries Performance" description: "An overview of how to get the most performance from the Microsoft C runtime multithreaded libraries." ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["threading [C++], performance", "libraries, multithreaded", "performance, multithreading", "multithreaded libraries"] ms.assetid: faa5d808-087c-463d-8f0d-8c478d137296 --- -# Multithreaded Libraries Performance +# Multithreaded libraries performance -The single-threaded CRT is no longer available. This topic discusses how to get the maximum performance from the multithreaded libraries. +The single-threaded CRT is no longer available. This article discusses how to get the maximum performance from the multithreaded libraries. ## Maximizing performance The performance of the multithreaded libraries has been improved and is close to the performance of the now-eliminated single-threaded libraries. For those situations when even higher performance is required, there are several new features. -- Independent stream locking allows you to lock a stream and then use [_nolock Functions](../c-runtime-library/nolock-functions.md) that access the stream directly. This allows lock usage to be hoisted outside critical loops. +- Independent stream locking allows you to lock a stream and then use [`_nolock` functions](./nolock-functions.md) that access the stream directly. This feature allows lock usage to be hoisted outside critical loops. -- Per-thread locale reduces the cost of locale access for multithreaded scenarios (see [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md)). +- Per-thread locale reduces the cost of locale access for multithreaded scenarios (see [`_configthreadlocale`](./reference/configthreadlocale.md)). -- Locale-dependent functions (with names ending in _l) take the locale as a parameter, removing substantial cost (for example, [printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)). +- Locale-dependent functions (with names ending in _l) take the locale as a parameter, removing substantial cost (for example, [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md)). - Optimizations for common codepages reduce the cost of many short operations. -- Defining [_CRT_DISABLE_PERFCRIT_LOCKS](../c-runtime-library/crt-disable-perfcrit-locks.md) forces all I/O operations to assume a single-threaded I/O model and use the _nolock forms of the functions. This allows highly I/O-based single-threaded applications to get better performance. +- Defining [`_CRT_DISABLE_PERFCRIT_LOCKS`](./crt-disable-perfcrit-locks.md) forces all I/O operations to assume a single-threaded I/O model and use the `_nolock` forms of the functions. This macro allows highly I/O-based single-threaded applications to get better performance. - Exposure of the CRT heap handle allows you to enable the Windows Low Fragmentation Heap (LFH) for the CRT heap, which can substantially improve performance in highly scaled scenarios. ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/new-operator-crt.md b/docs/c-runtime-library/new-operator-crt.md index dd43a78d1b4..c5273af0c40 100644 --- a/docs/c-runtime-library/new-operator-crt.md +++ b/docs/c-runtime-library/new-operator-crt.md @@ -5,10 +5,9 @@ ms.date: "11/04/2016" api_location: ["msvcr110_clr0400.dll", "msvcr100.dll", "msvcr120.dll", "msvcr110.dll", "msvcr80.dll", "msvcr90.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["new[]"] helpviewer_keywords: ["operator new[]", "vector new"] ms.assetid: 79682f85-6889-40f6-b8f7-9eed5176ea35 --- -# operator new(CRT) +# `operator new` (CRT) -Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific operator new and operator delete functions. These are now part of the C++ Standard Library. For more information, see [new and delete operators](../cpp/new-and-delete-operators.md) and [new operator](../cpp/new-operator-cpp.md) in the C++ Language Reference. +Beginning in Visual Studio 2013, the Universal C Runtime (UCRT) no longer supports the C++-specific `operator new` and `operator delete` functions. These functions are now part of the C++ Standard Library. For more information, see [`new` and `delete` operators](../cpp/new-and-delete-operators.md) and [`new` operator](../cpp/new-operator-cpp.md) in the C++ Language Reference. diff --git a/docs/c-runtime-library/nolock-functions.md b/docs/c-runtime-library/nolock-functions.md index 6cfc9a402ea..b231f2d9237 100644 --- a/docs/c-runtime-library/nolock-functions.md +++ b/docs/c-runtime-library/nolock-functions.md @@ -1,53 +1,38 @@ --- -description: "Learn more about: _nolock Functions" title: "_nolock Functions" -ms.date: "11/04/2016" +description: "Learn more about: _nolock Functions" +ms.date: "04/14/2024" helpviewer_keywords: ["_nolock functions", "nolock functions"] -ms.assetid: 7d651d87-38d2-4303-9897-fdb5f7a3e899 --- -# _nolock Functions +# `_nolock` functions -These are functions that do not perform any locking. They are provided for users requiring maximum performance. For more information, see [Multithreaded Libraries Performance](../c-runtime-library/multithreaded-libraries-performance.md). +The `_nolock` functions are versions of I/O functions that don't perform any locking. They're provided for users requiring maximum performance. For more information, see [Multithreaded libraries performance](multithreaded-libraries-performance.md). -Use _nolock functions only if your program is truly single-threaded or if it does its own locking. +Use `_nolock` functions only if your program is truly single-threaded or if it does its own locking. ## No lock routines -[_fclose_nolock](../c-runtime-library/reference/fclose-nolock.md) - -[_fflush_nolock](../c-runtime-library/reference/fflush-nolock.md) - -[_fgetc_nolock, _fgetwc_nolock](../c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md) - -[_fread_nolock](../c-runtime-library/reference/fread-nolock.md) - -[_fseek_nolock, _fseeki64_nolock](../c-runtime-library/reference/fseek-nolock-fseeki64-nolock.md) - -[_ftell_nolock, _ftelli64_nolock](../c-runtime-library/reference/ftell-nolock-ftelli64-nolock.md) - -[_fwrite_nolock](../c-runtime-library/reference/fwrite-nolock.md) - -[_getc_nolock, _getwc_nolock](../c-runtime-library/reference/getc-nolock-getwc-nolock.md) - -[_getch_nolock, _getwch_nolock](../c-runtime-library/reference/getch-nolock-getwch-nolock.md) - -[_getchar_nolock, _getwchar_nolock](../c-runtime-library/reference/getchar-nolock-getwchar-nolock.md) - -[_getche_nolock, _getwche_nolock](../c-runtime-library/reference/getche-nolock-getwche-nolock.md) - -[_getdcwd_nolock, _wgetdcwd_nolock](../c-runtime-library/reference/getdcwd-nolock-wgetdcwd-nolock.md) - -[_putc_nolock, _putwc_nolock](../c-runtime-library/reference/putc-nolock-putwc-nolock.md) - -[_putch_nolock, _putwch_nolock](../c-runtime-library/reference/putch-nolock-putwch-nolock.md) - -[_putchar_nolock, _putwchar_nolock](../c-runtime-library/reference/putchar-nolock-putwchar-nolock.md) - -[_ungetc_nolock, _ungetwc_nolock](../c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md) - -[_ungetch_nolock, _ungetwch_nolock](../c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) +| Routine | Use | +|---|---| +| [`_fclose_nolock`](reference/fclose-nolock.md) | Closes a stream without locking | +| [`_fflush_nolock`](reference/fflush-nolock.md) | Flushes a stream without locking | +| [`_fgetc_nolock`, `_fgetwc_nolock`](reference/fgetc-nolock-fgetwc-nolock.md) | Reads a character from a stream without locking | +| [`_fread_nolock`](reference/fread-nolock.md) | Reads data from a stream without locking | +| [`_fseek_nolock`, `_fseeki64_nolock`](reference/fseek-nolock-fseeki64-nolock.md) | Moves the file pointer to a specified location without locking | +| [`_ftell_nolock`, `_ftelli64_nolock`](reference/ftell-nolock-ftelli64-nolock.md) | Gets the current position of a file pointer without locking | +| [`_fwrite_nolock`](reference/fwrite-nolock.md) | Writes data to a stream without locking | +| [`_getc_nolock`, `_getwc_nolock`](reference/getc-nolock-getwc-nolock.md) | Reads a character from a stream without locking | +| [`_getch_nolock`, `_getwch_nolock`](reference/getch-nolock-getwch-nolock.md) | Gets a character from the console without echo and without locking | +| [`_getchar_nolock`, `_getwchar_nolock`](reference/getchar-nolock-getwchar-nolock.md) | Reads a character from the standard input without locking | +| [`_getche_nolock`, `_getwche_nolock`](reference/getche-nolock-getwche-nolock.md) | Gets a character from the console with echo and without locking | +| [`_getdcwd_nolock`, `_wgetdcwd_nolock`](reference/getdcwd-nolock-wgetdcwd-nolock.md) | Gets the full path of the current working directory on the specified drive | +| [`_putc_nolock`, `_putwc_nolock`](reference/putc-nolock-putwc-nolock.md) | Writes a character to a stream without locking | +| [`_putch_nolock`, `_putwch_nolock`](reference/putch-nolock-putwch-nolock.md) | Writes a character to the console without locking | +| [`_putchar_nolock`, `_putwchar_nolock`](reference/putchar-nolock-putwchar-nolock.md) | Writes a character to `stdout` without locking | +| [`_ungetc_nolock`, `_ungetwc_nolock`](reference/ungetc-nolock-ungetwc-nolock.md) | Pushes a character back onto the stream without locking | +| [`_ungetch_nolock`, `_ungetwch_nolock`](reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) | Pushes back the last character that's read from the console without locking | ## See also -[Input and Output](../c-runtime-library/input-and-output.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Input and output](input-and-output.md)\ +[Universal C runtime routines by category](run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/null-crt.md b/docs/c-runtime-library/null-crt.md index 9286b072fb5..a0e2fb57254 100644 --- a/docs/c-runtime-library/null-crt.md +++ b/docs/c-runtime-library/null-crt.md @@ -2,14 +2,14 @@ description: "Learn more about: NULL (CRT)" title: "NULL (CRT)" ms.date: "11/04/2016" -f1_keywords: ["null"] +f1_keywords: ["NULL", "VCRUNTIME/NULL"] helpviewer_keywords: ["NULL", "null pointers", "NULL, null pointer value"] ms.assetid: f9aac2a0-4f79-423f-8738-a76dccc0b1c3 --- -# NULL (CRT) +# `NULL` (CRT) -**NULL** is the null-pointer value used with many pointer operations and functions. It is equivalent to 0. **NULL** is defined in the following header files: CRTDBG.H, LOCALE.H, STDDEF.H, STDIO.H, STDLIB.H, STRING.H, TCHAR.H, TIME.H and WCHAR.H. +`NULL` is the null-pointer value used with many pointer operations and functions. It's equivalent to 0. `NULL` is defined in the following header files: CRTDBG.H, LOCALE.H, STDDEF.H, STDIO.H, STDLIB.H, STRING.H, TCHAR.H, TIME.H and WCHAR.H. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/obsolete-functions.md b/docs/c-runtime-library/obsolete-functions.md index 7a8b34d60ba..90759b70faa 100644 --- a/docs/c-runtime-library/obsolete-functions.md +++ b/docs/c-runtime-library/obsolete-functions.md @@ -3,46 +3,45 @@ title: "Obsolete functions" description: "Lists the obsolete functions that have been deprecated and removed from the Microsoft C runtime library (CRT)." ms.date: "4/2/2020" api_name: ["_beep", "_sleep", "_loaddll", "_getdllprocaddr", "_seterrormode", "is_wctype", "_getsystime", "_setsystime", "_unloaddll", "_o__beep", "_o__getdllprocaddr", "_o__getsystime", "_o__loaddll", "_o__seterrormode", "_o__setsystime", "_o__sleep", "_o__unloaddll", "_o_is_wctype"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["is_wctype", "_loaddll", "_unloaddll", "_getdllprocaddr", "_seterrormode", "_beep", "_sleep", "_getsystime", "corecrt_wctype/is_wctype", "process/_loaddll", "process/_unloaddll", "process/_getdllprocaddr", "stdlib/_seterrormode", "stdlib/_beep", "stdlib/_sleep", "time/_getsystime", "time/_setsystime"] helpviewer_keywords: ["obsolete functions", "_beep function", "_sleep function", "_seterrormode function"] ms.assetid: 8e14c2d4-1481-4240-8586-47eb43db02b0 --- -# Obsolete Functions +# Obsolete functions Certain library functions are obsolete and have more recent equivalents. We recommend you change these functions to the updated versions. Other obsolete functions have been removed from the CRT. This article lists the functions deprecated as obsolete, and the functions removed in a particular version of Visual Studio. ## Deprecated as obsolete in Visual Studio 2015 -|Obsolete function|Alternative| -|-----------------------|-----------------| -|`is_wctype`|[iswctype](../c-runtime-library/reference/isctype-iswctype-isctype-l-iswctype-l.md)| -|`_loaddll`|[LoadLibrary](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryw), [LoadLibraryEx](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw), or [LoadPackagedLibrary](/windows/win32/api/winbase/nf-winbase-loadpackagedlibrary)| -|`_unloaddll`|[FreeLibrary](/windows/win32/api/libloaderapi/nf-libloaderapi-freelibrary)| -|`_getdllprocaddr`|[GetProcAddress](../build/getprocaddress.md)| -|`_seterrormode`|[SetErrorMode](/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode)| -|`_beep`|[Beep](/windows/win32/api/utilapiset/nf-utilapiset-beep)| -|`_sleep`|[Sleep](/windows/win32/api/synchapi/nf-synchapi-sleep)| -|`_getsystime`|[GetLocalTime](/windows/win32/api/sysinfoapi/nf-sysinfoapi-getlocaltime)| -|`_setsystime`|[SetLocalTime](/windows/win32/api/sysinfoapi/nf-sysinfoapi-setlocaltime)| +| Obsolete function | Alternative | +|---|---| +| `is_wctype` | [`iswctype`](./reference/isctype-iswctype-isctype-l-iswctype-l.md) | +| `_loaddll` | [`LoadLibrary`](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryw), [`LoadLibraryEx`](/windows/win32/api/libloaderapi/nf-libloaderapi-loadlibraryexw), or [`LoadPackagedLibrary`](/windows/win32/api/winbase/nf-winbase-loadpackagedlibrary) | +| `_unloaddll` | [`FreeLibrary`](/windows/win32/api/libloaderapi/nf-libloaderapi-freelibrary) | +| `_getdllprocaddr` | [`GetProcAddress`](../build/getprocaddress.md) | +| `_seterrormode` | [`SetErrorMode`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode) | +| `_beep` | [`Beep`](/windows/win32/api/utilapiset/nf-utilapiset-beep) | +| `_sleep` | [`Sleep`](/windows/win32/api/synchapi/nf-synchapi-sleep) | +| `_getsystime` | [`GetLocalTime`](/windows/win32/api/sysinfoapi/nf-sysinfoapi-getlocaltime) | +| `_setsystime` | [`SetLocalTime`](/windows/win32/api/sysinfoapi/nf-sysinfoapi-setlocaltime) | ## Removed from the CRT in Visual Studio 2015 -|Obsolete function|Alternative| -|-----------------------|-----------------| -|[_cgets, _cgetws](../c-runtime-library/cgets-cgetws.md)|[_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md)| -|[gets, _getws](../c-runtime-library/gets-getws.md)|[gets_s, _getws_s](../c-runtime-library/reference/gets-s-getws-s.md)| -|[_get_output_format](../c-runtime-library/get-output-format.md)|None| -|[_heapadd](../c-runtime-library/heapadd.md)|None| -|[_heapset](../c-runtime-library/heapset.md)|None| -|[inp, inpw, _inp, _inpw, _inpd](../c-runtime-library/inp-inpw-inpd.md)|None| -|[outp, outpw, _outp, _outpw, _outpd](../c-runtime-library/outp-outpw-outpd.md)|None| -|[_set_output_format](../c-runtime-library/set-output-format.md)|None| +| Obsolete function | Alternative | +|---|---| +| [`_cgets`, `_cgetws`](./cgets-cgetws.md) | [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md) | +| [`gets`, `_getws`](./gets-getws.md) | [`gets_s`, `_getws_s`](./reference/gets-s-getws-s.md) | +| [`_get_output_format`](./get-output-format.md) | None | +| [`_heapadd`](./heapadd.md) | None | +| [`_heapset`](./heapset.md) | None | +| [`inp`, `inpw`, `_inp`, `_inpw`, `_inpd`](./inp-inpw-inpd.md) | None | +| [`outp`, `outpw`, `_outp`, `_outpw`, `_outpd`](./outp-outpw-outpd.md) | None | +| [`_set_output_format`](./set-output-format.md) | None | ## Removed from the CRT in earlier versions of Visual Studio -[_lock](../c-runtime-library/lock.md) - -[_unlock](../c-runtime-library/unlock.md) +[`_lock`](./lock.md)\ +[`_unlock`](./unlock.md) diff --git a/docs/c-runtime-library/outp-outpw-outpd.md b/docs/c-runtime-library/outp-outpw-outpd.md index 161f457d1ef..bc7244ca7a7 100644 --- a/docs/c-runtime-library/outp-outpw-outpd.md +++ b/docs/c-runtime-library/outp-outpw-outpd.md @@ -12,7 +12,7 @@ ms.assetid: c200fe22-41f6-46fd-b0be-ebb805b35181 --- # `outp`, `outpw`, `_outp`, `_outpw`, `_outpd` -Outputs, at a port, a byte (`outp`, `_outp`), a word (`outpw`, `_outpw`), or a double word (`_outpd`). +Outputs, at a port, a byte (**`outp`**, **`_outp`**), a word (**`outpw`**, **`_outpw`**), or a double word (**`_outpd`**). > [!IMPORTANT] > These functions are obsolete. Beginning in Visual Studio 2015, they are not available in the CRT.\ @@ -43,35 +43,35 @@ Port number. *`data_byte`*, *`data_word`*\ Output values. -## Return Value +## Return value The functions return the data output. There's no error return. ## Remarks -The `_outp`, `_outpw`, and `_outpd` functions write a byte, a word, and a double word, respectively, to the specified output port. The *`port`* argument can be any unsigned integer in the range 0 - 65,535. *`data_byte`* can be any integer in the range 0 - 255. *`data_word`* can be any value in the range of an integer, an unsigned short integer, and an unsigned long integer, respectively. +The **`_outp`**, **`_outpw`**, and **`_outpd`** functions write a byte, a word, and a double word, respectively, to the specified output port. The *`port`* argument can be any unsigned integer in the range 0 - 65,535. *`data_byte`* can be any integer in the range 0 - 255. *`data_word`* can be any value in the range of an integer, an unsigned short integer, and an unsigned long integer, respectively. Because these functions write directly to an I/O port, they can't be used in user-mode Windows code. -For information about using I/O ports in the Windows operating system, see [Serial Communications](/previous-versions/ff802693(v=msdn.10)). +For information about using I/O ports in the Windows operating system, see [Serial communications](/previous-versions/ff802693(v=msdn.10)). -The `outp` and `outpw` names are older, deprecated names for the `_outp` and `_outpw` functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +The **`outp`** and **`outpw`** names are older, deprecated names for the **`_outp`** and **`_outpw`** functions. For more information, see [POSIX function names](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_outp`|\| -|`_outpw`|\| -|`_outpd`|\| +| Routine | Required header | +|---|---| +| **`_outp`** | \ | +| **`_outpw`** | \ | +| **`_outpd`** | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](./compatibility.md). ## Libraries -All versions of the [C run-time libraries](../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](./crt-library-features.md). ## See also -[Console and Port I/O](../c-runtime-library/console-and-port-i-o.md)\ -[`inp`, `inpw`, `_inp`, `_inpw`, `_inpd`](../c-runtime-library/inp-inpw-inpd.md) +[Console and port I/O](./console-and-port-i-o.md)\ +[`inp`, `inpw`, `_inp`, `_inpw`, `_inpd`](./inp-inpw-inpd.md) diff --git a/docs/c-runtime-library/p-commode.md b/docs/c-runtime-library/p-commode.md index f9ced688c9b..3367ece1ce2 100644 --- a/docs/c-runtime-library/p-commode.md +++ b/docs/c-runtime-library/p-commode.md @@ -3,14 +3,14 @@ description: "Learn more about: __p__commode" title: "__p__commode" ms.date: "4/2/2020" api_name: ["__p__commode", "_o___p__commode"] -api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr110.dll", "msvcrt.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__p__commode"] +f1_keywords: ["STDIO/__p__commode", "__p__commode"] helpviewer_keywords: ["__p__commode"] ms.assetid: 4380acb8-e3e4-409c-a60f-6205ac5189ce --- -# __p__commode +# `__p__commode` Points to the `_commode` global variable, which specifies the default *file commit mode* for file I/O operations. @@ -21,20 +21,20 @@ int * __p__commode( ); ``` -## Return Value +## Return value Pointer to the `_commode` global variable. ## Remarks -The `__p__commode` function is for internal use only, and should not be called from user code. +The **`__p__commode`** function is for internal use only, and shouldn't be called from user code. -File commit mode specifies when critical data is written to disk. For more information, see [fflush](../c-runtime-library/reference/fflush.md). +File commit mode specifies when critical data is written to disk. For more information, see [`fflush`](./reference/fflush.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__p\__commode|internal.h| +| Routine | Required header | +|---|---| +| **`__p__commode`** | `internal.h` | diff --git a/docs/c-runtime-library/p-fmode.md b/docs/c-runtime-library/p-fmode.md index 8d2e7075ca8..ce214aea1b1 100644 --- a/docs/c-runtime-library/p-fmode.md +++ b/docs/c-runtime-library/p-fmode.md @@ -3,14 +3,14 @@ description: "Learn more about: __p__fmode" title: "__p__fmode" ms.date: "4/2/2020" api_name: ["__p__fmode", "_o___p__fmode"] -api_location: ["msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr80.dll", "msvcr120.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__p__fmode"] +f1_keywords: ["STDLIB/__p__fmode", "__p__fmode"] helpviewer_keywords: ["__p__fmode"] ms.assetid: 1daa1394-81eb-43aa-a71b-4cc6acf3207b --- -# __p__fmode +# `__p__fmode` Points to the `_fmode` global variable, which specifies the default *file translation mode* for file I/O operations. @@ -21,20 +21,20 @@ int* __p__fmode( ); ``` -## Return Value +## Return value Pointer to the `_fmode` global variable. ## Remarks -The `__p__fmode` function is for internal use only, and should not be called from user code. +The **`__p__fmode`** function is for internal use only, and shouldn't be called from user code. -File translation mode specifies either `binary` or `text` translation for [_open](../c-runtime-library/reference/open-wopen.md) and [_pipe](../c-runtime-library/reference/pipe.md) I/O operations. For more information, see [_fmode](../c-runtime-library/fmode.md). +File translation mode specifies either `binary` or `text` translation for [`_open`](./reference/open-wopen.md) and [`_pipe`](./reference/pipe.md) I/O operations. For more information, see [`_fmode`](./fmode.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__p\__fmode|stdlib.h| +| Routine | Required header | +|---|---| +| **`__p__fmode`** | `` | diff --git a/docs/c-runtime-library/parameter-validation.md b/docs/c-runtime-library/parameter-validation.md index 6e1ee99025f..c16c5b84dd5 100644 --- a/docs/c-runtime-library/parameter-validation.md +++ b/docs/c-runtime-library/parameter-validation.md @@ -1,28 +1,27 @@ --- title: "Parameter Validation" description: "A description of parameter validation in the Microsoft C runtime library." -ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.date: 11/04/2016 +ms.topic: "concept-article" helpviewer_keywords: ["parameters, validation"] -ms.assetid: 019dd5f0-dc61-4d2e-b4e9-b66409ddf1f2 --- -# Parameter Validation +# Parameter validation -Most of the security-enhanced CRT functions, and many that aren't, validate their parameters for things like checking pointers for **NULL**, that integers fall into a valid range, or that enumeration values are valid. If an invalid parameter is found, the invalid parameter handler is called. +Most of the security-enhanced CRT functions, and many that aren't, validate their parameters for things like checking pointers for `NULL`, that integers fall into a valid range, or that enumeration values are valid. If an invalid parameter is found, the invalid parameter handler is called. -## Invalid Parameter Handler Routine +## Invalid parameter handler routine -When a C Runtime Library function detects an invalid parameter, it captures some information about the error, and then calls a macro that wraps an invalid parameter handler dispatch function. Which will be one of [_invalid_parameter](../c-runtime-library/reference/invalid-parameter-functions.md), [_invalid_parameter_noinfo](../c-runtime-library/reference/invalid-parameter-functions.md), or [_invalid_parameter_noinfo_noreturn](../c-runtime-library/reference/invalid-parameter-functions.md). Which dispatch function is called depends on whether your code is, respectively, a debug build, a retail build, or the error isn't considered recoverable. +When a C Runtime Library function detects an invalid parameter, it captures some information about the error, and then calls a macro that wraps an invalid parameter handler dispatch function. Which will be one of [`_invalid_parameter`](./reference/invalid-parameter-functions.md), [`_invalid_parameter_noinfo`](./reference/invalid-parameter-functions.md), or [`_invalid_parameter_noinfo_noreturn`](./reference/invalid-parameter-functions.md). Which dispatch function is called depends on whether your code is, respectively, a debug build, a retail build, or the error isn't considered recoverable. -In debug builds, the invalid parameter macro usually raises a failed assertion and a debugger breakpoint before the dispatch function is called. When the code is executed, the assertion may be reported to the user in a dialog box that has "Abort", "Retry", and "Continue" or similar choices depending on the operating system and runtime library version. These options allow the user to immediately terminate the program, to attach a debugger, or to let the existing code continue to run which calls the dispatch function. +In debug builds, the invalid parameter macro usually raises a failed assertion and a debugger breakpoint before the dispatch function is called. When the code runs, the assertion may be reported to the user in a dialog box that has "Abort", "Retry", and "Continue" or similar choices that depend on the operating system and CRT version. These options allow the user to immediately terminate the program, to attach a debugger, or to let the existing code continue to run which calls the dispatch function. The invalid parameter handler dispatch function calls the currently assigned invalid parameter handler. By default, the invalid parameter calls `_invoke_watson`, which causes the application to close and generate a mini-dump. If enabled by the operating system, a dialog box asks the user if they want to send the crash dump to Microsoft for analysis. -You can change this behavior by using the functions [_set_invalid_parameter_handler](../c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) or [_set_thread_local_invalid_parameter_handler](../c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) to set the invalid parameter handler to your own function. If the function you specify does not terminate the application, control is returned to the function that received the invalid parameters. In the CRT, these functions will normally stop function execution, set `errno` to an error code, and return an error code. In many cases, the `errno` value and the return value are both `EINVAL`, to indicate an invalid parameter. In some cases, a more specific error code is returned, such as `EBADF` for a bad file pointer passed in as a parameter. +You can change this behavior by using the functions [`_set_invalid_parameter_handler`](./reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) or [`_set_thread_local_invalid_parameter_handler`](./reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md) to set the invalid parameter handler to your own function. If the function you specify doesn't terminate the application, control is returned to the function that received the invalid parameters. In the CRT, these functions will normally stop function execution, set `errno` to an error code, and return an error code. In many cases, the `errno` value and the return value are both `EINVAL`, to indicate an invalid parameter. In some cases, a more specific error code is returned, such as `EBADF` for a bad file pointer passed in as a parameter. -For more information on `errno`, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information on `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](./errno-doserrno-sys-errlist-and-sys-nerr.md). ## See also -[Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md)\ -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[Security features in the CRT](./security-features-in-the-crt.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/path-field-limits.md b/docs/c-runtime-library/path-field-limits.md index 75144b8a9ed..1890385a5d7 100644 --- a/docs/c-runtime-library/path-field-limits.md +++ b/docs/c-runtime-library/path-field-limits.md @@ -2,11 +2,11 @@ description: "Learn more about: Path Field Limits" title: "Path Field Limits" ms.date: "11/04/2016" -f1_keywords: ["_MAX_EXT", "_MAX_DIR", "_MAX_PATH", "_MAX_FNAME", "_MAX_DRIVE"] +f1_keywords: ["_MAX_EXT", "_MAX_DIR", "_MAX_PATH", "_MAX_FNAME", "_MAX_DRIVE", "STDLIB/_MAX_EXT", "STDLIB/_MAX_DIR", "STDLIB/_MAX_PATH", "STDLIB/_MAX_FNAME", "STDLIB/_MAX_DRIVE"] helpviewer_keywords: ["path field constants", "MAX_FNAME constant", "_MAX_DIR constant", "_MAX_DRIVE constant", "paths, maximum limit", "_MAX_PATH constant", "MAX_DRIVE constant", "_MAX_FNAME constant", "_MAX_EXT constant", "MAX_DIR constant", "MAX_EXT constant"] ms.assetid: 2b5d0e43-1347-45b4-8397-24a8a45c444e --- -# Path Field Limits +# Path field limits ## Syntax @@ -18,17 +18,17 @@ ms.assetid: 2b5d0e43-1347-45b4-8397-24a8a45c444e These constants define the maximum length for the path and for the individual fields within the path. -|Constant|Meaning| -|--------------|-------------| -|`_MAX_DIR`|Maximum length of directory component| -|`_MAX_DRIVE`|Maximum length of drive component| -|`_MAX_EXT`|Maximum length of extension component| -|`_MAX_FNAME`|Maximum length of filename component| -|`_MAX_PATH`|Maximum length of full path| +| Constant | Meaning | +|---|---| +| `_MAX_DIR` | Maximum length of directory component | +| `_MAX_DRIVE` | Maximum length of drive component | +| `_MAX_EXT` | Maximum length of extension component | +| `_MAX_FNAME` | Maximum length of filename component | +| `_MAX_PATH` | Maximum length of full path | > [!NOTE] > The C Runtime supports path lengths up to 32768 characters in length, but it is up to the operating system, specifically the file system, to support these longer paths. The sum of the fields should not exceed `_MAX_PATH` for full backwards compatibility with FAT32 file systems. The Windows NTFS file system supports paths up to 32768 characters in length, but only when using the Unicode APIs. When using long path names, prefix the path with the characters \\\\?\ and use the Unicode versions of the C Runtime functions. ## See also -[Global Constants](../c-runtime-library/global-constants.md) +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/pctype-func.md b/docs/c-runtime-library/pctype-func.md index 29d5695873d..e3918dc32f5 100644 --- a/docs/c-runtime-library/pctype-func.md +++ b/docs/c-runtime-library/pctype-func.md @@ -3,14 +3,14 @@ description: "Learn more about: __pctype_func" title: "__pctype_func" ms.date: "1/14/2021" api_name: ["__pctype_func", "_o___pctype_func"] -api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-locale-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr110_clr0400.dll", "msvcr110.dll", "msvcr120.dll", "msvcr90.dll", "msvcr100.dll", "msvcr80.dll", "api-ms-win-crt-locale-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__pctype_func"] +f1_keywords: ["CORECRT_WCTYPE/__pctype_func", "__pctype_func"] helpviewer_keywords: ["__pctype_func"] ms.assetid: d52b8add-d07d-4516-a22f-e836cde0c57f --- -# __pctype_func +# `__pctype_func` Retrieves a pointer to an array of character classification information. @@ -21,22 +21,22 @@ const unsigned short *__pctype_func( ) ``` -## Return Value +## Return value A pointer to an array of character classification information. ## Remarks -The information in the character classification table is for internal use only, and is used by various functions that classify characters of type **`char`**. For more information, see the `Remarks` section of [_pctype, _pwctype, _wctype, _mbctype, _mbcasemap](../c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md). +The information in the character classification table is for internal use only, and is used by various functions that classify characters of type **`char`**. For more information, see the `Remarks` section of [`_pctype`, `_pwctype`, `_wctype`, `_mbctype`, `_mbcasemap`](./pctype-pwctype-wctype-mbctype-mbcasemap.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__pctype_func|ctype.h| +| Routine | Required header | +|---|---| +| **`__pctype_func`** | `` | ## See also -[_pctype, _pwctype, _wctype, _mbctype, _mbcasemap](../c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md) +[`_pctype`, `_pwctype`, `_wctype`, `_mbctype`, `_mbcasemap`](./pctype-pwctype-wctype-mbctype-mbcasemap.md) diff --git a/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md b/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md index 069c9d6b643..9359692fd97 100644 --- a/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md +++ b/docs/c-runtime-library/pctype-pwctype-wctype-mbctype-mbcasemap.md @@ -6,17 +6,17 @@ api_name: ["_pctype", "_pwctype", "_wctype", "_mbctype", "_mbcasemap"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["pwctype", "pctype", "mbctype", "mbcasemap", "_mbcasemap", "_mbctype", "_pctype", "_wctype", "_pcwtype"] -helpviewer_keywords: ["_wctype function", "_pwctype function", "_pctype function", "_mbctype function", "wctype function", "pwctype function", "pctype function", "mbcasemap function", "mbctype function", "_mbcasemap function"] +f1_keywords: ["_pctype", "CORECRT_WCTYPE/_pctype", "_pwctype", "CORECRT_WCTYPE/_pcwtype", "_mbctype", "MBCTYPE/_mbctype", "_mbcasemap", "MBCTYPE/_mbcasemap", "_wctype"] +helpviewer_keywords: ["_pctype global variable", "_pwctype global variable", "_wctype global variable", "_mbctype global variable", "_mbcasemap global variable"] ms.assetid: 7f5e1107-c43b-4b9b-b387-781e6d2373cb --- -# _pctype, _pwctype, _wctype, _mbctype, _mbcasemap +# `_pctype`, `_pwctype`, `_wctype`, `_mbctype`, `_mbcasemap` These global variables contain information used by the character classification functions. They are for internal use only. ## Syntax -``` +```C extern const unsigned short *_pctype; extern const wctype_t *_pwctype; extern const unsigned short _wctype[]; @@ -26,9 +26,9 @@ extern unsigned char _mbcasemap[]; ## Remarks -The information in `_pctype`, `_pwctype`, and `_wctype` is used internally by [isupper, _isupper_l, iswupper, _iswupper_l](../c-runtime-library/reference/isupper-isupper-l-iswupper-iswupper-l.md), [islower, iswlower, _islower_l, _iswlower_l](../c-runtime-library/reference/islower-iswlower-islower-l-iswlower-l.md), [isdigit, iswdigit, _isdigit_l, _iswdigit_l](../c-runtime-library/reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [isxdigit, iswxdigit, _isxdigit_l, _iswxdigit_l](../c-runtime-library/reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md), [isspace, iswspace, _isspace_l, _iswspace_l](../c-runtime-library/reference/isspace-iswspace-isspace-l-iswspace-l.md), [isalnum, iswalnum, _isalnum_l, _iswalnum_l](../c-runtime-library/reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [ispunct, iswpunct, _ispunct_l, _iswpunct_l](../c-runtime-library/reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [isgraph, iswgraph, _isgraph_l, _iswgraph_l](../c-runtime-library/reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [iscntrl, iswcntrl, _iscntrl_l, _iswcntrl_l](../c-runtime-library/reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md), [toupper, _toupper, towupper, _toupper_l, _towupper_l](../c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [tolower, _tolower, towlower, _tolower_l, and _towlower_l](../c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md) functions. These functions should be used instead of accessing these global variables. +The information in `_pctype`, `_pwctype`, and `_wctype` is used internally by [`isupper`, `_isupper_l`, `iswupper`, `_iswupper_l`](./reference/isupper-isupper-l-iswupper-iswupper-l.md), [`islower`, `iswlower`, `_islower_l`, `_iswlower_l`](./reference/islower-iswlower-islower-l-iswlower-l.md), [`isdigit`, `iswdigit`, `_isdigit_l`, `_iswdigit_l`](./reference/isdigit-iswdigit-isdigit-l-iswdigit-l.md), [`isxdigit`, `iswxdigit`, `_isxdigit_l`, `_iswxdigit_l`](./reference/isxdigit-iswxdigit-isxdigit-l-iswxdigit-l.md), [`isspace`, `iswspace`, `_isspace_l`, `_iswspace_l`](./reference/isspace-iswspace-isspace-l-iswspace-l.md), [`isalnum`, `iswalnum`, `_isalnum_l`, `_iswalnum_l`](./reference/isalnum-iswalnum-isalnum-l-iswalnum-l.md), [`ispunct`, `iswpunct`, `_ispunct_l`, `_iswpunct_l`](./reference/ispunct-iswpunct-ispunct-l-iswpunct-l.md), [`isgraph`, `iswgraph`, `_isgraph_l`, `_iswgraph_l`](./reference/isgraph-iswgraph-isgraph-l-iswgraph-l.md), [`iscntrl`, `iswcntrl`, `_iscntrl_l`, `_iswcntrl_l`](./reference/iscntrl-iswcntrl-iscntrl-l-iswcntrl-l.md), [`toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l`](./reference/toupper-toupper-towupper-toupper-l-towupper-l.md), [`tolower`, `_tolower`, `towlower`, `_tolower_l`, and `_towlower_l`](./reference/tolower-tolower-towlower-tolower-l-towlower-l.md) functions. These functions should be used instead of accessing these global variables. -The information in `_mbctype` and `_mbcasemap` is used internally by [_ismbbkalnum, _ismbbkalnum_l](../c-runtime-library/reference/ismbbkalnum-ismbbkalnum-l.md), [_ismbbkana, _ismbbkana_l](../c-runtime-library/reference/ismbbkana-ismbbkana-l.md), [_ismbbkpunct, _ismbbkpunct_l](../c-runtime-library/reference/ismbbkpunct-ismbbkpunct-l.md), [_ismbbkprint, _ismbbkprint_l](../c-runtime-library/reference/ismbbkprint-ismbbkprint-l.md), [_ismbbalpha](reference/ismbbalpha-ismbbalpha-l.md), [_ismbbpunct, _ismbbpunct_l](../c-runtime-library/reference/ismbbpunct-ismbbpunct-l.md), [_ismbbalnum, _ismbbalnum_l](../c-runtime-library/reference/ismbbalnum-ismbbalnum-l.md), [_ismbbprint, _ismbbprint_l](../c-runtime-library/reference/ismbbprint-ismbbprint-l.md), [_ismbbgraph, _ismbbgraph_l](../c-runtime-library/reference/ismbbgraph-ismbbgraph-l.md), [_ismbblead, _ismbblead_l](../c-runtime-library/reference/ismbblead-ismbblead-l.md), [_ismbbtrail, _ismbbtrail_l](../c-runtime-library/reference/ismbbtrail-ismbbtrail-l.md), [_ismbslead, _ismbstrail, _ismbslead_l, _ismbstrail_l](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md), [_ismbslead, _ismbstrail, _ismbslead_l, and _ismbstrail_l](../c-runtime-library/reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md). Use these functions instead of accessing the global variables. +The information in `_mbctype` and `_mbcasemap` is used internally by [`_ismbbkalnum`, `_ismbbkalnum_l`](./reference/ismbbkalnum-ismbbkalnum-l.md), [`_ismbbkana`, `_ismbbkana_l`](./reference/ismbbkana-ismbbkana-l.md), [`_ismbbkpunct`, `_ismbbkpunct_l`](./reference/ismbbkpunct-ismbbkpunct-l.md), [`_ismbbkprint`, `_ismbbkprint_l`](./reference/ismbbkprint-ismbbkprint-l.md), [`_ismbbalpha`](reference/ismbbalpha-ismbbalpha-l.md), [`_ismbbpunct`, `_ismbbpunct_l`](./reference/ismbbpunct-ismbbpunct-l.md), [`_ismbbalnum`, `_ismbbalnum_l`](./reference/ismbbalnum-ismbbalnum-l.md), [`_ismbbprint`, `_ismbbprint_l`](./reference/ismbbprint-ismbbprint-l.md), [`_ismbbgraph`, `_ismbbgraph_l`](./reference/ismbbgraph-ismbbgraph-l.md), [`_ismbblead`, `_ismbblead_l`](./reference/ismbblead-ismbblead-l.md), [`_ismbbtrail`, `_ismbbtrail_l`](./reference/ismbbtrail-ismbbtrail-l.md), [`_ismbslead`, `_ismbstrail`, `_ismbslead_l`, `_ismbstrail_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md), [`_ismbslead`, `_ismbstrail`, `_ismbslead_l`, and `_ismbstrail_l`](./reference/ismbslead-ismbstrail-ismbslead-l-ismbstrail-l.md). Use these functions instead of accessing the global variables. ## Requirements @@ -36,5 +36,5 @@ Not for public use. ## See also -[is, isw Routines](../c-runtime-library/is-isw-routines.md)
-[__pctype_func](../c-runtime-library/pctype-func.md) +[`is`, `isw` routines](./is-isw-routines.md)\ +[`__pctype_func`](./pctype-func.md) diff --git a/docs/c-runtime-library/pgmptr-wpgmptr.md b/docs/c-runtime-library/pgmptr-wpgmptr.md index 1118e345ba6..e5779e90754 100644 --- a/docs/c-runtime-library/pgmptr-wpgmptr.md +++ b/docs/c-runtime-library/pgmptr-wpgmptr.md @@ -2,48 +2,48 @@ description: "Learn more about: _pgmptr, _wpgmptr" title: "_pgmptr, _wpgmptr" ms.date: "11/04/2016" -f1_keywords: ["pgmptr", "_pgmptr", "wpgmptr", "_wpgmptr"] -helpviewer_keywords: ["wpgmptr function", "_wpgmptr function", "_pgmptr function", "pgmptr function"] +f1_keywords: ["_pgmptr", "STDLIB/_pgmptr", "_wpgmptr", "STDLIB/_wpgmptr"] +helpviewer_keywords: ["_pgmptr global variable", "_wpgmptr global variable"] ms.assetid: 4d44b515-0eff-4136-8bc4-684195f218f5 --- -# _pgmptr, _wpgmptr +# `_pgmptr`, `_wpgmptr` -The path of the executable file. Deprecated; use [_get_pgmptr](../c-runtime-library/reference/get-pgmptr.md) and [_get_wpgmptr](../c-runtime-library/reference/get-wpgmptr.md). +The path of the executable file. Deprecated; use [`_get_pgmptr`](./reference/get-pgmptr.md) and [`_get_wpgmptr`](./reference/get-wpgmptr.md). ## Syntax -``` +```C extern char *_pgmptr; extern wchar_t *_wpgmptr; ``` ## Remarks -When a program is run from the command interpreter (Cmd.exe), `_pgmptr` is automatically initialized to the full path of the executable file. For example, if Hello.exe is in C:\BIN and C:\BIN is in the path, `_pgmptr` is set to C:\BIN\Hello.exe when you execute: +When a program is run from the command interpreter (Cmd.exe), **`_pgmptr`** is automatically initialized to the full path of the executable file. For example, if Hello.exe is in C:\BIN and C:\BIN is in the path, **`_pgmptr`** is set to *`C:\BIN\Hello.exe`* when you execute: -``` +```cmd C> hello ``` -When a program is not run from the command line, `_pgmptr` might be initialized to the program name (the file's base name without the file name extension) or to a file name, relative path, or full path. +When a program isn't run from the command line, **`_pgmptr`** might be initialized to the program name (the file's base name without the file name extension) or to a file name, relative path, or full path. -`_wpgmptr` is the wide-character counterpart of `_pgmptr` for use with programs that use `wmain`. +**`_wpgmptr`** is the wide-character counterpart of **`_pgmptr`** for use with programs that use `wmain`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_tpgmptr`|`_pgmptr`|`_pgmptr`|`_wpgmptr`| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tpgmptr` | **`_pgmptr`** | **`_pgmptr`** | **`_wpgmptr`** | ## Requirements -|Variable|Required header| -|--------------|---------------------| -|`_pgmptr`, `_wpgmptr`|\| +| Variable | Required header | +|---|---| +| **`_pgmptr`**, **`_wpgmptr`** | \ | ## Example -The following program demonstrates the use of `_pgmptr`. +The following program demonstrates the use of **`_pgmptr`**. ```c // crt_pgmptr.c @@ -60,8 +60,8 @@ int main( void ) } ``` -You could use `_wpgmptr` by changing `%Fs` to `%S` and `main` to `wmain`. +You could use **`_wpgmptr`** by changing `%Fs` to `%S` and `main` to `wmain`. ## See also -[Global Variables](../c-runtime-library/global-variables.md) +[Global variables](./global-variables.md) diff --git a/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md b/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md index 139e91d7885..6dc1fb53c42 100644 --- a/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md +++ b/docs/c-runtime-library/potential-errors-passing-crt-objects-across-dll-boundaries.md @@ -2,7 +2,7 @@ title: "Potential Errors Passing CRT Objects Across DLL Boundaries" description: "An overview of potential problems you may come across when passing Microsoft C runtime objects across a dynamic link library (DLL) boundary." ms.date: 06/29/2022 -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["DLL conflicts [C++]"] ms.assetid: c217ffd2-5d9a-4678-a1df-62a637a96460 --- @@ -131,4 +131,4 @@ New MYLIB variable is: c:\mylib;c:\yourlib ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/printf-p-positional-parameters.md b/docs/c-runtime-library/printf-p-positional-parameters.md index 7f64e9d3e9e..4237a034ea0 100644 --- a/docs/c-runtime-library/printf-p-positional-parameters.md +++ b/docs/c-runtime-library/printf-p-positional-parameters.md @@ -2,31 +2,28 @@ description: "Learn more about: printf_p Positional Parameters" title: "printf_p Positional Parameters" ms.date: "11/04/2016" -api_location: ["msvcr120.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr90.dll", "msvcr80.dll", "msvcr100.dll"] -api_type: ["DLLExport"] -topic_type: ["apiref"] helpviewer_keywords: ["_printf_p function, positional parameters", "printf_p function, positional parameters"] ms.assetid: beb4fd85-a7aa-4665-9085-2c907a5b9ab0 --- -# printf_p Positional Parameters +# `printf_p` positional parameters -Positional parameters provide the ability to specify by number which of the arguments is to be substituted into a field in a format string. The following positional parameter `printf` functions are available: +Positional parameters let you specify by number the argument to substitute into a field in a format string. The following positional parameter `printf` functions are available: | Non-positional printf functions | Positional parameter equivalents | |---|---| -|[printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)|[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](../c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)| -|[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)|[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](../c-runtime-library/reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)| -|[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md)|[_cprintf_p, _cprintf_p_l, _cwprintf_p, _cwprintf_p_l](../c-runtime-library/reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md)| -|[fprintf, _fprintf_l, fwprintf, _fwprintf_l](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)|[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](../c-runtime-library/reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)| -|[vprintf, _vprintf_l, vwprintf, _vwprintf_l](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md)|[_vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l](../c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md)| -|[vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)|[_vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l](../c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)| -|[vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, \__vswprintf_l](../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md)|[_vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l](../c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)| +| [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md) | [`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](./reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md) | +| [`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) | [`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](./reference/sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md) | +| [`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md) | [`_cprintf_p`, `_cprintf_p_l`, `_cwprintf_p`, `_cwprintf_p_l`](./reference/cprintf-p-cprintf-p-l-cwprintf-p-cwprintf-p-l.md) | +| [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) | [`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](./reference/fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md) | +| [`vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l`](./reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md) | [`_vprintf_p`, `_vprintf_p_l`, `_vwprintf_p`, `_vwprintf_p_l`](./reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md) | +| [`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](./reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) | [`_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l`](./reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md) | +| [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `__vswprintf_l`](./reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) | [`_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l`](./reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md) | ## How to specify positional parameters ### Parameter indexing -By default, if no positional formatting is present, the positional functions behave identically to the non-positional ones. You specify the positional parameter to format by using `%n$` at the beginning of the format specifier, where `n` is the position of the parameter to format in the parameter list. The parameter position starts at 1 for the first argument after the format string. The remainder of the format specifier follows the same rules as the `printf` format specifier. For more information about format specfiers, see [Format Specification Syntax: printf and wprintf Functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +By default, if no positional formatting is present, the positional functions behave identically to the non-positional ones. You specify the positional parameter to format by using `%n$` at the beginning of the format specifier, where `n` is the position of the parameter to format in the parameter list. The parameter position starts at 1 for the first argument after the format string. The remainder of the format specifier follows the same rules as the `printf` format specifier. For more information about format specifiers, see [Format specification syntax: `printf` and `wprintf` functions](./format-specification-syntax-printf-and-wprintf-functions.md). Here's an example of positional formatting: @@ -34,21 +31,21 @@ Here's an example of positional formatting: _printf_p("%1$s %2$s", "November", "10"); ``` -This prints: +This example prints: -``` +```Output November 10 ``` -The order of the numbers used doesn't need to match the order of the arguments. For example, this is a valid format string: +The order of the numbers used doesn't need to match the order of the arguments. For example, here's a valid format string: ```C _printf_p("%2$s %1$s", "November", "10"); ``` -This prints: +This example prints: -``` +```Output 10 November ``` @@ -58,9 +55,9 @@ Unlike traditional format strings, positional parameters may be used more than o _printf_p("%1$d times %1$d is %2$d", 10, 100); ``` -This prints: +This example prints: -``` +```Output 10 times 10 is 100 ``` @@ -136,4 +133,4 @@ ghi abc def ## See also -[Format Specification Syntax: printf and wprintf Functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) +[Format specification syntax: `printf` and `wprintf` functions](./format-specification-syntax-printf-and-wprintf-functions.md) diff --git a/docs/c-runtime-library/process-and-environment-control.md b/docs/c-runtime-library/process-and-environment-control.md index 16fcf184a84..06d36fd705f 100644 --- a/docs/c-runtime-library/process-and-environment-control.md +++ b/docs/c-runtime-library/process-and-environment-control.md @@ -5,74 +5,74 @@ ms.date: "11/04/2016" f1_keywords: ["c.programs"] helpviewer_keywords: ["processes, stopping", "processes, administrative tasks", "parent process", "processes, starting", "environment control routines", "process control routines"] --- -# Process and Environment Control +# Process and environment control Use the process-control routines to start, stop, and manage processes from within a program. Use the environment-control routines to get and change information about the operating-system environment. -## Process and Environment Control Functions +## Process and environment control functions -|Routine|Use| -|-------------|---------| -|[`abort`](../c-runtime-library/reference/abort.md)|Abort process without flushing buffers or calling functions registered by **`atexit`** and **`_onexit`**| -|[`assert`](../c-runtime-library/reference/assert-macro-assert-wassert.md)|Test for logic error| -|[`_ASSERT`, `_ASSERTE`](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) macros|Similar to **`assert`**, but only available in the debug versions of the run-time libraries| -|[`atexit`](../c-runtime-library/reference/atexit.md)|Schedule routines for execution at program termination| -|[`_beginthread`, `_beginthreadex`](../c-runtime-library/reference/beginthread-beginthreadex.md)|Create a new thread on a Windows operating system process| -|[`_cexit`](../c-runtime-library/reference/cexit-c-exit.md)|Perform **`exit`** termination procedures (such as flushing buffers), then return control to calling program without terminating process| -|[`_c_exit`](../c-runtime-library/reference/cexit-c-exit.md)|Perform **`_exit`** termination procedures, then return control to calling program without terminating process| -|[`_cwait`](../c-runtime-library/reference/cwait.md)|Wait until another process terminates| -|[`_endthread`, `_endthreadex`](../c-runtime-library/reference/endthread-endthreadex.md)|Terminate a Windows operating system thread| -|[`_execl`, `_wexecl`](../c-runtime-library/reference/execl-wexecl.md)|Execute new process with argument list| -|[`_execle`, `_wexecle`](../c-runtime-library/reference/execle-wexecle.md)|Execute new process with argument list and given environment| -|[`_execlp`, `_wexeclp`](../c-runtime-library/reference/execlp-wexeclp.md)|Execute new process using **`PATH`** variable and argument list| -|[`_execlpe`, `_wexeclpe`](../c-runtime-library/reference/execlpe-wexeclpe.md)|Execute new process using **`PATH`** variable, given environment, and argument list| -|[`_execv`, `_wexecv`](../c-runtime-library/reference/execv-wexecv.md)|Execute new process with argument array| -|[`_execve`, `_wexecve`](../c-runtime-library/reference/execve-wexecve.md)|Execute new process with argument array and given environment| -|[`_execvp`, `_wexecvp`](../c-runtime-library/reference/execvp-wexecvp.md)|Execute new process using **`PATH`** variable and argument array| -|[`_execvpe`, `_wexecvpe`](../c-runtime-library/reference/execvpe-wexecvpe.md)|Execute new process using **`PATH`** variable, given environment, and argument array| -|[`exit`](../c-runtime-library/reference/exit-exit-exit.md)|Call functions registered by **`atexit`** and **`_onexit`**, flush all buffers, close all open files, and terminate process| -|[`_exit`](../c-runtime-library/reference/exit-exit-exit.md)|Terminate process immediately without calling **`atexit`** or **`_onexit`** or flushing buffers| -|[`getenv`, `_wgetenv`](../c-runtime-library/reference/getenv-wgetenv.md), [`getenv_s`, `_wgetenv_s`](../c-runtime-library/reference/getenv-s-wgetenv-s.md)|Get value of environment variable| -|[`_getpid`](../c-runtime-library/reference/getpid.md)|Get process ID number| -|[`longjmp`](../c-runtime-library/reference/longjmp.md)|Restore saved stack environment; use it to execute a nonlocal **`goto`**| -|[`_onexit`](../c-runtime-library/reference/onexit-onexit-m.md)|Schedule routines for execution at program termination; use for compatibility with Microsoft C/C++ version 7.0 and earlier| -|[`_pclose`](../c-runtime-library/reference/pclose.md)|Wait for new command processor and close stream on associated pipe| -|[`perror`, `_wperror`](../c-runtime-library/reference/perror-wperror.md)|Print error message| -|[`_pipe`](../c-runtime-library/reference/pipe.md)|Create pipe for reading and writing| -|[`_popen`, `_wpopen`](../c-runtime-library/reference/popen-wpopen.md)|Create pipe and execute command| -|[`_putenv`, `_wputenv`](../c-runtime-library/reference/putenv-wputenv.md), [`_putenv_s`, `_wputenv_s`](../c-runtime-library/reference/putenv-s-wputenv-s.md)|Add or change value of environment variable| -|[`raise`](../c-runtime-library/reference/raise.md)|Send signal to calling process| -|[`setjmp`](../c-runtime-library/reference/setjmp.md)|Save stack environment; use to execute non local **`goto`**| -|[`signal`](../c-runtime-library/reference/signal.md)|Handle interrupt signal| -|[`_spawnl`, `_wspawnl`](../c-runtime-library/reference/spawnl-wspawnl.md)|Create and execute new process with specified argument list| -|[`_spawnle`, `_wspawnle`](../c-runtime-library/reference/spawnle-wspawnle.md)|Create and execute new process with specified argument list and environment| -|[`_spawnlp`, `_wspawnlp`](../c-runtime-library/reference/spawnlp-wspawnlp.md)|Create and execute new process using **`PATH`** variable and specified argument list| -|[`_spawnlpe`, `_wspawnlpe`](../c-runtime-library/reference/spawnlpe-wspawnlpe.md)|Create and execute new process using **`PATH`** variable, specified environment, and argument list| -|[`_spawnv`, `_wspawnv`](../c-runtime-library/reference/spawnv-wspawnv.md)|Create and execute new process with specified argument array| -|[`_spawnve`, `_wspawnve`](../c-runtime-library/reference/spawnve-wspawnve.md)|Create and execute new process with specified environment and argument array| -|[`_spawnvp`, `_wspawnvp`](../c-runtime-library/reference/spawnvp-wspawnvp.md)|Create and execute new process using **`PATH`** variable and specified argument array| -|[`_spawnvpe`, `_wspawnvpe`](../c-runtime-library/reference/spawnvpe-wspawnvpe.md)|Create and execute new process using **`PATH`** variable, specified environment, and argument array| -|[`system`, `_wsystem`](../c-runtime-library/reference/system-wsystem.md)|Execute operating-system command| +| Routine | Use | +|---|---| +| [`abort`](./reference/abort.md) | Abort process without flushing buffers or calling functions registered by **`atexit`** and **`_onexit`** | +| [`assert`](./reference/assert-macro-assert-wassert.md) | Test for logic error | +| [`_ASSERT`, `_ASSERTE`](./reference/assert-asserte-assert-expr-macros.md) macros | Similar to **`assert`**, but only available in the debug versions of the run-time libraries | +| [`atexit`](./reference/atexit.md) | Schedule routines for execution at program termination | +| [`_beginthread`, `_beginthreadex`](./reference/beginthread-beginthreadex.md) | Create a new thread on a Windows operating system process | +| [`_cexit`](./reference/cexit-c-exit.md) | Perform **`exit`** termination procedures (such as flushing buffers), then return control to calling program without terminating process | +| [`_c_exit`](./reference/cexit-c-exit.md) | Perform **`_exit`** termination procedures, then return control to calling program without terminating process | +| [`_cwait`](./reference/cwait.md) | Wait until another process terminates | +| [`_endthread`, `_endthreadex`](./reference/endthread-endthreadex.md) | Terminate a Windows operating system thread | +| [`_execl`, `_wexecl`](./reference/execl-wexecl.md) | Execute new process with argument list | +| [`_execle`, `_wexecle`](./reference/execle-wexecle.md) | Execute new process with argument list and given environment | +| [`_execlp`, `_wexeclp`](./reference/execlp-wexeclp.md) | Execute new process using `PATH` variable and argument list | +| [`_execlpe`, `_wexeclpe`](./reference/execlpe-wexeclpe.md) | Execute new process using `PATH` variable, given environment, and argument list | +| [`_execv`, `_wexecv`](./reference/execv-wexecv.md) | Execute new process with argument array | +| [`_execve`, `_wexecve`](./reference/execve-wexecve.md) | Execute new process with argument array and given environment | +| [`_execvp`, `_wexecvp`](./reference/execvp-wexecvp.md) | Execute new process using `PATH` variable and argument array | +| [`_execvpe`, `_wexecvpe`](./reference/execvpe-wexecvpe.md) | Execute new process using `PATH` variable, given environment, and argument array | +| [`exit`](./reference/exit-exit-exit.md) | Call functions registered by **`atexit`** and **`_onexit`**, flush all buffers, close all open files, and terminate process | +| [`_exit`](./reference/exit-exit-exit.md) | Terminate process immediately without calling **`atexit`** or **`_onexit`** or flushing buffers | +| [`getenv`, `_wgetenv`](./reference/getenv-wgetenv.md), [`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md) | Get value of environment variable | +| [`_getpid`](./reference/getpid.md) | Get process ID number | +| [`longjmp`](./reference/longjmp.md) | Restore saved stack environment; use it to execute a nonlocal **`goto`** | +| [`_onexit`](./reference/onexit-onexit-m.md) | Schedule routines for execution at program termination; use for compatibility with Microsoft C/C++ version 7.0 and earlier | +| [`_pclose`](./reference/pclose.md) | Wait for new command processor and close stream on associated pipe | +| [`perror`, `_wperror`](./reference/perror-wperror.md) | Print error message | +| [`_pipe`](./reference/pipe.md) | Create pipe for reading and writing | +| [`_popen`, `_wpopen`](./reference/popen-wpopen.md) | Create pipe and execute command | +| [`_putenv`, `_wputenv`](./reference/putenv-wputenv.md), [`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md) | Add or change value of environment variable | +| [`raise`](./reference/raise.md) | Send signal to calling process | +| [`setjmp`](./reference/setjmp.md) | Save stack environment; use to execute non local **`goto`** | +| [`signal`](./reference/signal.md) | Handle interrupt signal | +| [`_spawnl`, `_wspawnl`](./reference/spawnl-wspawnl.md) | Create and execute new process with specified argument list | +| [`_spawnle`, `_wspawnle`](./reference/spawnle-wspawnle.md) | Create and execute new process with specified argument list and environment | +| [`_spawnlp`, `_wspawnlp`](./reference/spawnlp-wspawnlp.md) | Create and execute new process using `PATH` variable and specified argument list | +| [`_spawnlpe`, `_wspawnlpe`](./reference/spawnlpe-wspawnlpe.md) | Create and execute new process using `PATH` variable, specified environment, and argument list | +| [`_spawnv`, `_wspawnv`](./reference/spawnv-wspawnv.md) | Create and execute new process with specified argument array | +| [`_spawnve`, `_wspawnve`](./reference/spawnve-wspawnve.md) | Create and execute new process with specified environment and argument array | +| [`_spawnvp`, `_wspawnvp`](./reference/spawnvp-wspawnvp.md) | Create and execute new process using `PATH` variable and specified argument array | +| [`_spawnvpe`, `_wspawnvpe`](./reference/spawnvpe-wspawnvpe.md) | Create and execute new process using `PATH` variable, specified environment, and argument array | +| [`system`, `_wsystem`](./reference/system-wsystem.md) | Execute operating-system command | In the Windows operating system, the spawned process is equivalent to the spawning process. Any process can use **`_cwait`** to wait for any other process for which the process ID is known. -The difference between the **`_exec`** and **`_spawn`** families is that a **`_spawn`** function can return control from the new process to the calling process. In a **`_spawn`** function, both the calling process and the new process are present in memory unless **`_P_OVERLAY`** is specified. In an **`_exec`** function, the new process overlays the calling process, so control can’t return to the calling process unless an error occurs in the attempt to start execution of the new process. +The difference between the **`_exec`** and **`_spawn`** families is that a **`_spawn`** function can return control from the new process to the calling process. In a **`_spawn`** function, both the calling process and the new process are present in memory unless `_P_OVERLAY` is specified. In an **`_exec`** function, the new process overlays the calling process, so control can't return to the calling process unless an error occurs in the attempt to start execution of the new process. -The differences among the functions in the **`_exec`** family, as well as among those in the **`_spawn`** family, involve the method of locating the file to be executed as the new process, the form in which arguments are passed to the new process, and the method of setting the environment, as shown in the following table. Use a function that passes an argument list when the number of arguments is constant or is known at compile time. Use a function that passes a pointer to an array containing the arguments when the number of arguments is to be determined at run time. The information in the following table also applies to the wide-character counterparts of the **`_spawn`** and **`_exec`** functions. +The differences among the functions in the **`_exec`** and **`_spawn`** families involve the method of locating the file to be executed as the new process, the form in which arguments are passed to the new process, and the method of setting the environment, as shown in the following table. Use a function that passes an argument list when the number of arguments is constant or is known at compile time. Use a function that passes a pointer to an array containing the arguments when the number of arguments is to be determined at run time. The information in the following table also applies to the wide-character counterparts of the **`_spawn`** and **`_exec`** functions. ### `_spawn` and `_exec` Function Families -|Functions|Use `PATH` variable to locate file|Argument-passing convention|Environment settings| -|---------------|--------------------------------------|----------------------------------|--------------------------| -|**`_execl`**, **`_spawnl`**|No|List|Inherited from calling process| -|**`_execle`**, **`_spawnle`**|No|List|Pointer to environment table for new process passed as last argument| -|**`_execlp`**, **`_spawnlp`**|Yes|List|Inherited from calling process| -|**`_execvpe`**, **`_spawnvpe`**|Yes|Array|Pointer to environment table for new process passed as last argument| -|**`_execlpe`**, **`_spawnlpe`**|Yes|List|Pointer to environment table for new process passed as last argument| -|**`_execv`**, **`_spawnv`**|No|Array|Inherited from calling process| -|**`_execve`**, **`_spawnve`**|No|Array|Pointer to environment table for new process passed as last argument| -|**`_execvp`**, **`_spawnvp`**|Yes|Array|Inherited from calling process| +| Functions | Use `PATH` variable to locate file | Argument-passing convention | Environment settings | +|---|---|---|---| +| **`_execl`**, **`_spawnl`** | No | List | Inherited from calling process | +| **`_execle`**, **`_spawnle`** | No | List | Pointer to environment table for new process passed as last argument | +| **`_execlp`**, **`_spawnlp`** | Yes | List | Inherited from calling process | +| **`_execvpe`**, **`_spawnvpe`** | Yes | Array | Pointer to environment table for new process passed as last argument | +| **`_execlpe`**, **`_spawnlpe`** | Yes | List | Pointer to environment table for new process passed as last argument | +| **`_execv`**, **`_spawnv`** | No | Array | Inherited from calling process | +| **`_execve`**, **`_spawnve`** | No | Array | Pointer to environment table for new process passed as last argument | +| **`_execvp`**, **`_spawnvp`** | Yes | Array | Inherited from calling process | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md) +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/rand-max.md b/docs/c-runtime-library/rand-max.md index 1fc11b09b9c..532c58038c1 100644 --- a/docs/c-runtime-library/rand-max.md +++ b/docs/c-runtime-library/rand-max.md @@ -2,14 +2,14 @@ description: "Learn more about: RAND_MAX" title: "RAND_MAX" ms.date: "11/04/2016" -f1_keywords: ["RAND_MAX"] +f1_keywords: ["STDLIB/RAND_MAX", "RAND_MAX"] helpviewer_keywords: ["RAND_MAX constant"] --- # `RAND_MAX` ## Syntax -``` +```C #include ``` @@ -19,5 +19,5 @@ The constant `RAND_MAX` is the maximum value that can be returned by the `rand` ## See also -[`rand`](../c-runtime-library/reference/rand.md)\ -[Global Constants](../c-runtime-library/global-constants.md) +[`rand`](./reference/rand.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md b/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md index 7017d4a920d..57ed7d86d04 100644 --- a/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md +++ b/docs/c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md @@ -2,12 +2,12 @@ title: "Recommendations for Choosing Between Functions and Macros" description: "Explains the differences between using macros vs functions in the Microsoft C runtime library (CRT)" ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: ["c.functions"] helpviewer_keywords: ["functions [CRT], vs. macros", "macros, vs. functions"] ms.assetid: 18a633d6-cf1c-470c-a649-fa7677473e2b --- -# Recommendations for Choosing Between Functions and Macros +# Recommendations for choosing between functions and macros Most Microsoft run-time library routines are compiled or assembled functions, but some routines are implemented as macros. When a header file declares both a function and a macro version of a routine, the macro definition takes precedence, because it always appears after the function declaration. When you invoke a routine that is implemented as both a function and a macro, you can force the compiler to use the function version in two ways: @@ -29,13 +29,13 @@ Most Microsoft run-time library routines are compiled or assembled functions, bu If you need to choose between a function and a macro implementation of a library routine, consider the following trade-offs: -- **Speed versus size** The main benefit of using macros is faster execution time. During preprocessing, a macro is expanded (replaced by its definition) inline each time it is used. A function definition occurs only once regardless of how many times it is called. Macros may increase code size but do not have the overhead associated with function calls. +- **Speed versus size** The main benefit of using macros is faster execution time. During preprocessing, a macro is expanded (replaced by its definition) inline each time it's used. A function definition occurs only once regardless of how many times it's called. Macros may increase code size but don't have the overhead associated with function calls. -- **Function evaluation** A function evaluates to an address; a macro does not. Thus you cannot use a macro name in contexts requiring a pointer. For instance, you can declare a pointer to a function, but not a pointer to a macro. +- **Function evaluation** A function evaluates to an address; a macro doesn't. Thus you can't use a macro name in contexts requiring a pointer. For instance, you can declare a pointer to a function, but not a pointer to a macro. -- **Type-checking** When you declare a function, the compiler can check the argument types. Because you cannot declare a macro, the compiler cannot check macro argument types; although it can check the number of arguments you pass to a macro. +- **Type-checking** When you declare a function, the compiler can check the argument types. Because you can't declare a macro, the compiler can't check macro argument types; although it can check the number of arguments you pass to a macro. ## See also [Type-generic math](tgmath.md)\ -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/reference/abort.md b/docs/c-runtime-library/reference/abort.md index 40c84322f5b..70885616878 100644 --- a/docs/c-runtime-library/reference/abort.md +++ b/docs/c-runtime-library/reference/abort.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: abort" title: "abort" -ms.date: "4/2/2020" +description: "Learn more about: abort" +ms.date: 07/07/2022 api_name: ["abort", "_o_abort"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["Abort"] +f1_keywords: ["STDLIB/abort", "abort"] helpviewer_keywords: ["aborting current process", "abort function", "processes, aborting"] --- # `abort` @@ -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 @@ -22,15 +22,15 @@ Aborts the current process and returns an error code. void abort( void ); ``` -## Return Value +## Return value -**`abort`** does not return control to the calling process. By default, it checks for an abort signal handler and raises `SIGABRT` if one is set. Then **`abort`** terminates the current process and returns an exit code to the parent process. +**`abort`** doesn't return control to the calling process. By default, it checks for an abort signal handler and raises `SIGABRT` if one is set. Then **`abort`** terminates the current process and returns an exit code to the parent process. ## Remarks **Microsoft Specific** -By default, when an app is built with the debug runtime library, the **`abort`** routine displays an error message before `SIGABRT` is raised. For console apps running in console mode, the message is sent to `STDERR`. Windows desktop apps and console apps running in windowed mode display the message in a message box. To suppress the message, use [`_set_abort_behavior`](set-abort-behavior.md) to clear the `_WRITE_ABORT_MSG` flag. The message displayed depends on the version of the runtime environment used. For applications built by using the most recent versions of Visual C++, the message resembles this: +By default, when an app is built with the debug runtime library, the **`abort`** routine displays an error message before `SIGABRT` is raised. For console apps running in console mode, the message is sent to `STDERR`. Windows desktop apps and console apps running in windowed mode display the message in a message box. To suppress the message, use [`_set_abort_behavior`](set-abort-behavior.md) to clear the `_WRITE_ABORT_MSG` flag. The message displayed depends on the version of the runtime environment used. For applications built by using the most recent versions of Visual C++, the message resembles this one: > R6010 - abort() has been called @@ -38,25 +38,27 @@ In previous versions of the C runtime library, this message was displayed: > This application has requested the Runtime to terminate it in an unusual way. Please contact the application's support team for more information. -When the program is compiled in debug mode, the message box displays options to **Abort**, **Retry**, or **Ignore**. If the user chooses **Abort**, the program terminates immediately and returns an exit code of 3. If the user chooses **Retry**, a debugger is invoked for just-in-time debugging, if available. If the user chooses **Ignore**, **abort** continues normal processing. +When the program is compiled in debug mode, the message box displays options to **Abort**, **Retry**, or **Ignore**. If the user chooses **Abort**, the program terminates immediately and returns an exit code of 3. If the user chooses **Retry**, a debugger is invoked for just-in-time debugging, if available. If the user chooses **Ignore**, **`abort`** continues normal processing. -In both retail and debug builds, **`abort`** then checks whether an abort signal handler is set. If a non-default signal handler is set, **`abort`** calls `raise(SIGABRT)`. Use the [`signal`](signal.md) function to associate an abort signal handler function with the `SIGABRT` signal. You can perform custom actions—for example, clean up resources or log information—and terminate the app with your own error code in the handler function. If no custom signal handler is defined, **`abort`** does not raise the `SIGABRT` signal. +In both retail and debug builds, **`abort`** then checks whether an abort signal handler is set. If a non-default signal handler is set, **`abort`** calls `raise(SIGABRT)`. Use the [`signal`](signal.md) function to associate an abort signal handler function with the `SIGABRT` signal. You can perform custom actions—for example, clean up resources or log information—and terminate the app with your own error code in the handler function. If no custom signal handler is defined, **`abort`** doesn't raise the `SIGABRT` signal. By default, in non-debug builds of desktop or console apps, **`abort`** then invokes the Windows Error Reporting Service mechanism (formerly known as Dr. Watson) to report failures to Microsoft. This behavior can be enabled or disabled by calling `_set_abort_behavior` and setting or masking the `_CALL_REPORTFAULT` flag. When the flag is set, Windows displays a message box that has text something like "A problem caused the program to stop working correctly." The user can choose to invoke a debugger with a **Debug** button, or choose the **Close program** button to terminate the app with an error code that's defined by the operating system. -If the Windows error reporting handler is not invoked, then **`abort`** calls [`_exit`](exit-exit-exit.md) to terminate the process with exit code 3 and returns control to the parent process or the operating system. `_exit` does not flush stream buffers or do `atexit`/`_onexit` processing. +If the Windows error reporting handler isn't invoked, then **`abort`** calls [`_exit`](exit-exit-exit.md) to terminate the process with exit code 3 and returns control to the parent process or the operating system. `_exit` doesn't flush stream buffers or do `atexit`/`_onexit` processing. + +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-conforming behavior. Conforming behavior may come at some cost in Windows compatibility. -For more information about CRT debugging, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +For more information about CRT debugging, see [CRT debugging techniques](../crt-debugging-techniques.md). **End Microsoft Specific** -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`abort`**|`` or ``| +| Routine | Required header | +|---|---| +| **`abort`** | `` or `` | ## Example @@ -69,8 +71,8 @@ The following program tries to open a file and aborts if the attempt fails. // the abort function by attempting to open a file // and aborts if the attempt fails. -#include -#include +#include +#include int main( void ) { @@ -97,12 +99,12 @@ File could not be opened: No such file or directory ## See also [Using `abort`](../../cpp/using-abort.md)\ -[`abort` Function](../../c-language/abort-function-c.md)\ -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ -[`_exec`, `_wexec` Functions](../../c-runtime-library/exec-wexec-functions.md)\ +[`abort` function](../../c-language/abort-function-c.md)\ +[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ [`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ [`raise`](raise.md)\ [`signal`](signal.md)\ -[`_spawn`, `_wspawn` Functions](../../c-runtime-library/spawn-wspawn-functions.md)\ -[`_DEBUG`](../../c-runtime-library/debug.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`_DEBUG`](../debug.md)\ [`_set_abort_behavior`](set-abort-behavior.md) diff --git a/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md b/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md index f304d5983ae..19dbdf4c9d9 100644 --- a/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md +++ b/docs/c-runtime-library/reference/abs-labs-llabs-abs64.md @@ -6,7 +6,7 @@ api_name: ["abs", "_abs64", "labs", "llabs"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["stdlib/_abs64", "math/abs", "_abs64", "abs", "labs", "math/labs", "llabs", "math/llabs", "cmath/abs"] +f1_keywords: ["_abs64", "STDLIB/_abs64", "abs", "CORECRT_MATH/abs", "STDLIB/abs", "CSTDLIB/abs", "labs", "CORECRT_MATH/labs", "llabs", "CORECRT_MATH/llabs"] helpviewer_keywords: ["absolute values", "abs function", "abs64 function", "_abs64 function", "calculating absolute values"] --- # `abs`, `labs`, `llabs`, `_abs64` @@ -35,7 +35,7 @@ float abs( float n ); // C++ only *`n`*\ Numeric value. -## Return Value +## Return value The **`abs`**, **`labs`**, **`llabs`**, and **`_abs64`** functions return the absolute value of the parameter *`n`*. There's no error return. @@ -43,14 +43,14 @@ The **`abs`**, **`labs`**, **`llabs`**, and **`_abs64`** functions return the ab Because C++ allows overloading, you can call overloads of **`abs`** that take and return **`long`**, **`long long`**, **`float`**, **`double`**, and **`long double`** values. These overloads are defined in the `` header. In a C program, **`abs`** always takes and returns an **`int`**. -**Microsoft-specific**: Because the range of negative integers that can be represented by using any integral type is larger than the range of positive integers that can be represented by using that type, it's possible to supply an argument to these functions that can't be converted. If the absolute value of the argument can’t be represented by the return type, the **`abs`** functions return the argument value unchanged. Specifically, `abs(INT_MIN)` returns `INT_MIN`, `labs(LONG_MIN)` returns `LONG_MIN`, `llabs(LLONG_MIN)` returns `LLONG_MIN`, and `_abs64(_I64_MIN)` returns `_I64_MIN`. This means that the **`abs`** functions can’t be used to guarantee a positive value. +**Microsoft-specific**: The range of negative integers representable in any integral type is larger than the range of positive integers representable in that type. So, it's possible to supply an argument to these functions that can't be converted. If the absolute value of the argument can't be represented by the return type, the **`abs`** functions return the argument value unchanged. Specifically, `abs(INT_MIN)` returns `INT_MIN`, `labs(LONG_MIN)` returns `LONG_MIN`, `llabs(LLONG_MIN)` returns `LLONG_MIN`, and `_abs64(_I64_MIN)` returns `_I64_MIN`. Effectively, the **`abs`** functions can't be used to guarantee a positive value. ## Requirements -|Routine|Required C header|Required C++ header| -|-------------|-----------------------|---------------------------| -|**`abs`**, **`labs`**, **`llabs`**|`` or ``|``, ``, `` or ``| -|**`_abs64`**|``|`` or ``| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`abs`**, **`labs`**, **`llabs`** | `` or `` | ``, ``, `` or `` | +| **`_abs64`** | `` | `` or `` | To use the overloaded versions of **`abs`** in C++, you must include the `` header. @@ -113,8 +113,8 @@ _abs64(_I64_MIN) returns 0x8000000000000000 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)\ -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`_cabs`](cabs.md)\ [`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md)\ [`imaxabs`](imaxabs.md) diff --git a/docs/c-runtime-library/reference/access-crt.md b/docs/c-runtime-library/reference/access-crt.md index 98e59aab621..7a6d411ca89 100644 --- a/docs/c-runtime-library/reference/access-crt.md +++ b/docs/c-runtime-library/reference/access-crt.md @@ -6,12 +6,12 @@ api_name: ["access"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["access"] +f1_keywords: ["access", "CORECRT_IO/access"] helpviewer_keywords: ["access function"] ms.assetid: 65197793-bd0a-41c3-9c29-18de2d95d9a6 --- -# access (CRT) +# `access` (CRT) -The Microsoft-implemented POSIX function name `access` is a deprecated alias for the [_access](access-waccess.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `access` is a deprecated alias for the [`_access`](access-waccess.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_access](access-waccess.md) or the security-enhanced [_access_s](access-s-waccess-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_access`](access-waccess.md) or the security-enhanced [`_access_s`](access-s-waccess-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/access-s-waccess-s.md b/docs/c-runtime-library/reference/access-s-waccess-s.md index 8b92d4b4e72..c054b3b97dc 100644 --- a/docs/c-runtime-library/reference/access-s-waccess-s.md +++ b/docs/c-runtime-library/reference/access-s-waccess-s.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: _access_s, _waccess_s" -title: "_access_s, _waccess_s" +description: "Learn more about: _access_s, _waccess_s, _taccess_s" +title: "_access_s, _waccess_s, _taccess_s" ms.date: "4/2/2020" -api_name: ["_access_s", "_waccess_s", "_o__access_s", "_o__waccess_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_access_s", "_waccess_s", "_taccess_s", "_o__access_s", "_o__waccess_s"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["waccess_s", "access_s", "_waccess_s", "_access_s"] -helpviewer_keywords: ["access_s function", "taccess_s function", "_taccess_s function", "waccess_s function", "_access_s function", "_waccess_s function"] -ms.assetid: fb3004fc-dcd3-4569-8b27-d817546e947e +f1_keywords: ["waccess_s", "access_s", "_taccess_s"] +helpviewer_keywords: ["access_s function", "waccess_s function", "_taccess_s function"] --- -# _access_s, _waccess_s +# `_access_s`, `_waccess_s`, `_taccess_s` -Determines file read/write permissions. This is a version of [_access, _waccess](access-waccess.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Determines file read/write permissions. These functions are versions of [`_access`, `_waccess`](access-waccess.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). + +For `_taccess_s`, see [Generic-text function mappings](#generic-text-function-mappings). ## Syntax @@ -29,59 +30,61 @@ errno_t _waccess_s( ### Parameters -*path*
+*`path`*\ File or directory path. -*mode*
+*`mode`*\ Permission setting. -## Return Value +## Return value -Each function returns 0 if the file has the given mode. The function returns an error code if the named file does not exist or is not accessible in the given mode. In this case, the function returns an error code from the set as follows and also sets `errno` to the same value. +Each function returns 0 if the file has the given mode. The function returns an error code if the named file doesn't exist or isn't accessible in the given mode. In this case, the function returns an error code from the set as follows and also sets `errno` to the same value. -|errno value|Condition| -|-|-| -`EACCES`|Access denied. The file's permission setting does not allow specified access. -`ENOENT`|File name or path not found. -`EINVAL`|Invalid parameter. +| `errno` value | Condition | +|---|---| +| `EACCES` | Access denied. The file's permission setting doesn't allow specified access. | +| `ENOENT` | File name or path not found. | +| `EINVAL` | Invalid parameter. | -For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -When used with files, the **_access_s** function determines whether the specified file exists and can be accessed as specified by the value of *mode*. When used with directories, **_access_s** determines only whether the specified directory exists. In Windows 2000 and later operating systems, all directories have read and write access. +When used with files, the **`_access_s`** function determines whether the specified file exists and can be accessed as specified by the value of *`mode`*. When used with directories, **`_access_s`** determines only whether the specified directory exists. In Windows 2000 and later operating systems, all directories have read and write access. + +| *`mode`* value | Checks file for | +|---|---| +| 00 | Existence only. | +| 02 | Write permission. | +| 04 | Read permission. | +| 06 | Read and write permission. | -|mode value|Checks file for| -|----------------|---------------------| -|00|Existence only.| -|02|Write permission.| -|04|Read permission.| -|06|Read and write permission.| +Permission to read or write the file isn't enough to ensure the ability to open a file. For example, if a file is locked by another process, it might not be accessible even though **`_access_s`** returns 0. -Permission to read or write the file is not enough to ensure the ability to open a file. For example, if a file is locked by another process, it might not be accessible even though **_access_s** returns 0. +**`_waccess_s`** is a wide-character version of **`_access_s`**, where the *`path`* argument to **`_waccess_s`** is a wide-character string. Otherwise, **`_waccess_s`** and **`_access_s`** behave identically. -**_waccess_s** is a wide-character version of **_access_s**, where the *path* argument to **_waccess_s** is a wide-character string. Otherwise, **_waccess_s** and **_access_s** behave identically. +These functions validate their parameters. If *`path`* is `NULL` or *`mode`* doesn't specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. -These functions validate their parameters. If *path* is NULL or *mode* does not specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_taccess_s`|**_access_s**|**_access_s**|**_waccess_s**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_taccess_s` | `_access_s` | `_access_s` | `_waccess_s` | ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_access_s**|\|\| -|**_waccess_s**|\ or \|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_access_s`** | `` | `` | +| **`_waccess_s`** | `` or `` | `` | ## Example -This example uses **_access_s** to check the file named crt_access_s.c to see whether it exists and whether writing is allowed. +This example uses **`_access_s`** to check the file named crt_access_s.c to see whether it exists and whether writing is allowed. ```C // crt_access_s.c @@ -125,9 +128,9 @@ File crt_access_s.c does not have write permission. ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_access, _waccess](access-waccess.md)
-[_chmod, _wchmod](chmod-wchmod.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[_open, _wopen](open-wopen.md)
-[_stat, _wstat Functions](stat-functions.md) +[File handling](../file-handling.md)\ +[`_access`, `_waccess`](access-waccess.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/access-waccess.md b/docs/c-runtime-library/reference/access-waccess.md index 7597f5528f2..87cf212ca0b 100644 --- a/docs/c-runtime-library/reference/access-waccess.md +++ b/docs/c-runtime-library/reference/access-waccess.md @@ -1,19 +1,20 @@ --- -description: "Learn more about: _access, _waccess" title: "_access, _waccess" +description: "Learn more about: _access, _waccess" ms.date: "4/2/2020" -api_name: ["_access", "_waccess", "_o__access", "_o__waccess"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_access", "_waccess", "t_access", "_o__access", "_o__waccess"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_waccess", "_access", "taccess", "waccess", "_taccess"] helpviewer_keywords: ["access function", "_taccess function", "waccess function", "_access function", "_waccess function", "taccess function"] -ms.assetid: ba34f745-85c3-49e5-a7d4-3590bd249dd3 --- -# `_access`, `_waccess` +# `_access`, `_waccess`, `t_access` Determines if a file is read-only or not. More secure versions are available; see [`_access_s`, `_waccess_s`](access-s-waccess-s.md). +For `_taccess`, see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -29,55 +30,55 @@ int _waccess( ### Parameters -*`path`*
+*`path`*\ File or directory path. -*`mode`*
+*`mode`*\ Read/write attribute. -## Return Value +## Return value -Each function returns 0 if the file has the given mode. The function returns -1 if the named file does not exist or does not have the given mode; in this case, `errno` is set as shown in the following table. +Each function returns 0 if the file has the given mode. The function returns -1 if the named file doesn't exist or doesn't have the given mode; in this case, `errno` is set as shown in the following table. | Value | Description | -|--|--| -| `EACCES` | Access denied: the file's permission setting does not allow specified access. | +|---|---| +| `EACCES` | Access denied: the file's permission setting doesn't allow specified access. | | `ENOENT` | File name or path not found. | | `EINVAL` | Invalid parameter. | -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks When used with files, the **`_access`** function determines whether the specified file or directory exists and has the attributes specified by the value of *`mode`*. When used with directories, **`_access`** determines only whether the specified directory exists; in Windows 2000 and later operating systems, all directories have read and write access. -|*`mode`* value|Checks file for| -|------------------|---------------------| -|00|Existence only| -|02|Write-only| -|04|Read-only| -|06|Read and write| +| *`mode`* value | Checks file for | +|---|---| +| 00 | Existence only | +| 02 | Write-only | +| 04 | Read-only | +| 06 | Read and write | -This function only checks whether the file and directory are read-only or not, it does not check the filesystem security settings. For that you need an access token. For more information on filesystem security, see [Access Tokens](/windows/win32/SecAuthZ/access-tokens). An ATL class exists to provide this functionality; see [`CAccessToken` Class](../../atl/reference/caccesstoken-class.md). +This function only checks whether the file and directory are read-only or not, it doesn't check the filesystem security settings. For that you need an access token. For more information on filesystem security, see [Access tokens](/windows/win32/SecAuthZ/access-tokens). An ATL class exists to provide this functionality; see [`CAccessToken` Class](../../atl/reference/caccesstoken-class.md). **`_waccess`** is a wide-character version of **`_access`**; the *`path`* argument to **`_waccess`** is a wide-character string. **`_waccess`** and **`_access`** behave identically otherwise. -This function validates its parameters. If *`path`* is `NULL` or *`mode`* does not specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns -1. +This function validates its parameters. If *`path`* is `NULL` or *`mode`* doesn't specify a valid mode, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text function mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_taccess`|**`_access`**|**`_access`**|**`_waccess`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_taccess` | **`_access`** | **`_access`** | **`_waccess`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`_access`**|``|``| -|**`_waccess`**|`` or ``|``| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_access`** | `` | `` | +| **`_waccess`** | `` or `` | `` | ## Example @@ -89,9 +90,9 @@ The following example uses **`_access`** to check the file named *`crt_ACCESS.C` // This example uses _access to check the file named // crt_ACCESS.C to see if it exists and if writing is allowed. -#include -#include -#include +#include +#include +#include int main( void ) { @@ -115,8 +116,8 @@ File crt_ACCESS.C does not have write permission. ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[`_chmod`, `_wchmod`](chmod-wchmod.md)
-[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[`_open`, `_wopen`](open-wopen.md)
-[`_stat`, `_wstat` Functions](stat-functions.md) +[File handling](../file-handling.md)\ +[`_chmod`, `_wchmod`](chmod-wchmod.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/acos-acosf-acosl.md b/docs/c-runtime-library/reference/acos-acosf-acosl.md index e8b1ce13c2a..b570c16c00b 100644 --- a/docs/c-runtime-library/reference/acos-acosf-acosl.md +++ b/docs/c-runtime-library/reference/acos-acosf-acosl.md @@ -1,12 +1,12 @@ --- title: "acos, acosf, acosl" description: "API reference for acos, acosf, and acosl; which calculate the arccosine of a floating-point value." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["acosf", "acos", "acosl", "_o_acos", "_o_acosf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["acos", "acosl", "acosf", "math/acosf", "math/acosl"] +f1_keywords: ["acos", "CMATH/acos", "CORECRT_MATH/acos", "acosl", "CORECRT_MATH/acosl", "acosf", "CORECRT_MATH/acosf"] helpviewer_keywords: ["acos function", "acosl function", "acosf function", "trigonometric functions", "arccosine function"] --- # `acos`, `acosf`, `acosl` @@ -19,7 +19,7 @@ Calculates the arccosine. double acos( double x ); float acosf( float x ); long double acosl( long double x ); -#define acos(X) // Requires C11 or higher +#define acos(X) // Requires C11 or later float acos( float x ); // C++ only long double acos( long double x ); // C++ only @@ -30,32 +30,32 @@ long double acos( long double x ); // C++ only *`x`*\ Value between -1 and 1, for which to calculate the arccosine (the inverse cosine). -## Return Value +## Return value -The **`acos`** function returns the arccosine of *x* in the range 0 to π radians. +The **`acos`** function returns the arccosine of *`x`* in the range 0 to π radians. By default, if *`x`* is less than -1 or greater than 1, **`acos`** returns an indefinite. -|Input|`SEH` exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|`± ∞`|`INVALID`|`_DOMAIN`| -|`± QNAN, IND`|none|`_DOMAIN`| -|`|x| > 1`|`INVALID`|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF | `INVALID` | `_DOMAIN` | +| ± QNaN, IND | none | `_DOMAIN` | +| `|x| > 1` | `INVALID` | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`acos`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the `` macro to call this function, **`acos`** always takes and returns a **`double`**. -If you use the `` `acos()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `acos` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`acos`**, **`acosf`**, **`acosl`**|``|``| -|**`acos()`** macro | `` || +| Routine | Required header | Optional headers | +|---|---|---| +| **`acos`**, **`acosf`**, **`acosl`** | `` | `` | +| **`acos`** macro | `` | | ## Example @@ -109,7 +109,7 @@ Arccosine of 0.000000 = 1.570796 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ diff --git a/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md b/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md index a0d9af21183..18d9c23aa14 100644 --- a/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md +++ b/docs/c-runtime-library/reference/acosh-acoshf-acoshl.md @@ -1,16 +1,15 @@ --- title: "acosh, acoshf, acoshl" description: "API reference for acosh, acoshf, and acoshl; which calculate the inverse hyperbolic cosine of a floating-point value." -ms.date: "08/31/2020" +ms.date: 08/31/2020 api_name: ["acoshf", "acosh", "acoshl", "_o_acosh", "_o_acoshf", "_o_acoshl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["acosh", "acoshf", "acoshl", "math/acosh", "math/acoshf", "math/acoshl"] helpviewer_keywords: ["acoshf function", "acosh function", "acoshl function"] -ms.assetid: 6985c4d7-9e2a-44ce-9a9b-5a43015f15f7 --- -# acosh, acoshf, acoshl +# `acosh`, `acoshf`, `acoshl` Calculates the inverse hyperbolic cosine. @@ -20,7 +19,7 @@ Calculates the inverse hyperbolic cosine. double acosh( double x ); float acoshf( float x ); long double acoshl( long double x ); -#define acosh(X) // Requires C11 or higher +#define acosh(X) // Requires C11 or later float acosh( float x ); // C++ only long double acosh( long double x ); // C++ only @@ -28,34 +27,34 @@ long double acosh( long double x ); // C++ only ### Parameters -*x*\ +*`x`*\ Floating-point value. -## Return Value +## Return value -The **acosh** functions return the inverse hyberbolic cosine (arc hyperbolic cosine) of *x*. These functions are valid over the domain *x* ≥ 1. If *x* is less than 1, `errno` is set to `EDOM` and the result is a quiet NaN. If *x* is a quiet NaN, indefinite, or infinity, the same value is returned. +The **`acosh`** functions return the inverse hyperbolic cosine (arc hyperbolic cosine) of *`x`*. These functions are valid over the domain *`x`* ≥ 1. If *`x`* is less than 1, `errno` is set to `EDOM`, and the result is a quiet NaN. If *`x`* is a quiet NaN, indefinite, or infinity, the same value is returned. -|Input|SEH Exception|`_matherr` Exception| -|-----------|-------------------|--------------------------| -|± QNAN, IND, INF|none|none| -|*x* < 1|none|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND, INF | none | none | +| *`x`* < 1 | none | none | ## Remarks -When you use C++, you can call overloads of **acosh** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **acosh** always takes and returns **`double`**. +When you use C++, you can call overloads of **`acosh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`acosh`** always takes and returns **`double`**. -If you use the \ `acosh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `acosh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**acosh**, **acoshf**, **acoshl**|\|\| -|**acosh()** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`acosh`**, **`acoshf`**, **`acoshl`** | \ | \ | +| **`acosh`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,9 +86,9 @@ acosh( 1.324609 ) = 0.785398 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[asinh, asinhf, asinhl](asinh-asinhf-asinhl.md)
-[atanh, atanhf, atanhl](atanh-atanhf-atanhl.md)
-[cosh, coshf, coshl](cosh-coshf-coshl.md)
-[sinh, sinhf, sinhl](sinh-sinhf-sinhl.md)
-[tanh, tanhf, tanhl](tanh-tanhf-tanhl.md) +[Math and floating-point support](../floating-point-support.md)\ +[`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ +[`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ +[`cosh`, `coshf`, `coshl`](cosh-coshf-coshl.md)\ +[`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md)\ +[`tanh`, `tanhf`, `tanhl`](tanh-tanhf-tanhl.md) diff --git a/docs/c-runtime-library/reference/aligned-free-dbg.md b/docs/c-runtime-library/reference/aligned-free-dbg.md index 5a724e6b3df..1ef9d5fe974 100644 --- a/docs/c-runtime-library/reference/aligned-free-dbg.md +++ b/docs/c-runtime-library/reference/aligned-free-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_aligned_free_dbg", "aligned_free_dbg"] helpviewer_keywords: ["_aligned_free_dbg function", "aligned_free_dbg function"] ms.assetid: eb0cb3c8-0992-4db8-bac3-65f1b8311ca6 --- -# _aligned_free_dbg +# `_aligned_free_dbg` -Frees a block of memory that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) (debug only). +Frees a block of memory that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) (debug only). ## Syntax @@ -24,27 +24,27 @@ void _aligned_free_dbg( ### Parameters -*memblock*
-A pointer to the memory block that was returned to the [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) function. +*`memblock`*\ +A pointer to the memory block that was returned to the [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) function. ## Remarks -The **_aligned_free_dbg** function is a debug version of the [_aligned_free](aligned-free.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_free_dbg** is reduced to a call to `_aligned_free`. Both `_aligned_free` and **_aligned_free_dbg** free a memory block in the base heap, but **_aligned_free_dbg** accommodates a debugging feature: the ability to keep freed blocks in the heap's linked list to simulate low memory conditions. +The **`_aligned_free_dbg`** function is a debug version of the [`_aligned_free`](aligned-free.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_free_dbg`** is reduced to a call to `_aligned_free`. Both `_aligned_free` and **`_aligned_free_dbg`** free a memory block in the base heap, but **`_aligned_free_dbg`** accommodates a debugging feature: the ability to keep freed blocks in the heap's linked list to simulate low memory conditions. -**_aligned_free_dbg** performs a validity check on all specified files and block locations before performing the free operation. The application is not expected to provide this information. When a memory block is freed, the debug heap manager automatically checks the integrity of the buffers on either side of the user portion and issues an error report if overwriting has occurred. If the _CRTDBG_DELAY_FREE_MEM_DF bit field of the [_crtDbgFlag](../../c-runtime-library/crtdbgflag.md) flag is set, the freed block is filled with the value 0xDD, assigned the _FREE_BLOCK block type, and kept in the heap's linked list of memory blocks. +**`_aligned_free_dbg`** performs a validity check on all specified files and block locations before performing the free operation. The application isn't expected to provide this information. When a memory block is freed, the debug heap manager automatically checks the integrity of the buffers on either side of the user portion. It issues an error report if overwriting has occurred. If the `_CRTDBG_DELAY_FREE_MEM_DF` bit field of the [`_crtDbgFlag`](../crtdbgflag.md) flag is set, the freed block is filled with the value 0xDD, assigned the `_FREE_BLOCK` block type, and kept in the heap's linked list of memory blocks. -If an error occurs in freeing the memory, `errno` is set with information from the operating system on the nature of the failure. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If an error occurs in freeing the memory, `errno` is set with information from the operating system on the nature of the failure. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_free_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_free_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md) +[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-free.md b/docs/c-runtime-library/reference/aligned-free.md index 264b0485be7..e369c867953 100644 --- a/docs/c-runtime-library/reference/aligned-free.md +++ b/docs/c-runtime-library/reference/aligned-free.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_free" title: "_aligned_free" ms.date: "4/2/2020" api_name: ["_aligned_free", "_o__aligned_free"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_free", "_aligned_free"] helpviewer_keywords: ["_aligned_free function", "aligned_free function"] ms.assetid: ed1ce952-cdfc-4682-85cc-f75d4101603d --- -# _aligned_free +# `_aligned_free` -Frees a block of memory that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md). +Frees a block of memory that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md). ## Syntax @@ -24,27 +24,27 @@ void _aligned_free ( ### Parameters -*memblock*
+*`memblock`*\ A pointer to the memory block that was returned to the `_aligned_malloc` or `_aligned_offset_malloc` function. ## Remarks -**_aligned_free** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [noalias](../../cpp/noalias.md). +**`_aligned_free`** is marked `__declspec(noalias)`, meaning that the function is guaranteed not to modify global variables. For more information, see [`noalias`](../../cpp/noalias.md). -This function does not validate its parameter, unlike the other _aligned CRT functions. If *memblock* is a NULL pointer, this function simply performs no actions. It does not change `errno` and it does not invoke the invalid parameter handler. If an error occurs in the function due to not using _aligned functions previously to allocate the block of memory or a misalignment of memory occurs due to some unforeseen calamity, the function generates a debug report from the [_RPT, _RPTF, _RPTW, _RPTFW Macros](rpt-rptf-rptw-rptfw-macros.md). +This function doesn't validate its parameter, unlike the other _aligned CRT functions. If *`memblock`* is a `NULL` pointer, this function simply performs no actions. It doesn't change `errno` and it doesn't invoke the invalid parameter handler. If an error occurs in the function because `_aligned` functions weren't used to allocate the block of memory, or a misalignment of memory occurs due to some unforeseen calamity, the function generates a debug report from the [`_RPT`, `_RPTF`, `_RPTW`, `_RPTFW` macros](rpt-rptf-rptw-rptfw-macros.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_free**|\| +| Routine | Required header | +|---|---| +| **`_aligned_free`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md) +[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-malloc-dbg.md b/docs/c-runtime-library/reference/aligned-malloc-dbg.md index 7dfd0eb9798..c9a59fa4381 100644 --- a/docs/c-runtime-library/reference/aligned-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-malloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_aligned_malloc_dbg", "aligned_malloc_dbg"] helpviewer_keywords: ["aligned_malloc_dbg function", "_aligned_malloc_dbg function"] ms.assetid: fb0429c3-685d-4826-9075-2515c5bdc5c6 --- -# _aligned_malloc_dbg +# `_aligned_malloc_dbg` -Allocates memory on a specified alignment boundary with additional space for a debugging header and overwrite buffers (debug version only). +Allocates memory on a specified alignment boundary with extra space for a debugging header and overwrite buffers (debug version only). ## Syntax @@ -27,44 +27,44 @@ void * _aligned_malloc_dbg( ### Parameters -*size*
+*`size`*\ Size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*filename*
-Pointer to the name of the source file that requested the allocation operation or NULL. +*`filename`*\ +Pointer to the name of the source file that requested the allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or NULL. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -## Return Value +## Return value -A pointer to the memory block that was allocated or NULL if the operation failed. +A pointer to the memory block that was allocated or `NULL` if the operation failed. ## Remarks -**_aligned_malloc_dbg** is a debug version of the [_aligned_malloc](aligned-malloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_malloc_dbg** is reduced to a call to `_aligned_malloc`. Both `_aligned_malloc` and **_aligned_malloc_dbg** allocate a block of memory in the base heap, but **_aligned_malloc_dbg** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_malloc_dbg`** is a debug version of the [`_aligned_malloc`](aligned-malloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_malloc_dbg`** is reduced to a call to `_aligned_malloc`. Both `_aligned_malloc` and **`_aligned_malloc_dbg`** allocate a block of memory in the base heap, but **`_aligned_malloc_dbg`** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_malloc_dbg** allocates the memory block with slightly more space than the requested *size*. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_aligned_malloc_dbg`** allocates the memory block with slightly more space than the requested *`size`*. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD, and each of the overwrite buffers are filled with 0xFD. -**_aligned_malloc_dbg** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_malloc_dbg** validates its parameters. If *alignment* is not a power of 2 or *size* is zero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns NULL and sets `errno` to `EINVAL`. +**`_aligned_malloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_malloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2 or *`size`* is zero, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_malloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_malloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md) +[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-malloc.md b/docs/c-runtime-library/reference/aligned-malloc.md index c0a5a7fb134..38430e1f869 100644 --- a/docs/c-runtime-library/reference/aligned-malloc.md +++ b/docs/c-runtime-library/reference/aligned-malloc.md @@ -3,7 +3,7 @@ description: "Learn more about: _aligned_malloc" title: "_aligned_malloc" ms.date: "4/2/2020" api_name: ["_aligned_malloc", "_o__aligned_malloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_malloc", "alligned_malloc"] @@ -25,13 +25,13 @@ void * _aligned_malloc( ### Parameters -*`size`*
+*`size`*\ Size of the requested memory allocation. -*`alignment`*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -## Return Value +## Return value A pointer to the memory block that was allocated or `NULL` if the operation failed. The pointer is a multiple of *`alignment`*. @@ -39,19 +39,19 @@ A pointer to the memory block that was allocated or `NULL` if the operation fail **`_aligned_malloc`** is based on [`malloc`](malloc.md). -**`_aligned_malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). +**`_aligned_malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_malloc`** validates its parameters. If *`alignment`* is not a power of 2 or *`size`* is zero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns NULL and sets `errno` to `EINVAL`. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_malloc`** validates its parameters. If *`alignment`* isn't a power of 2 or *`size`* is zero, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. Use [`_aligned_free`](aligned-free.md) to deallocate memory obtained by both **`_aligned_malloc`** and `_aligned_offset_malloc`. Don't use `free`, which doesn't reclaim the aligned memory correctly and can lead to hard-to-diagnose bugs. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_aligned_malloc`**|``| +| Routine | Required C header | C++ header | +|---|---|---| +| **`_aligned_malloc`** | `` | `` | ## Example @@ -137,4 +137,4 @@ This pointer, 3280891, is offset by 5 on alignment of 16 ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md) +[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-msize-dbg.md b/docs/c-runtime-library/reference/aligned-msize-dbg.md index 6d20552a77a..ef2623a5e2c 100644 --- a/docs/c-runtime-library/reference/aligned-msize-dbg.md +++ b/docs/c-runtime-library/reference/aligned-msize-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["_aligned_msize_dbg"] helpviewer_keywords: ["_aligned_msize_dbg"] ms.assetid: f1c44af0-3f66-4033-81d1-d71d3afecba0 --- -# _aligned_msize_dbg +# `_aligned_msize_dbg` Returns the size of a memory block allocated in the heap (debug version only). @@ -26,41 +26,41 @@ size_t _aligned_msize_dbg( ### Parameters -*memblock*
+*`memblock`*\ Pointer to the memory block. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value Returns the size (in bytes) as an unsigned integer. ## Remarks -The *alignment* and *offset* values must be the same as the values passed to the function that allocated the block. +The *`alignment`* and *`offset`* values must be the same as the values passed to the function that allocated the block. -**_aligned_msize_dbg** is a debug version of the [_aligned_msize](aligned-msize.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_msize_dbg** is reduced to a call to **_aligned_msize**. Both **_aligned_msize** and **_aligned_msize_dbg** calculate the size of a memory block in the base heap, but **_aligned_msize_dbg** adds a debugging feature: It includes the buffers on either side of the user portion of the memory block in the returned size. +**`_aligned_msize_dbg`** is a debug version of the [`_aligned_msize`](aligned-msize.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_msize_dbg`** is reduced to a call to `_aligned_msize`. Both `_aligned_msize` and **`_aligned_msize_dbg`** calculate the size of a memory block in the base heap, but **`_aligned_msize_dbg`** adds a debugging feature: It includes the buffers on either side of the user portion of the memory block in the returned size. -This function validates its parameter. If *memblock* is a null pointer or *alignment* is not a power of 2, **_msize** invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a null pointer or *`alignment`* isn't a power of 2, `_msize` invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_msize_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_msize_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
+[Memory allocation](../memory-allocation.md) diff --git a/docs/c-runtime-library/reference/aligned-msize.md b/docs/c-runtime-library/reference/aligned-msize.md index 65b5f73a8b1..62782ee2510 100644 --- a/docs/c-runtime-library/reference/aligned-msize.md +++ b/docs/c-runtime-library/reference/aligned-msize.md @@ -3,14 +3,14 @@ description: "Learn more about: _aligned_msize" title: "_aligned_msize" ms.date: "4/2/2020" api_name: ["_aligned_msize", "_o__aligned_msize"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_msize", "aligned_msize"] helpviewer_keywords: ["aligned_msize function", "_aligned_msize function"] ms.assetid: 10995edc-2110-4212-9ca9-5e0220a464f4 --- -# _aligned_msize +# `_aligned_msize` Returns the size of a memory block allocated in the heap. @@ -26,41 +26,41 @@ size_t _aligned_msize( ### Parameters -*memblock*
+*`memblock`*\ Pointer to the memory block. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value Returns the size (in bytes) as an unsigned integer. ## Remarks -The **_aligned_msize** function returns the size, in bytes, of the memory block allocated by a call to [_aligned_malloc](aligned-malloc.md) or [_aligned_realloc](aligned-realloc.md). The *alignment* and *offset* values must be the same as the values passed to the function that allocated the block. +The **`_aligned_msize`** function returns the size, in bytes, of the memory block allocated by a call to [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_realloc`](aligned-realloc.md). The *`alignment`* and *`offset`* values must be the same as the values passed to the function that allocated the block. -When the application is linked with a debug version of the C run-time libraries, **_aligned_msize** resolves to [_aligned_msize_dbg](aligned-msize-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`_aligned_msize`** resolves to [`_aligned_msize_dbg`](aligned-msize-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -This function validates its parameter. If *memblock* is a null pointer or *alignment* is not a power of 2, **_aligned_msize** invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a null pointer or *`alignment`* isn't a power of 2, **`_aligned_msize`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_msize**|\| +| Routine | Required header | +|---|---| +| **`_aligned_msize`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
+[Memory allocation](../memory-allocation.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md b/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md index 527f4be2818..3eaa602cfbe 100644 --- a/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-malloc-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["_aligned_offset_malloc_dbg", "aligned_offset_malloc_dbg"] helpviewer_keywords: ["_aligned_offset_malloc_dbg function", "aligned_offset_malloc_dbg function"] ms.assetid: 6c242307-c59e-4d63-aae5-d8cbec8e021c --- -# _aligned_offset_malloc_dbg +# `_aligned_offset_malloc_dbg` Allocates memory on a specified alignment boundary (debug version only). @@ -28,53 +28,53 @@ void * _aligned_offset_malloc_dbg( ### Parameters -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -*filename*
-Pointer to the name of the source file that requested the allocation operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the allocation operation or `NULL`. -*linenumber*
-Line number in the source file where the allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the allocation operation was requested or `NULL`. -## Return Value +## Return value -A pointer to the memory block that was allocated or **NULL** if the operation failed. +A pointer to the memory block that was allocated or `NULL` if the operation failed. ## Remarks -**_aligned_offset_malloc_dbg** is a debug version of the [_aligned_offset_malloc](aligned-offset-malloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_offset_malloc_dbg** is reduced to a call to **_aligned_offset_malloc**. Both **_aligned_offset_malloc** and **_aligned_offset_malloc_dbg** allocate a block of memory in the base heap, but **_aligned_offset_malloc_dbg** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_offset_malloc_dbg`** is a debug version of the [`_aligned_offset_malloc`](aligned-offset-malloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_offset_malloc_dbg`** is reduced to a call to **`_aligned_offset_malloc`**. Both **`_aligned_offset_malloc`** and **`_aligned_offset_malloc_dbg`** allocate a block of memory in the base heap, but **`_aligned_offset_malloc_dbg`** offers several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_offset_malloc_dbg** allocates the memory block with slightly more space than the requested *size*. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_aligned_offset_malloc_dbg`** allocates the memory block with slightly more space than the requested *`size`*. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. When the block is allocated, the user portion of the block is filled with the value 0xCD, and each of the overwrite buffers are filled with 0xFD. -**_aligned_offset_malloc_dbg** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. +**`_aligned_offset_malloc_dbg`** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. -**_aligned_offset_malloc_dbg** is based on **malloc**; for more information, see [malloc](malloc.md). +**`_aligned_offset_malloc_dbg`** is based on `malloc`; for more information, see [`malloc`](malloc.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_malloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, `_aligned_offset_malloc` validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). -For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_malloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_malloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-malloc.md b/docs/c-runtime-library/reference/aligned-offset-malloc.md index d0eae71c052..70bd83880bf 100644 --- a/docs/c-runtime-library/reference/aligned-offset-malloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-malloc.md @@ -3,14 +3,14 @@ description: "Learn more about: _aligned_offset_malloc" title: "_aligned_offset_malloc" ms.date: "4/2/2020" api_name: ["_aligned_offset_malloc", "_o__aligned_offset_malloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_offset_malloc", "aligned_offset_malloc"] helpviewer_keywords: ["_aligned_offset_malloc function", "aligned_offset_malloc function"] ms.assetid: 447681a3-7c95-4655-86ba-fa3a4ca4c521 --- -# _aligned_offset_malloc +# `_aligned_offset_malloc` Allocates memory on a specified alignment boundary. @@ -26,41 +26,41 @@ void * _aligned_offset_malloc( ### Parameters -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value -A pointer to the memory block that was allocated or **NULL** if the operation failed. +A pointer to the memory block that was allocated or `NULL` if the operation failed. ## Remarks -**_aligned_offset_malloc** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. +**`_aligned_offset_malloc`** is useful in situations where alignment is needed on a nested element; for example, if alignment was needed on a nested class. -**_aligned_offset_malloc** is based on **malloc**; for more information, see [malloc](malloc.md). +**`_aligned_offset_malloc`** is based on `malloc`; for more information, see [`malloc`](malloc.md). -**_aligned_offset_malloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_aligned_offset_malloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_malloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_malloc`** validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_malloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_malloc`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md b/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md index ec0b1863188..b9292dae921 100644 --- a/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-realloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["aligned_offset_realloc_dbg", "_aligned_offset_realloc_dbg"] helpviewer_keywords: ["aligned_offset_realloc_dbg function", "_aligned_offset_realloc_dbg function"] ms.assetid: 64e30a12-887e-453b-aea8-aed793fca9d8 --- -# _aligned_offset_realloc_dbg +# `_aligned_offset_realloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) (debug version only). ## Syntax @@ -29,52 +29,52 @@ void * _aligned_offset_realloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -*filename*
-Pointer to the name of the source file that requested the **aligned_offset_realloc** operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the **`aligned_offset_realloc`** operation or `NULL`. -*linenumber*
-Line number in the source file where the **aligned_offset_realloc** operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the **`aligned_offset_realloc`** operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_offset_realloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_realloc_dbg`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that's suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. ## Remarks -**_aligned_offset_realloc_dbg** is a debug version of the [_aligned_offset_realloc](aligned-offset-realloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_offset_realloc_dbg** is reduced to a call to **_aligned_offset_realloc**. Both **_aligned_offset_realloc** and **_aligned_offset_realloc_dbg** reallocate a memory block in the base heap, but **_aligned_offset_realloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_offset_realloc_dbg`** is a debug version of the [`_aligned_offset_realloc`](aligned-offset-realloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_offset_realloc_dbg`** is reduced to a call to **`_aligned_offset_realloc`**. Both **`_aligned_offset_realloc`** and **`_aligned_offset_realloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_offset_realloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -Like [_aligned_offset_malloc](aligned-offset-malloc.md), **_aligned_offset_realloc_dbg** allows a structure to be aligned at an offset within the structure. +Like [`_aligned_offset_malloc`](aligned-offset-malloc.md), **`_aligned_offset_realloc_dbg`** allows a structure to be aligned at an offset within the structure. -**_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +`_realloc_dbg` reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and also change the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_realloc_dbg** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_realloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2 or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_realloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_realloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-realloc.md b/docs/c-runtime-library/reference/aligned-offset-realloc.md index 53d2c11384e..462eb5e22a9 100644 --- a/docs/c-runtime-library/reference/aligned-offset-realloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-realloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_offset_realloc" title: "_aligned_offset_realloc" ms.date: "4/2/2020" api_name: ["_aligned_offset_realloc", "_o__aligned_offset_realloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_offset_realloc", "_aligned_offset_realloc"] helpviewer_keywords: ["aligned_offset_realloc function", "_aligned_offset_realloc function"] ms.assetid: e0263533-991e-41b0-acc9-1b8a51ab9ecd --- -# _aligned_offset_realloc +# `_aligned_offset_realloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md). ## Syntax @@ -27,44 +27,44 @@ void * _aligned_offset_realloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value -**_aligned_offset_realloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_realloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than `void`, use a type cast on the return value. -**_aligned_offset_realloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_aligned_offset_realloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). ## Remarks -Like [_aligned_offset_malloc](aligned-offset-malloc.md), **_aligned_offset_realloc** allows a structure to be aligned at an offset within the structure. +Like [`_aligned_offset_malloc`](aligned-offset-malloc.md), **`_aligned_offset_realloc`** allows a structure to be aligned at an offset within the structure. -**_aligned_offset_realloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). If *memblock* is **NULL**, the function calls **_aligned_offset_malloc** internally. +**`_aligned_offset_realloc`** is based on `malloc`. For more information about using **`_aligned_offset_malloc`**, see [`malloc`](malloc.md). If *`memblock`* is `NULL`, the function calls **`_aligned_offset_malloc`** internally. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_realloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to *size* and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_realloc`** validates its parameters. If *`alignment`* isn't a power of 2 or if *`offset`* is non-zero and greater than or equal to *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_realloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_realloc`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md b/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md index 99bd6f96539..34046b47a65 100644 --- a/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-offset-recalloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["aligned_offset_recalloc_dbg", "_aligned_offset_recalloc_dbg"] helpviewer_keywords: ["aligned_offset_recalloc_dbg function", "_aligned_offset_recalloc_dbg function"] ms.assetid: 7ab719c3-77e0-4d2e-934f-01529d062fbf --- -# _aligned_offset_recalloc_dbg +# `_aligned_offset_recalloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). ## Syntax @@ -30,47 +30,47 @@ void * _aligned_offset_recalloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ Number of elements. -*size*
+*`size`*\ Length in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -*filename*
-Pointer to the name of the source file that requested the realloc operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the realloc operation or `NULL`. -*linenumber*
-Line number in the source file where the realloc operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the realloc operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_offset_recalloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_recalloc_dbg`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than `void`, use a type cast on the return value. ## Remarks -**_aligned_offset_realloc_dbg** is a debug version of the [_aligned_offset_recalloc](aligned-offset-recalloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_offset_recalloc_dbg** is reduced to a call to **_aligned_offset_recalloc**. Both **_aligned_offset_recalloc** and **_aligned_offset_recalloc_dbg** reallocate a memory block in the base heap, but **_aligned_offset_recalloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_offset_realloc_dbg`** is a debug version of the [`_aligned_offset_recalloc`](aligned-offset-recalloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_offset_recalloc_dbg`** is reduced to a call to **`_aligned_offset_recalloc`**. Both **`_aligned_offset_recalloc`** and **`_aligned_offset_recalloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_offset_recalloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_offset_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +**`_aligned_offset_realloc_dbg`** reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and also change the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size (*number* * *size*) was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_recalloc_dbg** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to the requested size and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size (*`number`* * *`size`*) was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_recalloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to the requested *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_recalloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_recalloc_dbg`** | \ | ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-offset-recalloc.md b/docs/c-runtime-library/reference/aligned-offset-recalloc.md index e5536001234..6b8878748ff 100644 --- a/docs/c-runtime-library/reference/aligned-offset-recalloc.md +++ b/docs/c-runtime-library/reference/aligned-offset-recalloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_offset_recalloc" title: "_aligned_offset_recalloc" ms.date: "4/2/2020" api_name: ["_aligned_offset_recalloc", "_o__aligned_offset_recalloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_offset_recalloc", "_aligned_offset_recalloc"] helpviewer_keywords: ["aligned_offset_recalloc function", "_aligned_offset_recalloc function"] ms.assetid: a258f54e-eeb4-4853-96fc-007d710f98e9 --- -# _aligned_offset_recalloc +# `_aligned_offset_recalloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0. +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0. ## Syntax @@ -28,45 +28,45 @@ void * _aligned_offset_recalloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ Number of elements. -*size*
+*`size`*\ Length in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*offset*
+*`offset`*\ The offset into the memory allocation to force the alignment. -## Return Value +## Return value -**_aligned_offset_recalloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_offset_recalloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -**_aligned_offset_recalloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_aligned_offset_recalloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). ## Remarks -Like [_aligned_offset_malloc](aligned-offset-malloc.md), **_aligned_offset_recalloc** allows a structure to be aligned at an offset within the structure. +Like [`_aligned_offset_malloc`](aligned-offset-malloc.md), **`_aligned_offset_recalloc`** allows a structure to be aligned at an offset within the structure. -**_aligned_offset_recalloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). If *memblock* is **NULL**, the function calls **_aligned_offset_malloc** internally. +**`_aligned_offset_recalloc`** is based on `malloc`. For more information about using **`_aligned_offset_malloc`**, see [`malloc`](malloc.md). If *`memblock`* is `NULL`, the function calls **`_aligned_offset_malloc`** internally. -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size (*number* * *size*) was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_offset_recalloc** validates its parameters. If *alignment* is not a power of 2 or if *offset* is greater than or equal to the requested size and nonzero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size (*`number`* * *`size`*) was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_offset_recalloc`** validates its parameters. If *`alignment`* isn't a power of 2, or if *`offset`* is non-zero and greater than or equal to the requested *`size`*, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_offset_recalloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_offset_recalloc`** | \ | ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
-[_recalloc](recalloc.md)
-[_aligned_recalloc](aligned-recalloc.md)
+[Data alignment](../data-alignment.md)\ +[`_recalloc`](recalloc.md)\ +[`_aligned_recalloc`](aligned-recalloc.md) diff --git a/docs/c-runtime-library/reference/aligned-realloc-dbg.md b/docs/c-runtime-library/reference/aligned-realloc-dbg.md index b817c6b38a4..02f8a69c490 100644 --- a/docs/c-runtime-library/reference/aligned-realloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-realloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["aligned_realloc_dbg", "_aligned_realloc_dbg"] helpviewer_keywords: ["_aligned_realloc_dbg function", "aligned_realloc_dbg function"] ms.assetid: 8aede920-991e-44cd-867f-83dc2165db47 --- -# _aligned_realloc_dbg +# `_aligned_realloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) (debug version only). ## Syntax @@ -28,51 +28,51 @@ void * _aligned_realloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*filename*
-Pointer to the name of the source file that requested the **realloc** operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the `realloc` operation or `NULL`. -*linenumber*
-Line number in the source file where the **realloc** operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the `realloc` operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_realloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_realloc_dbg`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_realloc_dbg** is a debug version of the [_aligned_realloc](aligned-realloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_realloc_dbg** is reduced to a call to **_aligned_realloc**. Both **_aligned_realloc** and **_aligned_realloc_dbg** reallocate a memory block in the base heap, but **_aligned_realloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_realloc_dbg`** is a debug version of the [`_aligned_realloc`](aligned-realloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_realloc_dbg`** is reduced to a call to `_aligned_realloc`. Both `_aligned_realloc` and **`_aligned_realloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_realloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +**`_aligned_realloc_dbg`** reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and change the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -**_aligned_realloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_aligned_realloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -Also, **_aligned_realloc_dbg** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +Also, **`_aligned_realloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_realloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_realloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-realloc.md b/docs/c-runtime-library/reference/aligned-realloc.md index 964f8acf631..bb7f2177f09 100644 --- a/docs/c-runtime-library/reference/aligned-realloc.md +++ b/docs/c-runtime-library/reference/aligned-realloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_realloc" title: "_aligned_realloc" ms.date: "4/2/2020" api_name: ["_aligned_realloc", "_o__aligned_realloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_aligned_realloc", "aligned_realloc"] helpviewer_keywords: ["aligned_realloc function", "_aligned_realloc function"] ms.assetid: 80ce96e8-6087-416f-88aa-4dbb8cb1d218 --- -# _aligned_realloc +# `_aligned_realloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md). ## Syntax @@ -26,39 +26,39 @@ void * _aligned_realloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*size*
+*`size`*\ The size of the requested memory allocation. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -## Return Value +## Return value -**_aligned_realloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_realloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_realloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). +**`_aligned_realloc`** is based on `malloc`. For more information about using `_aligned_offset_malloc`, see [`malloc`](malloc.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_realloc** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_realloc`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_realloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_realloc`** | \ | ## Example -For more information, see [_aligned_malloc](aligned-malloc.md). +For more information, see [`_aligned_malloc`](aligned-malloc.md). ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
+[Data alignment](../data-alignment.md) diff --git a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md index f4743e9444b..41d21546894 100644 --- a/docs/c-runtime-library/reference/aligned-recalloc-dbg.md +++ b/docs/c-runtime-library/reference/aligned-recalloc-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_aligned_recalloc_dbg", "aligned_recalloc_dbg"] helpviewer_keywords: ["aligned_recalloc_dbg function", "_aligned_recalloc_dbg function"] ms.assetid: 55c3c27e-561c-4d6b-9bf9-1e34cc556e4b --- -# _aligned_recalloc_dbg +# `_aligned_recalloc_dbg` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0 (debug version only). ## Syntax @@ -29,54 +29,54 @@ void * _aligned_recalloc_dbg( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ The number of elements. -*size*
+*`size`*\ The size in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -*filename*
-Pointer to name of the source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of the source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in the source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where allocation operation was requested or `NULL`. -## Return Value +## Return value -**_aligned_recalloc_dbg** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_recalloc_dbg`** returns a `void` pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than `void`, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_recalloc_dbg** is a debug version of the [_aligned_recalloc](aligned-recalloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_aligned_recalloc_dbg** is reduced to a call to **_aligned_recalloc**. Both **_aligned_recalloc** and **_aligned_recalloc_dbg** reallocate a memory block in the base heap, but **_aligned_recalloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *filename*/*linenumber* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter is not a supported debug feature for aligned allocations. Aligned allocations will appear as a _NORMAL_BLOCK block type. +**`_aligned_recalloc_dbg`** is a debug version of the [`_aligned_recalloc`](aligned-recalloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_aligned_recalloc_dbg`** is reduced to a call to `_aligned_recalloc`. Both `_aligned_recalloc` and **`_aligned_recalloc_dbg`** reallocate a memory block in the base heap, but **`_aligned_recalloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. Tracking specific allocation types with a block type parameter isn't a supported debug feature for aligned allocations. Aligned allocations will appear as a `_NORMAL_BLOCK` block type. -**_aligned_recalloc_dbg** reallocates the specified memory block with slightly more space than the requested size (*number* * *size*) which might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. The user portion of the block is filled with the value 0xCD and the overwrite buffers are filled with 0xFD. +**`_aligned_recalloc_dbg`** reallocates the specified memory block with slightly more space than the requested size (*`number`* * *`size`*) which might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might both move the original memory block to a different location in the heap, and change the size of the memory block. The user portion of the block is filled with the value 0xCD, and the overwrite buffers are filled with 0xFD. -**_aligned_recalloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails; **EINVAL** is returned if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_aligned_recalloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails; `EINVAL` is returned if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -Also, **_aligned_recalloc_dbg** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +Also, **`_aligned_recalloc_dbg`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and their debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_recalloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_aligned_recalloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/aligned-recalloc.md b/docs/c-runtime-library/reference/aligned-recalloc.md index 0dd18cf48f6..f3127771e71 100644 --- a/docs/c-runtime-library/reference/aligned-recalloc.md +++ b/docs/c-runtime-library/reference/aligned-recalloc.md @@ -3,16 +3,16 @@ description: "Learn more about: _aligned_recalloc" title: "_aligned_recalloc" ms.date: "4/2/2020" api_name: ["_aligned_recalloc", "_o__aligned_recalloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["aligned_recalloc", "_aligned_recalloc"] helpviewer_keywords: ["aligned_recalloc function", "_aligned_recalloc function"] ms.assetid: d3da3dcc-79ef-4273-8af5-ac7469420142 --- -# _aligned_recalloc +# `_aligned_recalloc` -Changes the size of a memory block that was allocated with [_aligned_malloc](aligned-malloc.md) or [_aligned_offset_malloc](aligned-offset-malloc.md) and initializes the memory to 0. +Changes the size of a memory block that was allocated with [`_aligned_malloc`](aligned-malloc.md) or [`_aligned_offset_malloc`](aligned-offset-malloc.md) and initializes the memory to 0. ## Syntax @@ -27,40 +27,40 @@ void * _aligned_recalloc( ### Parameters -*memblock*
+*`memblock`*\ The current memory block pointer. -*number*
+*`number`*\ The number of elements. -*size*
+*`size`*\ The size in bytes of each element. -*alignment*
+*`alignment`*\ The alignment value, which must be an integer power of 2. -## Return Value +## Return value -**_aligned_recalloc** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is **NULL** if the size is zero and the buffer argument is not **NULL**, or if there is not enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. +**`_aligned_recalloc`** returns a void pointer to the reallocated (and possibly moved) memory block. The return value is `NULL` if the size is zero and the buffer argument isn't `NULL`, or if there isn't enough available memory to expand the block to the given size. In the first case, the original block is freed. In the second case, the original block is unchanged. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value. -It is an error to reallocate memory and change the alignment of a block. +It's an error to reallocate memory and change the alignment of a block. ## Remarks -**_aligned_recalloc** is based on **malloc**. For more information about using **_aligned_offset_malloc**, see [malloc](malloc.md). +**`_aligned_recalloc`** is based on `malloc`. For more information about using `_aligned_offset_malloc`, see [`malloc`](malloc.md). -This function sets **errno** to **ENOMEM** if the memory allocation failed or if the requested size was greater than **_HEAP_MAXREQ**. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **_aligned_recalloc** validates its parameters. If *alignment* is not a power of 2, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **NULL** and sets **errno** to **EINVAL**. +This function sets `errno` to `ENOMEM` if the memory allocation failed or if the requested size was greater than `_HEAP_MAXREQ`. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). Also, **`_aligned_recalloc`** validates its parameters. If *`alignment`* isn't a power of 2, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_aligned_recalloc**|\| +| Routine | Required header | +|---|---| +| **`_aligned_recalloc`** | \ | ## See also -[Data Alignment](../../c-runtime-library/data-alignment.md)
-[_recalloc](recalloc.md)
-[_aligned_offset_recalloc](aligned-offset-recalloc.md)
+[Data alignment](../data-alignment.md)\ +[`_recalloc`](recalloc.md)\ +[`_aligned_offset_recalloc`](aligned-offset-recalloc.md) diff --git a/docs/c-runtime-library/reference/alloca.md b/docs/c-runtime-library/reference/alloca.md index 5367a7aec44..7c78844e4d9 100644 --- a/docs/c-runtime-library/reference/alloca.md +++ b/docs/c-runtime-library/reference/alloca.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _alloca" title: "_alloca" +description: "Learn more about: _alloca" ms.date: 01/05/2022 api_name: ["_alloca"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -26,36 +26,36 @@ void *_alloca( *`size`*\ Bytes to be allocated from the stack. -## Return Value +## Return value -The **`_alloca`** routine returns a **`void`** pointer to the allocated space, which is guaranteed to be suitably aligned for storage of any type of object. If *`size`* is 0, **`_alloca`** allocates a zero-length item and returns a valid pointer to that item. +The **`_alloca`** routine returns a **`void`** pointer to the allocated space, which is suitably aligned for storage of any type of object. If *`size`* is 0, **`_alloca`** allocates a zero-length item and returns a valid pointer to that item. -A stack overflow exception is generated if the space can't be allocated. The stack overflow exception isn't a C++ exception; it's a structured exception. Instead of using C++ exception handling, you must use [Structured Exception Handling](../../cpp/structured-exception-handling-c-cpp.md) (SEH). +A stack overflow exception is generated if the space can't be allocated. The stack overflow exception isn't a C++ exception; it's a structured exception. Instead of using C++ exception handling, you must use [Structured exception handling](../../cpp/structured-exception-handling-c-cpp.md) (SEH). ## Remarks -**`_alloca`** allocates *`size`* bytes from the program stack. The allocated space is automatically freed when the calling function exits (not when the allocation merely passes out of scope). Therefore, do not pass the pointer value returned by **`_alloca`** as an argument to [`free`](free.md). +**`_alloca`** allocates *`size`* bytes from the program stack. The allocated space is automatically freed when the calling function exits (not when the allocation merely passes out of scope). Therefore, don't pass the pointer value returned by **`_alloca`** as an argument to [`free`](free.md). -There are restrictions to explicitly calling **`_alloca`** in an exception handler (EH). EH routines that run on x86-class processors operate in their own memory frame: They perform their tasks in memory space that isn't based on the current location of the stack pointer of the enclosing function. The most common implementations include Windows NT structured exception handling (SEH) and C++ catch clause expressions. Therefore, explicitly calling **`_alloca`** in any of the following scenarios results in program failure during the return to the calling EH routine: +There are restrictions to explicitly calling **`_alloca`** in an exception handler (EH). EH routines that run on x86-class processors operate in their own memory frame: They perform their tasks in memory space that isn't based on the current location of the stack pointer of the enclosing function. The most common implementations include Windows structured exception handling (SEH) and C++ catch clause expressions. Therefore, explicitly calling **`_alloca`** in any of the following scenarios results in program failure during the return to the calling EH routine: -- Windows NT SEH exception filter expression: `__except ( _alloca() )` +- Windows SEH exception filter expression: `__except ( _alloca() )` -- Windows NT SEH final exception handler: `__finally { _alloca() }` +- Windows SEH final exception handler: `__finally { _alloca() }` - C++ EH catch clause expression However, **`_alloca`** can be called directly from within an EH routine or from an application-supplied callback that gets invoked by one of the EH scenarios previously listed. > [!IMPORTANT] -> In Windows XP, if **`_alloca`** is called inside a try/catch block, you must call [`_resetstkoflw`](resetstkoflw.md) in the catch block. +> If **`_alloca`** is called inside a try block, you must call [`_resetstkoflw`](resetstkoflw.md) in the catch block. -In addition to the above restrictions, when using the[`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) option, **`_alloca`** can't be used in **`__except`** blocks. For more information, see [`/clr` Restrictions](../../build/reference/clr-restrictions.md). +In addition to the above restrictions, when using the [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) option, **`_alloca`** can't be used in **`__except`** blocks. For more information, see [`/clr` Restrictions](../../build/reference/clr-restrictions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_alloca`**|``| +| Routine | Required header | +|---|---| +| **`_alloca`** | `` | ## Example @@ -117,7 +117,7 @@ Allocated 1000 bytes of stack at 0x0012FB50 ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)\ +[Memory allocation](../memory-allocation.md)\ [`calloc`](calloc.md)\ [`malloc`](malloc.md)\ [`realloc`](realloc.md)\ diff --git a/docs/c-runtime-library/reference/amsg-exit.md b/docs/c-runtime-library/reference/amsg-exit.md index 7710315f0e8..ca2e19752d6 100644 --- a/docs/c-runtime-library/reference/amsg-exit.md +++ b/docs/c-runtime-library/reference/amsg-exit.md @@ -10,7 +10,7 @@ f1_keywords: ["_amsg_exit"] helpviewer_keywords: ["_amsg_exit"] ms.assetid: 146d4faf-d763-43a4-b264-12711196456b --- -# _amsg_exit +# `_amsg_exit` Emits a specified runtime error message and then exits your application with error code 255. @@ -22,15 +22,15 @@ void _amsg_exit ( int rterrnum ); ### Parameters -*rterrnum*
+*`rterrnum`*\ The identification number of a system-defined runtime error message. ## Remarks -This function emits the runtime error message to **stderr** for console applications, or displays the message in a message box for Windows applications. In debug mode, you can choose to invoke the debugger before exiting. +This function emits the runtime error message to `stderr` for console applications, or displays the message in a message box for Windows applications. In debug mode, you can choose to invoke the debugger before exiting. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|_amsg_exit|internal.h| +| Routine | Required header | +|---|---| +| _amsg_exit | internal.h | diff --git a/docs/c-runtime-library/reference/and-eq.md b/docs/c-runtime-library/reference/and-eq.md index 08fc82a019d..b8844704b39 100644 --- a/docs/c-runtime-library/reference/and-eq.md +++ b/docs/c-runtime-library/reference/and-eq.md @@ -5,11 +5,11 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["and_eq", "std.and_eq", "std::and_eq"] +f1_keywords: ["ISO646/and_eq", "and_eq", "std.and_eq", "std::and_eq"] helpviewer_keywords: ["and_eq macro"] ms.assetid: 11091772-e359-4c2b-95c6-00841ac04354 --- -# and_eq +# `and_eq` An alternative to the &= operator. diff --git a/docs/c-runtime-library/reference/and.md b/docs/c-runtime-library/reference/and.md index 99a4520effe..efa2cca2861 100644 --- a/docs/c-runtime-library/reference/and.md +++ b/docs/c-runtime-library/reference/and.md @@ -1,22 +1,20 @@ --- -description: "Learn more about: and" title: "and" +description: "Learn more about: and" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["And", "std.and", "std::and"] +f1_keywords: ["ISO646/and", "and", "std.and", "std::and"] helpviewer_keywords: ["and macro"] -ms.assetid: 2644ab57-8e1b-48f0-9021-cafe3e26bdc4 --- -# and +# `and` An alternative to the && operator. ## Syntax ```C - #define and && ``` diff --git a/docs/c-runtime-library/reference/asctime-s-wasctime-s.md b/docs/c-runtime-library/reference/asctime-s-wasctime-s.md index 4ea2fcd6d82..99d3ffe89b3 100644 --- a/docs/c-runtime-library/reference/asctime-s-wasctime-s.md +++ b/docs/c-runtime-library/reference/asctime-s-wasctime-s.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: asctime_s, _wasctime_s" title: "asctime_s, _wasctime_s" -ms.date: "4/2/2020" +description: "Learn more about: asctime_s, _wasctime_s" +ms.date: 4/2/2020 api_name: ["_wasctime_s", "asctime_s", "_o__wasctime_s", "_o_asctime_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["asctime_s", "_wasctime_s", "_tasctime_s"] helpviewer_keywords: ["tasctime_s function", "_tasctime_s function", "time structure conversion", "wasctime_s function", "time, converting", "_wasctime_s function", "asctime_s function"] -ms.assetid: 17ad9b2b-a459-465d-976a-42822897688a --- -# asctime_s, _wasctime_s +# `asctime_s`, `_wasctime_s` -Convert a **tm** time structure to a character string. These functions are versions of [asctime, _wasctime](asctime-wasctime.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a `tm` time structure to a character string. These functions are versions of [`asctime`, `_wasctime`](asctime-wasctime.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -24,7 +23,7 @@ errno_t asctime_s( ); errno_t _wasctime_s( wchar_t* buffer, - size_t numberOfElements + size_t numberOfElements, const struct tm *tmSource ); template @@ -41,82 +40,82 @@ errno_t _wasctime_s( ### Parameters -*buffer*
-A pointer to a buffer to store the character string result. This function assumes a pointer to a valid memory location with a size specified by *numberOfElements*. +*`buffer`*\ +A pointer to a buffer to store the character string result. This function assumes a pointer to a valid memory location with a size specified by *`numberOfElements`*. -*numberOfElements*
+*`numberOfElements`*\ The size of the buffer used to store the result. -*tmSource*
-Time/date structure. This function assumes a pointer to a valid **`struct`** **tm** object. +*`tmSource`*\ +Time/date structure. This function assumes a pointer to a valid `struct tm` object. -## Return Value +## Return value -Zero if successful. If there is a failure, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the return value is an error code. Error codes are defined in ERRNO.H. For more information, see [errno Constants](../../c-runtime-library/errno-constants.md). The actual error codes returned for each error condition are shown in the following table. +Zero if successful. If there's a failure, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the return value is an error code. Error codes are defined in ERRNO.H. For more information, see [`errno` constants](../errno-constants.md). The actual error codes returned for each error condition are shown in the following table. -### Error Conditions +### Error conditions -|*buffer*|*numberOfElements*|*tmSource*|Return|Value in *buffer*| -|--------------|------------------------|----------|------------|-----------------------| -|**NULL**|Any|Any|**EINVAL**|Not modified| -|Not **NULL** (points to valid memory)|0|Any|**EINVAL**|Not modified| -|Not **NULL**|0< size < 26|Any|**EINVAL**|Empty string| -|Not **NULL**|>= 26|**NULL**|**EINVAL**|Empty string| -|Not **NULL**|>= 26|Invalid time structure or out of range values for components of the time|**EINVAL**|Empty string| +| *`buffer`* | *`numberOfElements`* | *`tmSource`* | Return | Value in *`buffer`* | +|---|---|---|---|---| +| `NULL` | Any | Any | `EINVAL` | Not modified | +| Not `NULL` (points to valid memory) | 0 | Any | `EINVAL` | Not modified | +| Not `NULL` | 0< *`numberOfElements`* < 26 | Any | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | `NULL` | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | Invalid time structure or out of range values for components of the time | `EINVAL` | Empty string | > [!NOTE] -> Error conditions for **wasctime_s** are similar to **asctime_s** with the exception that the size limit is measured in words. +> Error conditions for **`wasctime_s`** are similar to **`asctime_s`** with the exception that the size limit is measured in words. ## Remarks -The **asctime** function converts a time stored as a structure to a character string. The *tmSource* value is usually obtained from a call to **gmtime** or **localtime**. Both functions can be used to fill in a **tm** structure, as defined in TIME.H. +The `asctime` function converts a time stored as a structure to a character string. The *`tmSource`* value is typically obtained from a call to `gmtime` or `localtime`. Both functions can be used to fill in a `tm` structure, as defined in TIME.H. -|timeptr member|Value| -|--------------------|-----------| -|**tm_hour**|Hours since midnight (0-23)| -|**tm_isdst**|Positive if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST).| -|**tm_mday**|Day of month (1-31)| -|**tm_min**|Minutes after hour (0-59)| -|**tm_mon**|Month (0-11; January = 0)| -|**tm_sec**|Seconds after minute (0-59)| -|**tm_wday**|Day of week (0-6; Sunday = 0)| -|**tm_yday**|Day of year (0-365; January 1 = 0)| -|**tm_year**|Year (current year minus 1900)| +| timeptr member | Value | +|---|---| +| `tm_hour` | Hours since midnight (0-23) | +| `tm_isdst` | Positive if daylight saving time is in effect; 0 if daylight saving time isn't in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST). | +| `tm_mday` | Day of month (1-31) | +| `tm_min` | Minutes after hour (0-59) | +| `tm_mon` | Month (0-11; January = 0) | +| `tm_sec` | Seconds after minute (0-59) | +| `tm_wday` | Day of week (0-6; Sunday = 0) | +| `tm_yday` | Day of year (0-365; January 1 = 0) | +| `tm_year` | Year (current year minus 1900) | -The converted character string is also adjusted according to the local time zone settings. See the [time, _time32, _time64](time-time32-time64.md), [_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md), and [localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md) functions for information about configuring the local time and the [_tzset](tzset.md) function for information about defining the time zone environment and global variables. +The converted character string is also adjusted according to the local time zone settings. For information about configuring the local time, see the [`time`, `_time32`, `_time64`](time-time32-time64.md), [`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md), and [`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md) functions. For information about defining the time zone environment and global variables, see [`_tzset`](tzset.md). -The string result produced by **asctime_s** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The new line character and the null character occupy the last two positions of the string. The value passed in as the second parameter should be at least this big. If it is less, an error code, **EINVAL**, will be returned. +The string result produced by **`asctime_s`** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The new line character and the null character occupy the last two positions of the string. The value passed in as *`numberOfElements`* should be at least this size. If it's less, an error code, `EINVAL`, will be returned. -**_wasctime_s** is a wide-character version of **asctime_s**. **_wasctime_s** and **asctime_s** behave identically otherwise. +**`_wasctime_s`** is a wide-character version of **`asctime_s`**. **`_wasctime_s`** and **`asctime_s`** behave identically otherwise. -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mapping +### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tasctime_s**|**asctime_s**|**asctime_s**|**_wasctime_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tasctime_s`** | **`asctime_s`** | **`asctime_s`** | **`_wasctime_s`** | -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**asctime_s**|\| -|**_wasctime_s**|\ or \| +| Routine | Required header | +|---|---| +| **`asctime_s`** | \ | +| **`_wasctime_s`** | \ or \ | ## Security -If the buffer pointer is not **NULL** and the pointer does not point to a valid buffer, the function will overwrite whatever is at the location. This can also result in an access violation. +If the buffer pointer isn't `NULL` and the pointer doesn't point to a valid buffer, the function will overwrite whatever is at the location. This error can also result in an access violation. A [buffer overrun](/windows/win32/SecBP/avoiding-buffer-overruns) can occur if the size argument passed in is greater than the actual size of the buffer. ## Example -This program places the system time in the long integer **aclock**, translates it into the structure **newtime** and then converts it to string form for output, using the **asctime_s** function. +This program places the system time in the long integer `aclock`, translates it into the structure `newtime`, and then converts it to string form for output, using the **`asctime_s`** function. ```C // crt_asctime_s.c @@ -152,10 +151,10 @@ Current date and time: Wed May 14 15:30:17 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/asctime-wasctime.md b/docs/c-runtime-library/reference/asctime-wasctime.md index 1d66bb3cda1..f08c1fbfb8e 100644 --- a/docs/c-runtime-library/reference/asctime-wasctime.md +++ b/docs/c-runtime-library/reference/asctime-wasctime.md @@ -1,18 +1,18 @@ --- description: "Learn more about: asctime, _wasctime" title: "asctime, _wasctime" -ms.date: "4/2/2020" +ms.date: 12/21/2022 api_name: ["_wasctime", "asctime", "_o__wasctime", "_o_asctime"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tasctime", "asctime", "_wasctime"] helpviewer_keywords: ["asctime function", "tasctime function", "wasctime function", "_tasctime function", "_wasctime function", "time structure conversion", "time, converting"] ms.assetid: 974f1727-10ff-4ed4-8cac-2eb2d681f576 --- -# asctime, _wasctime +# `asctime`, `_wasctime` -Convert a **tm** time structure to a character string. More secure versions of these functions are available; see [asctime_s, _wasctime_s](asctime-s-wasctime-s.md). +Convert a `tm` time structure to a character string. More secure versions of these functions are available; see [`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md). ## Syntax @@ -27,57 +27,57 @@ wchar_t *_wasctime( ### Parameters -*timeptr*
+*`timeptr`*\ Time/date structure. -## Return Value +## Return value -**asctime** returns a pointer to the character string result; **_wasctime** returns a pointer to the wide-character string result. There is no error return value. +**`asctime`** returns a pointer to the character string result; **`_wasctime`** returns a pointer to the wide-character string result. There's no error return value. ## Remarks -More secure versions of these functions are available; see [asctime_s, _wasctime_s](asctime-s-wasctime-s.md). +More secure versions of these functions are available; see [`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md). -The **asctime** function converts a time stored as a structure to a character string. The *timeptr* value is usually obtained from a call to **gmtime** or **localtime**, which both return a pointer to a **tm** structure, defined in TIME.H. +The **`asctime`** function converts a time stored as a structure to a character string. The *`timeptr`* value is typically obtained from a call to `gmtime` or `localtime`, which both return a pointer to a `tm` structure, defined in TIME.H. -|timeptr member|Value| -|--------------------|-----------| -|**tm_hour**|Hours since midnight (0-23)| -|**tm_isdst**|Positive if daylight saving time is in effect; 0 if daylight saving time is not in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST).| -|**tm_mday**|Day of month (1-31)| -|**tm_min**|Minutes after hour (0-59)| -|**tm_mon**|Month (0-11; January = 0)| -|**tm_sec**|Seconds after minute (0-59)| -|**tm_wday**|Day of week (0-6; Sunday = 0)| -|**tm_yday**|Day of year (0-365; January 1 = 0)| -|**tm_year**|Year (current year minus 1900)| +| `timeptr` member | Value | +|---|---| +| `tm_hour` | Hours since midnight (0-23) | +| `tm_isdst` | Positive if daylight saving time is in effect; 0 if daylight saving time isn't in effect; negative if status of daylight saving time is unknown. The C run-time library assumes the United States' rules for implementing the calculation of Daylight Saving Time (DST). | +| `tm_mday` | Day of month (1-31) | +| `tm_min` | Minutes after hour (0-59) | +| `tm_mon` | Month (0-11; January = 0) | +| `tm_sec` | Seconds after minute (0-59) | +| `tm_wday` | Day of week (0-6; Sunday = 0) | +| `tm_yday` | Day of year (0-365; January 1 = 0) | +| `tm_year` | Year (current year minus 1900) | -The converted character string is also adjusted according to the local time zone settings. For information about configuring the local time, see the [time](time-time32-time64.md), [_ftime](ftime-ftime32-ftime64.md), and [localtime](localtime-localtime32-localtime64.md) functions and the [_tzset](tzset.md) function for information about defining the time zone environment and global variables. +For information about configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For information about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function. -The string result produced by **asctime** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The newline character and the null character occupy the last two positions of the string. **asctime** uses a single, statically allocated buffer to hold the return string. Each call to this function destroys the result of the previous call. +The string result produced by **`asctime`** contains exactly 26 characters and has the form `Wed Jan 2 02:03:55 1980\n\0`. A 24-hour clock is used. All fields have a constant width. The newline character and the null character occupy the last two positions of the string. **`asctime`** uses a single, statically allocated buffer to hold the return string. Each call to this function destroys the result of the previous call. -**_wasctime** is a wide-character version of **asctime**. **_wasctime** and **asctime** behave identically otherwise. +**`_wasctime`** is a wide-character version of **`asctime`**, and otherwise behaves identically to **`asctime`**. -These functions validate their parameters. If *timeptr* is a null pointer, or if it contains out-of-range values, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **NULL** and sets **errno** to **EINVAL**. +These functions validate their parameters. If *`timeptr`* is a null pointer, or if it contains out-of-range values, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mapping +### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tasctime**|**asctime**|**asctime**|**_wasctime**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tasctime` | **`asctime`** | **`asctime`** | **`_wasctime`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**asctime**|\| -|**_wasctime**|\ or \| +| Routine | Required header | +|---|---| +| **`asctime`** | `` | +| **`_wasctime`** | `` or `` | ## Example -This program places the system time in the long integer **aclock**, translates it into the structure **newtime** and then converts it to string form for output, using the **asctime** function. +This program places the system time in the long integer `aclock`, translates it into the structure `newtime`, and then converts it to string form for output using the **`asctime`** function. ```C // crt_asctime.c @@ -109,11 +109,11 @@ Current date and time: Sun Feb 3 11:38:58 2002 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
+[Time management](../time-management.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md) diff --git a/docs/c-runtime-library/reference/asin-asinf-asinl.md b/docs/c-runtime-library/reference/asin-asinf-asinl.md index 4a3dd698671..0e7495e47af 100644 --- a/docs/c-runtime-library/reference/asin-asinf-asinl.md +++ b/docs/c-runtime-library/reference/asin-asinf-asinl.md @@ -1,9 +1,9 @@ --- title: "asin, asinf, asinl" description: "API reference for asin, asinf, and asinl; which calculate the arcsine of a floating-point value." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["asinf", "asinl", "asin", "_o_asin", "_o_asinf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["asin", "asinl", "asinf"] @@ -19,7 +19,7 @@ Calculates the arcsine. double asin( double x ); float asinf ( float x ); long double asinl( long double x ); -#define asin(X) // Requires C11 or higher +#define asin(X) // Requires C11 or later float asin( float x ); // C++ only long double asin( long double x ); // C++ only @@ -30,32 +30,32 @@ long double asin( long double x ); // C++ only *`x`*\ Value whose arcsine is to be calculated. -## Return Value +## Return value The **`asin`** function returns the arcsine (the inverse sine function) of *`x`* in the range -π/2 to π/2 radians. By default, if *`x`* is less than -1 or greater than 1, **`asin`** returns an indefinite. -|Input|SEH exception|Matherr exception| -|-----------|-------------------|-----------------------| -|`± ∞`|**`INVALID`**|**`_DOMAIN`**| -|`± QNAN`, `IND`|none|**`_DOMAIN`**| -|`|x| > 1`|**`INVALID`**|**`_DOMAIN`**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF | `INVALID` | `_DOMAIN` | +| ± QNaN, IND | none | `_DOMAIN` | +| `|x| > 1` | `INVALID` | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`asin`** with **`float`** and **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`asin`** always takes and returns a **`double`**. -If you use the `` `asin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `asin` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------|-| -|**`asin`**, **`asinf`**, **`asinl`**|``|`` or ``| -|**`asin()`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`asin`**, **`asinf`**, **`asinl`** | `` | `` or `` | +| **`asin`** macro | `` | | ## Example @@ -63,7 +63,7 @@ For more information, see [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ diff --git a/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md b/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md index ae062b5df93..8501e27ac0f 100644 --- a/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md +++ b/docs/c-runtime-library/reference/asinh-asinhf-asinhl.md @@ -1,16 +1,15 @@ --- title: "asinh, asinhf, asinhl" description: "API reference for asinh, asinhf, and asinhl; which calculate the inverse hyperbolic sine of a floating-point value." -ms.date: "08/31/2020" +ms.date: 08/31/2020 api_name: ["asinh", "asinhf", "asinhl", "_o_asinh", "_o_asinhf", "_o_asinhl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["asinhf", "asinhl", "asinh"] helpviewer_keywords: ["asinh function", "asinhl function", "asinhf function"] -ms.assetid: 4488babe-1a7e-44ca-8b7b-c2db0a70084f --- -# asinh, asinhf, asinhl +# `asinh`, `asinhf`, `asinhl` Calculates the inverse hyperbolic sine. @@ -20,7 +19,7 @@ Calculates the inverse hyperbolic sine. double asinh( double x ); float asinhf( float x ); long double asinhl( long double x ); -#define asinh(X) // Requires C11 or higher +#define asinh(X) // Requires C11 or later float asinh( float x ); // C++ only long double asinh( long double x ); // C++ only @@ -28,33 +27,33 @@ long double asinh( long double x ); // C++ only ### Parameters -*x*
+*`x`*\ Floating-point value. -## Return Value +## Return value -The **asinh** functions return the inverse hyberbolic sine (arc hyperbolic sine) of *x*. This function is valid over the floating-point domain. If *x* is a quiet NaN, indefinite, or infinity, the same value is returned. +The **`asinh`** functions return the inverse hyperbolic sine (arc hyperbolic sine) of *`x`*. This function is valid over the floating-point domain. If *`x`* is a quiet NaN, indefinite, or infinity, the same value is returned. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± QNAN, IND, INF|none|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND, INF | none | none | ## Remarks -When you use C++, you can call overloads of **asinh** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **asinh** always takes and returns **`double`**. +When you use C++, you can call overloads of **`asinh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`asinh`** always takes and returns **`double`**. -If you use the \ `asinh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `asinh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required C header|Required C++ header| -|--------------|--------------|------------------| -|**asinh**, **asinhf**, **asinhl**|\|\ or \| -|**asinh()** macro | \ || +| Function | Required C header | Required C++ header | +|---|---|---| +| **`asinh`**, **`asinhf`**, **`asinhl`** | \ | \ or \ | +| **asinh()** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For additional compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -86,9 +85,9 @@ asinh( 0.868671 ) = 0.785398 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[acosh, acoshf, acoshl](acosh-acoshf-acoshl.md)
-[atanh, atanhf, atanhl](atanh-atanhf-atanhl.md)
-[cosh, coshf, coshl](cosh-coshf-coshl.md)
-[sinh, sinhf, sinhl](sinh-sinhf-sinhl.md)
-[tanh, tanhf, tanhl](tanh-tanhf-tanhl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ +[`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ +[`cosh`, `coshf`, `coshl`](cosh-coshf-coshl.md)\ +[`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md)\ +[`tanh`, `tanhf`, `tanhl`](tanh-tanhf-tanhl.md) diff --git a/docs/c-runtime-library/reference/assert-asserte-assert-expr-macros.md b/docs/c-runtime-library/reference/assert-asserte-assert-expr-macros.md index 039ed8901f4..b728bbd517c 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 @@ -1,7 +1,7 @@ --- -description: "Learn more about: _ASSERT, _ASSERTE, _ASSERT_EXPR Macros" title: "_ASSERT, _ASSERTE, _ASSERT_EXPR Macros" -ms.date: "11/04/2016" +description: "Learn more about: _ASSERT, _ASSERTE, _ASSERT_EXPR Macros" +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"] @@ -10,7 +10,7 @@ helpviewer_keywords: ["debugging [CRT], using macros", "_ASSERTE macro", "macros --- # `_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` Macros -Evaluate an expression and generate a debug report when the result is **`False`** (debug version only). +Evaluate an expression and generate a debug report when the result is **`false`** (debug version only). ## Syntax @@ -31,39 +31,39 @@ A wide string to display as part of the report. ## Remarks -The **`_ASSERT_EXPR`**, **`_ASSERT`** and **`_ASSERTE`** macros provide an application with a clean and simple mechanism for checking assumptions during the debugging process. They're very flexible because they don't need to be enclosed in `#ifdef` statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [`_DEBUG`](../../c-runtime-library/debug.md) macro. **`_ASSERT_EXPR`**, **`_ASSERT`** and **`_ASSERTE`** are only available when **`_DEBUG`** is defined at compile time. When **`_DEBUG`** isn't defined, calls to these macros are removed during preprocessing. +The `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` macros provide an application with a clean and simple mechanism for checking assumptions during the debugging process. They're flexible because they don't need to be enclosed in `#ifdef` statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [`_DEBUG`](../debug.md) macro. `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` are only available when `_DEBUG` is defined at compile time. When `_DEBUG` isn't defined, calls to these macros are removed during preprocessing. -**`_ASSERT_EXPR`**, **`_ASSERT`** and **`_ASSERTE`** evaluate their *`booleanExpression`* argument and when the result is **`false`** (0), they print a diagnostic message and call [`_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md) to generate a debug report. The **`_ASSERT`** macro prints a simple diagnostic message, **`_ASSERTE`** includes a string representation of the failed expression in the message, and **`_ASSERT_EXPR`** includes the *`message`* string in the diagnostic message. These macros do nothing when *`booleanExpression`* evaluates to nonzero. +`_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` evaluate their *`booleanExpression`* argument and when the result is **`false`** (0), they print a diagnostic message and call [`_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md) to generate a debug report. The `_ASSERT` macro prints a simple diagnostic message, `_ASSERTE` includes a string representation of the failed expression in the message, and `_ASSERT_EXPR` includes the *`message`* string in the diagnostic message. These macros do nothing when *`booleanExpression`* evaluates to nonzero. -**`_ASSERT_EXPR`**, **`_ASSERT`** and **`_ASSERTE`** invoke **`_CrtDbgReportW`**, which causes all output to be in wide characters. **`_ASSERTE`** properly prints Unicode characters in *`booleanExpression`* and **`_ASSERT_EXPR`** prints Unicode characters in *`message`*. +`_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` invoke `_CrtDbgReportW`, which causes all output to be in wide characters. `_ASSERTE` properly prints Unicode characters in *`booleanExpression`* and `_ASSERT_EXPR` prints Unicode characters in *`message`*. -Because the **`_ASSERTE`** macro specifies the failed expression, and **`_ASSERT_EXPR`** lets you specify a message in the generated report, they enable users to identify the problem without referring to the application source code. However, a disadvantage exists in that every *`message`* printed by **`_ASSERT_EXPR`** and every expression evaluated by **`_ASSERTE`** is included in the output (debug version) file of your application as a string constant. Therefore, if a large number of calls are made to **`_ASSERT_EXPR`** or **`_ASSERTE`**, these expressions can greatly increase the size of your output file. +Because the `_ASSERTE` macro specifies the failed expression, and `_ASSERT_EXPR` lets you specify a message in the generated report, they enable users to identify the problem without referring to the application source code. However, a disadvantage exists in that every *`message`* printed by `_ASSERT_EXPR` and every expression evaluated by `_ASSERTE` is included in the output (debug version) file of your application as a string constant. Therefore, if a large number of calls are made to `_ASSERT_EXPR` or `_ASSERTE`, these expressions can greatly increase the size of your output file. Unless you specify otherwise with the [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions, messages appear in a pop-up dialog box equivalent to setting: ```C -_CrtSetReportMode(CRT_ASSERT, _CRTDBG_MODE_WNDW); -```` +_CrtSetReportMode(_CRT_ASSERT, _CRTDBG_MODE_WNDW); +``` -**`_CrtDbgReportW`** generates the debug report and determines its destination or destinations, based on the current report mode or modes and file defined for the **`_CRT_ASSERT`** report type. By default, assertion failures and errors are directed to a debug message window. The [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions are used to define the destinations for each report type. +`_CrtDbgReportW` generates the debug report and determines its destination or destinations, based on the current report mode or modes and file defined for the `_CRT_ASSERT` report type. By default, assertion failures and errors are directed to a debug message window. The [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions are used to define the destinations for each report type. -When the destination is a debug message window and the user selects the **Retry** button, **`_CrtDbgReportW`** returns 1, causing the **`_ASSERT_EXPR`**, **`_ASSERT`** and **`_ASSERTE`** macros to start the debugger provided that just-in-time (JIT) debugging is enabled. +When the destination is a debug message window and the user selects the **Retry** button, `_CrtDbgReportW` returns 1, causing the `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` macros to start the debugger if just-in-time (JIT) debugging is enabled. -For more information about the reporting process, see the [`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md) function. For more information about resolving assertion failures and using these macros as a debugging error handling mechanism, see [Using Macros for Verification and Reporting](/visualstudio/debugger/macros-for-reporting). +For more information about the reporting process, see the [`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md) function. For more information about resolving assertion failures and using these macros as a debugging error handling mechanism, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). -In addition to the **`_ASSERT`** macros, the [`assert`](assert-macro-assert-wassert.md) macro can be used to verify program logic. This macro is available in both the debug and release versions of the libraries. The [`_RPT`, `_RPTF`](rpt-rptf-rptw-rptfw-macros.md) debug macros are also available for generating a debug report, but they 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. +In addition to the `_ASSERT` macros, the [`assert`](assert-macro-assert-wassert.md) macro can be used to verify program logic. This macro is available in both the debug and release versions of the libraries. The [`_RPT`, `_RPTF`](rpt-rptf-rptw-rptfw-macros.md) debug macros are also available for generating a debug report, but they don't evaluate an expression. The `_RPT` macros generate a simple report. The `_RPTF` macros include the source file and line number where the report macro was called in the generated report. Wide character versions of these macros are available (`_RPTW`, `_RPTFW`). The wide character versions are identical to the narrow character versions except that wide character strings are used for all string parameters and output. -Although **`_ASSERT_EXPR`**, **`_ASSERT`** and **`_ASSERTE`** are macros and are available by including ``, the application must link with a debug version of the C run-time library when **`_DEBUG`** is defined because these macros call other run-time functions. +Although `_ASSERT_EXPR`, `_ASSERT` and `_ASSERTE` are macros and are available by including ``, the application must link with a debug version of the C run-time library when `_DEBUG` is defined because these macros call other run-time functions. ## Requirements -|Macro|Required header| -|-----------|---------------------| -|**`_ASSERT_EXPR`**, **`_ASSERT`**, **`_ASSERTE`**|``| +| Macro | Required header | +|---|---| +| `_ASSERT_EXPR`, `_ASSERT`, `_ASSERTE` | `` | ## Example -In this program, calls are made to the **`_ASSERT`** and **`_ASSERTE`** macros to test the condition `string1 == string2`. If the condition fails, these macros print a diagnostic message. The **`_RPT`** and **`_RPTF`** group of macros is also exercised in this program, as an alternative to the **`printf`** function. +In this program, calls are made to the `_ASSERT` and `_ASSERTE` macros to test the condition `string1 == string2`. If the condition fails, these macros print a diagnostic message. The `_RPT` and `_RPTF` group of macros is also exercised in this program, as an alternative to the **`printf`** function. ```C // crt_ASSERT_macro.c @@ -139,6 +139,6 @@ crt_ASSERT_macro.c(59) : Assertion failed: p1 == p2 ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)\ +[Debug routines](../debug-routines.md)\ [`assert` Macro, `_assert`, `_wassert`](assert-macro-assert-wassert.md)\ [`_RPT`, `_RPTF`, `_RPTW`, `_RPTFW` Macros](rpt-rptf-rptw-rptfw-macros.md) diff --git a/docs/c-runtime-library/reference/assert-macro-assert-wassert.md b/docs/c-runtime-library/reference/assert-macro-assert-wassert.md index 38e959d001c..116c8c986c0 100644 --- a/docs/c-runtime-library/reference/assert-macro-assert-wassert.md +++ b/docs/c-runtime-library/reference/assert-macro-assert-wassert.md @@ -10,7 +10,7 @@ f1_keywords: ["assert", "_assert", "_wassert", "assert/_wassert"] helpviewer_keywords: ["aborting programs", "assert function", "assert macro"] ms.assetid: a9ca031a-648b-47a6-bdf1-65fc7399dd40 --- -# `assert` Macro, `_assert`, `_wassert` +# `assert` macro, `_assert`, `_wassert` Evaluates an expression and, when the result is **`false`**, prints a diagnostic message and aborts the program. @@ -34,53 +34,53 @@ void _wassert( ### Parameters -*`expression`*
+*`expression`*\ A scalar expression (including pointer expressions) that evaluates to nonzero (**`true`**) or 0 (**`false`**). -*`message`*
+*`message`*\ The message to display. -*`filename`*
+*`filename`*\ The name of the source file the assertion failed in. -*`line`*
+*`line`*\ The line number in the source file of the failed assertion. ## Remarks -The `assert` macro is typically used to identify logic errors during program development. Use it to stop program execution when unexpected conditions occur by implementing the *`expression`* argument to evaluate to **`false`** only when the program is operating incorrectly. Assertion checks can be turned off at compile time by defining the macro **`NDEBUG`**. You can turn off the `assert` macro without modifying your source files by using a **`/DNDEBUG`** command-line option. You can turn off the `assert` macro in your source code by using a `#define NDEBUG` directive before `` is included. +The `assert` macro is typically used to identify logic errors during program development. Use it to stop program execution when unexpected conditions occur by implementing the *`expression`* argument to evaluate to **`false`** only when the program is operating incorrectly. Assertion checks can be turned off at compile time by defining the macro `NDEBUG`. You can turn off the `assert` macro without modifying your source files by using a **`/DNDEBUG`** command-line option. You can turn off the `assert` macro in your source code by using a `#define NDEBUG` directive before `` is included. The `assert` macro prints a diagnostic message when *`expression`* evaluates to **`false`** (0) and calls [`abort`](abort.md) to stop program execution. No action is taken if *`expression`* is **`true`** (nonzero). The diagnostic message includes the failed expression, the name of the source file and line number where the assertion failed. The diagnostic message is printed in wide (`wchar_t`) characters. Therefore, it will work as expected even if there are Unicode characters in the expression. -The destination of the diagnostic message depends on the type of application that called the routine. Console applications receive the message through **`stderr`**. In a Windows-based application, `assert` calls the Windows [`MessageBox`](/windows/win32/api/winuser/nf-winuser-messagebox) function to create a message box to display the message with three buttons: **Abort**, **Retry**, and **Ignore**. If the user clicks **Abort**, the program aborts immediately. If the user clicks **Retry**, the debugger is called and the user can debug the program if just-in-time (JIT) debugging is enabled. If the user clicks **Ignore**, the program will continue with normal execution. Clicking **Ignore** when an error condition exists can result in undefined behavior since preconditions of the calling code weren't met. +The destination of the diagnostic message depends on the type of application that called the routine. Console applications receive the message through **`stderr`**. In a Windows-based application, `assert` calls the Windows [`MessageBox`](/windows/win32/api/winuser/nf-winuser-messagebox) function to create a message box to display the message with three buttons: **Abort**, **Retry**, and **Ignore**. If the user chooses **Abort**, the program aborts immediately. If the user chooses **Retry**, the debugger is called, and the user can debug the program if just-in-time (JIT) debugging is enabled. If the user chooses **Ignore**, the program will continue with normal execution. Clicking **Ignore** when an error condition exists can result in undefined behavior since preconditions of the calling code weren't met. To override the default output behavior regardless of the app type, call [`_set_error_mode`](set-error-mode.md) to select between the output-to-stderr and display-dialog-box behavior. -After `assert` displays its message, it calls [`abort`](abort.md), which displays a dialog box with **Abort**, **Retry**, and **Ignore** buttons. [`abort`](abort.md) exits the program, so the **Retry** and **Ignore** button won't resume program execution following the `assert` call. If `assert` displayed a dialog box, the [`abort`](abort.md) dialog box isn't shown. The only time the [`abort`](abort.md) dialog box is shown is when `assert` sends its output to stderr. +After `assert` displays its message, it calls [`abort`](abort.md), which displays a dialog box with **Abort**, **Retry**, and **Ignore** buttons. [`abort`](abort.md) exits the program, so the **Retry** and **Ignore** button won't resume program execution following the `assert` call. If `assert` displayed a dialog box, the [`abort`](abort.md) dialog box isn't shown. The only time the [`abort`](abort.md) dialog box is shown, is when `assert` sends its output to stderr. As a consequence of the above behavior, a dialog box is always displayed following an `assert` call in debug mode. The behavior of each button is captured in the below table. -|Error mode|Output to `stderr` (Console/`_OUT_TO_STDERR`)|Display Dialog Box (Windows/`_OUT_TO_MSGBOX`)| -|----------|----------------|------------------| -|`Abort`|Exit immediately with exit code 3|Exit immediately with exit code 3| -|`Retry`|Break into debugger during `abort`|Break into debugger during `assert`| -|`Ignore`|Finish exiting via `abort`|Continue program as though the assert didn't fire (may result in undefined behavior since preconditions of the calling code weren't met)| +| Error mode | Output to `stderr` (Console/`_OUT_TO_STDERR`) | Display Dialog Box (Windows/`_OUT_TO_MSGBOX`) | +|---|---|---| +| `Abort` | Exit immediately with exit code 3 | Exit immediately with exit code 3 | +| `Retry` | Break into debugger during `abort` | Break into debugger during `assert` | +| `Ignore` | Finish exiting via `abort` | Continue program as though `assert` didn't fire (may result in undefined behavior since preconditions of the calling code weren't met) | -For more information about CRT debugging, see [CRT Debugging Techniques](/visualstudio/debugger/crt-debugging-techniques). +For more information about CRT debugging, see [CRT debugging techniques](../crt-debugging-techniques.md). The `_assert` and `_wassert` functions are internal CRT functions. They help minimize the code required in your object files to support assertions. We don't recommend that you call these functions directly. -The `assert` macro is enabled in both the release and debug versions of the C run-time libraries when **`NDEBUG`** isn't defined. When **`NDEBUG`** is defined, the macro is available but doesn't evaluate its argument and has no effect. When it's enabled, the `assert` macro calls `_wassert` for its implementation. Other assertion macros, [`_ASSERT`](assert-asserte-assert-expr-macros.md), [`_ASSERTE`](assert-asserte-assert-expr-macros.md) and [`_ASSERT_EXPR`](assert-asserte-assert-expr-macros.md), are also available, but they only evaluate the expressions passed to them when the [`_DEBUG`](../../c-runtime-library/debug.md) macro has been defined and when they are in code linked with the debug version of the C run-time libraries. +The `assert` macro is enabled in both the release and debug versions of the C run-time libraries when `NDEBUG` isn't defined. When `NDEBUG` is defined, the macro is available, but doesn't evaluate its argument and has no effect. When it's enabled, the `assert` macro calls `_wassert` for its implementation. Other assertion macros, [`_ASSERT`](assert-asserte-assert-expr-macros.md), [`_ASSERTE`](assert-asserte-assert-expr-macros.md) and [`_ASSERT_EXPR`](assert-asserte-assert-expr-macros.md), are also available, but they only evaluate the expressions passed to them when the [`_DEBUG`](../debug.md) macro has been defined and when they are in code linked with the debug version of the C run-time libraries. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`assert`, `_wassert`|``| +| Routine | Required header | +|---|---| +| `assert`, `_wassert` | `` | -The signature of the `_assert` function isn't available in a header file. The signature of the `_wassert` function is only available when the **`NDEBUG`** macro isn't defined. +The signature of the `_assert` function isn't available in a header file. The signature of the `_wassert` function is only available when the `NDEBUG` macro isn't defined. ## Example @@ -135,10 +135,10 @@ If a debugger is installed, choose the **Debug** button to start the debugger, o ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[`abort`](abort.md)
-[`raise`](raise.md)
-[`signal`](signal.md)
-[`_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` Macros](assert-asserte-assert-expr-macros.md)
-[`_DEBUG`](../../c-runtime-library/debug.md)
+[Error handling](../error-handling-crt.md)\ +[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`raise`](raise.md)\ +[`signal`](signal.md)\ +[`_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` Macros](assert-asserte-assert-expr-macros.md)\ +[`_DEBUG`](../debug.md) diff --git a/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md b/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md index 3d6bf584cd0..91fc052f9a7 100644 --- a/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md +++ b/docs/c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md @@ -1,9 +1,9 @@ --- title: "atan, atanf, atanl, atan2, atan2f, atan2l" description: "API reference for atan, atanf, atanl, atan2, atan2f, and atan2l; which calculate the arctangent of a floating-point value." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["atan2f", "atan2l", "atan2", "atanf", "atan", "atanl", "_o_atan", "_o_atan2", "_o_atan2f", "_o_atanf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["atan", "atan2l", "atan2", "atanl", "atanf", "atan2f"] @@ -19,7 +19,7 @@ Calculates the arctangent of **`x`** (**`atan`**, **`atanf`**, and **`atanl`**) double atan( double x ); float atanf( float x ); long double atanl( long double x ); -#define atan(X) // Requires C11 or higher +#define atan(X) // Requires C11 or later float atan( float x ); // C++ only long double atan( long double x ); // C++ only @@ -27,7 +27,7 @@ long double atan( long double x ); // C++ only double atan2( double y, double x ); float atan2f( float y, float x ); long double atan2l( long double y, long double x ); -#define atan2(Y, X) // Requires C11 or higher +#define atan2(Y, X) // Requires C11 or later float atan2( float y, float x ); // C++ only long double atan2( long double y, long double x ); // C++ only @@ -38,34 +38,34 @@ long double atan2( long double y, long double x ); // C++ only *`x`*, *`y`*\ Any numbers. -## Return Value +## Return value **`atan`** returns the arctangent of *`x`* in the range -π/2 to π/2 radians. **`atan2`** returns the arctangent of *`y`*/*`x`* in the range -π to π radians. If *`x`* is 0, **`atan`** returns 0. If both parameters of **`atan2`** are 0, the function returns 0. All results are in radians. **`atan2`** uses the signs of both parameters to determine the quadrant of the return value. -|Input|SEH exception|Matherr exception| -|-----------|-------------------|-----------------------| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks The **`atan`** function calculates the arctangent (the inverse tangent function) of *`x`*. **`atan2`** calculates the arctangent of *`y`*/*`x`* (if *`x`* equals 0, **`atan2`** returns π/2 if *`y`* is positive, -π/2 if *`y`* is negative, or 0 if *`y`* is 0.) -If you use the `` `atan()` or `atan2()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `atan` or `atan2` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. **`atan`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md). Because C++ allows overloading, you can call overloads of **`atan`** and **`atan2`** that take **`float`** or **`long double`** arguments. In a C program, unless you're using the `` macro to call this function, **`atan`** and **`atan2`** always take **`double`** arguments and return a **`double`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------|-| -|**`atan`**, **`atan2`**, **`atanf`**, **`atan2f`**, **`atanl`**, **`atan2l`**|``|`` or ``| -|**`atan()`**, **`atan2`** macros | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`atan`**, **`atan2`**, **`atanf`**, **`atan2f`**, **`atanl`**, **`atan2l`** | `` | `` or `` | +| **`atan`**, **`atan2`** macros | `` | | ## Example @@ -100,12 +100,12 @@ Arctangent of 0.500000 / 5.000000: 0.099669 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ [`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ [`_matherr`](matherr.md)\ [`sin`, `sinf`, `sinl`](sin-sinf-sinl.md)\ [`tan`, `tanf`, `tanl`](tan-tanf-tanl.md)\ -[`_CIatan`](../../c-runtime-library/ciatan.md)\ -[`_CIatan2`](../../c-runtime-library/ciatan2.md) +[`_CIatan`](../ciatan.md)\ +[`_CIatan2`](../ciatan2.md) diff --git a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md index 5986cbb41b6..02ebb06caf3 100644 --- a/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md +++ b/docs/c-runtime-library/reference/atanh-atanhf-atanhl.md @@ -1,16 +1,15 @@ --- title: "atanh, atanhf, atanhl" description: "API reference for atanh, atanhf, and atanhl; which calculate the inverse hyperbolic tangent of a floating-point value." -ms.date: "08/31/2020" +ms.date: 08/31/2020 api_name: ["atanhl", "atanhf", "atanh", "_o_atanh", "_o_atanhf", "_o_atanhl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["atanhl", "atanhf", "atanh"] -helpviewer_keywords: ["atanhf function", "atanhl function", "atanh funciton"] -ms.assetid: 83a43b5b-2580-4461-854f-dc84236d9f32 +helpviewer_keywords: ["atanhf function", "atanhl function", "atanh function"] --- -# atanh, atanhf, atanhl +# `atanh`, `atanhf`, `atanhl` Calculates the inverse hyperbolic tangent. @@ -20,7 +19,7 @@ Calculates the inverse hyperbolic tangent. double atanh( double x ); float atanhf( float x ); long double atanhl( long double x ); -#define atanh(X) // Requires C11 or higher +#define atanh(X) // Requires C11 or later float atanh( float x ); // C++ only long double atanh( long double x ); // C++ only @@ -28,34 +27,34 @@ long double atanh( long double x ); // C++ only ### Parameters -*x*\ +*`x`*\ Floating-point value. -## Return Value +## Return value -The **atanh** functions return the inverse hyberbolic tangent (arc hyperbolic tangent) of *x*. If *x* is greater than 1, or less than -1, **errno** is set to **EDOM** and the result is a quiet NaN. If *x* is equal to 1 or -1, a positive or negative infinity is returned, respectively, and **errno** is set to **ERANGE**. +The **`atanh`** functions return the inverse hyperbolic tangent (arc hyperbolic tangent) of *`x`*. If *`x`* is greater than 1, or less than -1, `errno` is set to `EDOM` and the result is a quiet NaN. If *`x`* is equal to 1 or -1, a positive or negative infinity is returned, respectively, and `errno` is set to `ERANGE`. -|Input|SEH Exception|**Matherr** Exception| -|-----------|-------------------|-------------------------| -|± QNAN,IND|none|none| -|*X* ≥ 1; *x* ≤ -1|none|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | none | +| *`X`* ≥ 1; *`x`* ≤ -1 | none | none | ## Remarks -Because C++ allows overloading, you can call overloads of **atanh** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **atanh** always takes and returns **`double`**. +Because C++ allows overloading, you can call overloads of **`atanh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`atanh`** always takes and returns **`double`**. -If you use the \ `atanh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `atanh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**atanh**, **atanhf**, **atanhl**|\|\ or \| -|**atanh()** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`atanh`**, **`atanhf`**, **`atanhl`** | \ | \ or \ | +| **`atanh`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,9 +86,9 @@ atanh( 0.655794 ) = 0.785398 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[acosh, acoshf, acoshl](acosh-acoshf-acoshl.md)
-[asinh, asinhf, asinhl](asinh-asinhf-asinhl.md)
-[cosh, coshf, coshl](cosh-coshf-coshl.md)
-[sinh, sinhf, sinhl](sinh-sinhf-sinhl.md)
-[tanh, tanhf, tanhl](tanh-tanhf-tanhl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ +[`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ +[`cosh`, `coshf`, `coshl`](cosh-coshf-coshl.md)\ +[`sinh`, `sinhf`, `sinhl`](sinh-sinhf-sinhl.md)\ +[`tanh`, `tanhf`, `tanhl`](tanh-tanhf-tanhl.md) diff --git a/docs/c-runtime-library/reference/atexit.md b/docs/c-runtime-library/reference/atexit.md index 428591dc53f..1264498d49f 100644 --- a/docs/c-runtime-library/reference/atexit.md +++ b/docs/c-runtime-library/reference/atexit.md @@ -26,13 +26,13 @@ int atexit( *`func`*\ Function to be called. -## Return Value +## Return value **`atexit`** returns 0 if successful, or a nonzero value if an error occurs. ## Remarks -The **`atexit`** function is passed the address of a function *`func`* to be called when the program terminates normally. Successive calls to **`atexit`** create a register of functions that are executed in last-in, first-out (LIFO) order. The functions passed to **`atexit`** can’t take parameters. **`atexit`** and **`_onexit`** use the heap to hold the register of functions. Thus, the number of functions that can be registered is limited only by heap memory. +The **`atexit`** function is passed the address of a function *`func`* to be called when the program terminates normally. Successive calls to **`atexit`** create a register of functions that are executed in last-in, first-out (LIFO) order. The functions passed to **`atexit`** can't take parameters. **`atexit`** and **`_onexit`** use the heap to hold the register of functions. Thus, the number of functions that can be registered is limited only by heap memory. The code in the **`atexit`** function shouldn't contain any dependency on any DLL that could have already been unloaded when the **`atexit`** function is called. @@ -40,9 +40,9 @@ To generate an ANSI-conformant application, use the ANSI-standard **`atexit`** f ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`atexit`**|``| +| Routine | Required header | +|---|---| +| **`atexit`** | `` | ## Example @@ -92,7 +92,7 @@ This is executed next. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`abort`](abort.md)\ [`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ [`_onexit`, `_onexit_m`](onexit-onexit-m.md) diff --git a/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md b/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md index e69575f0f87..d195860120a 100644 --- a/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md +++ b/docs/c-runtime-library/reference/atodbl-atodbl-l-atoldbl-atoldbl-l-atoflt-atoflt-l.md @@ -3,16 +3,16 @@ description: "Learn more about: _atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atofl title: "_atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l" ms.date: "4/2/2020" api_name: ["_atoldbl", "_atoldbl_l", "_atodbl", "_atoflt", "_atoflt_l", "_atodbl_l", "_o__atodbl", "_o__atodbl_l", "_o__atoflt", "_o__atoflt_l", "_o__atoldbl", "_o__atoldbl_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_atoflt", "_atoflt_l", "atodbl_l", "atoflt_l", "_atoldbl", "_atoldbl_l", "atodbl", "_atodbl_l", "atoldbl", "atoflt", "atoldbl_l", "_atodbl"] helpviewer_keywords: ["_atodbl function", "_atoldbl_l function", "atoflt function", "atoflt_l function", "atoldbl function", "_atoldbl function", "atodbl_l function", "_atoflt_l function", "atoldbl_l function", "atodbl function", "string conversion, to floating point values", "_atoflt function", "_atodbl_l function"] ms.assetid: 2d2530f4-4bd4-42e3-8083-f2d2fbc8432a --- -# _atodbl, _atodbl_l, _atoldbl, _atoldbl_l, _atoflt, _atoflt_l +# `_atodbl`, `_atodbl_l`, `_atoldbl`, `_atoldbl_l`, `_atoflt`, `_atoflt_l` -Converts a string to a double (**_atodbl**), long double (**_atoldbl**), or float (**_atoflt**). +Converts a string to a double (**`_atodbl`**), long double (**`_atoldbl`**), or float (**`_atoflt`**). ## Syntax @@ -27,34 +27,34 @@ int _atoflt_l( _CRT_FLOAT * value, const char * str, _locale_t locale ); ### Parameters -*value*
+*`value`*\ The double, long double, or float value that's produced by converting the string to a floating-point value. These values are wrapped in a structure. -*str*
+*`str`*\ The string to be parsed to convert into a floating-point value. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns 0 if successful. Possible error codes are **_UNDERFLOW** or **_OVERFLOW**, which are defined in the header file \. +Returns 0 if successful. Possible error codes are `_UNDERFLOW` or `_OVERFLOW`, which are defined in the header file \. ## Remarks -These functions convert a string to a floating-point value. The difference between these functions and the **atof** family of functions is that these functions do not generate floating-point code and do not cause hardware exceptions. Instead, error conditions are reported as error codes. +These functions convert a string to a floating-point value. The difference between these functions and the `atof` family of functions is that these functions don't generate floating-point code and don't cause hardware exceptions. Instead, error conditions are reported as error codes. -If a string does not have a valid interpretation as a floating-point value, *value* is set to zero and the return value is zero. +If a string doesn't have a valid interpretation as a floating-point value, *`value`* is set to zero, and the return value is zero. -The versions of these functions that have the **_l** suffix are identical the versions that don't have the suffix, except that they use the *locale* parameter that's passed in instead of the current thread locale. +The versions of these functions that have the `_l` suffix are identical the versions that don't have the suffix, except that they use the *`locale`* parameter that's passed in instead of the current thread locale. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routines|Required header| -|--------------|---------------------| -|**_atodbl**, **_atoldbl**, **_atoflt**

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

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

**`_DN_FLUSH`**|0x00000000

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

**`_EM_DENORMAL`**

**`_EM_ZERODIVIDE`**

**`_EM_OVERFLOW`**

**`_EM_UNDERFLOW`**

**`_EM_INEXACT`**|0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

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

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

**`_IC_PROJECTIVE`**|0x00040000

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

**`_RC_UP`**

**`_RC_DOWN`**

**`_RC_NEAR`**|0x00000300

0x00000200

0x00000100

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

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

**`_PC_53`** (53 bits)

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

0x00010000

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

`_DN_FLUSH` | 0x00000000

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

`_EM_DENORMAL`

`_EM_ZERODIVIDE`

`_EM_OVERFLOW`

`_EM_UNDERFLOW`

`_EM_INEXACT` | 0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

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

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

`_IC_PROJECTIVE` | 0x00040000

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

`_RC_UP`

`_RC_DOWN`

`_RC_NEAR` | 0x00000300

0x00000200

0x00000100

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

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

`_PC_53` (53 bits)

`_PC_64` (64 bits) | 0x00020000

0x00010000

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

**`_DN_FLUSH`**|0x00000000

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

**`_EM_DENORMAL`**

**`_EM_ZERODIVIDE`**

**`_EM_OVERFLOW`**

**`_EM_UNDERFLOW`**

**`_EM_INEXACT`**|0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

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

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

**`_IC_PROJECTIVE`**|0x00040000

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

**`_RC_UP`**

**`_RC_DOWN`**

**`_RC_NEAR`**|0x00000300

0x00000200

0x00000100

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

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

**`_PC_53`** (53 bits)

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

0x00010000

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

`_DN_FLUSH` | 0x00000000

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

`_EM_DENORMAL`

`_EM_ZERODIVIDE`

`_EM_OVERFLOW`

`_EM_UNDERFLOW`

`_EM_INEXACT` | 0x00000010

0x00080000

0x00000008

0x00000004

0x00000002

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

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

`_IC_PROJECTIVE` | 0x00040000

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

`_RC_UP`

`_RC_DOWN`

`_RC_NEAR` | 0x00000300

0x00000200

0x00000100

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

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

`_PC_53` (53 bits)

`_PC_64` (64 bits) | 0x00020000

0x00010000

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

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

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

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

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

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

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

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

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

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

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

1 **`_CRTDBG_MODE_FILE`**

2 **`_CRTDBG_MODE_DEBUG`**

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

1 `_CRTDBG_MODE_FILE`

2 `_CRTDBG_MODE_DEBUG`

4 `_CRTDBG_MODE_WNDW` | -Each report type can be reported using one, two, or three modes or no mode at all. Therefore, it is possible to have more than one destination defined for a single report type. For example, the following code fragment causes assertion failures to be sent to both a debug message window and to **`stderr`**: +Each report type can be reported using one, two, or three modes or no mode at all. Therefore, it's possible to have more than one destination defined for a single report type. For example, the following code fragment causes assertion failures to be sent to both a debug message window and to **`stderr`**: ```C _CrtSetReportMode( _CRT_ASSERT, _CRTDBG_MODE_FILE | _CRTDBG_MODE_WNDW ); _CrtSetReportFile( _CRT_ASSERT, _CRTDBG_FILE_STDERR ); ``` -In addition, the reporting mode or modes for each report type can be separately controlled. For example, it is possible to specify that a *`reportType`* of **`_CRT_WARN`** be sent to an output debug string, while **`_CRT_ASSERT`** be displayed using a debug message window and sent to **`stderr`**, as previously illustrated. +In addition, you can control the reporting mode or modes for each report type separately. For example, it's possible to specify that a *`reportType`* of `_CRT_WARN` goes to an output debug string, while `_CRT_ASSERT` is displayed using a debug message window and is sent to **`stderr`**, as previously illustrated. ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_CrtSetReportMode`**|``|``| +| Routine | Required header | Optional header | +|---|---|---| +| **`_CrtSetReportMode`** | `` | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** Debug versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md) only. +**Libraries:** Debug versions of the [C runtime libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md) +[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md b/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md index 989fb1faea7..a28d6c58c60 100644 --- a/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md +++ b/docs/c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md @@ -10,12 +10,12 @@ f1_keywords: ["_cwscanf", "cwscanf_l", "tcscanf_l", "_tcscanf_l", "_cscanf", "_c helpviewer_keywords: ["_cwscanf function", "data [C++], reading from the console", "cscanf_l function", "tcscanf function", "_cscanf_l function", "cwscanf function", "_tcscanf_l function", "_cscanf function", "_tcscanf function", "cwscanf_l function", "tcscanf_l function", "reading data [C++], from the console", "_cwscanf_l function"] ms.assetid: dbfe7547-b577-4567-a1cb-893fa640e669 --- -# _cscanf, _cscanf_l, _cwscanf, _cwscanf_l +# `_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l` -Reads formatted data from the console. More secure versions of these functions are available; see [_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md). +Reads formatted data from the console. More secure versions of these functions are available; see [`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md). > [!NOTE] -> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see *LNK2019* in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). +> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see Linker Error LNK2019 in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -45,42 +45,42 @@ int _cwscanf_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional parameters. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -The number of fields that were successfully converted and assigned. The return value does not include fields that were read but not assigned. The return value is **EOF** for an attempt to read at end of file. This can occur when keyboard input is redirected at the operating-system command-line level. A return value of 0 means that no fields were assigned. +The number of fields that were successfully converted and assigned. The return value doesn't include fields that were read but not assigned. The return value is `EOF` for an attempt to read at end of file. An `EOF` can also be returned when keyboard input is redirected at the operating-system command-line level. A return value of zero means that no fields were assigned. ## Remarks -The **_cscanf** function reads data directly from the console into the locations given by *argument*. The [_getche](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *format*. The format controls the interpretation of the input fields and has the same form and function as the *format* parameter for the [scanf](scanf-scanf-l-wscanf-wscanf-l.md) function. While **_cscanf** normally echoes the input character, it does not do so if the last call was to **_ungetch**. +The **`_cscanf`** function reads data directly from the console into the locations given by *`argument`*. The [`_getche`](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *`format`*. The format controls the interpretation of the input fields and has the same form and function as the *`format`* parameter for the [`scanf`](scanf-scanf-l-wscanf-wscanf-l.md) function. While **`_cscanf`** normally echoes the input character, it doesn't do so if the last call was to `_ungetch`. -This function validates its parameters. If format is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **EOF**. +This function validates its parameters. If format is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `EOF`. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcscanf**|**_cscanf**|**_cscanf**|**_cwscanf**| -|**_tcscanf_l**|**_cscanf_l**|**_cscanf_l**|**_cwscanf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscanf` | **`_cscanf`** | **`_cscanf`** | **`_cwscanf`** | +| `_tcscanf_l` | **`_cscanf_l`** | **`_cscanf_l`** | **`_cwscanf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cscanf**, **_cscanf_l**|\| -|**_cwscanf**, **_cwscanf_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_cscanf`**, **`_cscanf_l`** | \ | +| **`_cwscanf`**, **`_cwscanf_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -121,8 +121,8 @@ You entered 3 2 1 ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) diff --git a/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md b/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md index dd471dbac61..7ca544e88b7 100644 --- a/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md +++ b/docs/c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l" title: "_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l" -ms.date: "11/04/2016" +description: "Learn more about: _cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l" +ms.date: 11/04/2016 api_name: ["_cwscanf_s_l", "_cwscanf_s", "_cscanf_s", "_cscanf_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: ["cscanf_s", "cscanf_s_l", "cwscanf_s", "_cwscanf_s", "_tcscanf_s", "_cscanf_s", "_cwscanf_s_l", "_cscanf_s_l", "cwscanf_s_l", "_tcscanf_s_l", "tcscanf_s", "tcscanf_s_l"] helpviewer_keywords: ["cscanf_s function", "_cwscanf_s_l function", "tcscanf_s function", "console [C++], reading from", "_cscanf_s function", "data [C++], reading from the console", "cwscanf_s function", "_tcscanf_s_l function", "_cscanf_s_l function", "cscanf_s_l function", "cwscanf_s_l function", "reading data [C++], from the console", "_cwscanf_s function", "_tcscanf_s function", "tcscanf_s_l function"] -ms.assetid: 9ccab74d-916f-42a6-93d8-920525efdf4b --- -# _cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l +# `_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l` -Reads formatted data from the console. These more secure versions of [_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from the console. These more secure versions of [`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -42,57 +41,56 @@ int _cwscanf_s_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional parameters. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -The number of fields that were successfully converted and assigned. The return value does not include fields that were read but not assigned. The return value is **EOF** for an attempt to read at end of file. This can occur when keyboard input is redirected at the operating-system command-line level. A return value of 0 means that no fields were assigned. +The number of fields that were successfully converted and assigned. The return value doesn't include fields that were read but not assigned. The return value is `EOF` for an attempt to read at end of file. An `EOF` can also be returned when keyboard input is redirected at the operating-system command-line level. A return value of zero means that no fields were assigned. -These functions validate their parameters. If *format* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and **errno** is set to **EINVAL**. +These functions validate their parameters. If *`format`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF`, and `errno` is set to `EINVAL`. ## Remarks -The **_cscanf_s** function reads data directly from the console into the locations given by *argument*. The [_getche](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *format*. The format controls the interpretation of the input fields and has the same form and function as the *format* parameter for the [scanf_s](scanf-scanf-l-wscanf-wscanf-l.md) function. While **_cscanf_s** normally echoes the input character, it does not do so if the last call was to **_ungetch**. +The **`_cscanf_s`** function reads data directly from the console into the locations given by *`argument`*. The [`_getche`](getch-getwch.md) function is used to read characters. Each optional parameter must be a pointer to a variable with a type that corresponds to a type specifier in *`format`*. The format controls the interpretation of the input fields and has the same form and function as the *`format`* parameter for the [`scanf_s`](scanf-scanf-l-wscanf-wscanf-l.md) function. While **`_cscanf_s`** normally echoes the input character, it doesn't do so if the last call was to `_ungetch`. -Like other secure versions of functions in the **scanf** family, **_cscanf_s** and **_cswscanf_s** require size arguments for the type field characters **c**, **C**, **s**, **S**, and **[**. For more information, see [scanf Width Specification](../../c-runtime-library/scanf-width-specification.md). +Like other secure versions of functions in the `scanf` family, **`_cscanf_s`** and **`_cwscanf_s`** require size arguments for the type field characters **c**, **C**, **s**, **S**, and **[**. For more information, see [scanf Width Specification](../scanf-width-specification.md). > [!NOTE] -> The size parameter is of type **`unsigned`**, not **size_t**. +> The size parameter is of type **`unsigned`**, not `size_t`. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcscanf_s**|**_cscanf_s**|**_cscanf_s**|**_cwscanf_s**| -|**_tcscanf_s_l**|**_cscanf_s_l**|**_cscanf_s_l**|**_cwscanf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscanf_s` | **`_cscanf_s`** | **`_cscanf_s`** | **`_cwscanf_s`** | +| `_tcscanf_s_l` | **`_cscanf_s_l`** | **`_cscanf_s_l`** | **`_cwscanf_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_cscanf_s**, **_cscanf_s_l**|\| -|**_cwscanf_s**, **_cwscanf_s_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_cscanf_s`**, **`_cscanf_s_l`** | \ | +| **`_cwscanf_s`**, **`_cwscanf_s_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example ```C // crt_cscanf_s.c -// compile with: /c /* This program prompts for a string * and uses _cscanf_s to read in the response. * Then _cscanf_s returns the number of items @@ -125,8 +123,8 @@ You entered 1 2 3 ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md) diff --git a/docs/c-runtime-library/reference/cscanf.md b/docs/c-runtime-library/reference/cscanf.md index 8f4dfb73c45..ee1ad90cfed 100644 --- a/docs/c-runtime-library/reference/cscanf.md +++ b/docs/c-runtime-library/reference/cscanf.md @@ -10,11 +10,11 @@ f1_keywords: ["cscanf"] helpviewer_keywords: ["cscanf function"] ms.assetid: 51aa2da2-0d53-4272-b510-f3eabf049ea7 --- -# cscanf +# `cscanf` -The Microsoft-specific function name `cscanf` is a deprecated alias for the [_cscanf](cscanf-cscanf-l-cwscanf-cwscanf-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `cscanf` is a deprecated alias for the [`_cscanf`](cscanf-cscanf-l-cwscanf-cwscanf-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_cscanf](cscanf-cscanf-l-cwscanf-cwscanf-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_cscanf`](cscanf-cscanf-l-cwscanf-cwscanf-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/csin-csinf-csinl.md b/docs/c-runtime-library/reference/csin-csinf-csinl.md index 399c064829b..b2b68bab638 100644 --- a/docs/c-runtime-library/reference/csin-csinf-csinl.md +++ b/docs/c-runtime-library/reference/csin-csinf-csinl.md @@ -10,7 +10,7 @@ f1_keywords: ["csin", "csinf", "csinl", "complex/csin", "complex/csinf", "comple helpviewer_keywords: ["csin function", "csinf function", "csinl function"] ms.assetid: 3ed475e8-9aae-42ba-a25c-7ae656a0fd4d --- -# csin, csinf, csinl +# `csin`, `csinf`, `csinl` Retrieves the sine of a complex number. @@ -36,37 +36,37 @@ _Lcomplex csinl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The sine of *z*, in radians. +The sine of *`z`*, in radians. ## Remarks -Because C++ allows overloading, you can call overloads of **csin** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **csin** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`csin`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`csin`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**csin**, **csinf**, **csinl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`csin`**, **`csinf`**, **`csinl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md b/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md index b87356ab457..b1dea5a7425 100644 --- a/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md +++ b/docs/c-runtime-library/reference/csinh-csinhf-csinhl.md @@ -10,7 +10,7 @@ f1_keywords: ["csinh", "csinhf", "csinhl", "complex/csinh", "complex/csinhf", "c helpviewer_keywords: ["csinh function", "csinhf function", "csinhl function"] ms.assetid: cc616e55-d14d-4cd3-91f0-fbee03ce5edf --- -# csinh, csinhf, csinhl +# `csinh`, `csinhf`, `csinhl` Retrieves the hyperbolic sine of a complex number. @@ -36,37 +36,37 @@ _Lcomplex csinhl( ### Parameters -*z*
+*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The hyperbolic sine of *z*, in radians. +The hyperbolic sine of *`z`*, in radians. ## Remarks -Because C++ allows overloading, you can call overloads of **csinh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **csinh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`csinh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`csinh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**csinh**, **csinhf**, **csinhl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`csinh`**, **`csinhf`**, **`csinhl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md b/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md index dcfc4cea173..91ae3bdad69 100644 --- a/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md +++ b/docs/c-runtime-library/reference/csqrt-csqrtf-csqrtl.md @@ -10,7 +10,7 @@ f1_keywords: ["csqrt", "csqrtf", "csqrtl", "complex/csqrt", "complex/csqrtf", "c helpviewer_keywords: ["csqrt function", "csqrtf function", "csqrtl function"] ms.assetid: b65f086b-0f55-4622-a7a3-4e79d9c9c05c --- -# csqrt, csqrtf, csqrtl +# `csqrt`, `csqrtf`, `csqrtl` Retrieves the square root of a complex number, with a branch cut along the negative real axis. @@ -36,42 +36,42 @@ _Lcomplex csqrtl( ### Parameters -*z*
+*`z`*\ A complex number. -## Return Value +## Return value -The square root of *z*. The result is in the right half-plane. +The square root of *`z`*. The result is in the right half-plane. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± QNAN, IND|none|_DOMAIN| -|- ∞|none|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | _DOMAIN | +| - INF | none | _DOMAIN | ## Remarks -Because C++ allows overloading, you can call overloads of **csqrt** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **csqrt** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`csqrt`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`csqrt`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**csqrt**, **csqrtf**, **csqrtl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`csqrt`**, **`csqrtf`**, **`csqrtl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md) diff --git a/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md b/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md index 2b86ee75414..8272c80111f 100644 --- a/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md +++ b/docs/c-runtime-library/reference/ctan-ctanf-ctanl.md @@ -1,16 +1,15 @@ --- title: "ctan, ctanf, ctanl" description: "API reference for ctan, ctanf, and ctanl; which retrieve the tangent of a complex number." -ms.date: "11/04/2016" +ms.date: 11/04/2016 api_name: ["ctan", "ctanf", "ctanl"] api_location: ["msvcrt.dll", "msvcr80.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: ["ctan", "ctanf", "ctanl", "complex/ctan", "complex/ctanf", "complex/ctanl"] helpviewer_keywords: ["ctan function", "ctanf function", "ctanl function"] -ms.assetid: d3cbd25c-1e93-4a6d-8154-da42921f7223 --- -# ctan, ctanf, ctanl +# `ctan`, `ctanf`, `ctanl` Retrieves the tangent of a complex number. @@ -36,42 +35,42 @@ _Lcomplex ctanl( ### Parameters -*z*\ +*`z`*\ A complex number that represents the angle, in radians. -## Return Value +## Return value -The tangent of *z*. +The tangent of *`z`*. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± ∞, QNAN, IND|none|_DOMAIN| -|± ∞ (**tan**, **tanf**)|INVALID|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF, QNaN, IND | none | _DOMAIN | +| ± INF (`tan`, `tanf`) | INVALID | _DOMAIN | ## Remarks -Because C++ allows overloading, you can call overloads of **ctan** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **ctan** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`ctan`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`ctan`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ctan**, **ctanf**, **ctanl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`ctan`**, **`ctanf`**, **`ctanl`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[ctanh, ctanhf, ctanhl](ctanh-ctanhf-ctanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`ctanh`, `ctanhf`, `ctanhl`](ctanh-ctanhf-ctanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md b/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md index ec298344699..0b7fa8bfce4 100644 --- a/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md +++ b/docs/c-runtime-library/reference/ctanh-ctanhf-ctanhl.md @@ -10,7 +10,7 @@ f1_keywords: ["ctanh", "ctanhf", "ctanhl", "complex/ctanh", "complex/ctanhf", "c helpviewer_keywords: ["ctanh function", "ctanhl function", "ctanhf function"] ms.assetid: 807f2cd1-8740-4988-afff-5911c346385b --- -# ctanh, ctanhf, ctanhl +# `ctanh`, `ctanhf`, `ctanhl` Computes the complex hyperbolic tangent of a complex number. @@ -36,42 +36,42 @@ _Lcomplex ctanhl( ### Parameters -*z*\ +*`z`*\ A complex number that represents an angle, in radians. -## Return Value +## Return value -The complex hyperbolic tangent of *z*. +The complex hyperbolic tangent of *`z`*. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± ∞, QNAN, IND|none|_DOMAIN| -|± ∞ (tan, tanf)|INVALID|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF, QNaN, IND | none | _DOMAIN | +| ± INF (tan, tanf) | INVALID | _DOMAIN | ## Remarks -Because C++ allows overloading, you can call overloads of **ctanh** that take and return **_Fcomplex** and **_Lcomplex** values. In a C program, **ctanh** always takes and returns a **_Dcomplex** value. +Because C++ allows overloading, you can call overloads of **`ctanh`** that take and return `_Fcomplex` and `_Lcomplex` values. In a C program, **`ctanh`** always takes and returns a `_Dcomplex` value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**ctanh**, **ctanhf**, **ctanhl**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`ctanh`**, **`ctanhf`**, **`ctanhl`** | \ | \ | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[catanh, catanhf, catanhl](catanh-catanhf-catanhl.md)
-[catan, catanf, catanl](catan-catanf-catanl.md)
-[csinh, csinhf, csinhl](csinh-csinhf-csinhl.md)
-[casinh, casinhf, casinhl](casinh-casinhf-casinhl.md)
-[ccosh, ccoshf, ccoshl](ccosh-ccoshf-ccoshl.md)
-[cacosh, cacoshf, cacoshl](cacosh-cacoshf-cacoshl.md)
-[cacos, cacosf, cacosl](cacos-cacosf-cacosl.md)
-[ctan, ctanf, ctanl](ctan-ctanf-ctanl.md)
-[csin, csinf, csinl](csin-csinf-csinl.md)
-[casin, casinf, casinl](casin-casinf-casinl.md)
-[ccos, ccosf, ccosl](ccos-ccosf-ccosl.md)
-[csqrt, csqrtf, csqrtl](csqrt-csqrtf-csqrtl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`catanh`, `catanhf`, `catanhl`](catanh-catanhf-catanhl.md)\ +[`catan`, `catanf`, `catanl`](catan-catanf-catanl.md)\ +[`csinh`, `csinhf`, `csinhl`](csinh-csinhf-csinhl.md)\ +[`casinh`, `casinhf`, `casinhl`](casinh-casinhf-casinhl.md)\ +[`ccosh`, `ccoshf`, `ccoshl`](ccosh-ccoshf-ccoshl.md)\ +[`cacosh`, `cacoshf`, `cacoshl`](cacosh-cacoshf-cacoshl.md)\ +[`cacos`, `cacosf`, `cacosl`](cacos-cacosf-cacosl.md)\ +[`ctan`, `ctanf`, `ctanl`](ctan-ctanf-ctanl.md)\ +[`csin`, `csinf`, `csinl`](csin-csinf-csinl.md)\ +[`casin`, `casinf`, `casinl`](casin-casinf-casinl.md)\ +[`ccos`, `ccosf`, `ccosl`](ccos-ccosf-ccosl.md)\ +[`csqrt`, `csqrtf`, `csqrtl`](csqrt-csqrtf-csqrtl.md) diff --git a/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md b/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md index 3d6986a8278..3f03733bda5 100644 --- a/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md +++ b/docs/c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md @@ -3,48 +3,47 @@ description: "Learn more about: ctime, _ctime32, _ctime64, _wctime, _wctime32, _ title: "ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64" ms.date: "4/2/2020" api_name: ["_ctime64", "_wctime32", "ctime", "_wctime64", "_ctime32", "_wctime", "_o__wctime32", "_o__wctime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wctime64", "_ctime32", "_tctime", "_wctime", "_wctime32", "_tctime64", "_ctime64", "ctime"] helpviewer_keywords: ["tctime64 function", "_ctime32 function", "ctime32 function", "_wctime function", "wctime64 function", "_tctime64 function", "_tctime32 function", "_ctime64 function", "_wctime64 function", "ctime function", "wctime32 function", "ctime64 function", "_wctime32 function", "_tctime function", "tctime32 function", "tctime function", "wctime function", "time, converting"] -ms.assetid: 2423de37-a35c-4f0a-a378-3116bc120a9d --- -# ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64 +# `ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64` -Convert a time value to a string and adjust for local time zone settings. More secure versions of these functions are available; see [ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md). +Convert a time value to a string and adjust for local time zone settings. More secure versions of these functions are available; see [`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md). ## Syntax ```C -char *ctime( const time_t *sourceTime ); +char *ctime( const time_t *sourceTime ); // See note in remarks section about linkage char *_ctime32( const __time32_t *sourceTime ); char *_ctime64( const __time64_t *sourceTime ); -wchar_t *_wctime( const time_t *sourceTime ); +wchar_t *_wctime( const time_t *sourceTime ); // See note in remarks section about linkage wchar_t *_wctime32( const __time32_t *sourceTime ); wchar_t *_wctime64( const __time64_t *sourceTime ); ``` ### Parameters -*sourceTime*
+*`sourceTime`*\ Pointer to stored time to convert. -## Return Value +## Return value -A pointer to the character string result. **NULL** will be returned if: +A pointer to the character string result. `NULL` is returned when: -- *sourceTime* represents a date before midnight, January 1, 1970, UTC. +- *`sourceTime`* represents a date before midnight, January 1, 1970, UTC. -- If you use **_ctime32** or **_wctime32** and *sourceTime* represents a date after 23:59:59 January 18, 2038, UTC. +- You use **`_ctime32`** or **`_wctime32`**, and *`sourceTime`* represents a date after 23:59:59 January 18, 2038, UTC. -- If you use **_ctime64** or **_wctime64** and *sourceTime* represents a date after 23:59:59, December 31, 3000, UTC. +- You use **`_ctime64`** or **`_wctime64`**, and *`sourceTime`* represents a date after 23:59:59, December 31, 3000, UTC. -**ctime** is an inline function which evaluates to **_ctime64** and **time_t** is equivalent to **__time64_t**. If you need to force the compiler to interpret **time_t** as the old 32-bit **time_t**, you can define **_USE_32BIT_TIME_T**. Doing this will cause **ctime** to evaluate to **_ctime32**. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms. +**`ctime`** is an inline function that evaluates to **`_ctime64`**, and `time_t` is equivalent to `__time64_t`. If you need to force the compiler to interpret `time_t` as the old 32-bit `time_t`, you can define `_USE_32BIT_TIME_T`. This macro causes **`ctime`** to evaluate to **`_ctime32`**. We don't recommend you use it, because your application may fail after January 18, 2038, and it isn't allowed on 64-bit platforms. ## Remarks -The **ctime** function converts a time value stored as a [time_t](../../c-runtime-library/standard-types.md) value into a character string. The *sourceTime* value is usually obtained from a call to [time](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: +The **`ctime`** function converts a time value stored as a [`time_t`](../standard-types.md) value into a character string. The *`sourceTime`* value is typically obtained from a call to [`time`](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: ```Output Wed Jan 02 02:03:55 1980\n\0 @@ -52,36 +51,41 @@ Wed Jan 02 02:03:55 1980\n\0 A 24-hour clock is used. All fields have a constant width. The newline character ('\n') and the null character ('\0') occupy the last two positions of the string. -The converted character string is also adjusted according to the local time zone settings. See the [time](time-time32-time64.md), [_ftime](ftime-ftime32-ftime64.md), and [localtime](localtime-localtime32-localtime64.md) functions for information on configuring the local time and the [_tzset](tzset.md) function for details about defining the time zone environment and global variables. +The converted character string is also adjusted according to the local time zone settings. For information on configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For details about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function. -A call to **ctime** modifies the single statically allocated buffer used by the **gmtime** and **localtime** functions. Each call to one of these routines destroys the result of the previous call. **ctime** shares a static buffer with the **asctime** function. Thus, a call to **ctime** destroys the results of any previous call to **asctime**, **localtime**, or **gmtime**. +A call to **`ctime`** modifies the single statically allocated buffer used by the `gmtime` and `localtime` functions. Each call to one of these routines destroys the result of the previous call. **`ctime`** shares a static buffer with the `asctime` function. Thus, a call to **`ctime`** destroys the results of any previous call to `asctime`, `localtime`, or `gmtime`. -**_wctime** and **_wctime64** are the wide-character version of **ctime** and **_ctime64**; returning a pointer to wide-character string. Otherwise, **_ctime64**, **_wctime**, and **_wctime64** behave identically to **ctime**. +**`_wctime`** and **`_wctime64`** are the wide-character version of **`ctime`** and **`_ctime64`**; returning a pointer to wide-character string. Otherwise, **`_ctime64`**, **`_wctime`**, and **`_wctime64`** behave identically to **`ctime`**. -These functions validate their parameters. If *sourceTime* is a null pointer, or if the *sourceTime* value is negative, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return **NULL** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`sourceTime`* is a null pointer, or if the *`sourceTime`* value is negative, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return `NULL` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +> [!Note] +> When you use Windows SDK version 10.0.26100.6901 and Visual Studio 2026 or later together, `ctime` and `_wctime` are no longer `static inline` (internal linkage). Instead, they're `inline` (external linkage).\ +> To return to the previous behavior, `#define _STATIC_INLINE_UCRT_FUNCTIONS=1` before including any CRT headers. By default, `_STATIC_INLINE_UCRT_FUNCTIONS` is set to 0.\ +> This change increases UCRT conformance with the C++ standard and improves compatibility with C++ modules. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tctime**|**ctime**|**ctime**|**_wctime**| -|**_tctime32**|**_ctime32**|**_ctime32**|**_wctime32**| -|**_tctime64**|**_ctime64**|**_ctime64**|**_wctime64**| +### Generic-text routine mappings + +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tctime` | **`ctime`** | **`ctime`** | **`_wctime`** | +| `_tctime32` | **`_ctime32`** | **`_ctime32`** | **`_wctime32`** | +| `_tctime64` | **`_ctime64`** | **`_ctime64`** | **`_wctime64`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**ctime**|\| -|**_ctime32**|\| -|**_ctime64**|\| -|**_wctime**|\ or \| -|**_wctime32**|\ or \| -|**_wctime64**|\ or \| +| Routine | Required header | +|---|---| +| **`ctime`** | `` | +| **`_ctime32`** | `` | +| **`_ctime64`** | `` | +| **`_wctime`** | `` or `` | +| **`_wctime32`** | `` or `` | +| **`_wctime64`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -112,10 +116,10 @@ The time is Wed Feb 13 16:04:43 2002 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md b/docs/c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md index bc5265e7dac..12965dc90e2 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 @@ -1,23 +1,22 @@ --- -description: "Learn more about: ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s" title: "ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s" -ms.date: "4/2/2020" +description: "Learn more about: ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s" +ms.date: 4/2/2020 api_name: ["_ctime64_s", "_wctime32_s", "ctime_s", "_wctime64_s", "_ctime32_s", "_wctime_s", "_o__ctime32_s", "_o__ctime64_s", "_o__wctime32_s", "_o__wctime64_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ctime64_s", "_ctime32_s", "_tctime32_s", "_ctime64_s", "_wctime_s", "_tctime_s", "_tctime64_s", "ctime_s", "ctime32_s"] helpviewer_keywords: ["_wctime32_s function", "ctime64_s function", "_tctime64_s function", "_wctime_s function", "tctime_s function", "_wctime64_s function", "ctime_s function", "ctime32_s function", "_ctime64_s function", "tctime64_s function", "wctime64_s function", "wctime_s function", "_tctime_s function", "tctime32_s function", "wctime32_s function", "time, converting", "_ctime32_s function", "_tctime32_s function"] -ms.assetid: 36ac419a-8000-4389-9fd8-d78b747a009b --- -# ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s +# `ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s` -Convert a time value to a string and adjust for local time zone settings. These are versions of [ctime, _ctime64, _wctime, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a time value to a string and adjust for local time zone settings. These functions are versions of [`ctime`, `_ctime64`, `_wctime`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax ```C -errno_t ctime_s( +errno_t ctime_s( // See note in remarks section about linkage char* buffer, size_t numberOfElements, const time_t *sourceTime @@ -30,9 +29,9 @@ errno_t _ctime32_s( errno_t _ctime64_s( char* buffer, size_t numberOfElements, - const __time64_t *sourceTime ) -; -errno_t _wctime_s( + const __time64_t *sourceTime +); +errno_t _wctime_s( // See note in remarks section about linkage wchar_t* buffer, size_t numberOfElements, const time_t *sourceTime @@ -74,77 +73,82 @@ errno_t _wctime64_s( ### Parameters -*buffer*
-Must be large enough to hold 26 characters. A pointer to the character string result, or **NULL** if: +*`buffer`*\ +Must be large enough to hold 26 characters. A pointer to the character string result, or `NULL` if: -- *sourceTime* represents a date before midnight, January 1, 1970, UTC. +- *`sourceTime`* represents a date before midnight, January 1, 1970, UTC. -- If you use **_ctime32_s** or **_wctime32_s** and *sourceTime* represents a date after 23:59:59 January 18, 2038, UTC. +- If you use **`_ctime32_s`** or **`_wctime32_s`** and *`sourceTime`* represents a date after 23:59:59 January 18, 2038, UTC. -- If you use **_ctime64_s** or **_wctime64_s** and *sourceTime* represents a date after 23:59:59, December 31, 3000, UTC. +- If you use **`_ctime64_s`** or **`_wctime64_s`** and *`sourceTime`* represents a date after 23:59:59, December 31, 3000, UTC. -- If you use **_ctime_s** or **_wctime_s**, these functions are wrappers to the previous functions. See the Remarks section. +- If you use **`_ctime_s`** or **`_wctime_s`**, these functions are wrappers to the previous functions. See the Remarks section. -*numberOfElements*
+*`numberOfElements`*\ The size of the buffer. -*sourceTime*
+*`sourceTime`*\ Pointer to stored time. -## Return Value +## Return value -Zero if successful. If there is a failure due to an invalid parameter, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, an error code is returned. Error codes are defined in ERRNO.H; for a listing of these errors, see [errno](../../c-runtime-library/errno-constants.md). The actual error codes thrown for each error condition are shown in the following table. +Zero if successful. If there's a failure due to an invalid parameter, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, an error code is returned. Error codes are defined in ERRNO.H; for a listing of these errors, see [`errno`](../errno-constants.md). The actual error codes thrown for each error condition are shown in the following table. -## Error Conditions +## Error conditions -|*buffer*|*numberOfElements*|*sourceTime*|Return|Value in *buffer*| -|--------------|------------------------|------------|------------|-----------------------| -|**NULL**|any|any|**EINVAL**|Not modified| -|Not **NULL** (points to valid memory)|0|any|**EINVAL**|Not modified| -|Not **NULL**|0< size < 26|any|**EINVAL**|Empty string| -|Not **NULL**|>= 26|NULL|**EINVAL**|Empty string| -|Not **NULL**|>= 26|< 0|**EINVAL**|Empty string| +| *`buffer`* | *`numberOfElements`* | *`sourceTime`* | Return | Value in *`buffer`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | Not modified | +| Not `NULL` (points to valid memory) | 0 | any | `EINVAL` | Not modified | +| Not `NULL` | 0< size < 26 | any | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | NULL | `EINVAL` | Empty string | +| Not `NULL` | >= 26 | < 0 | `EINVAL` | Empty string | ## Remarks -The **ctime_s** function converts a time value stored as a [time_t](../../c-runtime-library/standard-types.md) structure into a character string. The *sourceTime* value is usually obtained from a call to [time](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: +The **`ctime_s`** function converts a time value stored as a [`time_t`](../standard-types.md) structure into a character string. The *`sourceTime`* value is typically obtained from a call to [`time`](time-time32-time64.md), which returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time (UTC). The return value string contains exactly 26 characters and has the form: -`Wed Jan 02 02:03:55 1980\n\0` +`Wed Jan 2 02:03:55 1980\n\0` A 24-hour clock is used. All fields have a constant width. The new line character ('\n') and the null character ('\0') occupy the last two positions of the string. -The converted character string is also adjusted according to the local time zone settings. See the [time](time-time32-time64.md), [_ftime](ftime-ftime32-ftime64.md), and [localtime32_s](localtime-s-localtime32-s-localtime64-s.md) functions for information about configuring the local time and the [_tzset](tzset.md) function for information about defining the time zone environment and global variables. +The converted character string is also adjusted according to the local time zone settings. For information on configuring the local time, see the [`time`](time-time32-time64.md), [`_ftime`](ftime-ftime32-ftime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions. For details about defining the time zone environment and global variables, see the [`_tzset`](tzset.md) function. + +**`_wctime32_s`** and **`_wctime64_s`** are the wide-character version of **`_ctime32_s`** and **`_ctime64_s`**; returning a pointer to wide-character string. Otherwise, **`_ctime64_s`**, **`_wctime32_s`**, and **`_wctime64_s`** behave identically to **`_ctime32_s`**. -**_wctime32_s** and **_wctime64_s** are the wide-character version of **_ctime32_s** and **_ctime64_s**; returning a pointer to wide-character string. Otherwise, **_ctime64_s**, **_wctime32_s**, and **_wctime64_s** behave identically to **_ctime32_s**. +**`ctime_s`** is an inline function that evaluates to **`_ctime64_s`** and `time_t` is equivalent to `__time64_t`. If you need to force the compiler to interpret `time_t` as the old 32-bit `time_t`, you can define `_USE_32BIT_TIME_T`. This macro causes **`ctime_s`** to evaluate to **`_ctime32_s`**. We don't recommend it, because your application may fail after January 18, 2038, and it isn't allowed on 64-bit platforms. -**ctime_s** is an inline function that evaluates to **_ctime64_s** and **time_t** is equivalent to **__time64_t**. If you need to force the compiler to interpret **time_t** as the old 32-bit **time_t**, you can define **_USE_32BIT_TIME_T**. Doing this will cause **ctime_s** to evaluate to **_ctime32_s**. This is not recommended because your application may fail after January 18, 2038, and it is not allowed on 64-bit platforms. +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +> [!Note] +> When you use Windows SDK version 10.0.26100.6901 and Visual Studio 2026 or later together, `ctime_s` and `_wctime_s` are no longer `static inline` (internal linkage). Instead, they're `inline` (external linkage).\ +> To return to the previous behavior, `#define _STATIC_INLINE_UCRT_FUNCTIONS=1` before including any CRT headers. By default, `_STATIC_INLINE_UCRT_FUNCTIONS` is set to 0.\ +> This change increases UCRT conformance with the C++ standard and improves compatibility with C++ modules. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tctime_s**|**ctime_s**|**ctime_s**|**_wctime_s**| -|**_tctime32_s**|**_ctime32_s**|**_ctime32_s**|**_wctime32_s**| -|**_tctime64_s**|**_ctime64_s**|**_ctime64_s**|**_wctime64_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tctime_s` | **`ctime_s`** | **`ctime_s`** | **`_wctime_s`** | +| `_tctime32_s` | **`_ctime32_s`** | **`_ctime32_s`** | **`_wctime32_s`** | +| `_tctime64_s` | **`_ctime64_s`** | **`_ctime64_s`** | **`_wctime64_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**ctime_s**, **_ctime32_s**, **_ctime64_s**|\| -|**_wctime_s**, **_wctime32_s**, **_wctime64_s**|\ or \| +| Routine | Required header | +|---|---| +| **`ctime_s`**, **`_ctime32_s`**, **`_ctime64_s`** | \ | +| **`_wctime_s`**, **`_wctime32_s`**, **`_wctime64_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -182,10 +186,10 @@ The time is Fri Apr 25 13:03:39 2003 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/cwait.md b/docs/c-runtime-library/reference/cwait.md index 86e3308cb83..4f2d069a7c6 100644 --- a/docs/c-runtime-library/reference/cwait.md +++ b/docs/c-runtime-library/reference/cwait.md @@ -1,16 +1,15 @@ --- title: "_cwait" description: "API reference for the Microsoft Visual C runtime `_cwait()` function." -ms.date: "10/23/2020" +ms.date: 10/23/2020 api_name: ["_cwait", "_o__cwait"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_cwait"] helpviewer_keywords: ["cwait function", "_cwait function"] -ms.assetid: d9b596b5-45f4-4e03-9896-3f383cb922b8 --- -# _cwait +# `_cwait` Waits until another process terminates. @@ -30,50 +29,49 @@ intptr_t _cwait( ### Parameters *`termstat`*\ -Pointer to a buffer where the result code of the specified process will be stored, or **`NULL`**. +Pointer to a buffer where the result code of the specified process will be stored, or `NULL`. *`procHandle`*\ -The handle to the process to wait on (that is, the process that has to terminate before **_cwait** can return). +The handle to the process to wait on (that is, the process that has to terminate before **`_cwait`** can return). *`action`*\ -**`NULL`**: Ignored by Windows operating system applications; for other applications: action code to perform on *`procHandle`*. +`NULL`: Ignored by Windows operating system applications; for other applications: action code to perform on *`procHandle`*. -## Return Value +## Return value -When the specified process has successfully completed, returns the handle of the specified process and sets *`termstat`* to the result code that's returned by the specified process. Otherwise, returns -1 and sets **`errno`** as follows. +When the specified process has successfully completed, returns the handle of the specified process and sets *`termstat`* to the result code that's returned by the specified process. Otherwise, returns -1 and sets `errno` as follows. -|Value|Description| -|-----------|-----------------| -|**`ECHILD`**|No specified process exists, *`procHandle`* is invalid, or the call to the [`GetExitCodeProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess) or [`WaitForSingleObject`](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject) API failed.| -|**`EINVAL`**|*`action`* is invalid.| +| `errno` value | Description | +|---|---| +| `ECHILD` | No specified process exists, *`procHandle`* is invalid, or the call to the [`GetExitCodeProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess) or [`WaitForSingleObject`](/windows/win32/api/synchapi/nf-synchapi-waitforsingleobject) API failed. | +| `EINVAL` | *`action`* is invalid. | -For more information about these and other return codes, see [`errno, _doserrno, _sys_errlist, and _sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`_cwait`** function waits for the termination of the process ID of the specified process that's provided by *`procHandle`*. The value of *`procHandle`* that's passed to **`_cwait`** should be the value that's returned by the call to the [`_spawn`](../../c-runtime-library/spawn-wspawn-functions.md) function that created the specified process. If the process ID terminates before **`_cwait`** is called, **`_cwait`** returns immediately. **`_cwait`** can be used by any process to wait for any other known process for which a valid handle (*`procHandle`*) exists. +The **`_cwait`** function waits for the termination of the process ID of the specified process that's provided by *`procHandle`*. The value of *`procHandle`* that's passed to **`_cwait`** should be the value that's returned by the call to the [`_spawn`](../spawn-wspawn-functions.md) function that created the specified process. If the process ID terminates before **`_cwait`** is called, **`_cwait`** returns immediately. **`_cwait`** can be used by any process to wait for any other known process for which a valid handle (*`procHandle`*) exists. -*`termstat`* points to a buffer where the return code of the specified process will be stored. The value of *`termstat`* indicates whether the specified process terminated normally by calling the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API. **`ExitProcess`** is called internally if the specified process calls **`exit`** or **`_exit`**, returns from **`main`**, or reaches the end of **`main`**. For more information about the value that's passed back through *`termstat`*, see [GetExitCodeProcess](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess). If **`_cwait`** is called by using a **`NULL`** value for *`termstat`*, the return code of the specified process isn't stored. +*`termstat`* points to a buffer where the return code of the specified process will be stored. The value of *`termstat`* indicates whether the specified process terminated normally by calling the Windows [`ExitProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitprocess) API. `ExitProcess` is called internally if the specified process calls **`exit`** or **`_exit`**, returns from **`main`**, or reaches the end of **`main`**. For more information about the value that's passed back through *`termstat`*, see [`GetExitCodeProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-getexitcodeprocess). If **`_cwait`** is called by using a `NULL` value for *`termstat`*, the return code of the specified process isn't stored. The *`action`* parameter is ignored by the Windows operating system because parent-child relationships aren't implemented in these environments. Unless *`procHandle`* is -1 or -2 (handles to the current process or thread), the handle will be closed. In this situation, don't use the returned handle. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_cwait`**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_cwait`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_cwait.c -// compile with: /c // This program launches several processes and waits // for a specified process to finish. @@ -141,5 +139,5 @@ Hi, Dad. It's Dave. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ -[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md) +[Process and environment control](../process-and-environment-control.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md) diff --git a/docs/c-runtime-library/reference/cxxthrowexception.md b/docs/c-runtime-library/reference/cxxthrowexception.md index 20d460e28a9..2a2a3b87b6f 100644 --- a/docs/c-runtime-library/reference/cxxthrowexception.md +++ b/docs/c-runtime-library/reference/cxxthrowexception.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _CxxThrowException" title: "_CxxThrowException" +description: "Learn more about: _CxxThrowException" ms.date: "11/04/2016" api_name: ["_CxxThrowException"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CxxThrowException", "_CxxThrowException"] helpviewer_keywords: ["_CxxThrowException function", "CxxThrowException function"] -ms.assetid: 0b90bef5-b7d2-46e0-88e2-59e531e01a4d --- -# _CxxThrowException +# `_CxxThrowException` Builds the exception record and calls the runtime environment to start processing the exception. @@ -18,22 +17,22 @@ Builds the exception record and calls the runtime environment to start processin ```C extern "C" void __stdcall _CxxThrowException( - void* pExceptionObject + void* pExceptionObject, _ThrowInfo* pThrowInfo ); ``` ### Parameters -*pExceptionObject*
+*`pExceptionObject`*\ The object that generated the exception. -*pThrowInfo*
+*`pThrowInfo`*\ The information that is required to process the exception. ## Remarks -This method is included in a compiler-only file that the compiler uses to process exceptions. Do not call the method directly from your code. +This method is included in a compiler-only file that the compiler uses to process exceptions. Don't call the method directly from your code. ## Requirements @@ -41,4 +40,4 @@ This method is included in a compiler-only file that the compiler uses to proces ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md b/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md index bb423593a5f..b1512299fa8 100644 --- a/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md +++ b/docs/c-runtime-library/reference/difftime-difftime32-difftime64.md @@ -3,58 +3,62 @@ description: "Learn more about: difftime, _difftime32, _difftime64" title: "difftime, _difftime32, _difftime64" ms.date: "4/2/2020" api_name: ["_difftime32", "difftime", "_difftime64", "_o__difftime32", "_o__difftime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_difftime64", "difftime", "difftime64", "_difftime32", "difftime32"] helpviewer_keywords: ["_difftime32 function", "difftime function", "time, finding the difference", "difftime64 function", "_difftime64 function", "difftime32 function"] -ms.assetid: 4cc0ac2b-fc7b-42c0-8283-8c9d10c566d0 --- -# difftime, _difftime32, _difftime64 +# `difftime`, `_difftime32`, `_difftime64` Finds the difference between two times. ## Syntax ```C -double difftime( time_t timeEnd, time_t timeStart ); +double difftime( time_t timeEnd, time_t timeStart ); // See note in remarks section about linkage double _difftime32( __time32_t timeEnd, __time32_t timeStart ); double _difftime64( __time64_t timeEnd, __time64_t timeStart ); ``` ### Parameters -*timeEnd*
+*`timeEnd`*\ Ending time. -*timeStart*
+*`timeStart`*\ Beginning time. -## Return Value +## Return value -**difftime** returns the elapsed time in seconds, from *timeStart* to *timeEnd*. The value returned is a double precision floating-point number. The return value may be 0, indicating an error. +**`difftime`** returns the elapsed time in seconds, from *`timeStart`* to *`timeEnd`*. The value returned is a double precision floating-point number. The return value may be 0, indicating an error. ## Remarks -The **difftime** function computes the difference between the two supplied time values *timeStart* and *timeEnd*. +The **`difftime`** function computes the difference between the two supplied time values *`timeStart`* and *`timeEnd`*. -The time value supplied must fit within the range of **time_t**. **time_t** is a 64-bit value. Thus, the end of the range was extended from 23:59:59 January 18, 2038, UTC to 23:59:59, December 31, 3000. The lower range of **time_t** is still midnight, January 1, 1970. +The time value supplied must fit within the range of `time_t`. `time_t` is a 64-bit value. Thus, the end of the range was extended from 23:59:59 January 18, 2038, UTC to 23:59:59, December 31, 3000. The lower range of `time_t` is still midnight, January 1, 1970. -**difftime** is an inline function that evaluates to either **_difftime32** or **_difftime64** depending on whether **_USE_32BIT_TIME_T** is defined. _difftime32 and _difftime64 can be used directly to force the use of a particular size of the time type. +**`difftime`** is an inline function that evaluates to either **`_difftime32`** or **`_difftime64`** depending on whether `_USE_32BIT_TIME_T` is defined. _difftime32 and _difftime64 can be used directly to force the use of a particular size of the time type. -These functions validate their parameters. If either of the parameters is zero or negative, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return 0 and set **errno** to **EINVAL**. +These functions validate their parameters. If either of the parameters is zero or negative, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return 0 and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). + +> [!Note] +> If you use Windows SDK version 10.0.26100.6901 and Visual Studio 2026 or later together, `difftime` is no longer `static inline` (internal linkage). Instead, it's `inline` (external linkage).\ +> To return to the previous behavior, `#define _STATIC_INLINE_UCRT_FUNCTIONS=1` before including any CRT headers. By default, `_STATIC_INLINE_UCRT_FUNCTIONS` is set to 0.\ +> This change increases UCRT conformance with the C++ standard and improves compatibility with C++ modules. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**difftime**|\| -|**_difftime32**|\| -|**_difftime64**|\| +| Routine | Required header | +|---|---| +| **`difftime`** | `` | +| **`_difftime32`** | `` | +| **`_difftime64`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -114,6 +118,6 @@ Program takes 3 seconds. ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Time Management](../../c-runtime-library/time-management.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Time management](../time-management.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/div.md b/docs/c-runtime-library/reference/div.md index a9e98499e6d..5fb4a081e97 100644 --- a/docs/c-runtime-library/reference/div.md +++ b/docs/c-runtime-library/reference/div.md @@ -49,15 +49,15 @@ The numerator. *`denom`*\ The denominator. -## Return Value +## Return value **`div`** called by using arguments of type **`int`** returns a structure of type `div_t`, which contains the quotient and the remainder. The return value with arguments of type **`long`** is `ldiv_t`, and the return value with arguments of type **`long long`** is `lldiv_t`. The `div_t`, `ldiv_t`, and `lldiv_t` types are defined in \. ## Remarks -The **`div`** function divides *`numer`* by *`denom`* and computes the quotient and the remainder. The [`div_t`](../../c-runtime-library/standard-types.md) structure contains the quotient, `quot`, and the remainder, `rem`. The sign of the quotient is the same as the sign of the mathematical quotient. Its absolute value is the largest integer that's less than the absolute value of the mathematical quotient. If the denominator is 0, the program terminates with an error message. +The **`div`** function divides *`numer`* by *`denom`* and computes the quotient and the remainder. The [`div_t`](../standard-types.md) structure contains the quotient, `quot`, and the remainder, `rem`. The sign of the quotient is the same as the sign of the mathematical quotient. Its absolute value is the largest integer that's less than the absolute value of the mathematical quotient. If the denominator is 0, the program terminates with an error message. -The overloads of **`div`** that take arguments of type **`long`** or **`long long`** are only available to C++ code. The return types [`ldiv_t`](../../c-runtime-library/standard-types.md) and [`lldiv_t`](../../c-runtime-library/standard-types.md) contains members `quot` and `rem`, which have the same meanings as the members of `div_t`. +The overloads of **`div`** that take arguments of type **`long`** or **`long long`** are only available to C++ code. The return types [`ldiv_t`](../standard-types.md) and [`lldiv_t`](../standard-types.md) contains members `quot` and `rem`, which have the same meanings as the members of `div_t`. ## Requirements @@ -65,7 +65,7 @@ The overloads of **`div`** that take arguments of type **`long`** or **`long lon |--|--| | **`div`**, **`ldiv`**, **`lldiv`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -107,5 +107,5 @@ The quotient is 67, and the remainder is 5 ## See also -[Floating-point support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`imaxdiv`](imaxdiv.md) diff --git a/docs/c-runtime-library/reference/dup-dup2.md b/docs/c-runtime-library/reference/dup-dup2.md index 20e0113b993..718e1e3af75 100644 --- a/docs/c-runtime-library/reference/dup-dup2.md +++ b/docs/c-runtime-library/reference/dup-dup2.md @@ -3,7 +3,7 @@ description: "Learn more about: _dup, _dup2" title: "_dup, _dup2" ms.date: "4/2/2020" api_name: ["_dup", "_dup2", "_o__dup", "_o__dup2"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_dup2", "_dup"] @@ -28,11 +28,11 @@ File descriptors referring to open file. *`fd2`*\ Any file descriptor. -## Return Value +## Return value -**`_dup`** returns a new file descriptor. **`_dup2`** returns 0 to indicate success. If an error occurs, each function returns -1 and sets **`errno`** to **`EBADF`** if the file descriptor is invalid or to **`EMFILE`** if no more file descriptors are available. In the case of an invalid file descriptor, the function also invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +**`_dup`** returns a new file descriptor. **`_dup2`** returns 0 to indicate success. If an error occurs, each function returns -1 and sets `errno` to `EBADF` if the file descriptor is invalid, or to `EMFILE` if no more file descriptors are available. When passed an invalid file descriptor, the function also invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -44,16 +44,16 @@ Both **`_dup`** and **`_dup2`** accept file descriptors as parameters. To pass a int cstderr = _dup( _fileno( stderr )); ``` -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_dup`**|``| -|**`_dup2`**|``| +| Routine | Required header | +|---|---| +| **`_dup`** | `` | +| **`_dup2`** | `` | -The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -118,7 +118,7 @@ This goes to file 'data' ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)\ +[Low-level I/O](../low-level-i-o.md)\ [`_close`](close.md)\ [`_creat`, `_wcreat`](creat-wcreat.md)\ [`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md b/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md index a23cbff6ee1..047aba34af6 100644 --- a/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md +++ b/docs/c-runtime-library/reference/dupenv-s-dbg-wdupenv-s-dbg.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _dupenv_s_dbg, _wdupenv_s_dbg" title: "_dupenv_s_dbg, _wdupenv_s_dbg" +description: "Learn more about: _dupenv_s_dbg, _wdupenv_s_dbg" ms.date: "11/04/2016" api_name: ["_dupenv_s_dbg", "_wdupenv_s_dbg"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tdupenv_s_dbg", "_dupenv_s_dbg", "_wdupenv_s_dbg"] helpviewer_keywords: ["_tdupenv_s_dbg function", "dupenv_s_dbg function", "_wdupenv_s_dbg function", "environment variables", "tdupenv_s_dbg function", "wdupenv_s_dbg function", "_dupenv_s_dbg function"] -ms.assetid: e3d81148-e24e-46d0-a21d-fd87b5e6256c --- -# _dupenv_s_dbg, _wdupenv_s_dbg +# `_dupenv_s_dbg`, `_wdupenv_s_dbg` -Get a value from the current environment. Versions of [_dupenv_s, _wdupenv_s](dupenv-s-wdupenv-s.md) that allocate memory with [_malloc_dbg](malloc-dbg.md) to provide additional debugging information. +Get a value from the current environment. Versions of [`_dupenv_s`, `_wdupenv_s`](dupenv-s-wdupenv-s.md) that allocate memory with [`_malloc_dbg`](malloc-dbg.md) to provide more debugging information. ## Syntax @@ -23,7 +22,7 @@ errno_t _dupenv_s_dbg( const char *varname, int blockType, const char *filename, - int linenumber + int lineNumber ); errno_t _wdupenv_s_dbg( wchar_t **buffer, @@ -31,64 +30,64 @@ errno_t _wdupenv_s_dbg( const wchar_t *varname, int blockType, const char *filename, - int linenumber + int lineNumber ); ``` ### Parameters -*buffer*
+*`buffer`*\ Buffer to store the variable's value. -*numberOfElements*
-Size of *buffer*. +*`numberOfElements`*\ +Size of *`buffer`*. -*varname*
+*`varname`*\ Environment variable name. -*blockType*
-Requested type of the memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of the memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file or **NULL**. +*`filename`*\ +Pointer to the name of the source file or `NULL`. -*linenumber*
-Line number in source file or **NULL**. +*`lineNumber`*\ +Line number in source file or `NULL`. -## Return Value +## Return value Zero on success, an error code on failure. -These functions validate their parameters; if *buffer* or *varname* is **NULL**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions set **errno** to **EINVAL** and return **EINVAL**. +These functions validate their parameters; if *`buffer`* or *`varname`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions set `errno` to `EINVAL`, and return `EINVAL`. -If these functions cannot allocate enough memory, they set *buffer* to **NULL** and *numberOfElements* to 0, and return **ENOMEM**. +If these functions can't allocate enough memory, they set *`buffer`* to `NULL` and *`numberOfElements`* to 0, and return `ENOMEM`. ## Remarks -The **_dupenv_s_dbg** and **_wdupenv_s_dbg** functions are identical to **_dupenv_s** and **_wdupenv_s** except that, when **_DEBUG** is defined, these functions use the debug version of [malloc](malloc.md), [_malloc_dbg](malloc-dbg.md), to allocate memory for the value of the environment variable. For information on the debugging features of **_malloc_dbg**, see [_malloc_dbg](malloc-dbg.md). +The **`_dupenv_s_dbg`** and **`_wdupenv_s_dbg`** functions are identical to `_dupenv_s` and `_wdupenv_s` except that, when `_DEBUG` is defined, these functions use the debug version of [`malloc`](malloc.md), [`_malloc_dbg`](malloc-dbg.md), to allocate memory for the value of the environment variable. For information on the debugging features of `_malloc_dbg`, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the flag **_CRTDBG_MAP_ALLOC**. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_dupenv_s** and **_wdupenv_s** are remapped to **_dupenv_s_dbg** and **_wdupenv_s_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information on block types, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the flag `_CRTDBG_MAP_ALLOC`. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_dupenv_s` and `_wdupenv_s` are remapped to **`_dupenv_s_dbg`** and **`_wdupenv_s_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information on block types, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tdupenv_s_dbg**|**_dupenv_s_dbg**|**_dupenv_s_dbg**|**_wdupenv_s_dbg**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tdupenv_s_dbg` | **`_dupenv_s_dbg`** | **`_dupenv_s_dbg`** | **`_wdupenv_s_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_dupenv_s_dbg**|\| -|**_wdupenv_s_dbg**|\| +| Routine | Required header | +|---|---| +| **`_dupenv_s_dbg`** | \ | +| **`_wdupenv_s_dbg`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_dupenv_s_dbg.c -#include +#include #include int main( void ) @@ -115,7 +114,7 @@ nonexistentvariable = (null) ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[Environmental Constants](../../c-runtime-library/environmental-constants.md)
-[getenv_s, _wgetenv_s](getenv-s-wgetenv-s.md)
-[_putenv_s, _wputenv_s](putenv-s-wputenv-s.md)
+[Process and environment control](../process-and-environment-control.md)\ +[Environmental constants](../environmental-constants.md)\ +[`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md)\ +[`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md) diff --git a/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md b/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md index 53149e85ef1..da9fb11032a 100644 --- a/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md +++ b/docs/c-runtime-library/reference/dupenv-s-wdupenv-s.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _dupenv_s, _wdupenv_s" title: "_dupenv_s, _wdupenv_s" +description: "Learn more about: _dupenv_s, _wdupenv_s" ms.date: "4/2/2020" api_name: ["_dupenv_s", "_wdupenv_s", "_o__dupenv_s", "_o__wdupenv_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["tdupenv_s", "_dupenv_s", "wdupenv_s", "dupenv_s", "_tdupenv_s", "_wdupenv_s"] helpviewer_keywords: ["_dupenv_s function", "_tdupenv_s function", "_wdupenv_s function", "environment variables", "wdupenv_s function", "dupenv_s function", "tdupenv_s function"] -ms.assetid: b729ecc2-a31d-4ccf-92a7-5accedb8f8c8 --- # `_dupenv_s`, `_wdupenv_s` @@ -34,62 +33,62 @@ errno_t _wdupenv_s( ### Parameters -*`buffer`*
+*`buffer`*\ Buffer to store the variable's value. -*`numberOfElements`*
+*`numberOfElements`*\ Size of *`buffer`*. -*`varname`*
+*`varname`*\ Environment variable name. -## Return Value +## Return value Zero on success, an error code on failure. -These functions validate their parameters; if *`buffer`* or *`varname`* is **`NULL`**, the invalid parameter handler is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions set **`errno`** to **`EINVAL`** and return **`EINVAL`**. +These functions validate their parameters; if *`buffer`* or *`varname`* is `NULL`, the invalid parameter handler is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions set `errno` to `EINVAL` and return `EINVAL`. -If these functions cannot allocate enough memory, they set *`buffer`* to **`NULL`** and *`numberOfElements`* to 0, and return **`ENOMEM`**. +If these functions can't allocate enough memory, they set *`buffer`* to `NULL` and *`numberOfElements`* to 0, and return `ENOMEM`. ## Remarks -The **`_dupenv_s`** function searches the list of environment variables for *`varname`*. If the variable is found, **`_dupenv_s`** allocates a buffer and copies the variable's value into the buffer. The buffer's address and length are returned in *`buffer`* and *`numberOfElements`*. By allocating the buffer itself, **`_dupenv_s`** provides a more convenient alternative to [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md). +The **`_dupenv_s`** function searches the list of environment variables for *`varname`*. If the variable is found, **`_dupenv_s`** allocates a buffer and copies the variable's value into the buffer. The buffer's address and length are returned in *`buffer`* and *`numberOfElements`*. Because it allocates the buffer itself, **`_dupenv_s`** provides a more convenient alternative to [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md). > [!NOTE] -> It is the calling program's responsibility to free the memory by calling [`free`](free.md). +> It's the calling program's responsibility to free the memory by calling [`free`](free.md). -If the variable is not found, then *`buffer`* is set to **`NULL`**, *`numberOfElements`* is set to 0, and the return value is 0 because this situation is not considered to be an error condition. +If the variable isn't found, then *`buffer`* is set to `NULL`, *`numberOfElements`* is set to 0, and the return value is 0 because this situation isn't considered to be an error condition. -If you are not interested in the size of the buffer you can pass **`NULL`** for *`numberOfElements`*. +If you aren't interested in the size of the buffer, you can pass `NULL` for *`numberOfElements`*. -**`_dupenv_s`** is not case sensitive in the Windows operating system. **`_dupenv_s`** uses the copy of the environment pointed to by the global variable **`_environ`** to access the environment. See the Remarks in [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md) for a discussion of **`_environ`**. +**`_dupenv_s`** isn't case sensitive in the Windows operating system. **`_dupenv_s`** uses the copy of the environment pointed to by the global variable **`_environ`** to access the environment. See the Remarks in [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md) for a discussion of **`_environ`**. The value in *`buffer`* is a copy of the environment variable's value; modifying it has no effect on the environment. Use the [`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md) function to modify the value of an environment variable. **`_wdupenv_s`** is a wide-character version of **`_dupenv_s`**; the arguments of **`_wdupenv_s`** are wide-character strings. The **`_wenviron`** global variable is a wide-character version of **`_environ`**. See the Remarks in [`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md) for more on **`_wenviron`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tdupenv_s`**|**`_dupenv_s`**|**`_dupenv_s`**|**`_wdupenv_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tdupenv_s`** | **`_dupenv_s`** | **`_dupenv_s`** | **`_wdupenv_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_dupenv_s`**|``| -|**`_wdupenv_s`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_dupenv_s`** | `` | +| **`_wdupenv_s`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_dupenv_s.c -#include +#include int main( void ) { @@ -113,8 +112,8 @@ nonexistentvariable = (null) ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[Environmental Constants](../../c-runtime-library/environmental-constants.md)
-[`_dupenv_s_dbg`, `_wdupenv_s_dbg`](dupenv-s-dbg-wdupenv-s-dbg.md)
-[`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md)
-[`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md)
+[Process and environment control](../process-and-environment-control.md)\ +[Environmental constants](../environmental-constants.md)\ +[`_dupenv_s_dbg`, `_wdupenv_s_dbg`](dupenv-s-dbg-wdupenv-s-dbg.md)\ +[`getenv_s`, `_wgetenv_s`](getenv-s-wgetenv-s.md)\ +[`_putenv_s`, `_wputenv_s`](putenv-s-wputenv-s.md) diff --git a/docs/c-runtime-library/reference/ecvt-s.md b/docs/c-runtime-library/reference/ecvt-s.md index ac3690bf2df..ea63b5f07a6 100644 --- a/docs/c-runtime-library/reference/ecvt-s.md +++ b/docs/c-runtime-library/reference/ecvt-s.md @@ -3,100 +3,100 @@ description: "Learn more about: _ecvt_s" title: "_ecvt_s" ms.date: "4/2/2020" api_name: ["_ecvt_s", "_o__ecvt_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ecvt_s", "_ecvt_s"] helpviewer_keywords: ["_ecvt_s function", "ecvt_s function", "numbers, converting", "converting double numbers"] ms.assetid: d52fb0a6-cb91-423f-80b3-952a8955d914 --- -# _ecvt_s +# `_ecvt_s` -Converts a **`double`** number to a string. This is a version of [_ecvt](ecvt.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a **`double`** number to a string. This function is a version of [`_ecvt`](ecvt.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax ```C errno_t _ecvt_s( - char * _Buffer, - size_t _SizeInBytes, - double _Value, - int _Count, - int *_Dec, - int *_Sign + char * buffer, + size_t sizeInBytes, + double value, + int count, + int *dec, + int *sign ); template errno_t _ecvt_s( - char (&_Buffer)[size], - double _Value, - int _Count, - int *_Dec, - int *_Sign + char (&buffer)[size], + double value, + int count, + int *dec, + int *sign ); // C++ only ``` ### Parameters -*_Buffer*
+*`buffer`*\ Filled with the pointer to the string of digits, the result of the conversion. -*_SizeInBytes*
+*`sizeInBytes`*\ Size of the buffer in bytes. -*_Value*
+*`value`*\ Number to be converted. -*_Count*
+*`count`*\ Number of digits stored. -*_Dec*
+*`dec`*\ Stored decimal-point position. -*_Sign*
+*`sign`*\ Sign of the converted number. -## Return Value +## Return value -Zero if successful. The return value is an error code if there is a failure. Error codes are defined in Errno.h. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in Errno.h. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -In the case of an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +If there's an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL`, and returns `EINVAL`. -### Error Conditions +### Error conditions -|*_Buffer*|*_SizeInBytes*|_Value|_Count|_Dec|_Sign|Return value|Value in *buffer*| -|---------------|--------------------|-------------|-------------|-----------|------------|------------------|-----------------------| -|**NULL**|any|any|any|any|any|**EINVAL**|Not modified.| -|Not **NULL** (points to valid memory)|<=0|any|any|any|any|**EINVAL**|Not modified.| -|any|any|any|any|**NULL**|any|**EINVAL**|Not modified.| -|any|any|any|any|any|**NULL**|**EINVAL**|Not modified.| +| *`buffer`* | *`sizeInBytes`* | *`value`* | *`count`* | *`dec`* | *`sign`* | Return value | Value in *`buffer`* | +|---|---|---|---|---|---|---|---| +| `NULL` | any | any | any | any | any | `EINVAL` | Not modified. | +| Not `NULL` (points to valid memory) | <=0 | any | any | any | any | `EINVAL` | Not modified. | +| any | any | any | any | `NULL` | any | `EINVAL` | Not modified. | +| any | any | any | any | any | `NULL` | `EINVAL` | Not modified. | -## Security Issues +## Security issues -**_ecvt_s** might generate an access violation if *buffer* does not point to valid memory and is not **NULL**. +**`_ecvt_s`** might generate an access violation if *`buffer`* doesn't point to valid memory and isn't `NULL`. ## Remarks -The **_ecvt_s** function converts a floating-point number to a character string. The *_Value* parameter is the floating-point number to be converted. This function stores up to *count* digits of *_Value* as a string and appends a null character ('\0'). If the number of digits in *_Value* exceeds *_Count*, the low-order digit is rounded. If there are fewer than *count* digits, the string is padded with zeros. +The **`_ecvt_s`** function converts a floating-point number to a character string. The *`value`* parameter is the floating-point number to be converted. This function stores up to *`count`* digits of *`value`* as a string and appends a null character ('\0'). If the number of digits in *`value`* exceeds *`count`*, the low-order digit is rounded. If there are fewer than *`count`* digits, the string is padded with zeros. -Only digits are stored in the string. The position of the decimal point and the sign of *_Value* can be obtained from *_Dec* and *_Sign* after the call. The *_Dec* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *_Sign* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and *`sign`* after the call. The *`dec`* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *`sign`* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. -A buffer of length **_CVTBUFSIZE** is sufficient for any floating-point value. +A buffer of length `_CVTBUFSIZE` is sufficient for any floating-point value. -The difference between **_ecvt_s** and **_fcvt_s** is in the interpretation of the *_Count* parameter. **_ecvt_s** interprets *_Count* as the total number of digits in the output string, whereas **_fcvt_s** interprets *_Count* as the number of digits after the decimal point. +The difference between **`_ecvt_s`** and `_fcvt_s` is in the interpretation of the *`count`* parameter. **`_ecvt_s`** interprets *`count`* as the total number of digits in the output string, whereas `_fcvt_s` interprets *`count`* as the number of digits after the decimal point. -In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_ecvt_s**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_ecvt_s`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -132,9 +132,9 @@ Converted value: 12000 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt](ecvt.md)
-[_fcvt_s](fcvt-s.md)
-[_gcvt_s](gcvt-s.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt`](ecvt.md)\ +[`_fcvt_s`](fcvt-s.md)\ +[`_gcvt_s`](gcvt-s.md) diff --git a/docs/c-runtime-library/reference/ecvt.md b/docs/c-runtime-library/reference/ecvt.md index f6cb268ae25..0f26c4a7046 100644 --- a/docs/c-runtime-library/reference/ecvt.md +++ b/docs/c-runtime-library/reference/ecvt.md @@ -3,16 +3,16 @@ description: "Learn more about: _ecvt" title: "_ecvt" ms.date: "4/2/2020" api_name: ["_ecvt", "_o__ecvt"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ecvt"] helpviewer_keywords: ["_ecvt function", "numbers, converting", "converting double numbers", "ecvt function"] ms.assetid: a916eb05-92d1-4b5c-8563-093acdb49dc8 --- -# _ecvt +# `_ecvt` -Converts a **`double`** number to a string. A more secure version of this function is available; see [_ecvt_s](ecvt-s.md). +Converts a **`double`** number to a string. A more secure version of this function is available; see [`_ecvt_s`](ecvt-s.md). ## Syntax @@ -27,45 +27,45 @@ char *_ecvt( ### Parameters -*value*
+*`value`*\ Number to be converted. -*count*
+*`count`*\ Number of digits stored. -*dec*
+*`dec`*\ Stored decimal-point position. -*sign*
+*`sign`*\ Sign of the converted number. -## Return Value +## Return value -**_ecvt** returns a pointer to the string of digits; **NULL** if an error occurred. +**`_ecvt`** returns a pointer to the string of digits; `NULL` if an error occurred. ## Remarks -The **_ecvt** function converts a floating-point number to a character string. The *value* parameter is the floating-point number to be converted. This function stores up to *count* digits of *value* as a string and appends a null character ('\0'). If the number of digits in *value* exceeds *count*, the low-order digit is rounded. If there are fewer than *count* digits, the string is padded with zeros. +The **`_ecvt`** function converts a floating-point number to a character string. The *`value`* parameter is the floating-point number to be converted. This function stores up to *`count`* digits of *`value`* as a string and appends a null character ('\0'). If the number of digits in *`value`* exceeds *`count`*, the low-order digit is rounded. If there are fewer than *`count`* digits, the string is padded with zeros. -The total number of digits returned by **_ecvt** will not exceed **_CVTBUFSIZE**. +The total number of digits returned by **`_ecvt`** won't exceed `_CVTBUFSIZE`. -Only digits are stored in the string. The position of the decimal point and the sign of *value* can be obtained from *dec* and *sign* after the call. The *dec* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *sign* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and *`sign`* after the call. The *`dec`* parameter points to an integer value giving the position of the decimal point with respect to the beginning of the string. A 0 or negative integer value indicates that the decimal point lies to the left of the first digit. The *`sign`* parameter points to an integer that indicates the sign of the converted number. If the integer value is 0, the number is positive. Otherwise, the number is negative. -The difference between **_ecvt** and **_fcvt** is in the interpretation of the *count* parameter. **_ecvt** interprets *count* as the total number of digits in the output string, whereas **_fcvt** interprets *count* as the number of digits after the decimal point. +The difference between **`_ecvt`** and `_fcvt` is in the interpretation of the *`count`* parameter. **`_ecvt`** interprets *`count`* as the total number of digits in the output string, whereas `_fcvt` interprets *`count`* as the number of digits after the decimal point. -**_ecvt** and **_fcvt** use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the result of the previous call. +**`_ecvt`** and `_fcvt` use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the result of the previous call. -This function validates its parameters. If *dec* or *sign* is **NULL**, or *count* is 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and **NULL** is returned. +This function validates its parameters. If *`dec`* or *`sign`* is `NULL`, or *`count`* is 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to **EINVAL,** and `NULL` is returned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_ecvt**|\| +| Function | Required header | +|---|---| +| **`_ecvt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,8 +98,8 @@ source: 3.1415926535 buffer: '3141592654' decimal: 1 sign: 0 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_fcvt](fcvt.md)
-[_gcvt](gcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_fcvt`](fcvt.md)\ +[`_gcvt`](gcvt.md) diff --git a/docs/c-runtime-library/reference/endthread-endthreadex.md b/docs/c-runtime-library/reference/endthread-endthreadex.md index dc23e3f6943..c452559de37 100644 --- a/docs/c-runtime-library/reference/endthread-endthreadex.md +++ b/docs/c-runtime-library/reference/endthread-endthreadex.md @@ -3,7 +3,7 @@ description: "Learn more about: _endthread, _endthreadex" title: "_endthread, _endthreadex" ms.date: "4/2/2020" api_name: ["_endthread", "_endthreadex", "_o__endthread", "_o__endthreadex"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_endthread", "endthreadex", "_endthreadex", "endthread"] @@ -32,29 +32,29 @@ Thread exit code. You can call **`_endthread`** or **`_endthreadex`** explicitly to terminate a thread; however, **`_endthread`** or **`_endthreadex`** is called automatically when the thread returns from the routine passed as a parameter to **`_beginthread`** or **`_beginthreadex`**. Terminating a thread with a call to **`endthread`** or **`_endthreadex`** helps ensure proper recovery of resources allocated for the thread. > [!NOTE] -> For an executable file linked with Libcmt.lib, do not call the Win32 [`ExitThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitthread) API; this prevents the run-time system from reclaiming allocated resources. **`_endthread`** and **`_endthreadex`** reclaim allocated thread resources and then call **`ExitThread`**. +> For an executable file linked with Libcmt.lib, do not call the Win32 [`ExitThread`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-exitthread) API; this prevents the run-time system from reclaiming allocated resources. **`_endthread`** and **`_endthreadex`** reclaim allocated thread resources and then call `ExitThread`. -**`_endthread`** automatically closes the thread handle. (This behavior differs from the Win32 **`ExitThread`** API.) Therefore, when you use **`_beginthread`** and **`_endthread`**, don't explicitly close the thread handle by calling the Win32 [`CloseHandle`](/windows/win32/api/handleapi/nf-handleapi-closehandle) API. +**`_endthread`** automatically closes the thread handle. (This behavior differs from the Win32 `ExitThread` API.) Therefore, when you use **`_beginthread`** and **`_endthread`**, don't explicitly close the thread handle by calling the Win32 [`CloseHandle`](/windows/win32/api/handleapi/nf-handleapi-closehandle) API. -Like the Win32 **`ExitThread`** API, **`_endthreadex`** doesn't close the thread handle. Therefore, when you use **`_beginthreadex`** and **`_endthreadex`**, you must close the thread handle by calling the Win32 **`CloseHandle`** API. +Like the Win32 `ExitThread` API, **`_endthreadex`** doesn't close the thread handle. Therefore, when you use **`_beginthreadex`** and **`_endthreadex`**, you must close the thread handle by calling the Win32 `CloseHandle` API. > [!NOTE] > **`_endthread`** and **`_endthreadex`** cause C++ destructors pending in the thread not to be called. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`_endthread`**|``| -|**`_endthreadex`**|``| +| Function | Required header | +|---|---| +| **`_endthread`** | `` | +| **`_endthreadex`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Multithreaded versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Multithreaded versions of the [C run-time libraries](../crt-library-features.md) only. ## Example @@ -62,5 +62,5 @@ See the example for [`_beginthread`](beginthread-beginthreadex.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`_beginthread`, `_beginthreadex`](beginthread-beginthreadex.md) diff --git a/docs/c-runtime-library/reference/eof.md b/docs/c-runtime-library/reference/eof.md index f9d66436964..ebe52efa18a 100644 --- a/docs/c-runtime-library/reference/eof.md +++ b/docs/c-runtime-library/reference/eof.md @@ -3,14 +3,14 @@ description: "Learn more about: _eof" title: "_eof" ms.date: "4/2/2020" api_name: ["_eof", "_o__eof"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_eof"] helpviewer_keywords: ["eof function", "end of file, testing for", "_eof function", "files [C++], end of", "testing, for end-of-file", "end of file"] ms.assetid: 265703f4-d07e-4005-abf3-b1d0cdd9e0b0 --- -# _eof +# `_eof` Tests for end of file (EOF). @@ -24,26 +24,26 @@ int _eof( ### Parameters -*fd*
+*`fd`*\ File descriptor referring to the open file. -## Return Value +## Return value -**_eof** returns 1 if the current position is end of file, or 0 if it is not. A return value of -1 indicates an error; in this case, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EBADF**, which indicates an invalid file descriptor. +**`_eof`** returns 1 if the current position is end of file, or 0 if it isn't. A return value of -1 indicates an error; in this case, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EBADF`, which indicates an invalid file descriptor. ## Remarks -The **_eof** function determines whether the end of the file associated with *fd* has been reached. +The **`_eof`** function determines whether the end of the file associated with *`fd`* has been reached. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_eof**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_eof`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -99,9 +99,9 @@ Number of bytes read = 29 ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[clearerr](clearerr.md)
-[feof](feof.md)
-[ferror](ferror.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Low-level I/O](../low-level-i-o.md)\ +[`clearerr`](clearerr.md)\ +[`feof`](feof.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md b/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md index 0629a5e8766..84e447fee52 100644 --- a/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md +++ b/docs/c-runtime-library/reference/erf-erff-erfl-erfc-erfcf-erfcl.md @@ -1,16 +1,15 @@ --- title: "erf, erff, erfl, erfc, erfcf, erfcl" description: "API reference for erf, erff, erfl, erfc, erfcf, and erfcl; which computes the error function or the complementary error function of a value." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["erff", "erfl", "erf", "erfc", "erfcf", "erfcl", "_o_erf", "_o_erfc", "_o_erfcf", "_o_erfcl", "_o_erff", "_o_erfl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["erfl", "erf", "erff", "erfc", "erfcf", "erfcl"] helpviewer_keywords: ["erfl function", "erff function", "erf function", "erfcl function", "erfcf function", "erfc function"] -ms.assetid: 144d90d3-e437-41c2-a659-cd57596023b5 --- -# erf, erff, erfl, erfc, erfcf, erfcl +# `erf`, `erff`, `erfl`, `erfc`, `erfcf`, `erfcl` Computes the error function or the complementary error function of a value. @@ -47,42 +46,42 @@ float erfcf( long double erfcl( long double x ); -#define erf(X) // Requires C11 or higher -#define erfc(X) // Requires C11 or higher +#define erf(X) // Requires C11 or later +#define erfc(X) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ A floating-point value. -## Return Value +## Return value -The **erf** functions return the Gauss error function of *x*. The **erfc** functions return the complementary Gauss error function of *x*. +The **`erf`** functions return the Gauss error function of *`x`*. The **`erfc`** functions return the complementary Gauss error function of *`x`*. ## Remarks -The **erf** functions calculate the Gauss error function of *x*, which is defined as: +The **`erf`** functions calculate the Gauss error function of *`x`*, which is defined as: ![The error function of x equals two over the square root of pi times the integral from zero to x of e to the minus t squared d t. ](media/crt_erf_formula.PNG "The error function of x") -The complementary Gauss error function is defined as 1 - erf(x). The **erf** functions return a value in the range -1.0 to 1.0. There's no error return. The **erfc** functions return a value in the range 0 to 2. If *x* is too large for **erfc**, the **errno** variable is set to **ERANGE**. +The complementary Gauss error function is defined as 1 - erf(x). The **`erf`** functions return a value in the range -1.0 to 1.0. There's no error return. The **`erfc`** functions return a value in the range 0 to 2. If *`x`* is too large for **`erfc`**, the `errno` variable is set to `ERANGE`. -Because C++ allows overloading, you can call overloads of **erf** and **erfc** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **erf** and **erfc** always take and return a **`double`**. +Because C++ allows overloading, you can call **`erf`** and **`erfc`** overloads that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`erf`** and **`erfc`** always take and return a **`double`**. -If you use the \ `erf()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `erf()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**erf**, **erff**, **erfl**, **erfc**, **erfcf**, **erfcl**|\| -|**erf** macro | \ | +| Function | Required header | +|---|---| +| **`erf`**, **`erff`**, **`erfl`**, **`erfc`**, **`erfcf`**, **`erfcl`** | \ | +| **`erf`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
+[Math and floating-point support](../floating-point-support.md) diff --git a/docs/c-runtime-library/reference/execl-wexecl.md b/docs/c-runtime-library/reference/execl-wexecl.md index b69916fb53d..2d3fd94167e 100644 --- a/docs/c-runtime-library/reference/execl-wexecl.md +++ b/docs/c-runtime-library/reference/execl-wexecl.md @@ -10,7 +10,7 @@ f1_keywords: ["_execl", "_wexecl", "wexecl"] helpviewer_keywords: ["_execl function", "wexecl function", "_wexecl function", "execl function"] ms.assetid: 81fefb8a-0a06-4221-b2bc-be18e38e89f4 --- -# _execl, _wexecl +# `_execl`, `_wexecl` Loads and executes new child processes. @@ -36,52 +36,52 @@ intptr_t _wexecl( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to be executed. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to the parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|errno value|Description| -|-----------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter (one or more of the parameters was a null pointer or empty string).| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path is not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter (one or more of the parameters was a null pointer or empty string). | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path isn't found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | ## Remarks Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter. The first argument is the command or executable file name, and the second argument should be the same as the first. It becomes `argv[0]` in the executed process. The third argument is the first argument, `argv[1]`, of the process being executed. -The **_execl** functions validate their parameters. If either *cmdname* or *arg0* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is executed. +The **`_execl`** functions validate their parameters. If either *`cmdname`* or *`arg0`* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md) If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is executed. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execl**|\|\| -|**_wexecl**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execl`** | \ | \ | +| **`_wexecl`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execle-wexecle.md b/docs/c-runtime-library/reference/execle-wexecle.md index 01b939e874a..4eebea6a6c2 100644 --- a/docs/c-runtime-library/reference/execle-wexecle.md +++ b/docs/c-runtime-library/reference/execle-wexecle.md @@ -10,7 +10,7 @@ f1_keywords: ["wexecle", "_execle", "_wexecle"] helpviewer_keywords: ["wexecle function", "execle function", "_wexecle function", "_execle function"] ms.assetid: 75efa9c5-96b7-4e23-acab-06258901f63a --- -# _execle, _wexecle +# `_execle`, `_wexecle` Loads and executes new child processes. @@ -38,57 +38,57 @@ intptr_t _wexecle( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space that's required for the arguments and the environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files are open. (The specified file must be opened to determine whether it is executable.)| -|**ENOENT**|The file or path is not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process was not allocated correctly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space that's required for the arguments and the environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files are open. (The specified file must be opened to determine whether it's executable.) | +| `ENOENT` | The file or path isn't found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process wasn't allocated correctly. | -For more information about these return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions loads and executes a new process, and passes each command-line argument as a separate parameter and passes an array of pointers to environment settings. -The **_execle** functions validate their parameters. If *cmdname* or *arg0* is a null pointer or an empty string, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is launched. +The **`_execle`** functions validate their parameters. If *`cmdname`* or *`arg0`* is a null pointer or an empty string, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is launched. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execle**|\|\| -|**_wexecle**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execle`** | \ | \ | +| **`_wexecle`** | \ or \ | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execle.md b/docs/c-runtime-library/reference/execle.md index 21af98255b0..860ad2858ca 100644 --- a/docs/c-runtime-library/reference/execle.md +++ b/docs/c-runtime-library/reference/execle.md @@ -10,11 +10,11 @@ f1_keywords: ["execle"] helpviewer_keywords: ["execle function"] ms.assetid: 5985b615-fe90-4d1c-9c1d-13ec87c8e306 --- -# execle +# `execle` -The Microsoft-implemented POSIX function name `execle` is a deprecated alias for the [_execle](execle-wexecle.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execle` is a deprecated alias for the [`_execle`](execle-wexecle.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execle](execle-wexecle.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execle`](execle-wexecle.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execlp-wexeclp.md b/docs/c-runtime-library/reference/execlp-wexeclp.md index 42edae9d98b..f10fca130ed 100644 --- a/docs/c-runtime-library/reference/execlp-wexeclp.md +++ b/docs/c-runtime-library/reference/execlp-wexeclp.md @@ -10,7 +10,7 @@ f1_keywords: ["_wexeclp", "wexeclp", "_execlp"] helpviewer_keywords: ["execlp function", "_execlp function", "_wexeclp function", "wexeclp function"] ms.assetid: 7b179163-4bcd-4d6a-8baf-68f886791928 --- -# _execlp, _wexeclp +# `_execlp`, `_wexeclp` Loads and executes new child processes. @@ -36,54 +36,54 @@ intptr_t _wexeclp( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and using the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and using the `PATH` environment variable to find the file to execute. -The **_execlp** functions validate their parameters. If *cmdname* or *arg0* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is launched. +The **`_execlp`** functions validate their parameters. If *`cmdname`* or *`arg0`* is a null pointer or empty string, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is launched. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execlp**|\|\| -|**_wexeclp**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execlp`** | \ | \ | +| **`_wexeclp`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execlp.md b/docs/c-runtime-library/reference/execlp.md index fcddb73c071..969b7278bf3 100644 --- a/docs/c-runtime-library/reference/execlp.md +++ b/docs/c-runtime-library/reference/execlp.md @@ -10,11 +10,11 @@ f1_keywords: ["execlp"] helpviewer_keywords: ["execlp function"] ms.assetid: 68b19143-e7b1-49c6-89b5-084d0d66de9c --- -# execlp +# `execlp` -The Microsoft-implemented POSIX function name `execlp` is a deprecated alias for the [_execlp](execlp-wexeclp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execlp` is a deprecated alias for the [`_execlp`](execlp-wexeclp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execlp](execlp-wexeclp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execlp`](execlp-wexeclp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execlpe-wexeclpe.md b/docs/c-runtime-library/reference/execlpe-wexeclpe.md index 92c28286707..486aa1d97c0 100644 --- a/docs/c-runtime-library/reference/execlpe-wexeclpe.md +++ b/docs/c-runtime-library/reference/execlpe-wexeclpe.md @@ -10,7 +10,7 @@ f1_keywords: ["_wexeclpe", "wexeclpe", "_execlpe"] helpviewer_keywords: ["wexeclpe function", "_wexeclpe function", "_execlpe function", "execlpe function"] ms.assetid: 07b861da-3e7e-4f1d-bb80-ad69b55e5162 --- -# _execlpe, _wexeclpe +# `_execlpe`, `_wexeclpe` Loads and executes new child processes. @@ -38,57 +38,57 @@ intptr_t _wexeclpe( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*arg0*, ... *argn*
+*`arg0`*, ... *`argN`*\ List of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and also passing an array of pointers to environment settings. These functions use the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, passing each command-line argument as a separate parameter and also passing an array of pointers to environment settings. These functions use the `PATH` environment variable to find the file to execute. -The **_execlpe** functions validate their parameters. If either *cmdname* or *arg0* is a null pointers or empty string, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No new process is launched. +The **`_execlpe`** functions validate their parameters. If either *`cmdname`* or *`arg0`* is a null pointers or empty string, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No new process is launched. ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execlpe**|\|\| -|**_wexeclpe**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execlpe`** | \ | \ | +| **`_wexeclpe`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execlpe.md b/docs/c-runtime-library/reference/execlpe.md index 5c08778fc64..f0d113390cb 100644 --- a/docs/c-runtime-library/reference/execlpe.md +++ b/docs/c-runtime-library/reference/execlpe.md @@ -10,11 +10,11 @@ f1_keywords: ["execlpe"] helpviewer_keywords: ["execlpe function"] ms.assetid: 33b28785-43e3-4971-b139-33743a7c9a32 --- -# execlpe +# `execlpe` -The Microsoft-specific function name `execlpe` is a deprecated alias for the [_execlpe](execlpe-wexeclpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `execlpe` is a deprecated alias for the [`_execlpe`](execlpe-wexeclpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execlpe](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execlpe`](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execv-wexecv.md b/docs/c-runtime-library/reference/execv-wexecv.md index 9eefcc60a51..4b11b47296b 100644 --- a/docs/c-runtime-library/reference/execv-wexecv.md +++ b/docs/c-runtime-library/reference/execv-wexecv.md @@ -3,14 +3,14 @@ description: "Learn more about: _execv, _wexecv" title: "_execv, _wexecv" ms.date: "4/2/2020" api_name: ["_wexecv", "_execv", "_o__execv", "_o__wexecv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_execv", "_wexecv", "wexecv"] helpviewer_keywords: ["_wexecv function", "_execv function", "wexecv function", "execv function"] ms.assetid: 8dbaf7bc-9040-4316-a0c1-db7e866b52af --- -# _execv, _wexecv +# `_execv`, `_wexecv` Loads and executes new child processes. @@ -32,56 +32,56 @@ intptr_t _wexecv( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments. -The **_execv** functions validate their parameters. If *cmdname* is a null pointer, or if *argv* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, the **_execv** functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +The **`_execv`** functions validate their parameters. If *`cmdname`* is a null pointer, or if *`argv`* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, the **`_execv`** functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return -1. No process is launched. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execv**|\|\| -|**_wexecv**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execv`** | \ | \ | +| **`_wexecv`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execv.md b/docs/c-runtime-library/reference/execv.md index 423925a59de..248b1cfd9b4 100644 --- a/docs/c-runtime-library/reference/execv.md +++ b/docs/c-runtime-library/reference/execv.md @@ -10,11 +10,11 @@ f1_keywords: ["execv"] helpviewer_keywords: ["execv function"] ms.assetid: b097d606-9384-427a-9a1d-707dc4ce03ae --- -# execv +# `execv` -The Microsoft-implemented POSIX function name `execv` is a deprecated alias for the [_execv](execv-wexecv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execv` is a deprecated alias for the [`_execv`](execv-wexecv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execv](execv-wexecv.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execv`](execv-wexecv.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execve-wexecve.md b/docs/c-runtime-library/reference/execve-wexecve.md index 2134987b05c..e1561aefbcc 100644 --- a/docs/c-runtime-library/reference/execve-wexecve.md +++ b/docs/c-runtime-library/reference/execve-wexecve.md @@ -3,14 +3,14 @@ description: "Learn more about: _execve, _wexecve" title: "_execve, _wexecve" ms.date: "4/2/2020" api_name: ["_execve", "_wexecve", "_o__execve", "_o__wexecve"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wexecve", "_wexecve", "_execve"] helpviewer_keywords: ["execve function", "wexecve function", "_execve function", "_wexecve function"] ms.assetid: 950d4802-a9c3-4f32-8145-a0119dd1d596 --- -# _execve, _wexecve +# `_execve`, `_wexecve` Loads and executes new child processes. @@ -34,59 +34,65 @@ intptr_t _wexecve( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments and an array of pointers to environment settings. -**_execve** and **_wexecve** validate their parameters. If *cmdname* is a null pointer, or if *argv* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +**`_execve`** and **`_wexecve`** validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +- *`cmdname`* is a null pointer, +- *`argv`* is either a null pointer or pointer to an empty array, +- the array contains an empty string as the first argument. + +If execution is allowed to continue by the handler, these functions set `errno` to `EINVAL`, and return -1. No process is launched. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execve**|\|\| -|**_wexecve**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execve`** | \ | \ | +| **`_wexecve`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execve.md b/docs/c-runtime-library/reference/execve.md index 7764e132c85..a0b12939078 100644 --- a/docs/c-runtime-library/reference/execve.md +++ b/docs/c-runtime-library/reference/execve.md @@ -10,11 +10,11 @@ f1_keywords: ["execve"] helpviewer_keywords: ["execve function"] ms.assetid: f28aabe4-fd76-422e-a0e4-80864736d245 --- -# execve +# `execve` -The Microsoft-implemented POSIX function name `execve` is a deprecated alias for the [_execve](execve-wexecve.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execve` is a deprecated alias for the [`_execve`](execve-wexecve.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execve](execve-wexecve.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execve`](execve-wexecve.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execvp-wexecvp.md b/docs/c-runtime-library/reference/execvp-wexecvp.md index 55228ac845c..1236bc4ff49 100644 --- a/docs/c-runtime-library/reference/execvp-wexecvp.md +++ b/docs/c-runtime-library/reference/execvp-wexecvp.md @@ -3,14 +3,14 @@ description: "Learn more about: _execvp, _wexecvp" title: "_execvp, _wexecvp" ms.date: "4/2/2020" api_name: ["_execvp", "_wexecvp", "_o__execvp", "_o__wexecvp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_execvp", "wexecvp", "_wexecvp"] helpviewer_keywords: ["_execvp function", "_wexecvp function", "wexecvp function", "execvp function"] ms.assetid: a4db15df-b204-4987-be7c-de84c3414380 --- -# _execvp, _wexecvp +# `_execvp`, `_wexecvp` Loads and executes new child processes. @@ -32,56 +32,62 @@ intptr_t _wexecvp( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EINVAL**|Invalid parameter.| -|**EMFILE**|Too many files open (the specified file must be opened to determine whether it is executable).| -|**ENOENT**|The file or path not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process was not allocated properly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EINVAL` | Invalid parameter. | +| `EMFILE` | Too many files open (the specified file must be opened to determine whether it's executable). | +| `ENOENT` | The file or path not found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, indicating that the calling process wasn't allocated properly. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments and using the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, passing an array of pointers to command-line arguments and using the `PATH` environment variable to find the file to execute. -The **_execvp** functions validate their parameters. If the *cmdname* is a null pointer, or *argv* is a null pointer, pointer to an empty array, or if the array contains an empty string as the first argument, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +The **`_execvp`** functions validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +- *`cmdname`* is a null pointer, +- *`argv`* is either a null pointer or pointer to an empty array, +- the array contains an empty string as the first argument. + +If execution is allowed to continue by the handler, these functions set `errno` to `EINVAL`, and return -1. No process is launched. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execvp**|\|\| -|**_wexecvp**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execvp`** | \ | \ | +| **`_wexecvp`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execvp.md b/docs/c-runtime-library/reference/execvp.md index 8a7a40a488a..4306af58b89 100644 --- a/docs/c-runtime-library/reference/execvp.md +++ b/docs/c-runtime-library/reference/execvp.md @@ -10,11 +10,11 @@ f1_keywords: ["execvp"] helpviewer_keywords: ["execvp function"] ms.assetid: a0d0e898-9f06-4aa9-94ce-3ad317318c3a --- -# execvp +# `execvp` -The Microsoft-implemented POSIX function name `execvp` is a deprecated alias for the [_execvp](execvp-wexecvp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `execvp` is a deprecated alias for the [`_execvp`](execvp-wexecvp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execvp](execvp-wexecvp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execvp`](execvp-wexecvp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/execvpe-wexecvpe.md b/docs/c-runtime-library/reference/execvpe-wexecvpe.md index c563d386c52..84548d549ef 100644 --- a/docs/c-runtime-library/reference/execvpe-wexecvpe.md +++ b/docs/c-runtime-library/reference/execvpe-wexecvpe.md @@ -3,14 +3,14 @@ description: "Learn more about: _execvpe, _wexecvpe" title: "_execvpe, _wexecvpe" ms.date: "4/2/2020" api_name: ["_execvpe", "_wexecvpe", "_o__execvpe", "_o__wexecvpe"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-process-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wexecvpe", "_wexecvpe", "_execvpe"] helpviewer_keywords: ["wexecvpe function", "execvpe function", "_wexecvpe function", "_execvpe function"] ms.assetid: c0c3c986-d9c0-4814-a96c-10f0b3092766 --- -# _execvpe, _wexecvpe +# `_execvpe`, `_wexecvpe` Loads and runs new child processes. @@ -34,58 +34,64 @@ intptr_t _wexecvpe( ### Parameters -*cmdname*
+*`cmdname`*\ Path of the file to execute. -*argv*
+*`argv`*\ Array of pointers to parameters. -*envp*
+*`envp`*\ Array of pointers to environment settings. -## Return Value +## Return value -If successful, these functions do not return to the calling process. A return value of -1 indicates an error, in which case the **errno** global variable is set. +If successful, these functions don't return to the calling process. A return value of -1 indicates an error, in which case the `errno` global variable is set. -|**errno** value|Description| -|-------------------|-----------------| -|**E2BIG**|The space that's required for the arguments and environment settings exceeds 32 KB.| -|**EACCES**|The specified file has a locking or sharing violation.| -|**EMFILE**|Too many files are open. (The specified file must be opened to determine whether it is executable.)| -|**ENOENT**|The file or path is not found.| -|**ENOEXEC**|The specified file is not executable or has an invalid executable-file format.| -|**ENOMEM**|Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process was not allocated correctly.| +| `errno` value | Description | +|---|---| +| `E2BIG` | The space that's required for the arguments and environment settings exceeds 32 KB. | +| `EACCES` | The specified file has a locking or sharing violation. | +| `EMFILE` | Too many files are open. (The specified file must be opened to determine whether it's executable.) | +| `ENOENT` | The file or path isn't found. | +| `ENOEXEC` | The specified file isn't executable or has an invalid executable-file format. | +| `ENOMEM` | Not enough memory is available to execute the new process; the available memory has been corrupted; or an invalid block exists, which indicates that the calling process wasn't allocated correctly. | -For more information about these and other return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions loads and executes a new process, and passes an array of pointers to command-line arguments and an array of pointers to environment settings. These functions use the **PATH** environment variable to find the file to execute. +Each of these functions loads and executes a new process, and passes an array of pointers to command-line arguments and an array of pointers to environment settings. These functions use the `PATH` environment variable to find the file to execute. -The **_execvpe** functions validate their parameters. If the *cmdname* is a null pointer, or if *argv* is a null pointer, a pointer to an empty array, or a pointer to an array that contains an empty string as the first argument, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return -1. No process is launched. +The **`_execvpe`** functions validate their parameters. These functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md), when: -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +- *`cmdname`* is a null pointer, +- *`argv`* is either a null pointer or pointer to an empty array, +- the array contains an empty string as the first argument. + +If execution is allowed to continue by the handler, these functions set `errno` to `EINVAL`, and return -1. No process is launched. + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_execvpe**|\|\| -|**_wexecvpe**|\ or \|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_execvpe`** | \ | \ | +| **`_wexecvpe`** | \ or \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md). +See the example in [`_exec`, `_wexec` functions](../exec-wexec-functions.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/execvpe.md b/docs/c-runtime-library/reference/execvpe.md index 979b2276ed5..5ecc9361123 100644 --- a/docs/c-runtime-library/reference/execvpe.md +++ b/docs/c-runtime-library/reference/execvpe.md @@ -10,11 +10,11 @@ f1_keywords: ["execvpe"] helpviewer_keywords: ["execvpe function"] ms.assetid: ee657071-c459-4bb6-82a2-8925c888f624 --- -# execvpe +# `execvpe` -The Microsoft-specific function name `execvpe` is a deprecated alias for the [_execvpe](execvpe-wexecvpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `execvpe` is a deprecated alias for the [`_execvpe`](execvpe-wexecvpe.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_execvpe](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_execvpe`](execlpe-wexeclpe.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/exit-exit-exit.md b/docs/c-runtime-library/reference/exit-exit-exit.md index 01e0c7cd8e9..1736f05b272 100644 --- a/docs/c-runtime-library/reference/exit-exit-exit.md +++ b/docs/c-runtime-library/reference/exit-exit-exit.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: exit, _Exit, _exit" title: "exit, _Exit, _exit" -ms.date: "4/2/2020" +description: "Learn more about: exit, _Exit, _exit" +ms.date: 4/2/2020 api_name: ["_exit", "exit", "_o__exit", "_o_exit"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["Exit", "_exit", "process/exit", "process/_Exit", "stdlib/exit", "stdlib/_Exit"] @@ -14,7 +14,7 @@ helpviewer_keywords: ["exit function", "_exit function", "processes, terminating Terminates the calling process. The **`exit`** function terminates it after cleanup; **`_exit`** and **`_Exit`** terminate it immediately. > [!NOTE] -> Do not use this method to shut down a Universal Windows Platform (UWP) app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP App lifecycle](/windows/uwp/launch-resume/app-lifecycle). For more information about UWP apps, see [Universal Windows Platform documentation](https://developer.microsoft.com/windows/apps). +> Do not use this method to shut down a Universal Windows Platform (UWP) app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). For more information about UWP apps, see [Universal Windows Platform documentation](https://developer.microsoft.com/windows/apps). ## Syntax @@ -32,27 +32,27 @@ void _exit( ### Parameters -*`status`*
+*`status`*\ Exit status code. ## Remarks The **`exit`**, **`_Exit`** and **`_exit`** functions terminate the calling process. The **`exit`** function calls destructors for thread-local objects, then calls—in last-in-first-out (LIFO) order—the functions that are registered by **`atexit`** and **`_onexit`**, and then flushes all file buffers before it terminates the process. The **`_Exit`** and **`_exit`** functions terminate the process without destroying thread-local objects or processing **`atexit`** or **`_onexit`** functions, and without flushing stream buffers. -Although the **`exit`**, **`_Exit`** and **`_exit`** calls do not return a value, the value in *`status`* is made available to the host environment or waiting calling process, if one exists, after the process exits. Typically, the caller sets the *`status`* value to 0 to indicate a normal exit, or to some other value to indicate an error. The *`status`* value is available to the operating-system batch command **`ERRORLEVEL`** and is represented by one of two constants: **`EXIT_SUCCESS`**, which represents a value of 0, or **`EXIT_FAILURE`**, which represents a value of 1. +Although the **`exit`**, **`_Exit`** and **`_exit`** calls don't return a value, the value in *`status`* is made available to the host environment or waiting calling process, if one exists, after the process exits. Typically, the caller sets the *`status`* value to 0 to indicate a normal exit, or to some other value to indicate an error. The *`status`* value is available to the operating-system batch command `ERRORLEVEL` and is represented by one of two constants: `EXIT_SUCCESS`, which represents a value of 0, or `EXIT_FAILURE`, which represents a value of 1. The **`exit`**, **`_Exit`**, **`_exit`**, **`quick_exit`**, **`_cexit`**, and **`_c_exit`** functions behave as follows. -|Function|Description| -|--------------|-----------------| -|**`exit`**|Performs complete C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`_Exit`**|Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`_exit`**|Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`quick_exit`**|Performs quick C library termination procedures, terminates the process, and provides the supplied status code to the host environment.| -|**`_cexit`**|Performs complete C library termination procedures and returns to the caller. Does not terminate the process.| -|**`_c_exit`**|Performs minimal C library termination procedures and returns to the caller. Does not terminate the process.| +| Function | Description | +|---|---| +| **`exit`** | Performs complete C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`_Exit`** | Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`_exit`** | Performs minimal C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`quick_exit`** | Performs quick C library termination procedures, terminates the process, and provides the supplied status code to the host environment. | +| **`_cexit`** | Performs complete C library termination procedures and returns to the caller. Doesn't terminate the process. | +| **`_c_exit`** | Performs minimal C library termination procedures and returns to the caller. Doesn't terminate the process. | -When you call the **`exit`**, **`_Exit`** or **`_exit`** function, the destructors for any temporary or automatic objects that exist at the time of the call are not called. An automatic object is a non-static local object defined in a function. A temporary object is an object that's created by the compiler, such as a value returned by a function call. To destroy an automatic object before you call **`exit`**, **`_Exit`**, or **`_exit`**, explicitly call the destructor for the object, as shown here: +When you call the **`exit`**, **`_Exit`** or **`_exit`** function, the destructors for any temporary or automatic objects that exist at the time of the call aren't called. An automatic object is a non-static local object defined in a function. A temporary object is an object that's created by the compiler, such as a value returned by a function call. To destroy an automatic object before you call **`exit`**, **`_Exit`**, or **`_exit`**, explicitly call the destructor for the object, as shown here: ```cpp void last_fn() {} @@ -63,17 +63,17 @@ void last_fn() {} } ``` -Do not use **`DLL_PROCESS_ATTACH`** to call **`exit`** from **`DllMain`**. To exit the **`DLLMain`** function, return **`FALSE`** from **`DLL_PROCESS_ATTACH`**. +Don't use `DLL_PROCESS_ATTACH` to call **`exit`** from `DllMain`. To exit the `DLLMain` function, return `FALSE` from `DLL_PROCESS_ATTACH`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`exit`**, **`_Exit`**, **`_exit`**|`` or ``| +| Function | Required header | +|---|---| +| **`exit`**, **`_Exit`**, **`_exit`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -92,12 +92,12 @@ int main( void ) ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[`abort`](abort.md)
-[`atexit`](atexit.md)
-[`_cexit`, `_c_exit`](cexit-c-exit.md)
-[`_exec`, `_wexec` Functions](../../c-runtime-library/exec-wexec-functions.md)
-[`_onexit`, `_onexit_m`](onexit-onexit-m.md)
-[`quick_exit`](quick-exit1.md)
-[`_spawn`, `_wspawn` Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[`system`, `_wsystem`](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_cexit`, `_c_exit`](cexit-c-exit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`quick_exit`](quick-exit1.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/exp-expf.md b/docs/c-runtime-library/reference/exp-expf.md index e96a61e96cb..b79dcacd4c9 100644 --- a/docs/c-runtime-library/reference/exp-expf.md +++ b/docs/c-runtime-library/reference/exp-expf.md @@ -1,9 +1,9 @@ --- title: "exp, expf, expl" description: "API reference for exp, expf, and expl; which calculate the exponential." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["expf", "expl", "exp", "_o_exp", "_o_expf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_expl", "expf", "expl", "exp"] @@ -31,7 +31,7 @@ float expf( long double expl( long double x ); -#define exp(z) // Requires C11 or higher +#define exp(z) // Requires C11 or later ``` ### Parameters @@ -39,16 +39,16 @@ long double expl( *`x`*\ The floating-point value to exponentiate the natural logarithm base *e* by. -## Return Value +## Return value The **`exp`** functions return the exponential value of the floating-point parameter, *`x`*, if successful. That is, the result is *e**`x`*, where *e* is the base of the natural logarithm. On overflow, the function returns `INF` (infinity) and on underflow, **`exp`** returns 0. -|Input|SEH exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|± Quiet NaN, indeterminate|None|`_DOMAIN`| -|± Infinity|`INVALID`|`_DOMAIN`| -|x ≥ 7.097827e+002|`INEXACT+OVERFLOW`|`OVERFLOW`| -|X ≤ -7.083964e+002|`INEXACT+UNDERFLOW`|`UNDERFLOW`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± Quiet NaN, indeterminate | None | `_DOMAIN` | +| ± Infinity | `INVALID` | `_DOMAIN` | +| *`x`* ≥ 7.097827e+002 | `INEXACT`+`OVERFLOW` | `OVERFLOW` | +| *`x`* ≤ -7.083964e+002 | `INEXACT`+`UNDERFLOW` | `UNDERFLOW` | The **`exp`** function has an implementation that uses Streaming SIMD Extensions 2 (SSE2). See [`_set_SSE2_enable`](set-sse2-enable.md) for information and restrictions on using the SSE2 implementation. @@ -56,18 +56,18 @@ The **`exp`** function has an implementation that uses Streaming SIMD Extensions C++ allows overloading, so you can call overloads of **`exp`** that take a **`float`** or **`long double`** argument. In a C program, unless you're using the `` macro to call this function, **`exp`** always takes and returns a **`double`**. -If you use the `` `exp()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `exp` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required C header|Required C++ header| -|--------------|---------------------|---| -|**`exp`**, **`expf`**, **`expl`**|``|`` or ``| -|**`exp`** macro| `` || +| Function | Required C header | Required C++ header | +|---|---|---| +| **`exp`**, **`expf`**, **`expl`** | `` | `` or `` | +| **`exp`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -92,6 +92,6 @@ exp( 2.302585 ) = 10.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[`log, logf, log10, log10f`](log-logf-log10-log10f.md)\ -[`_CIexp`](../../c-runtime-library/ciexp.md) +[Math and floating-point support](../floating-point-support.md)\ +[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ +[`_CIexp`](../ciexp.md) diff --git a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md index 8d1792c2aa5..472d0cd5ce2 100644 --- a/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md +++ b/docs/c-runtime-library/reference/exp2-exp2f-exp2l.md @@ -1,16 +1,15 @@ --- title: "exp2, exp2f, exp2l" description: "API ref for exp2(), exp2f(), and exp2l() which compute 2 raised to the specified value." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["exp2", "exp2f", "exp2l", "_o_exp2", "_o_exp2f", "_o_exp2l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["exp2", "math/exp2", "exp2f", "math/exp2f", "exp2l", "math/exp2l"] helpviewer_keywords: ["exp2 function", "exp2f function", "exp2l function"] -ms.assetid: 526e3e10-201a-4610-a886-533f44ece344 --- -# exp2, exp2f, exp2l +# `exp2`, `exp2f`, `exp2l` Computes 2 raised to the specified value. @@ -36,48 +35,48 @@ float exp2f( long double exp2l( long double x ); -#define exp2(X) // Requires C11 or higher +#define exp2(X) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ The value of the exponent. -## Return Value +## Return value -If successful, returns the base-2 exponent of *x*, that is, 2x. Otherwise, it returns one of the following values: +If successful, returns the base-2 exponent of *`x`*, that is, 2x. Otherwise, it returns one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = ±0|1| -|*x* = -INFINITY|+0| -|*x* = +INFINITY|+INFINITY| -|*x* = NaN|NaN| -|Overflow range error|+HUGE_VAL, +HUGE_VALF, or +HUGE_VALL| -|Underflow range error|Correct result, after rounding| +| Issue | Return | +|---|---| +| *`x`* = ±0 | 1 | +| *`x`* = -INFINITY | +0 | +| *`x`* = +INFINITY | +INFINITY | +| *`x`* = NaN | NaN | +| Overflow range error | +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL | +| Underflow range error | Correct result, after rounding | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **exp2** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **exp2** always takes and returns a **`double`**, unless you use the macro in \. +Because C++ allows overloading, you can call overloads of **`exp2`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`exp2`** always takes and returns a **`double`**, unless you use the macro in \. -If you use the \ `exp2()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `exp2()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**exp2**, **expf2**, **expl2**|\|\| -|**exp2** macro | \ || +| Routine | C header | C++ header | +|---|---|---| +| **`exp2`**, **`expf2`**, **`expl2`** | \ | \ | +| **`exp2`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[exp, expf, expl](exp-expf.md)
-[log2, log2f, log2l](log2-log2f-log2l.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`exp`, `expf`, `expl`](exp-expf.md)\ +[`log2`, `log2f`, `log2l`](log2-log2f-log2l.md) diff --git a/docs/c-runtime-library/reference/expand-dbg.md b/docs/c-runtime-library/reference/expand-dbg.md index ead55af3a48..04f87e4d632 100644 --- a/docs/c-runtime-library/reference/expand-dbg.md +++ b/docs/c-runtime-library/reference/expand-dbg.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _expand_dbg" title: "_expand_dbg" -ms.date: "11/04/2016" +description: "Learn more about: _expand_dbg" +ms.date: 11/04/2016 api_name: ["_expand_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: ["expand_dbg", "_expand_dbg"] helpviewer_keywords: ["memory blocks, changing size", "expand_dbg function", "_expand_dbg function"] -ms.assetid: dc58c91f-72a8-48c6-b643-fe130fb6c1fd --- -# _expand_dbg +# `_expand_dbg` Resizes a specified block of memory in the heap by expanding or contracting the block (debug version only). @@ -22,56 +21,56 @@ void *_expand_dbg( size_t newSize, int blockType, const char *filename, - int linenumber + int lineNumber ); ``` ### Parameters -*userData*
+*`userData`*\ Pointer to the previously allocated memory block. -*newSize*
+*`newSize`*\ Requested new size for the block (in bytes). -*blockType*
-Requested type for resized block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type for resized block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested expand operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested expand operation or `NULL`. -*linenumber*
-Line number in the source file where the expand operation was requested or **NULL**. +*`lineNumber`*\ +Line number in the source file where the expand operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_expand_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`lineNumber`* parameters are only available when **`_expand_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, **_expand_dbg** returns a pointer to the resized memory block. Because the memory is not moved, the address is the same as the userData. If an error occurred or the block could not be expanded to the requested size, it returns **NULL**. If a failure occurs, **errno** is with information from the operating system about the nature of the failure. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +On successful completion, **`_expand_dbg`** returns a pointer to the resized memory block. Because the memory isn't moved, the address is the same as the userData. If an error occurred or the block couldn't be expanded to the requested size, it returns `NULL`. If a failure occurs, `errno` is with information from the operating system about the nature of the failure. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_expand_dbg** function is a debug version of the _[expand](expand.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_expand_dbg** is reduced to a call to **_expand**. Both **_expand** and **_expand_dbg** resize a memory block in the base heap, but **_expand_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *filename*/*linenumber* information to determine the origin of allocation requests. +The **`_expand_dbg`** function is a debug version of the [`_expand`](expand.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_expand_dbg`** is reduced to a call to `_expand`. Both `_expand` and **`_expand_dbg`** resize a memory block in the base heap, but **`_expand_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *`filename`*/*`lineNumber`* information to determine the origin of allocation requests. -**_expand_dbg** resizes the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The resize is accomplished by either expanding or contracting the original memory block. **_expand_dbg** does not move the memory block, as does the [_realloc_dbg](realloc-dbg.md) function. +**`_expand_dbg`** resizes the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The resize is accomplished by either expanding or contracting the original memory block. **`_expand_dbg`** doesn't move the memory block, as does the [`_realloc_dbg`](realloc-dbg.md) function. -When *newSize* is greater than the original block size, the memory block is expanded. During an expansion, if the memory block cannot be expanded to accommodate the requested size, **NULL** is returned. When *newSize* is less than the original block size, the memory block is contracted until the new size is obtained. +When *`newSize`* is greater than the original block size, the memory block is expanded. During an expansion, if the memory block can't be expanded to accommodate the requested size, `NULL` is returned. When *`newSize`* is less than the original block size, the memory block is contracted until the new size is obtained. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). -This function validates its parameters. If *memblock* is a null pointer, or if size is greater than **_HEAP_MAXREQ**, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. +This function validates its parameters. If *`userData`* is a null pointer, or if size is greater than `_HEAP_MAXREQ`, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_expand_dbg**|\| +| Routine | Required header | +|---|---| +| **`_expand_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -132,5 +131,5 @@ The output of this program depends on your computer's ability to expand all the ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_malloc_dbg](malloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`_malloc_dbg`](malloc-dbg.md) diff --git a/docs/c-runtime-library/reference/expand.md b/docs/c-runtime-library/reference/expand.md index 19f6f3d7dc7..dfcbe00e561 100644 --- a/docs/c-runtime-library/reference/expand.md +++ b/docs/c-runtime-library/reference/expand.md @@ -3,14 +3,14 @@ description: "Learn more about: _expand" title: "_expand" ms.date: "4/2/2020" api_name: ["_expand", "_o__expand"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_bexpand", "fexpand", "expand", "nexpand", "_fexpand", "_nexpand", "bexpand", "_expand"] helpviewer_keywords: ["memory blocks, changing size", "_expand function", "expand function"] ms.assetid: 4ac55410-39c8-45c7-bccd-3f1042ae2ed3 --- -# _expand +# `_expand` Changes the size of a memory block. @@ -25,42 +25,42 @@ void *_expand( ### Parameters -*memblock*
+*`memblock`*\ Pointer to previously allocated memory block. -*size*
+*`size`*\ New size in bytes. -## Return Value +## Return value -**_expand** returns a void pointer to the reallocated memory block. **_expand**, unlike **realloc**, cannot move a block to change its size. Thus, if there is sufficient memory available to expand the block without moving it, the *memblock* parameter to **_expand** is the same as the return value. +**`_expand`** returns a void pointer to the reallocated memory block. **`_expand`**, unlike `realloc`, can't move a block to change its size. Thus, if there's sufficient memory available to expand the block without moving it, the *`memblock`* parameter to **`_expand`** is the same as the return value. -**_expand** returns **NULL** when an error is detected during its operation. For example, if **_expand** is used to shrink a memory block, it might detect corruption in the small block heap or an invalid block pointer and return **NULL**. +**`_expand`** returns `NULL` when an error is detected during its operation. For example, if **`_expand`** is used to shrink a memory block, it might detect corruption in the small block heap or an invalid block pointer and return `NULL`. -If there is insufficient memory available to expand the block to the given size without moving it, the function returns **NULL**. **_expand** never returns a block expanded to a size less than requested. If a failure occurs, **errno** indicates the nature of the failure. For more information about **errno**, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If there isn't sufficient memory available to expand the block without moving it, the function returns `NULL`. **`_expand`** never returns a block expanded to a size less than requested. If a failure occurs, `errno` indicates the nature of the failure. For more information about `errno`, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To check the new size of the item, use **_msize**. To get a pointer to a type other than **`void`**, use a type cast on the return value. +The return value points to a storage space that is suitably aligned for storage of any type of object. To check the new size of the item, use `_msize`. To get a pointer to a type other than **`void`**, use a type cast on the return value. ## Remarks -The **_expand** function changes the size of a previously allocated memory block by trying to expand or contract the block without moving its location in the heap. The *memblock* parameter points to the beginning of the block. The *size* parameter gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes. *memblock* should not be a block that has been freed. +The **`_expand`** function changes the size of a previously allocated memory block by trying to expand or contract the block without moving its location in the heap. The *`memblock`* parameter points to the beginning of the block. The *`size`* parameter gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes. *`memblock`* shouldn't be a block that has been freed. > [!NOTE] -> On 64-bit platforms, **_expand** might not contract the block if the new size is less than the current size; in particular, if the block was less than 16K in size and therefore allocated in the Low Fragmentation Heap, **_expand** leaves the block unchanged and returns *memblock*. +> On 64-bit platforms, **`_expand`** might not contract the block if the new size is less than the current size; in particular, if the block was less than 16K in size and therefore allocated in the Low Fragmentation Heap, **`_expand`** leaves the block unchanged and returns *`memblock`*. -When the application is linked with a debug version of the C run-time libraries, **_expand** resolves to [_expand_dbg](expand-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`_expand`** resolves to [`_expand_dbg`](expand-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -This function validates its parameters. If *memblock* is a null pointer, this function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns **NULL**. If *size* is greater than **_HEAP_MAXREQ**, **errno** is set to **ENOMEM** and the function returns **NULL**. +This function validates its parameters. If *`memblock`* is a null pointer, this function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. If *`size`* is greater than `_HEAP_MAXREQ`, `errno` is set to `ENOMEM`, and the function returns `NULL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_expand**|\| +| Function | Required header | +|---|---| +| **`_expand`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,9 +98,9 @@ Expanded block to 1024 bytes at 002C12BC ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[free](free.md)
-[malloc](malloc.md)
-[_msize](msize.md)
-[realloc](realloc.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`free`](free.md)\ +[`malloc`](malloc.md)\ +[`_msize`](msize.md)\ +[`realloc`](realloc.md) diff --git a/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md b/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md index 341686e3f55..7afd9844a3b 100644 --- a/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md +++ b/docs/c-runtime-library/reference/expm1-expm1f-expm1l.md @@ -1,16 +1,15 @@ --- title: "expm1, expm1f, expm1l" description: "API reference for expm1, expm1f, and expm1; which compute the base-e exponential of a value, minus one." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["expm1l", "expm1", "expm1f"] api_location: ["msvcrt.dll", "msvcr80.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: ["expm1l", "expm1", "expm1f"] helpviewer_keywords: ["expm1f function", "expm1l function", "expm1 function"] -ms.assetid: 2a4dd2d9-370c-42b0-9067-0625efa272e0 --- -# expm1, expm1f, expm1l +# `expm1`, `expm1f`, `expm1l` Computes the base-e exponential of a value, minus one. @@ -32,35 +31,35 @@ float expm1f( long double expm1l( long double x ); -#define expm1(X) // Requires C11 or higher +#define expm1(X) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ The floating-point exponential value. -## Return Value +## Return value -The **expm1** functions return a floating-point value that represents ex - 1, if successful. On overflow, **expm1** returns **HUGE_VAL**, **expm1f** returns **HUGE_VALF**, **expm1l** returns **HUGE_VALL**, and **errno** is set to **ERANGE**. For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +The **`expm1`** functions return a floating-point value that represents ex - 1, if successful. On overflow, **`expm1`** returns `HUGE_VAL`, **`expm1f`** returns `HUGE_VALF`, **`expm1l`** returns `HUGE_VALL`, and `errno` is set to `ERANGE`. For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **expm1** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **expm1** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`expm1`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`expm1`** always takes and returns a **`double`**. -If you use the \ `expm1()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `expm1()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**expm1**, **expm1f**, **expm1l**|\| -|**expm1** macro | \ | +| Routine | Required header | +|---|---| +| **`expm1`**, **`expm1f`**, **`expm1l`** | \ | +| **`expm1`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[exp2, exp2f, exp2l](exp2-exp2f-exp2l.md)
-[pow, powf, powl](pow-powf-powl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`exp2`, `exp2f`, `exp2l`](exp2-exp2f-exp2l.md)\ +[`pow`, `powf`, `powl`](pow-powf-powl.md) diff --git a/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md b/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md index b753e77b839..541221d8f91 100644 --- a/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md +++ b/docs/c-runtime-library/reference/fabs-fabsf-fabsl.md @@ -1,12 +1,12 @@ --- title: "fabs, fabsf, fabsl" description: "API reference for fabs, fabsf, and fabsl; which calculate the absolute value of a floating-point value." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["fabsf", "fabs", "fabsl", "_o_fabs", "_o_fabsf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["fabs", "fabsf", "fabsl", "math\fabs", "math\fabsf", "math\fabsl"] +f1_keywords: ["fabs", "fabsf", "fabsl", "math/fabs", "math/fabsf", "math/fabsl"] helpviewer_keywords: ["absolute values", "fabsf function", "calculating absolute values", "fabs function", "fabsl function"] --- # `fabs`, `fabsf`, `fabsl` @@ -32,7 +32,7 @@ long double fabsl( long double x ); -#define fabs(X) // Requires C11 or higher +#define fabs(X) // Requires C11 or later ``` ### Parameters @@ -40,30 +40,30 @@ long double fabsl( *`x`*\ Floating-point value. -## Return Value +## Return value -The **`fabs`** functions return the absolute value of the argument *x*. There's no error return. +The **`fabs`** functions return the absolute value of the argument *`x`*. There's no error return. -|Input|SEH exception|`Matherr` exception| -|-----------|-------------------|-----------------------| -|± `QNAN`,`IND`|none|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks C++ allows overloading, so you can call overloads of **`fabs`** if you include the `` header. In a C program, unless you're using the `` macro to call this function, **`fabs`** always takes and returns a **`double`**. -If you use the `` `fabs()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `fabs` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required C header|Required C++ header| -|--------------|-----------------------|---------------------------| -|**`fabs`**, **`fabsf`**, **`fabsl`**|``|`` or ``| -|**`fabs`** macro | `` || +| Function | Required C header | Required C++ header | +|---|---|---| +| **`fabs`**, **`fabsf`**, **`fabsl`** | `` | `` or `` | +| **`fabs`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -71,6 +71,6 @@ See the example for [`abs`](abs-labs-llabs-abs64.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[`abs, labs, llabs, _abs64`](abs-labs-llabs-abs64.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`abs`, `labs`, `llabs`, `_abs64`](abs-labs-llabs-abs64.md)\ [`_cabs`](cabs.md) diff --git a/docs/c-runtime-library/reference/fclose-fcloseall.md b/docs/c-runtime-library/reference/fclose-fcloseall.md index a20d70b5d56..5f0cee23e69 100644 --- a/docs/c-runtime-library/reference/fclose-fcloseall.md +++ b/docs/c-runtime-library/reference/fclose-fcloseall.md @@ -3,7 +3,7 @@ description: "Learn more about: fclose, _fcloseall" title: "fclose, _fcloseall" ms.date: "4/2/2020" api_name: ["fclose", "_fcloseall", "_o__fcloseall", "_o_fclose"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fclose", "_fcloseall"] @@ -25,34 +25,35 @@ int _fcloseall( void ); ### Parameters *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. -## Return Value +## Return value -**`fclose`** returns 0 if the stream is successfully closed. **`_fcloseall`** returns the total number of streams closed. Both functions return **`EOF`** to indicate an error. +**`fclose`** returns 0 if the stream is successfully closed. **`_fcloseall`** returns the total number of streams closed. Both functions return `EOF` to indicate an error. ## Remarks -The **`fclose`** function closes *`stream`*. If *`stream`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`fclose`** sets **`errno`** to **`EINVAL`** and returns **`EOF`**. It's recommended that the *`stream`* pointer always be checked prior to calling this function. +The **`fclose`** function closes *`stream`*. If *`stream`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`fclose`** sets `errno` to `EINVAL` and returns `EOF`. It's recommended that you always check the *`stream`* pointer before you call this function. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). The **`_fcloseall`** function closes all open streams except **`stdin`**, **`stdout`**, **`stderr`** (and, in MS-DOS, **`_stdaux`** and **`_stdprn`**). It also closes and deletes any temporary files created by **`tmpfile`**. In both functions, all buffers associated with the stream are flushed prior to closing. System-allocated buffers are released when the stream is closed. Buffers assigned by the user with **`setbuf`** and **`setvbuf`** aren't automatically released. -**Note:** When these functions are used to close a stream, the underlying file descriptor and OS file handle (or socket) are closed, as well as the stream. Thus, if the file was originally opened as a file handle or file descriptor and is closed with **`fclose`**, don't also call **`_close`** to close the file descriptor; don't call the Win32 function **`CloseHandle`** to close the file handle. +> [!NOTE] +> When `fclose` or `_fcloseall` functions are used to close a stream, the underlying file descriptor and OS file handle (or socket) are closed as well. Thus, if the file was originally opened as a file handle or file descriptor and is closed with **`fclose`**, don't also call **`_close`** to close the file descriptor; and don't call the Win32 function `CloseHandle` to close the file handle. **`fclose`** and **`_fcloseall`** include code to protect against interference from other threads. For non-locking version of a **`fclose`**, see **`_fclose_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fclose`**|``| -|**`_fcloseall`**|``| +| Function | Required header | +|---|---| +| **`fclose`** | `` | +| **`_fcloseall`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -60,7 +61,7 @@ See the example for [`fopen`](fopen-wfopen.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[Stream I/O](../stream-i-o.md)\ [`_close`](close.md)\ [`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ [`fflush`](fflush.md)\ diff --git a/docs/c-runtime-library/reference/fclose-nolock.md b/docs/c-runtime-library/reference/fclose-nolock.md index 6a511f90e18..b03860a277b 100644 --- a/docs/c-runtime-library/reference/fclose-nolock.md +++ b/docs/c-runtime-library/reference/fclose-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fclose_nolock" title: "_fclose_nolock" +description: "Learn more about: _fclose_nolock" ms.date: "4/2/2020" api_name: ["_fclose_nolock", "_o__fclose_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fclose_nolock", "_fclose_nolock"] helpviewer_keywords: ["streams, closing", "fclose_nolock function", "_fclose_nolock function"] -ms.assetid: b4af4392-5fc8-49bb-9fe2-ca7293d3ce04 --- -# _fclose_nolock +# `_fclose_nolock` -Closes a stream without thread-locking. +Closes a stream without locking. ## Syntax @@ -24,32 +23,32 @@ int _fclose_nolock( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -**fclose** returns 0 if the stream is successfully closed. Returns **EOF** to indicate an error. +**`_fclose_nolock`** returns 0 if the stream is successfully closed. Returns `EOF` to indicate an error. ## Remarks -This functions is a non-locking version of **fclose**. It is identical except that it is not protected from interference by other threads. It might be faster because it does not incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +This function is a non-locking version of `fclose`. It's identical except that it isn't protected from interference by other threads. It might be faster because it doesn't incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fclose_nolock**|\| +| Function | Required header | +|---|---| +| **`_fclose_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_close](close.md)
-[_fdopen, _wfdopen](fdopen-wfdopen.md)
-[fflush](fflush.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[freopen, _wfreopen](freopen-wfreopen.md)
+[Stream I/O](../stream-i-o.md)\ +[`_close`](close.md)\ +[`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ +[`fflush`](fflush.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`freopen`, `_wfreopen`](freopen-wfreopen.md) diff --git a/docs/c-runtime-library/reference/fcloseall.md b/docs/c-runtime-library/reference/fcloseall.md index 660bcd0651f..26e96ee80b9 100644 --- a/docs/c-runtime-library/reference/fcloseall.md +++ b/docs/c-runtime-library/reference/fcloseall.md @@ -10,8 +10,8 @@ f1_keywords: ["fcloseall"] helpviewer_keywords: ["fcloseall function"] ms.assetid: 4f14acde-5bc5-43da-a709-7a3c559df3cf --- -# fcloseall +# `fcloseall` -The Microsoft-specific function name `fcloseall` is a deprecated alias for the [_fcloseall](fclose-fcloseall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `fcloseall` is a deprecated alias for the [`_fcloseall`](fclose-fcloseall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fcloseall](fclose-fcloseall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fcloseall`](fclose-fcloseall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/fcvt-s.md b/docs/c-runtime-library/reference/fcvt-s.md index f6a9fc80aa9..bb29897a97e 100644 --- a/docs/c-runtime-library/reference/fcvt-s.md +++ b/docs/c-runtime-library/reference/fcvt-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _fcvt_s" title: "_fcvt_s" ms.date: "4/2/2020" api_name: ["_fcvt_s", "_o__fcvt_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fcvt_s", "_fcvt_s"] helpviewer_keywords: ["fcvt_s function", "converting floating point, to strings", "floating-point functions, converting number to string", "_fcvt_s function"] ms.assetid: 48671197-1d29-4c2b-a5d8-d2368f5f68a1 --- -# _fcvt_s +# `_fcvt_s` -Converts a floating-point number to a string. This is a version of [_fcvt](fcvt.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a floating-point number to a string. This function is a version of [`_fcvt`](fcvt.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,68 +37,68 @@ errno_t _fcvt_s( ### Parameters -*buffer*
+*`buffer`*\ The supplied buffer that will hold the result of the conversion. -*sizeInBytes*
+*`sizeInBytes`*\ The size of the buffer in bytes. -*value*
+*`value`*\ Number to be converted. -*count*
+*`count`*\ Number of digits after the decimal point. -*dec*
+*`dec`*\ Pointer to the stored decimal-point position. -*sign*
+*`sign`*\ Pointer to the stored sign indicator. -## Return Value +## Return value -Zero if successful. The return value is an error code if there is a failure. Error codes are defined in Errno.h. For a listing of these errors, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in `errno.h`. For a listing of these errors, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -In the case of an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +When there's an invalid parameter, as listed in the following table, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. -### Error Conditions +### Error conditions -|*buffer*|*sizeInBytes*|value|count|dec|sign|Return|Value in *buffer*| -|--------------|-------------------|-----------|-----------|---------|----------|------------|-----------------------| -|**NULL**|any|any|any|any|any|**EINVAL**|Not modified.| -|Not **NULL** (points to valid memory)|<=0|any|any|any|any|**EINVAL**|Not modified.| -|any|any|any|any|**NULL**|any|**EINVAL**|Not modified.| -|any|any|any|any|any|**NULL**|**EINVAL**|Not modified.| +| *`buffer`* | *`sizeInBytes`* | *`value`* | *`count`* | *`dec`* | *`sign`* | Return | Value in *`buffer`* | +|---|---|---|---|---|---|---|---| +| `NULL` | any | any | any | any | any | `EINVAL` | Not modified. | +| Not `NULL` (points to valid memory) | <=0 | any | any | any | any | `EINVAL` | Not modified. | +| any | any | any | any | `NULL` | any | `EINVAL` | Not modified. | +| any | any | any | any | any | `NULL` | `EINVAL` | Not modified. | ## Security Issues -**_fcvt_s** might generate an access violation if *buffer* does not point to valid memory and is not **NULL**. +**`_fcvt_s`** might generate an access violation if *`buffer`* doesn't point to valid memory and isn't `NULL`. ## Remarks -The **_fcvt_s** function converts a floating-point number to a null-terminated character string. The *value* parameter is the floating-point number to be converted. **_fcvt_s** stores the digits of *value* as a string and appends a null character ('\0'). The *count* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *count* places. If there are fewer than *count* digits of precision, the string is padded with zeros. +The **`_fcvt_s`** function converts a floating-point number to a null-terminated character string. The *`value`* parameter is the floating-point number to be converted. **`_fcvt_s`** stores the digits of *`value`* as a string and appends a null character ('\0'). The *`count`* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *`count`* places. If there are fewer than *`count`* digits of precision, the string is padded with zeros. -Only digits are stored in the string. The position of the decimal point and the sign of *value* can be obtained from *dec* and *sign* after the call. The *dec* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *sign* points to an integer indicating the sign of *value*. The integer is set to 0 if *value* is positive and is set to a nonzero number if *value* is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and *`sign`* after the call. The *`dec`* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *`sign`* points to an integer indicating the sign of *`value`*. The integer is set to 0 if *`value`* is positive and is set to a nonzero number if *`value`* is negative. -A buffer of length **_CVTBUFSIZE** is sufficient for any floating point value. +A buffer of length `_CVTBUFSIZE` is sufficient for any floating point value. -The difference between **_ecvt_s** and **_fcvt_s** is in the interpretation of the *count* parameter. **_ecvt_s** interprets *count* as the total number of digits in the output string, and **_fcvt_s** interprets *count* as the number of digits after the decimal point. +The difference between `_ecvt_s` and **`_fcvt_s`** is in the interpretation of the *`count`* parameter. `_ecvt_s` interprets *`count`* as the total number of digits in the output string, and **`_fcvt_s`** interprets *`count`* as the number of digits after the decimal point. -In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by a template overload; the overload can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug version of this function first fills the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header|Optional header| -|--------------|---------------------|---------------------| -|**_fcvt_s**|\|\| +| Function | Required header | Optional header | +|---|---|---| +| **`_fcvt_s`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** All versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md). +**Libraries:** All versions of the [C runtime libraries](../crt-library-features.md). ## Example @@ -134,9 +134,9 @@ Converted value: 120000 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt_s](ecvt-s.md)
-[_gcvt_s](gcvt-s.md)
-[_fcvt](fcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt_s`](ecvt-s.md)\ +[`_gcvt_s`](gcvt-s.md)\ +[`_fcvt`](fcvt.md) diff --git a/docs/c-runtime-library/reference/fcvt.md b/docs/c-runtime-library/reference/fcvt.md index 80c781354fc..a9a313c69e9 100644 --- a/docs/c-runtime-library/reference/fcvt.md +++ b/docs/c-runtime-library/reference/fcvt.md @@ -3,16 +3,16 @@ description: "Learn more about: _fcvt" title: "_fcvt" ms.date: "4/2/2020" api_name: ["_fcvt", "_o__fcvt"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fcvt"] helpviewer_keywords: ["converting floating point, to strings", "_fcvt function", "floating-point functions, converting number to string", "fcvt function", "floating-point functions"] ms.assetid: 74584c88-f0dd-4907-8fca-52da5df583f5 --- -# _fcvt +# `_fcvt` -Converts a floating-point number to a string. A more secure version of this function is available; see [_fcvt_s](fcvt-s.md). +Converts a floating-point number to a string. A more secure version of this function is available; see [`_fcvt_s`](fcvt-s.md). ## Syntax @@ -27,45 +27,45 @@ char *_fcvt( ### Parameters -*value*
+*`value`*\ Number to be converted. -*count*
+*`count`*\ Number of digits after the decimal point. -*dec*
+*`dec`*\ Pointer to the stored decimal-point position. -*sign*
+*`sign`*\ Pointer to the stored sign indicator. -## Return Value +## Return value -**_fcvt** returns a pointer to the string of digits, **NULL** on error. +**`_fcvt`** returns a pointer to the string of digits, `NULL` on error. ## Remarks -The **_fcvt** function converts a floating-point number to a null-terminated character string. The *value* parameter is the floating-point number to be converted. **_fcvt** stores the digits of *value* as a string and appends a null character ('\0'). The *count* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *count* places. If there are fewer than *count* digits of precision, the string is padded with zeros. +The **`_fcvt`** function converts a floating-point number to a null-terminated character string. The *`value`* parameter is the floating-point number to be converted. **`_fcvt`** stores the digits of *`value`* as a string and appends a null character ('\0'). The *`count`* parameter specifies the number of digits to be stored after the decimal point. Excess digits are rounded off to *`count`* places. If there are fewer than *`count`* digits of precision, the string is padded with zeros. -The total number of digits returned by **_fcvt** will not exceed **_CVTBUFSIZE**. +The total number of digits returned by **`_fcvt`** won't exceed `_CVTBUFSIZE`. -Only digits are stored in the string. The position of the decimal point and the sign of *value* can be obtained from *dec* and sign after the call. The *dec* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *sign* points to an integer indicating the sign of *value*. The integer is set to 0 if *value* is positive and is set to a nonzero number if *value* is negative. +Only digits are stored in the string. The position of the decimal point and the sign of *`value`* can be obtained from *`dec`* and sign after the call. The *`dec`* parameter points to an integer value; this integer value gives the position of the decimal point with respect to the beginning of the string. A zero or negative integer value indicates that the decimal point lies to the left of the first digit. The parameter *`sign`* points to an integer indicating the sign of *`value`*. The integer is set to 0 if *`value`* is positive and is set to a nonzero number if *`value`* is negative. -The difference between **_ecvt** and **_fcvt** is in the interpretation of the *count* parameter. **_ecvt** interprets *count* as the total number of digits in the output string, whereas **_fcvt** interprets *count* as the number of digits after the decimal point. +The difference between `_ecvt` and **`_fcvt`** is in the interpretation of the *`count`* parameter. `_ecvt` interprets *`count`* as the total number of digits in the output string, whereas **`_fcvt`** interprets *`count`* as the number of digits after the decimal point. -**_ecvt** and **_fcvt** use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the results of the previous call. +`_ecvt` and **`_fcvt`** use a single statically allocated buffer for the conversion. Each call to one of these routines destroys the results of the previous call. -This function validates its parameters. If *dec* or *sign* is **NULL**, or *count* is 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and **NULL** is returned. +This function validates its parameters. If *`dec`* or *`sign`* is `NULL`, or *`count`* is 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and `NULL` is returned. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fcvt**|\| +| Function | Required header | +|---|---| +| **`_fcvt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -98,8 +98,8 @@ source: 3.1415926535 buffer: '31415927' decimal: 1 sign: 0 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[_ecvt](ecvt.md)
-[_gcvt](gcvt.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`_ecvt`](ecvt.md)\ +[`_gcvt`](gcvt.md) diff --git a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md index 11a0b09bf5d..7b408b24326 100644 --- a/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md +++ b/docs/c-runtime-library/reference/fdim-fdimf-fdiml.md @@ -1,16 +1,15 @@ --- title: "fdim, fdimf, fdiml" description: "API reference for fdim, fdimf, and fdiml; which determines the positive difference between two values." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["fdim", "fdimf", "fdiml"] api_location: ["msvcrt.dll", "msvcr80.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: ["fdim", "fdimf", "fdiml", "math/fdim", "math/fdimf", "math/fdiml"] helpviewer_keywords: ["fdim function", "fdimf function", "fdiml function"] -ms.assetid: 2d4ac639-51e9-462d-84ab-fb03b06971a0 --- -# fdim, fdimf, fdiml +# `fdim`, `fdimf`, `fdiml` Determines the positive difference between the first and second values. @@ -42,55 +41,55 @@ long double fdiml( long double y ); -#define fdim(X) // Requires C11 or higher +#define fdim(X) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ The first value. -*y*\ +*`y`*\ The second value. -## Return Value +## Return value -Returns the positive difference between *x* and *y*: +Returns the positive difference between *`x`* and *`y`*: -|Return value|Scenario| -|------------------|--------------| -|x-y|if x > y| -|0|if x <= y| +| Return value | Scenario | +|---|---| +| `x-y` | if *`x`* > *`y`* | +| 0 | if *`x`* <= *`y`* | Otherwise, may return one of the following errors: -|Issue|Return| -|-----------|------------| -|Overflow range error|+HUGE_VAL, +HUGE_VALF, or +HUGE_VALL| -|Underflow range error|correct value (after rounding)| -|*x* or *y* is NaN|NaN| +| Issue | Return | +|---|---| +| Overflow range error | +HUGE_VAL, +HUGE_VALF, or +HUGE_VALL | +| Underflow range error | correct value (after rounding) | +| *`x`* or *`y`* is NaN | NaN | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **fdim** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **fdim** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`fdim`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`fdim`** always takes and returns a **`double`**. -If you use the \ `fdim()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fdim()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. Except for the NaN handling, this function is equivalent to `fmax(x - y, 0)`. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fdim**, **fdimf**, **fdiml**|\|\| -|**fdim** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`fdim`**, **`fdimf`**, **`fdiml`** | \ | \ | +| **`fdim`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fmax, fmaxf, fmaxl](fmax-fmaxf-fmaxl.md)
-[abs, labs, llabs, _abs64](abs-labs-llabs-abs64.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fmax`, `fmaxf`, `fmaxl`](fmax-fmaxf-fmaxl.md)\ +[`abs`, `labs`, `llabs`, `_abs64`](abs-labs-llabs-abs64.md) diff --git a/docs/c-runtime-library/reference/fdopen-wfdopen.md b/docs/c-runtime-library/reference/fdopen-wfdopen.md index 310f2d6e4b7..46191ee16c8 100644 --- a/docs/c-runtime-library/reference/fdopen-wfdopen.md +++ b/docs/c-runtime-library/reference/fdopen-wfdopen.md @@ -3,7 +3,7 @@ description: "Learn more about: _fdopen, _wfdopen" title: "_fdopen, _wfdopen" ms.date: 05/18/2022 api_name: ["_fdopen", "_wfdopen", "_o__fdopen", "_o__wfdopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["STDIO/_fdopen", "CORECRT_WSTDIO/_wfdopen", "TCHAR/_tfdopen", "_fdopen", "_wfdopen", "_tfdopen", "wfdopen", "tfdopen"] @@ -37,13 +37,13 @@ Type of file access. ## Return value -Each of these functions returns a pointer to the open stream. A null pointer value indicates an error. When an error occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, `errno` is set either to `EBADF`, which indicates a bad file descriptor, or `EINVAL`, which indicates that *`mode`* was a null pointer. +Each of these functions returns a pointer to the open stream. A null pointer value indicates an error. When an error occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set either to `EBADF`, which indicates a bad file descriptor, or `EINVAL`, which indicates that *`mode`* was a null pointer. -For more information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`_fdopen`** function associates an I/O stream with the file that is identified by *`fd`*, and thus allows a file that is opened for low-level I/O to be buffered and formatted. **`_wfdopen`** is a wide-character version of **`_fdopen`**; the *mode* argument to **`_wfdopen`** is a wide-character string. **`_wfdopen`** and **`_fdopen`** otherwise behave identically. +The **`_fdopen`** function associates an I/O stream with the file that is identified by *`fd`*, and thus allows a file that is opened for low-level I/O to be buffered and formatted. **`_wfdopen`** is a wide-character version of **`_fdopen`**; the *`mode`* argument to **`_wfdopen`** is a wide-character string. **`_wfdopen`** and **`_fdopen`** otherwise behave identically. File descriptors passed into **`_fdopen`** are owned by the returned `FILE *` stream. If **`_fdopen`** is successful, don't call [`_close`](close.md) on the file descriptor. Calling [`fclose`](fclose-fcloseall.md) on the returned `FILE *` also closes the file descriptor. @@ -62,18 +62,18 @@ The *`mode`* character string specifies the type of file access requested for th When a file is opened with the **`"a"`** or **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it's always moved back to the end of the file before any write operation is carried out. Thus, existing data can't be overwritten. When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are allowed (the file is said to be open for "update"). However, when you switch between reading and writing, there must be an intervening [`fflush`](fflush.md), [`fsetpos`](fsetpos.md), [`fseek`](fseek-fseeki64.md), or [`rewind`](rewind.md) operation. You can specify the current position for the [`fsetpos`](fsetpos.md) or [`fseek`](fseek-fseeki64.md) operation, if you want to. -In addition to the above values, the following characters can also be included in *mode* to specify the translation mode for newline characters: +In addition to the above values, the following characters can also be included in *`mode`* to specify the translation mode for newline characters: | *`mode`* modifier | Behavior | |-----------------|----------| | **`t`** | Open in text (translated) mode. In this mode, carriage return-line feed (CR-LF) combinations are translated into one-line feeds (LF) on input, and LF characters are translated to CR-LF combinations on output. Also, Ctrl+Z is interpreted as an end-of-file character on input. | | **`b`** | Open in binary (untranslated) mode. Any translations from **`t`** mode are suppressed. | -| **`c`** | Enable the commit flag for the associated *filename* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | -| **`n`** | Reset the commit flag for the associated *filename* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with *`Commode.obj`*. The global commit flag default is "no-commit" unless you explicitly link your program with *`Commode.obj`*. | +| **`c`** | Enable the commit flag for the associated *`filename`* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | +| **`n`** | Reset the commit flag for the associated *`filename`* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with *`Commode.obj`*. The global commit flag default is "no-commit" unless you explicitly link your program with *`Commode.obj`*. | The **`t`**, **`c`**, and **`n`** *`mode`* options are Microsoft extensions for **`fopen`** and **`_fdopen`**. Don't use them if you want to preserve ANSI portability. -If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../../c-runtime-library/fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. For a discussion of text and binary modes, see [Text and binary mode file I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md). +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. For a discussion of text and binary modes, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md). Valid characters for the *`mode`* string used in **`fopen`** and **`_fdopen`** correspond to *`oflag`* arguments used in [`_open`](open-wopen.md) and [`_sopen`](sopen-wsopen.md), as shown in this table: @@ -97,7 +97,7 @@ Valid characters for the *`mode`* string used in **`fopen`** and **`_fdopen`** c | **`_fdopen`** | `` | `` | | **`_wfdopen`** | `` or `` | `` | -For more information on standards conformance and naming conventions in the C runtime library, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information on standards conformance and naming conventions in the C runtime library, see [Compatibility](../compatibility.md). ### Generic-text routine mappings @@ -157,7 +157,7 @@ Lines in file: 2 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[Stream I/O](../stream-i-o.md)\ [`_dup`, `_dup2`](dup-dup2.md)\ [`fclose`, `_fcloseall`](fclose-fcloseall.md)\ [`fopen`, `_wfopen`](fopen-wfopen.md)\ diff --git a/docs/c-runtime-library/reference/fdopen.md b/docs/c-runtime-library/reference/fdopen.md index 549d0382dee..9471513b40c 100644 --- a/docs/c-runtime-library/reference/fdopen.md +++ b/docs/c-runtime-library/reference/fdopen.md @@ -10,8 +10,8 @@ f1_keywords: ["fdopen"] helpviewer_keywords: ["fdopen function"] ms.assetid: 3243c1d2-2826-4d2d-bfa2-a2da45f9cc7a --- -# fdopen +# `fdopen` -The Microsoft-implemented POSIX function name `fdopen` is a deprecated alias for the [_fdopen](fdopen-wfdopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `fdopen` is a deprecated alias for the [`_fdopen`](fdopen-wfdopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fdopen](fdopen-wfdopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fdopen`](fdopen-wfdopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/feclearexcept1.md b/docs/c-runtime-library/reference/feclearexcept1.md index 8c6e9e10ab6..de74f7735a4 100644 --- a/docs/c-runtime-library/reference/feclearexcept1.md +++ b/docs/c-runtime-library/reference/feclearexcept1.md @@ -10,9 +10,9 @@ f1_keywords: ["feclearexcept", "fenv/feclearexcept"] helpviewer_keywords: ["feclearexcept function"] ms.assetid: ef419da3-c248-4432-b53c-8e7a475d9533 --- -# feclearexcept +# `feclearexcept` -Attempts to clear the floating-point exception flags specified by the argument. +**`feclearexcept`** attempts to clear the floating-point exception flags specified by the argument. ## Syntax @@ -24,37 +24,37 @@ int feclearexcept( ### Parameters -*excepts*
+*`excepts`*\ The exception status flags to clear. -## Return Value +## Return value -Returns zero if *excepts* is zero, or if all the specified exceptions were successfully cleared. Otherwise, returns a nonzero value. +Returns zero if *`excepts`* is zero, or if all the specified exceptions were successfully cleared. Otherwise, it returns a nonzero value. ## Remarks -The **feclearexcept** function attempts to clear the floating point exception status flags specified by *excepts*. The function supports these exception macros, defined in fenv.h: +The **`feclearexcept`** function attempts to clear the floating point exception status flags specified by *`excepts`*. The function supports these exception macros, defined in fenv.h: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, or the bitwise OR of one or more of the supported exception macros. The result of any other argument value is undefined. +The *`excepts`* argument may be zero, or the bitwise OR of one or more of the supported exception macros. The result of any other argument value is undefined. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**feclearexcept**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`feclearexcept`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fetestexcept](fetestexcept1.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fetestexcept`](fetestexcept1.md) diff --git a/docs/c-runtime-library/reference/fegetenv1.md b/docs/c-runtime-library/reference/fegetenv1.md index 36ca31d1f1a..e14e60b558c 100644 --- a/docs/c-runtime-library/reference/fegetenv1.md +++ b/docs/c-runtime-library/reference/fegetenv1.md @@ -10,7 +10,7 @@ f1_keywords: ["fegetenv", "fenv/fegetenv"] helpviewer_keywords: ["fetegenv function"] ms.assetid: 68962421-6978-4b27-8e4c-ad1577830cf6 --- -# fegetenv +# `fegetenv` Stores the current floating-point environment in the specified object. @@ -24,28 +24,28 @@ int fegetenv( ### Parameters -*penv*
-Pointer to an **fenv_t** object to contain the current floating-point environment values. +*`penv`*\ +Pointer to an `fenv_t` object to contain the current floating-point environment values. -## Return Value +## Return value -Returns 0 if the floating-point environment was successfully stored in *penv*. Otherwise, returns a non-zero value. +Returns 0 if the floating-point environment was successfully stored in *`penv`*. Otherwise, it returns a non-zero value. ## Remarks -The **fegetenv** function stores the current floating-point environment in the object pointed to by *penv*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. This includes the rounding direction mode and the status flags for floating-point exceptions. If *penv* does not point to a valid **fenv_t** object, subsequent behavior is undefined. +The **`fegetenv`** function stores the current floating-point environment in the object pointed to by *`penv`*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. This environment includes the rounding direction mode and the status flags for floating-point exceptions. If *`penv`* doesn't point to a valid `fenv_t` object, subsequent behavior is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fegetenv**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fegetenv`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fesetenv](fesetenv1.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fesetenv`](fesetenv1.md) diff --git a/docs/c-runtime-library/reference/fegetexceptflag2.md b/docs/c-runtime-library/reference/fegetexceptflag2.md index 144cf99831a..eee0d9ff14a 100644 --- a/docs/c-runtime-library/reference/fegetexceptflag2.md +++ b/docs/c-runtime-library/reference/fegetexceptflag2.md @@ -10,7 +10,7 @@ f1_keywords: ["fegetexceptflag", "fenv/fegetexceptflag"] helpviewer_keywords: ["fegetexceptflag function"] ms.assetid: 2d28f0ca-70c9-4cff-be8b-3d876eacde71 --- -# fegetexceptflag +# `fegetexceptflag` Stores the current state of the specified floating-point exception flags. @@ -25,42 +25,42 @@ int fegetexceptflag( ### Parameters -*pstatus*
-A pointer to a **fexcept_t** object to contain the current values of the exception flags specified by *excepts*. +*`pstatus`*\ +A pointer to a `fexcept_t` object to contain the current values of the exception flags specified by *`excepts`*. -*excepts*
-The floating-point exception flags to store in *pstatus*. +*`excepts`*\ +The floating-point exception flags to store in *`pstatus`*. -## Return Value +## Return value -On success, returns 0. Otherwise, returns a non-zero value. +On success, returns 0. Otherwise, it returns a non-zero value. ## Remarks -The **fegetexceptflag** function stores the current state of the floating-point exception status flags specified by *excepts* in the **fexcept_t** object pointed to by *pstatus*. *pstatus* must point to a valid **fexcept_t** object, or subsequent behavior is undefined. The **fegetexceptflag** function supports these exception macros, defined in \: +The **`fegetexceptflag`** function stores the current state of the floating-point exception status flags specified by *`excepts`* in the `fexcept_t` object pointed to by *`pstatus`*. *`pstatus`* must point to a valid `fexcept_t` object, or subsequent behavior is undefined. The **`fegetexceptflag`** function supports these exception macros, defined in \: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. +The *`excepts`* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fegetexceptflag**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fegetexceptflag`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fesetexceptflag](fesetexceptflag2.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fesetexceptflag`](fesetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fegetround-fesetround2.md b/docs/c-runtime-library/reference/fegetround-fesetround2.md index cf1d8033a30..d771b3c7d4a 100644 --- a/docs/c-runtime-library/reference/fegetround-fesetround2.md +++ b/docs/c-runtime-library/reference/fegetround-fesetround2.md @@ -8,9 +8,8 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fegetround", "fesetround", "fenv/fegetround", "fenv/fesetround"] helpviewer_keywords: ["fegetround function", "fesetround function"] -ms.assetid: 596af00b-be2f-4f57-b2f5-460485f9ff0b --- -# fegetround, fesetround +# `fegetround`, `fesetround` Gets or sets the current floating-point rounding mode. @@ -18,67 +17,63 @@ Gets or sets the current floating-point rounding mode. ```C int fegetround(void); - -int fesetround( - int round_mode -); +int fesetround(int round_mode); ``` ### Parameters -*round_mode*
-The rounding mode to set, as one of the floating-point rounding macros. If the value is not equal to one of the floating-point rounding macros, the rounding mode is not changed. +*`round_mode`*\ +The rounding mode to set, as one of the floating-point rounding macros. If the value isn't equal to one of the floating-point rounding macros, the rounding mode isn't changed. -## Return Value +## Return value -On success, **fegetround** returns the rounding mode as one of the floating point rounding macro values. It returns a negative value if the current rounding mode can't be determined. +On success, **`fegetround`** returns the rounding mode as one of the floating point rounding macro values. It returns a negative value if the current rounding mode can't be determined. -On success, **fesetround** returns 0. Otherwise, a non-zero value is returned. +On success, **`fesetround`** returns 0. Otherwise, a non-zero value is returned. ## Remarks -Floating-point operations can use one of several rounding modes. These control which direction the results of floating-point operations are rounded toward when the results are stored. These are the names and behaviors of the floating-point rounding macros defined in \: +Floating-point operations can use one of several rounding modes. These modes control which direction the results of floating-point operations are rounded toward when the results are stored. Here are the names and behaviors of the floating-point rounding macros defined in \: -|Macro|Description| -|-----------|-----------------| -|FE_DOWNWARD|Round towards negative infinity.| -|FE_TONEAREST|Round towards the nearest.| -|FE_TOWARDZERO|Round towards zero.| -|FE_UPWARD|Round towards positive infinity.| +| Macro | Description | +|---|---| +| `FE_DOWNWARD` | Round towards negative infinity. | +| `FE_TONEAREST` | Round towards the nearest. | +| `FE_TOWARDZERO` | Round towards zero. | +| `FE_UPWARD` | Round towards positive infinity. | -The default behavior of FE_TONEAREST is to round results midway between representable values toward the nearest value with an even (0) least significant bit. +The default behavior of `FE_TONEAREST` is to round results midway between representable values toward the nearest value with an even (0) least significant bit. The current rounding mode affects these operations: - String conversions. - - The results of floating-point arithmetic operators outside of constant expressions. - -- The library rounding functions, such as **rint** and **nearbyint**. - +- The library rounding functions, such as `rint` and `nearbyint`. - Return values from standard library mathematical functions. -The current rounding mode does not affect these operations: - -- The **trunc**, **ceil**, **floor**, and **lround** library functions. +The current rounding mode doesn't affect these operations: +- The `trunc`, `ceil`, `floor`, and `lround` library functions. - Floating-point to integer implicit casts and conversions, which always round towards zero. - - The results of floating-point arithmetic operators in constant expressions, which always round to the nearest value. -To use these functions, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use these functions, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). + +> [!IMPORTANT] +> Prior to Windows 10 version 14393, `fenv.h` defined `FE_UPWARD = 0x0100` and `FE_DOWNWARD = 0x0200`. In Windows version 14393, this header was updated to address a bug in which some APIs would interpret `FE_UPWARD` as `FE_DOWNWARD`, and vice-versa. Starting in Windows version 14393, `FE_UPWARD = 0x0200` and `FE_DOWNWARD = 0x0100`, reversing their previous values. +> If you compiled your app against an old Windows SDK version (this issue depends on SDK version, not OS version or VS version) you might encounter this issue. Update your app to target the latest Windows SDK so that the definitions of `FE_UPWARD` and `FE_DOWNWARD` are consistent with the Windows implementation. If you can't update your app to target a later Windows SDK, you can define `FE_UPWARD` as `0x0100` and `FE_DOWNWARD` as `0x0200` in your code. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fegetround**, **fesetround**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fegetround`**, **`fesetround`** | `` | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[nearbyint, nearbyintf, nearbyintl](nearbyint-nearbyintf-nearbyintl1.md)
-[rint, rintf, rintl](rint-rintf-rintl.md)
-[lrint, lrintf, lrintl, llrint, llrintf, llrintl](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`nearbyint`, `nearbyintf`, `nearbyintl`](nearbyint-nearbyintf-nearbyintl1.md)\ +[`rint`, `rintf`, `rintl`](rint-rintf-rintl.md)\ +[`lrint`, `lrintf`, `lrintl`, `llrint`, `llrintf`, `llrintl`](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md) diff --git a/docs/c-runtime-library/reference/feholdexcept2.md b/docs/c-runtime-library/reference/feholdexcept2.md index 5addcd17fa4..fbf45b3e331 100644 --- a/docs/c-runtime-library/reference/feholdexcept2.md +++ b/docs/c-runtime-library/reference/feholdexcept2.md @@ -10,7 +10,7 @@ f1_keywords: ["feholdexcept", "fenv/feholdexcept"] helpviewer_keywords: ["feholdexcept function"] ms.assetid: 88e512ae-b5d8-452c-afe9-c824cd3ef1d8 --- -# feholdexcept +# `feholdexcept` Saves the current floating-point environment in the specified object, clears the floating-point status flags, and, if possible, puts the floating-point environment into non-stop mode. @@ -24,32 +24,32 @@ int feholdexcept( ### Parameters -*penv*
-Pointer to an **fenv_t** object to contain a copy of the floating-point environment. +*`penv`*\ +Pointer to an `fenv_t` object to contain a copy of the floating-point environment. -## Return Value +## Return value Returns zero if and only if the function is able to successfully turn on non-stop floating-point exception handling. ## Remarks -The **feholdexcept** function is used to store the state of the current floating point environment in the **fenv_t** object pointed to by *penv*, and to set the environment to not interrupt execution on floating-point exceptions. This is known as non-stop mode. This mode continues until the environment is restored using [fesetenv](fesetenv1.md) or [feupdateenv](feupdateenv.md). +The **`feholdexcept`** function is used to store the state of the current floating point environment in the `fenv_t` object pointed to by *`penv`*, and to set the environment to not interrupt execution on floating-point exceptions. This mode is known as *non-stop mode*. This mode continues until the environment is restored using [`fesetenv`](fesetenv1.md) or [`feupdateenv`](feupdateenv.md). -You can use this function at the beginning of a subroutine that needs to hide one or more floating-point exceptions from the caller. To report an exception, you can simply clear the unwanted exceptions by using [feclearexcept,](feclearexcept1.md) and then end the non-stop mode with a call to **feupdateenv**. +You can use this function at the beginning of a subroutine that needs to hide one or more floating-point exceptions from the caller. To report an exception, you can clear the unwanted exceptions by using [`feclearexcept`](feclearexcept1.md), and then end the non-stop mode with a call to `feupdateenv`. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**feholdexcept**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`feholdexcept`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[feclearexcept](feclearexcept1.md)
-[fesetenv](fesetenv1.md)
-[feupdateenv](feupdateenv.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`fesetenv`](fesetenv1.md)\ +[`feupdateenv`](feupdateenv.md) diff --git a/docs/c-runtime-library/reference/feof.md b/docs/c-runtime-library/reference/feof.md index 0e982944f47..a109a3b828b 100644 --- a/docs/c-runtime-library/reference/feof.md +++ b/docs/c-runtime-library/reference/feof.md @@ -3,14 +3,14 @@ description: "Learn more about: feof" title: "feof" ms.date: "4/2/2020" api_name: ["feof", "_o_feof"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["feof"] helpviewer_keywords: ["end of file, testing for", "feof function"] ms.assetid: 09081eee-7c4b-4189-861f-2fad95d3ec6d --- -# feof +# `feof` Tests for end-of-file on a stream. @@ -24,30 +24,30 @@ int feof( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -The **feof** function returns a nonzero value if a read operation has attempted to read past the end of the file; it returns 0 otherwise. If the stream pointer is **NULL**, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the **feof** returns 0. +The **`feof`** function returns a nonzero value if a read operation has attempted to read past the end of the file; it returns 0 otherwise. If the stream pointer is `NULL`, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the **`feof`** returns 0. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **feof** routine (implemented both as a function and as a macro) determines whether the end of *stream* has been passed. When the end of file is passed, read operations return an end-of-file indicator until the stream is closed or until [rewind](rewind.md), **fsetpos**, [fseek](fseek-fseeki64.md), or **clearerr** is called against it. +The **`feof`** routine (implemented both as a function and as a macro) determines whether the end of *`stream`* has been passed. When the end of file is passed, read operations return an end-of-file indicator until the stream is closed or until [`rewind`](rewind.md), `fsetpos`, [`fseek`](fseek-fseeki64.md), or `clearerr` is called against it. -For example, if a file contains 10 bytes and you read 10 bytes from the file, **feof** will return 0 because, even though the file pointer is at the end of the file, you have not attempted to read beyond the end. Only after you try to read an 11th byte will **feof** return a nonzero value. +For example, if a file contains 10 bytes and you read 10 bytes from the file, **`feof`** will return 0 because, even though the file pointer is at the end of the file, you haven't attempted to read beyond the end. Only after you try to read an 11th byte will **`feof`** return a nonzero value. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**feof**|\| +| Function | Required header | +|---|---| +| **`feof`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -104,9 +104,9 @@ Number of bytes read = 19 ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[clearerr](clearerr.md)
-[_eof](eof.md)
-[ferror](ferror.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Stream I/O](../stream-i-o.md)\ +[`clearerr`](clearerr.md)\ +[`_eof`](eof.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/feraiseexcept.md b/docs/c-runtime-library/reference/feraiseexcept.md index 53dfe4ba119..90eb2f4f93d 100644 --- a/docs/c-runtime-library/reference/feraiseexcept.md +++ b/docs/c-runtime-library/reference/feraiseexcept.md @@ -9,7 +9,7 @@ f1_keywords: ["feraiseexcept", "fenv/feraiseexcept"] helpviewer_keywords: ["feraiseexcept function"] ms.assetid: 87e89151-83c2-4563-9a9a-45666245d437 --- -# feraiseexcept +# `feraiseexcept` Raises the specified floating-point exceptions. @@ -23,44 +23,44 @@ int feraiseexcept( ### Parameters -*excepts*
+*`excepts`*\ The floating-point exceptions to raise. -## Return Value +## Return value If all specified exceptions are raised successfully, returns 0. ## Remarks -The **feraiseexcept** function attempts to raise the floating-point exceptions specified by *excepts*. The **feraiseexcept** function supports these exception macros, defined in \: +The **`feraiseexcept`** function attempts to raise the floating-point exceptions specified by *`excepts`*. The **`feraiseexcept`** function supports these exception macros, defined in \: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception Macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, one of the exception macro values, or the bitwise OR of two or more of the supported exception macros. If one of the specified exception macros is FE_OVERFLOW or FE_UNDERFLOW, the FE_INEXACT exception may be raised as a side-effect. +The *`excepts`* argument may be zero, one of the exception macro values, or the bitwise OR of two or more of the supported exception macros. If one of the specified exception macros is `FE_OVERFLOW` or `FE_UNDERFLOW`, the `FE_INEXACT` exception may be raised as a side-effect. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). -**Microsoft-specific:** The exceptions specified in *excepts* are raised in the order FE_INVALID, FE_DIVBYZERO, FE_OVERFLOW, FE_UNDERFLOW, FE_INEXACT. However, FE_INEXACT can be raised when FE_OVERFLOW or FE_UNDERFLOW is raised, even if not specified in *excepts*. +**Microsoft-specific:** The exceptions specified in *`excepts`* are raised in the order `FE_INVALID`, `FE_DIVBYZERO`, `FE_OVERFLOW`, `FE_UNDERFLOW`, `FE_INEXACT`. However, `FE_INEXACT` can be raised when `FE_OVERFLOW` or `FE_UNDERFLOW` is raised, even if not specified in *`excepts`*. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|*feraiseexcept*|\|\| +| Function | C header | C++ header | +|---|---|---| +| `feraiseexcept` | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fesetexceptflag](fesetexceptflag2.md)
-[feholdexcept](feholdexcept2.md)
-[fetestexcept](fetestexcept1.md)
-[feupdateenv](feupdateenv.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fesetexceptflag`](fesetexceptflag2.md)\ +[`feholdexcept`](feholdexcept2.md)\ +[`fetestexcept`](fetestexcept1.md)\ +[`feupdateenv`](feupdateenv.md) diff --git a/docs/c-runtime-library/reference/ferror.md b/docs/c-runtime-library/reference/ferror.md index 2d3b16c9787..66e3c806106 100644 --- a/docs/c-runtime-library/reference/ferror.md +++ b/docs/c-runtime-library/reference/ferror.md @@ -3,14 +3,14 @@ description: "Learn more about: ferror" title: "ferror" ms.date: "4/2/2020" api_name: ["ferror", "_o_ferror"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["ferror"] helpviewer_keywords: ["ferror function", "streams, testing for errors", "errors [C++], testing for stream"] ms.assetid: 528a34bc-f2aa-4c3f-b89a-5b148e6864f7 --- -# ferror +# `ferror` Tests for an error on a stream. @@ -24,39 +24,39 @@ int ferror( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -If no error has occurred on *stream*, **ferror** returns 0. Otherwise, it returns a nonzero value. If stream is **NULL**, **ferror** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns 0. +If no error has occurred on *`stream`*, **`ferror`** returns 0. Otherwise, it returns a nonzero value. If stream is `NULL`, **`ferror`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns 0. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **ferror** routine (implemented both as a function and as a macro) tests for a reading or writing error on the file associated with *stream*. If an error has occurred, the error indicator for the stream remains set until the stream is closed or rewound, or until **clearerr** is called against it. +The **`ferror`** routine (implemented both as a function and as a macro) tests for a reading or writing error on the file associated with *`stream`*. If an error has occurred, the error indicator for the stream remains set until the stream is closed or rewound, or until `clearerr` is called against it. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**ferror**|\| +| Function | Required header | +|---|---| +| **`ferror`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [feof](feof.md). +See the example for [`feof`](feof.md). ## See also -[Error Handling](../../c-runtime-library/error-handling-crt.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[clearerr](clearerr.md)
-[_eof](eof.md)
-[feof](feof.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[perror, _wperror](perror-wperror.md)
+[Error handling](../error-handling-crt.md)\ +[Stream I/O](../stream-i-o.md)\ +[`clearerr`](clearerr.md)\ +[`_eof`](eof.md)\ +[`feof`](feof.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/fesetenv1.md b/docs/c-runtime-library/reference/fesetenv1.md index d997c924e39..9f0535d02c1 100644 --- a/docs/c-runtime-library/reference/fesetenv1.md +++ b/docs/c-runtime-library/reference/fesetenv1.md @@ -10,7 +10,7 @@ f1_keywords: ["fesetenv", "fenv/fesetenv"] helpviewer_keywords: ["fesetenv function"] ms.assetid: ffc64fff-8ea7-4d59-9e04-ff96ef8cd012 --- -# fesetenv +# `fesetenv` Sets the current floating-point environment. @@ -24,33 +24,33 @@ int fesetenv( ### Parameters -*penv*
-Pointer to a **fenv_t** object that contains a floating-point environment as set by a call to [fegetenv](fegetenv1.md) or [feholdexcept](feholdexcept2.md). You can also specify the default startup floating-point environment by using the **FE_DFL_ENV** macro. +*`penv`*\ +Pointer to a `fenv_t` object that contains a floating-point environment as set by a call to [`fegetenv`](fegetenv1.md) or [`feholdexcept`](feholdexcept2.md). You can also specify the default startup floating-point environment by using the `FE_DFL_ENV` macro. -## Return Value +## Return value -Returns 0 if the environment was successfully set. Otherwise, returns a nonzero value. +Returns 0 if the environment was successfully set. Otherwise, it returns a nonzero value. ## Remarks -The **fesetenv** function sets the current floating-point environment from the value stored in the **fenv_t** object pointed to by *penv*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. This includes the rounding mode and the status flags for floating-point exceptions. If *penv* is not **FE_DFL_ENV** or does not point to a valid **fenv_t** object, subsequent behavior is undefined. +The **`fesetenv`** function sets the current floating-point environment from the value stored in the `fenv_t` object pointed to by *`penv`*. The floating point environment is the set of status flags and control modes that affect floating-point calculations. The environment includes the rounding mode and the status flags for floating-point exceptions. If *`penv`* isn't `FE_DFL_ENV` or doesn't point to a valid `fenv_t` object, subsequent behavior is undefined. -A call to this function sets the exception status flags that are in the *penv* object, but it does not raise those exceptions. +A call to this function sets the exception status flags that are in the *`penv`* object, but it doesn't raise those exceptions. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fesetenv**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fesetenv`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fegetenv](fegetenv1.md)
-[feclearexcept](feclearexcept1.md)
-[feholdexcept](feholdexcept2.md)
-[fesetexceptflag](fesetexceptflag2.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fegetenv`](fegetenv1.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`feholdexcept`](feholdexcept2.md)\ +[`fesetexceptflag`](fesetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fesetexceptflag2.md b/docs/c-runtime-library/reference/fesetexceptflag2.md index d5b6a4d7dac..9ab471a0180 100644 --- a/docs/c-runtime-library/reference/fesetexceptflag2.md +++ b/docs/c-runtime-library/reference/fesetexceptflag2.md @@ -10,7 +10,7 @@ f1_keywords: ["fesetexceptflag", "fenv/fesetexceptflag"] helpviewer_keywords: ["fesetexceptflag function"] ms.assetid: 2f7dad77-9e54-4097-a3e3-35176ace4de5 --- -# fesetexceptflag +# `fesetexceptflag` Sets the specified floating-point status flags in the current floating-point environment. @@ -25,42 +25,42 @@ int fesetexceptflag( ### Parameters -*pstatus*
-Pointer to an **fexcept_t** object containing the values to set the exception status flags to. The object may be set by a previous call to [fegetexceptflag](fegetexceptflag2.md). +*`pstatus`*\ +Pointer to an `fexcept_t` object containing the values to set the exception status flags to. The object may be set by a previous call to [`fegetexceptflag`](fegetexceptflag2.md). -*excepts*
+*`excepts`*\ The floating-point exception status flags to set. -## Return Value +## Return value -If all the specified exception status flags are set successfully, returns 0. Otherwise, returns a nonzero value. +If all the specified exception status flags are set successfully, returns 0. Otherwise, it returns a nonzero value. ## Remarks -The **fesetexceptflag** function sets the state of the floating-point exception status flags specified by *excepts* to the corresponding values set in the **fexcept_t** object pointed to by *pstatus*. It does not raise the exceptions. The *pstatus* pointer must point to a valid **fexcept_t** object, or subsequent behavior is undefined. The **fesetexceptflag** function supports these exception macro values in *excepts*, defined in \: +The **`fesetexceptflag`** function sets the state of the floating-point exception status flags specified by *`excepts`* to the corresponding values set in the `fexcept_t` object pointed to by *`pstatus`*. It doesn't raise the exceptions. The *`pstatus`* pointer must point to a valid `fexcept_t` object, or subsequent behavior is undefined. The **`fesetexceptflag`** function supports these exception macro values in *`excepts`*, defined in \: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception Macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The *excepts* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. +The *`excepts`* argument may be zero, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other argument value is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fesetexceptflag**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fesetexceptflag`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fegetexceptflag](fegetexceptflag2.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fegetexceptflag`](fegetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fetestexcept1.md b/docs/c-runtime-library/reference/fetestexcept1.md index 6086911b230..9022c438b82 100644 --- a/docs/c-runtime-library/reference/fetestexcept1.md +++ b/docs/c-runtime-library/reference/fetestexcept1.md @@ -10,7 +10,7 @@ f1_keywords: ["fetestexcept", "fenv/fetestexcept"] helpviewer_keywords: ["fetestexept function"] ms.assetid: ca4dc43f-5573-440d-bc19-ead7571b13dc --- -# fetestexcept +# `fetestexcept` Determines which of the specified floating-point exception status flags are currently set. @@ -24,40 +24,40 @@ int fetestexcept( ### Parameters -*excepts*
+*`excepts`*\ A bitwise OR of the floating-point status flags to test. -## Return Value +## Return value On success, returns a bitmask containing a bitwise OR of the floating-point exception macros that correspond to the exception status flags currently set. Returns 0 if none of the exceptions are set. ## Remarks -Use the fetestexcept function to determine which exceptions were raised by a floating point operation. Use the *excepts* parameter to specify which exception status flags to test. The **fetestexcept** function uses these exception macros defined in \ in *excepts* and the return value: +Use the fetestexcept function to determine which exceptions were raised by a floating point operation. Use the *`excepts`* parameter to specify which exception status flags to test. The **`fetestexcept`** function uses these exception macros defined in \ in *`excepts`* and the return value: -|Exception Macro|Description| -|---------------------|-----------------| -|FE_DIVBYZERO|A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created.| -|FE_INEXACT|The function was forced to round the stored result of an earlier floating-point operation.| -|FE_INVALID|A domain error occurred in an earlier floating-point operation.| -|FE_OVERFLOW|A range error occurred; an earlier floating-point operation result was too large to be represented.| -|FE_UNDERFLOW|An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created.| -|FE_ALL_EXCEPT|The bitwise OR of all supported floating-point exceptions.| +| Exception Macro | Description | +|---|---| +| `FE_DIVBYZERO` | A singularity or pole error occurred in an earlier floating-point operation; an infinity value was created. | +| `FE_INEXACT` | The function was forced to round the stored result of an earlier floating-point operation. | +| `FE_INVALID` | A domain error occurred in an earlier floating-point operation. | +| `FE_OVERFLOW` | A range error occurred; an earlier floating-point operation result was too large to be represented. | +| `FE_UNDERFLOW` | An earlier floating-point operation result was too small to be represented at full precision; a denormal value was created. | +| `FE_ALL_EXCEPT` | The bitwise OR of all supported floating-point exceptions. | -The specified *excepts* argument may be 0, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other *excepts* argument value is undefined. +The specified *`excepts`* argument may be 0, one of the supported floating-point exception macros, or the bitwise OR of two or more of the macros. The effect of any other *`excepts`* argument value is undefined. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fetestexcept**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`fetestexcept`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[feclearexcept](feclearexcept1.md)
-[feraiseexcept](feraiseexcept.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`feraiseexcept`](feraiseexcept.md) diff --git a/docs/c-runtime-library/reference/feupdateenv.md b/docs/c-runtime-library/reference/feupdateenv.md index c016f2c2f4e..288e355f6be 100644 --- a/docs/c-runtime-library/reference/feupdateenv.md +++ b/docs/c-runtime-library/reference/feupdateenv.md @@ -9,7 +9,7 @@ f1_keywords: ["feupdateenv", "fenv/feupdateenv"] helpviewer_keywords: ["feupdateenv function"] ms.assetid: 3d170042-dfd5-4e4f-a55f-038cf2296cc9 --- -# feupdateenv +# `feupdateenv` Saves the currently raised floating-point exceptions, restores the specified floating-point environment state, and then raises the saved floating-point exceptions. @@ -23,30 +23,30 @@ int feupdateenv( ### Parameters -*penv*
-Pointer to a **fenv_t** object that contains a floating-point environment as set by a call to [fegetenv](fegetenv1.md) or [feholdexcept](feholdexcept2.md). You can also specify the default startup floating-point environment by using the FE_DFL_ENV macro. +*`penv`*\ +Pointer to a `fenv_t` object that contains a floating-point environment as set by a call to [`fegetenv`](fegetenv1.md) or [`feholdexcept`](feholdexcept2.md). You can also specify the default startup floating-point environment by using the `FE_DFL_ENV` macro. -## Return Value +## Return value -Returns 0 if all actions completed successfully. Otherwise, returns a nonzero value. +Returns 0 if all actions completed successfully. Otherwise, it returns a nonzero value. ## Remarks -The **feupdateenv** function performs multiple actions. First, it stores the current raised floating-point exception status flags in automatic storage. Then, it sets the current floating-point environment from the value stored in the **fenv_t** object pointed to by *penv*. If *penv* is not **FE_DFL_ENV** or does not point to a valid **fenv_t** object, subsequent behavior is undefined. Finally, **feupdateenv** raises the locally stored floating-point exceptions. +The **`feupdateenv`** function performs multiple actions. First, it stores the current raised floating-point exception status flags in automatic storage. Then, it sets the current floating-point environment from the value stored in the `fenv_t` object pointed to by *`penv`*. If *`penv`* isn't `FE_DFL_ENV` or doesn't point to a valid `fenv_t` object, subsequent behavior is undefined. Finally, **`feupdateenv`** raises the locally stored floating-point exceptions. -To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [fenv_access](../../preprocessor/fenv-access.md). +To use this function, you must turn off floating-point optimizations that could prevent access by using the `#pragma fenv_access(on)` directive prior to the call. For more information, see [`fenv_access`](../../preprocessor/fenv-access.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**feupdateenv**|\|\| +| Function | C header | C++ header | +|---|---|---| +| **`feupdateenv`** | \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[fegetenv](fegetenv1.md)
-[feclearexcept](feclearexcept1.md)
-[feholdexcept](feholdexcept2.md)
-[fesetexceptflag](fesetexceptflag2.md)
+[`fegetenv`](fegetenv1.md)\ +[`feclearexcept`](feclearexcept1.md)\ +[`feholdexcept`](feholdexcept2.md)\ +[`fesetexceptflag`](fesetexceptflag2.md) diff --git a/docs/c-runtime-library/reference/fflush-nolock.md b/docs/c-runtime-library/reference/fflush-nolock.md index 289af553bd3..4c83497bc94 100644 --- a/docs/c-runtime-library/reference/fflush-nolock.md +++ b/docs/c-runtime-library/reference/fflush-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fflush_nolock" title: "_fflush_nolock" +description: "Learn more about: _fflush_nolock" ms.date: "4/2/2020" api_name: ["_fflush_nolock", "_o__fflush_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fflush_nolock", "_fflush_nolock"] helpviewer_keywords: ["fflush_nolock function", "_fflush_nolock function", "streams, flushing", "flushing"] -ms.assetid: 5e33c4a1-b10c-4001-ad01-210757919291 --- -# _fflush_nolock +# `_fflush_nolock` -Flushes a stream without locking the thread. +Flushes a stream without locking. ## Syntax @@ -24,30 +23,30 @@ int _fflush_nolock( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -See [fflush](fflush.md). +See [`fflush`](fflush.md). ## Remarks -This function is a non-locking version of **fflush**. It is identical to **fflush** except that it is not protected from interference by other threads. It might be faster because it does not incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +This function is a non-locking version of `fflush`. It's identical to `fflush` except that it isn't protected from interference by other threads. It might be faster because it doesn't incur the overhead of locking out other threads. Use this function only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fflush_nolock**|\| +| Function | Required header | +|---|---| +| **`_fflush_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fclose, _fcloseall](fclose-fcloseall.md)
-[_flushall](flushall.md)
-[setvbuf](setvbuf.md)
+[Stream I/O](../stream-i-o.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`_flushall`](flushall.md)\ +[`setvbuf`](setvbuf.md) diff --git a/docs/c-runtime-library/reference/fflush.md b/docs/c-runtime-library/reference/fflush.md index 76a501abeb2..46a2eefe190 100644 --- a/docs/c-runtime-library/reference/fflush.md +++ b/docs/c-runtime-library/reference/fflush.md @@ -3,7 +3,7 @@ description: "Learn more about: fflush" title: "fflush" ms.date: "4/2/2020" api_name: ["fflush", "_o_fflush"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fflush"] @@ -24,36 +24,36 @@ int fflush( ### Parameters *`stream`*\ -Pointer to **`FILE`** structure. +Pointer to `FILE` structure. -## Return Value +## Return value -**`fflush`** returns 0 if the buffer was successfully flushed. The value 0 is also returned in cases in which the specified stream has no buffer or is open for reading only. A return value of **`EOF`** indicates an error. +**`fflush`** returns 0 if the buffer was successfully flushed. The value 0 is also returned in cases in which the specified stream has no buffer or is open for reading only. A return value of `EOF` indicates an error. > [!NOTE] -> If **`fflush`** returns **`EOF`**, data may have been lost due to a write failure. When setting up a critical error handler, it is safest to turn buffering off with the **`setvbuf`** function or to use low-level I/O routines such as **`_open`**, **`_close`**, and **`_write`** instead of the stream I/O functions. +> If **`fflush`** returns `EOF`, data may have been lost due to a write failure. When setting up a critical error handler, it is safest to turn buffering off with the **`setvbuf`** function or to use low-level I/O routines such as **`_open`**, **`_close`**, and **`_write`** instead of the stream I/O functions. ## Remarks -The **`fflush`** function flushes the stream *`stream`*. If the stream was opened in write mode, or it was opened in update mode and the last operation was a write, the contents of the stream buffer are written to the underlying file or device and the buffer is discarded. If the stream was opened in read mode, or if the stream has no buffer, the call to **`fflush`** has no effect, and any buffer is retained. A call to **`fflush`** negates the effect of any prior call to **`ungetc`** for the stream. The stream remains open after the call. +The **`fflush`** function flushes the stream *`stream`*. If the stream was opened in write mode, or it was opened in update mode and the last operation was a write, **`fflush`** writes the contents of the stream buffer to the underlying file or device, and the buffer is discarded. If the stream was opened in read mode, or if the stream has no buffer, the call to **`fflush`** has no effect, and any buffer is retained. A call to **`fflush`** negates the effect of any prior call to **`ungetc`** for the stream. The stream remains open after the call. -If *`stream`* is **`NULL`**, the behavior is the same as a call to **`fflush`** on each open stream. All streams opened in write mode and all streams opened in update mode where the last operation was a write are flushed. The call has no effect on other streams. +If *`stream`* is `NULL`, the behavior is the same as a call to **`fflush`** on each open stream. All streams opened in write mode and all streams opened in update mode where the last operation was a write are flushed. The call has no effect on other streams. Buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing the stream. The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating-system buffers. Without rewriting an existing program, you can enable this feature by linking the program's object files with `COMMODE.OBJ`. In the resulting executable file, calls to **`_flushall`** write the contents of all buffers to disk. Only **`_flushall`** and **`fflush`** are affected by `COMMODE.OBJ`. -For information about controlling the commit-to-disk feature, see [Stream I/O](../../c-runtime-library/stream-i-o.md), [`fopen`](fopen-wfopen.md), and [`_fdopen`](fdopen-wfdopen.md). +For information about controlling the commit-to-disk feature, see [Stream I/O](../stream-i-o.md), [`fopen`](fopen-wfopen.md), and [`_fdopen`](fdopen-wfdopen.md). This function locks the calling thread and is therefore thread-safe. For a non-locking version, see **`_fflush_nolock`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fflush`**|``| +| Function | Required header | +|---|---| +| **`fflush`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -107,7 +107,7 @@ User selected 5 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[Stream I/O](../stream-i-o.md)\ [`fclose`, `_fcloseall`](fclose-fcloseall.md)\ [`_flushall`](flushall.md)\ [`setvbuf`](setvbuf.md) diff --git a/docs/c-runtime-library/reference/fgetc-fgetwc.md b/docs/c-runtime-library/reference/fgetc-fgetwc.md index 3cb59a03ae6..d24916bb400 100644 --- a/docs/c-runtime-library/reference/fgetc-fgetwc.md +++ b/docs/c-runtime-library/reference/fgetc-fgetwc.md @@ -3,14 +3,14 @@ description: "Learn more about: fgetc, fgetwc" title: "fgetc, fgetwc" ms.date: "4/2/2020" api_name: ["fgetwc", "fgetc", "_o_fgetc", "_o_fgetwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fgettc", "fgetwc", "fgetc"] helpviewer_keywords: ["fgettc function", "characters, reading", "_fgettc function", "fgetc function", "streams, reading characters from", "reading characters from streams", "fgetwc function"] ms.assetid: 13348b7b-dc86-421c-9d6c-611ca79c8338 --- -# fgetc, fgetwc +# `fgetc`, `fgetwc` Read a character from a stream. @@ -27,41 +27,41 @@ wint_t fgetwc( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -**fgetc** returns the character read as an **`int`** or returns **EOF** to indicate an error or end of file. **fgetwc** returns, as a [wint_t](../../c-runtime-library/standard-types.md), the wide character that corresponds to the character read or returns **WEOF** to indicate an error or end of file. For both functions, use **feof** or **ferror** to distinguish between an error and an end-of-file condition. If a read error occurs, the error indicator for the stream is set. If *stream* is **NULL**, **fgetc** and **fgetwc** invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **EOF**. +**`fgetc`** returns the character read as an **`int`** or returns `EOF` to indicate an error or end of file. **`fgetwc`** returns, as a [`wint_t`](../standard-types.md), the wide character that corresponds to the character read or returns `WEOF` to indicate an error or end of file. For both functions, use `feof` or `ferror` to distinguish between an error and an end-of-file condition. If a read error occurs, the error indicator for the stream is set. If *`stream`* is `NULL`, **`fgetc`** and **`fgetwc`** invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EOF`. ## Remarks -Each of these functions reads a single character from the current position of the file associated with *stream*. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. +Each of these functions reads a single character from the current position of the file associated with *`stream`*. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. -**fgetc** is equivalent to **getc**, but is implemented only as a function, rather than as a function and a macro. +**`fgetc`** is equivalent to `getc`, but is implemented only as a function, rather than as a function and a macro. -**fgetwc** is the wide-character version of **fgetc**; it reads **c** as a multibyte character or a wide character according to whether *stream* is opened in text mode or binary mode. +**`fgetwc`** is the wide-character version of **`fgetc`**; it reads **c** as a multibyte character or a wide character when *`stream`* is opened in text mode or binary mode, respectively. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. -For more information about processing wide characters and multibyte characters in text and binary modes, see [Unicode Stream I/O in Text and Binary Modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +For more information about processing wide characters and multibyte characters in text and binary modes, see [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_fgettc**|**fgetc**|**fgetc**|**fgetwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_fgettc` | **`fgetc`** | **`fgetc`** | **`fgetwc`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fgetc**|\| -|**fgetwc**|\ or \| +| Function | Required header | +|---|---| +| **`fgetc`** | \ | +| **`fgetwc`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -116,6 +116,6 @@ Line two. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md b/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md index 648bcbdf3fd..59604586b6e 100644 --- a/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md +++ b/docs/c-runtime-library/reference/fgetc-nolock-fgetwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _fgetc_nolock, _fgetwc_nolock" title: "_fgetc_nolock, _fgetwc_nolock" +description: "Learn more about: _fgetc_nolock, _fgetwc_nolock" ms.date: "4/2/2020" api_name: ["_fgetc_nolock", "_fgetwc_nolock", "_o__fgetc_nolock", "_o__fgetwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fgetwc_nolock", "fgettc_nolock", "fgetwc_nolock", "_fgetc_nolock", "_fgettc_nolock", "fgetc_nolock"] helpviewer_keywords: ["fgetc_nolock function", "fgetwc_nolock function", "_fgetwc_nolock function", "characters, reading", "_fgetc_nolock function", "streams, reading characters from", "fgettc_nolock function", "reading characters from streams", "_fgettc_nolock function"] -ms.assetid: fb8e7c5b-4503-493a-879e-6a1db75aa114 --- -# _fgetc_nolock, _fgetwc_nolock +# `_fgetc_nolock`, `_fgetwc_nolock` -Reads a character from a stream without locking the thread. +Reads a character from a stream without locking. ## Syntax @@ -27,33 +26,33 @@ wint_t _fgetwc_nolock( ### Parameters -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -See[fgetc, fgetwc](fgetc-fgetwc.md). +See[`fgetc`, `fgetwc`](fgetc-fgetwc.md). ## Remarks -**_fgetc_nolock** and **_fgetwc_nolock** are identical to **fgetc** and **fgetwc**, respectively, except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_fgetc_nolock`** and **`_fgetwc_nolock`** are identical to `fgetc` and `fgetwc`, respectively, except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_fgettc_nolock**|**_fgetc_nolock**|**_fgetc_nolock**|**_fgetwc_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_fgettc_nolock`** | **`_fgetc_nolock`** | **`_fgetc_nolock`** | **`_fgetwc_nolock`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fgetc_nolock**|\| -|**_fgetwc_nolock**|\ or \| +| Function | Required header | +|---|---| +| **`_fgetc_nolock`** | \ | +| **`_fgetwc_nolock`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -107,6 +106,6 @@ Line two. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/fgetchar-fgetwchar.md b/docs/c-runtime-library/reference/fgetchar-fgetwchar.md index 2f110ed4a9c..31a0e367916 100644 --- a/docs/c-runtime-library/reference/fgetchar-fgetwchar.md +++ b/docs/c-runtime-library/reference/fgetchar-fgetwchar.md @@ -3,16 +3,16 @@ description: "Learn more about: _fgetchar, _fgetwchar" title: "_fgetchar, _fgetwchar" ms.date: "4/2/2020" api_name: ["_fgetchar", "_fgetwchar", "_o__fgetchar", "_o__fgetwchar"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fgetwchar", "_fgettchar", "_fgetchar", "_fgetwchar", "fgettchar"] helpviewer_keywords: ["fgetwchar function", "_fgetchar function", "fgettchar function", "_fgetwchar function", "_fgettchar function", "standard input, reading from", "fgetchar function"] ms.assetid: 8bce874c-701a-41a3-b1b2-feff266fb5b9 --- -# _fgetchar, _fgetwchar +# `_fgetchar`, `_fgetwchar` -Reads a character from **stdin**. +Reads a character from `stdin`. ## Syntax @@ -21,34 +21,34 @@ int _fgetchar( void ); wint_t _fgetwchar( void ); ``` -## Return Value +## Return value -**\_fgetchar** returns the character read as an **`int`** or returns `EOF` to indicate an error or end of file. **\_fgetwchar** returns, as a [wint_t](../../c-runtime-library/standard-types.md), the wide character that corresponds to the character read or returns `WEOF` to indicate an error or end of file. For both functions, use **feof** or **ferror** to distinguish between an error and an end-of-file condition. +**\_fgetchar** returns the character read as an **`int`** or returns `EOF` to indicate an error or end of file. **\_fgetwchar** returns, as a [`wint_t`](../standard-types.md), the wide character that corresponds to the character read or returns `WEOF` to indicate an error or end of file. For both functions, use `feof` or `ferror` to distinguish between an error and an end-of-file condition. ## Remarks -These functions read a single character from **stdin**. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. +These functions read a single character from `stdin`. The function then increments the associated file pointer (if defined) to point to the next character. If the stream is at end of file, the end-of-file indicator for the stream is set. -**_fgetchar** is equivalent to `fgetc( stdin )`. It is also equivalent to **getchar**, but implemented only as a function, rather than as a function and a macro. **_fgetwchar** is the wide-character version of **_fgetchar**. +**`_fgetchar`** is equivalent to `fgetc( stdin )`. It's also equivalent to `getchar`, but implemented only as a function, rather than as a function and a macro. **`_fgetwchar`** is the wide-character version of **`_fgetchar`**. -These functions are not compatible with the ANSI standard. +These functions aren't compatible with the ANSI standard. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_fgettchar**|**_fgetchar**|**_fgetchar**|**_fgetwchar**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_fgettchar` | **`_fgetchar`** | **`_fgetchar`** | **`_fgetwchar`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_fgetchar**|\| -|**_fgetwchar**|\ or \| +| Function | Required header | +|---|---| +| **`_fgetchar`** | \ | +| **`_fgetwchar`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—**stdin**, **stdout**, and **stderr**—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console—`stdin`, `stdout`, and `stderr`—must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -90,6 +90,6 @@ Line two. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/fgetchar.md b/docs/c-runtime-library/reference/fgetchar.md index b28afc3c0bf..ece234801c4 100644 --- a/docs/c-runtime-library/reference/fgetchar.md +++ b/docs/c-runtime-library/reference/fgetchar.md @@ -10,8 +10,8 @@ f1_keywords: ["fgetchar"] helpviewer_keywords: ["fgetchar function"] ms.assetid: 2b27a6f2-d973-4d12-a66d-7e6b01e84470 --- -# fgetchar +# `fgetchar` -The Microsoft-specific function name `fgetchar` is a deprecated alias for the [_fgetchar](fgetchar-fgetwchar.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `fgetchar` is a deprecated alias for the [`_fgetchar`](fgetchar-fgetwchar.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fgetchar](fgetchar-fgetwchar.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fgetchar`](fgetchar-fgetwchar.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/fgetpos.md b/docs/c-runtime-library/reference/fgetpos.md index 06aea4ce3c4..8f504d44773 100644 --- a/docs/c-runtime-library/reference/fgetpos.md +++ b/docs/c-runtime-library/reference/fgetpos.md @@ -3,14 +3,14 @@ description: "Learn more about: fgetpos" title: "fgetpos" ms.date: "4/2/2020" api_name: ["fgetpos", "_o_fgetpos"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fgetpos"] helpviewer_keywords: ["fgetpos function", "streams, file position indicator"] ms.assetid: bfa05c38-1135-418c-bda1-d41be51acb62 --- -# fgetpos +# `fgetpos` Gets a stream's file-position indicator. @@ -25,29 +25,29 @@ int fgetpos( ### Parameters -*stream*
+*`stream`*\ Target stream. -*pos*
+*`pos`*\ Position-indicator storage. -## Return Value +## Return value -If successful, **fgetpos** returns 0. On failure, it returns a nonzero value and sets **errno** to one of the following manifest constants (defined in STDIO.H): **EBADF**, which means the specified stream is not a valid file pointer or is not accessible, or **EINVAL**, which means the *stream* value or the value of *pos* is invalid, such as if either is a null pointer. If *stream* or *pos* is a **NULL** pointer, the function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If successful, **`fgetpos`** returns 0. On failure, it returns a nonzero value and sets `errno` to one of the following manifest constants (defined in STDIO.H): `EBADF`, which means the specified stream isn't a valid file pointer or isn't accessible, or `EINVAL`, which means the *`stream`* value or the value of *`pos`* is invalid, such as if either is a null pointer. If *`stream`* or *`pos`* is a `NULL` pointer, the function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). ## Remarks -The **fgetpos** function gets the current value of the *stream* argument's file-position indicator and stores it in the object pointed to by *pos*. The **fsetpos** function can later use information stored in *pos* to reset the *stream* argument's pointer to its position at the time **fgetpos** was called. The *pos* value is stored in an internal format and is intended for use only by **fgetpos** and **fsetpos**. +The **`fgetpos`** function gets the current value of the *`stream`* argument's file-position indicator and stores it in the object pointed to by *`pos`*. The `fsetpos` function can later use information stored in *`pos`* to reset the *`stream`* argument's pointer to its position at the time **`fgetpos`** was called. The *`pos`* value is stored in an internal format and is intended for use only by **`fgetpos`** and `fsetpos`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**fgetpos**|\| +| Function | Required header | +|---|---| +| **`fgetpos`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,5 +106,5 @@ after fsetpos: gets a stream ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fsetpos](fsetpos.md)
+[Stream I/O](../stream-i-o.md)\ +[`fsetpos`](fsetpos.md) diff --git a/docs/c-runtime-library/reference/fgets-fgetws.md b/docs/c-runtime-library/reference/fgets-fgetws.md index 79cc1afd53e..0467e7281dd 100644 --- a/docs/c-runtime-library/reference/fgets-fgetws.md +++ b/docs/c-runtime-library/reference/fgets-fgetws.md @@ -3,7 +3,7 @@ description: "Learn more about: fgets, fgetws" title: "fgets, fgetws" ms.date: "4/2/2020" api_name: ["fgets", "fgetws", "_o_fgets", "_o_fgetws"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fgetts", "fgetws", "fgets"] @@ -31,20 +31,20 @@ wchar_t *fgetws( ### Parameters -*`str`*
+*`str`*\ Storage location for data. -*`numChars`*
+*`numChars`*\ Maximum number of characters to read. -*`stream`*
-Pointer to **`FILE`** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -Each of these functions returns *`str`*. **`NULL`** is returned to indicate an error or an end-of-file condition. Use **`feof`** or **`ferror`** to determine whether an error occurred. If *`str`* or *`stream`* is a null pointer, or *`numChars`* is less than or equal to zero, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`errno`** is set to **`EINVAL`** and the function returns **`NULL`**. +Each of these functions returns *`str`*. `NULL` is returned to indicate an error or an end-of-file condition. Use **`feof`** or **`ferror`** to determine whether an error occurred. If *`str`* or *`stream`* is a null pointer, or *`numChars`* is less than or equal to zero, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns `NULL`. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -52,24 +52,24 @@ The **`fgets`** function reads a string from the input *`stream`* argument and s **`fgetws`** is a wide-character version of **`fgets`**. -**`fgetws`** reads the wide-character argument *`str`* as a multibyte-character string or a wide-character string according to whether *`stream`* is opened in text mode or binary mode, respectively. For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [Unicode Stream I/O in Text and Binary Modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +**`fgetws`** reads the wide-character argument *`str`* as a multibyte-character string or as a wide-character string when *`stream`* is opened in text mode or binary mode, respectively. For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_fgetts`**|**`fgets`**|**`fgets`**|**`fgetws`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_fgetts`** | **`fgets`** | **`fgets`** | **`fgetws`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fgets`**|``| -|**`fgetws`**|`` or ``| +| Function | Required header | +|---|---| +| **`fgets`** | `` | +| **`fgetws`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -111,7 +111,7 @@ Line one. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fputs`, `fputws`](fputs-fputws.md)
-[`gets`, `_getws`](../../c-runtime-library/gets-getws.md)
-[`puts`, `_putws`](puts-putws.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputs`, `fputws`](fputs-fputws.md)\ +[`gets`, `_getws`](../gets-getws.md)\ +[`puts`, `_putws`](puts-putws.md) diff --git a/docs/c-runtime-library/reference/filelength-filelengthi64.md b/docs/c-runtime-library/reference/filelength-filelengthi64.md index cd39c3b1015..e364ec9fcdf 100644 --- a/docs/c-runtime-library/reference/filelength-filelengthi64.md +++ b/docs/c-runtime-library/reference/filelength-filelengthi64.md @@ -3,14 +3,14 @@ description: "Learn more about: _filelength, _filelengthi64" title: "_filelength, _filelengthi64" ms.date: "4/2/2020" api_name: ["_filelengthi64", "_filelength", "_o__filelength", "_o__filelengthi64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_filelength", "_filelengthi64", "filelengthi64"] helpviewer_keywords: ["filelengthi64 function", "lengths, file", "filelength function", "_filelength function", "files [C++], length", "_filelengthi64 function"] ms.assetid: 3ab83d5a-543c-4079-b9d9-0abfc7da0275 --- -# _filelength, _filelengthi64 +# `_filelength`, `_filelengthi64` Gets the length of a file. @@ -27,34 +27,34 @@ __int64 _filelengthi64( ### Parameters -*fd*
+*`fd`*\ Target the file descriptor. -## Return Value +## Return value -Both **_filelength** and **_filelengthi64** return the file length, in bytes, of the target file associated with *fd*. If *fd* is an invalid file descriptor, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, both functions return -1L to indicate an error and set **errno** to **EBADF**. +Both **`_filelength`** and **`_filelengthi64`** return the file length, in bytes, of the target file associated with *`fd`*. If *`fd`* is an invalid file descriptor, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, both functions return -1L to indicate an error and set `errno` to `EBADF`. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_filelength**|\| -|**_filelengthi64**|\| +| Function | Required header | +|---|---| +| **`_filelength`** | \ | +| **`_filelengthi64`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_chsize](chsize.md). +See the example for [`_chsize`](chsize.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_chsize](chsize.md)
-[_fileno](fileno.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[_stat, _wstat Functions](stat-functions.md)
+[File handling](../file-handling.md)\ +[`_chsize`](chsize.md)\ +[`_fileno`](fileno.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_stat`, `_wstat` functions](stat-functions.md) diff --git a/docs/c-runtime-library/reference/filelength.md b/docs/c-runtime-library/reference/filelength.md index 0d42b7b3bec..566d02a67f3 100644 --- a/docs/c-runtime-library/reference/filelength.md +++ b/docs/c-runtime-library/reference/filelength.md @@ -10,8 +10,8 @@ f1_keywords: ["filelength"] helpviewer_keywords: ["filelength function"] ms.assetid: 5fbc1912-7822-498d-bbf4-8bada87cf9b9 --- -# filelength +# `filelength` -The Microsoft-specific function name `filelength` is a deprecated alias for the [_filelength](filelength-filelengthi64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `filelength` is a deprecated alias for the [`_filelength`](filelength-filelengthi64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_filelength](filelength-filelengthi64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_filelength`](filelength-filelengthi64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/fileno.md b/docs/c-runtime-library/reference/fileno.md index 4966c25c06f..2752c38476d 100644 --- a/docs/c-runtime-library/reference/fileno.md +++ b/docs/c-runtime-library/reference/fileno.md @@ -3,7 +3,7 @@ title: "_fileno" description: "API reference for _fileno; which gets the file descriptor associated with a stream." ms.date: "4/2/2020" api_name: ["_fileno", "_o__fileno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fileno"] @@ -24,30 +24,30 @@ int _fileno( ### Parameters *`stream`*\ -Pointer to the **`FILE`** structure. +Pointer to the `FILE` structure. -## Return Value +## Return value -**`_fileno`** returns the file descriptor. There's no error return. The result is undefined if *`stream`* doesn't specify an open file. If stream is **`NULL`**, **`_fileno`** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets **`errno`** to **`EINVAL`**. +**`_fileno`** returns the file descriptor. There's no error return. The result is undefined if *`stream`* doesn't specify an open file. If stream is `NULL`, **`_fileno`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns -1 and sets `errno` to `EINVAL`. -For more information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). > [!NOTE] > If **`stdout`** or **`stderr`** is not associated with an output stream (for example, in a Windows application without a console window), the file descriptor returned is -2. In previous versions, the file descriptor returned was -1. This change allows applications to distinguish this condition from an error. ## Remarks -The **`_fileno`** routine returns the file descriptor currently associated with *`stream`*. This routine is implemented both as a function and as a macro. For information about choosing either implementation, see [Choosing Between Functions and Macros](../../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md). +The **`_fileno`** routine returns the file descriptor currently associated with *`stream`*. This routine is implemented both as a function and as a macro. For information about choosing either implementation, see [Recommendations for choosing between functions and macros](../recommendations-for-choosing-between-functions-and-macros.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`_fileno`**|``| +| Function | Required header | +|---|---| +| **`_fileno`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -75,7 +75,7 @@ The file descriptor for stderr is 2 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[Stream I/O](../stream-i-o.md)\ [`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ [`_filelength`, `_filelengthi64`](filelength-filelengthi64.md)\ [`fopen`, `_wfopen`](fopen-wfopen.md)\ diff --git a/docs/c-runtime-library/reference/findclose.md b/docs/c-runtime-library/reference/findclose.md index 3284bf7187f..6d7b4d6c81b 100644 --- a/docs/c-runtime-library/reference/findclose.md +++ b/docs/c-runtime-library/reference/findclose.md @@ -3,14 +3,14 @@ description: "Learn more about: _findclose" title: "_findclose" ms.date: "4/2/2020" api_name: ["_findclose", "_o__findclose"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_findclose", "findclose"] helpviewer_keywords: ["_findclose function", "findclose function"] ms.assetid: 9216c573-0878-444c-b5d7-cdaf16fb9163 --- -# _findclose +# `_findclose` Closes the specified search handle and releases associated resources. @@ -24,26 +24,26 @@ int _findclose( ### Parameters -*handle*
-Search handle returned by a previous call to **_findfirst**. +*`handle`*\ +The search handle returned by a previous call to `_findfirst`. -## Return Value +## Return value -If successful, **_findclose** returns 0. Otherwise, it returns -1 and sets **errno** to **ENOENT**, indicating that no more matching files could be found. +If successful, **`_findclose`** returns 0. Otherwise, it returns -1 and sets `errno` to `ENOENT`, indicating that no more matching files could be found. ## Remarks -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_findclose**|\| +| Function | Required header | +|---|---| +| **`_findclose`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[System Calls](../../c-runtime-library/system-calls.md)
-[Filename Search Functions](../../c-runtime-library/filename-search-functions.md)
+[System calls](../system-calls.md)\ +[Filename search functions](../filename-search-functions.md) diff --git a/docs/c-runtime-library/reference/findfirst-functions.md b/docs/c-runtime-library/reference/findfirst-functions.md index 235a55a87ad..dcfbffe363f 100644 --- a/docs/c-runtime-library/reference/findfirst-functions.md +++ b/docs/c-runtime-library/reference/findfirst-functions.md @@ -1,14 +1,13 @@ --- description: "Learn more about: _findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64" title: "_findfirst, _findfirst32, _findfirst32i64, _findfirst64, _findfirst64i32, _findfirsti64, _wfindfirst, _wfindfirst32, _wfindfirst32i64, _wfindfirst64, _wfindfirst64i32, _wfindfirsti64" -ms.date: "4/2/2020" +ms.date: 12/09/2022 api_name: ["_findfirst", "_wfindfirst", "_findfirst32", "_wfindfirst32", "_findfirst32i64", "_wfindfirst32i64", "_findfirst64", "_wfindfirst64", "_findfirst64i32", "_wfindfirst64i32", "_findfirsti64", "_wfindfirsti64", "_o__findfirst32", "_o__findfirst32i64", "_o__findfirst64", "_o__findfirst64i32", "_o__wfindfirst32", "_o__wfindfirst32i64", "_o__wfindfirst64", "_o__wfindfirst64i32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["findfirst32i64", "wfindfirst32i64", "tfindfirst64", "_findfirst64i32", "_wfindfirst32i64", "_wfindfirsti64", "wfindfirst", "_tfindfirsti64", "findfirst32", "_tfindfirst32", "_findfirsti64", "findfirst", "wfindfirst64", "wfindfirst32", "tfindfirst32", "_wfindfirst64i32", "findfirst64i32", "tfindfirst64i32", "_wfindfirst", "findfirsti64", "_findfirst32i64", "wfindfirst64i32", "_wfindfirst32", "_findfirst32", "_tfindfirst32i64", "tfindfirst", "_tfindfirst64i32", "findfirst64", "_tfindfirst", "_findfirst64", "_tfindfirst64", "tfindfirst32i64", "_findfirst", "_wfindfirst64"] helpviewer_keywords: ["_tfindfirst64 function", "_wfindfirst64i32 function", "_wfindfirst32i64 function", "wfindfirst32 function", "_findfirst function", "wfindfirst64 function", "_wfindfirst function", "_findfirst64i32 function", "wfindfirst function", "_findfirst64 function", "tfindfirst32 function", "_tfindfirst64i32 function", "findfirst function", "findfirst32i64 function", "tfindfirst64 function", "_tfindfirst32 function", "tfindfirst32i64 function", "tfindfirst64i32 function", "_wfindfirsti64 function", "_findfirst32i64 function", "findfirst32 function", "findfirsti64 function", "findfirst64i32 function", "tfindfirsti64 function", "tfindfirst function", "_wfindfirst32 function", "wfindfirsti64 function", "_tfindfirsti64 function", "_tfindfirst function", "_tfindfirst32i64 function", "findfirst64 function", "_findfirst32 function", "_findfirsti64 function", "wfindfirst32i64 function", "wfindfirst64i32 function", "_wfindfirst64 function"] -ms.assetid: 9bb46d1a-b946-47de-845a-a0b109a33ead --- # `_findfirst`, `_findfirst32`, `_findfirst32i64`, `_findfirst64`, `_findfirst64i32`, `_findfirsti64`, `_wfindfirst`, `_wfindfirst32`, `_wfindfirst32i64`, `_wfindfirst64`, `_wfindfirst64i32`, `_wfindfirsti64` @@ -69,87 +68,87 @@ intptr_t _wfindfirst64i32( ### Parameters -*`filespec`*
+*`filespec`*\ Target file specification (can include wildcard characters). -*`fileinfo`*
-File information buffer. +*`fileinfo`*\ +File information buffer. For more information about the `fileinfo` structs, see the Remarks in [Filename search functions](../filename-search-functions.md) and see [Data type mappings](../data-type-mappings.md). The structs are defined in the same header file as the function that uses them as a parameter. -## Return Value +## Return value -If successful, **`_findfirst`** returns a unique search handle identifying the file or group of files that match the *`filespec`* specification, which can be used in a subsequent call to [`_findnext`](findnext-functions.md) or to [`_findclose`](findclose.md). Otherwise, **`_findfirst`** returns -1 and sets **`errno`** to one of the following values. +If successful, **`_findfirst`** returns a unique search handle identifying the file or group of files that match the *`filespec`* specification, which can be used in a subsequent call to [`_findnext`](findnext-functions.md) or to [`_findclose`](findclose.md). Otherwise, **`_findfirst`** returns -1 and sets `errno` to one of the following values. | errno value | Condition | |-|-| -| **`EINVAL`** | Invalid parameter: *`filespec`* or *`fileinfo`* was **`NULL`**. Or, the operating system returned an unexpected error. | -| **`ENOENT`** | File specification that could not be matched. | -| **`ENOMEM`** | Insufficient memory. | -| **`EINVAL`** | Invalid file name specification or the file name given was larger than **`MAX_PATH`**. | +| `EINVAL` | Invalid parameter: *`filespec`* or *`fileinfo`* was `NULL`. Or, the operating system returned an unexpected error. | +| `ENOENT` | File specification that couldn't be matched. | +| `ENOMEM` | Insufficient memory. | +| `EINVAL` | Invalid file name specification or the file name given was larger than `MAX_PATH`. | -For more information about these and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). ## Remarks -You must call [`_findclose`](findclose.md) after you are finished with either the **`_findfirst`** or [`_findnext`](findnext-functions.md) function (or any variants). This frees resources used by these functions in your application. +You must call [`_findclose`](findclose.md) after you're finished with either the **`_findfirst`** or [`_findnext`](findnext-functions.md) function (or any variants) provided the call to `_findfirst` succeeded. `_findclose` frees resources used by these functions in your application. Calling `_findclose` on an invalid handle returns `-1` and sets `errno` to `EINVAL`. -The variations of these functions that have the **`w`** prefix are wide-character versions; otherwise, they are identical to the corresponding single-byte functions. +The variations of these functions that have the **`w`** prefix are wide-character versions; otherwise, they're identical to the corresponding single-byte functions. -Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numeric suffix (**`32`** or **`64`**) indicates the size of the time type; the second suffix is either **`i32`** or **`i64`**, and indicates whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The **`i32`** or **`i64`** suffix is omitted if it is the same as the size of the time type, so **`_findfirst64`** also supports 64-bit file lengths and **`_findfirst32`** supports only 32-bit file lengths. +Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numeric suffix (**`32`** or **`64`**) indicates the size of the time type; the second suffix is either **`i32`** or **`i64`**, and indicates whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The **`i32`** or **`i64`** suffix is omitted if it's the same as the size of the time type, so **`_findfirst64`** also supports 64-bit file lengths and **`_findfirst32`** supports only 32-bit file lengths. -These functions use various forms of the **`_finddata_t`** structure for the *`fileinfo`* parameter. For more information about the structure, see [Filename Search Functions](../../c-runtime-library/filename-search-functions.md). +These functions use various forms of the **`_finddata_t`** structure for the *`fileinfo`* parameter. For more information about the structure, see [Filename search functions](../filename-search-functions.md). -The variations that use a 64-bit time type enable file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC. Those that use 32-bit time types represent dates only through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. +The variations that use a 64-bit time type enable file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC. The ones that use 32-bit time types represent dates only through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. -Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findfirst`** or **`_wfindfirst`** or, if you need to support file sizes larger than 3 GB, use **`_findfirsti64`** or **`_wfindfirsti64`**. All these functions use the 64-bit time type. In earlier versions, these functions used a 32-bit time type. If this is a breaking change for an application, you might define **`_USE_32BIT_TIME_T`** to revert to the old behavior. If **`_USE_32BIT_TIME_T`** is defined, **`_findfirst`**, **`_finfirsti64`**, and their corresponding Unicode versions use a 32-bit time. +Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findfirst`** or **`_wfindfirst`** or, if you need to support file sizes larger than 3 GB, use **`_findfirsti64`** or **`_wfindfirsti64`**. All these functions use the 64-bit time type. In earlier versions, these functions used a 32-bit time type. If this change is a breaking change for an application, you might define `_USE_32BIT_TIME_T` to revert to the old behavior. If `_USE_32BIT_TIME_T` is defined, **`_findfirst`**, **`_findfirsti64`**, and their corresponding Unicode versions use a 32-bit time. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Time Type and File Length Type Variations of _findfirst -|Functions|**`_USE_32BIT_TIME_T`** defined?|Time type|File length type| -|---------------|----------------------------------|---------------|----------------------| -|**`_findfirst`**, **`_wfindfirst`**|Not defined|64-bit|32-bit| -|**`_findfirst`**, **`_wfindfirst`**|Defined|32-bit|32-bit| -|**`_findfirst32`**, **`_wfindfirst32`**|Not affected by the macro definition|32-bit|32-bit| -|**`_findfirst64`**, **`_wfindfirst64`**|Not affected by the macro definition|64-bit|64-bit| -|**`_findfirsti64`**, **`_wfindfirsti64`**|Not defined|64-bit|64-bit| -|**`_findfirsti64`**, **`_wfindfirsti64`**|Defined|32-bit|64-bit| -|**`_findfirst32i64`**, **`_wfindfirst32i64`**|Not affected by the macro definition|32-bit|64-bit| -|**`_findfirst64i32`**, **`_wfindfirst64i32`**|Not affected by the macro definition|64-bit|32-bit| - -### Generic-Text Routine Mappings - -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tfindfirst`**|**`_findfirst`**|**`_findfirst`**|**`_wfindfirst`**| -|**`_tfindfirst32`**|**`_findfirst32`**|**`_findfirst32`**|**`_wfindfirst32`**| -|**`_tfindfirst64`**|**`_findfirst64`**|**`_findfirst64`**|**`_wfindfirst64`**| -|**`_tfindfirsti64`**|**`_findfirsti64`**|**`_findfirsti64`**|**`_wfindfirsti64`**| -|**`_tfindfirst32i64`**|**`_findfirst32i64`**|**`_findfirst32i64`**|**`_wfindfirst32i64`**| -|**`_tfindfirst64i32`**|**`_findfirst64i32`**|**`_findfirst64i32`**|**`_wfindfirst64i32`**| +| Functions | `_USE_32BIT_TIME_T` defined? | Time type | File length type | +|---|---|---|---| +| **`_findfirst`**, **`_wfindfirst`** | Not defined | 64-bit | 32-bit | +| **`_findfirst`**, **`_wfindfirst`** | Defined | 32-bit | 32-bit | +| **`_findfirst32`**, **`_wfindfirst32`** | Not affected by the macro definition | 32-bit | 32-bit | +| **`_findfirst64`**, **`_wfindfirst64`** | Not affected by the macro definition | 64-bit | 64-bit | +| **`_findfirsti64`**, **`_wfindfirsti64`** | Not defined | 64-bit | 64-bit | +| **`_findfirsti64`**, **`_wfindfirsti64`** | Defined | 32-bit | 64-bit | +| **`_findfirst32i64`**, **`_wfindfirst32i64`** | Not affected by the macro definition | 32-bit | 64-bit | +| **`_findfirst64i32`**, **`_wfindfirst64i32`** | Not affected by the macro definition | 64-bit | 32-bit | + +### Generic-text routine mappings + +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tfindfirst`** | **`_findfirst`** | **`_findfirst`** | **`_wfindfirst`** | +| **`_tfindfirst32`** | **`_findfirst32`** | **`_findfirst32`** | **`_wfindfirst32`** | +| **`_tfindfirst64`** | **`_findfirst64`** | **`_findfirst64`** | **`_wfindfirst64`** | +| **`_tfindfirsti64`** | **`_findfirsti64`** | **`_findfirsti64`** | **`_wfindfirsti64`** | +| **`_tfindfirst32i64`** | **`_findfirst32i64`** | **`_findfirst32i64`** | **`_wfindfirst32i64`** | +| **`_tfindfirst64i32`** | **`_findfirst64i32`** | **`_findfirst64i32`** | **`_wfindfirst64i32`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`_findfirst`**|``| -|**`_findfirst32`**|``| -|**`_findfirst64`**|``| -|**`_findfirsti64`**|``| -|**`_findfirst32i64`**|``| -|**`_findfirst64i32`**|``| -|**`_wfindfirst`**|`` or ``| -|**`_wfindfirst32`**|`` or ``| -|**`_wfindfirst64`**|`` or ``| -|**`_wfindfirsti64`**|`` or ``| -|**`_wfindfirst32i64`**|`` or ``| -|**`_wfindfirst64i32`**|`` or ``| - -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +| Function | Required header | +|---|---| +| **`_findfirst`** | `` | +| **`_findfirst32`** | `` | +| **`_findfirst64`** | `` | +| **`_findfirsti64`** | `` | +| **`_findfirst32i64`** | `` | +| **`_findfirst64i32`** | `` | +| **`_wfindfirst`** | `` or `` | +| **`_wfindfirst32`** | `` or `` | +| **`_wfindfirst64`** | `` or `` | +| **`_wfindfirsti64`** | `` or `` | +| **`_wfindfirst32i64`** | `` or `` | +| **`_wfindfirst64i32`** | `` or `` | + +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[System Calls](../../c-runtime-library/system-calls.md)
-[Filename Search Functions](../../c-runtime-library/filename-search-functions.md)
+[System calls](../system-calls.md)\ +[Filename search functions](../filename-search-functions.md) diff --git a/docs/c-runtime-library/reference/findnext-functions.md b/docs/c-runtime-library/reference/findnext-functions.md index 71efb3b7d95..bcc7d4333b2 100644 --- a/docs/c-runtime-library/reference/findnext-functions.md +++ b/docs/c-runtime-library/reference/findnext-functions.md @@ -3,16 +3,16 @@ description: "Learn more about: _findnext, _findnext32, _findnext32i64, _findnex title: "_findnext, _findnext32, _findnext32i64, _findnext64, _findnext64i32, _findnexti64, _wfindnext, _wfindnext32, _wfindnext32i64, _wfindnext64, _wfindnext64i32, _wfindnexti64" ms.date: "4/2/2020" api_name: [_findnext, _findnext32, _findnext32i64, _findnext64, _findnext64i32, _findnexti64, _wfindnext, _wfindnext32, _wfindnext32i64, _wfindnext64, _wfindnext64i32, _wfindnexti64, "_o__findnext32", "_o__findnext32i64", "_o__findnext64", "_o__findnext64i32", "_o__wfindnext32", "_o__wfindnext32i64", "_o__wfindnext64", "_o__wfindnext64i32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["findnext", "_wfindnext32i64", "_tfindnext64i32", "findnext32", "findnext32i64", "wfindnext64i32", "_wfindnext", "tfindnext64", "findnexti64", "_findnexti64", "_tfindnexti64", "_findnext64i32", "tfindnexti64", "tfindnext32", "_wfindnext64i32", "findnext64i32", "_findnext", "_tfindnext32i64", "_wfindnext64", "wfindnext", "wfindnext32", "tfindnext32i64", "_findnext64", "_tfindnext64", "_wfindnext32", "findnext64", "_findnext32i64", "tfindnext", "wfindnexti64", "tfindnext64i32", "_tfindnext32", "wfindnext32i64", "wfindnext64", "_wfindnexti64", "_tfindnext", "_findnext32"] helpviewer_keywords: ["_wfindnexti64 function", "_tfindnext32 function", "wfindnexti64 function", "_wfindnext32i64 function", "findnext32i64 function", "tfindnext64i32 function", "_tfindnext64i32 function", "_findnext function", "findnext64i32 function", "_tfindnext function", "findnext32 function", "tfindnext32 function", "_findnext32 function", "_tfindnext32i64 function", "_wfindnext function", "tfindnext function", "_findnext64 function", "findnext64 function", "_findnext64i32 function", "wfindnext32i64 function", "findnext function", "wfindnext32 function", "_wfindnext64i32 function", "findnexti64 function", "_wfindnext64 function", "_findnext32i64 function", "_findnexti64 function", "_tfindnext64 function", "wfindnext64i32 function", "tfindnexti64 function", "wfindnext64 function", "wfindnext function", "tfindnext64 function", "_wfindnext32 function", "tfindnext32i64 function", "_tfindnexti64 function"] ms.assetid: 75d97188-5add-4698-a46c-4c492378f0f8 --- -# _findnext, _findnext32, _findnext32i64, _findnext64, _findnext64i32, _findnexti64, _wfindnext, _wfindnext32, _wfindnext32i64, _wfindnext64, _wfindnext64i32, _wfindnexti64 +# `_findnext`, `_findnext32`, `_findnext32i64`, `_findnext64`, `_findnext64i32`, `_findnexti64`, `_wfindnext`, `_wfindnext32`, `_wfindnext32i64`, `_wfindnext64`, `_wfindnext64i32`, `_wfindnexti64` -Find the next name, if any, that matches the *filespec* argument in a previous call to [_findfirst](findfirst-functions.md), and then alter the *fileinfo* structure contents accordingly. +Find the next name, if any, that matches the *`filespec`* argument in a previous call to [`_findfirst`](findfirst-functions.md), and then alter the *`fileinfo`* structure contents accordingly. ## Syntax @@ -69,84 +69,84 @@ int _wfindnext64i32( ### Parameters -*handle*
-Search handle returned by a previous call to **_findfirst**. +*`handle`*\ +The search handle returned by a previous call to `_findfirst`. -*fileinfo*
+*`fileinfo`*\ File information buffer. -## Return Value +## Return value -If successful, returns 0. Otherwise, returns -1 and sets **errno** to a value indicating the nature of the failure. Possible error codes are shown in the following table. +If successful, returns 0. Otherwise, returns -1 and sets `errno` to a value indicating the nature of the failure. Possible error codes are shown in the following table. -|errno value|Condition| -|-|-| -| **EINVAL** | Invalid parameter: *fileinfo* was **NULL**. Or, the operating system returned an unexpected error. | -| **ENOENT** | No more matching files could be found. | -| **ENOMEM** | Not enough memory or the file name's length exceeded **MAX_PATH**. | +| `errno` value | Condition | +|---|---| +| `EINVAL` | Invalid parameter: *`fileinfo`* was `NULL`. Or, the operating system returned an unexpected error. | +| `ENOENT` | No more matching files could be found. | +| `ENOMEM` | Not enough memory or the file name's length exceeded `MAX_PATH`. | -If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +If an invalid parameter is passed in, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). ## Remarks -You must call [_findclose](findclose.md) after you are finished using either the **_findfirst** or **_findnext** function (or any variants). This frees up resources used by these functions in your application. +You must call [`_findclose`](findclose.md) after you're finished using either the `_findfirst` or **`_findnext`** function (or any variants). `_findclose` frees up resources used by these functions in your application. -The variations of these functions with the **w** prefix are wide-character versions; otherwise, they are identical to the corresponding single-byte functions. +The variations of these functions with the **w** prefix are wide-character versions; otherwise, they're identical to the corresponding single-byte functions. -Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numerical suffix (**32** or **64**) indicates the size of the time type used; the second suffix is either **i32** or **i64**, indicating whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The variations that use a 64-bit time type allow file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas those using 32-bit time types only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. +Variations of these functions support 32-bit or 64-bit time types and 32-bit or 64-bit file sizes. The first numerical suffix (**`32`** or **`64`**) indicates the size of the time type used; the second suffix is either **`i32`** or **`i64`**, indicating whether the file size is represented as a 32-bit or 64-bit integer. For information about which versions support 32-bit and 64-bit time types and file sizes, see the following table. The variations that use a 64-bit time type allow file-creation dates to be expressed up through 23:59:59, December 31, 3000, UTC; whereas those using 32-bit time types only represent dates through 23:59:59 January 18, 2038, UTC. Midnight, January 1, 1970, is the lower bound of the date range for all these functions. -Unless you have a specific reason to use the versions that specify the time size explicitly, use **_findnext** or **_wfindnext** or, if you need to support file sizes greater than 3 GB, use **_findnexti64** or **_wfindnexti64**. All these functions use the 64-bit time type. In previous versions, these functions used a 32-bit time type. If this is a breaking change for an application, you might define **_USE_32BIT_TIME_T** to get the old behavior. If **_USE_32BIT_TIME_T** is defined, **_findnext**, **_finnexti64** and their corresponding Unicode versions use a 32-bit time. +Unless you have a specific reason to use the versions that specify the time size explicitly, use **`_findnext`** or **`_wfindnext`** or, if you need to support file sizes greater than 3 GB, use **`_findnexti64`** or **`_wfindnexti64`**. All these functions use the 64-bit time type. In previous versions, these functions used a 32-bit time type. If this change is a breaking change for an application, you might define `_USE_32BIT_TIME_T` to get the old behavior. If `_USE_32BIT_TIME_T` is defined, **`_findnext`**, **`_findnexti64`** and their corresponding Unicode versions use a 32-bit time. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Time Type and File Length Type Variations of _findnext -|Functions|**_USE_32BIT_TIME_T** defined?|Time type|File length type| -|---------------|----------------------------------|---------------|----------------------| -|**_findnext**, **_wfindnext**|Not defined|64-bit|32-bit| -|**_findnext**, **_wfindnext**|Defined|32-bit|32-bit| -|**_findnext32**, **_wfindnext32**|Not affected by the macro definition|32-bit|32-bit| -|**_findnext64**, **_wfindnext64**|Not affected by the macro definition|64-bit|64-bit| -|**_findnexti64**, **_wfindnexti64**|Not defined|64-bit|64-bit| -|**_findnexti64**, **_wfindnexti64**|Defined|32-bit|64-bit| -|**_findnext32i64**, **_wfindnext32i64**|Not affected by the macro definition|32-bit|64-bit| -|**_findnext64i32**, **_wfindnext64i32**|Not affected by the macro definition|64-bit|32-bit| - -### Generic-Text Routine Mappings - -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tfindnext**|**_findnext**|**_findnext**|**_wfindnext**| -|**_tfindnext32**|**_findnext32**|**_findnext32**|**_wfindnext32**| -|**_tfindnext64**|**_findnext64**|**_findnext64**|**_wfindnext64**| -|**_tfindnexti64**|**_findnexti64**|**_findnexti64**|**_wfindnexti64**| -|**_tfindnext32i64**|**_findnext32i64**|**_findnext32i64**|**_wfindnext32i64**| -|**_tfindnext64i32**|**_findnext64i32**|**_findnext64i32**|**_wfindnext64i32**| +| Functions | `_USE_32BIT_TIME_T` defined? | Time type | File length type | +|---|---|---|---| +| **`_findnext`**, **`_wfindnext`** | Not defined | 64-bit | 32-bit | +| **`_findnext`**, **`_wfindnext`** | Defined | 32-bit | 32-bit | +| **`_findnext32`**, **`_wfindnext32`** | Not affected by the macro definition | 32-bit | 32-bit | +| **`_findnext64`**, **`_wfindnext64`** | Not affected by the macro definition | 64-bit | 64-bit | +| **`_findnexti64`**, **`_wfindnexti64`** | Not defined | 64-bit | 64-bit | +| **`_findnexti64`**, **`_wfindnexti64`** | Defined | 32-bit | 64-bit | +| **`_findnext32i64`**, **`_wfindnext32i64`** | Not affected by the macro definition | 32-bit | 64-bit | +| **`_findnext64i32`**, **`_wfindnext64i32`** | Not affected by the macro definition | 64-bit | 32-bit | + +### Generic-text routine mappings + +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tfindnext` | **`_findnext`** | **`_findnext`** | **`_wfindnext`** | +| `_tfindnext32` | **`_findnext32`** | **`_findnext32`** | **`_wfindnext32`** | +| `_tfindnext64` | **`_findnext64`** | **`_findnext64`** | **`_wfindnext64`** | +| `_tfindnexti64` | **`_findnexti64`** | **`_findnexti64`** | **`_wfindnexti64`** | +| **`_tfindnext32i64`** | **`_findnext32i64`** | **`_findnext32i64`** | **`_wfindnext32i64`** | +| **`_tfindnext64i32`** | **`_findnext64i32`** | **`_findnext64i32`** | **`_wfindnext64i32`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_findnext**|\| -|**_findnext32**|\| -|**_findnext64**|\| -|**_findnexti64**|\| -|**_findnext32i64**|\| -|**_findnext64i32**|\| -|**_wfindnext**|\ or \| -|**_wfindnext32**|\ or \| -|**_wfindnext64**|\ or \| -|**_wfindnexti64**|\ or \| -|**_wfindnext32i64**|\ or \| -|**_wfindnext64i32**|\ or \| - -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +| Function | Required header | +|---|---| +| **`_findnext`** | \ | +| **`_findnext32`** | \ | +| **`_findnext64`** | \ | +| **`_findnexti64`** | \ | +| **`_findnext32i64`** | \ | +| **`_findnext64i32`** | \ | +| **`_wfindnext`** | \ or \ | +| **`_wfindnext32`** | \ or \ | +| **`_wfindnext64`** | \ or \ | +| **`_wfindnexti64`** | \ or \ | +| **`_wfindnext32i64`** | \ or \ | +| **`_wfindnext64i32`** | \ or \ | + +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[System Calls](../../c-runtime-library/system-calls.md)
-[Filename Search Functions](../../c-runtime-library/filename-search-functions.md)
+[System calls](../system-calls.md)\ +[Filename search functions](../filename-search-functions.md) diff --git a/docs/c-runtime-library/reference/finite-finitef.md b/docs/c-runtime-library/reference/finite-finitef.md index 54ccf595f11..4bc7c14d38a 100644 --- a/docs/c-runtime-library/reference/finite-finitef.md +++ b/docs/c-runtime-library/reference/finite-finitef.md @@ -10,7 +10,7 @@ f1_keywords: ["isfinite", "finite", "_finite", "_finitef", "math/isfinite", "mat helpviewer_keywords: ["finite function", "_finite function", "_finitef function"] ms.assetid: 5a7d7ca7-befb-4e1f-831d-28713c6eb805 --- -# isfinite, _finite, _finitef +# `isfinite`, `_finite`, `_finitef` Determines whether a floating-point value is finite. @@ -37,12 +37,12 @@ int _finitef( ### Parameters -*x*
+*`x`*\ The floating-point value to test. ## Return value -The `isfinite` macro and the `_finite` and `_finitef` functions return a non-zero value if *x* is either a normal or subnormal finite value. They return 0 if the argument is infinite or a NaN. The C++ inline template function `isfinite` behaves the same way, but returns **`true`** or **`false`**. +The `isfinite` macro and the `_finite` and `_finitef` functions return a non-zero value if *`x`* is either a normal or subnormal finite value. They return 0 if the argument is infinite or a NaN. The C++ inline template function `isfinite` behaves the same way, but returns **`true`** or **`false`**. ## Remarks @@ -50,18 +50,18 @@ The `isfinite` macro and the `_finite` and `_finitef` functions return a non-zer ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------------|-------------------------------| -|`_finite`|\ or \|\, \, \, or \| -|`isfinite`, `_finitef`|\|\ or \| +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| `_finite` | \ or \ | \, \, \, or \ | +| `isfinite`, `_finitef` | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md) diff --git a/docs/c-runtime-library/reference/floating-point-ordering.md b/docs/c-runtime-library/reference/floating-point-ordering.md index 1d8bb94251c..acdf45961dc 100644 --- a/docs/c-runtime-library/reference/floating-point-ordering.md +++ b/docs/c-runtime-library/reference/floating-point-ordering.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered" title: "isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered" +description: "Learn more about: isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered" ms.date: "01/31/2019" f1_keywords: ["isgreater", "math/isgreater", "isgreaterequal", "math/isgreaterequal", "isless", "math/isless", "islessequal", "math/islessequal", "islessgreater", "math/islessgreater", "isunordered", "math/isunordered"] helpviewer_keywords: ["isgreater function", "isgreaterequal function", "isless function", "islessequal function", "islessgreater function", "isunordered function"] --- -# isgreater, isgreaterequal, isless, islessequal, islessgreater, isunordered +# `isgreater`, `isgreaterequal`, `isless`, `islessequal`, `islessgreater`, `isunordered` Determines the ordering relationship between two floating-point values. @@ -43,7 +43,7 @@ int isunordered( ); /* C-only macro */ ``` -```C++ +```cpp template inline bool isgreater( FloatingType1 x, @@ -83,18 +83,18 @@ inline bool isunordered( ### Parameters -*x*, *y*
+*`x`*, *`y`*\ The floating-point values to compare. -## Return Value +## Return value -In all comparisons, infinities of the same sign compare as equal. Negative infinity is less than any finite value or positive infinity. Positive infinity is greater than any finite value or negative infinity. Zeroes are equal regardless of sign. NaNs are not less than, equal to, or greater than any value, including another NaN. +In all comparisons, infinities of the same sign compare as equal. Negative infinity is less than any finite value or positive infinity. Positive infinity is greater than any finite value or negative infinity. Zeroes are equal regardless of sign. NaNs aren't less than, equal to, or greater than any value, including another NaN. -When neither argument is a NaN, the ordering macros **isgreater**, **isgreaterequal**, **isless**, and **islessequal** return a non-zero value if the specified ordering relation between *x* and *y* holds true. These macros return 0 if either or both arguments are NaNs or if the ordering relationship is false. The function forms behave the same way, but return **`true`** or **`false`**. +When neither argument is a NaN, the ordering macros **`isgreater`**, **`isgreaterequal`**, **`isless`**, and **`islessequal`** return a non-zero value if the specified ordering relation between *`x`* and *`y`* holds true. These macros return 0 if either or both arguments are NaNs or if the ordering relationship is false. The function forms behave the same way, but return **`true`** or **`false`**. -The **islessgreater** macro returns a non-zero value if both *x* and *y* are not NaNs, and *x* is either less than or greater than *y*. It returns 0 if either or both arguments are NaNs, or if the values are equal. The function form behaves the same way, but returns **`true`** or **`false`**. +The **`islessgreater`** macro returns a non-zero value if both *`x`* and *`y`* aren't NaNs, and *`x`* is either less than or greater than *`y`*. It returns 0 if either or both arguments are NaNs, or if the values are equal. The function form behaves the same way, but returns **`true`** or **`false`**. -The **isunordered** macro returns a non-zero value if either *x*, *y*, or both are NaNs. Otherwise, it returns 0. The function form behaves the same way, but returns **`true`** or **`false`**. +The **`isunordered`** macro returns a non-zero value if either *`x`*, *`y`*, or both are NaNs. Otherwise, it returns 0. The function form behaves the same way, but returns **`true`** or **`false`**. ## Remarks @@ -102,16 +102,16 @@ These comparison operations are implemented as macros when compiled as C, and as ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------------|-------------------------------| -| **isgreater**, **isgreaterequal**, **isless**,
**islessequal**, **islessgreater**, **isunordered** | \ | \ or \ | +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`isgreater`**, **`isgreaterequal`**, **`isless`**,
**`islessequal`**, **`islessgreater`**, **`isunordered`** | \ | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) diff --git a/docs/c-runtime-library/reference/floating-point-primitives.md b/docs/c-runtime-library/reference/floating-point-primitives.md index bd74ad4ce6a..965ac7ec2db 100644 --- a/docs/c-runtime-library/reference/floating-point-primitives.md +++ b/docs/c-runtime-library/reference/floating-point-primitives.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Floating-point primitives" title: "Floating-point primitives" -ms.date: "4/2/2020" +description: "Learn more about: Floating-point primitives" +ms.date: 4/2/2020 api_name: ["_dclass", "_ldclass", "_fdclass", "_dsign", "_ldsign", "_fdsign", "_dpcomp", "_ldpcomp", "_fdpcomp", "_dtest", "_ldtest", "_fdtest", "_d_int", "_ld_int", "_fd_int", "_dscale", "_ldscale", "_fdscale", "_dunscale", "_ldunscale", "_fdunscale", "_dexp", "_ldexp", "_fdexp", "_dnorm", "_fdnorm", "_dpoly", "_ldpoly", "_fdpoly", "_dlog", "_ldlog", "_fdlog", "_dsin", "_ldsin", "_fdsin", "_o__d_int", "_o__dclass", "_o__dlog", "_o__dnorm", "_o__dpcomp", "_o__dpoly", "_o__dscale", "_o__dsign", "_o__dsin", "_o__dtest", "_o__dunscale", "_o__fd_int", "_o__fdclass", "_o__fdexp", "_o__fdlog", "_o__fdpcomp", "_o__fdpoly", "_o__fdscale", "_o__fdsign", "_o__fdsin", "_o__ld_int", "_o__ldclass", "_o__ldexp", "_o__ldlog", "_o__ldpcomp", "_o__ldpoly", "_o__ldscale", "_o__ldsign", "_o__ldsin", "_o__ldtest", "_o__ldunscale"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_dclass", "_ldclass", "_fdclass", "_dsign", "_ldsign", "_fdsign", "_dpcomp", "_ldpcomp", "_fdpcomp", "_dtest", "_ldtest", "_fdtest", "_d_int", "_ld_int", "_fd_int", "_dscale", "_ldscale", "_fdscale", "_dunscale", "_ldunscale", "_fdunscale", "_dexp", "_ldexp", "_fdexp", "_dnorm", "_fdnorm", "_dpoly", "_ldpoly", "_fdpoly", "_dlog", "_ldlog", "_fdlog", "_dsin", "_ldsin", "_fdsin"] @@ -13,9 +13,9 @@ helpviewer_keywords: ["_dclass", "_ldclass", "_fdclass", "_dsign", "_ldsign", "_ Microsoft-specific primitive functions that are used to implement some standard C runtime library (CRT) floating-point functions. They're documented here for completeness, but aren't recommended for use. Some of these functions are noted as unused, because they're known to have issues in precision, exception handling, and conformance to IEEE-754 behavior. They exist in the library only for backward compatibility. For correct behavior, portability, and adherence to standards, prefer the standard floating-point functions over these functions. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -## _dclass, _ldclass, _fdclass +## `_dclass`, `_ldclass`, `_fdclass` ### Syntax @@ -27,24 +27,24 @@ short __cdecl _fdclass(float x); ### Parameters -*x*
+*`x`*\ Floating-point function argument. ### Remarks -These floating-point primitives implement the C versions of the CRT macro [fpclassify](fpclassify.md) for floating-point types. The classification of the argument *x* is returned as one of these constants, defined in math.h: +These floating-point primitives implement the C versions of the CRT macro [`fpclassify`](fpclassify.md) for floating-point types. The classification of the argument *`x`* is returned as one of these constants, defined in `math.h`: -|Value|Description| -|-----------|-----------------| -| **FP_NAN** | A quiet, signaling, or indeterminate NaN | -| **FP_INFINITE** | A positive or negative infinity | -| **FP_NORMAL** | A positive or negative normalized non-zero value | -| **FP_SUBNORMAL** | A positive or negative subnormal (denormalized) value | -| **FP_ZERO** | A positive or negative zero value | +| Value | Description | +|---|---| +| `FP_NAN` | A quiet, signaling, or indeterminate NaN | +| `FP_INFINITE` | A positive or negative infinity | +| `FP_NORMAL` | A positive or negative normalized non-zero value | +| `FP_SUBNORMAL` | A positive or negative subnormal (denormalized) value | +| `FP_ZERO` | A positive or negative zero value | -For additional detail, you can use the Microsoft-specific [_fpclass, _fpclassf](fpclass-fpclassf.md) functions. Use the [fpclassify](fpclassify.md) macro or function for portability. +For more detail, you can use the Microsoft-specific [`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) functions. Use the [`fpclassify`](fpclassify.md) macro or function for portability. -## _dsign, _ldsign, _fdsign +## `_dsign`, `_ldsign`, `_fdsign` ### Syntax @@ -56,14 +56,14 @@ int __cdecl _fdsign(float x); ### Parameters -*x*
+*`x`*\ Floating-point function argument. ### Remarks -These floating-point primitives implement the [signbit](signbit.md) macro or function in the CRT. They return a non-zero value if the sign bit is set in the significand (mantissa) of the argument *x*, and 0 if the sign bit is not set. +These floating-point primitives implement the [`signbit`](signbit.md) macro or function in the CRT. They return a non-zero value if the sign bit is set in the significand (mantissa) of the argument *`x`*. Otherwise, they return 0 if the sign bit isn't set. -## _dpcomp, _ldpcomp, _fdpcomp +## `_dpcomp`, `_ldpcomp`, `_fdpcomp` ### Syntax @@ -75,22 +75,22 @@ int __cdecl _fdpcomp(float x, float y); ### Parameters -*x*, *y*
+*`x`*, *`y`*\ Floating-point function arguments. ### Remarks -These floating-point primitives take two arguments, *x* and *y*, and return a value that shows their ordering relationship, expressed as the bitwise or of these constants, defined in math.h: +These floating-point primitives take two arguments, *`x`* and *`y`*, and return a value that shows their ordering relationship, expressed as the bitwise or of these constants, defined in `math.h`: | Value | Description | |------------|-----------------| -| **_FP_LT** | *x* can be considered less than *y* | -| **_FP_EQ** | *x* can be considered equal to *y* | -| **_FP_GT** | *x* can be considered greater than *y* | +| `_FP_LT` | *`x`* can be considered less than *`y`* | +| `_FP_EQ` | *`x`* can be considered equal to *`y`* | +| `_FP_GT` | *`x`* can be considered greater than *`y`* | -These primitives implement the [isgreater, isgreaterequal, isless, islessequal, islessgreater, and isunordered](floating-point-ordering.md) macros and functions in the CRT. +These primitives implement the [`isgreater`, `isgreaterequal`, `isless`, `islessequal`, `islessgreater`, and `isunordered`](floating-point-ordering.md) macros and functions in the CRT. -## _dtest, _ldtest, _fdtest +## `_dtest`, `_ldtest`, `_fdtest` ### Syntax @@ -102,24 +102,24 @@ short __cdecl _fdtest(float* px); ### Parameters -*px*
+*`px`*\ Pointer to a floating-point argument. ### Remarks -These floating-point primitives implement the C++ versions of the CRT function [fpclassify](fpclassify.md) for floating-point types. The argument *x* is evaluated and the classification is returned as one of these constants, defined in math.h: +These floating-point primitives implement the C++ versions of the CRT function [`fpclassify`](fpclassify.md) for floating-point types. The argument *`x`* is evaluated and the classification is returned as one of these constants, defined in `math.h`: -|Value|Description| -|-----------|-----------------| -| **FP_NAN** | A quiet, signaling, or indeterminate NaN | -| **FP_INFINITE** | A positive or negative infinity | -| **FP_NORMAL** | A positive or negative normalized non-zero value | -| **FP_SUBNORMAL** | A positive or negative subnormal (denormalized) value | -| **FP_ZERO** | A positive or negative zero value | +| Value | Description | +|---|---| +| `FP_NAN` | A quiet, signaling, or indeterminate NaN | +| `FP_INFINITE` | A positive or negative infinity | +| `FP_NORMAL` | A positive or negative normalized non-zero value | +| `FP_SUBNORMAL` | A positive or negative subnormal (denormalized) value | +| `FP_ZERO` | A positive or negative zero value | -For additional detail, you can use the Microsoft-specific [_fpclass, _fpclassf](fpclass-fpclassf.md) functions. Use the [fpclassify](fpclassify.md) function for portability. +For more detail, you can use the Microsoft-specific [`_fpclass`, `_fpclassf`](fpclass-fpclassf.md) functions. Use the [`fpclassify`](fpclassify.md) function for portability. -## _d_int, _ld_int, _fd_int +## `_d_int`, `_ld_int`, `_fd_int` ### Syntax @@ -131,17 +131,17 @@ short __cdecl _fd_int(float* px, short exp); ### Parameters -*px*
+*`px`*\ Pointer to a floating-point argument. -*exp*
+*`exp`*\ An exponent as an integral type. ### Remarks -These floating-point primitives take a pointer to a floating-point value *px* and an exponent value *exp*, and remove the fractional part of the floating-point value below the given exponent, if possible. The value returned is the result of **fpclassify** on the input value in *px* if it's a NaN or infinity, and on the output value in *px* otherwise. +These floating-point primitives take a pointer to a floating-point value *`px`* and an exponent value *`exp`*, and remove the fractional part of the floating-point value below the given exponent, if possible. The value returned is the result of `fpclassify` on the input value in *`px`* if it's a NaN or infinity, and on the output value in *`px`* otherwise. -## _dscale, _ldscale, _fdscale +## `_dscale`, `_ldscale`, `_fdscale` ### Syntax @@ -153,17 +153,17 @@ short __cdecl _fdscale(float* px, long exp); ### Parameters -*px*
+*`px`*\ Pointer to a floating-point argument. -*exp*
+*`exp`*\ An exponent as an integral type. ### Remarks -These floating-point primitives take a pointer to a floating-point value *px* and an exponent value *exp*, and scale the value in *px* by 2*exp*, if possible. The value returned is the result of **fpclassify** on the input value in *px* if it's a NaN or infinity, and on the output value in *px* otherwise. For portability, prefer the [ldexp, ldexpf, and ldexpl](ldexp.md) functions. +These floating-point primitives take a pointer to a floating-point value *`px`* and an exponent value *`exp`*, and scale the value in *`px`* by 2*`exp`*, if possible. The value returned is the result of `fpclassify` on the input value in *`px`* if it's a NaN or infinity, and on the output value in *`px`* otherwise. For portability, prefer the [`ldexp`, `ldexpf`, `ldexpl`](ldexp.md) functions. -## _dunscale, _ldunscale, _fdunscale +## `_dunscale`, `_ldunscale`, `_fdunscale` ### Syntax @@ -175,17 +175,17 @@ short __cdecl _fdunscale(short* pexp, float* px); ### Parameters -*pexp*
+*`pexp`*\ A pointer to an exponent as an integral type. -*px*
+*`px`*\ Pointer to a floating-point argument. ### Remarks -These floating-point primitives break down the floating-point value pointed at by *px* into a significand (mantissa) and an exponent, if possible. The significand is scaled such that the absolute value is greater than or equal to 0.5 and less than 1.0. The exponent is the value *n*, where the original floating-point value is equal to the scaled significand times 2*n*. This integer exponent *n* is stored at the location pointed to by *pexp*. The value returned is the result of **fpclassify** on the input value in *px* if it's a NaN or infinity, and on the output value otherwise. For portability, prefer the [frexp, frexpf, frexpl](frexp.md) functions. +These floating-point primitives break down the floating-point value pointed at by *`px`* into a significand (mantissa) and an exponent, if possible. The significand is scaled such that the absolute value is greater than or equal to 0.5 and less than 1.0. The exponent is the value *`n`*, where the original floating-point value is equal to the scaled significand times 2n. This integer exponent *`n`* is stored at the location pointed to by *`pexp`*. The value returned is the result of `fpclassify` on the input value in *`px`* if it's a NaN or infinity, and on the output value otherwise. For portability, prefer the [`frexp`, `frexpf`, `frexpl`](frexp.md) functions. -## _dexp, _ldexp, _fdexp +## `_dexp`, `_ldexp`, `_fdexp` ### Syntax @@ -197,20 +197,20 @@ short __cdecl _fdexp(float* px, float y, long exp); ### Parameters -*y*
+*`y`*\ Floating-point function argument. -*px*
+*`px`*\ Pointer to a floating-point argument. -*exp*
+*`exp`*\ An exponent as an integral type. ### Remarks -These floating-point primitives construct a floating-point value in the location pointed at by *px* equal to *y* * 2*exp*. The value returned is the result of **fpclassify** on the input value in *y* if it's a NaN or infinity, and on the output value in *px* otherwise. For portability, prefer the [ldexp, ldexpf, and ldexpl](ldexp.md) functions. +These floating-point primitives construct a floating-point value in the location pointed at by *`px`* equal to *`y`* * 2exp. The value returned is the result of `fpclassify` on the input value in *`y`* if it's a NaN or infinity, and on the output value in *`px`* otherwise. For portability, prefer the [`ldexp`, `ldexpf`, `ldexpl`](ldexp.md) functions. -## _dnorm, _fdnorm +## `_dnorm`, `_fdnorm` ### Syntax @@ -221,39 +221,39 @@ short __cdecl _fdnorm(unsigned short* ps); ### Parameters -*ps*
+*`ps`*\ Pointer to the bitwise representation of a floating-point value expressed as an array of **`unsigned short`**. ### Remarks -These floating-point primitives normalize the fractional part of an underflowed floating-point value and adjust the *characteristic*, or biased exponent, to match. The value is passed as the bitwise representation of the floating-point type converted to an array of **`unsigned short`** through the `_double_val`, `_ldouble_val`, or `_float_val` type punning union declared in math.h. The return value is the result of **fpclassify** on the input floating-point value if it's a NaN or infinity, and on the output value otherwise. +These floating-point primitives normalize the fractional part of an underflowed floating-point value and adjust the *characteristic*, or biased exponent, to match. The value is passed as the bitwise representation of the floating-point type converted to an array of **`unsigned short`** through the `_double_val`, `_ldouble_val`, or `_float_val` type-punning union declared in `math.h`. The return value is the result of `fpclassify` on the input floating-point value if it's a NaN or infinity, and on the output value otherwise. -## _dpoly, _ldpoly, _fdpoly +## `_dpoly`, `_ldpoly`, `_fdpoly` ### Syntax ```C double __cdecl _dpoly(double x, double const* table, int n); long double __cdecl _ldpoly(long double x, long double const* table, int n); -float __cdecl _fdpoly(float x, _float const* table, int n); +float __cdecl _fdpoly(float x, float const* table, int n); ``` ### Parameters -*x*
+*`x`*\ Floating-point function argument. -*table*
+*`table`*\ Pointer to a table of constant coefficients for a polynomial. -*n*
+*`n`*\ Order of the polynomial to evaluate. ### Remarks -These floating-point primitives return the evaluation of *x* in the polynomial of order *n* whose coefficients are represented by the corresponding constant values in *table*. For example, if *table*\[0] = 3.0, *table*\[1] = 4.0, *table*\[2] = 5.0, and *n* = 2, it represents the polynomial 5.0x2 + 4.0x + 3.0. If this polynomial is evaluated for *x* of 2.0, the result is 31.0. These functions aren't used internally. +These floating-point primitives return the evaluation of *`x`* in the polynomial of order *`n`* whose coefficients are represented by the corresponding constant values in *`table`*. For example, if *`table[0]`* = 3.0, *`table[1]`* = 4.0, *`table[2]`* = 5.0, and *`n`* = 2, it represents the polynomial 5.0x2 + 4.0x + 3.0. If this polynomial is evaluated for *`x`* of 2.0, the result is 31.0. These functions aren't used internally. -## _dlog, _dlog, _dlog +## `_dlog`, `_ldlog`, `_fdlog` ### Syntax @@ -265,17 +265,17 @@ float __cdecl _fdlog(float x, int base_flag); ### Parameters -*x*
+*`x`*\ Floating-point function argument. -*base_flag*
+*`base_flag`*\ Flag that controls the base to use, 0 for base *e* and non-zero for base 10. ### Remarks -These floating-point primitives return the natural log of *x*, ln(*x*) or log*e*(*x*), when *base_flag* is 0. They return the log base 10 of *x*, or log10(*x*), when *base_flag* is non-zero. These functions aren't used internally. For portability, prefer the functions [log, logf, logl, log10, log10f, and log10l](log-logf-log10-log10f.md). +These floating-point primitives return the natural log of *`x`* (ln(x) or log*e*(x)), when *`base_flag`* is 0. They return the log base 10 of *`x`*, or log10(x), when *`base_flag`* is non-zero. These functions aren't used internally. For portability, prefer the functions [`log`, `logf`, `logl`, `log10`, `log10f`, and `log10l`](log-logf-log10-log10f.md). -## _dsin, _ldsin, _fdsin +## `_dsin`, `_ldsin`, `_fdsin` ### Syntax @@ -287,33 +287,33 @@ float __cdecl _fdsin(float x, unsigned int quadrant); ### Parameters -*x*
+*`x`*\ Floating-point function argument. -*quadrant*
+*`quadrant`*\ Quadrant offset of 0, 1, 2, or 3 to use to produce `sin`, `cos`, `-sin`, and `-cos` results. ### Remarks -These floating-point primitives return the sine of *x* offset by the *quadrant* modulo 4. Effectively, they return the sine, cosine, -sine, and -cosine of *x* when *quadrant* modulo 4 is 0, 1, 2, or 3, respectively. These functions aren't used internally. For portability, prefer the [sin, sinf, sinl](sin-sinf-sinl.md), [cos, cosf, and cosl](cos-cosf-cosl.md) functions. +These floating-point primitives return the sine of *`x`* offset by the *`quadrant`* modulo 4. Effectively, they return the sine, cosine, -sine, and -cosine of *`x`* when *`quadrant`* modulo 4 is 0, 1, 2, or 3, respectively. These functions aren't used internally. For portability, prefer the [`sin`, `sinf`, `sinl`](sin-sinf-sinl.md), [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md) functions. ## Requirements -Header: \ +Header: `` -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-point support](../floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
-[cos, cosf, cosl](cos-cosf-cosl.md)
-[frexp, frexpf, frexpl](frexp.md)
-[ldexp, ldexpf, and ldexpl](ldexp.md)
-[log, logf, logl, log10, log10f, log10l](log-logf-log10-log10f.md)
-[sin, sinf, sinl](sin-sinf-sinl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md)\ +[`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ +[`frexp`, `frexpf`, `frexpl`](frexp.md)\ +[`ldexp`, `ldexpf`, `ldexpl`](ldexp.md)\ +[`log`, `logf`, `logl`, `log10`, `log10f`, `log10l`](log-logf-log10-log10f.md)\ +[`sin`, `sinf`, `sinl`](sin-sinf-sinl.md) diff --git a/docs/c-runtime-library/reference/floor-floorf-floorl.md b/docs/c-runtime-library/reference/floor-floorf-floorl.md index 2f05bbc33fa..5e9997e6364 100644 --- a/docs/c-runtime-library/reference/floor-floorf-floorl.md +++ b/docs/c-runtime-library/reference/floor-floorf-floorl.md @@ -1,16 +1,15 @@ --- title: "floor, floorf, floorl" -description: "API reference for floor, floorf, and floorl; which calculates the floor of a value." -ms.date: "9/1/2020" +description: "API reference for floor, floorf, and floorl; which calculates the floor of a value." +ms.date: 9/1/2020 api_name: ["floorf", "floorl", "floor", "_o_floor", "_o_floorf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["floor", "floorl", "_floorl", "floorf"] helpviewer_keywords: ["floor function", "floorf function", "calculating floors of values", "floorl function"] -ms.assetid: e9955f70-d659-414f-8050-132e13c8ff36 --- -# floor, floorf, floorl +# `floor`, `floorf`, `floorl` Calculates the floor of a value. @@ -32,40 +31,40 @@ float floorf( long double floorl( long double x ); -#define floor(X) // Requires C11 or higher +#define floor(X) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ Floating-point value. -## Return Value +## Return value -The **floor** functions return a floating-point value that represents the largest integer that is less than or equal to *x*. There's no error return. +The **`floor`** functions return a floating-point value that represents the largest integer that is less than or equal to *`x`*. There's no error return. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± QNAN,IND|none|_DOMAIN| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | -**floor** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [_set_SSE2_enable](set-sse2-enable.md). +**`floor`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md). ## Remarks -C++ allows overloading, so you can call overloads of **floor** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **floor** always takes and returns a **`double`**. +C++ allows overloading, so you can call overloads of **`floor`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`floor`** always takes and returns a **`double`**. -If you use the \ `floor()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `floor()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**floor**, **floorf**, **floorl**|\| -|**floor** macro | \ | +| Function | Required header | +|---|---| +| **`floor`**, **`floorf`**, **`floorl`** | \ | +| **`floor`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -104,7 +103,7 @@ The ceil of -2.8 is -2.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ceil, ceilf, ceill](ceil-ceilf-ceill.md)
-[round, roundf, roundl](round-roundf-roundl.md)
-[fmod, fmodf](fmod-fmodf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`round`, `roundf`, `roundl`](round-roundf-roundl.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md) diff --git a/docs/c-runtime-library/reference/flushall.md b/docs/c-runtime-library/reference/flushall.md index e52662a35aa..504c655a090 100644 --- a/docs/c-runtime-library/reference/flushall.md +++ b/docs/c-runtime-library/reference/flushall.md @@ -3,14 +3,14 @@ title: "_flushall" description: "API reference for _flushall; which flushes all streams and clears all buffers." ms.date: "4/2/2020" api_name: ["_flushall", "_o__flushall"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_flushall"] helpviewer_keywords: ["flushall function", "flushing streams", "streams, flushing", "_flushall function"] ms.assetid: 2cd73562-6d00-4ca2-b13c-80d0ae7870b5 --- -# _flushall +# `_flushall` Flushes all streams; clears all buffers. @@ -20,29 +20,29 @@ Flushes all streams; clears all buffers. int _flushall( void ); ``` -## Return Value +## Return value -**_flushall** returns the number of open streams (input and output). There's no error return. +**`_flushall`** returns the number of open streams (input and output). There's no error return. ## Remarks -By default, the **_flushall** function writes to appropriate files the contents of all buffers associated with open output streams. All buffers associated with open input streams are cleared of their current contents. (These buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing streams.) +By default, the **`_flushall`** function writes to appropriate files the contents of all buffers associated with open output streams. All buffers associated with open input streams are cleared of their current contents. (These buffers are normally maintained by the operating system, which determines the optimal time to write the data automatically to disk: when a buffer is full, when a stream is closed, or when a program terminates normally without closing streams.) -If a read follows a call to **_flushall**, new data is read from the input files into the buffers. All streams remain open after the call to **_flushall**. +If a read follows a call to **`_flushall`**, new data is read from the input files into the buffers. All streams remain open after the call to **`_flushall`**. -The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system buffers. Without rewriting an existing program, you can enable this feature by linking the program's object files with Commode.obj. In the resulting executable file, calls to **_flushall** write the contents of all buffers to disk. Only **_flushall** and [fflush](fflush.md) are affected by Commode.obj. +The commit-to-disk feature of the run-time library lets you ensure that critical data is written directly to disk rather than to the operating system buffers. Without rewriting an existing program, you can enable this feature by linking the program's object files with Commode.obj. In the resulting executable file, calls to **`_flushall`** write the contents of all buffers to disk. Only **`_flushall`** and [`fflush`](fflush.md) are affected by Commode.obj. -For information about controlling the commit-to-disk feature, see [Stream I/O](../../c-runtime-library/stream-i-o.md), [fopen](fopen-wfopen.md), and [_fdopen](fdopen-wfdopen.md). +For information about controlling the commit-to-disk feature, see [Stream I/O](../stream-i-o.md), [`fopen`](fopen-wfopen.md), and [`_fdopen`](fdopen-wfdopen.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**_flushall**|\| +| Function | Required header | +|---|---| +| **`_flushall`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -68,8 +68,8 @@ There were 3 streams flushed ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_commit](commit.md)
-[fclose, _fcloseall](fclose-fcloseall.md)
-[fflush](fflush.md)
-[setvbuf](setvbuf.md)
+[Stream I/O](../stream-i-o.md)\ +[`_commit`](commit.md)\ +[`fclose`, `_fcloseall`](fclose-fcloseall.md)\ +[`fflush`](fflush.md)\ +[`setvbuf`](setvbuf.md) diff --git a/docs/c-runtime-library/reference/fma-fmaf-fmal.md b/docs/c-runtime-library/reference/fma-fmaf-fmal.md index 2d0f177e3ea..07f439ce48c 100644 --- a/docs/c-runtime-library/reference/fma-fmaf-fmal.md +++ b/docs/c-runtime-library/reference/fma-fmaf-fmal.md @@ -1,18 +1,17 @@ --- 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." -ms.date: "9/1/2020" +description: "API reference for fma, fmaf, and fmal; which multiplies two values together, adds a third value, and then rounds the result, while only losing a small amount of precision due to intermediary rounding." +ms.date: 9/1/2020 api_name: ["fma", "fmaf", "fmal", "_o_fma", "_o_fmaf", "_o_fmal"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fma", "fmaf", "fmal", "math/fma", "math/fmaf", "math/fmal"] helpviewer_keywords: ["fma function", "fmaf function", "fmal function"] -ms.assetid: 584a6037-da1e-4e86-9f0c-97aae86de0c0 --- -# fma, fmaf, fmal +# `fma`, `fmaf`, `fmal` -Multiplies two values together, adds a third value, and then rounds the result, without losing any precision due to intermediary rounding. +Multiplies two values together, adds a third value, and then rounds the result, while only losing a small amount of precision due to intermediary rounding. ## Syntax @@ -47,58 +46,58 @@ long double fmal( long double z ); -#define fma(X, Y, Z) // Requires C11 or higher +#define fma(X, Y, Z) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ The first value to multiply. -*y*\ +*`y`*\ The second value to multiply. -*z*\ +*`z`*\ The value to add. -## Return Value +## Return value -Returns `(x * y) + z`. The return value is then rounded using the current rounding format. +Returns approximately `(x * y) + z`. The return value is then rounded using the current rounding format, although in many cases, it returns incorrectly rounded results and thus the value may be inexact by up to half an ulp from the correct value. Otherwise, may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = INFINITY, *y* = 0 or

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

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

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

not (*`x`*=indefinite, *`y`*=0) and *`z`* = NaN | NaN | +| Overflow range error | ±`HUGE_VAL`, ±`HUGE_VALF`, or ±`HUGE_VALL` | +| Underflow range error | correct value, after rounding. | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **fma** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **fma** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`fma`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`fma`** always takes and returns a **`double`**. -If you use the \ `fma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. This function computes the value as though it were taken to infinite precision, and then rounds the final result. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fma**, **fmaf**, **fmal**|\|\| -|**fma** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`fma`**, **`fmaf`**, **`fmal`** | \ | \ | +| **`fma`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[remainder, remainderf, remainderl](remainder-remainderf-remainderl.md)
-[remquo, remquof, remquol](remquo-remquof-remquol.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`remainder`, `remainderf`, `remainderl`](remainder-remainderf-remainderl.md)\ +[`remquo`, `remquof`, `remquol`](remquo-remquof-remquol.md) diff --git a/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md b/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md index ce863ac8557..eac6d8411b6 100644 --- a/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md +++ b/docs/c-runtime-library/reference/fmax-fmaxf-fmaxl.md @@ -1,16 +1,15 @@ --- title: "fmax, fmaxf, fmaxl" description: "API reference for fmax, fmaxf, and fmaxl; which determines the larger of two numeric values." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["fmax", "fmaxf", "fmaxl"] api_location: ["msvcrt.dll", "msvcr80.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: ["fmax", "fmaxf", "fmaxl", "math/fmax", "math/fmaxf", "math/fmaxl"] helpviewer_keywords: ["fmax function", "fmaxf function", "fmaxl function"] -ms.assetid: a773ccf7-495e-4a9a-8c6d-dfb53e341e35 --- -# fmax, fmaxf, fmaxl +# `fmax`, `fmaxf`, `fmaxl` Determine the larger of two specified numeric values. @@ -42,47 +41,47 @@ long double fmaxl( long double y ); -#define fmax(X, Y) // Requires C11 or higher +#define fmax(X, Y) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ The first value to compare. -*y*\ +*`y`*\ The second value to compare. -## Return Value +## Return value -If successful, returns the larger of *x* or *y*. The value returned is exact, and does not depend on any form of rounding. +If successful, returns the larger of *`x`* or *`y`*. The value returned is exact, and doesn't depend on any form of rounding. Otherwise, may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = NaN|*y*| -|*y* = NaN|*x*| -|*x* and *y* = NaN|NaN| +| Issue | Return | +|---|---| +| *`x`* = NaN | *`y`* | +| *`y`* = NaN | *`x`* | +| *`x`* and *`y`* = NaN | NaN | -This function does not use the errors specified in [_matherr](matherr.md). +This function doesn't use the errors specified in [`_matherr`](matherr.md). ## Remarks Because C++ allows overloading, you can call overloads of fmax that take and return `float` and `long double` types. In a C program, unless you're using the \ macro to call this function, `fmax` always takes and returns a double. -If you use the \ `fmax()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fmax()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**fmax**, **fmaxf**, **fmaxl**|\|\ or \| -|**fmax** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`fmax`**, **`fmaxf`**, **`fmaxl`** | \ | \ or \ | +| **`fmax`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fmin, fminf, fminl](fmin-fminf-fminl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fmin`, `fminf`, `fminl`](fmin-fminf-fminl.md) diff --git a/docs/c-runtime-library/reference/fmin-fminf-fminl.md b/docs/c-runtime-library/reference/fmin-fminf-fminl.md index 1d7c0035e17..d3cfee38cff 100644 --- a/docs/c-runtime-library/reference/fmin-fminf-fminl.md +++ b/docs/c-runtime-library/reference/fmin-fminf-fminl.md @@ -1,16 +1,15 @@ --- title: "fmin, fminf, fminl" description: "API reference for fmin, fminf, and fminl; which determines the smaller of two values." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["fmin", "fminf", "fminl"] api_location: ["msvcrt.dll", "msvcr80.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: ["fmin", "fminf", "fminl", "math/fmin", "math/fminf", "math/fminl"] helpviewer_keywords: ["fmin function", "fminf function", "fminl function"] -ms.assetid: 1916dfb5-99c1-4b0d-aefb-513525c3f2ac --- -# fmin, fminf, fminl +# `fmin`, `fminf`, `fminl` Determines the smaller of the two specified values. @@ -42,45 +41,45 @@ long double fminl( long double y ); -#define fmin(x) // Requires C11 or higher +#define fmin(x) // Requires C11 or later ``` ### Parameters -*x*\ +*`x`*\ The first value to compare. -*y*\ +*`y`*\ The second value to compare. -## Return Value +## Return value -If successful, returns the smaller of *x* or *y*. +If successful, returns the smaller of *`x`* or *`y`*. -|Input|Result| -|-----------|------------| -|*x* is NaN|*y*| -|*y* is NaN|*x*| -|*x* and *y* are NaN|NaN| +| Input | Result | +|---|---| +| *`x`* is NaN | *`y`* | +| *`y`* is NaN | *`x`* | +| *`x`* and *`y`* are NaN | NaN | -The function does not cause [_matherr](matherr.md) to be invoked, cause any floating-point exceptions, or change the value of **errno**. +The function doesn't cause [`_matherr`](matherr.md) to be invoked, cause any floating-point exceptions, or change the value of `errno`. ## Remarks -Because C++ allows overloading, you can call overloads of **fmin** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **fmin** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`fmin`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`fmin`** always takes and returns a **`double`**. -If you use the \ `fmin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `fmin()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**fmin**, **fminf**, **fminl**|C: \
C++: \ or \| -|**fmin** macro | \ | +| Routine | Required header | +|---|---| +| **`fmin`**, **`fminf`**, **`fminl`** | C: \
C++: \ or \ | +| **`fmin`** macro | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[fmax, fmaxf, fmaxl](fmax-fmaxf-fmaxl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`fmax`, `fmaxf`, `fmaxl`](fmax-fmaxf-fmaxl.md) diff --git a/docs/c-runtime-library/reference/fmod-fmodf.md b/docs/c-runtime-library/reference/fmod-fmodf.md index 84b764bf3d4..5bd8fd5c8a7 100644 --- a/docs/c-runtime-library/reference/fmod-fmodf.md +++ b/docs/c-runtime-library/reference/fmod-fmodf.md @@ -1,9 +1,9 @@ --- title: "fmod, fmodf, fmodl" description: "API reference for fmod, fmodf, and fmodl; which calculates the floating-point remainder." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["fmod", "fmodf", "fmodl", "_o_fmod", "_o_fmodf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fmod", "_fmodl", "fmodf"] @@ -37,7 +37,7 @@ long double fmodl( long double y ); -#define fmod(X, Y) // Requires C11 or higher +#define fmod(X, Y) // Requires C11 or later ``` ### Parameters @@ -45,7 +45,7 @@ long double fmodl( *`x`*, *`y`*\ Floating-point values. -## Return Value +## Return value **`fmod`** returns the floating-point remainder of `x / y`. If the value of *`y`* is 0.0, **`fmod`** returns a quiet `NaN`. For information about representation of a quiet `NaN` by the **`printf`** family, see [`printf`](printf-printf-l-wprintf-wprintf-l.md). @@ -55,18 +55,18 @@ The **`fmod`** function calculates the floating-point remainder *`f`* of `x / y` C++ allows overloading, so you can call overloads of **`fmod`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`fmod`** always takes two **`double`** arguments and returns a **`double`**. -If you use the `` `fmod()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `fmod` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`fmod`**, **`fmodf`**, **`fmodl`**|``| -|**`fmod`** macro | `` | +| Function | Required header | +|---|---| +| **`fmod`**, **`fmodf`**, **`fmodl`** | `` | +| **`fmod`** macro | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -92,8 +92,8 @@ The remainder of -10.00 / 3.00 is -1.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[`ceil, ceilf, ceill`](ceil-ceilf-ceill.md)\ -[`fabs, fabsf, fabsl`](fabs-fabsf-fabsl.md)\ -[`floor, floorf, floorl`](floor-floorf-floorl.md)\ -[`_CIfmod`](../../c-runtime-library/cifmod.md) +[Math and floating-point support](../floating-point-support.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`fabs`, `fabsf`, `fabsl`](fabs-fabsf-fabsl.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`_CIfmod`](../cifmod.md) diff --git a/docs/c-runtime-library/reference/fopen-s-wfopen-s.md b/docs/c-runtime-library/reference/fopen-s-wfopen-s.md index a0b3f11047c..6964db2b65f 100644 --- a/docs/c-runtime-library/reference/fopen-s-wfopen-s.md +++ b/docs/c-runtime-library/reference/fopen-s-wfopen-s.md @@ -1,9 +1,9 @@ --- 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-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.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: ["STDIO/fopen_s", "CORECRT_WSTDIO/_wfopen_s", "TCHAR/_tfopen_s", "fopen_s", "_wfopen_s", "_tfopen_s"] @@ -11,7 +11,7 @@ helpviewer_keywords: ["_wfopen_s function", "opening files, for file I/O", "_tfo --- # `fopen_s`, `_wfopen_s` -Opens a file. These versions of [`fopen`, `_wfopen`](fopen-wfopen.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Opens a file. These versions of [`fopen`, `_wfopen`](fopen-wfopen.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -31,37 +31,37 @@ errno_t _wfopen_s( ### Parameters *`pFile`*\ -A pointer to the file pointer that will receive the pointer to the opened file. +A pointer to the file pointer that receives the pointer to the opened file. *`filename`*\ -Filename. +The name of the file to open. *`mode`*\ Type of access permitted. ## Return value -Zero if successful; an error code on failure. For more information about these error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Zero if successful; an error code on failure. For more information about these error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ### Error conditions | *`pFile`* | *`filename`* | *`mode`* | Return Value | Contents of *`pFile`* | |--|--|--|--|--| -| **`NULL`** | any | any | **`EINVAL`** | unchanged | -| any | **`NULL`** | any | **`EINVAL`** | unchanged | -| any | any | **`NULL`** | **`EINVAL`** | unchanged | +| `NULL` | any | any | `EINVAL` | unchanged | +| any | `NULL` | any | `EINVAL` | unchanged | +| any | any | `NULL` | `EINVAL` | unchanged | ## Remarks -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`** and **`_wfopen_s`** functions can't open a file for sharing. If you need to share the file, use [`_fsopen` or `_wfsopen`](fsopen-wfsopen.md) with the appropriate sharing mode constant—for example, use `_SH_DENYNO` for read/write sharing. -The **`fopen_s`** function opens the file that's specified by *filename*. **`_wfopen_s`** is a wide-character version of **`fopen_s`**; the arguments to **`_wfopen_s`** are wide-character strings. **`_wfopen_s`** and **`fopen_s`** behave identically otherwise. +The **`fopen_s`** function opens the file specified by *`filename`*. **`_wfopen_s`** is a wide-character version of **`fopen_s`** and the arguments to **`_wfopen_s`** are wide-character strings. **`_wfopen_s`** and **`fopen_s`** behave identically, otherwise. **`fopen_s`** accepts paths that are valid on the file system at the point of execution; UNC paths and paths that involve mapped network drives are accepted by **`fopen_s`** as long as the system that's executing the code has access to the share or mapped network drive at the time of execution. When you construct paths for **`fopen_s`**, don't make assumptions about the availability of drives, paths, or network shares in the execution environment. You can use either forward slashes (/) or backslashes (\\) as the directory separators in a path. -These functions validate their parameters. If *`pFile`*, *`filename`*, or *`mode`* is a null pointer, these functions generate an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +These functions validate their parameters. If *`pFile`*, *`filename`*, or *`mode`* is a null pointer, these functions generate an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). -Always check the return value to see if the function succeeded before you do any further operations on the file. If an error occurs, the error code is returned and the global variable **`errno`** is set. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Always check the return value to see if the function succeeded before you do any further operations on the file. If an error occurs, the error code is returned, and the global variable `errno` is set. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). @@ -71,7 +71,7 @@ By default, this function's global state is scoped to the application. To change **`fopen_s(&fp, "newfile.txt", "w+, ccs=UNICODE");`** -Allowed values of the **`ccs`** flag are **`UNICODE`**, **`UTF-8`**, and **`UTF-16LE`**. If no value is specified for **`ccs`**, **`fopen_s`** uses ANSI encoding. +Allowed values of the **`ccs`** flag are `UNICODE`, **`UTF-8`**, and **`UTF-16LE`**. If no value is specified for **`ccs`**, **`fopen_s`** uses ANSI encoding. If the file already exists and is opened for reading or appending, the byte order mark (BOM), if present in the file, determines the encoding. The BOM encoding takes precedence over the encoding that's specified by the **`ccs`** flag. The **`ccs`** encoding is only used when no BOM is present or if the file is a new file. @@ -84,7 +84,7 @@ The following table summarizes the modes for various **`ccs`** flag values that | `ccs` flag | No BOM (or new file) | BOM: UTF-8 | BOM: UTF-16 | |--|--|--|--| -| **`UNICODE`** | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** | +| `UNICODE` | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** | | **`UTF-8`** | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** | | **`UTF-16LE`** | **`UTF-16LE`** | **`UTF-8`** | **`UTF-16LE`** | @@ -105,36 +105,36 @@ The character string *`mode`* specifies the kind of access that's requested for When a file is opened by using the **`"a"`** or **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but it's always moved back to the end of the file before any write operation is carried out so that existing data can't be overwritten. -The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS `TYPE` command only shows data up to the original EOF marker and not any data that's appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS `TYPE` command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the **CTRL**+**Z** EOF marker. +The **`"a"`** mode doesn't remove the EOF marker before appending to the file. After appending has occurred, the MS-DOS `TYPE` command only shows data up to the original EOF marker and not any data that's appended to the file. The **`"a+"`** mode does remove the EOF marker before appending to the file. After appending, the MS-DOS `TYPE` command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the `CTRL`+**Z** EOF marker. When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are allowed. (The file is said to be open for "update".) However, when you switch from reading to writing, the input operation must come across an EOF marker. If there's no EOF marker, you must use an intervening call to a file-positioning function. The file-positioning functions are **`fsetpos`**, [`fseek`](fseek-fseeki64.md), and [`rewind`](rewind.md). When you switch from writing to reading, you must use an intervening call to either **`fflush`** or to a file-positioning function. Starting in C11, you can append **`"x"`** to **`"w"`** or **`"w+"`** to cause the function fail if the file exists, instead of overwriting it. -In addition to the values above, the following characters can be included in *`mode`* to specify the translation mode for newline characters: +In addition to the previous values, the following characters can be included in *`mode`* to specify the translation mode for newline characters: | *`mode`* modifier | Translation mode | |--|--| -| **`t`** | Open in text (translated) mode. | +| **`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). -If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../../c-runtime-library/fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns **`NULL`**. +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. -For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [Unicode Stream I/O in Text and Binary Modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +For more information about using text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). | *`mode`* modifier | Behavior | |--|--| | **`c`** | Enable the commit flag for the associated *`filename`* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | -| **`n`** | Reset the commit flag for the associated *`filename`* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with *`COMMODE.OBJ`*. The global commit flag default is "no-commit" unless you explicitly link your program with *`COMMODE.OBJ`* (see [Link Options](../../c-runtime-library/link-options.md)). | -| **`n`** | Specifies that the file isn't inherited by child processes. | +| **`n`** | Reset the commit flag for the associated *`filename`* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with *`COMMODE.OBJ`*. The global commit flag default is "no-commit" unless you explicitly link your program with *`COMMODE.OBJ`* (see [Link options](../link-options.md)). | +| **`N`** | Specifies that the file isn't inherited by child processes. | | **`S`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | | **`R`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **`t`** | Specifies a file as temporary. If possible, it isn't flushed to disk. | -| **`D`** | Specifies a file as temporary. It's deleted when the last file pointer is closed. | +| **`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 | @@ -172,7 +178,7 @@ If you're using **`rb`** mode, memory mapped Win32 files might also be an option | **`fopen_s`** | `` | `` | | **`_wfopen_s`** | `` or `` | `` | -For more information on standards conformance and naming conventions in the C runtime library, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information on standards conformance and naming conventions in the C runtime library, see [Compatibility](../compatibility.md). ### Generic-text routine mappings @@ -182,7 +188,7 @@ For more information on standards conformance and naming conventions in the C ru ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -250,7 +256,7 @@ Number of files closed by _fcloseall: 1 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ +[Stream I/O](../stream-i-o.md)\ [`fclose`, `_fcloseall`](fclose-fcloseall.md)\ [`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ [`ferror`](ferror.md)\ diff --git a/docs/c-runtime-library/reference/fopen-wfopen.md b/docs/c-runtime-library/reference/fopen-wfopen.md index e49b592eb6b..22d44f24215 100644 --- a/docs/c-runtime-library/reference/fopen-wfopen.md +++ b/docs/c-runtime-library/reference/fopen-wfopen.md @@ -1,14 +1,13 @@ --- -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-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.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: ["STDIO/fopen", "CORECRT_WSTDIO/_wfopen", "TCHAR/_tfopen", "fopen", "_wfopen", "_tfopen"] helpviewer_keywords: ["opening files, for file I/O", "wfopen function", "tfopen function", "_tfopen function", "_wfopen function", "files [C++], opening", "fopen function"] -ms.assetid: e868993f-738c-4920-b5e4-d8f2f41f933d --- # `fopen`, `_wfopen` @@ -37,17 +36,17 @@ Kind of access that's enabled. ## Return value -Each of these functions returns a pointer to the open file. A null pointer value indicates an error. If *`filename`* or *`mode`* is **`NULL`** or an empty string, these functions trigger the invalid parameter handler, which is described in [Parameter validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`NULL`** and set **`errno`** to **`EINVAL`**. +Each of these functions returns a pointer to the open file. A null pointer value indicates an error. If *`filename`* or *`mode`* is `NULL` or an empty string, these functions trigger the invalid parameter handler, which is described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `NULL` and set `errno` to `EINVAL`. -For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`fopen`** function opens the file that is specified by *filename*. By default, a narrow *filename* string is interpreted using the ANSI codepage (`CP_ACP`). In Windows Desktop applications, 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`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +Always check the return value to see whether the pointer is NULL before you perform any other operations on the file. If an error occurs, the global variable `errno` is set, and may be used to obtain specific error information. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). @@ -57,11 +56,11 @@ By default, this function's global state is scoped to the application. To change `FILE *fp = fopen("newfile.txt", "rt+, ccs=UTF-8");` -Allowed values for **`ccs`** encoding are **`UNICODE`**, **`UTF-8`**, and **`UTF-16LE`**. +Allowed values for **`ccs`** encoding are `UNICODE`, **`UTF-8`**, and **`UTF-16LE`**. -When a file is opened in Unicode mode, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it'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](../../c-runtime-library/parameter-validation.md) error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. +When a file is opened in Unicode mode, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a [parameter validation](../parameter-validation.md) error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. -If the file already exists and is opened for reading or appending, 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). @@ -70,19 +69,19 @@ The following table summarizes the modes that are used for various **`ccs`** fla ### Encodings used based on ccs flag and BOM -| ccs flag | No BOM (or new file) | BOM: UTF-8 | BOM: UTF-16 | +| `ccs` flag | No BOM (or new file) | BOM: UTF-8 | BOM: UTF-16 | |--|--|--|--| -| **`UNICODE`** | **`UTF-16LE`** | *`*UTF-8`** | **`UTF-16LE`** | +| `UNICODE` | **`UTF-16LE`** | **`UTF-8`** | **`UTF-16LE`** | | **`UTF-8`** | **`UTF-8`** | **`UTF-8`** | **`UTF-16LE`** | | **`UTF-16LE`** | **`UTF-16LE`** | **`UTF-8`** | **`UTF-16LE`** | Files opened for writing in Unicode mode have a BOM written to them automatically. -If *`mode`* is **`a, ccs=encoding`** 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 -| TCHAR.H routine | `_UNICODE` & `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | |--|--|--|--| | **`_tfopen`** | **`fopen`** | **`fopen`** | **`_wfopen`** | @@ -99,54 +98,55 @@ The character string *`mode`* specifies the kind of access that is requested for When a file is opened by using the **`"a"`** access type or the **`"a+"`** access type, all write operations occur at the end of the file. The file pointer can be repositioned by using [`fseek`](fseek-fseeki64.md) or [`rewind`](rewind.md), but is always moved back to the end of the file before any write operation is performed. Therefore, existing data can't be overwritten. -The **`"a"`** mode doesn't remove the EOF marker before it appends to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. Before it appends to the file, the **`"a+"`** mode does remove the EOF marker. After appending, the MS-DOS TYPE command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the **CTRL**+**Z** EOF marker. +The **`"a"`** mode doesn't remove the EOF marker before it appends to the file. After appending has occurred, the MS-DOS TYPE command only shows data up to the original EOF marker and not any data appended to the file. Before it appends to the file, the **`"a+"`** mode does remove the EOF marker. After appending, the MS-DOS TYPE command shows all data in the file. The **`"a+"`** mode is required for appending to a stream file that is terminated with the `CTRL`+**Z** EOF marker. When the **`"r+"`**, **`"w+"`**, or **`"a+"`** access type is specified, both reading and writing are enabled (the file is said to be open for "update"). However, when you switch from reading to writing, the input operation must encounter an EOF marker. If there's no EOF, you must use an intervening call to a file positioning function. The file positioning functions are **`fsetpos`**, [`fseek`](fseek-fseeki64.md), and [`rewind`](rewind.md). When you switch from writing to reading, you must use an intervening call to either **`fflush`** or to a file positioning function. -In addition to the earlier values, the following characters can be appended to *mode* to specify the translation mode for newline characters. +In addition to the earlier values, the following characters can be appended to *`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. 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. +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. In text mode, carriage return-line feed (CRLF) combinations are translated into single line feed (LF) characters on input, and LF characters are translated to CRLF combinations on output. When a Unicode stream-I/O function operates in text mode (the default), the source or destination stream is assumed to be a sequence of multibyte characters. Therefore, the Unicode stream-input functions convert multibyte characters to wide characters (as if by a call to the **`mbtowc`** function). For the same reason, the Unicode stream-output functions convert wide characters to multibyte characters (as if by a call to the **`wctomb`** function). -If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../../c-runtime-library/fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns **`NULL`**. +If **`t`** or **`b`** isn't given in *`mode`*, the default translation mode is defined by the global variable [`_fmode`](../fmode.md). If **`t`** or **`b`** is prefixed to the argument, the function fails and returns `NULL`. -For more information about how to use text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [Unicode stream I/O in text and binary modes](../../c-runtime-library/unicode-stream-i-o-in-text-and-binary-modes.md). +For more information about how to use text and binary modes in Unicode and multibyte stream-I/O, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [Unicode stream I/O in text and binary modes](../unicode-stream-i-o-in-text-and-binary-modes.md). The following options can be appended to *`mode`* to specify more behaviors. -| *mode* modifier | Behavior | +| *`mode`* modifier | Behavior | |--|--| -| **`x`** | Forces the function to fail if *filename* already exists. Can only be used with the "w" or "w+" specifiers. | -| **`c`** | Enable the commit flag for the associated *filename* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | -| **`n`** | Reset the commit flag for the associated *filename* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with COMMODE.OBJ. The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ (see [Link Options](../../c-runtime-library/link-options.md)). | +| **`x`** | Forces the function to fail if *`filename`* already exists. Can only be used with the "w" or "w+" specifiers. | +| **`c`** | Enable the commit flag for the associated *`filename`* so that the contents of the file buffer are written directly to disk if either **`fflush`** or **`_flushall`** is called. | +| **`n`** | Reset the commit flag for the associated *`filename`* to "no-commit." This flag is the default. It also overrides the global commit flag if you link your program with COMMODE.OBJ. The global commit flag default is "no-commit" unless you explicitly link your program with COMMODE.OBJ (see [Link options](../link-options.md)). | | **`N`** | Specifies that the file isn't inherited by child processes. | | **`S`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | | **`R`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **`T`** | Specifies a file as temporary. If possible, it isn't flushed to disk. | -| **`D`** | Specifies a file as temporary. It's deleted when the last file pointer is closed. | -| **`ccs=encoding`** | Specifies the encoded character set to use (one of **`UTF-8`**, **`UTF-16LE`**, or **`UNICODE`**) for this file. Leave unspecified if you want ANSI encoding. | +| **`T`** | Specifies a file that isn't written to disk unless memory pressure requires it. | +| **`D`** | Specifies a temporary file that'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. +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. | 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` | @@ -157,6 +157,13 @@ Valid characters for the *mode* string that is used in **`fopen`** and **`_fdope 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 | @@ -164,7 +171,7 @@ If you're using **`rb`** mode, you don't have to port your code, and if you expe | **`fopen`** | `` | | **`_wfopen`** | `` or `` | -**`_wfopen`** is a Microsoft extension. For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_wfopen`** is a Microsoft extension. For more information about compatibility, see [Compatibility](../compatibility.md). The **`c`**, **`n`**, **`t`**, **`S`**, **`R`**, **`T`**, and **`D`** *`mode`* options are Microsoft extensions for **`fopen`** and **`_fdopen`** and shouldn't be used where ANSI portability is desired. @@ -281,8 +288,8 @@ int main(int argc, char** argv) ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ +[Stream I/O](../stream-i-o.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ [`fclose`, `_fcloseall`](fclose-fcloseall.md)\ [`_fdopen`, `_wfdopen`](fdopen-wfdopen.md)\ [`ferror`](ferror.md)\ diff --git a/docs/c-runtime-library/reference/fpclass-fpclassf.md b/docs/c-runtime-library/reference/fpclass-fpclassf.md index 01b12f22ec6..a77c27c1923 100644 --- a/docs/c-runtime-library/reference/fpclass-fpclassf.md +++ b/docs/c-runtime-library/reference/fpclass-fpclassf.md @@ -3,7 +3,7 @@ description: "Learn more about: _fpclass, _fpclassf" title: "_fpclass, _fpclassf" ms.date: "1/15/2021" api_name: ["_fpclass", "_fpclassf", "_o__fpclass", "_o__fpclassf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["fpclass", "_fpclass", "_fpclassf", "math/_fpclass", "float/_fpclass", "math/_fpclassf"] @@ -30,39 +30,39 @@ int _fpclassf( *`x`*\ The floating-point value to test. -## Return Value +## Return value The **`_fpclass`** and **`_fpclassf`** functions return an integer value that indicates the floating-point classification of the argument *`x`*. The classification may have one of the following values, defined in ``. -|Value|Description| -|-----------|-----------------| -|**`_FPCLASS_SNAN`**|Signaling NaN| -|**`_FPCLASS_QNAN`**|Quiet NaN| -|**`_FPCLASS_NINF`**|Negative infinity (`-INF`)| -|**`_FPCLASS_NN`**|Negative normalized non-zero| -|**`_FPCLASS_ND`**|Negative denormalized| -|**`_FPCLASS_NZ`**|Negative zero (-0)| -|**`_FPCLASS_PZ`**|Positive 0 (+0)| -|**`_FPCLASS_PD`**|Positive denormalized| -|**`_FPCLASS_PN`**|Positive normalized non-zero| -|**`_FPCLASS_PINF`**|Positive infinity (`+INF`)| +| Value | Description | +|---|---| +| `_FPCLASS_SNAN` | Signaling NaN | +| `_FPCLASS_QNAN` | Quiet NaN | +| `_FPCLASS_NINF` | Negative infinity (`-INF`) | +| `_FPCLASS_NN` | Negative normalized non-zero | +| `_FPCLASS_ND` | Negative denormalized | +| `_FPCLASS_NZ` | Negative zero (-0) | +| `_FPCLASS_PZ` | Positive 0 (+0) | +| `_FPCLASS_PD` | Positive denormalized | +| `_FPCLASS_PN` | Positive normalized non-zero | +| `_FPCLASS_PINF` | Positive infinity (`+INF`) | ## Remarks -The **`_fpclass`** and **`_fpclassf`** functions are Microsoft-specific. They are similar to [`fpclassify`](fpclassify.md), but return more detailed information about the argument. The **`_fpclassf`** function is only available when compiled for the x64 platform. +The **`_fpclass`** and **`_fpclassf`** functions are Microsoft-specific. They're similar to [`fpclassify`](fpclassify.md), but return more detailed information about the argument. The **`_fpclassf`** function is only available when compiled for the x64 platform. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**`_fpclass`**, **`_fpclassf`**|``| +| Function | Required header | +|---|---| +| **`_fpclass`**, **`_fpclassf`** | `` | -For more compatibility and conformance information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility and conformance information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ [`fpclassify`](fpclassify.md) diff --git a/docs/c-runtime-library/reference/fpclassify.md b/docs/c-runtime-library/reference/fpclassify.md index e046e387ead..94f55eb792b 100644 --- a/docs/c-runtime-library/reference/fpclassify.md +++ b/docs/c-runtime-library/reference/fpclassify.md @@ -9,7 +9,7 @@ f1_keywords: ["fpclassify", "math/fpclassify"] helpviewer_keywords: ["fpclassify macro", "fpclassify function"] ms.assetid: bf549499-7ff9-4a58-8692-f2d1cb6bab81 --- -# fpclassify +# `fpclassify` Returns the floating-point classification of the argument. @@ -35,34 +35,34 @@ int fpclassify( ### Parameters -*x*
+*`x`*\ The floating-point value to test. -## Return Value +## Return value -**fpclassify** returns an integer value that indicates the floating-point class of the argument *x*. This table shows the possible values returned by **fpclassify**, defined in \. +**`fpclassify`** returns an integer value that indicates the floating-point class of the argument *`x`*. This table shows the possible values returned by **`fpclassify`**, defined in \. -|Value|Description| -|-----------|-----------------| -|**FP_NAN**|A quiet, signaling, or indeterminate NaN| -|**FP_INFINITE**|A positive or negative infinity| -|**FP_NORMAL**|A positive or negative normalized non-zero value| -|**FP_SUBNORMAL**|A positive or negative denormalized value| -|**FP_ZERO**|A positive or negative zero value| +| Value | Description | +|---|---| +| `FP_NAN` | A quiet, signaling, or indeterminate NaN | +| `FP_INFINITE` | A positive or negative infinity | +| `FP_NORMAL` | A positive or negative normalized non-zero value | +| `FP_SUBNORMAL` | A positive or negative denormalized value | +| `FP_ZERO` | A positive or negative zero value | ## Remarks -In C, **fpclassify** is a macro; in C++, **fpclassify** is a function overloaded using argument types of **`float`**, **`double`**, or **`long double`**. In either case, the value returned depends on the effective type of the argument expression, and not on any intermediate representation. For example, a normal **`double`** or **`long double`** value can become an infinity, denormal, or zero value when converted to a **`float`**. +In C, **`fpclassify`** is a macro; in C++, **`fpclassify`** is a function overloaded using argument types of **`float`**, **`double`**, or **`long double`**. In either case, the value returned depends on the effective type of the argument expression, and not on any intermediate representation. For example, a normal **`double`** or **`long double`** value can become an infinity, denormal, or zero value when converted to a **`float`**. ## Requirements -|Function/Macro|Required header (C)|Required header (C++)| -|---------------------|---------------------------|-------------------------------| -|**fpclassify**|\|\ or \| +| Function/Macro | Required header (C) | Required header (C++) | +|---|---|---| +| **`fpclassify`** | \ | \ or \ | -The **fpclassify** macro and **fpclassify** functions conform to the ISO C99 and C++11 specifications. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`fpclassify`** macro and **`fpclassify`** functions conform to the ISO C99 and C++11 specifications. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md) diff --git a/docs/c-runtime-library/reference/fpieee-flt.md b/docs/c-runtime-library/reference/fpieee-flt.md index 2eee8eee716..a0c5b419e38 100644 --- a/docs/c-runtime-library/reference/fpieee-flt.md +++ b/docs/c-runtime-library/reference/fpieee-flt.md @@ -10,7 +10,7 @@ f1_keywords: ["fpieee_flt", "_fpieee_flt"] helpviewer_keywords: ["_fpieee_flt function", "exception handling, floating-point", "floating-point exception handling", "fpieee_flt function"] ms.assetid: 2bc4801e-0eed-4e73-b518-215da8cc9740 --- -# _fpieee_flt +# `_fpieee_flt` Invokes a user-defined trap handler for IEEE floating-point exceptions. @@ -26,41 +26,41 @@ int _fpieee_flt( ### Parameters -*excCode*
+*`excCode`*\ Exception code. -*excInfo*
+*`excInfo`*\ Pointer to the Windows NT exception information structure. -*handler*
+*`handler`*\ Pointer to the user's IEEE trap-handler routine. -## Return Value +## Return value -The return value of **_fpieee_flt** is the value returned by *handler*. As such, the IEEE filter routine might be used in the except clause of a structured exception-handling (SEH) mechanism. +The return value of **`_fpieee_flt`** is the value returned by *`handler`*. As such, the IEEE filter routine might be used in the except clause of a structured exception-handling (SEH) mechanism. ## Remarks -The **_fpieee_flt** function invokes a user-defined trap handler for IEEE floating-point exceptions and provides it with all relevant information. This routine serves as an exception filter in the SEH mechanism, which invokes your own IEEE exception handler when necessary. +The **`_fpieee_flt`** function invokes a user-defined trap handler for IEEE floating-point exceptions and provides it with all relevant information. This routine serves as an exception filter in the SEH mechanism, which invokes your own IEEE exception handler when necessary. -The **_FPIEEE_RECORD** structure, defined in Fpieee.h, contains information pertaining to an IEEE floating-point exception. This structure is passed to the user-defined trap handler by **_fpieee_flt**. +The `_FPIEEE_RECORD` structure, defined in Fpieee.h, contains information pertaining to an IEEE floating-point exception. This structure is passed to the user-defined trap handler by **`_fpieee_flt`**. -|_FPIEEE_RECORD field|Description| -|----------------------------|-----------------| -|**RoundingMode**
**Precision**|These **`unsigned int`** fields contain information about the floating-point environment at the time the exception occurred.| -|**Operation**|This **`unsigned int`** field indicates the type of operation that caused the trap. If the type is a comparison (**_FpCodeCompare**), you can supply one of the special **_FPIEEE_COMPARE_RESULT** values (as defined in Fpieee.h) in the **Result.Value** field. The conversion type (**_FpCodeConvert**) indicates that the trap occurred during a floating-point conversion operation. You can look at the **Operand1** and **Result** types to determine the type of conversion being attempted.| -|**Operand1**
**Operand2**
**Result**|These **_FPIEEE_VALUE** structures indicate the types and values of the proposed result and operands. Each structure contains these fields:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

*x* = ±∞

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

*`x`* = ±INF

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

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

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

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

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

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

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

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

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

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

C++: `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -82,6 +82,6 @@ For -14.876543, the fraction is -0.876543 and the integer is -14 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`frexp`](frexp.md)\ [`ldexp`](ldexp.md) diff --git a/docs/c-runtime-library/reference/msize-dbg.md b/docs/c-runtime-library/reference/msize-dbg.md index 2d36d246e45..14b02c921cb 100644 --- a/docs/c-runtime-library/reference/msize-dbg.md +++ b/docs/c-runtime-library/reference/msize-dbg.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _msize_dbg" title: "_msize_dbg" -ms.date: "11/04/2016" +description: "Learn more about: _msize_dbg" +ms.date: 11/04/2016 api_name: ["_msize_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: ["_msize_dbg", "msize_dbg"] helpviewer_keywords: ["memory blocks", "_msize_dbg function", "msize_dbg function"] -ms.assetid: a333f4b6-f8a2-4e61-bb69-cb34063b8cef --- -# _msize_dbg +# `_msize_dbg` Calculates the size of a block of memory in the heap (debug version only). @@ -25,35 +24,35 @@ size_t _msize_dbg( ### Parameters -*userData*
+*`userData`*\ Pointer to the memory block for which to determine the size. -*blockType*
-Type of the specified memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Type of the specified memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -## Return Value +## Return value -On successful completion, **_msize_dbg** returns the size (in bytes) of the specified memory block; otherwise it returns **NULL**. +On successful completion, **`_msize_dbg`** returns the size (in bytes) of the specified memory block; otherwise it returns `NULL`. ## Remarks -**_msize_dbg** is a debug version of the _[msize](msize.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_msize_dbg** is reduced to a call to **_msize**. Both **_msize** and **_msize_dbg** calculate the size of a memory block in the base heap, but **_msize_dbg** adds two debugging features: It includes the buffers on either side of the user portion of the memory block in the returned size and it allows size calculations for specific block types. +**`_msize_dbg`** is a debug version of the [`_msize`](msize.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_msize_dbg`** is reduced to a call to `_msize`. Both `_msize` and **`_msize_dbg`** calculate the size of a memory block in the base heap, but **`_msize_dbg`** adds two debugging features: It includes the buffers on either side of the user portion of the memory block in the returned size and it allows size calculations for specific block types. -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and the debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). -This function validates its parameter. If *memblock* is a null pointer, **_msize** invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **errno** to **EINVAL** and returns -1. +This function validates its parameter. If *`memblock`* is a null pointer, **`_msize_dbg`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1 (18,446,744,073,709,551,615 unsigned). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_msize_dbg**|\| +| Routine | Required header | +|---|---| +| **`_msize_dbg`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example @@ -116,5 +115,5 @@ Size of block after _realloc_dbg of 40 more longs: 320 ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_malloc_dbg](malloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`_malloc_dbg`](malloc-dbg.md) diff --git a/docs/c-runtime-library/reference/msize.md b/docs/c-runtime-library/reference/msize.md index bf93a137f15..b5d1cad10bf 100644 --- a/docs/c-runtime-library/reference/msize.md +++ b/docs/c-runtime-library/reference/msize.md @@ -1,9 +1,9 @@ --- description: "Learn more about: _msize" title: "_msize" -ms.date: "4/2/2020" +ms.date: 07/26/2024 api_name: ["_msize", "_o__msize"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["msize", "_msize"] @@ -26,7 +26,7 @@ size_t _msize( *`memblock`*\ Pointer to the memory block. -## Return Value +## Return value **`_msize`** returns the size (in bytes) as an unsigned integer. @@ -34,23 +34,23 @@ 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](../../c-runtime-library/parameter-validation.md). If the error is handled, the function sets **`errno`** to **`EINVAL`** and returns -1. +This function validates its parameter. If *`memblock`* is a `NULL` pointer, **`_msize`** invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If the error is handled, the function sets `errno` to `EINVAL` and returns -1 (18,446,744,073,709,551,615 unsigned). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_msize`**|``| +| Routine | Required header | +|---|---| +| **`_msize`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -58,7 +58,7 @@ See the example for [`realloc`](realloc.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)\ +[Memory allocation](../memory-allocation.md)\ [`calloc`](calloc.md)\ [`_expand`](expand.md)\ [`malloc`](malloc.md)\ diff --git a/docs/c-runtime-library/reference/nan-nanf-nanl.md b/docs/c-runtime-library/reference/nan-nanf-nanl.md index 39baaf3cb88..a47582fbe36 100644 --- a/docs/c-runtime-library/reference/nan-nanf-nanl.md +++ b/docs/c-runtime-library/reference/nan-nanf-nanl.md @@ -3,14 +3,14 @@ description: "Learn more about: nan, nanf, nanl" title: "nan, nanf, nanl" ms.date: "4/2/2020" api_name: ["nanf", "nan", "nanl", "_o_nan", "_o_nanf", "_o_nanl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["nan", "nanl", "nanf"] helpviewer_keywords: ["nan function", "nanf function", "nanl function"] ms.assetid: 790e9158-80ab-43e0-8f5a-096198553fd9 --- -# nan, nanf, nanl +# `nan`, `nanf`, `nanl` Returns a quiet NaN value. @@ -24,31 +24,31 @@ long double nanl( const char* input ); ### Parameters -*input*
+*`input`*\ A string value. -## Return Value +## Return value -The **nan** functions return a quiet NaN value. +The **`nan`** functions return a quiet NaN value. ## Remarks -The **nan** functions return a floating-point value that corresponds to a quiet (non-signalling) NaN. The *input* value is ignored. For information about how a NaN is represented for output, see [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md). +The **`nan`** functions return a floating-point value that corresponds to a quiet (non-signalling) NaN. The *`input`* value is ignored. For information about how a NaN is represented for output, see [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**nan**, **nanf**, **nanl**|\|\ or \| +| Function | C header | C++ header | +|---|---|---| +| **`nan`**, **`nanf`**, **`nanl`** | \ | \ or \ | ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[fpclassify](fpclassify.md)
-[_fpclass, _fpclassf](fpclass-fpclassf.md)
-[isfinite, _finite, _finitef](finite-finitef.md)
-[isinf](isinf.md)
-[isnan, _isnan, _isnanf](isnan-isnan-isnanf.md)
-[isnormal](isnormal.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`fpclassify`](fpclassify.md)\ +[`_fpclass`, `_fpclassf`](fpclass-fpclassf.md)\ +[`isfinite`, `_finite`, `_finitef`](finite-finitef.md)\ +[`isinf`](isinf.md)\ +[`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md)\ +[`isnormal`](isnormal.md) diff --git a/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md b/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md index d36068eec7b..e94c9df0707 100644 --- a/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md +++ b/docs/c-runtime-library/reference/nearbyint-nearbyintf-nearbyintl1.md @@ -1,16 +1,15 @@ --- title: "nearbyint, nearbyintf, nearbyintl" description: "API reference for nearbyint, nearbyintf, and nearbyintl; which rounds the specified floating-point value to an integer, and returns that value in a floating-point format." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["nearbyint", "nearbyintf", "nearbyintl", "_o_nearbyint", "_o_nearbyintf", "_o_nearbyintl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["nearbyint", "nearbyintf", "nearbyintl", "math/nearbyint", "math/narbyintf", "math/narbyintl"] helpviewer_keywords: ["nearbyint function", "nearbyintf function", "nearbyintl function"] -ms.assetid: dd39cb68-96b0-434b-820f-6ff2ea65584f --- -# nearbyint, nearbyintf, nearbyintl +# `nearbyint`, `nearbyintf`, `nearbyintl` Rounds the specified floating-point value to an integer, and returns that value in a floating-point format. @@ -20,7 +19,7 @@ Rounds the specified floating-point value to an integer, and returns that value double nearbyint( double x ); float nearbyintf( float x ); long double nearbyintl( long double x ); -#define nearbyint( X ) // Requires C11 or higher +#define nearbyint( X ) // Requires C11 or later float nearbyint( float x ); //C++ only long double nearbyint( long double x ); //C++ only @@ -28,43 +27,43 @@ long double nearbyint( long double x ); //C++ only ### Parameters -*x*\ +*`x`*\ The value to round. -## Return Value +## Return value -If successful, returns *x*, rounded to the nearest integer, using the current rounding format as reported by [fegetround](fegetround-fesetround2.md). Otherwise, the function may return one of the following values: +If successful, returns *`x`*, rounded to the nearest integer, using the current rounding format as reported by [`fegetround`](fegetround-fesetround2.md). Otherwise, the function may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = ±INFINITY|±INFINITY, unmodified| -|*x* = ±0|±0, unmodified| -|*x* = NaN|NaN| +| Issue | Return | +|---|---| +| *`x`* = ±INFINITY | ±INFINITY, unmodified | +| *`x`* = ±0 | ±0, unmodified | +| *`x`* = NaN | NaN | -Errors are not reported through [_matherr](matherr.md); specifically, this function does not report any **FE_INEXACT** exceptions. +Errors aren't reported through [`_matherr`](matherr.md); specifically, this function doesn't report any `FE_INEXACT` exceptions. ## Remarks -The primary difference between this function and [rint](rint-rintf-rintl.md) is that this function does not raise the inexact floating point exception. +The primary difference between this function and [`rint`](rint-rintf-rintl.md) is that this function doesn't raise the inexact floating point exception. Because the maximum floating-point values are exact integers, this function will never overflow by itself; rather, the output may overflow the return value, depending on which version of the function you use. -C++ allows overloading, so you can call overloads of **nearbyint** that take and return **`float`** or **`long double`** parameters. In a C program, unless you're using the \ macro to call this function, **nearbyint** always takes two double values and returns a double value. +C++ allows overloading, so you can call overloads of **`nearbyint`** that take and return **`float`** or **`long double`** parameters. In a C program, unless you're using the \ macro to call this function, **`nearbyint`** always takes two double values and returns a double value. -If you use the \ `nearbyint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `nearbyint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**nearbyint**, **nearbyintf**, **nearbyintl**|\|\ or \| -|**nearbyint** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`nearbyint`**, **`nearbyintf`**, **`nearbyintl`** | \ | \ or \ | +| **`nearbyint`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[Math and floating-point support](../floating-point-support.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[Math and floating-point support](../floating-point-support.md) diff --git a/docs/c-runtime-library/reference/nextafter-functions.md b/docs/c-runtime-library/reference/nextafter-functions.md index b02d6828a2e..1e4d8da31d0 100644 --- a/docs/c-runtime-library/reference/nextafter-functions.md +++ b/docs/c-runtime-library/reference/nextafter-functions.md @@ -1,9 +1,9 @@ --- title: "nextafter, nextafterf, nextafterl, _nextafter, _nextafterf, nexttoward, nexttowardf, nexttowardl" description: "API reference for nextafter, nextafterf, nextafterl, _nextafter, _nextafterf, nexttoward, nexttowardf, and nexttowardl; which return the next representable floating-point value." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["nextafterf", "_nextafterf", "nextafter", "nextafterl", "_nextafter", "nexttoward", "nexttowardf", "nexttowardl", "_o__nextafter", "_o_nextafter", "_o_nextafterf", "_o_nextafterl", "_o_nexttoward", "_o_nexttowardf", "_o_nexttowardl", "_o__nextafterf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["nextafter", "_nextafter", "nextafterf", "nextafterl", "_nextafterf", "math/nextafter", "math/nextafterf", "math/nextafterl", "nexttoward", "nexttowardf", "nexttowardl", "math/nexttoward", "math/nexttowardf", "math/nexttowardl"] @@ -23,13 +23,13 @@ long double nextafterl( long double x, long double y ); double _nextafter( double x, double y ); float _nextafterf( float x, float y ); /* x64 only */ -#define nextafter(X, Y) // Requires C11 or higher +#define nextafter(X, Y) // Requires C11 or later double nexttoward( double x, long double y ); float nexttowardf( float x, long double y ); long double nexttowardl( long double x, long double y ); -#define nexttoward(X, Y) // Requires C11 or higher +#define nexttoward(X, Y) // Requires C11 or later float nextafter( float x, float y ); /* C++ only, requires */ long double nextafter( long double x, long double y ); /* C++ only, requires */ @@ -46,9 +46,9 @@ The floating-point value to start from. *`y`*\ The floating-point value to go towards. -## Return Value +## Return value -Returns the next representable floating-point value of the return type after *`x`* in the direction of *`y`*. If *`x`* and *`y`* are equal, the function returns *`y`*, converted to the return type, with no exception triggered. If *`x`* is not equal to *`y`*, and the result is a denormal or zero, the **`FE_UNDERFLOW`** and **`FE_INEXACT`** floating-point exception states are set, and the correct result is returned. If either *`x`* or *`y`* is a NAN, then the return value is one of the input NANs. If *`x`* is finite and the result is infinite or not representable in the type, a correctly signed infinity or NAN is returned, the **`FE_OVERFLOW`** and **`FE_INEXACT`** floating-point exception states are set, and **`errno`** is set to **`ERANGE`**. +Returns the next representable floating-point value of the return type after *`x`* in the direction of *`y`*. If *`x`* and *`y`* are equal, the function returns *`y`*, converted to the return type, with no exception triggered. If *`x`* isn't equal to *`y`*, and the result is a denormal or zero, the `FE_UNDERFLOW` and `FE_INEXACT` floating-point exception states are set, and the correct result is returned. If either *`x`* or *`y`* is a NAN, then the return value is one of the input NANs. If *`x`* is finite and the result is infinite or not representable in the type, a correctly signed infinity or NAN is returned, the `FE_OVERFLOW` and `FE_INEXACT` floating-point exception states are set, and `errno` is set to `ERANGE`. ## Remarks @@ -56,23 +56,23 @@ The **`nextafter`** and **`nexttoward`** function families are equivalent, excep Because C++ allows overloading, if you include `` you can call overloads of **`nextafter`** and **`nexttoward`** that return **`float`** and **`long double`** types. In a C program, unless you're using the `` macro to call this function, **`nextafter`** and **`nexttoward`** always return **`double`**. -If you use the `` `nextafter()` or `nexttoward()`macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `nextafter` or `nexttoward` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -The **_nextafter** and **_nextafterf** functions are Microsoft-specific. The **_nextafterf** function is only available when compiling for x64. +The **`_nextafter`** and **`_nextafterf`** functions are Microsoft-specific. The **`_nextafterf`** function is only available when compiling for x64. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------------|-------------------------------| -|**`nextafter`**, **`nextafterf`**, **`nextafterl`**, **`_nextafterf`**, **`nexttoward`**, **`nexttowardf`**, **`nexttowardl`**|``|`` or ``| -|**`_nextafter`**|``|`` or ``| -|**`nextafter`** macro, **`nexttoward`** macro| `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`nextafter`**, **`nextafterf`**, **`nextafterl`**, **`_nextafterf`**, **`nexttoward`**, **`nexttowardf`**, **`nexttowardl`** | `` | `` or `` | +| **`_nextafter`** | `` | `` or `` | +| **`nextafter`** macro, **`nexttoward`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`isnan`, `_isnan`, `_isnanf`](isnan-isnan-isnanf.md) diff --git a/docs/c-runtime-library/reference/norm-normf-norml1.md b/docs/c-runtime-library/reference/norm-normf-norml1.md index e86dff978cf..5115c675abe 100644 --- a/docs/c-runtime-library/reference/norm-normf-norml1.md +++ b/docs/c-runtime-library/reference/norm-normf-norml1.md @@ -10,7 +10,7 @@ f1_keywords: ["norm", "normf", "norml", "complex/norm", "complex/normf", "comple helpviewer_keywords: ["norm function", "normf function", "norml function"] ms.assetid: 9786ecfe-0019-4553-b378-0af6c691e15c --- -# norm, normf, norml +# `norm`, `normf`, `norml` Retrieves the squared magnitude of a complex number. @@ -29,31 +29,31 @@ long double norm( _Lcomplex z ); // C++ only ### Parameters -*z*
+*`z`*\ A complex number. -## Return Value +## Return value -The squared magnitude of *z*. +The squared magnitude of *`z`*. ## Remarks -Because C++ allows overloading, you can call overloads of **norm** that take **_Fcomplex** or **_Lcomplex** values, and return **`float`** or **`long double`** values. In a C program, **norm** always takes a **_Dcomplex** value and returns a **`double`** value. +Because C++ allows overloading, you can call overloads of **`norm`** that take `_Fcomplex` or `_Lcomplex` values, and return **`float`** or **`long double`** values. In a C program, **`norm`** always takes a `_Dcomplex` value and returns a **`double`** value. ## Requirements -|Routine|C header|C++ header| -|-------------|--------------|------------------| -|**norm**, **normf**, **norml**|\|\| +| Routine | C header | C++ header | +|---|---|---| +| **`norm`**, **`normf`**, **`norml`** | \ | \ | -The **_Fcomplex**, **_Dcomplex**, and **_Lcomplex** types are Microsoft-specific equivalents of the unimplemented native C99 types **float _Complex**, **double _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The `_Fcomplex`, `_Dcomplex`, and `_Lcomplex` types are Microsoft-specific equivalents of the unimplemented native C99 types **float _Complex**, **double _Complex**, and **long double _Complex**, respectively. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[creal, crealf, creall](creal-crealf-creall.md)
-[cproj, cprojf, cprojl](cproj-cprojf-cprojl.md)
-[conj, conjf, conjl](conj-conjf-conjl.md)
-[cimag, cimagf, cimagl](cimag-cimagf-cimagl.md)
-[carg, cargf, cargl](carg-cargf-cargl.md)
-[cabs, cabsf, cabsl](cabs-cabsf-cabsl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`creal`, `crealf`, `creall`](creal-crealf-creall.md)\ +[`cproj`, `cprojf`, `cprojl`](cproj-cprojf-cprojl.md)\ +[`conj`, `conjf`, `conjl`](conj-conjf-conjl.md)\ +[`cimag`, `cimagf`, `cimagl`](cimag-cimagf-cimagl.md)\ +[`carg`, `cargf`, `cargl`](carg-cargf-cargl.md)\ +[`cabs`, `cabsf`, `cabsl`](cabs-cabsf-cabsl.md) diff --git a/docs/c-runtime-library/reference/not-eq.md b/docs/c-runtime-library/reference/not-eq.md index 99a9fae2141..90877cd219c 100644 --- a/docs/c-runtime-library/reference/not-eq.md +++ b/docs/c-runtime-library/reference/not-eq.md @@ -1,55 +1,59 @@ --- description: "Learn more about: not_eq" title: "not_eq" -ms.date: "11/04/2016" +ms.date: 08/09/2024 api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["not_eq", "std::not_eq", "std.not_eq"] +f1_keywords: ["ISO646/not_eq", "not_eq", "std::not_eq", "std.not_eq"] helpviewer_keywords: ["not_eq function"] -ms.assetid: d87ad299-8b50-4393-a57f-06f70e1f23fb --- -# not_eq +# `not_eq` -An alternative to the != operator. +An alternative spelling for the **`!=`** operator. ## Syntax ```C - #define not_eq != ``` ## Remarks -The macro yields the operator !=. +C++: +- **`not_eq`** can be used as alternative to **`!=`**. The [`/permissive-`](../../build/reference/permissive-standards-conformance.md) or [`/Za`](../../build/reference/za-ze-disable-language-extensions.md) compiler option is required. +- Including `` or `` is deprecated. You can use the alternative spelling without including any header files. +- There's no alternative spelling for **`==`**. + +C: +- **`not_eq`** is an alternative spelling for **`!=`**. It is provided as a macro in ``, which you must `#include`. +- There's no alternative spelling for **`==`**. ## Example ```cpp -// iso646_not_eq.cpp // compile with: /EHsc #include #include int main( ) { - using namespace std; - int a = 0, b = 1; - - if (a != b) - cout << "a is not equal to b" << endl; - - if (a not_eq b) - cout << "a is not equal to b" << endl; + int x = 1, y = 2; + + // not_eq is available in C++ and C + // This example is for C++, so no header file is needed to use not_eq + // When compiling for C, #include to use not_eq + if (x not_eq y) + { + std::cout << "Not equal\n"; + } } ``` ```Output -a is not equal to b -a is not equal to b +Not equal ``` ## Requirements -**Header:** \ +**Header:** `` is necessary if you are compiling for C. \ No newline at end of file diff --git a/docs/c-runtime-library/reference/not.md b/docs/c-runtime-library/reference/not.md index 19dfab113a9..a878828337e 100644 --- a/docs/c-runtime-library/reference/not.md +++ b/docs/c-runtime-library/reference/not.md @@ -1,28 +1,26 @@ --- -description: "Learn more about: not" title: "not" +description: "Learn more about: not" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::not", "std.not", "Not"] +f1_keywords: ["std::not", "std.not", "ISO646/not", "not"] helpviewer_keywords: ["not function"] -ms.assetid: d2ddbd5c-33c0-4aff-8961-feac155b4ba1 --- -# not +# `not` -An alternative to the ! operator. +An alternative to the **`!`** operator. ## Syntax ```C - #define not ! ``` ## Remarks -The macro yields the operator !. +The macro yields the operator **`!`**. ## Example diff --git a/docs/c-runtime-library/reference/offsetof-macro.md b/docs/c-runtime-library/reference/offsetof-macro.md index 7ebcc5cd60a..1d200208d64 100644 --- a/docs/c-runtime-library/reference/offsetof-macro.md +++ b/docs/c-runtime-library/reference/offsetof-macro.md @@ -9,7 +9,7 @@ f1_keywords: ["offsetof"] helpviewer_keywords: ["structure members, offset", "offsetof macro"] ms.assetid: f3b4eb16-a882-4d38-afc9-eebd976a7352 --- -# offsetof Macro +# `offsetof` Macro Retrieves the offset of a member from the beginning of its parent structure. @@ -24,35 +24,35 @@ size_t offsetof( ### Parameters -*structName*
+*`structName`*\ Name of the parent data structure. -*memberName*
+*`memberName`*\ Name of the member in the parent data structure for which to determine the offset. -## Return Value +## Return value -**offsetof** returns the offset in bytes of the specified member from the beginning of its parent data structure. It is undefined for bit fields. +**`offsetof`** returns the offset in bytes of the specified member from the beginning of its parent data structure. It's undefined for bit fields. ## Remarks -The **offsetof** macro returns the offset in bytes of *memberName* from the beginning of the structure specified by *structName* as a value of type **size_t**. You can specify types with the **`struct`** keyword. +The **`offsetof`** macro returns the offset in bytes of *`memberName`* from the beginning of the structure specified by *`structName`* as a value of type `size_t`. You can specify types with the **`struct`** keyword. > [!NOTE] -> **offsetof** is not a function and cannot be described using a C prototype. +> **`offsetof`** is not a function and cannot be described using a C prototype. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**offsetof**|\| +| Routine | Required header | +|---|---| +| **`offsetof`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
+[Memory allocation](../memory-allocation.md) diff --git a/docs/c-runtime-library/reference/onexit-onexit-m.md b/docs/c-runtime-library/reference/onexit-onexit-m.md index fcbfd85e5b1..304be260d3c 100644 --- a/docs/c-runtime-library/reference/onexit-onexit-m.md +++ b/docs/c-runtime-library/reference/onexit-onexit-m.md @@ -10,7 +10,7 @@ f1_keywords: ["_onexit", "onexit_m", "onexit", "_onexit_m"] helpviewer_keywords: ["onexit function", "registry, registering exit routines", "_onexit_m function", "onexit_m function", "_onexit function", "registering exit routines", "registering to be called on exit"] ms.assetid: 45743298-0e2f-46cf-966d-1ca44babb443 --- -# _onexit, _onexit_m +# `_onexit`, `_onexit_m` Registers a routine to be called at exit time. @@ -27,28 +27,28 @@ _onexit_t_m _onexit_m( ### Parameters -*function*
+*`function`*\ Pointer to a function to be called at exit. -## Return Value +## Return value -**_onexit** returns a pointer to the function if successful or **NULL** if there is no space to store the function pointer. +**`_onexit`** returns a pointer to the function if successful or `NULL` if there's no space to store the function pointer. ## Remarks -The **_onexit** function is passed the address of a function (*function*) to be called when the program terminates normally. Successive calls to **_onexit** create a register of functions that are executed in LIFO (last-in-first-out) order. The functions passed to **_onexit** cannot take parameters. +The **`_onexit`** function is passed the address of a function (*`function`*) to be called when the program terminates normally. Successive calls to **`_onexit`** create a register of functions that are executed in LIFO (last-in-first-out) order. The functions passed to **`_onexit`** can't take parameters. -In the case when **_onexit** is called from within a DLL, routines registered with **_onexit** run on a DLL's unloading after **DllMain** is called with DLL_PROCESS_DETACH. +In the case when **`_onexit`** is called from within a DLL, routines registered with **`_onexit`** run when the DLL is unloaded, after `DllMain` is called with `DLL_PROCESS_DETACH`. -**_onexit** is a Microsoft extension. For ANSI portability, use [atexit](atexit.md). The **_onexit_m** version of the function is for mixed mode use. +**`_onexit`** is a Microsoft extension. For ANSI portability, use [`atexit`](atexit.md). The **`_onexit_m`** version of the function is for mixed mode use. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_onexit**|\| +| Routine | Required header | +|---|---| +| **`_onexit`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -104,7 +104,7 @@ This is executed next. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[atexit](atexit.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[__dllonexit](../../c-runtime-library/dllonexit.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`atexit`](atexit.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`__dllonexit`](../dllonexit.md) diff --git a/docs/c-runtime-library/reference/open-osfhandle.md b/docs/c-runtime-library/reference/open-osfhandle.md index 07ed8706d70..6ea534a28cd 100644 --- a/docs/c-runtime-library/reference/open-osfhandle.md +++ b/docs/c-runtime-library/reference/open-osfhandle.md @@ -3,7 +3,7 @@ description: "Learn more about: _open_osfhandle" title: "_open_osfhandle" ms.date: "4/2/2020" api_name: ["_open_osfhandle", "_o__open_osfhandle"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_open_osfhandle", "open_osfhandle"] @@ -30,36 +30,36 @@ Operating system file handle. *`flags`*\ Types of operations allowed. -## Return Value +## Return value If successful, **`_open_osfhandle`** returns a C run-time file descriptor. Otherwise, it returns -1. ## Remarks -The **`_open_osfhandle`** function allocates a C run-time file descriptor. It associates this file descriptor with the operating system file handle specified by *`osfhandle`*. To avoid a compiler warning, cast the *`osfhandle`* argument from **`HANDLE`** to **`intptr_t`**. The *`flags`* argument is an integer expression formed from one or more of the manifest constants defined in ``. You can use the bitwise "or" (`|`) operator to combine two or more manifest constants to form the *`flags`* argument. +The **`_open_osfhandle`** function allocates a C run-time file descriptor. It associates this file descriptor with the operating system file handle specified by *`osfhandle`*. To avoid a compiler warning, cast the *`osfhandle`* argument from `HANDLE` to **`intptr_t`**. The *`flags`* argument is an integer expression formed from one or more of the manifest constants defined in ``. You can use the bitwise "or" (`|`) operator to combine two or more manifest constants to form the *`flags`* argument. These manifest constants are defined in ``: | Constant | Description | |--|--| -| **`_O_APPEND`** | Positions a file pointer to the end of the file before every write operation. | -| **`_O_RDONLY`** | Opens the file for reading only. | -| **`_O_TEXT`** | Opens the file in text (translated) mode. | -| **`_O_WTEXT`** | Opens the file in Unicode (translated UTF-16) mode. | +| `_O_APPEND` | Positions a file pointer to the end of the file before every write operation. | +| `_O_RDONLY` | Opens the file for reading only. | +| `_O_TEXT` | Opens the file in ANSI text (translated) mode. | +| `_O_WTEXT` | Opens the file in Unicode (translated UTF-16) mode. | -The **`_open_osfhandle`** call transfers ownership of the Win32 file handle to the file descriptor. To close a file opened by using **`_open_osfhandle`**, call [`_close`](close.md). The underlying OS file handle is also closed by a call to **`_close`**. Don't call the Win32 function **`CloseHandle`** on the original handle. If the file descriptor is owned by a `FILE *` stream, then a call to [`fclose`](fclose-fcloseall.md) closes both the file descriptor and the underlying handle. In this case, don't call **`_close`** on the file descriptor or **`CloseHandle`** on the original handle. +The **`_open_osfhandle`** call transfers ownership of the Win32 file handle to the file descriptor. To close a file opened by using **`_open_osfhandle`**, call [`_close`](close.md). The underlying OS file handle is also closed by a call to **`_close`**. Don't call the Win32 function `CloseHandle` on the original handle. If the file descriptor is owned by a `FILE *` stream, then a call to [`fclose`](fclose-fcloseall.md) closes both the file descriptor and the underlying handle. In this case, don't call **`_close`** on the file descriptor or `CloseHandle` on the original handle. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_open_osfhandle`**|``| +| Routine | Required header | +|---|---| +| **`_open_osfhandle`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)\ +[File handling](../file-handling.md)\ [`_get_osfhandle`](get-osfhandle.md) diff --git a/docs/c-runtime-library/reference/open-wopen.md b/docs/c-runtime-library/reference/open-wopen.md index 6b82727fa77..13237079cad 100644 --- a/docs/c-runtime-library/reference/open-wopen.md +++ b/docs/c-runtime-library/reference/open-wopen.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _open, _wopen" title: "_open, _wopen" +description: "Learn more about: _open, _wopen" ms.date: 05/18/2022 api_name: ["_open", "_wopen"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] @@ -8,7 +8,6 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CORECRT_IO/_open", "CORECRT_WIO/_wopen", "TCHAR/_topen", "_open", "_wopen", "_topen"] helpviewer_keywords: ["opening files, for file I/O", "topen function", "_open function", "_topen function", "_wopen function", "files [C++], opening", "wopen function", "open function"] -ms.assetid: 13f6a0c3-d1aa-450d-a7aa-74abc91b163e --- # `_open`, `_wopen` @@ -42,17 +41,17 @@ Permission mode. ## Return value -Each of these functions returns a file descriptor for the opened file. A return value of -1 indicates an error; in that case **`errno`** is set to one of the following values. +Each of these functions returns a file descriptor for the opened file. A return value of -1 indicates an error; in that case `errno` is set to one of the following values. | `errno` value | Condition | |--|--| -| **`EACCES`** | Tried to open a read-only file for writing, file's sharing mode doesn't allow the specified operations, or the given path is a directory. | -| **`EEXIST`** | **`_O_CREAT`** and **`_O_EXCL`** flags specified, but *`filename`* already exists. | -| **`EINVAL`** | Invalid *`oflag`* or *`pmode`* argument. | -| **`EMFILE`** | No more file descriptors are available (too many files are open). | -| **`ENOENT`** | File or path not found. | +| `EACCES` | Tried to open a read-only file for writing, file's sharing mode doesn't allow the specified operations, or the given path is a directory. | +| `EEXIST` | `_O_CREAT` and `_O_EXCL` flags specified, but *`filename`* already exists. | +| `EINVAL` | Invalid *`oflag`* or *`pmode`* argument. | +| `EMFILE` | No more file descriptors are available (too many files are open). | +| `ENOENT` | File or path not found. | -For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -68,45 +67,45 @@ The **`_open`** function opens the file specified by *`filename`* and prepares i | *`oflag`* constant | Behavior | |--|--| -| **`_O_APPEND`** | Moves the file pointer to the end of the file before every write operation. | -| **`_O_BINARY`** | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) | -| **`_O_CREAT`** | Creates a file and opens it for writing. Has no effect if the file specified by *`filename`* exists. The *`pmode`* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT | _O_SHORT_LIVED`** | Creates a file as temporary and if possible doesn't flush to disk. The *`pmode`* argument is required when **`_O_CREAT`** is specified. | -| **`_O_CREAT | _O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when **`_O_CREAT`** is specified. To preserve legacy behavior for app-compatibility, other processes aren't prevented from deleting this file. | -| **`_O_CREAT | _O_EXCL`** | Returns an error value if a file specified by *`filename`* exists. Applies only when used with **`_O_CREAT`**. | -| **`_O_NOINHERIT`** | Prevents creation of a shared file descriptor. | -| **`_O_RANDOM`** | Specifies that caching is optimized for, but not restricted to, random access from disk. | -| **`_O_RDONLY`** | Opens a file for reading only. Can't be specified with **`_O_RDWR`** or **`_O_WRONLY`**. | -| **`_O_RDWR`** | Opens a file for both reading and writing. Can't be specified with **`_O_RDONLY`** or **`_O_WRONLY`**. | -| **`_O_SEQUENTIAL`** | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | -| **`_O_TEXT`** | Opens a file in text (translated) mode. (For more information, see [Text and binary mode file I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md) and [`fopen`](fopen-wfopen.md).) | -| **`_O_TRUNC`** | Opens a file and truncates it to zero length; the file must have write permission. Can't be specified with **`_O_RDONLY`**. **`_O_TRUNC`** used with **`_O_CREAT`** opens an existing file or creates a file. **Note:** The **`_O_TRUNC`** flag destroys the contents of the specified file. | -| **`_O_WRONLY`** | Opens a file for writing only. Can't be specified with **`_O_RDONLY`** or **`_O_RDWR`**. | -| **`_O_U16TEXT`** | Opens a file in Unicode UTF-16 mode. | -| **`_O_U8TEXT`** | Opens a file in Unicode UTF-8 mode. | -| **`_O_WTEXT`** | Opens a file in Unicode mode. | +| `_O_APPEND` | Moves the file pointer to the end of the file before every write operation. | +| `_O_BINARY` | Opens the file in binary (untranslated) mode. (See [`fopen`](fopen-wfopen.md) for a description of binary mode.) | +| `_O_CREAT` | Creates a file and opens it for writing. Has no effect if the file specified by *`filename`* exists. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_SHORT_LIVED`** | Creates a file as temporary and if possible doesn't flush to disk. The *`pmode`* argument is required when `_O_CREAT` is specified. | +| **`_O_CREAT | _O_TEMPORARY`** | Creates a file as temporary; the file is deleted when the last file descriptor is closed. The *`pmode`* argument is required when `_O_CREAT` is specified. To preserve legacy behavior for app-compatibility, other processes aren't prevented from deleting this file. | +| **`_O_CREAT | _O_EXCL`** | Returns an error value if a file specified by *`filename`* exists. Applies only when used with `_O_CREAT`. | +| `_O_NOINHERIT` | Prevents creation of a shared file descriptor. | +| `_O_RANDOM` | Specifies that caching is optimized for, but not restricted to, random access from disk. | +| `_O_RDONLY` | Opens a file for reading only. Can't be specified with `_O_RDWR` or `_O_WRONLY`. | +| `_O_RDWR` | Opens a file for both reading and writing. Can't be specified with `_O_RDONLY` or `_O_WRONLY`. | +| `_O_SEQUENTIAL` | Specifies that caching is optimized for, but not restricted to, sequential access from disk. | +| `_O_TEXT` | Opens a file in ANSI text (translated) mode. For more information, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) and [`fopen`](fopen-wfopen.md). | +| `_O_TRUNC` | Opens a file and truncates it to zero length; the file must have write permission. Can't be specified with `_O_RDONLY`. `_O_TRUNC` used with `_O_CREAT` opens an existing file or creates a file. **Note:** The `_O_TRUNC` flag destroys the contents of the specified file. | +| `_O_WRONLY` | Opens a file for writing only. Can't be specified with `_O_RDONLY` or `_O_RDWR`. | +| `_O_U16TEXT` | Opens a file in Unicode UTF-16 mode. | +| `_O_U8TEXT` | Opens a file in Unicode UTF-8 mode. | +| `_O_WTEXT` | Opens a file in Unicode mode. | -To specify the file access mode, you must specify either **`_O_RDONLY`**, **`_O_RDWR`**, or **`_O_WRONLY`**. There's no default value for the access mode. +To specify the file access mode, you must specify either `_O_RDONLY`, `_O_RDWR`, or `_O_WRONLY`. There's no default value for the access mode. -If **`_O_WTEXT`** is used to open a file for reading, **`_open`** reads the beginning of the file and checks for a byte order mark (BOM). If there's a BOM, the file is treated as UTF-8 or UTF-16LE, depending on the BOM. If no BOM is present, the file is treated as ANSI. When a file is opened for writing by using **`_O_WTEXT`**, UTF-16 is used. Regardless of any previous setting or byte order mark, if **`_O_U8TEXT`** is used, the file is always opened as UTF-8; if **`_O_U16TEXT`** is used, the file is always opened as UTF-16. +If `_O_WTEXT` is used to open a file for reading, **`_open`** reads the beginning of the file and checks for a byte order mark (BOM). If there's a BOM, the file is treated as UTF-8 or UTF-16LE, depending on the BOM. If no BOM is present, the file is treated as ANSI. When a file is opened for writing by using `_O_WTEXT`, UTF-16 is used. Regardless of any previous setting or byte order mark, if `_O_U8TEXT` is used, the file is always opened as UTF-8; if `_O_U16TEXT` is used, the file is always opened as UTF-16. -When a file is opened in Unicode mode by using **`_O_WTEXT`**, **`_O_U8TEXT`**, or **`_O_U16TEXT`**, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. +When a file is opened in Unicode mode by using `_O_WTEXT`, `_O_U8TEXT`, or `_O_U16TEXT`, input functions translate the data that's read from the file into UTF-16 data stored as type **`wchar_t`**. Functions that write to a file opened in Unicode mode expect buffers that contain UTF-16 data stored as type **`wchar_t`**. If the file is encoded as UTF-8, then UTF-16 data is translated into UTF-8 when it's written. The file's UTF-8-encoded content is translated into UTF-16 when it's read. An attempt to read or write an odd number of bytes in Unicode mode causes a parameter validation error. To read or write data that's stored in your program as UTF-8, use a text or binary file mode instead of a Unicode mode. You're responsible for any required encoding translation. -If **`_open`** is called with **`_O_WRONLY | _O_APPEND`** (append mode) and **`_O_WTEXT`**, **`_O_U16TEXT`**, or **`_O_U8TEXT`**, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. +If **`_open`** is called with **`_O_WRONLY | _O_APPEND`** (append mode) and `_O_WTEXT`, `_O_U16TEXT`, or `_O_U8TEXT`, it first tries to open the file for reading and writing, read the BOM, then reopen it for writing only. If opening the file for reading and writing fails, it opens the file for writing only and uses the default value for the Unicode mode setting. -When two or more manifest constants are used to form the *`oflag`* argument, the constants are combined with the bitwise-OR operator ( **`|`** ). For a discussion of binary and text modes, see [Text and binary mode file I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md). +When two or more manifest constants are used to form the *`oflag`* argument, the constants are combined with the bitwise-OR operator ( **`|`** ). For a discussion of binary and text modes, see [Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md). -The *`pmode`* argument is required only when **`_O_CREAT`** is specified. If the file already exists, *`pmode`* is ignored. Otherwise, *`pmode`* specifies the file permission settings, which are set when the new file is closed the first time. **`_open`** applies the current file-permission mask to *`pmode`* before the permissions are set. (For more information, see [`_umask`](umask.md).) *`pmode`* is an integer expression that contains one or both of the following manifest constants, which are defined in ``. +The *`pmode`* argument is required only when `_O_CREAT` is specified. If the file already exists, *`pmode`* is ignored. Otherwise, *`pmode`* specifies the file permission settings, which are set when the new file is closed the first time. **`_open`** applies the current file-permission mask to *`pmode`* before the permissions are set. For more information, see [`_umask`](umask.md). *`pmode`* is an integer expression that contains one or both of the following manifest constants, which are defined in ``. | *`pmode`* | Meaning | |--|--| -| **`_S_IREAD`** | Only reading permitted. | -| **`_S_IWRITE`** | Writing permitted. (In effect, permits reading and writing.) | +| `_S_IREAD` | Only reading permitted. | +| `_S_IWRITE` | Writing permitted. (In effect, permits reading and writing.) | | **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). In Windows, all files are readable; write-only permission isn't available. Therefore, the modes **`_S_IWRITE`** and **`_S_IREAD`** | **`_S_IWRITE`** are equivalent. +When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). In Windows, all files are readable; write-only permission isn't available. Therefore, the modes `_S_IWRITE` and `_S_IREAD` | `_S_IWRITE` are equivalent. -If a value other than some combination of **`_S_IREAD`** and **`_S_IWRITE`** is specified for *`pmode`*—even if it would specify a valid *`pmode`* in another operating system—or if any value other than the allowed *`oflag`* values is specified, the function generates an assertion in Debug mode and invokes the invalid parameter handler, as described in [Parameter validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **`errno`** to **`EINVAL`**. +If a value other than some combination of `_S_IREAD` and `_S_IWRITE` is specified for *`pmode`*—even if it would specify a valid *`pmode`* in another operating system—or if any value other than the allowed *`oflag`* values is specified, the function generates an assertion in Debug mode and invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. ## Requirements @@ -115,11 +114,11 @@ If a value other than some combination of **`_S_IREAD`** and **`_S_IWRITE`** is | **`_open`** | `` | ``, ``, `` | | **`_wopen`** | `` or `` | ``, ``, `` | -**`_open`** and **`_wopen`** are Microsoft extensions. For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`_open`** and **`_wopen`** are Microsoft extensions. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -172,7 +171,7 @@ Open succeeded on output file ## See also -[Low-level I/O](../../c-runtime-library/low-level-i-o.md)\ +[Low-level I/O](../low-level-i-o.md)\ [`_chmod`, `_wchmod`](chmod-wchmod.md)\ [`_close`](close.md)\ [`_creat`, `_wcreat`](creat-wcreat.md)\ diff --git a/docs/c-runtime-library/reference/open.md b/docs/c-runtime-library/reference/open.md index d1f53a77b74..26fa2bd93f2 100644 --- a/docs/c-runtime-library/reference/open.md +++ b/docs/c-runtime-library/reference/open.md @@ -10,8 +10,8 @@ f1_keywords: ["open"] helpviewer_keywords: ["open function"] ms.assetid: e3139118-4da2-434b-a551-fcf3fccf49b5 --- -# open +# `open` -The Microsoft-implemented POSIX function name `open` is a deprecated alias for the [_open](open-wopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `open` is a deprecated alias for the [`_open`](open-wopen.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_open](open-wopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_open`](open-wopen.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/or-eq.md b/docs/c-runtime-library/reference/or-eq.md index 7f01e8717f1..86d34f9fb7c 100644 --- a/docs/c-runtime-library/reference/or-eq.md +++ b/docs/c-runtime-library/reference/or-eq.md @@ -1,22 +1,20 @@ --- -description: "Learn more about: or_eq" title: "or_eq" +description: "Learn more about: or_eq" ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::or_eq", "or_eq", "std.or_eq"] +f1_keywords: ["std::or_eq", "ISO646/or_eq", "or_eq", "std.or_eq"] helpviewer_keywords: ["or_eq function"] -ms.assetid: 1eb92464-ed58-40d8-a30e-f0a6aa2f4318 --- -# or_eq +# `or_eq` An alternative to the `|=` operator. ## Syntax ```C - #define or_eq |= ``` diff --git a/docs/c-runtime-library/reference/or.md b/docs/c-runtime-library/reference/or.md index 2e12abe4ac4..43c77e35ed0 100644 --- a/docs/c-runtime-library/reference/or.md +++ b/docs/c-runtime-library/reference/or.md @@ -5,24 +5,23 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::or", "std.or", "Or"] +f1_keywords: ["std::or", "std.or", "ISO646/or", "or"] helpviewer_keywords: ["or function"] ms.assetid: 6523b3ac-0a18-44ec-9e9a-b9bab8525ead --- -# or +# `or` -An alternative to the `||` operator. +An alternative to the **`||`** operator. ## Syntax ```C - #define or || ``` ## Remarks -The macro yields the operator `||`. +The macro yields the operator **`||`**. ## Example diff --git a/docs/c-runtime-library/reference/pclose.md b/docs/c-runtime-library/reference/pclose.md index 088c5b80c35..55e048e73b2 100644 --- a/docs/c-runtime-library/reference/pclose.md +++ b/docs/c-runtime-library/reference/pclose.md @@ -3,14 +3,14 @@ description: "Learn more about: _pclose" title: "_pclose" ms.date: "4/2/2020" api_name: ["_pclose", "_o__pclose"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_pclose", "pclose"] helpviewer_keywords: ["_pclose function", "pclose function", "pipes, closing"] ms.assetid: e2e31a9e-ba3a-4124-bcbb-c4040110b3d3 --- -# _pclose +# `_pclose` Waits for a new command processor and closes the stream on the associated pipe. @@ -27,35 +27,35 @@ FILE *stream ### Parameters -*stream*
-Return value from the previous call to **_popen**. +*`stream`*\ +Return value from the previous call to `_popen`. -## Return Value +## Return value -Returns the exit status of the terminating command processor, or -1 if an error occurs. The format of the return value is the same as that for **_cwait**, except the low-order and high-order bytes are swapped. If stream is **NULL**, **_pclose** sets **errno** to **EINVAL** and returns -1. +Returns the exit status of the terminating command processor, or -1 if an error occurs. The format of the return value is the same as for `_cwait`, except the low-order and high-order bytes are swapped. If stream is `NULL`, **`_pclose`** sets `errno` to `EINVAL` and returns -1. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_pclose** function looks up the process ID of the command processor (Cmd.exe) started by the associated **_popen** call, executes a [_cwait](cwait.md) call on the new command processor, and closes the stream on the associated pipe. +The **`_pclose`** function looks up the process ID of the command processor (Cmd.exe) started by the associated `_popen` call, executes a [`_cwait`](cwait.md) call on the new command processor, and closes the stream on the associated pipe. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_pclose**|\| +| Routine | Required header | +|---|---| +| **`_pclose`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[_pipe](pipe.md)
-[_popen, _wpopen](popen-wpopen.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_pipe`](pipe.md)\ +[`_popen`, `_wpopen`](popen-wpopen.md) diff --git a/docs/c-runtime-library/reference/perror-wperror.md b/docs/c-runtime-library/reference/perror-wperror.md index d89b6de519c..f7e0a8f4d01 100644 --- a/docs/c-runtime-library/reference/perror-wperror.md +++ b/docs/c-runtime-library/reference/perror-wperror.md @@ -3,14 +3,14 @@ description: "Learn more about: perror, _wperror" title: "perror, _wperror" ms.date: "4/2/2020" api_name: ["_wperror", "perror", "_o__wperror"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wperror", "_tperror", "perror"] helpviewer_keywords: ["_tperror function", "tperror function", "wperror function", "error messages, printing", "printing error messages", "_wperror function", "perror function"] ms.assetid: 34fce792-16fd-4673-9849-cd88b54b6cd5 --- -# perror, _wperror +# `perror`, `_wperror` Print an error message. @@ -27,41 +27,41 @@ void _wperror( ### Parameters -*message*
+*`message`*\ String message to print. ## Remarks -The **perror** function prints an error message to **stderr**. **_wperror** is a wide-character version of **_perror**; the *message* argument to **_wperror** is a wide-character string. **_wperror** and **_perror** behave identically otherwise. +The **`perror`** function prints an error message to `stderr`. **`_wperror`** is a wide-character version of **`_perror`**; the *`message`* argument to **`_wperror`** is a wide-character string. **`_wperror`** and **`_perror`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tperror**|**perror**|**perror**|**_wperror**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tperror` | **`perror`** | **`perror`** | **`_wperror`** | -*message* is printed first, followed by a colon, then by the system error message for the last library call that produced the error, and finally by a newline character. If *message* is a null pointer or a pointer to a null string, **perror** prints only the system error message. +*`message`* is printed first, followed by a colon, then by the system error message for the last library call that produced the error, and finally by a newline character. If *`message`* is a null pointer or a pointer to a null string, **`perror`** prints only the system error message. -The error number is stored in the variable [errno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) (defined in ERRNO.H). The system error messages are accessed through the variable [_sys_errlist](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **perror** prints the appropriate error message using the **errno** value as an index to **_sys_errlist**. The value of the variable [_sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the **_sys_errlist** array. +The error number is stored in the variable [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md) (defined in ERRNO.H). The system error messages are accessed through the variable [`_sys_errlist`](../errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **`perror`** prints the appropriate error message using the `errno` value as an index to **`_sys_errlist`**. The value of the variable [`_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the **`_sys_errlist`** array. -For accurate results, call **perror** immediately after a library routine returns with an error. Otherwise, subsequent calls can overwrite the **errno** value. +For accurate results, call **`perror`** immediately after a library routine returns an error. Otherwise, subsequent calls can overwrite the `errno` value. -In the Windows operating system, some **errno** values listed in ERRNO.H are unused. These values are reserved for use by the UNIX operating system. See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for a listing of **errno** values used by the Windows operating system. **perror** prints an empty string for any **errno** value not used by these platforms. +In the Windows operating system, some `errno` values listed in ERRNO.H are unused. These values are reserved for use by the UNIX operating system. See [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) for a listing of `errno` values used by the Windows operating system. **`perror`** prints an empty string for any `errno` value not used by these platforms. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**perror**|\ or \| -|**_wperror**|\ or \| +| Routine | Required header | +|---|---| +| **`perror`** | \ or \ | +| **`_wperror`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -113,7 +113,7 @@ _strerror says open failed: No such file or directory ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[clearerr](clearerr.md)
-[ferror](ferror.md)
-[strerror, _strerror, _wcserror, \__wcserror](strerror-strerror-wcserror-wcserror.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`clearerr`](clearerr.md)\ +[`ferror`](ferror.md)\ +[`strerror`, `_strerror`, `_wcserror`, `__wcserror`](strerror-strerror-wcserror-wcserror.md) diff --git a/docs/c-runtime-library/reference/pipe.md b/docs/c-runtime-library/reference/pipe.md index 5022bb43e25..084b7d46665 100644 --- a/docs/c-runtime-library/reference/pipe.md +++ b/docs/c-runtime-library/reference/pipe.md @@ -3,7 +3,7 @@ description: "Learn more about: _pipe" title: "_pipe" ms.date: "4/2/2020" api_name: ["_pipe", "_o__pipe"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["pipe", "_pipe"] @@ -37,53 +37,53 @@ Amount of memory to reserve. *`textmode`*\ File mode. -## Return Value +## Return value -Returns 0 if successful. Returns -1 to indicate an error. On error, **`errno`** is set to one of these values: +Returns 0 if successful. Returns -1 to indicate an error. On error, `errno` is set to one of these values: -- **`EMFILE`**, which indicates that no more file descriptors are available. +- `EMFILE`, which indicates that no more file descriptors are available. -- **`ENFILE`**, which indicates a system-file-table overflow. +- `ENFILE`, which indicates a system-file-table overflow. -- **`EINVAL`**, which indicates that either the array *`pfds`* is a null pointer or that an invalid value for *`textmode`* was passed in. +- `EINVAL`, which indicates that either the array *`pfds`* is a null pointer or that an invalid value for *`textmode`* was passed in. -For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`_pipe`** function creates a *pipe*, which is an artificial I/O channel that a program uses to pass information to other programs. A pipe resembles a file because it has a file pointer, a file descriptor, or both, and it can be read from or written to by using the Standard Library input and output functions. However, a pipe doesn't represent a specific file or device. Instead, it represents temporary storage in memory that is independent of the program's own memory and is controlled entirely by the operating system. +The **`_pipe`** function creates a *pipe*, which is an artificial I/O channel that a program uses to pass information to other programs. A pipe resembles a file, because it has a file pointer, a file descriptor, or both. And, it can be read from or written to by using the Standard Library input and output functions. However, a pipe doesn't represent a specific file or device. Instead, it represents temporary storage in memory that is independent of the program's own memory and is controlled entirely by the operating system. **`_pipe`** resembles **`_open`** but opens the pipe for reading and writing and returns two file descriptors instead of one. The program can use both sides of the pipe or close the one that it doesn't need. For example, the command processor in Windows creates a pipe when it executes a command such as **`PROGRAM1 | PROGRAM2`**. -The standard output descriptor of **`PROGRAM1`** is attached to the pipe's write descriptor. The standard input descriptor of **`PROGRAM2`** is attached to the pipe's read descriptor. This eliminates the need to create temporary files to pass information to other programs. +The standard output descriptor of `PROGRAM1` is attached to the pipe's write descriptor. The standard input descriptor of `PROGRAM2` is attached to the pipe's read descriptor. This attachment eliminates the need to create temporary files to pass information to other programs. The **`_pipe`** function returns two file descriptors to the pipe in the *`pfds`* argument. The element *`pfds`*[0] contains the read descriptor, and the element *`pfds`*[1] contains the write descriptor. Pipe file descriptors are used in the same way as other file descriptors. (The low-level input and output functions **`_read`** and **`_write`** can read from and write to a pipe.) To detect the end-of-pipe condition, check for a **`_read`** request that returns 0 as the number of bytes read. -The *`psize`* argument specifies the amount of memory, in bytes, to reserve for the pipe. The *`textmode`* argument specifies the translation mode for the pipe. The manifest constant **`_O_TEXT`** specifies a text translation, and the constant **`_O_BINARY`** specifies binary translation. (See [`fopen`, `_wfopen`](fopen-wfopen.md) for a description of text and binary modes.) If the *`textmode`* argument is 0, **`_pipe`** uses the default translation mode that's specified by the default-mode variable [`_fmode`](../../c-runtime-library/fmode.md). +The *`psize`* argument specifies the amount of memory, in bytes, to reserve for the pipe. The *`textmode`* argument specifies the translation mode for the pipe. The manifest constant `_O_TEXT` specifies an ANSI text translation, and the constant `_O_BINARY` specifies binary translation. (See [`fopen`, `_wfopen`](fopen-wfopen.md) for a description of text and binary modes.) If the *`textmode`* argument is 0, **`_pipe`** uses the default translation mode that's specified by the default-mode variable [`_fmode`](../fmode.md). In multithreaded programs, no locking is performed. The file descriptors that are returned are newly opened and shouldn't be referenced by any thread until after the **`_pipe`** call is complete. -To use the **`_pipe`** function to communicate between a parent process and a child process, each process must have only one descriptor open on the pipe. The descriptors must be opposites: if the parent has a read descriptor open, then the child must have a write descriptor open. The easiest way to do this is to bitwise "or" (`|`) the **`_O_NOINHERIT`** flag with *`textmode`*. Then, use **`_dup`** or **`_dup2`** to create an inheritable copy of the pipe descriptor that you want to pass to the child. Close the original descriptor, and then spawn the child process. On returning from the spawn call, close the duplicate descriptor in the parent process. For more information, see example 2 later in this article. +To use the **`_pipe`** function to communicate between a parent process and a child process, each process must have only one descriptor open on the pipe. The descriptors must be opposites: if the parent has a read descriptor open, then the child must have a write descriptor open. It's easiest to use a bitwise "or" (**`|`**) on the `_O_NOINHERIT` flag with *`textmode`*. Then, use **`_dup`** or **`_dup2`** to create an inheritable copy of the pipe descriptor that you want to pass to the child. Close the original descriptor, and then spawn the child process. On returning from the spawn call, close the duplicate descriptor in the parent process. For more information, see example 2 later in this article. In the Windows operating system, a pipe is destroyed when all of its descriptors have been closed. (If all read descriptors on the pipe have been closed, then writing to the pipe causes an error.) All read and write operations on the pipe wait until there's enough data or enough buffer space to complete the I/O request. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**`_pipe`**|``|``,1 ``2| +| Routine | Required header | Optional header | +|---|---|---| +| **`_pipe`** | `` | ``,1 ``2 | -1 For **`_O_BINARY`** and **`_O_TEXT`** definitions. +1 For `_O_BINARY` and `_O_TEXT` definitions. -2 **`errno`** definitions. +2 `errno` definitions. -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example 1 @@ -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; @@ -192,7 +191,7 @@ Dad, the square root of 8000 is 89.44. ## Example 2 -This is a basic filter application. It spawns the application `crt_pipe_beeper` after it creates a pipe that directs the spawned application's `stdout` to the filter. The filter removes ASCII 7 (beep) characters. +The sample code is a basic filter application. It spawns the application `crt_pipe_beeper` after it creates a pipe that directs the spawned application's `stdout` to the filter. The filter removes ASCII 7 (beep) characters. ```C // crt_pipe_beeper.c @@ -321,5 +320,5 @@ This is speaker beep number 10... ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`_open`, `_wopen`](open-wopen.md) diff --git a/docs/c-runtime-library/reference/popen-wpopen.md b/docs/c-runtime-library/reference/popen-wpopen.md index f3ae62644d3..251723ea135 100644 --- a/docs/c-runtime-library/reference/popen-wpopen.md +++ b/docs/c-runtime-library/reference/popen-wpopen.md @@ -1,14 +1,13 @@ --- title: "_popen, _wpopen" description: "A reference for the Microsoft C runtime (CRT) library functions _popen and _wpopen." -ms.date: "4/2/2020" +ms.date: "1/25/2023" api_name: ["_popen", "_wpopen", "_o__popen", "_o__wpopen"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["tpopen", "popen", "wpopen", "_popen", "_wpopen", "_tpopen"] helpviewer_keywords: ["tpopen function", "pipes, creating", "_popen function", "_tpopen function", "popen function", "wpopen function", "_wpopen function"] -ms.assetid: eb718ff2-c87d-4bd4-bd2e-ba317c3d6973 no-loc: [_popen, _wpopen, _tpopen, _doserrno, errno, _sys_errlist, _sys_nerr, EINVAL] --- # `_popen`, `_wpopen` @@ -41,51 +40,51 @@ Mode of the returned stream. ## Return value -Returns a stream associated with one end of the created pipe. The other end of the pipe is associated with the spawned command's standard input or standard output. The functions return **`NULL`** on an error. If the error is caused by an invalid parameter, **`errno`** is set to **`EINVAL`**. See the Remarks section for valid modes. +Returns a stream associated with one end of the created pipe. The other end of the pipe is associated with the spawned command's standard input or standard output. The functions return `NULL` on an error. If the error is caused by an invalid parameter, `errno` is set to `EINVAL`. See the Remarks section for valid modes. -For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`_popen`** function creates a pipe. It then asynchronously executes a spawned copy of the command processor, and uses *`command`* as the command line. The character string *`mode`* specifies the type of access requested, as follows. -|Access mode|Description| -|-|-| -|**"r"**|The calling process can read the spawned command's standard output using the returned stream.| -|**"w"**|The calling process can write to the spawned command's standard input using the returned stream.| -|**"b"**|Open in binary mode.| -|**"t"**|Open in text mode.| +| Access mode | Description | +|---|---| +| **"`r`"** | The calling process can read the spawned command's standard output using the returned stream. | +| **"`w`"** | The calling process can write to the spawned command's standard input using the returned stream. | +| **"`b`"** | Open in binary mode. | +| **"`t`"** | Open in text mode. | > [!NOTE] -> If used in a Windows program, the **`_popen`** function returns an invalid file pointer that causes the program to stop responding indefinitely. **`_popen`** works properly in a console application. To create a Windows application that redirects input and output, see [Creating a Child Process with Redirected Input and Output](/windows/win32/ProcThread/creating-a-child-process-with-redirected-input-and-output) in the Windows SDK. +> If used in a Windows program, the **`_popen`** function returns an invalid file pointer that causes the program to stop responding indefinitely. **`_popen`** works properly in a console application. To create a Windows application that redirects input and output, see [Creating a child process with redirected input and output](/windows/win32/ProcThread/creating-a-child-process-with-redirected-input-and-output) in the Windows SDK. -**`_wpopen`** is a wide-character version of **`_popen`**; the *path* argument to **`_wpopen`** is a wide-character string. **`_wpopen`** and **`_popen`** behave identically otherwise. +**`_wpopen`** is a wide-character version of **`_popen`**; the *`path`* argument to **`_wpopen`** is a wide-character string. **`_wpopen`** and **`_popen`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tpopen`**|**`_popen`**|**`_popen`**|**`_wpopen`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tpopen` | **`_popen`** | **`_popen`** | **`_wpopen`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_popen`**|``| -|**`_wpopen`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_popen`** | `` | +| **`_wpopen`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example ```C -// crt_popen.c +// popen.c /* This program uses _popen and _pclose to receive a * stream of text from a system process. */ @@ -93,36 +92,39 @@ All versions of the [C run-time libraries](../../c-runtime-library/crt-library-f #include #include -int main( void ) +int main(void) { - - char psBuffer[128]; - FILE *pPipe; - - /* Run DIR so that it writes its output to a pipe. Open this - * pipe with read text attribute so that we can read it - * like a text file. - */ - - if( (pPipe = _popen( "dir *.c /on /p", "rt" )) == NULL ) - exit( 1 ); - - /* Read pipe until end of file, or an error occurs. */ - - while(fgets(psBuffer, 128, pPipe)) - { - puts(psBuffer); - } - - /* Close pipe and print return value of pPipe. */ - if (feof( pPipe)) - { - printf( "\nProcess returned %d\n", _pclose( pPipe ) ); - } - else - { - printf( "Error: Failed to read the pipe to the end.\n"); - } + char psBuffer[128]; + FILE* pPipe; + + /* Run DIR so that it writes its output to a pipe. Open this + * pipe with read text attribute so that we can read it + * like a text file. + */ + + if ((pPipe = _popen("dir *.c /on /p", "rt")) == NULL) + { + exit(1); + } + + /* Read pipe until end of file, or an error occurs. */ + + while (fgets(psBuffer, 128, pPipe)) + { + puts(psBuffer); + } + + int endOfFileVal = feof(pPipe); + int closeReturnVal = _pclose(pPipe); + + if (endOfFileVal) + { + printf("\nProcess returned %d\n", closeReturnVal); + } + else + { + printf("Error: Failed to read the pipe to the end.\n"); + } } ``` @@ -143,6 +145,6 @@ Process returned 0 ## See also -[Process and environment control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`_pclose`](pclose.md)\ [`_pipe`](pipe.md) diff --git a/docs/c-runtime-library/reference/posix-chsize.md b/docs/c-runtime-library/reference/posix-chsize.md index b71b2b63e97..e956ed5935e 100644 --- a/docs/c-runtime-library/reference/posix-chsize.md +++ b/docs/c-runtime-library/reference/posix-chsize.md @@ -10,8 +10,8 @@ f1_keywords: ["chsize"] helpviewer_keywords: ["chsize function"] ms.assetid: f94d62f6-b539-4cbf-bf99-b81d081b4216 --- -# chsize +# `chsize` -The Microsoft-specific function name `chsize` is a deprecated alias for the [_chsize](chsize.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `chsize` is a deprecated alias for the [`_chsize`](chsize.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_chsize](chsize.md) or the security-enhanced [_chsize_s](chsize-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_chsize`](chsize.md) or the security-enhanced [`_chsize_s`](chsize-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-close.md b/docs/c-runtime-library/reference/posix-close.md index 4ae588f0d40..6252af1673d 100644 --- a/docs/c-runtime-library/reference/posix-close.md +++ b/docs/c-runtime-library/reference/posix-close.md @@ -10,8 +10,8 @@ f1_keywords: ["close"] helpviewer_keywords: ["close function"] ms.assetid: c79689f4-9c86-4a4a-a256-d22e3498f55d --- -# close +# `close` -The Microsoft-implemented POSIX function name `close` is a deprecated alias for the [_close](close.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `close` is a deprecated alias for the [`_close`](close.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_close](close.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_close`](close.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-cwait.md b/docs/c-runtime-library/reference/posix-cwait.md index a075885647f..2fc975f4e70 100644 --- a/docs/c-runtime-library/reference/posix-cwait.md +++ b/docs/c-runtime-library/reference/posix-cwait.md @@ -10,11 +10,11 @@ f1_keywords: ["cwait"] helpviewer_keywords: ["cwait function"] ms.assetid: 1ad1ab19-02e5-4155-94ca-f02c2d5a90a6 --- -# cwait +# `cwait` -The Microsoft-specific function name `cwait` is a deprecated alias for the [_cwait](cwait.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `cwait` is a deprecated alias for the [`_cwait`](cwait.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_cwait](cwait.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_cwait`](cwait.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/posix-dup-dup2.md b/docs/c-runtime-library/reference/posix-dup-dup2.md index 8493deb9953..8ca5d6a2d9f 100644 --- a/docs/c-runtime-library/reference/posix-dup-dup2.md +++ b/docs/c-runtime-library/reference/posix-dup-dup2.md @@ -10,8 +10,8 @@ f1_keywords: ["dup", "dup2"] helpviewer_keywords: ["dup function", "dup2 function"] ms.assetid: c7572170-47ff-4e0d-b9c3-10f0ab0ba40a --- -# dup, dup2 +# `dup`, `dup2` -The Microsoft-implemented POSIX function names `dup` and `dup2` are deprecated aliases for the [_dup](dup-dup2.md) and [_dup2](dup-dup2.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-implemented POSIX function names `dup` and `dup2` are deprecated aliases for the [`_dup`](dup-dup2.md) and [`_dup2`](dup-dup2.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_dup](dup-dup2.md) and [_dup2](dup-dup2.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_dup`](dup-dup2.md) and [`_dup2`](dup-dup2.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-ecvt.md b/docs/c-runtime-library/reference/posix-ecvt.md index 9c02ed49d44..3c059f61b01 100644 --- a/docs/c-runtime-library/reference/posix-ecvt.md +++ b/docs/c-runtime-library/reference/posix-ecvt.md @@ -10,8 +10,8 @@ f1_keywords: ["ecvt"] helpviewer_keywords: ["ecvt function"] ms.assetid: a24fccea-033a-4cc7-b120-4fd0f525a7e3 --- -# ecvt +# `ecvt` -The Microsoft-specific function name `ecvt` is a deprecated alias for the [_ecvt](ecvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `ecvt` is a deprecated alias for the [`_ecvt`](ecvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_ecvt](ecvt.md) or the security-enhanced [_ecvt_s](ecvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_ecvt`](ecvt.md) or the security-enhanced [`_ecvt_s`](ecvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-eof.md b/docs/c-runtime-library/reference/posix-eof.md index e0ff5e79aac..4a089738819 100644 --- a/docs/c-runtime-library/reference/posix-eof.md +++ b/docs/c-runtime-library/reference/posix-eof.md @@ -10,8 +10,8 @@ f1_keywords: ["eof"] helpviewer_keywords: ["eof function"] ms.assetid: 2e8fb55b-b736-46a6-be5e-15f8876a714f --- -# eof +# `eof` -The Microsoft-specific function name `eof` is a deprecated alias for the [_eof](eof.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `eof` is a deprecated alias for the [`_eof`](eof.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_eof](eof.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_eof`](eof.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-fcvt.md b/docs/c-runtime-library/reference/posix-fcvt.md index ecab0f6c043..232bf20f644 100644 --- a/docs/c-runtime-library/reference/posix-fcvt.md +++ b/docs/c-runtime-library/reference/posix-fcvt.md @@ -10,8 +10,8 @@ f1_keywords: ["fcvt"] helpviewer_keywords: ["fcvt function"] ms.assetid: 1f748ad0-e186-400e-af8e-80d4431523d7 --- -# fcvt +# `fcvt` -The Microsoft-specific function name `fcvt` is a deprecated alias for the [_fcvt](fcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `fcvt` is a deprecated alias for the [`_fcvt`](fcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fcvt](fcvt.md) or the security-enhanced [_fcvt_s](fcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fcvt`](fcvt.md) or the security-enhanced [`_fcvt_s`](fcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-fileno.md b/docs/c-runtime-library/reference/posix-fileno.md index 9331d44a2ba..68fcf83d80f 100644 --- a/docs/c-runtime-library/reference/posix-fileno.md +++ b/docs/c-runtime-library/reference/posix-fileno.md @@ -10,8 +10,8 @@ f1_keywords: ["fileno"] helpviewer_keywords: ["fileno function"] ms.assetid: 8f33e1e0-0dc8-4311-b690-ec6e577a64b5 --- -# fileno +# `fileno` -The Microsoft-implemented POSIX function name `fileno` is a deprecated alias for the [_fileno](fileno.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `fileno` is a deprecated alias for the [`_fileno`](fileno.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_fileno](fileno.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_fileno`](fileno.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-flushall.md b/docs/c-runtime-library/reference/posix-flushall.md index b2e53a526bf..c6695ac843f 100644 --- a/docs/c-runtime-library/reference/posix-flushall.md +++ b/docs/c-runtime-library/reference/posix-flushall.md @@ -10,8 +10,8 @@ f1_keywords: ["flushall"] helpviewer_keywords: ["flushall function"] ms.assetid: 481429ae-3980-4233-9495-a3ee56e7c838 --- -# flushall +# `flushall` -The Microsoft-specific function name `flushall` is a deprecated alias for the [_flushall](flushall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `flushall` is a deprecated alias for the [`_flushall`](flushall.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_flushall](flushall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_flushall`](flushall.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-gcvt.md b/docs/c-runtime-library/reference/posix-gcvt.md index f954e02fa6c..c73d36d26f3 100644 --- a/docs/c-runtime-library/reference/posix-gcvt.md +++ b/docs/c-runtime-library/reference/posix-gcvt.md @@ -10,8 +10,8 @@ f1_keywords: ["gcvt"] helpviewer_keywords: ["gcvt function"] ms.assetid: 913478fd-ef22-4dee-b558-ff2bd6d72f3d --- -# gcvt +# `gcvt` -The Microsoft-specific function name `gcvt` is a deprecated alias for the [_gcvt](gcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `gcvt` is a deprecated alias for the [`_gcvt`](gcvt.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_gcvt](gcvt.md) or the security-enhanced [_gcvt_s](gcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_gcvt`](gcvt.md) or the security-enhanced [`_gcvt_s`](gcvt-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-getw.md b/docs/c-runtime-library/reference/posix-getw.md index 1c26fcd4b6f..e2331275365 100644 --- a/docs/c-runtime-library/reference/posix-getw.md +++ b/docs/c-runtime-library/reference/posix-getw.md @@ -10,8 +10,8 @@ f1_keywords: ["getw"] helpviewer_keywords: ["getw function"] ms.assetid: d3c347a4-3ff1-403b-8d02-2dd3b429bb5f --- -# getw +# `getw` -The Microsoft-specific function name `getw` is a deprecated alias for the [_getw](getw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `getw` is a deprecated alias for the [`_getw`](getw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_getw](getw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_getw`](getw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-isatty.md b/docs/c-runtime-library/reference/posix-isatty.md index 73151ae8e7c..4e1f70a71f4 100644 --- a/docs/c-runtime-library/reference/posix-isatty.md +++ b/docs/c-runtime-library/reference/posix-isatty.md @@ -10,8 +10,8 @@ f1_keywords: ["isatty"] helpviewer_keywords: ["isatty function"] ms.assetid: 610d0b09-a1db-41ef-9f45-a2c6076b4683 --- -# isatty +# `isatty` -The Microsoft-implemented POSIX function name `isatty` is a deprecated alias for the [_isatty](isatty.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `isatty` is a deprecated alias for the [`_isatty`](isatty.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_isatty](isatty.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_isatty`](isatty.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-kbhit.md b/docs/c-runtime-library/reference/posix-kbhit.md index 315579e00f2..c502ee65424 100644 --- a/docs/c-runtime-library/reference/posix-kbhit.md +++ b/docs/c-runtime-library/reference/posix-kbhit.md @@ -10,11 +10,11 @@ f1_keywords: ["kbhit"] helpviewer_keywords: ["kbhit function"] ms.assetid: 73f1eed7-b3ef-4887-8ec6-755367de1d7d --- -# kbhit +# `kbhit` -The Microsoft-specific function name `kbhit` is a deprecated alias for the [_kbhit](kbhit.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `kbhit` is a deprecated alias for the [`_kbhit`](kbhit.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_kbhit](kbhit.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_kbhit`](kbhit.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/posix-lfind.md b/docs/c-runtime-library/reference/posix-lfind.md index 52dafe65238..8972ef7872f 100644 --- a/docs/c-runtime-library/reference/posix-lfind.md +++ b/docs/c-runtime-library/reference/posix-lfind.md @@ -10,8 +10,8 @@ f1_keywords: ["lfind"] helpviewer_keywords: ["lfind function"] ms.assetid: 2528e787-94b6-4740-8a8d-6efc276d1f42 --- -# lfind +# `lfind` -The Microsoft-implemented POSIX function name `lfind` is a deprecated alias for the [_lfind](lfind.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `lfind` is a deprecated alias for the [`_lfind`](lfind.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_lfind](lfind.md) or security-enhanced [_lfind_s](lfind-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_lfind`](lfind.md) or security-enhanced [`_lfind_s`](lfind-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-locking.md b/docs/c-runtime-library/reference/posix-locking.md index 3252601bae6..aabcf9346aa 100644 --- a/docs/c-runtime-library/reference/posix-locking.md +++ b/docs/c-runtime-library/reference/posix-locking.md @@ -10,8 +10,8 @@ f1_keywords: ["locking"] helpviewer_keywords: ["locking function"] ms.assetid: 1db15308-543e-44cf-a26f-5539f8e4fb2f --- -# locking +# `locking` -The Microsoft-specific function name `locking` is a deprecated alias for the [_locking](locking.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `locking` is a deprecated alias for the [`_locking`](locking.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_locking](locking.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_locking`](locking.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-lsearch.md b/docs/c-runtime-library/reference/posix-lsearch.md index 3a98aad87f4..ddd2f426a51 100644 --- a/docs/c-runtime-library/reference/posix-lsearch.md +++ b/docs/c-runtime-library/reference/posix-lsearch.md @@ -10,8 +10,8 @@ f1_keywords: ["lsearch"] helpviewer_keywords: ["lsearch function"] ms.assetid: 130da3fc-904a-4375-b0ab-79bfea8a455f --- -# lsearch +# `lsearch` -The Microsoft-implemented POSIX function name `lsearch` is a deprecated alias for the [_lsearch](lsearch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `lsearch` is a deprecated alias for the [`_lsearch`](lsearch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_lsearch](lsearch.md) or security-enhanced [_lsearch_s](lsearch-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_lsearch`](lsearch.md) or security-enhanced [`_lsearch_s`](lsearch-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-memccpy.md b/docs/c-runtime-library/reference/posix-memccpy.md index a94f6bade8d..f72ef7307b3 100644 --- a/docs/c-runtime-library/reference/posix-memccpy.md +++ b/docs/c-runtime-library/reference/posix-memccpy.md @@ -10,8 +10,8 @@ f1_keywords: ["memccpy"] helpviewer_keywords: ["memccpy function"] ms.assetid: e9951812-2b69-43e9-bbee-a0001bce4d80 --- -# memccpy +# `memccpy` -The Microsoft-implemented POSIX function name `memccpy` is a deprecated alias for the [_memccpy](memccpy.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `memccpy` is a deprecated alias for the [`_memccpy`](memccpy.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_memccpy](memccpy.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_memccpy`](memccpy.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-putw.md b/docs/c-runtime-library/reference/posix-putw.md index 8182a13dca2..a270ffda486 100644 --- a/docs/c-runtime-library/reference/posix-putw.md +++ b/docs/c-runtime-library/reference/posix-putw.md @@ -10,8 +10,8 @@ f1_keywords: ["putw"] helpviewer_keywords: ["putw function"] ms.assetid: a004fbb6-7643-4f3f-9ee1-87a23154d49a --- -# putw +# `putw` -The Microsoft-specific function name `putw` is a deprecated alias for the [_putw](putw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `putw` is a deprecated alias for the [`_putw`](putw.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_putw](putw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_putw`](putw.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-read.md b/docs/c-runtime-library/reference/posix-read.md index 46b774c8ae5..d3487d5b9db 100644 --- a/docs/c-runtime-library/reference/posix-read.md +++ b/docs/c-runtime-library/reference/posix-read.md @@ -10,8 +10,8 @@ f1_keywords: ["read"] helpviewer_keywords: ["read function"] ms.assetid: 9e0eead4-d38c-4f65-87f5-f6c12da40ead --- -# read +# `read` -The Microsoft-implemented POSIX function name `read` is a deprecated alias for the [_read](read.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `read` is a deprecated alias for the [`_read`](read.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_read](read.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_read`](read.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-rmtmp.md b/docs/c-runtime-library/reference/posix-rmtmp.md index 801434b958c..845eacdd75b 100644 --- a/docs/c-runtime-library/reference/posix-rmtmp.md +++ b/docs/c-runtime-library/reference/posix-rmtmp.md @@ -10,8 +10,8 @@ f1_keywords: ["rmtmp"] helpviewer_keywords: ["rmtmp function"] ms.assetid: d79f0364-39e8-42fb-a73a-63c22a646cd8 --- -# rmtmp +# `rmtmp` -The Microsoft-specific function name `rmtmp` is a deprecated alias for the [_rmtmp](rmtmp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `rmtmp` is a deprecated alias for the [`_rmtmp`](rmtmp.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_rmtmp](rmtmp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_rmtmp`](rmtmp.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-setmode.md b/docs/c-runtime-library/reference/posix-setmode.md index 6b4d7557482..064dc32a700 100644 --- a/docs/c-runtime-library/reference/posix-setmode.md +++ b/docs/c-runtime-library/reference/posix-setmode.md @@ -10,8 +10,8 @@ f1_keywords: ["setmode"] helpviewer_keywords: ["setmode function"] ms.assetid: cb959d9e-09f3-45af-8943-85f4ca0d3f5a --- -# setmode +# `setmode` -The Microsoft-specific function name `setmode` is a deprecated alias for the [_setmode](setmode.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `setmode` is a deprecated alias for the [`_setmode`](setmode.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_setmode](setmode.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_setmode`](setmode.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-swab.md b/docs/c-runtime-library/reference/posix-swab.md index fd9e0270e9b..26edc6cd635 100644 --- a/docs/c-runtime-library/reference/posix-swab.md +++ b/docs/c-runtime-library/reference/posix-swab.md @@ -10,8 +10,8 @@ f1_keywords: ["swab"] helpviewer_keywords: ["swab function"] ms.assetid: fb8b7137-420d-4485-bb65-e1ec68602905 --- -# swab +# `swab` -The Microsoft-implemented POSIX function name `swab` is a deprecated alias for the [_swab](swab.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `swab` is a deprecated alias for the [`_swab`](swab.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_swab](swab.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_swab`](swab.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-tzset.md b/docs/c-runtime-library/reference/posix-tzset.md index 2508c322e67..8e65277ecad 100644 --- a/docs/c-runtime-library/reference/posix-tzset.md +++ b/docs/c-runtime-library/reference/posix-tzset.md @@ -10,11 +10,11 @@ f1_keywords: ["tzset"] helpviewer_keywords: ["tzset function"] ms.assetid: c3afa5d0-cb15-4163-9181-fafb962c95aa --- -# tzset +# `tzset` -The Microsoft-implemented POSIX function name `tzset` is a deprecated alias for the [_tzset](tzset.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `tzset` is a deprecated alias for the [`_tzset`](tzset.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_tzset](tzset.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_tzset`](tzset.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/posix-umask.md b/docs/c-runtime-library/reference/posix-umask.md index ea9f5322f29..91fa5134cf6 100644 --- a/docs/c-runtime-library/reference/posix-umask.md +++ b/docs/c-runtime-library/reference/posix-umask.md @@ -10,8 +10,8 @@ f1_keywords: ["umask"] helpviewer_keywords: ["umask function"] ms.assetid: d2f697fc-08d5-4b70-9dd5-df3f5bb8b754 --- -# umask +# `umask` -The Microsoft-implemented POSIX function name `umask` is a deprecated alias for the [_umask](umask.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `umask` is a deprecated alias for the [`_umask`](umask.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_umask](umask.md) or security-enhanced [_umask_s](umask-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_umask`](umask.md) or security-enhanced [`_umask_s`](umask-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/posix-write.md b/docs/c-runtime-library/reference/posix-write.md index c6fba512ec7..7c80fce32af 100644 --- a/docs/c-runtime-library/reference/posix-write.md +++ b/docs/c-runtime-library/reference/posix-write.md @@ -6,12 +6,12 @@ api_name: ["write"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["write"] +f1_keywords: ["CORECRT_IO/write", "write"] helpviewer_keywords: ["write function"] ms.assetid: 1cbf112e-b9ef-4df6-993a-83abd4213acd --- -# write +# `write` -The Microsoft-implemented POSIX function name `write` is a deprecated alias for the [_write](write.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `write` is a deprecated alias for the [`_write`](write.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_write](write.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_write`](write.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/pow-powf-powl.md b/docs/c-runtime-library/reference/pow-powf-powl.md index 506a379c7fa..dbc3247460f 100644 --- a/docs/c-runtime-library/reference/pow-powf-powl.md +++ b/docs/c-runtime-library/reference/pow-powf-powl.md @@ -1,14 +1,13 @@ --- title: "pow, powf, powl" -description: "API reference for pow, powf, and powl; which calculate raising to a power." -ms.date: "08/31/2020" +description: "API reference for pow, powf, and powl; which calculate exponents." +ms.date: 08/31/2020 api_name: ["powl", "pow", "powf", "_o_pow", "_o_powf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["powl", "pow", "_powl", "powf"] helpviewer_keywords: ["exponential calculations", "powl function", "_powl function", "exponentiation", "powers, calculating", "calculating exponentials", "powf function", "pow function"] -ms.assetid: e75c33ed-2e59-48b1-be40-81da917324f1 --- # `pow`, `powf`, `powl` @@ -20,7 +19,7 @@ Calculates *`x`* raised to the power of *`y`*. double pow( double x, double y ); float powf( float x, float y ); long double powl( long double x, long double y ); -define pow(X, Y) // Requires C11 or higher +define pow(X, Y) // Requires C11 or later double pow( double x, int y ); // C++ only float pow( float x, float y ); // C++ only @@ -37,40 +36,40 @@ Base. *`y`*\ Exponent. -## Return Value +## Return value Returns the value of *`x`**`y`*. No error message is printed on overflow or underflow. -|Values of x and y|Return value of pow| -|-----------------------|-------------------------| -|*x* != 0.0 and *y* == 0.0|1| -|*x* == 0.0 and *y* == 0.0|1| -|*x* == 0.0 and *y* < 0|INF| +| Values of *`x`* and *`y`* | Return value of **`pow`** | +|---|---| +| *`x`* != 0.0 and *`y`* == 0.0 | 1 | +| *`x`* == 0.0 and *`y`* == 0.0 | 1 | +| *`x`* == 0.0 and *`y`* < 0 | INF | ## Remarks -**`pow`** does not recognize integral floating-point values greater than 264 (for example, 1.0E100). +**`pow`** doesn't recognize integral floating-point values greater than 264 (for example, 1.0E100). **`pow`** has an implementation that uses Streaming SIMD Extensions 2 (SSE2). For information and restrictions about using the SSE2 implementation, see [`_set_SSE2_enable`](set-sse2-enable.md). Because C++ allows overloading, you can call any of the various overloads of **`pow`**. In a C program, unless you're using the `` macro to call this function, **`pow`** always takes two **`double`** values and returns a **`double`** value. -If you use the `` `pow()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `pow` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. The `pow(int, int)` overload is no longer available. If you use this overload, the compiler may emit [C2668](../../error-messages/compiler-errors-2/compiler-error-c2668.md). To avoid this problem, cast the first parameter to **`double`**, **`float`**, or **`long double`**. -Originally, the `pow(T, int)` overloads would unroll the `pow` call into a sequence of inline multiplication operations. While this was faster, it was also significantly less accurate and was removed in Visual Studio 2015 Update 1. For more information, see [Conformance Improvements in Visual Studio 2015 Update 1](../../porting/visual-cpp-what-s-new-2003-through-2015.md). +Originally, the `pow(T, int)` overloads unrolled the `pow` call into a sequence of inline multiplication operations. While it was faster, it was also much less accurate. This implementation was removed in Visual Studio 2015 Update 1. For more information, see [Conformance improvements in Visual Studio 2015 Update 1](../../porting/visual-cpp-what-s-new-2003-through-2015.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-|-|-| -|**`pow`**, **`powf`**, **`powl`**|``|`` or ``| -|**`pow`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`pow`**, **`powf`**, **`powl`** | `` | `` or `` | +| **`pow`** macro | `` | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -95,8 +94,8 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[`exp`, `expf`, `expl`](exp-expf.md)
-[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)
-[`sqrt`, `sqrtf`, `sqrtl`](sqrt-sqrtf-sqrtl.md)
-[`_CIpow`](../../c-runtime-library/cipow.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`exp`, `expf`, `expl`](exp-expf.md)\ +[`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ +[`sqrt`, `sqrtf`, `sqrtl`](sqrt-sqrtf-sqrtl.md)\ +[`_CIpow`](../cipow.md) diff --git a/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md b/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md index a5838e4630c..3d909d93970 100644 --- a/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md +++ b/docs/c-runtime-library/reference/printf-p-printf-p-l-wprintf-p-wprintf-p-l.md @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["wprintf_p", "_wprintf_p", "printf_p_l", "_printf_p", "printf_p", "_wprintf_p_l", "_printf_p_l", "wprintf_p_l"] helpviewer_keywords: ["printf_p function", "printf_p_l function", "wprintf_p function", "wprintf_p_l function", "_tprintf_p_l function", "_wprintf_p function", "_wprintf_p_l function", "_printf_p function", "tprintf_p_l function", "_printf_p_l function"] --- -# _printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l +# `_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l` Prints formatted output to the standard output stream, and enables specification of the order in which parameters are used in the format string. @@ -38,49 +38,49 @@ int _wprintf_p_l( ### Parameters -*format*
+*`format`*\ Format control. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Returns the number of characters printed or a negative value if an error occurs. ## Remarks -The **_printf_p** function formats and prints a series of characters and values to the standard output stream, **stdout**. If arguments follow the *format* string, the *format* string must contain specifications that determine the output format for the arguments (see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)). +The **`_printf_p`** function formats and prints a series of characters and values to the standard output stream, `stdout`. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments (see [printf_p Positional Parameters](../printf-p-positional-parameters.md)). -The difference between **_printf_p** and **printf_s** is that **_printf_p** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +The difference between **`_printf_p`** and `printf_s` is that **`_printf_p`** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -**_wprintf_p** is the wide-character version of **_printf_p**; they behave identically if the stream is opened in ANSI mode. **_printf_p** doesn't currently support output into a UNICODE stream. +**`_wprintf_p`** is the wide-character version of **`_printf_p`**; they behave identically if the stream is opened in ANSI mode. **`_printf_p`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. +> Ensure that *`format`* is not a user-defined string. -If *format* or *argument* are **NULL**, or of the format string contains invalid formatting characters, **_printf_p** and **_wprintf_p** functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **errno** to **EINVAL**. +If *`format`* or *`argument`* are `NULL`, or of the format string contains invalid formatting characters, **`_printf_p`** and **`_wprintf_p`** functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tprintf_p**|**_printf_p**|**_printf_p**|**_wprintf_p**| -|**_tprintf_p_l**|**_printf_p_l**|**_printf_p_l**|**_wprintf_p_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tprintf_p` | **`_printf_p`** | **`_printf_p`** | **`_wprintf_p`** | +| `_tprintf_p_l` | **`_printf_p_l`** | **`_printf_p_l`** | **`_wprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_printf_p**, **_printf_p_l**|\| -|**_wprintf_p**, **_wprintf_p_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_printf_p`**, **`_printf_p_l`** | \ | +| **`_wprintf_p`**, **`_wprintf_p_l`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -117,16 +117,16 @@ Width specifiers: Hello ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[fopen, _wfopen](fopen-wfopen.md)
-[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md b/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md index 821e36650ce..9754b1c51fd 100644 --- a/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md +++ b/docs/c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md @@ -38,26 +38,26 @@ int _wprintf_l( ### Parameters -*`format`*
+*`format`*\ Format control. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of characters printed, or a negative value if an error occurs. If *`format`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **`errno`** to **`EINVAL`**. If **`EOF`** (0xFFFF) is encountered in *`argument`*, the function returns -1. +Returns the number of characters printed, or a negative value if an error occurs. If *`format`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. If `EOF` (0xFFFF) is encountered in *`argument`*, the function returns -1. -For information on **`errno`** and error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on `errno` and error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`printf`** function formats and prints a series of characters and values to the standard output stream, **`stdout`**. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments. **`printf`** and [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md) behave identically except that **`printf`** writes output to **`stdout`** rather than to a destination of type **`FILE`**. +The **`printf`** function formats and prints a series of characters and values to the standard output stream, **`stdout`**. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments. **`printf`** and [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md) behave identically except that **`printf`** writes output to **`stdout`** rather than to a destination of type `FILE`. -**`wprintf`** is a wide-character version of **`printf`**; *`format`* is a wide-character string. **`wprintf`** and **`printf`** behave identically if the stream is opened in ANSI mode. **`printf`** does not currently support output into a UNICODE stream. +**`wprintf`** is a wide-character version of **`printf`**; *`format`* is a wide-character string. **`wprintf`** and **`printf`** behave identically if the stream is opened in ANSI mode. **`printf`** doesn't currently support output into a UNICODE stream. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. @@ -74,26 +74,26 @@ Line one Line two ``` -[Format specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**%**) and are read left to right. When **`printf`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for all the format specifications. +[Format specifications](../format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**%**) and are read left to right. When **`printf`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there aren't enough arguments for all the format specifications. > [!IMPORTANT] > Ensure that *`format`* is not a user-defined string. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tprintf`**|**`printf`**|**`printf`**|**`wprintf`**| -|**`_tprintf_l`**|**`_printf_l`**|**`_printf_l`**|**`_wprintf_l`**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tprintf`** | **`printf`** | **`printf`** | **`wprintf`** | +| **`_tprintf_l`** | **`_printf_l`** | **`_printf_l`** | **`_wprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`printf`**, **`_printf_l`**|``| -|**`wprintf`**, **`_wprintf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`printf`**, **`_printf_l`** | `` | +| **`wprintf`**, **`_wprintf_l`** | `` or `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -157,7 +157,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Integer formats: @@ -186,13 +186,13 @@ Address as: 0012FF3C ## See also -[Format Specification Syntax: `printf` and `wprintf` Functions](../format-specification-syntax-printf-and-wprintf-functions.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
-[`_set_output_format`](../../c-runtime-library/set-output-format.md)
+[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_set_output_format`](../set-output-format.md) diff --git a/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md b/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md index 0b7c70f5b54..be7f7d3340e 100644 --- a/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md +++ b/docs/c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md @@ -11,7 +11,7 @@ helpviewer_keywords: ["wprintf_s function", "tprintf_s function", "_tprintf_s fu --- # `printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l` -Prints formatted output to the standard output stream. These versions of [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Prints formatted output to the standard output stream. These versions of [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -38,16 +38,16 @@ int _wprintf_s_l( ### Parameters -*`format`*
+*`format`*\ Format control. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value Returns the number of characters printed, or a negative value if an error occurs. @@ -55,22 +55,22 @@ Returns the number of characters printed, or a negative value if an error occurs The **`printf_s`** function formats and prints a series of characters and values to the standard output stream, **`stdout`**. If arguments follow the *`format`* string, the *`format`* string must contain specifications that determine the output format for the arguments. -The main difference between **`printf_s`** and **`printf`** is that **`printf_s`** checks the format string for valid formatting characters, whereas **`printf`** only checks if the format string is a null pointer. If either check fails, an invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **`errno`** to **`EINVAL`**. +The main difference between **`printf_s`** and **`printf`** is that **`printf_s`** checks the format string for valid formatting characters, whereas **`printf`** only checks if the format string is a null pointer. If either check fails, an invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EINVAL`. -For information on **`errno`** and error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on `errno` and error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -**`printf_s`** and **`fprintf_s`** behave identically except that **`printf_s`** writes output to **`stdout`** rather than to a destination of type **`FILE`**. For more information, see [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md). +**`printf_s`** and **`fprintf_s`** behave identically except that **`printf_s`** writes output to **`stdout`** rather than to a destination of type `FILE`. For more information, see [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md). **`wprintf_s`** is a wide-character version of **`printf_s`**; *`format`* is a wide-character string. **`wprintf_s`** and **`printf_s`** behave identically if the stream is opened in ANSI mode. **`printf_s`** doesn't currently support output into a UNICODE stream. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tprintf_s`**|**`printf_s`**|**`printf_s`**|**`wprintf_s`**| -|**`_tprintf_s_l`**|**`_printf_s_l`**|**`_printf_s_l`**|**`_wprintf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tprintf_s` | **`printf_s`** | **`printf_s`** | **`wprintf_s`** | +| `_tprintf_s_l` | **`_printf_s_l`** | **`_printf_s_l`** | **`_wprintf_s_l`** | The *`format`* argument consists of ordinary characters, escape sequences, and (if arguments follow *`format`*) format specifications. The ordinary characters and escape sequences are copied to **`stdout`** in order of their appearance. For example, the line @@ -85,24 +85,23 @@ Line one Line two ``` -[Format specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**`%`**) and are read left to right. When **`printf_s`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there are not enough arguments for all the format specifications. +[Format specifications](../format-specification-syntax-printf-and-wprintf-functions.md) always begin with a percent sign (**`%`**) and are read left to right. When **`printf_s`** encounters the first format specification (if any), it converts the value of the first argument after *`format`* and outputs it accordingly. The second format specification causes the second argument to be converted and output, and so on. If there are more arguments than there are format specifications, the extra arguments are ignored. The results are undefined if there aren't enough arguments for all the format specifications. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`printf_s`**, **`_printf_s_l`**|``| -|**`wprintf_s`**, **`_wprintf_s_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`printf_s`**, **`_printf_s_l`** | `` | +| **`wprintf_s`**, **`_wprintf_s_l`** | `` or `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -154,7 +153,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Integer formats: @@ -183,11 +182,11 @@ Address as: 0012FF78 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fopen`, `_wfopen`](fopen-wfopen.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fopen`, `_wfopen`](fopen-wfopen.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/purecall.md b/docs/c-runtime-library/reference/purecall.md index 16a8898a920..b673b89065e 100644 --- a/docs/c-runtime-library/reference/purecall.md +++ b/docs/c-runtime-library/reference/purecall.md @@ -3,14 +3,14 @@ description: "Learn more about: _purecall" title: "_purecall" ms.date: "4/2/2020" api_name: ["_purecall", "_o__purecall"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["purecall", "_purecall"] helpviewer_keywords: ["_purecall function", "purecall function"] ms.assetid: 56135d9b-3403-4e22-822d-e714523801cc --- -# _purecall +# `_purecall` The default pure virtual function call error handler. The compiler generates code to call this function when a pure virtual member function is called. @@ -22,17 +22,17 @@ extern "C" int __cdecl _purecall(); ## Remarks -The **_purecall** function is a Microsoft-specific implementation detail of the Microsoft C++ compiler. This function is not intended to be called by your code directly, and it has no public header declaration. It is documented here because it is a public export of the C Runtime Library. +The **`_purecall`** function is a Microsoft-specific implementation detail of the Microsoft C++ compiler. This function isn't intended to be called by your code directly, and it has no public header declaration. It's documented here because it's a public export of the C Runtime Library. -A call to a pure virtual function is an error because it has no implementation. The compiler generates code to invoke the **_purecall** error handler function when a pure virtual function is called. By default, **_purecall** terminates the program. Before terminating, the **_purecall** function invokes a **_purecall_handler** function if one has been set for the process. You can install your own error handler function for pure virtual function calls, to catch them for debugging or reporting purposes. To use your own error handler, create a function that has the **_purecall_handler** signature, then use [_set_purecall_handler](get-purecall-handler-set-purecall-handler.md) to make it the current handler. +A call to a pure virtual function is an error because it has no implementation. The compiler generates code to invoke the **`_purecall`** error handler function when a pure virtual function is called. By default, **`_purecall`** terminates the program. Before the **`_purecall`** function terminates, it invokes a `_purecall_handler` function, if one has been set for the process. You can install your own error handler function for pure virtual function calls, to catch them for debugging or reporting purposes. To use your own error handler, create a function that has the `_purecall_handler` signature, then use [`_set_purecall_handler`](get-purecall-handler-set-purecall-handler.md) to make it the current handler. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -The **_purecall** function does not have a header declaration. The **_purecall_handler** typedef is defined in \. +The **`_purecall`** function doesn't have a header declaration. The `_purecall_handler` typedef is defined in \. ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_get_purecall_handler, _set_purecall_handler](get-purecall-handler-set-purecall-handler.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_get_purecall_handler`, `_set_purecall_handler`](get-purecall-handler-set-purecall-handler.md) diff --git a/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md b/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md index 1d5d566b01c..6c629ae81fb 100644 --- a/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md +++ b/docs/c-runtime-library/reference/putc-nolock-putwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _putc_nolock, _putwc_nolock" title: "_putc_nolock, _putwc_nolock" +description: "Learn more about: _putc_nolock, _putwc_nolock" ms.date: "4/2/2020" api_name: ["_putc_nolock", "_putwc_nolock", "_o__putc_nolock", "_o__putwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_puttc_nolock", "puttc_nolock", "putwc_nolock", "_putwc_nolock", "_putc_nolock", "putc_nolock"] helpviewer_keywords: ["puttc_nolock function", "putc_nolock function", "_putc_nolock function", "streams, writing characters to", "characters, writing", "putwc_nolock function", "_puttc_nolock function", "_putwc_nolock function"] -ms.assetid: 3cfc7f21-c9e8-4b7f-b0fb-af0d4d85e7e1 --- -# _putc_nolock, _putwc_nolock +# `_putc_nolock`, `_putwc_nolock` -Writes a character to a stream without locking the thread. +Writes a character to a stream without locking. ## Syntax @@ -29,42 +28,42 @@ wint_t _putwc_nolock( ### Parameters -*c*
+*`c`*\ Character to be written. -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value See **putc, putwc**. ## Remarks -**_putc_nolock** and **_putwc_nolock** are identical to the versions without the **_nolock** suffix except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_putc_nolock`** and **`_putwc_nolock`** are identical to the versions without the `_nolock` suffix except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -**_putwc_nolock** is the wide-character version of **_putc_nolock**; the two functions behave identically if the stream is opened in ANSI mode. **_putc_nolock** doesn't currently support output into a UNICODE stream. +**`_putwc_nolock`** is the wide-character version of **`_putc_nolock`**; the two functions behave identically if the stream is opened in ANSI mode. **`_putc_nolock`** doesn't currently support output into a UNICODE stream. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttc_nolock**|**_putc_nolock**|**_putc_nolock**|**_putwc_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttc_nolock` | **`_putc_nolock`** | **`_putc_nolock`** | **`_putwc_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putc_nolock**|\| -|**_putwc_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_putc_nolock`** | \ | +| **`_putwc_nolock`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -99,6 +98,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/putc-putwc.md b/docs/c-runtime-library/reference/putc-putwc.md index c9715a26588..9d4bc87c310 100644 --- a/docs/c-runtime-library/reference/putc-putwc.md +++ b/docs/c-runtime-library/reference/putc-putwc.md @@ -3,14 +3,14 @@ description: "Learn more about: putc, putwc" title: "putc, putwc" ms.date: "4/2/2020" api_name: ["putwc", "putc", "_o_putc", "_o_putwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_puttc", "putwc", "putc"] helpviewer_keywords: ["streams, writing characters to", "characters, writing", "putwc function", "putc function", "_puttc function", "puttc function"] ms.assetid: a37b2e82-9d88-4565-8190-ff8d04c0ddb9 --- -# putc, putwc +# `putc`, `putwc` Writes a character to a stream. @@ -29,44 +29,44 @@ wint_t putwc( ### Parameters -*c*
+*`c`*\ Character to be written. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -Returns the character written. To indicate an error or end-of-file condition, **putc** and **putchar** return **EOF**; **putwc** and **putwchar** return **WEOF**. For all four routines, use [ferror](ferror.md) or [feof](feof.md) to check for an error or end of file. If passed a null pointer for *stream*, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** or **WEOF** and set **errno** to **EINVAL**. +Returns the character written. To indicate an error or end-of-file condition, **`putc`** and `putchar` return `EOF`; **`putwc`** and `putwchar` return `WEOF`. For all four routines, use [`ferror`](ferror.md) or [`feof`](feof.md) to check for an error or end of file. If passed a null pointer for *`stream`*, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` or `WEOF`, and set `errno` to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **putc** routine writes the single character *c* to the output *stream* at the current position. Any integer can be passed to **putc**, but only the lower 8 bits are written. The **putchar** routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. **putc** and **putchar** are similar to **fputc** and **_fputchar**, respectively, but are implemented both as functions and as macros (see [Choosing Between Functions and Macros](../../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md)). **putwc** and **putwchar** are wide-character versions of **putc** and **putchar**, respectively. **putwc** and **putc** behave identically if the stream is opened in ANSI mode. **putc** doesn't currently support output into a UNICODE stream. +The **`putc`** routine writes the single character *`c`* to the output *`stream`* at the current position. Any integer can be passed to **`putc`**, but only the lower 8 bits are written. The `putchar` routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. **`putc`** and `putchar` are similar to `fputc` and `_fputchar`, respectively, but are implemented both as functions and as macros (see [Recommendations for choosing between functions and macros](../recommendations-for-choosing-between-functions-and-macros.md)). **`putwc`** and `putwchar` are wide-character versions of **`putc`** and `putchar`, respectively. **`putwc`** and **`putc`** behave identically if the stream is opened in ANSI mode. **`putc`** doesn't currently support output into a UNICODE stream. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. For more information, see **_putc_nolock, _putwc_nolock**. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. For more information, see **_putc_nolock, _putwc_nolock**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_puttc**|**putc**|**putc**|**putwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttc` | **`putc`** | **`putc`** | **`putwc`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**putc**|\| -|**putwc**|\ or \| +| Routine | Required header | +|---|---| +| **`putc`** | \ | +| **`putwc`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -101,6 +101,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md b/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md index 6eef9c8b1c2..d97eb45b182 100644 --- a/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md +++ b/docs/c-runtime-library/reference/putch-nolock-putwch-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _putch_nolock, _putwch_nolock" title: "_putch_nolock, _putwch_nolock" +description: "Learn more about: _putch_nolock, _putwch_nolock" ms.date: "4/2/2020" api_name: ["_putwch_nolock", "_putch_nolock", "_o__putch_nolock", "_o__putwch_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putch_nolock", "_puttch_nolock", "putch_nolock", "putwch_nolock", "_putwch_nolock"] helpviewer_keywords: ["putwch_nolock function", "puttch_nolock function", "characters, writing", "putch_nolock function", "_putch_nolock function", "_puttch_nolock function", "console, writing characters to", "_putwch_nolock function"] -ms.assetid: edbc811d-bac6-47fa-a872-fe4f3a1590b0 --- -# _putch_nolock, _putwch_nolock +# `_putch_nolock`, `_putwch_nolock` -Writes a character to the console without locking the thread. +Writes a character to the console without locking. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -30,40 +29,40 @@ wchar_t c ### Parameters -*c*
+*`c`*\ Character to be output. -## Return Value +## Return value -Returns *c* if successful. If **_putch_nolock** fails, it returns **EOF**; if **_putwch_nolock** fails, it returns **WEOF**. +Returns *`c`* if successful. If **`_putch_nolock`** fails, it returns `EOF`; if **`_putwch_nolock`** fails, it returns `WEOF`. ## Remarks -**_putch_nolock** and **_putwch_nolock** are identical to **_putch** and **_putwch**, respectively, except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`_putch_nolock`** and **`_putwch_nolock`** are identical to `_putch` and `_putwch`, respectively, except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttch_nolock**|**_putch_nolock**|**_putch_nolock**|**_putwch_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttch_nolock` | **`_putch_nolock`** | **`_putch_nolock`** | **`_putwch_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putch_nolock**|\| -|**_putwch_nolock**|\| +| Routine | Required header | +|---|---| +| **`_putch_nolock`** | \ | +| **`_putwch_nolock`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[_getch, _getwch](getch-getwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`_getch`, `_getwch`](getch-getwch.md) diff --git a/docs/c-runtime-library/reference/putch-putwch.md b/docs/c-runtime-library/reference/putch-putwch.md index 6e73309cfcd..eb94136fbe8 100644 --- a/docs/c-runtime-library/reference/putch-putwch.md +++ b/docs/c-runtime-library/reference/putch-putwch.md @@ -3,14 +3,14 @@ description: "Learn more about: _putch, _putwch" title: "_putch, _putwch" ms.date: "4/2/2020" api_name: ["_putwch", "_putch", "_o__putch", "_o__putwch"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putch", "putwch", "_putwch"] helpviewer_keywords: ["_putch function", "characters, writing", "putwch function", "_putwch function", "putch function", "console, writing characters to"] ms.assetid: 3babc7cf-e333-405d-8449-c788d61d51aa --- -# _putch, _putwch +# `_putch`, `_putwch` Writes a character to the console. @@ -31,46 +31,46 @@ wint_t _putwch( ### Parameters -*c*
+*`c`*\ Character to be output. -## Return Value +## Return value -Returns *c* if successful. If **_putch** fails, it returns **EOF**; if **_putwch** fails, it returns **WEOF**. +Returns *`c`* if successful. If **`_putch`** fails, it returns `EOF`; if **`_putwch`** fails, it returns `WEOF`. ## Remarks -These functions write the character *c* directly, without buffering, to the console. In Windows NT, **_putwch** writes Unicode characters using the current console locale setting. +These functions write the character *`c`* directly, without buffering, to the console. In Windows NT, **`_putwch`** writes Unicode characters using the current console locale setting. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. For more information, see **_putch_nolock**, **_putwch_nolock**. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. For more information, see [`_putch_nolock`, `_putwch_nolock`](./putch-nolock-putwch-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttch**|**_putch**|**_putch**|**_putwch**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttch` | **`_putch`** | **`_putch`** | **`_putwch`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putch**|\| -|**_putwch**|\| +| Routine | Required header | +|---|---| +| **`_putch`** | \ | +| **`_putwch`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example -See the example for [_getch](getch-getwch.md). +See the example for [`_getch`](getch-getwch.md). ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[_getch, _getwch](getch-getwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`_getch`, `_getwch`](getch-getwch.md) diff --git a/docs/c-runtime-library/reference/putch.md b/docs/c-runtime-library/reference/putch.md index 85549a6af15..2edfdc788b0 100644 --- a/docs/c-runtime-library/reference/putch.md +++ b/docs/c-runtime-library/reference/putch.md @@ -10,11 +10,11 @@ f1_keywords: ["putch"] helpviewer_keywords: ["putch function"] ms.assetid: 81e733e5-770e-4c7a-b7e4-8e66da109f92 --- -# putch +# `putch` -The Microsoft-specific function name `putch` is a deprecated alias for the [_putch](putch-putwch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `putch` is a deprecated alias for the [`_putch`](putch-putwch.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_putch](putch-putwch.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_putch`](putch-putwch.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md b/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md index ba566fcb51d..6fe752c3483 100644 --- a/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md +++ b/docs/c-runtime-library/reference/putchar-nolock-putwchar-nolock.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _putchar_nolock, _putwchar_nolock" title: "_putchar_nolock, _putwchar_nolock" +description: "Learn more about: _putchar_nolock, _putwchar_nolock" ms.date: "11/04/2016" api_name: ["_putchar_nolock", "_putwchar_nolock"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,11 +8,10 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["putwchar_nolock", "_puttchar_nolock", "_putchar_nolock", "_putwchar_nolock", "putchar_nolock"] helpviewer_keywords: ["_puttchar_nolock function", "putchar_nolock function", "characters, writing", "standard output, writing to", "putwchar_nolock function", "_putchar_nolock function", "_putwchar_nolock function", "puttchar_nolock function"] -ms.assetid: 9ac68092-bfc3-4352-b486-c3e780220575 --- -# _putchar_nolock, _putwchar_nolock +# `_putchar_nolock`, `_putwchar_nolock` -Writes a character to **stdout** without locking the thread. +Writes a character to `stdout` without locking. ## Syntax @@ -27,35 +26,35 @@ wint_t _putwchar_nolock( ### Parameters -*c*
+*`c`*\ Character to be written. -## Return Value +## Return value See **putchar, putwchar**. ## Remarks -**putchar_nolock** and **_putwchar_nolock** are identical to the versions without the **_nolock** suffix except that they are not protected from interference by other threads. They might be faster because they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +**`putchar_nolock`** and **`_putwchar_nolock`** are identical to the versions without the `_nolock` suffix except that they aren't protected from interference by other threads. They might be faster because they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_puttchar_nolock**|**_putchar_nolock**|**_putchar_nolock**|**_putwchar_nolock**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttchar_nolock` | **`_putchar_nolock`** | **`_putchar_nolock`** | **`_putwchar_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putchar_nolock**|\| -|**_putwchar_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_putchar_nolock`** | \ | +| **`_putwchar_nolock`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -89,6 +88,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[fgetc, fgetwc](fgetc-fgetwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`fgetc`, `fgetwc`](fgetc-fgetwc.md) diff --git a/docs/c-runtime-library/reference/putchar-putwchar.md b/docs/c-runtime-library/reference/putchar-putwchar.md index 378d4d73311..19f13eeb18f 100644 --- a/docs/c-runtime-library/reference/putchar-putwchar.md +++ b/docs/c-runtime-library/reference/putchar-putwchar.md @@ -3,16 +3,16 @@ description: "Learn more about: putchar, putwchar" title: "putchar, putwchar" ms.date: "4/2/2020" api_name: ["putchar", "putwchar", "_o_putchar", "_o_putwchar"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["putchar", "putwchar", "_puttchar"] helpviewer_keywords: ["putchar function", "_puttchar function", "characters, writing", "standard output, writing to", "putwchar function"] ms.assetid: 93657c7f-cca1-4032-8e3a-cd6ab6193748 --- -# putchar, putwchar +# `putchar`, `putwchar` -Writes a character to **stdout**. +Writes a character to `stdout`. ## Syntax @@ -27,41 +27,41 @@ wint_t putwchar( ### Parameters -*c*
+*`c`*\ Character to be written. -## Return Value +## Return value -Returns the character written. To indicate an error or end-of-file condition, **putc** and **putchar** return **EOF**; **putwc** and **putwchar** return **WEOF**. For all four routines, use [ferror](ferror.md) or [feof](feof.md) to check for an error or end of file. If passed a null pointer for *stream*, these functions generate an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, they return **EOF** or **WEOF** and set **errno** to **EINVAL**. +Returns the character written. To indicate an error or end-of-file condition, `putc` and **`putchar`** return `EOF`; `putwc` and **`putwchar`** return `WEOF`. For all four routines, use [`ferror`](ferror.md) or [`feof`](feof.md) to check for an error or end of file. If passed a null pointer for *`stream`*, these functions generate an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, they return `EOF` or `WEOF`, and set `errno` to `EINVAL`. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, error codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **putc** routine writes the single character *c* to the output *stream* at the current position. Any integer can be passed to **putc**, but only the lower 8 bits are written. The **putchar** routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. **putc** and **putchar** are similar to **fputc** and **_fputchar**, respectively, but are implemented both as functions and as macros (see [Choosing Between Functions and Macros](../../c-runtime-library/recommendations-for-choosing-between-functions-and-macros.md)). **putwc** and **putwchar** are wide-character versions of **putc** and **putchar**, respectively. +The `putc` routine writes the single character *`c`* to the output *`stream`* at the current position. Any integer can be passed to `putc`, but only the lower 8 bits are written. The **`putchar`** routine is identical to `putc( c, stdout )`. For each routine, if a read error occurs, the error indicator for the stream is set. `putc` and **`putchar`** are similar to `fputc` and `_fputchar`, respectively, but are implemented both as functions and as macros (see [Recommendations for choosing between functions and macros](../recommendations-for-choosing-between-functions-and-macros.md)). `putwc` and **`putwchar`** are wide-character versions of `putc` and **`putchar`**, respectively. -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. They may be faster since they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. They may be faster since they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_puttchar**|**putchar**|**putchar**|**putwchar**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_puttchar` | **`putchar`** | **`putchar`** | **`putwchar`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**putchar**|\| -|**putwchar**|\ or \| +| Routine | Required header | +|---|---| +| **`putchar`** | \ | +| **`putwchar`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -95,6 +95,6 @@ This is the line of output ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputc, fputwc](fputc-fputwc.md)
-[getc, getwc](getc-getwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputc`, `fputwc`](fputc-fputwc.md)\ +[`getc`, `getwc`](getc-getwc.md) diff --git a/docs/c-runtime-library/reference/putenv-s-wputenv-s.md b/docs/c-runtime-library/reference/putenv-s-wputenv-s.md index 0a4ce03eed6..6437099f5c6 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_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_wputenv_s", "_putenv_s", "_tputenv_s", "_o__putenv_s", "_o__wputenv_s"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["putenv_s", "wputenv_s", "_wputenv_s", "_putenv_s"] -helpviewer_keywords: ["wputenv_s function", "_putenv_s function", "environment variables, deleting", "putenv_s function", "_wputenv_s function", "environment variables, creating", "environment variables, modifying"] +f1_keywords: ["putenv_s", "wputenv_s", "_wputenv_s", "_putenv_s", "_tputenv_s"] +helpviewer_keywords: ["wputenv_s function", "_putenv_s function", "environment variables, deleting", "putenv_s function", "_wputenv_s function", "environment variables, creating", "environment variables, modifying", "_tputenv_s function"] --- -# `_putenv_s`, `_wputenv_s` +# `_putenv_s`, `_wputenv_s`, `_tputenv_s` -Creates, modifies, or removes environment variables. These are versions of [`_putenv`, `_wputenv`](putenv-wputenv.md) but have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Creates, modifies, or removes environment variables. These functions are versions of [`_putenv`, `_wputenv`](putenv-wputenv.md) that have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +For `_tputenv_s`, see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -37,50 +39,52 @@ The environment variable name. *`value_string`*\ The value to set the environment variable to. -## Return Value +## Return value Returns 0 if successful, or an error code. -### Error Conditions +### Error conditions -|*`varname`*|*`value_string`*|Return value| -|------------|-------------|------------------| -|**`NULL`**|any|**`EINVAL`**| -|any|**`NULL`**|**`EINVAL`**| +| *`varname`* | *`value_string`* | Return value | +|---|---|---| +| `NULL` | any | `EINVAL` | +| any | `NULL` | `EINVAL` | -If one of the error conditions occurs, these functions invoke an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EINVAL`** and set **`errno`** to **`EINVAL`**. +If one of the error conditions occurs, these functions invoke an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL`. ## Remarks The **`_putenv_s`** function adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process executes (for example, the default search path for libraries to be linked with a program). **`_wputenv_s`** is a wide-character version of **`_putenv_s`**; the *`envstring`* argument to **`_wputenv_s`** is a wide-character string. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). + +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tputenv_s`**|**`_putenv_s`**|**`_putenv_s`**|**`_wputenv_s`**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tputenv_s` | `_putenv_s` | `_putenv_s` | `_wputenv_s` | *`varname`* is the name of the environment variable to be added or modified and *`value_string`* is the variable's value. If *`varname`* is already part of the environment, its value is replaced by *`value_string`*; otherwise, the new *`varname`* variable and its *`value_string`* are added to the environment. You can remove a variable from the environment by specifying an empty string (that is, `""`) for *`value_string`*. -**`_putenv_s`** and **`_wputenv_s`** affect only the environment that is local to the current process; you can’t use them to modify the command-level environment. These functions operate only on data structures that are accessible to the run-time library and not on the environment "segment" that the operating system creates for a process. When the current process terminates, the environment reverts to the level of the calling process, which in most cases is the operating-system level. However, the modified environment can be passed to any new processes that are created by **`_spawn`**, **`_exec`**, or **`system`**, and these new processes get any new items that are added by **`_putenv_s`** and **`_wputenv_s`**. +**`_putenv_s`** and **`_wputenv_s`** affect only the environment that is local to the current process; you can't use them to modify the command-level environment. These functions operate only on data structures that are accessible to the run-time library and not on the environment "segment" that the operating system creates for a process. When the current process terminates, the environment reverts to the level of the calling process, which in most cases is the operating-system level. However, the modified environment can be passed to any new processes that are created by **`_spawn`**, **`_exec`**, or **`system`**, and these new processes get any new items that are added by **`_putenv_s`** and **`_wputenv_s`**. Don't change an environment entry directly; instead, use **`_putenv_s`** or **`_wputenv_s`** to change it. In particular, directly freeing elements of the **`_environ[]`** global array might cause invalid memory to be addressed. -**`getenv`** and **`_putenv_s`** use the global variable **`_environ`** to access the environment table; **`_wgetenv`** and **`_wputenv_s`** use **`_wenviron`**. **`_putenv_s`** and **`_wputenv_s`** may change the value of **`_environ`** and **`_wenviron`**, and thereby invalidate the *`envp`* argument to **`main`** and the **`_wenvp`** argument to **`wmain`**. Therefore, it's safer to use **`_environ`** or **`_wenviron`** to access the environment information. For more information about the relationship of **`_putenv_s`** and **`_wputenv_s`** to global variables, see [`_environ`, `_wenviron`](../../c-runtime-library/environ-wenviron.md). +**`getenv`** and **`_putenv_s`** use the global variable **`_environ`** to access the environment table; **`_wgetenv`** and **`_wputenv_s`** use **`_wenviron`**. **`_putenv_s`** and **`_wputenv_s`** may change the value of **`_environ`** and **`_wenviron`**, and thereby invalidate the *`envp`* argument to **`main`** and the **`_wenvp`** argument to **`wmain`**. Therefore, it's safer to use **`_environ`** or **`_wenviron`** to access the environment information. For more information about the relationship of **`_putenv_s`** and **`_wputenv_s`** to global variables, see [`_environ`, `_wenviron`](../environ-wenviron.md). > [!NOTE] > The **`_putenv_s`** and **`_getenv_s`** families of functions are not thread-safe. **`_getenv_s`** could return a string pointer while **`_putenv_s`** is modifying the string, and thereby cause random failures. Make sure that calls to these functions are synchronized. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_putenv_s`**|``| -|**`_wputenv_s`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_putenv_s`** | `` | +| **`_wputenv_s`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -88,6 +92,6 @@ For a sample that shows how to use **`_putenv_s`**, see [`getenv_s`, `_wgetenv_s ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`getenv`, `_wgetenv`](getenv-wgetenv.md)\ [`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md) diff --git a/docs/c-runtime-library/reference/putenv-wputenv.md b/docs/c-runtime-library/reference/putenv-wputenv.md index a95b63a64b7..943fa197608 100644 --- a/docs/c-runtime-library/reference/putenv-wputenv.md +++ b/docs/c-runtime-library/reference/putenv-wputenv.md @@ -3,7 +3,7 @@ description: "Learn more about: _putenv, _wputenv" title: "_putenv, _wputenv" ms.date: "4/2/2020" api_name: ["_putenv", "_wputenv", "_o__putenv", "_o__wputenv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tputenv", "_wputenv", "_putenv", "wputenv", "tputenv"] @@ -32,41 +32,41 @@ int _wputenv( *`envstring`*\ Environment-string definition. -## Return Value +## Return value -Return 0 if successful or -1 in the case of an error. +The functions return 0 if successful, or -1 if there's an error. ## Remarks The **`_putenv`** function adds new environment variables or modifies the values of existing environment variables. Environment variables define the environment in which a process executes (for example, the default search path for libraries to be linked with a program). **`_wputenv`** is a wide-character version of **`_putenv`**; the *`envstring`* argument to **`_wputenv`** is a wide-character string. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE and _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**`_tputenv`**|**`_putenv`**|**`_putenv`**|**`_wputenv`**| +| `Tchar.h` routine | `_UNICODE and _MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tputenv` | **`_putenv`** | **`_putenv`** | **`_wputenv`** | The *`envstring`* argument must be a pointer to a string of the form *`varname=value_string`*, where *`varname`* is the name of the environment variable to be added or modified and *`value_string`* is the variable's value. If *`varname`* is already part of the environment, its value is replaced by *`value_string`*; otherwise, the new *`varname`* variable and its *`value_string`* value are added to the environment. You can remove a variable from the environment by specifying an empty *`value_string`*, or in other words, by specifying only *`varname`*=. -**`_putenv`** and **`_wputenv`** affect only the environment that is local to the current process; you can’t use them to modify the command-level environment. That is, these functions operate only on data structures accessible to the run-time library and not on the environment segment created for a process by the operating system. When the current process terminates, the environment reverts to the level of the calling process (in most cases, the operating-system level). However, the modified environment can be passed to any new processes created by **`_spawn`**, **`_exec`**, or **`system`**, and these new processes get any new items added by **`_putenv`** and **`_wputenv`**. +**`_putenv`** and **`_wputenv`** affect only the environment that is local to the current process; you can't use them to modify the command-level environment. That is, these functions operate only on data structures accessible to the run-time library. They don't operate on the environment segment created for a process by the operating system. When the current process terminates, the environment reverts to the level of the calling process (in most cases, the operating-system level). However, the modified environment can be passed to any new processes created by **`_spawn`**, **`_exec`**, or **`system`**, and these new processes get any new items added by **`_putenv`** and **`_wputenv`**. Don't change an environment entry directly: instead, use **`_putenv`** or **`_wputenv`** to change it. In particular, direct freeing elements of the **`_environ[]`** global array might lead to invalid memory being addressed. -**`_getenv`** and **`_putenv`** use the global variable **`_environ`** to access the environment table; **`_wgetenv`** and **`_wputenv`** use **`_wenviron`**. **`_putenv`** and **`_wputenv`** might change the value of **`_environ`** and **`_wenviron`**, thus invalidating the **`_envp`** argument to **`main`** and the **`_wenvp`** argument to **`wmain`**. Therefore, it's safer to use **`_environ`** or **`_wenviron`** to access the environment information. For more information about the relation of **`_putenv`** and **`_wputenv`** to global variables, see [`_environ`, `_wenviron`](../../c-runtime-library/environ-wenviron.md). +**`_getenv`** and **`_putenv`** use the global variable **`_environ`** to access the environment table; **`_wgetenv`** and **`_wputenv`** use **`_wenviron`**. **`_putenv`** and **`_wputenv`** might change the value of **`_environ`** and **`_wenviron`**, thus invalidating the **`_envp`** argument to **`main`** and the **`_wenvp`** argument to **`wmain`**. Therefore, it's safer to use **`_environ`** or **`_wenviron`** to access the environment information. For more information about the relation of **`_putenv`** and **`_wputenv`** to global variables, see [`_environ`, `_wenviron`](../environ-wenviron.md). > [!NOTE] > The **`_putenv`** and **`_getenv`** families of functions are not thread-safe. **`_getenv`** could return a string pointer while **`_putenv`** is modifying the string, causing random failures. Make sure that calls to these functions are synchronized. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_putenv`**|``| -|**`_wputenv`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_putenv`** | `` | +| **`_wputenv`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -74,6 +74,6 @@ For a sample of how to use **`_putenv`**, see [`getenv`, `_wgetenv`](getenv-wget ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)\ +[Process and environment control](../process-and-environment-control.md)\ [`getenv`, `_wgetenv`](getenv-wgetenv.md)\ [`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md) diff --git a/docs/c-runtime-library/reference/putenv.md b/docs/c-runtime-library/reference/putenv.md index 92499d53efe..ced02af37e1 100644 --- a/docs/c-runtime-library/reference/putenv.md +++ b/docs/c-runtime-library/reference/putenv.md @@ -10,11 +10,11 @@ f1_keywords: ["putenv"] helpviewer_keywords: ["putenv function"] ms.assetid: 1dc49ef3-6b12-484c-8e60-7048bcc999f1 --- -# putenv +# `putenv` -The Microsoft-implemented POSIX function name `putenv` is a deprecated alias for the [_putenv](putenv-wputenv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `putenv` is a deprecated alias for the [`_putenv`](putenv-wputenv.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_putenv](putenv-wputenv.md) or security-enhanced [_putenv_s](putenv-s-wputenv-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_putenv`](putenv-wputenv.md) or security-enhanced [`_putenv_s`](putenv-s-wputenv-s.md) function instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/puts-putws.md b/docs/c-runtime-library/reference/puts-putws.md index 1c9ad50eedc..c7a68163da1 100644 --- a/docs/c-runtime-library/reference/puts-putws.md +++ b/docs/c-runtime-library/reference/puts-putws.md @@ -3,16 +3,16 @@ description: "Learn more about: puts, _putws" title: "puts, _putws" ms.date: "4/2/2020" api_name: ["_putws", "puts", "_o__putws", "_o_puts"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putts", "_putws", "puts"] helpviewer_keywords: ["strings [C++], writing", "_putts function", "standard output, writing to", "putws function", "puts function", "putts function", "_putws function"] ms.assetid: 32dada12-ed45-40ac-be06-3feeced9ecd6 --- -# puts, _putws +# `puts`, `_putws` -Writes a string to **stdout**. +Writes a string to `stdout`. ## Syntax @@ -27,43 +27,43 @@ int _putws( ### Parameters -*str*
+*`str`*\ Output string. -## Return Value +## Return value -Returns a nonnegative value if successful. If **puts** fails, it returns **EOF**; if **_putws** fails, it returns **WEOF**. If *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions set **errno** to **EINVAL** and return **EOF** or **WEOF**. +Returns a nonnegative value if successful. If **`puts`** fails, it returns `EOF`; if **`_putws`** fails, it returns `WEOF`. If *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions set `errno` to `EINVAL` and return `EOF` or `WEOF`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **puts** function writes *str* to the standard output stream **stdout**, replacing the string's terminating null character ('\0') with a newline character ('\n') in the output stream. +The **`puts`** function writes *`str`* to the standard output stream `stdout`, replacing the string's terminating null character ('\0') with a newline character ('\n') in the output stream. -**_putws** is the wide-character version of **puts**; the two functions behave identically if the stream is opened in ANSI mode. **puts** doesn't currently support output into a UNICODE stream. +**`_putws`** is the wide-character version of **`puts`**; the two functions behave identically if the stream is opened in ANSI mode. **`puts`** doesn't currently support output into a UNICODE stream. -**_putwch** writes Unicode characters using the current CONSOLE LOCALE setting. +`_putwch` writes Unicode characters using the current CONSOLE LOCALE setting. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_putts**|**puts**|**puts**|**_putws**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_putts` | **`puts`** | **`puts`** | **`_putws`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**puts**|\| -|**_putws**|\| +| Routine | Required header | +|---|---| +| **`puts`** | \ | +| **`_putws`** | \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -87,6 +87,6 @@ Hello world from puts! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fputs, fputws](fputs-fputws.md)
-[fgets, fgetws](fgets-fgetws.md)
+[Stream I/O](../stream-i-o.md)\ +[`fputs`, `fputws`](fputs-fputws.md)\ +[`fgets`, `fgetws`](fgets-fgetws.md) diff --git a/docs/c-runtime-library/reference/putw.md b/docs/c-runtime-library/reference/putw.md index b8f32d74a60..3f5bd5725d4 100644 --- a/docs/c-runtime-library/reference/putw.md +++ b/docs/c-runtime-library/reference/putw.md @@ -3,14 +3,14 @@ description: "Learn more about: _putw" title: "_putw" ms.date: "4/2/2020" api_name: ["_putw", "_o__putw"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_putw"] helpviewer_keywords: ["integers, writing to streams", "putw function", "streams, writing integers to", "_putw function"] ms.assetid: 83d63644-249d-4a39-87e5-3b7aa313968d --- -# _putw +# `_putw` Writes an integer to a stream. @@ -25,35 +25,35 @@ int _putw( ### Parameters -*binint*
+*`binint`*\ Binary integer to be output. -*stream*
-Pointer to the **FILE** structure. +*`stream`*\ +Pointer to the `FILE` structure. -## Return Value +## Return value -Returns the value written. A return value of **EOF** might indicate an error. Because **EOF** is also a legitimate integer value, use **ferror** to verify an error. If *stream* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EOF**. +Returns the value written. A return value of `EOF` might indicate an error. Because `EOF` is also a legitimate integer value, use `ferror` to verify an error. If *`stream`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EOF`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_putw** function writes a binary value of type **`int`** to the current position of *stream.* **_putw** does not affect the alignment of items in the stream nor does it assume any special alignment. **_putw** is primarily for compatibility with previous libraries. Portability problems might occur with **_putw** because the size of an **`int`** and the ordering of bytes within an **`int`** differ across systems. +The **`_putw`** function writes a binary value of type **`int`** to the current position of *stream.* **`_putw`** doesn't affect the alignment of items in the stream nor does it assume any special alignment. **`_putw`** is primarily for compatibility with previous libraries. Portability problems might occur with **`_putw`** because the size of an **`int`** and the ordering of bytes within an **`int`** differ across systems. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_putw**|\| +| Routine | Required header | +|---|---| +| **`_putw`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -95,5 +95,5 @@ Wrote ten words ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_getw](getw.md)
+[Stream I/O](../stream-i-o.md)\ +[`_getw`](getw.md) diff --git a/docs/c-runtime-library/reference/qsort-s.md b/docs/c-runtime-library/reference/qsort-s.md index 5011d7297cf..d5703f65c0d 100644 --- a/docs/c-runtime-library/reference/qsort-s.md +++ b/docs/c-runtime-library/reference/qsort-s.md @@ -3,16 +3,16 @@ description: "Learn more about: qsort_s" title: "qsort_s" ms.date: "4/2/2020" api_name: ["qsort_s", "_o_qsort_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["qsort_s"] helpviewer_keywords: ["arrays [C++], sorting", "quick-sort algorithm", "qsort_s function", "sorting arrays"] ms.assetid: 6ee817b0-4408-4355-a5d4-6605e419ab91 --- -# qsort_s +# `qsort_s` -Performs a quick sort. A version of [qsort](qsort.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Performs a quick sort. A version of [`qsort`](qsort.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -28,24 +28,24 @@ void qsort_s( ### Parameters -*base*
+*`base`*\ Start of target array. -*number*
+*`number`*\ Array size in elements. -*width*
+*`width`*\ Element size in bytes. -*compare*
-Comparison function. The first argument is the *context* pointer. The second argument is a pointer to the *key* for the search. The third argument is a pointer to the array element to be compared with *key*. +*`compare`*\ +Comparison function. The first argument is the *`context`* pointer. The second argument is a pointer to the *`key`* for the search. The third argument is a pointer to the array element to be compared with *`key`*. -*context*
-A pointer to a context, which can be any object that the *compare* routine needs to access. +*`context`*\ +A pointer to a context, which can be any object that the *`compare`* routine needs to access. ## Remarks -The **qsort_s** function implements a quick-sort algorithm to sort an array of *number* elements, each of *width* bytes. The argument *base* is a pointer to the base of the array to be sorted. **qsort_s** overwrites this array with the sorted elements. The argument *compare* is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. **qsort_s** calls the *compare* routine one or more times during the sort, passing pointers to two array elements on each call: +The **`qsort_s`** function implements a quick-sort algorithm to sort an array of *`number`* elements, each of *`width`* bytes. The argument *`base`* is a pointer to the base of the array to be sorted. **`qsort_s`** overwrites this array with the sorted elements. The argument *`compare`* is a pointer to a user-supplied routine that compares two array elements and returns a value specifying their relationship. **`qsort_s`** calls the *`compare`* routine one or more times during the sort, passing pointers to two array elements on each call: ```C compare( context, (void *) & elem1, (void *) & elem2 ); @@ -53,42 +53,42 @@ compare( context, (void *) & elem1, (void *) & elem2 ); The routine must compare the elements and then return one of the following values: -|Return value|Description| -|------------------|-----------------| -|< 0|**elem1** less than **elem2**| -|0|**elem1** equivalent to **elem2**| -|> 0|**elem1** greater than **elem2**| +| Return value | Description | +|---|---| +| < 0 | *element 1* less than *element 2* | +| 0 | *element 1* equivalent to *element 2* | +| > 0 | *element 1* greater than *element 2* | The array is sorted in increasing order, as defined by the comparison function. To sort an array in decreasing order, reverse the sense of "greater than" and "less than" in the comparison function. -If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, then the function returns and **errno** is set to **EINVAL**. For more information, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +If invalid parameters are passed to the function, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, then the function returns, and `errno` is set to `EINVAL`. For more information, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Error Conditions +### Error conditions -|key|base|compare|num|width|errno| -|---------|----------|-------------|---------|-----------|-----------| -|**NULL**|any|any|any|any|**EINVAL**| -|any|**NULL**|any|!= 0|any|**EINVAL**| -|any|any|any|any|<= 0|**EINVAL**| -|any|any|**NULL**|any|any|**EINVAL**| +| key | base | compare | num | width | errno | +|---|---|---|---|---|---| +| `NULL` | any | any | any | any | `EINVAL` | +| any | `NULL` | any | != 0 | any | `EINVAL` | +| any | any | any | any | <= 0 | `EINVAL` | +| any | any | `NULL` | any | any | `EINVAL` | -**qsort_s** has the same behavior as **qsort** but has the *context* parameter and sets **errno**. By passing a *context* parameter, comparison functions can use an object pointer to access object functionality or other information not accessible through an element pointer. The addition of the *context* parameter makes **qsort_s** more secure because *context* can be used to avoid reentrancy bugs introduced by using static variables to make shared information available to the *compare* function. +**`qsort_s`** has the same behavior as `qsort` but has the *`context`* parameter and sets `errno`. The *`context`* parameter allows comparison functions to use an object pointer to access object functionality or other information not accessible through an element pointer. The addition of the *`context`* parameter makes **`qsort_s`** more secure because *`context`* can be used to avoid reentrancy bugs introduced by using static variables to make shared information available to the *`compare`* function. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**qsort_s**|\ and \| +| Routine | Required header | +|---|---| +| **`qsort_s`** | \ and \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** All versions of the [C runtime libraries](../../c-runtime-library/crt-library-features.md). +**Libraries:** All versions of the [C runtime libraries](../crt-library-features.md). ## Example -The following example demonstrates how to use the *context* parameter in the **qsort_s** function. The *context* parameter makes it easier to perform thread-safe sorts. Instead of using static variables that must be synchronized to ensure thread safety, pass a different *context* parameter in each sort. In this example, a locale object is used as the *context* parameter. +The following example demonstrates how to use the *`context`* parameter in the **`qsort_s`** function. The *`context`* parameter makes it easier to perform thread-safe sorts. Instead of using static variables that must be synchronized to ensure thread safety, pass a different *`context`* parameter in each sort. In this example, a locale object is used as the *`context`* parameter. ```cpp // crt_qsort_s.cpp @@ -227,7 +227,7 @@ int main( ) } ``` -### Sample Output +### Sample output ```Output Unsorted input: @@ -242,7 +242,7 @@ table tablet tableux ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)
-[bsearch_s](bsearch-s.md)
-[_lsearch_s](lsearch-s.md)
-[qsort](qsort.md)
+[Searching and sorting](../searching-and-sorting.md)\ +[`bsearch_s`](bsearch-s.md)\ +[`_lsearch_s`](lsearch-s.md)\ +[`qsort`](qsort.md) diff --git a/docs/c-runtime-library/reference/qsort.md b/docs/c-runtime-library/reference/qsort.md index 38d337a08f8..9364fefb826 100644 --- a/docs/c-runtime-library/reference/qsort.md +++ b/docs/c-runtime-library/reference/qsort.md @@ -1,9 +1,9 @@ --- title: "qsort" description: "Describes the Microsoft C runtime quick sort API `qsort`" -ms.date: "10/23/2020" +ms.date: "8/2/2023" api_name: ["qsort", "_o_qsort"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["qsort"] @@ -45,30 +45,30 @@ The **`qsort`** function implements a quick-sort algorithm to sort an array of * **`qsort`** calls the *`compare`* routine one or more times during the sort, and passes pointers to two array elements on each call. If *`compare`* indicates two elements are the same, their order in the resulting sorted array is unspecified. ```C -compare( (void *) & elem1, (void *) & elem2 ); +compare(const void *elem1, const void *elem2); ``` The routine compares the elements and returns one of the following values. -|Compare function return value|Description| -|-----------------------------------|-----------------| -|< 0|**`elem1`** less than **`elem2`**| -|0|**`elem1`** equivalent to **`elem2`**| -|> 0|**`elem1`** greater than **`elem2`**| +| Compare function return value | Description | +|---|---| +| < 0 | **`elem1`** less than **`elem2`** | +| 0 | **`elem1`** equivalent to **`elem2`** | +| > 0 | **`elem1`** greater than **`elem2`** | The array is sorted in increasing order, as defined by the comparison function. To sort an array in decreasing order, reverse the sense of "greater than" and "less than" in the comparison function. -This function validates its parameters. If *`compare`* or *`number`* is **`NULL`**, or if *`base`* is **`NULL`** and *`number`* is nonzero, or if *`width`* is less than zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns and **`errno`** is set to **`EINVAL`**. +This function validates its parameters. If *`compare`* or *`number`* is `NULL`, or if *`base`* is `NULL` and *`number`* is nonzero, or if *`width`* is less than zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns, and `errno` is set to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`qsort`**|`` and ``| +| Routine | Required header | +|---|---| +| **`qsort`** | `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -116,6 +116,6 @@ boy deserves every favor good ## See also -[Searching and Sorting](../../c-runtime-library/searching-and-sorting.md)\ +[Searching and sorting](../searching-and-sorting.md)\ [`bsearch`](bsearch.md)\ [`_lsearch`](lsearch.md) diff --git a/docs/c-runtime-library/reference/query-new-handler.md b/docs/c-runtime-library/reference/query-new-handler.md index 62f280d87d4..d78494f3fae 100644 --- a/docs/c-runtime-library/reference/query-new-handler.md +++ b/docs/c-runtime-library/reference/query-new-handler.md @@ -10,9 +10,9 @@ f1_keywords: ["_query_new_handler", "query_new_handler"] helpviewer_keywords: ["query_new_handler function", "handler routines", "error handling", "_query_new_handler function"] ms.assetid: 9a84b5c3-fe33-4c01-83a0-be87dc3ec518 --- -# _query_new_handler +# `_query_new_handler` -Returns the address of the current new handler routine. +Returns the address of the current **`new`** handler routine. ## Syntax @@ -22,27 +22,27 @@ _PNH _query_new_handler( ); ``` -## Return Value +## Return value -Returns the address of the current new handler routine as set by **_set_new_handler**. +Returns the address of the current **`new`** handler routine as set by `_set_new_handler`. ## Remarks -The C++ **_query_new_handler** function returns the address of the current exception-handling function set by the C++ [_set_new_handler](set-new-handler.md) function. **_set_new_handler** is used to specify an exception-handling function that is to gain control if the **`new`** operator fails to allocate memory. For more information, see the discussion of the [new and delete operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. +The C++ **`_query_new_handler`** function returns the address of the current exception-handling function set by the C++ [`_set_new_handler`](set-new-handler.md) function. `_set_new_handler` is used to specify an exception-handling function that is to gain control if the **`new`** operator fails to allocate memory. For more information, see the discussion of the [`new` and `delete` operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_query_new_handler**|\| +| Routine | Required header | +|---|---| +| **`_query_new_handler`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[free](free.md)
+[Memory allocation](../memory-allocation.md)\ +[`free`](free.md) diff --git a/docs/c-runtime-library/reference/query-new-mode.md b/docs/c-runtime-library/reference/query-new-mode.md index 72e4d3ef34c..d5feb921c31 100644 --- a/docs/c-runtime-library/reference/query-new-mode.md +++ b/docs/c-runtime-library/reference/query-new-mode.md @@ -10,9 +10,9 @@ f1_keywords: ["query_new_mode", "_query_new_mode"] helpviewer_keywords: ["query_new_mode function", "handler modes", "_query_new_mode function"] ms.assetid: e185c5f9-b73b-4257-8eff-b47648374768 --- -# _query_new_mode +# `_query_new_mode` -Returns an integer indicating the new handler mode set by **_set_new_mode** for **malloc**. +Returns an integer indicating the **`new`** handler mode set by `_set_new_mode` for `malloc`. ## Syntax @@ -22,30 +22,30 @@ int _query_new_mode( ); ``` -## Return Value +## Return value -Returns the current new handler mode, namely 0 or 1, for **malloc**. A return value of 1 indicates that, on failure to allocate memory, **malloc** calls the new handler routine; a return value of 0 indicates that it does not. +Returns the current **`new`** handler mode, namely 0 or 1, for `malloc`. A return value of 1 indicates that, on failure to allocate memory, `malloc` calls the **`new`** handler routine; a return value of 0 indicates that it doesn't. ## Remarks -The C++ **_query_new_mode** function returns an integer that indicates the new handler mode that is set by the C++ [_set_new_mode](set-new-mode.md) function for [malloc](malloc.md). The new handler mode indicates whether, on failure to allocate memory, **malloc** is to call the new handler routine as set by [_set_new_handler](set-new-handler.md). By default, **malloc** does not call the new handler routine on failure. You can use **_set_new_mode** to override this behavior so that on failure **malloc** calls the new handler routine in the same way that the **`new`** operator does when it fails to allocate memory. For more information, see the discussion of the [new and delete operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. +The C++ **`_query_new_mode`** function returns an integer that indicates the **`new`** handler mode that is set by the C++ [`_set_new_mode`](set-new-mode.md) function for [`malloc`](malloc.md). The **`new`** handler mode indicates whether, on failure to allocate memory, `malloc` is to call the **`new`** handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, `malloc` doesn't call the **`new`** handler routine on failure. You can use `_set_new_mode` to override this behavior so that on failure `malloc` calls the **`new`** handler routine in the same way that the **`new`** operator does when it fails to allocate memory. For more information, see the discussion of the [new and delete operators](../../cpp/new-and-delete-operators.md) in the C++ Language Reference. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_query_new_mode**|\| +| Routine | Required header | +|---|---| +| **`_query_new_mode`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[calloc](calloc.md)
-[free](free.md)
-[realloc](realloc.md)
-[_query_new_handler](query-new-handler.md)
+[Memory allocation](../memory-allocation.md)\ +[`calloc`](calloc.md)\ +[`free`](free.md)\ +[`realloc`](realloc.md)\ +[`_query_new_handler`](query-new-handler.md) diff --git a/docs/c-runtime-library/reference/quick-exit1.md b/docs/c-runtime-library/reference/quick-exit1.md index ee936274292..77eba98477c 100644 --- a/docs/c-runtime-library/reference/quick-exit1.md +++ b/docs/c-runtime-library/reference/quick-exit1.md @@ -10,7 +10,7 @@ f1_keywords: ["quick_exit", "process/quick_exit", "stdlib/quick_exit"] helpviewer_keywords: ["quick_exit function"] ms.assetid: ecfbdae6-01c4-45fa-aaeb-b368e1de2a9c --- -# quick_exit +# `quick_exit` Causes normal program termination to occur. @@ -24,36 +24,36 @@ __declspec(noreturn) void quick_exit( ### Parameters -*status*
+*`status`*\ The status code to return to the host environment. -## Return Value +## Return value -The **quick_exit** function cannot return to its caller. +The **`quick_exit`** function can't return to its caller. ## Remarks -The **quick_exit** function causes normal program termination. It calls no functions registered by **atexit**, **_onexit** or signal handlers registered by the **signal** function. Behavior is undefined if **quick_exit** is called more than once, or if the **exit** function is also called. +The **`quick_exit`** function causes normal program termination. It calls no functions registered by `atexit`, `_onexit` or signal handlers registered by the `signal` function. Behavior is undefined if **`quick_exit`** is called more than once, or if the `exit` function is also called. -The **quick_exit** function calls, in last-in, first-out (LIFO) order, the functions registered by **at_quick_exit**, except for those functions already called when the function was registered. Behavior is undefined if a [longjmp](longjmp.md) call is made during a call to a registered function that would terminate the call to the function. +The **`quick_exit`** function calls, in last-in, first-out (LIFO) order, the functions registered by `at_quick_exit`, except for those functions already called when the function was registered. Behavior is undefined if a [`longjmp`](longjmp.md) call is made during a call to a registered function that would terminate the call to the function. -After the registered functions have been called, **quick_exit** invokes **_Exit** by using the *status* value to return control to the host environment. +After the registered functions have been called, **`quick_exit`** invokes `_Exit` by using the *`status`* value to return control to the host environment. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**quick_exit**|\ or \| +| Routine | Required header | +|---|---| +| **`quick_exit`** | \ or \ | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[abort](abort.md)
-[atexit](atexit.md)
-[_exec, _wexec Functions](../../c-runtime-library/exec-wexec-functions.md)
-[exit, _Exit, _exit](exit-exit-exit.md)
-[_onexit, _onexit_m](onexit-onexit-m.md)
-[_spawn, _wspawn Functions](../../c-runtime-library/spawn-wspawn-functions.md)
-[system, _wsystem](system-wsystem.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`atexit`](atexit.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_onexit`, `_onexit_m`](onexit-onexit-m.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md)\ +[`system`, `_wsystem`](system-wsystem.md) diff --git a/docs/c-runtime-library/reference/raise.md b/docs/c-runtime-library/reference/raise.md index 469d8528f7c..e3fe3e05b62 100644 --- a/docs/c-runtime-library/reference/raise.md +++ b/docs/c-runtime-library/reference/raise.md @@ -3,18 +3,18 @@ description: "Learn more about: raise" title: "raise" ms.date: "4/2/2020" api_name: ["raise", "_o_raise"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["Raise"] helpviewer_keywords: ["signals, sending to executing programs", "raise function", "signals", "programs [C++], sending signals to executing programs"] --- -# raise +# `raise` Sends a signal to the executing program. > [!NOTE] -> Do not use this method to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). +> Do not use this method to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). ## Syntax @@ -26,40 +26,40 @@ int raise( ### Parameters -*sig*
+*`sig`*\ Signal to be raised. -## Return Value +## Return value -If successful, **raise** returns 0. Otherwise, it returns a nonzero value. +If successful, **`raise`** returns 0. Otherwise, it returns a nonzero value. ## Remarks -The **raise** function sends *sig* to the executing program. If a previous call to **signal** has installed a signal-handling function for *sig*, **raise** executes that function. If no handler function has been installed, the default action associated with the signal value *sig* is taken, as follows. +The **`raise`** function sends *`sig`* to the executing program. If a previous call to `signal` has installed a signal-handling function for *`sig`*, **`raise`** executes that function. If no handler function has been installed, the default action associated with the signal value *`sig`* is taken, as follows. -|Signal|Meaning|Default| -|------------|-------------|-------------| -|**SIGABRT**|Abnormal termination|Terminates the calling program with exit code 3| -|**SIGFPE**|Floating-point error|Terminates the calling program| -|**SIGILL**|Illegal instruction|Terminates the calling program| -|**SIGINT**|CTRL+C interrupt|Terminates the calling program| -|**SIGSEGV**|Illegal storage access|Terminates the calling program| -|**SIGTERM**|Termination request sent to the program|Ignores the signal| +| Signal | Description | Default behavior | +|---|---|---| +| `SIGABRT` | Abnormal termination | Terminates the calling program with exit code 3 | +| `SIGFPE` | Floating-point error | Terminates the calling program | +| `SIGILL` | Illegal instruction | Terminates the calling program | +| `SIGINT` | CTRL+C interrupt | Terminates the calling program | +| `SIGSEGV` | Illegal storage access | Terminates the calling program | +| `SIGTERM` | Termination request sent to the program | Ignores the signal | -If the argument is not a valid signal as specified above, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If not handled, the function sets **errno** to **EINVAL** and returns a nonzero value. +If the argument isn't a valid signal as specified above, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If not handled, the function sets `errno` to `EINVAL` and returns a nonzero value. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**raise**|\| +| Routine | Required header | +|---|---| +| **`raise`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[abort](abort.md)
-[signal](signal.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`abort`](abort.md)\ +[`signal`](signal.md) diff --git a/docs/c-runtime-library/reference/rand-s.md b/docs/c-runtime-library/reference/rand-s.md index f8c381d5f76..427578e5e05 100644 --- a/docs/c-runtime-library/reference/rand-s.md +++ b/docs/c-runtime-library/reference/rand-s.md @@ -3,7 +3,7 @@ description: "Learn more about: rand_s" title: "rand_s" ms.date: "4/2/2020" api_name: ["rand_s", "_o_rand_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["STDLIB/rand_s", "rand_s"] @@ -11,7 +11,7 @@ helpviewer_keywords: ["generating pseudorandom numbers", "random numbers, crypto --- # `rand_s` -Generates a pseudorandom number. This is a more secure version of the function [`rand`](rand.md), with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Generates a pseudorandom number. This function is a more secure version of the function [`rand`](rand.md), with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -24,17 +24,17 @@ errno_t rand_s(unsigned int* randomValue); *`randomValue`*\ A pointer to an integer to hold the generated value. -## Return Value +## Return value -Zero if successful, otherwise, an error code. If the input pointer `_randomValue_` is a `NULL` pointer, the function invokes an invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **`EINVAL`** and sets **`errno`** to **`EINVAL`**. If the function fails for any other reason, `*_randomValue_` is set to 0. +Zero if successful, otherwise, an error code. If the input pointer `_randomValue_` is a `NULL` pointer, the function invokes an invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `EINVAL` and sets `errno` to `EINVAL`. If the function fails for any other reason, `*_randomValue_` is set to 0. ## Remarks -The **`rand_s`** function writes a pseudorandom integer in the range 0 to **`UINT_MAX`** to the input pointer. The **`rand_s`** function uses the operating system to generate cryptographically secure random numbers. It doesn't use the seed generated by the [`srand`](srand.md) function, nor does it affect the random number sequence used by [`rand`](rand.md). +The **`rand_s`** function writes a pseudorandom integer in the range 0 to `UINT_MAX` to the input pointer. The **`rand_s`** function uses the operating system to generate cryptographically secure random numbers. It doesn't use the seed generated by the [`srand`](srand.md) function, nor does it affect the random number sequence used by [`rand`](rand.md). -The **`rand_s`** function requires that constant **`_CRT_RAND_S`** be defined prior to the inclusion statement for the function to be declared, as in the following example: +The `_CRT_RAND_S` constant must be defined before the `stdlib.h` header for the **`rand_s`** function is included, as shown in the following example: -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ```C #define _CRT_RAND_S @@ -45,11 +45,11 @@ By default, this function's global state is scoped to the application. To change ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`rand_s`**|``| +| Routine | Required header | +|---|---| +| **`rand_s`** | `` | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Example @@ -58,8 +58,8 @@ For more information, see [Compatibility](../../c-runtime-library/compatibility. // This program illustrates how to generate random // integer or floating point numbers in a specified range. -// Remembering to define _CRT_RAND_S prior -// to inclusion statement. +// Remember to define _CRT_RAND_S before you include +// stdlib.h. #define _CRT_RAND_S #include @@ -101,7 +101,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output 10 @@ -129,6 +129,6 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`rand`](rand.md)\ [`srand`](srand.md) diff --git a/docs/c-runtime-library/reference/rand.md b/docs/c-runtime-library/reference/rand.md index cdef135e783..2c065c0b390 100644 --- a/docs/c-runtime-library/reference/rand.md +++ b/docs/c-runtime-library/reference/rand.md @@ -3,7 +3,7 @@ title: "rand" description: "API reference for rand, which generates a pseudorandom number by using a well-known and fully reproducible algorithm." ms.date: "7/7/2021" api_name: ["rand", "_o_rand"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["STDLIB/rand", "rand"] @@ -19,25 +19,25 @@ Generates a pseudorandom number. A more programmatically secure version of this int rand(void); ``` -## Return Value +## Return value **`rand`** returns a pseudorandom number, as described above. There's no error return. ## Remarks -The **`rand`** function returns a pseudorandom integer in the range 0 to **`RAND_MAX`** (32767). Use the [`srand`](srand.md) function to seed the pseudorandom-number generator before calling **`rand`**. +The **`rand`** function returns a pseudorandom integer in the range 0 to `RAND_MAX` (32767). Use the [`srand`](srand.md) function to seed the pseudorandom-number generator before calling **`rand`**. The **`rand`** function generates a well-known sequence and isn't appropriate for use as a cryptographic function. For more cryptographically secure random number generation, use [`rand_s`](rand-s.md) or the functions declared in the C++ Standard Library in [``](../../standard-library/random.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`rand`**|``| +| Routine | Required header | +|---|---| +| **`rand`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -72,7 +72,7 @@ void RangedRandDemo(int range_min, int range_max, int n) // generating random numbers across a large range using the method below. // The approach below also may result in a non-uniform distribution. // More robust random number functionality is available in the C++ header. - // See https://docs.microsoft.com/cpp/standard-library/random + // See https://learn.microsoft.com/cpp/standard-library/random int r = ((double)rand() / RAND_MAX) * (range_max - range_min) + range_min; printf(" %6d\n", r); } @@ -120,7 +120,7 @@ Random number in a range demo ==== ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`srand`](srand.md)\ [`rand_s`](rand-s.md)\ [C++ `` library](../../standard-library/random.md) diff --git a/docs/c-runtime-library/reference/read.md b/docs/c-runtime-library/reference/read.md index 7d42e35a609..2e7096eca66 100644 --- a/docs/c-runtime-library/reference/read.md +++ b/docs/c-runtime-library/reference/read.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: _read" title: "_read" +description: "Learn more about: _read" ms.date: "4/2/2020" api_name: ["_read", "_o__read"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_read"] @@ -34,15 +34,15 @@ Storage location for data. *`buffer_size`*\ Maximum number of bytes to read. -## Return Value +## Return value -**`_read`** returns the number of bytes read, which might be less than *`buffer_size`* if there are fewer than *`buffer_size`* bytes left in the file, or if the file was opened in text mode. In text mode, each carriage return-line feed pair `\r\n` is replaced with a single line feed character `\n`. Only the single line feed character is counted in the return value. The replacement does not affect the file pointer. +**`_read`** returns the number of bytes read, which might be less than *`buffer_size`* if there are fewer than *`buffer_size`* bytes left in the file, or if the file was opened in text mode. In text mode, each carriage return-line feed pair `\r\n` is replaced with a single line feed character `\n`. Only the single line feed character is counted in the return value. The replacement doesn't affect the file pointer. -If the function tries to read at end of file, it returns 0. If *`fd`* is not valid, the file isn't open for reading, or the file is locked, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets **`errno`** to **`EBADF`**. +If the function tries to read at end of file, it returns 0. If *`fd`* isn't valid, the file isn't open for reading, or the file is locked, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and sets `errno` to `EBADF`. -If *`buffer`* is `NULL`, or if *`buffer_size`* > **`INT_MAX`**, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns -1 and **`errno`** is set to **`EINVAL`**. +If *`buffer`* is `NULL`, or if *`buffer_size`* > `INT_MAX`, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns -1 and `errno` is set to `EINVAL`. -For more information about this and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -50,19 +50,19 @@ The **`_read`** function reads a maximum of *`buffer_size`* bytes into *`buffer` If the file was opened in text mode, the read terminates when **`_read`** encounters a CTRL+Z character, which is treated as an end-of-file indicator. Use [`_lseek`](lseek-lseeki64.md) to clear the end-of-file indicator. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_read`**|``| +| Routine | Required header | +|---|---| +| **`_read`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -119,8 +119,8 @@ Read 19 bytes from file ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)\ +[Low-level I/O](../low-level-i-o.md)\ [`_creat`, `_wcreat`](creat-wcreat.md)\ [`fread`](fread.md)\ [`_open`, `_wopen`](open-wopen.md)\ -[`_write`](write.md)\ +[`_write`](write.md) diff --git a/docs/c-runtime-library/reference/realloc-dbg.md b/docs/c-runtime-library/reference/realloc-dbg.md index f782ea0c5d4..7fe5026780c 100644 --- a/docs/c-runtime-library/reference/realloc-dbg.md +++ b/docs/c-runtime-library/reference/realloc-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["_realloc_dbg", "realloc_dbg"] helpviewer_keywords: ["reallocating memory blocks", "realloc_dbg function", "memory blocks, reallocating", "memory, reallocating", "_realloc_dbg function"] ms.assetid: 7c3cb780-51ed-4d9c-9929-cdde606d846a --- -# _realloc_dbg +# `_realloc_dbg` Reallocates a specified block of memory in the heap by moving and/or resizing the block (debug version only). @@ -28,54 +28,54 @@ void *_realloc_dbg( ### Parameters -*userData*
+*`userData`*\ Pointer to the previously allocated memory block. -*newSize*
+*`newSize`*\ Requested size for the reallocated block (bytes). -*blockType*
-Requested type for the reallocated block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type for the reallocated block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to the name of the source file that requested the **realloc** operation or **NULL**. +*`filename`*\ +Pointer to the name of the source file that requested the `realloc` operation or `NULL`. -*linenumber*
-Line number in the source file where the **realloc** operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where the `realloc` operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_realloc_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`linenumber`* parameters are only available when **`_realloc_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns **NULL**. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [realloc](realloc.md) function. +On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns `NULL`. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [`realloc`](realloc.md) function. ## Remarks -**_realloc_dbg** is a debug version of the [realloc](realloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_realloc_dbg** is reduced to a call to **realloc**. Both **realloc** and **_realloc_dbg** reallocate a memory block in the base heap, but **_realloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *filename*/*linenumber* information to determine the origin of allocation requests. +**`_realloc_dbg`** is a debug version of the [`realloc`](realloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_realloc_dbg`** is reduced to a call to `realloc`. Both `realloc` and **`_realloc_dbg`** reallocate a memory block in the base heap, but **`_realloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. -**_realloc_dbg** reallocates the specified memory block with slightly more space than the requested *newSize*. *newSize* might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. +**`_realloc_dbg`** reallocates the specified memory block with slightly more space than the requested *`newSize`*. *`newSize`* might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in both moving the original memory block to a different location in the heap, and changing the size of the memory block. If the memory block is moved, the contents of the original block are overwritten. -**_realloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_realloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails or if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_realloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_realloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## Example -See the example in the [_msize_dbg](msize-dbg.md) topic. +See the example in the [`_msize_dbg`](msize-dbg.md) article. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
-[_malloc_dbg](malloc-dbg.md)
+[Debug routines](../debug-routines.md)\ +[`_malloc_dbg`](malloc-dbg.md) diff --git a/docs/c-runtime-library/reference/realloc.md b/docs/c-runtime-library/reference/realloc.md index 4414bb12519..164743a6841 100644 --- a/docs/c-runtime-library/reference/realloc.md +++ b/docs/c-runtime-library/reference/realloc.md @@ -3,7 +3,7 @@ title: "realloc" description: "API reference for realloc(); which reallocates memory blocks." ms.date: "9/11/2020" api_name: ["realloc", "_o_realloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_brealloc", "_nrealloc", "realloc", "_frealloc"] @@ -31,13 +31,13 @@ Pointer to previously allocated memory block. *`size`*\ New size in bytes. -## Return Value +## Return value **`realloc`** returns a **`void`** pointer to the reallocated (and possibly moved) memory block. -If there is not enough available memory to expand the block to the given size, the original block is left unchanged, and **`NULL`** is returned. +If there isn't enough available memory to expand the block to the given size, the original block is left unchanged, and `NULL` is returned. -If *`size`* is zero, then the block pointed to by *`memblock`* is freed; the return value is **`NULL`**, and *`memblock`* is left pointing at a freed block. +If *`size`* is zero, then the block pointed to by *`memblock`* is freed; the return value is `NULL`, and *`memblock`* is left pointing at a freed block. The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. @@ -46,33 +46,33 @@ The return value points to a storage space that is suitably aligned for storage > [!NOTE] > **`realloc`** hasn't been updated to implement C17 behavior because the new behavior isn't compatible with the Windows operating system. -The **`realloc`** function changes the size of an allocated memory block. The *`memblock`* argument points to the beginning of the memory block. If *`memblock`* is **`NULL`**, **`realloc`** behaves the same way as **`malloc`** and allocates a new block of *`size`* bytes. If *`memblock`* is not **`NULL`**, it should be a pointer returned by a previous call to **`calloc`**, **`malloc`**, or **`realloc`**. +The **`realloc`** function changes the size of an allocated memory block. The *`memblock`* argument points to the beginning of the memory block. If *`memblock`* is `NULL`, **`realloc`** behaves the same way as **`malloc`** and allocates a new block of *`size`* bytes. If *`memblock`* isn't `NULL`, it should be a pointer returned by a previous call to **`calloc`**, **`malloc`**, or **`realloc`**. -The *`size`* argument gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a new memory location, the pointer returned by **`realloc`** is not guaranteed to be the pointer passed through the *`memblock`* argument. **`realloc`** does not zero newly allocated memory in the case of buffer growth. +The *`size`* argument gives the new size of the block, in bytes. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a new memory location, the pointer returned by **`realloc`** isn't guaranteed to be the pointer passed through the *`memblock`* argument. **`realloc`** doesn't zero newly allocated memory if there's buffer growth. -**`realloc`** sets **`errno`** to **`ENOMEM`** if the memory allocation fails or if the amount of memory requested exceeds **`_HEAP_MAXREQ`**. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`realloc`** sets `errno` to `ENOMEM` if the memory allocation fails or if the amount of memory requested exceeds `_HEAP_MAXREQ`. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -**`realloc`** calls **`malloc`** in order to use the C++ [`_set_new_mode`](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, **`malloc`** is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, **`malloc`** does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`realloc`** fails to allocate memory, **`malloc`** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call +**`realloc`** calls **`malloc`** in order to use the C++ [`_set_new_mode`](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, **`malloc`** is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, **`malloc`** doesn't call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`realloc`** fails to allocate memory, **`malloc`** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call ```C _set_new_mode(1); ``` -early in ones program, or link with NEWMODE.OBJ (see [Link Options](../../c-runtime-library/link-options.md)). +early in ones program, or link with NEWMODE.OBJ (see [Link options](../link-options.md)). -When the application is linked with a debug version of the C run-time libraries, **`realloc`** resolves to [`_realloc_dbg`](realloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`realloc`** resolves to [`_realloc_dbg`](realloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -**`realloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned is not aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). +**`realloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`realloc`**|`` and ``| +| Routine | Required header | +|---|---| +| **`realloc`** | `` and `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -123,7 +123,7 @@ Size of block after realloc of 1000 more longs: 8000 ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)\ +[Memory allocation](../memory-allocation.md)\ [`calloc`](calloc.md)\ [`free`](free.md)\ [`malloc`](malloc.md) diff --git a/docs/c-runtime-library/reference/recalloc-dbg.md b/docs/c-runtime-library/reference/recalloc-dbg.md index 471f9b30b94..66707f8e616 100644 --- a/docs/c-runtime-library/reference/recalloc-dbg.md +++ b/docs/c-runtime-library/reference/recalloc-dbg.md @@ -10,7 +10,7 @@ f1_keywords: ["recalloc_dbg", "_recalloc_dbg"] helpviewer_keywords: ["_recalloc_dbg function", "recalloc_dbg function"] ms.assetid: 43c3e9b2-be6d-4508-9b0f-3220c8a47ca3 --- -# _recalloc_dbg +# `_recalloc_dbg` Reallocates an array and initializes its elements to 0 (debug version only). @@ -29,54 +29,54 @@ void *_recalloc_dbg( ### Parameters -*userData*
+*`userData`*\ Pointer to the previously allocated memory block. -*number*
+*`number`*\ Requested number of memory blocks. -*size*
+*`size`*\ Requested size of each memory block (bytes). -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -For information about the allocation block types and how they are used, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +For information about the allocation block types and how they're used, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -*filename*
-Pointer to name of the source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of the source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in the source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in the source file where allocation operation was requested or `NULL`. -The *filename* and *linenumber* parameters are only available when **_recalloc_dbg** has been called explicitly or the [_CRTDBG_MAP_ALLOC](../../c-runtime-library/crtdbg-map-alloc.md) preprocessor constant has been defined. +The *`filename`* and *`linenumber`* parameters are only available when **`_recalloc_dbg`** has been called explicitly or the [`_CRTDBG_MAP_ALLOC`](../crtdbg-map-alloc.md) preprocessor constant has been defined. -## Return Value +## Return value -On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns **NULL**. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [_recalloc](recalloc.md) function. +On successful completion, this function either returns a pointer to the user portion of the reallocated memory block, calls the new handler function, or returns `NULL`. For a complete description of the return behavior, see the following Remarks section. For more information about how the new handler function is used, see the [`_recalloc`](recalloc.md) function. ## Remarks -**_recalloc_dbg** is a debug version of the [_recalloc](recalloc.md) function. When [_DEBUG](../../c-runtime-library/debug.md) is not defined, each call to **_recalloc_dbg** is reduced to a call to **_recalloc**. Both **_recalloc** and **_recalloc_dbg** reallocate a memory block in the base heap, but **_recalloc_dbg** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *filename*/*linenumber* information to determine the origin of allocation requests. +**`_recalloc_dbg`** is a debug version of the [`_recalloc`](recalloc.md) function. When [`_DEBUG`](../debug.md) isn't defined, each call to **`_recalloc_dbg`** is reduced to a call to `_recalloc`. Both `_recalloc` and **`_recalloc_dbg`** reallocate a memory block in the base heap, but **`_recalloc_dbg`** accommodates several debugging features: buffers on either side of the user portion of the block to test for leaks, a block type parameter to track specific allocation types, and *`filename`*/*`linenumber`* information to determine the origin of allocation requests. -**_recalloc_dbg** reallocates the specified memory block with slightly more space than the requested size (*number* * *size*) which might be greater or less than the size of the originally allocated memory block. The additional space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in moving the original memory block to a different location in the heap, as well as changing the size of the memory block. The user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. +**`_recalloc_dbg`** reallocates the specified memory block with slightly more space than the requested size (*`number`* * *`size`*) which might be greater or less than the size of the originally allocated memory block. The extra space is used by the debug heap manager to link the debug memory blocks and to provide the application with debug header information and overwrite buffers. The reallocation might result in both moving the original memory block to a different location in the heap, and changing the size of the memory block. The user portion of the block is filled with the value 0xCD and each of the overwrite buffers are filled with 0xFD. -**_recalloc_dbg** sets **errno** to **ENOMEM** if a memory allocation fails; **EINVAL** is returned if the amount of memory needed (including the overhead mentioned previously) exceeds **_HEAP_MAXREQ**. For information about this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_recalloc_dbg`** sets `errno` to `ENOMEM` if a memory allocation fails; `EINVAL` is returned if the amount of memory needed (including the overhead mentioned previously) exceeds `_HEAP_MAXREQ`. For information about this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). For information about the differences between calling a standard heap function and its debug version in a debug build of an application, see [Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions). +For information about how memory blocks are allocated, initialized, and managed in the debug version of the base heap, see [CRT debug heap details](../crt-debug-heap-details.md). For information about the differences between standard heap functions and debug versions, see [Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_recalloc_dbg**|\| +| Routine | Required header | +|---|---| +| **`_recalloc_dbg`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/recalloc.md b/docs/c-runtime-library/reference/recalloc.md index 1ffc2797175..09cd09dea34 100644 --- a/docs/c-runtime-library/reference/recalloc.md +++ b/docs/c-runtime-library/reference/recalloc.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: _recalloc" title: "_recalloc" +description: "Learn more about: _recalloc" ms.date: "4/2/2020" api_name: ["_recalloc", "_o__recalloc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-heap-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_recalloc", "recalloc"] helpviewer_keywords: ["_recalloc function", "recalloc function"] -ms.assetid: 1db8305a-3f03-418c-8844-bf9149f63046 --- -# _recalloc +# `_recalloc` -A combination of **realloc** and **calloc**. Reallocates an array in memory and initializes its elements to 0. +A combination of `realloc` and `calloc`. Reallocates an array in memory and initializes its elements to 0. ## Syntax ```C void *_recalloc( - void *memblock + void *memblock, size_t num, size_t size ); @@ -26,34 +25,34 @@ void *_recalloc( ### Parameters -*memblock*
+*`memblock`*\ Pointer to previously allocated memory block. -*number*
+*`number`*\ Number of elements. -*size*
+*`size`*\ Length in bytes of each element. -## Return Value +## Return value -**_recalloc** returns a **`void`** pointer to the reallocated (and possibly moved) memory block. +**`_recalloc`** returns a **`void`** pointer to the reallocated (and possibly moved) memory block. -If there is not enough available memory to expand the block to the given size, the original block is left unchanged, and **NULL** is returned. +If there isn't enough available memory to expand the block to the given size, the original block is left unchanged, and `NULL` is returned. -If the requested size is zero, then the block pointed to by *memblock* is freed; the return value is **NULL**, and *memblock* is left pointing at a freed block. +If the requested size is zero, then the block pointed to by *`memblock`* is freed; the return value is `NULL`, and *`memblock`* is left pointing at a freed block. -The return value points to a storage space that is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. +The return value points to a storage space that is suitably aligned for storage of any type of object. To get a pointer to a type other than **`void`**, use a type cast on the return value. ## Remarks -The **_recalloc** function changes the size of an allocated memory block. The *memblock* argument points to the beginning of the memory block. If *memblock* is **NULL**, **_recalloc** behaves the same way as [calloc](calloc.md) and allocates a new block of *number* * *size* bytes. Each element is initialized to 0. If *memblock* is not **NULL**, it should be a pointer returned by a previous call to **calloc**, [malloc](malloc.md), or [realloc](realloc.md). +The **`_recalloc`** function changes the size of an allocated memory block. The *`memblock`* argument points to the beginning of the memory block. If *`memblock`* is `NULL`, **`_recalloc`** behaves the same way as [`calloc`](calloc.md) and allocates a new block of *`number`* * *`size`* bytes. Each element is initialized to 0. If *`memblock`* isn't `NULL`, it should be a pointer returned by a previous call to `calloc`, [`malloc`](malloc.md), or [`realloc`](realloc.md). -Because the new block can be in a new memory location, the pointer returned by **_recalloc** is not guaranteed to be the pointer passed through the *memblock* argument. +Because the new block can be in a new memory location, the pointer returned by **`_recalloc`** isn't guaranteed to be the pointer passed through the *`memblock`* argument. -**_recalloc** sets **errno** to **ENOMEM** if the memory allocation fails or if the amount of memory requested exceeds **_HEAP_MAXREQ**. For information on this and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +**`_recalloc`** sets `errno` to `ENOMEM` if the memory allocation fails or if the amount of memory requested exceeds `_HEAP_MAXREQ`. For information on this and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -**recalloc** calls **realloc** in order to use the C++ [_set_new_mode](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, **realloc** is to call the new handler routine as set by [_set_new_handler](set-new-handler.md). By default, **realloc** does not call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **_recalloc** fails to allocate memory, **realloc** calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call +**`recalloc`** calls `realloc` in order to use the C++ [`_set_new_mode`](set-new-mode.md) function to set the new handler mode. The new handler mode indicates whether, on failure, `realloc` is to call the new handler routine as set by [`_set_new_handler`](set-new-handler.md). By default, `realloc` doesn't call the new handler routine on failure to allocate memory. You can override this default behavior so that, when **`_recalloc`** fails to allocate memory, `realloc` calls the new handler routine in the same way that the **`new`** operator does when it fails for the same reason. To override the default, call ```C _set_new_mode(1); @@ -61,25 +60,25 @@ _set_new_mode(1); early in the program, or link with NEWMODE.OBJ. -When the application is linked with a debug version of the C run-time libraries, **_recalloc** resolves to [_recalloc_dbg](recalloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT Debug Heap](/visualstudio/debugger/crt-debug-heap-details). +When the application is linked with a debug version of the C run-time libraries, **`_recalloc`** resolves to [`_recalloc_dbg`](recalloc-dbg.md). For more information about how the heap is managed during the debugging process, see [The CRT debug heap](../crt-debug-heap-details.md). -**_recalloc** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned is not aliased. For more information, see [noalias](../../cpp/noalias.md) and [restrict](../../cpp/restrict.md). +**`_recalloc`** is marked `__declspec(noalias)` and `__declspec(restrict)`, meaning that the function is guaranteed not to modify global variables, and that the pointer returned isn't aliased. For more information, see [`noalias`](../../cpp/noalias.md) and [`restrict`](../../cpp/restrict.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_recalloc**|\ and \| +| Routine | Required header | +|---|---| +| **`_recalloc`** | \ and \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Memory Allocation](../../c-runtime-library/memory-allocation.md)
-[_recalloc_dbg](recalloc-dbg.md)
-[_aligned_recalloc](aligned-recalloc.md)
-[_aligned_offset_recalloc](aligned-offset-recalloc.md)
-[free](free.md)
-[Link Options](../../c-runtime-library/link-options.md)
+[Memory allocation](../memory-allocation.md)\ +[`_recalloc_dbg`](recalloc-dbg.md)\ +[`_aligned_recalloc`](aligned-recalloc.md)\ +[`_aligned_offset_recalloc`](aligned-offset-recalloc.md)\ +[`free`](free.md)\ +[Link options](../link-options.md) diff --git a/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md b/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md index 2b04b53cc64..807e001cd3c 100644 --- a/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md +++ b/docs/c-runtime-library/reference/remainder-remainderf-remainderl.md @@ -1,16 +1,15 @@ --- title: "remainder, remainderf, remainderl" description: "API reference for remainder, remainderf, and remainderl; which compute the remainder of the quotient of two floating-point values, rounded to the nearest integral value." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["remainderl", "remainder", "remainderf", "_o_remainder", "_o_remainderf", "_o_remainderl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["remainderf", "remainder", "remainderl"] helpviewer_keywords: ["remainderf", "remainderl", "remainder"] -ms.assetid: 5f721fb3-8b78-4597-9bc0-ca9bcd1f1d0e --- -# remainder, remainderf, remainderl +# `remainder`, `remainderf`, `remainderl` Computes the remainder of the quotient of two floating-point values, rounded to the nearest integral value. @@ -20,7 +19,7 @@ Computes the remainder of the quotient of two floating-point values, rounded to double remainder( double x, double y ); float remainderf( float x, float y ); long double remainderl( long double x, long double y ); -#define remainder(X, Y) // Requires C11 or higher +#define remainder(X, Y) // Requires C11 or later float remainder( float x, float y ); /* C++ only */ long double remainder( long double x, long double y ); /* C++ only */ @@ -28,34 +27,34 @@ long double remainder( long double x, long double y ); /* C++ only */ ### Parameters -*x*\ +*`x`*\ The numerator. -*y*\ +*`y`*\ The denominator. -## Return Value +## Return value -The floating-point remainder of *x* / *y*. If the value of *y* is 0.0, **remainder** returns a quiet NaN. For information about the representation of a quiet NaN by the **printf** family, see [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md). +The floating-point remainder of *`x`* / *`y`*. If the value of *`y`* is 0.0, **`remainder`** returns a quiet NaN. For information about the representation of a quiet NaN by the `printf` family, see [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md). ## Remarks -The **remainder** functions calculate the floating-point remainder `r` of `x / y` such that `x = n * y + r`, where `n` is the integer nearest in value to `x / y` and `n` is even whenever `|n - x / y| = 1/2`. When `r = 0`, `r` has the same sign as *`x`*. +The **`remainder`** functions calculate the floating-point remainder `r` of `x / y` such that `x = n * y + r`, where `n` is the integer nearest in value to `x / y` and `n` is even whenever `|n - x / y| = 1/2`. When `r = 0`, `r` has the same sign as *`x`*. -Because C++ allows overloading, you can call overloads of **remainder** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **remainder** always takes two **`double`** arguments and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`remainder`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`remainder`** always takes two **`double`** arguments and returns a **`double`**. -If you use the \ `remainder()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `remainder()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------|-| -|**remainder**, **remainderf**, **remainderl**|\|\ or \| -|**remainder** macro | \ || +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`remainder`**, **`remainderf`**, **`remainderl`** | \ | \ or \ | +| **`remainder`** macro | \ | | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -81,8 +80,8 @@ The remainder of -10.00 / 3.00 is -1.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[ldiv, lldiv](./div.md)\ -[imaxdiv](imaxdiv.md)\ -[fmod, fmodf](fmod-fmodf.md)\ -[remquo, remquof, remquol](remquo-remquof-remquol.md) +[Math and floating-point support](../floating-point-support.md)\ +[`ldiv`, `lldiv`](./div.md)\ +[`imaxdiv`](imaxdiv.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`remquo`, `remquof`, `remquol`](remquo-remquof-remquol.md) diff --git a/docs/c-runtime-library/reference/remove-wremove.md b/docs/c-runtime-library/reference/remove-wremove.md index 2a45f9277fe..d2d7cac1537 100644 --- a/docs/c-runtime-library/reference/remove-wremove.md +++ b/docs/c-runtime-library/reference/remove-wremove.md @@ -3,7 +3,7 @@ description: "Learn more about: remove, _wremove" title: "remove, _wremove" ms.date: "4/2/2020" api_name: ["_wremove", "remove", "_o__wremove", "_o_remove"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["remove", "_wremove", "_tremove"] @@ -29,36 +29,36 @@ int _wremove( *`path`*\ Path of file to be removed. -## Return Value +## Return value -Each of these functions returns 0 if the file is successfully deleted. Otherwise, it returns -1 and sets **`errno`** either to **`EACCES`** to indicate that the path specifies a read-only file, specifies a directory, or the file is open, or to **`ENOENT`** to indicate that the filename or path wasn't found. +Each of these functions returns 0 if the file is successfully deleted. Otherwise, it returns -1 and sets `errno` either to `EACCES` to indicate that the path specifies a read-only file, specifies a directory, or the file is open, or to `ENOENT` to indicate that the filename or path wasn't found. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these and other return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`remove`** function deletes the file specified by *`path`.* **`_wremove`** is a wide-character version of **`_remove`**; the *`path`* argument to **`_wremove`** is a wide-character string. **`_wremove`** and **`_remove`** behave identically otherwise. All handles to a file must be closed before it can be deleted. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tremove`**|**`remove`**|**`remove`**|**`_wremove`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tremove` | **`remove`** | **`remove`** | **`_wremove`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`remove`**|`` or ``| -|**`_wremove`**|`` or ``| +| Routine | Required header | +|---|---| +| **`remove`** | `` or `` | +| **`_wremove`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -83,7 +83,7 @@ int main( void ) This file will be deleted. ``` -### Sample Output +### Sample output ```Output Deleted 'CRT_REMOVE.TXT' @@ -91,5 +91,5 @@ Deleted 'CRT_REMOVE.TXT' ## See also -[File Handling](../../c-runtime-library/file-handling.md)\ +[File handling](../file-handling.md)\ [`_unlink`, `_wunlink`](unlink-wunlink.md) diff --git a/docs/c-runtime-library/reference/remquo-remquof-remquol.md b/docs/c-runtime-library/reference/remquo-remquof-remquol.md index dbf6489667a..d756c829f01 100644 --- a/docs/c-runtime-library/reference/remquo-remquof-remquol.md +++ b/docs/c-runtime-library/reference/remquo-remquof-remquol.md @@ -1,18 +1,17 @@ --- title: "remquo, remquof, remquol" -description: "API reference for remquo, remquof, and remquol; which compute the remainder of two integer values, and stores an integer value with the sign and approximate magnitude of the quotient in a location that's specified in a parameter." -ms.date: "9/1/2020" +description: "API reference for remquo, remquof, and remquol, which compute the remainder of two integer values, and store the sign and approximate magnitude of the quotient." +ms.date: 9/1/2020 api_name: ["remquof", "remquo", "remquol", "_o_remquo", "_o_remquof", "_o_remquol"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["remquof", "remquol", "remquo"] helpviewer_keywords: ["remquol function", "remquof function", "remquo function"] -ms.assetid: a1d3cb8b-8027-4cd3-8deb-04eb17f299fc --- -# remquo, remquof, remquol +# `remquo`, `remquof`, `remquol` -Computes the remainder of two integer values, and stores an integer value with the sign and approximate magnitude of the quotient in a location that's specified in a parameter. +Computes the remainder of two integer values, and stores an integer value with the sign and approximate magnitude of the quotient in a parameter. ## Syntax @@ -20,7 +19,7 @@ Computes the remainder of two integer values, and stores an integer value with t double remquo( double numer, double denom, int* quo ); float remquof( float numer, float denom, int* quo ); long double remquol( long double numer, long double denom, int* quo ); -#define remquo(X, Y, INT_PTR) // Requires C11 or higher +#define remquo(X, Y, INT_PTR) // Requires C11 or later float remquo( float numer, float denom, int* quo ); /* C++ only */ long double remquo( long double numer, long double denom, int* quo ); /* C++ only */ @@ -28,37 +27,37 @@ long double remquo( long double numer, long double denom, int* quo ); /* C++ onl ### Parameters -*numer*\ +*`numer`*\ The numerator. -*denom*\ +*`denom`*\ The denominator. -*quo*\ +*`quo`*\ A pointer to an integer to store a value that has the sign and approximate magnitude of the quotient. -## Return Value +## Return value -**remquo** returns the floating-point remainder of *x* / *y*. If the value of *y* is 0.0, **remquo** returns a quiet NaN. For information about the representation of a quiet NaN by the **printf** family, see [printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md). +**`remquo`** returns the floating-point remainder of *`x`* / *`y`*. If the value of *`y`* is 0.0, **`remquo`** returns a quiet NaN. For information about the representation of a quiet NaN by the `printf` family, see [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md). ## Remarks -The **remquo** function calculates the floating-point remainder *f* of *x* / *y* such that *x* = *i* \* *y* + *f*, where *i* is an integer, *f* has the same sign as *x*, and the absolute value of *f* is less than the absolute value of *y*. +The **`remquo`** function calculates the floating-point remainder `f` of *`x`* / *`y`* such that *`x`* = `n` \* *`y`* + *`f`*, where `n` is an integer, `f` has the same sign as *`x`*, and the absolute value of `f` is less than the absolute value of *`y`*. -C++ allows overloading, so you can call overloads of **remquo** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **remquo** always takes two **`double`** arguments and returns a **`double`**. +C++ allows overloading, so you can call overloads of **`remquo`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`remquo`** always takes two **`double`** arguments and returns a **`double`**. -If you use the \ `remquo()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `remquo()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|Required header (C)|Required header (C++)| -|--------------|---------------------|-| -|**remquo**, **remquof**, **remquol**|\|\ or \| -|**remquo** macro | \ || +| Function | Required header (C) | Required header (C++) | +|---|---|---| +| **`remquo`**, **`remquof`**, **`remquol`** | \ | \ or \ | +| **`remquo`** macro | \ | | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,8 +86,8 @@ Approximate signed quotient is -3 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ldiv, lldiv](./div.md)
-[imaxdiv](imaxdiv.md)
-[fmod, fmodf](fmod-fmodf.md)
-[remainder, remainderf, remainderl](remainder-remainderf-remainderl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ldiv`, `lldiv`](./div.md)\ +[`imaxdiv`](imaxdiv.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`remainder`, `remainderf`, `remainderl`](remainder-remainderf-remainderl.md) diff --git a/docs/c-runtime-library/reference/rename-wrename.md b/docs/c-runtime-library/reference/rename-wrename.md index b5b29e4e1cf..bfab5461de7 100644 --- a/docs/c-runtime-library/reference/rename-wrename.md +++ b/docs/c-runtime-library/reference/rename-wrename.md @@ -3,7 +3,7 @@ description: "Learn more about: rename, _wrename" title: "rename, _wrename" ms.date: "4/2/2020" api_name: ["rename", "_wrename", "_o__wrename", "_o_rename"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wrename", "_trename", "Rename"] @@ -29,50 +29,50 @@ int _wrename( ### Parameters -*`oldname`*
+*`oldname`*\ Pointer to old name. -*`newname`*
+*`newname`*\ Pointer to new name. -## Return Value +## Return value -Each of these functions returns 0 if it is successful. On an error, the function returns a nonzero value and sets **`errno`** to one of the following values: +Each of these functions returns 0 if it's successful. On an error, the function returns a nonzero value and sets `errno` to one of the following values: -|errno value|Condition| -|-|-| -| **`EACCES`** | File or directory specified by *`newname`* already exists or could not be created (invalid path); or *`oldname`* is a directory and *`newname`* specifies a different path. | -| **`ENOENT`** | File or path specified by *`oldname`* not found. | -| **`EINVAL`** | Name contains invalid characters. | +| `errno` value | Condition | +|---|---| +| `EACCES` | File or directory specified by *`newname`* already exists or couldn't be created (invalid path); or *`oldname`* is a directory and *`newname`* specifies a different path. | +| `ENOENT` | File or path specified by *`oldname`* not found. | +| `EINVAL` | Name contains invalid characters. | -For other possible return values, see [`_doserrno`, `_errno`, `syserrlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For other possible return values, see [`_doserrno`, `_errno`, `syserrlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`rename`** function renames the file or directory specified by *`oldname`* to the name given by *`newname`*. The old name must be the path of an existing file or directory. The new name must not be the name of an existing file or directory. You can use **`rename`** to move a file from one directory or device to another by giving a different path in the *`newname`* argument. However, you cannot use **`rename`** to move a directory. Directories can be renamed, but not moved. +The **`rename`** function renames the file or directory specified by *`oldname`* to the name given by *`newname`*. The old name must be the path of an existing file or directory. The new name must not be the name of an existing file or directory. You can use **`rename`** to move a file from one directory or device to another by giving a different path in the *`newname`* argument. However, you can't use **`rename`** to move a directory. Directories can be renamed, but not moved. **`_wrename`** is a wide-character version of **`_rename`**; the arguments to **`_wrename`** are wide-character strings. **`_wrename`** and **`_rename`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_trename`**|**`rename`**|**`rename`**|**`_wrename`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_trename` | **`rename`** | **`rename`** | **`_wrename`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`rename`**|`` or ``| -|**`_wrename`**|`` or ``| +| Routine | Required header | +|---|---| +| **`rename`** | `` or `` | +| **`_wrename`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -108,4 +108,4 @@ File 'CRT_RENAMER.OBJ' renamed to 'CRT_RENAMER.JBO' ## See also -[File Handling](../../c-runtime-library/file-handling.md)
+[File handling](../file-handling.md) diff --git a/docs/c-runtime-library/reference/resetstkoflw.md b/docs/c-runtime-library/reference/resetstkoflw.md index f79dceafceb..89923dcc009 100644 --- a/docs/c-runtime-library/reference/resetstkoflw.md +++ b/docs/c-runtime-library/reference/resetstkoflw.md @@ -3,7 +3,7 @@ description: "Learn more about: _resetstkoflw" title: "_resetstkoflw" ms.date: "1/14/2021" api_name: ["_resetstkoflw", "_o__resetstkoflw"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["resetstkoflw", "_resetstkoflw"] @@ -23,7 +23,7 @@ Recovers from stack overflow. int _resetstkoflw( void ); ``` -## Return Value +## Return value Nonzero if the function succeeds, zero if it fails. @@ -31,27 +31,27 @@ Nonzero if the function succeeds, zero if it fails. The **`_resetstkoflw`** function recovers from a stack overflow condition, allowing a program to continue instead of failing with a fatal exception error. If the **`_resetstkoflw`** function isn't called, there are no guard pages after the previous exception. The next time that there's a stack overflow, there are no exceptions at all and the process terminates without warning. -If a thread in an application causes an **`EXCEPTION_STACK_OVERFLOW`** exception, the thread has left its stack in a damaged state. This is in contrast to other exceptions such as **`EXCEPTION_ACCESS_VIOLATION`** or **`EXCEPTION_INT_DIVIDE_BY_ZERO`**, where the stack isn't damaged. The stack is set to an arbitrarily small value when the program is first loaded. The stack then grows on demand to meet the needs of the thread. This is implemented by placing a page with PAGE_GUARD access at the end of the current stack. For more information, see [Creating Guard Pages](/windows/win32/Memory/creating-guard-pages). +If a thread in an application causes an `EXCEPTION_STACK_OVERFLOW` exception, the thread has left its stack in a damaged state. This exception is different from other exceptions such as `EXCEPTION_ACCESS_VIOLATION` or `EXCEPTION_INT_DIVIDE_BY_ZERO`, where the stack isn't damaged. The stack is set to an arbitrarily small value when the program is first loaded. The stack then grows on demand to meet the needs of the thread. On-demand growth is implemented by placing a page with `PAGE_GUARD` access at the end of the current stack. For more information, see [Creating guard pages](/windows/win32/Memory/creating-guard-pages). When the code causes the stack pointer to point to an address on this page, an exception occurs and the system does the following three things: -- Removes the PAGE_GUARD protection on the guard page so that the thread can read and write data to the memory. +- Removes the `PAGE_GUARD` protection on the guard page so that the thread can read and write data to the memory. - Allocates a new guard page that is located one page below the last one. - Reruns the instruction that raised the exception. -In this way, the system can increase the size of the stack for the thread automatically. Each thread in a process has a maximum stack size. The stack size is set at compile time by the [`/STACK` (Stack Allocations)](../../build/reference/stack-stack-allocations.md), or by the [`STACKSIZE`](../../build/reference/stacksize.md) statement in the `.def` file for the project. +In this way, the system can increase the size of the stack for the thread automatically. Each thread in a process has a maximum stack size. The stack size is set at compile time by the [`/STACK` (Stack Allocations)](../../build/reference/stack-stack-allocations.md) option, or by the [`STACKSIZE`](../../build/reference/stacksize.md) statement in the `.def` file for the project. When this maximum stack size is exceeded, the system does the following three things: - Removes the PAGE_GUARD protection on the guard page, as previously described. -- Tries to allocate a new guard page below the last one. However, this fails because the maximum stack size has been exceeded. +- Tries to allocate a new guard page below the last one. However, the allocation fails because the maximum stack size has been exceeded. - Raises an exception so that the thread can handle it in the exception block. -At that point, the stack no longer has a guard page. The next time that the program grows the stack all the way to the end, where there should be a guard page, the program writes beyond the end of the stack and causes an access violation. +At that point, the stack no longer has a guard page. The next time the program grows the stack to where it writes beyond the end of the stack, it causes an access violation. Call **`_resetstkoflw`** to restore the guard page whenever recovery is done after a stack overflow exception. This function can be called from inside the main body of an **`__except`** block or outside an **`__except`** block. However, there are some restrictions on when it should be used. **`_resetstkoflw`** shouldn't be called from: @@ -69,23 +69,23 @@ At these points, the stack isn't yet sufficiently unwound. Stack overflow exceptions are generated as structured exceptions, not C++ exceptions, so **`_resetstkoflw`** isn't useful in an ordinary **`catch`** block because it won't catch a stack overflow exception. However, if [`_set_se_translator`](set-se-translator.md) is used to implement a structured exception translator that throws C++ exceptions (as in the second example), a stack overflow exception results in a C++ exception that can be handled by a C++ catch block. -It isn't safe to call **`_resetstkoflw`** in a C++ catch block that is reached from an exception thrown by the structured exception translator function. In this case, the stack space isn't freed and the stack pointer isn't reset until outside the catch block, even though destructors have been called for any destructible objects before the catch block. This function shouldn't be called until the stack space is freed and the stack pointer has been reset. Therefore, it should be called only after exiting the catch block. As little stack space as possible should be used in the catch block because a stack overflow that occurs in the catch block that is itself attempting to recover from a previous stack overflow isn't recoverable and can cause the program to stop responding as the overflow in the catch block triggers an exception that itself is handled by the same catch block. +It isn't safe to call **`_resetstkoflw`** in a C++ catch block that is reached from an exception thrown by the structured exception translator function. In this case, the stack space isn't freed and the stack pointer isn't reset until outside the catch block, even though destructors have been called for any destructible objects before the catch block. This function shouldn't be called until the stack space is freed and the stack pointer has been reset. Therefore, it should be called only after exiting the catch block. As little stack space as possible should be used in the catch block. A stack overflow that occurs in the catch block that is itself attempting to recover from a previous stack overflow isn't recoverable. It can cause the program to stop responding, as the overflow in the catch block triggers an exception that itself is handled by the same catch block. -There are situations where **`_resetstkoflw`** can fail even if used in a correct location, such as within an **`__except`** block. If, even after unwinding the stack, there's still not enough stack space left to execute **`_resetstkoflw`** without writing into the last page of the stack, **`_resetstkoflw`** fails to reset the last page of the stack as the guard page and returns 0, indicating failure. Safe usage of this function should include checking the return value instead of assuming that the stack is safe to use. +There are situations where **`_resetstkoflw`** can fail even if used in a correct location, such as within an **`__except`** block. There may not be enough stack space left to execute **`_resetstkoflw`** without writing into the last page of the stack, even after unwinding the stack. Then, **`_resetstkoflw`** fails to reset the last page of the stack as the guard page, and returns 0, indicating failure. Safe usage of this function should include checking the return value instead of assuming that the stack is safe to use. -Structured exception handling won't catch a **`STATUS_STACK_OVERFLOW`** exception when the application is compiled with **`/clr`** (see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md)). +Structured exception handling won't catch a `STATUS_STACK_OVERFLOW` exception when the application is compiled with **`/clr`** (see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md)). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_resetstkoflw`**|\| +| Routine | Required header | +|---|---| +| **`_resetstkoflw`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -**Libraries:** All versions of the [CRT Library Features](../../c-runtime-library/crt-library-features.md). +**Libraries:** All versions of the [CRT library features](../crt-library-features.md). ## Example @@ -285,4 +285,4 @@ Recovered from stack overflow and allocated 100,000 bytes using _alloca. ## See also -[`_alloca`](alloca.md)
+[`_alloca`](alloca.md) diff --git a/docs/c-runtime-library/reference/rewind.md b/docs/c-runtime-library/reference/rewind.md index 2ff050d3aaf..5ece09a4f8e 100644 --- a/docs/c-runtime-library/reference/rewind.md +++ b/docs/c-runtime-library/reference/rewind.md @@ -3,14 +3,14 @@ description: "Learn more about: rewind" title: "rewind" ms.date: "4/2/2020" api_name: ["rewind", "_o_rewind"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["rewind"] helpviewer_keywords: ["rewind function", "repositioning file pointers", "file pointers [C++], repositioning", "file pointers [C++]"] ms.assetid: 1a460ce1-28d8-4b5e-83a6-633dca29c28a --- -# rewind +# `rewind` Repositions the file pointer to the beginning of a file. @@ -24,36 +24,36 @@ void rewind( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. ## Remarks -The **rewind** function repositions the file pointer associated with *stream* to the beginning of the file. A call to **rewind** is similar to +The **`rewind`** function repositions the file pointer associated with *`stream`* to the beginning of the file. A call to **`rewind`** is similar to -**(void) fseek(** _stream_**, 0L, SEEK_SET );** +`(void) fseek(stream, 0L, SEEK_SET );` -However, unlike [fseek](fseek-fseeki64.md), **rewind** clears the error indicators for the stream as well as the end-of-file indicator. Also, unlike [fseek](fseek-fseeki64.md), **rewind** does not return a value to indicate whether the pointer was successfully moved. +However, unlike [`fseek`](fseek-fseeki64.md), **`rewind`** clears both the error indicators for the stream and the end-of-file indicator. Also, unlike [`fseek`](fseek-fseeki64.md), **`rewind`** doesn't return a value to indicate whether the pointer was successfully moved. -To clear the keyboard buffer, use **rewind** with the stream **stdin**, which is associated with the keyboard by default. +To clear the keyboard buffer, use **`rewind`** with the stream `stdin`, which is associated with the keyboard by default. -If stream is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns and **errno** is set to **EINVAL**. +If stream is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns, and `errno` is set to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**rewind**|\| +| Routine | Required header | +|---|---| +| **`rewind`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -97,4 +97,4 @@ The values read are: 1 and -37 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
+[Stream I/O](../stream-i-o.md) diff --git a/docs/c-runtime-library/reference/rint-rintf-rintl.md b/docs/c-runtime-library/reference/rint-rintf-rintl.md index d5a9617c5b3..ac703cb135f 100644 --- a/docs/c-runtime-library/reference/rint-rintf-rintl.md +++ b/docs/c-runtime-library/reference/rint-rintf-rintl.md @@ -1,16 +1,15 @@ --- title: "rint, rintf, rintl" description: "API reference for rint, rintf, and rintl; which round a floating-point value to the nearest integer in floating-point format." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["rintf", "rintl", "rint", "_o_rint", "_o_rintf", "_o_rintl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["rintf", "rintl", "rint"] helpviewer_keywords: ["rintf function", "rint function", "rintl function"] -ms.assetid: 312ae3e6-278c-459a-9393-11b8f87d9184 --- -# rint, rintf, rintl +# `rint`, `rintf`, `rintl` Rounds a floating-point value to the nearest integer in floating-point format. @@ -20,7 +19,7 @@ Rounds a floating-point value to the nearest integer in floating-point format. double rint( double x ); float rintf( float x ); long double rintl( long double x ); -#define rint(X) // Requires C11 or higher +#define rint(X) // Requires C11 or later float rint( float x ); // C++ only long double rint( long double x ); // C++ only @@ -28,34 +27,34 @@ long double rint( long double x ); // C++ only ### Parameters -*x*\ +*`x`*\ The floating-point value to round. -## Return Value +## Return value -The **rint** functions return a floating-point value that represents the nearest integer to *x*. Halfway values are rounded according to the current setting of the floating-point rounding mode, the same as the **nearbyint** functions. Unlike the **nearbyint** functions, the **rint** functions may raise the **FE_INEXACT** floating-point exception if the result differs in value from the argument. There's no error return. +The **`rint`** functions return a floating-point value that represents the nearest integer to *`x`*. Halfway values are rounded according to the current setting of the floating-point rounding mode, the same as the `nearbyint` functions. Unlike the `nearbyint` functions, the **`rint`** functions may raise the `FE_INEXACT` floating-point exception if the result differs in value from the argument. There's no error return. -|Input|SEH Exception|**_matherr** Exception| -|-----------|-------------------|--------------------------| -|± ∞, QNAN, IND|none|none| -|Denormals|EXCEPTION_FLT_UNDERFLOW|none| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± INF, QNaN, IND | none | none | +| Denormals | `EXCEPTION_FLT_UNDERFLOW` | none | ## Remarks -Because C++ allows overloading, you can call overloads of **rint** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **rint** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`rint`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the \ macro to call this function, **`rint`** always takes and returns a **`double`**. -If you use the \ `rint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `rint()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**rint**, **rintf**, **rintl**|\|\| -|**rint** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`rint`**, **`rintf`**, **`rintl`** | \ | \ | +| **`rint`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -95,11 +94,11 @@ rintl(-2.500000) is -3 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[ceil, ceilf, ceill](ceil-ceilf-ceill.md)
-[floor, floorf, floorl](floor-floorf-floorl.md)
-[fmod, fmodf](fmod-fmodf.md)
-[lrint, lrintf, lrintl, llrint, llrintf, llrintl](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)
-[lround, lroundf, lroundl, llround, llroundf, llroundl](lround-lroundf-lroundl-llround-llroundf-llroundl.md)
-[nearbyint, nearbyintf, nearbyintl](nearbyint-nearbyintf-nearbyintl1.md)
-[rint](rint-rintf-rintl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`fmod`, `fmodf`](fmod-fmodf.md)\ +[`lrint`, `lrintf`, `lrintl`, `llrint`, `llrintf`, `llrintl`](lrint-lrintf-lrintl-llrint-llrintf-llrintl.md)\ +[`lround`, `lroundf`, `lroundl`, `llround`, `llroundf`, `llroundl`](lround-lroundf-lroundl-llround-llroundf-llroundl.md)\ +[`nearbyint`, `nearbyintf`, `nearbyintl`](nearbyint-nearbyintf-nearbyintl1.md)\ +[`rint`](rint-rintf-rintl.md) diff --git a/docs/c-runtime-library/reference/rmdir-wrmdir.md b/docs/c-runtime-library/reference/rmdir-wrmdir.md index 1b03190bfb6..ea688d79957 100644 --- a/docs/c-runtime-library/reference/rmdir-wrmdir.md +++ b/docs/c-runtime-library/reference/rmdir-wrmdir.md @@ -3,14 +3,14 @@ description: "Learn more about: _rmdir, _wrmdir" title: "_rmdir, _wrmdir" ms.date: "4/2/2020" api_name: ["_wrmdir", "_rmdir", "_o__rmdir", "_o__wrmdir"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["trmdir", "_trmdir", "wrmdir", "_rmdir", "_wrmdir"] helpviewer_keywords: ["_rmdir function", "directories [C++], deleting", "rmdir function", "directories [C++], removing", "trmdir function", "_trmdir function", "_wrmdir function", "wrmdir function"] ms.assetid: 652c2a5a-b0ac-4493-864e-1edf484333c5 --- -# _rmdir, _wrmdir +# `_rmdir`, `_wrmdir` Deletes a directory. @@ -27,54 +27,54 @@ int _wrmdir( ### Parameters -*dirname*
+*`dirname`*\ Path of the directory to be removed. -## Return Value +## Return value -Each of these functions returns 0 if the directory is successfully deleted. A return value of -1 indicates an error and **errno** is set to one of the following values: +Each of these functions returns 0 if the directory is successfully deleted. A return value of -1 indicates an error and `errno` is set to one of the following values: -|errno value|Condition| -|-|-| -| **ENOTEMPTY** | Given path is not a directory, the directory is not empty, or the directory is either the current working directory or the root directory. | -| **ENOENT** | Path is invalid. | -| **EACCES** | A program has an open handle to the directory. | +| `errno` value | Condition | +|---|---| +| `ENOTEMPTY` | Given path isn't a directory, the directory isn't empty, or the directory is either the current working directory or the root directory. | +| `ENOENT` | Path is invalid. | +| `EACCES` | A program has an open handle to the directory. | -For more information about these and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_rmdir** function deletes the directory specified by *dirname*. The directory must be empty, and it must not be the current working directory or the root directory. +The **`_rmdir`** function deletes the directory specified by *`dirname`*. The directory must be empty, and it must not be the current working directory or the root directory. -**_wrmdir** is a wide-character version of **_rmdir**; the *dirname* argument to **_wrmdir** is a wide-character string. **_wrmdir** and **_rmdir** behave identically otherwise. +**`_wrmdir`** is a wide-character version of **`_rmdir`**; the *`dirname`* argument to **`_wrmdir`** is a wide-character string. **`_wrmdir`** and **`_rmdir`** behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_trmdir**|**_rmdir**|**_rmdir**|**_wrmdir**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_trmdir` | **`_rmdir`** | **`_rmdir`** | **`_wrmdir`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_rmdir**|\| -|**_wrmdir**|\ or \| +| Routine | Required header | +|---|---| +| **`_rmdir`** | \ | +| **`_wrmdir`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example -See the example for [_mkdir](mkdir-wmkdir.md). +See the example for [`_mkdir`](mkdir-wmkdir.md). ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_chdir, _wchdir](chdir-wchdir.md)
-[_mkdir, _wmkdir](mkdir-wmkdir.md)
+[Directory control](../directory-control.md)\ +[`_chdir`, `_wchdir`](chdir-wchdir.md)\ +[`_mkdir`, `_wmkdir`](mkdir-wmkdir.md) diff --git a/docs/c-runtime-library/reference/rmdir.md b/docs/c-runtime-library/reference/rmdir.md index 0d5d7ec1572..856ee7479b5 100644 --- a/docs/c-runtime-library/reference/rmdir.md +++ b/docs/c-runtime-library/reference/rmdir.md @@ -10,8 +10,8 @@ f1_keywords: ["rmdir"] helpviewer_keywords: ["rmdir function"] ms.assetid: 03a0aff4-f66c-42a9-bee9-84c46f994952 --- -# rmdir +# `rmdir` -The Microsoft-implemented POSIX function name `rmdir` is a deprecated alias for the [_rmdir](rmdir-wrmdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `rmdir` is a deprecated alias for the [`_rmdir`](rmdir-wrmdir.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_rmdir](rmdir-wrmdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_rmdir`](rmdir-wrmdir.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/rmtmp.md b/docs/c-runtime-library/reference/rmtmp.md index cf26adf0e9c..7fac6abd1a6 100644 --- a/docs/c-runtime-library/reference/rmtmp.md +++ b/docs/c-runtime-library/reference/rmtmp.md @@ -1,55 +1,53 @@ --- -description: "Learn more about: _rmtmp" title: "_rmtmp" +description: "Learn more about: _rmtmp" ms.date: "4/2/2020" api_name: ["_rmtmp", "_o__rmtmp"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_rmtmp"] helpviewer_keywords: ["removing temporary files", "_rmtmp function", "files [C++], temporary", "rmtmp function", "files [C++], removing", "temporary files [C++], removing"] -ms.assetid: 7419501e-2587-4f2a-b469-0dca07f84736 --- -# _rmtmp +# `_rmtmp` Removes temporary files. ## Syntax ```C - int _rmtmp( void ); ``` -## Return Value +## Return value -**_rmtmp** returns the number of temporary files closed and deleted. +**`_rmtmp`** returns the number of temporary files closed and deleted. ## Remarks -The **_rmtmp** function cleans up all temporary files in the current directory. The function removes only those files created by **tmpfile**; use it only in the same directory in which the temporary files were created. +The **`_rmtmp`** function cleans up all temporary files in the current directory. The function removes only those files created by `tmpfile`; use it only in the same directory in which the temporary files were created. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_rmtmp**|\| +| Routine | Required header | +|---|---| +| **`_rmtmp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example -See the example for [tmpfile](tmpfile.md). +See the example for [`tmpfile`](tmpfile.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_flushall](flushall.md)
-[tmpfile](tmpfile.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
+[Stream I/O](../stream-i-o.md)\ +[`_flushall`](flushall.md)\ +[`tmpfile`](tmpfile.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) diff --git a/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md b/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md index f78d40eab9e..c095e8cadae 100644 --- a/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md +++ b/docs/c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md @@ -8,16 +8,14 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_rotr64", "rotl64", "_rotl64", "rotr64", "rotr", "_rotr", "_rotl", "rotl"] helpviewer_keywords: ["rotl64 function", "_rotl function", "rotr function", "rotr64 function", "_rotr function", "rotl function", "_rotl64 function", "rotating bits", "_rotr64 function", "bits, rotating"] -ms.assetid: cfce439b-366f-4584-8ab1-d527b13fcfc6 --- -# _rotl, _rotl64, _rotr, _rotr64 +# `_rotl`, `_rotl64`, `_rotr`, `_rotr64` -Rotates bits to the left (**_rotl**) or right (**_rotr**). +Rotates bits to the left (**`_rotl`**) or right (**`_rotr`**). ## Syntax ```C - unsigned int _rotl( unsigned int value, int shift @@ -38,32 +36,32 @@ unsigned __int64 _rotr64( ### Parameters -*value*
+*`value`*\ Value to be rotated. -*shift*
+*`shift`*\ Number of bits to shift. -## Return Value +## Return value The rotated value. There's no error return. ## Remarks -The **_rotl** and **_rotr** functions rotate the unsigned *value* by *shift* bits. **_rotl** rotates the value left. **_rotr** rotates the value right. Both functions wrap bits rotated off one end of *value* to the other end. +The **`_rotl`** and **`_rotr`** functions rotate the unsigned *`value`* by *`shift`* bits. **`_rotl`** rotates the value left. **`_rotr`** rotates the value right. Both functions wrap bits rotated off one end of *`value`* to the other end. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_rotl**, **_rotl64**|\| -|**_rotr**, **_rotr64**|\| +| Routine | Required header | +|---|---| +| **`_rotl`**, **`_rotl64`** | \ | +| **`_rotr`**, **`_rotr64`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -103,5 +101,5 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_lrotl, _lrotr](lrotl-lrotr.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_lrotl`, `_lrotr`](lrotl-lrotr.md) diff --git a/docs/c-runtime-library/reference/round-roundf-roundl.md b/docs/c-runtime-library/reference/round-roundf-roundl.md index 4237a2ac2a7..df753b8e603 100644 --- a/docs/c-runtime-library/reference/round-roundf-roundl.md +++ b/docs/c-runtime-library/reference/round-roundf-roundl.md @@ -1,14 +1,13 @@ --- title: "round, roundf, roundl" description: "API reference for round, roundf, and roundl; which round a floating-point value to the nearest integer value." -ms.date: "09/25/2020" +ms.date: 09/25/2020 api_name: ["round", "roundl", "roundf", "_o_round", "_o_roundf", "_o_roundl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["roundf", "roundl", "round"] helpviewer_keywords: ["roundl function", "round function", "roundf function"] -ms.assetid: 6be90877-193c-4b80-a32b-c3eca33f9c6f --- # `round`, `roundf`, `roundl` @@ -32,7 +31,7 @@ float roundf( long double roundl( long double x ); -#define round(X) // Requires C11 or higher +#define round(X) // Requires C11 or later ``` ### Parameters @@ -40,30 +39,30 @@ long double roundl( *`x`*\ The floating-point value to round. -## Return Value +## Return value The **`round`** functions return a floating-point value that represents the nearest integer to *`x`*. Halfway values are rounded away from zero, regardless of the setting of the floating-point rounding mode. There's no error return. -|Input|SEH Exception|Matherr Exception| -|-----------|-------------------|-----------------------| -|± **`QNAN`**, **`IND`**|none|**`_DOMAIN`**| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`round`** that take and return **`float`** and **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`round`** always takes and returns a **`double`**. -If you use the `` `round()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `round` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`round`**, **`roundf`**, **`roundl`**|``| -|**`round`** macro | `` | +| Routine | Required header | +|---|---| +| **`round`**, **`roundf`**, **`roundl`** | `` | +| **`round`** macro | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -117,7 +116,7 @@ roundl(-2.499999900000000163657887242152355611324310302734375) is -2 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ [`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ [`fmod`, `fmodf`](fmod-fmodf.md)\ diff --git a/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md b/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md index 6c41dbef60d..e143c539a1d 100644 --- a/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md +++ b/docs/c-runtime-library/reference/rpt-rptf-rptw-rptfw-macros.md @@ -9,19 +9,17 @@ f1_keywords: ["RPT3", "RPTF4", "_RPT4", "RPT1", "_RPTF0", "RPTF3", "_RPTF4", "RP helpviewer_keywords: ["debugging [CRT], using macros", "_RPTW3 macro", "_RPT0 macro", "RPTW4 macro", "_RPTF3 macro", "_RPTW4 macro", "RPTF4 macro", "RPTFW2 macro", "RPTW macros", "RPT1 macro", "_RPTF macros", "RPTFW3 macro", "_RPTW0 macro", "_RPTF0 macro", "macros, debugging with", "_RPTW2 macro", "RPTF3 macro", "RPT3 macro", "RPT0 macro", "_RPT macros", "RPTW3 macro", "_RPTFW macros", "debug reporting macros", "RPTF macros", "RPT macros", "_RPTW macros", "RPTF2 macro", "_RPTF1 macro", "_RPT1 macro", "_RPT4 macro", "_RPTFW2 macro", "_RPTFW1 macro", "RPTF0 macro", "_RPT2 macro", "RPTFW macros", "_RPTW1 macro", "_RPTFW0 macro", "RPT4 macro", "_RPT3 macro", "_RPTFW3 macro", "_RPTF4 macro", "_RPTFW4 macro", "_RPTF2 macro", "RPTW0 macro", "RPTFW4 macro", "RPTFW0 macro", "RPTW2 macro", "RPTF1 macro", "RPT2 macro", "RPTFW1 macro", "RPTW1 macro"] ms.assetid: a5bf8b30-57f7-4971-8030-e773b7a1ae13 --- -# _RPT, _RPTF, _RPTW, _RPTFW Macros +# `_RPT`, `_RPTF`, `_RPTW`, `_RPTFW` Macros -Tracks an application's progress by generating a debug report (debug version only). Note that *n* specifies the number of arguments in *args* and can be 0, 1, 2, 3, 4, or 5. +Tracks an application's progress by generating a debug report (debug version only). The `n` suffix specifies the number of arguments in *`args`*, and can be 0, 1, 2, 3, 4, or 5. ## Syntax ```C -_RPT - n - ( +_RPTn( reportType, format, -...[args] + ...[args] ); _RPTFn( reportType, @@ -42,60 +40,60 @@ _RPTFWn( ### Parameters -*reportType*
-Report type: **_CRT_WARN**, **_CRT_ERROR**, or **_CRT_ASSERT**. +*`reportType`*\ +Report type: `_CRT_WARN`, `_CRT_ERROR`, or `_CRT_ASSERT`. -*format*
+*`format`*\ Format-control string used to create the user message. -*args*
-Substitution arguments used by *format*. +*`args`*\ +Substitution arguments used by *`format`*. ## Remarks -All these macros take the *reportType* and *format* parameters. In addition, they might also take up to four additional arguments, signified by the number appended to the macro name. For example, **_RPT0** and **_RPTF0** take no additional arguments, **_RPT1** and **_RPTF1** take *arg1*, **_RPT2** and **_RPTF2** take *arg1* and **arg2**, and so on. +All these macros take the *`reportType`* and *`format`* parameters. In addition, they might also take up to four more arguments, signified by the number appended to the macro name. For example, **`_RPT0`** and **`_RPTF0`** take no more arguments, **`_RPT1`** and **`_RPTF1`** take *`arg1`*, **`_RPT2`** and **`_RPTF2`** take *`arg1`* and *`arg2`*, and so on. -The **_RPT** and **_RPTF** macros are similar to the [printf](printf-printf-l-wprintf-wprintf-l.md) function, because they can be used to track an application's progress during the debugging process. However, these macros are more flexible than **printf** because they do not need to be enclosed in **#ifdef** statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [_DEBUG](../../c-runtime-library/debug.md) macro; the **_RPT** and **_RPTF** macros are only available when the **_DEBUG** flag is defined. When **_DEBUG** is not defined, calls to these macros are removed during preprocessing. +The `_RPT` and `_RPTF` macros are similar to the [`printf`](printf-printf-l-wprintf-wprintf-l.md) function, because they can be used to track an application's progress during the debugging process. However, these macros are more flexible than `printf` because they don't need to be enclosed in **#ifdef** statements to prevent them from being called in a retail build of an application. This flexibility is achieved by using the [`_DEBUG`](../debug.md) macro; the `_RPT` and `_RPTF` macros are only available when the `_DEBUG` flag is defined. When `_DEBUG` isn't defined, calls to these macros are removed during preprocessing. -The **_RPTW** and **_RPTFW** macros are wide-character versions of these macros. They are like **wprintf** and take wide-character strings as arguments. +The `_RPTW` and `_RPTFW` macros are wide-character versions of these macros. They are like `wprintf` and take wide-character strings as arguments. -The **_RPT** macros call the [_CrtDbgReport](crtdbgreport-crtdbgreportw.md) function to generate a debug report with a user message. The **_RPTW** macros call the **_CrtDbgReportW** function to generate the same report with wide characters. The **_RPTF** and **_RPTFW** macros create a debug report with the source file and line number where the report macro was called, in addition to the user message. The user message is created by substituting the **arg**[*n*] arguments into the *format* string, using the same rules defined by the [printf](printf-printf-l-wprintf-wprintf-l.md) function. +The `_RPT` macros call the [`_CrtDbgReport`](crtdbgreport-crtdbgreportw.md) function to generate a debug report with a user message. The `_RPTW` macros call the `_CrtDbgReportW` function to generate the same report with wide characters. The `_RPTF` and `_RPTFW` macros create a debug report with the source file and line number where the report macro was called, in addition to the user message. The user message is created by substituting the *`arg[n]`* arguments into the *`format`* string, using the same rules defined by the [`printf`](printf-printf-l-wprintf-wprintf-l.md) function. -**_CrtDbgReport** or **_CrtDbgReportW** generates the debug report and determines its destinations based on the current report modes and file defined for *reportType*. The [_CrtSetReportMode](crtsetreportmode.md) and [_CrtSetReportFile](crtsetreportfile.md) functions are used to define the destinations for each report type. +`_CrtDbgReport` or `_CrtDbgReportW` generates the debug report and determines its destinations based on the current report modes and file defined for *`reportType`*. The [`_CrtSetReportMode`](crtsetreportmode.md) and [`_CrtSetReportFile`](crtsetreportfile.md) functions are used to define the destinations for each report type. -If an **_RPT** macro is called and neither **_CrtSetReportMode** nor **_CrtSetReportFile** has been called, messages are displayed as follows. +If an `_RPT` macro is called, and `_CrtSetReportMode` and `_CrtSetReportFile` haven't been called, messages are displayed as follows: -|Report type|Output destination| -|-----------------|------------------------| -|**_CRT_WARN**|Warning text is not displayed.| -|**_CRT_ERROR**|A pop-up window. Same as if `_CrtSetReportMode(_CRT_ERROR, _CRTDBG_MODE_WNDW);` had been specified.| -|**_CRT_ASSERT**|Same as **_CRT_ERROR**.| +| Report type | Output destination | +|---|---| +| `_CRT_WARN` | Warning text isn't displayed. | +| `_CRT_ERROR` | A pop-up window. Same as if `_CrtSetReportMode(_CRT_ERROR, _CRTDBG_MODE_WNDW);` had been specified. | +| `_CRT_ASSERT` | Same as `_CRT_ERROR`. | -When the destination is a debug message window and the user chooses the **Retry** button, **_CrtDbgReport** or **_CrtDbgReportW** returns 1, causing these macros to start the debugger, provided that just-in-time (JIT) debugging is enabled. For more information about using these macros as a debugging error handling mechanism, see [Using Macros for Verification and Reporting](/visualstudio/debugger/macros-for-reporting). +When the destination is a debug message window and the user chooses the **Retry** button, `_CrtDbgReport` or `_CrtDbgReportW` returns 1. This return value causes these macros to start the debugger, if just-in-time (JIT) debugging is enabled. For more information about using these macros as a debugging error handling mechanism, see [Macros for reporting](../crt-debugging-techniques.md#macros-for-reporting). -Two other macros exist that generate a debug report. The [_ASSERT](assert-asserte-assert-expr-macros.md) macro generates a report, but only when its expression argument evaluates to FALSE. [_ASSERTE](assert-asserte-assert-expr-macros.md) is exactly like **_ASSERT**, but includes the failed expression in the generated report. +Two other macros exist that generate a debug report. The [`_ASSERT`](assert-asserte-assert-expr-macros.md) macro generates a report, but only when its expression argument evaluates to `FALSE`. [`_ASSERTE`](assert-asserte-assert-expr-macros.md) is exactly like `_ASSERT`, but includes the failed expression in the generated report. ## Requirements -|Macro|Required header| -|-----------|---------------------| -|**_RPT** macros|\| -|**_RPTF** macros|\| -|**_RPTW** macros|\| -|**_RPTFW** macros|\| +| Macro | Required header | +|---|---| +| `_RPT` macros | \ | +| `_RPTF` macros | \ | +| `_RPTW` macros | \ | +| `_RPTFW` macros | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -Debug versions of [C run-time libraries](../../c-runtime-library/crt-library-features.md) only. +Debug versions of [C run-time libraries](../crt-library-features.md) only. -Although these are macros and are obtained by including Crtdbg.h, the application must link with one of the debug libraries because these macros call other run-time functions. +Although these macros are available when you include `crtdbg.h`, to run, the application must link with one of the debug libraries, because these macros call other run-time functions. ## Example -See the example in the [_ASSERT](assert-asserte-assert-expr-macros.md) topic. +See the example in the [`_ASSERT`](assert-asserte-assert-expr-macros.md) article. ## See also -[Debug Routines](../../c-runtime-library/debug-routines.md)
+[Debug routines](../debug-routines.md) diff --git a/docs/c-runtime-library/reference/rtc-geterrdesc.md b/docs/c-runtime-library/reference/rtc-geterrdesc.md index 978b40ea921..74eb5e71941 100644 --- a/docs/c-runtime-library/reference/rtc-geterrdesc.md +++ b/docs/c-runtime-library/reference/rtc-geterrdesc.md @@ -10,7 +10,7 @@ f1_keywords: ["RTC_GetErrDesc", "_RTC_GetErrDesc"] helpviewer_keywords: ["run-time errors", "_RTC_GetErrDesc function", "RTC_GetErrDesc function"] ms.assetid: 7994ec2b-5488-4fd4-806d-a166c9a9f927 --- -# _RTC_GetErrDesc +# `_RTC_GetErrDesc` Returns a brief description of a run-time error check (RTC) type. @@ -24,26 +24,26 @@ const char * _RTC_GetErrDesc( ### Parameters -*errnum*
-A number between zero and one less than the value returned by **_RTC_NumErrors**. +*`errnum`*\ +A number between zero and one less than the value returned by `_RTC_NumErrors`. -## Return Value +## Return value -A character string that contains a short description of one of the error types detected by the run-time error check system. If error is less than zero or greater than or equal to the value returned by [_RTC_NumErrors](rtc-numerrors.md), **_RTC_GetErrDesc** returns **NULL**. +A character string that contains a short description of one of the error types detected by the run-time error check system. If error is less than zero or greater than or equal to the value returned by [`_RTC_NumErrors`](rtc-numerrors.md), **`_RTC_GetErrDesc`** returns `NULL`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_GetErrDesc**|\| +| Routine | Required header | +|---|---| +| **`_RTC_GetErrDesc`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_RTC_NumErrors](rtc-numerrors.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_RTC_NumErrors`](rtc-numerrors.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-numerrors.md b/docs/c-runtime-library/reference/rtc-numerrors.md index adc69743fbc..f2428d8e7a7 100644 --- a/docs/c-runtime-library/reference/rtc-numerrors.md +++ b/docs/c-runtime-library/reference/rtc-numerrors.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: _RTC_NumErrors" title: "_RTC_NumErrors" +description: "Learn more about: _RTC_NumErrors" ms.date: "11/04/2016" api_name: ["_RTC_NumErrors"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] @@ -8,36 +8,34 @@ api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_RTC_NumErrors", "RTC_NumErrors"] helpviewer_keywords: ["run-time errors", "_RTC_NumErrors function", "RTC_NumErrors function"] -ms.assetid: 7e82adae-38e2-4f8b-bc0b-37bda8109fd1 --- -# _RTC_NumErrors +# `_RTC_NumErrors` -Returns the total number of errors that can be detected by run-time error checks (RTC). You can use this number as the control in a **`for`** loop, where each value in the loop is passed to [_RTC_GetErrDesc](rtc-geterrdesc.md). +Returns the total number of errors that can be detected by run-time error checks (RTC). You can use this number as the control in a **`for`** loop, where each value in the loop is passed to [`_RTC_GetErrDesc`](rtc-geterrdesc.md). ## Syntax ```C - int _RTC_NumErrors( void ); ``` -## Return Value +## Return value An integer whose value represents the total number of errors that can be detected by the Visual C++ run-time error checks. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_NumErrors**|\| +| Routine | Required header | +|---|---| +| **`_RTC_NumErrors`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_RTC_GetErrDesc](rtc-geterrdesc.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_RTC_GetErrDesc`](rtc-geterrdesc.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-seterrorfunc.md b/docs/c-runtime-library/reference/rtc-seterrorfunc.md index be9e6e6c444..decf0fe6e55 100644 --- a/docs/c-runtime-library/reference/rtc-seterrorfunc.md +++ b/docs/c-runtime-library/reference/rtc-seterrorfunc.md @@ -10,9 +10,9 @@ f1_keywords: ["RTC_SetErrorFunc", "_RTC_SetErrorFunc"] helpviewer_keywords: ["RTC_SetErrorFunc function", "_RTC_SetErrorFunc function"] ms.assetid: b2292722-0d83-4092-83df-3d5b19880666 --- -# _RTC_SetErrorFunc +# `_RTC_SetErrorFunc` -Designates a function as the handler for reporting run-time error checks (RTCs). This function is deprecated; use **_RTC_SetErrorFuncW** instead. +Designates a function as the handler for reporting run-time error checks (RTCs). This function is deprecated; use `_RTC_SetErrorFuncW` instead. ## Syntax @@ -24,30 +24,30 @@ _RTC_error_fn _RTC_SetErrorFunc( ### Parameters -*function*
+*`function`*\ The address of the function that will handle run-time error checks. -## Return Value +## Return value -The previously defined error function. If there is no previously defined function, returns **NULL**. +The previously defined error function. If there's no previously defined function, returns `NULL`. ## Remarks -Do not use this function; instead, use **_RTC_SetErrorFuncW**. It is retained only for backward compatibility. +Don't use this function; instead, use `_RTC_SetErrorFuncW`. It's retained only for backward compatibility. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_SetErrorFunc**|\| +| Routine | Required header | +|---|---| +| **`_RTC_SetErrorFunc`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_CrtDbgReport, _CrtDbgReportW](crtdbgreport-crtdbgreportw.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-seterrorfuncw.md b/docs/c-runtime-library/reference/rtc-seterrorfuncw.md index 28fe0f94e84..5505a8b5427 100644 --- a/docs/c-runtime-library/reference/rtc-seterrorfuncw.md +++ b/docs/c-runtime-library/reference/rtc-seterrorfuncw.md @@ -10,7 +10,7 @@ f1_keywords: ["_RTC_SetErrorFuncW", "RTC_SetErrorFuncW"] helpviewer_keywords: ["run-time errors", "RTC_SetErrorFuncW function", "_RTC_error_fnW typedef", "_RTC_SetErrorFuncW function", "RTC_error_fnW typedef"] ms.assetid: b3e0d71f-1bd3-4c37-9ede-2f638eb3c81a --- -# _RTC_SetErrorFuncW +# `_RTC_SetErrorFuncW` Designates a function as the handler for the reporting of run-time error checks (RTCs). @@ -24,26 +24,26 @@ _RTC_error_fnW _RTC_SetErrorFuncW( ### Parameters -*function*
+*`function`*\ The address of the function that will handle run-time error checks. -## Return Value +## Return value -The previously defined error function; or **NULL** if there is no previously defined function. +The previously defined error function; or `NULL` if there's no previously defined function. ## Remarks -In new code, use only **_RTC_SetErrorFuncW**. **_RTC_SetErrorFunc** is only included in the library for backward compatibility. +In new code, use only **`_RTC_SetErrorFuncW`**. `_RTC_SetErrorFunc` is only included in the library for backward compatibility. -The **_RTC_SetErrorFuncW** callback applies only to the component that it was linked in, but not globally. +The **`_RTC_SetErrorFuncW`** callback applies only to the component that it was linked in, but not globally. -Make sure that the address that you pass to **_RTC_SetErrorFuncW** is that of a valid error handling function. +Make sure that the address that you pass to **`_RTC_SetErrorFuncW`** is that of a valid error handling function. -If an error has been assigned a type of -1 by using [_RTC_SetErrorType](rtc-seterrortype.md), the error handling function is not called. +If an error has been assigned a type of -1 by using [`_RTC_SetErrorType`](rtc-seterrortype.md), the error handling function isn't called. -Before you can call this function, you must first call one of the run-time error-check initialization functions. For more information, see [Using Run-Time Checks Without the C Run-Time Library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library). +Before you can call this function, you must first call one of the run-time error-check initialization functions. For more information, see [Using runtime checks without the C runtime library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library). -**_RTC_error_fnW** is defined as follows: +`_RTC_error_fnW` is defined as follows: ```cpp typedef int (__cdecl * _RTC_error_fnW)( @@ -57,36 +57,36 @@ typedef int (__cdecl * _RTC_error_fnW)( where: -*errorType*
-The type of error that's specified by [_RTC_SetErrorType](rtc-seterrortype.md). +*`errorType`*\ +The type of error that's specified by [`_RTC_SetErrorType`](rtc-seterrortype.md). -*filename*
+*`filename`*\ The source file where the failure occurred, or null if no debug information is available. -*linenumber*
-The line in *filename* where the failure occurred, or 0 if no debug information is available. +*`linenumber`*\ +The line in *`filename`* where the failure occurred, or 0 if no debug information is available. -*moduleName*
+*`moduleName`*\ The DLL or executable name where the failure occurred. -*format*
-printf style string to display an error message, using the remaining parameters. The first argument of the VA_ARGLIST is the RTC Error number that occurred. +*`format`*\ +printf style string to display an error message, using the remaining parameters. The first argument of the `VA_ARGLIST` is the RTC Error number that occurred. -For an example that shows how to use **_RTC_error_fnW**, see [Native Run-Time Checks Customization](/visualstudio/debugger/native-run-time-checks-customization). +For an example that shows how to use `_RTC_error_fnW`, see [Native runtime checks customization](/visualstudio/debugger/native-run-time-checks-customization). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_SetErrorFuncW**|\| +| Routine | Required header | +|---|---| +| **`_RTC_SetErrorFuncW`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_CrtDbgReport, _CrtDbgReportW](crtdbgreport-crtdbgreportw.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_CrtDbgReport`, `_CrtDbgReportW`](crtdbgreport-crtdbgreportw.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/rtc-seterrortype.md b/docs/c-runtime-library/reference/rtc-seterrortype.md index 67c47077342..29ed6bd05db 100644 --- a/docs/c-runtime-library/reference/rtc-seterrortype.md +++ b/docs/c-runtime-library/reference/rtc-seterrortype.md @@ -10,7 +10,7 @@ f1_keywords: ["RTC_SetErrorType", "_RTC_SetErrorType"] helpviewer_keywords: ["run-time errors", "RTC_SetErrorType function", "_RTC_SetErrorType function"] ms.assetid: f5f99be7-d357-4b11-b8f5-ddd3428f2b06 --- -# _RTC_SetErrorType +# `_RTC_SetErrorType` Associates an error that is detected by run-time error checks (RTCs) with a type. Your error handler processes how to output errors of the specified type. @@ -25,37 +25,37 @@ int _RTC_SetErrorType( ### Parameters -*errnum*
-A number between zero and one less than the value returned by [_RTC_NumErrors](rtc-numerrors.md). +*`errnum`*\ +A number between zero and one less than the value returned by [`_RTC_NumErrors`](rtc-numerrors.md). -*ErrType*
-A value to assign to this *errnum*. For example, you might use **_CRT_ERROR**. If you are using **_CrtDbgReport** as your error handler, *ErrType* can only be one of the symbols defined in [_CrtSetReportMode](crtsetreportmode.md). If you have your own error handler ([_RTC_SetErrorFunc](rtc-seterrorfunc.md)), you can have as many *ErrType*s as there are *errnum*s. +*`ErrType`*\ +A value to assign to this *`errnum`*. For example, you might use `_CRT_ERROR`. If you're using `_CrtDbgReport` as your error handler, *`ErrType`* can only be one of the symbols defined in [`_CrtSetReportMode`](crtsetreportmode.md). If you have your own error handler ([`_RTC_SetErrorFunc`](rtc-seterrorfunc.md)), you can have as many *`ErrType`* values as there are *`errnum`* values. -An *ErrType* of _RTC_ERRTYPE_IGNORE has special meaning to **_CrtSetReportMode**; the error is ignored. +An *`ErrType`* of `_RTC_ERRTYPE_IGNORE` has special meaning to `_CrtSetReportMode`; the error is ignored. -## Return Value +## Return value -The previous value for the error type *type*. +The previous value for the error type replaced by *`ErrType`*. ## Remarks -By default, all errors are set to *ErrType* = 1, which corresponds to **_CRT_ERROR**. For more information about the default error types such as **_CRT_ERROR**, see [_CrtDbgReport](crtdbgreport-crtdbgreportw.md). +By default, all errors are set to *`ErrType`* = 1, which corresponds to `_CRT_ERROR`. For more information about the default error types such as `_CRT_ERROR`, see [`_CrtDbgReport`](crtdbgreport-crtdbgreportw.md). -Before you can call this function, you must first call one of the run-time error check initialization functions; see [Using Run-Time Checks without the C Run-Time Library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library) +Before you can call this function, you must first call one of the run-time error check initialization functions; see [Using runtime checks without the C runtime library](/visualstudio/debugger/using-run-time-checks-without-the-c-run-time-library) ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_RTC_SetErrorType**|\| +| Routine | Required header | +|---|---| +| **`_RTC_SetErrorType`** | \ | -For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## See also -[_RTC_GetErrDesc](rtc-geterrdesc.md)
-[Run-Time Error Checking](../../c-runtime-library/run-time-error-checking.md)
+[`_RTC_GetErrDesc`](rtc-geterrdesc.md)\ +[Runtime error checking](../run-time-error-checking.md) diff --git a/docs/c-runtime-library/reference/scalb.md b/docs/c-runtime-library/reference/scalb.md index cf5629f13b7..f4754e7857d 100644 --- a/docs/c-runtime-library/reference/scalb.md +++ b/docs/c-runtime-library/reference/scalb.md @@ -3,7 +3,7 @@ description: "Learn more about: _scalb, _scalbf" title: "_scalb, _scalbf" ms.date: "1/15/2021" api_name: ["_scalb", "_scalbf", "_o__scalb", "_o__scalbf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["scalb", "_scalb", "_scalbf"] @@ -34,27 +34,27 @@ Double-precision, floating-point value. *`exp`*\ Long integer exponent. -## Return Value +## Return value -Returns an exponential value if successful. On overflow (depending on the sign of *`x`*), **`_scalb`** returns +/- **`HUGE_VAL`**; the **`errno`** variable is set to **`ERANGE`**. +Returns an exponential value if successful. On overflow (depending on the sign of *`x`*), **`_scalb`** returns +/- `HUGE_VAL`; the `errno` variable is set to `ERANGE`. -For more information about this and other return codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`_scalb`** function calculates the value of *`x`* \* 2*`exp`*. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_scalb`**, **`_scalbf`**|``| +| Routine | Required header | +|---|---| +| **`_scalb`**, **`_scalbf`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`ldexp`](ldexp.md) diff --git a/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md b/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md index 04c178a5608..e8633ee0086 100644 --- a/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md +++ b/docs/c-runtime-library/reference/scalbn-scalbnf-scalbnl-scalbln-scalblnf-scalblnl.md @@ -1,18 +1,17 @@ --- title: "scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl" description: "API reference for scalbn, scalbnf, scalbnl, scalbln, scalblnf, and scalblnl; which multiplies a floating-point number by an integral power of `FLT_RADIX`." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["scalblnl", "scalbnl", "scalbnf", "scalblnf", "scalbn", "scalbln", "_o_scalbln", "_o_scalblnf", "_o_scalblnl", "_o_scalbn", "_o_scalbnf", "_o_scalbnl"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["scalblnf", "scalbnl", "scalblnl", "scalbln", "scalbn", "scalbnf"] helpviewer_keywords: ["scalbn function", "scalbln function", "scalblnl function", "scalbnl function", "scalbnf function", "scalblnf function"] -ms.assetid: df2f1543-8e39-4af4-a5cf-29307e64807d --- -# scalbn, scalbnf, scalbnl, scalbln, scalblnf, scalblnl +# `scalbn`, `scalbnf`, `scalbnl`, `scalbln`, `scalblnf`, `scalblnl` -Multiplies a floating-point number by an integral power of FLT_RADIX. +Multiplies a floating-point number by an integral power of `FLT_RADIX`. ## Syntax @@ -38,7 +37,7 @@ long double scalbnl( int exp ); -#define scalbn(X, INT) // Requires C11 or higher +#define scalbn(X, INT) // Requires C11 or later double scalbln( double x, @@ -54,7 +53,7 @@ long double scalblnl( long exp ); -#define scalbln(X, LONG) // Requires C11 or higher +#define scalbln(X, LONG) // Requires C11 or later float scalbln( float x, @@ -68,36 +67,36 @@ long double scalbln( ### Parameters -*x*\ +*`x`*\ Floating-point value. -*exp*\ +*`exp`*\ Integer exponent. -## Return Value +## Return value -The **scalbn** functions return the value of *x* \* **FLT_RADIX**exp when successful. On overflow (depending on the sign of *x*), **scalbn** returns +/- **HUGE_VAL**; the **errno** value is set to **ERANGE**. +The **`scalbn`** functions return the value of *`x`* \* `FLT_RADIX`exp when successful. On overflow (depending on the sign of *`x`*), **`scalbn`** returns +/- `HUGE_VAL`; the `errno` value is set to `ERANGE`. -For more information about **errno** and possible error return values, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about `errno` and possible error return values, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -**FLT_RADIX** is defined in \ as the native floating-point radix; on binary systems, it has a value of 2, and **scalbn** is equivalent to [ldexp](ldexp.md). +`FLT_RADIX` is defined in \ as the native floating-point radix; on binary systems, it has a value of 2, and **`scalbn`** is equivalent to [`ldexp`](ldexp.md). -Because C++ allows overloading, you can call overloads of **scalbn** and **scalbln** that take and return **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **scalbn** always takes a **`double`** and an **`int`** and returns a **`double`**, and **scalbln** always takes a **`double`** and a **`long`** and returns a **`double`**. +Because C++ allows overloading, you can call **`scalbn`** and **`scalbln`** overloads that take and return **`float`** or **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`scalbn`** always takes a **`double`** and an **`int`** and returns a **`double`**, and **`scalbln`** always takes a **`double`** and a **`long`** and returns a **`double`**. -If you use the \ `scalbn()` or `scalbln` macros, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `scalbn()` or `scalbln` macros, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**scalbn**, **scalbnf**, **scalbnl**, **scalbln**, **scalblnf**, **scalblnl**|\|\| -|**scalbn() or scalbln** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`scalbn`**, **`scalbnf`**, **`scalbnl`**, **`scalbln`**, **`scalblnf`**, **`scalblnl`** | \ | \ | +| **`scalbn`** or **`scalbln`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -125,7 +124,7 @@ int main( void ) ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[frexp](frexp.md)
-[ldexp](ldexp.md)
-[modf, modff, modfl](modf-modff-modfl.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`frexp`](frexp.md)\ +[`ldexp`](ldexp.md)\ +[`modf`, `modff`, `modfl`](modf-modff-modfl.md) diff --git a/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md b/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md index 7bf889d61d5..db73e93f9df 100644 --- a/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md +++ b/docs/c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md @@ -12,7 +12,7 @@ ms.assetid: 42cafcf7-52d6-404a-80e4-b056a7faf2e5 --- # `scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l` -Reads formatted data from the standard input stream. These versions of [`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from the standard input stream. These versions of [`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -39,30 +39,30 @@ int _wscanf_s_l( ### Parameters -*`format`*
+*`format`*\ Format control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of fields successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates no fields were assigned. The return value is **EOF** for an error, or if the end-of-file character or the end-of-string character is found in the first attempt to read a character. If *format* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`scanf_s`** and **`wscanf_s`** return **EOF** and set **`errno`** to **`EINVAL`**. +Returns the number of fields successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates no fields were assigned. The return value is `EOF` for an error, or if the end-of-file character or the end-of-string character is found in the first attempt to read a character. If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`scanf_s`** and **`wscanf_s`** return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`scanf_s`** function reads data from the standard input stream, **`stdin`**, and writes it into *`argument`*. Each *`argument`* must be a pointer to a variable type that corresponds to the type specifier in *`format`*. If copying occurs between strings that overlap, the behavior is undefined. -**`wscanf_s`** is a wide-character version of **`scanf_s`**; the *format* argument to **`wscanf_s`** is a wide-character string. **`wscanf_s`** and **`scanf_s`** behave identically if the stream is opened in ANSI mode. **`scanf_s`** doesn't currently support input from a UNICODE stream. +**`wscanf_s`** is a wide-character version of **`scanf_s`**; the *`format`* argument to **`wscanf_s`** is a wide-character string. **`wscanf_s`** and **`scanf_s`** behave identically if the stream is opened in ANSI mode. **`scanf_s`** doesn't currently support input from a UNICODE stream. -The versions of these functions that have the **_l** suffix are identical, except they use the *`locale`* parameter instead of the current thread locale. +The versions of these functions that have the `_l` suffix are identical, except they use the *`locale`* parameter instead of the current thread locale. -Unlike **`scanf`** and **`wscanf`**, **`scanf_s`** and **`wscanf_s`** require you to specify buffer sizes for some parameters. Specify the sizes for all **`c`**, **`C`**, **`s`**, **`S`**, or string control set **`[]`** parameters. The buffer size in characters is passed as an additional parameter. It immediately follows the pointer to the buffer or variable. For example, if you're reading a string, the buffer size for that string is passed as follows: +Unlike **`scanf`** and **`wscanf`**, **`scanf_s`** and **`wscanf_s`** require you to specify buffer sizes for some parameters. Specify the sizes for all **`c`**, **`C`**, **`s`**, **`S`**, or string control set **`[]`** parameters. The buffer size in characters is passed as another parameter. It immediately follows the pointer to the buffer or variable. For example, if you're reading a string, the buffer size for that string is passed as follows: ```C char s[10]; @@ -97,25 +97,25 @@ char c[4]; scanf_s("%4c", c, (unsigned)_countof(c)); // not null terminated ``` -For more information, see [`scanf` Width Specification](../../c-runtime-library/scanf-width-specification.md). +For more information, see [`scanf` Width Specification](../scanf-width-specification.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tscanf_s`**|**`scanf_s`**|**`scanf_s`**|**`wscanf_s`**| -|**`_tscanf_s_l`**|**`_scanf_s_l`**|**`_scanf_s_l`**|**`_wscanf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tscanf_s` | **`scanf_s`** | **`scanf_s`** | **`wscanf_s`** | +| `_tscanf_s_l` | **`_scanf_s_l`** | **`_scanf_s_l`** | **`_wscanf_s_l`** | -For more information, see [Format Specification Fields: `scanf` and `wscanf` Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`scanf_s`**, **`_scanf_s_l`**|``| -|**`wscanf_s`**, **`_wscanf_s_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`scanf_s`**, **`_scanf_s_l`** | `` | +| **`wscanf_s`**, **`_wscanf_s_l`** | `` or `` | -The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles **`stdin`**, **`stdout`**, and **`stderr`** must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles **`stdin`**, **`stdout`**, and **`stderr`** must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -166,10 +166,10 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) diff --git a/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md b/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md index abf517c7c8d..2cc46c3217e 100644 --- a/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md +++ b/docs/c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md @@ -12,10 +12,10 @@ ms.assetid: 73eac607-117f-4be4-9ff0-4afd9cf3c848 --- # `scanf`, `_scanf_l`, `wscanf`, `_wscanf_l` -Reads formatted data from the standard input stream. More secure versions of these function are available; see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). +Reads formatted data from the standard input stream. More secure versions of these functions are available; see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md). > [!NOTE] -> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see *LNK2019* in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). +> In Visual Studio 2015 The `printf` and `scanf` family of functions were declared as **`inline`** and moved to the `` and `` headers. If you are migrating older code you might see Linker Error LNK2019 in connection with these functions. For more information, see [Visual C++ change history 2003 - 2015](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). ## Syntax @@ -42,51 +42,51 @@ int _wscanf_l( ### Parameters -*`format`*
+*`format`*\ Format control string. -*`argument`*
+*`argument`*\ Optional arguments. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. +Returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. -If *`format`* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EOF`** and set **`errno`** to **`EINVAL`**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. -For information on these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`scanf`** function reads data from the standard input stream **`stdin`** and writes the data into the location given by *`argument`*. Each *`argument`* must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. If copying takes place between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> When reading a string with **`scanf`**, always specify a width for the **`%s`** format (for example, **"`%32s`"** instead of **"`%s`"**); otherwise, improperly formatted input can easily cause a buffer overrun. Alternately, consider using [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) or [`fgets`](fgets-fgetws.md). +> When reading a string with **`scanf`**, always specify a width for the **`%s`** format (for example, `%32s` instead of `%s`); otherwise, improperly formatted input can easily cause a buffer overrun. Alternately, consider using [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) or [`fgets`](fgets-fgetws.md). **`wscanf`** is a wide-character version of **`scanf`**; the *`format`* argument to **`wscanf`** is a wide-character string. **`wscanf`** and **`scanf`** behave identically if the stream is opened in ANSI mode. **`scanf`** doesn't currently support input from a UNICODE stream. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tscanf`**|**`scanf`**|**`scanf`**|**`wscanf`**| -|**`_tscanf_l`**|**`_scanf_l`**|**`_scanf_l`**|**`_wscanf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tscanf`** | **`scanf`** | **`scanf`** | **`wscanf`** | +| **`_tscanf_l`** | **`_scanf_l`** | **`_scanf_l`** | **`_wscanf_l`** | -For more information, see [Format Specification Fields — scanf functions and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`scanf`**, *`*_scanf_l`**|``| -|**`wscanf`**, **`_wscanf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`scanf`**, **`_scanf_l`** | `` | +| **`wscanf`**, **`_wscanf_l`** | `` or `` | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **`stdin`**, **`stdout`**, and **`stderr`**, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -128,10 +128,10 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) diff --git a/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md b/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md index 2303645c16c..8067e1ed052 100644 --- a/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md +++ b/docs/c-runtime-library/reference/scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: _scprintf_p, _scprintf_p_l, _scwprintf_p, _scwprintf_p_l" title: "_scprintf_p, _scprintf_p_l, _scwprintf_p, _scwprintf_p_l" -ms.date: "3/9/2021" +description: "Learn more about: _scprintf_p, _scprintf_p_l, _scwprintf_p, _scwprintf_p_l" +ms.date: 3/9/2021 api_name: ["_scwprintf_p", "_scprintf_p_l", "_scwprintf_p_l", "_scprintf_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"] @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["_scwprintf_p_l", "_sctprintf_p", "scprintf_p_l", "scprintf_p", "_sctprintf_p_l", "scwprintf_p", "_scprintf_p_l", "scwprintf_p_l", "_scprintf_p", "_scwprintf_p"] helpviewer_keywords: ["sctprintf_p_l function", "_scwprintf_p_l function", "scprintf_p_l function", "_scprintf_p function", "_scprintf_p_l function", "scprintf_p function", "sctprintf_p function", "_scwprintf_p function", "_sctprintf_p function", "scwprintf_p function", "scwprintf_p_l function", "_sctprintf_p_l function"] --- -# _scprintf_p, _scprintf_p_l, _scwprintf_p, _scwprintf_p_l +# `_scprintf_p`, `_scprintf_p_l`, `_scwprintf_p`, `_scwprintf_p_l` Returns the number of characters in the formatted string, with the ability to specify the order in which parameters are used in the format string. @@ -38,55 +38,54 @@ int _scwprintf_p _l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **_scwprintf_p** performs the same function for wide characters. +Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_scwprintf_p`** performs the same function for wide characters. -The difference between **_scprintf_p** and **_scprintf** is that **_scprintf_p** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +The difference between **`_scprintf_p`** and `_scprintf` is that **`_scprintf_p`** supports positional parameters, which allows specifying the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each *argument* (if any) is converted according to the corresponding format specification in *format*. The format consists of ordinary characters and has the same form and function as the *format* argument for [printf](printf-printf-l-wprintf-wprintf-l.md). +Each *`argument`* (if any) is converted according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > -> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_sctprintf_p**|**_scprintf_p**|**_scprintf_p**|**_scwprintf_p**| -|**_sctprintf_p_l**|**_scprintf_p_l**|**_scprintf_p_l**|**_scwprintf_p_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_sctprintf_p` | **`_scprintf_p`** | **`_scprintf_p`** | **`_scwprintf_p`** | +| `_sctprintf_p_l` | **`_scprintf_p_l`** | **`_scprintf_p_l`** | **`_scwprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_scprintf_p**, **_scprintf_p_l**|\| -|**_scwprintf_p**, **_scwprintf_p_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_scprintf_p`**, **`_scprintf_p_l`** | \ | +| **`_scwprintf_p`**, **`_scwprintf_p_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_scprintf, _scprintf_l, _scwprintf, _scwprintf_l](scprintf-scprintf-l-scwprintf-scwprintf-l.md)
-[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`_scprintf`, `_scprintf_l`, `_scwprintf`, `_scwprintf_l`](scprintf-scprintf-l-scwprintf-scwprintf-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md) diff --git a/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md b/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md index c05c00ba7a0..0d2d23af0d5 100644 --- a/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md +++ b/docs/c-runtime-library/reference/scprintf-scprintf-l-scwprintf-scwprintf-l.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: _scprintf, _scprintf_l, _scwprintf, _scwprintf_l" title: "_scprintf, _scprintf_l, _scwprintf, _scwprintf_l" -ms.date: "3/9/2021" +description: "Learn more about: _scprintf, _scprintf_l, _scwprintf, _scwprintf_l" +ms.date: 3/9/2021 api_name: ["_scprintf_l", "_scwprintf", "_scwprintf_l", "_scprintf"] api_location: ["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"] @@ -9,7 +9,7 @@ topic_type: ["apiref"] f1_keywords: ["scprintf", "_scprintf_l", "_scwprintf_l", "_scprintf", "scwprintf", "_scwprintf", "scprintf_l", "_sctprintf_l", "scwprintf_l", "_sctprintf"] helpviewer_keywords: ["scprintf function", "sctprintf_l function", "scwprintf_l function", "_scwprintf_l function", "_sctprintf_l function", "sctprintf function", "_scwprintf function", "_scprintf_l function", "_sctprintf function", "scprintf_l function", "formatted text [C++]", "_scprintf function", "scwprintf function"] --- -# _scprintf, _scprintf_l, _scwprintf, _scwprintf_l +# `_scprintf`, `_scprintf_l`, `_scwprintf`, `_scwprintf_l` Returns the number of characters in the formatted string. @@ -38,52 +38,51 @@ int _scwprintf_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argument*
+*`argument`*\ Optional arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **_scwprintf** performs the same function for wide characters. +Returns the number of characters that would be generated if the string were to be printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_scwprintf`** performs the same function for wide characters. -If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each *argument* (if any) is converted according to the corresponding format specification in *format*. The format consists of ordinary characters and has the same form and function as the *format* argument for [printf](printf-printf-l-wprintf-wprintf-l.md). +Each *`argument`* (if any) is converted according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. -> +> Ensure that *`format`* is not a user-defined string. > -> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_sctprintf**|**_scprintf**|**_scprintf**|**_scwprintf**| -|**_sctprintf_l**|**_scprintf_l**|**_scprintf_l**|**_scwprintf_l**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_sctprintf` | **`_scprintf`** | **`_scprintf`** | **`_scwprintf`** | +| `_sctprintf_l` | **`_scprintf_l`** | **`_scprintf_l`** | **`_scwprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_scprintf**, **_scprintf_l**|\| -|**_scwprintf**, **_scwprintf_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_scprintf`**, **`_scprintf_l`** | \ | +| **`_scwprintf`**, **`_scwprintf_l`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -122,9 +121,9 @@ The value of Pi is calculated to be 3.141593. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md b/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md index 278069237f3..dd5d3605428 100644 --- a/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md +++ b/docs/c-runtime-library/reference/searchenv-s-wsearchenv-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _searchenv_s, _wsearchenv_s" title: "_searchenv_s, _wsearchenv_s" ms.date: "4/2/2020" api_name: ["_wsearchenv_s", "_searchenv_s", "_o__searchenv_s", "_o__wsearchenv_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_searchenv_s", "_wsearchenv_s", "wsearchenv_s", "searchenv_s"] helpviewer_keywords: ["tsearchenv_s function", "files [C++], finding", "buffers [C++], buffer overruns", "environment paths, searching for files", "wsearchenv_s function", "searchenv_s function", "_tsearchenv_s function", "buffer overruns", "buffers [C++], avoiding overruns", "_wsearchenv_s function", "_searchenv_s function", "environment paths"] ms.assetid: 47f9fc29-250e-4c09-b52e-9e9f0ef395ca --- -# _searchenv_s, _wsearchenv_s +# `_searchenv_s`, `_wsearchenv_s` -Searches for a file by using environment paths. These versions of [_searchenv, _wsearchenv](searchenv-wsearchenv.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Searches for a file by using environment paths. These versions of [`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -48,62 +48,62 @@ errno_t _wsearchenv_s( ### Parameters -*filename*
+*`filename`*\ Name of the file to search for. -*varname*
+*`varname`*\ Environment to search. -*pathname*
+*`pathname`*\ Buffer to store the complete path. -*numberOfElements*
-Size of the *pathname* buffer. +*`numberOfElements`*\ +Size of the *`pathname`* buffer. -## Return Value +## Return value Zero if successful; an error code on failure. -If *filename* is an empty string, the return value is **ENOENT**. +If *`filename`* is an empty string, the return value is `ENOENT`. -### Error Conditions +### Error conditions -|*filename*|*varname*|*pathname*|*numberOfElements*|Return value|Contents of *pathname*| -|----------------|---------------|----------------|------------------------|------------------|----------------------------| -|any|any|**NULL**|any|**EINVAL**|n/a| -|**NULL**|any|any|any|**EINVAL**|not changed| -|any|any|any|<= 0|**EINVAL**|not changed| +| *`filename`* | *`varname`* | *`pathname`* | *`numberOfElements`* | Return value | Contents of *`pathname`* | +|---|---|---|---|---|---| +| any | any | `NULL` | any | `EINVAL` | n/a | +| `NULL` | any | any | any | `EINVAL` | not changed | +| any | any | any | <= 0 | `EINVAL` | not changed | -If any of these error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **EINVAL**. +If any of these error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. ## Remarks -The **_searchenv_s** routine searches for the target file in the specified domain. The *varname* variable can be any environment or user-defined variable that specifies a list of directory paths, such as **PATH**, **LIB**, and **INCLUDE**. Because **_searchenv_s** is case-sensitive, *varname* should match the case of the environment variable. If *varname* does not match the name of an environment variable defined in the process's environment, the function returns zero and the *pathname* variable is unchanged. +The **`_searchenv_s`** routine searches for the target file in the specified domain. The *`varname`* variable can be any environment or user-defined variable that specifies a list of directory paths, such as `PATH`, `LIB`, and `INCLUDE`. Because **`_searchenv_s`** is case-sensitive, *`varname`* should match the case of the environment variable. If *`varname`* doesn't match the name of an environment variable defined in the process's environment, the function returns zero, and the *`pathname`* variable is unchanged. -The routine searches first for the file in the current working directory. If it does not find the file, it looks next through the directories specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *pathname*. If the *filename* file is not found, *pathname* contains an empty null-terminated string. +The routine searches first for the file in the current working directory. If it doesn't find the file, it looks next through the directories specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *`pathname`*. If the *`filename`* file isn't found, *`pathname`* contains an empty null-terminated string. -The *pathname* buffer should be at least **_MAX_PATH** characters long to accommodate the full length of the constructed path name. Otherwise, **_searchenv_s** might overrun the *pathname* buffer resulting in unexpected behavior. +The *`pathname`* buffer should be at least `_MAX_PATH` characters long to accommodate the full length of the constructed path name. Otherwise, **`_searchenv_s`** might overrun the *`pathname`* buffer resulting in unexpected behavior. -**_wsearchenv_s** is a wide-character version of **_searchenv_s**; the arguments to **_wsearchenv_s** are wide-character strings. **_wsearchenv_s** and **_searchenv_s** behave identically otherwise. +**`_wsearchenv_s`** is a wide-character version of **`_searchenv_s`**; the arguments to **`_wsearchenv_s`** are wide-character strings. **`_wsearchenv_s`** and **`_searchenv_s`** behave identically otherwise. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tsearchenv_s**|**_searchenv_s**|**_searchenv_s**|**_wsearchenv_s**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tsearchenv_s` | **`_searchenv_s`** | **`_searchenv_s`** | **`_wsearchenv_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_searchenv_s**|\| -|**_wsearchenv_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_searchenv_s`** | \ | +| **`_wsearchenv_s`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -143,7 +143,7 @@ C:\Program Files\Microsoft Visual Studio 2010\VC\BIN\CL.EXE ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[_searchenv, _wsearchenv](searchenv-wsearchenv.md)
-[getenv, _wgetenv](getenv-wgetenv.md)
-[_putenv, _wputenv](putenv-wputenv.md)
+[Directory control](../directory-control.md)\ +[`_searchenv`, `_wsearchenv`](searchenv-wsearchenv.md)\ +[`getenv`, `_wgetenv`](getenv-wgetenv.md)\ +[`_putenv`, `_wputenv`](putenv-wputenv.md) diff --git a/docs/c-runtime-library/reference/searchenv-wsearchenv.md b/docs/c-runtime-library/reference/searchenv-wsearchenv.md index 4b2ab642c65..2ca6602eaf3 100644 --- a/docs/c-runtime-library/reference/searchenv-wsearchenv.md +++ b/docs/c-runtime-library/reference/searchenv-wsearchenv.md @@ -3,16 +3,16 @@ description: "Learn more about: _searchenv, _wsearchenv" title: "_searchenv, _wsearchenv" ms.date: "4/2/2020" api_name: ["_searchenv", "_wsearchenv", "_o__searchenv", "_o__wsearchenv"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-environment-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wsearchenv", "_tsearchenv", "wsearchenv", "_searchenv", "searchenv"] helpviewer_keywords: ["_wsearchenv function", "files [C++], finding", "_searchenv function", "tsearchenv function", "environment paths, searching for files", "_tsearchenv function", "wsearchenv function", "searchenv function", "environment paths"] ms.assetid: 9c944a27-d326-409b-aee6-410e8762d9d3 --- -# _searchenv, _wsearchenv +# `_searchenv`, `_wsearchenv` -Uses environment paths to search for a file. More secure versions of these functions are available; see [_searchenv_s, _wsearchenv_s](searchenv-s-wsearchenv-s.md). +Uses environment paths to search for a file. More secure versions of these functions are available; see [`_searchenv_s`, `_wsearchenv_s`](searchenv-s-wsearchenv-s.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -46,49 +46,49 @@ void _wsearchenv( ### Parameters -*filename*
+*`filename`*\ Name of the file to search for. -*varname*
+*`varname`*\ Environment to search. -*pathname*
+*`pathname`*\ Buffer to store the complete path. ## Remarks -The **_searchenv** routine searches for the target file in the specified domain. The *varname* variable can be any environment or user-defined variable—for example, **PATH**, **LIB**, or **INCLUDE**—that specifies a list of directory paths. Because **_searchenv** is case-sensitive, *varname* should match the case of the environment variable. +The **`_searchenv`** routine searches for the target file in the specified domain. The *`varname`* variable can be any environment or user-defined variable—for example, `PATH`, `LIB`, or `INCLUDE`—that specifies a list of directory paths. Because **`_searchenv`** is case-sensitive, *`varname`* should match the case of the environment variable. -The routine first searches for the file in the current working directory. If it does not find the file, it looks through the directories that are specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *pathname*. If the *filename* file is not found, *pathname* contains an empty null-terminated string. +The routine first searches for the file in the current working directory. If it doesn't find the file, it looks through the directories that are specified by the environment variable. If the target file is in one of those directories, the newly created path is copied into *`pathname`*. If the *`filename`* file isn't found, *`pathname`* contains an empty null-terminated string. -The *pathname* buffer should be at least **_MAX_PATH** characters long to accommodate the full length of the constructed path name. Otherwise, **_searchenv** might overrun the *pathname* buffer and cause unexpected behavior. +The *`pathname`* buffer should be at least `_MAX_PATH` characters long to accommodate the full length of the constructed path name. Otherwise, **`_searchenv`** might overrun the *`pathname`* buffer and cause unexpected behavior. -**_wsearchenv** is a wide-character version of **_searchenv**, and the arguments to **_wsearchenv** are wide-character strings. **_wsearchenv** and **_searchenv** behave identically otherwise. +**`_wsearchenv`** is a wide-character version of **`_searchenv`**, and the arguments to **`_wsearchenv`** are wide-character strings. **`_wsearchenv`** and **`_searchenv`** behave identically otherwise. -If *filename* is an empty string, these functions return **ENOENT**. +If *`filename`* is an empty string, these functions return `ENOENT`. -If *filename* or *pathname* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`filename`* or *`pathname`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For more information about **errno** and error codes, see [errno Constants](../../c-runtime-library/errno-constants.md). +For more information about `errno` and error codes, see [`errno` constants](../errno-constants.md). -In C++, these functions have template overloads that invoke the newer, more secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, more secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tsearchenv**|**_searchenv**|**_searchenv**|**_wsearchenv**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tsearchenv` | **`_searchenv`** | **`_searchenv`** | **`_wsearchenv`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_searchenv**|\| -|**_wsearchenv**|\ or \| +| Routine | Required header | +|---|---| +| **`_searchenv`** | \ | +| **`_wsearchenv`** | \ or \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -124,7 +124,7 @@ C:\Program Files\Microsoft Visual Studio 8\VC\BIN\CL.EXE ## See also -[Directory Control](../../c-runtime-library/directory-control.md)
-[getenv, _wgetenv](getenv-wgetenv.md)
-[_putenv, _wputenv](putenv-wputenv.md)
-[_searchenv_s, _wsearchenv_s](searchenv-s-wsearchenv-s.md)
+[Directory control](../directory-control.md)\ +[`getenv`, `_wgetenv`](getenv-wgetenv.md)\ +[`_putenv`, `_wputenv`](putenv-wputenv.md)\ +[`_searchenv_s`, `_wsearchenv_s`](searchenv-s-wsearchenv-s.md) diff --git a/docs/c-runtime-library/reference/security-init-cookie.md b/docs/c-runtime-library/reference/security-init-cookie.md index a3fa0ecc9b2..d7a8743b593 100644 --- a/docs/c-runtime-library/reference/security-init-cookie.md +++ b/docs/c-runtime-library/reference/security-init-cookie.md @@ -23,7 +23,7 @@ void __security_init_cookie(void); The global security cookie is used for buffer overrun protection in code compiled with [/GS (Buffer Security Check)](../../build/reference/gs-buffer-security-check.md) and in code that uses exception handling. On entry to an overrun-protected function, the cookie is put on the stack, and on exit, the value on the stack is compared with the global cookie. Any difference between them indicates that a buffer overrun has occurred and causes immediate termination of the program. -Normally, **`__security_init_cookie`** is called by the CRT when it's initialized. If you bypass CRT initialization—for example, if you use [`/ENTRY`](../../build/reference/entry-entry-point-symbol.md) to specify an entry-point—then you must call **`__security_init_cookie`** yourself. If **`__security_init_cookie`** isn't called, the global security cookie is set to a default value and buffer overrun protection is compromised. Because an attacker can exploit this default cookie value to defeat the buffer overrun checks, we recommend that you always call **`__security_init_cookie`** when you define your own entry point. +Normally, **`__security_init_cookie`** is called by the CRT when it's initialized. If you bypass CRT initialization—for example, if you use [`/ENTRY`](../../build/reference/entry-entry-point-symbol.md) to specify an entry-point—then you must call **`__security_init_cookie`** yourself. If **`__security_init_cookie`** isn't called, the global security cookie is set to a default value, and buffer overrun protection is compromised. Because an attacker can exploit this default cookie value to defeat the buffer overrun checks, we recommend that you always call **`__security_init_cookie`** when you define your own entry point. The call to **`__security_init_cookie`** must be made before any overrun-protected function is entered; otherwise a spurious buffer overrun will be detected. For more information, see [C Runtime Error R6035](../../error-messages/tool-errors/c-runtime-error-r6035.md). @@ -33,11 +33,11 @@ See the examples in [C Runtime Error R6035](../../error-messages/tool-errors/c-r ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`__security_init_cookie`**|``| +| Routine | Required header | +|---|---| +| **`__security_init_cookie`** | `` | -**`__security_init_cookie`** is a Microsoft extension to the standard C Runtime Library. For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +**`__security_init_cookie`** is a Microsoft extension to the standard C Runtime Library. For compatibility information, see [Compatibility](../compatibility.md). ## See also diff --git a/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md b/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md index bd7906b5c92..f25e172109f 100644 --- a/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md +++ b/docs/c-runtime-library/reference/seh-filter-dll-seh-filter-exe.md @@ -3,14 +3,14 @@ description: "Learn more about: _seh_filter_dll, _seh_filter_exe" title: "_seh_filter_dll, _seh_filter_exe" ms.date: "4/2/2020" api_name: ["_XcptFilter", "_seh_filter_dll", "_seh_filter_exe", "_o__seh_filter_dll", "_o__seh_filter_exe"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["XcptFilter", "_XcptFilter", "_seh_filter_dll", "_seh_filter_exe", "corecrt_startup/_seh_filter_exe", "corecrt_startup/_seh_filter_dll"] helpviewer_keywords: ["XcptFilter function", "_XcptFilter function", "_seh_filter_dll function", "_seh_filter_exe function"] ms.assetid: 747e5963-3a12-4bf5-b5c4-d4c1b6068e15 --- -# _seh_filter_dll, _seh_filter_exe +# `_seh_filter_dll`, `_seh_filter_exe` Identifies the exception and the related action to be taken. @@ -18,24 +18,24 @@ Identifies the exception and the related action to be taken. ```C int __cdecl _seh_filter_dll( - unsigned long _ExceptionNum, - struct _EXCEPTION_POINTERS* _ExceptionPtr + unsigned long exceptionNum, + struct _EXCEPTION_POINTERS* exceptionPtr ); int __cdecl _seh_filter_exe( - unsigned long _ExceptionNum, - struct _EXCEPTION_POINTERS* _ExceptionPtr + unsigned long exceptionNum, + struct _EXCEPTION_POINTERS* exceptionPtr ); ``` ### Parameters -*_ExceptionNum*
+*`exceptionNum`*\ The identifier for the exception. -*_ExceptionPtr*
+*`exceptionPtr`*\ A pointer to the exception information. -## Return Value +## Return value An integer that indicates the action to be taken, based on the result of exception processing. @@ -43,20 +43,20 @@ An integer that indicates the action to be taken, based on the result of excepti These methods are called by the exception-filter expression of the [try-except Statement](../../cpp/try-except-statement.md). The method consults a constant internal table to identify the exception and determine the appropriate action, as shown here. The exception numbers are defined in winnt.h and the signal numbers are defined in signal.h. -|Exception Number (unsigned long)|Signal Number| -|----------------------------------------|-------------------| -|STATUS_ACCESS_VIOLATION|SIGSEGV| -|STATUS_ILLEGAL_INSTRUCTION|SIGILL| -|STATUS_PRIVILEGED_INSTRUCTION|SIGILL| -|STATUS_FLOAT_DENORMAL_OPERAND|SIGFPE| -|STATUS_FLOAT_DIVIDE_BY_ZERO|SIGFPE| -|STATUS_FLOAT_INEXACT_RESULT|SIGFPE| -|STATUS_FLOAT_INVALID_OPERATION|SIGFPE| -|STATUS_FLOAT_OVERFLOW|SIGFPE| -|STATUS_FLOAT_STACK_CHECK|SIGFPE| -|STATUS_FLOAT_UNDERFLOW|SIGFPE| - -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +| Exception number (unsigned long) | Signal number | +|---|---| +| `STATUS_ACCESS_VIOLATION` | `SIGSEGV` | +| `STATUS_ILLEGAL_INSTRUCTION` | `SIGILL` | +| `STATUS_PRIVILEGED_INSTRUCTION` | `SIGILL` | +| `STATUS_FLOAT_DENORMAL_OPERAND` | `SIGFPE` | +| `STATUS_FLOAT_DIVIDE_BY_ZERO` | `SIGFPE` | +| `STATUS_FLOAT_INEXACT_RESULT` | `SIGFPE` | +| `STATUS_FLOAT_INVALID_OPERATION` | `SIGFPE` | +| `STATUS_FLOAT_OVERFLOW` | `SIGFPE` | +| `STATUS_FLOAT_STACK_CHECK` | `SIGFPE` | +| `STATUS_FLOAT_UNDERFLOW` | `SIGFPE` | + +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements @@ -64,4 +64,4 @@ By default, this function's global state is scoped to the application. To change ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md) diff --git a/docs/c-runtime-library/reference/set-abort-behavior.md b/docs/c-runtime-library/reference/set-abort-behavior.md index 6eaa4d55518..dc00ccec9be 100644 --- a/docs/c-runtime-library/reference/set-abort-behavior.md +++ b/docs/c-runtime-library/reference/set-abort-behavior.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: _set_abort_behavior" title: "_set_abort_behavior" -ms.date: "4/2/2020" +description: "Learn more about: _set_abort_behavior" +ms.date: 07/07/2022 api_name: ["_set_abort_behavior", "_o__set_abort_behavior"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_set_abort_behavior", "set_abort_behavior"] +f1_keywords: ["STDLIB/_set_abort_behavior", "_set_abort_behavior", "set_abort_behavior"] helpviewer_keywords: ["aborting programs", "_set_abort_behavior function", "set_abort_behavior function"] --- -# _set_abort_behavior +# `_set_abort_behavior` Specifies the action to be taken when a program is abnormally terminated. > [!NOTE] -> Do not use the [abort](abort.md) function to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/legal/windows/agreements/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). +> Do not use the [`abort`](abort.md) function to shut down a Microsoft Store app, except in testing or debugging scenarios. Programmatic or UI ways to close a Store app are not permitted according to the [Microsoft Store policies](/windows/apps/publish/store-policies). For more information, see [UWP app lifecycle](/windows/uwp/launch-resume/app-lifecycle). ## Syntax @@ -27,29 +27,31 @@ unsigned int _set_abort_behavior( ### Parameters -*flags*
-New value of the [abort](abort.md) flags. +*`flags`*\ +New value of the `abort` flags. -*mask*
-Mask for the [abort](abort.md) flags bits to set. +*`mask`*\ +Mask for the `abort` flags bits to set. -## Return Value +## Return value The old value of the flags. ## Remarks -There are two [abort](abort.md) flags: **_WRITE_ABORT_MSG** and **_CALL_REPORTFAULT**. **_WRITE_ABORT_MSG** determines whether a helpful text message is printed when a program is abnormally terminated. The message states that the application has called the [abort](abort.md) function. The default behavior is to print the message. **_CALL_REPORTFAULT**, if set, specifies that a Watson crash dump is generated and reported when [abort](abort.md) is called. By default, crash dump reporting is enabled in non-DEBUG builds. +There are two [`abort`](abort.md) flags: `_WRITE_ABORT_MSG` and `_CALL_REPORTFAULT`. `_WRITE_ABORT_MSG` determines whether a helpful text message is printed when a program is abnormally terminated. The message states that the application has called the `abort` function. The default behavior is to print the message. `_CALL_REPORTFAULT`, if set, invokes the Windows Error Reporting Service mechanism (formerly known as Dr. Watson) to report failures to Microsoft when `abort` is called. By default, crash dump reporting is enabled in non-DEBUG builds. If the Windows error reporting handler isn't invoked, then `abort` calls [`_exit`](exit-exit-exit.md) to terminate the process with exit code 3 and returns control to the parent process or the operating system. `_exit` doesn't flush stream buffers or do `atexit`/`_onexit` processing. + +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-conforming behavior. Conforming behavior may come at some cost in Windows compatibility. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change it, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_abort_behavior**|\| +| Routine | Required header | +|--|--| +| **`_set_abort_behavior`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -74,4 +76,4 @@ Suppressing the abort message. If successful, this message will be the only outp ## See also -[abort](abort.md)
+[`abort`](abort.md) diff --git a/docs/c-runtime-library/reference/set-controlfp.md b/docs/c-runtime-library/reference/set-controlfp.md index 5da13d46c5a..b7cfc47680a 100644 --- a/docs/c-runtime-library/reference/set-controlfp.md +++ b/docs/c-runtime-library/reference/set-controlfp.md @@ -10,7 +10,7 @@ f1_keywords: ["set_controlfp", "_set_controlfp"] helpviewer_keywords: ["set_controlfp function", "floating-point functions, setting control word", "_set_controlfp function"] ms.assetid: e0689d50-f68a-4028-a9c1-fb23eedee4ad --- -# _set_controlfp +# `_set_controlfp` Sets the floating-point control word. @@ -25,32 +25,32 @@ void __cdecl _set_controlfp( ### Parameters -*newControl*
+*`newControl`*\ New control-word bit values. -*mask*
+*`mask`*\ Mask for new control-word bits to set. -## Return Value +## Return value None. ## Remarks -The **_set_controlfp** function is similar to **_control87**, but it only sets the floating-point control word to *newControl*. The bits in the values indicate the floating-point control state. The floating-point control state allows the program to change the precision, rounding, and infinity modes in the floating-point math package. You can also mask or unmask floating-point exceptions using **_set_controlfp**. For more information, see [_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md). +The **`_set_controlfp`** function is similar to `_control87`, but it only sets the floating-point control word to *`newControl`*. The bits in the values indicate the floating-point control state. The floating-point control state allows the program to change the precision, rounding, and infinity modes in the floating-point math package. You can also mask or unmask floating-point exceptions using **`_set_controlfp`**. For more information, see [`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md). This function is deprecated when compiling with [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime only supports the default floating-point precision. ## Requirements -|Routine|Required header|Compatibility| -|-------------|---------------------|-------------------| -|**_set_controlfp**|\|x86 processor only| +| Routine | Required header | Compatibility | +|---|---|---| +| **`_set_controlfp`** | \ | x86 processor only | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_clear87, _clearfp](clear87-clearfp.md)
-[_status87, _statusfp, _statusfp2](status87-statusfp-statusfp2.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_clear87`, `_clearfp`](clear87-clearfp.md)\ +[`_status87`, `_statusfp`, `_statusfp2`](status87-statusfp-statusfp2.md) diff --git a/docs/c-runtime-library/reference/set-doserrno.md b/docs/c-runtime-library/reference/set-doserrno.md index 6e3161cb1cc..f6a0914ae67 100644 --- a/docs/c-runtime-library/reference/set-doserrno.md +++ b/docs/c-runtime-library/reference/set-doserrno.md @@ -3,16 +3,16 @@ description: "Learn more about: _set_doserrno" title: "_set_doserrno" ms.date: "4/2/2020" api_name: ["_set_doserrno", "_o__set_doserrno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_set_doserrno", "set_doserrno"] helpviewer_keywords: ["_set_doserrno function", "doserrno global variable", "set_doserrno function", "_doserrno global variable"] ms.assetid: 8686c159-3797-4705-a53e-7457869ca6f3 --- -# _set_doserrno +# `_set_doserrno` -Sets the value of the [_doserrno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) global variable. +Sets the value of the [`_doserrno`](../errno-doserrno-sys-errlist-and-sys-nerr.md) global variable. ## Syntax @@ -22,10 +22,10 @@ errno_t _set_doserrno( int error_value ); ### Parameters -*error_value*
-The new value of **_doserrno**. +*`error_value`*\ +The new value of `_doserrno`. -## Return Value +## Return value Returns zero if successful. @@ -33,17 +33,17 @@ Returns zero if successful. Possible values are defined in Errno.h. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_set_doserrno**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_set_doserrno`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_get_doserrno](get-doserrno.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
+[`_get_doserrno`](get-doserrno.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) diff --git a/docs/c-runtime-library/reference/set-errno.md b/docs/c-runtime-library/reference/set-errno.md index 44f0decedae..ed95b0eda68 100644 --- a/docs/c-runtime-library/reference/set-errno.md +++ b/docs/c-runtime-library/reference/set-errno.md @@ -3,16 +3,16 @@ description: "Learn more about: _set_errno" title: "_set_errno" ms.date: "4/2/2020" api_name: ["_set_errno", "_o__set_errno"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_errno", "_set_errno"] helpviewer_keywords: ["errno global variable", "set_errno function", "_set_errno function"] ms.assetid: d338914a-1894-4cf3-ae45-f2c4eb26590b --- -# _set_errno +# `_set_errno` -Set the value of the **errno** global variable. +Set the value of the `errno` global variable. ## Syntax @@ -22,18 +22,18 @@ errno_t _set_errno( int error_value ); ### Parameters -*error_value*
-The new value of **errno**. +*`error_value`*\ +The new value of `errno`. -## Return Value +## Return value Returns zero if successful. ## Remarks -Possible values are defined in Errno.h. Also, see [errno Constants](../../c-runtime-library/errno-constants.md). +Possible values are defined in Errno.h. Also, see [`errno` constants](../errno-constants.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Example @@ -55,13 +55,13 @@ Oops: Illegal byte sequence ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_set_errno**|\|\| +| Routine | Required header | Optional header | +|---|---|---| +| **`_set_errno`** | \ | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_get_errno](get-errno.md)
-[errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md)
+[`_get_errno`](get-errno.md)\ +[`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) diff --git a/docs/c-runtime-library/reference/set-error-mode.md b/docs/c-runtime-library/reference/set-error-mode.md index 17cabeeeeb0..28766500919 100644 --- a/docs/c-runtime-library/reference/set-error-mode.md +++ b/docs/c-runtime-library/reference/set-error-mode.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _set_error_mode" title: "_set_error_mode" -ms.date: "11/04/2016" +description: "Learn more about: _set_error_mode" +ms.date: 11/04/2016 api_name: ["_set_error_mode"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_error_mode", "_set_error_mode"] helpviewer_keywords: ["_set_error_mode function", "set_error_mode function"] -ms.assetid: f0807be5-73d1-4a32-a701-3c9bdd139c5c --- -# _set_error_mode +# `_set_error_mode` -Modifies **__error_mode** to determine a non-default location where the C runtime writes an error message for an error that might end the program. +Modifies `__error_mode` to determine a non-default location where the C runtime writes an error message for an error that might end the program. > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -27,41 +26,41 @@ int _set_error_mode( ### Parameters -*mode_val*
+*`mode_val`*\ Destination of error messages. -## Return Value +## Return value Returns the old setting or -1 if an error occurs. ## Remarks -Controls the error output sink by setting the value of **__error_mode**. For example, you can direct output to a standard error or use the **MessageBox** API. +Controls the error output sink by setting the value of `__error_mode`. For example, you can direct output to a standard error or use the `MessageBox` API. -The *mode_val* parameter can be set to one of the following values. +The *`mode_val`* parameter can be set to one of the following values. -|Value|Description| -|---------------|-----------------| -|**_OUT_TO_DEFAULT**|Error sink is determined by **__app_type**.| -|**_OUT_TO_STDERR**|Error sink is a standard error.| -|**_OUT_TO_MSGBOX**|Error sink is a message box.| -|**_REPORT_ERRMODE**|Report the current **__error_mode** value.| +| Value | Description | +|---|---| +| `_OUT_TO_DEFAULT` | Error sink is determined by `__app_type`. | +| `_OUT_TO_STDERR` | Error sink is a standard error. | +| `_OUT_TO_MSGBOX` | Error sink is a message box. | +| `_REPORT_ERRMODE` | Report the current `__error_mode` value. | -If a value other than those listed is passed in, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **_set_error_mode** sets **errno** to **EINVAL** and returns -1. +If a value is passed in other than the listed ones, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_set_error_mode`** sets `errno` to `EINVAL` and returns -1. -When it's used with an [assert](assert-macro-assert-wassert.md), **_set_error_mode** displays the failed statement in the dialog box and gives you the option of choosing the **Ignore** button so that you can continue to run the program. +When it's used with an [`assert`](assert-macro-assert-wassert.md), **`_set_error_mode`** displays the statement that failed in the dialog box, and gives you the option of choosing the **Ignore** button, so that you can continue to run the program. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_error_mode**|\| +| Routine | Required header | +|---|---| +| **`_set_error_mode`** | \ | ## Example ```C // crt_set_error_mode.c -// compile with: /c + #include #include @@ -81,4 +80,4 @@ Please contact the application's support team for more information. ## See also -[assert Macro, _assert, _wassert](assert-macro-assert-wassert.md)
+[assert Macro, _assert, _wassert](assert-macro-assert-wassert.md) diff --git a/docs/c-runtime-library/reference/set-fmode.md b/docs/c-runtime-library/reference/set-fmode.md index e2a8410d3f7..8082bfd3739 100644 --- a/docs/c-runtime-library/reference/set-fmode.md +++ b/docs/c-runtime-library/reference/set-fmode.md @@ -3,14 +3,14 @@ description: "Learn more about: _set_fmode" title: "_set_fmode" ms.date: "4/2/2020" api_name: ["_set_fmode", "_o__set_fmode"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_set_fmode", "set_fmode"] helpviewer_keywords: ["file translation [C++], default mode", "_set_fmode function", "file translation [C++], setting mode", "set_fmode function"] ms.assetid: f80eb9c7-733b-4652-a9bc-6b3790a35f12 --- -# _set_fmode +# `_set_fmode` Sets the default file translation mode for file I/O operations. @@ -24,28 +24,28 @@ errno_t _set_fmode( ### Parameters -*mode*
-The file translation mode desired: **_O_TEXT** or **_O_BINARY**. +*`mode`*\ +The file translation mode desired: `_O_TEXT` or `_O_BINARY`. -## Return Value +## Return value -Returns zero if successful, an error code on failure. If *mode* is not **_O_TEXT** or **_O_BINARY** or **_O_WTEXT**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function sets **errno** to **EINVAL** and returns **EINVAL**. +Returns zero if successful, an error code on failure. If *`mode`* isn't `_O_TEXT` or `_O_BINARY` or `_O_WTEXT`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function sets `errno` to `EINVAL` and returns `EINVAL`. ## Remarks -The function sets the [_fmode](../../c-runtime-library/fmode.md) global variable. This variable specifies the default file translation mode for the file I/O operations **_open** and **_pipe**. +The function sets the [`_fmode`](../fmode.md) global variable. This variable specifies the default file translation mode for the file I/O operations `_open` and `_pipe`. -**_O_TEXT** and **_O_BINARY** are defined in Fcntl.h. **EINVAL** is defined in Errno.h. +`_O_TEXT` and `_O_BINARY` are defined in Fcntl.h. `EINVAL` is defined in Errno.h. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_set_fmode**|\|\, \| +| Routine | Required header | Optional header | +|---|---|---| +| **`_set_fmode`** | \ | \, \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -112,7 +112,7 @@ A B C D E F G H I J K L ## See also -[_fmode](../../c-runtime-library/fmode.md)
-[_get_fmode](get-fmode.md)
-[_setmode](setmode.md)
-[Text and Binary Mode File I/O](../../c-runtime-library/text-and-binary-mode-file-i-o.md)
+[`_fmode`](../fmode.md)\ +[`_get_fmode`](get-fmode.md)\ +[`_setmode`](setmode.md)\ +[Text and binary mode file I/O](../text-and-binary-mode-file-i-o.md) diff --git a/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md b/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md index 239612d92e5..62c3ec01d46 100644 --- a/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md +++ b/docs/c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md @@ -3,14 +3,14 @@ title: "_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_hand description: "API reference for _set_invalid_parameter_handler, and _set_thread_local_invalid_parameter_handler; which set a function to be called when the CRT detects an invalid argument." ms.date: "4/2/2020" api_name: ["_set_invalid_parameter_handler", "_set_thread_local_invalid_parameter_handler", "_o__set_invalid_parameter_handler", "_o__set_thread_local_invalid_parameter_handler"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["set_invalid_parameter_handler", "_set_invalid_parameter_handler", "_set_thread_local_invalid_parameter_handler"] helpviewer_keywords: ["invalid parameter handler", "set_invalid_parameter_handler function", "_set_invalid_parameter_handler function", "_set_thread_local_invalid_parameter_handler function"] ms.assetid: c0e67934-1a41-4016-ad8e-972828f3ac11 --- -# _set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler +# `_set_invalid_parameter_handler`, `_set_thread_local_invalid_parameter_handler` Sets a function to be called when the CRT detects an invalid argument. @@ -27,18 +27,18 @@ _invalid_parameter_handler _set_thread_local_invalid_parameter_handler( ### Parameters -*pNew*
+*`pNew`*\ The function pointer to the new invalid parameter handler. -## Return Value +## Return value A pointer to the invalid parameter handler before the call. ## Remarks -Many C runtime functions check the validity of arguments passed to them. If an invalid argument is passed, the function can set the **errno** error number or return an error code. In such cases, the invalid parameter handler is also called. The C runtime supplies a default global invalid parameter handler that terminates the program and displays a runtime error message. You can use the **_set_invalid_parameter_handler** to set your own function as the global invalid parameter handler. The C runtime also supports a thread-local invalid parameter handler. If a thread-local parameter handler is set in a thread by using **_set_thread_local_invalid_parameter_handler**, the C runtime functions called from the thread use that handler instead of the global handler. Only one function can be specified as the global invalid argument handler at a time. Only one function can be specified as the thread-local invalid argument handler per thread, but different threads can have different thread-local handlers. This allows you to change the handler used in one part of your code without affecting the behavior of other threads. +Many C runtime functions check the validity of arguments passed to them. If an invalid argument is passed, the function can set the `errno` error number or return an error code. In such cases, the invalid parameter handler is also called. The C runtime supplies a default global invalid parameter handler that terminates the program and displays a runtime error message. You can use the **`_set_invalid_parameter_handler`** to set your own function as the global invalid parameter handler. The C runtime also supports a thread-local invalid parameter handler. If a thread-local parameter handler is set in a thread by using **`_set_thread_local_invalid_parameter_handler`**, the C runtime functions called from the thread use that handler instead of the global handler. Only one function can be specified as the global invalid argument handler at a time. Only one function can be specified as the thread-local invalid argument handler per thread, but different threads can have different thread-local handlers. Thread local handlers allow you to change the handler used in one part of your code without affecting the behavior of other threads. -When the runtime calls the invalid parameter function, it usually means that a nonrecoverable error occurred. The invalid parameter handler function you supply should save any data it can and then abort. It should not return control to the main function unless you're confident that the error is recoverable. +When the runtime calls the invalid parameter function, it usually means that a nonrecoverable error occurred. The invalid parameter handler function you supply should save any data it can and then abort. It shouldn't return control to the main function unless you're confident that the error is recoverable. The invalid parameter handler function must have the following prototype: @@ -52,21 +52,21 @@ void _invalid_parameter( ); ``` -The *expression* argument is a wide string representation of the argument expression that raised the error. The *function* argument is the name of the CRT function that received the invalid argument. The *file* argument is the name of the CRT source file that contains the function. The *line* argument is the line number in that file. The last argument is reserved. The parameters all have the value **NULL** unless a debug version of the CRT library is used. +The *`expression`* argument is a wide string representation of the argument expression that raised the error. The *`function`* argument is the name of the CRT function that received the invalid argument. The *`file`* argument is the name of the CRT source file that contains the function. The *`line`* argument is the line number in that file. The last argument is reserved. The parameters all have the value `NULL` unless a debug version of the CRT library is used. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_set_invalid_parameter_handler**, **_set_thread_local_invalid_parameter_handler**|C: \

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

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

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

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

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

C++: \, \, \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use sprintf_s to format data @@ -176,10 +176,10 @@ wrote -1 characters ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md b/docs/c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md index a80186727b3..f386fc7dfd5 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" title: "sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l" -ms.date: "3/9/2021" -api_name: ["__swprintf_l", "sprintf", "_sprintf_l", "_swprintf_l", "swprintf"] +description: "Learn more about: sprintf, _sprintf_l, swprintf, _swprintf, _swprintf_l, __swprintf_l" +ms.date: 3/9/2021 +api_name: ["__swprintf_l", "sprintf", "_sprintf_l", "_swprintf_l", "swprintf", "_swprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_stprintf_l", "__swprintf_l", "sprintf_l", "swprintf", "_sprintf_l", "sprintf", "_stprintf", "stprintf_l"] -helpviewer_keywords: ["_swprintf_l function", "_stprintf function", "__swprintf_l function", "stprintf function", "sprintf function", "_sprintf_l function", "_stprintf_l function", "swprintf function", "strings [C++], writing to", "_CRT_NON_CONFORMING_SWPRINTFS", "swprintf_l function", "stprintf_l function", "sprintf_l function", "formatted text [C++]"] +f1_keywords: ["_stprintf_l", "__swprintf_l", "sprintf_l", "_swprintf", "swprintf", "_sprintf_l", "sprintf", "_stprintf", "stprintf_l"] +helpviewer_keywords: ["_swprintf_l function", "_stprintf function", "__swprintf_l function", "stprintf function", "sprintf function", "_sprintf_l function", "_stprintf_l function", "swprintf function", "_swprintf function", "strings [C++], writing to", "_CRT_NON_CONFORMING_SWPRINTFS", "swprintf_l function", "stprintf_l function", "sprintf_l function", "formatted text [C++]"] --- -# `sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l` +# `sprintf`, `_sprintf_l`, `swprintf`, `_swprintf`, `_swprintf_l`, `__swprintf_l` Write formatted data to a string. More secure versions of some of these functions are available; see [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md). The secure versions of **`swprintf`** and **`_swprintf_l`** take the size of the buffer as a parameter. @@ -21,18 +21,27 @@ int sprintf( const char *format [, argument] ... ); + int _sprintf_l( char *buffer, const char *format, _locale_t locale [, argument] ... ); + int swprintf( wchar_t *buffer, size_t count, const wchar_t *format [, argument]... ); + +int _swprintf( + wchar_t *buffer, + const wchar_t *format [, + argument]... +); + int _swprintf_l( wchar_t *buffer, size_t count, @@ -40,18 +49,21 @@ int _swprintf_l( _locale_t locale [, argument] ... ); + int __swprintf_l( wchar_t *buffer, const wchar_t *format, _locale_t locale [, argument] ... ); + template int sprintf( char (&buffer)[size], const char *format [, argument] ... ); // C++ only + template int _sprintf_l( char (&buffer)[size], @@ -63,26 +75,26 @@ int _sprintf_l( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for output -*`count`*
+*`count`*\ Maximum number of characters to store in the Unicode version of this function. -*`format`*
+*`format`*\ Format-control string -*`argument`*
+*`argument`*\ Optional arguments -*`locale`*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The number of characters written, or -1 if an error occurred. If *`buffer`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +The number of characters written, or -1 if an error occurred. If *`buffer`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. **`sprintf`** returns the number of bytes stored in *`buffer`*, not counting the terminating null character. **`swprintf`** returns the number of wide characters stored in *`buffer`*, not counting the terminating null wide character. @@ -91,31 +103,31 @@ The number of characters written, or -1 if an error occurred. If *`buffer`* or * The **`sprintf`** function formats and stores a series of characters and values in *`buffer`*. Each *`argument`* (if any) is converted and output according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). A null character is appended after the last character written. If copying occurs between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> Using **`sprintf`**, there is no way to limit the number of characters written, which means that code using **`sprintf`** is susceptible to buffer overruns. Consider using the related function [`_snprintf`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md), which specifies a maximum number of characters to write to *`buffer`*, or use [`_scprintf`](scprintf-scprintf-l-scwprintf-scwprintf-l.md) to determine how large a buffer is required. Also, ensure that *`format`* is not a user-defined string. +> Using **`sprintf`**, there is no way to limit the number of characters written, which means that code using **`sprintf`** is susceptible to buffer overruns. Consider using the related function [`snprintf`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md), which specifies a maximum number of characters to write to *`buffer`*, or use [`_scprintf`](scprintf-scprintf-l-scwprintf-scwprintf-l.md) to determine how large a buffer is required. Also, ensure that *`format`* is not a user-defined string. > -> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -**`swprintf`** is a wide-character version of **`sprintf`**; the pointer arguments to **`swprintf`** are wide-character strings. Detection of encoding errors in **`swprintf`** may differ from **`sprintf`**. **`swprintf`** and **`fwprintf`** behave identically except **`swprintf`** writes output to a string rather than to a destination of type **`FILE`**, and **`swprintf`** requires the *count* parameter to specify the maximum number of characters to write. The versions of these functions with the **`_l`** suffix are identical except they use the locale parameter passed in instead of the current thread locale. +**`swprintf`** is a wide-character version of **`sprintf`**; the pointer arguments to **`swprintf`** are wide-character strings. Detection of encoding errors in **`swprintf`** may differ from **`sprintf`**. **`swprintf`** and **`fwprintf`** behave identically except **`swprintf`** writes output to a string rather than to a destination of type `FILE`, and **`swprintf`** requires the *`count`* parameter to specify the maximum number of characters to write. The versions of these functions with the **`_l`** suffix are identical except they use the locale parameter passed in instead of the current thread locale. -**`swprintf`** conforms to the ISO C Standard, which requires the second parameter, *`count`*, of type **`size_t`**. To force the old nonstandard behavior, define **`_CRT_NON_CONFORMING_SWPRINTFS`**. In a future version, the old behavior may be removed, so code should be changed to use the new conformant behavior. +Before the signature for `swprintf` was standardized, a version shipped in an older Microsoft C runtime library that didn't take the character count parameter. The older version is still available in the Microsoft C runtime library, but it's deprecated and was renamed `_swprintf()`. For code that was written against the older signature, define `_CRT_NON_CONFORMING_SWPRINTFS`, which maps calls to `swprintf` to `_swprintf`. In a future version, the old behavior may be removed, so code should be changed to use the new conformant behavior. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_stprintf`**|**`sprintf`**|**`sprintf`**|**`_swprintf`**| -|**`_stprintf_l`**|**`_sprintf_l`**|**`_sprintf_l`**|**`__swprintf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_stprintf`** | **`sprintf`** | **`sprintf`** | **`_swprintf`** | +| **`_stprintf_l`** | **`_sprintf_l`** | **`_sprintf_l`** | **`__swprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`sprintf`**, **`_sprintf_l`**|``| -|**`swprintf`**, **`_swprintf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`sprintf`**, **`_sprintf_l`** | `` | +| **`swprintf`**, **`_swprintf`**, **`_swprintf_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use `sprintf` to format data @@ -180,9 +192,9 @@ wrote -1 characters ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md b/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md index e8e0e4ef6c3..2e1c685b8e5 100644 --- a/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md +++ b/docs/c-runtime-library/reference/sqrt-sqrtf-sqrtl.md @@ -1,9 +1,9 @@ --- title: "sqrt, sqrtf, sqrtl" description: "API reference for sqrt, sqrtf, and sqrtl; which calculate a square root of a floating point number." -ms.date: "08/31/2020" +ms.date: 08/31/2020 api_name: ["sqrtl", "sqrtf", "sqrt", "_o_sqrt", "_o_sqrtf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["sqrt", "sqrtf", "_sqrtl"] @@ -31,7 +31,7 @@ float sqrtf( long double sqrtl( long double x ); -#define sqrt(x) // Requires C11 or higher +#define sqrt(x) // Requires C11 or later ``` ### Parameters @@ -43,28 +43,28 @@ Non-negative floating-point value Because C++ allows overloading, you can call overloads of **`sqrt`** that take **`float`** or **`long double`** types. In a C program, unless you're using the `` macro to call this function, **`sqrt`** always takes and returns **`double`**. -If you use the ` sqrt()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the ` sqrt()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -## Return Value +## Return value The **`sqrt`** functions return the square-root of *`x`*. By default, if *`x`* is negative, **`sqrt`** returns an indefinite `NaN`. -|Input|SEH Exception|**`_matherr`** Exception| -|-----------|-------------------|--------------------------| -|± `QNAN`,`IND`|none|`_DOMAIN`| -|- ∞|none|`_DOMAIN`| -|`x<0`|none|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | +| - INF | none | `_DOMAIN` | +| `x < 0` | none | `_DOMAIN` | ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**`sqrt`**, **`sqrtf`**, **`sqrtl`**|``|``| -|**`sqrt()`** macro | `` || +| Function | C header | C++ header | +|---|---|---| +| **`sqrt`**, **`sqrtf`**, **`sqrtl`** | `` | `` | +| **`sqrt`** macro | `` | | -For compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -93,8 +93,8 @@ The square root of 45.35 is 6.73 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`exp`, `expf`, `expl`](exp-expf.md)\ [`log`, `logf`, `log10`, `log10f`](log-logf-log10-log10f.md)\ [`pow`, `powf`, `powl`](pow-powf-powl.md)\ -[`_CIsqrt`](../../c-runtime-library/cisqrt.md)\ +[`_CIsqrt`](../cisqrt.md) diff --git a/docs/c-runtime-library/reference/srand.md b/docs/c-runtime-library/reference/srand.md index d32df47b746..018def508b1 100644 --- a/docs/c-runtime-library/reference/srand.md +++ b/docs/c-runtime-library/reference/srand.md @@ -3,7 +3,7 @@ description: "Learn more about: srand" title: "srand" ms.date: "4/2/2020" api_name: ["srand", "_o_srand"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["STDLIB/srand", "srand"] @@ -30,15 +30,15 @@ Seed for pseudorandom number generation The **`srand`** function sets the starting point for generating a series of pseudorandom integers in the current thread. To reinitialize the generator to create the same sequence of results, call the **`srand`** function and use the same *`seed`* argument again. Any other value for *`seed`* sets the generator to a different starting point in the pseudorandom sequence. **`rand`** retrieves the pseudorandom numbers that are generated. Calling **`rand`** before any call to **`srand`** generates the same sequence as calling **`srand`** with *`seed`* passed as 1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`srand`**|``| +| Routine | Required header | +|---|---| +| **`srand`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -46,5 +46,5 @@ See the example for [`rand`](rand.md). ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`rand`](rand.md) diff --git a/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md b/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md index 93e7f319c47..36b42b032c4 100644 --- a/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md +++ b/docs/c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md @@ -12,7 +12,7 @@ ms.assetid: 956e65c8-00a5-43e8-a2f2-0f547ac9e56c --- # `sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l` -Reads formatted data from a string. These versions of [`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from a string. These versions of [`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -43,38 +43,38 @@ int _swscanf_s_l( ### Parameters -*`buffer`*
+*`buffer`*\ Stored data -*`format`*
-Format-control string. For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). -*`argument`*
+*`argument`*\ Optional arguments -*`locale`*
+*`locale`*\ The locale to use -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **`EOF`** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *`buffer`* or *`format`* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`** +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL` -For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`sscanf_s`** function reads data from *`buffer`* into the location that's given by each *`argument`*. The arguments after the format string specify pointers to variables that have a type that corresponds to a type specifier in *format*. Unlike the less secure version [`sscanf`](sscanf-sscanf-l-swscanf-swscanf-l.md), a buffer size parameter is required when you use the type field characters **`c`**, **`C`**, **`s`**, **`S`**, or string control sets that are enclosed in **`[]`**. The buffer size in characters must be supplied as an additional parameter immediately after each buffer parameter that requires it. For example, if you are reading into a string, the buffer size for that string is passed as follows: +The **`sscanf_s`** function reads data from *`buffer`* into the location that's given by each *`argument`*. The arguments after the format string specify pointers to variables that have a type that corresponds to a type specifier in *`format`*. Unlike the less secure version [`sscanf`](sscanf-sscanf-l-swscanf-swscanf-l.md), a buffer size parameter is required when you use the type field characters **`c`**, **`C`**, **`s`**, **`S`**, or string control sets that are enclosed in **`[]`**. The buffer size in characters must be supplied as an extra parameter immediately after each buffer parameter that requires it. For example, if you're reading into a string, the buffer size for that string is passed as follows: ```C wchar_t ws[10]; swscanf_s(in_str, L"%9s", ws, (unsigned)_countof(ws)); // buffer size is 10, width specification is 9 ``` -The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer. +The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too large to fit in the buffer, nothing is written to that buffer. -In the case of characters, a single character may be read as follows: +A single character may be read as follows: ```C wchar_t wc; @@ -88,32 +88,32 @@ char c[4]; sscanf_s(input, "%4c", &c, (unsigned)_countof(c)); // not null terminated ``` -For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` Type Field Characters](../../c-runtime-library/scanf-type-field-characters.md). +For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` type field characters](../scanf-type-field-characters.md). > [!NOTE] > The size parameter is of type **`unsigned`**, not **`size_t`**. When compiling for 64-bit targets, use a static cast to convert **`_countof`** or **`sizeof`** results to the correct size. The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the **`scanf_s`** function. If copying occurs between strings that overlap, the behavior is undefined. -**`swscanf_s`** is a wide-character version of **`sscanf_s`**; the arguments to **`swscanf_s`** are wide-character strings. **`sscanf_s`** does not handle multibyte hexadecimal characters. **`swscanf_s`** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf_s`** and **`sscanf_s`** behave identically. +**`swscanf_s`** is a wide-character version of **`sscanf_s`**; the arguments to **`swscanf_s`** are wide-character strings. **`sscanf_s`** doesn't handle multibyte hexadecimal characters. **`swscanf_s`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf_s`** and **`sscanf_s`** behave identically. The versions of these functions that have the **`_l`** suffix are identical except that they use the locale parameter that's passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_stscanf_s`**|**`sscanf_s`**|**`sscanf_s`**|**`swscanf_s`**| -|**`_stscanf_s_l`**|**`_sscanf_s_l`**|**`_sscanf_s_l`**|**`_swscanf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_stscanf_s` | **`sscanf_s`** | **`sscanf_s`** | **`swscanf_s`** | +| `_stscanf_s_l` | **`_sscanf_s_l`** | **`_sscanf_s_l`** | **`_swscanf_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`sscanf_s`**, **`_sscanf_s_l`**|``| -|**`swscanf_s`**, **`_swscanf_s_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`sscanf_s`**, **`_sscanf_s_l`** | `` | +| **`swscanf_s`**, **`_swscanf_s_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -157,8 +157,8 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) diff --git a/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md b/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md index 7a35644c1ad..e51dab81d46 100644 --- a/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md +++ b/docs/c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md @@ -43,54 +43,54 @@ int _swscanf_l( ### Parameters -*`buffer`*
+*`buffer`*\ Stored data -*`format`*
-Format-control string. For more information, see [Format Specifications](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification syntax](../format-specification-fields-scanf-and-wscanf-functions.md). -*`argument`*
+*`argument`*\ Optional arguments -*`locale`*
+*`locale`*\ The locale to use -## Return Value +## Return value -Each of these functions returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **`EOF`** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *`buffer`* or *`format`* is a **`NULL`** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`sscanf`** function reads data from *`buffer`* into the location given by each *`argument`*. Every *`argument`* must be a pointer to a variable with a type that corresponds to a type specifier in *`format`*. The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the **`scanf`** function. If copying takes place between strings that overlap, the behavior is undefined. -For information about scanf type field characters, see [`scanf` Type Field Characters](../scanf-type-field-characters.md). For information about scanf format specification fields, see [Format Specification Fields](../format-specification-fields-scanf-and-wscanf-functions.md). +For information about scanf type field characters, see [`scanf` type field characters](../scanf-type-field-characters.md). For information about scanf format specification fields, see [Format specification fields](../format-specification-fields-scanf-and-wscanf-functions.md). > [!IMPORTANT] > When reading a string with **`sscanf`**, always specify a width for the **`%s`** format (for example, **"`%32s`"** instead of **"`%s`"**); otherwise, improperly formatted input can easily cause a buffer overrun. -**`swscanf`** is a wide-character version of **`sscanf`**; the arguments to **`swscanf`** are wide-character strings. **`sscanf`** does not handle multibyte hexadecimal characters. **`swscanf`** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf`** and **`sscanf`** behave identically. +**`swscanf`** is a wide-character version of **`sscanf`**; the arguments to **`swscanf`** are wide-character strings. **`sscanf`** doesn't handle multibyte hexadecimal characters. **`swscanf`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`swscanf`** and **`sscanf`** behave identically. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_stscanf`**|**`sscanf`**|**`sscanf`**|**`swscanf`**| -|**`_stscanf_l`**|**`_sscanf_l`**|**`_sscanf_l`**|**`_swscanf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_stscanf` | **`sscanf`** | **`sscanf`** | **`swscanf`** | +| `_stscanf_l` | **`_sscanf_l`** | **`_sscanf_l`** | **`_swscanf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`sscanf`**, **`_sscanf_l`**|``| -|**`swscanf`**, **`_swscanf_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`sscanf`**, **`_sscanf_l`** | `` | +| **`swscanf`**, **`_swscanf_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -135,8 +135,8 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) diff --git a/docs/c-runtime-library/reference/stat-functions.md b/docs/c-runtime-library/reference/stat-functions.md index 06d84d656f2..19b26217c48 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: 03/20/2026 api_name: ["_wstat64", "_stati64", "_stat32", "_stat32i64", "_stat", "_wstati64", "_wstat32", "_wstat64i32", "_wstat", "_stat64", "_stat64i32", "_wstat32i64", "_o__stat32", "_o__stat32i64", "_o__stat64", "_o__stat64i32", "_o__wstat32", "_o__wstat32i64", "_o__wstat64", "_o__wstat64i32"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tstat32", "tstat", "_tstat64i32", "tstati64", "_wstat64", "_wstat32", "wstati64", "tstat64", "_stati64", "_wstat", "wstat64i32", "stat32i64", "tstat32i64", "_tstat", "_wstati64", "_tstati64", "_wstat32i64", "wstat32", "_wstat64i32", "_stat", "_tstat32", "stat64i32", "wstat64", "stat", "_stat32i64", "_stat32", "stati64", "wstat", "_stat64i32", "stat32", "_tstat32i64", "tstat64i32", "_tstat64", "_stat64", "stat/_stat", "stat/_stat32", "stat/_stat64", "stat/_stati64", "stat/_stat32i64", "stat/_stat64i32", "stat/_wstat", "stat/_wstat32", "stat/_wstat64", "stat/_wstati64", "stat/_wstat32i64", "stat/_wstat64i32"] +f1_keywords: ["stat/_stat", "stat/_stat32", "stat/_stat32i64", "stat/_stat64", "stat/_stat64i32", "stat/_stati64", "stat/__stat64", "TCHAR/_tstat", "TCHAR/_tstat32", "TCHAR/_tstat32i64", "TCHAR/_tstat64", "TCHAR/_tstat64i32", "TCHAR/_tstati64", "stat/_wstat", "stat/_wstat32", "stat/_wstat32i64", "stat/_wstat64", "stat/_wstat64i32", "stat/_wstati64", "_stat", "_stat32", "_stat32i64", "_stat64", "_stat64i32", "_stati64", "__stat64", "_tstat", "_tstat32", "_tstat32i64", "_tstat64", "_tstat64i32", "_tstati64", "_wstat", "_wstat32", "_wstat32i64", "_wstat64", "_wstat64i32", "_wstati64", "stat", "stat32", "stat32i64", "stat64", "stat64i32", "stati64", "tstat", "tstat32", "tstat32i64", "tstat64", "tstat64i32", "tstati64", "wstat", "wstat32", "wstat32i64", "wstat64", "wstat64i32", "wstati64"] helpviewer_keywords: ["files [C++], status information", "_stat function", "_wstat function", "_stat64i32 function", "tstat function", "_tstat64i32 function", "_stati64 function", "_stat64 function", "tstati64 function", "wstati64 function", "wstat64 function", "_wstat64i32 function", "_tstat32i64 function", "_stat32i64 function", "stat function", "status of files", "_tstat32 function", "tstat64 function", "_wstat64 function", "_tstat function", "_stat32 function", "wstat function", "_wstat32i64 function", "_tstati64 function", "_wstat32 function", "stat64 function", "stati64 function", "_wstati64 function", "_tstat64 function", "files [C++], getting status information"] -ms.assetid: 99a75ae6-ff26-47ad-af70-5ea7e17226a5 --- # `_stat`, `_stat32`, `_stat64`, `_stati64`, `_stat32i64`, `_stat64i32`, `_wstat`, `_wstat32`, `_wstat64`, `_wstati64`, `_wstat32i64`, `_wstat64i32` @@ -69,86 +68,87 @@ int _wstat64i32( ### Parameters -*`path`*
+*`path`*\ Pointer to a string containing the path of existing file or directory. -*`buffer`*
+*`buffer`*\ Pointer to structure that stores results. -## Return Value +## Return value -Each of these functions returns 0 if the file-status information is obtained. A return value of -1 indicates an error, in which case **`errno`** is set to **`ENOENT`**, indicating that the filename or path could not be found. A return value of **`EINVAL`** indicates an invalid parameter; **`errno`** is also set to **`EINVAL`** in this case. +Each of these functions returns 0 if the file-status information is obtained. A return value of -1 indicates an error, in which case `errno` is set to `ENOENT`, indicating that the filename or path couldn't be found. A return value of `EINVAL` indicates an invalid parameter; `errno` is also set to `EINVAL` in this case. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The date stamp on a file can be represented if it is later than midnight, January 1, 1970, and before 23:59:59, December 31, 3000, UTC, unless you use **`_stat32`** or **`_wstat32`**, or have defined **`_USE_32BIT_TIME_T`**, in which case the date can be represented only until 23:59:59 January 18, 2038, UTC. +The date stamp on a file can be represented if it's later than midnight, January 1, 1970, and before 23:59:59, December 31, 3000, UTC, unless you use **`_stat32`** or **`_wstat32`**, or have defined `_USE_32BIT_TIME_T`, in which case the date can be represented only until 23:59:59 January 18, 2038, UTC. ## Remarks The **`_stat`** function obtains information about the file or directory specified by *`path`* and stores it in the structure pointed to by *`buffer`*. **`_stat`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. -**`_wstat`** is a wide-character version of **`_stat`**; the *`path`* argument to **`_wstat`** is a wide-character string. **`_wstat`** and **`_stat`** behave identically except that **`_wstat`** does not handle multibyte-character strings. +**`_wstat`** is a wide-character version of **`_stat`**; the *`path`* argument to **`_wstat`** is a wide-character string. **`_wstat`** and **`_stat`** behave identically except that **`_wstat`** doesn't handle multibyte-character strings. -Variations of these functions support 32- or 64-bit time types, and 32- or 64-bit file lengths. The first numerical suffix (**32** or **64**) indicates the size of the time type used; the second suffix is either **i32** or **i64**, indicating whether the file size is represented as a 32-bit or 64-bit integer. +Variations of these functions support 32-bit or 64-bit time types, and 32-bit or 64-bit file lengths. The first numerical suffix (**`32`** or **`64`**) indicates the size of the time type used; the second suffix is either **`i32`** or **`i64`**, indicating whether the file size is represented as a 32-bit or 64-bit integer. -**`_stat`** is equivalent to **`_stat64i32`**, and **`struct`** **`_stat`** contains a 64-bit time. This is true unless **`_USE_32BIT_TIME_T`** is defined, in which case the old behavior is in effect; **`_stat`** uses a 32-bit time, and **`struct`** **`_stat`** contains a 32-bit time. The same is true for **`_stati64`**. +**`_stat`** is equivalent to **`_stat64i32`**, and **`struct _stat`** contains a 64-bit time, unless `_USE_32BIT_TIME_T` is defined, in which case the old behavior is in effect; **`_stat`** uses a 32-bit time, and **`struct _stat`** contains a 32-bit time. The same is true for **`_stati64`**. > [!NOTE] > **`_wstat`** does not work with Windows Vista symbolic links. In these cases, **`_wstat`** will always report a file size of 0. **`_stat`** does work correctly with symbolic links. +> The `_stat` family of functions use `CreateFile` in Visual Studio 2015, instead of `FindFirstFile` as in Visual Studio 2013 and earlier. This means that `_stat` on a path ending with a slash succeeds if the path refers to a directory, as opposed to before when the function would error with `errno` set to `ENOENT`. -This function validates its parameters. If either *`path`* or *`buffer`* is **`NULL`**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +This function validates its parameters. If either *`path`* or *`buffer`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Time Type and File Length Type Variations of `_stat` +### Time type and file length type variations of `_stat` -|Functions|_USE_32BIT_TIME_T defined?|Time type|File length type| -|---------------|------------------------------------|---------------|----------------------| -|**`_stat`**, **`_wstat`**|Not defined|64-bit|32-bit| -|**`_stat`**, **`_wstat`**|Defined|32-bit|32-bit| -|**`_stat32`**, **`_wstat32`**|Not affected by the macro definition|32-bit|32-bit| -|**`_stat64`**, **`_wstat64`**|Not affected by the macro definition|64-bit|64-bit| -|**`_stati64`**, **`_wstati64`**|Not defined|64-bit|64-bit| -|**`_stati64`**, **`_wstati64`**|Defined|32-bit|64-bit| -|**`_stat32i64`**, **`_wstat32i64`**|Not affected by the macro definition|32-bit|64-bit| -|**`_stat64i32`**, **`_wstat64i32`**|Not affected by the macro definition|64-bit|32-bit| +| Functions | `_USE_32BIT_TIME_T` defined | Time type | File length type | +|---|---|---|---| +| **`_stat`**, **`_wstat`** | Not defined | 64-bit | 32-bit | +| **`_stat`**, **`_wstat`** | Defined | 32-bit | 32-bit | +| **`_stat32`**, **`_wstat32`** | Not affected by the macro definition | 32-bit | 32-bit | +| **`_stat64`**, **`_wstat64`** | Not affected by the macro definition | 64-bit | 64-bit | +| **`_stati64`**, **`_wstati64`** | Not defined | 64-bit | 64-bit | +| **`_stati64`**, **`_wstati64`** | Defined | 32-bit | 64-bit | +| **`_stat32i64`**, **`_wstat32i64`** | Not affected by the macro definition | 32-bit | 64-bit | +| **`_stat64i32`**, **`_wstat64i32`** | Not affected by the macro definition | 64-bit | 32-bit | -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tstat`**|**`_stat`**|**`_stat`**|**`_wstat`**| -|**`_tstat64`**|**`_stat64`**|**`_stat64`**|**`_wstat64`**| -|**`_tstati64`**|**`_stati64`**|**`_stati64`**|**`_wstati64`**| -|**`_tstat32i64`**|**`_stat32i64`**|**`_stat32i64`**|**`_wstat32i64`**| -|**`_tstat64i32`**|**`_stat64i32`**|**`_stat64i32`**|**`_wstat64i32`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstat` | **`_stat`** | **`_stat`** | **`_wstat`** | +| `_tstat64` | **`_stat64`** | **`_stat64`** | **`_wstat64`** | +| `_tstati64` | **`_stati64`** | **`_stati64`** | **`_wstati64`** | +| `_tstat32i64` | **`_stat32i64`** | **`_stat32i64`** | **`_wstat32i64`** | +| `_tstat64i32` | **`_stat64i32`** | **`_stat64i32`** | **`_wstat64i32`** | The **`_stat`** structure, defined in **`SYS\STAT.H`**, includes the following fields. -|Field|Description| -|-|-| +| Field | Description | +|---|---| | **`st_gid`** | Numeric identifier of group that owns the file (UNIX-specific) This field will always be zero on Windows systems. A redirected file is classified as a Windows file. | | **`st_atime`** | Time of last access of file. Valid on NTFS but not on FAT formatted disk drives. | | **`st_ctime`** | Time of creation of file. Valid on NTFS but not on FAT formatted disk drives. | | **`st_dev`** | Drive number of the disk containing the file (same as **`st_rdev`**). | | **`st_ino`** | Number of the information node (the **`inode`**) for the file (UNIX-specific). On UNIX file systems, the **`inode`** describes the file date and time stamps, permissions, and content. When files are hard-linked to one another, they share the same **`inode`**. The **`inode`**, and therefore **`st_ino`**, has no meaning in the FAT, HPFS, or NTFS file systems. | -| **`st_mode`** | Bit mask for file-mode information. The **`_S_IFDIR`** bit is set if *`path`* specifies a directory; the **`_S_IFREG`** bit is set if *`path`* specifies an ordinary file or a device. User read/write bits are set according to the file's permission mode; user execute bits are set according to the filename extension. | +| **`st_mode`** | Bit mask for file-mode information. The `_S_IFDIR` bit is set if *`path`* specifies a directory; the `_S_IFREG` bit is set if *`path`* specifies an ordinary file or a device. User read/write bits are set according to the file's permission mode; user execute bits are set according to the filename extension. | | **`st_mtime`** | Time of last modification of file. | | **`st_nlink`** | Always 1 on non-NTFS file systems. | | **`st_rdev`** | Drive number of the disk containing the file (same as **`st_dev`**). | | **`st_size`** | Size of the file in bytes; a 64-bit integer for variations with the **`i64`** suffix. | | **`st_uid`** | Numeric identifier of user who owns file (UNIX-specific). This field will always be zero on Windows systems. A redirected file is classified as a Windows file. | -If *`path`* refers to a device, the **`st_size`**, various time fields, **`st_dev`**, and **`st_rdev`** fields in the **`_stat`** structure are meaningless. Because **`STAT.H`** uses the [`_dev_t`](../../c-runtime-library/standard-types.md) type that is defined in **`TYPES.H`**, you must include **`TYPES.H`** before **`STAT.H`** in your code. +If *`path`* refers to a device, the **`st_size`**, various time fields, **`st_dev`**, and **`st_rdev`** fields in the **`_stat`** structure are meaningless. Because **`STAT.H`** uses the [`_dev_t`](../standard-types.md) type that is defined in **`TYPES.H`**, you must include **`TYPES.H`** before **`STAT.H`** in your code. ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`_stat`**, **`_stat32`**, **`_stat64`**, **`_stati64`**, **`_stat32i64`**, **`_stat64i32`**|`` followed by ``|``| -|**`_wstat`**, **`_wstat32`**, **`_wstat64`**, **`_wstati64`**, **`_wstat32i64`**, **`_wstat64i32`**|`` followed by `` or ``|``| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_stat`**, **`_stat32`**, **`_stat64`**, **`_stati64`**, **`_stat32i64`**, **`_stat64i32`** | `` followed by `` | `` | +| **`_wstat`**, **`_wstat32`**, **`_wstat64`**, **`_wstati64`**, **`_wstat32i64`**, **`_wstat64i32`** | `` followed by `` or `` | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -162,13 +162,14 @@ For additional compatibility information, see [Compatibility](../../c-runtime-li #include #include #include +#include int main( void ) { struct _stat buf; int result; char timebuf[26]; - char* filename = "crt_stat.c"; + const char* filename = "crt_stat.c"; errno_t err; // Get data associated with "crt_stat.c": @@ -215,8 +216,8 @@ Time modified : Thu Feb 07 14:39:36 2002 ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[`_access`, `_waccess`](access-waccess.md)
-[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[`_getmbcp`](getmbcp.md)
-[`_setmbcp`](setmbcp.md)
+[File handling](../file-handling.md)\ +[`_access`, `_waccess`](access-waccess.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_getmbcp`](getmbcp.md)\ +[`_setmbcp`](setmbcp.md) diff --git a/docs/c-runtime-library/reference/static-assert-macro.md b/docs/c-runtime-library/reference/static-assert-macro.md index 0e09a119ff6..2ecae090835 100644 --- a/docs/c-runtime-library/reference/static-assert-macro.md +++ b/docs/c-runtime-library/reference/static-assert-macro.md @@ -9,9 +9,9 @@ f1_keywords: ["_STATIC_ASSERT"] helpviewer_keywords: ["_STATIC_ASSERT macro"] ms.assetid: 89b0350c-2c2f-4be6-9786-8b1f0780a5da --- -# _STATIC_ASSERT Macro +# `_STATIC_ASSERT` macro -Evaluate an expression at compile time and generate an error when the result is **FALSE**. +Evaluate an expression at compile time and generate an error when the result is `FALSE`. ## Syntax @@ -23,16 +23,16 @@ _STATIC_ASSERT( ### Parameters -*booleanExpression*
-Expression (including pointers) that evaluates to nonzero (**TRUE**) or 0 (**FALSE**). +*`booleanExpression`*\ +Expression (including pointers) that evaluates to nonzero (`TRUE`) or 0 (`FALSE`). ## Remarks -This macro resembles the [_ASSERT and _ASSERTE macros](assert-asserte-assert-expr-macros.md), except that *booleanExpression* is evaluated at compile time instead of at runtime. If *booleanExpression* evaluates to **FALSE** (0), [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) is generated. +This macro resembles the [`_ASSERT` and `_ASSERTE` macros](assert-asserte-assert-expr-macros.md), except that *`booleanExpression`* is evaluated at compile time instead of at runtime. If *`booleanExpression`* evaluates to `FALSE` (0), [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) is generated. ## Example -In this example, we check whether the [sizeof](../../c-language/sizeof-operator-c.md) an **`int`** is larger than or equal to 2 bytes and whether the [sizeof](../../c-language/sizeof-operator-c.md) a **`long`** is 1 byte. The program will not compile and it will generate [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) because a **`long`** is larger than 1 byte. +In this example, we check whether the [`sizeof`](../../c-language/sizeof-operator-c.md) an **`int`** is larger than or equal to 2 bytes and whether the [`sizeof`](../../c-language/sizeof-operator-c.md) a **`long`** is 1 byte. The program won't compile and it will generate [Compiler Error C2466](../../error-messages/compiler-errors-1/compiler-error-c2466.md) because a **`long`** is larger than 1 byte. ```C // crt__static_assert.c @@ -54,11 +54,11 @@ int main() ## Requirements -|Macro|Required header| -|-----------|---------------------| -|**_STATIC_ASSERT**|\| +| Macro | Required header | +|---|---| +| **`_STATIC_ASSERT`** | \ | ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[_ASSERT, _ASSERTE, _ASSERT_EXPR Macros](assert-asserte-assert-expr-macros.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`_ASSERT`, `_ASSERTE`, `_ASSERT_EXPR` macros](assert-asserte-assert-expr-macros.md) diff --git a/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md b/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md index 0dec6287d74..3dee203f57f 100644 --- a/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md +++ b/docs/c-runtime-library/reference/status87-statusfp-statusfp2.md @@ -10,7 +10,7 @@ f1_keywords: ["_statusfp2", "_statusfp", "statusfp2", "_status87", "status87", " helpviewer_keywords: ["floating-point functions, getting status word", "floating-point numbers, status word", "status87 function", "status word, getting floating point", "statusfp function", "_statusfp function", "_statusfp2 function", "statusfp2 function", "_status87 function", "floating-point functions", "status word"] ms.assetid: 7ef963fa-b1fb-429d-94d6-fbf282ab7432 --- -# _status87, _statusfp, _statusfp2 +# `_status87`, `_statusfp`, `_statusfp2` Gets the floating-point status word. @@ -24,33 +24,33 @@ void _statusfp2(unsigned int *px86, unsigned int *pSSE2) ### Parameters -*px86*
+*`px86`*\ This address is filled with the status word for the x87 floating-point unit. -*pSSE2*
+*`pSSE2`*\ This address is filled with the status word for the SSE2 floating-point unit. -## Return Value +## Return value -For **_status87** and **_statusfp**, the bits in the value that's returned indicate the floating-point status. See the FLOAT.H include file for a definition of the bits that are returned by **_statusfp**. Many math library functions modify the floating-point status word, with unpredictable results. Optimization can reorder, combine, and eliminate floating-point operations around calls to **_status87**, **_statusfp**, and related functions. Use the [/Od (Disable (Debug))](../../build/reference/od-disable-debug.md) compiler option or the [fenv_access](../../preprocessor/fenv-access.md) pragma directive to prevent optimizations that reorder floating-point operations. Return values from **_clearfp** and **_statusfp**, and also the return parameters of **_statusfp2**, are more reliable if fewer floating-point operations are performed between known states of the floating-point status word. +For **`_status87`** and **`_statusfp`**, the bits in the value that's returned indicate the floating-point status. See the FLOAT.H include file for a definition of the bits that are returned by **`_statusfp`**. Many math library functions modify the floating-point status word, with unpredictable results. Optimization can reorder, combine, and eliminate floating-point operations around calls to **`_status87`**, **`_statusfp`**, and related functions. Use the [/Od (Disable (Debug))](../../build/reference/od-disable-debug.md) compiler option or the [`fenv_access`](../../preprocessor/fenv-access.md) pragma directive to prevent optimizations that reorder floating-point operations. Return values from `_clearfp` and **`_statusfp`**, and also the return parameters of **`_statusfp2`**, are more reliable if fewer floating-point operations are performed between known states of the floating-point status word. ## Remarks -The **_statusfp** function gets the floating-point status word. The status word is a combination of the floating-point processor status and other conditions detected by the floating-point exception handler—for example, floating-point stack overflow and underflow. Unmasked exceptions are checked for before the contents of the status word are returned. This means that the caller is informed of pending exceptions. On x86 platforms, **_statusfp** returns a combination of the x87 and SSE2 floating-point status. On x64 platforms, the status that's returned is based on the SSE’s MXCSR status. On ARM platforms, **_statusfp** returns status from the FPSCR register. +The **`_statusfp`** function gets the floating-point status word. The status word is a combination of the floating-point processor status and other conditions detected by the floating-point exception handler—for example, floating-point stack overflow and underflow. Unmasked exceptions are checked for before the contents of the status word are returned. In other words, the caller is informed of pending exceptions. On x86 platforms, **`_statusfp`** returns a combination of the x87 and SSE2 floating-point status. On x64 platforms, the status that's returned is based on the SSE's MXCSR status. On ARM64 platforms, **`_statusfp`** returns status from the FPSCR register. -**_statusfp** is a platform-independent, portable version of **_status87**. It is identical to **_status87** on Intel (x86) platforms and is also supported by the x64 and ARM platforms. To ensure that your floating-point code is portable to all architectures, use **_statusfp**. If you are only targeting x86 platforms, you can use either **_status87** or **_statusfp**. +**`_statusfp`** is a platform-independent, portable version of **`_status87`**. It's identical to **`_status87`** on Intel (x86) platforms and is also supported by the x64 and ARM64 platforms. To ensure that your floating-point code is portable to all architectures, use **`_statusfp`**. If you're only targeting x86 platforms, you can use either **`_status87`** or **`_statusfp`**. -We recommend **_statusfp2** for chips (such as the Pentium IV) that have both an x87 and an SSE2 floating-point processor. For **_statusfp2**, the addresses are filled by using the floating-point status word for both the x87 or the SSE2 floating-point processor. For a chip that supports x87 and SSE2 floating-point processors, EM_AMBIGUOUS is set to 1 if **_statusfp** or **_controlfp** is used and the action was ambiguous because it could refer to the x87 or the SSE2 floating-point status word. The **_statusfp2** function is only supported on x86 platforms. +We recommend **`_statusfp2`** for chips (such as the Pentium IV) that have both an x87 and an SSE2 floating-point processor. For **`_statusfp2`**, the addresses are filled by using the floating-point status word for both the x87 or the SSE2 floating-point processor. For a chip that supports x87 and SSE2 floating-point processors, `EM_AMBIGUOUS` is set to 1 if **`_statusfp`** or `_controlfp` is used and the action was ambiguous because it could refer to the x87 or the SSE2 floating-point status word. The **`_statusfp2`** function is only supported on x86 platforms. -These functions are not useful for [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime (CLR) only supports the default floating-point precision. +These functions aren't useful for [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) because the common language runtime (CLR) only supports the default floating-point precision. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_status87**, **_statusfp**, **_statusfp2**|\| +| Routine | Required header | +|---|---| +| **`_status87`**, **`_statusfp`**, **`_statusfp2`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -100,6 +100,6 @@ Status = 0x00080003 - inexact, underflow, denormal ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[_clear87, _clearfp](clear87-clearfp.md)
-[_control87, _controlfp, \__control87_2](control87-controlfp-control87-2.md)
+[Math and floating-point support](../floating-point-support.md)\ +[`_clear87`, `_clearfp`](clear87-clearfp.md)\ +[`_control87`, `_controlfp`, `__control87_2`](control87-controlfp-control87-2.md) diff --git a/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md b/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md index 985cda5c69c..261fe9e8059 100644 --- a/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md +++ b/docs/c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md @@ -3,7 +3,7 @@ description: "Learn more about: strcat_s, wcscat_s, _mbscat_s, _mbscat_s_l" title: "strcat_s, wcscat_s, _mbscat_s, _mbscat_s_l" ms.date: "4/2/2020" api_name: ["strcat_s", "_mbscat_s", "_mbscat_s_l", "wcscat_s", "_o__mbscat_s", "_o__mbscat_s_l", "_o_strcat_s", "_o_wcscat_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strcat_s", "wcscat_s", "_mbscat_s", "_mbscat_s_l"] @@ -12,7 +12,7 @@ ms.assetid: 0f2f9901-c5c5-480b-98bc-f8f690792fc0 --- # `strcat_s`, `wcscat_s`, `_mbscat_s`, `_mbscat_s_l` -Appends a string. These versions of [`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Appends a string. These versions of [`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbscat_s`** and **`_mbscat_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -66,35 +66,35 @@ errno_t _mbscat_s_l( ### Parameters -*`strDestination`*
+*`strDestination`*\ Null-terminated destination string buffer. -*`numberOfElements`*
+*`numberOfElements`*\ Size of the destination string buffer. -*`strSource`*
+*`strSource`*\ Null-terminated source string buffer. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful; an error code on failure. -### Error Conditions +### Error conditions -|*`strDestination`*|*`numberOfElements`*|*`strSource`*|Return value|Contents of *`strDestination`*| -|----------------------|------------------------|-----------------|------------------|----------------------------------| -|**`NULL`** or unterminated|any|any|**`EINVAL`**|not modified| -|any|any|**`NULL`**|**`EINVAL`**|*`strDestination[0]`* set to 0| -|any|0, or too small|any|**`ERANGE`**|*`strDestination[0]`* set to 0| +| *`strDestination`* | *`numberOfElements`* | *`strSource`* | Return value | Contents of *`strDestination`* | +|---|---|---|---|---| +| `NULL` or unterminated | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | *`strDestination[0]`* set to 0 | +| any | 0, or too small | any | `ERANGE` | *`strDestination[0]`* set to 0 | ## Remarks The **`strcat_s`** function appends *`strSource`* to *`strDestination`* and terminates the resulting string with a null character. The initial character of *`strSource`* overwrites the terminating null character of *`strDestination`*. The behavior of **`strcat_s`** is undefined if the source and destination strings overlap. -Note that the second parameter is the total size of the buffer, not the remaining size: +The second parameter is the total size of the buffer, not the remaining size: ```C char buf[16]; @@ -103,33 +103,33 @@ strcat_s(buf, 16, " End"); // Correct strcat_s(buf, 16 - strlen(buf), " End"); // Incorrect ``` -**`wcscat_s`** and **`_mbscat_s`** are wide-character and multibyte-character versions of **`strcat_s`**. The arguments and return value of **`wcscat_s`** are wide-character strings; those of **`_mbscat_s`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcscat_s`** and **`_mbscat_s`** are wide-character and multibyte-character versions of **`strcat_s`**. The arguments and return value of **`wcscat_s`** are wide-character strings. The arguments and return value of **`_mbscat_s`** are multibyte-character strings. These three functions behave identically otherwise. -If *`strDestination`* is a null pointer, or is not null-terminated, or if *`strSource`* is a **`NULL`** pointer, or if the destination string is too small, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EINVAL`** and set **`errno`** to **`EINVAL`**. +If *`strDestination`* is a null pointer, or isn't null-terminated, or if *`strSource`* is a `NULL` pointer, or if the destination string is too small, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL`. -The versions of functions that have the **`_l`** suffix have the same behavior, but use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of functions that have the **`_l`** suffix have the same behavior, but use the locale parameter that's passed in instead of the current locale. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscat_s`**|**`strcat_s`**|**`_mbscat_s`**|**`wcscat_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscat_s` | **`strcat_s`** | **`_mbscat_s`** | **`wcscat_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcat_s`**|``| -|**`wcscat_s`**|`` or ``| -|**`_mbscat_s`**|``| +| Routine | Required header | +|---|---| +| **`strcat_s`** | `` | +| **`wcscat_s`** | `` or `` | +| **`_mbscat_s`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -137,10 +137,10 @@ See the code example in [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s- ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md b/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md index 16e09f94862..5e202c05d3a 100644 --- a/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md +++ b/docs/c-runtime-library/reference/strcat-wcscat-mbscat.md @@ -51,13 +51,13 @@ unsigned char *_mbscat( ### Parameters -*`strDestination`*
+*`strDestination`*\ Null-terminated destination string. -*`strSource`*
+*`strSource`*\ Null-terminated source string. -## Return Value +## Return value Each of these functions returns the destination string (*`strDestination`*). No return value is reserved to indicate an error. @@ -66,27 +66,27 @@ Each of these functions returns the destination string (*`strDestination`*). No The **`strcat`** function appends *`strSource`* to *`strDestination`* and terminates the resulting string with a null character. The initial character of *`strSource`* overwrites the terminating null character of *`strDestination`*. The behavior of **`strcat`** is undefined if the source and destination strings overlap. > [!IMPORTANT] -> Because **`strcat`** does not check for sufficient space in *strDestination* before appending *strSource*, it is a potential cause of buffer overruns. Consider using [`strncat`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) instead. +> Because **`strcat`** does not check for sufficient space in *`strDestination`* before appending *`strSource`*, it is a potential cause of buffer overruns. Consider using [`strncat`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) instead. -**`wcscat`** and **`_mbscat`** are wide-character and multibyte-character versions of **`strcat`**. The arguments and return value of **`wcscat`** are wide-character strings; those of **`_mbscat`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcscat`** and **`_mbscat`** are wide-character and multibyte-character versions of **`strcat`**. The arguments and return value of **`wcscat`** are wide-character strings. The arguments and return value of **`_mbscat`** are multibyte-character strings. These three functions behave identically otherwise. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscat`**|**`strcat`**|**`_mbscat`**|**`wcscat`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscat` | **`strcat`** | **`_mbscat`** | **`wcscat`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcat`**|``| -|**`wcscat`**|`` or ``| -|**`_mbscat`**|``| +| Routine | Required header | +|---|---| +| **`strcat`** | `` | +| **`wcscat`** | `` or `` | +| **`_mbscat`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -94,10 +94,10 @@ See the example for [`strcpy`](strcpy-wcscpy-mbscpy.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md b/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md index 0ef51d2e0a8..13e43ded7c4 100644 --- a/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md +++ b/docs/c-runtime-library/reference/strchr-wcschr-mbschr-mbschr-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strchr, wcschr, _mbschr, _mbschr_l" title: "strchr, wcschr, _mbschr, _mbschr_l" ms.date: "4/2/2020" api_name: ["strchr", "wcschr", "_mbschr_l", "_mbschr", "_o__mbschr", "_o__mbschr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcschr", "strchr", "wcschr", "_tcschr", "_mbschr"] @@ -15,7 +15,7 @@ ms.assetid: 2639905d-e983-43b7-b885-abef32cfac43 Finds a character in a string, by using the current locale or a specified `LC_CTYPE` conversion-state category. > [!IMPORTANT] -> `_mbschr` and `_mbschr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbschr`** and **`_mbschr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -75,47 +75,46 @@ const unsigned char *_mbschr_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated source string. -*`c`*
+*`c`*\ Character to be located. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns a pointer to the first occurrence of *`c`* in *`str`*, or `NULL` if *`c`* is not found. +Each of these functions returns a pointer to the first occurrence of *`c`* in *`str`*, or `NULL` if *`c`* isn't found. ## Remarks -The `strchr` function finds the first occurrence of *`c`* in *`str`*, or it returns `NULL` if *`c`* is not found. The null terminating character is included in the search. +The **`strchr`** function finds the first occurrence of *`c`* in *`str`*, or it returns `NULL` if *`c`* isn't found. The null terminating character is included in the search. -`wcschr`, `_mbschr` and `_mbschr_l` are wide-character and multibyte-character versions of `strchr`. The arguments and return value of `wcschr` are wide-character strings; those of `_mbschr` are multibyte-character strings. `_mbschr` recognizes multibyte-character sequences. Also, if the string is a null pointer, `_mbschr` invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, `_mbschr` returns `NULL` and sets `errno` to `EINVAL`. `strchr` and `wcschr` do not validate their parameters. These three functions behave identically otherwise. +**`wcschr`**, **`_mbschr`** and **`_mbschr_l`** are wide-character and multibyte-character versions of **`strchr`**. The arguments and return value of **`wcschr`** are wide-character strings. The arguments and return value of **`_mbschr`** are multibyte-character strings. **`_mbschr`** recognizes multibyte-character sequences. Also, if the string is a null pointer, **`_mbschr`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbschr`** returns `NULL` and sets `errno` to `EINVAL`. **`strchr`** and **`wcschr`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcschr`|`strchr`|`_mbschr`|`wcschr`| -|**_n/a**|**n/a**|`_mbschr_l`|**n/a**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcschr` | **`strchr`** | **`_mbschr`** | **`wcschr`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strchr`|``| -|`wcschr`|`` or ``| -|`_mbschr`, `_mbschr_l`|``| +| Routine | Required header | +|---|---| +| **`strchr`** | `` | +| **`wcschr`** | `` or `` | +| **`_mbschr`**, **`_mbschr_l`** | `` | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example @@ -176,14 +175,14 @@ Result: last r found at position 30 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strstr`, `wcsstr`, `_mbsstr`, `_mbsstr_l`](strstr-wcsstr-mbsstr-mbsstr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strstr`, `wcsstr`, `_mbsstr`, `_mbsstr_l`](strstr-wcsstr-mbsstr-mbsstr-l.md) diff --git a/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md b/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md index 7379b15b38a..683b59764eb 100644 --- a/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md +++ b/docs/c-runtime-library/reference/strcmp-wcscmp-mbscmp.md @@ -3,7 +3,7 @@ description: "Learn more about: strcmp, wcscmp, _mbscmp, _mbscmp_l" title: "strcmp, wcscmp, _mbscmp, _mbscmp_l" ms.date: "4/2/2020" api_name: ["wcscmp", "_mbscmp", "_mbscmp_l", "strcmp", "_o__mbscmp", "_o__mbscmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbscmp", "_mbscmp_l", "wcscmp", "strcmp", "_tcscmp", "_ftcscmp"] @@ -41,37 +41,37 @@ int _mbscmp_l( ### Parameters -*`string1`*, *`string2`*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value The return value for each of these functions indicates the ordinal relation of *`string1`* to *`string2`*. -|Value|Relationship of `string1` to `string2`| -|-----------|----------------------------------------| -|< 0|*`string1`* is less than *`string2`*| -|0|*`string1`* is identical to *`string2`*| -|> 0|*`string1`* is greater than *`string2`*| +| Value | Relationship of `string1` to `string2` | +|---|---| +| < 0 | *`string1`* is less than *`string2`* | +| 0 | *`string1`* is identical to *`string2`* | +| > 0 | *`string1`* is greater than *`string2`* | -On a parameter validation error, **`_mbscmp`** and **`_mbscmp_l`** return **`_NLSCMPERROR`**, which is defined in `` and ``. +On a parameter validation error, **`_mbscmp`** and **`_mbscmp_l`** return `_NLSCMPERROR`, which is defined in `` and ``. ## Remarks -The **`strcmp`** function performs an ordinal comparison of *`string1`* and *`string2`* and returns a value that indicates their relationship. **`wcscmp`** and **`_mbscmp`** are, respectively, wide-character and multibyte-character versions of **`strcmp`**. **`_mbscmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns **`_NLSCMPERROR`** on an error. **`_mbscmp_l`** has the same behavior, but uses the locale parameter that's passed in instead of the current locale. For more information, see [Code Pages](../../c-runtime-library/code-pages.md). Also, if *`string1`* or *`string2`* is a null pointer, **`_mbscmp`** invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`_mbscmp`** and **`_mbscmp_l`** return **`_NLSCMPERROR`** and set **`errno`** to **`EINVAL`**. **`strcmp`** and **`wcscmp`** do not validate their parameters. These functions behave identically otherwise. +The **`strcmp`** function performs an ordinal comparison of *`string1`* and *`string2`* and returns a value that indicates their relationship. **`wcscmp`** and **`_mbscmp`** are, respectively, wide-character and multibyte-character versions of **`strcmp`**. **`_mbscmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns `_NLSCMPERROR` on an error. **`_mbscmp_l`** has the same behavior, but uses the locale parameter that's passed in instead of the current locale. For more information, see [Code pages](../code-pages.md). Also, if *`string1`* or *`string2`* is a null pointer, **`_mbscmp`** invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbscmp`** and **`_mbscmp_l`** return `_NLSCMPERROR` and set `errno` to `EINVAL`. **`strcmp`** and **`wcscmp`** don't validate their parameters. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscmp`**|**`strcmp`**|**`_mbscmp`**|**`wcscmp`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscmp` | **`strcmp`** | **`_mbscmp`** | **`wcscmp`** | -The **`strcmp`** functions differ from the **`strcoll`** functions in that **`strcmp`** comparisons are ordinal, and are not affected by locale. **`strcoll`** compares strings lexicographically by using the **`LC_COLLATE`** category of the current locale. For more information about the **`LC_COLLATE`** category, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). +The **`strcmp`** functions differ from the **`strcoll`** functions in that **`strcmp`** comparisons are ordinal, and aren't affected by locale. **`strcoll`** compares strings lexicographically by using the `LC_COLLATE` category of the current locale. For more information about the `LC_COLLATE` category, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). In the "C" locale, the order of characters in the character set (ASCII character set) is the same as the lexicographic character order. However, in other locales, the order of characters in the character set may differ from the lexicographic order. For example, in certain European locales, the character '`a`' (value 0x61) comes before the character '`ä`' (value 0xE4) in the character set, but the character '`ä`' comes in front of the character '`a`' lexicographically. @@ -81,17 +81,17 @@ The **`strcmp`** functions are case-sensitive. **`_stricmp`**, **`_wcsicmp`**, a ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcmp`**|``| -|**`wcscmp`**|`` or ``| -|**`_mbscmp`**|``| +| Routine | Required header | +|---|---| +| **`strcmp`** | `` | +| **`wcscmp`** | `` or `` | +| **`_mbscmp`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -144,13 +144,13 @@ Compare strings: ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)
-[`_memicmp`, `_memicmp_`l](memicmp-memicmp-l.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`_memicmp`, `_memicmp_l`](memicmp-memicmp-l.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strcmpi.md b/docs/c-runtime-library/reference/strcmpi.md index 9541964928c..3e80b441e23 100644 --- a/docs/c-runtime-library/reference/strcmpi.md +++ b/docs/c-runtime-library/reference/strcmpi.md @@ -10,8 +10,8 @@ f1_keywords: ["strcmpi"] helpviewer_keywords: ["strcmpi function"] ms.assetid: 74206b2f-9bca-4d32-9cdc-93cb94c2aaa1 --- -# strcmpi +# `strcmpi` -The Microsoft-specific function name `strcmpi` is a deprecated alias for the [_stricmp](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `strcmpi` is a deprecated alias for the [`_stricmp`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_stricmp](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_stricmp`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md b/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md index d917bdde486..653c50ba6f3 100644 --- a/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md +++ b/docs/c-runtime-library/reference/strcoll-wcscoll-mbscoll-strcoll-l-wcscoll-l-mbscoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll title: "strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l" ms.date: "4/2/2020" api_name: ["wcscoll", "_mbscoll", "_mbscoll_l", "strcoll", "_strcoll_l", "_wcscoll_l", "_o__mbscoll", "_o__mbscoll_l", "_o__strcoll_l", "_o__wcscoll_l", "_o_strcoll", "_o_wcscoll"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcscoll", "_mbscoll", "_tcscoll", "_ftcscoll"] +f1_keywords: ["STRING/strcoll", "CORECRT_WSTRING/wcscoll", "MBSTRING/_mbscoll", "TCHAR/_tcscoll", "TCHAR/_ftcscoll", "STRING/_strcoll_l", "CORECRT_WSTRING/_wcscoll_l", "MBSTRING/_mbscoll_l", "TCHAR/_tcscoll_l", "strcoll", "wcscoll", "_mbscoll", "_tcscoll", "_ftcscoll", "_strcoll_l", "_wcscoll_l", "_mbscoll_l", "_tcscoll_l"] helpviewer_keywords: ["code pages, using for string comparisons", "mbscoll function", "wcscoll_l function", "ftcscoll function", "wcscoll function", "_strcoll_l function", "tcscoll function", "_ftcscoll function", "_tcscoll function", "_wcscoll_l function", "_mbscoll function", "strcoll_l function", "strcoll functions", "strings [C++], comparing by code page"] ms.assetid: 900a7540-c7ec-4c2f-b292-7a85f63e3fe8 --- -# strcoll, wcscoll, _mbscoll, _strcoll_l, _wcscoll_l, _mbscoll_l +# `strcoll`, `wcscoll`, `_mbscoll`, `_strcoll_l`, `_wcscoll_l`, `_mbscoll_l` -Compares strings by using the current locale or a specified LC_COLLATE conversion-state category. +Compares strings by using the current locale or a specified `LC_COLLATE` conversion-state category. > [!IMPORTANT] -> **_mbscoll** and **_mbscoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbscoll`** and **`_mbscoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -51,62 +51,62 @@ int _mbscoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns a value indicating the relationship of *string1* to *string2*, as follows. +Each of these functions returns a value indicating the relationship of *`string1`* to *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* less than *string2*| -|0|*string1* identical to *string2*| -|> 0|*string1* greater than *string2*| +| Return value | Relationship of *`string1`* to *`string2`* | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | -Each of these functions returns **_NLSCMPERROR** on an error. To use **_NLSCMPERROR**, include either STRING.H or MBSTRING.H. **wcscoll** can fail if either *string1* or *string2* is **NULL** or contains wide-character codes outside the domain of the collating sequence. When an error occurs, **wcscoll** may set **errno** to **EINVAL**. To check for an error on a call to **wcscoll**, set **errno** to 0 and then check **errno** after calling **wcscoll**. +Each of these functions returns `_NLSCMPERROR` on an error. To use `_NLSCMPERROR`, include either STRING.H or MBSTRING.H. **`wcscoll`** can fail if either *`string1`* or *`string2`* is `NULL` or contains wide-character codes outside the domain of the collating sequence. When an error occurs, **`wcscoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`wcscoll`**, set `errno` to 0 and then check `errno` after calling **`wcscoll`**. ## Remarks -Each of these functions performs a case-sensitive comparison of *string1* and *string2* according to the code page currently in use. These functions should be used only when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. +Each of these functions performs a case-sensitive comparison of *`string1`* and *`string2`* according to the code page currently in use. These functions should be used only when there's a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, or if *count* is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, or if *`count`* is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -The comparison of the two strings is a locale-dependent operation since each locale has different rules for ordering characters. The versions of these functions without the **_l** suffix use the current thread's locale for this locale-dependent behavior; the versions with the **_l** suffix are identical to the corresponding function without the suffix except that they use the locale passed in as a parameter instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The comparison of the two strings is a locale-dependent operation since each locale has different rules for ordering characters. The versions of these functions without the `_l` suffix use the current thread's locale for this locale-dependent behavior; the versions with the `_l` suffix are identical to the corresponding function without the suffix except that they use the locale passed in as a parameter instead of the current locale. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcscoll**|**strcoll**|**_mbscoll**|**wcscoll**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscoll` | **`strcoll`** | **`_mbscoll`** | **`wcscoll`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strcoll**|\| -|**wcscoll**|\, \| -|**_mbscoll**, **_mbscoll_l**|\| -|**_strcoll_l**|\| -|**_wcscoll_l**|\, \| +| Routine | Required header | +|---|---| +| **`strcoll`** | \ | +| **`wcscoll`** | \, \ | +| **`_mbscoll`**, **`_mbscoll_l`** | \ | +| **`_strcoll_l`** | \ | +| **`_wcscoll_l`** | \, \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md b/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md index 9fff08fc53f..0871f968a50 100644 --- a/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md +++ b/docs/c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md @@ -3,7 +3,7 @@ description: "Learn more about: strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l" title: "strcpy_s, wcscpy_s, _mbscpy_s, _mbscpy_s_l" ms.date: "5/28/2020" api_name: ["wcscpy_s", "_mbscpy_s", "_mbscpy_s_l", "strcpy_s", "_o__mbscpy_s", "_o__mbscpy_s_l", "_o_strcpy_s", "_o_wcscpy_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strcpy_s", "_mbscpy_s", "_mbscpy_s_l", "_tcscpy_s", "wcscpy_s"] @@ -12,7 +12,7 @@ ms.assetid: 611326f3-7929-4a5d-a465-a4683af3b053 --- # `strcpy_s`, `wcscpy_s`, `_mbscpy_s`, `_mbscpy_s_l` -Copies a string. These versions of [`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copies a string. These versions of [`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbscpy_s`** and **`_mbscpy_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -70,61 +70,61 @@ errno_t _mbscpy_s_l( ### Parameters -*`dest`*
+*`dest`*\ Location of the destination string buffer. -*`dest_size`*
-Size of the destination string buffer in **`char`** units for narrow and multi-byte functions, and **`wchar_t`** units for wide functions. This value must be greater than zero and not greater than **`RSIZE_MAX`**. Ensure that this size accounts for the terminating `NULL` following the string. +*`dest_size`*\ +Size of the destination string buffer in **`char`** units for narrow and multi-byte functions, and **`wchar_t`** units for wide functions. This value must be greater than zero and not greater than `RSIZE_MAX`. Ensure that this size accounts for the terminating `NULL` following the string. -*`src`*
+*`src`*\ Null-terminated source string buffer. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful; otherwise, an error. -### Error Conditions +### Error conditions -|*`dest`*|*`dest_size`*|*`src`*|Return value|Contents of *`dest`*| -|----------------------|------------------------|-----------------|------------------|----------------------------------| -|**`NULL`**|any|any|**`EINVAL`**|not modified| -|any|any|**`NULL`**|**`EINVAL`**|*`dest[0]`* set to 0| -|any|0, or too small|any|**`ERANGE`**|*`dest[0]`* set to 0| +| *`dest`* | *`dest_size`* | *`src`* | Return value | Contents of *`dest`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | *`dest[0]`* set to 0 | +| any | 0, or too small | any | `ERANGE` | *`dest[0]`* set to 0 | ## Remarks The **`strcpy_s`** function copies the contents in the address of *`src`*, including the terminating null character, to the location that's specified by *`dest`*. The destination string must be large enough to hold the source string and its terminating null character. The behavior of **`strcpy_s`** is undefined if the source and destination strings overlap. -**`wcscpy_s`** is the wide-character version of **`strcpy_s`**, and **`_mbscpy_s`** is the multibyte-character version. The arguments of **`wcscpy_s`** are wide-character strings; those of **`_mbscpy_s`** and **`_mbscpy_s_l`** are multibyte-character strings. These functions behave identically otherwise. **`_mbscpy_s_l`** is identical to **`_mbscpy_s`** except that it uses the locale parameter passed in instead of the current locale. For more information, see [`locale`](../../c-runtime-library/locale.md). +**`wcscpy_s`** is the wide-character version of **`strcpy_s`**, and **`_mbscpy_s`** is the multibyte-character version. The arguments of **`wcscpy_s`** are wide-character strings. The arguments of **`_mbscpy_s`** and **`_mbscpy_s_l`** are multibyte-character strings. These functions behave identically otherwise. **`_mbscpy_s_l`** is identical to **`_mbscpy_s`** except that it uses the locale parameter passed in instead of the current locale. For more information, see [`locale`](../locale.md). -If *`dest`* or *`src`* is a null pointer, or if the destination string size *`dest_size`* is too small, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **`EINVAL`** and set **`errno`** to **`EINVAL`** when *`dest`* or *`src`* is a null pointer, and they return **`ERANGE`** and set **`errno`** to **`ERANGE`** when the destination string is too small. +If *`dest`* or *`src`* is a null pointer, or if the destination string size *`dest_size`* is too small, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL` when *`dest`* or *`src`* is a null pointer, and they return `ERANGE` and set `errno` to `ERANGE` when the destination string is too small. Upon successful execution, the destination string is always null-terminated. -In C++, use of these functions is simplified by template overloads that can infer buffer length automatically so that you don't have to specify a size argument, and they can automatically replace older, less-secure functions with their newer, more secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, use of these functions is simplified by template overloads that can infer buffer length automatically, so that you don't have to specify a size argument. And, they can automatically replace older, less-secure functions with newer, more secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscpy_s`**|**`strcpy_s`**|**`_mbscpy_s`**|**`wcscpy_s`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tcscpy_s`** | **`strcpy_s`** | **`_mbscpy_s`** | **`wcscpy_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcpy_s`**|``| -|**`wcscpy_s`**|`` or ``| -|**`_mbscpy_s`**|``| +| Routine | Required header | +|---|---| +| **`strcpy_s`** | `` | +| **`wcscpy_s`** | `` or `` | +| **`_mbscpy_s`** | `` | -These functions are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +These functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -158,7 +158,7 @@ int main(void) stringBuffer = Hello world from strcpy_s and strcat_s! ``` -When building C++ code, the template versions may be easier to use. +When you're building C++ code, the template versions may be easier to use. ```cpp // crt_wcscpy_s.cpp @@ -191,12 +191,12 @@ stringBuffer = Hello world from wcscpy_s and wcscat_s! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strcat`, `wcscat`, `_mbscat`, `_mbscat_l`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`, `_mbscmp_l`](strcmp-wcscmp-mbscmp.md)
-[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strcat`, `wcscat`, `_mbscat`, `_mbscat_l`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`, `_mbscmp_l`](strcmp-wcscmp-mbscmp.md)\ +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md b/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md index 761afc699f1..1e5a1b66892 100644 --- a/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md +++ b/docs/c-runtime-library/reference/strcpy-wcscpy-mbscpy.md @@ -3,7 +3,7 @@ description: "Learn more about: strcpy, wcscpy, _mbscpy" title: "strcpy, wcscpy, _mbscpy" ms.date: "4/2/2020" api_name: ["strcpy", "wcscpy", "_mbscpy", "_o_wcscpy"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbscpy", "_ftcscpy", "wcscpy", "_tcscpy", "strcpy"] @@ -51,44 +51,44 @@ unsigned char *_mbscpy( ### Parameters -*`strDestination`*
+*`strDestination`*\ Destination string. -*`strSource`*
+*`strSource`*\ Null-terminated source string. -## Return Value +## Return value Each of these functions returns the destination string. No return value is reserved to indicate an error. ## Remarks -The **`strcpy`** function copies *strSource*, including the terminating null character, to the location that's specified by *`strDestination`*. The behavior of **`strcpy`** is undefined if the source and destination strings overlap. +The **`strcpy`** function copies *`strSource`*, including the terminating null character, to the location that's specified by *`strDestination`*. The behavior of **`strcpy`** is undefined if the source and destination strings overlap. > [!IMPORTANT] -> Because **`strcpy`** does not check for sufficient space in *strDestination* before it copies *`strSource`*, it is a potential cause of buffer overruns. Therefore, we recommend that you use [`strcpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md) instead. +> Because **`strcpy`** does not check for sufficient space in *`strDestination`* before it copies *`strSource`*, it is a potential cause of buffer overruns. Therefore, we recommend that you use [`strcpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md) instead. -**`wcscpy`** and **`_mbscpy`** are, respectively, wide-character and multibyte-character versions of **`strcpy`**. The arguments and return value of **`wcscpy`** are wide-character strings; those of **`_mbscpy`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcscpy`** and **`_mbscpy`** are, respectively, wide-character and multibyte-character versions of **`strcpy`**. The arguments and return value of **`wcscpy`** are wide-character strings. The arguments and return value of **`_mbscpy`** are multibyte-character strings. These three functions behave identically otherwise. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcscpy`**|**`strcpy`**|**`_mbscpy`**|**`wcscpy`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscpy` | **`strcpy`** | **`_mbscpy`** | **`wcscpy`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strcpy`**|``| -|**`wcscpy`**|`` or ``| -|**`_mbscpy`**|``| +| Routine | Required header | +|---|---| +| **`strcpy`** | `` | +| **`wcscpy`** | `` or `` | +| **`_mbscpy`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -127,12 +127,12 @@ String = Hello world from strcpy and strcat! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md b/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md index 1a6fcbcc870..879e9482a2c 100644 --- a/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md +++ b/docs/c-runtime-library/reference/strcspn-wcscspn-mbscspn-mbscspn-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strcspn, wcscspn, _mbscspn, _mbscspn_l" title: "strcspn, wcscspn, _mbscspn, _mbscspn_l" ms.date: "4/2/2020" api_name: ["_mbscspn_l", "wcscspn", "_mbscspn", "strcspn", "_o__mbscspn", "_o__mbscspn_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strcspn", "_mbscspn", "wcscspn", "_ftcscspn", "_tcscspn"] helpviewer_keywords: ["strings [C++], searching", "ftcscspn function", "strcspn function", "_mbscspn function", "mbscspn_l function", "wcscspn function", "tcscspn function", "_ftcscspn function", "_mbscspn_l function", "mbscspn function", "_tcscspn function"] ms.assetid: f73f51dd-b533-4e46-ba29-d05c553708a6 --- -# strcspn, wcscspn, _mbscspn, _mbscspn_l +# `strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l` Returns the index of the first occurrence in a string, of a character that belongs to a set of characters. > [!IMPORTANT] -> **_mbschr** and **_mbschr_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> `_mbschr` and `_mbschr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,47 +41,46 @@ size_t _mbscspn_l( ### Parameters -*str*
+*`str`*\ Null-terminated searched string. -*strCharSet*
+*`strCharSet`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -These functions return the index of the first character in *str* that is in *strCharSet*. If none of the characters in *str* is in *strCharSet*, then the return value is the length of *str*. +These functions return the index of the first character in *`str`* that is in *`strCharSet`*. If none of the characters in *`str`* is in *`strCharSet`*, then the return value is the length of *`str`*. No return value is reserved to indicate an error. ## Remarks -**wcscspn** and **_mbscspn** are wide-character and multibyte-character versions of **strcspn**. The arguments of **wcscspn** are wide-character strings; those of **_mbscspn** are multibyte-character strings. +**`wcscspn`** and **`_mbscspn`** are wide-character and multibyte-character versions of **`strcspn`**. The arguments of **`wcscspn`** are wide-character strings. The arguments and return value of **`_mbscspn`** are multibyte-character strings. -**_mbscspn** validates its parameters. If either *str* or *strCharSet* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets **errno** to **EINVAL**. **strcspn** and **wcscspn** do not validate their parameters. These three functions behave identically otherwise. +**`_mbscspn`** validates its parameters. If either *`str`* or *`strCharSet`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets `errno` to `EINVAL`. **`strcspn`** and **`wcscspn`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcscspn**|**strcspn**|**_mbscspn**|**wcscspn**| -|n/a|n/a|**_mbscspn_l**|n/a| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcscspn` | **`strcspn`** | **`_mbscspn`** | **`wcscspn`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strcspn**|\| -|**wcscspn**|\ or \| -|**_mbscspn**, **_mbscspn_l**|\| +| Routine | Required header | +|---|---| +| **`strcspn`** | \ | +| **`wcscspn`** | \ or \ | +| **`_mbscspn`**, **`_mbscspn_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -119,12 +118,12 @@ strcspn( "", "" ) = 0 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md b/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md index c2273bfe38d..78db9567430 100644 --- a/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md +++ b/docs/c-runtime-library/reference/strdate-s-wstrdate-s.md @@ -1,18 +1,17 @@ --- title: "_strdate_s, _wstrdate_s" description: "_strdate_s and _wstrdate_s are secure CRT versions of the _strdate and _wstrdate functions that put the current date in a buffer." -ms.date: "4/2/2020" +ms.date: 4/2/2020 api_name: ["_strdate_s", "_wstrdate_s", "_o__strdate_s", "_o__wstrdate_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strdate_s", "wstrdate_s", "_wstrdate_s", "strdate_s", "_tstrdate_s"] helpviewer_keywords: ["dates, copying", "tstrdate_s function", "wstrdate_s function", "_tstrdate_s function", "strdate_s function", "copying dates", "_strdate_s function", "_wstrdate_s function"] -ms.assetid: d41d8ea9-e5ce-40d4-864e-1ac29b455991 --- -# _strdate_s, _wstrdate_s +# `_strdate_s`, `_wstrdate_s` -Copy the current system date to a buffer. These functions are versions of [_strdate, _wstrdate](strdate-wstrdate.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copy the current system date to a buffer. These functions are versions of [`_strdate`, `_wstrdate`](strdate-wstrdate.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,70 +36,70 @@ errno_t _wstrdate_s( ### Parameters -*buffer*\ +*`buffer`*\ A pointer to a buffer to put the formatted date string. -*size*\ +*`size`*\ Size of the buffer in character units. ## Return value -Zero if successful. The return value is an error code if there's a failure. Error codes are defined in ERRNO.H; see table below for the exact errors generated by this function. For more information on error codes, see [errno](../../c-runtime-library/errno-constants.md). +Zero if successful. The return value is an error code if there's a failure. Error codes are defined in ERRNO.H; see table below for the exact errors generated by this function. For more information on error codes, see [`errno`](../errno-constants.md). ## Error conditions -|*buffer*|*size*|Return|Contents of *buffer*| -|--------------|------------------------|------------|--------------------------| -|**NULL**|(any)|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0 < *size* < 9|**EINVAL**|Empty string| -|Not **NULL** (pointing to valid buffer)|*size* >= 9|0|Current date formatted as specified in the remarks| +| *`buffer`* | *`size`* | Return | Contents of *`buffer`* | +|---|---|---|---| +| `NULL` | (any) | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 < *`size`* < 9 | `EINVAL` | Empty string | +| Not `NULL` (pointing to valid buffer) | *`size`* >= 9 | 0 | Current date formatted as specified in the remarks | ## Security issues -Passing in an invalid, non-NULL value for *buffer* results in an access violation if the *size* parameter is greater than nine. +If you pass in an invalid, non-NULL value for *`buffer`*, it results in an access violation if the *`size`* parameter is greater than nine. -Passing a value for *size* greater than the actual size of *buffer* results in a buffer overrun. +Passing a value for *`size`* greater than the actual size of *`buffer`* results in a buffer overrun. ## Remarks -These functions provide more secure versions of **_strdate** and **_wstrdate**. The **_strdate_s** function copies the current system date to the buffer pointed to by *buffer*. It's formatted `mm/dd/yy`, where `mm` is the two-digit month, `dd` is the two-digit day, and `yy` is the last two digits of the year. For example, the string `12/05/99` represents December 5, 1999. The buffer must be at least nine characters long. +These functions provide more secure versions of `_strdate` and `_wstrdate`. The **`_strdate_s`** function copies the current system date to the buffer pointed to by *`buffer`*. It's formatted `mm/dd/yy`, where `mm` is the two-digit month, `dd` is the two-digit day, and `yy` is the last two digits of the year. For example, the string `12/05/99` represents December 5, 1999. The buffer must be at least nine characters long. -**_wstrdate_s** is a wide-character version of **_strdate_s**; the argument and return value of **_wstrdate_s** are wide-character strings. These functions behave identically otherwise. +**`_wstrdate_s`** is a wide-character version of **`_strdate_s`**; the argument and return value of **`_wstrdate_s`** are wide-character strings. These functions behave identically otherwise. -When *buffer* is a **NULL** pointer, or *size* is fewer than nine characters, the invalid parameter handler is invoked. It's described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1. They set **errno** to **EINVAL** if the buffer is **NULL** or if *size* is less than or equal to 0. Or, they set **errno** to **ERANGE** if *size* is less than 9. +When *`buffer`* is a `NULL` pointer, or *`size`* is fewer than nine characters, the invalid parameter handler is invoked. It's described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1. They set `errno` to `EINVAL` if the buffer is `NULL` or if *`size`* is less than or equal to 0. Or, they set `errno` to `ERANGE` if *`size`* is less than 9. -In C++, use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a *size* argument. And, they can automatically replace non-secure functions with their newer, more secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, use of these functions is simplified by template overloads. The overloads can infer buffer length automatically, which eliminates the need to specify a *`size`* argument. And, they can automatically replace non-secure functions with their newer, more secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-text routine mapping: +### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrdate_s**|**_strdate_s**|**_strdate_s**|**_wstrdate_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrdate_s` | **`_strdate_s`** | **`_strdate_s`** | **`_wstrdate_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strdate**|\| -|**_wstrdate**|\ or \| -|**_strdate_s**|\| +| Routine | Required header | +|---|---| +| **`_strdate`** | \ | +| **`_wstrdate`** | \ or \ | +| **`_strdate_s`** | \ | ## Example -See the example for [time](time-time32-time64.md). +See the example for [`time`](time-time32-time64.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)\ -[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)\ -[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ -[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)\ -[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)\ -[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)\ -[time, _time32, _time64](time-time32-time64.md)\ -[_tzset](tzset.md) +[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strdate-wstrdate.md b/docs/c-runtime-library/reference/strdate-wstrdate.md index 4f8422d4b22..8f2570b92fb 100644 --- a/docs/c-runtime-library/reference/strdate-wstrdate.md +++ b/docs/c-runtime-library/reference/strdate-wstrdate.md @@ -3,16 +3,16 @@ description: "Learn more about: _strdate, _wstrdate" title: "_strdate, _wstrdate" ms.date: "4/2/2020" api_name: ["_strdate", "_wstrdate", "_o__strdate", "_o__wstrdate"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tstrdate", "wstrdate", "_wstrdate", "_strdate", "strdate"] helpviewer_keywords: ["strdate function", "dates, copying", "tstrdate function", "_wstrdate function", "wstrdate function", "_strdate function", "_tstrdate function", "copying dates"] ms.assetid: de8e4097-58f8-42ba-9dcd-cb4d9a9f1696 --- -# _strdate, _wstrdate +# `_strdate`, `_wstrdate` -Copy current system date to a buffer. More secure versions of these functions are available; see [_strdate_s, _wstrdate_s](strdate-s-wstrdate-s.md). +Copy current system date to a buffer. More secure versions of these functions are available; see [`_strdate_s`, `_wstrdate_s`](strdate-s-wstrdate-s.md). ## Syntax @@ -35,41 +35,41 @@ wchar_t *_wstrdate( ### Parameters -*datestr*
+*`datestr`*\ A pointer to a buffer containing the formatted date string. -## Return Value +## Return value -Each of these functions returns a pointer to the resulting character string *datestr*. +Each of these functions returns a pointer to the resulting character string *`datestr`*. ## Remarks -More secure versions of these functions are available; see [_strdate_s, _wstrdate_s](strdate-s-wstrdate-s.md). It is recommended that the more secure functions be used wherever possible. +More secure versions of these functions are available; see [`_strdate_s`, `_wstrdate_s`](strdate-s-wstrdate-s.md). It's recommended that the more secure functions be used wherever possible. -The **_strdate** function copies the current system date to the buffer pointed to by *datestr*, formatted **mm**/**dd**/**yy**, where **mm** is two digits representing the month, **dd** is two digits representing the day, and **yy** is the last two digits of the year. For example, the string **12/05/99** represents December 5, 1999. The buffer must be at least 9 bytes long. +The **`_strdate`** function copies the current system date to the buffer pointed to by *`datestr`*, formatted *mm/dd/yy*, where *mm* is two digits representing the month, *dd* is two digits representing the day, and *yy* is the last two digits of the year. For example, the string *`12/05/99`* represents December 5, 1999. The buffer must be at least 9 bytes long. -If *datestr* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`datestr`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -**_wstrdate** is a wide-character version of **_strdate**; the argument and return value of **_wstrdate** are wide-character strings. These functions behave identically otherwise. +**`_wstrdate`** is a wide-character version of **`_strdate`**; the argument and return value of **`_wstrdate`** are wide-character strings. These functions behave identically otherwise. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrdate**|**_strdate**|**_strdate**|**_wstrdate**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrdate` | **`_strdate`** | **`_strdate`** | **`_wstrdate`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strdate**|\| -|**_wstrdate**|\ or \| +| Routine | Required header | +|---|---| +| **`_strdate`** | \ | +| **`_wstrdate`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -99,11 +99,11 @@ OS date: 04/25/03 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md b/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md index 1687ad4ed6d..2321d881fbc 100644 --- a/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md +++ b/docs/c-runtime-library/reference/strdec-wcsdec-mbsdec-mbsdec-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strdec, _wcsdec, _mbsdec, _mbsdec_l" title: "_strdec, _wcsdec, _mbsdec, _mbsdec_l" ms.date: "4/2/2020" api_name: ["_wcsdec", "_strdec", "_mbsdec", "_mbsdec_l", "_o__mbsdec", "_o__mbsdec_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strdec", "mbsdec_l", "strdec", "_mbsdec", "_mbsdec_l", "mbsdec", "wcsdec", "_wcsdec"] helpviewer_keywords: ["mbsdec_l function", "mbsdec function", "tcsdec function", "_tcsdec function", "_strdec function", "_wcsdec function", "_mbsdec_l function", "strdec function", "wcsdec function", "_mbsdec function"] ms.assetid: ae37c223-800f-48a9-ae8e-38c8d20af2dd --- -# _strdec, _wcsdec, _mbsdec, _mbsdec_l +# `_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l` Moves a string pointer back one character. > [!IMPORTANT] -> **mbsdec** and **mbsdec_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsdec`** and **`_mbsdec_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,56 +41,56 @@ unsigned char *_mbsdec_l( ### Parameters -*start*
-Pointer to any character (or for **_mbsdec** and **_mbsdec_l**, the first byte of any multibyte character) in the source string; *start* must precede *current* in the source string. +*`start`*\ +Pointer to any character (or for **`_mbsdec`** and **`_mbsdec_l`**, the first byte of any multibyte character) in the source string; *`start`* must precede *`current`* in the source string. -*current*
-Pointer to any character (or for **_mbsdec** and **_mbsdec_l**, the first byte of any multibyte character) in the source string; *current* must follow *start* in the source string. +*`current`*\ +Pointer to any character (or for **`_mbsdec`** and **`_mbsdec_l`**, the first byte of any multibyte character) in the source string; *`current`* must follow *`start`* in the source string. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsdec**, **_mbsdec_l**, **_strdec**, and **_wcsdec** each return a pointer to the character that immediately precedes *current*; **_mbsdec** returns **NULL** if the value of *start* is greater than or equal to that of *current*. **_tcsdec** maps to one of these functions and its return value depends on the mapping. +**`_mbsdec`**, **`_mbsdec_l`**, **`_strdec`**, and **`_wcsdec`** each return a pointer to the character that immediately precedes *`current`*; **`_mbsdec`** returns `NULL` if the value of *`start`* is greater than or equal to that of *`current`*. `_tcsdec` maps to one of these functions and its return value depends on the mapping. ## Remarks -The **_mbsdec** and **_mbsdec_l** functions return a pointer to the first byte of the multibyte character that immediately precedes *current* in the string that contains *start*. +The **`_mbsdec`** and **`_mbsdec_l`** functions return a pointer to the first byte of the multibyte character that immediately precedes *`current`* in the string that contains *`start`*. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. **_mbsdec** recognizes multibyte-character sequences according to the locale that's currently in use, while **_mbsdec_l** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). **`_mbsdec`** recognizes multibyte-character sequences according to the locale that's currently in use, while **`_mbsdec_l`** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../locale.md). -If *start* or *current* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **EINVAL** and sets **errno** to **EINVAL**. +If *`start`* or *`current`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `EINVAL` and sets `errno` to `EINVAL`. > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsdec**|**_strdec**|**_mbsdec**|**_wcsdec**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsdec` | **`_strdec`** | **`_mbsdec`** | **`_wcsdec`** | -**_strdec** and **_wcsdec** are single-byte-character and wide-character versions of **_mbsdec** and **_mbsdec_l**. **_strdec** and **_wcsdec** are provided only for this mapping and should not be used otherwise. +**`_strdec`** and **`_wcsdec`** are single-byte-character and wide-character versions of **`_mbsdec`** and **`_mbsdec_l`**. **`_strdec`** and **`_wcsdec`** are provided only for this mapping and shouldn't be used otherwise. -For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). ## Requirements -|Routine|Required header|Optional header| -|-------------|---------------------|---------------------| -|**_mbsdec**|\|\| -|**_mbsdec_l**|\|\| -|**_strdec**|\|| -|**_wcsdec**|\|| +| Routine | Required header | Optional header | +|---|---|---| +| **`_mbsdec`** | \ | \ | +| **`_mbsdec_l`** | \ | \ | +| **`_strdec`** | \ | | +| **`_wcsdec`** | \ | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -The following example shows a use of **_tcsdec**. +The following example shows a use of `_tcsdec`. ```cpp // crt_tcsdec.cpp @@ -116,7 +116,7 @@ int main() } ``` -The following example shows a use of **_mbsdec**. +The following example shows a use of **`_mbsdec`**. ```cpp // crt_mbsdec.cpp @@ -145,7 +145,7 @@ int main() ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strinc, _wcsinc, _mbsinc, _mbsinc_l](strinc-wcsinc-mbsinc-mbsinc-l.md)
-[_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)
-[_strninc, _wcsninc, _mbsninc, _mbsninc_l](strninc-wcsninc-mbsninc-mbsninc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](strinc-wcsinc-mbsinc-mbsinc-l.md)\ +[`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)\ +[`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](strninc-wcsninc-mbsninc-mbsninc-l.md) diff --git a/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md b/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md index a445f75214d..7f5a94682a1 100644 --- a/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md +++ b/docs/c-runtime-library/reference/strdup-dbg-wcsdup-dbg.md @@ -10,9 +10,9 @@ f1_keywords: ["_wcsdup_dbg", "strdup_dbg", "_strdup_dbg", "wcsdup_dbg"] helpviewer_keywords: ["_wcsdup_dbg function", "stdup_dbg function", "copying strings", "duplicating strings", "strings [C++], copying", "strings [C++], duplicating", "_strdup_dbg function", "wcsdup_dbg function"] ms.assetid: 681db70c-d124-43ab-b83e-5eeea9035097 --- -# _strdup_dbg, _wcsdup_dbg +# `_strdup_dbg`, `_wcsdup_dbg` -Versions of [_strdup and _wcsdup](strdup-wcsdup-mbsdup.md) that use the debug version of **malloc**. +Versions of [`_strdup` and `_wcsdup`](strdup-wcsdup-mbsdup.md) that use the debug version of `malloc`. ## Syntax @@ -33,48 +33,48 @@ wchar_t *_wcsdup_dbg( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated source string. -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to name of source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in source file where allocation operation was requested or `NULL`. -## Return Value +## Return value -Each of these functions returns a pointer to the storage location for the copied string or **NULL** if storage cannot be allocated. +Each of these functions returns a pointer to the storage location for the copied string or `NULL` if storage can't be allocated. ## Remarks -The **_strdup_dbg** and **_wcsdup_dbg** functions are identical to **_strdup** and **_wcsdup** except that, when **_DEBUG** is defined, these functions use the debug version of **malloc**, **_malloc_dbg**, to allocate memory for the duplicated string. For information on the debugging features of **_malloc_dbg**, see [_malloc_dbg](malloc-dbg.md). +The **`_strdup_dbg`** and **`_wcsdup_dbg`** functions are identical to `_strdup` and `_wcsdup` except that, when `_DEBUG` is defined, these functions use the debug version of `malloc`, `_malloc_dbg`, to allocate memory for the duplicated string. For information on the debugging features of `_malloc_dbg`, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the flag **_CRTDBG_MAP_ALLOC**. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_strdup** and **_wcsdup** are remapped to **_strdup_dbg** and **_wcsdup_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information on block types, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the flag `_CRTDBG_MAP_ALLOC`. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_strdup` and `_wcsdup` are remapped to **`_strdup_dbg`** and **`_wcsdup_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information on block types, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsdup_dbg**|**_strdup_dbg**|**_mbsdup**|**_wcsdup_dbg**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsdup_dbg` | **`_strdup_dbg`** | `_mbsdup` | **`_wcsdup_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strdup_dbg**, **_wcsdup_dbg**|\| +| Routine | Required header | +|---|---| +| **`_strdup_dbg`**, **`_wcsdup_dbg`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All debug versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All debug versions of the [C run-time libraries](../crt-library-features.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strdup, _wcsdup, _mbsdup](strdup-wcsdup-mbsdup.md)
-[Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions)
+[String manipulation](../string-manipulation-crt.md)\ +[`_strdup`, `_wcsdup`, `_mbsdup`](strdup-wcsdup-mbsdup.md)\ +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md b/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md index b48d4939506..f6bf0213c34 100644 --- a/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md +++ b/docs/c-runtime-library/reference/strdup-wcsdup-mbsdup.md @@ -3,7 +3,7 @@ description: "Learn more about: _strdup, _wcsdup, _mbsdup" title: "_strdup, _wcsdup, _mbsdup" ms.date: "4/2/2020" api_name: ["_strdup", "_mbsdup", "_wcsdup", "_o__strdup", "_o__wcsdup"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsdup", "mbsdup", "_mbsdup", "_strdup", "_ftcsdup", "_wcsdup"] @@ -33,40 +33,40 @@ unsigned char *_mbsdup( ### Parameters -*`strSource`*
+*`strSource`*\ Null-terminated source string. -## Return Value +## Return value -Each of these functions returns a pointer to the storage location for the copied string or **`NULL`** if storage cannot be allocated. +Each of these functions returns a pointer to the storage location for the copied string or `NULL` if storage can't be allocated. ## Remarks -The **`_strdup`** function calls [`malloc`](malloc.md) to allocate storage space for a copy of *strSource* and then copies *strSource* to the allocated space. +The **`_strdup`** function calls [`malloc`](malloc.md) to allocate storage space for a copy of *`strSource`* and then copies *`strSource`* to the allocated space. -**`_wcsdup`** and **`_mbsdup`** are wide-character and multibyte-character versions of **`_strdup`**. The arguments and return value of **`_wcsdup`** are wide-character strings; those of **`_mbsdup`** are multibyte-character strings. These three functions behave identically otherwise. +**`_wcsdup`** and **`_mbsdup`** are wide-character and multibyte-character versions of **`_strdup`**. The arguments and return value of **`_wcsdup`** are wide-character strings. The arguments and return value of **`_mbsdup`** are multibyte-character strings. These three functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsdup`**|**`_strdup`**|**`_mbsdup`**|**`_wcsdup`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsdup` | **`_strdup`** | **`_mbsdup`** | **`_wcsdup`** | -Because **`_strdup`** calls **`malloc`** to allocate storage space for the copy of *strSource*, it is good practice always to release this memory by calling the [`free`](free.md) routine on the pointer that's returned by the call to **`_strdup`**. +Because **`_strdup`** calls **`malloc`** to allocate storage space for the copy of *`strSource`*, it's good practice always to release this memory by calling the [`free`](free.md) routine on the pointer that's returned by the call to **`_strdup`**. -If **`_DEBUG`** and **`_CRTDBG_MAP_ALLOC`** are defined, **`_strdup`** and **`_wcsdup`** are replaced by calls to **`_strdup_dbg`** and **`_wcsdup_dbg`** to allow for debugging memory allocations. For more information, see [`_strdup_dbg`, `_wcsdup_dbg`](strdup-dbg-wcsdup-dbg.md). +If `_DEBUG` and `_CRTDBG_MAP_ALLOC` are defined, **`_strdup`** and **`_wcsdup`** are replaced by calls to **`_strdup_dbg`** and **`_wcsdup_dbg`**, to allow for debugging memory allocations. For more information, see [`_strdup_dbg`, `_wcsdup_dbg`](strdup-dbg-wcsdup-dbg.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_strdup`**|``| -|**`_wcsdup`**|`` or ``| -|**`_mbsdup`**|``| +| Routine | Required header | +|---|---| +| **`_strdup`** | `` | +| **`_wcsdup`** | `` or `` | +| **`_mbsdup`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -94,13 +94,13 @@ Copy: This is the buffer text ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`memset`, `wmemset`](memset-wmemset.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strdup-wcsdup.md b/docs/c-runtime-library/reference/strdup-wcsdup.md index 66c3b71fe11..16871efb490 100644 --- a/docs/c-runtime-library/reference/strdup-wcsdup.md +++ b/docs/c-runtime-library/reference/strdup-wcsdup.md @@ -10,8 +10,8 @@ f1_keywords: ["wcsdup", "strdup"] helpviewer_keywords: ["wcsdup function", "strdup function"] ms.assetid: c9ac0935-b525-4e95-8a64-396fc7e34ee9 --- -# strdup, wcsdup +# `strdup`, `wcsdup` -The Microsoft-implemented POSIX function names `strdup` and `wcsdup` are deprecated aliases for the [_strdup and _wcsdup](strdup-wcsdup-mbsdup.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-implemented POSIX function names `strdup` and `wcsdup` are deprecated aliases for the [`_strdup` and `_wcsdup`](strdup-wcsdup-mbsdup.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strdup and _wcsdup](strdup-wcsdup-mbsdup.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strdup` and `_wcsdup`](strdup-wcsdup-mbsdup.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md b/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md index ef9acd5eaea..e0cb870b103 100644 --- a/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md +++ b/docs/c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md @@ -1,18 +1,17 @@ --- title: "strerror_s, _strerror_s, _wcserror_s, __wcserror_s" description: "Functions with security enhancements to get a system error message or print a user-supplied error message." -ms.date: "09/25/2020" +ms.date: 05/31/2023 api_name: ["__wcserror_s", "_strerror_s", "_wcserror_s", "strerror_s", "_o__strerror_s", "_o__wcserror_s", "_o_strerror_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcserror_s", "__wcserror_s", "_tcserror_s", "_wcserror_s", "tcserror_s", "strerror_s", "_strerror_s"] helpviewer_keywords: ["__wcserror_s function", "error messages, printing", "tcserror_s function", "printing error messages", "strerror_s function", "_wcserror_s function", "_tcserror_s function", "_strerror_s function", "wcserror_s function", "error messages, getting"] -ms.assetid: 9e5b15a0-efe1-4586-b7e3-e1d7c31a03d6 --- -# strerror_s, _strerror_s, _wcserror_s, __wcserror_s +# `strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s` -Get a system error message (**strerror_s**, **_wcserror_s**) or print a user-supplied error message (**_strerror_s**, **__wcserror_s**). These are versions of [strerror, _strerror, _wcserror, \__wcserror](strerror-strerror-wcserror-wcserror.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Get a system error message (**`strerror_s`**, **`_wcserror_s`**) or print a user-supplied error message (**`_strerror_s`**, **`__wcserror_s`**). These functions are versions of [`strerror`, `_strerror`, `_wcserror`, `__wcserror`](strerror-strerror-wcserror-wcserror.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -64,37 +63,37 @@ errno_t __wcserror_s( ### Parameters -*buffer*\ +*`buffer`*\ Buffer to hold error string. -*sizeInBytes*\ +*`sizeInBytes`*\ The number of bytes in the buffer. -*sizeInWords*\ +*`sizeInWords`*\ The number of words in the buffer. -*errnum*\ +*`errnum`*\ Error number. -*strErrMsg*\ +*`strErrMsg`*\ User-supplied message. -## Return Value +## Return value Zero if successful, an error code on failure. ### Error conditions -|*buffer*|*sizeInBytes/sizeInWords*|*strErrMsg*|Contents of *buffer*| -|--------------|------------------------|-----------------|--------------------------| -|**NULL**|any|any|n/a| -|any|0|any|not modified| +| *`buffer`* | *`sizeInBytes`*/*`sizeInWords`* | *`strErrMsg`* | Contents of *`buffer`* | +|---|---|---|---| +| `NULL` | any | any | n/a | +| any | 0 | any | not modified | ## Remarks -The **strerror_s** function is thread-safe. +The **`strerror_s`** function is thread-safe. -The **strerror_s** function maps *errnum* to an error-message string, returning the string in *buffer*. **_strerror_s** doesn't take the error number; it uses the current value of **errno** to determine the appropriate message. Neither **strerror_s** nor **_strerror_s** actually prints the message: For that, you need to call an output function such as [fprintf](fprintf-fprintf-l-fwprintf-fwprintf-l.md): +The **`strerror_s`** function maps *`errnum`* to an error-message string, returning the string in *`buffer`*. **`_strerror_s`** doesn't take the error number; it uses the current value of `errno` to determine the appropriate message. The message isn't printed or displayed by **`strerror_s`** or **`_strerror_s`**. To output the message, you need to call an output function such as [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md): ```C if (( _access( "datafile",2 )) == -1 ) @@ -104,46 +103,46 @@ if (( _access( "datafile",2 )) == -1 ) } ``` -If *strErrMsg* is **NULL**, **_strerror_s** returns a string in *buffer* that contains the system error message for the last library call that produced an error. The error-message string is terminated by the newline character ('\n'). If *strErrMsg* isn't equal to **NULL**, then **_strerror_s** returns a string in *buffer* that contains (in order) your string message, a colon, a space, the system error message for the last library call that produced an error, and a newline character. Your string message can be, at most, 94 characters long. +If *`strErrMsg`* is `NULL`, **`_strerror_s`** returns a string in *`buffer`* that contains the system error message for the last library call that produced an error. If *`strErrMsg`* isn't equal to `NULL`, then **`_strerror_s`** returns a string in *`buffer`* that contains (in order) your string message, a colon, a space, the system error message for the last library call that produced an error. Your string message can be, at most, 94 characters long. -These functions truncate the error message if its length exceeds the size of the buffer - 1. The resulting string in *buffer* will always be null-terminated. +These functions truncate the error message if its length exceeds the size of the buffer - 1. The resulting string in *`buffer`* is always null-terminated. -The actual error number for **_strerror_s** is stored in the variable [errno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). The system error messages are accessed through the variable [_sys_errlist](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **_strerror_s** accesses the appropriate error message by using the **errno** value as an index to the variable **_sys_errlist**. The value of the variable [_sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the **_sys_errlist** array. To produce accurate results, call **_strerror_s** immediately after a library routine returns with an error. Otherwise, subsequent calls to **strerror_s** or **_strerror_s** can overwrite the **errno** value. +The actual error number for **`_strerror_s`** is stored in the variable [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md). The system error messages are accessed through the variable [`_sys_errlist`](../errno-doserrno-sys-errlist-and-sys-nerr.md), which is an array of messages ordered by error number. **`_strerror_s`** accesses the appropriate error message by using the `errno` value as an index to the variable `_sys_errlist`. The value of the variable [`_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) is defined as the maximum number of elements in the `_sys_errlist` array. To produce accurate results, call **`_strerror_s`** immediately after a library routine return with an error. Otherwise, subsequent calls to **`strerror_s`** or **`_strerror_s`** can overwrite the `errno` value. -**_wcserror_s** and **__wcserror_s** are wide-character versions of **strerror_s** and **_strerror_s**, respectively. +**`_wcserror_s`** and **`__wcserror_s`** are wide-character versions of **`strerror_s`** and **`_strerror_s`**, respectively. -These functions validate their parameters. If buffer is **NULL** or if the size parameter is 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the functions return **EINVAL** and set **errno** to **EINVAL**. +These functions validate their parameters. If buffer is `NULL` or if the size parameter is 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the functions return `EINVAL` and set `errno` to `EINVAL`. -**_strerror_s**, **_wcserror_s**, and **__wcserror_s** aren't part of the ANSI definition but are instead Microsoft extensions to it. Don't use them where portability is desired; for ANSI compatibility, use **strerror_s** instead. +**`_strerror_s`**, **`_wcserror_s`**, and **`__wcserror_s`** aren't part of the ANSI definition but are instead Microsoft extensions to it. Don't use them where portability is desired; for ANSI compatibility, use **`strerror_s`** instead. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcserror_s**|**strerror_s**|**strerror_s**|**_wcserror_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcserror_s` | **`strerror_s`** | **`strerror_s`** | **`_wcserror_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strerror_s**, **_strerror_s**|\| -|**_wcserror_s**, **__wcserror_s**|\ or \| +| Routine | Required header | +|---|---| +| **`strerror_s`**, **`_strerror_s`** | \ | +| **`_wcserror_s`**, **`__wcserror_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [perror](perror-wperror.md). +See the example for [`perror`](perror-wperror.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[clearerr](clearerr.md)\ -[ferror](ferror.md)\ -[perror, _wperror](perror-wperror.md) +[String manipulation](../string-manipulation-crt.md)\ +[`clearerr`](clearerr.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md b/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md index b0fd0d78528..234fd6914f6 100644 --- a/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md +++ b/docs/c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md @@ -1,18 +1,17 @@ --- title: "strerror, _strerror, _wcserror, __wcserror" description: "Describes the Microsoft C Runtime Library (CRT) functions strerror, _strerror, _wcserror, and __wcserror." -ms.date: "4/2/2020" +ms.date: "5/31/2023" api_name: ["strerror", "_strerror", "_wcserror", "__wcserror", "_o___wcserror", "_o__strerror", "_o__wcserror", "_o_strerror"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__sys_errlist", "wcserror", "_strerror", "__wcserror", "strerror", "__sys_nerr", "_tcserror", "_wcserror", "tcserror"] helpviewer_keywords: ["strerror function", "_strerror function", "__sys_errlist", "wcserror function", "error messages, printing", "__sys_nerr", "tcserror function", "printing error messages", "_wcserror function", "_tcserror function", "__wcserror function", "error messages, getting"] -ms.assetid: 27b72255-f627-43c0-8836-bcda8b003e14 --- -# strerror, _strerror, _wcserror, __wcserror +# `strerror`, `_strerror`, `_wcserror`, `__wcserror` -Gets a system error message string (**strerror**, **_wcserror**) or formats a user-supplied error message string (**_strerror**, **__wcserror**). More secure versions of these functions are available; see [strerror_s, _strerror_s, _wcserror_s, \__wcserror_s](strerror-s-strerror-s-wcserror-s-wcserror-s.md). +Gets a system error message string (**`strerror`**, **`_wcserror`**) or formats a user-supplied error message string (**`_strerror`**, **`__wcserror`**). More secure versions of these functions are available; see [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](strerror-s-strerror-s-wcserror-s-wcserror-s.md). ## Syntax @@ -32,10 +31,10 @@ wchar_t * __wcserror( ### Parameters -*errnum*\ +*`errnum`*\ Error number. -*strErrMsg*\ +*`strErrMsg`*\ User-supplied message. ## Return value @@ -44,48 +43,48 @@ All of these functions return a pointer to an error-message string, in a thread- ## Remarks -The **strerror** function maps *errnum* to an error-message string and returns a pointer to the string. The **strerror** and **_strerror** functions don't actually print the message. To print, call an output function such as [fprintf](fprintf-fprintf-l-fwprintf-fwprintf-l.md): +The **`strerror`** function maps *`errnum`* to an error-message string and returns a pointer to the string. The **`strerror`** and **`_strerror`** functions don't actually print the message. To print, call an output function such as [`fprintf`](fprintf-fprintf-l-fwprintf-fwprintf-l.md): ```C if (( _access( "datafile", 2 )) == -1 ) fprintf( stderr, _strerror(NULL) ); ``` -If *strErrMsg* is passed as **NULL**, **_strerror** returns a pointer to a string. It contains the system error message for the last library call that produced an error. The error-message string is terminated by the newline character ('\n'). When *strErrMsg* isn't **NULL**, the string contains, in order: your *strErrMsg* string, a colon, a space, the system error message, and a newline character. Your string message can be, at most, 94 characters long, in either narrow (**_strerror**) or wide (**__wcserror**) characters. +If *`strErrMsg`* is passed as `NULL`, **`_strerror`** returns a pointer to a string. It contains the system error message for the last library call that produced an error. If you call `__wcserror`, the error-message string is terminated by the newline character (`'\n'`). The other functions don't add `'\n'`. When *`strErrMsg`* isn't `NULL`, the string contains, in order: your *`strErrMsg`* string, a colon, a space, the system error message. Your string message can be, at most, 94 characters long, in either narrow (**`_strerror`**) or wide (**`__wcserror`**) characters. -The actual error number for **_strerror** is stored in the variable [errno](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). To produce accurate results, call **_strerror** immediately after a library routine returns an error. Otherwise, later calls to library routines may overwrite the **errno** value. +The actual error number for **`_strerror`** is stored in the variable [`errno`](../errno-doserrno-sys-errlist-and-sys-nerr.md). To produce accurate results, call **`_strerror`** immediately after a library routine returns an error. Otherwise, later calls to library routines may overwrite the `errno` value. -**_wcserror** and **__wcserror** are wide-character versions of **strerror** and **_strerror**, respectively. +**`_wcserror`** and **`__wcserror`** are wide-character versions of **`strerror`** and **`_strerror`**, respectively. -**_strerror**, **_wcserror**, and **__wcserror** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **strerror** instead. +**`_strerror`**, **`_wcserror`**, and **`__wcserror`** are Microsoft-specific, not part of the Standard C library. We don't recommend you use them where you want portable code. For Standard C compatibility, use **`strerror`** instead. -To get error strings, we recommend **strerror** or **_wcserror** instead of the deprecated macros [_sys_errlist](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) and [_sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) and the deprecated internal functions **__sys_errlist** and **__sys_nerr**. +To get error strings, we recommend **`strerror`** or **`_wcserror`** instead of the deprecated macros [`_sys_errlist`](../errno-doserrno-sys-errlist-and-sys-nerr.md) and [`_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md) and the deprecated internal functions `__sys_errlist` and `__sys_nerr`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcserror**|**strerror**|**strerror**|**_wcserror**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcserror` | **`strerror`** | **`strerror`** | **`_wcserror`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strerror**|\| -|**_strerror**|\| -|**_wcserror**, **__wcserror**|\| +| Routine | Required header | +|---|---| +| **`strerror`** | \ | +| **`_strerror`** | \ | +| **`_wcserror`**, **`__wcserror`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [perror](perror-wperror.md). +See the example for [`perror`](perror-wperror.md). ## See also -[String manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[clearerr](clearerr.md)\ -[ferror](ferror.md)\ -[perror, _wperror](perror-wperror.md) +[String manipulation](../string-manipulation-crt.md)\ +[`clearerr`](clearerr.md)\ +[`ferror`](ferror.md)\ +[`perror`, `_wperror`](perror-wperror.md) diff --git a/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md b/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md index 4a8ee18baed..92cf4ff91eb 100644 --- a/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md +++ b/docs/c-runtime-library/reference/strftime-wcsftime-strftime-l-wcsftime-l.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: strftime, wcsftime, _strftime_l, _wcsftime_l" title: "strftime, wcsftime, _strftime_l, _wcsftime_l" -ms.date: "4/2/2020" +description: "Learn more about: strftime, wcsftime, _strftime_l, _wcsftime_l" +ms.date: 4/2/2020 api_name: ["strftime", "_wcsftime_l", "_strftime_l", "wcsftime", "_o__strftime_l", "_o__wcsftime_l", "_o_strftime", "_o_wcsftime"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsftime", "strftime", "wcsftime", "_strftime_l", "_wcsftime_l"] helpviewer_keywords: ["_strftime_l function", "strftime function", "tcsftime function", "_wcsftime_l function", "wcsftime function", "_tcsftime function", "time strings"] -ms.assetid: 6330ff20-4729-4c4a-82af-932915d893ea --- # `strftime`, `wcsftime`, `_strftime_l`, `_wcsftime_l` @@ -47,111 +46,111 @@ size_t _wcsftime_l( ### Parameters -*`strDest`*
+*`strDest`*\ Output string. -*`maxsize`*
+*`maxsize`*\ Size of the *`strDest`* buffer, measured in characters (**`char`** or **`wchar_t`**). -*`format`*
+*`format`*\ Format-control string. -*`timeptr`*
+*`timeptr`*\ **`tm`** data structure. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value **`strftime`** returns the number of characters placed in *`strDest`* and **`wcsftime`** returns the corresponding number of wide characters. If the total number of characters, including the terminating null, is more than *`maxsize`*, both **`strftime`** and **`wcsftime`** return 0 and the contents of *`strDest`* are indeterminate. -The number of characters in *`strDest`* is equal to the number of literal characters in *`format`* as well as any characters that may be added to *`format`* via formatting codes. The terminating null of a string is not counted in the return value. +The number of characters in *`strDest`* is equal to the number of literal characters in *`format`*, plus any characters that may be added to *`format`* via formatting codes. The terminating null of a string isn't counted in the return value. ## Remarks The **`strftime`** and **`wcsftime`** functions format the **`tm`** time value in *`timeptr`* according to the supplied *`format`* argument and store the result in the buffer *`strDest`*. At most, *`maxsize`* characters are placed in the string. For a description of the fields in the *`timeptr`* structure, see [`asctime`](asctime-wasctime.md). **`wcsftime`** is the wide-character equivalent of **`strftime`**; its string-pointer argument points to a wide-character string. These functions behave identically otherwise. -This function validates its parameters. If *`strDest`*, *`format`*, or *`timeptr`* is a null pointer, or if the **`tm`** data structure addressed by *`timeptr`* is invalid (for example, if it contains out of range values for the time or date), or if the *`format`* string contains an invalid formatting code, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets **`errno`** to **`EINVAL`**. +This function validates its parameters. If *`strDest`*, *`format`*, or *`timeptr`* is a null pointer, or if the **`tm`** data structure addressed by *`timeptr`* is invalid (for example, if it contains out of range values for the time or date), or if the *`format`* string contains an invalid formatting code, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns 0 and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsftime`**|**`strftime`**|**`strftime`**|**`wcsftime`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tcsftime`** | **`strftime`** | **`strftime`** | **`wcsftime`** | -The *`format`* argument consists of one or more codes; as in **`printf`**, the formatting codes are preceded by a percent sign (**`%`**). Characters that do not begin with **`%`** are copied unchanged to *`strDest`*. The **`LC_TIME`** category of the current locale affects the output formatting of **`strftime`**. (For more information on **`LC_TIME`**, see [`setlocale`](setlocale-wsetlocale.md).) The **`strftime`** and **`wcsftime`** functions use the currently set locale. The **`_strftime_l`** and **`_wcsftime_l`** versions of these functions are identical except that they take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The *`format`* argument consists of one or more codes; as in **`printf`**, the formatting codes are preceded by a percent sign (**`%`**). Characters that don't begin with **`%`** are copied unchanged to *`strDest`*. The `LC_TIME` category of the current locale affects the output formatting of **`strftime`**. For more information on `LC_TIME`, see [`setlocale`](setlocale-wsetlocale.md). The **`strftime`** and **`wcsftime`** functions use the currently set locale. The **`_strftime_l`** and **`_wcsftime_l`** versions of these functions are identical except that they take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). The **`strftime`** functions support these formatting codes: -|Code|Replacement string| -|-|-| -|**`%a`**|Abbreviated weekday name in the locale| -|**`%A`**|Full weekday name in the locale| -|**`%b`**|Abbreviated month name in the locale| -|**`%B`**|Full month name in the locale| -|**`%c`**|Date and time representation appropriate for locale| -|**`%C`**|The year divided by 100 and truncated to an integer, as a decimal number (00−99)| -|**`%d`**|Day of month as a decimal number (01 - 31)| -|**`%D`**|Equivalent to **`%m/%d/%y`**| -|**`%e`**|Day of month as a decimal number (1 - 31), where single digits are preceded by a space| -|**`%F`**|Equivalent to **`%Y-%m-%d`**| -|**`%g`**|The last 2 digits of the ISO 8601 week-based year as a decimal number (00 - 99)| -|**`%G`**|The ISO 8601 week-based year as a decimal number| -|**`%h`**|Abbreviated month name (equivalent to **`%b`**)| -|**`%H`**|Hour in 24-hour format (00 - 23)| -|**`%I`**|Hour in 12-hour format (01 - 12)| -|**`%j`**|Day of the year as a decimal number (001 - 366)| -|**`%m`**|Month as a decimal number (01 - 12)| -|**`%M`**|Minute as a decimal number (00 - 59)| -|**`%n`**|A newline character (**`\n`**)| -|**`%p`**|The locale's A.M./P.M. indicator for 12-hour clock| -|**`%r`**|The locale's 12-hour clock time| -|**`%R`**|Equivalent to **`%H:%M`**| -|**`%S`**|Second as a decimal number (00 - 59)| -|**`%t`**|A horizontal tab character (**`\t`**)| -|**`%T`**|Equivalent to **`%H:%M:%S`**, the ISO 8601 time format| -|**`%u`**|ISO 8601 weekday as a decimal number (1 - 7; Monday is 1)| -|**`%U`**|Week number of the year as a decimal number (00 - 53), where the first Sunday is the first day of week 1| -|**`%V`**|ISO 8601 week number as a decimal number (00 - 53)| -|**`%w`**|Weekday as a decimal number (0 - 6; Sunday is 0)| -|**`%W`**|Week number of the year as a decimal number (00 - 53), where the first Monday is the first day of week 1| -|**`%x`**|Date representation for the locale| -|**`%X`**|Time representation for the locale| -|**`%y`**|Year without century, as decimal number (00 - 99)| -|**`%Y`**|Year with century, as decimal number| -|**`%z`**|The offset from UTC in ISO 8601 format; no characters if time zone is unknown| -|**`%Z`**|Either the locale's time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown| -|**`%%`**|Percent sign| +| Code | Replacement string | +|---|---| +| **`%a`** | Abbreviated weekday name in the locale | +| **`%A`** | Full weekday name in the locale | +| **`%b`** | Abbreviated month name in the locale | +| **`%B`** | Full month name in the locale | +| **`%c`** | Date and time representation appropriate for locale | +| **`%C`** | The year divided by 100 and truncated to an integer, as a decimal number (00−99) | +| **`%d`** | Day of month as a decimal number (01 - 31) | +| **`%D`** | Equivalent to **`%m/%d/%y`** | +| **`%e`** | Day of month as a decimal number (1 - 31), where single digits are preceded by a space | +| **`%F`** | Equivalent to **`%Y-%m-%d`** | +| **`%g`** | The last 2 digits of the ISO 8601 week-based year as a decimal number (00 - 99) | +| **`%G`** | The ISO 8601 week-based year as a decimal number | +| **`%h`** | Abbreviated month name (equivalent to **`%b`**) | +| **`%H`** | Hour in 24-hour format (00 - 23) | +| **`%I`** | Hour in 12-hour format (01 - 12) | +| **`%j`** | Day of the year as a decimal number (001 - 366) | +| **`%m`** | Month as a decimal number (01 - 12) | +| **`%M`** | Minute as a decimal number (00 - 59) | +| **`%n`** | A newline character (**`\n`**) | +| **`%p`** | The locale's A.M./P.M. indicator for 12-hour clock | +| **`%r`** | The locale's 12-hour clock time | +| **`%R`** | Equivalent to **`%H:%M`** | +| **`%S`** | Second as a decimal number (00 - 59) | +| **`%t`** | A horizontal tab character (**`\t`**) | +| **`%T`** | Equivalent to **`%H:%M:%S`**, the ISO 8601 time format | +| **`%u`** | ISO 8601 weekday as a decimal number (1 - 7; Monday is 1) | +| **`%U`** | Week number of the year as a decimal number (00 - 53), where the first Sunday is the first day of week 1 | +| **`%V`** | ISO 8601 week number as a decimal number (00 - 53) | +| **`%w`** | Weekday as a decimal number (0 - 6; Sunday is 0) | +| **`%W`** | Week number of the year as a decimal number (00 - 53), where the first Monday is the first day of week 1 | +| **`%x`** | Date representation for the locale | +| **`%X`** | Time representation for the locale | +| **`%y`** | Year without century, as decimal number (00 - 99) | +| **`%Y`** | Year with century, as decimal number | +| **`%z`** | The offset from UTC in ISO 8601 format; no characters if time zone is unknown | +| **`%Z`** | Either the locale's time-zone name or time zone abbreviation, depending on registry settings; no characters if time zone is unknown | +| **`%%`** | Percent sign | As in the **`printf`** function, the **`#`** flag may prefix any formatting code. In that case, the meaning of the format code is changed as follows. -|Format code|Meaning| -|-----------------|-------------| -|**`%#a`**, **`%#A`**, **`%#b`**, **`%#B`**, **`%#g`**, **`%#G`**, **`%#h`**, **`%#n`**, **`%#p`**, **`%#t`**, **`%#u`**, **`%#w`**, **`%#X`**, **`%#z`**, **`%#Z`**, **`%#%`**|**`#`** flag is ignored.| -|**`%#c`**|Long date and time representation, appropriate for the locale. For example: "Tuesday, March 14, 1995, 12:41:29".| -|**`%#x`**|Long date representation, appropriate to the locale. For example: "Tuesday, March 14, 1995".| -|**`%#d`**, **`%#D`**, **`%#e`**, **`%#F`**, **`%#H`**, **`%#I`**, **`%#j`**, **`%#m`**, **`%#M`**, **`%#r`**, **`%#R`**, **`%#S`**, **`%#T`**, **`%#U`**, **`%#V`**, **`%#W`**, **`%#y`**, **`%#Y`**|Remove leading zeros or spaces (if any).| +| Format code | Meaning | +|---|---| +| **`%#a`**, **`%#A`**, **`%#b`**, **`%#B`**, **`%#g`**, **`%#G`**, **`%#h`**, **`%#n`**, **`%#p`**, **`%#t`**, **`%#u`**, **`%#w`**, **`%#X`**, **`%#z`**, **`%#Z`**, **`%#%`** | **`#`** flag is ignored. | +| **`%#c`** | Long date and time representation, appropriate for the locale. For example: "Tuesday, March 14, 1995, 12:41:29". | +| **`%#x`** | Long date representation, appropriate to the locale. For example: "Tuesday, March 14, 1995". | +| **`%#d`**, **`%#D`**, **`%#e`**, **`%#F`**, **`%#H`**, **`%#I`**, **`%#j`**, **`%#m`**, **`%#M`**, **`%#r`**, **`%#R`**, **`%#S`**, **`%#T`**, **`%#U`**, **`%#V`**, **`%#W`**, **`%#y`**, **`%#Y`** | Remove leading zeros or spaces (if any). | -The ISO 8601 week and week-based year produced by **`%V`**, **`%g`**, and **`%G`**, uses a week that begins on Monday, where week 1 is the week that contains January 4th, which is the first week that includes at least four days of the year. If the first Monday of the year is the 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year. For those days, **`%V`** is replaced by 53, and both **`%g`** and **`%G`** are replaced by the digits of the preceding year. +The ISO 8601 week and week-based year produced by **`%V`**, **`%g`**, and **`%G`**, uses a week that begins on Monday. Week 1 is the week that contains the fourth day of January, which is the first week that includes at least four days of the year. If the first Monday of the year is the 2nd, 3rd, or 4th, the preceding days are part of the last week of the preceding year. For those days, **`%V`** is replaced by 53, and both **`%g`** and **`%G`** are replaced by the digits of the preceding year. > [!NOTE] -> When using one of the `strftime` functions with a `tm` pointer returned from `gmtime`, the values printed via the `%Z` and `%z` specifiers will not be accurate. This is because the `tm` struct as specified by the C Standard does not contain the information for time zone name nor offset. Instead, the timezone information is populated via the global variables [`_timezone` and `_dstbias`](../../c-runtime-library/daylight-dstbias-timezone-and-tzname.md). +> When using one of the `strftime` functions with a `tm` pointer returned from `gmtime`, the values printed via the `%Z` and `%z` specifiers will not be accurate. This is because the `tm` struct as specified by the C Standard does not contain the information for time zone name nor offset. Instead, the timezone information is populated via the global variables [`_timezone` and `_dstbias`](../daylight-dstbias-timezone-and-tzname.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strftime`**|``| -|**`wcsftime`**|`` or ``| -|**`_strftime_l`**|``| -|**`_wcsftime_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`strftime`** | `` | +| **`wcsftime`** | `` or `` | +| **`_strftime_l`** | `` | +| **`_wcsftime_l`** | `` or `` | -The **`_strftime_l`** and **`_wcsftime_l`** functions are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_strftime_l`** and **`_wcsftime_l`** functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -159,10 +158,10 @@ See the example for [`time`](time-time32-time64.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[Time Management](../../c-runtime-library/time-management.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`localeconv`](localeconv.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[Time management](../time-management.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md b/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md index 8e16c0c2fe7..a2a5dcd5634 100644 --- a/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md +++ b/docs/c-runtime-library/reference/stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md @@ -3,7 +3,7 @@ description: "Learn more about: _stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsic title: "_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l" ms.date: "4/2/2020" api_name: ["_stricmp_l", "_mbsicmp", "_wcsicmp", "_mbsicmp_l", "_stricmp", "_wcsicmp_l", "_o__mbsicmp", "_o__mbsicmp_l", "_o__stricmp", "_o__stricmp_l", "_o__wcsicmp", "_o__wcsicmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcsicmp", "_stricmp", "wcsicmp_l", "_wcsicmp", "_tcsicmp", "_strcmpi", "stricmp_l", "_mbsicmp", "_fstricmp", "mbsicmp_l", "mbsicmp"] @@ -51,27 +51,27 @@ int _mbsicmp_l( ### Parameters -*`string1`*, *`string2`*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value The return value indicates the relation of *`string1`* to *`string2`* as follows. -|Return value|Description| -|------------------|-----------------| -|< 0|*`string1`* less than *`string2`*| -|0|*`string1`* identical to *`string2`*| -|> 0|*`string1`* greater than *`string2`*| +| Return value | Description | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | -On an error, **`_mbsicmp`** returns **`_NLSCMPERROR`**, which is defined in `` and ``. +On an error, **`_mbsicmp`** returns `_NLSCMPERROR`, which is defined in `` and ``. ## Remarks -The **`_stricmp`** function ordinally compares *`string1`* and *`string2`* after converting each character to lowercase, and returns a value indicating their relationship. **`_stricmp`** differs from **`_stricoll`** in that the **`_stricmp`** comparison is only affected by **`LC_CTYPE`**, which determines which characters are upper and lowercase. The **`_stricoll`** function compares strings according to both the **`LC_CTYPE`** and **`LC_COLLATE`** categories of the locale, which includes both the case and the collation order. For more information about the **`LC_COLLATE`** category, see [`setlocale`](setlocale-wsetlocale.md) and [Locale Categories](../../c-runtime-library/locale-categories.md). The versions of these functions without the **`_l`** suffix use the current locale for locale-dependent behavior. The versions with the suffix are identical except that they use the locale passed in instead. If the locale has not been set, the C locale is used. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_stricmp`** function compares *`string1`* and *`string2`* after converting each character to lowercase, and returns a value indicating their relationship. **`_stricmp`** differs from **`_stricoll`** in that the **`_stricmp`** comparison is only affected by `LC_CTYPE`, which determines which characters are upper and lowercase. The **`_stricoll`** function compares strings according to both the `LC_CTYPE` and `LC_COLLATE` categories of the locale, which includes both the case and the collation order. For more information about the `LC_COLLATE` category, see [`setlocale`](setlocale-wsetlocale.md) and [Locale categories](../locale-categories.md). The versions of these functions without the **`_l`** suffix use the current locale for locale-dependent behavior. The versions with the suffix are identical except that they use the locale passed in instead. If the locale hasn't been set, the C locale is used. For more information, see [Locale](../locale.md). > [!NOTE] > **`_stricmp`** is equivalent to **`_strcmpi`**. They can be used interchangeably but **`_stricmp`** is the preferred standard. @@ -84,15 +84,15 @@ To illustrate when case conversion by **`_stricmp`** affects the outcome of a co If the [`strcmp`](strcmp-wcscmp-mbscmp.md) function is used instead of **`_stricmp`**, `JOHN_HENRY` will be greater than `JOHNSTON`. -**`_wcsicmp`** and **`_mbsicmp`** are wide-character and multibyte-character versions of **`_stricmp`**. The arguments and return value of **`_wcsicmp`** are wide-character strings; those of **`_mbsicmp`** are multibyte-character strings. **`_mbsicmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns **`_NLSCMPERROR`** on an error. For more information, see [Code Pages](../../c-runtime-library/code-pages.md). These three functions behave identically otherwise. +**`_wcsicmp`** and **`_mbsicmp`** are wide-character and multibyte-character versions of **`_stricmp`**. The arguments and return value of **`_wcsicmp`** are wide-character strings. The arguments and return value of **`_mbsicmp`** are multibyte-character strings. **`_mbsicmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns `_NLSCMPERROR` on an error. For more information, see [Code pages](../code-pages.md). These three functions behave identically otherwise. -**`_wcsicmp`** and **`wcscmp`** behave identically except that **`wcscmp`** does not convert its arguments to lowercase before comparing them. **`_mbsicmp`** and **`_mbscmp`** behave identically except that **`_mbscmp`** does not convert its arguments to lowercase before comparing them. +**`_wcsicmp`** and **`wcscmp`** behave identically except that **`wcscmp`** doesn't convert its arguments to lowercase before comparing them. **`_mbsicmp`** and **`_mbscmp`** behave identically except that **`_mbscmp`** doesn't convert its arguments to lowercase before comparing them. -You will need to call [`setlocale`](setlocale-wsetlocale.md) for **`_wcsicmp`** to work with Latin 1 characters. The C locale is in effect by default, so, for example, ä will not compare equal to Ä. Call **`setlocale`** with any locale other than the C locale before the call to **`_wcsicmp`**. The following sample demonstrates how **`_wcsicmp`** is sensitive to the locale: +You'll need to call [`setlocale`](setlocale-wsetlocale.md) for **`_wcsicmp`** to work with Latin 1 characters. The C locale is in effect by default, so, for example, ä won't compare equal to Ä. Call **`setlocale`** with any locale other than the C locale before the call to **`_wcsicmp`**. The following sample demonstrates how **`_wcsicmp`** is sensitive to the locale: ```C // crt_stricmp_locale.c -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). #include #include @@ -108,23 +108,23 @@ int main() { An alternative is to call [`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md) and pass the returned locale object as a parameter to **`_wcsicmp_l`**. -All of these functions validate their parameters. If either *`string1`* or *`string2`* are null pointers, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return **`_NLSCMPERROR`** and set **`errno`** to **`EINVAL`**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* are null pointers, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsicmp`**|**`_stricmp`**|**`_mbsicmp`**|**`_wcsicmp`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsicmp` | **`_stricmp`** | **`_mbsicmp`** | **`_wcsicmp`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_stricmp`**, **`_stricmp_l`**|``| -|**`_wcsicmp`**, **`_wcsicmp_l`**|`` or ``| -|**`_mbsicmp`**, **`_mbsicmp_l`**|``| +| Routine | Required header | +|---|---| +| **`_stricmp`**, **`_stricmp_l`** | `` | +| **`_wcsicmp`**, **`_wcsicmp_l`** | `` or `` | +| **`_mbsicmp`**, **`_mbsicmp_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -177,13 +177,13 @@ Compare strings: ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)
-[`_memicmp`, `_memicmp_l`](memicmp-memicmp-l.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`memcmp`, `wmemcmp`](memcmp-wmemcmp.md)\ +[`_memicmp`, `_memicmp_l`](memicmp-memicmp-l.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md b/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md index fa1fa5f9b9f..c5ed7b742dd 100644 --- a/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md +++ b/docs/c-runtime-library/reference/stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _w title: "_stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _wcsicoll_l, _mbsicoll_l" ms.date: "4/2/2020" api_name: ["_mbsicoll_l", "_stricoll_l", "_mbsicoll", "_wcsicoll_l", "_wcsicoll", "_stricoll", "_o__mbsicoll", "_o__mbsicoll_l", "_o__stricoll", "_o__stricoll_l", "_o__wcsicoll", "_o__wcsicoll_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["stricoll", "_stricoll", "_wcsicoll", "mbsicoll_l", "_mbsicoll", "_ftcsicoll", "wcsicoll_l", "_tcsicoll", "mbsicoll", "stricoll_l"] +f1_keywords: ["STRING/_stricoll", "CORECRT_WSTRING/_wcsicoll", "MBSTRING/_mbsicoll", "TCHAR/_tcsicoll", "TCHAR/_ftcsicoll", "STRING/_stricoll_l", "CORECRT_WSTRING/_wcsicoll_l", "MBSTRING/_mbsicoll_l", "TCHAR/_tcsicoll_l", "_stricoll", "_wcsicoll", "_mbsicoll", "_tcsicoll", "_ftcsicoll", "_stricoll_l", "_wcsicoll_l", "_mbsicoll_l", "_tcsicoll_l", "stricoll", "mbsicoll", "stricoll_l", "wcsicoll_l", "mbsicoll_l"] helpviewer_keywords: ["code pages, using for string comparisons", "_ftcsicoll function", "_mbsicoll_l function", "_mbsicoll function", "mbsicoll function", "stricoll function", "tcsicoll function", "string comparison [C++], culture-specific", "_tcsicoll function", "_stricoll function", "_stricoll_l function", "_wcsicoll function", "mbsicoll_l function", "stricoll_l function", "strings [C++], comparing by code page", "ftcsicoll function"] ms.assetid: 8ec93016-5a49-49d2-930f-721566661d82 --- -# _stricoll, _wcsicoll, _mbsicoll, _stricoll_l, _wcsicoll_l, _mbsicoll_l +# `_stricoll`, `_wcsicoll`, `_mbsicoll`, `_stricoll_l`, `_wcsicoll_l`, `_mbsicoll_l` Compares strings by using locale-specific information. > [!IMPORTANT] -> **_mbsicoll** and **_mbsicoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsicoll`** and **`_mbsicoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -51,61 +51,61 @@ int _mbsicoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns a value indicating the relationship of *string1* to *string2*, as follows. +Each of these functions returns a value indicating the relationship of *`string1`* to *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* less than *string2*| -|0|*string1* identical to *string2*| -|> 0|*string1* greater than *string2*| -|**_NLSCMPERROR**|An error occurred.| +| Return value | Relationship of *`string1`* to *`string2`* | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | +| `_NLSCMPERROR` | An error occurred. | -Each of these functions returns **_NLSCMPERROR**. To use **_NLSCMPERROR**, include either \ or \. **_wcsicoll** can fail if either *string1* or *string2* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **_wcsicoll** may set **errno** to **EINVAL**. To check for an error on a call to **_wcsicoll**, set **errno** to 0 and then check **errno** after calling **_wcsicoll**. +Each of these functions returns `_NLSCMPERROR`. To use `_NLSCMPERROR`, include either \ or \. **`_wcsicoll`** can fail if either *`string1`* or *`string2`* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **`_wcsicoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`_wcsicoll`**, set `errno` to 0 and then check `errno` after calling **`_wcsicoll`**. ## Remarks -Each of these functions performs a case-insensitive comparison of *string1* and *string2* according to the code page currently in use. These functions should be used only when there is a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. +Each of these functions performs a case-insensitive comparison of *`string1`* and *`string2`* according to the code page currently in use. These functions should be used only when there's a difference between the character set order and the lexicographic character order in the current code page and this difference is of interest for the string comparison. -**_stricmp** differs from **_stricoll** in that the **_stricmp** comparison is affected by **LC_CTYPE**, whereas the **_stricoll** comparison is according to the **LC_CTYPE** and **LC_COLLATE** categories of the locale. For more information on the **LC_COLLATE** category, see [setlocale](setlocale-wsetlocale.md) and [Locale Categories](../../c-runtime-library/locale-categories.md). The versions of these functions without the **_l** suffix use the current locale; the versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +`_stricmp` differs from **`_stricoll`** in that the `_stricmp` comparison is affected by `LC_CTYPE`, whereas the **`_stricoll`** comparison is according to the `LC_CTYPE` and `LC_COLLATE` categories of the locale. For more information on the `LC_COLLATE` category, see [`setlocale`](setlocale-wsetlocale.md) and [Locale categories](../locale-categories.md). The versions of these functions without the `_l` suffix use the current locale; the versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* are **NULL** pointers, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* are `NULL` pointers, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsicoll**|**_stricoll**|**_mbsicoll**|**_wcsicoll**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsicoll` | **`_stricoll`** | **`_mbsicoll`** | **`_wcsicoll`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_stricoll**, **_stricoll_l**|\| -|**_wcsicoll**, **_wcsicoll_l**|\, \| -|**_mbsicoll**, **_mbsicoll_l**|\| +| Routine | Required header | +|---|---| +| **`_stricoll`**, **`_stricoll_l`** | \ | +| **`_wcsicoll`**, **`_wcsicoll_l`** | \, \ | +| **`_mbsicoll`**, **`_mbsicoll_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md b/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md index 1a25f8da08f..57008d56786 100644 --- a/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md +++ b/docs/c-runtime-library/reference/strinc-wcsinc-mbsinc-mbsinc-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strinc, _wcsinc, _mbsinc, _mbsinc_l" title: "_strinc, _wcsinc, _mbsinc, _mbsinc_l" ms.date: "4/2/2020" api_name: ["_mbsinc", "_wcsinc", "_mbsinc_l", "_strinc", "_o__mbsinc", "_o__mbsinc_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsinc_l", "_strinc", "strinc", "_mbsinc", "_wcsinc", "wcsinc", "mbsinc", "_mbsinc_l"] helpviewer_keywords: ["_mbsinc function", "wcsinc function", "mbsinc_l function", "_strinc function", "strinc function", "_mbsinc_l function", "mbsinc function", "_wcsinc function", "_tcsinc function", "tcsinc function"] ms.assetid: 54685943-8e2c-45e9-a559-2d94930dc6b4 --- -# _strinc, _wcsinc, _mbsinc, _mbsinc_l +# `_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l` Advances a string pointer by one character. > [!IMPORTANT] -> **_mbsinc** and **_mbsinc_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsinc`** and **`_mbsinc_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -39,43 +39,43 @@ unsigned char *_mbsinc_l( ### Parameters -*current*
+*`current`*\ Character pointer. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a pointer to the character that immediately follows *current*. +Each of these routines returns a pointer to the character that immediately follows *`current`*. ## Remarks -The **_mbsinc** function returns a pointer to the first byte of the multibyte character that immediately follows *current*. **_mbsinc** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) that's currently in use; **_mbsinc_l** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_mbsinc`** function returns a pointer to the first byte of the multibyte character that immediately follows *`current`*. **`_mbsinc`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) that's currently in use; **`_mbsinc_l`** is identical except that it instead uses the locale parameter that's passed in. For more information, see [Locale](../locale.md). -The generic-text function **_tcsinc**, defined in Tchar.h, maps to **_mbsinc** if **_MBCS** has been defined, or to **_wcsinc** if **_UNICODE** has been defined. Otherwise, **_tcsinc** maps to **_strinc**. **_strinc** and **_wcsinc** are single-byte-character and wide-character versions of **_mbsinc**. **_strinc** and **_wcsinc** are provided only for this mapping and should not be used otherwise. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +The generic-text function `_tcsinc`, defined in Tchar.h, maps to **`_mbsinc`** if `_MBCS` has been defined, or to **`_wcsinc`** if `_UNICODE` has been defined. Otherwise, `_tcsinc` maps to **`_strinc`**. **`_strinc`** and **`_wcsinc`** are single-byte-character and wide-character versions of **`_mbsinc`**. **`_strinc`** and **`_wcsinc`** are provided only for this mapping and shouldn't be used otherwise. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -If *current* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, this function returns **EINVAL** and sets **errno** to **EINVAL**. +If *`current`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, this function returns `EINVAL` and sets `errno` to `EINVAL`. > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsinc**|\| -|**_mbsinc_l**|\| -|**_strinc**|\| -|**_wcsinc**|\| +| Routine | Required header | +|---|---| +| **`_mbsinc`** | \ | +| **`_mbsinc_l`** | \ | +| **`_strinc`** | \ | +| **`_wcsinc`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strdec, _wcsdec, _mbsdec, _mbsdec_l](strdec-wcsdec-mbsdec-mbsdec-l.md)
-[_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)
-[_strninc, _wcsninc, _mbsninc, _mbsninc_l](strninc-wcsninc-mbsninc-mbsninc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](strdec-wcsdec-mbsdec-mbsdec-l.md)\ +[`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)\ +[`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](strninc-wcsninc-mbsninc-mbsninc-l.md) diff --git a/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md b/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md index 4e1f6668998..73cda48cad0 100644 --- a/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md +++ b/docs/c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _ title: "strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l" ms.date: "4/2/2020" api_name: ["_mbslen", "_mbslen_l", "_mbstrlen", "wcslen", "_mbstrlen_l", "strlen", "_o__mbslen", "_o__mbslen_l", "_o__mbstrlen", "_o__mbstrlen_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbstrlen", "wcslen", "_tcslen", "_ftcslen", "strlen", "_mbslen"] @@ -44,13 +44,13 @@ size_t _mbstrlen_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated string. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Each of these functions returns the number of characters in *`str`*, excluding the terminal null. No return value is reserved to indicate an error, except for **`_mbstrlen`** and **`_mbstrlen_l`**, which return `((size_t)(-1))` if the string contains an invalid multibyte character. @@ -58,32 +58,32 @@ Each of these functions returns the number of characters in *`str`*, excluding t **`strlen`** interprets the string as a single-byte character string, so its return value is always equal to the number of bytes, even if the string contains multibyte characters. **`wcslen`** is a wide-character version of **`strlen`**; the argument of **`wcslen`** is a wide-character string and the count of characters is in wide (two-byte) characters. **`wcslen`** and **`strlen`** behave identically otherwise. -**Security Note** These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcslen`**|**`strlen`**|**`strlen`**|**`wcslen`**| -|**`_tcsclen`**|**`strlen`**|**`_mbslen`**|**`wcslen`**| -|**`_tcsclen_l`**|**`strlen`**|**`_mbslen_l`**|**`wcslen`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcslen` | **`strlen`** | **`strlen`** | **`wcslen`** | +| `_tcsclen` | **`strlen`** | **`_mbslen`** | **`wcslen`** | +| `_tcsclen_l` | **`strlen`** | **`_mbslen_l`** | **`wcslen`** | -**`_mbslen`** and **`_mbslen_l`** return the number of multibyte characters in a multibyte-character string but they do not test for multibyte-character validity. **`_mbstrlen`** and **`_mbstrlen_l`** test for multibyte-character validity and recognize multibyte-character sequences. If the string passed to **`_mbstrlen`** or **`_mbstrlen_l`** contains an invalid multibyte character for the code page, the function returns -1 and sets **`errno`** to **`EILSEQ`**. +**`_mbslen`** and **`_mbslen_l`** return the number of multibyte characters in a multibyte-character string but they don't test for multibyte-character validity. **`_mbstrlen`** and **`_mbstrlen_l`** test for multibyte-character validity and recognize multibyte-character sequences. If the string passed to **`_mbstrlen`** or **`_mbstrlen_l`** contains an invalid multibyte character for the code page, the function returns -1 and sets `errno` to `EILSEQ`. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale; see [`setlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strlen`**|``| -|**`wcslen`**|`` or ``| -|**`_mbslen`**, **`_mbslen_l`**|``| -|**`_mbstrlen`**, **`_mbstrlen_l`**|``| +| Routine | Required header | +|---|---| +| **`strlen`** | `` | +| **`wcslen`** | `` or `` | +| **`_mbslen`**, **`_mbslen_l`** | `` | +| **`_mbstrlen`**, **`_mbstrlen_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -150,14 +150,14 @@ Bytes in 'ABCァD' : 6 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Locale](../../c-runtime-library/locale.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md b/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md index ffda71534d0..41dd8656868 100644 --- a/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md +++ b/docs/c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, title: "_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l" ms.date: "4/2/2020" api_name: ["_strlwr_s_l", "_mbslwr_s_l", "_mbslwr_s", "_wcslwr_s", "_strlwr_s", "_wcslwr_s_l", "_o__mbslwr_s", "_o__mbslwr_s_l", "_o__strlwr_s", "_o__strlwr_s_l", "_o__wcslwr_s", "_o__wcslwr_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strlwr_s_l", "_strlwr_s", "mbslwr_s_l", "strlwr_s_l", "_wcslwr_s", "strlwr_s", "mbslwr_s", "_wcslwr_s_l", "wcslwr_s_l", "_tcslwr_s", "_tcslwr_s_l", "_mbslwr_s_l", "wcslwr_s", "_mbslwr_s"] helpviewer_keywords: ["_tcslwr_s function", "wcslwr_s function", "_mbslwr_s function", "_wcslwr_s function", "strlwr_s_l function", "mbslwr_s_l function", "_strlwr_s function", "string conversion [C++], case", "strlwr_s function", "wcslwr_s_l function", "_tcslwr_s_l function", "mbslwr_s function", "strings [C++], case", "_wcslwr_s_l function", "converting case, CRT functions", "_strlwr_s_l function", "_mbslwr_s_l function", "case, converting", "tcslwr_s function", "tcslwr_s_l function", "strings [C++], converting case"] ms.assetid: 4883d31b-bdac-4049-83a1-91dfdeceee79 --- -# _strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l +# `_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l` -Converts a string to lowercase, by using the current locale or a locale object that's passed in. These versions of [_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a string to lowercase, by using the current locale or a locale object that's passed in. These versions of [`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbslwr_s** and **_mbslwr_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbslwr_s`** and **`_mbslwr_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -78,49 +78,49 @@ errno_t _wcslwr_s_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to convert to lowercase. -*numberOfElements*
+*`numberOfElements`*\ Size of the buffer. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful; a non-zero error code on failure. -These functions validate their parameters. If *str* is not a valid null-terminated string, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the functions return **EINVAL** and set **errno** to **EINVAL**. If *numberOfElements* is less than the length of the string, the functions also return **EINVAL** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`str`* isn't a valid null-terminated string, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the functions return `EINVAL` and set `errno` to `EINVAL`. If *`numberOfElements`* is less than the length of the string, the functions also return `EINVAL` and set `errno` to `EINVAL`. ## Remarks -The **_strlwr_s** function converts, in place, any uppercase letters in *str* to lowercase. **_mbslwr_s** is a multi-byte character version of **_strlwr_s**. **_wcslwr_s** is a wide-character version of **_strlwr_s**. +The **`_strlwr_s`** function converts, in place, any uppercase letters in *`str`* to lowercase. **`_mbslwr_s`** is a multi-byte character version of **`_strlwr_s`**. **`_wcslwr_s`** is a wide-character version of **`_strlwr_s`**. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcslwr_s**|**_strlwr_s**|**_mbslwr_s**|**_wcslwr_s**| -|**_tcslwr_s_l**|**_strlwr_s_l**|**_mbslwr_s_l**|**_wcslwr_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcslwr_s` | **`_strlwr_s`** | **`_mbslwr_s`** | **`_wcslwr_s`** | +| `_tcslwr_s_l` | **`_strlwr_s_l`** | **`_mbslwr_s_l`** | **`_wcslwr_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strlwr_s**, **_strlwr_s_l**|\| -|**_mbslwr_s**, **_mbslwr_s_l**|\| -|**_wcslwr_s**, **_wcslwr_s_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_strlwr_s`**, **`_strlwr_s_l`** | \ | +| **`_mbslwr_s`**, **`_mbslwr_s_l`** | \ | +| **`_wcslwr_s`**, **`_wcslwr_s_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -162,7 +162,7 @@ Upper: THE STRING TO END ALL STRINGS! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) diff --git a/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md b/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md index 8ce41f53d46..0592f466da4 100644 --- a/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md +++ b/docs/c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, title: "_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l" ms.date: "4/2/2020" api_name: ["_strlwr_l", "_strlwr", "_wcslwr_l", "_mbslwr_l", "_wcslwr", "_mbslwr", "_o__mbslwr", "_o__mbslwr_l", "_o__strlwr", "_o__strlwr_l", "_o__wcslwr", "_o__wcslwr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strlwr", "wcslwr_l", "_ftcslwr", "mbslwr_l", "_mbslwr", "_wcslwr", "strlwr_l", "_tcslwr", "mbslwr"] helpviewer_keywords: ["tcslwr function", "_strlwr function", "converting case", "string conversion [C++], case", "mbslwr function", "_strlwr_l function", "strlwr_l function", "_wcslwr function", "ftcslwr function", "strings [C++], case", "_tcslwr_l function", "_wcslwr_l function", "wcslwr_l function", "mbslwr_l function", "tcslwr_l function", "_tcslwr function", "converting case, CRT functions", "_ftcslwr function", "_mbslwr function", "case, converting", "strings [C++], converting case", "_mbslwr_l function"] ms.assetid: d279181d-2e7d-401f-ab44-6e7c2786a046 --- -# _strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l +# `_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l` -Converts a string to lowercase. More secure versions of these functions are available; see [_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md). +Converts a string to lowercase. More secure versions of these functions are available; see [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md). > [!IMPORTANT] -> **_mbslwr** and **_mbslwr_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbslwr`** and **`_mbslwr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -72,44 +72,44 @@ unsigned char *_mbslwr_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to convert to lowercase. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Each of these functions returns a pointer to the converted string. Because the modification is done in place, the pointer returned is the same as the pointer passed as the input argument. No return value is reserved to indicate an error. ## Remarks -The **_strlwr** function converts any uppercase letters in *str* to lowercase as determined by the **LC_CTYPE** category setting of the locale. Other characters are not affected. For more information on **LC_CTYPE**, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for their locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_strlwr`** function converts any uppercase letters in *`str`* to lowercase as determined by the `LC_CTYPE` category setting of the locale. Other characters aren't affected. For more information on `LC_CTYPE`, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for their locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -The **_wcslwr** and **_mbslwr** functions are wide-character and multibyte-character versions of **_strlwr**. The argument and return value of **_wcslwr** are wide-character strings; those of **_mbslwr** are multibyte-character strings. These three functions behave identically otherwise. +The **`_wcslwr`** and **`_mbslwr`** functions are wide-character and multibyte-character versions of **`_strlwr`**. The argument and return value of **`_wcslwr`** are wide-character strings. The argument and return value of **`_mbslwr`** are multibyte-character strings. These three functions behave identically otherwise. -If *str* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set **errno** to **EINVAL**. +If *`str`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set `errno` to `EINVAL`. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcslwr**|**_strlwr**|**_mbslwr**|**_wcslwr**| -|**_tcslwr_l**|**_strlwr_l**|**_mbslwr_l**|**_wcslwr_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcslwr` | **`_strlwr`** | **`_mbslwr`** | **`_wcslwr`** | +| `_tcslwr_l` | **`_strlwr_l`** | **`_mbslwr_l`** | **`_wcslwr_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strlwr**, **_strlwr_l**|\| -|**_wcslwr**, **_wcslwr_l**|\ or \| -|**_mbslwr**, **_mbslwr_l**|\| +| Routine | Required header | +|---|---| +| **`_strlwr`**, **`_strlwr_l`** | \ | +| **`_wcslwr`**, **`_wcslwr_l`** | \ or \ | +| **`_mbslwr`**, **`_mbslwr_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -149,6 +149,6 @@ Upper: THE STRING TO END ALL STRINGS! ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) diff --git a/docs/c-runtime-library/reference/strlwr-wcslwr.md b/docs/c-runtime-library/reference/strlwr-wcslwr.md index e3e3f281e2c..4584af826bd 100644 --- a/docs/c-runtime-library/reference/strlwr-wcslwr.md +++ b/docs/c-runtime-library/reference/strlwr-wcslwr.md @@ -10,8 +10,8 @@ f1_keywords: ["wcslwr", "strlwr"] helpviewer_keywords: ["strlwr function", "wcslwr function"] ms.assetid: b9274824-4365-4674-b656-823c89653656 --- -# strlwr, wcslwr +# `strlwr`, `wcslwr` -The Microsoft-specific function names `strlwr` and `wcslwr` are deprecated aliases for the [_strlwr and _wcslwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strlwr` and `wcslwr` are deprecated aliases for the [`_strlwr` and `_wcslwr`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strlwr or _wcslwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) or the security-enhanced [_strlwr_s and _wcslwr_s](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [_strlwr or _wcslwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) or the security-enhanced [`_strlwr_s` and `_wcslwr_s`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md b/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md index 4a7faa8c6e2..80f787fd85d 100644 --- a/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md +++ b/docs/c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l title: "strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l" ms.date: "3/25/2021" api_name: ["_wcsncat_s_l", "wcsncat_s", "_mbsncat_s_l", "_mbsncat_s", "strncat_s", "_strncat_s_l", "_o__mbsncat_s", "_o__mbsncat_s_l", "_o_strncat_s", "_o_wcsncat_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strncat_s_l", "_mbsncat_s_l", "_tcsncat_s", "wcsncat_s", "wcsncat_s_l", "strncat_s", "_mbsncat_s", "_tcsncat_s_l"] helpviewer_keywords: ["concatenating strings", "_mbsncat_s function", "mbsncat_s_l function", "_tcsncat_s function", "_mbsncat_s_l function", "strncat_s function", "strings [C++], appending", "strncat_s_l function", "string concatenation [C++]", "_tcsncat_s_l function", "wcsncat_s function", "appending strings", "wcsncat_s_l function", "mbsncat_s function"] ms.assetid: de77eca2-4d9c-4e66-abf2-a95fefc21e5a --- -# strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l +# `strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l` -Appends characters to a string. These versions of [strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Appends characters to a string. These versions of [`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsncat_s** and **_mbsncat_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsncat_s`** and **`_mbsncat_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -102,38 +102,38 @@ errno_t _mbsncat_s_l( ### Parameters -*strDest*
+*`strDest`*\ Null-terminated destination string. -*numberOfElements*
+*`numberOfElements`*\ Size of the destination buffer. -*strSource*
+*`strSource`*\ Null-terminated source string. -*count*
-Number of characters to append, or [_TRUNCATE](../../c-runtime-library/truncate.md). +*`count`*\ +Number of characters to append, or [`_TRUNCATE`](../truncate.md). -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns 0 if successful, an error code on failure. -### Error Conditions +### Error conditions -|*strDestination*|*numberOfElements*|*strSource*|Return value|Contents of *strDestination*| -|----------------------|------------------------|-----------------|------------------|----------------------------------| -|**NULL** or unterminated|any|any|**EINVAL**|not modified| -|any|any|**NULL**|**EINVAL**|not modified| -|any|0, or too small|any|**ERANGE**|not modified| +| *`strDestination`* | *`numberOfElements`* | *`strSource`* | Return value | Contents of *`strDestination`* | +|---|---|---|---|---| +| `NULL` or unterminated | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | not modified | +| any | 0, or too small | any | `ERANGE` | not modified | ## Remarks -These functions try to append the first *D* characters of *strSource* to the end of *strDest*, where *D* is the lesser of *count* and the length of *strSource*. If appending those *D* characters will fit within *strDest* (whose size is given as *numberOfElements*) and still leave room for a null terminator, then those characters are appended, starting at the original terminating null of *strDest*, and a new terminating null is appended; otherwise, *strDest*[0] is set to the null character and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +These functions try to append the first `D` characters of *`strSource`* to the end of *`strDest`*, where `D` is the lesser of *`count`* and the length of *`strSource`*. If appending those `D` characters will fit within *`strDest`* (whose size is given as *`numberOfElements`*) and still leave room for a null terminator, then those characters are appended, starting at the original terminating null of *`strDest`*, and a new terminating null is appended; otherwise, *`strDest[0]`* is set to the null character and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -There is an exception to the above paragraph. If *count* is [_TRUNCATE](../../c-runtime-library/truncate.md), then as much of *strSource* as will fit is appended to *strDest* while still leaving room to append a terminating null. +There's an exception to the above paragraph. If *`count`* is [`_TRUNCATE`](../truncate.md), then as much of *`strSource`* as will fit is appended to *`strDest`* while still leaving room to append a terminating null. For example, @@ -143,9 +143,9 @@ strncpy_s(dst, _countof(dst), "12", 2); strncat_s(dst, _countof(dst), "34567", 3); ``` -means that we're asking **strncat_s** to append three characters to two characters in a buffer five characters long; this would leave no space for the null terminator, hence **strncat_s** zeroes out the string and calls the invalid parameter handler. +means that we're asking **`strncat_s`** to append three characters to two characters in a buffer five characters long; it would leave no space for the null terminator, so **`strncat_s`** zeroes out the string, and calls the invalid parameter handler. -If truncation behavior is needed, use **_TRUNCATE** or adjust the *count* parameter accordingly: +If truncation behavior is needed, use `_TRUNCATE` or adjust the *`count`* parameter accordingly: ```C strncat_s(dst, _countof(dst), "34567", _TRUNCATE); @@ -159,36 +159,36 @@ strncat_s(dst, _countof(dst), "34567", _countof(dst)-strlen(dst)-1); In all cases, the resulting string is terminated with a null character. If copying takes place between strings that overlap, the behavior is undefined. -If *strSource* or *strDest* is **NULL**, or *numberOfElements* is zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function returns **EINVAL** without modifying its parameters. +If *`strSource`* or *`strDest`* is `NULL`, or *`numberOfElements`* is zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the function returns `EINVAL` without modifying its parameters. -**wcsncat_s** and **_mbsncat_s** are wide-character and multibyte-character versions of **strncat_s**. The string arguments and return value of **wcsncat_s** are wide-character strings; those of **_mbsncat_s** are multibyte-character strings. These three functions behave identically otherwise. +**`wcsncat_s`** and **`_mbsncat_s`** are wide-character and multibyte-character versions of **`strncat_s`**. The string arguments and return value of **`wcsncat_s`** are wide-character strings. The arguments and return value of **`_mbsncat_s`** are multibyte-character strings. These three functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale. For more information, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsncat_s**|**strncat_s**|**_mbsnbcat_s**|**wcsncat_s**| -|**_tcsncat_s_l**|**_strncat_s_l**|**_mbsnbcat_s_l**|**_wcsncat_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncat_s` | **`strncat_s`** | **`_mbsnbcat_s`** | **`wcsncat_s`** | +| `_tcsncat_s_l` | **`_strncat_s_l`** | **`_mbsnbcat_s_l`** | **`_wcsncat_s_l`** | -**_strncat_s_l** and **_wcsncat_s_l** have no locale dependence; they're are only provided for **_tcsncat_s_l**. +**`_strncat_s_l`** and **`_wcsncat_s_l`** have no locale dependence; they're only provided for **`_tcsncat_s_l`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strncat_s**|\| -|**wcsncat_s**|\ or \| -|**_mbsncat_s**, **_mbsncat_s_l**|\| +| Routine | Required header | +|---|---| +| **`strncat_s`** | \ | +| **`wcsncat_s`** | \ or \ | +| **`_mbsncat_s`**, **`_mbsncat_s_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -329,16 +329,16 @@ Invalid parameter handler invoked: (L"Buffer is too small" && 0) ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md b/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md index 6d4f57cb244..53ae6ad1dfd 100644 --- a/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md +++ b/docs/c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l" title: "strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l" +description: "Learn more about: strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l" ms.date: "1/20/2021" api_name: ["strncat", "_strncat_l", "_mbsncat", "_mbsncat_l", "wcsncat", "wcsncat_l", "_o__mbsncat", "_o__mbsncat_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsncat_l", "_wcsncat_l", "_tcsnccat_l", "_mbsncat", "_strncat_l", "strncat", "_tcsnccat", "_mbsncat_l", "_ftcsncat", "wcsncat", "_tcsncat"] helpviewer_keywords: ["concatenating strings", "ftcsncat function", "tcsncat_l function", "_tcsnccat_l function", "_tcsncat function", "strncat function", "_ftcsncat function", "mbsncat function", "mbsncat_l function", "strings [C++], appending", "wcsncat function", "tcsnccat function", "tcsnccat_l function", "_tcsnccat function", "string concatenation [C++]", "appending strings", "characters [C++], appending to strings", "_mbsncat function", "_tcsncat_l function", "_mbsncat_l function", "tcsncat function"] --- -# strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l +# `strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l` -Appends characters of a string. More secure versions of these functions are available, see `[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) . +Appends characters of a string. More secure versions of these functions are available; see [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md). > [!IMPORTANT] -> **`_mbsncat`** and **`_mbsncat_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsncat`** and **`_mbsncat_l`** can't be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -81,7 +81,7 @@ Number of characters to append. *`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the destination string. No return value is reserved to indicate an error. @@ -90,20 +90,20 @@ Returns a pointer to the destination string. No return value is reserved to indi The **`strncat`** function appends, at most, the first *`count`* characters of *`strSource`* to *`strDest`*. The initial character of *`strSource`* overwrites the terminating null character of *`strDest`*. If a null character appears in *`strSource`* before *`count`* characters are appended, **`strncat`** appends all characters from *`strSource`*, up to the null character. If *`count`* is greater than the length of *`strSource`*, the length of *`strSource`* is used in place of *`count`*. In all cases, the resulting string is terminated with a null character. If copying takes place between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> **`strncat`** does not check for sufficient space in *`strDest`*; it is therefore a potential cause of buffer overruns. Keep in mind that *`count`* limits the number of characters appended; it is not a limit on the size of *`strDest`*. See the example below. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> **`strncat`** does not check for sufficient space in *`strDest`*; it is therefore a potential cause of buffer overruns. Keep in mind that *`count`* limits the number of characters appended; it is not a limit on the size of *`strDest`*. See the example below. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -**`wcsncat`** and **`_mbsncat`** are wide-character and multibyte-character versions of **`strncat`**. The string arguments and return value of **`wcsncat`** are wide-character strings; those of **`_mbsncat`** are multibyte-character strings. These three functions behave identically otherwise. +**`wcsncat`** and **`_mbsncat`** are wide-character and multibyte-character versions of **`strncat`**. The string arguments and return value of **`wcsncat`** are wide-character strings. The string arguments and return value of **`_mbsncat`** are multibyte-character strings. These three functions behave identically otherwise. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, these functions have template overloads. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings | `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | -|--|--|--|--| +|---|---|---|---| | **`_tcsncat`** | **`strncat`** | **`_mbsnbcat`** | **`wcsncat`** | | **`_tcsncat_l`** | **`_strncat_l`** | **`_mbsnbcat_l`** | **`_wcsncat_l`** | @@ -112,14 +112,14 @@ By default, this function's global state is scoped to the application. To change ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncat`**|\| -|**`wcsncat`**|\ or \| -|**`_mbsncat`**|\| -|**`_mbsncat_l`**|\| +| Routine | Required header | +|---|---| +| **`strncat`** | \ | +| **`wcsncat`** | \ or \ | +| **`_mbsncat`** | \ | +| **`_mbsncat_l`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -168,20 +168,20 @@ After BadAppend : This is the initial string!Extra text to add to (47 chars) After GoodAppend: This is the initial string!Extra text t (39 chars) ``` -Note that **BadAppend** caused a buffer overrun. +You can see that `BadAppend` caused a buffer overrun. ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[`_mbsnbcat, _mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ -[`strcat, wcscat, _mbscat`](strcat-wcscat-mbscat.md)\ -[`strcmp, wcscmp, _mbscmp`](strcmp-wcscmp-mbscmp.md)\ -[`strcpy, wcscpy, _mbscpy`](strcpy-wcscpy-mbscpy.md)\ -[`strncmp, wcsncmp, _mbsncmp, _mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ -[`strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ -[`_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ -[`strrchr, wcsrchr, _mbsrchr, _mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ -[`_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ -[`strspn, wcsspn, _mbsspn, _mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ -[Locale](../../c-runtime-library/locale.md)\ -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md b/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md index 84d81d578b1..78e1b172c52 100644 --- a/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md +++ b/docs/c-runtime-library/reference/strncmp-wcsncmp-mbsncmp-mbsncmp-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strncmp, wcsncmp, _mbsncmp, _mbsncmp_l" title: "strncmp, wcsncmp, _mbsncmp, _mbsncmp_l" ms.date: "4/2/2020" api_name: ["strncmp", "_mbsncmp", "wcsncmp", "_mbsncmp_l", "_o__mbsncmp", "_o__mbsncmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcsnccmp", "_ftcsncmp", "_tcsncmp", "_tcsnccmp", "strncmp", "_mbsncmp", "wcsncmp"] @@ -49,57 +49,56 @@ int _mbsncmp_l( ### Parameters -*`string1`*, *`string2`*
+*`string1`*, *`string2`*\ Strings to compare. -*`count`*
+*`count`*\ Number of characters to compare. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value The return value indicates the relation of the substrings of *`string1`* and *`string2`* as follows. -|Return value|Description| -|------------------|-----------------| -|< 0|*`string1`* substring less than *`string2`* substring| -|0|*`string1`* substring identical to *`string2`* substring| -|> 0|*`string1`* substring greater than *`string2`* substring| +| Return value | Description | +|---|---| +| < 0 | *`string1`* substring less than *`string2`* substring | +| 0 | *`string1`* substring identical to *`string2`* substring | +| > 0 | *`string1`* substring greater than *`string2`* substring | -On a parameter validation error, **`_mbsncmp`** and **`_mbsncmp_l`** return **`_NLSCMPERROR*`*, which is defined in `` and ``. +On a parameter validation error, **`_mbsncmp`** and **`_mbsncmp_l`** return **`_NLSCMPERROR`**, which is defined in `` and ``. ## Remarks The **`strncmp`** function performs an ordinal comparison of at most the first *`count`* characters in *`string1`* and *`string2`* and returns a value indicating the relationship between the substrings. **`strncmp`** is a case-sensitive version of **`_strnicmp`**. **`wcsncmp`** and **`_mbsncmp`** are case-sensitive versions of **`_wcsnicmp`** and **`_mbsnicmp`**. -**`wcsncmp`** and **`_mbsncmp`** are wide-character and multibyte-character versions of **`strncmp`**. The arguments of **`wcsncmp`** are wide-character strings; those of **`_mbsncmp`** are multibyte-character strings. **`_mbsncmp`** recognizes multibyte-character sequences according to a multibyte code page and returns **`_NLSCMPERROR`** on an error. +**`wcsncmp`** and **`_mbsncmp`** are wide-character and multibyte-character versions of **`strncmp`**. The arguments of **`wcsncmp`** are wide-character strings. The arguments of **`_mbsncmp`** are multibyte-character strings. **`_mbsncmp`** recognizes multibyte-character sequences according to a multibyte code page and returns `_NLSCMPERROR` on an error. -Also, **`_mbsncmp`** and **`_mbsncmp_l`** validate parameters. If *`string1`* or *`string2`* is a null pointer and *`count`* is not equal to 0, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`_mbsncmp`** and **`_mbsncmp_l`** return **`_NLSCMPERROR`** and set **`errno`** to **`EINVAL`**. **`strncmp`** and **`wcsncmp`** do not validate their parameters. These functions behave identically otherwise. +Also, **`_mbsncmp`** and **`_mbsncmp_l`** validate parameters. If *`string1`* or *`string2`* is a null pointer and *`count`* isn't equal to 0, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbsncmp`** and **`_mbsncmp_l`** return `_NLSCMPERROR` and set `errno` to `EINVAL`. **`strncmp`** and **`wcsncmp`** don't validate their parameters. These functions behave identically otherwise. -The comparison behavior of **`_mbsncmp`** and **`_mbsncmp_l`** is affected by the setting of the **`LC_CTYPE`** category setting of the locale. This controls detection of leading and trailing bytes of multibyte characters. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsncmp`** function uses the current locale for this locale-dependent behavior. The **`_mbsncmp_l`** function is identical except that it uses the *locale* parameter instead. For more information, see [Locale](../../c-runtime-library/locale.md). If the locale is a single-byte locale, the behavior of these functions is identical to **`strncmp`**. +The comparison behavior of **`_mbsncmp`** and **`_mbsncmp_l`** is affected by the setting of the `LC_CTYPE` category setting of the locale. This controls detection of leading and trailing bytes of multibyte characters. For more information, see [`setlocale`](setlocale-wsetlocale.md). The **`_mbsncmp`** function uses the current locale for this locale-dependent behavior. The **`_mbsncmp_l`** function is identical except that it uses the *`locale`* parameter instead. For more information, see [Locale](../locale.md). If the locale is a single-byte locale, the behavior of these functions is identical to **`strncmp`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsnccmp`**|**`strncmp`**|**`_mbsncmp`**|**`wcsncmp`**| -|**`_tcsncmp`**|**`strncmp`**|**`_mbsnbcmp`**|**`wcsncmp`**| -|**`_tccmp`**|Maps to macro or inline function|**`_mbsncmp`**|Maps to macro or inline function| -|**not applicable**|**not applicable**|**`_mbsncmp_l`**|**not applicable**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnccmp` | **`strncmp`** | **`_mbsncmp`** | **`wcsncmp`** | +| `_tcsncmp` | **`strncmp`** | **`_mbsnbcmp`** | **`wcsncmp`** | +| `_tccmp` | Maps to macro or inline function | **`_mbsncmp`** | Maps to macro or inline function | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncmp`**|``| -|**`wcsncmp`**|`` or ``| -|**`_mbsncmp`**, **`_mbsncmp_l`**|``| +| Routine | Required header | +|---|---| +| **`strncmp`** | `` | +| **`wcsncmp`** | `` or `` | +| **`_mbsncmp`**, **`_mbsncmp_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -152,14 +151,14 @@ Result: String 1 is equal to string 2 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)
-[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcmp`, `_mbsnbcmp_l`](mbsnbcmp-mbsnbcmp-l.md)\ +[`_mbsnbicmp`, `_mbsnbicmp_l`](mbsnbicmp-mbsnbicmp-l.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md b/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md index 76335ff106c..2c9cdcfed2f 100644 --- a/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md +++ b/docs/c-runtime-library/reference/strncnt-wcsncnt-mbsnbcnt-mbsnbcnt-l-mbsnccnt-mbsnccnt-l.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: _strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l" title: "_strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l" +description: "Learn more about: _strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l" ms.date: "4/2/2020" api_name: ["_mbsnbcnt_l", "_mbsnccnt", "_wcsncnt", "_strncnt", "_mbsnccnt_l", "_mbsnbcnt", "_o__mbsnbcnt", "_o__mbsnbcnt_l", "_o__mbsnccnt", "_o__mbsnccnt_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_mbsnbcnt", "wcsncnt", "_tcsnbcnt", "_mbsnccnt", "_ftcsnbcnt", "mbsnbcnt", "strncnt", "mbsnbcnt_l", "mbsnccnt_l", "mbsnccnt", "_strncnt", "_wcsncnt"] helpviewer_keywords: ["_strncnt function", "_mbsnbcnt function", "_mbsnbcnt_l function", "_mbsnccnt_l function", "mbsnbcnt_l function", "mbsnbcnt function", "tcsnbcnt function", "mbsnccnt_l function", "strncnt function", "_tcsnbcnt function", "mbsnccnt function", "wcsncnt function", "_mbsnccnt function", "_wcsncnt function"] -ms.assetid: 2a022e9e-a307-4acb-a66b-e56e5357f848 --- -# _strncnt, _wcsncnt, _mbsnbcnt, _mbsnbcnt_l, _mbsnccnt, _mbsnccnt_l +# `_strncnt`, `_wcsncnt`, `_mbsnbcnt`, `_mbsnbcnt_l`, `_mbsnccnt`, `_mbsnccnt_l` Returns the number of characters or bytes within a specified count. > [!IMPORTANT] -> **_mbsnbcnt**, **_mbsnbcnt_l**, **_mbsnccnt**, and **_mbsnccnt_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnbcnt`**, **`_mbsnbcnt_l`**, **`_mbsnccnt`**, and **`_mbsnccnt_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -50,63 +49,63 @@ size_t _mbsnccnt_l( ### Parameters -*str*
+*`str`*\ String to be examined. -*count*
-Number of characters or bytes to be examined in *str*. +*`count`*\ +Number of characters or bytes to be examined in *`str`*. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_mbsnbcnt** and **_mbsnbcnt_l** return the number of bytes found in the first *count* of multibyte characters of *str*. **_mbsnccnt** and **_mbsnccnt_l** return the number of characters found in the first *count* of bytes of *str*. If a null character is encountered before the examination of *str* has completed, they return the number of bytes or characters found before the null character. If *str* consists of fewer than *count* characters or bytes, they return the number of characters or bytes in the string. If *count* is less than zero, they return 0. In previous versions, these functions had a return value of type **`int`** rather than **size_t**. +**`_mbsnbcnt`** and **`_mbsnbcnt_l`** return the number of bytes found in the first *`count`* of multibyte characters of *`str`*. **`_mbsnccnt`** and **`_mbsnccnt_l`** return the number of characters found in the first *`count`* of bytes of *`str`*. If a null character is encountered before the examination of *`str`* has completed, they return the number of bytes or characters found before the null character. If *`str`* consists of fewer than *`count`* characters or bytes, they return the number of characters or bytes in the string. If *`count`* is less than zero, they return 0. In previous versions, these functions had a return value of type **`int`** rather than `size_t`. -**_strncnt** returns the number of characters in the first *count* bytes of the single-byte string *str*. **_wcsncnt** returns the number of characters in the first *count* wide characters of the wide-character string *str*. +**`_strncnt`** returns the number of characters in the first *`count`* bytes of the single-byte string *`str`*. **`_wcsncnt`** returns the number of characters in the first *`count`* wide characters of the wide-character string *`str`*. ## Remarks -**_mbsnbcnt** and **_mbsnbcnt_l** count the number of bytes found in the first *count* of multibyte characters of *str*. **_mbsnbcnt** and **_mbsnbcnt_l** replace **mtob** and should be used in place of **mtob**. +**`_mbsnbcnt`** and **`_mbsnbcnt_l`** count the number of bytes found in the first *`count`* of multibyte characters of *`str`*. **`_mbsnbcnt`** and **`_mbsnbcnt_l`** replace `mtob` and should be used in place of `mtob`. -**_mbsnccnt** and **_mbsnccnt_l** count the number of characters found in the first *count* of bytes of *str*. If **_mbsnccnt** and **_mbsnccnt_l** encounter a null character in the second byte of a double-byte character, the first byte is also considered to be null and is not included in the returned count value. **_mbsnccnt** and **_mbsnccnt_l** replace **btom** and should be used in place of **btom**. +**`_mbsnccnt`** and **`_mbsnccnt_l`** count the number of characters found in the first *`count`* of bytes of *`str`*. If **`_mbsnccnt`** and **`_mbsnccnt_l`** encounter a null character in the second byte of a double-byte character, the first byte is also considered to be null and isn't included in the returned count value. **`_mbsnccnt`** and **`_mbsnccnt_l`** replace `btom` and should be used in place of `btom`. -If *str* is a **NULL** pointer or is *count* is 0, these functions invoke the invalid parameter handler as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md), **errno** is set to **EINVAL**, and the function returns 0. +If *`str`* is a `NULL` pointer or is *`count`* is 0, these functions invoke the invalid parameter handler as described in [Parameter validation](../parameter-validation.md), `errno` is set to `EINVAL`, and the function returns 0. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|-------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnbcnt**|**_strncnt**|**_mbsnbcnt**|**_wcsncnt**| -|**_tcsnccnt**|**_strncnt**|**_mbsnbcnt**|n/a| -|**_wcsncnt**|n/a|n/a|**_mbsnbcnt**| -|**_wcsncnt**|n/a|n/a|**_mbsnccnt**| -|n/a|n/a|**_mbsnbcnt_l**|**_mbsnccnt_l**| +| Routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnbcnt` | **`_strncnt`** | **`_mbsnbcnt`** | **`_wcsncnt`** | +| `_tcsnccnt` | **`_strncnt`** | **`_mbsnbcnt`** | n/a | +| **`_wcsncnt`** | n/a | n/a | **`_mbsnbcnt`** | +| **`_wcsncnt`** | n/a | n/a | **`_mbsnccnt`** | +| n/a | n/a | **`_mbsnbcnt_l`** | **`_mbsnccnt_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnbcnt**|\| -|**_mbsnbcnt_l**|\| -|**_mbsnccnt**|\| -|**_mbsnccnt_l**|\| -|**_strncnt**|\| -|**_wcsncnt**|\| +| Routine | Required header | +|---|---| +| **`_mbsnbcnt`** | \ | +| **`_mbsnbcnt_l`** | \ | +| **`_mbsnccnt`** | \ | +| **`_mbsnccnt_l`** | \ | +| **`_strncnt`** | \ | +| **`_wcsncnt`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_mbsnbcnt.c -#include -#include +#include +#include int main( void ) { @@ -129,7 +128,7 @@ The first 10 characters are single-byte. ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbcat, _mbsnbcat_l](mbsnbcat-mbsnbcat-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcat`, `_mbsnbcat_l`](mbsnbcat-mbsnbcat-l.md) diff --git a/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md b/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md index 064cecd0adf..7e9c9b6a523 100644 --- a/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md +++ b/docs/c-runtime-library/reference/strncoll-wcsncoll-mbsncoll-strncoll-l-wcsncoll-l-mbsncoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _w title: "_strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l" ms.date: "4/2/2020" api_name: ["_strncoll", "_mbsncoll_l", "_wcsncoll", "_wcsncoll_l", "_mbsncoll", "_strncoll_l", "_o__mbsncoll", "_o__mbsncoll_l", "_o__strncoll", "_o__strncoll_l", "_o__wcsncoll", "_o__wcsncoll_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["mbsncoll_l", "strncoll", "_wcsncoll", "_tcsnccoll", "_ftcsnccoll", "wcsncoll", "_mbsncoll", "wcsncoll_l", "strncoll_l", "_ftcsncoll", "_strncoll", "_tcsncoll", "mbsncoll"] +f1_keywords: ["STRING/_strncoll", "MBSTRING/_mbsncoll", "CORECRT_WSTRING/_wcsncoll", "TCHAR/_tcsncoll", "TCHAR/_tcsnccoll", "TCHAR/_ftcsncoll", "TCHAR/_ftcsnccoll", "STRING/_strncoll_l", "MBSTRING/_mbsncoll_l", "CORECRT_WSTRING/_wcsncoll_l", "TCHAR/_tcsncoll_l", "_strncoll", "_mbsncoll", "_wcsncoll", "_tcsncoll", "_tcsnccoll", "_ftcsncoll", "_ftcsnccoll", "_strncoll_l", "_mbsncoll_l", "_wcsncoll_l", "_tcsncoll_l", "strncoll", "mbsncoll", "wcsncoll", "tcsncoll", "tcsnccoll", "ftcsncoll", "ftcsnccoll", "strncoll_l", "mbsncoll_l", "wcsncoll_l", "tcsncoll_l"] helpviewer_keywords: ["_strncoll_l function", "code pages, using for string comparisons", "_strncoll function", "_mbsncoll function", "ftcsncoll function", "strncoll function", "_ftcsncoll function", "strncoll_l function", "wcsncoll function", "mbsncoll function", "_tcsncoll function", "_tcsnccoll function", "wcsncoll_l function", "tcsnccoll function", "mbsncoll_l function", "_mbsncoll_l function", "tcsncoll function", "_wcsncoll function", "strings [C++], comparing by code page", "_ftcsnccoll function", "ftcsnccoll function", "_wcsncoll_l function"] ms.assetid: e659a5a4-8afe-4033-8e72-17ffd4bdd8e9 --- -# _strncoll, _wcsncoll, _mbsncoll, _strncoll_l, _wcsncoll_l, _mbsncoll_l +# `_strncoll`, `_wcsncoll`, `_mbsncoll`, `_strncoll_l`, `_wcsncoll_l`, `_mbsncoll_l` Compares strings by using locale-specific information. > [!IMPORTANT] -> **_mbsncoll** and **_mbsncoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsncoll`** and **`_mbsncoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,62 +57,62 @@ int _mbsncoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*count*
+*`count`*\ The number of characters to compare. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns a value that indicates the relationship of the substrings of *string1* and *string2*, as follows. +Each of these functions returns a value that indicates the relationship of the substrings of *`string1`* and *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* is less than *string2*.| -|0|*string1* is identical to *string2*.| -|> 0|*string1* is greater than *string2*.| +| Return value | Relationship of *`string1`* to *`string2`* | +|---|---| +| < 0 | *`string1`* is less than *`string2`*. | +| 0 | *`string1`* is identical to *`string2`*. | +| > 0 | *`string1`* is greater than *`string2`*. | -Each of these functions returns **_NLSCMPERROR**. To use **_NLSCMPERROR**, include either STRING.h or MBSTRING.h. **_wcsncoll** can fail if either *string1* or *string2* contains wide-character codes that are outside the domain of the collating sequence. When an error occurs, **_wcsncoll** may set **errno** to **EINVAL**. To check for an error on a call to **_wcsncoll**, set **errno** to 0 and then check **errno** after you call **_wcsncoll**. +Each of these functions returns `_NLSCMPERROR`. To use `_NLSCMPERROR`, include either STRING.h or MBSTRING.h. **`_wcsncoll`** can fail if either *`string1`* or *`string2`* contains wide-character codes that are outside the domain of the collating sequence. When an error occurs, **`_wcsncoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`_wcsncoll`**, set `errno` to 0, and then check `errno` after the **`_wcsncoll`** call. ## Remarks -Each of these functions performs a case-sensitive comparison of the first *count* characters in *string1* and *string2*, according to the code page that's currently in use. Use these functions only when there is a difference between the character set order and the lexicographic character order in the code page, and when this difference is of interest for the string comparison. The character set order is locale-dependent. The versions of these functions that don't have the **_l** suffix use the current locale, but the versions that have the **_l** suffix use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these functions performs a case-sensitive comparison of the first *`count`* characters in *`string1`* and *`string2`*, according to the code page that's currently in use. Use these functions only when there's a difference between the character set order and the lexicographic character order in the code page, and when this difference matters for the string comparison. The character set order is locale-dependent. The versions of these functions that don't have the `_l` suffix use the current locale, but the versions that have the `_l` suffix use the locale that's passed in. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, or *count* is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, or *`count`* is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnccoll**|**_strncoll**|**_mbsncoll**|**_wcsncoll**| -|**_tcsncoll**|**_strncoll**|[_mbsnbcoll](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)|**_wcsncoll**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnccoll` | **`_strncoll`** | **`_mbsncoll`** | **`_wcsncoll`** | +| `_tcsncoll` | **`_strncoll`** | [`_mbsnbcoll`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md) | **`_wcsncoll`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strncoll**, **_strncoll_l**|\| -|**_wcsncoll**, **_wcsncoll_l**|\ or \| -|**_mbsncoll**, **_mbsncoll_l**|\| +| Routine | Required header | +|---|---| +| **`_strncoll`**, **`_strncoll_l`** | \ | +| **`_wcsncoll`**, **`_wcsncoll_l`** | \ or \ | +| **`_mbsncoll`**, **`_mbsncoll_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md b/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md index 72e600d5ad4..784bbae4d57 100644 --- a/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md +++ b/docs/c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md @@ -1,22 +1,23 @@ --- description: "Learn more about: strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l" -title: "strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l" +title: "strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l, _tcsncpy_s, _tcsncpy_s_l, _tcsnccpy_s, _tcsnccpy_s_l" ms.date: "4/2/2020" -api_name: ["_mbsncpy_s_l", "wcsncpy_s", "_strncpy_s_l", "strncpy_s", "_mbsncpy_s", "_wcsncpy_s_l", "_o__mbsncpy_s", "_o__mbsncpy_s_l", "_o_strncpy_s", "_o_wcsncpy_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_mbsncpy_s_l", "wcsncpy_s", "_strncpy_s_l", "strncpy_s", "_mbsncpy_s", "_wcsncpy_s_l", "_o__mbsncpy_s", "_o__mbsncpy_s_l", "_o_strncpy_s", "_o_wcsncpy_s", "_tcsnccpy_s", "_tcsnccpy_s_l", "_tcsncpy_s", "_tcsncpy_s_l"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tcsncpy_s", "_wcsncpy_s_l", "strncpy_s", "_strncpy_s_l", "wcsncpy_s", "_tcsncpy_s_l"] -helpviewer_keywords: ["_wcsncpy_s_l function", "_mbsnbcpy_s function", "_tcsncpy_s_l function", "mbsncpy_s function", "strncpy_s_l function", "_strncpy_s_l function", "strncpy_s function", "mbsncpy_s_l function", "wcsncpy_s function", "copying strings", "strings [C++], copying", "_mbsnbcpy_s_l function", "_tcsncpy_s function", "wcsncpy_s_l function"] -ms.assetid: a971c800-94d1-4d88-92f3-a2fe236a4546 +f1_keywords: ["_tcsncpy_s", "_wcsncpy_s_l", "strncpy_s", "_strncpy_s_l", "wcsncpy_s", "_tcsncpy_s_l", "_tcsnccpy_s", "_tcsnccpy_s_l"] +helpviewer_keywords: ["_wcsncpy_s_l function", "_mbsnbcpy_s function", "_tcsncpy_s_l function", "mbsncpy_s function", "strncpy_s_l function", "_strncpy_s_l function", "strncpy_s function", "mbsncpy_s_l function", "wcsncpy_s function", "_tcsnccpy_s function", "copying strings", "strings [C++], copying", "_mbsnbcpy_s_l function", "_tcsncpy_s function", "wcsncpy_s_l function", "_tcsnccpy_s_l function"] --- -# `strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l` +# `strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`, `_tcsncpy_s`, `_tcsncpy_s_l`, `_tcsnccpy_s`, `_tcsnccpy_s_l` -Copies characters of one string to another. These versions of [`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copies characters of one string to another. These versions of [`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbsncpy_s`** and **`_mbsncpy_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +For `_tcsnccpy_s`, `_tcsnccpy_s_l`, `_tcsnccpy_s`, and `_tcsnccpy_s_l` see [Generic-text function mappings](#generic-text-function-mappings). + ## Syntax ```C @@ -102,39 +103,39 @@ errno_t _mbsncpy_s_l( ### Parameters -*`strDest`*
+*`strDest`*\ Destination string. -*`numberOfElements`*
+*`numberOfElements`*\ The size of the destination string, in characters. -*`strSource`*
+*`strSource`*\ Source string. -*`count`*
-Number of characters to be copied, or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +Number of characters to be copied, or [`_TRUNCATE`](../truncate.md). -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Zero if successful, **`STRUNCATE`** if truncation occurred, otherwise an error code. +Zero if successful, `STRUNCATE` if truncation occurred, otherwise an error code. -### Error Conditions +### Error conditions -|*`strDest`*|*`numberOfElements`*|*`strSource`*|Return value|Contents of *`strDest`*| -|---------------|------------------------|-----------------|------------------|---------------------------| -|**`NULL`**|any|any|**`EINVAL`**|not modified| -|any|any|**`NULL`**|**`EINVAL`**|*`strDest[0]`* set to 0| -|any|0|any|**`EINVAL`**|not modified| -|not **`NULL`**|too small|any|**`ERANGE`**|*`strDest[0]`* set to 0| +| *`strDest`* | *`numberOfElements`* | *`strSource`* | Return value | Contents of *`strDest`* | +|---|---|---|---|---| +| `NULL` | any | any | `EINVAL` | not modified | +| any | any | `NULL` | `EINVAL` | *`strDest[0]`* set to 0 | +| any | 0 | any | `EINVAL` | not modified | +| not `NULL` | too small | any | `ERANGE` | *`strDest[0]`* set to 0 | ## Remarks -These functions try to copy the first *`D`* characters of *`strSource`* to *`strDest`*, where *`D`* is the lesser of *`count`* and the length of *`strSource`*. If those *`D`* characters will fit within *`strDest`* (whose size is given as *`numberOfElements`*) and still leave room for a null terminator, then those characters are copied and a terminating null is appended; otherwise, *`strDest[0]`* is set to the null character and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +These functions try to copy the first *`D`* characters of *`strSource`* to *`strDest`*, where *`D`* is the lesser of *`count`* and the length of *`strSource`*. If those *`D`* characters will fit within *`strDest`* (whose size is given as *`numberOfElements`*) and still leave room for a null terminator, then those characters are copied and a terminating null is appended; otherwise, *`strDest[0]`* is set to the null character and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -There is an exception to the above paragraph. If *`count`* is **`_TRUNCATE`**, then as much of *`strSource`* as will fit into *`strDest`* is copied while still leaving room for the terminating null which is always appended. +There's an exception to the above paragraph. If *`count`* is `_TRUNCATE`, then as much of *`strSource`* as will fit into *`strDest`* is copied while still leaving room for the terminating null, which is always appended. For example, @@ -143,50 +144,54 @@ char dst[5]; strncpy_s(dst, 5, "a long string", 5); ``` -means that we are asking **`strncpy_s`** to copy five characters into a buffer five bytes long; this would leave no space for the null terminator, hence **`strncpy_s`** zeroes out the string and calls the invalid parameter handler. +means that **`strncpy_s`** copies five characters into a 5-byte buffer. This copy would leave no space for the null terminator, so **`strncpy_s`** zeroes out the string, and calls the invalid parameter handler. -If truncation behavior is needed, use **`_TRUNCATE`** or (*`size`* - 1): +If truncation behavior is needed, use `_TRUNCATE` or (*`size`* - 1): ```C strncpy_s(dst, 5, "a long string", _TRUNCATE); strncpy_s(dst, 5, "a long string", 4); ``` -Note that unlike **`strncpy`**, if *`count`* is greater than the length of *`strSource`*, the destination string is NOT padded with null characters up to length *`count`*. +Unlike **`strncpy`**, if *`count`* is greater than the length of *`strSource`*, the destination string is NOT padded with null characters up to length *`count`*. The behavior of **`strncpy_s`** is undefined if the source and destination strings overlap. -If *`strDest`* or *`strSource`* is **`NULL`**, or *`numberOfElements`* is 0, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns **`EINVAL`** and sets **`errno`** to **`EINVAL`**. +If *`strDest`* or *`strSource`* is `NULL`, or *`numberOfElements`* is 0, the invalid parameter handler is invoked. If execution is allowed to continue, the function returns `EINVAL` and sets `errno` to `EINVAL`. **`wcsncpy_s`** and **`_mbsncpy_s`** are wide-character and multibyte-character versions of **`strncpy_s`**. The arguments and return value of **`wcsncpy_s`** and **`mbsncpy_s`** do vary accordingly. These six functions behave identically otherwise. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale; see [`setlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). + +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsncpy_s`**|**`strncpy_s`**|**`_mbsnbcpy_s`**|**`wcsncpy_s`**| -|**`_tcsncpy_s_l`**|**`_strncpy_s_l`**|**`_mbsnbcpy_s_l`**|**`_wcsncpy_s_l`**| +| `tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncpy_s` | **`strncpy_s`** | **`_mbsnbcpy_s`** | **`wcsncpy_s`** | +| `_tcsncpy_s_l` | **`_strncpy_s_l`** | **`_mbsnbcpy_s_l`** | **`_wcsncpy_s_l`** | +| `_tcsnccpy_s` | **`strncpy_s`** | **`_mbsncpy_s`** | **`_wcsncpy_s`** | +| `_tcsnccpy_s_l` | **`_strncpy_s_l`** | **`_mbsncpy_s_l`** | **`_wcsncpy_s_l`** | > [!NOTE] -> **`_strncpy_s_l`**, **`_wcsncpy_s_l`** and **`_mbsncpy_s_l`** have no locale dependence and are provided just for **`_tcsncpy_s_l`** and are not intended to be called directly. +> **`_strncpy_s_l`**, **`_wcsncpy_s_l`** and **`_mbsncpy_s_l`** have no locale dependence. They're provided just for `_tcsncpy_s_l` and aren't intended to be called directly. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncpy_s`**, **`_strncpy_s_l`**|``| -|**`wcsncpy_s`**, **`_wcsncpy_s_l`**|`` or ``| -|**`_mbsncpy_s`**, **`_mbsncpy_s_l`**|``| +| Routine | Required header | +|---|---| +| **`strncpy_s`**, **`_strncpy_s_l`** | `` | +| **`wcsncpy_s`**, **`_wcsncpy_s_l`** | `` or `` | +| **`_mbsncpy_s`**, **`_mbsncpy_s_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Copy chars to a buffer @@ -361,16 +366,16 @@ After strncpy_s (with null-termination): ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)
-[`strcat_s`, `wcscat_s`, `_mbscat_s`](strcat-s-wcscat-s-mbscat-s.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)
-[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)\ +[`strcat_s`, `wcscat_s`, `_mbscat_s`](strcat-s-wcscat-s-mbscat-s.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)\ +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md b/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md index 9fc144bc708..5d7b9d4a72c 100644 --- a/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md +++ b/docs/c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsnc title: "strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l" ms.date: "4/2/2020" api_name: ["strncpy", "_strncpy_l", "_mbsncpy", "wcsncpy", "_mbsncpy_l", "_wcsncpy_l", "_o__mbsncpy", "_o__mbsncpy_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fstrncpy", "strncpy", "_ftcsncpy", "_tcsnccpy_l", "_tcsnccpy", "_mbsncpy", "wcsncpy", "_tcsncpy", "_strncpy_l", "_mbsncpy_l", "_wcsncpy_l"] @@ -96,58 +96,58 @@ unsigned char *_mbsncpy_l( ### Parameters -*`strDest`*
+*`strDest`*\ Destination string. -*`strSource`*
+*`strSource`*\ Source string. -*`count`*
+*`count`*\ Number of characters to be copied. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns *`strDest`*. No return value is reserved to indicate an error. ## Remarks -The **`strncpy`** function copies the initial *`count`* characters of *`strSource`* to *`strDest`* and returns *`strDest`*. If *`count`* is less than or equal to the length of *`strSource`*, a null character is not appended automatically to the copied string. If *`count`* is greater than the length of *`strSource`*, the destination string is padded with null characters up to length *`count`*. The behavior of **`strncpy`** is undefined if the source and destination strings overlap. +The **`strncpy`** function copies the initial *`count`* characters of *`strSource`* to *`strDest`* and returns *`strDest`*. If *`count`* is less than or equal to the length of *`strSource`*, a null character isn't appended automatically to the copied string. If *`count`* is greater than the length of *`strSource`*, the destination string is padded with null characters up to length *`count`*. The behavior of **`strncpy`** is undefined if the source and destination strings overlap. > [!IMPORTANT] -> **`strncpy`** does not check for sufficient space in *`strDest`*; this makes it a potential cause of buffer overruns. The *`count`* argument limits the number of characters copied; it is not a limit on the size of *`strDest`*. See the following example. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> **`strncpy`** does not check for sufficient space in *`strDest`*; this makes it a potential cause of buffer overruns. The *`count`* argument limits the number of characters copied; it is not a limit on the size of *`strDest`*. See the following example. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -If *`strDest`* or *`strSource`* is a **`NULL`** pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +If *`strDest`* or *`strSource`* is a `NULL` pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. **`wcsncpy`** and **`_mbsncpy`** are wide-character and multibyte-character versions of **`strncpy`**. The arguments and return value of **`wcsncpy`** and **`_mbsncpy`** vary accordingly. These six functions behave identically otherwise. -The versions of these functions with the **`_l`** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions with the **`_l`** suffix are identical except that they use the locale passed in instead of the current locale for their locale-dependent behavior. For more information, see [Locale](../locale.md). -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsncpy`**|**`strncpy`**|**`_mbsnbcpy`**|**`wcsncpy`**| -|**`_tcsncpy_l`**|**`_strncpy_l`**|**`_mbsnbcpy_l`**|**`_wcsncpy_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncpy` | **`strncpy`** | **`_mbsnbcpy`** | **`wcsncpy`** | +| `_tcsncpy_l` | **`_strncpy_l`** | **`_mbsnbcpy_l`** | **`_wcsncpy_l`** | > [!NOTE] > **`_strncpy_l`** and **`_wcsncpy_l`** have no locale dependence; they are provided just for **`_tcsncpy_l`** and are not intended to be called directly. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strncpy`**|``| -|**`wcsncpy`**|`` or ``| -|**`_mbsncpy`**, **`_mbsncpy_l`**|``| +| Routine | Required header | +|---|---| +| **`strncpy`** | `` | +| **`wcsncpy`** | `` or `` | +| **`_mbsncpy`**, **`_mbsncpy_l`** | `` | -For additional platform compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more platform compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -220,18 +220,18 @@ The layout of automatic variables and the level of error detection and code prot ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)
-[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbcpy`, `_mbsnbcpy_l`](mbsnbcpy-mbsnbcpy-l.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](strcpy-s-wcscpy-s-mbscpy-s.md) diff --git a/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md b/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md index e43f9c5fe09..dfb9505274f 100644 --- a/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md +++ b/docs/c-runtime-library/reference/strnextc-wcsnextc-mbsnextc-mbsnextc-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l" title: "_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l" ms.date: "4/2/2020" api_name: ["_strnextc", "_mbsnextc_l", "_mbsnextc", "_wcsnextc", "_o__mbsnextc", "_o__mbsnextc_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strnextc", "tcsnextc", "_mbsnextc_l", "_mbsnextc", "mbsnextc_l", "ftcsnextc", "mbsnextc", "_tcsnextc", "_wcsnextc", "_ftcsnextc", "_strnextc", "wcsnextc"] helpviewer_keywords: ["_mbsnextc function", "_tcsnextc function", "_wcsnextc function", "tcsnextc function", "strnextc function", "mbsnextc function", "_strnextc function", "_mbsnextc_l function", "mbsnextc_l function", "wcsnextc function"] ms.assetid: e3086173-9eb5-4540-a23a-5d866bd05340 --- -# _strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l +# `_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l` Finds the next character in a string. > [!IMPORTANT] -> **_mbsnextc** and **_mbsnextc_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnextc`** and **`_mbsnextc_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -37,52 +37,52 @@ unsigned int _mbsnextc_l( ### Parameters -*str*
+*`str`*\ Source string. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these functions returns the integer value of the next character in *str*. +Each of these functions returns the integer value of the next character in *`str`*. ## Remarks -The **_mbsnextc** function returns the integer value of the next multibyte character in *str*, without advancing the string pointer. **_mbsnextc** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) currently in use. +The **`_mbsnextc`** function returns the integer value of the next multibyte character in *`str`*, without advancing the string pointer. **`_mbsnextc`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) currently in use. -If *str* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns 0. +If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns 0. -**Security Note** This API incurs a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +**Security Note** This API incurs a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsnextc**|**_strnextc**|**_mbsnextc**|**_wcsnextc**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnextc` | **`_strnextc`** | **`_mbsnextc`** | **`_wcsnextc`** | -**_strnextc** and **_wcsnextc** are single-byte-character string and wide-character string versions of **_mbsnextc**. **_wcsnextc** returns the integer value of the next wide character in *str*; **_strnextc** returns the integer value of the next single-byte character in *str*. **_strnextc** and **_wcsnextc** are provided only for this mapping and should not be used otherwise. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +**`_strnextc`** and **`_wcsnextc`** are single-byte-character string and wide-character string versions of **`_mbsnextc`**. **`_wcsnextc`** returns the integer value of the next wide character in *`str`*; **`_strnextc`** returns the integer value of the next single-byte character in *`str`*. **`_strnextc`** and **`_wcsnextc`** are provided only for this mapping and shouldn't be used otherwise. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -**_mbsnextc_l** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbsnextc_l`** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsnextc**|\| -|**_mbsnextc_l**|\| -|**_strnextc**|\| -|**_wcsnextc**|\| +| Routine | Required header | +|---|---| +| **`_mbsnextc`** | \ | +| **`_mbsnextc_l`** | \ | +| **`_strnextc`** | \ | +| **`_wcsnextc`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strdec, _wcsdec, _mbsdec, _mbsdec_l](strdec-wcsdec-mbsdec-mbsdec-l.md)
-[_strinc, _wcsinc, _mbsinc, _mbsinc_l](strinc-wcsinc-mbsinc-mbsinc-l.md)
-[_strninc, _wcsninc, _mbsninc, _mbsninc_l](strninc-wcsninc-mbsninc-mbsninc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](strdec-wcsdec-mbsdec-mbsdec-l.md)\ +[`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](strinc-wcsinc-mbsinc-mbsinc-l.md)\ +[`_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l`](strninc-wcsninc-mbsninc-mbsninc-l.md) diff --git a/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md b/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md index c8eb33cb846..8b95d93fbaa 100644 --- a/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md +++ b/docs/c-runtime-library/reference/strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _w title: "_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l" ms.date: "4/2/2020" api_name: ["_wcsnicmp", "_strnicmp_l", "_wcsnicmp_l", "_strnicmp", "_mbsnicmp", "_mbsnicmp_l", "_o__mbsnicmp", "_o__mbsnicmp_l", "_o__strnicmp", "_o__strnicmp_l", "_o__wcsnicmp", "_o__wcsnicmp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcsnicmp_l", "_strnicmp", "_ftcsnicmp", "mbsnicmp_l", "_ftcsncicmp", "mbsnicmp", "_tcsncicmp", "_mbsnicmp", "_tcsnicmp", "strnicmp_l", "_wcsnicmp", "_wcsnicmp_l", "CORECRT_WSTRING/_wcsnicmp", "CORECRT_WSTRING/_wcsnicmp_l", "string/_strnicmp", "string/_strnicmp_l"] helpviewer_keywords: ["tcsnicmp function", "_tcsncicmp function", "_mbsnicmp_l function", "mbsnicmp_l function", "wcsnicmp_l function", "wcsnicmp function", "string comparison [C++], lowercase", "ftcsnicmp function", "strnicmp_l function", "strncmp function", "_strnicmp function", "strings [C++], comparing characters of", "_wcsnicmp_l function", "tcsncicmp function", "string comparison [C++], strncmp function", "_mbsnicmp function", "ftcsncicmp function", "_tcsnicmp function", "_ftcsncicmp function", "_strnicmp_l function", "_ftcsnicmp function", "characters [C++], comparing", "mbsnicmp function", "_wcsnicmp function"] ms.assetid: df6e5037-4039-4c85-a0a6-21d4ef513966 --- -# _strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l +# `_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l` Compares the specified number of characters of two strings without regard to case. > [!IMPORTANT] -> **_mbsnicmp** and **_mbsnicmp_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnicmp`** and **`_mbsnicmp_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,70 +57,70 @@ int _mbsnicmp_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare. -*count*
+*`count`*\ Number of characters to compare. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Indicates the relationship between the substrings, as follows. -|Return value|Description| -|------------------|-----------------| -|< 0|*string1* substring is less than *string2* substring.| -|0|*string1* substring is identical to *string2* substring.| -|> 0|*string1* substring is greater than *string2* substring.| +| Return value | Description | +|---|---| +| < 0 | *`string1`* substring is less than *`string2`* substring. | +| 0 | *`string1`* substring is identical to *`string2`* substring. | +| > 0 | *`string1`* substring is greater than *`string2`* substring. | -On a parameter validation error, these functions return **_NLSCMPERROR**, which is defined in \ and \. +On a parameter validation error, these functions return `_NLSCMPERROR`, which is defined in \ and \. ## Remarks -The **_strnicmp** function ordinally compares, at most, the first *count* characters of *string1* and *string2*. The comparison is performed without regard to case by converting each character to lowercase. **_strnicmp** is a case-insensitive version of **strncmp**. The comparison ends if a terminating null character is reached in either string before *count* characters are compared. If the strings are equal when a terminating null character is reached in either string before *count* characters are compared, the shorter string is lesser. +The **`_strnicmp`** function compares, at most, the first *`count`* characters of *`string1`* and *`string2`*. The comparison is performed without regard to case by converting each character to lowercase. **`_strnicmp`** is a case-insensitive version of **`strncmp`**. The comparison ends if a terminating null character is reached in either string before *`count`* characters are compared. If the strings are equal when a terminating null character is reached in either string before *`count`* characters are compared, the shorter string is lesser. -The characters from 91 to 96 in the ASCII table ('[', '\\', ']', '^', '_', and '\`') evaluate as less than any alphabetic character. This ordering is identical to that of **stricmp**. +The characters from 91 to 96 in the ASCII table ('[', '\\', ']', '^', '_', and '\`') evaluate as less than any alphabetic character. This ordering is identical to that of **`stricmp`**. -**_wcsnicmp** and **_mbsnicmp** are wide-character and multibyte-character versions of **_strnicmp**. The arguments of **_wcsnicmp** are wide-character strings; those of **_mbsnicmp** are multibyte-character strings. **_mbsnicmp** recognizes multibyte-character sequences according to the current multibyte code page and returns **_NLSCMPERROR** on an error. For more information, see [Code Pages](../../c-runtime-library/code-pages.md). These three functions behave identically otherwise. These functions are affected by the locale setting—the versions that don't have the **_l** suffix use the current locale for their locale-dependent behavior; the versions that do have the **_l** suffix instead use the *locale* that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_wcsnicmp`** and **`_mbsnicmp`** are wide-character and multibyte-character versions of **`_strnicmp`**. The arguments of **`_wcsnicmp`** are wide-character strings. The arguments of **`_mbsnicmp`** are multibyte-character strings. **`_mbsnicmp`** recognizes multibyte-character sequences according to the current multibyte code page and returns `_NLSCMPERROR` on an error. For more information, see [Code pages](../code-pages.md). These three functions behave identically otherwise. These functions are affected by the locale setting—the versions that don't have the `_l` suffix use the current locale for their locale-dependent behavior; the versions that do have the `_l` suffix instead use the *`locale`* that's passed in. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsncicmp**|**_strnicmp**|**_mbsnicmp**|**_wcsnicmp**| -|**_tcsnicmp**|**_strnicmp**|**_mbsnbicmp**|**_wcsnicmp**| -|**_tcsncicmp_l**|**_strnicmp_l**|**_mbsnicmp_l**|**_wcsnicmp_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncicmp` | **`_strnicmp`** | **`_mbsnicmp`** | **`_wcsnicmp`** | +| `_tcsnicmp` | **`_strnicmp`** | **`_mbsnbicmp`** | **`_wcsnicmp`** | +| `_tcsncicmp_l` | **`_strnicmp_l`** | **`_mbsnicmp_l`** | **`_wcsnicmp_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnicmp**, **_strnicmp_l**|\| -|**_wcsnicmp**, **_wcsnicmp_l**|\ or \| -|**_mbsnicmp**, **_mbsnicmp_l**|\| +| Routine | Required header | +|---|---| +| **`_strnicmp`**, **`_strnicmp_l`** | \ | +| **`_wcsnicmp`**, **`_wcsnicmp_l`** | \ or \ | +| **`_mbsnicmp`**, **`_mbsnicmp_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strncmp](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md). +See the example for [`strncmp`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md b/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md index a6cb2a2b073..3a9aea37f4b 100644 --- a/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md +++ b/docs/c-runtime-library/reference/strnicmp-wcsnicmp.md @@ -10,8 +10,8 @@ f1_keywords: ["wcsnicmp", "strnicmp"] helpviewer_keywords: ["strnicmp function", "wcsnicmp function"] ms.assetid: 01324ee4-0bd9-43e9-b2a3-53d180270a64 --- -# strnicmp, wcsnicmp +# `strnicmp`, `wcsnicmp` -The Microsoft-specific function names `strnicmp` and `wcsnicmp` are deprecated aliases for the [_strnicmp and _wcsnicmp](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strnicmp` and `wcsnicmp` are deprecated aliases for the [`_strnicmp` and `_wcsnicmp`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strnicmp and _wcsnicmp](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strnicmp` and `_wcsnicmp`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md b/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md index a7ed2d83229..b529a0df1bb 100644 --- a/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md +++ b/docs/c-runtime-library/reference/strnicoll-wcsnicoll-mbsnicoll-strnicoll-l-wcsnicoll-l-mbsnicoll-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l title: "_strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l" ms.date: "4/2/2020" api_name: ["_mbsnicoll_l", "_mbsnicoll", "_wcsnicoll_l", "_strnicoll", "_strnicoll_l", "_wcsnicoll", "_o__mbsnicoll", "_o__mbsnicoll_l", "_o__strnicoll", "_o__strnicoll_l", "_o__wcsnicoll", "_o__wcsnicoll_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcshicoll_l", "_ftcsncicoll", "strnicoll_l", "_wcsnicoll", "mbsnicoll_l", "_strnicoll", "mbsnicoll", "_ftcsnicoll", "wcsnicoll", "_tcsnicoll", "_mbsnicoll", "strinicoll", "_tcsncicoll"] +f1_keywords: ["STRING/_strnicoll", "MBSTRING/_mbsnicoll", "CORECRT_WSTRING/_wcsnicoll", "TCHAR/_tcsnicoll", "TCHAR/_tcsncicoll", "TCHAR/_ftcsncicoll", "TCHAR/_ftcsnicoll", "STRING/_strnicoll_l", "MBSTRING/_mbsnicoll_l", "CORECRT_WSTRING/_wcsnicoll_l", "TCHAR/_tcsnicoll_l", "_strnicoll", "_mbsnicoll", "_wcsnicoll", "_tcsnicoll", "_tcsncicoll", "_ftcsncicoll", "_ftcsnicoll", "_strnicoll_l", "_mbsnicoll_l", "_wcsnicoll_l", "_tcsnicoll_l", "strnicoll", "mbsnicoll", "wcsnicoll", "tcsnicoll", "tcsncicoll", "ftcsncicoll", "ftcsnicoll", "strnicoll_l", "mbsnicoll_l", "wcsnicoll_l", "tcsnicoll_l"] helpviewer_keywords: ["code pages, using for string comparisons", "ftcsncicoll function", "mbsnicoll_l function", "_ftcsnicoll function", "mbsnicoll function", "_tcsnicoll function", "_wcsnicoll_l function", "_mbsnicoll function", "tcsncicoll function", "strnicoll function", "_ftcsncicoll function", "wcsnicoll_l function", "_mbsnicoll_l function", "_tcsncicoll function", "strnicoll_l function", "wcsnicoll function", "_strnicoll_l function", "_wcsnicoll function", "ftcsnicoll function", "strings [C++], comparing by code page", "tcsnicoll function", "_strnicoll function"] ms.assetid: abf0c569-725b-428d-9ff2-924f430104b4 --- -# _strnicoll, _wcsnicoll, _mbsnicoll, _strnicoll_l, _wcsnicoll_l, _mbsnicoll_l +# `_strnicoll`, `_wcsnicoll`, `_mbsnicoll`, `_strnicoll_l`, `_wcsnicoll_l`, `_mbsnicoll_l` Compares strings by using locale-specific information. > [!IMPORTANT] -> **_mbsnicoll** and **_mbsnicoll_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnicoll`** and **`_mbsnicoll_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,63 +57,63 @@ int _mbsnicoll_l( ### Parameters -*string1*, *string2*
+*`string1`*, *`string2`*\ Null-terminated strings to compare -*count*
+*`count`*\ Number of characters to compare -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Each of these functions returns a value indicating the relationship of the substrings of *string1* and *string2*, as follows. +Each of these functions returns a value indicating the relationship of the substrings of *`string1`* and *`string2`*, as follows. -|Return value|Relationship of string1 to string2| -|------------------|----------------------------------------| -|< 0|*string1* less than *string2*| -|0|*string1* identical to *string2*| -|> 0|*string1* greater than *string2*| +| Return value | Relationship of string1 to string2 | +|---|---| +| < 0 | *`string1`* less than *`string2`* | +| 0 | *`string1`* identical to *`string2`* | +| > 0 | *`string1`* greater than *`string2`* | -Each of these functions returns **_NLSCMPERROR**. To use **_NLSCMPERROR**, include either STRING.H or MBSTRING.H. **_wcsnicoll** can fail if either *string1* or *string2* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **_wcsnicoll** may set **errno** to **EINVAL**. To check for an error on a call to **_wcsnicoll**, set **errno** to 0 and then check **errno** after calling **_wcsnicoll**. +Each of these functions returns `_NLSCMPERROR`. To use `_NLSCMPERROR`, include either STRING.H or MBSTRING.H. **`_wcsnicoll`** can fail if either *`string1`* or *`string2`* contains wide-character codes outside the domain of the collating sequence. When an error occurs, **`_wcsnicoll`** may set `errno` to `EINVAL`. To check for an error on a call to **`_wcsnicoll`**, set `errno` to 0 and then check `errno` after calling **`_wcsnicoll`**. ## Remarks -Each of these functions performs a case-insensitive comparison of the first *count* characters in *string1* and *string2* according to the code page. These functions should be used only when there is a difference between the character set order and the lexicographic character order in the code page and this difference is of interest for the string comparison. The versions of these functions without the **_l** suffix use the current locale and code page. The versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these functions performs a case-insensitive comparison of the first *`count`* characters in *`string1`* and *`string2`* according to the code page. These functions should be used only when there's a difference between the character set order and the lexicographic character order in the code page and this difference is of interest for the string comparison. The versions of these functions without the `_l` suffix use the current locale and code page. The versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -All of these functions validate their parameters. If either *string1* or *string2* is a null pointer, or if count is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return **_NLSCMPERROR** and set **errno** to **EINVAL**. +All of these functions validate their parameters. If either *`string1`* or *`string2`* is a null pointer, or if count is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return `_NLSCMPERROR` and set `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsncicoll**|**_strnicoll**|**_mbsnbicoll**|**_wcsnicoll**| -|**_tcsnicoll**|**_strnicoll**|[_mbsnbicoll](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)|**_wcsnicoll**| -|**_tcsnicoll_l**|**_strnicoll_l**|**_mbsnbicoll_l**|**_wcsnicoll_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsncicoll` | **`_strnicoll`** | **`_mbsnbicoll`** | **`_wcsnicoll`** | +| `_tcsnicoll` | **`_strnicoll`** | [`_mbsnbicoll`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md) | **`_wcsnicoll`** | +| `_tcsnicoll_l` | **`_strnicoll_l`** | **`_mbsnbicoll_l`** | **`_wcsnicoll_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnicoll**, **_strnicoll_l**|\| -|**_wcsnicoll**, **_wcsnicoll_l**|\ or \| -|**_mbsnicoll**, **_mbsnicoll_l**|\| +| Routine | Required header | +|---|---| +| **`_strnicoll`**, **`_strnicoll_l`** | \ | +| **`_wcsnicoll`**, **`_wcsnicoll_l`** | \ or \ | +| **`_mbsnicoll`**, **`_mbsnicoll_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[localeconv](localeconv.md)
-[_mbsnbcoll, _mbsnbcoll_l, _mbsnbicoll, _mbsnbicoll_l](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[_stricmp, _wcsicmp, _mbsicmp, _stricmp_l, _wcsicmp_l, _mbsicmp_l](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`localeconv`](localeconv.md)\ +[`_mbsnbcoll`, `_mbsnbcoll_l`, `_mbsnbicoll`, `_mbsnbicoll_l`](mbsnbcoll-mbsnbcoll-l-mbsnbicoll-mbsnbicoll-l.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`_stricmp`, `_wcsicmp`, `_mbsicmp`, `_stricmp_l`, `_wcsicmp_l`, `_mbsicmp_l`](stricmp-wcsicmp-mbsicmp-stricmp-l-wcsicmp-l-mbsicmp-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l`](strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md) diff --git a/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md b/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md index 653c6b743f4..b8d17fe1ca4 100644 --- a/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md +++ b/docs/c-runtime-library/reference/strninc-wcsninc-mbsninc-mbsninc-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strninc, _wcsninc, _mbsninc, _mbsninc_l" title: "_strninc, _wcsninc, _mbsninc, _mbsninc_l" ms.date: "4/2/2020" api_name: ["_mbsninc", "_mbsninc_l", "_wcsninc", "_strninc", "_o__mbsninc", "_o__mbsninc_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["strninc", "wcsninc", "mbsninc_l", "_strninc", "_tcsninc", "mbsninc", "_mbsninc_l", "_ftcsninc", "_wcsninc", "_mbsninc"] helpviewer_keywords: ["_mbsninc_l function", "mbsninc function", "_strninc function", "tcsninc function", "wcsninc function", "_mbsninc function", "strninc function", "_wcsninc function", "mbsninc_l function", "_tcsninc function"] ms.assetid: 6caace64-f9e4-48c0-afa8-ea51824ad723 --- -# _strninc, _wcsninc, _mbsninc, _mbsninc_l +# `_strninc`, `_wcsninc`, `_mbsninc`, `_mbsninc_l` Advances a string pointer by **n** characters. > [!IMPORTANT] -> **_mbsninc** and **_mbsninc_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsninc`** and **`_mbsninc_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,51 +41,51 @@ unsigned char *_mbsninc( ### Parameters -*str*
+*`str`*\ Source string. -*count*
+*`count`*\ Number of characters to increment a string pointer. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines returns a pointer to *str* after *str* has been incremented by *count* characters or **NULL** if the supplied pointer is **NULL**. If *count* is greater than or equal to the number of characters in *str*, the result is undefined. +Each of these routines returns a pointer to *`str`* after *`str`* has been incremented by *`count`* characters or `NULL` if the supplied pointer is `NULL`. If *`count`* is greater than or equal to the number of characters in *`str`*, the result is undefined. ## Remarks -The **_mbsninc** function increments *str* by *count* multibyte characters. **_mbsninc** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) currently in use. +The **`_mbsninc`** function increments *`str`* by *`count`* multibyte characters. **`_mbsninc`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) currently in use. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsninc**|**_strninc**|**_mbsninc**|**_wcsninc**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsninc` | **`_strninc`** | **`_mbsninc`** | **`_wcsninc`** | -**_strninc** and **_wcsninc** are single-byte-character string and wide-character string versions of **_mbsninc**. **_wcsninc** and **_strninc** are provided only for this mapping and should not be used otherwise. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +**`_strninc`** and **`_wcsninc`** are single-byte-character string and wide-character string versions of **`_mbsninc`**. **`_wcsninc`** and **`_strninc`** are provided only for this mapping and shouldn't be used otherwise. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -**_mbsninc_l** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbsninc_l`** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsninc**|\| -|**_mbsninc_l**|\| -|**_strninc**|\| -|**_wcsninc**|\| +| Routine | Required header | +|---|---| +| **`_mbsninc`** | \ | +| **`_mbsninc_l`** | \ | +| **`_strninc`** | \ | +| **`_wcsninc`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strdec, _wcsdec, _mbsdec, _mbsdec_l](strdec-wcsdec-mbsdec-mbsdec-l.md)
-[_strinc, _wcsinc, _mbsinc, _mbsinc_l](strinc-wcsinc-mbsinc-mbsinc-l.md)
-[_strnextc, _wcsnextc, _mbsnextc, _mbsnextc_l](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strdec`, `_wcsdec`, `_mbsdec`, `_mbsdec_l`](strdec-wcsdec-mbsdec-mbsdec-l.md)\ +[`_strinc`, `_wcsinc`, `_mbsinc`, `_mbsinc_l`](strinc-wcsinc-mbsinc-mbsinc-l.md)\ +[`_strnextc`, `_wcsnextc`, `_mbsnextc`, `_mbsnextc_l`](strnextc-wcsnextc-mbsnextc-mbsnextc-l.md) diff --git a/docs/c-runtime-library/reference/strnlen-strnlen-s.md b/docs/c-runtime-library/reference/strnlen-strnlen-s.md index d7a1217fa95..ba5972caaec 100644 --- a/docs/c-runtime-library/reference/strnlen-strnlen-s.md +++ b/docs/c-runtime-library/reference/strnlen-strnlen-s.md @@ -3,7 +3,7 @@ description: "Learn more about: strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen title: "strnlen, strnlen_s, wcsnlen, wcsnlen_s, _mbsnlen, _mbsnlen_l, _mbstrnlen, _mbstrnlen_l" ms.date: "4/2/2020" api_name: ["wcsnlen", "strnlen_s", "_mbstrnlen", "_mbsnlen_l", "_mbstrnlen_l", "strnlen", "wcsnlen_s", "_mbsnlen", "_o__mbsnlen", "_o__mbsnlen_l", "_o__mbstrnlen", "_o__mbstrnlen_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcsnlen", "strnlen_s", "_mbsnlen", "_mbsnlen_l", "_tcsnlen", "_tcscnlen", "_mbstrnlen_l", "wcsnlen_s", "_mbstrnlen", "strnlen", "_tcscnlen_l"] @@ -12,10 +12,10 @@ ms.assetid: cc05ce1c-72ea-4ae4-a7e7-4464e56e5f80 --- # `strnlen`, `strnlen_s`, `wcsnlen`, `wcsnlen_s`, `_mbsnlen`, `_mbsnlen_l`, `_mbstrnlen`, `_mbstrnlen_l` -Gets the length of a string by using the current locale or one that has been passed in. These are more secure versions of [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md). +Gets the length of a string by using the current locale or one that has been passed in. These functions are more secure versions of [`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md). > [!IMPORTANT] -> **`_mbsnlen`**, **`_mbsnlen_l`**, **`_mbstrnlen`**, and **`_mbstrnlen_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnlen`**, **`_mbsnlen_l`**, **`_mbstrnlen`**, and **`_mbstrnlen_l`** can't be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -24,7 +24,7 @@ size_t strnlen( const char *str, size_t numberOfElements ); -size_t strnlen_s( +size_t strnlen_s( // See note in remarks section about linkage const char *str, size_t numberOfElements ); @@ -32,7 +32,7 @@ size_t wcsnlen( const wchar_t *str, size_t numberOfElements ); -size_t wcsnlen_s( +size_t wcsnlen_s( // See note in remarks section about linkage const wchar_t *str, size_t numberOfElements ); @@ -58,18 +58,18 @@ size_t _mbstrnlen_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated string. -*`numberOfElements`*
+*`numberOfElements`*\ The size of the string buffer. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -These functions return the number of characters in the string, not including the terminating null character. If there is no null terminator within the first *`numberOfElements`* bytes of the string (or wide characters for **`wcsnlen`**), then *`numberOfElements`* is returned to indicate the error condition; null-terminated strings have lengths that are strictly less than *`numberOfElements`*. +These functions return the number of characters in the string, not including the terminating null character. If there's no null terminator within the first *`numberOfElements`* bytes of the string (or wide characters for **`wcsnlen`**), then *`numberOfElements`* is returned to indicate the error condition; null-terminated strings have lengths that are strictly less than *`numberOfElements`*. **`_mbstrnlen`** and **`_mbstrnlen_l`** return -1 if the string contains an invalid multibyte character. @@ -80,36 +80,41 @@ These functions return the number of characters in the string, not including the Each of these functions returns the number of characters in *`str`*, not including the terminating null character. However, **`strnlen`** and **`strnlen_s`** interpret the string as a single-byte character string and therefore, the return value is always equal to the number of bytes, even if the string contains multibyte characters. **`wcsnlen`** and **`wcsnlen_s`** are wide-character versions of **`strnlen`** and **`strnlen_s`** respectively; the arguments for **`wcsnlen`** and **`wcsnlen_s`** are wide-character strings and the count of characters are in wide-character units. Otherwise, **`wcsnlen`** and **`strnlen`** behave identically, as do **`strnlen_s`** and **`wcsnlen_s`**. -**`strnlen`**, **`wcsnlen`**, and **`_mbsnlen`** do not validate their parameters. If *`str`* is **`NULL`**, an access violation occurs. +**`strnlen`**, **`wcsnlen`**, and **`_mbsnlen`** don't validate their parameters. If *`str`* is `NULL`, an access violation occurs. -**`strnlen_s`** and **`wcsnlen_s`** validate their parameters. If *`str`* is **`NULL`**, the functions return 0. +**`strnlen_s`** and **`wcsnlen_s`** validate their parameters. If *`str`* is `NULL`, the functions return 0. -**`_mbstrnlen`** also validates its parameters. If *`str`* is **`NULL`**, or if *`numberOfElements`* is greater than **`INT_MAX`**, **`_mbstrnlen`** generates an invalid parameter exception, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`_mbstrnlen`** sets **`errno`** to **`EINVAL`** and returns -1. +**`_mbstrnlen`** also validates its parameters. If *`str`* is `NULL`, or if *`numberOfElements`* is greater than `INT_MAX`, **`_mbstrnlen`** generates an invalid parameter exception, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbstrnlen`** sets `errno` to `EINVAL` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +> [!Note] +> When you use Windows SDK version 10.0.26100.6901 and Visual Studio 2026 or later together, `strnlen_s` and `wcsnlen_s` are no longer `static inline` (internal linkage). Instead, they are `inline` (external linkage).\ +> To return to the previous behavior, `#define _STATIC_INLINE_UCRT_FUNCTIONS=1` before including any CRT headers. By default, `_STATIC_INLINE_UCRT_FUNCTIONS` is set to 0.\ +> This change increases UCRT conformance with the C++ standard and improves compatibility with C++ modules. -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcsnlen`**|**`strnlen`**|**`strnlen`**|**`wcsnlen`**| -|**`_tcscnlen`**|**`strnlen`**|**`_mbsnlen`**|**`wcsnlen`**| -|**`_tcscnlen_l`**|**`strnlen`**|**`_mbsnlen_l`**|**`wcsnlen`**| +### Generic-text routine mappings -**`_mbsnlen`** and **`_mbstrnlen`** return the number of multibyte characters in a multibyte-character string. **`_mbsnlen`** recognizes multibyte-character sequences according to the multibyte code page that's currently in use or according to the locale that's passed in; it does not test for multibyte-character validity. **`_mbstrnlen`** tests for multibyte-character validity and recognizes multibyte-character sequences. If the string that's passed to **`_mbstrnlen`** contains an invalid multibyte character, **`errno`** is set to **`EILSEQ`**. +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnlen` | **`strnlen`** | **`strnlen`** | **`wcsnlen`** | +| `_tcscnlen` | **`strnlen`** | **`_mbsnlen`** | **`wcsnlen`** | +| `_tcscnlen_l` | **`strnlen`** | **`_mbsnlen_l`** | **`wcsnlen`** | -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale; see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior and the versions that have the **`_l`** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbsnlen`** and **`_mbstrnlen`** return the number of multibyte characters in a multibyte-character string. **`_mbsnlen`** recognizes multibyte-character sequences according to the multibyte code page that's currently in use or according to the locale that's passed in; it doesn't test for multibyte-character validity. **`_mbstrnlen`** tests for multibyte-character validity and recognizes multibyte-character sequences. If the string that's passed to **`_mbstrnlen`** contains an invalid multibyte character, `errno` is set to `EILSEQ`. + +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior and the versions that have the **`_l`** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strnlen`**, **`strnlen_s`**|``| -|**`wcsnlen`**, **`wcsnlen_s`**|`` or ``| -|**`_mbsnlen`**, **`_mbsnlen_l`**|``| -|**`_mbstrnlen`**, **`_mbstrnlen_l`**|``| +| Routine | Required header | +|---|---| +| **`strnlen`**, **`strnlen_s`** | `` | +| **`wcsnlen`**, **`wcsnlen_s`** | `` or `` | +| **`_mbsnlen`**, **`_mbsnlen_l`** | `` | +| **`_mbstrnlen`**, **`_mbstrnlen_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -151,14 +156,14 @@ Length: 100 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)
-[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[`strcoll` Functions](../../c-runtime-library/strcoll-functions.md)
-[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md b/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md index 56de094843a..e7d55e8de25 100644 --- a/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md +++ b/docs/c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md @@ -1,21 +1,22 @@ --- description: "Learn more about: _strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l" -title: "_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l" +title: "_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l, _tcsnset_s, _tcsncset_s, _tcsncset_s_l" ms.date: "4/2/2020" -api_name: ["_mbsnset_s_l", "_strnset_s", "_mbsnset_s", "_strnset_s_l", "_wcsnset_s_l", "_wcsnset_s", "_o__mbsnset_s", "_o__mbsnset_s_l", "_o__strnset_s", "_o__wcsnset_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_name: ["_mbsnset_s_l", "_strnset_s", "_mbsnset_s", "_strnset_s_l", "_wcsnset_s_l", "_wcsnset_s", "_o__mbsnset_s", "_o__mbsnset_s_l", "_o__strnset_s", "_o__wcsnset_s", "_tcsncset_s", "_tcsncset_s_l", "_tcsnset_s"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_mbsnset_s_l", "wcsnset_s", "_tcsnset_s_l", "_wcsnset_s", "_mbsnset_s", "_wcsnset_s_l", "_strnset_s_l", "strnset_s_l", "_tcsnset_s", "_strnset_s", "strnset_s", "mbsnset_s_l", "mbsnset_s", "wcsnset_s_l"] -helpviewer_keywords: ["tcsnset_s function", "mbsnset_s_l function", "initializing characters", "wcsnset_s function", "mbsnset_s function", "_tcsnset_s_l function", "_strnset_s_l function", "_mbsnset_s function", "strnset_s_l function", "_tcsnset_s function", "_strnset_s function", "tcsnset_s_l function", "_mbsnset_s_l function", "strnset_s function", "_wcsnset_s function"] -ms.assetid: 9cf1b321-b5cb-4469-b285-4c07cfbd8813 +f1_keywords: ["_mbsnset_s_l", "wcsnset_s", "_tcsnset_s", "_tcsnset_s_l", "_wcsnset_s", "_mbsnset_s", "_wcsnset_s_l", "_strnset_s_l", "strnset_s_l", "_strnset_s", "strnset_s", "mbsnset_s_l", "mbsnset_s", "wcsnset_s_l", "_tcsncset_s", "_tcsncset_s_l"] +helpviewer_keywords: ["tcsnset_s function", "mbsnset_s_l function", "initializing characters", "wcsnset_s function", "mbsnset_s function", "_tcsnset_s function", "_tcsnset_s_l function", "_strnset_s_l function", "_mbsnset_s function", "strnset_s_l function", "_strnset_s function", "tcsnset_s_l function", "_mbsnset_s_l function", "strnset_s function", "_wcsnset_s function", "_tcsncset_s function", "_tcsncset_s_l function"] --- -# _strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l +# `_strnset_s`, `_strnset_s_l`, `_wcsnset_s`, `_wcsnset_s_l`, `_mbsnset_s`, `_mbsnset_s_l`, `_tcsnset_s`, `_tcsncset_s`, `_tcsncset_s_l` -Initializes characters of a string to a given character. These versions of [_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Initializes characters of a string to a given character. These versions of [`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsnset_s** and **_mbsnset_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnset_s`** and **`_mbsnset_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). + +For `_tcsnset_s`, `_tcsnset_s_l`, `_tcsncset_s`, and `_tcsncset_s_l` see [Generic-text function mappings](#generic-text-function-mappings). ## Syntax @@ -63,57 +64,61 @@ errno_t _mbsnset_s_l( ### Parameters -*str*
+*`str`*\ String to be altered. -*numberOfElements*
-The size of the *str* buffer. +*`numberOfElements`*\ +The size of the *`str`* buffer. -*c*
+*`c`*\ Character setting. -*count*
+*`count`*\ Number of characters to be set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful, otherwise an error code. -These functions validate their arguments. If *str* is not a valid null-terminated string or the size argument is less than or equal to 0, then the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return an error code and set **errno** to that error code. The default error code is **EINVAL** if a more specific value does not apply. +These functions validate their arguments. If *`str`* isn't a valid null-terminated string or the size argument is less than or equal to 0, then the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return an error code and set `errno` to that error code. The default error code is `EINVAL` if a more specific value doesn't apply. ## Remarks -These functions set, at most, the first *count* characters of *str* to *c*. If *count* is greater than the size of *str*, the size of *str* is used instead of *count*. An error occurs if *count* is greater than *numberOfElements* and both those parameters are greater than the size of *str*. +These functions set, at most, the first *`count`* characters of *`str`* to *`c`*. If *`count`* is greater than the size of *`str`*, the size of *`str`* is used instead of *`count`*. An error occurs if *`count`* is greater than *`numberOfElements`* and both those parameters are greater than the size of *`str`*. + +**`_wcsnset_s`** and **`_mbsnset_s`** are wide-character and multibyte-character versions of **`_strnset_s`**. The string argument of **`_wcsnset_s`** is a wide-character string; that of **`_mbsnset_s`** is a multibyte-character string. These three functions behave identically otherwise. -**_wcsnset_s** and **_mbsnset_s** are wide-character and multibyte-character versions of **_strnset_s**. The string argument of **_wcsnset_s** is a wide-character string; that of **_mbsnset_s** is amultibyte-character string. These three functions behave identically otherwise. +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The debug library versions of these functions first fill the buffer with `0xFE`. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +### Generic-text function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnset_s**|**_strnset_s**|**_mbsnbset_s**|**_wcsnset_s**| -|**_tcsnset_s_l**|**_strnset_s_l**|**_mbsnbset_s_l**|**_wcsnset_s_l**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnset_s` | `_strnset_s` | `_mbsnbset_s` | `_wcsnset_s` | +| `_tcsnset_s_l` | `_strnset_s_l` | `_mbsnbset_s_l` | `_wcsnset_s_l` | +| `_tcsncset_s` | `_strnset_s` | `_mbsnset_s` | `_wcsnset_s` | +| `_tcsncset_s_l` | `_strnset_s_l` | `_mbsnset_s_l` | `_wcsnset_s_l` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnset_s**|\| -|**_strnset_s_l**|\| -|**_wcsnset_s**|\ or \| -|**_wcsnset_s_l**|\| -|**_mbsnset_s**, **_mbsnset_s_l**|\| +| Routine | Required header | +|---|---| +| **`_strnset_s`** | `` | +| **`_strnset_s_l`** | `` | +| **`_wcsnset_s`** | `` or `` | +| **`_wcsnset_s_l`** | `` | +| **`_mbsnset_s`**, **`_mbsnset_s_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -139,10 +144,10 @@ After: **** is a test ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md b/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md index 7f22dc0b85f..7b6266e5357 100644 --- a/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md +++ b/docs/c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbs title: "_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l" ms.date: "4/2/2020" api_name: ["_mbsnset", "_strnset", "_mbsnset_l", "_wcsnset_l", "_wcsnset", "_strnset_l", "_o__mbsnset", "_o__mbsnset_l", "_o__wcsnset"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsncset_l", "mbsnset_l", "_tcsnset_l", "_fstrnset", "_wcsnset_l", "_ftcsnset", "wcsnset_l", "_mbsnset_l", "_strnset", "_tcsnset", "_strnset_l", "mbsnset", "strnset_l", "_mbsnset", "_wcsnset", "_tcsncset"] helpviewer_keywords: ["_wcsnset function", "strnset_l function", "tcsnset function", "tcsncset function", "characters [C++], initializing to formats", "mbsnset function", "_tcsnset_l function", "_mbsnset function", "_strnset function", "_tcsncset_l function", "mbsnset_l function", "_tcsnset function", "initializing characters", "_tcsncset function", "ftcsnset function", "wcsnset_l function", "_ftcsnset function", "_wcsnset_l function", "_fstrnset function", "_mbsnset_l function", "_strnset_l function", "fstrnset function", "strings [C++], initializing", "tcsnset_l function"] ms.assetid: 3f306489-5763-48e5-b939-aefee7c94ef5 --- -# _strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l +# `_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l` -Initializes characters of a string to a given character. More secure versions of these functions exist; see [_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md). +Initializes characters of a string to a given character. More secure versions of these functions exist; see [`_strnset_s`, `_strnset_s_l`, `_wcsnset_s`, `_wcsnset_s_l`, `_mbsnset_s`, `_mbsnset_s_l`](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md). > [!IMPORTANT] -> **_mbsnset** and **_mbsnset_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsnset`** and **`_mbsnset_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,52 +57,52 @@ unsigned char *_mbsnset_l( ### Parameters -*str*
+*`str`*\ String to be altered. -*c*
+*`c`*\ Character setting. -*count*
+*`count`*\ Number of characters to be set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the altered string. ## Remarks -The **_strnset** function sets, at most, the first *count* characters of *str* to *c* (converted to **`char`**). If *count* is greater than the length of *str*, the length of *str* is used instead of *count*. +The **`_strnset`** function sets, at most, the first *`count`* characters of *`str`* to *`c`* (converted to **`char`**). If *`count`* is greater than the length of *`str`*, the length of *`str`* is used instead of *`count`*. -**_wcsnset** and **_mbsnset** are wide-character and multibyte-character versions of **_strnset**. The string arguments and return value of **_wcsnset** are wide-character strings; those of **_mbsnset** are multibyte-character strings. These three functions behave identically otherwise. +**`_wcsnset`** and **`_mbsnset`** are wide-character and multibyte-character versions of **`_strnset`**. The string arguments and return value of **`_wcsnset`** are wide-character strings. The string arguments and return value of **`_mbsnset`** are multibyte-character strings. These three functions behave identically otherwise. -**_mbsnset** validates its parameters; if *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, **_mbsnset** returns **NULL** and sets **errno** to **EINVAL**. **_strnset** and **_wcsnset** do not validate their parameters. +**`_mbsnset`** validates its parameters; if *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, **`_mbsnset`** returns `NULL` and sets `errno` to `EINVAL`. **`_strnset`** and **`_wcsnset`** don't validate their parameters. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsnset**|**_strnset**|**_mbsnbset**|**_wcsnset**| -|**_tcsnset_l**|**_strnset_l**|**_mbsnbset_l**|**_wcsnset_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsnset` | **`_strnset`** | **`_mbsnbset`** | **`_wcsnset`** | +| `_tcsnset_l` | **`_strnset_l`** | **`_mbsnbset_l`** | **`_wcsnset_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strnset**|\| -|**_strnset_l**|\| -|**_wcsnset**|\ or \| -|**_wcsnset_l**|\| -|**_mbsnset**, **_mbsnset_l**|\| +| Routine | Required header | +|---|---| +| **`_strnset`** | \ | +| **`_strnset_l`** | \ | +| **`_wcsnset`** | \ or \ | +| **`_wcsnset_l`** | \ | +| **`_mbsnset`**, **`_mbsnset_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -130,10 +130,10 @@ After: **** is a test ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/strnset-wcsnset.md b/docs/c-runtime-library/reference/strnset-wcsnset.md index e7b45b81196..4447d81397a 100644 --- a/docs/c-runtime-library/reference/strnset-wcsnset.md +++ b/docs/c-runtime-library/reference/strnset-wcsnset.md @@ -10,8 +10,8 @@ f1_keywords: ["wcsnset", "strnset"] helpviewer_keywords: ["strnset function", "wcsnset function"] ms.assetid: e7868ac9-dc34-4606-bd3c-0fb2e7c51631 --- -# strnset, wcsnset +# `strnset`, `wcsnset` -The Microsoft-specific function names `strnset` and `wcsnset` are deprecated aliases for the [_strnset and _wcsnset](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strnset` and `wcsnset` are deprecated aliases for the [`_strnset` and `_wcsnset`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strnset and _wcsnset](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) or the security-enhanced [_strnset_s and _wcsnset_s](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strnset` and `_wcsnset`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) or the security-enhanced [`_strnset_s` and `_wcsnset_s`](strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md b/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md index a80c54a7acb..cf9a1974771 100644 --- a/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md +++ b/docs/c-runtime-library/reference/strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l" title: "strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l" ms.date: "4/2/2020" api_name: ["_mbspbrk", "wcspbrk", "_mbspbrk_l", "strpbrk", "_o__mbspbrk", "_o__mbspbrk_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fstrpbrk", "_mbspbrk", "strpbrk", "_tcspbrk", "_ftcspbrk", "wcspbrk"] helpviewer_keywords: ["fstrpbrk function", "_ftcspbrk function", "_mbspbrk_l function", "strpbrk function", "_fstrpbrk function", "mbspbrk function", "characters [C++], scanning strings", "_tcspbrk function", "wcspbrk function", "ftcspbrk function", "character sets [C++], scanning strings for characters", "strings [C++], scanning", "tcspbrk function", "_mbspbrk function", "mbspbrk_l function"] ms.assetid: 80b504f7-a167-4dde-97ad-4ae3000dc810 --- -# strpbrk, wcspbrk, _mbspbrk, _mbspbrk_l +# `strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l` Scans strings for characters in specified character sets. > [!IMPORTANT] -> `_mbspbrk` and `_mbspbrk_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbspbrk`** and **`_mbspbrk_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -75,51 +75,51 @@ const unsigned char *_mbspbrk_l( ### Parameters -*str*
+*`str`*\ Null-terminated, searched string. -*strCharSet*
+*`strCharSet`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Returns a pointer to the first occurrence of any character from *strCharSet* in *str*, or a NULL pointer if the two string arguments have no characters in common. +Returns a pointer to the first occurrence of any character from *`strCharSet`* in *`str`*, or a `NULL` pointer if the two string arguments have no characters in common. ## Remarks -The `strpbrk` function returns a pointer to the first occurrence of a character in *str* that belongs to the set of characters in *strCharSet*. The search does not include the terminating null character. +The **`strpbrk`** function returns a pointer to the first occurrence of a character in *`str`* that belongs to the set of characters in *`strCharSet`*. The search doesn't include the terminating null character. -`wcspbrk` and `_mbspbrk` are wide-character and multibyte-character versions of `strpbrk`. The arguments and return value of `wcspbrk` are wide-character strings; those of `_mbspbrk` are multibyte-character strings. +**`wcspbrk`** and **`_mbspbrk`** are wide-character and multibyte-character versions of **`strpbrk`**. The arguments and return value of **`wcspbrk`** are wide-character strings. The arguments and return value of **`_mbspbrk`** are multibyte-character strings. -`_mbspbrk` validates its parameters. If *str* or *strCharSet* is NULL, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, `_mbspbrk` returns NULL and sets `errno` to EINVAL. `strpbrk` and `wcspbrk` do not validate their parameters. These three functions behave identically otherwise. +**`_mbspbrk`** validates its parameters. If *`str`* or *`strCharSet`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbspbrk`** returns `NULL` and sets `errno` to `EINVAL`. **`strpbrk`** and **`wcspbrk`** don't validate their parameters. These three functions behave identically otherwise. -`_mbspbrk` is similar to `_mbscspn` except that `_mbspbrk` returns a pointer rather than a value of type [size_t](../../c-runtime-library/standard-types.md). +**`_mbspbrk`** is similar to `_mbscspn` except that **`_mbspbrk`** returns a pointer rather than a value of type [`size_t`](../standard-types.md). -In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro _CRT_CONST_CORRECT_OVERLOADS is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol _CONST_RETURN. +In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -The output value is affected by the setting of the LC_CTYPE category setting of the locale; for more information, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the version with the **_l** suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the version with the `_l` suffix is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcspbrk`|`strpbrk`|`_mbspbrk`|`wcspbrk`| -|**n/a**|**n/a**|`_mbspbrk_l`|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcspbrk` | **`strpbrk`** | **`_mbspbrk`** | **`wcspbrk`** | +| **n/a** | **n/a** | **`_mbspbrk_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strpbrk`|\| -|`wcspbrk`|\ or \| -|`_mbspbrk`, `_mbspbrk_l`|\| +| Routine | Required header | +|---|---| +| **`strpbrk`** | \ | +| **`wcspbrk`** | \ or \ | +| **`_mbspbrk`**, **`_mbspbrk_l`** | \ | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example @@ -157,9 +157,9 @@ int main( void ) ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcspn, wcscspn, _mbscspn, _mbscspn_l](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[strchr, wcschr, _mbschr, _mbschr_l](strchr-wcschr-mbschr-mbschr-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strchr`, `wcschr`, `_mbschr`, `_mbschr_l`](strchr-wcschr-mbschr-mbschr-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md) diff --git a/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md b/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md index c1c16e62f5c..9c8d760c683 100644 --- a/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md +++ b/docs/c-runtime-library/reference/strrchr-wcsrchr-mbsrchr-mbsrchr-l.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: strrchr, wcsrchr, _mbsrchr, _mbsrchr_l" title: "strrchr, wcsrchr, _mbsrchr, _mbsrchr_l" +description: "Learn more about: strrchr, wcsrchr, _mbsrchr, _mbsrchr_l" ms.date: "4/2/2020" api_name: ["strrchr", "wcsrchr", "_mbsrchr", "_mbsrchr_l", "_o__mbsrchr", "_o__mbsrchr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsrchr", "_ftcsrchr", "strrchr", "wcsrchr", "_mbsrchr"] @@ -14,7 +14,7 @@ helpviewer_keywords: ["_mbsrchr function", "tcsrchr function", "mbsrchr_l functi Scans a string for the last occurrence of a character. > [!IMPORTANT] -> `_mbsrchr` and `_mbsrchr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsrchr`** and **`_mbsrchr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -83,52 +83,52 @@ Character to be located. *`locale`*\ Locale to use. -## Return Value +## Return value -Returns a pointer to the last occurrence of *`c`* in *`str`*, or `NULL` if *`c`* is not found. +Returns a pointer to the last occurrence of *`c`* in *`str`*, or `NULL` if *`c`* isn't found. ## Remarks -The `strrchr` function finds the last occurrence of *`c`* (converted to **`char`**) in *`str`*. The search includes the terminating `NULL` character. +The **`strrchr`** function finds the last occurrence of *`c`* (converted to **`char`**) in *`str`*. The search includes the terminating `NULL` character. -`wcsrchr` and `_mbsrchr` are wide-character and multibyte-character versions of `strrchr`. The arguments and return value of `wcsrchr` are wide-character strings; those of `_mbsrchr` are multibyte-character strings. +**`wcsrchr`** and **`_mbsrchr`** are wide-character and multibyte-character versions of **`strrchr`**. The arguments and return value of **`wcsrchr`** are wide-character strings. The arguments and return value of **`_mbsrchr`** are multibyte-character strings. In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload taking a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -`_mbsrchr` validates its parameters. If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and `_mbsrchr` returns 0. `strrchr` and `wcsrchr` do not validate their parameters. These three functions behave identically otherwise. +**`_mbsrchr`** validates its parameters. If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and **`_mbsrchr`** returns 0. **`strrchr`** and **`wcsrchr`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale; for more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcsrchr`|`strrchr`|`_mbsrchr`|`wcsrchr`| -|**n/a**|**n/a**|`_mbsrchr_l`|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsrchr` | **`strrchr`** | **`_mbsrchr`** | **`wcsrchr`** | +| **n/a** | **n/a** | **`_mbsrchr_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strrchr`|``| -|`wcsrchr`|`` or ``| -|`_mbsrchr`, `_mbsrchr_l`|``| +| Routine | Required header | +|---|---| +| **`strrchr`** | `` | +| **`wcsrchr`** | `` or `` | +| **`_mbsrchr`**, **`_mbsrchr_l`** | `` | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example -For an example of using `strrchr`, see [`strchr`](strchr-wcschr-mbschr-mbschr-l.md). +For an example of using **`strrchr`**, see [`strchr`](strchr-wcschr-mbschr-mbschr-l.md). ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)\ -[Locale](../../c-runtime-library/locale.md)\ -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ [`strchr`, `wcschr`, `_mbschr`, `_mbschr_l`](strchr-wcschr-mbschr-mbschr-l.md)\ [`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ [`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ [`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)\ -[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md b/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md index b37c90bb3b7..b2a3b77d3b5 100644 --- a/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md +++ b/docs/c-runtime-library/reference/strrev-wcsrev-mbsrev-mbsrev-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strrev, _wcsrev, _mbsrev, _mbsrev_l" title: "_strrev, _wcsrev, _mbsrev, _mbsrev_l" ms.date: "4/2/2020" api_name: ["_wcsrev", "_mbsrev", "_strrev", "_mbsrev_l", "_o__mbsrev", "_o__mbsrev_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_strrev", "_ftcsrev", "_tcsrev", "mbsrev", "mbsrev_l", "_wcsrev_fstrrev", "_mbsrev"] helpviewer_keywords: ["_mbsrev_l function", "characters [C++], switching", "_mbsrev function", "strrev function", "_ftcsrev function", "strings [C++], reversing", "wcsrev function", "_strrev function", "mbsrev_l function", "reversing characters in strings", "ftcsrev function", "characters [C++], reversing order", "_wcsrev function", "mbsrev function", "tcsrev function", "_tcsrev function"] ms.assetid: 87863e89-4fa0-421c-af48-25d8516fe72f --- -# _strrev, _wcsrev, _mbsrev, _mbsrev_l +# `_strrev`, `_wcsrev`, `_mbsrev`, `_mbsrev_l` Reverses the characters of a string. > [!IMPORTANT] -> **_mbsrev** and **_mbsrev_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsrev`** and **`_mbsrev_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -37,45 +37,45 @@ unsigned char *_mbsrev_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to reverse. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the altered string. No return value is reserved to indicate an error. ## Remarks -The **_strrev** function reverses the order of the characters in *str*. The terminating null character remains in place. **_wcsrev** and **_mbsrev** are wide-character and multibyte-character versions of **_strrev**. The arguments and return value of **_wcsrev** are wide-character strings; those of **_mbsrev** are multibyte-character strings. For **_mbsrev**, the order of bytes in each multibyte character in *str* is not changed. These three functions behave identically otherwise. +The **`_strrev`** function reverses the order of the characters in *`str`*. The terminating null character remains in place. **`_wcsrev`** and **`_mbsrev`** are wide-character and multibyte-character versions of **`_strrev`**. The arguments and return value of **`_wcsrev`** are wide-character strings. The arguments and return value of **`_mbsrev`** are multibyte-character strings. For **`_mbsrev`**, the order of bytes in each multibyte character in *`str`* isn't changed. These three functions behave identically otherwise. -**_mbsrev** validates its parameters. If either *string1* or *string2* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **_mbsrev** returns **NULL** and sets **errno** to **EINVAL**. **_strrev** and **_wcsrev** do not validate their parameters. +**`_mbsrev`** validates its parameters. If either *`string1`* or *`string2`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbsrev`** returns `NULL` and sets `errno` to `EINVAL`. **`_strrev`** and **`_wcsrev`** don't validate their parameters. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **_l** suffix use the current locale and the ones that do have the **_l** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the `_l` suffix use the current locale and the ones that do have the `_l` suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsrev**|**_strrev**|**_mbsrev**|**_wcsrev**| -|**n/a**|**n/a**|**_mbsrev_l**|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsrev` | **`_strrev`** | **`_mbsrev`** | **`_wcsrev`** | +| **n/a** | **n/a** | **`_mbsrev_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strrev**|\| -|**_wcsrev**|\ or \| -|**_mbsrev**, **_mbsrev_l**|\| +| Routine | Required header | +|---|---| +| **`_strrev`** | \ | +| **`_wcsrev`** | \ or \ | +| **`_mbsrev`**, **`_mbsrev_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -109,8 +109,8 @@ The string "Able was I ere I saw Elba" is a palindrome ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) diff --git a/docs/c-runtime-library/reference/strrev-wcsrev.md b/docs/c-runtime-library/reference/strrev-wcsrev.md index 5a0d2c18125..a0dbe0251c6 100644 --- a/docs/c-runtime-library/reference/strrev-wcsrev.md +++ b/docs/c-runtime-library/reference/strrev-wcsrev.md @@ -10,8 +10,8 @@ f1_keywords: ["strrev", "wcsrev"] helpviewer_keywords: ["strrev function", "wcsrev function"] ms.assetid: 89e05854-a9ce-4fb7-993d-a9831cd7edf2 --- -# strrev, wcsrev +# `strrev`, `wcsrev` -The Microsoft-specific function names `strrev` and `wcsrev` are deprecated aliases for the [_strrev and _wcsrev](strrev-wcsrev-mbsrev-mbsrev-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strrev` and `wcsrev` are deprecated aliases for the [`_strrev` and `_wcsrev`](strrev-wcsrev-mbsrev-mbsrev-l.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strrev and _wcsrev](strrev-wcsrev-mbsrev-mbsrev-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strrev` and `_wcsrev`](strrev-wcsrev-mbsrev-mbsrev-l.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md b/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md index 363596b6ad0..e5081eaae0a 100644 --- a/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md +++ b/docs/c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, title: "_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l" ms.date: "4/2/2020" api_name: ["_wcsset_s", "_wcsset_s_l", "_strset_s", "_mbsset_s_l", "_strset_s_l", "_mbsset_s", "_o__mbsset_s", "_o__mbsset_s_l", "_o__strset_s", "_o__wcsset_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wcsset_s_l", "strset_s", "_mbsset_s", "mbsset_s", "_strset_s", "_mbsset_s_l", "strset_s_l", "_wcsset_s", "mbsset_s_l", "wcsset_s_l", "wcsset_s", "_strset_s_l", "_tcsset_s_l", "_tcsset_s"] helpviewer_keywords: ["mbsset_s_l function", "wcsset_s function", "_mbsset_s function", "tcsset_s function", "strset_s_l function", "characters [C++], setting", "_wcsset_s_l function", "_strset_s function", "strset_s function", "wcsset_s_l function", "strings [C++], setting characters", "_strset_s_l function", "_mbsset_s_l function", "_wcsset_s function", "tcsset_s_l function", "_tcsset_s_l function", "_tcsset_s function", "mbsset_s function"] ms.assetid: dceb2909-6b41-4792-acb7-888e45bb8b35 --- -# _strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l +# `_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l` -Sets characters of a string to a character. These versions of [_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Sets characters of a string to a character. These versions of [`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsset_s** and **_mbsset_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsset_s`** and **`_mbsset_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -57,52 +57,52 @@ errno_t _mbsset_s_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to be set. -*numberOfElements*
-The size of the *str* buffer. +*`numberOfElements`*\ +The size of the *`str`* buffer. -*c*
+*`c`*\ Character setting. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Zero if successful, otherwise an error code. -These functions validate their arguments. If *str* is a null pointer, or the *numberOfElements* argument is less than or equal to 0, or the block passed in is not null-terminated, then the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EINVAL** and set **errno** to **EINVAL**. +These functions validate their arguments. If *`str`* is a null pointer, or the *`numberOfElements`* argument is less than or equal to 0, or the block passed in isn't null-terminated, then the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EINVAL` and set `errno` to `EINVAL`. ## Remarks -The **_strset_s** function sets all the characters of *str* to *c* (converted to **`char`**), except the terminating null character. **_wcsset_s** and **_mbsset_s** are wide-character and multibyte-character versions of **_strset_s**. The data types of the arguments and return values vary accordingly. These functions behave identically otherwise. +The **`_strset_s`** function sets all the characters of *`str`* to *`c`* (converted to **`char`**), except the terminating null character. **`_wcsset_s`** and **`_mbsset_s`** are wide-character and multibyte-character versions of **`_strset_s`**. The data types of the arguments and return values vary accordingly. These functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsset_s**|**_strset_s**|**_mbsset_s**|**_wcsset_s**| -|**_tcsset_s_l**|**_strset_s_l**|**_mbsset_s_l**|**_wcsset_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsset_s` | **`_strset_s`** | **`_mbsset_s`** | **`_wcsset_s`** | +| `_tcsset_s_l` | **`_strset_s_l`** | **`_mbsset_s_l`** | **`_wcsset_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strset_s**|\| -|**_strset_s_l**|\| -|**_wcsset_s**|\ or \| -|**_wcsset_s_l**|\| -|**_mbsset_s**, **_mbsset_s_l**|\| +| Routine | Required header | +|---|---| +| **`_strset_s`** | \ | +| **`_strset_s_l`** | \ | +| **`_wcsset_s`** | \ or \ | +| **`_wcsset_s_l`** | \ | +| **`_mbsset_s`**, **`_mbsset_s_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -128,12 +128,12 @@ After: ******************************* ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md)
-[memset, wmemset](memset-wmemset.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) diff --git a/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md b/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md index e8265942b83..9b1e2d00550 100644 --- a/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md +++ b/docs/c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strset, _strset_l, _wcsset, _wcsset_l, _mbsset, title: "_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l" ms.date: "4/2/2020" api_name: ["_wcsset", "_mbsset", "_strset_l", "_strset", "_wcsset_l", "_mbsset_l", "_o__mbsset", "_o__mbsset_l", "_o__wcsset"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["mbsset", "_strset_l", "_mbsset", "_strset", "mbsset_l", "strset_l", "_wcsset", "_ftcsset", "wcsset_l", "_tcsset_l", "_mbsset_l", "_wcsset_l", "_fstrset", "_tcsset"] helpviewer_keywords: ["_wcsset_l function", "_tcsset function", "wcsset_l function", "_ftcsset function", "characters [C++], setting", "_strset function", "ftcsset function", "strings [C++], setting characters", "mbsset function", "tcsset_l function", "_fstrset function", "mbsset_l function", "strset_l function", "_wcsset function", "_mbsset function", "_mbsset_l function", "tcsset function", "_strset_l function", "fstrset function", "_tcsset_l function"] ms.assetid: c42ded42-2ed9-4f06-a0a9-247ba305473a --- -# _strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l +# `_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l` -Sets characters of a string to a character. More secure versions of these functions are available; see [_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md). +Sets characters of a string to a character. More secure versions of these functions are available; see [`_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l`](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md). > [!IMPORTANT] -> **_mbsset** and **_mbsset_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsset`** and **`_mbsset_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -51,50 +51,50 @@ unsigned char *_mbsset_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to be set. -*c*
+*`c`*\ Character setting. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value Returns a pointer to the altered string. ## Remarks -The **_strset** function sets all characters (except the terminating null character) of *str* to *c*, converted to **`char`**. **_wcsset** and **_mbsset_l** are wide-character and multibyte-character versions of **_strset**, and the data types of the arguments and return values vary accordingly. These functions behave identically otherwise. +The **`_strset`** function sets all characters (except the terminating null character) of *`str`* to *`c`*, converted to **`char`**. **`_wcsset`** and **`_mbsset_l`** are wide-character and multibyte-character versions of **`_strset`**, and the data types of the arguments and return values vary accordingly. These functions behave identically otherwise. -**_mbsset** validates its parameters. If *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **_mbsset** returns **NULL** and sets **errno** to **EINVAL**. **_strset** and **_wcsset** do not validate their parameters. +**`_mbsset`** validates its parameters. If *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_mbsset`** returns `NULL` and sets `errno` to `EINVAL`. **`_strset`** and **`_wcsset`** don't validate their parameters. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale, _wsetlocale](setlocale-wsetlocale.md) for more information. The versions of these functions are identical, except that the ones that don't have the **_l** suffix use the current locale and the ones that do have the **_l** suffix instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions are identical, except that the ones that don't have the `_l` suffix use the current locale and the ones that do have the `_l` suffix instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). > [!IMPORTANT] -> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might be vulnerable to buffer overrun threats. Buffer overruns can be used for system attacks because they can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsset**|**_strset**|**_mbsset**|**_wcsset**| -|**_tcsset_l**|**_strset_l**|**_mbsset_l**|**_wcsset_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsset` | **`_strset`** | **`_mbsset`** | **`_wcsset`** | +| `_tcsset_l` | **`_strset_l`** | **`_mbsset_l`** | **`_wcsset_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strset**|\| -|**_strset_l**|\| -|**_wcsset**|\ or \| -|**_wcsset_l**|\| -|**_mbsset**, **_mbsset_l**|\| +| Routine | Required header | +|---|---| +| **`_strset`** | \ | +| **`_strset_l`** | \ | +| **`_wcsset`** | \ or \ | +| **`_wcsset_l`** | \ | +| **`_mbsset`**, **`_mbsset_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -122,12 +122,12 @@ After: ******************************* ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_mbsnbset, _mbsnbset_l](mbsnbset-mbsnbset-l.md)
-[memset, wmemset](memset-wmemset.md)
-[strcat, wcscat, _mbscat](strcat-wcscat-mbscat.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strcpy, wcscpy, _mbscpy](strcpy-wcscpy-mbscpy.md)
-[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_mbsnbset`, `_mbsnbset_l`](mbsnbset-mbsnbset-l.md)\ +[`memset`, `wmemset`](memset-wmemset.md)\ +[`strcat`, `wcscat`, `_mbscat`](strcat-wcscat-mbscat.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strcpy`, `wcscpy`, `_mbscpy`](strcpy-wcscpy-mbscpy.md)\ +[`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) diff --git a/docs/c-runtime-library/reference/strset-wcsset.md b/docs/c-runtime-library/reference/strset-wcsset.md index ce34622ab8d..3d54b5a7ccb 100644 --- a/docs/c-runtime-library/reference/strset-wcsset.md +++ b/docs/c-runtime-library/reference/strset-wcsset.md @@ -10,6 +10,6 @@ f1_keywords: ["strset", "wcsset"] helpviewer_keywords: ["wcsset function", "strset function"] ms.assetid: 20e132d8-4b6c-4341-b1eb-8e19b46047e2 --- -# strset, wcsset +# `strset`, `wcsset` -These functions are deprecated. Use the ISO C++ conformant [_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) or security-enhanced [_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) instead. +These functions are deprecated. Use the ISO C++ conformant [`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) or security-enhanced [`_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l`](strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) instead. diff --git a/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md b/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md index cbce390bad4..676ade2b01e 100644 --- a/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md +++ b/docs/c-runtime-library/reference/strspn-wcsspn-mbsspn-mbsspn-l.md @@ -3,19 +3,19 @@ description: "Learn more about: strspn, wcsspn, _mbsspn, _mbsspn_l" title: "strspn, wcsspn, _mbsspn, _mbsspn_l" ms.date: "4/2/2020" api_name: ["_mbsspn_l", "wcsspn", "strspn", "_mbsspn", "_o__mbsspn", "_o__mbsspn_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_ftcsspn", "wcsspn", "_mbsspn", "_tcsspn", "strspn"] helpviewer_keywords: ["wcsspn function", "strings [C++], searching", "mbsspn function", "tcsspn function", "strspn function", "substrings, finding", "_mbsspn_l function", "ftcsspn function", "_mbsspn function", "_ftcsspn function", "mbsspn_l function", "_tcsspn function"] ms.assetid: d077284a-809f-4068-959e-c6d6262677eb --- -# strspn, wcsspn, _mbsspn, _mbsspn_l +# `strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l` -Returns the index of the first character, in a string, that does not belong to a set of characters. +Returns the index of the first character in a string that doesn't belong to a specified set of characters. > [!IMPORTANT] -> **_mbsspn** and **_mbsspn_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsspn`** and **`_mbsspn_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,45 +41,45 @@ size_t _mbsspn_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to search. -*strCharSet*
+*`strCharSet`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Returns an integer value specifying the length of the substring in *str* that consists entirely of characters in *strCharSet*. If *str* begins with a character not in *strCharSet*, the function returns 0. +Returns an integer value specifying the length of the substring in *`str`* that consists entirely of characters in *`strCharSet`*. If *`str`* begins with a character not in *`strCharSet`*, the function returns 0. ## Remarks -The **strspn** function returns the index of the first character in *str* that does not belong to the set of characters in *strCharSet*. The search does not include terminating null characters. +The **`strspn`** function returns the index of the first character in *`str`* that doesn't belong to the set of characters in *`strCharSet`*. The search doesn't include terminating null characters. -**wcsspn** and **_mbsspn** are wide-character and multibyte-character versions of **strspn**. The arguments of **wcsspn** are wide-character strings; those of **_mbsspn** are multibyte-character strings. **_mbsspn** validates its parameters. If *str* or *strCharSet* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, **_mbspn** sets **errno** to **EINVAL** and returns 0. **strspn** and **wcsspn** do not validate their parameters. These three functions behave identically otherwise. +**`wcsspn`** and **`_mbsspn`** are wide-character and multibyte-character versions of **`strspn`**. The arguments of **`wcsspn`** are wide-character strings. The arguments of **`_mbsspn`** are multibyte-character strings. **`_mbsspn`** validates its parameters. If *`str`* or *`strCharSet`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, **`_mbspn`** sets `errno` to `EINVAL` and returns 0. **`strspn`** and **`wcsspn`** don't validate their parameters. These three functions behave identically otherwise. -The output value is affected by the setting of the **LC_CTYPE** category setting of the locale; see [setlocale](setlocale-wsetlocale.md) for more information. The versions of these functions without the **_l** suffix use the current locale for this locale-dependent behavior; the versions with the **_l** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale for this locale-dependent behavior; the versions with the `_l` suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsspn**|**strspn**|**_mbsspn**|**wcsspn**| -|**n/a**|**n/a**|**_mbsspn_l**|**n/a**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsspn` | **`strspn`** | **`_mbsspn`** | **`wcsspn`** | +| **n/a** | **n/a** | **`_mbsspn_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strspn**|\| -|**wcsspn**|\ or \| -|**_mbsspn**, **_mbsspn_l**|\| +| Routine | Required header | +|---|---| +| **`strspn`** | \ | +| **`wcsspn`** | \ or \ | +| **`_mbsspn`**, **`_mbsspn_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -110,13 +110,13 @@ The portion of 'cabbage' containing only a, b, or c is 5 bytes long ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[_strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l](strspnp-wcsspnp-mbsspnp-mbsspnp-l.md)
-[strcspn, wcscspn, _mbscspn, _mbscspn_l](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`_strspnp`, `_wcsspnp`, `_mbsspnp`, `_mbsspnp_l`](strspnp-wcsspnp-mbsspnp-mbsspnp-l.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md) diff --git a/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md b/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md index 7eff7011b63..519b5dcc50a 100644 --- a/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md +++ b/docs/c-runtime-library/reference/strspnp-wcsspnp-mbsspnp-mbsspnp-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l" title: "_strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l" ms.date: "4/2/2020" api_name: ["_mbsspnp", "_wcsspnp", "_mbsspnp_l", "_strspnp", "_o__mbsspnp", "_o__mbsspnp_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcsspnp", "_mbsspnp", "strspnp", "_ftcsspnp", "_mbsspnp_l", "wcsspnp", "mbsspnp_l", "_wcsspnp", "_strspnp", "mbsspnp"] helpviewer_keywords: ["_strspnp function", "_wcsspnp function", "_mbsspnp_l function", "strspnp function", "mbsspnp function", "wcsspnp function", "_mbsspnp function", "mbsspnp_l function", "_tcsspnp function", "tcsspnp function"] ms.assetid: 1ce18100-2edd-4c3b-af8b-53f204d80233 --- -# _strspnp, _wcsspnp, _mbsspnp, _mbsspnp_l +# `_strspnp`, `_wcsspnp`, `_mbsspnp`, `_mbsspnp_l` -Returns a pointer to the first character in a given string that is not in another given string. +Returns a pointer to the first character in a given string that isn't in another given string. > [!IMPORTANT] -> **_mbsspnp** and **_mbsspnp_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsspnp`** and **`_mbsspnp_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -41,46 +41,46 @@ unsigned char *_mbsspnp_l( ### Parameters -*str*
+*`str`*\ Null-terminated string to search. -*charset*
+*`charset`*\ Null-terminated character set. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**_strspnp**, **_wcsspnp**, and **_mbsspnp** return a pointer to the first character in *str* that does not belong to the set of characters in *charset*. Each of these functions returns **NULL** if *str* consists entirely of characters from *charset*. For each of these routines, no return value is reserved to indicate an error. +**`_strspnp`**, **`_wcsspnp`**, and **`_mbsspnp`** return a pointer to the first character in *`str`* that doesn't belong to the set of characters in *`charset`*. Each of these functions returns `NULL` if *`str`* consists entirely of characters from *`charset`*. For each of these routines, no return value is reserved to indicate an error. ## Remarks -The **_mbsspnp** function returns a pointer to the multibyte character that is the first character in *str* that does not belong to the set of characters in *charset*. **_mbsspnp** recognizes multibyte-character sequences according to the [multibyte code page](../../c-runtime-library/code-pages.md) currently in use. The search does not include terminating null characters. +The **`_mbsspnp`** function returns a pointer to the multibyte character that is the first character in *`str`* that doesn't belong to the set of characters in *`charset`*. **`_mbsspnp`** recognizes multibyte-character sequences according to the [multibyte code page](../code-pages.md) currently in use. The search doesn't include terminating null characters. -If either *str* or *charset* is a null pointer, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns **NULL** and sets **errno** to **EINVAL**. +If either *`str`* or *`charset`* is a null pointer, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns `NULL` and sets `errno` to `EINVAL`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_tcsspnp**|**_strspnp**|**_mbsspnp**|**_wcsspnp**| +| Tchar.h routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsspnp` | **`_strspnp`** | **`_mbsspnp`** | **`_wcsspnp`** | -**_strspnp** and **_wcsspnp** are single-byte character and wide-character versions of **_mbsspnp**. **_strspnp** and **_wcsspnp** behave identically to **_mbsspnp** otherwise; they are provided only for this mapping and should not be used for any other reason. For more information, see [Using Generic-Text Mappings](../../c-runtime-library/using-generic-text-mappings.md) and [Generic-Text Mappings](../../c-runtime-library/generic-text-mappings.md). +**`_strspnp`** and **`_wcsspnp`** are single-byte character and wide-character versions of **`_mbsspnp`**. **`_strspnp`** and **`_wcsspnp`** behave identically to **`_mbsspnp`** otherwise; they're provided only for this mapping and shouldn't be used for any other reason. For more information, see [Using generic-text mappings](../using-generic-text-mappings.md) and [Generic-text mappings](../generic-text-mappings.md). -**_mbsspnp_l** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`_mbsspnp_l`** is identical except that it uses the locale parameter passed in instead. For more information, see [Locale](../locale.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_mbsspnp**|\| -|**_strspnp**|\| -|**_wcsspnp**|\| +| Routine | Required header | +|---|---| +| **`_mbsspnp`** | \ | +| **`_strspnp`** | \ | +| **`_wcsspnp`** | \ | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,12 +106,12 @@ abbage ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[strspn, wcsspn, _mbsspn, _mbsspn_l](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
-[strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)
-[_strnicmp, _wcsnicmp, _mbsnicmp, _strnicmp_l, _wcsnicmp_l, _mbsnicmp_l](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)
-[strrchr, wcsrchr, _mbsrchr, _mbsrchr_l](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)\ +[`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)\ +[`_strnicmp`, `_wcsnicmp`, `_mbsnicmp`, `_strnicmp_l`, `_wcsnicmp_l`, `_mbsnicmp_l`](strnicmp-wcsnicmp-mbsnicmp-strnicmp-l-wcsnicmp-l-mbsnicmp-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md) diff --git a/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md b/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md index d25146b66fd..d3d44af2523 100644 --- a/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md +++ b/docs/c-runtime-library/reference/strstr-wcsstr-mbsstr-mbsstr-l.md @@ -3,7 +3,7 @@ description: "Learn more about: strstr, wcsstr, _mbsstr, _mbsstr_l" title: "strstr, wcsstr, _mbsstr, _mbsstr_l" ms.date: "4/2/2020" api_name: ["_mbsstr", "wcsstr", "_mbsstr_l", "strstr", "_o__mbsstr", "_o__mbsstr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_fstrstr", "_ftcsstr", "strstr", "wcsstr", "_mbsstr", "_tcsstr"] @@ -15,7 +15,7 @@ ms.assetid: 03d70c3f-2473-45cb-a5f8-b35beeb2748a Returns a pointer to the first occurrence of a search string in a string. > [!IMPORTANT] -> `_mbsstr` and `_mbsstr_l` cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsstr`** and **`_mbsstr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -75,48 +75,48 @@ const unsigned char *_mbsstr_l( ### Parameters -*`str`*
+*`str`*\ Null-terminated string to search. -*`strSearch`*
+*`strSearch`*\ Null-terminated string to search for. -*`locale`*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Returns a pointer to the first occurrence of *`strSearch`* in *`str`*, or **`NULL`** if *`strSearch`* does not appear in *`str`*. If *`strSearch`* points to a string of zero length, the function returns *`str`*. +Returns a pointer to the first occurrence of *`strSearch`* in *`str`*, or `NULL` if *`strSearch`* doesn't appear in *`str`*. If *`strSearch`* points to a string of zero length, the function returns *`str`*. ## Remarks -The `strstr` function returns a pointer to the first occurrence of *`strSearch`* in *`str`*. The search does not include terminating null characters. `wcsstr` is the wide-character version of `strstr` and `_mbsstr` is the multibyte-character version. The arguments and return value of `wcsstr` are wide-character strings; those of `_mbsstr` are multibyte-character strings. `_mbsstr` validates its parameters. If *`str`* or *`strSearch`* is NULL, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, `_mbsstr` sets `errno` to `EINVAL` and returns 0. `strstr` and `wcsstr` do not validate their parameters. These three functions behave identically otherwise. +The **`strstr`** function returns a pointer to the first occurrence of *`strSearch`* in *`str`*. The search doesn't include terminating null characters. **`wcsstr`** is the wide-character version of **`strstr`** and **`_mbsstr`** is the multibyte-character version. The arguments and return value of **`wcsstr`** are wide-character strings. The arguments and return value of **`_mbsstr`** are multibyte-character strings. **`_mbsstr`** validates its parameters. If *`str`* or *`strSearch`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, **`_mbsstr`** sets `errno` to `EINVAL` and returns 0. **`strstr`** and **`wcsstr`** don't validate their parameters. These three functions behave identically otherwise. > [!IMPORTANT] -> These functions might incur a threat from a buffer overrun problem. Buffer overrun problems can be used to attack a system because they can allow the execution of arbitrary code, which can cause an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions might incur a threat from a buffer overrun problem. Buffer overrun problems can be used to attack a system because they can allow the execution of arbitrary code, which can cause an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). In C, these functions take a **`const`** pointer for the first argument. In C++, two overloads are available. The overload that takes a pointer to **`const`** returns a pointer to **`const`**; the version that takes a pointer to non-**`const`** returns a pointer to non-**`const`**. The macro `_CRT_CONST_CORRECT_OVERLOADS` is defined if both the **`const`** and non-**`const`** versions of these functions are available. If you require the non-**`const`** behavior for both C++ overloads, define the symbol `_CONST_RETURN`. -The output value is affected by the locale-category setting of `LC_CTYPE`; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that do not have the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions that have the **`_l`** suffix are identical except that they instead use the locale parameter that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The output value is affected by the locale-category setting of `LC_CTYPE`; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The versions of these functions that don't have the **`_l`** suffix use the current locale for this locale-dependent behavior; the versions that have the **`_l`** suffix are identical except that they instead use the locale parameter that's passed in. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|`_tcsstr`|`strstr`|`_mbsstr`|`wcsstr`| -|**n/a**|**n/a**|`_mbsstr_l`|**n/a**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsstr` | **`strstr`** | **`_mbsstr`** | **`wcsstr`** | +| **n/a** | **n/a** | **`_mbsstr_l`** | **n/a** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`strstr`|``| -|`wcsstr`|`` or ``| -|`_mbsstr`, `_mbsstr_l`|``| +| Routine | Required header | +|---|---| +| **`strstr`** | `` | +| **`wcsstr`** | `` or `` | +| **`_mbsstr`**, **`_mbsstr_l`** | `` | -For more information about compatibility, see [Compatibility](../../c-runtime-library/compatibility.md). +For more information about compatibility, see [Compatibility](../compatibility.md). ## Example @@ -157,12 +157,12 @@ lazy found at position 36 ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)
-[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)
-[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
-[`basic_string::find`](../../standard-library/basic-string-class.md#find)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strpbrk`, `wcspbrk`, `_mbspbrk`, `_mbspbrk_l`](strpbrk-wcspbrk-mbspbrk-mbspbrk-l.md)\ +[`strrchr`, `wcsrchr`, `_mbsrchr`, `_mbsrchr_l`](strrchr-wcsrchr-mbsrchr-mbsrchr-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)\ +[`basic_string::find`](../../standard-library/basic-string-class.md#find) diff --git a/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md b/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md index ef15b7288dd..c0ad6eb80e9 100644 --- a/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md +++ b/docs/c-runtime-library/reference/strtime-s-wstrtime-s.md @@ -3,16 +3,16 @@ description: "Learn more about: _strtime_s, _wstrtime_s" title: "_strtime_s, _wstrtime_s" ms.date: "4/2/2020" api_name: ["_wstrtime_s", "_strtime_s", "_o__strtime_s", "_o__wstrtime_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wstrtime_s", "strtime_s", "wstrtime_s", "_strtime_s"] helpviewer_keywords: ["wstrtime_s function", "copying time to buffers", "strtime_s function", "_wstrtime_s function", "time, copying", "_strtime_s function"] ms.assetid: 42acf013-c334-485d-b610-84c0af8a46ec --- -# _strtime_s, _wstrtime_s +# `_strtime_s`, `_wstrtime_s` -Copy the current time to a buffer. These are versions of [_strtime, _wstrtime](strtime-wstrtime.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Copy the current time to a buffer. These functions are versions of [`_strtime`, `_wstrtime`](strtime-wstrtime.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,59 +37,59 @@ errno_t _wstrtime_s( ### Parameters -*buffer*
+*`buffer`*\ A buffer, at least 10 bytes long, where the time will be written. -*numberOfElements*
+*`numberOfElements`*\ The size of the buffer. -## Return Value +## Return value Zero if successful. -If an error condition occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). The return value is an error code if there is a failure. Error codes are defined in ERRNO.H; see the following table for the exact errors generated by this function. For more information on error codes, see [errno Constants](../../c-runtime-library/errno-constants.md). +If an error condition occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). The return value is an error code if there's a failure. Error codes are defined in ERRNO.H; see the following table for the exact errors generated by this function. For more information on error codes, see [`errno` constants](../errno-constants.md). -### Error Conditions +### Error conditions -|*buffer*|*numberOfElements*|Return|Contents of *buffer*| -|--------------|------------------------|------------|--------------------------| -|**NULL**|(any)|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0|**EINVAL**|Not modified| -|Not **NULL** (pointing to valid buffer)|0 < size < 9|**EINVAL**|Empty string| -|Not **NULL** (pointing to valid buffer)|Size > 9|0|Current time formatted as specified in the remarks| +| *`buffer`* | *`numberOfElements`* | Return | Contents of *`buffer`* | +|---|---|---|---| +| `NULL` | (any) | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 | `EINVAL` | Not modified | +| Not `NULL` (pointing to valid buffer) | 0 < size < 9 | `EINVAL` | Empty string | +| Not `NULL` (pointing to valid buffer) | Size > 9 | 0 | Current time formatted as specified in the remarks | -## Security Issues +## Security issues -Passing in an invalid non-**NULL** value for the buffer will result in an access violation if the *numberOfElements* parameter is greater than 9. +Passing in an invalid non-`NULL` value for the buffer will result in an access violation if the *`numberOfElements`* parameter is greater than 9. -Passing a value for *numberOfElements* that is greater than the actual size of the buffer will result in buffer overrun. +Passing a value for *`numberOfElements`* that is greater than the actual size of the buffer will result in buffer overrun. ## Remarks -These functions provide more secure versions of [_strtime](strtime-wstrtime.md) and [_wstrtime](strtime-wstrtime.md). The **_strtime_s** function copies the current local time into the buffer pointed to by *timestr*. The time is formatted as **hh:mm:ss** where **hh** is two digits representing the hour in 24-hour notation, **mm** is two digits representing the minutes past the hour, and **ss** is two digits representing seconds. For example, the string **18:23:44** represents 23 minutes and 44 seconds past 6 P.M. The buffer must be at least 9 bytes long; the actual size is specified by the second parameter. +These functions provide more secure versions of [`_strtime`](strtime-wstrtime.md) and [`_wstrtime`](strtime-wstrtime.md). The **`_strtime_s`** function copies the current local time into the buffer pointed to by *`buffer`*. The time is formatted as **hh:mm:ss** where **`hh`** is two digits representing the hour in 24-hour notation, **`mm`** is two digits representing the minutes past the hour, and **`ss`** is two digits representing seconds. For example, the string **18:23:44** represents 23 minutes and 44 seconds after 6 P.M. The buffer must be at least 9 bytes long; the actual size is specified by the second parameter. -**_wstrtime** is a wide-character version of **_strtime**; the argument and return value of **_wstrtime** are wide-character strings. These functions behave identically otherwise. +**`_wstrtime_s`** is a wide-character version of **`_strtime_s`**; the argument and return value of **`_wstrtime_s`** are wide-character strings. These functions behave identically otherwise. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mapping: +### Generic-text routine mapping -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrtime_s**|**_strtime_s**|**_strtime_s**|**_wstrtime_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrtime_s` | **`_strtime_s`** | **`_strtime_s`** | **`_wstrtime_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strtime_s**|\| -|**_wstrtime_s**|\ or \| +| Routine | Required header | +|---|---| +| **`_strtime_s`** | \ | +| **`_wstrtime_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -136,11 +136,11 @@ OS date: 04/25/03 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
-[ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strtime-wstrtime.md b/docs/c-runtime-library/reference/strtime-wstrtime.md index a06657ee51b..a23a103124d 100644 --- a/docs/c-runtime-library/reference/strtime-wstrtime.md +++ b/docs/c-runtime-library/reference/strtime-wstrtime.md @@ -3,16 +3,16 @@ description: "Learn more about: _strtime, _wstrtime" title: "_strtime, _wstrtime" ms.date: "4/2/2020" api_name: ["_wstrtime", "_strtime", "_o__strtime", "_o__wstrtime"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_wstrtime", "_strtime", "wstrtime", "strtime", "_tstrtime"] helpviewer_keywords: ["strtime function", "_strtime function", "_wstrtime function", "copying time to buffers", "wstrtime function", "tstrtime function", "_tstrtime function", "time, copying"] ms.assetid: 9e538161-cf49-44ec-bca5-c0ab0b9e4ca3 --- -# _strtime, _wstrtime +# `_strtime`, `_wstrtime` -Copy the time to a buffer. More secure versions of these functions are available; see [_strtime_s, _wstrtime_s](strtime-s-wstrtime-s.md). +Copy the time to a buffer. More secure versions of these functions are available; see [`_strtime_s`, `_wstrtime_s`](strtime-s-wstrtime-s.md). ## Syntax @@ -35,37 +35,37 @@ wchar_t *_wstrtime( ### Parameters -*timestr*
+*`timestr`*\ Time string. -## Return Value +## Return value -Returns a pointer to the resulting character string *timestr*. +Returns a pointer to the resulting character string *`timestr`*. ## Remarks -The **_strtime** function copies the current local time into the buffer pointed to by *timestr*. The time is formatted as **hh:mm:ss** where **hh** is two digits representing the hour in 24-hour notation, **mm** is two digits representing the minutes past the hour, and **ss** is two digits representing seconds. For example, the string **18:23:44** represents 23 minutes and 44 seconds past 6 P.M. The buffer must be at least 9 bytes long. +The **`_strtime`** function copies the current local time into the buffer pointed to by *`timestr`*. The time is formatted as *`hh:mm:ss`*, where *`hh`* is two digits that represent the hour in 24-hour notation. *`mm`* is two digits for the minutes past the hour, and *`ss`* is two digits for seconds. For example, the string *`18:23:44`* represents 23 minutes and 44 seconds after 6 P.M. The buffer must be at least 9 bytes long. -**_wstrtime** is a wide-character version of **_strtime**; the argument and return value of **_wstrtime** are wide-character strings. These functions behave identically otherwise. If *timestr* is a **NULL** pointer or if *timestr* is formatted incorrectly, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If the exception is allowed to continue, these functions return a **NULL** and set **errno** to **EINVAL** if *timestr* was a **NULL** or set **errno** to **ERANGE** if *timestr* is formatted incorrectly. +**`_wstrtime`** is a wide-character version of **`_strtime`**; the argument and return value of **`_wstrtime`** are wide-character strings. These functions behave identically otherwise. If *`timestr`* is a `NULL` pointer or if *`timestr`* is formatted incorrectly, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If the exception is allowed to continue, these functions return a `NULL`, and set `errno` to `EINVAL` if *`timestr`* was a `NULL` or set `errno` to `ERANGE` if *`timestr`* is formatted incorrectly. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tstrtime**|**_strtime**|**_strtime**|**_wstrtime**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tstrtime` | **`_strtime`** | **`_strtime`** | **`_wstrtime`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strtime**|\| -|**_wstrtime**|\ or \| +| Routine | Required header | +|---|---| +| **`_strtime`** | \ | +| **`_wstrtime`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -91,11 +91,11 @@ The current time is 14:21:44 ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[mktime, _mktime32, _mktime64](mktime-mktime32-mktime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_tzset](tzset.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`mktime`, `_mktime32`, `_mktime64`](mktime-mktime32-mktime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_tzset`](tzset.md) diff --git a/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md b/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md index 0b88999b4b9..568751bf38e 100644 --- a/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md +++ b/docs/c-runtime-library/reference/strtod-strtod-l-wcstod-wcstod-l.md @@ -3,7 +3,7 @@ title: "strtod, _strtod_l, wcstod, _wcstod_l" description: "API reference for strtod, _strtod_l, wcstod, and _wcstod_l; which convert strings to a double-precision value." ms.date: "08/27/2020" api_name: ["wcstod", "_wcstod_l", "_strtod_l", "strtod", "_o__strtod_l", "_o__wcstod_l", "_o_strtod", "_o_wcstod"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcstod", "strtod", "wcstod", "_strtod_l", "_wcstod_l", "stdlib/strtod", "corecrt_wstdlib/wcstod", "stdlib/_strtod_l", "corecrt_wstdlib/_wcstod_l"] @@ -47,33 +47,33 @@ Pointer to character that stops scan. *`locale`*\ The locale to use. -## Return Value +## Return value -**`strtod`** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-**`HUGE_VAL`**. The sign of **`HUGE_VAL`** matches the sign of the value that can't be represented. **`strtod`** returns `0` if no conversion can be performed or an underflow occurs. +**`strtod`** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-`HUGE_VAL`. The sign of `HUGE_VAL` matches the sign of the value that can't be represented. **`strtod`** returns `0` if no conversion can be performed or an underflow occurs. **`wcstod`** returns values analogously to **`strtod`**: -- For both functions, **`errno`** is set to **`ERANGE`** if overflow or underflow occurs. -- If there are invalid parameters, **`errno`** is set to **`EINVAL`** and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +- For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. +- If there are invalid parameters, `errno` is set to `EINVAL` and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -For more information on this and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information on this and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each function converts the input string *`strSource`* to a **`double`**. The **`strtod`** function converts *`strSource`* to a double-precision value. **`strtod`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. This character may be the terminating null character. **`wcstod`** is a wide-character version of **`strtod`**; its *`strSource`* argument is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstod`**|**`strtod`**|**`strtod`**|**`wcstod`**| -|**`_tcstod_l`**|**`_strtod_l`**|**`_strtod_l`**|**`_wcstod_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tcstod`** | **`strtod`** | **`strtod`** | **`wcstod`** | +| **`_tcstod_l`** | **`_strtod_l`** | **`_strtod_l`** | **`_wcstod_l`** | -The **`LC_NUMERIC`** category setting of the current locale determines recognition of the radix point character in *`strSource`*. For more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtod_l`** is identical to **`_strtod`** except the former uses the *`locale`* passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The `LC_NUMERIC` category setting of the current locale determines recognition of the radix point character in *`strSource`*. For more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtod_l`** is identical to **`_strtod`** except the former uses the *`locale`* passed in instead. For more information, see [Locale](../locale.md). -If *`endptr`* isn't **`NULL`**, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. **`strtod`** expects *`strSource`* to point to a string of one of the following forms: @@ -99,16 +99,16 @@ In either form, if there isn't an exponent part or a radix point character, a ra Case is ignored in both the **`INF`** and **`NAN`** forms. The first character that doesn't fit one of these forms stops the scan. -The UCRT versions of these functions don't support conversion of Fortran-style (**`d`** or **`D`**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. The UCRT versions support hexadecimal strings and round-tripping of `INF` and `NAN` values, which weren't supported in earlier versions. This can also cause breaking changes in your code. For example, the string "`0x1a`" would be interpreted by **`strtod`** as 0.0 in previous versions, but as 26.0 in the UCRT version. +The UCRT versions of these functions don't support conversion of Fortran-style (**`d`** or **`D`**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. The UCRT versions support hexadecimal strings and round-tripping of `INF` and `NAN` values, which weren't supported in earlier versions. This support can also cause breaking changes in your code. For example, the string "`0x1a`" would be interpreted by **`strtod`** as 0.0 in previous versions, but as 26.0 in the UCRT version. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strtod`**, **`_strtod_l`**|C: `` C++: `` or `` | -|**`wcstod`**, **`_wcstod_l`**|C: `` or `` C++: ``, ``, or `` | +| Routine | Required header | +|---|---| +| **`strtod`**, **`_strtod_l`** | C: `` C++: `` or `` | +| **`wcstod`**, **`_wcstod_l`** | C: `` or `` C++: ``, ``, or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -203,11 +203,11 @@ No Fortran style support. Stopped parsing at d+49 ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)\ -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ -[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)\ -[Locale](../../c-runtime-library/locale.md)\ -[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)\ +[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ [`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ diff --git a/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md b/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md index 9ee3df1137a..016a7fa54c1 100644 --- a/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md +++ b/docs/c-runtime-library/reference/strtof-strtof-l-wcstof-wcstof-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strtof, _strtof_l, wcstof, _wcstof_l" title: "strtof, _strtof_l, wcstof, _wcstof_l" ms.date: "4/2/2020" api_name: ["_strtof_l", "wcstof", "strtof", "_wcstof_l", "_o__strtof_l", "_o__wcstof_l", "_o_strtof", "_o_wcstof"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["_tcstof", "_tcstof_l", "stdlib/strtof", "strtof", "stdlib/_strtof_l", "_strtof_l", "corecrt_wstdlib/wcstof", "wcstof", "corecrt_wstdlib/_wcstof_l", "_wcstof_l"] helpviewer_keywords: ["_strtof_l function", "_tcstof function", "_wcstof_l function", "wcstof function", "_tcstof_l function", "strtof function"] ms.assetid: 52221b46-876d-4fcc-afb1-97512c17a43b --- -# strtof, _strtof_l, wcstof, _wcstof_l +# `strtof`, `_strtof_l`, `wcstof`, `_wcstof_l` Converts strings to a single-precision floating-point value. @@ -39,56 +39,56 @@ float wcstof_l( ## Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtof** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-**HUGE_VALF**. The sign of **HUGE_VALF** matches the sign of the value that cannot be represented. **strtof** returns 0 if no conversion can be performed or an underflow occurs. +**`strtof`** returns the value of the floating-point number, except when the representation would cause an overflow, in which case the function returns +/-`HUGE_VALF`. The sign of `HUGE_VALF` matches the sign of the value that can't be represented. **`strtof`** returns 0 if no conversion can be performed or an underflow occurs. -**wcstof** returns values analogously to **strtof**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +**`wcstof`** returns values analogously to **`strtof`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each function converts the input string *strSource* to a **`float`**. The **strtof** function converts *strSource* to a single-precision value. **strtof** stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character. **wcstof** is a wide-character version of **strtof**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +Each function converts the input string *`strSource`* to a **`float`**. The **`strtof`** function converts *`strSource`* to a single-precision value. **`strtof`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. This character may be the terminating null character. **`wcstof`** is a wide-character version of **`strtof`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstof**|**strtof**|**strtof**|**wcstof**| -|**_tcstof_l**|**_strtof_l**|**_strtof_l**|**_wcstof_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstof` | **`strtof`** | **`strtof`** | **`wcstof`** | +| `_tcstof_l` | **`_strtof_l`** | **`_strtof_l`** | **`_wcstof_l`** | -The **LC_NUMERIC** category setting of the current locale determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions that don't have the **_l** suffix use the current locale; the ones that have the suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The `LC_NUMERIC` category setting of the current locale determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions that don't have the `_l` suffix use the current locale; the ones that have the suffix are identical except that they use the locale that's passed in instead. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**strtof** expects *strSource* to point to a string of the following form: +**`strtof`** expects *`strSource`* to point to a string of the following form: -[*whitespace*] [*sign*] [*digits*] [__.__*digits*] [{**e** | **E**} [*sign*] *digits*] +[*`whitespace`*] [*`sign`*] [*`digits`*] [.*`digits`*] [{**`e`** | **`E`**} [*`sign`*] *`digits`*] -A *whitespace* may consist of space and tab characters, which are ignored; *sign* is either plus (**+**) or minus (**-**); and *digits* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**e** or **E**) and an optionally signed integer. If neither an exponent part nor a radix character appears, a radix character is assumed to follow the last digit in the string. The first character that does not fit this form stops the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`sign`* is either plus (**`+`**) or minus (**`-`**); and *`digits`* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**`e`** or **`E`**) and an optionally signed integer. If no exponent part or radix character appears, a radix character is assumed to follow the last digit in the string. The first character that doesn't fit this form stops the scan. -The UCRT versions of these functions do not support conversion of Fortran-style (**d** or **D**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. +The UCRT versions of these functions don't support conversion of Fortran-style (**`d`** or **`D`**) exponent letters. This non-standard extension was supported by earlier versions of the CRT, and may be a breaking change for your code. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtof**, **_strtof_l**|C: \ C++: \ or \| -|**wcstof**, **_wcstof_l**|C: \ or \ C++: \, \ or \| +| Routine | Required header | +|---|---| +| **`strtof`**, **`_strtof_l`** | C: \ C++: \ or \ | +| **`wcstof`**, **`_wcstof_l`** | C: \ or \ C++: \, \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -122,15 +122,15 @@ string = 3.14159This stopped it ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Locale](../../c-runtime-library/locale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[localeconv](localeconv.md)
-[_create_locale, _wcreate_locale](create-locale-wcreate-locale.md)
-[_free_locale](free-locale.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`localeconv`](localeconv.md)\ +[`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md)\ +[`_free_locale`](free-locale.md) diff --git a/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md b/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md index fbc9037281a..f53343d45cb 100644 --- a/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md +++ b/docs/c-runtime-library/reference/strtoi64-wcstoi64-strtoi64-l-wcstoi64-l.md @@ -3,7 +3,7 @@ description: "Learn more about: _strtoi64, _wcstoi64, _strtoi64_l, _wcstoi64_l" title: "_strtoi64, _wcstoi64, _strtoi64_l, _wcstoi64_l" ms.date: 05/18/2022 api_name: ["_strtoi64", "_strtoi64_l", "_wcstoi64_l", "_wcstoi64", "_o__strtoi64", "_o__strtoi64_l", "_o__wcstoi64", "_o__wcstoi64_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CRT_OPEN/_strtoi64", "CRT_OPEN/_stroi64_l", "CORECRT_WSTDLIB/_wcstoi64", "CORECRT_WSTDLIB/_wcstoi64_l", "TCHAR/_tcstoi64", "TCHAR/_tcstoi64_l", "_strtoi64", "_stroi64_l", "_wcstoi64", "_wcstoi64_l", "_tcstoi64", "_tcstoi64_l", "strtoi64", "strtoi64_l", "wcstoi64", "wcstoi64_l"] @@ -57,13 +57,13 @@ The locale to use. ## Return value -**`_strtoi64`** returns the value represented in the string *`strSource`*, except when the representation would cause an overflow, in which case it returns **`_I64_MAX`** or **`_I64_MIN`**. The function will return 0 if no conversion can be performed. **`_wcstoi64`** returns values analogously to **`_strtoi64`**. +**`_strtoi64`** returns the value represented in the string *`strSource`*, except when the representation would cause an overflow, in which case it returns `_I64_MAX` or `_I64_MIN`. The function will return 0 if no conversion can be performed. **`_wcstoi64`** returns values analogously to **`_strtoi64`**. -**`_I64_MAX`** and **`_I64_MIN`** are defined in LIMITS.H. +`_I64_MAX` and `_I64_MIN` are defined in LIMITS.H. -If *`strSource`* is **`NULL`** or the *`base`* is nonzero and either less than 2 or greater than 36, **`errno`** is set to **`EINVAL`**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -For more information about return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -73,37 +73,37 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstoi64`**|**`_strtoi64`**|**`_strtoi64`**|**`_wcstoi64`**| -|**`_tcstoi64_l`**|**`_strtoi64_l`**|**`_strtoi64_l`**|**`_wcstoi64_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| ****`_tcstoi64`**** | **`_strtoi64`** | **`_strtoi64`** | **`_wcstoi64`** | +| ****`_tcstoi64_l`**** | **`_strtoi64_l`** | **`_strtoi64_l`** | **`_wcstoi64_l`** | -The locale's **`LC_NUMERIC`** category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtoi64_l`** and **`_wcstoi64_l`** are identical to the corresponding function without the **`_l`** suffix except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtoi64_l`** and **`_wcstoi64_l`** are identical to the corresponding function without the **`_l`** suffix except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -If *`endptr`* isn't **`NULL`**, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. **`_strtoi64`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**`+`** \| **`-`**}] [**`0`** [{ **`x`** \| **`X`** }]] [*digits* \| *letters*] +> [*`whitespace`*] [{**`+`** \| **`-`**}] [**`0`** [{ **`x`** \| **`X`** }]] [*`digits`* \| *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. ## Requirements | Function | Required header | -|--|--| +|---|---| | **`_strtoi64`**, **`_strtoi64_l`** | `` | | **`_wcstoi64`**, **`_wcstoi64_l`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data conversion](../../c-runtime-library/data-conversion.md)\ -[Locale](../../c-runtime-library/locale.md)\ +[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ [`localeconv`](localeconv.md)\ [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ -[String to numeric value functions](../../c-runtime-library/string-to-numeric-value-functions.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ [`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md b/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md index a68383b42a1..288b4dcce83 100644 --- a/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md +++ b/docs/c-runtime-library/reference/strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l" title: "strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l" -ms.date: "11/04/2016" +description: "Learn more about: strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l" +ms.date: 11/04/2016 api_name: ["wcstoimax", "_wcstoimax_l", "_strtoimax_l", "strtoimax"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["wcstoimax", "_tcstoimax", "strtoimax", "_wcstoimax_l", "_strtoimax_l", "_tcstoimax_l"] -helpviewer_keywords: ["strtoimax funciton", "conversion functions", "_strtoimax_l function", "_wcstoimax_l function", "wcstoimax function"] -ms.assetid: 4530d3dc-aaac-4a76-b7cf-29ae3c98d0ae +helpviewer_keywords: ["strtoimax function", "conversion functions", "_strtoimax_l function", "_wcstoimax_l function", "wcstoimax function"] --- -# strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l +# `strtoimax`, `_strtoimax_l`, `wcstoimax`, `_wcstoimax_l` Converts a string to an integer value of the largest supported signed integer type. @@ -43,66 +42,66 @@ intmax_t _wcstoimax_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtoimax** returns the value that's represented in the string *strSource*, except when the representation would cause an overflow—in that case, it returns **INTMAX_MAX** or **INTMAX_MIN**, and **errno** is set to **ERANGE**. The function returns 0 if no conversion can be performed. **wcstoimax** returns values analogously to **strtoimax**. +**`strtoimax`** returns the value that's represented in the string *`strSource`*, except when the representation would cause an overflow—in that case, it returns `INTMAX_MAX` or `INTMAX_MIN`, and `errno` is set to `ERANGE`. The function returns 0 if no conversion can be performed. **`wcstoimax`** returns values analogously to **`strtoimax`**. -**INTMAX_MAX** and **INTMAX_MIN** are defined in stdint.h. +`INTMAX_MAX` and `INTMAX_MIN` are defined in stdint.h. -If *strSource* is **NULL** or the *base* is nonzero and either less than 2 or greater than 36, **errno** is set to **EINVAL**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **strtoimax** function converts *strSource* to an **intmax_t**. The wide-character version of **strtoimax** is **wcstoimax**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. Both functions stop reading the string *strSource* at the first character they cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. +The **`strtoimax`** function converts *`strSource`* to an `intmax_t`. The wide-character version of **`strtoimax`** is **`wcstoimax`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. Both functions stop reading the string *`strSource`* at the first character they can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. -The locale's **LC_NUMERIC** category setting determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions that don't have the **_l** suffix use the current locale; **_strtoimax_l** and **_wcstoimax_l** are identical to the corresponding functions that don't have the **_l** suffix except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions that don't have the `_l` suffix use the current locale; **`_strtoimax_l`** and **`_wcstoimax_l`** are identical to the corresponding functions that don't have the `_l` suffix except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoimax**|**strtoimax**|**strtoimax**|**wcstoimax**| -|**_tcstoimax_l**|**strtoimax_l**|**_strtoimax_l**|**_wcstoimax_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoimax` | **`strtoimax`** | **`strtoimax`** | **`wcstoimax`** | +| `_tcstoimax_l` | **`strtoimax_l`** | **`_strtoimax_l`** | **`_wcstoimax_l`** | -**strtoimax** expects *strSource* to point to a string of the following form: +**`strtoimax`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored; *digits* are one or more decimal digits; *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`digits`* are one or more decimal digits; *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoimax**, **_strtoimax_l**, **wcstoimax**, **_wcstoimax_l**|\| +| Routine | Required header | +|---|---| +| **`strtoimax`**, **`_strtoimax_l`**, **`wcstoimax`**, **`_wcstoimax_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[strtoumax, _strtoumax_l, wcstoumax, _wcstoumax_l](strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`strtoumax`, `_strtoumax_l`, `wcstoumax`, `_wcstoumax_l`](strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md b/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md index 742b04f48d7..4f0db782faf 100644 --- a/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md +++ b/docs/c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md @@ -3,16 +3,16 @@ description: "Learn more about: strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _m title: "strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l" ms.date: "4/2/2020" api_name: ["_wcstok_s_l", "_mbstok_s_l", "_mbstok_s", "strtok_s", "wcstok_s", "_strtok_s_l", "_o__mbstok_s", "_o__mbstok_s_l", "_o_strtok_s", "_o_wcstok_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tcstok_s_l", "_wcstok_s_l", "_tcstok_s", "_mbstok_s_l", "strtok_s", "wcstok_s", "_mbstok_s", "_strtok_s_l"] +f1_keywords: ["STRING/strtok_s", "TCHAR/_strtok_s_l", "MBSTRING/_mbstok_s", "MBSTRING/_mbstok_s_l", "CORECRT_WSTRING/wcstok_s", "TCHAR/_wcstok_s_l", "TCHAR/_tcstok_s", "TCHAR/_tcstok_s_l", "strtok_s", "_strtok_s_l", "_mbstok_s", "_mbstok_s_l", "wcstok_s", "_wcstok_s_l", "_tcstok_s", "_tcstok_s_l"] helpviewer_keywords: ["_strtok_s_l function", "_mbstok_s_l function", "strings [C++], searching", "mbstok_s_l function", "wcstok_s_l function", "_wcstok_s_l function", "_tcstok_s function", "_tcstok_s_l function", "strtok_s_l function", "wcstok_s function", "tokens, finding in strings", "mbstok_s function", "_mbstok_s function", "strtok_s function"] ms.assetid: 7696c972-f83b-4617-8c82-95973e9fdb46 --- # `strtok_s`, `_strtok_s_l`, `wcstok_s`, `_wcstok_s_l`, `_mbstok_s`, `_mbstok_s_l` -Finds the next token in a string, by using the current locale or a locale that's passed in. These versions of [`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Finds the next token in a string, by using the current locale or a locale that's passed in. These versions of [`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > **`_mbstok_s`** and **`_mbstok_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -62,65 +62,65 @@ unsigned char* _mbstok_s_l( ### Parameters -*`str`*
+*`str`*\ A string containing the token or tokens to find. -*`delimiters`*
+*`delimiters`*\ The set of delimiter characters to use. -*`context`*
+*`context`*\ Used to store position information between calls to the function. -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns a pointer to the next token found in *`str`*. Returns **`NULL`** when no more tokens are found. Each call modifies *`str`* by substituting a null character for the first delimiter that occurs after the returned token. +Returns a pointer to the next token found in *`str`*. Returns `NULL` when no more tokens are found. Each call modifies *`str`* by substituting a null character for the first delimiter that occurs after the returned token. -### Error Conditions +### Error conditions -|*`str`*|*`delimiters`*|*`context`*|Return value|**`errno`**| -|----------------|------------------|---------------|------------------|-------------| -|**`NULL`**|any|pointer to a null pointer|**`NULL`**|**`EINVAL`**| -|any|**`NULL`**|any|**`NULL`**|**`EINVAL`**| -|any|any|**`NULL`**|**`NULL`**|**`EINVAL`**| +| *`str`* | *`delimiters`* | *`context`* | Return value | `errno` | +|---|---|---|---|---| +| `NULL` | any | pointer to a null pointer | `NULL` | `EINVAL` | +| any | `NULL` | any | `NULL` | `EINVAL` | +| any | any | `NULL` | `NULL` | `EINVAL` | -If *`str`* is **`NULL`** but *`context`* is a pointer to a valid context pointer, there's no error. +If *`str`* is `NULL` but *`context`* is a pointer to a valid context pointer, there's no error. ## Remarks -The **`strtok_s`** family of functions finds the next token in *`str`*. The set of characters in *`delimiters`* specifies possible delimiters of the token to be found in *`str`* on the current call. **`wcstok_s`** and **`_mbstok_s`** are wide-character and multibyte-character versions of **`strtok_s`**. The arguments and return values of **`wcstok_s`** and **`_wcstok_s_l`** are wide-character strings; those of **`_mbstok_s`** and **`_mbstok_s_l`** are multibyte-character strings. These functions behave identically otherwise. +The **`strtok_s`** family of functions finds the next token in *`str`*. The set of characters in *`delimiters`* specifies possible delimiters of the token to be found in *`str`* on the current call. **`wcstok_s`** and **`_mbstok_s`** are wide-character and multibyte-character versions of **`strtok_s`**. The arguments and return values of **`wcstok_s`** and **`_wcstok_s_l`** are wide-character strings. The arguments and return values of **`_mbstok_s`** and **`_mbstok_s_l`** are multibyte-character strings. These functions behave identically otherwise. -This function validates its parameters. When an error condition occurs, as in the Error Conditions table, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return **`NULL`**. +This function validates its parameters. When an error condition occurs, as in the Error Conditions table, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `NULL`. -On the first call to **`strtok_s`**, the function skips leading delimiters and returns a pointer to the first token in *`str`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`str`* by a series of calls to **`strtok_s`**. Each call to **`strtok_s`** modifies *`str`* by inserting a null character after the token returned by that call. The *`context`* pointer keeps track of which string is being read and where in the string the next token is to be read. To read the next token from *`str`*, call **`strtok_s`** with a **`NULL`** value for the *`str`* argument, and pass the same *`context`* parameter. The **`NULL`** *`str`* argument causes **`strtok_s`** to search for the next token in the modified *`str`*. The *`delimiters`* argument can take any value from one call to the next so that the set of delimiters may vary. +On the first call to **`strtok_s`**, the function skips leading delimiters and returns a pointer to the first token in *`str`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`str`* by a series of calls to **`strtok_s`**. Each call to **`strtok_s`** modifies *`str`* by inserting a null character after the token returned by that call. The *`context`* pointer keeps track of which string is being read and where in the string the next token is to be read. To read the next token from *`str`*, call **`strtok_s`** with a `NULL` value for the *`str`* argument, and pass the same *`context`* parameter. The `NULL` *`str`* argument causes **`strtok_s`** to search for the next token in the modified *`str`*. The *`delimiters`* argument can take any value from one call to the next so that the set of delimiters may vary. Since the *`context`* parameter supersedes the static buffers used in **`strtok`** and **`_strtok_l`**, it's possible to parse two strings simultaneously in the same thread. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). -The versions of these functions without the **`_l`** suffix use the current thread locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they instead use the locale specified by the *`locale`* parameter. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions without the **`_l`** suffix use the current thread locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except they instead use the locale specified by the *`locale`* parameter. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -## Requirements +### Generic-text routine mappings -|Routine|Required header| -|-------------|---------------------| -|**`strtok_s`**|``| -|**`_strtok_s_l`**|``| -|**`wcstok_s`**,
**`_wcstok_s_l`**|`` or ``| -|**`_mbstok_s`**,
**`_mbstok_s_l`**|``| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstok_s` | **`strtok_s`** | **`_mbstok_s`** | **`wcstok_s`** | +| `_tcstok_s_l` | **`_strtok_s_l`** | **`_mbstok_s_l`** | **`_wcstok_s_l`** | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +## Requirements -### Generic-Text Routine Mappings +| Routine | Required header | +|---|---| +| **`strtok_s`** | `` | +| **`_strtok_s_l`** | `` | +| **`wcstok_s`**,
**`_wcstok_s_l`** | `` or `` | +| **`_mbstok_s`**,
**`_mbstok_s_l`** | `` | -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstok_s`**|**`strtok_s`**|**`_mbstok_s`**|**`wcstok_s`**| -|**`_tcstok_s_l`**|**`_strtok_s_l`**|**`_mbstok_s_l`**|**`_wcstok_s_l`**| +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -190,8 +190,8 @@ tokens ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md b/docs/c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md index ee2e7d6a29b..d257087249c 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 @@ -1,14 +1,13 @@ --- -description: "Learn more about: strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l" title: "strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l" -ms.date: "6/24/2020" +description: "Learn more about: strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l" +ms.date: 6/24/2020 api_name: ["_mbstok_l", "_mbstok", "wcstok", "_mbstok", "strtok", "_wcstok_l", "_o__mbstok", "_o__mbstok_l", "_o_strtok", "_o_wcstok"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_mbstok", "strtok", "_tcstok", "wcstok"] +f1_keywords: ["STRING/strtok", "TCHAR/_strtok_l", "MBSTRING/_mbstok", "MBSTRING/_mbstok_l", "CORECRT_WSTRING/wcstok", "TCHAR/_wcstok_l", "TCHAR/_tcstok", "TCHAR/_tcstok_l", "strtok", "strtok_l", "_mbstok", "_mbstok_l", "wcstok", "_wcstok_l", "_tcstok", "_tcstok_l"] helpviewer_keywords: ["mbstok_l function", "strings [C++], searching", "tcstok function", "_tcstok function", "_strtok_l function", "strtok function", "mbstok function", "wcstok_l function", "_mbstok function", "tcstok_l function", "tokens, finding in strings", "_mbstok_l function", "wcstok function", "_wcstok_l function", "_tcstok_l function", "strtok_l function"] -ms.assetid: 904cb734-f0d7-4d77-ba81-4791ddf461ae --- # `strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l` @@ -24,12 +23,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 +37,7 @@ wchar_t *wcstok( const wchar_t *strDelimit, wchar_t **context ); -wchar_t *wcstok_l( +wchar_t *_wcstok_l( wchar_t *strToken, const wchar_t *strDelimit, _locale_t locale @@ -56,59 +55,59 @@ unsigned char *_mbstok_l( ### Parameters -*`strToken`*
+*`strToken`*\ String containing token or tokens. -*`strDelimit`*
+*`strDelimit`*\ Set of delimiter characters. -*`locale`*
+*`locale`*\ Locale to use. -*`context`*
+*`context`*\ Points to memory used to store the internal state of the parser so that the parser can continue from where it left off the next time you call **`wcstok`**. -## Return Value +## Return value -Returns a pointer to the next token found in *`strToken`*. The functions return **`NULL`** when no more tokens are found. Each call modifies *`strToken`* by substituting a null character for the first delimiter that occurs after the returned token. +Returns a pointer to the next token found in *`strToken`*. The functions return `NULL` when no more tokens are found. Each call modifies *`strToken`* by substituting a null character for the first delimiter that occurs after the returned token. ## Remarks -The **`strtok`** function finds the next token in *`strToken`*. The set of characters in *`strDelimit`* specifies possible delimiters of the token to be found in *`strToken`* on the current call. **`wcstok`** and **`_mbstok`** are wide-character and multibyte-character versions of **`strtok`**. The arguments and return value of **`wcstok`** are wide-character strings; those of **`_mbstok`** are multibyte-character strings. These three functions behave identically otherwise. +The **`strtok`** function finds the next token in *`strToken`*. The set of characters in *`strDelimit`* specifies possible delimiters of the token to be found in *`strToken`* on the current call. **`wcstok`** and **`_mbstok`** are wide-character and multibyte-character versions of **`strtok`**. The arguments and return value of **`wcstok`** are wide-character strings. The arguments and return value of **`_mbstok`** are multibyte-character strings. These three functions behave identically otherwise. -The two argument version of **`wcstok`** is not standard. If you need to use that version, you'll need to define `_CRT_NON_CONFORMING_WCSTOK` before you `#include ` (or `#include `). +The two argument version of **`wcstok`** isn't standard. If you need to use that version, you'll need to define `_CRT_NON_CONFORMING_WCSTOK` before you `#include ` (or `#include `). > [!IMPORTANT] -> These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> These functions incur a potential threat brought about by a buffer overrun problem. Buffer overrun problems are a frequent method of system attack, resulting in an unwarranted elevation of privilege. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -On the first call to **`strtok`**, the function skips leading delimiters and returns a pointer to the first token in *`strToken`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`strToken`* by a series of calls to **`strtok`**. Each call to **`strtok`** modifies *`strToken`* by inserting a null character after the **`token`** returned by that call. To read the next token from *`strToken`*, call **`strtok`** with a **`NULL`** value for the *`strToken`* argument. The **`NULL`** *`strToken`* argument causes **`strtok`** to search for the next token in the modified *`strToken`*. The *`strDelimit`* argument can take any value from one call to the next so that the set of delimiters may vary. +On the first call to **`strtok`**, the function skips leading delimiters and returns a pointer to the first token in *`strToken`*, terminating the token with a null character. More tokens can be broken out of the remainder of *`strToken`* by a series of calls to **`strtok`**. Each call to **`strtok`** modifies *`strToken`* by inserting a null character after the **`token`** returned by that call. To read the next token from *`strToken`*, call **`strtok`** with a `NULL` value for the *`strToken`* argument. The `NULL` *`strToken`* argument causes **`strtok`** to search for the next token in the modified *`strToken`*. The *`strDelimit`* argument can take any value from one call to the next so that the set of delimiters may vary. -The output value is affected by the setting of the **`LC_CTYPE`** category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). +The output value is affected by the setting of the `LC_CTYPE` category setting of the locale. For more information, see [`setlocale`](setlocale-wsetlocale.md). -The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The versions of these functions without the **`_l`** suffix use the current locale for this locale-dependent behavior. The versions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead. For more information, see [Locale](../locale.md). > [!NOTE] > Each function uses a thread-local static variable for parsing the string into tokens. Therefore, multiple threads can simultaneously call these functions without undesirable effects. However, within a single thread, interleaving calls to one of these functions is highly likely to produce data corruption and inaccurate results. When parsing different strings, finish parsing one string before starting to parse the next. Also, be aware of the potential for danger when calling one of these functions from within a loop where another function is called. If the other function ends up using one of these functions, an interleaved sequence of calls will result, triggering data corruption. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstok`**|**`strtok`**|**`_mbstok`**|**`wcstok`**| -|**`_tcstok`**|**`_strtok_l`**|**`_mbstok_l`**|**`_wcstok_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstok` | **`strtok`** | **`_mbstok`** | **`wcstok`** | +| `_tcstok` | **`_strtok_l`** | **`_mbstok_l`** | **`_wcstok_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strtok`**|``| -|**`wcstok`**|`` or ``| -|**`_wcstok_l`**|``| -|**`_mbstok`**, **`_mbstok_l`**|``| +| Routine | Required header | +|---|---| +| **`strtok`** | `` | +| **`wcstok`** | `` or `` | +| **`_wcstok_l`** | `` | +| **`_mbstok`**, **`_mbstok_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -158,8 +157,8 @@ tokens ## See also -[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)
-[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md)
+[String manipulation](../string-manipulation-crt.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`strcspn`, `wcscspn`, `_mbscspn`, `_mbscspn_l`](strcspn-wcscspn-mbscspn-mbscspn-l.md)\ +[`strspn`, `wcsspn`, `_mbsspn`, `_mbsspn_l`](strspn-wcsspn-mbsspn-mbsspn-l.md) diff --git a/docs/c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md b/docs/c-runtime-library/reference/strtol-wcstol-strtol-l-wcstol-l.md index 1596d8efa2c..1b097545911 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 @@ -1,12 +1,12 @@ --- -description: "Learn more about: strtol, wcstol, _strtol_l, _wcstol_l" title: "strtol, wcstol, _strtol_l, _wcstol_l" -ms.date: "4/2/2020" +description: "Learn more about: strtol, wcstol, _strtol_l, _wcstol_l" +ms.date: 4/2/2020 api_name: ["strtol", "wcstol", "_strtol_l", "_wcstol_l", "_o__strtol_l", "_o__wcstol_l", "_o_strtol", "_o_wcstol"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_wcstol_l", "strtol", "_tcstol", "wcstol", "_strtol_l", "_tcstol_l"] +f1_keywords: ["STDLIB/strtol", "STDLIB/_strtol_l", "CORECRT_WSTDLIB/wcstol", "CORECRT_WSTDLIB/_wcstol_l", "TCHAR/_tcstol", "TCHAR/_tcstol_l", "strtol", "_strtol_l", "wcstol", "_wcstol_l", "_tcstol", "_tcstol_l"] helpviewer_keywords: ["wcstol function", "wcstol_l function", "_tcstol function", "string conversion, to integers", "tcstol function", "strtol_l function", "_wcstol_l function", "_strtol_l function", "strtol function"] 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] --- @@ -47,7 +47,7 @@ long _wcstol_l( Null-terminated string to convert. *`end_ptr`*\ -An output parameter, set to point to the character after the last interpreted character. Ignored, if **`NULL`**. +An output parameter, set to point to the character after the last interpreted character. Ignored, if `NULL`. *`base`*\ Number base to use. @@ -55,45 +55,45 @@ Number base to use. *`locale`*\ Locale to use. -## Return Value +## Return value -**`strtol`**, **`wcstol`**, **`_strtol_l`**, and **`_wcstol_l`** return the value represented in *`string`*. They return 0 if no conversion is possible. When the representation would cause an overflow, they return **`LONG_MAX`** or **`LONG_MIN`**. +**`strtol`**, **`wcstol`**, **`_strtol_l`**, and **`_wcstol_l`** return the value represented in *`string`*. They return 0 if no conversion is possible. When the representation would cause an overflow, they return `LONG_MAX` or `LONG_MIN`. -**`errno`** is set to **`ERANGE`** if overflow or underflow occurs. It's set to **`EINVAL`** if *`string`* is **`NULL`**. Or, if *`base`* is nonzero and less than 2, or greater than 36. For more information on **`ERANGE`**, **`EINVAL`**, and other return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +`errno` is set to `ERANGE` if overflow or underflow occurs. It's set to `EINVAL` if *`string`* is `NULL`. Or, if *`base`* is nonzero and less than 2, or greater than 36. For more information on `ERANGE`, `EINVAL`, and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks The **`strtol`**, **`wcstol`**, **`_strtol_l`**, and **`_wcstol_l`** functions convert *`string`* to a **`long`**. They stop reading *`string`* at the first character not recognized as part of a number. It may be the terminating-null character, or the first alphanumeric character greater than or equal to *`base`*. -**`wcstol`** and **`_wcstol_l`** are wide-character versions of **`strtol`** and **`_strtol_l`**. Their *`string`* argument is a wide-character string. These functions behave identically to **`strtol`** and **`_strtol_l`** otherwise. The locale's **`LC_NUMERIC`** category setting determines recognition of the radix character (the fractional marker or decimal point) in *`string`*. The functions **`strtol`** and **`wcstol`** use the current locale. **`_strtol_l`** and **`_wcstol_l`** use the locale passed in instead. For more information, see [`setlocale`] and [Locale](../../c-runtime-library/locale.md). +**`wcstol`** and **`_wcstol_l`** are wide-character versions of **`strtol`** and **`_strtol_l`**. Their *`string`* argument is a wide-character string. These functions behave identically to **`strtol`** and **`_strtol_l`** otherwise. The locale's `LC_NUMERIC` category setting determines recognition of the radix character (the fractional marker or decimal point) in *`string`*. The functions **`strtol`** and **`wcstol`** use the current locale. **`_strtol_l`** and **`_wcstol_l`** use the locale passed in instead. For more information, see [`setlocale`](setlocale-wsetlocale.md) and [Locale](../locale.md). -When *`end_ptr`* is **`NULL`**, it's ignored. Otherwise, a pointer to the character that stopped the scan is stored at the location pointed to by *`end_ptr`*. No conversion is possible if no valid digits are found, or an invalid base is specified. The value of *`string`* is then stored at the location pointed to by *`end_ptr`*. +When *`end_ptr`* is `NULL`, it's ignored. Otherwise, a pointer to the character that stopped the scan is stored at the location pointed to by *`end_ptr`*. No conversion is possible if no valid digits are found, or an invalid base is specified. The value of *`string`* is then stored at the location pointed to by *`end_ptr`*. **`strtol`** expects *`string`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*alphanumerics*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`alphanumerics`*] -Square brackets (`[ ]`) surround optional elements. Curly braces and a vertical bar (`{ | }`) surround alternatives for a single element. *whitespace* may consist of space and tab characters, which are ignored. *alphanumerics* are decimal digits or the letters `'a'` through `'z'` (or `'A'` through `'Z'`). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is `0`, the initial characters of the string pointed to by *`string`* are used to determine the base. If the first character is `0`, and the second character isn't `'x'` or `'X'`, the string is interpreted as an octal integer. If the first character is `'0'` and the second character is `'x'` or `'X'`, the string is interpreted as a hexadecimal integer. If the first character is `'1'` through `'9'`, the string is interpreted as a decimal integer. The letters `'a'` through `'z'` (or `'A'` through `'Z'`) are assigned the values 10 through 35. The scan only allows letters whose values are less than *`base`*. The first character outside the range of the base stops the scan. For example, suppose *`string`* starts with `"01"`. If *`base`* is `0`, the scanner assumes it's an octal integer. An `'8'` or `'9'` character stops the scan. +Square brackets (`[ ]`) surround optional elements. Curly braces and a vertical bar (`{ | }`) surround alternatives for a single element. *`whitespace`* may consist of space and tab characters, which are ignored. *`alphanumerics`* are decimal digits or the letters `'a'` through `'z'` (or `'A'` through `'Z'`). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is `0`, the initial characters of the string pointed to by *`string`* are used to determine the base. If the first character is `0`, and the second character isn't `'x'` or `'X'`, the string is interpreted as an octal integer. If the first character is `'0'` and the second character is `'x'` or `'X'`, the string is interpreted as a hexadecimal integer. If the first character is `'1'` through `'9'`, the string is interpreted as a decimal integer. The letters `'a'` through `'z'` (or `'A'` through `'Z'`) are assigned the values 10 through 35. The scan only allows letters whose values are less than *`base`*. The first character outside the range of the base stops the scan. For example, suppose *`string`* starts with `"01"`. If *`base`* is `0`, the scanner assumes it's an octal integer. An `'8'` or `'9'` character stops the scan. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstol`**|**`strtol`**|**`strtol`**|**`wcstol`**| -|**`_tcstol_l`**|**`_strtol_l`**|**`_strtol_l`**|**`_wcstol_l`**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstol` | **`strtol`** | **`strtol`** | **`wcstol`** | +| `_tcstol_l` | **`_strtol_l`** | **`_strtol_l`** | **`_wcstol_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strtol`**|``| -|**`wcstol`**|`` or ``| -|**`_strtol_l`**|``| -|**`_wcstol_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`strtol`** | `` | +| **`wcstol`** | `` or `` | +| **`_strtol_l`** | `` | +| **`_wcstol_l`** | `` or `` | -The **`_strtol_l`** and **`_wcstol_l`** functions are Microsoft-specific, not part of the Standard C library. For additional compatibility information, see [Compatibility](../compatibility.md). +The **`_strtol_l`** and **`_wcstol_l`** functions are Microsoft-specific, not part of the Standard C library. For more compatibility information, see [Compatibility](../compatibility.md). ## Example 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 76d35f88357..e24182d5b59 100644 --- a/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md +++ b/docs/c-runtime-library/reference/strtold-strtold-l-wcstold-wcstold-l.md @@ -3,13 +3,13 @@ description: "Learn more about: strtold, _strtold_l, wcstold, _wcstold_l" title: "strtold, _strtold_l, wcstold, _wcstold_l" ms.date: "4/2/2020" api_name: ["wcstold", "strtold", "_strtold_l", "_wcstold_l", "_o__strtold_l", "_o__wcstold_l", "_o_strtold", "_o_wcstold"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tcstold_l", "_wcstold_l", "_tcstold", "strtold", "_strtold_l", "wcstold"] +f1_keywords: ["STDLIB/strtold", "STDLIB/_strtold_l", "CORECRT_WSTDLIB/wcstold", "CORECRT_WSTDLIB/_wcstold_l", "TCHAR/_tcstold", "TCHAR/_tcstold_l", "strtold", "_strtold_l", "wcstold", "_wcstold_l", "_tcstold", "_tcstold_l"] ms.assetid: 928c0c9a-bc49-445b-8822-100eb5954115 --- -# strtold, _strtold_l, wcstold, _wcstold_l +# `strtold`, `_strtold_l`, `wcstold`, `_wcstold_l` Converts strings to a long double-precision floating-point value. @@ -38,54 +38,54 @@ long double wcstold_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtold** returns the value of the floating-point number as a **`long double`**, except when the representation would cause an overflow—in that case, the function returns +/-**HUGE_VALL**. The sign of **HUGE_VALL** matches the sign of the value that cannot be represented. **strtold** returns 0 if no conversion can be performed or an underflow occurs. +**`strtold`** returns the value of the floating-point number as a **`long double`**, except when the representation would cause an overflow—in that case, the function returns +/-`HUGE_VALL`. The sign of `HUGE_VALL` matches the sign of the value that can't be represented. **`strtold`** returns 0 if no conversion can be performed or an underflow occurs. -**wcstold** returns values analogously to **strtold**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +**`wcstold`** returns values analogously to **`strtold`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each function converts the input string *strSource* to a **`long double`**. The **strtold** function stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character. The wide-character version of **strtold** is **wcstold**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +Each function converts the input string *`strSource`* to a **`long double`**. The **`strtold`** function stops reading the string *`strSource`* at the first character it can't recognize as part of a number. It may be the terminating null character. The wide-character version of **`strtold`** is **`wcstold`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstold**|**strtold**|**strtold**|**wcstold**| -|**_tcstold_l**|**_strtold_l**|**_strtold_l**|**_wcstold_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstold` | **`strtold`** | **`strtold`** | **`wcstold`** | +| `_tcstold_l` | **`_strtold_l`** | **`_strtold_l`** | **`_wcstold_l`** | -The **LC_NUMERIC** category setting of the current locale determines the recognition of the radix character in *strSource*. For more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions without the **_l** suffix use the current locale; **_strtold_l** and **_wcstold_l** are identical to **_strtold** and **_wcstold** except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The `LC_NUMERIC` category setting of the current locale determines the recognition of the radix character in *`strSource`*. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions without the `_l` suffix use the current locale; **`_strtold_l`** and **`_wcstold_l`** are identical to **`_strtold`** and **`_wcstold`** except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**strtold** expects *strSource* to point to a string of the following form: +**`strtold`** expects *`strSource`* to point to a string of the following form: -[*whitespace*] [*sign*] [*digits*] [.*digits*] [ {**d** | **D** | **e** | **E**}[*sign*]*digits*] +> \[*`whitespace`*\]\[*`sign`*\]\[*`digits`*\]\[.*`digits`*\]\[{**`d`** | **`D`** | **`e`** | **`E`**}\[*`sign`*\]*`digits`*\] -A *whitespace* may consist of space and tab characters, which are ignored; *sign* is either plus (**+**) or minus (**-**); and *digits* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**d**, **D**, **e**, or **E**) and an optionally signed integer. If neither an exponent part nor a radix character appears, a radix character is assumed to follow the last digit in the string. The first character that does not fit this form stops the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`sign`* is either plus (**`+`**) or minus (**`-`**); and *`digits`* are one or more decimal digits. If no digits appear before the radix character, at least one must appear after the radix character. The decimal digits can be followed by an exponent, which consists of an introductory letter (**`d`**, **`D`**, **`e`**, or **`E`**) and an optionally signed integer. If no exponent part or radix character appears, a radix character is assumed to follow the last digit in the string. The first character that doesn't fit this form stops the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtold**, **_strtold_l**|\| -|**wcstold**, **_wcstold_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtold`**, **`_strtold_l`** | \ | +| **`wcstold`**, **`_wcstold_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -120,15 +120,15 @@ string = 3.1415926535898This stopped it ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[Locale](../../c-runtime-library/locale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
-[localeconv](localeconv.md)
-[_create_locale, _wcreate_locale](create-locale-wcreate-locale.md)
-[_free_locale](free-locale.md)
+[Data conversion](../data-conversion.md)\ +[Math and floating-point support](../floating-point-support.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[Locale](../locale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md)\ +[`localeconv`](localeconv.md)\ +[`_create_locale`, `_wcreate_locale`](create-locale-wcreate-locale.md)\ +[`_free_locale`](free-locale.md) diff --git a/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md b/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md index 925f54ad33d..0460b9509da 100644 --- a/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md +++ b/docs/c-runtime-library/reference/strtoll-strtoll-l-wcstoll-wcstoll-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strtoll, _strtoll_l, wcstoll, _wcstoll_l" title: "strtoll, _strtoll_l, wcstoll, _wcstoll_l" ms.date: "4/2/2020" api_name: ["strtoll", "wcstoll", "_strtoll_l", "_wcstoll_l", "_o__strtoll_l", "_o__wcstoll_l", "_o_strtoll", "_o_wcstoll"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_strtoll_l", "_tcstoll_l", "_tcstoll", "_wcstoll_l", "strtoll", "wcstoll"] +f1_keywords: ["STDLIB/strtoll", "STDLIB/_strtoll_l", "CORECRT_WSTDLIB/wcstoll", "CORECRT_WSTDLIB/_wcstoll_l", "TCHAR/_tcstoll", "TCHAR/_tcstoll_l", "strtoll", "_strtoll_l", "wcstoll", "_wcstoll_l", "_tcstoll", "_tcstoll_l"] helpviewer_keywords: ["_tcstoll_l function", "_wcstoll_l function", "strtoll function", "wcstoll function", "_tcstoll function", "_strtoll_l function"] ms.assetid: e2d05dcf-d3b2-4291-9e60-dee77e540fd7 --- -# strtoll, _strtoll_l, wcstoll, _wcstoll_l +# `strtoll`, `_strtoll_l`, `wcstoll`, `_wcstoll_l` Converts a string to a **`long long`** value. @@ -43,68 +43,68 @@ long long _wcstoll_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**strtoll** returns the value that's represented in the string *strSource*, except when the representation would cause an overflow—in that case, it returns **LLONG_MAX** or **LLONG_MIN**. The function returns 0 if no conversion can be performed. **wcstoll** returns values analogously to **strtoll**. +**`strtoll`** returns the value that's represented in the string *`strSource`*, except when the representation would cause an overflow—in that case, it returns `LLONG_MAX` or `LLONG_MIN`. The function returns 0 if no conversion can be performed. **`wcstoll`** returns values analogously to **`strtoll`**. -**LLONG_MAX** and **LLONG_MIN** are defined in LIMITS.H. +`LLONG_MAX` and `LLONG_MIN` are defined in LIMITS.H. -If *strSource* is **NULL** or the *base* is nonzero and either less than 2 or greater than 36, **errno** is set to **EINVAL**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **strtoll** function converts *strSource* to a **`long long`**. Both functions stop reading the string *strSource* at the first character they cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. **wcstoll** is a wide-character version of **strtoll**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +The **`strtoll`** function converts *`strSource`* to a **`long long`**. Both functions stop reading the string *`strSource`* at the first character they can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. **`wcstoll`** is a wide-character version of **`strtoll`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoll**|**strtoll**|**strtoll**|**wcstoll**| -|**_tcstoll_l**|**_strtoll_l**|**_strtoll_l**|**_wcstoll_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoll` | **`strtoll`** | **`strtoll`** | **`wcstoll`** | +| `_tcstoll_l` | **`_strtoll_l`** | **`_strtoll_l`** | **`_wcstoll_l`** | -The locale's **LC_NUMERIC** category setting determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). The functions that don't have the **_l** suffix use the current locale; **_strtoll_l** and **_wcstoll_l** are identical to the corresponding functions that don't have the suffix, except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +The locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). The functions that don't have the `_l` suffix use the current locale; **`_strtoll_l`** and **`_wcstoll_l`** are identical to the corresponding functions that don't have the suffix, except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**strtoll** expects *strSource* to point to a string of the following form: +**`strtoll`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored; *digits* are one or more decimal digits; *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string that's pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored; *`digits`* are one or more decimal digits; *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string that's pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoll**, **_strtoll_l**|\| -|**wcstoll**, **_wcstoll_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtoll`**, **`_strtoll_l`** | \ | +| **`wcstoll`**, **`_wcstoll_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md b/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md index 3f0cedf5adf..bc63db4b838 100644 --- a/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md +++ b/docs/c-runtime-library/reference/strtoui64-wcstoui64-strtoui64-l-wcstoui64-l.md @@ -3,10 +3,10 @@ description: "Learn more about: _strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64 title: "_strtoui64, _wcstoui64, _strtoui64_l, _wcstoui64_l" ms.date: 05/18/2022 api_name: ["_strtoui64", "_strtoui64_l", "_wcstoui64", "_wcstoui64_l", "_o__strtoui64", "_o__strtoui64_l", "_o__wcstoui64", "_o__wcstoui64_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["CRT_OPEN/_strtoui64", "CRT_OPEN/_strtoui64_l", "CORECRT_WSTDLIB/_wcstoui64", "CORECRT_WSTDLIB/_wcstoui64_l", "TCHAR/_tcstoui64", "TCHAR_tcstoui64_l", "_strtoui64", "_strtoui64_l", "_wcstoui64", "_wcstoui64_l", "_tcstoui64", "_tcstoui64_l", "strtoui64", "strtoui64_l", "wcstoui64", "wcstoui64_l"] +f1_keywords: ["CRT_OPEN/_strtoui64", "CRT_OPEN/_strtoui64_l", "STDLIB/_strtoui64", "STDLIB/_strtoui64_l", "CORECRT_WSTDLIB/_wcstoui64", "CORECRT_WSTDLIB/_wcstoui64_l", "TCHAR/_tcstoui64", "TCHAR/_tcstoui64_l", "_strtoui64", "_strtoui64_l", "_wcstoui64", "_wcstoui64_l", "_tcstoui64", "_tcstoui64_l", "strtoui64", "strtoui64_l", "wcstoui64", "wcstoui64_l"] helpviewer_keywords: ["_strtoui64_l function", "_wcstoui64_l function", "string conversion, to integers", "wcstoui64_l function", "_strtoui64 function", "_wcstoui64 function", "wcstoui64 function", "strtoui64_l function", "strtoui64 function"] ms.assetid: 7fcb537e-4554-4ceb-a5b6-bc09244e72ef --- @@ -33,7 +33,7 @@ unsigned __int64 _strtoui64_l( int base, _locale_t locale ); -unsigned __int64 _wcstoui64( +unsigned __int64 _wcstoui64_l( const wchar_t *strSource, wchar_t **endptr, int base, @@ -57,13 +57,13 @@ Locale to use. ## Return value -**`_strtoui64`** returns the value represented in the string *`strSource`*, except when the representation would cause an overflow, in which case it returns **`_UI64_MAX`**. **`_strtoui64`** returns 0 if no conversion can be performed. +**`_strtoui64`** returns the value represented in the string *`strSource`*, except when the representation would cause an overflow, in which case it returns `_UI64_MAX`. **`_strtoui64`** returns 0 if no conversion can be performed. -**`_UI64_MAX`** is defined in `LIMITS.H`. +`_UI64_MAX` is defined in `LIMITS.H`. -If *`strSource`* is **`NULL`** or the *`base`* is nonzero and either less than 2 or greater than 36, **`errno`** is set to **`EINVAL`**. +If *`strSource`* is `NULL` or the *`base`* is nonzero and either less than 2 or greater than 36, `errno` is set to `EINVAL`. -For more information on return codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information on return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -75,20 +75,20 @@ By default, this function's global state is scoped to the application. To change ### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstoui64`**|**`_strtoui64`**|**`_strtoui64`**|**`_wcstoui64`**| -|**`_tcstoui64_l`**|**`_strtoui64_l`**|**`_strtoui64_l`**|**`_wcstoui64_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoui64` | **`_strtoui64`** | **`_strtoui64`** | **`_wcstoui64`** | +| `_tcstoui64_l` | **`_strtoui64_l`** | **`_strtoui64_l`** | **`_wcstoui64_l`** | -The current locale's **`LC_NUMERIC`** category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtoui64_l`** and **`_wcstoui64_l`** are identical to the corresponding functions without the **`_l`** suffix except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The current locale's `LC_NUMERIC` category setting determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). The functions without the **`_l`** suffix use the current locale; **`_strtoui64_l`** and **`_wcstoui64_l`** are identical to the corresponding functions without the **`_l`** suffix except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -If *`endptr`* isn't **`NULL`**, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. **`_strtoui64`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**`+`** \| **`-`**}] [**`0`** [{ **`x`** \| **`X`** }]] [*digits* \| *letters*] +> [*`whitespace`*] [{**`+`** \| **`-`**}] [**`0`** [{ **`x`** \| **`X`** }]] [*`digits`* \| *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character will stop the scan. ## Requirements @@ -99,7 +99,7 @@ A *whitespace* may consist of space and tab characters, which are ignored. *digi | **`_strtoui64_l`** | `` | | **`_wcstoui64_l`** | `` or `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -123,11 +123,11 @@ u = 18446744073709551615 ## See also -[Data conversion](../../c-runtime-library/data-conversion.md)\ -[Locale](../../c-runtime-library/locale.md)\ +[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ [`localeconv`](localeconv.md)\ [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ -[String to numeric value functions](../../c-runtime-library/string-to-numeric-value-functions.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ [`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ [`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md b/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md index f7d5b03c8bb..7584413c40c 100644 --- a/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md +++ b/docs/c-runtime-library/reference/strtoul-strtoul-l-wcstoul-wcstoul-l.md @@ -3,10 +3,10 @@ description: "Learn more about: strtoul, _strtoul_l, wcstoul, _wcstoul_l" title: "strtoul, _strtoul_l, wcstoul, _wcstoul_l" ms.date: "4/2/2020" api_name: ["_wcstoul_l", "_strtoul_l", "strtoul", "wcstoul", "_o__strtoul_l", "_o__wcstoul_l", "_o_strtoul", "_o_wcstoul"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strtoul", "_tcstoul", "wcstoul"] +f1_keywords: ["STDLIB/strtoul", "STDLIB/_strtoul_l", "CORECRT_WSTDLIB/wcstoul", "CORECRT_WSTDLIB/_wcstoul_l", "TCHAR/_tcstoul", "TCHAR/_tcstoul_l", "strtoul", "_strtoul_l", "wcstoul", "_wcstoul_l", "_tcstoul", "_tcstoul_l"] helpviewer_keywords: ["_wcstoul_l function", "_tcstoul function", "_strtoul_l function", "string conversion, to integers", "wcstoul function", "strtoul function", "wcstoul_l function", "strtoul_l function", "tcstoul function"] --- # `strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l` @@ -54,30 +54,30 @@ Number base to use. *`locale`*\ Locale to use. -## Return Value +## Return value -**`strtoul`** returns the converted value, if any, or **`ULONG_MAX`** on overflow. **`strtoul`** returns 0 if no conversion can be performed. **`wcstoul`** returns values analogously to **`strtoul`**. For both functions, **`errno`** is set to **`ERANGE`** if overflow or underflow occurs. +**`strtoul`** returns the converted value, if any, or `ULONG_MAX` on overflow. **`strtoul`** returns 0 if no conversion can be performed. **`wcstoul`** returns values analogously to **`strtoul`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks Each of these functions converts the input string *`strSource`* to an **`unsigned long`**. -**`strtoul`** stops reading the string *`strSource`* at the first character it can’t recognize as part of a number. This may be the terminating `NULL` character, or it may be the first numeric character greater than or equal to *`base`*. The **`LC_NUMERIC`** category setting of the locale determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). **`strtoul`** and **`wcstoul`** use the current locale; **`_strtoul_l`** and **`_wcstoul_l`** are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`strtoul`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. This character may be the terminating `NULL`, or it may be the first numeric character greater than or equal to *`base`*. The `LC_NUMERIC` category setting of the locale determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`](setlocale-wsetlocale.md). **`strtoul`** and **`wcstoul`** use the current locale; **`_strtoul_l`** and **`_wcstoul_l`** are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -If *`endptr`* isn't **`NULL`**, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location pointed to by *`endptr`*. **`wcstoul`** is a wide-character version of **`strtoul`**; its *`strSource`* argument is a wide-character string. Otherwise these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tcstoul`**|**`strtoul`**|**`strtoul`**|**`wcstoul`**| -|**`_tcstoul_l`**|**`strtoul_l`**|**`_strtoul_l`**|**`_wcstoul_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoul` | **`strtoul`** | **`strtoul`** | **`wcstoul`** | +| `_tcstoul_l` | **`strtoul_l`** | **`_strtoul_l`** | **`_wcstoul_l`** | **`strtoul`** expects *`strSource`* to point to a string of the following form: @@ -87,14 +87,14 @@ A *`whitespace`* may consist of space and tab characters, which are ignored. *`d ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`strtoul`**|``| -|**`wcstoul`**|`` or ``| -|**`_strtoul_l`**|``| -|**`_wcstoul_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`strtoul`** | `` | +| **`wcstoul`** | `` or `` | +| **`_strtoul_l`** | `` | +| **`_wcstoul_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -102,11 +102,11 @@ See the example for [`strtod`](strtod-strtod-l-wcstod-wcstod-l.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)\ -[Locale](../../c-runtime-library/locale.md)\ +[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ [`localeconv`](localeconv.md)\ [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ -[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ [`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ [`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ [`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md b/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md index 09adf3a924e..58bde7c9013 100644 --- a/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md +++ b/docs/c-runtime-library/reference/strtoull-strtoull-l-wcstoull-wcstoull-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strtoull, _strtoull_l, wcstoull, _wcstoull_l" title: "strtoull, _strtoull_l, wcstoull, _wcstoull_l" ms.date: "4/2/2020" api_name: ["_strtoull_l", "_wcstoull_l", "strtoull", "wcstoull", "_o__strtoull_l", "_o__wcstoull_l", "_o_strtoull", "_o_wcstoull"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_wcstoull_l", "_tcstoull", "_tcstoull_l", "wcstoull", "_strtoull_l", "strtoull"] +f1_keywords: ["STDLIB/strtoull", "STDLIB/_strtoull_l", "CORECRT_WSTDLIB/wcstoull", "CORECRT_WSTDLIB/_wcstoull_l", "TCHAR/_tcstoull", "TCHAR/_tcstoull_l", "strtoull", "_strtoull_l", "wcstoull", "_wcstoull_l", "_tcstoull", "_tcstoull_l"] helpviewer_keywords: ["strtoull function", "_tcstoull_l function", "_tcstoull function", "_wcstoull_l function", "_strtoull_l function", "wcstoull function"] ms.assetid: 36dac1cc-e901-40a0-8802-63562d6d01df --- -# strtoull, _strtoull_l, wcstoull, _wcstoull_l +# `strtoull`, `_strtoull_l`, `wcstoull`, `_wcstoull_l` Converts strings to an **`unsigned long long`** integer value. @@ -43,73 +43,73 @@ unsigned long long _wcstoull_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**strtoull** returns the converted value, if any, or **ULLONG_MAX** on overflow. **strtoull** returns 0 if no conversion can be performed. **wcstoull** returns values analogously to **strtoull**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs. +**`strtoull`** returns the converted value, if any, or `ULLONG_MAX` on overflow. **`strtoull`** returns 0 if no conversion can be performed. **`wcstoull`** returns values analogously to **`strtoull`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions converts the input string *strSource* to an **`unsigned long long`** integer value. +Each of these functions converts the input string *`strSource`* to an **`unsigned long long`** integer value. -**strtoull** stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. The setting of the **LC_NUMERIC** category of the locale determines recognition of the radix character in *strSource*; for more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). **strtoull** and **wcstoull** use the current locale; **_strtoull_l** and **_wcstoull_l** instead use the locale that's passed in but are identical otherwise. For more information, see [Locale](../../c-runtime-library/locale.md). +**`strtoull`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. The setting of the `LC_NUMERIC` category of the locale determines recognition of the radix character in *`strSource`*; for more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). **`strtoull`** and **`wcstoull`** use the current locale; **`_strtoull_l`** and **`_wcstoull_l`** instead use the locale that's passed in but are identical otherwise. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -**wcstoull** is a wide-character version of **strtoull** and its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +**`wcstoull`** is a wide-character version of **`strtoull`** and its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoull**|**strtoull**|**strtoull**|**wcstoull**| -|**_tcstoull_l**|**strtoull_l**|**_strtoull_l**|**_wcstoull_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoull` | **`strtoull`** | **`strtoull`** | **`wcstoull`** | +| `_tcstoull_l` | **`strtoull_l`** | **`_strtoull_l`** | **`_wcstoull_l`** | -**strtoull** expects *strSource* to point to a string of the following form: +**`strtoull`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string that's pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. **strtoull** allows a plus sign (**+**) or minus sign (**-**) prefix; a leading minus sign indicates that the return value is negated. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string that's pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character stops the scan. **`strtoull`** allows a plus sign (**`+`**) or minus sign (**`-`**) prefix; a leading minus sign indicates that the return value is negated. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoull**|\| -|**wcstoull**|\ or \| -|**_strtoull_l**|\| -|**_wcstoull_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtoull`** | \ | +| **`wcstoull`** | \ or \ | +| **`_strtoull_l`** | \ | +| **`_wcstoull_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strtod](strtod-strtod-l-wcstod-wcstod-l.md). +See the example for [`strtod`](strtod-strtod-l-wcstod-wcstod-l.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[strtoll, _strtoll_l, wcstoll, _wcstoll_l](strtoll-strtoll-l-wcstoll-wcstoll-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`strtoll`, `_strtoll_l`, `wcstoll`, `_wcstoll_l`](strtoll-strtoll-l-wcstoll-wcstoll-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md b/docs/c-runtime-library/reference/strtoumax-strtoumax-l-wcstoumax-wcstoumax-l.md index 06c20c89c19..e43cfdbd12d 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 @@ -1,16 +1,15 @@ --- -description: "Learn more about: strtoumax, _strtoumax_l, wcstoumax, _wcstoumax_l" title: "strtoumax, _strtoumax_l, wcstoumax, _wcstoumax_l" -ms.date: "11/04/2016" +description: "Learn more about: strtoumax, _strtoumax_l, wcstoumax, _wcstoumax_l" +ms.date: 11/04/2016 api_name: ["_wcstoumax_l", "_strtoumax_l", "wcstoumax", "strtoumax"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcstoumax", "_tcstoumax", "_strtoumax_l", "_wcstoumax_l", "_tcstoumax_l", "strtoumax"] +f1_keywords: ["INTTYPES/strtoumax", "INTTYPES/_strtoumax_l", "INTTYPES/wcstoumax", "INTTYPES/_wcstoumax_l", "TCHAR/_tcstoumax", "TCHAR/_tcstoumax_l", "strtoumax", "_strtoumax_l", "wcstoumax", "_wcstoumax_l", "_tcstoumax", "_tcstoumax_l"] helpviewer_keywords: ["_strtoumax_l function", "conversion functions", "wcstoumax function", "_wcstoumax_l function", "strtoumax function"] -ms.assetid: 566769f9-495b-4508-b9c6-02217a578897 --- -# strtoumax, _strtoumax_l, wcstoumax, _wcstoumax_l +# `strtoumax`, `_strtoumax_l`, `wcstoumax`, `_wcstoumax_l` Converts strings to an integer value of the largest supported unsigned integer type. @@ -43,72 +42,69 @@ uintmax_t _wcstoumax_l( ### Parameters -*strSource*
+*`strSource`*\ Null-terminated string to convert. -*endptr*
+*`endptr`*\ Pointer to the character that stops the scan. -*base*
+*`base`*\ Number base to use. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -**strtoumax** returns the converted value, if any, or **UINTMAX_MAX** on overflow. **strtoumax** returns 0 if no conversion can be performed. **wcstoumax** returns values analogously to **strtoumax**. For both functions, **errno** is set to **ERANGE** if overflow or underflow occurs. +**`strtoumax`** returns the converted value, if any, or `UINTMAX_MAX` on overflow. **`strtoumax`** returns 0 if no conversion can be performed. **`wcstoumax`** returns values analogously to **`strtoumax`**. For both functions, `errno` is set to `ERANGE` if overflow or underflow occurs. -For more information about return codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions converts the input string *strSource* to a **uintmax_t** integer value. +Each of these functions converts the input string *`strSource`* to a `uintmax_t` integer value. -**strtoumax** stops reading the string *strSource* at the first character it cannot recognize as part of a number. This may be the terminating null character, or it may be the first numeric character that's greater than or equal to *base*. The **LC_NUMERIC** category setting of the locale determines the recognition of the radix character in *strSource*. For more information, see [setlocale, _wsetlocale](setlocale-wsetlocale.md). **strtoumax** and **wcstoumax** use the current locale; **_strtoumax_l** and **_wcstoumax_l** are identical except that they instead use the locale that's passed in. For more information, see [Locale](../../c-runtime-library/locale.md). +**`strtoumax`** stops reading the string *`strSource`* at the first character it can't recognize as part of a number. It may be the terminating null character, or it may be the first numeric character that's greater than or equal to *`base`*. The `LC_NUMERIC` category setting of the locale determines the recognition of the radix character in *`strSource`*. For more information, see [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md). **`strtoumax`** and **`wcstoumax`** use the current locale; **`_strtoumax_l`** and **`_wcstoumax_l`** are identical except that they instead use the locale that's passed in. For more information, see [Locale](../locale.md). -If *endptr* is not **NULL**, a pointer to the character that stopped the scan is stored at the location that's pointed to by *endptr*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *strSource* is stored at the location that's pointed to by *endptr*. +If *`endptr`* isn't `NULL`, a pointer to the character that stopped the scan is stored at the location that's pointed to by *`endptr`*. If no conversion can be performed (no valid digits were found or an invalid base was specified), the value of *`strSource`* is stored at the location that's pointed to by *`endptr`*. -The wide-character version of **strtoumax** is **wcstoumax**; its *strSource* argument is a wide-character string. Otherwise, these functions behave identically. +The wide-character version of **`strtoumax`** is **`wcstoumax`**; its *`strSource`* argument is a wide-character string. Otherwise, these functions behave identically. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcstoumax**|**strtoumax**|**strtoumax**|**wcstoumax**| -|**_tcstoumax_l**|**strtoumax_l**|**_strtoumax_l**|**_wcstoumax_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcstoumax` | **`strtoumax`** | **`strtoumax`** | **`wcstoumax`** | +| `_tcstoumax_l` | **`strtoumax_l`** | **`_strtoumax_l`** | **`_wcstoumax_l`** | -**strtoumax** expects *strSource* to point to a string of the following form: +**`strtoumax`** expects *`strSource`* to point to a string of the following form: -> [*whitespace*] [{**+** | **-**}] [**0** [{ **x** | **X** }]] [*digits* | *letters*] +> [*`whitespace`*] [{**`+`** | **`-`**}] [**`0`** [{ **`x`** | **`X`** }]] [*`digits`* | *`letters`*] -A *whitespace* may consist of space and tab characters, which are ignored. *digits* are one or more decimal digits. *letters* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that does not fit this form stops the scan. If *base* is between 2 and 36, then it is used as the base of the number. If *base* is 0, the initial characters of the string that's pointed to by *strSource* are used to determine the base. If the first character is '0' and the second character is not 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *base* are permitted. The first character outside the range of the base stops the scan. For example, if *base* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. **strtoumax** allows a plus sign (**+**) or minus sign (**-**) prefix; a leading minus sign indicates that the return value is the two’s complement of the absolute value of the converted string. +A *`whitespace`* may consist of space and tab characters, which are ignored. *`digits`* are one or more decimal digits. *`letters`* are one or more of the letters 'a' through 'z' (or 'A' through 'Z'). The first character that doesn't fit this form stops the scan. If *`base`* is between 2 and 36, then it's used as the base of the number. If *`base`* is 0, the initial characters of the string that's pointed to by *`strSource`* are used to determine the base. If the first character is '0' and the second character isn't 'x' or 'X', the string is interpreted as an octal integer. If the first character is '0' and the second character is 'x' or 'X', the string is interpreted as a hexadecimal integer. If the first character is '1' through '9', the string is interpreted as a decimal integer. The letters 'a' through 'z' (or 'A' through 'Z') are assigned the values 10 through 35; only letters whose assigned values are less than *`base`* are permitted. The first character outside the range of the base stops the scan. For example, if *`base`* is 0 and the first character scanned is '0', an octal integer is assumed and an '8' or '9' character would stop the scan. **`strtoumax`** allows a plus sign (**`+`**) or minus sign (**`-`**) prefix; a leading minus sign indicates that the return value is the two's complement of the absolute value of the converted string. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strtoumax**|\| -|**wcstoumax**|\ or \| -|**_strtoumax_l**|\| -|**_wcstoumax_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strtoumax`**, **`wcstoumax`**, **`_strtoumax_l`**, **`_wcstoumax_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [strtod](strtod-strtod-l-wcstod-wcstod-l.md). +See the example for [`strtod`](strtod-strtod-l-wcstod-wcstod-l.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[String to Numeric Value Functions](../../c-runtime-library/string-to-numeric-value-functions.md)
-[strtod, _strtod_l, wcstod, _wcstod_l](strtod-strtod-l-wcstod-wcstod-l.md)
-[strtoimax, _strtoimax_l, wcstoimax, _wcstoimax_l](strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md)
-[strtol, wcstol, _strtol_l, _wcstol_l](strtol-wcstol-strtol-l-wcstol-l.md)
-[strtoul, _strtoul_l, wcstoul, _wcstoul_l](strtoul-strtoul-l-wcstoul-wcstoul-l.md)
-[strtoll, _strtoll_l, wcstoll, _wcstoll_l](strtoll-strtoll-l-wcstoll-wcstoll-l.md)
-[atof, _atof_l, _wtof, _wtof_l](atof-atof-l-wtof-wtof-l.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[String to numeric value functions](../string-to-numeric-value-functions.md)\ +[`strtod`, `_strtod_l`, `wcstod`, `_wcstod_l`](strtod-strtod-l-wcstod-wcstod-l.md)\ +[`strtoimax`, `_strtoimax_l`, `wcstoimax`, `_wcstoimax_l`](strtoimax-strtoimax-l-wcstoimax-wcstoimax-l.md)\ +[`strtol`, `wcstol`, `_strtol_l`, `_wcstol_l`](strtol-wcstol-strtol-l-wcstol-l.md)\ +[`strtoul`, `_strtoul_l`, `wcstoul`, `_wcstoul_l`](strtoul-strtoul-l-wcstoul-wcstoul-l.md)\ +[`strtoll`, `_strtoll_l`, `wcstoll`, `_wcstoll_l`](strtoll-strtoll-l-wcstoll-wcstoll-l.md)\ +[`atof`, `_atof_l`, `_wtof`, `_wtof_l`](atof-atof-l-wtof-wtof-l.md) diff --git a/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md b/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md index aa6ec6677fd..9f490cf61ed 100644 --- a/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md +++ b/docs/c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md @@ -3,19 +3,19 @@ description: "Learn more about: _strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, title: "_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l" ms.date: "4/2/2020" api_name: ["_strupr_s", "_strupr_s_l", "_mbsupr_s", "_wcsupr_s_l", "_mbsupr_s_l", "_wcsupr_s", "_o__mbsupr_s", "_o__mbsupr_s_l", "_o__strupr_s", "_o__strupr_s_l", "_o__wcsupr_s", "_o__wcsupr_s_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strupr_s", "mbsupr_s", "wcsupr_s", "_mbsupr_s_l", "mbsupr_s_l", "wcsupr_s_l", "_wcsupr_s", "_tcsupr_s_l", "_mbsupr_s", "_tcsupr_s", "strupr_s_l", "_wcsupr_s_l", "_strupr_s", "_strupr_s_l"] +f1_keywords: ["_strupr_s", "_strupr_s_l", "_mbsupr_s", "_mbsupr_s_l", "_wcsupr_s", "_wcsupr_s_l", "_tcsupr_s", "_tcsupr_s_l"] helpviewer_keywords: ["mbsupr_s_l function", "strupr_s_l function", "_wcsupr_s_l function", "_tcsupr_s_l function", "mbsupr_s function", "_wcsupr_s function", "uppercase, converting strings to", "tcsupr_s function", "string conversion [C++], case", "strupr_s function", "wcsupr_s_l function", "_mbsupr_s function", "_mbsupr_s_l function", "_strupr_s_l function", "tcsupr_s_l function", "strings [C++], case", "converting case, CRT functions", "_tcsupr_s function", "strings [C++], converting case", "_strupr_s function", "wcsupr_s function"] ms.assetid: 82d3a273-9f6f-4a26-9560-919d891e4581 --- -# _strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l +# `_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l` -Converts a string to uppercase, by using the current locale or a specified locale that's passed in. These versions of [_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a string to uppercase, by using the current locale or a specified locale that's passed in. These versions of [`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] -> **_mbsupr_s** and **_mbsupr_s_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsupr_s`** and **`_mbsupr_s_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -78,56 +78,56 @@ errno_t _mbsupr_s_l( ### Parameters -*str*
+*`str`*\ String to capitalize. -*numberOfElements*
+*`numberOfElements`*\ Size of the buffer. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful; a non-zero error code on failure. -These functions validate their parameters. If *str* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the functions return **EINVAL** and set **errno** to **EINVAL**. If *numberOfElements* is less than the length of the string, the functions return **ERANGE** and set **errno** to **ERANGE**. +These functions validate their parameters. If *`str`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the functions return `EINVAL` and set `errno` to `EINVAL`. If *`numberOfElements`* is less than the length of the string, the functions return `ERANGE` and set `errno` to `ERANGE`. ## Remarks -The **_strupr_s** function converts, in place, each lowercase letter in *str* to uppercase. **_wcsupr_s** is the wide-character version of **_strupr_s**. **_mbsupr_s** is the multi-byte character version of **_strupr_s**. +The **`_strupr_s`** function converts, in place, each lowercase letter in *`str`* to uppercase. **`_wcsupr_s`** is the wide-character version of **`_strupr_s`**. **`_mbsupr_s`** is the multi-byte character version of **`_strupr_s`**. -The conversion is determined by the **LC_CTYPE** category setting of the locale. Other characters are not affected. For more information on **LC_CTYPE**, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale; the visions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The conversion is determined by the `LC_CTYPE` category setting of the locale. Other characters aren't affected. For more information on `LC_CTYPE`, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale; the visions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [_CrtSetDebugFillThreshold](crtsetdebugfillthreshold.md). +The debug library versions of these functions first fill the buffer with 0xFE. To disable this behavior, use [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsupr_s**|**_strupr_s**|**_mbsupr_s**|**_wcsupr_s**| -|**_tcsupr_s_l**|**_strupr_s_l**|**_mbsupr_s_l**|**_wcsupr_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsupr_s` | **`_strupr_s`** | **`_mbsupr_s`** | **`_wcsupr_s`** | +| `_tcsupr_s_l` | **`_strupr_s_l`** | **`_mbsupr_s_l`** | **`_wcsupr_s_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strupr_s**, **_strupr_s_l**|\| -|**_wcsupr_s**, **_wcsupr_s_l**, **_mbsupr_s**, **_mbsupr_s_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_strupr_s`**, **`_strupr_s_l`** | \ | +| **`_wcsupr_s`**, **`_wcsupr_s_l`**, **`_mbsupr_s`**, **`_mbsupr_s_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) . +See the example for [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) . ## See also -[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)
+[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) diff --git a/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md b/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md index b4ba8693af6..3e7ba39f46b 100644 --- a/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md +++ b/docs/c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md @@ -3,19 +3,19 @@ description: "Learn more about: _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_ title: "_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr" ms.date: "4/2/2020" api_name: ["_mbsupr_l", "_mbsupr", "_strupr_l", "_wcsupr", "_wcsupr_l", "_strupr", "_o__mbsupr", "_o__mbsupr_l", "_o__strupr", "_o__strupr_l", "_o__wcsupr", "_o__wcsupr_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll", "api-ms-win-crt-multibyte-l1-1-0.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_mbsupr", "_ftcsupr", "mbsupr", "_tcsupr", "strupr_l", "_fstrupr", "_strupr", "mbsupr_l", "_wcsupr"] +f1_keywords: ["STRING/_strupr", "STRING/_strupr_l", "MBSTRING/_mbsupr", "MBSTRING/_mbsupr_l", "CORECRT_WSTRING/_wcsupr", "CORECRT_WSTRING/_wcsupr_l", "TCHAR/_tcsupr", "TCHAR/_tcsupr_l", "_strupr", "_strupr_l", "_mbsupr", "_mbsupr_l", "_wcsupr", "_wcsupr_l", "_tcsupr", "_tcsupr_l", "_ftcsupr", "_fstrupr"] helpviewer_keywords: ["tcsupr_l function", "mbsupr function", "strupr function", "uppercase, converting strings to", "wcsupr function", "_wcsupr function", "string conversion [C++], case", "ftcsupr function", "_ftcsupr function", "_wcsupr_l function", "wcsupr_l function", "strings [C++], case", "tcsupr function", "_tcsupr_l function", "_fstrupr function", "_strupr_l function", "_mbsupr_l function", "converting case, CRT functions", "fstrupr function", "mbsupr_l function", "strupr_l function", "_strupr function", "_mbsupr function", "_tcsupr function", "strings [C++], converting case"] ms.assetid: caac8f16-c233-41b6-91ce-575ec7061b77 --- -# _strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr +# `_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr` -Converts a string to uppercase. More secure versions of these functions are available; see [_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md). +Converts a string to uppercase. More secure versions of these functions are available; see [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md). > [!IMPORTANT] -> **_mbsupr** and **_mbsupr_l** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). +> **`_mbsupr`** and **`_mbsupr_l`** cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). ## Syntax @@ -72,51 +72,51 @@ unsigned char *_mbsupr_l( ### Parameters -*str*
+*`str`*\ String to capitalize. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Returns a pointer to the altered string. Because the modification is done in place, the pointer returned is the same as the pointer passed as the input argument. No return value is reserved to indicate an error. ## Remarks -The **_strupr** function converts, in place, each lowercase letter in *str* to uppercase. The conversion is determined by the **LC_CTYPE** category setting of the locale. Other characters are not affected. For more information on **LC_CTYPE**, see [setlocale](setlocale-wsetlocale.md). The versions of these functions without the **_l** suffix use the current locale; the versions with the **_l** suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`_strupr`** function converts, in place, each lowercase letter in *`str`* to uppercase. The conversion is determined by the `LC_CTYPE` category setting of the locale. Other characters aren't affected. For more information on `LC_CTYPE`, see [`setlocale`](setlocale-wsetlocale.md). The versions of these functions without the `_l` suffix use the current locale; the versions with the `_l` suffix are identical except that they use the locale passed in instead. For more information, see [Locale](../locale.md). -**_wcsupr** and **_mbsupr** are wide-character and multibyte-character versions of **_strupr**. The argument and return value of **_wcsupr** are wide-character strings; those of **_mbsupr** are multibyte-character strings. These three functions behave identically otherwise. +**`_wcsupr`** and **`_mbsupr`** are wide-character and multibyte-character versions of **`_strupr`**. The argument and return value of **`_wcsupr`** are wide-character strings. The argument and return value of **`_mbsupr`** are multibyte-character strings. These three functions behave identically otherwise. -If *str* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set **errno** to **EINVAL**. +If *`str`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions return the original string and set `errno` to `EINVAL`. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsupr**|**_strupr**|**_mbsupr**|**_wcsupr**| -|**_tcsupr_l**|**_strupr_l**|**_mbsupr_l**|**_wcsupr_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsupr` | **`_strupr`** | **`_mbsupr`** | **`_wcsupr`** | +| `_tcsupr_l` | **`_strupr_l`** | **`_mbsupr_l`** | **`_wcsupr_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_strupr**, **_strupr_l**|\| -|**_wcsupr**, **_wcsupr_l**|\ or \| -|**_mbsupr**, **_mbsupr_l**|\| +| Routine | Required header | +|---|---| +| **`_strupr`**, **`_strupr_l`** | \ | +| **`_wcsupr`**, **`_wcsupr_l`** | \ or \ | +| **`_mbsupr`**, **`_mbsupr_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [_strlwr](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md). +See the example for [`_strlwr`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md). ## See also -[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md)
+[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) diff --git a/docs/c-runtime-library/reference/strupr-wcsupr.md b/docs/c-runtime-library/reference/strupr-wcsupr.md index a299292679a..1b25726e49a 100644 --- a/docs/c-runtime-library/reference/strupr-wcsupr.md +++ b/docs/c-runtime-library/reference/strupr-wcsupr.md @@ -6,12 +6,12 @@ api_name: ["strupr", "wcsupr"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strupr", "wcsupr"] +f1_keywords: ["STRING/strupr", "CORECRT_WSTRING/wcsupr", "strupr", "wcsupr"] helpviewer_keywords: ["strupr function", "wcsupr function"] ms.assetid: 17dfe1cd-3b09-4702-9f89-2207f44953e6 --- -# strupr, wcsupr +# `strupr`, `wcsupr` -The Microsoft-specific function names `strupr` and `wcsupr` are deprecated aliases for the [_strupr and _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-specific function names `strupr` and `wcsupr` are deprecated aliases for the [`_strupr` and `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_strupr and _wcsupr](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) or the security-enhanced [_strupr_s and _wcsupr_s](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_strupr` and `_wcsupr`](strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) or the security-enhanced [`_strupr_s` and `_wcsupr_s`](strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) functions instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md b/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md index 6c1fcd53415..793aca693fa 100644 --- a/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md +++ b/docs/c-runtime-library/reference/strxfrm-wcsxfrm-strxfrm-l-wcsxfrm-l.md @@ -3,14 +3,14 @@ description: "Learn more about: strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l" title: "strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l" ms.date: "4/2/2020" api_name: ["strxfrm", "_wcsxfrm_l", "_strxfrm_l", "wcsxfrm", "_o__strxfrm_l", "_o__wcsxfrm_l"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["strxfrm", "_tcsxfrm", "wcsxfrm"] +f1_keywords: ["STRING/strxfrm", "STRING/_strxfrm_l", "CORECRT_WSTRING/wcsxfrm", "CORECRT_WSTRING/_wcsxfrm_l", "TCHAR/_tcsxfrm", "TCHAR/_tcsxfrm_l", "strxfrm", "_strxfrm_l", "wcsxfrm", "_wcsxfrm_l", "_tcsxfrm", "_tcsxfrm_l"] helpviewer_keywords: ["strxfrm_l function", "_tcsxfrm function", "_strxfrm_l function", "strxfrm function", "wcsxfrm_l function", "wcsxfrm function", "string comparison [C++], transforming strings", "tcsxfrm function", "strings [C++], comparing locale", "_wcsxfrm_l function"] ms.assetid: 6ba8e1f6-4484-49aa-83b8-bc2373187d9e --- -# strxfrm, wcsxfrm, _strxfrm_l, _wcsxfrm_l +# `strxfrm`, `wcsxfrm`, `_strxfrm_l`, `_wcsxfrm_l` Transform a string based on locale-specific information. @@ -43,52 +43,52 @@ size_t wcsxfrm_l( ### Parameters -*strDest*
+*`strDest`*\ Destination string. -*strSource*
+*`strSource`*\ Source string. -*count*
-Maximum number of characters to place in *strDest*. +*`count`*\ +Maximum number of characters to place in *`strDest`*. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -Returns the length of the transformed string, not counting the terminating null character. If the return value is greater than or equal to *count*, the content of *strDest* is unpredictable. On an error, each function sets **errno** and returns **INT_MAX**. For an invalid character, **errno** is set to **EILSEQ**. +Returns the length of the transformed string, not counting the terminating null character. If the return value is greater than or equal to *`count`*, the content of *`strDest`* is unpredictable. On an error, each function sets `errno` and returns `INT_MAX`. For an invalid character, `errno` is set to `EILSEQ`. ## Remarks -The **strxfrm** function transforms the string pointed to by *strSource* into a new collated form that is stored in *strDest*. No more than *count* characters, including the null character, are transformed and placed into the resulting string. The transformation is made using the locale's **LC_COLLATE** category setting. For more information on **LC_COLLATE**, see [setlocale](setlocale-wsetlocale.md). **strxfrm** uses the current locale for its locale-dependent behavior; **_strxfrm_l** is identical except that it uses the locale passed in instead of the current locale. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`strxfrm`** function transforms the string pointed to by *`strSource`* into a new collated form that is stored in *`strDest`*. No more than *`count`* characters, including the null character, are transformed and placed into the resulting string. The transformation is made using the locale's `LC_COLLATE` category setting. For more information on `LC_COLLATE`, see [`setlocale`](setlocale-wsetlocale.md). **`strxfrm`** uses the current locale for its locale-dependent behavior; **`_strxfrm_l`** is identical except that it uses the locale passed in instead of the current locale. For more information, see [Locale](../locale.md). -After the transformation, a call to **strcmp** with the two transformed strings yields results identical to those of a call to **strcoll** applied to the original two strings. As with **strcoll** and **stricoll**, **strxfrm** automatically handles multibyte-character strings as appropriate. +After the transformation, a call to `strcmp` with the two transformed strings yields results identical to the results of a call to `strcoll` applied to the original two strings. As with `strcoll` and `stricoll`, **`strxfrm`** automatically handles multibyte-character strings as appropriate. -**wcsxfrm** is a wide-character version of **strxfrm**; the string arguments of **wcsxfrm** are wide-character pointers. For **wcsxfrm**, after the string transformation, a call to **wcscmp** with the two transformed strings yields results identical to those of a call to **wcscoll** applied to the original two strings. **wcsxfrm** and **strxfrm** behave identically otherwise. **wcsxfrm** uses the current locale for its locale-dependent behavior; **_wcsxfrm_l** uses the locale passed in instead of the current locale. +**`wcsxfrm`** is a wide-character version of **`strxfrm`**; the string arguments of **`wcsxfrm`** are wide-character pointers. For **`wcsxfrm`**, after the string transformation, a call to `wcscmp` with the two transformed strings yields results identical to the results of a call to `wcscoll` applied to the original two strings. **`wcsxfrm`** and **`strxfrm`** behave identically otherwise. **`wcsxfrm`** uses the current locale for its locale-dependent behavior; **`_wcsxfrm_l`** uses the locale passed in instead of the current locale. -These functions validate their parameters. If *strSource* is a null pointer, or *strDest* is a **NULL** pointer (unless count is zero), or if *count* is greater than **INT_MAX**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **INT_MAX**. +These functions validate their parameters. If *`strSource`* is a null pointer, or *`strDest`* is a `NULL` pointer (unless count is zero), or if *`count`* is greater than `INT_MAX`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `INT_MAX`. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tcsxfrm**|**strxfrm**|**strxfrm**|**wcsxfrm**| -|**_tcsxfrm_l**|**_strxfrm_l**|**_strxfrm_l**|**_wcsxfrm_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tcsxfrm` | **`strxfrm`** | **`strxfrm`** | **`wcsxfrm`** | +| `_tcsxfrm_l` | **`_strxfrm_l`** | **`_strxfrm_l`** | **`_wcsxfrm_l`** | In the "C" locale, the order of the characters in the character set (ASCII character set) is the same as the lexicographic order of the characters. However, in other locales, the order of characters in the character set may differ from the lexicographic character order. For example, in certain European locales, the character 'a' (value 0x61) precedes the character '&\#x00E4;' (value 0xE4) in the character set, but the character 'ä' precedes the character 'a' lexicographically. -In locales for which the character set and the lexicographic character order differ, use **strxfrm** on the original strings and then **strcmp** on the resulting strings to produce a lexicographic string comparison according to the current locale's **LC_COLLATE** category setting. Thus, to compare two strings lexicographically in the above locale, use **strxfrm** on the original strings, then **strcmp** on the resulting strings. Alternately, you can use **strcoll** rather than **strcmp** on the original strings. +In locales for which the character set and the lexicographic character order differ, use **`strxfrm`** on the original strings and then `strcmp` on the resulting strings to produce a lexicographic string comparison according to the current locale's `LC_COLLATE` category setting. Thus, to compare two strings lexicographically in the above locale, use **`strxfrm`** on the original strings, then `strcmp` on the resulting strings. Alternately, you can use `strcoll` rather than `strcmp` on the original strings. -**strxfrm** is basically a wrapper around [LCMapString](/windows/win32/api/winnls/nf-winnls-lcmapstringw) with **LCMAP_SORTKEY**. +**`strxfrm`** is basically a wrapper around [`LCMapString`](/windows/win32/api/winnls/nf-winnls-lcmapstringw) with `LCMAP_SORTKEY`. -The value of the following expression is the size of the array needed to hold the **strxfrm** transformation of the source string: +The value of the following expression is the size of the array needed to hold the **`strxfrm`** transformation of the source string: `1 + strxfrm( NULL, string, 0 )` -In the "C" locale only, **strxfrm** is equivalent to the following: +In the "C" locale only, **`strxfrm`** is equivalent to the following function calls: ```C strncpy( _string1, _string2, _count ); @@ -97,22 +97,22 @@ return( strlen( _string1 ) ); ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**strxfrm**|\| -|**wcsxfrm**|\ or \| -|**_strxfrm_l**|\| -|**_wcsxfrm_l**|\ or \| +| Routine | Required header | +|---|---| +| **`strxfrm`** | \ | +| **`wcsxfrm`** | \ or \ | +| **`_strxfrm_l`** | \ | +| **`_wcsxfrm_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[localeconv](localeconv.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
-[Locale](../../c-runtime-library/locale.md)
-[String Manipulation](../../c-runtime-library/string-manipulation-crt.md)
-[strcoll Functions](../../c-runtime-library/strcoll-functions.md)
-[strcmp, wcscmp, _mbscmp](strcmp-wcscmp-mbscmp.md)
-[strncmp, wcsncmp, _mbsncmp, _mbsncmp_l](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md)
+[Data conversion](../data-conversion.md)\ +[`localeconv`](localeconv.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md)\ +[Locale](../locale.md)\ +[String manipulation](../string-manipulation-crt.md)\ +[`strcoll` functions](../strcoll-functions.md)\ +[`strcmp`, `wcscmp`, `_mbscmp`](strcmp-wcscmp-mbscmp.md)\ +[`strncmp`, `wcsncmp`, `_mbsncmp`, `_mbsncmp_l`](strncmp-wcsncmp-mbsncmp-mbsncmp-l.md) diff --git a/docs/c-runtime-library/reference/swab.md b/docs/c-runtime-library/reference/swab.md index 334aa108678..2eb748ef51f 100644 --- a/docs/c-runtime-library/reference/swab.md +++ b/docs/c-runtime-library/reference/swab.md @@ -3,14 +3,14 @@ description: "Learn more about: _swab" title: "_swab" ms.date: "4/2/2020" api_name: ["_swab", "stdlib/_swab", "_o__swab"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-utility-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_swab", "stdlib/_swab"] +f1_keywords: ["STDLIB/_swab", "_swab"] helpviewer_keywords: ["_swab function", "swapping bytes", "swab function", "bytes, swapping"] ms.assetid: 017142f2-050c-4f6a-8b49-6b094f58ec94 --- -# _swab +# `_swab` Swaps bytes. @@ -26,34 +26,34 @@ void _swab( ## Parameters -*src*
+*`src`*\ Data to be copied and swapped. -*dest*
+*`dest`*\ Storage location for swapped data. -*n*
+*`n`*\ Number of bytes to be copied and swapped. ## Return value -The **swab** function does not return a value. The function sets **errno** to **EINVAL** if either the *src* or *dest* pointer is null or *n* is less than zero, and the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). +The **`swab`** function doesn't return a value. The function sets `errno` to `EINVAL` if either the *`src`* or *`dest`* pointer is null or *`n`* is less than zero, and the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this and other return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -If *n* is even, the **_swab** function copies *n* bytes from *src*, swaps each pair of adjacent bytes, and stores the result at *dest*. If *n* is odd, **_swab** copies and swaps the first *n*-1 bytes of *src*, and the final byte is not copied. The **_swab** function is typically used to prepare binary data for transfer to a machine that uses a different byte order. +If *`n`* is even, the **`_swab`** function copies *`n`* bytes from *`src`*, swaps each pair of adjacent bytes, and stores the result at *`dest`*. If *`n`* is odd, **`_swab`** copies and swaps the first *`n`*-1 bytes of *`src`*, and the final byte isn't copied. The **`_swab`** function is typically used to prepare binary data for transfer to a machine that uses a different byte order. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_swab**|C: \ C++: \ or \| +| Routine | Required header | +|---|---| +| **`_swab`** | C: \ C++: \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -84,4 +84,4 @@ After: BADCFEHGJILKNMPORQTSVUXWZY ## See also -[Buffer Manipulation](../../c-runtime-library/buffer-manipulation.md)
+[Buffer manipulation](../buffer-manipulation.md) diff --git a/docs/c-runtime-library/reference/system-wsystem.md b/docs/c-runtime-library/reference/system-wsystem.md index 8d4972c5f84..7afde9d4911 100644 --- a/docs/c-runtime-library/reference/system-wsystem.md +++ b/docs/c-runtime-library/reference/system-wsystem.md @@ -3,10 +3,10 @@ description: "Learn more about: system, _wsystem" title: "system, _wsystem" ms.date: "4/2/2020" api_name: ["system", "_wsystem", "_o__wsystem", "_o_system"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tsystem", "_wsystem"] +f1_keywords: ["PROCESS/system", "CORECRT_WPROCESS/_wsystem", "TCHAR/_tsystem", "system", "_wsystem", "_tsystem"] helpviewer_keywords: ["_wsystem function", "wsystem function", "tsystem function", "_tsystem function", "system function", "commands, executing", "command interpreter"] ms.assetid: 7d3df2b6-f742-49ce-bf52-012b0aee3df5 --- @@ -30,46 +30,46 @@ int _wsystem( ### Parameters -*`command`*
+*`command`*\ The command to be executed. -## Return Value +## Return value -If *`command`* is **`NULL`** and the command interpreter is found, returns a nonzero value. If the command interpreter is not found, returns 0 and sets **`errno`** to **`ENOENT`**. If *`command`* is not **`NULL`**, **`system`** returns the value that is returned by the command interpreter. It returns the value 0 only if the command interpreter returns the value 0. A return value of -1 indicates an error, and **`errno`** is set to one of the following values: +If *`command`* is `NULL` and the command interpreter is found, returns a nonzero value. If the command interpreter isn't found, returns 0 and sets `errno` to `ENOENT`. If *`command`* isn't `NULL`, **`system`** returns the value that is returned by the command interpreter. It returns the value 0 only if the command interpreter returns the value 0. A return value of -1 indicates an error, and `errno` is set to one of the following values: | Value | Description | |-|-| -| **`E2BIG`** | The argument list (which is system-dependent) is too big. | -| **`ENOENT`** | The command interpreter cannot be found. | -| **`ENOEXEC`** | The command-interpreter file cannot be executed because the format is not valid. | -| **`ENOMEM`** | Not enough memory is available to execute command; or available memory has been corrupted; or a non-valid block exists, which indicates that the process that's making the call was not allocated correctly. | +| `E2BIG` | The argument list (which is system-dependent) is too large. | +| `ENOENT` | The command interpreter can't be found. | +| `ENOEXEC` | The command-interpreter file can't be executed because the format isn't valid. | +| `ENOMEM` | Not enough memory is available to execute command; or available memory has been corrupted; or a non-valid block exists, which indicates that the calling process has been allocated incorrectly. | -See [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information about these return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **`system`** function passes *`command`* to the command interpreter, which executes the string as an operating-system command. **`system`** uses the **`COMSPEC`** and **`PATH`** environment variables to locate the command-interpreter file CMD.exe. If *`command`* is **`NULL`**, the function just checks whether the command interpreter exists. +The **`system`** function passes *`command`* to the command interpreter, which executes the string as an operating-system command. **`system`** uses the `COMSPEC` and `PATH` environment variables to locate the command-interpreter file CMD.exe. If *`command`* is `NULL`, the function just checks whether the command interpreter exists. You must explicitly flush, by using [`fflush`](fflush.md) or [`_flushall`](flushall.md), or close any stream before you call **`system`**. **`_wsystem`** is a wide-character version of **`system`**; the *`command`* argument to **`_wsystem`** is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_tsystem`**|**`system`**|**`system`**|**`_wsystem`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_tsystem`** | **`system`** | **`system`** | **`_wsystem`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`system`**|`` or ``| -|**`_wsystem`**|`` or `` or ``| +| Routine | Required header | +|---|---| +| **`system`** | `` or `` | +| **`_wsystem`** | `` or `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -102,8 +102,8 @@ Line two. ## See also -[Process and Environment Control](../../c-runtime-library/process-and-environment-control.md)
-[`_exec`, `_wexec` Functions](../../c-runtime-library/exec-wexec-functions.md)
-[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)
-[`_flushall`](flushall.md)
-[`_spawn`, `_wspawn` Functions](../../c-runtime-library/spawn-wspawn-functions.md)
+[Process and environment control](../process-and-environment-control.md)\ +[`_exec`, `_wexec` functions](../exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](exit-exit-exit.md)\ +[`_flushall`](flushall.md)\ +[`_spawn`, `_wspawn` functions](../spawn-wspawn-functions.md) diff --git a/docs/c-runtime-library/reference/tan-tanf-tanl.md b/docs/c-runtime-library/reference/tan-tanf-tanl.md index 368112080cc..58e1563bf1a 100644 --- a/docs/c-runtime-library/reference/tan-tanf-tanl.md +++ b/docs/c-runtime-library/reference/tan-tanf-tanl.md @@ -1,14 +1,13 @@ --- title: "tan, tanf, tanl" description: "API reference for tan, tanf, and tanl; which calculate the tangent of a floating-point value." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["tan", "tanf", "tanl", "_o_tan", "_o_tanf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tan", "tanf", "_tanl", "tanl"] -helpviewer_keywords: ["tanl function", "_tanl function", "tan function", "calculating tangents", "tangent", "tanf function", "trigonometric functions"] -ms.assetid: 36cc0ce8-9c80-4653-b354-ddb3b378b6bd +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"] --- # `tan`, `tanf`, `tanl` @@ -20,7 +19,7 @@ Calculates the tangent. double tan( double x ); float tanf( float x ); long double tanl( long double x ); -#define tan(x) // Requires C11 or higher +#define tan(x) // Requires C11 or later ``` ```cpp @@ -37,27 +36,27 @@ Angle in radians. The **`tan`** functions return the tangent of *`x`*. If *`x`* is greater than or equal to 263, or less than or equal to -263, a loss of significance in the result occurs. -|Input|SEH exception|**`Matherr`** exception| -|-----------|-------------------|-------------------------| -|`± QNAN`,`IND`|none|`_DOMAIN`| -|`± INF`|**INVALID**|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | +| ± INF | `INVALID` | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`tan`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`tan`** always takes and returns **`double`**. -If you use the `` `tan()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `tan` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------|-| -|**`tan`**, **`tanf`**, **`tanl`**|``|`` or ``| -|**`tan()`** macro | `` || +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`tan`**, **`tanf`**, **`tanl`** | `` | `` or `` | +| **`tan`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -85,10 +84,10 @@ tan( 0.785398 ) = 1.000000 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acos`, `acosf`, `acosl`](acos-acosf-acosl.md)\ [`asin`, `asinf`, `asinl`](asin-asinf-asinl.md)\ [`atan`, `atanf`, `atanl`, `atan2`, `atan2f`, `atan2l`](atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`cos`, `cosf`, `cosl`](cos-cosf-cosl.md)\ [`sin`, `sinf`, `sinl`](sin-sinf-sinl.md)\ -[`_CItan`](../../c-runtime-library/citan.md) +[`_CItan`](../citan.md) diff --git a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md index 759de428563..069c1a809fe 100644 --- a/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md +++ b/docs/c-runtime-library/reference/tanh-tanhf-tanhl.md @@ -1,13 +1,13 @@ --- title: "tanh, tanhf, tanhl" description: "API reference for tanh, tanhf, and tanhl; which calculate the hyperbolic tangent of a floating-point value." -ms.date: "1/15/2021" +ms.date: 1/15/2021 api_name: ["tanh", "tanhf", "tanhl", "_o_tanh", "_o_tanhf"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tanh", "tanhf", "tanhl", "_tanhl"] -helpviewer_keywords: ["tanhl function", "_tanhl function", "tanh function", "tanhf function", "trigonometric functions", "hyperbolic functions"] +f1_keywords: ["CORECRT_MATH/tanh", "CORECRT_MATH/tanhf", "CORECRT_MATH/tanhl", "tanh", "tanhf", "tanhl"] +helpviewer_keywords: ["tanhl function", "tanh function", "tanhf function", "trigonometric functions", "hyperbolic functions"] --- # `tanh`, `tanhf`, `tanhl` @@ -19,7 +19,7 @@ Calculates the hyperbolic tangent. double tanh( double x ); float tanhf( float x ); long double tanhl( long double x ); -#define tanh(x) // Requires C11 or higher +#define tanh(x) // Requires C11 or later ``` ```cpp @@ -36,26 +36,26 @@ Angle in radians. The **`tanh`** functions return the hyperbolic tangent of *`x`*. There's no error return. -|Input|SEH exception|**`Matherr`** exception| -|-----------|-------------------|-------------------------| -|± `QNAN`,`IND`|none|`_DOMAIN`| +| Input | SEH exception | `_matherr` exception | +|---|---|---| +| ± QNaN, IND | none | `_DOMAIN` | ## Remarks Because C++ allows overloading, you can call overloads of **`tanh`** that take and return **`float`** or **`long double`** values. In a C program, unless you're using the `` macro to call this function, **`tanh`** always takes and returns **`double`**. -If you use the `` `tanh()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the `tanh` macro from ``, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header (C)|Required header (C)| -|-------------|---------------------|-| -|**`tanh`**, **`tanhf`**, **`tanhl`**|``|`` or ``| -|**`tanh()`** macro | `` || +| Routine | Required header (C) | Required header (C) | +|---|---|---| +| **`tanh`**, **`tanhf`**, **`tanhl`** | `` | `` or `` | +| **`tanh`** macro | `` | | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,7 +87,7 @@ tanh( 1.000000 ) = 0.761594 ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)\ +[Math and floating-point support](../floating-point-support.md)\ [`acosh`, `acoshf`, `acoshl`](acosh-acoshf-acoshl.md)\ [`asinh`, `asinhf`, `asinhl`](asinh-asinhf-asinhl.md)\ [`atanh`, `atanhf`, `atanhl`](atanh-atanhf-atanhl.md)\ diff --git a/docs/c-runtime-library/reference/tell-telli64.md b/docs/c-runtime-library/reference/tell-telli64.md index 5b3bf23a8e6..9e7cc0ff459 100644 --- a/docs/c-runtime-library/reference/tell-telli64.md +++ b/docs/c-runtime-library/reference/tell-telli64.md @@ -3,14 +3,14 @@ description: "Learn more about: _tell, _telli64" title: "_tell, _telli64" ms.date: "4/2/2020" api_name: ["_telli64", "_tell", "_o__tell", "_o__telli64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["telli64", "_telli64", "_tell"] +f1_keywords: ["CORECRT_IO/_tell", "CORECRT_IO/_telli64", "_tell", "_telli64"] helpviewer_keywords: ["tell function", "file pointers [C++], getting", "_tell function", "file pointers [C++]", "telli64 function", "_telli64 function"] ms.assetid: 1500e8f9-8fec-4253-9eec-ec66125dfc9b --- -# _tell, _telli64 +# `_tell`, `_telli64` Get the position of the file pointer. @@ -27,30 +27,30 @@ __int64 _telli64( ### Parameters -*handle*
+*`handle`*\ File descriptor referring to open file. -## Return Value +## Return value The current position of the file pointer. On devices incapable of seeking, the return value is undefined. -A return value of -1L indicates an error. If *handle* is an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EBADF** and return -1L. +A return value of -1L indicates an error. If *`handle`* is an invalid file descriptor, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EBADF` and return -1L. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on this, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_tell** function gets the current position of the file pointer (if any) associated with the *handle* argument. The position is expressed as the number of bytes from the beginning of the file. For the **_telli64** function, this value is expressed as a 64-bit integer. +The **`_tell`** function gets the current position of the file pointer (if any) associated with the *`handle`* argument. The position is expressed as the number of bytes from the beginning of the file. For the **`_telli64`** function, this value is expressed as a 64-bit integer. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tell**, **_telli64**|\| +| Routine | Required header | +|---|---| +| **`_tell`**, **`_telli64`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -100,6 +100,6 @@ Current file position is: 20 ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)
-[ftell, _ftelli64](ftell-ftelli64.md)
-[_lseek, _lseeki64](lseek-lseeki64.md)
+[Low-level I/O](../low-level-i-o.md)\ +[`ftell`, `_ftelli64`](ftell-ftelli64.md)\ +[`_lseek`, `_lseeki64`](lseek-lseeki64.md) diff --git a/docs/c-runtime-library/reference/tell.md b/docs/c-runtime-library/reference/tell.md index 6b7f179c7fd..3c48b55f025 100644 --- a/docs/c-runtime-library/reference/tell.md +++ b/docs/c-runtime-library/reference/tell.md @@ -6,12 +6,12 @@ api_name: ["tell"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tell"] +f1_keywords: ["CORECRT_IO/tell", "tell"] helpviewer_keywords: ["tell function"] ms.assetid: 3a92a40d-f472-4545-a493-f57c340ee798 --- -# tell +# `tell` -The Microsoft-specific function name `tell` is a deprecated alias for the [_tell](tell-telli64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `tell` is a deprecated alias for the [`_tell`](tell-telli64.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_tell](tell-telli64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_tell`](tell-telli64.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md b/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md index a91537e7ded..296d21e43e8 100644 --- a/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md +++ b/docs/c-runtime-library/reference/tempnam-dbg-wtempnam-dbg.md @@ -6,13 +6,13 @@ api_name: ["_wtempnam_dbg", "_tempnam_dbg"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wtempnam_dbg", "tempnam_dbg", "_tempnam_dbg", "_wtempnam_dbg"] +f1_keywords: ["CRTDBG/_tempnam_dbg", "CRTDBG/_wtempnam_dbg", "_tempnam_dbg", "_wtempnam_dbg"] helpviewer_keywords: ["file names [C++], creating temporary", "tempnam_dbg function", "temporary files, creating", "file names [C++], temporary", "wtempnam_dbg function", "_tempnam_dbg function", "_wtempnam_dbg function"] ms.assetid: e3760bb4-bb01-4808-b689-2c45af56a170 --- -# _tempnam_dbg, _wtempnam_dbg +# `_tempnam_dbg`, `_wtempnam_dbg` -Function versions of [_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md) that use the debug version of **malloc**, **_malloc_dbg**. +Function versions of [`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) that use the debug version of `malloc`, `_malloc_dbg`. ## Syntax @@ -35,50 +35,50 @@ wchar_t *_wtempnam_dbg( ### Parameters -*dir*
-The path used in the file name if there is no TMP environment variable, or if TMP is not a valid directory. +*`dir`*\ +The path used in the file name if there's no TMP environment variable, or if TMP isn't a valid directory. -*prefix*
-The string that will be pre-pended to names returned by **_tempnam**. +*`prefix`*\ +The string that will be pre-pended to names returned by `_tempnam`. -*blockType*
-Requested type of memory block: **_CLIENT_BLOCK** or **_NORMAL_BLOCK**. +*`blockType`*\ +Requested type of memory block: `_CLIENT_BLOCK` or `_NORMAL_BLOCK`. -*filename*
-Pointer to name of source file that requested allocation operation or **NULL**. +*`filename`*\ +Pointer to name of source file that requested allocation operation or `NULL`. -*linenumber*
-Line number in source file where allocation operation was requested or **NULL**. +*`linenumber`*\ +Line number in source file where allocation operation was requested or `NULL`. -## Return Value +## Return value -Each function returns a pointer to the name generated or **NULL** if there is a failure. Failure can occur if there is an invalid directory name specified in the TMP environment variable and in the *dir* parameter. +Each function returns a pointer to the name generated or `NULL` if there's a failure. Failure can occur if there's an invalid directory name specified in the TMP environment variable and in the *`dir`* parameter. > [!NOTE] -> **free** (or **free_dbg**) does need to be called for pointers allocated by **_tempnam_dbg** and **_wtempnam_dbg**. +> `free` (or `free_dbg`) does need to be called for pointers allocated by **`_tempnam_dbg`** and **`_wtempnam_dbg`**. ## Remarks -The **_tempnam_dbg** and **_wtempnam_dbg** functions are identical to **_tempnam** and **_wtempnam** except that, when **_DEBUG** is defined, these functions use the debug version of **malloc** and **_malloc_dbg**, to allocate memory if **NULL** is passed as the first parameter. For more information, see [_malloc_dbg](malloc-dbg.md). +The **`_tempnam_dbg`** and **`_wtempnam_dbg`** functions are identical to `_tempnam` and `_wtempnam` except that, when `_DEBUG` is defined, these functions use the debug version of `malloc` and `_malloc_dbg`, to allocate memory if `NULL` is passed as the first parameter. For more information, see [`_malloc_dbg`](malloc-dbg.md). -You do not need to call these functions explicitly in most cases. Instead, you can define the flag **_CRTDBG_MAP_ALLOC**. When **_CRTDBG_MAP_ALLOC** is defined, calls to **_tempnam** and **_wtempnam** are remapped to **_tempnam_dbg** and **_wtempnam_dbg**, respectively, with the *blockType* set to **_NORMAL_BLOCK**. Thus, you do not need to call these functions explicitly unless you want to mark the heap blocks as **_CLIENT_BLOCK**. For more information, see [Types of blocks on the debug heap](/visualstudio/debugger/crt-debug-heap-details). +You don't need to call these functions explicitly in most cases. Instead, you can define the flag `_CRTDBG_MAP_ALLOC`. When `_CRTDBG_MAP_ALLOC` is defined, calls to `_tempnam` and `_wtempnam` are remapped to **`_tempnam_dbg`** and **`_wtempnam_dbg`**, respectively, with the *`blockType`* set to `_NORMAL_BLOCK`. Thus, you don't need to call these functions explicitly unless you want to mark the heap blocks as `_CLIENT_BLOCK`. For more information, see [Types of blocks on the debug heap](../crt-debug-heap-details.md#types-of-blocks-on-the-debug-heap). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ttempnam_dbg**|**_tempnam_dbg**|**_tempnam_dbg**|**_wtempnam_dbg**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ttempnam_dbg` | **`_tempnam_dbg`** | **`_tempnam_dbg`** | **`_wtempnam_dbg`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tempnam_dbg**, **_wtempnam_dbg**|\| +| Routine | Required header | +|---|---| +| **`_tempnam_dbg`**, **`_wtempnam_dbg`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Debug Versions of Heap Allocation Functions](/visualstudio/debugger/debug-versions-of-heap-allocation-functions)
+[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md)\ +[Stream I/O](../stream-i-o.md)\ +[Debug versions of heap allocation functions](../debug-versions-of-heap-allocation-functions.md) diff --git a/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md b/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md index 663e24764b3..10e1de817af 100644 --- a/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md +++ b/docs/c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md @@ -6,13 +6,13 @@ api_name: ["_wtempnam", "_wtmpnam", "tmpnam", "_tempnam"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wtempnam", "_wtmpnam", "wtmpnam", "tmpnam", "_wtempnam", "_tempnam"] +f1_keywords: ["STDIO/tmpnam", "STDIO/_tempnam", "CORECRT_WSTDIO/_wtmpnam", "CORECRT_WSTDIO/_wtempnam", "TCHAR/_ttmpnam", "TCHAR/_ttempnam", "tmpnam", "_tempnam", "_wtmpnam", "_wtempnam", "_ttmpnam", "_ttempnam"] helpviewer_keywords: ["wtempnam function", "file names [C++], creating temporary", "_tempnam function", "ttmpnam function", "tmpnam function", "tempnam function", "wtmpnam function", "temporary files, creating", "file names [C++], temporary", "_ttmpnam function", "_wtmpnam function", "_wtempnam function"] ms.assetid: 3ce75f0f-5e30-42a6-9791-8d7cbfe70fca --- -# _tempnam, _wtempnam, tmpnam, _wtmpnam +# `_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam` -Generate names you can use to create temporary files. More secure versions of some of these functions are available; see [tmpnam_s, _wtmpnam_s](tmpnam-s-wtmpnam-s.md). +Generate names you can use to create temporary files. More secure versions of some of these functions are available; see [`tmpnam_s`, `_wtmpnam_s`](tmpnam-s-wtmpnam-s.md). ## Syntax @@ -35,58 +35,58 @@ wchar_t *_wtmpnam( ### Parameters -*prefix*
-The string that will be pre-pended to names returned by **_tempnam**. +*`prefix`*\ +The string that's prepended to names returned by **`_tempnam`**. -*dir*
-The path used in the file name if there is no TMP environment variable, or if TMP is not a valid directory. +*`dir`*\ +The path used in the file name if there's no TMP environment variable, or if TMP isn't a valid directory. -*str*
-Pointer that will hold the generated name and will be identical to the name returned by the function. This is a convenient way to save the generated name. +*`str`*\ +Pointer that holds the generated name, identical to the name returned by the function. It's a convenient way to save the generated name. -## Return Value +## Return value -Each of these functions returns a pointer to the name generated or **NULL** if there is a failure. Failure can occur if you attempt more than **TMP_MAX** (see STDIO.H) calls with **tmpnam** or if you use **_tempnam** and there is an invalid directory name specified in the TMP environment variable and in the *dir* parameter. +Each of these functions returns a pointer to the name generated or `NULL` if there's a failure. Failure can occur if you attempt more than `TMP_MAX` (see STDIO.H) calls with **`tmpnam`** or if you use **`_tempnam`** and there's an invalid directory name specified in the `TMP` environment variable and in the *`dir`* parameter. > [!NOTE] -> The pointers returned by **tmpnam** and **_wtmpnam** point to internal static buffers. [free](free.md) should not be called to deallocate those pointers. **free** needs to be called for pointers allocated by **_tempnam** and **_wtempnam**. +> The pointers returned by **`tmpnam`** and **`_wtmpnam`** point to internal static buffers. [`free`](free.md) should not be called to deallocate those pointers. `free` needs to be called for pointers allocated by **`_tempnam`** and **`_wtempnam`**. ## Remarks -Each of these functions returns the name of a file that does not currently exist. **tmpnam** returns a name that's unique in the designated Windows temporary directory returned by [GetTempPathW](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). **\_tempnam** generates a unique name in a directory other than the designated one. Note than when a file name is pre-pended with a backslash and no path information, such as \fname21, this indicates that the name is valid for the current working directory. +Each of these functions returns the name of a file that doesn't currently exist. **`tmpnam`** returns a name that's unique in the designated Windows temporary directory returned by [`GetTempPathW`](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). **`_tempnam`** generates a unique name in a directory other than the designated one. When a file name is prepended with a backslash and no path information, such as `\fname21`, it indicates that the name is valid for the current working directory. -For **tmpnam**, you can store this generated file name in *str*. If *str* is **NULL**, then **tmpnam** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **tmpnam** consists of a program-generated file name and, after the first call to **tmpnam**, a file extension of sequential numbers in base 32 (.1-.vvu, when **TMP_MAX** in STDIO.H is 32,767). +For **`tmpnam`**, you can store this generated file name in *`str`*. If *`str`* is `NULL`, then **`tmpnam`** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **`tmpnam`** consists of a program-generated file name and, after the first call to **`tmpnam`**, a file extension of sequential numbers in base 32 (.1-.vvu, when `TMP_MAX` in STDIO.H is 32,767). -**_tempnam** will generate a unique file name for a directory chosen by the following rules: +**`_tempnam`** generates a unique file name for a directory chosen by the following rules: -- If the TMP environment variable is defined and set to a valid directory name, unique file names will be generated for the directory specified by TMP. +- If the TMP environment variable is defined and set to a valid directory name, unique file names are generated for the directory specified by TMP. -- If the TMP environment variable is not defined or if it is set to the name of a directory that does not exist, **_tempnam** will use the *dir* parameter as the path for which it will generate unique names. +- If the TMP environment variable isn't defined or if it's set to the name of a directory that doesn't exist, **`_tempnam`** uses the *`dir`* parameter as the path for which it generates unique names. -- If the TMP environment variable is not defined or if it is set to the name of a directory that does not exist, and if *dir* is either **NULL** or set to the name of a directory that does not exist, **_tempnam** will use the current working directory to generate unique names. Currently, if both TMP and *dir* specify names of directories that do not exist, the **_tempnam** function call will fail. +- If the TMP environment variable isn't defined or if it's set to the name of a directory that doesn't exist, and if *`dir`* is either `NULL` or set to the name of a directory that doesn't exist, **`_tempnam`** uses the current working directory to generate unique names. Currently, if both TMP and *`dir`* specify names of directories that don't exist, the **_tempnam** function call fails. -The name returned by **_tempnam** will be a concatenation of *prefix* and a sequential number, which will combine to create a unique file name for the specified directory. **_tempnam** generates file names that have no extension. **_tempnam** uses [malloc](malloc.md) to allocate space for the filename; the program is responsible for freeing this space when it is no longer needed. +The name returned by **`_tempnam`** is a concatenation of *`prefix`* and a sequential number, which combine to create a unique file name for the specified directory. **`_tempnam`** generates file names that have no extension. **`_tempnam`** uses [`malloc`](malloc.md) to allocate space for the filename; the program is responsible for freeing this space when it's no longer needed. -**_tempnam** and **tmpnam** automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **_wtempnam** is a wide-character version of **_tempnam**; the arguments and return value of **_wtempnam** are wide-character strings. **_wtempnam** and **_tempnam** behave identically except that **_wtempnam** does not handle multibyte-character strings. **_wtmpnam** is a wide-character version of **tmpnam**; the argument and return value of **_wtmpnam** are wide-character strings. **_wtmpnam** and **tmpnam** behave identically except that **_wtmpnam** does not handle multibyte-character strings. +**`_tempnam`** and **`tmpnam`** automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **`_wtempnam`** is a wide-character version of **`_tempnam`**; the arguments and return value of **`_wtempnam`** are wide-character strings. **`_wtempnam`** and **`_tempnam`** behave identically except that **`_wtempnam`** doesn't handle multibyte-character strings. **`_wtmpnam`** is a wide-character version of **`tmpnam`**; the argument and return value of **`_wtmpnam`** are wide-character strings. **`_wtmpnam`** and **`tmpnam`** behave identically except that **`_wtmpnam`** doesn't handle multibyte-character strings. -If **_DEBUG** and **_CRTDBG_MAP_ALLOC** are defined, **_tempnam** and **_wtempnam** are replaced by calls to [_tempnam_dbg and _wtempnam_dbg](tempnam-dbg-wtempnam-dbg.md). +If `_DEBUG` and `_CRTDBG_MAP_ALLOC` are defined, **`_tempnam`** and **`_wtempnam`** are replaced by calls to [`_tempnam_dbg` and `_wtempnam_dbg`](tempnam-dbg-wtempnam-dbg.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ttmpnam**|**tmpnam**|**tmpnam**|**_wtmpnam**| -|**_ttempnam**|**_tempnam**|**_tempnam**|**_wtempnam**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ttmpnam` | **`tmpnam`** | **`tmpnam`** | **`_wtmpnam`** | +| `_ttempnam` | **`_tempnam`** | **`_tempnam`** | **`_wtempnam`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tempnam**|\| -|**_wtempnam**, **_wtmpnam**|\ or \| -|**tmpnam**|\| +| Routine | Required header | +|---|---| +| **`_tempnam`** | \ | +| **`_wtempnam`**, **`_wtmpnam`** | \ or \ | +| **`tmpnam`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -135,7 +135,7 @@ int main(void) printf("Could not remove TMP environment variable.\n"); } - // With TMP unset, we will use C:\tmp as the temporary directory. + // With TMP unset, we'll use C:\tmp as the temporary directory. // Create a temporary filename in C:\tmp with prefix "stq". if ((name3 = _tempnam("c:\\tmp", "stq")) != NULL) { printf("%s is safe to use as a temporary file.\n", name3); @@ -161,9 +161,9 @@ c:\tmp\stq3 is safe to use as a temporary file. ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_getmbcp](getmbcp.md)
-[malloc](malloc.md)
-[_setmbcp](setmbcp.md)
-[tmpfile](tmpfile.md)
-[tmpfile_s](tmpfile-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`_getmbcp`](getmbcp.md)\ +[`malloc`](malloc.md)\ +[`_setmbcp`](setmbcp.md)\ +[`tmpfile`](tmpfile.md)\ +[`tmpfile_s`](tmpfile-s.md) diff --git a/docs/c-runtime-library/reference/tempnam.md b/docs/c-runtime-library/reference/tempnam.md index 6584eeedf14..230f6c67c22 100644 --- a/docs/c-runtime-library/reference/tempnam.md +++ b/docs/c-runtime-library/reference/tempnam.md @@ -6,12 +6,12 @@ api_name: ["tempnam"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tempnam"] +f1_keywords: ["STDIO/tempnam", "tempnam"] helpviewer_keywords: ["tempnam function"] ms.assetid: 42446733-f131-470f-b4d0-96918becab11 --- -# tempnam +# `tempnam` -The Microsoft-implemented POSIX function name `tempnam` is a deprecated alias for the [_tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `tempnam` is a deprecated alias for the [`_tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/terminate-crt.md b/docs/c-runtime-library/reference/terminate-crt.md index 3b0796229fa..cda2e499e59 100644 --- a/docs/c-runtime-library/reference/terminate-crt.md +++ b/docs/c-runtime-library/reference/terminate-crt.md @@ -3,16 +3,16 @@ description: "Learn more about: terminate (CRT)" title: "terminate (CRT)" ms.date: "4/2/2020" api_name: ["terminate", "_o_terminate"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["terminate"] +f1_keywords: ["CORECRT_TERMINATE/terminate", "EH/terminate", "terminate"] helpviewer_keywords: ["terminate function", "exception handling, termination"] ms.assetid: 90e67402-08e9-4b2a-962c-66a8afd3ccb4 --- -# terminate (CRT) +# `terminate` (CRT) -Calls [abort](abort.md) or a function you specify using **set_terminate**. +Calls [`abort`](abort.md) or a function you specify using `set_terminate`. ## Syntax @@ -22,25 +22,25 @@ void terminate( void ); ## Remarks -The **terminate** function is used with C++ exception handling and is called in the following cases: +The **`terminate`** function is used with C++ exception handling and is called in the following cases: -- A matching catch handler cannot be found for a thrown C++ exception. +- A matching catch handler can't be found for a thrown C++ exception. - An exception is thrown by a destructor function during stack unwind. - The stack is corrupted after throwing an exception. -**terminate** calls [abort](abort.md) by default. You can change this default by writing your own termination function and calling **set_terminate** with the name of your function as its argument. **terminate** calls the last function given as an argument to **set_terminate**. For more information, see [Unhandled C++ Exceptions](../../cpp/unhandled-cpp-exceptions.md). +**`terminate`** calls [`abort`](abort.md) by default. You can change this default by writing your own termination function and calling `set_terminate` with the name of your function as its argument. **`terminate`** calls the last function given as an argument to `set_terminate`. For more information, see [Unhandled C++ Exceptions](../../cpp/unhandled-cpp-exceptions.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**terminate**|\| +| Routine | Required header | +|---|---| +| **`terminate`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -90,9 +90,9 @@ term_func() was called by terminate(). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)
-[abort](abort.md)
-[_set_se_translator](set-se-translator.md)
-[set_terminate](set-terminate-crt.md)
-[set_unexpected](set-unexpected-crt.md)
-[unexpected](unexpected-crt.md)
+[Exception handling routines](../exception-handling-routines.md)\ +[`abort`](abort.md)\ +[`_set_se_translator`](set-se-translator.md)\ +[`set_terminate`](set-terminate-crt.md)\ +[`set_unexpected`](set-unexpected-crt.md)\ +[`unexpected`](unexpected-crt.md) diff --git a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md index e2a68366dd5..a8bb3f757de 100644 --- a/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md +++ b/docs/c-runtime-library/reference/tgamma-tgammaf-tgammal.md @@ -1,16 +1,15 @@ --- title: "tgamma, tgammaf, tgammal" description: "API reference for tgamma, tgammaf, and tgammal; which determine the gamma function of the specified value." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["tgamma", "tgammaf", "tgammal", "_o_tgamma", "_o_tgammaf", "_o_tgammal"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tgamma", "tgammaf", "tgammal", "math/tgamma", "math/tgammaf", "math/tgammal"] +f1_keywords: ["CORECRT_MATH/tgamma", "CORECRT_MATH/tgammaf", "CORECRT_MATH/tgammal", "tgamma", "tgammaf", "tgammal"] helpviewer_keywords: ["tgamma function", "tgammaf function", "tgammal function"] -ms.assetid: f1bd2681-8af2-48a9-919d-5358fd068acd --- -# tgamma, tgammaf, tgammal +# `tgamma`, `tgammaf`, `tgammal` Determines the gamma function of the specified value. @@ -29,7 +28,7 @@ long double tgammal( long double x ); -#define tgamma(X) // Requires C11 or higher +#define tgamma(X) // Requires C11 or later float tgamma( float x @@ -42,49 +41,49 @@ long double tgamma( ### Parameters -*x*\ +*`x`*\ The value to find the gamma of. -## Return Value +## Return value -If successful, returns the gamma of *x*. +If successful, returns the gamma of *`x`*. -A range error may occur if the magnitude of *x* is too large or too small for the data type. A domain error or range error may occur if *x* <= 0. +A range error may occur if the magnitude of *`x`* is too large or too small for the data type. A domain error or range error may occur if *`x`* <= 0. -|Issue|Return| -|-----------|------------| -|x = ±0|±INFINITY| -|x = negative integer|NaN| -|x = -INFINITY|NaN| -|x = +INFINITY|+INFINITY| -|x = NaN|NaN| -|domain error|NaN| -|pole error|±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL| -|overflow range error|±HUGE_VAL, ±HUGE_VALF, or ±HUGE_VALL| -|underflow range error|the correct value, after rounding.| +| Issue | Return | +|---|---| +| *`x`* = ±0 | ±INFINITY | +| *`x`* = negative integer | NaN | +| *`x`* = -INFINITY | NaN | +| *`x`* = +INFINITY | +INFINITY | +| *`x`* = NaN | NaN | +| domain error | NaN | +| pole error | ±`HUGE_VAL`, ±`HUGE_VALF`, or ±`HUGE_VALL` | +| overflow range error | ±`HUGE_VAL`, ±`HUGE_VALF`, or ±`HUGE_VALL` | +| underflow range error | the correct value, after rounding. | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **tgamma** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **tgamma** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`tgamma`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`tgamma`** always takes and returns a **`double`**. -If you use the \ `tgamma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `tgamma()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. If x is a natural number, this function returns the factorial of (x-1). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**tgamma**, **tgammaf**, **tgammal**|\|\| -|**tgamma** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`tgamma`**, **`tgammaf`**, **`tgammal`** | \ | \ | +| **`tgamma`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[lgamma, lgammaf, lgammal](lgamma-lgammaf-lgammal.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`lgamma`, `lgammaf`, `lgammal`](lgamma-lgammaf-lgammal.md) diff --git a/docs/c-runtime-library/reference/time-time32-time64.md b/docs/c-runtime-library/reference/time-time32-time64.md index 1eacd1fbe2f..8db058298e9 100644 --- a/docs/c-runtime-library/reference/time-time32-time64.md +++ b/docs/c-runtime-library/reference/time-time32-time64.md @@ -6,9 +6,8 @@ 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 --- # `time`, `_time32`, `_time64` @@ -17,33 +16,40 @@ Gets the system time. ## Syntax ```C -time_t time( time_t *destTime ); +time_t time( time_t *destTime ); // See note in remarks section about linkage __time32_t _time32( __time32_t *destTime ); __time64_t _time64( __time64_t *destTime ); ``` ### Parameters -*`destTime`*
+*`destTime`*\ Pointer to the storage location for time. -## Return Value +## Return value -Returns the time as seconds elapsed since midnight, January 1, 1970, or -1 in the case of an error. +Returns the time as seconds elapsed since midnight, January 1, 1970, or -1 if there's an error. ## Remarks -The **`time`** function returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Coordinated Universal Time (UTC), according to the system clock. The return value is stored in the location given by *`destTime`*. This parameter may be **`NULL`**, in which case the return value is not stored. +The **`time`** function returns the number of seconds elapsed since midnight (00:00:00), January 1, 1970, Coordinated Universal Time (UTC), according to the system clock. The return value is stored in the location given by *`destTime`*. This parameter may be `NULL`, in which case the return value isn't stored. -**`time`** is a wrapper for **`_time64`** and **`time_t`** is, by default, equivalent to **`__time64_t`**. If you need to force the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, you can define **`_USE_32BIT_TIME_T`**. This is not recommended because your application may fail after January 18, 2038; the use of this macro is not allowed on 64-bit platforms. +**`time_t`** is defined in `` and ``. It represents time as an integer count of seconds. It's equivalent to **`__time64_t`** by default, which is a 64-bit signed integer that supports dates through 23:59:59, December 31, 3000 UTC. If you need the compiler to interpret **`time_t`** as the old 32-bit **`time_t`**, define `_USE_32BIT_TIME_T`. We don't recommend `_USE_32BIT_TIME_T` because your application may fail after January 18, 2038. This macro isn't allowed on 64-bit platforms. + +**`time`** is a wrapper for **`_time64`**. + +> [!Note] +> When you use Windows SDK version 10.0.26100.6901 and Visual Studio 2026 or later together, `time` is no longer `static inline` (internal linkage). Instead, it's `inline` (external linkage).\ +> To return to the previous behavior, `#define _STATIC_INLINE_UCRT_FUNCTIONS=1` before including any CRT headers. By default, `_STATIC_INLINE_UCRT_FUNCTIONS` is set to 0.\ +> This change increases UCRT conformance with the C++ standard and improves compatibility with C++ modules. ## Requirements -|Routine|Required C header|Required C++ header| -|-------|------|---------------------| -|**`time`**, **`_time32`**, **`_time64`**|``|`` or ``| +| Routine | Required C header | Required C++ header | +|---|---|---| +| **`time`**, **`_time32`**, **`_time64`** | `` | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -199,12 +205,12 @@ Today is Friday, day 25 of April in the year 2003. ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[`asctime`, `_wasctime`](asctime-wasctime.md)
-[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)
-[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)
-[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)
-[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)
-[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)
-[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)
-[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md) diff --git a/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md b/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md index cad2b00f408..fea1cd33a5a 100644 --- a/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md +++ b/docs/c-runtime-library/reference/timespec-get-timespec32-get-timespec64-get1.md @@ -3,21 +3,21 @@ description: "Learn more about: timespec_get, _timespec32_get, _timespec64_get" title: "timespec_get, _timespec32_get, _timespec64_get1" ms.date: "4/2/2020" api_name: ["timespec_get", "_timespec32_get", "_timespec64_get", "_o__timespec32_get", "_o__timespec64_get"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["timespec_get", "_timespec32_get", "_timespec64_get", "time/timespec_get", "time/_timespec32_get", "time/_timespec64_get", "timespec", "_timespec32", "_timespec64"] +f1_keywords: ["TIME/timespec_get", "TIME/_timespec32_get", "TIME/_timespec64_get", "TIME/timespec", "TIME/_timespec32", "TIME/_timespec64", "timespec_get", "_timespec32_get", "_timespec64_get", "timespec", "_timespec32", "_timespec64"] helpviewer_keywords: ["timespec_get function", "_timespec32_get function", "_timespec64_get function"] ms.assetid: ed757258-b4f2-4c1d-a91b-22ea6ffce4ab --- -# timespec_get, _timespec32_get, _timespec64_get +# `timespec_get`, `_timespec32_get`, `_timespec64_get` Sets the interval pointed to by the first argument to the current calendar time, based on the specified time base. ## Syntax ```C -int timespec_get( +int timespec_get( // See note in remarks section about linkage struct timespec* const time_spec, int const base ); @@ -33,45 +33,50 @@ int _timespec64_get( ### Parameters -*time_spec*
+*`time_spec`*\ Pointer to a struct that is set to the time in seconds and nanoseconds since the start of the epoch. -*base*
+*`base`*\ A non-zero implementation-specific value that specifies the time base. -## Return Value +## Return value -The value of *base* if successful, otherwise it returns zero. +The value of *`base`* if successful, otherwise it returns zero. ## Remarks -The **timespec_get** functions set the current time in the struct pointed to by the *time_spec* argument. All versions of this struct have two members, **tv_sec** and **tv_nsec**. The **tv_sec** value is set to the whole number of seconds and **tv_nsec** to the integral number of nanoseconds, rounded to the resolution of the system clock, since the start of the epoch specified by *base*. +The **`timespec_get`** functions set the current time in the struct pointed to by the *`time_spec`* argument. All versions of this struct have two members, `tv_sec` and `tv_nsec`. The `tv_sec` value is set to the whole number of seconds and `tv_nsec` to the integral number of nanoseconds, rounded to the resolution of the system clock, since the start of the epoch specified by *`base`*. **Microsoft Specific** -These functions support only **TIME_UTC** as the *base* value. This sets the *time_spec* value to the number of seconds and nanoseconds since the epoch start, Midnight, January 1, 1970, Coordinated Universal Time (UTC). In a **`struct`** **_timespec32**, **tv_sec** is a **__time32_t** value. In a **`struct`** **_timespec64**, **tv_sec** is a **__time64_t** value. In a **`struct`** **timespec**, **tv_sec** is a **time_t** type, which is 32 bits or 64 bits in length depending on whether the preprocessor macro _USE_32BIT_TIME_T is defined. The **timespec_get** function is an inline function that calls **_timespec32_get** if _USE_32BIT_TIME_T is defined; otherwise it calls **_timespec64_get**. +These functions support only `TIME_UTC` as the *`base`* value. `TIME_UTC` sets the *`time_spec`* value to the number of seconds and nanoseconds since the epoch start, Midnight, January 1, 1970, Coordinated Universal Time (UTC). In a `_timespec32`, `tv_sec` is a `__time32_t` value. In a `_timespec64`, `tv_sec` is a `__time64_t` value. In a `timespec`, `tv_sec` is a `time_t` type, which is 32 bits or 64 bits in length depending on whether the preprocessor macro _USE_32BIT_TIME_T is defined. The **`timespec_get`** function is an inline function that calls **`_timespec32_get`** if `_USE_32BIT_TIME_T` is defined; otherwise it calls **`_timespec64_get`**. **End Microsoft Specific** -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). + +> [!Note] +> When you use Windows SDK version 10.0.26100.6901 and Visual Studio 2026 or later together, `timespec_get` is no longer `static inline` (internal linkage). Instead, it's `inline` (external linkage).\ +> To return to the previous behavior, `#define _STATIC_INLINE_UCRT_FUNCTIONS=1` before including any CRT headers. By default, `_STATIC_INLINE_UCRT_FUNCTIONS` is set to 0.\ +> This change increases UCRT conformance with the C++ standard and improves compatibility with C++ modules. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**timespec_get**, **_timespec32_get**, **_timespec64_get**|C: \, C++: \ or \| +| Routine | Required header | +|---|---| +| **`timespec_get`**, **`_timespec32_get`**, **`_timespec64_get`** | C: \, C++: \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[asctime_s, _wasctime_s](asctime-s-wasctime-s.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[gmtime_s, _gmtime32_s, _gmtime64_s](gmtime-s-gmtime32-s-gmtime64-s.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[localtime_s, _localtime32_s, _localtime64_s](localtime-s-localtime32-s-localtime64-s.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64](utime-utime32-utime64-wutime-wutime32-wutime64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`asctime_s`, `_wasctime_s`](asctime-s-wasctime-s.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`gmtime_s`, `_gmtime32_s`, `_gmtime64_s`](gmtime-s-gmtime32-s-gmtime64-s.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`localtime_s`, `_localtime32_s`, `_localtime64_s`](localtime-s-localtime32-s-localtime64-s.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md) diff --git a/docs/c-runtime-library/reference/tmpfile-s.md b/docs/c-runtime-library/reference/tmpfile-s.md index 788969ad754..d71b77dcea4 100644 --- a/docs/c-runtime-library/reference/tmpfile-s.md +++ b/docs/c-runtime-library/reference/tmpfile-s.md @@ -3,16 +3,16 @@ description: "Learn more about: tmpfile_s" title: "tmpfile_s" ms.date: "4/2/2020" api_name: ["tmpfile_s", "_o_tmpfile_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tmpfile_s"] +f1_keywords: ["STDIO/tmpfile_s", "tmpfile_s"] helpviewer_keywords: ["temporary files", "tmpfile_s function", "temporary files, creating"] ms.assetid: 50879c69-215e-425a-a2a3-8b5467121eae --- -# tmpfile_s +# `tmpfile_s` -Creates a temporary file. It is a version of [tmpfile](tmpfile.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Creates a temporary file. It's a version of [`tmpfile`](tmpfile.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -24,38 +24,38 @@ errno_t tmpfile_s( ### Parameters -*pFilePtr*
+*`pFilePtr`*\ The address of a pointer to store the address of the generated pointer to a stream. -## Return Value +## Return value Returns 0 if successful, an error code on failure. -### Error Conditions +### Error conditions -|*pFilePtr*|**Return Value**|**Contents of** *pFilePtr*| -|----------------|----------------------|---------------------------------| -|**NULL**|**EINVAL**|not changed| +| *`pFilePtr`* | Return value | Contents of *`pFilePtr`* | +|---|---|---| +| `NULL` | `EINVAL` | not changed | -If the above parameter validation error occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the return value is **EINVAL**. +If the above parameter validation error occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and the return value is `EINVAL`. ## Remarks -The **tmpfile_s** function creates a temporary file and puts a pointer to that stream in the *pFilePtr* argument. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [tmpnam_s](tmpnam-s-wtmpnam-s.md) or [tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) in conjunction with [fopen](fopen-wfopen.md). +The **`tmpfile_s`** function creates a temporary file and puts a pointer to that stream in the *`pFilePtr`* argument. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [`tmpnam_s`](tmpnam-s-wtmpnam-s.md) or [`tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) with [`fopen`](fopen-wfopen.md). -If the file cannot be opened, **tmpfile_s** writes **NULL** to the *pFilePtr* parameter. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when **_rmtmp** is called, assuming that the current working directory does not change. The temporary file is opened in **w+b** (binary read/write) mode. +If the file can't be opened, **`tmpfile_s`** writes `NULL` to the *`pFilePtr`* parameter. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when `_rmtmp` is called, assuming that the current working directory doesn't change. The temporary file is opened in **w+b** (binary read/write) mode. -Failure can occur if you attempt more than **TMP_MAX_S** (see STDIO.H) calls with **tmpfile_s**. +Failure can occur if you attempt more than `TMP_MAX_S` (see STDIO.H) calls with **`tmpfile_s`**. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tmpfile_s**|\| +| Routine | Required header | +|---|---| +| **`tmpfile_s`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -101,6 +101,6 @@ Temporary file 3 was created ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_rmtmp](rmtmp.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
+[Stream I/O](../stream-i-o.md)\ +[`_rmtmp`](rmtmp.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) diff --git a/docs/c-runtime-library/reference/tmpfile.md b/docs/c-runtime-library/reference/tmpfile.md index 28b33f49bb3..53f2b59e953 100644 --- a/docs/c-runtime-library/reference/tmpfile.md +++ b/docs/c-runtime-library/reference/tmpfile.md @@ -6,13 +6,13 @@ api_name: ["tmpfile"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tmpfile"] +f1_keywords: ["STDIO/tmpfile", "tmpfile"] helpviewer_keywords: ["temporary files", "tmpfile function", "temporary files, creating"] ms.assetid: c4a4dc24-70da-438d-ae4e-98352d88e375 --- -# tmpfile +# `tmpfile` -Creates a temporary file. This function is deprecated because a more secure version is available; see [tmpfile_s](tmpfile-s.md). +Creates a temporary file. This function is deprecated because a more secure version is available; see [`tmpfile_s`](tmpfile-s.md). ## Syntax @@ -20,25 +20,25 @@ Creates a temporary file. This function is deprecated because a more secure vers FILE *tmpfile( void ); ``` -## Return Value +## Return value -If successful, **tmpfile** returns a stream pointer. Otherwise, it returns a **NULL** pointer. +If successful, **`tmpfile`** returns a stream pointer. Otherwise, it returns a `NULL` pointer. ## Remarks -The **tmpfile** function creates a temporary file and returns a pointer to that stream. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [tmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md) or [tempnam](tempnam-wtempnam-tmpnam-wtmpnam.md) in conjunction with [fopen](fopen-wfopen.md). +The **`tmpfile`** function creates a temporary file and returns a pointer to that stream. The temporary file is created in the root directory. To create a temporary file in a directory other than the root, use [`tmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) or [`tempnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) with [`fopen`](fopen-wfopen.md). -If the file cannot be opened, **tmpfile** returns a **NULL** pointer. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when **_rmtmp** is called, assuming that the current working directory does not change. The temporary file is opened in **w+b** (binary read/write) mode. +If the file can't be opened, **`tmpfile`** returns a `NULL` pointer. This temporary file is automatically deleted when the file is closed, when the program terminates normally, or when `_rmtmp` is called, assuming that the current working directory doesn't change. The temporary file is opened in **w+b** (binary read/write) mode. -Failure can occur if you attempt more than TMP_MAX (see STDIO.H) calls with **tmpfile**. +Failure can occur if you attempt more than TMP_MAX (see STDIO.H) calls with **`tmpfile`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tmpfile**|\| +| Routine | Required header | +|---|---| +| **`tmpfile`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -81,6 +81,6 @@ Temporary file 3 was created ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_rmtmp](rmtmp.md)
-[_tempnam, _wtempnam, tmpnam, _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md)
+[Stream I/O](../stream-i-o.md)\ +[`_rmtmp`](rmtmp.md)\ +[`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) diff --git a/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md b/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md index 0d972689513..bb547ff8fe1 100644 --- a/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md +++ b/docs/c-runtime-library/reference/tmpnam-s-wtmpnam-s.md @@ -3,16 +3,16 @@ description: "Learn more about: tmpnam_s, _wtmpnam_s" title: "tmpnam_s, _wtmpnam_s" ms.date: "4/2/2020" api_name: ["tmpnam_s", "_wtmpnam_s", "_o__wtmpnam_s", "_o_tmpnam_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["tmpnam_s", "_wtmpnam_s", "L_tmpnam_s"] +f1_keywords: ["STDIO/tmpnam_s", "CORECRT_WSTDIO/_wtmpnam_s", "TCHAR/_ttmpnam_s", "STDIO/L_tmpnam_s", "tmpnam_s", "_wtmpnam_s", "_ttmpnam_s", "L_tmpnam_s"] helpviewer_keywords: ["tmpnam_s function", "file names [C++], creating temporary", "_wtmpnam_s function", "L_tmpnam_s constant", "temporary files, creating", "file names [C++], temporary", "wtmpnam_s function"] ms.assetid: e70d76dc-49f5-4aee-bfa2-f1baa2bcd29f --- -# tmpnam_s, _wtmpnam_s +# `tmpnam_s`, `_wtmpnam_s` -Generate names you can use to create temporary files. These are versions of [tmpnam and _wtmpnam](tempnam-wtempnam-tmpnam-wtmpnam.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Generate names you can use to create temporary files. These functions are versions of [`tmpnam` and `_wtmpnam`](tempnam-wtempnam-tmpnam-wtmpnam.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,51 +37,51 @@ errno_t _wtmpnam_s( ### Parameters -*str*
-Pointer that will hold the generated name. +*`str`*\ +[out] Pointer that holds the generated name. -*sizeInChars*
-The size of the buffer in characters. +*`sizeInChars`*\ +[in] The size of the buffer in characters. -## Return Value +## Return value Both of these functions return 0 if successful or an error number on failure. -### Error Conditions +### Error conditions -| *str* | *sizeInChars* | **Return Value** | **Contents of** *str* | +| *`str`* | *`sizeInChars`* | Return value | Contents of *`str`* | |--|--|--|--| -| **NULL** | any | **EINVAL** | not modified | -| not **NULL** (points to valid memory) | too short | **ERANGE** | not modified | +| `NULL` | any | `EINVAL` | not modified | +| not `NULL` (points to valid memory) | too short | `ERANGE` | not modified | -If *str* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions set **errno** to **EINVAL** and return **EINVAL**. +If *`str`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions set `errno` to `EINVAL` and return `EINVAL`. ## Remarks -Each of these functions returns the name of a file that does not currently exist. **tmpnam_s** returns a name unique in the designated Windows temporary directory returned by [GetTempPathW](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). Note than when a file name is pre-pended with a backslash and no path information, such as \fname21, this indicates that the name is valid for the current working directory. +Each of these functions returns the name of a file that doesn't currently exist. **`tmpnam_s`** returns a name unique in the designated Windows temporary directory returned by [`GetTempPathW`](/windows/win32/api/fileapi/nf-fileapi-gettemppathw). When a file name is prepended with a backslash and no path information, such as `\fname21`, it indicates that the name is valid for the current working directory. -For **tmpnam_s**, you can store this generated file name in *str*. The maximum length of a string returned by **tmpnam_s** is **L_tmpnam_s**, defined in STDIO.H. If *str* is **NULL**, then **tmpnam_s** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **tmpnam_s** consists of a program-generated file name and, after the first call to **tmpnam_s**, a file extension of sequential numbers in base 32 (.1-.1vvvvvu, when **TMP_MAX_S** in STDIO.H is **INT_MAX**). +For **`tmpnam_s`**, you can store this generated file name in *`str`*. The maximum length of a string returned by **`tmpnam_s`** is `L_tmpnam_s`, defined in STDIO.H. If *`str`* is `NULL`, then **`tmpnam_s`** leaves the result in an internal static buffer. Thus any subsequent calls destroy this value. The name generated by **`tmpnam_s`** consists of a program-generated file name and, after the first call to **`tmpnam_s`**, a file extension of sequential numbers in base 32 (.1-.1vvvvvu, when `TMP_MAX_S` in STDIO.H is `INT_MAX`). -**tmpnam_s** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **_wtmpnam_s** is a wide-character version of **tmpnam_s**; the argument and return value of **_wtmpnam_s** are wide-character strings. **_wtmpnam_s** and **tmpnam_s** behave identically except that **_wtmpnam_s** does not handle multibyte-character strings. +**`tmpnam_s`** automatically handles multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the OEM code page obtained from the operating system. **`_wtmpnam_s`** is a wide-character version of **`tmpnam_s`**; the argument and return value of **`_wtmpnam_s`** are wide-character strings. **`_wtmpnam_s`** and **`tmpnam_s`** behave identically except that **`_wtmpnam_s`** doesn't handle multibyte-character strings. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically, eliminating the need to specify a size argument. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ttmpnam_s**|**tmpnam_s**|**tmpnam_s**|**_wtmpnam_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ttmpnam_s` | **`tmpnam_s`** | **`tmpnam_s`** | **`_wtmpnam_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tmpnam_s**|\| -|**_wtmpnam_s**|\ or \| +| Routine | Required header | +|---|---| +| **`tmpnam_s`** | \ | +| **`_wtmpnam_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -136,8 +136,8 @@ C:\Users\LocalUser\AppData\Local\Temp\u19q8.e is safe to use as a temporary file ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_getmbcp](getmbcp.md)
-[malloc](malloc.md)
-[_setmbcp](setmbcp.md)
-[tmpfile_s](tmpfile-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`_getmbcp`](getmbcp.md)\ +[`malloc`](malloc.md)\ +[`_setmbcp`](setmbcp.md)\ +[`tmpfile_s`](tmpfile-s.md) diff --git a/docs/c-runtime-library/reference/toascii-toascii.md b/docs/c-runtime-library/reference/toascii-toascii.md index 5a4197c3b7e..590d1ddca7f 100644 --- a/docs/c-runtime-library/reference/toascii-toascii.md +++ b/docs/c-runtime-library/reference/toascii-toascii.md @@ -6,11 +6,11 @@ api_name: ["__toascii"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__toascii", "toascii", "ctype/toascii", "ctype/__toascii"] +f1_keywords: ["CTYPE/toascii", "CTYPE/__toascii", "__toascii", "toascii"] helpviewer_keywords: ["toascii function", "string conversion, to ASCII characters", "__toascii function", "ASCII characters, converting to"] ms.assetid: a07c0608-b0e2-4da2-a20c-7b64d6a9b77c --- -# toascii, __toascii +# `toascii`, `__toascii` Converts characters to 7-bit ASCII by truncation. @@ -25,29 +25,29 @@ int __toascii( ### Parameters -*c*
+*`c`*\ Character to convert. -## Return Value +## Return value -**__toascii** converts the value of *c* to the 7-bit ASCII range and returns the result. There is no return value reserved to indicate an error. +**`__toascii`** converts the value of *`c`* to the 7-bit ASCII range and returns the result. There's no return value reserved to indicate an error. ## Remarks -The **__toascii** routine converts the given character to an ASCII character by truncating it to the low-order 7 bits. No other transformation is applied. +The **`__toascii`** routine converts the given character to an ASCII character by truncating it to the low-order 7 bits. No other transformation is applied. -The **__toascii** routine is defined as a macro unless the preprocessor macro _CTYPE_DISABLE_MACROS is defined. For backward compatibility, **toascii** is defined as a macro only when [`__STDC__`](../../preprocessor/predefined-macros.md) is not defined or is defined as 0; otherwise it is undefined. +The **`__toascii`** routine is defined as a macro unless the preprocessor macro `_CTYPE_DISABLE_MACROS` is defined. For backward compatibility, **`toascii`** is defined as a macro only when [`__STDC__`](../../preprocessor/predefined-macros.md) isn't defined or is defined as 0; otherwise it's undefined. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**toascii**, **__toascii**|C: \

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

C++: \ or \ | -The **toascii** macro is a POSIX extension, and **__toascii** is a Microsoft-specific implementation of the POSIX extension. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`toascii`** macro is a POSIX extension, and **`__toascii`** is a Microsoft-specific implementation of the POSIX extension. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[to Functions](../../c-runtime-library/to-functions.md)
+[Data conversion](../data-conversion.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`to` functions](../to-functions.md) diff --git a/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md b/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md index 03095cd0286..1bdcdc5a05c 100644 --- a/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md +++ b/docs/c-runtime-library/reference/tolower-tolower-towlower-tolower-l-towlower-l.md @@ -3,14 +3,14 @@ description: "Learn more about: tolower, _tolower, towlower, _tolower_l, _towlow title: "tolower, _tolower, towlower, _tolower_l, _towlower_l" ms.date: "4/2/2020" api_name: ["_tolower_l", "towlower", "tolower", "_tolower", "_towlower_l", "_o__tolower", "_o__tolower_l", "_o__towlower_l", "_o_tolower", "_o_towlower"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_totlower", "tolower", "_tolower", "towlower"] +f1_keywords: ["CTYPE/tolower", "CTYPE/_tolower", "CTYPE/_tolower_l", "CORECRT_WCTYPE/towlower", "CORECRT_WCTYPE/_towlower_l", "TCHAR/_totlower", "TCHAR/_totlower_l", "tolower", "_tolower", "_tolower_l", "towlower", "_towlower_l", "_totlower", "_totlower_l"] helpviewer_keywords: ["tolower_l function", "_tolower_l function", "totlower function", "string conversion, to different characters", "lowercase, converting to", "tolower function", "string conversion, case", "towlower function", "_tolower function", "_totlower function", "towlower_l function", "case, converting", "characters, converting", "_towlower_l function"] ms.assetid: 86e0fc02-94ae-4472-9631-bf8e96f67b92 --- -# tolower, _tolower, towlower, _tolower_l, _towlower_l +# `tolower`, `_tolower`, `towlower`, `_tolower_l`, `_towlower_l` Converts a character to lowercase. @@ -38,52 +38,52 @@ int _towlower_l( ### Parameters -*c*
+*`c`*\ Character to convert. -*locale*
+*`locale`*\ Locale to use for locale-specific translation. -## Return Value +## Return value -Each of these routines converts a copy of *c* to lower case if the conversion is possible, and returns the result. There is no return value reserved to indicate an error. +Each of these routines converts a copy of *`c`* to lower case if the conversion is possible, and returns the result. There's no return value reserved to indicate an error. ## Remarks -Each of these routines converts a given uppercase letter to a lowercase letter if it is possible and relevant. The case conversion of **towlower** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the **_l** suffix use the currently set locale. The versions of these functions that have the **_l** suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../../c-runtime-library/locale.md). +Each of these routines converts a given uppercase letter to a lowercase letter if it's possible and relevant. The case conversion of **`towlower`** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the `_l` suffix use the currently set locale. The versions of these functions that have the `_l` suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). -In order for **_tolower** to give the expected results, [__isascii](isascii-isascii-iswascii.md) and [isupper](isupper-isupper-l-iswupper-iswupper-l.md) must both return nonzero. +In order for **`_tolower`** to give the expected results, [`__isascii`](isascii-isascii-iswascii.md) and [`isupper`](isupper-isupper-l-iswupper-iswupper-l.md) must both return nonzero. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_totlower**|**tolower**|**_mbctolower**|**towlower**| -|**_totlower_l**|**_tolower_l**|**_mbctolower_l**|**_towlower_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_totlower` | **`tolower`** | `_mbctolower` | **`towlower`** | +| `_totlower_l` | **`_tolower_l`** | `_mbctolower_l` | **`_towlower_l`** | > [!NOTE] -> **_tolower_l** and **_towlower_l** have no locale dependence and are not meant to be called directly. They are provided for internal use by **_totlower_l**. +> **`_tolower_l`** and **`_towlower_l`** have no locale dependence and are not meant to be called directly. They are provided for internal use by **`_totlower_l`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**tolower**|\| -|**_tolower**|\| -|**towlower**|\ or \| +| Routine | Required header | +|---|---| +| **`tolower`** | \ | +| **`_tolower`** | \ | +| **`towlower`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [to Functions](../../c-runtime-library/to-functions.md). +See the example in [`to` functions](../to-functions.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[to Functions](../../c-runtime-library/to-functions.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
+[Data conversion](../data-conversion.md)\ +[`is`, `isw` routines](../is-isw-routines.md)\ +[`to` functions](../to-functions.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md b/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md index ee174af35d8..0e89d73c470 100644 --- a/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md +++ b/docs/c-runtime-library/reference/toupper-toupper-towupper-toupper-l-towupper-l.md @@ -3,14 +3,13 @@ description: "Learn more about: toupper, _toupper, towupper, _toupper_l, _towupp title: "toupper, _toupper, towupper, _toupper_l, _towupper_l" ms.date: "4/2/2020" api_name: ["_toupper_l", "towupper", "toupper", "_towupper_l", "_toupper", "_o__toupper", "_o__toupper_l", "_o__towupper_l", "_o_toupper", "_o_towupper"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["towupper", "_toupper", "_totupper", "toupper"] +f1_keywords: ["CTYPE/toupper", "CTYPE/_toupper", "CTYPE/_toupper_l", "CORECRT_WCTYPE/towupper", "CORECRT_WCTYPE/_towupper_l", "TCHAR/_totupper", "TCHAR/_totupper_l", "toupper", "_toupper", "_toupper_l", "towupper", "_towupper_l", "_totupper", "_totupper_l"] helpviewer_keywords: ["_toupper function", "towupper function", "uppercase, converting strings to", "totupper function", "string conversion, to different characters", "towupper_l function", "toupper_l function", "string conversion, case", "_toupper_l function", "_towupper_l function", "_totupper function", "case, converting", "characters, converting", "toupper function"] -ms.assetid: cdef1b0f-b19c-4d11-b7d2-cf6334c9b6cc --- -# toupper, _toupper, towupper, _toupper_l, _towupper_l +# `toupper`, `_toupper`, `towupper`, `_toupper_l`, `_towupper_l` Convert character to uppercase. @@ -38,59 +37,55 @@ int _towupper_l( ### Parameters -*c*
+*`c`*\ Character to convert. -*locale*
+*`locale`*\ Locale to use. -## Return Value +## Return value -Each of these routines converts a copy of *c*, if possible, and returns the result. +Each of these routines converts a copy of *`c`*, if possible, and returns the result. -If *c* is a wide character for which **iswlower** is nonzero and there is a corresponding wide character for which [iswupper](isupper-isupper-l-iswupper-iswupper-l.md) is nonzero, **towupper** returns the corresponding wide character; otherwise, **towupper** returns *c* unchanged. +If *`c`* is a wide character for which `iswlower` is nonzero and there's a corresponding wide character for which [`iswupper`](isupper-isupper-l-iswupper-iswupper-l.md) is nonzero, **`towupper`** returns the corresponding wide character; otherwise, **`towupper`** returns *`c`* unchanged. -There is no return value reserved to indicate an error. - -In order for **toupper** to give the expected results, [__isascii](isascii-isascii-iswascii.md) and [islower](islower-iswlower-islower-l-iswlower-l.md) must both return nonzero. +There's no return value reserved to indicate an error. ## Remarks -Each of these routines converts a given lowercase letter to an uppercase letter if possible and appropriate. The case conversion of **towupper** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the **_l** suffix use the currently set locale. The versions of these functions with the **_l** suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../../c-runtime-library/locale.md). - -In order for **toupper** to give the expected results, [__isascii](isascii-isascii-iswascii.md) and [isupper](isupper-isupper-l-iswupper-iswupper-l.md) must both return nonzero. +Each of these routines converts a given lowercase letter to an uppercase letter if possible and appropriate. The case conversion of **`towupper`** is locale-specific. Only the characters relevant to the current locale are changed in case. The functions without the `_l` suffix use the currently set locale. The versions of these functions with the `_l` suffix take the locale as a parameter and use that instead of the currently set locale. For more information, see [Locale](../locale.md). -[Data Conversion Routines](../../c-runtime-library/data-conversion.md) +For **`toupper`** to give the expected results, [`__isascii`](isascii-isascii-iswascii.md) must return nonzero. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_totupper**|**toupper**|**_mbctoupper**|**towupper**| -|**_totupper_l**|**_toupper_l**|**_mbctoupper_l**|**_towupper_l**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_totupper` | **`toupper`** | **`_mbctoupper`** | **`towupper`** | +| `_totupper_l` | **`_toupper_l`** | **`_mbctoupper_l`** | **`_towupper_l`** | > [!NOTE] -> **_toupper_l** and **_towupper_l** have no locale dependence and are not meant to be called directly. They are provided for internal use by **_totupper_l**. +> **`_toupper_l`** and **`_towupper_l`** have no locale dependence and are not meant to be called directly. They are provided for internal use by **`_totupper_l`**. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**toupper**|\| -|**_toupper**|\| -|**towupper**|\ or \| +| Routine | Required header | +|---|---| +| **`toupper`** | \ | +| **`_toupper`** | \ | +| **`towupper`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example in [to Functions](../../c-runtime-library/to-functions.md). +See the example in [`to` functions](../to-functions.md). ## See also -[is, isw Routines](../../c-runtime-library/is-isw-routines.md)
-[to Functions](../../c-runtime-library/to-functions.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
+[`is`, `isw` routines](../is-isw-routines.md)\ +[`to` functions](../to-functions.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md) diff --git a/docs/c-runtime-library/reference/towctrans.md b/docs/c-runtime-library/reference/towctrans.md index 617720b5bb3..6cf88abded3 100644 --- a/docs/c-runtime-library/reference/towctrans.md +++ b/docs/c-runtime-library/reference/towctrans.md @@ -6,11 +6,11 @@ api_name: ["towctrans"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["towctrans"] +f1_keywords: ["WCTYPE/towctrans", "towctrans"] helpviewer_keywords: ["towctrans function"] ms.assetid: 1ed1e70d-7b31-490f-a7d9-42564b5924ca --- -# towctrans +# `towctrans` Transforms a character. @@ -25,32 +25,32 @@ wint_t towctrans( ### Parameters -*c*
+*`c`*\ The character you want to transform. -*category*
-An identifier that contains the return value of [wctrans](wctrans.md). +*`category`*\ +An identifier that contains the return value of [`wctrans`](wctrans.md). -## Return Value +## Return value -The character *c*, after **towctrans** used the transform rule in *category*. +The character *`c`*, after **`towctrans`** used the transform rule in *`category`*. ## Remarks -The value of *category* must have been returned by an earlier successful call to [wctrans](wctrans.md). +The value of *`category`* must have been returned by an earlier successful call to [`wctrans`](wctrans.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**towctrans**|\| +| Routine | Required header | +|---|---| +| **`towctrans`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See **wctrans** for a sample that uses **towctrans**. +See `wctrans` for a sample that uses **`towctrans`**. ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
+[Data conversion](../data-conversion.md) diff --git a/docs/c-runtime-library/reference/trunc-truncf-truncl.md b/docs/c-runtime-library/reference/trunc-truncf-truncl.md index eddefce9603..19205505760 100644 --- a/docs/c-runtime-library/reference/trunc-truncf-truncl.md +++ b/docs/c-runtime-library/reference/trunc-truncf-truncl.md @@ -1,16 +1,15 @@ --- title: "trunc, truncf, truncl" description: "API reference for trunc, truncf, truncl; which determine the nearest integer that is less than or equal to the specified floating-point value." -ms.date: "9/1/2020" +ms.date: 9/1/2020 api_name: ["trunc", "truncf", "truncl"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["trunc", "truncf", "truncl", "math/trunc", "math/truncf", "math/truncl"] +f1_keywords: ["CORECRT_MATH/trunc", "CORECRT_MATH/truncf", "CORECRT_MATH/truncl", "math/trunc", "math/truncf", "math/truncl", "trunc", "truncf", "truncl"] helpviewer_keywords: ["trunc function", "truncf function", "truncl function"] -ms.assetid: de2038ac-ac0b-483e-870c-e8992dcd4fd0 --- -# trunc, truncf, truncl +# `trunc`, `truncf`, `truncl` Determines the nearest integer that is less than or equal to the specified floating-point value. @@ -19,7 +18,7 @@ Determines the nearest integer that is less than or equal to the specified float ```C double trunc( double x ); long double truncl( long double x ); -#define trunc(X) // Requires C11 or higher +#define trunc(X) // Requires C11 or later long double trunc( long double x ); //C++ only float trunc( float x ); //C++ only @@ -27,45 +26,45 @@ float trunc( float x ); //C++ only ### Parameters -*x*\ +*`x`*\ The value to truncate. -## Return Value +## Return value -If successful, returns an integer value of *x*, rounded towards zero. +If successful, the functions return an integer value of *`x`*, rounded towards zero. -Otherwise, may return one of the following: +Otherwise, the functions may return one of the following values: -|Issue|Return| -|-----------|------------| -|*x* = ±INFINITY|x| -|*x* = ±0|x| -|*x* = NaN|NaN| +| Issue | Return | +|---|---| +| *`x`* = ±INFINITY | x | +| *`x`* = ±0 | x | +| *`x`* = NaN | NaN | -Errors are reported as specified in [_matherr](matherr.md). +Errors are reported as specified in [`_matherr`](matherr.md). ## Remarks -Because C++ allows overloading, you can call overloads of **trunc** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **trunc** always takes and returns a **`double`**. +Because C++ allows overloading, you can call overloads of **`trunc`** that take and return **`float`** and **`long double`** types. In a C program, unless you're using the \ macro to call this function, **`trunc`** always takes and returns a **`double`**. -If you use the \ `trunc()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../../c-runtime-library/tgmath.md) for details. +If you use the \ `trunc()` macro, the type of the argument determines which version of the function is selected. See [Type-generic math](../tgmath.md) for details. -Because the largest floating-point values are exact integers, this function will not overflow on its own. However, you may cause the function to overflow by returning a value into an integer type. +Because the largest floating-point values are exact integers, this function won't overflow on its own. However, you may cause the function to overflow by returning a value into an integer type. You can also round down by implicitly converting from floating-point to integral; however, doing so is limited to the values that can be stored in the target type. ## Requirements -|Function|C header|C++ header| -|--------------|--------------|------------------| -|**trunc**, **truncf**, **truncl**|\|\| -|**trunc** macro | \ || +| Function | C header | C++ header | +|---|---|---| +| **`trunc`**, **`truncf`**, **`truncl`** | \ | \ | +| **`trunc`** macro | \ | | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Alphabetical Function Reference](crt-alphabetical-function-reference.md)
-[floor, floorf, floorl](floor-floorf-floorl.md)
-[ceil, ceilf, ceill](ceil-ceilf-ceill.md)
-[round, roundf, roundl](round-roundf-roundl.md)
+[Alphabetical function reference](crt-alphabetical-function-reference.md)\ +[`floor`, `floorf`, `floorl`](floor-floorf-floorl.md)\ +[`ceil`, `ceilf`, `ceill`](ceil-ceilf-ceill.md)\ +[`round`, `roundf`, `roundl`](round-roundf-roundl.md) diff --git a/docs/c-runtime-library/reference/tzset.md b/docs/c-runtime-library/reference/tzset.md index 1dfc4e1b3ae..23fcafc53dc 100644 --- a/docs/c-runtime-library/reference/tzset.md +++ b/docs/c-runtime-library/reference/tzset.md @@ -3,14 +3,14 @@ description: "Learn more about: _tzset" title: "_tzset" ms.date: "4/2/2020" api_name: ["_tzset", "_o__tzset"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tzset"] +f1_keywords: ["TIME/_tzset", "_tzset"] helpviewer_keywords: ["_tzset function", "time environment variables", "environment variables, setting time"] ms.assetid: 3f6ed537-b414-444d-b272-5dd377481930 --- -# _tzset +# `_tzset` Sets time environment variables. @@ -25,56 +25,56 @@ void _tzset( void ); ## Remarks -The **_tzset** function uses the current setting of the environment variable **TZ** to assign values to three global variables: **_daylight**, **_timezone**, and **_tzname**. These variables are used by the [_ftime](ftime-ftime32-ftime64.md) and [localtime](localtime-localtime32-localtime64.md) functions to make corrections from coordinated universal time (UTC) to local time, and by the [time](time-time32-time64.md) function to compute UTC from system time. Use the following syntax to set the **TZ** environment variable: +The **`_tzset`** function uses the current setting of the environment variable **`TZ`** to assign values to three global variables: `_daylight`, `_timezone`, and `_tzname`. These variables are used by the [`_ftime`](ftime-ftime32-ftime64.md) and [`localtime`](localtime-localtime32-localtime64.md) functions to make corrections from coordinated universal time (UTC) to local time, and by the [`time`](time-time32-time64.md) function to compute UTC from system time. Use the following syntax to set the **`TZ`** environment variable: -> **set TZ=**_tzn_ \[**+**|**-**]*hh*\[**:**_mm_\[**:**_ss_] ][*dzn*] +> **`set TZ=`***`tzn`* \[**`+`**|**`-`**]*`hh`*\[**`:`***`mm`*\[**:***`ss`*] ][*`dzn`*] - *tzn* \ + *`tzn`* \ Three-letter time-zone name, such as PST. You must specify the correct offset from local time to UTC. - *hh* \ + *`hh`* \ Difference in hours between UTC and local time. Sign (+) optional for positive values. - *mm* \ - Minutes. Separated from *hh* by a colon (**:**). + *`mm`* \ + Minutes. Separated from *`hh`* by a colon (**`:`**). - *ss* \ - Seconds. Separated from *mm* by a colon (**:**). + *`ss`* \ + Seconds. Separated from *`mm`* by a colon (**`:`**). - *dzn* \ - Three-letter daylight-saving-time zone such as PDT. If daylight saving time is never in effect in the locality, set **TZ** without a value for *dzn*. The C run-time library assumes the United States' rules for implementing the calculation of daylight saving time (DST). + *`dzn`* \ + Three-letter daylight-saving-time zone such as PDT. If daylight saving time is never in effect in the locality, set **`TZ`** without a value for *`dzn`*. The C run-time library assumes the United States' rules for implementing the calculation of daylight saving time (DST). > [!NOTE] > Take care in computing the sign of the time difference. Because the time difference is the offset from local time to UTC (rather than the reverse), its sign may be the opposite of what you might intuitively expect. For time zones ahead of UTC, the time difference is negative; for those behind UTC, the difference is positive. -For example, to set the **TZ** environment variable to correspond to the current time zone in Germany, enter the following on the command line: +For example, to set the **`TZ`** environment variable to correspond to the current time zone in Germany, enter this command on the command line: > **set TZ=GST-1GDT** -This command uses GST to indicate German standard time, assumes that UTC is one hour behind Germany (or in other words, that Germany is one hour ahead of UTC), and assumes that Germany observes daylight-saving time. +This command uses GST to indicate German standard time. It assumes that UTC is one hour behind Germany (or in other words, that Germany is one hour ahead of UTC). And, it assumes that Germany observes daylight-saving time. -If the **TZ** value is not set, **_tzset** attempts to use the time zone information specified by the operating system. In the Windows operating system, this information is specified in the Date/Time application in Control Panel. If **_tzset** cannot obtain this information, it uses PST8PDT by default, which signifies the Pacific Time zone. +If the **`TZ`** value isn't set, **`_tzset`** attempts to use the time zone information specified by the operating system. In the Windows operating system, this information is specified in the Date/Time application in Control Panel. If **`_tzset`** can't obtain this information, it uses PST8PDT by default, which signifies the Pacific Time zone. -Based on the **TZ** environment variable value, the following values are assigned to the global variables **_daylight**, **_timezone**, and **_tzname** when **_tzset** is called: +Based on the **`TZ`** environment variable value, the following values are assigned to the global variables `_daylight`, `_timezone`, and `_tzname` when **`_tzset`** is called: -|Global variable|Description|Default value| -|---------------------|-----------------|-------------------| -|**_daylight**|Nonzero value if a daylight-saving-time zone is specified in **TZ** setting; otherwise, 0.|1| -|**_timezone**|Difference in seconds between local time and UTC.|28800 (28800 seconds equals 8 hours)| -|**_tzname**[0]|String value of time-zone name from **TZ** environmental variable; empty if **TZ** has not been set.|PST| -|**_tzname**[1]|String value of daylight-saving-time zone; empty if daylight-saving-time zone is omitted from **TZ** environmental variable.|PDT| +| Global variable | Description | Default value | +|---|---|---| +| `_daylight` | Nonzero value if a daylight-saving-time zone is specified in **`TZ`** setting; otherwise, 0. | 1 | +| `_timezone` | Difference in seconds between local time and UTC. | 28800 (28,800 seconds equals 8 hours) | +| `_tzname[0]` | String value of time-zone name from **`TZ`** environmental variable; empty if **`TZ`** hasn't been set. | PST | +| `_tzname[1]` | String value of daylight-saving-time zone; empty if daylight-saving-time zone is omitted from **`TZ`** environmental variable. | PDT | -The default values shown in the preceding table for **_daylight** and the **_tzname** array correspond to "PST8PDT." If the DST zone is omitted from the **TZ** environmental variable, the value of **_daylight** is 0 and the [_ftime](ftime-ftime32-ftime64.md), [gmtime](gmtime-gmtime32-gmtime64.md), and [localtime](localtime-localtime32-localtime64.md) functions return 0 for their DST flags. +The default values shown in the preceding table for `_daylight` and the `_tzname` array correspond to "PST8PDT." If the DST zone is omitted from the **`TZ`** environmental variable, the value of `_daylight` is 0 and the [`_ftime`](ftime-ftime32-ftime64.md), [`gmtime`](gmtime-gmtime32-gmtime64.md), and [`localtime`](localtime-localtime32-localtime64.md) functions return 0 for their DST flags. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_tzset**|\| +| Routine | Required header | +|---|---| +| **`_tzset`** | \ | -The **_tzset** function is Microsoft-specific. For more information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_tzset`** function is Microsoft-specific. For more information, see [Compatibility](../compatibility.md). ## Example @@ -113,10 +113,10 @@ _tzname[0] = Pacific Standard Time ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[time, _time32, _time64](time-time32-time64.md)
-[_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64](utime-utime32-utime64-wutime-wutime32-wutime64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md)\ +[`_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64`](utime-utime32-utime64-wutime-wutime32-wutime64.md) diff --git a/docs/c-runtime-library/reference/umask-s.md b/docs/c-runtime-library/reference/umask-s.md index 2460098e1c6..04e1a094fae 100644 --- a/docs/c-runtime-library/reference/umask-s.md +++ b/docs/c-runtime-library/reference/umask-s.md @@ -3,7 +3,7 @@ description: "Learn more about: _umask_s" title: "_umask_s" ms.date: 05/18/2022 api_name: ["_umask_s", "_o__umask_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CORECRT_IO/_umask_s", "_umask_s", "umask_s"] @@ -12,7 +12,7 @@ ms.assetid: 70898f61-bf2b-4d8d-8291-0ccaa6d33145 --- # `_umask_s` -Sets the default file-permission mask. A version of [`_umask`](umask.md) with security enhancements as described in [Security features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Sets the default file-permission mask. A version of [`_umask`](umask.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -33,16 +33,16 @@ The previous value of the permission setting. ## Return value -Returns an error code if *`mode`* doesn't specify a valid mode or the *`pOldMode`* pointer is **`NULL`**. +Returns an error code if *`mode`* doesn't specify a valid mode or the *`pOldMode`* pointer is `NULL`. ### Error conditions | *`mode`* | *`pOldMode`* | Return value | Contents of *`pOldMode`* | |--|--|--|--| -| any | **`NULL`** | **`EINVAL`** | not modified | -| invalid mode | any | **`EINVAL`** | not modified | +| any | `NULL` | `EINVAL` | not modified | +| invalid mode | any | `EINVAL` | not modified | -If one of the above conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **`_umask_s`** returns **`EINVAL`** and sets **`errno`** to **`EINVAL`**. +If one of the above conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`_umask_s`** returns `EINVAL` and sets `errno` to `EINVAL`. ## Remarks @@ -52,11 +52,11 @@ The integer expression *`mode`* contains one or both of the following manifest c | *`mode`* | Description | |--|--| -| **`_S_IWRITE`** | Writing permitted. | -| **`_S_IREAD`** | Reading permitted. | +| `_S_IWRITE` | Writing permitted. | +| `_S_IREAD` | Reading permitted. | | **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). If the *`mode`* argument is **`_S_IREAD`**, reading isn't allowed (the file is write-only). If the *`mode`* argument is **`_S_IWRITE`**, writing isn't allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. In MS-DOS and the Windows operating systems, all files are readable; it isn't possible to give write-only permission. Therefore, setting the read bit with **`_umask_s`** has no effect on the file's modes. +When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). If the *`mode`* argument is `_S_IREAD`, reading isn't allowed (the file is write-only). If the *`mode`* argument is `_S_IWRITE`, writing isn't allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. In MS-DOS and the Windows operating systems, all files are readable; it isn't possible to give write-only permission. Therefore, setting the read bit with **`_umask_s`** has no effect on the file's modes. If *`mode`* isn't a combination of one of the manifest constants or incorporates an alternate set of constants, the function ignores them. @@ -68,7 +68,7 @@ By default, this function's global state is scoped to the application. To change |--|--| | **`_umask_s`** | `` and `` and `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,8 +106,8 @@ Oldmask = 0x0000 ## See also -[File handling](../../c-runtime-library/file-handling.md)\ -[Low-level I/O](../../c-runtime-library/low-level-i-o.md)\ +[File handling](../file-handling.md)\ +[Low-level I/O](../low-level-i-o.md)\ [`_chmod`, `_wchmod`](chmod-wchmod.md)\ [`_creat`, `_wcreat`](creat-wcreat.md)\ [`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ diff --git a/docs/c-runtime-library/reference/umask.md b/docs/c-runtime-library/reference/umask.md index 630ea527d17..015b0b81ead 100644 --- a/docs/c-runtime-library/reference/umask.md +++ b/docs/c-runtime-library/reference/umask.md @@ -3,7 +3,7 @@ title: "_umask" description: "API reference for _umask; which sets the default file-permission mask." ms.date: "4/2/2020" api_name: ["_umask", "_o__umask"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["CORECRT_IO/_umask", "_umask"] @@ -37,11 +37,11 @@ The integer expression *`pmode`* contains one or both of the following manifest | *`pmode`* | Description | |--|--| -| **`_S_IWRITE`** | Writing permitted. | -| **`_S_IREAD`** | Reading permitted. | +| `_S_IWRITE` | Writing permitted. | +| `_S_IREAD` | Reading permitted. | | **`_S_IREAD | _S_IWRITE`** | Reading and writing permitted. | -When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). If the *`pmode`* argument is **`_S_IREAD`**, reading isn't allowed (the file is write-only). If the *`pmode`* argument is **`_S_IWRITE`**, writing isn't allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. In MS-DOS and the Windows operating systems, all files are readable; it isn't possible to give write-only permission. Therefore, setting the read bit with **`_umask`** has no effect on the file's modes. +When both constants are given, they're joined with the bitwise-OR operator ( **`|`** ). If the *`pmode`* argument is `_S_IREAD`, reading isn't allowed (the file is write-only). If the *`pmode`* argument is `_S_IWRITE`, writing isn't allowed (the file is read-only). For example, if the write bit is set in the mask, any new files will be read-only. In MS-DOS and the Windows operating systems, all files are readable; it isn't possible to give write-only permission. Therefore, setting the read bit with **`_umask`** has no effect on the file's modes. If *`pmode`* isn't a combination of one of the manifest constants or incorporates an alternate set of constants, the function ignores them. @@ -53,11 +53,11 @@ By default, this function's global state is scoped to the application. To change |--|--| | **`_umask`** | ``, ``, `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -90,8 +90,8 @@ Oldmask = 0x0000 ## See also -[File handling](../../c-runtime-library/file-handling.md)\ -[Low-level I/O](../../c-runtime-library/low-level-i-o.md)\ +[File handling](../file-handling.md)\ +[Low-level I/O](../low-level-i-o.md)\ [`_chmod`, `_wchmod`](chmod-wchmod.md)\ [`_creat`, `_wcreat`](creat-wcreat.md)\ [`_mkdir`, `_wmkdir`](mkdir-wmkdir.md)\ diff --git a/docs/c-runtime-library/reference/uncaught-exception.md b/docs/c-runtime-library/reference/uncaught-exception.md index 00c1d2c8da7..9cb0108509d 100644 --- a/docs/c-runtime-library/reference/uncaught-exception.md +++ b/docs/c-runtime-library/reference/uncaught-exception.md @@ -1,38 +1,34 @@ --- -description: "Learn more about: __uncaught_exception" title: "__uncaught_exception" -ms.date: "1/14/2021" +description: "Learn more about: __uncaught_exception" +ms.date: 1/14/2021 api_name: ["__uncaught_exception"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__uncaught_exception"] +f1_keywords: ["EH/__uncaught_exception"] helpviewer_keywords: ["__uncaught_exception"] -ms.assetid: 4d9b75c6-c9c7-4876-b761-ea9ab1925e96 --- -# __uncaught_exception +# `__uncaught_exception` -Indicates whether one or more exceptions have been thrown, but have not yet been handled by the corresponding **`catch`** block of a [try-catch](../../cpp/try-throw-and-catch-statements-cpp.md) statement. +Indicates whether one or more exceptions have been thrown, but haven't yet been handled by the corresponding **`catch`** block of a [try-catch](../../cpp/try-throw-and-catch-statements-cpp.md) statement. ## Syntax ```cpp -bool __uncaught_exception( - ); +bool __uncaught_exception(); ``` -## Return Value +## Return value **`true`** from the time an exception is thrown in a **`try`** block until the matching **`catch`** block is initialized; otherwise, **`false`**. -## Remarks - ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__uncaught_exception|eh.h| +| Routine | Required header | +|---|---| +| **`__uncaught_exception`** | `` | ## See also -[try, throw, and catch Statements (C++)](../../cpp/try-throw-and-catch-statements-cpp.md)
+[try, throw, and catch Statements (C++)](../../cpp/try-throw-and-catch-statements-cpp.md) diff --git a/docs/c-runtime-library/reference/unexpected-crt.md b/docs/c-runtime-library/reference/unexpected-crt.md index 0127f107599..a1fabd706f3 100644 --- a/docs/c-runtime-library/reference/unexpected-crt.md +++ b/docs/c-runtime-library/reference/unexpected-crt.md @@ -3,10 +3,10 @@ description: "Learn more about: unexpected (CRT)" title: "unexpected (CRT)" ms.date: "1/14/2021" api_name: ["unexpected"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["unexpected"] +f1_keywords: ["EH/unexpected"] helpviewer_keywords: ["unexpected function"] ms.assetid: 2f873763-15ad-4556-a924-dcf28f2b52b4 --- @@ -26,17 +26,17 @@ The **`unexpected`** routine isn't used with the current implementation of C++ e ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`unexpected`**|``| +| Routine | Required header | +|---|---| +| **`unexpected`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Exception Handling Routines](../../c-runtime-library/exception-handling-routines.md)
-[abort](abort.md)
-[_set_se_translator](set-se-translator.md)
-[set_terminate](set-terminate-crt.md)
-[set_unexpected](set-unexpected-crt.md)
-[terminate](terminate-crt.md)
+[Exception handling routines](../exception-handling-routines.md)\ +[`abort`](abort.md)\ +[`_set_se_translator`](set-se-translator.md)\ +[`set_terminate`](set-terminate-crt.md)\ +[`set_unexpected`](set-unexpected-crt.md)\ +[`terminate`](terminate-crt.md) diff --git a/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md b/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md index e50a89d8682..eba0a2a0495 100644 --- a/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md +++ b/docs/c-runtime-library/reference/ungetc-nolock-ungetwc-nolock.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: _ungetc_nolock, _ungetwc_nolock" title: "_ungetc_nolock, _ungetwc_nolock" +description: "Learn more about: _ungetc_nolock, _ungetwc_nolock" ms.date: "4/2/2020" api_name: ["_ungetwc_nolock", "_ungetc_nolock", "_o__ungetc_nolock", "_o__ungetwc_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_ungettc_nolock", "ungetwc_nolock", "ungetc_nolock", "_ungetc_nolock", "_ungetwc_nolock"] +f1_keywords: ["STDIO/_ungetc_nolock", "CORECRT_WSTDIO/_ungetwc_nolock", "TCHAR/_ungettc_nolock", "_ungetc_nolock", "_ungetwc_nolock", "_ungettc_nolock"] helpviewer_keywords: ["_ungettc_nolock function", "_ungetwc_nolock function", "characters, pushing back onto stream", "_ungetc_nolock function", "ungetwc_nolock function", "ungettc_nolock function", "ungetc_nolock function"] -ms.assetid: aa02d5c2-1be1-46d2-a8c4-b61269e9d465 --- -# _ungetc_nolock, _ungetwc_nolock +# `_ungetc_nolock`, `_ungetwc_nolock` -Pushes a character back onto the stream. +Pushes a character back onto the stream without locking. ## Syntax @@ -29,41 +28,41 @@ wint_t _ungetwc_nolock( ### Parameters -*c*
+*`c`*\ Character to be pushed. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -If successful, each of these functions returns the character argument *c*. If *c* cannot be pushed back or if no character has been read, the input stream is unchanged and **_ungetc_nolock** returns **EOF**; **_ungetwc_nolock** returns **WEOF**. If *stream* is **NULL**, **EOF** or **WEOF** is returned and **errno** is set to **EINVAL**. +If successful, each of these functions returns the character argument *`c`*. If *`c`* can't be pushed back or if no character has been read, the input stream is unchanged and **`_ungetc_nolock`** returns `EOF`; **`_ungetwc_nolock`** returns `WEOF`. If *`stream`* is `NULL`, `EOF` or `WEOF` is returned, and `errno` is set to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -These functions are non-locking versions of **ungetc** and **ungetwc**. The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. They may be faster since they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +These functions are non-locking versions of `ungetc` and `ungetwc`. The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. They may be faster since they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettc_nolock**|**_ungetc_nolock**|**_ungetc_nolock**|**_ungetwc_nolock**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ungettc_nolock` | **`_ungetc_nolock`** | **`_ungetc_nolock`** | **`_ungetwc_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ungetc_nolock**|\| -|**_ungetwc_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_ungetc_nolock`** | \ | +| **`_ungetwc_nolock`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[getc, getwc](getc-getwc.md)
-[putc, putwc](putc-putwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`putc`, `putwc`](putc-putwc.md) diff --git a/docs/c-runtime-library/reference/ungetc-ungetwc.md b/docs/c-runtime-library/reference/ungetc-ungetwc.md index dba46d89f79..fe97a8b26f4 100644 --- a/docs/c-runtime-library/reference/ungetc-ungetwc.md +++ b/docs/c-runtime-library/reference/ungetc-ungetwc.md @@ -3,14 +3,14 @@ description: "Learn more about: ungetc, ungetwc" title: "ungetc, ungetwc" ms.date: "4/2/2020" api_name: ["ungetwc", "ungetc", "_o_ungetc", "_o_ungetwc"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_ungettc", "ungetwc", "ungetc"] +f1_keywords: ["STDIO/ungetc", "CORECRT_WSTDIO/ungetwc", "TCHAR/_ungettc", "ungetc", "ungetwc", "_ungettc"] helpviewer_keywords: ["ungetwc function", "ungettc function", "characters, pushing back onto stream", "_ungettc function", "ungetc function"] ms.assetid: e0754f3a-b4c6-408f-90c7-e6387b830d84 --- -# ungetc, ungetwc +# `ungetc`, `ungetwc` Pushes a character back onto the stream. @@ -29,46 +29,46 @@ wint_t ungetwc( ### Parameters -*c*
+*`c`*\ Character to be pushed. -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -## Return Value +## Return value -If successful, each of these functions returns the character argument *c*. If *c* cannot be pushed back or if no character has been read, the input stream is unchanged and **ungetc** returns **EOF**; **ungetwc** returns **WEOF**. If *stream* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **EOF** or **WEOF** is returned and **errno** is set to **EINVAL**. +If successful, each of these functions returns the character argument *`c`*. If *`c`* can't be pushed back or if no character has been read, the input stream is unchanged and **`ungetc`** returns `EOF`; **`ungetwc`** returns `WEOF`. If *`stream`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `EOF` or `WEOF` is returned, and `errno` is set to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **ungetc** function pushes the character *c* back onto *stream* and clears the end-of-file indicator. The stream must be open for reading. A subsequent read operation on *stream* starts with *c*. An attempt to push **EOF** onto the stream using **ungetc** is ignored. +The **`ungetc`** function pushes the character *`c`* back onto *`stream`* and clears the end-of-file indicator. The stream must be open for reading. A subsequent read operation on *`stream`* starts with *`c`*. An attempt to push `EOF` onto the stream using **`ungetc`** is ignored. -Characters placed on the stream by **ungetc** may be erased if **fflush**, [fseek](fseek-fseeki64.md), **fsetpos**, or [rewind](rewind.md) is called before the character is read from the stream. The file-position indicator will have the value it had before the characters were pushed back. The external storage corresponding to the stream is unchanged. On a successful **ungetc** call against a text stream, the file-position indicator is unspecified until all the pushed-back characters are read or discarded. On each successful **ungetc** call against a binary stream, the file-position indicator is decremented; if its value was 0 before a call, the value is undefined after the call. +Characters placed on the stream by **`ungetc`** may be erased if `fflush`, [`fseek`](fseek-fseeki64.md), `fsetpos`, or [`rewind`](rewind.md) is called before the character is read from the stream. The file-position indicator will have the value it had before the characters were pushed back. The external storage corresponding to the stream is unchanged. On a successful **`ungetc`** call against a text stream, the file-position indicator is unspecified until all the pushed-back characters are read or discarded. On each successful **`ungetc`** call against a binary stream, the file-position indicator is decremented; if its value was 0 before a call, the value is undefined after the call. -Results are unpredictable if **ungetc** is called twice without a read or file-positioning operation between the two calls. After a call to **fscanf**, a call to **ungetc** may fail unless another read operation (such as **getc**) has been performed. This is because **fscanf** itself calls **ungetc**. +Results are unpredictable if **`ungetc`** is called twice without a read or file-positioning operation between the two calls. After a call to `fscanf`, a call to **`ungetc`** may fail unless another read operation (such as `getc`) has been performed, because `fscanf` itself calls **`ungetc`**. -**ungetwc** is a wide-character version of **ungetc**. However, on each successful **ungetwc** call against a text or binary stream, the value of the file-position indicator is unspecified until all pushed-back characters are read or discarded. +**`ungetwc`** is a wide-character version of **`ungetc`**. However, on each successful **`ungetwc`** call against a text or binary stream, the value of the file-position indicator is unspecified until all pushed-back characters are read or discarded. -These functions are thread-safe and lock sensitive data during execution. For a non-locking version, see [_ungetc_nolock, _ungetwc_nolock](ungetc-nolock-ungetwc-nolock.md). +These functions are thread-safe and lock sensitive data during execution. For a non-locking version, see [`_ungetc_nolock`, `_ungetwc_nolock`](ungetc-nolock-ungetwc-nolock.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettc**|**ungetc**|**ungetc**|**ungetwc**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ungettc` | **`ungetc`** | **`ungetc`** | **`ungetwc`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**ungetc**|\| -|**ungetwc**|\ or \| +| Routine | Required header | +|---|---| +| **`ungetc`** | \ | +| **`ungetwc`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -106,6 +106,6 @@ Next character in stream = 'a' ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[getc, getwc](getc-getwc.md)
-[putc, putwc](putc-putwc.md)
+[Stream I/O](../stream-i-o.md)\ +[`getc`, `getwc`](getc-getwc.md)\ +[`putc`, `putwc`](putc-putwc.md) diff --git a/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md b/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md index 35b0e272954..1564dabc49c 100644 --- a/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md +++ b/docs/c-runtime-library/reference/ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: _ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock" title: "_ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock" -ms.date: "4/2/2020" +description: "Learn more about: _ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock" +ms.date: 4/2/2020 api_name: ["_ungetch_nolock", "_ungetwch_nolock", "_ungetwch", "_ungetch", "_o__ungetch", "_o__ungetch_nolock", "_o__ungetwch", "_o__ungetwch_nolock"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-conio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_ungetch_nolock", "ungetwch", "ungetch_nolock", "_ungetwch", "ungetwch_nolock", "_ungetch", "_ungettch_nolock", "_ungettch", "_ungetwch_nolock"] +f1_keywords: ["CONIO/_ungetch", "CONIO/_ungetch_nolock", "CORECRT_WCONIO/_ungetwch", "CORECRT_WCONIO/_ungetwch_nolock", "TCHAR/_ungettch", "TCHAR/_ungettch_nolock", "_ungetch", "_ungetch_nolock", "_ungetwch", "_ungetwch_nolock", "_ungettch", "_ungettch_nolock"] helpviewer_keywords: ["_ungetch function", "ungetwch function", "characters, pushing back to console", "_ungettch_nolock function", "ungettch function", "_ungettch function", "ungetch_nolock function", "ungettch_nolock function", "_ungetwch_nolock function", "_ungetch_nolock function", "ungetwch_nolock function", "_ungetwch function"] -ms.assetid: 70ae71c6-228c-4883-a57d-de6d5f873825 --- -# _ungetch, _ungetwch, _ungetch_nolock, _ungetwch_nolock +# `_ungetch`, `_ungetwch`, `_ungetch_nolock`, `_ungetwch_nolock` Pushes back the last character that's read from the console. @@ -36,42 +35,41 @@ wint_t _ungetwch_nolock( ### Parameters -*c*
+*`c`*\ Character to be pushed. -## Return Value +## Return value -Both functions return the character *c* if successful. If there is an error, **_ungetch** returns a value of **EOF** and **_ungetwch** returns **WEOF**. +Both functions return the character *`c`* if successful. If there's an error, **`_ungetch`** returns a value of `EOF` and **`_ungetwch`** returns `WEOF`. ## Remarks -These functions push the character *c* back to the console, causing *c* to be the next character read by **_getch** or **_getche** (or **_getwch** or **_getwche**). **_ungetch** and **_ungetwch** fail if they are called more than once before the next read. The *c* argument may not be **EOF** (or **WEOF**). +These functions push the character *`c`* back to the console, causing *`c`* to be the next character read by `_getch` or `_getche` (or `_getwch` or `_getwche`). **`_ungetch`** and **`_ungetwch`** fail if they're called more than once before the next read. The *`c`* argument may not be `EOF` (or `WEOF`). -The versions with the **_nolock** suffix are identical except that they are not protected from interference by other threads. They may be faster since they do not incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. +The versions with the `_nolock` suffix are identical except that they aren't protected from interference by other threads. They may be faster since they don't incur the overhead of locking out other threads. Use these functions only in thread-safe contexts such as single-threaded applications or where the calling scope already handles thread isolation. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_ungettch**|**_ungetch**|**_ungetch**|**_ungetwch**| -|**_ungettch_nolock**|**_ungetch_nolock**|**_ungetch_nolock**|**_ungetwch_nolock**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_ungettch` | **`_ungetch`** | **`_ungetch`** | **`_ungetwch`** | +| `_ungettch_nolock` | **`_ungetch_nolock`** | **`_ungetch_nolock`** | **`_ungetwch_nolock`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_ungetch**, **_ungetch_nolock**|\| -|**_ungetwch**, **_ungetwch_nolock**|\ or \| +| Routine | Required header | +|---|---| +| **`_ungetch`**, **`_ungetch_nolock`** | \ | +| **`_ungetwch`**, **`_ungetwch_nolock`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```C // crt_ungetch.c -// compile with: /c // In this program, a white-space delimited // token is read from the keyboard. When the program // encounters a delimiter, it uses _ungetch to replace @@ -111,6 +109,6 @@ Whitetoken = White ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[_getch, _getwch](getch-getwch.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`_getch`, `_getwch`](getch-getwch.md) diff --git a/docs/c-runtime-library/reference/ungetch.md b/docs/c-runtime-library/reference/ungetch.md index 7b67fd45ace..668a233b35e 100644 --- a/docs/c-runtime-library/reference/ungetch.md +++ b/docs/c-runtime-library/reference/ungetch.md @@ -6,15 +6,15 @@ api_name: ["ungetch"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["ungetch"] +f1_keywords: ["CONIO/ungetch", "ungetch"] helpviewer_keywords: ["ungetch function"] ms.assetid: 6921232f-6317-41cd-948b-91d56a11bc0e --- -# ungetch +# `ungetch` -The Microsoft-specific function name `ungetch` is a deprecated alias for the [_ungetch](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `ungetch` is a deprecated alias for the [`_ungetch`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_ungetch](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_ungetch`](ungetch-ungetwch-ungetch-nolock-ungetwch-nolock.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). diff --git a/docs/c-runtime-library/reference/unlink-wunlink.md b/docs/c-runtime-library/reference/unlink-wunlink.md index 84be18664bf..2a0dba15a76 100644 --- a/docs/c-runtime-library/reference/unlink-wunlink.md +++ b/docs/c-runtime-library/reference/unlink-wunlink.md @@ -3,14 +3,14 @@ description: "Learn more about: _unlink, _wunlink" title: "_unlink, _wunlink" ms.date: "4/2/2020" api_name: ["_unlink", "_wunlink", "_o__unlink", "_o__wunlink"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tunlink", "_unlink", "wunlink", "_wunlink"] +f1_keywords: ["CORECRT_IO/_unlink", "CORECRT_WIO/_wunlink", "TCHAR/_tunlink", "_unlink", "_wunlink", "_tunlink"] helpviewer_keywords: ["files [C++], deleting", "_wunlink function", "wunlink function", "unlink function", "_unlink function", "tunlink function", "files [C++], removing", "_tunlink function"] ms.assetid: 5e4f5f1b-1e99-4391-9b18-9ac63c32fae8 --- -# _unlink, _wunlink +# `_unlink`, `_wunlink` Delete a file. @@ -27,37 +27,37 @@ int _wunlink( ### Parameters -*filename*
+*`filename`*\ Name of file to remove. -## Return Value +## Return value -Each of these functions returns 0 if successful. Otherwise, the function returns -1 and sets **errno** to **EACCES**, which means the path specifies a read-only file or a directory, or to **ENOENT**, which means the file or path is not found. +Each of these functions returns 0 if successful. Otherwise, the function returns -1 and sets `errno` to `EACCES`, which means the path specifies a read-only file or a directory, or to `ENOENT`, which means the file or path isn't found. -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **_unlink** function deletes the file specified by *filename*. **_wunlink** is a wide-character version of **_unlink**; the *filename* argument to **_wunlink** is a wide-character string. These functions behave identically otherwise. +The **`_unlink`** function deletes the file specified by *`filename`*. **`_wunlink`** is a wide-character version of **`_unlink`**; the *`filename`* argument to **`_wunlink`** is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tunlink**|**_unlink**|**_unlink**|**_wunlink**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tunlink` | **`_unlink`** | **`_unlink`** | **`_wunlink`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_unlink**|\ and \| -|**_wunlink**|\ or \| +| Routine | Required header | +|---|---| +| **`_unlink`** | \ and \ | +| **`_wunlink`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). -## Code Example +## Code example This program uses _unlink to delete CRT_UNLINK.TXT. @@ -81,7 +81,7 @@ int main( void ) This file will be deleted. ``` -### Sample Output +### Sample output ```Output Deleted 'CRT_UNLINK.TXT' @@ -89,6 +89,6 @@ Deleted 'CRT_UNLINK.TXT' ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_close](close.md)
-[remove, _wremove](remove-wremove.md)
+[File handling](../file-handling.md)\ +[`_close`](close.md)\ +[`remove`, `_wremove`](remove-wremove.md) diff --git a/docs/c-runtime-library/reference/unlink.md b/docs/c-runtime-library/reference/unlink.md index 98863f4473d..58c351ba3a6 100644 --- a/docs/c-runtime-library/reference/unlink.md +++ b/docs/c-runtime-library/reference/unlink.md @@ -6,12 +6,12 @@ api_name: ["unlink"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["unlink"] +f1_keywords: ["CORECRT_IO/unlink", "unlink"] helpviewer_keywords: ["unlink function"] ms.assetid: 2cd82055-5770-48be-88ee-4b2c70541c46 --- -# unlink +# `unlink` -The Microsoft-implemented POSIX function name `unlink` is a deprecated alias for the [_unlink](unlink-wunlink.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-implemented POSIX function name `unlink` is a deprecated alias for the [`_unlink`](unlink-wunlink.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_unlink](unlink-wunlink.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_unlink`](unlink-wunlink.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/unlock-file.md b/docs/c-runtime-library/reference/unlock-file.md index f37d5498d8b..af13c9ba9f5 100644 --- a/docs/c-runtime-library/reference/unlock-file.md +++ b/docs/c-runtime-library/reference/unlock-file.md @@ -3,14 +3,14 @@ description: "Learn more about: _unlock_file" title: "_unlock_file" ms.date: "4/2/2020" api_name: ["_unlock_file", "_o__unlock_file"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-filesystem-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_unlock_file", "unlock_file"] +f1_keywords: ["STDIO/_unlock_file", "_unlock_file"] helpviewer_keywords: ["files [C++], unlocking", "unlock_file function", "_unlock_file function", "unlocking files"] ms.assetid: cf380a51-6d3a-4f38-bd64-2d4fb57b4369 --- -# _unlock_file +# `_unlock_file` Unlocks a file, allowing other processes to access the file. @@ -24,26 +24,26 @@ void _unlock_file( ### Parameters -*file*
+*`file`*\ File handle. ## Remarks -The **_unlock_file** function unlocks the file specified by *file*. Unlocking a file allows access to the file by other processes. This function should not be called unless **_lock_file** was previously called on the *file* pointer. Calling **_unlock_file** on a file that isn't locked may result in a deadlock. For an example, see [_lock_file](lock-file.md). +The **`_unlock_file`** function unlocks the file specified by *`file`*. Unlocking a file allows access to the file by other processes. This function shouldn't be called unless `_lock_file` was previously called on the *`file`* pointer. Calling **`_unlock_file`** on a file that isn't locked may result in a deadlock. For an example, see [`_lock_file`](lock-file.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_unlock_file**|\| +| Routine | Required header | +|---|---| +| **`_unlock_file`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[File Handling](../../c-runtime-library/file-handling.md)
-[_creat, _wcreat](creat-wcreat.md)
-[_open, _wopen](open-wopen.md)
-[_lock_file](lock-file.md)
+[File handling](../file-handling.md)\ +[`_creat`, `_wcreat`](creat-wcreat.md)\ +[`_open`, `_wopen`](open-wopen.md)\ +[`_lock_file`](lock-file.md) diff --git a/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md b/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md index ed2a5e043e8..84b91e8d2ea 100644 --- a/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md +++ b/docs/c-runtime-library/reference/utime-utime32-utime64-wutime-wutime32-wutime64.md @@ -3,21 +3,20 @@ description: "Learn more about: _utime, _utime32, _utime64, _wutime, _wutime32, title: "_utime, _utime32, _utime64, _wutime, _wutime32, _wutime64" ms.date: "4/2/2020" api_name: ["_utime64", "_utime", "_wutime", "_wutime64", "_wutime32", "_utime32", "_o__utime32", "_o__utime64", "_o__wutime32", "_o__wutime64"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-time-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_tutime", "_utime64", "wutime", "utime32", "wutime64", "_utime", "wutime32", "_wutime", "utime", "utime64", "_wutime64", "_utime32", "_tutime64", "_wutime32"] +f1_keywords: ["UTIME/_utime", "UTIME/_utime32", "UTIME/_utime64", "UTIME/_wutime", "UTIME/_wutime32", "UTIME/_wutime64", "TCHAR/_tutime", "TCHAR/_tutime32", "TCHAR/_tutime64", "_utime", "_utime32", "_utime64", "_wutime", "_wutime32", "_wutime64", "_tutime", "_tutime32", "_tutime64"] helpviewer_keywords: ["tutime function", "utime32 function", "utime64 function", "_utime function", "_tutime32 function", "time [C++], file modification", "wutime function", "_wutime function", "_wutime32 function", "_tutime64 function", "_tutime function", "files [C++], modification time", "_wutime64 function", "_utime32 function", "utime function", "_utime64 function", "wutime64 function", "wutime32 function", "tutime64 function", "tutime32 function"] -ms.assetid: 8d482d40-19b9-4591-bfee-5d7f601d1a9e --- -# _utime, _utime32, _utime64, _wutime, _wutime32, _wutime64 +# `_utime`, `_utime32`, `_utime64`, `_wutime`, `_wutime32`, `_wutime64` Set the file modification time. ## Syntax ```C -int _utime( +int _utime( // See note in remarks section about linkage const char *filename, struct _utimbuf *times ); @@ -29,7 +28,7 @@ int _utime64( const char *filename, struct __utimbuf64 *times ); -int _wutime( +int _wutime( // See note in remarks section about linkage const wchar_t *filename, struct _utimbuf *times ); @@ -45,67 +44,72 @@ int _wutime64( ### Parameters -*filename*
+*`filename`*\ Pointer to a string that contains the path or filename. -*times*
+*`times`*\ Pointer to stored time values. -## Return Value +## Return value -Each of these functions returns 0 if the file-modification time was changed. A return value of -1 indicates an error. If an invalid parameter is passed, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and **errno** is set to one of the following values: +Each of these functions returns 0 if the file-modification time was changed. A return value of -1 indicates an error. If an invalid parameter is passed, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1, and `errno` is set to one of the following values: -|errno value|Condition| -|-|-| -| **EACCES** | Path specifies directory or read-only file | -| **EINVAL** | Invalid *times* argument | -| **EMFILE** | Too many open files (the file must be opened to change its modification time) | -| **ENOENT** | Path or filename not found | +| `errno` value | Condition | +|---|---| +| `EACCES` | Path specifies directory or read-only file | +| `EINVAL` | Invalid *`times`* argument | +| `EMFILE` | Too many open files (the file must be opened to change its modification time) | +| `ENOENT` | Path or filename not found | -See [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md) for more information on these, and other, return codes. +For more information about return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -The date can be changed for a file if the change date is after midnight, January 1, 1970, and before the end date of the function used. **_utime** and **_wutime** use a 64-bit time value, so the end date is 23:59:59, December 31, 3000, UTC. If **_USE_32BIT_TIME_T** is defined to force the old behavior, the end date is 23:59:59 January 18, 2038, UTC. **_utime32** or **_wutime32** use a 32-bit time type regardless of whether **_USE_32BIT_TIME_T** is defined, and always have the earlier end date. **_utime64** or **_wutime64** always use the 64-bit time type, so these functions always support the later end date. +The date can be changed for a file if the change date is after midnight, January 1, 1970, and before the end date of the function used. **`_utime`** and **`_wutime`** use a 64-bit time value, so the end date is 23:59:59, December 31, 3000, UTC. If `_USE_32BIT_TIME_T` is defined to force the old behavior, the end date is 23:59:59 January 18, 2038, UTC. **`_utime32`** or **`_wutime32`** use a 32-bit time type regardless of whether `_USE_32BIT_TIME_T` is defined, and always have the earlier end date. **`_utime64`** or **`_wutime64`** always use the 64-bit time type, so these functions always support the later end date. ## Remarks -The **_utime** function sets the modification time for the file specified by *filename*. The process must have write access to the file in order to change the time. In the Windows operating system, you can change the access time and the modification time in the **_utimbuf** structure. If *times* is a **NULL** pointer, the modification time is set to the current local time. Otherwise, *times* must point to a structure of type **_utimbuf**, defined in SYS\UTIME.H. +The **`_utime`** function sets the modification time for the file specified by *`filename`*. The process must have write access to the file in order to change the time. In the Windows operating system, you can change the access time and the modification time in the `_utimbuf` structure. If *`times`* is a `NULL` pointer, the modification time is set to the current local time. Otherwise, *`times`* must point to a structure of type `_utimbuf`, defined in SYS\UTIME.H. -The **_utimbuf** structure stores file access and modification times used by **_utime** to change file-modification dates. The structure has the following fields, which are both of type **time_t**: +The **`_utimbuf`** structure stores file access and modification times used by **`_utime`** to change file-modification dates. The structure has the following fields, which are both of type `time_t`: | Field | Description | -|-------|---| -| **actime** | Time of file access | -| **modtime** | Time of file modification | +|---|---| +| **`actime`** | Time of file access | +| **`modtime`** | Time of file modification | -Specific versions of the **_utimbuf** structure (**_utimebuf32** and **__utimbuf64**) are defined using the 32-bit and 64-bit versions of the time type. These are used in the 32-bit and 64-bit specific versions of this function. **_utimbuf** itself by default uses a 64-bit time type unless **_USE_32BIT_TIME_T** is defined. +Specific versions of the `_utimbuf` structure (`__utimbuf32` and `__utimbuf64`) are defined using the 32-bit and 64-bit versions of the time type. These structures are used in the 32-bit and 64-bit specific versions of this function. `_utimbuf` itself by default uses a 64-bit time type unless `_USE_32BIT_TIME_T` is defined. -**_utime** is identical to **_futime** except that the *filename* argument of **_utime** is a filename or a path to a file, rather than a file descriptor of an open file. +`_utime` is identical to `_futime` except that the *`filename`* argument of **`_utime`** is a filename or a path to a file, rather than a file descriptor of an open file. -**_wutime** is a wide-character version of **_utime**; the *filename* argument to **_wutime** is a wide-character string. These functions behave identically otherwise. +**`_wutime`** is a wide-character version of **`_utime`**; the *`filename`* argument to **`_wutime`** is a wide-character string. These functions behave identically otherwise. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). -### Generic-Text Routine Mappings +> [!Note] +> When you use Windows SDK version 10.0.26100.6901 and Visual Studio 2026 or later together, `_utime` and `_wutime` are no longer `static inline` (internal linkage). Instead, they're `inline` (external linkage).\ +> To return to the previous behavior, `#define _STATIC_INLINE_UCRT_FUNCTIONS=1` before including any CRT headers. By default, `_STATIC_INLINE_UCRT_FUNCTIONS` is set to 0.\ +> This change increases UCRT conformance with the C++ standard and improves compatibility with C++ modules. -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_tutime**|**_utime**|**_utime**|**_wutime**| -|**_tutime32**|**_utime32**|**_utime32**|**_wutime32**| -|**_tutime64**|**_utime64**|**_utime64**|**_wutime64**| +### Generic-text routine mappings + +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tutime` | **`_utime`** | **`_utime`** | **`_wutime`** | +| `_tutime32` | **`_utime32`** | **`_utime32`** | **`_wutime32`** | +| `_tutime64` | **`_utime64`** | **`_utime64`** | **`_wutime64`** | ## Requirements -|Routine|Required headers|Optional headers| -|-------------|----------------------|----------------------| -|**_utime**, **_utime32**, **_utime64**|\|\| -|**_utime64**|\|\| -|**_wutime**|\ or \|\| +| Routine | Required headers | Optional headers | +|---|---|---| +| **`_utime`**, **`_utime32`**, **`_utime64`** | \ | \ | +| **`_utime64`** | \ | \ | +| **`_wutime`** | \ or \ | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program uses **_utime** to set the file-modification time to the current time. +This program uses **`_utime`** to set the file-modification time to the current time. ```C // crt_utime.c @@ -152,7 +156,7 @@ int main( void ) } ``` -### Sample Output +### Sample output ```Output Volume in drive C has no label. @@ -176,13 +180,13 @@ Directory of C:\test ## See also -[Time Management](../../c-runtime-library/time-management.md)
-[asctime, _wasctime](asctime-wasctime.md)
-[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)
-[_fstat, _fstat32, _fstat64, _fstati64, _fstat32i64, _fstat64i32](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)
-[_ftime, _ftime32, _ftime64](ftime-ftime32-ftime64.md)
-[_futime, _futime32, _futime64](futime-futime32-futime64.md)
-[gmtime, _gmtime32, _gmtime64](gmtime-gmtime32-gmtime64.md)
-[localtime, _localtime32, _localtime64](localtime-localtime32-localtime64.md)
-[_stat, _wstat Functions](stat-functions.md)
-[time, _time32, _time64](time-time32-time64.md)
+[Time management](../time-management.md)\ +[`asctime`, `_wasctime`](asctime-wasctime.md)\ +[`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)\ +[`_fstat`, `_fstat32`, `_fstat64`, `_fstati64`, `_fstat32i64`, `_fstat64i32`](fstat-fstat32-fstat64-fstati64-fstat32i64-fstat64i32.md)\ +[`_ftime`, `_ftime32`, `_ftime64`](ftime-ftime32-ftime64.md)\ +[`_futime`, `_futime32`, `_futime64`](futime-futime32-futime64.md)\ +[`gmtime`, `_gmtime32`, `_gmtime64`](gmtime-gmtime32-gmtime64.md)\ +[`localtime`, `_localtime32`, `_localtime64`](localtime-localtime32-localtime64.md)\ +[`_stat`, `_wstat` functions](stat-functions.md)\ +[`time`, `_time32`, `_time64`](time-time32-time64.md) diff --git a/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md b/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md index 7d420334077..a8f051d5ae9 100644 --- a/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md +++ b/docs/c-runtime-library/reference/va-arg-va-copy-va-end-va-start.md @@ -6,7 +6,7 @@ api_name: ["va_arg", "va_end", "va_copy", "va_start"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["va_arg", "va_start", "va_list", "va_alist", "va_dcl", "va_copy", "va_end"] +f1_keywords: ["STDARG/va_arg", "STDARG/va_copy", "STDARG/va_end", "VADEFS/va_list", "STDARG/va_start", "va_alist", "va_arg", "va_copy", "va_dcl", "va_end", "va_list", "va_start"] helpviewer_keywords: ["variable argument lists, accessing", "va_start macro", "va_arg macro", "va_end macro", "arguments [C++], argument lists", "va_list macro", "va_dcl macro", "va_alist macro", "va_copy macro"] ms.assetid: a700dbbd-bfe5-4077-87b6-3a07af74a907 --- @@ -39,24 +39,24 @@ void va_start( ### Parameters -*`type`*
+*`type`*\ Type of argument to be retrieved. -*`arg_ptr`*
+*`arg_ptr`*\ Pointer to the list of arguments. -*`dest`*
+*`dest`*\ Pointer to the list of arguments to be initialized from *`src`* -*`src`*
+*`src`*\ Pointer to the initialized list of arguments to copy to *`dest`*. -*`prev_param`*
+*`prev_param`*\ Parameter that precedes the first optional argument. -## Return Value +## Return value -**`va_arg`** returns the current argument. **`va_copy`**, **`va_start`** and **`va_end`** do not return values. +**`va_arg`** returns the current argument. **`va_copy`**, **`va_start`** and **`va_end`** don't return values. ## Remarks @@ -72,12 +72,12 @@ The C standard macros, defined in `STDARG.H`, are used as follows: - **`va_copy`** makes a copy of a list of arguments in its current state. The *`src`* parameter must already be initialized with **`va_start`**; it may have been updated with **`va_arg`** calls, but must not have been reset with **`va_end`**. The next argument that's retrieved by **`va_arg`** from *`dest`* is the same as the next argument that's retrieved from *`src`*. -- After all arguments have been retrieved, **`va_end`** resets the pointer to **`NULL`**. **`va_end`** must be called on each argument list that's initialized with **`va_start`** or **`va_copy`** before the function returns. +- After all arguments have been retrieved, **`va_end`** resets the pointer to `NULL`. **`va_end`** must be called on each argument list that's initialized with **`va_start`** or **`va_copy`** before the function returns. > [!NOTE] > The macros in VARARGS.H are deprecated and are retained only for backwards compatibility with code that was written before the ANSI C89 standard. In all other cases, use the macros in STDARGS.H. -When they are compiled by using [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md), programs that use these macros may generate unexpected results because of differences between native and common language runtime (CLR) type systems. Consider this program: +When they're compiled by using [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md), programs that use these macros may generate unexpected results because of differences between native and common language runtime (CLR) type systems. Consider this program: ```C #include @@ -109,7 +109,7 @@ int main() } ``` -Notice that **`testit`** expects its second parameter to be either an **`int`** or a **`char*`**. The arguments being passed are 0xffffffff (an **`unsigned int`**, not an **`int`**) and **`NULL`** (actually an **`int`**, not a **`char*`**). When the program is compiled for native code, it produces this output: +Notice that **`testit`** expects its second parameter to be either an **`int`** or a **`char*`**. The arguments being passed are 0xffffffff (an **`unsigned int`**, not an **`int`**) and `NULL` (actually an **`int`**, not a **`char*`**). When the program is compiled for native code, it produces this output: ```Output -1 @@ -125,7 +125,7 @@ Notice that **`testit`** expects its second parameter to be either an **`int`** ## Libraries -All versions of the [C run-time libraries](../../c-runtime-library/crt-library-features.md). +All versions of the [C run-time libraries](../crt-library-features.md). ## Example @@ -194,5 +194,5 @@ Deviation is: 0.000000 ## See also -[Argument Access](../../c-runtime-library/argument-access.md)
-[`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)
+[Argument access](../argument-access.md)\ +[`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) diff --git a/docs/c-runtime-library/reference/vcprintf-p-vcprintf-p-l-vcwprintf-p-vcwprintf-p-l.md b/docs/c-runtime-library/reference/vcprintf-p-vcprintf-p-l-vcwprintf-p-vcwprintf-p-l.md index c8cc18d5d19..04735adbee7 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 @@ -1,15 +1,15 @@ --- -description: "Learn more about: _vcprintf_p, _vcprintf_p_l, _vcwprintf_p, _vcwprintf_p_l" title: "_vcprintf_p, _vcprintf_p_l, _vcwprintf_p, _vcwprintf_p_l" -ms.date: "3/9/2021" +description: "Learn more about: _vcprintf_p, _vcprintf_p_l, _vcwprintf_p, _vcwprintf_p_l" +ms.date: 3/9/2021 api_name: ["_vcprintf_p", "_vcwprintf_p_l", "_vcprintf_p_l", "_vcwprintf_p"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vcwprintf_p", "vcprintf_p_l", "_vcprintf_p", "_vcprintf_p_l", "vcwprintf_p_l", "vcprintf_p", "_vcwprintf_p", "_vcwprintf_p_l"] +f1_keywords: ["CONIO/_vcprintf_p", "CONIO/_vcprintf_p_l", "CORECRT_WCONIO/_vcwprintf_p", "CORECRT_WCONIO/_vcwprintf_p_l", "TCHAR/_vtcprintf_p", "TCHAR/_vtcprintf_p_l", "_vcprintf_p", "_vcprintf_p_l", "_vcwprintf_p", "_vcwprintf_p_l", "_vtcprintf_p", "_vtcprintf_p_l"] helpviewer_keywords: ["_vtcprintf_p_l function", "vcprintf_p_l function", "_vcprintf_p_l function", "vtcprintf_p_l function", "vcprintf_p function", "_vcwprintf_p function", "_vcprintf_p function", "vcwprintf_p function", "vcwprintf_p_l function", "vtcprintf_p function", "_vcwprintf_p_l function", "_vtcprintf_p function"] --- -# _vcprintf_p, _vcprintf_p_l, _vcwprintf_p, _vcwprintf_p_l +# `_vcprintf_p`, `_vcprintf_p_l`, `_vcwprintf_p`, `_vcwprintf_p_l` Writes formatted output to the console by using a pointer to a list of arguments, and supports positional parameters in the format string. @@ -41,51 +41,51 @@ int _vcwprintf_p_l( ### Parameters -*format*
+*`format`*\ The format specification. -*argptr*
+*`argptr`*\ A pointer to a list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The number of characters that are written, or a negative value if an output error occurs. If *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and -1 is returned. +The number of characters that are written, or a negative value if an output error occurs. If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and -1 is returned. ## Remarks -Each of these functions takes a pointer to an argument list, and then uses the **_putch** function to format and write the given data to the console. (**_vcwprintf_p** uses **_putwch** instead of **_putch**. **_vcwprintf_p** is the wide-character version of **_vcprintf_p**. It takes a wide-character string as an argument.) +Each of these functions takes a pointer to an argument list, and then uses the `_putch` function to format and write the given data to the console. (**`_vcwprintf_p`** uses `_putwch` instead of `_putch`. **`_vcwprintf_p`** is the wide-character version of **`_vcprintf_p`**. It takes a wide-character string as an argument.) -The versions of these functions that have the **_l** suffix are identical except that they use the locale parameter that's passed in instead of the current locale. +The versions of these functions that have the `_l` suffix are identical except that they use the locale parameter that's passed in instead of the current locale. -Each *argument* (if any) is converted and is output according to the corresponding format specification in *format*. The format specification supports positional parameters so that you can specify the order in which the arguments are used in the format string. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +Each *`argument`* (if any) is converted and is output according to the corresponding format specification in *`format`*. The format specification supports positional parameters so that you can specify the order in which the arguments are used in the format string. For more information, see [`printf_p` positional parameters](../printf-p-positional-parameters.md). -These functions do not translate line-feed characters into carriage return-line feed (CR-LF) combinations when they are output. +These functions don't translate line-feed characters on output into carriage return-line feed (CR-LF) combinations. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -These functions validate the input pointer and the format string. If *format* or *argument* is **NULL**, or if the format string contains invalid formatting characters, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +These functions validate the input pointer and the format string. If *`format`* or *`argument`* is `NULL`, or if the format string contains invalid formatting characters, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|Tchar.h routine|_UNICODE and _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|**_vtcprintf_p**|**_vcprintf_p**|**_vcprintf_p**|**_vcwprintf_p**| -|**_vtcprintf_p_l**|**_vcprintf_p_l**|**_vcprintf_p_l**|**_vcwprintf_p_l**| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtcprintf_p` | **`_vcprintf_p`** | **`_vcprintf_p`** | **`_vcwprintf_p`** | +| `_vtcprintf_p_l` | **`_vcprintf_p_l`** | **`_vcprintf_p_l`** | **`_vcwprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_vcprintf_p**, **_vcprintf_p_l**|\ and \| -|**_vcwprintf_p**, **_vcwprintf_p_l**|\ and \| +| Routine | Required header | +|---|---| +| **`_vcprintf_p`**, **`_vcprintf_p_l`** | `` and `` | +| **`_vcwprintf_p`**, **`_vcwprintf_p_l`** | `` and `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -94,25 +94,25 @@ For more compatibility information, see [Compatibility](../../c-runtime-library/ ```C // crt_vcprintf_p.c -// compile with: /c + #include #include // An error formatting function that's used to print to the console. int eprintf(const char* format, ...) { - va_list args; - va_start(args, format); - int result = _vcprintf_p(format, args); - va_end(args); - return result; + va_list args; + va_start(args, format); + int result = _vcprintf_p(format, args); + va_end(args); + return result; } int main() { - int n = eprintf("parameter 2 = %2$d; parameter 1 = %1$s\r\n", - "one", 222); - _cprintf_s("%d characters printed\r\n"); + int n = eprintf("parameter 2 = %2$d; parameter 1 = %1$s\r\n", + "one", 222); + _cprintf_s("%d characters printed\r\n", n); } ``` @@ -123,7 +123,7 @@ parameter 2 = 222; parameter 1 = one ## See also -[Console and Port I/O](../../c-runtime-library/console-and-port-i-o.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
+[Console and port I/O](../console-and-port-i-o.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)\ +[`printf_p` positional parameters](../printf-p-positional-parameters.md) diff --git a/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md b/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md index 7bc6adf20d2..5c37e0a97a9 100644 --- a/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md +++ b/docs/c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md @@ -6,12 +6,12 @@ api_name: ["_vcprintf_s", "_vcprintf_s_l", "_vcwprintf_s", "_vcwprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vcprintf_s", "vcwprintf_s_l", "_vcwprintf_s", "_vcwprintf_s_l", "_vcprintf_s_l", "_vtcprintf_s", "vcwprintf_s", "vcprintf_s_l", "_vcprintf_s"] +f1_keywords: ["CONIO/_vcprintf_s", "CONIO/_vcprintf_s_l", "CORECRT_WCONIO/_vcwprintf_s", "CORECRT_WCONIO/_vcwprintf_s_l", "TCHAR/_vtcprintf_s", "TCHAR/_vtcprintf_s_l", "_vcprintf_s", "_vcprintf_s_l", "_vcwprintf_s", "_vcwprintf_s_l", "_vtcprintf_s", "_vtcprintf_s_l"] helpviewer_keywords: ["_vtcprintf_s_l function", "_vcwprintf_s_l function", "_vtcprintf_s function", "vtcprintf_s_l function", "vcprintf_s_l function", "_vcprintf_s function", "_vcwprintf_s function", "vcwprintf_s_l function", "vcwprintf_s function", "vcprintf_s function", "_vcprintf_s_l function", "vtcprintf_s function", "formatted text [C++]"] --- -# _vcprintf_s, _vcprintf_s_l, _vcwprintf_s, _vcwprintf_s_l +# `_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l` -Writes formatted output to the console by using a pointer to a list of arguments. These versions of [_vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l](vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Writes formatted output to the console by using a pointer to a list of arguments. These versions of [`_vcprintf`, `_vcprintf_l`, `_vcwprintf`, `_vcwprintf_l`](vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -19,21 +19,21 @@ Writes formatted output to the console by using a pointer to a list of arguments ## Syntax ```C -int _vcprintf( - const char* format, +int _vcprintf_s( + char const* const format, va_list argptr ); -int _vcprintf( - const char* format, +int _vcprintf_s_l( + char const* const format, _locale_t locale, va_list argptr ); int _vcwprintf_s( - const wchar_t* format, + wchar_t const* const format, va_list argptr ); int _vcwprintf_s_l( - const wchar_t* format, + wchar_t const* const format, _locale_t locale, va_list argptr ); @@ -41,49 +41,49 @@ int _vcwprintf_s_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to the list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value The number of characters written, or a negative value if an output error occurs. -Like the less secure versions of these functions, if *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). Additionally, unlike the less secure versions of these functions, if *format* does not specify a valid format, an invalid parameter exception is generated. If execution is allowed to continue, these functions return an error code and set **errno** to that error code. The default error code is **EINVAL** if a more specific value does not apply. +Like the less secure versions of these functions, if *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). Additionally, unlike the less secure versions of these functions, if *`format`* doesn't specify a valid format, an invalid parameter exception is generated. If execution is allowed to continue, these functions return an error code and set `errno` to that error code. The default error code is `EINVAL` if a more specific value doesn't apply. ## Remarks -Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the console. **_vcwprintf_s** is the wide-character version of **_vcprintf_s**. It takes a wide-character string as an argument. +Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the console. **`_vcwprintf_s`** is the wide-character version of **`_vcprintf_s`**. It takes a wide-character string as an argument. -The versions of these functions that have the **_l** suffix are identical except that they use the locale parameter that's passed in instead of the current locale. +The versions of these functions that have the `_l` suffix are identical except that they use the locale parameter that's passed in instead of the current locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtcprintf_s**|**_vcprintf_s**|**_vcprintf_s**|**_vcwprintf_s**| -|**_vtcprintf_s_l**|**_vcprintf_s_l**|**_vcprintf_s_l**|**_vcwprintf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtcprintf_s` | **`_vcprintf_s`** | **`_vcprintf_s`** | **`_vcwprintf_s`** | +| `_vtcprintf_s_l` | **`_vcprintf_s_l`** | **`_vcprintf_s_l`** | **`_vcwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vcprintf_s**, **_vcprintf_s_l**|\ and \|\*| -|**_vcwprintf_s**, **_vcwprintf_s_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vcprintf_s`**, **`_vcprintf_s_l`** | \ and \ | \* | +| **`_vcwprintf_s`**, **`_vcwprintf_s_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). > [!IMPORTANT] > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). @@ -121,10 +121,10 @@ int main() ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md b/docs/c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md index 6136b8332a2..0bffc074e8c 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 @@ -1,17 +1,17 @@ --- -description: "Learn more about: _vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l" title: "_vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l" -ms.date: "3/9/2021" +description: "Learn more about: _vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l" +ms.date: 3/9/2021 api_name: ["_vcwprintf", "_vcprintf_l", "_vcwprintf_l", "_vcprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vcwprintf_l", "_vtcprintf", "vcwprintf", "_vcwprintf", "vcprintf_l", "_vcprintf_l", "_vcprintf", "vcprintf", "vcwprintf_l"] +f1_keywords: ["CONIO/_vcprintf", "CONIO/_vcprintf_l", "CORECRT_WCONIO/_vcwprintf", "CORECRT_WCONIO/_vcwprintf_l", "TCHAR/_vtcprintf", "TCHAR/_vtcprintf_l", "_vcprintf", "_vcprintf_l", "_vcwprintf", "_vcwprintf_l", "_vtcprintf", "_vtcprintf_l"] helpviewer_keywords: ["vcwprintf function", "_vcwprintf_l function", "_vcprintf function", "_vcprintf_l function", "vtcprintf_l function", "vcprintf function", "vcprintf_l function", "_vtcprintf function", "_vcwprintf function", "_vtcprintf_l function", "vcwprintf_l function", "vtcprintf function", "formatted text [C++]"] --- -# _vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l +# `_vcprintf`, `_vcprintf_l`, `_vcwprintf`, `_vcwprintf_l` -Writes formatted output to the console by using a pointer to a list of arguments. More secure versions of these functions are available, see [_vcprintf_s, _vcprintf_s_l, _vcwprintf_s, _vcwprintf_s_l](vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md). +Writes formatted output to the console by using a pointer to a list of arguments. More secure versions of these functions are available, see [`_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l`](vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md). > [!IMPORTANT] > This API cannot be used in applications that execute in the Windows Runtime. For more information, see [CRT functions not supported in Universal Windows Platform apps](../../cppcx/crt-functions-not-supported-in-universal-windows-platform-apps.md). @@ -41,54 +41,55 @@ int _vcwprintf_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The number of characters written, or a negative value if an output error occurs. If *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and -1 is returned. +The number of characters written, or a negative value if an output error occurs. If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL`, and -1 is returned. ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to the console. **_vcwprintf** is the wide-character version of **_vcprintf**. It takes a wide-character string as an argument. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to the console. **`_vcwprintf`** is the wide-character version of **`_vcprintf`**. It takes a wide-character string as an argument. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtcprintf**|**_vcprintf**|**_vcprintf**|**_vcwprintf**| -|**_vtcprintf_l**|**_vcprintf_l**|**_vcprintf_l**|**_vcwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtcprintf` | **`_vcprintf`** | **`_vcprintf`** | **`_vcwprintf`** | +| `_vtcprintf_l` | **`_vcprintf_l`** | **`_vcprintf_l`** | **`_vcwprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vcprintf**, **_vcprintf_l**|\ and \|\*| -|**_vcwprintf**, **_vcwprintf_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vcprintf`**, **`_vcprintf_l`** | \ and \ | \* | +| **`_vcwprintf`**, **`_vcwprintf_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example ```cpp // crt_vcprintf.cpp -// compile with: /c + #include #include @@ -118,10 +119,10 @@ int main() ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](cprintf-cprintf-l-cwprintf-cwprintf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](cprintf-cprintf-l-cwprintf-cwprintf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md b/docs/c-runtime-library/reference/vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md index 4bcf50a866f..1da2fe9b48e 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 @@ -1,15 +1,15 @@ --- -description: "Learn more about: _vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l" title: "_vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l" -ms.date: "3/9/2021" +description: "Learn more about: _vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l" +ms.date: 3/9/2021 api_name: ["_vfprintf_p", "_vfwprintf_p", "_vfprintf_p_l", "_vfwprintf_p_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vfwprintf_p_l", "_vfprintf_p", "vfwprintf_p_l", "vfwprintf_p", "vfprintf_p_l", "_vfwprintf_p", "_vftprintf_p", "_vfprintf_p_l", "vfprintf_p"] +f1_keywords: ["STDIO/_vfprintf_p", "STDIO/_vfprintf_p_l", "CORECRT_WSTDIO/_vfwprintf_p", "CORECRT_WSTDIO/_vfwprintf_p_l", "TCHAR/_vftprintf_p", "TCHAR/_vftprintf_p_l", "_vfprintf_p", "_vfprintf_p_l", "_vfwprintf_p", "_vfwprintf_p_l", "_vftprintf_p", "_vftprintf_p_l"] helpviewer_keywords: ["vfprintf_p_l function", "_vftprintf_p_l function", "_vfprintf_p function", "vfprintf_p function", "vftprintf_p_l function", "_vfprintf_p_l function", "_vftprintf_p function", "_vfwprintf_p_l function", "vfwprintf_p_l function", "_vfwprintf_p function", "vftprintf_p function", "formatted text [C++]", "vfwprintf_p function"] --- -# _vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l +# `_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l` Write formatted output using a pointer to a list of arguments, with the ability to specify the order that arguments are used in the format string. @@ -42,65 +42,65 @@ int _vfwprintf_p_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**_vfprintf_p** and **_vfwprintf_p** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. +**`_vfprintf_p`** and **`_vfwprintf_p`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to *stream*. These functions differ from the **_vfprint_s** and **_vfwprint_s** versions only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +Each of these functions takes a pointer to an argument list, then formats and writes the given data to *`stream`*. These functions differ from the `_vfprint_s` and `_vfwprint_s` versions only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -**_vfwprintf_p** is the wide-character version of **_vprintf_p**; the two functions behave identically if the stream is opened in ANSI mode. **_vprintf_p** doesn't currently support output into a UNICODE stream. +**`_vfwprintf_p`** is the wide-character version of **`_vprintf_p`**; the two functions behave identically if the stream is opened in ANSI mode. **`_vprintf_p`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -If either *stream* or *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If either *`stream`* or *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf_p**|**_vfprintf_p**|**_vfprintf_p**|**_vfwprintf_p**| -|**_vftprintf_p_l**|**_vfprintf_p_l**|**_vfprintf_p_l**|**_vfwprintf_p_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftprintf_p` | **`_vfprintf_p`** | **`_vfprintf_p`** | **`_vfwprintf_p`** | +| `_vftprintf_p_l` | **`_vfprintf_p_l`** | **`_vfprintf_p_l`** | **`_vfwprintf_p_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vfprintf_p**, **_vfprintf_p_l**|\ and \|\*| -|**_vfwprintf_p**, **_vfwprintf_p_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vfprintf_p`**, **`_vfprintf_p_l`** | \ and \ | \* | +| **`_vfwprintf_p`**, **`_vfwprintf_p_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
-[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[_vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l](vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)
-[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l`](vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md)\ +[`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md) diff --git a/docs/c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md b/docs/c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md index b79108ae393..5b805440d0e 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 @@ -1,17 +1,17 @@ --- -description: "Learn more about: vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l" title: "vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l" -ms.date: "3/9/2021" +description: "Learn more about: vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l" +ms.date: 3/9/2021 api_name: ["vfwprintf_s", "_vfprintf_s_l", "vfprintf_s", "_vfwprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vftprintf_s", "vfwprintf_s", "vfprintf_s"] +f1_keywords: ["STDIO/vfprintf_s", "STDIO/_vfprintf_s_l", "CORECRT_WSTDIO/vfwprintf_s", "CORECRT_WSTDIO/_vfwprintf_s_l", "TCHAR/_vftprintf_s", "TCHAR/_vftprintf_s_l", "vfprintf_s", "_vfprintf_s_l", "vfwprintf_s", "_vfwprintf_s_l", "_vftprintf_s", "_vftprintf_s_l"] helpviewer_keywords: ["vfprintf_s_l function", "vfwprintf_s_l function", "vfwprintf_s function", "_vfprintf_s_l function", "_vfwprintf_s_l function", "vftprintf_s_l function", "vfprintf_s function", "_vftprintf_s_l function", "formatted text [C++]", "_vftprintf_s function"] --- -# vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l +# `vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l` -Write formatted output using a pointer to a list of arguments. These are versions of [vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Write formatted output using a pointer to a list of arguments. These functions are versions of [`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -42,63 +42,63 @@ int _vfwprintf_s_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vfprintf_s** and **vfwprintf_s** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *stream* or *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vfprintf_s`** and **`vfwprintf_s`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *`stream`* or *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to *stream*. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to *`stream`*. -These functions differ from the non-secure versions only in that the secure versions check that the *format* string contains valid formatting characters. +These functions differ from the non-secure versions only in that the secure versions check that the *`format`* string contains valid formatting characters. -**vfwprintf_s** is the wide-character version of **vfprintf_s**; the two functions behave identically if the stream is opened in ANSI mode. **vfprintf_s** doesn't currently support output into a UNICODE stream. +**`vfwprintf_s`** is the wide-character version of **`vfprintf_s`**; the two functions behave identically if the stream is opened in ANSI mode. **`vfprintf_s`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf_s**|**vfprintf_s**|**vfprintf_s**|**vfwprintf_s**| -|**_vftprintf_s_l**|**_vfprintf_s_l**|**_vfprintf_s_l**|**_vfwprintf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftprintf_s` | **`vfprintf_s`** | **`vfprintf_s`** | **`vfwprintf_s`** | +| `_vftprintf_s_l` | **`_vfprintf_s_l`** | **`_vfprintf_s_l`** | **`_vfwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vfprintf_s**, **_vfprintf_s_l**|\ and \|\*| -|**vfwprintf_s**, **_vfwprintf_s_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vfprintf_s`**, **`_vfprintf_s_l`** | \ and \ | \* | +| **`vfwprintf_s`**, **`_vfwprintf_s_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md b/docs/c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md index f1a4211619d..3c06a9bf539 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 @@ -1,17 +1,17 @@ --- -description: "Learn more about: vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l" title: "vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l" -ms.date: "3/9/2021" +description: "Learn more about: vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l" +ms.date: 3/9/2021 api_name: ["_vfprintf_l", "vfprintf", "vfwprintf", "_vfwprintf_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vfwprintf", "_vftprintf", "vfprintf"] +f1_keywords: ["STDIO/vfprintf", "STDIO/_vfprintf_l", "CORECRT_WSTDIO/vfwprintf", "CORECRT_WSTDIO/_vfwprintf_l", "TCHAR/_vftprintf", "TCHAR/_vftprintf_l", "vfprintf", "_vfprintf_l", "vfwprintf", "_vfwprintf_l", "_vftprintf", "_vftprintf_l"] helpviewer_keywords: ["_vfwprintf_l function", "_vftprintf function", "vfprintf function", "_vftprintf_l function", "vfprintf_l function", "vftprintf_l function", "vfwprintf_l function", "vftprintf function", "vfwprintf function", "_vfprintf_l function", "formatted text [C++]"] --- -# vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l +# `vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l` -Write formatted output using a pointer to a list of arguments. More secure versions of these functions exist; see [vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l](vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md). +Write formatted output using a pointer to a list of arguments. More secure versions of these functions exist; see [`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md). ## Syntax @@ -42,61 +42,61 @@ int _vfwprintf_l( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vfprintf** and **vfwprintf** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *stream* or *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vfprintf`** and **`vfwprintf`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If either *`stream`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to *stream*. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to *`stream`*. -**vfwprintf** is the wide-character version of **vfprintf**; the two functions behave identically if the stream is opened in ANSI mode. **vfprintf** doesn't currently support output into a UNICODE stream. +**`vfwprintf`** is the wide-character version of **`vfprintf`**; the two functions behave identically if the stream is opened in ANSI mode. **`vfprintf`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftprintf**|**vfprintf**|**vfprintf**|**vfwprintf**| -|**_vftprintf_l**|**_vfprintf_l**|**_vfprintf_l**|**_vfwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftprintf` | **`vfprintf`** | **`vfprintf`** | **`vfwprintf`** | +| `_vftprintf_l` | **`_vfprintf_l`** | **`_vfprintf_l`** | **`_vfwprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vfprintf**, **_vfprintf_l**|\ and \|\*| -|**vfwprintf**, **_vfwprintf_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vfprintf`**, **`_vfprintf_l`** | \ and \ | \* | +| **`vfwprintf`**, **`_vfwprintf_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md b/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md index c544c87d2f6..4f1a7f89305 100644 --- a/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md +++ b/docs/c-runtime-library/reference/vfscanf-s-vfwscanf-s.md @@ -6,12 +6,12 @@ api_name: ["vfscanf_s", "vfwscanf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vfscanf_s", "vfwscanf_s", "_vftscanf_s"] +f1_keywords: ["STDIO/vfscanf_s", "CORECRT_WSTDIO/vfwscanf_s", "TCHAR/_vftscanf_s", "vfscanf_s", "vfwscanf_s", "_vftscanf_s"] ms.assetid: 9b0133f0-9a18-4581-b24b-3b72683ad432 --- -# vfscanf_s, vfwscanf_s +# `vfscanf_s`, `vfwscanf_s` -Reads formatted data from a stream. These versions of vfscanf, vfwscanf have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from a stream. These versions of vfscanf, vfwscanf have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -30,44 +30,44 @@ int vfwscanf_s( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format-control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **EOF** for **vfscanf_s** and **vfwscanf_s**. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is `EOF` for **`vfscanf_s`** and **`vfwscanf_s`**. -These functions validate their parameters. If *stream* is an invalid file pointer, or *format* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`stream`* is an invalid file pointer, or *`format`* is a null pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. ## Remarks -The **vfscanf_s** function reads data from the current position of *stream* into the locations that are given by the *arglist* argument list (if any). Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. *format* controls the interpretation of the input fields and has the same form and function as the *format* argument for **scanf_s**; see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md) for a description of *format*. **vfwscanf_s** is a wide-character version of **vfscanf_s**; the format argument to **vfwscanf_s** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **vfscanf_s** doesn't currently support input from a UNICODE stream. +The **`vfscanf_s`** function reads data from the current position of *`stream`* into the locations that are given by the *`arglist`* argument list (if any). Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *`format`* argument for `scanf_s`; see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md) for a description of *`format`*. **`vfwscanf_s`** is a wide-character version of **`vfscanf_s`**; the format argument to **`vfwscanf_s`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`vfscanf_s`** doesn't currently support input from a UNICODE stream. -The main difference between the more secure functions (that have the **_s** suffix) and the other versions is that the more secure functions require the size in characters of each **c**, **C**, **s**, **S**, and **[** type field to be passed as an argument immediately following the variable. For more information, see [scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [scanf Width Specification](../../c-runtime-library/scanf-width-specification.md). +The main difference between the more secure functions (that have the **`_s`** suffix) and the other versions is that the more secure functions require the size in characters of each **`c`**, **`C`**, **`s`**, **`S`**, and **`[`** type field to be passed as an argument immediately following the variable. For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [`scanf` width specification](../scanf-width-specification.md). > [!NOTE] -> The size parameter is of type **`unsigned`**, not **size_t**. +> The size parameter is of type **`unsigned`**, not `size_t`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftscanf_s**|**vfscanf_s**|**vfscanf_s**|**vfwscanf_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftscanf_s` | **`vfscanf_s`** | **`vfscanf_s`** | **`vfwscanf_s`** | ## Requirements -|Function|Required header| -|--------------|---------------------| -|**vfscanf_s**|\| -|**vfwscanf_s**|\ or \| +| Function | Required header | +|---|---| +| **`vfscanf_s`** | \ | +| **`vfwscanf_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -139,10 +139,10 @@ x ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)
-[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[vfscanf, vfwscanf](vfscanf-vfwscanf.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)\ +[`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`vfscanf`, `vfwscanf`](vfscanf-vfwscanf.md) diff --git a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md index 996c9b964ff..152140dd56a 100644 --- a/docs/c-runtime-library/reference/vfscanf-vfwscanf.md +++ b/docs/c-runtime-library/reference/vfscanf-vfwscanf.md @@ -6,12 +6,12 @@ api_name: ["vfwscanf", "vfscanf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vfwscanf", "_vftscanf", "vfscanf"] +f1_keywords: ["STDIO/vfscanf", "CORECRT_WSTDIO/vfwscanf", "TCHAR/_vftscanf", "vfscanf", "vfwscanf", "_vftscanf"] ms.assetid: c06450ef-03f1-4d24-a8ac-d2dd98847918 --- -# vfscanf, vfwscanf +# `vfscanf`, `vfwscanf` -Reads formatted data from a stream. More secure versions of these functions are available; see [vfscanf_s, vfwscanf_s](vfscanf-s-vfwscanf-s.md). +Reads formatted data from a stream. More secure versions of these functions are available; see [`vfscanf_s`, `vfwscanf_s`](vfscanf-s-vfwscanf-s.md). ## Syntax @@ -30,43 +30,43 @@ int vfwscanf( ### Parameters -*stream*
-Pointer to **FILE** structure. +*`stream`*\ +Pointer to `FILE` structure. -*format*
+*`format`*\ Format-control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that are read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is **EOF** for **vfscanf** and **vfwscanf**. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that are read but not assigned. A return value of 0 indicates that no fields were assigned. If an error occurs, or if the end of the file stream is reached before the first conversion, the return value is `EOF` for **`vfscanf`** and **`vfwscanf`**. -These functions validate their parameters. If *stream* or *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +These functions validate their parameters. If *`stream`* or *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. ## Remarks -The **vfscanf** function reads data from the current position of *stream* into the locations that are given by the *arglist* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. *format* controls the interpretation of the input fields and has the same form and function as the *format* argument for **scanf**; see [scanf](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *format*. +The **`vfscanf`** function reads data from the current position of *`stream`* into the locations that are given by the *`arglist`* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. *`format`* controls the interpretation of the input fields and has the same form and function as the *`format`* argument for `scanf`; see [`scanf`](scanf-scanf-l-wscanf-wscanf-l.md) for a description of *`format`*. -**vfwscanf** is a wide-character version of **vfscanf**; the format argument to **vfwscanf** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **vfscanf** doesn't support input from a UNICODE stream. +**`vfwscanf`** is a wide-character version of **`vfscanf`**; the format argument to **`vfwscanf`** is a wide-character string. These functions behave identically if the stream is opened in ANSI mode. **`vfscanf`** doesn't support input from a UNICODE stream. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vftscanf**|**vfscanf**|**vfscanf**|**vfwscanf**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vftscanf` | **`vfscanf`** | **`vfscanf`** | **`vfwscanf`** | -For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Function|Required header| -|--------------|---------------------| -|**vfscanf**|\| -|**vfwscanf**|\ or \| +| Function | Required header | +|---|---| +| **`vfscanf`** | \ | +| **`vfwscanf`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -137,10 +137,10 @@ x ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](cscanf-cscanf-l-cwscanf-cwscanf-l.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)
-[vfscanf_s, vfwscanf_s](vfscanf-s-vfwscanf-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](cscanf-cscanf-l-cwscanf-cwscanf-l.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)\ +[`vfscanf_s`, `vfwscanf_s`](vfscanf-s-vfwscanf-s.md) diff --git a/docs/c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md b/docs/c-runtime-library/reference/vprintf-p-vprintf-p-l-vwprintf-p-vwprintf-p-l.md index d469f73b457..239ea8e1b57 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 @@ -1,15 +1,15 @@ --- -description: "Learn more about: _vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l" title: "_vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l" -ms.date: "3/9/2021" +description: "Learn more about: _vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l" +ms.date: 3/9/2021 api_name: ["_vwprintf_p", "_vprintf_p", "_vprintf_p_l", "_vwprintf_p_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vwprintf_p_l", "vprintf_p", "_vprintf_p_l", "_vwprintf_p", "vprintf_p_l", "vwprintf_p_l", "vwprintf_p", "vtprintf_p", "_vtprintf_p", "_vprintf_p"] +f1_keywords: ["STDIO/_vprintf_p", "STDIO/_vprintf_p_l", "CORECRT_WSTDIO/_vwprintf_p","CORECRT_WSTDIO/_vwprintf_p_l", "TCHAR/_vtprintf_p", "TCHAR/_vtprintf_p_l", "_vprintf_p", "_vprintf_p_l", "_vwprintf_p", "_vwprintf_p_l", "_vtprintf_p", "_vtprintf_p_l"] helpviewer_keywords: ["_vtprintf_p_l function", "_vtprintf_p function", "vtprintf_p function", "_vwprintf_p function", "_vwprintf_p_l function", "_vprintf_p function", "_vprintf_p_l function", "vprintf_p_l function", "vwprintf_p function", "vprintf_p function", "vtprintf_p_l function", "vwprintf_p_l function", "formatted text [C++]"] --- -# _vprintf_p, _vprintf_p_l, _vwprintf_p, _vwprintf_p_l +# `_vprintf_p`, `_vprintf_p_l`, `_vwprintf_p`, `_vwprintf_p_l` Writes formatted output by using a pointer to a list of arguments, and enables specification of the order in which the arguments are used. @@ -38,62 +38,62 @@ int _vwprintf_p_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**_vprintf_p** and **_vwprintf_p** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. +**`_vprintf_p`** and **`_vwprintf_p`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to **stdout**. These functions differ from **vprintf_s** and **vwprintf_s** only in that they support the ability to specify the order in which the arguments are used. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +Each of these functions takes a pointer to an argument list, then formats and writes the given data to `stdout`. These functions differ from `vprintf_s` and `vwprintf_s` only in that they support the ability to specify the order in which the arguments are used. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -**_vwprintf_p** is the wide-character version of **_vprintf_p**; the two functions behave identically if the stream is opened in ANSI mode. **_vprintf_p** doesn't currently support output into a UNICODE stream. +**`_vwprintf_p`** is the wide-character version of **`_vprintf_p`**; the two functions behave identically if the stream is opened in ANSI mode. **`_vprintf_p`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -If *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf_p**|**_vprintf_p**|**_vprintf_p**|**_vwprintf_p**| -|**_vtprintf_p_l**|**_vprintf_p_l**|**_vprintf_p_l**|**_vwprintf_p_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtprintf_p` | **`_vprintf_p`** | **`_vprintf_p`** | **`_vwprintf_p`** | +| `_vtprintf_p_l` | **`_vprintf_p_l`** | **`_vprintf_p_l`** | **`_vwprintf_p_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vprintf_p**, **_vprintf_p_l**|\ and \|\*| -|**_vwprintf_p**, **_vwprintf_p_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vprintf_p`**, **`_vprintf_p_l`** | \ and \ | \* | +| **`_vwprintf_p`**, **`_vwprintf_p_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[_fprintf_p, _fprintf_p_l, _fwprintf_p, _fwprintf_p_l](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)
-[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
-[_sprintf_p, _sprintf_p_l, _swprintf_p, _swprintf_p_l](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)
-[vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
-[_vfprintf_p, _vfprintf_p_l, _vfwprintf_p, _vfwprintf_p_l](vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)
-[_printf_p, _printf_p_l, _wprintf_p, _wprintf_p_l](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)
-[printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`_fprintf_p`, `_fprintf_p_l`, `_fwprintf_p`, `_fwprintf_p_l`](fprintf-p-fprintf-p-l-fwprintf-p-fwprintf-p-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)\ +[`_sprintf_p`, `_sprintf_p_l`, `_swprintf_p`, `_swprintf_p_l`](sprintf-p-sprintf-p-l-swprintf-p-swprintf-p-l.md)\ +[`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)\ +[`_vfprintf_p`, `_vfprintf_p_l`, `_vfwprintf_p`, `_vfwprintf_p_l`](vfprintf-p-vfprintf-p-l-vfwprintf-p-vfwprintf-p-l.md)\ +[`_printf_p`, `_printf_p_l`, `_wprintf_p`, `_wprintf_p_l`](printf-p-printf-p-l-wprintf-p-wprintf-p-l.md)\ +[printf_p Positional Parameters](../printf-p-positional-parameters.md) diff --git a/docs/c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md b/docs/c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md index 90a77d0fe29..b1a404e8fc5 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 @@ -1,17 +1,17 @@ --- -description: "Learn more about: vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l" title: "vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l" -ms.date: "3/9/2021" +description: "Learn more about: vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l" +ms.date: 3/9/2021 api_name: ["_vwprintf_s_l", "vwprintf_s", "_vprintf_s_l", "vprintf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vprintf_s", "vwprintf_s", "_vtprintf_s"] +f1_keywords: ["STDIO/vprintf_s", "STDIO/_vprintf_s_l", "CORECRT_WSTDIO/vwprintf_s", "CORECRT_WSTDIO/_vwprintf_s_l", "TCHAR/_vtprintf_s", "TCHAR/_vtprintf_s_l", "vprintf_s", "_vprintf_s_l", "vwprintf_s", "_vwprintf_s_l", "_vtprintf_s", "_vtprintf_s_l"] helpviewer_keywords: ["vwprintf_s_l function", "_vwprintf_s_l function", "vwprintf_s function", "_vtprintf_s_l function", "vprintf_s_l function", "vtprintf_s_l function", "_vtprintf_s function", "vtprintf_s function", "_vprintf_s_l function", "formatted text [C++]", "vprintf_s function"] --- -# vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l +# `vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l` -Writes formatted output by using a pointer to a list of arguments. These versions of [vprintf, _vprintf_l, vwprintf, _vwprintf_l](vprintf-vprintf-l-vwprintf-vwprintf-l.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Writes formatted output by using a pointer to a list of arguments. These versions of [`vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l`](vprintf-vprintf-l-vwprintf-vwprintf-l.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -38,60 +38,60 @@ int _vwprintf_s_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vprintf_s** and **vwprintf_s** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vprintf_s`** and **`vwprintf_s`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to **stdout**. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to `stdout`. -The secure versions of these functions differ from **vprintf** and **vwprintf** only in that the secure versions check that the format string contains valid formatting characters. +The secure versions of these functions differ from `vprintf` and `vwprintf` only in that the secure versions check that the format string contains valid formatting characters. -**vwprintf_s** is the wide-character version of **vprintf_s**; the two functions behave identically if the stream is opened in ANSI mode. **vprintf_s** doesn't currently support output into a UNICODE stream. +**`vwprintf_s`** is the wide-character version of **`vprintf_s`**; the two functions behave identically if the stream is opened in ANSI mode. **`vprintf_s`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf_s**|**vprintf_s**|**vprintf_s**|**vwprintf_s**| -|**_vtprintf_s_l**|**_vprintf_s_l**|**_vprintf_s_l**|**_vwprintf_s_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtprintf_s` | **`vprintf_s`** | **`vprintf_s`** | **`vwprintf_s`** | +| `_vtprintf_s_l` | **`_vprintf_s_l`** | **`_vprintf_s_l`** | **`_vwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vprintf_s**, **_vprintf_s_l**|\ and \|\*| -|**vwprintf_s**, **_vwprintf_s_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vprintf_s`**, **`_vprintf_s_l`** | \ and \ | \* | +| **`vwprintf_s`**, **`_vwprintf_s_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md b/docs/c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md index 229fa135a77..e91e6092aeb 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 @@ -1,17 +1,17 @@ --- -description: "Learn more about: vprintf, _vprintf_l, vwprintf, _vwprintf_l" title: "vprintf, _vprintf_l, vwprintf, _vwprintf_l" -ms.date: "3/9/2021" +description: "Learn more about: vprintf, _vprintf_l, vwprintf, _vwprintf_l" +ms.date: 3/9/2021 api_name: ["vprintf", "_vwprintf_l", "_vprintf_l", "vwprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vwprintf", "_vtprintf"] +f1_keywords: ["STDIO/vprintf", "STDIO/_vprintf_l", "CORECRT_WSTDIO/vwprintf", "CORECRT_WSTDIO/_vwprintf_l", "TCHAR/_vtprintf", "TCHAR/_vtprintf_l", "vprintf", "_vprintf_l", "vwprintf", "_vwprintf_l", "_vtprintf", "_vtprintf_l"] helpviewer_keywords: ["vwprintf function", "_vwprintf_l function", "vwprintf_l function", "_vtprintf function", "vtprintf_l function", "vprintf function", "_vprintf_l function", "vprintf_l function", "vtprintf function", "_vtprintf_l function", "formatted text [C++]"] --- -# vprintf, _vprintf_l, vwprintf, _vwprintf_l +# `vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l` -Writes formatted output by using a pointer to a list of arguments. More secure versions of these functions are available, see [vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l](vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md). +Writes formatted output by using a pointer to a list of arguments. More secure versions of these functions are available, see [`vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l`](vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md). ## Syntax @@ -38,58 +38,58 @@ int _vwprintf_l( ### Parameters -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**vprintf** and **vwprintf** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *format* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +**`vprintf`** and **`vwprintf`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *`format`* is a null pointer, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [_doserrno, errno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -Each of these functions takes a pointer to an argument list, then formats and writes the given data to **stdout**. +Each of these functions takes a pointer to an argument list, then formats and writes the given data to `stdout`. -**vwprintf** is the wide-character version of **vprintf**; the two functions behave identically if the stream is opened in ANSI mode. **vprintf** doesn't currently support output into a UNICODE stream. +**`vwprintf`** is the wide-character version of **`vprintf`**; the two functions behave identically if the stream is opened in ANSI mode. **`vprintf`** doesn't currently support output into a UNICODE stream. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Ensure that *format* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). Invalid format strings are detected and result in an error. -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). Invalid format strings are detected and result in an error. +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtprintf**|**vprintf**|**vprintf**|**vwprintf**| -|**_vtprintf_l**|**_vprintf_l**|**_vprintf_l**|**_vwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtprintf` | **`vprintf`** | **`vprintf`** | **`vwprintf`** | +| `_vtprintf_l` | **`_vprintf_l`** | **`_vprintf_l`** | **`_vwprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**vprintf**, **_vprintf_l**|\ and \|\*| -|**vwprintf**, **_vwprintf_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vprintf`**, **`_vprintf_l`** | \ and \ | \* | +| **`vwprintf`**, **`_vwprintf_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md b/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md index 9e2330b9357..4494f96ba16 100644 --- a/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md +++ b/docs/c-runtime-library/reference/vscanf-s-vwscanf-s.md @@ -6,12 +6,12 @@ api_name: ["vscanf_s", "vwscanf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vtscanf_s", "vscanf_s", "vwscanf_s"] +f1_keywords: ["STDIO/vscanf_s", "CORECRT_WSTDIO/vwscanf_s", "TCHAR/_vtscanf_s", "vscanf_s", "vwscanf_s", "_vtscanf_s"] ms.assetid: 23a1c383-5b01-4887-93ce-534a1e38ed93 --- -# vscanf_s, vwscanf_s +# `vscanf_s`, `vwscanf_s` -Reads formatted data from the standard input stream. These versions of [vscanf, vwscanf](vscanf-vwscanf.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from the standard input stream. These versions of [`vscanf`, `vwscanf`](vscanf-vwscanf.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -28,49 +28,49 @@ int vwscanf_s( ### Parameters -*format*
+*`format`*\ Format control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Returns the number of fields successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error, or if the end-of-file character or the end-of-string character is encountered in the first attempt to read a character. If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **vscanf_s** and **vwscanf_s** return **EOF** and set **errno** to **EINVAL**. +Returns the number of fields successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error, or if the end-of-file character or the end-of-string character is encountered in the first attempt to read a character. If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, **`vscanf_s`** and **`vwscanf_s`** return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vscanf_s** function reads data from the standard input stream **stdin** and writes the data into the locations that are given by the *arglist* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. If copying occurs between strings that overlap, the behavior is undefined. +The **`vscanf_s`** function reads data from the standard input stream `stdin` and writes the data into the locations that are given by the *`arglist`* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. If copying occurs between strings that overlap, the behavior is undefined. -**vwscanf_s** is a wide-character version of **vscanf_s**; the *format* argument to **vwscanf_s** is a wide-character string. **vwscanf_s** and **vscanf_s** behave identically if the stream is opened in ANSI mode. **vscanf_s** doesn't support input from a UNICODE stream. +**`vwscanf_s`** is a wide-character version of **`vscanf_s`**; the *`format`* argument to **`vwscanf_s`** is a wide-character string. **`vwscanf_s`** and **`vscanf_s`** behave identically if the stream is opened in ANSI mode. **`vscanf_s`** doesn't support input from a UNICODE stream. -Unlike **vscanf** and **vwscanf**, **vscanf_s** and **vwscanf_s** require the buffer size to be specified for all input parameters of type **c**, **C**, **s**, **S**, or string control sets that are enclosed in **[]**. The buffer size in characters is passed as an additional parameter immediately following the pointer to the buffer or variable. The buffer size in characters for a **`wchar_t`** string is not the same as the size in bytes. +Unlike `vscanf` and `vwscanf`, **`vscanf_s`** and **`vwscanf_s`** require the buffer size to be specified for all input parameters of type **c**, **C**, **s**, **S**, or string control sets that are enclosed in **[]**. The buffer size in characters is passed as another parameter immediately following the pointer to the buffer or variable. The buffer size in characters for a **`wchar_t`** string isn't the same as the size in bytes. -The buffer size includes the terminating null. You can use a width-specification field to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer. +The buffer size includes the terminating null. You can use a width-specification field to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too large to fit in the buffer, nothing is written to that buffer. > [!NOTE] -> The *size* parameter is of type **`unsigned`**, not **size_t**. +> The *`size`* parameter is of type **`unsigned`**, not `size_t`. -For more information, see [scanf Width Specification](../../c-runtime-library/scanf-width-specification.md). +For more information, see [scanf Width Specification](../scanf-width-specification.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtscanf_s**|**vscanf_s**|**vscanf_s**|**vwscanf_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtscanf_s` | **`vscanf_s`** | **`vscanf_s`** | **`vwscanf_s`** | -For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vscanf_s**|\| -|**wscanf_s**|\ or \| +| Routine | Required header | +|---|---| +| **`vscanf_s`** | \ | +| **`wscanf_s`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -137,10 +137,10 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[vscanf, vwscanf](vscanf-vwscanf.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[`vscanf`, `vwscanf`](vscanf-vwscanf.md) diff --git a/docs/c-runtime-library/reference/vscanf-vwscanf.md b/docs/c-runtime-library/reference/vscanf-vwscanf.md index ecf9c7b21fe..043913e4b2d 100644 --- a/docs/c-runtime-library/reference/vscanf-vwscanf.md +++ b/docs/c-runtime-library/reference/vscanf-vwscanf.md @@ -6,12 +6,12 @@ api_name: ["vscanf", "vwscanf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vscanf", "vwscanf", "_vtscanf"] +f1_keywords: ["STDIO/vscanf", "CORECRT_WSTDIO/vwscanf", "TCHAR/_vtscanf", "vscanf", "vwscanf", "_vtscanf"] ms.assetid: d1df595b-11bc-4682-9441-a92616301e3b --- -# vscanf, vwscanf +# `vscanf`, `vwscanf` -Reads formatted data from the standard input stream. More secure versions of these function are available; see [vscanf_s, vwscanf_s](vscanf-s-vwscanf-s.md). +Reads formatted data from the standard input stream. More secure versions of these functions are available; see [`vscanf_s`, `vwscanf_s`](vscanf-s-vwscanf-s.md). ## Syntax @@ -28,45 +28,45 @@ int vwscanf( ### Parameters -*format*
+*`format`*\ Format control string. -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. +Returns the number of fields that are successfully converted and assigned; the return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. -If *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return **EOF** and set **errno** to **EINVAL**. +If *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return `EOF` and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vscanf** function reads data from the standard input stream **stdin** and writes the data into the locations that are given by the *arglist* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *format*. If copying occurs between strings that overlap, the behavior is undefined. +The **`vscanf`** function reads data from the standard input stream `stdin` and writes the data into the locations that are given by the *`arglist`* argument list. Each argument in the list must be a pointer to a variable of a type that corresponds to a type specifier in *`format`*. If copying occurs between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> When you use **vscanf** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. As an alternative, you can use [vscanf_s, vwscanf_s](vscanf-s-vwscanf-s.md) or [fgets](fgets-fgetws.md). +> When you use **`vscanf`** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. As an alternative, you can use [`vscanf_s`, `vwscanf_s`](vscanf-s-vwscanf-s.md) or [`fgets`](fgets-fgetws.md). -**vwscanf** is a wide-character version of **vscanf**; the *format* argument to **vwscanf** is a wide-character string. **vwscanf** and **vscanf** behave identically if the stream is opened in ANSI mode. **vscanf** doesn't support input from a UNICODE stream. +**`vwscanf`** is a wide-character version of **`vscanf`**; the *`format`* argument to **`vwscanf`** is a wide-character string. **`vwscanf`** and **`vscanf`** behave identically if the stream is opened in ANSI mode. **`vscanf`** doesn't support input from a UNICODE stream. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vtscanf**|**vscanf**|**vscanf**|**vwscanf**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vtscanf` | **`vscanf`** | **`vscanf`** | **`vwscanf`** | -For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vscanf**|\| -|**vwscanf**|\ or \| +| Routine | Required header | +|---|---| +| **`vscanf`** | \ | +| **`vwscanf`** | \ or \ | -The console is not supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, **stdin**, **stdout**, and **stderr**, must be redirected before C run-time functions can use them in UWP apps. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The console isn't supported in Universal Windows Platform (UWP) apps. The standard stream handles that are associated with the console, `stdin`, `stdout`, and `stderr`, must be redirected before C run-time functions can use them in UWP apps. For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -125,11 +125,11 @@ The contents are: 36 92.300003 y n Wide characters ## See also -[Floating-Point Support](../../c-runtime-library/floating-point-support.md)
-[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[Locale](../../c-runtime-library/locale.md)
-[fscanf, _fscanf_l, fwscanf, _fwscanf_l](fscanf-fscanf-l-fwscanf-fwscanf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vscanf_s, vwscanf_s](vscanf-s-vwscanf-s.md)
+[Math and floating-point support](../floating-point-support.md)\ +[Stream I/O](../stream-i-o.md)\ +[Locale](../locale.md)\ +[`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](fscanf-fscanf-l-fwscanf-fwscanf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vscanf_s`, `vwscanf_s`](vscanf-s-vwscanf-s.md) diff --git a/docs/c-runtime-library/reference/vscprintf-p-vscprintf-p-l-vscwprintf-p-vscwprintf-p-l.md b/docs/c-runtime-library/reference/vscprintf-p-vscprintf-p-l-vscwprintf-p-vscwprintf-p-l.md index 0e483b59b8c..388f6f46a27 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" -ms.date: "10/21/2021" +description: "Learn more about: _vscprintf_p, _vscprintf_p_l, _vscwprintf_p, _vscwprintf_p_l" +ms.date: 10/21/2021 api_name: ["_vscprintf_p_l", "_vscprintf_p", "_vscwprintf_p_l", "_vscwprintf_p"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vscprintf_p", "_vscprintf_p_l", "vscwprintf_p", "vscprintf_p", "vscwprintf_p_l", "_vscwprintf_p_l", "vscprintf_p_l", "_vscwprintf_p"] +f1_keywords: ["STDIO/_vscprintf_p", "STDIO/_vscprintf_p_l", "CORECRT_WSTDIO/_vscwprintf_p", "CORECRT_WSTDIO/_vscwprintf_p_l", "TCHAR/_vsctprintf_p", "TCHAR/_vsctprintf_p_l", "_vscprintf_p", "_vscprintf_p_l", "_vscwprintf_p", "_vscwprintf_p_l", "_vsctprintf_p", "_vsctprintf_p_l"] helpviewer_keywords: ["vscprintf_p function", "_vsctprintf_p_l function", "vscwprintf_p_l function", "_vscwprintf_p_l function", "_vscprintf_p function", "vsctprintf_p function", "_vscprintf_p_l function", "_vscwprintf_p function", "vscwprintf_p function", "vsctprintf_p_l function", "_vsctprintf_p function", "vscprintf_p_l function"] --- # `_vscprintf_p`, `_vscprintf_p_l`, `_vscwprintf_p`, `_vscwprintf_p_l` @@ -47,39 +47,42 @@ Pointer to list of arguments. *`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**`_vscprintf_p`** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **`_vscwprintf_p`** performs the same function for wide characters. +**`_vscprintf_p`** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_vscwprintf_p`** performs the same function for wide characters. ## Remarks -These functions differ from **`_vscprintf`** and **`_vscwprintf`** only in that they support the ability to specify the order in which the arguments are used. For more information, see [`printf_p` Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +These functions differ from **`_vscprintf`** and **`_vscwprintf`** only in that they support the ability to specify the order in which the arguments are used. For more information, see [`printf_p` Positional Parameters](../printf-p-positional-parameters.md). The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **`errno`** to **`EINVAL`**. +Return Value is the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. + +If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. > [!IMPORTANT] -> Ensure that if *`format`* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that if *`format`* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vsctprintf_p`**|**`_vscprintf_p`**|**`_vscprintf_p`**|**`_vscwprintf_p`**| -|**`_vsctprintf_p_l`**|**`_vscprintf_p_l`**|**`_vscprintf_p_l`**|**`_vscwprintf_p_l`**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| **`_vsctprintf_p`** | **`_vscprintf_p`** | **`_vscprintf_p`** | **`_vscwprintf_p`** | +| **`_vsctprintf_p_l`** | **`_vscprintf_p_l`** | **`_vscprintf_p_l`** | **`_vscwprintf_p_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_vscprintf_p`**, **`_vscprintf_p_l`**|``| -|**`_vscwprintf_p`**, **`_vscwprintf_p_l`**|`` or ``| +| Routine | Required header | +|---|---| +| **`_vscprintf_p`**, **`_vscprintf_p_l`** | `` | +| **`_vscwprintf_p`**, **`_vscwprintf_p_l`** | `` or `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -87,6 +90,6 @@ See the example for [`vsprintf`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswpr ## See also -[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)\ +[`vprintf` functions](../vprintf-functions.md)\ [`_scprintf_p`, `_scprintf_p_l`, `_scwprintf_p`, `_scwprintf_p_l`](scprintf-p-scprintf-p-l-scwprintf-p-scwprintf-p-l.md)\ -[`_vscprintf`, `_vscprintf_l`, `_vscwprintf`, `_vscwprintf_l`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md)\ +[`_vscprintf`, `_vscprintf_l`, `_vscwprintf`, `_vscwprintf_l`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) diff --git a/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md b/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md index 4d999679dc7..ac02613e06b 100644 --- a/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md +++ b/docs/c-runtime-library/reference/vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md @@ -6,10 +6,10 @@ api_name: ["_vscprintf", "_vscprintf_l", "_vscwprintf_l", "_vscwprintf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vscprintf_l", "vscwpeintf", "_vscwprintf", "_vsctprintf", "_vscprintf", "vscwprintf_l", "vscprintf", "_vscwprintf_l"] +f1_keywords: ["STDIO/_vscprintf", "STDIO/_vscprintf_l", "CORECRT_WSTDIO/_vscwprintf", "CORECRT_WSTDIO/_vscwprintf_l", "TCHAR/_vsctprintf", "TCHAR/_vsctprintf_l", "_vscprintf", "_vscprintf_l", "_vscwprintf", "_vscwprintf_l", "_vsctprintf", "_vsctprintf_l"] helpviewer_keywords: ["vsctprintf function", "_vscprintf_l function", "_vsctprintf_l function", "_vsctprintf function", "_vscwprintf_l function", "vscwprintf_l function", "_vscprintf function", "_vscwprintf function", "vscwprintf function", "vsctprintf_l function", "formatted text [C++]", "vscprintf function", "vscprintf_l function"] --- -# _vscprintf, _vscprintf_l, _vscwprintf, _vscwprintf_l +# `_vscprintf`, `_vscprintf_l`, `_vscwprintf`, `_vscwprintf_l` Returns the number of characters in the formatted string using a pointer to a list of arguments. @@ -38,59 +38,62 @@ int _vscwprintf_l( ### Parameters -*format*
+*`format`*\ Format-control string. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -**_vscprintf** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned does not include the terminating null character. **_vscwprintf** performs the same function for wide characters. +**`_vscprintf`** returns the number of characters that would be generated if the string pointed to by the list of arguments was printed or sent to a file or buffer using the specified formatting codes. The value returned doesn't include the terminating null character. **`_vscwprintf`** performs the same function for wide characters. -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -If *format* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If *`format`* is a null pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. ## Remarks -Each *argument* (if any) is converted according to the corresponding format specification in *format*. The format consists of ordinary characters and has the same form and function as the *format* argument for [printf](printf-printf-l-wprintf-wprintf-l.md). +Return Value is the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. + +Each *`argument`* (if any) is converted according to the corresponding format specification in *`format`*. The format consists of ordinary characters and has the same form and function as the *`format`* argument for [`printf`](printf-printf-l-wprintf-wprintf-l.md). > [!IMPORTANT] -> Ensure that if *format* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Ensure that if *`format`* is a user-defined string, it is null terminated and has the correct number and type of parameters. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). > > Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vsctprintf**|**_vscprintf**|**_vscprintf**|**_vscwprintf**| -|**_vsctprintf_l**|**_vscprintf_l**|**_vscprintf_l**|**_vscwprintf_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vsctprintf` | **`_vscprintf`** | **`_vscprintf`** | **`_vscwprintf`** | +| `_vsctprintf_l` | **`_vscprintf_l`** | **`_vscprintf_l`** | **`_vscwprintf_l`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**_vscprintf**, **_vscprintf_l**|\| -|**_vscwprintf**, **_vscwprintf_l**|\ or \| +| Routine | Required header | +|---|---| +| **`_vscprintf`**, **`_vscprintf_l`** | \ | +| **`_vscwprintf`**, **`_vscwprintf_l`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -See the example for [vsprintf](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md). +See the example for [`vsprintf`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md). ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
+[Stream I/O](../stream-i-o.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`vprintf` functions](../vprintf-functions.md) diff --git a/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md b/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md index 954e77bb952..0cdb13f915d 100644 --- a/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md +++ b/docs/c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l" title: "vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l" -ms.date: "3/9/2021" +description: "Learn more about: vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l" +ms.date: 06/27/2023 api_name: ["_vsnwprintf_s", "_vsnwprintf_s_l", "_vsnprintf_s", "vsnprintf_s", "_vsnprintf_s_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntdll.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vsnprintf_s", "_vsntprintf_s", "_vsnwprintf_s"] +f1_keywords: ["STDIO/vsnprintf_s", "STDIO/_vsnprintf_s", "CORECRT_WSTDIO/_vsnwprintf_s", "TCHAR/_vsntprintf_s", "STDIO/_vsnprintf_s_l", "CORECRT_WSTDIO/_vsnwprintf_s_l", "TCHAR/_vsntprintf_s_l", "vsnprintf_s", "_vsnprintf_s", "_vsnwprintf_s", "_vsntprintf_s", "_vsnprintf_s_l", "_vsnwprintf_s_l", "_vsntprintf_s_l"] helpviewer_keywords: ["vsnwprintf_s function", "_vsntprintf_s function", "_vsntprintf_s_l function", "vsntprintf_s function", "vsnwprintf_s_l function", "vsnprintf_s_l function", "vsntprintf_s_l function", "_vsnwprintf_s_l function", "_vsnprintf_s function", "vsnprintf_s function", "_vsnprintf_s_l function", "_vsnwprintf_s function", "formatted text [C++]"] --- # `vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l` -Write formatted output using a pointer to a list of arguments. These are versions of [`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Write formatted output using a pointer to a list of arguments. These functions are versions of [`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -23,6 +23,7 @@ int vsnprintf_s( const char *format, va_list argptr ); + int _vsnprintf_s( char *buffer, size_t sizeOfBuffer, @@ -30,6 +31,7 @@ int _vsnprintf_s( const char *format, va_list argptr ); + int _vsnprintf_s_l( char *buffer, size_t sizeOfBuffer, @@ -38,6 +40,7 @@ int _vsnprintf_s_l( _locale_t locale, va_list argptr ); + int _vsnwprintf_s( wchar_t *buffer, size_t sizeOfBuffer, @@ -45,6 +48,7 @@ int _vsnwprintf_s( const wchar_t *format, va_list argptr ); + int _vsnwprintf_s_l( wchar_t *buffer, size_t sizeOfBuffer, @@ -53,6 +57,7 @@ int _vsnwprintf_s_l( _locale_t locale, va_list argptr ); + template int _vsnprintf_s( char (&buffer)[size], @@ -60,6 +65,7 @@ int _vsnprintf_s( const char *format, va_list argptr ); // C++ only + template int _vsnwprintf_s( wchar_t (&buffer)[size], @@ -71,88 +77,101 @@ int _vsnwprintf_s( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for output. -*`sizeOfBuffer`*
-The size of the *`buffer`* for output, as the character count. +*`sizeOfBuffer`*\ +The size of the *`buffer`* for output. Size in **bytes** for the functions that take `char`, and **words** for those that take `wchar_t`. -*`count`*
-Maximum number of characters to write (not including the terminating null), or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +Maximum number of characters to write not including the terminating `NULL`. For the functions that take `wchar_t`, it's the number of wide characters to write. Or [`_TRUNCATE`](../truncate.md). -*`format`*
+*`format`*\ Format specification. -*`argptr`*
+*`argptr`*\ Pointer to list of arguments. -*`locale`*
-The locale to use. - -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +*`locale`*\ +The locale to use when formatting the output. -## Return Value +For more information, see [Format specifications](../format-specification-syntax-printf-and-wprintf-functions.md). -**`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. +## Return value -* If *`count`* is less than *`sizeOfBuffer`* and the number of characters of data is less than or equal to *`count`*, or *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written and the number of characters is returned. +The number of characters written, not including the terminating `NULL`, or a negative value if an output error occurs. -* 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. - -* If *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md) and the number of characters of data equals or exceeds *`sizeOfBuffer`*, then as much of the string as will fit in *`buffer`* (with terminating null) is written. Truncation of the remaining data occurs and -1 is returned without invoking the invalid parameter handler. - -* If *`count`* is equal to or exceeds *`sizeOfBuffer`* but the number of characters of data is less than *`sizeOfBuffer`*, then all of the data is written (with terminating null) and the number of characters is returned. - -* If *`count`* and the number of characters of data both equal or exceed *`sizeOfBuffer`*, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution continues after the invalid parameter handler, these functions set *buffer* to an empty string, set **`errno`** to **`ERANGE`**, and return -1. - -* If *`buffer`* or *`format`* is a **`NULL`** pointer, or if *`count`* is less than or equal to zero, the invalid parameter handler is invoked. If execution is allowed to continue, these functions set **`errno`** to **`EINVAL`** and return -1. - -### Error Conditions - -|**Condition**|Return|**`errno`**| -|-----------------|------------|-------------| -|*`buffer`* is **`NULL`**|-1|**`EINVAL`**| -|*`format`* is **`NULL`**|-1|**`EINVAL`**| -|*`count`* <= 0|-1|**`EINVAL`**| -|*`sizeOfBuffer`* too small (and *`count`* != **`_TRUNCATE`**)|-1 (and *`buffer`* set to an empty string)|**`ERANGE`**| +See [Behavior summary](#behavior-summary) for details. ## Remarks -**`vsnprintf_s`** is identical to **`_vsnprintf_s`**. **`vsnprintf_s`** is included for conformance to the ANSI standard. **`_vnsprintf`** is retained for backward compatibility. - -Each of these functions takes a pointer to an argument list, then formats and writes up to *`count`* characters of the given data to the memory pointed to by *`buffer`* and appends a terminating null. +Each of these functions takes a pointer to an argument list, then formats and writes up to *`count`* characters of the given data to the memory pointed to by *`buffer`* and appends a terminating `NULL`. -If *`count`* is [`_TRUNCATE`](../../c-runtime-library/truncate.md), then these functions write as much of the string as will fit in *`buffer`* while leaving room for a terminating null. If the entire string (with terminating null) fits in *`buffer`*, then these functions return the number of characters written (not including the terminating null); otherwise, these functions return -1 to indicate that truncation occurred. +In debug builds, the remaining `sizeOfBuffer` bytes following the terminating `NULL` are filled with 'xFE' as described in [`_CrtSetDebugFillThreshold`](crtsetdebugfillthreshold.md). The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +**`vsnprintf_s`** is identical to **`_vsnprintf_s`** and is included for conformance to the ANSI standard. **`_vnsprintf`** is retained for backward compatibility. + +### Behavior summary + +For the following table: + +- Let `len` be the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. +- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). + +| Condition | Behavior | Return value | `errno` | Invokes invalid parameter handler| +|--|--|--|--|--| +| Success | Writes the characters into the buffer using the specified format string | The number of characters written | N/A | No | +| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops. | -1 | `EILSEQ (42)` | No | +| Encoding error during formatting | If processing character specifier `c` or `C`, the invalid character is skipped. The number of characters written isn't incremented for the skipped character, nor is any data written for it. Processing the format specification continues after skipping the specifier with the encoding error. | The number of characters written, not including the terminating `NULL`. | `EILSEQ (42)` | No | +| `buffer == NULL` and `sizeOfBuffer == 0` and `count == 0` | No data is written. | 0 | N/A | No | +| `buffer == NULL` and either `sizeOfBuffer != 0` or `count != 0` | If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value.| -1 | `EINVAL` (22) | Yes | +| `buffer != NULL` and `sizeOfBuffer == 0` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | +| `buffer != NULL` and `sizeOfBuffer != 0` and `count == 0` | The buffer is `NULL` terminated. | -1 | N/A | No | +| `count == 0`| Doesn't write any data and returns the number of characters that would have been written, not including the terminating `NULL`. | The number of characters that would have been written not including the terminating `NULL`. | N/A | No | +| `count < 0` | Unsafe: the value is treated as unsigned, likely creating a large value that results in overwriting the memory that follows the buffer. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count < sizeOfBuffer` and `len <= count` | All of the data is written and a terminating `NULL` is appended. | The number of characters written. | N/A | No | +| `count < sizeOfBuffer` and `len > count` | The first *`count`* characters are written. | -1 | N/A | No | +| `count >= sizeOfBuffer` and `len < sizeOfBuffer` | All of the data is written with a terminating `NULL`. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count >= sizeOfBuffer` and `len >= sizeOfBuffer` and `count != _TRUNCATE` | If execution continues after invalid parameter handler executes, sets `errno`, sets `buffer[0] == NULL`, and returns a negative value. | -1 | `ERANGE` (34) | Yes | +| `count == _TRUNCATE` and `len >= sizeOfBuffer` | Writes as much of the string as fits in *`buffer`*, including the terminating `NULL`. | -1 | N/A | No | +| `count == _TRUNCATE` and `len < sizeOfBuffer` | Writes the entire string into *`buffer`* with terminating `NULL`. | Number of characters written. | N/A | No | +| `format == NULL` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | + +For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). + > [!IMPORTANT] -> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). > [!NOTE] -> To ensure that there is room for the terminating null, be sure that *`count`* is strictly less than the buffer length, or use **`_TRUNCATE`**. +> To ensure that there is room for the terminating `NULL`, be sure that *`count`* is strictly less than the buffer length, or use `_TRUNCATE`. + +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +> [!TIP] +> If you get an undefined external `_vsnprintf_s` error and are using the Universal C Runtime, add `legacy_stdio_definitions.lib` to the set of libraries to link. The Universal C Runtime doesn't export this function directly and is instead defined inline in ``. For more information, see [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md#libraries) and [Visual Studio 2015 conformance changes](../../porting/visual-cpp-change-history-2003-2015.md#stdio_and_conio). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vsntprintf_s`**|**`_vsnprintf_s`**|**`_vsnprintf_s`**|**`_vsnwprintf_s`**| -|**`_vsntprintf_s_l`**|**`_vsnprintf_s_l`**|**`_vsnprintf_s_l`**|**`_vsnwprintf_s_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vsntprintf_s` | **`_vsnprintf_s`** | **`_vsnprintf_s`** | **`_vsnwprintf_s`** | +| `_vsntprintf_s_l` | **`_vsnprintf_s_l`** | **`_vsnprintf_s_l`** | **`_vsnwprintf_s_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`vsnprintf_s`**|`` and ``|``*| -|**`_vsnprintf_s`**, **`_vsnprintf_s_l`**|`` and ``|``*| -|**`_vsnwprintf_s`**, **`_vsnwprintf_s_l`**|`` or ``, and ``|``*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vsnprintf_s`** | `` and `` | ``* | +| **`_vsnprintf_s`**, **`_vsnprintf_s_l`** | `` and `` | ``* | +| **`_vsnwprintf_s`**, **`_vsnwprintf_s_l`** | `` or ``, and `` | ``* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -188,9 +207,9 @@ nSize: -1, buff: Hi there! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md b/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md index 15b2afda7d2..7a90fece022 100644 --- a/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md +++ b/docs/c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md @@ -1,12 +1,12 @@ --- title: "vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l" description: "API reference for vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, and _vsnwprintf_l; which write formatted output using a pointer to a list of arguments." -ms.date: "3/9/2021" +ms.date: 06/27/2023 api_name: ["_vsnprintf", "_vsnprintf_l", "_vsnwprintf", "_vsnwprintf_l", "_vsnprintf", "_vsnprintf;", "vsnprintf; _vsnprintf", "_vsnwprintf;", "_vsnprintf_l;", "_vsnwprintf_l;"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ntoskrnl.exe", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vsnprintf", "_vsnwprintf", "_vsntprintf", "vsnprintf", "stdio/vsnprintf", "stdio/_vsnprintf", "stdio/_vsnprintf_l", "stdio/_vsnwprintf", "stdio/_vsnwprintf_l", "_vsnprintf_l", "_vsnwprintf_l"] +f1_keywords: ["STDIO/vsnprintf", "STDIO/_vsnprintf", "CORECRT_WSTDIO/_vsnwprintf", "TCHAR/_vsntprintf", "STDIO/_vsnprintf_l", "CORECRT_WSTDIO/_vsnwprintf_l", "TCHAR/_vsntprintf_l", "vsnprintf", "_vsnprintf", "_vsnwprintf", "_vsntprintf", "_vsnprintf_l", "_vsnwprintf_l", "_vsntprintf_l"] helpviewer_keywords: ["vsntprintf function", "_vsnwprintf_l function", "vsnwprintf_l function", "vsntprintf_l function", "_vsntprintf function", "_vsnprintf_l function", "vsnprintf function", "_vsntprintf_l function", "vsnprintf_l function", "_vsnwprintf function", "_vsnprintf function", "formatted text [C++]", "vsnwprintf function"] --- # `vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l` @@ -22,12 +22,14 @@ int vsnprintf( const char *format, va_list argptr ); + int _vsnprintf( char *buffer, size_t count, const char *format, va_list argptr ); + int _vsnprintf_l( char *buffer, size_t count, @@ -35,12 +37,14 @@ int _vsnprintf_l( _locale_t locale, va_list argptr ); + int _vsnwprintf( wchar_t *buffer, size_t count, const wchar_t *format, va_list argptr ); + int _vsnwprintf_l( wchar_t *buffer, size_t count, @@ -48,6 +52,7 @@ int _vsnwprintf_l( _locale_t locale, va_list argptr ); + template int vsnprintf( char (&buffer)[size], @@ -55,6 +60,7 @@ int vsnprintf( const char *format, va_list argptr ); // C++ only + template int _vsnprintf( char (&buffer)[size], @@ -62,6 +68,7 @@ int _vsnprintf( const char *format, va_list argptr ); // C++ only + template int _vsnprintf_l( char (&buffer)[size], @@ -70,6 +77,7 @@ int _vsnprintf_l( _locale_t locale, va_list argptr ); // C++ only + template int _vsnwprintf( wchar_t (&buffer)[size], @@ -77,6 +85,7 @@ int _vsnwprintf( const wchar_t *format, va_list argptr ); // C++ only + template int _vsnwprintf_l( wchar_t (&buffer)[size], @@ -89,69 +98,89 @@ int _vsnwprintf_l( ### Parameters -*`buffer`*
+*`buffer`*\ Storage location for output. -*`count`*
-Maximum number of characters to write. +*`count`*\ +Maximum number of characters to write. For the functions that take `wchar_t`, it's the number of wide characters to write. -*`format`*
+*`format`*\ Format specification. -*`argptr`*
+*`argptr`*\ Pointer to list of arguments. -*`locale`*
+*`locale`*\ The locale to use. -For more information, see [Format Specifications](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). +For more information, see [Format specification syntax](../format-specification-syntax-printf-and-wprintf-functions.md). -## Return Value +## Return value -The **`vsnprintf`** function returns the number of characters that are written, not counting the terminating null character. If the buffer size specified by *`count`* isn't sufficiently large to contain the output specified by *`format`* and *`argptr`*, the return value of **`vsnprintf`** is the number of characters that would be written, not counting the null character, if *`count`* were sufficiently large. If the return value is greater than *`count`* - 1, the output has been truncated. A return value of -1 indicates that an encoding error has occurred. +The number of characters written, not including the terminating `NULL`, or a negative value if an output error occurs. -Both **`_vsnprintf`** and **`_vsnwprintf`** functions return the number of characters written if the number of characters to write is less than or equal to *`count`*. If the number of characters to write is greater than *`count`*, these functions return -1 indicating that output has been truncated. - -The value returned by all these functions doesn't include the terminating null, whether one is written or not. - -- If *`count`* is zero and *`buffer`* is **`NULL`**, the value returned is the number of characters the functions would write. The value does not take into account a terminating **`NULL`**. You can use this result to allocate sufficient buffer space for the string and its terminating null, and then call the function again to fill the buffer. -- If *`count`* is zero but *`buffer`* isn't **`NULL`**, nothing is written and the function returns `-1`. -- If *`format`* is **`NULL`**, or if *`buffer`* is **`NULL`** and *count* isn't equal to zero, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +See [Behavior summary](#behavior-summary) for details. ## Remarks -Each of these functions takes a pointer to an argument list, then formats the data, and writes up to *`count`* characters to the memory pointed to by *`buffer`*. The **`vsnprintf`** function always writes a null terminator, even if it truncates the output. When using **`_vsnprintf`** and **`_vsnwprintf`**, the buffer will be null-terminated only if there's room at the end (that is, if the number of characters to write is less than *`count`*). +Each of these functions takes a pointer to an argument list, then formats the data, and writes up to *`count`* characters to the memory pointed to by *`buffer`*. The **`vsnprintf`** function always writes a null terminator, even if it truncates the output. When you use **`_vsnprintf`** and **`_vsnwprintf`**, the buffer is null-terminated only if there's room at the end (that is, if the number of characters to write is less than *`count`*). + +Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`vsnprintf`** is no longer identical to **`_vsnprintf`**. The **`vsnprintf`** function conforms to the C99 standard; **`_vsnprintf`** is kept for backward compatibility with older code. The difference is that if you run out of buffer, `vsnprintf` null-terminates the end of the buffer and returns the number of characters that would have been required, while `_vsnprintf` doesn't null-terminate the buffer and returns -1. Also, `_vsnprintf()` includes one more character in the output because it doesn't null-terminate the buffer. > [!IMPORTANT] -> To prevent certain kinds of security risks, ensure that *format* isn't a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> To prevent certain kinds of security risks, ensure that *`format`* isn't a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). > [!NOTE] > To ensure that there's room for the terminating null when calling **`_vsnprintf`**, **`_vsnprintf_l`**, **`_vsnwprintf`** and **`_vsnwprintf_l`**, be sure that *`count`* is strictly less than the buffer length and initialize the buffer to null prior to calling the function. > -> Because **`vsnprintf`** always writes the terminating null, the *count* parameter may be equal to the size of the buffer. - -Beginning with the UCRT in Visual Studio 2015 and Windows 10, **`vsnprintf`** is no longer identical to **`_vsnprintf`**. The **`vsnprintf`** function conforms to the C99 standard; **`_vnsprintf`** is kept for backward compatibility with older Visual Studio code. +> Because **`vsnprintf`** always writes a terminating null, the *`count`* parameter may be equal to the size of the buffer. The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). + +### Behavior summary + +For the following table: + +- Let `sizeOfBuffer` be the size of `buffer`. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Let `len` be the size of the formatted data. If the function takes a `char` buffer, the size is in bytes. If the function takes a `wchar_t` buffer, the size specifies the number of 16-bit words. +- Characters refer to `char` characters for functions that take a `char` buffer, and to `wchar_t` characters for functions that take a `wchar_t` buffer. +- For more information about the invalid parameter handler, see [Parameter Validation](../../c-runtime-library/parameter-validation.md). + +| Condition | Behavior | Return value | `errno` | Invokes invalid parameter handler| +|--|--|--|--|--| +| Success | Writes the characters into the buffer using the specified format string. | The number of characters written, not counting the terminating null character. | N/A | No | +| Encoding error during formatting | If processing string specifier `s`, `S`, or `Z`, format specification processing stops. | -1 | `EILSEQ` (42) | No | +| Encoding error during formatting | If processing character specifier `c` or `C`, the invalid character is skipped. The number of characters written isn't incremented for the skipped character, nor is any data written for it. Processing the format specification continues after skipping the specifier with the encoding error. | The number of characters written, not including the terminating `NULL`. | `EILSEQ` (42) | No | +| `buffer == NULL` and `count != 0` | If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value.| -1 | `EINVAL` (22) | Yes | +| `buffer == NULL` and `count == 0` | No data is written | The number of characters that would have been written, not including the terminating `NULL`. You can use this result to allocate sufficient buffer space for the string and a terminating `NULL`, and then call the function again to fill the buffer. | N/A | No | +| `count == 0` | No data is written | -1 | `ERANGE` (34) | No | +| `count < 0`| Unsafe: the value is treated as unsigned, likely creating a large value that results in overwriting the memory that follows the buffer. | The number of characters written. | N/A | No | +| `count < sizeOfBuffer` and `len <= count` | All of the data is written and a terminating `NULL` is appended. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count < sizeOfBuffer` and `len > count` | The first *`count-1`* characters are written followed by a null-terminator. | The number of characters that would have been written had `count` matched the number of characters to output, not including the null-terminator. | N/A | No | +| `count >= sizeOfBuffer` and `len < sizeOfBuffer` | All of the data is written with a terminating `NULL`. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `count >= sizeOfBuffer` and `len >= sizeOfBuffer` | Unsafe: overwrites the memory that follows the buffer. | The number of characters written, not including the terminating `NULL`. | N/A | No | +| `format == NULL` | No data is written. If execution continues after invalid parameter handler executes, sets `errno` and returns a negative value. | -1 | `EINVAL` (22) | Yes | + +For information about these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE` & `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vsntprintf`**|**`_vsnprintf`**|**`_vsnprintf`**|**`_vsnwprintf`**| -|**`_vsntprintf_l`**|**`_vsnprintf_l`**|**`_vsnprintf_l`**|**`_vsnwprintf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vsntprintf` | **`_vsnprintf`** | **`_vsnprintf`** | **`_vsnwprintf`** | +| `_vsntprintf_l` | **`_vsnprintf_l`** | **`_vsnprintf_l`** | **`_vsnwprintf_l`** | ## Requirements -|Routine|Required header (C)|Required header (C++)| -|-------------|---------------------------|-------------------------------| -|**`vsnprintf`**, **`_vsnprintf`**, **`_vsnprintf_l`**|``|`` or ``| -|**`_vsnwprintf`**, **`_vsnwprintf_l`**|`` or ``|``, ``, ``, or ``| +| Routine | Required header (C) | Required header (C++) | +|---|---|---| +| **`vsnprintf`**, **`_vsnprintf`**, **`_vsnprintf_l`** | `` | `` or `` | +| **`_vsnwprintf`**, **`_vsnwprintf_l`** | `` or `` | ``, ``, ``, or `` | -The **`_vsnprintf`**, **`_vsnprintf_l`**, **`_vsnwprintf`** and **`_vsnwprintf_l`** functions are Microsoft-specific. For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +The **`_vsnprintf`**, **`_vsnprintf_l`**, **`_vsnwprintf`** and **`_vsnwprintf_l`** functions are Microsoft-specific. For more compatibility information, see [Compatibility](../compatibility.md). ## Example: Use wide characters with `_vsnwprintf()` @@ -233,10 +262,10 @@ nSize: 10, buff: Hi there! ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)
-[Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
-[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)
-[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md b/docs/c-runtime-library/reference/vsprintf-p-vsprintf-p-l-vswprintf-p-vswprintf-p-l.md index 35fe461896a..7b74d3eb27a 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 @@ -1,15 +1,15 @@ --- -description: "Learn more about: _vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l" title: "_vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l" -ms.date: "3/9/2021" +description: "Learn more about: _vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l" +ms.date: 3/9/2021 api_name: ["_vsprintf_p", "_vswprintf_p", "_vsprintf_p_l", "_vswprintf_p_l"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vsprintf_p", "_vswprintf_p", "_vstprintf_p", "vswprintf_p", "_vsprintf_p", "vstprintf_p"] +f1_keywords: ["STDIO/_vsprintf_p", "CORECRT_WSTDIO/_vswprintf_p", "TCHAR/_vstprintf_p", "STDIO/_vsprintf_p_l", "CORECRT_WSTDIO/_vswprintf_p_l", "TCHAR/_vstprintf_p_l", "_vsprintf_p", "_vswprintf_p", "_vstprintf_p", "_vsprintf_p_l", "_vswprintf_p_l", "_vstprintf_p_l"] helpviewer_keywords: ["vstprintf_p_l function", "_vsprintf_p_l function", "_vstprintf_p function", "vsprintf_p_l function", "_vswprintf_p function", "vswprintf_p function", "vsprintf_p function", "vswprintf_p_l function", "_vswprintf_p_l function", "vstprintf_p function", "formatted text [C++]", "_vsprintf_p function", "_vstprintf_p_l function"] --- -# _vsprintf_p, _vsprintf_p_l, _vswprintf_p, _vswprintf_p_l +# `_vsprintf_p`, `_vsprintf_p_l`, `_vswprintf_p`, `_vswprintf_p_l` Write formatted output using a pointer to a list of arguments, with the ability to specify the order in which the arguments are used. @@ -46,58 +46,60 @@ int _vswprintf_p_l( ### Parameters -*buffer*
+*`buffer`*\ Storage location for output. -*sizeInBytes*
-Size of *buffer* in characters. +*`sizeInBytes`*\ +Size of *`buffer`* in characters. -*count*
+*`count`*\ Maximum number of characters to store, in the UNICODE version of this function. -*format*
+*`format`*\ Format specification. -*argptr*
+*`argptr`*\ Pointer to list of arguments. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value -**_vsprintf_p** and **_vswprintf_p** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. +**`_vsprintf_p`** and **`_vswprintf_p`** return the number of characters written, not including the terminating `NULL` character, or a negative value if an output error occurs. +If the *`buffer`* is a `NULL` pointer and *`sizeInBytes`* or *`count`* are zero, functions return the number of characters that would have been written not including the terminating `NULL`. +If the *`buffer`* is valid and *`sizeInBytes`* or *`count`* are zero, returns -1. ## Remarks -Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *buffer*. +Each of these functions takes a pointer to an argument list, and then formats and writes the given data to the memory pointed to by *`buffer`*. -These functions differ from the **vsprintf_s** and **vswprintf_s** only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +These functions differ from the `vsprintf_s` and `vswprintf_s` only in that they support positional parameters. For more information, see [printf_p Positional Parameters](../printf-p-positional-parameters.md). -The versions of these functions with the **_l** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. +The versions of these functions with the `_l` suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -If the *buffer* or *format* parameters are **NULL** pointers, if count is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **errno** to **EINVAL**. +If the *`buffer`* or *`format`* parameters are `NULL` pointers, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. > [!IMPORTANT] -> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstprintf_p**|**_vsprintf_p**|**_vsprintf_p**|**_vswprintf_p**| -|**_vstprintf_p_l**|**_vsprintf_p_l**|**_vsprintf_p_l**|**_vswprintf_p_l**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstprintf_p` | **`_vsprintf_p`** | **`_vsprintf_p`** | **`_vswprintf_p`** | +| `_vstprintf_p_l` | **`_vsprintf_p_l`** | **`_vsprintf_p_l`** | **`_vswprintf_p_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**_vsprintf_p**, **_vsprintf_p_l**|\ and \|\*| -|**_vswprintf_p**, **_vswprintf_p_l**|\ or \, and \|\*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`_vsprintf_p`**, **`_vsprintf_p_l`** | \ and \ | \* | +| **`_vswprintf_p`**, **`_vswprintf_p_l`** | \ or \, and \ | \* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -150,10 +152,10 @@ This is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[vprintf Functions](../../c-runtime-library/vprintf-functions.md)
-[Format Specification Syntax: printf and wprintf Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)
-[fprintf, _fprintf_l, fwprintf, _fwprintf_l](fprintf-fprintf-l-fwprintf-fwprintf-l.md)
-[printf, _printf_l, wprintf, _wprintf_l](printf-printf-l-wprintf-wprintf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[va_arg, va_copy, va_end, va_start](va-arg-va-copy-va-end-va-start.md)
+[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ +[`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ +[`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md b/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md index 4fa00766399..94c4dc36323 100644 --- a/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md +++ b/docs/c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md @@ -1,17 +1,19 @@ --- +title: "vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l, _vstprintf_s, _vstprintf_s_l" 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" -ms.date: "3/9/2021" -api_name: ["_vswprintf_s_l", "vsprintf_s", "vswprintf_s", "_vsprintf_s_l"] +ms.date: 3/9/2021 +api_name: ["_vswprintf_s_l", "vsprintf_s", "vswprintf_s", "_vsprintf_s_l", _vstprintf_s, _vstprintf_s_l] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vswprintf_s", "vsprintf_s", "_vstprintf_s"] +f1_keywords: ["CORECRT_WSTDIO/vswprintf_s", "STDIO/vsprintf_s", "TCHAR/_vstprintf_s", "vswprintf_s", "vsprintf_s", "_vstprintf_s", "_vstprintf_s_l", "_vswprintf_s_l"] helpviewer_keywords: ["_vstprintf_s_l function", "vsprintf_s_l function", "_vstprintf_s function", "vswprintf_s function", "vstprintf_s function", "vstprintf_s_l function", "vswprintf_s_l function", "vsprintf_s function", "_vsprintf_s_l function", "formatted text [C++]", "_vswprintf_s_l function"] --- -# `vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l` +# `vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`, `_vstprintf_s`, `_vstprintf_s_l` -Write formatted output using a pointer to a list of arguments. These functions are versions of [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, \`__vswprintf_l`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Write formatted output using a pointer to a list of arguments. These functions are versions of [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, \`__vswprintf_l`](vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). + +For `_vstprintf_s` and `_vstprintf_s_l`, see [Generic-text function mappings](#generic-text-function-mappings). ## Syntax @@ -73,11 +75,11 @@ Pointer to list of arguments. *`locale`*\ The locale to use. -## Return Value +## Return value -**`vsprintf_s`** and **`vswprintf_s`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a null pointer, if *`numberOfElements`* is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the functions return -1 and set **`errno`** to **`EINVAL`**. +**`vsprintf_s`** and **`vswprintf_s`** return the number of characters written, not including the terminating null character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a null pointer, if *`numberOfElements`* is zero, or if the format string contains invalid formatting characters, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the functions return -1 and set `errno` to `EINVAL`. -For information on these and other error codes, see [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -85,32 +87,34 @@ Each of these functions takes a pointer to an argument list, and then formats an **`vswprintf_s`** conforms to the ISO C Standard for **`vswprintf`**, which requires the second parameter, *`count`*, of type **`size_t`**. -These functions differ from the non-secure versions only in that the secure versions support positional parameters. For more information, see [`printf_p` Positional Parameters](../../c-runtime-library/printf-p-positional-parameters.md). +These functions differ from the non-secure versions only in that the secure versions support positional parameters. For more information, see [`printf_p` Positional Parameters](../printf-p-positional-parameters.md). The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. -In C++, using these functions is simplified by template overloads. The overloads can infer buffer length automatically, eliminating the need to specify a size argument. And, they can automatically replace non-secure functions with their secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads. The overloads can infer buffer length automatically, eliminating the need to specify a size argument. And, they can automatically replace non-secure functions with their secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). > [!IMPORTANT] -> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with ['legacy_stdio_float_rounding.obj`](../link-options.md). +> 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 function mappings -### Generic-Text Routine Mappings +The function in the `tchar.h` column maps to the function in the other columns depending on the character set that is defined at compile time. -|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vstprintf_s`**|**`vsprintf_s`**|**`vsprintf_s`**|**`vswprintf_s`**| -|**`_vstprintf_s_l`**|**`_vsprintf_s_l`**|**`_vsprintf_s_l`**|**`_vswprintf_s_l`**| +| `tchar.h` function | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstprintf_s` | `vsprintf_s` | `vsprintf_s` | `vswprintf_s` | +| `_vstprintf_s_l` | `_vsprintf_s_l` | `_vsprintf_s_l` | `_vswprintf_s_l` | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`vsprintf_s`**, **`_vsprintf_s_l`**|`` and ``|`*`| -|**`vswprintf_s`**, **`_vswprintf_s_l`**|`` or ``, and ``|`*`| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vsprintf_s`**, **`_vsprintf_s_l`** | `` and `` | `*` | +| **`vswprintf_s`**, **`_vswprintf_s_l`** | `` or ``, and `` | `*` | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -157,10 +161,10 @@ This is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ -[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)\ -[Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ -[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `\__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ [`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md b/docs/c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md index 16c497a2c6f..e5eadb3323b 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 @@ -1,12 +1,12 @@ --- -description: "Learn more about: vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l" title: "vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l" -ms.date: "3/9/2021" +description: "Learn more about: vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, __vswprintf_l" +ms.date: 3/9/2021 api_name: ["_vswprintf_l", "_vsprintf_l", "vsprintf", "vswprintf", "__vswprintf_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: ["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` @@ -91,11 +91,15 @@ Pointer to list of arguments. *`locale`*\ The locale to use. -## Return Value +## Return value + +**`vsprintf`** and **`vswprintf`** return the number of characters written, not including the terminating `NULL` character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a `NULL` pointer, these functions invoke the invalid parameter handler, as described in [Parameter validation](../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. -**`vsprintf`** and **`vswprintf`** return the number of characters written, not including the terminating `NULL` character, or a negative value if an output error occurs. If *`buffer`* or *`format`* is a `NULL` pointer, these functions invoke the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **`errno`** to **`EINVAL`**. +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 [`_doserrno`, `errno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information on these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks @@ -104,30 +108,30 @@ Each of these functions takes a pointer to an argument list, and then formats an The versions of these functions with the **`_l`** suffix are identical except that they use the locale parameter passed in instead of the current thread locale. > [!IMPORTANT] -> Using **`vsprintf`**, there is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [`_vsnprintf`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [`_vscprintf`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that *`format`* is not a user-defined string. For more information, see [Avoiding Buffer Overruns](/windows/win32/SecBP/avoiding-buffer-overruns). -> 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). +> Using **`vsprintf`**, there is no way to limit the number of characters written, which means that code using this function is susceptible to buffer overruns. Use [`_vsnprintf`](vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) instead, or call [`_vscprintf`](vscprintf-vscprintf-l-vscwprintf-vscwprintf-l.md) to determine how large a buffer is needed. Also, ensure that *`format`* is not a user-defined string. For more information, see [Avoiding buffer overruns](/windows/win32/SecBP/avoiding-buffer-overruns). +> Starting in Windows 10 version 2004 (build 19041), the `printf` family of functions prints exactly representable floating point numbers according to the IEEE 754 rules for rounding. In previous versions of Windows, exactly representable floating point numbers ending in '5' would always round up. IEEE 754 states that they must round to the closest even digit (also known as "Banker's Rounding"). For example, both `printf("%1.0f", 1.5)` and `printf("%1.0f", 2.5)` should round to 2. Previously, 1.5 would round to 2 and 2.5 would round to 3. This change only affects exactly representable numbers. For example, 2.35 (which, when represented in memory, is closer to 2.35000000000000008) continues to round up to 2.4. Rounding done by these functions now also respects the floating point rounding mode set by [`fesetround`](fegetround-fesetround2.md). Previously, rounding always chose `FE_TONEAREST` behavior. This change only affects programs built using Visual Studio 2019 version 16.2 and later. To use the legacy floating point rounding behavior, link with [`legacy_stdio_float_rounding.obj`](../link-options.md). -**`vswprintf`** conforms to the ISO C Standard, which requires the second parameter, *`count`*, of type **`size_t`**. To force the old nonstandard behavior, define **`_CRT_NON_CONFORMING_SWPRINTFS`**. The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. +**`vswprintf`** conforms to the ISO C Standard, which requires the second parameter, *`count`*, of type **`size_t`**. To force the old nonstandard behavior, define `_CRT_NON_CONFORMING_SWPRINTFS`. The old behavior may not be in a future version, so code should be changed to use the new conformant behavior. -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`TCHAR.H` routine|`_UNICODE & _MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**`_vstprintf`**|**`vsprintf`**|**`vsprintf`**|**`vswprintf`**| -|**`_vstprintf_l`**|**`_vsprintf_l`**|**`_vsprintf_l`**|**`_vswprintf_l`**| +| `TCHAR.H` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstprintf` | **`vsprintf`** | **`vsprintf`** | **`vswprintf`** | +| `_vstprintf_l` | **`_vsprintf_l`** | **`_vsprintf_l`** | **`_vswprintf_l`** | ## Requirements -|Routine|Required header|Optional headers| -|-------------|---------------------|----------------------| -|**`vsprintf`**, **`_vsprintf_l`**|`` and ``|``*| -|**`vswprintf`**, **`_vswprintf_l`**|`` or ``, and ``|``*| +| Routine | Required header | Optional headers | +|---|---|---| +| **`vsprintf`**, **`_vsprintf_l`** | `` and `` | ``* | +| **`vswprintf`**, **`_vswprintf_l`** | `` or ``, and `` | ``* | \* Required for UNIX V compatibility. -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -180,10 +184,10 @@ This is a string ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)\ -[`vprintf` Functions](../../c-runtime-library/vprintf-functions.md)\ -[Format Specification Syntax: `printf` and `wprintf` Functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[Stream I/O](../stream-i-o.md)\ +[`vprintf` functions](../vprintf-functions.md)\ +[Format specification syntax: `printf` and `wprintf` functions](../format-specification-syntax-printf-and-wprintf-functions.md)\ [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](fprintf-fprintf-l-fwprintf-fwprintf-l.md)\ [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](printf-printf-l-wprintf-wprintf-l.md)\ -[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `\__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ [`va_arg`, `va_copy`, `va_end`, `va_start`](va-arg-va-copy-va-end-va-start.md) diff --git a/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md b/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md index d0f8aac3d11..2ba236d4262 100644 --- a/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md +++ b/docs/c-runtime-library/reference/vsscanf-s-vswscanf-s.md @@ -6,12 +6,12 @@ api_name: ["vswscanf_s", "vsscanf_s"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["vsscanf_s", "vswscanf_s", "_vstscanf_s"] +f1_keywords: ["STDIO/vsscanf_s", "CORECRT_WSTDIO/vswscanf_s", "TCHAR/_vstscanf_s", "vsscanf_s", "vswscanf_s", "_vstscanf_s"] ms.assetid: 7b732e68-c6f4-4579-8917-122f5a7876e1 --- -# vsscanf_s, vswscanf_s +# `vsscanf_s`, `vswscanf_s` -Reads formatted data from a string. These versions of [vsscanf, vswscanf](vsscanf-vswscanf.md) have security enhancements, as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Reads formatted data from a string. These versions of [`vsscanf`, `vswscanf`](vsscanf-vswscanf.md) have security enhancements, as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -30,52 +30,52 @@ int vswscanf_s( ### Parameters -*buffer*
+*`buffer`*\ Stored data -*format*
-Format-control string. For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *buffer* or *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vsscanf_s** function reads data from *buffer* into the locations that are given by each argument in the *arglist* argument list. The arguments in the argument list specify pointers to variables that have a type that corresponds to a type specifier in *format*. Unlike the less secure version **vsscanf**, a buffer size parameter is required when you use the type field characters **c**, **C**, **s**, **S**, or string-control sets that are enclosed in **[]**. The buffer size in characters must be supplied as an additional parameter immediately after each buffer parameter that requires it. +The **`vsscanf_s`** function reads data from *`buffer`* into the locations that are given by each argument in the *`arglist`* argument list. The arguments in the argument list specify pointers to variables that have a type that corresponds to a type specifier in *`format`*. Unlike the less secure version **`vsscanf`**, a buffer size parameter is required when you use the type field characters **c**, **C**, **s**, **S**, or string-control sets that are enclosed in **[]**. The buffer size in characters must be supplied as another parameter immediately after each buffer parameter that requires it. -The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too big to fit in the buffer, nothing is written to that buffer. +The buffer size includes the terminating null. A width specification field may be used to ensure that the token that's read in will fit into the buffer. If no width specification field is used, and the token read in is too large to fit in the buffer, nothing is written to that buffer. -For more information, see [scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [scanf Type Field Characters](../../c-runtime-library/scanf-type-field-characters.md). +For more information, see [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) and [scanf Type Field Characters](../scanf-type-field-characters.md). > [!NOTE] -> The size parameter is of type **`unsigned`**, not **size_t**. +> The size parameter is of type **`unsigned`**, not `size_t`. -The *format* argument controls the interpretation of the input fields and has the same form and function as the *format* argument for the **scanf_s** function. If copying occurs between strings that overlap, the behavior is undefined. +The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the `scanf_s` function. If copying occurs between strings that overlap, the behavior is undefined. -**vswscanf_s** is a wide-character version of **vsscanf_s**; the arguments to **vswscanf_s** are wide-character strings. **vsscanf_s** does not handle multibyte hexadecimal characters. **vswscanf_s** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **vswscanf_s** and **vsscanf_s** behave identically. +**`vswscanf_s`** is a wide-character version of **`vsscanf_s`**; the arguments to **`vswscanf_s`** are wide-character strings. **`vsscanf_s`** doesn't handle multibyte hexadecimal characters. **`vswscanf_s`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`vswscanf_s`** and **`vsscanf_s`** behave identically. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstscanf_s**|**vsscanf_s**|**vsscanf_s**|**vswscanf_s**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstscanf_s` | **`vsscanf_s`** | **`vsscanf_s`** | **`vswscanf_s`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vsscanf_s**|\| -|**vswscanf_s**|\ or \| +| Routine | Required header | +|---|---| +| **`vsscanf_s`** | \ | +| **`vswscanf_s`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -131,9 +131,9 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[vsscanf, vswscanf](vsscanf-vswscanf.md)
+[Stream I/O](../stream-i-o.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vsscanf`, `vswscanf`](vsscanf-vswscanf.md) diff --git a/docs/c-runtime-library/reference/vsscanf-vswscanf.md b/docs/c-runtime-library/reference/vsscanf-vswscanf.md index 118fbd3d9a9..456e5cf8ad9 100644 --- a/docs/c-runtime-library/reference/vsscanf-vswscanf.md +++ b/docs/c-runtime-library/reference/vsscanf-vswscanf.md @@ -6,13 +6,13 @@ api_name: ["vsscanf", "vswscanf"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_vstscanf", "vsscanf", "vswscanf"] +f1_keywords: ["TCHAR/_vstscanf", "STDIO/vsscanf", "CORECRT_WSTDIO/vswscanf", "_vstscanf", "vsscanf", "vswscanf"] helpviewer_keywords: ["vswscanf function", "vsscanf function"] ms.assetid: e96180f2-df46-423d-b4eb-0a49ab819bde --- -# vsscanf, vswscanf +# `vsscanf`, `vswscanf` -Reads formatted data from a string. More secure versions of these functions are available; see [vsscanf_s, vswscanf_s](vsscanf-s-vswscanf-s.md). +Reads formatted data from a string. More secure versions of these functions are available; see [`vsscanf_s`, `vswscanf_s`](vsscanf-s-vswscanf-s.md). ## Syntax @@ -31,46 +31,46 @@ int vswscanf( ### Parameters -*buffer*
+*`buffer`*\ Stored data -*format*
-Format-control string. For more information, see [Format Specification Fields: scanf and wscanf Functions](../../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md). +*`format`*\ +Format-control string. For more information, see [Format specification fields: `scanf` and `wscanf` functions](../format-specification-fields-scanf-and-wscanf-functions.md). -*arglist*
+*`arglist`*\ Variable argument list. -## Return Value +## Return value -Each of these functions returns the number of fields that are successfully converted and assigned; the return value does not include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is **EOF** for an error or if the end of the string is reached before the first conversion. +Each of these functions returns the number of fields that are successfully converted and assigned. The return value doesn't include fields that were read but not assigned. A return value of 0 indicates that no fields were assigned. The return value is `EOF` for an error or if the end of the string is reached before the first conversion. -If *buffer* or *format* is a **NULL** pointer, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, these functions return -1 and set **errno** to **EINVAL**. +If *`buffer`* or *`format`* is a `NULL` pointer, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, these functions return -1 and set `errno` to `EINVAL`. -For information about these and other error codes, see [errno, _doserrno, _sys_errlist, and _sys_nerr](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For information about these and other error codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). ## Remarks -The **vsscanf** function reads data from *buffer* into the locations that are given by each argument in the *arglist* argument list. Every argument in the list must be a pointer to a variable that has a type that corresponds to a type specifier in *format*. The *format* argument controls the interpretation of the input fields and has the same form and function as the *format* argument for the **scanf** function. If copying takes place between strings that overlap, the behavior is undefined. +The **`vsscanf`** function reads data from *`buffer`* into the locations that are given by each argument in the *`arglist`* argument list. Every argument in the list must be a pointer to a variable that has a type that corresponds to a type specifier in *`format`*. The *`format`* argument controls the interpretation of the input fields and has the same form and function as the *`format`* argument for the `scanf` function. If copying takes place between strings that overlap, the behavior is undefined. > [!IMPORTANT] -> When you use **vsscanf** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. +> When you use **`vsscanf`** to read a string, always specify a width for the **%s** format (for example, **"%32s"** instead of **"%s"**); otherwise, incorrectly formatted input can cause a buffer overrun. -**vswscanf** is a wide-character version of **vsscanf**; the arguments to **vswscanf** are wide-character strings. **vsscanf** does not handle multibyte hexadecimal characters. **vswscanf** does not handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **vswscanf** and **vsscanf** behave identically. +**`vswscanf`** is a wide-character version of **`vsscanf`**; the arguments to **`vswscanf`** are wide-character strings. **`vsscanf`** doesn't handle multibyte hexadecimal characters. **`vswscanf`** doesn't handle Unicode full-width hexadecimal or "compatibility zone" characters. Otherwise, **`vswscanf`** and **`vsscanf`** behave identically. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|TCHAR.H routine|_UNICODE & _MBCS not defined|_MBCS defined|_UNICODE defined| -|---------------------|------------------------------------|--------------------|-----------------------| -|**_vstscanf**|**vsscanf**|**vsscanf**|**vswscanf**| +| TCHAR.H routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_vstscanf` | **`vsscanf`** | **`vsscanf`** | **`vswscanf`** | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**vsscanf**|\| -|**vswscanf**|\ or \| +| Routine | Required header | +|---|---| +| **`vsscanf`** | \ | +| **`vswscanf`** | \ or \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -125,8 +125,8 @@ Real: = 15.000000 ## See also -[Stream I/O](../../c-runtime-library/stream-i-o.md)
-[scanf, _scanf_l, wscanf, _wscanf_l](scanf-scanf-l-wscanf-wscanf-l.md)
-[sscanf, _sscanf_l, swscanf, _swscanf_l](sscanf-sscanf-l-swscanf-swscanf-l.md)
-[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)
-[vsscanf_s, vswscanf_s](vsscanf-s-vswscanf-s.md)
+[Stream I/O](../stream-i-o.md)\ +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](scanf-scanf-l-wscanf-wscanf-l.md)\ +[`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](sscanf-sscanf-l-swscanf-swscanf-l.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`vsscanf_s`, `vswscanf_s`](vsscanf-s-vswscanf-s.md) diff --git a/docs/c-runtime-library/reference/wcrtomb-s.md b/docs/c-runtime-library/reference/wcrtomb-s.md index d6186244703..3f0b1ca8b40 100644 --- a/docs/c-runtime-library/reference/wcrtomb-s.md +++ b/docs/c-runtime-library/reference/wcrtomb-s.md @@ -3,16 +3,16 @@ description: "Learn more about: wcrtomb_s" title: "wcrtomb_s" ms.date: "4/2/2020" api_name: ["wcrtomb_s", "_o_wcrtomb_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcrtomb_s"] +f1_keywords: ["WCHAR/wcrtomb_s", "wcrtomb_s"] helpviewer_keywords: ["wide characters, converting", "wcrtomb_s function", "multibyte characters", "characters, converting"] ms.assetid: 9a8a1bd0-1d60-463d-a3a2-d83525eaf656 --- -# wcrtomb_s +# `wcrtomb_s` -Convert a wide character into its multibyte character representation. A version of [wcrtomb](wcrtomb.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a wide character into its multibyte character representation. A version of [`wcrtomb`](wcrtomb.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -35,40 +35,40 @@ errno_t wcrtomb_s( ### Parameters -*pReturnValue*
+*`pReturnValue`*\ Returns the number of bytes written or -1 if an error occurred. -*mbchar*
+*`mbchar`*\ The resulting multibyte converted character. -*sizeOfmbchar*
-The size of the *mbchar* variable in bytes. +*`sizeOfmbchar`*\ +The size of the *`mbchar`* variable in bytes. -*wchar*
+*`wchar`*\ A wide character to convert. -*mbstate*
-A pointer to an **mbstate_t** object. +*`mbstate`*\ +A pointer to an `mbstate_t` object. -## Return Value +## Return value -Returns zero or an **errno** value if an error occurs. +Returns zero or an `errno` value if an error occurs. ## Remarks -The **wcrtomb_s** function converts a wide character, beginning in the specified conversion state contained in *mbstate*, from the value contained in *wchar*, into the address represented by *mbchar*. The *pReturnValue* value will be the number of bytes converted, but no more than **MB_CUR_MAX** bytes, or an -1 if an error occurred. +The **`wcrtomb_s`** function converts a wide character, beginning in the specified conversion state contained in *`mbstate`*, from the value contained in *`wchar`*, into the address represented by *`mbchar`*. The *`pReturnValue`* value will be the number of bytes converted, but no more than `MB_CUR_MAX` bytes, or an -1 if an error occurred. -If *mbstate* is null, the internal **mbstate_t** conversion state is used. If the character contained in *wchar* does not have a corresponding multibyte character, the value of *pReturnValue* will be -1 and the function will return the **errno** value of **EILSEQ**. +If *`mbstate`* is null, the internal `mbstate_t` conversion state is used. If the character contained in *`wchar`* doesn't have a corresponding multibyte character, the value of *`pReturnValue`* is -1, and the function returns the `errno` value of `EILSEQ`. -The **wcrtomb_s** function differs from [wctomb_s, _wctomb_s_l](wctomb-s-wctomb-s-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcslen**, if a subsequent call to **wcsrtombs_s** were used instead of **wcstombs_s**. +The **`wcrtomb_s`** function differs from [`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcslen`, if a subsequent call to `wcsrtombs_s` were used instead of `wcstombs_s`. -In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using this function is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcrtomb_s** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and the *mbstate* is null. +The **`wcrtomb_s`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and the *`mbstate`* is null. ## Example @@ -116,13 +116,13 @@ The corresponding wide character "Q" was converted to a the "Q" multibyte charac ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcrtomb_s**|\| +| Routine | Required header | +|---|---| +| **`wcrtomb_s`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcrtomb.md b/docs/c-runtime-library/reference/wcrtomb.md index 9b622df552c..a88c83cdbe2 100644 --- a/docs/c-runtime-library/reference/wcrtomb.md +++ b/docs/c-runtime-library/reference/wcrtomb.md @@ -3,16 +3,16 @@ description: "Learn more about: wcrtomb" title: "wcrtomb" ms.date: "4/2/2020" api_name: ["wcrtomb", "_o_wcrtomb"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcrtomb"] +f1_keywords: ["WCHAR/wcrtomb", "wcrtomb"] helpviewer_keywords: ["wide characters, converting", "wcrtomb function", "multibyte characters", "characters, converting"] ms.assetid: 717f1b21-2705-4b7f-b6d0-82adc5224340 --- -# wcrtomb +# `wcrtomb` -Convert a wide character into its multibyte character representation. A more secure version of this function is available; see [wcrtomb_s](wcrtomb-s.md). +Convert a wide character into its multibyte character representation. A more secure version of this function is available; see [`wcrtomb_s`](wcrtomb-s.md). ## Syntax @@ -32,34 +32,34 @@ size_t wcrtomb( ### Parameters -*mbchar*
+*`mbchar`*\ The resulting multibyte converted character. -*wchar*
+*`wchar`*\ A wide character to convert. -*mbstate*
-A pointer to an **mbstate_t** object. +*`mbstate`*\ +A pointer to an `mbstate_t` object. -## Return Value +## Return value Returns the number of bytes required to represent the converted multibyte character, otherwise a -1 if an error occurs. ## Remarks -The **wcrtomb** function converts a wide character, beginning in the specified conversion state contained in *mbstate*, from the value contained in *wchar*, into the address represented by *mbchar*. The return value is the number of bytes required to represent the corresponding multibyte character, but it will not return more than **MB_CUR_MAX** bytes. +The **`wcrtomb`** function converts a wide character, beginning in the specified conversion state contained in *`mbstate`*, from the value contained in *`wchar`*, into the address represented by *`mbchar`*. The return value is the number of bytes required to represent the corresponding multibyte character, but it will not return more than `MB_CUR_MAX` bytes. -If *mbstate* is null, the internal **mbstate_t** object containing the conversion state of *mbchar* is used. If the character sequence *wchar* does not have a corresponding multibyte character representation, a -1 is returned and the **errno** is set to **EILSEQ**. +If *`mbstate`* is null, the internal `mbstate_t` object containing the conversion state of *`mbchar`* is used. If the character sequence *`wchar`* doesn't have a corresponding multibyte character representation, a -1 is returned, and the `errno` is set to `EILSEQ`. -The **wcrtomb** function differs from [wctomb, _wctomb_l](wctomb-wctomb-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcsnlen**, if a subsequent call to **wcsrtombs** were used instead of **wcstombs**. +The **`wcrtomb`** function differs from [`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcsnlen`, if a subsequent call to `wcsrtombs` were used instead of `wcstombs`. -In C++, this function has a template overload that invokes the newer, secure counterparts of this function. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, this function has a template overload that invokes the newer, secure counterparts of this function. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcrtomb** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and while the *mbstate* is null. +The **`wcrtomb`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and while the *`mbstate`* is null. ## Example @@ -106,13 +106,13 @@ The corresponding wide character "Q" was converted to the "Q" multibyte characte ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcrtomb**|\| +| Routine | Required header | +|---|---| +| **`wcrtomb`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcsicoll.md b/docs/c-runtime-library/reference/wcsicoll.md index f235899e390..5e73d3af12f 100644 --- a/docs/c-runtime-library/reference/wcsicoll.md +++ b/docs/c-runtime-library/reference/wcsicoll.md @@ -6,12 +6,12 @@ api_name: ["wcsicoll"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcsicoll"] +f1_keywords: ["CORECRT_WSTRING/wcsicoll", "wcsicoll"] helpviewer_keywords: ["wcsicoll function"] ms.assetid: d049022d-cf60-467f-842b-9a508d9aeaff --- -# wcsicoll +# `wcsicoll` -The Microsoft-specific function name `wcsicoll` is a deprecated alias for the [_wcsicoll](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. +The Microsoft-specific function name `wcsicoll` is a deprecated alias for the [`_wcsicoll`](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) function. By default, it generates [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The name is deprecated because it doesn't follow the Standard C rules for implementation-specific names. However, the function is still supported. -We recommend you use [_wcsicoll](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_wcsicoll`](stricoll-wcsicoll-mbsicoll-stricoll-l-wcsicoll-l-mbsicoll-l.md) instead. Or, you can continue to use this function name, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/reference/wcsrtombs-s.md b/docs/c-runtime-library/reference/wcsrtombs-s.md index bab32985cd8..a56efa3cd5a 100644 --- a/docs/c-runtime-library/reference/wcsrtombs-s.md +++ b/docs/c-runtime-library/reference/wcsrtombs-s.md @@ -3,16 +3,16 @@ description: "Learn more about: wcsrtombs_s" title: "wcsrtombs_s" ms.date: "4/2/2020" api_name: ["wcsrtombs_s", "_o_wcsrtombs_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcsrtombs_s"] +f1_keywords: ["WCHAR/wcsrtombs_s", "wcsrtombs_s"] helpviewer_keywords: ["string conversion, wide characters", "wcsrtombs_s function", "wide characters, strings"] ms.assetid: 9dccb766-113c-44bb-9b04-07a634dddec8 --- -# wcsrtombs_s +# `wcsrtombs_s` -Convert a wide character string to its multibyte character string representation. A version of [wcsrtombs](wcsrtombs.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Convert a wide character string to its multibyte character string representation. A version of [`wcsrtombs`](wcsrtombs.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -37,68 +37,68 @@ errno_t wcsrtombs_s( ### Parameters -*pReturnValue*
+*`pReturnValue`*\ The size in bytes of the converted string, including the null terminator. -*mbstr*
+*`mbstr`*\ The address of a buffer for the resulting converted multibyte character string. -*sizeInBytes*
-The size in bytes of the *mbstr* buffer. +*`sizeInBytes`*\ +The size in bytes of the *`mbstr`* buffer. -*wcstr*
+*`wcstr`*\ Points to the wide character string to be converted. -*count*
-The maximum number of bytes to be stored in the *mbstr* buffer, or [_TRUNCATE](../../c-runtime-library/truncate.md). +*`count`*\ +The maximum number of bytes to be stored in the *`mbstr`* buffer, or [`_TRUNCATE`](../truncate.md). -*mbstate*
-A pointer to an **mbstate_t** conversion state object. +*`mbstate`*\ +A pointer to an `mbstate_t` conversion state object. -## Return Value +## Return value Zero if successful, an error code on failure. -|Error condition|Return value and **errno**| -|---------------------|------------------------------| -|*mbstr* is **NULL** and *sizeInBytes* > 0|**EINVAL**| -|*wcstr* is **NULL**|**EINVAL**| -|The destination buffer is too small to contain the converted string (unless *count* is **_TRUNCATE**; see Remarks below)|**ERANGE**| +| Error condition | Return value and `errno` | +|---|---| +| *`mbstr`* is `NULL` and *`sizeInBytes`* > 0 | `EINVAL` | +| *`wcstr`* is `NULL` | `EINVAL` | +| The destination buffer is too small to contain the converted string (unless *`count`* is `_TRUNCATE`; see Remarks below) | `ERANGE` | -If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md) . If execution is allowed to continue, the function returns an error code and sets **errno** as indicated in the table. +If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter validation](../parameter-validation.md) . If execution is allowed to continue, the function returns an error code and sets `errno` as indicated in the table. ## Remarks -The **wcsrtombs_s** function converts a string of wide characters pointed to by *wcstr* into multibyte characters stored in the buffer pointed to by *mbstr*, using the conversion state contained in *mbstate*. The conversion will continue for each character until one of these conditions is met: +The **`wcsrtombs_s`** function converts a string of wide characters pointed to by *`wcstr`* into multibyte characters stored in the buffer pointed to by *`mbstr`*, using the conversion state contained in *`mbstate`*. The conversion will continue for each character until one of these conditions is met: - A null wide character is encountered -- A wide character that cannot be converted is encountered +- A wide character that can't be converted is encountered -- The number of bytes stored in the *mbstr* buffer equals *count*. +- The number of bytes stored in the *`mbstr`* buffer equals *`count`*. -The destination string is always null-terminated (even in the case of an error). +The destination string is always null-terminated (even if there's an error). -If *count* is the special value [_TRUNCATE](../../c-runtime-library/truncate.md), then **wcsrtombs_s** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. +If *`count`* is the special value [`_TRUNCATE`](../truncate.md), then **`wcsrtombs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. -If **wcsrtombs_s** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into `*pReturnValue` (provided *pReturnValue* is not **NULL**). This occurs even if the *mbstr* argument is **NULL** and provides a way to determine the required buffer size. Note that if *mbstr* is **NULL**, *count* is ignored. +If **`wcsrtombs_s`** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into `*pReturnValue` (provided *`pReturnValue`* isn't `NULL`). The size is calculated even if the *`mbstr`* argument is `NULL`; it provides a way to determine the required buffer size. If *`mbstr`* is `NULL`, *`count`* is ignored. -If **wcsrtombs_s** encounters a wide character it cannot convert to a multibyte character, it puts -1 in *\*pReturnValue*, sets the destination buffer to an empty string, sets **errno** to **EILSEQ**, and returns **EILSEQ**. +If **`wcsrtombs_s`** encounters a wide character it can't convert to a multibyte character, it puts -1 in *\*`pReturnValue`*, sets the destination buffer to an empty string, sets `errno` to `EILSEQ`, and returns `EILSEQ`. -If the sequences pointed to by *wcstr* and *mbstr* overlap, the behavior of **wcsrtombs_s** is undefined. **wcsrtombs_s** is affected by the LC_TYPE category of the current locale. +If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcsrtombs_s`** is undefined. **`wcsrtombs_s`** is affected by the LC_TYPE category of the current locale. > [!IMPORTANT] -> Ensure that *wcstr* and *mbstr* do not overlap, and that *count* correctly reflects the number of wide characters to convert. +> Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of wide characters to convert. -The **wcsrtombs_s** function differs from [wcstombs_s, _wcstombs_s_l](wcstombs-s-wcstombs-s-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcslen**, if a subsequent call to **wcsrtombs_s** were used instead of **wcstombs_s**. +The **`wcsrtombs_s`** function differs from [`wcstombs_s`, `_wcstombs_s_l`](wcstombs-s-wcstombs-s-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcslen`, if a subsequent call to **`wcsrtombs_s`** were used instead of `wcstombs_s`. -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcsrtombs_s** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and the *mbstate* is null. +The **`wcsrtombs_s`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and the *`mbstate`* is null. ## Example @@ -149,17 +149,17 @@ The string was successfully converted. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcsrtombs_s**|\| +| Routine | Required header | +|---|---| +| **`wcsrtombs_s`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[wcrtomb](wcrtomb.md)
-[wcrtomb_s](wcrtomb-s.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`wcrtomb`](wcrtomb.md)\ +[`wcrtomb_s`](wcrtomb-s.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcsrtombs.md b/docs/c-runtime-library/reference/wcsrtombs.md index 97f603bc0b0..9df3eb44eed 100644 --- a/docs/c-runtime-library/reference/wcsrtombs.md +++ b/docs/c-runtime-library/reference/wcsrtombs.md @@ -3,16 +3,16 @@ description: "Learn more about: wcsrtombs" title: "wcsrtombs" ms.date: "4/2/2020" api_name: ["wcsrtombs", "_o_wcsrtombs"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcsrtombs"] +f1_keywords: ["WCHAR/wcsrtombs", "wcsrtombs"] helpviewer_keywords: ["wcsrtombs function", "string conversion, wide characters", "wide characters, strings"] ms.assetid: a8d21fec-0d36-4085-9d81-9b1c61c7259d --- -# wcsrtombs +# `wcsrtombs` -Convert a wide character string to its multibyte character string representation. A more secure version of this function is available; see [wcsrtombs_s](wcsrtombs-s.md). +Convert a wide character string to its multibyte character string representation. A more secure version of this function is available; see [`wcsrtombs_s`](wcsrtombs-s.md). ## Syntax @@ -34,39 +34,39 @@ size_t wcsrtombs( ### Parameters -*mbstr*
+*`mbstr`*\ The resulting converted multibyte character string's address location. -*wcstr*
+*`wcstr`*\ Indirectly points to the location of the wide character string to be converted. -*count*
-The number of character to be converted. +*`count`*\ +The number of characters to be converted. -*mbstate*
-A pointer to an **mbstate_t** conversion state object. +*`mbstate`*\ +A pointer to an `mbstate_t` conversion state object. -## Return Value +## Return value Returns the number of bytes successfully converted, not including the null terminating null byte (if any), otherwise a -1 if an error occurred. ## Remarks -The **wcsrtombs** function converts a string of wide characters, beginning in the specified conversion state contained in *mbstate*, from the values indirect pointed to in *wcstr*, into the address of *mbstr*. The conversion will continue for each character until: after a null terminating wide character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in *count*. If **wcsrtombs** encounters the wide-character null character (L'\0') either before or when *count* occurs, it converts it to an 8-bit 0 and stops. +The **`wcsrtombs`** function converts a string of wide characters, beginning in the specified conversion state contained in *`mbstate`*, from the values indirect pointed to in *`wcstr`*, into the address of *`mbstr`*. The conversion will continue for each character until: after a null terminating wide character is encountered, when a non corresponding character is encountered or when the next character would exceed the limit contained in *`count`*. If **`wcsrtombs`** encounters the wide-character null character (L'\0') either before or when *`count`* occurs, it converts it to an 8-bit 0 and stops. -Thus, the multibyte character string at *mbstr* is null-terminated only if **wcsrtombs** encounters a wide character null character during conversion. If the sequences pointed to by *wcstr* and *mbstr* overlap, the behavior of **wcsrtombs** is undefined. **wcsrtombs** is affected by the LC_TYPE category of the current locale. +Thus, the multibyte character string at *`mbstr`* is null-terminated only if **`wcsrtombs`** encounters a wide character null character during conversion. If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcsrtombs`** is undefined. **`wcsrtombs`** is affected by the LC_TYPE category of the current locale. -The **wcsrtombs** function differs from [wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md) by its restartability. The conversion state is stored in *mbstate* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use **wcsrlen** rather than **wcsnlen**, if a subsequent call to **wcsrtombs** were used instead of **wcstombs**. +The **`wcsrtombs`** function differs from [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md) by its restartability. The conversion state is stored in *`mbstate`* for subsequent calls to the same or other restartable functions. Results are undefined when mixing the use of restartable and nonrestartable functions. For example, an application would use `wcsrlen` rather than `wcsnlen`, if a subsequent call to **`wcsrtombs`** were used instead of `wcstombs`. -If the *mbstr* argument is **NULL**, **wcsrtombs** returns the required size in bytes of the destination string. If *mbstate* is null, the internal **mbstate_t** conversion state is used. If the character sequence *wchar* does not have a corresponding multibyte character representation, a -1 is returned and the **errno** is set to **EILSEQ**. +If the *`mbstr`* argument is `NULL`, **`wcsrtombs`** returns the required size in bytes of the destination string. If *`mbstate`* is null, the internal `mbstate_t` conversion state is used. If the character sequence *`wchar`* doesn't have a corresponding multibyte character representation, a -1 is returned, and the `errno` is set to `EILSEQ`. -In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, this function has a template overload that invokes the newer, secure counterpart of this function. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Exceptions -The **wcsrtombs** function is multithread safe as long as no function in the current thread calls **setlocale** while this function is executing and the *mbstate* is not null. +The **`wcsrtombs`** function is multithread safe as long as no function in the current thread calls `setlocale` while this function is executing and the *`mbstate`* isn't null. ## Example @@ -116,17 +116,17 @@ The string was successfuly converted. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wcsrtombs**|\| +| Routine | Required header | +|---|---| +| **`wcsrtombs`** | \ | ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[Interpretation of Multibyte-Character Sequences](../../c-runtime-library/interpretation-of-multibyte-character-sequences.md)
-[wcrtomb](wcrtomb.md)
-[wcrtomb_s](wcrtomb-s.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[mbsinit](mbsinit.md)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[Interpretation of multibyte-character sequences](../interpretation-of-multibyte-character-sequences.md)\ +[`wcrtomb`](wcrtomb.md)\ +[`wcrtomb_s`](wcrtomb-s.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`mbsinit`](mbsinit.md) diff --git a/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md b/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md index 62abbb9f8f0..aed6aa514a8 100644 --- a/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md +++ b/docs/c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md @@ -3,15 +3,15 @@ description: "Learn more about: wcstombs_s, _wcstombs_s_l" title: "wcstombs_s, _wcstombs_s_l" ms.date: 09/30/2021 api_name: ["_wcstombs_s_l", "wcstombs_s", "_o__wcstombs_s_l", "_o_wcstombs_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcstombs_s", "_wcstombs_s_l"] +f1_keywords: ["STDLIB/wcstombs_s", "STDLIB/_wcstombs_s_l", "wcstombs_s", "_wcstombs_s_l"] helpviewer_keywords: ["wcstombs_s function", "string conversion, wide characters", "wide characters, converting", "_wcstombs_s_l function", "wcstombs_s_l function", "characters, converting", "string conversion, multibyte character strings"] --- # `wcstombs_s`, `_wcstombs_s_l` -Converts a sequence of wide characters to a corresponding sequence of multibyte characters. A version of [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a sequence of wide characters to a corresponding sequence of multibyte characters. A version of [`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -53,35 +53,35 @@ errno_t _wcstombs_s_l( ### Parameters -*`pReturnValue`*
+*`pReturnValue`*\ The size in bytes of the converted string, including the null terminator. -*`mbstr`*
+*`mbstr`*\ The address of a buffer for the resulting converted multibyte character string. -*`sizeInBytes`*
+*`sizeInBytes`*\ The size in bytes of the *`mbstr`* buffer. -*`wcstr`*
+*`wcstr`*\ Points to the wide character string to be converted. -*`count`*
-The maximum number of bytes to store in the *`mbstr`* buffer, not including the terminating null character, or [`_TRUNCATE`](../../c-runtime-library/truncate.md). +*`count`*\ +The maximum number of bytes to store in the *`mbstr`* buffer, not including the terminating null character, or [`_TRUNCATE`](../truncate.md). -*`locale`*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful, an error code on failure. -|Error condition|Return value and **`errno`**| -|---------------------|------------------------------| -|*`mbstr`* is **`NULL`** and *`sizeInBytes`* > 0|**`EINVAL`**| -|*`wcstr`* is **`NULL`**|**`EINVAL`**| -|The destination buffer is too small to contain the converted string (unless *`count`* is **`_TRUNCATE`**; see Remarks below)|**`ERANGE`**| +| Error condition | Return value and `errno` | +|---|---| +| *`mbstr`* is `NULL` and *`sizeInBytes`* > 0 | `EINVAL` | +| *`wcstr`* is `NULL` | `EINVAL` | +| The destination buffer is too small to contain the converted string (unless *`count`* is `_TRUNCATE`; see Remarks below) | `ERANGE` | -If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns an error code and sets **`errno`** as indicated in the table. +If any of these conditions occurs, the invalid parameter exception is invoked as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns an error code and sets `errno` as indicated in the table. ## Remarks @@ -89,36 +89,36 @@ The **`wcstombs_s`** function converts a string of wide characters pointed to by - A null wide character is encountered -- A wide character that cannot be converted is encountered +- A wide character that can't be converted is encountered - The number of bytes stored in the *`mbstr`* buffer equals *`count`*. -The destination string is always null-terminated (even in the case of an error). +The destination string is always null-terminated (even if there's an error). -If *`count`* is the special value [`_TRUNCATE`](../../c-runtime-library/truncate.md), then **`wcstombs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. If the string is truncated, the return value is **`STRUNCATE`**, and the conversion is considered successful. +If *`count`* is the special value [`_TRUNCATE`](../truncate.md), then **`wcstombs_s`** converts as much of the string as will fit into the destination buffer, while still leaving room for a null terminator. If the string is truncated, the return value is `STRUNCATE`, and the conversion is considered successful. -If **`wcstombs_s`** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *`*pReturnValue`* (provided *`pReturnValue`* is not **`NULL`**). This occurs even if the *`mbstr`* argument is **`NULL`** and provides a way to determine the required buffer size. Note that if *`mbstr`* is **`NULL`**, *`count`* is ignored. +If **`wcstombs_s`** successfully converts the source string, it puts the size in bytes of the converted string, including the null terminator, into *`*pReturnValue`* (provided *`pReturnValue`* isn't `NULL`). The size is calculated even if the *`mbstr`* argument is `NULL`; it provides a way to determine the required buffer size. If *`mbstr`* is `NULL`, *`count`* is ignored. -If **`wcstombs_s`** encounters a wide character it cannot convert to a multibyte character, it puts 0 in *`*ReturnValue`*, sets the destination buffer to an empty string, sets **`errno`** to **`EILSEQ`**, and returns **`EILSEQ`**. +If **`wcstombs_s`** encounters a wide character it can't convert to a multibyte character, it puts 0 in *`*ReturnValue`*, sets the destination buffer to an empty string, sets `errno` to `EILSEQ`, and returns `EILSEQ`. If the sequences pointed to by *`wcstr`* and *`mbstr`* overlap, the behavior of **`wcstombs_s`** is undefined. > [!IMPORTANT] > Ensure that *`wcstr`* and *`mbstr`* do not overlap, and that *`count`* correctly reflects the number of wide characters to convert. -**`wcstombs_s`** uses the current locale for any locale-dependent behavior; **`_wcstombs_s_l`** is identical to **`wcstombs`** except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`wcstombs_s`** uses the current locale for any locale-dependent behavior; **`_wcstombs_s_l`** is identical to **`wcstombs`** except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, using these functions is simplified by template overloads; the overloads can infer buffer length automatically (eliminating the need to specify a size argument) and they can automatically replace older, non-secure functions with their newer, secure counterparts. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`wcstombs_s`**|``| +| Routine | Required header | Required library | +|---|---|---| +| **`wcstombs_s`** | `` | ucrt.lib (the Universal C Runtime Library) | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -168,10 +168,10 @@ Convert wide-character string: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)
-[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)
-[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)
-[`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md)
-[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md index 6aadb68c5e4..cd259d21027 100644 --- a/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md +++ b/docs/c-runtime-library/reference/wcstombs-wcstombs-l.md @@ -3,10 +3,10 @@ description: "Learn more about: wcstombs, _wcstombs_l" title: "wcstombs, _wcstombs_l" ms.date: "4/2/2020" api_name: ["wcstombs", "_wcstombs_l", "_o__wcstombs_l", "_o_wcstombs"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wcstombs", "_wcstombs_l"] +f1_keywords: ["STDLIB/wcstombs", "STDLIB/_wcstombs_l", "wcstombs", "_wcstombs_l"] helpviewer_keywords: ["_wcstombs_l function", "wcstombs function", "string conversion, wide characters", "wide characters, converting", "wcstombs_l function", "characters, converting", "string conversion, multibyte character strings"] --- # `wcstombs`, `_wcstombs_l` @@ -56,34 +56,36 @@ The maximum number of bytes that can be stored in the multibyte output string. *`locale`*\ The locale to use. -## Return Value +## Return value -If **`wcstombs`** successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating `NULL` (if any). If the *`mbstr`* argument is **`NULL`**, **`wcstombs`** returns the required size in bytes of the destination string. If **`wcstombs`** encounters a wide character it can’t convert to a multibyte character, it returns -1 cast to type **`size_t`** and sets **`errno`** to **`EILSEQ`**. +If **`wcstombs`** successfully converts the multibyte string, it returns the number of bytes written into the multibyte output string, excluding the terminating `NULL` (if any). If the *`mbstr`* argument is `NULL`, **`wcstombs`** returns the required size in bytes of the destination string. If **`wcstombs`** encounters a wide character it can't convert to a multibyte character, it returns -1 cast to type **`size_t`** and sets `errno` to `EILSEQ`. ## Remarks -The **`wcstombs`** function converts the wide-character string pointed to by *`wcstr`* to the corresponding multibyte characters and stores the results in the *`mbstr`* array. The *`count`* parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of *`mbstr`*). In general, it isn't known how many bytes will be required when converting a wide-character string. Some wide characters will require only one byte in the output string; others require two. If there are two bytes in the multibyte output string for every wide character in the input string (including the wide character `NULL`), the result is guaranteed to fit. +The **`wcstombs`** function converts the wide-character string pointed to by *`wcstr`* to the corresponding multibyte characters and stores the results in the *`mbstr`* array. The *`count`* parameter indicates the maximum number of bytes that can be stored in the multibyte output string (that is, the size of *`mbstr`*). In general, it isn't known how many bytes will be required when converting a wide-character string. Some wide characters will require only a single byte in the output string; others require 2 bytes. If there are 2 bytes in the multibyte output string for every wide character in the input string (including the wide character `NULL`), the result is guaranteed to fit. + +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. +If the *`mbstr`* argument is `NULL`, **`wcstombs`** returns the required size in bytes of the destination string. -**`wcstombs`** validates its parameters. If *`wcstr`* is **`NULL`**, or if *`count`* is greater than **`INT_MAX`**, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function sets **`errno`** to **`EINVAL`** and returns -1. +**`wcstombs`** validates its parameters. If *`wcstr`* is `NULL`, or if *`count`* is greater than `INT_MAX`, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function sets `errno` to `EINVAL` and returns -1. -**`wcstombs`** uses the current locale for any locale-dependent behavior; **`_wcstombs_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`wcstombs`** uses the current locale for any locale-dependent behavior; **`_wcstombs_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure Template Overloads](../../c-runtime-library/secure-template-overloads.md). +In C++, these functions have template overloads that invoke the newer, secure counterparts of these functions. For more information, see [Secure template overloads](../secure-template-overloads.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`wcstombs`**|``| -|**`_wcstombs_l`**|``| +| Routine | Required header | +|---|---| +| **`wcstombs`** | `` | +| **`_wcstombs_l`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -129,8 +131,8 @@ Convert wide-character string: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)\ -[Locale](../../c-runtime-library/locale.md)\ +[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ [`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ [`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ [`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ diff --git a/docs/c-runtime-library/reference/wctob.md b/docs/c-runtime-library/reference/wctob.md index 72be225e5c7..70b552de85b 100644 --- a/docs/c-runtime-library/reference/wctob.md +++ b/docs/c-runtime-library/reference/wctob.md @@ -3,14 +3,14 @@ description: "Learn more about: wctob" title: "wctob" ms.date: "4/2/2020" api_name: ["wctob", "_o_wctob"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctob"] +f1_keywords: ["WCHAR/wctob", "wctob"] helpviewer_keywords: ["wide characters, converting", "wctob function", "characters, converting"] ms.assetid: 46aec98b-c2f2-4e9d-9d89-7db99ba8a9a6 --- -# wctob +# `wctob` Determines if a wide character corresponds to a multibyte character and returns its multibyte character representation. @@ -24,32 +24,32 @@ int wctob( ### Parameters -*wchar*
+*`wchar`*\ Value to translate. -## Return Value +## Return value -If **wctob** successfully converts a wide character, it returns its multibyte character representation, only if the multibyte character is exactly one byte long. If **wctob** encounters a wide character it cannot convert to a multibyte character or the multibyte character is not exactly one byte long, it returns a -1. +If **`wctob`** successfully converts a wide character, it returns its multibyte character representation only if the multibyte character is a single byte long. If **`wctob`** encounters a wide character it can't convert to a multibyte character, or if the multibyte character isn't a single byte long, it returns -1. ## Remarks -The **wctob** function converts a wide character contained in *wchar* to the corresponding multibyte character passed by the return **`int`** value, if the multibyte character is exactly one byte long. +The **`wctob`** function converts a wide character contained in *`wchar`* to the corresponding multibyte character passed by the **`int`** return value, if the multibyte character is a single byte long. -If **wctob** was unsuccessful and no corresponding multibyte character was found, the function sets **errno** to **EILSEQ** and returns -1. +If **`wctob`** was unsuccessful and no corresponding multibyte character was found, the function sets `errno` to `EILSEQ` and returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wctob**|\| +| Routine | Required header | +|---|---| +| **`wctob`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program illustrates the behavior of the **wcstombs** function. +This program illustrates the behavior of the `wctob` function. ```C // crt_wctob.c @@ -83,10 +83,10 @@ Determined the corresponding multibyte character to be "A". ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wctomb, _wctomb_l](wctomb-wctomb-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md b/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md index 943cd74ed2b..5158493a592 100644 --- a/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md +++ b/docs/c-runtime-library/reference/wctomb-s-wctomb-s-l.md @@ -3,16 +3,16 @@ description: "Learn more about: wctomb_s, _wctomb_s_l" title: "wctomb_s, _wctomb_s_l" ms.date: "4/2/2020" api_name: ["_wctomb_s_l", "wctomb_s", "_o__wctomb_s_l", "_o_wctomb_s"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctomb_s", "_wctomb_s_l"] +f1_keywords: ["STDLIB/wctomb_s", "STDLIB/_wctomb_s_l", "wctomb_s", "_wctomb_s_l"] helpviewer_keywords: ["wctomb_s function", "wctomb_s_l function", "string conversion, wide characters", "wide characters, converting", "_wctomb_s_l function", "characters, converting", "string conversion, multibyte character strings"] ms.assetid: 7e94a888-deed-4dbd-b5e9-d4a0455538b8 --- -# wctomb_s, _wctomb_s_l +# `wctomb_s`, `_wctomb_s_l` -Converts a wide character to the corresponding multibyte character. A version of [wctomb, _wctomb_l](wctomb-wctomb-l.md) with security enhancements as described in [Security Features in the CRT](../../c-runtime-library/security-features-in-the-crt.md). +Converts a wide character to the corresponding multibyte character. A version of [`wctomb`, `_wctomb_l`](wctomb-wctomb-l.md) with security enhancements as described in [Security features in the CRT](../security-features-in-the-crt.md). ## Syntax @@ -34,57 +34,59 @@ errno_t _wctomb_s_l( ### Parameters -*pRetValue*
+*`pRetValue`*\ The number of bytes, or a code indicating the result. -*mbchar*
+*`mbchar`*\ The address of a multibyte character. -*sizeInBytes*
-Size of the buffer *mbchar*. +*`sizeInBytes`*\ +Size of the buffer *`mbchar`*. -*wchar*
-A wide character. +*`wchar`*\ +The wide character to convert. -*locale*
+*`locale`*\ The locale to use. -## Return Value +## Return value Zero if successful, an error code on failure. Error Conditions -|*mbchar*|*sizeInBytes*|Return value|*pRetValue*| -|--------------|-------------------|------------------|-----------------| -|**NULL**|>0|**EINVAL**|not modified| -|any|>**INT_MAX**|**EINVAL**|not modified| -|any|too small|**EINVAL**|not modified| +| *`mbchar`* | *`sizeInBytes`* | Return value | *`pRetValue`* | +|---|---|---|---| +| `NULL` | >0 | `EINVAL` | not modified | +| any | >`INT_MAX` | `EINVAL` | not modified | +| any | too small | `EINVAL` | not modified | + +If any of the above error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `wctomb` returns `EINVAL` and sets `errno` to `EINVAL`. -If any of the above error conditions occurs, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **wctomb** returns **EINVAL** and sets **errno** to **EINVAL**. +The return value [`EILSEQ`](../errno-constants.md) indicates that the value passed via the parameter `wchar` is not a valid wide character. ## Remarks -The **wctomb_s** function converts its *wchar* argument to the corresponding multibyte character and stores the result at *mbchar*. You can call the function from any point in any program. +The **`wctomb_s`** function converts its *`wchar`* argument to the corresponding multibyte character and stores the result at *`mbchar`*. You can call the function from any point in any program. -If **wctomb_s** converts the wide character to a multibyte character, it puts the number of bytes (which is never greater than **MB_CUR_MAX**) in the wide character into the integer pointed to by *pRetValue*. If *wchar* is the wide-character null character (L'\0'), **wctomb_s** fills *pRetValue* with 1. If the target pointer *mbchar* is **NULL**, **wctomb_s** puts 0 in *pRetValue*. If the conversion is not possible in the current locale, **wctomb_s** puts -1 in *pRetValue*. +If **`wctomb_s`** converts the wide character to a multibyte character, it puts the number of bytes (which is never greater than `MB_CUR_MAX`) in the wide character into the integer pointed to by *`pRetValue`*. If *`wchar`* is the wide-character null character (L'\0'), **`wctomb_s`** fills *`pRetValue`* with 1. If the target pointer *`mbchar`* is `NULL`, **`wctomb_s`** puts 0 in *`pRetValue`*. If the conversion isn't possible in the current locale, **`wctomb_s`** puts -1 in *`pRetValue`*. -**wctomb_s** uses the current locale for locale-dependent information; **_wctomb_s_l** is identical except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +**`wctomb_s`** uses the current locale for locale-dependent information; **`_wctomb_s_l`** is identical except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wctomb_s**|\| -|**_wctomb_s_l**|\| +| Routine | Required header | +|---|---| +| **`wctomb_s`** | \ | +| **`_wctomb_s_l`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example -This program illustrates the behavior of the **wctomb** function. +This program illustrates the behavior of the **`wctomb_s`** function. ```cpp // crt_wctomb_s.cpp @@ -112,10 +114,10 @@ Convert a wide character: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wctomb-wctomb-l.md b/docs/c-runtime-library/reference/wctomb-wctomb-l.md index ff7dea146e0..003b081d840 100644 --- a/docs/c-runtime-library/reference/wctomb-wctomb-l.md +++ b/docs/c-runtime-library/reference/wctomb-wctomb-l.md @@ -3,16 +3,16 @@ description: "Learn more about: wctomb, _wctomb_l" title: "wctomb, _wctomb_l" ms.date: "4/2/2020" api_name: ["_wctomb_l", "wctomb", "_o__wctomb_l", "_o_wctomb"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll", "ntoskrnl.exe"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctomb"] +f1_keywords: ["STDLIB/wctomb", "STDLIB/_wctomb_l", "wctomb", "_wctomb_l"] helpviewer_keywords: ["string conversion, wide characters", "wide characters, converting", "_wctomb_l function", "wctomb function", "wctomb_l function", "characters, converting", "string conversion, multibyte character strings"] ms.assetid: 4a543f0e-5516-4d81-8ff2-3c5206f02ed5 --- -# wctomb, _wctomb_l +# `wctomb`, `_wctomb_l` -Convert a wide character to the corresponding multibyte character. More secure versions of these functions are available; see [wctomb_s, _wctomb_s_l](wctomb-s-wctomb-s-l.md). +Convert a wide character to the corresponding multibyte character. More secure versions of these functions are available; see [`wctomb_s`, `_wctomb_s_l`](wctomb-s-wctomb-s-l.md). ## Syntax @@ -30,31 +30,31 @@ int _wctomb_l( ### Parameters -*mbchar*
+*`mbchar`*\ The address of a multibyte character. -*wchar*
+*`wchar`*\ A wide character. -## Return Value +## Return value -If **wctomb** converts the wide character to a multibyte character, it returns the number of bytes (which is never greater than **MB_CUR_MAX**) in the wide character. If *wchar* is the wide-character null character (L'\0'), **wctomb** returns 1. If the target pointer *mbchar* is **NULL**, **wctomb** returns 0. If the conversion is not possible in the current locale, **wctomb** returns -1 and **errno** is set to **EILSEQ**. +If **`wctomb`** converts the wide character to a multibyte character, it returns the number of bytes (which is never greater than `MB_CUR_MAX`) in the wide character. If *`wchar`* is the wide-character null character (L'\0'), **`wctomb`** returns 1. If the target pointer *`mbchar`* is `NULL`, **`wctomb`** returns 0. If the conversion isn't possible in the current locale, **`wctomb`** returns -1 and `errno` is set to `EILSEQ`. ## Remarks -The **wctomb** function converts its *wchar* argument to the corresponding multibyte character and stores the result at *mbchar*. You can call the function from any point in any program. **wctomb** uses the current locale for any locale-dependent behavior; **_wctomb_l** is identical to **wctomb** except that it uses the locale passed in instead. For more information, see [Locale](../../c-runtime-library/locale.md). +The **`wctomb`** function converts its *`wchar`* argument to the corresponding multibyte character and stores the result at *`mbchar`*. You can call the function from any point in any program. **`wctomb`** uses the current locale for any locale-dependent behavior; **`_wctomb_l`** is identical to **`wctomb`** except that it uses the locale passed in instead. For more information, see [Locale](../locale.md). -**wctomb** validates its parameters. If *mbchar* is **NULL**, the invalid parameter handler is invoked, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, **errno** is set to **EINVAL** and the function returns -1. +**`wctomb`** validates its parameters. If *`mbchar`* is `NULL`, the invalid parameter handler is invoked, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, `errno` is set to `EINVAL` and the function returns -1. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**wctomb**|\| +| Routine | Required header | +|---|---| +| **`wctomb`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -88,10 +88,10 @@ Convert a wide character: ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[Locale](../../c-runtime-library/locale.md)
-[_mbclen, mblen, _mblen_l](mbclen-mblen-mblen-l.md)
-[mbstowcs, _mbstowcs_l](mbstowcs-mbstowcs-l.md)
-[mbtowc, _mbtowc_l](mbtowc-mbtowc-l.md)
-[wcstombs, _wcstombs_l](wcstombs-wcstombs-l.md)
-[WideCharToMultiByte](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte)
+[Data conversion](../data-conversion.md)\ +[Locale](../locale.md)\ +[`_mbclen`, `mblen`, `_mblen_l`](mbclen-mblen-mblen-l.md)\ +[`mbstowcs`, `_mbstowcs_l`](mbstowcs-mbstowcs-l.md)\ +[`mbtowc`, `_mbtowc_l`](mbtowc-mbtowc-l.md)\ +[`wcstombs`, `_wcstombs_l`](wcstombs-wcstombs-l.md)\ +[`WideCharToMultiByte`](/windows/win32/api/stringapiset/nf-stringapiset-widechartomultibyte) diff --git a/docs/c-runtime-library/reference/wctrans.md b/docs/c-runtime-library/reference/wctrans.md index 47bcc798608..7bcac2489ae 100644 --- a/docs/c-runtime-library/reference/wctrans.md +++ b/docs/c-runtime-library/reference/wctrans.md @@ -6,11 +6,11 @@ api_name: ["wctrans"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-convert-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctrans"] +f1_keywords: ["WCTYPE/wctrans", "wctrans"] helpviewer_keywords: ["character codes, wctrans", "characters, codes", "characters, converting", "wctrans function"] ms.assetid: 215404bf-6d60-489c-9ae9-880e6b586162 --- -# wctrans +# `wctrans` Determines a mapping from one set of character codes to another. @@ -24,31 +24,31 @@ wctrans_t wctrans( ### Parameters -*property*
+*`property`*\ A string that specifies one of the valid transformations. -## Return Value +## Return value -If the **LC_CTYPE** category of the current locale does not define a mapping whose name matches the property string *property*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [towctrans](towctrans.md). +If the `LC_CTYPE` category of the current locale doesn't define a mapping whose name matches the property string *`property`*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [`towctrans`](towctrans.md). ## Remarks This function determines a mapping from one set of character codes to another. -The following pairs of calls have the same behavior in all locales, but it is possible to define additional mappings even in the "C" locale: +The following pairs of calls have the same behavior in all locales, but it's possible to define more mappings even in the "C" locale: -|Function|Same As| -|--------------|-------------| -|tolower(c)|towctrans(c, wctrans("towlower"))| -|towupper(c)|towctrans(c, wctrans("toupper"))| +| Function | Same As | +|---|---| +| `tolower(c)` | `towctrans(c, wctrans("towlower"))` | +| `towupper(c)` | `towctrans(c, wctrans("toupper"))` | ## Requirements -|Routine|Required Header| -|-------------|---------------------| -|**wctrans**|\| +| Routine | Required Header | +|---|---| +| **`wctrans`** | \ | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -88,5 +88,5 @@ int main() ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)
-[setlocale, _wsetlocale](setlocale-wsetlocale.md)
+[Data conversion](../data-conversion.md)\ +[`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/reference/wctype.md b/docs/c-runtime-library/reference/wctype.md index 43bdf52c273..123b547d78a 100644 --- a/docs/c-runtime-library/reference/wctype.md +++ b/docs/c-runtime-library/reference/wctype.md @@ -6,7 +6,7 @@ api_name: ["wctype"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-string-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["wctype"] +f1_keywords: ["WCTYPE/wctype", "wctype"] helpviewer_keywords: ["wctype function", "wide characters"] --- # `wctype` @@ -26,37 +26,37 @@ wctype_t wctype( *`property`*\ Property string. -## Return Value +## Return value -If the **`LC_CTYPE`** category of the current locale doesn't define a classification rule whose name matches the property string *`property`*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [`towctrans`](towctrans.md). +If the `LC_CTYPE` category of the current locale doesn't define a classification rule whose name matches the property string *`property`*, the function returns zero. Otherwise, it returns a nonzero value suitable for use as the second argument to a subsequent call to [`towctrans`](towctrans.md). ## Remarks -The function determines a classification rule for wide-character codes. The following pairs of calls have the same behavior in all locales (but an implementation can define additional classification rules even in the "C" locale): - -|Function|Same as| -|--------------|-------------| -|`iswalnum(c)`|`iswctype(c, wctype( "alnum" ))`| -|`iswalpha(c)`|`iswctype(c, wctype( "alpha" ))`| -|`iswcntrl(c)`|`iswctype(c, wctype( "cntrl" ))`| -|`iswdigit(c)`|`iswctype(c, wctype( "digit" ))`| -|`iswgraph(c)`|`iswctype(c, wctype( "graph" ))`| -|`iswlower(c)`|`iswctype(c, wctype( "lower" ))`| -|`iswprint(c)`|`iswctype(c, wctype( "print" ))`| -|`iswpunct(c)`|`iswctype(c, wctype( "punct" ))`| -|`iswspace(c)`|`iswctype(c, wctype( "space" ))`| -|`iswupper(c)`|`iswctype(c, wctype( "upper" ))`| -|`iswxdigit(c)`|`iswctype(c, wctype( "xdigit" ))`| +The function determines a classification rule for wide-character codes. The following pairs of calls have the same behavior in all locales (but an implementation can define more classification rules even in the "C" locale): + +| Function | Same as | +|---|---| +| `iswalnum(c)` | `iswctype(c, wctype( "alnum" ))` | +| `iswalpha(c)` | `iswctype(c, wctype( "alpha" ))` | +| `iswcntrl(c)` | `iswctype(c, wctype( "cntrl" ))` | +| `iswdigit(c)` | `iswctype(c, wctype( "digit" ))` | +| `iswgraph(c)` | `iswctype(c, wctype( "graph" ))` | +| `iswlower(c)` | `iswctype(c, wctype( "lower" ))` | +| `iswprint(c)` | `iswctype(c, wctype( "print" ))` | +| `iswpunct(c)` | `iswctype(c, wctype( "punct" ))` | +| `iswspace(c)` | `iswctype(c, wctype( "space" ))` | +| `iswupper(c)` | `iswctype(c, wctype( "upper" ))` | +| `iswxdigit(c)` | `iswctype(c, wctype( "xdigit" ))` | ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`wctype`|``| +| Routine | Required header | +|---|---| +| **`wctype`** | `` | -For more compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## See also -[Data Conversion](../../c-runtime-library/data-conversion.md)\ +[Data conversion](../data-conversion.md)\ [`setlocale`, `_wsetlocale`](setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/reference/write.md b/docs/c-runtime-library/reference/write.md index 5e2f2a95f37..f21ee87c4dc 100644 --- a/docs/c-runtime-library/reference/write.md +++ b/docs/c-runtime-library/reference/write.md @@ -3,10 +3,10 @@ description: "Learn more about: _write" title: "_write" ms.date: "4/2/2020" api_name: ["_write", "_o__write"] -api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll", "api-ms-win-crt-stdio-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_write"] +f1_keywords: ["CORECRT_IO/_write", "_write"] helpviewer_keywords: ["_write function", "write function", "files [C++], writing to"] --- # `_write` @@ -34,31 +34,31 @@ Data to be written. *`count`*\ Number of bytes. -## Return Value +## Return value -If successful, **`_write`** returns the number of bytes written. If the actual space remaining on the disk is less than the size of the buffer the function is trying to write to the disk, **`_write`** fails and doesn't flush any of the buffer's contents to the disk. A return value of -1 indicates an error. If invalid parameters are passed, this function invokes the invalid parameter handler, as described in [Parameter Validation](../../c-runtime-library/parameter-validation.md). If execution is allowed to continue, the function returns -1 and **`errno`** is set to one of three values: **`EBADF`**, which means the file descriptor is invalid or the file isn't opened for writing; **`ENOSPC`**, which means there isn't enough space left on the device for the operation; or **`EINVAL`**, which means that *`buffer`* was a null pointer or that an odd *`count`* of bytes was passed to be written to a file in Unicode mode. +If successful, **`_write`** returns the number of bytes written. If the actual space remaining on the disk is less than the size of the buffer the function is trying to write to the disk, **`_write`** fails and doesn't flush any of the buffer's contents to the disk. A return value of -1 indicates an error. If invalid parameters are passed, this function invokes the invalid parameter handler, as described in [Parameter validation](../parameter-validation.md). If execution is allowed to continue, the function returns -1 and `errno` is set to one of three values: `EBADF`, which means the file descriptor is invalid or the file isn't opened for writing; `ENOSPC`, which means there isn't enough space left on the device for the operation; or `EINVAL`, which means that *`buffer`* was a null pointer, or that an odd *`count`* of bytes was passed in Unicode mode. -For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../../c-runtime-library/errno-doserrno-sys-errlist-and-sys-nerr.md). +For more information about these and other return codes, see [`errno`, `_doserrno`, `_sys_errlist`, and `_sys_nerr`](../errno-doserrno-sys-errlist-and-sys-nerr.md). If the file is opened in text mode, each line feed character is replaced with a carriage return-line feed pair in the output. The replacement doesn't affect the return value. -When the file is opened in Unicode translation mode—for example, if *`fd`* is opened by using **`_open`** or **`_sopen`** and a mode parameter that includes **`_O_WTEXT`**, **`_O_U16TEXT`**, or **`_O_U8TEXT`**, or if it's opened by using **`fopen`** and a mode parameter that includes **`ccs=UNICODE`**, **`ccs=UTF-16LE`**, or **`ccs=UTF-8`**, or if the mode is changed to a Unicode translation mode by using **`_setmode`**—*`buffer`* is interpreted as a pointer to an array of **`wchar_t`** that contains **`UTF-16`** data. An attempt to write an odd number of bytes in this mode causes a parameter validation error. +When the file is opened in Unicode translation mode—for example, if *`fd`* is opened by using **`_open`** or **`_sopen`** and a mode parameter that includes `_O_WTEXT`, `_O_U16TEXT`, or `_O_U8TEXT`, or if it's opened by using **`fopen`** and a mode parameter that includes **`ccs=UNICODE`**, **`ccs=UTF-16LE`**, or **`ccs=UTF-8`**, or if the mode is changed to a Unicode translation mode by using **`_setmode`**—*`buffer`* is interpreted as a pointer to an array of **`wchar_t`** that contains **`UTF-16`** data. An attempt to write an odd number of bytes in this mode causes a parameter validation error. ## Remarks The **`_write`** function writes *`count`* bytes from *`buffer`* into the file associated with *`fd`*. The write operation begins at the current position of the file pointer (if any) associated with the given file. If the file is open for appending, the operation begins at the current end of the file. After the write operation, the file pointer is increased by the number of bytes written. -When writing to files opened in text mode, **`_write`** treats a CTRL+Z character as the logical end of file. When writing to a device, **`_write`** treats a CTRL+Z character in the buffer as an output terminator. +When it writes to files opened in text mode, **`_write`** treats a CTRL+Z character as the logical end of file. When it writes to a device, **`_write`** treats a CTRL+Z character in the buffer as an output terminator. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](../global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](../global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|**`_write`**|``| +| Routine | Required header | +|---|---| +| **`_write`** | `` | -For additional compatibility information, see [Compatibility](../../c-runtime-library/compatibility.md). +For more compatibility information, see [Compatibility](../compatibility.md). ## Example @@ -120,7 +120,7 @@ Wrote 36 bytes to file. ## See also -[Low-Level I/O](../../c-runtime-library/low-level-i-o.md)\ +[Low-level I/O](../low-level-i-o.md)\ [`fwrite`](fwrite.md)\ [`_open`, `_wopen`](open-wopen.md)\ [`_read`](read.md)\ diff --git a/docs/c-runtime-library/reference/xor-eq.md b/docs/c-runtime-library/reference/xor-eq.md index 1c53b39e114..4a9898a2c20 100644 --- a/docs/c-runtime-library/reference/xor-eq.md +++ b/docs/c-runtime-library/reference/xor-eq.md @@ -5,24 +5,23 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std.xor_eq", "xor_eq", "std::xor_eq"] +f1_keywords: ["std.xor_eq", "xor_eq", "std::xor_eq", "ISO646/xor_eq"] helpviewer_keywords: ["xor_eq function"] ms.assetid: eca4b6b4-b77a-4d44-a09a-5a7e69fdb56c --- -# xor_eq +# `xor_eq` -An alternative to the ^= operator. +An alternative to the **`^=`** operator. ## Syntax ```C - #define xor_eq ^= ``` ## Remarks -The macro yields the operator ^=. +The macro yields the operator **`^=`**. ## Example diff --git a/docs/c-runtime-library/reference/xor.md b/docs/c-runtime-library/reference/xor.md index 9a84a5b2af7..1bc78efb8df 100644 --- a/docs/c-runtime-library/reference/xor.md +++ b/docs/c-runtime-library/reference/xor.md @@ -5,24 +5,23 @@ ms.date: "11/04/2016" api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["std::xor", "std.xor"] +f1_keywords: ["std::xor", "std.xor", "ISO646/xor"] helpviewer_keywords: ["xor function"] ms.assetid: 0fe9554b-d87b-4487-92ed-366c6dc21df2 --- -# xor +# `xor` -An alternative to the ^ operator. +An alternative to the **`^`** operator. ## Syntax ```C - #define xor ^ ``` ## Remarks -The macro yields the operator ^. +The macro yields the operator **`^`**. ## Example @@ -40,7 +39,7 @@ int main( ) result= a ^ b; cout << result << endl; - result= a xor_eq b; + result= a xor b; cout << result << endl; } ``` diff --git a/docs/c-runtime-library/reference/y0-y1-yn.md b/docs/c-runtime-library/reference/y0-y1-yn.md index 77991781eeb..6b3d3111525 100644 --- a/docs/c-runtime-library/reference/y0-y1-yn.md +++ b/docs/c-runtime-library/reference/y0-y1-yn.md @@ -6,12 +6,12 @@ api_name: ["y1", "yn", "y0"] api_location: ["msvcrt.dll", "msvcr80.dll", "msvcr90.dll", "msvcr100.dll", "msvcr100_clr0400.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr120_clr0400.dll", "ucrtbase.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["yn", "y1", "y0"] +f1_keywords: ["CORECRT_MATH/yn", "CORECRT_MATH/y1", "CORECRT_MATH/y0", "yn", "y1", "y0"] helpviewer_keywords: ["y0 function", "y1 function", "yn function"] ms.assetid: e14215f3-53d4-4ae8-816e-4c1ec2019316 --- -# y0, y1, yn +# `y0`, `y1`, `yn` -The Microsoft-implemented POSIX function names `y0`, `y1`, and `yn` are deprecated aliases for the [_y0, _y1, and _yn](bessel-functions-j0-j1-jn-y0-y1-yn.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. +The Microsoft-implemented POSIX function names `y0`, `y1`, and `yn` are deprecated aliases for the [`_y0`, `_y1`, and `_yn`](bessel-functions-j0-j1-jn-y0-y1-yn.md) functions. By default, they generate [Compiler warning (level 3) C4996](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). The names are deprecated because they don't follow the Standard C rules for implementation-specific names. However, the functions are still supported. -We recommend you use [_y0, _y1, and _yn](bessel-functions-j0-j1-jn-y0-y1-yn.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). +We recommend you use [`_y0`, `_y1`, and `_yn`](bessel-functions-j0-j1-jn-y0-y1-yn.md) instead. Or, you can continue to use these function names, and disable the warning. For more information, see [Turn off the warning](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#turn-off-the-warning) and [POSIX function names](../../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md#posix-function-names). diff --git a/docs/c-runtime-library/required-and-optional-header-files.md b/docs/c-runtime-library/required-and-optional-header-files.md index d0abc8a3196..13fb797a279 100644 --- a/docs/c-runtime-library/required-and-optional-header-files.md +++ b/docs/c-runtime-library/required-and-optional-header-files.md @@ -2,23 +2,23 @@ title: "Required and Optional Header Files" description: "When to use required versus optional header files from the Microsoft C runtime library." ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: ["c.headers"] helpviewer_keywords: ["include files, required in run time", "header files, required in run time"] ms.assetid: f64d0bf5-e2c3-4b42-97d0-443b3d901d9f --- -# Required and Optional Header Files +# Required and optional header files -The description of each run-time routine includes a list of the required and optional include, or header (.H), files for that routine. Required header files need to be included to obtain the function declaration for the routine or a definition used by another routine called internally. Optional header files are usually included to take advantage of predefined constants, type definitions, or inline macros. The following table lists some examples of optional header file contents: +The description of each run-time routine includes a list of the required and optional include, or header (.H), files for that routine. Required header files need to be included to obtain the function declaration for the routine or a definition used by another routine called internally. Optional header files are often included to take advantage of predefined constants, type definitions, or inline macros. The following table lists some examples of optional header file contents: -|Definition|Example| -|----------------|-------------| -|Macro definition|If a library routine is implemented as a macro, the macro definition may be in a header file other than the header file for the original routine. For instance, the `_toupper` macro is defined in the header file CTYPE.H, while the function `toupper` is declared in STDLIB.H.| -|Predefined Constant|Many library routines refer to constants that are defined in header files. For instance, the `_open` routine uses constants such as `_O_CREAT`, which is defined in the header file FCNTL.H.| -|Type definition|Some library routines return a structure or take a structure as an argument. For example, stream input/output routines use a structure of type `FILE`, which is defined in STDIO.H.| +| Definition | Example | +|---|---| +| Macro definition | If a library routine is implemented as a macro, the macro definition may be in a header file other than the header file for the original routine. For instance, the `_toupper` macro is defined in the header file CTYPE.H, while the function `toupper` is declared in STDLIB.H. | +| Predefined Constant | Many library routines refer to constants that are defined in header files. For instance, the `_open` routine uses constants such as `_O_CREAT`, which is defined in the header file FCNTL.H. | +| Type definition | Some library routines return a structure or take a structure as an argument. For example, stream input/output routines use a structure of type `FILE`, which is defined in STDIO.H. | -The run-time library header files provide function declarations in the ANSI/ISO C standard recommended style. The compiler performs type checking on any routine reference that occurs after its associated function declaration. Function declarations are especially important for routines that return a value of some type other than **`int`**, which is the default. Routines that do not specify their appropriate return value in their declaration will be considered by the compiler to return an **`int`**, which can cause unexpected results. See [Type Checking](../c-runtime-library/type-checking-crt.md) for more information. +The run-time library header files provide function declarations in the ANSI/ISO C standard recommended style. The compiler performs type checking on any routine reference that occurs after its associated function declaration. Function declarations are especially important for routines that return a value of some type other than **`int`**, which is the default. Routines that don't specify their appropriate return value in their declaration will be considered by the compiler to return an **`int`**, which can cause unexpected results. For more information, see [Type checking](./type-checking-crt.md). ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/robustness.md b/docs/c-runtime-library/robustness.md index b6547f231f2..0ea11d6d2f0 100644 --- a/docs/c-runtime-library/robustness.md +++ b/docs/c-runtime-library/robustness.md @@ -9,16 +9,16 @@ ms.assetid: 7f1a87f8-eff9-4b76-ae9b-d133d3de6adf Use the following C run-time library functions to improve the robustness of your program. -## Run-Time Robustness Functions +## Run-time robustness functions -|Function|Use| -|--------------|---------| -|[_set_new_handler](../c-runtime-library/reference/set-new-handler.md)|Transfers control to your error-handling mechanism if the **`new`** operator fails to allocate memory.| -|[_set_se_translator](../c-runtime-library/reference/set-se-translator.md)|Handles Win32 exceptions (C structured exceptions) as C++ typed exceptions.| -|[set_terminate](../c-runtime-library/reference/set-terminate-crt.md)|Installs your own termination function to be called by [terminate](../c-runtime-library/reference/terminate-crt.md).| -|[set_unexpected](../c-runtime-library/reference/set-unexpected-crt.md)|Installs your own termination function to be called by [unexpected](../c-runtime-library/reference/unexpected-crt.md).| +| Function | Use | +|---|---| +| [`_set_new_handler`](./reference/set-new-handler.md) | Transfers control to your error-handling mechanism if the **`new`** operator fails to allocate memory. | +| [`_set_se_translator`](./reference/set-se-translator.md) | Handles Win32 exceptions (C structured exceptions) as C++ typed exceptions. | +| [`set_terminate`](./reference/set-terminate-crt.md) | Installs your own termination function to be called by [`terminate`](./reference/terminate-crt.md). | +| [`set_unexpected`](./reference/set-unexpected-crt.md) | Installs your own termination function to be called by [`unexpected`](./reference/unexpected-crt.md). | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
-[SetUnhandledExceptionFilter](/windows/win32/api/errhandlingapi/nf-errhandlingapi-setunhandledexceptionfilter)
+[Universal C runtime routines by category](./run-time-routines-by-category.md)\ +[`SetUnhandledExceptionFilter`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-setunhandledexceptionfilter) diff --git a/docs/c-runtime-library/routine-mappings.md b/docs/c-runtime-library/routine-mappings.md index 1a89b74b20f..e36658b7393 100644 --- a/docs/c-runtime-library/routine-mappings.md +++ b/docs/c-runtime-library/routine-mappings.md @@ -1,261 +1,262 @@ --- -description: "Learn more about: Routine Mappings" -title: "Routine 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 +title: "Generic-text function mappings" +description: "Learn more about: Microsoft specific generic-text functions and the CRT functions they map to." +ms.date: 11/04/2016 +ms.author: twhitney +f1_keywords: ["_cgetts", "_cgetts_s", "_cputts", "_fgettc", "_fgettchar", "_fgetts", "_fputtc", "_fputtchar", "_fputts", "_ftscanf", "_ftscanf_s", "_gettc", "_gettch", "_gettchar", "_gettche", "_getts", "_getts_s", "_istalnum", "_istalpha", "_istascii", "_istcntrl", "_istdigit", "_istgraph", "_istlead", "_istleadbyte", "_istlegal", "_istlower", "_istprint", "_istpunct", "_istspace", "_istupper", "_istxdigit", "_itot", "_itot_s", "_ltot", "_ltot_s", "_puttc", "_puttch", "_puttchar", "_putts", "_sctprintf", "_sntprintf", "_sntprintf_s", "_sntscanf", "_sntscanf_s", "_stprintf", "_stprintf_s", "_stscanf", "_stscanf_s", "_taccess", "_tasctime", "_tasctime_s", "_tccmp", "_tccpy", "_tccpy_s", "_tchdir", "_tclen", "_tchmod", "_tcprintf", "_tcprintf_s", "_tcreat", "_tcscanf", "_tcscanf_s", "_tcscat", "_tcscat_s", "_tcschr", "_tcsclen", "_tcsclen_s", "_tcscmp", "_tcscoll", "_tcscpy", "_tcscpy_s", "_tcscspn", "_tcsdec", "_tcsdup", "_tcserror", "_tcserror_s", "_tcsftime", "_tcsicmp", "_tcsicoll", "_tcsinc", "_tcslen", "_tcslwr", "_tcslwr_s", "_tcsnbcnt", "_tcsncat", "_tcsncat_s", "_tcsnccat", "_tcsnccmp", "_tcsnccmp_s", "_tcsnccoll", "_tcsncmp", "_tcsnccnt", "_tcsnccpy", "_tcsncicmp", "_tcsncicoll", "_tcsncpy", "_tcsncset", "_tcsnextc", "_tcsnicmp", "_tcsnicoll", "_tcsninc", "_tcsnccnt", "_tcsnset", "_tcspbrk", "_tcsspnp", "_tcsrchr", "_tcsrev", "_tcsset", "_tcsspn", "_tcsstr", "_tcstod", "_tcstoi64", "_tcstok", "_tcstok_s", "_tcstol", "_tcstoui64", "_tcstoul", "_tcsupr", "_tcsupr_s", "_tcsxfrm", "_tctime", "_tctime_s", "_tctime32", "_tctime32_s", "_tctime64", "_tctime64_s", "_texecl", "_texecle", "_texeclp", "_texeclpe", "_texecv", "_texecve", "_texecvp", "_texecvpe", "_tfdopen", "_tfindfirst", "_tfindnext", "_tfindnext32", "_tfindnext64", "_tfindnexti64", "_tfindnexti6432", "_tfindnext32i64", "_tfopen", "_tfopen_s", "_tfreopen", "_tfreopen_s", "_tfsopen", "_tfullpath", "_tgetcwd", "_tgetdcwd", "_tgetenv", "_tgetenv_s", "_tmain", "_tmakepath", "_tmakepath_s", "_tmkdir", "_tmktemp", "_tmktemp_s", "_topen", "_topen_s", "_totlower", "_totupper", "_tperror", "_tpopen", "_tprintf", "_tprintf_s", "_tputenv", "_tremove", "_trename", "_trmdir", "_tsearchenv", "_tsearchenv_s", "_tscanf", "_tscanf_s", "_tsetlocale", "_tsopen", "_tsopen_s", "_tspawnl", "_tspawnle", "_tspawnlp", "_tspawnlpe", "_tspawnv", "_tspawnve", "_tspawnvp", "_tspawnvpe", "_tsplitpath", "_tstat", "_tstat32", "_tstati32", "_tstat64", "_tstati64", "_tstof", "_tstoi", "_tstoi64", "_tstol", "_tstrdate", "_tstrdate_s", "_tstrtime", "_tstrtime_s", "_tsystem", "_ttempnam", "_ttmpnam", "_ttmpnam_s", "_ttoi", "_ttoi64", "_ttol", "_tunlink", "_tutime", "_tutime32", "_tutime64", "_tWinMain", "_ui64tot", "_ui64tot_s", "_ultot", "_ultot_s", "_ungettc", "_ungettch", "_vftprintf", "_vftprintf_s", "_vsctprintf", "_vsctprintf_s", "_vsntprintf", "_vsntprintf_s", "_vstprintf", "_vtprintf", "_vtprintf_s"] +helpviewer_keywords: ["_tWinMain", "TCHAR.H functions, list of generic-text function mappings", "generic-text mappings", "_cgetts function", "_cgetts_s function", "_cputts function", "_fgettc function", "_fgettchar function", "_fgetts function", "_fputtc function", "_fputtchar function", "_fputts function", "_ftscanf function", "_ftscanf_s function", "_gettc function", "_gettch function", "_gettchar function", "_gettche function", "_getts function", "_getts_s function", "_istalnum function", "_istalpha function", "_istascii function", "_istcntrl function", "_istdigit function", "_istgraph function", "_istlead function", "_istleadbyte function", "_istlegal function", "_istlower function", "_istprint function", "_istpunct function", "_istspace function", "_istupper function", "_istxdigit function", "_itot function", "_itot_s function", "_ltot function", "_ltot_s function", "_puttc function", "_puttch function", "_puttchar function", "_putts function", "_sctprintf function", "_sntprintf function", "_sntprintf_s function", "_sntscanf function", "_sntscanf_s function", "_stprintf function", "_stprintf_s function", "_stscanf function", "_stscanf_s function", "_taccess function", "_tasctime function", "_tasctime_s function", "_tccmp function", "_tccpy function", "_tccpy_s function", "_tchdir function", "_tclen function", "_tchmod function", "_tcprintf function", "_tcprintf_s function", "_tcreat function", "_tcscanf function", "_tcscanf_s function", "_tcscat function", "_tcscat_s function", "_tcschr function", "_tcsclen function", "_tcsclen_s function", "_tcscmp function", "_tcscoll function", "_tcscpy function", "_tcscpy_s function", "_tcscspn function", "_tcsdec function", "_tcsdup function", "_tcserror function", "_tcserror_s function", "_tcsftime function", "_tcsicmp function", "_tcsicoll function", "_tcsinc function", "_tcslen function", "_tcslwr function", "_tcslwr_s function", "_tcsnbcnt function", "_tcsncat function", "_tcsncat_s function", "_tcsnccat function", "_tcsnccmp function", "_tcsnccmp_s function", "_tcsnccoll function", "_tcsncmp function", "_tcsnccnt function", "_tcsnccpy function", "_tcsncicmp function", "_tcsncicoll function", "_tcsncpy function", "_tcsncset function", "_tcsnextc function", "_tcsnicmp function", "_tcsnicoll function", "_tcsninc function", "_tcsnccnt function", "_tcsnset function", "_tcspbrk function", "_tcsspnp function", "_tcsrchr function", "_tcsrev function", "_tcsset function", "_tcsspn function", "_tcsstr function", "_tcstod function", "_tcstoi64 function", "_tcstok function", "_tcstok_s function", "_tcstol function", "_tcstoui64 function", "_tcstoul function", "_tcsupr function", "_tcsupr_s function", "_tcsxfrm function", "_tctime function", "_tctime_s function", "_tctime32 function", "_tctime32_s function", "_tctime64 function", "_tctime64_s function", "_texecl function", "_texecle function", "_texeclp function", "_texeclpe function", "_texecv function", "_texecve function", "_texecvp function", "_texecvpe function", "_tfdopen function", "_tfindfirst function", "_tfindnext function", "_tfindnext32 function", "_tfindnext64 function", "_tfindnexti64 function", "_tfindnexti6432 function", "_tfindnext32i64 function", "_tfopen function", "_tfopen_s function", "_tfreopen function", "_tfreopen_s function", "_tfsopen function", "_tfullpath function", "_tgetcwd function", "_tgetdcwd function", "_tgetenv function", "_tgetenv_s function", "_tmain function", "_tmakepath function", "_tmakepath_s function", "_tmkdir function", "_tmktemp function", "_tmktemp_s function", "_topen function", "_topen_s function", "_totlower function", "_totupper function", "_tperror function", "_tpopen function", "_tprintf function", "_tprintf_s function", "_tputenv function", "_tremove function", "_trename function", "_trmdir function", "_tsearchenv function", "_tsearchenv_s function", "_tscanf function", "_tscanf_s function", "_tsetlocale function", "_tsopen function", "_tsopen_s function", "_tspawnl function", "_tspawnle function", "_tspawnlp function", "_tspawnlpe function", "_tspawnv function", "_tspawnve function", "_tspawnvp function", "_tspawnvpe function", "_tsplitpath function", "_tstat function", "_tstat32 function", "_tstati32 function", "_tstat64 function", "_tstati64 function", "_tstof function", "_tstoi function", "_tstoi64 function", "_tstol function", "_tstrdate function", "_tstrdate_s function", "_tstrtime function", "_tstrtime_s function", "_tsystem function", "_ttempnam function", "_ttmpnam function", "_ttmpnam_s function", "_ttoi function", "_ttoi64 function", "_ttol function", "_tunlink function", "_tutime function", "_tutime32 function", "_tutime64 function", "_tWinMain function", "_ui64tot function", "_ui64tot_s function", "_ultot function", "_ultot_s function", "_ungettc function", "_ungettch function", "_vftprintf function", "_vftprintf_s function", "_vsctprintf function", "_vsctprintf_s function", "_vsntprintf function", "_vsntprintf_s function", "_vstprintf function", "_vtprintf function", "_vtprintf_s function"] --- -# Routine Mappings +# Generic-text function mappings -The generic-text routine mappings are defined in TCHAR.H. `_tccpy` and `_tclen` map to functions in the MBCS model; they are mapped to macros or inline functions in the SBCS and Unicode models for completeness. For information on a generic text routine, see the help topic about the corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. +The generic-text routine mappings are defined in `TCHAR.H`. `_tccpy` and `_tclen` map to functions in the MBCS model; they're mapped to macros or inline functions in the SBCS and Unicode models for completeness. For information on a generic text routine, see the help article about the corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. -More specific information about individual routines listed in the left column in the following table is not available in this documentation. However, you can easily look up the information on a corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. Use the **Search** command on the **Help** menu to look up any generic-text routine listed below. +More specific information about individual routines listed in the left column in the following table isn't available in this documentation. However, you can easily look up the information on a corresponding `SBCS`-, `_MBCS`-, or `_UNICODE`-related routine. Use the **Search** command on the **Help** menu to look up any generic-text routine listed below. -For related information, see [Generic-Text Mappings in TCHAR.H](../text/generic-text-mappings-in-tchar-h.md). +For related information, see [Generic-text mappings in tchar.h](../text/generic-text-mappings-in-tchar-h.md). -### Generic-Text Routine Mappings +### Function mappings -|Generic-text routine name|SBCS (_UNICODE & MBCS not defined)|_MBCS defined|_UNICODE defined| -|--------------------------------|-------------------------------------------|--------------------|-----------------------| -|`_cgetts`|`_cgets`|`_cgets`|`_cgetws`| -|`_cgetts_s`|`_cgets_s`|`_cgets_s`|`_cgetws_s`| -|`_cputts`|`_cputs`|`_cputs`|`_cputws`| -|`_fgettc`|`fgetc`|`fgetc`|`fgetwc`| -|`_fgettchar`|`_fgetchar`|`_fgetchar`|`_fgetwchar`| -|`_fgetts`|`fgets`|`fgets`|`fgetws`| -|`_fputtc`|`fputc`|`fputc`|`fputwc`| -|`_fputtchar`|`_fputchar`|`_fputchar`|`_fputwchar`| -|`_fputts`|`fputs`|`fputs`|`fputws`| -|`_ftprintf`|`fprintf`|`fprintf`|`fwprintf`| -|`_ftprintf_s`|`fprintf_s`|`fprintf_s`|`fwprintf_s`| -|`_ftscanf`|`fscanf`|`fscanf`|`fwscanf`| -|`_ftscanf_s`|`fscanf_s`|`fscanf_s`|`fwscanf_s`| -|`_gettc`|`getc`|`getc`|`getwc`| -|`_gettch`|`_getch`|`_getch`|`_getwch`| -|`_gettchar`|`getchar`|`getchar`|`getwchar`| -|`_gettche`|`_getche`|`_getche`|`_getwche`| -|`_getts`|`gets`|`gets`|`getws`| -|`_getts_s`|`gets_s`|`gets_s`|`getws_s`| -|`_istalnum`|`isalnum`|`_ismbcalnum`|`iswalnum`| -|`_istalpha`|`isalpha`|`_ismbcalpha`|`iswalpha`| -|`_istascii`|`isascii`|`isascii`|`iswascii`| -|`_istcntrl`|`iscntrl`|`iscntrl`|`iswcntrl`| -|`_istdigit`|`isdigit`|`_ismbcdigit`|`iswdigit`| -|`_istgraph`|`isgraph`|`_ismbcgraph`|`iswgraph`| -|`_istlead`|Always returns false|`_ismbblead`|Always returns false| -|`_istleadbyte`|Always returns false|`isleadbyte`|Always returns false| -|`_istlegal`|Always returns true|`_ismbclegal`|Always returns true| -|`_istlower`|`islower`|`_ismbclower`|`iswlower`| -|`_istprint`|`isprint`|`_ismbcprint`|`iswprint`| -|`_istpunct`|`ispunct`|`_ismbcpunct`|`iswpunct`| -|`_istspace`|`isspace`|`_ismbcspace`|`iswspace`| -|`_istupper`|`isupper`|`_ismbcupper`|`iswupper`| -|`_istxdigit`|`isxdigit`|`isxdigit`|`iswxdigit`| -|`_itot`|`_itoa`|`_itoa`|`_itow`| -|`_itot_s`|`_itoa_s`|`_itoa_s`|`_itow_s`| -|`_ltot`|`_ltoa`|`_ltoa`|`_ltow`| -|`_ltot_s`|`_ltoa_s`|`_ltoa_s`|`_ltow_s`| -|`_puttc`|`putc`|`putc`|`putwc`| -|`_puttch`|`_putch`|`_putch`|`_putwch`| -|`_puttchar`|`putchar`|`putchar`|`putwchar`| -|`_putts`|`puts`|`puts`|`_putws`| -|`_sctprintf`|`_scprintf`|`_scprintf`|`_scwprintf`| -|`_sntprintf`|`_snprintf`|`_snprintf`|`_snwprintf`| -|`_sntprintf_s`|`_snprintf_s`|`_snprintf_s`|`_snwprintf_s`| -|`_sntscanf`|`_snscanf`|`_snscanf`|`_snwscanf`| -|`_sntscanf_s`|`_snscanf_s`|`_snscanf_s`|`_snwscanf_s`| -|`_stprintf`|`sprintf`|`sprintf`|`swprintf`| -|`_stprintf_s`|`sprintf_s`|`sprintf_s`|`swprintf_s`| -|`_stscanf`|`sscanf`|`sscanf`|`swscanf`| -|`_stscanf_s`|`sscanf_s`|`sscanf_s`|`swscanf_s`| -|`_taccess`|`_access`|`_access`|`_waccess`| -|`_taccess_s`|`_access_s`|`_access_s`|`_waccess_s`| -|`_tasctime`|`asctime`|`asctime`|`_wasctime`| -|`_tasctime_s`|`asctime_s`|`asctime_s`|`_wasctime_s`| -|`_tccmp`|Maps to macro or inline function|`_mbsncmp`|Maps to macro or inline function| -|`_tccpy`|Maps to macro or inline function|`_mbccpy`|Maps to macro or inline function| -|`_tccpy_s`|`strcpy_s`|`_mbccpy_s`|`wcscpy_s`| -|`_tchdir`|`_chdir`|`_chdir`|`_wchdir`| -|`_tclen`|Maps to macro or inline function|`_mbclen`|Maps to macro or inline function| -|`_tchmod`|`_chmod`|`_chmod`|`_wchmod`| -|`_tcprintf`|`_cprintf`|`_cprintf`|`_cwprintf`| -|`_tcprintf_s`|`_cprintf_s`|`_cprintf_s`|`_cwprintf_s`| -|`_tcreat`|`_creat`|`_creat`|`_wcreat`| -|`_tcscanf`|`_cscanf`|`_cscanf`|`_cwscanf`| -|`_tcscanf_s`|`_cscanf_s`|`_cscanf_s`|`_cwscanf_s`| -|`_tcscat`|`strcat`|`_mbscat`|`wcscat`| -|`_tcscat_s`|`strcat_s`|`_mbscat_s`|`wcscat_s`| -|`_tcschr`|`strchr`|`_mbschr`|`wcschr`| -|`_tcsclen`|`strlen`|`_mbslen`|`wcslen`| -|`_tcsclen_s`|`strlen_s`|`_mbslen_s`|`wcslen_s`| -|`_tcscmp`|`strcmp`|`_mbscmp`|`wcscmp`| -|`_tcscoll`|`strcoll`|`_mbscoll`|`wcscoll`| -|`_tcscpy`|`strcpy`|`_mbscpy`|`wcscpy`| -|`_tcscpy_s`|`strcpy_s`|`_mbscpy_s`|`wcscpy_s`| -|`_tcscspn`|`strcspn`|`_mbscspn`|`wcscspn`| -|`_tcsdec`|`_strdec`|`_mbsdec`|`_wcsdec`| -|`_tcsdup`|`_strdup`|`_mbsdup`|`_wcsdup`| -|`_tcserror`|`strerror`|`strerror`|`_wcserror`| -|`_tcserror_s`|`strerror_s`|`strerror_s`|`_wcserror_s`| -|`_tcsftime`|`strftime`|`strftime`|`wcsftime`| -|`_tcsicmp`|`_stricmp`|`_mbsicmp`|`_wcsicmp`| -|`_tcsicoll`|`_stricoll`|`_mbsicoll`|`_wcsicoll`| -|`_tcsinc`|`_strinc`|`_mbsinc`|`_wcsinc`| -|`_tcslen`|`strlen`|`strlen`|`wcslen`| -|`_tcslwr`|`_strlwr`|`_mbslwr`|`_wcslwr`| -|`_tcslwr_s`|`_strlwr_s`|`_mbslwr_s`|`_wcslwr_s`| -|`_tcsnbcnt`|`_strncnt`|`_mbsnbcnt`|`_wcsncnt`| -|`_tcsncat`|`strncat`|`_mbsnbcat`|`wcsncat`| -|`_tcsncat_s`|`strncat_s`|`_mbsnbcat_s`|`wcsncat_s`| -|`_tcsnccat`|`strncat`|`_mbsncat`|`wcsncat`| -|`_tcsnccmp`|`strncmp`|`_mbsncmp`|`wcsncmp`| -|`_tcsnccmp_s`|`strncmp_s`|`_mbsncmp_s`|`wcsncmp_s`| -|`_tcsnccoll`|`_strncoll`|`_mbsncoll`|`_wcsncoll`| -|`_tcsncmp`|`strncmp`|`_mbsnbcmp`|`wcsncmp`| -|`_tcsnccnt`|`_strncnt`|`_mbsnccnt`|`_wcsncnt`| -|`_tcsnccpy`|`strncpy`|`_mbsncpy`|`wcsncpy`| -|`_tcsnccpy_s`|`strncpy_s`|`_mbsncpy_s`|`wcsncpy_s`| -|`_tcsncicmp`|`_strnicmp`|`_mbsnicmp`|`_wcsnicmp`| -|`_tcsncicoll`|`_strnicoll`|`_mbsnicoll`|`_wcsnicoll`| -|`_tcsncpy`|`strncpy`|`_mbsnbcpy`|`wcsncpy`| -|`_tcsncpy_s`|`strncpy_s`|`_mbsnbcpy_s`|`wcsncpy_s`| -|`_tcsncset`|`_strnset`|`_mbsnset`|`_wcsnset`| -|`_tcsnextc`|`_strnextc`|`_mbsnextc`|`_wcsnextc`| -|`_tcsnicmp`|`_strnicmp`|`_mbsnbicmp`|`_wcsnicmp`| -|`_tcsnicoll`|`_strnicoll`|`_mbsnbicoll`|`_wcsnicoll`| -|`_tcsninc`|`_strninc`|`_mbsninc`|`_wcsninc`| -|`_tcsnccnt`|`_strncnt`|`_mbsnccnt`|`_wcsncnt`| -|`_tcsnset`|`_strnset`|`_mbsnbset`|`_wcsnset`| -|`_tcspbrk`|`strpbrk`|`_mbspbrk`|`wcspbrk`| -|`_tcsspnp`|`_strspnp`|`_mbsspnp`|`_wcsspnp`| -|`_tcsrchr`|`strrchr`|`_mbsrchr`|`wcsrchr`| -|`_tcsrev`|`_strrev`|`_mbsrev`|`_wcsrev`| -|`_tcsset`|`_strset`|`_mbsset`|`_wcsset`| -|`_tcsspn`|`strspn`|`_mbsspn`|`wcsspn`| -|`_tcsstr`|`strstr`|`_mbsstr`|`wcsstr`| -|`_tcstod`|`strtod`|`strtod`|`wcstod`| -|`_tcstoi64`|`_strtoi64`|`_strtoi64`|`_wcstoi64`| -|`_tcstok`|`strtok`|`_mbstok`|`wcstok`| -|`_tcstok_s`|`strtok_s`|`_mbstok_s`|`wcstok_s`| -|`_tcstol`|`strtol`|`strtol`|`wcstol`| -|`_tcstoui64`|`_strtoui64`|`_strtoui64`|`_wcstoui64`| -|`_tcstoul`|`strtoul`|`strtoul`|`wcstoul`| -|`_tcsupr`|`_strupr`|`_mbsupr`|`_wcsupr`| -|`_tcsupr_s`|`_strupr_s`|`_mbsupr_s`|`_wcsupr_s`| -|`_tcsxfrm`|`strxfrm`|`strxfrm`|`wcsxfrm`| -|`_tctime`|`ctime`|`ctime`|`_wctime`| -|`_tctime_s`|`ctime_s`|`ctime_s`|`_wctime_s`| -|`_tctime32`|`_ctime32`|`_ctime32`|`_wctime32`| -|`_tctime32_s`|`_ctime32_s`|`_ctime32_s`|`_wctime32_s`| -|`_tctime64`|`_ctime64`|`_ctime64`|`_wctime64`| -|`_tctime64_s`|`_ctime64_s`|`_ctime64_s`|`_wctime64_s`| -|`_texecl`|`_execl`|`_execl`|`_wexecl`| -|`_texecle`|`_execle`|`_execle`|`_wexecle`| -|`_texeclp`|`_execlp`|`_execlp`|`_wexeclp`| -|`_texeclpe`|`_execlpe`|`_execlpe`|`_wexeclpe`| -|`_texecv`|`_execv`|`_execv`|`_wexecv`| -|`_texecve`|`_execve`|`_execve`|`_wexecve`| -|`_texecvp`|`_execvp`|`_execvp`|`_wexecvp`| -|`_texecvpe`|`_execvpe`|`_execvpe`|`_wexecvpe`| -|`_tfdopen`|`_fdopen`|`_fdopen`|`_wfdopen`| -|`_tfindfirst`|`_findfirst`|`_findfirst`|`_wfindfirst`| -|`_tfindnext`|`_findnext`|`_findnext`|`_wfindnext`| -|`_tfindnext32`|`_findnext32`|`_findnext32`|`_wfindnext32`| -|`_tfindnext64`|`_findnext64`|`_findnext64`|`_wfindnext64`| -|`_tfindnexti64`|`_findnexti64`|`_findnexti64`|`_wfindnexti64`| -|`_tfindnexti6432`|`_findnexti6432`|`_findnexti6432`|`_wfindnexti6432`| -|`_tfindnext32i64`|`_findnext32i64`|`_findnext32i64`|`_wfindnext32i64`| -|`_tfopen`|`fopen`|`fopen`|`_wfopen`| -|`_tfopen_s`|`fopen_s`|`fopen_s`|`_wfopen_s`| -|`_tfreopen`|`freopen`|`freopen`|`_wfreopen`| -|`_tfreopen_s`|`freopen_s`|`freopen_s`|`_wfreopen_s`| -|`_tfsopen`|`_fsopen`|`_fsopen`|`_wfsopen`| -|`_tfullpath`|`_fullpath`|`_fullpath`|`_wfullpath`| -|`_tgetcwd`|`_getcwd`|`_getcwd`|`_wgetcwd`| -|`_tgetdcwd`|`_getdcwd`|`_getdcwd`|`_wgetdcwd`| -|`_tgetenv`|`getenv`|`getenv`|`_wgetenv`| -|`_tgetenv_s`|`getenv_s`|`getenv_s`|`_wgetenv_s`| -|`_tmain`|`main`|`main`|`wmain`| -|`_tmakepath`|`_makepath`|`_makepath`|`_wmakepath`| -|`_tmakepath_s`|`_makepath_s`|`_makepath_s`|`_wmakepath_s`| -|`_tmkdir`|`_mkdir`|`_mkdir`|`_wmkdir`| -|`_tmktemp`|`_mktemp`|`_mktemp`|`_wmktemp`| -|`_tmktemp_s`|`_mktemp_s`|`_mktemp_s`|`_wmktemp_s`| -|`_topen`|`_open`|`_open`|`_wopen`| -|`_topen_s`|`_open_s`|`_open_s`|`_wopen_s`| -|`_totlower`|`tolower`|`_mbctolower`|`towlower`| -|`_totupper`|`toupper`|`_mbctoupper`|`towupper`| -|`_tperror`|`perror`|`perror`|`_wperror`| -|`_tpopen`|`_popen`|`_popen`|`_wpopen`| -|`_tprintf`|`printf`|`printf`|`wprintf`| -|`_tprintf_s`|`printf_s`|`printf_s`|`wprintf_s`| -|`_tputenv`|`_putenv`|`_putenv`|`_wputenv`| -|`_tputenv_s`|`_putenv_s`|`_putenv_s`|`_wputenv_s`| -|`_tremove`|`remove`|`remove`|`_wremove`| -|`_trename`|`rename`|`rename`|`_wrename`| -|`_trmdir`|`_rmdir`|`_rmdir`|`_wrmdir`| -|`_tsearchenv`|`_searchenv`|`_searchenv`|`_wsearchenv`| -|`_tsearchenv_s`|`_searchenv_s`|`_searchenv_s`|`_wsearchenv_s`| -|`_tscanf`|`scanf`|`scanf`|`wscanf`| -|`_tscanf_s`|`scanf_s`|`scanf_s`|`wscanf_s`| -|`_tsetlocale`|`setlocale`|`setlocale`|`_wsetlocale`| -|`_tsopen`|`_sopen`|`_sopen`|`_wsopen`| -|`_tsopen_s`|`_sopen_s`|`_sopen_s`|`_wsopen_s`| -|`_tspawnl`|`_spawnl`|`_spawnl`|`_wspawnl`| -|`_tspawnle`|`_spawnle`|`_spawnle`|`_wspawnle`| -|`_tspawnlp`|`_spawnlp`|`_spawnlp`|`_wspawnlp`| -|`_tspawnlpe`|`_spawnlpe`|`_spawnlpe`|`_wspawnlpe`| -|`_tspawnv`|`_spawnv`|`_spawnv`|`_wspawnv`| -|`_tspawnve`|`_spawnve`|`_spawnve`|`_wspawnve`| -|`_tspawnvp`|`_spawnvp`|`_spawnvp`|`_wspawnvp`| -|`_tspawnvpe`|`_spawnvpe`|`_spawnvpe`|`_wspawnvpe`| -|`_tsplitpath`|`_splitpath`|`_splitpath`|`_wsplitpath`| -|`_tstat`|`_stat`|`_stat`|`_wstat`| -|`_tstat32`|`_stat32`|`_stat32`|`_wstat32`| -|`_tstati32`|`_stati32`|`_stati32`|`_wstati32`| -|`_tstat64`|`_stat64`|`_stat64`|`_wstat64`| -|`_tstati64`|`_stati64`|`_stati64`|`_wstati64`| -|`_tstof`|`atof`|`atof`|`_wtof`| -|`_tstoi`|`atoi`|`atoi`|`_wtoi`| -|`_tstoi64`|`_atoi64`|`_atoi64`|`_wtoi64`| -|`_tstol`|`atol`|`atol`|`_wtol`| -|`_tstrdate`|`_strdate`|`_strdate`|`_wstrdate`| -|`_tstrdate_s`|`_strdate_s`|`_strdate_s`|`_wstrdate_s`| -|`_tstrtime`|`_strtime`|`_strtime`|`_wstrtime`| -|`_tstrtime_s`|`_strtime_s`|`_strtime_s`|`_wstrtime_s`| -|`_tsystem`|`system`|`system`|`_wsystem`| -|`_ttempnam`|`_tempnam`|`_tempnam`|`_wtempnam`| -|`_ttmpnam`|`tmpnam`|`tmpnam`|`_wtmpnam`| -|`_ttmpnam_s`|`tmpnam_s`|`tmpnam_s`|`_wtmpnam_s`| -|`_ttoi`|`atoi`|`atoi`|`_wtoi`| -|`_ttoi64`|`_atoi64`|`_atoi64`|`_wtoi64`| -|`_ttol`|`atol`|`atol`|`_wtol`| -|`_tunlink`|`_unlink`|`_unlink`|`_wunlink`| -|`_tutime`|`_utime`|`_utime`|`_wutime`| -|`_tutime32`|`_utime32`|`_utime32`|`_wutime32`| -|`_tutime64`|`_utime64`|`_utime64`|`_wutime64`| -|`_tWinMain`|`WinMain`|`WinMain`|`wWinMain`| -|`_ui64tot`|`_ui64toa`|`_ui64toa`|`_ui64tow`| -|`_ui64tot_s`|`_ui64toa_s`|`_ui64toa_s`|`_ui64tow_s`| -|`_ultot`|`_ultoa`|`_ultoa`|`_ultow`| -|`_ultot_s`|`_ultoa_s`|`_ultoa_s`|`_ultow_s`| -|`_ungettc`|`ungetc`|`ungetc`|`ungetwc`| -|`_ungettch`|`_ungetch`|`_ungetch`|`_ungetwch`| -|`_vftprintf`|`vfprintf`|`vfprintf`|`vfwprintf`| -|`_vftprintf_s`|`vfprintf_s`|`vfprintf_s`|`vfwprintf_S`| -|`_vsctprintf`|`_vscprintf`|`_vscprintf`|`_vscwprintf`| -|`_vsctprintf_s`|`_vscprintf_s`|`_vscprintf_s`|`_vscwprintf_S`| -|`_vsntprintf`|`_vsnprintf`|`_vsnprintf`|`_vsnwprintf`| -|`_vsntprintf_s`|`_vsnprintf_s`|`_vsnprintf_s`|`_vsnwprintf_s`| -|`_vstprintf`|`vsprintf`|`vsprintf`|`vswprintf`| -|`_vstprintf_s`|`vsprintf_s`|`vsprintf_s`|`vswprintf_s`| -|`_vtprintf`|`vprintf`|`vprintf`|`vwprintf`| -|`_vtprintf_s`|`vprintf_s`|`vprintf_s`|`vwprintf_s`| +| Generic-text routine name | `SBCS` (`_UNICODE` and `MBCS` not defined) | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_cgetts` | `_cgets` | `_cgets` | `_cgetws` | +| `_cgetts_s` | `_cgets_s` | `_cgets_s` | `_cgetws_s` | +| `_cputts` | `_cputs` | `_cputs` | `_cputws` | +| `_fgettc` | `fgetc` | `fgetc` | `fgetwc` | +| `_fgettchar` | `_fgetchar` | `_fgetchar` | `_fgetwchar` | +| `_fgetts` | `fgets` | `fgets` | `fgetws` | +| `_fputtc` | `fputc` | `fputc` | `fputwc` | +| `_fputtchar` | `_fputchar` | `_fputchar` | `_fputwchar` | +| `_fputts` | `fputs` | `fputs` | `fputws` | +| `_ftprintf` | `fprintf` | `fprintf` | `fwprintf` | +| `_ftprintf_l` | `_fprintf_l` | `_fprintf_l` | `_fwprintf_l` | +| `_ftprintf_s` | `fprintf_s` | `fprintf_s` | `fwprintf_s` | +| `_ftscanf` | `fscanf` | `fscanf` | `fwscanf` | +| `_ftscanf_s` | `fscanf_s` | `fscanf_s` | `fwscanf_s` | +| `_gettc` | `getc` | `getc` | `getwc` | +| `_gettch` | `_getch` | `_getch` | `_getwch` | +| `_gettchar` | `getchar` | `getchar` | `getwchar` | +| `_gettche` | `_getche` | `_getche` | `_getwche` | +| `_getts` | `gets` | `gets` | `getws` | +| `_getts_s` | `gets_s` | `gets_s` | `getws_s` | +| `_istalnum` | `isalnum` | `_ismbcalnum` | `iswalnum` | +| `_istalpha` | `isalpha` | `_ismbcalpha` | `iswalpha` | +| `_istascii` | `isascii` | `isascii` | `iswascii` | +| `_istcntrl` | `iscntrl` | `iscntrl` | `iswcntrl` | +| `_istdigit` | `isdigit` | `_ismbcdigit` | `iswdigit` | +| `_istgraph` | `isgraph` | `_ismbcgraph` | `iswgraph` | +| `_istlead` | Always returns false | `_ismbblead` | Always returns false | +| `_istleadbyte` | Always returns false | `isleadbyte` | Always returns false | +| `_istlegal` | Always returns true | `_ismbclegal` | Always returns true | +| `_istlower` | `islower` | `_ismbclower` | `iswlower` | +| `_istprint` | `isprint` | `_ismbcprint` | `iswprint` | +| `_istpunct` | `ispunct` | `_ismbcpunct` | `iswpunct` | +| `_istspace` | `isspace` | `_ismbcspace` | `iswspace` | +| `_istupper` | `isupper` | `_ismbcupper` | `iswupper` | +| `_istxdigit` | `isxdigit` | `isxdigit` | `iswxdigit` | +| `_itot` | `_itoa` | `_itoa` | `_itow` | +| `_itot_s` | `_itoa_s` | `_itoa_s` | `_itow_s` | +| `_ltot` | `_ltoa` | `_ltoa` | `_ltow` | +| `_ltot_s` | `_ltoa_s` | `_ltoa_s` | `_ltow_s` | +| `_puttc` | `putc` | `putc` | `putwc` | +| `_puttch` | `_putch` | `_putch` | `_putwch` | +| `_puttchar` | `putchar` | `putchar` | `putwchar` | +| `_putts` | `puts` | `puts` | `_putws` | +| `_sctprintf` | `_scprintf` | `_scprintf` | `_scwprintf` | +| `_sntprintf` | `_snprintf` | `_snprintf` | `_snwprintf` | +| `_sntprintf_s` | `_snprintf_s` | `_snprintf_s` | `_snwprintf_s` | +| `_sntscanf` | `_snscanf` | `_snscanf` | `_snwscanf` | +| `_sntscanf_s` | `_snscanf_s` | `_snscanf_s` | `_snwscanf_s` | +| `_stprintf` | `sprintf` | `sprintf` | `swprintf` | +| `_stprintf_s` | `sprintf_s` | `sprintf_s` | `swprintf_s` | +| `_stscanf` | `sscanf` | `sscanf` | `swscanf` | +| `_stscanf_s` | `sscanf_s` | `sscanf_s` | `swscanf_s` | +| `_taccess` | `_access` | `_access` | `_waccess` | +| `_taccess_s` | `_access_s` | `_access_s` | `_waccess_s` | +| `_tasctime` | `asctime` | `asctime` | `_wasctime` | +| `_tasctime_s` | `asctime_s` | `asctime_s` | `_wasctime_s` | +| `_tccmp` | Maps to macro or inline function | `_mbsncmp` | Maps to macro or inline function | +| `_tccpy` | Maps to macro or inline function | `_mbccpy` | Maps to macro or inline function | +| `_tccpy_s` | `strcpy_s` | `_mbccpy_s` | `wcscpy_s` | +| `_tchdir` | `_chdir` | `_chdir` | `_wchdir` | +| `_tclen` | Maps to macro or inline function | `_mbclen` | Maps to macro or inline function | +| `_tchmod` | `_chmod` | `_chmod` | `_wchmod` | +| `_tcprintf` | `_cprintf` | `_cprintf` | `_cwprintf` | +| `_tcprintf_s` | `_cprintf_s` | `_cprintf_s` | `_cwprintf_s` | +| `_tcreat` | `_creat` | `_creat` | `_wcreat` | +| `_tcscanf` | `_cscanf` | `_cscanf` | `_cwscanf` | +| `_tcscanf_s` | `_cscanf_s` | `_cscanf_s` | `_cwscanf_s` | +| `_tcscat` | `strcat` | `_mbscat` | `wcscat` | +| `_tcscat_s` | `strcat_s` | `_mbscat_s` | `wcscat_s` | +| `_tcschr` | `strchr` | `_mbschr` | `wcschr` | +| `_tcsclen` | `strlen` | `_mbslen` | `wcslen` | +| `_tcsclen_s` | `strlen_s` | `_mbslen_s` | `wcslen_s` | +| `_tcscmp` | `strcmp` | `_mbscmp` | `wcscmp` | +| `_tcscoll` | `strcoll` | `_mbscoll` | `wcscoll` | +| `_tcscpy` | `strcpy` | `_mbscpy` | `wcscpy` | +| `_tcscpy_s` | `strcpy_s` | `_mbscpy_s` | `wcscpy_s` | +| `_tcscspn` | `strcspn` | `_mbscspn` | `wcscspn` | +| `_tcsdec` | `_strdec` | `_mbsdec` | `_wcsdec` | +| `_tcsdup` | `_strdup` | `_mbsdup` | `_wcsdup` | +| `_tcserror` | `strerror` | `strerror` | `_wcserror` | +| `_tcserror_s` | `strerror_s` | `strerror_s` | `_wcserror_s` | +| `_tcsftime` | `strftime` | `strftime` | `wcsftime` | +| `_tcsicmp` | `_stricmp` | `_mbsicmp` | `_wcsicmp` | +| `_tcsicoll` | `_stricoll` | `_mbsicoll` | `_wcsicoll` | +| `_tcsinc` | `_strinc` | `_mbsinc` | `_wcsinc` | +| `_tcslen` | `strlen` | `strlen` | `wcslen` | +| `_tcslwr` | `_strlwr` | `_mbslwr` | `_wcslwr` | +| `_tcslwr_s` | `_strlwr_s` | `_mbslwr_s` | `_wcslwr_s` | +| `_tcsnbcnt` | `_strncnt` | `_mbsnbcnt` | `_wcsncnt` | +| `_tcsncat` | `strncat` | `_mbsnbcat` | `wcsncat` | +| `_tcsncat_s` | `strncat_s` | `_mbsnbcat_s` | `wcsncat_s` | +| `_tcsnccat` | `strncat` | `_mbsncat` | `wcsncat` | +| `_tcsnccmp` | `strncmp` | `_mbsncmp` | `wcsncmp` | +| `_tcsnccmp_s` | `strncmp_s` | `_mbsncmp_s` | `wcsncmp_s` | +| `_tcsnccoll` | `_strncoll` | `_mbsncoll` | `_wcsncoll` | +| `_tcsncmp` | `strncmp` | `_mbsnbcmp` | `wcsncmp` | +| `_tcsnccnt` | `_strncnt` | `_mbsnccnt` | `_wcsncnt` | +| `_tcsnccpy` | `strncpy` | `_mbsncpy` | `wcsncpy` | +| `_tcsnccpy_s` | `strncpy_s` | `_mbsncpy_s` | `wcsncpy_s` | +| `_tcsncicmp` | `_strnicmp` | `_mbsnicmp` | `_wcsnicmp` | +| `_tcsncicoll` | `_strnicoll` | `_mbsnicoll` | `_wcsnicoll` | +| `_tcsncpy` | `strncpy` | `_mbsnbcpy` | `wcsncpy` | +| `_tcsncpy_s` | `strncpy_s` | `_mbsnbcpy_s` | `wcsncpy_s` | +| `_tcsncset` | `_strnset` | `_mbsnset` | `_wcsnset` | +| `_tcsnextc` | `_strnextc` | `_mbsnextc` | `_wcsnextc` | +| `_tcsnicmp` | `_strnicmp` | `_mbsnbicmp` | `_wcsnicmp` | +| `_tcsnicoll` | `_strnicoll` | `_mbsnbicoll` | `_wcsnicoll` | +| `_tcsninc` | `_strninc` | `_mbsninc` | `_wcsninc` | +| `_tcsnset` | `_strnset` | `_mbsnbset` | `_wcsnset` | +| `_tcspbrk` | `strpbrk` | `_mbspbrk` | `wcspbrk` | +| `_tcsspnp` | `_strspnp` | `_mbsspnp` | `_wcsspnp` | +| `_tcsrchr` | `strrchr` | `_mbsrchr` | `wcsrchr` | +| `_tcsrev` | `_strrev` | `_mbsrev` | `_wcsrev` | +| `_tcsset` | `_strset` | `_mbsset` | `_wcsset` | +| `_tcsspn` | `strspn` | `_mbsspn` | `wcsspn` | +| `_tcsstr` | `strstr` | `_mbsstr` | `wcsstr` | +| `_tcstod` | `strtod` | `strtod` | `wcstod` | +| `_tcstoi64` | `_strtoi64` | `_strtoi64` | `_wcstoi64` | +| `_tcstok` | `strtok` | `_mbstok` | `wcstok` | +| `_tcstok_s` | `strtok_s` | `_mbstok_s` | `wcstok_s` | +| `_tcstol` | `strtol` | `strtol` | `wcstol` | +| `_tcstoui64` | `_strtoui64` | `_strtoui64` | `_wcstoui64` | +| `_tcstoul` | `strtoul` | `strtoul` | `wcstoul` | +| `_tcsupr` | `_strupr` | `_mbsupr` | `_wcsupr` | +| `_tcsupr_s` | `_strupr_s` | `_mbsupr_s` | `_wcsupr_s` | +| `_tcsxfrm` | `strxfrm` | `strxfrm` | `wcsxfrm` | +| `_tctime` | `ctime` | `ctime` | `_wctime` | +| `_tctime_s` | `ctime_s` | `ctime_s` | `_wctime_s` | +| `_tctime32` | `_ctime32` | `_ctime32` | `_wctime32` | +| `_tctime32_s` | `_ctime32_s` | `_ctime32_s` | `_wctime32_s` | +| `_tctime64` | `_ctime64` | `_ctime64` | `_wctime64` | +| `_tctime64_s` | `_ctime64_s` | `_ctime64_s` | `_wctime64_s` | +| `_texecl` | `_execl` | `_execl` | `_wexecl` | +| `_texecle` | `_execle` | `_execle` | `_wexecle` | +| `_texeclp` | `_execlp` | `_execlp` | `_wexeclp` | +| `_texeclpe` | `_execlpe` | `_execlpe` | `_wexeclpe` | +| `_texecv` | `_execv` | `_execv` | `_wexecv` | +| `_texecve` | `_execve` | `_execve` | `_wexecve` | +| `_texecvp` | `_execvp` | `_execvp` | `_wexecvp` | +| `_texecvpe` | `_execvpe` | `_execvpe` | `_wexecvpe` | +| `_tfdopen` | `_fdopen` | `_fdopen` | `_wfdopen` | +| `_tfindfirst` | `_findfirst` | `_findfirst` | `_wfindfirst` | +| `_tfindnext` | `_findnext` | `_findnext` | `_wfindnext` | +| `_tfindnext32` | `_findnext32` | `_findnext32` | `_wfindnext32` | +| `_tfindnext64` | `_findnext64` | `_findnext64` | `_wfindnext64` | +| `_tfindnexti64` | `_findnexti64` | `_findnexti64` | `_wfindnexti64` | +| `_tfindnexti6432` | `_findnexti6432` | `_findnexti6432` | `_wfindnexti6432` | +| `_tfindnext32i64` | `_findnext32i64` | `_findnext32i64` | `_wfindnext32i64` | +| `_tfopen` | `fopen` | `fopen` | `_wfopen` | +| `_tfopen_s` | `fopen_s` | `fopen_s` | `_wfopen_s` | +| `_tfreopen` | `freopen` | `freopen` | `_wfreopen` | +| `_tfreopen_s` | `freopen_s` | `freopen_s` | `_wfreopen_s` | +| `_tfsopen` | `_fsopen` | `_fsopen` | `_wfsopen` | +| `_tfullpath` | `_fullpath` | `_fullpath` | `_wfullpath` | +| `_tgetcwd` | `_getcwd` | `_getcwd` | `_wgetcwd` | +| `_tgetdcwd` | `_getdcwd` | `_getdcwd` | `_wgetdcwd` | +| `_tgetenv` | `getenv` | `getenv` | `_wgetenv` | +| `_tgetenv_s` | `getenv_s` | `getenv_s` | `_wgetenv_s` | +| `_tmain` | `main` | `main` | `wmain` | +| `_tmakepath` | `_makepath` | `_makepath` | `_wmakepath` | +| `_tmakepath_s` | `_makepath_s` | `_makepath_s` | `_wmakepath_s` | +| `_tmkdir` | `_mkdir` | `_mkdir` | `_wmkdir` | +| `_tmktemp` | `_mktemp` | `_mktemp` | `_wmktemp` | +| `_tmktemp_s` | `_mktemp_s` | `_mktemp_s` | `_wmktemp_s` | +| `_topen` | `_open` | `_open` | `_wopen` | +| `_topen_s` | `_open_s` | `_open_s` | `_wopen_s` | +| `_totlower` | `tolower` | `_mbctolower` | `towlower` | +| `_totupper` | `toupper` | `_mbctoupper` | `towupper` | +| `_tperror` | `perror` | `perror` | `_wperror` | +| `_tpopen` | `_popen` | `_popen` | `_wpopen` | +| `_tprintf` | `printf` | `printf` | `wprintf` | +| `_tprintf_s` | `printf_s` | `printf_s` | `wprintf_s` | +| `_tputenv` | `_putenv` | `_putenv` | `_wputenv` | +| `_tputenv_s` | `_putenv_s` | `_putenv_s` | `_wputenv_s` | +| `_tremove` | `remove` | `remove` | `_wremove` | +| `_trename` | `rename` | `rename` | `_wrename` | +| `_trmdir` | `_rmdir` | `_rmdir` | `_wrmdir` | +| `_tsearchenv` | `_searchenv` | `_searchenv` | `_wsearchenv` | +| `_tsearchenv_s` | `_searchenv_s` | `_searchenv_s` | `_wsearchenv_s` | +| `_tscanf` | `scanf` | `scanf` | `wscanf` | +| `_tscanf_s` | `scanf_s` | `scanf_s` | `wscanf_s` | +| `_tsetlocale` | `setlocale` | `setlocale` | `_wsetlocale` | +| `_tsopen` | `_sopen` | `_sopen` | `_wsopen` | +| `_tsopen_s` | `_sopen_s` | `_sopen_s` | `_wsopen_s` | +| `_tspawnl` | `_spawnl` | `_spawnl` | `_wspawnl` | +| `_tspawnle` | `_spawnle` | `_spawnle` | `_wspawnle` | +| `_tspawnlp` | `_spawnlp` | `_spawnlp` | `_wspawnlp` | +| `_tspawnlpe` | `_spawnlpe` | `_spawnlpe` | `_wspawnlpe` | +| `_tspawnv` | `_spawnv` | `_spawnv` | `_wspawnv` | +| `_tspawnve` | `_spawnve` | `_spawnve` | `_wspawnve` | +| `_tspawnvp` | `_spawnvp` | `_spawnvp` | `_wspawnvp` | +| `_tspawnvpe` | `_spawnvpe` | `_spawnvpe` | `_wspawnvpe` | +| `_tsplitpath` | `_splitpath` | `_splitpath` | `_wsplitpath` | +| `_tstat` | `_stat` | `_stat` | `_wstat` | +| `_tstat32` | `_stat32` | `_stat32` | `_wstat32` | +| `_tstati32` | `_stati32` | `_stati32` | `_wstati32` | +| `_tstat64` | `_stat64` | `_stat64` | `_wstat64` | +| `_tstati64` | `_stati64` | `_stati64` | `_wstati64` | +| `_tstof` | `atof` | `atof` | `_wtof` | +| `_tstoi` | `atoi` | `atoi` | `_wtoi` | +| `_tstoi64` | `_atoi64` | `_atoi64` | `_wtoi64` | +| `_tstol` | `atol` | `atol` | `_wtol` | +| `_tstrdate` | `_strdate` | `_strdate` | `_wstrdate` | +| `_tstrdate_s` | `_strdate_s` | `_strdate_s` | `_wstrdate_s` | +| `_tstrtime` | `_strtime` | `_strtime` | `_wstrtime` | +| `_tstrtime_s` | `_strtime_s` | `_strtime_s` | `_wstrtime_s` | +| `_tsystem` | `system` | `system` | `_wsystem` | +| `_ttempnam` | `_tempnam` | `_tempnam` | `_wtempnam` | +| `_ttmpnam` | `tmpnam` | `tmpnam` | `_wtmpnam` | +| `_ttmpnam_s` | `tmpnam_s` | `tmpnam_s` | `_wtmpnam_s` | +| `_ttoi` | `atoi` | `atoi` | `_wtoi` | +| `_ttoi64` | `_atoi64` | `_atoi64` | `_wtoi64` | +| `_ttol` | `atol` | `atol` | `_wtol` | +| `_tunlink` | `_unlink` | `_unlink` | `_wunlink` | +| `_tutime` | `_utime` | `_utime` | `_wutime` | +| `_tutime32` | `_utime32` | `_utime32` | `_wutime32` | +| `_tutime64` | `_utime64` | `_utime64` | `_wutime64` | +| `_tWinMain` | `WinMain` | `WinMain` | `wWinMain` | +| `_ui64tot` | `_ui64toa` | `_ui64toa` | `_ui64tow` | +| `_ui64tot_s` | `_ui64toa_s` | `_ui64toa_s` | `_ui64tow_s` | +| `_ultot` | `_ultoa` | `_ultoa` | `_ultow` | +| `_ultot_s` | `_ultoa_s` | `_ultoa_s` | `_ultow_s` | +| `_ungettc` | `ungetc` | `ungetc` | `ungetwc` | +| `_ungettch` | `_ungetch` | `_ungetch` | `_ungetwch` | +| `_vftprintf` | `vfprintf` | `vfprintf` | `vfwprintf` | +| `_vftprintf_s` | `vfprintf_s` | `vfprintf_s` | `vfwprintf_S` | +| `_vsctprintf` | `_vscprintf` | `_vscprintf` | `_vscwprintf` | +| `_vsctprintf_s` | `_vscprintf_s` | `_vscprintf_s` | `_vscwprintf_S` | +| `_vsntprintf` | `_vsnprintf` | `_vsnprintf` | `_vsnwprintf` | +| `_vsntprintf_s` | `_vsnprintf_s` | `_vsnprintf_s` | `_vsnwprintf_s` | +| `_vstprintf` | `vsprintf` | `vsprintf` | `vswprintf` | +| `_vstprintf_s` | `vsprintf_s` | `vsprintf_s` | `vswprintf_s` | +| `_vtprintf` | `vprintf` | `vprintf` | `vwprintf` | +| `_vtprintf_s` | `vprintf_s` | `vprintf_s` | `vwprintf_s` | ## See also -[Generic-Text Mappings](../c-runtime-library/generic-text-mappings.md)
-[Data Type Mappings](../c-runtime-library/data-type-mappings.md)
-[Constant and Global Variable Mappings](../c-runtime-library/constant-and-global-variable-mappings.md)
-[A Sample Generic-Text Program](../c-runtime-library/a-sample-generic-text-program.md)
-[Using Generic-Text Mappings](../c-runtime-library/using-generic-text-mappings.md) +[Generic-text mappings](./generic-text-mappings.md)\ +[Data type mappings](./data-type-mappings.md)\ +[Constant and global variable mappings](./constant-and-global-variable-mappings.md)\ +[A sample generic-text program](./a-sample-generic-text-program.md)\ +[Using generic-text mappings](./using-generic-text-mappings.md) diff --git a/docs/c-runtime-library/rtdynamiccast.md b/docs/c-runtime-library/rtdynamiccast.md index 47de02d92bb..791143e7c05 100644 --- a/docs/c-runtime-library/rtdynamiccast.md +++ b/docs/c-runtime-library/rtdynamiccast.md @@ -3,49 +3,48 @@ description: "Learn more about: __RTDynamicCast" title: "__RTDynamicCast" ms.date: "1/14/2021" api_name: ["__RTDynamicCast"] -api_location: ["msvcr90.dll", "msvcr110.dll", "msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcr90.dll", "msvcr110.dll", "msvcr120.dll", "msvcrt.dll", "msvcr100.dll", "msvcr80.dll", "msvcr110_clr0400.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["__RTDynamicCast"] +f1_keywords: ["RTTIDATA/__RTDynamicCast", "__RTDynamicCast"] helpviewer_keywords: ["__RTDynamicCast"] -ms.assetid: 56aa2d7a-aa47-46ef-830d-e37175611239 --- -# __RTDynamicCast +# `__RTDynamicCast` -Runtime implementation of the [dynamic_cast](../cpp/dynamic-cast-operator.md) operator. +Runtime implementation of the [`dynamic_cast`](../cpp/dynamic-cast-operator.md) operator. ## Syntax ```cpp -PVOID __RTDynamicCast ( +PVOID __RTDynamicCast( PVOID inptr, LONG VfDelta, PVOID SrcType, PVOID TargetType, BOOL isReference - ) throw(...) +) throw(...) ``` #### Parameters -*inptr*
+*`inptr`*\ Pointer to a polymorphic object. -*VfDelta*
+*`VfDelta`*\ Offset of virtual function pointer in object. -*SrcType*
+*`SrcType`*\ Static type of object pointed to by the `inptr` parameter. -*TargetType*
+*`TargetType`*\ Intended result of cast. -*isReference*
+*`isReference`*\ **`true`** if input is a reference; **`false`** if input is a pointer. -## Return Value +## Return value -Pointer to the appropriate sub-object, if successful; otherwise, **NULL**. +Pointer to the appropriate subobject if successful; otherwise, `NULL`. ## Exceptions @@ -57,6 +56,6 @@ Converts `inptr` to an object of type `TargetType`. The type of `inptr` must be ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__RTDynamicCast|rtti.h| +| Routine | Required header | +|---|---| +| **`__RTDynamicCast`** | `` | diff --git a/docs/c-runtime-library/run-time-error-checking.md b/docs/c-runtime-library/run-time-error-checking.md index 90bfd33b54e..29ce32a4e13 100644 --- a/docs/c-runtime-library/run-time-error-checking.md +++ b/docs/c-runtime-library/run-time-error-checking.md @@ -12,16 +12,16 @@ Use the following functions to customize the way your program does runtime error ## Runtime error checking functions -|Function|Use| -|--------------|---------| -|[_RTC_GetErrDesc](../c-runtime-library/reference/rtc-geterrdesc.md)|Returns a brief description of a runtime error check type.| -|[_RTC_NumErrors](../c-runtime-library/reference/rtc-numerrors.md)|Returns the total number of errors that can be detected by runtime error checks.| -|[_RTC_SetErrorFunc](../c-runtime-library/reference/rtc-seterrorfunc.md)|Designates a function as the handler for reporting runtime error checks.| -|[_RTC_SetErrorType](../c-runtime-library/reference/rtc-seterrortype.md)|Associates an error that is detected by runtime error checks with a type.| +| Function | Use | +|---|---| +| [`_RTC_GetErrDesc`](./reference/rtc-geterrdesc.md) | Returns a brief description of a runtime error check type. | +| [`_RTC_NumErrors`](./reference/rtc-numerrors.md) | Returns the total number of errors that can be detected by runtime error checks. | +| [`_RTC_SetErrorFunc`](./reference/rtc-seterrorfunc.md) | Designates a function as the handler for reporting runtime error checks. | +| [`_RTC_SetErrorType`](./reference/rtc-seterrortype.md) | Associates an error that is detected by runtime error checks with a type. | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md)\ [/RTC (Runtime error checks)](../build/reference/rtc-run-time-error-checks.md)\ -[runtime_checks](../preprocessor/runtime-checks.md)\ -[Debug routines](../c-runtime-library/debug-routines.md) +[`runtime_checks`](../preprocessor/runtime-checks.md)\ +[Debug routines](./debug-routines.md) diff --git a/docs/c-runtime-library/run-time-routines-by-category.md b/docs/c-runtime-library/run-time-routines-by-category.md index 82114a33081..9fe6744b4aa 100644 --- a/docs/c-runtime-library/run-time-routines-by-category.md +++ b/docs/c-runtime-library/run-time-routines-by-category.md @@ -13,36 +13,30 @@ This section lists Universal C runtime (UCRT) library routines by category. For The main categories of UCRT library routines are: -:::row::: - :::column span=""::: - [Argument Access](../c-runtime-library/argument-access.md)\ - [Buffer Manipulation](../c-runtime-library/buffer-manipulation.md)\ - [Byte Classification](../c-runtime-library/byte-classification.md)\ - [Character Classification](../c-runtime-library/character-classification.md)\ - [Complex math support](../c-runtime-library/complex-math-support.md)\ - [Data Alignment](../c-runtime-library/data-alignment.md)\ - [Data Conversion](../c-runtime-library/data-conversion.md)\ - [Debug Routines](../c-runtime-library/debug-routines.md)\ - [Directory Control](../c-runtime-library/directory-control.md)\ - [Error Handling](../c-runtime-library/error-handling-crt.md)\ - [Exception Handling Routines](../c-runtime-library/exception-handling-routines.md)\ - [File Handling](../c-runtime-library/file-handling.md) - :::column-end::: - :::column span=""::: - [Floating-Point Support](../c-runtime-library/floating-point-support.md)\ - [Input and Output](../c-runtime-library/input-and-output.md)\ - [Internationalization](../c-runtime-library/internationalization.md)\ - [Memory Allocation](../c-runtime-library/memory-allocation.md)\ - [Process and Environment Control](../c-runtime-library/process-and-environment-control.md)\ - [Robustness](../c-runtime-library/robustness.md)\ - [Run-Time Error Checking](../c-runtime-library/run-time-error-checking.md)\ - [Searching and Sorting](../c-runtime-library/searching-and-sorting.md)\ - [String Manipulation](../c-runtime-library/string-manipulation-crt.md)\ - [System Calls](../c-runtime-library/system-calls.md)\ - [Time Management](../c-runtime-library/time-management.md) - :::column-end::: -:::row-end::: +- [Argument access](./argument-access.md) +- [Buffer manipulation](./buffer-manipulation.md) +- [Byte classification](./byte-classification.md) +- [Character classification](./character-classification.md) +- [Complex math support](./complex-math-support.md) +- [Data alignment](./data-alignment.md) +- [Data conversion](./data-conversion.md) +- [Debug routines](./debug-routines.md) +- [Directory control](./directory-control.md) +- [Error handling](./error-handling-crt.md) +- [Exception handling routines](./exception-handling-routines.md) +- [File handling](./file-handling.md) +- [Math and floating-point support](./floating-point-support.md) +- [Input and output](./input-and-output.md) +- [Internationalization](./internationalization.md) +- [Memory allocation](./memory-allocation.md) +- [Process and environment control](./process-and-environment-control.md) +- [Robustness](./robustness.md) +- [Runtime error checking](./run-time-error-checking.md) +- [Searching and sorting](./searching-and-sorting.md) +- [String manipulation](./string-manipulation-crt.md) +- [System calls](./system-calls.md) +- [Time management](./time-management.md) ## See also -[C Run-Time Library Reference](../c-runtime-library/c-run-time-library-reference.md)
+[C runtime library reference](./c-run-time-library-reference.md) diff --git a/docs/c-runtime-library/sal-annotations.md b/docs/c-runtime-library/sal-annotations.md index 40aaed2477d..5c145f5c570 100644 --- a/docs/c-runtime-library/sal-annotations.md +++ b/docs/c-runtime-library/sal-annotations.md @@ -1,17 +1,16 @@ --- title: "SAL Annotations" description: "A brief description of the Microsoft source-code annotation language (SAL)." -ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.date: 11/04/2016 +ms.topic: "concept-article" helpviewer_keywords: ["__z annotation", "ref annotation", "_opt annotation", "__checkreturn annotatioin", "__deref_opt annotation", "deref_opt annotation", "__deref annotation", "__in annotation", "annotations [C++]", "z annotation", "_inout annotation", "__ref annotation", "full annotation", "_in annotation", "_ref annotation", "__out annotation", "_ecount annotation", "SAL annotations", "__opt annotation", "inout annotation", "in annotation", "_CA_SHOULD_CHECK_RETURN", "__bcount annotation", "_full annotation", "_bcount annotation", "deref annotation", "part annotation", "_out annotation", "__nz annotation", "__part annotation", "opt annotation", "__full annotation", "_nz annotation", "_z annotation", "out annotation", "__ecount annotation", "__inout annotation", "SAL annotations, _CA_SHOULD_CHECK_RETURN", "_deref_opt annotation", "_deref annotation", "nz annotation", "_part annotation", "ecount annotation", "bcount annotation"] -ms.assetid: 81893638-010c-41a0-9cb3-666fe360f3e0 --- -# SAL Annotations +# SAL annotations -If you examine the library header files, you may notice some unusual annotations, for example, `_In_z` and `_Out_z_cap_(_Size)`. These are examples of the Microsoft source-code annotation language (SAL), which provides a set of annotations to describe how a function uses its parameters, for example, the assumptions it makes about them and the guarantees it makes on finishing. The header file \ defines the annotations. +If you examine the library header files, you may notice some unusual annotations, for example, `_In_z_` and `_Out_z_cap_(_Size)`. These annotations are examples of the Microsoft source-code annotation language (SAL). SAL provides a set of annotations to describe how a function uses its parameters and return type. For example, it indicates the assumptions it makes about them and the guarantees it makes on finishing. The header file \ defines the annotations. -For more information about using SAL annotations in Visual Studio, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +For more information about using SAL annotations in Visual Studio, see [Using SAL annotations to reduce C/C++ code defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/sbcs-and-mbcs-data-types.md b/docs/c-runtime-library/sbcs-and-mbcs-data-types.md index baad2737c27..c2111a54b41 100644 --- a/docs/c-runtime-library/sbcs-and-mbcs-data-types.md +++ b/docs/c-runtime-library/sbcs-and-mbcs-data-types.md @@ -1,30 +1,30 @@ --- title: "SBCS and MBCS Data Types" description: "How to represent single and multibyte characters in the Microsoft C runtime." -ms.topic: "conceptual" +ms.topic: "how-to" ms.date: "04/11/2018" -f1_keywords: ["MBCS", "SBCS"] +f1_keywords: ["_MBCS", "MBCS", "SBCS"] helpviewer_keywords: ["SBCS and MBCS data types", "data types [C], MBCS and SBCS"] ms.assetid: 4c3ef9da-e397-48d4-800e-49dba36db171 --- -# SBCS and MBCS Data Types +# SBCS and MBCS data types -Any Microsoft MBCS run-time library routine that handles only 1 multibyte character or 1 byte of a multibyte character expects an **`unsigned int`** argument (where 0x00 <= character value <= 0xFFFF and 0x00 <= byte value <= 0xFF). An MBCS routine that handles multibyte bytes or characters in a string context expects a multibyte-character string to be represented as an **`unsigned char`** pointer. +Any Microsoft MBCS run-time library routine that handles only a single multibyte character, or a single byte of a multibyte character, expects an **`unsigned int`** argument (where 0x0000 <= character value <= 0xFFFF and 0x00 <= byte value <= 0xFF). An MBCS routine that handles multibyte bytes or characters in a string context expects a multibyte-character string to be represented as an **`unsigned char`** pointer. > [!CAUTION] > Each byte of a multibyte character can be represented in an 8-bit **`char`**. However, an SBCS or MBCS single-byte character of type **`char`** with a value greater than 0x7F is negative. When such a character is converted directly to an **`int`** or a **`long`**, the result is sign-extended by the compiler and can therefore yield unexpected results. It's best to represent a byte of a multibyte character as an 8-bit **`unsigned char`**. Or, to avoid a negative result, convert a single-byte character of type **`char`** to an **`unsigned char`** before converting it to an **`int`** or a **`long`**. -Because some SBCS string-handling functions take (signed) **`char`**\* parameters, a type mismatch compiler warning will result when **_MBCS** is defined. There are three ways to avoid this warning, listed in order of efficiency: +Because some SBCS string-handling functions take (signed) **`char`**\* parameters, a type mismatch compiler warning will result when `_MBCS` is defined. There are three ways to avoid this warning, listed in order of efficiency: -1. Use the type-safe inline functions in TCHAR.H. This is the default behavior. +1. Use the type-safe inline functions in TCHAR.H. This behavior is the default. -1. Use the direct macros in TCHAR.H by defining **_MB_MAP_DIRECT** on the command line. If you do this, you must manually match types. This is the fastest method but isn't type-safe. +1. Use the direct macros in TCHAR.H by defining `_MB_MAP_DIRECT` on the command line. If you do, you must manually match types. This method is the fastest but isn't type-safe. -1. Use the type-safe statically linked library functions in TCHAR.H. To do so, define the constant **_NO_INLINING** on the command line. This is the slowest method, but the most type-safe. +1. Use the type-safe statically linked library functions in TCHAR.H. To do so, define the constant `_NO_INLINING` on the command line. This method is the slowest, but the most type-safe. ## See also -[Internationalization](../c-runtime-library/internationalization.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/scanf-type-field-characters.md b/docs/c-runtime-library/scanf-type-field-characters.md index df7e521c5b4..f8fbb3cff25 100644 --- a/docs/c-runtime-library/scanf-type-field-characters.md +++ b/docs/c-runtime-library/scanf-type-field-characters.md @@ -4,7 +4,7 @@ title: "scanf Type Field Characters" ms.date: "11/04/2016" helpviewer_keywords: ["scanf function, type field characters"] --- -# `scanf` Type Field Characters +# `scanf` type field characters The following information applies to any of the `scanf` family of functions, including the secure versions, such as `scanf_s`. @@ -12,25 +12,25 @@ The `type` character is the only required format field; it appears after any opt ### `type` Characters for `scanf` functions -|Character|Type of input expected|Type of argument|Size argument in secure version?| -|---------------|----------------------------|----------------------|--------------------------------------| -|`c`|Character. When used with `scanf` functions, specifies single-byte character; when used with `wscanf` functions, specifies wide character. White-space characters that are ordinarily skipped are read when `c` is specified. Unlike with other type fields, the field width specifier indicates the exact number of characters, not the maximum. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`.|Pointer to **`char`** when used with `scanf` functions, pointer to **`wchar_t`** when used with `wscanf` functions.|Required. Size does not include space for a null terminator.| -|`C`|Opposite size character. When used with `scanf` functions, specifies wide character; when used with `wscanf` functions, specifies single-byte character. White-space characters that are ordinarily skipped are read when `C` is specified. Unlike with other type fields, the field width specifier indicates the exact number of characters, not the maximum. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`.|Pointer to **`wchar_t`** when used with `scanf` functions, pointer to **`char`** when used with `wscanf` functions.|Required. Size argument does not include space for a null terminator.| -|`d`|Decimal integer.|Pointer to **`int`**.|No.| -|`i`|An integer. Hexadecimal if the input string begins with "0x" or "0X", octal if the string begins with "0", otherwise decimal.|Pointer to **`int`**.|No.| -|`o`|Octal integer.|Pointer to **`int`**.|No.| -|`p`|A pointer address in hexadecimal digits. The maximum number of digits read depends on the size of a pointer (32 or 64 bits), which depends on the machine architecture. "0x" or "0X" are accepted as prefixes.|Pointer to **`void*`**.|No.| -|`u`|Unsigned decimal integer.|Pointer to **`unsigned int`**.|No.| -|`x`|Hexadecimal integer.|Pointer to **`int`**.|No.| -|`e`, `E`, `f`, `F`, `g`, `G`|Floating-point value consisting of optional sign (+ or -), series of one or more decimal digits containing decimal point, and optional exponent ("e" or "E") followed by an optionally signed integer value.|Pointer to **`float`**.|No.| -|`a`, `A`|Floating-point value consisting of a series of one or more hexadecimal digits containing an optional decimal point, and an exponent ("p" or "P") followed by a decimal value.|Pointer to **`float`**.|No.| -|`n`|No input read from stream or buffer.|Pointer to **`int`**, into which is stored number of characters successfully read from stream or buffer up to that point in current call to `scanf` functions or `wscanf` functions.|No.| -|`s`|String, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [`scanf` Width Specification](../c-runtime-library/scanf-width-specification.md).|When used with `scanf` functions, signifies single-byte character array; when used with `wscanf` functions, signifies wide-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended.|Required. Size includes space for a null terminator.| -|`S`|Opposite-size character string, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [`scanf` Width Specification](../c-runtime-library/scanf-width-specification.md).|When used with `scanf` functions, signifies wide-character array; when used with `wscanf` functions, signifies single-byte-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended.|Required. Size includes space for a null terminator.| - -The size arguments, if required, should be passed in the parameter list immediately following the argument they apply to. For example, the following code: - -``` +| Character | Type of input expected | Type of argument | Size argument in secure version? | +|---|---|---|---| +| `c` | Character. When used with `scanf` functions, specifies single-byte character; when used with `wscanf` functions, specifies wide character. White-space characters that are ordinarily skipped are read when `c` is specified. Unlike with other type fields, the field width specifier indicates the exact number of characters, not the maximum. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`. | Pointer to **`char`** when used with `scanf` functions, pointer to **`wchar_t`** when used with `wscanf` functions. | Required. Size doesn't include space for a null terminator. | +| `C` | Opposite size character. When used with `scanf` functions, specifies wide character; when used with `wscanf` functions, specifies single-byte character. White-space characters that are ordinarily skipped are read when `C` is specified. Unlike with other type fields, the field width specifier indicates the exact number of characters, not the maximum. To read next non-white-space single-byte character, use `%1s`; to read next non-white-space wide character, use `%1ws`. | Pointer to **`wchar_t`** when used with `scanf` functions, pointer to **`char`** when used with `wscanf` functions. | Required. Size argument doesn't include space for a null terminator. | +| `d` | Decimal integer. | Pointer to **`int`**. | No. | +| `i` | An integer. Hexadecimal if the input string begins with "0x" or "0X", octal if the string begins with "0", otherwise decimal. | Pointer to **`int`**. | No. | +| `o` | Octal integer. | Pointer to **`int`**. | No. | +| `p` | A pointer address in hexadecimal digits. The maximum number of digits read depends on the size of a pointer (32 bits or 64 bits), which depends on the machine architecture. "0x" or "0X" are accepted as prefixes. | Pointer to **`void*`**. | No. | +| `u` | Unsigned decimal integer. | Pointer to **`unsigned int`**. | No. | +| `x` | Hexadecimal integer. | Pointer to **`int`**. | No. | +| `e`, `E`, `f`, `F`, `g`, `G` | Floating-point value consisting of optional sign (+ or -), series of one or more decimal digits containing decimal point, and optional exponent ("e" or "E") followed by an optionally signed integer value. | Pointer to **`float`**. | No. | +| `a`, `A` | Floating-point value consisting of a series of one or more hexadecimal digits containing an optional decimal point, and an exponent ("p" or "P") followed by a decimal value. | Pointer to **`float`**. | No. | +| `n` | No input read from stream or buffer. | Pointer to **`int`**, into which is stored number of characters successfully read from stream or buffer up to that point in current call to `scanf` functions or `wscanf` functions. | No. | +| `s` | String, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [`scanf` Width Specification](./scanf-width-specification.md). | When used with `scanf` functions, signifies single-byte character array; when used with `wscanf` functions, signifies wide-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended. | Required. Size includes space for a null terminator. | +| `S` | Opposite-size character string, up to first white-space character (space, tab or newline). To read strings not delimited by space characters, use set of square brackets (`[ ]`), as discussed in [`scanf` Width Specification](./scanf-width-specification.md). | When used with `scanf` functions, signifies wide-character array; when used with `wscanf` functions, signifies single-byte-character array. In either case, character array must be large enough for input field plus terminating null character, which is automatically appended. | Required. Size includes space for a null terminator. | + +The size arguments, if necessary, should be passed in the parameter list immediately following the argument they apply to. For example, the following code: + +```C char string1[11], string2[9]; scanf_s("%10s %8s", string1, 11, string2, 9); ``` @@ -39,15 +39,15 @@ reads a string with a maximum length of 10 into `string1`, and a string with a m The format string can handle single-byte or wide character input regardless of whether the single-byte character or wide-character version of the function is used. Thus, to read single-byte or wide characters with `scanf` functions and `wscanf` functions, use format specifiers as follows. -|To read character as|Use this function|With these format specifiers| -|--------------------------|-----------------------|----------------------------------| -|single byte|`scanf` functions|`c`, `hc`, or `hC`| -|single byte|`wscanf` functions|`C`, `hc`, or `hC`| -|wide|`wscanf` functions|`c`, `lc`, or `lC`| -|wide|`scanf` functions|`C`, `lc`, or `lC`| +| To read character as | Use this function | With these format specifiers | +|---|---|---| +| single byte | `scanf` functions | `c`, `hc`, or `hC` | +| single byte | `wscanf` functions | `C`, `hc`, or `hC` | +| wide | `wscanf` functions | `c`, `lc`, or `lC` | +| wide | `scanf` functions | `C`, `lc`, or `lC` | To scan strings with `scanf` functions, and `wscanf` functions, use the above table with format type-specifiers `s` and `S` instead of `c` and `C`. ## See also -[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md) +[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md) diff --git a/docs/c-runtime-library/scanf-width-specification.md b/docs/c-runtime-library/scanf-width-specification.md index b92ecd91664..10def004d79 100644 --- a/docs/c-runtime-library/scanf-width-specification.md +++ b/docs/c-runtime-library/scanf-width-specification.md @@ -26,33 +26,33 @@ If the *`width`* field isn't used, `scanf_s` attempts to read the entire token i ## The size prefix -The optional prefixes **`h`**, **`hh`**, **`l`**, **`ll`**, **`I64`**, and **`L`** indicate the size of the `argument` (long or short, single-byte character or wide character, depending upon the type character that they modify). These format-specification characters are used with type characters in `scanf` or `wscanf` functions to specify interpretation of arguments as shown in the following table. The type prefix **`I64`** is a Microsoft extension and isn't compatible with Standard C. The type characters and their meanings are described in the "Type Characters for scanf functions" table in [`scanf` Type Field Characters](../c-runtime-library/scanf-type-field-characters.md). +The optional prefixes **`h`**, **`hh`**, **`l`**, **`ll`**, **`I64`**, and **`L`** indicate the size of the `argument` (long or short, single-byte character or wide character, depending upon the type character that they modify). These format-specification characters are used with type characters in `scanf` or `wscanf` functions to specify interpretation of arguments as shown in the following table. The type prefix **`I64`** is a Microsoft extension and isn't compatible with Standard C. The type characters and their meanings are described in the "Type Characters for scanf functions" table in [`scanf` type field characters](./scanf-type-field-characters.md). > [!NOTE] > The **`h`**, **`l`**, and **`L`** prefixes are Microsoft extensions when used with data of type **`char`**. ### Size prefixes for `scanf` and `wscanf` format-type specifiers -|To specify|Use prefix|With type specifier| -|----------------|----------------|-------------------------| -|**`double`**|**`l`**|**`e`**, **`E`**, **`f`**, **`g`**, or **`G`**| -|**`long double`** (same as **`double`**)|**`L`**|**`e`**, **`E`**, **`f`**, **`g`**, or **`G`**| -|**`long int`**|**`l`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`long unsigned int`**|**`l`**|**`u`**| -|**`long long`**|**`ll`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`short int`**|**`h`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`short unsigned int`**|**`h`**|**`u`**| -|**`char`**|**`hh`**|**`d`**, **`i`**, **`o`**, **`x`**, or **`X`**| -|**`unsigned char`**|**`hh`**|**`u`**| -|**`int64`**|**`I64`**|**`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`**| -|Single-byte character with `scanf`|**`h`**|**`c`** or **`C`**| -|Single-byte character with `wscanf`|**`h`**|**`c`** or **`C`**| -|Wide character with `scanf`|**`l`**|**`c`** or **`C`**| -|Wide character with `wscanf`|**`l`**|**`c`**, or **`C`**| -|Single-byte character string with `scanf`|**`h`**|**`s`** or **`S`**| -|Single-byte character string with `wscanf`|**`h`**|**`s`** or **`S`**| -|Wide character string with `scanf`|**`l`**|**`s`** or **`S`**| -|Wide character string with `wscanf`|**`l`**|**`s`** or **`S`**| +| To specify | Use prefix | With type specifier | +|---|---|---| +| **`double`** | **`l`** | **`e`**, **`E`**, **`f`**, **`g`**, or **`G`** | +| **`long double`** (same as **`double`**) | **`L`** | **`e`**, **`E`**, **`f`**, **`g`**, or **`G`** | +| **`long int`** | **`l`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`long unsigned int`** | **`l`** | **`u`** | +| **`long long`** | **`ll`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`short int`** | **`h`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`short unsigned int`** | **`h`** | **`u`** | +| **`char`** | **`hh`** | **`d`**, **`i`**, **`o`**, **`x`**, or **`X`** | +| **`unsigned char`** | **`hh`** | **`u`** | +| **`int64`** | **`I64`** | **`d`**, **`i`**, **`o`**, **`u`**, **`x`**, or **`X`** | +| Single-byte character with `scanf` | **`h`** | **`c`** or **`C`** | +| Single-byte character with `wscanf` | **`h`** | **`c`** or **`C`** | +| Wide character with `scanf` | **`l`** | **`c`** or **`C`** | +| Wide character with `wscanf` | **`l`** | **`c`**, or **`C`** | +| Single-byte character string with `scanf` | **`h`** | **`s`** or **`S`** | +| Single-byte character string with `wscanf` | **`h`** | **`s`** or **`S`** | +| Wide character string with `scanf` | **`l`** | **`s`** or **`S`** | +| Wide character string with `wscanf` | **`l`** | **`s`** or **`S`** | The following examples use **`h`** and **`l`** with `scanf_s` functions and `wscanf_s` functions: @@ -89,7 +89,7 @@ For whatever reason, when the `scanf` function stops reading an input field, the ## See also -[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)
-[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)
-[Format Specification Fields: `scanf` and `wscanf` Functions](../c-runtime-library/format-specification-fields-scanf-and-wscanf-functions.md)
-[`scanf` Type Field Characters](../c-runtime-library/scanf-type-field-characters.md)
+[`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[Format specification fields: `scanf` and `wscanf` functions](./format-specification-fields-scanf-and-wscanf-functions.md)\ +[`scanf` type field characters](./scanf-type-field-characters.md) diff --git a/docs/c-runtime-library/searching-and-sorting.md b/docs/c-runtime-library/searching-and-sorting.md index 1eb7dbdb238..706301f3b0a 100644 --- a/docs/c-runtime-library/searching-and-sorting.md +++ b/docs/c-runtime-library/searching-and-sorting.md @@ -5,23 +5,23 @@ ms.date: "11/04/2016" helpviewer_keywords: ["sorting data", "data [CRT], searching", "searching [C++], CRT search functions", "searching [C++]"] ms.assetid: 15e984f0-e155-46f5-8542-51c458792f54 --- -# Searching and Sorting +# Searching and sorting Use the following functions for searching and sorting. -## Searching and Sorting Functions +## Searching and sorting functions -|Function|Search or Sort| -|--------------|--------------------| -|[bsearch](../c-runtime-library/reference/bsearch.md)|Binary search| -|[bsearch_s](../c-runtime-library/reference/bsearch-s.md)|A more secure version of **bsearch**| -|[_lfind](../c-runtime-library/reference/lfind.md)|Linear search for given value| -|[_lfind_s](../c-runtime-library/reference/lfind-s.md)|A more secure version of **_lfind**| -|[_lsearch](../c-runtime-library/reference/lsearch.md)|Linear search for given value, which is added to array if not found| -|[_lsearch_s](../c-runtime-library/reference/lsearch-s.md)|A more secure version of **_lsearch**| -|[qsort](../c-runtime-library/reference/qsort.md)|Quick sort| -|[qsort_s](../c-runtime-library/reference/qsort-s.md)|A more secure version of **qsort**| +| Function | Search or Sort | +|---|---| +| [`bsearch`](./reference/bsearch.md) | Binary search | +| [`bsearch_s`](./reference/bsearch-s.md) | A more secure version of `bsearch` | +| [`_lfind`](./reference/lfind.md) | Linear search for given value | +| [`_lfind_s`](./reference/lfind-s.md) | A more secure version of `_lfind` | +| [`_lsearch`](./reference/lsearch.md) | Linear search for given value, which is added to array if not found | +| [`_lsearch_s`](./reference/lsearch-s.md) | A more secure version of `_lsearch` | +| [`qsort`](./reference/qsort.md) | Quick sort | +| [`qsort_s`](./reference/qsort-s.md) | A more secure version of `qsort` | ## See also -[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/secure-template-overloads.md b/docs/c-runtime-library/secure-template-overloads.md index 6b42b4911c5..99f5ab2d923 100644 --- a/docs/c-runtime-library/secure-template-overloads.md +++ b/docs/c-runtime-library/secure-template-overloads.md @@ -2,12 +2,12 @@ title: "Secure Template Overloads" description: "A description of Microsoft C runtime template overloads that provide security-enhanced functions." ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: ["_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES", "_CRT_SECURE_CPP_OVERLOAD_SECURE_NAMES", "_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT"] helpviewer_keywords: ["_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES", "_CRT_SECURE_CPP_OVERLOAD_SECURE_NAMES", "_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT", "secure template overloads"] ms.assetid: 562741d0-39c0-485e-8529-73d740f29f8f --- -# Secure Template Overloads +# Secure template overloads Microsoft has deprecated many C Runtime library (CRT) functions in favor of security-enhanced versions. For example, `strcpy_s` is the more secure replacement for `strcpy`. The deprecated functions are common sources of security bugs, because they don't prevent operations that can overwrite memory. By default, the compiler produces a deprecation warning when you use one of these functions. The CRT provides C++ template overloads for these functions to help ease the transition to the more secure variants. @@ -25,7 +25,7 @@ char szBuf[10]; strcpy_s(szBuf, 10, "test"); // security-enhanced _s function ``` -The template overloads provide additional choices. If you define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` to 1, this enables template overloads of standard CRT functions that call the more secure variants automatically. If `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is 1, then no changes to your code are necessary. Behind the scenes, the call to `strcpy` is changed to a call to `strcpy_s` with the size argument supplied automatically. +The template overloads provide more choices. If you define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` to 1, it enables template overloads of standard CRT functions that call the more secure variants automatically. If `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is 1, then no changes to your code are necessary. Behind the scenes, the call to `strcpy` is changed to a call to `strcpy_s` with the size argument supplied automatically. ```cpp #define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 @@ -36,7 +36,7 @@ char szBuf[10]; strcpy(szBuf, "test"); // ==> strcpy_s(szBuf, 10, "test") ``` -The macro `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` doesn't affect the functions that take a count, such as `strncpy`. To enable template overloads for the count functions, define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` to 1. Before doing so, however, make sure that your code passes the count of characters, not the size of the buffer (a common mistake). Also, code that explicitly writes a null terminator at the end of the buffer after the function call is unnecessary if the secure variant is called. If you need truncation behavior, see [_TRUNCATE](../c-runtime-library/truncate.md). +The macro `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` doesn't affect the functions that take a count, such as `strncpy`. To enable template overloads for the count functions, define `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` to 1. Before doing so, however, make sure that your code passes the count of characters, not the size of the buffer (a common mistake). Also, code that explicitly writes a null terminator at the end of the buffer after the function call is unnecessary if the secure variant is called. If you need truncation behavior, see [`_TRUNCATE`](./truncate.md). > [!NOTE] > The macro `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` requires that `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is also defined as 1. If `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` is defined as 1 and `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` is defined as 0, the application will not perform any template overloads. @@ -56,7 +56,7 @@ Only the name of the function needs to be changed (by adding "_s"); the template By default, `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` and `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES_COUNT` are defined as 0 (disabled) and `_CRT_SECURE_CPP_OVERLOAD_SECURE_NAMES` is defined as 1 (enabled). -These template overloads only work for static arrays. Dynamically allocated buffers require additional source code changes. Revisiting the above examples: +The template overloads only work for static arrays. Dynamically allocated buffers require other source code changes. Revisiting the above examples: ```cpp #define _CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES 1 @@ -68,7 +68,7 @@ strcpy(szBuf, "test"); // still deprecated; change it to // strcpy_s(szBuf, 10, "test"); ``` -And this: +And this example: ```cpp #define _CRT_SECURE_CPP_OVERLOAD_SECURE_NAMES 1 @@ -82,5 +82,5 @@ strcpy_s(szBuf, "test"); // doesn't compile; change it to ## See also -[Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md)
-[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[Security features in the CRT](./security-features-in-the-crt.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md b/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md index d86139ec35e..30a570fbaaa 100644 --- a/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md +++ b/docs/c-runtime-library/security-enhanced-versions-of-crt-functions.md @@ -5,92 +5,92 @@ ms.date: "03/21/2018" helpviewer_keywords: ["security [CRT]", "security-enhanced CRT", "CRT, security enhancements"] ms.assetid: f87e5a01-4cb2-4379-9e8f-d4693828c55a --- -# Security-Enhanced Versions of CRT Functions +# Security-enhanced versions of CRT functions -More secure versions of run-time library routines are available. For further information concerning security enhancements in the CRT, see [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). +More secure versions of run-time library routines are available. For more information about security enhancements in the CRT, see [Security features in the CRT](./security-features-in-the-crt.md). ## Secure functions -|CRT Function|Security enhanced function|Use| -|------------------|--------------------------------|---------| -|[_access, _waccess](../c-runtime-library/reference/access-waccess.md)|[_access_s, _waccess_s](../c-runtime-library/reference/access-s-waccess-s.md)|Determine file-access permission| -|[_alloca](../c-runtime-library/reference/alloca.md)|[_malloca](../c-runtime-library/reference/malloca.md)|Allocate memory on the stack| -|[asctime, _wasctime](../c-runtime-library/reference/asctime-wasctime.md)|[asctime_s, _wasctime_s](../c-runtime-library/reference/asctime-s-wasctime-s.md)|Convert time from type `struct tm` to character string| -|[bsearch](../c-runtime-library/reference/bsearch.md)|[bsearch_s](../c-runtime-library/reference/bsearch-s.md)|Perform a binary search of a sorted array| -|[_cgets, _cgetws](../c-runtime-library/cgets-cgetws.md)|[_cgets_s, _cgetws_s](../c-runtime-library/reference/cgets-s-cgetws-s.md)|Get a character string from the console| -|[_chsize](../c-runtime-library/reference/chsize.md)|[_chsize_s](../c-runtime-library/reference/chsize-s.md)|Change the size of a file| -|[clearerr](../c-runtime-library/reference/clearerr.md)|[clearerr_s](../c-runtime-library/reference/clearerr-s.md)|Reset the error indicator for a stream| -|[_control87, _controlfp, \__control87_2](../c-runtime-library/reference/control87-controlfp-control87-2.md)|[_controlfp_s](../c-runtime-library/reference/controlfp-s.md)|Get and set the floating-point control word| -|[_cprintf, _cprintf_l, _cwprintf, _cwprintf_l](../c-runtime-library/reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md)|[_cprintf_s, _cprintf_s_l, _cwprintf_s, _cwprintf_s_l](../c-runtime-library/reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md)|Format and print to the console| -|[_cscanf, _cscanf_l, _cwscanf, _cwscanf_l](../c-runtime-library/reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md)|[_cscanf_s, _cscanf_s_l, _cwscanf_s, _cwscanf_s_l](../c-runtime-library/reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md)|Read formatted data from the console| -|[ctime, _ctime32, _ctime64, _wctime, _wctime32, _wctime64](../c-runtime-library/reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md)|[_ctime_s, _ctime32_s, _ctime64_s, _wctime_s, _wctime32_s, _wctime64_s](../c-runtime-library/reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md)|Convert time from type `time_t`, `__time32_t` or `__time64_t` to character string| -|[_ecvt](../c-runtime-library/reference/ecvt.md)|[_ecvt_s](../c-runtime-library/reference/ecvt-s.md)|Convert a **`double`** number to a string| -|[_fcvt](../c-runtime-library/reference/fcvt.md)|[_fcvt_s](../c-runtime-library/reference/fcvt-s.md)|Converts a floating-point number to a string| -|[fopen, _wfopen](../c-runtime-library/reference/fopen-wfopen.md)|[fopen_s, _wfopen_s](../c-runtime-library/reference/fopen-s-wfopen-s.md)|Open a file| -|[fprintf, _fprintf_l, fwprintf, _fwprintf_l](../c-runtime-library/reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md)|[fprintf_s, _fprintf_s_l, fwprintf_s, _fwprintf_s_l](../c-runtime-library/reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md)|Print formatted data to a stream| -|[fread](../c-runtime-library/reference/fread.md)|[fread_s](../c-runtime-library/reference/fread-s.md)|Read from a file| -|[_fread_nolock](../c-runtime-library/reference/fread-nolock.md)|[_fread_nolock_s](../c-runtime-library/reference/fread-nolock-s2.md)|Read from a file without using a multi-thread write lock| -|[freopen, _wfreopen](../c-runtime-library/reference/freopen-wfreopen.md)|[freopen_s, _wfreopen_s](../c-runtime-library/reference/freopen-s-wfreopen-s.md)|Reopen the file| -|[fscanf, _fscanf_l, fwscanf, _fwscanf_l](../c-runtime-library/reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md)|[fscanf_s, _fscanf_s_l, fwscanf_s, _fwscanf_s_l](../c-runtime-library/reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md)|Read formatted data from a stream| -|[_ftime, _ftime32, _ftime64](../c-runtime-library/reference/ftime-ftime32-ftime64.md)|[_ftime_s, _ftime32_s, _ftime64_s](../c-runtime-library/reference/ftime-s-ftime32-s-ftime64-s.md)|Get the current time| -|[_gcvt](../c-runtime-library/reference/gcvt.md)|[_gcvt_s](../c-runtime-library/reference/gcvt-s.md)|Convert a floating-point value to a string, and store it in a buffer| -|[getenv, _wgetenv](../c-runtime-library/reference/getenv-wgetenv.md)|[getenv_s, _wgetenv_s](../c-runtime-library/reference/getenv-s-wgetenv-s.md)|Get a value from the current environment.| -|[gets, getws](../c-runtime-library/gets-getws.md)|[gets_s, _getws_s](../c-runtime-library/reference/gets-s-getws-s.md)|Get a line from the `stdin` stream| -|[gmtime, _gmtime32, _gmtime64](../c-runtime-library/reference/gmtime-gmtime32-gmtime64.md)|[_gmtime32_s, _gmtime64_s](../c-runtime-library/reference/gmtime-s-gmtime32-s-gmtime64-s.md)|Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm`| -|[itoa, _itoa, ltoa, _ltoa, ultoa, _ultoa, _i64toa, _ui64toa, _itow, _ltow, _ultow, _i64tow, _ui64tow](../c-runtime-library/reference/itoa-itow.md)|[_itoa_s, _ltoa_s, _ultoa_s, _i64toa_s, _ui64toa_s, _itow_s, _ltow_s, _ultow_s, _i64tow_s, _ui64tow_s](../c-runtime-library/reference/itoa-s-itow-s.md)|Convert an integral type to a string| -|[_lfind](../c-runtime-library/reference/lfind.md)|[_lfind_s](../c-runtime-library/reference/lfind-s.md)|Perform a linear search for the specified key| -|[localtime, _localtime32, _localtime64](../c-runtime-library/reference/localtime-localtime32-localtime64.md)|[localtime_s, _localtime32_s, _localtime64_s](../c-runtime-library/reference/localtime-s-localtime32-s-localtime64-s.md)|Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm` with local correction| -|[_lsearch](../c-runtime-library/reference/lsearch.md)|[_lsearch_s](../c-runtime-library/reference/lsearch-s.md)|Perform a linear search for a value; adds to end of list if not found| -|[_makepath, _wmakepath](../c-runtime-library/reference/makepath-wmakepath.md)|[_makepath_s, _wmakepath_s](../c-runtime-library/reference/makepath-s-wmakepath-s.md)|Create a path name from components| -|[_mbccpy, _mbccpy_l](../c-runtime-library/reference/mbccpy-mbccpy-l.md)|[_mbccpy_s, _mbccpy_s_l](../c-runtime-library/reference/mbccpy-s-mbccpy-s-l.md)|Copy a multibyte character from one string to another string| -|[_mbsnbcat, _mbsnbcat_l](../c-runtime-library/reference/mbsnbcat-mbsnbcat-l.md)|[_mbsnbcat_s, _mbsnbcat_s_l](../c-runtime-library/reference/mbsnbcat-s-mbsnbcat-s-l.md)|Append, at most, the first *n* bytes of one multibyte character string to another| -|[_mbsnbcpy, _mbsnbcpy_l](../c-runtime-library/reference/mbsnbcpy-mbsnbcpy-l.md)|[_mbsnbcpy_s, _mbsnbcpy_s_l](../c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md)|Copy *n* bytes of a string to a destination string| -|[_mbsnbset, _mbsnbset_l](../c-runtime-library/reference/mbsnbset-mbsnbset-l.md)|[_mbsnbset_s, _mbsnbset_s_l](../c-runtime-library/reference/mbsnbset-s-mbsnbset-s-l.md)|Set the first *n* bytes of a string to a specified character| -|[mbsrtowcs](../c-runtime-library/reference/mbsrtowcs.md)|[mbsrtowcs_s](../c-runtime-library/reference/mbsrtowcs-s.md)|Convert a multibyte character string to a corresponding wide character string| -|[mbstowcs, _mbstowcs_l](../c-runtime-library/reference/mbstowcs-mbstowcs-l.md)|[mbstowcs_s, _mbstowcs_s_l](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)|Convert a sequence of multibyte characters to a corresponding sequence of wide characters| -|[memcpy, wmemcpy](../c-runtime-library/reference/memcpy-wmemcpy.md)|[memcpy_s, wmemcpy_s](../c-runtime-library/reference/memcpy-s-wmemcpy-s.md)|Copy characters between buffers| -|[memmove, wmemmove](../c-runtime-library/reference/memmove-wmemmove.md)|[memmove_s, wmemmove_s](../c-runtime-library/reference/memmove-s-wmemmove-s.md)|Move one buffer to another| -|[_mktemp, _wmktemp](../c-runtime-library/reference/mktemp-wmktemp.md)|[_mktemp_s, _wmktemp_s](../c-runtime-library/reference/mktemp-s-wmktemp-s.md)|Create a unique filename| -|[printf, _printf_l, wprintf, _wprintf_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)|[printf_s, _printf_s_l, wprintf_s, _wprintf_s_l](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)|Print formatted output to the standard output stream| -|[_putenv, _wputenv](../c-runtime-library/reference/putenv-wputenv.md)|[_putenv_s, _wputenv_s](../c-runtime-library/reference/putenv-s-wputenv-s.md)|Create, modify, or remove environment variables| -|[qsort](../c-runtime-library/reference/qsort.md)|[qsort_s](../c-runtime-library/reference/qsort-s.md)|Perform a quick sort| -|[rand](../c-runtime-library/reference/rand.md)|[rand_s](../c-runtime-library/reference/rand-s.md)|Generate a pseudorandom number| -|[scanf, _scanf_l, wscanf, _wscanf_l](../c-runtime-library/reference/scanf-scanf-l-wscanf-wscanf-l.md)|[scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)|Read formatted data from the standard input stream| -|[_searchenv, _wsearchenv](../c-runtime-library/reference/searchenv-wsearchenv.md)|[_searchenv_s, _wsearchenv_s](../c-runtime-library/reference/searchenv-s-wsearchenv-s.md)|Search for a file using environment paths| -|[snprintf, _snprintf, _snprintf_l, _snwprintf, _snwprintf_l](../c-runtime-library/reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md)|[_snprintf_s, _snprintf_s_l, _snwprintf_s, _snwprintf_s_l](../c-runtime-library/reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md)|Write formatted data to a string| -|[_snscanf, _snscanf_l, _snwscanf, _snwscanf_l](../c-runtime-library/reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md)|[_snscanf_s, _snscanf_s_l, _snwscanf_s, _snwscanf_s_l](../c-runtime-library/reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md)|Read formatted data of a specified length from a string.| -|[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)|[_sopen_s, _wsopen_s](../c-runtime-library/reference/sopen-s-wsopen-s.md)|Open a file for sharing| -|[_splitpath, _wsplitpath](../c-runtime-library/reference/splitpath-wsplitpath.md)|[_splitpath_s, _wsplitpath_s](../c-runtime-library/reference/splitpath-s-wsplitpath-s.md)|Break a path name into components| -|[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)|[sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)|Write formatted data to a string| -|[sscanf, _sscanf_l, swscanf, _swscanf_l](../c-runtime-library/reference/sscanf-sscanf-l-swscanf-swscanf-l.md)|[sscanf_s, _sscanf_s_l, swscanf_s, _swscanf_s_l](../c-runtime-library/reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md)|Read formatted data from a string| -|[strcat, wcscat, _mbscat](../c-runtime-library/reference/strcat-wcscat-mbscat.md)|[strcat_s, wcscat_s, _mbscat_s](../c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md)|Append a string| -|[strcpy, wcscpy, _mbscpy](../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md)|[strcpy_s, wcscpy_s, _mbscpy_s](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md)|Copy a string| -|[_strdate, _wstrdate](../c-runtime-library/reference/strdate-wstrdate.md)|[_strdate_s, _wstrdate_s](../c-runtime-library/reference/strdate-s-wstrdate-s.md)|Return current system date as string| -|[strerror, _strerror, _wcserror, \__wcserror](../c-runtime-library/reference/strerror-strerror-wcserror-wcserror.md)|[strerror_s, _strerror_s, _wcserror_s, \__wcserror_s](../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md)|Get a system error message (`strerror`, `_wcserror`) or print a user-supplied error message (`_strerror`, `__wcserror`)| -|[_strlwr, _wcslwr, _mbslwr, _strlwr_l, _wcslwr_l, _mbslwr_l](../c-runtime-library/reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md)|[_strlwr_s, _strlwr_s_l, _mbslwr_s, _mbslwr_s_l, _wcslwr_s, _wcslwr_s_l](../c-runtime-library/reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md)|Convert a string to lowercase| -|[strncat, _strncat_l, wcsncat, _wcsncat_l, _mbsncat, _mbsncat_l](../c-runtime-library/reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md)|[strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md)|Append characters to a string| -|[strncpy, _strncpy_l, wcsncpy, _wcsncpy_l, _mbsncpy, _mbsncpy_l](../c-runtime-library/reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md)|[strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md)|Copy characters of one string to another| -|[_strnset, _strnset_l, _wcsnset, _wcsnset_l, _mbsnset, _mbsnset_l](../c-runtime-library/reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md)|[_strnset_s, _strnset_s_l, _wcsnset_s, _wcsnset_s_l, _mbsnset_s, _mbsnset_s_l](../c-runtime-library/reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md)|Set the first n characters of a string to the specified character| -|[_strset, _strset_l, _wcsset, _wcsset_l, _mbsset, _mbsset_l](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)|[_strset_s, _strset_s_l, _wcsset_s, _wcsset_s_l, _mbsset_s, _mbsset_s_l](../c-runtime-library/reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md)|Set all the characters of a string to the specified character| -|[_strtime, _wstrtime](../c-runtime-library/reference/strtime-wstrtime.md)|[_strtime_s, _wstrtime_s](../c-runtime-library/reference/strtime-s-wstrtime-s.md)|Return current system time as string| -|[strtok, _strtok_l, wcstok, _wcstok_l, _mbstok, _mbstok_l](../c-runtime-library/reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md)|[strtok_s, _strtok_s_l, wcstok_s, _wcstok_s_l, _mbstok_s, _mbstok_s_l](../c-runtime-library/reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md)|Find the next token in a string, using the current locale or a locale passed in| -|[_strupr, _strupr_l, _mbsupr, _mbsupr_l, _wcsupr_l, _wcsupr](../c-runtime-library/reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md)|[_strupr_s, _strupr_s_l, _mbsupr_s, _mbsupr_s_l, _wcsupr_s, _wcsupr_s_l](../c-runtime-library/reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md)|Convert a string to uppercase| -|[tmpfile](../c-runtime-library/reference/tmpfile.md)|[tmpfile_s](../c-runtime-library/reference/tmpfile-s.md)|Create a temporary file| -|[_tempnam, _wtempnam, tmpnam, _wtmpnam](../c-runtime-library/reference/tempnam-wtempnam-tmpnam-wtmpnam.md)|[tmpnam_s, _wtmpnam_s](../c-runtime-library/reference/tmpnam-s-wtmpnam-s.md)|Generate names you can use to create temporary files| -|[_umask](../c-runtime-library/reference/umask.md)|[_umask_s](../c-runtime-library/reference/umask-s.md)|Set the default file-permission mask| -|[_vcprintf, _vcprintf_l, _vcwprintf, _vcwprintf_l](../c-runtime-library/reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md)|[_vcprintf_s, _vcprintf_s_l, _vcwprintf_s, _vcwprintf_s_l](../c-runtime-library/reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md)|Write formatted output to the console using a pointer to a list of arguments| -|[vfprintf, _vfprintf_l, vfwprintf, _vfwprintf_l](../c-runtime-library/reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md)|[vfprintf_s, _vfprintf_s_l, vfwprintf_s, _vfwprintf_s_l](../c-runtime-library/reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vfscanf, vfwscanf](../c-runtime-library/reference/vfscanf-vfwscanf.md)|[vfscanf_s, vfwscanf_s](../c-runtime-library/reference/vfscanf-s-vfwscanf-s.md)|Read formatted data from a stream| -|[vprintf, _vprintf_l, vwprintf, _vwprintf_l](../c-runtime-library/reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md)|[vprintf_s, _vprintf_s_l, vwprintf_s, _vwprintf_s_l](../c-runtime-library/reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vscanf, vwscanf](../c-runtime-library/reference/vscanf-vwscanf.md)|[vscanf_s, vwscanf_s](../c-runtime-library/reference/vscanf-s-vwscanf-s.md)|Read formatted data from the standard input stream| -|[vsnprintf, _vsnprintf, _vsnprintf_l, _vsnwprintf, _vsnwprintf_l](../c-runtime-library/reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md)|[vsnprintf_s, _vsnprintf_s, _vsnprintf_s_l, _vsnwprintf_s, _vsnwprintf_s_l](../c-runtime-library/reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vsprintf, _vsprintf_l, vswprintf, _vswprintf_l, \__vswprintf_l](../c-runtime-library/reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md)|[vsprintf_s, _vsprintf_s_l, vswprintf_s, _vswprintf_s_l](../c-runtime-library/reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md)|Write formatted output using a pointer to a list of arguments| -|[vsscanf, vswscanf](../c-runtime-library/reference/vsscanf-vswscanf.md)|[vsscanf_s, vswscanf_s](../c-runtime-library/reference/vsscanf-s-vswscanf-s.md)|Read formatted data from a string| -|[wcrtomb](../c-runtime-library/reference/wcrtomb.md)|[wcrtomb_s](../c-runtime-library/reference/wcrtomb-s.md)|Convert a wide character into its multibyte character representation| -|[wcsrtombs](../c-runtime-library/reference/wcsrtombs.md)|[wcsrtombs_s](../c-runtime-library/reference/wcsrtombs-s.md)|Convert a wide character string to its multibyte character string representation| -|[wcstombs, _wcstombs_l](../c-runtime-library/reference/wcstombs-wcstombs-l.md)|[wcstombs_s, _wcstombs_s_l](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)|Convert a sequence of wide characters to a corresponding sequence of multibyte characters| -|[wctomb, _wctomb_l](../c-runtime-library/reference/wctomb-wctomb-l.md)|[wctomb_s, _wctomb_s_l](../c-runtime-library/reference/wctomb-s-wctomb-s-l.md)|Convert a wide character to the corresponding multibyte character| +| CRT Function | Security enhanced function | Use | +|---|---|---| +| [`_access`, `_waccess`](./reference/access-waccess.md) | [`_access_s`, `_waccess_s`](./reference/access-s-waccess-s.md) | Determine file-access permission | +| [`_alloca`](./reference/alloca.md) | [`_malloca`](./reference/malloca.md) | Allocate memory on the stack | +| [`asctime`, `_wasctime`](./reference/asctime-wasctime.md) | [`asctime_s`, `_wasctime_s`](./reference/asctime-s-wasctime-s.md) | Convert time from type `struct tm` to character string | +| [`bsearch`](./reference/bsearch.md) | [`bsearch_s`](./reference/bsearch-s.md) | Perform a binary search of a sorted array | +| [`_cgets`, `_cgetws`](./cgets-cgetws.md) | [`_cgets_s`, `_cgetws_s`](./reference/cgets-s-cgetws-s.md) | Get a character string from the console | +| [`_chsize`](./reference/chsize.md) | [`_chsize_s`](./reference/chsize-s.md) | Change the size of a file | +| [`clearerr`](./reference/clearerr.md) | [`clearerr_s`](./reference/clearerr-s.md) | Reset the error indicator for a stream | +| [`_control87`, `_controlfp`, `__control87_2`](./reference/control87-controlfp-control87-2.md) | [`_controlfp_s`](./reference/controlfp-s.md) | Get and set the floating-point control word | +| [`_cprintf`, `_cprintf_l`, `_cwprintf`, `_cwprintf_l`](./reference/cprintf-cprintf-l-cwprintf-cwprintf-l.md) | [`_cprintf_s`, `_cprintf_s_l`, `_cwprintf_s`, `_cwprintf_s_l`](./reference/cprintf-s-cprintf-s-l-cwprintf-s-cwprintf-s-l.md) | Format and print to the console | +| [`_cscanf`, `_cscanf_l`, `_cwscanf`, `_cwscanf_l`](./reference/cscanf-cscanf-l-cwscanf-cwscanf-l.md) | [`_cscanf_s`, `_cscanf_s_l`, `_cwscanf_s`, `_cwscanf_s_l`](./reference/cscanf-s-cscanf-s-l-cwscanf-s-cwscanf-s-l.md) | Read formatted data from the console | +| [`ctime`, `_ctime32`, `_ctime64`, `_wctime`, `_wctime32`, `_wctime64`](./reference/ctime-ctime32-ctime64-wctime-wctime32-wctime64.md) | [`_ctime_s`, `_ctime32_s`, `_ctime64_s`, `_wctime_s`, `_wctime32_s`, `_wctime64_s`](./reference/ctime-s-ctime32-s-ctime64-s-wctime-s-wctime32-s-wctime64-s.md) | Convert time from type `time_t`, `__time32_t` or `__time64_t` to character string | +| [`_ecvt`](./reference/ecvt.md) | [`_ecvt_s`](./reference/ecvt-s.md) | Convert a **`double`** number to a string | +| [`_fcvt`](./reference/fcvt.md) | [`_fcvt_s`](./reference/fcvt-s.md) | Converts a floating-point number to a string | +| [`fopen`, `_wfopen`](./reference/fopen-wfopen.md) | [`fopen_s`, `_wfopen_s`](./reference/fopen-s-wfopen-s.md) | Open a file | +| [`fprintf`, `_fprintf_l`, `fwprintf`, `_fwprintf_l`](./reference/fprintf-fprintf-l-fwprintf-fwprintf-l.md) | [`fprintf_s`, `_fprintf_s_l`, `fwprintf_s`, `_fwprintf_s_l`](./reference/fprintf-s-fprintf-s-l-fwprintf-s-fwprintf-s-l.md) | Print formatted data to a stream | +| [`fread`](./reference/fread.md) | [`fread_s`](./reference/fread-s.md) | Read from a file | +| [`_fread_nolock`](./reference/fread-nolock.md) | [`_fread_nolock_s`](./reference/fread-nolock-s2.md) | Read from a file without using a multi-thread write lock | +| [`freopen`, `_wfreopen`](./reference/freopen-wfreopen.md) | [`freopen_s`, `_wfreopen_s`](./reference/freopen-s-wfreopen-s.md) | Reopen the file | +| [`fscanf`, `_fscanf_l`, `fwscanf`, `_fwscanf_l`](./reference/fscanf-fscanf-l-fwscanf-fwscanf-l.md) | [`fscanf_s`, `_fscanf_s_l`, `fwscanf_s`, `_fwscanf_s_l`](./reference/fscanf-s-fscanf-s-l-fwscanf-s-fwscanf-s-l.md) | Read formatted data from a stream | +| [`_ftime`, `_ftime32`, `_ftime64`](./reference/ftime-ftime32-ftime64.md) | [`_ftime_s`, `_ftime32_s`, `_ftime64_s`](./reference/ftime-s-ftime32-s-ftime64-s.md) | Get the current time | +| [`_gcvt`](./reference/gcvt.md) | [`_gcvt_s`](./reference/gcvt-s.md) | Convert a floating-point value to a string, and store it in a buffer | +| [`getenv`, `_wgetenv`](./reference/getenv-wgetenv.md) | [`getenv_s`, `_wgetenv_s`](./reference/getenv-s-wgetenv-s.md) | Get a value from the current environment. | +| [`gets`, `getws`](./gets-getws.md) | [`gets_s`, `_getws_s`](./reference/gets-s-getws-s.md) | Get a line from the `stdin` stream | +| [`gmtime`, `_gmtime32`, `_gmtime64`](./reference/gmtime-gmtime32-gmtime64.md) | [`_gmtime32_s`, `_gmtime64_s`](./reference/gmtime-s-gmtime32-s-gmtime64-s.md) | Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm` | +| [`itoa`, `_itoa`, `ltoa`, `_ltoa`, `ultoa`, `_ultoa`, `_i64toa`, `_ui64toa`, `_itow`, `_ltow`, `_ultow`, `_i64tow`, `_ui64tow`](./reference/itoa-itow.md) | [`_itoa_s`, `_ltoa_s`, `_ultoa_s`, `_i64toa_s`, `_ui64toa_s`, `_itow_s`, `_ltow_s`, `_ultow_s`, `_i64tow_s`, `_ui64tow_s`](./reference/itoa-s-itow-s.md) | Convert an integral type to a string | +| [`_lfind`](./reference/lfind.md) | [`_lfind_s`](./reference/lfind-s.md) | Perform a linear search for the specified key | +| [`localtime`, `_localtime32`, `_localtime64`](./reference/localtime-localtime32-localtime64.md) | [`localtime_s`, `_localtime32_s`, `_localtime64_s`](./reference/localtime-s-localtime32-s-localtime64-s.md) | Convert time from type `time_t` to `struct tm` or from type `__time64_t` to `struct tm` with local correction | +| [`_lsearch`](./reference/lsearch.md) | [`_lsearch_s`](./reference/lsearch-s.md) | Perform a linear search for a value; adds to end of list if not found | +| [`_makepath`, `_wmakepath`](./reference/makepath-wmakepath.md) | [`_makepath_s`, `_wmakepath_s`](./reference/makepath-s-wmakepath-s.md) | Create a path name from components | +| [`_mbccpy`, `_mbccpy_l`](./reference/mbccpy-mbccpy-l.md) | [`_mbccpy_s`, `_mbccpy_s_l`](./reference/mbccpy-s-mbccpy-s-l.md) | Copy a multibyte character from one string to another string | +| [`_mbsnbcat`, `_mbsnbcat_l`](./reference/mbsnbcat-mbsnbcat-l.md) | [`_mbsnbcat_s`, `_mbsnbcat_s_l`](./reference/mbsnbcat-s-mbsnbcat-s-l.md) | Append at most the first *n* bytes of one multibyte character string to another | +| [`_mbsnbcpy`, `_mbsnbcpy_l`](./reference/mbsnbcpy-mbsnbcpy-l.md) | [`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](./reference/mbsnbcpy-s-mbsnbcpy-s-l.md) | Copy *n* bytes of a string to a destination string | +| [`_mbsnbset`, `_mbsnbset_l`](./reference/mbsnbset-mbsnbset-l.md) | [`_mbsnbset_s`, `_mbsnbset_s_l`](./reference/mbsnbset-s-mbsnbset-s-l.md) | Set the first *n* bytes of a string to a specified character | +| [`mbsrtowcs`](./reference/mbsrtowcs.md) | [`mbsrtowcs_s`](./reference/mbsrtowcs-s.md) | Convert a multibyte character string to a corresponding wide character string | +| [`mbstowcs`, `_mbstowcs_l`](./reference/mbstowcs-mbstowcs-l.md) | [`mbstowcs_s`, `_mbstowcs_s_l`](./reference/mbstowcs-s-mbstowcs-s-l.md) | Convert a sequence of multibyte characters to a corresponding sequence of wide characters | +| [`memcpy`, `wmemcpy`](./reference/memcpy-wmemcpy.md) | [`memcpy_s`, `wmemcpy_s`](./reference/memcpy-s-wmemcpy-s.md) | Copy characters between buffers | +| [`memmove`, `wmemmove`](./reference/memmove-wmemmove.md) | [`memmove_s`, `wmemmove_s`](./reference/memmove-s-wmemmove-s.md) | Move one buffer to another | +| [`_mktemp`, `_wmktemp`](./reference/mktemp-wmktemp.md) | [`_mktemp_s`, `_wmktemp_s`](./reference/mktemp-s-wmktemp-s.md) | Create a unique filename | +| [`printf`, `_printf_l`, `wprintf`, `_wprintf_l`](./reference/printf-printf-l-wprintf-wprintf-l.md) | [`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md) | Print formatted output to the standard output stream | +| [`_putenv`, `_wputenv`](./reference/putenv-wputenv.md) | [`_putenv_s`, `_wputenv_s`](./reference/putenv-s-wputenv-s.md) | Create, modify, or remove environment variables | +| [`qsort`](./reference/qsort.md) | [`qsort_s`](./reference/qsort-s.md) | Perform a quick sort | +| [`rand`](./reference/rand.md) | [`rand_s`](./reference/rand-s.md) | Generate a pseudorandom number | +| [`scanf`, `_scanf_l`, `wscanf`, `_wscanf_l`](./reference/scanf-scanf-l-wscanf-wscanf-l.md) | [`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](./reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) | Read formatted data from the standard input stream | +| [`_searchenv`, `_wsearchenv`](./reference/searchenv-wsearchenv.md) | [`_searchenv_s`, `_wsearchenv_s`](./reference/searchenv-s-wsearchenv-s.md) | Search for a file using environment paths | +| [`snprintf`, `_snprintf`, `_snprintf_l`, `_snwprintf`, `_snwprintf_l`](./reference/snprintf-snprintf-snprintf-l-snwprintf-snwprintf-l.md) | [`_snprintf_s`, `_snprintf_s_l`, `_snwprintf_s`, `_snwprintf_s_l`](./reference/snprintf-s-snprintf-s-l-snwprintf-s-snwprintf-s-l.md) | Write formatted data to a string | +| [`_snscanf`, `_snscanf_l`, `_snwscanf`, `_snwscanf_l`](./reference/snscanf-snscanf-l-snwscanf-snwscanf-l.md) | [`_snscanf_s`, `_snscanf_s_l`, `_snwscanf_s`, `_snwscanf_s_l`](./reference/snscanf-s-snscanf-s-l-snwscanf-s-snwscanf-s-l.md) | Read formatted data of a specified length from a string. | +| [`_sopen`, `_wsopen`](./reference/sopen-wsopen.md) | [`_sopen_s`, `_wsopen_s`](./reference/sopen-s-wsopen-s.md) | Open a file for sharing | +| [`_splitpath`, `_wsplitpath`](./reference/splitpath-wsplitpath.md) | [`_splitpath_s`, `_wsplitpath_s`](./reference/splitpath-s-wsplitpath-s.md) | Break a path name into components | +| [`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](./reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) | [`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](./reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) | Write formatted data to a string | +| [`sscanf`, `_sscanf_l`, `swscanf`, `_swscanf_l`](./reference/sscanf-sscanf-l-swscanf-swscanf-l.md) | [`sscanf_s`, `_sscanf_s_l`, `swscanf_s`, `_swscanf_s_l`](./reference/sscanf-s-sscanf-s-l-swscanf-s-swscanf-s-l.md) | Read formatted data from a string | +| [`strcat`, `wcscat`, `_mbscat`](./reference/strcat-wcscat-mbscat.md) | [`strcat_s`, `wcscat_s`, `_mbscat_s`](./reference/strcat-s-wcscat-s-mbscat-s.md) | Append a string | +| [`strcpy`, `wcscpy`, `_mbscpy`](./reference/strcpy-wcscpy-mbscpy.md) | [`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](./reference/strcpy-s-wcscpy-s-mbscpy-s.md) | Copy a string | +| [`_strdate`, `_wstrdate`](./reference/strdate-wstrdate.md) | [`_strdate_s`, `_wstrdate_s`](./reference/strdate-s-wstrdate-s.md) | Return current system date as string | +| [`strerror`, `_strerror`, `_wcserror`, `__wcserror`](./reference/strerror-strerror-wcserror-wcserror.md) | [`strerror_s`, `_strerror_s`, `_wcserror_s`, `__wcserror_s`](./reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) | Get a system error message (`strerror`, `_wcserror`) or print a user-supplied error message (`_strerror`, `__wcserror`) | +| [`_strlwr`, `_wcslwr`, `_mbslwr`, `_strlwr_l`, `_wcslwr_l`, `_mbslwr_l`](./reference/strlwr-wcslwr-mbslwr-strlwr-l-wcslwr-l-mbslwr-l.md) | [`_strlwr_s`, `_strlwr_s_l`, `_mbslwr_s`, `_mbslwr_s_l`, `_wcslwr_s`, `_wcslwr_s_l`](./reference/strlwr-s-strlwr-s-l-mbslwr-s-mbslwr-s-l-wcslwr-s-wcslwr-s-l.md) | Convert a string to lowercase | +| [`strncat`, `_strncat_l`, `wcsncat`, `_wcsncat_l`, `_mbsncat`, `_mbsncat_l`](./reference/strncat-strncat-l-wcsncat-wcsncat-l-mbsncat-mbsncat-l.md) | [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](./reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) | Append characters to a string | +| [`strncpy`, `_strncpy_l`, `wcsncpy`, `_wcsncpy_l`, `_mbsncpy`, `_mbsncpy_l`](./reference/strncpy-strncpy-l-wcsncpy-wcsncpy-l-mbsncpy-mbsncpy-l.md) | [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](./reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) | Copy characters of one string to another | +| [`_strnset`, `_strnset_l`, `_wcsnset`, `_wcsnset_l`, `_mbsnset`, `_mbsnset_l`](./reference/strnset-strnset-l-wcsnset-wcsnset-l-mbsnset-mbsnset-l.md) | [`_strnset_s`, `_strnset_s_l`, `_wcsnset_s`, `_wcsnset_s_l`, `_mbsnset_s`, `_mbsnset_s_l`](./reference/strnset-s-strnset-s-l-wcsnset-s-wcsnset-s-l-mbsnset-s-mbsnset-s-l.md) | Set the first n characters of a string to the specified character | +| [`_strset`, `_strset_l`, `_wcsset`, `_wcsset_l`, `_mbsset`, `_mbsset_l`](./reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) | [`_strset_s`, `_strset_s_l`, `_wcsset_s`, `_wcsset_s_l`, `_mbsset_s`, `_mbsset_s_l`](./reference/strset-s-strset-s-l-wcsset-s-wcsset-s-l-mbsset-s-mbsset-s-l.md) | Set all the characters of a string to the specified character | +| [`_strtime`, `_wstrtime`](./reference/strtime-wstrtime.md) | [`_strtime_s`, `_wstrtime_s`](./reference/strtime-s-wstrtime-s.md) | Return current system time as string | +| [`strtok`, `_strtok_l`, `wcstok`, `_wcstok_l`, `_mbstok`, `_mbstok_l`](./reference/strtok-strtok-l-wcstok-wcstok-l-mbstok-mbstok-l.md) | [`strtok_s`, `_strtok_s_l`, `wcstok_s`, `_wcstok_s_l`, `_mbstok_s`, `_mbstok_s_l`](./reference/strtok-s-strtok-s-l-wcstok-s-wcstok-s-l-mbstok-s-mbstok-s-l.md) | Find the next token in a string, using the current locale or a locale passed in | +| [`_strupr`, `_strupr_l`, `_mbsupr`, `_mbsupr_l`, `_wcsupr_l`, `_wcsupr`](./reference/strupr-strupr-l-mbsupr-mbsupr-l-wcsupr-l-wcsupr.md) | [`_strupr_s`, `_strupr_s_l`, `_mbsupr_s`, `_mbsupr_s_l`, `_wcsupr_s`, `_wcsupr_s_l`](./reference/strupr-s-strupr-s-l-mbsupr-s-mbsupr-s-l-wcsupr-s-wcsupr-s-l.md) | Convert a string to uppercase | +| [`tmpfile`](./reference/tmpfile.md) | [`tmpfile_s`](./reference/tmpfile-s.md) | Create a temporary file | +| [`_tempnam`, `_wtempnam`, `tmpnam`, `_wtmpnam`](./reference/tempnam-wtempnam-tmpnam-wtmpnam.md) | [`tmpnam_s`, `_wtmpnam_s`](./reference/tmpnam-s-wtmpnam-s.md) | Generate names you can use to create temporary files | +| [`_umask`](./reference/umask.md) | [`_umask_s`](./reference/umask-s.md) | Set the default file-permission mask | +| [`_vcprintf`, `_vcprintf_l`, `_vcwprintf`, `_vcwprintf_l`](./reference/vcprintf-vcprintf-l-vcwprintf-vcwprintf-l.md) | [`_vcprintf_s`, `_vcprintf_s_l`, `_vcwprintf_s`, `_vcwprintf_s_l`](./reference/vcprintf-s-vcprintf-s-l-vcwprintf-s-vcwprintf-s-l.md) | Write formatted output to the console using a pointer to a list of arguments | +| [`vfprintf`, `_vfprintf_l`, `vfwprintf`, `_vfwprintf_l`](./reference/vfprintf-vfprintf-l-vfwprintf-vfwprintf-l.md) | [`vfprintf_s`, `_vfprintf_s_l`, `vfwprintf_s`, `_vfwprintf_s_l`](./reference/vfprintf-s-vfprintf-s-l-vfwprintf-s-vfwprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vfscanf`, `vfwscanf`](./reference/vfscanf-vfwscanf.md) | [`vfscanf_s`, `vfwscanf_s`](./reference/vfscanf-s-vfwscanf-s.md) | Read formatted data from a stream | +| [`vprintf`, `_vprintf_l`, `vwprintf`, `_vwprintf_l`](./reference/vprintf-vprintf-l-vwprintf-vwprintf-l.md) | [`vprintf_s`, `_vprintf_s_l`, `vwprintf_s`, `_vwprintf_s_l`](./reference/vprintf-s-vprintf-s-l-vwprintf-s-vwprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vscanf`, `vwscanf`](./reference/vscanf-vwscanf.md) | [`vscanf_s`, `vwscanf_s`](./reference/vscanf-s-vwscanf-s.md) | Read formatted data from the standard input stream | +| [`vsnprintf`, `_vsnprintf`, `_vsnprintf_l`, `_vsnwprintf`, `_vsnwprintf_l`](./reference/vsnprintf-vsnprintf-vsnprintf-l-vsnwprintf-vsnwprintf-l.md) | [`vsnprintf_s`, `_vsnprintf_s`, `_vsnprintf_s_l`, `_vsnwprintf_s`, `_vsnwprintf_s_l`](./reference/vsnprintf-s-vsnprintf-s-vsnprintf-s-l-vsnwprintf-s-vsnwprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vsprintf`, `_vsprintf_l`, `vswprintf`, `_vswprintf_l`, `__vswprintf_l`](./reference/vsprintf-vsprintf-l-vswprintf-vswprintf-l-vswprintf-l.md) | [`vsprintf_s`, `_vsprintf_s_l`, `vswprintf_s`, `_vswprintf_s_l`](./reference/vsprintf-s-vsprintf-s-l-vswprintf-s-vswprintf-s-l.md) | Write formatted output using a pointer to a list of arguments | +| [`vsscanf`, `vswscanf`](./reference/vsscanf-vswscanf.md) | [`vsscanf_s`, `vswscanf_s`](./reference/vsscanf-s-vswscanf-s.md) | Read formatted data from a string | +| [`wcrtomb`](./reference/wcrtomb.md) | [`wcrtomb_s`](./reference/wcrtomb-s.md) | Convert a wide character into its multibyte character representation | +| [`wcsrtombs`](./reference/wcsrtombs.md) | [`wcsrtombs_s`](./reference/wcsrtombs-s.md) | Convert a wide character string to its multibyte character string representation | +| [`wcstombs`, `_wcstombs_l`](./reference/wcstombs-wcstombs-l.md) | [`wcstombs_s`, `_wcstombs_s_l`](./reference/wcstombs-s-wcstombs-s-l.md) | Convert a sequence of wide characters to a corresponding sequence of multibyte characters | +| [`wctomb`, `_wctomb_l`](./reference/wctomb-wctomb-l.md) | [`wctomb_s`, `_wctomb_s_l`](./reference/wctomb-s-wctomb-s-l.md) | Convert a wide character to the corresponding multibyte character | ## See also -[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/security-features-in-the-crt.md b/docs/c-runtime-library/security-features-in-the-crt.md index d84f1b777d6..624d6d1b9eb 100644 --- a/docs/c-runtime-library/security-features-in-the-crt.md +++ b/docs/c-runtime-library/security-features-in-the-crt.md @@ -2,66 +2,81 @@ 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"] +ms.topic: "concept-article" +f1_keywords: ["_CRT_SECURE_NO_DEPRECATE", "_CRT_NONSTDC_NO_DEPRECATE", "_CRT_NONSTDC_NO_WARNINGS", "_CRT_SECURE_NO_WARNINGS"] helpviewer_keywords: ["security deprecation warnings [C++]", "CRT_NONSTDC_NO_DEPRECATE", "buffers [C++], buffer overruns", "deprecation warnings (security-related), disabling", "_CRT_NONSTDC_NO_WARNINGS", "security [CRT]", "_CRT_SECURE_NO_WARNINGS", "_CRT_NONSTDC_NO_DEPRECATE", "_CRT_SECURE_NO_DEPRECATE", "security-enhanced CRT", "CRT_SECURE_NO_WARNINGS", "CRT_SECURE_NO_DEPRECATE", "deprecation warnings (security-related)", "buffer overruns", "CRT_NONSTDC_NO_WARNINGS", "CRT, security enhancements", "parameters [C++], validation"] -ms.assetid: d9568b08-9514-49cd-b3dc-2454ded195a3 --- # Security Features in the CRT -Many old CRT functions have newer, more secure versions. If a secure function exists, the older, less secure version is marked as deprecated and the new version has the `_s` ("secure") suffix. +Many old CRT functions have newer, more secure versions. If a secure function exists, the older, less secure version is marked as deprecated. The new version has the `_s` ("secure") suffix. -In this context, "deprecated" means using the function's isn't recommended. It doesn't mean the function is scheduled to be removed from the CRT. +In this context, "deprecated" means that use of the function isn't recommended. It doesn't mean the function will be removed from the CRT. -The secure functions don't prevent or correct security errors. Instead, they catch errors when they occur. They do additional checks for error conditions. If there is an error, they invoke an error handler (see [Parameter Validation](../c-runtime-library/parameter-validation.md)). +The secure functions don't prevent or correct security errors. Instead, they catch errors when they occur. They do extra checks for error conditions. If there's an error, they invoke an error handler (see [Parameter validation](./parameter-validation.md)). -For example, the `strcpy` function can't tell if the string it's copying is too large for the destination buffer. Its secure counterpart, `strcpy_s`, takes the size of the buffer as a parameter. So it can determine if a buffer overrun will occur. If you use `strcpy_s` to copy 11 characters into a 10 character buffer, that is an error on your part; `strcpy_s` can't correct your mistake. But it can detect your error and inform you by invoking the invalid parameter handler. +For example, the `strcpy` function can't tell if the string it copies is too large for the destination buffer. Its secure counterpart, `strcpy_s`, takes the size of the buffer as a parameter. So, it can determine if a buffer overrun will occur. If you use `strcpy_s` to copy 11 characters into a 10 character buffer, that's an error on your part; `strcpy_s` can't correct your mistake. But it can detect your error and inform you by invoking the invalid parameter handler. ## Eliminating deprecation warnings -There are several ways to eliminate deprecation warnings for the older, less secure functions. The simplest is simply to define `_CRT_SECURE_NO_WARNINGS` or use the [warning](../preprocessor/warning.md) pragma. Either will disable deprecation warnings, but the security issues that caused the warnings still exist. It's better to leave deprecation warnings enabled and take advantage of the new CRT security features. +There are several ways to eliminate deprecation warnings for the older, less secure functions. The simplest is simply to define `_CRT_SECURE_NO_WARNINGS` or use the [`warning`](../preprocessor/warning.md) pragma. Either disables deprecation warnings, but the security issues that caused the warnings still exist. It's better to leave deprecation warnings enabled and take advantage of the new CRT security features. -In C++, the easiest way to do that is to use [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md). This will eliminate deprecation warnings, in many cases, by replacing calls to deprecated functions with calls to secure versions of those functions. For example, consider this deprecated call to `strcpy`: +In C++, the easiest way to eliminate the deprecation warnings is to use [Secure template overloads](./secure-template-overloads.md). The overloads eliminate deprecation warnings in many cases. They replace calls to deprecated functions with calls to secure versions of the functions. For example, consider this deprecated call to `strcpy`: -``` +```cpp char szBuf[10]; strcpy(szBuf, "test"); // warning: deprecated ``` -Defining `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 eliminates the warning by changing the `strcpy` call to `strcpy_s`, which prevents buffer overruns. For more information, see [Secure Template Overloads](../c-runtime-library/secure-template-overloads.md). +Defining `_CRT_SECURE_CPP_OVERLOAD_STANDARD_NAMES` as 1 eliminates the warning by changing the `strcpy` call to `strcpy_s`, which prevents buffer overruns. For more information, see [Secure template overloads](./secure-template-overloads.md). For those deprecated functions without secure template overloads, you should definitely consider manually updating your code to use the secure versions. -Another source of deprecation warnings, unrelated to security, is the POSIX functions. Replace POSIX function names with their standard equivalents (for example, change [access](../c-runtime-library/reference/access-crt.md) to [_access](../c-runtime-library/reference/access-waccess.md)), or disable POSIX-related deprecation warnings by defining `_CRT_NONSTDC_NO_WARNINGS`. For more information, see [Compatibility](compatibility.md). +Another source of deprecation warnings, unrelated to security, is the POSIX functions. Replace POSIX function names with their standard equivalents (for example, change [`access`](./reference/access-crt.md) to [`_access`](./reference/access-waccess.md)), or disable POSIX-related deprecation warnings by defining `_CRT_NONSTDC_NO_WARNINGS`. For more information, see [Compatibility](compatibility.md). -## Additional Security Features +## More security features Some of the security features include: -- `Parameter Validation`. Secure functions, and many of their unsecure counterparts, validate parameters. Validation may include: +- **Parameter Validation** + + Secure functions, and many of their unsecure counterparts, validate parameters. Validation may include: - - Checking for **NULL** values. + - Checking for `NULL` values. - Checking enumerated values for validity. - Checking that integral values are in valid ranges. -- For more information, see [Parameter Validation](../c-runtime-library/parameter-validation.md). + For more information, see [Parameter validation](./parameter-validation.md). + + A handler for invalid parameters is also accessible to the developer. When a function encounters an invalid parameter, instead of asserting and exiting the application, the CRT allows you to check these problems via [`_set_invalid_parameter_handler` or `_set_thread_local_invalid_parameter_handler`](./reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). + +- **Sized Buffers** + + You must pass the buffer size to any secure function that writes to a buffer. The secure versions validate that the buffer is large enough before writing to it. The validation helps avoid dangerous buffer overrun errors that could allow malicious code to execute. These functions usually return an `errno` error code and invoke the invalid parameter handler if the size of the buffer is too small. Functions that read from input buffers, such as `gets`, have secure versions that require you to specify a maximum size. + + The debug versions of *some* security-enhanced CRT functions fill the buffer passed to them with a special character (0xFE). This fill character helps to find cases where the incorrect size was passed to the function. Unfortunately, it also reduces performance. To improve performance, use **`_CrtSetDebugFillThreshold`** to disable buffer-filling. For more information, and a list of functions that have this behavior, see [`_CrtSetDebugFillThreshold`](./reference/crtsetdebugfillthreshold.md). + +- **Null termination** + + Some functions that left potentially nonterminated strings have secure versions, which ensure that strings are properly null-terminated. + +- **Enhanced error reporting** -- A handler for invalid parameters is also accessible to the developer. When a function encounters an invalid parameter, instead of asserting and exiting the application, the CRT allows you to check these problems via [_set_invalid_parameter_handler, _set_thread_local_invalid_parameter_handler](../c-runtime-library/reference/set-invalid-parameter-handler-set-thread-local-invalid-parameter-handler.md). + The secure functions return error codes with more error information than was available with the preexisting functions. The secure functions and many of the preexisting functions now set `errno` and often return an `errno` code type as well, to provide better error reporting. -- `Sized Buffers`. You must pass the buffer size to any secure function that writes to a buffer. The secure versions validate that the buffer is large enough before writing to it. Which helps avoid dangerous buffer overrun errors that could allow malicious code to execute. These functions usually return an `errno` error code and invoke the invalid parameter handler if the size of the buffer is too small. Functions that read from input buffers, such as `gets`, have secure versions that require you to specify a maximum size. +- **Filesystem security** -- `Null termination`. Some functions that left potentially non-terminated strings have secure versions, which ensure that strings are properly null-terminated. + Secure file I/O APIs support secure file access in the default case. -- `Enhanced error reporting`. The secure functions return error codes with more error information than was available with the pre-existing functions. The secure functions and many of the pre-existing functions now set `errno` and often return an `errno` code type as well, to provide better error reporting. +- **Windows security** -- `Filesystem security`. Secure file I/O APIs support secure file access in the default case. + Secure process APIs enforce security policies and allow ACLs to be specified. -- `Windows security`. Secure process APIs enforce security policies and allow ACLs to be specified. +- **Format string syntax checking** -- `Format string syntax checking`. Invalid strings are detected, for example, using incorrect type field characters in `printf` format strings. + Invalid strings are detected, for example, when you use incorrect type field characters in `printf` format strings. ## See also -[Parameter Validation](../c-runtime-library/parameter-validation.md)
-[Secure Template Overloads](../c-runtime-library/secure-template-overloads.md)
-[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md) +[Parameter validation](./parameter-validation.md)\ +[Secure template overloads](./secure-template-overloads.md)\ +[C runtime (CRT) and C++ Standard Library (STL) `.lib` files](./crt-library-features.md) diff --git a/docs/c-runtime-library/set-app-type.md b/docs/c-runtime-library/set-app-type.md index dec1f9fef1d..6b7666c2799 100644 --- a/docs/c-runtime-library/set-app-type.md +++ b/docs/c-runtime-library/set-app-type.md @@ -3,13 +3,13 @@ description: "Learn more about: _set_app_type" title: "_set_app_type" ms.date: "4/2/2020" api_name: ["_set_app_type", "_o__set_app_type"] -api_location: ["api-ms-win-crt-runtime-l1-1-0.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["api-ms-win-crt-runtime-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] -f1_keywords: ["_set_app_type", "corecrt_startup/_set_app_type"] +f1_keywords: ["_set_app_type", "corecrt_startup/_set_app_type", "corecrt_startup/_crt_app_type", "corecrt_startup/_crt_unknown_app", "corecrt_startup/_crt_console_app", "corecrt_startup/_crt_gui_app"] ms.assetid: 1e7fe786-b587-4116-8c05-f7d762350100 --- -# _set_app_type +# `_set_app_type` An internal function used at startup to tell the CRT whether the app is a console app or a GUI app. @@ -30,23 +30,23 @@ void __cdecl _set_app_type( ## Parameters -*appType*
+*`appType`*\ A value that indicates the application type. The possible values are: -|Value|Description| -|----------------|-----------------| -|_crt_unknown_app|Unknown application type.| -|_crt_console_app|Console (command-line) application.| -|_crt_gui_app|GUI (Windows) application.| +| Value | Description | +|---|---| +| `_crt_unknown_app` | Unknown application type. | +| `_crt_console_app` | Console (command-line) application. | +| `_crt_gui_app` | GUI (Windows) application. | ## Remarks -Normally, you do not need to call this function. It is part of the C runtime startup code that executes before `main` is called in your app. +Normally, you don't need to call this function. It's part of the C runtime startup code that executes before `main` is called in your app. -By default, this function's global state is scoped to the application. To change this, see [Global state in the CRT](global-state.md). +By default, this function's global state is scoped to the application. To change this behavior, see [Global state in the CRT](global-state.md). ## Requirements -|Routine|Required header| -|-------------|---------------------| -|_set_app_type|process.h| +| Routine | Required header | +|---|---| +| **`_set_app_type`** | `` | diff --git a/docs/c-runtime-library/set-output-format.md b/docs/c-runtime-library/set-output-format.md index 15fabff3242..551c5d90e08 100644 --- a/docs/c-runtime-library/set-output-format.md +++ b/docs/c-runtime-library/set-output-format.md @@ -10,7 +10,7 @@ f1_keywords: ["set_output_format", "_set_output_format"] helpviewer_keywords: ["_TWO_DIGIT_EXPONENT constant", "output formatting", "TWO_DIGIT_EXPONENT constant", "_set_output_format function", "set_output_format function"] ms.assetid: 1cb48df8-44b4-4400-bd27-287831d6b3ff --- -# _set_output_format +# `_set_output_format` Customizes output formats used by formatted I/O functions. @@ -19,7 +19,7 @@ Customizes output formats used by formatted I/O functions. ## Syntax -``` +```C unsigned int _set_output_format( unsigned int format ); @@ -27,7 +27,7 @@ unsigned int _set_output_format( #### Parameters -*format*
+*`format`*\ [in] An value representing the format to use. ## Return value @@ -36,19 +36,19 @@ The previous output format. ## Remarks -`_set_output_format` is used to configure the output of formatted I/O functions such as [printf_s](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md). At present, the only formatting convention that can be changed by this function is the number of digits displayed in exponents in the output of floating point numbers. +**`_set_output_format`** is used to configure the output of formatted I/O functions such as [`printf_s`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md). The only formatting convention that can be changed by this function is the number of digits displayed in exponents in the output of floating point numbers. -By default, the output of floating point numbers by functions such as `printf_s`, `wprintf_s`, and related functions in the Visual C++ Standard C library prints three digits for the exponent, even if three digits are not required to represent the value of the exponent. Zeroes are used to pad the value to three digits. `_set_output_format` allows you to change this behavior so that only two digits are printed in the exponent unless a third digit is required by the size of the exponent. +By default, the output of floating point numbers by functions such as `printf_s`, `wprintf_s`, and related functions in the Visual C++ Standard C library prints three digits for the exponent, even if three digits aren't required to represent the value of the exponent. Zeroes are used to pad the value to three digits. **`_set_output_format`** allows you to change this behavior so that only two digits are printed in the exponent unless a third digit is required by the size of the exponent. To enable two-digit exponents, call this function with the parameter `_TWO_DIGIT_EXPONENT`, as shown in the example. To disable two digit exponents, call this function with an argument of 0. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`_set_output_format`|\| +| Routine | Required header | +|---|---| +| **`_set_output_format`** | \ | -For more compatibility information, see [Compatibility](../c-runtime-library/compatibility.md) in the Introduction. +For more compatibility information, see [Compatibility](./compatibility.md) in the Introduction. ## Example @@ -102,5 +102,5 @@ int main() ## See also -[printf_s, _printf_s_l, wprintf_s, _wprintf_s_l](../c-runtime-library/reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)
-[_get_output_format](../c-runtime-library/get-output-format.md) +[`printf_s`, `_printf_s_l`, `wprintf_s`, `_wprintf_s_l`](./reference/printf-s-printf-s-l-wprintf-s-wprintf-s-l.md)\ +[`_get_output_format`](./get-output-format.md) diff --git a/docs/c-runtime-library/setjmp3.md b/docs/c-runtime-library/setjmp3.md index 18242e77c08..d406921ec9d 100644 --- a/docs/c-runtime-library/setjmp3.md +++ b/docs/c-runtime-library/setjmp3.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _setjmp3" title: "_setjmp3" -ms.date: "1/14/2021" +description: "Learn more about: _setjmp3" +ms.date: 1/14/2021 api_name: ["_setjmp3"] -api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr110.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr120.dll", "api-ms-win-crt-private-l1-1-0.dll"] +api_location: ["msvcrt.dll", "msvcr90.dll", "msvcr110.dll", "msvcr80.dll", "msvcr110_clr0400.dll", "msvcr100.dll", "msvcr120.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["setjmp3", "_setjmp3"] helpviewer_keywords: ["_setjmp3 function", "setjmp3 function"] -ms.assetid: 6129c2f3-8bac-4fdb-a827-44e1eebba500 --- # `_setjmp3` @@ -16,7 +15,7 @@ Internal CRT function. A new implementation of the `setjmp` function. ## Syntax -``` +```C int _setjmp3( OUT jmp_buf env, int count, @@ -30,12 +29,12 @@ int _setjmp3( [out] Address of the buffer for storing state information. *`count`*\ -[in] The number of additional `DWORD`s of information that are stored in the `optional parameters`. +[in] The number of `DWORD`s of information stored in the `optional parameters`. *`optional parameters`*\ -[in] Additional data pushed down by the `setjmp` intrinsic. The first `DWORD` is a function pointer that is used to unwind extra data and return to a nonvolatile register state. The second `DWORD` is the try level to be restored. Any further data is saved in the generic data array in the `jmp_buf`. +[in] Extra data pushed down by the `setjmp` intrinsic. The first `DWORD` is a function pointer that is used to unwind extra data and return to a nonvolatile register state. The second `DWORD` is the try level to be restored. Any further data is saved in the generic data array in the `jmp_buf`. -## Return Value +## Return value Always returns 0. @@ -43,9 +42,7 @@ Always returns 0. Don't use this function in a C++ program. It's an intrinsic function that doesn't support C++. For more information about how to use `setjmp`, see [Using setjmp/longjmp](../cpp/using-setjmp-longjmp.md). -## Requirements - ## See also -[Alphabetical Function Reference](../c-runtime-library/reference/crt-alphabetical-function-reference.md)\ -[`setjmp`](../c-runtime-library/reference/setjmp.md) +[Alphabetical function reference](./reference/crt-alphabetical-function-reference.md)\ +[`setjmp`](./reference/setjmp.md) diff --git a/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md b/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md index fa329705e86..b725aaed44c 100644 --- a/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md +++ b/docs/c-runtime-library/setlc-active-func-unguarded-readlc-active-add-func.md @@ -10,7 +10,7 @@ f1_keywords: ["___unguarded_readlc_active_add_func", "___setlc_active_func"] helpviewer_keywords: ["___setlc_active_func", "___unguarded_readlc_active_add_func"] ms.assetid: 605ec4e3-81e5-4ece-935a-f434768cc702 --- -# ___setlc_active_func, ___unguarded_readlc_active_add_func +# `___setlc_active_func`, `___unguarded_readlc_active_add_func` OBSOLETE. The CRT exports these internal functions only to preserve binary compatibility. @@ -21,20 +21,20 @@ int ___setlc_active_func(void); int * ___unguarded_readlc_active_add_func(void); ``` -## Return Value +## Return value -The value returned is not significant. +The value returned isn't significant. ## Remarks -Although the internal CRT functions `___setlc_active_func` and `___unguarded_readlc_active_add_func` are obsolete and no longer used, they are exported by the CRT library to preserve binary compatibility. The original purpose of `___setlc_active_func` was to return the number of currently active calls to the `setlocale` function. The original purpose of `___unguarded_readlc_active_add_func` was to return the number of functions that referenced the locale without locking it. +Although the internal CRT functions **`___setlc_active_func`** and **`___unguarded_readlc_active_add_func`** are obsolete and no longer used, they're exported by the CRT library to preserve binary compatibility. The original purpose of **`___setlc_active_func`** was to return the number of currently active calls to the `setlocale` function. The original purpose of **`___unguarded_readlc_active_add_func`** was to return the number of functions that referenced the locale without locking it. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|`___setlc_active_func`, `___unguarded_readlc_active_add_func`|none| +| Routine | Required header | +|---|---| +| **`___setlc_active_func`**, **`___unguarded_readlc_active_add_func`** | none | ## See also -[setlocale, _wsetlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) +[`setlocale`, `_wsetlocale`](./reference/setlocale-wsetlocale.md) diff --git a/docs/c-runtime-library/setusermatherr.md b/docs/c-runtime-library/setusermatherr.md index e04c346680d..b63946d98ec 100644 --- a/docs/c-runtime-library/setusermatherr.md +++ b/docs/c-runtime-library/setusermatherr.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: __setusermatherr" title: "__setusermatherr" -ms.date: "11/04/2016" +description: "Learn more about: __setusermatherr" +ms.date: 11/04/2016 api_name: ["__setusermatherr"] api_location: ["msvcr80.dll", "msvcr90.dll", "msvcrt.dll", "msvcr110.dll", "msvcr110_clr0400.dll", "msvcr120.dll", "msvcr100.dll", "api-ms-win-crt-math-l1-1-0.dll"] api_type: ["DLLExport"] topic_type: ["apiref"] f1_keywords: ["__setusermatherr"] helpviewer_keywords: ["__setusermatherr"] -ms.assetid: f306818d-381a-4d68-8739-71b92bacb5ea --- -# __setusermatherr +# `__setusermatherr` -Specifies a user-supplied rountine to handle math errors, instead of the [_matherr](../c-runtime-library/reference/matherr.md) routine. +Specifies a user-supplied routine to handle math errors, instead of the [`_matherr`](./reference/matherr.md) routine. ## Syntax @@ -24,15 +23,13 @@ void __setusermatherr( #### Parameters -*pf*
+*`pf`*\ Pointer to an implementation of `_matherr` that is supplied by the user. -The type of the *pf* parameter is declared as `typedef int (__cdecl * _HANDLE_MATH_ERROR)(struct _exception *)`. - -## Remarks +The type of the *`pf`* parameter is declared as `typedef int (__cdecl * _HANDLE_MATH_ERROR)(struct _exception *)`. ## Requirements -|Routine|Required header| -|-------------|---------------------| -|__setusermatherr|matherr.c| +| Routine | Required header | +|---|---| +| **`__setusermatherr`** | `matherr.c` | diff --git a/docs/c-runtime-library/setvbuf-constants.md b/docs/c-runtime-library/setvbuf-constants.md index a4a2f00503c..06386d05fb6 100644 --- a/docs/c-runtime-library/setvbuf-constants.md +++ b/docs/c-runtime-library/setvbuf-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: setvbuf Constants" title: "setvbuf Constants" ms.date: "11/04/2016" -f1_keywords: ["_IOFBF", "_IONBF", "_IOLBF"] +f1_keywords: ["STDIO/_IOFBF", "STDIO/_IONBF", "STDIO/_IOLBF", "_IOFBF", "_IONBF", "_IOLBF"] helpviewer_keywords: ["_IOFBF constant", "IOFBF constant", "IONBF constant", "_IOLBF constant", "IOLBF constant", "_IONBF constant"] ms.assetid: a6ec4dd5-1f24-498c-871a-e874cd28d33c --- -# setvbuf Constants +# `setvbuf` constants ## Syntax -``` +```C #include ``` @@ -20,13 +20,13 @@ These constants represent the type of buffer for `setvbuf`. The possible values are given by the following manifest constants: -|Constant|Meaning| -|--------------|-------------| -|`_IOFBF`|Full buffering: Buffer specified in call to `setvbuf` is used and its size is as specified in `setvbuf` call. If buffer pointer is **NULL**, automatically allocated buffer of specified size is used.| -|`_IOLBF`|Same as `_IOFBF`.| -|`_IONBF`|No buffer is used, regardless of arguments in call to `setvbuf`.| +| Constant | Meaning | +|---|---| +| `_IOFBF` | Full buffering: Buffer specified in call to `setvbuf` is used and its size is as specified in `setvbuf` call. If buffer pointer is `NULL`, automatically allocated buffer of specified size is used. | +| `_IOLBF` | Same as `_IOFBF`. | +| `_IONBF` | No buffer is used, regardless of arguments in call to `setvbuf`. | ## See also -[setbuf](../c-runtime-library/reference/setbuf.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`setbuf`](./reference/setbuf.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/sharing-constants.md b/docs/c-runtime-library/sharing-constants.md index 13eb899f295..11c84f2d81e 100644 --- a/docs/c-runtime-library/sharing-constants.md +++ b/docs/c-runtime-library/sharing-constants.md @@ -2,36 +2,36 @@ description: "Learn more about: Sharing Constants" title: "Sharing Constants" ms.date: "11/04/2016" -f1_keywords: ["_SH_DENYNO", "_SH_DENYRD", "_SH_DENYRW", "_SH_DENYWR", "_SH_COMPAT"] -helpviewer_keywords: ["_SH_DENYRW constant", "SH_DENYRD constant", "_SH_COMPAT constant", "_SH_DENYRD constant", "SH_DENYRW constant", "sharing constants", "SH_DENYNO constant", "_SH_DENYWR constant", "SH_DENYWR constant", "_SH_DENYNO constant", "SH_COMPAT constant"] +f1_keywords: ["CORECRT_SHARE/_SH_DENYNO", "CORECRT_SHARE/_SH_DENYRD", "CORECRT_SHARE/_SH_DENYRW", "CORECRT_SHARE/_SH_DENYWR", "CORECRT_SHARE/_SH_SECURE", "_SH_DENYNO", "_SH_DENYRD", "_SH_DENYRW", "_SH_DENYWR", "_SH_SECURE"] +helpviewer_keywords: ["_SH_DENYRW constant", "SH_DENYRD constant", "_SH_SECURE constant", "_SH_DENYRD constant", "SH_DENYRW constant", "sharing constants", "SH_DENYNO constant", "_SH_DENYWR constant", "SH_DENYWR constant", "_SH_DENYNO constant", "SH_SECURE constant"] ms.assetid: 95fadc3a-55dc-473d-98b5-e8211900465d --- -# Sharing Constants +# Sharing constants Constants for file-sharing modes. ## Syntax -``` +```C #include ``` ## Remarks -The *shflag* argument determines the sharing mode, which consists of one or more manifest constants. These can be combined with the *oflag* arguments (see [File Constants](../c-runtime-library/file-constants.md)). +The *`shflag`* argument determines the sharing mode, which consists of one or more manifest constants. These constants can be combined with the *`oflag`* arguments (see [File constants](./file-constants.md)). The following table lists the constants and their meanings: -|Constant|Meaning| -|--------------|-------------| -|`_SH_DENYRW`|Denies read and write access to file| -|`_SH_DENYWR`|Denies write access to file| -|`_SH_DENYRD`|Denies read access to file| -|`_SH_DENYNO`|Permits read and write access| -|`_SH_SECURE`|Sets secure mode (shared read, exclusive write access).| +| Constant | Meaning | +|---|---| +| `_SH_DENYRW` | Denies read and write access to file | +| `_SH_DENYWR` | Denies write access to file | +| `_SH_DENYRD` | Denies read access to file | +| `_SH_DENYNO` | Permits read and write access | +| `_SH_SECURE` | Sets secure mode (shared read, exclusive write access). | ## See also -[_sopen, _wsopen](../c-runtime-library/reference/sopen-wsopen.md)
-[_fsopen, _wfsopen](../c-runtime-library/reference/fsopen-wfsopen.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_sopen`, `_wsopen`](./reference/sopen-wsopen.md)\ +[`_fsopen`, `_wfsopen`](./reference/fsopen-wfsopen.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/signal-action-constants.md b/docs/c-runtime-library/signal-action-constants.md index be53b6bb852..17d063de1ca 100644 --- a/docs/c-runtime-library/signal-action-constants.md +++ b/docs/c-runtime-library/signal-action-constants.md @@ -2,17 +2,17 @@ description: "Learn more about: signal Action Constants" title: "signal Action Constants" ms.date: "11/04/2016" -f1_keywords: ["SIG_IGN", "SIG_DFL"] +f1_keywords: ["SIGNAL/SIG_IGN", "SIGNAL/SIG_DFL", "SIGNAL/SIG_GET", "SIGNAL/SIG_SGE", "SIGNAL/SIG_ACK", "SIGNAL/SIG_ERR", "SIG_IGN", "SIG_DFL", "SIG_GET", "SIG_SGE", "SIG_ACK", "SIG_ERR"] helpviewer_keywords: ["signal action constants", "SIG_IGN constant", "SIG_DFL constant"] ms.assetid: c3cb4f15-d39e-4d9d-84f9-0d33e3eb5993 --- -# signal Action Constants +# `signal` action constants The action taken when the interrupt signal is received depends on the value of `func`. ## Syntax -``` +```C #include ``` @@ -20,15 +20,16 @@ The action taken when the interrupt signal is received depends on the value of ` The `func` argument must be either a function address or one of the manifest constants listed below and defined in SIGNAL.H. -|Constant|Description| -|-|-| -| `SIG_DFL` | Uses system-default response. If the calling program uses stream I/O, buffers created by the run-time library are not flushed. | -| `SIG_IGN` | Ignores interrupt signal. This value should never be given for `SIGFPE`, since the floating-point state of the process is left undefined. | -| `SIG_SGE` | Indicates an error occurred in the signal. | -| `SIG_ACK` | Indicates an acknowledgement was received. | -| `SIG_ERR` | A return type from a signal indicating an error has occurred. | +| Constant | Description | +|---|---| +| `SIG_DFL` | Uses system-default response. If the calling program uses stream I/O, buffers created by the run-time library aren't flushed. | +| `SIG_IGN` | Ignores interrupt signal. This value should never be given for `SIGFPE`, since the floating-point state of the process is left undefined. | +| `SIG_GET` | Returns the current value of the signal. | +| `SIG_SGE` | Indicates an error occurred in the signal. | +| `SIG_ACK` | Indicates an acknowledgment was received. | +| `SIG_ERR` | A return type from a signal indicating an error has occurred. | ## See also -[signal](../c-runtime-library/reference/signal.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`signal`](./reference/signal.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/signal-constants.md b/docs/c-runtime-library/signal-constants.md index 5982962d583..24d35116ca8 100644 --- a/docs/c-runtime-library/signal-constants.md +++ b/docs/c-runtime-library/signal-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: signal Constants" title: "signal Constants" ms.date: "11/04/2016" -f1_keywords: ["SIGTERM", "SIGFPE", "SIGABRT", "SIGILL", "SIGINT", "SIGSEGV"] +f1_keywords: ["SIGNAL/SIGTERM", "SIGNAL/SIGFPE", "SIGNAL/SIGABRT", "SIGNAL/SIGILL", "SIGNAL/SIGINT", "SIGNAL/SIGSEGV", "SIGNAL/SIGABRT_COMPAT", "SIGTERM", "SIGFPE", "SIGABRT", "SIGILL", "SIGINT", "SIGSEGV", "SIGABRT_COMPAT"] helpviewer_keywords: ["SIGTERM constant", "SIGABRT constant", "SIGSEGV constant", "SIGFPE constant", "SIGINT constant", "signal constants", "SIGILL constant"] ms.assetid: a3b39281-dae7-4e44-8d68-e6a610c669dd --- -# signal Constants +# `signal` constants ## Syntax -``` +```C #include ``` @@ -18,19 +18,19 @@ ms.assetid: a3b39281-dae7-4e44-8d68-e6a610c669dd The `sig` argument must be one of the manifest constants listed below (defined in SIGNAL.H). -|Constant|Description| -|-|-| -|SIGABRT|Abnormal termination. The default action terminates the calling program with exit code 3. | -|SIGABRT_COMPAT|Same as SIGABRT. For compatibility with other platforms. | -|SIGFPE|Floating-point error, such as overflow, division by zero, or invalid operation. The default action terminates the calling program. | -|SIGILL|Illegal instruction. The default action terminates the calling program. | -|SIGINT|CTRL+C interrupt. The default action terminates the calling program with exit code 3. | -|SIGSEGV|Illegal storage access. The default action terminates the calling program. | -|SIGTERM|Termination request sent to the program. The default action terminates the calling program with exit code 3. | -|SIG_ERR|A return type from a signal indicating an error has occurred. | +| Constant | Description | +|---|---| +| `SIGABRT` | Abnormal termination. The default action terminates the calling program with exit code 3. | +| `SIGABRT_COMPAT` | Same meaning as `SIGABRT`. For compatibility with other platforms. | +| `SIGFPE` | Floating-point error, such as overflow, division by zero, or invalid operation. The default action terminates the calling program. | +| `SIGILL` | Illegal instruction. The default action terminates the calling program. | +| `SIGINT` | CTRL+C interrupt. The default action terminates the calling program with exit code 3. | +| `SIGSEGV` | Illegal storage access. The default action terminates the calling program. | +| `SIGTERM` | Termination request sent to the program. The default action terminates the calling program with exit code 3. | +| `SIG_ERR` | A return type from a signal indicating an error has occurred. | ## See also -[signal](../c-runtime-library/reference/signal.md)
-[raise](../c-runtime-library/reference/raise.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`signal`](./reference/signal.md)\ +[`raise`](./reference/raise.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md b/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md index 78287e07f80..cbebeccee27 100644 --- a/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md +++ b/docs/c-runtime-library/single-byte-and-multibyte-character-sets.md @@ -1,21 +1,20 @@ --- title: "Single-Byte and Multibyte Character Sets" description: "An introduction to single and multi-byte character sets in the Microsoft runtime library." -ms.topic: "conceptual" -ms.date: "11/04/2016" +ms.date: 11/04/2016 +ms.topic: "concept-article" helpviewer_keywords: ["SBCS (single byte character set)", "MBCS [C++], about MBCS", "character sets [C++], multibyte", "character sets [C++], single byte"] -ms.assetid: 2cbc78ea-33c0-4cfb-b0df-7ce2458431ce --- -# Single-Byte and Multibyte Character Sets +# Single-byte and multibyte character sets -The ASCII character set defines characters in the range 0x00 - 0x7F. There are a number of other character sets, primarily European, that define the characters within the range 0x00 - 0x7F identically to the ASCII character set and also define an extended character set from 0x80 - 0xFF. An 8-bit, single-byte-character set (SBCS) is sufficient to represent the ASCII character set as well as the character sets for many European languages. However, some non-European character sets, such as Japanese Kanji, include many more characters than can be represented in a single-byte coding scheme, and so require multibyte-character set (MBCS) encoding. +The ASCII character set defines characters in the range 0x00 - 0x7F. There are other character sets, primarily European, that define the characters within the range 0x00 - 0x7F identically to the ASCII character set and also define an extended character set from 0x80 - 0xFF. Thus, an 8-bit, single-byte-character set (SBCS) is sufficient to represent the ASCII character set and the character sets for many European languages. However, some non-European character sets, such as Japanese Kanji, include many more characters than a single-byte coding scheme can represent, and therefore require multibyte-character set (MBCS) encoding. > [!NOTE] -> Many SBCS routines in the Microsoft run-time library handle multibyte bytes, characters, and strings as appropriate. Many multibyte-character sets define the ASCII character set as a subset. In many multibyte character sets, each character in the range 0x00 - 0x7F is identical to the character that has the same value in the ASCII character set. For example, in both ASCII and MBCS character strings, the one-byte null character ('\0') has value 0x00 and indicates the terminating null character. +> Many Microsoft run-time library SBCS routines handle multibyte bytes, characters, and strings as appropriate. Many multibyte-character sets define the ASCII character set as a subset. In many multibyte character sets, each character in the range 0x00 - 0x7F is identical to the character that has the same value in the ASCII character set. For example, in both ASCII and MBCS character strings, the one-byte null character ('\0') has value 0x00 and indicates the terminating null character. -A multibyte character set can consist of both one-byte and two-byte characters. A multibyte-character string can contain a mixture of single-byte and double-byte characters. A two-byte multibyte character has a lead byte and a trail byte. In a particular multibyte-character set, the lead bytes fall within a certain range, as do the trail bytes. When these ranges overlap, you may need to evaluate the context to determine whether a given byte is functioning as a lead byte or a trail byte. +A multibyte character set can consist of both 1-byte and 2-byte characters. A multibyte-character string can contain a mixture of single-byte and double-byte characters. A two-byte multibyte character has a lead byte and a trail byte. In a particular multibyte-character set, the lead bytes fall within a certain range, as do the trail bytes. When these ranges overlap, you may need to evaluate the context to determine whether a given byte is functioning as a lead byte or a trail byte. ## See also -[Internationalization](../c-runtime-library/internationalization.md)
-[Universal C runtime routines by category](../c-runtime-library/run-time-routines-by-category.md)
+[Internationalization](./internationalization.md)\ +[Universal C runtime routines by category](./run-time-routines-by-category.md) diff --git a/docs/c-runtime-library/spawn-constants.md b/docs/c-runtime-library/spawn-constants.md index b0bc3d8242b..0be2e3c4d49 100644 --- a/docs/c-runtime-library/spawn-constants.md +++ b/docs/c-runtime-library/spawn-constants.md @@ -2,15 +2,15 @@ description: "Learn more about: spawn Constants" title: "spawn Constants" ms.date: "11/04/2016" -f1_keywords: ["_P_NOWAIT", "_P_OVERLAY", "_P_WAIT", "_P_DETACH", "_P_NOWAITO"] +f1_keywords: ["PROCESS/_P_NOWAIT", "PROCESS/_P_OVERLAY", "PROCESS/_P_WAIT", "PROCESS/_P_DETACH", "PROCESS/_P_NOWAITO", "_P_NOWAIT", "_P_OVERLAY", "_P_WAIT", "_P_DETACH", "_P_NOWAITO"] helpviewer_keywords: ["_P_OVERLAY constant", "P_DETACH constant", "P_OVERLAY constant", "P_NOWAIT constant", "_P_DETACH constant", "_P_NOWAIT constant", "_P_NOWAITO constant", "P_NOWAITO constant", "spawn constants", "P_WAIT constant", "_P_WAIT constant"] ms.assetid: e0533e88-d362-46fc-b53c-5f193226d879 --- -# spawn Constants +# `spawn` constants ## Syntax -``` +```C #include ``` @@ -18,14 +18,14 @@ ms.assetid: e0533e88-d362-46fc-b53c-5f193226d879 The `mode` argument determines the action taken by the calling process before and during a spawn operation. The following values for `mode` are possible: -|Constant|Meaning| -|--------------|-------------| -|`_P_OVERLAY`|Overlays calling process with new process, destroying calling process (same effect as `_exec` calls).| -|`_P_WAIT`|Suspends calling thread until execution of new process is complete (synchronous `_spawn`).| -|`_P_NOWAIT`, `_P_NOWAITO`|Continues to execute calling process concurrently with new process (asynchronous `_spawn`).| -|`_P_DETACH`|Continues to execute calling process; new process is run in background with no access to console or keyboard. Calls to `_cwait` against new process will fail. This is an asynchronous `_spawn`.| +| Constant | Meaning | +|---|---| +| `_P_OVERLAY` | Overlays calling process with new process, destroying calling process (same effect as `_exec` calls). | +| `_P_WAIT` | Suspends calling thread until execution of new process is complete (synchronous `_spawn`). | +| `_P_NOWAIT`, `_P_NOWAITO` | Continues to execute calling process concurrently with new process (asynchronous `_spawn`). | +| `_P_DETACH` | Continues to execute calling process; new process is run in background with no access to console or keyboard. Calls to `_cwait` against new process will fail. This `_spawn` is asynchronous. | ## See also -[_spawn, _wspawn Functions](../c-runtime-library/spawn-wspawn-functions.md)
-[Global Constants](../c-runtime-library/global-constants.md) +[`_spawn`, `_wspawn` functions](./spawn-wspawn-functions.md)\ +[Global constants](./global-constants.md) diff --git a/docs/c-runtime-library/spawn-wspawn-functions.md b/docs/c-runtime-library/spawn-wspawn-functions.md index 41646f6f7b7..97667c5c001 100644 --- a/docs/c-runtime-library/spawn-wspawn-functions.md +++ b/docs/c-runtime-library/spawn-wspawn-functions.md @@ -2,65 +2,56 @@ 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"] --- -# `_spawn`, `_wspawn` Functions +# `_spawn`, `_wspawn` functions Each of the `_spawn` functions creates and executes a new process: -:::row::: - :::column span=""::: - [`_spawnl`, `_wspawnl`](../c-runtime-library/reference/spawnl-wspawnl.md)\ - [`_spawnle`, `_wspawnle`](../c-runtime-library/reference/spawnle-wspawnle.md)\ - [`_spawnlp`, `_wspawnlp`](../c-runtime-library/reference/spawnlp-wspawnlp.md)\ - [`_spawnlpe`, `_wspawnlpe`](../c-runtime-library/reference/spawnlpe-wspawnlpe.md) - :::column-end::: - :::column span=""::: - [`_spawnv`, `_wspawnv`](../c-runtime-library/reference/spawnv-wspawnv.md)\ - [`_spawnve`, `_wspawnve`](../c-runtime-library/reference/spawnve-wspawnve.md)\ - [`_spawnvp`, `_wspawnvp`](../c-runtime-library/reference/spawnvp-wspawnvp.md)\ - [`_spawnvpe`, `_wspawnvpe`](../c-runtime-library/reference/spawnvpe-wspawnvpe.md) - :::column-end::: -:::row-end::: +[`_spawnl`, `_wspawnl`](./reference/spawnl-wspawnl.md)\ +[`_spawnle`, `_wspawnle`](./reference/spawnle-wspawnle.md)\ +[`_spawnlp`, `_wspawnlp`](./reference/spawnlp-wspawnlp.md)\ +[`_spawnlpe`, `_wspawnlpe`](./reference/spawnlpe-wspawnlpe.md)\ +[`_spawnv`, `_wspawnv`](./reference/spawnv-wspawnv.md)\ +[`_spawnve`, `_wspawnve`](./reference/spawnve-wspawnve.md)\ +[`_spawnvp`, `_wspawnvp`](./reference/spawnvp-wspawnvp.md)\ +[`_spawnvpe`, `_wspawnvpe`](./reference/spawnvpe-wspawnvpe.md) The letters at the end of the function name determine the variation. -|Letter|Variant| -|-|-| -| `e` | `envp`, array of pointers to environment settings, is passed to new process. | -| `l` | Command-line arguments are passed individually to `_spawn` function. This suffix is typically used when a number of parameters to a new process are known in advance. | -| `p` | `PATH` environment variable is used to find the file to execute. | -| `v` | `argv`, array of pointers to command-line arguments, is passed to `_spawn` function. This suffix is typically used when a number of parameters to a new process are variable. | +| Letter | Variant | +|---|---| +| `e` | `envp`, array of pointers to environment settings, is passed to new process. | +| `l` | Command-line arguments are passed individually to `_spawn` function. This suffix is typically used when some parameters to a new process are known in advance. | +| `p` | `PATH` environment variable is used to find the file to execute. | +| `v` | `argv`, array of pointers to command-line arguments, is passed to `_spawn` function. This suffix is typically used when several parameters to a new process are variable. | ## Remarks The `_spawn` functions each create and execute a new process. They automatically handle multibyte-character string arguments as appropriate, recognizing multibyte-character sequences according to the multibyte code page currently in use. The `_wspawn` functions are wide-character versions of the `_spawn` functions; they don't handle multibyte-character strings. Otherwise, the `_wspawn` functions behave identically to their `_spawn` counterparts. -### Generic-Text Routine Mappings +### Generic-text routine mappings -|`Tchar.h` routine|`_UNICODE` and `_MBCS` not defined|`_MBCS` defined|`_UNICODE` defined| -|---------------------|--------------------------------------|--------------------|-----------------------| -|`_tspawnl`|`_spawnl`|`_spawnl`|`_wspawnl`| -|`_tspawnle`|`_spawnle`|`_spawnle`|`_wspawnle`| -|`_tspawnlp`|`_spawnlp`|`_spawnlp`|`_wspawnlp`| -|`_tspawnlpe`|`_spawnlpe`|`_spawnlpe`|`_wspawnlpe`| -|`_tspawnv`|`_spawnv`|`_spawnv`|`_wspawnv`| -|`_tspawnve`|`_spawnve`|`_spawnve`|`_wspawnve`| -|`_tspawnvp`|`_spawnvp`|`_spawnvp`|`_wspawnvp`| -|`_tspawnvpe`|`_spawnvpe`|`_spawnvpe`|`_wspawnvpe`| +| `Tchar.h` routine | `_UNICODE` and `_MBCS` not defined | `_MBCS` defined | `_UNICODE` defined | +|---|---|---|---| +| `_tspawnl` | `_spawnl` | `_spawnl` | `_wspawnl` | +| `_tspawnle` | `_spawnle` | `_spawnle` | `_wspawnle` | +| `_tspawnlp` | `_spawnlp` | `_spawnlp` | `_wspawnlp` | +| `_tspawnlpe` | `_spawnlpe` | `_spawnlpe` | `_wspawnlpe` | +| `_tspawnv` | `_spawnv` | `_spawnv` | `_wspawnv` | +| `_tspawnve` | `_spawnve` | `_spawnve` | `_wspawnve` | +| `_tspawnvp` | `_spawnvp` | `_spawnvp` | `_wspawnvp` | +| `_tspawnvpe` | `_spawnvpe` | `_spawnvpe` | `_wspawnvpe` | Enough memory must be available for loading and executing the new process. The `mode` argument determines the action taken by the calling process before and during `_spawn`. The following values for `mode` are defined in `Process.h`: -|Value|Description| -|-|-| -| `_P_OVERLAY` | Overlays a calling process with a new process, destroying the calling process (same effect as `_exec` calls). | -| `_P_WAIT` | Suspends a calling thread until execution of the new process is complete (synchronous `_spawn`). | -| `_P_NOWAIT` or `_P_NOWAITO` | Continues to execute a calling process concurrently with the new process (asynchronous `_spawn`). | -| `_P_DETACH` | Continues to execute the calling process; the new process is run in the background with no access to the console or keyboard. Calls to `_cwait` against the new process fail (asynchronous `_spawn`). | +| Value | Description | +|---|---| +| `_P_OVERLAY` | Overlays a calling process with a new process, destroying the calling process (same effect as `_exec` calls). | +| `_P_WAIT` | Suspends a calling thread until execution of the new process is complete (synchronous `_spawn`). | +| `_P_NOWAIT` or `_P_NOWAITO` | Continues to execute a calling process concurrently with the new process (asynchronous `_spawn`). | +| `_P_DETACH` | Continues to execute the calling process; the new process is run in the background with no access to the console or keyboard. Calls to `_cwait` against the new process fail (asynchronous `_spawn`). | The `cmdname` argument specifies the file that is executed as the new process and can specify a full path (from the root), a partial path (from the current working directory), or just a file name. If `cmdname` doesn't have a file name extension or doesn't end with a period (.), the `_spawn` function first tries the .com file name extension and then the .exe file name extension, the .bat file name extension, and finally the .cmd file name extension. @@ -73,7 +64,7 @@ In the past, some of these functions set `errno` to zero on success; the current > [!NOTE] > To ensure proper overlay initialization and termination, do not use the `setjmp` or `longjmp` function to enter or leave an overlay routine. -## Arguments for the Spawned Process +## Arguments for the spawned process To pass arguments to the new process, give one or more pointers to character strings as arguments in the `_spawn` call. These character strings form the argument list for the spawned process. The combined length of the strings forming the argument list for the new process must not exceed 1024 bytes. The terminating null character ('\0') for each string isn't included in the count, but space characters (automatically inserted to separate arguments) are included. @@ -85,13 +76,13 @@ To pass arguments to the new process, give one or more pointers to character str You can pass argument pointers as separate arguments (in `_spawnl`, `_spawnle`, `_spawnlp`, and `_spawnlpe`) or as an array of pointers (in `_spawnv`, `_spawnve`, `_spawnvp`, and `_spawnvpe`). You must pass at least one argument, `arg0` or `argv[0]`, to the spawned process. By convention, this argument is the name of the program as you would type it on the command line. A different value doesn't produce an error. -The `_spawnl`, `_spawnle`, `_spawnlp`, and `_spawnlpe` calls are typically used in cases where the number of arguments is known in advance. The `arg0` argument is usually a pointer to `cmdname`. The arguments `arg1` through `argn` are pointers to the character strings forming the new argument list. Following `argn`, there must be a **`NULL`** pointer to mark the end of the argument list. +The `_spawnl`, `_spawnle`, `_spawnlp`, and `_spawnlpe` calls are typically used in cases where the number of arguments is known in advance. The `arg0` argument is usually a pointer to `cmdname`. The arguments `arg1` through `argn` are pointers to the character strings forming the new argument list. Following `argn`, there must be a `NULL` pointer to mark the end of the argument list. -The `_spawnv`, `_spawnve`, `_spawnvp`, and `_spawnvpe` calls are useful when there's a variable number of arguments to the new process. Pointers to the arguments are passed as an array, `argv`*.* The argument `argv[0]` is usually a pointer to a path in real mode or to the program name in protected mode, and `argv[1]` through `argv[n]` are pointers to the character strings forming the new argument list. The argument `argv[n +1]` must be a **`NULL`** pointer to mark the end of the argument list. +The `_spawnv`, `_spawnve`, `_spawnvp`, and `_spawnvpe` calls are useful when there's a variable number of arguments to the new process. Pointers to the arguments are passed as an array, `argv`*.* The argument `argv[0]` is usually a pointer to a path in real mode or to the program name in protected mode, and `argv[1]` through `argv[n]` are pointers to the character strings forming the new argument list. The argument `argv[n +1]` must be a `NULL` pointer to mark the end of the argument list. ## Environment of the Spawned Process -Files that are open when a `_spawn` call is made remain open in the new process. In the `_spawnl`, `_spawnlp`, `_spawnv`, and `_spawnvp` calls, the new process inherits the environment of the calling process. You can use the `_spawnle`, `_spawnlpe`, `_spawnve`, and `_spawnvpe` calls to alter the environment for the new process by passing a list of environment settings through the `envp` argument. The argument `envp` is an array of character pointers, each element (except the final element) of which points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME`=`value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (Note that `value` isn't enclosed in double quotation marks.) The final element of the `envp` array should be **`NULL`**. When `envp` itself is **`NULL`**, the spawned process inherits the environment settings of the parent process. +Files that are open when a `_spawn` call is made remain open in the new process. In the `_spawnl`, `_spawnlp`, `_spawnv`, and `_spawnvp` calls, the new process inherits the environment of the calling process. You can use the `_spawnle`, `_spawnlpe`, `_spawnve`, and `_spawnvpe` calls to alter the environment for the new process by passing a list of environment settings through the `envp` argument. The argument `envp` is an array of character pointers, each element (except the final element) of which points to a null-terminated string defining an environment variable. Such a string usually has the form `NAME`=`value` where `NAME` is the name of an environment variable and `value` is the string value to which that variable is set. (The `value` isn't enclosed in double quotation marks.) The final element of the `envp` array should be `NULL`. When `envp` itself is `NULL`, the spawned process inherits the environment settings of the parent process. The `_spawn` functions can pass all information about open files, including the translation mode, to the new process. This information is passed in real mode through the `C_FILE_INFO` entry in the environment. The startup code normally processes this entry and then deletes it from the environment. However, if a `_spawn` function spawns a non-C process, this entry remains in the environment. Printing the environment shows graphics characters in the definition string for this entry because the environment information is passed in binary form in real mode. It shouldn't have any other effect on normal operations. In protected mode, the environment information is passed in text form and therefore contains no graphics characters. @@ -105,7 +96,7 @@ If you're calling `_spawn` from a DLL or a GUI application and want to redirect - Use the Win32 API to create a pipe, then call [`AllocConsole`](/windows/console/allocconsole), set the handle values in the startup structure, and call [`CreateProcess`](/windows/win32/api/processthreadsapi/nf-processthreadsapi-createprocessw). -- Call [`_popen`, `_wpopen`](../c-runtime-library/reference/popen-wpopen.md) which will create a pipe and invoke the app using **`cmd.exe /c`** (or **`command.exe /c`**). +- Call [`_popen` or `_wpopen`](./reference/popen-wpopen.md), which will create a pipe and invoke the app using **`cmd.exe /c`** (or **`command.exe /c`**). ## Example @@ -192,13 +183,13 @@ from SPAWN! ## See also -[Process and Environment Control](../c-runtime-library/process-and-environment-control.md)\ -[`abort`](../c-runtime-library/reference/abort.md)\ -[`atexit`](../c-runtime-library/reference/atexit.md)\ -[`_exec`, `_wexec` Functions](../c-runtime-library/exec-wexec-functions.md)\ -[`exit`, `_Exit`, `_exit`](../c-runtime-library/reference/exit-exit-exit.md)\ -[`_flushall`](../c-runtime-library/reference/flushall.md)\ -[`_getmbcp`](../c-runtime-library/reference/getmbcp.md)\ -[`_onexit`, `_onexit_m`](../c-runtime-library/reference/onexit-onexit-m.md)\ -[`_setmbcp`](../c-runtime-library/reference/setmbcp.md)\ -[`system`, `_wsystem`](../c-runtime-library/reference/system-wsystem.md) +[Process and environment control](./process-and-environment-control.md)\ +[`abort`](./reference/abort.md)\ +[`atexit`](./reference/atexit.md)\ +[`_exec`, `_wexec` functions](./exec-wexec-functions.md)\ +[`exit`, `_Exit`, `_exit`](./reference/exit-exit-exit.md)\ +[`_flushall`](./reference/flushall.md)\ +[`_getmbcp`](./reference/getmbcp.md)\ +[`_onexit`, `_onexit_m`](./reference/onexit-onexit-m.md)\ +[`_setmbcp`](./reference/setmbcp.md)\ +[`system`, `_wsystem`](./reference/system-wsystem.md) diff --git a/docs/c-runtime-library/standard-types.md b/docs/c-runtime-library/standard-types.md index 037336c552d..f5e544a7d28 100644 --- a/docs/c-runtime-library/standard-types.md +++ b/docs/c-runtime-library/standard-types.md @@ -1,97 +1,97 @@ --- description: "Learn more about: Standard Types" title: "Standard Types" -ms.date: "11/04/2016" -f1_keywords: ["__time64_t", "_diskfree_t", "_CRT_DUMP_CLIENT", "_fsize_t", "__timeb64", "File", "__utimeb64", "jmp_buf", "__finddata64_t", "_wfinddata_t", "_finddata_t", "utimbuf64", "wint_t", "wctrans_t", "wctype_t", "_HFILE", "_secerr_handler_func", "clock_t", "fpos_t", "_dev_t", "time64_t", "wfinddata64_t", "stat64", "ldiv_t", "_EXCEPTION_POINTERS", "terminate_function", "size_t", "timeb64", "tm", "_HEAPINFO", "unexpected_function", "_CrtMemState", "_se_translator_function", "sig_atomic_t", "_CRT_REPORT_HOOK", "_complex", "_w_finddatai64_t", "_timeb", "_onexit_t", "_RTC_ErrorNumber", "lconv", "_PNH", "_off_t", "ptrdiff_t", "time_t", "_FPIEEE_RECORD", "_exception", "__w_finddata64_t", "__stat64", "_utimbuf", "__utimbuf64", "div_t", "_CRT_ALLOC_HOOK", "int8_t", "uint8_t", "int16_t", "uint16_t", "int32_t", "uint32_t", "int64_t", "int_least8_t", "uint_least8_t", "int_least16_t", "uint_least16_t", "int_least32_t", "uint_least32_t", "int_least64_t", "uint_least64_t", "int_fast8_t", "uint_fast8_t", "int_fast16_t", "uint_fast16_t", "int_fast32_t", "uint_fast32_t", "int_fast64_t", "uint_fast64_t", "intmax_t", "uintmax_t"] -helpviewer_keywords: ["__timeb64 type", "tm type", "clock_t type", "intptr_t type", "diskfree_t type", "wctype_t type", "CRT_DUMP_CLIENT type", "sig_atomic_t type", "_PNH type", "time_t type", "wfinddata_t type", "timeb64", "CRT, standard types", "wint_t type", "_RTC_ErrorNumber type", "_diskfree_t type", "_dev_t type", "_wfinddata_t type", "HFILE type", "__utimbuf64 type", "div_t type", "_onexit_t type", "_secerr_handler_func type", "FPIEEE_RECORD type", "HEAPINFO type", "PNH type", "_CRT_ALLOC_HOOK type", "_se_translater_function type", "va_list type", "wctrans_t type", "secerr_handler_func type", "_locale_t type", "timeb type", "lconv type", "utimbuf type", "dev_t type", "unexpected_function typedef", "_complex type", "_off_t type", "off_t type", "RTC_ErrorNumber type", "_FPIEEE_RECORD type", "exception type", "_CRT_REPORT_HOOK type", "_HEAPINFO type", "ldiv_t type", "terminate_function type", "uintptr_t type", "_CRT_DUMP_CLIENT type", "_utimbuf type", "wfinddatai64_t type", "fpos_t type", "wchar_t type", "CRT_ALLOC_HOOK type", "_HFILE type", "__time64_t type", "_timeb type", "CrtMemState type", "__finddata64_t type", "_exception type", "stat type", "onexit_t type", "FILE constant", "_stat type", "finddata_t type", "__wfinddata64_t type", "ptrdiff_t type", "complex types", "_wfinddatai64_t type", "_EXCEPTION_POINTERS type", "jmp_buf type", "se_translater_function type", "size_t type", "EXCEPTION_POINTERS type", "__stat64 type", "_fsize_t type", "CRT_REPORT_HOOK type", "_finddata_t type"] +ms.date: 01/26/2023 +f1_keywords: ["CORECRT_IO/__finddata64_t", "CORECRT_IO/_finddata_t", "CORECRT_MATH/_complex", "CORECRT_MATH/_exception", "CORECRT_STARTUP/_EXCEPTION_POINTERS", "CORECRT_STARTUP/_onexit_t", "CORECRT_TERMINATE/terminate_function", "CORECRT_WIO/_fsize_t", "CORECRT_WIO/_wfinddata_t", "CORECRT_WIO/_wfinddata64_t", "CORECRT_WIO/_wfinddatai64_t", "CORECRT_WSTDIO/FILE", "CORECRT_WTIME/tm", "CORECRT/__time64_t", "CORECRT/time_t", "CORECRT/wctype_t", "CORECRT/wint_t", "CRTDBG/_CRT_ALLOC_HOOK", "CRTDBG/_CRT_DUMP_CLIENT", "CRTDBG/_CRT_REPORT_HOOK", "CRTDBG/_CrtMemState", "CRTDBG/_HFILE", "DIRECT/_diskfree_t", "EH/_se_translator_function", "EH/unexpected_function", "FPIEEE/_FPIEEE_RECORD", "LOCALE/lconv", "MALLOC/_HEAPINFO", "NEW/_PNH", "RTCAPI/_RTC_ErrorNumber", "SETJMP/jmp_buf", "SIGNAL/sig_atomic_t", "STDINT/int_fast16_t", "STDINT/int_fast32_t", "STDINT/int_fast64_t", "STDINT/int_fast8_t", "STDINT/int_least16_t", "STDINT/int_least32_t", "STDINT/int_least64_t", "STDINT/int_least8_t", "STDINT/int16_t", "STDINT/int32_t", "STDINT/int64_t", "STDINT/int8_t", "STDINT/intmax_t", "STDINT/uint_fast16_t", "STDINT/uint_fast32_t", "STDINT/uint_fast64_t", "STDINT/uint_fast8_t", "STDINT/uint_least16_t", "STDINT/uint_least32_t", "STDINT/uint_least64_t", "STDINT/uint_least8_t", "STDINT/uint16_t", "STDINT/uint32_t", "STDINT/uint64_t", "STDINT/uint8_t", "STDINT/uintmax_t", "STDIO/fpos_t", "STDLIB/div_t", "STDLIB/ldiv_t", "TIME/clock_t", "TIMEB/__timeb64", "TIMEB/_timeb", "TYPES/_dev_t", "TYPES/_off_t", "UTIME/__utimbuf64", "UTIME/_utimbuf", "VCRUNTIME/ptrdiff_t", "VCRUNTIME/size_t", "WCTYPE/wctrans_t", "__finddata64_t", "_finddata_t", "_complex", "_exception", "_EXCEPTION_POINTERS", "_onexit_t", "terminate_function", "_fsize_t", "_wfinddata_t", "_wfinddata64_t", "_wfinddatai64_t", "FILE", "tm", "__time64_t", "time_t", "wctype_t", "wint_t", "_CRT_ALLOC_HOOK", "_CRT_DUMP_CLIENT", "_CRT_REPORT_HOOK", "_CrtMemState", "_HFILE", "_diskfree_t", "_se_translator_function", "unexpected_function", "_FPIEEE_RECORD", "lconv", "_HEAPINFO", "_PNH", "_RTC_ErrorNumber", "jmp_buf", "sig_atomic_t", "int_fast16_t", "int_fast32_t", "int_fast64_t", "int_fast8_t", "int_least16_t", "int_least32_t", "int_least64_t", "int_least8_t", "int16_t", "int32_t", "int64_t", "int8_t", "intmax_t", "uint_fast16_t", "uint_fast32_t", "uint_fast64_t", "uint_fast8_t", "uint_least16_t", "uint_least32_t", "uint_least64_t", "uint_least8_t", "uint16_t", "uint32_t", "uint64_t", "uint8_t", "uintmax_t", "fpos_t", "div_t", "ldiv_t", "clock_t", "__timeb64", "_timeb", "_dev_t", "_off_t", "__utimbuf64", "_utimbuf", "ptrdiff_t", "size_t", "wctrans_t"] +helpviewer_keywords: ["__timeb64 type", "tm type", "clock_t type", "intptr_t type", "diskfree_t type", "wctype_t type", "CRT_DUMP_CLIENT type", "sig_atomic_t type", "_PNH type", "time_t type", "wfinddata_t type", "timeb64", "CRT, standard types", "wint_t type", "_RTC_ErrorNumber type", "_diskfree_t type", "_dev_t type", "_wfinddata_t type", "HFILE type", "__utimbuf64 type", "div_t type", "_onexit_t type", "_secerr_handler_func type", "FPIEEE_RECORD type", "HEAPINFO type", "PNH type", "_CRT_ALLOC_HOOK type", "_se_translater_function type", "va_list type", "wctrans_t type", "secerr_handler_func type", "_locale_t type", "timeb type", "lconv type", "utimbuf type", "dev_t type", "unexpected_function typedef", "_complex type", "_off_t type", "off_t type", "RTC_ErrorNumber type", "_FPIEEE_RECORD type", "exception type", "_CRT_REPORT_HOOK type", "_HEAPINFO type", "ldiv_t type", "terminate_function type", "uintptr_t type", "_CRT_DUMP_CLIENT type", "_utimbuf type", "wfinddatai64_t type", "fpos_t type", "wchar_t type", "CRT_ALLOC_HOOK type", "_HFILE type", "__time64_t type", "_timeb type", "CrtMemState type", "__finddata64_t type", "_exception type", "stat type", "onexit_t type", "FILE constant", "_stat type", "finddata_t type", "_wfinddata64_t type", "ptrdiff_t type", "complex types", "_wfinddatai64_t type", "_EXCEPTION_POINTERS type", "jmp_buf type", "se_translater_function type", "size_t type", "EXCEPTION_POINTERS type", "__stat64 type", "_fsize_t type", "CRT_REPORT_HOOK type", "_finddata_t type"] ms.assetid: 23312dd2-4a6a-4d70-9b48-2a5d0d8c9f28 --- -# Standard Types +# Standard types The Microsoft run-time library defines the following standard types and typedefs. ### Fixed-width integral types (`stdint.h`) -|Name|Equivalent built-in type| -|----------|-------------------------------| -|`int8_t`, `uint8_t`|`signed char`, `unsigned char`| -|`int16_t`, `uint16_t`|`short`, `unsigned short`| -|`int32_t`, `uint32_t`|`int`, `unsigned int`| -|`int64_t`, `uint64_t`|`long long`, `unsigned long long`| -|`int_least8_t`, `uint_least8_t`|`signed char`, `unsigned char`| -|`int_least16_t`, `uint_least16_t`|`short`, `unsigned short`| -|`int_least32_t`, `uint_least32_t`|`int`, `unsigned int`| -|`int_least64_t`, `uint_least64_t`|`long long`, `unsigned long long`| -|`int_fast8_t`, `uint_fast8_t`|`signed char`, `unsigned char`| -|`int_fast16_t`, `uint_fast16_t`|`int`, `unsigned int`| -|`int_fast32_t`, `uint_fast32_t`|`int`, `unsigned int`| -|`int_fast64_t`, `uint_fast64_t`|`long long`, `unsigned long long`| -|`intmax_t`, `uintmax_t`|`long long`, `unsigned long long`| +| Name | Equivalent built-in type | +|---|---| +| `int8_t`, `uint8_t` | `signed char`, `unsigned char` | +| `int16_t`, `uint16_t` | `short`, `unsigned short` | +| `int32_t`, `uint32_t` | `int`, `unsigned int` | +| `int64_t`, `uint64_t` | `long long`, `unsigned long long` | +| `int_least8_t`, `uint_least8_t` | `signed char`, `unsigned char` | +| `int_least16_t`, `uint_least16_t` | `short`, `unsigned short` | +| `int_least32_t`, `uint_least32_t` | `int`, `unsigned int` | +| `int_least64_t`, `uint_least64_t` | `long long`, `unsigned long long` | +| `int_fast8_t`, `uint_fast8_t` | `signed char`, `unsigned char` | +| `int_fast16_t`, `uint_fast16_t` | `int`, `unsigned int` | +| `int_fast32_t`, `uint_fast32_t` | `int`, `unsigned int` | +| `int_fast64_t`, `uint_fast64_t` | `long long`, `unsigned long long` | +| `intmax_t`, `uintmax_t` | `long long`, `unsigned long long` | -|Type|Description|Declared in| -|----------|-----------------|-----------------| -|`clock_t` (long)|Stores time values; used by [`clock`](../c-runtime-library/reference/clock.md).|`TIME.H`| -|`_complex` structure|Stores real and imaginary parts of complex numbers; used by [`_cabs`](../c-runtime-library/reference/cabs.md).|`MATH.H`| -|`_CRT_ALLOC_HOOK`|A type define for the user-defined hook function. Used in [`_CrtSetAllocHook`](../c-runtime-library/reference/crtsetallochook.md).|`CRTDBG.H`| -|`_CRT_DUMP_CLIENT`,

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

`_CRT_REPORT_HOOKW`,

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

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

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

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

`_LONGDOUBLE`,

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

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

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

`SYS\STAT.H`,

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

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

`SYS\STAT.H`,

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

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

`CRTDEFS.H`,

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

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

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

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

`_CRT_REPORT_HOOKW`,

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

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

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

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

`_LONGDOUBLE`,

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

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

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

`SYS\STAT.H`,

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

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

`SYS\STAT.H`,

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

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

`CRTDEFS.H`,

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

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

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

`_Lock_kind_mutex_`
Lock kind ID for mutexes.

`_Lock_kind_event_`
Lock kind ID for events.

`_Lock_kind_semaphore_`
Lock kind ID for semaphores.

`_Lock_kind_spin_lock_`
Lock kind ID for spin locks.

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

`_Lock_kind_mutex_`
Lock kind ID for mutexes.

`_Lock_kind_event_`
Lock kind ID for events.

`_Lock_kind_semaphore_`
Lock kind ID for semaphores.

`_Lock_kind_spin_lock_`
Lock kind ID for spin locks.

`_Lock_kind_critical_section_`
Lock kind ID for critical sections.| |`_Has_lock_level_(name)`|Annotates a lock object and gives it the lock level of `name`.| |`_Lock_level_order_(name1, name2)`|A statement that gives the lock ordering between `name1` and `name2`. Locks that have level `name1` must be acquired before locks that have level `name2`.| -|`_Post_same_lock_(expr1, expr2)`|Annotates a function and indicates that in post state the two locks, `expr1` and `expr2`, are treated as if they are the same lock object.| +|`_Post_same_lock_(dst, src)`|Annotates a function and indicates that in post state the two locks, `dst` and `src`, are treated as if they're the same lock object, by applying lock properties from `src` to `dst`.| |`_Releases_exclusive_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the exclusive lock count of the lock object that's named by `expr`.| |`_Releases_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the lock count of the lock object that's named by `expr`.| -|`_Releases_nonreentrant_lock_(expr)`|The lock that's named by `expr` is released. An error is reported if the lock is not currently held.| +|`_Releases_nonreentrant_lock_(expr)`|The lock that's named by `expr` is released. An error is reported if the lock isn't currently held.| |`_Releases_shared_lock_(expr)`|Annotates a function and indicates that in post state the function decrements by one the shared lock count of the lock object that's named by `expr`.| |`_Requires_lock_held_(expr)`|Annotates a function and indicates that in pre state the lock count of the object that's named by `expr` is at least one.| |`_Requires_lock_not_held_(expr)`|Annotates a function and indicates that in pre state the lock count of the object that's named by `expr` is zero.| @@ -80,7 +80,7 @@ The following table lists the locking annotations. ## SAL Intrinsics For Unexposed Locking Objects -Certain lock objects are not exposed by the implementation of the associated locking functions. The following table lists SAL intrinsic variables that enable annotations on functions that operate on those unexposed lock objects. +Certain lock objects aren't exposed by the implementation of the associated locking functions. The following table lists SAL intrinsic variables that enable annotations on functions that operate on those unexposed lock objects. |Annotation|Description| |----------------|-----------------| @@ -97,21 +97,21 @@ The following table lists the annotations for shared data access. |----------------|-----------------| |`_Guarded_by_(expr)`|Annotates a variable and indicates that whenever the variable is accessed, the lock count of the lock object that's named by `expr` is at least one.| |`_Interlocked_`|Annotates a variable and is equivalent to `_Guarded_by_(_Global_interlock_)`.| -|`_Interlocked_operand_`|The annotated function parameter is the target operand of one of the various Interlocked functions. Those operands must have specific additional properties.| +|`_Interlocked_operand_`|The annotated function parameter is the target operand of one of the various Interlocked functions. Those operands must have other specific properties.| |`_Write_guarded_by_(expr)`|Annotates a variable and indicates that whenever the variable is modified, the lock count of the lock object that's named by `expr` is at least one.| ## Smart Lock and RAII Annotations -Smart locks typically wrap native locks and manage their lifetime. The following table lists annotations that can be used with smart locks and RAII coding patterns with support for `move` semantics. +Smart locks typically wrap native locks and manage their lifetime. The following table lists annotations that can be used with smart locks and Resource Acquisition Is Initialization (RAII) coding patterns with support for `move` semantics. |Annotation|Description| |----------------|-----------------| -|`_Analysis_assume_smart_lock_acquired_`|Tells the analyzer to assume that a smart lock has been acquired. This annotation expects a reference lock type as its parameter.| -|`_Analysis_assume_smart_lock_released_`|Tells the analyzer to assume that a smart lock has been released. This annotation expects a reference lock type as its parameter.| -|`_Moves_lock_(target, source)`|Describes `move constructor` operation which transfers lock state from the `source` object to the `target`. The `target` is considered a newly constructed object, so any state it had before is lost and replaced by the `source` state. The `source` is also reset to a clean state with no lock counts or aliasing target, but aliases pointing to it remain unchanged.| -|`_Replaces_lock_(target, source)`|Describes `move assignment operator` semantics where the target lock is released before transferring the state from the source. This can be regarded as a combination of `_Moves_lock_(target, source)` preceded by a `_Releases_lock_(target)`.| -|`_Swaps_locks_(left, right)`|Describes the standard `swap` behavior which assumes that objects `left` and `right` exchange their state. The state exchanged includes lock count and aliasing target, if present. Aliases that point to the `left` and `right` objects remain unchanged.| -|`_Detaches_lock_(detached, lock)`|Describes a scenario in which a lock wrapper type allows dissociation with its contained resource. This is similar to how `std::unique_ptr` works with its internal pointer: it allows programmers to extract the pointer and leave its smart pointer container in a clean state. Similar logic is supported by `std::unique_lock` and can be implemented in custom lock wrappers. The detached lock retains its state (lock count and aliasing target, if any), while the wrapper is reset to contain zero lock count and no aliasing target, while retaining its own aliases. There's no operation on lock counts (releasing and acquiring). This annotation behaves exactly as `_Moves_lock_` except that the detached argument should be **`return`** rather than **`this`**.| +|`_Analysis_assume_smart_lock_acquired_(lock)`|Tells the analyzer to assume that a smart lock was acquired. This annotation expects a reference lock type as its parameter.| +|`_Analysis_assume_smart_lock_released_(lock)`|Tells the analyzer to assume that a smart lock was released. This annotation expects a reference lock type as its parameter.| +|`_Moves_lock_(target, source)`|Describes a `move constructor` operation, which transfers lock state from the `source` object to the `target`. The `target` is considered a newly constructed object, so any state it had before is lost and replaced by the `source` state. The `source` is also reset to a clean state with no lock counts or aliasing target, but aliases pointing to it remain unchanged.| +|`_Replaces_lock_(target, source)`|Describes `move assignment operator` semantics where the target lock is released before transferring the state from the source. You can regard it as a combination of `_Moves_lock_(target, source)` preceded by a `_Releases_lock_(target)`.| +|`_Swaps_locks_(left, right)`|Describes the standard `swap` behavior, which assumes that objects `left` and `right` exchange their state. The state exchanged includes lock count and aliasing target, if present. Aliases that point to the `left` and `right` objects remain unchanged.| +|`_Detaches_lock_(detached, lock)`|Describes a scenario in which a lock wrapper type allows dissociation with its contained resource. It's similar to how `std::unique_ptr` works with its internal pointer: it allows programmers to extract the pointer and leave its smart pointer container in a clean state. Similar logic is supported by `std::unique_lock` and can be implemented in custom lock wrappers. The detached lock retains its state (lock count and aliasing target, if any), while the wrapper is reset to contain zero lock count and no aliasing target, while retaining its own aliases. There's no operation on lock counts (releasing and acquiring). This annotation behaves exactly as `_Moves_lock_` except that the detached argument should be **`return`** rather than **`this`**.| ## See also diff --git a/docs/code-quality/annotating-structs-and-classes.md b/docs/code-quality/annotating-structs-and-classes.md index f58ce2ad826..fdc83bc210b 100644 --- a/docs/code-quality/annotating-structs-and-classes.md +++ b/docs/code-quality/annotating-structs-and-classes.md @@ -1,8 +1,8 @@ --- -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" +ms.topic: "concept-article" f1_keywords: - "_Field_size_bytes_part_" - "_Field_size_bytes_full_opt_" @@ -19,7 +19,6 @@ f1_keywords: - "_Field_size_full_" - "_Field_size_full_opt_" - "_Field_z_" -ms.assetid: b8278a4a-c86e-4845-aa2a-70da21a1dd52 --- # Annotating Structs and Classes @@ -52,13 +51,11 @@ You can annotate struct and class members by using annotations that act like inv Applies to struct or class declaration. Indicates that a valid object of that type may be larger than the declared type, with the number of bytes being specified by `size`. For example: ```cpp - typedef _Struct_size_bytes_(nSize) struct MyStruct { size_t nSize; ... }; - ``` The buffer size in bytes of a parameter `pM` of type `MyStruct *` is then taken to be: @@ -97,7 +94,7 @@ Notes for this example: - `_Field_z_` is equivalent to `_Null_terminated_`. `_Field_z_` for the name field specifies that the name field is a null-terminated string. - `_Field_range_` for `bufferSize` specifies that the value of `bufferSize` should be within 1 and `MaxBufferSize` (both inclusive). -- The end results of the `_Struct_size_bytes_` and `_Field_size_` annotations are equivalent. For structures or classes that have a similar layout, `_Field_size_` is easier to read and maintain, because it has fewer references and calculations than the equivalent `_Struct_size_bytes_` annotation. `_Field_size_` doesn’t require conversion to the byte size. If byte size is the only option, for example, for a void pointer field, `_Field_size_bytes_` can be used. If both `_Struct_size_bytes_` and `_Field_size_` exist, both will be available to tools. It is up to the tool what to do if the two annotations disagree. +- The end results of the `_Struct_size_bytes_` and `_Field_size_` annotations are equivalent. For structures or classes that have a similar layout, `_Field_size_` is easier to read and maintain, because it has fewer references and calculations than the equivalent `_Struct_size_bytes_` annotation. `_Field_size_` doesn't require conversion to the byte size. If byte size is the only option, for example, for a void pointer field, `_Field_size_bytes_` can be used. If both `_Struct_size_bytes_` and `_Field_size_` exist, both will be available to tools. It is up to the tool what to do if the two annotations disagree. ## See also diff --git a/docs/code-quality/best-practices-and-examples-sal.md b/docs/code-quality/best-practices-and-examples-sal.md index ad538573111..aa2b6e986b0 100644 --- a/docs/code-quality/best-practices-and-examples-sal.md +++ b/docs/code-quality/best-practices-and-examples-sal.md @@ -1,8 +1,8 @@ --- description: "Learn more about: Best practices and examples (SAL)" title: Best practices and examples (SAL) -ms.date: 01/27/2022 -ms.topic: "conceptual" +ms.date: 03/30/2023 +ms.topic: "best-practice" --- # 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 00000000000..2f31f19fc15 --- /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: "concept-article" +--- + +# 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` - Microsoft C++ compiler](../build/reference/analyze-code-analysis.md) +- [`/W4` and `/WX` - Microsoft 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 Studio 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 Microsoft 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 Microsoft 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 Microsoft 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 Microsoft 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 C++ on Windows, Microsoft recommends: + +- Prefer TypeScript, JavaScript, and ASP.NET for web applications. +- Don't write web extensions in C++. Microsoft has deprecated ActiveX. +- When code is compiled to Emscripten/WASM, it's no longer C++ and other tools apply. +- Microsoft provides [RESTler, a stateful REST API fuzzer](https://github.com/microsoft/restler-fuzzer). + +**Overview and key qualities** + +A web application scanner explores a web application by crawling through its web pages and examines it for security vulnerabilities. This crawl involves the automatic generation of malicious inputs and evaluation of the application's responses. Critically, web application scanning must cover/support: + +- Catalogs all web apps in your network, including new and unknown ones, and scales from a handful of apps to thousands. +- Deep scanning for software versions, SOAP and REST API services and APIs used by mobile devices. +- Insertion of security primitives into application development and deployment in DevOps environments. These primitives work with the crawler. +- Malware detection. + +## 2.11 Check Included Software Components + +**Summary** + +Handle your C++ code the same as code written in other programming languages, and apply any Software Composition Analysis (SCA) and Origin Analysis (OA) tooling adopted by your company to your C++ code. Workflows and security scanning should be designed as part of CI/CD (continuous integration and continuous delivery) systems. + +**Upstream defense** + +To mitigate the risk of attacks on upstream dependencies, third party sources/components should be stored on an enterprise-controlled asset, against which SCA and OA tools are run. +- Tools should scan and alert when vulnerabilities are identified (including public databases) such as: [Home | CVE](https://www.cve.org/) +- Run static analysis on all software components included in your application/repo to identify vulnerable code patterns. + +**Dependency defense** + +Perform and maintain an audit of dependencies to validate that all such occurrences are accounted for and covered by your SCA and OA tools. +- Components should be regularly audited and updated to the latest verified versions. +- Package feed dependencies. +- SCA/OA tools cover and audit all package dependencies that come from a single feed. + +**SBOM** + +Produce an SBOM (software bill of materials) with your product listing all dependencies such as: +- origin (for example, URL (Uniform Resource Locator)) +- version +- consistency (for example, SHA-256 source hash), and other means for validating consistency such as deterministic builds. +- Require and audit SBOM files in software dependencies or produced as part of a build including OSS (open-source software). +- Microsoft is standardizing on and recommends [SPDX (Software Package Data Exchange) version 2.2 or later | Linux Foundation](https://spdx.dev/specifications/) as the SBOM document format. +- Build determinism can be used to independently produce bit-wise identical binaries and provide independent verifications of integrity: + - First-party or third-party attestation of reproducibility + - Other techniques such as binary signing via a trusted certificate source can also provide some assurances of binary integrity. + +**Additional resources** + +Microsoft solutions include the following guidance and products: +- [Microsoft Supply Chain Platform | Microsoft](https://www.microsoft.com/microsoft-cloud/solutions/microsoft-supply-chain-platform) +- [Secure your software supply chain | GitHub Security](https://github.com/features/security/software-supply-chain) +- [vcpkg](/vcpkg/) - vcpkg private registries allow redirection of OSS acquisition to Enterprise-controlled resources for acquiring sources for a dependency, to minimize risk of upstream or over-the-wire attacks. diff --git a/docs/code-quality/c1250.md b/docs/code-quality/c1250.md index 8f26a647061..593bf2fe4df 100644 --- a/docs/code-quality/c1250.md +++ b/docs/code-quality/c1250.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C1250" -title: C1250 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1250"] +title: "Fatal error C1250" +description: "Learn more about: Fatal error C1250" +ms.date: 10/04/2022 +f1_keywords: ["C1250", "FATALERROR_UnableToLoadPlugin"] helpviewer_keywords: ["C1250"] -ms.assetid: 3f2385d7-e0d6-4574-8cea-342e82d0aea4 --- -# C1250 +# Fatal error C1250 -> warning C1250: Unable to load plug-in. +> Unable to load plug-in '*plugin-name*'. -The Code Analysis tool reports this warning when there is an internal error in the plugin, not in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1251.md b/docs/code-quality/c1251.md index c24156a79e4..369f49e98ea 100644 --- a/docs/code-quality/c1251.md +++ b/docs/code-quality/c1251.md @@ -1,12 +1,14 @@ --- -description: "Learn more about: C1251" -title: C1251 -ms.date: 11/04/2016 -ms.topic: reference -ms.assetid: 0b46e0a5-c290-48d8-ba4e-f526ae68993b +title: "Fatal error C1251" +description: "Learn more about: Fatal error C1251" +ms.date: 10/04/2022 +f1_keywords: ["C1251", "FATALERROR_UnableToLoadModel"] +helpviewer_keywords: ["C1251"] --- -# C1251 +# Fatal error C1251 -> warning C1251: Unable to load models. +> Unable to load models. -The Code Analysis tool reports this warning when there is an internal error in the model file, not in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the model file, not in the code being analyzed. diff --git a/docs/code-quality/c1252.md b/docs/code-quality/c1252.md index 300e92597a5..3e679ec2d38 100644 --- a/docs/code-quality/c1252.md +++ b/docs/code-quality/c1252.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: C1252" -title: C1252 -ms.date: 06/01/2022 -ms.topic: reference -f1_keywords: ["C1252"] +title: "Fatal error C1252" +description: "Learn more about: Fatal error C1252" +ms.date: 10/04/2022 +f1_keywords: ["C1252", "FATALERROR_CircularDependency"] helpviewer_keywords: ["C1252"] -ms.assetid: e88bf199-890d-4582-bb5c-c1238797145b --- -# C1252 +# Fatal error C1252 -> warning C1252: Circular or missing dependency between plugins: '*plugin-name*' requires GUID '*globally-unique-identifier*' +> Circular or missing dependency between plugins: '*plugin-name*' requires GUID '*globally-unique-identifier*' -The Code Analysis tool reports this warning when there's an internal error in the plugin dependencies. It's not caused by an issue in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the plugin dependencies. It's not caused by an issue in the code being analyzed. In some cases, it's possible to work around this issue by disabling the **Enable Code Analysis on Build** property. To disable this build property, open the Property pages dialog for your project. In the **Solution Explorer** window, right-click on the project (not the solution) and select **Properties** in the shortcut menu. Set the **Configuration** to **All Configurations** and the **Platform** to **All Platforms**. Open the **Configuration Properties** > **Code Analysis** > **General** property page. Modify the **Enable Code Analysis on Build** property to **No**. Choose **OK** to save your changes, and then save your project files. Rebuild your project to verify that the issue no longer occurs. diff --git a/docs/code-quality/c1253.md b/docs/code-quality/c1253.md index 665fad98cf1..568be82155e 100644 --- a/docs/code-quality/c1253.md +++ b/docs/code-quality/c1253.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C1253" -title: C1253 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1253"] +title: "Fatal error C1253" +description: "Learn more about: Fatal error C1253" +ms.date: 10/04/2022 +f1_keywords: ["C1253", "FATALERROR_UnableToLoadModelFile"] helpviewer_keywords: ["C1253"] -ms.assetid: 21a4062f-fde8-40e5-8dbd-6f892926d3d2 --- -# C1253 +# Fatal error C1253 -> warning C1253: Unable to load model file. +> Unable to load model file. -The Code Analysis tool reports this warning when there is an internal error in the model file, not in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the model file, not in the code being analyzed. diff --git a/docs/code-quality/c1254.md b/docs/code-quality/c1254.md index c54bb701160..b77f3f40da4 100644 --- a/docs/code-quality/c1254.md +++ b/docs/code-quality/c1254.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C1254" -title: C1254 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1254"] +title: "Fatal error C1254" +description: "Learn more about: Fatal error C1254" +ms.date: 10/04/2022 +f1_keywords: ["C1254", "FATALERROR_PluginVersionMismatch"] helpviewer_keywords: ["C1254"] -ms.assetid: cb1377cf-869e-432d-941f-71f77134f97a --- -# C1254 +# Fatal error C1254 -> warning C1254: Plugin version mismatch : version doesn't match the version of the PREfast driver +> Plugin version mismatch: '*module*' version '*version-number*' doesn't match the version '*version-number*' of the PREfast driver -The Code Analysis tool reports this warning when there is an internal error with the plugin version, not in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error with the plugin version, not in the code being analyzed. diff --git a/docs/code-quality/c1255.md b/docs/code-quality/c1255.md index 883029a8fd4..1f3b9d92e50 100644 --- a/docs/code-quality/c1255.md +++ b/docs/code-quality/c1255.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C1255" -title: C1255 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1255"] +title: "Fatal error C1255" +description: "Learn more about: Fatal error C1255" +ms.date: 10/04/2022 +f1_keywords: ["C1255", "FATALERROR_PCHSyncLost"] helpviewer_keywords: ["C1255"] -ms.assetid: a97da6bd-06dc-42bf-9158-0de1ebb90d4a --- -# C1255 +# Fatal error C1255 -> warning C1255: PCH data for plugin has incorrect length. +> PCH data for plugin '*plugin-name*' has incorrect length. -The Code Analysis tool reports this warning when there is an internal error in the tool, not in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the tool, not in the code being analyzed. diff --git a/docs/code-quality/c1256.md b/docs/code-quality/c1256.md index ac9492478b2..bdf7af0eff0 100644 --- a/docs/code-quality/c1256.md +++ b/docs/code-quality/c1256.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C1256" -title: C1256 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1256"] +title: "Fatal error C1256" +description: "Learn more about: Fatal error C1256" +ms.date: 10/04/2022 +f1_keywords: ["C1256", "FATALERROR_PCHInconsistent"] helpviewer_keywords: ["C1256"] -ms.assetid: 4d65e495-f9d9-435c-ba51-1cf5b4cc2309 --- -# C1256 +# Fatal error C1256 -> warning C1256: PCH must be both written and read. +> '*plugin-name*': PCH must be both written and read. -The Code Analysis tool reports this warning when there is an internal error in the tool, not in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the tool, not in the code being analyzed. diff --git a/docs/code-quality/c1257.md b/docs/code-quality/c1257.md index bea6022a24b..b4e698c29b9 100644 --- a/docs/code-quality/c1257.md +++ b/docs/code-quality/c1257.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C1257" -title: C1257 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C1257"] +title: "Fatal error C1257" +description: "Learn more about: Fatal error C1257" +ms.date: 10/04/2022 +f1_keywords: ["C1257", "FATALERROR_InitFailure"] helpviewer_keywords: ["C1257"] -ms.assetid: 38d3ec05-01ba-42b3-aac6-077e92bf2ded --- -# C1257 +# Fatal error C1257 -> warning C1257: Plugin Initialization Failure. +> '*Plugin-name*': Initialization Failure. -The Code Analysis tool reports this warning when there is an internal error in the plugin, not in the code being analyzed. +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1258.md b/docs/code-quality/c1258.md new file mode 100644 index 00000000000..46de1a74a71 --- /dev/null +++ b/docs/code-quality/c1258.md @@ -0,0 +1,14 @@ +--- +title: "Fatal error C1258" +description: "Learn more about: Fatal error C1258" +ms.date: 10/04/2022 +f1_keywords: ["C1258", "FATALERROR_SaveToXmlFailed"] +helpviewer_keywords: ["C1258"] +--- +# Fatal error C1258 + +> Failed to save XML Log file '*filename*'. *Message*. + +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1259.md b/docs/code-quality/c1259.md new file mode 100644 index 00000000000..0dd892f8aee --- /dev/null +++ b/docs/code-quality/c1259.md @@ -0,0 +1,14 @@ +--- +title: "Fatal error C1259" +description: "Learn more about: Fatal error C1259" +ms.date: 10/04/2022 +f1_keywords: ["C1259", "FATALERROR_FatalError"] +helpviewer_keywords: ["C1259"] +--- +# Fatal error C1259 + +> A fatal error was issued by a plugin. + +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c1260.md b/docs/code-quality/c1260.md new file mode 100644 index 00000000000..8142771589a --- /dev/null +++ b/docs/code-quality/c1260.md @@ -0,0 +1,14 @@ +--- +title: "Fatal error C1260" +description: "Learn more about: Fatal error C1260" +ms.date: 10/04/2022 +f1_keywords: ["C1260", "FATALERROR_DuplicateId"] +helpviewer_keywords: ["C1260"] +--- +# Fatal error C1260 + +> The plugins '*plugin-1*' and '*plugin-2*' share the same id. It is not supported to load the same plugin twice. + +## Remarks + +The Code Analysis tool reports this error when there's an internal error in the plugin, not in the code being analyzed. diff --git a/docs/code-quality/c26100.md b/docs/code-quality/c26100.md index b15fa6d5b31..c0a64ac0408 100644 --- a/docs/code-quality/c26100.md +++ b/docs/code-quality/c26100.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C26100" -title: C26100 +title: "Warning C26100" +description: "Learn more about: Warning C26100" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C26100"] +f1_keywords: ["C26100", "RACE_CONDITION", "__WARNING_RACE_CONDITION"] helpviewer_keywords: ["C26100"] -ms.assetid: 470ab2b2-5b55-424f-b192-3863a773c892 --- -# C26100 +# Warning C26100 -> warning C26100: Race condition. Variable \ should be protected by lock \. +> Race condition. Variable '*var*' should be protected by lock '*lock*'. + +## Remarks The `_Guarded_by_` annotation in the code specifies the lock to use to guard a shared variable. Warning C26100 is generated when the guard contract is violated. +Code analysis name: `RACE_CONDITION` + ## Examples -The following example generates warning C26100 because there is a violation of the `_Guarded_by_` contract. +The following example generates warning C26100 because there's a violation of the `_Guarded_by_` contract. ```cpp CRITICAL_SECTION gCS; diff --git a/docs/code-quality/c26101.md b/docs/code-quality/c26101.md index 8d881597a84..c89fbe4543c 100644 --- a/docs/code-quality/c26101.md +++ b/docs/code-quality/c26101.md @@ -1,21 +1,21 @@ --- -description: "Learn more about: C26101" -title: C26101 +title: "Warning C26101" +description: "Learn more about: Warning C26101" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26101"] helpviewer_keywords: ["C26101"] -ms.assetid: 86046553-09ec-40ce-82b3-fd641928f0b0 --- -# C26101 +# Warning C26101 -> warning C26101: Failing to use interlocked operation properly for variable \. +> Failing to use interlocked operation properly for variable '*var*'. -Windows APIs offer a variety of interlocked operations. Annotation `_Interlocked_` specifies that a variable should only be accessed through an interlocked operation. Warning C26101 is issued when an access is not consistent with the `_Interlocked_` annotation. +## Remarks + +Windows APIs offer various interlocked operations. Annotation `_Interlocked_` specifies that a variable should only be accessed through an interlocked operation. Warning C26101 is issued when a variable access isn't consistent with the `_Interlocked_` annotation. ## Example -The following example generates warning C26101 because there is a violation of the `_Interlocked_` contract. +The following example generates warning C26101 because there's a violation of the `_Interlocked_` contract. ```cpp CRITICAL_SECTION cs; diff --git a/docs/code-quality/c26105.md b/docs/code-quality/c26105.md index 749ff32dbe9..0381c3feec2 100644 --- a/docs/code-quality/c26105.md +++ b/docs/code-quality/c26105.md @@ -1,21 +1,21 @@ --- -description: "Learn more about: C26105" -title: C26105 +title: "Warning C26105" +description: "Learn more about: Warning C26105" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26105"] helpviewer_keywords: ["C26105"] -ms.assetid: 5558a3db-0513-43b4-8579-ccdc17e2b92f --- -# C26105 +# Warning C26105 -> warning C26105: Lock order violation. Acquiring lock \ with level \ causes order inversion. +> Lock order violation. Acquiring lock '*lock*' with level '*level*' causes order inversion. + +## Remarks Concurrency SAL supports *lock levels*. To declare a lock level, which is denoted by a string literal without double quotes, use `_Create_lock_level_`. You can impose an order of acquisition between two lock levels by using the annotation `_Set_lock_level_order_(A,B)`, which states that locks that have level `A` must be acquired before locks that have level `B`. To establish a lock order hierarchy (a partial order among lock levels), use multiple `_Set_lock_level_order_` annotations. To associate a lock with a lock level, use the `_Set_lock_level_` annotation when you declare the lock. Warning C26105 is issued when a lock ordering violation is detected. ## Example -The following example generates warning C26105 because there is a lock order inversion in the function `OrderInversion`. +The following example generates warning C26105 because there's a lock order inversion in the function `OrderInversion`. ```cpp _Create_lock_level_(MutexLockLevel); diff --git a/docs/code-quality/c26110.md b/docs/code-quality/c26110.md index 90238930a87..67d89e3cefe 100644 --- a/docs/code-quality/c26110.md +++ b/docs/code-quality/c26110.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: C26110" -title: C26110 +title: "Warning C26110" +description: "Learn more about: Warning C26110" ms.date: 10/01/2019 -ms.topic: reference f1_keywords: ["C26110"] helpviewer_keywords: ["C26110"] -ms.assetid: d82b79ec-6d7f-438b-bd6a-da874a3e08e5 --- -# C26110 +# Warning C26110 -> warning C26110: Caller failing to hold lock \ before calling function \. +> Caller failing to hold lock '*lock*' before calling function '*func*'. -When a lock is required, make sure to clarify whether the function itself or its caller should acquire the lock. Warning C26110 is issued when there is a violation of the `_Requires_lock_held_` annotation, or other lock-related annotations. For more information, see [Annotating Locking Behavior](annotating-locking-behavior.md) +## Remarks + +When a lock is required, make sure to clarify whether the function itself, or its caller, should acquire the lock. Warning C26110 is issued when there's a violation of the `_Requires_lock_held_` annotation, or other lock-related annotations. For more information, see [Annotating Locking Behavior](annotating-locking-behavior.md) ## Example diff --git a/docs/code-quality/c26111.md b/docs/code-quality/c26111.md index 9b09995f936..c7bf8bee694 100644 --- a/docs/code-quality/c26111.md +++ b/docs/code-quality/c26111.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: C26111" -title: C26111 +title: "Warning C26111" +description: "Learn more about: Warning C26111" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26111"] helpviewer_keywords: ["C26111"] -ms.assetid: 85fc740a-3bbb-41b8-a848-95e243a08da9 --- -# C26111 +# Warning C26111 -> warning C26111: Caller failing to release lock \ before calling function \. +> Caller failing to release lock '*lock*' before calling function '*func*'. -The annotation `_Requires_lock_not_held_` imposes a precondition that the lock count for the specified lock cannot be greater than zero when the function is called. Warning C26111 is issued when a function fails to release the lock before it calls another function. +## Remarks + +The annotation `_Requires_lock_not_held_` imposes a precondition that the lock count for the specified lock can't be greater than zero when the function is called. Warning C26111 is issued when a function fails to release the lock before it calls another function. ## Example diff --git a/docs/code-quality/c26112.md b/docs/code-quality/c26112.md index 9b0990c8d25..58554638b08 100644 --- a/docs/code-quality/c26112.md +++ b/docs/code-quality/c26112.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C26112" -title: C26112 +title: "Warning C26112" +description: "Learn more about: Warning C26112" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26112"] helpviewer_keywords: ["C26112"] -ms.assetid: 926de738-b9b0-43d7-9137-ab2daa44ad4d --- -# C26112 +# Warning C26112 -> warning C26112: Caller cannot hold any lock before calling \. +> Caller cannot hold any lock before calling '*func*'. + +## Remarks The annotation `_Requires_no_locks_held_` imposes a precondition that the caller must not hold any lock while it calls the function. Warning C26112 is issued when a function fails to release all locks before it calls another function. diff --git a/docs/code-quality/c26115.md b/docs/code-quality/c26115.md index 410c812ae8b..3c634459d07 100644 --- a/docs/code-quality/c26115.md +++ b/docs/code-quality/c26115.md @@ -1,23 +1,23 @@ --- -description: "Learn more about: C26115" -title: C26115 +title: "Warning C26115" +description: "Learn more about: Warning C26115" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26115"] helpviewer_keywords: ["C26115"] -ms.assetid: 3977a2bb-d1fe-4510-89dd-07fdc69e911c --- -# C26115 +# Warning C26115 -> warning C26115: Failing to release lock \ in function \. +> Failing to release lock '*lock*' in function '*func*'. -Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs is not performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. +## Remarks -You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases are not balanced, they are considered to be *orphaned*. Warning C26115 is issued when a function introduces an orphaned lock. +Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. + +You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26115 is issued when a function introduces an orphaned lock. ## Example -The following example generates warning C26115 because there is an orphaned lock in a function that is not annotated with `_Acquires_lock_`. +The following example generates warning C26115 because there's an orphaned lock in a function that isn't annotated with `_Acquires_lock_`. ```cpp typedef struct _DATA diff --git a/docs/code-quality/c26116.md b/docs/code-quality/c26116.md index c01fc2a5fa2..b6d60a75544 100644 --- a/docs/code-quality/c26116.md +++ b/docs/code-quality/c26116.md @@ -1,21 +1,19 @@ --- -description: "Learn more about: C26116" -title: C26116 +title: "Warning C26116" +description: "Learn more about: Warning C26116" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26116"] helpviewer_keywords: ["C26116"] -ms.assetid: 43e99d2c-405e-4913-b6bd-47f5858b2877 --- -# C26116 +# Warning C26116 -> warning C26116: Failing to acquire or to hold lock \ in \. +> Failing to acquire or to hold lock '*lock*' in '*func*'. -Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs is not performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock.You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Requires_lock_held`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases are not balanced, they are considered to be *orphaned*. Warning C26116 is issued when a function has been annotated with `_Acquires_lock_`, but it does not acquire a lock, or when a function is annotated with `_Requires_lock_held` and releases the lock. +Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Requires_lock_held_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26116 is issued when a function has been annotated with `_Acquires_lock_`, but it doesn't acquire a lock, or when a function is annotated with `_Requires_lock_held_` and releases the lock. ## Example -The following example generates warning C26116 because the function `DoesNotLock` was annotated with `_Acquires_lock_` but does not acquire it. The function `DoesNotHoldLock` generates the warning because it is annotated with `_Requires_lock_held` and does not hold it. +The following example generates warning C26116 because the function `DoesNotLock` was annotated with `_Acquires_lock_` but doesn't acquire it. The function `DoesNotHoldLock` generates the warning because it's annotated with `_Requires_lock_held_` and doesn't hold it. ```cpp typedef struct _DATA diff --git a/docs/code-quality/c26117.md b/docs/code-quality/c26117.md index 892d8507dfe..16ebb6bff74 100644 --- a/docs/code-quality/c26117.md +++ b/docs/code-quality/c26117.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: C26117" -title: C26117 +title: "Warning C26117" +description: "Learn more about: Warning C26117" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26117"] helpviewer_keywords: ["C26117"] -ms.assetid: cc7ebc8d-9826-4cad-a4d5-2d3ad5896734 --- -# C26117 +# Warning C26117 -> warning C26117: Releasing unheld lock \ in function \. +> Releasing unheld lock '*lock*' in function '*func*'. -Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs is not performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock.You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases are not balanced, they are considered to be *orphaned*. Warning C26117 is issued when a function that has not been annotated with `_Releases_lock_` releases a lock that it doesn't hold, because the function must own the lock before it releases it. +## Remarks + +Enforcement of syntactically scoped lock *acquire* and lock *release* pairs in C/C++ programs isn't performed by the language. A function may introduce a locking side effect by making an observable modification to the concurrency state. For example, a lock wrapper function increments the number of lock acquisitions, or lock count, for a given lock. You can annotate a function that has a side effect from a lock acquire or lock release by using `_Acquires_lock_` or `_Releases_lock_`, respectively. Without such annotations, a function is expected not to change any lock count after it returns. If acquires and releases aren't balanced, they're considered to be *orphaned*. Warning C26117 is issued when a function that hasn't been annotated with `_Releases_lock_` releases a lock that it doesn't hold, because the function must own the lock before it releases it. ## Examples -The following example generates warning C26117 because the function `ReleaseUnheldLock` releases a lock that it doesn't necessarily hold—the state of `flag` is ambiguous—and there is no annotation that specifies that it should. +The following example generates warning C26117 because the function `ReleaseUnheldLock` releases a lock that it doesn't necessarily hold—the state of `flag` is ambiguous—and there's no annotation that specifies that it should. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; @@ -38,7 +37,6 @@ void ReleaseUnheldLock(DATA* p) The following code fixes the problem by guaranteeing that the released lock is also acquired under the same conditions. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; diff --git a/docs/code-quality/c26130.md b/docs/code-quality/c26130.md index 77bd55296ec..990d87c2b3e 100644 --- a/docs/code-quality/c26130.md +++ b/docs/code-quality/c26130.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: C26130" -title: C26130 +title: "Warning C26130" +description: "Learn more about: Warning C26130" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26130"] helpviewer_keywords: ["C26130"] -ms.assetid: 535e2356-bc84-4549-983d-7d29aee2249c --- -# C26130 +# Warning C26130 -> warning C26130: Missing annotation \_Requires\_lock\_held\_(\) or \_No\_competing\_thread\_ at function \. Otherwise it could be a race condition. Variable \ should be protected by lock \. +> Missing annotation \_Requires\_lock\_held\_('*lock*') or \_No\_competing\_thread\_ at function '*func*'. Otherwise it could be a race condition. Variable '*var*' should be protected by lock '*lock*'. -Warning C26130 is issued when the analyzer detects a potential race condition but infers that the function is likely to be run in a single threaded mode, for example, when the function is in the initialization stage based on certain heuristics. +## Remarks + +Warning C26130 is issued when the analyzer detects a potential race condition but infers that the function is likely to be run in a single threaded mode. For example, when the function is in the initialization stage, based on certain heuristics. ## Examples @@ -30,7 +30,7 @@ void Init(DATA* p) } ``` -If the previous code is guaranteed to be operated in a single threaded mode, annotate the function by using `_No_competing_thread_`, as shown in the following example. +If the previous code is guaranteed to operate in single-threaded mode, annotate the function by using `_No_competing_thread_`, as shown in the following example. ```cpp typedef struct _DATA diff --git a/docs/code-quality/c26132.md b/docs/code-quality/c26132.md new file mode 100644 index 00000000000..aedc7e027ce --- /dev/null +++ b/docs/code-quality/c26132.md @@ -0,0 +1,73 @@ +--- +title: "Warning C26132" +description: "Documentation on static analysis warning C26132" +ms.date: 02/11/2025 +author: Rastaban +ms.author: philc +ms.service: visual-cpp +ms.topic: concept-article +--- +# 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 00000000000..e206e837948 --- /dev/null +++ b/docs/code-quality/c26133.md @@ -0,0 +1,76 @@ +--- +title: "Warning C26133" +description: "Documentation on static analysis warning C26133" +ms.date: 02/19/2025 +author: Rastaban +ms.author: philc +ms.service: visual-cpp +ms.topic: concept-article +--- +# 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 973d72eb86a..aee06179d65 100644 --- a/docs/code-quality/c26135.md +++ b/docs/code-quality/c26135.md @@ -1,17 +1,17 @@ --- -description: "Learn more about: C26135" -title: C26135 +title: "Warning C26135" +description: "Learn more about: Warning C26135" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26135"] helpviewer_keywords: ["C26135"] -ms.assetid: e9515189-8d21-473b-89f4-8b92ebd3a4f1 --- -# C26135 +# Warning C26135 -> warning C26135: Missing annotation \ at function \. +> Missing annotation '*annotation*' at function '*func*'. -Warning C26135 is issued when the analyzer infers that a function is a lock wrapper function that has a lock acquire or lock release side effect. If the code is not intended to be a wrapper function, then either the lock is leaking (if the lock is being acquired) or it is being released incorrectly (if the lock is being released). +## Remarks + +Warning C26135 is issued when the analyzer infers that a function is a lock wrapper function that has a "lock acquire" or "lock release" side effect. If the code isn't intended to be a wrapper function, then either the lock is leaking (if it's being acquired), or it's being released incorrectly (if the lock is being released). ## Examples @@ -26,14 +26,14 @@ typedef struct _DATA void MyEnter(DATA* p) { // Warning C26135: - // Missing side effect annotation _Acquires_lock_(&p->cs) + // Missing side effect annotation _Acquires_lock_(p->cs) EnterCriticalSection(&p->cs); } void MyLeave(DATA* p) { // warning C26135: - // Missing side effect annotation _Releases_lock_(&p->cs) + // Missing side effect annotation _Releases_lock_(p->cs) LeaveCriticalSection(&p->cs); } ``` diff --git a/docs/code-quality/c26138.md b/docs/code-quality/c26138.md index 9f28d7c7668..12838bac4d8 100644 --- a/docs/code-quality/c26138.md +++ b/docs/code-quality/c26138.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: C26138" -title: C26138 +title: "Warning C26138" +description: "Learn more about: Warning C26138" ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26138"] +f1_keywords: ["C26138", "SUSPENDED_WITH_LOCK"] helpviewer_keywords: ["C26138"] -author: sunnychatterjee -ms.author: sunnych --- -# C26138 +# Warning C26138 -> warning C26138: Suspending a coroutine while holding lock \. +> Suspending a coroutine while holding lock '*lock*'. + +## Remarks Warning C26138 warns when a coroutine is suspended while holding a lock. In general, we can't know how long will a coroutine remain in the suspended state so this pattern may result in longer critical sections than expected. +Code analysis name: `SUSPENDED_WITH_LOCK` + ## Examples The following code will generate C26138. ```cpp - #include #include #include @@ -48,7 +48,6 @@ generator mutex_acquiring_generator_report_once() { The following code will correct these warnings. ```cpp - #include #include #include diff --git a/docs/code-quality/c26140.md b/docs/code-quality/c26140.md index 80e2289c6a9..33e63f3b518 100644 --- a/docs/code-quality/c26140.md +++ b/docs/code-quality/c26140.md @@ -1,15 +1,13 @@ --- -description: "Learn more about: C26140" -title: C26140 +title: "Warning C26140" +description: "Learn more about: Warning C26140" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26140"] helpviewer_keywords: ["C26140"] -ms.assetid: a0b521b4-0c2f-470a-8904-f7bbb8014536 --- -# C26140 +# Warning C26140 -> warning C26140: Undefined lock kind \ in annotation \ on lock \. +> Undefined lock kind '*lock*' in annotation '*annotation*' on lock '*lock*'. ## Example diff --git a/docs/code-quality/c26160.md b/docs/code-quality/c26160.md index 13d5294d869..9fb21be939c 100644 --- a/docs/code-quality/c26160.md +++ b/docs/code-quality/c26160.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C26160" -title: C26160 +title: "Warning C26160" +description: "Learn more about: Warning C26160" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26160"] helpviewer_keywords: ["C26160"] -ms.assetid: e6518687-36b4-4eae-a732-758881638295 --- -# C26160 +# Warning C26160 -> warning C26160: Caller possibly failing to hold lock \ before calling function \. +> Caller possibly failing to hold lock '*lock*' before calling function '*func*'. + +## Remarks Warning C26160 resembles warning [C26110](../code-quality/c26110.md) except that the confidence level is lower. For example, the function may contain annotation errors. @@ -18,7 +18,6 @@ Warning C26160 resembles warning [C26110](../code-quality/c26110.md) except that The following code generates warning C26160. ```cpp - struct Account { _Guarded_by_(cs) int balance; @@ -50,7 +49,6 @@ struct Account The following code shows a solution to the previous example. ```cpp - struct Account { _Guarded_by_(cs) int balance; diff --git a/docs/code-quality/c26165.md b/docs/code-quality/c26165.md index 0d82647c213..a87f5b15e94 100644 --- a/docs/code-quality/c26165.md +++ b/docs/code-quality/c26165.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C26165" -title: C26165 +title: "Warning C26165" +description: "Learn more about: Warning C26165" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26165"] helpviewer_keywords: ["C26165"] -ms.assetid: a1d89bd6-08f3-4215-8a0c-b8ecfeb0cffc --- -# C26165 +# Warning C26165 -> warning C26165: Possibly failing to release lock \ in function \. +> Possibly failing to release lock '*lock*' in function '*func*'. + +## Remarks Warning C26165 resembles warning [C26115](../code-quality/c26115.md) except that the confidence level is lower. For example, the function may contain annotation errors. @@ -18,7 +18,6 @@ Warning C26165 resembles warning [C26115](../code-quality/c26115.md) except that The following code generates warning C26165. ```cpp - _Create_lock_level_(LockLevelOne); _Create_lock_level_(LockLevelTwo); @@ -46,7 +45,6 @@ void testLockLevelledStruct(LockLevelledStruct* s) // Warning C26165 To correct this warning, change the previous example to the following. ```cpp - _Create_lock_level_(LockLevelOne); _Create_lock_level_(LockLevelTwo); diff --git a/docs/code-quality/c26166.md b/docs/code-quality/c26166.md index 88fc282f7be..93176e6a086 100644 --- a/docs/code-quality/c26166.md +++ b/docs/code-quality/c26166.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C26166" -title: C26166 +title: "Warning C26166" +description: "Learn more about: Warning C26166" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26166"] helpviewer_keywords: ["C26166"] -ms.assetid: a3d21838-07da-40f6-8d2e-1ada72765af2 --- -# C26166 +# Warning C26166 -> warning C26166: Possibly failing to acquire or to hold lock \ in function \. +> Possibly failing to acquire or to hold lock '*lock*' in function '*func*'. + +## Remarks Warning C26166 resembles warning [C26116](../code-quality/c26116.md) except that the confidence level is lower. For example, the function may contain annotation errors. @@ -18,7 +18,6 @@ Warning C26166 resembles warning [C26116](../code-quality/c26116.md) except that The following code shows code that will generate warning C26166. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; } DATA; diff --git a/docs/code-quality/c26167.md b/docs/code-quality/c26167.md index bb1a8605754..24c4e950d2e 100644 --- a/docs/code-quality/c26167.md +++ b/docs/code-quality/c26167.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: C26167" -title: C26167 +title: "Warning C26167" +description: "Learn more about: Warning C26167" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C26167"] helpviewer_keywords: ["C26167"] -ms.assetid: 5a3d767f-31fa-45e0-8c9b-1aa776acaa45 --- -# C26167 +# Warning C26167 -> warning C26167: Possibly releasing unheld lock \ in function \. +> Possibly releasing unheld lock '*lock*' in function '*func*'. + +## Remarks Warning C26167 resembles warning [C26117](../code-quality/c26117.md) except that the confidence level is lower. For example, the function may contain annotation errors. ## Examples -The following code will generate C26167, as well as C26110. +The following code will generate C26167 and C26110. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; } DATA; @@ -35,7 +34,6 @@ void ReleaseUnheldLock(DATA* p) { // Warning C26167 The following code will correct these warnings. ```cpp - typedef struct _DATA { CRITICAL_SECTION cs; } DATA; diff --git a/docs/code-quality/c26400.md b/docs/code-quality/c26400.md index 93c9add39de..e4819ceeaaf 100644 --- a/docs/code-quality/c26400.md +++ b/docs/code-quality/c26400.md @@ -1,22 +1,26 @@ --- -title: C26400 +title: Warning C26400 description: "Describes the Microsoft C/C++ code analysis warning C26400, its causes, and how to address it." ms.date: 10/23/2020 -f1_keywords: ["C26400"] +f1_keywords: ["C26400", "NO_RAW_POINTER_ASSIGNMENT"] helpviewer_keywords: ["C26400"] --- -# C26400 NO_RAW_POINTER_ASSIGNMENT +# Warning C26400 -This check helps to enforce the *rule I.11: Never transfer ownership by a raw pointer (T\*)*, which is a subset of the rule *R.3: A raw pointer (a T\*) is non-owning*. Specifically, it warns on any call to `operator new`, which saves its result in a variable of raw pointer type. It also warns on calls to functions that return `gsl::owner` if their results are assigned to raw pointers. The idea here is that you should clearly state ownership of memory resources. For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). +> Do not assign the result of an allocation or a function call with an `owner` return value to a raw pointer, use `owner` instead (i.11) + +## Remarks + +This check helps to enforce the *rule I.11: Never transfer ownership by a raw pointer (T\*), which is a subset of the rule *R.3: A raw pointer (a T\*) is non-owning*. Specifically, it warns on any call to `operator new`, which saves its result in a variable of raw pointer type. It also warns on calls to functions that return `gsl::owner` if their results are assigned to raw pointers. The idea is that you should clearly state ownership of memory resources. For more information, see the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-resource). The easiest way to fix this warning is to use **`auto`** declaration if the resource is assigned immediately at the variable declaration. If this fix isn't possible, then we suggest that you use the type `gsl::owner`. The **`auto`** declarations initialized with operator **`new`** are "owners" because we assume that the result of any allocation is implicitly an owner pointer. We transfer this assumption to the **`auto`** variable and treat it as `owner`. If this check flags a call to a function that returns `owner`, it may be an indication of a legitimate bug in the code. Basically, it points to a place where the code leaks an explicit notion of ownership (and maybe the resource itself). -## Remarks - This rule currently checks only local variables. If you assign an allocation to a formal parameter, global variable, class member, and so on, it's not flagged. Appropriate coverage of such scenarios is planned for future work. +Code analysis name: `NO_RAW_POINTER_ASSIGNMENT` + ## Example 1: Simple allocation ```cpp diff --git a/docs/code-quality/c26401.md b/docs/code-quality/c26401.md index 0c1da704aac..0029e443d56 100644 --- a/docs/code-quality/c26401.md +++ b/docs/code-quality/c26401.md @@ -1,21 +1,26 @@ --- -title: C26401 +title: Warning C26401 ms.date: 12/14/2020 -ms.topic: "conceptual" -f1_keywords: ["C26401"] +f1_keywords: ["C26401", "DONT_DELETE_NON_OWNER"] helpviewer_keywords: ["C26401"] ms.assetid: b9d3d398-697a-4a5d-8bfe-9c667dffb90b description: CppCoreCheck rule C26401 enforces C++ Core Guidelines I.11 --- -# C26401 DONT_DELETE_NON_OWNER +# Warning C26401 -This check detects places where moving to `owner` can be a good option for the first stage of refactoring. Like C26400, it enforces rules I.11 and R.3, but focuses on the "release" portion of the pointer lifetime. It warns on any call to operator **`delete`** if its target isn't an `owner` or an implicitly assumed owner. For more information about **`auto`** declarations, see [C26400](c26400.md). This check includes expressions that refer to global variables, formal parameters, and so on. +> Do not delete a raw pointer that is not an `owner` (i.11) + +## Remarks + +This check detects code where moving to `owner` can be a good option for the first stage of refactoring. Like C26400, it enforces rules I.11 and R.3, but focuses on the "release" portion of the pointer lifetime. It warns on any call to operator **`delete`** if its target isn't an `owner` or an implicitly assumed owner. For more information about **`auto`** declarations, see [C26400](c26400.md). This check includes expressions that refer to global variables, formal parameters, and so on. Warnings C26400 and C26401 always occur with [C26409](c26409.md), but they're more appropriate for scenarios where immediate migration to smart pointers isn't feasible. In such cases, the `owner` concept can be adopted first, and C26409 may be temporarily suppressed. +Code analysis name: `DONT_DELETE_NON_OWNER` + ## See also -[C++ Core Guidelines I.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i11-never-transfer-ownership-by-a-raw-pointer-t-or-reference-t) +[C++ Core Guidelines I.11](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-raw) ## Examples @@ -46,7 +51,7 @@ void function() } ``` -There's a C++ idiom, `delete this`, that triggers this warning. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: +There's a C++ idiom that triggers this warning: `delete this`. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: ```cpp class MyReferenceCountingObject final @@ -58,7 +63,7 @@ public: ref_count_--; if (ref_count_ == 0) { - [[gsl::suppress(i.11)]] + [[gsl::suppress("i.11")]] delete this; } } diff --git a/docs/code-quality/c26402.md b/docs/code-quality/c26402.md index 828a1cbb939..d375a3128c5 100644 --- a/docs/code-quality/c26402.md +++ b/docs/code-quality/c26402.md @@ -1,23 +1,21 @@ --- -description: "Learn more about: C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT" -title: C26402 +title: "Warning C26402" +description: "Learn more about: Warning C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT" ms.date: 08/20/2020 -ms.topic: "conceptual" -f1_keywords: ["C26402"] +f1_keywords: ["C26402", "DONT_HEAP_ALLOCATE_MOVABLE_RESULT"] helpviewer_keywords: ["C26402"] -ms.assetid: b9d3d398-697a-4a5d-8bfe-9c667dffb90b --- -# C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT +# Warning C26402 > `Return a scoped object instead of a heap-allocated if it has a move constructor (r.3).` ## Remarks -To avoid confusion about whether a pointer owns an object, a function that returns a movable object should allocate it on the stack. It should then return the object by value instead of returning a heap-allocated object. If pointer semantics are required, return a smart pointer instead of a raw pointer. For more information, see [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr): *Warn if a function returns an object that was allocated within the function but has a move constructor. Suggest considering returning it by value instead.* +To avoid confusion about whether a pointer owns an object, a function that returns a movable object should allocate it on the stack. It should then return the object by value instead of returning a heap-allocated object. If pointer semantics are required, return a smart pointer instead of a raw pointer. For more information, see [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr): *Warn if a function returns an object that was allocated within the function but has a move constructor. Suggest considering returning it by value instead.* ## Example -This example shows a function, `bad_example`, that raises warning C26409. It also shows how function `good_example` doesn't cause this issue. +This example shows a `bad_example` function that raises warning C26409. It also shows how function `good_example` doesn't cause this issue. ```cpp // C26402.cpp @@ -35,7 +33,7 @@ S* bad_example() return s; // C26402 } -// Prefer returning objects with move contructors by value instead of unnecessarily heap-allocating the object. +// Prefer returning objects with move constructors by value instead of unnecessarily heap-allocating the object. S good_example() noexcept { S s; diff --git a/docs/code-quality/c26403.md b/docs/code-quality/c26403.md index d688d724cfc..801e33dce9a 100644 --- a/docs/code-quality/c26403.md +++ b/docs/code-quality/c26403.md @@ -1,27 +1,32 @@ --- -description: "Learn more about: C26403 RESET_OR_DELETE_OWNER" -title: C26403 +description: "Learn more about: Warning C26403 RESET_OR_DELETE_OWNER" +title: Warning C26403 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26403"] +f1_keywords: ["C26403", "RESET_OR_DELETE_OWNER"] helpviewer_keywords: ["C26403"] ms.assetid: 7e14868d-df86-4df3-98d3-71b1e80ba14e --- -# C26403 RESET_OR_DELETE_OWNER +# Warning C26403 -Owner pointers are like unique pointers: they own a resource exclusively, and manage release of the resource, as well as its transfers to other owners. This check validates that a local owner pointer properly maintains its resource through all execution paths in a function. If the resource was not transferred to another owner, or was not explicitly release, the checker warns, and points to the declaration of the pointer variable. +> Reset or explicitly delete an `owner` pointer '*variable*' (r.3) -For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). +Owner pointers are like unique pointers: they own a resource exclusively, and manage release of the resource, or its transfers to other owners. This check validates that a local owner pointer properly maintains its resource through all execution paths in a function. If the resource wasn't transferred to another owner, or wasn't explicitly release, the checker warns, and points to the declaration of the pointer variable. + +For more information, see the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-resource). ## Remarks -- Currently this check doesn’t give the exact path which fails to release the resource. This behavior may be improved in future releases. It may be difficult to find exact location for a fix. The better approach is to try to replace plain pointers in complex functions with unique pointers to avoid any risks. +- Currently this check doesn't give the exact path that fails to release the resource. This behavior may be improved in future releases. It may be difficult to find exact location for a fix. The better approach is to try to replace plain pointers in complex functions with unique pointers to avoid any risks. + +- The check may discard an over-complicated function in order to not block code analysis. Generally, the complexity of functions should be maintained under some reasonable threshold. We may consider adding a local complexity check to the C++ Core Guidelines module if there's clear demand for it. This limitation is applicable to other rules that are sensitive to data flow. + +- The warning may fire on clearly false positive cases where memory is deleted only after the null check of a pointer. These false positives are the result of a current limitation of the tool's API, but it may be improved in future. -- The check may discard an over-complicated function in order to not block code analysis. Generally, the complexity of functions should be maintained under some reasonable threshold. We may consider adding a local complexity check to the C++ Core Guidelines module if there is clear demand for it. This limitation is applicable to other rules which are sensitive to data flow. +Code analysis name: `RESET_OR_DELETE_OWNER` -- The warning may fire on clearly false positive cases where memory is deleted only after the nullness check of a pointer. This is the result of a current limitation of the tool’s API, but it may be improved in future. +## Example -## Example 1: Missing cleanup during error handling +Missing cleanup during error handling: ```cpp gsl::owner sequence = GetRandomSequence(); // C26403 diff --git a/docs/code-quality/c26404.md b/docs/code-quality/c26404.md index 53274f5dad7..f37ed895fb1 100644 --- a/docs/code-quality/c26404.md +++ b/docs/code-quality/c26404.md @@ -1,18 +1,24 @@ --- -description: "Learn more about: C26404 DONT_DELETE_INVALID" -title: C26404 +description: "Learn more about: Warning C26404 DONT_DELETE_INVALID" +title: Warning C26404 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26404"] +f1_keywords: ["C26404", "DONT_DELETE_INVALID"] helpviewer_keywords: ["C26404"] ms.assetid: 94afb700-3f3b-40db-8afc-2481935360c2 --- -# C26404 DONT_DELETE_INVALID +# Warning C26404 -Once owner pointer releases or transfers its resource, it gets into an "invalid" state. -Deleting such a pointer may lead to immediate memory corruption due to double delete, or to an access violation when the deleted resource is accessed from another owner pointer. +> Do not delete an `owner` which may be in invalid state (r.3) -## Example 1: Deleting an owner after transferring its value +## Remarks + +Once an owner pointer releases or transfers its resource, it gets into an "invalid" state. Deleting such a pointer may lead to immediate memory corruption due to double delete, or to an access violation when the deleted resource is accessed from another owner pointer. + +Code analysis name: `DONT_DELETE_INVALID` + +## Example 1 + +Deleting an owner after transferring its value: ```cpp gsl::owner validState = nullptr; @@ -22,7 +28,9 @@ if (!IsValid(state)) delete state; // C26404 ``` -## Example 2: Deleting an uninitialized owner +## Example 2 + +Deleting an uninitialized owner: ```cpp gsl::owner message; diff --git a/docs/code-quality/c26405.md b/docs/code-quality/c26405.md index 4fb63a8631b..8c8d2b45eb6 100644 --- a/docs/code-quality/c26405.md +++ b/docs/code-quality/c26405.md @@ -1,17 +1,24 @@ --- -description: "Learn more about: C26405 DONT_ASSIGN_TO_VALID" -title: C26405 +description: "Learn more about: Warning C26405 DONT_ASSIGN_TO_VALID" +title: Warning C26405 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26405"] +f1_keywords: ["C26405", "DONT_ASSIGN_TO_VALID"] helpviewer_keywords: ["C26405"] ms.assetid: 2034d961-3ec5-4184-bbef-aa792e4c03c0 --- -# C26405 DONT_ASSIGN_TO_VALID +# Warning C26405 -If an owner pointer already points to a valid memory buffer, it must not be assigned to another value without releasing its current resource first. Such assignment may lead to a resource leak even if the resource address is copied into some raw pointer (because raw pointers shouldn’t release resources). For more information, see the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r3-a-raw-pointer-a-t-is-non-owning). +> Do not assign to an `owner` which may be in valid state (r.3) -## Example 1: Overwriting an owner in a loop +## Remarks + +If an owner pointer already points to a valid memory buffer, it must not be assigned to another value without releasing its current resource first. Such assignment may lead to a resource leak even if the resource address is copied into some raw pointer (because raw pointers shouldn't release resources). For more information, see the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). + +Code analysis name: `DONT_ASSIGN_TO_VALID` + +## Example 1 + +Overwriting an owner in a loop: ```cpp gsl::owner shape = nullptr; diff --git a/docs/code-quality/c26406.md b/docs/code-quality/c26406.md index 9f9090494b6..3027afd7284 100644 --- a/docs/code-quality/c26406.md +++ b/docs/code-quality/c26406.md @@ -1,21 +1,26 @@ --- -description: "Learn more about: C26406 DONT_ASSIGN_RAW_TO_OWNER" -title: C26406 +description: "Learn more about: Warning C26406 DONT_ASSIGN_RAW_TO_OWNER" +title: Warning C26406 ms.date: 08/18/2020 -ms.topic: "conceptual" -f1_keywords: ["C26406"] +f1_keywords: ["C26406", "DONT_ASSIGN_RAW_TO_OWNER"] helpviewer_keywords: ["C26406"] ms.assetid: 02fb8e23-1989-4e24-a5a5-e30f71d00325 --- -# C26406 DONT_ASSIGN_RAW_TO_OWNER +# Warning C26406 -This warning enforces R.3 from the C++ Core Guidelines. For more information, see [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r3-a-raw-pointer-a-t-is-non-owning). +> Do not assign a raw pointer to an `owner` (r.3) + +This warning enforces R.3 from the C++ Core Guidelines. For more information, see [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). ## Remarks -Owners are initialized from allocations or from other owners. This warning occurs when you assign a value from a raw pointer to an owner pointer. Raw pointers don’t guarantee ownership transfer; the original owner may still hold the resource and attempt to release it. It's okay to assign a value from an owner to a raw pointer. Raw pointers are valid clients to access resources, but not to manage them. +Owners are initialized from allocations or from other owners. This warning occurs when you assign a value from a raw pointer to an owner pointer. Raw pointers don't guarantee ownership transfer; the original owner may still hold the resource and attempt to release it. It's okay to assign a value from an owner to a raw pointer. Raw pointers are valid clients to access resources, but not to manage them. + +Code analysis name: `DONT_ASSIGN_RAW_TO_OWNER` + +## Example -## Example 1: Using address of object +Using address of object: This sample attempts to assign ownership of the address of `defaultSocket` to owner pointer `socket`: diff --git a/docs/code-quality/c26407.md b/docs/code-quality/c26407.md index 88184142c2a..79022356f01 100644 --- a/docs/code-quality/c26407.md +++ b/docs/code-quality/c26407.md @@ -1,25 +1,28 @@ --- -title: C26407 +title: Warning C26407 description: "Reference for Visual Studio C++ Core Guidelines code analysis warning C26407." ms.date: 08/18/2020 -ms.topic: "conceptual" -f1_keywords: ["C26407"] +f1_keywords: ["C26407", "DONT_HEAP_ALLOCATE_UNNECESSARILY"] helpviewer_keywords: ["C26407"] ms.assetid: 5539907a-bfa0-40db-82a6-b860c97209e1 --- -# C26407 DONT_HEAP_ALLOCATE_UNNECESSARILY +# Warning C26407 -To avoid unnecessary use of pointers, we try to detect common patterns of local allocations. For example, we detect when the result of a call to operator **`new`** is stored in a local variable and later explicitly deleted. This supports the [C++ Core Guidelines rule R.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r5-prefer-scoped-objects-dont-heap-allocate-unnecessarily): *Prefer scoped objects, don't heap-allocate unnecessarily*. To fix the issue, use an RAII type instead of a raw pointer, and allow it to deal with resources. Obviously, it isn't necessary to create a wrapper type to allocate a single object. Instead, a local variable of the object's type would work better. +> Prefer scoped objects, don't heap-allocate unnecessarily (r.5) + +To avoid unnecessary use of pointers, we try to detect common patterns of local allocations. For example, we detect when the result of a call to operator **`new`** is stored in a local variable and later explicitly deleted. This check supports the [C++ Core Guidelines rule R.5](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-scoped): *Prefer scoped objects, don't heap-allocate unnecessarily*. To fix the issue, use an RAII type instead of a raw pointer, and allow it to deal with resources. Obviously, it isn't necessary to create a wrapper type to allocate a single object. Instead, a local variable of the object's type would work better. ## Remarks -- To reduce the number of warnings, code analysis only detects this pattern for owner pointers. So, it's necessary to mark owners properly first. We can easily extend this to cover raw pointers if we receive feedback on the Visual Studio C++ [Developer Community](https://aka.ms/feedback/suggest?space=62) from customers in support of such scenarios. +- To reduce the number of warnings, code analysis only detects this pattern for owner pointers. So, it's necessary to mark owners properly first. We can easily extend this analysis to cover raw pointers if we receive feedback on the Visual Studio C++ [Developer Community](https://aka.ms/feedback/suggest?space=62) from customers in support of such scenarios. + +- The *scoped object* term may be a bit misleading. In general, we suggest you use either a local variable whose lifetime is automatically managed, or a smart object that efficiently manages dynamic resources. Smart objects can do heap allocations, but it's not explicit in the code. -- The *scoped object* term may be a bit misleading. In general, we suggest you use either a local variable whose lifetime is automatically managed, or a smart object that efficiently manages dynamic resources. Smart objects can of course do heap allocations, but it's not explicit in the code. +- If the warning fires on array allocation, which is often needed for dynamic buffers, you can fix it by using standard containers, or `std::unique_pointer`. -- If the warning fires on array allocation, (which is usually needed for dynamic buffers), you can fix it by using standard containers, or `std::unique_pointer`. +- The pattern is detected only for local variables. We don't warn in cases where an allocation is assigned to, say, a global variable and then deleted in the same function. -- The pattern is detected only for local variables. We don’t warn in cases where an allocation is assigned to, say, a global variable and then deleted in the same function. +Code analysis name: `DONT_HEAP_ALLOCATE_UNNECESSARILY` ## Example 1: Unnecessary object allocation on heap diff --git a/docs/code-quality/c26408.md b/docs/code-quality/c26408.md index ae507ff4564..423b99d972a 100644 --- a/docs/code-quality/c26408.md +++ b/docs/code-quality/c26408.md @@ -1,25 +1,28 @@ --- -title: C26408 +title: Warning C26408 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26408"] +f1_keywords: ["C26408", "NO_MALLOC_FREE"] helpviewer_keywords: ["C26408"] ms.assetid: 55b0706f-1107-41c1-8ad0-c9e1e86a3b8c description: CppCoreCheck rule that enforces C++ Core Guidelines R.10 --- -# C26408 NO_MALLOC_FREE +# Warning C26408 -This warning flags places where `malloc` or `free` is invoked explicitly in accordance to R.10: Avoid `malloc` and `free`. One potential fix for such warnings would be to use [std::make_unique](../standard-library/memory-functions.md#make_unique) to avoid explicit creation and destruction of objects. If such a fix is not acceptable, operator [new and delete](../cpp/new-and-delete-operators.md) should be preferred. In some cases, if exceptions are not welcome, `malloc` and `free` can be replaced with the nothrow version of operators `new` and `delete`. +> Avoid `malloc()` and `free()`, prefer the `nothrow` version of `new` with `delete` (r.10) + +This warning flags places where `malloc` or `free` is invoked explicitly in accordance to R.10: Avoid `malloc` and `free`. One potential fix for such warnings would be to use [std::make_unique](../standard-library/memory-functions.md#make_unique) to avoid explicit creation and destruction of objects. If such a fix isn't acceptable, operator [new and delete](../cpp/new-and-delete-operators.md) should be preferred. In some cases, if exceptions aren't welcome, `malloc` and `free` can be replaced with the nothrow version of operators `new` and `delete`. ## Remarks -- To detect malloc() we check if a call invokes a global function with name "malloc" or "std::malloc". The function must return a pointer to **`void`** and accept one parameter of unsigned integral type. +- To detect `malloc()`, we check if a call invokes a global function named `malloc` or `std::malloc`. The function must return a pointer to **`void`** and accept one parameter of unsigned integral type. + +- To detect `free()`, we check global functions named `free` or `std::free` that return no result and accept one parameter, which is a pointer to **`void`**. -- To detect free() we check global functions with names "free" or "std::free" which return no result and accept one parameter, which is a pointer to **`void`**. +Code analysis name: `NO_MALLOC_FREE` ## See also -[C++ Core Guidelines R.10](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r10-avoid-malloc-and-free) +[C++ Core Guidelines R.10](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-mallocfree) ## Example diff --git a/docs/code-quality/c26409.md b/docs/code-quality/c26409.md index 81344c1b46a..459ce8cf922 100644 --- a/docs/code-quality/c26409.md +++ b/docs/code-quality/c26409.md @@ -1,20 +1,18 @@ --- +title: Warning C26409 description: "Learn more about CppCoreCheck rule C26409: avoid explicit new and delete." -title: C26409 ms.date: 12/14/2020 -ms.topic: "conceptual" -f1_keywords: ["C26409"] +f1_keywords: ["C26409", "NO_NEW_DELETE"] helpviewer_keywords: ["C26409"] -ms.assetid: a3b3a229-d566-4be3-bd28-2876ccc8dc37 --- -# C26409 NO_NEW_DELETE +# Warning C26409 -> `Avoid calling new and delete explicitly, use std::make_unique instead (r.11).` +> Avoid calling `new` and `delete` explicitly, use `std::make_unique` instead (r.11). Even if code is clean of calls to `malloc` and `free`, we still suggest that you consider better options than explicit use of operators [`new` and `delete`](../cpp/new-and-delete-operators.md). **C++ Core Guidelines**:\ -[R.11: Avoid calling new and delete explicitly](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r11-avoid-calling-new-and-delete-explicitly) +[R.11: Avoid calling `new` and `delete` explicitly](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-newdelete) The ultimate fix is to use smart pointers and appropriate factory functions, such as [`std::make_unique`](../standard-library/memory-functions.md#make_unique). @@ -22,6 +20,8 @@ The ultimate fix is to use smart pointers and appropriate factory functions, suc - The checker warns on calls to any kind of operator **`new`** or **`delete`**: scalar, vector, overloaded versions (global and class-specific), and placement versions. The placement **`new`** case may require some clarifications in the Core Guidelines for suggested fixes, and may be omitted in the future. +Code analysis name: `NO_NEW_DELETE` + ## Examples This example shows C26409 is raised for explicit **`new`** and **`delete`**. Consider using smart pointer factory functions such as `std::make_unique` instead. @@ -36,7 +36,7 @@ void f(int i) } ``` -There's a C++ idiom, `delete this`, that triggers this warning. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: +There's a C++ idiom that triggers this warning: `delete this`. The warning is intentional, because the C++ Core Guidelines discourage this pattern. You can suppress the warning by using the `gsl::suppress` attribute, as shown in this example: ```cpp class MyReferenceCountingObject final @@ -48,7 +48,7 @@ public: ref_count_--; if (ref_count_ == 0) { - [[gsl::suppress(i.11)]] + [[gsl::suppress("i.11")]] delete this; } } diff --git a/docs/code-quality/c26410.md b/docs/code-quality/c26410.md index ea44343787c..6a8429c1ec5 100644 --- a/docs/code-quality/c26410.md +++ b/docs/code-quality/c26410.md @@ -1,23 +1,28 @@ --- -description: "Learn more about: C26410 NO_REF_TO_CONST_UNIQUE_PTR" -title: C26410 +description: "Learn more about: Warning C26410 NO_REF_TO_CONST_UNIQUE_PTR" +title: Warning C26410 ms.date: 07/21/2017 -ms.topic: "conceptual" -f1_keywords: ["C26410"] +f1_keywords: ["C26410", "NO_REF_TO_CONST_UNIQUE_PTR"] helpviewer_keywords: ["C26410"] ms.assetid: d1547faf-96c6-48da-90f5-841154d0e878 --- -# C26410 NO_REF_TO_CONST_UNIQUE_PTR +# Warning C26410 -Generally, references to const unique pointer are meaningless. They can safely be replaced by a raw reference or a pointer. This warning enforces [C++ Core Guidelines rule R.32](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r32-take-a-unique_ptrwidget-parameter-to-express-that-a-function-assumes-ownership-of-a-widget). +> The parameter '*parameter*' is a reference to const unique pointer, use `const T*` or `const T&` instead (r.32) + +Generally, references to const unique pointer are meaningless. They can safely be replaced by a raw reference or a pointer. This warning enforces [C++ Core Guidelines rule R.32](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-uniqueptrparam). ## Remarks -- Unique pointer checks have rather broad criteria to identify smart pointers. The [C++ Core Guidelines rule R.31](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r31-if-you-have-non-std-smart-pointers-follow-the-basic-pattern-from-std): *If you have non-std smart pointers, follow the basic pattern from std describes the unique pointer and shared pointer concepts*. The heuristic is simple, but may lead to surprises: a smart pointer type is any type which defines either operator-> or operator\*; a copy-able type (shared pointer) must have either public copy constructor or overloaded assignment operator which deals with a non-R-value reference parameter. +- Unique pointer checks have rather broad criteria to identify smart pointers. The [C++ Core Guidelines rule R.31](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-smart): *If you have non-std smart pointers, follow the basic pattern from std describes the unique pointer and shared pointer concepts*. The heuristic is simple, but may lead to surprises: a smart pointer type is any type that defines either `operator->` or `operator*`. A copy-able type (shared pointer) must have either a public copy constructor or an overloaded assignment operator that deals with a non-Rvalue reference parameter. + +- Template code may produce noisy warnings. Keep in mind that templates can be instantiated with various type parameters with different levels of indirection, including references. Some warnings may not be obvious and fixes may require some rework of templates (for example, explicit removal of reference indirection). If template code is intentionally generic, the warning can be suppressed. + +Code analysis name: `NO_REF_TO_CONST_UNIQUE_PTR` -- Template code may produce a lot of noise. Keep in mind that templates can be instantiated with various type parameters with different levels of indirection, including references. Some warnings may not be obvious and fixes may require some rework of templates (for example, explicit removal of reference indirection). If template code is intentionally generic, the warning can be suppressed. +## Example -## Example 1: Unnecessary reference +Unnecessary reference: ```cpp std::vector> roots = GetRoots(); diff --git a/docs/code-quality/c26411.md b/docs/code-quality/c26411.md index a18594bc5bf..cf66a21b4de 100644 --- a/docs/code-quality/c26411.md +++ b/docs/code-quality/c26411.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: C26411 NO_REF_TO_UNIQUE_PTR" -title: C26411 +description: "Learn more about: Warning C26411 NO_REF_TO_UNIQUE_PTR" +title: Warning C26411 ms.date: 08/19/2020 -ms.topic: "conceptual" -f1_keywords: ["C26411"] +f1_keywords: ["C26411", "NO_REF_TO_UNIQUE_PTR"] helpviewer_keywords: ["C26411"] ms.assetid: 5134e51e-8b92-4ee7-94c3-022e318a0e24 --- -# C26411 NO_REF_TO_UNIQUE_PTR +# Warning C26411 -When you pass a unique pointer to a function by reference, it implies that its resource may be released or transferred inside the function. If the function uses its parameter only to access the resource, it's safe to pass a raw pointer or a reference. For additional information, see [C++ Core Guidelines rule R.33](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r33-take-a-unique_ptrwidget-parameter-to-express-that-a-function-reseats-thewidget): *Take a unique_ptr\& parameter to express that a function reseats the widget*. +> The parameter '*parameter*' is a reference to unique pointer and it is never reassigned or reset, use `T*` or `T&` instead (r.33) + +When you pass a unique pointer to a function by reference, it implies that its resource may be released or transferred inside the function. If the function uses its parameter only to access the resource, it's safe to pass a raw pointer or a reference. For more information, see [C++ Core Guidelines rule R.33](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-reseat): *Take a unique_ptr\& parameter to express that a function reseats the widget*. ## Remarks @@ -17,10 +18,12 @@ When you pass a unique pointer to a function by reference, it implies that its r - The heuristic to detect `release` or `reset` access to the unique pointer is naive. We only detect calls to assignment operators and to functions named `reset` (case-insensitive). Obviously, this detection doesn't cover all possible cases of smart pointer modifications. (For example, it doesn't detect `std::swap`, or any special non-**`const`** function in a custom smart pointer). We expect this warning may produce many false positives on custom types, and in some scenarios dealing with standard unique pointers. We expect to improve the heuristic as we implement more checks focused on smart pointers. -- The fact that smart pointers are often templates brings an interesting limitation. The compiler isn't required to process template code in templates if it's not used. In code that makes limited use of smart pointer interfaces, the checker may produce unexpected results. The checker can't properly identify semantics of the template type, because some functions may never get used. For the standard `std::unique_ptr`, this limitation is mitigated by recognizing the type's name. This may be extended in future to cover more well-known smart pointers. +- The fact that smart pointers are often templates brings an interesting limitation. The compiler isn't required to process template code in templates if it's not used. In code that makes limited use of smart pointer interfaces, the checker may produce unexpected results. The checker can't properly identify semantics of the template type, because some functions may never get used. For the standard `std::unique_ptr`, this limitation is mitigated by recognizing the type's name. This analysis may be extended in the future to cover more well-known smart pointers. - Lambda expressions that do implicit capture-by-reference may lead to surprising warnings about references to unique pointers. Currently, all captured reference parameters in lambdas are reported, regardless of whether they're reset or not. A future release may extend the heuristic to correlate lambda fields and lambda parameters. +Code analysis name: `NO_REF_TO_UNIQUE_PTR` + ## Example: Unnecessary reference ```cpp diff --git a/docs/code-quality/c26414.md b/docs/code-quality/c26414.md index 494b2ea93e6..704a57d4e80 100644 --- a/docs/code-quality/c26414.md +++ b/docs/code-quality/c26414.md @@ -1,13 +1,11 @@ --- -title: C26414 +title: Warning C26414 description: "Reference for Visual Studio C++ Core Guidelines code analysis warning C26414." ms.date: 01/29/2020 -ms.topic: "conceptual" -f1_keywords: ["C26414"] +f1_keywords: ["C26414", "RESET_LOCAL_SMART_PTR"] helpviewer_keywords: ["C26414"] -ms.assetid: dd875d0c-6752-4491-a533-3e8831795fbc --- -# C26414 RESET_LOCAL_SMART_PTR +# Warning C26414 > "Move, copy, reassign or reset a local smart pointer." @@ -20,7 +18,7 @@ Smart pointers are convenient for dynamic resource management, but they're not a This check recognizes both the standard `std::unique_pointer` and `std::shared_pointer` templates, and user-defined types that are likely intended to be smart pointers. Such types are expected to define the following operations: -- overloaded dereference or member access operators, that are public and not marked as deleted; +- overloaded dereference or member access operators that are public and not marked as deleted; - a public destructor that isn't deleted or defaulted. That includes destructors explicitly defined as empty. @@ -28,9 +26,11 @@ The type `Microsoft::WRL::ComPtr` behaves as a shared pointer, but it's often us This check looks for explicit local allocations assigned to smart pointers, to identify if scoped variables could work as an alternative. Both direct calls to operator `new`, and special functions like `std::make_unique` and `std::make_shared`, are interpreted as direct allocations. +Code analysis name: `RESET_LOCAL_SMART_PTR` + ## Example -Dynamic buffer +Dynamic buffer: ```cpp void unpack_and_send(const frame &f) @@ -41,7 +41,7 @@ void unpack_and_send(const frame &f) } ``` -Dynamic buffer – replaced by container +Dynamic buffer replaced by container: ```cpp void unpack_and_send(const frame &f) diff --git a/docs/code-quality/c26415.md b/docs/code-quality/c26415.md index bff20f15279..93c445fc29c 100644 --- a/docs/code-quality/c26415.md +++ b/docs/code-quality/c26415.md @@ -1,29 +1,28 @@ --- -description: "Learn more about: C26415 SMART_PTR_NOT_NEEDED" -title: C26415 +description: "Learn more about: Warning C26415 SMART_PTR_NOT_NEEDED" +title: Warning C26415 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26415"] +f1_keywords: ["C26415", "SMART_PTR_NOT_NEEDED"] helpviewer_keywords: ["C26415"] ms.assetid: 4165f70a-78ae-4a03-b256-c4bd74b02d09 --- -# C26415 SMART_PTR_NOT_NEEDED +# Warning C26415 -"Smart pointer parameter is used only to access contained pointer. Use T* or T& instead." +> Smart pointer parameter is used only to access contained pointer. Use T* or T& instead. **C++ Core Guidelines**: -[R.30](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r30-take-smart-pointers-as-parameters-only-to-explicitly-express-lifetime-semantics): Take smart pointers as parameters only to explicitly express lifetime semantics +[R.30](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-smartptrparam): Take smart pointers as parameters only to explicitly express lifetime semantics -Using a smart pointer type to pass data to a function indicates that the target function needs to manage the lifetime of the contained object. However, if the function only uses the smart pointer to access the contained object and never actually calls any code that may lead to its deallocation (that is, never affect its lifetime), there is usually no need to complicate the interface with smart pointers. A plain pointer or reference to the contained object is preferred. +Using a smart pointer type to pass data to a function indicates that the target function needs to manage the lifetime of the contained object. However, say the function only uses the smart pointer to access the contained object and never actually calls any code that may lead to its deallocation (that is, never affects its lifetime). Then there's usually no need to complicate the interface with smart pointers. A plain pointer or reference to the contained object is preferred. ## Remarks -This check covers a majority of scenarios that also cause C26410, C26415, C26417, and C26418. It is better to clean up SMART_PTR_NOT_NEEDED first and then switch to edge cases for shared or unique pointers. For more focused cleanup, this warning can be disabled. +This check covers most scenarios that also cause C26410, C26415, C26417, and C26418. It's better to clean up SMART_PTR_NOT_NEEDED first and then switch to edge cases for shared or unique pointers. For more focused cleanup, this warning can be disabled. In addition to the standard std::unqiue_pointer and std::shared_pointer templates, this check recognizes user-defined types that are likely intended to be smart pointers. Such types are expected to define the following operations: - Overloaded dereference or member access operators that are public and not marked as deleted. -- Public destructor that's not deleted or defaulted. This includes destructors that are explicitly defined empty. +- Public destructor that's not deleted or defaulted, including destructors that are explicitly defined empty. Interpretation of the operations that can affect the lifetime of contained objects is broad and includes: diff --git a/docs/code-quality/c26416.md b/docs/code-quality/c26416.md index 007443126c6..c658471dc4d 100644 --- a/docs/code-quality/c26416.md +++ b/docs/code-quality/c26416.md @@ -1,34 +1,33 @@ --- -description: "Learn more about: C26416 NO_RVALUE_REF_SHARED_PTR" -title: C26416 +description: "Learn more about: Warning C26416 NO_RVALUE_REF_SHARED_PTR" +title: Warning C26416 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26416"] +f1_keywords: ["C26416", "NO_RVALUE_REF_SHARED_PTR"] helpviewer_keywords: ["C26416"] ms.assetid: f158207b-45cf-44cf-8e4b-b5b75b56ea0e --- -# C26416 NO_RVALUE_REF_SHARED_PTR +# Warning C26416 > Shared pointer parameter is passed by rvalue reference. Pass by value instead. **C++ Core Guidelines**: -[R.34](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r34-take-a-shared_ptrwidget-parameter-to-express-that-a-function-is-part-owner): Take a shared_ptr\ parameter to express that a function is part owner +[R.34](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-sharedptrparam-owner): Take a shared_ptr\ parameter to express shared ownership -Passing a shared pointer by rvalue reference is usually unnecessary. Unless it is an implementation of move semantics for a shared pointer type itself, shared pointer objects can be safely passed by value. Using rvalue reference may be also an indication that unique pointer is more appropriate since it clearly transfers unique ownership from caller to callee. +Passing a shared pointer by rvalue reference is rarely necessary. Unless it's an implementation of move semantics for a shared pointer type itself, shared pointer objects can be safely passed by value. Using rvalue reference may be also an indication that unique pointer is more appropriate since it clearly transfers unique ownership from caller to callee. ## Remarks -- This check recognizes std::shared_pointer and user-defined types which are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: +- This check recognizes `std::shared_pointer` and user-defined types that are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: - overloaded dereference or member access operators (public and non-deleted); -- copy constructor or copy assignment operator (public and non-deleted); +- a copy constructor or copy assignment operator (public and non-deleted); -- public destructor which is neither deleted nor defaulted. Empty destructors are still counted as user-defined. +- a public destructor that isn't deleted or defaulted. Empty destructors are still counted as user-defined. ## Examples -questionable constructor optimization +Questionable constructor optimization: ```cpp action::action(std::shared_ptr &&t) noexcept // C26416 @@ -40,7 +39,7 @@ action::action(std::shared_ptr &t) noexcept // also C26417 LVALUE_ {} ``` -questionable constructor optimization - simplified +Questionable constructor optimization - simplified: ```cpp action::action(std::shared_ptr t) noexcept diff --git a/docs/code-quality/c26417.md b/docs/code-quality/c26417.md index 02f6623f843..b8138b42abd 100644 --- a/docs/code-quality/c26417.md +++ b/docs/code-quality/c26417.md @@ -1,36 +1,35 @@ --- -description: "Learn more about: C26417 NO_LVALUE_REF_SHARED_PTR" -title: C26417 +description: "Learn more about: Warning C26417 NO_LVALUE_REF_SHARED_PTR" +title: Warning C26417 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26417"] +f1_keywords: ["C26417", "NO_LVALUE_REF_SHARED_PTR"] helpviewer_keywords: ["C26417"] ms.assetid: 0e09fcc6-f9eb-4404-b51e-5815705c6afb --- -# C26417 NO_LVALUE_REF_SHARED_PTR +# Warning C26417 > Shared pointer parameter is passed by reference and not reset or reassigned. Use T* or T& instead. **C++ Core Guidelines**: -[R.35](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r35-take-a-shared_ptrwidget-parameter-to-express-that-a-function-might-reseat-the-shared-pointer): Take a shared_ptr\& parameter to express that a function might reseat the shared pointer +[R.35](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-sharedptrparam): Take a shared_ptr\& parameter to express that a function might reseat the shared pointer -Passing shared pointers by reference may be useful in scenarios where callee code updates target of the smart pointer object and its caller expects to see such update. Using a reference solely to reduce costs of passing a shared pointer is questionable. If callee code only accesses target object and never manages its lifetime, it is safer to pass raw pointer or reference, rather than to expose resource management details. +Passing shared pointers by reference may be useful in scenarios where called code updates the target of the smart pointer object, and its caller expects to see such updates. Using a reference solely to reduce costs of passing a shared pointer is questionable. If called code only accesses the target object and never manages its lifetime, it's safer to pass a raw pointer or reference, rather than to expose resource management details. ## Remarks -- This check recognizes std::shared_pointer and user-defined types which are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: +- This check recognizes `std::shared_pointer` and user-defined types that are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: - overloaded dereference or member access operators (public and non-deleted); -- copy constructor or copy assignment operator (public and non-deleted); +- a copy constructor or copy assignment operator (public and non-deleted); -- public destructor which is neither deleted nor defaulted. Empty destructors are still counted as user-defined. +- a public destructor that isn't deleted or defaulted. Empty destructors are still counted as user-defined. - The action of resetting or reassigning is interpreted in a more generic way: - any call to a non-constant function on a shared pointer can potentially reset the pointer; -- any call to a function which accepts a reference to a non-constant shared pointer can potentially reset or reassign that pointer. +- any call to a function that accepts a reference to a non-constant shared pointer can potentially reset or reassign that pointer. ## Examples diff --git a/docs/code-quality/c26418.md b/docs/code-quality/c26418.md index 7c5c2eb4698..d29c62c8656 100644 --- a/docs/code-quality/c26418.md +++ b/docs/code-quality/c26418.md @@ -1,30 +1,29 @@ --- -description: "Learn more about: C26418 NO_VALUE_OR_CONST_REF_SHARED_PTR" -title: C26418| Microsoft Docs +description: "Learn more about: Warning C26418 NO_VALUE_OR_CONST_REF_SHARED_PTR" +title: Warning C26418 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26418"] +f1_keywords: ["C26418", "NO_VALUE_OR_CONST_REF_SHARED_PTR"] helpviewer_keywords: ["C26418"] ms.assetid: d2c84a40-8a5d-4018-92c2-6498cdd9b541 --- -# C26418 NO_VALUE_OR_CONST_REF_SHARED_PTR +# Warning C26418 > Shared pointer parameter is not copied or moved. Use T* or T& instead. **C++ Core Guidelines**: -[R.36](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r36-take-a-const-shared_ptrwidget-parameter-to-express-that-it-might-retain-a-reference-count-to-the-object-): Take a const shared_ptr\& parameter to express that it might retain a reference count to the object +[R.36](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-sharedptrparam-const): Take a const shared_ptr\& parameter to express that it might retain a reference count to the object -If shared pointer parameter is passed by value or reference to a constant object it is expected that function will take control of its target object’s lifetime without affecting of the caller. The code should either copy or move the shared pointer parameter to another shared pointer object or pass it further to other code by invoking functions which accept shared pointers. If this is not the case, then plain pointer or reference may be feasible. +If a shared pointer parameter is passed by value or by reference to a constant object, the function is expected to take control of the target object's lifetime without affecting the caller. The code should either copy or move the shared pointer parameter to another shared pointer object, or pass it along to other code by invoking functions that accept shared pointers. Otherwise, a plain pointer or reference may be feasible. ## Remarks -- This check recognizes std::shared_pointer and user-defined types which are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: +- This check recognizes `std::shared_pointer` and user-defined types that are likely to behave like shared pointers. The following traits are expected for user-defined shared pointers: - overloaded dereference or member access operators (public and non-deleted); -- copy constructor or copy assignment operator (public and non-deleted); +- a copy constructor or copy assignment operator (public and non-deleted); -- public destructor which is neither deleted nor defaulted. Empty destructors are still counted as user-defined. +- a public destructor that isn't deleted or defaulted. Empty destructors are still counted as user-defined. ## Examples diff --git a/docs/code-quality/c26426.md b/docs/code-quality/c26426.md index 0b9877fbff6..15289f08c7c 100644 --- a/docs/code-quality/c26426.md +++ b/docs/code-quality/c26426.md @@ -1,34 +1,36 @@ --- -description: "Learn more about: C26426 NO_GLOBAL_INIT_CALLS" -title: C26426 +description: "Learn more about: Warning C26426 NO_GLOBAL_INIT_CALLS" +title: Warning C26426 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26426"] +f1_keywords: ["C26426", "NO_GLOBAL_INIT_CALLS"] helpviewer_keywords: ["C26426"] ms.assetid: 6fb5f6d2-b097-47f8-8b49-f2fd4e9bef0e --- -# C26426 NO_GLOBAL_INIT_CALLS +# Warning C26426 -"Global initializer calls a non-constexpr function." +> Global initializer calls a non-constexpr function '*symbol*' (i.22) -**C++ Core Guidelines**: -[I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects): Avoid complex initialization of global objects +## C++ Core Guidelines -The order of execution of initializers for global objects may be inconsistent or undefined. This can lead to issues that are hard to reproduce and investigate. To avoid such problems, global initializers should not depend on external code that's executed at run time and can potentially depend on data that's not yet initialized. This rule flags cases where global objects call functions to obtain their initial values. +[I.22](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-global-init): Avoid complex initialization of global objects + +The order of execution of initializers for global objects may be inconsistent or undefined, which can lead to issues that are hard to reproduce and investigate. To avoid such problems, global initializers shouldn't depend on external code that's executed at run time, and that may depend on data that's not yet initialized. This rule flags cases where global objects call functions to obtain their initial values. ## Remarks -- The rule ignores calls to constexpr functions or intrinsic functions on assumption that these either will be calculated at compile time or guarantee predictable execution at run time. +- The rule ignores calls to `constexpr` functions or intrinsic functions on the assumption that these calls either will be calculated at compile time or guarantee predictable execution at run time. -- Calls to inline functions are still flagged since the checker doesn’t attempt to analyze their implementation. +- Calls to inline functions are still flagged, since the checker doesn't attempt to analyze their implementation. -- This rule can be noisy in many common scenarios where a variable of a user-defined type (or standard container) is initialized globally: this is often due to calls to constructors and destructors. This is still a valid warning since it points to places where unpredictable behavior may exist or future changes in external code may introduce instability. +- This rule can be noisy in many common scenarios where a variable of a user-defined type (or a standard container) is initialized globally. It's often due to calls to constructors and destructors. It's still a valid warning, since it points to places where unpredictable behavior may exist or where future changes in external code may introduce instability. - Static class members are considered global, so their initializers are also checked. +Code analysis name: `NO_GLOBAL_INIT_CALLS` + ## Examples -external version check +External version check: ```cpp // api.cpp @@ -42,7 +44,7 @@ int get_api_version() noexcept; bool is_legacy_mode = get_api_version() <= API_LEGACY_VERSION; // C26426, also stale value ``` -external version check – made more reliable +External version check made more reliable: ```cpp // api.cpp diff --git a/docs/code-quality/c26427.md b/docs/code-quality/c26427.md index 97f63d5b5cb..5586e4d46a4 100644 --- a/docs/code-quality/c26427.md +++ b/docs/code-quality/c26427.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C26427 NO_GLOBAL_INIT_EXTERNS" -title: C26427 +description: "Learn more about: Warning C26427 NO_GLOBAL_INIT_EXTERNS" +title: Warning C26427 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26427"] +f1_keywords: ["C26427", "NO_GLOBAL_INIT_EXTERNS"] helpviewer_keywords: ["C26427"] ms.assetid: 8fb95a44-8704-45b1-bc55-eccd59b1db2f --- -# C26427 NO_GLOBAL_INIT_EXTERNS +# Warning C26427 -"Global initializer accesses extern object." +> Global initializer accesses extern object '*symbol*' (i.22) **C++ Core Guidelines**: -[I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects): Avoid complex initialization of global objects +[I.22](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-global-init): Avoid complex initialization of global objects Global objects may be initialized in an inconsistent or undefined order, which means that interdependency between them is risky and should be avoided. This guideline is applicable when initializers refer to another object that's considered to be **`extern`**. @@ -20,14 +19,16 @@ Global objects may be initialized in an inconsistent or undefined order, which m An object is deemed **`extern`** if it conforms to the following rules: -- it's a global variable marked with **`extern`** specifier or it is a static member of a class; +- it's a global variable marked with **`extern`** specifier or it's a static member of a class; - it's not in an anonymous namespace; - it's not marked as **`const`**; - Static class members are considered global, so their initializers are also checked. +Code analysis name: `NO_GLOBAL_INIT_EXTERNS` + ## Example -external version check +External version check: ```cpp // api.cpp @@ -38,7 +39,7 @@ extern int api_version; bool is_legacy_mode = api_version <= API_LEGACY_VERSION; // C26427, also stale value ``` -external version check – made more reliable +External version check made more reliable: ```cpp // api.cpp diff --git a/docs/code-quality/c26429.md b/docs/code-quality/c26429.md index de8800ee3ff..857bffecf9d 100644 --- a/docs/code-quality/c26429.md +++ b/docs/code-quality/c26429.md @@ -1,35 +1,39 @@ --- -description: "Learn more about: C26429 USE_NOTNULL" -title: C26429 +description: "Learn more about: Warning C26429 USE_NOTNULL" +title: Warning C26429 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26429"] +f1_keywords: ["C26429", "USE_NOTNULL"] helpviewer_keywords: ["C26429"] ms.assetid: 4e1c74d5-7307-436c-927b-f74ae863282c - --- -# C26429 USE_NOTNULL +# Warning C26429 -"Symbol is never tested for nullness, it can be marked as gsl::not_null." +> Symbol is never tested for nullness, it can be marked as `gsl::not_null`. **C++ Core Guidelines**: -[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" is not a valid value +[F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr): Use a `not_null` to indicate that "null" is not a valid value -It is a common practice to use asserts to enforce assumptions about validity of pointer values. The problem with asserts is that they do not expose assumptions through the interface (e.g. in return types or parameters). Asserts are also harder to maintain and keep in sync with other code changes. The recommendation is to use gsl::not_null from the Guidelines Support Library as a marker of resources which should never have null value. The rule USE_NOTNULL helps to identify places that omit checks for nullness and hence can be updated to use gsl::not_null. +It's a common practice to use asserts to enforce assumptions about the validity of pointer values. The problem is, asserts don't expose assumptions through the interface (such as in return types or parameters). Asserts are also harder to maintain and keep in sync with other code changes. The recommendation is to use `gsl::not_null` from the Guidelines Support Library to mark resources that should never have a null value. The rule `USE_NOTNULL` helps to identify places that omit checks for null and hence can be updated to use `gsl::not_null`. ## Remarks -- The logic of the rule requires code to dereference a pointer variable so that nullness check (or enforcement of non-null value) would be justified. So, warning will be emitted only if pointers are dereferenced and never tested for nullness. - - Current implementation handles only plain pointers (or their aliases) and doesn’t detect smart pointers even though gsl::not_null can be applied to smart pointers as well. - - A variable is marked as checked for nullness when it is used in the following contexts: - - as a symbol expression in a branch condition, e.g. "if (p) { ... }"; - - non-bitwise logical operations; - - comparison operations where one operand is a constant expression which evaluates to zero. - - The rule doesn’t have full dataflow tracking and can produce incorrect results in cases where indirect checks are used (e.g. when intermediate variable holds null value and later used in comparison). +The logic of the rule requires code to dereference a pointer variable so that a null check (or enforcement of a non-null value) would be justified. So, warnings are emitted only if pointers are dereferenced and never tested for null. + +The current implementation handles only plain pointers (or their aliases) and doesn't detect smart pointers, even though `gsl::not_null` can be applied to smart pointers as well. + +A variable is marked as checked for null when it's used in the following contexts: + +- as a symbol expression in a branch condition, for example, `if (p) { ... }`; +- non-bitwise logical operations; +- comparison operations where one operand is a constant expression that evaluates to zero. + +The rule doesn't have full dataflow tracking. It can produce incorrect results in cases where indirect checks are used (such as when an intermediate variable holds a null value and is later used in a comparison). + +Code analysis name: `USE_NOTNULL` ## Example -hidden expectation +Hidden expectation: ```cpp using client_collection = gsl::span; @@ -46,7 +50,7 @@ void keep_alive(const connection *connection) // C26429 } ``` -hidden expectation – clarified by gsl::not_null +Hidden expectation clarified by `gsl::not_null`: ```cpp using client_collection = gsl::span>; diff --git a/docs/code-quality/c26430.md b/docs/code-quality/c26430.md index e3a54f4e0ba..92fa6af1ec7 100644 --- a/docs/code-quality/c26430.md +++ b/docs/code-quality/c26430.md @@ -1,34 +1,36 @@ --- -description: "Learn more about: C26430 TEST_ON_ALL_PATHS" -title: C26430 +description: "Learn more about: Warning C26430 TEST_ON_ALL_PATHS" +title: Warning C26430 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26430"] +f1_keywords: ["C26430", "TEST_ON_ALL_PATHS"] helpviewer_keywords: ["C26430"] ms.assetid: 3dca2626-8102-4eed-8ff3-73eb3d5c328c - --- -# C26430 TEST_ON_ALL_PATHS +# Warning C26430 -"Symbol is not tested for nullness on all paths." +> Symbol is not tested for nullness on all paths. **C++ Core Guidelines**: -[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" is not a valid value +[F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr): Use a not_null\ to indicate that "null" is not a valid value -If code ever checks nullness of pointer variables it should do this consistently and validate pointers on all paths. Sometimes overaggressive checking for nullness is still better than possibility of a hard crash in one of the complicated branches. Ideally such code should be refactored to be less complex (by splitting into multiple functions) and to rely on markers like gsl::not_null (see Guidelines Support Library) to isolate parts of algorithm that can make safe assumption about valid pointer values. The rule TEST_ON_ALL_PATHS helps to find places where nullness checks are either inconsistent (hence assumptions may require review) or actual bugs where potential null value can bypass nullness check in some of the code paths. +If code ever checks pointer variables for null, it should do so consistently and validate pointers on all paths. Sometimes overaggressive checking for null is still better than the possibility of a hard crash in one of the complicated branches. Ideally, such code should be refactored to be less complex (by splitting it into multiple functions), and to rely on markers like `gsl::not_null`. These markers allow the code to isolate parts of the algorithm that can make safe assumptions about valid pointer values. The rule `TEST_ON_ALL_PATHS` helps to find places where null checks are inconsistent (meaning assumptions may require review). Or, it finds actual bugs where a potential null value can bypass null checks in some of the code paths. ## Remarks -- This rule expects that code dereferences a pointer variable so that nullness check (or enforcement of non-null value) would be justified. If there is no dereference, the rule is suspended. - - Current implementation handles only plain pointers (or their aliases) and doesn’t detect smart pointers even though nullness checks are applicable to smart pointers as well. - - A variable is marked as checked for nullness when it is used in the following contexts: - - as a symbol expression in a branch condition, e.g. "if (p) { ... }"; - - non-bitwise logical operations; - - comparison operations where one operand is a constant expression which evaluates to zero. - - The rule doesn’t have full data flow tracking and can produce incorrect results in cases where indirect checks are used (e.g. when intermediate variable holds null value and later used in comparison). - - Implicit nullness checks are assumed when pointer value is assigned from: - - an allocation performed with throwing operator new; - - a pointer obtained from type marked with gsl::not_null. +This rule expects that code dereferences a pointer variable so that a null check (or enforcement of a non-null value) would be justified. If there's no dereference, the rule is suspended. + +The current implementation handles only plain pointers (or their aliases) and doesn't detect smart pointers, even though null checks are applicable to smart pointers as well. + +A variable is marked as checked for null when it's used in the following contexts: + +- as a symbol expression in a branch condition, for example, in `if (p) { ... }`; +- in non-bitwise logical operations; +- in comparison operations where one operand is a constant expression that evaluates to zero. + +Implicit null checks are assumed when a pointer value is assigned from: + +- an allocation performed with throwing `operator new`; +- a pointer obtained from a type marked with `gsl::not_null`. ## Example @@ -63,3 +65,36 @@ void merge_states(gsl::not_null left, gsl::not_null The type of expression '*expr*' is already `gsl::not_null`. Do not test it for nullness (f.23) **C++ Core Guidelines**: -[F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value): Use a not_null\ to indicate that "null" is not a valid value +[F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr): Use a not_null\ to indicate that "null" is not a valid value -The marker type gsl::not_null from Guidelines Support Library is used to clearly indicate values that are never null pointers. It causes a hard failure if such assumption is not held at run time. So, obviously, there is no need to check for nullness if expression evaluates to a result of type gsl::not_null. +The marker type `gsl::not_null` from the Guidelines Support Library is used to clearly indicate values that are never null pointers. It causes a hard failure if the assumption doesn't hold at run time. So, obviously, there's no need to check for null if an expression evaluates to a result of type `gsl::not_null`. ## Remarks -- Since gsl::not_null itself is a thin pointer wrapper class, the rule actually tracks temporary variables that hold results from calls to the overloaded conversion operator (which returns contained pointer object). Such logic makes this rule applicable to expressions that involve variables and eventually have result of the gsl::not_null type. But it currently skips expressions that contain function calls returning gsl::not_null. - - Current heuristic for nullness checks detects the following contexts: - - symbol expression in a branch condition, for example "if (p) { ... }"; - - non-bitwise logical operations; - - comparison operations where one operand is a constant expression that evaluates to zero. +Since `gsl::not_null` itself is a thin pointer wrapper class, the rule actually tracks temporary variables that hold results from calls to the overloaded conversion operator (which returns contained pointer objects). Such logic makes this rule applicable to expressions that involve variables and eventually have a result of the `gsl::not_null` type. However, it currently skips expressions that contain function calls returning `gsl::not_null`. + +The current heuristic for null checks detects the following contexts: + +- a symbol expression in a branch condition, for example `if (p) { ... }`; +- non-bitwise logical operations; +- comparison operations where one operand is a constant expression that evaluates to zero. + +Code analysis name: `DONT_TEST_NOTNULL` ## Example -unnecessary null checks reveal questionable logic +Unnecessary null checks reveal questionable logic: ```cpp class type { @@ -58,7 +60,7 @@ public: }; ``` -unnecessary null checks reveal questionable logic - reworked +Unnecessary null checks reveal questionable logic, reworked: ```cpp //... diff --git a/docs/code-quality/c26432.md b/docs/code-quality/c26432.md index d98e920d657..98a45f3475e 100644 --- a/docs/code-quality/c26432.md +++ b/docs/code-quality/c26432.md @@ -1,32 +1,34 @@ --- -title: C26432 +title: Warning C26432 description: "Microsoft C++ Code Analysis warning C26432 for the C++ Core Guidelines case C.21." ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26432"] +f1_keywords: ["C26432", "DEFINE_OR_DELETE_SPECIAL_OPS"] helpviewer_keywords: ["C26432"] -ms.assetid: f587b05a-5c69-4176-baa6-fcb79d228b24 --- -# C26432 DEFINE_OR_DELETE_SPECIAL_OPS +# Warning C26432 > `If you define or delete any default operation in the type 'type-name', define or delete them all (c.21).` **C++ Core Guidelines**:\ -[C.21: If you define or =delete any default operation, define or =delete them all](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c21-if-you-define-or-delete-any-default-operation-define-or-delete-them-all) +[C.21: If you define or `=delete` any copy, move, or destructor function, define or `=delete` them all](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rc-five) Special operations such as constructors are assumed to alter the behavior of types so they rely more on language mechanisms to automatically enforce specific scenarios. The canonical example is resource management. If you explicitly define, default, or delete any of these special operations, it signals you want to avoid any special handling of a type. It's inconsistent to leave the other operations unspecified, that is, implicitly defined as deleted by the compiler. ## Remarks -- This check implements the *rule of five*, which treats the following operations as special: - - copy constructors, - - move constructors, - - copy assignment operators, - - move assignment operators, and - - destructors. -- The rule doesn't check if operations are defined in the same way. It's okay to mix deleted and defaulted operations with explicitly defined ones. However, you must specify all of them if you specify any of them. -- Access levels aren't important and can also be mixed. -- The warning flags the first non-static function definition of a type, once per type. +This check implements the *rule of five*, which treats the following operations as special: + +- copy constructors, +- move constructors, +- copy assignment operators, +- move assignment operators, and +- destructors. + +The rule doesn't check if operations are defined in the same way. It's okay to mix deleted and defaulted operations with explicitly defined ones. However, you must specify all of them if you specify any of them. + +Access levels aren't important and can also be mixed. + +The warning flags the first non-static function definition of a type, once per type. ## Example diff --git a/docs/code-quality/c26433.md b/docs/code-quality/c26433.md index 6f7553f7f9b..20d866f966d 100644 --- a/docs/code-quality/c26433.md +++ b/docs/code-quality/c26433.md @@ -1,30 +1,31 @@ --- -description: "Learn more about: C26433 OVERRIDE_EXPLICITLY" -title: C26433 -keywords: C26433 +title: Warning C26433 +description: "Learn more about: Warning C26433 OVERRIDE_EXPLICITLY" ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26433"] +f1_keywords: ["C26433", "OVERRIDE_EXPLICITLY"] helpviewer_keywords: ["C26433"] -dev_langs: ["C++"] --- -# C26433 OVERRIDE_EXPLICITLY +# Warning C26433 -Function should be marked with `override` +> Function should be marked with `override` ## C++ Core Guidelines -[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override) -It's not required by the compiler to clearly state that a virtual function overrides its base. Not specifying `override` can cause subtle issues during maintenance if the virtual specification ever changes in the class hierarchy. It also lowers readability and makes an interface's polymorphic behavior less obvious. If a function is clearly marked as `override`, it enables the compiler to check consistency of the interface and help to spot issues before they manifest themselves at run time. +It's not required by the compiler to clearly state that a virtual function overrides its base. Not specifying `override` can cause subtle issues during maintenance if the virtual specification ever changes in the class hierarchy. It also lowers readability and makes an interface's polymorphic behavior less obvious. If a function is clearly marked as `override`, the compiler can check the consistency of the interface, and help to spot issues before they manifest themselves at run time. ## Notes -1. This rule isn't applicable to destructors. Destructors have their own virtuality specifics. -1. The rule doesn't flag functions explicitly marked as `final`, which is itself a special variety of virtual specifier. -1. Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still correct. +This rule isn't applicable to destructors. Destructors have their own virtuality specifics. -## Example: Implicit overriding +The rule doesn't flag functions explicitly marked as `final`, which is itself a special variety of virtual specifier. + +Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still correct. + +Code analysis name: `OVERRIDE_EXPLICITLY` + +## Example: Implicit overriding ```cpp class Shape { @@ -43,4 +44,4 @@ public: ## See also -[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override) diff --git a/docs/code-quality/c26434.md b/docs/code-quality/c26434.md index 72041cdace8..197a57cbcf8 100644 --- a/docs/code-quality/c26434.md +++ b/docs/code-quality/c26434.md @@ -1,23 +1,21 @@ --- -title: C26434 +title: Warning C26434 description: "Microsoft C++ Code Analysis warning C26434 for the C++ Core Guidelines case C.128." ms.date: 08/21/2020 -ms.topic: "conceptual" -f1_keywords: ["C26434"] +f1_keywords: ["C26434", "DONT_HIDE_METHODS"] helpviewer_keywords: ["C26434"] -ms.assetid: 7f66477f-da66-444a-a6e3-44513d7d7e31 --- -# C26434 DONT_HIDE_METHODS +# Warning C26434 -> `Function 'derived::function' hides a non-virtual function 'base::function' (c.128).` +> Function 'derived::function' hides a non-virtual function 'base::function' (c.128). ## C++ Core Guidelines -[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override) ## Remarks -When you introduce a function that has the same name as a non-virtual function in a base class, you may get unexpected behavior. It's like introducing a variable name which conflicts with a name from an outer scope. For example, you may have intended to override a base class function. If the signatures of the functions don't match, the override you intended may turn into an overload instead. In general, name hiding is dangerous and error-prone. +When you introduce a function that has the same name as a non-virtual function in a base class, you may get unexpected behavior. It's like introducing a variable name that conflicts with a name from an outer scope. For example, you may have intended to override a base class function. If the signatures of the functions don't match, the override you intended may turn into an overload instead. In general, name hiding is dangerous and error-prone. In the Core Guidelines checks: @@ -45,5 +43,4 @@ struct Derived : Base void not_virtual() noexcept {} // C26434, hides a non-virtual function virtual void not_virtual(int i) noexcept {} // C26434, and parameters ignored }; - ``` diff --git a/docs/code-quality/c26435.md b/docs/code-quality/c26435.md index 5aee50571a1..61b57161dc4 100644 --- a/docs/code-quality/c26435.md +++ b/docs/code-quality/c26435.md @@ -1,32 +1,31 @@ --- -description: "Learn more about: C26435 SINGLE_VIRTUAL_SPECIFICATION" -title: C26435 -keywords: C26435 +description: "Learn more about: Warning C26435 SINGLE_VIRTUAL_SPECIFICATION" +title: Warning C26435 ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26435"] +f1_keywords: ["C26435", "SINGLE_VIRTUAL_SPECIFICATION"] helpviewer_keywords: ["C26435"] -dev_langs: ["C++"] --- -# C26435 SINGLE_VIRTUAL_SPECIFICATION +# Warning C26435 -"Function should specify exactly one of 'virtual', 'override', or 'final'." +> The virtual function '*symbol*' should specify exactly one of 'virtual', 'override', or 'final' (c.128) ## C++ Core Guidelines -[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override) To improve readability, the kind of virtual behavior should be stated clearly and without unnecessary redundancy. Even though multiple virtual specifiers can be used simultaneously, it's better to specify one at a time to emphasize the most important aspect of virtual behavior. The following order of importance is apparent: - plain virtual function; -- virtual function which explicitly overrides its base; -- virtual function which overrides its base and provides the final implementation in the current inheritance chain. +- virtual function that explicitly overrides its base; +- virtual function that overrides its base and provides the final implementation in the current inheritance chain. ## Notes - This rule skips destructors since they have special rules regarding virtuality. - Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still appropriate. +Code analysis name: `SINGLE_VIRTUAL_SPECIFICATION` + ## Example: Redundant specifier ```cpp @@ -42,9 +41,12 @@ public: void Draw() override final { // C26435, only 'final' is necessary. //... } + virtual void DrawCircumference() final { // C26435, should be neither 'virtual' nor 'final'. + //... + } }; ``` ## See also -[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) diff --git a/docs/code-quality/c26436.md b/docs/code-quality/c26436.md index 3953b426655..f2c433854f4 100644 --- a/docs/code-quality/c26436.md +++ b/docs/code-quality/c26436.md @@ -1,24 +1,26 @@ --- -title: C26436 +title: Warning C26436 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26436"] +f1_keywords: ["C26436", "NEED_VIRTUAL_DTOR"] helpviewer_keywords: ["C26436"] ms.assetid: 82d14d5d-5c5d-4e27-bdc8-268f9973a312 description: CppCoreCheck rule that enforces C++ Core Guidelines C.35 --- -# C26436 NEED_VIRTUAL_DTOR +# Warning C26436 -"The type with a virtual function needs either public virtual or protected nonvirtual destructor." +> The type '*symbol*' with a virtual function needs either public virtual or protected non-virtual destructor (c.35) -[**C++ Core Guidelines**: C.35](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c35-a-base-class-destructor-should-be-either-public-and-virtual-or-protected-and-non-virtual): A base class destructor should be either public and virtual, or protected and nonvirtual +[**C++ Core Guidelines**: C.35](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rc-dtor-virtual): A base class destructor should be either public and virtual, or protected and non-virtual -If a class defines a virtual function it becomes polymorphic, which implies that derived classes can change its behavior including resource management and destruction logic. Because client code may call polymorphic types via pointers to base classes, there is no way a client can explicitly choose which behavior is appropriate without downcasting. To make sure that resources are managed consistently and destruction occurs according to the actual type's rules it is recommended to define a public virtual destructor. If the type hierarchy is designed to disallow client code to destroy objects directly, destructors should be defined as protected non-virtual. +If a class defines a virtual function it becomes polymorphic, which implies that derived classes can change its behavior including resource management and destruction logic. Because client code may call polymorphic types via pointers to base classes, there's no way a client can explicitly choose which behavior is appropriate without downcasting. To make sure that resources are managed consistently and destruction occurs according to the actual type's rules, you should define a public virtual destructor. If the type hierarchy is designed to disallow client code to destroy objects directly, destructors should be defined as protected non-virtual. ## Remarks -- The warning shows up on the first virtual function definition of a type (it can be a virtual destructor if it is not public), once per type. - - Since definition can be placed separately from declaration, it may not always have any of the virtual specifiers. But the warning is still valid – it checks the actual 'virtuality' of a function. +- The warning shows up on the first virtual function definition of a type (it can be a virtual destructor if it isn't public), once per type. + +- Since a definition can be placed separately from a declaration, it may not always have any of the virtual specifiers. But the warning is still valid: it checks the actual 'virtuality' of a function. + +Code analysis name: `NEED_VIRTUAL_DTOR` ## Example @@ -31,7 +33,7 @@ namespace no_destructor } ``` -The warning does not appear when the base class has either a virtual public destructor or a protected non-virtual destructor. +The warning doesn't appear when the base class has either a virtual public destructor or a protected non-virtual destructor. ```cpp namespace virtual_destructor diff --git a/docs/code-quality/c26437.md b/docs/code-quality/c26437.md index 4c4bf445b92..1ec3dbc4327 100644 --- a/docs/code-quality/c26437.md +++ b/docs/code-quality/c26437.md @@ -1,33 +1,30 @@ --- -description: "Learn more about: C26437 DONT_SLICE" -title: C26437 -ms.date: 10/07/2019 -ms.topic: "conceptual" -f1_keywords: ["C26437"] +title: Warning C26437 +description: "Learn more about: Warning C26437 DONT_SLICE" +ms.date: 05/17/2023 +f1_keywords: ["C26437", "DONT_SLICE"] helpviewer_keywords: ["C26437"] -ms.assetid: ed2f55bc-a6d8-4cc4-8069-5c96e581a96a - --- -# C26437 DONT_SLICE +# Warning C26437 -"Do not slice." +> Do not slice. **C++ Core Guidelines**: -[ES.63: Don't slice](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-slice) +[ES.63: Don't slice](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-slice) -[Slicing](https://en.wikipedia.org/wiki/Object_slicing) is allowed by compiler and can be viewed as a special case of dangerous implicit cast. Even if it is done intentionally and doesn’t lead to immediate issues, it is still highly discouraged since it makes code rather unmaintainable by forcing additional requirements on related data types. This is especially true if types are polymorphic or involve resource management. +The language allows [slicing](https://en.wikipedia.org/wiki/Object_slicing) and can be viewed as a special case of a dangerous implicit cast. Even if it's done intentionally and doesn't lead to immediate issues, it's still highly discouraged. It makes code harder to change, by forcing extra requirements on related data types. It's especially true if types are polymorphic or involve resource management. ## Remarks -- This rule would warn not only on explicit assignments, but also on implicit slicing which happens when result gets returned from current function or data passed as arguments to other functions. - - Warnings would also flag cases where assignment doesn’t involve real data slicing (e.g. if types are empty or don’t make any dangerous data manipulations). Such warnings should still be addressed to prevent any undesirable regressions if types data or behavior changes in future. +This rule warns not only on explicit assignments, but also on implicit slicing. Implicit slicing happens when a result gets returned from the current function, or when data gets passed to other functions. + +The rule also flags cases where an assignment doesn't involve real data slicing (for example, if types are empty or don't make any dangerous data manipulations). Such warnings should still be fixed to prevent any undesirable regressions if data types or behaviors change in the future. ## Example -slicing points to outdated +In the next code example, we read `id_ex`, but the caller of the function will only get a slice of the object: ```cpp -interface struct id { int value; }; @@ -46,7 +43,7 @@ bool read_id(stream &s, id &v) { } ``` -slicing points to outdated, interface - corrected +To fix the issue, update the function to use the correct types: ```cpp // ... diff --git a/docs/code-quality/c26438.md b/docs/code-quality/c26438.md index a5b0371fc5c..dd7f16b4ebf 100644 --- a/docs/code-quality/c26438.md +++ b/docs/code-quality/c26438.md @@ -1,27 +1,27 @@ --- -description: "Learn more about: C26438 NO_GOTO" -title: C26438 +description: "Learn more about: Warning C26438 NO_GOTO" +title: Warning C26438 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26438"] +f1_keywords: ["C26438", "NO_GOTO"] helpviewer_keywords: ["C26438"] ms.assetid: c7b3f59c-fb2f-4816-bda4-0fad23c80d83 - --- -# C26438 NO_GOTO +# Warning C26438 -"Avoid **`goto`**." +> Avoid `goto` (es.76) **C++ Core Guidelines**:\ -[ES.76](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es76-avoid-goto): Avoid goto +[ES.76](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-goto): Avoid goto The use of **`goto`** is widely considered a dangerous and error-prone practice. It's acceptable only in generated code, such as in a parser generated from a grammar. With modern C++ features and utilities provided by the Guidelines Support Library, it should be easy to avoid **`goto`** altogether. ## Remarks -- This rule warns on any occurrence of **`goto`**, even if it happens in dead code, except template code that's never used and consequently ignored by compiler. +- This rule warns on any occurrence of **`goto`**, even if it happens in dead code, except template code that's never used and so is ignored by the compiler. - Warnings can multiply when a macro contains **`goto`**. Current reporting mechanisms point to all instances where such a macro gets expanded. It can often be fixed in one place by changing the macro, or avoiding its use in favor of more maintainable mechanisms. +Code analysis name: `NO_GOTO` + ## Example 'goto clean-up' in macro @@ -47,7 +47,7 @@ end: } ``` -'goto clean-up' in macro - replaced with gsl::finally +'goto clean-up' in macro, replaced with `gsl::finally` ```cpp void poll(connection &c) diff --git a/docs/code-quality/c26439.md b/docs/code-quality/c26439.md index b68822de7f9..385f65ca546 100644 --- a/docs/code-quality/c26439.md +++ b/docs/code-quality/c26439.md @@ -1,39 +1,40 @@ --- -title: C26439 -ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26439"] -helpviewer_keywords: ["C26439"] -ms.assetid: 9df2a1b0-ea94-4884-9d28-c1522ec33a1b +title: Warning C26439 description: CppCoreCheck rule C26439 that enforces C++ Core Guidelines F.6 +ms.date: 05/17/2023 +f1_keywords: ["C26439", "SPECIAL_NOEXCEPT"] +helpviewer_keywords: ["C26439"] --- -# C26439 SPECIAL_NOEXCEPT +# Warning C26439 + +> This kind of function may not throw. Declare it 'noexcept'. + +[F.6: If your function must not throw, declare it `noexcept`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-noexcept) -"This kind of function may not throw. Declare it 'noexcept'." +Some operations should never throw exceptions. Their implementations should be reliable and should handle possible errors conditions gracefully. They shouldn't use exceptions to indicate failure. This rule flags cases where such operations aren't explicitly marked as `noexcept`, which means that they may throw exceptions and consumers can't make assumptions about its reliability. -[**C++ Core Guidelines** F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept): If your function may not throw, declare it noexcept +It's important for these functions to be reliable as they're often used as building blocks to implement functions with [exception safety guarantees](https://en.cppreference.com/w/cpp/language/exceptions). A move constructor that throws will force Standard Template Library (STL) containers to fall back to copy operations, reducing runtime performance. -Some kinds of operations should never cause exceptions. Their implementations should be reliable and should handle possible errors conditions gracefully. They should never use exceptions to indicate failure. This rule flags cases where such operations are not explicitly marked as 'noexcept' which means that they may throw exceptions and cannot convey assumptions about their reliability. +Code analysis name: `SPECIAL_NOEXCEPT` ## Remarks -- Special kinds of operations are the following: +- Special kinds of operations: - destructors; - - default constructors; - move constructors and move assignment operators; - - standard functions with move semantics: std::move and std::swap. -- Non-standard and outdated specifiers like throw() or declspec(nothrow) are not equivalent to 'noexcept'. -- Explicit specifiers noexcept(false) and noexcept(true) are respected appropriately. -- The warning may still appear for operations that are marked as constexpr. This may change in future releases. + - standard functions with move semantics: `std::move` and `std::swap`. + +- Nonstandard and outdated specifiers like `throw()` or `declspec(nothrow)` aren't equivalent to `noexcept`. + +- Explicit specifiers `noexcept(false)` and `noexcept(true)` are respected appropriately. ## Example -All functions except the destructor will warn because they are missing noexcept. +The tool warns on all functions except the destructor because they're missing `noexcept`. ```cpp struct S { - S() {} // C26455, Default constructor may not throw. Declare it 'noexcept' ~S() {} S(S&& s) {/*impl*/} // C26439, This kind of function may not throw. Declare it 'noexcept' (f.6) @@ -44,12 +45,11 @@ struct S }; ``` -With noexcept decorating the same structure, all warnings are removed. +With `noexcept` decorating the same structure, all warnings are removed. ```cpp struct S { - S() noexcept {} ~S() {} S(S&& s) noexcept {/*impl*/} @@ -59,3 +59,8 @@ struct S S& operator=(const S& s) noexcept {/*impl*/} }; ``` + +## See also + +[C26455](c26455.md)\ +[F.6: If your function must not throw, declare it `noexcept`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-noexcept) diff --git a/docs/code-quality/c26440.md b/docs/code-quality/c26440.md index df691de7f1a..62a9c87e536 100644 --- a/docs/code-quality/c26440.md +++ b/docs/code-quality/c26440.md @@ -1,34 +1,33 @@ --- -title: C26440 +title: Warning C26440 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26440"] +f1_keywords: ["C26440", "DECLARE_NOEXCEPT"] helpviewer_keywords: ["C26440"] ms.assetid: b6d2b188-35cc-4de2-878c-6f97d5a2444a description: CppCoreCheck rule C26440 that enforces C++ Core Guidelines F.6 --- -# C26440 DECLARE_NOEXCEPT +# Warning C26440 -"Function can be declared 'noexcept'." +> Function can be declared 'noexcept'. -[**C++ Core Guidelines** F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept): If your function may not throw, declare it noexcept +[**C++ Core Guidelines** F.6](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-noexcept): If your function must not throw, declare it `noexcept` -If code is not supposed to cause any exceptions, it should be marked as such by using the 'noexcept' specifier. This would help to simplify error handling on the client code side, as well as enable compiler to do additional optimizations. +If code isn't supposed to cause any exceptions, it should be marked by using the `noexcept` specifier. This annotation helps to simplify error handling on the client code side, and enables the compiler to do more optimizations. ## Remarks - A function is considered non-throwing if: - - it has no explicit throw statements; - - function calls in its body, if any, invoke only functions that unlikely to throw: constexpr or functions marked with any exception specification which entails non-throwing behavior (this includes some non-standard specifications). -- Non-standard and outdated specifiers like throw() or declspec(nothrow) are not equivalent to 'noexcept'. -- Explicit specifiers noexcept(false) and noexcept(true) are respected appropriately. -- Functions marked as constexpr are not supposed to cause exceptions and are not analyzed. + - it has no explicit `throw` statements; + - function calls in its body, if any, invoke only functions that are unlikely to throw: `constexpr` or functions marked with any exception specification that entails non-throwing behavior (including some non-standard specifications). +- Non-standard and outdated specifiers like `throw()` or `__declspec(nothrow)` aren't equivalent to `noexcept`. +- Explicit specifiers `noexcept(false)` and `noexcept(true)` are respected appropriately. +- Functions marked as `constexpr` aren't supposed to cause exceptions and aren't analyzed. - The rule also applies to lambda expressions. -- The logic doesn't consider recursive calls as potentially non-throwing. This may change in the future. +- The logic doesn't consider recursive calls as potentially non-throwing. This logic may change in the future. ## Example -All functions except the destructor will warn because they are missing noexcept. +All functions except the destructor will warn because they're missing noexcept. ```cpp struct S diff --git a/docs/code-quality/c26441.md b/docs/code-quality/c26441.md index 9acc8449202..a91a41ff873 100644 --- a/docs/code-quality/c26441.md +++ b/docs/code-quality/c26441.md @@ -1,57 +1,68 @@ --- -description: "Learn more about: C26441 NO_UNNAMED_GUARDS" -title: C26441 -ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26441"] +title: Warning C26441 +description: "Learn more about: Warning C26441 NO_UNNAMED_GUARDS." +ms.date: 5/11/2023 +f1_keywords: ["C26441", "NO_UNNAMED_GUARDS"] helpviewer_keywords: ["C26441"] -ms.assetid: f923c422-ed01-4644-b40b-93f15fc5bb93 - --- -# C26441 NO_UNNAMED_GUARDS +# Warning C26441 -"Guard objects must be named." +> Guard objects must be named (cp.44) -**C++ Core Guidelines**: -[CP.44](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#cp44-remember-to-name-your-lock_guards-and-unique_locks): Remember to name your lock_guards and unique_locks +## C++ Core Guidelines -The standard library provides a few useful classes which help to control concurrent access to resources. Objects of such types lock exclusive access for the duration of their lifetime. This implies that every lock object must be named, i.e. have clearly defined lifetime which spans through the period in which access operations are executed. So, failing to assign a lock object to a variable is a mistake which is effectively disables locking mechanism (because temporary variables are transient). This rule tries to catch simple cases of such unintended behavior. +[CP.44: Remember to name your `lock_guard`s and `unique_lock`s](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconc-name) ## Remarks -- Only standard lock types are tracked: std::scoped_lock, std::unique_lock, and std::lock_quard. - - Only simple calls to constructors are analyzed. More complex initializer expression may lead to inaccurate results, but this is rather an unusual scenario. - - Locks passed as arguments to function calls or returned as results of function calls are ignored. - - Locks created as temporaries but assigned to named references to extend their lifetime are ignored. +The standard library provides locks to help control concurrent access to resources during their lifetime. When you declare a lock object without a name, the compiler creates a temporary object that's immediately destructed rather than one that lives to the end of the enclosing scope. So, failure to assign a lock object to a variable is a mistake that effectively disables the locking mechanism (because temporary variables are transient). This rule catches simple cases of such unintended behavior. + +This diagnostic only analyzes the standard lock types `std::scoped_lock`, `std::unique_lock`, and `std::lock_guard`. Warning [C26444](c26444.md) covers other unnamed RAII types. + +The analyzer only analyzes simple calls to constructors. More complex initializer expressions may lead to inaccurate results in the form of missed warnings. The analyzer ignores locks passed as arguments to function calls or returned from function calls. It's unable to determine if those locks are deliberately trying to protect that function call or if their [lifetime should be extended](https://abseil.io/tips/107). To provide similar protection for types returned by a function call, annotate them with `[[nodiscard]]`. You can also annotate constructors with `[[nodiscard]]` to avoid unnamed objects of that type: + +```cpp +struct X { [[nodiscard]] X(); }; + +void f() { + X{}; // warning C4834 +} +``` + + The analyzer ignores locks created as temporaries but assigned to named references to extend their lifetime. + +Code analysis name: `NO_UNNAMED_GUARDS` ## Example -missing scoped variable +In this example, the name of the scoped lock is missing. ```cpp -void print_diagnostic(gsl::string_span<> text) +void print_diagnostic(std::string_view text) { auto stream = get_diagnostic_stream(); if (stream) { std::lock_guard{ diagnostic_mutex_ }; // C26441 write_line(stream, text); - // ... } } ``` -missing scoped variable - corrected +To fix the error, give a name to the lock, which extends its lifetime. ```cpp -void print_diagnostic(gsl::string_span<> text) +void print_diagnostic(std::string_view text) { auto stream = get_diagnostic_stream(); if (stream) { std::lock_guard lock{ diagnostic_mutex_ }; write_line(stream, text); - // ... } } ``` + +## See also + +[C26444](C26444.md) diff --git a/docs/code-quality/c26443.md b/docs/code-quality/c26443.md index 9538b58553d..e07e15b419b 100644 --- a/docs/code-quality/c26443.md +++ b/docs/code-quality/c26443.md @@ -1,23 +1,19 @@ --- -title: C26443 -keywords: C26443 +title: Warning C26443 ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26443"] +f1_keywords: ["C26443", "NO_EXPLICIT_DTOR_OVERRIDE"] helpviewer_keywords: ["C26443"] -dev_langs: ["C++"] -description: Rule concerning overriding destructors +description: Warning C26443 Rule concerning overriding destructors --- +# Warning C26443 -# C26443 NO_EXPLICIT_DTOR_OVERRIDE - -"Overriding destructor should not use explicit 'override' or 'virtual' specifiers." +> Overriding destructor should not use explicit 'override' or 'virtual' specifiers. This warning was removed in Visual Studio 16.8 to reflect [changes to C.128 in the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/pull/1448). ## C++ Core Guidelines -[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md). +[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override). The current consensus on the Core Guidelines is to exclude destructors from the 'override explicitly' recommendation. @@ -27,6 +23,8 @@ The current consensus on the Core Guidelines is to exclude destructors from the - Destructors can still use the 'final' specifier because of its special semantics. - Warnings show up on function definitions, not declarations. It may be confusing, since definitions don't have virtual specifiers, but the warning is still appropriate. +Code analysis name: `NO_EXPLICIT_DTOR_OVERRIDE` + ## Example: Explicit 'override' ```cpp @@ -46,4 +44,4 @@ public: ## See also -[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override) diff --git a/docs/code-quality/c26444.md b/docs/code-quality/c26444.md index 883d9547a65..cca16a240be 100644 --- a/docs/code-quality/c26444.md +++ b/docs/code-quality/c26444.md @@ -1,54 +1,49 @@ --- -description: "Learn more about: C26444 NO_UNNAMED_RAII_OBJECTS" -title: C26444 -keywords: C26444 -ms.date: 01/18/2017 -ms.topic: "reference" -f1_keywords: ["C26444"] +title: Warning C26444 +description: "Learn more about: Warning C26444 NO_UNNAMED_RAII_OBJECTS." +ms.date: 05/11/2023 +f1_keywords: ["C26444", "NO_UNNAMED_RAII_OBJECTS"] helpviewer_keywords: ["C26444"] -dev_langs: ["C++"] --- -# C26444 NO_UNNAMED_RAII_OBJECTS +# Warning C26444 -Avoid unnamed objects with custom construction and destruction. +> Don't try to declare a local variable with no name (es.84). ## C++ Core Guidelines -[ES.84: Don't (try to) declare a local variable with no name](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-noname) +[ES.84: Don't try to declare a local variable with no name](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-noname) -Unnamed (that is, temporary) objects with non-trivial behavior may point to either (a) inefficient code that allocates and immediately throws away resources or (b) to the code that unintentionally ignores non-primitive data. Sometimes it may also indicate plainly wrong declaration. +An unnamed variable declaration creates a temporary object that is discarded at the end of the statement. Such temporary objects with nontrivial behavior may point to either inefficient code that allocates and immediately throws away resources or to the code that unintentionally ignores nonprimitive data. Sometimes it may also indicate plainly wrong declaration. -## Notes +## Remarks -- This rule detects types with non-deleted destructors. Keep in mind that destructors can be compiler generated. -- The warning can flag code that is not compiler generated and that invokes either a non-default constructor of a RAII type or a function that returns an object of such type. This warning helps to detect ignored call results in addition to wrong declarations. -- The logic skips temporaries if they are used in higher-level expressions. One example is temporaries that are passed as arguments or used to invoke a function. -- The standard library implementation may have different versions of destruction logic for some types (for example, containers). This can produce noisy warnings on debug builds because it is customary to ignore iterators returned from calls like [std::vector::insert](../standard-library/vector-class.md#insert). While such warnings are not actionable in the majority of cases, they are legitimate in pointing to the place where some non-obvious work is done in temporary objects. +- This rule detects types with a hand-written destructor or a compiler-generated destructor that transitively calls a hand-written destructor. +- This rule can flag code that invokes a nontrivial constructor of an RAII type. +- The logic skips temporaries if they're used in higher-level expressions. One example is temporaries that are passed as arguments or used to invoke a function. -## Example: Ignored call result +Code analysis name: `NO_UNNAMED_RAII_OBJECTS` + +## Examples ```cpp -std::string ToTraceMessage(State &state); -void SaveState(State &state) +struct A { A(int i); ~A(); }; +void Foo() { - // ... - ToTraceMessage(state); // C26444, should we do something with the result of this call? + A{42}; // warning C26444: Don't try to declare a local variable with no name (es.84). } +``` -Example: Ignored call result - fixed. -std::cerr << ToTraceMessage(state); +To fix the issue, convert the temporary object to a local. -Example: Unexpected lifetime. -void SplitCache() +```cpp +struct A { A(int i); ~A(); }; +void Foo() { - gsl::finally([] { RestoreCache(); }); // C26444, RestoreCache is invoked immediately! - //... + A guard{42}; // OK. } - -Example: Unexpected lifetime - fixed. -const auto _ = gsl::finally([] { RestoreCache(); }); ``` ## See also -[ES.84: Don't (try to) declare a local variable with no name](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) +[C26441](C26441.md)\ +[ES.84: Don't try to declare a local variable with no name](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-noname) diff --git a/docs/code-quality/c26445.md b/docs/code-quality/c26445.md index 1ba9d9c2fe2..2269f7e0653 100644 --- a/docs/code-quality/c26445.md +++ b/docs/code-quality/c26445.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: C26445 NO_SPAN_REF" -title: C26445 +description: "Learn more about: Warning C26445 NO_SPAN_REF" +title: Warning C26445 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26445"] +f1_keywords: ["C26445", "NO_SPAN_REF"] helpviewer_keywords: ["C26445"] --- -# C26445 NO_SPAN_REF +# Warning C26445 + +> Do not assign `gsl::span` or `std::string_view` to a reference. They are cheap to construct and are not owners of the underlying data. (gsl.view) A reference to `gsl::span` or `std::string_view` may be an indication of a lifetime issue. ## C++ Core Guidelines -[GSL.view: Views](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslview-views) +[GSL.view: Views](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-views) -This rule catches subtle lifetime issues that may occur in code migrated from standard containers to new span and view types. Such types can be considered as "references to buffers." Using a reference to a span or view creates an additional layer of indirection. Such indirection is often unnecessary and can be confusing for maintainers. Spans are cheap to copy and can be returned by value from function calls. Obviously, such call results should never be referenced. +This rule catches subtle lifetime issues that may occur in code migrated from standard containers to new span and view types. Such types can be considered as "references to buffers." Using a reference to a span or view creates an extra layer of indirection. Such indirection is often unnecessary and can be confusing for maintainers. Spans are cheap to copy and can be returned by value from function calls. Obviously, such call results should never be referenced. ## Remarks @@ -22,13 +23,17 @@ This rule catches subtle lifetime issues that may occur in code migrated from st - Currently warnings are emitted only on declarations and return statements. This rule may be extended in future to also flag function parameters. - The implementation of this rule is lightweight doesn't attempt to trace actual lifetimes. Using of references may still make sense in some scenarios. In such cases, false positives can safely be suppressed. -## Example: Reference to a temporary +Code analysis name: `NO_SPAN_REF` + +## Example + +Reference to a temporary: ```cpp // Old API - uses string reference to avoid data copy. const std::string& get_working_directory() noexcept; -// New API – after migration to C++17 it uses string view. +// New API - after migration to C++17 it uses string view. std::string_view get_working_directory() noexcept; // ... diff --git a/docs/code-quality/c26446.md b/docs/code-quality/c26446.md index e78fef3e364..c8e7f37213f 100644 --- a/docs/code-quality/c26446.md +++ b/docs/code-quality/c26446.md @@ -1,16 +1,15 @@ --- -title: C26446 +title: Warning C26446 description: "Microsoft C++ Code Analysis warning C26446 for the C++ Core Guidelines case Bounds.4." ms.date: 08/21/2010 -ms.topic: reference -f1_keywords: ["C26446"] +f1_keywords: ["C26446", "USE_GSL_AT"] helpviewer_keywords: ["C26446"] --- -# C26446 USE_GSL_AT +# Warning C26446 -> `Prefer to use gsl::at() instead of unchecked subscript operator (bounds.4).` +> Prefer to use gsl::at() instead of unchecked subscript operator (bounds.4). -C++ Core Guidelines: [Bounds.4: Don't use standard-library functions and types that are not bounds-checked](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#probounds-bounds-safety-profile). +C++ Core Guidelines: [Bounds.4: Don't use standard-library functions and types that are not bounds-checked](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-bounds). ## Remarks @@ -21,11 +20,11 @@ This rule helps to find places where potentially unchecked access is performed v - Access to arrays of known size is flagged when a non-constant index is used in a subscript operator. Constant indices are handled by [C26483 STATIC_INDEX_OUT_OF_RANGE](c26483.md). - The logic to warn on overloaded `operator[]` calls is more complex: - If the index is non-integral, the call is ignored. This also handles indexing in standard maps, since parameters in such operators are passed by reference. - - If the operator is marked as non-throwing (by using **`noexcept`**, **`throw()`**, or **`__declspec(nothrow)`**), the call is flagged. We assume that if the subscript operator never throws exceptions, it either doesn’t perform range checks or these checks are obscure. + - If the operator is marked as non-throwing (by using **`noexcept`**, **`throw()`**, or **`__declspec(nothrow)`**), the call is flagged. We assume that if the subscript operator never throws exceptions, it either doesn't perform range checks or these checks are obscure. - If the operator isn't marked as non-throwing, it may be flagged if it comes from an STL container that also defines a conventional `at()` member function. Such functions are detected by simple name matching. - - The rule doesn’t warn on calls to standard `at()` functions. These functions are safe; replacing them with `gsl::at()` wouldn't bring much value. + - The rule doesn't warn on calls to standard `at()` functions. These functions are safe; replacing them with `gsl::at()` wouldn't bring much value. - Indexing into `std::basic_string_view<>` is unsafe, so a warning is issued. Replace the standard `string_view` by using `gsl::basic_string_span<>`, which is always bounds-checked. -- The implementation doesn’t consider range checks that user code may have somewhere in loops or branches. Accuracy here is traded for performance. In general, you can often replace explicit range checks by using more reliable iterators or more concise enhanced **`for`**-loops. +- The implementation doesn't consider range checks that user code may have somewhere in loops or branches. Here, accuracy is traded for performance. In general, you can often replace explicit range checks by using more reliable iterators or more concise enhanced **`for`**-loops. ## Example diff --git a/docs/code-quality/c26447.md b/docs/code-quality/c26447.md index 7595b29a59b..1835053be83 100644 --- a/docs/code-quality/c26447.md +++ b/docs/code-quality/c26447.md @@ -1,17 +1,16 @@ --- -title: C26447 +title: Warning C26447 description: "Microsoft C++ Code Analysis warning C26447 for the C++ Core Guidelines case F.6." ms.date: 08/25/2020 -ms.topic: reference -f1_keywords: ["C26447"] +f1_keywords: ["C26447", "DONT_THROW_IN_NOEXCEPT"] helpviewer_keywords: ["C26447"] --- -# C26447 DONT_THROW_IN_NOEXCEPT +# Warning C26447 > The function is declared `noexcept` but calls function *function_name* that may throw exceptions (f.6). C++ Core Guidelines:\ -[F.6: If your function may not throw, declare it noexcept](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-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#Rf-noexcept). ## Remarks @@ -19,7 +18,7 @@ This rule amends another rule, [C26440 DECLARE_NOEXCEPT](c26440.md), which tries - The Microsoft C++ compiler already handles straightforward violations like **`throw`** statements in the function body (see [C4297](../error-messages/compiler-warnings/compiler-warning-level-1-c4297.md)). - The rule focuses only on function calls. It flags targets that aren't **`constexpr`** and that can potentially throw exceptions. In other words, they aren't marked explicitly as non-throwing by using **`noexcept`**, **`__declspec(nothrow)`**, or **throw()**. -- The compiler-generated target functions are skipped to reduce noise since exception specifications are not always provided by the compiler. +- The compiler-generated target functions are skipped to reduce noise since exception specifications aren't always provided by the compiler. - The checker also skips special kinds of target functions we expect you to implement as **`noexcept`**; this rule is enforced by [C26439 SPECIAL_NOEXCEPT](c26439.md). ## Example diff --git a/docs/code-quality/c26448.md b/docs/code-quality/c26448.md index 7b75d262114..3da19b9eca0 100644 --- a/docs/code-quality/c26448.md +++ b/docs/code-quality/c26448.md @@ -1,29 +1,32 @@ --- -description: "Learn more about: C26448 USE_GSL_FINALLY" -title: C26448 +description: "Learn more about: Warning C26448 USE_GSL_FINALLY" +title: Warning C26448 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26448"] +f1_keywords: ["C26448", "USE_GSL_FINALLY"] helpviewer_keywords: ["C26448"] --- -# C26448 USE_GSL_FINALLY +# Warning C26448 -Consider using `gsl::finally` if final action is intended. +> Consider using `gsl::finally` if final action is intended (gsl.util) -C++ Core Guidelines: [GSL.util: Utilities](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-utilities) +C++ Core Guidelines: [GSL.util: Utilities](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-utilities) The Guidelines Support Library provides a convenient utility to implement the *final action* concept. Since the C++ language doesn't support **try-finally** constructs, it became common to implement custom cleanup types that would invoke arbitrary actions on destruction. The `gsl::finally` utility is implemented in this way and provides a more uniform way to perform final actions across a code base. -There are also cases where final actions are performed in an old-fashioned C-style way by using **`goto`** statements (which is generally discouraged by [C26438 NO_GOTO](c26438.md)). It is hard to detect the exact intention in code that heavily uses **`goto`**, but some heuristics can help to find better candidates for cleanup. +There are also cases where final actions are performed in an old-fashioned C-style way by using **`goto`** statements (which is discouraged by [C26438 NO_GOTO](c26438.md)). It's hard to detect the exact intention in code that heavily uses **`goto`**, but some heuristics can help to find better candidates for cleanup. ## Remarks -- This rule is very lightweight and uses label names to guess about opportunities to use final action objects. +- This rule is lightweight and uses label names to guess about opportunities to use final action objects. - Label names that can raise a warning contain words like "end", "final", "clean", and so on. -- Warnings appear at the **`goto`** statements. You may see verbose output on some occasions, but this may help in prioritizing code depending on its complexity. -- This rule always goes in pair with [C26438 NO_GOTO](c26438.md). Depending on the priorities, one of these can be disabled. +- Warnings appear at the **`goto`** statements. You may see verbose output on some occasions, but the output may help in prioritizing code, depending on its complexity. +- This rule always goes in pair with [C26438 NO_GOTO](c26438.md). Depending on the priorities, one of these rules can be disabled. -## Example: Cleanup with multiple goto statements +Code analysis name: `USE_GSL_FINALLY` + +## Example + +Cleanup with multiple goto statements: ```cpp void poll(connection_info info) @@ -48,7 +51,7 @@ end: } ``` -## Example: Cleanup with multiple goto statements replaced by gsl::finally +Cleanup with multiple goto statements replaced by `gsl::finally`: ```cpp void poll(connection_info info) diff --git a/docs/code-quality/c26449.md b/docs/code-quality/c26449.md index 002d926f475..594025669c1 100644 --- a/docs/code-quality/c26449.md +++ b/docs/code-quality/c26449.md @@ -1,38 +1,46 @@ --- -description: "Learn more about: C26449 NO_SPAN_FROM_TEMPORARY" -title: C26449 -ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26449"] +title: Warning C26449 +description: "Learn more about: Warning C26449 NO_SPAN_FROM_TEMPORARY." +ms.date: 05/11/2023 +f1_keywords: ["C26449", "NO_SPAN_FROM_TEMPORARY"] helpviewer_keywords: ["C26449"] --- -# C26449 NO_SPAN_FROM_TEMPORARY +# Warning C26449 -`gsl::span` or `std::string_view` created from a temporary will be invalid when the temporary is invalidated. +> `gsl::span` or `std::string_view` created from a temporary will be invalid when the temporary is invalidated (gsl.view) -C++ Core Guidelines: [GSL.view: Views](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslview-views). +C++ Core Guidelines: [GSL.view: Views](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-views). -Spans and views are convenient and lightweight types that allow to reference memory buffers. But they must be used carefully: while their interface looks similar to standard containers, their behavior is more like the behavior of pointers and references. They do not own data and must never be constructed from temporary buffers. This check focuses on cases where source data is temporary, while span or view is not. There is another check which handles slightly different scenario involving span references: [C26445 NO_SPAN_REF](c26445.md). Both rules can help to avoid subtle but dangerous mistakes made when legacy code gets modernized and adopts spans or views. +Spans and views are convenient and lightweight types that allow you to reference memory buffers. But they must be used carefully: while their interface looks similar to standard containers, their behavior is more like the behavior of pointers and references. They don't own data and must never be constructed from temporary buffers. This check focuses on cases where source data is temporary, while a span or view isn't. This rule can help to avoid subtle but dangerous mistakes made when legacy code gets modernized and adopts spans or views. There's another check that handles a slightly different scenario involving span references: [C26445 NO_SPAN_REF](c26445.md). + +Consider using [C26815](c26815.md) and [C26816](c26816.md). Those warnings are more general versions of this warning. ## Remarks -- This rule warns on places where constructors get invoked for spans or views and the source data buffer belongs to a temporary object created in the same statement. This includes: +- This rule warns on places where constructors get invoked for spans or views and the source data buffer belongs to a temporary object created in the same statement. This check includes: - implicit conversions in return statements; - implicit conversions in ternary operators; - explicit conversions in `static_cast` expressions; - function calls that return containers by value. -- Temporaries created for function call arguments are not flagged. It is safe to pass spans from such temporaries if target functions don’t retain data pointers in external variables. + +- Temporaries created for function call arguments aren't flagged. It's safe to pass spans from such temporaries if target functions don't retain data pointers in external variables. + - If spans or views are themselves temporaries, the rule skips them. + - Data tracking in the checker has certain limitations; therefore complex scenarios involving multiple or obscure reassignments may not be handled. -## Example: Subtle difference in result types +Code analysis name: `NO_SPAN_FROM_TEMPORARY` + +## Example + +Subtle difference in result types: ```cpp // Returns a predefined collection. Keeps data alive. gsl::span get_seed_sequence() noexcept; -// Returns a generated collection. Doesn’t own new data. -const std::vector get_next_sequence(gsl::span); +// Returns a generated collection. Doesn't own new data. +std::vector get_next_sequence(gsl::span); void run_batch() { @@ -44,3 +52,9 @@ void run_batch() } } ``` + +To fix the issue, make sure the view is created from an object that lives at least as long as the view itself. Sometimes a solution can be achieved by copying the data, other times some APIs need to be redesigned to share a reference to an object that lives long enough instead of returning a temporary copy. + +## See also +[C26815](c26815.md)\ +[C26816](c26816.md) \ No newline at end of file diff --git a/docs/code-quality/c26450.md b/docs/code-quality/c26450.md index 6a6b26bf5b3..2f4d1f351da 100644 --- a/docs/code-quality/c26450.md +++ b/docs/code-quality/c26450.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Arithmetic overflow: '%operator%' operation causes overflow at compile time. Use a wider type to store the operands" -title: C26450 -keywords: C26450 -ms.date: 01/08/2017 -ms.topic: "reference" -f1_keywords: ["C26450"] +title: Warning C26450 +description: "Describes the causes of MSVC code analysis warning C26450 and how to fix it." +ms.date: 05/11/2023 +f1_keywords: ["C26450", "RESULT_OF_ARITHMETIC_OPERATION_PROVABLY_LOSSY"] helpviewer_keywords: ["C26450"] -dev_langs: ["C++"] --- -# Arithmetic overflow: '%operator%' operation causes overflow at compile time. Use a wider type to store the operands +# Warning C26450 -This warning indicates that an arithmetic operation was provably lossy at compile time. This can be asserted when the operands are all compile-time constants. Currently, we check left shift, multiplication, addition, and subtraction operations for such overflows. +> Arithmetic overflow: '*operator*' operation causes overflow at compile time. Use a wider type to store the operands (io.1) -Note: C4307 is a similar check in the Microsoft C++ compiler. +## Remarks -## Example 1 +This warning indicates that an arithmetic operation was provably lossy at compile time. It can be asserted when the operands are all compile-time constants. Currently, we check left shift, multiplication, addition, and subtraction operations for such overflows. + +Warning [C4307](../error-messages/compiler-warnings/compiler-warning-level-2-c4307.md) is a similar check in the Microsoft C++ compiler. + +Code analysis name: `RESULT_OF_ARITHMETIC_OPERATION_PROVABLY_LOSSY` + +## Examples ```cpp int multiply() @@ -33,59 +36,15 @@ long long multiply() { const int a = INT_MAX; const int b = 2; - long long c = (long long)a * b; // OK - return c; -} -``` - -## Example 2 - -```cpp -int add() -{ - const int a = INT_MAX; - const int b = 2; - int c = a + b; // C26450 reported here - return c; -} -``` - -To correct this warning, use the following code: - -```cpp -long long add() -{ - const int a = INT_MAX; - const int b = 2; - long long c = (long long)a + b; // OK - return c; -} -``` - -## Example 3 - -```cpp -int subtract() -{ - const int a = -INT_MAX; - const int b = 2; - int c = a - b; // C26450 reported here - return c; -} -``` - -To correct this warning, use the following code. - -```cpp -long long subtract() -{ - const int a = -INT_MAX; - const int b = 2; - long long c = (long long)a - b; // OK + long long c = static_cast(a) * b; // OK return c; } ``` ## See also -[ES.103: Don't overflow](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-overflow) +[C26451](c26451.md)\ +[C26452](c26452.md)\ +[C26453](c26453.md)\ +[C26454](c26454.md)\ +[ES.103: Don't overflow](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-overflow) diff --git a/docs/code-quality/c26451.md b/docs/code-quality/c26451.md index f925524710a..3a2246a977b 100644 --- a/docs/code-quality/c26451.md +++ b/docs/code-quality/c26451.md @@ -1,15 +1,13 @@ --- -title: C26451 +title: Warning C26451 description: "Describes the causes of MSVC code analysis warning C26451, and shows how to fix it." -ms.date: 07/15/2020 -ms.topic: "reference" -f1_keywords: ["C26451"] +ms.date: 05/11/2023 +f1_keywords: ["C26451", "RESULT_OF_ARITHMETIC_OPERATION_CAST_TO_LARGER_SIZE"] helpviewer_keywords: ["C26451"] -dev_langs: ["C++"] --- # Warning C26451 -> Arithmetic overflow: Using operator '*operator*' on a *size-a* byte value and then casting the result to a *size-b* byte value. Cast the value to the wider type before calling operator '*operator*' to avoid overflow +> Arithmetic overflow: Using operator '*operator*' on a *size-a* byte value and then casting the result to a *size-b* byte value. Cast the value to the wider type before calling operator '*operator*' to avoid overflow (io.2) This warning indicates incorrect behavior that results from integral promotion rules and types larger than the ones in which arithmetic is typically performed. @@ -17,14 +15,16 @@ This warning indicates incorrect behavior that results from integral promotion r Code analysis detects when an integral value gets shifted left, multiplied, added, or subtracted, and the result gets cast to a wider integral type. If the operation overflows the narrower integral type, then data is lost. You can prevent this loss by casting the value to a wider type before the arithmetic operation. -## Example 1 +Code analysis name: `RESULT_OF_ARITHMETIC_OPERATION_CAST_TO_LARGER_SIZE` + +## Examples The following code generates this warning: ```cpp void leftshift(int i) noexcept { - unsigned __int64 x; + unsigned long long x; x = i << 31; // C26451 reported here // code @@ -36,55 +36,17 @@ To correct this warning, use the following code: ```cpp void leftshift(int i) noexcept { - unsigned __int64 x; - x = static_cast(i) << 31; // OK + unsigned long long x; + x = static_cast(i) << 31; // OK // code } ``` -## Example 2 - -```cpp -void somefunc(__int64 /* y */) noexcept -{} - -void callsomefunc(int x) noexcept -{ - somefunc(x * 2); // C26451 reported here -} -``` - -To correct this warning, use the following code: - -```cpp -void callsomefunc(int x) noexcept -{ - somefunc(static_cast<__int64>(x) * 2); // OK -} -``` - -## Example 3 - -```cpp -__int64 add(int x) noexcept -{ - constexpr auto value = 2; - return x += value; // C26451 reported here -} -``` - -To correct this warning, use the following code: - -```cpp -__int64 add(int x) noexcept -{ - constexpr auto value = 2; - const __int64 y = static_cast<__int64>(x) + value; // OK - return y; -} -``` - ## See also -- [ES.103: Don't overflow](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-overflow) +[C26450](c26450.md)\ +[C26452](c26452.md)\ +[C26453](c26453.md)\ +[C26454](c26454.md)\ +[ES.103: Don't overflow](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-overflow) diff --git a/docs/code-quality/c26452.md b/docs/code-quality/c26452.md index bccb98e2031..14a7f7d7279 100644 --- a/docs/code-quality/c26452.md +++ b/docs/code-quality/c26452.md @@ -1,23 +1,26 @@ --- -title: C26452 +title: Warning C26452 description: "Describes causes of MSVC Code analysis warning C26452, and how to fix the issue." ms.date: 07/15/2020 -ms.topic: "reference" -f1_keywords: ["C26452"] +f1_keywords: ["C26452", "SHIFT_COUNT_NEGATIVE_OR_TOO_BIG"] helpviewer_keywords: ["C26452"] -dev_langs: ["C++"] --- # Warning C26452 -> Arithmetic overflow: Left shift count is negative or greater than or equal to the operand size, which is undefined behavior +> Arithmetic overflow: Left shift count is negative or greater than or equal to the operand size, which is undefined behavior (io.3) + +## Remarks This warning indicates the shift count is negative, or greater than or equal to the number of bits in the shifted operand. Either case results in undefined behavior. -C4293 is a similar check in the Microsoft C++ compiler. + +Warning [C4293](../error-messages/compiler-warnings/compiler-warning-level-1-c4293.md) is a similar check in the Microsoft C++ compiler. + +Code analysis name: `SHIFT_COUNT_NEGATIVE_OR_TOO_BIG` ## Example ```cpp -unsigned __int64 combine(unsigned lo, unsigned hi) +unsigned long long combine(unsigned lo, unsigned hi) { return (hi << 32) | lo; // C26252 here } @@ -26,7 +29,7 @@ unsigned __int64 combine(unsigned lo, unsigned hi) To correct this warning, use the following code: ```cpp -unsigned __int64 combine(unsigned lo, unsigned hi) +unsigned long long combine(unsigned lo, unsigned hi) { return (static_cast(hi) << 32) | lo; // OK } @@ -34,4 +37,9 @@ unsigned __int64 combine(unsigned lo, unsigned hi) ## See also -[ES.102: Use signed types for arithmetic](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-unsigned) +[C26450](c26450.md)\ +[C26451](c26451.md)\ +[C26453](c26453.md)\ +[C26454](c26454.md)\ +[ES.101: Use unsigned types for bit manipulation](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-unsigned)\ +[ES.102: Use signed types for arithmetic](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-signed) diff --git a/docs/code-quality/c26453.md b/docs/code-quality/c26453.md index ee2388594f2..f7a44f29ab0 100644 --- a/docs/code-quality/c26453.md +++ b/docs/code-quality/c26453.md @@ -1,17 +1,19 @@ --- -title: C26453 +title: Warning C26453 description: "Describes the causes of MSVC code analysis warning C26453, and shows how to fix it." -ms.date: 07/15/2020 -ms.topic: "reference" -f1_keywords: ["C26453"] +ms.date: 05/11/2023 +f1_keywords: ["C26453", "LEFTSHIFT_NEGATIVE_SIGNED_NUMBER"] helpviewer_keywords: ["C26453"] -dev_langs: ["C++"] --- # Warning C26453 -> Arithmetic overflow: Left shift of a negative signed number is undefined behavior +> Arithmetic overflow: Left shift of a negative signed number is undefined behavior (io.4) -This warning indicates the code left shifts a negative signed integral value, which is non-portable and triggers implementation defined behavior. +## Remarks + +This warning indicates the code left shifts a negative signed integral value, which is nonportable and triggers implementation defined behavior. + +Code analysis name: `LEFTSHIFT_NEGATIVE_SIGNED_NUMBER` ## Example @@ -29,7 +31,7 @@ To correct this warning, use the following code: ```cpp void leftshift(int shiftCount) { - const auto result = static_cast(-1) << shiftCount; // OK + const auto result = ~0u << shiftCount; // OK // code } @@ -37,4 +39,9 @@ void leftshift(int shiftCount) ## See also -[ES.102: Use signed types for arithmetic](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-unsigned) +[C26450](c26450.md)\ +[C26451](c26451.md)\ +[C26452](c26452.md)\ +[C26454](c26454.md)\ +[ES.101: Use unsigned types for bit manipulation](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-unsigned)\ +[ES.102: Use signed types for arithmetic](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-signed) diff --git a/docs/code-quality/c26454.md b/docs/code-quality/c26454.md index 433e8319236..59e6c58c517 100644 --- a/docs/code-quality/c26454.md +++ b/docs/code-quality/c26454.md @@ -1,16 +1,19 @@ --- -description: "Learn more about: Arithmetic overflow: '%operator%' operation produces a negative unsigned result at compile time" -title: C26454 -keywords: C26454 +title: Warning C26454 +description: "Learn more about: Arithmetic overflow: 'operator' operation produces a negative unsigned result at compile time" ms.date: 01/08/2017 -ms.topic: "reference" -f1_keywords: ["C26454"] +f1_keywords: ["C26454", "RESULT_OF_ARITHMETIC_OPERATION_NEGATIVE_UNSIGNED"] helpviewer_keywords: ["C26454"] -dev_langs: ["C++"] --- -# Arithmetic overflow: '%operator%' operation produces a negative unsigned result at compile time +# Warning C26454 - This warning indicates that the subtraction operation produces a negative result which was evaluated in an unsigned context. This can result in unintended overflows. +> Arithmetic overflow: '*operator*' operation produces a negative unsigned result at compile time + +## Remarks + +This warning indicates that the subtraction operation produces a negative result that was evaluated in an unsigned context, which can result in unintended overflows. + +Code analysis name: `RESULT_OF_ARITHMETIC_OPERATION_NEGATIVE_UNSIGNED` ## Example @@ -34,4 +37,8 @@ unsigned int negativeunsigned() ## See also -[ES.106: Don't try to avoid negative values by using unsigned](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-nonnegative) +[C26450](c26450.md)\ +[C26451](c26451.md)\ +[C26452](c26452.md)\ +[C26453](c26453.md)\ +[ES.106: Don't try to avoid negative values by using `unsigned`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-nonnegative) diff --git a/docs/code-quality/c26455.md b/docs/code-quality/c26455.md index 208cf4d588c..756871cae8f 100644 --- a/docs/code-quality/c26455.md +++ b/docs/code-quality/c26455.md @@ -1,23 +1,26 @@ --- -description: "Learn more about the C26455 DEFAULT_CTOR_NOEXCEPT C++ Core Guidelines Checker warning. Default constructors shouldn't do anything that can throw." -title: C26455 DEFAULT_CTOR_NOEXCEPT +title: Warning C26455 +description: "Learn more about the C26455 DEFAULT_CTOR_NOEXCEPT" ms.date: 04/29/2022 -ms.topic: reference -f1_keywords: ["C26455"] +f1_keywords: ["C26455", "DEFAULT_CTOR_NOEXCEPT"] helpviewer_keywords: ["C26455"] -ms.assetid: 27e86063-d969-49d8-8912-dcc2dc57249f author: kylereedmsft ms.author: kylereed ms.custom: kr2b-contr-experiment --- -# C26455 DEFAULT_CTOR_NOEXCEPT +# Warning C26455 -The C++ Core Guidelines suggest that default constructors shouldn't do anything that can throw. If the default constructor is allowed to throw, operations such as move and swap will also throw which is undesirable because move and swap should always succeed. Parameterized constructors may throw. +> Default constructor should not throw. Declare it '`noexcept`' (f.6) + +The C++ Core Guidelines suggest that default constructors shouldn't do anything that can throw. When the default constructor can throw, all code that relies on a properly instantiated object may also throw. ## Remarks Consider the default constructors of the STL types, like `std::vector`. In these implementations, the default constructors initialize internal state without making allocations. In the `std::vector` case, the size is set to 0 and the internal pointer is set to `nullptr`. The same pattern should be followed for all default constructors. +Code analysis name: `DEFAULT_CTOR_NOEXCEPT` + ## See also -- [C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rf-noexcept) +[C26439](./c26439.md)\ +[F.6: If your function must not throw, declare it `noexcept`](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-noexceptt) diff --git a/docs/code-quality/c26456.md b/docs/code-quality/c26456.md index 8c6fc0b3278..74456141ad6 100644 --- a/docs/code-quality/c26456.md +++ b/docs/code-quality/c26456.md @@ -1,17 +1,24 @@ --- description: "Learn more about the C26456 DONT_HIDE_OPERATORS C++ Core Guidelines Checker warning. Hiding base methods is error prone and makes code harder to read." -title: C26456 DONT_HIDE_OPERATORS +title: Warning C26456 ms.date: 04/29/2022 -ms.topic: reference -f1_keywords: ["C26456"] +f1_keywords: ["C26456", "DONT_HIDE_OPERATORS"] helpviewer_keywords: ["C26456"] ms.assetid: 3a3ad636-0938-40b5-93ce-169322e2ff23 author: kylereedmsft ms.author: kylereed ms.custom: kr2b-contr-experiment --- -# C26456 DONT_HIDE_OPERATORS +# Warning C26456 + +> Operator '*symbol_1*' hides a non-virtual operator '*symbol_2*' (c.128) + +## Remarks Hiding base methods that aren't virtual is error prone and makes code harder to read. -[C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c128-virtual-functions-should-specify-exactly-one-of-virtual-override-or-final) +Code analysis name: `DONT_HIDE_OPERATORS` + +## See also + +[C++ Core Guideline c.128](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override) diff --git a/docs/code-quality/c26457.md b/docs/code-quality/c26457.md index f7fab2b4c20..17430f18309 100644 --- a/docs/code-quality/c26457.md +++ b/docs/code-quality/c26457.md @@ -1,17 +1,27 @@ --- -description: "Learn more about: C26457 USE_STD_IGNORE_INSTEAD_OF_VOID_CAST" -title: C26457 +description: "Learn more about: Warning C26457 USE_STD_IGNORE_INSTEAD_OF_VOID_CAST" +title: Warning C26457 ms.date: 3/1/2021 -f1_keywords: ["C26457"] +f1_keywords: ["C26457", "USE_STD_IGNORE_INSTEAD_OF_VOID_CAST"] helpviewer_keywords: ["C26457"] --- -# C26457 USE_STD_IGNORE_INSTEAD_OF_VOID_CAST +# Warning C26457 -Excerpt from the [C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es48-avoid-casts): +> `(void)` should not be used to ignore return values, use '`std::ignore =`' instead (es.48) + +## Remarks + +Excerpt from the [C++ Core Guideline ES.48](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts): > Never cast to `(void)` to ignore a `[[nodiscard]]` return value. If you deliberately want to discard such a result, first think hard about whether that is really a good idea (there is usually a good reason the author of the function or of the return type used `[[nodiscard]]` in the first place). If you still think it's appropriate and your code reviewer agrees, use `std::ignore =` to turn off the warning which is simple, portable, and easy to grep. -```C++ +Code analysis name: `USE_STD_IGNORE_INSTEAD_OF_VOID_CAST` + +## Example + +Use `std::ignore` instead of cast to `void`: + +```cpp struct S{}; [[nodiscard]] S getS(); diff --git a/docs/code-quality/c26459.md b/docs/code-quality/c26459.md new file mode 100644 index 00000000000..0bd58559214 --- /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 da0cb686dbe..008786d1a01 100644 --- a/docs/code-quality/c26460.md +++ b/docs/code-quality/c26460.md @@ -1,20 +1,19 @@ --- -title: C26460 +title: Warning C26460 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26460"] +f1_keywords: ["C26460", "USE_CONST_REFERENCE_ARGUMENTS"] helpviewer_keywords: ["C26460"] description: CppCoreCheck rule that enforces C++ Core Guidelines Con.3 --- -# C26460 USE_CONST_REFERENCE_ARGUMENTS +# Warning C26460 -The reference argument '%argument%' for function '%function%' can be marked as `const` (con.3). +> The reference argument '*argument*' for function '*function*' can be marked as `const` (con.3). -Passing an object by reference indicates that the function has the potential modify the object. If that is not the intent of the function, it is better to mark the argument as a const reference. +## Remarks -## See also +Passing an object by reference indicates that the function has the potential modify the object. If that isn't the intent of the function, it's better to mark the argument as a const reference. -[C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). +Code analysis name: `USE_CONST_REFERENCE_ARGUMENTS` ## Example @@ -25,7 +24,6 @@ struct MyStruct void MemberFn2(); }; - void Function1_Helper(const MyStruct&); void Function1(MyStruct& myStruct) // C26460, see comments below. { @@ -38,3 +36,7 @@ void Function2(MyStruct& myStruct) myStruct.MemberFn2(); // MemberFn2 is non-const and has the potential to modify data } ``` + +## See also + +[C++ Core Guidelines con.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-ref). diff --git a/docs/code-quality/c26461.md b/docs/code-quality/c26461.md index 72d51e3ec87..eb18934fd4d 100644 --- a/docs/code-quality/c26461.md +++ b/docs/code-quality/c26461.md @@ -1,20 +1,19 @@ --- -title: C26461 +title: Warning C26461 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26461"] +f1_keywords: ["C26461", "USE_CONST_POINTER_ARGUMENTS"] helpviewer_keywords: ["C26461"] description: CppCoreCheck rule that enforces C++ Core Guidelines con.3 --- -# C26461 USE_CONST_POINTER_ARGUMENTS: +# Warning C26461 -The pointer argument '%argument%' for function '%function%' can be marked as a pointer to `const` (con.3). +> The pointer argument '*argument*' for function '*function*' can be marked as a pointer to `const` (con.3). -A function with a `T*` argument has the potential to modify the value of the object. If that is not the intent of the function, it is better to make the pointer a `const T*` instead. +## Remarks -## See also +A function with a `T*` argument has the potential to modify the value of the object. If that isn't the intent of the function, it's better to make the pointer a `const T*` instead. -[C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). +Code analysis name: `USE_CONST_POINTER_ARGUMENTS` ## Example @@ -43,3 +42,7 @@ void Function2(MyStruct* myStruct) myStruct->MemberFn2(); // The member function is non-const, so no C26461 will be issued } ``` + +## See also + +[C++ Core Guidelines con.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-ref). diff --git a/docs/code-quality/c26462.md b/docs/code-quality/c26462.md index 1530cbb8265..8f9adfd83d4 100644 --- a/docs/code-quality/c26462.md +++ b/docs/code-quality/c26462.md @@ -1,20 +1,19 @@ --- -title: C26462 +title: Warning C26462 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26462"] +f1_keywords: ["C26462", "USE_CONST_POINTER_FOR_VARIABLE"] helpviewer_keywords: ["C26462"] description: CppCoreCheck rule C26462 that enforces C++ Core Guidelines Con.4 --- -# C26462 USE_CONST_POINTER_FOR_VARIABLE +# Warning C26462 -The value pointed to by '%variable%' is assigned only once, mark it as a pointer to `const` (con.4). +> The value pointed to by '*variable*' is assigned only once, mark it as a pointer to `const` (con.4). -Pointers to variables whose values remain unchanged should be marked as `const`. +## Remarks -## See also +Pointers to variables whose values remain unchanged should be marked as `const`. -[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +Code analysis name: `USE_CONST_POINTER_FOR_VARIABLE` ## Example @@ -29,3 +28,7 @@ void function1(int* ptr) useVal(*p); } ``` + +## See also + +[C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). diff --git a/docs/code-quality/c26463.md b/docs/code-quality/c26463.md index 55459cb3396..1da69c4f32e 100644 --- a/docs/code-quality/c26463.md +++ b/docs/code-quality/c26463.md @@ -1,19 +1,20 @@ --- -title: C26463 +title: Warning C26463 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26463"] +f1_keywords: ["C26463", "USE_CONST_FOR_ELEMENTS"] helpviewer_keywords: ["C26463"] description: CppCoreCheck placeholder warning C26463 for future con.4 enforcement --- -# C26463 USE_CONST_FOR_ELEMENTS +# Warning C26463 -The elements of array '%array%' are assigned only once, mark elements `const` (con.4) +> The elements of array '%array%' are assigned only once, mark elements `const` (con.4) -## See also +## Remarks -[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +- This rule is currently not implemented in CppCoreCheck. -## Remark +Code analysis name: `USE_CONST_FOR_ELEMENTS` -- This rule is currently not implemented in CppCoreCheck. +## See also + +[C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). diff --git a/docs/code-quality/c26464.md b/docs/code-quality/c26464.md index a280783c5dd..aa5d02d1284 100644 --- a/docs/code-quality/c26464.md +++ b/docs/code-quality/c26464.md @@ -1,19 +1,20 @@ --- -title: C26464 +title: Warning C26464 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26464"] +f1_keywords: ["C26464", "USE_CONST_POINTER_FOR_ELEMENTS"] helpviewer_keywords: ["C26464"] description: CppCoreCheck placeholder warning C26464 for future con.4 enforcement --- -# C26464 USE_CONST_POINTER_FOR_ELEMENTS +# Warning C26464 -The values pointed to by elements of array '%array%' are assigned only once, mark elements as pointer to `const` (con.4). - -## See also - -[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +> The values pointed to by elements of array '*array*' are assigned only once, mark elements as pointer to `const` (con.4). ## Remarks - This rule is currently not implemented in CppCoreCheck. + +Code analysis name: `USE_CONST_POINTER_FOR_ELEMENTS` + +## See also + +[C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). diff --git a/docs/code-quality/c26465.md b/docs/code-quality/c26465.md index 7b0a27fb45e..1ca3fee5d14 100644 --- a/docs/code-quality/c26465.md +++ b/docs/code-quality/c26465.md @@ -1,18 +1,17 @@ --- -title: C26465 +title: Warning C26465 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26465"] +f1_keywords: ["C26465", "NO_CONST_CAST_UNNECESSARY"] helpviewer_keywords: ["C26465"] description: CppCoreCheck rule C26465 that enforces C++ Core Guidelines Type.3 --- -# C26465 NO_CONST_CAST_UNNECESSARY +# Warning C26465 -Don't use `const_cast` to cast away `const`. `const_cast` is not required; constness or volatility is not being removed by this conversion. +> Don't use `const_cast` to cast away `const`. `const_cast` is not required; constness or volatility is not being removed by this conversion. ## See also -[C++ Core Guidelines Type.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-constcast) +[C++ Core Guidelines Type.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-constcast) ## Example diff --git a/docs/code-quality/c26466.md b/docs/code-quality/c26466.md index a6d419fe938..786d95159bc 100644 --- a/docs/code-quality/c26466.md +++ b/docs/code-quality/c26466.md @@ -1,18 +1,17 @@ --- -title: C26466 +title: Warning C26466 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26466"] +f1_keywords: ["C26466", "NO_STATIC_DOWNCAST_POLYMORPHIC"] helpviewer_keywords: ["C26466"] description: CppCoreCheck rule that enforces C++ Core Guidelines Type.2 --- -# C26466 NO_STATIC_DOWNCAST_POLYMORPHIC +# Warning C26466 -Don't use `static_cast` downcasts. A cast from a polymorphic type should use dynamic_cast. +> Don't use `static_cast` downcasts. A cast from a polymorphic type should use dynamic_cast. ## See also -[C++ Core Guidelines Type.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-downcast) +[C++ Core Guidelines Type.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-downcast) ## Example diff --git a/docs/code-quality/c26471.md b/docs/code-quality/c26471.md index deaa79b91c8..f44d8335af7 100644 --- a/docs/code-quality/c26471.md +++ b/docs/code-quality/c26471.md @@ -1,18 +1,17 @@ --- -title: C26471 +title: Warning C26471 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26471"] +f1_keywords: ["C26471", "NO_REINTERPRET_CAST_FROM_VOID_PTR"] helpviewer_keywords: ["C26471"] description: CppCoreCheck rule C26471 that enforces C++ Core Guidelines Type.1 --- -# C26471 NO_REINTERPRET_CAST_FROM_VOID_PTR +# Warning C26471 -Don't use `reinterpret_cast`. A cast from void* can use `static_cast`. +> Don't use `reinterpret_cast`. A cast from `void*` can use `static_cast` (type.1) -## See also +## Remarks -[C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast) +Code analysis name: `NO_REINTERPRET_CAST_FROM_VOID_PTR` ## Example @@ -27,3 +26,7 @@ void function(void* pValue) } } ``` + +## See also + +[C++ Core Guidelines Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-reinterpretcast) diff --git a/docs/code-quality/c26472.md b/docs/code-quality/c26472.md index 2b64d60e6bf..67a2f80fd15 100644 --- a/docs/code-quality/c26472.md +++ b/docs/code-quality/c26472.md @@ -1,31 +1,32 @@ --- -description: "Learn more about: C26472 NO_CASTS_FOR_ARITHMETIC_CONVERSION" -title: C26472 +description: "Learn more about: Warning C26472 NO_CASTS_FOR_ARITHMETIC_CONVERSION" +title: Warning C26472 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26472"] +f1_keywords: ["C26472", "NO_CASTS_FOR_ARITHMETIC_CONVERSION"] helpviewer_keywords: ["C26472"] ms.assetid: 51e215a7-0e0a-4e6c-bff1-805bf5b1af29 --- -# C26472 NO_CASTS_FOR_ARITHMETIC_CONVERSION +# Warning C26472 -"Don't use a static_cast for arithmetic conversions. Use brace initialization, gsl::narrow_cast, or gsl::narrow." +> Don't use a static_cast for arithmetic conversions. Use brace initialization, `gsl::narrow_cast`, or `gsl::narrow`. **C++ Core Guidelines**: -[Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile): Avoid casts +[Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-arithmeticcast): Avoid casts -This rule helps to find places where static casts are used to convert between integral types. These casts are unsafe because the compiler would not warn if any data loss occurs. Brace initializers are better for the cases where constants are used, and a compiler error is desired. There are also utilities from the Guidelines Support Library that help to describe intentions clearly: +This rule helps to find places where static casts are used to convert between integral types. These casts are unsafe because the compiler wouldn't warn if any data loss occurs. Brace initializers are better for the cases where constants are used, and a compiler error is desired. There are also utilities from the Guidelines Support Library that help to describe intentions clearly: -- gsl::narrow ensures lossless conversion and causes run-time crash if it is not possible. -- gsl::narrow_cast clearly states that conversion can lose data and it is acceptable. +- `gsl::narrow` ensures lossless conversion and throws `gsl::narrowing_error` if it's not possible. +- `gsl::narrow_cast` clearly states that conversion can lose data and it's acceptable. ## Remarks -- This rule is implemented only for static_casts. Using of C-style casts is generally discouraged. +- This rule is implemented only for static casts. Using of C-style casts is discouraged. + +Code analysis name: `NO_CASTS_FOR_ARITHMETIC_CONVERSION` ## Example -unhandled unexpected data +Unhandled unexpected data: ```cpp rgb from_24bit(std::uint32_t v) noexcept { @@ -37,7 +38,7 @@ rgb from_24bit(std::uint32_t v) noexcept { } ``` -unhandled unexpected data – safer version +Unhandled unexpected data, safer version: ```cpp rgb from_24bit(std::uint32_t v) noexcept { diff --git a/docs/code-quality/c26473.md b/docs/code-quality/c26473.md index 2e61b7b4ef4..410129d326e 100644 --- a/docs/code-quality/c26473.md +++ b/docs/code-quality/c26473.md @@ -1,25 +1,23 @@ --- -description: "Learn more about: C26473 NO_IDENTITY_CAST" -title: C26473 +description: "Learn more about: Warning C26473 NO_IDENTITY_CAST" +title: Warning C26473 ms.date: 11/15/2017 -ms.topic: "conceptual" -f1_keywords: ["C26473"] +f1_keywords: ["C26473", "NO_IDENTITY_CAST"] helpviewer_keywords: ["C26473"] ms.assetid: d88aaa57-0003-421f-8377-4e6a5c27f2df - --- -# C26473 NO_IDENTITY_CAST +# Warning C26473 -"Don't cast between pointer types where the source type and the target type are the same." +> Don't cast between pointer types where the source type and the target type are the same. **C++ Core Guidelines**: -[Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile): Avoid casts +[Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-identitycast): Avoid casts -This rule helps to remove unnecessary or suspicious casts. Obviously, when type is converted to itself, such conversion is ineffective, yet the fact that the cast is used may indicate subtle design issue or a potential for regression if types change in future. It is always safer to use as few casts as possible. +This rule helps to remove unnecessary or suspicious casts. Obviously, when a type is converted to itself, such a conversion is ineffective. Yet the fact that the cast is used may indicate a subtle design issue or a potential for regression if types change in future. It's always safer to use as few casts as possible. ## Remarks -- This rule is implemented for static and reinterpret casts and checks only pointer types. +- This rule is implemented for static casts and reinterpret casts, and checks only pointer types. ## Example diff --git a/docs/code-quality/c26474.md b/docs/code-quality/c26474.md index fe113b6b282..fd62d069f68 100644 --- a/docs/code-quality/c26474.md +++ b/docs/code-quality/c26474.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C26474 NO_IMPLICIT_CAST" -title: C26474 +description: "Learn more about: Warning C26474 NO_IMPLICIT_CAST" +title: Warning C26474 ms.date: 08/11/2020 -ms.topic: "conceptual" -f1_keywords: ["C26474"] +f1_keywords: ["C26474", "NO_IMPLICIT_CAST"] helpviewer_keywords: ["C26474"] ms.assetid: 1e23a8e6-97fa-47f5-a279-b52aa2efafa4 --- -# C26474 NO_IMPLICIT_CAST +# Warning C26474 -"Don't cast between pointer types when the conversion could be implicit." +> Don't cast between pointer types when the conversion could be implicit. **C++ Core Guidelines**:\ -[Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile): Avoid casts +[Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-implicitpointercast): Avoid casts In some cases, implicit casts between pointer types are safe and don't require you to write a specific cast expression. This rule finds instances of unnecessary casts you can safely remove. diff --git a/docs/code-quality/c26475.md b/docs/code-quality/c26475.md index 5307db2b373..b44baae8a8e 100644 --- a/docs/code-quality/c26475.md +++ b/docs/code-quality/c26475.md @@ -1,22 +1,21 @@ --- -description: "Learn more about: C26475 NO_FUNCTION_STYLE_CASTS" -title: C26475 +description: "Learn more about: Warning C26475 NO_FUNCTION_STYLE_CASTS" +title: Warning C26475 ms.date: 06/29/2022 -ms.topic: "conceptual" -f1_keywords: ["C26475"] +f1_keywords: ["C26475", "NO_FUNCTION_STYLE_CASTS"] helpviewer_keywords: ["C26475"] ms.assetid: 4ed71cf8-f155-4961-b4fe-77feb3b880c3 --- -# C26475 NO_FUNCTION_STYLE_CASTS +# Warning C26475 -"Do not use function style C-casts." +> Do not use function style C-casts. **C++ Core Guidelines**: -[ES.49](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es49-if-you-must-use-a-cast-use-a-named-cast): If you must use a cast, use a named cast +[ES.49](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts-named): If you must use a cast, use a named cast Function-style casts (for example, `int(1.1)`) are another form of C-style casts (like `(int)1.1`), which have questionable safety. Specifically, the compiler doesn't try to check if any data loss can occur either in C-casts or in function casts. In both cases, it's better either to avoid casting or to use a braced initializer if possible. If neither works, static casts may be suitable, but it's still better to use utilities from the Guidelines Support Library: -- `gsl::narrow` ensures lossless conversion and causes run-time crash if it's not possible. +- `gsl::narrow` ensures lossless conversion and throws `gsl::narrowing_error` if it's not possible. - `gsl::narrow_cast` clearly states that conversion can lose data and it's acceptable. ## Remarks diff --git a/docs/code-quality/c26476.md b/docs/code-quality/c26476.md index 7d8c96fadd9..b07cb80eeab 100644 --- a/docs/code-quality/c26476.md +++ b/docs/code-quality/c26476.md @@ -1,18 +1,24 @@ --- description: "Learn more about the C26476 USE_VARIANT C++ Core Guidelines Checker warning. Use a type-safe alternative to union, which is preferred in modern code." -title: C26476 USE_VARIANT +title: Warning C26476 ms.date: 04/29/2022 -ms.topic: reference -f1_keywords: ["C26476"] +f1_keywords: ["C26476", "USE_VARIANT"] helpviewer_keywords: ["C26476"] ms.assetid: bb2b3b26-9a84-4d81-8bae-ad9a5577c8a6 author: kylereedmsft ms.author: kylereed ms.custom: kr2b-contr-experiment --- +# Warning C26476 -# C26476 USE_VARIANT +> Expression/symbol '*name*' uses a naked union '*union*' with multiple type pointers: Use variant instead (type.7) + +## Remarks `std::variant` provides a type-safe alternative to `union` and should be preferred in modern code. -[C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ru-naked) +Code analysis name: `USE_VARIANT` + +## See also + +[C++ Core Guideline C.181](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ru-naked) diff --git a/docs/code-quality/c26477.md b/docs/code-quality/c26477.md index 0c60d575621..7da0611abfa 100644 --- a/docs/code-quality/c26477.md +++ b/docs/code-quality/c26477.md @@ -1,17 +1,24 @@ --- description: "Learn more about the C26477 USE_NULLPTR_NOT_CONSTANT C++ Core Guidelines Checker warning. The nullptr value allows overloads with special null handling." -title: C26477 USE_NULLPTR_NOT_CONSTANT +title: Warning C26477 ms.date: 04/29/2022 -ms.topic: reference -f1_keywords: ["C26477"] +f1_keywords: ["C26477", "USE_NULLPTR_NOT_CONSTANT"] helpviewer_keywords: ["C26477"] ms.assetid: d5395efc-5eb2-4e82-9b45-fcd5ff4577bf author: kylereedmsft ms.author: kylereed ms.custom: kr2b-contr-experiment --- -# C26477 USE_NULLPTR_NOT_CONSTANT +# Warning C26477 + +> Use '`nullptr`' rather than 0 or NULL (es.47) + +## Remarks `nullptr` has a special type `nullptr_t` that allows overloads with special null handling. Using `0` or `NULL` in place of `nullptr` bypasses the type safety and deduction that `nullptr` provides. -[C++ Core Guideline for this warning](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-nullptr) +Code analysis name: `USE_NULLPTR_NOT_CONSTANT` + +## See also + +[C++ Core Guideline ES.47](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-nullptr) diff --git a/docs/code-quality/c26478.md b/docs/code-quality/c26478.md index 68a0e6d53d3..47dc1d62bf3 100644 --- a/docs/code-quality/c26478.md +++ b/docs/code-quality/c26478.md @@ -1,20 +1,23 @@ --- +title: Warning C26478 description: "Learn more about: Warning C26478: Don't use std::move on constant variables. (es.56)" -title: c26478 -keywords: c26478 -ms.date: 07/15/2019 -ms.topic: reference -f1_keywords: ["C26478"] +ms.date: 10/12/2023 +f1_keywords: ["C26478", "NO_MOVE_OP_ON_CONST"] helpviewer_keywords: ["C26478"] -dev_langs: ["C++"] --- -# Warning C26478: Don't use std::move on constant variables. (es.56) +# Warning C26478 -This warning is to indicate that the use of std::move not consistent with how std::move is intended to be used. +> Don't use `std::move` on constant variables. (es.56) -When called on a const object, std::move returns a copy of the object, which is likely not the developer's intent. +## Remarks -## Example 1 +This warning is to indicate that the use of `std::move` not consistent with how `std::move` is intended to be used. + +Because `const` objects can't be moved, calling `std::move` on them has no effect. This pattern can result in unintended copies. + +Code analysis name: `NO_MOVE_OP_ON_CONST` + +## Example ```cpp struct node @@ -30,23 +33,8 @@ void foo(const node& n) } ``` -An assignment operator or using the passed in parameter will prevent this warning from being issued and will adequately serve the developer's use case. - -## Example 2 - -```cpp -struct s; - -template -void bar(T t){}; - -void foo() -{ - const s s1; - bar(std::move(s1)); // C26478 reported here -} -``` +To fix the issue, remove the redundant `std::move`. ## See also -[ES.56 - Write std::move() only when you need to explicitly move an object to another scope](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es56-write-stdmove-only-when-you-need-to-explicitly-move-an-object-to-another-scope) +[ES.56: Write `std::move()` only when you need to explicitly move an object to another scope](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-move) diff --git a/docs/code-quality/c26479.md b/docs/code-quality/c26479.md new file mode 100644 index 00000000000..130adb11af8 --- /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#Rf-return-move-local)\ +[ES.56: Write `std::move()` only when you need to explicitly move an object to another scope](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-move) diff --git a/docs/code-quality/c26481.md b/docs/code-quality/c26481.md index c0003e1eb84..31249a98f10 100644 --- a/docs/code-quality/c26481.md +++ b/docs/code-quality/c26481.md @@ -1,23 +1,22 @@ --- -description: "Learn more about: C26481 NO_POINTER_ARITHMETIC" -title: C26481 +description: "Learn more about: Warning C26481 NO_POINTER_ARITHMETIC" +title: Warning C26481 ms.date: 04/29/2020 -ms.topic: "conceptual" -f1_keywords: ["C26481"] +f1_keywords: ["C26481", "NO_POINTER_ARITHMETIC"] helpviewer_keywords: ["C26481"] ms.assetid: 4fd8694d-b45b-4163-b2d5-88c4889d00ed --- -# C26481 NO_POINTER_ARITHMETIC +# Warning C26481 -> warning C26481: Don't use pointer arithmetic. Use span instead (bounds.1). +> Don't use pointer arithmetic. Use span instead (bounds.1). ## Remarks -This check supports the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) rule [I.13](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-array): *Do not pass an array as a single pointer*. Whenever raw pointers are used in arithmetic operations they should be replaced with safer kinds of buffers, such as `span` or `vector`. +This check supports the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) rule [I.13](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-array): *Do not pass an array as a single pointer*. Whenever raw pointers are used in arithmetic operations they should be replaced with safer kinds of buffers, such as `span` or `vector`. -This check is more restrictive than I.13: it doesn’t skip `zstring` or `czstring` types. +This check is more restrictive than I.13: it doesn't skip `zstring` or `czstring` types. -C26481 and [C26485](c26485.md) come from the [Bounds Safety Profile](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) rules. These rules were implemented in the first release of the C++ Core Guidelines Checker. They're applicable to the raw pointers category since they help to avoid unsafe use of raw pointers. +C26481 and [C26485](c26485.md) come from the [Bounds Safety Profile](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-bounds) rules. These rules were implemented in the first release of the C++ Core Guidelines Checker. They're applicable to the raw pointers category since they help to avoid unsafe use of raw pointers. ## Example diff --git a/docs/code-quality/c26482.md b/docs/code-quality/c26482.md index 36e607c406e..9fafb3b9124 100644 --- a/docs/code-quality/c26482.md +++ b/docs/code-quality/c26482.md @@ -1,18 +1,17 @@ --- -title: C26482 +title: Warning C26482 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26482"] +f1_keywords: ["C26482", "NO_DYNAMIC_ARRAY_INDEXING"] helpviewer_keywords: ["C26482"] description: CppCoreCheck rule C26482 that enforces C++ Core Guidelines Bounds.2 --- -# C26482 NO_DYNAMIC_ARRAY_INDEXING +# Warning C26482 -Only index into arrays using constant expressions. +> Only index into arrays using constant expressions. ## See also -[C++ Core Guidelines Bounds.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) +[C++ Core Guidelines Bounds.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-arrayindex) ## Example diff --git a/docs/code-quality/c26483.md b/docs/code-quality/c26483.md index c41fbc206a8..45fb0f24716 100644 --- a/docs/code-quality/c26483.md +++ b/docs/code-quality/c26483.md @@ -1,18 +1,17 @@ --- -title: C26483 +title: Warning C26483 +description: CppCoreCheck rule C26483 that enforces C++ Core Guidelines Bounds.2 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26483"] +f1_keywords: ["C26483", "STATIC_INDEX_OUT_OF_RANGE"] helpviewer_keywords: ["C26483"] -description: CppCoreCheck rule C26483 that enforces C++ Core Guidelines Bounds.2 --- -# C26483 STATIC_INDEX_OUT_OF_RANGE +# Warning C26483 -Value %value% is outside the bounds (0, %bound%) of variable '%variable%'. Only index into arrays using constant expressions that are within bounds of the array (bounds.2). +> Value '*value*' is outside the bounds (0, '*bound*') of variable '*variable*'. Only index into arrays using constant expressions that are within bounds of the array (bounds.2). ## See also -[C++ Core Guidelines Bounds.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) +[C++ Core Guidelines Bounds.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-arrayindex) ## Example @@ -25,5 +24,4 @@ void function() int arr2[] { 1, 2, 3 }; arr2[3] = 4; // C26483, 3 is outside the bounds of the array } - ``` diff --git a/docs/code-quality/c26485.md b/docs/code-quality/c26485.md index 89e92249311..ef77b057905 100644 --- a/docs/code-quality/c26485.md +++ b/docs/code-quality/c26485.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C26485 NO_ARRAY_TO_POINTER_DECAY" -title: C26485 +description: "Learn more about: Warning C26485 NO_ARRAY_TO_POINTER_DECAY" +title: Warning C26485 ms.date: 04/29/2020 -ms.topic: "conceptual" -f1_keywords: ["C26485"] +f1_keywords: ["C26485", "NO_ARRAY_TO_POINTER_DECAY"] helpviewer_keywords: ["C26485"] ms.assetid: 8915ad2d-7fd6-4bbc-abe4-0b3292ea2170 --- -# C26485 NO_ARRAY_TO_POINTER_DECAY +# Warning C26485 -> warning C26485: Expression '*array-name*': No array to pointer decay (bounds.3). +> Expression '*array-name*': No array to pointer decay (bounds.3). ## Remarks -Like [C26481](c26481.md), this check helps to enforce the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) rule [I.13](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-array): *Do not pass an array as a single pointer*. The rule detects places where static array type information is lost from decay to a raw pointer. The `zstring` and `czstring` types are not excluded. +Like [C26481](c26481.md), this check helps to enforce the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) rule [I.13](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-array): *Do not pass an array as a single pointer*. The rule detects places where static array type information is lost from decay to a raw pointer. The `zstring` and `czstring` types aren't excluded. -C26481 and C26485 come from the [Bounds Safety Profile](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) rules. These rules were implemented in the first release of the C++ Core Guidelines Checker. They're applicable to the raw pointers category since they help to avoid unsafe use of raw pointers. +C26481 and C26485 come from the [Bounds Safety Profile](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-bounds) rules. These rules were implemented in the first release of the C++ Core Guidelines Checker. They're applicable to the raw pointers category since they help to avoid unsafe use of raw pointers. ## Example diff --git a/docs/code-quality/c26486.md b/docs/code-quality/c26486.md index 4cc8e355719..bc06d1ef910 100644 --- a/docs/code-quality/c26486.md +++ b/docs/code-quality/c26486.md @@ -1,18 +1,17 @@ --- description: "Learn more about the C26486 LIFETIMES_FUNCTION_PRECONDITION_VIOLATION C++ Core Guidelines Checker warning. Don't pass an invalid pointer as a parameter." -title: C26486 LIFETIMES_FUNCTION_PRECONDITION_VIOLATION +title: Warning C26486 ms.date: 04/29/2022 -ms.topic: reference -f1_keywords: ["C26486"] +f1_keywords: ["C26486", "LIFETIMES_FUNCTION_PRECONDITION_VIOLATION"] helpviewer_keywords: ["C26486"] ms.assetid: d5395efc-5eb2-4e82-9b45-fcd5ff4577bf author: kylereedmsft ms.author: kylereed ms.custom: kr2b-contr-experiment --- -# C26486 LIFETIMES_FUNCTION_PRECONDITION_VIOLATION +# Warning C26486 -Don't pass a pointer that may be invalid (dangling) as a parameter to a function. +> Don't pass a pointer that may be invalid (dangling) as a parameter to a function. ```cpp void use(int*); @@ -37,6 +36,8 @@ The Lifetime guidelines from the C++ core guidelines outline a contract that cod - Never return (either formal return or out parameter) any pointer from a function. - Never pass an invalid (dangling) pointer to any function. +Code analysis name: `LIFETIMES_FUNCTION_PRECONDITION_VIOLATION` + ## See also - [C++ Core Guidelines Lifetimes Paper](https://github.com/isocpp/CppCoreGuidelines/blob/master/docs/Lifetime.pdf) diff --git a/docs/code-quality/c26487.md b/docs/code-quality/c26487.md index 7a53a57f8b6..801d46b9ce8 100644 --- a/docs/code-quality/c26487.md +++ b/docs/code-quality/c26487.md @@ -1,15 +1,14 @@ --- -title: C26487 +title: Warning C26487 description: "Reference for Visual Studio C++ code analysis warning C26487 from the C++ Core Guidelines." ms.date: 01/30/2020 -ms.topic: "conceptual" -f1_keywords: ["C26487"] +f1_keywords: ["C26487", "LIFETIMES_FUNCTION_POSTCONDITION_VIOLATION"] helpviewer_keywords: ["C26487"] ms.assetid: 2b0dbec3-c963-4437-8218-933717c1db98 --- -# C26487 LIFETIMES_FUNCTION_POSTCONDITION_VIOLATION +# Warning C26487 -Don't allow a function to return an invalid pointer, either through a formal return statement or through output parameters. +> Don't allow a function to return an invalid pointer, either through a formal return statement or through output parameters. ```cpp int* ex1(int a) diff --git a/docs/code-quality/c26488.md b/docs/code-quality/c26488.md index 8e108982fcb..a54608facb9 100644 --- a/docs/code-quality/c26488.md +++ b/docs/code-quality/c26488.md @@ -1,17 +1,15 @@ --- -description: "Learn more about: C26488 LIFETIMES_DEREF_NULL_POINTER" -title: C26488 +title: Warning C26488 +description: "Learn more about: Warning C26488 LIFETIMES_DEREF_NULL_POINTER" ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26488"] +f1_keywords: ["C26488", "LIFETIMES_DEREF_NULL_POINTER"] helpviewer_keywords: ["C26488"] -ms.assetid: 2ade0d31-f259-49de-8676-cce6092fabfc author: kylereedmsft ms.author: kylereed --- -# C26488 LIFETIMES_DEREF_NULL_POINTER +# Warning C26488 -Don't dereference a pointer that may be null. +> Don't dereference a pointer that may be null. ```cpp void ex1() @@ -29,9 +27,9 @@ void ex1() The Lifetime guidelines from the C++ core guidelines outline a contract that code can follow which will enable more thorough static memory leak and dangling pointer detection. The basic ideas behind the guidelines are: -1) Never dereference an invalid (dangling) or known-null pointer -2) Never return (either formal return or out parameter) any pointer from a function. -3) Never pass an invalid (dangling) pointer to any function. +1. Never dereference an invalid (dangling) or known-null pointer. +1. Never return (either formal return or out parameter) any pointer from a function. +1. Never pass an invalid (dangling) pointer to any function. ## See also diff --git a/docs/code-quality/c26489.md b/docs/code-quality/c26489.md index 2723776bed8..85df9e569a0 100644 --- a/docs/code-quality/c26489.md +++ b/docs/code-quality/c26489.md @@ -1,17 +1,15 @@ --- -description: "Learn more about: C26489 LIFETIMES_DEREF_INVALID_POINTER" -title: C26489 +title: Warning C26489 +description: "Learn more about: Warning C26489 LIFETIMES_DEREF_INVALID_POINTER" ms.date: 12/14/2018 -ms.topic: "conceptual" -f1_keywords: ["C26489"] +f1_keywords: ["C26489", "LIFETIMES_DEREF_INVALID_POINTER"] helpviewer_keywords: ["C26489"] -ms.assetid: 15983d4f-f615-42e7-8521-ee094b87d066 author: kylereedmsft ms.author: kylereed --- -# C26489 LIFETIMES_DEREF_INVALID_POINTER +# Warning C26489 -Don't dereference a pointer that may be invalid. +> Don't dereference a pointer that may be invalid. ```cpp int ex1() @@ -31,9 +29,9 @@ int ex1() The Lifetime guidelines from the C++ core guidelines outline a contract that code can follow which will enable more thorough static memory leak and dangling pointer detection. The basic ideas behind the guidelines are: -1) Never dereference an invalid (dangling) or known-null pointer -2) Never return (either formal return or out parameter) any pointer from a function. -3) Never pass an invalid (dangling) pointer to any function. +1. Never dereference an invalid (dangling) or known-null pointer. +1. Never return (either formal return or out parameter) any pointer from a function. +1. Never pass an invalid (dangling) pointer to any function. ## See also diff --git a/docs/code-quality/c26490.md b/docs/code-quality/c26490.md index b81adfe5eeb..141a6a19411 100644 --- a/docs/code-quality/c26490.md +++ b/docs/code-quality/c26490.md @@ -1,18 +1,17 @@ --- -title: C26490 +title: Warning C26490 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26490"] +f1_keywords: ["C26490", "NO_REINTERPRET_CAST"] helpviewer_keywords: ["C26490"] description: CppCoreCheck rule C26490 that enforces C++ Core Guidelines Type.1 --- -# C26490 NO_REINTERPRET_CAST +# Warning C26490 -Don't use `reinterpret_cast`. +> Don't use `reinterpret_cast`. ## See also -[C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +[C++ Core Guidelines Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-reinterpretcast). ## Example diff --git a/docs/code-quality/c26491.md b/docs/code-quality/c26491.md index a486684bf42..109c4dae5aa 100644 --- a/docs/code-quality/c26491.md +++ b/docs/code-quality/c26491.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: C26491 NO_STATIC_DOWNCAST" -title: C26491 +description: "Learn more about: Warning C26491 NO_STATIC_DOWNCAST" +title: Warning C26491 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26491"] +f1_keywords: ["C26491", "NO_STATIC_DOWNCAST"] helpviewer_keywords: ["C26491"] --- -# C26491 NO_STATIC_DOWNCAST +# Warning C26491 -Don't use `static_cast` downcasts. See [C++ Core Guidelines Type.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +> Don't use `static_cast` downcasts. See [C++ Core Guidelines Type.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-downcast). diff --git a/docs/code-quality/c26492.md b/docs/code-quality/c26492.md index 5e9ef50e4b3..33735543dcd 100644 --- a/docs/code-quality/c26492.md +++ b/docs/code-quality/c26492.md @@ -1,18 +1,17 @@ --- -title: C26492 +title: Warning C26492 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26492"] +f1_keywords: ["C26492", "NO_CONST_CAST"] helpviewer_keywords: ["C26492"] description: CppCoreCheck rule C26492 that enforces C++ Core Guidelines Type.3 --- -# C26492 NO_CONST_CAST +# Warning C26492 -Don't use `const_cast` to cast away `const`. +> Don't use `const_cast` to cast away `const`. ## See also -[C++ Core Guidelines Type.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +[C++ Core Guidelines Type.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-constcast). ## Example diff --git a/docs/code-quality/c26493.md b/docs/code-quality/c26493.md index 136eee26a6b..c67d9ffdd55 100644 --- a/docs/code-quality/c26493.md +++ b/docs/code-quality/c26493.md @@ -1,18 +1,17 @@ --- -title: C26493 +title: Warning C26493 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26493"] +f1_keywords: ["C26493", "NO_CSTYLE_CAST"] helpviewer_keywords: ["C26493"] description: CppCoreCheck rule that enforces C++ Core Guidelines Type.4 --- -# C26493 NO_CSTYLE_CAST +# Warning C26493 -Don't use C-style casts. +> Don't use C-style casts. ## See also -[C++ Core Guidelines Type.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +[C++ Core Guidelines Type.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-cstylecast). ## Example diff --git a/docs/code-quality/c26494.md b/docs/code-quality/c26494.md index 941794a77ae..447b03a4c41 100644 --- a/docs/code-quality/c26494.md +++ b/docs/code-quality/c26494.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C26494 VAR_USE_BEFORE_INIT" -title: C26494 +title: Warning C26494 +description: "Learn more about: Warning C26494 VAR_USE_BEFORE_INIT." ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26494"] +f1_keywords: ["C26494", "VAR_USE_BEFORE_INIT"] helpviewer_keywords: ["C26494"] --- -# C26494 VAR_USE_BEFORE_INIT +# Warning C26494 -Variable '%variable%' is uninitialized. Always initialize an object. +> Variable '*variable*' is uninitialized. Always initialize an object. -## See also +## Remarks -[C++ Core Guidelines Type.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +This check requires local variables to be initialized at the declaration or in the following statement. ## Example @@ -24,3 +23,19 @@ void function() std::cout << myVal; // C6001 } ``` + +To fix the issue, initialize the variable at the declaration. + +```cpp +#include +void function() +{ + int myVal{}; + std::cout << myVal; +} +``` + +## See also + +[ES.20: Always initialize an object](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-always)\ +[Pro.safety: Type-safety profile](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-type) diff --git a/docs/code-quality/c26495.md b/docs/code-quality/c26495.md index 40152b8b05a..5bfc3c16854 100644 --- a/docs/code-quality/c26495.md +++ b/docs/code-quality/c26495.md @@ -1,21 +1,26 @@ --- -title: C26495 -ms.date: 05/23/2022 -ms.topic: reference -f1_keywords: ["C26495"] +title: Warning C26495 +description: "CppCoreCheck rule that enforces C++ Core Guidelines Type.6." +ms.date: 05/11/2023 +f1_keywords: ["C26495", "MEMBER_UNINIT", "__WARNING_MEMBER_UNINIT"] helpviewer_keywords: ["C26495"] -description: CppCoreCheck rule that enforces C++ Core Guidelines Type.6 --- -# C26495 MEMBER_UNINIT +# Warning C26495 -> Variable '*identifier*' is uninitialized. Always initialize a member variable (type.6). +> Variable '*variable*' is uninitialized. Always initialize a member variable (type.6). ## Remarks -A member variable isn't initialized by a constructor or by an initializer. Make sure all variables are initialized by the end of construction. For more information, see C++ Core Guidelines [Type.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type) and [C.48](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c48-prefer-in-class-initializers-to-member-initializers-in-constructors-for-constant-initializers). +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://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-memberinit) and [C.48](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rc-in-class-initializer). + +This check is intra-procedural. Whenever there's a function call to a nonconst member function, the check assumes that this member function initializes all of the members. This heuristic can result in missed errors and is in place to avoid false positive results. Moreover, when a member is passed by nonconst reference to a function, the check assumes that the function initializes the member. + +Code analysis name: `MEMBER_UNINIT` ## Example +The following sample generates warning C26495 because the member variable `value` isn't initialized when a `MyStruct` object is created. + ```cpp struct MyStruct { @@ -24,12 +29,16 @@ struct MyStruct }; ``` -To fix the warning, add in-class initialization to all of the member variables: +To resolve the issue, you can add in-class initialization to all of the member variables. ```cpp struct MyStruct { - int value{}; + int value{}; // empty brace initializer sets value to 0 MyStruct() {} // no warning, MyStruct::value is set via default member initialization }; ``` + +## See also + +[C26494](c26494.md) \ No newline at end of file diff --git a/docs/code-quality/c26496.md b/docs/code-quality/c26496.md index 37cf4131648..9fd6800df5a 100644 --- a/docs/code-quality/c26496.md +++ b/docs/code-quality/c26496.md @@ -1,18 +1,17 @@ --- -title: C26496 +title: Warning C26496 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26496"] +f1_keywords: ["C26496", "USE_CONST_FOR_VARIABLE"] helpviewer_keywords: ["C26496"] description: CppCoreCheck rule C26496 that enforces C++ Core Guidelines Con.4 --- -# C26496 USE_CONST_FOR_VARIABLE +# Warning C26496 > The variable '*variable*' is assigned only once, mark it as `const`. ## See also -[C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +[C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). ## Example diff --git a/docs/code-quality/c26497.md b/docs/code-quality/c26497.md index 40cb974f201..36b52d3bfea 100644 --- a/docs/code-quality/c26497.md +++ b/docs/code-quality/c26497.md @@ -1,18 +1,17 @@ --- -title: C26497 +title: Warning C26497 ms.date: 03/22/2018 -ms.topic: reference -f1_keywords: ["C26497"] +f1_keywords: ["C26497", "USE_CONSTEXPR_FOR_FUNCTION"] helpviewer_keywords: ["C26497"] description: CppCoreCheck rule that enforces C++ Core Guidelines F.4 --- -# C26497 USE_CONSTEXPR_FOR_FUNCTION +# Warning C26497 > This function *function-name* could be marked `constexpr` if compile-time evaluation is desired (f.4). ## See also -[C++ Core Guidelines F.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rf-constexpr). +[C++ Core Guidelines F.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-constexpr). ## Example diff --git a/docs/code-quality/c26498.md b/docs/code-quality/c26498.md index 4b26c617e77..7bb0edb9750 100644 --- a/docs/code-quality/c26498.md +++ b/docs/code-quality/c26498.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL" -title: C26498 +title: "Warning C26498" +description: "Learn more about: Warning C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL" ms.date: 08/18/2020 -ms.topic: reference -f1_keywords: ["C26498"] +f1_keywords: ["C26498", "USE_CONSTEXPR_FOR_FUNCTIONCALL"] helpviewer_keywords: ["C26498"] --- -# C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL +# Warning C26498 -This rule helps to enforce Con.5 from the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con5-use-constexpr-for-values-that-can-be-computed-at-compile-time): use constexpr for values that can be computed at compile time. +> The function '*function*' is constexpr, mark variable '*variable*' constexpr if compile-time evaluation is desired (con.5) + +This rule helps to enforce [Con.5: Use `constexpr` for values that can be computed at compile time](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-constexpr) in the C++ Core Guidelines. ## Remarks The warning is triggered by assigning the result of a **`constexpr`** function to any non-**`constexpr`** variable whose value doesn't change after the initial assignment. +Code analysis name: `USE_CONSTEXPR_FOR_FUNCTIONCALL` + ## Example -This sample code shows where C26498 may appear, and how to avoid it: +This sample code shows where C26498 may appear: ```cpp constexpr int getMyValue() @@ -33,3 +36,28 @@ void foo() val3 = val3 * val2; } ``` + +To fix the issues, mark `val1` and `val2` **`constexpr`**: + +```cpp +constexpr int getMyValue() +{ + return 1; +} + +void foo() +{ + constexpr int val0 = getMyValue(); // OK + constexpr int val1 = getMyValue(); // OK + constexpr int val2 = getMyValue(); // OK + int val3 = getMyValue(); // OK + val3 = val3 * val2; +} +``` + + +## See also + +[C26497](c26497.md)\ +[C26814](c26814.md)\ +[Con.5: Use `constexpr` for values that can be computed at compile time](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-constexpr) diff --git a/docs/code-quality/c26800.md b/docs/code-quality/c26800.md index 6c6ce8ad760..81d9a17805f 100644 --- a/docs/code-quality/c26800.md +++ b/docs/code-quality/c26800.md @@ -1,25 +1,54 @@ --- -description: "Learn more about: C26800" -title: C26800 +title: "Warning C26800" +description: "Learn more about: Warning C26800" ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26800"] +f1_keywords: ["C26800", "USE_OF_A_MOVED_FROM_OBJECT"] helpviewer_keywords: ["C26800"] -author: sunnychatterjee -ms.author: sunnych --- -# C26800 +# Warning C26800 -> warning C26800: Use of a moved from object: \. +> Use of a moved from object: '*object*'. -Warning C26800 is triggered when variable is used after it has been moved from. A variable is considered moved from after it was passed to a function as rvalue reference. There are some legitimate exceptions for uses such as assignment, destruction, and some state resetting functions such as std::vector::clear. +## Remarks -## Examples +Warning C26800 is triggered when a variable is used after it has been moved from. A variable is considered moved from after it's passed to a function as rvalue reference. There are some exceptions for assignment, destruction, and some state resetting functions such as `std::vector::clear`. After using a state resetting function, we're free to use the variable. This check only reasons about the local variables. + +The following methods are considered state resetting methods: +- Functions with the following case-insensitive substring in their name: `clear`, `clean`, `reset`, `free`, `destroy`, `release`, `dealloc`, `assign` +- Overloaded assignment operators, destructor -The following code will generate C26800. +This check respects the `std::swap` operation: ```cpp +void f() { + Y y1, y2; + consume(std::move(y1)); + std::swap(y1, y2); + y1.method(); // OK, valid after swap. + y2.method(); // warning C26800 +} +``` +The check also supports the `try_emplace` operations in STL that conditionally move its argument: + +```cpp +int g() { + std::map m; + Y val; + auto emplRes = m.try_emplace(1, std::move(val)); + if (!emplRes.second) { + val.method(); // No C26800, val was not moved because the insertion did not happen. + } +} +``` + +Code analysis name: `USE_OF_A_MOVED_FROM_OBJECT` + +## Examples + +The following code generates C26800. + +```cpp #include struct X { @@ -37,14 +66,13 @@ void use_cref(const T&); void test() { X x1; X x2 = std::move(x1); - use_cref(x1); // @expected(26800) + use_cref(x1); // warning C26800 } ``` -The following code will not generate C26800. +The following code doesn't generate C26800. ```cpp - #include struct MoveOnly { diff --git a/docs/code-quality/c26810.md b/docs/code-quality/c26810.md index b43faab362d..027f55e32eb 100644 --- a/docs/code-quality/c26810.md +++ b/docs/code-quality/c26810.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: C26810" -title: C26810 -ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26810"] +title: "Warning C26810" +description: "Learn more about: Warning C26810." +ms.date: 05/11/2023 +f1_keywords: ["C26810", "COROUTINES_USE_AFTER_FREE_CAPTURE"] helpviewer_keywords: ["C26810"] -author: sunnychatterjee -ms.author: sunnych --- -# C26810 +# Warning C26810 -> warning C26810: Lifetime of captured variable \ might end by the time the coroutine is resumed. +> Lifetime of captured variable '*var*' might end by the time the coroutine is resumed. -Warning C26810 is triggered when a memory region might be used after it went out of scope in a resumed coroutine. +## Remarks + +Warning C26810 is triggered when a variable might be used after its lifetime ended in a resumed coroutine. + +Code analysis name: `COROUTINES_USE_AFTER_FREE_CAPTURE` ## Example -The following code will generate C26810. +The following code generates C26810. ```cpp - #include #include @@ -48,6 +48,22 @@ void bad_lambda_example1() } ``` +To fix this warning, consider using by-value arguments instead of captures: + +```cpp +void bad_lambda_example1() +{ + int x = 5; + auto good = [](int x) -> std::future { + co_await ManualControl{g_suspended_coro}; + printf("%d\n", x); + }; + good(x); +} +``` + +Alternatively, if the coroutine is guaranteed to live shorter than the lambda object, use `gsl::suppress` to suppress the warning and document the lifetime contracts in a comment. + ## See also -- [C26811](../code-quality/c26811.md) +[C26811](c26811.md) diff --git a/docs/code-quality/c26811.md b/docs/code-quality/c26811.md index eb9c6ec0e4c..7651fbbf469 100644 --- a/docs/code-quality/c26811.md +++ b/docs/code-quality/c26811.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: C26811" -title: C26811 -ms.date: 01/14/2019 -ms.topic: reference -f1_keywords: ["C26811"] +title: "Warning C26811" +description: "Learn more about: Warning C26811." +ms.date: 05/11/2023 +f1_keywords: ["C26811", "COROUTINES_USE_AFTER_FREE_PARAM"] helpviewer_keywords: ["C26811"] -author: sunnychatterjee -ms.author: sunnych --- -# C26811 +# Warning C26811 -> warning C26811: Lifetime of the memory referenced by parameter \ might end by the time the coroutine is resumed. +> Lifetime of the memory referenced by parameter '*var*' might end by the time the coroutine is resumed. -Warning C26811 is triggered when a memory region might be used after it went out of scope in a resumed coroutine. +## Remarks + +Warning C26811 is triggered when a variable might be used after its lifetime ended in a resumed coroutine. + +Code analysis name: `COROUTINES_USE_AFTER_FREE_PARAM` ## Example -The following code will generate C26811. +The following code generates C26811. ```cpp - #include #include @@ -44,6 +44,18 @@ std::future async_coro(int &a) } ``` +To fix this warning, consider taking the argument by value: + +```cpp +std::future async_coro(int a) +{ + co_await ManualControl{g_suspended_coro}; + ++a; +} +``` + +Alternatively, when the lifetime of `a` is guaranteed to outlive the lifetime of the coroutine, suppress the warning using `gsl::suppress` and document the lifetime contracts of the code. + ## See also -- [C26810](../code-quality/c26810.md) +[C26810](c26810.md) diff --git a/docs/code-quality/c26812.md b/docs/code-quality/c26812.md index 2b452c48152..3ea3543dc18 100644 --- a/docs/code-quality/c26812.md +++ b/docs/code-quality/c26812.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: C26812" -title: c26812 -keywords: c26812 +title: "Warning C26812" +description: "Learn more about: Warning C26812" ms.date: 02/14/2022 -ms.topic: reference -f1_keywords: ["C26812"] +f1_keywords: ["C26812", "PreferScopedEnum"] helpviewer_keywords: ["C26812"] -dev_langs: ["C++"] --- -# C26812 +# Warning C26812 -> Warning C26812: Prefer 'enum class' over 'enum' (Enum.3) +> The enum type '*type-name*' is unscoped. Prefer 'enum class' over 'enum' (Enum.3) -The `enum` type *type-name* is unscoped. Prefer `enum class` over `enum` (Enum.3) +## Remarks + +Prefer `enum class` over `enum` to prevent pollution in the global namespace. + +Code analysis name: `PreferScopedEnum` ## Example @@ -46,4 +47,4 @@ Print_color(Product_info::Red); // Error: cannot convert Product_info to int. ## See also -[Enum.3 Prefer enum class over enum](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#enum3-prefer-class-enums-over-plain-enums) +[Enum.3 Prefer enum class over enum](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Renum-class) diff --git a/docs/code-quality/c26813.md b/docs/code-quality/c26813.md index 76618ca09e1..cbaa14e3863 100644 --- a/docs/code-quality/c26813.md +++ b/docs/code-quality/c26813.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: C26813" -title: c26813 -ms.date: 03/02/2022 -ms.topic: reference -f1_keywords: ["C26813"] +title: "Warning C26813" +description: "Learn more about: Warning C26813" +ms.date: 05/17/2022 +f1_keywords: ["C26813", "USE_BITWISE_AND_TO_CHEK_ENUM_FLAGS", "USE_BITWISE_AND_TO_CHECK_ENUM_FLAGS"] helpviewer_keywords: ["C26813"] --- -# C26813 +# Warning C26813 -> Warning C26813: Use 'bitwise and' to check if a flag is set +> Use 'bitwise and' to check if a flag is set + +## Remarks Most `enum` types with power of two member values are intended to be used as bit flags. As a result, you rarely want to compare these flags for equality. Instead, extract the bits you're interested in by using bitwise operations. +Code analysis name: `USE_BITWISE_AND_TO_CHEK_ENUM_FLAGS` + ## Example ```cpp diff --git a/docs/code-quality/c26814.md b/docs/code-quality/c26814.md index eeb77e1c86c..363b3c50732 100644 --- a/docs/code-quality/c26814.md +++ b/docs/code-quality/c26814.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C26814" -title: c26814 -keywords: c26814 +title: "Warning C26814" +description: "Learn more about: Warning C26814" ms.date: 07/15/2019 -ms.topic: reference -f1_keywords: ["C26814"] +f1_keywords: ["C26814", "USE_CONSTEXPR_RATHER_THAN_CONST"] helpviewer_keywords: ["C26814"] -dev_langs: ["C++"] --- -# C26814 +# Warning C26814 -> Warning C26814: Use constexpr for constants whose value is known at compile time. (Con.5) -The const variable '%variable%' can be computed at compile time. Consider using constexpr (con.5) +> The const variable '*variable*' can be computed at compile time. Consider using `constexpr` (con.5) + +## Remarks + +Use `constexpr` for constants whose value is known at compile time. (Con.5) + +Code analysis name: `USE_CONSTEXPR_RATHER_THAN_CONST` ## Example @@ -31,4 +33,4 @@ void bar() ## See also -[Con.5 Use constexpr for all variables that can be computed at compile time](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-constexpr) +[Con.5 Use constexpr for all variables that can be computed at compile time](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-constexpr) diff --git a/docs/code-quality/c26815.md b/docs/code-quality/c26815.md index 811812568c8..bab51260def 100644 --- a/docs/code-quality/c26815.md +++ b/docs/code-quality/c26815.md @@ -1,21 +1,29 @@ --- -description: "Learn more about: Warning C26815 The pointer is dangling because it points at a temporary instance that was destroyed. (ES.65)" -title: c26815 -keywords: c26815 +title: "Warning C26815" +description: "Learn more about: Warning C26815." +ms.date: 01/27/2020 author: Rastaban ms.author: philc -ms.date: 01/27/2020 -ms.topic: reference -f1_keywords: ["C26815"] +f1_keywords: ["C26815", "LIFETIME_LOCAL_USE_AFTER_FREE_TEMP"] helpviewer_keywords: ["C26815"] -dev_langs: ["C++"] --- -# Warning C26815 The pointer is dangling because it points at a temporary instance that was destroyed. (ES.65) +# Warning C26815 + +> The pointer is dangling because it points at a temporary instance that was destroyed. (ES.65) + +## Remarks + +The created pointer or view refers to an unnamed temporary object that is destroyed at the end of the statement. The pointer or view will dangle. + +This check recognizes views and owners from the C++ Standard Template Library (STL). To teach this check about user-authored types, use the `[[msvc::lifetimebound]]` annotation. +The `[[msvc::lifetimebound]]` support is new in MSVC 17.7. -There is a dangling pointer that is the result of an unnamed temporary that has been destroyed. +Code analysis name: `LIFETIME_LOCAL_USE_AFTER_FREE_TEMP` ## Example +Consider the following code compiled in a C++ version before C++23: + ```cpp std::optional> getTempOptVec(); @@ -33,6 +41,11 @@ void views() // Oops, the 's' suffix turns the string literal into a temporary std::string. std::string_view value("This is a std::string"s); // warning C26815 } + +struct Y { int& get() [[msvc::lifetimebound]]; }; +void f() { + int& r = Y{}.get(); // warning C26815 +} ``` These warnings can be fixed by extending the lifetime of the temporary object. @@ -54,8 +67,15 @@ void views() // Fixed by changing to a constant string literal. std::string_view value("This is a string literal"); } + +struct Y { int& get() [[msvc::lifetimebound]]; }; +void f() { + Y y{}; + int& r = y.get(); +} ``` ## See also -[ES.65: Don't dereference an invalid pointer](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-deref) +[C26816](c26816.md)\ +[ES.65: Don't dereference an invalid pointer](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-deref) diff --git a/docs/code-quality/c26816.md b/docs/code-quality/c26816.md index 768f918df43..0dd97234962 100644 --- a/docs/code-quality/c26816.md +++ b/docs/code-quality/c26816.md @@ -1,20 +1,26 @@ --- -description: "Learn more about: Warning C26816 The pointer points to memory allocated on the stack (ES.65)" -title: c26816 -keywords: c26816 +title: "Warning C26816" +description: "Learn more about: Warning C26816." +ms.date: 01/27/2020 author: Rastaban ms.author: philc -ms.date: 01/27/2020 -ms.topic: reference -f1_keywords: ["C26816"] +f1_keywords: ["C26816", "LIFETIME_LOCAL_USE_AFTER_FREE_STACK"] helpviewer_keywords: ["C26816"] -dev_langs: ["C++"] --- -# Warning C26816 The pointer points to memory allocated on the stack (ES.65) +# Warning C26816 + +> The pointer points to memory allocated on the stack (ES.65) + +## Remarks + +The pointer points to a variable that is allocated on the stack. When the variable goes out of scope it's cleaned up, which causes the pointer to be invalid. -The pointer points to a variable that is allocated on the stack. When the variable goes out of scope it is cleaned up, which causes the pointer to be invalid. +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. -## Example +Code analysis name: `LIFETIME_LOCAL_USE_AFTER_FREE_STACK` + +## Examples ```cpp // In this example, std::string is being used internally because the implementer felt it was easier to @@ -24,7 +30,13 @@ const char *danglingRawPtrFromLocal() { // interesting string initialization here - return s.c_str(); // Oops, The pointer points to memory allocated on the stack + return s.c_str(); // Oops, The pointer points to memory that will be cleaned up upon return. Warning C26816. +} + +struct Y { int& get() [[msvc::lifetimebound]]; }; +int& f() { + Y y; + return y.get(); // Warning C26826 } ``` @@ -39,8 +51,15 @@ std::string danglingRawPtrFromLocal() { return s; } + +struct Y { int& get() [[msvc::lifetimebound]]; }; +int f() { + Y y; + return y.get(); +} ``` ## See also -[ES.65: Don't dereference an invalid pointer](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-deref) +[C26815](c26815.md)\ +[ES.65: Don't dereference an invalid pointer](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-deref) diff --git a/docs/code-quality/c26817.md b/docs/code-quality/c26817.md index 11e462699e6..9e8bcb7a9b2 100644 --- a/docs/code-quality/c26817.md +++ b/docs/code-quality/c26817.md @@ -1,16 +1,17 @@ --- -title: C26817 +title: "Warning C26817" description: "Reference for Microsoft C++ Code Analysis warning C26817 in Visual Studio." -ms.date: 02/24/2020 -ms.topic: "reference" +ms.date: 10/12/2023 f1_keywords: ["C26817"] helpviewer_keywords: ["C26817"] --- -# C26817 +# Warning C26817 > Potentially expensive copy of variable *name* in range-for loop. Consider making it a const reference (es.71). -For more information, see [ES.71 notes](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#note-214) in the C++ Core Guidelines. +## Remarks + +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#Res-for-range) in the C++ Core Guidelines. ## Example @@ -26,7 +27,7 @@ class MyComplexType { void expensive_function(std::vector& complex_vector_ref) { - for (auto item: complex_vector_ref) + for (auto item: complex_vector_ref) // Warning: C26817 { // At each iteration, item gets a copy of the next element // ... @@ -39,9 +40,7 @@ void expensive_function(std::vector& complex_vector_ref) } ``` -This behavior is fine for scalars (pointers, arithmetic types, and so on), but for larger types, the copying may become expensive. - -## Solution +The warning is ignoring some types that are cheap to copy like for scalars (pointers, arithmetic types, and so on). To fix this issue, if the loop variable isn't mutated anywhere in the loop, make it a const reference: @@ -68,4 +67,4 @@ void less_expensive_function(std::vector& complex_vector_ref) } ``` -The **`const`** keyword makes the loop variable immutable. Use of a non-const reference may cause potentially unwanted side effects in the original container elements. If you need to modify only the local loop variable, the potentially expensive copying is unavoidable. +The **`const`** keyword makes the loop variable immutable. Use of a non-const reference makes it possible to inadvertently use the reference to modify the container's elements. If you need to modify only the local loop variable, the potentially expensive copying is unavoidable. diff --git a/docs/code-quality/c26818.md b/docs/code-quality/c26818.md index cac9a5c97b0..46d89915db4 100644 --- a/docs/code-quality/c26818.md +++ b/docs/code-quality/c26818.md @@ -1,12 +1,12 @@ --- -title: C26818 +title: "Warning C26818" description: "Reference for Microsoft C++ Code Analysis warning C26818 in Visual Studio." ms.date: 04/22/2020 f1_keywords: ["C26818"] helpviewer_keywords: ["C26818"] no-loc: [ default, int, char ] --- -# C26818 +# Warning C26818 > Switch statement does not cover all cases. Consider adding a 'default' label (es.79). @@ -14,7 +14,7 @@ no-loc: [ default, int, char ] This check covers the missing **`default`** label in switch statements that switch over a non-enumeration type, such as **`int`**, **`char`**, and so on. -For more information, see [ES.79: Use default to handle common cases (only)](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es79-use-default-to-handle-common-cases-only) in the C++ Core Guidelines. +For more information, see [ES.79: Use default to handle common cases (only)](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-default) in the C++ Core Guidelines. ## Example diff --git a/docs/code-quality/c26819.md b/docs/code-quality/c26819.md index 28c85110edf..19dd7513510 100644 --- a/docs/code-quality/c26819.md +++ b/docs/code-quality/c26819.md @@ -1,12 +1,11 @@ --- -title: C26819 +title: "Warning C26819" description: "Reference for Microsoft C++ Code Analysis warning C26819 in Visual Studio." ms.date: 04/22/2020 -ms.topic: "reference" f1_keywords: ["C26819"] helpviewer_keywords: ["C26819"] --- -# C26819 +# Warning C26819 > Unannotated fallthrough between switch labels (es.78). @@ -14,11 +13,11 @@ helpviewer_keywords: ["C26819"] This check covers implicit fallthrough in switch statements. Implicit fallthrough is when control flow transfers from one switch case directly into a following switch case without the use of the `[[fallthrough]];` statement. This warning is raised when an implicit fallthrough is detected in a switch case containing at least one statement. -For more information, see [ES.78: Don't rely on implicit fallthrough in `switch` statements](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-break) in the C++ Core Guidelines. +For more information, see [ES.78: Don't rely on implicit fallthrough in `switch` statements](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-break) in the C++ Core Guidelines. ## Example -In this sample, implicit fallthrough occurs from a non-empty switch case into a following case. +In this sample, implicit fallthrough occurs from a nonempty `switch` `case` into a following `case`. ```cpp void fn1(); @@ -28,10 +27,10 @@ void foo(int a) { switch (a) { - case 0: // implicit fallthrough from case 0 to case 1 is OK because case 0 is empty + case 0: // implicit fallthrough from case 0 to case 1 is OK because case 0 is empty case 1: fn1(); // implicit fallthrough from case 1 into case 2 - case 2: + case 2: // Warning C26819. fn2(); break; default: @@ -40,8 +39,6 @@ void foo(int a) } ``` -## Solution - To fix this issue, insert a `[[fallthrough]];` statement where the fallthrough occurs. ```cpp @@ -87,3 +84,7 @@ void foo(int a) } } ``` + +## See also + +[ES.78: Don't rely on implicit fallthrough in `switch` statements](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-break) diff --git a/docs/code-quality/c26820.md b/docs/code-quality/c26820.md index 865640ad169..bec99f63c72 100644 --- a/docs/code-quality/c26820.md +++ b/docs/code-quality/c26820.md @@ -1,19 +1,19 @@ --- -title: C26820 +title: "Warning C26820" description: "Reference for Microsoft C++ Code Analysis warning C26820 in Visual Studio." -ms.date: 04/07/2020 +ms.date: 10/12/2023 f1_keywords: ["C26820"] helpviewer_keywords: ["C26820"] --- -# C26820 +# Warning C26820 -> Assigning by value when a const-reference would suffice, use const auto& instead (p.9). +> This is a potentially expensive copy operation. Consider using a reference unless a copy is required (p.9) -For more information, see [P.9: Don't waste time or space](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#p9-dont-waste-time-or-space) in the C++ Core Guidelines. +## Remarks -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. +For more information, see [P.9: Don't waste time or space](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rp-waste) in the C++ Core Guidelines. -## Remarks +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. - This warning isn't raised for scalars, smart pointers, or views. It's also not raised for types whose size isn't more than twice the platform-dependent pointer size. - This warning isn't raised when the variable gets mutated, as marking it `auto&` would introduce side-effects to the mutation. diff --git a/docs/code-quality/c26822.md b/docs/code-quality/c26822.md index 242d4dcf5d3..15e355ba209 100644 --- a/docs/code-quality/c26822.md +++ b/docs/code-quality/c26822.md @@ -1,42 +1,44 @@ --- -title: C26822 +title: "Warning C26822" description: "Describes the Microsoft C/C++ code analysis warning C26822, its causes, and how to address it." ms.date: 06/27/2022 -f1_keywords: ["C26822"] +f1_keywords: ["C26822", "NULLPTR_DEREFERENCE"] helpviewer_keywords: ["C26822"] --- +# Warning C26822 -# C26822: NULLPTR_DEREFERENCE +> Dereferencing a null pointer '*variable*' (lifetime.1) -Dereferencing a null pointer is frequent problem in C and C++. We have a variety of checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine deduces the value of a pointer to be null and sees a dereference to that pointer it will emit a `C26822` warning. You can also enable [C26823](../code-quality/c26823.md) for a stricter analysis. This check also supports [SAL annotations](../code-quality/understanding-sal.md) and [`gsl::not_null`](https://github.com/microsoft/GSL) to describe invariants of the code. +## Remarks +Dereferencing a null pointer is frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine deduces the value of a pointer to be null and sees that pointer get dereferenced, it will emit a `C26822` warning. You can also enable [C26823](../code-quality/c26823.md) for a stricter analysis. This check also supports [SAL annotations](../code-quality/understanding-sal.md) and [`gsl::not_null`](https://github.com/microsoft/GSL) to describe invariants of the code. ## Example ```cpp -void f(int *p) { -    if (p == nullptr) -     *p = 42; // warning: C26822 +void f(int *p) { + if (p == nullptr) + *p = 42; // warning: C26822 } -void assign_to_gsl_notnull() { -    int* p = nullptr; -    auto q = gsl::make_not_null(p); // C26822 warning +void assign_to_gsl_notnull() { + int* p = nullptr; + auto q = gsl::make_not_null(p); // C26822 warning } ``` -To solve this warning, make sure there is no null pointer dereference in the code, potentially by adding null checks. In case the code was found to be correct, false positive findings can often be fixed by using `gsl::not_null` or SAL annotations. There are some examples how to use some of those annotations below: +To solve this warning, make sure there's no null pointer dereference in the code, potentially by adding null checks. In case the code was found to be correct, false positive findings can often be fixed by using `gsl::not_null` or SAL annotations. There are some examples how to use some of those annotations below: ```cpp -_Notnull_ int *get_my_ptr(); -gsl::not_null get_my_ptr2(); +_Notnull_ int *get_my_ptr(); +gsl::not_null get_my_ptr2(); -void local_analysis(int *p) { -    _Analysis_assume_(p != nullptr); -    *p = 42; +void local_analysis(int *p) { + _Analysis_assume_(p != nullptr); + *p = 42; } -void local_analysis2(_In_ int *p) { -    int a = *p; +void local_analysis2(_In_ int *p) { + int a = *p; } ``` diff --git a/docs/code-quality/c26823.md b/docs/code-quality/c26823.md index 339e744317c..e89b46c2e42 100644 --- a/docs/code-quality/c26823.md +++ b/docs/code-quality/c26823.md @@ -1,15 +1,17 @@ --- -title: C26823 +title: "Warning C26823" description: "Describes the Microsoft C/C++ code analysis warning C26823, its causes, and how to address it." ms.date: 06/27/2022 -f1_keywords: ["C26823"] +f1_keywords: ["C26823", "NULLPTR_DEREFERENCE_MAYBE"] helpviewer_keywords: ["C26823"] --- +# Warning C26823 -# C26823: NULLPTR_DEREFERENCE_MAYBE +> Dereferencing a possibly null pointer '*variable*' (lifetime.1) -Dereferencing a null pointer is frequent problem in C and C++. We have a variety of checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine deduces the value of a pointer might be null and sees a dereference to that pointer it will emit a `C26823` warning. You can enable [C26822](../code-quality/c26822.md) only for a more permissive analysis. This check also supports [SAL annotations](../code-quality/understanding-sal.md) and [`gsl::not_null`](https://github.com/microsoft/GSL) to describe invariants of the code. +## Remarks +Dereferencing a null pointer is frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine deduces that the value of a pointer might be null and sees that pointer get dereferenced, it will emit a `C26823` warning. You can enable [C26822](../code-quality/c26822.md) only for a more permissive analysis. This check also supports [SAL annotations](../code-quality/understanding-sal.md) and [`gsl::not_null`](https://github.com/microsoft/GSL) to describe invariants of the code. ## Example @@ -26,18 +28,18 @@ void condition_null_dereference_invalidated(int* p) } ``` -To solve this warning, make sure there is no null pointer dereference in the code, potentially by adding null checks. In case the code was found to be correct, false positive findings can often be fixed by using `gsl::not_null` or SAL annotations. There are some examples how to use some of those annotations below: +To solve this warning, make sure there's no null pointer dereference in the code, potentially by adding null checks. In case the code was found to be correct, false positive findings can often be fixed by using `gsl::not_null` or SAL annotations. There are some examples how to use some of those annotations below: ```cpp -_Notnull_ int *get_my_ptr(); -gsl::not_null get_my_ptr2(); +_Notnull_ int *get_my_ptr(); +gsl::not_null get_my_ptr2(); -void local_analysis(int *p) { -    _Analysis_assume_(p != nullptr); -    *p = 42; +void local_analysis(int *p) { + _Analysis_assume_(p != nullptr); + *p = 42; } -void local_analysis2(_In_ int *p) { -    int a = *p; +void local_analysis2(_In_ int *p) { + int a = *p; } -``` \ No newline at end of file +``` diff --git a/docs/code-quality/c26824.md b/docs/code-quality/c26824.md index a5803a770ca..c2e9cea848d 100644 --- a/docs/code-quality/c26824.md +++ b/docs/code-quality/c26824.md @@ -1,23 +1,25 @@ --- -title: C26824 +title: "Warning C26824" description: "Describes the Microsoft C/C++ code analysis warning C26824, its causes, and how to address it." ms.date: 06/27/2022 -f1_keywords: ["C26824"] +f1_keywords: ["C26824", "NULLPTR_POSTCONDITION_VIOLATION"] helpviewer_keywords: ["C26824"] --- +# Warning C26824 -# C26824: NULLPTR_POSTCONDITION_VIOLATION +> Postcondition for null pointer '*variable*' requires it to be non-null (lifetime.1) -Dereferencing a null pointer is frequent problem in C and C++. We have a variety of checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine sees a null pointer returned from a function that has a contract forbidding such operation, it will emit a `C26824` warning. You can also enable [C26825](../code-quality/c26825.md) for a stricter analysis. This check only works on functions annotated using [SAL annotations](../code-quality/understanding-sal.md). +## Remarks +Dereferencing a null pointer is a frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine sees a null pointer returned from a function that has a contract forbidding such an operation, it will emit a `C26824` warning. You can also enable [C26825](../code-quality/c26825.md) for a stricter analysis. This check only works on functions annotated using [SAL annotations](../code-quality/understanding-sal.md). ## Example ```cpp -void postcondition_conditional(bool b, _When_(b == true, _Outptr_) int** p) { -    if (b == true) -        *p = nullptr; // C26824 warning +void postcondition_conditional(bool b, _When_(b == true, _Outptr_) int** p) { + if (b == true) + *p = nullptr; // C26824 warning } ``` -To solve this warning, make sure there is no null pointer returned from the annotated function or change the annotations to reflect the behavior of the function. \ No newline at end of file +To solve this warning, make sure there's no null pointer returned from the annotated function. Or, change the annotations to reflect the behavior of the function. diff --git a/docs/code-quality/c26825.md b/docs/code-quality/c26825.md index adc98d0cafa..0c438deafb8 100644 --- a/docs/code-quality/c26825.md +++ b/docs/code-quality/c26825.md @@ -1,22 +1,24 @@ --- -title: C26825 +title: "Warning C26825" description: "Describes the Microsoft C/C++ code analysis warning C26825, its causes, and how to address it." ms.date: 06/27/2022 -f1_keywords: ["C26825"] +f1_keywords: ["C26825", "NULLPTR_POSTCONDITION_VIOLATION_MAYBE"] helpviewer_keywords: ["C26825"] --- +# Warning C26825 -# C26825: NULLPTR_POSTCONDITION_VIOLATION_MAYBE +> Postcondition for possibly null pointer '*variable*' requires it to be non-null (lifetime.1) -Dereferencing a null pointer is frequent problem in C and C++. We have a variety of checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine sees a potentially null pointer returned from a function that has a contract forbidding such operation, it will emit a `C26825` warning. You can enable [C26824](../code-quality/c26824.md) only for a more permissive analysis. This check only works on functions annotated using [SAL annotations](../code-quality/understanding-sal.md). +## Remarks +Dereferencing a null pointer is a frequent problem in C and C++. We have several checks to deal with such problems. See this [blog post](https://devblogs.microsoft.com/cppblog/improved-null-pointer-dereference-detection-in-visual-studio-2022-version-17-0-preview-4/) for a comparison. When the analysis engine sees a potentially null pointer returned from a function that has a contract forbidding such operation, it will emit a `C26825` warning. You can enable [C26824](../code-quality/c26824.md) only for a more permissive analysis. This check only works on functions annotated using [SAL annotations](../code-quality/understanding-sal.md). ## Example ```cpp -void postcondition_conditional(int *q, _Outptr_ int** p) { - *p = q; // C26825 warning +void postcondition_conditional(int *q, _Outptr_ int** p) { + *p = q; // C26825 warning } ``` -To solve this warning, make sure there is no null pointer returned from the annotated function or change the annotations to reflect the behavior of the function. \ No newline at end of file +To solve this warning, make sure there's no null pointer returned from the annotated function. Or, change the annotations to reflect the behavior of the function. diff --git a/docs/code-quality/c26826.md b/docs/code-quality/c26826.md index 0dcfd827128..d1da079af20 100644 --- a/docs/code-quality/c26826.md +++ b/docs/code-quality/c26826.md @@ -1,18 +1,18 @@ --- -title: C26826 +title: "Warning C26826" description: "Reference for Microsoft C++ Code Analysis warning C26826 in Visual Studio." ms.date: 10/25/2021 f1_keywords: ["C26826"] helpviewer_keywords: ["C26826"] --- -# C26826 +# Warning C26826 > Don't use C-style variable arguments (f.55). -For more information, see [F.55: Don't use `va_arg` arguments](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#F-varargs) in the C++ Core Guidelines. - ## Remarks +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. + This check warns on all usages of `va_list`, `va_start`, `va_arg`, and `va_end`, discouraging the use of C-style variable arguments. C-style variable arguments are unsafe because they require the programmer to assume that the arguments are all passed and read with the correct types. Warning C26826 is available starting in Visual Studio 2022 version 17.1. @@ -41,6 +41,7 @@ int main() { ``` Alternatives to C-style variable arguments include: + - function overloading - variadic templates - `std::variant` arguments diff --git a/docs/code-quality/c26827.md b/docs/code-quality/c26827.md index 2d8b5475a64..6f806ba3939 100644 --- a/docs/code-quality/c26827.md +++ b/docs/code-quality/c26827.md @@ -1,19 +1,24 @@ --- -description: "Learn more about: C26827" -title: c26827 -ms.date: 03/02/2022 -ms.topic: reference -f1_keywords: ["C26827"] +title: "Warning C26827" +description: "Learn more about: Warning C26827" +ms.date: 05/17/2023 +f1_keywords: ["C26827", "ALMOST_BITWISE_ENUM"] helpviewer_keywords: ["C26827"] --- -# C26827 +# Warning C26827 -> Warning C26827: Did you forget to initialize an enum, or intend to use another type? +> Did you forget to initialize an enum, or intend to use another type? + +## Remarks Most `enum` types used in bitwise operations are expected to have members with values of powers of two. This warning attempts to find cases where a value wasn't given explicitly to an enumeration constant. It also finds cases where the wrong enumeration type may have been used inadvertently. +Code analysis name: `ALMOST_BITWISE_ENUM` + ## Example +The following sample code causes warning C26827: + ```cpp enum class AlmostBitWise { diff --git a/docs/code-quality/c26828.md b/docs/code-quality/c26828.md index 34eef90fec0..ad057d7aa97 100644 --- a/docs/code-quality/c26828.md +++ b/docs/code-quality/c26828.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C26828" -title: c26828 -ms.date: 03/02/2022 -ms.topic: reference -f1_keywords: ["C26828"] +title: "Warning C26828" +description: "Learn more about: Warning C26828" +ms.date: 05/17/2023 +f1_keywords: ["C26828", "MIXING_OVERLAPPING_ENUMS"] helpviewer_keywords: ["C26828"] --- -# C26828 +# Warning C26828 -> Warning C26828: Different enum types have overlapping values. Did you want to use another enum constant here? +> Different enum types have overlapping values. Did you want to use another enum constant here? + +## Remarks Most of the time, a single enumeration type describes all the bit flags that you can use for an option. If you use two different enumeration types that have overlapping values in the same bitwise expression, the chances are good those enumeration types weren't designed for use together. +Code analysis name: `MIXING_OVERLAPPING_ENUMS` + ## Example -```cpp +The following sample code causes warning C26828: +```cpp enum BitWiseA { A = 1, @@ -40,7 +44,6 @@ int overlappingBitwiseEnums(BitWiseA a) To fix the warning, make sure enumeration types designed for use together have no overlapping values. Or, make sure all the related options are in a single enumeration type. ```cpp - enum BitWiseA { A = 1, diff --git a/docs/code-quality/c26829.md b/docs/code-quality/c26829.md index 7dabeacd064..9eb04b47e84 100644 --- a/docs/code-quality/c26829.md +++ b/docs/code-quality/c26829.md @@ -1,14 +1,17 @@ --- -title: C26829 +title: "Warning C26829" description: "Describes the Microsoft C/C++ code analysis warning C26829, its causes, and how to address it." ms.date: 06/23/2022 -f1_keywords: ["C26829"] +f1_keywords: ["C26829", "UNWRAP_EMPTY_OPTIONAL"] helpviewer_keywords: ["C26829"] --- +# Warning C26829 -# C26829: UNWRAP_EMPTY_OPTIONAL +> Empty optional '*variable*' is unwrapped -Unwrapping empty `std::optional` values is undefined behavior. Such operation is considered a security vulnerability as it can result in a crash, reading uninitialized memory, or other unexpected behavior. This check will attempt to find cases where the value of the `std::optional` is known to be empty and unwrapped. You can also enable [C26830](../code-quality/c26830.md) for a stricter analysis. +## Remarks + +Unwrapping empty `std::optional` values is undefined behavior. Such operation is considered a security vulnerability as it can result in a crash, reading uninitialized memory, or other unexpected behavior. This check will attempt to find cases where a `std::optional` is known to be empty and unwrapped. You can also enable [C26830](../code-quality/c26830.md), [C26859](../code-quality/c26859.md), and [C26860](../code-quality/c26860.md) for a stricter analysis. ## Example @@ -24,4 +27,4 @@ void f(std::optional maybeEmpty) } ``` -To solve this problem, make sure the code never unwraps an empty optional. +To solve this problem, make sure the code never unwraps an empty optional. Alternatively, use the `value` method and make sure you handle the `std::bad_optional_access` exception. diff --git a/docs/code-quality/c26830.md b/docs/code-quality/c26830.md index 4dcfd3d2e48..513cf97632c 100644 --- a/docs/code-quality/c26830.md +++ b/docs/code-quality/c26830.md @@ -1,14 +1,17 @@ --- -title: C26830 +title: "Warning C26830" description: "Describes the Microsoft C/C++ code analysis warning C26830, its causes, and how to address it." ms.date: 06/23/2022 -f1_keywords: ["C26830"] +f1_keywords: ["C26830", "UNWRAP_EMPTY_OPTIONAL_MAYBE"] helpviewer_keywords: ["C26830"] --- +# Warning C26830 -# C26830: UNWRAP_EMPTY_OPTIONAL_MAYBE +> Potentially empty optional '*variable*' is unwrapped -Unwrapping empty `std::optional` values is undefined behavior. Such operation is considered a security vulnerability as it can result in a crash, reading uninitialized memory, or other unexpected behavior. This check will attempt to find cases where the value of the `std::optional` is not checked for emptiness before unwrap operations. You can enable [C26829](../code-quality/c26829.md) only for a more permissive analysis. +## Remarks + +Unwrapping empty `std::optional` values is undefined behavior. Such operation is considered a security vulnerability as it can result in a crash, reading uninitialized memory, or other unexpected behavior. This check will attempt to find cases where a `std::optional` isn't checked for emptiness before unwrap operations. You can enable [C26829](../code-quality/c26829.md) only for a more permissive analysis. ## Example @@ -25,4 +28,4 @@ void f(std::optional maybeEmpty) } ``` -To solve this problem, make sure the code never unwraps an empty optional. +To solve this problem, make sure the code never unwraps an empty optional. Alternatively, use the `value` method and make sure you handle the `std::bad_optional_access` exception. \ No newline at end of file diff --git a/docs/code-quality/c26831.md b/docs/code-quality/c26831.md new file mode 100644 index 00000000000..fba6057d2f2 --- /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 00000000000..adf379b5ca0 --- /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 00000000000..f7519480984 --- /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 00000000000..1070ca73fdb --- /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 00000000000..2be95d94db5 --- /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 00000000000..652ec704cde --- /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 00000000000..96d47c6df22 --- /dev/null +++ b/docs/code-quality/c26839.md @@ -0,0 +1,53 @@ +--- +title: Warning C26839 +description: Learn about Microsoft C++ code analysis warning C26839. +author: Rastaban +ms.author: philc +ms.topic: reference +ms.date: 1/10/2025 +--- +# Warning C26839 + +> Array new allocation size is the result of a signed to unsigned narrowing conversion that could result in overflow if the signed value is negative. + +This warning was added in Visual Studio 2022 version 17.13. + +## Remarks + +Reports that the size specified for an array `new` allocation may be the result of the conversion of a possibly negative signed value to an unsigned value. For example: + +```cpp +int* CreateIntArray(int size) +{ + int* intArray = new int[size]; + return intArray; +} +``` + +The expression `new int[size]`, `size` is signed. The compiler converts the signed value to an unsigned value to calculate how many bytes to be allocated for the array. When `size` is negative, the result of that calculation may overflow or have unexpected results when passed to `new`. + +This check is the same as [`C26838`](c26838.md), but applies only to `new T[]`. + +This check sometimes fails to recognize that certain checks can prevent overflows because the check is conservative. + +## Example + +To fix the previous code example in which the size calculation might overflow due to a negative signed value, introduce a check to ensure it won't. For example: + +```cpp +int* CreateIntArray(int size) +{ + if (size < 0) + return nullptr; + + int* intArray = new int[size]; + return intArray; +} +``` + +## See also + +[`C26831`](c26831.md)\ +[`C26832`](c26832.md)\ +[`C26838`](c26833.md)\ +[`C26838`](c26838.md) \ No newline at end of file diff --git a/docs/code-quality/c26859.md b/docs/code-quality/c26859.md new file mode 100644 index 00000000000..23e1980b8c9 --- /dev/null +++ b/docs/code-quality/c26859.md @@ -0,0 +1,30 @@ +--- +title: Warning C26859 +description: "Describes the Microsoft C/C++ code analysis warning C26859, its causes, and how to address it." +ms.date: 12/15/2022 +f1_keywords: ["C26859", "UNWRAP_EMPTY_OPTIONAL_VALUE"] +helpviewer_keywords: ["C26859"] +--- +# Warning C26859 + +> Empty optional '*variable*' is unwrapped, will throw exception + +## Remarks + +Unwrapping empty `std::optional` values via the `value` method will throw an exception. Such operation can result in a crash when the exception isn't handled. This check will attempt to find cases where a `std::optional` is known to be empty and unwrapped using the `value` method. You can also enable [C26829](../code-quality/c26829.md), [C26830](../code-quality/c26830.md), and [C26860](../code-quality/c26860.md) for a stricter analysis. + +## Example + +```cpp +void f(std::optional maybeEmpty) +{ + std::optional empty; + std::optional nonEmpty{5}; + nonEmpty.value() = 42; // No warning + empty.value() = 42; // warning: C26859 + if (!maybeEmpty) + maybeEmpty.value() = 42; // warning: C26859 +} +``` + +To solve this problem, make sure the code never unwraps an empty optional. diff --git a/docs/code-quality/c26860.md b/docs/code-quality/c26860.md new file mode 100644 index 00000000000..6bae85a25eb --- /dev/null +++ b/docs/code-quality/c26860.md @@ -0,0 +1,31 @@ +--- +title: Warning C26860 +description: "Describes the Microsoft C/C++ code analysis warning C26860, its causes, and how to address it." +ms.date: 12/15/2022 +f1_keywords: ["C26860", "UNWRAP_EMPTY_OPTIONAL_VALUE_MAYBE"] +helpviewer_keywords: ["C26860"] +--- +# Warning C26860 + +> Potentially empty optional '*variable*' is unwrapped, may throw exception + +## Remarks + +Unwrapping empty `std::optional` values via the `value` method will throw an exception. Such operation can result in a crash when the exception isn't handled. This check will attempt to find cases where a `std::optional` isn't checked for emptiness before unwrapping it via the `value` method. You can enable [C26829](../code-quality/c26829.md), and [C26859](../code-quality/c26859.md) only for a more permissive analysis. + +## Example + +```cpp +std::optional getOptional(); + +void f(std::optional maybeEmpty) +{ + if (maybeEmpty) + maybeEmpty.value() = 42; // No warning + maybeEmpty.value() = 5; // warning: C26860 + std::optional o = getOptional(); + o.value() = 42; // warning: C26860 +} +``` + +To solve this problem, make sure the code never unwraps an empty optional. diff --git a/docs/code-quality/c26861.md b/docs/code-quality/c26861.md new file mode 100644 index 00000000000..2346fa7afdc --- /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 00000000000..f56e78753c9 --- /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 00000000000..169368c8df7 --- /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 00000000000..0df5d94644e --- /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/c26865.md b/docs/code-quality/c26865.md new file mode 100644 index 00000000000..0e9bd9d213a --- /dev/null +++ b/docs/code-quality/c26865.md @@ -0,0 +1,54 @@ +--- +description: "Learn more about: Warning C26865" +title: Warning C26865 +ms.date: 10/03/2022 +f1_keywords: ["C26865", "ALLOCATION_DEALLOCATION_MISMATCH", "__WARNING_ALLOCATION_DEALLOCATION_MISMATCH"] +helpviewer_keywords: ["C26865"] +ms.assetid: 2fbe9dc5-fa43-47b9-97a7-3f8215da1d40 +--- +# Warning C26865 + +> Memory allocated with '\' is being deallocated with '\'. Use '\' instead. + +This rule was added in Visual Studio 2026 18.0. + +## Remarks + +This warning indicates that the memory was allocated with one family of allocation functions, but was freed with a deallocation function from a different family. This usage results in undefined behavior according to C/C++ and the Microsoft MSVC implementation. + +The exact ramifications of this defect are difficult to predict. It might result in leaks for classes with destructors that perform memory deallocation. It could cause inconsistent behavior for classes with destructors that perform semantically significant operations, or memory corruptions and crashes. In other cases the mismatch might be unimportant, depending on the implementation of the compiler and its libraries. Analysis tools can't always distinguish between these situations. + +If memory is allocated with one family of allocation functions, it should be freed with a matching deallocation function. + +C26865 covers the following allocation/deallocation pairs: + +- C++ scalar new (`new`) must be deallocated with scalar delete (`delete`). +- C++ array new (`new[]`) must be deallocated with array delete (`delete[]`). +- C/C++ `malloc`/`calloc`/`realloc` must be deallocated with `free` (or `realloc`). +- Windows `HeapAlloc` must be deallocated with `HeapFree`. +- Windows `GlobalAlloc` must be deallocated with `GlobalFree`. +- Windows `LocalAlloc` must be deallocated with `LocalFree`. +- Windows `MIDL_user_allocate` must be deallocated with `MIDL_user_free`. +- Component Object Model (COM) `CoTaskMemAlloc` must be deallocated with `CoTaskMemFree`. + +Code analysis name: `ALLOCATION_DEALLOCATION_MISMATCH` + +## Example + +The following sample code generates warning C26865: + +```cpp +void f() { + int *pInt = (int *)calloc(10, sizeof(int)); + // code ... + delete pInt; // C26865: Memory allocated with 'calloc' is being deallocated with 'delete'. Use 'free' instead. +} + +void g() { + char * str = new char[50]; + // code ... + delete str; // C26865: Memory allocated with 'new[]' is being deallocated with 'delete'. Use 'delete[]' instead. +} +``` + +Manual memory management has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These mechanisms include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c28020.md b/docs/code-quality/c28020.md index e94476bc7d6..927e462bda8 100644 --- a/docs/code-quality/c28020.md +++ b/docs/code-quality/c28020.md @@ -1,16 +1,32 @@ --- -description: "Learn more about: C28020" -title: C28020 -ms.date: 11/04/2016 -ms.topic: reference +title: Warning C28020 +description: "Learn more about: Warning C28020" +ms.date: 03/25/2025 f1_keywords: ["C28020"] helpviewer_keywords: ["C28020"] -ms.assetid: 3612185a-0858-4ba9-b795-4a0681073cf7 --- -# C28020 +# Warning C28020 -> warning C28020: The expression \ is not true at this call +> The expression '*expr*' is not true at this call. -This warning is reported when the \_Satisfies\_ expression listed is not true. Frequently this indicates an incorrect parameter. +This warning is reported when the `_Satisfies_` expression listed isn't true. Frequently, the warning indicates an incorrect parameter. -If this occurs on a function declaration, the annotations indicate an impossible condition. +If this warning occurs on a function declaration, the annotations indicate an impossible condition. + +## Example + +The following example generates C28020: + +```cpp +#include + +int func(_In_range_(0, 10) int value) +{ + return value; +} + +int main() +{ + func(11); // C28020 +} +``` diff --git a/docs/code-quality/c28021.md b/docs/code-quality/c28021.md index d5162d3e0c0..bb8b0d3657d 100644 --- a/docs/code-quality/c28021.md +++ b/docs/code-quality/c28021.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28021" -title: C28021 +description: "Learn more about: Warning C28021" +title: Warning C28021 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28021"] helpviewer_keywords: ["C28021"] ms.assetid: 4cc205d2-d44d-4d44-9ece-0a4673617096 --- -# C28021 +# Warning C28021 -> warning C28021: The parameter \ being annotated with \ must be a pointer +> The parameter '*param*' being annotated with '*annotation*' must be a pointer -This warning is reported when the object being annotated is not a pointer type. This annotation cannot be used with **`void`** or integral types. +This warning is reported when the object being annotated is not a pointer type. This annotation can't be used with **`void`** or integral types. diff --git a/docs/code-quality/c28022.md b/docs/code-quality/c28022.md index 22ff0d3a26b..ebc089c6bc0 100644 --- a/docs/code-quality/c28022.md +++ b/docs/code-quality/c28022.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28022" -title: C28022 +description: "Learn more about: Warning C28022" +title: Warning C28022 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28022"] helpviewer_keywords: ["C28022"] ms.assetid: 9cef31e0-54f3-4b56-8c97-abb0ea1b98f7 --- -# C28022 +# Warning C28022 -> warning C28022: The function class(es) \ on this function do not match the function class(es) \ on the typedef used to define it. +> The function class(es) '*classlist1*' on this function do not match the function class(es) '*classlist2*' on the typedef used to define it. -This warning is reported when there is an error in the annotations. Both the typedef and the function itself have `_Function_class_` annotations, but they do not match. If both are used they must match. +This warning is reported when there's an error in the annotations. Both the typedef and the function itself have `_Function_class_` annotations, but they don't match. If both are used, they must match. diff --git a/docs/code-quality/c28023.md b/docs/code-quality/c28023.md index 52cc5029583..4daf46bd602 100644 --- a/docs/code-quality/c28023.md +++ b/docs/code-quality/c28023.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28023" -title: C28023 +description: "Learn more about: Warning C28023" +title: Warning C28023 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28023"] helpviewer_keywords: ["C28023"] ms.assetid: c59986a8-8712-4d58-b415-ec08b4daf66f --- -# C28023 +# Warning C28023 -> warning C28023: The function being assigned or passed should have a `_Function_class_` annotation for at least one of the class(es) in: \ +> The function being assigned or passed should have a `_Function_class_` annotation for at least one of the class(es) in: '*classlist*' -This warning is usually reported when only one function class is in use and a callback of the appropriate type is not declared. +This warning is often reported when only one function class is in use and a callback of the appropriate type isn't declared. -This warning is issued when the function on the left side of the assignment (or of the implied assignment, if this is a function call) is annotated to indicate that it is a driver-specific function type that uses the `_Function_class_` annotation or a typedef that contains such an annotation. The function on the right side of the assignment does not have a `_Function_class_` annotation. The function on the right should be annotated to be of the same type as the function on the left. This is usually best done by adding the declaration \ \ before the current first declaration of \. +This warning is issued when the function on the left side of the assignment (or of the implied assignment, if it's a function call) is annotated to indicate that it's a driver-specific function type that uses the `_Function_class_` annotation, or a typedef that contains such an annotation. The function on the right side of the assignment doesn't have a `_Function_class_` annotation. The function on the right should be annotated to be of the same type as the function on the left. Often the best approach is to place the declaration \ \ before the current first declaration of \. diff --git a/docs/code-quality/c28024.md b/docs/code-quality/c28024.md index e6ab50209ad..d99fce5b379 100644 --- a/docs/code-quality/c28024.md +++ b/docs/code-quality/c28024.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28024" -title: C28024 +description: "Learn more about: Warning C28024" +title: Warning C28024 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28024"] helpviewer_keywords: ["C28024"] ms.assetid: b74fad50-0a2e-43d7-ba5e-e9432aa9f7c8 --- -# C28024 +# Warning C28024 -> warning C28024: The function pointer being assigned to is annotated with the function class \, which is not contained in the function class(es) \. +> The function pointer being assigned to is annotated with the function class '*class*', which is not contained in the function class(es) '*classlist*'. -This warning is reported when both functions were annotated with a function class, but the classes do not match. +This warning is reported when both functions were annotated with a function class, but the classes don't match. -this warning is issued when a function pointer has a `_Function_class_` annotation that specifies that only functions of a particular functional class should be assigned to it. In an assignment or implied assignment in a function call, the source and target must be of the same function class, but the function classes do not match. +This warning is issued when a function pointer has a `_Function_class_` annotation that specifies that only functions of a particular functional class should be assigned to it. In an assignment or implied assignment in a function call, the source and target must be of the same function class, but the function classes don't match. diff --git a/docs/code-quality/c28039.md b/docs/code-quality/c28039.md index c58ae3a9b30..cd7fabc682f 100644 --- a/docs/code-quality/c28039.md +++ b/docs/code-quality/c28039.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28039" -title: C28039 +description: "Learn more about: Warning C28039" +title: Warning C28039 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28039"] helpviewer_keywords: ["C28039"] ms.assetid: 36cd63fe-1f0a-4f1c-a40b-5d52e22f19b3 --- -# C28039 +# Warning C28039 -> warning C28039: The type of actual parameter \ should exactly match the type \ +> The type of actual parameter '*operand*' should exactly match the type '*typename*' -This warning is usually reported when an enum formal was not passed a member of the enum, but may also be used for other types. +This warning is reported when an `enum` formal wasn't passed a member of the `enum`, but may also be used for other types. -Because C permits enums to be used interchangeably, and interchangeably with constants, it is easy to pass the wrong enum value to a function without an error. +Because C permits `enum` types to be used interchangeably, and interchangeably with constants, it's easy to pass the wrong `enum` value to a function without an error. -For enum types, if the type of an enum parameter is annotated with `_Enum_is_bitflag_`, arithmetic is permitted on the parameter. Otherwise the parameter must be of exactly the correct type. If a constant is strictly required, warning C28137 may also apply. +For `enum` types, if the type of an `enum` parameter is annotated with `_Enum_is_bitflag_`, arithmetic is permitted on the parameter. Otherwise the parameter must be of exactly the correct type. If a constant is strictly required, warning C28137 may also apply. This rule can be used for other parameter types as well; see the function documentation for why the types must match exactly. diff --git a/docs/code-quality/c28103.md b/docs/code-quality/c28103.md index dd3dc8e4239..0385a09b5e1 100644 --- a/docs/code-quality/c28103.md +++ b/docs/code-quality/c28103.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28103" -title: C28103 +description: "Learn more about: Warning C28103" +title: Warning C28103 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28103"] helpviewer_keywords: ["C28103"] ms.assetid: e39c464d-1049-4ff4-a62b-9cad9d3f6fee --- -# C28103 +# Warning C28103 -> warning C28103: Leaking resource +> Leaking resource -The specified object contains a resource that has not been freed. A function being called has been annotated with `__drv_acquiresResource` or `__drv_acquiresResourceGlobal` and this warning indicates that the resource named in the annotation was not freed. +The specified object contains a resource that hasn't been freed. A function being called has been annotated with `__drv_acquiresResource` or `__drv_acquiresResourceGlobal` and this warning indicates that the resource named in the annotation wasn't freed. ## Example @@ -31,4 +30,4 @@ if (NT_SUCCESS(res)) } ``` -If this warning is reported as a false positive, the most likely cause is that the function that releases the resource is not annotated with `__drv_releasesResource` or `__drv_releasesResourceGlobal`. Note that if you are using wrapper functions for system functions, the wrapper functions should use the same annotations that the system functions do. Currently, many system functions are annotated in the model file, so the annotations are not visible in the header files. +If this warning is reported as a false positive, the most likely cause is that the function that releases the resource isn't annotated with `__drv_releasesResource` or `__drv_releasesResourceGlobal`. If you're using wrapper functions for system functions, the wrapper functions should use the same annotations that the system functions do. Currently, many system functions are annotated in the model file, so the annotations aren't visible in the header files. diff --git a/docs/code-quality/c28104.md b/docs/code-quality/c28104.md index 36a6681efc4..cc2b632cfe5 100644 --- a/docs/code-quality/c28104.md +++ b/docs/code-quality/c28104.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28104" -title: C28104 +description: "Learn more about: Warning C28104" +title: Warning C28104 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28104"] helpviewer_keywords: ["C28104"] ms.assetid: 0dda7e70-7c63-4b6b-a3fc-adad0815f7f4 --- -# C28104 +# Warning C28104 -> warning C28104: Resource that should have been acquired before function exit was not acquired +> Resource that should have been acquired before function exit was not acquired -A function that is intended to acquire a resource before it exits has exited without acquiring the resource. This warning indicates that the function is annotated with `__drv_acquiresResource` but does not return having actually acquired the resource. If this function is a wrapper function, a path through the function did not reach the wrapped function. If the failure to reach the wrapped function is because the function returned an error and did not actually acquire the resource, you might need to use a conditional annotation (`__drv_when`). +A function that is intended to acquire a resource before it exits has exited without acquiring the resource. This warning indicates that the function is annotated with `__drv_acquiresResource` but doesn't return having actually acquired the resource. If this function is a wrapper function, a path through the function didn't reach the wrapped function. If the failure to reach the wrapped function is because the function returned an error and didn't actually acquire the resource, you might need to use a conditional annotation (`__drv_when`). -If this function actually implements the acquisition of the resource, it might not be possible for PFD to detect that the resource is acquired. In that case, use a `#pragma` warning to suppress the error. You can probably place the `#pragma` on the line preceding the `{` that begins the function body. The calling functions still need the annotation, but the Code Analysis tool will not be able to detect that the resource was acquired. +If this function actually implements the acquisition of the resource, it might not be possible for PFD to detect that the resource is acquired. In that case, use a `#pragma` warning to suppress the error. You can probably place the `#pragma` on the line preceding the `{` that begins the function body. The calling functions still need the annotation, but the Code Analysis tool won't be able to detect that the resource was acquired. ## Example diff --git a/docs/code-quality/c28105.md b/docs/code-quality/c28105.md index 7cb9f248351..defa5234327 100644 --- a/docs/code-quality/c28105.md +++ b/docs/code-quality/c28105.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28105" -title: C28105 +description: "Learn more about: Warning C28105" +title: Warning C28105 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28105"] helpviewer_keywords: ["C28105"] ms.assetid: 5afdec78-30eb-470c-980f-93d0cb3e74cc --- -# C28105 +# Warning C28105 -> warning C28105: Leaking resource due to an exception +> Leaking resource due to an exception -The specified resource is not freed when an exception is raised. The statement specified by the path can raise an exception. This warning is similar to warning [C28103](../code-quality/c28103.md), except that in this case an exception is involved. +The specified resource isn't freed when an exception is raised. The statement specified by the path can raise an exception. This warning is similar to warning [C28103](../code-quality/c28103.md), except that in this case an exception is involved. ## Example diff --git a/docs/code-quality/c28106.md b/docs/code-quality/c28106.md index d99f64db6e7..4cad2d6efbb 100644 --- a/docs/code-quality/c28106.md +++ b/docs/code-quality/c28106.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28106" -title: C28106 +description: "Learn more about: Warning C28106" +title: Warning C28106 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28106"] helpviewer_keywords: ["C28106"] ms.assetid: 362ee78e-b1d8-4991-bfd0-c465d084bd58 --- -# C28106 +# Warning C28106 -> warning C28106: Variable already holds resource possibly causing leak +> Variable already holds resource possibly causing leak -A variable that contains a resource is used in a context in which a new value can be placed in the variable. If this occurs, the resource can be lost and not properly freed, causing a resource leak. +A variable that contains a resource is used in a context in which a new value can be placed in the variable. If such placement occurs, the original resource can be lost and not properly freed, causing a resource leak. ## Example diff --git a/docs/code-quality/c28107.md b/docs/code-quality/c28107.md index 3e1deff100e..4ccb0d2aa08 100644 --- a/docs/code-quality/c28107.md +++ b/docs/code-quality/c28107.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28107" -title: C28107 +description: "Learn more about: Warning C28107" +title: Warning C28107 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28107"] helpviewer_keywords: ["C28107"] ms.assetid: aa8158be-d3f4-4e7e-918b-b04a910ce658 --- -# C28107 +# Warning C28107 -> warning C28107: Resource must be held when calling function +> Resource must be held when calling function -A resource that the program must acquire before calling the function was not acquired when the function was called. As a result, the function call will fail. This warning is reported only when resources are acquired and released in the same function. +A resource that the program must acquire before calling the function wasn't acquired when the function was called. As a result, the function call will fail. This warning is reported only when resources are acquired and released in the same function. ## Example diff --git a/docs/code-quality/c28108.md b/docs/code-quality/c28108.md index ca0ffd3106f..c9df1a23cdb 100644 --- a/docs/code-quality/c28108.md +++ b/docs/code-quality/c28108.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28108" -title: C28108 +description: "Learn more about: Warning C28108" +title: Warning C28108 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28108"] helpviewer_keywords: ["C28108"] ms.assetid: 6b931114-640e-43ea-b781-cd256e9163c7 --- -# C28108 +# Warning C28108 -> warning C28108: Variable holds an unexpected resource +> Variable holds an unexpected resource The resource that the driver is using is in the expected C language type, but has a different semantic type. diff --git a/docs/code-quality/c28109.md b/docs/code-quality/c28109.md index 6a39e9d6b04..05c8bf6f3bd 100644 --- a/docs/code-quality/c28109.md +++ b/docs/code-quality/c28109.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28109" -title: C28109 +description: "Learn more about: Warning C28109" +title: Warning C28109 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28109"] helpviewer_keywords: ["C28109"] ms.assetid: 32e4a493-8a51-4b27-b599-6271cd8d834a --- -# C28109 +# Warning C28109 -> warning C28109: Variable cannot be held at the time function is called +> Variable cannot be held at the time function is called -The program is holding a resource that should not be held when it is calling this function. Typically, it indicates that the resource was unintentionally acquired twice. The Code Analysis tool reports this warning when resources are acquired and released in the same function. +The program is holding a resource that shouldn't be held when it's calling this function. Typically, it indicates that the resource was unintentionally acquired twice. The Code Analysis tool reports this warning when resources are acquired and released in the same function. ## Example diff --git a/docs/code-quality/c28112.md b/docs/code-quality/c28112.md index 44278db5a4f..61e0a5588ee 100644 --- a/docs/code-quality/c28112.md +++ b/docs/code-quality/c28112.md @@ -1,34 +1,41 @@ --- -description: "Learn more about: C28112" -title: C28112 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28112"] +title: Warning C28112 +description: "Learn more about: Warning C28112" +ms.date: 08/25/2022 +f1_keywords: ["C28112", "INTERLOCKED_ACCESS", "__WARNING_INTERLOCKED_ACCESS"] helpviewer_keywords: ["C28112"] -ms.assetid: 2720a5dc-84e9-4f78-a8c7-a320c9f9216b --- -# C28112 +# Warning C28112 -> warning C28112: A variable which is accessed via an Interlocked function must always be accessed via an Interlocked function +> A variable (*parameter-name*) which is accessed via an Interlocked function must always be accessed via an Interlocked function. See line *line-number*: It is not always safe to access a variable which is accessed via the Interlocked\* family of functions in any other way. -See line *[number]*: It is not always safe to access a variable which is accessed via the Interlocked\* family of functions in any other way. +A variable that is accessed by using the Interlocked executive support routines, such as InterlockedCompareExchangeAcquire, is later accessed by using a different function. -A variable that is accessed by using the Interlocked executive support routines, such as InterlockedCompareExchangeAcquire, is later accessed by using a different function. Although certain ordinary assignments, accesses, and comparisons to variables that are used by the Interlocked\* routines can be safely accessed by using a different function, the risk is great enough to justify examining each instance. +## Remarks + +`InterlockedXxx` functions are intended to provide atomic operations, but are only atomic with respect to other `InterlockedXxx` functions. Although certain ordinary assignments, accesses, and comparisons to variables that are used by the Interlocked\* routines can be safely accessed by using a different function, the risk is great enough to justify examining each instance. + +Code analysis name: `INTERLOCKED_ACCESS` ## Example -The following code example generates this warning: +The following code generates this warning: ```cpp -inter_var --; -... +inter_var--; +//code InterlockedIncrement(&inter_var); ``` -The following code example avoids this warning: +The following code corrects this warning by strictly accessing `inter_var` through `InterlockedXxx` functions: ```cpp InterlockedDecrement(&inter_var); -... +//code InterlockedIncrement(&inter_var); ``` + +## See also + +[InterlockedIncrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockedincrement)\ +[InterlockedDecrement function (wdm.h)](/windows-hardware/drivers/ddi/wdm/nf-wdm-interlockeddecrement) diff --git a/docs/code-quality/c28113.md b/docs/code-quality/c28113.md index 6b43e2ebba5..984d5cf84fd 100644 --- a/docs/code-quality/c28113.md +++ b/docs/code-quality/c28113.md @@ -1,23 +1,22 @@ --- -description: "Learn more about: C28113" -title: C28113 +description: "Learn more about: Warning C28113" +title: Warning C28113 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28113"] helpviewer_keywords: ["C28113"] ms.assetid: c3f4f143-6985-4274-a87a-59c21a82d67a --- -# C28113 +# Warning C28113 -> warning C28113: Accessing a local variable via an Interlocked function +> Accessing a local variable via an Interlocked function The driver is using an Interlocked executive support routine, such as [InterlockedDecrement](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-interlockeddecrement), to access a local variable. -Although drivers are permitted to pass the address of a local variable to another function, and then use an interlocked function to operate on that variable, it's important to verify that the stack will not be swapped out to disk unexpectedly and that the variable has the correct life time across all threads that might use it. +Although drivers are permitted to pass the address of a local variable to another function, and then use an interlocked function to operate on that variable, it's important to verify that the stack won't be swapped out to disk unexpectedly and that the variable has the correct life time across all threads that might use it. ## Example -Typically, the return value of an Interlocked executive support routine is used in subsequent computations, instead of the input arguments. Also, the Interlocked routines only protect the first (leftmost) argument. Using an Interlocked routine in the following way does not protect the value of global and often serves no purpose. +Typically, the return value of an Interlocked executive support routine is used in subsequent computations, instead of the input arguments. Also, the Interlocked routines only protect the first (leftmost) argument. Using an Interlocked routine in the following way doesn't protect the value of global and often serves no purpose. ```cpp InterlockedExchange(&local, global) diff --git a/docs/code-quality/c28125.md b/docs/code-quality/c28125.md index 6027db0c13c..05ccc90635a 100644 --- a/docs/code-quality/c28125.md +++ b/docs/code-quality/c28125.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28125" -title: C28125 +description: "Learn more about: Warning C28125" +title: Warning C28125 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28125"] helpviewer_keywords: ["C28125"] ms.assetid: 3f7b8db4-6a64-4480-919e-3f3ceca7f948 --- -# C28125 +# Warning C28125 -> warning C28125: The function must be called from within a try/except block +> The function must be called from within a try/except block -The driver is calling a function that must be called from within a try/except block, such as [ProbeForRead](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforread), [ProbeForWrite](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforwrite), [MmProbeAndLockPages](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-mmprobeandlockpages). +The driver is calling a function that must be called from within a try/except block, such as [`ProbeForRead`](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforread), [`ProbeForWrite`](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-probeforwrite), or [`MmProbeAndLockPages`](/windows-hardware/drivers/ddi/content/wdm/nf-wdm-mmprobeandlockpages). ## Example diff --git a/docs/code-quality/c28137.md b/docs/code-quality/c28137.md index f4237d177bd..56969005883 100644 --- a/docs/code-quality/c28137.md +++ b/docs/code-quality/c28137.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28137" -title: C28137 +description: "Learn more about: Warning C28137" +title: Warning C28137 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28137"] helpviewer_keywords: ["C28137"] ms.assetid: 34420007-6a73-4f09-bdf7-8d923eef9654 --- -# C28137 +# Warning C28137 -> warning C28137: The variable argument should instead be a (literal) constant +> The variable argument should instead be a (literal) constant This warning is reported when a function call is missing a required (literal) constant. Consult the documentation for the function. diff --git a/docs/code-quality/c28138.md b/docs/code-quality/c28138.md index bc8db136a3d..03614ce4468 100644 --- a/docs/code-quality/c28138.md +++ b/docs/code-quality/c28138.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28138" -title: C28138 +description: "Learn more about: Warning C28138" +title: Warning C28138 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28138"] helpviewer_keywords: ["C28138"] ms.assetid: d8c455db-1fa0-426c-9846-545f1dfe57bd --- -# C28138 +# Warning C28138 -> warning C28138: The constant argument should instead be variable +> The constant argument should instead be variable This warning is reported in a function call that expects a variable or a non-constant expression, but the call includes a constant. For information about the function and its parameter, consult the WDK documentation of the function. @@ -29,4 +28,4 @@ To correct this warning, use a pointer to the port address. READ_PORT_UCHAR(PortAddress); ``` -There are a few older devices for which a constant parameter is acceptable with the READ_PORT and WRITE_PORT family of functions. When those devices receive this warning, the warning can be suppressed or ignored. However, any new devices should not assume a constant hardware address. +There are a few older devices for which a constant parameter is acceptable with the READ_PORT and WRITE_PORT family of functions. When those devices receive this warning, the warning can be suppressed or ignored. However, any new devices shouldn't assume a constant hardware address. diff --git a/docs/code-quality/c28159.md b/docs/code-quality/c28159.md index 99eb40a523e..05fbe31944d 100644 --- a/docs/code-quality/c28159.md +++ b/docs/code-quality/c28159.md @@ -1,34 +1,34 @@ --- -description: "Learn more about: C28159" -title: C28159 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28159"] +title: Warning C28159 +description: "Learn more about: Warning C28159" +ms.date: 09/08/2022 +f1_keywords: ["C28159", "USE_OTHER_FUNCTION", "__WARNING_USE_OTHER_FUNCTION"] helpviewer_keywords: ["C28159"] -ms.assetid: fab6cd58-0985-4ef6-89a2-64ed04297437 --- -# C28159 +# Warning C28159 -> warning C28159: Consider using another function instead. +> Consider using *`function_name_1`* instead of *`function_name_2`*. Reason: *reason* -This warning is reported for Drivers is suggesting that you use a preferred function call that is semantically equivalent to the function that the driver is calling. This is a general warning message; the annotation `__drv_preferredFunction` was used (possibly with a conditional a `__drv_when`() annotation) to flag a bad coding practice. +This warning occurs when you use a function that is semantically equivalent to an alternative, preferred function call. + +## Remarks + +C28159 is a general warning message; the annotation `__drv_preferredFunction` was used (possibly with a conditional `__drv_when`() annotation) to flag a bad coding practice. + +Code analysis name: `USE_OTHER_FUNCTION` ## Example -The following code example generates this warning: +The following code example generates this warning. This issue is due to the use of `OemToChar`, which doesn't validate the buffer size: ```cpp char buff[MAX_PATH]; - -// if strlen(input) > MAX_PATH -// leads to buffer overrun -OemToChar(buff, input); +OemToChar(buff, input); // If strlen(input) > MAX_PATH, this call leads to buffer overrun ``` -The following code example avoids this warning: +The following code example avoids this warning by using the recommended alternative `OemToCharBuff`, which takes in the destination buffer size and limits the copy appropriately: ```cpp char buff[MAX_PATH]; - OemToCharBuff(buff, input, MAX_PATH); ``` diff --git a/docs/code-quality/c28160.md b/docs/code-quality/c28160.md index 682724e3ca0..eeee7046da1 100644 --- a/docs/code-quality/c28160.md +++ b/docs/code-quality/c28160.md @@ -1,14 +1,18 @@ --- -description: "Learn more about: C28160" -title: C28160 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28160"] +title: Warning C28160 +description: "Learn more about: Warning C28160" +ms.date: 09/08/2022 +f1_keywords: ["C28160", "ERROR", "__WARNING_ERROR"] helpviewer_keywords: ["C28160"] -ms.assetid: cab15f6b-909c-4cc8-81a0-c24ac7c91c7c --- -# C28160 +# Warning C28160 -> warning C28160: Error annotation +> Error annotation: *reason* -This warning is reported when a `__drv_error` annotation has been encountered. This annotation is used to flag coding practices that should be fixed, and can be used with a `__drv_when` annotation to indicate specific combinations of parameters. +This warning is reported when a `__drv_error` annotation has been encountered. + +## Remarks + +This annotation is used to flag coding practices that should be fixed, and can be used with a `__drv_when` annotation to indicate specific combinations of parameters. + +Code analysis name: `ERROR` diff --git a/docs/code-quality/c28163.md b/docs/code-quality/c28163.md index 5ba3fb4600b..365185fab73 100644 --- a/docs/code-quality/c28163.md +++ b/docs/code-quality/c28163.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28163" -title: C28163 +description: "Learn more about: Warning C28163" +title: Warning C28163 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28163"] helpviewer_keywords: ["C28163"] ms.assetid: 24fecbde-1c96-4a45-82f7-9f47cfc0ef11 --- -# C28163 +# Warning C28163 -> warning C28163: The function should never be called from within a try/except block +> The function should never be called from within a try/except block This warning is reported when a function is of a type that should never be enclosed in a `try/except` block is found in a `try/except` block. The code analysis tool found at least one path in which the function called was within a `try/except` block. diff --git a/docs/code-quality/c28164.md b/docs/code-quality/c28164.md index 63b9cf0a5b8..8a79c33c961 100644 --- a/docs/code-quality/c28164.md +++ b/docs/code-quality/c28164.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C28164" -title: C28164 +description: "Learn more about: Warning C28164" +title: Warning C28164 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28164"] helpviewer_keywords: ["C28164"] ms.assetid: 13327bf3-3f12-4226-85cf-48e215d01c1d --- -# C28164 +# Warning C28164 -> warning C28164: The argument is being passed to a function that expects a pointer to an object (not a pointer to a pointer) +> The argument is being passed to a function that expects a pointer to an object (not a pointer to a pointer) This warning is reported when a pointer to a pointer is used in a call to a function that is expecting a pointer to an object. -The function takes a `PVOID` in this position. Usually, this indicates that `&pXXX` was used when `pXXX` is required. +The function takes a `PVOID` in this position. Usually, it indicates that `&pXXX` was used when `pXXX` is required. -Some *polymorphic functions* (functions that can evaluate to, and be applied to, values of different types) are implemented in C by using a `PVOID` argument that takes any pointer type. However, this allows the programmer to code a pointer to a pointer without causing a compiler error, even when this type is not appropriate. +Some *polymorphic functions* (functions that can evaluate to, and be applied to, values of different types) are implemented in C by using a `PVOID` argument that takes any pointer type. However, this allows the programmer to code a pointer to a pointer without causing a compiler error, even when this type isn't appropriate. ## Example diff --git a/docs/code-quality/c28182.md b/docs/code-quality/c28182.md index e48ff38521d..6a2ce93dfe4 100644 --- a/docs/code-quality/c28182.md +++ b/docs/code-quality/c28182.md @@ -1,27 +1,26 @@ --- -description: "Learn more about: C28182" -title: C28182 +description: "Learn more about: Warning C28182" +title: Warning C28182 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28182"] helpviewer_keywords: ["C28182"] ms.assetid: efec8b1f-8994-4a09-aaaf-6afaadfde883 --- -# C28182 +# Warning C28182 -> warning C28182: Dereferencing NULL pointer. +> Dereferencing NULL pointer. - **Additional information**: *\* contains the same NULL value as *\* did *\* + **Additional information**: *\* contains the same NULL value as *\* did. *\* The code analysis tool reports this warning when it confirms that the pointer can be NULL. If there are unconfirmed instances where the error might occur earlier in the trace, the code analysis tool adds the line number of the first instance to the warning message so that you can change the code to address all instances. - *\* is confirmed to be potentially NULL. *\* contains the same value as *pointer2* and is being dereferenced. Because these pointers may be at very different places in the code, both are reported so that you can determine why the code analysis tool is reporting this warning. + *\* is confirmed to be potentially NULL. *\* contains the same value as *pointer2* and is being dereferenced. Because these pointers may be at different places in the code, both are reported so that you can determine why the code analysis tool is reporting this warning. If an unconfirmed earlier instance of the condition exists, then *\* is replaced by this text: "See line *\* for an earlier location where this can occur." ## Examples -The following example shows code that could cause the code analysis tool to generate this warning message. In this example, the code analysis tool determines that `pNodeFree` is NULL in the **`if`** statement, and the code path into the body of the **`if`** is taken. However, because `nBlockSize` is potentially zero, the body of the **`for`** statement is not executed and `pNodeFree` is left unmodified. `pNodeFree` is then assigned to `pNode`, and `pNode` is used while a NULL dereference could occur. +The following example shows code that could cause the code analysis tool to generate this warning message. In this example, the code analysis tool determines that `pNodeFree` is NULL in the **`if`** statement, and the code path into the body of the **`if`** is taken. However, because `nBlockSize` is potentially zero, the body of the **`for`** statement isn't executed and `pNodeFree` is left unmodified. `pNodeFree` is then assigned to `pNode`, and `pNode` is used while a NULL dereference could occur. ```cpp typedef struct xlist { diff --git a/docs/code-quality/c28183.md b/docs/code-quality/c28183.md index b1860b17763..157f1571111 100644 --- a/docs/code-quality/c28183.md +++ b/docs/code-quality/c28183.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28183" -title: C28183 +description: "Learn more about: Warning C28183" +title: Warning C28183 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28183"] helpviewer_keywords: ["C28183"] ms.assetid: 50519e92-575a-4349-9167-5740f66933bf --- -# C28183 +# Warning C28183 -> warning C28183: The argument could be one value, and is a copy of the value found in the pointer +> The argument could be one value, and is a copy of the value found in the pointer -This warning indicates that this value is unexpected in the current context. This warning usually appears when a `NULL` value is passed as an argument to a function that does not permit it. The value was actually found in the specified variable, and the argument is a copy of that variable. +This warning indicates that this value is unexpected in the current context. This warning usually appears when a `NULL` value is passed as an argument to a function that doesn't permit it. The value was actually found in the specified variable, and the argument is a copy of that variable. -The Code Analysis tool reports this warning at the first point where it can definitively determine that the pointer is `NULL` or that it contains an illegal value. However, it is often the case that the error could actually occur earlier in the trace. When this happens, the Code Analysis tool will also give the line number of the first possible instance -- usually at a location where it could not definitively determine that the warning was appropriate. In those cases, the earlier location where this can occur is appended to the warning message. Typically, a code change should occur at or before that line number, rather than at the point of report. +The Code Analysis tool reports this warning at the first point where it can definitively determine that the pointer is `NULL` or that it contains an illegal value. However, it's often the case that the error could actually occur earlier in the trace. When it happens, the Code Analysis tool will also give the line number of the first possible instance, usually at a location where it couldn't definitively determine that the warning was appropriate. In those cases, the earlier location where it can occur is appended to the warning message. Typically, a code change should occur at or before that line number, rather than at the point of report. ## Example diff --git a/docs/code-quality/c28193.md b/docs/code-quality/c28193.md index f5f1f235080..858dad15588 100644 --- a/docs/code-quality/c28193.md +++ b/docs/code-quality/c28193.md @@ -1,25 +1,24 @@ --- -description: "Learn more about: C28193" -title: C28193 +description: "Learn more about: Warning C28193" +title: Warning C28193 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28193"] helpviewer_keywords: ["C28193"] ms.assetid: 1db205f2-618c-4285-98b5-641b3ad8f10f --- -# C28193 +# Warning C28193 -> warning C28193: The variable holds a value that must be examined +> The variable holds a value that must be examined -This warning indicates that the calling function is not checking the value of the specified variable, which was supplied by a function. The returned value is annotated with the `_Check_return_` annotation, but the calling function is either not using the value or is overwriting the value without examining it. +This warning indicates that the calling function isn't checking the value of the specified variable, which was supplied by a function. The returned value is annotated with the `_Check_return_` annotation, but the calling function is either not using the value or is overwriting the value without examining it. -This warning is similar to warning [C6031](../code-quality/c6031.md), but it is reported only when the code does not test or examine the value of the variable, such as by using it in a comparison. Simply assigning the value is not considered to be a sufficient examination to avoid this warning. Aliasing the result out of the function is considered a sufficient examination, but the result itself should be annotated with `_Check_return_`. +This warning is similar to warning [C6031](../code-quality/c6031.md), but it's reported only when the code doesn't test or examine the value of the variable, such as by using it in a comparison. Simply assigning the value isn't considered to be a sufficient examination to avoid this warning. Aliasing the result out of the function is considered a sufficient examination, but the result itself should be annotated with `_Check_return_`. -Certain functions (such as `strlen`) exist almost exclusively for their return value, so it makes sense for them to have the `_Check_return_` annotation. For these functions, the Code Analysis tool might report this warning when the return value is unused. This usually indicates that the code is incorrect, for example, it might contain residual code that could be deleted. However, in some rare instances, the return value is intentionally not used. The most common of these instances is where a string length is returned but not actually used before some other test is made. That other test causes a path to be simulated where the string length ends up being unused. When this happens, the code can be correct, but it might be inefficient. +Certain functions (such as `strlen`) exist almost exclusively for their return value, so it makes sense for them to have the `_Check_return_` annotation. For these functions, the Code Analysis tool might report this warning when the return value is unused. This warning usually indicates that the code is incorrect, for example, it might contain residual code that could be deleted. However, in some rare instances, the return value is intentionally not used. The most common of these instances is where a string length is returned but not actually used before some other test is made. That other test causes a path to be simulated where the string length ends up being unused. When this happens, the code can be correct, but it might be inefficient. There are two primary strategies for dealing with these cases where the return value is unused: -Reorder the code so that the string length is only returned along the path where it is needed. +Reorder the code so that the string length is only returned along the path where it's needed. Use a `#pragma` warning to suppress the warning--if by reordering the code, you would make the code too complex or otherwise less useful. diff --git a/docs/code-quality/c28194.md b/docs/code-quality/c28194.md index 76c040011a9..157b9863e7c 100644 --- a/docs/code-quality/c28194.md +++ b/docs/code-quality/c28194.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28194" -title: C28194 +description: "Learn more about: Warning C28194" +title: Warning C28194 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28194"] helpviewer_keywords: ["C28194"] ms.assetid: 311c9390-b056-4f6a-a06f-a4aded66df9f --- -# C28194 +# Warning C28194 -> warning C28194: The function was declared as aliasing the value in variable and exited without doing so +> The function was declared as aliasing the value in variable and exited without doing so -This warning indicates that the function prototype for the function being analyzed has a `__drv_isAliased` annotation, which indicates that it will *alias* the specified argument (that is, assign the value in a way that it will survive returning from the function). However, the function does not alias the argument along the path that is indicated by the annotation. Most functions that alias a variable save its value to a global data structure. +This warning indicates that the function prototype for the function being analyzed has a `__drv_isAliased` annotation, which indicates that it will *alias* the specified argument (that is, assign the value in a way that it will survive returning from the function). However, the function doesn't alias the argument along the path that is indicated by the annotation. Most functions that alias a variable save its value to a global data structure. diff --git a/docs/code-quality/c28195.md b/docs/code-quality/c28195.md index fd02628a582..c89ed73413a 100644 --- a/docs/code-quality/c28195.md +++ b/docs/code-quality/c28195.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28195" -title: C28195 +description: "Learn more about: Warning C28195" +title: Warning C28195 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28195"] helpviewer_keywords: ["C28195"] ms.assetid: 89524043-215e-4932-8079-ca2084d32963 --- -# C28195 +# Warning C28195 -> warning C28195: The function was declared as acquiring memory in a variable and exited without doing so +> The function was declared as acquiring memory in a variable and exited without doing so -This warning indicates that the function prototype for the function being analyzed has a `__drv_allocatesMem` annotation. The `__drv_allocatesMem` annotation indicates that the function acquires memory in the designated result location, but in at least one path, the function did not acquire the memory. Note that the Code Analysis tool will not recognize the actual implementation of a memory allocator (involving address arithmetic) and will not recognize that memory is allocated (although many wrappers will be recognized). In this case, the Code Analysis tool does not recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma` warning on the line that precedes the opening brace `{` of the function body +This warning indicates that the function prototype for the function being analyzed has a `__drv_allocatesMem` annotation. The `__drv_allocatesMem` annotation indicates that the function acquires memory in the designated result location, but in at least one path, the function didn't acquire the memory. The Code Analysis tool won't recognize the actual implementation of a memory allocator (involving address arithmetic) and won't recognize that memory is allocated (although many wrappers will be recognized). In this case, the Code Analysis tool doesn't recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma` warning on the line that precedes the opening brace `{` of the function body diff --git a/docs/code-quality/c28196.md b/docs/code-quality/c28196.md index a8571b9fedd..388766230a3 100644 --- a/docs/code-quality/c28196.md +++ b/docs/code-quality/c28196.md @@ -1,14 +1,53 @@ --- -description: "Learn more about: C28196" -title: C28196 +title: Warning C28196 +description: "Learn more about: Warning C28196" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28196"] +f1_keywords: ["C28196", "RETURNING_BAD_RESULT", "__WARNING_RETURNING_BAD_RESULT"] helpviewer_keywords: ["C28196"] -ms.assetid: 5ee89e96-2796-4316-a64c-702463ca1374 --- -# C28196 +# Warning C28196 -> warning C28196: The requirement is not satisfied. (The expression does not evaluate to true.) +> The requirement is not satisfied. (The expression does not evaluate to true.) -This warning indicates that the function prototype for the function being analyzed has a `__notnull`, `__null` or `__drv_valueIs` on an `_Out_` parameter or the return value, but the value returned is inconsistent with that annotation. +This warning indicates that the function being analyzed has a `__notnull`, `__null`, `__drv_valueIs` or similar annotation on an `_Out_` parameter or the return value, but the value returned is inconsistent with that annotation. + +## Remarks + +Annotations like `__notnull` describe invariants about `_Out_` parameters and return values, which serves both as documentation and as a sanity check for the author of the function. Warning C28196 indicates a mismatch between the annotations and the actual behavior of the function. The warning can be useful for discovering cases where a function might behave unexpectedly for certain input values. It's then up to the author to decide what the intended behavior of the function is and either adapt the annotations or the implementation accordingly. + +## Examples + +The following function causes warning C28196 because it's annotated with `_Ret_notnull_` even though some code paths return a null pointer. + +```cpp +#include + +_Ret_notnull_ +Item *get_item(_In_reads_(len) Item *items, size_t len, size_t index) { + if (index >= len) { + return nullptr; + } + + return items + index; +} +``` + +To resolve this issue, refine the annotation to accurately reflect the function's behavior. + +```cpp +#include + +_When_(index < len, _Ret_notnull_) +Item *get_item(_In_reads_(len) Item *items, size_t len, size_t index) { + if (index >= len) { + return nullptr; + } + + return items + index; +} +``` + +## See also + +[Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md)\ +[Specifying When and Where an Annotation Applies](./specifying-when-and-where-an-annotation-applies.md) diff --git a/docs/code-quality/c28197.md b/docs/code-quality/c28197.md index 13b11f6295a..0688cd6846d 100644 --- a/docs/code-quality/c28197.md +++ b/docs/code-quality/c28197.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: C28197" -title: C28197 +description: "Learn more about: Warning C28197" +title: Warning C28197 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28197"] helpviewer_keywords: ["C28197"] ms.assetid: b685f4c1-9bd1-4ca3-a2b6-6eb87877b5db --- -# C28197 +# Warning C28197 -> warning C28197: Possibly leaking memory +> Possibly leaking memory This warning is reported for both memory and resource leaks when the resource is potentially aliased to another location. -The *pointer* points to allocated memory or to another allocated resource that was not explicitly freed. This warning is usually due to inadequate annotations on the called function, although inadequate annotations on the calling function can also make this more likely. +The *pointer* points to allocated memory or to another allocated resource that wasn't explicitly freed. This warning is usually due to inadequate annotations on the called function, although inadequate annotations on the calling function can also make this warning more likely. -This warning can be reported on function exit if an input argument has a `__drv_freesMem` or `__drv_aliasesMem` annotation. This warning typically indicates either a valid leak or that a function called by the current function needs additional annotation. +This warning can be reported on function exit if an input argument has a `__drv_freesMem` or `__drv_aliasesMem` annotation. This warning typically indicates either a valid leak or that a function called by the current function needs more annotation. In particular, the absence of the basic `_In_` and `_Out_` annotations make this warning fairly likely, although the `__drv_aliasesMem` and `__drv_freesMem` annotations might be needed as well. A false positive is a likely result of a missing `_In_` annotation. diff --git a/docs/code-quality/c28198.md b/docs/code-quality/c28198.md index 89cdde546d3..56ee969a23b 100644 --- a/docs/code-quality/c28198.md +++ b/docs/code-quality/c28198.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28198" -title: C28198 +description: "Learn more about: Warning C28198" +title: Warning C28198 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28198"] helpviewer_keywords: ["C28198"] ms.assetid: 8bad4acb-712c-43f5-81d1-45d92092d4c5 --- -# C28198 +# Warning C28198 -> warning C28198: Possibly leaking memory due to an exception. +> Possibly leaking memory due to an exception. -This warning indicates that allocated memory is not being freed after an exception is raised. The statement at the end of the path can raise an exception. The memory was passed to a function that might have saved a copy to be freed later. +This warning indicates that allocated memory isn't being freed after an exception is raised. The statement at the end of the path can raise an exception. The memory was passed to a function that might have saved a copy to be freed later. -This warning is very similar to warning [C28197](../code-quality/c28197.md). The annotations that are recommended for use with warning [C28197](../code-quality/c28197.md) can also be used here. +This warning is similar to warning [C28197](../code-quality/c28197.md). The annotations that are recommended for use with warning [C28197](../code-quality/c28197.md) can also be used here. ## Example diff --git a/docs/code-quality/c28199.md b/docs/code-quality/c28199.md index 3a30c2beea1..46d9128a794 100644 --- a/docs/code-quality/c28199.md +++ b/docs/code-quality/c28199.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28199" -title: C28199 +description: "Learn more about: Warning C28199" +title: Warning C28199 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28199"] helpviewer_keywords: ["C28199"] ms.assetid: a1f0fb4a-65d6-4bd1-8b4f-8a7ae8c47123 --- -# C28199 +# Warning C28199 -> warning C28199: Using possibly uninitialized memory +> Using possibly uninitialized memory This message indicates that the variable has had its address taken but no assignment to it has been discovered. -The specified variable is being used without being explicitly initialized, but at some point its address was taken, indicating that it might be initialized invisibly to the Code Analysis tool. +The specified variable is used without being explicitly initialized, but at some point its address was taken, indicating that it might be initialized invisibly to the Code Analysis tool. This warning can be mistaken if the variable is initialized outside of the function. -The Code Analysis tool reports this warning on function exit if a parameter has an `_Out_` or `_Inout_` annotation and the variable is not initialized. +The Code Analysis tool reports this warning on function exit if a parameter has an `_Out_` or `_Inout_` annotation and the variable isn't initialized. diff --git a/docs/code-quality/c28202.md b/docs/code-quality/c28202.md index 9c91a1901c0..c8dfd3ce579 100644 --- a/docs/code-quality/c28202.md +++ b/docs/code-quality/c28202.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28202" -title: C28202 +description: "Learn more about: Warning C28202" +title: Warning C28202 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28202"] helpviewer_keywords: ["C28202"] ms.assetid: 05abbda7-c656-4f2b-bd4a-93805cf80a77 --- -# C28202 +# Warning C28202 -> warning C28202: Illegal reference to non-static member +> Illegal reference to non-static member -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c28203.md b/docs/code-quality/c28203.md index e2a46ab7727..33f43345e07 100644 --- a/docs/code-quality/c28203.md +++ b/docs/code-quality/c28203.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28203" -title: C28203 +description: "Learn more about: Warning C28203" +title: Warning C28203 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28203"] helpviewer_keywords: ["C28203"] ms.assetid: 20b98be6-0fc2-4712-9090-41201d80155e --- -# C28203 +# Warning C28203 -> warning C28203: Ambiguous reference to class member. Could be \ or \ +> Ambiguous reference to class member. Could be '*name1*' or '*name2*' -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c28204.md b/docs/code-quality/c28204.md index c33372c726a..aba49b5603f 100644 --- a/docs/code-quality/c28204.md +++ b/docs/code-quality/c28204.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28204" -title: C28204 +description: "Learn more about: Warning C28204" +title: Warning C28204 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28204"] helpviewer_keywords: ["C28204"] ms.assetid: e614e33f-4ba3-4c68-ae0c-3a667d64b044 --- -# C28204 +# Warning C28204 -> warning C28204: \ : Only one of this overload and the one at \(\) are annotated for \: both or neither must be annotated. +> \ : Only one of this overload and the one at '*filename*'('*line*') are annotated for '*paramname*': both or neither must be annotated. -This warning is reported when there is an error in the annotations. +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c28205.md b/docs/code-quality/c28205.md index 100f5143726..59f081c596f 100644 --- a/docs/code-quality/c28205.md +++ b/docs/code-quality/c28205.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28205" -title: C28205 +description: "Learn more about: Warning C28205" +title: Warning C28205 ms.date: 06/29/2022 -ms.topic: reference f1_keywords: ["C28205"] helpviewer_keywords: ["C28205"] ms.assetid: 3d802885-bdb8-47cb-9108-527a328a0774 --- -# C28205 +# Warning C28205 -> warning C28205: function> : `_Success_` or `_On_failure_` used in an illegal context +> '*function*': `_Success_` or `_On_failure_` used in an illegal context The `_Success_` and `_On_failure_` annotations can only be used on function return values. diff --git a/docs/code-quality/c28206.md b/docs/code-quality/c28206.md index 8a5f3de3dea..ed1a9f956e3 100644 --- a/docs/code-quality/c28206.md +++ b/docs/code-quality/c28206.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28206" -title: C28206 +description: "Learn more about: Warning C28206" +title: Warning C28206 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28206"] helpviewer_keywords: ["C28206"] ms.assetid: 27500f97-fe59-452c-8d9c-4258cb44764c --- -# C28206 +# Warning C28206 -> warning C28206: \ : left operand points to a struct, use `->` +> \ : left operand points to a struct, use `->` This warning is reported when the struct pointer dereference notation `->` was expected. diff --git a/docs/code-quality/c28207.md b/docs/code-quality/c28207.md index cdef20f96f1..5bba7531ec4 100644 --- a/docs/code-quality/c28207.md +++ b/docs/code-quality/c28207.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28207" -title: C28207 +description: "Learn more about: Warning C28207" +title: Warning C28207 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28207"] helpviewer_keywords: ["C28207"] ms.assetid: 057d88cf-d3c7-4d70-9d3a-f3b1b4d194ff --- -# C28207 +# Warning C28207 -> warning C28207: \: left operand is a struct, use . +> \: left operand is a struct, use . This warning is reported when a struct dereference dot (.) was expected. diff --git a/docs/code-quality/c28208.md b/docs/code-quality/c28208.md index ce205b2e404..6d352f4247b 100644 --- a/docs/code-quality/c28208.md +++ b/docs/code-quality/c28208.md @@ -1,14 +1,39 @@ --- -description: "Learn more about: C28208" -title: C28208 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28208"] +title: Warning C28208 +description: "Learn more about: Warning C28208" +ms.date: 10/03/2022 +f1_keywords: ["C28208", "FUNCTION_TYPE_REDECLARATION", "__WARNING_FUNCTION_TYPE_REDECLARATION"] helpviewer_keywords: ["C28208"] -ms.assetid: e9a8ce37-3b05-4202-b078-5570ae496d1d --- -# C28208 +# Warning C28208 -> warning C28208: Function \ was previously defined with a different parameter list at \(\). Some analysis tools will yield incorrect results +> Function *function_name* was previously defined with a different parameter list at *file_name*(*line_number*). Some analysis tools will yield incorrect results -This warning is reported when a function's known definition doesn't match another occurrence. +## Remarks + +This warning almost always accompanies [Compiler Warning (level 1) C4028](../error-messages/compiler-warnings/compiler-warning-level-1-c4028.md). Both warn of a mismatch between the parameters of a function's declaration and its definition. However, this specific error indicates a more niche case than C4028. C28208 indicates not only that a mismatch exists, but that it also can cause issues with analysis tools. This warning most notably occurs when the mismatch exists between a `typedef` function pointer and the definition of that function. This warning is demonstrated in the example below. + +Code analysis name: `FUNCTION_TYPE_REDECLARATION` + +## Example + +The following code generates C28208. `test_type` declares `my_test1` and `my_test2` to take a `void*` parameter, but the definition of `my_test1` takes an `int*` parameter instead. `my_test2` avoids this issue because the definition parameters match the declaration parameters. + +```cpp +// c28208_example.h +typedef void test_type(void*); +``` + +```cpp +// c28208_example.cpp +#include "c28208_example.h" +test_type my_test1; +test_type my_test2; +void my_test1(int* x){} // Generates C28208 +void my_test2(void* x){} // Doesn't generate C28208 + +int main() +{ + // Code +} +``` diff --git a/docs/code-quality/c28209.md b/docs/code-quality/c28209.md index 87d2f04d3a1..461e21a7b9a 100644 --- a/docs/code-quality/c28209.md +++ b/docs/code-quality/c28209.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28209" -title: C28209 +description: "Learn more about: Warning C28209" +title: Warning C28209 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28209"] helpviewer_keywords: ["C28209"] ms.assetid: 245b5fa5-ef64-4c2b-b469-35e184a1fc7d --- -# C28209 +# Warning C28209 -> warning C28209: The declaration for symbol has a conflicting declaration +> The declaration for symbol has a conflicting declaration This warning indicates an incorrectly constructed annotation declaration. This warning should never occur in normal use. diff --git a/docs/code-quality/c28210.md b/docs/code-quality/c28210.md index ba55995c441..4a3ca1068d5 100644 --- a/docs/code-quality/c28210.md +++ b/docs/code-quality/c28210.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28210" -title: C28210 +description: "Learn more about: Warning C28210" +title: Warning C28210 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28210"] helpviewer_keywords: ["C28210"] ms.assetid: 653ed499-2b51-413b-b510-e3bc842981b4 --- -# C28210 +# Warning C28210 -> warning C28210: Annotations for the `_On_failure_` context must not be in explicit pre context +> Annotations for the `_On_failure_` context must not be in explicit pre context -Annotations `_On_failure_` must be explicitly or implicitly indicated in `__post` context, that is, to be applied after the function returns. Use `_drv_out` to ensure this. +Annotations `_On_failure_` must be explicitly or implicitly indicated in `__post` context, that is, to be applied after the function returns. Use `_drv_out` to ensure this annotation is indicated. diff --git a/docs/code-quality/c28211.md b/docs/code-quality/c28211.md index 8486bf15c92..30c7b1f97d2 100644 --- a/docs/code-quality/c28211.md +++ b/docs/code-quality/c28211.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28211" -title: C28211 +description: "Learn more about: Warning C28211" +title: Warning C28211 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28211"] helpviewer_keywords: ["C28211"] ms.assetid: ce14ba26-daaf-47e0-940f-60073faa93b0 --- -# C28211 +# Warning C28211 -> warning C28211: Static context name expected for SAL_context +> Static context name expected for SAL_context This warning indicates that the operand to the `_Static_context_` annotation must be the name of a tool-defined context. This warning should never occur in normal use. diff --git a/docs/code-quality/c28212.md b/docs/code-quality/c28212.md index dcae67f520d..e9231b8147a 100644 --- a/docs/code-quality/c28212.md +++ b/docs/code-quality/c28212.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28212" -title: C28212 +description: "Learn more about: Warning C28212" +title: Warning C28212 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28212"] helpviewer_keywords: ["C28212"] ms.assetid: 77046589-0135-490a-b760-a0b9a962c665 --- -# C28212 +# Warning C28212 -> warning C28212: Pointer expression expected for annotation +> Pointer expression expected for annotation This warning indicates that the numbered parameter to an annotation (not the function being annotated) is expected to be a pointer or array type, but some other type was encountered. The annotation needs to be corrected. diff --git a/docs/code-quality/c28213.md b/docs/code-quality/c28213.md index 587d95bb326..0703a653b85 100644 --- a/docs/code-quality/c28213.md +++ b/docs/code-quality/c28213.md @@ -1,45 +1,72 @@ --- -description: "Learn more about: C28213" -title: C28213 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28213"] +description: "Learn more about: Warning C28213" +title: Warning C28213 +ms.date: 02/07/2023 +f1_keywords: ["C28213", "BAD_USEHEADER", "__WARNING_BAD_USEHEADER"] helpviewer_keywords: ["C28213"] -ms.assetid: e141a12a-4c46-47eb-aa9d-a6444472cfaa --- -# C28213 +# Warning C28213 -> warning C28213: The `_Use_decl_annotations_` annotation must be used to reference, without modification, a prior declaration. +> The `_Use_decl_annotations_` annotation must be used to reference, without modification, a prior declaration. -`_Use_decl_annotations_` tells the compiler to use the annotations from an earlier declaration of the function. If no earlier declaration can be found, or if the current declaration makes changes to the annotations than this warning is emitted. +## Remarks -## Example +`_Use_decl_annotations_` tells the compiler to use the annotations from an earlier declaration of the function. If it can't find an earlier declaration, or if the current declaration makes changes to the annotations, it emits this warning. `_Use_decl_annotations_` also lets you remove all other annotations from the definition, and uses the declaration annotations for analysis of the function. + +This diagnostic is frequently a side effect of refactoring or fixing other warnings by adjusting the annotations on a function. To fix the issue, use the same annotations at the other locations. To determine the correct set of annotations, look at the behavior in the function definition. In most cases, this behavior is intentional and the annotations to the function should reflect it. For more information on SAL annotations, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +It's important for the annotations to match between the declarations and the definition of a function. When the analysis tools analyze the call site of the function, they use the declaration annotations. If the declaration and definition don't match, the static analysis tools may produce incorrect results. When you fix this warning, it's common for your changes to have cascading effects as the tool reanalyzes the source with updated information. + +If this diagnostic occurs because the analyzer couldn't find a previous declaration in the translation unit, the most likely cause is a missing `#include` directive. To resolve this issue when you intentionally don't include the header file, verify that the annotations in the declaration and definition match, and remove the `_Use_decl_annotations_` annotation. Be careful when you don't include a header file, as the two sets of annotations may get out of sync in the future. + +Code analysis name: `BAD_USEHEADER` + +## Examples + +The following code generates C28160. The `buffer` parameter annotation doesn't match between the two files. + +*From example.h:* ```cpp -// from example.h -void example_func(_Out_writes_(n) char* buffer, int n); +void addNullTerminate(_Out_writes_(n) char* buffer, int n); +``` + +*From example.cpp:* -// from example.cpp +```cpp _Use_decl_annotations_ -void example_func(_Out_writes_z_(n) char* buffer, int n) +void addNullTerminate(_Out_writes_z_(n) char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` -The `buffer` parameter annotation does not match between the two files. This can be fixed by either changing the annotation so they match at all locations, or by removing all annotations except `_Use_decl_annotations_` from the function definition. In this example `_Out_writes_z_` appears to be correct so we will move that to the function declaration in the header file. +Examine the function definition to determine what the correct annotations should be. In this case, `_Out_writes_z_(n)` appears to be correct, so we move that annotation to the function declaration in the header file. This change resolves the issue because the annotations in the declaration and definition now match. + +*From example.h:* ```cpp +void addNullTerminate(_Out_writes_z_(n) char* buffer, int n); +``` + +Now we can remove the buffer annotation on the definition to simplify future maintenance (although this step is optional). -// from example.h -void example_func(_Out_writes_z_(n) char* buffer, int n); +*From example.cpp:* -// from example.cpp +```cpp _Use_decl_annotations_ -void example_func(char* buffer, int n) +void addNullTerminate(char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` + +In real world code, it's not usually as clear which annotation is correct. For more information and guidance, see [using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +## See also + +[Rule sets for C++ code](./using-rule-sets-to-specify-the-cpp-rules-to-run.md)\ +[Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md)\ +[C28252](C28252.md)\ +[C28253](C28253.md)\ +[C28301](C28301.md) diff --git a/docs/code-quality/c28214.md b/docs/code-quality/c28214.md index 5dd26dcc4e7..63c2046d2e5 100644 --- a/docs/code-quality/c28214.md +++ b/docs/code-quality/c28214.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28214" -title: C28214 +description: "Learn more about: Warning C28214" +title: Warning C28214 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28214"] helpviewer_keywords: ["C28214"] ms.assetid: dceacf19-9813-4e4c-9aa3-889227a93e08 --- -# C28214 +# Warning C28214 -> warning C28214: Attribute parameter names must be p1...p9 +> Attribute parameter names must be p1...p9 This warning indicates that when you construct an annotation declaration, the parameter names are limited to p1...p9. This warning should never occur in normal use. diff --git a/docs/code-quality/c28215.md b/docs/code-quality/c28215.md index 74b5b4fbff6..8faccbd7cb2 100644 --- a/docs/code-quality/c28215.md +++ b/docs/code-quality/c28215.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28215" -title: C28215 +description: "Learn more about: Warning C28215" +title: Warning C28215 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28215"] helpviewer_keywords: ["C28215"] ms.assetid: 47f51185-66f8-4b9c-b614-1d275b388729 --- -# C28215 +# Warning C28215 -> warning C28215: The typefix cannot be applied to a parameter that already has a typefix +> The typefix cannot be applied to a parameter that already has a typefix -Applying a `__typefix` annotation to a parameter that already has that annotation is an error. The `__typefix` annotations are used only in a few special cases and this warning is not expected to be seen in normal use. +Applying a `__typefix` annotation to a parameter that already has that annotation is an error. The `__typefix` annotations are used only in a few special cases. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28216.md b/docs/code-quality/c28216.md index c6eec79b181..7b29988b810 100644 --- a/docs/code-quality/c28216.md +++ b/docs/code-quality/c28216.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28216" -title: C28216 +description: "Learn more about: Warning C28216" +title: Warning C28216 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28216"] helpviewer_keywords: ["C28216"] ms.assetid: 627f0280-915b-49b7-9086-43bd0835c919 --- -# C28216 +# Warning C28216 -> warning C28216: The \_Check\_return\_ annotation only applies to post-conditions for the specific function parameter. +> The \_Check\_return\_ annotation only applies to post-conditions for the specific function parameter. The `_Check_return_` annotation has been applied in a context other than `__post`; it may need a `__post` (or `__drv_out`) modifier, or it may be placed incorrectly. diff --git a/docs/code-quality/c28217.md b/docs/code-quality/c28217.md index 875eaae0827..48b1464978b 100644 --- a/docs/code-quality/c28217.md +++ b/docs/code-quality/c28217.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28217" -title: C28217 +description: "Learn more about: Warning C28217" +title: Warning C28217 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28217"] helpviewer_keywords: ["C28217"] ms.assetid: 681fc502-b4d2-45a2-8a9e-7323e6860626 --- -# C28217 +# Warning C28217 -> warning C28217: For function, the number of parameters to annotation does not match that found at file +> For function, the number of parameters to annotation does not match that found at file -The annotations on the current line and on the line in the message are inconsistent. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +The annotations on the current line and on the line in the message are inconsistent. This inconsistency shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28218.md b/docs/code-quality/c28218.md index 88ad73cf483..1347548f679 100644 --- a/docs/code-quality/c28218.md +++ b/docs/code-quality/c28218.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28218" -title: C28218 +description: "Learn more about: Warning C28218" +title: Warning C28218 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28218"] helpviewer_keywords: ["C28218"] ms.assetid: 3810c606-c43f-47e6-beee-a6ee089ab66a --- -# C28218 +# Warning C28218 -> warning C28218: For function parameter, the annotation's parameter does not match that found at file +> For function parameter, the annotation's parameter does not match that found at file -The annotations on the current line and on the line in the message are inconsistent. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +The annotations on the current line and on the line in the message are inconsistent. This inconsistency shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28219.md b/docs/code-quality/c28219.md index 04f38c2aa64..cfe7fed7c40 100644 --- a/docs/code-quality/c28219.md +++ b/docs/code-quality/c28219.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28219" -title: C28219 +description: "Learn more about: Warning C28219" +title: Warning C28219 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28219"] helpviewer_keywords: ["C28219"] ms.assetid: f8b4fca4-8bba-4720-ae79-f4619161a85e --- -# C28219 +# Warning C28219 -> warning C28219: Member of enumeration expected for annotation the parameter in the annotation +> Member of enumeration expected for annotation the parameter in the annotation -A parameter to an annotation is expected to be a member of the named **`enum`** type, and some other symbol was encountered; use a member of that **`enum`** type. This usually indicates an incorrectly coded annotation macro. +A parameter to an annotation is expected to be a member of the named **`enum`** type, and some other symbol was encountered; use a member of that **`enum`** type. This warning usually indicates an incorrectly coded annotation macro. diff --git a/docs/code-quality/c28220.md b/docs/code-quality/c28220.md index c2751bce117..e0c69848684 100644 --- a/docs/code-quality/c28220.md +++ b/docs/code-quality/c28220.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: C28220" -title: C28220 +description: "Learn more about: Warning C28220" +title: Warning C28220 ms.date: 12/17/2019 -ms.topic: reference f1_keywords: ["C28220"] helpviewer_keywords: ["C28220"] ms.assetid: 64ff46fe-7ce7-491a-b0bb-484500b0267a --- -# C28220 +# Warning C28220 -> warning C28220: Integer expression expected for annotation '\' +> Integer expression expected for annotation '*annotation*' -This warning indicates that an integer expression was expected as an annotation parameter, but an incompatible type was used instead. It can be caused by trying to use a SAL annotation macro that does not fit the current scenario. +This warning indicates that an integer expression was expected as an annotation parameter, but an incompatible type was used instead. It can be caused by trying to use a SAL annotation macro that doesn't fit the current scenario. ## Example @@ -28,7 +27,7 @@ void f(_In_reads_(last) const int *buffer, const int *last) } ``` -In this example the intent of the developer was to indicate that `buffer` would be read up to the `last` element. The `_In_reads_` annotation does not fix the scenario because it is used to indicate a buffer size in number of elements. The correct annotation here is `_In_reads_to_ptr_`, which indicates the end of the buffer with a pointer. +In this example, the intent of the developer was to indicate that `buffer` would be read up to the `last` element. The `_In_reads_` annotation doesn't fix the scenario because it's used to indicate a buffer size in number of elements. The correct annotation is `_In_reads_to_ptr_`, which indicates the end of the buffer with a pointer. If there was no `_to_ptr_` equivalent to the annotation used, then the warning could have been addressed by converting the `last` pointer into a size value with `(buffer - size)` in the annotation. diff --git a/docs/code-quality/c28221.md b/docs/code-quality/c28221.md index 5185aa210f7..c5983849aa8 100644 --- a/docs/code-quality/c28221.md +++ b/docs/code-quality/c28221.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28221" -title: C28221 +description: "Learn more about: Warning C28221" +title: Warning C28221 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28221"] helpviewer_keywords: ["C28221"] ms.assetid: 06277429-1c19-4729-8abc-69ae90eb1e4e --- -# C28221 +# Warning C28221 -> warning C28221: String expression expected for the parameter in the annotation +> String expression expected for the parameter in the annotation -This warning indicates that a parameter to an annotation is expected to be a string, and some other type was encountered. This usually indicates an incorrectly coded annotation macro and is not expected to be seen in normal use. +This warning indicates that a parameter to an annotation is expected to be a string, and some other type was encountered. This warning usually indicates an incorrectly coded annotation macro, and we don't expect it to be seen in normal use. diff --git a/docs/code-quality/c28222.md b/docs/code-quality/c28222.md index bfc44941f91..c3877869613 100644 --- a/docs/code-quality/c28222.md +++ b/docs/code-quality/c28222.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28222" -title: C28222 +description: "Learn more about: Warning C28222" +title: Warning C28222 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28222"] helpviewer_keywords: ["C28222"] ms.assetid: 28c21fab-ffa4-4153-8145-a2da2cb8fbe8 --- -# C28222 +# Warning C28222 -> warning C28222: \_Yes\_, \_No\_, or \_Maybe\_ expected for annotation +> \_Yes\_, \_No\_, or \_Maybe\_ expected for annotation -This warning indicates that a parameter to an annotation is expected to be one of the symbols `_Yes_`, `_No_`, or `_Maybe_`, and some other symbol was encountered. This usually indicates an incorrectly coded annotation macro. +This warning indicates that a parameter to an annotation is expected to be one of the symbols `_Yes_`, `_No_`, or `_Maybe_`, and some other symbol was encountered. This warning usually indicates an incorrectly coded annotation macro. diff --git a/docs/code-quality/c28223.md b/docs/code-quality/c28223.md index 09025bac07a..73e8c613f67 100644 --- a/docs/code-quality/c28223.md +++ b/docs/code-quality/c28223.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28223" -title: C28223 +description: "Learn more about: Warning C28223" +title: Warning C28223 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28223"] helpviewer_keywords: ["C28223"] ms.assetid: 4c1a2421-5846-46bb-bc39-5aa38e3760a5 --- -# C28223 +# Warning C28223 -> warning C28223: Did not find expected Token/identifier for annotation, parameter +> Did not find expected Token/identifier for annotation, parameter -This warning indicates that a parameter to an annotation is expected to be an identifier, and some other symbol was encountered. This usually indicates an incorrectly coded annotation macro. The use of C or C++ keywords in this position will cause this error. +This warning indicates that a parameter to an annotation is expected to be an identifier, and some other symbol was encountered. This warning usually indicates an incorrectly coded annotation macro. The use of C or C++ keywords in this position will cause this error. diff --git a/docs/code-quality/c28224.md b/docs/code-quality/c28224.md index 4fa26670c18..773c0fa54f1 100644 --- a/docs/code-quality/c28224.md +++ b/docs/code-quality/c28224.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28224" -title: C28224 +description: "Learn more about: Warning C28224" +title: Warning C28224 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28224"] helpviewer_keywords: ["C28224"] ms.assetid: 44d5c30f-46b2-463b-bf4f-038523b945a1 --- -# C28224 +# Warning C28224 -> warning C28224: Annotation requires parameters +> Annotation requires parameters -This warning indicates that the named annotation is used without parameters and at least one parameter is required. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +This warning indicates that the named annotation is used without parameters and at least one parameter is required. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in normal use. diff --git a/docs/code-quality/c28225.md b/docs/code-quality/c28225.md index b3d8d29e183..05a14b5d0c7 100644 --- a/docs/code-quality/c28225.md +++ b/docs/code-quality/c28225.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28225" -title: C28225 +description: "Learn more about: Warning C28225" +title: Warning C28225 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28225"] helpviewer_keywords: ["C28225"] ms.assetid: 8b5de42e-8969-46c0-a022-430f3135f707 --- -# C28225 +# Warning C28225 -> warning C28225: Did not find the correct number of required parameters in annotation +> Did not find the correct number of required parameters in annotation -This warning indicates that the named annotation is used with the incorrect number of parameters. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that the named annotation is used with the incorrect number of parameters. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28226.md b/docs/code-quality/c28226.md index d5711bd9adc..9609d7bd217 100644 --- a/docs/code-quality/c28226.md +++ b/docs/code-quality/c28226.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28226" -title: C28226 +description: "Learn more about: Warning C28226" +title: Warning C28226 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28226"] helpviewer_keywords: ["C28226"] ms.assetid: 2c1f1987-5012-413a-a268-12880e6024ee --- -# C28226 +# Warning C28226 -> warning C28226: Annotation cannot also be a PrimOp (in current declaration) +> Annotation cannot also be a PrimOp (in current declaration) -This warning indicates that the named annotation is being declared as a PrimOp, and also was previously declared as a normal annotation. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in normal use. +This warning indicates that the named annotation is being declared as a PrimOp, and also was previously declared as a normal annotation. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28227.md b/docs/code-quality/c28227.md index 57c16bec9b3..10012946237 100644 --- a/docs/code-quality/c28227.md +++ b/docs/code-quality/c28227.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28227" -title: C28227 +description: "Learn more about: Warning C28227" +title: Warning C28227 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28227"] helpviewer_keywords: ["C28227"] ms.assetid: be7b212b-41c2-45e8-85d1-807d86e92311 --- -# C28227 +# Warning C28227 -> warning C28227: Annotation cannot also be a PrimOp (see prior declaration) +> Annotation cannot also be a PrimOp (see prior declaration) -This warning indicates that the named annotation is being declared as an ordinary annotation, and also was previously declared as a PrimOp. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that the named annotation is being declared as an ordinary annotation, and also was previously declared as a PrimOp. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28228.md b/docs/code-quality/c28228.md index 954cf7cc777..9b7cc616991 100644 --- a/docs/code-quality/c28228.md +++ b/docs/code-quality/c28228.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28228" -title: C28228 +description: "Learn more about: Warning C28228" +title: Warning C28228 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28228"] helpviewer_keywords: ["C28228"] ms.assetid: 2e5aea19-808e-4489-9692-bcde046d8f55 --- -# C28228 +# Warning C28228 -> warning C28228: Annotation parameter: cannot use type in annotations +> Annotation parameter: cannot use type in annotations -This warning indicates that a parameter is of type that is not supported. Annotations can only use a limited set of types as parameters. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that a parameter is of type that isn't supported. Annotations can only use a limited set of types as parameters. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28229.md b/docs/code-quality/c28229.md index 90b33f4ccd3..d78ecc7d092 100644 --- a/docs/code-quality/c28229.md +++ b/docs/code-quality/c28229.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28229" -title: C28229 +description: "Learn more about: Warning C28229" +title: Warning C28229 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28229"] helpviewer_keywords: ["C28229"] ms.assetid: 29137cc9-81ac-416c-b56b-4ad9886d68f8 --- -# C28229 +# Warning C28229 -> warning C28229: Annotation does not support parameters +> Annotation does not support parameters -This warning indicates that an annotation was used with a parameter when the annotation is declared without parameters. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that an annotation was used with a parameter when the annotation is declared without parameters. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28230.md b/docs/code-quality/c28230.md index 67ca8b45374..2ec2e28c5e3 100644 --- a/docs/code-quality/c28230.md +++ b/docs/code-quality/c28230.md @@ -1,17 +1,16 @@ --- -title: C28230 +title: Warning C28230 description: "Understand the causes of Microsoft C/C++ code analysis warning C28230, and learn how to fix them." ms.date: 10/23/2020 -ms.topic: reference f1_keywords: ["C28230"] helpviewer_keywords: ["C28230"] ms.assetid: 124b17ed-ae47-42c7-bec5-e8e7210af899 --- -# C28230 +# Warning C28230 -> warning C28230: The type of parameter has no member. +> The type of parameter has no member. -This warning indicates that an argument to an annotation attempts to access a member of a **`struct`**, **`class`**, or **`union`** that does not exist. This warning will also be emitted if a parameter tries to call a member function of the object. +This warning indicates that an argument to an annotation attempts to access a member of a **`struct`**, **`class`**, or **`union`** that doesn't exist. This warning will also be emitted if a parameter tries to call a member function of the object. ## Example @@ -35,7 +34,7 @@ void f(_Out_writes_(value.usefulmember) int *buffer, MyStruct value) } ``` -In this example the spelling just needs to be corrected. +In this example, the spelling just needs to be corrected. ```cpp void f(_Out_writes_(value.usefulMember) int *buffer, MyStruct value) diff --git a/docs/code-quality/c28231.md b/docs/code-quality/c28231.md index 7836abf6b0c..6b410ce7436 100644 --- a/docs/code-quality/c28231.md +++ b/docs/code-quality/c28231.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28231" -title: C28231 +description: "Learn more about: Warning C28231" +title: Warning C28231 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28231"] helpviewer_keywords: ["C28231"] ms.assetid: d1cb9c55-5a4f-40c0-9908-9285cb78a50a --- -# C28231 +# Warning C28231 -> warning C28231: Annotation is only valid on array +> Annotation is only valid on array This warning indicates that an argument to an annotation should be an array, and some other type was encountered. diff --git a/docs/code-quality/c28232.md b/docs/code-quality/c28232.md index c4bcd148fe4..f72fd7a1717 100644 --- a/docs/code-quality/c28232.md +++ b/docs/code-quality/c28232.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28232" -title: C28232 +description: "Learn more about: Warning C28232" +title: Warning C28232 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28232"] helpviewer_keywords: ["C28232"] ms.assetid: c616b978-02fa-4a0b-8532-d4249369bca1 --- -# C28232 +# Warning C28232 -> warning C28232: \_Pre\_, \_Post\_, or \_Deref\_ not applied to any annotation +> \_Pre\_, \_Post\_, or \_Deref\_ not applied to any annotation -This warning indicates that a `_Pre_`, `_Post_`, or `_Deref_` operator appears in an annotation expression without a subsequent functional annotation; the modifier was ignored, but this indicates an incorrectly coded annotation. +This warning indicates that a `_Pre_`, `_Post_`, or `_Deref_` operator appears in an annotation expression without a subsequent functional annotation; the modifier was ignored, but this warning indicates an incorrectly coded annotation. diff --git a/docs/code-quality/c28233.md b/docs/code-quality/c28233.md index 1f3940d2e36..686c5efd513 100644 --- a/docs/code-quality/c28233.md +++ b/docs/code-quality/c28233.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C28233" -title: C28233 +description: "Learn more about: Warning C28233" +title: Warning C28233 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28233"] +f1_keywords: ["C28233", "BLOCK_QUALIFIER"] helpviewer_keywords: ["C28233"] ms.assetid: 07a6a54d-8da8-4a2a-aa7f-2cbd11f8fc9a --- -# C28233 +# Warning C28233 -> warning C28233: pre, post, or deref applied to a block +> Pre, post, or deref applied to a block diff --git a/docs/code-quality/c28234.md b/docs/code-quality/c28234.md index 5a945eb644e..f4a37123c1c 100644 --- a/docs/code-quality/c28234.md +++ b/docs/code-quality/c28234.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28234" -title: C28234 +description: "Learn more about: Warning C28234" +title: Warning C28234 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28234"] helpviewer_keywords: ["C28234"] ms.assetid: 5bd48232-3738-4d01-a48b-f3f57a288a6a --- -# C28234 +# Warning C28234 -> warning C28234: \_At\_ expression does not apply to current function +> \_At\_ expression does not apply to current function -This warning indicates that the value of an `_At_` expression does not identify an accessible object. +This warning indicates that the value of an `_At_` expression doesn't identify an accessible object. diff --git a/docs/code-quality/c28235.md b/docs/code-quality/c28235.md index 32b838c272c..664dbf6d0a8 100644 --- a/docs/code-quality/c28235.md +++ b/docs/code-quality/c28235.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28235" -title: C28235 +description: "Learn more about: Warning C28235" +title: Warning C28235 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28235"] helpviewer_keywords: ["C28235"] ms.assetid: 46e71e11-dda6-44b3-9f6e-8a3c956f7364 --- -# C28235 +# Warning C28235 -> warning C28235: The function cannot stand alone as an annotation +> The function cannot stand alone as an annotation -This warning indicates that an attempt was made to use a function that was not declared to be an annotation in an annotation context. This includes using a primitive operation (PrimOp) in a standalone context. This should not be possible if the standard macros are being used for annotations. This warning is not expected to be seen in typical use. +This warning indicates that an attempt was made to use a function that wasn't declared to be an annotation in an annotation context. This includes using a primitive operation (PrimOp) in a standalone context. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28236.md b/docs/code-quality/c28236.md index 5d225178652..b3641ad5e25 100644 --- a/docs/code-quality/c28236.md +++ b/docs/code-quality/c28236.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28236" -title: C28236 +description: "Learn more about: Warning C28236" +title: Warning C28236 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28236"] helpviewer_keywords: ["C28236"] ms.assetid: 6c2761fe-1121-4d54-b973-6c53f0f3080a --- -# C28236 +# Warning C28236 -> warning C28236: The annotation cannot be used in an expression +> The annotation cannot be used in an expression -This warning indicates that an attempt was made to use a function declared to be an annotation in an expression context. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning indicates that an attempt was made to use a function declared to be an annotation in an expression context. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28237.md b/docs/code-quality/c28237.md index f630bc8afc7..bcf0630a12e 100644 --- a/docs/code-quality/c28237.md +++ b/docs/code-quality/c28237.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28237" -title: C28237 +description: "Learn more about: Warning C28237" +title: Warning C28237 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28237"] helpviewer_keywords: ["C28237"] ms.assetid: d33cb4b6-a061-4927-bfab-e25e352af97b --- -# C28237 +# Warning C28237 -> warning C28237: The annotation on parameter is no longer supported +> The annotation on parameter is no longer supported -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28238.md b/docs/code-quality/c28238.md index 6051b95fd0a..325fb6ceccf 100644 --- a/docs/code-quality/c28238.md +++ b/docs/code-quality/c28238.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28238" -title: C28238 +description: "Learn more about: Warning C28238" +title: Warning C28238 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28238"] helpviewer_keywords: ["C28238"] ms.assetid: e2e67617-652d-44dd-aff7-cce25f81b9f1 --- -# C28238 +# Warning C28238 -> warning C28238: The annotation on parameter has more than one of value, stringValue, and longValue. Use paramn=xxx +> The annotation on parameter has more than one of value, stringValue, and longValue. Use paramn=xxx -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28239.md b/docs/code-quality/c28239.md index 8ad366263d8..0045271c938 100644 --- a/docs/code-quality/c28239.md +++ b/docs/code-quality/c28239.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28239" -title: C28239 +description: "Learn more about: Warning C28239" +title: Warning C28239 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28239"] helpviewer_keywords: ["C28239"] ms.assetid: 3b9aeb08-a538-4ab0-a52f-d9e5c9c6bf00 --- -# C28239 +# Warning C28239 -> warning C28239: The annotation on parameter has both value, stringValue, or longValue; and paramn=xxx. Use only paramn=xxx +> The annotation on parameter has both value, stringValue, or longValue; and paramn=xxx. Use only paramn=xxx -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28240.md b/docs/code-quality/c28240.md index 34411aae511..60fb884be56 100644 --- a/docs/code-quality/c28240.md +++ b/docs/code-quality/c28240.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28240" -title: C28240 +description: "Learn more about: Warning C28240" +title: Warning C28240 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28240"] helpviewer_keywords: ["C28240"] ms.assetid: fb40abdd-c082-4ee4-bbb1-cee3e089267a --- -# C28240 +# Warning C28240 -> warning C28240: The annotation on parameter has param2 but no param1 +> The annotation on parameter has param2 but no param1 -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28241.md b/docs/code-quality/c28241.md index 8975a1b6822..97d32e715c1 100644 --- a/docs/code-quality/c28241.md +++ b/docs/code-quality/c28241.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28241" -title: C28241 +description: "Learn more about: Warning C28241" +title: Warning C28241 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28241"] helpviewer_keywords: ["C28241"] ms.assetid: b8fc340d-84b7-43a9-bfb1-00845154939c --- -# C28241 +# Warning C28241 -> warning C28241: The annotation for function on parameter is not recognized +> The annotation for function on parameter is not recognized -An unrecognized annotation name was used. This should not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +An unrecognized annotation name was used. This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28243.md b/docs/code-quality/c28243.md index 2735d310c1f..c0e5087bf70 100644 --- a/docs/code-quality/c28243.md +++ b/docs/code-quality/c28243.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28243" -title: C28243 +description: "Learn more about: Warning C28243" +title: Warning C28243 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28243"] helpviewer_keywords: ["C28243"] ms.assetid: a5c57acc-704b-45fe-bed2-4eb1aa8d3d8f --- -# C28243 +# Warning C28243 -> warning C28243: The annotation for function on parameter requires more dereferences than the actual type annotated allows +> The annotation for function on parameter requires more dereferences than the actual type annotated allows The number of `__deref` operators on an annotation is more than the number of levels of pointer defined by the parameter type. Correct this warning by changing either the number in the annotation or the pointer levels of the parameter referenced. diff --git a/docs/code-quality/c28244.md b/docs/code-quality/c28244.md index fdb12ce5f10..ddd7f5dc0a4 100644 --- a/docs/code-quality/c28244.md +++ b/docs/code-quality/c28244.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28244" -title: C28244 +description: "Learn more about: Warning C28244" +title: Warning C28244 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28244"] helpviewer_keywords: ["C28244"] ms.assetid: 9fc03940-0810-4693-a1cd-1e03b4681fb9 --- -# C28244 +# Warning C28244 -> warning C28244: The annotation for function has an unparseable parameter/external annotation +> The annotation for function has an unparseable parameter/external annotation -This should currently not be possible if the standard macros are being used for annotations; this warning is not expected to be seen in typical use. +This warning shouldn't be possible if the standard macros are being used for annotations. We don't expect this warning to be seen in typical use. diff --git a/docs/code-quality/c28245.md b/docs/code-quality/c28245.md index 861a2dc449f..1f8bf3ce22f 100644 --- a/docs/code-quality/c28245.md +++ b/docs/code-quality/c28245.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28245" -title: C28245 +description: "Learn more about: Warning C28245" +title: Warning C28245 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28245"] helpviewer_keywords: ["C28245"] ms.assetid: fabd3338-51f4-4b81-a333-e4fed203bc72 --- -# C28245 +# Warning C28245 -> warning C28245: The annotation for function annotates 'this' on a non-member-function +> The annotation for function annotates 'this' on a non-member-function -An internal error has occurred in the PREfast model file. This warning should not occur in typical use. +An internal error has occurred in the PREfast model file. This warning shouldn't occur in typical use. diff --git a/docs/code-quality/c28246.md b/docs/code-quality/c28246.md index cbefa3f8608..abf7d57ad7d 100644 --- a/docs/code-quality/c28246.md +++ b/docs/code-quality/c28246.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28246" -title: C28246 +description: "Learn more about: Warning C28246" +title: Warning C28246 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28246"] helpviewer_keywords: ["C28246"] ms.assetid: 66a297ab-19fc-4985-8738-0a92f8d1d5cc --- -# C28246 +# Warning C28246 -> warning C28246: The annotation for function '\' - parameter '\' does not match the type of the parameter +> The annotation for function '*name*' - parameter '*parameter*' does not match the type of the parameter -A __deref operator was applied to a non-pointer type when creating an annotation. +A `__deref` operator was applied to a non-pointer type when creating an annotation. diff --git a/docs/code-quality/c28250.md b/docs/code-quality/c28250.md index 92e878e5072..f67dd8deadd 100644 --- a/docs/code-quality/c28250.md +++ b/docs/code-quality/c28250.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: C28250" -title: C28250 +description: "Learn more about: Warning C28250" +title: Warning C28250 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28250"] helpviewer_keywords: ["C28250"] ms.assetid: 8f405533-fbc3-4ba6-b169-a4c9288acd9a --- -# C28250 +# Warning C28250 -> warning C28250: Inconsistent annotation for function: the prior instance has an error. +> Inconsistent annotation for function: the prior instance has an error. Note: There are several prototypes for this function. This warning compares the first prototype with instance number \. If a declaration is made using a **`typedef`**, the line where the **`typedef`** appears is more useful than the line of the declaration. -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, each declaration is checked pairwise. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, each declaration is checked pairwise. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28251.md b/docs/code-quality/c28251.md index 9842467750d..3139b8bd873 100644 --- a/docs/code-quality/c28251.md +++ b/docs/code-quality/c28251.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28251" -title: C28251 +description: "Learn more about: Warning C28251" +title: Warning C28251 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28251"] helpviewer_keywords: ["C28251"] ms.assetid: 9335ad9a-4650-41d2-a2c2-0474d7346472 --- -# C28251 +# Warning C28251 -> warning C28251: Inconsistent annotation for function: this instance has an error +> Inconsistent annotation for function: this instance has an error -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, then each declaration is checked in groups of two. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, then each declaration is checked in groups of two. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The *text* field above contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28252.md b/docs/code-quality/c28252.md index 0a863defa70..81586e5f4c8 100644 --- a/docs/code-quality/c28252.md +++ b/docs/code-quality/c28252.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28252" -title: C28252 +description: "Learn more about: Warning C28252" +title: Warning C28252 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28252"] helpviewer_keywords: ["C28252"] ms.assetid: 58407fc3-ef27-4905-bc03-caf07b907cc4 --- -# C28252 +# Warning C28252 -> warning C28252: Inconsistent annotation for function: parameter has another annotation on this instance +> Inconsistent annotation for function: parameter has another annotation on this instance -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, then each declaration is checked in groups of two. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, then each declaration is checked in groups of two. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28253.md b/docs/code-quality/c28253.md index 2bd42879179..6dfd0c46862 100644 --- a/docs/code-quality/c28253.md +++ b/docs/code-quality/c28253.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: C28253" -title: C28253 +description: "Learn more about: Warning C28253" +title: Warning C28253 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28253"] helpviewer_keywords: ["C28253"] ms.assetid: df049e53-aab7-4914-b5f6-81ebe8ee989b --- -# C28253 +# Warning C28253 -> warning C28253: Inconsistent annotation for function: parameter has another annotations on this instance +> Inconsistent annotation for function: parameter has another annotations on this instance -This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match those on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. +This warning refers to an error in the annotation and reflects the requirement that the annotations on a function declaration must match the ones on the definition, except if a function **`typedef`** is involved. In that case, the function **`typedef`** is taken as definitive for both the declaration and the definition. -Note that annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield a number of unmatched low-level annotations. It is best to simply compare the declaration and definition source code to make sure that they are the same. (Trivial differences in the order of the annotations are not reported.) +Annotations are usually implemented as macros, and one macro will usually yield several low-level annotations. This warning is reported for each unmatched low-level annotation, so a single unmatched annotation macro may yield many unmatched low-level annotations. It's best to compare the declaration and definition source code to make sure that they're the same. (Trivial differences in the order of the annotations aren't reported.) -The comparison is always between the first declaration found and the current one. If there are additional declarations, then each declaration is checked in groups of two. It is currently not possible to do a comparison other than in pairs, although it is possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. +The comparison is always between the first declaration found and the current one. If there are more declarations, then each declaration is checked in groups of two. It's currently not possible to do a comparison other than in pairs, although it's possible to identify that there are more than two declarations/definitions. The error message contains a list of the annotations that differ (at a fairly low level) between the two instances. -This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you do not need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. +This warning message displays the text of the underlying code sent to the compiler, and not the macros that are used to actually insert the annotation in the source code (as is the case whenever macros are used). In general, you don't need to understand the low-level annotations, but you should recognize that the annotations are being reported as inconsistent between the line numbers reported in the error message. Mostly, an inspection of the source code will make it clear why the inconsistency exists. diff --git a/docs/code-quality/c28254.md b/docs/code-quality/c28254.md index 8196abf4ef1..892b526c9d4 100644 --- a/docs/code-quality/c28254.md +++ b/docs/code-quality/c28254.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28254" -title: C28254 +description: "Learn more about: Warning C28254" +title: Warning C28254 ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28254"] +f1_keywords: ["C28254", "DYNAMIC_CAST"] helpviewer_keywords: ["C28254"] ms.assetid: ac8a6d6d-4e8f-4e90-8d90-4c107e245b53 --- -# C28254 +# Warning C28254 -> warning C28254: dynamic_cast<>() is not supported in annotations +> `dynamic_cast<>()` is not supported in annotations -The C++ **`dynamic_cast`** operator cannot be used in annotations. +The C++ **`dynamic_cast`** operator can't be used in annotations. diff --git a/docs/code-quality/c28262.md b/docs/code-quality/c28262.md index 670ccc107e3..bff5e7dbded 100644 --- a/docs/code-quality/c28262.md +++ b/docs/code-quality/c28262.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C28262" -title: C28262 +description: "Learn more about: Warning C28262" +title: Warning C28262 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28262"] helpviewer_keywords: ["C28262"] ms.assetid: 58e130b7-c466-411f-84a0-502898e3e9e6 --- -# C28262 +# Warning C28262 -> warning C28262: A syntax error in the annotation was found in function \ for annotation \ +> A syntax error in the annotation was found in function '*function*' for annotation '*name*' diff --git a/docs/code-quality/c28263.md b/docs/code-quality/c28263.md index c2483ccaaa6..93a35243080 100644 --- a/docs/code-quality/c28263.md +++ b/docs/code-quality/c28263.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C28263" -title: C28263 +description: "Learn more about: Warning C28263" +title: Warning C28263 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28263"] helpviewer_keywords: ["C28263"] ms.assetid: 5b75fb56-8fc9-43ad-a00d-a28dc6cf6fca --- -# C28263 +# Warning C28263 -> warning C28263: A syntax error in a conditional annotation was found for Intrinsic annotation +> A syntax error in a conditional annotation was found for Intrinsic annotation The Code Analysis tool reports this warning when the return value for the specified function has a conditional value. This warning indicates an error in the annotations, not in the code being analyzed. If the function declaration is in a header file, the annotation should be corrected so that it matches the header file. The result list for the function and parameter specified has multiple unconditional values. -Typically, this indicates that more than one unconditional `_Null_` or `__drv_valueIs` annotations have been used to specify a result value. +Typically, this warning indicates that more than one unconditional `_Null_` or `__drv_valueIs` annotations have been used to specify a result value. diff --git a/docs/code-quality/c28267.md b/docs/code-quality/c28267.md index c3823f014ff..ceb6cf1c983 100644 --- a/docs/code-quality/c28267.md +++ b/docs/code-quality/c28267.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: C28267" -title: C28267 +description: "Learn more about: Warning C28267" +title: Warning C28267 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28267"] helpviewer_keywords: ["C28267"] ms.assetid: 3f32f302-842d-43df-bb28-e90b24021ae9 --- -# C28267 +# Warning C28267 -> warning C28267: A syntax error in the annotations was found annotation \ in the function \. +> A syntax error in the annotations was found for function '*function-name*', for annotation '*annotation-name*': *reason*. diff --git a/docs/code-quality/c28272.md b/docs/code-quality/c28272.md index d55950b6dfd..78010775734 100644 --- a/docs/code-quality/c28272.md +++ b/docs/code-quality/c28272.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28272" -title: C28272 +description: "Learn more about: Warning C28272" +title: Warning C28272 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28272"] helpviewer_keywords: ["C28272"] ms.assetid: 0288be83-d0aa-488c-9097-cb33bd423033 --- -# C28272 +# Warning C28272 -> warning C28272: The annotation for function, parameter when examining is inconsistent with the function declaration +> The annotation for function '*function-name*', parameter '*parameter-name*' when examining '*clue*' is inconsistent with the function declaration -This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with those appearing on a declaration. The two annotations should be resolved to match. +This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with the ones appearing on a declaration. The two annotations should be resolved to match. diff --git a/docs/code-quality/c28273.md b/docs/code-quality/c28273.md index 6f93b9694dd..208eb97a06f 100644 --- a/docs/code-quality/c28273.md +++ b/docs/code-quality/c28273.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28273" -title: C28273 +description: "Learn more about: Warning C28273" +title: Warning C28273 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28273"] helpviewer_keywords: ["C28273"] ms.assetid: 3115995b-5734-425f-91ef-115293bfb862 --- -# C28273 +# Warning C28273 -> warning C28273: For function, the clues are inconsistent with the function declaration +> For function '*function-name*', the clues are inconsistent with the function declaration -This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with those appearing on a declaration. The two annotations should be resolved to match. +This warning indicates an error in the annotations, not in the code that is being analyzed. The annotations appearing on a function definition are inconsistent with the ones appearing on a declaration. The two annotations should be resolved to match. diff --git a/docs/code-quality/c28275.md b/docs/code-quality/c28275.md index 47d839e7c7f..935b1abdac7 100644 --- a/docs/code-quality/c28275.md +++ b/docs/code-quality/c28275.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28275" -title: C28275 +description: "Learn more about: Warning C28275" +title: Warning C28275 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28275"] helpviewer_keywords: ["C28275"] ms.assetid: fb3ee99d-9855-45e6-aebd-f2174a85c481 --- -# C28275 +# Warning C28275 -> warning C28275: The parameter to \_Macro\_value\_ is null +> The parameter to \_Macro\_value\_ is null -This warning indicates that there is an internal error in the model file, not in the code being analyzed. The *macroValue* function was called without a parameter. +This warning indicates that there's an internal error in the model file, not in the code being analyzed. The *macroValue* function was called without a parameter. diff --git a/docs/code-quality/c28278.md b/docs/code-quality/c28278.md index 1db293b6f0d..901ee8e558a 100644 --- a/docs/code-quality/c28278.md +++ b/docs/code-quality/c28278.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: C28278" -title: C28278 +description: "Learn more about: Warning C28278" +title: Warning C28278 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28278"] helpviewer_keywords: ["C28278"] ms.assetid: fbfe2256-022f-4251-8397-d3e5511632e2 --- -# C28278 +# Warning C28278 -> warning C28278: Function name appears with no prototype in scope. +> Function name appears with no prototype in scope. This warning typically indicates that a `__deref` is needed to apply the `__return` annotation to the value returned. The Code Analysis tool reports this warning when a function without a declaration was called, and the analysis that can be performed is limited because the declaration contains important information. -The C language permits (but discourages) the use of a function for which no prototype has been declared. A function definition or a function declaration (prototype) should appear before the first use of the function. This warning indicates that a function without a declaration was called, and the analysis that can be performed is limited because declaration contains important information. If the function declaration were to contain annotations, the function declaration is even more useful to the Code Analysis tool. +The C language permits (but discourages) the use of a function for which no prototype has been declared. A function definition or a function declaration (prototype) should appear before the first use of the function. This warning indicates that a function without a declaration was called, and the analysis that can be performed is limited because declaration contains important information. If the function declaration contains annotations, the function declaration is even more useful to the Code Analysis tool. diff --git a/docs/code-quality/c28279.md b/docs/code-quality/c28279.md index 2c92db7b3e0..7a2922ea5b4 100644 --- a/docs/code-quality/c28279.md +++ b/docs/code-quality/c28279.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28279" -title: C28279 +description: "Learn more about: Warning C28279" +title: Warning C28279 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28279"] helpviewer_keywords: ["C28279"] ms.assetid: 10e2bbd9-84c9-4f52-94ba-722e9fef0b5e --- -# C28279 +# Warning C28279 -> warning C28279: For symbol, a 'begin' was found without a matching 'end' +> For symbol, a 'begin' was found without a matching 'end' The annotation language supports a begin and end (`{` and `}` in C) construct, and the pairing has gotten unbalanced. This situation can be avoided if the macros are used. diff --git a/docs/code-quality/c28280.md b/docs/code-quality/c28280.md index 775143c4975..c7b78317c3b 100644 --- a/docs/code-quality/c28280.md +++ b/docs/code-quality/c28280.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28280" -title: C28280 +description: "Learn more about: Warning C28280" +title: Warning C28280 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28280"] helpviewer_keywords: ["C28280"] ms.assetid: f9c989e3-c11d-4742-9e9c-db49096ef099 --- -# C28280 +# Warning C28280 -> warning C28280: For symbol, an 'end' was found without a matching 'begin' +> For symbol, an 'end' was found without a matching 'begin' The annotation language supports a begin and an end (`{` and `}` in C) construct, and the pairing has gotten unbalanced. This situation can be avoided if the macros are used. diff --git a/docs/code-quality/c28282.md b/docs/code-quality/c28282.md index 95edd408283..381f066b76e 100644 --- a/docs/code-quality/c28282.md +++ b/docs/code-quality/c28282.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28282" -title: C28282 +description: "Learn more about: Warning C28282" +title: Warning C28282 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28282"] helpviewer_keywords: ["C28282"] ms.assetid: 36ffd1c6-722e-492f-aa91-650b705511c5 --- -# C28282 +# Warning C28282 -> warning C28282: Format Strings must be in preconditions +> Format Strings must be in preconditions -This warning indicates that a `__drv_formatString` annotation is found, which is not in a `_Pre_` (`__drv_in`) annotation (function parameters are by default `_Pre_`). Check whether the annotation used in an explicit block with a `_Post_` (`__drv_out`) annotation. If so, remove the annotation from any enclosing block that has put it in a `_Post_` context. +This warning indicates that a `__drv_formatString` annotation is found, which isn't in a `_Pre_` (`__drv_in`) annotation (function parameters are by default `_Pre_`). Check whether the annotation used in an explicit block with a `_Post_` (`__drv_out`) annotation. If so, remove the annotation from any enclosing block that has put it in a `_Post_` context. diff --git a/docs/code-quality/c28283.md b/docs/code-quality/c28283.md index 0c58488a30f..7b265029cf9 100644 --- a/docs/code-quality/c28283.md +++ b/docs/code-quality/c28283.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28283" -title: C28283 +description: "Learn more about: Warning C28283" +title: Warning C28283 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28283"] helpviewer_keywords: ["C28283"] ms.assetid: 061d7818-6826-4e6f-8f9c-a6ed687ee1b3 --- -# C28283 +# Warning C28283 -> warning C28283: For symbol, the specified size specification is not yet supported +> For symbol, the specified size specification is not yet supported The warning indicates that the size specification "sentinel" annotation received a value other than zero. Essentially, the caller tried to say that the string is terminated by a character other than binary zero. diff --git a/docs/code-quality/c28284.md b/docs/code-quality/c28284.md index 35028ee67c3..e08a870bed2 100644 --- a/docs/code-quality/c28284.md +++ b/docs/code-quality/c28284.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28284" -title: C28284 +description: "Learn more about: Warning C28284" +title: Warning C28284 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28284"] helpviewer_keywords: ["C28284"] ms.assetid: 11dd24b0-7057-4fe8-919e-b61cf3674fea --- -# C28284 +# Warning C28284 -> warning C28284: For symbol, Predicates are currently not supported for non-function symbols +> For symbol, Predicates are currently not supported for non-function symbols This warning indicates that a conditional annotation (predicate, `__drv_when`) was found on something other than a function. diff --git a/docs/code-quality/c28285.md b/docs/code-quality/c28285.md index dedc06f6e9e..d3603284c42 100644 --- a/docs/code-quality/c28285.md +++ b/docs/code-quality/c28285.md @@ -1,35 +1,35 @@ --- -description: "Learn more about: C28285" -title: C28285 -ms.date: 12/17/2019 -ms.topic: reference -f1_keywords: ["C28285"] +description: "Learn more about: Warning C28285" +title: Warning C28285 +ms.date: 09/22/2022 +f1_keywords: ["C28285", "SPEC_INVALID_SYNTAX2", "__WARNING_SPEC_INVALID_SYNTAX2"] helpviewer_keywords: ["C28285"] ms.assetid: 6197eb0f-7e1e-4c3e-b097-1f6481405994 --- -# C28285 +# Warning C28285 -> warning C28285: For function 'function_name', syntax error in 'annotation' +> For function '*function-name*', syntax error in '*annotation*' -The Code Analysis tool reports this warning for syntax errors in the SAL annotation. The SAL parser will recover by discarding the malformed annotation. +## Remarks + +The Code Analysis tool reports this warning for syntax errors in the SAL annotation. The SAL parser will recover by discarding the malformed annotation. Double check the documentation for the SAL annotations being used and try to simplify the annotation. You shouldn't use implementation layer annotations such as `__declspec("SAL_begin")` directly. If you're using that layer, then change them into higher layers such as `_In_`/`_Out_`/`_Ret_`. For more information, see [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md). ## Example +The following code generates this warning. The argument `(2,n)` is malformed and will cause a C28285 warning after the `_Out_writes_z_` macro is expanded. + ```cpp -// The argument '(n,2)' is malformed and will cause a C28285 warning after the _Out_writes_z_ macro is expanded. void example_func(_Out_writes_z_((2,n)) char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` -Double check the documentation to the SAL annotations being used and try to simplify the annotation. You should not use implementation layer annotations such as `__declspec("SAL_begin")` directly. If you are using that layer then change them into higher layers such as `_In_`/`_Out_`/`_Ret_`. See [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md) for more information. +The following code remediates this warning by correcting the malformed annotation ```cpp void example_func(_Out_writes_z_(n) char* buffer, int n) { - // ... - buffer[n] = '\0'; + buffer[n] = '\0'; } ``` diff --git a/docs/code-quality/c28286.md b/docs/code-quality/c28286.md index f46720281ab..61c5cfb967b 100644 --- a/docs/code-quality/c28286.md +++ b/docs/code-quality/c28286.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28286" -title: C28286 +description: "Learn more about: Warning C28286" +title: Warning C28286 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28286"] helpviewer_keywords: ["C28286"] ms.assetid: dce3c45f-3632-407d-b9ac-8a37b3ce21a4 --- -# C28286 +# Warning C28286 -> warning C28286: For function, syntax error near the end +> For function, syntax error near the end The Code Analysis tool reports this warning when a probable error is encountered in the model file. A few source file errors can also cause such errors. diff --git a/docs/code-quality/c28287.md b/docs/code-quality/c28287.md index f87e5ec7ebb..efec973fbb4 100644 --- a/docs/code-quality/c28287.md +++ b/docs/code-quality/c28287.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28287" -title: C28287 +description: "Learn more about: Warning C28287" +title: Warning C28287 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28287"] helpviewer_keywords: ["C28287"] ms.assetid: b0edc1b6-ad52-4512-a1ee-90180f800d44 --- -# C28287 +# Warning C28287 -> warning C28287: For function, syntax Error in \_At\_() annotation (unrecognized parameter name) +> For function, syntax Error in \_At\_() annotation (unrecognized parameter name) -The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression cannot be interpreted in the current context. This might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. +The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression can't be interpreted in the current context. Reasons might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. diff --git a/docs/code-quality/c28288.md b/docs/code-quality/c28288.md index d5c8d406c27..4d359b12695 100644 --- a/docs/code-quality/c28288.md +++ b/docs/code-quality/c28288.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28288" -title: C28288 +description: "Learn more about: Warning C28288" +title: Warning C28288 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28288"] helpviewer_keywords: ["C28288"] ms.assetid: 3995f210-e797-434c-bc1c-db10b42da3ac --- -# C28288 +# Warning C28288 -> warning C28288: For function, syntax Error in \_At\_() annotation (invalid parameter name) +> For function, syntax Error in \_At\_() annotation (invalid parameter name) -The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression cannot be interpreted in the current context. This might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. +The Code Analysis tool reports this warning when the `SAL_at` (`__drv_at`) annotation is used and the parameter expression can't be interpreted in the current context. Reasons might include using a misspelled parameter or member name, or a misspelling of "return" or "this" keywords. diff --git a/docs/code-quality/c28289.md b/docs/code-quality/c28289.md index 58f99f72d89..0cee2027750 100644 --- a/docs/code-quality/c28289.md +++ b/docs/code-quality/c28289.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28289" -title: C28289 +description: "Learn more about: Warning C28289" +title: Warning C28289 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28289"] helpviewer_keywords: ["C28289"] ms.assetid: 13af34f6-c8b0-4751-9df5-251322073fff --- -# C28289 +# Warning C28289 -> warning C28289: For function: ReadableTo or WritableTo did not have a limit-spec as a parameter +> For function: ReadableTo or WritableTo did not have a limit-spec as a parameter The Code Analysis tool reports this warning when the function/parameter annotation is miscoded as noted. diff --git a/docs/code-quality/c28290.md b/docs/code-quality/c28290.md index 1d8a32a4704..f01f88a591d 100644 --- a/docs/code-quality/c28290.md +++ b/docs/code-quality/c28290.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28290" -title: C28290 +description: "Learn more about: Warning C28290" +title: Warning C28290 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28290"] helpviewer_keywords: ["C28290"] ms.assetid: 33c22d66-fce4-4670-99d4-7bd147dd05d0 --- -# C28290 +# Warning C28290 -> warning C28290: the annotation for function contains more Externals than the actual number of parameters +> The annotation for function contains more Externals than the actual number of parameters The Code Analysis tool reports this warning when the annotation for the function contains more Externals than the actual number of parameters. diff --git a/docs/code-quality/c28291.md b/docs/code-quality/c28291.md index 5e768d95456..346c9e49f67 100644 --- a/docs/code-quality/c28291.md +++ b/docs/code-quality/c28291.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28291" -title: C28291 +description: "Learn more about: Warning C28291" +title: Warning C28291 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28291"] helpviewer_keywords: ["C28291"] ms.assetid: 92157d55-d8d2-4c3e-9240-c5d8923631f6 --- -# C28291 +# Warning C28291 -> warning C28291: Post null/notnull at deref level 0 is meaningless for function \ at param \ +> Post null/notnull at deref level 0 is meaningless for function '*x*' at param '*number*' -The Code Analysis tool reports this warning when the post condition of a dereference level-zero parameter is specified to have a null/non-null property. This error occurs because a value at dereference level zero cannot change. +The Code Analysis tool reports this warning when the post condition of a dereference level-zero parameter is specified to have a null/non-null property. This error occurs because a value at dereference level zero can't change. diff --git a/docs/code-quality/c28300.md b/docs/code-quality/c28300.md index a3c853ea27c..38dec826cbf 100644 --- a/docs/code-quality/c28300.md +++ b/docs/code-quality/c28300.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28300" -title: C28300 +description: "Learn more about: Warning C28300" +title: Warning C28300 ms.date: 12/17/2019 -ms.topic: reference f1_keywords: ["C28300"] helpviewer_keywords: ["C28300"] ms.assetid: 29430cff-c5b8-4759-8898-055dc1c4597f --- -# C28300 +# Warning C28300 -> warning C28300: : Expression operands of incompatible types for operator +> : Expression operands of incompatible types for operator This warning fires a SAL annotation contains an expression containing incompatible types. @@ -32,7 +31,7 @@ void f(_In_reads_(10 + value) int *buffer, MyUnion value) } ``` -In the previous example the developer forgot to access the appropriate member variable. In other cases you may need to fix the error with an explicit cast. +In the previous example, the developer forgot to access the appropriate member variable. In other cases, you may need to fix the error with an explicit cast. ```cpp void f(_In_reads_(10 + value.length) int *buffer, MyUnion value) diff --git a/docs/code-quality/c28301.md b/docs/code-quality/c28301.md index 5c26d4f356c..dd41694f883 100644 --- a/docs/code-quality/c28301.md +++ b/docs/code-quality/c28301.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28301" -title: C28301 +description: "Learn more about: Warning C28301" +title: Warning C28301 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28301"] helpviewer_keywords: ["C28301"] ms.assetid: bef85fd0-dc76-4981-bd64-618317e97a38 --- -# C28301 +# Warning C28301 -> warning C28301: No annotations for first declaration of \.\ See \(\). \ +> No annotations for first declaration of '*function*'.'*note1*' See '*filename*'('*line*'). '*note2*' -This warning is reported when annotations were not found at the first declaration of a given function. +This warning is reported when annotations weren't found at the first declaration of a given function. diff --git a/docs/code-quality/c28302.md b/docs/code-quality/c28302.md index f1ee4ac0470..81f4f296b4a 100644 --- a/docs/code-quality/c28302.md +++ b/docs/code-quality/c28302.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28302" -title: C28302 +description: "Learn more about: Warning C28302" +title: Warning C28302 ms.date: 06/29/2022 -ms.topic: reference f1_keywords: ["C28302"] helpviewer_keywords: ["C28302"] ms.assetid: 288316e1-f7ea-4c73-a1e6-8f6fe645fbaf --- -# C28302 +# Warning C28302 -> warning C28302: For C++ reference-parameter \, an extra `_Deref_` operator was found on \. +> For C++ reference-parameter '*parameter_name*', an extra `_Deref_` operator was found on '*annotation*'. This warning is reported when an extra level of `_Deref_` is used on a parameter of a reference type such as `T &a`. A common mistake when using SAL1 annotations is to use `__deref` on a reference type. Reference types are understood by SAL, so all annotations are already applied to the underlying type. It's typically not an issue in SAL2 because the free-floating `__deref` annotation was removed. If you intend to apply an annotation to a subtype, then you should instead use the SAL2 `_AT_` or `_Outref_` annotations. diff --git a/docs/code-quality/c28303.md b/docs/code-quality/c28303.md index b661800ef8a..9ac04b56bb7 100644 --- a/docs/code-quality/c28303.md +++ b/docs/code-quality/c28303.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: C28303" -title: C28303 +description: "Learn more about: Warning C28303" +title: Warning C28303 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28303"] helpviewer_keywords: ["C28303"] ms.assetid: 0b314abd-6082-43fb-bba3-a9edb5a7bf19 --- -# C28303 +# Warning C28303 -> warning C28303: For C++ reference-parameter , an ambiguous `_Deref_` operator was found on \. +> For C++ reference-parameter , an ambiguous `_Deref_` operator was found on '*annotation*'. This warning similar to warning C28302 and is reported when an extra level of `_Deref_` is used on a parameter. -SAL2 does not require the use of an extra level of `_Deref_` when dealing with reference parameters. This particular annotation is ambiguous as to which level of dereference is intended to be annotated. It may be necessary to use `_At_` to reference the specific object to be annotated. +SAL2 doesn't require the use of an extra level of `_Deref_` when dealing with reference parameters. This particular annotation is ambiguous as to which level of dereference is intended to be annotated. It may be necessary to use `_At_` to reference the specific object to be annotated. ## Example @@ -29,7 +28,7 @@ The above annotation could be interpreted either as: - a reference to a pointer to an array (of n) integers (SAL2 interpretation) - Either of the following can correct this warning: + Either of the following changes can correct this warning: ```cpp void ref(_Out_writes_(n) int **&buff, int &n) diff --git a/docs/code-quality/c28304.md b/docs/code-quality/c28304.md index e00b915e018..8e6b84c97b1 100644 --- a/docs/code-quality/c28304.md +++ b/docs/code-quality/c28304.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28304" -title: C28304 +description: "Learn more about: Warning C28304" +title: Warning C28304 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28304"] helpviewer_keywords: ["C28304"] ms.assetid: 5bc7f593-dfc3-4172-a403-97bdf7be4885 --- -# C28304 +# Warning C28304 -> warning C28304: For C++ reference-parameter , an improperly placed `_Notref_` operator was found applied to \. +> For C++ reference-parameter , an improperly placed `_Notref_` operator was found applied to '*token*'. The `_Notref_` operator should only be used in special circumstances involving C++ reference parameters and only in system-provided macros. It must be immediately followed by a `_Deref_` operator or a functional annotation. diff --git a/docs/code-quality/c28305.md b/docs/code-quality/c28305.md index 64688a7e8d0..17bd8083dd9 100644 --- a/docs/code-quality/c28305.md +++ b/docs/code-quality/c28305.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28305" -title: C28305 +description: "Learn more about: Warning C28305" +title: Warning C28305 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28305"] helpviewer_keywords: ["C28305"] ms.assetid: c9495d3f-aa11-4695-ab8d-1d2194da9ce3 --- -# C28305 +# Warning C28305 -> warning C28305: An error while parsing \ was discovered. +> An error while parsing '*token*' was discovered. This warning is reported when the expression containing the specified token is ill-formed. diff --git a/docs/code-quality/c28306.md b/docs/code-quality/c28306.md index fc72b5838f1..0462d5856dd 100644 --- a/docs/code-quality/c28306.md +++ b/docs/code-quality/c28306.md @@ -1,14 +1,17 @@ --- -description: "Learn more about: C28306" -title: C28306 +description: "Learn more about: Warning C28306" +title: Warning C28306 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28306"] helpviewer_keywords: ["C28306"] ms.assetid: 64517b10-c8b3-4100-953b-278eab624369 --- -# C28306 +# Warning C28306 -> warning C28306: The annotation on parameter is obsolescent +> The annotation on parameter is obsolescent Use `_String_length_` with the appropriate SAL2 annotation instead. + +## See also + +[Intrinsic Functions](./intrinsic-functions.md) diff --git a/docs/code-quality/c28307.md b/docs/code-quality/c28307.md index 16801c99f84..28d5af3d02c 100644 --- a/docs/code-quality/c28307.md +++ b/docs/code-quality/c28307.md @@ -1,14 +1,17 @@ --- -description: "Learn more about: C28307" -title: C28307 +description: "Learn more about: Warning C28307" +title: Warning C28307 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28307"] helpviewer_keywords: ["C28307"] ms.assetid: e86a14cc-9ff1-4bad-9d85-93c739704ab8 --- -# C28307 +# Warning C28307 -> warning C28307: The annotation on parameter is obsolescent +> The annotation on parameter is obsolescent Use `_String_length_` with the appropriate SAL2 annotation instead. + +## See also + +[Intrinsic Functions](./intrinsic-functions.md) diff --git a/docs/code-quality/c28308.md b/docs/code-quality/c28308.md index 1ee8e1e2a2a..c4ceffa7438 100644 --- a/docs/code-quality/c28308.md +++ b/docs/code-quality/c28308.md @@ -1,22 +1,50 @@ --- -description: "Learn more about: C28308" -title: C28308 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C28308"] +description: "Learn more about: Warning C28308" +title: Warning C28308 +ms.date: 03/07/2023 +f1_keywords: ["C28308", "BAD_FORMAT_ARGUMENT_POSITION", "__WARNING_BAD_FORMAT_ARGUMENT_POSITION"] helpviewer_keywords: ["C28308"] -ms.assetid: 2be46de3-844e-4cd6-a97f-d5c12ac9dc31 --- -# C28308 +# Warning C28308 -> warning C28308: The format list argument position specified by the annotation is incorrect. +> The format list argument position specified by the annotation is incorrect. -The format list argument position must be either a parameter name, or an integer offset that's in the parameter list, or zero. +## Remarks -The second parameter to `IsFormatString2` (`where`) can be in one of two forms: +This warning indicates a `_*_format_strings_param(position)` SAL annotation is specifying an invalid position for the first parameter to the format string. The annotation helps the checker verify `printf` style formatting strings passed to the function. Other format string validity checks that rely on this annotation won't run as a result of this warning. -- A parameter name, which is taken as the first argument to the format string. +The `_*_format_strings_param(position)` SAL annotation is attached to the formatting string argument. `position` must be in one of these forms: -- An offset (`n`) relative to the format-string parameter. +- An identifier, which is taken as the first argument to the format string. When the identifier isn't the name of a parameter to the function, a warning is emitted. +- A positive integer offset relative to the format-string parameter where `1` is the next parameter. When the offset is out of bounds for the parameters, a warning is emitted. +- The value `0`, which is interpreted as the `...` parameter. When the function isn't variadic, a warning is emitted. - In the second form, the first format-string parameter is the `n`-th argument after the format string. If `n` is zero, an ellipsis is specified as the parameter. Specifying an offset of zero without specifying the ellipsis as the first format-string parameter will cause an error. +One limitation of this check, is that it's run at the function call site and not at the declaration. This limitation is a side effect of the lazy evaluation of SAL annotations. + +## Examples + +In this example, there's a specialized function for logging coordinates. The params annotation specifies the `...` parameter, which doesn't exist. + +```cpp +void LogCoordinate(_Printf_format_string_params_(0) _In_ char *format, int x, int y); + +void func(int x, int y) +{ + LogCoordinate("(%d, %d)", x, y); +} +``` + +This issue is fixed by changing the annotated position to `x` or `1`. To determine the correct value for your code, check the behavior of the called function. + +```cpp +void LogCoordinate(_Printf_format_string_params_(1) _In_ char *format, int x, int y); + +void func(int x, int y) +{ + LogCoordinate("(%d, %d)", x, y); +} +``` + +## See also + +[Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md) diff --git a/docs/code-quality/c28309.md b/docs/code-quality/c28309.md index 90102f769b3..b5fc4d73a5d 100644 --- a/docs/code-quality/c28309.md +++ b/docs/code-quality/c28309.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28309" -title: C28309 +description: "Learn more about: Warning C28309" +title: Warning C28309 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28309"] helpviewer_keywords: ["C28309"] ms.assetid: b3039b80-8623-42f5-8b46-6665e7ba7762 --- -# C28309 +# Warning C28309 -> warning C28309: : Annotation operands must be integer/enum/pointer types. Void operands and C++ overloaded operators are not supported. Floats are approximated as integers. Types: \. +> : Annotation operands must be integer/enum/pointer types. Void operands and C++ overloaded operators are not supported. Floats are approximated as integers. Types: '*typelist*'. You've tried to use a void or a function in an annotation expression, and Code Analysis can't handle it. This error typically occurs when an `operator==` that's implemented as a function is used, but other cases may also occur. Examine the types in \ for clues about what's wrong. diff --git a/docs/code-quality/c28310.md b/docs/code-quality/c28310.md index f700b869eed..30aa4d82445 100644 --- a/docs/code-quality/c28310.md +++ b/docs/code-quality/c28310.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28310" -title: C28310 +title: Warning C28310 +description: "Learn more about: Warning C28310" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28310"] -ms.assetid: 51054ca8-01b6-454b-9853-f05f1c817b18 +helpviewer_keywords: ["C28310"] --- -# C28310 +# Warning C28310 -> warning C28310: The annotation on \ \ has no SAL version. +> The annotation on '*function*' '*parameter*' has no SAL version. -All SAL annotations used in source code should have an annotation version applied by the use of SAL_name. This needs to be corrected in the macro definition. +All SAL annotations used in source code should have an annotation version applied by the use of SAL_name. This issue needs to be corrected in the macro definition. This warning is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. diff --git a/docs/code-quality/c28311.md b/docs/code-quality/c28311.md index 6ca8410a9cd..9d72006caeb 100644 --- a/docs/code-quality/c28311.md +++ b/docs/code-quality/c28311.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28311" -title: C28311 +title: Warning C28311 +description: "Learn more about: Warning C28311" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28311"] -ms.assetid: 2c76e07a-4418-40ef-8a77-c62774bc3677 +helpviewer_keywords: ["C28311"] --- -# C28311 +# Warning C28311 -> warning C28311: The annotation on \ \ is an obsolescent version of SAL. +> The annotation on '*function*' '*parameter*' is an obsolescent version of SAL. -The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning is not emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. +The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning isn't emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. ## See also diff --git a/docs/code-quality/c28312.md b/docs/code-quality/c28312.md index d9b81cb87d2..852d5bec16d 100644 --- a/docs/code-quality/c28312.md +++ b/docs/code-quality/c28312.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: C28312" -title: C28312 +title: Warning C28312 +description: "Learn more about: Warning C28312" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28312"] -ms.assetid: 19828546-33c9-4373-b7df-2a362ca12637 +helpviewer_keywords: ["C28312"] --- -# C28312 +# Warning C28312 -> warning C28312: The annotation on the repeated declaration of \ \ is an obsolescent version of SAL. +> The annotation on the repeated declaration of '*function*' '*parameter*' is an obsolescent version of SAL. -The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning is not emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. +The annotation is an old version and should be updated to the equivalent [SAL2](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning isn't emitted if a prior inconsistent annotation warning has been emitted, and is reported only once per declaration. Inspect the rest of the declaration for more obsolete SAL. ## See also diff --git a/docs/code-quality/c28350.md b/docs/code-quality/c28350.md index 2e1c8badbd9..ef1ffff5eac 100644 --- a/docs/code-quality/c28350.md +++ b/docs/code-quality/c28350.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: C28350" -title: C28350 +description: "Learn more about: Warning C28350" +title: Warning C28350 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28350"] helpviewer_keywords: ["C28350"] ms.assetid: 912475d6-3856-4bff-86e4-e7bdce21410c --- -# C28350 +# Warning C28350 -> warning C28350: The annotation \ describes a situation that is not conditionally applicable. +> The annotation '*annotation*' describes a situation that is not conditionally applicable. Usually this warning is generated when an annotation is applied where the C/C++ type is being inspected. diff --git a/docs/code-quality/c28351.md b/docs/code-quality/c28351.md index 017692a1f26..b3a45785e0e 100644 --- a/docs/code-quality/c28351.md +++ b/docs/code-quality/c28351.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: C28351" -title: C28351 +description: "Learn more about: Warning C28351" +title: Warning C28351 ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C28351"] helpviewer_keywords: ["C28351"] ms.assetid: 3535daab-cab1-4167-b860-d6748d8357b5 --- -# C28351 +# Warning C28351 -> warning C28351: The annotation \ describes where a dynamic value (a variable) cannot be used in the condition. +> The annotation '*annotation*' describes where a dynamic value (a variable) cannot be used in the condition. This warning is reported when an annotation is applied where the C/C++ type is being inspected. diff --git a/docs/code-quality/c33001.md b/docs/code-quality/c33001.md index e07584a3031..679ffc1e04c 100644 --- a/docs/code-quality/c33001.md +++ b/docs/code-quality/c33001.md @@ -1,24 +1,36 @@ --- -title: c33001 +title: Warning C33001 description: C33001 warning for VARIANTs -keywords: c33001 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33001"] +f1_keywords: ["C33001", "VARIANTCLEAR_UNINITIALIZED"] helpviewer_keywords: ["C33001"] -dev_langs: ["C++"] --- -# C33001 +# Warning C33001 -> Warning C33001: VARIANT 'var' was cleared when it was uninitialized (expression 'expr') +> VARIANT '*var*' was cleared when it was uninitialized (expression '*expr*') -This warning is triggered when an uninitialized VARIANT is passed to an API such as VariantClear -that expects an initialized VARIANT. +## Remarks + +This warning is triggered when an uninitialized `VARIANT` is passed to an API, such as `VariantClear`, that clears the object. Initialize the `VARIANT` before passing it to these functions so it can be properly cleared. + +This warning applies to these functions: + +* `VariantClear` +* `PropVariantClear` +* `VariantCopy` +* `VariantCopyInd` +* `VariantChangeType` +* `VariantChangeTypeEx` +* `DestroyPropVariant` + +Code analysis name: `VARIANTCLEAR_UNINITIALIZED` ## Example +The following code causes warning C33001: + ```cpp #include @@ -33,11 +45,11 @@ HRESULT foo(bool some_condition) //... } - VariantClear(&var); // C33001 + VariantClear(&var); // C33001 } ``` -These warnings are corrected by ensuring VariantClear is called only for a properly initialized VARIANT: +In this example, the warning is corrected by calling `VariantClear` only after `var` has been initialized: ```cpp #include @@ -51,12 +63,12 @@ HRESULT foo(bool some_condition) //... VariantInit(&var); //... - VariantClear(&var); // C33001 + VariantClear(&var); // OK } } ``` ## See also -[C33004](./c33004.md) +[C33004](./c33004.md)\ [C33005](./c33005.md) diff --git a/docs/code-quality/c33004.md b/docs/code-quality/c33004.md index 51f70675f14..44486d8ffc6 100644 --- a/docs/code-quality/c33004.md +++ b/docs/code-quality/c33004.md @@ -1,24 +1,27 @@ --- -title: c33004 +title: Warning C33004 description: C33004 warning for VARIANTs -keywords: c33004 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33004"] +f1_keywords: ["C33004", "VARIANTCLEAR_UNINITOUTPARAM"] helpviewer_keywords: ["C33004"] -dev_langs: ["C++"] --- -# C33004 +# Warning C33004 -> Warning C33004: VARIANT 'var', which is marked as _Out_ was cleared before being initialized (expression 'expr') +> VARIANT '*var*', which is marked as `_Out_` was cleared before being initialized (expression '*expr*') -This warning is triggered when a VARIANT parameter with \_Out\_ SAL annotation, which may haven't been -initialized on input, is passed to an API such as VariantClear that expects an initialized VARIANT. +## Remarks + +This warning is triggered when a `VARIANT` parameter with `_Out_` SAL annotation may not have been +initialized on input, and is then passed to an API such as `VariantClear` that expects an initialized `VARIANT`. + +Code analysis name: `VARIANTCLEAR_UNINITOUTPARAM` ## Example +The following sample code causes warning C33004: + ```cpp #include @@ -46,5 +49,5 @@ void t2(_Out_ VARIANT* pv) ## See also -[C33001](./c33001.md) +[C33001](./c33001.md)\ [C33005](./c33005.md) diff --git a/docs/code-quality/c33005.md b/docs/code-quality/c33005.md index 9c69e08d18c..41509513e3c 100644 --- a/docs/code-quality/c33005.md +++ b/docs/code-quality/c33005.md @@ -1,24 +1,26 @@ --- -title: c33005 +title: Warning C33005 description: C33005 warning for VARIANTs -keywords: c33005 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33005"] +f1_keywords: ["C33005", "VARIANTCLEAR_UNINITFUNCPARAM"] helpviewer_keywords: ["C33005"] -dev_langs: ["C++"] --- -# C33005 +# Warning C33005 -> Warning C33005: VARIANT 'var' was provided as an input or input/output parameter but was not initialized (expression 'expr') +> VARIANT '*var*' was provided as an `_In_` or `_InOut_` parameter but was not initialized (expression '*expr*') -This warning is triggered when an uninitialized VARIANT is passed to a function as input-only or input/output -parameter - for example, a pass-by-refrence parameter without an \_Out\_ SAL annotation. +## Remarks + +This warning is triggered when an uninitialized `VARIANT` is passed to a function as an input-only or input/output parameter. For example, a pass-by-reference parameter without an `_Out_` SAL annotation. + +Code analysis name: `VARIANTCLEAR_UNINITFUNCPARAM` ## Example +The following sample code causes warning C33005: + ```cpp #include @@ -33,7 +35,7 @@ void foo() } ``` -These warnings are corrected by ensuring to initialize the VARIANT before passing it to a function +To correct these warnings, initialize the `VARIANT` before passing it to a function as input-only or input/output. ```cpp @@ -53,5 +55,5 @@ void foo() ## See also -[C33001](./c33001.md) +[C33001](./c33001.md)\ [C33004](./c33004.md) diff --git a/docs/code-quality/c33010.md b/docs/code-quality/c33010.md index 5fa8865836e..e4c4a598dfd 100644 --- a/docs/code-quality/c33010.md +++ b/docs/code-quality/c33010.md @@ -1,28 +1,27 @@ --- -title: c33010 +title: Warning C33010 description: C33010 warning for enums -keywords: c33010 author: hwisungi ms.author: hwisungi -ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33010"] +ms.date: 09/08/2022 +f1_keywords: ["C33010", "UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX", "__WARNING_UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX"] helpviewer_keywords: ["C33010"] -dev_langs: ["C++"] --- -# C33010 +# Warning C33010 -> Warning C33010: Unchecked lower bound for enum 'enum' used as index. +> Unchecked lower bound for enum 'enum' used as index. -This warning is triggered for an enum that is used as an index into an array, -if the upper bound is checked for its value, but not the lower bound. +This warning is triggered if an enum is both used as an index into an array and isn't checked on the lower bound. + +## Remarks + +Code using enumerated types as indexes for arrays will often check for the upper bound in order to ensure the index isn't out of range. Because an enum variable is signed by default, it can have a negative value. A negative array index can allow arbitrary memory to be read, used, or even executed. + +Code analysis name: `UNCHECKED_LOWER_BOUND_FOR_ENUMINDEX` ## Example -Code using enumerated types as indexes for arrays will often check for the upper bound -in order to ensure the index is not out of range. Because an enum variable is signed by default, -it can have a negative value. If it is used as an index into an array of values or an array of function pointers, -a negative value can allow arbitrary memory to be read, used, or even executed. +The following code generates this warning. `idx` is used as an index to access `functions`, but the lower bound is never checked. ```cpp typedef void (*PFN)(); @@ -41,14 +40,13 @@ void foo(Index idx, PFN(&functions)[5]) if (idx > Index::Max) return; - auto pfn = functions[static_cast(idx)]; // C33010 + auto pfn = functions[static_cast(idx)]; if (pfn != nullptr) (*pfn)(); - // ...... } ``` -These warnings are corrected by checking the index value for lower bound as well: +The following code remediates this warning by checking the lower bound as well to ensure `idx` isn't negative: ```cpp typedef void (*PFN)(); @@ -67,10 +65,34 @@ void foo(Index idx, PFN(&functions)[5]) if (idx < Index::Zero || idx > Index::Max) return; - auto pfn = functions[static_cast(idx)]; // OK + auto pfn = functions[static_cast(idx)]; + if (pfn != nullptr) + (*pfn)(); +} +``` + +Alternatively, the issue can be fixed by choosing an underlying type for `Index` that is unsigned. Because an unsigned value is always positive, it is sufficient to only check the upper bound. + +```cpp +typedef void (*PFN)(); + +enum class Index : unsigned int +{ + Zero, + One, + Two, + Three, + Max +}; + +void foo(Index idx, PFN(&functions)[5]) +{ + if (idx > Index::Max) + return; + + auto pfn = functions[static_cast(idx)]; if (pfn != nullptr) (*pfn)(); - // ...... } ``` diff --git a/docs/code-quality/c33011.md b/docs/code-quality/c33011.md index 880d7adb02a..f2087f89c88 100644 --- a/docs/code-quality/c33011.md +++ b/docs/code-quality/c33011.md @@ -1,27 +1,26 @@ --- -title: c33011 +title: Warning C33011 description: C33011 warning for enums -keywords: c33011 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33011"] +f1_keywords: ["C33011", "UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX", "__WARNING_UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX"] helpviewer_keywords: ["C33011"] -dev_langs: ["C++"] --- -# C33011 +# Warning C33011 -> Warning C33011: Unchecked upper bound for enum 'enum' used as index. +> Unchecked upper bound for enum 'enum' used as index. + +## Remarks This warning is triggered for an enum that is used as an index into an array, if the lower bound is checked for its value, but not the upper bound. +Code analysis name: `UNCHECKED_UPPER_BOUND_FOR_ENUMINDEX` + ## Example -Code that uses enumerated types as indexes for arrays must check the enum value for both lower and -upper bounds. If the enum value is checked only for the lower bound before used to index into an array of values -or an array of function pointers, then it can allow arbitrary memory to be read, used, or even executed. +Code that uses enumerated types as indexes for arrays must check the enum value for both lower and upper bounds. If the enum value is checked only for the lower bound before used to index into an array of values (or an array of function pointers), then it can allow arbitrary memory to be read, used, or even executed. ```cpp typedef void (*PFN)(); diff --git a/docs/code-quality/c33020.md b/docs/code-quality/c33020.md index 456bdc80ce2..77b698be2a5 100644 --- a/docs/code-quality/c33020.md +++ b/docs/code-quality/c33020.md @@ -1,23 +1,26 @@ --- -title: c33020 +title: Warning C33020 description: C33020 warning for HRESULTs -keywords: c33020 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33020"] +f1_keywords: ["C33020", "HRESULT_LIKELY_INCORRECT_USAGE"] helpviewer_keywords: ["C33020"] -dev_langs: ["C++"] --- -# C33020 +# Warning C33020 -> Warning C33020: Likely incorrect HRESULT usage detected. +> Likely incorrect HRESULT usage detected. -This is high-confidence warning indicating that HRESULT-returning function returns FALSE. +## Remarks + +This warning is a high-confidence indication that an HRESULT-returning function returns `FALSE`. + +Code analysis name: `HRESULT_LIKELY_INCORRECT_USAGE` ## Example +The following sample code causes warning C33020: + ```cpp #include @@ -28,7 +31,7 @@ HRESULT foo() } ``` -These warnings are corrected by using proper HRESULT value: +These warnings are corrected by using the proper HRESULT value: ```cpp #include diff --git a/docs/code-quality/c33022.md b/docs/code-quality/c33022.md index 3979bd0ff37..c8385b9a169 100644 --- a/docs/code-quality/c33022.md +++ b/docs/code-quality/c33022.md @@ -1,24 +1,26 @@ --- -title: c33022 +title: Warning C33022 description: C33022 warning for HRESULTs -keywords: c33022 author: hwisungi ms.author: hwisungi ms.date: 06/20/2020 -ms.topic: reference -f1_keywords: ["C33022"] +f1_keywords: ["C33022", "HRESULT_USAGE_LOW_CONFIDENCE"] helpviewer_keywords: ["C33022"] -dev_langs: ["C++"] --- -# C33022 +# Warning C33022 -> Warning C33022: Potentially incorrect HRESULT usage detected (low confidence) +> Potentially incorrect HRESULT usage detected (low confidence) -This is low-confidence warning for a function that returns HRESULT, if there is "FALSE" -somewhere along the line that eventually returns it or assigns it to a variable that is returned. +## Remarks + +This warning is a low-confidence indicator for a function that returns HRESULT, that there's a `FALSE` that is either eventually returned, or it's assigned to a variable that is returned. + +Code analysis name: `HRESULT_USAGE_LOW_CONFIDENCE` ## Example +The following sample code causes warning C33022: + ```cpp #include diff --git a/docs/code-quality/c6001.md b/docs/code-quality/c6001.md index 5e030368091..8d57dd9cc84 100644 --- a/docs/code-quality/c6001.md +++ b/docs/code-quality/c6001.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6001" -title: C6001 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6001"] +title: "Warning C6001" +description: "Learn more about: Warning C6001" +ms.date: 10/04/2022 +f1_keywords: ["C6001", "USING_UNINIT_VAR", "__WARNING_USING_UNINIT_VAR"] helpviewer_keywords: ["C6001"] -ms.assetid: 55e779f1-7295-48f7-8ce1-b43898b36cd8 --- -# C6001 +# Warning C6001 -> warning C6001: using uninitialized memory \ +> Using uninitialized memory '*variable*'. -This warning is reported when an uninitialized local variable is used before it is assigned a value. This could lead to unpredictable results. You should always initialize variables before use. +## Remarks + +This warning is reported when an uninitialized local variable is used before it's assigned a value. This usage could lead to unpredictable results. You should always initialize variables before use. + +Code analysis name: `USING_UNINIT_VAR` ## Example -The following code generates this warning because variable `i` is only initialized if `b` is true; otherwise an uninitialized `i` is returned: +The following code generates this warning because variable `i` is only initialized if `b` is true: ```cpp int f( bool b ) @@ -34,7 +36,49 @@ To correct this warning, initialize the variable as shown in the following code: ```cpp int f( bool b ) { - int i= -1; + int i = -1; + + if ( b ) + { + i = 0; + } + return i; +} +``` + +## Heuristics + +The following example shows that passing a variable to a function by reference causes the compiler to assume that it's initialized: + +```cpp +void init( int& i ); + +int f( bool b ) +{ + int i; + + init(i); + + if ( b ) + { + i = 0; + } + return i; // i is assumed to be initialized because it's passed by reference to init() +} +``` + +This supports the pattern of passing a pointer to a variable into an initialization function. + +This heuristic can lead to false negatives because many functions expect pointers that point to initialized data. Use [SAL annotations](annotating-function-parameters-and-return-values.md), such as `_In_` and `_Out_`, to describe the function's behavior. The following example calls a function that expects its argument to be initialized, so a warning is generated: + +```cpp +void use( _In_ int& i ); + +int f( bool b ) +{ + int i; + + use(i); // uninitialized variable warning because of the _In_ annotation on use() if ( b ) { diff --git a/docs/code-quality/c6011.md b/docs/code-quality/c6011.md index 6ff3d15d1ad..2255b15e363 100644 --- a/docs/code-quality/c6011.md +++ b/docs/code-quality/c6011.md @@ -1,19 +1,21 @@ --- -title: C6011 +title: "Warning C6011" description: "Reference for Visual Studio C++ code analysis warning C6011." -ms.date: 03/23/2020 -ms.topic: reference -f1_keywords: ["C6011"] +ms.date: 10/04/2022 +f1_keywords: ["C6011", "DEREF_NULL_PTR", "__WARNING_DEREF_NULL_PTR"] helpviewer_keywords: ["C6011"] -ms.assetid: 54b7bc2b-b8f5-43fc-a9a3-8189b03f249a --- -# C6011 +# Warning C6011 -> warning C6011: dereferencing NULL pointer \ +> Dereferencing NULL pointer '*pointer-name*'. + +## Remarks This warning indicates that your code dereferences a potentially null pointer. If the pointer value is invalid, the result is undefined. To resolve the issue, validate the pointer before use. -## Example +Code analysis name: `DEREF_NULL_PTR` + +## Examples The following code generates this warning because a call to `malloc` might return null if insufficient memory is available: @@ -59,12 +61,35 @@ void f([Pre(Null=Yes)] char* pc) } ``` -The careless use of `malloc` and `free` leads to memory leaks and exceptions. To minimize these kinds of leaks and exception problems altogether, avoid allocating raw memory yourself. Instead, use the mechanisms provided by the C++ Standard Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The careless use of `malloc` and `free` leads to memory leaks and exceptions. To minimize these kinds of leaks and exception problems altogether, avoid allocating raw memory yourself. Instead, use the mechanisms provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and [`vector`](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). + +## Heuristics + +A heuristic used to reduce the number of warnings in legacy code assumes that a pointer is non-`NULL` unless there is evidence that it is `NULL`. In the examples we've seen so far, pointers returned by `malloc` or `new` might be `NULL` because allocation might fail. Another characteristic that the analysis engine uses as evidence of nullability is if the program explicitly checks for `NULL`. This is illustrated in the following examples: + +```cpp +void f(int* n) +{ + *n = 1; // Does not warn, n is assumed to be non-null +} + +void f(int* n) +{ + if (n) { + (*n)++; + } + *n = 1; // Warns because the earlier conditional shows that n might be null +} +``` + +In the second case, the user can fix the warning by moving the `*n = 1` line inside the if block. ## See also - [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) -- [NULL](../c-runtime-library/null-crt.md) +- [`NULL`](../c-runtime-library/null-crt.md) - [Indirection and Address-of Operators](../c-language/indirection-and-address-of-operators.md) -- [malloc](../c-runtime-library/reference/malloc.md) -- [free](../c-runtime-library/reference/free.md) +- [`malloc`](../c-runtime-library/reference/malloc.md) +- [`free`](../c-runtime-library/reference/free.md) +- [`new` operator](../cpp/new-operator-cpp.md) +- [`delete` operator](../cpp/delete-operator-cpp.md) diff --git a/docs/code-quality/c6014.md b/docs/code-quality/c6014.md index 62e9a6ef123..6065a8b16c3 100644 --- a/docs/code-quality/c6014.md +++ b/docs/code-quality/c6014.md @@ -1,21 +1,29 @@ --- -description: "Learn more about: C6014" -title: C6014 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6014"] +title: "Warning C6014" +description: "Learn more about: Warning C6014" +ms.date: 10/03/2022 +f1_keywords: ["C6014", "MEMORY_LEAK", "__WARNING_MEMORY_LEAK"] helpviewer_keywords: ["C6014"] -ms.assetid: ef76ec88-74d2-4a3b-b6fe-4b0851ab3372 --- -# C6014 +# Warning C6014 -> warning C6014: Leaking memory. +> Leaking memory '*pointer-name*'. -This warning indicates that the specified pointer points to allocated memory or some other allocated resource that has not been freed. The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +## Remarks + +This warning indicates that the specified pointer points to allocated memory or some other allocated resource that hasn't been freed. + +The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +This warning is reported for both memory and resource leaks when the resource is commonly *aliased* to another location. Memory is aliased when a pointer to the memory escapes the function by using an `_Out_` parameter annotation, global variable, or return value. This warning can be reported on function exit if the argument is annotated that its release is expected. + +Code Analysis won't recognize the actual implementation of a memory allocator (involving address arithmetic) and won't recognize that memory is allocated (although many wrappers will be recognized). In this case, the analyzer doesn't recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma warning(disable: 6014)` directive on the line that precedes the opening brace `{` of the function body. + +Code analysis name: `MEMORY_LEAK` ## Examples -The following code generates this warning: +The following code generates warning C6014: ```cpp // cl.exe /analyze /EHsc /nologo /W4 @@ -72,11 +80,7 @@ int main( ) } ``` -This warning is reported for both memory and resource leaks when the resource is commonly *aliased* to another location. Memory is aliased when a pointer to the memory escapes the function by means of an `_Out_` parameter annotation, global variable, or return value. This warning can be reported on function exit if the argument is annotated as having been expected to be released. - -Note that Code Analysis will not recognize the actual implementation of a memory allocator (involving address arithmetic) and will not recognize that memory is allocated (although many wrappers will be recognized). In this case, the analyzer does not recognize that the memory was allocated and issues this warning. To suppress the false positive, use a `#pragma` directive on the line that precedes the opening brace `{` of the function body. - -To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ```cpp // cl.exe /analyze /EHsc /nologo /W4 @@ -92,7 +96,6 @@ const int TEST_DATA [ARRAYSIZE] = {10,20,30,40,50,60,70,80,90,100}; void f( ) { - unique_ptr p(new int[ARRAYSIZE]); std::copy(begin(TEST_DATA), end(TEST_DATA), p.get()); @@ -110,4 +113,4 @@ int main( ) ## See also -[C6211](../code-quality/c6211.md) +[Warning C6211](../code-quality/c6211.md) diff --git a/docs/code-quality/c6029.md b/docs/code-quality/c6029.md index 8f502d08fea..2fd6c711b0a 100644 --- a/docs/code-quality/c6029.md +++ b/docs/code-quality/c6029.md @@ -1,80 +1,92 @@ --- -description: "Learn more about: C6029" -title: C6029 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6029"] +title: "Warning C6029" +description: "Learn more about: Warning C6029" +ms.date: 2/07/2023 +f1_keywords: ["C6029", "USING_TAINTED_DATA", "__WARNING_USING_TAINTED_DATA"] helpviewer_keywords: ["C6029"] -ms.assetid: 07f89261-1b77-4597-9f34-12ce5d569b60 --- -# C6029 +# Warning C6029 -> warning C6029: possible buffer overrun in call to \: use of unchecked value +> Possible buffer overrun in call to '*function*' -This warning indicates that a function that takes a buffer and a size is being passed a unchecked size. The data read-in from some external source has not been verified to see whether it is smaller than the buffer size. An attacker might intentionally specify a much larger than expected value for the size, which will lead to a buffer overrun. +## Remarks -Generally, whenever you read data from an untrusted external source, make sure to verify it for validity. It is usually appropriate to verify the size to make sure it is in the expected range. +Possible buffer overrun in called function due to an unchecked buffer length/size parameter. + +This warning indicates that code passes an unchecked size to a function that takes a buffer and a size. The code doesn't verify that the data read from some external source is smaller than the buffer size. An attacker might intentionally specify a larger than expected value for the size, which can lead to a buffer overrun. Generally, whenever you read data from an untrusted external source, make sure to verify it for validity. It's appropriate to verify the size to make sure it's in the expected range. + +Code analysis name: `USING_TAINTED_DATA` ## Example -The following code generates this warning by calling the annotated function [ReadFile](/windows/desktop/api/fileapi/nf-fileapi-readfile) two times. After the first call, the Post attribute property marks the second parameter value untrusted. Therefore, passing an untrusted value in the second call to `ReadFile` generates this warning as shown in the following code: +The following code generates this warning when it calls the annotated function `std::fread` two times. The code uses the first call to determine the length of the data to read in later calls. After the first call, analysis marks `dataSize` as coming from an untrusted source. Therefore, when the code passes the untrusted value to the second `std::fread` call, the analyzer generates this warning. A malicious actor could modify the file and cause the call to `std::fread` to overflow the `buffer` array. In real world code, you should also handle error recovery based on the return value of `std::fread`. For simplicity, these examples intentionally leave out error recovery code. ```cpp +void processData(FILE* file) +{ + const size_t MAX_BUFFER_SIZE = 100; + uint32_t buffer[MAX_BUFFER_SIZE]{}; + uint8_t dataSize = 0; + + // Read length data from the beginning of the file + fread(&dataSize, sizeof(uint8_t), 1, file); + // Read the rest of the data based on the dataSize + fread(buffer, sizeof(uint32_t), dataSize, file); +} +``` -#include "windows.h" +The fix for the issue depends on the nature of the data and the behavior of the annotated function that triggers the diagnostic. For more information, see the documentation for that function. A straightforward fix is to check the size before the second call to `std::fread`. In the next example, we throw an exception to terminate the function. Most real-world code would instead have an error recovery strategy that's specific to the scenario. -bool f(HANDLE hFile) +```cpp +void processData(FILE* file) { - char buff[MAX_PATH]; + const size_t MAX_BUFFER_SIZE = 100; + uint32_t buffer[MAX_BUFFER_SIZE]{}; + uint8_t dataSize = 0; - DWORD cbLen; - DWORD cbRead; + fread(&dataSize, sizeof(uint32_t), 1, file); - // Read the number of byte to read (cbLen). - if (!ReadFile (hFile, &cbLen, sizeof (cbLen), &cbRead, NULL)) - { - return false; - } - // Read the bytes - if (!ReadFile (hFile, buff, cbLen, &cbRead, NULL)) // warning C6029 + if (dataSize > MAX_BUFFER_SIZE) { - return false; + throw std::runtime_error("file data unexpected size"); } - return true; + fread(buffer, sizeof(uint32_t), dataSize, file); } ``` -To correct this warning, check the buffer size as shown in the following code: +In `std::fread` and similar functions, the code may need to read large amounts of data. To handle large data, you can allocate the size of the buffer dynamically after the size becomes known. Or, you can call `std::fread` multiple times as needed to read in the rest of the data. If you allocate the buffer dynamically, we recommend you put a limit on the size to avoid introducing an out-of-memory exploit for large values. We don't use this approach in our example because it's already bounded by the size of `uint8_t`. ```cpp -bool f(HANDLE hFile) +void processDataDynamic(FILE* file) { - char buff[MAX_PATH]; + uint8_t dataSize = 0; + fread(&dataSize, sizeof(uint8_t), 1, file); + + // Vector with `dataSize` default initialized objects + std::vector vecBuffer(dataSize); - DWORD cbLen; - DWORD cbRead; + fread(&vecBuffer[0], sizeof(uint32_t), dataSize, file); +} +void processDataMultiple(FILE* file) +{ + const size_t MAX_BUFFER_SIZE = 100; + uint32_t buffer[MAX_BUFFER_SIZE]{}; + uint8_t dataSize = 0; - // Read the number of byte to read (cbLen). - if (!ReadFile (hFile, &cbLen, sizeof (cbLen), &cbRead, NULL)) - { - return false; - } - // Ensure that there's enough space in the buffer to read that many bytes. - if (cbLen > sizeof(buff)) - { - return false; - } - // Read the bytes - if (!ReadFile (hFile, buff, cbLen, &cbRead, NULL)) // warning C6029 + fread(&dataSize, sizeof(uint32_t), 1, file); + + while( dataSize > 0 ) { - return false; + size_t readSize = dataSize > MAX_BUFFER_SIZE ? MAX_BUFFER_SIZE : dataSize; + readSize = fread(buffer, sizeof(uint32_t), readSize, file); + dataSize = dataSize - readSize; + // Process the data in `buffer`... } - - return true; } ``` ## See also -- [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) +[Rule sets for C++ code](./using-rule-sets-to-specify-the-cpp-rules-to-run.md)\ +[Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) diff --git a/docs/code-quality/c6030.md b/docs/code-quality/c6030.md new file mode 100644 index 00000000000..ab0f26a88e8 --- /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 010c322ebe7..f134bddcc00 100644 --- a/docs/code-quality/c6031.md +++ b/docs/code-quality/c6031.md @@ -1,56 +1,62 @@ --- -title: C6031 +title: "Warning C6031" description: "Describes C++ Code Analysis warning C6031 and how to resolve it." -ms.date: 03/16/2020 -ms.topic: reference -f1_keywords: ["C6031"] +ms.date: 4/5/2024 +f1_keywords: ["C6031", "RETVAL_IGNORED_FUNC_COULD_FAIL", "__WARNING_RETVAL_IGNORED_FUNC_COULD_FAIL"] helpviewer_keywords: ["C6031"] -ms.assetid: 59e1ef0a-b3ca-4ffa-bcb3-ad2bd22ece22 --- -# C6031 +# Warning C6031 -> warning C6031: return value ignored: *called-function* could return unexpected value +> Return value ignored: '*called-function*' could return unexpected value -This warning indicates the caller doesn't check a function's return value for failure. Depending on which function is being called, this defect can lead to seemingly random program misbehavior. That includes crashes and data corruptions in error conditions or low-resource situations. +## Remarks + +Warning C6031 indicates the caller doesn't check a function's return value for failure. Depending on which function is being called, this defect can lead to seemingly random program misbehavior. That includes crashes and data corruptions in error conditions or low-resource situations. In general, it isn't safe to assume that calls to functions requiring disk, network, memory, or other resources will succeed. The caller should always check the return value and handle error cases appropriately. Also consider using the `_Must_inspect_result_` annotation, which checks that the value is examined in a useful way. -## Example +This warning applies to both C and C++ code. -The following code generates this warning: +Code analysis name: `RETVAL_IGNORED_FUNC_COULD_FAIL` -```cpp +## Examples + +The following code generates warning C6031: + +```c #include -void f( ) +int main() { - fopen( "test.c", "r" ); // C4996, C6031 return value ignored + fopen("test.c", "r"); // C4996, C6031 return value ignored // code ... } ``` To correct this warning, check the return value of the function as shown in the following code: -```cpp +```c #include -void f( ) +int main() { - FILE *stream; - if ( (stream = fopen( "test.c", "r" )) == NULL ) + FILE* stream; + if ((stream = fopen("test.c", "r")) == NULL) + { return; + } // code ... } ``` The following code uses safe function `fopen_s` to correct this warning: -```cpp +```c #include -void f( ) +int main() { - FILE *stream; + FILE* stream; errno_t err; - if ( (err = fopen_s( &stream, "test.c", "r" )) !=0 ) + if ((err = fopen_s(&stream, "test.c", "r")) != 0) { // code ... } @@ -61,11 +67,14 @@ This warning is also generated if the caller ignores the return value of a funct ```cpp #include -_Check_return_ bool func(); +_Check_return_ bool func() +{ + return true; +} -void test_f() +int main() { - func(); // Warning C6031 + func(); } ``` @@ -73,25 +82,31 @@ To correct the previous warning, check the return value as shown in the followin ```cpp #include -_Check_return_ bool func(); +_Check_return_ bool func() +{ + return true; +} -void test_f() +int main() { - if ( func() ) { + if (func()) + { // code ... } } ``` -In cases where it is necessary to ignore the return value of a function, assign the returned value to `std::ignore`. Assigning to `std::ignore` clearly indicates developer intent and helps in future code maintenance. +In cases where it's necessary to ignore the return value of a function, assign the returned value to `std::ignore`. Assigning to `std::ignore` clearly indicates developer intent and helps in future code maintenance. ```cpp #include #include +#include #include -void f() + +int main() { - std::srand(static_cast(std::time(nullptr))); // set initial seed value to system clock + std::srand(static_cast(std::time(nullptr))); // set initial seed value to system clock std::ignore = std::rand(); // Discard the first result as the few random results are always small. // ... } diff --git a/docs/code-quality/c6053.md b/docs/code-quality/c6053.md index e5ba91e8541..80c15b91dd2 100644 --- a/docs/code-quality/c6053.md +++ b/docs/code-quality/c6053.md @@ -1,26 +1,27 @@ --- -description: "Learn more about: C6053" -title: C6053 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6053"] +title: "Warning C6053" +description: "Learn more about: Warning C6053" +ms.date: 10/04/2022 +f1_keywords: ["C6053", "MISSING_ZERO_TERMINATION1", "__WARNING_MISSING_ZERO_TERMINATION1"] helpviewer_keywords: ["C6053"] -ms.assetid: 8e25566a-e3b9-470a-820d-64221a877c53 --- -# C6053 +# Warning C6053 -> warning C6053: call to \ may not zero-terminate string \ +> Call to '*function*' may not zero-terminate string '*variable*'. -This warning indicates that the specified function has been called in such a way that the resulting string might not be zero-terminated. This defect might cause an exploitable buffer overrun or crash. This warning is also generated if an annotated function expects a null terminated string is passed a string that is not null terminated. +## Remarks -Most C standard library and Win32 string handling functions require and produce zero-terminated strings. A few 'counted string' functions (including `strncpy`, `wcsncpy`, `_mbsncpy`, `_snprintf`, and `snwprintf`) do not produce zero-terminated strings if they exactly fill their buffer. In this case, a subsequent call to a string function that expects a zero-terminated string will go beyond the end of the buffer looking for the zero. The program should make sure that the string ends with a zero. In general, you should pass a length to the 'counted string' function one smaller than the size of the buffer and then explicitly assign zero to the last character in the buffer. +This warning indicates that the specified function has been called in such a way that the resulting string might not be zero-terminated. This defect might cause an exploitable buffer overrun or crash. This warning is also generated if an annotated function expects a null-terminated string, but you pass a non-null-terminated string. -## Examples +Most C standard library and Win32 string handling functions require and produce zero-terminated strings. A few 'counted string' functions (including `strncpy`, `wcsncpy`, `_mbsncpy`, `_snprintf`, and `snwprintf`) don't produce zero-terminated strings if they exactly fill their buffer. In this case, a subsequent call to a string function that expects a zero-terminated string will go beyond the end of the buffer looking for the zero. The program should make sure that the string ends with a zero. In general, you should pass a length to the 'counted string' function one smaller than the size of the buffer and then explicitly assign zero to the last character in the buffer. -The following sample code generates this warning: +Code analysis name: `MISSING_ZERO_TERMINATION1` -```cpp +## Example + +The following example code generates this warning: +```cpp #include #define MAX 15 @@ -34,10 +35,9 @@ size_t f( ) } ``` -To correct this warning, zero-terminate the string as shown in the following sample code: +To correct this warning, zero-terminate the string as shown in the following example code: ```cpp - #include #define MAX 15 @@ -52,10 +52,9 @@ size_t f( ) } ``` -The following sample code corrects this warning using safe string manipulation `strncpy_s` function: +The following example code corrects this warning using safe string manipulation `strncpy_s` function: ```cpp - #include #define MAX 15 @@ -69,9 +68,11 @@ size_t f( ) } ``` -You should note that this warning is sometimes reported on certain idioms guaranteed to be safe in practice. Because of the frequency and potential consequences of this defect, the analysis tool is biased in favor of finding potential issues instead of its typical bias of reducing noise. +## Heuristics + +This warning is sometimes reported on certain idioms guaranteed to be safe in practice. Because of the frequency and potential consequences of this defect, the analysis tool is biased in favor of finding potential issues instead of its typical bias of reducing noise. ## See also - [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) -- [strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +- [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) diff --git a/docs/code-quality/c6054.md b/docs/code-quality/c6054.md index 8abfba08f36..32962f45ea6 100644 --- a/docs/code-quality/c6054.md +++ b/docs/code-quality/c6054.md @@ -1,26 +1,26 @@ --- -title: C6054 +title: "Warning C6054" description: "Reference guide to Microsoft C++ code analysis warning C6054." -ms.date: 04/22/2020 -ms.topic: reference -f1_keywords: ["C6054"] +ms.date: 10/04/2022 +f1_keywords: ["C6054", "MISSING_ZERO_TERMINATION2", "__WARNING_MISSING_ZERO_TERMINATION2"] helpviewer_keywords: ["C6054"] -ms.assetid: d573a5c1-7e74-402b-92e6-8085f967aa50 --- -# C6054 +# Warning C6054 -> warning C6054: string \ may not be zero-terminated +> String '*variable*' may not be zero-terminated. ## Remarks This warning indicates that a function that requires a zero-terminated string was passed a non-zero terminated string. A function that expects a zero-terminated string could look for the zero beyond the end of the buffer. This defect might cause an exploitable buffer overrun error or crash. The program should make sure the string passed in ends with a zero. +Code analysis name: `MISSING_ZERO_TERMINATION2` + ## Example The following code generates this warning: ```cpp -// C6054_bad.cpp +// Warning C6054_bad.cpp // Compile using: cl /W4 /EHsc /c /analyze C6054_bad.cpp #include @@ -33,7 +33,7 @@ void g ( ) } ``` -To correct this warning, null-terminate `wcArray` before calling function `func()` as shown in the following sample code: +To correct this warning, null-terminate `wcArray` before calling function `func()` as shown in the following example code: ```cpp // C6054_good.cpp @@ -51,5 +51,5 @@ void g ( ) ## See also -- [C6053](../code-quality/c6053.md) +- [Warning C6053](../code-quality/c6053.md) - [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) diff --git a/docs/code-quality/c6059.md b/docs/code-quality/c6059.md index f8c1c0c7b04..2678b0fd252 100644 --- a/docs/code-quality/c6059.md +++ b/docs/code-quality/c6059.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6059" -title: C6059 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6059"] +title: "Warning C6059" +description: "Learn more about: Warning C6059" +ms.date: 12/14/2023 +f1_keywords: ["C6059", "BAD_CONCATENATION", "__WARNING_BAD_CONCATENATION"] helpviewer_keywords: ["C6059"] -ms.assetid: 343a4cd1-048a-4edf-bb4b-187097bb6093 --- -# C6059 +# Warning C6059 -> warning C6059: Incorrect length parameter in call to \. Pass the number of remaining characters, not the buffer size of \ +> Incorrect length parameter in call to '*function*'. Pass the number of remaining characters, not the buffer size of '*variable*'. -This warning indicates that a call to a string concatenation function is probably passing an incorrect value for the number of characters to concatenate. This defect might cause an exploitable buffer overrun or crash. A common cause of this defect is passing the buffer size, instead of the remaining number of characters in the buffer, to the string manipulation function. +## Remarks + +This warning indicates that a call to a string concatenation function is probably passing an incorrect value for the number of characters to concatenate. This defect might cause an exploitable buffer overrun or crash. A common cause of this defect is passing the buffer size (instead of the remaining number of characters in the buffer) to the string manipulation function. + +This warning helps identify the common error of sending the size of the target buffer instead of the size of the data. It does so by detecting when the size used to allocate the buffer is passed, unchanged, to the function putting data in the buffer. + +Code analysis name: `BAD_CONCATENATION` ## Example -The following code generates this warning: +The following code generates warning C6059: ```cpp #include @@ -24,12 +28,12 @@ The following code generates this warning: void f( ) { char szTarget[MAX]; - char *szState ="Washington"; - char *szCity="Redmond, "; + const char *szState ="Washington"; + const char *szCity="Redmond, "; - strncpy(szTarget,szCity, MAX); + strncpy(szTarget, szCity, MAX); szTarget[MAX -1] = '\0'; - strncat(szTarget, szState, MAX); //wrong size + strncat(szTarget, szState, MAX); // wrong size // code ... } ``` @@ -43,30 +47,30 @@ To correct this warning, use the correct number of characters to concatenate as void f( ) { char szTarget[MAX]; - char *szState ="Washington"; - char *szCity="Redmond, "; + const char *szState ="Washington"; + const char *szCity="Redmond, "; - strncpy(szTarget,szCity, MAX); + strncpy(szTarget, szCity, MAX); szTarget[MAX -1] = '\0'; strncat(szTarget, szState, MAX - strlen(szTarget)); // correct size // code ... } ``` -To correct this warning using the safe string manipulation function, see the following code: +To correct this warning using the safe string manipulation functions `strncpy_s` and `strncat_s`, see the following code: ```cpp #include void f( ) { - char *szState ="Washington"; - char *szCity="Redmond, "; + const char *szState ="Washington"; + const char *szCity="Redmond, "; size_t nTargetSize = strlen(szState) + strlen(szCity) + 1; char *szTarget= new char[nTargetSize]; - strncpy_s(szTarget, nTargetSize, szCity,strlen(szCity)); + strncpy_s(szTarget, nTargetSize, szCity, strlen(szCity)); strncat_s(szTarget, nTargetSize, szState, nTargetSize - strlen(szTarget)); // code ... @@ -74,7 +78,49 @@ void f( ) } ``` +## Heuristics + +This analysis detects when the target buffer size is passed unmodified into the length parameter of the string manipulation function. This warning isn't given if some other value is passed as the length parameter, even if that value is incorrect. + +Consider the following code that generates warning C6059: + +```cpp +#include +#define MAX 25 + +void f( ) +{ + char szTarget[MAX]; + const char *szState ="Washington"; + const char *szCity="Redmond, "; + + strncpy(szTarget, szCity, MAX); + szTarget[MAX -1] = '\0'; + strncat(szTarget, szState, MAX); // wrong size + // code ... +} +``` + +The warning goes away by changing the `MAX` argument to `strncat` to `MAX - 1`, even though the length calculation is still incorrect. + +```cpp +#include +#define MAX 25 + +void f( ) +{ + char szTarget[MAX]; + const char *szState ="Washington"; + const char *szCity="Redmond, "; + + strncpy(szTarget, szCity, MAX); + szTarget[MAX -1] = '\0'; + strncat(szTarget, szState, MAX - 1); // wrong size, but no warning + // code ... +} +``` + ## See also -- [strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) -- [strncat_s, _strncat_s_l, wcsncat_s, _wcsncat_s_l, _mbsncat_s, _mbsncat_s_l](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) +- [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +- [`strncat_s`, `_strncat_s_l`, `wcsncat_s`, `_wcsncat_s_l`, `_mbsncat_s`, `_mbsncat_s_l`](../c-runtime-library/reference/strncat-s-strncat-s-l-wcsncat-s-wcsncat-s-l-mbsncat-s-mbsncat-s-l.md) diff --git a/docs/code-quality/c6063.md b/docs/code-quality/c6063.md index bd9058ce89c..23882eb5492 100644 --- a/docs/code-quality/c6063.md +++ b/docs/code-quality/c6063.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6063" -title: C6063 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6063"] +title: "Warning C6063" +description: "Learn more about: Warning C6063" +ms.date: 2/22/2023 +f1_keywords: ["C6063", "MISSING_STRING_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_MISSING_STRING_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6063"] -ms.assetid: 9a4b0684-6c13-4242-a1ab-97980b6cfdc4 --- -# C6063 +# Warning C6063 -> warning C6063: missing string argument to \ corresponding to conversion specifier \ +> Missing string argument to '*function*' that corresponds to conversion specifier '*number*'. -This warning indicates that not enough arguments are being provided to match a format string; at least one of the missing arguments is a string. This defect can cause crashes and buffer overflows (if the called function is of the `sprintf` family), as well as potentially incorrect output. +## Remarks + +This warning indicates that not enough arguments are being provided to match a format string. At least one of the missing arguments is a string. This defect can cause crashes and buffer overflows (if the called function is of the `sprintf` family), and also potentially incorrect output. + +Code analysis name: `MISSING_STRING_ARGUMENT_TO_FORMAT_FUNCTION` ## Example The following code generates this warning: ```cpp -#include +#include void f( ) { char buff[15]; @@ -26,10 +28,10 @@ void f( ) } ``` -To correct this warning, provide additional arguments as shown in the following code: +To correct this warning, remove the unused format specifier or provide the required arguments as shown in the following code: ```cpp -#include +#include void f( ) { char buff[15]; @@ -40,7 +42,7 @@ void f( ) The following code corrects this warning using safe string manipulation function: ```cpp -#include +#include void f( ) { char buff[15]; @@ -50,4 +52,5 @@ void f( ) ## See also +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ [sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) diff --git a/docs/code-quality/c6064.md b/docs/code-quality/c6064.md index 8243a635fa8..2bf2c32b05d 100644 --- a/docs/code-quality/c6064.md +++ b/docs/code-quality/c6064.md @@ -1,59 +1,53 @@ --- -description: "Learn more about: C6064" -title: C6064 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6064"] +title: "Warning C6064" +description: "Learn more about: Warning C6064" +ms.date: 9/29/2025 +f1_keywords: ["C6064", "MISSING_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_MISSING_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6064"] -ms.assetid: d8f126aa-b093-440e-820f-65b8e6cffaba --- -# C6064 +# Warning C6064 -> warning C6064: missing integer argument to \ corresponding to conversion specifier \ +> Missing integer argument to '*function-name*' corresponding to conversion specifier '*number*' -This warning indicates that not enough arguments are being provided to match a format string and one of the missing arguments is an integer. This defect can cause incorrect output. +## Remarks -## Example +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. -The following code generates this warning because an incorrect number of arguments were used in call to `sprintf` and the missing argument was an integer: +Providing too few arguments to a format function leads to undefined behavior because the function attempts to read values that aren't passed. Possible consequences include incorrect output, crashes, or even security vulnerabilities such as information leaks. -```cpp -#include -void f( ) -{ - char buff[15]; - char *string="Hello, World"; +To ensure stability and safety, always match the number and types of arguments to the format specifiers in the string. - sprintf(buff,"%s %d", string); -} -``` +Code analysis name: `MISSING_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION` -To correct this warning, specify missing arguments as shown in the following code: +## Example + +The following code generates this warning when code analysis is enabled (Project properties > **Configuration Properties** > **Code Analysis ** > **General** > **Enable Code Analysis on Build**) because it uses an incorrect number of arguments in the call to `sprintf_s` and the missing argument is an integer. If the unsafe function `sprintf` was used instead of the safer variant `sprintf_s`, this code would likely cause a stack overflow instead of just an unexpected output: ```cpp -#include -void f( ) +void f() { - char buff[15]; - char *string = "Hello, World"; - - sprintf(buff,"%s %d",string, strlen(string)); + char buff[8]; + const char *string="Hello"; + sprintf_s(buff, sizeof(buff), "%s %d", string); // Attempts to print "Hello " + // followed by a number up to eleven characters long, depending on the garbage + // found on the stack. Any number other than a single non-negative digit can't + // fit in the 8 char buffer and leave room for the trailing null. If sprintf + // had been used instead, it would overflow. } ``` -The following code uses safe string manipulation function, `sprintf_s` to correct this warning: +To correct this warning, specify the missing arguments or adjust the format string. In this example, we add the missing integer value. ```cpp -#include -void f( ) +void f() { - char buff[15]; - char *string="Hello World"; - - sprintf_s(buff,sizeof(buff),"%s %d", string, strlen(string)); + char buff[8]; + const char *string = "Hello"; + sprintf_s(buff, sizeof(buff), "%s %d", string, strlen(string)); } ``` ## See also -[sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4473](../error-messages/compiler-warnings/c4473.md) diff --git a/docs/code-quality/c6065.md b/docs/code-quality/c6065.md new file mode 100644 index 00000000000..915ba25f3e1 --- /dev/null +++ b/docs/code-quality/c6065.md @@ -0,0 +1,46 @@ +--- +title: "Warning C6065" +description: "Learn more about: 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 d2f755aa6e1..8bdd672541d 100644 --- a/docs/code-quality/c6066.md +++ b/docs/code-quality/c6066.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6066" -title: C6066 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6066"] +title: "Warning C6066" +description: "Learn more about: Warning C6066" +ms.date: 3/02/2023 +f1_keywords: ["C6066", "NON_POINTER_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_POINTER_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6066"] -ms.assetid: f03c9cf1-d8eb-4731-a66a-da7c924616fb --- -# C6066 +# Warning C6066 -> warning C6066: non-pointer passed as parameter \ when pointer is required in call to \ +> Non-pointer passed as parameter(*number*) when pointer is required in call to '*function*'. -This warning indicates that the format string specifies that a pointer is required, for example, a `%n` or `%p` specification for printf or a `%d` for `scanf`, but a non-pointer is being passed. This defect is likely to cause a crash or corruption of some form. +## Remarks + +This warning indicates that the format string specifies that a pointer is required, but a non-pointer is being passed. A pointer is required, for example, when you use a `%n` or `%p` specification for `printf`, or a `%d` for `scanf`. This defect is likely to cause a crash or corruption of some form. + +Code analysis name: `NON_POINTER_ARGUMENT_TO_FORMAT_FUNCTION` ## Example @@ -29,8 +31,7 @@ void f( ) void g( int i ) { - int result; - result = scanf( "%d", i ); // warning C6066 + int result = scanf( "%d", i ); // warning C6066 // code ... } ``` @@ -44,41 +45,38 @@ To correct this warning, the following code passes correct parameters to the `sp void f( ) { char buff[MAX]; - sprintf( buff, "%s %p %d", "Hello, World!", buff, MAX ); // pass buff // code ... } void g( int i ) { - int result; - // code ... - result = scanf( "%d", &i ); // pass the address of i + int result = scanf( "%d", &i ); // pass the address of i // code ... } ``` -The following code use safe string manipulation functions — `sprintf_s` and `scanf_s` — to correct this warning: +The following code uses safe string manipulation functions `sprintf_s` and `scanf_s` to correct this warning: ```cpp void f( ) { char buff[MAX]; - sprintf_s( buff, sizeof(buff), "%s %p %d", "Hello, World!", buff, MAX ); // code ... } void g( int i ) { - int result; - // code ... - result = scanf_s( "%d", &i ); + int result = scanf_s( "%d", &i ); // code ... } ``` -This warning is typically reported because an integer has been used for a `%p` format instead of a pointer. Using an integer in this instance is not portable to 64-bit computers. +This warning is typically reported because an integer has been used for a `%p` format instead of a pointer. Using an integer in this instance isn't portable to 64-bit computers. ## See also -- [sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) -- [scanf_s, _scanf_s_l, wscanf_s, _wscanf_s_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[`scanf_s`, `_scanf_s_l`, `wscanf_s`, `_wscanf_s_l`](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[C4313](../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6067.md b/docs/code-quality/c6067.md index 9cf2b51d2da..e2546bfb680 100644 --- a/docs/code-quality/c6067.md +++ b/docs/code-quality/c6067.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6067" -title: C6067 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6067"] +title: "Warning C6067" +description: "Learn more about: Warning C6067" +ms.date: 3/02/2023 +f1_keywords: ["C6067", "NON_STRING_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_STRING_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6067"] -ms.assetid: 6fbaee53-daaa-4ba5-9b11-2a8066d86240 --- -# C6067 +# Warning C6067 -> warning C6067: parameter \ in call to \ must be the address of the string +> Parameter '*number*' in call to '*function*' must be the address of the string + +## Remarks This warning indicates a mismatch between the format specifier and the function parameter. Even though the warning suggests using the address of the string, you must check the type of parameter a function expects before correcting the problem. For example, a `%s` specification for `printf` requires a string argument, but a `%s` specification in `scanf` requires an address of the string. This defect is likely to cause a crash or corruption of some form. -## Example +Code analysis name: `NON_STRING_ARGUMENT_TO_FORMAT_FUNCTION` + +## Examples The following code generates this warning because an integer is passed instead of a string: @@ -25,7 +27,7 @@ The following code generates this warning because an integer is passed instead o void f_defective() { char *str = "Hello, World!"; - printf("String:\n %s", 1); // warning + printf("String:\n %s", 1); // code ... } ``` @@ -97,6 +99,9 @@ void f_safe() ## See also -- [sprintf\_s, \_sprintf\_s\_l, swprintf\_s, \_swprintf\_s\_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) -- [printf, \_printf\_l, wprintf, \_wprintf\_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md) -- [scanf\_s, \_scanf\_s\_l, wscanf\_s, \_wscanf\_s\_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[sprintf\_s, \_sprintf\_s\_l, swprintf\_s, \_swprintf\_s\_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[printf, \_printf\_l, wprintf, \_wprintf\_l](../c-runtime-library/reference/printf-printf-l-wprintf-wprintf-l.md)\ +[scanf\_s, \_scanf\_s\_l, wscanf\_s, \_wscanf\_s\_l](../c-runtime-library/reference/scanf-s-scanf-s-l-wscanf-s-wscanf-s-l.md)\ +[C4313](../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6101.md b/docs/code-quality/c6101.md index 6294816d293..11dd9b17a78 100644 --- a/docs/code-quality/c6101.md +++ b/docs/code-quality/c6101.md @@ -1,14 +1,86 @@ --- -description: "Learn more about: C6101" -title: C6101 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6101"] +title: "Warning C6101" +description: "Learn more about: Warning C6101" +ms.date: 02/7/2023 +f1_keywords: ["C6101", "RETURN_UNINIT_VAR", "__WARNING_RETURN_UNINIT_VAR"] helpviewer_keywords: ["C6101"] -ms.assetid: 8546367c-5de5-479a-a231-c15c0aa89ef1 --- -# C6101 +# Warning C6101 -> warning C6101: Returning uninitialized memory +> Returning uninitialized memory '*parameter-name*'. -A successful path through the function does not set the named `_Out_` parameter. This message is generated based on SAL annotations that indicate that the function in question always succeeds. A function that doesn't return a success/failure indication should set all of its `_Out_` parameters because the analyzer assumes that the `_Out_` parameter is uninitialized data before the function is called, and that the function will set the parameter so that it's no longer uninitialized. If the function does indicate success/failure, then the `_Out_` parameter doesn't have to be set in the case of failure, and you can detect and avoid the uninitialized location. In either case, the objective is to avoid the reading of an uninitialized location. If the function sometimes doesn't touch an `_Out_` parameter that's subsequently used, then the parameter should be initialized before the function call and be marked with the `_Inout_` annotation, or the more explicit `_Pre_null_` or `_Pre_satisfies_()` when appropriate. "Partial success" can be handled with the `_When_` annotation. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +## Remarks + +A successful path through the function doesn't set the `_Out_` annotated parameter. + +The purpose of this warning is to avoid the use of uninitialized values by callers of the function. The analyzer assumes callers don't initialize any parameters annotated with `_Out_` before the function call, and checks that the function initializes them. The analyzer doesn't emit this warning if the function returns a value that indicates it had an error or wasn't successful. To fix this issue, make sure to initialize the `_Out_` parameter under all successful return paths. The error message contains the line numbers of an example path that doesn't initialize the parameter. + +If the initialization behavior is by design, then incorrect or missing SAL annotations are a likely cause for the warning. You can typically resolve these cases in one of two ways: Either change `_Out_` to a more appropriate annotation, or use the `_Success_()` annotation to help define the success/error states of the function. It's important for the static analysis tools to have correct annotations on the function when analyzing the call sites of the function. + +### Fix by changes to parameter annotations + +If the parameter should already be in an initialized state and the function conditionally modifies it, then the `_Inout_` annotation may be more appropriate. If no other high level annotation fits the intended behavior, you can use low level annotations such as `_Pre_null_`, `_Pre_satisfies_()`, and `_Post_satisfies_()` that provide extra flexibility and control over the expected state of the parameter. For more information on parameter annotations, see [Annotating function parameters and return values](./annotating-function-parameters-and-return-values.md). + +### Fix by defining successful return paths + +The analyzer only emits this warning when the code doesn't initialize an `_Out_` parameter in the success paths of the function. If there's no `_Success_` annotation and no function return type annotation, then it considers all return paths successful. For more information on `_Success_` and similar annotations, see [Success/Failure annotations](./annotating-function-behavior.md#successfailure-annotations). + +Code analysis name: `RETURN_UNINIT_VAR` + +## Example + +The following code generates this warning. Because the function returns `void`, the analyzer considers all paths successful. In this case, the correct fix would probably be to adjust the logic of the `if` statement, but in real world code it's typically not as straightforward and the solution depends on the intended behavior of the function. + +```cpp +#include +void AlwaysInit(_Out_ int* output, int input) // : warning C6101: Returning uninitialized memory '*p'.: Lines: 2, 4, 9, 14, 2 +{ + if( input > 0 ) + { + *output = input; + return; + } + else if( input < 0 ) + { + *output = 0; + return; + } + return; // Oops, input was 0 +} +``` + +To make the solution more interesting, we assume that it isn't valid to initialize `output` when `input` is `0`. One approach is to modify the function return value to a different type, such as `bool`. Then, add a `_Success_` annotation to define the successful return paths. + +```cpp +_Success_(return == true) +bool InitNotZero(_Out_ int* output, int input) +{ + if( input > 0 ) + { + *output = input; + return true; + } + else if( input < 0 ) + { + *output = 0; + return true; + } + return false; +} +``` + +If this pattern is common in your codebase, you can add the annotation to the return type. Error codes such as HRESULT from the Windows SDK give you the behavior of the `_Success_` annotation without needing to add it to each function. If you already use an annotated type as a return type and want to override the behavior, then add the annotation to the function, as shown in the previous example. + +```cpp +using SuccessWhenTrue = _Success_(return == true) bool; + +SuccessWhenTrue InitNotZero(_Out_ int* output, int input) +{ + // ... +} +``` + +## See also + +[Rule sets for C++ code](./using-rule-sets-to-specify-the-cpp-rules-to-run.md)\ +[Using SAL Annotations to Reduce C/C++ Code Defects](./using-sal-annotations-to-reduce-c-cpp-code-defects.md) diff --git a/docs/code-quality/c6102.md b/docs/code-quality/c6102.md index a1abbc5157e..e003c84636b 100644 --- a/docs/code-quality/c6102.md +++ b/docs/code-quality/c6102.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: C6102" -title: C6102 +title: "Warning C6102" +description: "Learn more about: Warning C6102" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6102"] -ms.assetid: cfd49a8c-df46-48de-8dcb-02ecf2450034 +helpviewer_keywords: ["C6102"] --- -# C6102 +# Warning C6102 -> warning C6102: Using \ from failed function call at line \. +> Using '*variable*' from failed function call at line '*location*'. -This warning is reported instead of [C6001](../code-quality/c6001.md) when a variable is not set because it was marked as an `_Out_` parameter on a prior function call that failed. +## Remarks -The problem might be that the prior called function is not completely annotated. It may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation. +This warning is reported instead of [C6001](../code-quality/c6001.md) when a variable isn't set because it was marked as an `_Out_` parameter on a prior function call that failed. + +The problem might be that the prior called function isn't fully annotated. It may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation. ## See also diff --git a/docs/code-quality/c6103.md b/docs/code-quality/c6103.md index 2a24fa43d16..4ab5fd62efe 100644 --- a/docs/code-quality/c6103.md +++ b/docs/code-quality/c6103.md @@ -1,18 +1,19 @@ --- -description: "Learn more about: C6103" -title: C6103 +title: "Warning C6103" +description: "Learn more about: Warning C6103" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6103"] -ms.assetid: 22d1ab35-31a3-4ba9-8ef4-7a64bce66621 +helpviewer_keywords: ["C6103"] --- -# C6103 +# Warning C6103 -> warning C6103: Returning \ from failed function call at line \. +> Returning '*variable*' from failed function call at line '*location*'. + +## Remarks A successful path through the function is returning a variable that was used as an `_Out_` parameter to an internal function call that failed. -The problem might be that the called function and the calling function are not completely annotated. The called function may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation, and the calling function may require a `_Success_` annotation. Another possible cause for this warning is that the `_Success_` annotation on the called function is incorrect. +The problem might be that the called function and the calling function aren't fully annotated. The called function may require `_Always_`, `_Outptr_result_nullonfailure_` (`_COM_Outptr_` for COM code), or a related annotation, and the calling function may require a `_Success_` annotation. Another possible cause for this warning is that the `_Success_` annotation on the called function is incorrect. ## See also diff --git a/docs/code-quality/c6200.md b/docs/code-quality/c6200.md index f8f0234c51d..945df12b0be 100644 --- a/docs/code-quality/c6200.md +++ b/docs/code-quality/c6200.md @@ -1,46 +1,85 @@ --- -description: "Learn more about: C6200" -title: C6200 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6200"] +title: "Warning C6200" +description: "Learn more about: Warning C6200" +ms.date: 08/16/2022 +f1_keywords: ["C6200", "INDEX_EXCEEDS_MAX_NONSTACK", "__WARNING_INDEX_EXCEEDS_MAX_NONSTACK"] helpviewer_keywords: ["C6200"] -ms.assetid: bbeb159b-4e97-4317-9a07-bb83cd03069a --- -# C6200 +# Warning C6200 -> warning C6200: index \ is out of valid index range \ to \ for non-stack buffer \ +> Index '*index*' is out of valid index range '*min*' to '*max*' for nonstack buffer '*parameter-name*' -This warning indicates that an integer offset into the specified array exceeds the maximum bounds of that array. This defect might cause random behavior or crashes. +## Remarks + +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. One common cause of this defect is using the size of an array as an index into the array. Because C/C++ array indexing is zero-based, the maximum legal index into an array is one less than the number of array elements. +Code analysis name: `INDEX_EXCEEDS_MAX_NONSTACK` + ## Example -The following code generates this warning because the **`for`** loop exceeds the index range: +The following code generates this warning. This issue stems from the **`for`** loop exceeding the index range, attempting to access index 14 (the 15th element) when index 13 (the 14th element) is the last: ```cpp -int buff[14]; // array of 0..13 elements void f() { - for (int i=0; i<=14;i++) // i exceeds the index - { - buff[i]= 0; // warning C6200 - // code... - } + int* buff = new int[14]; // array of 0..13 elements + for (int i = 0; i <= 14; i++) // i exceeds the index + { + buff[i] = 0; // warning C6200 + } + delete[] buff; } ``` To correct both warnings, use correct array size as shown in the following code: ```cpp -int buff[14]; // array of 0..13 elements void f() { - for ( int i=0; i < 14; i++) // loop stops when i < 14 - { - buff[i]= 0; // initialize buffer - // code... - } + int* buff = new int[14]; // array of 0..13 elements + for (int i = 0; i < 14; i++) // i == 13 on the final iteration + { + buff[i] = 0; // initialize buffer + } + delete[] buff; } ``` + +## Heuristics + +Code analysis can't always prove whether an array index is in range. This can happen, for example, when the index is computed from a complex expression, including those expressions that call into other functions. In these cases, code analysis may fall back on other clues to determine the range an array index expression may fall into. + +For example, consider the following function that uses `rand()` in index calculations as a stand-in for a function call that code analysis can't analyze: + +```cpp +#include + +void f() +{ + int* buff = new int[14]; + for (int i = 1; i < 14; i++) + { + buff[rand()] = 0; // no warning, nothing is known about the return value of rand() + buff[rand() % 15] = 0; // warning C6200, rand() % 15 is known to be in the range 0..14 and index 14 is out of bounds + buff[rand() % 14] = 0; // no warning, rand() % 14 is known to be in the range 0..13 + } + delete[] buff; +} +``` + +Code analysis doesn't warn with just `rand()` because it doesn't have any information about its return value. On the other hand, `rand() % 15` and `rand() % 14` provide hints as to the range of the return value of `rand()` and code analysis can use that information to determine that the index is out of bounds in the first case but not the second. + +## Disable warning C6200 + +You can disable this warning project-wide by passing the compiler switch `/wd6200`. If you want a more targeted solution, surround the code that generates the warning with: + +```cpp + #pragma warning(push) // save which warnings are enabled/disabled + #pragma warning(disable: 6200) // suppress this warning only in this block + // ... code that intentionally generates C6200 + #pragma warning(pop) // restore the warning state saved with the previous push +``` + +To learn more about pragma directives, see [warning pragma](../preprocessor/warning.md). diff --git a/docs/code-quality/c6201.md b/docs/code-quality/c6201.md index 69b122ae80f..c1ec04f38cc 100644 --- a/docs/code-quality/c6201.md +++ b/docs/code-quality/c6201.md @@ -1,46 +1,52 @@ --- -description: "Learn more about: C6201" -title: C6201 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6201"] +title: "Warning C6201" +description: "Learn more about: Warning C6201" +ms.date: 11/17/2023 +f1_keywords: ["C6201", "INDEX_EXCEEDS_MAX", "__WARNING_INDEX_EXCEEDS_MAX"] helpviewer_keywords: ["C6201"] -ms.assetid: eefbbd77-007c-4f28-95f6-6de5ee6a27db --- -# C6201 +# Warning C6201 -> warning C6201: buffer overrun for \, which is possibly stack allocated: index \ is out of valid index range \ to \ +> Index '*index-name*' is out of valid index range '*minimum*' to '*maximum*' for possibly stack allocated buffer '*variable*' -This warning indicates that an integer offset into the specified stack array exceeds the maximum bounds of that array. This defect might cause random behavior or crashes. +## Remarks + +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. One common cause of this defect is using an array's size as an index into the array. Because C/C++ array indexing is zero-based, the maximum legal index into an array is one less than the number of array elements. +Code analysis name: `INDEX_EXCEEDS_MAX` + ## Example -The following code generates this warning because the array index is out of the valid range: +The following code generates warning C6201. The **`for`** loop condition exceeds the valid index range for `buff` when it sets `i` to 14, which is one element past the end: ```cpp -void f( ) +void f() { - int buff[25]; - for (int i=0; i <= 25; i++) // i exceeds array bound - { - buff[i]=0; // initialize i - // code ... - } + int buff[14]; // array of 0..13 elements + for (int i = 0; i <= 14; i++) // i == 14 exceeds the bounds + { + buff[i] = 0; // initialize buffer + } } ``` -To correct both warnings, use the correct array size as shown in the following code: +To correct the warning, make sure the index stays in bounds. The following code shows the corrected loop condition: ```cpp -void f( ) +void f() { - int buff[25]; - for (int i=0; i < 25; i++) - { - buff[i]=0; // initialize i - // code ... - } + int buff[14]; // array of 0..13 elements + for (int i = 0; i < 14; i++) // i == 13 on the final iteration + { + buff[i]= 0; // initialize buffer + } } ``` + +## Heuristics + +This analysis is limited to stack-allocated arrays. It doesn't consider, for example, arrays passed into the function with a Microsoft source code annotation language ([SAL](understanding-sal.md))-annotated length. + +This analysis can't catch all possible out of bounds indices because not all arithmetic can be precisely analyzed. It's tuned to report cases where it can guarantee an out of bounds index is possible. The absence of a warning doesn't mean the index is guaranteed to be in bounds. diff --git a/docs/code-quality/c6211.md b/docs/code-quality/c6211.md index c162cbb6752..015ad0081c3 100644 --- a/docs/code-quality/c6211.md +++ b/docs/code-quality/c6211.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6211" -title: C6211 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6211"] +title: "Warning C6211" +description: "Learn more about: Warning C6211" +ms.date: 10/03/2022 +f1_keywords: ["C6211", "MEMORY_LEAK_EXCEPTION", "__WARNING_MEMORY_LEAK_EXCEPTION"] helpviewer_keywords: ["C6211"] -ms.assetid: 9b68243b-534c-4a05-b789-bb155dfcba1e --- -# C6211 +# Warning C6211 -> warning C6211: Leaking memory \ due to an exception. Consider using a local catch block to clean up memory +> Leaking memory '*pointer*' due to an exception. Consider using a local catch block to clean up memory -This warning indicates that allocated memory is not being freed when an exception is thrown. The statement at the end of the path could throw an exception. The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +## Remarks + +This warning indicates that allocated memory isn't freed when an exception is thrown. The statement at the end of the path could throw an exception. + +The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +Code analysis name: `MEMORY_LEAK_EXCEPTION` ## Example -The following code generates this warning because an exception could be thrown during the second allocation and thereby leak the first allocation, or an exception could be thrown somewhere in the code that's represented by the "`code ...`" comment and thereby leak both allocations. +The following code generates warning C6211 because an exception could be thrown during the second allocation and thereby leak the first allocation. Or, an exception could be thrown somewhere in the code that's represented by the "`code ...`" comment and thereby leak both allocations. ```cpp // cl.exe /analyze /c /EHsc /nologo /W4 @@ -70,7 +74,7 @@ void f() } ``` -To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ```cpp // cl.exe /analyze /c /EHsc /nologo /W4 @@ -107,4 +111,4 @@ void f( ) ## See also -[C++ Exception Handling](../cpp/exception-handling-in-visual-cpp.md) +[C++ exception handling](../cpp/exception-handling-in-visual-cpp.md) diff --git a/docs/code-quality/c6214.md b/docs/code-quality/c6214.md index 5bfd7b0c830..719f5333c2d 100644 --- a/docs/code-quality/c6214.md +++ b/docs/code-quality/c6214.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6214" -title: C6214 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6214"] +title: "Warning C6214" +description: "Learn more about: Warning C6214" +ms.date: 10/03/2022 +f1_keywords: ["C6214", "CAST_HRESULT_TO_BOOL", "__WARNING_CAST_HRESULT_TO_BOOL"] helpviewer_keywords: ["C6214"] -ms.assetid: 233e2395-61c1-4a3b-a54b-f19a9ffc31a8 --- -# C6214 +# Warning C6214 -> warning C6214: cast between semantically different integer types: HRESULT to a Boolean type +> Cast between semantically different integer types: HRESULT to a Boolean type -This warning indicates that an `HRESULT` is being cast to a Boolean type. The success value (`S_OK`) of an `HRESULT` equals 0. However, 0 indicates failure for a Boolean type. Casting an `HRESULT` to a Boolean type and then using it in a test expression will yield an incorrect result. Sometimes, this warning occurs if an `HRESULT` is being stored in a Boolean variable. Any comparison that uses the Boolean variable to test for `HRESULT` success or failure could lead to incorrect results. +## Remarks + +This warning indicates that an `HRESULT` is being cast to a Boolean type. The success value (`S_OK`) of an `HRESULT` equals 0. However, 0 indicates failure for a Boolean type. Casting an `HRESULT` to a Boolean type and then using it in a test expression will yield an incorrect result. + +Sometimes, this warning occurs if an `HRESULT` is being stored in a Boolean variable. Any comparison that uses the Boolean variable to test for `HRESULT` success or failure could lead to incorrect results. + +Code analysis name: `CAST_HRESULT_TO_BOOL` ## Example -The following code generates this warning: +The following code generates warning C6214: ```cpp #include @@ -66,10 +70,10 @@ For this warning, the `SCODE` type is equivalent to `HRESULT`. Usually, the `SUCCEEDED` or `FAILED` macro should be used to test the value of an `HRESULT`. -For more information, see one of the following topics: +For more information, see one of the following articles: -[SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) +[`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) -[FAILED](/windows/desktop/api/winerror/nf-winerror-failed) +[`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) -To leverage modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To make use of modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6215.md b/docs/code-quality/c6215.md index a332c868c3e..ef513041b8b 100644 --- a/docs/code-quality/c6215.md +++ b/docs/code-quality/c6215.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6215" -title: C6215 +title: "Warning C6215" +description: "Learn more about: Warning C6215" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6215"] +f1_keywords: ["C6215", "CAST_BOOL_TO_HRESULT", "__WARNING_CAST_BOOL_TO_HRESULT"] helpviewer_keywords: ["C6215"] -ms.assetid: f20cc258-9c0f-4eaa-828d-74f76580ca78 --- -# C6215 +# Warning C6215 -> warning C6215: cast between semantically different integer types: a Boolean type to HRESULT +> Cast between semantically different integer types: a Boolean type to HRESULT + +## Remarks This warning indicates that a Boolean is being cast to an `HRESULT`. Boolean types indicate success by a non-zero value, whereas success (`S_OK`) in `HRESULT` is indicated by a value of 0. Casting a Boolean type to an `HRESULT` and then using it in a test expression will yield an incorrect result. This warning frequently occurs when a Boolean is used as an argument to `SUCCEEDED` or `FAILED` macro, which explicitly casts their arguments to an `HRESULT`. +Code analysis name: `CAST_BOOL_TO_HRESULT` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6216.md b/docs/code-quality/c6216.md index d8f4d7463f4..b796a0da137 100644 --- a/docs/code-quality/c6216.md +++ b/docs/code-quality/c6216.md @@ -1,17 +1,21 @@ --- -description: "Learn more about: C6216" -title: C6216 +title: "Warning C6216" +description: "Learn more about: Warning C6216" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6216"] +f1_keywords: ["C6216", "COMPILER_INSERTED_CAST_BOOL_TO_HRESULT", "__WARNING_COMPILER_INSERTED_CAST_BOOL_TO_HRESULT"] helpviewer_keywords: ["C6216"] -ms.assetid: d5c4dcf9-bfd7-4604-804f-9cc41b08d060 --- -# C6216 +# Warning C6216 -> warning C6216: compiler-inserted cast between semantically different integral types: a Boolean type to HRESULT +> Compiler-inserted cast between semantically different integral types: a Boolean type to HRESULT -A Boolean type is being used as an `HRESULT` without being explicitly cast. Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. This means a Boolean false value used as an `HRESULT` would indicate `S_OK`, which is frequently a mistake. +## Remarks + +A Boolean type is being used as an `HRESULT` without being explicitly cast. + +Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. A Boolean `false` value used as an `HRESULT` would indicate `S_OK`, which is frequently a mistake. + +Code analysis name: `COMPILER_INSERTED_CAST_BOOL_TO_HRESULT` ## Example diff --git a/docs/code-quality/c6217.md b/docs/code-quality/c6217.md index aa5952e4725..042364717e6 100644 --- a/docs/code-quality/c6217.md +++ b/docs/code-quality/c6217.md @@ -1,21 +1,27 @@ --- -description: "Learn more about: C6217" -title: C6217 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6217"] +title: "Warning C6217" +description: "Learn more about: Warning C6217" +ms.date: 2/07/2023 +f1_keywords: ["C6217", "TESTING_HRESULT_WITH_NOT", "__WARNING_TESTING_HRESULT_WITH_NOT"] helpviewer_keywords: ["C6217"] -ms.assetid: 93ac7ce2-c27b-4b3a-9a98-72f26fcf1def --- -# C6217 +# Warning C6217 -> warning C6217: Implicit cast between semantically different integer types: testing HRESULT with 'not'. Consider using [SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) or [FAILED](/windows/desktop/api/winerror/nf-winerror-failed) macro instead. +> Implicit cast between semantically different integer types: testing HRESULT with 'not'. Consider using [`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) or [`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) macro instead. -This warning indicates that an `HRESULT` is being tested with the not (`!`) operator. A success (`S_OK`) in `HRESULT` is indicated by a value of 0. However, 0 indicates failure for a Boolean type. Testing `HRESULT` with the not operator (`!`) to determine which code block to run can cause following the wrong code path. This will lead to unwanted results. +## Remarks + +This warning indicates that the code tests an `HRESULT` with the logical-not (`!`) operator. A value of 0 (the value defined for `S_OK`) indicates success in an `HRESULT`. However, 0 also indicates failure for a Boolean type. If you test an `HRESULT` with the logical-not operator (`!`) to determine which code block to run, it can cause incorrect behavior or code that confuses future maintainers. + +To verify whether an `HRESULT` is a success or failure, use the `SUCCEEDED` or `FAILED` macros instead. + +This warning works for both `HRESULT` and `SCODE` types. + +Code analysis name: `TESTING_HRESULT_WITH_NOT` ## Example -The following code generates this warning because the not operator is used to determine success or failure of an `HRESULT` value. In this case, wrong code path is executed because `( !hr )` runs the failure code: +The following code generates this warning because it uses the logical-not (`!`) operator to determine success or failure of an `HRESULT` value. In this case, the code executes the wrong code path because an `HRESULT` of 0 indicates success, so `( !hr )` incorrectly runs the failure code: ```cpp #include @@ -35,7 +41,7 @@ void f( ) } ``` -To correct this warning, the following code uses `FAILED` macro to look for failure: +To correct this warning, the following code uses a `FAILED` macro to check for failure: ```cpp #include @@ -55,8 +61,7 @@ void f( ) } ``` -For this warning, the `SCODE` type is equivalent to `HRESULT`. - -The typical success value of HRESULT (`S_OK`) is **`false`** when it is tested as a Boolean. +## See also -To verify whether `HRESULT` is a success, use the `SUCCEEDED` macro instead. +[`SUCCEEDED` macro](/windows/desktop/api/winerror/nf-winerror-succeeded)\ +[`FAILED` macro](/windows/desktop/api/winerror/nf-winerror-failed) diff --git a/docs/code-quality/c6219.md b/docs/code-quality/c6219.md index 2447d4eca6f..3dabeed9296 100644 --- a/docs/code-quality/c6219.md +++ b/docs/code-quality/c6219.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6219" -title: C6219 +title: "Warning C6219" +description: "Learn more about: Warning C6219" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6219"] +f1_keywords: ["C6219", "COMPARING_HRESULT_TO_ONE", "__WARNING_COMPARING_HRESULT_TO_ONE"] helpviewer_keywords: ["C6219"] -ms.assetid: 889a2de8-c0dc-4e8e-a46b-735384202675 --- -# C6219 +# Warning C6219 -> warning C6219: Implicit cast between semantically different integer types: comparing HRESULT to 1 or TRUE. Consider using [SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) or [FAILED](/windows/desktop/api/winerror/nf-winerror-failed) macro instead +> Implicit cast between semantically different integer types: comparing HRESULT to 1 or TRUE. Consider using [`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) or [`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) macro instead -This warning indicates an `HRESULT` is being compared with an explicit, non-`HRESULT` value of one (1). This comparison is likely to lead to incorrect results, because the typical success value of `HRESULT` (`S_OK`) is 0. If you compare this value to a Boolean type it's implicitly converted to false. +## Remarks + +This warning indicates an `HRESULT` is being compared with an explicit, non-`HRESULT` value of one (1). This comparison is likely to lead to incorrect results, because the typical success value of `HRESULT` (`S_OK`) is 0. If you compare this value to a Boolean type, it's implicitly converted to `false`. + +Code analysis name: `COMPARING_HRESULT_TO_ONE` ## Example diff --git a/docs/code-quality/c6220.md b/docs/code-quality/c6220.md index ea3f5d6a190..b0ad41d021d 100644 --- a/docs/code-quality/c6220.md +++ b/docs/code-quality/c6220.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6220" -title: C6220 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6220"] +title: "Warning C6220" +description: "Learn more about: Warning C6220" +ms.date: 10/03/2022 +f1_keywords: ["C6220", "COMPARING_HRESULT_TO_MINUS_ONE", "__WARNING_COMPARING_HRESULT_TO_MINUS_ONE"] helpviewer_keywords: ["C6220"] -ms.assetid: a13524f4-0a1f-4670-b830-70b06e4d39d2 --- -# C6220 +# Warning C6220 -> warning C6220 - Implicit cast between semantically different integer types: comparing HRESULT to -1. Consider using SUCCEEDED or FAILED macro instead +> Implicit cast between semantically different integer types: comparing HRESULT to -1. Consider using `SUCCEEDED` or `FAILED` macro instead -This warning indicates that an `HRESULT` is being compared with an explicit, non-`HRESULT` value of -1, which is not a well-formed `HRESULT`. A failure in `HRESULT` (`E_FAIL`) is not represented by a -1. Therefore, an implicit cast of an `HRESULT` to an integer will generate an incorrect value and is likely to lead to the wrong result. +## Remarks + +This warning indicates that an `HRESULT` is being compared with an explicit, non-`HRESULT` value of -1, which isn't a well-formed `HRESULT`. + +A failure in `HRESULT` (`E_FAIL`) isn't represented by a -1. Therefore, an implicit cast of an `HRESULT` to an integer will generate an incorrect value and is likely to lead to the wrong result. + +Code analysis name: `COMPARING_HRESULT_TO_MINUS_ONE` ## Example -In most cases, this warning is caused by the code mistakenly expecting that a function that should return an `HRESULT` instead returns an integer, by using -1 as a failure value. The following code sample generates this warning: +In most cases, warning C6220 is caused by code that mistakenly expects a function to return an integer, and to use -1 as a failure value, but instead the function returns an `HRESULT`. The following code example generates this warning: ```cpp #include @@ -39,7 +43,7 @@ HRESULT f( ) } ``` -It is best to use the `SUCCEEDED` or `FAILED` macro to test the value of an `HRESULT`. To correct this warning, use the following code: +It's best to use the `SUCCEEDED` or `FAILED` macro to test the value of an `HRESULT`. To correct this warning, use the following code: ```cpp #include @@ -67,6 +71,6 @@ For this warning, the `SCODE` type is equivalent to `HRESULT`. Explicit comparison is appropriate to check for specific `HRESULT` values, such as, `E_FAIL`. Otherwise, use the `SUCCEEDED` or `FAILED` macros. -For more information, see [SUCCEEDED Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [FAILED Macro](/windows/win32/api/winerror/nf-winerror-failed). +For more information, see [`SUCCEEDED` Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [`FAILED` Macro](/windows/win32/api/winerror/nf-winerror-failed). -Note that the use of malloc and free (and related dynamic memory allocation APIs) have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` (and related dynamic memory allocation APIs) has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6221.md b/docs/code-quality/c6221.md index 7869db2cbd2..c4c2e80c8d5 100644 --- a/docs/code-quality/c6221.md +++ b/docs/code-quality/c6221.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6221" -title: C6221 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6221"] +title: "Warning C6221" +description: "Learn more about: Warning C6221" +ms.date: 10/03/2022 +f1_keywords: ["C6221", "COMPARING_HRESULT_TO_INT", "__WARNING_COMPARING_HRESULT_TO_INT"] helpviewer_keywords: ["C6221"] -ms.assetid: b07989b7-f50f-46e0-8ed8-d9269b3d3580 --- -# C6221 +# Warning C6221 -> warning C6221: Implicit cast between semantically different integer types: comparing HRESULT to an integer. Consider using SUCCEEDED or FAILED macros instead +> Implicit cast between semantically different integer types: comparing HRESULT to an integer. Consider using `SUCCEEDED` or `FAILED` macros instead -This warning indicates that an `HRESULT` is being compared to an integer other than zero. A success in `HRESULT` (`S_OK`) is represented by a 0. Therefore, an implicit cast of an `HRESULT` to an integer will generate an incorrect value and is likely to lead to the wrong result. It is often caused by mistakenly expecting a function to return an integer when it actually returns an `HRESULT`. +## Remarks + +This warning indicates that an `HRESULT` is being compared to an integer other than zero. + +A success in an `HRESULT` (`S_OK`) is represented by a 0. Therefore, an implicit cast of an `HRESULT` to an integer generates an incorrect value and is likely to lead to the wrong result. The error is often caused by mistakenly expecting a function to return an integer when it actually returns an `HRESULT`. + +Code analysis name: `COMPARING_HRESULT_TO_INT` ## Example -The following code generates this warning by comparing `HRESULT` against an integer value: +The following code generates warning C6221 by comparing an `HRESULT` against an integer value: ```cpp #include @@ -65,6 +69,6 @@ HRESULT f( ) For this warning, the `SCODE` type is equivalent to `HRESULT`. -For more information, see [SUCCEEDED Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [FAILED Macro](/windows/win32/api/winerror/nf-winerror-failed). +For more information, see [`SUCCEEDED` Macro](/windows/win32/api/winerror/nf-winerror-succeeded) and [`FAILED` Macro](/windows/win32/api/winerror/nf-winerror-failed). -Note that the use of malloc and free (and related dynamic memory allocation APIs) have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` (and related dynamic memory allocation APIs) has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6225.md b/docs/code-quality/c6225.md index 0a3326757a3..9e792a74553 100644 --- a/docs/code-quality/c6225.md +++ b/docs/code-quality/c6225.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6225" -title: C6225 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6225"] +title: "Warning C6225" +description: "Learn more about: Warning C6225" +ms.date: 10/03/2022 +f1_keywords: ["C6225", "ASSIGNING_ONE_TO_HRESULT", "__WARNING_ASSIGNING_ONE_TO_HRESULT"] helpviewer_keywords: ["C6225"] -ms.assetid: 2d98ffec-9842-4cd1-b1a9-9ac9d1d2a136 --- -# C6225 +# Warning C6225 -> warning C6225: Implicit cast between semantically different integer types: assigning 1 or TRUE to HRESULT. Consider using S_FALSE instead +> Implicit cast between semantically different integer types: assigning 1 or `TRUE` to `HRESULT`. Consider using `S_FALSE` instead -This warning indicates that an `HRESULT` is being assigned or initialized with a value of an explicit 1. Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. This warning is frequently caused by accidental confusion of Boolean and `HRESULT` types. To indicate success, the symbolic constant `S_OK` should be used. +## Remarks + +This warning indicates that an `HRESULT` is being assigned or initialized with a value of an explicit 1. Boolean types indicate success by a non-zero value; success (`S_OK`) in `HRESULT` is indicated by a value of 0. + +This warning is frequently caused by accidental confusion of Boolean and `HRESULT` types. To indicate success, the symbolic constant `S_OK` should be used. + +Code analysis name: `ASSIGNING_ONE_TO_HRESULT` ## Example -In the following code, assignment of `HRESULT` generates this warning: +In the following code, assignment of `HRESULT` generates warning C6225: ```cpp #include @@ -59,10 +63,10 @@ For this warning, the `SCODE` type is equivalent to `HRESULT`. To indicate failure, `E_FAIL`, or another constant, should be used. -For more information see one of the following topics: +For more information, see one of the following articles: -[SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) +[`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) -[FAILED](/windows/desktop/api/winerror/nf-winerror-failed) +[`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) -To leverage modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To make use of modern C++ memory allocation methodology, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6226.md b/docs/code-quality/c6226.md index e732e6e66a9..48fcb9f1f07 100644 --- a/docs/code-quality/c6226.md +++ b/docs/code-quality/c6226.md @@ -1,19 +1,23 @@ --- -description: "Learn more about: C6226" -title: C6226 +title: "Warning C6226" +description: "Learn more about: Warning C6226" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6226"] +f1_keywords: ["C6226", "ASSIGNING_MINUS_ONE_TO_HRESULT", "__WARNING_ASSIGNING_MINUS_ONE_TO_HRESULT"] helpviewer_keywords: ["C6226"] -ms.assetid: c18aa576-b316-4f11-b48f-f5183fa49c7c --- -# C6226 +# Warning C6226 -> warning C6226: Implicit cast between semantically different integer types: assigning -1 to HRESULT. Consider using E_FAIL instead. +> Implicit cast between semantically different integer types: assigning -1 to HRESULT. Consider using E_FAIL instead. -This warning indicates that an `HRESULT` is assigned or initialized to an explicit value of -1. This warning is frequently caused by accidental confusion of integer and `HRESULT` types. To indicate success, use the symbolic constant `S_OK` instead. To indicate failure, use the symbolic constants that start with E_*constant*, such as `E_FAIL`. +## Remarks -For more information, see the [SUCCEEDED](/windows/desktop/api/winerror/nf-winerror-succeeded) and [FAILED](/windows/desktop/api/winerror/nf-winerror-failed) macros. +This warning indicates that an `HRESULT` is assigned or initialized to an explicit value of -1. + +This warning is frequently caused by accidental confusion of integer and `HRESULT` types. To indicate success, use the symbolic constant `S_OK` instead. To indicate failure, use the symbolic constants that start with E_*constant*, such as `E_FAIL`. + +For more information, see the [`SUCCEEDED`](/windows/desktop/api/winerror/nf-winerror-succeeded) and [`FAILED`](/windows/desktop/api/winerror/nf-winerror-failed) macros. + +Code analysis name: `ASSIGNING_MINUS_ONE_TO_HRESULT` ## Example diff --git a/docs/code-quality/c6230.md b/docs/code-quality/c6230.md index 8e620ef7f48..ae8a8308813 100644 --- a/docs/code-quality/c6230.md +++ b/docs/code-quality/c6230.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6230" -title: C6230 +title: "Warning C6230" +description: "Learn more about: Warning C6230" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6230"] +f1_keywords: ["C6230", "USING_HRESULT_IN_BOOLEAN_CONTEXT", "__WARNING_USING_HRESULT_IN_BOOLEAN_CONTEXT"] helpviewer_keywords: ["C6230"] -ms.assetid: aa91291d-cdc5-4720-89d4-194ce0557e99 --- -# C6230 +# Warning C6230 -> warning C6230: implicit cast between semantically different integer types: using HRESULT in a Boolean context +> Implicit cast between semantically different integer types: using HRESULT in a Boolean context + +## Remarks This warning indicates that a bare `HRESULT` is used in a context where a Boolean result is expected, such as an **`if`** statement. This test is likely to yield incorrect results. For example, the typical success value for `HRESULT` (`S_OK`) is false when it's tested as a Boolean. +Code analysis name: `USING_HRESULT_IN_BOOLEAN_CONTEXT` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6235.md b/docs/code-quality/c6235.md index bafc70190fa..b94279a6979 100644 --- a/docs/code-quality/c6235.md +++ b/docs/code-quality/c6235.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6235" -title: C6235 +title: "Warning C6235" +description: "Learn more about: Warning C6235" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6235"] +f1_keywords: ["C6235", "NONZEROLOGICALOR", "__WARNING_NONZEROLOGICALOR"] helpviewer_keywords: ["C6235"] -ms.assetid: e225955e-0bb5-43a4-a83d-83290e209df4 --- -# C6235 +# Warning C6235 -> warning C6235: (\ \|\| \) is always a non-zero constant +> ('*non-zero constant*' \|\| '*expression*') is always a non-zero constant -This warning indicates that a non-zero constant value, other than one, was detected on the left side of a logical-or operation that occurs in a test context. The right side of the logical-or operation is not evaluated because the resulting expression always evaluates to true. This is referred to as "short-circuit evaluation." +## Remarks -A non-zero constant value, other than one, suggests that the bitwise-AND operator (`&`) may have been intended. This warning is not generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths, but it is generated if the non-zero constant evaluates to 1, for example 1+0. +This warning indicates that a non-zero constant value, other than one, was detected on the left side of a logical-or operation that occurs in a test context. The right side of the logical-or operation isn't evaluated because the resulting expression always evaluates to true. This language feature is referred to as "short-circuit evaluation." + +A non-zero constant value, other than one, suggests that the bitwise-AND operator (`&`) may have been intended. This warning isn't generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths. However, it's generated if the non-zero constant evaluates to 1, for example `1+0`. + +Code analysis name: `NONZEROLOGICALOR` ## Example diff --git a/docs/code-quality/c6236.md b/docs/code-quality/c6236.md index 3ce9710077d..fd1b5c35e91 100644 --- a/docs/code-quality/c6236.md +++ b/docs/code-quality/c6236.md @@ -1,23 +1,25 @@ --- -description: "Learn more about: C6236" -title: C6236 +title: "Warning C6236" +description: "Learn more about: Warning C6236" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6236"] +f1_keywords: ["C6236", "LOGICALORNONZERO", "__WARNING_LOGICALORNONZERO"] helpviewer_keywords: ["C6236"] -ms.assetid: 3d5ae268-6f40-4c45-a483-b5b0e6a808fc --- -# C6236 +# Warning C6236 -> warning C6236: (\ \|\| \) is always a non-zero constant +> ('*expression*' \|\| '*non-zero constant*') is always a non-zero constant -This warning indicates that a non-zero constant value, other than one, was detected on the right side of a logical OR operation that occurs in a test context. Logically, this implies that the test is redundant and can be removed safely. Alternatively, it suggests that the programmer may have intended to use a different operator, for example, the equality (`==`), bitwise-AND (`&`) or bitwise-XOR (`^`) operator, to test for a specific value or flag. +## Remarks -This warning is not generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths at compile time. However, the warning is generated if the non-zero constant is formed by an expression that evaluates to 1, for example, 1 + 0. +This warning indicates that a non-zero constant value, other than one, was detected on the right side of a logical OR operation that occurs in a test context. Logically, it implies that the test is redundant and can be removed safely. Alternatively, it suggests that the programmer may have intended to use a different operator, for example, the equality (`==`), bitwise-AND (`&`) or bitwise-XOR (`^`) operator, to test for a specific value or flag. + +This warning isn't generated for the common idiom when the non-zero constant is 1, because of its use for selectively enabling code paths at compile time. However, the warning is generated if the non-zero constant is formed by an expression that evaluates to 1, for example, 1 + 0. + +Code analysis name: `LOGICALORNONZERO` ## Example -This code shows how warning C6236 can appear. Because `INPUT_TYPE` is not 0, the expression `n || INPUT_TYPE` is always non-zero, and the **`else`** clause is never executed. However, `INPUT_TYPE` is a constant with a value other than one, which suggests that it is meant as a value for comparison: +This code shows how warning C6236 can appear. Because `INPUT_TYPE` isn't 0, the expression `n || INPUT_TYPE` is always non-zero, and the **`else`** clause is never executed. However, `INPUT_TYPE` is a constant with a value other than one, which suggests that it's meant as a value for comparison: ```cpp #define INPUT_TYPE 2 diff --git a/docs/code-quality/c6237.md b/docs/code-quality/c6237.md index 9cb3a4602a6..8518bd67ad8 100644 --- a/docs/code-quality/c6237.md +++ b/docs/code-quality/c6237.md @@ -1,25 +1,27 @@ --- -description: "Learn more about: C6237" -title: C6237 +title: "Warning C6237" +description: "Learn more about: Warning C6237" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6237"] +f1_keywords: ["C6237", "ZEROLOGICALANDLOSINGSIDEEFFECTS", "__WARNING_ZEROLOGICALANDLOSINGSIDEEFFECTS"] helpviewer_keywords: ["C6237"] -ms.assetid: a18d8630-e4d6-4132-b976-c1f3e7c5c3f0 --- -# C6237 +# Warning C6237 -> warning C6237: (\ && \) is always zero. \ is never evaluated and may have side effects +> ('*zero*' && '*expression*') is always zero. '*expression*' is never evaluated and may have side effects -This warning indicates that a constant value of zero was detected on the left side of a logical-and operation that occurs in a test context. The resulting expression always evaluates to false. Therefore, the right side of the logical-AND operation is not evaluated. This is referred to as "short-circuit evaluation." +## Remarks -You should examine the right side of the expression carefully to ensure that any side effects such as assignment, function call, increment, and decrement operations needed for proper functionality are not affected by the short-circuit evaluation. +This warning indicates that a constant value of zero was detected on the left side of a logical-and operation that occurs in a test context. The resulting expression always evaluates to false. Therefore, the right side of the logical-AND operation isn't evaluated. This language feature is referred to as "short-circuit evaluation." + +You should examine the right side of the expression carefully: Ensure that any side effects such as assignment, function call, increment, and decrement operations needed for proper functionality aren't affected by the short-circuit evaluation. The expression (`0 && n`) produces no side effects and is commonly used to selectively choose code paths. +Code analysis name: `ZEROLOGICALANDLOSINGSIDEEFFECTS` + ## Example -The following code shows various code samples that generate this warning: +The following code shows various code examples that generate this warning: ```cpp #include diff --git a/docs/code-quality/c6239.md b/docs/code-quality/c6239.md index 7abc7ca7f26..0bf4cc1cb50 100644 --- a/docs/code-quality/c6239.md +++ b/docs/code-quality/c6239.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6239" -title: C6239 +title: "Warning C6239" +description: "Learn more about: Warning C6239" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6239"] +f1_keywords: ["C6239", "NONZEROLOGICALAND", "__WARNING_NONZEROLOGICALAND"] helpviewer_keywords: ["C6239"] -ms.assetid: c80e02bc-ff54-4fde-8c1c-5852853bed24 --- -# C6239 +# Warning C6239 -> warning C6239: (\ && \) always evaluates to the result of \. Did you intend to use the bitwise-and operator? +> ('*non-zero constant*' && '*expression*') always evaluates to the result of '*expression*'. Did you intend to use the bitwise-and operator? + +## Remarks This warning indicates that a non-zero constant value, other than one, was detected on the left side of a logical-AND operation that occurs in a test context. For example, the expression `( 2 && n )` is reduced to `(!!n)`, which is the Boolean value of `n`. -This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used, and is not generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. +This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used, and isn't generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. + +Code analysis name: `NONZEROLOGICALAND` ## Example diff --git a/docs/code-quality/c6240.md b/docs/code-quality/c6240.md index 6ba52d6372f..7ed90bcdd6a 100644 --- a/docs/code-quality/c6240.md +++ b/docs/code-quality/c6240.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6240" -title: C6240 +title: "Warning C6240" +description: "Learn more about: Warning C6240" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6240"] +f1_keywords: ["C6240", "LOGICALANDNONZERO", "__WARNING_LOGICALANDNONZERO"] helpviewer_keywords: ["C6240"] -ms.assetid: b9412ae4-622d-4aed-8c34-b67db1ccd48a --- -# C6240 +# Warning C6240 -> warning C6240: (\ && \) always evaluates to the result of \. Did you intend to use the bitwise-and operator? +> ('*expression*' && '*non-zero constant*') always evaluates to the result of '*expression*'. Did you intend to use the bitwise-and operator? + +## Remarks This warning indicates that a non-zero constant value, other than one, was detected on the right side of a logical-and operation that occurs in a test context. For example, the expression `(n && 3)` reduces to `(!!n)`, which is the Boolean value of `n`. -This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used. It is not generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. +This warning typically indicates an attempt to check a bit mask in which the bitwise-AND (`&`) operator should be used. It isn't generated if the non-zero constant evaluates to 1 because of its use for selectively choosing code paths. + +Code analysis name: `LOGICALANDNONZERO` ## Example @@ -50,7 +52,7 @@ void f(int n) } else { - puts("bitmak false"); + puts("bitmask false"); } } ``` diff --git a/docs/code-quality/c6242.md b/docs/code-quality/c6242.md index a3f9208b2d9..783981a099c 100644 --- a/docs/code-quality/c6242.md +++ b/docs/code-quality/c6242.md @@ -1,15 +1,15 @@ --- -title: C6242 +title: "Warning C6242" description: "Describes Microsoft C/C++ compiler warning C6242." ms.date: 08/24/2020 -ms.topic: reference -f1_keywords: ["C6242"] +f1_keywords: ["C6242", "LOCALUNWINDFORCED", "__WARNING_LOCALUNWINDFORCED"] helpviewer_keywords: ["C6242"] -ms.assetid: 523d46ce-8370-434c-a752-2e3a18cca9a5 --- -# C6242 +# Warning C6242 -> warning C6242: A jump out of this try-block forces local unwind. Incurs severe performance penalty +> A jump out of this try-block forces local unwind. Incurs severe performance penalty + +## Remarks This warning indicates that a jump statement causes control-flow to leave the protected block of a `try-finally` other than by fall-through. @@ -17,6 +17,8 @@ Leaving the protected block of a `try-finally` other than by falling through fro Use **`__leave`** to exit the protected block of a try-finally. +Code analysis name: `LOCALUNWINDFORCED` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6244.md b/docs/code-quality/c6244.md index e5307d9995b..fa539eeac6c 100644 --- a/docs/code-quality/c6244.md +++ b/docs/code-quality/c6244.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6244" -title: C6244 +title: "Warning C6244" +description: "Learn more about: Warning C6244" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6244"] +f1_keywords: ["C6244", "LOCALDECLHIDESGLOBAL", "__WARNING_LOCALDECLHIDESGLOBAL"] helpviewer_keywords: ["C6244"] -ms.assetid: ce2c853d-3354-40f2-a8c5-569f6e4bfc0a --- -# C6244 +# Warning C6244 -> warning C6244: local declaration of \ hides previous declaration at \ of \ +> Local declaration of '*variable*' hides previous declaration at '*line*' of '*file*' -This warning indicates that a declaration has the same name as a declaration at an outer scope and hides the previous declaration. You will not be able to refer to the previous declaration from inside the local scope. Any intended use of the previous declaration will end up using the local declaration This warning only identifies a scope overlap and not lifetime overlap. +## Remarks + +This warning indicates that a declaration has the same name as a declaration at an outer scope and hides the previous declaration. You won't be able to refer to the previous declaration from inside the local scope. Any intended use of the previous declaration will end up using the local declaration. This warning only identifies a scope overlap and not lifetime overlap. + +Code analysis name: `LOCALDECLHIDESGLOBAL` ## Example @@ -39,7 +41,7 @@ void test() #pragma warning(pop) ``` -To correct this warning, use the following sample code: +To correct this warning, use the following example code: ```cpp #include diff --git a/docs/code-quality/c6246.md b/docs/code-quality/c6246.md index 609d8f57e08..611da41b47e 100644 --- a/docs/code-quality/c6246.md +++ b/docs/code-quality/c6246.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6246" -title: C6246 +title: "Warning C6246" +description: "Learn more about: Warning C6246" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6246"] +f1_keywords: ["C6246", "LOCALDECLHIDESLOCAL", "__WARNING_LOCALDECLHIDESLOCAL"] helpviewer_keywords: ["C6246"] -ms.assetid: cd895cdb-ab3b-4671-ab43-419228fbf980 --- -# C6246 +# Warning C6246 -> warning C6246: Local declaration of \ hides declaration of same name in outer scope. Additional Information: See previous declaration at \. +> Local declaration of '*variable*' hides declaration of same name in outer scope. Additional Information: See previous declaration at '*location*'. + +## Remarks This warning indicates that two declarations have the same name at local scope. The name at outer scope is hidden by the declaration at the inner scope. Any intended use of the outer scope declaration will result in the use of local declaration. +Code analysis name: `LOCALDECLHIDESLOCAL` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6248.md b/docs/code-quality/c6248.md index 029f5b08295..6b85cdf3699 100644 --- a/docs/code-quality/c6248.md +++ b/docs/code-quality/c6248.md @@ -1,21 +1,19 @@ --- -description: "Learn more about: C6248" -title: C6248 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6248"] +title: "Warning C6248" +description: "Learn more about: Warning C6248" +ms.date: 08/16/2022 +f1_keywords: ["C6248", "__WARNING_CREATINGNULLDACL", "CREATINGNULLDACL"] helpviewer_keywords: ["C6248"] -ms.assetid: 75743622-7a79-4fe8-81b9-dbdfa1a12f3d --- -# C6248 +# Warning C6248 -> warning C6248: setting a SECURITY_DESCRIPTOR's DACL to NULL will result in an unprotected object +> Setting a SECURITY_DESCRIPTOR's DACL to NULL will result in an unprotected object. -This warning identifies a call that sets a SECURITY_DESCRIPTOR's DACL field to null. If the DACL that belongs to the security descriptor of an object is set to NULL, a null DACL is created. A null DACL grants full access to any user who requests it; normal security checking is not performed with respect to the object. A null DACL should not be confused with an empty DACL. An empty DACL is a properly allocated and initialized DACL that contains no ACEs. An empty DACL grants no access to the object it is assigned to. +## Remarks -Objects that have null DACLs can have their security descriptors altered by malicious users so that no one has access to the object. +If the DACL that belongs to the security descriptor of an object is set to NULL, a null DACL is created. A null DACL grants full access to any user who requests it; normal security checking isn't performed with respect to the object. A null DACL shouldn't be confused with an empty DACL. An empty DACL is a properly allocated and initialized DACL that contains no ACEs. An empty DACL grants no access to the object it's assigned to. Objects that have null DACLs can have their security descriptors altered by malicious users, making it so that no one has access to the object. Even in a situation where everyone needs access to an object, only administrators should be able to alter that object's security. If only the creator needs access to an object, a DACL shouldn't be set on the object; the system will choose an appropriate default. -Even if everyone needs access to an object, the object should be secured so that only administrators can alter its security. If only the creator needs access to an object, a DACL should not be set on the object; the system will choose an appropriate default. +Code analysis name: `CREATINGNULLDACL` ## Example @@ -36,4 +34,4 @@ void f( PSECURITY_DESCRIPTOR pSecurityDescriptor ) } ``` -To see a complete example on how to create security descriptor, see [Creating a Security Descriptor for a New Object in C++](/windows/desktop/SecAuthZ/creating-a-security-descriptor-for-a-new-object-in-c--). For more information, see [Creating a DACL](/windows/desktop/SecBP/creating-a-dacl). +To see a complete example on how to create security descriptor, see [Creating a Security Descriptor for a New Object in C++](/windows/desktop/SecAuthZ/creating-a-security-descriptor-for-a-new-object-in-c--). For more information on creating DACLs, see [Creating a DACL](/windows/desktop/SecBP/creating-a-dacl). diff --git a/docs/code-quality/c6250.md b/docs/code-quality/c6250.md index e0ef462fd54..aab691615a8 100644 --- a/docs/code-quality/c6250.md +++ b/docs/code-quality/c6250.md @@ -1,27 +1,29 @@ --- -description: "Learn more about: C6250" -title: C6250 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6250"] +title: "Warning C6250" +description: "Learn more about: Warning C6250" +ms.date: 10/03/2022 +f1_keywords: ["C6250", "WIN32UNRELEASEDVADS", "__WARNING_WIN32UNRELEASEDVADS"] helpviewer_keywords: ["C6250"] -ms.assetid: 6949c9c5-e8bd-4f95-bc80-42073a293357 --- -# C6250 +# Warning C6250 -> warning C6250: Calling \ VirtualFree without the MEM_RELEASE flag may free memory but not address descriptors (VADs); results in address space leaks +> Calling 'VirtualFree' without the MEM_RELEASE flag may free memory but not address descriptors (VADs); results in address space leaks -This warning indicates that a call to `VirtualFree` without the `MEM_RELEASE` flag only decommits the pages, and does not release them. To decommit and release pages, use `MEM_RELEASE` flag in call to `VirtualFree`. If any pages in the region are committed, the function first decommits and then releases them. After this operation, the pages are in the free state. If you specify this flag, `dwSize` must be zero, and `lpAddress` must point to the base address returned by the `VirtualAlloc` function when the region was reserved. The function fails if either of these conditions is not met. +## Remarks + +This warning indicates that a call to `VirtualFree` without the `MEM_RELEASE` flag only decommits the pages, and doesn't release them. To both decommit and release pages, use the `MEM_RELEASE` flag in the call to `VirtualFree`. If any pages in the region are committed, the function first decommits and then releases them. After this operation, the pages are in the free state. If you specify this flag, `dwSize` must be zero, and `lpAddress` must point to the base address returned by the `VirtualAlloc` function when the region was reserved. The function fails if either of these conditions isn't met. You can ignore this warning if your code later frees the address space by calling `VirtualFree` with the `MEM_RELEASE` flag. -For more information see [VirtualAlloc](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc) and [VirtualFree](/windows/win32/api/memoryapi/nf-memoryapi-virtualfree). +For more information, see [`VirtualAlloc`](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc) and [`VirtualFree`](/windows/win32/api/memoryapi/nf-memoryapi-virtualfree). + +The use of `VirtualAlloc` and `VirtualFree` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). -The use of VirtualAlloc and VirtualFree have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +Code analysis name: `WIN32UNRELEASEDVADS` ## Example -The following sample code generates this warning: +The following example code generates warning C6250: ```cpp #include @@ -67,7 +69,7 @@ VOID f( ) } ``` -To correct this warning, use the following sample code: +To correct this warning, use the following example code: ```cpp #include diff --git a/docs/code-quality/c6255.md b/docs/code-quality/c6255.md index cfe09c1718f..c8859f60aea 100644 --- a/docs/code-quality/c6255.md +++ b/docs/code-quality/c6255.md @@ -1,17 +1,21 @@ --- -description: "Learn more about: C6255" -title: C6255 +title: "Warning C6255" +description: "Learn more about: Warning C6255" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6255"] +f1_keywords: ["C6255", "UNPROTECTEDUSEOFALLOCA", "__WARNING_UNPROTECTEDUSEOFALLOCA"] helpviewer_keywords: ["C6255"] -ms.assetid: bb6430b2-782a-4410-a8e1-609df06007de --- -# C6255 +# Warning C6255 -> warning C6255: _alloca indicates failure by raising a stack overflow exception. Consider using _malloca instead +> _alloca indicates failure by raising a stack overflow exception. Consider using _malloca instead -This warning indicates that a call to `_alloca` has been detected outside of local exception handling. `_alloca` should always be called from within the protected range of an exception handler because it can raise a stack overflow exception on failure. If possible, instead of using `_alloca`, consider using `_malloca` which is a more secure version of `_alloca`. +## Remarks + +This warning indicates that a call to `_alloca` has been detected outside of local exception handling. + +`_alloca` should always be called from within the protected range of an exception handler because it can raise a stack overflow exception on failure. If possible, instead of using `_alloca`, consider using `_malloca`, which is a more secure version of `_alloca`. + +Code analysis name: `UNPROTECTEDUSEOFALLOCA` ## Example diff --git a/docs/code-quality/c6258.md b/docs/code-quality/c6258.md index 5b2d1df7d34..e9efa609a9d 100644 --- a/docs/code-quality/c6258.md +++ b/docs/code-quality/c6258.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6258" -title: C6258 +title: "Warning C6258" +description: "Learn more about: Warning C6258" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6258"] +f1_keywords: ["C6258", "USINGTERMINATETHREAD", "__WARNING_USINGTERMINATETHREAD"] helpviewer_keywords: ["C6258"] -ms.assetid: 62f3eed7-d9cd-46eb-8c38-0bc4f647941f --- -# C6258 +# Warning C6258 -> warning C6258: using TerminateThread does not allow proper thread clean up. +> Using `TerminateThread` does not allow proper thread clean up. -This warning indicates that a call to TerminateThread has been detected. +## Remarks -TerminateThread is a dangerous function that should only be used in the most extreme cases. For more information about problems associated with TerminateThread call, see [TerminateThread function](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminatethread). +This warning indicates that a call to `TerminateThread` has been detected. + +`TerminateThread` is a dangerous function that should only be used in the most extreme cases. For more information about problems associated with TerminateThread call, see [`TerminateThread` function](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-terminatethread). + +Code analysis name: `USINGTERMINATETHREAD` ## To properly terminate threads diff --git a/docs/code-quality/c6259.md b/docs/code-quality/c6259.md index ad982abffa9..07203450c55 100644 --- a/docs/code-quality/c6259.md +++ b/docs/code-quality/c6259.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6259" -title: C6259 +title: "Warning C6259" +description: "Learn more about: Warning C6259" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6259"] +f1_keywords: ["C6259", "DEADCODEINBITORLIMITEDSWITCH", "__WARNING_DEADCODEINBITORLIMITEDSWITCH"] helpviewer_keywords: ["C6259"] -ms.assetid: a370bfd2-6634-402c-84c7-3d83fa0009b7 --- -# C6259 +# Warning C6259 -> warning C6259: labeled code is unreachable: (\ & \) in switch-expr cannot evaluate to \ +> Labeled code is unreachable: ('*expression*' & '*constant*') in switch-expr cannot evaluate to '*case-label*' -This warning indicates unreachable code caused by the result of a bitwise-AND (`&`) comparison in a switch expression. The case statement that matches the constant in the switch expression is only reachable; all other case statements are not reachable. +## Remarks + +This warning indicates unreachable code caused by the result of a bitwise-AND (`&`) comparison in a switch expression. Only the case statement that matches the constant in the switch expression is reachable; all other case statements aren't reachable. + +Code analysis name: `DEADCODEINBITORLIMITEDSWITCH` ## Example -The following sample code generates this warning because the 'switch' expression `(rand() & 3)` cannot evaluate to case label (`case 4`): +The following example code generates this warning because the 'switch' expression `(rand() & 3)` can't evaluate to case label (`case 4`): ```cpp #include diff --git a/docs/code-quality/c6260.md b/docs/code-quality/c6260.md index 47d270bac0b..41c4541cf36 100644 --- a/docs/code-quality/c6260.md +++ b/docs/code-quality/c6260.md @@ -1,24 +1,28 @@ --- -description: "Learn more about: C6260" -title: C6260 +title: "Warning C6260" +description: "Learn more about: Warning C6260" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6260"] +f1_keywords: ["C6260", "USEOFBYTEAREA", "__WARNING_USEOFBYTEAREA"] helpviewer_keywords: ["C6260"] -ms.assetid: 9cbedfcb-32b2-4fe4-99f7-a2d4a7f4422a --- -# C6260 +# Warning C6260 -> warning C6260: sizeof * sizeof is almost always wrong, did you intend to use a character count or a byte count? +> `sizeof` * `sizeof` is almost always wrong, did you intend to use a character count or a byte count? -This warning indicates that the results of two **`sizeof`** operations have been multiplied together. The C/C++ **`sizeof`** operator returns the number of bytes of storage an object uses. It is typically incorrect to multiply it by another **`sizeof`** operation; usually one is interested in the number of bytes in an object or the number of elements in an array (for example the number of wide-characters in an array). +## Remarks -There is some unintuitive behavior associated with **`sizeof`** operator. For example, in C, the `sizeof ('\0') == 4,` because a character is of an integral type. In C++, the type of a character literal is **`char`**, so `sizeof ('\0') == 1`. However, in both C and C++, the following is true: +This warning indicates that the results of two **`sizeof`** operations have been multiplied together. + +The C/C++ **`sizeof`** operator returns the number of bytes of storage an object uses. It's typically incorrect to multiply it by another **`sizeof`** operation. Usually, you're interested in the number of bytes in an object or the number of elements in an array (for example, the number of wide-characters in an array). + +There's some unintuitive behavior associated with **`sizeof`** operator. For example, in C, `sizeof ('\0') == 4`, because a character is of an integral type. In C++, the type of a character literal is **`char`**, so `sizeof ('\0') == 1`. However, in both C and C++, the following relation is true: ```cpp -sizeof ("\0") == 2. +sizeof ("\0") == 2 ``` +Code analysis name: `USEOFBYTEAREA` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6262.md b/docs/code-quality/c6262.md index bee4faf5702..1280eed743c 100644 --- a/docs/code-quality/c6262.md +++ b/docs/code-quality/c6262.md @@ -1,14 +1,13 @@ --- -title: C6262 +title: "Warning C6262" description: "Visual Studio C++ Code Analysis warning C6262 description and resolution." ms.date: 10/14/2020 -ms.topic: reference -f1_keywords: ["C6262"] +f1_keywords: ["C6262", "EXCESSIVESTACKUSAGE", "__WARNING_EXCESSIVESTACKUSAGE"] helpviewer_keywords: ["C6262"] --- -# C6262 +# Warning C6262 -> warning C6262: Function uses *constant_1* bytes of stack: exceeds /analyze:stacksize *constant_2*. Consider moving some data to heap +> Function uses *constant_1* bytes of stack: exceeds /analyze:stacksize *constant_2*. Consider moving some data to heap ## Remarks @@ -18,6 +17,8 @@ To correct the problem behind this warning, you can either move some data to the For kernel-mode code—for example, in driver projects—the value of *constant_2* is set to 1 KB. Well-written drivers should have few functions that approach this value, and changing the limit downward may be desirable. The same general techniques that are used for user-mode code to reduce the stack size can be adapted to kernel-mode code. +Code analysis name: `EXCESSIVESTACKUSAGE` + ## Adjust the stack size to suppress the warning You can use the [`/analyze:stacksize`](../build/reference/analyze-code-analysis.md) command-line option to change the value for *constant_2*, but increasing it introduces a risk that an error may not be reported. diff --git a/docs/code-quality/c6263.md b/docs/code-quality/c6263.md index dcaf889c926..3d8b854aa72 100644 --- a/docs/code-quality/c6263.md +++ b/docs/code-quality/c6263.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6263" -title: C6263 +title: "Warning C6263" +description: "Learn more about: Warning C6263" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6263"] +f1_keywords: ["C6263", "USINGALLOCAINLOOP", "__WARNING_USINGALLOCAINLOOP"] helpviewer_keywords: ["C6263"] -ms.assetid: bc360ad7-5f59-4480-a642-6c7e6beeb5f6 --- -# C6263 +# Warning C6263 -> warning C6263: using _alloca in a loop; this can quickly overflow stack +> Using _alloca in a loop; this can quickly overflow stack -This warning indicates that calling _alloca inside a loop to allocate memory can cause stack overflow. _alloca allocates memory from the stack, but that memory is only freed when the calling function exits. Stack, even in user-mode, is limited, and failure to commit a page of stack causes a stack overflow exception. The `_resetstkoflw` function recovers from a stack overflow condition, allowing a program to continue instead of failing with a fatal exception error. If the `_resetstkoflw` function is not called, there is no guard page after the previous exception. The next time that there is a stack overflow, there are no exceptions at all and the process terminates without warning. +## Remarks -You should avoid calling `_alloca` inside a loop if either the allocation size or the iteration count is unknown because it might cause stack overflow. In these cases, consider other options such as, heap memory, or [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) classes. +This warning indicates that calling `_alloca` inside a loop to allocate memory can cause stack overflow. `_alloca` allocates memory from the stack, but that memory is only freed when the calling function exits. Stack, even in user-mode, is limited, and failure to commit a page of stack causes a stack overflow exception. The `_resetstkoflw` function recovers from a stack overflow condition, allowing a program to continue instead of failing with a fatal exception error. If the `_resetstkoflw` function isn't called, there's no guard page after the previous exception. The next time that there's a stack overflow, there are no exceptions at all and the process terminates without warning. + +You should avoid calling `_alloca` inside a loop if either the allocation size or the iteration count is unknown because it might cause stack overflow. In these cases, consider other options such as heap memory or [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) classes. + +Code analysis name: `USINGALLOCAINLOOP` ## Example diff --git a/docs/code-quality/c6268.md b/docs/code-quality/c6268.md index 6fccb810acd..758c5b3a36b 100644 --- a/docs/code-quality/c6268.md +++ b/docs/code-quality/c6268.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C6268" -title: C6268 +title: "Warning C6268" +description: "Learn more about: Warning C6268" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6268"] +f1_keywords: ["C6268", "MISPARENTHESIZED_CASTS", "__WARNING_MISPARENTHESIZED_CASTS"] helpviewer_keywords: ["C6268"] -ms.assetid: fd81e00a-de2f-498b-b3fe-53ce056042d7 --- -# C6268 +# Warning C6268 -> warning C6268: Incorrect order of operations: (\)(\)x + y. Possible missing parentheses in (\)((\)x + y) +> Incorrect order of operations: ('*TYPE1*')('*TYPE2*')x + y. Possible missing parentheses in ('*TYPE1*')(('*TYPE2*')x + y) + +## Remarks This warning indicates that a complex cast expression might involve a precedence problem when performing pointer arithmetic. Because casts group more closely than binary operators, the result might not be what the programmer intended. In some cases, this defect causes incorrect behavior or a program crash. @@ -31,15 +31,17 @@ is equivalent to: ((int *)(char *)p) + offset ``` -and so the offset is interpreted as an offset in integers. In other words, it is equivalent to: +and so the offset is interpreted as an offset in integers. In other words, it's equivalent to: ```cpp (int *)((char *)p + (offset * sizeof(int))) ``` -which is not likely to be what the programmer intended. +which isn't likely to be what the programmer intended. + +Depending on the relative sizes of the two types, this offset can lead to a buffer overrun. -Depending on the relative sizes of the two types, this can lead to a buffer overrun. +Code analysis name: `MISPARENTHESIZED_CASTS` ## Example diff --git a/docs/code-quality/c6269.md b/docs/code-quality/c6269.md index c4f80b47d3a..d7b26922a15 100644 --- a/docs/code-quality/c6269.md +++ b/docs/code-quality/c6269.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C6269" -title: C6269 +title: "Warning C6269" +description: "Learn more about: Warning C6269" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6269"] +f1_keywords: ["C6269", "POINTER_DEREF_DISCARDED", "__WARNING_POINTER_DEREF_DISCARDED"] helpviewer_keywords: ["C6269"] -ms.assetid: a01fa7fa-fc6c-4af7-ac8c-585e44e60cca --- -# C6269 +# Warning C6269 -> warning C6269: possible incorrect order of operations: dereference ignored +> Possible incorrect order of operations: dereference ignored + +## Remarks This warning indicates that the result of a pointer dereference is being ignored, which raises the question of why the pointer is being dereferenced in the first place. @@ -21,7 +21,9 @@ One common cause for this defect is an expression statement of the form: *p++; ``` -If the intent of this statement is simply to increment the pointer `p`, then dereference is unnecessary; however, if the intent is to increment the location that `p` is pointing to, then the program will not behave as intended because `p++` construct is interpreted as `(p++)` instead of `(*p)++`. +If the intent of this statement is simply to increment the pointer `p`, then dereference is unnecessary; however, if the intent is to increment the location that `p` is pointing to, then the program won't behave as intended because `p++` construct is interpreted as `(p++)` instead of `(*p)++`. + +Code analysis name: `POINTER_DEREF_DISCARDED` ## Example diff --git a/docs/code-quality/c6270.md b/docs/code-quality/c6270.md index 730f6edab91..ce3f1f68a54 100644 --- a/docs/code-quality/c6270.md +++ b/docs/code-quality/c6270.md @@ -1,59 +1,45 @@ --- -description: "Learn more about: C6270" -title: C6270 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6270"] +title: "Warning C6270" +description: "Learn more about: Warning C6270" +ms.date: 3/03/2023 +f1_keywords: ["C6270", "MISSING_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_MISSING_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6270"] -ms.assetid: 34467f6e-98cf-489c-ae5e-c08a744d86c3 --- -# C6270 +# Warning C6270 -> warning C6270: missing float argument to \: add a float argument corresponding to conversion specifier \ +> Missing float argument to '*function-name*': add a float argument corresponding to conversion specifier '*number*' -This warning indicates that not enough arguments are being provided to match a format string; at least one of the missing arguments is a floating-point number. This defect can lead to crashes, in addition to potentially incorrect output. +## Remarks -## Example - -The following code generates this warning: +This warning indicates that not enough arguments are provided to match a format string. At least one of the missing arguments is a floating-point number. This defect can lead to crashes, in addition to potentially incorrect output. -```cpp -#include -#include +Code analysis name: `MISSING_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION` -void f() -{ - char buff [25]; - sprintf(buff,"%s %f","pi:"); -} -``` +## Example -To correct this warning, pass the missing argument as shown in the following code: +The following code generates warning C6270. `sprintf_s` expects a second float argument as denoted by `%f` but none is provided: ```cpp -#include -#include - void f() { - char buff [25]; - sprintf(buff,"%s %f","pi:",3.1415); + char buff[25]; + sprintf_s(buff, sizeof(buff), "%s %f", "pi: "); } ``` -The following sample code uses the safe string manipulation function, `sprintf_s`, to correct this warning: +To correct this warning, pass the missing float argument as shown in the following code: ```cpp -#include -#include - void f() { - char buff [25]; - sprintf_s( buff, 25,"%s %f", "pi:",3.1415 ); + char buff[25]; + sprintf_s(buff, sizeof(buff), "%s %f", "pi: ", 3.14159); } ``` ## See also -[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4473](../error-messages/compiler-warnings/C4473.md) diff --git a/docs/code-quality/c6271.md b/docs/code-quality/c6271.md index 61234c98f21..059c2c969f0 100644 --- a/docs/code-quality/c6271.md +++ b/docs/code-quality/c6271.md @@ -1,62 +1,64 @@ --- -description: "Learn more about: C6271" -title: C6271 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6271"] +title: "Warning C6271" +description: "Learn more about: Warning C6271" +ms.date: 3/06/2023 +f1_keywords: ["C6271", "EXTRA_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_EXTRA_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6271"] -ms.assetid: 24703b17-5bdc-4f97-a56a-b2ea48bacc43 --- -# C6271 +# Warning C6271 -> warning C6271: extra argument passed to \: parameter \ is not used by the format string +> Extra argument passed to '*function*' -This warning indicates that additional arguments are being provided beyond those specified by the format string. By itself, this defect will not have any visible effect although it indicates that the programmer's intent is not reflected in the code. +## Remarks + +This warning indicates that extra arguments are being provided beyond the ones specified by the format string. By itself, this defect doesn't have any visible effect although it indicates that the programmer's intent isn't reflected in the code. + +Code analysis name: `EXTRA_ARGUMENT_TO_FORMAT_FUNCTION` ## Example -The following sample code generates this warning: +The following example 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); } ``` -The following sample code calls the safe string manipulation function, `sprintf_s`, to correct this warning: +The following example code calls the safe string manipulation function, `sprintf_s`, to correct this warning: ```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 d491300543a..98cc4975756 100644 --- a/docs/code-quality/c6272.md +++ b/docs/code-quality/c6272.md @@ -1,65 +1,47 @@ --- -description: "Learn more about: C6272" -title: C6272 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6272"] +title: "Warning C6272" +description: "Learn more about: Warning C6272" +ms.date: 03/07/2023 +f1_keywords: ["C6272", "NON_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6272"] -ms.assetid: b63937ac-fbb2-45ec-936a-641c156e6355 --- -# C6272 +# Warning C6272 -> warning C6272: non-float passed as argument \ when float is required in call to \ +> Non-float passed as argument '*number*' when float is required in call to '*function-name*' -This warning indicates that the format string specifies that a float is required, for example, a `%f` or `%g` specification for `printf,` but a non-float such as an integer or string is being passed. This defect is likely to result in incorrect output; however, in certain circumstances it could result in a crash. +## Remarks -## Example - -The following code generates this warning: +This warning indicates that the format string specifies that a float is required. For example, a `%f` or `%g` specification for `printf`, but a non-float such as an integer or string is being passed. This defect can lead to crashes, in addition to potentially incorrect output. -```cpp -#include -#include +Code analysis name: `NON_FLOAT_ARGUMENT_TO_FORMAT_FUNCTION` -void f() -{ - char buff[5]; - int i=5; - - sprintf(buff,"%s %f","a",i); -} -``` +## Example -To correct this warning, use `%i` instead of `%f` specification as shown in the following code: +The following code generates this warning. `%f` indicates a float is expected, but the integer `i` is passed instead: ```cpp -#include -#include - void f() { - char buff[5]; - int i=5; - - sprintf(buff,"%s %i","a",i); + char buff[5]; + int i=5; + sprintf_s(buff, sizeof(buff), "%s %f", "a", i); } ``` -The following code uses the safe string manipulation function, `sprintf_s`, to correct this warning: +To correct this warning, change the format specifier or modify the parameters passed to the function. In this example, we correct this warning by using `%i` instead of `%f`. ```cpp -#include -#include - void f() { - char buff[5]; - int i=5; - - sprintf_s(buff,5,"%s %i","a",i); // safe version + char buff[5]; + int i=5; + sprintf_s(buff, sizeof(buff), "%s %i", "a", i); } ``` ## See also -[sprintf, _sprintf_l, swprintf, _swprintf_l, \__swprintf_l](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf`, `_sprintf_l`, `swprintf`, `_swprintf_l`, `__swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6273.md b/docs/code-quality/c6273.md index b9823639814..4a84e4345b0 100644 --- a/docs/code-quality/c6273.md +++ b/docs/code-quality/c6273.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6273" -title: C6273 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6273"] +title: "Warning C6273" +description: "Learn more about: Warning C6273" +ms.date: 03/07/2023 +f1_keywords: ["C6273", "NON_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6273"] -ms.assetid: e780e504-8b8d-4d61-b15f-4859133134ad --- -# C6273 +# Warning C6273 -> warning C6273 - non-integer passed as parameter \ when integer is required in call to \: if a pointer value is being passed, %p should be used +> Non-integer passed as parameter '*number*' when an integer is required in call to '*function*' -This warning indicates that the format string specifies an integer, for example, a `%d`, length or precedence specification for `printf` but a non-integer such as a **`float`**, string, or **`struct`** is being passed as a parameter. This defect is likely to result in incorrect output. +## Remarks + +This warning indicates that the format string specifier in a `printf` like function is expecting an integer type, but a non-integer such as a **`float`**, string, or **`struct`** is being passed instead. This warning checks integer type specifiers like `%d`, and width/precision specifier that use integers like `%*.*f`. This defect is likely to result in incorrect output. + +Code analysis name: `NON_INTEGER_ARGUMENT_TO_FORMAT_FUNCTION` ## Example @@ -19,7 +21,6 @@ The following code generates this warning because an integer is required instead ```cpp #include -#include void f_defective() { @@ -30,11 +31,10 @@ void f_defective() } ``` -The following code uses an integer cast to correct this warning: +The following code uses an integer cast to correct this warning. Alternatively it could have corrected the warning by modifying the format specifier to match the type. ```cpp #include -#include void f_corrected() { @@ -49,7 +49,6 @@ The following code uses safe string manipulation function, `sprintf_s`, to corre ```cpp #include -#include void f_safe() { @@ -60,8 +59,10 @@ void f_safe() } ``` -This warning is not applicable on Windows 9x and Windows NT version 4 because %p is not supported on these platforms. +This warning isn't applicable on Windows 9x and Windows NT version 4 because %p isn't supported on these platforms. ## See also -[`sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md) +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md) diff --git a/docs/code-quality/c6274.md b/docs/code-quality/c6274.md index dac15007124..8a324e84008 100644 --- a/docs/code-quality/c6274.md +++ b/docs/code-quality/c6274.md @@ -1,30 +1,30 @@ --- -description: "Learn more about: C6274" -title: C6274 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6274"] +title: "Warning C6274" +description: "Learn more about: Warning C6274" +ms.date: 03/07/2023 +f1_keywords: ["C6274", "NON_CHAR_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_NON_CHAR_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6274"] -ms.assetid: d32f1c67-edf1-4d03-9103-133272631948 --- -# C6274 +# Warning C6274 -> warning C6274: non-character passed as parameter \ when character is required in call to \ +> Non-character passed as parameter '*number*' when character is required in call to '*function*' + +## Remarks This warning indicates that the format string specifies that a character is required (for example, a `%c` or `%C` specification) but a non-integer such as a float, string, or struct is being passed. This defect is likely to cause incorrect output. +Code analysis name: `NON_CHAR_ARGUMENT_TO_FORMAT_FUNCTION` + ## Example The following code generates this warning: ```cpp #include -#include void f(char str[]) { char buff[5]; - sprintf(buff,"%c",str); } ``` @@ -33,12 +33,10 @@ To correct this warning, use the following code: ```cpp #include -#include void f(char str[]) { char buff[5]; - sprintf(buff,"%c",str[0]); } ``` @@ -47,12 +45,15 @@ The following code uses safe string manipulation function, `sprintf_s`, to corre ```cpp #include -#include void f(char str[]) { char buff[5]; - sprintf_s(buff,5,"%c", str[0]); } ``` + +[Format specification syntax: printf and wprintf functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[`sprintf, _sprintf_l, swprintf, _swprintf_l, __swprintf_l`](../c-runtime-library/reference/sprintf-sprintf-l-swprintf-swprintf-l-swprintf-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C4313](../error-messages/compiler-warnings/compiler-warning-level-1-c4313.md) diff --git a/docs/code-quality/c6276.md b/docs/code-quality/c6276.md index 883b0c5c21e..e31ce0bf0a4 100644 --- a/docs/code-quality/c6276.md +++ b/docs/code-quality/c6276.md @@ -1,59 +1,48 @@ --- -description: "Learn more about: C6276" -title: C6276 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6276"] +title: "Warning C6276" +description: "Learn more about: Warning C6276" +ms.date: 09/28/2022 +f1_keywords: ["C6276", "CHAR_TO_WCHAR_CAST", "__WARNING_CHAR_TO_WCHAR_CAST"] helpviewer_keywords: ["C6276"] -ms.assetid: 88f288da-da81-4d32-ab0f-be9d01a2606a --- -# C6276 +# Warning C6276 -> warning C6276: Cast between semantically different string types: char* to wchar_t\*. Use of invalid string can lead to undefined behavior +> Cast between semantically different string types. Use of invalid string can lead to undefined behavior. -This warning indicates a potentially incorrect cast from an ANSI string (`char_t*`) to a UNICODE string (`wchar_t *`). Because UNICODE strings have a character size of 2 bytes, this cast might yield strings that are not correctly terminated. Using such strings with the wcs* library of functions could cause buffer overruns and access violations. +## Remarks -## Example +This warning indicates a potentially incorrect cast from a narrow character string (`char*`) to a wide character string (`wchar_t*`). -The following code generates this warning: +Because the Microsoft compiler implements wide strings with a character size of 2 bytes, casting from a narrow string might produce strings that aren't correctly terminated. If you use such strings with the `wcs*` functions in the runtime library, they could cause buffer overruns and access violations. -```cpp -#include -VOID f() -{ - WCHAR szBuffer[8]; - LPWSTR pSrc; +Code analysis name: `CHAR_TO_WCHAR_CAST` - pSrc = (LPWSTR)"a"; - wcscpy(szBuffer, pSrc); -} -``` +## Example -The following code corrects this warning by appending the letter L to represent the ASCII character as a wide character: +The following code generates warning C6276. It's caused by an improper cast of the narrow string "a" (2 bytes, one for the 'a' and one for the null terminator) to a wide string (a 2-byte wide character 'a' with no null terminator): ```cpp #include -VOID f() +void f() { - WCHAR szBuffer[8]; - LPWSTR pSrc; - - pSrc = L"a"; - wcscpy(szBuffer, pSrc); + WCHAR szBuffer[8]; + LPWSTR pSrc; + pSrc = (LPWSTR)"a"; + wcscpy_s(szBuffer, pSrc); } ``` -The following code uses the safe string manipulation function, `wcscpy_s`, to correct this warning: +The following code corrects this warning. It removes the problem cast and adds an `L` prefix to the string to define it as a properly terminated wide character string: ```cpp #include -VOID f() +void f() { - WCHAR szBuffer[8]; - LPWSTR pSrc; - pSrc = L"a"; - wcscpy_s(szBuffer,8,pSrc); + WCHAR szBuffer[8]; + LPWSTR pSrc; + pSrc = L"a"; + wcscpy_s(szBuffer, pSrc); } ``` diff --git a/docs/code-quality/c6277.md b/docs/code-quality/c6277.md index 188abb3be48..9b80fad0fba 100644 --- a/docs/code-quality/c6277.md +++ b/docs/code-quality/c6277.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6277" -title: C6277 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6277"] +title: "Warning C6277" +description: "Learn more about: Warning C6277" +ms.date: 09/28/2022 +f1_keywords: ["C6277", "CREATEPROCESS_ESCAPE", "__WARNING_CREATEPROCESS_ESCAPE"] helpviewer_keywords: ["C6277"] -ms.assetid: 2b41252a-68c2-4e92-b005-0458db5f4430 --- -# C6277 +# Warning C6277 -> warning C6277: NULL application name with an unquoted path in call to \: results in a security vulnerability if the path contains spaces +> NULL application name with an unquoted path in call to '*function-name*': results in a security vulnerability if the path contains spaces -This warning indicates that the application name parameter is null and there might be spaces in the executable path name. In this case, unless the executable name is "fully qualified," there is likely to be a security problem. A malicious user might insert a rogue executable with the same name earlier in the path. To correct this warning, you can specify the application name instead of passing null or if you do pass null for the application name, use quotation marks around the executable path. +## Remarks + +This warning indicates that the application name parameter is null and that there might be spaces in the executable path name. + +Unless the executable name is fully qualified, there's likely to be a security problem. A malicious user could insert a rogue executable with the same name earlier in the path. To correct this warning, you can specify the application name instead of passing null. Alternatively, if you do pass null for the application name, use quotation marks around the executable path. + +Code analysis name: `CREATEPROCESS_ESCAPE` ## Example -The following sample code generates this warning because the application name parameter is null, and the executable path name has a space in it; there is a risk that a different executable could be run because of the way the function parses spaces. For more information, see [CreateProcess](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createprocessa). +The following example code generates warning C6277. The warning is caused by the NULL application name and from the executable path name having a space. Due to how the function parses spaces, there's a risk that a different executable could be run. For more information, see [`CreateProcessA`](/windows/desktop/api/processthreadsapi/nf-processthreadsapi-createprocessa). ```cpp #include diff --git a/docs/code-quality/c6278.md b/docs/code-quality/c6278.md index 38d7e2cd4a0..44f9604a392 100644 --- a/docs/code-quality/c6278.md +++ b/docs/code-quality/c6278.md @@ -1,31 +1,39 @@ --- -description: "Learn more about: C6278" -title: C6278 -ms.date: 10/16/2019 -ms.topic: reference -f1_keywords: ["C6278"] +title: "Warning C6278" +description: "Learn more about: Warning C6278" +ms.date: 10/03/2022 +f1_keywords: ["C6278", "ARRAY_NEW_DELETE_MISMATCH", "__WARNING_ARRAY_NEW_DELETE_MISMATCH"] helpviewer_keywords: ["C6278"] -ms.assetid: 5cc3c393-c48a-4f91-9f38-03d7868be5e5 --- -# C6278 +# Warning C6278 -> warning C6278: \ is allocated with array new [], but deleted with scalar delete. Destructors will not be called +> '*variable*' is allocated with array new [], but deleted with scalar delete. Destructors will not be called. -This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array **new []** operator, but freed it with the scalar **`delete`** operator. This is undefined behavior according to the C++ standard and the Microsoft C++ implementation. There are at least three reasons that this is likely to cause problems: +## Notice -- The constructors for the individual objects in the array are invoked, but the destructors are not invoked. +Warning C6278 was removed in Visual Studio 2026. Use the more generic warning [`C26865`](../code-quality/C26865.md) instead. -- If global, or class-specific, **operator new** and **operator delete** are not compatible with **operator new[]** and **operator delete[]**, unexpected results are likely to occur. +## Remarks -- It is always risky to rely on undefined behavior. +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array **`new []`** operator, but freed it with the scalar **`delete`** operator. This usage is undefined behavior according to the C++ standard and the Microsoft C++ implementation. -The exact ramifications of this defect are difficult to predict. It might result in leaks for classes with destructors that perform memory de-allocation; inconsistent behavior for classes with destructors that perform some semantically significant operation; or memory corruptions and crashes when operators have been overridden. In other cases the mismatch might be unimportant, depending on the implementation of the compiler and its libraries. Analysis tool cannot always distinguish between these situations. +There are at least three reasons that this mismatch is likely to cause problems: -If memory is allocated with array **new []**, it should be typically be freed with array **delete[]**. +- The constructors for the individual objects in the array are invoked, but the destructors aren't invoked. + +- If global, or class-specific, **`operator new`** and **`operator delete`** aren't compatible with **`operator new[]`** and **`operator delete[]`**, unexpected results are likely to occur. + +- It's always risky to rely on undefined behavior. + +The exact ramifications of this defect are difficult to predict. It might result in leaks for classes with destructors that perform memory de-allocation. It could cause inconsistent behavior for classes with destructors that perform some semantically significant operation, or memory corruptions and crashes when operators have been overridden. In other cases the mismatch might be unimportant, depending on the implementation of the compiler and its libraries. Analysis tools can't always distinguish between these situations. + +If memory is allocated with array **`new []`**, it should be freed with array **`delete[]`**. + +Code analysis name: `ARRAY_NEW_DELETE_MISMATCH` ## Example -The following sample code generates this warning: +The following example code generates warning C6278: ```cpp class A @@ -41,7 +49,7 @@ void f( ) } ``` -To correct this warning, use the following sample code: +To correct this warning, use the following example code: ```cpp void f( ) @@ -52,6 +60,6 @@ void f( ) } ``` -If the underlying object in the array is a primitive type such as **`int`**, **`float`**, **`enum`**, or pointer, there are no destructors to be called. In these cases warning [C6283](../code-quality/c6283.md) is reported instead. +If the underlying object in the array is a primitive type such as **`int`**, **`float`**, **`enum`**, or pointer, there are no destructors to call. In these cases, warning [C6283](../code-quality/c6283.md) is reported instead. -The use of new and delete have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `new` and `delete` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6279.md b/docs/code-quality/c6279.md index 55cf9c4b976..4107dd19b22 100644 --- a/docs/code-quality/c6279.md +++ b/docs/code-quality/c6279.md @@ -1,29 +1,33 @@ --- -description: "Learn more about: C6279" -title: C6279 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6279"] +title: "Warning C6279" +description: "Learn more about: Warning C6279" +ms.date: 10/03/2022 +f1_keywords: ["C6279", "NEW_ARRAY_DELETE_MISMATCH", "__WARNING_NEW_ARRAY_DELETE_MISMATCH"] helpviewer_keywords: ["C6279"] -ms.assetid: 0af88b58-35df-456f-8c02-e8eeffe3b7de --- -# C6279 +# Warning C6279 -> warning C6279: \ is allocated with scalar new, deleted with array delete [] +> '*variable-name*' is allocated with scalar new, deleted with array delete [] -This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the scalar **`new`** operator, but freed it with the array **delete []** operator. If memory is allocated with scalar **`new`**, it should typically be freed with scalar **`delete`**. +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the scalar `new` operator, but freed it with the array `delete[]` operator. If memory is allocated with scalar `new`, it should typically be freed with scalar `delete`. -There are at least three reasons that this is likely to cause problems: +## Notice -- The constructors for the individual objects in the array are not invoked, although the destructors are. +Warning C6279 was removed in Visual Studio 2026. Use the more generic warning [`C26865`](../code-quality/C26865.md) instead. -- If global (or class-specific) **operator new** and **operator delete** are not compatible with **operator new[]** and **operator delete[]**, unexpected results are likely to occur. +## Remarks -The exact ramifications of this defect are difficult to predict. It might cause random behavior or crashes due to usage of uninitialized memory because constructors are not invoked. Or, it might cause memory allocations and crashes in situations where operators have been overridden. In rare cases, the mismatch might be unimportant. Analysis tool does not currently distinguish between these situations. +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the scalar `new` operator, but freed it with the array `delete[]` operator. If memory is allocated with scalar `new`, it should typically be freed with scalar `delete`. + +The exact ramifications of this defect are difficult to predict. It might cause random behavior or crashes due to usage of uninitialized memory as constructors aren't invoked. Or, it might cause memory allocations and crashes in situations where operators have been overridden. The analysis tool doesn't currently distinguish between these situations. + +To avoid these kinds of allocation problems altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). + +Code analysis name: `NEW_ARRAY_DELETE_MISMATCH` ## Example -The following code generates this warning: +The following code generates warning C6279. `A` is allocated using `new` but deleted using `delete[]`: ```cpp class A @@ -31,27 +35,30 @@ class A // members }; -void f ( ) +void f() { - A *pA = new A; - //code ... - delete[] pA; + A *pA = new A; + //code ... + delete[] pA; } ``` -To correct this warning, use the following code: +The following code avoids this warning by using `delete` instead: ```cpp -void f( ) +class A { - A *pA = new A; - //code ... - delete pA; + // members +}; + +void f() +{ + A *pA = new A; + //code ... + delete pA; } ``` -To avoid these kinds of allocation problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). - ## See also -- [C6014](../code-quality/c6014.md) +- [C6014](c6014.md) diff --git a/docs/code-quality/c6280.md b/docs/code-quality/c6280.md index 47e20831963..8d30cbf344f 100644 --- a/docs/code-quality/c6280.md +++ b/docs/code-quality/c6280.md @@ -1,25 +1,36 @@ --- -description: "Learn more about: C6280" -title: C6280 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6280"] +title: "Warning C6280" +description: "Learn more about: Warning C6280" +ms.date: 10/03/2022 +f1_keywords: ["C6280", "MEMORY_ALLOCATION_MISMATCH", "__WARNING_MEMORY_ALLOCATION_MISMATCH"] helpviewer_keywords: ["C6280"] -ms.assetid: b91f2966-0876-4c9b-843a-e142f35be864 --- -# C6280 +# Warning C6280 -> warning C6280: \ is allocated with \, but deleted with \ +> '*variable-name*' is allocated with '*function-name-1*', but deleted with '*function-name-2*' -This warning indicates that the calling function has inconsistently allocated memory by using a function from one memory allocation family and freed it by using a function from another memory allocation family. The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). +This warning indicates that the calling function has inconsistently allocated memory by using a function from one family and freed it by using a function from another. -For example, this warning would be produced if memory is allocated by using `malloc` but freed by using `GlobalFree` or **`delete`**. In the specific cases of mismatches between array `new[]` and scalar **`delete`**, more precise warnings are reported instead of this one. +## Notice + +Warning C6280 was removed in Visual Studio 2026. Use the more generic warning [`C26865`](../code-quality/C26865.md) instead. + +## Remarks + +This warning indicates that the calling function has inconsistently allocated memory by using a function from one family and freed it by using a function from another. + +The analyzer checks for this condition only when the `_Analysis_mode_(_Analysis_local_leak_checks_)` SAL annotation is specified. By default, this annotation is specified for Windows kernel mode (driver) code. For more information about SAL annotations, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +For example, this warning would be produced if memory is allocated by using `malloc` but freed by using `GlobalFree` or `delete`. In the specific cases of mismatches between array `new[]` and scalar `delete`, more precise warnings are reported instead of this one. + +Code analysis name: `MEMORY_ALLOCATION_MISMATCH` ## Example -The following sample code generates this warning. +The following example code generates this warning. `pInt` is allocated using `calloc` but is freed using the mismatched function `delete`: ```cpp +// C6280a_warning.cpp // cl.exe /analyze /c /EHsc /nologo /W4 #include #include @@ -34,9 +45,10 @@ void f(int arraySize) } ``` -To correct this warning, use this code: +The following code avoids this warning by using the deallocation function `free`, the match to `calloc`: ```cpp +// C6280a_no_warning.cpp // cl.exe /analyze /c /EHsc /nologo /W4 #include #include @@ -51,11 +63,14 @@ void f(int arraySize) } ``` -Different API definitions can use different heaps. For example, `GlobalAlloc` uses the system heap, and `free` uses the process heap. This is likely to cause memory corruptions and crashes. +Different API definitions can use different heaps. For example, `GlobalAlloc` uses the system heap, and `free` uses the process heap. This issue is likely to cause memory corruptions and crashes. + +These inconsistencies apply to the `new`/`delete` and `malloc`/`free` memory allocation mechanisms. To avoid these kinds of potential inconsistencies altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). -These inconsistencies apply to the **`new`**/**`delete`** and `malloc`/`free` memory allocation mechanisms. To avoid these kinds of potential inconsistencies altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The following code avoids this problem entirely by using `unique_ptr`: ```cpp +// C6280b_no_warning.cpp // cl.exe /analyze /c /EHsc /nologo /W4 #include #include @@ -79,11 +94,11 @@ void f(int arraySize) ## See also -- [calloc](../c-runtime-library/reference/calloc.md) -- [malloc](../c-runtime-library/reference/malloc.md) -- [free](../c-runtime-library/reference/free.md) -- [operator new](../cpp/new-operator-cpp.md) -- [delete Operator](../cpp/delete-operator-cpp.md) -- [shared_ptr](../standard-library/shared-ptr-class.md) -- [unique_ptr](../standard-library/unique-ptr-class.md) -- [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) +[`calloc`](../c-runtime-library/reference/calloc.md)\ +[`malloc`](../c-runtime-library/reference/malloc.md)\ +[`free`](../c-runtime-library/reference/free.md)\ +[`operator new`](../cpp/new-operator-cpp.md)\ +[`delete` Operator](../cpp/delete-operator-cpp.md)\ +[`shared_ptr`](../standard-library/shared-ptr-class.md)\ +[`unique_ptr`](../standard-library/unique-ptr-class.md)\ +[Smart pointers](../cpp/smart-pointers-modern-cpp.md) diff --git a/docs/code-quality/c6281.md b/docs/code-quality/c6281.md index 1b28775d044..4481fe9fc2e 100644 --- a/docs/code-quality/c6281.md +++ b/docs/code-quality/c6281.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6281" -title: C6281 +title: "Warning C6281" +description: "Learn more about: Warning C6281" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6281"] +f1_keywords: ["C6281", "BITWISERELATIONPRECEDENCEERROR", "__WARNING_BITWISERELATIONPRECEDENCEERROR"] helpviewer_keywords: ["C6281"] -ms.assetid: d0182269-8403-486b-ac3f-325522871bb1 --- -# C6281 +# Warning C6281 -> warning C6281 - incorrect order of operations: relational operators have higher precedence than bitwise operators +> Incorrect order of operations: relational operators have higher precedence than bitwise operators + +## Remarks This warning indicates a possible error in the operator precedence, which might produce incorrect results. You should check the precedence and use parentheses to clarify the intent. Relational operators (`<`, `>`, `<=`, `>=`, `==`, `!=`) have higher precedence than bitwise operators (`&`, `|`, `^`). +Code analysis name: `BITWISERELATIONPRECEDENCEERROR` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6282.md b/docs/code-quality/c6282.md index 292d6ec6e71..c068864b18e 100644 --- a/docs/code-quality/c6282.md +++ b/docs/code-quality/c6282.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6282" -title: C6282 +title: "Warning C6282" +description: "Learn more about: Warning C6282" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6282"] +f1_keywords: ["C6282", "ASSIGNMENTREPLACESTEST", "__WARNING_ASSIGNMENTREPLACESTEST"] helpviewer_keywords: ["C6282"] -ms.assetid: 7dc153d5-fb9f-424a-8afa-4e2661efa51c --- -# C6282 +# Warning C6282 -> warning C6282: Incorrect operator: assignment of constant in Boolean context. Consider using '==' instead +> Incorrect operator: assignment of constant in Boolean context. Consider using '==' instead + +## Remarks This warning indicates that an assignment of a constant to a variable was detected in a test context. Assignment of a constant to a variable in a test context is almost always incorrect. Replace the `=` with `==`, or remove the assignment from the test context to resolve this warning. +Code analysis name: `ASSIGNMENTREPLACESTEST` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6283.md b/docs/code-quality/c6283.md index f6ba994030e..5ae2a64d214 100644 --- a/docs/code-quality/c6283.md +++ b/docs/code-quality/c6283.md @@ -1,42 +1,50 @@ --- -description: "Learn more about: C6283" -title: C6283 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6283"] +title: "Warning C6283" +description: "Learn more about: Warning C6283" +ms.date: 10/03/2022 +f1_keywords: ["C6283", "PRIMITIVE_ARRAY_NEW_DELETE_MISMATCH", "__WARNING_PRIMITIVE_ARRAY_NEW_DELETE_MISMATCH"] helpviewer_keywords: ["C6283"] -ms.assetid: 7760d32e-6d71-4c81-a6d2-719c9c76c2bb --- -# C6283 +# Warning C6283 -> warning C6283: \ is allocated with array new [], but deleted with scalar delete +> '*variable-name*' is allocated with array new [], but deleted with scalar delete -This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array `new []` operator, but freed it with the scalar **`delete`** operator. This defect might cause leaks, memory corruptions, and, in situations where operators have been overridden, crashes. If memory is allocated with array `new []`, it should typically be freed with array `delete[]`. +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array `new []` operator, but freed it with the scalar `delete` operator. + +## Notice + +Warning C6283 was removed in Visual Studio 2026. Use the more generic warning [`C26865`](../code-quality/C26865.md) instead. + +## Remarks + +This warning appears only in C++ code and indicates that the calling function has inconsistently allocated memory with the array `new []` operator, but freed it with the scalar `delete` operator. + +This defect might cause leaks, memory corruptions, and, in situations where operators have been overridden, crashes. If memory is allocated with array `new []`, it should typically be freed with array `delete[]`. + +Warning C6283 only applies to arrays of primitive types such as integers or characters. If elements of the array are objects of class type then warning [C6278](../code-quality/c6278.md) is issued. + +The use of `new` and `delete` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). + +Code analysis name: `PRIMITIVE_ARRAY_NEW_DELETE_MISMATCH` ## Example -The following code generates this warning: +The following code generates warning C6283. `str` is allocated using `new ...[...]` but is freed using the mismatched function `delete`: ```cpp void f( ) { - char *str = new char[50]; - // code ... - delete str; + char *str = new char[50]; + delete str; } ``` -To correct this warning, use the following code: +The following code remediates this warning by using the matching function `delete[]`: ```cpp void f( ) { - char *str = new char[50]; - // code ... - delete[] str; + char *str = new char[50]; + delete[] str; } ``` - -Warning C6283 only applies to arrays of primitive types such as, integers or characters. If elements of the array are objects of class type then warning [C6278](../code-quality/c6278.md) is issued. - -The use of new and delete have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6284.md b/docs/code-quality/c6284.md index 519f6509035..81aeb042c5f 100644 --- a/docs/code-quality/c6284.md +++ b/docs/code-quality/c6284.md @@ -1,28 +1,29 @@ --- -description: "Learn more about: C6284" -title: C6284 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6284"] +title: "Warning C6284" +description: "Learn more about: Warning C6284" +ms.date: 03/07/2023 +f1_keywords: ["C6284", "OBJECT_AS_STRING_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_OBJECT_AS_STRING_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6284"] -ms.assetid: f3633df6-2978-4899-8c0b-b495bd869e1a --- -# C6284 +# Warning C6284 -> warning C6284: object passed as parameter when string is required in call to \ +> Object passed as parameter when string is required in call to '*function\*' -This warning indicates that there is a mismatch between the format specifier and the type being used in a `printf`-style function. The format specifier is a C style String type such as `%s` or `%ws`, and the argument matched with it is an object type. +## Remarks -This defect might produce incorrect output or crash. +This warning indicates that there's a mismatch between the format specifier and the type being used in a `printf`-style function. The format specifier is a C style String type such as `%s` or `%ws`, and the argument is a class/struct/union type. This defect can lead to crashes, in addition to potentially incorrect output. -This is frequently due to forgetting to convert an object string type such as `std::string`, `CComBSTR` or `bstr_t` into the C style string the `printf`-style function expects. If this is the case then the fix is to add the appropriate conversion to the type. This is needed because the parameters to `printf`-style functions are essentially untyped so no automatic conversion occurs. +This defect is frequently due to forgetting to convert an object string type such as `std::string`, `CComBSTR` or `bstr_t` into the C style string the `printf`-style function expects. If so, then the fix is to add the appropriate conversion to the type. The conversion is needed because the variadic parameters to `printf`-style functions are untyped, so no automatic conversion occurs. + +Code analysis name: `OBJECT_AS_STRING_ARGUMENT_TO_FORMAT_FUNCTION` ## Example +The following example generates C6284: + ```cpp #include #include -#include void f() { @@ -31,7 +32,7 @@ void f() std::string str{"World"}; // Oops, %ws and %s require C-style strings but CComBSTR and std::strings are being passed instead - sprintf(buff,"%ws %s",bstrValue, str); + sprintf(buff, "%ws %s", bstrValue, str); } ``` @@ -40,7 +41,6 @@ Fix the warning by adding the appropriate conversions: ```cpp #include #include -#include void f() { @@ -49,11 +49,13 @@ void f() std::string str{"World"}; // Fixed by adding a static_cast to the CComBSTR and calling c_str() on the std::string - sprintf(buff,"%ws %s",static_cast(bstrValue), str.c_str()); + sprintf(buff, "%ws %s", static_cast(bstrValue), str.c_str()); } ``` ## See also -- [static_cast Operator](../cpp/static-cast-operator.md) -- [sprintf_s, _sprintf_s_l, swprintf_s, _swprintf_s_l](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md) +[`static_cast` Operator](../cpp/static-cast-operator.md)\ +[`sprintf_s`, `_sprintf_s_l`, `swprintf_s`, `_swprintf_s_l`](../c-runtime-library/reference/sprintf-s-sprintf-s-l-swprintf-s-swprintf-s-l.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C4840](../error-messages/compiler-warnings/compiler-warning-level-4-c4840.md) diff --git a/docs/code-quality/c6285.md b/docs/code-quality/c6285.md index cc9b48bc68f..d7b4077b96d 100644 --- a/docs/code-quality/c6285.md +++ b/docs/code-quality/c6285.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6285" -title: C6285 +title: "Warning C6285" +description: "Learn more about: Warning C6285" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6285"] +f1_keywords: ["C6285", "LOGICALOROFCONSTANTS", "__WARNING_LOGICALOROFCONSTANTS"] helpviewer_keywords: ["C6285"] -ms.assetid: f5bc6d3d-d33b-42c8-98d2-92ec8ab17193 --- -# C6285 +# Warning C6285 -> warning C6285: (\ \|\| \) is always a non-zero constant. Did you intend to use the bitwise-and operator? +> ('*non-zero constant*' \|\| '*non-zero constant*') is always a non-zero constant. Did you intend to use the bitwise-and operator? + +## Remarks This warning indicates that two constant values, both greater than one, were detected as arguments to a logical-or operation that occurs in a test context. This expression is always TRUE. Constant values greater than one suggest that the arguments to logical-or could be bit fields. Consider whether a bitwise operator might be a more appropriate operator in this case. +Code analysis name: `LOGICALOROFCONSTANTS` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6286.md b/docs/code-quality/c6286.md index 6cf192437d0..5c850b5e3c2 100644 --- a/docs/code-quality/c6286.md +++ b/docs/code-quality/c6286.md @@ -1,22 +1,24 @@ --- -description: "Learn more about: C6286" -title: C6286 +title: "Warning C6286" +description: "Learn more about: Warning C6286" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6286"] +f1_keywords: ["C6286", "NONZEROLOGICALORLOSINGSIDEEFFECTS", "__WARNING_NONZEROLOGICALORLOSINGSIDEEFFECTS"] helpviewer_keywords: ["C6286"] -ms.assetid: c79c5d4a-c02b-4b98-891a-d79e471f9da7 --- -# C6286 +# Warning C6286 -> warning C6286: (\ \|\| \) is always a non-zero constant. \ is never evaluated and may have side effects +> ('*non-zero constant*' \|\| '*expression*') is always a non-zero constant. '*expression*' is never evaluated and may have side effects -This warning indicates that a non-zero constant was detected on the left side of a logical-or operation that occurs in a test context. The resulting expression always evaluates to TRUE. In addition, the right side of the expression appears to have side effects, and they will be lost. +## Remarks -This warning indicates that you may want to examine the right side of the expression carefully to ensure that any side effects needed for proper functionality are not lost. +This warning indicates that a non-zero constant was detected on the left side of a logical-or operation that occurs in a test context. The resulting expression always evaluates to TRUE. In addition, the right side of the expression appears to have side effects, and they'll be lost. + +You may want to examine the right side of the expression carefully to ensure that any side effects needed for proper functionality aren't lost. The `(!0 || )` construction is commonly used to force execution of a controlled block. +Code analysis name: `NONZEROLOGICALORLOSINGSIDEEFFECTS` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6287.md b/docs/code-quality/c6287.md index 8d670ee2d4c..ecf799346b7 100644 --- a/docs/code-quality/c6287.md +++ b/docs/code-quality/c6287.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6287" -title: C6287 +title: "Warning C6287" +description: "Learn more about: Warning C6287" ms.date: 12/17/2019 -ms.topic: reference -f1_keywords: ["C6287"] +f1_keywords: ["C6287", "REDUNDANTTEST", "__WARNING_REDUNDANTTEST"] helpviewer_keywords: ["C6287"] -ms.assetid: 9cb12641-8853-413a-b89e-f8b32c8dc5d3 --- -# C6287 +# Warning C6287 -> warning C6287: redundant code: the left and right subexpressions are identical +> Redundant code: the left and right subexpressions are identical -This warning is emitted when an expression contains redundant logic. The warning can indicate a logic error. For example, accidentally using the wrong variable. It might also be a redundant test that can be removed. Inspect the code to verify that there is no logic error. +## Remarks + +This warning is emitted when an expression contains redundant logic. The warning can indicate a logic error. For example, accidentally using the wrong variable. It might also be a redundant test that can be removed. Inspect the code to verify that there's no logic error. + +Code analysis name: `REDUNDANTTEST` ## Example diff --git a/docs/code-quality/c6288.md b/docs/code-quality/c6288.md index 7cffbca563f..0057b6c8fea 100644 --- a/docs/code-quality/c6288.md +++ b/docs/code-quality/c6288.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6288" -title: C6288 +title: "Warning C6288" +description: "Learn more about: Warning C6288" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6288"] +f1_keywords: ["C6288", "MUTUALINCLUSIONOVERANDISFALSE", "__WARNING_MUTUALINCLUSIONOVERANDISFALSE"] helpviewer_keywords: ["C6288"] -ms.assetid: 3856b80a-c9f2-4e86-97fc-c913b0186788 --- -# C6288 +# Warning C6288 -> warning C6288: Incorrect operator: mutual inclusion over && is always zero. Did you intend to use \|\| instead? +> Incorrect operator: mutual inclusion over && is always zero. Did you intend to use \|\| instead? -This warning indicates that in a test expression, a variable is being tested against two different constants and the result depends on both conditions being true. The code in these cases indicates that the programmer's intent isn't captured correctly. It's important to examine the code and correct the problem. Otherwise, your code won't behave the way you expected it to. +## Remarks -This problem is generally caused by using `&&`; in place of `||`, but can also be caused by using `==` where `!=` was intended. +This warning indicates that in a test expression, a variable is being tested against two different constants. The result depends on both conditions being true, which is impossible. The code in these cases indicates that the programmer's intent isn't captured correctly. It's important to examine the code and correct the problem. Otherwise, your code won't behave the way you expected it to. + +This problem is often caused by using `&&`; in place of `||`, but can also be caused by using `==` where `!=` was intended. + +Code analysis name: `MUTUALINCLUSIONOVERANDISFALSE` ## Example @@ -47,4 +49,4 @@ void f(int x) } ``` -The analysis tool does not warn if the expression has side effects. +The analysis tool doesn't warn if the expression has side effects. diff --git a/docs/code-quality/c6289.md b/docs/code-quality/c6289.md index 918a383f0e1..500153072b2 100644 --- a/docs/code-quality/c6289.md +++ b/docs/code-quality/c6289.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6289" -title: C6289 +title: "Warning C6289" +description: "Learn more about: Warning C6289" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6289"] +f1_keywords: ["C6289", "MUTUALEXCLUSIONOVERORISTRUE", "__WARNING_MUTUALEXCLUSIONOVERORISTRUE"] helpviewer_keywords: ["C6289"] -ms.assetid: 0fe09974-7577-468b-91a0-62dbe915443e --- -# C6289 +# Warning C6289 -> warning C6289: Incorrect operator: mutual exclusion over \|\| is always a non-zero constant. Did you intend to use && instead? +> Incorrect operator: mutual exclusion over `||` is always a non-zero constant. Did you intend to use `&&` instead? -This warning indicates that in a test expression a variable is being tested against two different constants and the result depends on either condition being true. This always evaluates to true. +## Remarks -This problem is generally caused by using `||` in place of `&&`, but can also be caused by using `!=` where `==` was intended. +This warning indicates that in a test expression a variable is being tested as unequal to two different constants. The result depends on either condition being true, but it always evaluates to true. + +This problem is often caused by using `||` in place of `&&`, but can also be caused by using `!=` where `==` was intended. + +Code analysis name: `MUTUALEXCLUSIONOVERORISTRUE` ## Example diff --git a/docs/code-quality/c6290.md b/docs/code-quality/c6290.md index a278c37cb1f..61854f30eed 100644 --- a/docs/code-quality/c6290.md +++ b/docs/code-quality/c6290.md @@ -1,21 +1,21 @@ --- -description: "Learn more about: C6290" -title: C6290 +title: "Warning C6290" +description: "Learn more about: Warning C6290" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6290"] +f1_keywords: ["C6290", "LOGICALNOTBITWISEAND", "__WARNING_LOGICALNOTBITWISEAND"] helpviewer_keywords: ["C6290"] -ms.assetid: 96a1acc4-724b-4b56-b091-661ddcc03884 --- -# C6290 +# Warning C6290 -> warning C6290: Bitwise operation on logical result: ! has higher precedence than &. Use && or (!(x & y)) instead +> Bitwise operation on logical result: ! has higher precedence than &. Use && or (!(x & y)) instead + +## Remarks This warning indicates possible confusion in the use of an operator or an operator precedence. The `!` operator yields a Boolean result, and it has higher precedence than the `&`. The bitwise-and (&) operator takes two arithmetic arguments. Therefore, one of the following errors has been detected: -- The expression is mis-parenthesised: +- The expression is mis-parenthesized: Because the result of `!` is Boolean (zero or one), an attempt to test that two variables have bits in common will only end up testing that the lowest bit is present in the right side: `((!8) & 1) == 0`. @@ -25,9 +25,11 @@ The `!` operator yields a Boolean result, and it has higher precedence than the - The binary operator `&` is incorrect, and should instead be `&&`: - While `&` can sometimes be interchanged with `&&`, it is not equivalent because it forces evaluation of the right side of the expression. Certain side effects in this type of expression can be terminal. + While `&` can sometimes be interchanged with `&&`, it isn't equivalent because it forces evaluation of the right side of the expression. Certain side effects in this type of expression can be terminal. + +It's difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. -It is difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. +Code analysis name: `LOGICALNOTBITWISEAND` ## Example @@ -43,7 +45,7 @@ void f(int x, int y) } ``` -To correct this warning, use the following sample code: +To correct this warning, use the following example code: ```cpp void f(int x, int y) diff --git a/docs/code-quality/c6291.md b/docs/code-quality/c6291.md index 265926e5186..cfdb0e86e6f 100644 --- a/docs/code-quality/c6291.md +++ b/docs/code-quality/c6291.md @@ -1,21 +1,21 @@ --- -description: "Learn more about: C6291" -title: C6291 +title: "Warning C6291" +description: "Learn more about: Warning C6291" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6291"] +f1_keywords: ["C6291", "LOGICALNOTBITWISEOR", "__WARNING_LOGICALNOTBITWISEOR"] helpviewer_keywords: ["C6291"] -ms.assetid: d0457386-e403-43fa-b959-5b6a495fab42 --- -# C6291 +# Warning C6291 -> warning C6291: Bitwise operation on logical result: ! has higher precedence than \|. Use \|\| or (!(x \| y)) instead +> Bitwise operation on logical result: ! has higher precedence than \|. Use \|\| or (!(x \| y)) instead + +## Remarks The `!` operator yields a Boolean result, and the `|` (bitwise-or) operator takes two arithmetic arguments. The `!` operator also has higher precedence than `|`. Therefore, one of the following errors has been detected: -- The expression is mis-parenthesised: +- The expression is mis-parenthesized: Because the result of `!` is Boolean (zero or one), an attempt to test that two variables have bits set will only end up testing that the lowest bit is present in the right side: `((!x) | y) != (!(x | y))` when `x == 0` and `y == 1`. @@ -25,14 +25,16 @@ Therefore, one of the following errors has been detected: - The binary operator `|` is incorrect, and should instead be `||`: - Even though `|` can sometimes be interchanged with `||`, it is not equivalent because it forces evaluation of the right side of the expression. Certain side-effects in this type of expression can be terminal: `(!p | (*p == '\0'))`, when `p == NULL`, we must dereference it to evaluate the other half of the expression. + Even though `|` can sometimes be interchanged with `||`, it isn't equivalent because it forces evaluation of the right side of the expression. Certain side-effects in this type of expression can be terminal: `(!p | (*p == '\0'))`, when `p == NULL`, we must dereference it to evaluate the other half of the expression. -This warning is not reported if the `!` operator is on the right side of the `|` operator because this case is typically just the relatively harmless case of an incorrect operator. +This warning isn't reported if the `!` operator is on the right side of the `|` operator because this case is typically just the relatively harmless case of an incorrect operator. -It is difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. +It's difficult to judge the severity of this problem without examining the code. The code should be inspected to ensure that the intended test is occurring. This warning always indicates possible confusion in the use of an operator or operator precedence. +Code analysis name: `LOGICALNOTBITWISEOR` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6292.md b/docs/code-quality/c6292.md index 0991c5685cd..d3f8731f944 100644 --- a/docs/code-quality/c6292.md +++ b/docs/code-quality/c6292.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6292" -title: C6292 +title: "Warning C6292" +description: "Learn more about: Warning C6292" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6292"] +f1_keywords: ["C6292", "LOOP_COUNTS_UP_FROM_MAX", "__WARNING_LOOP_COUNTS_UP_FROM_MAX"] helpviewer_keywords: ["C6292"] -ms.assetid: 23998c78-ebd7-4ba1-a391-7b31b170f8fe --- -# C6292 +# Warning C6292 -> warning C6292: ill-defined for-loop: counts up from maximum +> Ill-defined for-loop: counts up from maximum + +## Remarks This warning indicates that a for-loop might not function as intended. It occurs when a loop counts up from a maximum, but has a lower termination condition. This loop will terminate only after integer overflow occurs. +Code analysis name: `LOOP_COUNTS_UP_FROM_MAX` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6293.md b/docs/code-quality/c6293.md index e5f62336307..1624ad4ff61 100644 --- a/docs/code-quality/c6293.md +++ b/docs/code-quality/c6293.md @@ -1,23 +1,25 @@ --- -description: "Learn more about: C6293" -title: C6293 +title: "Warning C6293" +description: "Learn more about: Warning C6293" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6293"] +f1_keywords: ["C6293", "LOOP_INDEX_GOES_NEGATIVE", "__WARNING_LOOP_INDEX_GOES_NEGATIVE"] helpviewer_keywords: ["C6293"] -ms.assetid: 24a475f6-fd93-4778-856a-9dd7941f7520 --- -# C6293 +# Warning C6293 -> warning C6293: Ill-defined for-loop: counts down from minimum +> Ill-defined for-loop: counts down from minimum + +## Remarks This warning indicates that a for-loop might not function as intended. It occurs when a loop counts down from a minimum, but has a higher termination condition. -A signed —or unsigned—index variable together with a negative increment will cause the loop to count negative until an overflow occurs. This will terminate the loop. +A signed or unsigned index variable, together with a negative increment, will cause the loop to count negative until an overflow occurs, which will terminate the loop. + +Code analysis name: `LOOP_INDEX_GOES_NEGATIVE` ## Example -The following sample code generates this warning: +The following example code generates this warning: ```cpp void f( ) diff --git a/docs/code-quality/c6294.md b/docs/code-quality/c6294.md index 2dc5b09202c..d747530e5a5 100644 --- a/docs/code-quality/c6294.md +++ b/docs/code-quality/c6294.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6294" -title: C6294 +title: "Warning C6294" +description: "Learn more about: Warning C6294" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6294"] +f1_keywords: ["C6294", "LOOP_BODY_NEVER_EXECUTED", "__WARNING_LOOP_BODY_NEVER_EXECUTED"] helpviewer_keywords: ["C6294"] -ms.assetid: 1171d76f-b862-416d-b7c0-7a29be5c132d --- -# C6294 +# Warning C6294 -> warning C6294: Ill-defined for-loop: initial condition does not satisfy test. Loop body not executed +> Ill-defined for-loop: initial condition does not satisfy test. Loop body not executed -This warning indicates that a for-loop cannot be executed because the terminating condition is true. This warning suggests that the programmer's intent is not correctly captured. +## Remarks + +This warning indicates that a for-loop can't be executed because the terminating condition is true. This warning suggests that the programmer's intent isn't correctly captured. + +Code analysis name: `LOOP_BODY_NEVER_EXECUTED` ## Example -The following sample code generates this warning because MAX_VALUE is 0: +The following example code generates this warning because MAX_VALUE is 0: ```cpp #define MAX_VALUE 0 @@ -29,7 +31,7 @@ void f() } ``` -The following sample code corrects this warning by changing the value of MAX_VALUE to 25 +The following example code corrects this warning by changing the value of MAX_VALUE to 25 ```cpp #define MAX_VALUE 25 diff --git a/docs/code-quality/c6295.md b/docs/code-quality/c6295.md index 8896b620447..80b75b427cb 100644 --- a/docs/code-quality/c6295.md +++ b/docs/code-quality/c6295.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6295" -title: C6295 +title: "Warning C6295" +description: "Learn more about: Warning C6295" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6295"] +f1_keywords: ["C6295", "INFINITE_LOOP", "__WARNING_INFINITE_LOOP"] helpviewer_keywords: ["C6295"] -ms.assetid: 64e890ee-b688-4487-938d-3928762b83a4 --- -# C6295 +# Warning C6295 -> warning C6295: Ill-defined for-loop: \ values are of the range "min" to "max". Loop executed indefinitely +> Ill-defined for-loop: '*variable*' values are of the range "min" to "max". Loop executed indefinitely + +## Remarks This warning indicates that a for-loop might not function as intended. The for-loop tests an unsigned value against zero (0) with >=. The result is always true, therefore the loop is infinite. +Code analysis name: `INFINITE_LOOP` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6296.md b/docs/code-quality/c6296.md index 365e75a8f11..a12e1eaafb5 100644 --- a/docs/code-quality/c6296.md +++ b/docs/code-quality/c6296.md @@ -1,44 +1,35 @@ --- -description: "Learn more about: C6296" -title: C6296 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6296"] +title: "Warning C6296" +description: "Learn more about: Warning C6296" +ms.date: 03/30/2025 +f1_keywords: ["C6296", "LOOP_ONLY_EXECUTED_ONCE", "__WARNING_LOOP_ONLY_EXECUTED_ONCE"] helpviewer_keywords: ["C6296"] -ms.assetid: 226573e0-db18-4c44-8fc6-0bc09d1028bc --- -# C6296 +# Warning C6296 -> warning C6296: Ill-defined for-loop: Loop body only executed once +> Ill-defined for-loop. Loop body only executed once. -This warning indicates that a for-loop might not function as intended. When the index is unsigned and a loop counts down from zero, its body is run only once. +## Remarks + +This warning indicates that a for-loop might unintentionally execute only once. A loop with an unsigned index counting down from zero or a mistaken use of `==` might cause this warning. + +Code analysis name: `LOOP_ONLY_EXECUTED_ONCE` ## Example -The following code generates this warning: +The following example generates C6296. Each for-loop shown executes exactly once. ```cpp -void f( ) +int main() { - unsigned int i; + for (unsigned int i = 0; i < 10; i--) {} // C6296 + // Use the following line to resolve the warning: + // for (unsigned int i = 0; i < 10; i++) {} - for (i = 0; i < 100; i--) - { - // code ... - } -} -``` + for (int i = 0; i == 0; i++) {} // C6296 -To correct this warning, use the following code: - -```cpp -void f( ) -{ - unsigned int i; + for (int i = 0; i < 1; i++) {} // OK - for (i = 0; i < 100; i++) - { - // code ... - } + for (int i = 1; i > 0; i--) {} // OK } ``` diff --git a/docs/code-quality/c6297.md b/docs/code-quality/c6297.md index 8d8f72935ab..d048cd48b79 100644 --- a/docs/code-quality/c6297.md +++ b/docs/code-quality/c6297.md @@ -1,10 +1,9 @@ --- -title: C6297 +title: "Warning C6297" description: "Describes causes of MSVC Code analysis warning C6297, and how to fix the issue." ms.date: 07/15/2020 -f1_keywords: ["C6297"] +f1_keywords: ["C6297", "RESULTOFSHIFTCASTTOLARGERSIZE", "__WARNING_RESULTOFSHIFTCASTTOLARGERSIZE"] helpviewer_keywords: ["C6297"] -ms.assetid: 17b585f0-75e5-4fc0-935a-143ec67659f4 --- # Warning C6297 @@ -18,6 +17,8 @@ In this case, a 32-bit value was shifted left, and the result of that shift was If you don't want to lose bits, cast the value to shift to a 64-bit quantity before it's shifted. If you want to lose bits, perform the appropriate cast to `unsigned long` or a `short` type. Or, mask the result of the shift. Either approach eliminates this warning and makes the intent of the code clearer. +Code analysis name: `RESULTOFSHIFTCASTTOLARGERSIZE` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6298.md b/docs/code-quality/c6298.md index dfe553ad926..e86e5e4b260 100644 --- a/docs/code-quality/c6298.md +++ b/docs/code-quality/c6298.md @@ -1,23 +1,25 @@ --- -description: "Learn more about: C6298" -title: C6298 +title: "Warning C6298" +description: "Learn more about: Warning C6298" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6298"] +f1_keywords: ["C6298", "CONST_STRING_TO_WRITABLE_STRING", "__WARNING_CONST_STRING_TO_WRITABLE_STRING"] helpviewer_keywords: ["C6298"] -ms.assetid: 986dc8e7-8596-4223-a66f-8616357d4399 --- -# C6298 +# Warning C6298 -> warning C6298: using a read-only string \ as a writable string argument: this will attempt to write into static read-only memory and cause random crashes +> Using a read-only string '*pointer*' as a writable string argument: this will attempt to write into static read-only memory and cause random crashes + +## Remarks This warning indicates the use of a constant string as an argument to a function that might modify the contents of that string. Because the compiler allocates constant strings in a static read-only memory, any attempts to modify it cause access violations and random crashes. -This can be avoided by storing the constant string into a local array and then using the array as the argument to the function. +This warning can be avoided by storing the constant string into a local array and then using the array as the argument to the function. + +Code analysis name: `CONST_STRING_TO_WRITABLE_STRING` ## Example -The following sample code generates this warning: +The following example code generates this warning: ```cpp #include @@ -55,7 +57,7 @@ void f() } ``` -To correct this warning, use the following sample code: +To correct this warning, use the following example code: ```cpp #include diff --git a/docs/code-quality/c6299.md b/docs/code-quality/c6299.md index 3d067057084..2a56ce73b7b 100644 --- a/docs/code-quality/c6299.md +++ b/docs/code-quality/c6299.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6299" -title: C6299 +title: "Warning C6299" +description: "Learn more about: Warning C6299" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6299"] +f1_keywords: ["C6299", "BITFIELD_TO_BOOL_COMPARISON", "__WARNING_BITFIELD_TO_BOOL_COMPARISON"] helpviewer_keywords: ["C6299"] -ms.assetid: 5129ac34-0d4f-4056-aea2-b0df2127dead --- -# C6299 +# Warning C6299 -> warning C6299: explicitly comparing a bit field to a Boolean type will yield unexpected results +> Explicitly comparing a bit field to a Boolean type will yield unexpected results + +## Remarks This warning indicates an incorrect assumption that Booleans and bit fields are equivalent. Assigning 1 to bit fields will place 1 in its single bit; however, any comparison of this bit field to 1 includes an implicit cast of the bit field to a signed int. This cast will convert the stored 1 to a -1 and the comparison can yield unexpected results. +Code analysis name: `BITFIELD_TO_BOOL_COMPARISON` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6302.md b/docs/code-quality/c6302.md index ba0540bb29f..1de8b8f8611 100644 --- a/docs/code-quality/c6302.md +++ b/docs/code-quality/c6302.md @@ -1,42 +1,44 @@ --- -description: "Learn more about: C6302" -title: C6302 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6302"] +title: "Warning C6302" +description: "Learn more about: Warning C6302" +ms.date: 03/07/2023 +f1_keywords: ["C6302", "CHAR_WCHAR_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_CHAR_WCHAR_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6302"] -ms.assetid: b0b33103-6a0a-4c5b-bdb4-1b55ce877e74 --- -# C6302 +# Warning C6302 -> warning C6302: format string mismatch: character string passed as parameter \ when wide character string is required in call to \ +> Format string mismatch. -This warning indicates that the format string specifies a wide character string is expected. However, a character string is being passed. This will likely cause the output to be malformed or for the program to crash at runtime. +## Remarks + +This warning indicates that a format string specifies a wide character string, but is being passed a narrow character string instead. One cause of the warning is because the meaning of `%s` and `%S` flip when used with `printf` or `wprintf`. This defect can lead to crashes, in addition to potentially incorrect output. + +Code analysis name: `CHAR_WCHAR_ARGUMENT_TO_FORMAT_FUNCTION` ## Example -```cpp -#include +The following code generates this warning. `buff` is a narrow character string, but `wprintf_s` is the wide string variant of `printf_s` and so expects `%s` to be wide: +```cpp void f() { - char buff[5] = "hi"; - - // Oops, because this is wprintf, the %s format specifier will interpret the argument as a wide string. - wprintf_s(L"%s", buff); + char buff[5] = "hi"; + wprintf_s(L"%s", buff); } ``` -The following sample code uses `%hs` to specify a single-byte character string with `wprintf_s` function: +The following example code remediates this issue by using `%hs` to specify a single-byte character string. Alternatively it could have switched to `%S`, which is a narrow string when used with `wprintf` like functions. See [Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md#type-field-characters) for more options. ```cpp -#include - void f() { - char buff[5] = "hi"; - - // Use %hs format specifier so wprintf_s will interpret the argument correctly as a character string - wprintf_s(L"%hs", buff); + char buff[5] = "hi"; + wprintf_s(L"%hs", buff); } ``` + +## See also + +[Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C6303](./C6303.md) diff --git a/docs/code-quality/c6303.md b/docs/code-quality/c6303.md index 9e013b0c661..003309b49f4 100644 --- a/docs/code-quality/c6303.md +++ b/docs/code-quality/c6303.md @@ -1,55 +1,48 @@ --- -description: "Learn more about: C6303" -title: C6303 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6303"] +title: "Warning C6303" +description: "Learn more about: Warning C6303" +ms.date: 03/07/2023 +f1_keywords: ["C6303", "WCHAR_CHAR_ARGUMENT_TO_FORMAT_FUNCTION", "__WARNING_WCHAR_CHAR_ARGUMENT_TO_FORMAT_FUNCTION"] helpviewer_keywords: ["C6303"] -ms.assetid: b29aa352-9382-49d4-aeb8-03f34b0639a0 --- -# C6303 +# Warning C6303 -> warning C6303: format string mismatch: wide character string passed as parameter \ when character string is required in call to \ +> Format string mismatch. -This warning indicates that the format string specifies that a character string is required. However, a wide character string is being passed. This defect is likely to cause a crash or corruption of some form. +## Remarks + +This warning indicates that a format string specifies a narrow character string, but is being passed a wide character string instead. One cause of the warning is because the meaning of `%s` and `%S` flip when used with `printf` or `wprintf`. This defect can lead to crashes, in addition to potentially incorrect output. + +Code analysis name: `WCHAR_CHAR_ARGUMENT_TO_FORMAT_FUNCTION` ## Example -The following sample code generates this warning: +The following example code generates this warning. `buff` is a wide character string, but the `printf_s` call expects a short string as denoted by `%s`: ```cpp #include void f() { - wchar_t buff[5] = L"hi"; - - printf("%s", buff); + wchar_t buff[5] = L"hi"; + printf_s("%s", buff); } ``` -To correct this warning, use `%ls` as shown in the following sample code: +The following example code remediates this issue by using `%ls` to specify a wide character string. Alternatively it could have switched to `%S`, which is a wide string when used with `printf` like functions. See [Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md#type-field-characters) for more options. ```cpp #include void f() { - wchar_t buff[5] = L"hi"; - - printf("%ls", buff); + wchar_t buff[5] = L"hi"; + printf_s("%ls", buff); } ``` -The following sample code uses safe string manipulation function `printf_s` to correct this warning: - -```cpp -#include - -void f() -{ - wchar_t buff[5] = L"hi"; +## See also - printf_s("%ls",buff); -} -``` +[Format specification syntax: `printf` and `wprintf` functions](../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md)\ +[C4477](../error-messages/compiler-warnings/C4477.md)\ +[C6302](./C6302.md) diff --git a/docs/code-quality/c6305.md b/docs/code-quality/c6305.md index 78c7c63ded1..9ffba3948ee 100644 --- a/docs/code-quality/c6305.md +++ b/docs/code-quality/c6305.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6305" -title: C6305 +title: "Warning C6305" +description: "Learn more about: Warning C6305" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6305"] +f1_keywords: ["C6305", "SIZEOF_COUNTOF_MISMATCH", "__WARNING_SIZEOF_COUNTOF_MISMATCH"] helpviewer_keywords: ["C6305"] -ms.assetid: 4b3bdf86-b593-425e-89cb-9282878b21bd --- -# C6305 +# Warning C6305 -> warning C6305: potential mismatch between sizeof and countof quantities +> Potential mismatch between sizeof and countof quantities -This warning indicates that a variable holding a **`sizeof`** result is being added to or subtracted from a pointer or `countof` expression. This will cause unexpected scaling in pointer arithmetic. +## Remarks + +This warning indicates that a variable holding a **`sizeof`** result is being added to or subtracted from a pointer or `countof` expression. This operation will cause unexpected scaling in pointer arithmetic. + +Code analysis name: `SIZEOF_COUNTOF_MISMATCH` ## Example diff --git a/docs/code-quality/c6306.md b/docs/code-quality/c6306.md index d8be24ee320..c4d0f81a096 100644 --- a/docs/code-quality/c6306.md +++ b/docs/code-quality/c6306.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6306" -title: C6306 +title: "Warning C6306" +description: "Learn more about: Warning C6306" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6306"] +f1_keywords: ["C6306", "INCORRECT_VARARG_FUNCTIONCALL", "__WARNING_INCORRECT_VARARG_FUNCTIONCALL"] helpviewer_keywords: ["C6306"] -ms.assetid: 7502710c-7e0e-4412-aecc-b6821cb8c182 --- -# C6306 +# Warning C6306 -> warning C6306: incorrect call to \: consider using \ which accepts a va_list as an argument +> Incorrect call to '*function*': consider using '*function*' which accepts a va_list as an argument -This warning indicates an incorrect function call. The `printf` family includes several functions that take a variable list of arguments; however, these functions cannot be called with a `va_list` argument. There is a corresponding `vprintf` family of functions that can be used for such calls. Calling the wrong print function will cause incorrect output. +## Remarks + +This warning indicates an incorrect function call. The `printf` family includes several functions that take a variable list of arguments; however, these functions can't be called with a `va_list` argument. There's a corresponding `vprintf` family of functions that can be used for such calls. Calling the wrong print function will cause incorrect output. + +Code analysis name: `INCORRECT_VARARG_FUNCTIONCALL` ## Example diff --git a/docs/code-quality/c6308.md b/docs/code-quality/c6308.md index c06cd5c712d..0a92764dc8b 100644 --- a/docs/code-quality/c6308.md +++ b/docs/code-quality/c6308.md @@ -1,21 +1,23 @@ --- -title: C6308 +title: "Warning C6308" description: "Understand the causes of Microsoft C/C++ code analysis warning C6308, and learn how to fix them." -ms.date: 10/23/2020 -ms.topic: reference -f1_keywords: ["C6308"] +ms.date: 09/28/2022 +f1_keywords: ["C6308", "REALLOCLEAK", "__WARNING_REALLOCLEAK"] helpviewer_keywords: ["C6308"] -ms.assetid: 1162cd96-9037-4576-9858-0c8361a12559 --- -# C6308 +# Warning C6308 -> warning C6308: 'realloc' may return null pointer: assigning a null pointer to \, which is passed as an argument to 'realloc', will cause the original memory block to be leaked +> 'realloc' may return null pointer: assigning a null pointer to '*parameter-name*', which is passed as an argument to 'realloc', will cause the original memory block to be leaked -This warning indicates a memory leak that is the result of the incorrect use of a reallocation function. Heap reallocation functions do not free the passed buffer if reallocation is unsuccessful. To correct the defect, assign the result of the reallocation function to a temporary, and then replace the original pointer after successful reallocation. +## Remarks + +Heap reallocation functions don't free the passed buffer if reallocation is unsuccessful, potentially resulting in a memory leak if not handled properly. To correct the issue, assign the result of the reallocation function to a temporary variable, and then replace the original pointer after successful reallocation. + +Code analysis name: `REALLOCLEAK` ## Example -The following sample code generates this warning: +The following example code generates warning C6308. This issue stems from the assignment of the return value from `realloc` to `x`. If `realloc` fails and returns a null pointer, then the original memory pointed to by `x` won't be freed: ```cpp #include @@ -23,18 +25,17 @@ The following sample code generates this warning: void f( ) { - char *x; - x = (char *) malloc(10); - if (x != NULL) - { - x = (char *) realloc(x, 512); - // code... - free(x); - } + char *x = (char *) malloc(10); + if (x != NULL) + { + x = (char *) realloc(x, 512); + // code... + free(x); + } } ``` -To correct this warning, use the following code: +To resolve the issue, you can create a temporary variable to store the return value of `realloc`. This change allows you to free the previously allocated memory safely if `realloc` fails: ```cpp #include @@ -42,27 +43,24 @@ To correct this warning, use the following code: void f() { - char *x, *tmp; - - x = (char *) malloc(10); - - if (x != NULL) - { - tmp = (char *) realloc(x,512); - if (tmp != NULL) + char *x = (char *) malloc(10); + if (x != NULL) { - x = tmp; + char *tmp = (char *) realloc(x,512); + if (tmp != NULL) + { + x = tmp; + } + // code... + free(x); } - // code... - free(x); - } } ``` -This warning might generate noise if there is a live alias to the buffer-to-be-reallocated at the time of the assignment of the result of the reallocation function. +This warning might generate noise if there's a live alias to the buffer-to-be-reallocated at the time of the assignment of the result of the reallocation function. -To avoid these kinds of problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +To avoid these kinds of issues altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -[C6014](../code-quality/c6014.md) +[Warning C6014](../code-quality/c6014.md) diff --git a/docs/code-quality/c6310.md b/docs/code-quality/c6310.md index 6d35ade07af..30516b4684d 100644 --- a/docs/code-quality/c6310.md +++ b/docs/code-quality/c6310.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C6310" -title: C6310 +title: "Warning C6310" +description: "Learn more about: Warning C6310" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6310"] +f1_keywords: ["C6310", "ILLEGALEXCEPTEXPRCONST", "__WARNING_ILLEGALEXCEPTEXPRCONST"] helpviewer_keywords: ["C6310"] -ms.assetid: e759eb63-883f-4c3e-bf2f-b924ff511405 --- -# C6310 +# Warning C6310 -> warning C6310: illegal constant in exception filter can cause unexpected behavior +> Illegal constant in exception filter can cause unexpected behavior + +## Remarks This message indicates that an illegal constant was detected in the filter expression of a structured exception handler. The constants defined for use in the filter expression of a structured exception handler are: @@ -21,7 +21,9 @@ This message indicates that an illegal constant was detected in the filter expre These values are defined in the run-time header file excpt.h. -Using a constant that is not in the preceding list can cause unexpected behavior. +Using a constant that isn't in the preceding list can cause unexpected behavior. + +Code analysis name: `ILLEGALEXCEPTEXPRCONST` ## Example diff --git a/docs/code-quality/c6312.md b/docs/code-quality/c6312.md index 7289e2e1d03..c63f31ea716 100644 --- a/docs/code-quality/c6312.md +++ b/docs/code-quality/c6312.md @@ -1,22 +1,24 @@ --- -description: "Learn more about: C6312" -title: C6312 +title: "Warning C6312" +description: "Learn more about: Warning C6312" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6312"] +f1_keywords: ["C6312", "EXCEPTIONCONTINUEEXECUTION", "__WARNING_EXCEPTIONCONTINUEEXECUTION"] helpviewer_keywords: ["C6312"] -ms.assetid: 1fc8b9a1-e6ba-4799-84c3-31f289576cca --- -# C6312 +# Warning C6312 -> warning C6312: Possible infinite loop: use of the constant EXCEPTION_CONTINUE_EXECUTION in the exception-filter expression of a try-except +> Possible infinite loop: use of the constant EXCEPTION_CONTINUE_EXECUTION in the exception-filter expression of a try-except -This warning indicates the use of the constant `EXCEPTION_CONTINUE_EXECUTION` (or another constant that evaluates to -1) in the filter expression of a structured exception handler. Use of the constant value `EXCEPTION_CONTINUE_EXECUTION` could lead to an infinite loop. For example, if an exception was raised by hardware, the instruction that caused the exception will be restarted. If the address that caused the exception is still bad, another exception will occur and be handled in the same way. This causes an infinite loop. +## Remarks -An explicit call to `RaiseException` will not directly cause an infinite loop, but it will continue execution of the code in the protected block. This can be unexpected, and could lead to an infinite loop if `RaiseException` was used to avoid dereferencing an invalid pointer. +This warning indicates the use of the constant `EXCEPTION_CONTINUE_EXECUTION` (or another constant that evaluates to -1) in the filter expression of a structured exception handler. Use of the constant value `EXCEPTION_CONTINUE_EXECUTION` could lead to an infinite loop. For example, if an exception was raised by hardware, the instruction that caused the exception will be restarted. If the address that caused the exception is still bad, another exception will occur and be handled in the same way. The result is an infinite loop. + +An explicit call to `RaiseException` won't directly cause an infinite loop, but it will continue execution of the code in the protected block. This behavior can be unexpected, and could lead to an infinite loop if `RaiseException` was used to avoid dereferencing an invalid pointer. Typically, `EXCEPTION_CONTINUE_EXECUTION` should be returned only by a function called in the filter expression, which has a chance to fix either the pointer that caused the exception or the underlying memory. +Code analysis name: `EXCEPTIONCONTINUEEXECUTION` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6313.md b/docs/code-quality/c6313.md index ba210cddbe6..c57dfc2e09e 100644 --- a/docs/code-quality/c6313.md +++ b/docs/code-quality/c6313.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6313" -title: C6313 +title: "Warning C6313" +description: "Learn more about: Warning C6313" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6313"] +f1_keywords: ["C6313", "BITANDVSZEROVALUEDFLAG", "__WARNING_BITANDVSZEROVALUEDFLAG"] helpviewer_keywords: ["C6313"] -ms.assetid: 2fb95c62-d81e-4525-9ec7-7723844c806c --- -# C6313 +# Warning C6313 -> warning C6313: Incorrect operator: Zero-valued flag cannot be tested with bitwise-and. Use an equality test to check for zero-valued flags +> Incorrect operator: Zero-valued flag cannot be tested with bitwise-and. Use an equality test to check for zero-valued flags + +## Remarks This warning indicates that a constant value of zero was provided as an argument to the bitwise-and (`&`) operator in a test context. The resulting expression is constant and evaluates to false; the result is different than intended. -This is typically caused by using bitwise-and to test for a flag that has the value zero. To test zero-valued flags, a test for equality must be performed, for example, using `==` or `!=`. +This warning is typically caused by using bitwise-and to test for a flag that has the value zero. To test zero-valued flags, a test for equality must be performed, for example, using `==` or `!=`. + +Code analysis name: `BITANDVSZEROVALUEDFLAG` ## Example diff --git a/docs/code-quality/c6314.md b/docs/code-quality/c6314.md index 6a637411ea4..8f7303162c3 100644 --- a/docs/code-quality/c6314.md +++ b/docs/code-quality/c6314.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6314" -title: C6314 +title: "Warning C6314" +description: "Learn more about: Warning C6314" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6314"] +f1_keywords: ["C6314", "BITORVSQUESTION", "__WARNING_BITORVSQUESTION"] helpviewer_keywords: ["C6314"] -ms.assetid: 2145ca62-967c-4223-b582-f1481b74f181 --- -# C6314 +# Warning C6314 -> warning C6314: Incorrect order of operations: bitwise-or has higher precedence than the conditional-expression operator. Add parentheses to clarify intent +> Incorrect order of operations: bitwise-or has higher precedence than the conditional-expression operator. Add parentheses to clarify intent + +## Remarks This message indicates that an expression that contains a bitwise-or operator (`|`) was detected in the tested expression of a conditional operation (`?:`). The conditional operator has lower precedence than bitwise operators. If the tested expression should contain the bitwise-or operator, then parentheses should be added around the conditional-expression. +Code analysis name: `BITORVSQUESTION` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6315.md b/docs/code-quality/c6315.md index 2ca23c75ad1..edb8a62c4c9 100644 --- a/docs/code-quality/c6315.md +++ b/docs/code-quality/c6315.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6315" -title: C6315 +title: "Warning C6315" +description: "Learn more about: Warning C6315" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6315"] +f1_keywords: ["C6315", "BITORVSBITAND", "__WARNING_BITORVSBITAND"] helpviewer_keywords: ["C6315"] -ms.assetid: 4bc932d5-04fd-440d-b3af-e32a8bbc0618 --- -# C6315 +# Warning C6315 -> warning C6315: Incorrect order of operations: bitwise-and has higher precedence than bitwise-or. Add parentheses to clarify intent +> Incorrect order of operations: bitwise-and has higher precedence than bitwise-or. Add parentheses to clarify intent + +## Remarks This warning indicates that an expression in a test context contains both bitwise-and (`&`) and bitwise-or (`|`) operations, but causes a constant because the bitwise-or operation happens last. Parentheses should be added to clarify intent. +Code analysis name: `BITORVSBITAND` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6316.md b/docs/code-quality/c6316.md index cd520cd7fe8..11ff13efa2d 100644 --- a/docs/code-quality/c6316.md +++ b/docs/code-quality/c6316.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6316" -title: C6316 +title: "Warning C6316" +description: "Learn more about: Warning C6316" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6316"] +f1_keywords: ["C6316", "INAPPROPRIATEUSEOFBITOR", "__WARNING_INAPPROPRIATEUSEOFBITOR"] helpviewer_keywords: ["C6316"] -ms.assetid: ddd6a928-76b1-4d1b-9a9d-af1efcf02e3a --- -# C6316 +# Warning C6316 -> warning C6316: Incorrect operator: tested expression is constant and non-zero. Use bitwise-and to determine whether bits are set +> Incorrect operator: tested expression is constant and non-zero. Use bitwise-and to determine whether bits are set + +## Remarks This warning indicates the use of bitwise-or (`|`) when bitwise-and (`&`) should have been used. Bitwise-or adds bits to the resulting expression, whereas bitwise-and selects only those bits in common between its two operators. Tests for flags must be performed with bitwise-and or a test of equality. +Code analysis name: `INAPPROPRIATEUSEOFBITOR` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6317.md b/docs/code-quality/c6317.md index 45c7e3bd1ec..04b7fef3f49 100644 --- a/docs/code-quality/c6317.md +++ b/docs/code-quality/c6317.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6317" -title: C6317 +title: "Warning C6317" +description: "Learn more about: Warning C6317" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6317"] +f1_keywords: ["C6317", "NOTNOTCOMPLEMENT", "__WARNING_NOTNOTCOMPLEMENT"] helpviewer_keywords: ["C6317"] -ms.assetid: dc771bb8-f596-4514-af0f-4b39658af365 --- -# C6317 +# Warning C6317 -> warning C6317: incorrect operator: logical-not (!) is not interchangeable with ones-complement (~) +> Incorrect operator: logical-not (!) is not interchangeable with ones-complement (~) -This warning indicates that a logical-not (`!`) is being applied to a constant that is likely to be a bit-flag. The result of logical-not is Boolean; it is incorrect to apply the bitwise-and (`&`) operator to a Boolean value. Use the ones-complement (`~`) operator to flip flags. +## Remarks + +This warning indicates that a logical-not (`!`) is being applied to a constant that is likely to be a bit-flag. The result of logical-not is Boolean; it's incorrect to apply the bitwise-and (`&`) operator to a Boolean value. Use the ones-complement (`~`) operator to flip flags. + +Code analysis name: `NOTNOTCOMPLEMENT` ## Example diff --git a/docs/code-quality/c6318.md b/docs/code-quality/c6318.md index 04be16a9dd9..420919c91b0 100644 --- a/docs/code-quality/c6318.md +++ b/docs/code-quality/c6318.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6318" -title: C6318 +title: "Warning C6318" +description: "Learn more about: Warning C6318" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6318"] +f1_keywords: ["C6318", "EXCEPTIONCONTINUESEARCH", "__WARNING_EXCEPTIONCONTINUESEARCH"] helpviewer_keywords: ["C6318"] -ms.assetid: 3284a83e-bb8e-461c-adcc-cfc66ceea05e --- -# C6318 +# Warning C6318 -> warning C6318: Ill-defined __try/\__except: use of the constant EXCEPTION_CONTINUE_SEARCH or another constant that evaluates to zero in the exception-filter expression. The code in the exception handler block is not executed +> Ill-defined `__try`/`__except`: use of the constant EXCEPTION_CONTINUE_SEARCH or another constant that evaluates to zero in the exception-filter expression. The code in the exception handler block is not executed -This warning indicates that if an exception occurs in the protected block of this structured exception handler, the exception will not be handled because the constant `EXCECPTION_CONTINUE_SEARCH` is used in the exception filter expression. +## Remarks -This code is equivalent to the protected block without the exception handler block because the handler block is not executed. +This warning indicates that if an exception occurs in the protected block of this structured exception handler, the exception won't be handled because the constant `EXCECPTION_CONTINUE_SEARCH` is used in the exception filter expression. + +This code is equivalent to the protected block without the exception handler block because the handler block isn't executed. + +Code analysis name: `EXCEPTIONCONTINUESEARCH` ## Example diff --git a/docs/code-quality/c6319.md b/docs/code-quality/c6319.md index 9721879b60c..22249d73224 100644 --- a/docs/code-quality/c6319.md +++ b/docs/code-quality/c6319.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6319" -title: C6319 +title: "Warning C6319" +description: "Learn more about: Warning C6319" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6319"] +f1_keywords: ["C6319", "IGNOREDBYCOMMA", "__WARNING_IGNOREDBYCOMMA"] helpviewer_keywords: ["C6319"] -ms.assetid: 3ccfc1d4-820d-48f0-8ff0-8fcfc87c45d6 --- -# C6319 +# Warning C6319 -> warning C6319: use of the comma-operator in a tested expression causes the left argument to be ignored when it has no side-effects +> Use of the comma-operator in a tested expression causes the left argument to be ignored when it has no side-effects -This warning indicates an ignored sub-expression in test context because of the comma-operator (,). The comma operator has left-to-right associativity. The result of the comma-operator is the last expression evaluated. If the left expression to comma-operator has no side effects, the compiler might omit code generation for the expression. +## Remarks + +This warning indicates an ignored sub-expression in test context because of the comma-operator (**`,`**). The comma operator has left-to-right associativity. The result of the comma-operator is the last expression evaluated. If the left expression to comma-operator has no side effects, the compiler might omit code generation for the expression. + +Code analysis name: `IGNOREDBYCOMMA` ## Example diff --git a/docs/code-quality/c6320.md b/docs/code-quality/c6320.md index c5d91299bb8..2f566ee530c 100644 --- a/docs/code-quality/c6320.md +++ b/docs/code-quality/c6320.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6320" -title: C6320 +title: "Warning C6320" +description: "Learn more about: Warning C6320" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6320"] +f1_keywords: ["C6320", "EXCEPTIONEXECUTEHANDLER", "__WARNING_EXCEPTIONEXECUTEHANDLER"] helpviewer_keywords: ["C6320"] -ms.assetid: fb9e568e-b3d4-4ce2-a276-a64ad74d7b1e --- -# C6320 +# Warning C6320 -> warning C6320: exception-filter expression is the constant EXCEPTION_EXECUTE_HANDLER. This may mask exceptions that were not intended to be handled +> Exception-filter expression is the constant EXCEPTION_EXECUTE_HANDLER. This may mask exceptions that were not intended to be handled -This warning indicates the side effect of using EXCEPTION_EXECUTE_HANDLER constant in __except block. In this case, the statement in the \__except block will always execute to handle the exception, including exceptions you did not want to handle in a particular function. It is recommended that you check the exception before handling it. +## Remarks + +This warning indicates the side effect of using `EXCEPTION_EXECUTE_HANDLER` constant in an `__except` block. In this case, the statement in the `__except` block will always execute to handle the exception, including exceptions you didn't want to handle in a particular function. It's recommended that you check the exception before handling it. + +Code analysis name: `EXCEPTIONEXECUTEHANDLER` ## Example -The following code generates this warning because the __except block will try to handle exceptions of all types: +The following code generates this warning because the `__except` block will try to handle exceptions of all types: ```cpp #include diff --git a/docs/code-quality/c6322.md b/docs/code-quality/c6322.md index a5587f94740..e555f1801bd 100644 --- a/docs/code-quality/c6322.md +++ b/docs/code-quality/c6322.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6322" -title: C6322 +title: "Warning C6322" +description: "Learn more about: Warning C6322" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6322"] +f1_keywords: ["C6322", "EXCEPT_BLOCK_EMPTY", "__WARNING_EXCEPT_BLOCK_EMPTY"] helpviewer_keywords: ["C6322"] -ms.assetid: fb23d2b1-b2a0-465c-8bf5-ec039c6c7757 --- -# C6322 +# Warning C6322 -> warning C6322: empty _except block +> Empty `__except` block -This message indicates that there is no code in the _except block. As a result, exceptions might go unhandled. +## Remarks + +This message indicates that there's no code in the `__except` block. As a result, exceptions might go unhandled. + +Code analysis name: `EXCEPT_BLOCK_EMPTY` ## Example @@ -26,7 +28,7 @@ void fd(char *pch) { __try { - // exception rasied if pch is null + // exception raised if pch is null *pch= 0 ; } __except(GetExceptionCode() == EXCEPTION_ACCESS_VIOLATION) @@ -46,7 +48,7 @@ void f(char *pch) { __try { - // exception rasied if pch is null + // exception raised if pch is null *pch= 0 ; } __except(GetExceptionCode() == EXCEPTION_ACCESS_VIOLATION ? @@ -60,4 +62,4 @@ void f(char *pch) ## See also -[try-except Statement](../cpp/try-except-statement.md) +[`try-except` Statement](../cpp/try-except-statement.md) diff --git a/docs/code-quality/c6323.md b/docs/code-quality/c6323.md index 40ebde2dc6c..cca253b079b 100644 --- a/docs/code-quality/c6323.md +++ b/docs/code-quality/c6323.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6323" -title: C6323 +title: "Warning C6323" +description: "Learn more about: Warning C6323" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6323"] +f1_keywords: ["C6323", "ARITH_OP_ON_BOOL", "__WARNING_ARITH_OP_ON_BOOL"] helpviewer_keywords: ["C6323"] -ms.assetid: e9ab47d7-21e1-4204-8dad-ed7ec6127647 --- -# C6323 +# Warning C6323 -> warning C6323 - use of arithmetic operator on Boolean type(s) +> Use of arithmetic operator on Boolean type(s) -This warning occurs if arithmetic operators are used on Boolean data types. Use of incorrect operator might yield incorrect results. It also indicates that the programmer's intent is not reflected in the code. +## Remarks + +This warning occurs if arithmetic operators are used on Boolean data types. Use of incorrect operator might yield incorrect results. It also indicates that the programmer's intent isn't reflected in the code. + +Code analysis name: `ARITH_OP_ON_BOOL` ## Example diff --git a/docs/code-quality/c6324.md b/docs/code-quality/c6324.md index adb3164dde5..89539cd2214 100644 --- a/docs/code-quality/c6324.md +++ b/docs/code-quality/c6324.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6324" -title: C6324 +title: "Warning C6324" +description: "Learn more about: Warning C6324" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6324"] +f1_keywords: ["C6324", "STRCPY_INSTEAD_OF_STRCMP", "__WARNING_STRCPY_INSTEAD_OF_STRCMP"] helpviewer_keywords: ["C6324"] -ms.assetid: 08675af3-8957-4640-9bd6-01de71ea1042 --- -# C6324 +# Warning C6324 -> warning C6324: potential incorrect use of \: Did you intend to use \? +> Potential incorrect use of '*function1*': Did you intend to use '*function2*'? -This warning indicates that a string copy function was used where a string comparison function should have been used. Incorrect use of function can cause an unexpected logic error. +## Remarks + +This warning indicates that a string copy function was used where a string comparison function should have been used. Incorrect use of the function can cause an unexpected logic error. + +Code analysis name: `STRCPY_INSTEAD_OF_STRCMP` ## Example diff --git a/docs/code-quality/c6326.md b/docs/code-quality/c6326.md index d365061ac46..9d023afa3ed 100644 --- a/docs/code-quality/c6326.md +++ b/docs/code-quality/c6326.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6326" -title: C6326 +title: "Warning C6326" +description: "Learn more about: Warning C6326" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6326"] +f1_keywords: ["C6326", "CONST_CONST_COMP", "__WARNING_CONST_CONST_COMP"] helpviewer_keywords: ["C6326"] -ms.assetid: 0b606d29-e3c2-48b5-b520-b71b670c19a1 --- -# C6326 +# Warning C6326 -> warning C6326: potential comparison of a constant with another constant +> Potential comparison of a constant with another constant + +## Remarks This warning indicates a potential comparison of a constant with another constant, which is redundant code. You must check to make sure that your intent is properly captured in the code. In some cases, you can simplify the test condition to achieve the same result. +Code analysis name: `CONST_CONST_COMP` + ## Example The following code generates this warning because two constants are compared: diff --git a/docs/code-quality/c6328.md b/docs/code-quality/c6328.md index 790cb0fb918..6c6c6dd36a0 100644 --- a/docs/code-quality/c6328.md +++ b/docs/code-quality/c6328.md @@ -1,46 +1,67 @@ --- -description: "Learn more about: C6328" -title: C6328 -ms.date: 10/16/2019 -ms.topic: reference -f1_keywords: ["C6328"] +title: "Warning C6328" +description: "Learn more about: Warning C6328" +ms.date: 02/14/2024 +f1_keywords: ["C6328", "FORMAT_SIZE_MISMATCH", "__WARNING_FORMAT_SIZE_MISMATCH"] helpviewer_keywords: ["C6328"] -ms.assetid: e25b00fa-d344-4dc9-b322-b4f1ae06f315 --- -# C6328 +# Warning C6328 -> warning C6328: Size mismatch: \ passed as parameter \ when \ is required in call to \ +> Size mismatch: '*type*' passed as _Param_(*number*) when '*type*' is required in call to '*function-name*' -Passing an argument of type **`char`** to C runtime, character-based routines named `is()`, for example, `isspace()`, can have unpredictable results. For example, an SBCS or MBCS single-byte character of type **`char`** with a value greater than `0x7F` is a negative value. If a **`char`** is passed, the compiler might convert the value to a signed **`int`** or a signed **`long`**. This value could be sign-extended by the compiler, with unexpected results. For example, `isspace` accepts an argument of type **`int`**; however, the valid range of values for its input argument is: +## Remarks -`0 <= c <= 255`, plus the special value `EOF`. +This warning indicates that type required by the format specifier and the type of the expression passed in don't match. +Using the wrong format specifier is undefined behavior. To fix the warning, make sure that the format specifiers match the types of the expressions passed in. + +Code analysis name: `FORMAT_SIZE_MISMATCH` ## Example -By default, **`char`** is a signed type in the Microsoft C++ compiler, so the range of values of a variable of type char is `-128 <= c <= 127`. Therefore, if you did the following, `c` would be sign-extended to a signed **`int`** with a value of -37, which is outside the valid range for [isspace](../standard-library/locale-functions.md#isspace): +The following example generates C6328: + +```cpp +#include + +void f(long long a) +{ + printf("%d\n", a); // C6328 emitted. +} +``` + +There are multiple ways to fix the undefined behavior. We can change the format specifier: ```cpp -#include +#include -void f( ) +void f(long long a) { - char c = -37; - int retVal = isspace( c ); - // code ... + printf("%lld\n", a); // No C6328 emitted. } ``` -To correct this problem, you can use `static_cast`, as shown in the following code: +We can change the type of the expression: ```cpp -#include +#include -void f( ) +void f(int a) { - char c = -37; - int retVal = isspace( static_cast (c) ); - // code ... + printf("%d\n", a); // No C6328 emitted. } ``` -Warning C6328 exists specifically to catch this bug. For characters in the 7-bit ASCII range, the cast is unnecessary. Characters outside that range can have unpredictable results, for example, program fault and termination. +As a last resort when overflow can't happen, we can introduce a cast: + +```cpp +#include + +void f(unsigned char a) +{ + printf("%hhd\n", static_cast(a)); // No C6328 emitted. +} +``` + +## See also + +[C6340](c6340.md) diff --git a/docs/code-quality/c6329.md b/docs/code-quality/c6329.md index 209d363c68c..6f3223f7f8b 100644 --- a/docs/code-quality/c6329.md +++ b/docs/code-quality/c6329.md @@ -1,19 +1,21 @@ --- -description: "Learn more about: C6329" -title: C6329 +title: "Warning C6329" +description: "Learn more about: Warning C6329" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6329"] +f1_keywords: ["C6329", "POTENTIAL_INCORRECT_RETVAL_CHECK", "__WARNING_POTENTIAL_INCORRECT_RETVAL_CHECK"] helpviewer_keywords: ["C6329"] -ms.assetid: 5765bd4d-5fa1-4e51-82d6-c1837b4743db --- -# C6329 +# Warning C6329 -> warning C6329: Return value for a call to \ should not be checked against \ +> Return value for a call to '*function*' should not be checked against '*number*' + +## Remarks The program is comparing a number against the return value from a call to `CreateFile`. If `CreateFile` succeeds, it returns an open handle to the object. If it fails, it returns `INVALID_HANDLE_VALUE`. -## Examples +Code analysis name: `POTENTIAL_INCORRECT_RETVAL_CHECK` + +## Example This code could cause the warning: diff --git a/docs/code-quality/c6330.md b/docs/code-quality/c6330.md index 3737106126e..2bd84f26fb1 100644 --- a/docs/code-quality/c6330.md +++ b/docs/code-quality/c6330.md @@ -1,12 +1,14 @@ --- -description: "Learn more about: C6330" -title: C6330 +title: "Warning C6330" +description: "Learn more about: Warning C6330" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6330"] +f1_keywords: ["C6330", "POTENTIAL_ARGUMENT_TYPE_MISMATCH", "__WARNING_POTENTIAL_ARGUMENT_TYPE_MISMATCH"] helpviewer_keywords: ["C6330"] -ms.assetid: 48594e1c-0a4b-4848-8598-ae6d7e08b4e9 --- -# C6330 +# Warning C6330 -> warning C6330: Incorrect type passed as parameter in call to function +> '*type1*' passed as Parameter('*number*') when '*type2*' is required in call to '*function*' + +## Remarks + +Code analysis name: `POTENTIAL_ARGUMENT_TYPE_MISMATCH` diff --git a/docs/code-quality/c6331.md b/docs/code-quality/c6331.md index 08361c89ee3..0b7c6f2ee12 100644 --- a/docs/code-quality/c6331.md +++ b/docs/code-quality/c6331.md @@ -1,23 +1,25 @@ --- -description: "Learn more about: C6331" -title: C6331 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6331"] +title: "Warning C6331" +description: "Learn more about: Warning C6331" +ms.date: 10/03/2022 +f1_keywords: ["C6331", "VirtualFreeInvalidParam1", "__WARNING_VIRTUALFREEINVALIDPARAM1"] helpviewer_keywords: ["C6331"] -ms.assetid: cb1ecc2c-29a5-4c57-acf2-0954a4c047b1 --- -# C6331 +# Warning C6331 -> warning C6331: Invalid parameter: passing MEM_RELEASE and MEM_DECOMMIT in conjunction to \ is not allowed. This results in the failure of this call +> Invalid parameter: passing MEM_RELEASE and MEM_DECOMMIT in conjunction to *`function`* is not allowed. This results in the failure of this call + +## Remarks This message indicates that an invalid parameter is passed to `VirtualFree` or `VirtualFreeEx`. `VirtualFree` and `VirtualFreeEx` both reject the flags (`MEM_RELEASE | MEM_DECOMMIT`) in combination. Therefore, the values `MEM_DECOMMIT` and `MEM_RELEASE` may not be used together in the same call. -It is not required for decommit and release to occur as independent steps. Releasing committed memory will decommit the pages as well. Also, ensure the return value of this function is not ignored. +It's not required for decommit and release to occur as independent steps. Releasing committed memory will decommit the pages as well. Also, ensure the return value of this function isn't ignored. + +Code analysis name: `VirtualFreeInvalidParam1` ## Example -The following sample code generates this warning: +The following example code generates warning C6331: ```cpp #include @@ -56,7 +58,7 @@ VOID fd( VOID ) } ``` -To correct this warning, do not pass MEM_DECOMMIT value to VirtualFree call as shown in the following code: +To correct this warning, don't pass `MEM_DECOMMIT` to the `VirtualFree` call, as shown in the following code: ```cpp #include @@ -93,9 +95,9 @@ VOID f( VOID ) } ``` -Note that the use of malloc and free (and related dynamic memory allocation APIs) have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` (and related dynamic memory allocation APIs) has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -- [VirtualAlloc Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method) -- [VirtualFree Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) +[`VirtualAlloc` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method)\ +[`VirtualFree` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) diff --git a/docs/code-quality/c6332.md b/docs/code-quality/c6332.md index ae7bed2bc96..392d45b1f78 100644 --- a/docs/code-quality/c6332.md +++ b/docs/code-quality/c6332.md @@ -1,21 +1,25 @@ --- -description: "Learn more about: C6332" -title: C6332 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6332"] +title: "Warning C6332" +description: "Learn more about: Warning C6332" +ms.date: 10/03/2022 +f1_keywords: ["C6332", "VirtualFreeInvalidParam2", "__WARNING_VIRTUALFREEINVALIDPARAM2"] helpviewer_keywords: ["C6332"] -ms.assetid: 93d74b3f-4070-4b48-807e-52b1dfee1330 --- -# C6332 +# Warning C6332 -> warning C6332: Invalid parameter: passing zero as the dwFreeType parameter to \ is not allowed. This results in the failure of this call +> Invalid parameter: passing zero as the dwFreeType parameter to '*function*' is not allowed. This results in the failure of this call -This warning indicates that an invalid parameter is being passed to VirtualFree or VirtualFreeEx. VirtualFree and VirtualFreeEx both reject a dwFreeType parameter of zero. The dwFreeType parameter can be either MEM_DECOMMIT or MEM_RELEASE. However, the values MEM_DECOMMIT and MEM_RELEASE may not be used together in the same call. Also, make sure that the return value of the VirtualFree function is not ignored. +## Remarks + +This warning indicates that an invalid parameter is being passed to `VirtualFree` or `VirtualFreeEx`. + +`VirtualFree` and `VirtualFreeEx` both reject a `dwFreeType` parameter of zero. The `dwFreeType` parameter can be either `MEM_DECOMMIT` or `MEM_RELEASE`. However, the values `MEM_DECOMMIT` and `MEM_RELEASE` may not be used together in the same call. Also, make sure that the return value of the `VirtualFree` function isn't ignored. + +Code analysis name: `VirtualFreeInvalidParam2` ## Example -The following code generates this warning because an invalid parameter is passed to the VirtualFree function: +The following code generates warning C6332 because an invalid parameter is passed to the `VirtualFree` function: ```cpp #include @@ -53,7 +57,7 @@ VOID f( VOID ) } ``` -To correct this warning, modify the call to the VirtualFree function as shown in the following code: +To correct this warning, modify the call to the `VirtualFree` function, as shown in the following code: ```cpp #include @@ -91,9 +95,9 @@ VOID f( VOID ) } ``` -The use of VirtualAlloc and VirtualFree have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `VirtualAlloc` and `VirtualFree` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -- [VirtualAlloc Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method) -- [VirtualFree Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) +[`VirtualAlloc` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualalloc-method)\ +[`VirtualFree` Method](/dotnet/framework/unmanaged-api/hosting/ihostmemorymanager-virtualfree-method) diff --git a/docs/code-quality/c6333.md b/docs/code-quality/c6333.md index f54993c55dd..2a8dac30c9c 100644 --- a/docs/code-quality/c6333.md +++ b/docs/code-quality/c6333.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6333" -title: C6333 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6333"] +title: "Warning C6333" +description: "Learn more about: Warning C6333" +ms.date: 08/25/2022 +f1_keywords: ["C6333", "VIRTUALFREEINVALIDPARAM3", "__WARNING_VIRTUALFREEINVALIDPARAM3"] helpviewer_keywords: ["C6333"] -ms.assetid: 4b8fa4b2-a3a0-4d00-bec7-76686b66fcf9 --- -# C6333 +# Warning C6333 -> warning C6333: Invalid parameter: passing MEM_RELEASE and a non-zero dwSize parameter to \ is not allowed. This results in the failure of this call +> Invalid parameter: passing MEM_RELEASE and a non-zero dwSize parameter to '*function_name*' is not allowed. This results in the failure of this call -This warning indicates an invalid parameter is being passed to VirtualFree or VirtualFreeEx. Both of these functions reject a dwFreeType of MEM_RELEASE with a non-zero value of dwSize. When passing MEM_RELEASE, the dwSize parameter must be zero. Also, make sure that the return value of this function is not ignored. +## Remarks + +Both `VirtualFree` and `VirtualFreeEx` reject a `dwFreeType` of `MEM_RELEASE` with a non-zero value of `dwSize`. When `MEM_RELEASE` is passed, the `dwSize` parameter must be zero. + +Code analysis name: `VIRTUALFREEINVALIDPARAM3` ## Example -The following sample code generates this warning: +The following code example generates this warning: ```cpp #include @@ -24,36 +26,36 @@ The following sample code generates this warning: DWORD dwPages = 0; // count of pages DWORD dwPageSize; // page size -VOID f( VOID ) +VOID f(VOID) { - LPVOID lpvBase; // base address of the test memory - BOOL bSuccess; - SYSTEM_INFO sSysInfo; // system information - - GetSystemInfo( &sSysInfo ); - dwPageSize = sSysInfo.dwPageSize; - - // Reserve pages in the process's virtual address space - lpvBase = VirtualAlloc( - NULL, // system selects address - PAGELIMIT*dwPageSize,// size of allocation - MEM_RESERVE, - PAGE_NOACCESS ); - if (lpvBase) - { - // code to access memory - } - else - { - return; - } - - bSuccess = VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_RELEASE); - //code... + LPVOID lpvBase; // base address of the test memory + BOOL bSuccess; + SYSTEM_INFO sSysInfo; // system information + + GetSystemInfo(&sSysInfo); + dwPageSize = sSysInfo.dwPageSize; + + // Reserve pages in the process's virtual address space + lpvBase = VirtualAlloc( + NULL, // system selects address + PAGELIMIT*dwPageSize,// size of allocation + MEM_RESERVE, + PAGE_NOACCESS); + if (lpvBase) + { + // code to access memory + } + else + { + return; + } + + bSuccess = VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_RELEASE); + //code... } ``` -To correct this warning, use the following sample code: +To correct this warning, ensure that the value of `dwSize` is 0 in the call to `VirtualFree`: ```cpp #include @@ -62,37 +64,37 @@ To correct this warning, use the following sample code: DWORD dwPages = 0; // count of pages DWORD dwPageSize; // page size -VOID f( VOID ) +VOID f(VOID) { - LPVOID lpvBase; // base address of the test memory - BOOL bSuccess; - SYSTEM_INFO sSysInfo; // system information - - GetSystemInfo( &sSysInfo ); - dwPageSize = sSysInfo.dwPageSize; - - // Reserve pages in the process's virtual address space - lpvBase = VirtualAlloc( - NULL, // system selects address - PAGELIMIT*dwPageSize,// size of allocation - MEM_RESERVE, - PAGE_NOACCESS ); - if (lpvBase) - { - // code to access memory - } - else - { - return; - } - bSuccess = VirtualFree(lpvBase, 0, MEM_RELEASE ); - - // VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT); - // code... + LPVOID lpvBase; // base address of the test memory + BOOL bSuccess; + SYSTEM_INFO sSysInfo; // system information + + GetSystemInfo(&sSysInfo); + dwPageSize = sSysInfo.dwPageSize; + + // Reserve pages in the process's virtual address space + lpvBase = VirtualAlloc( + NULL, // system selects address + PAGELIMIT*dwPageSize, // size of allocation + MEM_RESERVE, + PAGE_NOACCESS); + if (lpvBase) + { + // code to access memory + } + else + { + return; + } + bSuccess = VirtualFree(lpvBase, 0, MEM_RELEASE); + + // VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT); + // code... } ``` -You can also use VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT); call to decommit pages, and later release them using MEM_RELEASE flag. +You can also use `VirtualFree(lpvBase, PAGELIMIT * dwPageSize, MEM_DECOMMIT);` call to decommit pages, and later release them using `MEM_RELEASE` flag. ## See also diff --git a/docs/code-quality/c6334.md b/docs/code-quality/c6334.md index 90b45505f56..96de5d6dbbe 100644 --- a/docs/code-quality/c6334.md +++ b/docs/code-quality/c6334.md @@ -1,54 +1,43 @@ --- -description: "Learn more about: C6334" -title: C6334 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6334"] +title: "Warning C6334" +description: "Learn more about: Warning C6334" +ms.date: 08/25/2022 +f1_keywords: ["C6334", "SIZEOFEXPR", "__WARNING_SIZEOFEXPR"] helpviewer_keywords: ["C6334"] -ms.assetid: 83c8abfb-b11e-4573-8c6f-95b205d32137 --- -# C6334 +# Warning C6334 -> warning C6334: sizeof operator applied to an expression with an operator may yield unexpected results +> `sizeof` operator applied to an expression with an operator may yield unexpected results -This warning indicates a misuse of the **`sizeof`** operator. The **`sizeof`** operator, when applied to an expression, yields the size of the type of the resulting expression. +## Remarks -For example, in the following code: +The `sizeof` operator, when applied to an expression, yields the size of the type of the resulting expression. -```cpp -char a[10]; -size_t x; - -x = sizeof (a - 1); -``` - - `x` will be assigned the value 4, not 9, because the resulting expression is no longer a pointer to the array `a`, but simply a pointer. +Code analysis name: `SIZEOFEXPR` ## Example -The following code generates this warning: +The following code generates this warning. Since `a - 4` is an expression, `sizeof` will return the size of the resulting pointer, not the size of the structure found at that pointer: ```cpp void f( ) { - size_t x; - char a[10]; - - x= sizeof (a - 4); - // code... + size_t x; + char a[100]; + x = sizeof(a - 4); + assert(x == 96); //assert fails since x == sizeof(char*) } ``` -To correct this warning, use the following code: +To correct this warning, ensure that you're working with the return value of `sizeof`, not the argument to it: ```cpp void f( ) { - size_t x; - char a[10]; - - x= sizeof (a) - 4; - // code... + size_t x; + char a[100]; + x = sizeof(a) - 4; + assert(x == 96); //assert succeeds } ``` diff --git a/docs/code-quality/c6335.md b/docs/code-quality/c6335.md index 41e51ad74e7..662ee5f946e 100644 --- a/docs/code-quality/c6335.md +++ b/docs/code-quality/c6335.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6335" -title: C6335 +title: "Warning C6335" +description: "Learn more about: Warning C6335" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6335"] +f1_keywords: ["C6335", "LEAKING_PROCESS_HANDLE", "__WARNING_LEAKING_PROCESS_HANDLE"] helpviewer_keywords: ["C6335"] -ms.assetid: f81c0859-3d82-4182-8bf1-6c3b76c7486f --- -# C6335 +# Warning C6335 -> warning C6335: leaking process information handle \ +> Leaking process information handle '*handlename*' + +## Remarks This warning indicates that the process information handles returned by the CreateProcess family of functions need to be closed using CloseHandle. Failure to do so will cause handle leaks. +Code analysis name: `LEAKING_PROCESS_HANDLE` + ## Example The following code generates this warning: @@ -51,7 +53,7 @@ void f( ) } ``` -To correct this warning, call `CloseHandle (pi.``hThread)` to close thread handle as shown in the following code: +To correct this warning, call `CloseHandle( pi.hThread )` to close thread handle as shown in the following code: ```cpp #include diff --git a/docs/code-quality/c6336.md b/docs/code-quality/c6336.md index 0bd0047fa14..1f3cc67146d 100644 --- a/docs/code-quality/c6336.md +++ b/docs/code-quality/c6336.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6336" -title: C6336 +title: "Warning C6336" +description: "Learn more about: Warning C6336" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6336"] +f1_keywords: ["C6336", "QUESTIONPRECEDENCE", "__WARNING_QUESTIONPRECEDENCE"] helpviewer_keywords: ["C6336"] -ms.assetid: cf402433-9940-4466-ac15-f94288f51f74 --- -# C6336 +# Warning C6336 -> warning C6336: arithmetic operator has precedence over question operator, use parentheses to clarify intent +> Arithmetic operator has precedence over question operator, use parentheses to clarify intent -This warning indicates a possible operator precedence problem. The '+','-','*' and '/' operators have precedence over the '?' operator. If the precedence in the expression is not correct, use parentheses to change the operator precedence. +## Remarks + +This warning indicates a possible operator precedence problem. The '`+`','`-`','`*`' and '`/`' operators have precedence over the '`?`' operator. If the precedence in the expression isn't correct, use parentheses to change the operator precedence. + +Code analysis name: `QUESTIONPRECEDENCE` ## Example diff --git a/docs/code-quality/c6340.md b/docs/code-quality/c6340.md index e1d6c988ff9..7733f30f873 100644 --- a/docs/code-quality/c6340.md +++ b/docs/code-quality/c6340.md @@ -1,12 +1,68 @@ --- -description: "Learn more about: C6340" -title: C6340 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6340"] +title: "Warning C6340" +description: "Learn more about: Warning C6340" +ms.date: 02/14/2024 +f1_keywords: ["C6340", "FORMAT_SIGN_MISMATCH"] helpviewer_keywords: ["C6340"] -ms.assetid: c4fe474f-5a27-4148-ba35-1ef021371e13 --- -# C6340 +# Warning C6340 + +> Mismatch on sign: '*type*' passed as _Param_(*number*) when some (signed|unsigned) type is required in call to '*function-name*' + +## Remarks + +This warning indicates that sign of the type required by the format specifier and sign of the type of the expression passed in don't match. +Using the wrong format specifier is undefined behavior. To fix the warning, make sure that the format specifiers match the types of the expressions passed in. + +Code analysis name: `FORMAT_SIGN_MISMATCH` + +## Example + +The following example generates C6340: + +```cpp +#include + +void f(unsigned char a) +{ + printf("%hhd\n", a); // C6340 emitted. +} +``` +There are multiple ways to fix the undefined behavior. We can change the format specifier: + +```cpp +#include + +void f(unsigned char a) +{ + printf("%hhu\n", a); // No C6340 emitted. +} +``` + +We can change the type of the expression: + +```cpp +#include + +void f(signed char a) +{ + printf("%hhd\n", a); // No C6340 emitted. +} +``` + +As a last resort when overflow can't happen, we can introduce a cast: + +```cpp +#include + +void f(long long a) +{ + printf("%d\n", static_cast(a)); // No C6328 emitted. +} +``` + +## See also + +[C6328](c6328.md) + -> warning C6340: Mismatch on sign: Incorrect type passed as parameter in call to function diff --git a/docs/code-quality/c6381.md b/docs/code-quality/c6381.md index 41058a91dd9..b374965fd48 100644 --- a/docs/code-quality/c6381.md +++ b/docs/code-quality/c6381.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6381" -title: C6381 +title: "Warning C6381" +description: "Learn more about: Warning C6381" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6381"] +f1_keywords: ["C6381", "SHUTDOWN_API", "__WARNING_SHUTDOWN_API"] helpviewer_keywords: ["C6381"] -ms.assetid: c01a3040-26d4-47ac-b72d-7e1292ca435f --- -# C6381 +# Warning C6381 -> warning C6381: Shutdown API \ requires a valid dwReason or lpMessage +> Shutdown API '*function*' requires a valid dwReason or lpMessage -This warning is issued if InitiateSystemShutdownEx is called: +## Remarks -- Without passing a valid shutdown reason (dwReason). If dwReason parameter is zero, the default is an undefined shutdown. By default, it is also an unplanned shutdown. You should use one of the System Shutdown Reason Codes for this parameter. +This warning is issued if `InitiateSystemShutdownEx` is called: -- Without passing a shutdown message (lpMessage). +- Without passing a valid shutdown reason (`dwReason`). If `dwReason` parameter is zero, the default is an undefined shutdown. By default, it's also an unplanned shutdown. You should use one of the System Shutdown Reason Codes for this parameter. + +- Without passing a shutdown message (`lpMessage`). We recommend that you use appropriate parameters when calling this API to help system administrators determine the cause of the shutdown. +Code analysis name: `SHUTDOWN_API` + ## Example The following code generates this warning because dwReason is zero and lpMessage is null: diff --git a/docs/code-quality/c6383.md b/docs/code-quality/c6383.md index 14bd47580f6..ee46f686092 100644 --- a/docs/code-quality/c6383.md +++ b/docs/code-quality/c6383.md @@ -1,56 +1,43 @@ --- -description: "Learn more about: C6383" -title: C6383 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6383"] +title: "Warning C6383" +description: "Learn more about: Warning C6383" +ms.date: 09/07/2022 +f1_keywords: ["C6383", "ELEMENTS_TO_BYTES", "__WARNING_ELEMENTS_TO_BYTES"] helpviewer_keywords: ["C6383"] -ms.assetid: f5ff7938-0fbe-4b71-b98f-098fe887799d --- -# C6383 +# Warning C6383 -> warning C6383: buffer overrun due to conversion of an element count into a byte count: an element count is expected for parameter \ in call to \ +> Buffer overrun due to conversion of an element count into a byte count: an element count is expected for parameter *`parameter_name`* in call to *`function_name`* -This warning indicates that a non-constant byte count is being passed when an element count is required. Typically, this occurs when a variable is multiplied by the **`sizeof`** a type, but code analysis suggests that an element count is required. +## Remarks -## Example +This warning indicates that a non-constant byte count is being passed when an element count is instead required. -The following code generates this warning: +Typically, this warning occurs when a variable is multiplied by the `sizeof` a type. This issue will likely result in more bytes being copied to the buffer than it can hold. -```cpp -#include +Code analysis name: `ELEMENTS_TO_BYTES` -void f( wchar_t* t, wchar_t* s, int n ) -{ - // code ... - wcsncpy (t, s, n*sizeof(wchar_t)); // warning C6383 - // code ... -} -``` +## Example -To correct this warning, do not multiply the variable with the **`sizeof`** a type as shown in the following code: +The following code generates this warning. `wcsncpy` will allow `n * sizeof(wchar_t)` characters to be copied, but the buffer can only hold `n` characters. It should be noted that `wcsncpy` is an unsafe function, and shouldn't be used per [C28719](/windows-hardware/drivers/devtest/28719-banned-api-usage-use-updated-function-replacement). The unsafe variant is used here only for the purposes of demonstrating this warning: ```cpp -void f( wchar_t* t, wchar_t* s, int n ) +void f(wchar_t* t, wchar_t* s, int n) { - // code ... - wcsncpy (t, s, n); - // code ... + wcsncpy (t, s, n*sizeof(wchar_t)); } ``` -The following code corrects this warning by using the safe string manipulation function: +The following code corrects this warning by sending element count instead of the byte count: ```cpp -void f(wchar_t* t, wchar_t* s, size_t n) +void f( wchar_t* t, wchar_t* s, int n ) { - // code ... - wcsncpy_s( t, sizeof(s), s, n ); - // code ... + wcsncpy (t, s, n); } ``` ## See also -- [strncpy_s, _strncpy_s_l, wcsncpy_s, _wcsncpy_s_l, _mbsncpy_s, _mbsncpy_s_l](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) -- [sizeof Operator](../cpp/sizeof-operator.md) +- [`strncpy_s`, `_strncpy_s_l`, `wcsncpy_s`, `_wcsncpy_s_l`, `_mbsncpy_s`, `_mbsncpy_s_l`](../c-runtime-library/reference/strncpy-s-strncpy-s-l-wcsncpy-s-wcsncpy-s-l-mbsncpy-s-mbsncpy-s-l.md) +- [`sizeof` Operator](../cpp/sizeof-operator.md) diff --git a/docs/code-quality/c6384.md b/docs/code-quality/c6384.md index c91bee577af..23a603be8b1 100644 --- a/docs/code-quality/c6384.md +++ b/docs/code-quality/c6384.md @@ -1,23 +1,25 @@ --- -description: "Learn more about: C6384" -title: C6384 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6384"] +title: "Warning C6384" +description: "Learn more about: Warning C6384" +ms.date: 10/03/2022 +f1_keywords: ["C6384", "DIVIDING_SIZEOF_POINTER", "__WARNING_DIVIDING_SIZEOF_POINTER"] helpviewer_keywords: ["C6384"] -ms.assetid: 9c605b61-1485-49a8-847b-41170193dbf4 --- -# C6384 +# Warning C6384 -> warning C6384: dividing sizeof a pointer by another value +> Dividing sizeof a pointer by another value -This warning indicates that a size calculation might be incorrect. To calculate the number of elements in an array, one sometimes divides the size of the array by the size of the first element; however, when the array is actually a pointer, the result is typically different than intended. +## Remarks -If the pointer is a function parameter and the size of the buffer was not passed, it is not possible to calculate the maximum buffer available. When the pointer is allocated locally, the size used in the allocation should be used. +This warning indicates that a size calculation might be incorrect. To calculate the number of elements in an array, you sometimes divide the size of the array by the size of the first element. However, when the array is actually a pointer, the result is typically different than intended. + +If the pointer is a function parameter and the size of the buffer wasn't passed, it isn't possible to calculate the maximum buffer available. When the pointer is allocated locally, the size used in the allocation should be used. + +Code analysis name: `DIVIDING_SIZEOF_POINTER` ## Example -The following code generates this warning: +The following code generates warning C6384: ```cpp #include @@ -55,7 +57,7 @@ void f( ) } ``` -To correct this warning using the safe string function _tcsncpy_s, use the following code: +To correct this warning using the safe string function `_tcsncpy_s`, use the following code: ```cpp void f( ) @@ -69,9 +71,9 @@ void f( ) } ``` -Note that the use of new and delete have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `new` and `delete` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of potential leaks altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). ## See also -- [_mbsnbcpy_s, _mbsnbcpy_s_l](../c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md) -- [sizeof Operator](../cpp/sizeof-operator.md) +[`_mbsnbcpy_s`, `_mbsnbcpy_s_l`](../c-runtime-library/reference/mbsnbcpy-s-mbsnbcpy-s-l.md)\ +[`sizeof` Operator](../cpp/sizeof-operator.md) diff --git a/docs/code-quality/c6385.md b/docs/code-quality/c6385.md index 786ed5289d3..8e6446f76b7 100644 --- a/docs/code-quality/c6385.md +++ b/docs/code-quality/c6385.md @@ -1,18 +1,20 @@ --- -title: C6385 +title: "Warning C6385" description: "Describes C++ Code Analysis warning C6385 and how to resolve it." ms.date: 03/16/2020 -ms.topic: reference -f1_keywords: ["C6385"] +f1_keywords: ["C6385", "READ_OVERRUN", "__WARNING_READ_OVERRUN"] helpviewer_keywords: ["C6385"] -ms.assetid: 3e4961e7-0f09-42a8-8cc2-151109dfdbda --- -# C6385 +# Warning C6385 -> warning C6385: invalid data: accessing *buffer-name*, the readable size is *size1* bytes, but *size2* bytes may be read: Lines: *x*, *y* +> Invalid data: accessing *buffer-name*, the readable size is *size1* bytes, but *size2* bytes may be read: Lines: *x*, *y* + +## Remarks The readable extent of the buffer might be smaller than the index used to read from it. Attempts to read data outside the valid range leads to buffer overrun. +Code analysis name: `READ_OVERRUN` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6386.md b/docs/code-quality/c6386.md index 5121e5b1c42..1b08ddf6bdf 100644 --- a/docs/code-quality/c6386.md +++ b/docs/code-quality/c6386.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6386" -title: C6386 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6386"] +title: "Warning C6386" +description: "Learn more about: Warning C6386" +ms.date: 4/30/2025 +f1_keywords: ["C6386", "WRITE_OVERRUN", "__WARNING_WRITE_OVERRUN"] helpviewer_keywords: ["C6386"] -ms.assetid: 84e69fe8-8f03-4bb3-b194-e5551882e214 --- -# C6386 +# Warning C6386 -> warning C6386: buffer overrun: accessing \, the writable size is \ bytes, but \ bytes may be written: Lines: x, y +> Buffer overrun: accessing '*buffer name*', the writable size is '*size1*' bytes, but '*size2*' bytes may be written: Lines: x, y -This warning indicates that the writable extent of the specified buffer might be smaller than the index used to write to it. This can cause buffer overrun. +## Remarks + +This warning indicates that the writable extent of the specified buffer might be smaller than the index used to write to it. This defect can cause buffer overrun. + +Code analysis name: `WRITE_OVERRUN` ## Example @@ -20,15 +22,14 @@ The following code generates both this warning and [C6201](../code-quality/c6201 ```cpp #define MAX 25 -void f ( ) +void f() { - char ar[MAX]; - // code ... - ar[MAX] = '\0'; + char a[MAX]; + a[MAX] = '\0'; // this writes one element past the end of the buffer } ``` -To correct both warnings, use the following code: +To correct the warning, use the following code which accounts for the fact that array indexes are zero-based. Thus `MAX - 1` is the last element in the buffer: ```cpp #define MAX 25 @@ -36,8 +37,7 @@ To correct both warnings, use the following code: void f ( ) { char a[MAX]; - // code ... - a[MAX - 1] = '\0'; + a[MAX-1] = '\0'; } ``` diff --git a/docs/code-quality/c6387.md b/docs/code-quality/c6387.md index 5721b46c5e5..b6aa4f4bc65 100644 --- a/docs/code-quality/c6387.md +++ b/docs/code-quality/c6387.md @@ -1,54 +1,101 @@ --- -description: "Learn more about: C6387" -title: C6387 -ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6387"] +title: "Warning C6387" +description: "Learn more about: Warning C6387" +ms.date: 04/10/2026 +f1_keywords: ["C6387", "INVALID_PARAM_VALUE_1", "__WARNING_INVALID_PARAM_VALUE_1"] helpviewer_keywords: ["C6387"] -ms.assetid: 3ea2fc4d-ffc3-4c3c-bfae-d42aa56235d8 +ai-usage: ai-assisted --- -# C6387 +# Warning C6387 -> warning C6387: \ may be \: this does not adhere to the specification for the function \: Lines: x, y +> '*argument*' may be '*value*': this does not adhere to the specification for the function '*function name*': Lines: x, y + +## Remarks This warning is raised if an annotated function parameter is being passed an unexpected value. For example, passing a potentially null value to a parameter that is marked with `_In_` annotation generates this warning. +This commonly happens when one function is annotated with `_Post_ _Null_` on its return value (meaning it may return null), and the result is then passed to another function that expects a non-null `_In_` parameter. To fix the issue, either change the first function's annotation to `_Post_ _Notnull_` if it truly never returns null, or add a null check before passing the value to the second function. + +> [!NOTE] +> The SAL annotations (`_Post_ _Null_`, `_Post_ _Notnull_`, `_In_`, and so on) are used on function declarations to describe the contract of the function's parameters and return values. They do not apply to local variable declarations. + +Code analysis name: `INVALID_PARAM_VALUE_1` + ## Example -The following code generates this warning because a null parameter is passed to `f(char *)`: +The following code generates this warning because the function `g` is annotated as potentially returning null (`_Post_ _Null_`), and the result is passed to `f`, which requires a non-null input (`_In_`): ```cpp - #include +#include -_Post_ _Null_ char * g(); +_Post_ _Null_ char* g() +{ + return nullptr; +} -void f(_In_ char *pch); +void f(_In_ char* pch) +{ + printf("%s\n", pch);; +} -void main() +int main() { - char *pCh = g(); + char* pCh = g(); f(pCh); // Warning C6387 } ``` -To correct this warning, use the following code: +To correct this warning, you can change the annotation on `g` if it never actually returns null: ```cpp - #include +#include -_Post_ _Notnull_ char * g(); +_Post_ _Notnull_ char* g() +{ + static char buf[] = "hello"; + return buf; +} -void f(_In_ char *pch); +void f(_In_ char* pch) +{ + printf("%s\n", pch); +} + +int main() +{ + char* pCh = g(); + f(pCh); // No warning C6387 +} +``` + +Alternatively, you can add a null check before passing the value: + +```cpp +#include +#include + +_Post_ _Null_ char* g() +{ + return nullptr; +} + +void f(_In_ char* pch) +{ + printf("%s\n", pch); +} -void main() +int main() { - char *pCh = g(); - f(pCh); + char* pCh = g(); + if (pCh != nullptr) + { + f(pCh); // No warning C6387 + } } ``` ## See also -[strlen, wcslen, _mbslen, _mbslen_l, _mbstrlen, _mbstrlen_l](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) +[`strlen`, `wcslen`, `_mbslen`, `_mbslen_l`, `_mbstrlen`, `_mbstrlen_l`](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) diff --git a/docs/code-quality/c6388.md b/docs/code-quality/c6388.md index 2a188f19a58..229efeee446 100644 --- a/docs/code-quality/c6388.md +++ b/docs/code-quality/c6388.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6388" -title: C6388 +title: "Warning C6388" +description: "Learn more about: Warning C6388" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6388"] +f1_keywords: ["C6388", "INVALID_PARAM_VALUE_2", "__WARNING_INVALID_PARAM_VALUE_2"] helpviewer_keywords: ["C6388"] -ms.assetid: 667fe9cf-cc53-49f9-b6c0-6ee87c397568 --- -# C6388 +# Warning C6388 -> warning C6388: \ may not be \: this does not adhere to the specification for the function \: Lines: x, y +> '*argument*' may not be '*value*': this does not adhere to the specification for the function '*function-name*': Lines: x, y -This warning indicates that an unexpected value is being used in the specified context. This is typically reported for values passed as arguments to a function that does not expect it. +## Remarks + +This warning indicates that an unexpected value is being used in the specified context. This warning is typically reported for values passed as arguments to a function that doesn't expect it. + +Code analysis name: `INVALID_PARAM_VALUE_2` ## Example -The following C++ code generates this warning because DoSomething expects a null value but a potentially non-null value might be passed: +The following code generates warning C6388 because `DoSomething` expects a null value but a potentially non-null value might be passed: ```cpp - +// C6388_warning.cpp #include #include #include @@ -34,10 +36,10 @@ void f() } ``` -To correct this warning, use the following sample code: +To correct this warning, use the following example code: ```cpp - +// C6388_no_warning.cpp #include #include #include @@ -58,4 +60,4 @@ void f() } ``` -Note that the use of malloc and free have many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Template Library (STL). These include [shared_ptr](../standard-library/shared-ptr-class.md), [unique_ptr](../standard-library/unique-ptr-class.md), and [vector](../standard-library/vector.md). For more information, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). +The use of `malloc` and `free` has many pitfalls in terms of memory leaks and exceptions. To avoid these kinds of leaks and exception problems altogether, use the mechanisms that are provided by the C++ Standard Library (STL). These include [`shared_ptr`](../standard-library/shared-ptr-class.md), [`unique_ptr`](../standard-library/unique-ptr-class.md), and containers such as [`vector`](../standard-library/vector.md). For more information, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md) and [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). diff --git a/docs/code-quality/c6389.md b/docs/code-quality/c6389.md index 043cf4b80d6..0b4fb2a1d54 100644 --- a/docs/code-quality/c6389.md +++ b/docs/code-quality/c6389.md @@ -1,12 +1,15 @@ --- -title: C6389 +title: "Warning C6389" description: "Describes the Microsoft C/C++ code analysis warning C6389, its causes, and how to address it." ms.date: 06/09/2021 -f1_keywords: ["C6389"] +f1_keywords: ["C6389", "MARK_INTERNAL_OR_MISSING_COMMON_DECL"] helpviewer_keywords: ["C6389"] --- +# Warning C6389 -# C6389: MARK_INTERNAL_OR_MISSING_COMMON_DECL +> Move '*declaration*' to anonymous namespace or put a forward declaration in a common header included in this file. + +## Remarks This check is intended to help reduce the visibility of certain symbols and to modularize the code. In multi-file C++ projects, each declaration should be either local to a C++ file (part of the anonymous namespace) or declared in a common header file that's included by multiple C++ files. @@ -14,8 +17,12 @@ When this check flags a declaration, either it should be moved to an anonymous n The rule is an experimental rule that must be explicitly enabled in a rule set file to work. For more information about rule sets, see [Use rule sets to group code analysis rules](/visualstudio/code-quality/using-rule-sets-to-group-code-analysis-rules). +Code analysis name: `MARK_INTERNAL_OR_MISSING_COMMON_DECL` + ## Example +The following example generates C6389: + ```cpp // A.h struct X; diff --git a/docs/code-quality/c6390.md b/docs/code-quality/c6390.md index 973cbbd9cf9..225bfd16e4f 100644 --- a/docs/code-quality/c6390.md +++ b/docs/code-quality/c6390.md @@ -1,17 +1,24 @@ --- -title: C6390 +title: "Warning C6390" description: "Describes the Microsoft C/C++ code analysis warning C6390, its causes, and how to address it." ms.date: 06/17/2022 -f1_keywords: ["C6390"] +f1_keywords: ["C6390", "NO_NULLCHECK_FOR_THIS"] helpviewer_keywords: ["C6390"] --- +# Warning C6390 -# C6390: NO_NULLCHECK_FOR_THIS +> According to the C++ standard, the value of 'this' is never null; some compilers will optimize this check out -According to the C++ standard, the value of `this` is never null; some compilers will optimize null checks for `this` out. While MSVC is not doing such optimizations, code relying on null-valued `this` can trigger unexpected behavior when compiled with other compilers. This warning helps detect these portability problems. +## Remarks + +While MSVC doesn't do such optimizations, some compilers optimize null checks for `this` out. Code that relies on null-valued `this` can trigger unexpected behavior when compiled with other compilers. This warning helps detect these portability problems. + +Code analysis name: `NO_NULLCHECK_FOR_THIS` ## Example +The following example generates C6390: + ```cpp struct X { diff --git a/docs/code-quality/c6392.md b/docs/code-quality/c6392.md new file mode 100644 index 00000000000..63f9a7c3139 --- /dev/null +++ b/docs/code-quality/c6392.md @@ -0,0 +1,60 @@ +--- +title: "Warning C6392" +description: "Learn more about: 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 *' + +## Remarks + +This rule was added in Visual Studio 2022 17.8. + +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 00000000000..2de6638f3ab --- /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 + +## Remarks + +This rule was added in Visual Studio 2022 17.8. + +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 00000000000..913accff0e0 --- /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 + +## Remarks + +This rule was added in Visual Studio 2022 17.8. + +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 00000000000..52a0feeb35a --- /dev/null +++ b/docs/code-quality/c6395.md @@ -0,0 +1,37 @@ +--- +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 + +The following example generates C6395: + +```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 00000000000..210935d9f60 --- /dev/null +++ b/docs/code-quality/c6396.md @@ -0,0 +1,36 @@ +--- +title: "Warning C6396" +description: "Learn more about: Warning C6396: sizeof('integerConstant') always returns the size of the underlying integer type" +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 + +The following example generates C6396: + +```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 00000000000..a45d0582c08 --- /dev/null +++ b/docs/code-quality/c6397.md @@ -0,0 +1,40 @@ +--- +title: "Warning C6397" +description: "Learn more about: Warning C6397: The address-of operator cannot return null pointer in well-defined code" +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 + +The following example generates C6397: + +```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 00000000000..072a3669b65 --- /dev/null +++ b/docs/code-quality/c6398.md @@ -0,0 +1,44 @@ +--- +title: "Warning C6398" +description: "Learn more about: Warning C6398: The address-of a field cannot be null in well-defined code" +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 + +The following example generates C6398: + +```cpp +struct A { int* x; }; + +bool hasNullField(A *a) +{ + return &a->x == nullptr; // C6398 reported here. +} +``` + +To fix this issue, double check if the use of unary `&` was intentional: + +```cpp +struct A { int* x; }; + +bool hasNullField(A *a) +{ + return a->x == nullptr; // no C6398 reported here. +} +``` + +## See also + +[C6397](c6397.md) \ No newline at end of file diff --git a/docs/code-quality/c6400.md b/docs/code-quality/c6400.md index 4a3729c9876..ed5d187c376 100644 --- a/docs/code-quality/c6400.md +++ b/docs/code-quality/c6400.md @@ -1,22 +1,24 @@ --- -description: "Learn more about: C6400" -title: C6400 +title: "Warning C6400" +description: "Learn more about: Warning C6400" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6400"] +f1_keywords: ["C6400", "LOCALE_DEPENDENT_CONSTANT_STRING_COMPARISON", "__WARNING_LOCALE_DEPENDENT_CONSTANT_STRING_COMPARISON"] helpviewer_keywords: ["C6400"] -ms.assetid: 35808969-1d43-41e8-bcda-33635637fb26 --- -# C6400 +# Warning C6400 -> warning C6400: Using \ to perform a case-insensitive compare to constant string \. Yields unexpected results in non-English locales +> Using '*function name*' to perform a case-insensitive compare to constant string '*string name*'. Yields unexpected results in non-English locales -This warning indicates that a case-insensitive comparison to a constant string is being performed in a locale-dependent way, when, apparently, a locale-independent comparison was intended. +## Remarks -The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" will not match ".GIF"; in Vietnamese, "LogIn" will not match "LOGIN". +This warning indicates that a case-insensitive comparison to a constant string is being done in a locale-dependent way. It appears that a locale-independent comparison was intended. + +The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" won't match ".GIF"; in Vietnamese, "LookUp" won't match "LOOKUP". String comparisons should typically be performed with the `CompareString` function. To perform a locale-independent comparison on Windows XP, the first parameter should be the constant `LOCALE_INVARIANT`. +Code analysis name: `LOCALE_DEPENDENT_CONSTANT_STRING_COMPARISON` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6401.md b/docs/code-quality/c6401.md index 521a57d2c1c..071f30b46bc 100644 --- a/docs/code-quality/c6401.md +++ b/docs/code-quality/c6401.md @@ -1,19 +1,19 @@ --- -description: "Learn more about: C6401" -title: C6401 +title: "Warning C6401" +description: "Learn more about: Warning C6401" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6401"] +f1_keywords: ["C6401", "DEFAULT_LOCALE_CONSTANT_STRING_COMPARISON", "__WARNING_DEFAULT_LOCALE_CONSTANT_STRING_COMPARISON"] helpviewer_keywords: ["C6401"] -ms.assetid: d57b1c94-57a3-4d4b-a7de-8b9ffbac3ebe --- -# C6401 +# Warning C6401 -> warning C6401: Using \ in a default locale to perform a case-insensitive compare to constant string \< string name>. Yields unexpected results in non-English locales +> Using '*function name*' in a default locale to perform a case-insensitive compare to constant string '*string name*'. Yields unexpected results in non-English locales -This warning indicates that a case-insensitive comparison to a constant string is being performed when specifying the default locale; usually, a locale-independent comparison was intended. +## Remarks -The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" will not match ".GIF"; in Vietnamese, "LogIn" will not match "LOGIN". +This warning indicates that a case-insensitive comparison to a constant string is being done when specifying the default locale. Usually, a locale-independent comparison was intended. + +The typical consequence of this defect is incorrect behavior in non-English speaking locales. For example, in Turkish, ".gif" won't match ".GIF"; in Vietnamese, "LookUp" won't match "LOOKUP". The `CompareString` function takes a locale as an argument; however, passing in a default locale, for example, the constant `LOCALE_USER_DEFAULT`, will cause different behaviors in different locales, depending on the user's default. Usually, case-insensitive comparisons against a constant string should be performed in a locale-independent comparison. @@ -28,6 +28,8 @@ CompareString(LOCALE_INVARIANT, -1) == CSTR_EQUAL ``` +Code analysis name: `DEFAULT_LOCALE_CONSTANT_STRING_COMPARISON` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6411.md b/docs/code-quality/c6411.md index e22a8d4df3f..4e1627384d3 100644 --- a/docs/code-quality/c6411.md +++ b/docs/code-quality/c6411.md @@ -1,16 +1,19 @@ --- -description: "Learn more about: C6411" -title: C6411 +title: "Warning C6411" +description: "Learn more about: Warning C6411" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6411"] -ms.assetid: 6bbc1734-eec4-4ad6-9908-4ed2a5f025db +f1_keywords: ["C6411", "POTENTIAL_READ_OVERRUN"] +helpviewer_keywords: ["C6411"] --- -# C6411 +# Warning C6411 -> warning C6411: Potentially reading invalid data from the buffer. +> Potentially reading invalid data from '*buffer*'. -This warning indicates that the value of the index that is used to read from the buffer can exceed the readable size of the buffer. Because the code analysis tool reports this warning when it cannot reduce a complex expression that represents the buffer size, or the index used to access the buffer, this warning might be reported in error. +## Remarks + +This warning indicates that the value of the index that is used to read from the buffer can exceed the readable size of the buffer. The code analysis tool may report this warning in error. The error may occur when it can't reduce a complex expression that represents the buffer size, or the index used to access the buffer. + +Code analysis name: `POTENTIAL_READ_OVERRUN` ## Example diff --git a/docs/code-quality/c6412.md b/docs/code-quality/c6412.md index 0d8da858159..cd387c66074 100644 --- a/docs/code-quality/c6412.md +++ b/docs/code-quality/c6412.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: C6412" -title: C6412 +title: "Warning C6412" +description: "Learn more about: Warning C6412" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6412"] -ms.assetid: 6498f045-1bdc-4428-9d95-d9498de207bb +f1_keywords: ["C6412", "POTENTIAL_WRITE_OVERRUN"] +helpviewer_keywords: ["C6412"] --- -# C6412 +# Warning C6412 -> warning C6412: Potential buffer overrun while writing to buffer. The writable size is *write_size* bytes, but *write_index* bytes may be written. +> Potential buffer overrun while writing to buffer. The writable size is *write_size* bytes, but *write_index* bytes may be written. -This warning indicates that the value of the index that is used to write to the buffer can exceed the writeable size of the buffer. +## Remarks -Because the code analysis tool reports this warning when it cannot reduce a complex expression that represents the buffer size, or the index used to access the buffer, this warning might be reported in error. +This warning indicates that the value of the index that's used to write to the buffer can exceed the writeable size of the buffer. + +The code analysis tool may report this warning in error. It reports this warning when it can't reduce a complex expression that represents the buffer size, or the index used to access the buffer. + +Code analysis name: `POTENTIAL_WRITE_OVERRUN` ## Example diff --git a/docs/code-quality/c6500.md b/docs/code-quality/c6500.md index 14bd402e7d6..4b2373b63d5 100644 --- a/docs/code-quality/c6500.md +++ b/docs/code-quality/c6500.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6500" -title: C6500 +title: "Warning C6500" +description: "Learn more about: Warning C6500" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6500"] +f1_keywords: ["C6500", "INVALID_ATTRIBUTE_PROPERTY", "__WARNING_INVALID_ATTRIBUTE_PROPERTY"] helpviewer_keywords: ["C6500"] -ms.assetid: bfc61ec1-8ac5-4465-a23c-91418fbc4552 --- -# C6500 +# Warning C6500 -> warning C6500: invalid annotation: value for \ property is invalid +> Invalid annotation: value for '*name*' property is invalid + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that a property value used in the annotation is not valid. For example, it can occur if an incorrect level of dereference is used in the Deref property, or if you use a constant value that is larger than size_t for properties like ElementSize. +This warning indicates that a property value used in the annotation isn't valid. For example, it can occur if an incorrect level of dereference is used in the `Deref` property, or if you use a constant value that is larger than `size_t` for properties like `ElementSize`. + +Code analysis name: `INVALID_ATTRIBUTE_PROPERTY` ## Example -The following code generates this warning because an incorrect level of dereference is used in the Pre condition: +The following code generates this warning because an incorrect level of dereference is used in the `Pre` condition: ```cpp // C @@ -32,7 +34,7 @@ using namespace vc_attributes; void f( [Pre( Deref=2, Access=Read )] char buffer[] ); ``` -To correct this warning, specify the correct level of dereference, as shown in the following sample code: +To correct this warning, specify the correct level of dereference, as shown in the following example code: ```cpp // C diff --git a/docs/code-quality/c6501.md b/docs/code-quality/c6501.md index 8e663f71e46..6b552356726 100644 --- a/docs/code-quality/c6501.md +++ b/docs/code-quality/c6501.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6501" -title: C6501 +title: "Warning C6501" +description: "Learn more about: Warning C6501" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6501"] +f1_keywords: ["C6501", "CONFLICTING_ATTRIBUTE_PROPERTY_VALUES", "__WARNING_CONFLICTING_ATTRIBUTE_PROPERTY_VALUES"] helpviewer_keywords: ["C6501"] -ms.assetid: f9e8b847-2516-4bbb-bb1c-c87cfbacf254 --- -# C6501 +# Warning C6501 -> warning C6501: annotation conflict: \ property conflicts with previously specified property +> Annotation conflict: '*name*' property conflicts with previously specified property + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates the presence of conflicting properties in the annotation. This typically occurs when multiple properties that serve similar purpose are used to annotate a parameter or return value. To correct the warning, you must choose the property that best addresses your need. +This warning indicates the presence of conflicting properties in the annotation. The warning typically occurs when multiple properties that serve similar purpose are used to annotate a parameter or return value. To correct the warning, you must choose the property that best addresses your need. + +Code analysis name: `CONFLICTING_ATTRIBUTE_PROPERTY_VALUES` ## Example diff --git a/docs/code-quality/c6503.md b/docs/code-quality/c6503.md index 1d1f71cb4d6..5c320d0eaed 100644 --- a/docs/code-quality/c6503.md +++ b/docs/code-quality/c6503.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6503" -title: C6503 +title: "Warning C6503" +description: "Learn more about: Warning C6503" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6503"] +f1_keywords: ["C6503", "REFERENCES_CANT_BE_NULL", "__WARNING_REFERENCES_CANT_BE_NULL"] helpviewer_keywords: ["C6503"] -ms.assetid: a6212938-bef9-4830-becb-6baa70b53e97 --- -# C6503 +# Warning C6503 -> warning C6503: Invalid annotation: references and arrays may not be marked Null=Yes or Null=Maybe +> Invalid annotation: references and arrays may not be marked `Null=Yes` or `Null=Maybe` + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that Null property is incorrectly used on a reference or array type. A reference or array type holds the address of an object and must point to a valid object. Because reference and array types cannot be null, you must correct the error by either removing the Null property or by setting the Null property value to No. +This warning indicates that `Null` property is incorrectly used on a reference or array type. A reference or array type holds the address of an object and must point to a valid object. Because reference and array types can't be null, you must correct the error by either removing the `Null` property or by setting the `Null` property value to `No`. + +Code analysis name: `REFERENCES_CANT_BE_NULL` ## Example diff --git a/docs/code-quality/c6504.md b/docs/code-quality/c6504.md index 319eb776d8e..eb9d24fa536 100644 --- a/docs/code-quality/c6504.md +++ b/docs/code-quality/c6504.md @@ -1,66 +1,64 @@ --- -description: "Learn more about: C6504" -title: C6504 -ms.date: 12/19/2019 -ms.topic: reference -f1_keywords: ["C6504"] +title: "Warning C6504" +description: "Learn more about: Warning C6504" +ms.date: 10/03/2022 +f1_keywords: ["C6504", "NULL_ON_NON_POINTER", "__WARNING_NULL_ON_NON_POINTER"] helpviewer_keywords: ["C6504"] -ms.assetid: 6baeed46-e73d-4974-af16-7487c55b3473 --- -# C6504 +# Warning C6504 -> warning C6504: invalid annotation: property may only be used on values of pointer, pointer-to-member, or array type +> Invalid annotation: property may only be used on values of pointer, pointer-to-member, or array type -This warning indicates the use of a pointer-specific SAL annotation on a non-pointer data type. For more information about what data types are supported by properties, see [Annotation Properties](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +## Remarks + +This warning indicates the use of a pointer-specific SAL annotation on a non-pointer data type. + +For more information about what data types are supported by properties, see [Annotation Properties](using-sal-annotations-to-reduce-c-cpp-code-defects.md). + +Code analysis name: `NULL_ON_NON_POINTER` ## Example -```cpp -#include +The following code generates warning C6504. This issue stems from the use of the pointer-specific `_Maybenull_` and `_Notnull_` on reference `pt`. +```cpp class Point { -public: - // members + public: + // members }; -// Oops, according to this annotation, pt may be null which does not make sense for a reference types void f(_Pre_ _Maybenull_ Point& pt) { // code ... } -// Oops, according to this annotation, pt cannot be null which does not make sense for a reference types void g(_Pre_ _Notnull_ Point& pt) { // code ... } ``` -To correct this warning remove the annotation if it does not make sense. You could also change to an annotation to be applicable to the type used, or change to type to match the annotation. +To correct this warning, remove the annotation if it doesn't make sense. You could also change to an annotation that's applicable to the type used, or change the type to match the annotation. The following code remediates this warning by changing the first instance of `pt` to a pointer and by removing the second annotation to match the reference type. ```cpp -#include - class Point { -public: - // members + public: + // members }; -// Changed to pointer type because it may be null void f(_Pre_ _Maybenull_ Point* pt) { // code ... } -// Removed annotation because it did not apply to reference types. void g(Point& pt) { // code ... } ``` -## See Also +## See also [Annotation Properties](using-sal-annotations-to-reduce-c-cpp-code-defects.md) diff --git a/docs/code-quality/c6505.md b/docs/code-quality/c6505.md index 08843cd99a4..317778e442c 100644 --- a/docs/code-quality/c6505.md +++ b/docs/code-quality/c6505.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6505" -title: C6505 +title: "Warning C6505" +description: "Learn more about: Warning C6505" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6505"] +f1_keywords: ["C6505", "MUSTCHECK_ON_VOID", "__WARNING_MUSTCHECK_ON_VOID"] helpviewer_keywords: ["C6505"] -ms.assetid: 1883ce60-48d7-41c8-add8-814e4b8b908b --- -# C6505 +# Warning C6505 -> warning C6505: invalid annotation: MustCheck property may not be used on values of void type +> Invalid annotation: MustCheck property may not be used on values of void type -This warning indicated that MustCheck property was used on a void data type. You cannot use MustCheck property on void type. Either remove the MustCheck property or use another data type. +## Remarks + +This warning indicated that MustCheck property was used on a void data type. You can't use `MustCheck` property on `void` type. Either remove the `MustCheck` property or use another data type. + +Code analysis name: `MUSTCHECK_ON_VOID` ## Example diff --git a/docs/code-quality/c6506.md b/docs/code-quality/c6506.md index e80d7abe48c..6cd1cf750b2 100644 --- a/docs/code-quality/c6506.md +++ b/docs/code-quality/c6506.md @@ -1,34 +1,36 @@ --- -description: "Learn more about: C6506" -title: C6506 +title: "Warning C6506" +description: "Learn more about: Warning C6506" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6506"] +f1_keywords: ["C6506", "BUFFER_SIZE_ON_NON_POINTER_OR_ARRAY", "__WARNING_BUFFER_SIZE_ON_NON_POINTER_OR_ARRAY"] helpviewer_keywords: ["C6506"] -ms.assetid: 20b87ee8-13ea-4d71-95a1-2b2d144d196a --- -# C6506 +# Warning C6506 -> warning C6506: invalid annotation: \ property may only be used on values of pointer or array types +> Invalid annotation: '*name*' property may only be used on values of pointer or array types + +## Remarks This warning indicates that a property is used on a type other than pointer or array types. The Access, Tainted, and Valid properties can be used on all data types. Other properties, such as ValidBytesConst, ValidElementsConst, ElementSize, and NullTerminted support pointer, pointer to members, or array types. For a complete list of properties and the supported data types, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +Code analysis name: `BUFFER_SIZE_ON_NON_POINTER_OR_ARRAY` + ## Example The following code generates this warning: ```cpp -#include +#include void f(_Out_ char c) { c = 'd'; } ``` -To correct this warning, use a pointer or an array type, as shown in the following sample code: +To correct this warning, use a pointer or an array type, as shown in the following example code: ```cpp -#include +#include void f(_Out_ char *c) { *c = 'd'; diff --git a/docs/code-quality/c6508.md b/docs/code-quality/c6508.md index 2d5020e858c..f48ec901cc3 100644 --- a/docs/code-quality/c6508.md +++ b/docs/code-quality/c6508.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6508" -title: C6508 +title: "Warning C6508" +description: "Learn more about: Warning C6508" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6508"] +f1_keywords: ["C6508", "WRITE_ACCESS_ON_CONST", "__WARNING_WRITE_ACCESS_ON_CONST"] helpviewer_keywords: ["C6508"] -ms.assetid: ac5b23c8-ab9e-481b-bc97-8404f0b63100 --- -# C6508 +# Warning C6508 -> warning C6508: invalid annotation: write access is not allowed on const values +> Invalid annotation: write access is not allowed on const values + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning indicates that the Access property specified on a const parameter implies that it can be written to. For constant values, Access=Read is the only valid setting. +Code analysis name: `WRITE_ACCESS_ON_CONST` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6509.md b/docs/code-quality/c6509.md index e40431abd59..e969a7c5d47 100644 --- a/docs/code-quality/c6509.md +++ b/docs/code-quality/c6509.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6509" -title: C6509 +title: "Warning C6509" +description: "Learn more about: Warning C6509" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6509"] +f1_keywords: ["C6509", "RETURN_USED_ON_PRECONDITION", "__WARNING_RETURN_USED_ON_PRECONDITION"] helpviewer_keywords: ["C6509"] -ms.assetid: 6311bfd9-8372-48da-b01b-1c8775c38449 --- -# C6509 +# Warning C6509 -> warning C6509: invalid annotation: 'return' cannot be referenced from a precondition +> Invalid annotation: 'return' cannot be referenced from a precondition -This warning indicates that the **`return`** keyword cannot be used in a precondition. The **`return`** keyword is used to terminate the execution of a function and return control to the calling function. +## Remarks + +This warning indicates that the **`return`** keyword can't be used in a precondition. The **`return`** keyword is used to terminate the execution of a function and return control to the calling function. + +Code analysis name: `RETURN_USED_ON_PRECONDITION` ## Example diff --git a/docs/code-quality/c6510.md b/docs/code-quality/c6510.md index 7095859ba05..b390495e5f6 100644 --- a/docs/code-quality/c6510.md +++ b/docs/code-quality/c6510.md @@ -1,17 +1,19 @@ --- -description: "Learn more about: C6510" -title: C6510 +title: "Warning C6510" +description: "Learn more about: Warning C6510" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6510"] +f1_keywords: ["C6510", "NULLTERMINATED_ON_NON_POINTER", "__WARNING_NULLTERMINATED_ON_NON_POINTER"] helpviewer_keywords: ["C6510"] -ms.assetid: b7fc5eb4-3311-442c-ac79-401e88ef2129 --- -# C6510 +# Warning C6510 -> warning C6510: Invalid annotation: 'NullTerminated' property may only be used on buffers whose elements are of integral or pointer type: Function '\' \. +> Invalid annotation: 'NullTerminated' property may only be used on buffers whose elements are of integral or pointer type: Function ''*function*'' '*parameter*'. -This warning indicates an incorrect use of the **NullTerminated** property (those ending in '`_z`'). You can only use this type of property on pointer or array types. +## Remarks + +This warning indicates an incorrect use of the **NullTerminated** property (the ones ending in '`_z`'). You can only use this type of property on pointer or array types. + +Code analysis name: `NULLTERMINATED_ON_NON_POINTER` ## Example diff --git a/docs/code-quality/c6511.md b/docs/code-quality/c6511.md index f8baeaf483b..37d75c8a480 100644 --- a/docs/code-quality/c6511.md +++ b/docs/code-quality/c6511.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6511" -title: C6511 +title: "Warning C6511" +description: "Learn more about: Warning C6511" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6511"] +f1_keywords: ["C6511", "MUSTCHECK_MAYBE", "__WARNING_MUSTCHECK_MAYBE"] helpviewer_keywords: ["C6511"] -ms.assetid: 1a0ac213-c205-4fb1-9bc3-3dc7885329fa --- -# C6511 +# Warning C6511 -> warning C6511: invalid annotation: MustCheck property must be Yes or No +> Invalid annotation: MustCheck property must be Yes or No + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates an invalid value for MustCheck property was specified. The only valid values for this property are: Yes and No. +This warning indicates an invalid value for `MustCheck` property was specified. The only valid values for this property are: Yes and No. + +Code analysis name: `MUSTCHECK_MAYBE` ## Example diff --git a/docs/code-quality/c6513.md b/docs/code-quality/c6513.md index 45c5d0bb6f3..7f4d110c621 100644 --- a/docs/code-quality/c6513.md +++ b/docs/code-quality/c6513.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6513" -title: C6513 +title: "Warning C6513" +description: "Learn more about: Warning C6513" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6513"] +f1_keywords: ["C6513", "ELEMENT_SIZE_WITHOUT_BUFFER_SIZE", "__WARNING_ELEMENT_SIZE_WITHOUT_BUFFER_SIZE"] helpviewer_keywords: ["C6513"] -ms.assetid: b27780ac-b237-4b26-a796-68a920da73a3 --- -# C6513 +# Warning C6513 -> warning C6513: invalid annotation: ElementSizeConst requires additional size properties +> Invalid annotation: ElementSizeConst requires additional size properties + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that ElementSizeConst requires other properties that are missing from the annotation. Specifying ElementSizeConst alone does not provide any benefit to the analysis process. In addition to specifying ElementSize, other properties such as ValidElementsConst or WritableElementsConst must also be specified. +This warning indicates that `ElementSizeConst` requires other properties that are missing from the annotation. Specifying `ElementSizeConst` alone doesn't provide any benefit to the analysis process. In addition to specifying `ElementSize`, other properties such as `ValidElementsConst` or `WritableElementsConst` must also be specified. + +Code analysis name: `ELEMENT_SIZE_WITHOUT_BUFFER_SIZE` ## Example diff --git a/docs/code-quality/c6514.md b/docs/code-quality/c6514.md index e0b4cd94826..b0826ee86ce 100644 --- a/docs/code-quality/c6514.md +++ b/docs/code-quality/c6514.md @@ -1,23 +1,23 @@ --- -description: "Learn more about: C6514" -title: C6514 +title: "Warning C6514" +description: "Learn more about: Warning C6514" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6514"] +f1_keywords: ["C6514", "BUFFER_SIZE_EXCEEDS_ARRAY_SIZE", "__WARNING_BUFFER_SIZE_EXCEEDS_ARRAY_SIZE"] helpviewer_keywords: ["C6514"] -ms.assetid: 4930a9f9-c721-437f-8754-cf39b30ea2db --- -# C6514 +# Warning C6514 -> warning C6514: invalid annotation: value of the \ property exceeds the size of the array +> Invalid annotation: value of the '*name*' property exceeds the size of the array ## Remarks This warning indicates that a property value exceeds the size of the array specified in the parameter being annotated. This warning occurs when the value specified for the annotation property is greater than the actual length of the array being passed. +Code analysis name: `BUFFER_SIZE_EXCEEDS_ARRAY_SIZE` + ## Example -The following code generates this warning because the size of the array is 6 whereas the ValidElementsConst property value is 8: +The following code generates this warning because the size of the array is 6 but the `ValidElementsConst` property value is 8: ```cpp // C @@ -30,7 +30,7 @@ using namespace vc_attributes; void f( [Pre(Deref=1, ValidElementsConst=8)] char(*matrix) [6] ); ``` -To correct this warning, make sure the size of specified in ValidElementsConst is less than or equal to the size of the array, as shown in the following sample code: +To correct this warning, make sure the size of specified in ValidElementsConst is less than or equal to the size of the array, as shown in the following example code: ```cpp // C diff --git a/docs/code-quality/c6515.md b/docs/code-quality/c6515.md index 85da3d19fdc..b8d51042420 100644 --- a/docs/code-quality/c6515.md +++ b/docs/code-quality/c6515.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: C6515" -title: C6515 +title: "Warning C6515" +description: "Learn more about: Warning C6515" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6515"] +f1_keywords: ["C6515", "BUFFER_SIZE_ON_NON_POINTER", "__WARNING_BUFFER_SIZE_ON_NON_POINTER"] helpviewer_keywords: ["C6515"] -ms.assetid: e0f21858-0fea-427b-965a-a7eff62e1371 --- -# C6515 +# Warning C6515 -> warning C6515 - invalid annotation: \ property may only be used on values of pointer type +> Invalid annotation: '*name*' property may only be used on values of pointer type + +## Remarks This warning indicates that a property for use on pointers was applied to a non-pointer type. For a list of annotation properties, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +Code analysis name: `BUFFER_SIZE_ON_NON_POINTER` + ## Example The following code generates this warning: diff --git a/docs/code-quality/c6516.md b/docs/code-quality/c6516.md index b345070573a..128900e3e6b 100644 --- a/docs/code-quality/c6516.md +++ b/docs/code-quality/c6516.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6516" -title: C6516 +title: "Warning C6516" +description: "Learn more about: Warning C6516" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6516"] +f1_keywords: ["C6516", "NO_PROPERTIES_ON_ATTRIBUTE", "__WARNING_NO_PROPERTIES_ON_ATTRIBUTE"] helpviewer_keywords: ["C6516"] -ms.assetid: 461078c8-18d4-49ca-80a2-a15736f429a0 --- -# C6516 +# Warning C6516 -> warning C6516: invalid annotation: no properties specified for \ attribute +> Invalid annotation: no properties specified for '*name*' attribute + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that either no property was specified in the attribute or the property that was specified is invalid; therefore, the attribute cannot be considered complete. +This warning indicates that either no property was specified in the attribute or the property that was specified is invalid; therefore, the attribute can't be considered complete. + +Code analysis name: `NO_PROPERTIES_ON_ATTRIBUTE` ## Example -The following code generates this warning because Deref=1 only specifies the level of indirection, but this information alone does not help the analysis tool: +The following code generates this warning because Deref=1 only specifies the level of indirection, but this information alone doesn't help the analysis tool: ```cpp // C diff --git a/docs/code-quality/c6517.md b/docs/code-quality/c6517.md index affb3811430..45b7ea115d8 100644 --- a/docs/code-quality/c6517.md +++ b/docs/code-quality/c6517.md @@ -1,24 +1,26 @@ --- -description: "Learn more about: C6517" -title: C6517 +title: "Warning C6517" +description: "Learn more about: Warning C6517" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6517"] +f1_keywords: ["C6517", "VALID_SIZE_ON_NON_READABLE_BUFFER", "__WARNING_VALID_SIZE_ON_NON_READABLE_BUFFER"] helpviewer_keywords: ["C6517"] -ms.assetid: 96822155-8b2a-4699-980f-744afff84ca8 --- -# C6517 +# Warning C6517 -> warning C6517: Invalid annotation: 'SAL_readableTo' property may not be specified on buffers that are not readable: '\_Param\_(1)'. +> Invalid annotation: 'SAL_readableTo' property may not be specified on buffers that are not readable: '*Parameter*'. + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that `SAL_readableTo` property does not have the required read access. You cannot use this property to annotate a parameter without providing read access. +This warning indicates that `SAL_readableTo` property doesn't have the required read access. You can't use this property to annotate a parameter without providing read access. + +Code analysis name: `VALID_SIZE_ON_NON_READABLE_BUFFER` ## Example -The following code generates this warning because read access is not granted on the buffer: +The following code generates this warning because read access isn't granted on the buffer: ```cpp #include diff --git a/docs/code-quality/c6518.md b/docs/code-quality/c6518.md index dfab23db1cc..de6c364ac96 100644 --- a/docs/code-quality/c6518.md +++ b/docs/code-quality/c6518.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6518" -title: C6518 +title: "Warning C6518" +description: "Learn more about: Warning C6518" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6518"] +f1_keywords: ["C6518", "WRITABLE_SIZE_ON_NON_WRITABLE_BUFFER", "__WARNING_WRITABLE_SIZE_ON_NON_WRITABLE_BUFFER"] helpviewer_keywords: ["C6518"] -ms.assetid: c391a75b-9f16-43a5-a7cd-c5a233002850 --- -# C6518 +# Warning C6518 -> warning C6518: Invalid annotation: 'SAL_writableTo' property may not be specified as a precondition on buffers that are not writable: '\_Param\_(1)' +> Invalid annotation: 'SAL_writableTo' property may not be specified as a precondition on buffers that are not writable: '*Parameter*'. -This warning indicates that a conflict exists between a `SAL_writableTo` property value and a writable property. This ordinarily indicates that a writable property does not have write access to the parameter being annotated. +## Remarks + +This warning indicates that a conflict exists between a `SAL_writableTo` property value and a writable property. The warning ordinarily indicates that a writable property doesn't have write access to the parameter being annotated. + +Code analysis name: `WRITABLE_SIZE_ON_NON_WRITABLE_BUFFER` ## Example -The following code generates this warning because the `_Out_` annotation compiles to include a `SAL_writableTo` property, which does not allow write access: +The following code generates this warning because the `_Out_` annotation compiles to include a `SAL_writableTo` property, which doesn't allow write access: ```cpp #include diff --git a/docs/code-quality/c6522.md b/docs/code-quality/c6522.md index 0ef96ca6a45..b4d4d9f5bc2 100644 --- a/docs/code-quality/c6522.md +++ b/docs/code-quality/c6522.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: C6522" -title: C6522 +title: "Warning C6522" +description: "Learn more about: Warning C6522" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6522"] +f1_keywords: ["C6522", "INVALID_SIZE_STRING_TYPE", "__WARNING_INVALID_SIZE_STRING_TYPE"] helpviewer_keywords: ["C6522"] -ms.assetid: ac482f63-b27f-4807-968a-1c449033d2dd --- -# C6522 +# Warning C6522 -> warning C6522: invalid size specification: expression must be of integral type +> Invalid size specification: expression must be of integral type: annotation '*annotation*' on function '*function*' '*parameter*' + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). This warning indicates that an integral type was expected, but an incorrect data type was used. You can use annotation properties that accept the size of a parameter in terms of another parameter, but you must use correct data type. For a list of annotation properties, see [Using SAL Annotations to reduce code defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md). +Code analysis name: `INVALID_SIZE_STRING_TYPE` + ## Example The following code generates this warning: @@ -31,7 +33,7 @@ using namespace vc_attributes; void f ([Pre(ValidBytes="c")] char *pc, double c); ``` -To correct this warning, use `size_t` for the `ValidBytesParam` parameter data type, as shown in the following sample code: +To correct this warning, use `size_t` for the `ValidBytesParam` parameter data type, as shown in the following example code: ```cpp // C diff --git a/docs/code-quality/c6525.md b/docs/code-quality/c6525.md index 81d20ab9ce6..36a6e2cd5e0 100644 --- a/docs/code-quality/c6525.md +++ b/docs/code-quality/c6525.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6525" -title: C6525 +title: "Warning C6525" +description: "Learn more about: Warning C6525" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6525"] +f1_keywords: ["C6525", "INVALID_SIZE_STRING_UNREACHABLE_LOCATION", "__WARNING_INVALID_SIZE_STRING_UNREACHABLE_LOCATION"] helpviewer_keywords: ["C6525"] -ms.assetid: a7af4dc7-d5a4-455f-a414-0c389ffd9aa9 --- -# C6525 +# Warning C6525 -> warning C6525: invalid size specification: property value may not be valid +> Invalid size specification: property value may not be valid + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that the property value used to specify the size is not valid. This occurs if the size parameter is annotated using Valid=No. +This warning indicates that the property value used to specify the size isn't valid. The warning occurs if the size parameter is annotated using `Valid=No`. + +Code analysis name: `INVALID_SIZE_STRING_UNREACHABLE_LOCATION` ## Example diff --git a/docs/code-quality/c6527.md b/docs/code-quality/c6527.md index 5246109cda3..0df3ea2dd62 100644 --- a/docs/code-quality/c6527.md +++ b/docs/code-quality/c6527.md @@ -1,12 +1,10 @@ --- -description: "Learn more about: C6527" -title: C6527 +title: "Warning C6527" +description: "Learn more about: Warning C6527" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6527"] helpviewer_keywords: ["C6527"] -ms.assetid: 5ebb6279-0f75-4566-a5f3-a47834de9625 --- -# C6527 +# Warning C6527 -> warning C6527: Invalid annotation: NeedsRelease property may not be used on values of void type +> Invalid annotation: NeedsRelease property may not be used on values of void type diff --git a/docs/code-quality/c6530.md b/docs/code-quality/c6530.md index d203ff4e716..fcaaaee3b72 100644 --- a/docs/code-quality/c6530.md +++ b/docs/code-quality/c6530.md @@ -1,20 +1,22 @@ --- -description: "Learn more about: C6530" -title: C6530 +title: "Warning C6530" +description: "Learn more about: Warning C6530" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6530"] +f1_keywords: ["C6530", "UNRECOGNIZED_FORMAT_STRING_STYLE", "__WARNING_UNRECOGNIZED_FORMAT_STRING_STYLE"] helpviewer_keywords: ["C6530"] -ms.assetid: 60e9dc58-e0f1-4a34-8c75-efebaa6cadd2 --- -# C6530 +# Warning C6530 -> warning C6530: unrecognized format string style \ +> Unrecognized format string style '*name*' + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). -This warning indicates that the FormatString property is using a value other than scanf or printf. To correct this warning, review your code and use a valid value for the Style property. +This warning indicates that the `FormatString` property is using a value other than `scanf` or `printf`. To correct this warning, review your code and use a valid value for the `Style` property. + +Code analysis name: `UNRECOGNIZED_FORMAT_STRING_STYLE` ## Example diff --git a/docs/code-quality/c6540.md b/docs/code-quality/c6540.md index 97520807faf..65e63f09ada 100644 --- a/docs/code-quality/c6540.md +++ b/docs/code-quality/c6540.md @@ -1,12 +1,10 @@ --- -description: "Learn more about: C6540" -title: C6540 +title: "Warning C6540" +description: "Learn more about: Warning C6540" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6540"] helpviewer_keywords: ["C6540"] -ms.assetid: b047084c-9187-443e-8bcd-8f42064003f7 --- -# C6540 +# Warning C6540 -> warning C6540: The use of attribute annotations on this function will invalidate all of its existing **`__declspec`** annotations +> The use of attribute annotations on this function will invalidate all of its existing **`__declspec`** annotations diff --git a/docs/code-quality/c6551.md b/docs/code-quality/c6551.md index 944bafdfa34..6a4e0b3c4a9 100644 --- a/docs/code-quality/c6551.md +++ b/docs/code-quality/c6551.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C6551" -title: C6551 +title: "Warning C6551" +description: "Learn more about: Warning C6551" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6551"] helpviewer_keywords: ["C6551"] -ms.assetid: cfd02698-7ba7-4564-841d-208999b1561d --- -# C6551 +# Warning C6551 -> warning C6551: Invalid size specification: expression not parsable +> Invalid size specification: expression not parsable + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). diff --git a/docs/code-quality/c6552.md b/docs/code-quality/c6552.md index 57c0fdd9d65..ebdf48ef39d 100644 --- a/docs/code-quality/c6552.md +++ b/docs/code-quality/c6552.md @@ -1,15 +1,15 @@ --- -description: "Learn more about: C6552" -title: C6552 +title: "Warning C6552" +description: "Learn more about: Warning C6552" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6552"] helpviewer_keywords: ["C6552"] -ms.assetid: 6c6f17d8-4ddd-4fad-b81f-e32285e7afa8 --- -# C6552 +# Warning C6552 -> warning C6552: Invalid `Deref=` or `Notref=`: expression not parsable +> Invalid `Deref=` or `Notref=`: expression not parsable + +## Remarks > [!NOTE] > This warning occurs only in code that is using a deprecated version of the source-code annotation language (SAL). We recommend that you port your code to use the latest version of SAL. For more information, see [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md). diff --git a/docs/code-quality/c6701.md b/docs/code-quality/c6701.md index 47dc9ab7b60..35aa86ba49d 100644 --- a/docs/code-quality/c6701.md +++ b/docs/code-quality/c6701.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C6701" -title: C6701 +title: "Warning C6701" +description: "Learn more about: Warning C6701" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6701"] -helpviewer_keywords: ["C67901"] -ms.assetid: c48484e2-542c-4f7b-93ea-98c6367cb3d9 +helpviewer_keywords: ["C6701"] --- -# C6701 +# Warning C6701 -> warning C6701: The value is not a valid Yes/No/Maybe value: \ +> The value is not a valid Yes/No/Maybe value: '*string*' -This warning is reported when there is an error in the annotations. +## Remarks + +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6702.md b/docs/code-quality/c6702.md index 5fab2c898ca..ecb9a87a5dc 100644 --- a/docs/code-quality/c6702.md +++ b/docs/code-quality/c6702.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C6702" -title: C6702 +title: "Warning C6702" +description: "Learn more about: Warning C6702" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6702"] helpviewer_keywords: ["C6702"] -ms.assetid: 6d373843-4ab4-4a94-bb83-5fec9214c625 --- -# C6702 +# Warning C6702 -> warning C6702: The value is not a string value: \ +> The value is not a string value: '*string*' -This warning is reported when there is an error in the annotations. +## Remarks + +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6703.md b/docs/code-quality/c6703.md index d6d89be47fb..40f198dc2e5 100644 --- a/docs/code-quality/c6703.md +++ b/docs/code-quality/c6703.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C6703" -title: C6703 +title: "Warning C6703" +description: "Learn more about: Warning C6703" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6703"] helpviewer_keywords: ["C6703"] -ms.assetid: 8ec4f403-e63e-4930-8266-569c9cd263b4 --- -# C6703 +# Warning C6703 -> warning C6703: The value is not a number: \ +> The value is not a number: '*string*' -This warning is reported when there is an error in the annotations. +## Remarks + +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6704.md b/docs/code-quality/c6704.md index 2edd6f25ef3..5a68ddfee58 100644 --- a/docs/code-quality/c6704.md +++ b/docs/code-quality/c6704.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C6704" -title: C6704 +title: "Warning C6704" +description: "Learn more about: Warning C6704" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6704"] helpviewer_keywords: ["C6704"] -ms.assetid: fc25543d-746e-415e-b0a8-d5134461af41 --- -# C6704 +# Warning C6704 -> warning C6704: Unexpected Annotation Expression Error: \ [\] +> Unexpected Annotation Expression Error: '*annotation*' ['*why*'] -This warning is reported when there is an error in the annotations. +## Remarks + +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6705.md b/docs/code-quality/c6705.md index 0049e5d34bd..17a2222150d 100644 --- a/docs/code-quality/c6705.md +++ b/docs/code-quality/c6705.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C6705" -title: C6705 +title: "Warning C6705" +description: "Learn more about: Warning C6705" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6705"] helpviewer_keywords: ["C6705"] -ms.assetid: 5d81e7ac-0c51-4cca-aaa8-df1aa599f175 --- -# C6705 +# Warning C6705 -> warning C6705: Annotation error expected arguments for annotation \ found . +> Annotation error expected arguments for annotation '*parameter*' found . -This warning is reported when there is an error in the annotations. +## Remarks + +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6706.md b/docs/code-quality/c6706.md index fdd87f01317..7f430a9c48b 100644 --- a/docs/code-quality/c6706.md +++ b/docs/code-quality/c6706.md @@ -1,14 +1,14 @@ --- -description: "Learn more about: C6706" -title: C6706 +title: "Warning C6706" +description: "Learn more about: Warning C6706" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6706"] helpviewer_keywords: ["C6706"] -ms.assetid: 20f3fd01-4993-4f7f-bd3f-57706356cf1d --- -# C6706 +# Warning C6706 -> warning C6706: Unexpected Annotation Error for annotation \: \ +> Unexpected Annotation Error for annotation '*annotation*': '*why*' -This warning is reported when there is an error in the annotations. +## Remarks + +This warning is reported when there's an error in the annotations. diff --git a/docs/code-quality/c6707.md b/docs/code-quality/c6707.md index f60931a9412..24441240b1d 100644 --- a/docs/code-quality/c6707.md +++ b/docs/code-quality/c6707.md @@ -1,12 +1,10 @@ --- -description: "Learn more about: C6707" -title: C6707 +title: "Warning C6707" +description: "Learn more about: Warning C6707" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6707"] helpviewer_keywords: ["C6707"] -ms.assetid: a6610464-9bc5-4f24-b0a5-7fa29581874d --- -# C6707 +# Warning C6707 -> warning C6707: Unexpected Model Error: \ +> Unexpected Model Error: '*why*' diff --git a/docs/code-quality/c6993.md b/docs/code-quality/c6993.md index 07c46c2a9a6..a2b72c3ae86 100644 --- a/docs/code-quality/c6993.md +++ b/docs/code-quality/c6993.md @@ -1,13 +1,16 @@ --- -description: "Learn more about: C6993" -title: C6993 -ms.date: 11/04/2016 -ms.topic: reference +title: "Warning C6993" +description: "Learn more about: Warning C6993" +ms.date: 2/25/2025 f1_keywords: ["C6993"] -ms.assetid: 7ea93bc6-b934-4b6b-b71a-a56e765fb4cd +helpviewer_keywords: ["C6993"] --- -# C6993 +# Warning C6993 -> warning C6993: Code analysis ignores OpenMP constructs; analyzing single-threaded code +> Code analysis ignores OpenMP constructs; analyzing single-threaded code -This warning indicates that the Code Analyzer has encountered Open MP pragmas that it cannot analyze. +## Remarks + +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 321ce2ed49c..a7183235967 100644 --- a/docs/code-quality/c6995.md +++ b/docs/code-quality/c6995.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: C6995" -title: C6995 +title: "Warning C6995" +description: "Learn more about: Warning C6995" ms.date: 11/04/2016 -ms.topic: reference f1_keywords: ["C6995"] -ms.assetid: 1e82e3ad-99fe-4a35-87d5-359c74b9658e +helpviewer_keywords: ["C6995"] --- -# C6995 +# Warning C6995 -> warning C6995: Failed to save XML Log file +> Failed to save XML Log file -This warning indicates that the Code Analysis tool cannot create the defect log, which is the output of the code analysis. +## Remarks -This error might indicate a disk error or indicate that you do not have permission to create a file in the specified directory. +This warning indicates that the Code Analysis tool can't create the defect log, which is the output of the code analysis. + +This error might indicate a disk error or indicate that you don't have permission to create a file in the specified directory. diff --git a/docs/code-quality/c6997.md b/docs/code-quality/c6997.md index 01a768b5e20..693cd3ffb47 100644 --- a/docs/code-quality/c6997.md +++ b/docs/code-quality/c6997.md @@ -1,16 +1,19 @@ --- -description: "Learn more about: C6997" -title: C6997 +title: "Warning C6997" +description: "Learn more about: Warning C6997" ms.date: 11/04/2016 -ms.topic: reference -f1_keywords: ["C6997"] -ms.assetid: 48fd86a3-d57b-4ecb-979a-5d3a4186482e +f1_keywords: ["C6997", "IGNORED_ANNOTATIONS"] +helpviewer_keywords: ["C6997"] --- -# C6997 +# Warning C6997 -> warning C6997: Annotations at this location are meaningless and will be ignored. +> Annotations at this location are meaningless and will be ignored. -Annotations cannot be applied to `extern "C" {...}`. Apply the annotations to a specific object. +## Remarks + +Annotations can't be applied to `extern "C" {...}`. Apply the annotations to a specific object. + +Code analysis name: `IGNORED_ANNOTATIONS` ## See also diff --git a/docs/code-quality/clang-tidy.md b/docs/code-quality/clang-tidy.md index 004a9c4e973..3d731181ea9 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.topic: "conceptual" -f1_keywords: ["vs.codeanalysis.clangtidy"] +ms.date: 03/1/2022 +ms.topic: "concept-article" +f1_keywords: ["vs.codeanalysis.clangtidy","vs.codeanalysis.propertypages.ClangTidyToolPath","vs.codeanalysis.propertypages.AdditionalOptions","vs.codeanalysis.propertypages.MaxProcesses"] --- # 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,84 @@ 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. + +## Clang-Tidy Additional Options + +The **Clang-Tidy Additional Options** property lets you specify additional compiler arguments that are passed to Clang-Tidy using the `--extra-args` command-line option. These arguments can be used to control how Clang-Tidy parses your code, such as defining macros, include paths, or language standards. Enter arguments as a semi-colon separated list. For example: `-std=c++20;-DMY_DEFINE=1;-Ipath\to\include`. + +## Clang-Tidy Prepend Additional Options + +The **Clang-Tidy Prepend Additional Options** property lets you specify compiler arguments that are passed to Clang-Tidy using the `--extra-args-before` command-line option. These arguments are inserted before the default compiler arguments when Clang-Tidy parses your code. Enter arguments as a semi-colon separated list. For example: `-std=c++20;-DMY_DEFINE=1;`. + +## Max Number of Processes + +The **Max Number of Processes** property lets you specify how many processes Clang-Tidy can use to run analysis in parallel. By default, Clang-Tidy runs serially. Set this property to enable parallel execution and specify the number of parallel processes. Set it to `0` to use all available logical processors on your system. Increasing the number of processes can improve analysis speed on multi-core machines. + ## See also -- [Clang/LLVM support for MSBuild projects](https://devblogs.microsoft.com/cppblog/clang-llvm-support-for-msbuild-projects/) -- [Clang/LLVM support for CMake projects](https://devblogs.microsoft.com/cppblog/visual-studio-cmake-support-clang-llvm-cmake-3-14-vcpkg-and-performance-improvements/) +[Clang/LLVM support for MSBuild projects](https://devblogs.microsoft.com/cppblog/clang-llvm-support-for-msbuild-projects/)\ +[Clang/LLVM support for CMake projects](https://devblogs.microsoft.com/cppblog/visual-studio-cmake-support-clang-llvm-cmake-3-14-vcpkg-and-performance-improvements/) ::: moniker-end diff --git a/docs/code-quality/code-analysis-for-c-cpp-overview.md b/docs/code-quality/code-analysis-for-c-cpp-overview.md index e9ef85e6775..fffa6d3ad8b 100644 --- a/docs/code-quality/code-analysis-for-c-cpp-overview.md +++ b/docs/code-quality/code-analysis-for-c-cpp-overview.md @@ -2,7 +2,7 @@ description: "Learn more about: Code analysis for C/C++ overview" title: Code analysis for C/C++ overview ms.date: 04/28/2018 -ms.topic: conceptual +ms.topic: concept-article helpviewer_keywords: - "annotations, code analysis" - "build integration, code analysis" @@ -20,7 +20,7 @@ ms.assetid: 81f0c9e8-f471-4de5-aac4-99db336a8809 --- # Code analysis for C/C++ overview -The C/C++ Code Analysis tool provides information about possible defects in your C/C++ source code. Common coding errors reported by the tool include buffer overruns, uninitialized memory, null pointer dereferences, and memory and resource leaks. The tool can also run checks against the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md). +The Microsoft C++ Code Analysis tool provides information about possible defects in your C/C++ source code. Common coding errors reported by the tool include buffer overruns, uninitialized memory, null pointer dereferences, and memory and resource leaks. The tool can also run checks against the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines). ## IDE (integrated development environment) integration diff --git a/docs/code-quality/code-analysis-for-cpp-corecheck.md b/docs/code-quality/code-analysis-for-cpp-corecheck.md index dc5f05ad2db..c57ae64393f 100644 --- a/docs/code-quality/code-analysis-for-cpp-corecheck.md +++ b/docs/code-quality/code-analysis-for-cpp-corecheck.md @@ -1,11 +1,10 @@ --- +title: "C++ Core Guidelines checker reference" description: "Learn more about: C++ Core Guidelines checker reference" -title: C++ Core Guidelines checker reference ms.date: 03/22/2018 ms.topic: reference helpviewer_keywords: - "code analysis, C++ core check" -ms.assetid: f1429463-136e-41ed-8a75-a8dbf0b4fd89 --- # C++ Core Guidelines checker reference @@ -16,251 +15,251 @@ This section lists C++ Core Guidelines Checker warnings. For information about C ## OWNER_POINTER Group -[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ -Return a scoped object instead of a heap-allocated if it has a move constructor. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). +[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ +Return a scoped object instead of a heap-allocated if it has a move constructor. See [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). [C26403 RESET_OR_DELETE_OWNER](C26403.md)\ -Reset or explicitly delete an owner\ pointer '*variable*'. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). +Reset or explicitly delete an owner\ pointer '*variable*'. See [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). [C26404 DONT_DELETE_INVALID](C26404.md)\ -Do not delete an owner\ that may be in invalid state. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). +Do not delete an owner\ that may be in invalid state. See [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). [C26405 DONT_ASSIGN_TO_VALID](C26405.md)\ -Do not assign to an owner\ that may be in valid state. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). +Do not assign to an owner\ that may be in valid state. See [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). [C26406 DONT_ASSIGN_RAW_TO_OWNER](C26406.md)\ -Do not assign a raw pointer to an owner\. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). +Do not assign a raw pointer to an owner\. See [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). [C26407 DONT_HEAP_ALLOCATE_UNNECESSARILY](C26407.md)\ -Prefer scoped objects, don't heap-allocate unnecessarily. See [C++ Core Guidelines R.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-scoped). +Prefer scoped objects, don't heap-allocate unnecessarily. See [C++ Core Guidelines R.5](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-scoped). [C26429 USE_NOTNULL](C26429.md)\ -Symbol '*symbol*' is never tested for nullness, it can be marked as not_null. See [C++ Core Guidelines F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value). +Symbol '*symbol*' is never tested for nullness, it can be marked as not_null. See [C++ Core Guidelines F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr). [C26430 TEST_ON_ALL_PATHS](C26430.md)\ -Symbol '*symbol*' is not tested for nullness on all paths. See [C++ Core Guidelines F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value). +Symbol '*symbol*' is not tested for nullness on all paths. See [C++ Core Guidelines F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr). [C26431 DONT_TEST_NOTNULL](C26431.md)\ -The type of expression '*expr*' is already gsl::not_null. Do not test it for nullness. See [C++ Core Guidelines F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value). +The type of expression '*expr*' is already gsl::not_null. Do not test it for nullness. See [C++ Core Guidelines F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr). ## RAW_POINTER Group [C26400 NO_RAW_POINTER_ASSIGNMENT](c26400.md)\ -Do not assign the result of an allocation or a function call with an owner\ return value to a raw pointer; use owner\ instead. See [C++ Core Guidelines I.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-raw). +Do not assign the result of an allocation or a function call with an owner\ return value to a raw pointer; use owner\ instead. See [C++ Core Guidelines I.11](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-raw). [C26401 DONT_DELETE_NON_OWNER](c26401.md)\ -Do not delete a raw pointer that is not an owner\. See [C++ Core Guidelines I.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Ri-raw). +Do not delete a raw pointer that is not an owner\. See [C++ Core Guidelines I.11](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-raw). -[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ -Return a scoped object instead of a heap-allocated if it has a move constructor. See [C++ Core Guidelines R.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-ptr). +[C26402 DONT_HEAP_ALLOCATE_MOVABLE_RESULT](C26402.md)\ +Return a scoped object instead of a heap-allocated if it has a move constructor. See [C++ Core Guidelines R.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-ptr). [C26408 NO_MALLOC_FREE](C26408.md)\ -Avoid malloc() and free(), prefer the nothrow version of new with delete. See [C++ Core Guidelines R.10](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-mallocfree). +Avoid malloc() and free(), prefer the nothrow version of new with delete. See [C++ Core Guidelines R.10](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-mallocfree). [C26409 NO_NEW_DELETE](C26409.md)\ -Avoid calling new and delete explicitly, use std::make_unique\ instead. See [C++ Core Guidelines R.11](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-newdelete). +Avoid calling new and delete explicitly, use std::make_unique\ instead. See [C++ Core Guidelines R.11](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-newdelete). [C26429 USE_NOTNULL](C26429.md)\ -Symbol '*symbol*' is never tested for nullness, it can be marked as not_null. See [C++ Core Guidelines F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value). +Symbol '*symbol*' is never tested for nullness, it can be marked as not_null. See [C++ Core Guidelines F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr). [C26430 TEST_ON_ALL_PATHS](C26430.md)\ -Symbol '*symbol*' is not tested for nullness on all paths. See [C++ Core Guidelines F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value). +Symbol '*symbol*' is not tested for nullness on all paths. See [C++ Core Guidelines F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr). [C26431 DONT_TEST_NOTNULL](C26431.md)\ -The type of expression '*expr*' is already gsl::not_null. Do not test it for nullness. See [C++ Core Guidelines F.23](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f23-use-a-not_nullt-to-indicate-that-null-is-not-a-valid-value). +The type of expression '*expr*' is already gsl::not_null. Do not test it for nullness. See [C++ Core Guidelines F.23](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-nullptr). [C26481 NO_POINTER_ARITHMETIC](C26481.md)\ -Don't use pointer arithmetic. Use span instead. See [C++ Core Guidelines Bounds.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds). +Don't use pointer arithmetic. Use span instead. See [C++ Core Guidelines Bounds.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-arithmetic). [C26485 NO_ARRAY_TO_POINTER_DECAY](C26485.md)\ -Expression '*expr*': No array to pointer decay. See [C++ Core Guidelines Bounds.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds). +Expression '*expr*': No array to pointer decay. See [C++ Core Guidelines Bounds.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-decay). ## UNIQUE_POINTER Group [C26410 NO_REF_TO_CONST_UNIQUE_PTR](C26410.md)\ -The parameter '*parameter*' is a reference to `const` unique pointer, use const T* or const T& instead. See [C++ Core Guidelines R.32](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-uniqueptrparam). +The parameter '*parameter*' is a reference to `const` unique pointer, use const T* or const T& instead. See [C++ Core Guidelines R.32](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-uniqueptrparam). [C26411 NO_REF_TO_UNIQUE_PTR](C26411.md)\ -The parameter '*parameter*' is a reference to unique pointer and it is never reassigned or reset, use T* or T& instead. See [C++ Core Guidelines R.33](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-reseat). +The parameter '*parameter*' is a reference to unique pointer and it is never reassigned or reset, use T* or T& instead. See [C++ Core Guidelines R.33](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-reseat). [C26414 RESET_LOCAL_SMART_PTR](C26414.md)\ -Move, copy, reassign, or reset a local smart pointer '*symbol*'. See [C++ Core Guidelines R.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-scoped). +Move, copy, reassign, or reset a local smart pointer '*symbol*'. See [C++ Core Guidelines R.5](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-scoped). [C26415 SMART_PTR_NOT_NEEDED](C26415.md)\ -Smart pointer parameter '*symbol*' is used only to access contained pointer. Use T* or T& instead. See [C++ Core Guidelines R.30](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-smartptrparam). +Smart pointer parameter '*symbol*' is used only to access contained pointer. Use T* or T& instead. See [C++ Core Guidelines R.30](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-smartptrparam). ## SHARED_POINTER Group [C26414 RESET_LOCAL_SMART_PTR](C26414.md)\ -Move, copy, reassign, or reset a local smart pointer '*symbol*'. See [C++ Core Guidelines R.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-scoped). +Move, copy, reassign, or reset a local smart pointer '*symbol*'. See [C++ Core Guidelines R.5](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-scoped). [C26415 SMART_PTR_NOT_NEEDED](C26415.md)\ -Smart pointer parameter '*symbol*' is used only to access contained pointer. Use T* or T& instead. See [C++ Core Guidelines R.30](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-smartptrparam). +Smart pointer parameter '*symbol*' is used only to access contained pointer. Use T* or T& instead. See [C++ Core Guidelines R.30](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-smartptrparam). [C26416 NO_RVALUE_REF_SHARED_PTR](C26416.md)\ -Shared pointer parameter '*symbol*' is passed by rvalue reference. Pass by value instead. See [C++ Core Guidelines R.34](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-sharedptrparam-owner). +Shared pointer parameter '*symbol*' is passed by rvalue reference. Pass by value instead. See [C++ Core Guidelines R.34](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-sharedptrparam-owner). [C26417 NO_LVALUE_REF_SHARED_PTR](C26417.md)\ -Shared pointer parameter '*symbol*' is passed by reference and not reset or reassigned. Use T* or T& instead. See [C++ Core Guidelines R.35](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-sharedptrparam). +Shared pointer parameter '*symbol*' is passed by reference and not reset or reassigned. Use T* or T& instead. See [C++ Core Guidelines R.35](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-sharedptrparam). [C26418 NO_VALUE_OR_CONST_REF_SHARED_PTR](C26418.md)\ -Shared pointer parameter '*symbol*' is not copied or moved. Use T* or T& instead. See [C++ Core Guidelines R.36](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rr-sharedptrparam-const). +Shared pointer parameter '*symbol*' is not copied or moved. Use T* or T& instead. See [C++ Core Guidelines R.36](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rr-sharedptrparam-const). ## DECLARATION Group [C26426 NO_GLOBAL_INIT_CALLS](C26426.md)\ -Global initializer calls a non-constexpr function '*symbol*'. See [C++ Core Guidelines I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects). +Global initializer calls a non-constexpr function '*symbol*'. See [C++ Core Guidelines I.22](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-global-init). [C26427 NO_GLOBAL_INIT_EXTERNS](C26427.md)\ -Global initializer accesses extern object '*symbol*'. See [C++ Core Guidelines I.22](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i22-avoid-complex-initialization-of-global-objects). +Global initializer accesses extern object '*symbol*'. See [C++ Core Guidelines I.22](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Ri-global-init). [C26444 NO_UNNAMED_RAII_OBJECTS](c26444.md)\ -Avoid unnamed objects with custom construction and destruction. See [ES.84: Don't (try to) declare a local variable with no name](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md). +Avoid unnamed objects with custom construction and destruction. See [ES.84: Don't (try to) declare a local variable with no name](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-noname). ## CLASS Group [C26432 DEFINE_OR_DELETE_SPECIAL_OPS](C26432.md)\ -If you define or delete any default operation in the type '*symbol*', define or delete them all. See [C++ Core Guidelines C.21](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c21-if-you-define-or-delete-any-default-operation-define-or-delete-them-all). +If you define or delete any default operation in the type '*symbol*', define or delete them all. See [C++ Core Guidelines C.21](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rc-five). [C26433 OVERRIDE_EXPLICITLY](c26433.md)\ -Function '*symbol*' should be marked with 'override'. See [C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c128-virtual-functions-should-specify-exactly-one-of-virtual-override-or-final). +Function '*symbol*' should be marked with 'override'. See [C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override). [C26434 DONT_HIDE_METHODS](C26434.md)\ -Function '*symbol_1*' hides a non-virtual function '*symbol_2*'. See [C++ Core Guidelines C.128](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c128-virtual-functions-should-specify-exactly-one-of-virtual-override-or-final). +Function '*symbol_1*' hides a non-virtual function '*symbol_2*'. See [C++ Core Guidelines C.128](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override). [C26435 SINGLE_VIRTUAL_SPECIFICATION](c26435.md)\ -Function '*symbol*' should specify exactly one of 'virtual', 'override', or 'final'. See [C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md). +Function '*symbol*' should specify exactly one of 'virtual', 'override', or 'final'. See [C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override). [C26436 NEED_VIRTUAL_DTOR](C26436.md)\ -The type '*symbol*' with a virtual function needs either public virtual or protected non-virtual destructor. See [C++ Core Guidelines C.35](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c35-a-base-class-destructor-should-be-either-public-and-virtual-or-protected-and-nonvirtual). +The type '*symbol*' with a virtual function needs either public virtual or protected non-virtual destructor. See [C++ Core Guidelines C.35](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rc-dtor-virtual). [C26443 NO_EXPLICIT_DTOR_OVERRIDE](c26443.md)\ -Overriding destructor should not use explicit 'override' or 'virtual' specifiers. See [C.128: Virtual functions should specify exactly one of virtual, override, or final](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md). +Overriding destructor should not use explicit 'override' or 'virtual' specifiers. See [C.128: Virtual functions should specify exactly one of virtual, override, or final](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rh-override). ## STYLE Group [C26438 NO_GOTO](C26438.md)\ -Avoid `goto`. See [C++ Core Guidelines ES.76](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es76-avoid-goto). +Avoid `goto`. See [C++ Core Guidelines ES.76](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-goto). ## FUNCTION Group [C26439 SPECIAL_NOEXCEPT](C26439.md)\ -This kind of function may not throw. Declare it **`noexcept`**. See [C++ Core Guidelines F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept). +This kind of function may not throw. Declare it **`noexcept`**. See [C++ Core Guidelines F.6](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-noexcept). [C26440 DECLARE_NOEXCEPT](C26440.md)\ -Function '*symbol*' can be declared **`noexcept`**. See [C++ Core Guidelines F.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept). +Function '*symbol*' can be declared **`noexcept`**. See [C++ Core Guidelines F.6](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-noexcept). [C26447 DONT_THROW_IN_NOEXCEPT](c26447.md)\ The function is declared **`noexcept`** but calls a function which may throw exceptions. -See [C++ Core Guidelines: F.6: If your function may not throw, declare it noexcept](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f6-if-your-function-may-not-throw-declare-it-noexcept). +See [C++ Core Guidelines: F.6: If your function may not throw, declare it noexcept](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-noexcept). ## CONCURRENCY Group [C26441 NO_UNNAMED_GUARDS](C26441.md)\ -Guard objects must be named. See [C++ Core Guidelines cp.44](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#cp44-remember-to-name-your-lock_guards-and-unique_locks). +Guard objects must be named. See [C++ Core Guidelines cp.44](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconc-name). ## CONST Group [C26460 USE_CONST_REFERENCE_ARGUMENTS](c26460.md)\ -The reference argument '*argument*' for function '*function*' can be marked as `const`. See [C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). +The reference argument '*argument*' for function '*function*' can be marked as `const`. See [C++ Core Guidelines con.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-ref). [C26461 USE_CONST_POINTER_ARGUMENTS](c26461.md):\ -The pointer argument '*argument*' for function '*function*' can be marked as a pointer to `const`. See [C++ Core Guidelines con.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-ref). +The pointer argument '*argument*' for function '*function*' can be marked as a pointer to `const`. See [C++ Core Guidelines con.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-ref). [C26462 USE_CONST_POINTER_FOR_VARIABLE](c26462.md)\ -The value pointed to by '*variable*' is assigned only once, mark it as a pointer to `const`. See [C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +The value pointed to by '*variable*' is assigned only once, mark it as a pointer to `const`. See [C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). [C26463 USE_CONST_FOR_ELEMENTS](c26463.md)\ -The elements of array '*array*' are assigned only once, mark elements `const`. See [C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +The elements of array '*array*' are assigned only once, mark elements `const`. See [C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). [C26464 USE_CONST_POINTER_FOR_ELEMENTS](c26464.md)\ -The values pointed to by elements of array '*array*' are assigned only once, mark elements as pointer to `const`. See [C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +The values pointed to by elements of array '*array*' are assigned only once, mark elements as pointer to `const`. See [C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). [C26496 USE_CONST_FOR_VARIABLE](c26496.md)\ -The variable '*variable*' is assigned only once, mark it as `const`. See [C++ Core Guidelines con.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con4-use-const-to-define-objects-with-values-that-do-not-change-after-construction). +The variable '*variable*' is assigned only once, mark it as `const`. See [C++ Core Guidelines con.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-const). [C26497 USE_CONSTEXPR_FOR_FUNCTION](c26497.md)\ -This function *function* could be marked `constexpr` if compile-time evaluation is desired. See [C++ Core Guidelines F.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rf-constexpr). +This function *function* could be marked `constexpr` if compile-time evaluation is desired. See [C++ Core Guidelines F.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rf-constexpr). [C26498 USE_CONSTEXPR_FOR_FUNCTIONCALL](c26498.md)\ -This function call *function* can use `constexpr` if compile-time evaluation is desired. See [C++ Core Guidelines con.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Rconst-constexpr). +This function call *function* can use `constexpr` if compile-time evaluation is desired. See [C++ Core Guidelines con.5](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Rconst-constexpr). ## TYPE Group [C26437 DONT_SLICE](C26437.md)\ -Do not slice. See [C++ Core Guidelines ES.63](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es63-dont-slice). +Do not slice. See [C++ Core Guidelines ES.63](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-slice). [C26465 NO_CONST_CAST_UNNECESSARY](c26465.md)\ -Don't use `const_cast` to cast away `const`. `const_cast` is not required; constness or volatility is not being removed by this conversion. See [C++ Core Guidelines Type.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-constcast). +Don't use `const_cast` to cast away `const`. `const_cast` is not required; constness or volatility is not being removed by this conversion. See [C++ Core Guidelines Type.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-constcast). [C26466 NO_STATIC_DOWNCAST_POLYMORPHIC](c26466.md)\ -Don't use `static_cast` downcasts. A cast from a polymorphic type should use dynamic_cast. See [C++ Core Guidelines Type.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-downcast). +Don't use `static_cast` downcasts. A cast from a polymorphic type should use dynamic_cast. See [C++ Core Guidelines Type.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-downcast). [C26471 NO_REINTERPRET_CAST_FROM_VOID_PTR](c26471.md)\ -Don't use `reinterpret_cast`. A cast from void* can use `static_cast`. See [C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast). +Don't use `reinterpret_cast`. A cast from void* can use `static_cast`. See [C++ Core Guidelines Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-reinterpretcast). [C26472 NO_CASTS_FOR_ARITHMETIC_CONVERSION](C26472.md)\ -Don't use a `static_cast` for arithmetic conversions. Use brace initialization, gsl::narrow_cast, or gsl::narrow. See [C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast). +Don't use a `static_cast` for arithmetic conversions. Use brace initialization, gsl::narrow_cast, or gsl::narrow. See [C++ Core Guidelines Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-arithmeticcast). [C26473 NO_IDENTITY_CAST](C26473.md)\ -Don't cast between pointer types where the source type and the target type are the same. See [C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast). +Don't cast between pointer types where the source type and the target type are the same. See [C++ Core Guidelines Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-identitycast). [C26474 NO_IMPLICIT_CAST](C26474.md)\ -Don't cast between pointer types when the conversion could be implicit. See [C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Pro-type-reinterpretcast). +Don't cast between pointer types when the conversion could be implicit. See [C++ Core Guidelines Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-implicitpointercast). [C26475 NO_FUNCTION_STYLE_CASTS](C26475.md)\ -Do not use function style C-casts. See [C++ Core Guidelines ES.49](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es49-if-you-must-use-a-cast-use-a-named-cast). +Do not use function style C-casts. See [C++ Core Guidelines ES.49](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-casts-named). [C26490 NO_REINTERPRET_CAST](c26490.md)\ -Don't use `reinterpret_cast`. See [C++ Core Guidelines Type.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +Don't use `reinterpret_cast`. See [C++ Core Guidelines Type.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-reinterpretcast). -[C26491 NO_STATIC_DOWNCAST](c26490.md)\ -Don't use `static_cast` downcasts. See [C++ Core Guidelines Type.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +[C26491 NO_STATIC_DOWNCAST](c26491.md)\ +Don't use `static_cast` downcasts. See [C++ Core Guidelines Type.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-downcast). [C26492 NO_CONST_CAST](c26492.md)\ -Don't use `const_cast` to cast away `const`. See [C++ Core Guidelines Type.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +Don't use `const_cast` to cast away `const`. See [C++ Core Guidelines Type.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-constcast). [C26493 NO_CSTYLE_CAST](c26493.md)\ -Don't use C-style casts. See [C++ Core Guidelines Type.4](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +Don't use C-style casts. See [C++ Core Guidelines Type.4](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-cstylecast). [C26494 VAR_USE_BEFORE_INIT](c26494.md)\ -Variable '*variable*' is uninitialized. Always initialize an object. See [C++ Core Guidelines Type.5](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +Variable '*variable*' is uninitialized. Always initialize an object. See [C++ Core Guidelines Type.5](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-init). [C26495 MEMBER_UNINIT](c26495.md)\ -Variable '*variable*' is uninitialized. Always initialize a member variable. See [C++ Core Guidelines Type.6](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-type). +Variable '*variable*' is uninitialized. Always initialize a member variable. See [C++ Core Guidelines Type.6](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-type-memberinit). ## BOUNDS Group [C26446 USE_GSL_AT](c26446.md)\ -Prefer to use `gsl::at()` instead of unchecked subscript operator. See [C++ Core Guidelines: Bounds.4: Don't use standard-library functions and types that are not bounds-checked](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#probounds-bounds-safety-profile). +Prefer to use `gsl::at()` instead of unchecked subscript operator. See [C++ Core Guidelines: Bounds.4: Don't use standard-library functions and types that are not bounds-checked](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-stdlib). [C26481 NO_POINTER_ARITHMETIC](C26481.md)\ -Don't use pointer arithmetic. Use span instead. See [C++ Core Guidelines Bounds.1](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) +Don't use pointer arithmetic. Use span instead. See [C++ Core Guidelines Bounds.1](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-arithmetic) [C26482 NO_DYNAMIC_ARRAY_INDEXING](c26482.md)\ -Only index into arrays using constant expressions. See [C++ Core Guidelines Bounds.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) +Only index into arrays using constant expressions. See [C++ Core Guidelines Bounds.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-arrayindex) [C26483 STATIC_INDEX_OUT_OF_RANGE](c26483.md)\ -Value *value* is outside the bounds (0, *bound*) of variable '*variable*'. Only index into arrays using constant expressions that are within bounds of the array. See [C++ Core Guidelines Bounds.2](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) +Value *value* is outside the bounds (0, *bound*) of variable '*variable*'. Only index into arrays using constant expressions that are within bounds of the array. See [C++ Core Guidelines Bounds.2](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-arrayindex) [C26485 NO_ARRAY_TO_POINTER_DECAY](C26485.md)\ -Expression '*expr*': No array to pointer decay. See [C++ Core Guidelines Bounds.3](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-bounds) +Expression '*expr*': No array to pointer decay. See [C++ Core Guidelines Bounds.3](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-decay) ## GSL Group [C26445 NO_SPAN_REF](c26445.md)\ A reference to `gsl::span` or `std::string_view` may be an indication of a lifetime issue. -See [C++ Core Guidelines GSL.view: Views](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#gslview-views) +See [C++ Core Guidelines GSL.view: Views](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-views) [C26446 USE_GSL_AT](c26446.md)\ -Prefer to use `gsl::at()` instead of unchecked subscript operator. See [C++ Core Guidelines: Bounds.4: Don't use standard-library functions and types that are not bounds-checked](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#probounds-bounds-safety-profile). +Prefer to use `gsl::at()` instead of unchecked subscript operator. See [C++ Core Guidelines: Bounds.4: Don't use standard-library functions and types that are not bounds-checked](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Pro-bounds-stdlib). [C26448 USE_GSL_FINALLY](c26448.md)\ -Consider using `gsl::finally` if final action is intended. See [C++ Core Guidelines: GSL.util: Utilities](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#SS-utilities). +Consider using `gsl::finally` if final action is intended. See [C++ Core Guidelines: GSL.util: Utilities](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#SS-utilities). [C26449 NO_SPAN_FROM_TEMPORARY](c26449.md)\ `gsl::span` or `std::string_view` created from a temporary will be invalid when the temporary is invalidated. See -[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#SS-views). ## Deprecated Warnings diff --git a/docs/code-quality/how-to-set-code-analysis-properties-for-c-cpp-projects.md b/docs/code-quality/how-to-set-code-analysis-properties-for-c-cpp-projects.md index cd25a57d26d..d4b1e95e891 100644 --- a/docs/code-quality/how-to-set-code-analysis-properties-for-c-cpp-projects.md +++ b/docs/code-quality/how-to-set-code-analysis-properties-for-c-cpp-projects.md @@ -2,7 +2,6 @@ description: "Learn more about: How to: Set Code Analysis Properties for C/C++ Projects" title: "How to: Set Code Analysis Properties for C/C++ Projects" ms.date: 11/04/2016 -ms.topic: "conceptual" f1_keywords: - "vs.codeanalysis.propertypages.native" - "VC.Project.VCCLCompilerTool.EnablePrefast" 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 68220286ec9..16272c8e974 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 @@ -2,7 +2,6 @@ description: "Learn more about how to specify additional code information by using _Analysis_assume_." title: "Use _Analysis_assume_ for code analysis hints" ms.date: 12/16/2020 -ms.topic: "conceptual" f1_keywords: - "_Analysis_assume_" helpviewer_keywords: @@ -10,7 +9,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 +26,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 7ae4caa6680..337b3f5afa4 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/intrinsic-functions.md b/docs/code-quality/intrinsic-functions.md index 7b9d3a334cb..7a86f4a05c3 100644 --- a/docs/code-quality/intrinsic-functions.md +++ b/docs/code-quality/intrinsic-functions.md @@ -2,7 +2,7 @@ description: "Learn more about: Intrinsic Functions" title: Intrinsic Functions ms.date: 11/04/2016 -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: - "_String_length_" - "_Param_" 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 d5924b87e71..1a8f22e7f2c 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 @@ -2,7 +2,7 @@ title: "Quickstart: Code analysis for C/C++" description: "Run static analysis on C++ code in Visual Studio to detect common coding problems and defects." ms.date: 04/08/2020 -ms.topic: "conceptual" +ms.topic: "quickstart" helpviewer_keywords: - "C/C++ code analysis" - "code analysis, C/C++" @@ -17,9 +17,9 @@ You can improve the quality of your application by running code analysis regular 1. Optionally, in the **Configuration** and **Platform** lists, choose the build configuration and target platform. -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. To run code analysis every time the project is built using the selected configuration, select **Configuration Properties** > **Code Analysis**, then 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 @@ -27,25 +27,25 @@ Visual Studio includes these standard sets of rules for native code: | Rule Set | Description | |--|--| -| **C++ Core Check Arithmetic Rules** | These rules enforce checks related to [arithmetic operations from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es-expressions-and-statements). | -| **C++ Core Check Bounds Rules** | These rules enforce the [Bounds profile of the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#probounds-bounds-safety-profile). | -| **C++ Core Check Class Rules** | These rules enforce checks related to [classes from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c-classes-and-class-hierarchies). | -| **C++ Core Check Concurrency Rules** | These rules enforce checks related to [concurrency from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#cpcon-concurrency). | -| **C++ Core Check Const Rules** | These rules enforce [const-related checks from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con-constants-and-immutability). | -| **C++ Core Check Declaration Rules** | These rules enforce checks related to [declarations from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#i-interfaces). | -| **C++ Core Check Enum Rules** | These rules enforce [enum-related checks from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-enum). | +| **C++ Core Check Arithmetic Rules** | These rules enforce checks related to [arithmetic operations from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es-expressions-and-statements). | +| **C++ Core Check Bounds Rules** | These rules enforce the [Bounds profile of the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#probounds-bounds-safety-profile). | +| **C++ Core Check Class Rules** | These rules enforce checks related to [classes from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c-classes-and-class-hierarchies). | +| **C++ Core Check Concurrency Rules** | These rules enforce checks related to [concurrency from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#cpcon-concurrency). | +| **C++ Core Check Const Rules** | These rules enforce [const-related checks from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#con-constants-and-immutability). | +| **C++ Core Check Declaration Rules** | These rules enforce checks related to [declarations from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#i-interfaces). | +| **C++ Core Check Enum Rules** | These rules enforce [enum-related checks from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-enum). | | **C++ Core Check Experimental Rules** | These rules collect some experimental checks. Eventually, we expect these checks to be moved to other rulesets or removed completely. | -| **C++ Core Check Function Rules** | These rules enforce checks related to [functions from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#f-functions). | -| **C++ Core Check GSL Rules** | These rules enforce checks related to the [Guidelines Support Library from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-gsl). | -| **C++ Core Check Lifetime Rules** | These rules enforce the [Lifetime profile of the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prolifetime-lifetime-safety-profile). | -| **C++ Core Check Owner Pointer Rules** | These rules enforce resource-management checks related to [`owner` from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). | -| **C++ Core Check Raw Pointer Rules** | These rules enforce resource-management checks related to [raw pointers from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). | -| **C++ Core Check Rules** | These rules enforce a subset of the checks from the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c-core-guidelines). Use this ruleset to include all of the C++ Core Check rules except the Enum and Experimental rulesets. | -| **C++ Core Check Shared Pointer Rules** | These rules enforce resource-management checks related to [types with shared pointer semantics from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). | -| **C++ Core Check STL Rules** | These rules enforce checks related to the [C++ Standard Template Library (STL) from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-stdlib). | -| **C++ Core Check Style Rules** | These rules enforce checks related to use of [expressions and statements from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#es-expressions-and-statements). | -| **C++ Core Check Type Rules** | These rules enforce the [Type profile of the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile). | -| **C++ Core Check Unique Pointer Rules** | These rules enforce resource-management checks related to types with [unique pointer semantics from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management). | +| **C++ Core Check Function Rules** | These rules enforce checks related to [functions from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#f-functions). | +| **C++ Core Check GSL Rules** | These rules enforce checks related to the [Guidelines Support Library from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl). | +| **C++ Core Check Lifetime Rules** | These rules enforce the [Lifetime profile of the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#prolifetime-lifetime-safety-profile). | +| **C++ Core Check Owner Pointer Rules** | These rules enforce resource-management checks related to [`owner` from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r-resource-management). | +| **C++ Core Check Raw Pointer Rules** | These rules enforce resource-management checks related to [raw pointers from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r-resource-management). | +| **C++ Core Check Rules** | These rules enforce a subset of the checks from the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c-core-guidelines). Use this ruleset to include all of the C++ Core Check rules except the Enum and Experimental rulesets. | +| **C++ Core Check Shared Pointer Rules** | These rules enforce resource-management checks related to [types with shared pointer semantics from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r-resource-management). | +| **C++ Core Check STL Rules** | These rules enforce checks related to the [C++ Standard Library from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-stdlib). | +| **C++ Core Check Style Rules** | These rules enforce checks related to use of [expressions and statements from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#es-expressions-and-statements). | +| **C++ Core Check Type Rules** | These rules enforce the [Type profile of the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#prosafety-type-safety-profile). | +| **C++ Core Check Unique Pointer Rules** | These rules enforce resource-management checks related to types with [unique pointer semantics from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r-resource-management). | | **Concurrency Check Rules** | These rules enforce a set of Win32 concurrency pattern checks in C++. | | **Concurrency Rules** | Adds concurrency rules from C++ Core Guidelines to **Concurrency Check Rules**. | | **Microsoft Native Minimum Rules** | These rules focus on the most critical problems in your native code, including potential security holes and application crashes. We recommend you include this rule set in any custom rule set you create for your native projects. | @@ -57,10 +57,10 @@ Visual Studio includes these standard sets of rules for managed code: |--|--| | **Microsoft Basic Correctness Rules** | These rules focus on logic errors and common mistakes made in the usage of framework APIs. Include this rule set to expand on the list of warnings reported by the minimum recommended rules. | | **Microsoft Basic Design Guideline Rules** | These rules focus on enforcing best practices to make your code easy to understand and use. Include this rule set if your project includes library code or if you want to enforce best practices for easily maintainable code. | -| **Microsoft Extended Correctness Rules** | These rules expand on the basic correctness rules to maximize the reported logic and framework usage errors. Extra emphasis is placed on specific scenarios such as COM interop and mobile applications. Consider including this rule set if one of these scenarios applies to your project or to find additional problems in your project. | +| **Microsoft Extended Correctness Rules** | These rules expand on the basic correctness rules to maximize the reported logic and framework usage errors. Extra emphasis is placed on specific scenarios such as COM interop and mobile applications. Consider including this rule set if one of these scenarios applies to your project or to find more problems in your project. | | **Microsoft Extended Design Guideline Rules** | These rules expand on the basic design guideline rules to maximize the reported usability and maintainability issues. Extra emphasis is placed on naming guidelines. Consider including this rule set if your project includes library code or if you want to enforce the highest standards for writing maintainable code. | | **Microsoft Globalization Rules** | These rules focus on problems that prevent data in your application from displaying correctly when used in different languages, locales, and cultures. Include this rule set if your application is localized and/or globalized. | -| **Microsoft Managed Minimum Rules** | These rules focus on the most critical problems in your code for which Code Analysis is the most accurate. These rules are small in number and they are intended only to run in limited Visual Studio editions. Use MinimumRecommendedRules.ruleset with other Visual Studio editions. | +| **Microsoft Managed Minimum Rules** | These rules focus on the most critical problems in your code for which Code Analysis is the most accurate. These rules are small in number and they're intended only to run in limited Visual Studio editions. Use MinimumRecommendedRules.ruleset with other Visual Studio editions. | | **Microsoft Managed Recommended Rules** | These rules focus on the most critical problems in your code. These problems include potential security holes, application crashes, and other important logic and design errors. We recommend you include this rule set in any custom rule set you create for your projects. | | **Microsoft Mixed (C++ /CLR) Minimum Rules** | These rules focus on the most critical problems in your C++ projects that support the Common Language Runtime. These problems include potential security holes, application crashes, and other important logic and design errors. We recommend you include this rule set in any custom rule set you create for your C++ projects that support the Common Language Runtime. | | **Microsoft Mixed (C++ /CLR) Recommended Rules** | These rules focus on the most common and critical problems in your C++ projects that support the Common Language Runtime. These problems include potential security holes, application crashes, and other important logic and design errors. This ruleset is designed for use in the Visual Studio Professional edition and higher. | @@ -92,7 +92,7 @@ To run code analysis on a file: 1. In the **Build** menu, choose **Run Code Analysis on File** or press **Ctrl+Shift+Alt+F7**. - The project or solution is compiled and code analysis runs. Results appear in the Error List window. +The project or solution is compiled and code analysis runs. Results appear in the **Error List** window. ## Analyze and resolve code analysis warnings @@ -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/specifying-when-and-where-an-annotation-applies.md b/docs/code-quality/specifying-when-and-where-an-annotation-applies.md index d0849fc192a..f01e08d9919 100644 --- a/docs/code-quality/specifying-when-and-where-an-annotation-applies.md +++ b/docs/code-quality/specifying-when-and-where-an-annotation-applies.md @@ -2,7 +2,7 @@ description: "Learn more about: Specifying When and Where an Annotation Applies" title: Specifying When and Where an Annotation Applies ms.date: 11/04/2016 -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: - "_Group_" - "_At_" diff --git a/docs/code-quality/toc.yml b/docs/code-quality/toc.yml index 89b308dd0b8..948d04dcb78 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,807 +41,867 @@ items: href: ../code-quality/intrinsic-functions.md - name: Best practices and examples (SAL) href: ../code-quality/best-practices-and-examples-sal.md -- name: Specify additional code information by using _Analysis_assume_ +- name: Specify more code information by using _Analysis_assume_ href: ../code-quality/how-to-specify-additional-code-information-by-using-analysis-assume.md - name: C++ Core Guidelines checker warnings items: - name: Overview displayName: "C++ core guidelines checker warnings" href: ../code-quality/code-analysis-for-cpp-corecheck.md - - name: C26400 + - name: Warning C26400 href: ../code-quality/c26400.md - - name: C26401 + - name: Warning C26401 href: ../code-quality/c26401.md - - name: C26402 + - name: Warning C26402 href: ../code-quality/c26402.md - - name: C26403 + - name: Warning C26403 href: ../code-quality/c26403.md - - name: C26404 + - name: Warning C26404 href: ../code-quality/c26404.md - - name: C26405 + - name: Warning C26405 href: ../code-quality/c26405.md - - name: C26406 + - name: Warning C26406 href: ../code-quality/c26406.md - - name: C26407 + - name: Warning C26407 href: ../code-quality/c26407.md - - name: C26408 + - name: Warning C26408 href: ../code-quality/c26408.md - - name: C26409 + - name: Warning C26409 href: ../code-quality/c26409.md - - name: C26410 + - name: Warning C26410 href: ../code-quality/c26410.md - - name: C26411 + - name: Warning C26411 href: ../code-quality/c26411.md - - name: C26414 + - name: Warning C26414 href: ../code-quality/c26414.md - - name: C26415 + - name: Warning C26415 href: ../code-quality/c26415.md - - name: C26416 + - name: Warning C26416 href: ../code-quality/c26416.md - - name: C26417 + - name: Warning C26417 href: ../code-quality/c26417.md - - name: C26418 + - name: Warning C26418 href: ../code-quality/c26418.md - - name: C26426 + - name: Warning C26426 href: ../code-quality/c26426.md - - name: C26427 + - name: Warning C26427 href: ../code-quality/c26427.md - - name: C26429 + - name: Warning C26429 href: ../code-quality/c26429.md - - name: C26430 + - name: Warning C26430 href: ../code-quality/c26430.md - - name: C26431 + - name: Warning C26431 href: ../code-quality/c26431.md - - name: C26432 + - name: Warning C26432 href: ../code-quality/c26432.md - - name: C26433 + - name: Warning C26433 href: ../code-quality/c26433.md - - name: C26434 + - name: Warning C26434 href: ../code-quality/c26434.md - - name: C26435 + - name: Warning C26435 href: ../code-quality/c26435.md - - name: C26436 + - name: Warning C26436 href: ../code-quality/c26436.md - - name: C26437 + - name: Warning C26437 href: ../code-quality/c26437.md - - name: C26438 + - name: Warning C26438 href: ../code-quality/c26438.md - - name: C26439 + - name: Warning C26439 href: ../code-quality/c26439.md - - name: C26440 + - name: Warning C26440 href: ../code-quality/c26440.md - - name: C26441 + - name: Warning C26441 href: ../code-quality/c26441.md - - name: C26443 + - name: Warning C26443 href: ../code-quality/c26443.md - - name: C26444 + - name: Warning C26444 href: ../code-quality/c26444.md - - name: C26445 + - name: Warning C26445 href: ../code-quality/c26445.md - - name: C26446 + - name: Warning C26446 href: ../code-quality/c26446.md - - name: C26447 + - name: Warning C26447 href: ../code-quality/c26447.md - - name: C26448 + - name: Warning C26448 href: ../code-quality/c26448.md - - name: C26449 + - name: Warning C26449 href: ../code-quality/c26449.md - - name: C26450 + - name: Warning C26450 href: ../code-quality/c26450.md - - name: C26451 + - name: Warning C26451 href: ../code-quality/c26451.md - - name: C26452 + - name: Warning C26452 href: ../code-quality/c26452.md - - name: C26453 + - name: Warning C26453 href: ../code-quality/c26453.md - - name: C26454 + - name: Warning C26454 href: ../code-quality/c26454.md - - name: C26455 + - name: Warning C26455 href: ../code-quality/c26455.md - - name: C26456 + - name: Warning C26456 href: ../code-quality/c26456.md - - name: C26457 + - name: Warning C26457 href: ../code-quality/c26457.md - - name: C26460 + - name: Warning C26459 + href: ../code-quality/c26459.md + - name: Warning C26460 href: ../code-quality/c26460.md - - name: C26461 + - name: Warning C26461 href: ../code-quality/c26461.md - - name: C26462 + - name: Warning C26462 href: ../code-quality/c26462.md - - name: C26463 + - name: Warning C26463 href: ../code-quality/c26463.md - - name: C26464 + - name: Warning C26464 href: ../code-quality/c26464.md - - name: C26465 + - name: Warning C26465 href: ../code-quality/c26465.md - - name: C26466 + - name: Warning C26466 href: ../code-quality/c26466.md - - name: C26471 + - name: Warning C26471 href: ../code-quality/c26471.md - - name: C26472 + - name: Warning C26472 href: ../code-quality/c26472.md - - name: C26473 + - name: Warning C26473 href: ../code-quality/c26473.md - - name: C26474 + - name: Warning C26474 href: ../code-quality/c26474.md - - name: C26475 + - name: Warning C26475 href: ../code-quality/c26475.md - - name: C26476 + - name: Warning C26476 href: ../code-quality/c26476.md - - name: C26477 + - name: Warning C26477 href: ../code-quality/c26477.md - - name: C26478 + - name: Warning C26478 href: ../code-quality/c26478.md - - name: C26481 + - name: Warning C26479 + href: ../code-quality/c26479.md + - name: Warning C26481 href: ../code-quality/c26481.md - - name: C26482 + - name: Warning C26482 href: ../code-quality/c26482.md - - name: C26483 + - name: Warning C26483 href: ../code-quality/c26483.md - - name: C26485 + - name: Warning C26485 href: ../code-quality/c26485.md - - name: C26486 + - name: Warning C26486 href: ../code-quality/c26486.md - - name: C26487 + - name: Warning C26487 href: ../code-quality/c26487.md - - name: C26488 + - name: Warning C26488 href: ../code-quality/c26488.md - - name: C26489 + - name: Warning C26489 href: ../code-quality/c26489.md - - name: C26490 + - name: Warning C26490 href: ../code-quality/c26490.md - - name: C26491 + - name: Warning C26491 href: ../code-quality/c26491.md - - name: C26492 + - name: Warning C26492 href: ../code-quality/c26492.md - - name: C26493 + - name: Warning C26493 href: ../code-quality/c26493.md - - name: C26494 + - name: Warning C26494 href: ../code-quality/c26494.md - - name: C26495 + - name: Warning C26495 href: ../code-quality/c26495.md - - name: C26496 + - name: Warning C26496 href: ../code-quality/c26496.md - - name: C26497 + - name: Warning C26497 href: ../code-quality/c26497.md - - name: C26498 + - name: Warning C26498 href: ../code-quality/c26498.md - - name: C26812 + - name: Warning C26812 href: ../code-quality/c26812.md - - name: C26814 + - name: Warning C26814 href: ../code-quality/c26814.md - - name: C26815 + - name: Warning C26815 href: ../code-quality/c26815.md - - name: C26816 + - name: Warning C26816 href: ../code-quality/c26816.md - - name: C26817 + - name: Warning C26817 href: ../code-quality/c26817.md - - name: C26818 + - name: Warning C26818 href: ../code-quality/c26818.md - - name: C26819 + - name: Warning C26819 href: ../code-quality/c26819.md - - name: C26820 + - name: Warning C26820 href: ../code-quality/c26820.md - name: C/C++ code analysis warnings items: - name: Overview displayName: "Code analysis warnings" href: ../code-quality/code-analysis-for-c-cpp-warnings.md - - name: C1250 + - name: Fatal error C1250 href: ../code-quality/c1250.md - - name: C1251 + - name: Fatal error C1251 href: ../code-quality/c1251.md - - name: C1252 + - name: Fatal error C1252 href: ../code-quality/c1252.md - - name: C1253 + - name: Fatal error C1253 href: ../code-quality/c1253.md - - name: C1254 + - name: Fatal error C1254 href: ../code-quality/c1254.md - - name: C1255 + - name: Fatal error C1255 href: ../code-quality/c1255.md - - name: C1256 + - name: Fatal error C1256 href: ../code-quality/c1256.md - - name: C1257 + - name: Fatal error C1257 href: ../code-quality/c1257.md - - name: C6001 + - name: Fatal error C1258 + href: ../code-quality/c1258.md + - name: Fatal error C1259 + href: ../code-quality/c1259.md + - name: Fatal error C1260 + href: ../code-quality/c1260.md + - name: Warning C6001 href: ../code-quality/c6001.md - - name: C6011 + - name: Warning C6011 href: ../code-quality/c6011.md - - name: C6014 + - name: Warning C6014 href: ../code-quality/c6014.md - - name: C6029 + - name: Warning C6029 href: ../code-quality/c6029.md - - name: C6031 + - name: Warning C6030 + href: ../code-quality/c6030.md + - name: Warning C6031 href: ../code-quality/c6031.md - - name: C6053 + - name: Warning C6053 href: ../code-quality/c6053.md - - name: C6054 + - name: Warning C6054 href: ../code-quality/c6054.md - - name: C6059 + - name: Warning C6059 href: ../code-quality/c6059.md - - name: C6063 + - name: Warning C6063 href: ../code-quality/c6063.md - - name: C6064 + - name: Warning C6064 href: ../code-quality/c6064.md - - name: C6066 + - name: Warning C6065 + href: ../code-quality/c6065.md + - name: Warning C6066 href: ../code-quality/c6066.md - - name: C6067 + - name: Warning C6067 href: ../code-quality/c6067.md - - name: C6101 + - name: Warning C6101 href: ../code-quality/c6101.md - - name: C6102 + - name: Warning C6102 href: ../code-quality/c6102.md - - name: C6103 + - name: Warning C6103 href: ../code-quality/c6103.md - - name: C6200 + - name: Warning C6200 href: ../code-quality/c6200.md - - name: C6201 + - name: Warning C6201 href: ../code-quality/c6201.md - - name: C6211 + - name: Warning C6211 href: ../code-quality/c6211.md - - name: C6214 + - name: Warning C6214 href: ../code-quality/c6214.md - - name: C6215 + - name: Warning C6215 href: ../code-quality/c6215.md - - name: C6216 + - name: Warning C6216 href: ../code-quality/c6216.md - - name: C6217 + - name: Warning C6217 href: ../code-quality/c6217.md - - name: C6219 + - name: Warning C6219 href: ../code-quality/c6219.md - - name: C6220 + - name: Warning C6220 href: ../code-quality/c6220.md - - name: C6221 + - name: Warning C6221 href: ../code-quality/c6221.md - - name: C6225 + - name: Warning C6225 href: ../code-quality/c6225.md - - name: C6226 + - name: Warning C6226 href: ../code-quality/c6226.md - - name: C6230 + - name: Warning C6230 href: ../code-quality/c6230.md - - name: C6235 + - name: Warning C6235 href: ../code-quality/c6235.md - - name: C6236 + - name: Warning C6236 href: ../code-quality/c6236.md - - name: C6237 + - name: Warning C6237 href: ../code-quality/c6237.md - - name: C6239 + - name: Warning C6239 href: ../code-quality/c6239.md - - name: C6240 + - name: Warning C6240 href: ../code-quality/c6240.md - - name: C6242 + - name: Warning C6242 href: ../code-quality/c6242.md - - name: C6244 + - name: Warning C6244 href: ../code-quality/c6244.md - - name: C6246 + - name: Warning C6246 href: ../code-quality/c6246.md - - name: C6248 + - name: Warning C6248 href: ../code-quality/c6248.md - - name: C6250 + - name: Warning C6250 href: ../code-quality/c6250.md - - name: C6255 + - name: Warning C6255 href: ../code-quality/c6255.md - - name: C6258 + - name: Warning C6258 href: ../code-quality/c6258.md - - name: C6259 + - name: Warning C6259 href: ../code-quality/c6259.md - - name: C6260 + - name: Warning C6260 href: ../code-quality/c6260.md - - name: C6262 + - name: Warning C6262 href: ../code-quality/c6262.md - - name: C6263 + - name: Warning C6263 href: ../code-quality/c6263.md - - name: C6268 + - name: Warning C6268 href: ../code-quality/c6268.md - - name: C6269 + - name: Warning C6269 href: ../code-quality/c6269.md - - name: C6270 + - name: Warning C6270 href: ../code-quality/c6270.md - - name: C6271 + - name: Warning C6271 href: ../code-quality/c6271.md - - name: C6272 + - name: Warning C6272 href: ../code-quality/c6272.md - - name: C6273 + - name: Warning C6273 href: ../code-quality/c6273.md - - name: C6274 + - name: Warning C6274 href: ../code-quality/c6274.md - - name: C6276 + - name: Warning C6276 href: ../code-quality/c6276.md - - name: C6277 + - name: Warning C6277 href: ../code-quality/c6277.md - - name: C6278 + - name: Warning C6278 href: ../code-quality/c6278.md - - name: C6279 + - name: Warning C6279 href: ../code-quality/c6279.md - - name: C6280 + - name: Warning C6280 href: ../code-quality/c6280.md - - name: C6281 + - name: Warning C6281 href: ../code-quality/c6281.md - - name: C6282 + - name: Warning C6282 href: ../code-quality/c6282.md - - name: C6283 + - name: Warning C6283 href: ../code-quality/c6283.md - - name: C6284 + - name: Warning C6284 href: ../code-quality/c6284.md - - name: C6285 + - name: Warning C6285 href: ../code-quality/c6285.md - - name: C6286 + - name: Warning C6286 href: ../code-quality/c6286.md - - name: C6287 + - name: Warning C6287 href: ../code-quality/c6287.md - - name: C6288 + - name: Warning C6288 href: ../code-quality/c6288.md - - name: C6289 + - name: Warning C6289 href: ../code-quality/c6289.md - - name: C6290 + - name: Warning C6290 href: ../code-quality/c6290.md - - name: C6291 + - name: Warning C6291 href: ../code-quality/c6291.md - - name: C6292 + - name: Warning C6292 href: ../code-quality/c6292.md - - name: C6293 + - name: Warning C6293 href: ../code-quality/c6293.md - - name: C6294 + - name: Warning C6294 href: ../code-quality/c6294.md - - name: C6295 + - name: Warning C6295 href: ../code-quality/c6295.md - - name: C6296 + - name: Warning C6296 href: ../code-quality/c6296.md - - name: C6297 + - name: Warning C6297 href: ../code-quality/c6297.md - - name: C6298 + - name: Warning C6298 href: ../code-quality/c6298.md - - name: C6299 + - name: Warning C6299 href: ../code-quality/c6299.md - - name: C6302 + - name: Warning C6302 href: ../code-quality/c6302.md - - name: C6303 + - name: Warning C6303 href: ../code-quality/c6303.md - - name: C6305 + - name: Warning C6305 href: ../code-quality/c6305.md - - name: C6306 + - name: Warning C6306 href: ../code-quality/c6306.md - - name: C6308 + - name: Warning C6308 href: ../code-quality/c6308.md - - name: C6310 + - name: Warning C6310 href: ../code-quality/c6310.md - - name: C6312 + - name: Warning C6312 href: ../code-quality/c6312.md - - name: C6313 + - name: Warning C6313 href: ../code-quality/c6313.md - - name: C6314 + - name: Warning C6314 href: ../code-quality/c6314.md - - name: C6315 + - name: Warning C6315 href: ../code-quality/c6315.md - - name: C6316 + - name: Warning C6316 href: ../code-quality/c6316.md - - name: C6317 + - name: Warning C6317 href: ../code-quality/c6317.md - - name: C6318 + - name: Warning C6318 href: ../code-quality/c6318.md - - name: C6319 + - name: Warning C6319 href: ../code-quality/c6319.md - - name: C6320 + - name: Warning C6320 href: ../code-quality/c6320.md - - name: C6322 + - name: Warning C6322 href: ../code-quality/c6322.md - - name: C6323 + - name: Warning C6323 href: ../code-quality/c6323.md - - name: C6324 + - name: Warning C6324 href: ../code-quality/c6324.md - - name: C6326 + - name: Warning C6326 href: ../code-quality/c6326.md - - name: C6328 + - name: Warning C6328 href: ../code-quality/c6328.md - - name: C6329 + - name: Warning C6329 href: ../code-quality/c6329.md - - name: C6330 + - name: Warning C6330 href: ../code-quality/c6330.md - - name: C6331 + - name: Warning C6331 href: ../code-quality/c6331.md - - name: C6332 + - name: Warning C6332 href: ../code-quality/c6332.md - - name: C6333 + - name: Warning C6333 href: ../code-quality/c6333.md - - name: C6334 + - name: Warning C6334 href: ../code-quality/c6334.md - - name: C6335 + - name: Warning C6335 href: ../code-quality/c6335.md - - name: C6336 + - name: Warning C6336 href: ../code-quality/c6336.md - - name: C6340 + - name: Warning C6340 href: ../code-quality/c6340.md - - name: C6381 + - name: Warning C6381 href: ../code-quality/c6381.md - - name: C6383 + - name: Warning C6383 href: ../code-quality/c6383.md - - name: C6384 + - name: Warning C6384 href: ../code-quality/c6384.md - - name: C6385 + - name: Warning C6385 href: ../code-quality/c6385.md - - name: C6386 + - name: Warning C6386 href: ../code-quality/c6386.md - - name: C6387 + - name: Warning C6387 href: ../code-quality/c6387.md - - name: C6388 + - name: Warning C6388 href: ../code-quality/c6388.md - - name: C6389 + - name: Warning C6389 href: ../code-quality/c6389.md - - name: C6390 + - name: Warning C6390 href: ../code-quality/c6390.md - - name: C6400 + - name: Warning C6392 + href: ../code-quality/c6392.md + - name: Warning C6393 + href: ../code-quality/c6393.md + - name: Warning C6394 + href: ../code-quality/c6394.md + - name: Warning C6395 + href: ../code-quality/c6395.md + - name: Warning C6396 + href: ../code-quality/c6396.md + - name: Warning C6397 + href: ../code-quality/c6397.md + - name: Warning C6398 + href: ../code-quality/c6398.md + - name: Warning C6400 href: ../code-quality/c6400.md - - name: C6401 + - name: Warning C6401 href: ../code-quality/c6401.md - - name: C6411 + - name: Warning C6411 href: ../code-quality/c6411.md - - name: C6412 + - name: Warning C6412 href: ../code-quality/c6412.md - - name: C6500 + - name: Warning C6500 href: ../code-quality/c6500.md - - name: C6501 + - name: Warning C6501 href: ../code-quality/c6501.md - - name: C6503 + - name: Warning C6503 href: ../code-quality/c6503.md - - name: C6504 + - name: Warning C6504 href: ../code-quality/c6504.md - - name: C6505 + - name: Warning C6505 href: ../code-quality/c6505.md - - name: C6506 + - name: Warning C6506 href: ../code-quality/c6506.md - - name: C6508 + - name: Warning C6508 href: ../code-quality/c6508.md - - name: C6509 + - name: Warning C6509 href: ../code-quality/c6509.md - - name: C6510 + - name: Warning C6510 href: ../code-quality/c6510.md - - name: C6511 + - name: Warning C6511 href: ../code-quality/c6511.md - - name: C6513 + - name: Warning C6513 href: ../code-quality/c6513.md - - name: C6514 + - name: Warning C6514 href: ../code-quality/c6514.md - - name: C6515 + - name: Warning C6515 href: ../code-quality/c6515.md - - name: C6516 + - name: Warning C6516 href: ../code-quality/c6516.md - - name: C6517 + - name: Warning C6517 href: ../code-quality/c6517.md - - name: C6518 + - name: Warning C6518 href: ../code-quality/c6518.md - - name: C6522 + - name: Warning C6522 href: ../code-quality/c6522.md - - name: C6525 + - name: Warning C6525 href: ../code-quality/c6525.md - - name: C6527 + - name: Warning C6527 href: ../code-quality/c6527.md - - name: C6530 + - name: Warning C6530 href: ../code-quality/c6530.md - - name: C6540 + - name: Warning C6540 href: ../code-quality/c6540.md - - name: C6551 + - name: Warning C6551 href: ../code-quality/c6551.md - - name: C6552 + - name: Warning C6552 href: ../code-quality/c6552.md - - name: C6701 + - name: Warning C6701 href: ../code-quality/c6701.md - - name: C6702 + - name: Warning C6702 href: ../code-quality/c6702.md - - name: C6703 + - name: Warning C6703 href: ../code-quality/c6703.md - - name: C6704 + - name: Warning C6704 href: ../code-quality/c6704.md - - name: C6705 + - name: Warning C6705 href: ../code-quality/c6705.md - - name: C6706 + - name: Warning C6706 href: ../code-quality/c6706.md - - name: C6707 + - name: Warning C6707 href: ../code-quality/c6707.md - - name: C6993 + - name: Warning C6993 href: ../code-quality/c6993.md - - name: C6995 + - name: Warning C6995 href: ../code-quality/c6995.md - - name: C6997 + - name: Warning C6997 href: ../code-quality/c6997.md - - name: C26100 + - name: Warning C26100 href: ../code-quality/c26100.md - - name: C26101 + - name: Warning C26101 href: ../code-quality/c26101.md - - name: C26105 + - name: Warning C26105 href: ../code-quality/c26105.md - - name: C26110 + - name: Warning C26110 href: ../code-quality/c26110.md - - name: C26111 + - name: Warning C26111 href: ../code-quality/c26111.md - - name: C26112 + - name: Warning C26112 href: ../code-quality/c26112.md - - name: C26115 + - name: Warning C26115 href: ../code-quality/c26115.md - - name: C26116 + - name: Warning C26116 href: ../code-quality/c26116.md - - name: C26117 + - name: Warning C26117 href: ../code-quality/c26117.md - - name: C26130 + - name: Warning C26130 href: ../code-quality/c26130.md - - name: C26135 + - name: Warning C26132 + href: c26132.md + - name: Warning C26133 + href: c26133.md + - name: Warning C26135 href: ../code-quality/c26135.md - - name: C26138 + - name: Warning C26138 href: ../code-quality/c26138.md - - name: C26140 + - name: Warning C26140 href: ../code-quality/c26140.md - - name: C26160 + - name: Warning C26160 href: ../code-quality/c26160.md - - name: C26165 + - name: Warning C26165 href: ../code-quality/c26165.md - - name: C26166 + - name: Warning C26166 href: ../code-quality/c26166.md - - name: C26167 + - name: Warning C26167 href: ../code-quality/c26167.md - - name: C26800 + - name: Warning C26800 href: ../code-quality/c26800.md - - name: C26810 + - name: Warning C26810 href: ../code-quality/c26810.md - - name: C26811 + - name: Warning C26811 href: ../code-quality/c26811.md - - name: C26813 + - name: Warning C26813 href: ../code-quality/c26813.md - - name: C26822 + - name: Warning C26822 href: ../code-quality/c26822.md - - name: C26823 + - name: Warning C26823 href: ../code-quality/c26823.md - - name: C26824 + - name: Warning C26824 href: ../code-quality/c26824.md - - name: C26825 + - name: Warning C26825 href: ../code-quality/c26825.md - - name: C26826 + - name: Warning C26826 href: ../code-quality/c26826.md - - name: C26827 + - name: Warning C26827 href: ../code-quality/c26827.md - - name: C26828 + - name: Warning C26828 href: ../code-quality/c26828.md - - name: C26829 + - name: Warning C26829 href: ../code-quality/c26829.md - - name: C26830 + - name: Warning C26830 href: ../code-quality/c26830.md - - name: C28020 + - 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 C26865 + href: ../code-quality/c26865.md + - name: Warning C28020 href: ../code-quality/c28020.md - - name: C28021 + - name: Warning C28021 href: ../code-quality/c28021.md - - name: C28022 + - name: Warning C28022 href: ../code-quality/c28022.md - - name: C28023 + - name: Warning C28023 href: ../code-quality/c28023.md - - name: C28024 + - name: Warning C28024 href: ../code-quality/c28024.md - - name: C28039 + - name: Warning C28039 href: ../code-quality/c28039.md - - name: C28103 + - name: Warning C28103 href: ../code-quality/c28103.md - - name: C28104 + - name: Warning C28104 href: ../code-quality/c28104.md - - name: C28105 + - name: Warning C28105 href: ../code-quality/c28105.md - - name: C28106 + - name: Warning C28106 href: ../code-quality/c28106.md - - name: C28107 + - name: Warning C28107 href: ../code-quality/c28107.md - - name: C28108 + - name: Warning C28108 href: ../code-quality/c28108.md - - name: C28109 + - name: Warning C28109 href: ../code-quality/c28109.md - - name: C28112 + - name: Warning C28112 href: ../code-quality/c28112.md - - name: C28113 + - name: Warning C28113 href: ../code-quality/c28113.md - - name: C28125 + - name: Warning C28125 href: ../code-quality/c28125.md - - name: C28137 + - name: Warning C28137 href: ../code-quality/c28137.md - - name: C28138 + - name: Warning C28138 href: ../code-quality/c28138.md - - name: C28159 + - name: Warning C28159 href: ../code-quality/c28159.md - - name: C28160 + - name: Warning C28160 href: ../code-quality/c28160.md - - name: C28163 + - name: Warning C28163 href: ../code-quality/c28163.md - - name: C28164 + - name: Warning C28164 href: ../code-quality/c28164.md - - name: C28182 + - name: Warning C28182 href: ../code-quality/c28182.md - - name: C28183 + - name: Warning C28183 href: ../code-quality/c28183.md - - name: C28193 + - name: Warning C28193 href: ../code-quality/c28193.md - - name: C28194 + - name: Warning C28194 href: ../code-quality/c28194.md - - name: C28195 + - name: Warning C28195 href: ../code-quality/c28195.md - - name: C28196 + - name: Warning C28196 href: ../code-quality/c28196.md - - name: C28197 + - name: Warning C28197 href: ../code-quality/c28197.md - - name: C28198 + - name: Warning C28198 href: ../code-quality/c28198.md - - name: C28199 + - name: Warning C28199 href: ../code-quality/c28199.md - - name: C28202 + - name: Warning C28202 href: ../code-quality/c28202.md - - name: C28203 + - name: Warning C28203 href: ../code-quality/c28203.md - - name: C28204 + - name: Warning C28204 href: ../code-quality/c28204.md - - name: C28205 + - name: Warning C28205 href: ../code-quality/c28205.md - - name: C28206 + - name: Warning C28206 href: ../code-quality/c28206.md - - name: C28207 + - name: Warning C28207 href: ../code-quality/c28207.md - - name: C28208 + - name: Warning C28208 href: ../code-quality/c28208.md - - name: C28209 + - name: Warning C28209 href: ../code-quality/c28209.md - - name: C28210 + - name: Warning C28210 href: ../code-quality/c28210.md - - name: C28211 + - name: Warning C28211 href: ../code-quality/c28211.md - - name: C28212 + - name: Warning C28212 href: ../code-quality/c28212.md - - name: C28213 + - name: Warning C28213 href: ../code-quality/c28213.md - - name: C28214 + - name: Warning C28214 href: ../code-quality/c28214.md - - name: C28215 + - name: Warning C28215 href: ../code-quality/c28215.md - - name: C28216 + - name: Warning C28216 href: ../code-quality/c28216.md - - name: C28217 + - name: Warning C28217 href: ../code-quality/c28217.md - - name: C28218 + - name: Warning C28218 href: ../code-quality/c28218.md - - name: C28219 + - name: Warning C28219 href: ../code-quality/c28219.md - - name: C28220 + - name: Warning C28220 href: ../code-quality/c28220.md - - name: C28221 + - name: Warning C28221 href: ../code-quality/c28221.md - - name: C28222 + - name: Warning C28222 href: ../code-quality/c28222.md - - name: C28223 + - name: Warning C28223 href: ../code-quality/c28223.md - - name: C28224 + - name: Warning C28224 href: ../code-quality/c28224.md - - name: C28225 + - name: Warning C28225 href: ../code-quality/c28225.md - - name: C28226 + - name: Warning C28226 href: ../code-quality/c28226.md - - name: C28227 + - name: Warning C28227 href: ../code-quality/c28227.md - - name: C28228 + - name: Warning C28228 href: ../code-quality/c28228.md - - name: C28229 + - name: Warning C28229 href: ../code-quality/c28229.md - - name: C28230 + - name: Warning C28230 href: ../code-quality/c28230.md - - name: C28231 + - name: Warning C28231 href: ../code-quality/c28231.md - - name: C28232 + - name: Warning C28232 href: ../code-quality/c28232.md - - name: C28233 + - name: Warning C28233 href: ../code-quality/c28233.md - - name: C28234 + - name: Warning C28234 href: ../code-quality/c28234.md - - name: C28235 + - name: Warning C28235 href: ../code-quality/c28235.md - - name: C28236 + - name: Warning C28236 href: ../code-quality/c28236.md - - name: C28237 + - name: Warning C28237 href: ../code-quality/c28237.md - - name: C28238 + - name: Warning C28238 href: ../code-quality/c28238.md - - name: C28239 + - name: Warning C28239 href: ../code-quality/c28239.md - - name: C28240 + - name: Warning C28240 href: ../code-quality/c28240.md - - name: C28241 + - name: Warning C28241 href: ../code-quality/c28241.md - - name: C28243 + - name: Warning C28243 href: ../code-quality/c28243.md - - name: C28244 + - name: Warning C28244 href: ../code-quality/c28244.md - - name: C28245 + - name: Warning C28245 href: ../code-quality/c28245.md - - name: C28246 + - name: Warning C28246 href: ../code-quality/c28246.md - - name: C28250 + - name: Warning C28250 href: ../code-quality/c28250.md - - name: C28251 + - name: Warning C28251 href: ../code-quality/c28251.md - - name: C28252 + - name: Warning C28252 href: ../code-quality/c28252.md - - name: C28253 + - name: Warning C28253 href: ../code-quality/c28253.md - - name: C28254 + - name: Warning C28254 href: ../code-quality/c28254.md - - name: C28262 + - name: Warning C28262 href: ../code-quality/c28262.md - - name: C28263 + - name: Warning C28263 href: ../code-quality/c28263.md - - name: C28267 + - name: Warning C28267 href: ../code-quality/c28267.md - - name: C28272 + - name: Warning C28272 href: ../code-quality/c28272.md - - name: C28273 + - name: Warning C28273 href: ../code-quality/c28273.md - - name: C28275 + - name: Warning C28275 href: ../code-quality/c28275.md - - name: C28278 + - name: Warning C28278 href: ../code-quality/c28278.md - - name: C28279 + - name: Warning C28279 href: ../code-quality/c28279.md - - name: C28280 + - name: Warning C28280 href: ../code-quality/c28280.md - - name: C28282 + - name: Warning C28282 href: ../code-quality/c28282.md - - name: C28283 + - name: Warning C28283 href: ../code-quality/c28283.md - - name: C28284 + - name: Warning C28284 href: ../code-quality/c28284.md - - name: C28285 + - name: Warning C28285 href: ../code-quality/c28285.md - - name: C28286 + - name: Warning C28286 href: ../code-quality/c28286.md - - name: C28287 + - name: Warning C28287 href: ../code-quality/c28287.md - - name: C28288 + - name: Warning C28288 href: ../code-quality/c28288.md - - name: C28289 + - name: Warning C28289 href: ../code-quality/c28289.md - - name: C28290 + - name: Warning C28290 href: ../code-quality/c28290.md - - name: C28291 + - name: Warning C28291 href: ../code-quality/c28291.md - - name: C28300 + - name: Warning C28300 href: ../code-quality/c28300.md - - name: C28301 + - name: Warning C28301 href: ../code-quality/c28301.md - - name: C28302 + - name: Warning C28302 href: ../code-quality/c28302.md - - name: C28303 + - name: Warning C28303 href: ../code-quality/c28303.md - - name: C28304 + - name: Warning C28304 href: ../code-quality/c28304.md - - name: C28305 + - name: Warning C28305 href: ../code-quality/c28305.md - - name: C28306 + - name: Warning C28306 href: ../code-quality/c28306.md - - name: C28307 + - name: Warning C28307 href: ../code-quality/c28307.md - - name: C28308 + - name: Warning C28308 href: ../code-quality/c28308.md - - name: C28309 + - name: Warning C28309 href: ../code-quality/c28309.md - - name: C28310 + - name: Warning C28310 href: ../code-quality/c28310.md - - name: C28311 + - name: Warning C28311 href: ../code-quality/c28311.md - - name: C28312 + - name: Warning C28312 href: ../code-quality/c28312.md - - name: C28350 + - name: Warning C28350 href: ../code-quality/c28350.md - - name: C28351 + - name: Warning C28351 href: ../code-quality/c28351.md - - name: C33001 + - name: Warning C33001 href: ../code-quality/c33001.md - - name: C33004 + - name: Warning C33004 href: ../code-quality/c33004.md - - name: C33005 + - name: Warning C33005 href: ../code-quality/c33005.md - - name: C33010 + - name: Warning C33010 href: ../code-quality/c33010.md - - name: C33011 + - name: Warning C33011 href: ../code-quality/c33011.md - - name: C33020 + - name: Warning C33020 href: ../code-quality/c33020.md - - name: C33022 + - name: Warning C33022 href: ../code-quality/c33022.md diff --git a/docs/code-quality/understanding-sal.md b/docs/code-quality/understanding-sal.md index 198aed73359..fea482553a1 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 +ms.topic: "concept-article" --- # Understanding SAL @@ -20,7 +19,6 @@ Simply stated, SAL is an inexpensive way to let the compiler check your code for SAL can help you make your code design more understandable, both for humans and for code analysis tools. Consider this example that shows the C runtime function `memcpy`: ```cpp - void * memcpy( void *dest, const void *src, @@ -42,7 +40,6 @@ The documentation contains a couple of bits of information that suggest that you However, the compiler can't read the documentation or informal comments. It doesn't know that there is a relationship between the two buffers and `count`, and it also can't effectively guess about a relationship. SAL could provide more clarity about the properties and implementation of the function, as shown here: ```cpp - void * memcpy( _Out_writes_bytes_all_(count) void *dest, _In_reads_bytes_(count) const void *src, @@ -53,7 +50,6 @@ void * memcpy( Notice that these annotations resemble the information in the documentation, but they are more concise and they follow a semantic pattern. When you read this code, you can quickly understand the properties of this function and how to avoid buffer overrun security issues. Even better, the semantic patterns that SAL provides can improve the efficiency and effectiveness of automated code analysis tools in the early discovery of potential bugs. Imagine that someone writes this buggy implementation of `wmemcpy`: ```cpp - wchar_t * wmemcpy( _Out_writes_all_(count) wchar_t *dest, _In_reads_(count) const wchar_t *src, @@ -97,9 +93,9 @@ These annotations help identify possible uninitialized values and invalid null p This section shows code examples for the basic SAL annotations. -### Using the Visual Studio Code Analysis Tool to Find Defects +### Using the Visual Studio code analysis tool to find defects -In the examples, the Visual Studio Code Analysis tool is used together with SAL annotations to find code defects. Here's how to do that. +In the examples, the Visual Studio code analysis tool is used together with SAL annotations to find code defects. Here's how to do that. #### To use Visual Studio code analysis tools and SAL @@ -148,14 +144,13 @@ void BadInCaller() } ``` -If you use Visual Studio Code Analysis on this example, it validates that the callers pass a non-Null pointer to an initialized buffer for `pInt`. In this case, `pInt` pointer cannot be NULL. +If you use Visual Studio code analysis on this example, it validates that the callers pass a non-Null pointer to an initialized buffer for `pInt`. In this case, `pInt` pointer cannot be NULL. ### Example: The \_In\_opt\_ Annotation `_In_opt_` is the same as `_In_`, except that the input parameter is allowed to be NULL and, therefore, the function should check for this. ```cpp - void GoodInOptCallee(_In_opt_ int *pInt) { if(pInt != NULL) { @@ -176,7 +171,7 @@ void InOptCaller() } ``` -Visual Studio Code Analysis validates that the function checks for NULL before it accesses the buffer. +Visual Studio code analysis validates that the function checks for NULL before it accesses the buffer. ### Example: The \_Out\_ Annotation @@ -202,7 +197,7 @@ void OutCaller() } ``` -Visual Studio Code Analysis Tool validates that the caller passes a non-NULL pointer to a buffer for `pInt` and that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that the caller passes a non-NULL pointer to a buffer for `pInt` and that the buffer is initialized by the function before it returns. ### Example: The \_Out\_opt\_ Annotation @@ -229,7 +224,7 @@ void OutOptCaller() } ``` -Visual Studio Code Analysis validates that this function checks for NULL before `pInt` is dereferenced, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that this function checks for NULL before `pInt` is dereferenced, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. ### Example: The \_Inout\_ Annotation @@ -260,7 +255,7 @@ void BadInOutCaller() } ``` -Visual Studio Code Analysis validates that callers pass a non-NULL pointer to an initialized buffer for `pInt`, and that, before return, `pInt` is still non-NULL and the buffer is initialized. +Visual Studio code analysis validates that callers pass a non-NULL pointer to an initialized buffer for `pInt`, and that, before return, `pInt` is still non-NULL and the buffer is initialized. ### Example: The \_Inout\_opt\_ Annotation @@ -289,7 +284,7 @@ void InOutOptCaller() } ``` -Visual Studio Code Analysis validates that this function checks for NULL before it accesses the buffer, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that this function checks for NULL before it accesses the buffer, and if `pInt` is not NULL, that the buffer is initialized by the function before it returns. ### Example: The \_Outptr\_ Annotation @@ -319,7 +314,7 @@ void OutPtrCaller() } ``` -Visual Studio Code Analysis validates that the caller passes a non-NULL pointer for `*pInt`, and that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that the caller passes a non-NULL pointer for `*pInt`, and that the buffer is initialized by the function before it returns. ### Example: The \_Outptr\_opt\_ Annotation @@ -351,7 +346,7 @@ void OutPtrOptCaller() } ``` -Visual Studio Code Analysis validates that this function checks for NULL before `*pInt` is dereferenced, and that the buffer is initialized by the function before it returns. +Visual Studio code analysis validates that this function checks for NULL before `*pInt` is dereferenced, and that the buffer is initialized by the function before it returns. ### Example: The \_Success\_ Annotation in Combination with \_Out\_ @@ -370,7 +365,7 @@ bool GetValue(_Out_ int *pInt, bool flag) } ``` -The `_Out_` annotation causes Visual Studio Code Analysis to validate that the caller passes a non-NULL pointer to a buffer for `pInt`, and that the buffer is initialized by the function before it returns. +The `_Out_` annotation causes Visual Studio code analysis to validate that the caller passes a non-NULL pointer to a buffer for `pInt`, and that the buffer is initialized by the function before it returns. ## SAL Best Practice @@ -388,7 +383,7 @@ Here are some guidelines: - Annotate value-range annotations so that Code Analysis can ensure buffer and pointer safety. -- Annotate locking rules and locking side effects. For more information, see [Annotating Locking Behavior](../code-quality/annotating-locking-behavior.md). +- Annotate locking rules and locking side effects. For more information, see [Annotating Locking Behavior](annotating-locking-behavior.md). - Annotate driver properties and other domain-specific properties. @@ -396,10 +391,10 @@ Or you can annotate all parameters to make your intent clear throughout and to m ## See also -- [Using SAL Annotations to Reduce C/C++ Code Defects](../code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md) -- [Annotating Function Parameters and Return Values](../code-quality/annotating-function-parameters-and-return-values.md) -- [Annotating Function Behavior](../code-quality/annotating-function-behavior.md) -- [Annotating Structs and Classes](../code-quality/annotating-structs-and-classes.md) -- [Annotating Locking Behavior](../code-quality/annotating-locking-behavior.md) -- [Specifying When and Where an Annotation Applies](../code-quality/specifying-when-and-where-an-annotation-applies.md) -- [Best Practices and Examples](../code-quality/best-practices-and-examples-sal.md) +- [Using SAL Annotations to Reduce C/C++ Code Defects](using-sal-annotations-to-reduce-c-cpp-code-defects.md) +- [Annotating Function Parameters and Return Values](annotating-function-parameters-and-return-values.md) +- [Annotating Function Behavior](annotating-function-behavior.md) +- [Annotating Structs and Classes](annotating-structs-and-classes.md) +- [Annotating Locking Behavior](annotating-locking-behavior.md) +- [Specifying When and Where an Annotation Applies](specifying-when-and-where-an-annotation-applies.md) +- [Best Practices and Examples](best-practices-and-examples-sal.md) diff --git a/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md b/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md index 6591618fe17..a9884d1794c 100644 --- a/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md +++ b/docs/code-quality/using-rule-sets-to-specify-the-cpp-rules-to-run.md @@ -1,8 +1,8 @@ --- +title: "Using Rule Sets to Specify the C++ Rules to Run" description: "Learn more about: Use Rule Sets to Specify the C++ Rules to Run" -title: Using Rule Sets to Specify the C++ Rules to Run ms.date: 07/27/2020 -ms.topic: "conceptual" +ms.topic: "how-to" f1_keywords: - "vs.codeanalysis.rulesets.native" --- @@ -229,7 +229,6 @@ The following ruleset schema describes the XML schema of a ruleset file. The rul - ``` Schema element details: @@ -244,7 +243,7 @@ Schema element details: | `TIncludeAll` | Rule action for all rules | | `TRule` | Rule ID with rule action | | `TRules` | Collection of one or more rules | -| `TRuleSet` | Ruleset file format consisting of localization information, rule hint paths, include all information, include information, rules information, name, description, and tools version information | +| `TRuleSet` | Ruleset file format consisting of localization information, rule hint paths, include all information, include information, rules information, name, description, and tools version information | | `TRuleAction` | Enumeration describing a rule action such as an error, warning, info, hidden, or none | | `TIncludeAction` | Enumeration describing a rule action such as an error, warning, info, hidden, none, or default | | `TIncludeAllAction` | Enumeration describing a rule action such as an error, warning, info, or hidden | diff --git a/docs/code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md b/docs/code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md index 80f88e1c27f..3426d695a2a 100644 --- a/docs/code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md +++ b/docs/code-quality/using-sal-annotations-to-reduce-c-cpp-code-defects.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: Using SAL Annotations to Reduce C/C++ Code Defects" title: Using SAL Annotations to Reduce C/C++ Code Defects +description: "Learn more about: Using SAL Annotations to Reduce C/C++ Code Defects" ms.date: 11/04/2016 -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: - "annotations" - "SAL annotations" - "code analysis, annotation" -ms.assetid: a16e47d0-6f3e-4ed6-8883-459b2874e9a4 --- # Using SAL Annotations to Reduce C/C++ Code Defects @@ -47,6 +46,6 @@ The articles in this section of the documentation discuss aspects of SAL, provid Provides examples that show how to use SAL annotations. Also explains common pitfalls. -## See Also +## See also [SAL 2.0 Annotations for Windows Drivers](/windows-hardware/drivers/devtest/sal-2-annotations-for-windows-drivers) 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 1718eccb480..34cdcc545ff 100644 --- a/docs/code-quality/using-the-cpp-core-guidelines-checkers.md +++ b/docs/code-quality/using-the-cpp-core-guidelines-checkers.md @@ -1,14 +1,14 @@ --- 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.topic: "conceptual" +ms.date: 06/21/2023 +ms.topic: "how-to" dev_langs: - CPP --- # Use the C++ Core Guidelines checkers -The C++ Core Guidelines are a portable set of guidelines, rules, and best practices about coding in C++ created by C++ experts and designers. Visual Studio currently supports a subset of these rules as part of its code analysis tools for C++. The core guideline checkers are installed by default in Visual Studio 2017 and Visual Studio 2019. They're [available as a NuGet package for Visual Studio 2015](#vs2015_corecheck). +The C++ Core Guidelines are a portable set of guidelines, rules, and best practices about coding in C++ created by C++ experts and designers. Visual Studio currently supports a subset of these rules as part of its Microsoft C++ Code Analysis tools. The core guideline checkers are installed by default in Visual Studio 2017 and Visual Studio 2019. They're [available as a NuGet package for Visual Studio 2015](#vs2015_corecheck). ## The C++ Core Guidelines Project @@ -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) @@ -39,7 +39,7 @@ To enable additional Core Check rules, open the dropdown list and choose which r A subset of C++ Core Check rules is included in the Microsoft Native Recommended rule set. It's the ruleset that runs by default when Microsoft code analysis is enabled. -### To enable code analysis on your project: +### To enable code analysis on your project 1. Open the **Property Pages** dialog for your project. @@ -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,50 +104,50 @@ 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 +- **Arithmetic Rules**: Rules to detect arithmetic [overflow](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-overflow), [signed-unsigned operations](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-unsigned), and [bit manipulation](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-nonnegative).15.6 -- **Bounds Rules**: Enforce the [Bounds profile of the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#probounds-bounds-safety-profile).15.3 +- **Bounds Rules**: Enforce the [Bounds profile of the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#probounds-bounds-safety-profile).15.3 -- **Class Rules**: A few rules that focus on proper use of special member functions and virtual specifications. They're a subset of the checks recommended for [classes and class hierarchies](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-class).15.5 +- **Class Rules**: A few rules that focus on proper use of special member functions and virtual specifications. They're a subset of the checks recommended for [classes and class hierarchies](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-class).15.5 -- **Concurrency Rules**: A single rule, which catches bad guard object declarations. For more information, see [guidelines related to concurrency](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-concurrency).15.5 +- **Concurrency Rules**: A single rule, which catches bad guard object declarations. For more information, see [guidelines related to concurrency](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-concurrency).15.5 -- **Const Rules**: Enforce [const-related checks from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#con-constants-and-immutability).15.3 +- **Const Rules**: Enforce [const-related checks from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#con-constants-and-immutability).15.3 -- **Declaration Rules**: A couple of rules from the [interfaces guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-interfaces) that focus on how global variables are declared.15.5 +- **Declaration Rules**: A couple of rules from the [interfaces guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-interfaces) that focus on how global variables are declared.15.5 -- **Enum Rules**: These rules enforce [enum-related checks from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-enum).16.3 +- **Enum Rules**: These rules enforce [enum-related checks from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-enum).16.3 - **Experimental Rules** These are experimental C++ Core Check rules that are useful but not ready for everyday use. Try them out and [provide feedback](https://aka.ms/feedback/suggest?space=62).16.0 -- **Function Rules**: Two checks that help with adoption of the **`noexcept`** specifier. They're part of the guidelines for [clear function design and implementation](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-functions).15.5 +- **Function Rules**: Two checks that help with adoption of the **`noexcept`** specifier. They're part of the guidelines for [clear function design and implementation](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-functions).15.5 -- **GSL Rules**: These rules enforce checks related to the [Guidelines Support Library from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-gsl).15.7 +- **GSL Rules**: These rules enforce checks related to the [Guidelines Support Library from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-gsl).15.7 -- **Lifetime Rules**: These rules enforce the [Lifetime profile of the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prolifetime-lifetime-safety-profile).15.7 +- **Lifetime Rules**: These rules enforce the [Lifetime profile of the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#prolifetime-lifetime-safety-profile).15.7 -- **Owner Pointer Rules**: Enforce [resource-management checks related to owner\ from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management).15.3 +- **Owner Pointer Rules**: Enforce [resource-management checks related to owner\ from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r-resource-management).15.3 -- **Raw Pointer Rules**: Enforce [resource-management checks related to raw pointers from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management).15.3 +- **Raw Pointer Rules**: Enforce [resource-management checks related to raw pointers from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r-resource-management).15.3 -- **Shared pointer Rules**: It's part of [resource management](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-resource) guidelines enforcement.15.5 We added a few rules specific to how shared pointers are passed into functions or used locally. +- **Shared pointer Rules**: It's part of [resource management](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-resource) guidelines enforcement.15.5 We added a few rules specific to how shared pointers are passed into functions or used locally. -- **STL Rules**: These rules enforce checks related to the [C++ Standard Library (STL) from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#S-stdlib).15.7 +- **STL Rules**: These rules enforce checks related to the [C++ Standard Library (STL) from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#S-stdlib).15.7 -- **Style Rules**: One simple but important check, which bans use of [goto](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#Res-goto).15.5 It's the first step to improve your coding style and use of expressions and statements in C++. +- **Style Rules**: One simple but important check, which bans use of [goto](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#Res-goto).15.5 It's the first step to improve your coding style and use of expressions and statements in C++. -- **Type Rules**: Enforce the [Type profile of the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#prosafety-type-safety-profile).15.3 +- **Type Rules**: Enforce the [Type profile of the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#prosafety-type-safety-profile).15.3 -- **Unique Pointer Rules**: Enforce [resource-management checks related to types with unique pointer semantics from the C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#r-resource-management).15.3 +- **Unique Pointer Rules**: Enforce [resource-management checks related to types with unique pointer semantics from the C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#r-resource-management).15.3 -- **C++ Core Check Rules**: This rule set contains all the currently implemented checks from the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md#c-core-guidelines), except for the Experimental rules. +- **C++ Core Check Rules**: This rule set contains all the currently implemented checks from the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#c-core-guidelines), except for the Experimental rules. 15.3 These rules first appeared in Visual Studio 2017 version 15.3\ 15.5 These rules first appeared in Visual Studio 2017 version 15.5\ @@ -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 [https://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 7ef995023ed..384584b365a 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 @@ -2,7 +2,7 @@ title: "Walkthrough: Analyzing C/C++ code for defects" description: "Demonstrates how to use code analysis with Microsoft C++ in Visual Studio." ms.date: 04/14/2020 -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["C/C++, code analysis", "code analysis, walkthroughs", "code, analyzing C/C++", "code analysis tool, walkthroughs"] --- # Walkthrough: Analyzing C/C++ code for defects @@ -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/abstract-classes-cpp.md b/docs/cpp/abstract-classes-cpp.md index dd7181e7171..af5343782dd 100644 --- a/docs/cpp/abstract-classes-cpp.md +++ b/docs/cpp/abstract-classes-cpp.md @@ -31,13 +31,15 @@ The only difference between this declaration and the previous one is that `Print Abstract classes can't be used for: -- Variables or member data +- Variables or member data (you can't declare a variable of an abstract class type) -- Argument types +- Argument types (you can't pass an abstract class by value as a function parameter) -- Function return types +- Function return types (a function can't return an abstract class by value) -- Types of explicit conversions +- Types of explicit conversions (you can't cast to an abstract class type) + +In each case, you can use pointers or references to the abstract class type instead. For example, a function can take `AbstractBase&` or `AbstractBase*` as a parameter, and you can declare pointers or references of the abstract class type. If the constructor for an abstract class calls a pure virtual function, either directly or indirectly, the result is undefined. However, constructors and destructors for abstract classes can call other member functions. diff --git a/docs/cpp/additive-operators-plus-and.md b/docs/cpp/additive-operators-plus-and.md index 57281c0514f..7c86e0a3ea9 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 3f3a3411d64..939c0edb165 100644 --- a/docs/cpp/align-cpp.md +++ b/docs/cpp/align-cpp.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: align (C++)" title: "align (C++)" -ms.date: "12/17/2018" +description: "Learn more about: align (C++)" +ms.date: 12/17/2018 f1_keywords: ["align_cpp"] helpviewer_keywords: ["align __declspec keyword", "__declspec keyword [C++], align"] --- # `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 00000000000..4b5672fe866 --- /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 0219a84e4d3..092f6033416 100644 --- a/docs/cpp/alignment-cpp-declarations.md +++ b/docs/cpp/alignment-cpp-declarations.md @@ -1,16 +1,15 @@ --- title: "Alignment" description: "How data alignment is specified in modern C++." -ms.date: "12/11/2019" -ms.assetid: a986d510-ccb8-41f8-b905-433df9183485 +ms.date: 10/31/2023 --- # Alignment One of the low-level features of C++ is the ability to specify the precise alignment of objects in memory to take maximum advantage of a specific hardware architecture. By default, the compiler aligns class and struct members on their size value: **`bool`** and **`char`** on 1-byte boundaries, **`short`** on 2-byte boundaries, **`int`**, **`long`**, and **`float`** on 4-byte boundaries, and **`long long`**, **`double`**, and **`long double`** on 8-byte boundaries. -In most scenarios, you never have to be concerned with alignment because the default alignment is already optimal. In some cases, however, you can achieve significant performance improvements, or memory savings, by specifying a custom alignment for your data structures. Before Visual Studio 2015 you could use the Microsoft-specific keywords **`__alignof`** and **`__declspec(align)`** to specify an alignment greater than the default. Starting in Visual Studio 2015 you should use the C++11 standard keywords **`alignof`** and **`alignas`** for maximum code portability. The new keywords behave in the same way under the hood as the Microsoft-specific extensions. The documentation for those extensions also applies to the new keywords. For more information, see [`alignof` Operator](../cpp/alignof-operator.md) and [align](../cpp/align-cpp.md). The C++ standard doesn't specify packing behavior for alignment on boundaries smaller than the compiler default for the target platform, so you still need to use the Microsoft [`#pragma pack`](../preprocessor/pack.md) in that case. +In most scenarios, you never have to be concerned with alignment because the default alignment is already optimal. In some cases, however, you can achieve significant performance improvements, or memory savings, by specifying a custom alignment for your data structures. Before Visual Studio 2015 you could use the Microsoft-specific keywords **`__alignof`** and **`__declspec(align)`** to specify an alignment greater than the default. Starting in Visual Studio 2015 you should use the C++11 standard keywords **`alignof`** and **`alignas`** for maximum code portability. The new keywords behave in the same way under the hood as the Microsoft-specific extensions. The documentation for those extensions also applies to the new keywords. For more information, see [`alignof` Operator](../cpp/alignof-operator.md), [`alignas` Specifier](../cpp/alignas-specifier.md) and [align](../cpp/align-cpp.md). The C++ standard doesn't specify packing behavior for alignment on boundaries smaller than the compiler default for the target platform, so you still need to use the Microsoft [`#pragma pack`](../preprocessor/pack.md) in that case. -Use the [aligned_storage class](../standard-library/aligned-storage-class.md) for memory allocation of data structures with custom alignments. The [aligned_union class](../standard-library/aligned-union-class.md) is for specifying alignment for unions with non-trivial constructors or destructors. +Use the [aligned_storage class](../standard-library/aligned-storage-class.md) for memory allocation of data structures with custom alignments. The [aligned_union class](../standard-library/aligned-union-class.md) is for specifying alignment for unions with nontrivial constructors or destructors. ## Alignment and memory addresses @@ -58,8 +57,7 @@ Both declarations return `sizeof(struct x_)` as 12 bytes. The second declaration includes two padding elements: 1. `char _pad0[3]` to align the `int b` member on a 4-byte boundary. - -1. `char _pad1[1]` to align the array elements of the structure `struct _x bar[3];` on a four-byte boundary. +1. `char _pad1[1]` to align the array elements of the structure `struct _x bar[3];` on a 4-byte boundary. The padding aligns the elements of `bar[3]` in a way that allows natural access. @@ -92,11 +90,11 @@ adr offset element ## `alignof` and `alignas` -The **`alignas`** type specifier is a portable, C++ standard way to specify custom alignment of variables and user defined types. The **`alignof`** operator is likewise a standard, portable way to obtain the alignment of a specified type or variable. +The **`alignas`** specifier is a portable, C++ standard way to specify custom alignment of variables and user defined types. The **`alignof`** operator is likewise a standard, portable way to obtain the alignment of a specified type or variable. ## Example -You can use **`alignas`** on a class, struct or union, or on individual members. When multiple **`alignas`** specifiers are encountered, the compiler will choose the strictest one, (the one with the largest value). +You can use **`alignas`** on a class, struct or union, or on individual members. When multiple **`alignas`** specifiers are encountered, the compiler chooses the one with the largest value. ```cpp // alignas_alignof.cpp diff --git a/docs/cpp/alignof-operator.md b/docs/cpp/alignof-operator.md index 85de3668703..a30d84fe45d 100644 --- a/docs/cpp/alignof-operator.md +++ b/docs/cpp/alignof-operator.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: alignof Operator" title: "alignof Operator" -ms.date: "12/17/2018" +description: "Learn more about: alignof Operator" +ms.date: 12/17/2018 f1_keywords: ["__alignof_cpp", "alignof_cpp", "__alignof", "_alignof"] helpviewer_keywords: ["alignas [C++]", "alignment of structures", "__alignof keyword [C++]", "alignof [C++]", "types [C++], alignment requirements"] --- diff --git a/docs/cpp/anonymous-class-types.md b/docs/cpp/anonymous-class-types.md index 591f8492676..2e26ebc728b 100644 --- a/docs/cpp/anonymous-class-types.md +++ b/docs/cpp/anonymous-class-types.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Anonymous Class Types" title: "Anonymous Class Types" -ms.date: "11/04/2016" +description: "Learn more about: Anonymous Class Types" +ms.date: 11/04/2016 helpviewer_keywords: ["class types [C++], anonymous", "anonymous class types"] -ms.assetid: 9ba667b2-8c2a-4c29-82a6-fa120b9233c8 --- # Anonymous Class Types @@ -42,7 +41,7 @@ In the preceding code, `iValue` can be accessed using the object member-selectio int i = ptv.iValue; ``` -Anonymous classes are subject to certain restrictions. (For more information about anonymous unions, see [Unions](../cpp/unions.md).) Anonymous classes: +Anonymous classes are subject to certain restrictions. For more information about anonymous unions, see [Unions](../cpp/unions.md). Anonymous classes: - Cannot have a constructor or destructor. diff --git a/docs/cpp/argument-passing-and-naming-conventions.md b/docs/cpp/argument-passing-and-naming-conventions.md index b7ec0825474..11dfa80a2e9 100644 --- a/docs/cpp/argument-passing-and-naming-conventions.md +++ b/docs/cpp/argument-passing-and-naming-conventions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Argument Passing and Naming Conventions" title: "Argument Passing and Naming Conventions" -ms.date: "12/17/2018" +description: "Learn more about: Argument Passing and Naming Conventions" +ms.date: 12/17/2018 helpviewer_keywords: ["argument passing [C++], conventions", "arguments [C++], widening", "coding conventions, arguments", "arguments [C++], passing", "registers, return values", "thiscall keyword [C++]", "naming conventions [C++], arguments", "arguments [C++], naming", "passing arguments [C++], conventions", "conventions [C++], argument names"] -ms.assetid: de468979-eab8-4158-90c5-c198932f93b9 --- # Argument Passing and Naming Conventions @@ -32,6 +31,7 @@ The following calling conventions are supported by the Visual C/C++ compiler. |[__fastcall](../cpp/fastcall.md)|Callee|Stored in registers, then pushed on stack| |[__thiscall](../cpp/thiscall.md)|Callee|Pushed on stack; **`this`** pointer stored in ECX| |[__vectorcall](../cpp/vectorcall.md)|Callee|Stored in registers, then pushed on stack in reverse order (right to left)| +|[__preserve_none](../cpp/preserve-none.md)|Callee|Stored in registers only| For related information, see [Obsolete Calling Conventions](../cpp/obsolete-calling-conventions.md). diff --git a/docs/cpp/arrays-cpp.md b/docs/cpp/arrays-cpp.md index 941b90493e9..48563141ee0 100644 --- a/docs/cpp/arrays-cpp.md +++ b/docs/cpp/arrays-cpp.md @@ -3,11 +3,10 @@ title: "Arrays (C++)" description: "Learn how to declare and use the native array type in the standard C++ programming language." ms.date: 11/08/2020 helpviewer_keywords: ["declaring arrays [C++], about declaring arrays", "multidimensional arrays [C++]", "arrays [C++]"] -ms.assetid: 3f5986aa-485c-4ba4-9502-67e2ef924238 --- # Arrays (C++) -An array is a sequence of objects of the same type that occupy a contiguous area of memory. Traditional C-style arrays are the source of many bugs, but are still common, especially in older code bases. In modern C++, we strongly recommend using [std::vector](../standard-library/vector-class.md) or [std::array](../standard-library/array-class-stl.md) instead of C-style arrays described in this section. Both of these standard library types store their elements as a contiguous block of memory. However, they provide much greater type safety, and support iterators that are guaranteed to point to a valid location within the sequence. For more information, see [Containers](../standard-library/stl-containers.md). +An array is a sequence of objects of the same type that occupy a contiguous area of memory. Traditional C-style arrays are the source of many bugs, but are still common, especially in older code bases. In modern C++, we strongly recommend using [`std::vector`](../standard-library/vector-class.md) or [`std::array`](../standard-library/array-class-stl.md) instead of C-style arrays described in this section. Both of these standard library types store their elements as a contiguous block of memory. However, they provide greater type safety, and support iterators that are guaranteed to point to a valid location within the sequence. For more information, see [Containers](../standard-library/stl-containers.md). ## Stack declarations @@ -52,7 +51,6 @@ You may require an array that's too large to allocate on the stack, or whose siz The following example shows how to define an array on the heap at run time. It shows how to access the array elements using the subscript operator and by using pointer arithmetic: ```cpp - void do_something(size_t size) { // Declare an array of doubles to be allocated on the heap @@ -104,7 +102,6 @@ int main() { do_something(108); } - ``` ## Initializing arrays @@ -123,7 +120,7 @@ You can initialize an array in a loop, one element at a time, or in a single sta ## Passing arrays to functions -When an array is passed to a function, it's passed as a pointer to the first element, whether it's a stack-based or heap-based array. The pointer contains no additional size or type information. This behavior is called *pointer decay*. When you pass an array to a function, you must always specify the number of elements in a separate parameter. This behavior also implies that the array elements aren't copied when the array gets passed to a function. To prevent the function from modifying the elements, specify the parameter as a pointer to **`const`** elements. +When an array is passed to a function, it's passed as a pointer to the first element, whether it's a stack-based or heap-based array. The pointer contains no other size or type information. This behavior is called *pointer decay*. When you pass an array to a function, you must always specify the number of elements in a separate parameter. This behavior also implies that the array elements aren't copied when the array gets passed to a function. To prevent the function from modifying the elements, specify the parameter as a pointer to **`const`** elements. The following example shows a function that accepts an array and a length. The pointer points to the original array, not a copy. Because the parameter isn't **`const`**, the function can modify the array elements. @@ -164,8 +161,9 @@ int i2[5][7]; It specifies an array of type **`int`**, conceptually arranged in a two-dimensional matrix of five rows and seven columns, as shown in the following figure: -![Conceptual layout of a multi dimensional array.](../cpp/media/vc38rc1.gif)
-Conceptual layout of a multi-dimensional array +:::image type="complex" source="../cpp/media/vc38rc1.gif" alt-text="Conceptual layout of a multidimensional array."::: +The image is a grid 7 cells wide and 5 cells high. Each cell contains the index of the cell. The first cell index is labeled 0,0. The next cell in that row is 0,1 and so on to the last cell in that row which is 0,6. The next row starts with the index 1,0. The cell after that has an index of 1,1. The last cell in that row is 1,6. This pattern repeats until the last row, which starts with the index 4,0. The last cell in the last row has an index of 4,6. +:::image-end::: You can declare multidimensioned arrays that have an initializer list (as described in [Initializers](../cpp/initializers.md)). In these declarations, the constant expression that specifies the bounds for the first dimension can be omitted. For example: @@ -359,4 +357,4 @@ szError1 = psz; ## See also -[std::array](../standard-library/array-class-stl.md) +[`std::array`](../standard-library/array-class-stl.md) diff --git a/docs/cpp/assignment-operators.md b/docs/cpp/assignment-operators.md index 5e59a236b0c..d03022b7bda 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 2b23619f7ed..5e6cfc32fc0 100644 --- a/docs/cpp/attributes.md +++ b/docs/cpp/attributes.md @@ -1,13 +1,16 @@ --- -description: "Learn more about: Attributes in C++" title: "Attributes in C++" -ms.date: 04/27/2022 +description: "Learn more about: Attributes in C++" +f1_keywords: ["deprecated", "noreturn", "carries_dependency", "fallthrough", "nodiscard", "maybe_unused", "likely", "unlikely", "gsl::suppress", "msvc::disable", "msvc::enable", "msvc::flatten", "msvc::forceinline", "msvc::forceinline_calls", "msvc::intrinsic", "msvc::noinline", "msvc::noinline_calls", "msvc::no_tls_guard", "msvc::musttail"] +helpviewer_keywords: ["deprecated", "noreturn", "carries_dependency", "fallthrough", "nodiscard", "maybe_unused", "likely", "unlikely", "gsl::suppress", "msvc::disable", "msvc::enable", "msvc::flatten", "msvc::forceinline", "msvc::forceinline_calls", "msvc::intrinsic", "msvc::noinline", "msvc::noinline_calls", "msvc::no_tls_guard", "msvc::musttail"] +ms.date: 05/15/2026 --- + # Attributes in C++ The C++ Standard defines a common set of attributes. It also allows compiler vendors to define their own attributes within a vendor-specific namespace. However, compilers are only required to recognize the attributes defined in the standard. -In some cases, standard attributes overlap with compiler-specific `__declspec` parameters. In Microsoft C++, you can use the `[[deprecated]]` attribute instead of using `__declspec(deprecated)`. The `[[deprecated]]` attribute is recognized by any conforming compiler. For all other `__declspec` parameters such as `dllimport` and `dllexport`, so far there's no attribute equivalent, so you must continue to use `__declspec` syntax. Attributes don't affect the type system, and they don’t change the meaning of a program. Compilers ignore attribute values they don't recognize. +In some cases, standard attributes overlap with compiler-specific `__declspec` parameters. In Microsoft C++, you can use the `[[deprecated]]` attribute instead of using `__declspec(deprecated)`. The `[[deprecated]]` attribute is recognized by any conforming compiler. For all other `__declspec` parameters such as `dllimport` and `dllexport`, so far there's no attribute equivalent, so you must continue to use `__declspec` syntax. Attributes don't affect the type system, and they don't change the meaning of a program. Compilers ignore attribute values they don't recognize. **Visual Studio 2017 version 15.3 and later** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later): In the scope of an attribute list, you can specify the namespace for all names with a single **`using`** introducer: @@ -18,7 +21,7 @@ void g() { } ``` -## C++ Standard Attributes +## C++ standard attributes In C++11, attributes provide a standardized way to annotate C++ constructs (including but not limited to classes, functions, variables, and blocks) with additional information. Attributes may or may not be vendor-specific. A compiler can use this information to generate informational messages, or to apply special logic when compiling the attributed code. The compiler ignores any attributes that it doesn't recognize, which means you can't define your own custom attributes using this syntax. Attributes are enclosed by double square brackets: @@ -27,58 +30,258 @@ In C++11, attributes provide a standardized way to annotate C++ constructs (incl void Foo(int); ``` -Attributes represent a standardized alternative to vendor-specific extensions such as `#pragma` directives, `__declspec()` (Visual C++), or `__attribute__` (GNU). However, you'll still need to use the vendor-specific constructs for most purposes. The standard currently specifies the following attributes that a conforming compiler should recognize: +Attributes represent a standardized alternative to vendor-specific extensions such as `#pragma` directives, `__declspec()` (Visual C++), or `__attribute__` (GNU). However, you'll still need to use the vendor-specific constructs for most purposes. The standard currently specifies the following attributes that a conforming compiler should recognize. -- `[[noreturn]]` Specifies that a function never returns; in other words it always throws an exception. The compiler can adjust its compilation rules for `[[noreturn]]` entities. +### `[[carries_dependency]]` -- `[[carries_dependency]]` Specifies that the function propagates data dependency ordering for thread synchronization. The attribute can be applied to one or more parameters, to specify that the passed-in argument carries a dependency into the function body. The attribute can be applied to the function itself, to specify that the return value carries a dependency out of the function. The compiler can use this information to generate more efficient code. +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:** Specifies that a function isn't intended for use. Or, that it might not exist in future versions of a library interface. The compiler can use this attribute to generate an informational message when client code attempts to call the function. `[[deprecated]]` can be applied to declaration of a class, a typedef-name, a variable, a non-static data member, a function, a namespace, an enumeration, an enumerator, or a template specialization. +### `[[deprecated]]` -- `[[fallthrough]]` **Visual Studio 2017 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) The `[[fallthrough]]` attribute can be used in the context of [`switch`](switch-statement-cpp.md) statements as a hint to the compiler (or anyone reading the code) that the fallthrough behavior is intended. The Microsoft C++ compiler currently doesn't warn on fallthrough behavior, so this attribute has no effect compiler behavior. +**Visual Studio 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). -- `[[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: +### `[[fallthrough]]` - ```cpp - [[nodiscard]] - int foo(int i) { return i * i; } +**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. - int main() - { - foo(42); //warning C4834: discarding return value of function with 'nodiscard' attribute - return 0; - } - ``` +### `[[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.) 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. +### `[[maybe_unused]]` -- `[[likely]]` **Visual Studio 2019 version 16.6 and later:** (Available with [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) and later.) 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 re-ordering optimization is not yet implemented for this attribute. +**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. -- `[[unlikely]]` **Visual Studio 2019 version 16.6 and later:** (Available with [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) and later.) Specifies a hint to the compiler that the code path for the attributed label or statement is less likely to execute than alternatives. In the Microsoft compiler, the `[[unlikely]]` attribute marks blocks as "cold code", which decrements an internal optimization score. The score is decremented more when optimizing for size, and not as much when optimizing for speed. The net score affects the likelihood of inlining, loop unrolling, and vectorizing optimizations. The block re-ordering optimization is not yet implemented for this attribute. +### `[[nodiscard]]` + +**Visual Studio 2017 version 15.3 and later:** (Available with [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) and later.) Specifies that a function's return value isn't intended to be discarded. Raises warning [C4834](../error-messages/compiler-warnings/c4834.md), as shown in this example: + +```cpp +[[nodiscard]] +int foo(int i) { return i * i; } + +int main() +{ + foo(42); //warning C4834: discarding return value of function with 'nodiscard' attribute + return 0; +} +``` + +### `[[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. + +### `[[unlikely]]` + +**Visual Studio 2019 version 16.6 and later:** (Available with [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) and later.) The `[[unlikely]]` attribute specifies a hint to the compiler that the code path for the attributed label or statement is less likely to execute than alternatives. In the Microsoft compiler, the `[[unlikely]]` attribute marks blocks as "cold code", which decrements an internal optimization score. The score is decremented more when optimizing for size, and not as much when optimizing for speed. The net score affects the likelihood of inlining, loop unrolling, and vectorizing optimizations. The block reordering optimization isn't implemented yet for this attribute. ## Microsoft-specific attributes -- `[[gsl::suppress(rules)]]` This Microsoft-specific attribute is used for suppressing warnings from checkers that enforce [Guidelines Support Library (GSL)](https://github.com/Microsoft/GSL) rules in code. For example, consider this code snippet: +### `[[gsl::suppress( [, justification: ])]]` + +This Microsoft-specific attribute, introduced in Visual Studio 2022 version 17.14, suppresses warnings from checkers that enforce [Guidelines Support Library (GSL)](https://github.com/Microsoft/GSL) rules. The attribute can be applied to a statement, a block, or a declaration. It's only available for C++. For C code, use [`#pragma warning(suppress)`](../preprocessor/warning.md) instead. + +`` 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 appears in the Static Analysis Results Interchange Format ([SARIF](https://sarif.info/)) output when the `/analyze:log:includesuppressed` option is specified. Its value is a UTF-8 encoded narrow string literal. To generate a SARIF file, use the `/analyze:log:format:sarif` compiler option. - ```cpp - int main() +Example: + +```cpp +int main() +{ + int arr[10]; // GSL warning C26494 will be fired + int* p = arr; // GSL warning C26485 will be fired + [[gsl::suppress("bounds.1", justification: "This attribute suppresses Bounds rule #1")]] { - int arr[10]; // GSL warning C26494 will be fired - int* p = arr; // GSL warning C26485 will be fired - [[gsl::suppress(bounds.1)]] // This attribute suppresses Bounds rule #1 + int* q = p + 1; // GSL warning C26481 suppressed + p = q--; // GSL warning C26481 suppressed + } +} +``` + +This example raises these warnings: + +- [C26494](../code-quality/c26494.md) (Type Rule 5: Always initialize an object.) +- [C26485](../code-quality/c26485.md) (Bounds Rule 3: No array to pointer decay.) +- [C26481](../code-quality/c26481.md) (Bounds Rule 1: Don't use pointer arithmetic. Use span instead.) + +The first two warnings occur 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. + +**Choosing between `#pragma warning` and `[[gsl::suppress]]`** + +Both `#pragma warning(suppress)` and `[[gsl::suppress]]` offer fine-grained control over warning suppression: +- `[[gsl::suppress]]` only suppresses warnings emitted by Microsoft C++ Code Analysis. Use it with the C++ Core Guidelines checks, which can be applied to a scope or a specific declaration. +- `#pragma warning(suppress)` can be used for any compiler warning. It’s useful when you need to suppress a warning in a specific code block without altering the code’s structure significantly. + +Whenever possible, use `[[gsl::suppress]]` for suppressing Microsoft C++ Code Analysis warnings. + +### `[[msvc::disable(feature:APX)]]` + +The `[[msvc::disable(feature:APX)]]` attribute, introduced in [MSVC Build Tools version 14.51](../overview/what-s-new-for-msvc.md#whats-new-for-msvc-build-tools-version-1451) (Visual Studio version 18.6.0), is an x64-only Microsoft-specific attribute that disables Intel Advanced Performance Extensions (APX) instruction generation for a specific function. When applied to a function declaration or definition, it prevents the compiler from emitting APX instructions in that function's body, even if APX is globally enabled via the `/feature:APX` compiler option. Other functions in the same translation unit continue to use APX instructions unless they are similarly attributed. If a function with `[[msvc::disable(feature:APX)]]` calls inlined functions, the inlined code is also compiled without APX instructions. + +#### Example + +```cpp +// The following shows how to disable APX instructions for specific functions, +// even when APX is enabled globally with /feature:APX +​int test(int argc) +{ + auto lambda = + [] + [[msvc::disable(feature:APX)]] + (int argc) { - int* q = p + 1; // GSL warning C26481 suppressed - p = q--; // GSL warning C26481 suppressed - } + return argc + 42; + }; + return lambda(argc); +} + +[[msvc::disable(feature:APX)]] +int test2(int x) +{ + return x + 42; +} +``` + +### `[[msvc::enable(feature:APX)]]` + +The `[[msvc::enable(feature:APX)]]` attribute, introduced in [MSVC Build Tools version 14.51](../overview/what-s-new-for-msvc.md#whats-new-for-msvc-build-tools-version-1451) (Visual Studio version 18.6.0), is an x64-only Microsoft-specific attribute that enables Intel Advanced Performance Extensions (APX) instruction generation for a specific function. When applied to a function declaration or definition, it allows the compiler to emit APX instructions in that function's body, even when APX is not globally enabled. This provides per-function opt-in to APX features without requiring `/arch:APX` for the entire translation unit. If a function with `[[msvc::enable(feature:APX)]]` has calls that are inlined into it, the inlined code is also compiled with APX instructions. + +#### `[[msvc::enable(feature:APX)]]` example + +```cpp +// The following shows how to enable APX instructions for specific functions, +// even when APX isn't enabled globally with /feature:APX + +​int test(int argc) +{ + auto lambda = + [] + [[msvc::enable(feature:APX)]] + (int argc) + { + return argc + 42; + }; + return lambda(argc); +} + +[[msvc::enable(feature:APX), msvc::noinline]] +int test2(int x) +{ + return x + 42; +} +``` + +### `[[msvc::flatten]]` + +The Microsoft-specific attribute `[[msvc::flatten]]` is 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 `[[msvc::intrinsic]]` attribute has three constraints on the function it's applied to: + +- The function can't be recursive; its body must only have a return statement with a `static_cast` from the parameter type to the return type. +- The function can only accept a single parameter. +- The **`/permissive-`** compiler option is required. (The **`/std:c++20`** and later options imply **`/permissive-`** by default.) + +The Microsoft-specific `[[msvc::intrinsic]]` attribute tells the compiler to inline a metafunction that acts as a named cast from the parameter type to the return type. When the attribute is present on a function definition, the compiler replaces all calls to that function with a simple cast. The `[[msvc::intrinsic]]` attribute is available in Visual Studio 2022 version 17.5 preview 2 and later versions. This attribute applies only to the specific function that follows it. + +#### Example + +In this sample code, the `[[msvc::intrinsic]]` attribute applied to the `my_move` function makes the compiler replace calls to the function with the inlined static cast in its body: + +```cpp +template +[[msvc::intrinsic]] T&& my_move(T&& t) { return static_cast(t); } + +void f() { + int i = 0; + i = my_move(i); +} +``` + +### `[[msvc::musttail]]` + +The `[[msvc::musttail]]` attribute, introduced in [MSVC Build Tools version 14.50](../overview/what-s-new-for-msvc.md#whats-new-for-msvc-build-tools-version-1450), is an experimental x64-only Microsoft-specific attribute that enforces tail-call optimization. When applied to a qualifying return statement, it instructs the compiler to emit the call as a tail call. If the compiler can't emit the tail call, it produces a compilation error. The `[[msvc::musttail]]` attribute enforces a tail call instead of inlining the function. + +`[[msvc::musttail]]` requirements: +- The caller and callee must have matching return types. +- The calling conventions must be compatible. +- The tail call must be the final action in the calling function. +- The callee can't use more stack space than the calling function. +- If more than four integer parameters are passed, the calling function must allocate enough stack space for the other arguments. +- Compile with `/O2` or `/O2 /GL` optimization level. + +#### Example + +Tail calls are a compiler optimization that's possible when a function call is the last action performed before returning. Instead of creating a new stack frame to call the function, the current function's stack frame is reused. This reduces stack usage and improves performance—especially in recursive scenarios. + +In the following code, the `[[msvc::musttail]]` attribute applied to `return increment(x)` causes control to transfer directly to `increment`. When `increment` reaches the `return x+1;` statement, its result is provided directly to the caller of `incrementIfPositive`, that is `main`. This replaces inlining `increment` into `incrementIfPositive` or calling `increment` from `incrementIfPositive` and returning to `incrementIfPositive` before returning to `main`. The tail call optimization eliminates the need for `incrementIfPositive` to regain control after `increment` finishes. This is a performance optimization that reduces stack usage, especially useful in recursive scenarios. + +```cpp +// compile with /O2 +#include + +int increment(int x) +{ + return x + 1; +} + +int incrementIfPositive(int x) +{ + if (x > 0) + { + [[msvc::musttail]] + return increment(x); + } + return -1; +} + +int main() +{ + int result = incrementIfPositive(42); + if (result < 0) + { + return -1; } - ``` - The example raises these warnings: + std::cout << result; // outputs 43 + return 0; +} +``` + +### `[[msvc::noinline]]` + +When placed before a function declaration, the Microsoft-specific attribute `[[msvc::noinline]]` has the same meaning as `__declspec(noinline)`. - - 26494 (Type Rule 5: Always initialize an object.) +### `[[msvc::noinline_calls]]` - - 26485 (Bounds Rule 3: No array to pointer decay.) +The Microsoft-specific attribute `[[msvc::noinline_calls]]` has the same usage as `[[msvc::forceinline_calls]]`. It can be placed before any statement or block. Rather than force-inlining all calls in that block, it has the effect of turning off inlining for the scope it's applied to. - - 26481 (Bounds Rule 1: Don't use pointer arithmetic. Use span instead.) +### `[[msvc::no_tls_guard]]` - The first two warnings fire when you compile this code with the CppCoreCheck code analysis tool installed and activated. But the third warning doesn't fire because of the attribute. You can suppress the entire bounds profile by writing `[[gsl::suppress(bounds)]]` without including a specific rule number. The C++ Core Guidelines are designed to help you write better and safer code. The suppress attribute makes it easy to turn off the warnings when they aren't wanted. +The Microsoft-specific `[[msvc::no_tls_guard]]` attribute disables checks for initialization on first access to thread-local variables in DLLs. The checks are enabled by default in code built using Visual Studio 2019 version 16.5 and later versions. This attribute applies only to the specific variable that follows it. To disable checks globally, use the [`/Zc:tlsGuards-`](../build/reference/zc-tlsguards.md) compiler option. diff --git a/docs/cpp/auto-cpp.md b/docs/cpp/auto-cpp.md index eefb9773b7d..ef1288e32f9 100644 --- a/docs/cpp/auto-cpp.md +++ b/docs/cpp/auto-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: `auto` (C++)" title: "auto (C++)" -ms.date: "12/10/2019" +ms.date: 09/27/2022 f1_keywords: ["auto_CPP", "auto"] helpviewer_keywords: ["auto keyword [C++]"] ms.assetid: e9d495d7-601c-4547-b897-998389a311f4 @@ -25,9 +25,9 @@ The **`auto`** keyword directs the compiler to use the initialization expression We recommend that you use the **`auto`** keyword for most situations—unless you really want a conversion—because it provides these benefits: -- **Robustness:** If the expression’s type is changed—this includes when a function return type is changed—it just works. +- **Robustness:** If the expression's type is changed—including when a function return type is changed—it just works. -- **Performance:** You’re guaranteed that there will be no conversion. +- **Performance:** You're guaranteed that there's no conversion. - **Usability:** You don't have to worry about type name spelling difficulties and typos. @@ -35,9 +35,9 @@ We recommend that you use the **`auto`** keyword for most situations—unless yo Conversion cases in which you might not want to use **`auto`**: -- When you want a specific type and nothing else will do. +- You want a specific type and nothing else will do. -- Expression template helper types—for example, `(valarray+valarray)`. +- In expression template helper types—for example, `(valarray+valarray)`. To use the **`auto`** keyword, use it instead of a type to declare a variable, and specify an initialization expression. In addition, you can modify the **`auto`** keyword by using specifiers and declarators such as **`const`**, **`volatile`**, pointer (**`*`**), reference (**`&`**), and rvalue reference (**`&&`**). The compiler evaluates the initialization expression and then uses that information to deduce the type of the variable. @@ -45,14 +45,14 @@ The **`auto`** initialization expression can take several forms: - Universal initialization syntax, such as `auto a { 42 };`. - Assignment syntax, such as `auto b = 0;`. -- Universal assignment syntax, which combines the two previous forms, such as `auto c = { 3.14156 };`. +- Universal assignment syntax, which combines the two previous forms, such as `auto c = { 3.14159 };`. - Direct initialization, or constructor-style syntax, such as `auto d( 1.41421f );`. For more information, see [Initializers](../cpp/initializers.md) and the code examples later in this document. When **`auto`** is used to declare the loop parameter in a range-based **`for`** statement, it uses a different initialization syntax, for example `for (auto& i : iterable) do_action(i);`. For more information, see [Range-based `for` Statement (C++)](../cpp/range-based-for-statement-cpp.md). -The **`auto`** keyword is a placeholder for a type, but it is not itself a type. Therefore, the **`auto`** keyword cannot be used in casts or operators such as [`sizeof`](../cpp/sizeof-operator.md) and (for C++/CLI) [`typeid`](../extensions/typeid-cpp-component-extensions.md). +The **`auto`** keyword is a placeholder for a type, but it isn't itself a type. Therefore, the **`auto`** keyword can't be used in casts or operators such as [`sizeof`](../cpp/sizeof-operator.md) and (for C++/CLI) [`typeid`](../extensions/typeid-cpp-component-extensions.md). ## Usefulness @@ -62,11 +62,11 @@ You can also use **`auto`** to declare and initialize a variable to a lambda exp ## Trailing Return Types -You can use **`auto`**, together with the **`decltype`** type specifier, to help write template libraries. Use **`auto`** and **`decltype`** to declare a template function whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a template function that wraps a call to another function, and then returns whatever is the return type of that other function. For more information, see [`decltype`](../cpp/decltype-cpp.md). +You can use **`auto`**, together with the **`decltype`** type specifier, to help write template libraries. Use **`auto`** and **`decltype`** to declare a function template whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a function template that wraps a call to another function, and then returns whatever is the return type of that other function. For more information, see [`decltype`](../cpp/decltype-cpp.md). ## References and cv-qualifiers -Note that using **`auto`** drops references, **`const`** qualifiers, and **`volatile`** qualifiers. Consider the following example: +Using **`auto`** drops references, **`const`** qualifiers, and **`volatile`** qualifiers. Consider the following example: ```cpp // cl.exe /analyze /EHsc /W4 @@ -88,7 +88,7 @@ int main( ) } ``` -In the previous example, myAuto is an **`int`**, not an **`int`** reference, so the output is `11 11`, not `11 12` as would be the case if the reference qualifier had not been dropped by **`auto`**. +In the previous example, myAuto is an **`int`**, not an **`int`** reference, so the output is `11 11`, not `11 12` as would be the case if the reference qualifier hadn't been dropped by **`auto`**. ## Type deduction with braced initializers (C++14) @@ -119,21 +119,21 @@ int main() } ``` -## Restrictions and Error Messages +## Restrictions and error messages The following table lists the restrictions on the use of the **`auto`** keyword, and the corresponding diagnostic error message that the compiler emits. -|Error number|Description| -|------------------|-----------------| -|[C3530](../error-messages/compiler-errors-2/compiler-error-c3530.md)|The **`auto`** keyword cannot be combined with any other type-specifier.| -|[C3531](../error-messages/compiler-errors-2/compiler-error-c3531.md)|A symbol that is declared with the **`auto`** keyword must have an initializer.| -|[C3532](../error-messages/compiler-errors-2/compiler-error-c3532.md)|You incorrectly used the **`auto`** keyword to declare a type. For example, you declared a method return type or an array.| -|[C3533](../error-messages/compiler-errors-2/compiler-error-c3533.md), [C3539](../error-messages/compiler-errors-2/compiler-error-c3539.md)|A parameter or template argument cannot be declared with the **`auto`** keyword.| -|[C3535](../error-messages/compiler-errors-2/compiler-error-c3535.md)|A method or template parameter cannot be declared with the **`auto`** keyword.| -|[C3536](../error-messages/compiler-errors-2/compiler-error-c3536.md)|A symbol cannot be used before it is initialized. In practice, this means that a variable cannot be used to initialize itself.| -|[C3537](../error-messages/compiler-errors-2/compiler-error-c3537.md)|You cannot cast to a type that is declared with the **`auto`** keyword.| -|[C3538](../error-messages/compiler-errors-2/compiler-error-c3538.md)|All the symbols in a declarator list that is declared with the **`auto`** keyword must resolve to the same type. For more information, see [Declarations and Definitions](declarations-and-definitions-cpp.md).| -|[C3540](../error-messages/compiler-errors-2/compiler-error-c3540.md), [C3541](../error-messages/compiler-errors-2/compiler-error-c3541.md)|The [sizeof](../cpp/sizeof-operator.md) and [typeid](../extensions/typeid-cpp-component-extensions.md) operators cannot be applied to a symbol that is declared with the **`auto`** keyword.| +| Error number | Description | +|--|--| +| [C3530](../error-messages/compiler-errors-2/compiler-error-c3530.md) | The **`auto`** keyword can't be combined with any other type-specifier. | +| [C3531](../error-messages/compiler-errors-2/compiler-error-c3531.md) | A symbol that is declared with the **`auto`** keyword must have an initializer. | +| [C3532](../error-messages/compiler-errors-2/compiler-error-c3532.md) | You incorrectly used the **`auto`** keyword to declare a type. For example, you declared a method return type or an array. | +| [C3533](../error-messages/compiler-errors-2/compiler-error-c3533.md), [C3539](../error-messages/compiler-errors-2/compiler-error-c3539.md) | A parameter or template argument can't be declared with the **`auto`** keyword. | +| [C3535](../error-messages/compiler-errors-2/compiler-error-c3535.md) | A method or template parameter can't be declared with the **`auto`** keyword. | +| [C3536](../error-messages/compiler-errors-2/compiler-error-c3536.md) | A symbol can't be used before it's initialized. In practice, it means that a variable can't be used to initialize itself. | +| [C3537](../error-messages/compiler-errors-2/compiler-error-c3537.md) | You can't cast to a type that is declared with the **`auto`** keyword. | +| [C3538](../error-messages/compiler-errors-2/compiler-error-c3538.md) | All the symbols in a declarator list that is declared with the **`auto`** keyword must resolve to the same type. For more information, see [Declarations and Definitions](declarations-and-definitions-cpp.md). | +| [C3540](../error-messages/compiler-errors-2/compiler-error-c3540.md), [C3541](../error-messages/compiler-errors-2/compiler-error-c3541.md) | The [sizeof](../cpp/sizeof-operator.md) and [typeid](../extensions/typeid-cpp-component-extensions.md) operators can't be applied to a symbol that is declared with the **`auto`** keyword. | ## Examples @@ -221,12 +221,12 @@ int main() ## See also -[Keywords](../cpp/keywords-cpp.md)
-[`/Zc:auto` (Deduce Variable Type)](../build/reference/zc-auto-deduce-variable-type.md)
-[`sizeof` Operator](../cpp/sizeof-operator.md)
-[`typeid`](../extensions/typeid-cpp-component-extensions.md)
-[`operator new`](new-operator-cpp.md)
-[Declarations and Definitions](declarations-and-definitions-cpp.md)
-[Examples of Lambda Expressions](../cpp/examples-of-lambda-expressions.md)
-[Initializers](../cpp/initializers.md)
+[Keywords](../cpp/keywords-cpp.md)\ +[`/Zc:auto` (Deduce variable type)](../build/reference/zc-auto-deduce-variable-type.md)\ +[`sizeof` operator](../cpp/sizeof-operator.md)\ +[`typeid`](../extensions/typeid-cpp-component-extensions.md)\ +[`operator new`](new-operator-cpp.md)\ +[Declarations and definitions](declarations-and-definitions-cpp.md)\ +[Examples of lambda expressions](../cpp/examples-of-lambda-expressions.md)\ +[Initializers](../cpp/initializers.md)\ [`decltype`](../cpp/decltype-cpp.md) diff --git a/docs/cpp/based-grammar.md b/docs/cpp/based-grammar.md index 292565d4170..8797b6baa91 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/basic-concepts-cpp.md b/docs/cpp/basic-concepts-cpp.md index 7102a6a9f74..a60b27fef42 100644 --- a/docs/cpp/basic-concepts-cpp.md +++ b/docs/cpp/basic-concepts-cpp.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Basic Concepts (C++)" -title: "Basic Concepts (C++)" +title: "Basic Concepts (C++)" +description: "Learn more about: Basic Concepts (C++)" ms.custom: "index-page" -ms.date: "12/11/2019" +ms.date: 12/11/2019 helpviewer_keywords: ["C++, basic language concepts"] -ms.assetid: 961801e6-2ffd-4bf1-bb71-7f55e48d9c79 --- -# Basic Concepts (C++) +# Basic Concepts (C++) This section explains concepts that are critical to understanding C++. C programmers will be familiar with many of these concepts, but there are some subtle differences that can cause unexpected program results. The following topics are included: diff --git a/docs/cpp/bitwise-exclusive-or-operator-hat.md b/docs/cpp/bitwise-exclusive-or-operator-hat.md index 62b113a0856..b6755b4b065 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 d148fa4bae0..5e759dc2e90 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 821fbad22a6..1439e29ff97 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 565b248630a..801be55d0ab 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 a6f866c4468..ee3ccbc4ab2 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 4 Specifications](https://github.com/microsoft/proxy/tree/main/docs/spec#readme) + [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 20c8157beb1..1a74c493987 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 3b18753f079..4a4e7703852 100644 --- a/docs/cpp/char-wchar-t-char16-t-char32-t.md +++ b/docs/cpp/char-wchar-t-char16-t-char32-t.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: char, wchar_t, char8_t, char16_t, char32_t" title: "char, wchar_t, char8_t, char16_t, char32_t" +description: "Learn more about: 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`](../standard-library/basic-string-class.md) 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`](../standard-library/sstream-typedefs.md#stringstream) and [`std::cout`](../standard-library/iostream.md#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 54f6191224d..3d97b74bea9 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 9799e84fc01..4d0d7b7ce66 100644 --- a/docs/cpp/class-templates.md +++ b/docs/cpp/class-templates.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Class Templates" title: "Class Templates" +description: "Learn more about: Class Templates" ms.date: 06/30/2022 helpviewer_keywords: ["classes [C++], operating on type", "class templates", "templates, class templates"] -ms.assetid: 633a53c8-24ee-4c23-8c88-e7c3cb0b7ac3 --- # Class Templates @@ -28,15 +27,15 @@ public: template< class T, int i > MyStack< T, i >::MyStack( void ) { -}; +} template< class T, int i > void MyStack< T, i >::push( const T item ) { -}; +} template< class T, int i > T& MyStack< T, i >::pop( void ) { -}; +} int main() { @@ -83,7 +82,6 @@ using namespace std; class X { - template struct Y { diff --git a/docs/cpp/clrcall.md b/docs/cpp/clrcall.md index 63c3326e482..c368132c787 100644 --- a/docs/cpp/clrcall.md +++ b/docs/cpp/clrcall.md @@ -20,7 +20,7 @@ When `/clr` (not `/clr:pure` or `/clr:safe`) is used and **__clrcall** is not us [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) implies that all functions and function pointers are **__clrcall** and the compiler will not permit a function inside the compiland to be marked anything other than **__clrcall**. When **/clr:pure** is used, **__clrcall** can only be specified on function pointers and external declarations. -You can directly call **__clrcall** functions from existing C++ code that was compiled by using **/clr** as long as that function has an MSIL implementation. **__clrcall** functions cannot be called directly from functions that have inline asm and call CPU-specific intrinisics, for example, even if those functions are compiled with `/clr`. +You can directly call **__clrcall** functions from existing C++ code that was compiled by using **/clr** as long as that function has an MSIL implementation. **__clrcall** functions cannot be called directly from functions that have inline asm and call CPU-specific intrinsics, for example, even if those functions are compiled with `/clr`. **__clrcall** function pointers are only meant to be used in the application domain in which they were created. Instead of passing **__clrcall** function pointers across application domains, use . For more information, see [Application Domains and Visual C++](../dotnet/application-domains-and-visual-cpp.md). @@ -38,7 +38,7 @@ int __clrcall Func1() { } // Func1 hasn't been used at this point (code has not been generated), -// so runtime returns the adddress of a stub to the function +// so runtime returns the address of a stub to the function int (__clrcall *pf)() = &Func1; // code calls the function, code generated at difference address diff --git a/docs/cpp/code-seg-declspec.md b/docs/cpp/code-seg-declspec.md index b4c26c8a031..888c24bbaf5 100644 --- a/docs/cpp/code-seg-declspec.md +++ b/docs/cpp/code-seg-declspec.md @@ -1,50 +1,48 @@ --- description: "Learn more about: code_seg (__declspec)" title: "code_seg (__declspec)" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["code_seg_cpp"] helpviewer_keywords: ["code_seg __declspec keyword"] ms.assetid: ad3c1105-15d3-4e08-b7b9-e4bd9d7b6aa0 --- -# code_seg (__declspec) +# `__declspec(code_seg)` **Microsoft Specific** -The **code_seg** declaration attribute names an executable text segment in the .obj file in which the object code for the function or class member functions will be stored. +The **`code_seg`** declaration attribute names an executable text segment in the *`.obj`* file in which the object code for the function or class member functions is stored. ## Syntax -``` -__declspec(code_seg("segname")) declarator -``` +> **`__declspec(code_seg("`***`segname`***`"))`** *`declarator`* ## Remarks The `__declspec(code_seg(...))` attribute enables the placement of code into separate named segments that can be paged or locked in memory individually. You can use this attribute to control the placement of instantiated templates and compiler-generated code. -A *segment* is a named block of data in an .obj file that is loaded into memory as a unit. A *text segment* is a segment that contains executable code. The term *section* is often used interchangeably with segment. +A *segment* is a named block of data in an *`.obj`* file that is loaded into memory as a unit. A *text segment* is a segment that contains executable code. The term *section* is often used interchangeably with segment. -Object code that's generated when `declarator` is defined is put in the text segment specified by `segname`, which is a narrow-string literal. The name `segname` does not have to be specified in a [section](../preprocessor/section.md) pragma before it can be used in a declaration. By default, when no `code_seg` is specified, object code is put in a segment named .text. A **code_seg** attribute overrides any existing [#pragma code_seg](../preprocessor/code-seg.md) directive. A **code_seg** attribute applied to a member function overrides any **code_seg** attribute applied to the enclosing class. +Object code that's generated when `declarator` is defined is put in the text segment specified by `segname`, which is a narrow-string literal. The name `segname` doesn't have to be specified in a [section](../preprocessor/section.md) pragma before it can be used in a declaration. By default, when no `code_seg` is specified, object code is put in a segment named `.text`. A **`code_seg`** attribute overrides any existing [#pragma code_seg](../preprocessor/code-seg.md) directive. A **`code_seg`** attribute applied to a member function overrides any **`code_seg`** attribute applied to the enclosing class. -If an entity has a **code_seg** attribute, all declarations and definitions of the same entity must have identical **code_seg** attributes. If a base-class has a **code_seg** attribute, derived classes must have the same attribute. +If an entity has a **`code_seg`** attribute, all declarations and definitions of the same entity must have identical **`code_seg`** attributes. If a base-class has a **`code_seg`** attribute, derived classes must have the same attribute. -When a **code_seg** attribute is applied to a namespace-scope function or a member function, the object code for that function is put in the specified text segment. When this attribute is applied to a class, all member functions of the class and nested classes—this includes compiler-generated special member functions—are put in the specified segment. Locally defined classes—for example, classes defined in a member function body—do not inherit the **code_seg** attribute of the enclosing scope. +When a **`code_seg`** attribute is applied to a namespace-scope function or a member function, the object code for that function is put in the specified text segment. When this attribute is applied to a class, all member functions of the class and nested classes—including compiler-generated special member functions—are put in the specified segment. Locally defined classes—for example, classes defined in a member function body—don't inherit the **`code_seg`** attribute of the enclosing scope. -When a **code_seg** attribute is applied to a template class or template function, all implicit specializations of the template are put in the specified segment. Explicit or partial specializations do not inherit the **code_seg** attribute from the primary template. You may specify the same or a different **code_seg** attribute on the specialization. A **code_seg** attribute can’t be applied to an explicit template instantiation. +When a **`code_seg`** attribute is applied to a class template or function template, all implicit specializations of the template are put in the specified segment. Explicit or partial specializations don't inherit the **`code_seg`** attribute from the primary template. You may specify the same or a different **`code_seg`** attribute on the specialization. A **`code_seg`** attribute can't be applied to an explicit template instantiation. -By default, compiler-generated code such as a special member function is put in the .text segment. The `#pragma code_seg` directive does not override this default. Use the **code_seg** attribute on the class, class template, or function template to control where compiler-generated code is put. +By default, compiler-generated code such as a special member function is put in the `.text` segment. The `#pragma code_seg` directive doesn't override this default. Use the **`code_seg`** attribute on the class, class template, or function template to control where compiler-generated code is put. -Lambdas inherit **code_seg** attributes from their enclosing scope. To specify a segment for a lambda, apply a **code_seg** attribute after the parameter-declaration clause and before any mutable or exception specification, any trailing return-type specification, and the lambda body. For more information, see [Lambda Expression Syntax](../cpp/lambda-expression-syntax.md). This example defines a lambda in a segment named PagedMem: +Lambdas inherit **`code_seg`** attributes from their enclosing scope. To specify a segment for a lambda, apply a **`code_seg`** attribute after the parameter-declaration clause and before any mutable or exception specification, any trailing return-type specification, and the lambda body. For more information, see [Lambda Expression Syntax](../cpp/lambda-expression-syntax.md). This example defines a lambda in a segment named PagedMem: ```cpp auto Sqr = [](int t) __declspec(code_seg("PagedMem")) -> int { return t*t; }; ``` -Be careful when you put specific member functions—especially virtual member functions—in different segments. If you define a virtual function in a derived class that resides in a paged segment when the base class method resides in a non-paged segment, other base class methods or user code may assume that invoking the virtual method will not trigger a page fault. +Be careful when you put specific member functions—especially virtual member functions—in different segments. Say you define a virtual function in a derived class that resides in a paged segment when the base class method resides in a non-paged segment. Other base class methods or user code may assume that invoking the virtual method won't trigger a page fault. ## Example -This example shows how a **code_seg** attribute controls segment placement when implicit and explicit template specialization is used: +This example shows how a **`code_seg`** attribute controls segment placement when implicit and explicit template specialization is used: ```cpp // code_seg.cpp @@ -100,5 +98,5 @@ int main() ## See also -[__declspec](../cpp/declspec.md)
+[`__declspec`](../cpp/declspec.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_1.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-ccomptr-and-ccomqiptr-instances_1.cpp index e8577af7f1e..dd50495388a 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 820b1d6cd63..3bcf58d97eb 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 af736b0495e..753367555e0 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 00000000000..f11f275deef --- /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 551c3f2f5b7..2c02d593fbd 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_1.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_1.cpp index 3ca09b621c1..838fe5a5607 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_1.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_1.cpp @@ -1,20 +1,43 @@ -unique_ptr SongFactory(const std::wstring& artist, const std::wstring& title) -{ - // Implicit move operation into the variable that stores the result. - return make_unique(artist, title); +// Compile with: cl /EHsc /std:c++17 + +#include +#include +#include + +struct Song { + std::string artist; + std::string title; + Song(const std::string& a, const std::string& t) : artist(a), title(t) { + std::cout << "Created: " << title << "\n"; + } + ~Song() { std::cout << "Destroyed: " << title << "\n"; } +}; + +// Returning a unique_ptr by value transfers ownership to the caller. +std::unique_ptr SongFactory(const std::string& artist, const std::string& title) { + return std::make_unique(artist, title); +} + +// Passing a unique_ptr by value transfers ownership to the function. +// The Song is automatically destroyed when the function exits. +void SingSong(std::unique_ptr song) { + std::cout << "Singing: " << song->title << " by " << song->artist << "\n"; } -void MakeSongs() -{ +int main() { // Create a new unique_ptr with a new object. - auto song = make_unique(L"Mr. Children", L"Namonaki Uta"); + auto song = std::make_unique("Mr. Children", "Namonaki Uta"); + std::cout << "song points to: " << song->title << "\n"; - // Use the unique_ptr. - vector titles = { song->title }; + // Move ownership from one unique_ptr to another. + std::unique_ptr song2 = std::move(song); + std::cout << "After move, song is " << (song ? "not null" : "null") << "\n"; + std::cout << "song2 points to: " << song2->title << "\n"; - // Move raw pointer from one unique_ptr to another. - unique_ptr song2 = std::move(song); + // Obtain unique_ptr from a factory function that returns by value. + auto song3 = SongFactory("Michael Jackson", "Beat It"); - // Obtain unique_ptr from function that returns by value. - auto song3 = SongFactory(L"Michael Jackson", L"Beat It"); + // Transfer ownership to a function. + SingSong(std::move(song3)); + std::cout << "After SingSong, song3 is " << (song3 ? "not null" : "null") << "\n"; } \ No newline at end of file diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_2.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_2.cpp index b1f6a067f95..862c0293cd8 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_2.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_2.cpp @@ -1,17 +1,32 @@ -void SongVector() -{ - vector> songs; - - // Create a few new unique_ptr instances - // and add them to vector using implicit move semantics. - songs.push_back(make_unique(L"B'z", L"Juice")); - songs.push_back(make_unique(L"Namie Amuro", L"Funky Town")); - songs.push_back(make_unique(L"Kome Kome Club", L"Kimi ga Iru Dake de")); - songs.push_back(make_unique(L"Ayumi Hamasaki", L"Poker Face")); +// Compile with: cl /EHsc /std:c++17 - // Pass by const reference when possible to avoid copying. - for (const auto& song : songs) - { - wcout << L"Artist: " << song->artist << L" Title: " << song->title << endl; - } +#include +#include +#include +#include + +struct Song { + std::string artist; + std::string title; + Song(const std::string& a, const std::string& t) : artist(a), title(t) {} +}; + +int main() { + std::vector> songs; + + // Create unique_ptr instances and add them to the vector + // using implicit move semantics. + songs.push_back(std::make_unique("B'z", "Juice")); + songs.push_back(std::make_unique("Namie Amuro", "Funky Town")); + songs.push_back(std::make_unique("Kome Kome Club", "Kimi ga Iru Dake de")); + songs.push_back(std::make_unique("Ayumi Hamasaki", "Poker Face")); + + // Pass by const reference to avoid copying. + // Passing by value causes a compile error because + // the unique_ptr copy constructor is deleted. + for (const auto& song : songs) { + std::cout << "Artist: " << song->artist + << " Title: " << song->title << "\n"; + } + // The unique_ptr instances in the vector are automatically destroyed when the vector goes out of scope at the end of main() } \ No newline at end of file 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 e7ad81c8d5a..35b67cc059c 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,18 +1,29 @@ +// Compile with: cl /EHsc /std:c++17 -class MyClass -{ -private: - // MyClass owns the unique_ptr. - unique_ptr factory; +#include +#include + +class Engine { public: + Engine() { std::cout << "Engine created\n"; } + ~Engine() { std::cout << "Engine destroyed\n"; } + void Run() { std::cout << "Engine running\n"; } +}; - // Initialize by using make_unique with ClassFactory default constructor. - MyClass() : factory (make_unique()) - { - } +class Car { +private: + // Car owns the unique_ptr. + std::unique_ptr engine; +public: + // Initialize by using make_unique in the member initializer list. + Car() : engine(std::make_unique()) {} - void MakeClass() - { - factory->DoSomething(); + void Start() { + engine->Run(); } }; + +int main() { + Car car; + car.Start(); +} \ No newline at end of file diff --git a/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_4.cpp b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_4.cpp index c7d62f9ca60..4637f942998 100644 --- a/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_4.cpp +++ b/docs/cpp/codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_4.cpp @@ -1,9 +1,17 @@ +// Compile with: cl /EHsc /std:c++17 + +#include +#include + +int main() { // Create a unique_ptr to an array of 5 integers. - auto p = make_unique(5); + // The elements are value-initialized to 0. + auto p = std::make_unique(5); - // Initialize the array. - for (int i = 0; i < 5; ++i) - { + // Assign values to the array elements. + for (int i = 0; i < 5; ++i) { p[i] = i; - wcout << p[i] << endl; - } \ No newline at end of file + std::cout << p[i] << "\n"; + } + // The array is automatically deleted when p goes out of scope. +} \ No newline at end of file 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 94a74225546..1ae88eee620 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 10ac9aab95d..2c7e2716ed6 100644 --- a/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_2.cpp +++ b/docs/cpp/codesnippet/CPP/smart-pointers-modern-cpp_2.cpp @@ -1,4 +1,3 @@ - class LargeObject { public: diff --git a/docs/cpp/com-error-class.md b/docs/cpp/com-error-class.md index 579cbec9ccf..90c26e6dd29 100644 --- a/docs/cpp/com-error-class.md +++ b/docs/cpp/com-error-class.md @@ -1,59 +1,59 @@ --- description: "Learn more about: _com_error Class" title: "_com_error Class" -ms.date: "11/04/2016" +ms.date: 11/17/2022 f1_keywords: ["_com_error"] helpviewer_keywords: ["_com_error class"] ms.assetid: 70dafa69-b1fb-4a5c-9249-e857e0793d42 --- -# _com_error Class +# `_com_error` class **Microsoft Specific** -A **_com_error** object represents an exception condition detected by the error-handling wrapper functions in the header files generated from the type library or by one of the COM support classes. The **_com_error** class encapsulates the HRESULT error code and any associated `IErrorInfo Interface` object. +A `_com_error` object represents an exception condition detected by the error-handling wrapper functions in the header files generated from the type library or by one of the COM support classes. The `_com_error` class encapsulates the `HRESULT` error code and any associated `IErrorInfo Interface` object. ### Construction | Name | Description | -|-|-| -|[_com_error](../cpp/com-error-com-error.md)|Constructs a **_com_error** object.| +|---|---| +| [`_com_error`](../cpp/com-error-com-error.md) | Constructs a `_com_error` object. | ### Operators | Name | Description | -|-|-| -|[operator =](../cpp/com-error-operator-equal.md)|Assigns an existing **_com_error** object to another.| +|---|---| +| [`operator =`](../cpp/com-error-operator-equal.md) | Assigns an existing `_com_error` object to another. | -### Extractor Functions +### Extractor functions | Name | Description | -|-|-| -|[Error](../cpp/com-error-error.md)|Retrieves the HRESULT passed to the constructor.| -|[ErrorInfo](../cpp/com-error-errorinfo.md)|Retrieves the `IErrorInfo` object passed to the constructor.| -|[WCode](../cpp/com-error-wcode.md)|Retrieves the 16-bit error code mapped into the encapsulated HRESULT.| +|---|---| +| [`Error`](../cpp/com-error-error.md) | Retrieves the `HRESULT` passed to the constructor. | +| [`ErrorInfo`](../cpp/com-error-errorinfo.md) | Retrieves the `IErrorInfo` object passed to the constructor. | +| [`WCode`](../cpp/com-error-wcode.md) | Retrieves the 16-bit error code mapped into the encapsulated `HRESULT`. | -### IErrorInfo Functions +### `IErrorInfo` functions | Name | Description | -|-|-| -|[Description](../cpp/com-error-description.md)|Calls `IErrorInfo::GetDescription` function.| -|[HelpContext](../cpp/com-error-helpcontext.md)|Calls `IErrorInfo::GetHelpContext` function.| -|[HelpFile](../cpp/com-error-helpfile.md)|Calls `IErrorInfo::GetHelpFile` function| -|[Source](../cpp/com-error-source.md)|Calls `IErrorInfo::GetSource` function.| -|[GUID](../cpp/com-error-guid.md)|Calls `IErrorInfo::GetGUID` function.| +|---|---| +| [`Description`](../cpp/com-error-description.md) | Calls `IErrorInfo::GetDescription` function. | +| [`HelpContext`](../cpp/com-error-helpcontext.md) | Calls `IErrorInfo::GetHelpContext` function. | +| [`HelpFile`](../cpp/com-error-helpfile.md) | Calls `IErrorInfo::GetHelpFile` function | +| [`Source`](../cpp/com-error-source.md) | Calls `IErrorInfo::GetSource` function. | +| [`GUID`](../cpp/com-error-guid.md) | Calls `IErrorInfo::GetGUID` function. | -### Format Message Extractor +### Format message extractor | Name | Description | -|-|-| -|[ErrorMessage](../cpp/com-error-errormessage.md)|Retrieves the string message for HRESULT stored in the **_com_error** object.| +|---|---| +| [`ErrorMessage`](../cpp/com-error-errormessage.md) | Retrieves the string message for `HRESULT` stored in the `_com_error` object. | -### ExepInfo.wCode to HRESULT Mappers +### `ExepInfo.wCode` to `HRESULT` mappers | Name | Description | -|-|-| -|[HRESULTToWCode](../cpp/com-error-hresulttowcode.md)|Maps 32-bit HRESULT to 16-bit `wCode`.| -|[WCodeToHRESULT](../cpp/com-error-wcodetohresult.md)|Maps 16-bit `wCode` to 32-bit HRESULT.| +|---|---| +| [`HRESULTToWCode`](../cpp/com-error-hresulttowcode.md) | Maps 32-bit `HRESULT` to 16-bit `wCode`. | +| [`WCodeToHRESULT`](../cpp/com-error-wcodetohresult.md) | Maps 16-bit `wCode` to 32-bit `HRESULT`. | **END Microsoft Specific** @@ -61,9 +61,9 @@ A **_com_error** object represents an exception condition detected by the error- **Header:** \ -`Lib:` comsuppw.lib or comsuppwd.lib (see [/Zc:wchar_t (wchar_t Is Native Type)](../build/reference/zc-wchar-t-wchar-t-is-native-type.md) for more information) +**Library:** *`comsuppw.lib`* or *`comsuppwd.lib`* (for more information, see [`/Zc:wchar_t` (wchar_t is native type)](../build/reference/zc-wchar-t-wchar-t-is-native-type.md)) ## See also -[Compiler COM Support Classes](../cpp/compiler-com-support-classes.md)
-[IErrorInfo Interface](/windows/win32/api/oaidl/nn-oaidl-ierrorinfo) +[Compiler COM support classes](../cpp/compiler-com-support-classes.md)\ +[`IErrorInfo` interface](/windows/win32/api/oaidl/nn-oaidl-ierrorinfo) diff --git a/docs/cpp/com-error-com-error.md b/docs/cpp/com-error-com-error.md index bb48c81b33a..62702d9e5fd 100644 --- a/docs/cpp/com-error-com-error.md +++ b/docs/cpp/com-error-com-error.md @@ -1,58 +1,58 @@ --- description: "Learn more about: _com_error::_com_error" title: "_com_error::_com_error" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::_com_error"] -helpviewer_keywords: ["_com_error method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error", "_com_error::_com_error"] +helpviewer_keywords: ["_com_error constructor [C++]"] ms.assetid: 0a69e46c-caab-49ef-b091-eee401253ce6 --- -# _com_error::_com_error +# `_com_error::_com_error` **Microsoft Specific** -Constructs a **_com_error** object. +Constructs a `_com_error` object. ## Syntax -``` +```cpp _com_error( HRESULT hr, IErrorInfo* perrinfo = NULL, - bool fAddRef=false) throw( ); + bool fAddRef = false) throw(); -_com_error( const _com_error& that ) throw( ); +_com_error( const _com_error& that ) throw(); ``` -#### Parameters +### Parameters -*hr*
-HRESULT information. +*`hr`*\ +`HRESULT` information. -*perrinfo*
+*`perrinfo`*\ `IErrorInfo` object. -*fAddRef*
-The default causes the constructor to call AddRef on a non-null `IErrorInfo` interface. This provides for correct reference counting in the common case where ownership of the interface is passed into the **_com_error** object, such as: +*`fAddRef`*\ +The default causes the constructor to not call AddRef on a non-null `IErrorInfo` interface. This behavior provides for correct reference counting in the common case where ownership of the interface is passed into the `_com_error` object, such as: ```cpp throw _com_error(hr, perrinfo); ``` -If you do not want your code to transfer ownership to the **_com_error** object, and the `AddRef` is required to offset the `Release` in the **_com_error** destructor, construct the object as follows: +If you don't want your code to transfer ownership to the `_com_error` object, and the `AddRef` is required to offset the `Release` in the `_com_error` destructor, construct the object as follows: ```cpp _com_error err(hr, perrinfo, true); ``` -*that*
-An existing **_com_error** object. +*`that`*\ +An existing `_com_error` object. ## Remarks -The first constructor creates a new object given an HRESULT and optional `IErrorInfo` object. The second creates a copy of an existing **_com_error** object. +The first constructor creates a new object given an `HRESULT` and optional `IErrorInfo` object. The second creates a copy of an existing `_com_error` object. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-description.md b/docs/cpp/com-error-description.md index c351a52017a..b60eb466ea4 100644 --- a/docs/cpp/com-error-description.md +++ b/docs/cpp/com-error-description.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::Description" title: "_com_error::Description" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::Description"] -helpviewer_keywords: ["Description method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::Description", "_com_error::Description"] +helpviewer_keywords: ["_com_error Description method [C++]"] ms.assetid: 88191e24-4ee8-44a6-8c4c-3758e22e0548 --- -# _com_error::Description +# `_com_error::Description` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetDescription` function. ## Syntax -``` -_bstr_t Description( ) const; +```cpp +_bstr_t Description() const; ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetDescription` for the `IErrorInfo` object recorded within the `_com_error` object. The resulting `BSTR` is encapsulated in a `_bstr_t` object. If no `IErrorInfo` is recorded, it returns an empty `_bstr_t`. @@ -30,4 +30,4 @@ Calls the `IErrorInfo::GetDescription` function and retrieves `IErrorInfo` recor ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-error.md b/docs/cpp/com-error-error.md index e784068c599..5301a4b1fbd 100644 --- a/docs/cpp/com-error-error.md +++ b/docs/cpp/com-error-error.md @@ -1,33 +1,33 @@ --- description: "Learn more about: _com_error::Error" title: "_com_error::Error" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::Error", "Error"] -helpviewer_keywords: ["Error method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::Error", "_com_error::Error"] +helpviewer_keywords: ["_com_error Error method [C++]"] ms.assetid: b53a15fd-198e-4276-afcd-13439c4807f7 --- -# _com_error::Error +# `_com_error::Error` **Microsoft Specific** -Retrieves the HRESULT passed to the constructor. +Retrieves the `HRESULT` passed to the constructor. ## Syntax -``` -HRESULT Error( ) const throw( ); +```cpp +HRESULT Error() const throw(); ``` -## Return Value +## Return value -Raw HRESULT item passed into the constructor. +Raw `HRESULT` item passed into the constructor. ## Remarks -Retrieves the encapsulated HRESULT item in a `_com_error` object. +Retrieves the encapsulated `HRESULT` item in a `_com_error` object. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-errorinfo.md b/docs/cpp/com-error-errorinfo.md index e352994c3ac..b622817cb7b 100644 --- a/docs/cpp/com-error-errorinfo.md +++ b/docs/cpp/com-error-errorinfo.md @@ -1,9 +1,9 @@ --- description: "Learn more about: _com_error::ErrorInfo" title: "_com_error::ErrorInfo" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::ErrorInfo"] -helpviewer_keywords: ["ErrorInfo method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::ErrorInfo", "_com_error::ErrorInfo"] +helpviewer_keywords: ["_com_error ErrorInfo method [C++]"] ms.assetid: 071b446c-4395-4fb8-bd3d-300a8b25f5cd --- # _com_error::ErrorInfo @@ -14,20 +14,20 @@ Retrieves the `IErrorInfo` object passed to the constructor. ## Syntax -``` +```cpp IErrorInfo * ErrorInfo( ) const throw( ); ``` -## Return Value +## Return value Raw `IErrorInfo` item passed into the constructor. ## Remarks -Retrieves the encapsulated `IErrorInfo` item in a `_com_error` object, or NULL if no `IErrorInfo` item is recorded. The caller must call `Release` on the returned object when finished using it. +Retrieves the encapsulated `IErrorInfo` item in a `_com_error` object, or `NULL` if no `IErrorInfo` item is recorded. The caller must call `Release` on the returned object when finished using it. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-errormessage.md b/docs/cpp/com-error-errormessage.md index 28e397f695f..9b30f24e0a0 100644 --- a/docs/cpp/com-error-errormessage.md +++ b/docs/cpp/com-error-errormessage.md @@ -1,33 +1,33 @@ --- description: "Learn more about: _com_error::ErrorMessage" title: "_com_error::ErrorMessage" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::ErrorMessage"] -helpviewer_keywords: ["ErrorMessage method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::ErrorMessage", "_com_error::ErrorMessage"] +helpviewer_keywords: ["_com_error ErrorMessage method [C++]"] ms.assetid: e47335b6-01af-4975-a841-121597479eb7 --- -# _com_error::ErrorMessage +# `_com_error::ErrorMessage` **Microsoft Specific** -Retrieves the string message for HRESULT stored in the `_com_error` object. +Retrieves the string message for `HRESULT` stored in the `_com_error` object. ## Syntax -``` -const TCHAR * ErrorMessage( ) const throw( ); +```cpp +const TCHAR * ErrorMessage() const throw(); ``` -## Return Value +## Return value -Returns the string message for the HRESULT recorded within the `_com_error` object. If the HRESULT is a mapped 16-bit [wCode](../cpp/com-error-wcode.md), then a generic message "`IDispatch error #`" is returned. If no message is found, then a generic message "`Unknown error #`" is returned. The returned string is either a Unicode or multibyte string, depending on the state of the _UNICODE macro. +Returns the string message for the `HRESULT` recorded within the `_com_error` object. If the `HRESULT` is a mapped 16-bit [`wCode`](../cpp/com-error-wcode.md), then a generic message "`IDispatch error #`" is returned. If no message is found, then a generic message "`Unknown error #`" is returned. The returned string is either a Unicode or multibyte string, depending on the state of the `_UNICODE` macro. ## Remarks -Retrieves the appropriate system message text for HRESULT recorded within the `_com_error` object. The system message text is obtained by calling the Win32 [FormatMessage](/windows/win32/api/winbase/nf-winbase-formatmessage) function. The string returned is allocated by the `FormatMessage` API, and it is released when the `_com_error` object is destroyed. +Retrieves the appropriate system message text for `HRESULT` recorded within the `_com_error` object. The system message text is obtained by calling the Win32 [`FormatMessage`](/windows/win32/api/winbase/nf-winbase-formatmessage) function. The string returned is allocated by the `FormatMessage` API, and it's released when the `_com_error` object is destroyed. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-guid.md b/docs/cpp/com-error-guid.md index 1b46f6c3c3c..b0355853338 100644 --- a/docs/cpp/com-error-guid.md +++ b/docs/cpp/com-error-guid.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::GUID" title: "_com_error::GUID" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::GUID"] -helpviewer_keywords: ["GUID method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::GUID", "_com_error::GUID"] +helpviewer_keywords: ["_com_error GUID method [C++]"] ms.assetid: e84c2c23-d02e-48f8-b776-9bd6937296d2 --- -# _com_error::GUID +# `_com_error::GUID` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetGUID` function. ## Syntax -``` -GUID GUID( ) const throw( ); +```cpp +GUID GUID() const throw(); ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetGUID` for the `IErrorInfo` object recorded within the `_com_error` object. If no `IErrorInfo` object is recorded, it returns `GUID_NULL`. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetGUID` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-helpcontext.md b/docs/cpp/com-error-helpcontext.md index 28494a998bc..28917755d8d 100644 --- a/docs/cpp/com-error-helpcontext.md +++ b/docs/cpp/com-error-helpcontext.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::HelpContext" title: "_com_error::HelpContext" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::HelpContext"] -helpviewer_keywords: ["HelpContext method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::HelpContext", "_com_error::HelpContext"] +helpviewer_keywords: ["_com_error HelpContext method [C++]"] ms.assetid: 160d6443-9b68-4cf5-a540-50da951a5b2b --- -# _com_error::HelpContext +# `_com_error::HelpContext` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetHelpContext` function. ## Syntax -``` -DWORD HelpContext( ) const throw( ); +```cpp +DWORD HelpContext() const throw(); ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetHelpContext` for the `IErrorInfo` object recorded within the `_com_error` object. If no `IErrorInfo` object is recorded, it returns a zero. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetHelpContext` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-helpfile.md b/docs/cpp/com-error-helpfile.md index 6415cba6d3b..917a3f7550d 100644 --- a/docs/cpp/com-error-helpfile.md +++ b/docs/cpp/com-error-helpfile.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::HelpFile" title: "_com_error::HelpFile" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::HelpFile"] -helpviewer_keywords: ["HelpFile method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::HelpFile", "_com_error::HelpFile"] +helpviewer_keywords: ["_com_error HelpFile method [C++]"] ms.assetid: d2d3a0a1-6b62-4d52-a818-3cfae545a4af --- -# _com_error::HelpFile +# `_com_error::HelpFile` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetHelpFile` function. ## Syntax -``` +```cpp _bstr_t HelpFile() const; ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetHelpFile` for the `IErrorInfo` object recorded within the `_com_error` object. The resulting BSTR is encapsulated in a `_bstr_t` object. If no `IErrorInfo` is recorded, it returns an empty `_bstr_t`. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetHelpFile` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-hresulttowcode.md b/docs/cpp/com-error-hresulttowcode.md index 1cdfcce66c5..166b4249d23 100644 --- a/docs/cpp/com-error-hresulttowcode.md +++ b/docs/cpp/com-error-hresulttowcode.md @@ -1,42 +1,42 @@ --- description: "Learn more about: _com_error::HRESULTToWCode" title: "_com_error::HRESULTToWCode" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::HRESULTToWCode"] -helpviewer_keywords: ["HRESULTToWCode method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::HRESULTToWCode", "_com_error::HRESULTToWCode"] +helpviewer_keywords: ["_com_error HRESULTToWCode method [C++]"] ms.assetid: ff3789f5-1047-41a0-b7e3-86dd8f638dba --- -# _com_error::HRESULTToWCode +# `_com_error::HRESULTToWCode` **Microsoft Specific** -Maps 32-bit HRESULT to 16-bit `wCode`. +Maps 32-bit `HRESULT` to 16-bit `wCode`. ## Syntax -``` +```cpp static WORD HRESULTToWCode( HRESULT hr -) throw( ); +) throw(); ``` -#### Parameters +### Parameters -*hr*
-The 32-bit HRESULT to be mapped to 16-bit `wCode`. +*`hr`*\ +The 32-bit `HRESULT` to be mapped to 16-bit `wCode`. -## Return Value +## Return value -16-bit `wCode` mapped from the 32-bit HRESULT. +16-bit `wCode` mapped from the 32-bit `HRESULT`. ## Remarks -See [_com_error::WCode](../cpp/com-error-wcode.md) for more information. +For more information, see [`_com_error::WCode`](../cpp/com-error-wcode.md). **END Microsoft Specific** ## See also -[_com_error::WCode](../cpp/com-error-wcode.md)
-[_com_error::WCodeToHRESULT](../cpp/com-error-wcodetohresult.md)
-[_com_error Class](../cpp/com-error-class.md) +[`_com_error::WCode`](../cpp/com-error-wcode.md)\ +[`_com_error::WCodeToHRESULT`](../cpp/com-error-wcodetohresult.md)\ +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-member-functions.md b/docs/cpp/com-error-member-functions.md index 5f62a95fcb2..6e84505cbfc 100644 --- a/docs/cpp/com-error-member-functions.md +++ b/docs/cpp/com-error-member-functions.md @@ -1,14 +1,14 @@ --- description: "Learn more about: _com_error Member Functions" title: "_com_error Member Functions" -ms.date: "11/04/2016" +ms.date: 11/17/2022 helpviewer_keywords: ["_com_error class [C++], member functions"] ms.assetid: 39a73cdb-c12c-4d3b-a314-e3f6580f4d2d --- -# _com_error Member Functions +# `_com_error` member functions -For information about the **_com_error** member functions, see [_com_error Class](../cpp/com-error-class.md). +For information about the `_com_error` member functions, see [`_com_error` class](../cpp/com-error-class.md). ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-operator-equal.md b/docs/cpp/com-error-operator-equal.md index 8d4a2a2e4b8..35748208fc0 100644 --- a/docs/cpp/com-error-operator-equal.md +++ b/docs/cpp/com-error-operator-equal.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: _com_error::operator =" -title: "_com_error::operator =" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::operator="] -helpviewer_keywords: ["_com_error [C++]"] +description: "Learn more about: _com_error::operator=" +title: "_com_error::operator=" +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::operator=", "_com_error::operator="] +helpviewer_keywords: ["_com_error operator= [C++]"] ms.assetid: b9cc4094-d055-450c-b45a-0a95317488f8 --- -# _com_error::operator = +# `_com_error::operator=` **Microsoft Specific** @@ -14,19 +14,19 @@ Assigns an existing `_com_error` object to another. ## Syntax -``` -_com_error& operator = ( +```cpp +_com_error& operator=( const _com_error& that -) throw ( ); +) throw (); ``` -#### Parameters +### Parameters -*that*
+*`that`*\ A `_com_error` object. **END Microsoft Specific** ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-operators.md b/docs/cpp/com-error-operators.md index cfe6340686c..c4f8411660f 100644 --- a/docs/cpp/com-error-operators.md +++ b/docs/cpp/com-error-operators.md @@ -1,14 +1,14 @@ --- description: "Learn more about: _com_error Operators" title: "_com_error Operators" -ms.date: "11/04/2016" +ms.date: 11/17/2022 helpviewer_keywords: ["_com_error class [C++], operators"] ms.assetid: 0c4a1532-59b7-41ea-8aeb-1c486898db4d --- -# _com_error Operators +# `_com_error` operators -For information about the **_com_error** operators, see [_com_error Class](../cpp/com-error-class.md). +For information about the `_com_error` operators, see [`_com_error` class](../cpp/com-error-class.md). ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-source.md b/docs/cpp/com-error-source.md index b2f53f049dc..f14b30defbd 100644 --- a/docs/cpp/com-error-source.md +++ b/docs/cpp/com-error-source.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _com_error::Source" title: "_com_error::Source" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::Source"] -helpviewer_keywords: ["Source method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::Source", "_com_error::Source"] +helpviewer_keywords: ["_com_error Source method [C++]"] ms.assetid: 55353741-fabc-4b0c-9787-b5a69bb189f2 --- -# _com_error::Source +# `_com_error::Source` **Microsoft Specific** @@ -14,11 +14,11 @@ Calls `IErrorInfo::GetSource` function. ## Syntax -``` +```cpp _bstr_t Source() const; ``` -## Return Value +## Return value Returns the result of `IErrorInfo::GetSource` for the `IErrorInfo` object recorded within the `_com_error` object. The resulting `BSTR` is encapsulated in a `_bstr_t` object. If no `IErrorInfo` is recorded, it returns an empty `_bstr_t`. @@ -30,4 +30,4 @@ Any failure while calling the `IErrorInfo::GetSource` method is ignored. ## See also -[_com_error Class](../cpp/com-error-class.md) +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-wcode.md b/docs/cpp/com-error-wcode.md index 964866741b7..e3170bdbc7d 100644 --- a/docs/cpp/com-error-wcode.md +++ b/docs/cpp/com-error-wcode.md @@ -1,35 +1,35 @@ --- description: "Learn more about: _com_error::WCode" title: "_com_error::WCode" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::WCode"] -helpviewer_keywords: ["WCode method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::WCode", "_com_error::WCode"] +helpviewer_keywords: ["_com_error WCode method [C++]"] ms.assetid: f3b21852-f8ea-4e43-bff1-11c2d35454c4 --- -# _com_error::WCode +# `_com_error::WCode` **Microsoft Specific** -Retrieves the 16-bit error code mapped into the encapsulated HRESULT. +Retrieves the 16-bit error code mapped into the encapsulated `HRESULT`. ## Syntax -``` -WORD WCode ( ) const throw( ); +```cpp +WORD WCode ( ) const throw(); ``` -## Return Value +## Return value -If the HRESULT is within the range 0x80040200 to 0x8004FFFF, the `WCode` method returns the HRESULT minus 0x80040200; otherwise, it returns zero. +If the `HRESULT` is within the range 0x80040200 to 0x8004FFFF, the `WCode` method returns the `HRESULT` minus 0x80040200; otherwise, it returns zero. ## Remarks -The `WCode` method is used to undo a mapping that happens in the COM support code. The wrapper for a `dispinterface` property or method calls a support routine that packages the arguments and calls `IDispatch::Invoke`. Upon return, if a failure HRESULT of `DISP_E_EXCEPTION` is returned, the error information is retrieved from the `EXCEPINFO` structure passed to `IDispatch::Invoke`. The error code can either be a 16-bit value stored in the `wCode` member of the `EXCEPINFO` structure or a full 32-bit value in the `scode` member of the `EXCEPINFO` structure. If a 16-bit `wCode` is returned, it must first be mapped to a 32-bit failure HRESULT. +The `WCode` method is used to undo a mapping that happens in the COM support code. The wrapper for a `dispinterface` property or method calls a support routine that packages the arguments and calls `IDispatch::Invoke`. Upon return, if a failure `HRESULT` of `DISP_E_EXCEPTION` is returned, the error information is retrieved from the `EXCEPINFO` structure passed to `IDispatch::Invoke`. The error code can either be a 16-bit value stored in the `wCode` member of the `EXCEPINFO` structure or a full 32-bit value in the `scode` member of the `EXCEPINFO` structure. If a 16-bit `wCode` is returned, it must first be mapped to a 32-bit failure `HRESULT`. **END Microsoft Specific** ## See also -[_com_error::HRESULTToWCode](../cpp/com-error-hresulttowcode.md)
-[_com_error::WCodeToHRESULT](../cpp/com-error-wcodetohresult.md)
-[_com_error Class](../cpp/com-error-class.md) +[`_com_error::HRESULTToWCode`](../cpp/com-error-hresulttowcode.md)\ +[`_com_error::WCodeToHRESULT`](../cpp/com-error-wcodetohresult.md)\ +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-error-wcodetohresult.md b/docs/cpp/com-error-wcodetohresult.md index 13141e0df24..0e3bb9a678d 100644 --- a/docs/cpp/com-error-wcodetohresult.md +++ b/docs/cpp/com-error-wcodetohresult.md @@ -1,42 +1,42 @@ --- description: "Learn more about: _com_error::WCodeToHRESULT" title: "_com_error::WCodeToHRESULT" -ms.date: "11/04/2016" -f1_keywords: ["_com_error::WCodeToHRESULT"] -helpviewer_keywords: ["WCodeToHRESULT method [C++]"] +ms.date: 11/17/2022 +f1_keywords: ["COMDEF/_com_error::WCodeToHRESULT", "_com_error::WCodeToHRESULT"] +helpviewer_keywords: ["_com_error WCodeToHRESULT method [C++]"] ms.assetid: 0ec43a4b-ca91-42d5-b270-3fde9c8412ea --- -# _com_error::WCodeToHRESULT +# `_com_error::WCodeToHRESULT` **Microsoft Specific** -Maps 16-bit *wCode* to 32-bit HRESULT. +Maps 16-bit *`wCode`* to 32-bit `HRESULT`. ## Syntax -``` +```cpp static HRESULT WCodeToHRESULT( WORD wCode -) throw( ); +) throw(); ``` -#### Parameters +### Parameters -*wCode*
-The 16-bit *wCode* to be mapped to 32-bit HRESULT. +*`wCode`*\ +The 16-bit *`wCode`* to be mapped to 32-bit `HRESULT`. -## Return Value +## Return value -32-bit HRESULT mapped from the 16-bit *wCode*. +32-bit `HRESULT` mapped from the 16-bit *`wCode`*. ## Remarks -See the [WCode](../cpp/com-error-wcode.md) member function. +See the [`WCode`](../cpp/com-error-wcode.md) member function. **END Microsoft Specific** ## See also -[_com_error::WCode](../cpp/com-error-wcode.md)
-[_com_error::HRESULTToWCode](../cpp/com-error-hresulttowcode.md)
-[_com_error Class](../cpp/com-error-class.md) +[`_com_error::WCode`](../cpp/com-error-wcode.md)\ +[`_com_error::HRESULTToWCode`](../cpp/com-error-hresulttowcode.md)\ +[`_com_error` class](../cpp/com-error-class.md) diff --git a/docs/cpp/com-ptr-t-extractors.md b/docs/cpp/com-ptr-t-extractors.md index 416c3967124..305a593e877 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/com-ptr-t-relational-operators.md b/docs/cpp/com-ptr-t-relational-operators.md index 37ebee59797..7101967bd2a 100644 --- a/docs/cpp/com-ptr-t-relational-operators.md +++ b/docs/cpp/com-ptr-t-relational-operators.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: _com_ptr_t Relational Operators" title: "_com_ptr_t Relational Operators" -ms.date: "11/04/2016" +description: "Learn more about: _com_ptr_t Relational Operators" +ms.date: 11/04/2016 f1_keywords: ["_com_ptr_t::operator>", "_com_ptr_t::operator>=", "_com_ptr_t::operator<=", "_com_ptr_t::operator==", "_com_ptr_t::operator!=", "_com_ptr_t::operator<"] helpviewer_keywords: [">= operator [C++], comparing specific objects", "!= operator", "operator > [C++], pointers", "operator>= [C++], pointers", "operator < [C++], pointers", "operator!= [C++], relational operators", "< operator [C++], comparing specific objects", "operator== [C++], pointers", "operator == [C++], pointers", "<= operator [C++], with specific objects", "relational operators [C++], _com_ptr_t class", "operator >= [C++], pointers", "operator != [C++], relational operators", "operator <= [C++], pointers", "> operator [C++], comparing specific objects", "operator<= [C++], pointers", "operator< [C++], pointers", "== operator [C++], with specific Visual C++ objects"] -ms.assetid: 5ae4028c-33ee-485d-bbda-88d2604d6d4b --- # _com_ptr_t Relational Operators @@ -33,7 +32,7 @@ bool operator==( const _com_ptr_t& p ) throw(); template<> bool operator==( _com_ptr_t& p ) throw(); -bool operator==( Int null ); +bool operator==( int null ); template bool operator!=( const _com_ptr_t<_OtherIID>& p ); @@ -44,7 +43,7 @@ bool operator!=( _com_ptr_t<_OtherIID>& p ); template bool operator!=( _InterfaceType* p ); -bool operator!=( Int null ); +bool operator!=( int null ); template bool operator<( const _com_ptr_t<_OtherIID>& p ); diff --git a/docs/cpp/comma-operator.md b/docs/cpp/comma-operator.md index 60bad789d8b..a43a7c1193e 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 9059716f9c7..4fcdd08cfc9 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 511680d32d8..4560531ba40 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 cca4371b50a..b786fcb6b4d 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 aa2cd84c0f7..fc2837dbf0c 100644 --- a/docs/cpp/const-cpp.md +++ b/docs/cpp/const-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: const (C++)" title: "const (C++)" -ms.date: 02/03/2022 +ms.date: 09/27/2022 f1_keywords: ["const_cpp"] helpviewer_keywords: ["const keyword [C++]"] ms.assetid: b21c0271-1ad0-40a0-b21c-5e812bba0318 @@ -147,25 +147,30 @@ 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: -```cpp +```C const int i = 2; ``` You can then use this variable in another module as follows: -```cpp +```C extern const int i; ``` -But to get the same behavior in C++, you must declare your **`const`** variable as: +But to get the same behavior in C++, you must define your **`const`** variable as: ```cpp extern const int i = 2; ``` +Similar to C, you can then use this variable in another module as follows: + +```cpp +extern const int i; +``` -If you wish to declare an **`extern`** variable in a C++ source code file for use in a C source code file, use: +If you wish to define an **`extern`** variable in a C++ source code file for use in a C source code file, use: ```cpp extern "C" const int x=10; diff --git a/docs/cpp/constexpr-cpp.md b/docs/cpp/constexpr-cpp.md index 4620d2775fa..0096561562a 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 c175d82314a..9f71ee362e6 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 f5316639dfd..7165a7aa290 100644 --- a/docs/cpp/cpp-language-reference.md +++ b/docs/cpp/cpp-language-reference.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: C++ Language Reference" title: "C++ Language Reference" +description: "Learn more about: C++ Language Reference" ms.custom: "index-page" -ms.date: "12/10/2019" +ms.date: 12/10/2019 helpviewer_keywords: ["C++, language reference"] -ms.assetid: 4be9cacb-c862-4391-894a-3a118c9c93ce --- # C++ Language Reference @@ -14,96 +13,95 @@ For an overview of Modern C++ programming practices, see [Welcome Back to C++](w See the following tables to quickly find a keyword or operator: -- [C++ Keywords](../cpp/keywords-cpp.md) - -- [C++ Operators](../cpp/cpp-built-in-operators-precedence-and-associativity.md) +- [C++ Keywords](keywords-cpp.md) +- [C++ Operators](cpp-built-in-operators-precedence-and-associativity.md) ## In This Section -[Lexical Conventions](../cpp/lexical-conventions.md)
+[Lexical Conventions](lexical-conventions.md)\ Fundamental lexical elements of a C++ program: tokens, comments, operators, keywords, punctuators, literals. Also, file translation, operator precedence/associativity. -[Basic Concepts](../cpp/basic-concepts-cpp.md)
+[Basic Concepts](basic-concepts-cpp.md)\ Scope, linkage, program startup and termination, storage classes, and types. -[Built-in types](fundamental-types-cpp.md) +[Built-in types](fundamental-types-cpp.md)\ The fundamental types that are built into the C++ compiler and their value ranges. -[Standard Conversions](../cpp/standard-conversions.md)
+[Standard Conversions](standard-conversions.md)\ Type conversions between built-in types. Also, arithmetic conversions and conversions among pointer, reference, and pointer-to-member types. -[Declarations and definitions](declarations-and-definitions-cpp.md) +[Declarations and definitions](declarations-and-definitions-cpp.md)\ Declaring and defining variables, types and functions. -[Operators, Precedence and Associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[Operators, Precedence and Associativity](cpp-built-in-operators-precedence-and-associativity.md)\ The operators in C++. -[Expressions](../cpp/expressions-cpp.md)
+[Expressions](expressions-cpp.md)\ Types of expressions, semantics of expressions, reference topics on operators, casting and casting operators, run-time type information. -[Lambda Expressions](../cpp/lambda-expressions-in-cpp.md)
+[Lambda Expressions](lambda-expressions-in-cpp.md)\ A programming technique that implicitly defines a function object class and constructs a function object of that class type. -[Statements](../cpp/statements-cpp.md)
+[Statements](statements-cpp.md)\ Expression, null, compound, selection, iteration, jump, and declaration statements. -[Classes and structs](../cpp/classes-and-structs-cpp.md)
+[Classes and structs](classes-and-structs-cpp.md)\ Introduction to classes, structures, and unions. Also, member functions, special member functions, data members, bit fields, **`this`** pointer, nested classes. -[Unions](unions.md)
+[Unions](unions.md)\ User-defined types in which all members share the same memory location. -[Derived Classes](../cpp/inheritance-cpp.md)
+[Derived Classes](inheritance-cpp.md)\ Single and multiple inheritance, **`virtual`** functions, multiple base classes, **abstract** classes, scope rules. Also, the **`__super`** and **`__interface`** keywords. -[Member-Access Control](../cpp/member-access-control-cpp.md)
+[Member-Access Control](member-access-control-cpp.md)\ Controlling access to class members: **`public`**, **`private`**, and **`protected`** keywords. Friend functions and classes. -[Overloading](operator-overloading.md)
+[Overloading](operator-overloading.md)\ Overloaded operators, rules for operator overloading. -[Exception Handling](../cpp/exception-handling-in-visual-cpp.md)
+[Exception Handling](exception-handling-in-visual-cpp.md)\ C++ exception handling, structured exception handling (SEH), keywords used in writing exception handling statements. -[Assertion and User-Supplied Messages](../cpp/assertion-and-user-supplied-messages-cpp.md)
+[Assertion and User-Supplied Messages](assertion-and-user-supplied-messages-cpp.md)\ `#error` directive, the **`static_assert`** keyword, the `assert` macro. -[Templates](../cpp/templates-cpp.md)
+[Templates](templates-cpp.md)\ Template specifications, function templates, class templates, **`typename`** keyword, templates vs. macros, templates and smart pointers. -[Event Handling](../cpp/event-handling.md)
+[Event Handling](event-handling.md)\ Declaring events and event handlers. -[Microsoft-Specific Modifiers](../cpp/microsoft-specific-modifiers.md)
+[Microsoft-Specific Modifiers](microsoft-specific-modifiers.md)\ Modifiers specific to Microsoft C++. Memory addressing, calling conventions, **`naked`** functions, extended storage-class attributes (**`__declspec`**), **`__w64`**. -[Inline Assembler](../assembler/inline/inline-assembler.md)
+[Inline Assembler](../assembler/inline/inline-assembler.md)\ Using assembly language and C++ in **`__asm`** blocks. -[Compiler COM Support](../cpp/compiler-com-support.md)
+[Compiler COM Support](compiler-com-support.md)\ A reference to Microsoft-specific classes and global functions used to support COM types. -[Microsoft Extensions](../cpp/microsoft-extensions.md)
+[Microsoft Extensions](microsoft-extensions.md)\ Microsoft extensions to C++. -[Nonstandard Behavior](../cpp/nonstandard-behavior.md)
+[Nonstandard Behavior](nonstandard-behavior.md)\ Information about nonstandard behavior of the Microsoft C++ compiler. -[Welcome Back to C++](welcome-back-to-cpp-modern-cpp.md)
+[Welcome Back to C++](welcome-back-to-cpp-modern-cpp.md)\ An overview of modern C++ programming practices for writing safe, correct and efficient programs. ## Related Sections -[Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md)
+[Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md)\ Reference material on using the Microsoft C++ compiler to target .NET. -[C/C++ Building Reference](../build/reference/c-cpp-building-reference.md)
+[C/C++ Building Reference](../build/reference/c-cpp-building-reference.md)\ Compiler options, linker options, and other build tools. -[C/C++ Preprocessor Reference](../preprocessor/c-cpp-preprocessor-reference.md)
+[C/C++ Preprocessor Reference](../preprocessor/c-cpp-preprocessor-reference.md)\ Reference material on pragmas, preprocessor directives, predefined macros, and the preprocessor. -[Visual C++ Libraries](../standard-library/cpp-standard-library-reference.md)
+[Visual C++ Libraries](../standard-library/cpp-standard-library-reference.md)\ A list of links to the reference start pages for the various Microsoft C++ libraries. ## See also diff --git a/docs/cpp/cpp-type-system-modern-cpp.md b/docs/cpp/cpp-type-system-modern-cpp.md index b9b3d4b8f0d..67772c31a07 100644 --- a/docs/cpp/cpp-type-system-modern-cpp.md +++ b/docs/cpp/cpp-type-system-modern-cpp.md @@ -1,29 +1,32 @@ --- description: "Learn more about: C++ type system" title: "C++ type system" -ms.date: "11/19/2019" -ms.topic: "conceptual" -ms.assetid: 553c0ed6-77c4-43e9-87b1-c903eec53e80 +ms.date: 11/04/2022 +ms.topic: "concept-article" --- # C++ type system -The concept of *type* is very important in C++. Every variable, function argument, and function return value must have a type in order to be compiled. Also, every expression (including literal values) is implicitly given a type by the compiler before it is evaluated. Some examples of types include **`int`** to store integer values, **`double`** to store floating-point values (also known as *scalar* data types), or the Standard Library class [std::basic_string](../standard-library/basic-string-class.md) to store text. You can create your own type by defining a **`class`** or **`struct`**. The type specifies the amount of memory that will be allocated for the variable (or expression result), the kinds of values that may be stored in that variable, how those values (as bit patterns) are interpreted, and the operations that can be performed on it. This article contains an informal overview of the major features of the C++ type system. +The concept of *type* is important in C++. Every variable, function argument, and function return value must have a type in order to be compiled. Also, all expressions (including literal values) are implicitly given a type by the compiler before they're evaluated. Some examples of types include built-in types such as **`int`** to store integer values, **`double`** to store floating-point values, or Standard Library types such as class [`std::basic_string`](../standard-library/basic-string-class.md) to store text. You can create your own type by defining a **`class`** or **`struct`**. The type specifies the amount of memory that's allocated for the variable (or expression result). The type also specifies the kinds of values that may be stored, how the compiler interprets the bit patterns in those values, and the operations you can perform on them. This article contains an informal overview of the major features of the C++ type system. ## Terminology -**Variable**: The symbolic name of a quantity of data so that the name can be used to access the data it refers to throughout the scope of the code where it is defined. In C++, *variable* is generally used to refer to instances of scalar data types, whereas instances of other types are usually called *objects*. +**Scalar type**: A type that holds a single value of a defined range. Scalars include arithmetic types (integral or floating-point values), enumeration type members, pointer types, pointer-to-member types, and `std::nullptr_t`. Fundamental types are typically scalar types. -**Object**: For simplicity and consistency, this article uses the term *object* to refer to any instance of a class or structure, and when it is used in the general sense includes all types, even scalar variables. +**Compound type**: A type that isn't a scalar type. Compound types include array types, function types, class (or struct) types, union types, enumerations, references, and pointers to non-static class members. -**POD type** (plain old data): This informal category of data types in C++ refers to types that are scalar (see the Fundamental types section) or are *POD classes*. A POD class has no static data members that aren’t also PODs, and has no user-defined constructors, user-defined destructors, or user-defined assignment operators. Also, a POD class has no virtual functions, no base class, and no private or protected non-static data members. POD types are often used for external data interchange, for example with a module written in the C language (which has POD types only). +**Variable**: The symbolic name of a quantity of data. The name can be used to access the data it refers to throughout the scope of the code where it's defined. In C++, *variable* is often used to refer to instances of scalar data types, whereas instances of other types are typically called *objects*. + +**Object**: For simplicity and consistency, this article uses the term *object* to refer to any instance of a class or structure. When it's used in the general sense, it includes all types, even scalar variables. + +**POD type** (plain old data): This informal category of data types in C++ refers to types that are scalar (see the Fundamental types section) or are *POD classes*. A POD class has no static data members that aren't also PODs, and has no user-defined constructors, user-defined destructors, or user-defined assignment operators. Also, a POD class has no virtual functions, no base class, and no private or protected non-static data members. POD types are often used for external data interchange, for example with a module written in the C language (which has POD types only). ## Specifying variable and function types -C++ is a *strongly typed* language and it is also *statically-typed*; every object has a type and that type never changes (not to be confused with static data objects). When you declare a variable in your code, you must either specify its type explicitly, or use the **`auto`** keyword to instruct the compiler to deduce the type from the initializer. When you declare a function in your code, you must specify the type of each argument and its return value, or **`void`** if no value is returned by the function. The exception is when you are using function templates, which allow for arguments of arbitrary types. +C++ is both a *strongly typed* language and a *statically typed* language; every object has a type and that type never changes. When you declare a variable in your code, you must either specify its type explicitly, or use the **`auto`** keyword to instruct the compiler to deduce the type from the initializer. When you declare a function in your code, you must specify the type of its return value and of each argument. Use the return value type **`void`** if no value is returned by the function. The exception is when you're using function templates, which allow for arguments of arbitrary types. -After you first declare a variable, you cannot change its type at some later point. However, you can copy the variable’s value or a function’s return value into another variable of a different type. Such operations are called *type conversions*, which are sometimes necessary but are also potential sources of data loss or incorrectness. +After you first declare a variable, you can't change its type at some later point. However, you can copy the variable's value or a function's return value into another variable of a different type. Such operations are called *type conversions*, which are sometimes necessary but are also potential sources of data loss or incorrectness. -When you declare a variable of POD type, we strongly recommend you initialize it, which means to give it an initial value. Until you initialize a variable, it has a "garbage" value that consists of whatever bits happened to be in that memory location previously. This is an important aspect of C++ to remember, especially if you are coming from another language that handles initialization for you. When declaring a variable of non-POD class type, the constructor handles initialization. +When you declare a variable of POD type, we strongly recommend you *initialize* it, which means to give it an initial value. Until you initialize a variable, it has a "garbage" value that consists of whatever bits happened to be in that memory location previously. It's an important aspect of C++ to remember, especially if you're coming from another language that handles initialization for you. When you declare a variable of non-POD class type, the constructor handles initialization. The following example shows some simple variable declarations with some descriptions for each. The example also shows how the compiler uses type information to allow or disallow certain subsequent operations on the variable. @@ -37,8 +40,8 @@ auto address; // error. Compiler cannot deduce a type // without an intializing value. age = 12; // error. Variable declaration must // specify a type or use auto! -result = "Kenny G."; // error. Can’t assign text to an int. -string result = "zero"; // error. Can’t redefine a variable with +result = "Kenny G."; // error. Can't assign text to an int. +string result = "zero"; // error. Can't redefine a variable with // new type. int maxValue; // Not recommended! maxValue contains // garbage bits until it is initialized. @@ -46,13 +49,13 @@ int maxValue; // Not recommended! maxValue contains ## Fundamental (built-in) types -Unlike some languages, C++ has no universal base type from which all other types are derived. The language includes many *fundamental types*, also known as *built-in types*. This includes numeric types such as **`int`**, **`double`**, **`long`**, **`bool`**, plus the **`char`** and **`wchar_t`** types for ASCII and UNICODE characters, respectively. Most integral fundamental types (except **`bool`**, **`double`**, **`wchar_t`**, and related types) all have **`unsigned`** versions, which modify the range of values that the variable can store. For example, an **`int`**, which stores a 32-bit signed integer, can represent a value from -2,147,483,648 to 2,147,483,647. An **`unsigned int`**, which is also stored as 32-bits, can store a value from 0 to 4,294,967,295. The total number of possible values in each case is the same; only the range is different. +Unlike some languages, C++ has no universal base type from which all other types are derived. The language includes many *fundamental types*, also known as *built-in types*. These types include numeric types such as **`int`**, **`double`**, **`long`**, **`bool`**, plus the **`char`** and **`wchar_t`** types for ASCII and UNICODE characters, respectively. Most integral fundamental types (except **`bool`**, **`double`**, **`wchar_t`**, and related types) all have **`unsigned`** versions, which modify the range of values that the variable can store. For example, an **`int`**, which stores a 32-bit signed integer, can represent a value from -2,147,483,648 to 2,147,483,647. An **`unsigned int`**, which is also stored as 32 bits, can store a value from 0 to 4,294,967,295. The total number of possible values in each case is the same; only the range is different. -The fundamental types are recognized by the compiler, which has built-in rules that govern what operations you can perform on them, and how they can be converted to other fundamental types. For a complete list of built-in types and their size and numeric limits, see [Built-in types](../cpp/fundamental-types-cpp.md). +The compiler recognizes these built-in types, and it has built-in rules that govern what operations you can perform on them, and how they can be converted to other fundamental types. For a complete list of built-in types and their size and numeric limits, see [Built-in types](../cpp/fundamental-types-cpp.md). The following illustration shows the relative sizes of the built-in types in the Microsoft C++ implementation: -![Diagram of the relative size in bytes of several built in types.](../cpp/media/built-intypesizes.png) +:::image type="content" source="../cpp/media/built-intypesizes.png" alt-text="Diagram showing the relative sizes in bytes of C++ built-in types: bool and char (1 byte), short (2 bytes), int, long, and float (4 bytes), double and long long (8 bytes)"::: The following table lists the most frequently used fundamental types, and their sizes in the Microsoft C++ implementation: @@ -62,34 +65,33 @@ The following table lists the most frequently used fundamental types, and their | **`double`** | 8 bytes | The default choice for floating point values. | | **`bool`** | 1 byte | Represents values that can be either true or false. | | **`char`** | 1 byte | Use for ASCII characters in older C-style strings or std::string objects that will never have to be converted to UNICODE. | -| **`wchar_t`** | 2 bytes | Represents "wide" character values that may be encoded in UNICODE format (UTF-16 on Windows, other operating systems may differ). This is the character type that is used in strings of type `std::wstring`. | +| **`wchar_t`** | 2 bytes | Represents "wide" character values that may be encoded in UNICODE format (UTF-16 on Windows, other operating systems may differ). **`wchar_t`** is the character type that's used in strings of type `std::wstring`. | | **`unsigned char`** | 1 byte | C++ has no built-in byte type. Use **`unsigned char`** to represent a byte value. | | **`unsigned int`** | 4 bytes | Default choice for bit flags. | -| **`long long`** | 8 bytes | Represents very large integer values. | +| **`long long`** | 8 bytes | Represents a much larger range of integer values. | Other C++ implementations may use different sizes for certain numeric types. For more information on the sizes and size relationships that the C++ standard requires, see [Built-in types](fundamental-types-cpp.md). -## The void type +## The `void` type -The **`void`** type is a special type; you cannot declare a variable of type **`void`**, but you can declare a variable of type `void *` (pointer to **`void`**), which is sometimes necessary when allocating raw (un-typed) memory. However, pointers to **`void`** are not type-safe and generally their use is strongly discouraged in modern C++. In a function declaration, a **`void`** return value means that the function does not return a value; this is a common and acceptable use of **`void`**. While the C language required functions that have zero parameters to declare **`void`** in the parameter list, for example, `fou(void)`, this practice is discouraged in modern C++ and should be declared `fou()`. For more information, see [Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). +The **`void`** type is a special type; you can't declare a variable of type **`void`**, but you can declare a variable of type `void *` (pointer to **`void`**), which is sometimes necessary when allocating raw (untyped) memory. However, pointers to **`void`** aren't type-safe and their use is discouraged in modern C++. In a function declaration, a **`void`** return value means that the function doesn't return a value; using it as a return type is a common and acceptable use of **`void`**. While the C language required functions that have zero parameters to declare **`void`** in the parameter list, for example, `fn(void)`, this practice is discouraged in modern C++; a parameterless function should be declared `fn()`. For more information, see [Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). -## const type qualifier +## `const` type qualifier -Any built-in or user-defined type may be qualified by the const keyword. Additionally, member functions may be **`const`**-qualified and even **`const`**-overloaded. The value of a **`const`** type cannot be modified after it is initialized. +Any built-in or user-defined type may be qualified by the **`const`** keyword. Additionally, member functions may be **`const`**-qualified and even **`const`**-overloaded. The value of a **`const`** type can't be modified after it's initialized. ```cpp - const double PI = 3.1415; -PI = .75 //Error. Cannot modify const variable. +PI = .75; //Error. Cannot modify const variable. ``` -The **`const`** qualifier is used extensively in function and variable declarations and "const correctness" is an important concept in C++; essentially it means to use **`const`** to guarantee, at compile time, that values are not modified unintentionally. For more information, see [`const`](../cpp/const-cpp.md). +The **`const`** qualifier is used extensively in function and variable declarations and "const correctness" is an important concept in C++; essentially it means to use **`const`** to guarantee, at compile time, that values aren't modified unintentionally. For more information, see [`const`](../cpp/const-cpp.md). -A **`const`** type is distinct from its non-const version; for example, **`const int`** is a distinct type from **`int`**. You can use the C++ **`const_cast`** operator on those rare occasions when you must remove *const-ness* from a variable. For more information, see [Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). +A **`const`** type is distinct from its non-**`const`** version; for example, **`const int`** is a distinct type from **`int`**. You can use the C++ **`const_cast`** operator on those rare occasions when you must remove *const-ness* from a variable. For more information, see [Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). ## String types -Strictly speaking, the C++ language has no built-in string type; **`char`** and **`wchar_t`** store single characters - you must declare an array of these types to approximate a string, adding a terminating null value (for example, ASCII `'\0'`) to the array element one past the last valid character (also called a *C-style string*). C-style strings required much more code to be written or the use of external string utility library functions. But in modern C++, we have the Standard Library types `std::string` (for 8-bit **`char`**-type character strings) or `std::wstring` (for 16-bit **`wchar_t`**-type character strings). These C++ Standard Library containers can be thought of as native string types because they are part of the standard libraries that are included in any conformant C++ build environment. Simply use the `#include ` directive to make these types available in your program. (If you are using MFC or ATL, the `CString` class is also available, but is not part of the C++ standard.) The use of null-terminated character arrays (the C-style strings previously mentioned) is strongly discouraged in modern C++. +Strictly speaking, the C++ language has no built-in string type; **`char`** and **`wchar_t`** store single characters - you must declare an array of these types to approximate a string, adding a terminating null value (for example, ASCII `'\0'`) to the array element one past the last valid character (also called a *C-style string*). C-style strings required much more code to be written or the use of external string utility library functions. But in modern C++, we have the Standard Library types `std::string` (for 8-bit **`char`**-type character strings) or `std::wstring` (for 16-bit **`wchar_t`**-type character strings). These C++ Standard Library containers can be thought of as native string types because they're part of the standard libraries that are included in any conformant C++ build environment. Use the `#include ` directive to make these types available in your program. (If you're using MFC or ATL, the `CString` class is also available, but isn't part of the C++ standard.) The use of null-terminated character arrays (the C-style strings previously mentioned) is discouraged in modern C++. ## User-defined types @@ -97,13 +99,15 @@ When you define a **`class`**, **`struct`**, **`union`**, or **`enum`**, that co - The compiler has no built-in knowledge of a user-defined type. It learns of the type when it first encounters the definition during the compilation process. -- You specify what operations can be performed on your type, and how it can be converted to other types, by defining (through overloading) the appropriate operators, either as class members or non-member functions. For more information, see [Function Overloading](function-overloading.md) +- You specify what operations can be performed on your type, and how it can be converted to other types, by defining (through overloading) the appropriate operators, either as class members or non-member functions. For more information, see [Function overloading](function-overloading.md) ## Pointer types -Dating back to the earliest versions of the C language, C++ continues to let you declare a variable of a pointer type by using the special declarator **`*`** (asterisk). A pointer type stores the address of the location in memory where the actual data value is stored. In modern C++, these are referred to as *raw pointers*, and are accessed in your code through special operators **`*`** (asterisk) or **`->`** (dash with greater-than). This is called *dereferencing*, and which one that you use depends on whether you are dereferencing a pointer to a scalar or a pointer to a member in an object. Working with pointer types has long been one of the most challenging and confusing aspects of C and C++ program development. This section outlines some facts and practices to help use raw pointers if you want to, but in modern C++ it’s no longer required (or recommended) to use raw pointers for object ownership at all, due to the evolution of the [smart pointer](../cpp/smart-pointers-modern-cpp.md) (discussed more at the end of this section). It is still useful and safe to use raw pointers for observing objects, but if you must use them for object ownership, you should do so with caution and very careful consideration of how the objects owned by them are created and destroyed. +As in the earliest versions of the C language, C++ continues to let you declare a variable of a pointer type by using the special declarator **`*`** (asterisk). A pointer type stores the address of the location in memory where the actual data value is stored. In modern C++, these pointer types are referred to as *raw pointers*, and they're accessed in your code through special operators: **`*`** (asterisk) or **`->`** (dash with greater-than, often called *arrow*). This memory access operation is called *dereferencing*. Which operator you use depends on whether you're dereferencing a pointer to a scalar, or a pointer to a member in an object. + +Working with pointer types has long been one of the most challenging and confusing aspects of C and C++ program development. This section outlines some facts and practices to help use raw pointers if you want to. However, in modern C++, it's no longer required (or recommended) to use raw pointers for object ownership at all, due to the evolution of the [smart pointer](../cpp/smart-pointers-modern-cpp.md) (discussed more at the end of this section). It's still useful and safe to use raw pointers for observing objects. However, if you must use them for object ownership, you should do so with caution and with careful consideration of how the objects owned by them are created and destroyed. -The first thing that you should know is declaring a raw pointer variable will allocate only the memory that is required to store an address of the memory location that the pointer will be referring to when it is dereferenced. Allocation of the memory for the data value itself (also called *backing store*) is not yet allocated. In other words, by declaring a raw pointer variable, you are creating a memory address variable, not an actual data variable. Dereferencing a pointer variable before making sure that it contains a valid address to a backing store will cause undefined behavior (usually a fatal error) in your program. The following example demonstrates this kind of error: +The first thing that you should know is that a raw pointer variable declaration only allocates enough memory to store an address: the memory location that the pointer refers to when it's dereferenced. The pointer declaration doesn't allocate the memory needed to store the data value. (That memory is also called the *backing store*.) In other words, by declaring a raw pointer variable, you're creating a memory address variable, not an actual data variable. If you dereference a pointer variable before you've made sure that it contains a valid address for a backing store, it causes undefined behavior (usually a fatal error) in your program. The following example demonstrates this kind of error: ```cpp int* pNumber; // Declare a pointer-to-int variable. @@ -129,9 +133,9 @@ The example dereferences a pointer type without having any memory allocated to s // "pNumber". ``` -The corrected code example uses local stack memory to create the backing store that `pNumber` points to. We use a fundamental type for simplicity. In practice, the backing store for pointers are most often user-defined types that are dynamically-allocated in an area of memory called the *heap* (or *free store*) by using a **`new`** keyword expression (in C-style programming, the older `malloc()` C runtime library function was used). Once allocated, these variables are usually referred to as objects, especially if they are based on a class definition. Memory that is allocated with **`new`** must be deleted by a corresponding **`delete`** statement (or, if you used the `malloc()` function to allocate it, the C runtime function `free()`). +The corrected code example uses local stack memory to create the backing store that `pNumber` points to. We use a fundamental type for simplicity. In practice, the backing stores for pointers are most often user-defined types that are dynamically allocated in an area of memory called the *heap* (or *free store*) by using a **`new`** keyword expression (in C-style programming, the older `malloc()` C runtime library function was used). Once allocated, these variables are normally referred to as *objects*, especially if they're based on a class definition. Memory that is allocated with **`new`** must be deleted by a corresponding **`delete`** statement (or, if you used the `malloc()` function to allocate it, the C runtime function `free()`). -However, it is easy to forget to delete a dynamically-allocated object- especially in complex code, which causes a resource bug called a *memory leak*. For this reason, the use of raw pointers is strongly discouraged in modern C++. It is almost always better to wrap a raw pointer in a [smart pointer](../cpp/smart-pointers-modern-cpp.md), which will automatically release the memory when its destructor is invoked (when the code goes out of scope for the smart pointer); by using smart pointers you virtually eliminate a whole class of bugs in your C++ programs. In the following example, assume `MyClass` is a user-defined type that has a public method `DoSomeWork();` +However, it's easy to forget to delete a dynamically allocated object- especially in complex code, which causes a resource bug called a *memory leak*. For this reason, the use of raw pointers is discouraged in modern C++. It's almost always better to wrap a raw pointer in a [smart pointer](../cpp/smart-pointers-modern-cpp.md), which automatically releases the memory when its destructor is invoked. (That is, when the code goes out of scope for the smart pointer.) By using smart pointers, you virtually eliminate a whole class of bugs in your C++ programs. In the following example, assume `MyClass` is a user-defined type that has a public method `DoSomeWork();` ```cpp void someFunction() { @@ -142,28 +146,28 @@ void someFunction() { // for the unique_ptr, freeing the resource. ``` -For more information about smart pointers, see [Smart Pointers](../cpp/smart-pointers-modern-cpp.md). +For more information about smart pointers, see [Smart pointers](../cpp/smart-pointers-modern-cpp.md). -For more information about pointer conversions, see [Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). +For more information about pointer conversions, see [Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md). For more information about pointers in general, see [Pointers](../cpp/pointers-cpp.md). ## Windows data types -In classic Win32 programming for C and C++, most functions use Windows-specific typedefs and `#define` macros (defined in `windef.h`) to specify the types of parameters and return values. These Windows data types are mostly just special names (aliases) given to C/C++ built-in types. For a complete list of these typedefs and preprocessor definitions, see [Windows Data Types](/windows/win32/WinProg/windows-data-types). Some of these typedefs, such as `HRESULT` and `LCID`, are useful and descriptive. Others, such as `INT`, have no special meaning and are just aliases for fundamental C++ types. Other Windows data types have names that are retained from the days of C programming and 16-bit processors, and have no purpose or meaning on modern hardware or operating systems. There are also special data types associated with the Windows Runtime Library, listed as [Windows Runtime base data types](/windows/win32/WinRT/base-data-types). In modern C++, the general guideline is to prefer the C++ fundamental types unless the Windows type communicates some additional meaning about how the value is to be interpreted. +In classic Win32 programming for C and C++, most functions use Windows-specific typedefs and `#define` macros (defined in `windef.h`) to specify the types of parameters and return values. These Windows data types are mostly special names (aliases) given to C/C++ built-in types. For a complete list of these typedefs and preprocessor definitions, see [Windows Data Types](/windows/win32/WinProg/windows-data-types). Some of these typedefs, such as `HRESULT` and `LCID`, are useful and descriptive. Others, such as `INT`, have no special meaning and are just aliases for fundamental C++ types. Other Windows data types have names that are retained from the days of C programming and 16-bit processors, and have no purpose or meaning on modern hardware or operating systems. There are also special data types associated with the Windows Runtime Library, listed as [Windows Runtime base data types](/windows/win32/WinRT/base-data-types). In modern C++, the general guideline is to prefer the C++ fundamental types unless the Windows type communicates some extra meaning about how the value is to be interpreted. ## More information -For more information about the C++ type system, see the following topics. +For more information about the C++ type system, see the following articles. -[Value Types](../cpp/value-types-modern-cpp.md)\ +[Value types](../cpp/value-types-modern-cpp.md)\ Describes *value types* along with issues relating to their use. -[Type Conversions and Type Safety](../cpp/type-conversions-and-type-safety-modern-cpp.md)\ +[Type conversions and type safety](../cpp/type-conversions-and-type-safety-modern-cpp.md)\ Describes common type conversion issues and shows how to avoid them. ## See also -[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)
-[C++ Language Reference](../cpp/cpp-language-reference.md)
+[Welcome back to C++](../cpp/welcome-back-to-cpp-modern-cpp.md)\ +[C++ language reference](../cpp/cpp-language-reference.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/cpp/data-type-ranges.md b/docs/cpp/data-type-ranges.md index 3e2e319429c..eb511339251 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 253de9e94dd..443a140a7cb 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 7596557a30d..a223db3db59 100644 --- a/docs/cpp/decltype-cpp.md +++ b/docs/cpp/decltype-cpp.md @@ -1,98 +1,97 @@ --- -description: "Learn more about: decltype (C++)" -title: "decltype (C++)" -ms.date: "11/04/2016" +title: "decltype (C++)" +description: "Learn more about: decltype (C++)" +ms.date: 09/14/2023 f1_keywords: ["decltype_cpp"] helpviewer_keywords: ["operators [C++], decltype", "decltype operator", "operators [C++], type of an expression", "operators [C++], deduce expression type"] -ms.assetid: 6dcf8888-8196-4f13-af50-51e3797255d4 --- -# decltype (C++) +# `decltype` (C++) -The **`decltype`** type specifier yields the type of a specified expression. The **`decltype`** type specifier, together with the [`auto` keyword](../cpp/auto-cpp.md), is useful primarily to developers who write template libraries. Use **`auto`** and **`decltype`** to declare a template function whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a template function that wraps a call to another function, and then returns the return type of the wrapped function. +The **`decltype`** type specifier yields the type of a specified expression. The **`decltype`** type specifier, together with the [`auto` keyword](../cpp/auto-cpp.md), is useful primarily to developers who write template libraries. Use **`auto`** and **`decltype`** to declare a function template whose return type depends on the types of its template arguments. Or, use **`auto`** and **`decltype`** to declare a function template that wraps a call to another function, and then returns the return type of the wrapped function. ## Syntax -> **`decltype(`** *expression* **`)`** +> **`decltype(`** *`expression`* **`)`** ### Parameters -*expression*\ +*`expression`*\ An expression. For more information, see [Expressions](../cpp/expressions-cpp.md). -## Return Value +## Return value -The type of the *expression* parameter. +The type of the *`expression`* parameter. ## Remarks The **`decltype`** type specifier is supported in Visual Studio 2010 or later versions, and can be used with native or managed code. `decltype(auto)` (C++14) is supported in Visual Studio 2015 and later. -The compiler uses the following rules to determine the type of the *expression* parameter. +The compiler uses the following rules to determine the type of the *`expression`* parameter. -- If the *expression* parameter is an identifier or a [class member access](../cpp/member-access-operators-dot-and.md), `decltype(expression)` is the type of the entity named by *expression*. If there is no such entity or the *expression* parameter names a set of overloaded functions, the compiler yields an error message. +- If the *`expression`* parameter is an identifier or a [class member access](../cpp/member-access-operators-dot-and.md), `decltype(expression)` is the type of the entity named by *`expression`*. If there's no such entity or the *`expression`* parameter names a set of overloaded functions, the compiler yields an error message. -- If the *expression* parameter is a call to a function or an overloaded operator function, `decltype(expression)` is the return type of the function. Parentheses around an overloaded operator are ignored. +- If the *`expression`* parameter is a call to a function or an overloaded operator function, `decltype(expression)` is the return type of the function. Parentheses around an overloaded operator are ignored. -- If the *expression* parameter is an [rvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is the type of *expression*. If the *expression* parameter is an [lvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is an [lvalue reference](../cpp/lvalue-reference-declarator-amp.md) to the type of *expression*. +- If the *`expression`* parameter is an [rvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is the type of *`expression`*. If the *`expression`* parameter is an [lvalue](../cpp/lvalues-and-rvalues-visual-cpp.md), `decltype(expression)` is an [lvalue reference](../cpp/lvalue-reference-declarator-amp.md) to the type of *`expression`*. -The following code example demonstrates some uses of the **`decltype`** type specifier. First, assume that you have coded the following statements. +The following code example demonstrates some uses of the **`decltype`** type specifier. First, assume that you've coded the following statements. ```cpp int var; const int&& fx(); -struct A { double x; } +struct A { double x; }; const A* a = new A(); ``` Next, examine the types that are returned by the four **`decltype`** statements in the following table. -|Statement|Type|Notes| -|---------------|----------|-----------| -|`decltype(fx());`|`const int&&`|An [rvalue reference](../cpp/rvalue-reference-declarator-amp-amp.md) to a **`const int`**.| -|`decltype(var);`|**`int`**|The type of variable `var`.| -|`decltype(a->x);`|**`double`**|The type of the member access.| -|`decltype((a->x));`|`const double&`|The inner parentheses cause the statement to be evaluated as an expression instead of a member access. And because `a` is declared as a **`const`** pointer, the type is a reference to **`const double`**.| +| Statement | Type | Notes | +|--|--|--| +| `decltype(fx());` | `const int&&` | An [rvalue reference](../cpp/rvalue-reference-declarator-amp-amp.md) to a **`const int`**. | +| `decltype(var);` | **`int`** | The type of variable `var`. | +| `decltype(a->x);` | **`double`** | The type of the member access. | +| `decltype((a->x));` | `const double&` | The inner parentheses cause the statement to be evaluated as an expression instead of a member access. And because `a` is declared as a **`const`** pointer, the type is a reference to **`const double`**. | -## Decltype and Auto +## `decltype` and `auto` -In C++14, you can use `decltype(auto)` with no trailing return type to declare a template function whose return type depends on the types of its template arguments. +In C++14, you can use `decltype(auto)` with no trailing return type to declare a function template whose return type depends on the types of its template arguments. -In C++11, you can use the **`decltype`** type specifier on a trailing return type, together with the **`auto`** keyword, to declare a template function whose return type depends on the types of its template arguments. For example, consider the following code example in which the return type of the template function depends on the types of the template arguments. In the code example, the *UNKNOWN* placeholder indicates that the return type cannot be specified. +In C++11, you can use the **`decltype`** type specifier on a trailing return type, together with the **`auto`** keyword, to declare a function template whose return type depends on the types of its template arguments. For example, consider the following code example in which the return type of the function template depends on the types of the template arguments. In the code example, the *`UNKNOWN`* placeholder indicates that the return type can't be specified. ```cpp template -UNKNOWN func(T&& t, U&& u){ return t + u; }; +UNKNOWN func(T&& t, U&& u){ return t + u; } ``` -The introduction of the **`decltype`** type specifier enables a developer to obtain the type of the expression that the template function returns. Use the *alternative function declaration syntax* that is shown later, the **`auto`** keyword, and the **`decltype`** type specifier to declare a *late-specified* return type. The late-specified return type is determined when the declaration is compiled, instead of when it is coded. +The introduction of the **`decltype`** type specifier enables a developer to obtain the type of the expression that the function template returns. Use the *alternative function declaration syntax* that is shown later, the **`auto`** keyword, and the **`decltype`** type specifier to declare a *late-specified* return type. The late-specified return type is determined when the declaration is compiled, instead of when it's coded. -The following prototype illustrates the syntax of an alternative function declaration. Note that the **`const`** and **`volatile`** qualifiers, and the **`throw`** [exception specification](../cpp/exception-specifications-throw-cpp.md) are optional. The *function_body* placeholder represents a compound statement that specifies what the function does. As a best coding practice, the *expression* placeholder in the **`decltype`** statement should match the expression specified by the **`return`** statement, if any, in the *function_body*. +The following prototype illustrates the syntax of an alternative function declaration. The **`const`** and **`volatile`** qualifiers, and the **`throw`** [exception specification](../cpp/exception-specifications-throw-cpp.md) are optional. The *`function_body`* placeholder represents a compound statement that specifies what the function does. As a best coding practice, the *`expression`* placeholder in the **`decltype`** statement should match the expression specified by the **`return`** statement, if any, in the *`function_body`*. -**`auto`** *function_name* **`(`** *parameters*opt **`)`** **`const`**opt **`volatile`**opt **`->`** **`decltype(`** *expression* **`)`** **`noexcept`**opt **`{`** *function_body* **`};`** +**`auto`** *`function_name`* **`(`** *`parameters`*opt **`)`** **`const`**opt **`volatile`**opt **`->`** **`decltype(`** *`expression`* **`)`** **`noexcept`**opt **`{`** *`function_body`* **`};`** -In the following code example, the late-specified return type of the `myFunc` template function is determined by the types of the `t` and `u` template arguments. As a best coding practice, the code example also uses rvalue references and the `forward` function template, which support *perfect forwarding*. For more information, see [Rvalue Reference Declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). +In the following code example, the late-specified return type of the `myFunc` function template is determined by the types of the `t` and `u` template arguments. As a best coding practice, the code example also uses rvalue references and the `forward` function template, which support *perfect forwarding*. For more information, see [Rvalue reference declarator: &&](../cpp/rvalue-reference-declarator-amp-amp.md). ```cpp //C++11 template auto myFunc(T&& t, U&& u) -> decltype (forward(t) + forward(u)) - { return forward(t) + forward(u); }; + { return forward(t) + forward(u); } //C++14 template decltype(auto) myFunc(T&& t, U&& u) - { return forward(t) + forward(u); }; + { return forward(t) + forward(u); } ``` -## Decltype and Forwarding Functions (C++11) +## `decltype` and forwarding functions (C++11) Forwarding functions wrap calls to other functions. Consider a function template that forwards its arguments, or the results of an expression that involves those arguments, to another function. Furthermore, the forwarding function returns the result of calling the other function. In this scenario, the return type of the forwarding function should be the same as the return type of the wrapped function. -In this scenario, you cannot write an appropriate type expression without the **`decltype`** type specifier. The **`decltype`** type specifier enables generic forwarding functions because it does not lose required information about whether a function returns a reference type. For a code example of a forwarding function, see the previous `myFunc` template function example. +In this scenario, you can't write an appropriate type expression without the **`decltype`** type specifier. The **`decltype`** type specifier enables generic forwarding functions because it doesn't lose required information about whether a function returns a reference type. For a code example of a forwarding function, see the previous `myFunc` function template example. ## Examples -The following code example declares the late-specified return type of template function `Plus()`. The `Plus` function processes its two operands with the **`operator+`** overload. Consequently, the interpretation of the plus operator (**`+`**) and the return type of the `Plus` function depends on the types of the function arguments. +The following code example declares the late-specified return type of function template `Plus()`. The `Plus` function processes its two operands with the **`operator+`** overload. So, the interpretation of the plus operator (**`+`**) and the return type of the `Plus` function depends on the types of the function arguments. ```cpp // decltype_1.cpp @@ -164,7 +163,7 @@ Hello, world! x3.Dump() = 42 ``` -**Visual Studio 2017 and later:** The compiler parses **`decltype`** arguments when the templates are declared rather than instantiated. Consequently, if a non-dependent specialization is found in the **`decltype`** argument, it will not be deferred to instantiation-time and will be processed immediately and any resulting errors will be diagnosed at that time. +**Visual Studio 2017 and later:** The compiler parses **`decltype`** arguments when the templates are declared rather than instantiated. So, if a non-dependent specialization is found in the **`decltype`** argument, it won't be deferred to instantiation-time; it's processed immediately and any resulting errors are diagnosed at that time. The following example shows such a compiler error that is raised at the point of declaration: diff --git a/docs/cpp/delegating-constructors.md b/docs/cpp/delegating-constructors.md index bca843faa6d..0760096e488 100644 --- a/docs/cpp/delegating-constructors.md +++ b/docs/cpp/delegating-constructors.md @@ -57,7 +57,7 @@ int main() { As you step through the previous example, notice that the constructor `class_c(int, int, int)` first calls the constructor `class_c(int, int)`, which in turn calls `class_c(int)`. Each of the constructors performs only the work that is not performed by the other constructors. -The first constructor that's called initializes the object so that all of its members are initialized at that point. You can’t do member initialization in a constructor that delegates to another constructor, as shown here: +The first constructor that's called initializes the object so that all of its members are initialized at that point. You can't do member initialization in a constructor that delegates to another constructor, as shown here: ```cpp class class_a { @@ -66,7 +66,7 @@ public: // member initialization here, no delegate class_a(string str) : m_string{ str } {} - //can’t do member initialization here + //can't do member initialization here // error C3511: a call to a delegating constructor shall be the only member-initializer class_a(string str, double dbl) : class_a(str) , m_double{ dbl } {} diff --git a/docs/cpp/destructors-cpp.md b/docs/cpp/destructors-cpp.md index feeb87d6a57..f1a95449acf 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 be9b5b3b3bd..e19dca76282 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 6093be23a73..cf31a138182 100644 --- a/docs/cpp/dynamic-cast-operator.md +++ b/docs/cpp/dynamic-cast-operator.md @@ -4,7 +4,6 @@ description: "Overview of the C++ language dynamic_cast operator." ms.date: "02/03/2020" f1_keywords: ["dynamic_cast_cpp"] helpviewer_keywords: ["dynamic_cast keyword [C++]"] -ms.assetid: f380ada8-6a18-4547-93c9-63407f19856b --- # dynamic_cast Operator @@ -20,15 +19,15 @@ dynamic_cast < type-id > ( expression ) The `type-id` must be a pointer or a reference to a previously defined class type or a "pointer to void". The type of `expression` must be a pointer if `type-id` is a pointer, or an l-value if `type-id` is a reference. -See [static_cast](../cpp/static-cast-operator.md) for an explanation of the difference between static and dynamic casting conversions, and when it is appropriate to use each. +See [static_cast](../cpp/static-cast-operator.md) for an explanation of the difference between static and dynamic casting conversions, and when it's appropriate to use each. There are two breaking changes in the behavior of **`dynamic_cast`** in managed code: - **`dynamic_cast`** to a pointer to the underlying type of a boxed enum will fail at runtime, returning 0 instead of the converted pointer. -- **`dynamic_cast`** will no longer throw an exception when `type-id` is an interior pointer to a value type, with the cast failing at runtime. The cast will now return the 0 pointer value instead of throwing. +- **`dynamic_cast`** will no longer throw an exception when `type-id` is an interior pointer to a value type; instead, the cast fails at runtime. The cast returns the 0 pointer value instead of throwing. -If `type-id` is a pointer to an unambiguous accessible direct or indirect base class of `expression`, a pointer to the unique subobject of type `type-id` is the result. For example: +If `type-id` is a pointer to an unambiguous accessible direct or indirect base class of `expression`, then a pointer to the unique subobject of type `type-id` is the result. For example: ```cpp // dynamic_cast_1.cpp @@ -45,7 +44,7 @@ void f(D* pd) { } ``` -This type of conversion is called an "upcast" because it moves a pointer up a class hierarchy, from a derived class to a class it is derived from. An upcast is an implicit conversion. +This type of conversion is called an "upcast" because it moves a pointer up a class hierarchy, from a derived class to a class it's derived from. An upcast is an implicit conversion. If `type-id` is void*, a run-time check is made to determine the actual type of `expression`. The result is a pointer to the complete object pointed to by `expression`. For example: @@ -66,7 +65,7 @@ void f() { } ``` -If `type-id` is not void*, a run-time check is made to see if the object pointed to by `expression` can be converted to the type pointed to by `type-id`. +If `type-id` isn't `void*`, a run-time check is made to see if the object pointed to by `expression` can be converted to the type pointed to by `type-id`. If the type of `expression` is a base class of the type of `type-id`, a run-time check is made to see if `expression` actually points to a complete object of the type of `type-id`. If this is true, the result is a pointer to a complete object of the type of `type-id`. For example: @@ -114,8 +113,9 @@ int main() { } ``` -![Class hierarchy that shows multiple inheritance.](../cpp/media/vc39011.gif "Class hierarchy that shows multiple inheritance")
-Class hierarchy that shows multiple inheritance +:::image type="complex" source="../cpp/media/vc39011.gif" alt-text="Diagram that shows multiple inheritance."::: +The diagram shows a class hierarchy with A as a base class of B which is a base class of D. A is also a base class for C, which is a base class for D. Class D inherits from both B and C. +:::image-end::: A pointer to an object of type `D` can be safely cast to `B` or `C`. However, if `D` is cast to point to an `A` object, which instance of `A` would result? This would result in an ambiguous casting error. To get around this problem, you can perform two unambiguous casts. For example: @@ -137,14 +137,18 @@ void f() { Further ambiguities can be introduced when you use virtual base classes. Consider the class hierarchy shown in the following figure. -![Class hierarchy that shows virtual base classes.](../cpp/media/vc39012.gif "Class hierarchy that shows virtual base classes")
+:::image type="complex" source="../cpp/media/vc39012.gif" alt-text="Diagram of a class hierarchy that shows virtual base classes."::: +The diagram shows the classes A, B, C, D, and E arranged as follows: Class A is a base class of B. Classes C and E each derive from B. Class E also inherits from D, which inherits from class B, which inherits from class A. +:::image-end::: Class hierarchy that shows virtual base classes -In this hierarchy, `A` is a virtual base class. Given an instance of class `E` and a pointer to the `A` subobject, a **`dynamic_cast`** to a pointer to `B` will fail due to ambiguity. You must first cast back to the complete `E` object, then work your way back up the hierarchy, in an unambiguous manner, to reach the correct `B` object. +In this hierarchy, `A` is a virtual base class. Given an instance of class `E` and a pointer to the `A` subobject, a **`dynamic_cast`** to a pointer to `B` fails due to ambiguity. You must first cast back to the complete `E` object, then work your way back up the hierarchy, in an unambiguous manner, to reach the correct `B` object. Consider the class hierarchy shown in the following figure. -![Class hierarchy that shows duplicate base classes.](../cpp/media/vc39013.gif "Class hierarchy that shows duplicate base classes")
+:::image type="complex" source="../cpp/media/vc39013.gif" alt-text="Diagram of a class hierarchy that shows duplicate base classes."::: +The diagram shows the classes A, B, C, D, and E arranged as follows: Class B derives from Class A. Class C derives from class A. class D derives from class B. Class E derives from class C, which derives from class A. In this case, the duplicate base class is class A, which is directly or indirectly inherited by all the other classes. Class A is inherited directly by classes B and C, and indirectly by class D via class B, and indirectly by class E via class C, and indirectly in class D via class B. +:::image-end::: Class hierarchy that shows duplicate base classes Given an object of type `E` and a pointer to the `D` subobject, to navigate from the `D` subobject to the left-most `A` subobject, three conversions can be made. You can perform a **`dynamic_cast`** conversion from the `D` pointer to an `E` pointer, then a conversion (either **`dynamic_cast`** or an implicit conversion) from `E` to `B`, and finally an implicit conversion from `B` to `A`. For example: @@ -165,9 +169,9 @@ void f(D* pd) { } ``` -The **`dynamic_cast`** operator can also be used to perform a "cross cast." Using the same class hierarchy, it is possible to cast a pointer, for example, from the `B` subobject to the `D` subobject, as long as the complete object is of type `E`. +The **`dynamic_cast`** operator can also be used to perform a "cross cast." Using the same class hierarchy, it's possible to cast a pointer, for example, from the `B` subobject to the `D` subobject, as long as the complete object is of type `E`. -Considering cross casts, it is actually possible to do the conversion from a pointer to `D` to a pointer to the left-most `A` subobject in just two steps. You can perform a cross cast from `D` to `B`, then an implicit conversion from `B` to `A`. For example: +Considering cross casts, it's possible to do the conversion from a pointer to `D` to a pointer to the left-most `A` subobject in just two steps. You can perform a cross cast from `D` to `B`, then an implicit conversion from `B` to `A`. For example: ```cpp // dynamic_cast_6.cpp @@ -186,7 +190,7 @@ void f(D* pd) { A null pointer value is converted to the null pointer value of the destination type by **`dynamic_cast`**. -When you use `dynamic_cast < type-id > ( expression )`, if `expression` cannot be safely converted to type `type-id`, the run-time check causes the cast to fail. For example: +When you use `dynamic_cast < type-id > ( expression )`, if `expression` can't be safely converted to type `type-id`, the run-time check causes the cast to fail. For example: ```cpp // dynamic_cast_7.cpp @@ -201,7 +205,7 @@ void f() { } ``` -The value of a failed cast to pointer type is the null pointer. A failed cast to reference type throws a [bad_cast Exception](../cpp/bad-cast-exception.md). If `expression` does not point to or reference a valid object, a `__non_rtti_object` exception is thrown. +The value of a failed cast to pointer type is the null pointer. A failed cast to reference type throws a [bad_cast Exception](../cpp/bad-cast-exception.md). If `expression` doesn't point to or reference a valid object, a `__non_rtti_object` exception is thrown. See [typeid](../cpp/typeid-operator.md) for an explanation of the `__non_rtti_object` exception. @@ -209,7 +213,7 @@ See [typeid](../cpp/typeid-operator.md) for an explanation of the `__non_rtti_ob The following sample creates the base class (struct A) pointer, to an object (struct C). This, plus the fact there are virtual functions, enables runtime polymorphism. -The sample also calls a non-virtual function in the hierarchy. +The sample also calls a nonvirtual function in the hierarchy. ```cpp // dynamic_cast_8.cpp @@ -270,7 +274,7 @@ int main() { C ConStack; Globaltest(ConStack); - // will fail because B knows nothing about C + // fails because B knows nothing about C B BonStack; Globaltest(BonStack); } diff --git a/docs/cpp/ellipses-and-variadic-templates.md b/docs/cpp/ellipses-and-variadic-templates.md index a2d3467566c..a7e40b2769b 100644 --- a/docs/cpp/ellipses-and-variadic-templates.md +++ b/docs/cpp/ellipses-and-variadic-templates.md @@ -1,40 +1,40 @@ --- -description: "Learn more about: Ellipsis and Variadic Templates" -title: "Ellipsis and Variadic Templates" -ms.date: "11/04/2016" +description: "Learn more about: Ellipsis and variadic templates" +title: "Ellipsis and variadic templates" +ms.date: 09/27/2022 ms.assetid: f20967d9-c967-4fd2-b902-2bb1d5ed87e3 --- -# Ellipsis and Variadic Templates +# Ellipsis and variadic templates This article shows how to use the ellipsis (`...`) with C++ variadic templates. The ellipsis has had many uses in C and C++. These include variable argument lists for functions. The `printf()` function from the C Runtime Library is one of the most well-known examples. -A *variadic template* is a class or function template that supports an arbitrary number of arguments. This mechanism is especially useful to C++ library developers because you can apply it to both class templates and function templates, and thereby provide a wide range of type-safe and non-trivial functionality and flexibility. +A *variadic template* is a class or function template that supports an arbitrary number of arguments. This mechanism is especially useful to C++ library developers: You can apply it to both class templates and function templates, and thereby provide a wide range of type-safe and non-trivial functionality and flexibility. ## Syntax An ellipsis is used in two ways by variadic templates. To the left of the parameter name, it signifies a *parameter pack*, and to the right of the parameter name, it expands the parameter packs into separate names. -Here's a basic example of *variadic template class* definition syntax: +Here's a basic example of *variadic class template* definition syntax: ```cpp template class classname; ``` -For both parameter packs and expansions, you can add whitespace around the ellipsis, based on your preference, as shown in these examples: +For both parameter packs and expansions, you can add whitespace around the ellipsis, based on your preference, as shown in this example: ```cpp template class classname; ``` -Or this: +Or this example: ```cpp template class classname; ``` -Notice that this article uses the convention that's shown in the first example (the ellipsis is attached to **`typename`**). +This article uses the convention that's shown in the first example (the ellipsis is attached to **`typename`**). -In the preceding examples, *Arguments* is a parameter pack. The class `classname` can accept a variable number of arguments, as in these examples: +In the preceding examples, *`Arguments`* is a parameter pack. The class `classname` can accept a variable number of arguments, as in these examples: ```cpp template class vtclass; @@ -45,21 +45,21 @@ vtclass vtinstance3; vtclass, std::string> vtinstance4; ``` -By using a variadic template class definition, you can also require at least one parameter: +By using a variadic class template definition, you can also require at least one parameter: ```cpp template class classname; ``` -Here's a basic example of *variadic template function* syntax: +Here's a basic example of *variadic function template* syntax: ```cpp template returntype functionname(Arguments... args); ``` -The *Arguments* parameter pack is then expanded for use, as shown in the next section, **Understanding variadic templates**. +The *`Arguments`* parameter pack is then expanded for use, as shown in the next section. -Other forms of variadic template function syntax are possible—including, but not limited to, these examples: +Other forms of variadic function template syntax are possible—including, but not limited to, these examples: ```cpp template returntype functionname(Arguments&... args); @@ -95,7 +95,7 @@ void tfunc(const Arguments&... args) ## More about ellipsis placement -Previously, this article described ellipsis placement that defines parameter packs and expansions as "to the left of the parameter name, it signifies a parameter pack, and to the right of the parameter name, it expands the parameter packs into separate names". This is technically true but can be confusing in translation to code. Consider: +Previously, this article described ellipsis placement that defines parameter packs and expansions in this form: "to the left of the parameter name, it signifies a parameter pack, and to the right of the parameter name, it expands the parameter packs into separate names". While technically true, it can be confusing in translation to code. Consider: - In a template-parameter-list (`template `), `typename...` introduces a template parameter pack. @@ -113,7 +113,7 @@ Previously, this article described ellipsis placement that defines parameter pac ## Example -A good way to illustrate the variadic template function mechanism is to use it in a re-write of some of the functionality of `printf`: +A good way to illustrate the variadic function template mechanism is to use it in a rewrite of some of the functionality of `printf`: ```cpp #include @@ -156,4 +156,4 @@ first, 2, third, 3.14159 ``` > [!NOTE] -> Most implementations that incorporate variadic template functions use recursion of some form, but it's slightly different from traditional recursion. Traditional recursion involves a function calling itself by using the same signature. (It may be overloaded or templated, but the same signature is chosen each time.) Variadic recursion involves calling a variadic function template by using differing (almost always decreasing) numbers of arguments, and thereby stamping out a different signature every time. A "base case" is still required, but the nature of the recursion is different. +> Most implementations that incorporate variadic function templates use recursion of some form, but it's slightly different from traditional recursion. Traditional recursion involves a function calling itself by using the same signature. (It may be overloaded or templated, but the same signature is chosen each time.) Variadic recursion involves calling a variadic function template by using differing (almost always decreasing) numbers of arguments, and thereby stamping out a different signature every time. A "base case" is still required, but the nature of the recursion is different. diff --git a/docs/cpp/enumerations-cpp.md b/docs/cpp/enumerations-cpp.md index ff818007577..bce6d27a4e5 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 9701cac39f6..c0853757bba 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 d9feec12664..3140848fae8 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.topic: "conceptual" -ms.assetid: a6c111d0-24f9-4bbb-997d-3db4569761b7 +ms.date: 03/22/2024 +ms.topic: "best-practice" --- # Modern C++ best practices for exceptions and error handling @@ -11,19 +10,20 @@ In modern C++, in most scenarios, the preferred way to report and handle both lo ## Use exceptions for exceptional code -Program errors are often divided into two categories: Logic errors that are caused by programming mistakes, for example, an "index out of range" error. And, runtime errors that are beyond the control of programmer, for example, a "network service unavailable" error. In C-style programming and in COM, error reporting is managed either by returning a value that represents an error code or a status code for a particular function, or by setting a global variable that the caller may optionally retrieve after every function call to see whether errors were reported. For example, COM programming uses the HRESULT return value to communicate errors to the caller. And the Win32 API has the `GetLastError` function to retrieve the last error that was reported by the call stack. In both of these cases, it's up to the caller to recognize the code and respond to it appropriately. If the caller doesn't explicitly handle the error code, the program might crash without warning. Or, it might continue to execute using bad data and produce incorrect results. +Program errors are often divided into two categories: +- Logic errors caused by programming mistakes. For example, an "index out of range" error. +- Runtime errors that are beyond the control of programmer. For example, a "network service unavailable" error. + +In C-style programming and in COM, error reporting is managed either by returning a value that represents an error code or a status code for a particular function, or by setting a global variable that the caller may optionally retrieve after every function call to see whether errors were reported. For example, COM programming uses the `HRESULT` return value to communicate errors to the caller. And the Win32 API has the `GetLastError` function to retrieve the last error reported by the call stack. In both of these cases, it's up to the caller to recognize the code and respond to it appropriately. If the caller doesn't explicitly handle the error code, the program might crash without warning. Or, it might continue to execute using bad data and produce incorrect results. Exceptions are preferred in modern C++ for the following reasons: - An exception forces calling code to recognize an error condition and handle it. Unhandled exceptions stop program execution. - - An exception jumps to the point in the call stack that can handle the error. Intermediate functions can let the exception propagate. They don't have to coordinate with other layers. - - The exception stack-unwinding mechanism destroys all objects in scope after an exception is thrown, according to well-defined rules. - - An exception enables a clean separation between the code that detects the error and the code that handles the error. -The following simplified example shows the necessary syntax for throwing and catching exceptions in C++. +The following simplified example shows the necessary syntax for throwing and catching exceptions in C++: ```cpp #include @@ -35,7 +35,9 @@ using namespace std; void MyFunc(int c) { if (c > numeric_limits< char> ::max()) + { throw invalid_argument("MyFunc argument too large."); + } //... } @@ -56,33 +58,27 @@ int main() } ``` -Exceptions in C++ resemble ones in languages such as C# and Java. In the **`try`** block, if an exception is *thrown* it will be *caught* by the first associated **`catch`** block whose type matches that of the exception. In other words, execution jumps from the **`throw`** statement to the **`catch`** statement. If no usable catch block is found, `std::terminate` is invoked and the program exits. In C++, any type may be thrown; however, we recommend that you throw a type that derives directly or indirectly from `std::exception`. In the previous example, the exception type, [`invalid_argument`](../standard-library/invalid-argument-class.md), is defined in the standard library in the [``](../standard-library/stdexcept.md) header file. C++ doesn't provide or require a **`finally`** block to make sure all resources are released if an exception is thrown. The resource acquisition is initialization (RAII) idiom, which uses smart pointers, provides the required functionality for resource cleanup. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). For information about the C++ stack-unwinding mechanism, see [Exceptions and stack unwinding](exceptions-and-stack-unwinding-in-cpp.md). +Exceptions in C++ resemble ones in languages such as C# and Java. In the **`try`** block, if an exception is *thrown* it is *caught* by the first associated **`catch`** block whose type matches that of the exception. In other words, execution jumps from the **`throw`** statement to the **`catch`** statement. If no usable catch block is found, `std::terminate` is invoked and the program exits. In C++, any type may be thrown; however, we recommend that you throw a type that derives directly or indirectly from `std::exception`. In the previous example, the exception type, [`invalid_argument`](../standard-library/invalid-argument-class.md), is defined in the standard library in the [``](../standard-library/stdexcept.md) header file. C++ doesn't provide or require a **`finally`** block to make sure all resources are released if an exception is thrown. The resource acquisition is initialization (RAII) idiom, which uses smart pointers, provides the required functionality for resource cleanup. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). For information about the C++ stack-unwinding mechanism, see [Exceptions and stack unwinding](exceptions-and-stack-unwinding-in-cpp.md). ## Basic guidelines Robust error handling is challenging in any programming language. Although exceptions provide several features that support good error handling, they can't do all the work for you. To realize the benefits of the exception mechanism, keep exceptions in mind as you design your code. -- Use asserts to check for errors that should never occur. Use exceptions to check for errors that might occur, for example, errors in input validation on parameters of public functions. For more information, see the [Exceptions versus assertions](#exceptions_versus_assertions) section. - +- Use asserts to check for conditions that should always be true or always be false. Use exceptions to check for errors that might occur, for example, errors in input validation on parameters of public functions. For more information, see the [Exceptions versus assertions](#exceptions_versus_assertions) section. - Use exceptions when the code that handles the error is separated from the code that detects the error by one or more intervening function calls. Consider whether to use error codes instead in performance-critical loops, when code that handles the error is tightly coupled to the code that detects it. - -- For every function that might throw or propagate an exception, provide one of the three exception guarantees: the strong guarantee, the basic guarantee, or the nothrow (noexcept) guarantee. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). - -- Throw exceptions by value, catch them by reference. Don’t catch what you can't handle. - +- For every function that might throw or propagate an exception, provide one of the three exception guarantees: the strong guarantee, the basic guarantee, or the nothrow (`noexcept`) guarantee. For more information, see [How to: Design for exception safety](how-to-design-for-exception-safety.md). +- Throw exceptions by value, catch them by reference. Don't catch what you can't handle. - Don't use exception specifications, which are deprecated in C++11. For more information, see the [Exception specifications and `noexcept`](#exception_specifications_and_noexcept) section. - - Use standard library exception types when they apply. Derive custom exception types from the [`exception` Class](../standard-library/exception-class.md) hierarchy. - - Don't allow exceptions to escape from destructors or memory-deallocation functions. ## Exceptions and performance -The exception mechanism has a minimal performance cost if no exception is thrown. If an exception is thrown, the cost of the stack traversal and unwinding is roughly comparable to the cost of a function call. Additional data structures are required to track the call stack after a **`try`** block is entered, and additional instructions are required to unwind the stack if an exception is thrown. However, in most scenarios, the cost in performance and memory footprint isn't significant. The adverse effect of exceptions on performance is likely to be significant only on memory-constrained systems. Or, in performance-critical loops, where an error is likely to occur regularly and there's tight coupling between the code to handle it and the code that reports it. In any case, it's impossible to know the actual cost of exceptions without profiling and measuring. Even in those rare cases when the cost is significant, you can weigh it against the increased correctness, easier maintainability, and other advantages that are provided by a well-designed exception policy. +The exception mechanism has a minimal performance cost if no exception is thrown. If an exception is thrown, the cost of the stack traversal and unwinding is roughly comparable to the cost of a function call. Other data structures are required to track the call stack after a **`try`** block is entered, and more instructions are required to unwind the stack if an exception is thrown. However, in most scenarios, the cost in performance and memory footprint isn't significant. The adverse effect of exceptions on performance is likely to be significant only on memory-constrained systems. Or, in performance-critical loops, where an error is likely to occur regularly and there's tight coupling between the code to handle it and the code that reports it. In any case, it's impossible to know the actual cost of exceptions without profiling and measuring. Even in those rare cases when the cost is significant, you can weigh it against the increased correctness, easier maintainability, and other advantages that are provided by a well-designed exception policy. ## Exceptions versus assertions -Exceptions and asserts are two distinct mechanisms for detecting run-time errors in a program. Use `assert` statements to test for conditions during development that should never be true if all your code is correct. There's no point in handling such an error by using an exception, because the error indicates that something in the code has to be fixed. It doesn't represent a condition that the program has to recover from at run time. An `assert` stops execution at the statement so that you can inspect the program state in the debugger. An exception continues execution from the first appropriate catch handler. Use exceptions to check error conditions that might occur at run time even if your code is correct, for example, "file not found" or "out of memory." Exceptions can handle these conditions, even if the recovery just outputs a message to a log and ends the program. Always check arguments to public functions by using exceptions. Even if your function is error-free, you might not have complete control over arguments that a user might pass to it. +Exceptions and asserts are two distinct mechanisms for detecting run-time errors in a program. Use `assert` statements to test for conditions during development that should always be true or always be false if all your code is correct. There's no point in handling such an error by using an exception, because the error indicates that something in the code has to be fixed. It doesn't represent a condition that the program has to recover from at run time. An `assert` stops execution at the statement so that you can inspect the program state in the debugger. An exception continues execution from the first appropriate catch handler. Use exceptions to check error conditions that might occur at run time even if your code is correct, for example, "file not found" or "out of memory." Exceptions can handle these conditions, even if the recovery just outputs a message to a log and ends the program. Always check arguments to public functions by using exceptions. Even if your function is error-free, you might not have complete control over arguments that a user might pass to it. ## C++ exceptions versus Windows SEH exceptions @@ -96,6 +92,6 @@ Exception specifications were introduced in C++ as a way to specify the exceptio ## See also -[How to: Interface between exceptional and non-exceptional code](../cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md)
-[C++ language reference](../cpp/cpp-language-reference.md)
+[How to: Interface between exceptional and non-exceptional code](../cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md)\ +[C++ language reference](../cpp/cpp-language-reference.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/cpp/examples-of-lambda-expressions.md b/docs/cpp/examples-of-lambda-expressions.md index 7cb154f621a..b61948f50cd 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 d63159cfaf9..268e410d73d 100644 --- a/docs/cpp/exception-specifications-throw-cpp.md +++ b/docs/cpp/exception-specifications-throw-cpp.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Exception specifications (throw, noexcept) (C++)" title: "Exception specifications (throw, noexcept) (C++)" +description: "Learn more about: Exception specifications (throw, noexcept) (C++)" ms.date: "01/18/2018" helpviewer_keywords: ["exceptions [C++], exception specifications", "throwing exceptions [C++], throw keyword", "C++ exception handling [C++], throwing exceptions", "throw keyword [C++]", "noexcept keyword [C++]"] -ms.assetid: 4d3276df-6f31-4c7f-8cab-b9d2d003a629 --- # Exception specifications (throw, noexcept) (C++) @@ -25,7 +24,7 @@ The following table summarizes the Microsoft C++ implementation of exception spe |Exception specification|Meaning| |-----------------------------|-------------| -|**`noexcept`**
`noexcept(true)`
`throw()`|The function does not throw an exception. In **`/std:c++14`** mode (which is the default), **`noexcept`** and `noexcept(true)` are equivalent. When an exception is thrown from a function that is declared **`noexcept`** or `noexcept(true)`, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked. When an exception is thrown from a function declared as `throw()` in **`/std:c++14`** mode, the result is undefined behavior. No specific function is invoked. This is a divergence from the C++14 standard, which required the compiler to invoke [`std::unexpected`](../standard-library/exception-functions.md#unexpected).
**Visual Studio 2017 version 15.5 and later**: In **`/std:c++17`** mode , **`noexcept`**, `noexcept(true)`, and `throw()` are all equivalent. In **`/std:c++17`** mode, `throw()` is an alias for `noexcept(true)`. In **`/std:c++17`** mode and later, when an exception is thrown from a function declared with any of these specifications, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked as required by the C++17 standard.| +|**`noexcept`**
`noexcept(true)`
`throw()`|The function does not throw an exception. In **`/std:c++14`** mode (which is the default), **`noexcept`** and `noexcept(true)` are equivalent. When an exception is thrown from a function that is declared **`noexcept`** or `noexcept(true)`, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked. When an exception is thrown from a function declared as `throw()` in **`/std:c++14`** mode, the result is undefined behavior. No specific function is invoked. This is a divergence from the C++14 standard, which required the compiler to invoke [`std::unexpected`](../standard-library/exception-functions.md#unexpected).
**Visual Studio 2017 version 15.5 and later**: In **`/std:c++17`** mode, **`noexcept`**, `noexcept(true)`, and `throw()` are all equivalent. In **`/std:c++17`** mode, `throw()` is an alias for `noexcept(true)`. In **`/std:c++17`** mode and later, when an exception is thrown from a function declared with any of these specifications, [`std::terminate`](../standard-library/exception-functions.md#terminate) is invoked as required by the C++17 standard.| |`noexcept(false)`
`throw(...)`
No specification|The function can throw an exception of any type.| |`throw(type)`| (**C++14 and earlier**) The function can throw an exception of type `type`. The compiler accepts the syntax, but interprets it as `noexcept(false)`. In **`/std:c++17`** mode and later, the compiler issues warning C5040.| diff --git a/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md b/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md index 3cb9e891b98..3219d0d5d80 100644 --- a/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md +++ b/docs/cpp/exceptions-and-stack-unwinding-in-cpp.md @@ -20,7 +20,7 @@ In the C++ exception mechanism, control moves from the throw statement to the fi ## Stack unwinding example -The following example demonstrates how the stack is unwound when an exception is thrown. Execution on the thread jumps from the throw statement in `C` to the catch statement in `main`, and unwinds each function along the way. Notice the order in which the `Dummy` objects are created and then destroyed as they go out of scope. Also notice that no function completes except `main`, which contains the catch statement. Function `A` never returns from its call to `B()`, and `B` never returns from its call to `C()`. If you uncomment the definition of the `Dummy` pointer and the corresponding delete statement, and then run the program, notice that the pointer is never deleted. This shows what can happen when functions do not provide an exception guarantee. For more information, see How to: Design for Exceptions. If you comment out the catch statement, you can observe what happens when a program terminates because of an unhandled exception. +The following example demonstrates how the stack is unwound when an exception is thrown. Execution on the thread jumps from the throw statement in `C` to the catch statement in `main`, and unwinds each function along the way. Notice the order in which the `Dummy` objects are created and then destroyed as they go out of scope. Also notice that no function completes except `main`, which contains the catch statement. Function `A` never returns from its call to `B()`, and `B` never returns from its call to `C()`. If you uncomment the definition of the `Dummy` pointer and the corresponding delete statement, and then run the program, notice that the pointer is never deleted. This shows what can happen when functions do not provide an exception guarantee. For more information, see [How to: Design for Exceptions](how-to-design-for-exception-safety.md). If you comment out the catch statement, you can observe what happens when a program terminates because of an unhandled exception. ```cpp #include diff --git a/docs/cpp/explicit-instantiation.md b/docs/cpp/explicit-instantiation.md index 578575d787b..02a1e53d688 100644 --- a/docs/cpp/explicit-instantiation.md +++ b/docs/cpp/explicit-instantiation.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: Explicit Instantiation" -title: "Explicit Instantiation" -ms.date: "11/04/2016" +description: "Learn more about: Explicit instantiation" +title: "Explicit instantiation" +ms.date: 09/27/2022 helpviewer_keywords: ["templates, instantiation", "explicit instantiation", "instantiation, explicit"] ms.assetid: 8b0d4e32-45a6-49d5-8041-1ebdd674410e --- -# Explicit Instantiation +# Explicit instantiation -You can use explicit instantiation to create an instantiation of a templated class or function without actually using it in your code. Because this is useful when you are creating library (.lib) files that use templates for distribution, uninstantiated template definitions are not put into object (.obj) files. +You can use explicit instantiation to create an instantiation of a templated class or function without actually using it in your code. Because it's useful when you're creating library (*`.lib`*) files that use templates for distribution, uninstantiated template definitions aren't put into object (*`.obj`*) files. + +## Examples This code explicitly instantiates `MyStack` for **`int`** variables and six items: @@ -23,7 +25,7 @@ The next line explicitly instantiates only the constructor member function: template MyStack::MyStack( void ); ``` -You can explicitly instantiate function templates by using a specific type argument to re-declare them, as shown in the example in [Function Template Instantiation](../cpp/function-template-instantiation.md). +You can explicitly instantiate function templates by using a specific type argument to redeclare them, as shown in the example in [Function template instantiation](../cpp/function-template-instantiation.md). You can use the **`extern`** keyword to prevent the automatic instantiation of members. For example: @@ -37,11 +39,11 @@ Similarly, you can mark specific members as being external and not instantiated: extern template MyStack::MyStack( void ); ``` -You can use the **`extern`** keyword to keep the compiler from generating the same instantiation code in more than one object module. You must instantiate the template function by using the specified explicit template parameters in at least one linked module if the function is called, or you will get a linker error when the program is built. +You can use the **`extern`** keyword to keep the compiler from generating the same instantiation code in more than one object module. You must instantiate the function template by using the specified explicit template parameters in at least one linked module if the function is called. Otherwise, you'll get a linker error when the program is built. > [!NOTE] > The **`extern`** keyword in the specialization only applies to member functions defined outside of the body of the class. Functions defined inside the class declaration are considered inline functions and are always instantiated. ## See also -[Function Templates](../cpp/function-templates.md) +[Function templates](../cpp/function-templates.md) diff --git a/docs/cpp/explicit-specialization-of-function-templates.md b/docs/cpp/explicit-specialization-of-function-templates.md index 5842f4e767d..769315f1496 100644 --- a/docs/cpp/explicit-specialization-of-function-templates.md +++ b/docs/cpp/explicit-specialization-of-function-templates.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Explicit Specialization of Function Templates" title: "Explicit Specialization of Function Templates" -ms.date: "11/04/2016" +description: "Learn more about: Explicit Specialization of Function Templates" +ms.date: 11/04/2016 helpviewer_keywords: ["overriding, functions", "function templates, specialization", "explicit specialization of function templates", "declaring functions [C++], specialization of function template", "specialization of function templates"] -ms.assetid: eb0fcb73-eaed-42a1-9b83-14b055a34bf8 --- # Explicit Specialization of Function Templates @@ -21,7 +20,7 @@ This declaration enables you to define a different function for **`double`** var // explicit_specialization.cpp template void f(T t) { -}; +} // Explicit specialization of f with 'char' with the // template argument explicitly specified: diff --git a/docs/cpp/explicit-type-conversion-operator-parens.md b/docs/cpp/explicit-type-conversion-operator-parens.md index 184ba177cca..e0a684cebb8 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 25f53cb673f..78904c4e76c 100644 --- a/docs/cpp/explicitly-defaulted-and-deleted-functions.md +++ b/docs/cpp/explicitly-defaulted-and-deleted-functions.md @@ -1,16 +1,15 @@ --- -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 +description: "Learn more about: Explicitly Defaulted and Deleted Functions" +ms.date: 11/04/2016 --- # 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,16 +35,16 @@ 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 { - noncopyable() {}; + noncopyable() {} private: noncopyable(const 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/extension-restrict.md b/docs/cpp/extension-restrict.md index ce69c439af6..16c3231d0a3 100644 --- a/docs/cpp/extension-restrict.md +++ b/docs/cpp/extension-restrict.md @@ -1,7 +1,7 @@ --- title: "`__restrict`" -description: "Describes the Microsoft Visual C++ `__restrict` keyword." -ms.date: "11/6/2020" +description: "Describes the Microsoft Visual C++ `__restrict` keyword." +ms.date: 11/6/2020 f1_keywords: ["__restrict_cpp", "__restrict", "_restrict"] helpviewer_keywords: ["__restrict keyword [C++]"] --- diff --git a/docs/cpp/fastcall.md b/docs/cpp/fastcall.md index bae76403dbc..772adbead20 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/floating-limits.md b/docs/cpp/floating-limits.md index 475ad5b18ba..60762ecfb15 100644 --- a/docs/cpp/floating-limits.md +++ b/docs/cpp/floating-limits.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Floating Limits" title: "Floating Limits" -ms.date: "08/03/2018" +description: "Learn more about: Floating Limits" +ms.date: 08/03/2018 helpviewer_keywords: ["ranges, floating-point constants", "floating-point constants, limits", "float.h header file", "limits, floating-point constants", "floating-point numbers [C++]", "floating limits"] -ms.assetid: fc718652-1f4c-4ed8-af60-0e769637459c --- # Floating Limits @@ -15,7 +14,7 @@ The following table lists the limits on the values of floating-point constants. |Constant|Meaning|Value| |--------------|-------------|-----------| -|`FLT_DIG`
`DBL_DIG`
`LDBL_DIG`|Number of digits, q, such that a floating-point number with q decimal digits can be rounded into a floating-point representation and back without loss of precision.|6
15
15| +|`FLT_DIG`
`DBL_DIG`
`LDBL_DIG`|Number of digits, q, such that a floating-point number with q decimal digits can be rounded into a floating-point representation and back without loss of precision.|6
15
15| |`FLT_EPSILON`
`DBL_EPSILON`
`LDBL_EPSILON`|Smallest positive number x, such that x + 1.0 is not equal to 1.0.|1.192092896e-07F
2.2204460492503131e-016
2.2204460492503131e-016| |`FLT_GUARD`||0| |`FLT_MANT_DIG`
`DBL_MANT_DIG`
`LDBL_MANT_DIG`|Number of digits in the radix specified by `FLT_RADIX` in the floating-point significand. The radix is 2; hence these values specify bits.|24
53
53| diff --git a/docs/cpp/friend-cpp.md b/docs/cpp/friend-cpp.md index a2364c59d33..4e4aa5f1d02 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 b065fdd6b08..3766abb0f4b 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 2d13256630c..8f8c24a61a9 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 a1b57135b7b..58670206a16 100644 --- a/docs/cpp/functions-cpp.md +++ b/docs/cpp/functions-cpp.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Functions (C++)" title: "Functions (C++)" -ms.date: "11/19/2018" +description: "Learn more about: Functions (C++)" +ms.date: 11/19/2018 helpviewer_keywords: ["defaults, arguments", "function definitions", "function definitions, about function definitions", "default arguments", "declarators, functions"] -ms.assetid: 33ba01d5-75b5-48d2-8eab-5483ac7d2274 --- # Functions (C++) @@ -27,15 +26,15 @@ int main() } ``` -There is no practical limit to function length, but good design aims for functions that perform a single well-defined task. Complex algorithms should be broken up into easy-to-understand simpler functions whenever possible. +There's no practical limit to function length, but good design aims for functions that perform a single well-defined task. Complex algorithms should be broken up into easy-to-understand simpler functions whenever possible. -Functions that are defined at class scope are called member functions. In C++, unlike other languages, a function can also be defined at namespace scope (including the implicit global namespace). Such functions are called *free functions* or *non-member functions*; they are used extensively in the Standard Library. +Functions that are defined at class scope are called member functions. In C++, unlike other languages, a function can also be defined at namespace scope (including the implicit global namespace). Such functions are called *free functions* or *non-member functions*; they're used extensively in the Standard Library. Functions may be *overloaded*, which means different versions of a function may share the same name if they differ by the number and/or type of formal parameters. For more information, see [Function Overloading](../cpp/function-overloading.md). ## Parts of a function declaration -A minimal function *declaration* consists of the return type, function name, and parameter list (which may be empty), along with optional keywords that provide additional instructions to the compiler. The following example is a function declaration: +A minimal function *declaration* consists of the return type, function name, and parameter list (which may be empty), along with optional keywords that provide more instructions to the compiler. The following example is a function declaration: ```cpp int sum(int a, int b); @@ -56,7 +55,7 @@ The required parts of a function declaration are: 1. The return type, which specifies the type of the value that the function returns, or **`void`** if no value is returned. In C++11, **`auto`** is a valid return type that instructs the compiler to infer the type from the return statement. In C++14, `decltype(auto)` is also allowed. For more information, see Type Deduction in Return Types below. -1. The function name, which must begin with a letter or underscore and cannot contain spaces. In general, leading underscores in the Standard Library function names indicate private member functions, or non-member functions that are not intended for use by your code. +1. The function name, which must begin with a letter or underscore and can't contain spaces. In general, leading underscores in the Standard Library function names indicate private member functions, or non-member functions that aren't intended for use by your code. 1. The parameter list, a brace delimited, comma-separated set of zero or more parameters that specify the type and optionally a local name by which the values may be accessed inside the function body. @@ -78,7 +77,6 @@ Optional parts of a function declaration are: ```cpp //Declare printf with C linkage. extern "C" int printf( const char *fmt, ... ); - ``` For more information, see [Translation units and linkage](../cpp/program-and-linkage-cpp.md). @@ -94,7 +92,7 @@ Optional parts of a function declaration are: For more information, see [Inline Functions](../cpp/inline-functions-cpp.md). -1. A **`noexcept`** expression, which specifies whether or not the function can throw an exception. In the following example, the function does not throw an exception if the `is_pod` expression evaluates to **`true`**. +1. A **`noexcept`** expression, which specifies whether or not the function can throw an exception. In the following example, the function doesn't throw an exception if the `is_pod` expression evaluates to **`true`**. ```cpp #include @@ -107,17 +105,12 @@ Optional parts of a function declaration are: 1. (Member functions only) The cv-qualifiers, which specify whether the function is **`const`** or **`volatile`**. -1. (Member functions only) **`virtual`**, **`override`**, or **`final`**. **`virtual`** specifies that a function can be overridden in a derived class. **`override`** means that a function in a derived class is overriding a virtual function. **`final`** means a function cannot be overridden in any further derived class. For more information, see [Virtual Functions](../cpp/virtual-functions.md). +1. (Member functions only) **`virtual`**, **`override`**, or **`final`**. **`virtual`** specifies that a function can be overridden in a derived class. **`override`** means that a function in a derived class is overriding a virtual function. **`final`** means a function can't be overridden in any further derived class. For more information, see [Virtual Functions](../cpp/virtual-functions.md). -1. (member functions only) **`static`** applied to a member function means that the function is not associated with any object instances of the class. +1. (member functions only) **`static`** applied to a member function means that the function isn't associated with any object instances of the class. 1. (Non-static member functions only) The ref-qualifier, which specifies to the compiler which overload of a function to choose when the implicit object parameter (`*this`) is an rvalue reference vs. an lvalue reference. For more information, see [Function Overloading](function-overloading.md#ref-qualifiers). -The following figure shows the parts of a function definition. The shaded area is the function body. - -![Diagram of the parts of a function definition.](../cpp/media/vc38ru1.gif "Parts of a function definition")
-Parts of a function definition - ## Function definitions A *function definition* consists of the declaration and the function body, enclosed in curly braces, which contains variable declarations, statements and expressions. The following example shows a complete function definition: @@ -149,7 +142,7 @@ Variables declared inside the body are called local variables or locals. They go ## const and constexpr functions -You can declare a member function as **`const`** to specify that the function is not allowed to change the values of any data members in the class. By declaring a member function as **`const`**, you help the compiler to enforce *const-correctness*. If someone mistakenly tries to modify the object by using a function declared as **`const`**, a compiler error is raised. For more information, see [const](const-cpp.md). +You can declare a member function as **`const`** to specify that the function isn't allowed to change the values of any data members in the class. By declaring a member function as **`const`**, you help the compiler to enforce *const-correctness*. If someone mistakenly tries to modify the object by using a function declared as **`const`**, a compiler error is raised. For more information, see [const](const-cpp.md). Declare a function as **`constexpr`** when the value it produces can possibly be determined at compile time. A constexpr function generally executes faster than a regular function. For more information, see [`constexpr`](constexpr-cpp.md). @@ -172,9 +165,9 @@ For more information, see [Function Templates](../cpp/function-templates.md) ## Function parameters and arguments -A function has a comma-separated parameter list of zero or more types, each of which has a name by which it can be accessed inside the function body. A function template may specify additional type or value parameters. The caller passes arguments, which are concrete values whose types are compatible with the parameter list. +A function has a comma-separated parameter list of zero or more types, each of which has a name by which it can be accessed inside the function body. A function template may specify more type or value parameters. The caller passes arguments, which are concrete values whose types are compatible with the parameter list. -By default, arguments are passed to the function by value, which means the function receives a copy of the object being passed. For large objects, making a copy can be expensive and is not always necessary. To cause arguments to be passed by reference (specifically lvalue reference), add a reference quantifier to the parameter: +By default, arguments are passed to the function by value, which means the function receives a copy of the object being passed. For large objects, making a copy can be expensive and isn't always necessary. To cause arguments to be passed by reference (specifically lvalue reference), add a reference quantifier to the parameter: ```cpp void DoSomething(std::string& input){...} @@ -186,7 +179,7 @@ When a function modifies an argument that is passed by reference, it modifies th void DoSomething(const std::string& input){...} ``` -**C++ 11:** To explicitly handle arguments that are passed by rvalue-reference or lvalue-reference, use a double-ampersand on the parameter to indicate a universal reference: +**C++11:** To explicitly handle arguments that are passed by rvalue-reference or lvalue-reference, use a double-ampersand on the parameter to indicate a universal reference: ```cpp void DoSomething(const std::string&& input){...} @@ -195,12 +188,11 @@ void DoSomething(const std::string&& input){...} A function declared with the single keyword **`void`** in the parameter declaration list takes no arguments, as long as the keyword **`void`** is the first and only member of the argument declaration list. Arguments of type **`void`** elsewhere in the list produce errors. For example: ```cpp - // OK same as GetTickCount() long GetTickCount( void ); ``` -Note that, while it is illegal to specify a **`void`** argument except as outlined here, types derived from type **`void`** (such as pointers to **`void`** and arrays of **`void`**) can appear anywhere the argument declaration list. +While it's illegal to specify a **`void`** argument except as outlined here, types derived from type **`void`** (such as pointers to **`void`** and arrays of **`void`**) can appear anywhere the argument declaration list. ### Default Arguments @@ -233,7 +225,7 @@ A function may not return another function, or a built-in array; however it can ### Trailing return types -An "ordinary" return type is located on the left side of the function signature. A *trailing return type* is located on the right most side of the signature and is preceded by the **`->`** operator. Trailing return types are especially useful in function templates when the type of the return value depends on template parameters. +An "ordinary" return type is located on the left side of the function signature. A *trailing return type* is located on the rightmost side of the signature and is preceded by the **`->`** operator. Trailing return types are especially useful in function templates when the type of the return value depends on template parameters. ```cpp template @@ -243,13 +235,13 @@ auto Add(const Lhs& lhs, const Rhs& rhs) -> decltype(lhs + rhs) } ``` -When **`auto`** is used in conjunction with a trailing return type, it just serves as a placeholder for whatever the decltype expression produces, and does not itself perform type deduction. +When **`auto`** is used in conjunction with a trailing return type, it just serves as a placeholder for whatever the decltype expression produces, and doesn't itself perform type deduction. ## Function local variables -A variable that is declared inside a function body is called a *local variable* or simply a *local*. Non-static locals are only visible inside the function body and, if they are declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the *named return value optimization* to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed. +A variable that is declared inside a function body is called a *local variable* or simply a *local*. Non-static locals are only visible inside the function body and, if they're declared on the stack go out of scope when the function exits. When you construct a local variable and return it by value, the compiler can usually perform the *named return value optimization* to avoid unnecessary copy operations. If you return a local variable by reference, the compiler will issue a warning because any attempt by the caller to use that reference will occur after the local has been destroyed. -In C++ a local variable may be declared as static. The variable is only visible inside the function body, but a single copy of the variable exists for all instances of the function. Local static objects are destroyed during termination specified by `atexit`. If a static object was not constructed because the program's flow of control bypassed its declaration, no attempt is made to destroy that object. +In C++ a local variable may be declared as static. The variable is only visible inside the function body, but a single copy of the variable exists for all instances of the function. Local static objects are destroyed during termination specified by `atexit`. If a static object wasn't constructed because the program's flow of control bypassed its declaration, no attempt is made to destroy that object. ## Type deduction in return types (C++14) @@ -265,7 +257,7 @@ auto Add2(const Lhs& lhs, const Rhs& rhs) } ``` -Note that **`auto`** does not preserve the const-ness of the type it deduces. For forwarding functions whose return value needs to preserve the const-ness or ref-ness of its arguments, you can use the **`decltype(auto)`** keyword, which uses the **`decltype`** type inference rules and preserves all the type information. **`decltype(auto)`** may be used as an ordinary return value on the left side, or as a trailing return value. +Note that **`auto`** doesn't preserve the const-ness of the type it deduces. For forwarding functions whose return value needs to preserve the const-ness or ref-ness of its arguments, you can use the **`decltype(auto)`** keyword, which uses the **`decltype`** type inference rules and preserves all the type information. **`decltype(auto)`** may be used as an ordinary return value on the left side, or as a trailing return value. The following example (based on code from [N3493](https://wg21.link/n3493)), shows **`decltype(auto)`** being used to enable perfect forwarding of function arguments in a return type that isn't known until the template is instantiated. @@ -352,7 +344,7 @@ There are various ways to return more than one value from a function: } ``` -1. **Visual Studio 2017 version 15.3 and later** (available in [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode and later): Use structured bindings. The advantage of structured bindings is that the variables that store the return values are initialized at the same time they are declared, which in some cases can be significantly more efficient. In the statement `auto[x, y, z] = f();` the brackets introduce and initialize names that are in scope for the entire function block. +1. **Visual Studio 2017 version 15.3 and later** (available in [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) mode and later): Use structured bindings. The advantage of structured bindings is that the variables that store the return values are initialized at the same time they're declared, which in some cases can be significantly more efficient. In the statement `auto[x, y, z] = f();` the brackets introduce and initialize names that are in scope for the entire function block. ```cpp #include @@ -398,26 +390,26 @@ There are various ways to return more than one value from a function: C++ supports function pointers in the same manner as the C language. However a more type-safe alternative is usually to use a function object. -It is recommended that **`typedef`** be used to declare an alias for the function pointer type if declaring a function that returns a function pointer type. For example +It's recommended that you use **`typedef`** to declare an alias for the function pointer type if declaring a function that returns a function pointer type. For example ```cpp typedef int (*fp)(int); fp myFunction(char* s); // function returning function pointer ``` -If this is not done, the proper syntax for the function declaration may be deduced from the declarator syntax for the function pointer by replacing the identifier (`fp` in the above example) with the functions name and argument list, as follows: +If this isn't done, the proper syntax for the function declaration may be deduced from the declarator syntax for the function pointer by replacing the identifier (`fp` in the above example) with the functions name and argument list, as follows: ```cpp int (*myFunction(char* s))(int); ``` -The preceding declaration is equivalent to the declaration using **`typedef`** above. +The preceding declaration is equivalent to the declaration using **`typedef`** earlier. ## See also -[Function Overloading](../cpp/function-overloading.md)
-[Functions with Variable Argument Lists](../cpp/functions-with-variable-argument-lists-cpp.md)
-[Explicitly Defaulted and Deleted Functions](../cpp/explicitly-defaulted-and-deleted-functions.md)
-[Argument-Dependent Name (Koenig) Lookup on Functions](../cpp/argument-dependent-name-koenig-lookup-on-functions.md)
-[Default Arguments](../cpp/default-arguments.md)
+[Function Overloading](../cpp/function-overloading.md)\ +[Functions with Variable Argument Lists](../cpp/functions-with-variable-argument-lists-cpp.md)\ +[Explicitly Defaulted and Deleted Functions](../cpp/explicitly-defaulted-and-deleted-functions.md)\ +[Argument-Dependent Name (Koenig) Lookup on Functions](../cpp/argument-dependent-name-koenig-lookup-on-functions.md)\ +[Default Arguments](../cpp/default-arguments.md)\ [Inline Functions](../cpp/inline-functions-cpp.md) diff --git a/docs/cpp/functions-with-variable-argument-lists-cpp.md b/docs/cpp/functions-with-variable-argument-lists-cpp.md index 1fb884942d9..59316d69931 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" +title: "Functions with Variable Argument Lists (C++)" +description: "Learn more about: Functions with Variable Argument Lists (C++)" +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++) +# 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/fundamental-types-cpp.md b/docs/cpp/fundamental-types-cpp.md index 457e01bac46..69c1c4ca01d 100644 --- a/docs/cpp/fundamental-types-cpp.md +++ b/docs/cpp/fundamental-types-cpp.md @@ -1,10 +1,9 @@ --- +title: "Built-in types (C++)" description: "Learn more about: Built-in types (C++)" -title: "Built-in types (C++)" ms.date: 07/22/2020 f1_keywords: ["__int128_cpp", "__wchar_t_cpp", "char_cpp", "char8_t_cpp", "char16_t_cpp", "char32_t_cpp", "double_cpp", "float_cpp", "int_cpp", "long_cpp", "long_double_cpp", "short_cpp", "signed_cpp", "unsigned_cpp", "unsigned_int_cpp", "wchar_t_cpp"] helpviewer_keywords: ["specifiers [C++], type", "float keyword [C++]", "char keyword [C++]", "__wchar_t keyword [C++]", "signed types [C++], summary of data types", "Integer data type [C++], C++ data types", "arithmetic operations [C++], types", "int data type", "unsigned types [C++], summary of data types", "short data type [C++]", "double data type [C++], summary of types", "long long keyword [C++]", "long double keyword [C++]", "unsigned types [C++]", "signed types [C++]", "void keyword [C++]", "storage [C++], basic type", "integral types, C++", "wchar_t keyword [C++]", "floating-point numbers [C++], C++ data types", "long keyword [C++]", "type specifiers [C++]", "integral types", "long keyword [C++]", "storing types [C++]", "data types [C++], void"] -ms.assetid: 58b0106a-0406-4b74-a430-7cbd315c0f89 --- # Built-in types (C++) @@ -14,11 +13,11 @@ Built-in types (also called *fundamental types*) are specified by the C++ langua The [`void`](void-cpp.md) type describes an empty set of values. No variable of type **`void`** can be specified. The **`void`** type is used primarily to declare functions that return no values or to declare generic pointers to untyped or arbitrarily typed data. Any expression can be explicitly converted or cast to type **`void`**. However, such expressions are restricted to the following uses: -- An expression statement. (For more information, see [Expressions](expressions-cpp.md).) +- An expression statement. For more information, see [Expressions](expressions-cpp.md). -- The left operand of the comma operator. (For more information, see [Comma Operator](comma-operator.md).) +- The left operand of the comma operator. For more information, see [Comma Operator](comma-operator.md). -- The second or third operand of the conditional operator (`? :`). (For more information, see [Expressions with the Conditional Operator](conditional-operator-q.md).) +- The second or third operand of the conditional operator (`? :`). For more information, see [Expressions with the Conditional Operator](conditional-operator-q.md). ## std::nullptr_t diff --git a/docs/cpp/how-to-create-and-use-ccomptr-and-ccomqiptr-instances.md b/docs/cpp/how-to-create-and-use-ccomptr-and-ccomqiptr-instances.md index c25e220009e..a780106d816 100644 --- a/docs/cpp/how-to-create-and-use-ccomptr-and-ccomqiptr-instances.md +++ b/docs/cpp/how-to-create-and-use-ccomptr-and-ccomqiptr-instances.md @@ -3,8 +3,6 @@ description: "Learn more about: How to: Create and use CComPtr and CComQIPtr ins title: "How to: Create and use CComPtr and CComQIPtr instances" ms.custom: "how-to" ms.date: "11/19/2019" -ms.topic: "conceptual" -ms.assetid: b0356cfb-12cc-4ee8-b988-8311ed1ab5e0 --- # How to: Create and use CComPtr and CComQIPtr instances @@ -20,7 +18,7 @@ The following example shows how to use `CComPtr` to instantiate a COM object and `CComPtr` and its relatives are part of the ATL and are defined in \. `_com_ptr_t` is declared in \. The compiler creates specializations of `_com_ptr_t` when it generates wrapper classes for type libraries. -## Example: CComQIPt +## Example: CComQIPtr ATL also provides `CComQIPtr`, which has a simpler syntax for querying a COM object to retrieve an additional interface. However, we recommend `CComPtr` because it does everything that `CComQIPtr` can do and is semantically more consistent with raw COM interface pointers. If you use a `CComPtr` to query for an interface, the new interface pointer is placed in an out parameter. If the call fails, an HRESULT is returned, which is the typical COM pattern. With `CComQIPtr`, the return value is the pointer itself, and if the call fails, the internal HRESULT return value cannot be accessed. The following two lines show how the error handling mechanisms in `CComPtr` and `CComQIPtr` differ. 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 dd384467400..cc993258bd9 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,17 @@ 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.topic: "conceptual" -ms.assetid: 7d6ebb73-fa0d-4b0b-a528-bf05de96518e +ms.date: "12/4/2024" --- # 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 +67,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 +81,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 +97,21 @@ You can pass a `shared_ptr` to another function in the following ways: - Pass the `shared_ptr` by reference or const reference. In this case, the reference count isn't incremented, and the callee can access the pointer as long as the caller doesn't go out of scope. Or, the callee can decide to create a `shared_ptr` based on the reference, and become a shared owner. Use this option when the caller has no knowledge of the callee, or when you must pass a `shared_ptr` and want to avoid the copy operation for performance reasons. -- Pass the underlying pointer or a reference to the underlying object. This enables the callee to use the object, but doesn't enable it to share ownership or extend the lifetime. If the callee creates a `shared_ptr` from the raw pointer, the new `shared_ptr` is independent from the original, and doesn't control the underlying resource. Use this option when the contract between the caller and callee clearly specifies that the caller retains ownership of the `shared_ptr` lifetime. +- Pass the underlying pointer or a reference to the underlying object. This enables the callee to use the object, but it doesn't share ownership of the object with the caller's `shared_ptr`. Beware the case of the callee creating a `shared_ptr` from the passed raw pointer because the callee's `shared_ptr` has an independent reference count from the caller's `shared_ptr`. When the `shared_ptr` in the callee goes out of scope, it will delete the object, leaving the pointer in the caller's 'shared_ptr' pointing at released memory. When the caller's `shared_ptr` then goes out of scope, a double-free results. Only use this option when the contract between the caller and callee clearly specifies that the caller retains ownership of the `shared_ptr` lifetime. - When you're deciding how to pass a `shared_ptr`, determine whether the callee has to share ownership of the underlying resource. An "owner" is an object or function that can keep the underlying resource alive for as long as it needs it. If the caller has to guarantee that the callee can extend the life of the pointer beyond its (the function's) lifetime, use the first option. If you don't care whether the callee extends the lifetime, then pass by reference and let the callee copy it or not. -- If you have to give a helper function access to the underlying pointer, and you know that the helper function will just use the pointer and return before the calling function returns, then that function doesn't have to share ownership of the underlying pointer. It just has to access the pointer within the lifetime of the caller's `shared_ptr`. In this case, it's safe to pass the `shared_ptr` by reference, or pass the raw pointer or a reference to the underlying object. Passing this way provides a small performance benefit, and may also help you express your programming intent. +- If you have to give a helper function access to the underlying pointer, and you know that the helper function uses the pointer and return before the calling function returns, then that function doesn't have to share ownership of the underlying pointer. It just has to access the pointer within the lifetime of the caller's `shared_ptr`. In this case, it's safe to pass the `shared_ptr` by reference, or pass the raw pointer or a reference to the underlying object. Passing this way provides a small performance benefit, and may also help you express your programming intent. - Sometimes, for example in a `std::vector>`, you may have to pass each `shared_ptr` to a lambda expression body or named function object. If the lambda or function doesn't store the pointer, then pass the `shared_ptr` by reference to avoid invoking the copy constructor for each element. +[!code-cpp[stl_smart_pointers#5](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_5.cpp)] + ## Example 6 The following example shows how `shared_ptr` overloads various comparison operators to enable pointer comparisons on the memory that is owned by the `shared_ptr` instances. -[!code-cpp[stl_smart_pointers#3](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp)] +[!code-cpp[stl_smart_pointers#6](codesnippet/CPP/how-to-create-and-use-shared-ptr-instances_6.cpp)] ## See also diff --git a/docs/cpp/how-to-create-and-use-unique-ptr-instances.md b/docs/cpp/how-to-create-and-use-unique-ptr-instances.md index 4621600bd18..f0c566944c2 100644 --- a/docs/cpp/how-to-create-and-use-unique-ptr-instances.md +++ b/docs/cpp/how-to-create-and-use-unique-ptr-instances.md @@ -2,26 +2,39 @@ description: "Learn more about: How to: Create and use unique_ptr instances" title: "How to: Create and use unique_ptr instances" ms.custom: "how-to" -ms.date: "11/19/2018" -ms.topic: "conceptual" -ms.assetid: 9a373030-e587-452f-b9a5-c5f9d58b7673 +ms.date: 04/10/2026 +ai-usage: ai-assisted --- # How to: Create and use unique_ptr instances -A [unique_ptr](../standard-library/unique-ptr-class.md) does not share its pointer. It cannot be copied to another `unique_ptr`, passed by value to a function, or used in any C++ Standard Library algorithm that requires copies to be made. A `unique_ptr` can only be moved. This means that the ownership of the memory resource is transferred to another `unique_ptr` and the original `unique_ptr` no longer owns it. We recommend that you restrict an object to one owner, because multiple ownership adds complexity to the program logic. Therefore, when you need a smart pointer for a plain C++ object, use `unique_ptr`, and when you construct a `unique_ptr`, use the [make_unique](../standard-library/memory-functions.md#make_unique) helper function. +A [unique_ptr](../standard-library/unique-ptr-class.md) doesn't share its pointer. It can't be copied to another `unique_ptr`, passed by value to a function, or used in any C++ Standard Library algorithm that requires copies to be made. A `unique_ptr` can only be moved. This means that the ownership of the memory resource is transferred to another `unique_ptr` and the original `unique_ptr` no longer owns it. We recommend that you restrict an object to one owner, because multiple ownership adds complexity. When you need a smart pointer for a plain C++ object, use `unique_ptr`, and when you construct a `unique_ptr`, use the [`make_unique`](../standard-library/memory-functions.md#make_unique) helper function. The following diagram illustrates the transfer of ownership between two `unique_ptr` instances. ![Diagram that shows moving the ownership of a unique pointer.](media/unique_ptr.png) -`unique_ptr` is defined in the `` header in the C++ Standard Library. It is exactly as efficient as a raw pointer and can be used in C++ Standard Library containers. The addition of `unique_ptr` instances to C++ Standard Library containers is efficient because the move constructor of the `unique_ptr` eliminates the need for a copy operation. +`unique_ptr` is defined in the `` header in the C++ Standard Library. It's exactly as efficient as a raw pointer and can be used in C++ Standard Library containers. The addition of `unique_ptr` instances to C++ Standard Library containers is efficient because the move constructor of the `unique_ptr` eliminates the need for a copy operation. + +To use `unique_ptr` and `make_unique`, include the `` header. The following examples each compile and run as standalone programs. ## Example 1 -The following example shows how to create `unique_ptr` instances and pass them between functions. +The following example shows how to create `unique_ptr` instances and pass them between functions. Returning a `unique_ptr` by value transfers ownership to the caller. Passing a `unique_ptr` by value to a function transfers ownership to the callee. [!code-cpp[stl_smart_pointers#210](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_1.cpp)] +```output +Created: Namonaki Uta +song points to: Namonaki Uta +After move, song is null +song2 points to: Namonaki Uta +Created: Beat It +Singing: Beat It by Michael Jackson +Destroyed: Beat It +After SingSong, song3 is null +Destroyed: Namonaki Uta +``` + These examples demonstrate this basic characteristic of `unique_ptr`: it can be moved, but not copied. "Moving" transfers ownership to a new `unique_ptr` and resets the old `unique_ptr`. ## Example 2 @@ -30,7 +43,18 @@ The following example shows how to create `unique_ptr` instances and use them in [!code-cpp[stl_smart_pointers#211](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_2.cpp)] -In the range for loop, notice that the `unique_ptr` is passed by reference. If you try to pass by value here, the compiler will throw an error because the `unique_ptr` copy constructor is deleted. +```output +Artist: B'z Title: Juice +Artist: Namie Amuro Title: Funky Town +Artist: Kome Kome Club Title: Kimi ga Iru Dake de +Artist: Ayumi Hamasaki Title: Poker Face +Destroyed: Juice +Destroyed: Funky Town +Destroyed: Kimi ga Iru Dake de +Destroyed: Poker Face +``` + +In the range for loop, notice that the `unique_ptr` is passed by reference. If you try to pass by value here, the compiler reports an error because the `unique_ptr` copy constructor is deleted. ## Example 3 @@ -38,12 +62,26 @@ The following example shows how to initialize a `unique_ptr` that is a class mem [!code-cpp[stl_smart_pointers#212](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_3.cpp)] +```output +Engine created +Engine running +Engine destroyed +``` + ## Example 4 -You can use [make_unique](../standard-library/memory-functions.md#make_unique) to create a `unique_ptr` to an array, but you cannot use `make_unique` to initialize the array elements. +You can use [make_unique](../standard-library/memory-functions.md#make_unique) to create a `unique_ptr` to an array. `make_unique(5)` creates a five element array that is value-initialized to zero. You can't pass individual element values to `make_unique`, so assign them after creation. [!code-cpp[stl_smart_pointers#213](codesnippet/CPP/how-to-create-and-use-unique-ptr-instances_4.cpp)] +```output +0 +1 +2 +3 +4 +``` + For more examples, see [make_unique](../standard-library/memory-functions.md#make_unique). ## See also diff --git a/docs/cpp/how-to-create-and-use-weak-ptr-instances.md b/docs/cpp/how-to-create-and-use-weak-ptr-instances.md index 0f5cf8724c2..0947a8d9be9 100644 --- a/docs/cpp/how-to-create-and-use-weak-ptr-instances.md +++ b/docs/cpp/how-to-create-and-use-weak-ptr-instances.md @@ -3,7 +3,6 @@ description: "Learn more about: How to: Create and use weak_ptr instances" title: "How to: Create and use weak_ptr instances" ms.custom: "how-to" ms.date: "11/19/2019" -ms.topic: "conceptual" ms.assetid: 8dd6909b-b070-4afa-9696-f2fc94579c65 --- # How to: Create and use weak_ptr instances diff --git a/docs/cpp/how-to-design-for-exception-safety.md b/docs/cpp/how-to-design-for-exception-safety.md index 8d6a8c270d3..588c564ebd8 100644 --- a/docs/cpp/how-to-design-for-exception-safety.md +++ b/docs/cpp/how-to-design-for-exception-safety.md @@ -3,7 +3,6 @@ description: "Learn more about: How to: Design for exception safety" title: "How to: Design for exception safety" ms.custom: "how-to" ms.date: "11/19/2019" -ms.topic: "conceptual" ms.assetid: 19ecc5d4-297d-4c4e-b4f3-4fccab890b3d --- # How to: Design for exception safety diff --git a/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md b/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md index 75d4de49348..2c4f1b4b128 100644 --- a/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md +++ b/docs/cpp/how-to-interface-between-exceptional-and-non-exceptional-code.md @@ -3,7 +3,6 @@ description: "Learn more about: How to: Interface between exceptional and non-ex title: "How to: Interface between exceptional and non-exceptional code" ms.custom: "how-to" ms.date: 03/02/2022 -ms.topic: "conceptual" --- # How to: Interface between exceptional and non-exceptional code diff --git a/docs/cpp/hybrid-patchable.md b/docs/cpp/hybrid-patchable.md new file mode 100644 index 00000000000..49dc470455b --- /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 bcdcc5ff98f..ab4d4e811f6 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 a4328a4eced..21563cb7493 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 349708fa551..360717d20f8 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 +description: Use import and export declarations to access and to publish types and functions defined in the specified module. +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 @@ -112,6 +109,7 @@ import // Always an identifier, never a keyword **End Microsoft Specific** -## See Also +## 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 99eefb75a3f..4ba7817947d 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 9cde55e2a54..440b30ef039 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 c024fafdcf2..14660d3866f 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 de37785bbfc..465e8537f7d 100644 --- a/docs/cpp/initializers.md +++ b/docs/cpp/initializers.md @@ -1,9 +1,8 @@ --- title: "Initializers" -ms.date: "07/29/2019" description: "How to initialize classes, structs, arrays and fundamental types in C++." +ms.date: 07/29/2019 helpviewer_keywords: ["arrays [C++], array-element initializers", "aggregate initializers [C++]"] -ms.assetid: ce301ed8-aa1c-47b2-bb39-9f0541b4af85 --- # Initializers @@ -52,8 +51,8 @@ Initializers may take these forms: }; class PointConsumer{ public: - void set_point(Point p){}; - void set_points(initializer_list my_list){}; + void set_point(Point p){} + void set_points(initializer_list my_list){} }; int main() { PointConsumer pc{}; @@ -65,7 +64,7 @@ Initializers may take these forms: ## Kinds of initialization -There are several kinds of initialization, which may occur at different points in program execution. Different kinds of initialization are not mutually exclusive—for example, list initialization can trigger value initialization and in other circumstances, it can trigger aggregate initialization. +There are several kinds of initialization, which may occur at different points in program execution. Different kinds of initialization aren't mutually exclusive—for example, list initialization can trigger value initialization and in other circumstances, it can trigger aggregate initialization. ### Zero initialization @@ -115,9 +114,9 @@ MyClass mc1; MyClass* mc3 = new MyClass; ``` -If the class, struct, or union does not have a default constructor, the compiler emits an error. +If the class, struct, or union doesn't have a default constructor, the compiler emits an error. -Scalar variables are default initialized when they are defined with no initialization expression. They have indeterminate values. +Scalar variables are default initialized when they're defined with no initialization expression. They have indeterminate values. ```cpp int i1; @@ -125,17 +124,17 @@ float f; char c; ``` -Arrays are default initialized when they are defined with no initialization expression. When an array is default-initialized, its members are default initialized and have indeterminate values, as in the following example: +Arrays are default initialized when they're defined with no initialization expression. When an array is default-initialized, its members are default initialized and have indeterminate values, as in the following example: ```cpp int int_arr[3]; ``` -If the array members do not have a default constructor, the compiler emits an error. +If the array members don't have a default constructor, the compiler emits an error. #### Default initialization of constant variables -Constant variables must be declared together with an initializer. If they are scalar types they cause a compiler error, and if they are class types that have a default constructor they cause a warning: +Constant variables must be declared together with an initializer. If they're scalar types they cause a compiler error, and if they're class types that have a default constructor they cause a warning: ```cpp class MyClass{}; @@ -181,7 +180,7 @@ Value initialization does the following: - for classes with at least one public constructor, the default constructor is called -- for non-union classes with no declared constructors, the object is zero-initialized and the default constructor is called +- for nonunion classes with no declared constructors, the object is zero-initialized and the default constructor is called - for arrays, every element is value-initialized @@ -250,10 +249,10 @@ int main() { } ``` -Copy initialization cannot invoke explicit constructors. +Copy initialization can't invoke explicit constructors. ```cpp -vector v = 10; // the constructor is explicit; compiler error C2440: cannot convert from 'int' to 'std::vector>' +vector v = 10; // the constructor is explicit; compiler error C2440: can't convert from 'int' to 'std::vector>' regex r = "a.*b"; // the constructor is explicit; same error shared_ptr sp = new int(1729); // the constructor is explicit; same error ``` @@ -423,7 +422,7 @@ myArr3: 8 9 10 0 0 #### Initializing unions and structs -If a union does not have a constructor, you can initialize it with a single value (or with another instance of a union). The value is used to initialize the first non-static field. This is different from struct initialization, in which the first value in the initializer is used to initialize the first field, the second to initialize the second field, and so on. Compare the initialization of unions and structs in the following example: +If a union doesn't have a constructor, you can initialize it with a single value (or with another instance of a union). The value is used to initialize the first non-static field. This is different from struct initialization, in which the first value in the initializer is used to initialize the first field, the second to initialize the second field, and so on. Compare the initialization of unions and structs in the following example: ```cpp struct MyStruct { @@ -489,7 +488,7 @@ int main() } ``` -The only way to initialize a reference with a temporary object is to initialize a constant temporary object. Once initialized, a reference-type variable always points to the same object; it cannot be modified to point to another object. +The only way to initialize a reference with a temporary object is to initialize a constant temporary object. Once initialized, a reference-type variable always points to the same object; it can't be modified to point to another object. Although the syntax can be the same, initialization of reference-type variables and assignment to reference-type variables are semantically different. In the preceding example, the assignments that change `iVar` and `lVar` look similar to the initializations, but have different effects. The initialization specifies the object to which the reference-type variable points; the assignment assigns to the referred-to object through the reference. @@ -521,15 +520,17 @@ Reference-type variables can be declared without initializers only in the follow extern int& iVal; ``` -When initializing a reference-type variable, the compiler uses the decision graph shown in the following figure to select between creating a reference to an object or creating a temporary object to which the reference points. +When initializing a reference-type variable, the compiler uses the decision graph shown in the following figure to select between creating a reference to an object or creating a temporary object to which the reference points: -![Decision graph for initialization of reference types.](../cpp/media/vc38s71.gif "Decision graph for initialization of reference types")
+:::image type="complex" source="../cpp/media/vc38s71.gif" alt-text="Decision graph for initialization of reference types."::: +The decision graph begins with: is the initializer an lvalue of the same type or a type derived from the type of reference? If yes, the reference refers to the object specified in the initializer. If no, the next decision is whether the reference-type variable is a const T reference being initialized and can the initializer be implicitly converted to a T? If yes, the temporary is created and the reference variable becomes a name for that temporary. If no, it's an error. +:::image-end::: Decision graph for initialization of reference types -References to **`volatile`** types (declared as **`volatile`** *typename*& *identifier*) can be initialized with **`volatile`** objects of the same type or with objects that have not been declared as **`volatile`**. They cannot, however, be initialized with **`const`** objects of that type. Similarly, references to **`const`** types (declared as **`const`** *typename*& *identifier*) can be initialized with **`const`** objects of the same type (or anything that has a conversion to that type or with objects that have not been declared as **`const`**). They cannot, however, be initialized with **`volatile`** objects of that type. +References to **`volatile`** types (declared as **`volatile`** *typename*& *identifier*) can be initialized with **`volatile`** objects of the same type or with objects that haven't been declared as **`volatile`**. They can't, however, be initialized with **`const`** objects of that type. Similarly, references to **`const`** types (declared as **`const`** *typename*& *identifier*) can be initialized with **`const`** objects of the same type (or anything that has a conversion to that type or with objects that haven't been declared as **`const`**). They can't, however, be initialized with **`volatile`** objects of that type. -References that are not qualified with either the **`const`** or **`volatile`** keyword can be initialized only with objects declared as neither **`const`** nor **`volatile`**. +References that aren't qualified with either the **`const`** or **`volatile`** keyword can be initialized only with objects declared as neither **`const`** nor **`volatile`**. ### Initialization of external variables -Declarations of automatic, static, and external variables can contain initializers. However, declarations of external variables can contain initializers only if the variables are not declared as **`extern`**. +Declarations of automatic, static, and external variables can contain initializers. However, declarations of external variables can contain initializers only if the variables aren't declared as **`extern`**. diff --git a/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md b/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md index f47974713af..88ddfde83fb 100644 --- a/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md +++ b/docs/cpp/initializing-classes-and-structs-without-constructors-cpp.md @@ -42,8 +42,9 @@ int main() // Member initialization (in order of declaration): TempData td{ 45978, time(&time_to_set), 28.9, 37.0, 16.7 }; - // Default initialization = {0,0,0,0,0} - TempData td_default{}; + // When there's no constructor, an empty brace initializer does + // value initialization = {0,0,0,0,0} + TempData td_emptyInit{}; // Uninitialized = if used, emits warning C4700 uninitialized local variable TempData td_noInit; @@ -55,7 +56,7 @@ int main() } ``` -When a `class` or `struct` has no constructor, you provide the list elements in the order that the members are declared in the `class`. If the `class` has a constructor, provide the elements in the order of the parameters. If a type has a default constructor, either implicitly or explicitly declared, you can use default brace initialization (with empty braces). For example, the following `class` may be initialized by using both default and non-default brace initialization: +When a `class` or `struct` has no constructor, you provide the list elements in the order that the members are declared in the `class`. If the `class` has a constructor, provide the elements in the order of the parameters. If a type has a default constructor, either implicitly or explicitly declared, you can use brace initialization with empty braces to invoke it. For example, the following `class` may be initialized by using both empty and non-empty brace initialization: ```cpp #include @@ -106,7 +107,7 @@ int main() } ``` -If the default constructor is explicitly declared but marked as deleted, default brace initialization can't be used: +If the default constructor is explicitly declared but marked as deleted, empty brace initialization can't be used: ```cpp class class_f { diff --git a/docs/cpp/inline-functions-cpp.md b/docs/cpp/inline-functions-cpp.md index 76552aea2bf..f67599ff01b 100644 --- a/docs/cpp/inline-functions-cpp.md +++ b/docs/cpp/inline-functions-cpp.md @@ -1,90 +1,125 @@ --- title: "Inline Functions (C++)" description: "The C++ inline keyword can be used to suggest inline functions to the compiler." -ms.date: 05/17/2022 +ms.date: 02/05/2026 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 doesn'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. +## The `inline` keyword and the One Definition Rule (ODR) -## Example +The original meaning of **`inline`** is a hint to the compiler to prefer code expansion at the call site over function call instructions. This remains one of the meanings of **`inline`**. -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. +However, the **`inline`** keyword also has implications for the One Definition Rule (ODR). Normally, a function can only be defined once across all translation units. When a function is marked **`inline`**, it can be defined in multiple translation units (typically via a header file) if all the definitions are identical. The linker then selects one definition and discards the duplicates rather than reporting an error. + +This dual nature of **`inline`**—as both an optimization hint and an ODR mechanism—can cause confusion. The ODR aspect is a practical necessity where the same header (containing an inline function definition) may be included in multiple source files. + +## Implicitly inline functions + +Certain functions are implicitly **`inline`** without requiring the keyword: + +- **Functions defined at class scope**: A function defined in the body of a class declaration is implicitly an inline function. This allows small accessor functions and to be defined directly in class definitions without incurring function call overhead—a priority since the early days of C++. + +- **`constexpr` functions**: Functions declared **`constexpr`** (introduced in C++11) are implicitly **`inline`**. Because **`constexpr`** functions are typically defined in header files to allow compile-time evaluation, they must follow the same ODR rules as inline functions. + +- **`consteval` functions**: Functions declared **`consteval`** (introduced in C++20) are implicitly **`inline`**. + +## Inline variables (C++17) + +C++17 extended the **`inline`** keyword to variables. An **`inline`** variable can be defined in multiple translation units, and like inline functions, the linker selects one definition and discards the rest. + +Inline variables are useful for defining constants or static data members in header files: ```cpp -// Inline_Member_Functions.cpp +// constants.h +inline constexpr double pi = 3.14159265358979323846; + +struct MyClass +{ + static inline int instanceCount = 0; // Can be defined in header +}; +``` + +Before C++17, such variables required a separate definition in a single source file to avoid linker errors. + +## Example: Inline class member functions + +In the following class declaration, the `Account` constructor is an inline function because it's 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 +// account.h class Account { public: - Account(double initial_balance) { balance = initial_balance; } - double GetBalance(); - double Deposit( double Amount ); - double Withdraw( double Amount ); + Account(double initial_balance) + { + balance = initial_balance; + } + + double GetBalance() const; + double Deposit(double amount); + double Withdraw(double amount); + private: double balance; }; -inline double Account::GetBalance() +inline double Account::GetBalance() const { return balance; } -inline double Account::Deposit( double Amount ) +inline double Account::Deposit(double amount) { - return ( balance += Amount ); + balance += amount; + return balance; } -inline double Account::Withdraw( double Amount ) -{ - return ( balance -= Amount ); -} -int main() +inline double Account::Withdraw(double amount) { + balance -= amount; + return balance; } ``` > [!NOTE] > In the class declaration, the functions were declared without the **`inline`** keyword. The **`inline`** keyword can be specified in the class declaration; the result is the same. -A given inline member function must be declared the same way in every compilation unit. This constraint causes inline functions to behave as if they were instantiated functions. Additionally, there must be exactly one definition of an inline function. +A given inline member function must be declared the same way in every compilation unit. There must be exactly one definition of an inline function. -A class member function defaults to external linkage unless a definition for that function contains the **`inline`** specifier. The preceding example shows that you don't have to declare these functions explicitly with the **`inline`** specifier. Using **`inline`** in the function definition causes it to be an inline function. However, it's not allowed to redeclare a function as **`inline`** after a call to that function. +A class member function defaults to external linkage unless a definition for that function contains the **`inline`** specifier. The preceding example shows that you don't have to declare these functions explicitly with the **`inline`** specifier. Using **`inline`** in the function definition suggests to the compiler to treat it 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). +The **`__forceinline`** keyword (or [`[msvc::forceinline]`](/cpp/cpp/attributes#msvcforceinline) attribute) 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). -The compiler treats the inline expansion options and keywords as suggestions. There's no guarantee that functions will be inlined. You can't force the compiler to inline a particular function, even with the **`__forceinline`** keyword. When compiling with **`/clr`**, the compiler won't inline a function if there are security attributes applied to the function. +The compiler treats the inline expansion options and keywords as suggestions. There's no guarantee that functions will be inlined. You can't force the compiler to inline a particular function, even with the **`__forceinline`** keyword. When you compile with **`/clr`**, the compiler won't inline a function if there are security attributes applied to the function. -The **`inline`** keyword is available only in C++. The **`__inline`** and **`__forceinline`** keywords are available in both C and C++. For compatibility with previous versions, **`_inline`** and **`_forceinline`** are synonyms for **`__inline`**, and **`__forceinline`** unless compiler option [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. +For compatibility with previous versions, **`_inline`** and **`_forceinline`** are synonyms for **`__inline`** and **`__forceinline`** (two leading underscores), 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 +127,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 +141,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,55 +156,60 @@ 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. +The C++ Standard defines a common set of attributes. It also allows compiler vendors to define their own attributes within a vendor-specific (in our case, `msvc`) namespace. The following Microsoft-specific attributes can be used to control inlining behavior: + +## Microsoft-specific attributes for controlling inlining behavior + +|Attribute | Meaning | +|---------|---------| +| [`[msvc::forceinline]`](/cpp/cpp/attributes#msvcforceinline)| Has the same meaning as **`__forceinline`**.| +| [`[msvc::forceinline_calls]`](/cpp/cpp/attributes#msvcforceinline_calls) | Can be placed on or before a statement or block to cause the inline heuristic to force-inline all calls in that statement or block.| +| [`[msvc::flatten]`](/cpp/cpp/attributes#msvcflatten) | Similar to `[[msvc::forceinline_calls]]`, but recursively force-inlines all calls in the scope it's applied to until no calls are left. | +| [`[msvc::noinline]`](/cpp/cpp/attributes#msvcnoinline) | When placed before a function declaration, has the same meaning as `__declspec(noinline)`. | +| [`[msvc::noinline_calls]`](/cpp/cpp/attributes#msvcnoinline_calls) | Can be placed before any statement or block to turn off inlining for all calls in the scope it's applied to. | + **END Microsoft Specific** 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,86 +219,108 @@ 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. +A macro has some things in common with an `inline` function. But there are important differences. Consider the following example: -- Inline functions are specified using the same syntax as any other function except that they include the **`inline`** keyword in the function declaration. - -- Expressions passed as arguments to inline functions are evaluated once. In some cases, expressions passed as arguments to macros can be evaluated more than once. +```cpp +#include -The following example shows a macro that converts lowercase letters to uppercase: +#define mult1(a, b) a * b +#define mult2(a, b) (a) * (b) +#define mult3(a, b) ((a) * (b)) -```cpp -// inline_functions_macro.c -#include -#include +inline int multiply(int a, int b) +{ + return a * b; +} -#define toupper(a) ((a) >= 'a' && ((a) <= 'z') ? ((a)-('a'-'A')):(a)) +int main() +{ + std::cout << (48 / mult1(2 + 2, 3 + 3)) << std::endl; // outputs 33 + std::cout << (48 / mult2(2 + 2, 3 + 3)) << std::endl; // outputs 72 + std::cout << (48 / mult3(2 + 2, 3 + 3)) << std::endl; // outputs 2 + std::cout << (48 / multiply(2 + 2, 3 + 3)) << std::endl; // outputs 2 -int main() { - char ch; - printf_s("Enter a character: "); - ch = toupper( getc(stdin) ); - printf_s( "%c", ch ); + std::cout << mult3(2, 2.2) << std::endl; // no warning + std::cout << multiply(2, 2.2); // Warning C4244 'argument': conversion from 'double' to 'int', possible loss of data } -// Sample Input: xyz -// Sample Output: Z ``` -The intent of the expression `toupper(getc(stdin))` is that a character should be read from the console device (`stdin`) and, if necessary, converted to uppercase. +```Output +33 +72 +2 +2 +4.4 +4 +``` -Because of the implementation of the macro, `getc` is executed once to determine whether the character is greater than or equal to "a," and once to determine whether it's less than or equal to "z." If it is in that range, `getc` is executed again to convert the character to uppercase. It means the program waits for two or three characters when, ideally, it should wait for only one. +Here are some of the differences between the macro and the inline function: -Inline functions remedy the problem previously described: +- Macros are always expanded inline. However, an inline function is only inlined when the compiler determines it's 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 solves 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)\ -[`auto_inline`](../preprocessor/auto-inline.md) +[`auto_inline`](../preprocessor/auto-inline.md)\ +[`[msvc::forceinline]`](/cpp/cpp/attributes#msvcforceinline)\ +[`[msvc::forceinline_calls]`](/cpp/cpp/attributes#msvcforceinline_calls)\ +[`[msvc::flatten]`](/cpp/cpp/attributes#msvcflatten)\ +[`[msvc::nolinline]`](/cpp/cpp/attributes#msvcnoinline)\ +[`[msvc::nolinline_calls]`](/cpp/cpp/attributes#msvcnoinline_calls) \ No newline at end of file diff --git a/docs/cpp/keywords-cpp.md b/docs/cpp/keywords-cpp.md index f6d042ba489..8d9269c07fb 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)\ @@ -116,9 +115,9 @@ Keywords are predefined reserved identifiers that have special meanings. They ca :::column-end::: :::row-end::: -a The Microsoft-specific **`__asm`** keyword replaces C++ **`asm`** syntax. **`asm`** is reserved for compatibility with other C++ implementations, but not implemented. Use **`__asm`** for inline assembly on x86 targets. Microsoft C++ doesn't support Inline assembly for other targets. +a The Microsoft-specific **`__asm`** keyword replaces C++ **`asm`** syntax. **`asm`** is reserved for compatibility with other C++ implementations, but not implemented. Use **`__asm`** for inline assembly on x86 targets. Microsoft C++ doesn't support inline assembly for other targets. -b The extended operator synonyms are keywords when [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. They aren't keywords when Microsoft extensions are enabled. +b The extended operator synonyms are keywords when [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za` (Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. They aren't keywords when Microsoft extensions are enabled. c Supported when [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later (such as **`/std:c++latest`**) is specified. @@ -126,7 +125,7 @@ Keywords are predefined reserved identifiers that have special meanings. They ca In C++, identifiers that contain two consecutive underscores are reserved for compiler implementations. The Microsoft convention is to precede Microsoft-specific keywords with double underscores. These words can't be used as identifier names. -Microsoft extensions are enabled by default. To ensure that your programs are fully portable, you can disable Microsoft extensions by specifying the [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za` \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) option during compilation. These options disable some Microsoft-specific keywords. +Microsoft extensions are enabled by default. To ensure that your programs are fully portable, you can disable Microsoft extensions by specifying the [`/permissive-`](../build/reference/permissive-standards-conformance.md) or [`/Za` (Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) option during compilation. These options disable some Microsoft-specific keywords. When Microsoft extensions are enabled, you can use the Microsoft-specific keywords in your programs. For ANSI conformance, these keywords are prefaced by a double underscore. For backward compatibility, single-underscore versions of many of the double-underscored keywords are supported. The **`__cdecl`** keyword is available with no leading underscore. @@ -167,11 +166,11 @@ The **`__based`** keyword has limited uses for 32-bit and 64-bit target compilat [`__m64`](m64.md)\ [`__multiple_inheritance`](inheritance-keywords.md) e\ [`__ptr32`](ptr32-ptr64.md) e\ - [`__ptr64`](ptr32-ptr64.md)e\ + [`__ptr64`](ptr32-ptr64.md) e\ [`__raise`](raise.md)\ [`__restrict`](extension-restrict.md) e\ - [`__single_inheritance`](inheritance-keywords.md)e\ - [`__sptr`](sptr-uptr.md)e\ + [`__single_inheritance`](inheritance-keywords.md) e\ + [`__sptr`](sptr-uptr.md) e\ [`__stdcall`](stdcall.md) e :::column-end::: :::column::: @@ -192,7 +191,7 @@ The **`__based`** keyword has limited uses for 32-bit and 64-bit target compilat e For backward compatibility with previous versions, these keywords are available both with two leading underscores and a single leading underscore when Microsoft extensions are enabled (the default). -## Microsoft keywords in __declspec modifiers +## Microsoft keywords in `__declspec` modifiers These identifiers are extended attributes for the **`__declspec`** modifier. They're considered keywords within that context. @@ -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 6756e7efac3..74d9b2a76a9 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,9 +105,9 @@ When you use the capture clause, we recommend that you keep these points in mind - Reference captures introduce a lifetime dependency, but value captures have no lifetime dependencies. It's especially important when the lambda runs asynchronously. If you capture a local by reference in an async lambda, that local could easily be gone by the time the lambda runs. Your code could cause an access violation at run time. -### Generalized capture (C++ 14) +### Generalized capture (C++14) -In C++14, you can introduce and initialize new variables in the capture clause, without the need to have those variables exist in the lambda function’s enclosing scope. The initialization can be expressed as any arbitrary expression; the type of the new variable is deduced from the type produced by the expression. This feature lets you capture move-only variables (such as `std::unique_ptr`) from the surrounding scope and use them in a lambda. +In C++14, you can introduce and initialize new variables in the capture clause, without the need to have those variables exist in the lambda function's enclosing scope. The initialization can be expressed as any arbitrary expression; the type of the new variable is deduced from the type produced by the expression. This feature lets you capture move-only variables (such as `std::unique_ptr`) from the surrounding scope and use them in a lambda. ```cpp pNums = make_unique>(nums); diff --git a/docs/cpp/left-shift-and-right-shift-operators-input-and-output.md b/docs/cpp/left-shift-and-right-shift-operators-input-and-output.md index 9fb7c08ec2b..ca0ac901cab 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 812624506ea..359a0ebbf49 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 8533e8f8b16..b5a178d585e 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 c4dbc9e284b..ad2e8ebae47 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,18 +13,21 @@ 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. +An xvalue expression has an address that is 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. ## Example diff --git a/docs/cpp/m64.md b/docs/cpp/m64.md index 74c415036ca..66800090f64 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 9e632f62516..ac291e13746 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 75a4b731c7f..00000000000 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 2f7a74fd605..27f8ab7b177 100644 --- a/docs/cpp/member-access-control-cpp.md +++ b/docs/cpp/member-access-control-cpp.md @@ -228,9 +228,11 @@ In the preceding example, calling the virtual function `GetState` using a pointe ## Access control with multiple inheritance -In multiple-inheritance lattices involving virtual base classes, a given name can be reached through more than one path. Because different access control can be applied along these different paths, the compiler chooses the path that gives the most access. See the following figure. +In multiple-inheritance lattices involving virtual base classes, a given name can be reached through more than one path. Because different access control can be applied along these different paths, the compiler chooses the path that gives the most access. See the following figure: -![Diagram showing access along the paths of an inheritance graph.](../cpp/media/vc38v91.gif "Access along paths of an inheritance graph")
+:::image type="complex" source="../cpp/media/vc38v91.gif" alt-text="Diagram showing access along the paths of an inheritance graph."::: +The diagram shows the following inheritance hierarchy: class VBase is the base class. Class LeftPath inherits from VBase using virtual private VBase. class RightPath also inherits from VBase but using virtual public VBase. Finally, class Derived inherits from both class LeftPath and class RightPath using public LeftPath, public RightPath. +:::image-end::: Access along paths of an inheritance graph In the figure, a name declared in class `VBase` is always reached through class `RightPath`. The right path is more accessible because `RightPath` declares `VBase` as a **`public`** base class, while `LeftPath` declares `VBase` as **`private`**. diff --git a/docs/cpp/member-function-templates.md b/docs/cpp/member-function-templates.md index 7ae5206125a..6ce35e319de 100644 --- a/docs/cpp/member-function-templates.md +++ b/docs/cpp/member-function-templates.md @@ -1,19 +1,19 @@ --- -description: "Learn more about: Member Function Templates" -title: "Member Function Templates" -ms.date: "11/04/2016" +description: "Learn more about: Member function templates" +title: "Member function templates" +ms.date: 09/27/2022 helpviewer_keywords: ["function templates, member functions"] ms.assetid: 83d51835-6a27-40ed-997c-7d90dc9182d8 --- -# Member Function Templates +# Member function templates -The term member template refers to both member function templates and nested class templates. Member function templates are template functions that are members of a class or class template. +The term member template refers to both member function templates and nested class templates. Member function templates are function templates that are members of a class or class template. -Member functions can be function templates in several contexts. All functions of class templates are generic but are not referred to as member templates or member function templates. If these member functions take their own template arguments, they are considered to be member function templates. +Member functions can be function templates in several contexts. All functions of class templates are generic but aren't referred to as member templates or member function templates. If these member functions take their own template arguments, they're considered to be member function templates. ## Example: Declare member function templates -Member function templates of nontemplate or template classes are declared as function templates with their template parameters. +Member function templates of non-template classes or class templates are declared as function templates with their template parameters. ```cpp // member_function_templates.cpp @@ -30,9 +30,9 @@ int main() } ``` -## Example: Member function template of template class +## Example: Member function template of a class template -The following example shows a member function template of a template class. +The following example shows a member function template of a class template. ```cpp // member_function_templates2.cpp @@ -75,9 +75,9 @@ int main() ## Example: Templated user-defined conversion -Local classes are not allowed to have member templates. +Local classes aren't allowed to have member templates. -Member template functions cannot be virtual functions and cannot override virtual functions from a base class when they are declared with the same name as a base class virtual function. +Member function templates can't be virtual functions. And, they can't override virtual functions from a base class when they're declared with the same name as a base class virtual function. The following example shows a templated user-defined conversion: @@ -101,4 +101,4 @@ int main() ## See also -[Function Templates](../cpp/function-templates.md) +[Function templates](../cpp/function-templates.md) diff --git a/docs/cpp/microsoft-extensions.md b/docs/cpp/microsoft-extensions.md index daa58f6df41..55d937622ac 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 3d8fc865625..fda7e966152 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 7b47677a5d2..333beca9b52 100644 --- a/docs/cpp/modules-cpp.md +++ b/docs/cpp/modules-cpp.md @@ -1,43 +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. - -## Enable modules in the Microsoft C++ compiler +C++20 introduces *modules*. A *module* is a set of source code files that are compiled independently of the source files (or more precisely, the [translation units](https://wikipedia.org/wiki/Translation_unit_(programming))) that import them. -Modules have had experimental support in the Microsoft C++ compiler for a long time. As of Visual Studio 2022 version 17.1, C++20 standard modules are fully implemented in the Microsoft C++ compiler. You can use the modules feature to create single-partition modules and to import the Standard Library modules provided by Microsoft. To enable support for 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)**. +Modules eliminate or reduce many of the problems associated with the use of header files. They often reduce compilation times, sometimes significantly. Macros, preprocessor directives, and nonexported names declared in a module aren't visible outside the module. They have no effect on the compilation of the translation unit that imports the module. You can import modules in any order without concern for macro redefinitions. Declarations in the importing translation unit don't participate in overload resolution or name lookup in the imported module. After a module is compiled once, the results are stored in a binary file that describes all the exported types, functions, and templates. The compiler can process that file much faster than a header file. And, the compiler can reuse it every place where the module is imported in a project. -A module and the code that consumes it must be compiled with the same compiler options. +You can use modules side by side with header files. A C++ source file can `import` modules and also `#include` header files. In some cases, you can import a header file as a module, which is faster than using `#include` to process it with the preprocessor. We recommend that you use modules in new projects rather than header files as much as possible. For larger existing projects under active development, experiment with converting legacy headers to modules. Base your adoption on whether you get a meaningful reduction in compilation times. -## Consume the C++ Standard Library as modules +To contrast modules with other ways to import the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). -Although not specified by the C++20 standard, Microsoft makes its implementation of the C++ Standard Library importable as modules. By importing the C++ Standard Library as modules rather than including it through header files, you can potentially speed up compilation times depending on the size of your project. The library is split into the following named modules: +Starting with Visual Studio 2022 version 17.5, importing the Standard Library as a module is both standardized and fully implemented in the Microsoft C++ compiler. To learn how to import the Standard Library using modules, see [Import the C++ standard library using modules](tutorial-import-stl-named-module.md). -- `std.regex` provides the content of header `` -- `std.filesystem` provides the content of header `` -- `std.memory` provides the content of header `` -- `std.threading` provides the contents of headers ``, ``, ``, ``, ``, and `` -- `std.core` provides everything else in the C++ Standard Library - -To consume these modules, add an import declaration to the top of the source code file. For example: - -```cpp -import std.core; -import std.regex; -``` +## Single-partition modules -To consume the Microsoft Standard Library 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 @@ -47,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; @@ -74,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 @@ -99,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 *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 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 *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 @@ -164,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 @@ -174,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 ``` @@ -191,5 +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) +[Named modules tutorial](tutorial-named-modules-cpp.md)\ +[Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md) diff --git a/docs/cpp/multiple-base-classes.md b/docs/cpp/multiple-base-classes.md index aa470f564d0..26bdbee6881 100644 --- a/docs/cpp/multiple-base-classes.md +++ b/docs/cpp/multiple-base-classes.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Multiple Base Classes" title: "Multiple Base Classes" -ms.date: "11/19/2018" +description: "Learn more about: 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 @@ -12,24 +11,23 @@ A class can be derived from more than one base class. In a multiple-inheritance ```cpp // deriv_MultipleBaseClasses.cpp // compile with: /LD -class Collection { -}; +class Collection {}; class Book {}; class CollectionOfBook : public Book, public Collection { // New members }; ``` -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. + > 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 +39,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="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="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,35 +66,41 @@ 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="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="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="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: ```cpp #pragma vtordisp( off ) class GetReal : virtual public { ... }; -\#pragma vtordisp( on ) +#pragma vtordisp( on ) ``` ## 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 +116,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 +125,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,15 +133,15 @@ 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).) +1. If access to the name violates member-access permission, an error message is generated. For more information, see [Member-Access Control](member-access-control-cpp.md). When an expression produces an ambiguity through inheritance, you can manually resolve it by qualifying the name in question with its class name. To make the preceding example compile properly with no ambiguities, use code such as: @@ -148,9 +156,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 +187,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="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,15 +205,17 @@ 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="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 -[Inheritance](../cpp/inheritance-cpp.md) +[Inheritance](inheritance-cpp.md) diff --git a/docs/cpp/multiplicative-operators-and-the-modulus-operator.md b/docs/cpp/multiplicative-operators-and-the-modulus-operator.md index 588bec202e7..3dd6968ca1a 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 0c35e0be6dd..6f074013479 100644 --- a/docs/cpp/mutable-data-members-cpp.md +++ b/docs/cpp/mutable-data-members-cpp.md @@ -1,14 +1,13 @@ --- description: "Learn more about: Mutable Data Members (C++)" title: "Mutable Data Members (C++)" -ms.date: "11/04/2016" +ms.date: "03/14/2024" f1_keywords: ["mutable_cpp"] helpviewer_keywords: ["mutable keyword [C++]"] -ms.assetid: ebe89746-3d36-43a8-8d69-f426af23f551 --- # Mutable Data Members (C++) -This keyword can only be applied to non-static and non-const data members of a class. If a data member is declared **`mutable`**, then it is legal to assign a value to this data member from a **`const`** member function. +This keyword can only be applied to non-static, non-const, and non-reference data members of a class. If a data member is declared **`mutable`**, then it is legal to assign a value to this data member from a **`const`** member function. ## Syntax @@ -25,19 +24,15 @@ For example, the following code will compile without error because `m_accessCoun class X { public: - bool GetFlag() const - { - m_accessCount++; - return m_flag; - } + bool GetFlag() const + { + m_accessCount++; + return m_flag; + } private: - bool m_flag; - mutable int m_accessCount; + bool m_flag; + mutable int m_accessCount; }; - -int main() -{ -} ``` ## See also diff --git a/docs/cpp/name-resolution-for-locally-declared-names.md b/docs/cpp/name-resolution-for-locally-declared-names.md index 8d161502897..be2d0b31bc2 100644 --- a/docs/cpp/name-resolution-for-locally-declared-names.md +++ b/docs/cpp/name-resolution-for-locally-declared-names.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Name Resolution for Locally Declared Names" title: "Name Resolution for Locally Declared Names" -ms.date: "11/04/2016" +ms.date: 09/27/2022 ms.assetid: 743b88f3-de11-48f4-ae83-931449ea3886 --- # Name Resolution for Locally Declared Names @@ -10,7 +10,7 @@ The template's name itself can be referred to with or without the template argum ## Example: Specialization versus partial specialization -The following code shows that the class template's name A is interpreted differently in the scope of a specialization or partial specialization. +The following code shows that the class template's name `A` is interpreted differently in the scope of a specialization or partial specialization. ```cpp // template_name_resolution3.cpp @@ -32,7 +32,7 @@ template<> class A { ## Example: Name conflict between template parameter and object -In the case of a name conflict between a template parameter and another object, the template parameter can or cannot be hidden. The following rules will help determine precedence. +When there's a name conflict between a template parameter and another object, the template parameter can or can't be hidden. The following rules will help determine precedence. The template parameter is in scope from the point where it first appears until the end of the class or function template. If the name appears again in the template argument list or in the list of base classes, it refers to the same type. In standard C++, no other name that is identical to the template parameter can be declared in the same scope. A Microsoft extension allows the template parameter to be redefined in the scope of the template. The following example shows using the template parameter in the base specification of a class template. @@ -52,7 +52,7 @@ int main() { ## Example: Define member function outside class template -When defining a template's member functions outside the class template, a different template parameter name can be used. If the template member function definition uses a different name for the template parameter than the declaration does, and the name used in the definition conflicts with another member of the declaration, the member in the template declaration takes precedence. +When member functions are defined outside the class template, a different template parameter name can be used. If the class template member function's definition uses a different name for the template parameter than the declaration does, and the name used in the definition conflicts with another member of the declaration, the member in the template declaration takes precedence. ```cpp // template_name_resolution5.cpp @@ -87,7 +87,7 @@ Z::Z() ## Example: Define template or member function outside namespace -When defining a template function or member function outside the namespace in which the template was declared, the template argument takes precedence over the names of other members of the namespace. +When defining a function template or a member function outside the namespace in which the template was declared, the template argument takes precedence over the names of other members of the namespace. ```cpp // template_name_resolution6.cpp @@ -121,7 +121,7 @@ C::g ## Example: Base class or member name hides template argument -In definitions that are outside of the template class declaration, if a template class has a base class that does not depend on a template argument and if the base class or one of its members has the same name as a template argument, then the base class or member name hides the template argument. +In definitions that are outside of the template class declaration, if a template class has a base class that doesn't depend on a template argument and if the base class or one of its members has the same name as a template argument, then the base class or member name hides the template argument. ```cpp // template_name_resolution7.cpp @@ -159,4 +159,4 @@ Base ## See also -[Name Resolution](../cpp/templates-and-name-resolution.md) +[Name resolution](../cpp/templates-and-name-resolution.md) diff --git a/docs/cpp/namespaces-cpp.md b/docs/cpp/namespaces-cpp.md index 91eeb7b5082..8051071fee7 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/noexcept-cpp.md b/docs/cpp/noexcept-cpp.md index 9302f2cc285..ceca8431bb2 100644 --- a/docs/cpp/noexcept-cpp.md +++ b/docs/cpp/noexcept-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: noexcept (C++)" title: "noexcept (C++)" -ms.date: 11/30/2021 +ms.date: 09/27/2022 f1_keywords: ["noexcept_cpp"] ms.assetid: df24edb9-c6a6-4e37-9914-fd5c0c3716a8 --- @@ -31,7 +31,7 @@ Mark a function as **`noexcept`** only if all the functions that it calls, eithe ## Example -A template function that copies its argument might be declared **`noexcept`** on the condition that the object being copied is a plain old data type (POD). Such a function could be declared like this: +A function template that copies its argument might be declared **`noexcept`** on the condition that the object being copied is a plain old data type (POD). Such a function could be declared like this: ```cpp #include diff --git a/docs/cpp/nonstandard-behavior.md b/docs/cpp/nonstandard-behavior.md index d7d9e061dea..2871910d0de 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 52f2b3db728..e06cecf56ea 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/nothrow-cpp.md b/docs/cpp/nothrow-cpp.md index b0749a32f4c..fd5ebc478b4 100644 --- a/docs/cpp/nothrow-cpp.md +++ b/docs/cpp/nothrow-cpp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: nothrow (C++)" title: "nothrow (C++)" -ms.date: "01/03/2018" +description: "Learn more about: nothrow (C++)" +ms.date: 01/03/2018 f1_keywords: ["nothrow_cpp"] helpviewer_keywords: ["__declspec keyword [C++], nothrow", "nothrow __declspec keyword"] -ms.assetid: 0a475139-459c-4ec6-99e8-7ecd0d7f44a3 --- # `nothrow` (C++) @@ -20,7 +19,7 @@ A **`__declspec`** extended attribute which can be used in the declaration of fu We recommend that all new code use the [`noexcept`](noexcept-cpp.md) operator rather than `__declspec(nothrow)`. -This attribute tells the compiler that the declared function and the functions it calls never throw an exception. However, it does not enforce the directive. In other words, it never causes [`std::terminate`](../standard-library/exception-functions.md#terminate) to be invoked, unlike **`noexcept`**, or in **`std:c++17`** mode (Visual Studio 2017 version 15.5 and later), `throw()`. +This attribute tells the compiler that the declared function and the functions it calls never throw an exception. However, it does not enforce the directive. In other words, it never causes [`std::terminate`](../standard-library/exception-functions.md#terminate) to be invoked, unlike **`noexcept`**, or in **`/std:c++17`** mode (Visual Studio 2017 version 15.5 and later), `throw()`. With the synchronous exception handling model, now the default, the compiler can eliminate the mechanics of tracking the lifetime of certain unwindable objects in such a function, and significantly reduce the code size. Given the following preprocessor directive, the three function declarations below are equivalent in **`/std:c++14`** mode: diff --git a/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md b/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md index 3609a42adb2..f57d1fb1360 100644 --- a/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md +++ b/docs/cpp/numeric-boolean-and-pointer-literals-cpp.md @@ -63,7 +63,7 @@ auto val_4 = 0x8000000000000000ULL << 16; // unsigned long long **Digit separators**: You can use the single-quote character (apostrophe) to separate place values in larger numbers to make them easier for humans to read. Separators have no effect on compilation. ```cpp -long long i = 24'847'458'121 +long long i = 24'847'458'121; ``` ## Floating point literals diff --git a/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md b/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md index a36c0eaff6b..a4aa439b894 100644 --- a/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md +++ b/docs/cpp/object-lifetime-and-resource-management-modern-cpp.md @@ -2,7 +2,7 @@ title: "Object lifetime and resource management (RAII)" description: "Follow the principle of RAII in modern C++ to avoid resource leaks." ms.date: 06/02/2022 -ms.topic: "conceptual" +ms.topic: "concept-article" ms.assetid: 8aa0e1a1-e04d-46b1-acca-1d548490700f --- # Object lifetime and resource management (RAII) @@ -53,7 +53,6 @@ void functionUsingWidget() { w.do_something(); } // automatic destruction and deallocation for w and w.data - ``` Since C++11, there's a better way to write the previous example: by using a smart pointer from the standard library. The smart pointer handles the allocation and deletion of the memory it owns. Using a smart pointer eliminates the need for an explicit destructor in the `widget` class. diff --git a/docs/cpp/one-s-complement-operator-tilde.md b/docs/cpp/one-s-complement-operator-tilde.md index 1f996f18f71..bcdc6623a1a 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 d515ad8419b..f8e8fc30319 100644 --- a/docs/cpp/overload-resolution-of-function-template-calls.md +++ b/docs/cpp/overload-resolution-of-function-template-calls.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: Overload Resolution of Function Template Calls" -title: "Overload Resolution of Function Template Calls" -ms.date: "11/04/2016" +title: "Overload resolution of function template calls" +description: "Learn more about: Overload resolution of function template calls" +ms.date: 09/27/2022 helpviewer_keywords: ["function templates overload resolution"] -ms.assetid: a2918748-2cbb-4fc6-a176-e256f120bee4 --- -# Overload Resolution of Function Template Calls +# Overload resolution of function template calls -A function template can overload nontemplate functions of the same name. In this scenario, function calls are resolved by first using template argument deduction to instantiate the function template with a unique specialization. If template argument deduction fails, the other function overloads are considered to resolve the call. These other overloads, also known as the candidate set, include nontemplate functions and other instantiated function templates. If template argument deduction succeeds, then the generated function is compared with the other functions to determine the best match, following the rules for overload resolution. For more information, see [Function Overloading](function-overloading.md). +A function template can overload non-template functions of the same name. In this scenario, the compiler first attempts to resolve a function call by using template argument deduction to instantiate the function template with a unique specialization. If template argument deduction fails, then the compiler considers both instantiated function template overloads and non-template function overloads to resolve the call. These other overloads are known as the *candidate set*. If template argument deduction succeeds, then the generated function is compared with the other functions in the candidate set to determine the best match, following the rules for overload resolution. For more information, see [Function overloading](function-overloading.md). -## Example: Choose a nontemplate function +## Example: Choose a non-template function -If a nontemplate function is an equally good match to a template function, the nontemplate function is chosen (unless the template arguments were explicitly specified), as in the call `f(1, 1)` in the following example. +If a non-template function is an equally good match to a function template, the non-template function is chosen (unless the template arguments were explicitly specified), as in the call `f(1, 1)` in the following example. ```cpp // template_name_resolution9.cpp @@ -26,12 +25,12 @@ template void f(T1, T2) { cout << "void f(T1, T2)" << endl; -}; +} int main() { - f(1, 1); // Equally good match; choose the nontemplate function. - f('a', 1); // Chooses the template function. + f(1, 1); // Equally good match; choose the non-template function. + f('a', 1); // Chooses the function template. f(2, 2); // Template arguments explicitly specified. } ``` @@ -42,9 +41,9 @@ void f(T1, T2) void f(T1, T2) ``` -## Example: Exact match template function preferred +## Example: Exact match function template preferred -The next example illustrates that the exactly matching template function is preferred if the nontemplate function requires a conversion. +The next example illustrates that the exactly matching function template is preferred if the non-template function requires a conversion. ```cpp // template_name_resolution10.cpp @@ -58,13 +57,13 @@ template void f(T1, T2) { cout << "void f(T1, T2)" << endl; -}; +} int main() { long l = 0; int i = 0; - // Call the template function f(long, int) because f(int, int) + // Call the function template f(long, int) because f(int, int) // would require a conversion from long to int. f(l, i); } @@ -76,5 +75,5 @@ void f(T1, T2) ## See also -[Name Resolution](../cpp/templates-and-name-resolution.md)
-[typename](../cpp/typename.md) +[Name resolution](templates-and-name-resolution.md)\ +[`typename`](typename.md) diff --git a/docs/cpp/overloading-unary-operators.md b/docs/cpp/overloading-unary-operators.md index d99c49b8cce..6d9b26f6b07 100644 --- a/docs/cpp/overloading-unary-operators.md +++ b/docs/cpp/overloading-unary-operators.md @@ -1,51 +1,57 @@ --- -description: "Learn more about: Overloading Unary Operators" -title: "Overloading Unary Operators" -ms.date: "11/04/2016" +description: "Learn more about: Overloading unary operators" +title: "Overloading unary operators" +ms.date: 07/08/2022 helpviewer_keywords: ["unary operators [C++], plus", "increment operators [C++], overloaded", "unary operators [C++], minus", "operators [C++], unary", "redefinable unary operators [C++]", "unary operators [C++]", "pointer dereference operator overloading", "plus operator"] ms.assetid: 7683ef08-42a4-4283-928f-d3dd4f3ab4c0 --- -# Overloading Unary Operators +# Overloading unary operators -The unary operators that can be overloaded are the following: +Unary operators produce a result from a single operand. You can define overloads of a standard set of unary operators to work on user-defined types. -1. `!` ([logical NOT](../cpp/logical-negation-operator-exclpt.md)) +## Overloadable unary operators -1. `&` ([address-of](../cpp/address-of-operator-amp.md)) +You can overload the following unary operators on user-defined types: -1. `~` ([one's complement](../cpp/one-s-complement-operator-tilde.md)) +- **`!`** ([logical NOT](../cpp/logical-negation-operator-exclpt.md)) -1. `*` ([pointer dereference](../cpp/indirection-operator-star.md)) +- **`&`** ([address-of](../cpp/address-of-operator-amp.md)) -1. `+` ([unary plus](../cpp/additive-operators-plus-and.md)) +- **`~`** ([complement](../cpp/one-s-complement-operator-tilde.md)) -1. `-` ([unary negation](../cpp/additive-operators-plus-and.md)) +- **`*`** ([pointer dereference](../cpp/indirection-operator-star.md)) -1. `++` ([increment](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) +- **`+`** ([unary plus](../cpp/unary-plus-and-negation-operators-plus-and.md)) -1. `--` ([decrement](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) +- **`-`** ([unary negation](../cpp/unary-plus-and-negation-operators-plus-and.md)) -1. conversion operators +- **`++`** ([prefix increment](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) or ([postfix increment](../cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md)) -The postfix increment and decrement operators (`++` and `--`) are treated separately in [Increment and Decrement](../cpp/increment-and-decrement-operator-overloading-cpp.md). +- **`--`** ([prefix decrement](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md)) or ([postfix decrement](../cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md)) -Conversion operators are also discussed in a separate topic; see [User-Defined Type Conversions](../cpp/user-defined-type-conversions-cpp.md). +- [Conversion operators](../cpp/user-defined-type-conversions-cpp.md) -The following rules are true of all other unary operators. To declare a unary operator function as a nonstatic member, you must declare it in the form: +## Unary operator overload declarations -> *ret-type* **`operator`** *op* **()** +You can declare overloaded unary operators either as non-static member functions or as nonmember functions. Overloaded unary member functions take no argument because they implicitly operate on **`this`**. Nonmember functions are declared with one argument. When both forms are declared, the compiler follows the rules for overload resolution to determine which function to use, if any. -where *ret-type* is the return type and *op* is one of the operators listed in the preceding table. +The following rules apply to all prefix unary operators. To declare a unary operator function as a non-static member function, use this declaration form: -To declare a unary operator function as a global function, you must declare it in the form: +> *`return-type`* **`operator`** *`op`* **`();`** -> *ret-type* **`operator`** *op* **(** *arg* **)** +In this form, *`return-type`* is the return type and *`op`* is one of the operators listed in the preceding table. -where *ret-type* and *op* are as described for member operator functions and the *arg* is an argument of class type on which to operate. +To declare a unary operator function as a nonmember function, use this declaration form: + +> *`return-type`* **`operator`** *`op`* **`(`** *`class-type`* **`);`** + +In this form, *`return-type`* is the return type, *`op`* is one of the operators listed in the preceding table, and *`class-type`* is the class type of the argument on which to operate. + +The postfix forms of **`++`** and **`--`** take an extra **`int`** argument to distinguish them from the prefix forms. For more information about the prefix and postfix forms of **`++`** and **`--`**, see [Increment and decrement operator overloading](../cpp/increment-and-decrement-operator-overloading-cpp.md). > [!NOTE] -> There is no restriction on the return types of the unary operators. For example, it makes sense for logical NOT (`!`) to return an integral value, but this is not enforced. +> There's no restriction on the return types of the unary operators. For example, it makes sense for logical NOT (**`!`**) to return a **`bool`** value, but this behavior isn't enforced. ## See also -[Operator Overloading](../cpp/operator-overloading.md) +[Operator overloading](../cpp/operator-overloading.md) diff --git a/docs/cpp/partial-ordering-of-function-templates-cpp.md b/docs/cpp/partial-ordering-of-function-templates-cpp.md index 22b8d8f8f09..5e5607e8435 100644 --- a/docs/cpp/partial-ordering-of-function-templates-cpp.md +++ b/docs/cpp/partial-ordering-of-function-templates-cpp.md @@ -1,25 +1,25 @@ --- -description: "Learn more about: Partial Ordering of Function Templates (C++)" -title: "Partial Ordering of Function Templates (C++)" -ms.date: "07/30/2019" +description: "Learn more about: Partial ordering of function templates (C++)" +title: "Partial ordering of function templates (C++)" +ms.date: 09/27/2022 helpviewer_keywords: ["partial ordering of function templates"] ms.assetid: 0c17347d-0e80-47ad-b5ac-046462d9dc73 --- -# Partial Ordering of Function Templates (C++) +# Partial ordering of function templates (C++) Multiple function templates that match the argument list of a function call can be available. C++ defines a partial ordering of function templates to specify which function should be called. The ordering is partial because there can be some templates that are considered equally specialized. -The compiler chooses the most specialized template function available from the possible matches. For example, if a function template takes a type `T` and another function template that takes `T*` is available, the `T*` version is said to be more specialized. It's preferred over the generic `T` version whenever the argument is a pointer type, even though both would be allowable matches. +The compiler chooses the most specialized function template available from the possible matches. For example, if a function template takes a type `T` and another function template that takes `T*` is available, the `T*` version is said to be more specialized. It's preferred over the generic `T` version whenever the argument is a pointer type, even though both would be allowable matches. Use the following process to determine if one function template candidate is more specialized: -1. Consider two function templates, T1 and T2. +1. Consider two function templates, `T1` and `T2`. -1. Replace the parameters in T1 with a hypothetical unique type X. +1. Replace the parameters in `T1` with a hypothetical unique type `X`. -1. With the parameter list in T1, see if T2 is a valid template for that parameter list. Ignore any implicit conversions. +1. With the parameter list in `T1`, see if `T2` is a valid template for that parameter list. Ignore any implicit conversions. -1. Repeat the same process with T1 and T2 reversed. +1. Repeat the same process with `T1` and `T2` reversed. 1. If one template is a valid template argument list for the other template, but the converse isn't true, then that template is considered to be less specialized than the other template. If by using the previous step, both templates form valid arguments for each other, then they're considered to be equally specialized, and an ambiguous call results when you attempt to use them. @@ -27,11 +27,11 @@ Use the following process to determine if one function template candidate is mor 1. A template specialization for a specific type is more specialized than one taking a generic type argument. - 1. A template taking only `T*` is more specialized than one taking only `T`, because a hypothetical type `X*` is a valid argument for a `T` template argument, but `X` is not a valid argument for a `T*` template argument. + 1. A template taking only `T*` is more specialized than one taking only `T`, because a hypothetical type `X*` is a valid argument for a `T` template argument, but `X` isn't a valid argument for a `T*` template argument. - 1. `const T` is more specialized than `T`, because `const X` is a valid argument for a `T` template argument, but `X` is not a valid argument for a `const T` template argument. + 1. `const T` is more specialized than `T`, because `const X` is a valid argument for a `T` template argument, but `X` isn't a valid argument for a `const T` template argument. - 1. `const T*` is more specialized than `T*`, because `const X*` is a valid argument for a `T*` template argument, but `X*` is not a valid argument for a `const T*` template argument. + 1. `const T*` is more specialized than `T*`, because `const X*` is a valid argument for a `T*` template argument, but `X*` isn't a valid argument for a `const T*` template argument. ## Example @@ -77,4 +77,4 @@ Even more specialized function for const T* ## See also -[Function Templates](../cpp/function-templates.md) +[Function templates](../cpp/function-templates.md) diff --git a/docs/cpp/pimpl-for-compile-time-encapsulation-modern-cpp.md b/docs/cpp/pimpl-for-compile-time-encapsulation-modern-cpp.md index 5aede48b9b8..3865266d997 100644 --- a/docs/cpp/pimpl-for-compile-time-encapsulation-modern-cpp.md +++ b/docs/cpp/pimpl-for-compile-time-encapsulation-modern-cpp.md @@ -2,7 +2,7 @@ description: "Learn more about: Pimpl For Compile-Time Encapsulation (Modern C++)" title: "Pimpl For Compile-Time Encapsulation (Modern C++)" ms.date: "11/04/2016" -ms.topic: "conceptual" +ms.topic: "concept-article" ms.assetid: c3e8a90a-b328-4990-82bb-e1b147f76e07 --- # Pimpl For Compile-Time Encapsulation (Modern C++) diff --git a/docs/cpp/pointers-to-members.md b/docs/cpp/pointers-to-members.md index 17e5da3112e..9512ed71b35 100644 --- a/docs/cpp/pointers-to-members.md +++ b/docs/cpp/pointers-to-members.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Pointers to Members" title: "Pointers to Members" -ms.date: "11/04/2016" +description: "Learn more about: Pointers to Members" +ms.date: 11/04/2016 helpviewer_keywords: ["declarations, pointers", "class members [C++], pointers to", "pointers, to members", "members [C++], pointers to", "pointers, declarations"] -ms.assetid: f42ddb79-9721-4e39-95b1-c56b55591f68 --- # Pointers to Members @@ -121,7 +120,7 @@ The address of a static member isn't a pointer to a member. It's a regular point Invoking a virtual function through a pointer-to-member function works as if the function had been called directly. The correct function is looked up in the v-table and invoked. -The key to virtual functions working, as always, is invoking them through a pointer to a base class. (For more information about virtual functions, see [Virtual Functions](../cpp/virtual-functions.md).) +The key to virtual functions working, as always, is invoking them through a pointer to a base class. For more information about virtual functions, see [Virtual Functions](../cpp/virtual-functions.md). The following code shows how to invoke a virtual function through a pointer-to-member function: diff --git a/docs/cpp/portability-at-abi-boundaries-modern-cpp.md b/docs/cpp/portability-at-abi-boundaries-modern-cpp.md index 28caf182d05..09249b99cd1 100644 --- a/docs/cpp/portability-at-abi-boundaries-modern-cpp.md +++ b/docs/cpp/portability-at-abi-boundaries-modern-cpp.md @@ -2,7 +2,7 @@ title: "Portability at ABI boundaries" description: "Flatten C++ interfaces to C calling conventions at binary interface boundaries." ms.date: "11/19/2019" -ms.topic: "conceptual" +ms.topic: "concept-article" ms.assetid: abbd405e-3038-427c-8c24-e00598f0936a --- # Portability at ABI boundaries diff --git a/docs/cpp/postfix-expressions.md b/docs/cpp/postfix-expressions.md index 9ed1835bcfc..dbb3ab65ddb 100644 --- a/docs/cpp/postfix-expressions.md +++ b/docs/cpp/postfix-expressions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Postfix Expressions" title: "Postfix Expressions" -ms.date: "11/04/2016" +description: "Learn more about: Postfix Expressions" +ms.date: 11/04/2016 helpviewer_keywords: ["operators [C++], postfix", "postfix expressions", "expressions [C++], postfix"] -ms.assetid: 7ac62a57-06df-422f-b012-a75b37d7cb9b --- # Postfix Expressions @@ -72,7 +71,7 @@ When a function is called, the following tasks are performed: Func( Temp_i ); ``` - Note that the initialization is performed as if using the equal-sign syntax instead of the parentheses syntax. A copy of `i` is made prior to passing the value to the function. (For more information, see [Initializers](../cpp/initializers.md) and [Conversions](../cpp/user-defined-type-conversions-cpp.md)). + Note that the initialization is performed as if using the equal-sign syntax instead of the parentheses syntax. A copy of `i` is made prior to passing the value to the function. For more information, see [Initializers](../cpp/initializers.md) and [Conversions](../cpp/user-defined-type-conversions-cpp.md). Therefore, if the function prototype (declaration) calls for an argument of type **`long`**, and if the calling program supplies an actual argument of type **`int`**, the actual argument is promoted using a standard type conversion to type **`long`** (see [Standard Conversions](../cpp/standard-conversions.md)). diff --git a/docs/cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md b/docs/cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md index e594603a521..9113738138e 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 @@ -1,12 +1,11 @@ --- -description: "Learn more about: Postfix Increment and Decrement Operators: ++ and --" title: "Postfix Increment and Decrement Operators: ++ and --" -ms.date: "11/04/2016" +description: "Learn more about: Postfix Increment and Decrement Operators: ++ and --" +ms.date: 11/04/2016 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 @@ -17,13 +16,13 @@ postfix-expression -- ## Remarks -C++ provides prefix and postfix increment and decrement operators; this section describes only the postfix increment and decrement operators. (For more information, see [Prefix Increment and Decrement Operators](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md).) The difference between the two is that in the postfix notation, the operator appears after *postfix-expression*, whereas in the prefix notation, the operator appears before *expression.* The following example shows a postfix-increment operator: +C++ provides prefix and postfix increment and decrement operators; this section describes only the postfix increment and decrement operators. For more information, see [Prefix Increment and Decrement Operators](../cpp/prefix-increment-and-decrement-operators-increment-and-decrement.md). The difference between the two is that in the postfix notation, the operator appears after *postfix-expression*, whereas in the prefix notation, the operator appears before *expression.* The following example shows a postfix-increment operator: ```cpp 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. @@ -43,23 +42,29 @@ The following code illustrates the postfix increment operator: #include using namespace std; -int main() { - int i = 10; - cout << i++ << endl; - cout << i << endl; +int main() +{ + int i = 10; + cout << i++ << endl; + cout << i << endl; } ``` +```Output +10 +11 +``` + Postincrement and postdecrement operations on enumerated types are not supported: ```cpp -enum Compass { North, South, East, West ); +enum Compass { North, South, East, West }; Compass myCompass; -for( myCompass = North; myCompass != West; myCompass++ ) // Error +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 08b245ea218..0ca9c55341a 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 @@ -1,12 +1,11 @@ --- -description: "Learn more about: Prefix Increment and Decrement Operators: ++ and --" title: "Prefix Increment and Decrement Operators: ++ and --" -ms.date: "11/04/2016" +description: "Learn more about: Prefix Increment and Decrement Operators: ++ and --" +ms.date: 11/04/2016 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,13 +16,13 @@ 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`**. -Both the prefix and postfix increment and decrement operators affect their operands. The key difference between them is the order in which the increment or decrement takes place in the evaluation of an expression. (For more information, see [Postfix Increment and Decrement Operators](../cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md).) In the prefix form, the increment or decrement takes place before the value is used in expression evaluation, so the value of the expression is different from the value of the operand. In the postfix form, the increment or decrement takes place after the value is used in expression evaluation, so the value of the expression is the same as the value of the operand. For example, the following program prints "`++i = 6`": +Both the prefix and postfix increment and decrement operators affect their operands. The key difference between them is the order in which the increment or decrement takes place in the evaluation of an expression. For more information, see [Postfix Increment and Decrement Operators](../cpp/postfix-increment-and-decrement-operators-increment-and-decrement.md). In the prefix form, the increment or decrement takes place before the value is used in expression evaluation, so the value of the expression is different from the value of the operand. In the postfix form, the increment or decrement takes place after the value is used in expression evaluation, so the value of the expression is the same as the value of the operand. For example, the following program prints "`++i = 6`": ```cpp // expre_Increment_and_Decrement_Operators.cpp @@ -66,6 +65,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/preserve-none.md b/docs/cpp/preserve-none.md new file mode 100644 index 00000000000..ba7d97cf3b4 --- /dev/null +++ b/docs/cpp/preserve-none.md @@ -0,0 +1,74 @@ +--- +description: "Learn more about: __preserve_none" +title: "__preserve_none" +ms.date: 02/11/2026 +f1_keywords: ["__preserve_none", "register spilling", "non preserving calling convention"] +helpviewer_keywords: ["__preserve_none keyword"] +--- +# __preserve_none + +**Microsoft Specific** + +> [!IMPORTANT] +> The **`__preserve_none`** calling convention is experimental and subject to change. + +The **`__preserve_none`** calling convention specifies that arguments to functions are to be passed in registers, with most general-purpose registers treated as volatile. This calling convention is only supported for C programs and only applies to x64 code. + +This calling convention is designed to minimize register spilling and improve performance. + +The following list shows the behavior of this calling convention. + +| Element | Behavior | +|---------|----------------| +| Argument-passing order | Arguments are passed in up to 10 registers in the following order: `r13`, `r14`, `r15`, `rbx`, `rsi`, `rdi`, `r9`, `r8`, `rdx`, `rcx`. If a hidden parameter is required for struct returns, it's passed in `r13` (the first parameter register), reducing available parameter registers to 9. Registers `r10`-`r12` are reserved for various CRT and Windows runtimes. All parameters must be passed through registers; stack-based parameters aren't currently supported. | +| Register allocation strategy | To help minimize register spilling when calling functions with different calling conventions, the allocator assigns `rcx`, `rdx`, `r8`, and `r9` only after other registers have been used, since those registers are used first by the [__vectorcall](vectorcall.md) and [__cdecl](cdecl.md) calling conventions. | +| Argument limit | Functions are restricted to a maximum of 10 parameters. An error is generated if this limit is exceeded. | +| Return value convention | Follows the regular x64 calling convention rules. Scalar return values are returned in `rax`. Structs of size 1, 2, 4, or 8 bytes are returned through the `rax` register. For structs of other sizes, a pointer to memory allocated by the caller and passed through the hidden parameter is returned in `rax`. | +| Volatile registers | All general-purpose registers except `r12`, `rsp` (stack pointer) and `rbp` (base pointer) are treated as volatile and don't need to be preserved across function calls. While `r10` and `r11` are volatile, they aren't used for parameter passing to maintain compatibility with existing programs. | +| Nonvolatile registers | Only `rsp`, `rbp`, and `r12` are nonvolatile. | +| Stack alignment | The stack must maintain 16-byte alignment. | +| Frame pointer | The `rbp` register and frame chain follow the [/Gy switch](../build/reference/gy-enable-function-level-linking.md) settings. | +| Stack-maintenance responsibility | The callee is responsible for cleaning up its own stack space. | +| Shadow space | 32 bytes are reserved on the stack as a shadow space to maintain compatibility with profilers and debugging tools. *(Shadow space is a reserved area on the stack where register parameters can be spilled if needed. It's typically 32 bytes (4 registers × 8 bytes each) that the caller reserves for the first four register parameters.)* | +| Floating-point support | Floating-point parameters aren't supported. | +| Name-decoration convention | Function names are decorated with @@_A suffix. | +| Case-translation convention | No case translation performed. | + +## Restrictions and Limitations + +The **`__preserve_none`** calling convention has the following restrictions: + +- **C only**: Only supported for C programs. +- **x64 only**: Only supported on x64. +- **No floating-point**: Floating-point parameters aren't supported. +- **No variadic functions**: Variadic functions (varargs) aren't supported. +- **Parameter limit**: Maximum of 10 parameters, all passed through registers. + +## Use Cases + +The **`__preserve_none`** calling convention is designed for performance-critical scenarios where: + +- Most functions in the codebase use the **`__preserve_none`** calling convention +- Used with `msvc::musttail` to tail call between functions with no stack usage +- Minimizing register spilling is important for performance +- The codebase is compatible with treating most registers as volatile + +## Example + +In the following example, the function `ProcessData` uses the **`__preserve_none`** calling convention: + +```c +// Example of the __preserve_none keyword +void __preserve_none ProcessData(int a, int b, int c, int d, int e); + +// Example of the __preserve_none keyword on function pointer +typedef int (__preserve_none *callback_ptr)(void* context, int value, int flags); +``` + +**END Microsoft Specific** + +## See also + +[Argument Passing and Naming Conventions](argument-passing-and-naming-conventions.md)\ +[x64 Calling Convention](../build/x64-calling-convention.md)\ +[Keywords](keywords-cpp.md) diff --git a/docs/cpp/primary-expressions.md b/docs/cpp/primary-expressions.md index 11f926e8a0f..8722190e3e4 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 85a25f80160..720e33de0fc 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/program-termination.md b/docs/cpp/program-termination.md index b582c5c91f9..1ce131eed8a 100644 --- a/docs/cpp/program-termination.md +++ b/docs/cpp/program-termination.md @@ -1,7 +1,7 @@ --- title: "C++ program termination" description: "Learn about the standard ways to exit a C++-language program." -ms.date: 12/07/2020 +ms.date: 07/07/2022 helpviewer_keywords: ["terminating execution", "quitting applications", "exiting applications", "programs [C++], terminating"] --- # C++ program termination @@ -16,11 +16,11 @@ In C++, you can exit a program in these ways: The [`exit`](../c-runtime-library/reference/exit-exit-exit.md) function, declared in \, terminates a C++ program. The value supplied as an argument to `exit` is returned to the operating system as the program's return code or exit code. By convention, a return code of zero means that the program completed successfully. You can use the constants `EXIT_FAILURE` and `EXIT_SUCCESS`, also defined in \, to indicate success or failure of your program. -Issuing a **`return`** statement from the `main` function is equivalent to calling the `exit` function with the return value as its argument. - ## `abort` function -The [`abort`](../c-runtime-library/reference/abort.md) function, also declared in the standard include file \, terminates a C++ program. The difference between `exit` and `abort` is that `exit` allows the C++ run-time termination processing to take place (global object destructors get called), but `abort` terminates the program immediately. The `abort` function bypasses the normal destruction process for initialized global static objects. It also bypasses any special processing that was specified using the [`atexit`](../c-runtime-library/reference/atexit.md) function. +The [`abort`](../c-runtime-library/reference/abort.md) function, also declared in the standard include file \, terminates a C++ program. The difference between `exit` and `abort` is that `exit` allows the C++ runtime termination processing to take place (global object destructors get called). `abort` terminates the program immediately. The `abort` function bypasses the normal destruction process for initialized global static objects. It also bypasses any special processing that was specified using the [`atexit`](../c-runtime-library/reference/atexit.md) function. + +**Microsoft-specific**: For Windows compatibility reasons, the Microsoft implementation of `abort` may allow DLL termination code to run in certain circumstances. For more information, see [`abort`](../c-runtime-library/reference/abort.md). ## `atexit` function @@ -28,23 +28,32 @@ Use the [`atexit`](../c-runtime-library/reference/atexit.md) function to specify ## `return` statement in `main` -Issuing a [`return`](return-statement-cpp.md) statement from `main` is functionally equivalent to calling the `exit` function. Consider the following example: +The **`return`** statement allows you to specify a return value from `main`. A [`return`](return-statement-cpp.md) statement in `main` first acts like any other `return` statement. Any automatic variables are destroyed. Then, `main` invokes `exit` with the return value as a parameter. Consider the following example: ```cpp // return_statement.cpp #include +struct S +{ + int value; +}; int main() { + S s{ 3 }; + exit( 3 ); + // or return 3; } ``` -The `exit` and **`return`** statements in the preceding example are functionally identical. Normally, C++ requires that functions that have return types other than **`void`** return a value. The `main` function is an exception; it can end without a **`return`** statement. In that case, it returns an implementation-specific value to the invoking process. The **`return`** statement allows you to specify a return value from `main`. +The `exit` and **`return`** statements in the preceding example have similar behavior. Both terminate the program and return a value of 3 to the operating system. The difference is that `exit` doesn't destroy the automatic variable `s`, while the `return` statement does. + +Normally, C++ requires that functions that have return types other than **`void`** return a value. The `main` function is an exception; it can end without a **`return`** statement. In that case, it returns an implementation-specific value to the invoking process. (By default, MSVC returns 0.) -## Destruction of static objects +## Destruction of thread and static objects -When you call `exit` or execute a **`return`** statement from `main`, static objects are destroyed in the reverse order of their initialization (after the call to `atexit` if one exists). The following example shows how such initialization and cleanup works. +When you call `exit` directly (or when it's called after a **`return`** statement from `main`), thread objects associated with the current thread are destroyed. Next, static objects are destroyed in the reverse order of their initialization (after calls to functions specified to `atexit`, if any). The following example shows how such initialization and cleanup works. ### Example @@ -86,7 +95,7 @@ int main() { } ``` -Another way to write this code is to declare the `ShowData` objects with block scope, allowing them to be destroyed when they go out of scope: +Another way to write this code is to declare the `ShowData` objects with block scope, which implicitly destroys them when they go out of scope: ```cpp int main() { diff --git a/docs/cpp/protected-cpp.md b/docs/cpp/protected-cpp.md index 8d4ec89e285..515f71fb84d 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/ptr32-ptr64.md b/docs/cpp/ptr32-ptr64.md index 08fc2cedc23..a41c67307da 100644 --- a/docs/cpp/ptr32-ptr64.md +++ b/docs/cpp/ptr32-ptr64.md @@ -1,16 +1,17 @@ --- description: "Learn more about: __ptr32, __ptr64" title: "__ptr32, __ptr64" -ms.date: "10/09/2018" +ms.date: 12/16/2025 f1_keywords: ["__ptr32_cpp", "__ptr64_cpp", "__ptr32", "__ptr64", "_ptr32", "_ptr64"] helpviewer_keywords: ["__ptr64 keyword [C++]", "_ptr32 keyword [C++]", "ptr32 keyword [C++]", "ptr64 keyword [C++]", "_ptr64 keyword [C++]", "__ptr32 keyword [C++]"] -ms.assetid: afb563d8-7458-4fe7-9c30-bd4b5385a59f --- # __ptr32, __ptr64 -**Microsoft Specific** +**Microsoft specific** -**`__ptr32`** represents a native pointer on a 32-bit system, while **`__ptr64`** represents a native pointer on a 64-bit system. +Use **`__ptr32`** to represent a native pointer on a 32-bit system. Use **`__ptr64`** to represent a native pointer on a 64-bit system. + +The `__ptr32` and `__ptr64` modifiers are Microsoft-specific extensions for interop scenarios. For standard 32-bit (x86) or standard x64 code, use native pointers, instead. The following example shows how to declare each of these pointer types: @@ -19,17 +20,22 @@ int * __ptr32 p32; int * __ptr64 p64; ``` -On a 32-bit system, a pointer declared with **`__ptr64`** is truncated to a 32-bit pointer. On a 64-bit system, a pointer declared with **`__ptr32`** is coerced to a 64-bit pointer. +On a 32-bit system, a pointer declared with **`__ptr64`** is treated as a 32-bit pointer and truncates the upper 32 bits of any 64-bit address assigned to it. On a 64-bit system, a pointer declared with **`__ptr32`** is treated as a 32-bit pointer and truncates the upper 32 bits of any 64-bit address assigned to it. This truncation can lead to an invalid pointer if the 64-bit address is above 4GB. > [!NOTE] -> You cannot use **`__ptr32`** or **`__ptr64`** when compiling with **/clr:pure**. Otherwise, Compiler Error C2472 will be generated. The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. +> You can't use **`__ptr32`** or **`__ptr64`** when compiling with **`/clr:pure`**. Otherwise, the compiler generates error C2472. The **/clr:pure** and **/clr:safe** compiler options are deprecated in Microsoft Visual Studio 2015 and unsupported in Microsoft Visual Studio 2017. -For compatibility with previous versions, **_ptr32** and **_ptr64** are synonyms for **`__ptr32`** and **`__ptr64`** unless compiler option [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. +For compatibility with previous versions, **`_ptr32`** and **`_ptr64`** are synonyms for **`__ptr32`** and **`__ptr64`** unless you specify compiler option [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md). ## Example The following example shows how to declare and allocate pointers with the **`__ptr32`** and **`__ptr64`** keywords. +This code works on x86 but might crash on x64. + +- It works when compiled for 32-bit because **`__ptr64`** pointers are treated as 32-bit pointers on x86. On x86 (32-bit), `malloc` returns a 32-bit address which fits in `p64`. +- It might crash when compiled for 64-bit because on x64, `malloc` returns a 64-bit pointer which is truncated to 32 bits by this line: `p32 = (int* __ptr32)malloc(4);`. Truncating a 64-bit address to a 32-bit address could result in an invalid pointer if the allocation happened above 4GB. In that case, `*p32 = 32` could attempt to access a truncated address that isn't part of your process's address space, causing an access violation. Even if it works once, it could fail later if the memory allocator returns a higher address. + ```cpp #include #include @@ -38,22 +44,22 @@ int main() { using namespace std; - int * __ptr32 p32; - int * __ptr64 p64; + int* __ptr32 p32; + int* __ptr64 p64; - p32 = (int * __ptr32)malloc(4); - *p32 = 32; + p64 = (int* __ptr64)malloc(4); + *p64 = 64; // Works on x86 and x64 + cout << *p64 << endl; + + p32 = (int* __ptr32)malloc(4); + *p32 = 32; // Works on x86. Possible exception on x64 cout << *p32 << endl; - - p64 = (int * __ptr64)malloc(4); - *p64 = 64; - cout << *p64 << endl; } ``` ```Output -32 64 +32 ``` **END Microsoft Specific** diff --git a/docs/cpp/raw-pointers.md b/docs/cpp/raw-pointers.md index 2e8bcaf0921..3c4d07c50e6 100644 --- a/docs/cpp/raw-pointers.md +++ b/docs/cpp/raw-pointers.md @@ -19,7 +19,7 @@ A pointer can also be *dereferenced* to retrieve the value of the object that it int j = *p; // dereference p to retrieve the value at its address ``` -A pointer can point to a typed object or to **`void`**. When a program allocates an object on the [heap](https://wikipedia.org/wiki/Heap) in memory, it receives the address of that object in the form of a pointer. Such pointers are called *owning pointers*. An owning pointer (or a copy of it) must be used to explicitly free the heap-allocated object when it's no longer needed. Failure to free the memory results in a *memory leak*, and renders that memory location unavailable to any other program on the machine. Memory allocated using **`new`** must be freed by using **`delete`** (or **`delete[]`**). For more information, see [`new` and `delete` operators](new-and-delete-operators.md). +A pointer can point to a typed object or to **`void`**. When a program allocates an object on the [heap](https://wikipedia.org/wiki/Heap) in memory, it receives the address of that object in the form of a pointer. Such pointers are called *owning pointers*. An owning pointer (or a copy of it) must be used to explicitly free the heap-allocated object when it's no longer needed. Failure to free the memory results in a *memory leak*, and renders that memory location unavailable to any other program on the machine. Memory allocated with **`new`** must be freed using **`delete`**, and memory allocated with **`new[]`** must be freed using **`delete[]`**. For more information, see [`new` and `delete` operators](new-and-delete-operators.md). ```cpp MyClass* mc = new MyClass(); // allocate object on the heap @@ -78,10 +78,9 @@ void func_B(MyClass mc) // This statement modifies only the local copy of mc. mc.num = 21; std::cout << "Local copy of mc:"; - mc.print(); // "Erika, 21" + mc.print(); // "Erika:21" } - int main() { // Use the * operator to declare a pointer type @@ -100,28 +99,28 @@ int main() MyClass* pcopy = &mc; // Use the -> operator to access the object's public members - pmc->print(); // "Nick, 108" + pmc->print(); // "Nick:108" // Copy the pointer. Now pmc and pmc2 point to same object! MyClass* pmc2 = pmc; // Use copied pointer to modify the original object pmc2->name = "Erika"; - pmc->print(); // "Erika, 108" - pmc2->print(); // "Erika, 108" + pmc->print(); // "Erika:108" + pmc2->print(); // "Erika:108" // Pass the pointer to a function. func_A(pmc); - pmc->print(); // "Erika, 3" - pmc2->print(); // "Erika, 3" + pmc->print(); // "Erika:3" + pmc2->print(); // "Erika:3" // Dereference the pointer and pass a copy // of the pointed-to object to a function func_B(*pmc); - pmc->print(); // "Erika, 3" (original not modified by function) + pmc->print(); // "Erika:3" (original not modified by function) - delete(pmc); // don't forget to give memory back to operating system! - // delete(pmc2); //crash! memory location was already deleted + delete pmc; // don't forget to give memory back to operating system! + // delete pmc2; //crash! memory location was already deleted } ``` @@ -150,7 +149,6 @@ void func(int arr[], int length) int main() { - int i[5]{ 1,2,3,4,5 }; // sizeof(i) = total bytes int j = sizeof(i) / sizeof(i[0]); @@ -158,7 +156,11 @@ int main() } ``` -Certain arithmetic operations can be used on non-`const` pointers to make them point to another memory location. Pointers are incremented and decremented using the **`++`**, **`+=`**, **`-=`** and **`--`** operators. This technique can be used in arrays and is especially useful in buffers of untyped data. A `void*` gets incremented by the size of a **`char`** (1 byte). A typed pointer gets incremented by size of the type it points to. +```Output +1 2 3 4 5 +``` + +Certain arithmetic operations can be used on non-`const` pointers to make them point to another memory location. Pointers are incremented and decremented using the **`++`**, **`+=`**, **`-=`** and **`--`** operators. This technique can be used in arrays and is especially useful in buffers of untyped data. A typed pointer gets incremented by size of the type it points to. The following example demonstrates how pointer arithmetic can be used to access individual pixels in a bitmap on Windows. Note the use of **`new`** and **`delete`**, and the dereference operator. @@ -170,7 +172,6 @@ using namespace std; int main() { - BITMAPINFOHEADER header; header.biHeight = 100; // Multiple of 4 for simplicity. header.biWidth = 100; @@ -232,7 +233,6 @@ A pointer to **`void`** simply points to a raw memory location. Sometimes it's n When a typed pointer is cast to a `void` pointer, the contents of the memory location are unchanged. However, the type information is lost, so that you can't do increment or decrement operations. A memory location can be cast, for example, from `MyClass*` to `void*` and back again to `MyClass*`. Such operations are inherently error-prone and require great care to avoid errors. Modern C++ discourages the use of `void` pointers in almost all circumstances. ```cpp - //func.c void func(void* data, int length) { @@ -268,7 +268,7 @@ int main() void* p = static_cast(mc); MyClass* mc2 = static_cast(p); std::cout << mc2->name << std::endl; // "Marian" - delete(mc); + delete mc; // use operator new to allocate untyped memory block void* pvoid = operator new(1000); @@ -336,9 +336,14 @@ int main() } ``` +```Output +hello world from MSVC +Good morning and hello world from MSVC +``` + ## See also -[Smart pointers](smart-pointers-modern-cpp.md) -[Indirection Operator: *](indirection-operator-star.md)
-[Address-of Operator: &](address-of-operator-amp.md)
+[Smart pointers](smart-pointers-modern-cpp.md)\ +[Indirection Operator: *](indirection-operator-star.md)\ +[Address-of Operator: &](address-of-operator-amp.md)\ [Welcome back to C++](welcome-back-to-cpp-modern-cpp.md) diff --git a/docs/cpp/reference-type-function-returns.md b/docs/cpp/reference-type-function-returns.md index cdf3ea30b00..077a0218377 100644 --- a/docs/cpp/reference-type-function-returns.md +++ b/docs/cpp/reference-type-function-returns.md @@ -91,7 +91,7 @@ Declarations of reference types must contain initializers except in the followin If you declare an object at local scope, that object will be destroyed when the function returns. If the function returns a reference to that object, that reference will probably cause an access violation at runtime if the caller attempts to use the null reference. ```cpp -// C4172 means Don’t do this!!! +// C4172 means Don't do this!!! Foo& GetFoo() { Foo f; diff --git a/docs/cpp/references-cpp.md b/docs/cpp/references-cpp.md index fc609d9e3b0..456e543da05 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 06221f50012..72b747923c8 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/restrict-cpp-amp.md b/docs/cpp/restrict-cpp-amp.md index 5255fa72ffd..97dcc8e1286 100644 --- a/docs/cpp/restrict-cpp-amp.md +++ b/docs/cpp/restrict-cpp-amp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: restrict (C++ AMP)" title: "restrict (C++ AMP)" -ms.date: "11/04/2016" +description: "Learn more about: restrict (C++ AMP)" +ms.date: 11/04/2016 f1_keywords: ["cpu_CPP", "amp_CPP"] helpviewer_keywords: ["restrict clause (C++ AMP)"] -ms.assetid: 07d3291f-7edf-456b-8828-283ac8673661 --- # restrict (C++ AMP) @@ -19,7 +18,7 @@ The **`restrict`** clause takes the following forms: |------------|-----------------| |`restrict(cpu)`|The function can use the full C++ language. Only other functions that are declared by using restrict(cpu) functions can call the function.| |`restrict(amp)`|The function can only use the subset of the C++ language that C++ AMP can accelerate.| -|A sequence of `restrict(cpu)` and `restrict(amp)`.|The function must adhere to the limitations of both `restrict(cpu)` and `restrict(amp)`. The function can be called by functions that are declared by using `restrict(cpu)`, `restrict(amp)`, `restrict(cpu, amp)`, or `restrict(amp, cpu)`.

The form `restrict(A) restrict(B)` can be written as `restrict(A,B)`.| +|A sequence of `restrict(cpu)` and `restrict(amp)`.|The function must adhere to the limitations of both `restrict(cpu)` and `restrict(amp)`. The function can be called by functions that are declared by using `restrict(cpu)`, `restrict(amp)`, `restrict(cpu, amp)`, or `restrict(amp, cpu)`.

The form `restrict(A) restrict(B)` can be written as `restrict(A,B)`.| ## Remarks diff --git a/docs/cpp/results-of-calling-example.md b/docs/cpp/results-of-calling-example.md index d4b2e023575..7684793aa79 100644 --- a/docs/cpp/results-of-calling-example.md +++ b/docs/cpp/results-of-calling-example.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Results of Calling Example" title: "Results of Calling Example" -ms.date: "11/19/2018" +description: "Learn more about: Results of Calling Example" +ms.date: 11/19/2018 helpviewer_keywords: ["examples [C++], results of calling", "results, thiscall call", "results, __fastcall keyword call", "results, __cdecl call", "results, __stdcall call"] -ms.assetid: aa70a7cb-ba1d-4aa6-bd0a-ba783da2e642 --- # Results of Calling Example @@ -20,7 +19,7 @@ The **`__cdecl`** calling convention The C decorated name (**`__stdcall`**) is `_MyFunc@20`. The C++ decorated name is implementation-specific. -![Diagram showing the stack and registers for the S T D call and this call calling conventions.](../cpp/media/vc37i02.gif )
+![Diagram showing the stack and registers for the S T D call and this call calling conventions.](../cpp/media/vc37i02.gif)
The __stdcall and thiscall calling conventions ## `__fastcall` diff --git a/docs/cpp/rvalue-reference-declarator-amp-amp.md b/docs/cpp/rvalue-reference-declarator-amp-amp.md index aa24139baf8..441521e11c2 100644 --- a/docs/cpp/rvalue-reference-declarator-amp-amp.md +++ b/docs/cpp/rvalue-reference-declarator-amp-amp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Rvalue reference declarator: &&" title: "Rvalue reference declarator: &&" -ms.date: "11/04/2016" +description: "Learn more about: Rvalue reference declarator: &&" +ms.date: 09/27/2022 f1_keywords: ["&&"] helpviewer_keywords: ["&& rvalue reference declarator"] -ms.assetid: eab0ce3a-c5a3-4992-aa70-6a8ab1f7491d --- # Rvalue reference declarator: `&&` @@ -21,7 +20,7 @@ Rvalue references enable you to distinguish an lvalue from an rvalue. Lvalue ref The following sections describe how rvalue references support the implementation of *move semantics* and *perfect forwarding*. -## Move Semantics +## Move semantics Rvalue references support the implementation of *move semantics*, which can significantly increase the performance of your applications. Move semantics enables you to write code that transfers resources (such as dynamically allocated memory) from one object to another. Move semantics works because it enables transfer of resources from temporary objects: ones that can't be referenced elsewhere in the program. @@ -43,17 +42,17 @@ int main() } ``` -Before Visual Studio 2010, each call to **`operator+`** allocates and returns a new temporary `string` object (an rvalue). **`operator+`** can't append one string to the other because it doesn't know whether the source strings are lvalues or rvalues. If the source strings are both lvalues, they might be referenced elsewhere in the program and so must not be modified. By using rvalue references, **`operator+`** can be modified to take rvalues, which can't be referenced elsewhere in the program. With this change, **`operator+`** can now append one string to another. The change significantly reduces the number of dynamic memory allocations that the `string` class must make. For more information about the `string` class, see [basic_string Class](../standard-library/basic-string-class.md). +Before Visual Studio 2010, each call to **`operator+`** allocates and returns a new temporary `string` object (an rvalue). **`operator+`** can't append one string to the other because it doesn't know whether the source strings are lvalues or rvalues. If the source strings are both lvalues, they might be referenced elsewhere in the program, and so must not be modified. You can modify **`operator+`** to take rvalues by using rvalue references, which can't be referenced elsewhere in the program. With this change, **`operator+`** can now append one string to another. The change significantly reduces the number of dynamic memory allocations that the `string` class must make. For more information about the `string` class, see [`basic_string` Class](../standard-library/basic-string-class.md). Move semantics also helps when the compiler can't use Return Value Optimization (RVO) or Named Return Value Optimization (NRVO). In these cases, the compiler calls the move constructor if the type defines it. -To better understand move semantics, consider the example of inserting an element into a `vector` object. If the capacity of the `vector` object is exceeded, the `vector` object must reallocate memory for its elements and then copy each element to another memory location to make room for the inserted element. When an insertion operation copies an element, it first creates a new element. Then it calls the copy constructor to copy the data from the previous element to the new element. Finally, it destroys the previous element. Move semantics enables you to move objects directly without having to make expensive memory allocation and copy operations. +To better understand move semantics, consider the example of inserting an element into a `vector` object. If the capacity of the `vector` object is exceeded, the `vector` object must reallocate enough memory for its elements, and then copy each element to another memory location to make room for the inserted element. When an insertion operation copies an element, it first creates a new element. Then it calls the copy constructor to copy the data from the previous element to the new element. Finally, it destroys the previous element. Move semantics enables you to move objects directly without having to make expensive memory allocation and copy operations. To take advantage of move semantics in the `vector` example, you can write a move constructor to move data from one object to another. For more information about the introduction of move semantics into the C++ Standard Library in Visual Studio 2010, see [C++ Standard Library](../standard-library/cpp-standard-library-reference.md). -## Perfect Forwarding +## Perfect forwarding Perfect forwarding reduces the need for overloaded functions and helps avoid the forwarding problem. The *forwarding problem* can occur when you write a generic function that takes references as its parameters. If it passes (or *forwards*) these parameters to another function, for example, if it takes a parameter of type `const T&`, then the called function can't modify the value of that parameter. If the generic function takes a parameter of type `T&`, then the function can't be called by using an rvalue (such as a temporary object or integer literal). @@ -100,7 +99,7 @@ int a = 4, b = 5; W* pw = factory(a, b); ``` -However, the following example doesn't contain a valid call to the `factory` function. That's because `factory` takes lvalue references that are modifiable as its parameters, but it's called by using rvalues: +However, the following example doesn't contain a valid call to the `factory` function. It's because `factory` takes lvalue references that are modifiable as its parameters, but it's called by using rvalues: ```cpp Z* pz = factory(2, 2); @@ -116,7 +115,7 @@ T* factory(A1&& a1, A2&& a2) } ``` -This example uses rvalue references as the parameters to the `factory` function. The purpose of the [std::forward](../standard-library/utility-functions.md#forward) function is to forward the parameters of the factory function to the constructor of the template class. +This example uses rvalue references as the parameters to the `factory` function. The purpose of the [`std::forward`](../standard-library/utility-functions.md#forward) function is to forward the parameters of the factory function to the constructor of the template class. The following example shows the `main` function that uses the revised `factory` function to create instances of the `W`, `X`, `Y`, and `Z` classes. The revised `factory` function forwards its parameters (either lvalues or rvalues) to the appropriate class constructor. @@ -136,7 +135,7 @@ int main() } ``` -## Properties of Rvalue References +## Properties of rvalue references **You can overload a function to take an lvalue reference and an rvalue reference.** @@ -183,7 +182,7 @@ In this example, the first call to `f` passes a local variable (an lvalue) as it **The compiler treats a named rvalue reference as an lvalue and an unnamed rvalue reference as an rvalue.** -Functions that take an rvalue reference as a parameter treat the parameter as an lvalue in the body of the function. The compiler treats a named rvalue reference as an lvalue. That's because a named object can be referenced by several parts of a program. It's dangerous to allow multiple parts of a program to modify or remove resources from that object. For example, if multiple parts of a program try to transfer resources from the same object, only the first transfer succeeds. +Functions that take an rvalue reference as a parameter treat the parameter as an lvalue in the body of the function. The compiler treats a named rvalue reference as an lvalue. It's because a named object can be referenced by several parts of a program. It's dangerous to allow multiple parts of a program to modify or remove resources from that object. For example, if multiple parts of a program try to transfer resources from the same object, only the first transfer succeeds. The following example shows the function `g`, which is overloaded to take an lvalue reference and an rvalue reference. The function `f` takes an rvalue reference as its parameter (a named rvalue reference) and returns an rvalue reference (an unnamed rvalue reference). In the call to `g` from `f`, overload resolution selects the version of `g` that takes an lvalue reference because the body of `f` treats its parameter as an lvalue. In the call to `g` from `main`, overload resolution selects the version of `g` that takes an rvalue reference because `f` returns an rvalue reference. @@ -223,7 +222,7 @@ int main() This example produces the following output: -```cpp +```Output In g(const MemoryBlock&). In g(MemoryBlock&&). ``` @@ -266,7 +265,7 @@ int main() This example produces the following output: -```cpp +```Output In g(const MemoryBlock&). In g(MemoryBlock&&). ``` @@ -275,7 +274,7 @@ In g(MemoryBlock&&). A function template that passes (or *forwards*) its parameters to another function is a common pattern. It's important to understand how template type deduction works for function templates that take rvalue references. -If the function argument is an rvalue, the compiler deduces the argument to be an rvalue reference. For example, assume you pass an rvalue reference to an object of type `X` to a template function that takes type `T&&` as its parameter. Template argument deduction deduces `T` to be `X`, so the parameter has type `X&&`. If the function argument is an lvalue or **`const`** lvalue, the compiler deduces its type to be an lvalue reference or **`const`** lvalue reference of that type. +If the function argument is an rvalue, the compiler deduces the argument to be an rvalue reference. For example, assume you pass an rvalue reference to an object of type `X` to a function template that takes type `T&&` as its parameter. Template argument deduction deduces `T` to be `X`, so the parameter has type `X&&`. If the function argument is an lvalue or **`const`** lvalue, the compiler deduces its type to be an lvalue reference or **`const`** lvalue reference of that type. The following example declares one structure template and then specializes it for various reference types. The `print_type_and_value` function takes an rvalue reference as its parameter and forwards it to the appropriate specialized version of the `S::print` method. The `main` function demonstrates the various ways to call the `S::print` method. @@ -360,7 +359,7 @@ int main() This example produces the following output: -```cpp +```Output print: first print: second print: third @@ -390,7 +389,7 @@ The following table summarizes the reference collapsing rules for template argum | `T&& &` | `T&` | | `T&& &&` | `T&&` | -Template argument deduction is an important element of implementing perfect forwarding. The [Perfect Forwarding](#perfect-forwarding) section describes perfect forwarding in more detail. +Template argument deduction is an important element of implementing perfect forwarding. The [Perfect forwarding](#perfect-forwarding) section describes perfect forwarding in more detail. ## Summary diff --git a/docs/cpp/safebuffers.md b/docs/cpp/safebuffers.md index 5d581c08ee5..c813aa53e2b 100644 --- a/docs/cpp/safebuffers.md +++ b/docs/cpp/safebuffers.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: safebuffers" title: "safebuffers" -ms.date: "11/04/2016" +description: "Learn more about: safebuffers" +ms.date: 11/04/2016 f1_keywords: ["safebuffers_cpp"] helpviewer_keywords: ["__declspec keyword (C++), safebuffers", "safebuffers __declspec keyword"] -ms.assetid: 0b0dce14-4523-44d2-8070-5dd0fdabc618 --- # safebuffers @@ -50,7 +49,7 @@ static int checkBuffers() { BUFFER cb; // Use the buffer... return 0; -}; +} static __declspec(safebuffers) int noCheckBuffers() { BUFFER ncb; diff --git a/docs/cpp/scope-resolution-operator.md b/docs/cpp/scope-resolution-operator.md index 5ed0813b267..02a1ee72fa0 100644 --- a/docs/cpp/scope-resolution-operator.md +++ b/docs/cpp/scope-resolution-operator.md @@ -81,7 +81,7 @@ int main() { } ``` -You can use the scope resolution operator to identify a member of a **`namespace`**, or to identify a namespace that nominates the member’s namespace in a **`using`** directive. In the example below, you can use `NamespaceC` to qualify `ClassB`, even though `ClassB` was declared in namespace `NamespaceB`, because `NamespaceB` was nominated in `NamespaceC` by a **`using`** directive. +You can use the scope resolution operator to identify a member of a **`namespace`**, or to identify a namespace that nominates the member's namespace in a **`using`** directive. In the example below, you can use `NamespaceC` to qualify `ClassB`, even though `ClassB` was declared in namespace `NamespaceB`, because `NamespaceB` was nominated in `NamespaceC` by a **`using`** directive. ```cpp namespace NamespaceB { @@ -168,5 +168,5 @@ int main() { ## See also -[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)
+[C++ built-in operators, precedence, and associativity](../cpp/cpp-built-in-operators-precedence-and-associativity.md)\ [Namespaces](../cpp/namespaces-cpp.md) diff --git a/docs/cpp/scope-visual-cpp.md b/docs/cpp/scope-visual-cpp.md index 6a735944423..3e160bde303 100644 --- a/docs/cpp/scope-visual-cpp.md +++ b/docs/cpp/scope-visual-cpp.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Scope (C++)" title: "Scope (C++)" -ms.date: "11/19/2018" +description: "Learn more about: Scope (C++)" +ms.date: 11/19/2018 helpviewer_keywords: ["classes [C++], scope", "scope [C++]", "function prototypes [C++], scope", "class scope", "prototype scope", "functions [C++], scope", "scope, C++ names"] -ms.assetid: 81fecbb0-338b-4325-8332-49f33e716352 --- # Scope (C++) @@ -34,7 +33,7 @@ Block scope and name hiding The output from the program shown in the figure is: -```cpp +```Output i = 0 i = 7 j = 9 diff --git a/docs/cpp/selectany.md b/docs/cpp/selectany.md index 4369cd35eb0..73b773a2a0e 100644 --- a/docs/cpp/selectany.md +++ b/docs/cpp/selectany.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: `selectany`" title: "selectany" -ms.date: "11/04/2016" +description: "Learn more about: `selectany`" +ms.date: 11/04/2016 f1_keywords: ["selectany_cpp"] helpviewer_keywords: ["__declspec keyword [C++], selectany", "selectany __declspec keyword"] -ms.assetid: 9c353017-5a42-4f50-b741-bd13da1ce84d --- # `selectany` @@ -56,7 +55,7 @@ extern __declspec(selectany) int x5; // OK: dynamic initialization of global object class X { public: -X(int i){i++;}; +X(int i){i++;} int i; }; diff --git a/docs/cpp/single-inheritance.md b/docs/cpp/single-inheritance.md index 74c79169b4c..ccba5fd02c1 100644 --- a/docs/cpp/single-inheritance.md +++ b/docs/cpp/single-inheritance.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Single Inheritance" title: "Single Inheritance" -ms.date: "11/19/2018" +description: "Learn more about: Single Inheritance" +ms.date: 11/19/2018 helpviewer_keywords: ["single inheritance", "base classes [C++], indirect", "scope, scope resolution operator", "operators [C++], scope resolution", "scope resolution operator", "derived classes [C++], single base class", "inheritance, single"] -ms.assetid: 1cb946ed-8b1b-4cf1-bde0-d9cecbfdc622 --- # Single Inheritance @@ -74,7 +73,7 @@ Book::Book( char *name, long pagecount ) { Name = new char[ strlen( name ) + 1 ]; strcpy_s( Name, strlen(Name), name ); PageCount = pagecount; -}; +} ``` Note that the constructor for `Book`, (`Book::Book`), has access to the data member, `Name`. In a program, an object of type `Book` can be created and used as follows: diff --git a/docs/cpp/sizeof-operator.md b/docs/cpp/sizeof-operator.md index d7eb3a70299..ae040a3a9b7 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/smart-pointers-modern-cpp.md b/docs/cpp/smart-pointers-modern-cpp.md index 40af79d21d5..2551bba44a0 100644 --- a/docs/cpp/smart-pointers-modern-cpp.md +++ b/docs/cpp/smart-pointers-modern-cpp.md @@ -2,7 +2,7 @@ description: "Learn more about: Smart pointers (Modern C++)" title: "Smart pointers (Modern C++)" ms.date: "11/19/2019" -ms.topic: "conceptual" +ms.topic: "concept-article" ms.assetid: 909ef870-904c-49b6-b8cd-e9d0b7dc9435 --- # Smart pointers (Modern C++) diff --git a/docs/cpp/standard-conversions.md b/docs/cpp/standard-conversions.md index 2c6163b9806..aabdc570be3 100644 --- a/docs/cpp/standard-conversions.md +++ b/docs/cpp/standard-conversions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Standard conversions" title: "Standard conversions" -ms.date: "10/02/2019" +description: "Learn more about: 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| @@ -202,7 +203,7 @@ The second case in which a pointer to a class can be converted to a pointer to a The result of such a conversion is a pointer to the *subobject*, the portion of the object that is completely described by the base class. -The following code defines two classes, `A` and `B`, where `B` is derived from `A`. (For more information on inheritance, see [Derived Classes](../cpp/inheritance-cpp.md).) It then defines `bObject`, an object of type `B`, and two pointers (`pA` and `pB`) that point to the object. +The following code defines two classes, `A` and `B`, where `B` is derived from `A`. For more information on inheritance, see [Derived Classes](../cpp/inheritance-cpp.md). It then defines `bObject`, an object of type `B`, and two pointers (`pA` and `pB`) that point to the object. ```cpp // C2039 expected @@ -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 @@ -277,7 +278,7 @@ A reference to a class can be converted to a reference to a base class in these - The specified base class is accessible. -- The conversion is unambiguous. (For more information about ambiguous base-class references, see [Multiple base classes](../cpp/multiple-base-classes.md).) +- The conversion is unambiguous. For more information about ambiguous base-class references, see [Multiple base classes](../cpp/multiple-base-classes.md). The result of the conversion is a pointer to the subobject that represents the base class. @@ -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 727c96727c4..9ca5dc04b5d 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 a6e9a503516..61ad524d75c 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 561a75d2728..643fd31daea 100644 --- a/docs/cpp/string-and-character-literals-cpp.md +++ b/docs/cpp/string-and-character-literals-cpp.md @@ -211,7 +211,7 @@ char u5 = '\U00000041'; // \U UCN 'A' Universal character names can't encode values in the surrogate code point range D800-DFFF. For Unicode surrogate pairs, specify the universal character name by using `\UNNNNNNNN`, where NNNNNNNN is the eight-digit code point for the character. The compiler generates a surrogate pair if necessary. -In C++03, the language only allowed a subset of characters to be represented by their universal character names, and allowed some universal character names that didn’t actually represent any valid Unicode characters. This mistake was fixed in the C++11 standard. In C++11, both character and string literals and identifiers can use universal character names. For more information on universal character names, see [Character Sets](../cpp/character-sets.md). For more information about Unicode, see [Unicode](/windows/win32/intl/unicode). For more information about surrogate pairs, see [Surrogate Pairs and Supplementary Characters](/windows/win32/Intl/surrogates-and-supplementary-characters). +In C++03, the language only allowed a subset of characters to be represented by their universal character names, and allowed some universal character names that didn't actually represent any valid Unicode characters. This mistake was fixed in the C++11 standard. In C++11, both character and string literals and identifiers can use universal character names. For more information on universal character names, see [Character Sets](../cpp/character-sets.md). For more information about Unicode, see [Unicode](/windows/win32/intl/unicode). For more information about surrogate pairs, see [Surrogate Pairs and Supplementary Characters](/windows/win32/Intl/surrogates-and-supplementary-characters). ## String literals @@ -331,7 +331,10 @@ const size_t byteSize = (wcslen(str) + 1) * sizeof(wchar_t); Notice that `strlen()` and `wcslen()` don't include the size of the terminating null character, whose size is equal to the element size of the string type: one byte on a `char*` or `char8_t*` string, two bytes on `wchar_t*` or `char16_t*` strings, and four bytes on `char32_t*` strings. -The maximum length of a string literal is 65,535 bytes. This limit applies to both narrow string literals and wide string literals. +Maximum length of a string literal after concatenation: + +* Visual Studio prior to 2022 version 17.0: the maximum length of a string literal after concatenation is 65,535 bytes. This applies to both narrow and wide string literals. +* From Visual Studio 2022 version 17.0 onwards: the maximum length of a string literal after concatenation is only limited by available memory. However, the size limit before concatenation is still 16,384 bytes ### Modifying string literals @@ -391,7 +394,7 @@ The actual result is a hexadecimal 5F, which is the ASCII code for an underscore "\x05" "five" // Use string splicing. ``` -`std::string` literals (and the related `std::u8string`, `std::u16string`, and `ste::u32string`) can be concatenated with the **`+`** operator that's defined for [`basic_string`](../standard-library/basic-string-class.md) types. They can also be concatenated in the same way as adjacent string literals. In both cases, the string encoding and the suffix must match: +`std::string` literals (and the related `std::u8string`, `std::u16string`, and `std::u32string`) can be concatenated with the **`+`** operator that's defined for [`basic_string`](../standard-library/basic-string-class.md) types. They can also be concatenated in the same way as adjacent string literals. In both cases, the string encoding and the suffix must match: ```cpp auto x1 = "hello" " " " world"; // OK diff --git a/docs/cpp/structured-exception-handling-c-cpp.md b/docs/cpp/structured-exception-handling-c-cpp.md index 832b1ef11d1..ab3f3c5817f 100644 --- a/docs/cpp/structured-exception-handling-c-cpp.md +++ b/docs/cpp/structured-exception-handling-c-cpp.md @@ -1,20 +1,20 @@ --- title: "Structured Exception Handling (C/C++)" description: "An overview of structured exception handling in Microsoft C/C++." -ms.date: 08/24/2020 +ms.date: 09/27/2022 helpviewer_keywords: ["termination handlers [C++], handling exceptions in C++", "structured exception handling [C++]", "try-catch keyword [C++], exception handlers", "C++ exception handling, termination handlers", "try-catch keyword [C++], termination handlers", "C++ exception handling, exception handlers"] ms.assetid: dd3b647d-c269-43a8-aab9-ad1458712976 --- # Structured Exception Handling (C/C++) -Structured exception handling (SEH) is a Microsoft extension to C to handle certain exceptional code situations, such as hardware faults, gracefully. Although Windows and Microsoft C++ support SEH, we recommend that you use ISO-standard C++ exception handling. It makes your code more portable and flexible. However, to maintain existing code or for particular kinds of programs, you still might have to use SEH. +Structured exception handling (SEH) is a Microsoft extension to C and C++ to handle certain exceptional code situations, such as hardware faults, gracefully. Although Windows and Microsoft C++ support SEH, we recommend that you use ISO-standard C++ exception handling in C++ code. It makes your code more portable and flexible. However, to maintain existing code or for particular kinds of programs, you still might have to use SEH. **Microsoft-specific:** ## Grammar > *`try-except-statement`* :
->  **`__try`** *`compound-statement`* **`__except`** **`(`** *`expression`* **`)`** *`compound-statement`* +>  **`__try`** *`compound-statement`* **`__except`** **`(`** *`filter-expression`* **`)`** *`compound-statement`* > > *`try-finally-statement`* :
>  **`__try`** *`compound-statement`* **`__finally`** *`compound-statement`* @@ -23,23 +23,23 @@ Structured exception handling (SEH) is a Microsoft extension to C to handle cert With SEH, you can ensure that resources, such as memory blocks and files, get released correctly if execution unexpectedly terminates. You can also handle specific problems—for example, insufficient memory—by using concise structured code that doesn't rely on **`goto`** statements or elaborate testing of return codes. -The `try-except` and `try-finally` statements referred to in this article are Microsoft extensions to the C language. They support SEH by enabling applications to gain control of a program after events that would otherwise terminate execution. Although SEH works with C++ source files, it's not specifically designed for C++. If you use SEH in a C++ program that you compile by using the [`/EHa` or `/EHsc`](../build/reference/eh-exception-handling-model.md) option, destructors for local objects are called but other execution behavior might not be what you expect. For an illustration, see the example later in this article. In most cases, instead of SEH we recommend that you use ISO-standard [C++ exception handling](../cpp/try-throw-and-catch-statements-cpp.md), which the Microsoft C++ compiler also supports. By using C++ exception handling, you can ensure that your code is more portable, and you can handle exceptions of any type. +The [`try-except`](./try-except-statement.md) and [`try-finally`](./try-finally-statement.md) statements referred to in this article are Microsoft extensions to the C and C++ languages. They support SEH by enabling applications to gain control of a program after events that would otherwise terminate execution. Although SEH works with C++ source files, it's not specifically designed for C++. If you use SEH in a C++ program that you compile by using the [`/EHa` or `/EHsc`](../build/reference/eh-exception-handling-model.md) option, destructors for local objects are called, but other execution behavior might not be what you expect. For an illustration, see the example later in this article. In most cases, instead of SEH we recommend that you use ISO-standard [C++ exception handling](../cpp/try-throw-and-catch-statements-cpp.md). By using C++ exception handling, you can ensure that your code is more portable, and you can handle exceptions of any type. If you have C code that uses SEH, you can mix it with C++ code that uses C++ exception handling. For information, see [Handle structured exceptions in C++](../cpp/exception-handling-differences.md). There are two SEH mechanisms: -- [Exception handlers](../cpp/writing-an-exception-handler.md), or **`__except`** blocks, which can respond to or dismiss the exception. +- [Exception handlers](../cpp/writing-an-exception-handler.md), or **`__except`** blocks, which can respond to or dismiss the exception based on the *`filter-expression`* value. For more information, see [`try-except` statement](./try-except-statement.md). -- [Termination handlers](../cpp/writing-a-termination-handler.md), or **`__finally`** blocks, which are always called, whether an exception causes termination or not. +- [Termination handlers](../cpp/writing-a-termination-handler.md), or **`__finally`** blocks, which are always called, whether an exception causes termination or not. For more information, see [`try-finally` statement](./try-finally-statement.md). These two kinds of handlers are distinct, but are closely related through a process known as *unwinding the stack*. When a structured exception occurs, Windows looks for the most recently installed exception handler that's currently active. The handler can do one of three things: -- Fail to recognize the exception and pass control to other handlers. +- Fail to recognize the exception and pass control to other handlers (`EXCEPTION_CONTINUE_SEARCH`). -- Recognize the exception but dismiss it. +- Recognize the exception but dismiss it (`EXCEPTION_CONTINUE_EXECUTION`). -- Recognize the exception and handle it. +- Recognize the exception and handle it (`EXCEPTION_EXECUTE_HANDLER`). The exception handler that recognizes the exception may not be in the function that was running when the exception occurred. It may be in a function much higher on the stack. The currently running function and all other functions on the stack frame are terminated. During this process, the stack is *unwound*. That is, local non-static variables of terminated functions get cleared from the stack. @@ -67,17 +67,17 @@ class TestClass public: ~TestClass() { - printf("Destroying TestClass!\r\n"); + printf("Destroying TestClass!\n"); } }; __declspec(noinline) void TestCPPEX() { #ifdef CPPEX - printf("Throwing C++ exception\r\n"); + printf("Throwing C++ exception\n"); throw std::exception(""); #else - printf("Triggering SEH exception\r\n"); + printf("Triggering SEH exception\n"); volatile int *pInt = 0x00000000; *pInt = 20; #endif @@ -97,7 +97,7 @@ int main() } __except(EXCEPTION_EXECUTE_HANDLER) { - printf("Executing SEH __except block\r\n"); + printf("Executing SEH __except block\n"); } return 0; diff --git a/docs/cpp/subscript-operator.md b/docs/cpp/subscript-operator.md index 86d55361d04..ae2835f6359 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 54bcda7443b..321b32fa4ca 100644 --- a/docs/cpp/switch-statement-cpp.md +++ b/docs/cpp/switch-statement-cpp.md @@ -1,11 +1,10 @@ --- title: "switch statement (C++)" description: "Reference to the Standard C++ switch statement in Microsoft Visual Studio C++." -ms.date: "04/25/2020" +ms.date: 04/25/2020 f1_keywords: ["default_cpp", "switch_cpp", "case_cpp"] helpviewer_keywords: ["switch keyword [C++]", "case keyword [C++], in switch statements", "default keyword [C++]"] no-loc: [switch, case, default, break, while, opt] -ms.assetid: 6c3f3ed3-5593-463c-8f4b-b33742b455c6 --- # `switch` statement (C++) @@ -14,19 +13,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 @@ -117,7 +116,7 @@ int main() break; case status::bad: throw BadGadget(); - }; + } ``` An inner block of a **`switch`** statement can contain definitions with initializers as long as they're *reachable*, that is, not bypassed by all possible execution paths. Names introduced using these declarations have local scope. For example: diff --git a/docs/cpp/templates-and-name-resolution.md b/docs/cpp/templates-and-name-resolution.md index d54b1e2dd7f..f6737fa2ecd 100644 --- a/docs/cpp/templates-and-name-resolution.md +++ b/docs/cpp/templates-and-name-resolution.md @@ -64,7 +64,7 @@ A type is dependent if it depends on the template arguments. Specifically, a typ ## Type Dependence and Value Dependence -Names and expressions dependent on a template parameter are categorized as type dependent or value dependent, depending on whether the template parameter is a type parameter or a value parameter. Also, any identifiers declared in a template with a type dependent on the template argument are considered value dependent, as is a integral or enumeration type initialized with a value-dependent expression. +Names and expressions dependent on a template parameter are categorized as type dependent or value dependent, depending on whether the template parameter is a type parameter or a value parameter. Also, any identifiers declared in a template with a type dependent on the template argument are considered value dependent, as is an integral or enumeration type initialized with a value-dependent expression. Type-dependent and value-dependent expressions are expressions that involve variables that are type dependent or value dependent. These expressions can have semantics that differ, depending on the parameters used for the template. diff --git a/docs/cpp/templates-cpp.md b/docs/cpp/templates-cpp.md index b7b65afd822..bc964932988 100644 --- a/docs/cpp/templates-cpp.md +++ b/docs/cpp/templates-cpp.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Templates (C++)" title: "Templates (C++)" -ms.date: "12/27/2019" +description: "Learn more about: Templates (C++)" +ms.date: 12/27/2019 f1_keywords: ["template_cpp"] helpviewer_keywords: ["templates, C++", "templates [C++]"] -ms.assetid: 90fcc14a-2092-47af-9d2e-dba26d25b872 --- # Templates (C++) @@ -157,7 +156,7 @@ class MyClass2 }; ``` -Because the *Arr* parameter itself has no body, its parameter names are not needed. In fact, it is an error to refer to *Arr*'s typename or class parameter names from within the body of `MyClass2`. For this reason, *Arr*'s type parameter names can be omitted, as shown in this example: +Because the *Arr* parameter itself has no body, its parameter names are not needed. In fact, it is an error to refer to *Arr*'s typename or class parameter names from within the body of `MyClass2`. For this reason, *Arr*'s type parameter names can be omitted, as shown in this example: ```cpp template class Arr> @@ -207,7 +206,7 @@ int main() ## Template specialization -In some cases, it isn’t possible or desirable for a template to define exactly the same code for any type. For example, you might wish to define a code path to be executed only if the type argument is a pointer, or a std::wstring, or a type derived from a particular base class. In such cases you can define a *specialization* of the template for that particular type. When a user instantiates the template with that type, the compiler uses the specialization to generate the class, and for all other types, the compiler chooses the more general template. Specializations in which all parameters are specialized are *complete specializations*. If only some of the parameters are specialized, it is called a *partial specialization*. +In some cases, it isn't possible or desirable for a template to define exactly the same code for any type. For example, you might wish to define a code path to be executed only if the type argument is a pointer, or a std::wstring, or a type derived from a particular base class. In such cases you can define a *specialization* of the template for that particular type. When a user instantiates the template with that type, the compiler uses the specialization to generate the class, and for all other types, the compiler chooses the more general template. Specializations in which all parameters are specialized are *complete specializations*. If only some of the parameters are specialized, it is called a *partial specialization*. ```cpp template diff --git a/docs/cpp/this-pointer.md b/docs/cpp/this-pointer.md index ef9e1bb8595..1b560dd3728 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 8fac3bb88c1..1f17ade4e51 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 @@ -367,7 +369,7 @@ items: - name: Pimpl idiom for compile-time encapsulation href: ../cpp/pimpl-for-compile-time-encapsulation-modern-cpp.md - name: Portability at ABI boundaries - href: ../cpp/portability-at-abi-boundaries-modern-cpp.md + href: ../cpp/portability-at-abi-boundaries-modern-cpp.md - name: Constructors items: - name: Constructors @@ -554,6 +556,8 @@ items: href: ../cpp/modules-cpp.md - name: module, import, export href: ../cpp/import-export-module.md + - name: "Tutorial: Import the standard library as a module" + href: ../cpp/tutorial-import-stl-named-module.md - name: Named modules tutorial in C++ href: ../cpp/tutorial-named-modules-cpp.md - name: Templates @@ -640,6 +644,8 @@ items: href: ../cpp/thiscall.md - name: __vectorcall href: ../cpp/vectorcall.md + - name: __preserve_none + href: ../cpp/preserve-none.md - name: "Calling example: Function prototype and call" items: - name: "Calling example: Function prototype and call" @@ -692,6 +698,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 6f6b018cedb..b05544d78bc 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](errors-and-exception-handling-modern-cpp.md), [structured exception handling (SEH)](/windows/win32/debug/structured-exception-handling), and [common language runtime (CLR) exceptions](../extensions/exception-handling-cpp-component-extensions.md). 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-except-statement.md b/docs/cpp/try-except-statement.md index cb344b682e9..451aed3b2a8 100644 --- a/docs/cpp/try-except-statement.md +++ b/docs/cpp/try-except-statement.md @@ -4,7 +4,6 @@ description: "The Microsoft C++ reference to the __try and __except structured e ms.date: 08/25/2020 f1_keywords: ["_abnormal_termination_cpp", "_exception_code_cpp", "_exception_info", "__except", "_except", "_exception_code", "__except_cpp", "_exception_info_cpp"] helpviewer_keywords: ["__try keyword [C++]", "EXCEPTION_CONTINUE_EXECUTION macro", "EXCEPTION_CONTINUE_SEARCH macro", "EXCEPTION_EXECUTE_HANDLER macro", "GetExceptionCode function", "try-catch keyword [C++], try-except keyword [C++]", "_exception_code keyword [C++]", "try-except keyword [C++]", "_exception_info keyword [C++]", "_abnormal_termination keyword [C++]"] -ms.assetid: 30d60071-ea49-4bfb-a8e6-7a420de66381 --- # `try-except` statement @@ -115,7 +114,7 @@ int filter(unsigned int code, struct _EXCEPTION_POINTERS *ep) { puts("didn't catch AV, unexpected."); return EXCEPTION_CONTINUE_SEARCH; - }; + } } int main() diff --git a/docs/cpp/try-finally-statement.md b/docs/cpp/try-finally-statement.md index da5bcbcc209..538555ed277 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 d18bac16272..602b308056c 100644 --- a/docs/cpp/try-throw-and-catch-statements-cpp.md +++ b/docs/cpp/try-throw-and-catch-statements-cpp.md @@ -1,10 +1,9 @@ --- description: "Learn more about: try, throw, and catch Statements (C++)" title: "try, throw, and catch Statements (C++)" -ms.date: "11/04/2016" +ms.date: 02/01/2023 f1_keywords: ["catch_cpp", "try_cpp", "throw_cpp"] helpviewer_keywords: ["catch keyword [C++]", "keywords [C++], exception handling", "C++ exception handling, statement syntax", "try-catch keyword [C++], about try-catch exception handling", "throw keyword [C++]", "try-catch keyword [C++]", "try-catch keyword [C++], exception handling", "throwing exceptions [C++], throw keyword", "try-catch keyword [C++], throw keyword [C++]s", "throwing exceptions [C++], implementing C++ exception handling", "throwing exceptions [C++]", "throw keyword [C++], throw() vs. throw(...)"] -ms.assetid: 15e6a87b-b8a5-4032-a7ef-946c644ba12a --- # try, throw, and catch Statements (C++) @@ -12,7 +11,7 @@ To implement exception handling in C++, you use **`try`**, **`throw`**, and **`c First, use a **`try`** block to enclose one or more statements that might throw an exception. -A **`throw`** expression signals that an exceptional condition—often, an error—has occurred in a **`try`** block. You can use an object of any type as the operand of a **`throw`** expression. Typically, this object is used to communicate information about the error. In most cases, we recommend that you use the [std::exception](../standard-library/exception-class.md) class or one of the derived classes that are defined in the standard library. If one of those is not appropriate, we recommend that you derive your own exception class from `std::exception`. +A **`throw`** expression signals that an exceptional condition—often, an error—has occurred in a **`try`** block. You can use an object of any type as the operand of a **`throw`** expression. Typically, this object is used to communicate information about the error. In most cases, we recommend that you use the [`std::exception`](../standard-library/exception-class.md) class or one of the derived classes that are defined in the standard library. If one of those isn't appropriate, we recommend that you derive your own exception class from `std::exception`. To handle exceptions that may be thrown, implement one or more **`catch`** blocks immediately following a **`try`** block. Each **`catch`** block specifies the type of exception it can handle. @@ -54,9 +53,9 @@ MyData GetNetworkResource() ## Remarks -The code after the **`try`** clause is the guarded section of code. The **`throw`** expression *throws*—that is, raises—an exception. The code block after the **`catch`** clause is the exception handler. This is the handler that *catches* the exception that's thrown if the types in the **`throw`** and **`catch`** expressions are compatible. For a list of rules that govern type-matching in **`catch`** blocks, see [How Catch Blocks are Evaluated](../cpp/how-catch-blocks-are-evaluated-cpp.md). If the **`catch`** statement specifies an ellipsis (...) instead of a type, the **`catch`** block handles every type of exception. When you compile with the [/EHa](../build/reference/eh-exception-handling-model.md) option, these can include C structured exceptions and system-generated or application-generated asynchronous exceptions such as memory protection, divide-by-zero, and floating-point violations. Because **`catch`** blocks are processed in program order to find a matching type, an ellipsis handler must be the last handler for the associated **`try`** block. Use `catch(...)` with caution; do not allow a program to continue unless the catch block knows how to handle the specific exception that is caught. Typically, a `catch(...)` block is used to log errors and perform special cleanup before program execution is stopped. +The code after the **`try`** clause is the guarded section of code. The **`throw`** expression *throws*—that is, raises—an exception. The code block after the **`catch`** clause is the exception handler. This is the handler that *catches* the exception that's thrown if the types in the **`throw`** and **`catch`** expressions are compatible. For a list of rules that govern type-matching in **`catch`** blocks, see [How Catch Blocks are Evaluated](../cpp/how-catch-blocks-are-evaluated-cpp.md). If the **`catch`** statement specifies an ellipsis (...) instead of a type, the **`catch`** block handles every type of exception. When you compile with the [`/EHa`](../build/reference/eh-exception-handling-model.md) option, these can include C structured exceptions and system-generated or application-generated asynchronous exceptions such as memory protection, divide-by-zero, and floating-point violations. Because **`catch`** blocks are processed in program order to find a matching type, an ellipsis handler must be the last handler for the associated **`try`** block. Use `catch(...)` with caution; don't allow a program to continue unless the catch block knows how to handle the specific exception that is caught. Typically, a `catch(...)` block is used to log errors and perform special cleanup before program execution is stopped. -A **`throw`** expression that has no operand re-throws the exception currently being handled. We recommend this form when re-throwing the exception, because this preserves the original exception’s polymorphic type information. Such an expression should only be used in a **`catch`** handler or in a function that's called from a **`catch`** handler. The re-thrown exception object is the original exception object, not a copy. +A **`throw`** expression that has no operand rethrows the exception currently being handled. We recommend this form when rethrowing the exception, because this preserves the original exception's polymorphic type information. Such an expression should only be used in a **`catch`** handler or in a function that's called from a **`catch`** handler. The rethrown exception object is the original exception object, not a copy. ```cpp try { @@ -76,4 +75,4 @@ catch(...) { [Modern C++ best practices for exceptions and error handling](../cpp/errors-and-exception-handling-modern-cpp.md)
[Keywords](../cpp/keywords-cpp.md)
[Unhandled C++ Exceptions](../cpp/unhandled-cpp-exceptions.md)
-[__uncaught_exception](../c-runtime-library/reference/uncaught-exception.md) +[`__uncaught_exception`](../c-runtime-library/reference/uncaught-exception.md) diff --git a/docs/cpp/tutorial-import-stl-named-module.md b/docs/cpp/tutorial-import-stl-named-module.md new file mode 100644 index 00000000000..717ad7e3d43 --- /dev/null +++ b/docs/cpp/tutorial-import-stl-named-module.md @@ -0,0 +1,236 @@ +--- +title: "Tutorial: Import the standard library (STL) using modules from the command line (C++)" +description: "Learn how to import the C++ standard library (STL) using modules from the command line." +ms.date: 01/29/2024 +ms.topic: "tutorial" +author: "tylermsft" +ms.author: "twhitney" +helpviewer_keywords: ["modules [C++]", "named modules [C++], import standard library (STL) using named modules"] +--- + +# Tutorial: Import the C++ standard library using modules from the command line + +Learn how to import the C++ standard library using C++ library modules. This results in faster compilation and is more robust than using header files or header units or precompiled headers (PCH). + +In this tutorial, learn about: + +- How to import the standard library as a module from the command line. +- The performance and usability benefits of modules. +- The two standard library modules `std` and `std.compat` and the difference between them. + +## Prerequisites + +This tutorial requires Visual Studio 2022 17.5 or later. + +## Introduction to standard library modules + +Header file semantics can change depending on macro definitions, the order in which you include them, and they slow compilation. Modules solve these problems. + +It's now possible to import the standard library as a module instead of as a tangle of header files. This is much faster and more robust than including header files, header units, or precompiled headers (PCH). + +The C++23 standard library introduces two named modules: `std` and `std.compat`: + +- `std` exports the declarations and names defined in the C++ standard library namespace `std`, such as `std::vector`. It also exports the contents of C wrapper headers such as `` and ``, which provide functions like `std::printf()`. C functions defined in the global namespace, such as `::printf()`, aren't exported. This improves the situation where including a C wrapper header like `` *also* includes C header files like `stdio.h`, which bring in the C global namespace versions. This isn't a problem if you import `std`. +- `std.compat` exports everything in `std` and adds the C runtime global namespaces such as `::printf`, `::fopen`, `::size_t`, `::strlen`, and so on. The `std.compat` module makes it easier to work with codebases that refer to many C runtime functions/types in the global namespace. + +The compiler imports the entire standard library when you use `import std;` or `import std.compat;` and does it faster than bringing in a single header file. It's faster to bring in the entire standard library with `import std;` (or `import std.compat`) than to `#include `, for example. + +Because named modules don't expose macros, macros like `assert`, `errno`, `offsetof`, `va_arg`, and others aren't available when you import `std` or `std.compat`. See [Standard library named module considerations](#standard-library-named-module-considerations) for workarounds. + +## About C++ modules + +Header files are how declarations and definitions have been shared between source files in C++. Before standard library modules, you'd include the part of the standard library you needed with a directive like `#include `. Header files are fragile and difficult to compose because their semantics may change depending on the order you include them, or whether certain macros are defined. They also slow compilation because they're reprocessed by every source file that includes them. + +C++20 introduces a modern alternative called *modules*. In C++23, we were able to capitalize on module support to introduce named modules to represent the standard library. + +Like header files, modules allow you to share declarations and definitions across source files. But unlike header files, modules aren't fragile and are easier to compose because their semantics don't change due to macro definitions or the order in which you import them. The compiler can process modules much faster than it can process `#include` files, and uses less memory at compile time as well. Named modules don't expose macro definitions or private implementation details. + +This article demonstrates the new and best way to consume the standard library. For more information about alternative ways to consume the standard library, see [Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md). + +## Import the standard library with `std` + +The following examples demonstrate how to consume the standard library as a module using the command line compiler. For information about how to do this in the Visual Studio IDE, see [Build ISO C++23 Standard Library Modules](../build/reference/c-cpp-prop-page.md#build-iso-c23-standard-library-modules). + +The statement `import std;` or `import std.compat;` imports the standard library into your application. But first, you must compile the standard library named modules into binary form. The following steps demonstrate how. + +### Example: How to build and import `std` + +1. Open a x86 Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You get errors if you use the wrong version of the prompt. The examples used in this tutorial are for the CMD shell. +1. Create a directory, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors during compilation. +1. Compile the `std` named module with the following command: + + ```cmd + cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" + ``` + + If you get errors, ensure that you're using the correct version of the command prompt. + + Compile the `std` named module using the same compiler settings that you intend to use with the code that imports the built module. If you have a multi-project solution, you can compile the standard library named module once, and then refer to it from all of your projects by using the [`/reference`](../build/reference/module-reference.md) compiler option. + + Using the previous compiler command, the compiler outputs two files: + - `std.ifc` is the compiled binary representation of the named module interface that the compiler consults to process the `import std;` statement. This is a compile-time only artifact. It doesn't ship with your application. + - `std.obj` contains the implementation of the named module. Add `std.obj` to the command line when you compile the sample app to statically link the functionality you use from the standard library into your application. + + The key command-line switches in this example are: + + | Switch | Meaning | + |---|---| + | [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) | Use the latest version of the C++ language standard and library. Although module support is available under `/std:c++20`, you need the latest standard library to get support for standard library named modules. | + | [`/EHsc`](../build/reference/eh-exception-handling-model.md) | Use C++ exception handling, except for functions marked `extern "C"`. | + | [`/W4`](../build/reference/compiler-option-warning-level.md) | Using `/W4` is generally recommended, especially for new projects because it enables all level 1, level 2, level 3, and most level 4 (informational) warnings, which can help you catch potential issues early. It essentially provides lint-like warnings that can help ensure the fewest possible hard-to-find code defects. | + | [`/c`](../build/reference/c-compile-without-linking.md) | Compile without linking, because we're just building the binary named module interface at this point. | + + You can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo:"somethingelse"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the object file name is `std.obj` by default because we're compiling the module file `std.ixx`. + - [`/ifcOutput`](../build/reference/ifc-output.md) sets the name of the named module interface file (`.ifc`). For example, `/ifcOutput "somethingelse.ifc"`. By default, the compiler uses the same name for the module interface file (`.ifc`) as the module source file (`.ixx`) you're compiling. In the example, the generated `ifc` file is `std.ifc` by default because we're compiling the module file `std.ixx`. + +1. Import the `std` library you built by first creating a file named `importExample.cpp` with the following content: + + ```cpp + // requires /std:c++latest + + import std; + + int main() + { + std::cout << "Import the STL library for best performance\n"; + std::vector v{5, 5, 5}; + for (const auto& e : v) + { + std::cout << e; + } + } + ``` + + In the preceding code, `import std;` replaces `#include ` and `#include `. The statement `import std;` makes all of the standard library available with one statement. Importing the entire standard library is often much faster than processing a single standard library header file such as `#include `. + +1. Compile the example by using the following command in the same directory as the previous step: + + ```cmd + cl /c /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp + link importExample.obj std.obj + ``` + + It isn't necessary to specify `/reference "std=std.ifc"` on the command line in this example because the compiler automatically looks for the `.ifc` file matching the module name specified by the `import` statement. When the compiler encounters `import std;` it can find `std.ifc` if it's located in the same directory as the source code. If the `.ifc` file is in a different directory than the source code, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + + In this example, compiling the source code and linking the module's implementation into the application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 /reference "std=std.ifc" importExample.cpp std.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects, in your build's link step. + + If you're building a single project, you can combine the steps of building the `std` standard library named module and the step of building your application by adding `"%VCToolsInstallDir%\modules\std.ixx"` to the command line. Put it before any `.cpp` files that consume the `std` module. + + By default, the output executable's name is taken from the first input file. Use the `/Fe` compiler option to specify the executable file name you want. This tutorial shows compiling the `std` named module as a separate step because you only need to build the standard library named module once, and then you can refer to it from your project, or from multiple projects. But it may be convenient to build everything together, as shown by this command line: + + ```cmd + cl /FeimportExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" importExample.cpp + ``` + + Given the previous command line, the compiler produces an executable named `importExample.exe`. When you run it, it produces the following output: + + ```output + Import the STL library for best performance + 555 + ``` + +## Import the standard library and global C functions with `std.compat` + +The C++ standard library includes the ISO C standard library. The `std.compat` module provides all of the functionality of the `std` module like `std::vector`, `std::cout`, `std::printf`, `std::scanf`, and so on. But it also provides the global namespace versions of these functions such as `::printf`, `::scanf`, `::fopen`, `::size_t`, and so on. + +The `std.compat` named module is a compatibility layer provided to ease migrating existing code that refers to C runtime functions in the global namespace. If you want to avoid adding names to the global namespace, use `import std;`. If you need to ease migrating a codebase that uses many unqualified (global namespace) C runtime functions, use `import std.compat;`. This provides the global namespace C runtime names so that you don't have to qualify all the global names with `std::`. If you don't have any existing code that uses the global namespace C runtime functions, then you don't need to use `import std.compat;`. If you only call a few C runtime functions in your code, it may be better to use `import std;` and qualify the few global namespace C runtime names that need it with `std::`. For example, `std::printf()`. If you see an error like `error C3861: 'printf': identifier not found` when you try to compile your code, consider using `import std.compat;` to import the global namespace C runtime functions. + +### Example: How to build and import `std.compat` + +Before you can use `import std.compat;` you must compile the module interface file found in source code form in `std.compat.ixx`. Visual Studio ships the source code for the module so that you can compile the module using the compiler settings that match your project. The steps are similar to for building the `std` named module. The `std` named module is built first because `std.compat` depends on it: + +1. Open a Native Tools Command Prompt for VS: from the Windows **Start** menu, type *x86 native* and the prompt should appear in the list of apps. Ensure that the prompt is for Visual Studio 2022 version 17.5 or above. You'll get compiler errors if you use the wrong version of the prompt. +1. Create a directory to try this example, such as `%USERPROFILE%\source\repos\STLModules`, and make it the current directory. If you choose a directory that you don't have write access to, you'll get errors. +1. Compile the `std` and `std.compat` named modules with the following command: + + ```cmd + cl /std:c++latest /EHsc /nologo /W4 /c "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" + ``` + + You should compile `std` and `std.compat` using the same compiler settings that you intend to use with the code that will import them. If you have a multi-project solution, you can compile them once, and then refer to them from all of your projects using the [`/reference`](../build/reference/module-reference.md) compiler option. + + If you get errors, ensure that you're using the correct version of the command prompt. + + The compiler outputs four files from the previous two steps: + - `std.ifc` is the compiled binary named module interface that the compiler consults to process the `import std;` statement. The compiler also consults `std.ifc` to process `import std.compat;` because `std.compat` builds on `std`. This is a compile-time only artifact. It doesn't ship with your application. + - `std.obj` contains the implementation of the standard library. + - `std.compat.ifc` is the compiled binary named module interface that the compiler consults to process the `import std.compat;` statement. This is a compile-time only artifact. It doesn't ship with your application. + - `std.compat.obj` contains implementation. However, most of the implementation is provided by `std.obj`. Add `std.obj` to the command line when you compile the sample app to statically link the functionality that you use from the standard library into your application. + + You can control the object file name and the named module interface file name with the following switches: + - [`/Fo`](../build/reference/fo-object-file-name.md) sets the name of the object file. For example, `/Fo:"somethingelse"`. By default, the compiler uses the same name for the object file as the module source file (`.ixx`) you're compiling. In the example, the object file names are `std.obj` and `std.compat.obj` by default because we're compiling the module files `std.ixx` and `std.compat.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` files are `std.ifc` and `std.compat.ifc` by default because we're compiling the module files `std.ixx` and `std.compat.ixx`. + +1. Import the `std.compat` library by first creating a file named `stdCompatExample.cpp` with the following content: + + ```cpp + import std.compat; + + int main() + { + printf("Import std.compat to get global names like printf()\n"); + + std::vector v{5, 5, 5}; + for (const auto& e : v) + { + printf("%i", e); + } + } + ``` + + In the preceding code, `import std.compat;` replaces `#include ` and `#include `. The statement `import std.compat;` makes the standard library and C runtime functions available with one statement. Importing this named module, which includes the C++ standard library and C runtime library global namespace functions, is faster than processing a single `#include` like `#include `. + +1. Compile the example by using the following command: + + ```cmd + cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp + link stdCompatExample.obj std.obj std.compat.obj + ``` + + We didn't have to specify `std.compat.ifc` on the command line because the compiler automatically looks for the `.ifc` file that matches the module name in an `import` statement. When the compiler encounters `import std.compat;` it finds `std.compat.ifc` since we put it in the same directory as the source code--relieving us of the need to specify it on the command line. If the `.ifc` file is in a different directory than the source code, or has a different name, use the [`/reference`](../build/reference/module-reference.md) compiler switch to refer to it. + + When you import `std.compat`, you must link against both `std.compat` and `std.obj` because `std.compat` uses code in `std.obj`. + + If you're building a single project, you can combine the steps of building the `std` and `std.compat` standard library named modules by adding `"%VCToolsInstallDir%\modules\std.ixx"` and `"%VCToolsInstallDir%\modules\std.compat.ixx"` (in that order) to the command line. This tutorial shows building the standard library modules as a separate step because you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects. But if it's convenient to build them all at once, make sure to put them before any `.cpp` files that consume them, and specify `/Fe` to name the built `exe` as shown in this example: + + ```cmd + cl /c /FestdCompatExample /std:c++latest /EHsc /nologo /W4 "%VCToolsInstallDir%\modules\std.ixx" "%VCToolsInstallDir%\modules\std.compat.ixx" stdCompatExample.cpp + link stdCompatExample.obj std.obj std.compat.obj + ``` + + In this example, compiling the source code and linking the module's implementation into your application are separate steps. They don't have to be. You could use `cl /std:c++latest /EHsc /nologo /W4 stdCompatExample.cpp std.obj std.compat.obj` to compile and link in one step. But it may be convenient to build and link separately because then you only need to build the standard library named modules once, and then you can refer to them from your project, or from multiple projects, in your build's link step. + + The previous compiler command produces an executable named `stdCompatExample.exe`. When you run it, it produces the following output: + + ```output + Import std.compat to get global names like printf() + 555 + ``` + +## Standard library named module considerations + +Versioning for named modules is the same as for headers. The `.ixx` named module files are installed alongside the headers, for example: `"%VCToolsInstallDir%\modules\std.ixx"`, which resolves to `C:\Program Files\Microsoft Visual Studio\2022\Enterprise\VC\Tools\MSVC\14.38.33130\modules\std.ixx` in the version of the tools used at the time of this writing. Select the version of the named module the same way you choose the version of the header file to use--by the directory you refer to them from. + +Don't mix and match importing header units and named modules. For example, don't `import ;` and `import std;` in the same file. + +Don't mix and match importing C++ standard library header files and the named modules `std` or `std.compat`. For example, don't `#include ` and `import std;` in the same file. However, you can include C headers and import named modules in the same file. For example, you can `import std;` and `#include ` in the same file. Just don't include the C++ standard library version ``. + +You don't have to defend against importing a module multiple times. That is, you don't need `#ifndef` style header guards in modules. The compiler knows when it has already imported a named module and ignores duplicate attempts to do so. + +If you need to use the `assert()` macro, then `#include `. + +If you need to use the `errno` macro, `#include `. Because named modules don't expose macros, this is the workaround if you need to check for errors from ``, for example. + +Macros such as `NAN`, `INFINITY`, and `INT_MIN` are defined by ``, which you can include. However, if you `import std;` you can use `std::numeric_limits::quiet_NaN()` and `std::numeric_limits::infinity()` instead of `NAN` and `INFINITY`, and `std::numeric_limits::min()` instead of `INT_MIN`. + +## Summary + +In this tutorial, you've imported the standard library using modules. Next, learn about creating and importing your own modules in [Named modules tutorial in C++](tutorial-named-modules-cpp.md). + +## See also + +[Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md)\ +[Overview of modules in C++](modules-cpp.md)\ +[A Tour of C++ Modules in Visual Studio](https://devblogs.microsoft.com/cppblog/a-tour-of-cpp-modules-in-visual-studio)\ +[Moving a project to C++ named Modules](https://devblogs.microsoft.com/cppblog/moving-a-project-to-cpp-named-modules) diff --git a/docs/cpp/tutorial-named-modules-cpp.md b/docs/cpp/tutorial-named-modules-cpp.md index 0a260bddf0b..776ac6f114f 100644 --- a/docs/cpp/tutorial-named-modules-cpp.md +++ b/docs/cpp/tutorial-named-modules-cpp.md @@ -1,15 +1,17 @@ --- title: "Named modules tutorial in C++" -ms.date: 02/10/2022 +ms.date: 02/13/2025 ms.topic: "tutorial" +author: "tylermsft" +ms.author: "twhitney" helpviewer_keywords: ["modules [C++]", "modules [C++], named modules tutorial"] description: Named modules in C++20 provide a modern alternative to header files. --- # Named modules tutorial (C++) - This tutorial introduces the basics of creating C++20 modules. Modules are a new way to componentize C++ programs, replacing the venerable header file. You'll learn how modules are an improvement on header files. And, you'll build an app that shows how to create and consume a module. +This tutorial is about creating C++20 modules. Modules are a significant improvement on header files. -In this tutorial, you learn how to: +In this tutorial, learn how to: - Create and import a module - Create a primary module interface unit @@ -18,51 +20,51 @@ In this tutorial, you learn how to: ## Prerequisites -For this tutorial, you'll need Visual Studio 2022 17.1.0 or later. - -You might get IntelliSense errors while working on the code example in this tutorial. Work on the IntelliSense engine is catching up with the compiler. IntelliSense errors can be ignored and won't prevent the code example from building. To track progress on the IntelliSense work, see this [issue](https://developercommunity.visualstudio.com/t/When-importing-a-C20-module-or-header-/1550846). +This tutorial requires Visual Studio 2022 17.1.0 or later. ## What are C++ modules -Header files are how declarations and definitions are shared between source files in C++. Header files are fragile and difficult to compose, because they may compile differently depending on the order 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. -Modules are easier to compose. They make it easier to control what is visible to consumers. And their semantics don't change because of macro definitions or what else has been imported, the order of imports, and so on. +Modules are easier to compose because their semantics don't change because of macro definitions or what else has been imported, the order of imports, and so on. They also make it easier to control what is visible to consumers. -Modules provide extra safety guarantees that header files don't. The compiler and linker work together to prevent possible name collision issues and provide stronger one definition rule ([ODR](https://stroustrup.com/glossary.html#Gone-definition-rule)) guarantees. +Modules provide extra safety guarantees that header files don't. The compiler and linker work together to prevent possible name collision issues, and provide stronger one definition rule ([ODR](https://stroustrup.com/glossary.html#Gone-definition-rule)) guarantees. A strong ownership model avoids clashes between names at link time because the linker attaches exported names to the module that exports them. This model allows the Microsoft Visual C++ compiler to prevent undefined behavior caused by linking different modules that report similar names in the same program. For more information, see [Strong Ownership](https://devblogs.microsoft.com/cppblog/standard-c20-modules-support-with-msvc-in-visual-studio-2019-version-16-8/#strong-ownership). -A module is made up of one or more source code files compiled into a binary file. The binary file describes all the exported types, functions, and templates in the module. When a source file imports a module, the compiler reads in the binary file that contains the contents of the module. Reading the binary file is faster than processing a header file. The binary file is reused by the compiler every time the module is imported by a source file. Because a module is built once rather than every time it's imported, build time can be reduced, sometimes dramatically. +A module is made up of one or more source code files compiled into a binary file. The binary file describes all the exported types, functions, and templates in the module. When a source file imports a module, the compiler reads in the binary file that contains the contents of the module. Reading the binary file is much faster than processing a header file. Also, the binary file is reused by the compiler every time the module is imported, saving even more time. Because a module is built once rather than every time it's imported, build time can be reduced, sometimes dramatically. + +More importantly, modules don't have the fragility problems that header files do. Importing a module doesn't change the module's semantics, or the semantics of any other imported module. Macros, preprocessor directives, and non-exported names declared in a module aren't visible to the source file that imports it. You can import modules in any order and it won't change the meaning of the modules. -But more importantly, modules don't have the fragility problems that header files do. Importing a module doesn't change the module's semantics, or the semantics of any other imported module. Macros, preprocessor directives, and non-exported names declared in a module aren't visible to the source file that imports it. You can import modules in any order without changing the meaning of the modules. +Modules can be used side by side with header files. This feature is convenient if you're migrating a code base to use modules because you can do it in stages. -Modules can be used side by side with header files. This feature is convenient if you're migrating a code base to use modules in stages. In some cases, a header file can be imported as a header unit rather than as an `#include` file. Header units are the recommended alternative to [precompiled header files](../build/creating-precompiled-header-files.md) (PCH). They're easier to set up and use than [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio) files, but they provide similar performance benefits. For more information, see [Walkthrough: Build and import header units in Microsoft Visual C++](../build/walkthrough-header-units.md). +In some cases, a header file can be imported as a header unit rather than as an `#include` file. Header units are the recommended alternative to [precompiled header files](../build/creating-precompiled-header-files.md) (PCH). They're easier to set up and use than [shared PCH](https://devblogs.microsoft.com/cppblog/shared-pch-usage-sample-in-visual-studio) files, but they provide similar performance benefits. For more information, see [Walkthrough: Build and import header units in Microsoft Visual C++](../build/walkthrough-header-units.md). -Your code can consume modules in the same project, or any referenced projects, automatically using project-to-project references to static library projects. +Your code can consume modules in the same project, or any referenced projects, automatically by using project-to-project references to static library projects. ## Create the project -As we build a simple project, we'll look at various aspects of modules as we implement an API using a module instead of a header file. +The following project implements an API using a module instead of a header file. -To begin, in Visual Studio 2022, choose **Create a new project** and then the **Console App** (for C++) project type. If this project type isn't available, you may not have selected the **Desktop development with C++** workload when you installed Visual Studio. You can use the Visual Studio Installer to add the C++ workload. +In Visual Studio 2022 or later, choose **Create a new project** and then the **Console App** (for C++) project type. If this project type isn't available, you may not have selected the **Desktop development with C++** workload when you installed Visual Studio. You can use the Visual Studio Installer to add the C++ workload. -Give the new project the name `ModulesTutorial` and create the project. +Give the new project the name *`ModulesTutorial`* and create the project. -Because modules are a C++20 feature, the project needs the [`/std:c++20` or `/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. Set the **C++ Language Standard** property by right-clicking in the **Solution Explorer** on the project name `ModulesTutorial`, then choose `Properties`. In the project properties page that appears, ensure that `General` is selected on the left, and then change the **C++ Language Standard** dropdown to **ISO C++20 Standard (/std:c++20)**. Select **OK** to accept the change. +Because modules are a C++20 feature, use the [`/std:c++20` or `/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. In the **Solution Explorer**, right-click on the project name `ModulesTutorial`, then choose **Properties**. In the project Property Pages dialog, change **Configuration** to **All Configurations** and **Platform** to **All Platforms**. Select **Configuration Properties** > **General** in the tree view pane on the left. Select the **C++ Language Standard** property. Use the dropdown to change the property value to **ISO C++20 Standard (/std:c++20)**. Select **OK** to accept the change. ![A screenshot of the ModulesTutorial property page with the left pane open to Configuration Properties > General, and the C++ Language Standard dropdown open with ISO C++20 Standard (/std:c++20) selected](media/language-switch.png) ## Create the primary module interface unit -A module consists of one or more files. One of 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 in a 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 on **Source Files**, then select **Add** > **Module**. +To add a primary module interface unit, in **Solution Explorer**, right-click **Source Files** then select **Add** > **Module**. -![Add item dialog in solution explorer with Add > Module... highlighted to illustrate where to click to add a module](media/add-module.png) +![Add item dialog in solution explorer with Add > Module... highlighted to illustrate where to click to add a module.](media/add-module.png) In the **Add New Item** dialog that appears, give the new module the name *`BasicPlane.Figures.ixx`* and choose **Add**. @@ -70,42 +72,43 @@ The default contents of the created module file has two lines: ```cpp export module BasicPlane; + export void MyFunc(); ``` -The first line declares this file to be a module interface unit. Specifically, the `export module` keywords identify this file as a module interface unit. There's a subtle point here. For every named module, there must be exactly one module interface unit with no module partition specified. That module unit is called the primary module interface unit. +The `export module` keywords in the first line declare that this file is a module interface unit. There's a subtle point here: for every named module, there must be exactly one module interface unit with no module partition specified. That module unit is called the *primary module interface unit*. The primary module interface unit is where you declare the functions, types, templates, other modules, and module partitions to expose when source files import the module. A module can consist of multiple files, but only the primary module interface file identifies what to expose. -Replace the contents of this file with: +Replace the contents of *`BasicPlane.Figures.ixx`* file with: ```cpp export module BasicPlane.Figures; // the export module keywords mark this 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 being part of the named module. In other words, a named module is the collection of module units with the same module name. +This name is also where the "named" in "named module" comes from. The files that are part of this module use this name to identify themselves as part of the named module. A named module is the collection of module units with the same module name. -We should talk about the API we'll implement for a moment before going further. It impacts the choices we make next. The API itself is simple. It represents different shapes. We're only going to provide a couple shapes in this example: `Point` and `Rectangle`. `Point` is meant to be used as part of more complex shapes, such as `Rectangle`. +We should talk about the API we'll implement for a moment before going further. It impacts the choices we make next. The API represents different shapes. We're only going to provide a couple shapes in this example: `Point` and `Rectangle`. `Point` is meant to be used as part of more complex shapes such as `Rectangle`. -To illustrate some features of modules, we'll factor this API into pieces. One piece will be the `Point` part of the API. The other part will be `Rectangle`. Imagine that this API will grow into something more complex. 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. They're useful for dividing the module implementation into more manageable pieces. +Module partitions are useful for dividing the module implementation into manageable parts. A module partition file is part of a module. What makes it unique is that it can be treated as an individual parts of the module--but only within the module. Module partitions can't be consumed outside of a module. -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. +When you import a partition into the primary module, all its declarations become visible to the primary module regardless of whether they're exported. Partitions can be imported into any partition interface, primary module interface, or module unit that belongs to the named module. ## Create a module partition file -### `Point` module partition +### `Point` module partition example -To create a module partition file, in the **Solution Explorer**, right-click **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Point.ixx`* and select **Add**. +To create a module partition file, in the **Solution Explorer** right-click **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Point.ixx`* and choose **Add**. -Because 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: 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. You can easily see which files belong to which modules. +Because it's a module partition file, we add a hyphen and the name of the partition to the module name. This convention aids the compiler in the command-line case because the compiler uses name lookup rules based on the module name to find the compiled *`.ifc`* file for the partition. This way you don't have to provide explicit `/reference` command-line arguments to find the partitions that belong to the module. It's also helpful for organizing the files that belong to a module by name because you can easily see which files belong to which modules. -Replace the contents of the file with: +Replace the contents of *`BasicPlane.Figures-Point.ixx`* with: ```cpp export module BasicPlane.Figures:Point; // defines a module partition, Point, that's part of the module BasicPlane.Figures @@ -116,17 +119,17 @@ export struct Point }; ``` -The file starts with `export module`. These keywords are also how the primary module interface starts out. 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 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. That is, in **Solution Explorer**, right-click on **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Rectangle.ixx`* and select **Add**. +The next partition we define is `Rectangle`. Create another module file using the same steps as before: In **Solution Explorer**, right-click on **Source Files**, then select **Add** > **Module**. Name the file *`BasicPlane.Figures-Rectangle.ixx`* and select **Add**. -Replace the contents of the file with: +Replace the contents of *`BasicPlane.Figures-Rectangle.ixx`* with: ```cpp export module BasicPlane.Figures:Rectangle; // defines the module partition Rectangle @@ -145,21 +148,21 @@ export int height(const Rectangle& r); export int width(const Rectangle& r); ``` -The file begins with `export module BasicPlane.Figures:Rectangle;`. It declares a module partition that's part of the module `BasicPlane.Figures`. The `:Rectangle` added to the module name defines it as a partition of the module `BasicPlane.Figures`. It can be imported individually into any of the module files that are part of this named module. +The file begins with `export module BasicPlane.Figures:Rectangle;` which declares a module partition that's part of the module `BasicPlane.Figures`. The `:Rectangle` added to the module name defines it as a partition of the module `BasicPlane.Figures`. It can be imported individually into any of the module files that are part of this named module. Next, `import :Point;` shows how to import a module partition. The `import` statement makes all the exported types, functions, and templates in the module partition visible to the module. You don't have to specify the module name. The compiler knows that this file belongs to the `BasicPlane.Figures` module because of the `export module BasicPlane.Figures:Rectangle;` at the top of the file. 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 directly within the braces is exported. But if elsewhere in the module you define `namespace N { struct S {...};}`, then `struct S` isn't available to consumers of the module. 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. The type, function, and so on, will be visible to other files that are part of the module, but not to importers of the module. -- Use `module :private;` to mark the beginning of the private module partition. The private module partition is a section of the module where declarations are only visible to that file. They aren't visible to files that import this module or to other files that are part of this module. Think of it as a section that is static local to the file, and visible only within the file. -- To make an imported module or module partition visible, use the `export import` keyword combination. An example is shown in the next section. +- If you put `export` in front of a namespace, for example `export namespace N { ... }`, everything defined within the braces is exported. But if elsewhere in the module you define `namespace N { struct S {...};}`, then `struct S` isn't available to consumers of the module. It's not available because that namespace declaration isn't prefaced by `export`, even though there's another namespace with the same name that is. +- If a type, function, and so on, shouldn't be exported, omit the `export` keyword. It's visible to other files that are part of the module, but not to importers of the module. +- Use `module :private;` to mark the beginning of the private module partition. The private module partition is a section of the module where declarations are only visible to that file. They aren't visible to files that import this module or to other files that are part of this module. Think of it as a section that is static local to the file. This section is visible only within the file. +- To make an imported module or module partition visible, use `export import`. An example is shown in the next section. ## Compose the module partitions @@ -174,17 +177,17 @@ 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 `export import` are new here. When combined like this, these two keywords instruct the compiler to import the specified module (in this case, a module partition, which is expressed by the colon (`:`) in the module name), and make it visible to consumers of this module. +The two lines that begin with `export import` are new here. When combined like this, these two keywords instruct the compiler to import the specified module and make it visible to consumers of this module. In this case, the colon (`:`) in the module name indicates that we're importing a module partition. -Notice that the imported names don't include the full module name. For example, the `:Point` partition was declared as `export module BasicPlane.Figures:Point;`. Yet here we're importing `:Point`. Because we're in the primary module interface file for the module `BasicPlane.Figures`, the module name is implied and only the partition name is specified. +The imported names don't include the full module name. For example, the `:Point` partition was declared as `export module BasicPlane.Figures:Point`. Yet here we're importing `:Point`. Because we're in the primary module interface file for the module `BasicPlane.Figures`, the module name is implied, and only the partition name is specified. -So far, we've defined the primary module interface, which exposes the API surface we want to make available. But we've only declared, not defined, `area()`, `height()`, or `width()`. We'll do that in a module implementation file, which we'll create next. +So far, we've defined the primary module interface, which exposes the API surface we want to make available. But we've only declared, not defined, `area()`, `height()`, or `width()`. We do that next by creating a module implementation file. ## Create a module unit implementation file -Module unit implementation files don't end with an *`.ixx`* extension. They're normal *`.cpp`* files. Add a module unit implementation file by creating a source file with a right-click in the **Solution Explorer** on **Source Files**, select **Add** > **New item** and then select **C++ File (.cpp)**. Give the new file the name `BasicPlane.Figures-Rectangle.cpp`, then select **Add**. +Module unit implementation files don't end with an *`.ixx`* extension--they're normal *`.cpp`* files. Add a module unit implementation file by creating a source file with a right-click in the **Solution Explorer** on **Source Files**, select **Add** > **New item** and then select **C++ File (.cpp)**. Give the new file the name *`BasicPlane.Figures-Rectangle.cpp`*, then choose **Add**. -The naming convention for the module partition's implementation file follows the naming convention for partition. But it has a *`.cpp`* extension because it's an implementation file. +The naming convention for the module partition's implementation file follows the naming convention for a partition. But it has a *`.cpp`* extension because it's an implementation file. Replace the contents of the `BasicPlane.Figures-Rectangle.cpp` file with: @@ -200,21 +203,21 @@ int height(const Rectangle& r) { return r.ul.y - r.lr.y; } int width(const Rectangle& r) { return r.lr.x - r.ul.x; } ``` -This file begins with `module;`, which introduces a special area of the module called the *global module fragment*. It precedes the code for the named module and is where you can use preprocessor directives such as `#include`. This area is important because code in the global module fragment isn't owned or exported by the module interface. +This file begins with `module;` which introduces a special area of the module called the *global module fragment*. It precedes the code for the named module and is where you can use preprocessor directives such as `#include`. Code in the global module fragment isn't owned or exported by the module interface. When you include a header file, you generally don't want it to be treated as an exported part of the module. You typically include the header file as an implementation detail that shouldn't be part of the module interface. There may be advanced cases where want to do that, but generally you don't. No separate metadata (*`.ifc`* files) are generated for `#include` directives in the global module fragment. Global module fragments provide a good place to include header files such as *`windows.h`*, or on Linux, *`unistd.h`*. The module implementation file we're building doesn't include any libraries because it doesn't need them as part of its implementation. But if it did, this area is where the `#include` directives would go. -The line `module BasicPlane.Figures;` identifies this file as part of the named module `BasicPlane.Figures`. The compiler automatically brings the types and functions exposed by the primary module interface into this file. A module implementation unit doesn't have the `export` keyword before the `module` keyword in its module-declaration. +The line `module BasicPlane.Figures:Rectangle;` indicates that this file is part of the named module `BasicPlane.Figures`. The compiler automatically brings the types and functions exposed by the primary module interface into this file. A module implementation unit doesn't have the `export` keyword before the `module` keyword in its module declaration. -Next are the definition of the functions `area()`, `height()`, and `width()`. They were declared in the `Rectangle` partition in `BasicPlane.Figures-Rectangle.ixx`. Because the primary module interface for this module imported the `Point` and `Rectangle` module partitions, those types are visible here in the module unit implementation file. An interesting feature of module implementation units: The compiler automatically makes everything in the corresponding module primary interface visible to the file. No `imports ` is needed. +Next are the definition of the functions `area()`, `height()`, and `width()`. They were declared in the `Rectangle` partition in *`BasicPlane.Figures-Rectangle.ixx`*. Because the primary module interface for this module imported the `Point` and `Rectangle` module partitions, those types are visible here in the module unit implementation file. An interesting feature of module implementation units: The compiler automatically makes everything in the corresponding module primary interface visible to the file. No `imports ` is needed. Anything you declare within an implementation unit is only visible to the module that it belongs to. ## Import the module -Now we'll make use of the module we've defined. Open the `ModulesTutorial.cpp` file. It was created automatically as part of the project. It currently contains the function `main()`. Replace its contents with: +Now we make use of the module we've defined. Open the *`ModulesTutorial.cpp`* file. It was created automatically as part of the project. It currently contains the function `main()`. Replace its contents with: ```cpp #include @@ -232,7 +235,7 @@ int main() } ``` -The first line, `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It can come before or after `#include` directives. +The statement `import BasicPlane.Figures;` makes all the exported functions and types from the `BasicPlane.Figures` module visible to this file. It comes after any `#include` directives. The app then uses the types and functions from the module to output the area and width of the defined rectangle: @@ -247,9 +250,9 @@ Let's now look in more detail at the various module files. ### Primary module interface -A module consists of one or more files. One of them defines the interface that importers will see. This file contains the *Primary module interface*. There can only be one primary module interface per module. As pointed out earlier, it's the exported module interface unit that doesn't specify a module partition. +A module consists of one or more files. One of them defines the interface that importers see. This file contains the *Primary module interface*. There can only be one primary module interface per module. As pointed out earlier, the exported module interface unit doesn't specify a module partition. -It has an *`.ixx`* extension by default. However, you can treat a source file with any extension as a module interface file. Set the **Compile As** property in the **Advanced** tab for the source file's properties page to **Compile As Module (/interface)**. +It has an *`.ixx`* extension by default. However, you can treat a source file with any extension as a module interface file. To do so, set the **Compile As** property in the **Advanced** tab for the source file's properties page to **Compile As Module (/interface)**: ![Screenshot of a hypothetical source file's Configuration properties under Configuration properties > C/C++ > Advanced > Compile As, with Compile as C++ Module Code (/interface) highlighted](media\file-property-compile-as.png) @@ -260,13 +263,13 @@ module; // optional. Defines the beginning of the global module fragment // #include directives go here but only apply to this file and // aren't shared with other module implementation files. -// Macro definitions aren't visible outside this file, or to importers. +// Macro definitions aren't visible outside this file or to importers. // import statements aren't allowed here. They go in the module preamble, below. export module [module-name]; // Required. Marks the beginning of the module preamble // import statements go here. They're available to all files that belong to the named module -// Put #includes in in the global module fragment, above +// Put #includes in the global module fragment, above // After any import statements, the module purview begins here // Put exported functions, types, and templates here @@ -279,11 +282,11 @@ module :private; // optional. The start of the private module partition. This file must begin with either `module;` to indicate the beginning of the global module fragment, or `export module [module-name];` to indicate the start of the *module purview*. -The module purview is where functions, types, templates, and so on, go that you want the module to expose. +The module purview is where functions, types, templates, and so on, go that you want to expose from the module. -It's also where you can expose other modules or module partitions via the `export import` keywords, as shown in the `BasicPlane.Figures.ixx` file. +It's also where you can expose other modules or module partitions via the `export import` keywords, as shown in the *`BasicPlane.Figures.ixx`* file. -The primary interface file must export all the interface partitions defined for the module, either directly or indirectly, or the program is ill-formed. +The primary interface file must export all the interface partitions defined for the module directly or indirectly, or the program is ill-formed. The private module partition is where you can put things that you want to be only visible in this file. @@ -293,26 +296,29 @@ For a more in-depth look at module syntax, see [Modules](modules-cpp.md). ### Module implementation units -Module implementation units belong to a named module. The named module they belong to is established by the `module [module-name]` statement in the file. Module implementation units provide implementation details that, for code hygiene or other reasons, you don't want to put in the primary module interface or in a module partition file. +Module implementation units belong to a named module. The named module they belong to is indicated by the `module [module-name]` statement in the file. Module implementation units provide implementation details that, for code hygiene or other reasons, you don't want to put in the primary module interface or in a module partition file. -Module implementation units are useful for breaking up a large module to factor dependencies to get faster build times. This 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 +module [module-name]; // required. Identifies which named module this implementation unit belongs to // implementation ``` ### Module partition files -Module partitions provide a way to componentize a module into different pieces, or partitions. Module partitions are meant to be imported only in files that are part of the named module. They can't be imported outside of the named module. +Module partitions provide a way to componentize a module into different parts, or *partitions*. Module partitions are meant to be imported only in files that are part of the named module. They can't be imported outside of the named module. + +A partition has an interface file, and zero or more implementation files. A module partition shares ownership of all the declarations in the entire module. -A partition has an interface file and zero or more implementation files. A module partition shares ownership of all the declarations in the entire module. All names exported by partition interface files must be imported and re-exported (`export import`) by the primary interface file. A partition's name must begin with the module name, followed by a colon, and then the name of the partition. +All names exported by partition interface files must be imported and re-exported (`export import`) by the primary interface file. A partition's name must begin with the module name, followed by a colon, and then the name of the partition. The basic outline of a partition interface file looks like this: @@ -348,14 +354,14 @@ A module and the code that imports it must be compiled with the same compiler op ### Module naming - You can use periods ('.') in your module names but they have no special meaning to the compiler. Use them to convey meaning to the users of your module. For example, start with the library or project top namespace. Finish with a name that describes the module's functionality. `BasicPlane.Figures` is meant to convey an API for geometric planes, and specifically figures that can be represented on a plane. -- The name of the file that contains the module primary interface is generally the name of the module. For example, given the module name `BasicPlane.Figures`, the name of the file containing the primary interface would be named `BasicPlane.Figures.ixx`. -- The name of a module partition file is generally `-` where the name of the module is followed by a hyphen ('-') and then the name of the partition. For example, `BasicPlane.Figures-Rectangle.ixx` +- The name of the file that contains the module primary interface is generally the name of the module. For example, given the module name `BasicPlane.Figures`, the name of the file containing the primary interface would be named *`BasicPlane.Figures.ixx`*. +- The name of a module partition file is generally `-` where the name of the module is followed by a hyphen ('-') and then the name of the partition. For example, *`BasicPlane.Figures-Rectangle.ixx`* -If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler will look for them automatically based on the name of the module. The name of the compiled partition file (ending with an *`.ifc`* extension) is generated implicitly from the module name. Consider the module name `BasicPlane.Figures:Rectangle`. The compiler will anticipate that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to ease using module partitions by automatically finding the interface unit files for partitions. +If you're building from the command line and you use this naming convention for module partitions, then you won't have to explicitly add `/reference` for each module partition file. The compiler looks for them automatically based on the name of the module. The name of the compiled partition file is generated from the module name and ends in *`.ifc`*. Consider the module name `BasicPlane.Figures:Rectangle`: the compiler anticipates that the corresponding compiled partition file for `Rectangle` is named `BasicPlane.Figures-Rectangle.ifc`. The compiler uses this naming scheme to make it easier to use module partitions by automatically finding the interface unit files for partitions. -Or, you can name them using your own convention. But then you'll need to specify corresponding [`/reference`](../build/reference/module-reference.md) arguments to the command-line compiler. +You can name them using your own convention. But then you'll need to specify corresponding [`/reference`](../build/reference/module-reference.md) arguments to the command-line compiler. -### Module factoring +### Factor modules Use module implementation files and partitions to factor your module for easier code maintenance and potentially faster compilation times. @@ -365,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. These files factor the module and present an API to the files that import it. +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 0d6fb436b4b..08ae5ed19c0 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 +ms.topic: "concept-article" --- # 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 51a91196c12..65843208264 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 06ffeb8a997..ebe06ae194b 100644 --- a/docs/cpp/typeid-operator.md +++ b/docs/cpp/typeid-operator.md @@ -5,7 +5,7 @@ ms.date: "10/04/2019" helpviewer_keywords: ["typeid operator"] ms.assetid: 8871cee6-d6b9-4301-a5cb-bf3dc9798d61 --- -# typeid Operator +# `typeid` Operator ## Syntax @@ -26,9 +26,9 @@ The **`typeid`** operator does a run-time check when applied to an l-value of a - A reference to a class -- A pointer, dereferenced with `*` +- A pointer, dereferenced with **`*`** -- A subscripted pointer (`[ ]`). (It's not safe to use a subscript with a pointer to a polymorphic type.) +- A subscripted pointer (**`[ ]`**). (It's not safe to use a subscript with a pointer to a polymorphic type.) If the *expression* points to a base class type, yet the object is actually of a type derived from that base class, a `type_info` reference for the derived class is the result. The *expression* must point to a polymorphic type (a class with virtual functions). Otherwise, the result is the `type_info` for the static class referred to in the *expression*. Further, the pointer must be dereferenced so that the object used is the one it points to. Without dereferencing the pointer, the result will be the `type_info` for the pointer, not what it points to. For example: diff --git a/docs/cpp/typename.md b/docs/cpp/typename.md index 602d1d0de4b..60273a3ddb8 100644 --- a/docs/cpp/typename.md +++ b/docs/cpp/typename.md @@ -1,26 +1,24 @@ --- description: "Learn more about: typename" title: "typename" -ms.date: "11/04/2016" +ms.date: 09/27/2022 f1_keywords: ["typename_cpp"] helpviewer_keywords: ["typename template specifier"] ms.assetid: 52e1d901-220d-4f0d-ab43-dae7e05fb491 --- -# typename +# `typename` -In template definitions, provides a hint to the compiler that an unknown identifier is a type. In template parameter lists, is used to specify a type parameter. +In template definitions, **`typename`** provides a hint to the compiler that an unknown identifier is a type. In template parameter lists, it's used to specify a type parameter. ## Syntax -``` -typename identifier; -``` +> **`typename`** *`identifier`***`;`** ## Remarks -This keyword must be used if a name in a template definition is a qualified name that is dependent on a template argument; it is optional if the qualified name is not dependent. For more information, see [Templates and Name Resolution](../cpp/templates-and-name-resolution.md). +The **`typename`** keyword must be used if a name in a template definition is a qualified name that is dependent on a template argument; it's optional if the qualified name isn't dependent. For more information, see [Templates and Name Resolution](../cpp/templates-and-name-resolution.md). -**`typename`** can be used by any type anywhere in a template declaration or definition. It is not allowed in the base class list, unless as a template argument to a template base class. +**`typename`** can be used by any type anywhere in a template declaration or definition. It isn't allowed in the base class list, unless as a template argument to a template base class. ```cpp template @@ -54,5 +52,5 @@ int main() ## See also -[Templates](../cpp/templates-cpp.md)
+[Templates](../cpp/templates-cpp.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/unaligned.md b/docs/cpp/unaligned.md index ab25505fd0f..9892e057476 100644 --- a/docs/cpp/unaligned.md +++ b/docs/cpp/unaligned.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: __unaligned" title: "__unaligned" -ms.date: "12/17/2018" +description: "Learn more about: __unaligned" +ms.date: 12/17/2018 f1_keywords: ["__unaligned_cpp", "__unaligned", "_unaligned"] helpviewer_keywords: ["__unaligned keyword [C++]"] --- 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 7aec830b643..16c5a8ce9d8 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,25 +15,21 @@ 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. -**Microsoft Specific** - Unary negation of unsigned quantities is performed by subtracting the value of the operand from 2^n, where n is the number of bits in an object of the given unsigned type. -**END Microsoft Specific** - ## 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 c281450fafc..146b6502e07 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 1ea4ddf6dcb..5ee20502c57 100644 --- a/docs/cpp/unions.md +++ b/docs/cpp/unions.md @@ -4,7 +4,6 @@ description: "A description of the Standard C++ union class-type and keyword, it ms.date: "08/18/2020" f1_keywords: ["union_cpp"] helpviewer_keywords: ["class type [C++], union as", "union keyword [C++]"] -ms.assetid: 25c4e219-fcbb-4b7b-9b64-83f3252a92ca no-loc: ["union", "struct", "enum", "class", "static"] --- # `union` @@ -14,7 +13,7 @@ no-loc: ["union", "struct", "enum", "class", "static"] A **`union`** is a user-defined type in which all members share the same memory location. This definition means that at any given time, a union can contain no more than one object from its list of members. It also means that no matter how many members a union has, it always uses only enough memory to store the largest member. -A union can be useful for conserving memory when you have lots of objects and limited memory. However, a union requires extra care to use correctly. You're responsible for ensuring that you always access the same member you assigned. If any member types have a non-trivial constructor, then you must write additional code to explicitly construct and destroy that member. Before you use a union, consider whether the problem you're trying to solve could be better expressed by using a base class and derived class types. +A union can be useful for conserving memory when you have lots of objects and limited memory. However, a union requires extra care to use correctly. You're responsible for ensuring that you always access the same member you assigned. If any member types have a nontrivial constructor, then you must write code to explicitly construct and destroy that member. Before you use a union, consider whether the problem you're trying to solve could be better expressed by using a base class and derived class types. ## Syntax @@ -22,10 +21,10 @@ A union can be useful for conserving memory when you have lots of objects and li ### Parameters -*`tag`*
+*`tag`*\ The type name given to the union. -*`member-list`*
+*`member-list`*\ Members that the union can contain. ## Declare a union @@ -144,7 +143,7 @@ It's easy to misuse the `Input` struct in the example. It's up to the user to us ## Unrestricted union (C++11) -In C++03 and earlier, a union can contain non-static data members that have a class type, as long as the type has no user provided constructors, destructors, or assignment operators. In C++11, these restrictions are removed. If you include such a member in your union, the compiler automatically marks any special member functions that aren't user provided as **`deleted`**. If the union is an anonymous union inside a class or struct, then any special member functions of the class or struct that aren't user provided are marked as **`deleted`**. The following example shows how to handle this case. One of the members of the union has a member that requires this special treatment: +In C++03 and earlier, a union can contain nonstatic data members that have a class type, as long as the type has no user provided constructors, destructors, or assignment operators. In C++11, these restrictions are removed. If you include such a member in your union, the compiler automatically marks any special member functions that aren't user provided as **`deleted`**. If the union is an anonymous union inside a class or struct, then any special member functions of the class or struct that aren't user provided are marked as **`deleted`**. The following example shows how to handle this case. One of the members of the union has a member that requires this special treatment: ```cpp // for MyVariant @@ -504,7 +503,7 @@ int main() } ``` -A union can't store a reference. A union also doesn’t support inheritance. That means you can't use a union as a base class, or inherit from another class, or have virtual functions. +A union can't store a reference. A union also doesn't support inheritance. That means you can't use a union as a base class, or inherit from another class, or have virtual functions. ## Initialize a union @@ -534,10 +533,11 @@ int main() */ ``` -The `NumericType` union is arranged in memory (conceptually) as shown in the following figure. +The `NumericType` union is arranged in memory (conceptually) as shown in the following figure: -![Diagram that shows the overlapping storage of data in a numeric type union.](../cpp/media/vc38ul1.png "Storage of data in a NumericType union")
-Storage of data in a `NumericType` union +:::image type="complex" source="../cpp/media/vc38ul1.png" alt-text="Diagram that shows the overlapping storage of data in the NumericType union."::: +The diagram shows 8 bytes of data. The double type dValue occupies the entire 8 bytes. The type long lValue occupies the first 4 bytes. The short type iValue occupies the first byte. +:::image-end::: ## Anonymous union @@ -547,17 +547,15 @@ An anonymous union is one declared without a *`class-name`* or *`declarator-list Names declared in an anonymous union are used directly, like nonmember variables. It implies that the names declared in an anonymous union must be unique in the surrounding scope. -An anonymous union is subject to these additional restrictions: +An anonymous union is subject to these restrictions: - If declared in file or namespace scope, it must also be declared as **`static`**. - - It can have only **`public`** members; having **`private`** and **`protected`** members in an anonymous union generates errors. - - It can't have member functions. ## See also -[Classes and Structs](../cpp/classes-and-structs-cpp.md)
-[Keywords](../cpp/keywords-cpp.md)
-[`class`](../cpp/class-cpp.md)
+[Classes and Structs](../cpp/classes-and-structs-cpp.md)\ +[Keywords](../cpp/keywords-cpp.md)\ +[`class`](../cpp/class-cpp.md)\ [`struct`](../cpp/struct-cpp.md) diff --git a/docs/cpp/user-defined-literals-cpp.md b/docs/cpp/user-defined-literals-cpp.md index 8261db33e37..3dcac38eb89 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 11e02a7c90b..e6628b991e5 100644 --- a/docs/cpp/uuidof-operator.md +++ b/docs/cpp/uuidof-operator.md @@ -70,5 +70,5 @@ StringFromCLSID(__LIBID_, &lpolestr); ## See also -[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)
+[Expressions with Unary Operators](../cpp/expressions-with-unary-operators.md)\ [Keywords](../cpp/keywords-cpp.md) diff --git a/docs/cpp/value-types-modern-cpp.md b/docs/cpp/value-types-modern-cpp.md index 942388464b4..8178c483c4a 100644 --- a/docs/cpp/value-types-modern-cpp.md +++ b/docs/cpp/value-types-modern-cpp.md @@ -2,7 +2,7 @@ description: "Learn more about: C++ classes as value types" title: "C++ classes as value types" ms.date: 06/09/2022 -ms.topic: "conceptual" +ms.topic: "concept-article" ms.assetid: f63bb62c-60da-40d5-ac14-4366608fe260 --- # C++ classes as value types @@ -99,7 +99,7 @@ public: If you enable copy construction/assignment, also enable move construction/assignment if it can be cheaper than a deep copy. -Some *non-value* types are move-only, such as when you can’t clone a resource, only transfer ownership. Example: `unique_ptr`. +Some *non-value* types are move-only, such as when you can't clone a resource, only transfer ownership. Example: `unique_ptr`. ## See also diff --git a/docs/cpp/variant-t-variant-t.md b/docs/cpp/variant-t-variant-t.md index 48f311b9eb8..cc8b1633389 100644 --- a/docs/cpp/variant-t-variant-t.md +++ b/docs/cpp/variant-t-variant-t.md @@ -171,7 +171,7 @@ A `BYTE` value to be copied into the new `_variant_t` object. A **`char`** value to be copied into the new `_variant_t` object. *`usSrc`*\ -A **`unsigned short`** value to be copied into the new `_variant_t` object. +An **`unsigned short`** value to be copied into the new `_variant_t` object. *`ulSrc`*\ A **`unsigned long`** value to be copied into the new `_variant_t` object. diff --git a/docs/cpp/vectorcall.md b/docs/cpp/vectorcall.md index 7fe02662530..54209c78efd 100644 --- a/docs/cpp/vectorcall.md +++ b/docs/cpp/vectorcall.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: __vectorcall" title: "__vectorcall" -ms.date: "12/17/2018" +description: "Learn more about: __vectorcall" +ms.date: 12/17/2018 f1_keywords: ["__vectorcall_cpp", "__vectorcall", "_vectorcall"] helpviewer_keywords: ["__vectorcall keyword", "__vectorcall"] -ms.assetid: 1c95ed59-86c6-4857-b4ed-10519193f851 --- # __vectorcall @@ -21,7 +20,7 @@ Using the [`/Gv`](../build/reference/gd-gr-gv-gz-calling-convention.md) compiler You can pass three kinds of arguments by register in **`__vectorcall`** functions: *integer type* values, *vector type* values, and *homogeneous vector aggregate* (HVA) values. -An integer type satisfies two requirements: it fits in the native register size of the processor—for example, 4 bytes on an x86 machine or 8 bytes on an x64 machine—and it’s convertible to an integer of register length and back again without changing its bit representation. For example, any type that can be promoted to **`int`** on x86 (**`long long`** on x64)—for example, a **`char`** or **`short`**—or that can be cast to **`int`** (**`long long`** on x64) and back to its original type without change is an integer type. Integer types include pointer, reference, and **`struct`** or **`union`** types of 4 bytes (8 bytes on x64) or less. On x64 platforms, larger **`struct`** and **`union`** types are passed by reference to memory allocated by the caller; on x86 platforms, they are passed by value on the stack. +An integer type satisfies two requirements: it fits in the native register size of the processor—for example, 4 bytes on an x86 machine or 8 bytes on an x64 machine—and it's convertible to an integer of register length and back again without changing its bit representation. For example, any type that can be promoted to **`int`** on x86 (**`long long`** on x64)—for example, a **`char`** or **`short`**—or that can be cast to **`int`** (**`long long`** on x64) and back to its original type without change is an integer type. Integer types include pointer, reference, and **`struct`** or **`union`** types of 4 bytes (8 bytes on x64) or less. On x64 platforms, larger **`struct`** and **`union`** types are passed by reference to memory allocated by the caller; on x86 platforms, they are passed by value on the stack. A vector type is either a floating-point type—for example, a **`float`** or **`double`**—or an SIMD vector type—for example, **`__m128`** or **`__m256`**. @@ -35,7 +34,7 @@ typedef struct { } hva3; // 3 element HVA type on __m256 ``` -Declare your functions explicitly with the **`__vectorcall`** keyword in header files to allow separately compiled code to link without errors. Functions must be prototyped to use **`__vectorcall`**, and can’t use a `vararg` variable length argument list. +Declare your functions explicitly with the **`__vectorcall`** keyword in header files to allow separately compiled code to link without errors. Functions must be prototyped to use **`__vectorcall`**, and can't use a `vararg` variable length argument list. A member function may be declared by using the **`__vectorcall`** specifier. The hidden **`this`** pointer is passed by register as the first integer type argument. @@ -73,7 +72,7 @@ For compatibility with previous versions, **`_vectorcall`** is a synonym for **` The **`__vectorcall`** calling convention on x64 extends the standard x64 calling convention to take advantage of additional registers. Both integer type arguments and vector type arguments are mapped to registers based on position in the argument list. HVA arguments are allocated to unused vector registers. -When any of the first four arguments in order from left to right are integer type arguments, they are passed in the register that corresponds to that position—RCX, RDX, R8, or R9. A hidden **`this`** pointer is treated as the first integer type argument. When an HVA argument in one of the first four arguments can’t be passed in the available registers, a reference to caller-allocated memory is passed in the corresponding integer type register instead. Integer type arguments after the fourth parameter position are passed on the stack. +When any of the first four arguments in order from left to right are integer type arguments, they are passed in the register that corresponds to that position—RCX, RDX, R8, or R9. A hidden **`this`** pointer is treated as the first integer type argument. When an HVA argument in one of the first four arguments can't be passed in the available registers, a reference to caller-allocated memory is passed in the corresponding integer type register instead. Integer type arguments after the fourth parameter position are passed on the stack. When any of the first six arguments in order from left to right are vector type arguments, they are passed by value in SSE vector registers 0 to 5 according to argument position. Floating-point and **`__m128`** types are passed in XMM registers, and **`__m256`** types are passed in YMM registers. This differs from the standard x64 calling convention, because the vector types are passed by value instead of by reference, and additional registers are used. The shadow stack space allocated for vector type arguments is fixed at 8 bytes, and the [`/homeparams`](../build/reference/homeparams-copy-register-parameters-to-stack.md) option does not apply. Vector type arguments in the seventh and later parameter positions are passed on the stack by reference to memory allocated by the caller. diff --git a/docs/cpp/virtual-functions.md b/docs/cpp/virtual-functions.md index 665db8ecdf3..308dcd25756 100644 --- a/docs/cpp/virtual-functions.md +++ b/docs/cpp/virtual-functions.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Virtual Functions" title: "Virtual Functions" -ms.date: "09/10/2019" -helpviewer_keywords: ["functions [C++], virtual functions", "derived classes [C++], virtual functions", "virtual functions"] -ms.assetid: b3e1ed88-2a90-4af8-960a-16f47deb3452 +description: "Learn more about: Virtual Functions" +ms.date: 09/10/2019 adobe-target: true +helpviewer_keywords: ["functions [C++], virtual functions", "derived classes [C++], virtual functions", "virtual functions"] --- # Virtual Functions @@ -137,7 +136,7 @@ Because virtual functions are called only for objects of class types, you cannot The **`virtual`** keyword can be used when declaring overriding functions in a derived class, but it is unnecessary; overrides of virtual functions are always virtual. -Virtual functions in a base class must be defined unless they are declared using the *pure-specifier*. (For more information about pure virtual functions, see [Abstract Classes](../cpp/abstract-classes-cpp.md).) +Virtual functions in a base class must be defined unless they are declared using the *pure-specifier*. For more information about pure virtual functions, see [Abstract Classes](../cpp/abstract-classes-cpp.md). The virtual function-call mechanism can be suppressed by explicitly qualifying the function name using the scope-resolution operator (`::`). Consider the earlier example involving the `Account` class. To call `PrintBalance` in the base class, use code such as the following: diff --git a/docs/cpp/void-cpp.md b/docs/cpp/void-cpp.md index 9d991fdb273..b53334fff27 100644 --- a/docs/cpp/void-cpp.md +++ b/docs/cpp/void-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: void (C++)" title: "void (C++)" -ms.date: 10/15/2021 +ms.date: 12/13/2022 f1_keywords: ["void_cpp"] helpviewer_keywords: ["void keyword [C++]", "functions [C++], void", "pointers, void"] ms.assetid: d203edba-38e6-4056-8b89-011437351057 @@ -16,16 +16,26 @@ In C++, a **`void`** pointer can point to a free function (a function that's not You can't declare a variable of type **`void`**. +As a matter of style, the C++ Core Guidelines recommend you don't use **`void`** to specify an empty formal parameter list. For more information, see [C++ Core Guidelines NL.25: Don't use `void` as an argument type](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#nl25-dont-use-void-as-an-argument-type). + ## Example ```cpp // void.cpp + +void return_nothing() +{ + // A void function can have a return with no argument, + // or no return statement. +} + void vobject; // C2182 void *pv; // okay int *pint; int i; -int main() { +int main() +{ pv = &i; - // Cast optional in C required in C++ + // Cast is optional in C, required in C++ pint = (int *)pv; } ``` diff --git a/docs/cpp/welcome-back-to-cpp-modern-cpp.md b/docs/cpp/welcome-back-to-cpp-modern-cpp.md index 7751df99960..dad330d014a 100644 --- a/docs/cpp/welcome-back-to-cpp-modern-cpp.md +++ b/docs/cpp/welcome-back-to-cpp-modern-cpp.md @@ -2,8 +2,7 @@ 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 +ms.topic: "concept-article" --- # Welcome back to C++ - Modern C++ @@ -37,7 +36,6 @@ void functionUsingWidget() { w.do_something(); // ... } // automatic destruction and deallocation for w and w.data - ``` Whenever possible, use a smart pointer to manage heap memory. If you must use the **`new`** and **`delete`** operators explicitly, follow the principle of RAII. For more information, see [Object lifetime and resource management (RAII)](object-lifetime-and-resource-management-modern-cpp.md). @@ -65,13 +63,10 @@ apple_color["Granny Smith"] = "Green"; When performance optimization is needed, consider using: -- The [`array`](../standard-library/array-class-stl.md) type when embedding is important, for example, as a class member. - - Unordered associative containers such as [`unordered_map`](../standard-library/unordered-map-class.md). These have lower per-element overhead and constant-time lookup, but they can be harder to use correctly and efficiently. - - Sorted `vector`. For more information, see [Algorithms](../standard-library/algorithms.md). -Don’t use C-style arrays. For older APIs that need direct access to the data, use accessor methods such as `f(vec.data(), vec.size());` instead. For more information about containers, see [C++ Standard Library Containers](../standard-library/stl-containers.md). +Don't use C-style arrays. For older APIs that need direct access to the data, use accessor methods such as `f(vec.data(), vec.size());` instead. For more information about containers, see [C++ Standard Library Containers](../standard-library/stl-containers.md). ## Standard Library algorithms @@ -80,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 cf3e4b37814..dfa69fb7dfb 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/attributes-c-cx.md b/docs/cppcx/attributes-c-cx.md index 38b2c2a6ec3..f7c87dca2b2 100644 --- a/docs/cppcx/attributes-c-cx.md +++ b/docs/cppcx/attributes-c-cx.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Attributes (C++/CX)" title: "Attributes (C++/CX)" -ms.date: "12/30/2016" -ms.assetid: 4438e03c-4de3-433d-abcc-31aa863bc0e0 +description: "Learn more about: Attributes (C++/CX)" +ms.date: 12/30/2016 --- # Attributes (C++/CX) -An attribute is a special kind of ref class that can be prepended in square brackets to Windows Runtime types and methods to specify certain behaviors in metadata creation. Several predefined attributes—for example, [Windows::Foundation::Metadata::WebHostHidden](/uwp/api/windows.foundation.metadata.webhosthiddenattribute)—are commonly used in C++/CX code. This example shows how the attribute is applied to a class: +An attribute is a special kind of ref class that can be prepended in square brackets to Windows Runtime types and methods to specify certain behaviors in metadata creation. Several predefined attributes—for example, [Windows::Foundation::Metadata::WebHostHidden](/uwp/api/windows.foundation.metadata.webhosthiddenattribute)—are commonly used in C++/CX code. This example shows how the attribute is applied to a class: [!code-cpp[cx_attributes#01](../cppcx/codesnippet/CPP/cx_attributes/class1.h#01)] diff --git a/docs/cppcx/back-inserter-function.md b/docs/cppcx/back-inserter-function.md index 7e0f7a15e45..0860f65804f 100644 --- a/docs/cppcx/back-inserter-function.md +++ b/docs/cppcx/back-inserter-function.md @@ -13,7 +13,6 @@ Returns an iterator that is used to insert elements at the end of the specified ## Syntax ``` - template Platform::BackInsertIterator back_inserter(IVector^ v); diff --git a/docs/cppcx/begin-function.md b/docs/cppcx/begin-function.md index f240fa91ddf..dd0749fbe14 100644 --- a/docs/cppcx/begin-function.md +++ b/docs/cppcx/begin-function.md @@ -1,63 +1,58 @@ --- description: "Learn more about: begin Function" title: "begin Function" -ms.date: "01/22/2017" +ms.date: 09/27/2022 f1_keywords: ["collection/Windows::Foundation::Collections::begin"] helpviewer_keywords: ["begin Function"] ms.assetid: 5a44fb33-e247-49fd-b7a1-4a5b42e9e1e4 --- -# begin Function +# `begin` Function Returns an iterator that points to the beginning of a collection that is accessed by the specified interface parameter. ## Syntax -``` - +```cpp template ::Platform::Collections::VectorIterator - begin( - IVector^ v ); + begin(IVector^ v); template ::Platform::Collections::VectorViewIterator - begin( - IVectorView^ v - ); + begin(IVectorView^ v); template ::Platform::Collections::InputIterator - begin( - IIterable^ i ); + begin(IIterable^ i); ``` #### Parameters -*T*
+*`T`*\ A template type parameter. -*v*
-A collection of Vector\ or VectorView\ objects that are accessed by an IVector\ or IVectorView\ interface. +*`v`*\ +A collection of `Vector` or `VectorView` objects that are accessed by an `IVector` or `IVectorView` interface. -*i*
-A collection of arbitrary Windows Runtime objects that are accessed by an IIterable\ interface. +*`i`*\ +A collection of arbitrary Windows Runtime objects that are accessed by an `IIterable` interface. -### Return Value +### Return value An iterator that points to the beginning of the collection. ### Remarks -The first two template functions return iterators, and the third template function returns an input iterator. +The first two function templates return iterators, and the third function template returns an input iterator. -The VectorIterator object that is returned by begin is a proxy iterator that stores elements of type VectorProxy\. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). +The `VectorIterator` object that is returned by `begin` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). ### Requirements **Header:** collection.h -**Namespace:** Windows::Foundation::Collections +**Namespace:** `Windows::Foundation::Collections` ## See also -[Windows::Foundation::Collections Namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) +[`Windows::Foundation::Collections` namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) diff --git a/docs/cppcx/casting-c-cx.md b/docs/cppcx/casting-c-cx.md index 0815789fc4b..621c4ab35d4 100644 --- a/docs/cppcx/casting-c-cx.md +++ b/docs/cppcx/casting-c-cx.md @@ -43,14 +43,14 @@ Use safe_cast if the code does not declare the relationship but you are sure tha // ... A^ obj = ref new Class1(); - // You know that obj’s backing type implements A and B, but - // the compiler can’t tell this by comparing A and B. The run-time type check succeeds. + // You know that obj's backing type implements A and B, but + // the compiler can't tell this by comparing A and B. The run-time type check succeeds. B^ obj2 = safe_cast(obj); ``` ## dynamic_cast -Use **`dynamic_cast`** when you cast an object (more specifically, a hat **^**) to a more derived type, you expect either that the target object might sometimes be **`nullptr`** or that the cast might fail, and you want to handle that condition as a regular code path instead of an exception. For example, in the **Blank App (Universal Windows)** project template, the `OnLaunched` method in app.xaml.cpp uses **`dynamic_cast`** to test whether the app window has content. It's not an error if it doesn’t have content; it is an expected condition. `Windows::Current::Content` is a `Windows::UI::XAML::UIElement` and the conversion is to a `Windows::UI.XAML::Controls::Frame`, which is a more derived type in the inheritance hierarchy. +Use **`dynamic_cast`** when you cast an object (more specifically, a hat **^**) to a more derived type, you expect either that the target object might sometimes be **`nullptr`** or that the cast might fail, and you want to handle that condition as a regular code path instead of an exception. For example, in the **Blank App (Universal Windows)** project template, the `OnLaunched` method in app.xaml.cpp uses **`dynamic_cast`** to test whether the app window has content. It's not an error if it doesn't have content; it is an expected condition. `Windows::Current::Content` is a `Windows::UI::XAML::UIElement` and the conversion is to a `Windows::UI.XAML::Controls::Frame`, which is a more derived type in the inheritance hierarchy. ```cpp void App::OnLaunched(Windows::ApplicationModel::Activation::LaunchActivatedEventArgs^ args) @@ -77,7 +77,7 @@ You can also apply a **`dynamic_cast`** to a tracking reference, but in this cas ## reinterpret_cast -We recommend that you not use [reinterpret_cast](../cpp/reinterpret-cast-operator.md) because neither a compile-time check nor a run-time check is performed. In the worst case, a **`reinterpret_cast`** makes it possible for programming errors to go undetected at development time and cause subtle or catastrophic errors in your program’s behavior. Therefore, we recommend that you use **`reinterpret_cast`** only in those rare cases when you must cast between unrelated types and you know that the cast will succeed. An example of a rare use is to convert a Windows Runtime type to its underlying ABI type—this means that you are taking control of the reference counting for the object. To do this, we recommend that you use the [ComPtr Class](../cpp/com-ptr-t-class.md) smart pointer. Otherwise, you must specifically call Release on the interface. The following example shows how a ref class can be cast to an `IInspectable*`. +We recommend that you not use [reinterpret_cast](../cpp/reinterpret-cast-operator.md) because neither a compile-time check nor a run-time check is performed. In the worst case, a **`reinterpret_cast`** makes it possible for programming errors to go undetected at development time and cause subtle or catastrophic errors in your program's behavior. Therefore, we recommend that you use **`reinterpret_cast`** only in those rare cases when you must cast between unrelated types and you know that the cast will succeed. An example of a rare use is to convert a Windows Runtime type to its underlying ABI type—this means that you are taking control of the reference counting for the object. To do this, we recommend that you use the [ComPtr Class](../cpp/com-ptr-t-class.md) smart pointer. Otherwise, you must specifically call Release on the interface. The following example shows how a ref class can be cast to an `IInspectable*`. ```cpp #include @@ -97,7 +97,7 @@ If you use **`reinterpret_cast`** to convert from one Windows Runtime interface - Conversions between a Windows Runtime interface type and its equivalent ABI type are always safe—that is, `IBuffer^` to `ABI::IBuffer*`. -- A Windows Runtime runtime class should always be converted to `IInspectable*` or its default interface, if that is known. +- A Windows Runtime class should always be converted to `IInspectable*` or its default interface, if that is known. - After you convert to ABI types, you own the lifetime of the type and must follow the COM rules. We recommend that you use `WRL::ComPtr` to simplify lifetime management of ABI pointers. diff --git a/docs/cppcx/codesnippet/CPP/cppcx_strings/class1.cpp b/docs/cppcx/codesnippet/CPP/cppcx_strings/class1.cpp index cdc05a2c214..654cf20fe9e 100644 --- a/docs/cppcx/codesnippet/CPP/cppcx_strings/class1.cpp +++ b/docs/cppcx/codesnippet/CPP/cppcx_strings/class1.cpp @@ -55,11 +55,11 @@ void Test1() if (str1 == str2) { /* ... */ } if (str1->Equals(str2)) { /* ... */ } if (str1 != str2) { /* ... */ } - if (str1 < str2 || str1 > str2) { /* ... */}; + if (str1 < str2 || str1 > str2) { /* ... */ } int result = String::CompareOrdinal(str1, str2); - if(str1 == nullptr) { /* ...*/}; - if(str1->IsEmpty()) { /* ...*/}; + if (str1 == nullptr) { /* ...*/ } + if (str1->IsEmpty()) { /* ...*/ } // Accessing individual characters in a String^ auto it = str1->Begin(); diff --git a/docs/cppcx/codesnippet/CPP/partialclassexample/class1.h b/docs/cppcx/codesnippet/CPP/partialclassexample/class1.h index 52efa84e747..9e8425b3b8f 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/codesnippet/CPP/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation_4.cpp b/docs/cppcx/codesnippet/CPP/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation_4.cpp index d5b8967bfde..9bdeebfd49e 100644 --- a/docs/cppcx/codesnippet/CPP/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation_4.cpp +++ b/docs/cppcx/codesnippet/CPP/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation_4.cpp @@ -252,7 +252,7 @@ MFT_GRAYSCALE_SATURATION (type = double) MFT_GRAYSCALE_CHROMA_ROTATION (type = double) - Rotates the chroma values of each pixel. The attribue value is the angle of + Rotates the chroma values of each pixel. The attribute value is the angle of rotation in degrees. The result is a shift in hue. The effect is implemented by treating the chroma value of each pixel as a vector [u,v], @@ -351,7 +351,7 @@ void TransformChroma(const D2D1::Matrix3x2F& mat, BYTE *pu, BYTE *pv) // // The image conversion functions take the following parameters: // -// mat Transfomation matrix for chroma values. +// mat Transformation matrix for chroma values. // rcDest Destination rectangle. // pDest Pointer to the destination buffer. // lDestStride Stride of the destination buffer, in bytes. diff --git a/docs/cppcx/collections-c-cx.md b/docs/cppcx/collections-c-cx.md index e5de70a968c..2471f4f3bb9 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)" -ms.date: "11/19/2018" -ms.assetid: 914da30b-aac5-4cd7-9da3-a5ac08cdd72c +description: "Learn more about: Collections (C++/CX)" +ms.date: 11/19/2018 --- # Collections (C++/CX) @@ -10,57 +9,57 @@ In a C++/CX program, you can make free use of Standard Template Library (STL) co The Windows Runtime defines the interfaces for collections and related types, and C++/CX provides the concrete C++ implementations in the collection.h header file. This illustration shows the relationships between the collection types: -![Diagram of C plus plus C X inheritance tree for collection types.](../cppcx/media/cppcxcollectionsinheritancetree.png) +![Diagram of C plus plus C X inheritance tree for collection types.](media/cppcxcollectionsinheritancetree.png) -- The [Platform::Collections::Vector class](../cppcx/platform-collections-vector-class.md) resembles the [std::vector class](../standard-library/vector-class.md). +- The [`Platform::Collections::Vector` class](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](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](platform-collections-vectorview-class.md) and [`Platform::Collections::MapView` class](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. +- Iterators are defined in the [`Platform::Collections` Namespace](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`](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. > [!IMPORTANT] - > Proxy iterators `VectorIterator` and `VectorViewIterator` utilize proxy objects `VectoryProxy` and `ArrowProxy` to enable usage with STL containers. For more information, see "VectorProxy elements" later in this article. + > Proxy iterators `VectorIterator` and `VectorViewIterator` utilize proxy objects `VectorProxy` and `ArrowProxy` to enable usage with STL containers. For more information, see [VectorProxy elements](#vectorproxy-elements) later in this article. - The C++/CX collection types support the same thread safety guarantees that STL containers support. -- [Windows::Foundation::Collections::IObservableVector](/uwp/api/windows.foundation.collections.iobservablevector-1) and [Windows::Foundation::Collections::IObservableMap](/uwp/api/windows.foundation.collections.iobservablemap-2) define events that are fired when the collection changes in various ways. By implementing these interfaces, [Platform::Collections::Map](../cppcx/platform-collections-map-class.md) and [Platform::Collections::Vector](../cppcx/platform-collections-vector-class.md) support databinding with XAML collections. For example, if you have a `Vector` that is data-bound to a `Grid`, when you add an item to a collection, the change is reflected in the Grid UI. +- [`Windows::Foundation::Collections::IObservableVector`](/uwp/api/windows.foundation.collections.iobservablevector-1) and [`Windows::Foundation::Collections::IObservableMap`](/uwp/api/windows.foundation.collections.iobservablemap-2) define events that are fired when the collection changes in various ways. By implementing these interfaces, [`Platform::Collections::Map`](platform-collections-map-class.md) and [`Platform::Collections::Vector`](platform-collections-vector-class.md) support databinding with XAML collections. For example, if you have a `Vector` that is data-bound to a `Grid`, when you add an item to a collection, the change is reflected in the Grid UI. ## Vector usage -When your class has to pass a sequence container to another Windows Runtime component, use [Windows::Foundation::Collections:: IVector\](/uwp/api/windows.foundation.collections.ivector-1) as the parameter or return type, and [Platform::Collections::Vector\](../cppcx/platform-collections-vector-class.md) as the concrete implementation. If you attempt to use a `Vector` type in a public return value or parameter, compiler error C3986 will be raised. You can fix the error by changing the `Vector` to an `IVector`. +When your class has to pass a sequence container to another Windows Runtime component, use [`Windows::Foundation::Collections::IVector`](/uwp/api/windows.foundation.collections.ivector-1) as the parameter or return type, and [`Platform::Collections::Vector`](platform-collections-vector-class.md) as the concrete implementation. If you attempt to use a `Vector` type in a public return value or parameter, compiler error C3986 will be raised. You can fix the error by changing the `Vector` to an `IVector`. > [!IMPORTANT] > If you are passing a sequence within your own program, then use either `Vector` or `std::vector` because they are more efficient than `IVector`. Use `IVector` only when you pass the container across the ABI. > > The Windows Runtime type system does not support the concept of jagged arrays and therefore you cannot pass an `IVector>` as a return value or method parameter. To pass a jagged array or a sequence of sequences across the ABI, use `IVector^>`. -`Vector` provides the methods that are required for adding, removing, and accessing items in the collection, and it is implicitly convertible to `IVector`. You can also use STL algorithms on instances of `Vector`. The following example demonstrates some basic usage. The [begin function](../cppcx/begin-function.md) and [end function](../cppcx/end-function.md) here are from the `Platform::Collections` namespace, not the `std` namespace. +`Vector` provides the methods that are required for adding, removing, and accessing items in the collection, and it is implicitly convertible to `IVector`. You can also use STL algorithms on instances of `Vector`. The following example demonstrates some basic usage. The [`begin` function](begin-function.md) and [`end` function](end-function.md) here are from the `Platform::Collections` namespace, not the `std` namespace. -[!code-cpp[cx_collections#01](../cppcx/codesnippet/CPP/collections/class1.cpp#01)] +[!code-cpp[cx_collections#01](codesnippet/CPP/collections/class1.cpp#01)] If you have existing code that uses `std::vector` and you want to reuse it in a Windows Runtime component, just use one of the `Vector` constructors that takes a `std::vector` or a pair of iterators to construct a `Vector` at the point where you pass the collection across the ABI. The following example shows how to use the `Vector` move constructor for efficient initialization from a `std::vector`. After the move operation, the original `vec` variable is no longer valid. -[!code-cpp[cx_collections#02](../cppcx/codesnippet/CPP/collections/class1.cpp#02)] +[!code-cpp[cx_collections#02](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 -Any element to be stored in a [Platform::Collections::Vector](../cppcx/platform-collections-vector-class.md) must support equality comparison, either implicitly or by using a custom [std::equal_to](../standard-library/equal-to-struct.md) comparator that you provide. All reference types and all scalar types implicitly support equality comparisons. For non-scalar value types such as [Windows::Foundation::DateTime](/uwp/api/windows.foundation.datetime), or for custom comparisons—for example, `objA->UniqueID == objB->UniqueID`—you must provide a custom function object. +Any element to be stored in a [`Platform::Collections::Vector`](platform-collections-vector-class.md) must support equality comparison, either implicitly or by using a custom [`std::equal_to`](../standard-library/equal-to-struct.md) comparator that you provide. All reference types and all scalar types implicitly support equality comparisons. For non-scalar value types such as [`Windows::Foundation::DateTime`](/uwp/api/windows.foundation.datetime), or for custom comparisons—for example, `objA->UniqueID == objB->UniqueID`—you must provide a custom function object. ## VectorProxy elements -[Platform::Collections::VectorIterator](../cppcx/platform-collections-vectoriterator-class.md) and [Platform::Collections::VectorViewIterator](../cppcx/platform-collections-vectorviewiterator-class.md) enable the use of `range for` loops and algorithms like [std::sort](../standard-library/algorithm-functions.md#sort) with an [IVector\](/uwp/api/windows.foundation.collections.ivector-1) container. But `IVector` elements cannot be accessed through C++ pointer dereference; they can be accessed only through [GetAt](/uwp/api/windows.foundation.collections.ivector-1.getat) and [SetAt](/uwp/api/windows.foundation.collections.ivector-1.setat) methods. Therefore, these iterators use the proxy classes `Platform::Details::VectorProxy` and `Platform::Details::ArrowProxy` to provide access to the individual elements through __\*__, __->__, and __\[]__ operators, as required by the Standard Library. Strictly speaking, given an `IVector vec`, the type of `*begin(vec)` is `VectorProxy`. However, the proxy object is almost always transparent to your code. These proxy objects are not documented because they are only for internal use by the iterators, but it is useful to know how the mechanism works. +[`Platform::Collections::VectorIterator`](platform-collections-vectoriterator-class.md) and [`Platform::Collections::VectorViewIterator`](platform-collections-vectorviewiterator-class.md) enable the use of `range for` loops and algorithms like [`std::sort`](../standard-library/algorithm-functions.md#sort) with an [`IVector`](/uwp/api/windows.foundation.collections.ivector-1) container. But `IVector` elements cannot be accessed through C++ pointer dereference; they can be accessed only through [`GetAt`](/uwp/api/windows.foundation.collections.ivector-1.getat) and [`SetAt`](/uwp/api/windows.foundation.collections.ivector-1.setat) methods. Therefore, these iterators use the proxy classes `Platform::Details::VectorProxy` and `Platform::Details::ArrowProxy` to provide access to the individual elements through **`*`**, **`->`**, and **`[]`** operators, as required by the Standard Library. Strictly speaking, given an `IVector vec`, the type of `*begin(vec)` is `VectorProxy`. However, the proxy object is almost always transparent to your code. These proxy objects are not documented because they are only for internal use by the iterators, but it is useful to know how the mechanism works. -When you use a range-based **`for`** loop over `IVector` containers, use `auto&&` to enable the iterator variable to bind correctly to the `VectorProxy` elements. If you use `auto&`, compiler warning [C4239](../error-messages/compiler-warnings/compiler-warning-level-4-c4239.md) is raised and `VectoryProxy` is mentioned in the warning text. +When you use a range-based **`for`** loop over `IVector` containers, use `auto&&` to enable the iterator variable to bind correctly to the `VectorProxy` elements. If you use `auto&`, compiler warning [C4239](../error-messages/compiler-warnings/compiler-warning-level-4-c4239.md) is raised and `VectorProxy` is mentioned in the warning text. The following illustration shows a `range for` loop over an `IVector`. Notice that execution is stopped on the breakpoint on line 64. The **QuickWatch** window shows that the iterator variable `p` is in fact a `VectorProxy` that has `m_v` and `m_i` member variables. However, when you call `GetType` on this variable, it returns the identical type to the `Person` instance `p2`. The takeaway is that although `VectorProxy` and `ArrowProxy` might appear in **QuickWatch**, the debugger certain compiler errors, or other places, you typically don't have to explicitly code for them. -![Screenshot of debugging VectorProxy in a range based for loop.](../cppcx/media/vectorproxy-1.png) +![Screenshot of debugging VectorProxy in a range based for loop.](media/vectorproxy-1.png) -One scenario in which you have to code around the proxy object is when you have to perform a **`dynamic_cast`** on the elements—for example, when you are looking for XAML objects of a particular type in a `UIElement` element collection. In this case, you must first cast the element to [Platform::Object](../cppcx/platform-object-class.md)^ and then perform the dynamic cast: +One scenario in which you have to code around the proxy object is when you have to perform a **`dynamic_cast`** on the elements—for example, when you are looking for XAML objects of a particular type in a `UIElement` element collection. In this case, you must first cast the element to [`Platform::Object`](platform-object-class.md)^ and then perform the dynamic cast: ```cpp void FindButton(UIElementCollection^ col) @@ -79,67 +78,67 @@ void FindButton(UIElementCollection^ col) ## Map usage -This example shows how to insert items and look them up in a [Platform::Collections::Map](../cppcx/platform-collections-map-class.md), and then return the `Map` as a read-only [Windows::Foundation::Collections::IMapView](/uwp/api/windows.foundation.collections.imapview-2) type. +This example shows how to insert items and look them up in a [`Platform::Collections::Map`](platform-collections-map-class.md), and then return the `Map` as a read-only [`Windows::Foundation::Collections::IMapView`](/uwp/api/windows.foundation.collections.imapview-2) type. -[!code-cpp[cx_collections#04](../cppcx/codesnippet/CPP/collections/class1.cpp#04)] +[!code-cpp[cx_collections#04](codesnippet/CPP/collections/class1.cpp#04)] -In general, for internal map functionality, prefer the `std::map` type for performance reasons. If you have to pass the container across the ABI, construct a [Platform::Collections::Map](../cppcx/platform-collections-map-class.md) from the [std::map](../standard-library/map-class.md) and return the `Map` as an [Windows::Foundation::Collections::IMap](/uwp/api/windows.foundation.collections.imap-2). If you attempt to use a `Map` type in a public return value or parameter, compiler error C3986 will be raised. You can fix the error by changing the `Map` to an `IMap`. In some cases—for example, if you are not making a large number of lookups or insertions, and you are passing the collection across the ABI frequently—it might be less expensive to use `Platform::Collections::Map` from the beginning and avoid the cost of converting the `std::map`. In any case, avoid lookup and insert operations on an `IMap` because these are the least performant of the three types. Convert to `IMap` only at the point that you pass the container across the ABI. +In general, for internal map functionality, prefer the `std::map` type for performance reasons. If you have to pass the container across the ABI, construct a [`Platform::Collections::Map`](platform-collections-map-class.md) from the [`std::map`](../standard-library/map-class.md) and return the `Map` as an [`Windows::Foundation::Collections::IMap`](/uwp/api/windows.foundation.collections.imap-2). If you attempt to use a `Map` type in a public return value or parameter, compiler error C3986 will be raised. You can fix the error by changing the `Map` to an `IMap`. In some cases—for example, if you are not making a large number of lookups or insertions, and you are passing the collection across the ABI frequently—it might be less expensive to use `Platform::Collections::Map` from the beginning and avoid the cost of converting the `std::map`. In any case, avoid lookup and insert operations on an `IMap` because these are the least performant of the three types. Convert to `IMap` only at the point that you pass the container across the ABI. ## Value types in Map -Elements in a [Platform::Collections::Map](../cppcx/platform-collections-map-class.md) are ordered. Any element to be stored in a `Map` must support less-than comparison with strict weak ordering, either implicitly or by using a custom [stl::less](../standard-library/less-struct.md) comparator that you provide. Scalar types support the comparison implicitly. For non-scalar value types such as `Windows::Foundation::DateTime`, or for custom comparisons—for example, `objA->UniqueID < objB->UniqueID`—you must provide a custom comparator. +Elements in a [`Platform::Collections::Map`](platform-collections-map-class.md) are ordered. Any element to be stored in a `Map` must support less-than comparison with strict weak ordering, either implicitly or by using a custom [`std::less`](../standard-library/less-struct.md) comparator that you provide. Scalar types support the comparison implicitly. For non-scalar value types such as `Windows::Foundation::DateTime`, or for custom comparisons—for example, `objA->UniqueID < objB->UniqueID`—you must provide a custom comparator. ## Collection types Collections fall into four categories: modifiable versions and read-only versions of sequence collections and associative collections. In addition, C++/CX enhances collections by providing three iterator classes that simplify the accessing of collections. -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. +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`](platform-collections-vector-class.md) or [`Platform::Collections::VectorView`](platform-collections-vectorview-class.md) collection can be accessed by using an iterator or the collection's [`Vector::GetAt`](platform-collections-vector-class.md#getat) and an index. Elements of an associative collection can be accessed by using the collection's [`Map::Lookup`](platform-collections-map-class.md#lookup) and a key. -[Platform::Collections::Map Class](../cppcx/platform-collections-map-class.md)
+[`Platform::Collections::Map` class](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. +`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](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](platform-collections-vector-class.md)\ +A modifiable sequence collection. `Vector` supports constant-time random access and amortized-constant-time [`Append`](platform-collections-vector-class.md#append) operations. -[Platform::Collections::VectorView Class](../cppcx/platform-collections-vectorview-class.md)
+[`Platform::Collections::VectorView` class](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](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](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)
-An STL iterator that satisfies the requirements of an STL **`const`** random-access iterator. +[`Platform::Collections::VectorViewIterator` class](platform-collections-vectorviewiterator-class.md)\ +An STL iterator that satisfies the requirements of an STL **`const`** random-access iterator. ### begin() and end() functions -To simplify the use of the STL to process `Vector`, `VectorView`, `Map`, `MapView`, and arbitrary `Windows::Foundation::Collections` objects, C++/CX supports overloads of the [begin Function](../cppcx/begin-function.md) and [end Function](../cppcx/end-function.md) non-member functions. +To simplify the use of the STL to process `Vector`, `VectorView`, `Map`, `MapView`, and arbitrary `Windows::Foundation::Collections` objects, C++/CX supports overloads of the [`begin` Function](begin-function.md) and [`end` Function](end-function.md) non-member functions. The following table lists the available iterators and functions. |Iterators|Functions| |---------------|---------------| -|[Platform::Collections::VectorIterator\](../cppcx/platform-collections-vectoriterator-class.md)

(Internally stores [Windows::Foundation::Collections:: IVector\](/uwp/api/windows.foundation.collections.ivector-1) and int.)|[begin](../cppcx/begin-function.md)/ [end](../cppcx/end-function.md)([Windows::Foundation::Collections:: IVector\](/uwp/api/windows.foundation.collections.ivector-1))| -|[Platform::Collections::VectorViewIterator\](../cppcx/platform-collections-vectorviewiterator-class.md)

(Internally stores [IVectorView\](/uwp/api/windows.foundation.collections.ivectorview-1)^ and int.)|[begin](../cppcx/begin-function.md)/ [end](../cppcx/end-function.md) ([IVectorView\](/uwp/api/windows.foundation.collections.ivectorview-1)^)| -|[Platform::Collections::InputIterator\](../cppcx/platform-collections-inputiterator-class.md)

(Internally stores [IIterator\](/uwp/api/windows.foundation.collections.iiterator-1)^ and T.)|[begin](../cppcx/begin-function.md)/ [end](../cppcx/end-function.md) ([IIterable\](/uwp/api/windows.foundation.collections.iiterable-1))| -|[Platform::Collections::InputIterator^>](../cppcx/platform-collections-inputiterator-class.md)

(Internally stores [IIterator\](/uwp/api/windows.foundation.collections.iiterator-1)^ and T.)|[begin](../cppcx/begin-function.md)/ [end](../cppcx/end-function.md) ([IMap\](/uwp/api/windows.foundation.collections.imap-2).| -|[Platform::Collections::InputIterator^>](../cppcx/platform-collections-inputiterator-class.md)

(Internally stores [IIterator\](/uwp/api/windows.foundation.collections.iiterator-1)^ and T.)|[begin](../cppcx/begin-function.md)/ [end](../cppcx/end-function.md) ([Windows::Foundation::Collections::IMapView](/uwp/api/windows.foundation.collections.imapview-2))| +|[`Platform::Collections::VectorIterator`](platform-collections-vectoriterator-class.md)

(Internally stores [`Windows::Foundation::Collections::IVector`](/uwp/api/windows.foundation.collections.ivector-1) and `int`.)|[`begin`](begin-function.md)/ [`end`](end-function.md)([`Windows::Foundation::Collections::IVector`](/uwp/api/windows.foundation.collections.ivector-1))| +|[`Platform::Collections::VectorViewIterator`](platform-collections-vectorviewiterator-class.md)

(Internally stores [`IVectorView`](/uwp/api/windows.foundation.collections.ivectorview-1)^ and `int`.)|[`begin`](begin-function.md)/ [`end`](end-function.md) ([`IVectorView`](/uwp/api/windows.foundation.collections.ivectorview-1)^)| +|[`Platform::Collections::InputIterator`](platform-collections-inputiterator-class.md)

(Internally stores [`IIterator`](/uwp/api/windows.foundation.collections.iiterator-1)^ and `T`.)|[`begin`](begin-function.md)/ [`end`](end-function.md) ([`IIterable`](/uwp/api/windows.foundation.collections.iiterable-1))| +|[`Platform::Collections::InputIterator^>`](platform-collections-inputiterator-class.md)

(Internally stores [`IIterator`](/uwp/api/windows.foundation.collections.iiterator-1)^ and `T`.)|[`begin`](begin-function.md)/ [`end`](end-function.md) ([`IMap`](/uwp/api/windows.foundation.collections.imap-2))| +|[`Platform::Collections::InputIterator^>`](platform-collections-inputiterator-class.md)

(Internally stores [`IIterator`](/uwp/api/windows.foundation.collections.iiterator-1)^ and `T`.)|[`begin`](begin-function.md)/ [`end`](end-function.md) ([`Windows::Foundation::Collections::IMapView`](/uwp/api/windows.foundation.collections.imapview-2))| ### Collection change events `Vector` and `Map` support databinding in XAML collections by implementing events that occur when a collection object is changed or reset, or when any element of a collection is inserted, removed, or changed. You can write your own types that support databinding, although you cannot inherit from `Map` or `Vector` because those types are sealed. -The [Windows::Foundation::Collections::VectorChangedEventHandler](/uwp/api/windows.foundation.collections.vectorchangedeventhandler-1) and [Windows::Foundation::Collections::MapChangedEventHandler](/uwp/api/windows.foundation.collections.mapchangedeventhandler-2) delegates specify the signatures for event handlers for collection change events. The [Windows::Foundation::Collections::CollectionChange](/uwp/api/windows.foundation.collections.collectionchange) public enum class, and `Platform::Collection::Details::MapChangedEventArgs` and `Platform::Collections::Details::VectorChangedEventArgs` ref classes, store the event arguments to determine what caused the event. The `*EventArgs` types are defined in the `Details` namespace because you don't have to construct or consume them explicitly when you use `Map` or `Vector`. +The [`Windows::Foundation::Collections::VectorChangedEventHandler`](/uwp/api/windows.foundation.collections.vectorchangedeventhandler-1) and [`Windows::Foundation::Collections::MapChangedEventHandler`](/uwp/api/windows.foundation.collections.mapchangedeventhandler-2) delegates specify the signatures for event handlers for collection change events. The [`Windows::Foundation::Collections::CollectionChange`](/uwp/api/windows.foundation.collections.collectionchange) public enum class, and `Platform::Collections::Details::MapChangedEventArgs` and `Platform::Collections::Details::VectorChangedEventArgs` ref classes, store the event arguments to determine what caused the event. The `*EventArgs` types are defined in the `Details` namespace because you don't have to construct or consume them explicitly when you use `Map` or `Vector`. ## See also -[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) +[Type System](type-system-c-cx.md)\ +[C++/CX Language Reference](visual-c-language-reference-c-cx.md)\ +[Namespaces Reference](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 602af8f2765..9291df90ccb 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 1da0f2675b1..3ea53942eb7 100644 --- a/docs/cppcx/delegates-c-cx.md +++ b/docs/cppcx/delegates-c-cx.md @@ -12,13 +12,13 @@ The **`delegate`** keyword is used to declare a reference type that is the Windo public delegate void PrimeFoundHandler(int result); ``` -Delegates are most commonly used in conjunction with events. An event has a delegate type, in much the same way that a class can have an interface type. The delegate represents a contract that event handlers much fulfill. Here’s an event class member whose type is the previously-defined delegate: +Delegates are most commonly used in conjunction with events. An event has a delegate type, in much the same way that a class can have an interface type. The delegate represents a contract that event handlers much fulfill. Here's an event class member whose type is the previously-defined delegate: ```cpp event PrimeFoundHandler^ primeFoundEvent; ``` -When declaring delegates that will be exposed to clients across the Windows Runtime application binary interface, use [Windows::Foundation::TypedEventHandler\](/uwp/api/windows.foundation.typedeventhandler-2). This delegate has predefined proxy and stub binaries that enable it to be consumed by Javascript clients. +When declaring delegates that will be exposed to clients across the Windows Runtime application binary interface, use [Windows::Foundation::TypedEventHandler\](/uwp/api/windows.foundation.typedeventhandler-2). This delegate has predefined proxy and stub binaries that enable it to be consumed by JavaScript clients. ## Consuming delegates @@ -81,7 +81,7 @@ It then calls the member function and passes the delegate. Assume that `ci` is a In the next example, a client app passes a custom delegate to a public method in a Windows Runtime component that executes the delegate against each item in a `Vector`: [!code-cpp[Cx_delegates#118](../cppcx/codesnippet/CPP/clientapp/mainpage.xaml.cpp#118)] - +  [!code-cpp[Cx_delegates#119](../cppcx/codesnippet/CPP/delegatesevents/class1.cpp#119)] ### Construction @@ -105,7 +105,7 @@ The following example shows how to construct a delegate from each of these objec ### Generic delegates -Generic delegates in C++/CX have restrictions similar to declarations of generic classes. They cannot be declared as public. You can declare a private or internal generic delegate and consume it from C++, but .NET or JavaScript clients can’t consume it because it is not emitted into the .winmd metadata. This example declares a generic delegate that can only be consumed by C++: +Generic delegates in C++/CX have restrictions similar to declarations of generic classes. They cannot be declared as public. You can declare a private or internal generic delegate and consume it from C++, but .NET or JavaScript clients can't consume it because it is not emitted into the .winmd metadata. This example declares a generic delegate that can only be consumed by C++: [!code-cpp[Cx_delegates#116](../cppcx/codesnippet/CPP/delegatesevents/class1.h#116)] @@ -123,7 +123,7 @@ If the code that executes the delegate is running on a different thread—for ex If you want your created delegate to be called back on the same thread that it was created on—for example, if you pass it to a component that runs in an MTA apartment—and you want it to be invoked on the same thread as the creator, then use the delegate constructor overload that takes a second `CallbackContext` parameter. Only use this overload on delegates that have a registered proxy/stub; not all of the delegates that are defined in Windows.winmd are registered. -If you are familiar with event handlers in .NET, you know that the recommended practice is to make a local copy of an event before you fire it. This avoids race conditions in which an event handler might be removed just before the event is invoked. It isn’t necessary to do this in C++/CX because when event handlers are added or removed a new handler list is created. Because a C++ object increments the reference count on the handler list before invoking an event, it is guaranteed that all handlers will be valid. However, this also means that if you remove an event handler on the consuming thread, that handler might still get invoked if the publishing object is still operating on its copy of the list, which is now out-of-date. The publishing object will not get the updated list until the next time it fires the event. +If you are familiar with event handlers in .NET, you know that the recommended practice is to make a local copy of an event before you fire it. This avoids race conditions in which an event handler might be removed just before the event is invoked. It isn't necessary to do this in C++/CX because when event handlers are added or removed a new handler list is created. Because a C++ object increments the reference count on the handler list before invoking an event, it is guaranteed that all handlers will be valid. However, this also means that if you remove an event handler on the consuming thread, that handler might still get invoked if the publishing object is still operating on its copy of the list, which is now out-of-date. The publishing object will not get the updated list until the next time it fires the event. ## See also diff --git a/docs/cppcx/deprecating-types-and-members-c-cx.md b/docs/cppcx/deprecating-types-and-members-c-cx.md index 85471b58e54..8c17a5e3a88 100644 --- a/docs/cppcx/deprecating-types-and-members-c-cx.md +++ b/docs/cppcx/deprecating-types-and-members-c-cx.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Deprecating types and members (C++/CX)" title: "Deprecating types and members (C++/CX)" +description: "Learn more about: Deprecating types and members (C++/CX)" ms.date: 01/07/2022 no-loc: [ "class", "delegate", "enum", "field", "interface", "method", "property", "struct" ] --- @@ -13,7 +13,7 @@ C++/CX supports deprecation of Windows Runtime types and members for producers a ## Example -The following example shows how to deprecate your own public APIs—for example, in a Windows Runtime component. The second parameter, of type [`Windows:Foundation::Metadata::DeprecationType`](/uwp/api/windows.foundation.metadata.deprecationtype) specifies whether the API is being deprecated or removed. Currently only the `DeprecationType::Deprecated` value is supported. The third parameter in the attribute specifies the [`Windows::Foundation::Metadata::Platform`](/uwp/api/windows.foundation.metadata.platformattribute) to which the attribute applies. +The following example shows how to deprecate your own public APIs—for example, in a Windows Runtime component. The second parameter, of type [`Windows::Foundation::Metadata::DeprecationType`](/uwp/api/windows.foundation.metadata.deprecationtype) specifies whether the API is being deprecated or removed. Currently only the `DeprecationType::Deprecated` value is supported. The third parameter in the attribute specifies the [`Windows::Foundation::Metadata::Platform`](/uwp/api/windows.foundation.metadata.platformattribute) to which the attribute applies. ```cpp namespace wfm = Windows::Foundation::Metadata; diff --git a/docs/cppcx/dlls-c-cx.md b/docs/cppcx/dlls-c-cx.md index e3ed96ed356..a9d97df533d 100644 --- a/docs/cppcx/dlls-c-cx.md +++ b/docs/cppcx/dlls-c-cx.md @@ -22,7 +22,7 @@ For more information, see [Creating Windows Runtime Components in C++](/windows/ ## Standard DLLs -You can create a standard DLL for C++ code that doesn’t consume or produce public Windows Runtime types and consume it from a UWP app. Use the Dynamic-Link Library (DLL) project type when you just want to migrate an existing DLL to compile in this version of Visual Studio but not convert the code to a Windows Runtime Component project. When you use the following steps, the DLL will be deployed alongside your app executable in the .appx package. +You can create a standard DLL for C++ code that doesn't consume or produce public Windows Runtime types and consume it from a UWP app. Use the Dynamic-Link Library (DLL) project type when you just want to migrate an existing DLL to compile in this version of Visual Studio but not convert the code to a Windows Runtime Component project. When you use the following steps, the DLL will be deployed alongside your app executable in the .appx package. ### To create a standard DLL in Visual Studio diff --git a/docs/cppcx/end-function.md b/docs/cppcx/end-function.md index 6c75d827eb3..dc3a983fb3d 100644 --- a/docs/cppcx/end-function.md +++ b/docs/cppcx/end-function.md @@ -1,63 +1,57 @@ --- description: "Learn more about: end Function" title: "end Function" -ms.date: "01/22/2017" +ms.date: 09/27/2022 f1_keywords: ["collection/Windows::Foundation::Collections::end"] helpviewer_keywords: ["end Function"] ms.assetid: fb837bff-fc76-4bae-9096-facf0e03041c --- -# end Function +# `end` function Returns an iterator that points beyond the end of a collection that is accessed by the specified interface parameter. ## Syntax -``` - +```cpp template ::Platform::Collections::VectorIterator - end( - IVector^ v ); + end(IVector^ v); template ::Platform::Collections::VectorViewIterator - end( - IVectorView^ v - ); + end(IVectorView^ v); template ::Platform::Collections::InputIterator - end( - IIterable^ i - ); + end(IIterable^ i); ``` -#### Parameters +### Parameters -*T*
+*`T`*\ A template type parameter. -*v*
-A collection of Vector\ or VectorView\ objects that are accessed by an IVector\, or IVectorView\ interface. +*`v`*\ +A collection of `Vector` or `VectorView` objects that are accessed by an `IVector`, or `IVectorView` interface. -*i*
-A collection of arbitraty Windows Runtime objects that are accessed by an IIterable\ interface. +*`i`*\ +A collection of arbitrary Windows Runtime objects that are accessed by an `IIterable` interface. -### Return Value +## Return Value An iterator that points beyond the end of the collection. -### Remarks +## Remarks -The first two template functions return iterators, and the third template function returns an input iterator. +The first two function templates return iterators, and the third function template returns an input iterator. -The [Platform::Collections::VectorViewIterator](../cppcx/platform-collections-vectorviewiterator-class.md) object that is returned by `end` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). +The [`Platform::Collections::VectorViewIterator`](../cppcx/platform-collections-vectorviewiterator-class.md) object that is returned by `end` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). -### Requirements +## Requirements **Header:** collection.h -**Namespace:** Windows::Foundation::Collections +**Namespace:** `Windows::Foundation::Collections` ## See also -[Windows::Foundation::Collections Namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) +[`Windows::Foundation::Collections` Namespace](../cppcx/windows-foundation-collections-namespace-c-cx.md) diff --git a/docs/cppcx/enums-c-cx.md b/docs/cppcx/enums-c-cx.md index 964fbe106e0..f0d9e1ff1c9 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 404e0b5d804..d0a5ef857c3 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 4f1bd6c1d8b..47155e3cdb7 100644 --- a/docs/cppcx/fundamental-types-c-cx.md +++ b/docs/cppcx/fundamental-types-c-cx.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Fundamental types (C++/CX)" title: "Fundamental types (C++/CX)" +description: "Learn more about: Fundamental types (C++/CX)" ms.date: "01/22/2017" -ms.assetid: c9f82907-25f2-440b-91d6-afb8dbd46ea6 --- # Fundamental types (C++/CX) -In addition to the standard C++ built-in types, C++/CX supports the type system that's defined by the Windows Runtime architecture by providing typedefs for the Windows Runtime fundamental types that map to standard C++ types.. C++/CX implements Boolean, character, and numeric fundamental types. These typedefs are defined in the `default` namespace, which never needs to be specified explicitly. In addition, C++/CX provides wrappers and concrete implementations for certain Windows Runtime types and interfaces. +In addition to the standard C++ built-in types, C++/CX supports the type system that's defined by the Windows Runtime architecture by providing typedefs for the Windows Runtime fundamental types that map to standard C++ types. C++/CX implements Boolean, character, and numeric fundamental types. These typedefs are defined in the `default` namespace, which never needs to be specified explicitly. In addition, C++/CX provides wrappers and concrete implementations for certain Windows Runtime types and interfaces. ## Boolean and Character Types diff --git a/docs/cppcx/interfaces-c-cx.md b/docs/cppcx/interfaces-c-cx.md index bef57c95d83..eff0d690664 100644 --- a/docs/cppcx/interfaces-c-cx.md +++ b/docs/cppcx/interfaces-c-cx.md @@ -86,7 +86,7 @@ Here's how Windows Runtime types can be used to author a generic interface: - In the interface, any reference to the current interface—in a method parameter, return value, or property—is assumed to refer to the current instantiation. For example, *IMyIntf* means *IMyIntf\*. -- When the type of a method parameter is a type parameter, the declaration of that parameter or variable uses the type parameter’s name without any pointer, native reference, or handle declarators. In other words, you never write "T^". +- When the type of a method parameter is a type parameter, the declaration of that parameter or variable uses the type parameter's name without any pointer, native reference, or handle declarators. In other words, you never write "T^". - Templated ref classes must be private. They can implement generic interfaces, and can pass template parameter *T* to generic argument *T*. Each instantiation of a templated ref class is itself a ref class. diff --git a/docs/cppcx/namespaces-and-type-visibility-c-cx.md b/docs/cppcx/namespaces-and-type-visibility-c-cx.md index 83ed1947d70..c225de9e734 100644 --- a/docs/cppcx/namespaces-and-type-visibility-c-cx.md +++ b/docs/cppcx/namespaces-and-type-visibility-c-cx.md @@ -1,21 +1,20 @@ --- -description: "Learn more about: Namespaces and Type Visibility (C++/CX )" -title: "Namespaces and Type Visibility (C++/CX )" -ms.date: "12/30/2016" -ms.assetid: cbc01a3a-3b69-4ded-9c42-ecbf0fd0a00e +title: "Namespaces and Type Visibility (C++/CX)" +description: "Learn more about: Namespaces and Type Visibility (C++/CX)" +ms.date: 12/30/2016 --- -# Namespaces and Type Visibility (C++/CX ) +# Namespaces and Type Visibility (C++/CX) A namespace is a standard C++ construct for grouping types that have related functionality and for preventing name collisions in libraries. The Windows Runtime type system requires that all public Windows Runtime types, including those in your own code, must be declared in a namespace at namespace scope. Public types that are declared at global scope or nested inside another class will cause a compile-time error. -A .winmd file must have the same name that the root namespace has. For example, a class that's named A.B.C.MyClass can be instantiated only if it's defined in a metadata file that's named A.winmd or A.B.winmd or A.B.C.winmd. The name of the executable is not required to match the .winmd file name. +A `.winmd` file must have the same name that the root namespace has. For example, a class that's named `A.B.C.MyClass` can be instantiated only if it's defined in a metadata file that's named `A.winmd` or `A.B.winmd` or `A.B.C.winmd`. The name of the executable is not required to match the `.winmd` file name. ## Type visibility In a namespace, Windows Runtime types—unlike standard C++ types—have either private or public accessibility. By default, the accessibility is private. Only a public type is visible to metadata and is therefore consumable from apps and components that might be written in languages other than C++. In general, the rules for visible types are more restrictive than the rules for non-visible types because visible types cannot expose C++-specific concepts that are not supported in .NET languages or JavaScript. > [!NOTE] -> Metadata is only consumed at run time by .NET languages and JavaScript. When a C++ app or component is talking to another C++ app or component—this includes Windows components ,which are all written in C++—then no run-time consumption of metadata is required. +> Metadata is only consumed at run time by .NET languages and JavaScript. When a C++ app or component is talking to another C++ app or component—this includes Windows components, which are all written in C++—then no run-time consumption of metadata is required. ## Member accessibility and visibility @@ -34,7 +33,7 @@ Use the following access modifiers to control both metadata visibility and sourc ## Windows Runtime namespaces -The Windows API consists of types that are declared in the Windows::\* namespaces. These namespaces are reserved for Windows, and types cannot be added to them. In the **Object Browser**, you can view these namespaces in the windows.winmd file. For documentation about these namespaces, see [Windows API](/uwp/api/). +The Windows API consists of types that are declared in the `Windows::*` namespaces. These namespaces are reserved for Windows, and types cannot be added to them. In the **Object Browser**, you can view these namespaces in the `windows.winmd` file. For documentation about these namespaces, see [Windows API](/uwp/api/). ## C++/CX namespaces @@ -44,9 +43,9 @@ The C++/CX define certain types in these namespaces as part of the projection of |--|--| | default | Contains the built-in numeric and char16 types. These types are in scope in every namespace and a **`using`** statement is never required. | | `Platform` | Contains primarily public types that correspond to Windows Runtime types such as `Array`, `String`, `Guid`, and `Boolean`. Also includes specialized helper types such as `Platform::Agile` and `Platform::Box`. | -| `Platform::Collections` | Contains the concrete collection classes that implement the Windows Runtime collection interfaces `IVector`, `IMap`, and so on. These types are defined in a header file, collection.h, not in platform.winmd. | +| `Platform::Collections` | Contains the concrete collection classes that implement the Windows Runtime collection interfaces `IVector`, `IMap`, and so on. These types are defined in a header file, `collection.h`, not in `platform.winmd`. | | `Platform::Details` | Contains types that are used by the compiler and are not meant for public consumption. | ## See also -[Type System (C++/CX)](../cppcx/type-system-c-cx.md) +[Type System (C++/CX)](type-system-c-cx.md) diff --git a/docs/cppcx/operator-type-hat.md b/docs/cppcx/operator-type-hat.md index 04b0546b107..238e11d9715 100644 --- a/docs/cppcx/operator-type-hat.md +++ b/docs/cppcx/operator-type-hat.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: operator Type^" title: "operator Type^" -ms.date: "12/30/2016" -ms.assetid: b24ffc83-0780-4f9a-8ee0-f5725db339d1 +description: "Learn more about: operator Type^" +ms.date: 12/30/2016 --- # operator Type^ @@ -20,7 +19,7 @@ Returns a `Platform::Type` when given a [Windows::UI::Xaml::Interop::TypeName](/ ### Remarks -`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can’t be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: +`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can't be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: ``` rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments); @@ -31,7 +30,6 @@ rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments); The next example shows how to convert between `TypeName` and `Type`. ``` - // Convert from Type to TypeName TypeName tn = TypeName(MainPage::typeid); @@ -43,8 +41,6 @@ Type^ tx2 = (Type^)(tn); .NET Framework programs project `TypeName` as -### Requirements - ## See also [operator Windows::UI::Xaml::Interop::TypeName](../cppcx/operator-windows-ui-xaml-interop-typename.md)
diff --git a/docs/cppcx/operator-windows-ui-xaml-interop-typename.md b/docs/cppcx/operator-windows-ui-xaml-interop-typename.md index ea83d67b0de..0e585769a5e 100644 --- a/docs/cppcx/operator-windows-ui-xaml-interop-typename.md +++ b/docs/cppcx/operator-windows-ui-xaml-interop-typename.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: operator Windows::UI::Xaml::Interop::TypeName" title: "operator Windows::UI::Xaml::Interop::TypeName" -ms.date: "12/30/2016" -ms.assetid: a65a105e-7e3a-452f-932f-2cdaf00fbba5 +description: "Learn more about: operator Windows::UI::Xaml::Interop::TypeName" +ms.date: 12/30/2016 --- # operator Windows::UI::Xaml::Interop::TypeName @@ -20,7 +19,7 @@ Returns a [Windows::UI::Xaml::Interop::TypeName](/uwp/api/windows.ui.xaml.intero ### Remarks -`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can’t be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: +`TypeName` is the language-neutral Windows Runtime struct for representing type information. [Platform::Type](../cppcx/platform-type-class.md) is specific to C++ and can't be passed across the application binary interface (ABI). Here's one use of `TypeName`, in the [Navigate](/uwp/api/windows.ui.xaml.controls.frame.navigate) function: ```cpp rootFrame->Navigate(TypeName(MainPage::typeid), e->Arguments); @@ -42,8 +41,6 @@ Type^ tx2 = (Type^)(tn); .NET Framework programs project `TypeName` as [System.Type](/dotnet/api/system.type). -### Requirements - ## See also [operator Windows::UI::Xaml::Interop::TypeName](../cppcx/operator-windows-ui-xaml-interop-typename.md)
diff --git a/docs/cppcx/partial-classes-c-cx.md b/docs/cppcx/partial-classes-c-cx.md index b17036025e1..d6e18b397e6 100644 --- a/docs/cppcx/partial-classes-c-cx.md +++ b/docs/cppcx/partial-classes-c-cx.md @@ -69,7 +69,7 @@ At the point of the full definition of the class X, the behavior is the same as The following two code examples have identical meaning and effect. The first example uses a partial class and the second example doesn't. [!code-cpp[cx_partial#05](../cppcx/codesnippet/CPP/partialclassexample/class1.h#05)] - +  [!code-cpp[cx_partial#06](../cppcx/codesnippet/CPP/partialclassexample/class1.h#06)] ## Templates @@ -87,7 +87,7 @@ The **`partial`** keyword is supported only in combination with the **`ref class The following example defines the `Address` class across two code files. The designer modifies `Address.details.h` and you modify `Address.h`. Only the class definition in the first file uses the **`partial`** keyword. [!code-cpp[cx_partial#07](../cppcx/codesnippet/CPP/partialclassexample/address.details.h#07)] - +  [!code-cpp[cx_partial#09](../cppcx/codesnippet/CPP/partialclassexample/address.h#09)] ## See also diff --git a/docs/cppcx/platform-accessdeniedexception-class.md b/docs/cppcx/platform-accessdeniedexception-class.md index bf6cbaed0b4..cc50d74596c 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 59f73faa71a..26713d7fe98 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-arrayreference-class.md b/docs/cppcx/platform-arrayreference-class.md index 4441c41afba..7925842befc 100644 --- a/docs/cppcx/platform-arrayreference-class.md +++ b/docs/cppcx/platform-arrayreference-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::ArrayReference Class" title: "Platform::ArrayReference Class" -ms.date: "10/16/2019" +description: "Learn more about: Platform::ArrayReference Class" +ms.date: 10/16/2019 ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::ArrayReference::ArrayReference"] helpviewer_keywords: ["Platform::ArrayReference Class"] -ms.assetid: 9ab3b15e-8a60-4600-8fcb-7d6c86284f4b --- # Platform::ArrayReference Class @@ -70,8 +69,6 @@ The number of elements in the source array. *otherArg*
An `ArrayReference` object whose data will be moved to initialize the new instance. -### Remarks - ## ArrayReference::operator= Operator Assigns the specified object to the current [Platform::ArrayReference](../cppcx/platform-arrayreference-class.md) object by using move semantics. diff --git a/docs/cppcx/platform-changedstateexception-class.md b/docs/cppcx/platform-changedstateexception-class.md index b123e94431b..6fc12015009 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 9fa2b993972..0108e2bff66 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 dac7e5cdabe..f2d5367a68e 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 21b981e5f6e..473101cef06 100644 --- a/docs/cppcx/platform-collections-map-class.md +++ b/docs/cppcx/platform-collections-map-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::Collections::Map Class" title: "Platform::Collections::Map Class" -ms.date: "10/01/2019" +description: "Learn more about: Platform::Collections::Map Class" +ms.date: 10/01/2019 ms.topic: "reference" f1_keywords: ["COLLECTION/Platform::Collections::Map::Map", "COLLECTION/Platform::Collections::Map::Clear", "COLLECTION/Platform::Collections::Map::First", "COLLECTION/Platform::Collections::Map::GetView", "COLLECTION/Platform::Collections::Map::HasKey", "COLLECTION/Platform::Collections::Map::Insert", "COLLECTION/Platform::Collections::Map::Lookup", "COLLECTION/Platform::Collections::Map::Remove", "COLLECTION/Platform::Collections::Map::Size"] helpviewer_keywords: ["Map Class (C++/Cx)"] -ms.assetid: 2b8cf968-1167-4898-a149-1195b32c1785 --- # Platform::Collections::Map Class @@ -206,7 +205,7 @@ Initializes a new instance of the Map class. ```cpp explicit Map(const C& comp = C()); explicit Map(const StdMap& m); -explicit Map(StdMap&& m ; +explicit Map(StdMap&& m); template Map( InItfirst, diff --git a/docs/cppcx/platform-collections-mapview-class.md b/docs/cppcx/platform-collections-mapview-class.md index 67ca96405de..2f166b244ed 100644 --- a/docs/cppcx/platform-collections-mapview-class.md +++ b/docs/cppcx/platform-collections-mapview-class.md @@ -90,7 +90,6 @@ Determines whether the current MapView contains the specified key. ### Syntax ``` - bool HasKey(K key); ``` diff --git a/docs/cppcx/platform-collections-namespace.md b/docs/cppcx/platform-collections-namespace.md index f079c117af1..1cffd685219 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 d79f646dd14..a65c9b4d548 100644 --- a/docs/cppcx/platform-collections-unorderedmap-class.md +++ b/docs/cppcx/platform-collections-unorderedmap-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Platform::Collections::UnorderedMap Class" title: "Platform::Collections::UnorderedMap Class" -ms.date: "12/30/2016" +description: "Learn more about: Platform::Collections::UnorderedMap Class" +ms.date: 12/30/2016 ms.topic: "reference" f1_keywords: ["collection/Platform::Collections::UnorderedMap"] -ms.assetid: dc84f261-b13c-4c0a-9b57-30dcb9e3065e --- # Platform::Collections::UnorderedMap Class @@ -30,7 +29,7 @@ The type of the key in the key-value pair. The type of the value in the key-value pair. *C*
-A type that provides a function object that can compare two element values as sort keys to determine their relative order in the Map. By default, [std::equal_to\](../standard-library/equal-to-struct.md). +A type that provides a function object that can compare two element values as sort keys to determine their relative order in the Map. By default, [std::equal_to\](../standard-library/equal-to-struct.md). ### Remarks @@ -46,7 +45,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 +118,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-vector-class.md b/docs/cppcx/platform-collections-vector-class.md index 56d9181e80a..4bb382e37ef 100644 --- a/docs/cppcx/platform-collections-vector-class.md +++ b/docs/cppcx/platform-collections-vector-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::Collections::Vector Class" title: "Platform::Collections::Vector Class" -ms.date: "12/04/2019" +description: "Learn more about: Platform::Collections::Vector Class" +ms.date: 12/04/2019 ms.topic: "reference" f1_keywords: ["COLLECTION/Platform::Collections::Vector::Vector", "COLLECTION/Platform::Collections::Vector::Append", "COLLECTION/Platform::Collections::Vector::Clear", "COLLECTION/Platform::Collections::Vector::First", "COLLECTION/Platform::Collections::Vector::GetAt", "COLLECTION/Platform::Collections::Vector::GetMany", "COLLECTION/Platform::Collections::Vector::GetView", "COLLECTION/Platform::Collections::Vector::IndexOf", "COLLECTION/Platform::Collections::Vector::InsertAt", "COLLECTION/Platform::Collections::Vector::ReplaceAll", "COLLECTION/Platform::Collections::Vector::RemoveAt", "COLLECTION/Platform::Collections::Vector::RemoveAtEnd", "COLLECTION/Platform::Collections::Vector::SetAt", "COLLECTION/Platform::Collections::Vector::Size", "COLLECTION/Platform::Collections::Vector::VectorChanged"] helpviewer_keywords: ["Vector Class (C++/Cx)"] -ms.assetid: aee8c076-9700-47c3-99b6-799fd3edb0ca --- # Platform::Collections::Vector Class @@ -176,7 +175,7 @@ The number of items retrieved. ### Remarks -This function is not intended for use directly by client code. It is used internally in the [to_vector Function](../cppcx/to-vector-function.md) to enable efficient conversion of Platform::Vector intances to std::vector instances. +This function is not intended for use directly by client code. It is used internally in the [to_vector Function](../cppcx/to-vector-function.md) to enable efficient conversion of Platform::Vector instances to std::vector instances. ## Vector::GetView Method diff --git a/docs/cppcx/platform-collections-vectoriterator-class.md b/docs/cppcx/platform-collections-vectoriterator-class.md index f6a5f656603..f7d2ee8c9ff 100644 --- a/docs/cppcx/platform-collections-vectoriterator-class.md +++ b/docs/cppcx/platform-collections-vectoriterator-class.md @@ -1,29 +1,28 @@ --- +title: "Platform::Collections::VectorIterator class" description: "Learn more about: Platform::Collections::VectorIterator Class" -title: "Platform::Collections::VectorIterator Class" ms.date: "03/27/2019" ms.topic: "reference" f1_keywords: ["COLLECTION/Platform::Collections::VectorIterator::VectorIterator"] helpviewer_keywords: ["VectorIterator Class"] -ms.assetid: d531cb42-27e0-48a6-bf5e-c265891a18ff --- -# Platform::Collections::VectorIterator Class +# `Platform::Collections::VectorIterator` class -Provides a Standard Template Library iterator for objects derived from the Windows Runtime IVector interface. +Provides a Standard Template Library iterator for objects derived from the Windows Runtime `IVector` interface. -VectorIterator is a proxy iterator that stores elements of type VectorProxy\. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). +`VectorIterator` is a proxy iterator that stores elements of type `VectorProxy`. However, the proxy object is almost never visible to user code. For more information, see [Collections (C++/CX)](../cppcx/collections-c-cx.md). ## Syntax -``` +```cpp template class VectorIterator; ``` #### Parameters -*T*
-The typename of the VectorIterator template class. +*`T`*\ +The typename of the `VectorIterator` template class. ### Members @@ -31,37 +30,37 @@ The typename of the VectorIterator template class. |Name|Description| |----------|-----------------| -|`difference_type`|A pointer difference (ptrdiff_t).| -|`iterator_category`|The category of a random access iterator (::std::random_access_iterator_tag).| -|`pointer`|A pointer to an internal type, Platform::Collections::Details::VectorProxy\, that is required for the implementation of VectorIterator.| -|`reference`|A reference to an internal type, Platform::Collections::Details::VectorProxy\,, that is required for the implementation of VectorIterator.| +|`difference_type`|A pointer difference (`ptrdiff_t`).| +|`iterator_category`|The category of a random access iterator (`::std::random_access_iterator_tag`).| +|`pointer`|A pointer to an internal type, `Platform::Collections::Details::VectorProxy`, that is required for the implementation of `VectorIterator`.| +|`reference`|A reference to an internal type, `Platform::Collections::Details::VectorProxy`, that is required for the implementation of `VectorIterator`.| |`value_type`|The `T` typename.| -### Public Constructors +### Public constructors |Name|Description| |----------|-----------------| -|[VectorIterator::VectorIterator](#ctor)|Initializes a new instance of the VectorIterator class.| +|[`VectorIterator::VectorIterator`](#ctor)|Initializes a new instance of the `VectorIterator` class.| -### Public Operators +### Public operators |Name|Description| |----------|-----------------| -|[VectorIterator::operator- Operator](#operator-minus)|Subtracts either a specified number of elements from the current iterator yielding a new iterator, or a specified iterator from the current iterator yielding the number of elements between the iterators.| -|[VectorIterator::operator-- Operator](#operator-decrement)|Decrements the current VectorIterator.| -|[VectorIterator::operator!= Operator](#operator-inequality)|Indicates whether the current VectorIterator is not equal to a specified VectorIterator.| -|[VectorIterator::operator* Operator](#operator-dereference)|Retrieves a reference to the element specified by the current VectorIterator.| -|[VectorIterator::operator\[\]](#operator-at)|Retrieves a reference to the element that is a specified displacement from the current VectorIterator.| -|[VectorIterator::operator+ Operator](#operator-plus)|Returns a VectorIterator that references the element at the specified displacement from the specified VectorIterator.| -|[VectorIterator::operator++ Operator](#operator-increment)|Increments the current VectorIterator.| -|[VectorIterator::operator+= Operator](#operator-plus-assign)|Increments the current VectorIterator by the specified displacement.| -|[VectorIterator::operator< Operator](#operator-less-than)|Indicates whether the current VectorIterator is less than a specified VectorIterator.| -|[VectorIterator::operator\<= Operator](#operator-less-than-or-equals)|Indicates whether the current VectorIterator is less than or equal to a specified VectorIterator.| -|[VectorIterator::operator-= Operator](#operator-minus-equals)|Decrements the current VectorIterator by the specified displacement.| -|[VectorIterator::operator== Operator](#operator-equality)|Indicates whether the current VectorIterator is equal to a specified VectorIterator.| -|[VectorIterator::operator> Operator](#operator-greater-than)|Indicates whether the current VectorIterator is greater than a specified VectorIterator.| -|[VectorIterator::operator-> Operator](#operator-arrow)|Retrieves the address of the element referenced by the current VectorIterator.| -|[VectorIterator::operator>= Operator](#operator-greater-than-or-equals)|Indicates whether the current VectorIterator is greater than or equal to a specified VectorIterator.| +|[`VectorIterator::operator-` Operator](#operator-minus)|Subtracts either a specified number of elements from the current iterator yielding a new iterator, or a specified iterator from the current iterator yielding the number of elements between the iterators.| +|[`VectorIterator::operator--` Operator](#operator-decrement)|Decrements the current VectorIterator.| +|[`VectorIterator::operator!=` Operator](#operator-inequality)|Indicates whether the current VectorIterator is not equal to a specified VectorIterator.| +|[`VectorIterator::operator*` Operator](#operator-dereference)|Retrieves a reference to the element specified by the current VectorIterator.| +|[`VectorIterator::operator[]`](#operator-at)|Retrieves a reference to the element that is a specified displacement from the current VectorIterator.| +|[`VectorIterator::operator+` Operator](#operator-plus)|Returns a VectorIterator that references the element at the specified displacement from the specified VectorIterator.| +|[`VectorIterator::operator++` Operator](#operator-increment)|Increments the current VectorIterator.| +|[`VectorIterator::operator+=` Operator](#operator-plus-assign)|Increments the current VectorIterator by the specified displacement.| +|[`VectorIterator::operator<` Operator](#operator-less-than)|Indicates whether the current VectorIterator is less than a specified VectorIterator.| +|[`VectorIterator::operator<=` Operator](#operator-less-than-or-equals)|Indicates whether the current VectorIterator is less than or equal to a specified VectorIterator.| +|[`VectorIterator::operator-=` Operator](#operator-minus-equals)|Decrements the current VectorIterator by the specified displacement.| +|[`VectorIterator::operator==` Operator](#operator-equality)|Indicates whether the current VectorIterator is equal to a specified VectorIterator.| +|[`VectorIterator::operator>` Operator](#operator-greater-than)|Indicates whether the current VectorIterator is greater than a specified VectorIterator.| +|[`VectorIterator::operator->` Operator](#operator-arrow)|Retrieves the address of the element referenced by the current VectorIterator.| +|[`VectorIterator::operator>=` Operator](#operator-greater-than-or-equals)|Indicates whether the current VectorIterator is greater than or equal to a specified VectorIterator.| ## Inheritance Hierarchy @@ -69,84 +68,83 @@ The typename of the VectorIterator template class. ### Requirements -**Header:** collection.h +**Header:** `collection.h` -**Namespace:** Platform::Collections +**Namespace:** `Platform::Collections` -## `VectorIterator::operator->` Operator +## `VectorIterator::operator->` operator Retrieves the address of the element referenced by the current VectorIterator. ### Syntax -``` +```cpp Detail::ArrowProxy operator->() const; ``` ### Return Value -The value of the element that is referenced by the current VectorIterator. +The value of the element that is referenced by the current `VectorIterator`. The type of the return value is an unspecified internal type that is required for the implementation of this operator. -## VectorIterator::operator-- Operator +## `VectorIterator::operator--` operator Decrements the current VectorIterator. ### Syntax -``` - +```cpp VectorIterator& operator--(); VectorIterator operator--(int); ``` ### Return Value -The first syntax decrements and then returns the current VectorIterator. The second syntax returns a copy of the current VectorIterator and then decrements the current VectorIterator. +The first syntax decrements and then returns the current `VectorIterator`. The second syntax returns a copy of the current `VectorIterator` and then decrements the current `VectorIterator`. ### Remarks -The first VectorIterator syntax pre-decrements the current VectorIterator. +The first VectorIterator syntax pre-decrements the current `VectorIterator`. The second syntax post-decrements the current VectorIterator. The **`int`** type in the second syntax indicates a post-decrement operation, not an actual integer operand. -## VectorIterator::operator\* Operator +## `VectorIterator::operator*` operator -Retrieves the address of the element specified by the current VectorIterator. +Retrieves the address of the element specified by the current `VectorIterator`. ### Syntax -``` +```cpp reference operator*() const; ``` ### Return Value -The element specified by the current VectorIterator. +The element specified by the current `VectorIterator`. -## VectorIterator::operator== Operator +## `VectorIterator::operator==` operator -Indicates whether the current VectorIterator is equal to a specified VectorIterator. +Indicates whether the current `VectorIterator` is equal to a specified `VectorIterator`. ### Syntax -``` +```cpp bool operator==(const VectorIterator& other) const; ``` ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value **`true`** if the current VectorIterator is equal to *other*; otherwise, **`false`**. -## `VectorIterator::operator>` Operator +## `VectorIterator::operator>` operator -Indicates whether the current VectorIterator is greater than a specified VectorIterator. +Indicates whether the current `VectorIterator` is greater than a specified `VectorIterator`. ### Syntax @@ -156,16 +154,16 @@ bool operator>(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is greater than *other*; otherwise, **`false`**. +**`true`** if the current VectorIterator is greater than *`other`*; otherwise, **`false`**. -## `VectorIterator::operator>=` Operator +## `VectorIterator::operator>=` operator -Indicates whether the current VectorIterator is greater than or equal to the specified VectorIterator. +Indicates whether the current VectorIterator is greater than or equal to the specified `VectorIterator`. ### Syntax @@ -175,56 +173,56 @@ bool operator>=(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is greater than or equal to *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is greater than or equal to *`other`*; otherwise, **`false`**. -## VectorIterator::operator++ Operator +## `VectorIterator::operator++` operator -Increments the current VectorIterator. +Increments the current `VectorIterator`. ### Syntax -``` +```cpp VectorIterator& operator++(); VectorIterator operator++(int); ``` ### Return Value -The first syntax increments and then returns the current VectorIterator. The second syntax returns a copy of the current VectorIterator and then increments the current VectorIterator. +The first syntax increments and then returns the current `VectorIterator`. The second syntax returns a copy of the current `VectorIterator` and then increments the current `VectorIterator`. ### Remarks -The first VectorIterator syntax pre-increments the current VectorIterator. +The first `VectorIterator` syntax pre-increments the current `VectorIterator`. -The second syntax post-increments the current VectorIterator. The **`int`** type in the second syntax indicates a post-increment operation, not an actual integer operand. +The second syntax post-increments the current `VectorIterator`. The **`int`** type in the second syntax indicates a post-increment operation, not an actual integer operand. -## VectorIterator::operator!= Operator +## `VectorIterator::operator!=` operator -Indicates whether the current VectorIterator is not equal to a specified VectorIterator. +Indicates whether the current `VectorIterator` is not equal to a specified `VectorIterator`. ### Syntax -``` +```cpp bool operator!=(const VectorIterator& other) const; ``` ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is not equal to *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is not equal to *other*; otherwise, **`false`**. -## `VectorIterator::operator<` Operator +## `VectorIterator::operator<` operator -Indicates whether the current VectorIterator is less than a specified VectorIterator. +Indicates whether the current `VectorIterator` is less than a specified `VectorIterator`. ### Syntax @@ -234,16 +232,16 @@ bool operator<(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is less than *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is less than *`other`*; otherwise, **`false`**. -## `VectorIterator::operator<=` Operator +## `VectorIterator::operator<=` operator -Indicates whether the current VectorIterator is less than or equal to a specified VectorIterator. +Indicates whether the current `VectorIterator` is less than or equal to a specified `VectorIterator`. ### Syntax @@ -253,21 +251,20 @@ bool operator<=(const VectorIterator& other) const ### Parameters -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -**`true`** if the current VectorIterator is less than or equal to *other*; otherwise, **`false`**. +**`true`** if the current `VectorIterator` is less than or equal to *`other`*; otherwise, **`false`**. -## VectorIterator::operator- Operator +## `VectorIterator::operator-` operator Subtracts either a specified number of elements from the current iterator yielding a new iterator, or a specified iterator from the current iterator yielding the number of elements between the iterators. ### Syntax -``` - +```cpp VectorIterator operator-(difference_type n) const; difference_type operator-(const VectorIterator& other) const; @@ -275,43 +272,42 @@ difference_type operator-(const VectorIterator& other) const; ### Parameters -*n*
+*`n`*\ A number of elements. -*other*
-Another VectorIterator. +*`other`*\ +Another `VectorIterator`. ### Return Value -The first operator syntax returns a VectorIterator object that is `n` elements less than the current VectorIterator. The second operator syntax returns the number of elements between the current and the `other` VectorIterator. +The first operator syntax returns a `VectorIterator` object that is `n` elements less than the current `VectorIterator`. The second operator syntax returns the number of elements between the current and the `other` `VectorIterator`. -## VectorIterator::operator+= Operator +## `VectorIterator::operator+=` operator -Increments the current VectorIterator by the specified displacement. +Increments the current `VectorIterator` by the specified displacement. ### Syntax -``` +```cpp VectorIterator& operator+=(difference_type n); ``` ### Parameters -*n*
+*`n`*\ A integer displacement. ### Return Value -The updated VectorIterator. +The updated `VectorIterator`. -## VectorIterator::operator+ Operator +## `VectorIterator::operator+` operator -Returns a VectorIterator that references the element at the specified displacement from the specified VectorIterator. +Returns a `VectorIterator` that references the element at the specified displacement from the specified `VectorIterator`. ### Syntax -``` - +```cpp VectorIterator operator+(difference_type n); template @@ -322,70 +318,70 @@ inline VectorIterator operator+( ### Parameters -*T*
-In the second syntax, the typename of the VectorIterator. +*`T`*\ +In the second syntax, the typename of the `VectorIterator`. -*n*
+*`n`*\ An integer displacement. -*i*
-In the second syntax, a VectorIterator. +*`i`*\ +In the second syntax, a `VectorIterator`. ### Return Value -In the first syntax, a VectorIterator that references the element at the specified displacement from the current VectorIterator. +In the first syntax, a `VectorIterator` that references the element at the specified displacement from the current `VectorIterator`. -In the second syntax, a VectorIterator that references the element at the specified displacement from the beginning of parameter `i`. +In the second syntax, a `VectorIterator` that references the element at the specified displacement from the beginning of parameter `i`. ### Remarks The first syntax example -## VectorIterator::operator-= Operator +## `VectorIterator::operator-=` operator -Decrements the current VectorIterator by the specified displacement. +Decrements the current `VectorIterator` by the specified displacement. ### Syntax -``` +```cpp VectorIterator& operator-=(difference_type n); ``` ### Parameters -*n*
+*`n`*\ An integer displacement. ### Return Value -The updated VectorIterator. +The updated `VectorIterator`. -## VectorIterator::operator\[\] +## `VectorIterator::operator[]` operator -Retrieves a reference to the element that is a specified displacement from the current VectorIterator. +Retrieves a reference to the element that is a specified displacement from the current `VectorIterator`. ### Syntax -``` +```cpp reference operator[](difference_type n) const; ``` ### Parameters -*n*
+*`n`*\ An integer displacement. ### Return Value -The element that is displaced by `n` elements from the current VectorIterator. +The element that is displaced by `n` elements from the current `VectorIterator`. -## VectorIterator::VectorIterator Constructor +## `VectorIterator::VectorIterator` constructor -Initializes a new instance of the VectorIterator class. +Initializes a new instance of the `VectorIterator` class. ### Syntax -``` +```cpp VectorIterator(); explicit VectorIterator( @@ -394,12 +390,12 @@ explicit VectorIterator( ### Parameters -*v*
-An IVector\ object. +*`v`*\ +An `IVector` object. ### Remarks -The first syntax example is the default constructor. The second syntax example is an explicit constructor that is used to construct a VectorIterator from an IVector\ object. +The first syntax example is the default constructor. The second syntax example is an explicit constructor that is used to construct a `VectorIterator` from an `IVector` object. ## See also diff --git a/docs/cppcx/platform-collections-vectorview-class.md b/docs/cppcx/platform-collections-vectorview-class.md index 9bbc63a3227..5fe72ec39f4 100644 --- a/docs/cppcx/platform-collections-vectorview-class.md +++ b/docs/cppcx/platform-collections-vectorview-class.md @@ -65,7 +65,6 @@ Returns an iterator that specifies the first element in the VectorView. ### Syntax ``` - virtual Windows::Foundation::Collections::IIterator^ First(); ``` @@ -85,7 +84,6 @@ Retrieves the element of the current VectorView that is indicated by the specifi ### Syntax ``` - T GetAt( UInt32 index ); @@ -107,7 +105,6 @@ Retrieves a sequence of items from the current VectorView, starting at the speci ### Syntax ``` - virtual unsigned int GetMany( unsigned int startIndex, ::Platform::WriteOnlyArray^ dest @@ -133,7 +130,6 @@ Searches for the specified item in the current VectorView, and if found, returns ### Syntax ``` - virtual bool IndexOf( T value, unsigned int* index @@ -161,7 +157,6 @@ Returns the number of elements in the current VectorView object. ### Syntax ``` - virtual property unsigned int Size; ``` diff --git a/docs/cppcx/platform-collections-vectorviewiterator-class.md b/docs/cppcx/platform-collections-vectorviewiterator-class.md index 9e58635be0e..9abe5629996 100644 --- a/docs/cppcx/platform-collections-vectorviewiterator-class.md +++ b/docs/cppcx/platform-collections-vectorviewiterator-class.md @@ -150,7 +150,6 @@ Indicates whether the current VectorViewIterator is greater than a specified Vec ### Syntax ``` - bool operator>(const VectorViewIterator& other) const; ``` @@ -170,7 +169,6 @@ Indicates whether the current `VectorViewIterator` is greater than or equal to t ### Syntax ``` - bool operator>=(const VectorViewIterator& other) const; ``` @@ -190,7 +188,6 @@ Increments the current VectorViewIterator. ### Syntax ``` - VectorViewIterator& operator++(); VectorViewIterator operator++(int); ``` @@ -250,7 +247,6 @@ Indicates whether the current `VectorIterator` is less than or equal to a specif ### Syntax ``` - bool operator<=(const VectorViewIterator& other) const; ``` @@ -270,7 +266,6 @@ Subtracts either a specified number of elements from the current iterator yieldi ### Syntax ``` - VectorViewIterator operator-(difference_type n) const; difference_type operator-(const VectorViewIterator& other) const; @@ -314,7 +309,6 @@ Returns a VectorViewIterator that references the element at the specified displa ### Syntax ``` - VectorViewIterator operator+(difference_type n) const; template @@ -385,7 +379,6 @@ Initializes a new instance of the VectorViewIterator class. ### Syntax ``` - VectorViewIterator(); explicit VectorViewIterator( diff --git a/docs/cppcx/platform-comexception-class.md b/docs/cppcx/platform-comexception-class.md index 5c8363381cc..42aaeb78ad9 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" -ms.date: "12/30/2016" +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 @@ -74,17 +73,17 @@ The following predefined exceptions are derived from COMException. They differ f ## COMException::COMException Constructor -Intializes a new instance of the COMException class. +Initializes 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 095d32d6233..8e3e645bf9f 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 332d47be884..5721f44c9aa 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 69631f3d545..32f89702c67 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" -ms.date: "12/30/2016" +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 @@ -87,7 +86,7 @@ It is strongly recommended to use CreateException to create a strongly-typed exc ## Exception::Exception Constructor -Intializes a new instance of the Exception class. +Initializes a new instance of the Exception class. ### Syntax @@ -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 02f7ca1cfb6..24268a74b33 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 952645712cc..825700de854 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-ibox-interface.md b/docs/cppcx/platform-ibox-interface.md index bf606fcf34c..fdc629b0e21 100644 --- a/docs/cppcx/platform-ibox-interface.md +++ b/docs/cppcx/platform-ibox-interface.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Platform::IBox Interface" title: "Platform::IBox Interface" -ms.date: "12/30/2016" +description: "Learn more about: Platform::IBox Interface" +ms.date: 12/30/2016 ms.topic: "reference" f1_keywords: ["VCCORLIB/Namespace not found::Platform", "VCCORLIB/Namespace not found::Platform::Value"] -ms.assetid: 774df45d-f8a7-45a3-ae24-eecc3c681040 --- # Platform::IBox Interface @@ -26,8 +25,6 @@ The type of the boxed value. The `IBox` interface is primarily used internally to represent nullable value types, as described in [Value classes and structs (C++/CX)](../cppcx/value-classes-and-structs-c-cx.md). The interface is also used to box value types that are passed to C++ methods that take parameters of type `Object^`. You can explicitly declare an input parameter as `IBox`. For an example, see [Boxing](../cppcx/boxing-c-cx.md). -### Requirements - ### Members The `Platform::IBox` interface inherits from the [Platform::IValueType](../cppcx/platform-ivaluetype-interface.md) interface. `IBox` has these members: diff --git a/docs/cppcx/platform-intptr-value-class.md b/docs/cppcx/platform-intptr-value-class.md index ffadf9627d9..8abd76f842b 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" -ms.date: "12/30/2016" +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,14 +36,16 @@ 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. ### Syntax ```cpp -IntPtr( __int64 handle-or-pointer ); IntPtr( void* value ); IntPtr( int 32-bit_value ); +IntPtr( __int64 handle-or-pointer ); +IntPtr( void* value ); +IntPtr( int 32-bit_value ); ``` ### Parameters @@ -52,14 +53,16 @@ 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. ### Syntax ```cpp -static IntPtr::operator IntPtr( void* value1); static IntPtr::operator IntPtr( int value2); static IntPtr::operator void*( IntPtr value3 ); +static IntPtr::operator IntPtr( void* value1); +static IntPtr::operator IntPtr( int value2); +static IntPtr::operator void*( IntPtr value3 ); ``` ### Parameters @@ -68,7 +71,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 +80,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 120bdd9d5c6..040d608c66d 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 4f9b3c4ba71..9e664b598be 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-flagsattribute-attribute.md b/docs/cppcx/platform-metadata-flagsattribute-attribute.md index b3f435aa5ad..ec334277811 100644 --- a/docs/cppcx/platform-metadata-flagsattribute-attribute.md +++ b/docs/cppcx/platform-metadata-flagsattribute-attribute.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::Metadata::FlagsAttribute Attribute" title: "Platform::Metadata::FlagsAttribute Attribute" -ms.date: "12/30/2016" +description: "Learn more about: Platform::Metadata::FlagsAttribute Attribute" +ms.date: 12/30/2016 ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::Metadata::FlagsAttribute"] helpviewer_keywords: ["Platform::Metadata::FlagsAttribute Attribute"] -ms.assetid: 56f4a191-cc81-4742-aff8-bd2219c0735c --- # Platform::Metadata::FlagsAttribute Attribute @@ -23,8 +22,6 @@ public ref class Flags abstract : Attribute [Platform::Metadata::Attribute](../cppcx/platform-metadata-attribute-attribute.md) -### Remarks - ### Requirements **Minimum supported client:** Windows 8 diff --git a/docs/cppcx/platform-metadata-runtimeclassname.md b/docs/cppcx/platform-metadata-runtimeclassname.md index d40541dd80c..e7e5d3a0568 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 55e18d0b577..94f1c289d83 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 c5924402c21..4fd31538544 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 3c0b40457d3..a080235c9d0 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" -ms.date: "12/30/2016" +description: "Learn more about: Platform::Object Class" +ms.date: 12/30/2016 ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::Object::Object", "VCCORLIB/Platform::Object::Equals", "VCCORLIB/Platform::Object::GetHashCode", "VCCORLIB/Platform::Object::ReferenceEquals", "VCCORLIB/Platform::ToString", "VCCORLIB/Platform::GetType"] helpviewer_keywords: ["Object class"] -ms.assetid: 709e84a8-0bff-471b-bc14-63e424080b5a --- # Platform::Object Class @@ -104,7 +103,7 @@ A [Platform::Type](../cppcx/platform-type-class.md) object that describes the ru The static [Type::GetTypeCode](../cppcx/platform-type-class.md#gettypecode) can be used to get a [Platform::TypeCode Enumeration](../cppcx/platform-typecode-enumeration.md) value that represents the current type. This is mostly useful for built-in types. The type code for any ref class besides [Platform::String](../cppcx/platform-string-class.md) is Object (1). -The [Windows::UI::Xaml::Interop::TypeName](/uwp/api/windows.ui.xaml.interop.typename) class is used in the Windows APIs as a language-independent way of passing type information between Windows components and apps. The T[Platform::Type Class](../cppcx/platform-type-class.md) has operators for converting between `Type` and `TypeName`. +The [Windows::UI::Xaml::Interop::TypeName](/uwp/api/windows.ui.xaml.interop.typename) class is used in the Windows APIs as a language-independent way of passing type information between Windows components and apps. The [Platform::Type Class](../cppcx/platform-type-class.md) has operators for converting between `Type` and `TypeName`. Use the [typeid](../extensions/typeid-cpp-component-extensions.md) operator to return a `Platform::Type` object for a class name, for example when navigating between XAML pages: @@ -166,13 +165,13 @@ public: Tree(){} virtual Platform::String^ ToString() override { - return "I’m a Tree"; - }; + return "I'm a Tree"; + } }; ``` ## See also -[Platform Namespace](platform-namespace-c-cx.md)
-[Platform::Type Class](platform-type-class.md)
+[Platform Namespace](platform-namespace-c-cx.md)\ +[Platform::Type Class](platform-type-class.md)\ [Type System](type-system-c-cx.md) diff --git a/docs/cppcx/platform-objectdisposedexception-class.md b/docs/cppcx/platform-objectdisposedexception-class.md index 36f7004267f..0d9a9055519 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 0ada6f44964..99ce0bc5589 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 d8a878c8913..2bca3dbbac7 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 bf36a9f7911..486396cf6ac 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-sizet-value-class.md b/docs/cppcx/platform-sizet-value-class.md index fe4da84ea6a..3bfbf58eb18 100644 --- a/docs/cppcx/platform-sizet-value-class.md +++ b/docs/cppcx/platform-sizet-value-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Platform::SizeT value class" title: "Platform::SizeT value class" -ms.date: "12/30/2016" +description: "Learn more about: Platform::SizeT value class" +ms.date: 12/30/2016 ms.topic: "reference" f1_keywords: ["VCCORLIB/PlatformSizeT::SizeT constructor"] helpviewer_keywords: ["Platform::SizeT Struct"] -ms.assetid: 0803612c-8ba1-430c-9b7b-1bebae88608d --- # Platform::SizeT value class @@ -40,7 +39,8 @@ Initializes a new instance of SizeT with the specified value. ### Syntax ```cpp -SizeT( uint32 value1 ); SizeT( void* value2 ); +SizeT( uint32 value1 ); +SizeT( void* value2 ); ``` ### Parameters diff --git a/docs/cppcx/platform-string-class.md b/docs/cppcx/platform-string-class.md index 340750259b5..aeaff32abf6 100644 --- a/docs/cppcx/platform-string-class.md +++ b/docs/cppcx/platform-string-class.md @@ -22,7 +22,7 @@ public ref class String sealed : Object, ## Iterators -Two iterator functions, which are not members of the String class, can be used with the `std::for_each` template function to enumerate the characters in a String object. +Two iterator functions, which are not members of the String class, can be used with the `std::for_each` function template to enumerate the characters in a String object. |Member|Description| |------------|-----------------| diff --git a/docs/cppcx/platform-stringreference-class.md b/docs/cppcx/platform-stringreference-class.md index 6b6a0663076..ca8ef3bcf09 100644 --- a/docs/cppcx/platform-stringreference-class.md +++ b/docs/cppcx/platform-stringreference-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Platform::StringReference Class" title: "Platform::StringReference Class" -ms.date: "12/30/2016" +description: "Learn more about: Platform::StringReference Class" +ms.date: 12/30/2016 ms.topic: "reference" f1_keywords: ["VCCORLIB/Platform::StringReference::StringReference", "VCCORLIB/Platform::StringReference::Data", "VCCORLIB/Platform::StringReference::Length", "VCCORLIB/Platform::StringReference::GetHSTRING", "VCCORLIB/Platform::StringReference::GetString"] -ms.assetid: 2d09c7ec-0f16-458e-83ed-7225a1b9221e --- # Platform::StringReference Class @@ -16,8 +15,6 @@ An optimization type that you can use to pass string data from `Platform::String class StringReference ``` -### Remarks - ### Members ### Public Constructors @@ -80,8 +77,6 @@ __abi_HSTRING GetHSTRING() const; An `__abi_HSTRING` that contains the string data. -### Remarks - ## StringReference::GetString Method Returns the contents of the string as a `Platform::String^`. @@ -111,8 +106,6 @@ unsigned int Length() const; An unsigned integer that specifies the number of characters in the string. -### Remarks - ## StringReference::operator= Operator Assigns the specified object to the current `StringReference` object. @@ -140,7 +133,7 @@ A reference to an object of type `StringReference`. Because `StringReference` is a standard C++ class and not a ref class, it does not appear in the **Object Browser**. -## StringReference::operator() Operator +## StringReference::operator() Operator Converts a `StringReference` object to a `Platform::String^` object. diff --git a/docs/cppcx/platform-type-class.md b/docs/cppcx/platform-type-class.md index df4a4ca7ce3..b63ccf0366a 100644 --- a/docs/cppcx/platform-type-class.md +++ b/docs/cppcx/platform-type-class.md @@ -100,7 +100,7 @@ The equivalent of the GetTypeCode() member method is the **`typeid`** property. ## Type::ToString Method -Retrieves a the name of the type. +Retrieves the name of the type. ### Syntax diff --git a/docs/cppcx/platform-writeonlyarray-class.md b/docs/cppcx/platform-writeonlyarray-class.md index 744ff8e94df..797264d80b2 100644 --- a/docs/cppcx/platform-writeonlyarray-class.md +++ b/docs/cppcx/platform-writeonlyarray-class.md @@ -30,7 +30,7 @@ These methods have internal accessibility—that is, they are only accessible wi |[WriteOnlyArray::begin](#begin)|An iterator that points to the first element of the array.| |[WriteOnlyArray::Data](#data)|A pointer to the data buffer.| |[WriteOnlyArray::end](#end)|An iterator that points to one past the last element in the array.| -|[WriteOnlyArray::FastPass](#fastpass)|Indicates whether the array can use the FastPass mechanism, which is an optimization transparently performed by the system. Don’t use this in your code| +|[WriteOnlyArray::FastPass](#fastpass)|Indicates whether the array can use the FastPass mechanism, which is an optimization transparently performed by the system. Don't use this in your code| |[WriteOnlyArray::Length](#length)|Returns the number of elements in the array.| |[WriteOnlyArray::set](#set)|Sets the specified element to the specified value.| diff --git a/docs/cppcx/platform-wrongthreadexception-class.md b/docs/cppcx/platform-wrongthreadexception-class.md index 79320770d50..33c50399148 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/static-libraries-c-cx.md b/docs/cppcx/static-libraries-c-cx.md index a67e7db8feb..8f887064f47 100644 --- a/docs/cppcx/static-libraries-c-cx.md +++ b/docs/cppcx/static-libraries-c-cx.md @@ -38,13 +38,13 @@ Instructions for creating a new project vary depending on which version of Visua When you compile a new static library, if you make a call to a Win32 API that's excluded for UWP apps, the compiler will raise error C3861, "Identifier not found." To look for an alternative method that's supported for the Windows Runtime, see [Alternatives to Windows APIs in UWP apps](/uwp/win32-and-com/alternatives-to-windows-apis-uwp). -If you add a C++ static library project to a UWP app solution, you might have to update the library project’s property settings so that the UWP support property is set to **Yes**. Without this setting, the code builds and links, but an error occurs when you attempt to verify the app for the Microsoft Store. The static lib should be compiled with the same compiler settings as the project that consumes it. +If you add a C++ static library project to a UWP app solution, you might have to update the library project's property settings so that the UWP support property is set to **Yes**. Without this setting, the code builds and links, but an error occurs when you attempt to verify the app for the Microsoft Store. The static lib should be compiled with the same compiler settings as the project that consumes it. If you consume a static library that creates public `ref` classes, public interface classes, or public value classes, the linker raises this warning: > **warning LNK4264:** archiving object file compiled with /ZW into a static library; note that when authoring Windows Runtime types it is not recommended to link with a static library that contains Windows Runtime metadata. -You can safely ignore the warning only if the static library is not producing Windows Runtime components that are consumed outside the library itself. If the library doesn’t consume a component that it defines, then the linker can optimize away the implementation even though the public metadata contains the type information. This means that public components in a static library will compile but will not activate at run time. For this reason, any Windows Runtime component that's intended for consumption by other components or apps must be implemented in a dynamic-link library (DLL). +You can safely ignore the warning only if the static library is not producing Windows Runtime components that are consumed outside the library itself. If the library doesn't consume a component that it defines, then the linker can optimize away the implementation even though the public metadata contains the type information. This means that public components in a static library will compile but will not activate at run time. For this reason, any Windows Runtime component that's intended for consumption by other components or apps must be implemented in a dynamic-link library (DLL). ## See also diff --git a/docs/cppcx/threading-and-marshaling-c-cx.md b/docs/cppcx/threading-and-marshaling-c-cx.md index da89d293b33..3ddf3dd4991 100644 --- a/docs/cppcx/threading-and-marshaling-c-cx.md +++ b/docs/cppcx/threading-and-marshaling-c-cx.md @@ -18,7 +18,7 @@ A Windows Runtime class can support concurrent thread access in various ways, as - `MarshallingBehavior` attribute can have one of the values—Agile, None, or Standard as defined by the `MarshallingType` enumeration. -The `ThreadingModel` attribute specifies where the class is loaded when activated: only in a user-interface thread (STA) context, only in a background thread (MTA) context, or in the context of the thread that creates the object (Both). The `MarshallingBehavior` attribute values refer to how the object behaves in the various threading contexts; in most cases, you don’t have to understand these values in detail. Of the classes that are provided by the Windows API, about 90 percent have `ThreadingModel`=Both and `MarshallingType`=Agile. This means that they can handle low-level threading details transparently and efficiently. When you use `ref new` to create an "agile" class, you can call methods on it from your main app thread or from one or more worker threads. In other words, you can use an agile class—no matter whether it's provided by Windows or by a third party—from anywhere in your code. You don’t have to be concerned with the class’s threading model or marshaling behavior. +The `ThreadingModel` attribute specifies where the class is loaded when activated: only in a user-interface thread (STA) context, only in a background thread (MTA) context, or in the context of the thread that creates the object (Both). The `MarshallingBehavior` attribute values refer to how the object behaves in the various threading contexts; in most cases, you don't have to understand these values in detail. Of the classes that are provided by the Windows API, about 90 percent have `ThreadingModel`=Both and `MarshallingType`=Agile. This means that they can handle low-level threading details transparently and efficiently. When you use `ref new` to create an "agile" class, you can call methods on it from your main app thread or from one or more worker threads. In other words, you can use an agile class—no matter whether it's provided by Windows or by a third party—from anywhere in your code. You don't have to be concerned with the class's threading model or marshaling behavior. ## Consuming Windows Runtime components @@ -31,7 +31,6 @@ For various reasons, some classes can't be agile. If you are accessing instances Of the non-agile classes, the easiest to deal with are those that have `ThreadingModel`=Both and `MarshallingType`=Standard. You can make these classes agile just by using the `Agile` helper class. The following example shows a declaration of a non-agile object of type `Windows::Security::Credentials::UI::CredentialPickerOptions^`, and the compiler warning that's issued as a result. ``` - ref class MyOptions { public: @@ -63,7 +62,6 @@ If neither of those conditions apply, then you can mark the containing class as The following example shows how to use `Agile` so that you can safely ignore the warning. ``` - #include ref class MyOptions { diff --git a/docs/cppcx/toc.yml b/docs/cppcx/toc.yml index edc76e601e7..12708f934f9 100644 --- a/docs/cppcx/toc.yml +++ b/docs/cppcx/toc.yml @@ -13,7 +13,7 @@ items: items: - name: Type system overview href: ../cppcx/type-system-c-cx.md - - name: Namespaces and type visibility (C++/CX ) + - name: Namespaces and type visibility (C++/CX) href: ../cppcx/namespaces-and-type-visibility-c-cx.md - name: Fundamental types href: ../cppcx/fundamental-types-c-cx.md diff --git a/docs/cppcx/value-classes-and-structs-c-cx.md b/docs/cppcx/value-classes-and-structs-c-cx.md index 9dbebf73e1c..55d96917543 100644 --- a/docs/cppcx/value-classes-and-structs-c-cx.md +++ b/docs/cppcx/value-classes-and-structs-c-cx.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Value classes and structs (C++/CX)" title: "Value classes and structs (C++/CX)" +description: "Learn more about: Value classes and structs (C++/CX)" ms.date: "12/30/2016" helpviewer_keywords: ["value struct", "value class"] -ms.assetid: 262a0992-9721-4c02-8297-efc07d90e5a4 --- # Value classes and structs (C++/CX) @@ -12,7 +11,6 @@ A *value struct* or *value class* is a Windows Runtime-compatible POD ("plain ol The following examples show how to declare and initialize value structs. ``` - // in mainpage.xaml.h: value struct TestStruct { @@ -49,7 +47,7 @@ A value struct or value class can contain as fields only fundamental numeric typ A value class or value struct that contains a `Platform::String^` or `IBox^` type as a member is not `memcpy`-able. -Because all members of a **`value class`** or **`value struct`** are public and are emitted into metadata, standard C++ types are not allowed as members. This is different from ref classes, which may contain **`private`** or **`internal`** standard C++ types.. +Because all members of a **`value class`** or **`value struct`** are public and are emitted into metadata, standard C++ types are not allowed as members. This is different from ref classes, which may contain **`private`** or **`internal`** standard C++ types. The following code fragment declares the `Coordinates` and `City` types as value structs. Notice that one of the `City` data members is a `GeoCoordinates` type. A **`value struct`** can contain other value structs as members. @@ -125,7 +123,6 @@ bool MainPage::IsCurrentlyEnrolled(Student s) A value struct itself may be made nullable in the same way, as shown here: ``` - public value struct MyStruct { public: @@ -142,7 +139,7 @@ public: ## See also -[Type System (C++/CX)](../cppcx/type-system-c-cx.md)
-[C++/CX Language Reference](../cppcx/visual-c-language-reference-c-cx.md)
-[Namespaces Reference](../cppcx/namespaces-reference-c-cx.md)
+[Type System (C++/CX)](../cppcx/type-system-c-cx.md)\ +[C++/CX Language Reference](../cppcx/visual-c-language-reference-c-cx.md)\ +[Namespaces Reference](../cppcx/namespaces-reference-c-cx.md)\ [Ref classes and structs (C++/CX)](../cppcx/ref-classes-and-structs-c-cx.md) diff --git a/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md b/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md index 6ec20f173f4..77f627b36d0 100644 --- a/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md +++ b/docs/cppcx/weak-references-and-breaking-cycles-c-cx.md @@ -6,12 +6,11 @@ ms.assetid: 1acb6402-05f0-4951-af94-0e9dab41c53e --- # Weak references and breaking cycles (C++/CX) -In any type system that's based on reference-counting, references to types can form *cycles*—that is, one object refers to a second object, the second object refers to a third object, and so on until some final object refers back to the first object. In a cycle, objects can't be deleted correctly when one object's reference count becomes zero. To help you solve this problem, C++/CX provides the [Platform::WeakReference Class](../cppcx/platform-weakreference-class.md) class. A `WeakReference` object supports the [Resolve](../cppcx/platform-weakreference-class.md#resolve) method, which returns null if the object no longer exists, or throws an [Platform::InvalidCastException](../cppcx/platform-invalidcastexception-class.md) if the object is alive but is not of type `T`. +In any type system that's based on reference-counting, references to types can form *cycles*—that is, one object refers to a second object, the second object refers to a third object, and so on until some final object refers back to the first object. In a cycle, objects can't be deleted correctly when one object's reference count becomes zero. To help you solve this problem, C++/CX provides the [Platform::WeakReference Class](../cppcx/platform-weakreference-class.md). A `WeakReference` object supports the [Resolve](../cppcx/platform-weakreference-class.md#resolve) method, which returns null if the object no longer exists, or throws an [Platform::InvalidCastException](../cppcx/platform-invalidcastexception-class.md) if the object is alive but is not of type `T`. One scenario in which `WeakReference` must be used is when the **`this`** pointer is captured in a lambda expression that's used to define an event handler. We recommend that you use named methods when you define event handlers, but if you want to use a lambda for your event handler—or if you have to break a reference counting cycle in some other situation—use `WeakReference`. Here's an example: ``` - using namespace Platform::Details; using namespace Windows::UI::Xaml; using namespace Windows::UI::Xaml::Input; diff --git a/docs/cppcx/windows-foundation-collections-namespace-c-cx.md b/docs/cppcx/windows-foundation-collections-namespace-c-cx.md index e9f90569667..4bfd12a620d 100644 --- a/docs/cppcx/windows-foundation-collections-namespace-c-cx.md +++ b/docs/cppcx/windows-foundation-collections-namespace-c-cx.md @@ -13,7 +13,6 @@ C++/CX supplements the Windows::Foundation::Collections namespace with functions ## Syntax ``` - namespace Windows { namespace Foundation { namespace Collections; diff --git a/docs/cppcx/wrl/activationfactory-class.md b/docs/cppcx/wrl/activationfactory-class.md index 26f79c006eb..dc849fce65a 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 5a3d5415888..3922e3f696c 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/callback-function-wrl.md b/docs/cppcx/wrl/callback-function-wrl.md index 777ea551af4..dd804d4df02 100644 --- a/docs/cppcx/wrl/callback-function-wrl.md +++ b/docs/cppcx/wrl/callback-function-wrl.md @@ -20,166 +20,14 @@ template< ComPtr Callback( TCallback callback ); -template< - typename TDelegateInterface, - typename TCallbackObject -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)() -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1) -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1, - typename TArg2 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2) -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1, - typename TArg2, - typename TArg3 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2, - TArg3) -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1, - typename TArg2, - typename TArg3, - typename TArg4 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2, - TArg3, - TArg4) -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1, - typename TArg2, - typename TArg3, - typename TArg4, - typename TArg5 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2, - TArg3, - TArg4, - TArg5) -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1, - typename TArg2, - typename TArg3, - typename TArg4, - typename TArg5, - typename TArg6 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2, - TArg3, - TArg4, - TArg5, - TArg6) -); template< typename TDelegateInterface, typename TCallbackObject, - typename TArg1, - typename TArg2, - typename TArg3, - typename TArg4, - typename TArg5, - typename TArg6, - typename TArg7 + typename... TArgs > ComPtr Callback( _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2, - TArg3, - TArg4, - TArg5, - TArg6, - TArg7) -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1, - typename TArg2, - typename TArg3, - typename TArg4, - typename TArg5, - typename TArg6, - typename TArg7, - typename TArg8 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2, - TArg3, - TArg4, - TArg5, - TArg6, - TArg7, - TArg8) -); -template< - typename TDelegateInterface, - typename TCallbackObject, - typename TArg1, - typename TArg2, - typename TArg3, - typename TArg4, - typename TArg5, - typename TArg6, - typename TArg7, - typename TArg8, - typename TArg9 -> -ComPtr Callback( - _In_ TCallbackObject *object, - _In_ HRESULT (TCallbackObject::* method)(TArg1, - TArg2, - TArg3, - TArg4, - TArg5, - TArg6, - TArg7, - TArg8, - TArg9) + _In_ HRESULT (TCallbackObject::* method)(TArgs...) ); ``` @@ -194,32 +42,8 @@ A template parameter that specifies the type of an object that represents an obj *TCallbackObject*
A template parameter that specifies the object whose member function is the method to call when an event occurs. -*TArg1*
-A template parameter that specifies the type of the first callback method argument. - -*TArg2*
-A template parameter that specifies the type of the second callback method argument. - -*TArg3*
-A template parameter that specifies the type of the third callback method argument. - -*TArg4*
-A template parameter that specifies the type of the fourth callback method argument. - -*TArg5*
-A template parameter that specifies the type of the fifth callback method argument. - -*TArg6*
-A template parameter that specifies the type of the sixth callback method argument. - -*TArg7*
-A template parameter that specifies the type of the seventh callback method argument. - -*TArg8*
-A template parameter that specifies the type of the eighth callback method argument. - -*TArg9*
-A template parameter that specifies the type of the ninth callback method argument. +*TArgs*
+A template parameter pack that specifies the types of the callback method arguments. *callback*
An object that represents the callback object and its member function. diff --git a/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md b/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md index 9ed068e9a3b..84a982a6a9a 100644 --- a/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md +++ b/docs/cppcx/wrl/canceltransitionpolicy-enumeration.md @@ -9,7 +9,7 @@ ms.assetid: 5de49f7d-e5e3-43e9-bbca-666caf226cef --- # CancelTransitionPolicy Enumeration -Indicates how an asynchronous operation’s attempt to transition to a terminal state of completed or error should behave with respect to a client-requested canceled state. +Indicates how an asynchronous operation's attempt to transition to a terminal state of completed or error should behave with respect to a client-requested canceled state. ## Syntax diff --git a/docs/cppcx/wrl/chaininterfaces-structure.md b/docs/cppcx/wrl/chaininterfaces-structure.md index 8f4c5b7bede..d27322ff971 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 de0c012ca78..c061d367726 100644 --- a/docs/cppcx/wrl/criticalsection-class.md +++ b/docs/cppcx/wrl/criticalsection-class.md @@ -75,7 +75,7 @@ The spin count for the critical section object. The default value is 0. ### Remarks -For more information about critical sections and spincounts, see the `InitializeCriticalSectionAndSpinCount` function in the `Synchronization` section of the Windows API documenation. +For more information about critical sections and spincounts, see the `InitializeCriticalSectionAndSpinCount` function in the `Synchronization` section of the Windows API documentation. ## CriticalSection::cs_ diff --git a/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md b/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md index 90737d312d1..113ac97dc39 100644 --- a/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md +++ b/docs/cppcx/wrl/how-to-activate-and-use-a-windows-runtime-component-using-wrl.md @@ -47,7 +47,7 @@ The following steps use the `Windows::Foundation::IUriRuntimeClass` interface to [!code-cpp[wrl-consume-component#6](../codesnippet/CPP/how-to-activate-and-use-a-windows-runtime-component-using-wrl_4.cpp)] - In the Windows Runtime, you don’t allocate memory for a string that the Windows Runtime will use. Instead, the Windows Runtime creates a copy of your string in a buffer that it maintains and uses for operations, and then returns a handle to the buffer that it created. + In the Windows Runtime, you don't allocate memory for a string that the Windows Runtime will use. Instead, the Windows Runtime creates a copy of your string in a buffer that it maintains and uses for operations, and then returns a handle to the buffer that it created. 5. Use the `IUriRuntimeClassFactory::CreateUri` factory method to create a `ABI::Windows::Foundation::IUriRuntimeClass` object. diff --git a/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md b/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md index 9c2412c0435..5e6a4535bf1 100644 --- a/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md +++ b/docs/cppcx/wrl/how-to-complete-asynchronous-operations-using-wrl.md @@ -46,7 +46,7 @@ The following steps start an asynchronous timer and wait for the timer to expire [!code-cpp[wrl-consume-async#5](../codesnippet/CPP/how-to-complete-asynchronous-operations-using-wrl_4.cpp)] > [!NOTE] - > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don’t wait for async operations to complete. + > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don't wait for async operations to complete. 5. Create an `IThreadPoolTimer` object that expires after two seconds. Use the `Callback` function to create the event handler (an `ABI::Windows::System::Threading::ITimerElapsedHandler` object). @@ -94,7 +94,7 @@ The following steps start a worker thread and define the action that's performed [!code-cpp[wrl-consume-asyncOp#5](../codesnippet/CPP/how-to-complete-asynchronous-operations-using-wrl_11.cpp)] > [!NOTE] - > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don’t wait for async operations to complete. + > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don't wait for async operations to complete. 5. Call the `IThreadPoolStatics::RunAsync` method to create a worker thread. Use the `Callback` function to define the action. diff --git a/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md b/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md index 8436766015b..4b01f17a9ab 100644 --- a/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md +++ b/docs/cppcx/wrl/how-to-create-a-classic-com-component-using-wrl.md @@ -68,7 +68,7 @@ This document shows how to use the Windows Runtime C++ Template Library to creat @="1.0" ``` -2. Run RegScript.reg or add it to your project’s **Post-Build Event**. For more information, see [Pre-build Event/Post-build Event Command Line Dialog Box](/visualstudio/ide/reference/pre-build-event-post-build-event-command-line-dialog-box). +2. Run RegScript.reg or add it to your project's **Post-Build Event**. For more information, see [Pre-build Event/Post-build Event Command Line Dialog Box](/visualstudio/ide/reference/pre-build-event-post-build-event-command-line-dialog-box). 3. Add a **Win32 Console Application** project to the solution. Name the project, for example, `Calculator`. diff --git a/docs/cppcx/wrl/how-to-handle-events-using-wrl.md b/docs/cppcx/wrl/how-to-handle-events-using-wrl.md index 24586748072..40245ab4982 100644 --- a/docs/cppcx/wrl/how-to-handle-events-using-wrl.md +++ b/docs/cppcx/wrl/how-to-handle-events-using-wrl.md @@ -39,7 +39,7 @@ The following steps start an `ABI::Windows::System::Threading::IDeviceWatcher` o [!code-cpp[wrl-consume-event#4](../codesnippet/CPP/how-to-handle-events-using-wrl_4.cpp)] > [!NOTE] - > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don’t wait for async operations to complete. + > This event is for demonstration only as part of a console app. This example uses the event to ensure that an async operation completes before the app exits. In most apps, you typically don't wait for async operations to complete. 5. Create an activation factory for the `IDeviceWatcher` interface. diff --git a/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md b/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md index f450c89319e..207ee699fd9 100644 --- a/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md +++ b/docs/cppcx/wrl/how-to-instantiate-wrl-components-directly.md @@ -16,7 +16,7 @@ To learn how to use Windows Runtime C++ Template Library to create a classic COM This document shows two examples. The first example uses the `Make` function to instantiate a component. The second example uses the `MakeAndInitialize` function to instantiate a component that can fail during construction. (Because COM typically uses HRESULT values, instead of exceptions, to indicate errors, a COM type typically does not throw from its constructor. `MakeAndInitialize` enables a component to validate its construction arguments through the `RuntimeClassInitialize` method.) Both examples define a basic logger interface and implement that interface by defining a class that writes messages to the console. > [!IMPORTANT] -> You can’t use the `new` operator to instantiate Windows Runtime C++ Template Library components. Therefore, we recommend that you always use `Make` or `MakeAndInitialize` to instantiate a component directly. +> You can't use the `new` operator to instantiate Windows Runtime C++ Template Library components. Therefore, we recommend that you always use `Make` or `MakeAndInitialize` to instantiate a component directly. ### To create and instantiate a basic logger component diff --git a/docs/cppcx/wrl/hstring-class.md b/docs/cppcx/wrl/hstring-class.md index 310b828349c..1d9df0ceedf 100644 --- a/docs/cppcx/wrl/hstring-class.md +++ b/docs/cppcx/wrl/hstring-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: HString Class" title: "HString Class" -ms.date: "07/15/2019" +description: "Learn more about: HString Class" +ms.date: 07/15/2019 ms.topic: "reference" f1_keywords: ["corewrappers/Microsoft::WRL::Wrappers::HString", "corewrappers/Microsoft::WRL::Wrappers::HString::Attach", "corewrappers/Microsoft::WRL::Wrappers::HString::CopyTo", "corewrappers/Microsoft::WRL::Wrappers::HString::Detach", "corewrappers/Microsoft::WRL::Wrappers::HString::Get", "corewrappers/Microsoft::WRL::Wrappers::HString::GetRawBuffer","corewrappers/Microsoft::WRL::Wrappers::HString::GetAddressOf", "corewrappers/Microsoft::WRL::Wrappers::HString::HString", "corewrappers/Microsoft::WRL::Wrappers::HString::IsValid", "corewrappers/Microsoft::WRL::Wrappers::HString::MakeReference", "corewrappers/Microsoft::WRL::Wrappers::HString::operator=", "corewrappers/Microsoft::WRL::Wrappers::HString::operator==", "corewrappers/Microsoft::WRL::Wrappers::HString::operator!=", "corewrappers/Microsoft::WRL::Wrappers::HString::operator<", "corewrappers/Microsoft::WRL::Wrappers::HString::Release", "corewrappers/Microsoft::WRL::Wrappers::HString::Set", "corewrappers/Microsoft::WRL::Wrappers::HString::~HString"] helpviewer_keywords: ["Microsoft::WRL::Wrappers::HString class", "Microsoft::WRL::Wrappers::HString::Attach method", "Microsoft::WRL::Wrappers::HString::CopyTo method", "Microsoft::WRL::Wrappers::HString::Detach method", "Microsoft::WRL::Wrappers::HString::Get method", "Microsoft::WRL::Wrappers::HString::GetAddressOf method", "Microsoft::WRL::Wrappers::HString::HString, constructor", "Microsoft::WRL::Wrappers::HString::IsValid method", "Microsoft::WRL::Wrappers::HString::MakeReference method", "Microsoft::WRL::Wrappers::HString::operator= operator", "Microsoft::WRL::Wrappers::HString::operator== operator", "Microsoft::WRL::Wrappers::HString::operator!= operator", "Microsoft::WRL::Wrappers::HString::operator< operator", "Microsoft::WRL::Wrappers::HString::Release method", "Microsoft::WRL::Wrappers::HString::Set method", "Microsoft::WRL::Wrappers::HString::~HString, destructor"] -ms.assetid: 6709dd2e-8d72-4675-8ec7-1baa7d71854d --- # HString Class @@ -42,7 +41,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 @@ -340,7 +339,7 @@ The second parameter to compare. *rhs* can be a reference to an `HString`. ## HString::Release -Deletes the underlying string value and intializes the current `HString` object to an empty value. +Deletes the underlying string value and initializes the current `HString` object to an empty value. ```cpp void Release() throw() diff --git a/docs/cppcx/wrl/module-class.md b/docs/cppcx/wrl/module-class.md index 75bbf6bc9c8..3cefc4e6d76 100644 --- a/docs/cppcx/wrl/module-class.md +++ b/docs/cppcx/wrl/module-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Module Class" title: "Module Class" -ms.date: "10/18/2018" +description: "Learn more about: Module Class" +ms.date: 10/18/2018 ms.topic: "reference" f1_keywords: ["module/Microsoft::WRL::Module", "module/Microsoft::WRL::Module::Create", "module/Microsoft::WRL::Module::DecrementObjectCount", "module/Microsoft::WRL::Module::GetActivationFactory", "module/Microsoft::WRL::Module::GetClassObject", "module/Microsoft::WRL::Module::GetModule", "module/Microsoft::WRL::Module::GetObjectCount", "module/Microsoft::WRL::Module::IncrementObjectCount", "module/Microsoft::WRL::Module::Module", "module/Microsoft::WRL::Module::objectCount_Data", "module/Microsoft::WRL::Module::RegisterCOMObject", "module/Microsoft::WRL::Module::RegisterObjects", "module/Microsoft::WRL::Module::RegisterWinRTObject", "module/Microsoft::WRL::Module::releaseNotifier_", "module/Microsoft::WRL::Module::Terminate", "module/Microsoft::WRL::Module::~Module", "module/Microsoft::WRL::Module::UnregisterCOMObject", "module/Microsoft::WRL::Module::UnregisterObjects", "module/Microsoft::WRL::Module::UnregisterWinRTObject"] helpviewer_keywords: ["Microsoft::WRL::Module class", "Microsoft::WRL::Module::Create method", "Microsoft::WRL::Module::DecrementObjectCount method", "Microsoft::WRL::Module::GetActivationFactory method", "Microsoft::WRL::Module::GetClassObject method", "Microsoft::WRL::Module::GetModule method", "Microsoft::WRL::Module::GetObjectCount method", "Microsoft::WRL::Module::IncrementObjectCount method", "Microsoft::WRL::Module::Module, constructor", "Microsoft::WRL::Module::objectCount_ data member", "Microsoft::WRL::Module::RegisterCOMObject method", "Microsoft::WRL::Module::RegisterObjects method", "Microsoft::WRL::Module::RegisterWinRTObject method", "Microsoft::WRL::Module::releaseNotifier_ data member", "Microsoft::WRL::Module::Terminate method", "Microsoft::WRL::Module::~Module, destructor", "Microsoft::WRL::Module::UnregisterCOMObject method", "Microsoft::WRL::Module::UnregisterObjects method", "Microsoft::WRL::Module::UnregisterWinRTObject method"] -ms.assetid: dd67e3b8-c2e1-4f53-8c0f-565a140ba649 --- # Module Class @@ -189,7 +188,7 @@ S_OK if successful; otherwise, the HRESULT returned by GetActivationFactory. ## Module::GetClassObject -Retreives a cache of class factories. +Retrieves a cache of class factories. ```cpp HRESULT GetClassObject( @@ -309,7 +308,7 @@ The number of CLSIDs to register. ### Return Value -S_OK if successfu; otherwise, an HRESULT such as CO_E_OBJISREG that indicates the reason the operation failed. +S_OK if successful; otherwise, an HRESULT such as CO_E_OBJISREG that indicates the reason the operation failed. ### Remarks @@ -396,7 +395,7 @@ Unregisters one or more COM objects, which prevents other applications from conn virtual HRESULT UnregisterCOMObject( const wchar_t* serverName, DWORD* cookies, - unsigned int count + unsigned int count); ``` ### Parameters diff --git a/docs/cppcx/wrl/runtimeclass-class.md b/docs/cppcx/wrl/runtimeclass-class.md index 5011d0fbaee..6e026c28c9c 100644 --- a/docs/cppcx/wrl/runtimeclass-class.md +++ b/docs/cppcx/wrl/runtimeclass-class.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: RuntimeClass Class" -title: "RuntimeClass Class" -ms.date: "09/11/2018" +description: "Learn more about: RuntimeClass class" +title: "RuntimeClass class" +ms.date: 09/28/2022 ms.topic: "reference" f1_keywords: ["implements/Microsoft::WRL::RuntimeClass", "implements/Microsoft::WRL::RuntimeClass::AddRef", "implements/Microsoft::WRL::RuntimeClass::DecrementReference", "implements/Microsoft::WRL::RuntimeClass::GetIids", "implements/Microsoft::WRL::RuntimeClass::GetRuntimeClassName", "implements/Microsoft::WRL::RuntimeClass::GetTrustLevel", "implements/Microsoft::WRL::RuntimeClass::GetWeakReference", "implements/Microsoft::WRL::RuntimeClass::InternalAddRef", "implements/Microsoft::WRL::RuntimeClass::QueryInterface", "implements/Microsoft::WRL::RuntimeClass::Release", "implements/Microsoft::WRL::RuntimeClass::RuntimeClass", "implements/Microsoft::WRL::RuntimeClass::~RuntimeClass"] helpviewer_keywords: ["Microsoft::WRL::RuntimeClass class", "Microsoft::WRL::RuntimeClass::AddRef method", "Microsoft::WRL::RuntimeClass::DecrementReference method", "Microsoft::WRL::RuntimeClass::GetIids method", "Microsoft::WRL::RuntimeClass::GetRuntimeClassName method", "Microsoft::WRL::RuntimeClass::GetTrustLevel method", "Microsoft::WRL::RuntimeClass::GetWeakReference method", "Microsoft::WRL::RuntimeClass::InternalAddRef method", "Microsoft::WRL::RuntimeClass::QueryInterface method", "Microsoft::WRL::RuntimeClass::Release method", "Microsoft::WRL::RuntimeClass::RuntimeClass, constructor", "Microsoft::WRL::RuntimeClass::~RuntimeClass, destructor"] ms.assetid: d52f9d1a-98e5-41f2-a143-8fb629dd0727 --- -# RuntimeClass Class +# `RuntimeClass` class Represents a WinRT or COM class that inherits the specified interfaces and provides the specified Windows Runtime, classic COM, and weak reference support. @@ -22,49 +22,49 @@ template class RuntimeClass; ### Parameters -*classFlags*
-Optional parameter. A combination of one or more [RuntimeClassType](runtimeclasstype-enumeration.md) enumeration values. The `__WRL_CONFIGURATION_LEGACY__` macro can be defined to change the default value of classFlags for all runtime classes in the project. If defined, RuntimeClass instances are non-agile by default. When not defined, RuntimeClass instances are agile by default. To avoid ambiguity always specify the `Microsoft::WRL::FtmBase` in `TInterfaces` or `RuntimeClassType::InhibitFtmBase`. Note, if InhibitFtmBase and FtmBase are both used the object will be agile. +*`classFlags`*\ +Optional parameter. A combination of one or more [`RuntimeClassType`](runtimeclasstype-enumeration.md) enumeration values. The `__WRL_CONFIGURATION_LEGACY__` macro can be defined to change the default value of *`classFlags`* for all runtime classes in the project. If defined, `RuntimeClass` instances are non-agile by default. When not defined, `RuntimeClass` instances are agile by default. To avoid ambiguity, always specify the `Microsoft::WRL::FtmBase` in `TInterfaces` or `RuntimeClassType::InhibitFtmBase`. If `InhibitFtmBase` and `FtmBase` are both used, the object will be agile. -*TInterfaces*
-The list of interfaces the object implements beyond `IUnknown`, `IInspectable` or other interfaces controlled by [RuntimeClassType](runtimeclasstype-enumeration.md). It also may list other classes to be derived from, notably `Microsoft::WRL::FtmBase` to make the object agile and cause it to implement `IMarshal`. +*`TInterfaces`*\ +The list of interfaces the object implements beyond `IUnknown`, `IInspectable` or other interfaces controlled by [`RuntimeClassType`](runtimeclasstype-enumeration.md). It also may list other classes to be derived from, notably `Microsoft::WRL::FtmBase` to make the object agile and cause it to implement `IMarshal`. ## Members -`RuntimeClassInitialize`
-A function which initializes the object if the `MakeAndInitialize` template function is used to construct the object. It returns S_OK if the object was successfully initialized, or a COM error code if initialization failed. The COM error code is propagated as the return value of `MakeAndInitialize`. Note that the `RuntimeClassInitialize` method is not called if the `Make` template function is used to construct the object. +`RuntimeClassInitialize`\ +A function that initializes the object if the `MakeAndInitialize` function template is used to construct the object. It returns `S_OK` if the object was successfully initialized, or a COM error code if initialization failed. The COM error code is propagated as the return value of `MakeAndInitialize`. The `RuntimeClassInitialize` method isn't called if the `Make` function template is used to construct the object. ### Public Constructors -| Name | Description | -| -------------------------------------------------- | --------------------------------------------------------------- | -| [RuntimeClass::RuntimeClass](#runtimeclass) | Initializes the current instance of the `RuntimeClass` class. | -| [RuntimeClass::~RuntimeClass](#tilde-runtimeclass) | Deinitializes the current instance of the `RuntimeClass` class. | +| Name | Description | +|--|--| +| [`RuntimeClass::RuntimeClass`](#runtimeclass) | Initializes the current instance of the `RuntimeClass` class. | +| [`RuntimeClass::~RuntimeClass`](#tilde-runtimeclass) | Deinitializes the current instance of the `RuntimeClass` class. | ### Public Methods -| Name | Description | -| --------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | -| [RuntimeClass::AddRef](#addref) | Increments the reference count for the current `RuntimeClass` object. | -| [RuntimeClass::DecrementReference](#decrementreference) | Decrements the reference count for the current `RuntimeClass` object. | -| [RuntimeClass::GetIids](#getiids) | Gets an array that can contain the interface IDs implemented by the current `RuntimeClass` object. | -| [RuntimeClass::GetRuntimeClassName](#getruntimeclassname) | Gets the runtime class name of the current `RuntimeClass` object. | -| [RuntimeClass::GetTrustLevel](#gettrustlevel) | Gets the trust level of the current `RuntimeClass` object. | -| [RuntimeClass::GetWeakReference](#getweakreference) | Gets a pointer to the weak reference object for the current `RuntimeClass` object. | -| [RuntimeClass::InternalAddRef](#internaladdref) | Increments the reference count to the current `RuntimeClass` object. | -| [RuntimeClass::QueryInterface](#queryinterface) | Retrieves a pointer to the specified interface ID. | -| [RuntimeClass::Release](#release) | Performs a COM Release operation on the current `RuntimeClass` object. | +| Name | Description | +|--|--| +| [`RuntimeClass::AddRef`](#addref) | Increments the reference count for the current `RuntimeClass` object. | +| [`RuntimeClass::DecrementReference`](#decrementreference) | Decrements the reference count for the current `RuntimeClass` object. | +| [`RuntimeClass::GetIids`](#getiids) | Gets an array that can contain the interface IDs implemented by the current `RuntimeClass` object. | +| [`RuntimeClass::GetRuntimeClassName`](#getruntimeclassname) | Gets the runtime class name of the current `RuntimeClass` object. | +| [`RuntimeClass::GetTrustLevel`](#gettrustlevel) | Gets the trust level of the current `RuntimeClass` object. | +| [`RuntimeClass::GetWeakReference`](#getweakreference) | Gets a pointer to the weak reference object for the current `RuntimeClass` object. | +| [`RuntimeClass::InternalAddRef`](#internaladdref) | Increments the reference count to the current `RuntimeClass` object. | +| [`RuntimeClass::QueryInterface`](#queryinterface) | Retrieves a pointer to the specified interface ID. | +| [`RuntimeClass::Release`](#release) | Performs a COM Release operation on the current `RuntimeClass` object. | ## Inheritance Hierarchy -This is an implementation detail. +The hierarchy is an implementation detail. ## Requirements **Header:** implements.h -**Namespace:** Microsoft::WRL +**Namespace:** `Microsoft::WRL` -## RuntimeClass::~RuntimeClass +## `RuntimeClass::~RuntimeClass` Deinitializes the current instance of the `RuntimeClass` class. @@ -72,7 +72,7 @@ Deinitializes the current instance of the `RuntimeClass` class. virtual ~RuntimeClass(); ``` -## RuntimeClass::AddRef +## `RuntimeClass::AddRef` Increments the reference count for the current `RuntimeClass` object. @@ -83,11 +83,11 @@ STDMETHOD_( )(); ``` -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## RuntimeClass::DecrementReference +## `RuntimeClass::DecrementReference` Decrements the reference count for the current `RuntimeClass` object. @@ -95,11 +95,11 @@ Decrements the reference count for the current `RuntimeClass` object. ULONG DecrementReference(); ``` -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## RuntimeClass::GetIids +## `RuntimeClass::GetIids` Gets an array that can contain the interface IDs implemented by the current `RuntimeClass` object. @@ -113,17 +113,17 @@ STDMETHOD( ### Parameters -*iidCount*
-When this operation completes, the total number of elements in array *iids*. +*`iidCount`*\ +When this operation completes, the total number of elements in array *`iids`*. -*iids*
+*`iids`*\ When this operation completes, a pointer to an array of interface IDs. -### Return Value +### Return value -S_OK if successful; otherwise, E_OUTOFMEMORY. +`S_OK` if successful; otherwise, `E_OUTOFMEMORY`. -## RuntimeClass::GetRuntimeClassName +## `RuntimeClass::GetRuntimeClassName` Gets the runtime class name of the current `RuntimeClass` object. @@ -135,18 +135,18 @@ STDMETHOD( GetRuntimeClassName )( ### Parameters -*runtimeName*
+*`runtimeName`*\ When this operation completes, the runtime class name. -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. ### Remarks An assert error is emitted if `__WRL_STRICT__` or `__WRL_FORCE_INSPECTABLE_CLASS_MACRO__` isn't defined. -## RuntimeClass::GetTrustLevel +## `RuntimeClass::GetTrustLevel` Gets the trust level of the current `RuntimeClass` object. @@ -158,18 +158,18 @@ STDMETHOD(GetTrustLevel)( ### Parameters -*trustLvl*
+*`trustLvl`*\ When this operation completes, the trust level of the current `RuntimeClass` object. -### Return Value +### Return value -Always S_OK. +Always `S_OK`. ### Remarks An assert error is emitted if `__WRL_STRICT__` or `__WRL_FORCE_INSPECTABLE_CLASS_MACRO__` isn't defined. -## RuntimeClass::GetWeakReference +## `RuntimeClass::GetWeakReference` Gets a pointer to the weak reference object for the current `RuntimeClass` object. @@ -181,14 +181,14 @@ STDMETHOD( ### Parameters -*weakReference*
+*`weakReference`*\ When this operation completes, a pointer to a weak reference object. -### Return Value +### Return value -Always S_OK. +Always `S_OK`. -## RuntimeClass::InternalAddRef +## `RuntimeClass::InternalAddRef` Increments the reference count to the current `RuntimeClass` object. @@ -196,11 +196,11 @@ Increments the reference count to the current `RuntimeClass` object. ULONG InternalAddRef(); ``` -### Return Value +### Return value The resulting reference count. -## RuntimeClass::QueryInterface +## `RuntimeClass::QueryInterface` Retrieves a pointer to the specified interface ID. @@ -214,17 +214,17 @@ STDMETHOD( ### Parameters -*riid*
+*`riid`*\ An interface ID. -*ppvObject*
-When this opereation completes, a pointer to the interface specified by the *riid* parameter. +*`ppvObject`*\ +When this operation completes, a pointer to the interface specified by the *`riid`* parameter. -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. -## RuntimeClass::Release +## `RuntimeClass::Release` Performs a COM Release operation on the current `RuntimeClass` object. @@ -235,15 +235,15 @@ STDMETHOD_( )(); ``` -### Return Value +### Return value -S_OK if successful; otherwise, an HRESULT that indicates the error. +`S_OK` if successful; otherwise, an `HRESULT` that indicates the error. ### Remarks If the reference count becomes zero, the `RuntimeClass` object is deleted. -## RuntimeClass::RuntimeClass +## `RuntimeClass::RuntimeClass` Initializes the current instance of the `RuntimeClass` class. diff --git a/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md b/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md index 9986b362fe6..5ec81ffc805 100644 --- a/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md +++ b/docs/cppcx/wrl/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Creating a UWP app using WRL and Media Foundation" title: "Walkthrough: Creating a UWP app using WRL and Media Foundation" +description: "Learn more about: Creating a UWP app using WRL and Media Foundation" ms.date: 04/15/2021 ms.topic: "reference" --- @@ -37,7 +37,7 @@ You can usually use C++/CX to create Windows Runtime components. However, someti - The `namespace` and `runtimeclass` attributes, and the `NTDDI_WIN8` [version](/windows/win32/Midl/version) attribute value are important parts of the MIDL definition for a Media Foundation component that uses WRL. -- [`Microsoft::WRL::RuntimeClass`](runtimeclass-class.md) is the base class for the custom Media Foundation component. The [`Microsoft::WRL::RuntimeClassType::WinRtClassicComMix]`(runtimeclasstype-enumeration.md) enum value, which is provided as a template argument, marks the class for use both as a Windows Runtime class and as a classic COM runtime class. +- [`Microsoft::WRL::RuntimeClass`](runtimeclass-class.md) is the base class for the custom Media Foundation component. The [`Microsoft::WRL::RuntimeClassType::WinRtClassicComMix`](runtimeclasstype-enumeration.md) enum value, which is provided as a template argument, marks the class for use both as a Windows Runtime class and as a classic COM runtime class. - The [`InspectableClass`](inspectableclass-macro.md) macro implements basic COM functionality such as reference counting and the `QueryInterface` method, and sets the runtime class name and trust level. @@ -86,7 +86,7 @@ You can usually use C++/CX to create Windows Runtime components. However, someti [!code-cpp[wrl-media-capture#6](../codesnippet/CPP/walkthrough-creating-a-windows-store-app-using-wrl-and-media-foundation_6.cpp)] -1. In the project’s **Property Pages** dialog box, set the following **Linker** properties. +1. In the project's **Property Pages** dialog box, set the following **Linker** properties. 1. Under **Input**, for the **Module Definition File**, specify `GrayScaleTransform.def`. diff --git a/docs/cppcx/wrl/weakref-class.md b/docs/cppcx/wrl/weakref-class.md index 86e2c5d46a0..66191b5c263 100644 --- a/docs/cppcx/wrl/weakref-class.md +++ b/docs/cppcx/wrl/weakref-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: WeakRef Class" title: "WeakRef Class" +description: "Learn more about: WeakRef Class" ms.date: 11/22/2021 ms.topic: "reference" f1_keywords: ["client/Microsoft::WRL::WeakRef", "client/Microsoft::WRL::WeakRef::~WeakRef", "client/Microsoft::WRL::WeakRef::As", "client/Microsoft::WRL::WeakRef::AsIID", "client/Microsoft::WRL::WeakRef::CopyTo", "client/Microsoft::WRL::WeakRef::operator&", "client/Microsoft::WRL::WeakRef::WeakRef"] @@ -60,7 +60,7 @@ HRESULT hr = wr.As(&strongRef); // Check the input pointer instead. if(wr == nullptr) { - wprintf(L"Couldn’t get strong ref!"); + wprintf(L"Couldn't get strong ref!"); } ``` @@ -193,7 +193,7 @@ When this operation completes, an object that represents parameter *`riid`*. - `S_OK` if this operation succeeds, but the current `WeakRef` object has already been released. Parameter *`ptr`* is set to **`nullptr`**. -- `S_OK` if this operation succeeds, but the current `WeakRef` object isn't derived from parameter *`riid`*. Parameter *`ptr`* is set to **`nullptr`**. (For more information, see Remarks.) +- `S_OK` if this operation succeeds, but the current `WeakRef` object isn't derived from parameter *`riid`*. Parameter *`ptr`* is set to **`nullptr`**. For more information, see Remarks. ### Remarks diff --git a/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md b/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md index 9630e0cffc5..931a152030f 100644 --- a/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md +++ b/docs/cppcx/wrl/windows-runtime-cpp-template-library-wrl.md @@ -24,7 +24,7 @@ The Windows Runtime C++ Template Library and C++/CX provide different benefits. - Windows Runtime C++ Template Library adds little abstraction over the Windows Runtime Application Binary Interface (ABI), giving you the ability to control the underlying code to better create or consume Windows Runtime APIs. -- C++/CX represents COM HRESULT values as exceptions. If you’ve inherited a code base that uses COM, or one that doesn’t use exceptions, you might find that the Windows Runtime C++ Template Library is a more natural way to work with the Windows Runtime because you don't have to use exceptions. +- C++/CX represents COM HRESULT values as exceptions. If you've inherited a code base that uses COM, or one that doesn't use exceptions, you might find that the Windows Runtime C++ Template Library is a more natural way to work with the Windows Runtime because you don't have to use exceptions. > [!NOTE] > The Windows Runtime C++ Template Library uses HRESULT values and does not throw exceptions. In addition, the Windows Runtime C++ Template Library uses smart pointers and the RAII pattern to help guarantee that objects are destroyed correctly when your application code throws an exception. For more info about smart pointers and RAII, see [Smart Pointers](../../cpp/smart-pointers-modern-cpp.md) and [Objects Own Resources (RAII)](../../cpp/object-lifetime-and-resource-management-modern-cpp.md). diff --git a/docs/cross-platform/build-an-opengl-es-application-on-android-and-ios.md b/docs/cross-platform/build-an-opengl-es-application-on-android-and-ios.md index 991d9a0c234..8f2c0764404 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,22 @@ --- 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" +ms.topic: how-to +ms.custom: sfi-image-nochange --- + # Build an OpenGL ES application on Android and iOS +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. +> OpenGL support is no longer available. It was last available in Visual Studio 17.3. + 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. +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 +24,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 +56,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/create-an-android-native-activity-app.md b/docs/cross-platform/create-an-android-native-activity-app.md index c8a88f33efc..095a2a7735a 100644 --- a/docs/cross-platform/create-an-android-native-activity-app.md +++ b/docs/cross-platform/create-an-android-native-activity-app.md @@ -2,10 +2,13 @@ description: "Learn more about: Create an Android Native Activity App" title: "Create an Android Native Activity App" ms.date: "10/17/2019" -ms.assetid: 884014b1-5208-45ec-b0da-ad0070d2c24d +ms.topic: how-to --- # Create an Android Native Activity App +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + When you install the cross-platform **Mobile development with C++** workload, Visual Studio can be used to create fully functional Android Native Activity apps. The Android Native Development Kit (NDK) is a toolset that allows you to implement the majority of your Android app using pure C/C++ code. Some Java JNI code acts as glue to allow your C/C++ code to interact with Android. The Android NDK introduced the ability to create Native Activity apps with Android API Level 9. Native Activity code is popular for creating gaming and graphic intensive apps that use Unreal Engine or OpenGL. This topic will guide you through creation of a simple Native Activity app that uses OpenGL. Additional topics walk through the developer lifecycle of editing, building, debugging and deploying Native Activity code. ## Requirements diff --git a/docs/cross-platform/cross-platform-mobile-development-examples.md b/docs/cross-platform/cross-platform-mobile-development-examples.md index c6a20033c91..4a53fea00e5 100644 --- a/docs/cross-platform/cross-platform-mobile-development-examples.md +++ b/docs/cross-platform/cross-platform-mobile-development-examples.md @@ -1,41 +1,31 @@ --- 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. +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. -- [hello-jni Android Application Sample](https://code.msdn.microsoft.com/hello-jni-Android-790ab73d) +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. - 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) - - 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. - -- [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) +- [hello-jni Android Application Sample](https://github.com/android/ndk-samples/tree/master/hello-jni) - 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. + 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. -- [MoreTeaPots Android Application Sample](https://code.msdn.microsoft.com/MoreTeaPots-Android-a9bd8549) +- [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 MoreTeaPots application. The sample demonstrates an end-to-end Java Native Interface Android OpenGL application. + 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. -- [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/general-android-prop-page.md b/docs/cross-platform/general-android-prop-page.md index 3bbadb70d3a..df6f9dd5a42 100644 --- a/docs/cross-platform/general-android-prop-page.md +++ b/docs/cross-platform/general-android-prop-page.md @@ -2,7 +2,6 @@ description: "Learn more about: General Project Properties (Android C++)" title: "General Project Properties (Android C++)" ms.date: "10/23/2017" -ms.assetid: 65f4868b-b864-4989-a275-1e51869ef599 f1_keywords: - VC.Project.VCConfiguration.Android.OutputDirectory - VC.Project.VCConfiguration.Android.IntermediateDirectory @@ -17,6 +16,9 @@ f1_keywords: --- # General Project Properties (Android C++) +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + | Property | Description | Choices | |--|--|--| | Output Directory | Specifies a relative path to the output file directory; can include environment variables. | diff --git a/docs/cross-platform/import-an-xcode-project.md b/docs/cross-platform/import-an-xcode-project.md index a536a9fc47d..1ea0c5c2e8b 100644 --- a/docs/cross-platform/import-an-xcode-project.md +++ b/docs/cross-platform/import-an-xcode-project.md @@ -2,10 +2,13 @@ description: "Learn more about: Import an Xcode project" title: "Import an Xcode project" ms.date: "10/17/2019" -ms.assetid: aa4b8161-d98f-4a1a-9db3-520133bfc82f +ms.topic: how-to --- # Import an Xcode project +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + The Visual Studio tools for cross-platform mobile development with C++ include support for moving your Xcode projects into Visual Studio, where you can create cross-platform libraries and share code with other projects. The Import from Xcode wizard simplifies the process of importing projects and splitting out the C++ code in your Xcode targets for use as a static library or shared code project. You can manage your iOS-specific code in Visual Studio and still use Xcode to do storyboards and builds. For information on how to easily move code back and forth between Visual Studio and Xcode, see [Sync changes between Xcode and Visual Studio](sync-changes-between-xcode-and-visual-studio.md). ## Use the Import From Xcode wizard diff --git a/docs/cross-platform/index.yml b/docs/cross-platform/index.yml index 60d95e09afd..789c7f8b022 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 @@ -17,7 +17,7 @@ landingContent: # Cards and links should be based on top customer tasks or top subjects # Start card title with a verb # Card (optional) - - title: Learn how to build cross-platform mobile apps + - title: Learn how to build cross-platform mobile apps linkLists: - linkListType: get-started links: @@ -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 34ad0a4084a..b0adf51b595 100644 --- a/docs/cross-platform/install-and-configure-tools-to-build-using-ios.md +++ b/docs/cross-platform/install-and-configure-tools-to-build-using-ios.md @@ -1,22 +1,27 @@ --- description: "Learn more about: Install and configure tools to build using iOS" title: "Install and configure tools to build using iOS" -ms.date: "10/17/2019" -ms.assetid: d0c311c9-9eb9-42c5-ba07-25604362cd28 -ms.custom: intro-installation +ms.date: 12/18/2022 +ms.topic: install-set-up-deploy +ms.custom: + - intro-installation + - sfi-image-nochange --- # Install and configure tools to build using iOS -You can use Visual Studio with the cross-platform **Mobile development with C++** tools to edit, debug, and deploy iOS code to the iOS Simulator or to an iOS device. But, because of licensing restrictions, the code must be built and run remotely on a Mac. To build and run iOS apps using Visual Studio, you need to set up and configure the remote agent, [vcremote](https://www.npmjs.com/package/vcremote), on your Mac. The remote agent handles build requests from Visual Studio and runs the app on an iOS device connected to the Mac, or in the iOS Simulator on the Mac. +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + +You can use Visual Studio with the cross-platform **Mobile development with C++** tools to edit, debug, and deploy iOS code to the iOS Simulator or to an iOS device. But, because of licensing restrictions, the code must be built and run remotely on a Mac. To build and run iOS apps using Visual Studio, you need to set up and configure the remote agent, [vcremote](https://www.npmjs.com/package/vcremote), on your Mac. The vcremote remote agent handles build requests from Visual Studio and runs the app on an iOS device connected to the Mac, or in the iOS Simulator on the Mac. > [!NOTE] > For information on using cloud-hosted Mac services instead of a Mac, see [Configure Visual Studio to connect to your cloud hosted Mac](/visualstudio/cross-platform/tools-for-cordova/tips-workarounds/host-a-mac-in-the-cloud?view=toolsforcordova-2017&preserve-view=true#configure-visual-studio-to-connect-to-your-cloud-hosted-mac). The instructions are for building using Visual Studio Tools for Apache Cordova. To use the instructions to build using C++, substitute `vcremote` for `remotebuild`. -Once you have installed the tools to build using iOS, refer to this article for ways to quickly configure and update the remote agent for iOS development in Visual Studio and on your Mac. +Once you've installed the tools to build using iOS, refer to this article again. It describes ways to quickly configure and update vcremote for iOS development in Visual Studio and on your Mac. ## Prerequisites -To install and use the remote agent to develop code for iOS, you must first have these prerequisites: +To install and use the vcremote remote agent to develop code for iOS, you must first have these prerequisites: - A Mac computer running macOS Mojave version 10.14 or later @@ -26,7 +31,7 @@ To install and use the remote agent to develop code for iOS, you must first have You can get a free account that allows sideloading apps to an iOS device for testing only but not for distribution. -- [Xcode](https://developer.apple.com/xcode/downloads/) version 10.2.1 or later +- [Xcode](https://apps.apple.com/us/app/xcode/id497799835?mt=12/) version 10.2.1 or later Xcode can be downloaded from the App Store. @@ -42,25 +47,25 @@ To install and use the remote agent to develop code for iOS, you must first have For detailed information on signing requirements, see [What is app signing](https://help.apple.com/xcode/mac/current/#/dev3a05256b8). -- If you are using an iOS device for development, a provisioning Profile configured in Xcode for your device +- If you're using an iOS device for development, a provisioning Profile configured in Xcode for your device - Xcode provides automatic signing where it creates signing certificates for you as needed. For detailed information about Xcode automatic signing see [automatic signing](https://help.apple.com/xcode/mac/current/#/dev80cc24546). + Xcode provides automatic signing, where it creates signing certificates for you as needed. For detailed information about Xcode automatic signing, see [automatic signing](https://help.apple.com/xcode/mac/current/#/dev80cc24546). If you want to do manual signing, you need to create a provisioning Profile for your app. For detailed information on creating provisioning Profiles, see [Create a development provisioning profile](https://help.apple.com/developer-account/#/devf2eb157f8). -- [Node.js](https://nodejs.org/) version 12.14.1 and npm version 6.13.4 +- [Node.js](https://nodejs.org/dist/v18.12.1/node-v18.12.1.pkg) version 18.12.1 and npm version 8.19.2 - Install version 12.14.1 of Node.js on your Mac. If you install the Node.js package, it should come with npm version 6.13.4. Other versions of Node.js and npm may not support some modules used in the remote agent `vcremote`, which can cause `vcremote` installation to fail. We recommend you install Node.js by using a package manager such as [Node Version Manager](https://nodejs.org/en/download/package-manager/#nvm). Avoid using the command `sudo` to install Node.js, as some modules can fail to install when using `sudo`. + Install version 18.12.1 of Node.js on your Mac. If you install the Node.js package, it should come with npm version 8.19.2. Other versions of Node.js and npm may not support some modules used in vcremote, which can cause vcremote installation to fail. We recommend you install Node.js by using a package manager such as [Node Version Manager](https://nodejs.org/en/download/package-manager/#nvm). Avoid using the command `sudo` to install Node.js, as some modules can fail to install when using sudo. -## Install the remote agent for iOS +## Install vcremote for iOS -When you install the Mobile development with C++ workload, Visual Studio can communicate with [vcremote](https://www.npmjs.com/package/vcremote), a remote agent running on your Mac to transfer files, build and run your iOS app, and send debugging commands. +When you install the Mobile development with C++ workload, Visual Studio can communicate with the [vcremote](https://www.npmjs.com/package/vcremote) remote agent running on your Mac to transfer files, build and run your iOS app, and send debugging commands. -Before you install the remote agent, make sure you have satisfied the [Prerequisites](#prerequisites) and completed the installation steps in [Install cross-platform mobile development with C++](../cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md#install-the-tools). +Before you install vcremote, make sure you've satisfied the [Prerequisites](#prerequisites) and completed the installation steps in [Install cross-platform mobile development with C++](../cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md#install-the-tools). -### To download and install the remote agent +### To download and install vcremote -- From the Terminal app on your Mac, verify that the Node.js version currently in use is the required version 12.14.1. To verify the version, run the command: +- From the Terminal app on your Mac, verify that the Node.js version currently in use is the required version 18.12.1. To verify the version, run the command: `node -v` @@ -75,35 +80,44 @@ Before you install the remote agent, make sure you have satisfied the [Prerequis During the installation, `vcremote` is installed and developer mode is activated on your Mac. [Homebrew](https://brew.sh/) and two npm packages, `vcremote-lib` and `vcremote-utils`, are also installed. When installation completes, it's safe to ignore any warnings about skipped optional dependencies. > [!NOTE] - > To install Homebrew, you must have sudo (administrator) access. If you need to install `vcremote` without sudo, you can install Homebrew manually in a usr/local location and add its bin folder to your path. For more information, see the [Homebrew documentation](https://github.com/Homebrew/homebrew/wiki/Installation). To manually enable developer mode, enter this command in the Terminal app: `DevToolsSecurity -enable` + > To install Homebrew, you must have sudo (administrator) access. If you need to install vcremote without sudo, you can install Homebrew manually in a `usr/local` location and add its `bin` folder to your path. For more information, see the [Homebrew documentation](https://github.com/Homebrew/homebrew/wiki/Installation). To manually enable developer mode, enter this command in the Terminal app: `DevToolsSecurity -enable` + +If you update to a new version of Visual Studio, you must update to the current version of vcremote as well. To update vcremote, repeat the steps to download and install the remote agent. -If you update to a new version of Visual Studio, you must update to the current version of the remote agent as well. To update the remote agent, repeat the steps to download and install the remote agent. +## Start vcremote -## Start the remote agent +The vcremote remote agent must be running for Visual Studio to build and run your iOS code. Visual Studio must be paired with vcremote before it can communicate. By default, vcremote runs in *secured connection mode*, which requires the transferring of client and server certificates between the Visual Studio and Mac machines. -The remote agent must be running for Visual Studio to build and run your iOS code. Visual Studio must be paired with the remote agent before it can communicate. By default, the remote agent runs in secured connection mode, which requires a PIN to pair with Visual Studio. + > [!NOTE] + > Version 1.0.19 or later of vcremote requires at least Visual Studio 2022 version 17.5.0 Preview 1 or later. If you're using Visual Studio 2022 version 17.4 or an earlier version, install vcremote version 1.0.17. -### To start the remote agent +### To start vcremote - From the Terminal app on your Mac, enter: `vcremote` - This command starts the remote agent with a default build directory of `~/vcremote`. For additional configuration options, see [Configure the remote agent on the Mac](#ConfigureMac). + This command starts the remote agent with a default build directory of *`~/vcremote`*. For more configuration options, see [Configure vcremote on the Mac](#ConfigureMac). + +The first time you start vcremote, and every time you create a new server certificate, you're provided with the required information to configure the connection in Visual Studio. The information includes the host name and the port. If you intend to configure the remote agent in Visual Studio using the host name, ping the Mac from Windows using the host name to verify that it's reachable. Otherwise, you may need to use the IP address instead. + +You can use the remote agent in unsecured mode. In unsecured mode, the remote agent can be paired to Visual Studio using a simple HTTP connection that doesn't encrypt data. Use unsecured mode at your own risk. We recommend you use a secure mode to connect: -The first time you start the agent, and every time you create a new client certificate, you are provided with the required information to configure the agent in Visual Studio, including the host name, the port, and the PIN. +**Visual Studio 2022 version 17.5 and later with vcremote 1.0.19 and later:** -![Use vcremote to generate a secure PIN.](../cross-platform/media/cppmdd-vcremote-generateclientcert.png "Use vcremote to generate a secure PIN") +In vcremote 1.0.19 and later, vcremote reports the path to a *`server-cert.pem`* certificate file, which must be uploaded to Visual Studio. -If you intend to configure the remote agent in Visual Studio using the host name, ping the Mac from Windows using the host name to verify that it is reachable. Otherwise, you may need to use the IP address instead. +**Visual Studio 2022 version 17.4 and earlier versions with vcremote 1.0.17 and earlier:** -The generated PIN is for one time use, and is only valid for a limited time. If you do not pair Visual Studio with the remote agent before the time expires, you will need to generate a new PIN. For more information, see [Generate a new security PIN](#GeneratePIN). +Version 1.0.17 and older versions of vcremote generate a PIN for secure communication with versions of Visual Studio through Visual Studio 2022 version 17.4. -You can use the remote agent in unsecured mode. In unsecured mode, the remote agent can be paired to Visual Studio without a PIN. +:::image type="content" source="media/cppmdd-vcremote-generateclientcert.png" alt-text="Screenshot of the Mac Terminal window that shows the host name, port, and PIN reported when VC remote is started."::: + +The generated PIN is for one time use, and is only valid for a limited time. If you don't pair Visual Studio with the remote agent before the time expires, you'll need to generate a new PIN. For more information, see [Generate a new security PIN](#GeneratePIN). #### To disable secured connection mode -- To disable secured connection mode in `vcremote`, enter this command in the Terminal app on your Mac: +- To disable secured connection mode in vcremote, enter this command in the Terminal app on your Mac: `vcremote --secure false` @@ -113,27 +127,61 @@ You can use the remote agent in unsecured mode. In unsecured mode, the remote ag `vcremote --secure true` -Once you have started the remote agent, you can use it from Visual Studio until you stop it. +Once you've started the remote agent, you can use it from Visual Studio until you stop it. #### To stop the remote agent -- In the Terminal window `vcremote` is running in, enter **Control**+**C**. +- In the Terminal window vcremote is running in, enter **Control**+**C**. -## Configure the remote agent in Visual Studio +## Configure vcremote in Visual Studio -To connect to the remote agent from Visual Studio, you must specify the remote configuration in the Visual Studio options. +To connect to the vcremote remote agent from Visual Studio, you must specify the remote configuration in the Visual Studio options. Visual Studio uses the same information to connect to the remote agent on your Mac each time you use it. You don't need to pair Visual Studio with the remote agent again unless you generate a new security certificate on your Mac, or its hostname or IP address changes. -### To configure the remote agent from Visual Studio +### To configure vcremote from Visual Studio 2022 version 17.5 and later -1. If the agent is not already running on your Mac, follow the steps in [Start the remote agent](#Start). Your Mac must be running `vcremote` for Visual Studio to successfully pair, connect, and build your project. +1. If the agent isn't already running on your Mac, follow the steps in [Start the remote agent](#Start). Your Mac must be running vcremote for Visual Studio to successfully pair, connect, and build your project. 1. On your Mac, get the host name or IP address of your Mac. - You can get the IP address by using the **ifconfig** command in a Terminal window. Use the inet address listed under the active network interface. + You can get the IP address by using the **ifconfig** command in a Terminal window. Use the `inet` address listed under the active network interface. -1. On the Visual Studio menu bar, choose **Tools**, **Options**. +1. On the Visual Studio menu bar, choose **Tools** > **Options**. -1. In the **Options** dialog box, expand **Cross Platform**, **C++**, **iOS**. +1. In the **Options** dialog box, expand **Cross Platform** > **C++** > **iOS**. + +1. In the **Host Name** and **Port** fields, enter the values specified by the remote agent when you started it. The host name can be the DNS name or IP address of your Mac. The default port is 3030. + + > [!NOTE] + > If you can't ping the Mac using the host name, you may need to use the IP address. + +1. If you use the remote agent in the default secured connection mode, check the **Secure** checkbox, and transfer the *`server-cert.pem`* file from the Mac to Visual Studio for uploading. Next, choose the **Generate** button to generate a new *`client-cert.pem`* file, which should appear on the desktop. Then, transfer the client certificate to the Mac under *`/vcremote/certs/Authorized-Clients`*. (You may transfer multiple client certificate files to this directory, so multiple authorized Visual Studio machines can send requests to this Mac.) + + > [!NOTE] + > If you're using a USB drive to transfer certificates, delete the certificates from the USB drive after the transfer is complete. + +1. Choose **Pair** to enable the pairing. + + :::image type="content" source="media/cppmdd-options-ios-new.png" alt-text="Screenshot of the Tools Options dialog for iOS pairing. The host name, the port, the Secure checkbox, and the Remote Root values are set."::: + + The pairing persists until you change the host name, port, or generate a new server or client certificate. If you change the host name or port in the **Options** dialog box, you can choose the **Revert** button to undo the change and revert to the previous pairing. + + If the pairing doesn't succeed, verify that the remote agent is running by following the steps in [Start the remote agent](#Start). Follow the steps to [Generate a new server certificate](#GenerateServerCert) and [Generate a new client certificate](#GenerateClientCert). If you're using the host name of your Mac, try using the IP address in the **Host Name** field instead. + +1. Update the folder name in the **Remote Root** field to specify the folder used by the remote agent in your home (*`~`*) directory on the Mac. By default, the remote agent uses *`/Users//vcremote`* as the remote root. + +1. Choose **OK** to save the remote pairing connection settings. + +### To configure vcremote from versions before Visual Studio 2022 version 17.5 + +1. If the agent isn't already running on your Mac, follow the steps in [Start the remote agent](#Start). Your Mac must be running vcremote for Visual Studio to successfully pair, connect, and build your project. + +1. On your Mac, get the host name or IP address of your Mac. + + You can get the IP address by using the **ifconfig** command in a Terminal window. Use the `inet` address listed under the active network interface. + +1. On the Visual Studio menu bar, choose **Tools** > **Options**. + +1. In the **Options** dialog box, expand **Cross Platform** > **C++** > **iOS**. 1. In the **Host Name** and **Port** fields, enter the values specified by the remote agent when you started it. The host name can be the DNS name or IP address of your Mac. The default port is 3030. @@ -144,21 +192,21 @@ To connect to the remote agent from Visual Studio, you must specify the remote c 1. Choose **Pair** to enable the pairing. - ![Configure vcremote connection for iOS builds.](../cross-platform/media/cppmdd-options-ios.png "Configure vcremote connection for iOS builds") + :::image type="content" source="media/cppmdd-options-ios-old.png" alt-text="Screenshot of the Tools Options dialog for iOS pairing. The host name, the port, the Secure checkbox, the pin, and the Remote Root values are set."::: The pairing persists until you change the host name or port. If you change the host name or port in the **Options** dialog box, to undo the change, choose the **Revert** button to revert to the previous pairing. - If the pairing does not succeed, verify that the remote agent is running by following the steps in [Start the remote agent](#Start). If too much time has passed since the remote agent PIN was generated, follow the steps in [Generate a new security PIN](#GeneratePIN) on the Mac and then try again. If you are using the host name of your Mac, try using the IP address in the **Host Name** field instead. + If the pairing doesn't succeed, verify that the remote agent is running by following the steps in [Start the remote agent](#Start). If too much time has passed since the remote agent PIN was generated, follow the steps in [Generate a new security PIN](#GeneratePIN). Then try again. If you're using the host name of your Mac, try using the IP address in the **Host Name** field instead. -1. Update the folder name in the **Remote Root** field to specify the folder used by the remote agent in your home (*~*) directory on the Mac. By default, the remote agent uses `/Users//vcremote` as the remote root. +1. Update the folder name in the **Remote Root** field to specify the folder used by the remote agent in your home (*`~`*) directory on the Mac. By default, the remote agent uses `/Users//vcremote` as the remote root. 1. Choose **OK** to save the remote pairing connection settings. -Visual Studio uses the same information to connect to the remote agent on your Mac each time you use it. You do not need to pair Visual Studio with the remote agent again unless you generate a new security certificate on your Mac, or its hostname or IP address changes. - ## Generate a new security PIN -When you start the remote agent the first time, the generated PIN is valid for a limited amount of time—by default, 10 minutes. If you don't pair Visual Studio to the remote agent before the time expires, you will need to generate a new PIN. +**Applies to: Visual Studio 2022 version 17.4 and earlier versions, using vcremote version 1.0.17 and earlier.** + +When you start the remote agent the first time, the generated PIN is valid for a limited amount of time—by default, 10 minutes. If you don't pair Visual Studio to the remote agent before the time expires, you'll need to generate a new PIN. ### To generate a new PIN @@ -170,7 +218,15 @@ When you start the remote agent the first time, the generated PIN is valid for a The remote agent generates a new temporary PIN. To pair Visual Studio by using the new PIN, repeat the steps in [Configure the remote agent in Visual Studio](#ConfigureVS). -## Generate a new server certificate +## Generate a new client certificate + +**Applies to: Visual Studio 2022 version 17.5 and later versions, using vcremote version 1.0.19 and later.** + +When you pair on Visual Studio, you'll generate a new *`client-cert.pem`* file. Transfer the certificate file to the Mac build machine under *`/vcremote/certs/Authorized-Clients`*. This certificate allows the Mac to authorize requests that come from your Visual Studio machine. + +## Generate a new server certificate + +**Applies to: Visual Studio 2022 version 17.5 and later versions, using vcremote version 1.0.19 and later.** For security purposes, the server certificates that pair Visual Studio with the remote agent are tied to the IP address or host name of your Mac. If these values change, you must generate a new server certificate, and then reconfigure Visual Studio with the new values. @@ -184,15 +240,9 @@ For security purposes, the server certificates that pair Visual Studio with the 1. When prompted for confirmation, enter `Y`. -1. Enter this command in the Terminal app: - - `vcremote generateClientCert` - - This command generates a new temporary PIN. - -1. To pair Visual Studio by using the new PIN, repeat the steps in [Configure the remote agent in Visual Studio](#ConfigureVS). +1. To pair Visual Studio with the Mac, transfer the newly generated *`server-cert.pem`* file from the Mac and upload it to Visual Studio, repeating the steps in [Configure the remote agent in Visual Studio](#ConfigureVS). -## Configure the remote agent on the Mac +## Configure vcremote on the Mac You can configure the remote agent using various command-line options. For example, you can specify the port to listen for build requests and specify the maximum number of builds to maintain on the file system. By default, the limit is 10 builds. The remote agent will remove builds that exceed the maximum on shutdown. @@ -206,31 +256,31 @@ You can configure the remote agent using various command-line options. For examp `vcremote --secure false` - When you use this option, clear the **Secure** checkbox and leave the **Pin** field blank when configuring the agent in Visual Studio. + When you use this option, clear the **Secure** checkbox. - To specify a location for remote agent files, enter: `vcremote --serverDir directory_path` - where *directory_path* is the location on your Mac to place log files, builds, and server certificates. By default, this location is `/Users//vcremote`. Builds are organized by build number in this location. + Replace `directory_path` with the location on your Mac to place log files, builds, and server certificates. By default, this location is *`/Users//vcremote`*. Builds are organized by build number in this location. -- To use a background process to capture `stdout` and `stderr` to a file named server.log, enter: +- To use a background process to capture `stdout` and `stderr` to a file named *`server.log`*, enter: `vcremote > server.log 2>&1 &` - The server.log file can assist in troubleshooting build issues. + The *`server.log`* file can help troubleshooting build issues. - To run the agent by using a configuration file instead of command-line parameters, enter: `vcremote --config config_file_path` - where *config_file_path* is the path to a configuration file in JSON format. The startup options and their values must not include dashes. + Replace `config_file_path` with the path to a configuration file in JSON format. The startup options and their values must not include dashes. ## Troubleshoot the remote agent ### Debugging on an iOS device -If debugging on an iOS device does not work, there could be issues with the tool [ideviceinstaller](https://github.com/libimobiledevice/ideviceinstaller), which is used to communicate with an iOS device. This tool is typically installed from Homebrew during the installation of `vcremote`. Follow the steps below as a workaround. +If debugging on an iOS device doesn't work, there could be issues with the [`ideviceinstaller`](https://github.com/libimobiledevice/ideviceinstaller) tool, which is used to communicate with an iOS device. This tool is typically installed from Homebrew during the installation of `vcremote`. Follow the next steps as a workaround: Open the Terminal app and update `ideviceinstaller` and its dependencies by running the following commands in order: @@ -264,7 +314,7 @@ Verify that `ideviceinstaller` can communicate with the device by trying to list `ideviceinstaller -l` -If `ideviceinstaller` errors that it cannot access the folder `/var/db/lockdown`, change the privilege on the folder with: +If `ideviceinstaller` reports an error that it can't access the folder `/var/db/lockdown`, change the privilege on the folder using this command: `sudo chmod 777 /var/db/lockdown` diff --git a/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md b/docs/cross-platform/install-visual-cpp-for-cross-platform-mobile-development.md index 5d610defde3..abd451551b8 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,15 @@ 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 +ms.topic: install-set-up-deploy --- # 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. +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + +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 +33,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 +65,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 +90,11 @@ You can use Visual Studio to edit, debug, and deploy iOS code to the iOS Simulat You don't have to install all the third-party dependencies when you install the **Mobile development with C++** workload (or in Visual Studio 2015, the Visual C++ Mobile Development option). Install them later by using the steps in [Install the tools](#install-the-tools). The Visual Studio Installer is updated regularly to install the latest third-party components. Use it to install updated SDKs and NDKs. You can also install or update them independently of Visual Studio. -You can run the SDK Manager app in the Android SDK directory again to update the SDK. And, to install optional tools and additional API levels. Updates may fail to install unless you use **Run as administrator** to run the SDK Manager app. If you have problems building an Android app, check the SDK Manager for updates to your installed SDKs. +You can run the SDK Manager app in the Android SDK directory again to update the SDK. And, to install optional tools and other API levels. Updates may fail to install unless you use **Run as administrator** to run the SDK Manager app. If you have problems building an Android app, check the SDK Manager for updates to your installed SDKs. -To use some of the Android SDK emulators, you may need to set up hardware acceleration. For more information, see [Hardware acceleration for emulator performance (Hyper-V & HAXM)](/xamarin/android/get-started/installation/android-emulator/hardware-acceleration?tabs=vswin). +To use some of the Android SDK emulators, you may need to set up hardware acceleration. For more information, see [How to enable hardware acceleration with Android emulators (Hyper-V & AEHD)](/dotnet/maui/android/emulator/hardware-acceleration). -In most cases, Visual Studio can detect the configurations for the third-party software you've installed. It maintains the installation paths in internal environment variables. You can override the default paths of these cross-platform development tools in the Visual Studio IDE. +In most cases, Visual Studio can detect the configurations for installed third-party software. It maintains the installation paths in internal environment variables. You can override the default paths of these cross-platform development tools in the Visual Studio IDE. ### To set the paths for third-party tools diff --git a/docs/cross-platform/media/cppmdd-options-ios-new.png b/docs/cross-platform/media/cppmdd-options-ios-new.png new file mode 100644 index 00000000000..4a79c5d2006 Binary files /dev/null and b/docs/cross-platform/media/cppmdd-options-ios-new.png differ diff --git a/docs/cross-platform/media/cppmdd-options-ios.png b/docs/cross-platform/media/cppmdd-options-ios-old.png similarity index 100% rename from docs/cross-platform/media/cppmdd-options-ios.png rename to docs/cross-platform/media/cppmdd-options-ios-old.png diff --git a/docs/cross-platform/sync-changes-between-xcode-and-visual-studio.md b/docs/cross-platform/sync-changes-between-xcode-and-visual-studio.md index 834a4af4463..415ec583ea6 100644 --- a/docs/cross-platform/sync-changes-between-xcode-and-visual-studio.md +++ b/docs/cross-platform/sync-changes-between-xcode-and-visual-studio.md @@ -2,10 +2,12 @@ description: "Learn more about: Sync changes between Xcode and Visual Studio" title: "Sync changes between Xcode and Visual Studio" ms.date: "10/17/2019" -ms.assetid: c71a4d7c-120e-4559-a114-3a99c4b860a9 --- # Sync changes between Xcode and Visual Studio +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + The mobile development with C++ components in Visual Studio include remote capabilities for syncing your work between your PC and your Mac. When your Visual Studio and Mac machines are paired, new options are available for iOS Application projects in Visual Studio that you can use to open your project in Xcode, move your code between Xcode and Visual Studio, and clean the temporary Xcode project directory. To use the Remote Machine options, your project must be an iOS Application project, and Visual Studio must be paired with your Mac. For prerequisites and instructions on how to pair a Mac, see [Install and configure tools to build using iOS](../cross-platform/install-and-configure-tools-to-build-using-ios.md). diff --git a/docs/cross-platform/toc.yml b/docs/cross-platform/toc.yml index 4446b6541ff..22771c639f1 100644 --- a/docs/cross-platform/toc.yml +++ b/docs/cross-platform/toc.yml @@ -2,7 +2,7 @@ items: - name: Cross-platform mobile development with C++ href: ../cross-platform/index.yml - name: Overview - href: ../cross-platform/visual-cpp-for-cross-platform-mobile-development.md + href: ../cross-platform/visual-cpp-for-cross-platform-mobile-development.md - name: Get Started expanded: true items: diff --git a/docs/cross-platform/visual-cpp-for-cross-platform-mobile-development.md b/docs/cross-platform/visual-cpp-for-cross-platform-mobile-development.md index 561a0d7c2d8..997d8893371 100644 --- a/docs/cross-platform/visual-cpp-for-cross-platform-mobile-development.md +++ b/docs/cross-platform/visual-cpp-for-cross-platform-mobile-development.md @@ -1,11 +1,13 @@ --- description: "Learn more about: Cross-platform mobile development with C++" title: "Cross-platform mobile development with C++" -ms.date: "11/14/2019" -ms.assetid: 0bb872d6-981b-4c96-9143-fcec5336bf0d +ms.date: 11/07/2025 --- # Cross-platform mobile development with C++ +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + You can build native C++ apps for iOS, Android, and Windows devices by using the cross-platform tools available in Visual Studio. **Mobile development with C++** is a workload available in the Visual Studio installer. It installs the SDKs and tools you need for cross-platform development of shared libraries and native apps. When it's installed, you can use C++ to create code that runs on iOS and Android devices and platforms, Windows, Windows Store, and Xbox. Writing code for multiple platforms is often frustrating. The primary development languages and tools for iOS, Android, and Windows are different on each platform. However, all platforms support writing code in C++. It's the common denominator that can enable reuse of core code across platforms. Native code written in C++ can be both more performant and resistant to reverse engineering. Code reuse can save both time and effort when creating apps for multiple platforms. diff --git a/docs/data/catalog-information-mfc-data-access.md b/docs/data/catalog-information-mfc-data-access.md index 6935e8ae313..39e786d3e45 100644 --- a/docs/data/catalog-information-mfc-data-access.md +++ b/docs/data/catalog-information-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Catalog Information (MFC Data Access)" -title: "Catalog Information (MFC Data Access)" -ms.date: "11/04/2016" +title: "Catalog Information (MFC Data Access)" +description: "Learn more about: Catalog Information (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["tables [C++], catalog information", "tables [C++]", "ODBC [C++], catalog information", "catalog information database [C++]", "databases [C++], catalog information database"] -ms.assetid: c184e80f-ff17-409f-9df8-05275080bb8d --- -# Catalog Information (MFC Data Access) +# Catalog Information (MFC Data Access) Information about the tables in a data source can include the names of tables and the columns in them, table privileges, names of primary and foreign keys, information about predefined queries or stored procedures, information about indexes on tables, and statistics about tables. 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 e2555def69d..36779b2c17c 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,11 +1,10 @@ --- -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)" -ms.date: "11/04/2016" +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) +# Changes You Might Make to the Default Code (MFC Data Access) The [MFC Application Wizard](../mfc/reference/database-support-mfc-application-wizard.md) writes a recordset class for you that selects all records in a single table. You will often want to modify that behavior in one or more of the following ways: @@ -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/command-handlers-for-record-scrolling-mfc-data-access.md b/docs/data/command-handlers-for-record-scrolling-mfc-data-access.md index 62d9a45c139..5974a0a0173 100644 --- a/docs/data/command-handlers-for-record-scrolling-mfc-data-access.md +++ b/docs/data/command-handlers-for-record-scrolling-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Command Handlers for Record Scrolling (MFC Data Access)" -title: "Command Handlers for Record Scrolling (MFC Data Access)" -ms.date: "11/04/2016" +title: "Command Handlers for Record Scrolling (MFC Data Access)" +description: "Learn more about: Command Handlers for Record Scrolling (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["record views [C++], scrolling", "record scrolling [C++]", "scrolling records"] -ms.assetid: f8b13477-2a37-459e-a30c-806fb78165ac --- -# Command Handlers for Record Scrolling (MFC Data Access) +# Command Handlers for Record Scrolling (MFC Data Access) The [CRecordView](../mfc/reference/crecordview-class.md) class provides default command handling for the following standard commands: diff --git a/docs/data/data-access-in-cpp.md b/docs/data/data-access-in-cpp.md index 9ac4a727550..f9f8add32c0 100644 --- a/docs/data/data-access-in-cpp.md +++ b/docs/data/data-access-in-cpp.md @@ -20,18 +20,18 @@ Describes legacy data access programming with Visual C++, where the preferred wa The Microsoft Foundation Classes (MFC) library supplies classes for programming with Open Database Connectivity (ODBC). [OLE DB Programming](oledb/ole-db-programming.md)
-A mostly legacy interface which is still required in some scenarios, specifically when you are programming against linked servers. +A mostly legacy interface which is still required in some scenarios, specifically when you're programming against linked servers. ## Related Topics [Connect to SQL Database using C and C++](/azure/sql-database/sql-database-develop-cplusplus-simple)
Connect to Azure SQL Database from C or C++ applications. -[Microsoft Azure Storage Client Library for C++](https://github.com/Azure/azure-storage-cpp)
-[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++. +[Azure SDK for C++](/azure/developer/cpp/sdk/overview)
+[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 SDK 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/data-access-programming-mfc-atl.md b/docs/data/data-access-programming-mfc-atl.md index c2dda6ed1d6..f98e765142a 100644 --- a/docs/data/data-access-programming-mfc-atl.md +++ b/docs/data/data-access-programming-mfc-atl.md @@ -3,10 +3,12 @@ description: "Learn more about: Data Access Programming (MFC/ATL)" title: "Data Access Programming (MFC-ATL)" ms.date: "11/16/2018" helpviewer_keywords: ["MFC [C++], data access applications", "databases [C++], MFC", "OLE DB [C++], data access technologies", "data [C++], data access technologies", "data access [C++], class libraries for databases"] -ms.assetid: def97b2c-b5a6-445f-afeb-308050fd4852 --- # Data Access Programming (MFC/ATL) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) and Active Template Library (ATL) libraries continue to be supported. However, we're no longer adding features or updating the documentation. + Over the years, Visual C++ has provided several ways to work with databases. In 2011 Microsoft announced that it is aligning on Open Database Connectivity (ODBC) as the preferred technology for accessing SQL Server products from native code. ODBC is an industry standard, and by using it you gain maximum portability of your code over multiple platforms and data sources. Most SQL database products and many NoSQL products support ODBC. You can use ODBC directly by calling the low-level ODBC APIs, or you can use the MFC ODBC wrapper classes, or a third-party C++ wrapper library. OLE DB is a low-level, high-performance API based on the COM specification, and is only supported on Windows. Use OLE DB if your program is accessing [linked servers](/sql/relational-databases/linked-servers/linked-servers-database-engine). ATL provides OLE DB templates that make it easier to create custom OLE DB providers and consumers. The most recent provider for Microsoft SQL Server can be found in the documentation for the [OLE DB Driver for SQL Server](/sql/connect/oledb/oledb-driver-for-sql-server). diff --git a/docs/data/data-exchange-for-record-views-mfc-data-access.md b/docs/data/data-exchange-for-record-views-mfc-data-access.md index 08307d190cf..cf7e9e780d0 100644 --- a/docs/data/data-exchange-for-record-views-mfc-data-access.md +++ b/docs/data/data-exchange-for-record-views-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Data Exchange for Record Views (MFC Data Access)" -title: "Data Exchange for Record Views (MFC Data Access)" -ms.date: "11/19/2018" +title: "Data Exchange for Record Views (MFC Data Access)" +description: "Learn more about: Data Exchange for Record Views (MFC Data Access)" +ms.date: 11/19/2018 helpviewer_keywords: ["RFX (record field exchange), data exchange mechanism", "RFX (record field exchange), record views", "record views, data exchange", "DDX (dialog data exchange), record views", "RFX (record field exchange)"] -ms.assetid: abc52ca7-6997-47a7-98f3-f347f52b1f72 --- -# Data Exchange for Record Views (MFC Data Access) +# Data Exchange for Record Views (MFC Data Access) When you use [Add Class](../mfc/reference/adding-an-mfc-odbc-consumer.md) to map the controls in a record view's dialog template resource to the fields of a recordset, the framework manages data exchange in both directions — from recordset to controls and from controls to recordset. Using the DDX mechanism means that you do not have to write the code to transfer data back and forth yourself. diff --git a/docs/data/designing-and-creating-a-record-view-mfc-data-access.md b/docs/data/designing-and-creating-a-record-view-mfc-data-access.md index aa747752af9..82d8ec88812 100644 --- a/docs/data/designing-and-creating-a-record-view-mfc-data-access.md +++ b/docs/data/designing-and-creating-a-record-view-mfc-data-access.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Designing and Creating a Record View (MFC Data Access)" -title: "Designing and Creating a Record View (MFC Data Access)" -ms.date: "11/04/2016" +title: "Designing and Creating a Record View (MFC Data Access)" +description: "Learn more about: Designing and Creating a Record View (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["designing forms", "record views, creating", "forms [C++], designing", "record views, designing", "application wizards [C++], creating record view classes", "designing record views"] -ms.assetid: 1d6f5439-754f-4b8b-a19d-841a4657827b +ms.topic: how-to --- -# Designing and Creating a Record View (MFC Data Access) +# Designing and Creating a Record View (MFC Data Access) You can create your record view class with the [MFC Application Wizard](../mfc/reference/database-support-mfc-application-wizard.md). If you use an application wizard, it creates the record view class and a dialog template resource for it (without controls). You must use the Visual C++ Dialog editor to add controls to the dialog template resource. On the other hand, if you use **Add Class**, you must first create the dialog template resource in the Dialog editor and then create the record view class. diff --git a/docs/data/features-of-record-view-classes-mfc-data-access.md b/docs/data/features-of-record-view-classes-mfc-data-access.md index 0f19f101bda..4b5aa7499ed 100644 --- a/docs/data/features-of-record-view-classes-mfc-data-access.md +++ b/docs/data/features-of-record-view-classes-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Features of Record View Classes (MFC Data Access)" -title: "Features of Record View Classes (MFC Data Access)" -ms.date: "11/04/2016" +title: "Features of Record View Classes (MFC Data Access)" +description: "Learn more about: Features of Record View Classes (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["record views, classes", "record view classes"] -ms.assetid: e7b2820f-09c4-483f-83c0-317e8be42bdf --- -# Features of Record View Classes (MFC Data Access) +# Features of Record View Classes (MFC Data Access) You can do form-based data-access programming with class [CFormView](../mfc/reference/cformview-class.md), but [CRecordView](../mfc/reference/crecordview-class.md) is generally a better class to derive from. In addition to its `CFormView` features, `CRecordView`: diff --git a/docs/data/filling-a-list-box-from-a-second-recordset-mfc-data-access.md b/docs/data/filling-a-list-box-from-a-second-recordset-mfc-data-access.md index 78104b47fc8..23a02764b2d 100644 --- a/docs/data/filling-a-list-box-from-a-second-recordset-mfc-data-access.md +++ b/docs/data/filling-a-list-box-from-a-second-recordset-mfc-data-access.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Filling a List Box from a Second Recordset (MFC Data Access)" -title: "Filling a List Box from a Second Recordset (MFC Data Access)" -ms.date: "11/04/2016" +title: "Filling a List Box from a Second Recordset (MFC Data Access)" +description: "Learn more about: Filling a List Box from a Second Recordset (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["record views, filling list boxes", "list boxes, filling from second recordset", "recordsets [C++], filling list boxes or combo boxes", "CComboBox class, filling object from second rowset", "ODBC recordsets [C++], filling list boxes or combo boxes", "combo boxes [C++], filling from second recordset", "CListCtrl class, filling from second recordset"] -ms.assetid: 360c0834-da6b-4dc0-bcea-80e9acd611f0 +ms.topic: how-to --- -# Filling a List Box from a Second Recordset (MFC Data Access) +# Filling a List Box from a Second Recordset (MFC Data Access) By default, a record view is associated with a single recordset object, whose fields are mapped to the record view's controls. Sometimes you might want to put a list box or combo box control in your record view and fill it with values from a second recordset object. The user can use the list box to select a new category of information to display in the record view. This topic explains how and when to do that. diff --git a/docs/data/installing-database-support-mfc-atl.md b/docs/data/installing-database-support-mfc-atl.md index d4a6c7cfbdc..6a63eec21ef 100644 --- a/docs/data/installing-database-support-mfc-atl.md +++ b/docs/data/installing-database-support-mfc-atl.md @@ -5,10 +5,11 @@ ms.date: "11/04/2016" helpviewer_keywords: ["data access [C++], installing database support", "installing database support", "ATL [C++], database support", "databases [C++], installing database support"] ms.assetid: 3820ba96-4fb8-4405-83dd-bb3bc5998667 ms.custom: intro-installation +ms.topic: concept-article --- # 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/connecting-to-a-data-source.md b/docs/data/odbc/connecting-to-a-data-source.md index 18a727d5a83..52845dfa96b 100644 --- a/docs/data/odbc/connecting-to-a-data-source.md +++ b/docs/data/odbc/connecting-to-a-data-source.md @@ -4,6 +4,7 @@ title: "Connecting to a Data Source" ms.date: "11/04/2016" helpviewer_keywords: ["database connections [C++], ODBC", "ODBC connections [C++], using", "connections [C++], data source", "databases [C++], connecting to", "data sources [C++], connecting to", "ODBC data sources [C++], connections", "database connections [C++], MFC ODBC classes"] ms.assetid: ef6c8c98-5979-43a8-9fb5-5bb06fc59f36 +ms.topic: concept-article --- # Connecting to a Data Source diff --git a/docs/data/odbc/data-source-managing-connections-odbc.md b/docs/data/odbc/data-source-managing-connections-odbc.md index 3c08f7c6a11..8667ed49931 100644 --- a/docs/data/odbc/data-source-managing-connections-odbc.md +++ b/docs/data/odbc/data-source-managing-connections-odbc.md @@ -4,6 +4,7 @@ title: "Data Source: Managing Connections (ODBC)" ms.date: "11/04/2016" helpviewer_keywords: ["ODBC data sources [C++], multiuser environments", "generalizing connection strings", "ODBC [C++], disconnecting from data sources", "connection strings [C++], generalizing", "database connections [C++], creating", "GetDefaultConnect method", "connections [C++], data source", "ODBC connections [C++], configuring", "disconnecting from data sources", "databases [C++], connecting to", "ODBC connections [C++], disconnecting", "data sources [C++], connecting to", "ODBC connections [C++], connecting to data source", "ODBC data sources [C++], connections", "database connections [C++], MFC ODBC classes"] ms.assetid: c0adbcdd-c000-40c6-b199-09ffdc7b6ef2 +ms.custom: sfi-ropc-nochange --- # Data Source: Managing Connections (ODBC) diff --git a/docs/data/odbc/displaying-and-manipulating-data-in-a-form.md b/docs/data/odbc/displaying-and-manipulating-data-in-a-form.md index 46c6041841d..cf05784207f 100644 --- a/docs/data/odbc/displaying-and-manipulating-data-in-a-form.md +++ b/docs/data/odbc/displaying-and-manipulating-data-in-a-form.md @@ -4,6 +4,7 @@ title: "Displaying and Manipulating Data in a Form" ms.date: "11/04/2016" helpviewer_keywords: ["forms [C++], displaying data", "displaying data [C++], forms", "ODBC [C++], forms", "record views [C++], displaying data", "data [MFC]", "data [MFC], displaying in a form"] ms.assetid: c56185c4-12cb-40b1-b499-02b29ea83e3a +ms.topic: concept-article --- # Displaying and Manipulating Data in a Form diff --git a/docs/data/odbc/installing-and-getting-started-with-odbc.md b/docs/data/odbc/installing-and-getting-started-with-odbc.md index 6f358b59278..a62e8cab628 100644 --- a/docs/data/odbc/installing-and-getting-started-with-odbc.md +++ b/docs/data/odbc/installing-and-getting-started-with-odbc.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["installing ODBC", "ODBC, installing"] ms.assetid: 6b473481-1d68-468f-89f6-82b0fd7716fd ms.custom: intro-installation +ms.topic: get-started --- # Installing and Getting Started with ODBC diff --git a/docs/data/odbc/odbc-and-mfc.md b/docs/data/odbc/odbc-and-mfc.md index 5f25751635a..8a647cef023 100644 --- a/docs/data/odbc/odbc-and-mfc.md +++ b/docs/data/odbc/odbc-and-mfc.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: ODBC and MFC" title: "ODBC and MFC" +description: "Learn more about: ODBC and MFC" ms.date: "11/04/2016" helpviewer_keywords: ["ODBC [C++], MFC", "connections [C++], databases", "connections [C++], data source", "databases [C++], connecting to", "data sources [C++], connecting to", "MFC [C++], ODBC and", "database connections [C++], MFC ODBC classes"] -ms.assetid: 98f02fd7-1235-437b-89a9-edfd0fc797f7 --- # ODBC and MFC > [!NOTE] -> To use the MFC database classes, you must have the appropriate ODBC driver for your data source. The lastest Microsoft ODBC driver for SQL Server is [Microsoft ODBC Driver 13 for SQL Server](https://www.microsoft.com/download/details.aspx?id=50420). Most database vendors provide an ODBC driver for Windows. +> To use the MFC database classes, you must have the appropriate ODBC driver for your data source. The lastest Microsoft ODBC driver for SQL Server is [Microsoft ODBC Driver 18 for SQL Server](/sql/connect/odbc/download-odbc-driver-for-sql-server). Most database vendors provide an ODBC driver for Windows. This topic introduces the main concepts of the Microsoft Foundation Classes (MFC) library's ODBC-based database classes and provides an overview of how the classes work together. For more information about ODBC and MFC, see the following topics: diff --git a/docs/data/odbc/record-field-exchange-how-rfx-works.md b/docs/data/odbc/record-field-exchange-how-rfx-works.md index 1845d7f121e..f2f300fd447 100644 --- a/docs/data/odbc/record-field-exchange-how-rfx-works.md +++ b/docs/data/odbc/record-field-exchange-how-rfx-works.md @@ -4,6 +4,7 @@ title: "Record Field Exchange: How RFX Works" ms.date: "11/04/2016" helpviewer_keywords: ["record editing [C++], using RFX", "RFX (ODBC) [C++], updating data in recordsets", "scrolling [C++]", "ODBC [C++], RFX", "data binding [C++], DFX", "scrolling [C++], RFX", "RFX (ODBC) [C++], binding fields and parameters"] ms.assetid: e647cacd-62b0-4b80-9e20-b392deca5a88 +ms.topic: concept-article --- # Record Field Exchange: How RFX Works diff --git a/docs/data/odbc/record-field-exchange-working-with-the-wizard-code.md b/docs/data/odbc/record-field-exchange-working-with-the-wizard-code.md index e4863b06c9f..40e4b98913b 100644 --- a/docs/data/odbc/record-field-exchange-working-with-the-wizard-code.md +++ b/docs/data/odbc/record-field-exchange-working-with-the-wizard-code.md @@ -4,6 +4,7 @@ title: "Record Field Exchange: Working with the Wizard Code" ms.date: "05/09/2019" helpviewer_keywords: ["DoFieldExchange method, overriding", "Unicode, with database classes", "field data members, declaring", "RFX (ODBC), wizard code", "RFX (ODBC), implementing", "field data members", "ODBC, RFX", "m_nParams data member, initializing", "m_nFields data member", "m_nParams data member", "overriding, DoFieldExchange", "m_nFields data member, initializing"] ms.assetid: f00d882a-ff1b-4a75-9717-98d8762bb237 +ms.topic: how-to --- # Record Field Exchange: Working with the Wizard Code diff --git a/docs/data/odbc/recordset-fetching-records-in-bulk-odbc.md b/docs/data/odbc/recordset-fetching-records-in-bulk-odbc.md index bea45e7ed94..83ad1f4bc73 100644 --- a/docs/data/odbc/recordset-fetching-records-in-bulk-odbc.md +++ b/docs/data/odbc/recordset-fetching-records-in-bulk-odbc.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Recordset: Fetching Records in Bulk (ODBC)" title: "Recordset: Fetching Records in Bulk (ODBC)" -ms.date: "11/04/2016" +description: "Learn more about: Recordset: Fetching Records in Bulk (ODBC)" +ms.date: 11/04/2016 helpviewer_keywords: ["bulk row fetching, implementing", "ODBC recordsets, bulk row fetching", "bulk record field exchange", "bulk row fetching", "bulk RFX functions", "recordsets, bulk row fetching", "DoBulkFieldExchange method", "fetching ODBC records in bulk", "RFX (ODBC), bulk", "rowsets, bulk row fetching", "RFX (ODBC), bulk row fetching"] -ms.assetid: 20d10fe9-c58a-414a-b675-cdf9aa283e4f --- # Recordset: Fetching Records in Bulk (ODBC) @@ -74,7 +73,7 @@ public: . . . -} +}; ``` You can either allocate these storage buffers manually or have the framework do the allocation. To allocate the buffers yourself, you must specify the `CRecordset::userAllocMultiRowBuffers` option of the *dwOptions* parameter in the `Open` member function. Be sure to set the sizes of the arrays at least equal to the rowset size. If you want to have the framework do the allocation, you should initialize your pointers to NULL. This is typically done in the recordset object's constructor: diff --git a/docs/data/odbc/redistributing-odbc-components-to-your-customers.md b/docs/data/odbc/redistributing-odbc-components-to-your-customers.md index 96b7157adc5..35e7a61de99 100644 --- a/docs/data/odbc/redistributing-odbc-components-to-your-customers.md +++ b/docs/data/odbc/redistributing-odbc-components-to-your-customers.md @@ -4,6 +4,7 @@ title: "Redistributing ODBC Components to Your Customers" ms.date: "11/04/2016" helpviewer_keywords: ["ODBC components, redistributing", "ODBC, distributing components", "components [C++], distributing", "ODBC Administrator", "components [C++]", "components [C++], redistributing"] ms.assetid: 17b065b4-a307-4b89-99ac-d05831cfab87 +ms.topic: concept-article --- # Redistributing ODBC Components to Your Customers diff --git a/docs/data/odbc/selecting-and-manipulating-records.md b/docs/data/odbc/selecting-and-manipulating-records.md index c39755668cb..d8d3c06f787 100644 --- a/docs/data/odbc/selecting-and-manipulating-records.md +++ b/docs/data/odbc/selecting-and-manipulating-records.md @@ -4,6 +4,7 @@ title: "Selecting and Manipulating Records" ms.date: "05/09/2019" helpviewer_keywords: ["records, selecting", "record selection, MFC ODBC classes", "ODBC recordsets, selecting records"] ms.assetid: 7f0b3a4a-9941-4475-a612-9ec8d15b7691 +ms.topic: concept-article --- # Selecting and Manipulating Records diff --git a/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md b/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md index b458eab1d29..034a0b37d85 100644 --- a/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md +++ b/docs/data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: SQL: Customizing Your Recordset’s SQL Statement (ODBC)" -title: "SQL: Customizing Your Recordset’s SQL Statement (ODBC)" -ms.date: "11/04/2016" +title: "SQL: Customizing Your Recordset's SQL Statement (ODBC)" +description: "Learn more about: SQL: Customizing Your Recordset's SQL Statement (ODBC)" +ms.date: 11/04/2016 helpviewer_keywords: ["recordsets, SQL statements", "ODBC recordsets, SQL statements", "SQL statements, customizing", "SQL statements, recordset", "customizing SQL statements", "overriding, SQL statements", "SQL, opening recordsets"] -ms.assetid: 72293a08-cef2-4be2-aa1c-30565fcfbaf9 --- -# SQL: Customizing Your Recordset’s SQL Statement (ODBC) +# SQL: Customizing Your Recordset's SQL Statement (ODBC) This topic explains: @@ -82,11 +81,11 @@ The following table shows the possibilities for the *lpszSQL* parameter to `Open \* `m_nFields` must be less than or equal to the number of columns specified in the **SELECT** statement. The data type of each column specified in the **SELECT** statement must be the same as the data type of the corresponding RFX output column. -### Case 1 lpszSQL = NULL +### Case 1 lpszSQL = NULL The recordset selection depends on what `GetDefaultSQL` returns when `CRecordset::Open` calls it. Cases 2 through 5 describe the possible strings. -### Case 2 lpszSQL = a Table Name +### Case 2 lpszSQL = a Table Name The recordset uses record field exchange (RFX) to build the column list from the column names provided in the RFX function calls in the recordset class's override of `DoFieldExchange`. If you used a wizard to declare your recordset class, this case has the same result as case 1 (provided that you pass the same table name you specified in the wizard). If you do not use a wizard to write your class, case 2 is the simplest way to construct the SQL statement. @@ -120,7 +119,7 @@ SELECT CourseID, InstructorID, RoomNo, Schedule, SectionNo FROM SECTION ``` -### Case 3 lpszSQL = a SELECT/FROM Statement +### Case 3 lpszSQL = a SELECT/FROM Statement You specify the column list by hand rather than relying on RFX to construct it automatically. You might want to do this when: @@ -138,11 +137,11 @@ You specify the column list by hand rather than relying on RFX to construct it a For information and an example, see [Recordset: Performing a Join (ODBC)](../../data/odbc/recordset-performing-a-join-odbc.md). -### Case 4 lpszSQL = SELECT/FROM Plus WHERE and/or ORDER BY +### Case 4 lpszSQL = SELECT/FROM Plus WHERE and/or ORDER BY You specify everything: the column list (based on the RFX calls in `DoFieldExchange`), the table list, and the contents of a **WHERE** and/or an **ORDER BY** clause. If you specify your **WHERE** and/or **ORDER BY** clauses this way, do not use `m_strFilter` and/or `m_strSort`. -### Case 5 lpszSQL = a Stored Procedure Call +### Case 5 lpszSQL = a Stored Procedure Call If you need to call a predefined query (such as a stored procedure in a Microsoft SQL Server database), you must write a **CALL** statement in the string you pass to *lpszSQL*. The wizards do not support declaring a recordset class for calling a predefined query. Not all predefined queries return records. diff --git a/docs/data/odbc/working-with-documents-and-views.md b/docs/data/odbc/working-with-documents-and-views.md index fd9339a4dff..d683432083b 100644 --- a/docs/data/odbc/working-with-documents-and-views.md +++ b/docs/data/odbc/working-with-documents-and-views.md @@ -4,6 +4,7 @@ title: "Working with Documents and Views" ms.date: "11/04/2016" helpviewer_keywords: ["MFC [C++], documents", "MFC [C++], views", "views [C++], MFC", "documents [C++], MFC"] ms.assetid: 349b142d-1c5a-4b99-9de4-241e41d3d2f1 +ms.topic: concept-article --- # Working with Documents and Views diff --git a/docs/data/oledb/cdataconnection-class.md b/docs/data/oledb/cdataconnection-class.md index 6185ad46918..d388cafa612 100644 --- a/docs/data/oledb/cdataconnection-class.md +++ b/docs/data/oledb/cdataconnection-class.md @@ -179,7 +179,7 @@ This operator returns a reference to the contained `CDataSource` object, allowin If you have a function (such as `func` below) that takes a `CDataSource` reference, you can use `CDataSource&` to pass a `CDataConnection` object instead. [!code-cpp[NVC_OLEDB_Consumer#3](../../data/oledb/codesnippet/cpp/cdataconnection-operator-cdatasource-amp_1.cpp)] - +  [!code-cpp[NVC_OLEDB_Consumer#4](../../data/oledb/codesnippet/cpp/cdataconnection-operator-cdatasource-amp_2.cpp)] ## `CDataConnection::operator CDataSource*` @@ -217,7 +217,7 @@ This operator returns a reference to the contained `CSession` object, allowing y If you have a function (such as `func` below) that takes a `CSession` reference, you can use `CSession&` to pass a `CDataConnection` object instead. [!code-cpp[NVC_OLEDB_Consumer#5](../../data/oledb/codesnippet/cpp/cdataconnection-operator-csession-amp_1.cpp)] - +  [!code-cpp[NVC_OLEDB_Consumer#6](../../data/oledb/codesnippet/cpp/cdataconnection-operator-csession-amp_2.cpp)] ## `CDataConnection::operator CSession*` diff --git a/docs/data/oledb/cdatasource-class.md b/docs/data/oledb/cdatasource-class.md index befd0149817..d85b974a3cb 100644 --- a/docs/data/oledb/cdatasource-class.md +++ b/docs/data/oledb/cdatasource-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: CDataSource Class" title: "CDataSource Class" -ms.date: "11/04/2016" +description: "Learn more about: CDataSource Class" +ms.date: 11/04/2016 f1_keywords: ["ATL.CDataSource", "ATL::CDataSource", "CDataSource", "ATL::CDataSource::Close", "ATL.CDataSource.Close", "CDataSource::Close", "CDataSource.Close", "ATL::CDataSource::GetInitializationString", "CDataSource.GetInitializationString", "GetInitializationString", "CDataSource::GetInitializationString", "ATL.CDataSource.GetInitializationString", "CDataSource::GetProperties", "ATL.CDataSource.GetProperties", "CDataSource.GetProperties", "ATL::CDataSource::GetProperties", "ATL::CDataSource::GetProperty", "ATL.CDataSource.GetProperty", "CDataSource.GetProperty", "CDataSource::GetProperty", "ATL::CDataSource::Open", "ATL.CDataSource.Open", "CDataSource::Open", "CDataSource.Open", "CDataSource::OpenFromFileName", "ATL::CDataSource::OpenFromFileName", "OpenFromFileName", "CDataSource.OpenFromFileName", "ATL.CDataSource.OpenFromFileName", "CDataSource.OpenFromInitializationString", "OpenFromInitializationString", "CDataSource::OpenFromInitializationString", "ATL::CDataSource::OpenFromInitializationString", "ATL.CDataSource.OpenFromInitializationString", "CDataSource.OpenWithPromptFileName", "OpenWithPromptFileName", "ATL::CDataSource::OpenWithPromptFileName", "ATL.CDataSource.OpenWithPromptFileName", "CDataSource::OpenWithPromptFileName", "CDataSource::OpenWithServiceComponents", "OpenWithServiceComponents", "CDataSource.OpenWithServiceComponents"] helpviewer_keywords: ["CDataSource class", "Close method", "GetInitializationString method", "GetProperties method", "GetProperty method", "Open method", "OpenFromFileName method", "OpenFromInitializationString method", "OpenWithPromptFileName method", "OpenWithServiceComponents method"] -ms.assetid: 99bf862c-9d5c-4117-9501-aa0e2672085c --- # CDataSource Class @@ -201,7 +200,7 @@ HRESULT Open(LPCSTR szProgID, [in] The user's password. *nInitMode*
-[in] Database initialization mode. See [Initialization Properties](/previous-versions/windows/desktop/ms723127(v=vs.85))in the *OLE DB Programmer's Reference* in the Windows SDK for a list of valid initialization modes. If *nInitMode* is zero, no initialization mode is included in the property set used to open the connection. +[in] Database initialization mode. See [Initialization Properties](/previous-versions/windows/desktop/ms723127(v=vs.85)) in the *OLE DB Programmer's Reference* in the Windows SDK for a list of valid initialization modes. If *nInitMode* is zero, no initialization mode is included in the property set used to open the connection. *szProgID*
[in] A program identifier. diff --git a/docs/data/oledb/cdbpropset-class.md b/docs/data/oledb/cdbpropset-class.md index 9086c09dde7..858162faf33 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 c56375b66cc..07eb3edd885 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 28a3305590d..1bda3085456 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/creating-an-updatable-provider.md b/docs/data/oledb/creating-an-updatable-provider.md index dd01af2f426..cb579e95ae6 100644 --- a/docs/data/oledb/creating-an-updatable-provider.md +++ b/docs/data/oledb/creating-an-updatable-provider.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Creating an Updatable Provider" title: "Creating an Updatable Provider" -ms.date: "08/16/2018" +description: "Learn more about: Creating an Updatable Provider" +ms.date: 08/16/2018 helpviewer_keywords: ["OLE DB providers, updatable", "notifications, support in providers", "OLE DB providers, creating"] -ms.assetid: bdfd5c9f-1c6f-4098-822c-dd650e70ab82 --- # Creating an Updatable Provider @@ -174,7 +173,7 @@ Making sure that the data store can handle changes. Handling NULL values. -### Handling default values. +### Handling default values To implement your own `FlushData` method, you need to: diff --git a/docs/data/oledb/crowset-class.md b/docs/data/oledb/crowset-class.md index d64fd3ebc50..d42f6d0f813 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/crowsetimpl-class.md b/docs/data/oledb/crowsetimpl-class.md index e83271fca53..ee3884e6daa 100644 --- a/docs/data/oledb/crowsetimpl-class.md +++ b/docs/data/oledb/crowsetimpl-class.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" f1_keywords: ["CRowsetImpl", "ATL.CRowsetImpl", "ATL::CRowsetImpl", "CRowsetImpl.NameFromDBID", "CRowsetImpl::NameFromDBID", "CRowsetImpl.SetCommandText", "CRowsetImpl::SetCommandText", "CRowsetImpl.GetColumnInfo", "CRowsetImpl::GetColumnInfo", "CRowsetImpl::GetCommandFromID", "GetCommandFromID", "CRowsetImpl.GetCommandFromID", "CRowsetImpl.ValidateCommandID", "CRowsetImpl::ValidateCommandID", "CRowsetImpl.m_rgRowData", "CRowsetImpl::m_rgRowData", "CRowsetImpl::m_strCommandText", "CRowsetImpl.m_strCommandText", "CRowsetImpl::m_strIndexText", "CRowsetImpl.m_strIndexText"] helpviewer_keywords: ["CRowsetImpl class", "NameFromDBID method", "SetCommandText method", "GetColumnInfo method", "GetCommandFromID method", "ValidateCommandID method", "m_rgRowData", "m_strCommandText", "m_strIndexText"] ms.assetid: e97614b3-b11d-4806-a0d3-b9401331473f +ms.custom: sfi-ropc-nochange --- # CRowsetImpl Class diff --git a/docs/data/oledb/dynamically-determining-columns-returned-to-the-consumer.md b/docs/data/oledb/dynamically-determining-columns-returned-to-the-consumer.md index 9ae135a598a..14175fae5ef 100644 --- a/docs/data/oledb/dynamically-determining-columns-returned-to-the-consumer.md +++ b/docs/data/oledb/dynamically-determining-columns-returned-to-the-consumer.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: Dynamically Determining Columns Returned to the Consumer" title: "Dynamically Determining Columns Returned to the Consumer" -ms.date: "10/26/2018" +description: "Learn more about: Dynamically Determining Columns Returned to the Consumer" +ms.date: 10/26/2018 helpviewer_keywords: ["bookmarks [C++], dynamically determining columns", "dynamically determining columns [C++]"] -ms.assetid: 58522b7a-894e-4b7d-a605-f80e900a7f5f --- # Dynamically Determining Columns Returned to the Consumer -The PROVIDER_COLUMN_ENTRY macros normally handle the `IColumnsInfo::GetColumnsInfo` call. However, because a consumer might choose to use bookmarks, the provider must be able to change the columns returned depending on whether the consumer asks for a bookmark. +The `PROVIDER_COLUMN_ENTRY` macros normally handle the `IColumnsInfo::GetColumnsInfo` call. However, because a consumer might choose to use bookmarks, the provider must be able to change the columns returned depending on whether the consumer asks for a bookmark. -To handle the `IColumnsInfo::GetColumnsInfo` call, delete the PROVIDER_COLUMN_MAP, which defines a function `GetColumnInfo`, from the `CCustomWindowsFile` user record in *Custom*RS.h and replace it with the definition for your own `GetColumnInfo` function: +To handle the `IColumnsInfo::GetColumnsInfo` call, delete the `PROVIDER_COLUMN_MAP`, which defines a function `GetColumnInfo`, from the `CCustomWindowsFile` user record in *Custom*RS.h and replace it with the definition for your own `GetColumnInfo` function: ```cpp //////////////////////////////////////////////////////////////////////// @@ -23,7 +22,7 @@ public: TCHAR szText[iSize]; TCHAR szCommand2[iSize]; TCHAR szText2[iSize]; - + static ATLCOLUMNINFO* GetColumnInfo(void* pThis, ULONG* pcCols); bool operator==(const CCustomWindowsFile& am) { @@ -36,7 +35,7 @@ Next, implement the `GetColumnInfo` function in *Custom*RS.cpp, as shown in the `GetColumnInfo` checks first to see if the OLE DB property `DBPROP_BOOKMARKS` is set. To get the property, `GetColumnInfo` uses a pointer (`pRowset`) to the rowset object. The `pThis` pointer represents the class that created the rowset, which is the class where the property map is stored. `GetColumnInfo` typecasts the `pThis` pointer to an `RCustomRowset` pointer. -To check for the `DBPROP_BOOKMARKS` property, `GetColumnInfo` uses the `IRowsetInfo` interface, which you can get by calling `QueryInterface` on the `pRowset` interface. As an alternative, you can use an ATL [CComQIPtr](../../atl/reference/ccomqiptr-class.md) method instead. +To check for the `DBPROP_BOOKMARKS` property, `GetColumnInfo` uses the `IRowsetInfo` interface, which you can get by calling `QueryInterface` on the `pRowset` interface. As an alternative, you can use an ATL [`CComQIPtr`](../../atl/reference/ccomqiptr-class.md) method instead. ```cpp //////////////////////////////////////////////////////////////////// @@ -45,27 +44,27 @@ ATLCOLUMNINFO* CCustomWindowsFile::GetColumnInfo(void* pThis, ULONG* pcCols) { static ATLCOLUMNINFO _rgColumns[5]; ULONG ulCols = 0; - + // Check the property flag for bookmarks; if it is set, set the zero // ordinal entry in the column map with the bookmark information. CCustomRowset* pRowset = (CCustomRowset*) pThis; CComQIPtr spRowsetProps = pRowset; - + CDBPropIDSet set(DBPROPSET_ROWSET); set.AddPropertyID(DBPROP_BOOKMARKS); DBPROPSET* pPropSet = NULL; ULONG ulPropSet = 0; HRESULT hr; - + if (spRowsetProps) hr = spRowsetProps->GetProperties(1, &set, &ulPropSet, &pPropSet); - + if (pPropSet) { CComVariant var = pPropSet->rgProperties[0].vValue; CoTaskMemFree(pPropSet->rgProperties); CoTaskMemFree(pPropSet); - + if (SUCCEEDED(hr) && (var.boolVal == VARIANT_TRUE)) { ADD_COLUMN_ENTRY_EX(ulCols, OLESTR("Bookmark"), 0, sizeof(DWORD), @@ -74,7 +73,7 @@ ATLCOLUMNINFO* CCustomWindowsFile::GetColumnInfo(void* pThis, ULONG* pcCols) ulCols++; } } - + // Next, set the other columns up. ADD_COLUMN_ENTRY(ulCols, OLESTR("Command"), 1, 256, DBTYPE_STR, 0xFF, 0xFF, GUID_NULL, CCustomWindowsFile, szCommand) @@ -82,50 +81,50 @@ ATLCOLUMNINFO* CCustomWindowsFile::GetColumnInfo(void* pThis, ULONG* pcCols) ADD_COLUMN_ENTRY(ulCols, OLESTR("Text"), 2, 256, DBTYPE_STR, 0xFF, 0xFF, GUID_NULL, CCustomWindowsFile, szText) ulCols++; - + ADD_COLUMN_ENTRY(ulCols, OLESTR("Command2"), 3, 256, DBTYPE_STR, 0xFF, 0xFF, GUID_NULL, CCustomWindowsFile, szCommand2) ulCols++; ADD_COLUMN_ENTRY(ulCols, OLESTR("Text2"), 4, 256, DBTYPE_STR, 0xFF, 0xFF, GUID_NULL, CCustomWindowsFile, szText2) ulCols++; - + if (pcCols != NULL) *pcCols = ulCols; - + return _rgColumns; } ``` -This example uses a static array to hold the column information. If the consumer doesn't want the bookmark column, one entry in the array is unused. To handle the information, you create two array macros: ADD_COLUMN_ENTRY and ADD_COLUMN_ENTRY_EX. ADD_COLUMN_ENTRY_EX takes an extra parameter, *flags*, that is needed if you designate a bookmark column. +This example uses a static array to hold the column information. If the consumer doesn't want the bookmark column, one entry in the array is unused. To handle the information, you create two array macros: `ADD_COLUMN_ENTRY` and `ADD_COLUMN_ENTRY_EX`. `ADD_COLUMN_ENTRY_EX` takes an extra parameter, *`flags`*, that is needed if you designate a bookmark column. ```cpp -//////////////////////////////////////////////////////////////////////// -// CustomRS.h - -#define ADD_COLUMN_ENTRY(ulCols, name, ordinal, colSize, type, precision, scale, guid, dataClass, member) \ - _rgColumns[ulCols].pwszName = (LPOLESTR)name; \ - _rgColumns[ulCols].pTypeInfo = (ITypeInfo*)NULL; \ - _rgColumns[ulCols].iOrdinal = (ULONG)ordinal; \ - _rgColumns[ulCols].dwFlags = 0; \ - _rgColumns[ulCols].ulColumnSize = (ULONG)colSize; \ - _rgColumns[ulCols].wType = (DBTYPE)type; \ - _rgColumns[ulCols].bPrecision = (BYTE)precision; \ - _rgColumns[ulCols].bScale = (BYTE)scale; \ - _rgColumns[ulCols].cbOffset = offsetof(dataClass, member); - -#define ADD_COLUMN_ENTRY_EX(ulCols, name, ordinal, colSize, type, precision, scale, guid, dataClass, member, flags) \ - _rgColumns[ulCols].pwszName = (LPOLESTR)name; \ - _rgColumns[ulCols].pTypeInfo = (ITypeInfo*)NULL; \ - _rgColumns[ulCols].iOrdinal = (ULONG)ordinal; \ - _rgColumns[ulCols].dwFlags = flags; \ - _rgColumns[ulCols].ulColumnSize = (ULONG)colSize; \ - _rgColumns[ulCols].wType = (DBTYPE)type; \ - _rgColumns[ulCols].bPrecision = (BYTE)precision; \ - _rgColumns[ulCols].bScale = (BYTE)scale; \ - _rgColumns[ulCols].cbOffset = offsetof(dataClass, member); \ - memset(&(_rgColumns[ulCols].columnid), 0, sizeof(DBID)); \ - _rgColumns[ulCols].columnid.uName.pwszName = (LPOLESTR)name; +//////////////////////////////////////////////////////////////////////// +// CustomRS.h + +#define ADD_COLUMN_ENTRY(ulCols, name, ordinal, colSize, type, precision, scale, guid, dataClass, member) \ + _rgColumns[ulCols].pwszName = (LPOLESTR)name; \ + _rgColumns[ulCols].pTypeInfo = (ITypeInfo*)NULL; \ + _rgColumns[ulCols].iOrdinal = (ULONG)ordinal; \ + _rgColumns[ulCols].dwFlags = 0; \ + _rgColumns[ulCols].ulColumnSize = (ULONG)colSize; \ + _rgColumns[ulCols].wType = (DBTYPE)type; \ + _rgColumns[ulCols].bPrecision = (BYTE)precision; \ + _rgColumns[ulCols].bScale = (BYTE)scale; \ + _rgColumns[ulCols].cbOffset = offsetof(dataClass, member); + +#define ADD_COLUMN_ENTRY_EX(ulCols, name, ordinal, colSize, type, precision, scale, guid, dataClass, member, flags) \ + _rgColumns[ulCols].pwszName = (LPOLESTR)name; \ + _rgColumns[ulCols].pTypeInfo = (ITypeInfo*)NULL; \ + _rgColumns[ulCols].iOrdinal = (ULONG)ordinal; \ + _rgColumns[ulCols].dwFlags = flags; \ + _rgColumns[ulCols].ulColumnSize = (ULONG)colSize; \ + _rgColumns[ulCols].wType = (DBTYPE)type; \ + _rgColumns[ulCols].bPrecision = (BYTE)precision; \ + _rgColumns[ulCols].bScale = (BYTE)scale; \ + _rgColumns[ulCols].cbOffset = offsetof(dataClass, member); \ + memset(&(_rgColumns[ulCols].columnid), 0, sizeof(DBID)); \ + _rgColumns[ulCols].columnid.uName.pwszName = (LPOLESTR)name; ``` In the `GetColumnInfo` function, the bookmark macro is used like this: @@ -136,8 +135,8 @@ ADD_COLUMN_ENTRY_EX(ulCols, OLESTR("Bookmark"), 0, sizeof(DWORD), DBCOLUMNFLAGS_ISBOOKMARK) ``` -You can now compile and run the enhanced provider. To test the provider, modify the test consumer as described in [Implementing a Simple Consumer](../../data/oledb/implementing-a-simple-consumer.md). Run the test consumer with the provider and verify that the test consumer retrieves the proper strings from the provider. +You can now compile and run the enhanced provider. To test the provider, modify the test consumer as described in [Implementing a Simple Consumer](implementing-a-simple-consumer.md). Run the test consumer with the provider and verify that the test consumer retrieves the proper strings from the provider. ## See also -[Enhancing the Simple Read-Only Provider](../../data/oledb/enhancing-the-simple-read-only-provider.md)
+[Enhancing the Simple Read-Only Provider](enhancing-the-simple-read-only-provider.md) diff --git a/docs/data/oledb/icommandpropertiesimpl-class.md b/docs/data/oledb/icommandpropertiesimpl-class.md index 3d50ed3c85f..2b1694ea7c9 100644 --- a/docs/data/oledb/icommandpropertiesimpl-class.md +++ b/docs/data/oledb/icommandpropertiesimpl-class.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" f1_keywords: ["ICommandPropertiesImpl", "ATL.ICommandPropertiesImpl", "ATL::ICommandPropertiesImpl", "ICommandPropertiesImpl::GetProperties", "ICommandPropertiesImpl.GetProperties", "ICommandPropertiesImpl.SetProperties", "ICommandPropertiesImpl::SetProperties"] helpviewer_keywords: ["ICommandPropertiesImpl class", "GetProperties method", "SetProperties method"] ms.assetid: b3cf6aea-527e-4f0d-96e0-669178b021a2 +ms.custom: sfi-ropc-nochange --- # ICommandPropertiesImpl Class diff --git a/docs/data/oledb/irowsetcreatorimpl-class.md b/docs/data/oledb/irowsetcreatorimpl-class.md index 542a3dffabe..8fb9c33eabd 100644 --- a/docs/data/oledb/irowsetcreatorimpl-class.md +++ b/docs/data/oledb/irowsetcreatorimpl-class.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" f1_keywords: ["ATL::IRowsetCreatorImpl", "ATL.IRowsetCreatorImpl", "ATL::IRowsetCreatorImpl", "ATL.IRowsetCreatorImpl", "IRowsetCreatorImpl", "IRowsetCreatorImpl.SetSite", "IRowsetCreatorImpl::SetSite", "IRowsetCreatorImpl::SetSite", "SetSite", "ATL.IRowsetCreatorImpl.SetSite", "ATL::IRowsetCreatorImpl::SetSite", "ATL::IRowsetCreatorImpl::SetSite", "ATL.IRowsetCreatorImpl.SetSite"] helpviewer_keywords: ["IRowsetCreatorImpl class", "SetSite method"] ms.assetid: 92cc950f-7978-4754-8d9a-defa63867d82 +ms.custom: sfi-ropc-nochange --- # IRowsetCreatorImpl Class diff --git a/docs/data/oledb/irowsetinfoimpl-class.md b/docs/data/oledb/irowsetinfoimpl-class.md index d05de7876df..d5f545e3bb7 100644 --- a/docs/data/oledb/irowsetinfoimpl-class.md +++ b/docs/data/oledb/irowsetinfoimpl-class.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" f1_keywords: ["ATL.IRowsetInfoImpl", "IRowsetInfoImpl", "ATL::IRowsetInfoImpl", "ATL.IRowsetInfoImpl.GetProperties", "IRowsetInfoImpl.GetProperties", "ATL::IRowsetInfoImpl::GetProperties", "IRowsetInfoImpl::GetProperties", "ATL::IRowsetInfoImpl::GetReferencedRowset", "GetReferencedRowset", "ATL.IRowsetInfoImpl.GetReferencedRowset", "IRowsetInfoImpl.GetReferencedRowset", "IRowsetInfoImpl::GetReferencedRowset", "IRowsetInfoImpl::GetSpecification", "ATL.IRowsetInfoImpl.GetSpecification", "IRowsetInfoImpl.GetSpecification", "GetSpecification", "ATL::IRowsetInfoImpl::GetSpecification"] helpviewer_keywords: ["IRowsetInfoImpl class", "GetProperties method", "GetReferencedRowset method", "GetSpecification method"] ms.assetid: 9c654155-7727-464e-bd31-143e68391a47 +ms.custom: sfi-ropc-nochange --- # IRowsetInfoImpl Class diff --git a/docs/data/oledb/irowsetlocateimpl-class.md b/docs/data/oledb/irowsetlocateimpl-class.md index 082de1f7b90..16872cbd1a0 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 314202ddd9b..8737941bcd0 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/isessionpropertiesimpl-class.md b/docs/data/oledb/isessionpropertiesimpl-class.md index 89043502938..5818498c6e9 100644 --- a/docs/data/oledb/isessionpropertiesimpl-class.md +++ b/docs/data/oledb/isessionpropertiesimpl-class.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" f1_keywords: ["ISessionPropertiesImpl", "ISessionPropertiesImpl::GetProperties", "ISessionPropertiesImpl.GetProperties", "ISessionPropertiesImpl.SetProperties", "ISessionPropertiesImpl::SetProperties"] helpviewer_keywords: ["ISessionPropertiesImpl class", "GetProperties method", "SetProperties method"] ms.assetid: ca0ba254-c7dc-4c52-abec-cf895a0c6a63 +ms.custom: sfi-ropc-nochange --- # ISessionPropertiesImpl Class diff --git a/docs/data/oledb/ole-db-provider-templates-reference.md b/docs/data/oledb/ole-db-provider-templates-reference.md index 8e4f8167f9f..ba16a0f8a26 100644 --- a/docs/data/oledb/ole-db-provider-templates-reference.md +++ b/docs/data/oledb/ole-db-provider-templates-reference.md @@ -4,6 +4,7 @@ title: "OLE DB Provider Templates Reference" ms.date: "11/04/2016" helpviewer_keywords: ["OLE DB provider templates"] ms.assetid: 518358f0-bab1-4de9-bce9-4062cc87c11f +ms.custom: sfi-ropc-nochange --- # OLE DB Provider Templates Reference 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 574d95b2ac2..f4782506663 100644 --- a/docs/data/oledb/schema-rowset-classes-and-typedef-classes.md +++ b/docs/data/oledb/schema-rowset-classes-and-typedef-classes.md @@ -1,12 +1,9 @@ --- -description: "Learn more about: Schema Rowset Classes and Typedef Classes" title: "Schema Rowset Classes and Typedef Classes" -ms.date: "11/04/2016" +description: "Learn more about: Schema Rowset Classes and Typedef Classes" +ms.date: 11/04/2016 f1_keywords: ["CAssertionInfo", "CAssertions", "CCatalogInfo", "CCatalogs", "CCharacterSetInfo", "CCharacterSets", "CCheckConstraintInfo", "CCheckConstraints", "CCollationInfo", "CCollations", "CColumnDomainUsage", "CColumnDomainUsageInfo", "CColumnPrivilegeInfo", "CColumnPrivileges", "CColumns", "CColumnsInfo", "CConstraintColumnUsage", "CConstraintColumnUsageInfo", "CConstraintTableUsage", "CConstraintTableUsageInfo", "CForeignKeys", "CForeignKeysInfo", "CHARACTER_MAXIMUM_LENGTH", "CHARACTER_OCTET_LENGTH", "CHARACTER_SET_CATALOG", "CHARACTER_SET_NAME", "CHARACTER_SET_SCHEMA", "CHECK_CLAUSE", "CHECK_CONSTRAINTS", "CHECK_OPTION", "CIndexes", "CIndexInfo", "CKeyColumnInfo", "CKeyColumns", "CLUSTERED", "COLLATION", "COLLATION_CATALOG", "COLLATION_NAME", "COLLATION_SCHEMA", "COLLATIONS", "COLUMN_DEFAULT", "COLUMN_DOMAIN_USAGE", "COLUMN_FLAGS", "COLUMN_GUID", "COLUMN_HASDEFAULT", "COLUMN_PRIVILEGES", "COLUMN_PROPID", "COLUMN_SIZE", "CONSTRAINT_CATALOG", "CONSTRAINT_COLUMN_USAGE", "CONSTRAINT_NAME", "CONSTRAINT_SCHEMA", "CONSTRAINT_TABLE_USAGE", "CONSTRAINT_TYPE", "CPrimaryKeyInfo", "CPrimaryKeys", "CProcedureColumnInfo", "CProcedureColumns", "CProcedureInfo", "CProcedureParameters", "CProcedureParamInfo", "CProcedures", "CProviderInfo", "CProviderTypes", "CReferentialConstraintInfo", "CReferentialConstraints", "CSchemata", "CSchemataInfo", "CSQLLanguageInfo", "CSQLLanguages", "CStatisticInfo", "CStatistics", "CTableConstraintInfo", "CTableConstraints", "CTableInfo", "CTablePrivilegeInfo", "CTablePrivileges", "CTables", "CTranslationInfo", "CTranslations", "CUsagePrivilegeInfo", "CUsagePrivileges", "CViewColumnInfo", "CViewColumnUsage", "CViewInfo", "CViews", "CViewTableInfo", "CViewTableUsage", "DATA_TYPE", "DATETIME_PRECISION", "DEFAULT_CHARACTER_SET_CATALOG", "DEFAULT_CHARACTER_SET_NAME", "DEFAULT_CHARACTER_SET_SCHEMA", "DEFAULT_COLLATE_CATALOG", "DEFAULT_COLLATE_NAME", "DEFAULT_COLLATE_SCHEMA", "DELETE_RULE", "DOMAIN_CATALOG", "DOMAIN_NAME", "DOMAIN_SCHEMA", "FILL_FACTOR", "FILTER_CONDITION", "FIXED_PREC_SCALE", "FK_COLUMN_GUID", "FK_COLUMN_NAME", "FK_COLUMN_PROPID", "FK_TABLE_CATALOG", "FK_TABLE_NAME", "FK_TABLE_SCHEMA", "FORM_OF_USE", "GRANTEE", "GRANTOR", "INDEX_CATALOG", "INDEX_NAME", "INDEX_SCHEMA", "INITIAL_SIZE", "INITIALLY_DEFERRED", "IS_DEFERRABLE", "IS_GRANTABLE", "IS_LONG", "IS_NULLABLE", "IS_UPDATABLE", "LITERAL_SUFFIX", "LOCAL_TYPE_NAME", "m_bAutoUniqueValue", "m_bAutoUpdate", "m_bBestMatch", "m_bCaseSensitive", "m_bCheckOption", "m_bClustered", "m_bColumnHasDefault", "m_bFixedPrecScale", "m_bHasDefault", "m_bInitiallyDeferred", "m_bIsDeferrable", "m_bIsGrantable", "m_bIsLong", "m_bIsNullable", "m_bIsUpdatable", "m_bPrimaryKey", "m_bSortBookmarks", "m_bUnique", "m_bUnsignedAttribute", "m_guidColumn", "m_guidFKColumn", "m_guidPKColumn", "m_guidTable", "m_guidType", "m_nCardinality", "m_nCollation", "m_nColumnFlags", "m_nColumnPropID", "m_nColumnSize", "m_nDataType", "m_nDateTimePrecision", "m_nFillFactor", "m_nFKColumnPropID", "m_nInitialSize", "m_nMaxLength", "m_nMaxScale", "m_nNullCollation", "m_nNulls", "m_nNumCharacters", "m_nNumericPrecision", "m_nNumericScale", "m_nOctetLength", "m_nOrdinal", "m_nOrdinalPosition", "m_nPages", "m_nPKColumnPropID", "m_nPrecision", "m_nRowsetNumber", "m_nScale", "m_nSearchable", "m_szBindingStyle", "m_szCatalog", "m_szCharCatalog", "m_szCharName", "m_szCharSchema", "m_szCharSetCatalog", "m_szCharSetName", "m_szCharSetSchema", "m_szCheckClause", "m_szCollateCatalog", "m_szCollateName", "m_szCollateSchema", "m_szCollationCatalog", "m_szCollationName", "m_szCollationSchema", "m_szColumnDefault", "m_szColumnName", "m_szConformance", "m_szConstraintCatalog", "m_szConstraintName", "m_szConstraintSchema", "m_szCreateParams", "m_szDefault", "m_szDefinition", "m_szDeleteRule", "m_szDomainCatalog", "m_szDomainName", "m_szDomainSchema", "m_szFilterCondition", "m_szFKColumnName", "m_szFKTableCatalog", "m_szFKTableName", "m_szFKTableSchema", "m_szFormOfUse", "m_szGrantee", "m_szGrantor", "m_szImplementation", "m_szIndexCatalog", "m_szIndexName", "m_szIndexSchema", "m_szIntegrity", "m_szLiter alSuffix", "m_szLiteralPrefix", "m_szLocalTypeName", "m_szMatchOption", "m_szObjectCatalog", "m_szObjectName", "m_szObjectSchema", "m_szObjectType", "m_szOwner", "m_szPadAttribute", "m_szParameterName", "m_szPKColumnName", "m_szPKTableCatalog", "m_szPKTableName", "m_szPKTableSchema", "m_szPrivilegeType", "m_szProgrammingLanguage", "m_szSchema", "m_szSource", "m_szSourceCatalog", "m_szSourceName", "m_szSourceSchema", "m_szTableCatalog", "m_szTableName", "m_szTableSchema", "m_szTargetCatalog", "m_szTargetName", "m_szTargetSchema", "m_szType", "m_szTypeLib", "m_szTypeName", "m_szUniqueCatalog", "m_szUniqueName", "m_szUniqueSchema", "m_szUpdateRule", "m_szVersion", "m_szYear", "MATCH_OPTION", "MAXIMUM_SCALE", "MINIMUM_SCALE", "NULL_COLLATION", "NULLS", "NUMBER_OF_CHARACTERS", "NUMERIC_PRECISION", "NUMERIC_SCALE", "OBJECT_CATALOG", "OBJECT_NAME", "OBJECT_SCHEMA", "OBJECT_TYPE", "ORDINAL", "ORDINAL_POSITION", "TABLE_CATALOG", "TABLE_GUID", "TABLE_NAME", "TABLE_SCHEMA"] - - helpviewer_keywords: ["schema rowsets", "CAssertionInfo parameter class", "CAssertions typedef class", "CCatalogInfo parameter class", "CCatalogs typedef class", "CCharacterSetInfo parameter class", "CCharacterSets typedef class", "CCheckConstraintInfo parameter class", "CCheckConstraints typedef class", "CCollationInfo parameter class", "CCollations typedef class", "CColumnDomainUsage typedef class", "CColumnDomainUsageInfo parameter class", "CColumnPrivilegeInfo parameter class", "CColumnPrivileges typedef class", "CColumns typedef class", "CColumnsInfo parameter class", "CConstraintColumnUsage typedef class", "CConstraintColumnUsageInfo parameter class", "CConstraintTableUsage typedef class", "CConstraintTableUsageInfo parameter class", "CForeignKeys typedef class", "CForeignKeysInfo parameter class", "CHARACTER_MAXIMUM_LENGTH", "CHARACTER_OCTET_LENGTH", "CHARACTER_SET_CATALOG", "CHARACTER_SET_NAME", "CHARACTER_SET_SCHEMA", "CHECK_CLAUSE", "CHECK_CONSTRAINTS", "CHECK_OPTION", "CIndexes typedef class", "CIndexInfo parameter class", "CKeyColumnInfo parameter class", "CKeyColumns typedef class", "CLUSTERED", "COLLATION_CATALOG", "COLLATION_NAME", "COLLATION_SCHEMA", "COLLATIONS recordset", "COLUMN_DEFAULT", "COLUMN_DOMAIN_USAGE", "COLUMN_FLAGS", "COLUMN_GUID", "COLUMN_HASDEFAULT", "COLUMN_NAME", "COLUMN_PRIVILEGES", "COLUMN_PROPID", "CONSTRAINT_CATALOG", "CONSTRAINT_COLUMN_USAGE", "CONSTRAINT_NAME", "CONSTRAINT_SCHEMA", "CONSTRAINT_TABLE_USAGE", "CONSTRAINT_TYPE", "CPrimaryKeyInfo parameter class", "CPrimaryKeys typedef class", "CProcedureColumnInfo parameter class", "CProcedureColumns typedef class", "CProcedureInfo parameter class", "CProcedureParameters typedef class", "CProcedureParamInfo parameter class", "CProcedures typedef class", "CProviderInfo parameter class", "CProviderTypes typedef class", "CReferentialConstraintInfo parameter class", "CReferentialConstraints typedef class", "CSchemata typedef class", "CSchemataInfo parameter class", "CSQLLanguageInfo parameter class", "CSQLLanguages typedef class", "CStatisticInfo parameter class", "CStatistics typedef class", "CTableConstraintInfo parameter class", "CTableConstraints typedef class", "CTableInfo parameter class", "CTablePrivilegeInfo parameter class", "CTablePrivileges typedef class", "CTables typedef class", "CTranslationInfo parameter class", "CTranslations typedef class", "CUsagePrivilegeInfo parameter class", "CUsagePrivileges typedef class", "CViewColumnInfo parameter class", "CViewColumnUsage typedef class", "CViewInfo parameter class", "CViews typedef class", "CViewTableInfo parameter class", "CViewTableUsage typedef class", "DATA_TYPE", "DATETIME_PRECISION", "DEFAULT_CHARACTER_SET_CATALOG", "DEFAULT_CHARACTER_SET_NAME", "DEFAULT_CHARACTER_SET_SCHEMA", "DEFAULT_COLLATE_CATALOG", "DEFAULT_COLLATE_NAME", "DEFAULT_COLLATE_SCHEMA", "DELETE_RULE", "DESCRIPTION class data member", "DOMAIN_CATALOG", "DOMAIN_NAME", "DOMAIN_SCHEMA", "FILL_FACTOR", "FILTER_CONDITION", "FIXED_PREC_SCALE", "FK_COLUMN_GUID", "FK_COLUMN_NAME", "FK_COLUMN_PROPID", "FK_TABLE_CATALOG", "FK_TABLE_NAME", "FK_TABLE_SCHEMA", "FORM_OF_USE OLE DB column", "GRANTEE", "GRANTOR", "INDEX_CATALOG", "INDEX_NAME", "INDEX_SCHEMA", "INITIAL_SIZE", "INITIALLY_DEFERRED", "IS_DEFERRABLE", "IS_GRANTABLE", "IS_LONG", "IS_NULLABLE", "IS_UPDATABLE", "LITERAL_SUFFIX", "LOCAL_TYPE_NAME", "m_bAutoUniqueValue", "m_bAutoUpdate", "m_bBestMatch", "m_bCaseSensitive", "m_bCheckOption", "m_bClustered", "m_bColumnHasDefault", "m_bFixedPrecScale", "m_bHasDefault", "m_bInitiallyDeferred", "m_bIsDeferrable", "m_bIsGrantable", "m_bIsLong", "m_bIsNullable", "m_bIsUpdatable", "m_bPrimaryKey", "m_bSortBookmarks", "m_bUnique", "m_bUnsignedAttribute", "m_guidColumn", "m_guidFKColumn", "m_guidTable", "m_guidType", "m_nCardinality", "m_nCollation", "m_nColumnFlags", "m_nColumnPropID", "m_nColumnSize", "m_nDataType", "m_nDateTimePrecision", "m_nFillFactor", "m_nFKColumnPropID", "m_nInitialSize", "m_nMaxLength", "m_nMinScale", "m_nNullCollation", "m_nNulls", "m_nNumCharacters", "m_nNumericPrecision", "m_nNumericScale", "m_nOctetLength", "m_nOrdinal", "m_nOrdinalPosition", "m_nPages", "m_nPKColumnPropID", "m_nPrecision", "m_nRowsetNumber", "m_nScale", "m_nSearchable", "m_nType", "m_szBindingStyle", "m_szCatalog", "m_szCharCatalog", "m_szCharName", "m_szCharSchema", "m_szCharSetCatalog", "m_szCharSetName", "m_szCharSetSchema", "m_szCheckClause", "m_szCollateCatalog", "m_szCollateName", "m_szCollateSchema", "m_szCollationCatalog", "m_szCollationName", "m_szCollationSchema", "m_szColumnDefault", "m_szColumnName", "m_szConformance", "m_szConstraintCatalog", "m_szConstraintName", "m_szConstraintSchema", "m_szCreateParams", "m_szDefault", "m_szDefinition", "m_szDeleteRule", "m_szDescription", "m_szDomainCatalog", "m_szDomainName", "m_szDomainSchema", "m_szFilterCondition", "m_szFKColumnName", "m_szFKTableCatalog", "m_szFKTableName", "m_szFKTableSchema", "m_szFormOfUse", "m_szGrantee", "m_szGrantor", "m_szImplementation", "m_szIndexCatalog", "m_szIndexName", "m_szIndexSchema", "m_szIntegrity", "m_szLiteralPrefix", "m_szLocalTypeName", "m_szMatchOption", "m_szName", "m_szObjectCatalog", "m_szObjectName", "m_szObjectSchema", "m_szObjectType", "m_szOwner", "m_szPadAttribute", "m_szParameterName", "m_szPKColumnName", "m_szPKTableCatalog", "m_szPKTableName", "m_szPKTableSchema", "m_szPrivilegeType", "m_szPrivilegeType", "m_szProgrammingLanguage", "m_szSchema", "m_szSource", "m_szSourceCatalog", "m_szSourceName", "m_szSourceSchema", "m_szTableCatalog", "m_szTableName", "m_szTableSchema", "m_szTargetCatalog", "m_szTargetName", "m_szTargetSchema", "m_szType", "m_szTypeLib", "m_szTypeName", "m_szUniqueCatalog", "m_szUniqueName", "m_szUniqueSchema", "m_szUpdateRule", "m_szUpdateRule", "m_szVersion", "m_szYear", "MATCH_OPTION", "MAXIMUM_SCALE", "MINIMUM_SCALE", "NULL_COLLATION", "NULLS", "NUMBER_OF_CHARACTERS", "NUMERIC_PRECISION", "NUMERIC_SCALE", "OBJECT_CATALOG", "OBJECT_NAME", "OBJECT_SCHEMA", "OBJECT_TYPE", "ORDINAL data member", "ORDINAL_POSITION", "TABLE_CATALOG", "TABLE_GUID", "TABLE_NAME", "TABLE_SCHEMA"] -ms.assetid: 4bd881b3-26ca-4bdb-9226-d67560864f29 --- # Schema Rowset Classes and Typedef Classes diff --git a/docs/data/record-view-code-created-by-application-wizard-mfc-data-access.md b/docs/data/record-view-code-created-by-application-wizard-mfc-data-access.md index 73e90f63211..25cbb8cdefb 100644 --- a/docs/data/record-view-code-created-by-application-wizard-mfc-data-access.md +++ b/docs/data/record-view-code-created-by-application-wizard-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Record View Code Created by Application Wizard (MFC Data Access)" -title: "Record View Code Created by Application Wizard (MFC Data Access)" -ms.date: "11/04/2016" +title: "Record View Code Created by Application Wizard (MFC Data Access)" +description: "Learn more about: Record View Code Created by Application Wizard (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["application wizards [C++], record view code", "record views, refreshing controls", "record views, application wizard code"] -ms.assetid: 18fd4703-5939-491d-b759-985f767b951f --- -# Record View Code Created by Application Wizard (MFC Data Access) +# Record View Code Created by Application Wizard (MFC Data Access) The [MFC Application Wizard](../mfc/reference/database-support-mfc-application-wizard.md) overrides the view's `OnInitialUpdate` and `OnGetRecordset` member functions. After the framework creates the frame window, document, and view, it calls `OnInitialUpdate` to initialize the view. `OnInitialUpdate` obtains a pointer to the recordset from the document. A call to the base class [CView::OnInitialUpdate](../mfc/reference/cview-class.md#oninitialupdate) function opens the recordset. The following code shows this process for a `CRecordView`: diff --git a/docs/data/record-views-mfc-data-access.md b/docs/data/record-views-mfc-data-access.md index d6ad32f05e2..2741f14ec1c 100644 --- a/docs/data/record-views-mfc-data-access.md +++ b/docs/data/record-views-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Record Views (MFC Data Access)" -title: "Record Views (MFC Data Access)" -ms.date: "11/04/2016" +title: "Record Views (MFC Data Access)" +description: "Learn more about: Record Views (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["MFC [C++], record views", "ODBC recordsets [C++], record views", "databases [C++], record views", "record views [C++]", "forms [C++], data access tasks"] -ms.assetid: 562122d9-01d8-4284-acf6-ea109ab0408d --- -# Record Views (MFC Data Access) +# Record Views (MFC Data Access) This section applies only to the MFC ODBC classes. For information about OLE DB record views, see [COleDBRecordView](../mfc/reference/coledbrecordview-class.md) and [Using OLE DB Record Views](../data/oledb/using-ole-db-record-views.md). diff --git a/docs/data/schema-mfc-data-access.md b/docs/data/schema-mfc-data-access.md index c45bdeb2bc5..6b5c9e1d0e4 100644 --- a/docs/data/schema-mfc-data-access.md +++ b/docs/data/schema-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Schema (MFC Data Access)" -title: "Schema (MFC Data Access)" -ms.date: "11/04/2016" +title: "Schema (MFC Data Access)" +description: "Learn more about: Schema (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["structures [C++], database", "databases [C++], schema", "database schema [C++], about database schemas", "database schema [C++]", "schemas [C++], database", "structures [C++]"] -ms.assetid: 7d17e35f-1ccf-4853-b915-5b8c7a45b9ee --- -# Schema (MFC Data Access) +# Schema (MFC Data Access) A database schema describes the current structure of the tables and database views in the database. In general, wizard-generated code assumes that the schema for the table or tables accessed by a recordset will not change, but the database classes can deal with some schema changes, such as adding, reordering, or deleting unbound columns. If a table changes, you must manually update the recordset for the table, then recompile your application. diff --git a/docs/data/supporting-navigation-in-a-record-view-mfc-data-access.md b/docs/data/supporting-navigation-in-a-record-view-mfc-data-access.md index df688530ed2..0bc07831d5d 100644 --- a/docs/data/supporting-navigation-in-a-record-view-mfc-data-access.md +++ b/docs/data/supporting-navigation-in-a-record-view-mfc-data-access.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Supporting Navigation in a Record View (MFC Data Access)" -title: "Supporting Navigation in a Record View (MFC Data Access)" -ms.date: "11/04/2016" +title: "Supporting Navigation in a Record View (MFC Data Access)" +description: "Learn more about: Supporting Navigation in a Record View (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["records [C++], navigating", "record views, navigation", "navigation [C++], in record view"] -ms.assetid: 227f2a6d-87c9-4656-807a-8e246965bcce +ms.topic: reference --- -# Supporting Navigation in a Record View (MFC Data Access) +# Supporting Navigation in a Record View (MFC Data Access) This topic explains how to support movement from record to record in your [CRecordView](../mfc/reference/crecordview-class.md) class, including information about: diff --git a/docs/data/toc.yml b/docs/data/toc.yml index aea9e6bb11e..af9d03c0fad 100644 --- a/docs/data/toc.yml +++ b/docs/data/toc.yml @@ -575,7 +575,7 @@ items: items: - name: SQL in ODBC href: ../data/odbc/sql.md - - name: "SQL: Customizing Your recordset’s SQL statement (ODBC)" + - name: "SQL: Customizing Your recordset's SQL statement (ODBC)" href: ../data/odbc/sql-customizing-your-recordsets-sql-statement-odbc.md - name: "SQL: SQL and C++ data types (ODBC)" href: ../data/odbc/sql-sql-and-cpp-data-types-odbc.md diff --git a/docs/data/transactions-mfc-data-access.md b/docs/data/transactions-mfc-data-access.md index b9008f382a7..6d9bcec6ace 100644 --- a/docs/data/transactions-mfc-data-access.md +++ b/docs/data/transactions-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Transactions (MFC Data Access)" -title: "Transactions (MFC Data Access)" -ms.date: "11/04/2016" +title: "Transactions (MFC Data Access)" +description: "Learn more about: Transactions (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["transactions [C++], support for", "transactions [C++]", "databases [C++], transactions"] -ms.assetid: f80afbfe-1517-4fec-8870-9ffc70a58b05 --- -# Transactions (MFC Data Access) +# Transactions (MFC Data Access) The concept of a transaction was developed to handle cases in which the resulting state of the database depends on the total success of a series of operations. This could come about because successive operations might modify the results of previous operations. In such cases, if any one operation fails, the resulting state could be indeterminate. diff --git a/docs/data/user-interface-updating-for-record-views-mfc-data-access.md b/docs/data/user-interface-updating-for-record-views-mfc-data-access.md index 5e489fd9018..e221fc09c0d 100644 --- a/docs/data/user-interface-updating-for-record-views-mfc-data-access.md +++ b/docs/data/user-interface-updating-for-record-views-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: User-Interface Updating for Record Views (MFC Data Access)" -title: "User-Interface Updating for Record Views (MFC Data Access)" -ms.date: "11/04/2016" +title: "User-Interface Updating for Record Views (MFC Data Access)" +description: "Learn more about: User-Interface Updating for Record Views (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["user interfaces, updating", "menus, updating as context changes", "record views, user interface"] -ms.assetid: 2c7914b6-2dc3-40c3-b2f2-8371da2a4063 --- -# User-Interface Updating for Record Views (MFC Data Access) +# User-Interface Updating for Record Views (MFC Data Access) `CRecordView` provides default user-interface update handlers for the navigation commands. These handlers automate enabling and disabling the user-interface objects — menu items and toolbar buttons. The application wizard supplies standard menus and, if you choose the **Dockable Toolbar** option, a set of toolbar buttons for the commands. If you create a record view class using `CRecordView`, you might want to add similar user-interface objects to your application. diff --git a/docs/data/using-a-record-view-mfc-data-access.md b/docs/data/using-a-record-view-mfc-data-access.md index 18724bc75b9..6cb21b3e690 100644 --- a/docs/data/using-a-record-view-mfc-data-access.md +++ b/docs/data/using-a-record-view-mfc-data-access.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: Using a Record View (MFC Data Access)" -title: "Using a Record View (MFC Data Access)" -ms.date: "11/04/2016" +title: "Using a Record View (MFC Data Access)" +description: "Learn more about: Using a Record View (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["record views, customizing default code"] -ms.assetid: 91f2828f-0666-4273-ae28-e4703fd98521 +ms.topic: concept-article --- -# Using a Record View (MFC Data Access) +# Using a Record View (MFC Data Access) This topic explains how you might commonly customize the default code for record views that the wizard writes for you. Typically, you want to constrain the record selection with a [filter](../data/odbc/recordset-filtering-records-odbc.md) or [parameters](../data/odbc/recordset-parameterizing-a-recordset-odbc.md), perhaps [sort](../data/odbc/recordset-sorting-records-odbc.md) the records, customize the SQL statement. diff --git a/docs/data/your-role-in-working-with-a-record-view-mfc-data-access.md b/docs/data/your-role-in-working-with-a-record-view-mfc-data-access.md index be06ed8b285..f88cfad605f 100644 --- a/docs/data/your-role-in-working-with-a-record-view-mfc-data-access.md +++ b/docs/data/your-role-in-working-with-a-record-view-mfc-data-access.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: Your Role in Working with a Record View (MFC Data Access)" -title: "Your Role in Working with a Record View (MFC Data Access)" -ms.date: "11/04/2016" +title: "Your Role in Working with a Record View (MFC Data Access)" +description: "Learn more about: Your Role in Working with a Record View (MFC Data Access)" +ms.date: 11/04/2016 helpviewer_keywords: ["record views, customizing default code", "MFC, record views"] -ms.assetid: 691e89a5-ff21-4ca3-9278-69d4678288bb --- -# Your Role in Working with a Record View (MFC Data Access) +# Your Role in Working with a Record View (MFC Data Access) The following table shows what you typically must do to work with a record view and what the framework does for you. diff --git a/docs/docfx.json b/docs/docfx.json index 11e30e03f93..e450d439f85 100644 --- a/docs/docfx.json +++ b/docs/docfx.json @@ -6,15 +6,15 @@ "**/*.md", "**/*.yml" ], - "group": "group-vc2015", - "src": ".", "exclude": [ "**/2019/**", "**/2017/**", "**/obj/**", "vcppdocs/**", "**/includes/**" - ] + ], + "src": ".", + "group": "group-vc2015" } ], "resource": [ @@ -25,42 +25,48 @@ "**/*.gif", "**/*.svg" ], - "group": "group-vc2015", - "src": ".", "exclude": [ "**/obj/**", "vcppdocs/**", "**/includes/**" - ] + ], + "src": ".", + "group": "group-vc2015" } ], "overwrite": [], "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", + "ms.topic": "concept-article", "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" }, @@ -96,147 +102,257 @@ "atl/reference/**.md": "reference", "atl-mfc-shared/**.md": "reference", "build/reference/**.md": "reference", + "build-insights/reference/sdk/c-event-data-types/**.md": "reference", "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", + "ide/refactoring/**.md": "how-to", "extensions/**.md": "reference", "intrinsics/**.md": "reference", "mfc/reference/**.md": "reference", "overview/**.md": "overview", - "parallel/amp/reference/**.md": "reference", - "parallel/concrt/reference/**.md": "reference", - "parallel/openmp/reference/**.md": "reference", + "parallel/**.md": "how-to", "preprocessor/**.md": "reference", "safeint/**.md": "reference", "sanitizers/**.md": "reference", "standard-library/**.md": "reference", - "windows/attributes/**.md": "reference" + "windows/attributes/**.md": "reference", + "**/how-to*.md": "how-to" + }, + "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/**.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" }, - "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.update-cycle": { + "assembler/**.md": "3650-days", + "assembler/**.yml": "3650-days", + "attributes/**.md": "3650-days", + "attributes/**.yml": "3650-days", + "atl/**.md": "3650-days", + "atl/**.yml": "3650-days", + "atl-mfc-shared/**.md": "3650-days", + "atl-mfc-shared/**.yml": "3650-days", + "build/**.md": "1825-days", + "build/**.yml": "1825-days", + "c-language/**.md": "3650-days", + "c-language/**.yml": "3650-days", + "c-runtime-library/**.md": "3650-days", + "c-runtime-library/**.yml": "3650-days", + "cpp/**.md": "1095-days", + "cpp/**.yml": "1095-days", + "cppcx/**.md": "3650-days", + "cppcx/**.yml": "3650-days", + "cross-platform/**.md": "1825-days", + "cross-platform/**.yml": "1825-days", + "data/**.md": "3650-days", + "data/**.yml": "3650-days", + "dotnet/**.md": "3650-days", + "dotnet/**.yml": "3650-days", + "embedded/**.md": "3650-days", + "embedded/**.yml": "3650-days", + "error-messages/**.md": "3650-days", + "error-messages/**.yml": "3650-days", + "extensions/**.md": "3650-days", + "extensions/**.yml": "3650-days", + "intrinsics/**.md": "3650-days", + "intrinsics/**.yml": "3650-days", + "mfc/**.md": "3650-days", + "mfc/**.yml": "3650-days", + "parallel/**.md": "3650-days", + "parallel/**.yml": "3650-days", + "porting/**.md": "1095-days", + "porting/**.yml": "1095-days", + "preprocessor/**.md": "3650-days", + "preprocessor/**.yml": "3650-days", + "safeint/**.md": "3650-days", + "safeint/**.yml": "3650-days", + "standard-library/**.md": "3650-days", + "standard-library/**.yml": "3650-days", + "text/**.md": "3650-days", + "text/**.yml": "3650-days", + "windows/**.md": "1825-days", + "windows/**.yml": "1825-days" }, "author": { - "index.md": "corob-msft", - "assembler/**.md": "corob-msft", - "attributes/**.md": "corob-msft", - "atl/**.md": "tylermsft", - "atl-mfc-shared/**.md": "tylermsft", - "build/**.md": "corob-msft", - "build-insights/**.md": "kevcadieux", - "c-language/**.md": "corob-msft", - "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", - "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", - "linux/**.md": "tylermsft", - "mfc/**.md": "tylermsft", - "overview/**.md": "corob-msft", - "parallel/amp/**.md": "tylermsft", - "parallel/concrt/**.md": "tylermsft", - "parallel/**.md": "tylermsft", - "porting/**.md": "corob-msft", - "preprocessor/**.md": "corob-msft", - "safeint/**.md": "tylermsft", - "sanitizers/**.md": "corob-msft", - "security/**.md": "corob-msft", - "standard-library/**.md": "tylermsft", - "text/**.md": "tylermsft", - "windows/**.md": "corob-msft" + "index.md": "TylerMSFT", + "assembler/**.md": "TylerMSFT", + "assembler/**.yml": "TylerMSFT", + "attributes/**.md": "TylerMSFT", + "attributes/**.yml": "TylerMSFT", + "atl/**.md": "TylerMSFT", + "atl/**.yml": "TylerMSFT", + "atl-mfc-shared/**.md": "TylerMSFT", + "atl-mfc-shared/**.yml": "TylerMSFT", + "build/**.md": "TylerMSFT", + "build/**.yml": "TylerMSFT", + "build-insights/**.md": "TylerMSFT", + "build-insights/**.yml": "TylerMSFT", + "c-language/**.md": "TylerMSFT", + "c-language/**.yml": "TylerMSFT", + "c-runtime-library/**.md": "TylerMSFT", + "c-runtime-library/**.yml": "TylerMSFT", + "cloud/**.md": "TylerMSFT", + "cloud/**.yml": "TylerMSFT", + "code-quality/**.md": "TylerMSFT", + "code-quality/**.yml": "TylerMSFT", + "cpp/**.md": "TylerMSFT", + "cpp/**.yml": "TylerMSFT", + "cppcx/**.md": "TylerMSFT", + "cppcx/**.yml": "TylerMSFT", + "cross-platform/**.md": "TylerMSFT", + "cross-platform/**.yml": "TylerMSFT", + "data/**.md": "TylerMSFT", + "data/**.yml": "TylerMSFT", + "dotnet/**.md": "TylerMSFT", + "dotnet/**.yml": "TylerMSFT", + "error-messages/**.md": "TylerMSFT", + "error-messages/**.yml": "TylerMSFT", + "extensions/**.md": "TylerMSFT", + "extensions/**.yml": "TylerMSFT", + "get-started/**.md": "TylerMSFT", + "get-started/**.yml": "TylerMSFT", + "ide/**.md": "TylerMSFT", + "ide/**.yml": "TylerMSFT", + "intrinsics/**.md": "TylerMSFT", + "intrinsics/**.yml": "TylerMSFT", + "linux/**.md": "TylerMSFT", + "linux/**.yml": "TylerMSFT", + "mfc/**.md": "TylerMSFT", + "mfc/**.yml": "TylerMSFT", + "overview/**.md": "TylerMSFT", + "overview/**.yml": "TylerMSFT", + "parallel/**.md": "TylerMSFT", + "parallel/**.yml": "TylerMSFT", + "porting/**.md": "TylerMSFT", + "porting/**.yml": "TylerMSFT", + "preprocessor/**.md": "TylerMSFT", + "preprocessor/**.yml": "TylerMSFT", + "safeint/**.md": "TylerMSFT", + "safeint/**.yml": "TylerMSFT", + "sanitizers/**.md": "TylerMSFT", + "sanitizers/**.yml": "TylerMSFT", + "security/**.md": "TylerMSFT", + "security/**.yml": "TylerMSFT", + "standard-library/**.md": "TylerMSFT", + "standard-library/**.yml": "TylerMSFT", + "text/**.md": "TylerMSFT", + "text/**.yml": "TylerMSFT", + "windows/**.md": "TylerMSFT", + "windows/**.yml": "TylerMSFT" }, "ms.author": { - "index.md": "corob", - "assembler/**.md": "corob", + "index.md": "twhitney", + "assembler/**.md": "twhitney", + "assembler/**.yml": "twhitney", "atl/**.md": "twhitney", + "atl/**.yml": "twhitney", "atl-mfc-shared/**.md": "twhitney", - "attributes/**.md": "corob", - "build/**.md": "corob", - "build-insights/**.md": "kevca", - "c-language/**.md": "corob", + "atl-mfc-shared/**.yml": "twhitney", + "attributes/**.md": "twhitney", + "attributes/**.yml": "twhitney", + "build/**.md": "twhitney", + "build/**.yml": "twhitney", + "build-insights/**.md": "twhitney", + "build-insights/**.yml": "twhitney", + "c-language/**.md": "twhitney", + "c-language/**.yml": "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", + "c-runtime-library/**.yml": "twhitney", + "cloud/**.md": "twhitney", + "cloud/**.yml": "twhitney", + "code-quality/**.md": "twhitney", + "code-quality/**.yml": "twhitney", + "cpp/**.md": "twhitney", + "cpp/**.yml": "twhitney", + "cppcx/**.md": "twhitney", + "cppcx/**.yml": "twhitney", + "cross-platform/**.md": "twhitney", + "cross-platform/**.yml": "twhitney", + "data/**.md": "twhitney", + "data/**.yml": "twhitney", "dotnet/**.md": "twhitney", - "error-messages/**.md": "corob", - "extensions/**.md": "corob", - "get-started/**.md": "corob", - "ide/**.md": "corob", - "intrinsics/**.md": "corob", + "dotnet/**.yml": "twhitney", + "error-messages/**.md": "twhitney", + "error-messages/**.yml": "twhitney", + "extensions/**.md": "twhitney", + "extensions/**.yml": "twhitney", + "get-started/**.md": "twhitney", + "get-started/**.yml": "twhitney", + "ide/**.md": "twhitney", + "ide/**.yml": "twhitney", + "intrinsics/**.md": "twhitney", + "intrinsics/**.yml": "twhitney", "linux/**.md": "twhitney", + "linux/**.yml": "twhitney", "mfc/**.md": "twhitney", - "overview/**.md": "corob", - "parallel/amp/**.md": "twhitney", - "parallel/concrt/**.md": "twhitney", + "mfc/**.yml": "twhitney", + "overview/**.md": "twhitney", + "overview/**.yml": "twhitney", "parallel/**.md": "twhitney", - "porting/**.md": "corob", - "preprocessor/**.md": "corob", + "parallel/**.yml": "twhitney", + "porting/**.md": "twhitney", + "porting/**.yml": "twhitney", + "preprocessor/**.md": "twhitney", + "preprocessor/**.yml": "twhitney", "safeint/**.md": "twhitney", - "sanitizers/**.md": "corob", - "security/**.md": "corob", + "safeint/**.yml": "twhitney", + "sanitizers/**.md": "twhitney", + "sanitizers/**.yml": "twhitney", + "security/**.md": "twhitney", + "security/**.yml": "twhitney", "standard-library/**.md": "twhitney", + "standard-library/**.yml": "twhitney", "text/**.md": "twhitney", - "windows/**.md": "corob" + "text/**.yml": "twhitney", + "windows/**.md": "twhitney", + "windows/**.yml": "twhitney" } }, "template": [], + "markdownEngineName": "markdig", "xref": [], - "dest": "vcppdocs", "groups": { "group-vc2015": { - "moniker_range": ">= msvc-140", - "dest": "vcppdocs-2015" + "dest": "vcppdocs-2015", + "moniker_range": ">= msvc-140" } }, - "markdownEngineName": "markdig" + "dest": "vcppdocs" } -} +} \ No newline at end of file diff --git a/docs/dotnet/adapter-stl-clr.md b/docs/dotnet/adapter-stl-clr.md index 957a358febe..7bd08c581e5 100644 --- a/docs/dotnet/adapter-stl-clr.md +++ b/docs/dotnet/adapter-stl-clr.md @@ -7,9 +7,9 @@ f1_keywords: ["", "cliext::collection_adapter", "cliext::collect helpviewer_keywords: [" header [STL/CLR]", "adapter [STL/CLR]", " header [STL/CLR]", "collection_adapter class [STL/CLR]", "base member [STL/CLR]", "begin member [STL/CLR]", "collection_adapter member [STL/CLR]", "difference_type member [STL/CLR]", "end member [STL/CLR]", "iterator member [STL/CLR]", "key_type member [STL/CLR]", "mapped_type member [STL/CLR]", "operator= member [STL/CLR]", "reference member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "value_type member [STL/CLR]", "make_collection function [STL/CLR]", "range_adapter class [STL/CLR]", "operator= member [STL/CLR]", "range_adapter member [STL/CLR]"] ms.assetid: 71ce7e51-42b6-4f70-9595-303791a97677 --- -# adapter (STL/CLR) +# `` (STL/CLR) -The STL/CLR header `` specifies two template classes (`collection_adapter` and `range_adapter`), and the template function `make_collection`. +The STL/CLR header `` specifies two class templates (`collection_adapter` and `range_adapter`), and the function template `make_collection`. ## Syntax @@ -21,22 +21,22 @@ The STL/CLR header `` specifies two template classes (`collectio **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Class|Description| -|-----------|-----------------| -|[collection_adapter (STL/CLR)](#collection_adapter)|Wraps the Base Class Library (BCL) collection as a range.| -|[range_adapter (STL/CLR)](#range_adapter)|Wraps the range as a BCL collection.| +| Class | Description | +|---|---| +| [`collection_adapter`](#collection_adapter) | Wraps the Base Class Library (BCL) collection as a range. | +| [`range_adapter`](#range_adapter) | Wraps the range as a BCL collection. | -|Function|Description| -|--------------|-----------------| -|[make_collection (STL/CLR)](#make_collection)|Creates a range adapter using an iterator pair.| +| Function | Description | +|---|---| +| [`make_collection`](#make_collection) | Creates a range adapter using an iterator pair. | ## Members -## collection_adapter (STL/CLR) +## `collection_adapter` Wraps a .NET collection for use as an STL/CLR container. A `collection_adapter` is a template class that describes a simple STL/CLR container object. It wraps a Base Class Library (BCL) interface, and returns an iterator pair that you use to manipulate the controlled sequence. @@ -75,52 +75,52 @@ template +*`Coll`*\ The type of the wrapped collection. ### Specializations -|Specialization|Description| -|--------------------|-----------------| -|IEnumerable|Sequences through elements.| -|ICollection|Maintains a group of elements.| -|IList|Maintains an ordered group of elements.| -|IDictionary|Maintain a set of {key, value} pairs.| -|IEnumerable\|Sequences through typed elements.| -|ICollection\|Maintains a group of typed elements.| -|IList\|Maintains an ordered group of typed elements.| -|IDictionary\|Maintains a set of typed {key, value} pairs.| +| Specialization | Description | +|---|---| +| `IEnumerable` | Sequences through elements. | +| `ICollection` | Maintains a group of elements. | +| `IList` | Maintains an ordered group of elements. | +| `IDictionary` | Maintain a set of {key, value} pairs. | +| `IEnumerable` | Sequences through typed elements. | +| `ICollection` | Maintains a group of typed elements. | +| `IList` | Maintains an ordered group of typed elements. | +| `IDictionary` | Maintains a set of typed {key, value} pairs. | ### Members -|Type Definition|Description| -|---------------------|-----------------| -|[collection_adapter::difference_type (STL/CLR)](#difference_type)|The type of a signed distance between two elements.| -|[collection_adapter::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[collection_adapter::key_type (STL/CLR)](#key_type)|The type of a dictionary key.| -|[collection_adapter::mapped_type (STL/CLR)](#mapped_type)|The type of a dictionary value.| -|[collection_adapter::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[collection_adapter::size_type (STL/CLR)](#size_type)|The type of a signed distance between two elements.| -|[collection_adapter::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[collection_adapter::base (STL/CLR)](#base)|Designates the wrapped BCL interface.| -|[collection_adapter::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[collection_adapter::collection_adapter (STL/CLR)](#collection_adapter_collection_adapter)|Constructs an adapter object.| -|[collection_adapter::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[collection_adapter::size (STL/CLR)](#size)|Counts the number of elements.| -|[collection_adapter::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| - -|Operator|Description| -|--------------|-----------------| -|[collection_adapter::operator= (STL/CLR)](#op_eq)|Replaces the stored BCL handle.| +| Type definition | Description | +|---|---| +| [`collection_adapter::difference_type`](#difference_type) | The type of a signed distance between two elements. | +| [`collection_adapter::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`collection_adapter::key_type`](#key_type) | The type of a dictionary key. | +| [`collection_adapter::mapped_type`](#mapped_type) | The type of a dictionary value. | +| [`collection_adapter::reference`](#reference) | The type of a reference to an element. | +| [`collection_adapter::size_type`](#size_type) | The type of a signed distance between two elements. | +| [`collection_adapter::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`collection_adapter::base`](#base) | Designates the wrapped BCL interface. | +| [`collection_adapter::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`collection_adapter::collection_adapter`](#collection_adapter_collection_adapter) | Constructs an adapter object. | +| [`collection_adapter::end`](#end) | Designates the end of the controlled sequence. | +| [`collection_adapter::size`](#size) | Counts the number of elements. | +| [`collection_adapter::swap`](#swap) | Swaps the contents of two containers. | + +| Operator | Description | +|---|---| +| [`collection_adapter::operator=`](#op_eq) | Replaces the stored BCL handle. | ### Remarks You use this template class to manipulate a BCL container as a STL/CLR container. The `collection_adapter` stores a handle to a BCL interface, which in turn controls a sequence of elements. A `collection_adapter` object `X` returns a pair of input iterators `X.begin()` and `X.end()` that you use to visit the elements, in order. Some of the specializations also let you write `X.size()` to determine the length of the controlled sequence. -## collection_adapter::base (STL/CLR) +## `collection_adapter::base` Designates the wrapped BCL interface. @@ -164,7 +164,7 @@ x x x x x x base() same = True ``` -## collection_adapter::begin (STL/CLR) +## `collection_adapter::begin` Designates the beginning of the controlled sequence. @@ -215,7 +215,7 @@ a b c *++begin() = b ``` -## collection_adapter::collection_adapter (STL/CLR) +## `collection_adapter::collection_adapter` Constructs an adapter object. @@ -230,10 +230,10 @@ collection_adapter(Coll^ collection); #### Parameters -*collection*
+*`collection`*\ BCL handle to wrap. -*right*
+*`right`*\ Object to copy. ### Remarks @@ -248,13 +248,13 @@ The constructor: `collection_adapter(collection_adapter% right);` -initializes the stored handle with `right.`[collection_adapter::base (STL/CLR)](#base)`()`. +initializes the stored handle with `right.base()`. The constructor: `collection_adapter(collection_adapter^ right);` -initializes the stored handle with `right->`[collection_adapter::base (STL/CLR)](#base)`()`. +initializes the stored handle with `right->base()`. The constructor: @@ -309,7 +309,7 @@ x x x x x x x x x x x x ``` -## collection_adapter::difference_type (STL/CLR) +## `collection_adapter::difference_type` The types of a signed distance between two elements. @@ -361,7 +361,7 @@ a b c end()-begin() = 3 ``` -## collection_adapter::end (STL/CLR) +## `collection_adapter::end` Designates the end of the controlled sequence. @@ -406,7 +406,7 @@ int main() a b c ``` -## collection_adapter::iterator (STL/CLR) +## `collection_adapter::iterator` The type of an iterator for the controlled sequence. @@ -451,7 +451,7 @@ int main() a b c ``` -## collection_adapter::key_type (STL/CLR) +## `collection_adapter::key_type` The type of a dictionary key. @@ -463,7 +463,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter `Key`, in a specialization for `IDictionary` or `IDictionary`; otherwise it is not defined. +The type is a synonym for the template parameter `Key`, in a specialization for `IDictionary` or `IDictionary`; otherwise it isn't defined. ### Example @@ -501,7 +501,7 @@ int main() [a 1] [b 2] [c 3] ``` -## collection_adapter::mapped_type (STL/CLR) +## `collection_adapter::mapped_type` The type of a dictionary value. @@ -513,7 +513,7 @@ typedef Value mapped_type; ### Remarks -The type is a synonym for the template parameter `Value`, in a specialization for `IDictionary` or `IDictionary`; otherwise it is not defined. +The type is a synonym for the template parameter `Value`, in a specialization for `IDictionary` or `IDictionary`; otherwise it isn't defined. ### Example @@ -551,7 +551,7 @@ int main() [a 1] [b 2] [c 3] ``` -## collection_adapter::operator= (STL/CLR) +## `collection_adapter::operator=` Replaces the stored BCL handle. @@ -563,12 +563,12 @@ collection_adapter% operator=(collection_adapter% right); #### Parameters -*right*
+*`right`*\ Adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the stored BCL handle with a copy of the stored BCL handle in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the stored BCL handle with a copy of the stored BCL handle in *`right`*. ### Example @@ -608,7 +608,7 @@ a b c a b c ``` -## collection_adapter::reference (STL/CLR) +## `collection_adapter::reference` The type of a reference to an element. @@ -656,7 +656,7 @@ int main() a b c ``` -## collection_adapter::size (STL/CLR) +## `collection_adapter::size` Counts the number of elements. @@ -668,7 +668,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. It is not defined in a specialization for `IEnumerable` or `IEnumerable`. +The member function returns the length of the controlled sequence. It isn't defined in a specialization for `IEnumerable` or `IEnumerable`. ### Example @@ -699,9 +699,9 @@ x x x x x x size() = 6 ``` -## collection_adapter::size_type (STL/CLR) +## `collection_adapter::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -744,7 +744,7 @@ x x x x x x size() = 6 ``` -## collection_adapter::swap (STL/CLR) +## `collection_adapter::swap` Swaps the contents of two containers. @@ -756,12 +756,12 @@ void swap(collection_adapter% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the stored BCL handles between **`*this`** and *right*. +The member function swaps the stored BCL handles between **`*this`** and *`right`*. ### Example @@ -813,7 +813,7 @@ x x x x x a b c ``` -## collection_adapter::value_type (STL/CLR) +## `collection_adapter::value_type` The type of an element. @@ -825,7 +825,7 @@ typedef Value value_type; ### Remarks -The type is a synonym for the template parameter *Value*, if present in the specialization; otherwise it is a synonym for `System::Object^`. +The type is a synonym for the template parameter *`Value`*, if present in the specialization; otherwise it's a synonym for `System::Object^`. ### Example @@ -875,18 +875,18 @@ template #### Parameters -*Iter*
+*`Iter`*\ The type of the wrapped iterators. -*first*
+*`first`*\ First iterator to wrap. -*last*
+*`last`*\ Second iterator to wrap. ### Remarks -The template function returns `gcnew range_adapter(first, last)`. You use it to construct a `range_adapter` object from a pair of iterators. +The function template returns `gcnew range_adapter(first, last)`. You use it to construct a `range_adapter` object from a pair of iterators. ### Example @@ -942,7 +942,7 @@ SyncRoot not nullptr = True ## range_adapter (STL/CLR) -A template class that wraps a pair of iterators that are used to implement several Base Class Library (BCL) interfaces. You use the range_adapter to manipulate an STL/CLR range as if it were a BCL collection. +A template class that wraps a pair of iterators that are used to implement several Base Class Library (BCL) interfaces. You use the range_adapter to manipulate an STL/CLR range as if it was a BCL collection. ### Syntax @@ -959,33 +959,33 @@ template #### Parameters -*Iter*
+*`Iter`*\ The type associated with the wrapped iterators. ### Members -|Member Function|Description| -|---------------------|-----------------| -|[range_adapter::range_adapter (STL/CLR)](#range_adapter_range_adapter)|Constructs an adapter object.| +| Member function | Description | +|---|---| +| [`range_adapter::range_adapter`](#range_adapter_range_adapter) | Constructs an adapter object. | -|Operator|Description| -|--------------|-----------------| -|[range_adapter::operator= (STL/CLR)](#range_adapter_op_eq)|Replaces the stored iterator pair.| +| Operator | Description | +|---|---| +| [`range_adapter::operator=`](#range_adapter_op_eq) | Replaces the stored iterator pair. | ### Interfaces -|Interface|Description| -|---------------|-----------------| -||Iterates through elements in the collection.| -||Maintains a group of elements.| -||Iterates through typed elements in the collection..| -||Maintains a group of typed elements.| +| Interface | Description | +|---|---| +| | Iterates through elements in the collection. | +| | Maintains a group of elements. | +| | Iterates through typed elements in the collection. | +| | Maintains a group of typed elements. | ### Remarks The range_adapter stores a pair of iterators, which in turn delimit a sequence of elements. The object implements four BCL interfaces that let you iterate through the elements, in order. You use this template class to manipulate STL/CLR ranges much like BCL containers. -## range_adapter::operator= (STL/CLR) +## `range_adapter::operator=` Replaces the stored iterator pair. @@ -997,12 +997,12 @@ range_adapter% operator=(range_adapter% right); #### Parameters -*right*
+*`right`*\ Adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the stored iterator pair with a copy of the stored iterator pair in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the stored iterator pair with a copy of the stored iterator pair in *`right`*. ### Example @@ -1042,7 +1042,7 @@ a b c a b c ``` -## range_adapter::range_adapter (STL/CLR) +## `range_adapter::range_adapter` Constructs an adapter object. @@ -1057,13 +1057,13 @@ range_adapter(Iter first, Iter last); #### Parameters -*first*
+*`first`*\ First iterator to wrap. -*last*
+*`last`*\ Second iterator to wrap. -*right*
+*`right`*\ Object to copy. ### Remarks @@ -1078,7 +1078,7 @@ The constructor: `range_adapter(range_adapter% right);` -initializes the stored iterator pair by copying the pair stored in *right*. +initializes the stored iterator pair by copying the pair stored in *`right`*. The constructor: @@ -1090,7 +1090,7 @@ The constructor: `range_adapter(Iter^ first, last);` -initializes the stored iterator pair with *first* and *last*. +initializes the stored iterator pair with *`first`* and *`last`*. ### Example diff --git a/docs/dotnet/algorithm-stl-clr.md b/docs/dotnet/algorithm-stl-clr.md index d719dd4ab43..7b08823a394 100644 --- a/docs/dotnet/algorithm-stl-clr.md +++ b/docs/dotnet/algorithm-stl-clr.md @@ -9,7 +9,7 @@ ms.assetid: ee2718dc-a98d-40b8-8341-593fe7d2ac15 --- # algorithm (STL/CLR) -Defines STL/CLR container template functions that perform algorithms. +Defines STL/CLR container function templates that perform algorithms. ## Syntax diff --git a/docs/dotnet/auto-gcroot-class.md b/docs/dotnet/auto-gcroot-class.md index 00b3976e160..0998fb94764 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" -ms.date: "01/16/2019" +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 @@ -49,8 +47,8 @@ The managed type to be embedded. |---------|-----------| |[`auto_gcroot::operator->`](#operator-arrow)|The member access operator.| |[auto_gcroot::operator=](#operator-assign)|Assignment operator.| -|[auto_gcroot::operator auto_gcroot](#operator-auto-gcroot)|Type-cast operator between `auto_gcroot` and compatible types.| -|[auto_gcroot::operator bool](#operator-bool)|Operator for using `auto_gcroot` in a conditional expression.| +|[auto_gcroot::operator auto_gcroot](#operator-auto-gcroot)|Type-cast operator between `auto_gcroot` and compatible types.| +|[auto_gcroot::operator bool](#operator-bool)|Operator for using `auto_gcroot` in a conditional expression.| |[auto_gcroot::operator!](#operator-logical-not)|Operator for using `auto_gcroot` in a conditional expression.| ## Requirements @@ -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/auto-handle-class.md b/docs/dotnet/auto-handle-class.md index cf238bd76d9..8363250a9a4 100644 --- a/docs/dotnet/auto-handle-class.md +++ b/docs/dotnet/auto-handle-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: auto_handle Class" title: "auto_handle Class" -ms.date: "01/16/2019" +description: "Learn more about: auto_handle Class" +ms.date: 01/16/2019 ms.topic: "reference" f1_keywords: ["msclr::auto_handle::auto_handle", "msclr::auto_handle::get", "msclr::auto_handle::release", "msclr::auto_handle::reset", "msclr::auto_handle::swap", "msclr::auto_handle::operator->", "msclr::auto_handle::operator=", "msclr::auto_handle::operator auto_handle", "msclr::auto_handle::operator!"] helpviewer_keywords: ["msclr::auto_handle class"] -ms.assetid: a65604d1-ecbb-44fd-ae2f-696ddeeed9d6 --- # auto_handle Class @@ -25,14 +24,14 @@ The managed type to be embedded. ## Members -### Public constructors +### Public constructors |Name|Description| |---------|-----------| |[auto_handle::auto_handle](#auto-handle)|The `auto_handle` constructor.| |[auto_handle::~auto_handle](#tilde-auto-handle)|The `auto_handle` destructor.| -### Public methods +### Public methods |Name|Description| |---------|-----------| diff --git a/docs/dotnet/avoiding-exceptions-on-clr-shutdown-when-consuming-com-objects-built-with-clr.md b/docs/dotnet/avoiding-exceptions-on-clr-shutdown-when-consuming-com-objects-built-with-clr.md index 3959e713c67..bc10b85fb92 100644 --- a/docs/dotnet/avoiding-exceptions-on-clr-shutdown-when-consuming-com-objects-built-with-clr.md +++ b/docs/dotnet/avoiding-exceptions-on-clr-shutdown-when-consuming-com-objects-built-with-clr.md @@ -4,6 +4,7 @@ title: "Avoiding Exceptions thrown by COM Objects Built with -clr" ms.date: "11/04/2016" helpviewer_keywords: ["interop [C++], CLR shutdown exceptions", "/clr compiler option [C++], CLR shutdown exceptions", "mixed assemblies [C++], CLR shutdown exceptions", "/clr compiler option [C++], COM objects", "interoperability [C++], CLR shutdown exceptions", "CLR shutdown exceptions [C++]"] ms.assetid: 41249d83-4b51-4e46-866f-27f475f2498c +ms.topic: concept-article --- # Avoiding Exceptions on CLR Shutdown When Consuming COM Objects Built with /clr diff --git a/docs/dotnet/boxing-cpp-cli.md b/docs/dotnet/boxing-cpp-cli.md index e012f8806eb..f57d3ad8922 100644 --- a/docs/dotnet/boxing-cpp-cli.md +++ b/docs/dotnet/boxing-cpp-cli.md @@ -3,6 +3,7 @@ description: "Learn more about: Boxing (C++/CLI)" title: "Boxing (C++/CLI)" ms.date: "11/04/2016" ms.assetid: f4ee27a8-6a34-432d-b9ec-39285d513b23 +ms.topic: concept-article --- # Boxing (C++/CLI) diff --git a/docs/dotnet/calling-native-functions-from-managed-code.md b/docs/dotnet/calling-native-functions-from-managed-code.md index fd914a432a2..78930676f74 100644 --- a/docs/dotnet/calling-native-functions-from-managed-code.md +++ b/docs/dotnet/calling-native-functions-from-managed-code.md @@ -4,6 +4,7 @@ title: "Calling Native Functions from Managed Code" ms.date: "11/04/2016" helpviewer_keywords: ["native functions called from managed code [C++]", "managed code [C++], interoperability", "platform invoke [C++], interoperability", "interoperabiliy [C++], calling native functions from managed code", "calling native functions from managed code", "interop [C++], calling native functions from managed code"] ms.assetid: 982cef18-20d9-42b4-8242-a77fa65f2e36 +ms.topic: concept-article --- # Calling Native Functions from Managed Code diff --git a/docs/dotnet/com-ptr-class.md b/docs/dotnet/com-ptr-class.md index 047e3491791..e72c3f8d9e0 100644 --- a/docs/dotnet/com-ptr-class.md +++ b/docs/dotnet/com-ptr-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: com::ptr Class" title: "com::ptr Class" -ms.date: "01/16/2019" +description: "Learn more about: com::ptr Class" +ms.date: 01/16/2019 ms.topic: "reference" f1_keywords: ["msclr::com::ptr::ptr", "msclr::com::ptr::Attach", "msclr::com::ptr::CreateInstance", "msclr::com::ptr::Detach", "msclr::com::ptr::GetInterface", "msclr::com::ptr::QueryInterface", "msclr::com::ptr::Release", "msclr::com::ptr::operator=", "msclr::com::ptr::operator->", "msclr::com::ptr::operator!"] helpviewer_keywords: ["msclr::ptr class"] -ms.assetid: 0144d0e4-919c-45f9-a3f8-fbc9edba32bf --- # com::ptr Class @@ -173,7 +172,7 @@ int main() { |---------|-----------| |[`ptr::operator->`](#operator-arrow)|Member access operator, used to call methods on the owned COM object.| |[ptr::operator=](#operator-assign)|Attaches a COM object to a `com::ptr`.| -|[ptr::operator bool](#operator-bool)|Operator for using `com::ptr` in a conditional expression.| +|[ptr::operator bool](#operator-bool)|Operator for using `com::ptr` in a conditional expression.| |[ptr::operator!](#operator-logical-not)|Operator to determine if the owned COM object is invalid.| ## Requirements diff --git a/docs/dotnet/converting-projects-from-mixed-mode-to-pure-intermediate-language.md b/docs/dotnet/converting-projects-from-mixed-mode-to-pure-intermediate-language.md index e035e617f92..4f62d8f01c8 100644 --- a/docs/dotnet/converting-projects-from-mixed-mode-to-pure-intermediate-language.md +++ b/docs/dotnet/converting-projects-from-mixed-mode-to-pure-intermediate-language.md @@ -3,6 +3,7 @@ description: "Learn more about: Converting projects from mixed mode to pure inte title: "Converting projects from mixed mode to pure intermediate language" ms.date: 04/15/2021 helpviewer_keywords: ["intermediate language, mixed-mode applications", "mixed-mode applications", "mixed-mode applications, intermediate language", "projects [C++], converting to intermediate language"] +ms.topic: how-to --- # Converting projects from mixed mode to pure intermediate language diff --git a/docs/dotnet/cpp-stack-semantics-for-reference-types.md b/docs/dotnet/cpp-stack-semantics-for-reference-types.md index 83f5b0cccbd..279b7584eb2 100644 --- a/docs/dotnet/cpp-stack-semantics-for-reference-types.md +++ b/docs/dotnet/cpp-stack-semantics-for-reference-types.md @@ -29,7 +29,7 @@ A compiler-generated assignment operator will follow the usual standard C++ rule - Any non-static data member whose type is a value type will be shallow copied. -- Any non-static data member whose type is an instance of a reference type will invoke a call to the reference type’s copy constructor. +- Any non-static data member whose type is an instance of a reference type will invoke a call to the reference type's copy constructor. The compiler also provides a `%` unary operator to convert an instance of a reference type created using stack semantics to its underlying handle type. diff --git a/docs/dotnet/create-a-partially-trusted-application.md b/docs/dotnet/create-a-partially-trusted-application.md index 5e0a343494b..9d24f2ea685 100644 --- a/docs/dotnet/create-a-partially-trusted-application.md +++ b/docs/dotnet/create-a-partially-trusted-application.md @@ -5,6 +5,7 @@ ms.custom: "get-started-article" ms.date: "11/04/2016" helpviewer_keywords: ["partially trusted applications [C++]", "mixed assemblies [C++], partially trusted applications", "msvcm90[d].dll", "interoperability [C++], partially trusted applications", "interop [C++], partially trusted applications", "/clr compiler option [C++], partially trusted applications"] ms.assetid: 4760cd0c-4227-4f23-a7fb-d25b51bf246e +ms.topic: how-to --- # How to: Create a Partially Trusted Application by Removing Dependency on the CRT Library DLL diff --git a/docs/dotnet/data-access-using-adonet-cpp-cli.md b/docs/dotnet/data-access-using-adonet-cpp-cli.md index 73c3d4e6c82..69724de4d57 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/debug-class-cpp-cli.md b/docs/dotnet/debug-class-cpp-cli.md index f4f8da1750b..5230757827e 100644 --- a/docs/dotnet/debug-class-cpp-cli.md +++ b/docs/dotnet/debug-class-cpp-cli.md @@ -4,6 +4,7 @@ title: "Debug Class (C++/CLI)" ms.date: "11/04/2016" helpviewer_keywords: ["Trace class, Visual C++", ".NET Framework [C++], Debug class", "Debug class"] ms.assetid: 076bd528-1b6f-4e8a-a372-eb5849cf969a +ms.topic: how-to --- # Debug Class (C++/CLI) diff --git a/docs/dotnet/deque-stl-clr.md b/docs/dotnet/deque-stl-clr.md index b7e7be166a5..8a4ef045094 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)" -ms.date: "11/04/2016" +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 @@ -1568,7 +1567,7 @@ Position of element to access. ### Remarks -The member operator returns a referene to the element at position *pos*. You use it to access an element whose position you know. +The member operator returns a reference to the element at position *pos*. You use it to access an element whose position you know. ### Example 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 2109d30acee..359bef6d31e 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,22 @@ --- 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 +> [!IMPORTANT] +> C++/CLI is a technology designed during the early years of .NET (2003–2010) and remains supported for compatibility purposes. It's best suited for existing codebases, particularly those being brought forward from .NET Framework to .NET Core, or for maintaining large legacy systems that are unlikely to evolve beyond .NET Framework. +> +> While C++/CLI is reliable and robust, no new feature work is planned beyond what's necessary to ensure continued functionality. Developers should be aware that using C++/CLI pessimizes both C++ and .NET languages, as it's constrained by the language features and APIs available at the time of its design—that is, prior to ISO C++11 and .NET Core. C++/CLI was designed based on C++98, and its [ECMA standard](https://ecma-international.org/publications-and-standards/standards/ecma-372) hasn't been updated to keep up with newer C++ standards since C++11. While some features in C++11 were incorporated, many features from more recent standards, like C++20 and C++23, have no direct support in C++/CLI for compilation to managed code. For more information, see [C++20 Support Comes To C++/CLI](https://devblogs.microsoft.com/cppblog/cpp20-support-comes-to-cpp-cli/). +> +> For new projects, we recommend exploring modern third-party alternatives such as or , which offer more flexibility and better alignment with current language and runtime capabilities. + +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 +52,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/double-thunking-cpp.md b/docs/dotnet/double-thunking-cpp.md index f8b13c40ff2..345eb179e61 100644 --- a/docs/dotnet/double-thunking-cpp.md +++ b/docs/dotnet/double-thunking-cpp.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Double Thunking (C++)" title: "Double Thunking (C++)" -ms.date: "11/04/2016" +description: "Learn more about: Double Thunking (C++)" +ms.date: 11/04/2016 helpviewer_keywords: ["double thunks", "interop [C++], double thunking", "mixed assemblies [C++], double thunking", "/clr compiler option [C++], double thunking", "interoperability [C++], double thunking"] -ms.assetid: a85090b2-dc3c-498a-b40c-340db229dd6f +ms.topic: how-to --- # Double Thunking (C++) @@ -51,7 +51,7 @@ struct T { }; struct S { - virtual void /* __clrcall */ f(T t) {}; + virtual void /* __clrcall */ f(T t) {} } s; int main() { @@ -100,7 +100,7 @@ struct T { }; struct S { - virtual void /* __clrcall */ f(T t) {}; + virtual void /* __clrcall */ f(T t) {} } s; int main() { diff --git a/docs/dotnet/file-handling-and-i-o-cpp-cli.md b/docs/dotnet/file-handling-and-i-o-cpp-cli.md index dba79da1ef8..b19777bddd1 100644 --- a/docs/dotnet/file-handling-and-i-o-cpp-cli.md +++ b/docs/dotnet/file-handling-and-i-o-cpp-cli.md @@ -4,6 +4,7 @@ title: "File Handling and I-O (C++/CLI)" ms.date: "11/04/2016" helpviewer_keywords: [".NET Framework [C++], file handling", "files [C++], .NET Framework and", "I/O [C++], .NET Framework applications", ".NET Framework [C++], I/O", "files [C++], listing files", "directories [C++], listing files", "monitoring file system events", "FileSystemWatcher class, examples", "examples [C++], monitoring file system changes", "events [C++], monitoring", "file system events [C++]", "files [C++], binary", "binary files, reading in C++", "reading text files", "text files, reading", "files [C++], retrieving information about", "FileInfo class", "binary files, writing in C++", "files [C++], binary", "files [C++], text", "text files, writing in C++"] ms.assetid: 3296fd59-a83a-40d4-bd4a-6096cc13101b +ms.topic: how-to --- # File Handling and I/O (C++/CLI) diff --git a/docs/dotnet/for-each-in.md b/docs/dotnet/for-each-in.md index 0d805f1c485..51f9e9fe177 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 194249db4d6..a47621cd29a 100644 --- a/docs/dotnet/functional-stl-clr.md +++ b/docs/dotnet/functional-stl-clr.md @@ -1,15 +1,14 @@ --- -description: "Learn more about: functional (STL/CLR)" title: "functional (STL/CLR)" -ms.date: "11/04/2016" +description: "Learn more about: functional (STL/CLR)" +ms.date: 09/28/2022 ms.topic: "reference" f1_keywords: ["", "cliext::binary_delegate", "cliext::binary_delegate_noreturn", "cliext::binary_negate", "cliext::bind1st", "cliext::bind2nd", "cliext::binder1st", "cliext::binder2nd", "cliext::divides", "cliext::equal_to", "cliext::greater", "cliext::greater_equal", "cliext::less", "cliext::less_equal", "cliext::logical_and", "cliext::logical_not", "cliext::logical_or", "cliext::minus", "cliext::modulus", "cliext::multiplies", "cliext::negate", "cliext::not_equal_to", "cliext::not1", "cliext::not2", "cliext::plus", "cliext::unary_delegate", "cliext::unary_delegate_noreturn", "cliext::unary_negate"] helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "functional functions [STL/CLR]", "binary_delegate function [STL/CLR]", "binary_delegate_noreturn function [STL/CLR]", "binary_negate function [STL/CLR]", "bind1st function [STL/CLR]", "bind2nd function [STL/CLR]", "binder1st function [STL/CLR]", "binder2nd function [STL/CLR]", "divides function [STL/CLR]", "equal_to function [STL/CLR]", "greater function [STL/CLR]", "greater_equal function [STL/CLR]", "less function [STL/CLR]", "less_equal function [STL/CLR]", "logical_and function [STL/CLR]", "logical_not function [STL/CLR]", "logical_or function [STL/CLR]", "minus function [STL/CLR]", "modulus function [STL/CLR]", "multiplies function [STL/CLR]", "negate function [STL/CLR]", "not_equal_to function [STL/CLR]", "not1 function [STL/CLR]", "not2 function [STL/CLR]", "plus function [STL/CLR]", "unary_delegate function [STL/CLR]", "unary_delegate_noreturn function [STL/CLR]", "unary_negate function [STL/CLR]"] -ms.assetid: 88738b8c-5d37-4375-970e-a4442bf5efde --- -# functional (STL/CLR) +# `functional` (STL/CLR) -Include the STL/CLR header `` to define the a number of template classes and related template delegates and functions. +Include the STL/CLR header `` to define functional class templates and related template delegates and functions. ## Syntax @@ -21,51 +20,51 @@ Include the STL/CLR header `` to define the a number of templ **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Delegate|Description| -|--------------|-----------------| -|[binary_delegate (STL/CLR)](#binary_delegate)|Two-argument delegate.| -|[binary_delegate_noreturn (STL/CLR)](#binary_delegate_noreturn)|Two-argument delegate returning **`void`**.| -|[unary_delegate (STL/CLR)](#unary_delegate)|One-argument delegate.| -|[unary_delegate_noreturn (STL/CLR)](#unary_delegate_noreturn)|One-argument delegate returning **`void`**.| - -|Class|Description| -|-----------|-----------------| -|[binary_negate (STL/CLR)](#binary_negate)|Functor to negate a two-argument functor.| -|[binder1st (STL/CLR)](#binder1st)|Functor to bind first argument to a two-argument functor.| -|[binder2nd (STL/CLR)](#binder2nd)|Functor to bind second argument to a two-argument functor.| -|[divides (STL/CLR)](#divides)|Divide functor.| -|[equal_to (STL/CLR)](#equal_to)|Equal comparison functor.| -|[greater (STL/CLR)](#greater)|Greater comparison functor.| -|[greater_equal (STL/CLR)](#greater_equal)|Greater or equal comparison functor.| -|[less (STL/CLR)](#less)|Less comparison functor.| -|[less_equal (STL/CLR)](#less_equal)|Less or equal comparison functor.| -|[logical_and (STL/CLR)](#logical_and)|Logical AND functor.| -|[logical_not (STL/CLR)](#logical_not)|Logical NOT functor.| -|[logical_or (STL/CLR)](#logical_or)|Logical OR functor.| -|[minus (STL/CLR)](#minus)|Subtract functor.| -|[modulus (STL/CLR)](#modulus)|Modulus functor.| -|[multiplies (STL/CLR)](#multiplies)|Multiply functor.| -|[negate (STL/CLR)](#negate)|Functor to return its argument negated.| -|[not_equal_to (STL/CLR)](#not_equal_to)|Not equal comparison functor.| -|[plus (STL/CLR)](#plus)|Add functor.| -|[unary_negate (STL/CLR)](#unary_negate)|Functor to negate a one-argument functor.| - -|Function|Description| -|--------------|-----------------| -|[bind1st (STL/CLR)](#bind1st)|Generates a binder1st for an argument and functor.| -|[bind2nd (STL/CLR)](#bind2nd)|Generates a binder2nd for an argument and functor.| -|[not1 (STL/CLR)](#not1)|Generates a unary_negate for a functor.| -|[not2 (STL/CLR)](#not2)|Generates a binary_negate for a functor.| +| Delegate | Description | +|--|--| +| [`binary_delegate` (STL/CLR)](#binary_delegate) | Two-argument delegate. | +| [`binary_delegate_noreturn` (STL/CLR)](#binary_delegate_noreturn) | Two-argument delegate returning **`void`**. | +| [`unary_delegate` (STL/CLR)](#unary_delegate) | One-argument delegate. | +| [`unary_delegate_noreturn` (STL/CLR)](#unary_delegate_noreturn) | One-argument delegate returning **`void`**. | + +| Class | Description | +|--|--| +| [`binary_negate` (STL/CLR)](#binary_negate) | Functor to negate a two-argument functor. | +| [`binder1st` (STL/CLR)](#binder1st) | Functor to bind first argument to a two-argument functor. | +| [`binder2nd` (STL/CLR)](#binder2nd) | Functor to bind second argument to a two-argument functor. | +| [`divides` (STL/CLR)](#divides) | Divide functor. | +| [`equal_to` (STL/CLR)](#equal_to) | Equal comparison functor. | +| [`greater` (STL/CLR)](#greater) | Greater comparison functor. | +| [`greater_equal` (STL/CLR)](#greater_equal) | Greater or equal comparison functor. | +| [`less` (STL/CLR)](#less) | Less comparison functor. | +| [`less_equal` (STL/CLR)](#less_equal) | Less or equal comparison functor. | +| [`logical_and` (STL/CLR)](#logical_and) | Logical AND functor. | +| [`logical_not` (STL/CLR)](#logical_not) | Logical NOT functor. | +| [`logical_or` (STL/CLR)](#logical_or) | Logical OR functor. | +| [`minus` (STL/CLR)](#minus) | Subtract functor. | +| [`modulus` (STL/CLR)](#modulus) | Modulus functor. | +| [`multiplies` (STL/CLR)](#multiplies) | Multiply functor. | +| [`negate` (STL/CLR)](#negate) | Functor to return its argument negated. | +| [`not_equal_to` (STL/CLR)](#not_equal_to) | Not equal comparison functor. | +| [`plus` (STL/CLR)](#plus) | Add functor. | +| [`unary_negate` (STL/CLR)](#unary_negate) | Functor to negate a one-argument functor. | + +| Function | Description | +|--|--| +| [`bind1st` (STL/CLR)](#bind1st) | Generates a binder1st for an argument and functor. | +| [`bind2nd` (STL/CLR)](#bind2nd) | Generates a binder2nd for an argument and functor. | +| [`not1` (STL/CLR)](#not1) | Generates a unary_negate for a functor. | +| [`not2` (STL/CLR)](#not2) | Generates a binary_negate for a functor. | ## Members -## binary_delegate (STL/CLR) +## `binary_delegate` (STL/CLR) -The genereic class describes a two-argument delegate. You use it specify a delegate in terms of its argument and return types. +The generic class describes a two-argument delegate. You use it specify a delegate in terms of its argument and return types. ### Syntax @@ -78,20 +77,20 @@ generic +*`Arg1`*\ The type of the first argument. -*Arg2*
+*`Arg2`*\ The type of the second argument. -*Result*
+*`Result`*\ The return type. ### Remarks -The genereic delegate describes a two-argument function. +The generic delegate describes a two-argument function. -Note that for: +In these function templates: `binary_delegate Fun1;` @@ -103,7 +102,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate int Fun2(int, int);` -they are not the same type. +they aren't the same type. ### Example @@ -139,9 +138,9 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## binary_delegate_noreturn (STL/CLR) +## `binary_delegate_noreturn` (STL/CLR) -The genereic class describes a two-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument. +The generic class describes a two-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument. ### Syntax @@ -153,17 +152,17 @@ generic +*`Arg1`*\ The type of the first argument. -*Arg2*
+*`Arg2`*\ The type of the second argument. ### Remarks -The genereic delegate describes a two-argument function that returns **`void`**. +The generic delegate describes a two-argument function that returns **`void`**. -Note that for: +In these function templates: `binary_delegate_noreturn Fun1;` @@ -175,7 +174,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate void Fun2(int, int);` -they are not the same type. +they aren't the same type. ### Example @@ -209,7 +208,7 @@ compare(a, b) = True compare(b, a) = False ``` -## binary_negate (STL/CLR) +## `binary_negate` (STL/CLR) The template class describes a functor that, when called, returns the logical NOT of its stored two-argument functor. You use it specify a function object in terms of its stored functor. @@ -239,27 +238,27 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| -|stored_function_type|The type of the functor.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| +|`stored_function_type`|The type of the functor.| |Member|Description| |------------|-----------------| -|binary_negate|Constructs the functor.| +|`binary_negate`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -323,7 +322,7 @@ int main() 1 0 ``` -## bind1st (STL/CLR) +## `bind1st` (STL/CLR) Generates a `binder1st` for an argument and functor. @@ -338,23 +337,23 @@ template +*`Arg`*\ The type of the argument. -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. -*left*
+*`left`*\ The first argument to wrap. ### Remarks -The template function returns [binder1st (STL/CLR)](#binder1st)`(functor, left)`. You use it as a convenient way to wrap a two-argument functor and its first argument in a one-argument functor that calls it with a second argument. +The function template returns [`binder1st(functor, left)`](#binder1st). You use it as a convenient way to wrap a two-argument functor and its first argument in a one-argument functor that calls it with a second argument. ### Example @@ -404,7 +403,7 @@ int main() -1 0 ``` -## bind2nd (STL/CLR) +## `bind2nd` (STL/CLR) Generates a `binder2nd` for an argument and functor. @@ -419,23 +418,23 @@ template +*`Arg`*\ The type of the argument. -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. -*right*
+*`right`*\ The second argument to wrap. ### Remarks -The template function returns [binder2nd (STL/CLR)](#binder2nd)`(functor, right)`. You use it as a convenient way to wrap a two-argument functor and its second argument in a one-argument functor that calls it with a first argument. +The function template returns [`binder2nd(functor, right)`](#binder2nd). You use it as a convenient way to wrap a two-argument functor and its second argument in a one-argument functor that calls it with a first argument. ### Example @@ -485,7 +484,7 @@ int main() 0 -1 ``` -## binder1st (STL/CLR) +## `binder1st` (STL/CLR) The template class describes a one-argument functor that, when called, returns its stored two-argument functor called with its stored first argument and the supplied second argument. You use it specify a function object in terms of its stored functor. @@ -499,7 +498,7 @@ public: typedef Fun stored_function_type; typedef typename Fun::first_argument_type first_argument_type; typedef typename Fun::second_argument_type second_argument_type; - typedef typename Fun:result_type result_type; + typedef typename Fun::result_type result_type; typedef Microsoft::VisualC::StlClr::UnaryDelegate< second_argument_type, result_type> delegate_type; @@ -514,27 +513,27 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| -|stored_function_type|The type of the functor.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| +|`stored_function_type`|The type of the functor.| |Member|Description| |------------|-----------------| -|binder1st|Constructs the functor.| +|`binder1st`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -590,7 +589,7 @@ int main() -1 0 ``` -## binder2nd (STL/CLR) +## `binder2nd` (STL/CLR) The template class describes a one-argument functor that, when called, returns its stored two-argument functor called with the supplied first argument and its stored second argument. You use it specify a function object in terms of its stored functor. @@ -604,7 +603,7 @@ public: typedef Fun stored_function_type; typedef typename Fun::first_argument_type first_argument_type; typedef typename Fun::second_argument_type second_argument_type; - typedef typename Fun:result_type result_type; + typedef typename Fun::result_type result_type; typedef Microsoft::VisualC::StlClr::UnaryDelegate< first_argument_type, result_type> delegate_type; @@ -619,27 +618,27 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| -|stored_function_type|The type of the functor.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| +|`stored_function_type`|The type of the functor.| |Member|Description| |------------|-----------------| -|binder2nd|Constructs the functor.| +|`binder2nd`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -695,7 +694,7 @@ int main() 0 -1 ``` -## divides (STL/CLR) +## `divides` (STL/CLR) The template class describes a functor that, when called, returns the first argument divided by the second. You use it specify a function object in terms of its argument type. @@ -724,26 +723,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|divides|Constructs the functor.| +|`divides`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -796,7 +795,7 @@ int main() 2 3 ``` -## equal_to (STL/CLR) +## `equal_to` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is equal to the second. You use it specify a function object in terms of its argument type. @@ -825,26 +824,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|equal_to|Constructs the functor.| +|`equal_to`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^()|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^()`|Casts the functor to a delegate.| ### Remarks @@ -897,7 +896,7 @@ int main() 1 0 ``` -## greater (STL/CLR) +## `greater` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is greater than the second. You use it specify a function object in terms of its argument type. @@ -926,26 +925,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|greater|Constructs the functor.| +|`greater`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -998,7 +997,7 @@ int main() 1 0 ``` -## greater_equal (STL/CLR) +## `greater_equal` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is greater than or equal to the second. You use it specify a function object in terms of its argument type. @@ -1027,26 +1026,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|greater_equal|Constructs the functor.| +|`greater_equal`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1099,7 +1098,7 @@ int main() 1 0 ``` -## less (STL/CLR) +## `less` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is less than the second. You use it specify a function object in terms of its argument type. @@ -1128,26 +1127,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|less|Constructs the functor.| +|`less`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1200,7 +1199,7 @@ int main() 0 1 ``` -## less_equal (STL/CLR) +## `less_equal` (STL/CLR) The template class describes a functor that, when called, returns true only if the first argument is less than or equal to the second. You use it specify a function object in terms of its argument type. @@ -1229,26 +1228,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|less_equal|Constructs the functor.| +|`less_equal`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1301,7 +1300,7 @@ int main() 0 1 ``` -## logical_and (STL/CLR) +## `logical_and` (STL/CLR) The template class describes a functor that, when called, returns true only if both the first argument and the second test as true. You use it specify a function object in terms of its argument type. @@ -1330,26 +1329,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|logical_and|Constructs the functor.| +|`logical_and`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1402,7 +1401,7 @@ int main() 1 0 ``` -## logical_not (STL/CLR) +## `logical_not` (STL/CLR) The template class describes a functor that, when called, returns true only if either its argument tests as false. You use it specify a function object in terms of its argument type. @@ -1429,25 +1428,25 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|argument_type|The type of the functor argument.| -|delegate_type|The type of the generic delegate.| -|result_type|The type of the functor result.| +|`argument_type`|The type of the functor argument.| +|`delegate_type`|The type of the generic delegate.| +|`result_type`|The type of the functor result.| |Member|Description| |------------|-----------------| -|logical_not|Constructs the functor.| +|`logical_not`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1492,7 +1491,7 @@ int main() 0 1 ``` -## logical_or (STL/CLR) +## `logical_or` (STL/CLR) The template class describes a functor that, when called, returns true only if either the first argument or the second tests as true. You use it specify a function object in terms of its argument type. @@ -1521,26 +1520,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|logical_or|Constructs the functor.| +|`logical_or`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1593,7 +1592,7 @@ int main() 1 0 ``` -## minus (STL/CLR) +## `minus` (STL/CLR) The template class describes a functor that, when called, returns the first argument minus the second. You use it specify a function object in terms of its argument type. @@ -1622,26 +1621,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|minus|Constructs the functor.| +|`minus`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1694,7 +1693,7 @@ int main() 2 2 ``` -## modulus (STL/CLR) +## `modulus` (STL/CLR) The template class describes a functor that, when called, returns the first argument modulo the second. You use it specify a function object in terms of its argument type. @@ -1723,26 +1722,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|modulus|Constructs the functor.| +|`modulus`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1795,7 +1794,7 @@ int main() 1 0 ``` -## multiplies (STL/CLR) +## `multiplies` (STL/CLR) The template class describes a functor that, when called, returns the first argument times the second. You use it specify a function object in terms of its argument type. @@ -1824,26 +1823,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|multiplies|Constructs the functor.| +|`multiplies`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1896,7 +1895,7 @@ int main() 8 3 ``` -## negate (STL/CLR) +## `negate` (STL/CLR) The template class describes a functor that, when called, returns its argument negated. You use it specify a function object in terms of its argument type. @@ -1923,25 +1922,25 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|argument_type|The type of the functor argument.| -|delegate_type|The type of the generic delegate.| -|result_type|The type of the functor result.| +|`argument_type`|The type of the functor argument.| +|`delegate_type`|The type of the generic delegate.| +|`result_type`|The type of the functor result.| |Member|Description| |------------|-----------------| -|negate|Constructs the functor.| +|`negate`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -1986,9 +1985,9 @@ int main() -4 3 ``` -## not_equal_to (STL/CLR) +## `not_equal_to` (STL/CLR) -The template class describes a functor that, when called, returns true only if the first argument is not equal to the second. You use it specify a function object in terms of its argument type. +The template class describes a functor that, when called, returns true only if the first argument isn't equal to the second. You use it specify a function object in terms of its argument type. ### Syntax @@ -2015,30 +2014,30 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|not_equal_to|Constructs the functor.| +|`not_equal_to`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks -The template class describes a two-argument functor. It defines the member operator `operator()` so that, when the object is called as a function, it returns true only if the first argument is not equal to the second. +The template class describes a two-argument functor. It defines the member operator `operator()` so that, when the object is called as a function, it returns true only if the first argument isn't equal to the second. You can also pass the object as a function argument whose type is `delegate_type^` and it will be converted appropriately. @@ -2087,7 +2086,7 @@ int main() 0 1 ``` -## not1 (STL/CLR) +## `not1` (STL/CLR) Generates a `unary_negate` for a functor. @@ -2100,17 +2099,17 @@ template #### Template Parameters -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. ### Remarks -The template function returns [unary_negate (STL/CLR)](#unary_negate)`(functor)`. You use it as a convenient way to wrap a one-argument functor in a functor that delivers its logical NOT. +The function template returns [`unary_negate(functor)`](#unary_negate). You use it as a convenient way to wrap a one-argument functor in a functor that delivers its logical NOT. ### Example @@ -2159,7 +2158,7 @@ int main() 1 0 ``` -## not2 (STL/CLR) +## `not2` (STL/CLR) Generates a `binary_negate` for a functor. @@ -2172,17 +2171,17 @@ template #### Template Parameters -*Fun*
+*`Fun`*\ The type of the functor. #### Function Parameters -*functor*
+*`functor`*\ The functor to wrap. ### Remarks -The template function returns [binary_negate (STL/CLR)](#negate)`(functor)`. You use it as a convenient way to wrap a two-argument functor in a functor that delivers its logical NOT. +The function template returns [`binary_negate(functor)`](#negate). You use it as a convenient way to wrap a two-argument functor in a functor that delivers its logical NOT. ### Example @@ -2240,7 +2239,7 @@ int main() 1 0 ``` -## plus (STL/CLR) +## `plus` (STL/CLR) The template class describes a functor that, when called, returns the first argument plus the second. You use it specify a function object in terms of its argument type. @@ -2269,26 +2268,26 @@ public: #### Parameters -*Arg*
+*`Arg`*\ The type of the arguments and return value. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|delegate_type|The type of the generic delegate.| -|first_argument_type|The type of the functor first argument.| -|result_type|The type of the functor result.| -|second_argument_type|The type of the functor second argument.| +|`delegate_type`|The type of the generic delegate.| +|`first_argument_type`|The type of the functor first argument.| +|`result_type`|The type of the functor result.| +|`second_argument_type`|The type of the functor second argument.| |Member|Description| |------------|-----------------| -|plus|Constructs the functor.| +|`plus`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|operator delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`operator delegate_type^`|Casts the functor to a delegate.| ### Remarks @@ -2341,9 +2340,9 @@ int main() 6 4 ``` -## unary_delegate (STL/CLR) +## `unary_delegate` (STL/CLR) -The genereic class describes a one-argument delegate. You use it specify a delegate in terms of its argument and return types. +The generic class describes a one-argument delegate. You use it specify a delegate in terms of its argument and return types. ### Syntax @@ -2355,21 +2354,21 @@ generic +*`Arg`*\ The type of the argument. -*Result*
+*`Result`*\ The return type. ### Remarks -The genereic delegate describes a one-argument function. +The generic delegate describes a one-argument function. -Note that for: +In these function templates: -`unary_delegare Fun1;` +`unary_delegate Fun1;` -`unary_delegare Fun2;` +`unary_delegate Fun2;` the types `Fun1` and `Fun2` are synonyms, while for: @@ -2377,7 +2376,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate int Fun2(int);` -they are not the same type. +they aren't the same type. ### Example @@ -2407,9 +2406,9 @@ hash(L'a') = 5 hash(L'b') = 22 ``` -## unary_delegate_noreturn (STL/CLR) +## `unary_delegate_noreturn` (STL/CLR) -The genereic class describes a one-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument type. +The generic class describes a one-argument delegate that returns **`void`**. You use it specify a delegate in terms of its argument type. ### Syntax @@ -2420,18 +2419,18 @@ generic #### Parameters -*Arg*
+*`Arg`*\ The type of the argument. ### Remarks -The genereic delegate describes a one-argument function that returns **`void`**. +The generic delegate describes a one-argument function that returns **`void`**. -Note that for: +In these function templates: -`unary_delegare_noreturn Fun1;` +`unary_delegate_noreturn Fun1;` -`unary_delegare_noreturn Fun2;` +`unary_delegate_noreturn Fun2;` the types `Fun1` and `Fun2` are synonyms, while for: @@ -2439,7 +2438,7 @@ the types `Fun1` and `Fun2` are synonyms, while for: `delegate void Fun2(int);` -they are not the same type. +they aren't the same type. ### Example @@ -2470,7 +2469,7 @@ hash(a) = 5 hash(b) = 22 ``` -## unary_negate (STL/CLR) +## `unary_negate` (STL/CLR) The template class describes a functor that, when called, returns the logical NOT of its stored one-argument functor. You use it specify a function object in terms of its stored functor. @@ -2498,25 +2497,25 @@ public: #### Parameters -*Fun*
+*`Fun`*\ The type of the stored functor. ### Member Functions |Type Definition|Description| |---------------------|-----------------| -|argument_type|The type of the functor argument.| -|delegate_type|The type of the generic delegate.| -|result_type|The type of the functor result.| +|`argument_type`|The type of the functor argument.| +|`delegate_type`|The type of the generic delegate.| +|`result_type`|The type of the functor result.| |Member|Description| |------------|-----------------| -|unary_negate|Constructs the functor.| +|`unary_negate`|Constructs the functor.| |Operator|Description| |--------------|-----------------| -|operator()|Computes the desired function.| -|delegate_type^|Casts the functor to a delegate.| +|`operator()`|Computes the desired function.| +|`delegate_type^`|Casts the functor to a delegate.| ### Remarks diff --git a/docs/dotnet/hash-map-stl-clr.md b/docs/dotnet/hash-map-stl-clr.md index c824be59ad7..b7d55f25530 100644 --- a/docs/dotnet/hash-map-stl-clr.md +++ b/docs/dotnet/hash-map-stl-clr.md @@ -7,7 +7,7 @@ f1_keywords: ["cliext::hash_map", "cliext::hash_map::begin", "cliext::hash_map:: helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "hash_map class [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_map member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "mapped_type member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "operator member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: c3cfc69b-04c6-42ae-a30e-0eda953fe883 --- -# hash_map (STL/CLR) +# `hash_map` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_map` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +17,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as `Key` unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as `Key` unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as `Mapped` unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as `Mapped` unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -41,123 +41,123 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_map::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_map::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_map::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_map::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_map::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_map::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_map::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_map::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_map::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_map::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_map::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_map::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_map::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[hash_map::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_map::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_map::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_map::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_map::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_map::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_map::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_map::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_map::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_map::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_map::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_map::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_map::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_map::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_map::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_map::hash_map (STL/CLR)](#hash_map)|Constructs a container object.| -|[hash_map::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_map::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_map::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_map::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_map::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_map::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_map::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_map::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_map::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_map::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_map::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_map::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_map::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_map::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_map::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[hash_map::operator(STL/CLR)](#op)|Maps a key to its associated mapped value.| +| Type definition | Description | +|---|---| +| [`hash_map::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_map::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_map::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_map::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_map::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_map::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_map::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_map::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_map::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_map::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_map::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_map::key_type`](#key_type) | The type of an ordering key. | +| [`hash_map::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`hash_map::reference`](#reference) | The type of a reference to an element. | +| [`hash_map::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_map::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_map::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_map::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_map::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_map::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_map::clear`](#clear) | Removes all elements. | +| [`hash_map::count`](#count) | Counts elements matching a specified key. | +| [`hash_map::empty`](#empty) | Tests whether no elements are present. | +| [`hash_map::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_map::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_map::erase`](#erase) | Removes elements at specified positions. | +| [`hash_map::find`](#find) | Finds an element that matches a specified key. | +| [`hash_map::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_map::hash_map`](#hash_map) | Constructs a container object. | +| [`hash_map::insert`](#insert) | Adds elements. | +| [`hash_map::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_map::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_map::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_map::make_value`](#make_value) | Constructs a value object. | +| [`hash_map::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_map::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_map::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_map::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_map::size`](#size) | Counts the number of elements. | +| [`hash_map::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_map::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_map::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_map::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_map::operator=`](#op_as) | Replaces the controlled sequence. | +| [`hash_map::operator[]`](#op) | Maps a key to its associated mapped value. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -||Maintain group of {key, value} pairs.| -|IHash|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| | Maintain group of {key, value} pairs. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](./hash-set-stl-clr.md#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp()`](./hash-set-stl-clr.md#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_multimap (STL/CLR)](../dotnet/hash-multimap-stl-clr.md), an object of template class `hash_map` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [`hash_multimap`](../dotnet/hash-multimap-stl-clr.md), an object of template class `hash_map` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](./hash-set-stl-clr.md#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](./hash-set-stl-clr.md#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](./hash-set-stl-clr.md#max_load_factor) and [hash_set::rehash (STL/CLR)](./hash-set-stl-clr.md#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](./hash-set-stl-clr.md#max_load_factor) and [`hash_set::rehash`](./hash-set-stl-clr.md#rehash). -A hash_map supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_map::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_map iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_map` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_map` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_map element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_map` element directly given its numerical position; that requires a random-access iterator. -A hash_map iterator stores a handle to its associated hash_map node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_map iterator remains valid so long as its associated hash_map node is associated with some hash_map. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_map` iterator stores a handle to its associated `hash_map` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_map` iterator remains valid so long as its associated `hash_map` node is associated with some `hash_map`. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it's not equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles doesn't* destroy its elements. ## Members -## hash_map::begin (STL/CLR) +## `hash_map::begin` Designates the beginning of the controlled sequence. @@ -208,7 +208,7 @@ int main() *++begin() = [b 2] ``` -## hash_map::bucket_count (STL/CLR) +## `hash_map::bucket_count` Counts the number of buckets. @@ -220,7 +220,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -282,7 +282,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::clear (STL/CLR) +## `hash_map::clear` Removes all elements. @@ -294,7 +294,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_map::erase (STL/CLR)](#erase)`(` [hash_map::begin (STL/CLR)](#begin)`(),` [hash_map::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -340,7 +340,7 @@ size() = 0 size() = 0 ``` -## hash_map::const_iterator (STL/CLR) +## `hash_map::const_iterator` The type of a constant iterator for the controlled sequence. @@ -382,7 +382,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::const_reference (STL/CLR) +## `hash_map::const_reference` The type of a constant reference to an element. @@ -427,9 +427,9 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::const_reverse_iterator (STL/CLR) +## `hash_map::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -469,7 +469,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_map::count (STL/CLR) +## `hash_map::count` Finds the number of elements matching a specified key. @@ -481,12 +481,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -522,7 +522,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_map::difference_type (STL/CLR) +## `hash_map::difference_type` The types of a signed distance between two elements. @@ -577,7 +577,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_map::empty (STL/CLR) +## `hash_map::empty` Tests whether no elements are present. @@ -589,7 +589,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_map::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_map is empty. +The member function returns `true` for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_map` is empty. ### Example @@ -629,7 +629,7 @@ size() = 0 empty() = True ``` -## hash_map::end (STL/CLR) +## `hash_map::end` Designates the end of the controlled sequence. @@ -641,7 +641,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -682,7 +682,7 @@ int main() *--end() = [c 3] ``` -## hash_map::equal_range (STL/CLR) +## `hash_map::equal_range` Finds range that matches a specified key. @@ -694,7 +694,7 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks @@ -743,7 +743,7 @@ equal_range(L'x') empty = True [b 2] ``` -## hash_map::erase (STL/CLR) +## `hash_map::erase` Removes elements at specified positions. @@ -757,25 +757,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_map::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -836,7 +836,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## hash_map::find (STL/CLR) +## `hash_map::find` Finds an element that matches a specified key. @@ -848,12 +848,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_map::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -895,7 +895,7 @@ find b = [b 2] find C = False ``` -## hash_map::generic_container (STL/CLR) +## `hash_map::generic_container` The type of the generic interface for the container. @@ -959,7 +959,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## hash_map::generic_iterator (STL/CLR) +## `hash_map::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -1016,7 +1016,7 @@ int main() [a 1] ``` -## hash_map::generic_reverse_iterator (STL/CLR) +## `hash_map::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1072,7 +1072,7 @@ int main() [c 3] ``` -## hash_map::generic_value (STL/CLR) +## `hash_map::generic_value` The type of an element for use with the generic interface for the container. @@ -1126,7 +1126,7 @@ int main() [a 1] ``` -## hash_map::hash_delegate (STL/CLR) +## `hash_map::hash_delegate` Finds an element that matches a specified key. @@ -1164,7 +1164,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_map::hash_map (STL/CLR) +## `hash_map::hash_map` Constructs a container object. @@ -1193,19 +1193,19 @@ hash_map(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1220,25 +1220,25 @@ The constructor: `explicit hash_map(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_map(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_map(hash_map% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_map object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_map` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_map(hash_map^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_map object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_map` object *`right`*, with the default ordering predicate and hash function. The constructor: @@ -1250,31 +1250,31 @@ The constructor: `template hash_map(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_map(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_map(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_map(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_map(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1407,7 +1407,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## hash_map::hasher (STL/CLR) +## `hash_map::hasher` The hashing delegate for a key. @@ -1446,7 +1446,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_map::insert (STL/CLR) +## `hash_map::insert` Adds elements. @@ -1462,19 +1462,19 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks @@ -1483,13 +1483,13 @@ Each of the member functions inserts a sequence specified by the remaining opera The first member function endeavors to insert an element with value `val`, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1566,7 +1566,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [c 3] [x 24] [y 25] ``` -## hash_map::iterator (STL/CLR) +## `hash_map::iterator` The type of an iterator for the controlled sequence. @@ -1608,7 +1608,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::key_comp (STL/CLR) +## `hash_map::key_comp` Copies the ordering delegate for two keys. @@ -1667,7 +1667,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_map::key_compare (STL/CLR) +## `hash_map::key_compare` The ordering delegate for two keys. @@ -1727,7 +1727,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_map::key_type (STL/CLR) +## `hash_map::key_type` The type of an ordering key. @@ -1739,7 +1739,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1772,7 +1772,7 @@ int main() a b c ``` -## hash_map::load_factor (STL/CLR) +## `hash_map::load_factor` Counts the average elements per bucket. @@ -1784,7 +1784,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_map::size (STL/CLR)](#size)`() /` [hash_map::bucket_count (STL/CLR)](#bucket_count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / bucket_count()`. You use it to determine the average bucket size. ### Example @@ -1846,7 +1846,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::lower_bound (STL/CLR) +## `hash_map::lower_bound` Finds beginning of range that matches a specified key. @@ -1858,12 +1858,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1905,7 +1905,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## hash_map::make_value (STL/CLR) +## `hash_map::make_value` Constructs a value object. @@ -1917,15 +1917,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1954,7 +1954,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::mapped_type (STL/CLR) +## `hash_map::mapped_type` The type of a mapped value associated with each key. @@ -1999,7 +1999,7 @@ int main() 1 2 3 ``` -## hash_map::max_load_factor (STL/CLR) +## `hash_map::max_load_factor` Gets or sets the maximum elements per bucket. @@ -2012,14 +2012,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -2081,7 +2081,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::operator= (STL/CLR) +## `hash_map::operator=` Replaces the controlled sequence. @@ -2093,12 +2093,12 @@ hash_map% operator=(hash_map% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2136,7 +2136,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::operator(STL/CLR) +## `hash_map::operator[]` Maps a key to its associated mapped value. @@ -2148,12 +2148,12 @@ mapped_type operator[](key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member functions endeavors to find an element with equivalent ordering to *key*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. +The member functions endeavors to find an element with equivalent ordering to *`key`*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. ### Example @@ -2203,7 +2203,7 @@ c1[b] = 2 [a 1] [A 10] [b 2] [c 13] ``` -## hash_map::rbegin (STL/CLR) +## `hash_map::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2254,7 +2254,7 @@ int main() *++rbegin() = [b 2] ``` -## hash_map::reference (STL/CLR) +## `hash_map::reference` The type of a reference to an element. @@ -2299,7 +2299,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::rehash (STL/CLR) +## `hash_map::rehash` Rebuilds the hash table. @@ -2311,7 +2311,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_map::load_factor (STL/CLR)](#load_factor)`() <=` [hash_map::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2373,7 +2373,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_map::rend (STL/CLR) +## `hash_map::rend` Designates the end of the reversed controlled sequence. @@ -2426,7 +2426,7 @@ int main() *--rend() = [a 1] ``` -## hash_map::reverse_iterator (STL/CLR) +## `hash_map::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2468,7 +2468,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_map::size (STL/CLR) +## `hash_map::size` Counts the number of elements. @@ -2480,7 +2480,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_map::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`hash_map::empty`](#empty). ### Example @@ -2520,9 +2520,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_map::size_type (STL/CLR) +## `hash_map::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2568,7 +2568,7 @@ int main() end()-begin() = 3 ``` -## hash_map::swap (STL/CLR) +## `hash_map::swap` Swaps the contents of two containers. @@ -2580,12 +2580,12 @@ void swap(hash_map% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2636,7 +2636,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::to_array (STL/CLR) +## `hash_map::to_array` Copies the controlled sequence to a new array. @@ -2686,7 +2686,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_map::upper_bound (STL/CLR) +## `hash_map::upper_bound` Finds end of range that matches a specified key. @@ -2698,12 +2698,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2745,7 +2745,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## hash_map::value_comp (STL/CLR) +## `hash_map::value_comp` Copies the ordering delegate for two element values. @@ -2792,7 +2792,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_map::value_compare (STL/CLR) +## `hash_map::value_compare` The ordering delegate for two element values. @@ -2840,7 +2840,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_map::value_type (STL/CLR) +## `hash_map::value_type` The type of an element. diff --git a/docs/dotnet/hash-multimap-stl-clr.md b/docs/dotnet/hash-multimap-stl-clr.md index 54cb5964bce..59ec4336e52 100644 --- a/docs/dotnet/hash-multimap-stl-clr.md +++ b/docs/dotnet/hash-multimap-stl-clr.md @@ -7,7 +7,7 @@ f1_keywords: ["cliext::hash_multimap", "cliext::hash_multimap::begin", "cliext:: helpviewer_keywords: ["hash_multimap class [STL/CLR]", " header [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_multimap member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "mapped_type member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: cd78687b-8a05-48e0-9d22-8b8194ae3b0b --- -# hash_multimap (STL/CLR) +# `hash_multimap` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_multimap` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +17,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as *Key* unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as *Mapped* unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as *`Mapped`* unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -40,121 +40,121 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_multimap::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_multimap::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_multimap::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_multimap::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_multimap::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_multimap::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_multimap::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_multimap::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_multimap::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_multimap::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_multimap::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_multimap::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_multimap::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[hash_multimap::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_multimap::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_multimap::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_multimap::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_multimap::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_multimap::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_multimap::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_multimap::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_multimap::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_multimap::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_multimap::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_multimap::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_multimap::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_multimap::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_multimap::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_multimap::hash_multimap (STL/CLR)](#hash_multimap)|Constructs a container object.| -|[hash_multimap::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_multimap::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_multimap::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_multimap::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_multimap::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_multimap::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_multimap::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_multimap::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_multimap::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_multimap::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_multimap::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_multimap::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_multimap::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_multimap::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_multimap::operator= (STL/CLR)](#op)|Replaces the controlled sequence.| +| Type definition | Description | +|---|---| +| [`hash_multimap::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_multimap::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_multimap::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_multimap::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_multimap::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_multimap::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_multimap::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_multimap::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_multimap::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_multimap::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_multimap::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_multimap::key_type`](#key_type) | The type of an ordering key. | +| [`hash_multimap::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`hash_multimap::reference`](#reference) | The type of a reference to an element. | +| [`hash_multimap::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_multimap::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_multimap::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_multimap::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_multimap::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_multimap::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_multimap::clear`](#clear) | Removes all elements. | +| [`hash_multimap::count`](#count) | Counts elements matching a specified key. | +| [`hash_multimap::empty`](#empty) | Tests whether no elements are present. | +| [`hash_multimap::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_multimap::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_multimap::erase`](#erase) | Removes elements at specified positions. | +| [`hash_multimap::find`](#find) | Finds an element that matches a specified key. | +| [`hash_multimap::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_multimap::hash_multimap`](#hash_multimap) | Constructs a container object. | +| [`hash_multimap::insert`](#insert) | Adds elements. | +| [`hash_multimap::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_multimap::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_multimap::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_multimap::make_value`](#make_value) | Constructs a value object. | +| [`hash_multimap::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_multimap::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_multimap::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_multimap::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_multimap::size`](#size) | Counts the number of elements. | +| [`hash_multimap::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_multimap::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_multimap::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_multimap::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_multimap::operator=`](#op) | Replaces the controlled sequence. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|IHash\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](./hash-set-stl-clr.md#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp`](./hash-set-stl-clr.md#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_map (STL/CLR)](../dotnet/hash-map-stl-clr.md), an object of template class `hash_multimap` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [`hash_map` (STL/CLR)](../dotnet/hash-map-stl-clr.md), an object of template class `hash_multimap` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](./hash-set-stl-clr.md#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](./hash-set-stl-clr.md#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](./hash-set-stl-clr.md#max_load_factor) and [hash_set::rehash (STL/CLR)](./hash-set-stl-clr.md#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](./hash-set-stl-clr.md#max_load_factor) and [`hash_set::rehash`](./hash-set-stl-clr.md#rehash). -A hash_multimap supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_multimap::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_multimap iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_multimap` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_multimap` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_multimap element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_multimap` element directly given its numerical position. That requires a random-access iterator. -A hash_multimap iterator stores a handle to its associated hash_multimap node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_multimap iterator remains valid so long as its associated hash_multimap node is associated with some hash_multimap. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_multimap` iterator stores a handle to its associated `hash_multimap` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_multimap` iterator remains valid so long as its associated `hash_multimap` node is associated with some `hash_multimap`. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## hash_multimap::begin (STL/CLR) +## hash_multimap::begin Designates the beginning of the controlled sequence. @@ -205,7 +205,7 @@ int main() *++begin() = [b 2] ``` -## hash_multimap::bucket_count (STL/CLR) +## hash_multimap::bucket_count Counts the number of buckets. @@ -217,7 +217,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -279,7 +279,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::clear (STL/CLR) +## hash_multimap::clear Removes all elements. @@ -291,7 +291,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_multimap::erase (STL/CLR)](#erase)`(` [hash_multimap::begin (STL/CLR)](#begin)`(),` [hash_multimap::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -337,7 +337,7 @@ size() = 0 size() = 0 ``` -## hash_multimap::const_iterator (STL/CLR) +## hash_multimap::const_iterator The type of a constant iterator for the controlled sequence. @@ -379,7 +379,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::const_reference (STL/CLR) +## hash_multimap::const_reference The type of a constant reference to an element. @@ -424,9 +424,9 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::const_reverse_iterator (STL/CLR) +## hash_multimap::const_reverse_iterator -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -466,7 +466,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_multimap::count (STL/CLR) +## hash_multimap::count Finds the number of elements matching a specified key. @@ -478,12 +478,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -519,7 +519,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_multimap::difference_type (STL/CLR) +## hash_multimap::difference_type The types of a signed distance between two elements. @@ -574,7 +574,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_multimap::empty (STL/CLR) +## hash_multimap::empty Tests whether no elements are present. @@ -586,7 +586,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_multimap::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_multimap is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_multimap` is empty. ### Example @@ -626,7 +626,7 @@ size() = 0 empty() = True ``` -## hash_multimap::end (STL/CLR) +## hash_multimap::end Designates the end of the controlled sequence. @@ -638,7 +638,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -679,7 +679,7 @@ int main() *--end() = [c 3] ``` -## hash_multimap::equal_range (STL/CLR) +## hash_multimap::equal_range Finds range that matches a specified key. @@ -691,12 +691,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [hash_multimap::lower_bound (STL/CLR)](#lower_bound)`(key),` [hash_multimap::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -740,7 +740,7 @@ equal_range(L'x') empty = True [b 2] ``` -## hash_multimap::erase (STL/CLR) +## hash_multimap::erase Removes elements at specified positions. @@ -754,25 +754,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_multimap::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the half-open range `[first, last)`, and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -833,7 +833,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## hash_multimap::find (STL/CLR) +## `hash_multimap::find` Finds an element that matches a specified key. @@ -845,12 +845,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_multimap::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`hash_multimap::end`](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -892,7 +892,7 @@ find b = [b 2] find C = False ``` -## hash_multimap::generic_container (STL/CLR) +## `hash_multimap::generic_container` The type of the generic interface for the container. @@ -956,7 +956,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## hash_multimap::generic_iterator (STL/CLR) +## `hash_multimap::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -1013,7 +1013,7 @@ int main() [a 1] ``` -## hash_multimap::generic_reverse_iterator (STL/CLR) +## `hash_multimap::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1069,7 +1069,7 @@ int main() [c 3] ``` -## hash_multimap::generic_value (STL/CLR) +## `hash_multimap::generic_value` The type of an element for use with the generic interface for the container. @@ -1123,7 +1123,7 @@ int main() [a 1] ``` -## hash_multimap::hash_delegate (STL/CLR) +## `hash_multimap::hash_delegate` Finds an element that matches a specified key. @@ -1161,7 +1161,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multimap::hash_multimap (STL/CLR) +## `hash_multimap::hash_multimap` Constructs a container object. @@ -1190,19 +1190,19 @@ hash_multimap(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1217,61 +1217,61 @@ The constructor: `explicit hash_multimap(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_multimap(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_multimap(hash_multimap% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multimap object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multimap` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_multimap(hash_multimap^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multimap object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multimap` object *`right`*, with the default ordering predicate and hash function. The constructor: `template hash_multimap(InIter first, InIter last);` -initializes the controlled sequence with the sequence [`first`, `last`), with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence `[first, last)`, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the default ordering predicate and hash function. The constructor: `template hash_multimap(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence `[first, last)`, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_multimap(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence `[first, last)`, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_multimap(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_multimap(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_multimap(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1404,7 +1404,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## hash_multimap::hasher (STL/CLR) +## `hash_multimap::hasher` The hashing delegate for a key. @@ -1443,7 +1443,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multimap::insert (STL/CLR) +## `hash_multimap::insert` Adds elements. @@ -1459,34 +1459,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. -The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. +The third member function inserts the sequence `[first, last)`. You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1561,7 +1561,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [b 2] [c 3] [x 24] [y 25] ``` -## hash_multimap::iterator (STL/CLR) +## `hash_multimap::iterator` The type of an iterator for the controlled sequence. @@ -1603,7 +1603,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::key_comp (STL/CLR) +## `hash_multimap::key_comp` Copies the ordering delegate for two keys. @@ -1662,7 +1662,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multimap::key_compare (STL/CLR) +## `hash_multimap::key_compare` The ordering delegate for two keys. @@ -1722,7 +1722,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multimap::key_type (STL/CLR) +## `hash_multimap::key_type` The type of an ordering key. @@ -1734,7 +1734,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1767,7 +1767,7 @@ int main() a b c ``` -## hash_multimap::load_factor (STL/CLR) +## `hash_multimap::load_factor` Counts the average elements per bucket. @@ -1779,7 +1779,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_multimap::size (STL/CLR)](#size)`() /` [hash_multimap::bucket_count (STL/CLR)](#bucket_count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / bucket_count()`. You use it to determine the average bucket size. ### Example @@ -1841,7 +1841,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::lower_bound (STL/CLR) +## `hash_multimap::lower_bound` Finds beginning of range that matches a specified key. @@ -1853,12 +1853,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`hash_multimap::end`](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1900,7 +1900,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## hash_multimap::make_value (STL/CLR) +## `hash_multimap::make_value` Constructs a value object. @@ -1912,15 +1912,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1949,7 +1949,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::mapped_type (STL/CLR) +## `hash_multimap::mapped_type` The type of a mapped value associated with each key. @@ -1961,7 +1961,7 @@ typedef Mapped mapped_type; ### Remarks -The type is a synonym for the template parameter *Mapped*. +The type is a synonym for the template parameter *`Mapped`*. ### Example @@ -1994,7 +1994,7 @@ int main() 1 2 3 ``` -## hash_multimap::max_load_factor (STL/CLR) +## `hash_multimap::max_load_factor` Gets or sets the maximum elements per bucket. @@ -2007,14 +2007,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -2076,7 +2076,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::operator= (STL/CLR) +## `hash_multimap::operator=` Replaces the controlled sequence. @@ -2088,12 +2088,12 @@ hash_multimap% operator=(hash_multimap% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2131,7 +2131,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::rbegin (STL/CLR) +## `hash_multimap::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2182,7 +2182,7 @@ int main() *++rbegin() = [b 2] ``` -## hash_multimap::reference (STL/CLR) +## `hash_multimap::reference` The type of a reference to an element. @@ -2227,7 +2227,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::rehash (STL/CLR) +## `hash_multimap::rehash` Rebuilds the hash table. @@ -2239,7 +2239,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_multimap::load_factor (STL/CLR)](#load_factor)`() <=` [hash_multimap::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2301,7 +2301,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multimap::rend (STL/CLR) +## `hash_multimap::rend` Designates the end of the reversed controlled sequence. @@ -2354,7 +2354,7 @@ int main() *--rend() = [a 1] ``` -## hash_multimap::reverse_iterator (STL/CLR) +## `hash_multimap::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2396,7 +2396,7 @@ int main() [c 3] [b 2] [a 1] ``` -## hash_multimap::size (STL/CLR) +## `hash_multimap::size` Counts the number of elements. @@ -2408,7 +2408,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_multimap::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`hash_multimap::empty`](#empty)`()`. ### Example @@ -2448,9 +2448,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_multimap::size_type (STL/CLR) +## `hash_multimap::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2496,7 +2496,7 @@ int main() end()-begin() = 3 ``` -## hash_multimap::swap (STL/CLR) +## `hash_multimap::swap` Swaps the contents of two containers. @@ -2508,12 +2508,12 @@ void swap(hash_multimap% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2564,7 +2564,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::to_array (STL/CLR) +## `hash_multimap::to_array` Copies the controlled sequence to a new array. @@ -2614,7 +2614,7 @@ int main() [a 1] [b 2] [c 3] ``` -## hash_multimap::upper_bound (STL/CLR) +## `hash_multimap::upper_bound` Finds end of range that matches a specified key. @@ -2626,12 +2626,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`hash_multimap::end`](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2673,7 +2673,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## hash_multimap::value_comp (STL/CLR) +## `hash_multimap::value_comp` Copies the ordering delegate for two element values. @@ -2720,7 +2720,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_multimap::value_compare (STL/CLR) +## `hash_multimap::value_compare` The ordering delegate for two element values. @@ -2768,7 +2768,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## hash_multimap::value_type (STL/CLR) +## `hash_multimap::value_type` The type of an element. diff --git a/docs/dotnet/hash-multiset-stl-clr.md b/docs/dotnet/hash-multiset-stl-clr.md index c14ded18c11..0c6b7b53d54 100644 --- a/docs/dotnet/hash-multiset-stl-clr.md +++ b/docs/dotnet/hash-multiset-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::hash_multiset", "cliext::hash_multiset::begin", "cliext:: helpviewer_keywords: [" header [STL/CLR]", "hash_multiset class [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_multiset member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: 8462bd21-6829-4dd3-ac81-c42d6fdf92f0 --- -# hash_multiset (STL/CLR) +# `hash_multiset` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_multiset` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. The value of each element is used as a key, for ordering the sequence. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,117 +31,117 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_multiset::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_multiset::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_multiset::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_multiset::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_multiset::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_multiset::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_multiset::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_multiset::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_multiset::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_multiset::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_multiset::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_multiset::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_multiset::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_multiset::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_multiset::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_multiset::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_multiset::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_multiset::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_multiset::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_multiset::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_multiset::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_multiset::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_multiset::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_multiset::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_multiset::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_multiset::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_multiset::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_multiset::hash_multiset (STL/CLR)](#hash_multiset)|Constructs a container object.| -|[hash_multiset::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_multiset::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_multiset::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_multiset::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_multiset::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_multiset::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_multiset::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_multiset::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_multiset::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_multiset::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_multiset::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_multiset::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_multiset::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_multiset::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_multiset::operator= (STL/CLR)](#op)|Replaces the controlled sequence.| +| Type definition | Description | +|---|---| +| [`hash_multiset::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_multiset::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_multiset::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_multiset::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_multiset::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_multiset::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_multiset::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_multiset::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_multiset::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_multiset::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_multiset::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_multiset::key_type`](#key_type) | The type of an ordering key. | +| [`hash_multiset::reference`](#reference) | The type of a reference to an element. | +| [`hash_multiset::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_multiset::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_multiset::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_multiset::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_multiset::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_multiset::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_multiset::clear`](#clear) | Removes all elements. | +| [`hash_multiset::count`](#count) | Counts elements matching a specified key. | +| [`hash_multiset::empty`](#empty) | Tests whether no elements are present. | +| [`hash_multiset::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_multiset::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_multiset::erase`](#erase) | Removes elements at specified positions. | +| [`hash_multiset::find`](#find) | Finds an element that matches a specified key. | +| [`hash_multiset::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_multiset::hash_multiset`](#hash_multiset) | Constructs a container object. | +| [`hash_multiset::insert`](#insert) | Adds elements. | +| [`hash_multiset::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_multiset::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_multiset::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_multiset::make_value`](#make_value) | Constructs a value object. | +| [`hash_multiset::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_multiset::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_multiset::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_multiset::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_multiset::size`](#size) | Counts the number of elements. | +| [`hash_multiset::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_multiset::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_multiset::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_multiset::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_multiset::operator=`](#op) | Replaces the controlled sequence. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|IHash\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](./hash-set-stl-clr.md#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](./hash-set-stl-clr.md#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp`](./hash-set-stl-clr.md#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](./hash-set-stl-clr.md#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_set (STL/CLR)](../dotnet/hash-set-stl-clr.md), an object of template class `hash_multiset` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [`hash_set` (STL/CLR)](../dotnet/hash-set-stl-clr.md), an object of template class `hash_multiset` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](./hash-set-stl-clr.md#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](./hash-set-stl-clr.md#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](./hash-set-stl-clr.md#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](./hash-set-stl-clr.md#max_load_factor) and [hash_set::rehash (STL/CLR)](./hash-set-stl-clr.md#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](./hash-set-stl-clr.md#max_load_factor) and [`hash_set::rehash`](./hash-set-stl-clr.md#rehash). -A hash_multiset supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_multiset::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_multiset iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_multiset` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`hash_multiset::end`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_multiset` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_multiset element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_multiset` element directly given its numerical position. That requires a random-access iterator. -A hash_multiset iterator stores a handle to its associated hash_multiset node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_multiset iterator remains valid so long as its associated hash_multiset node is associated with some hash_multiset. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_multiset` iterator stores a handle to its associated `hash_multiset` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_multiset` iterator remains valid so long as its associated `hash_multiset` node is associated with some `hash_multiset`. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## hash_multiset::begin (STL/CLR) +## `hash_multiset::begin` Designates the beginning of the controlled sequence. @@ -189,7 +189,7 @@ a b c *++begin() = b ``` -## hash_multiset::bucket_count (STL/CLR) +## `hash_multiset::bucket_count` Counts the number of buckets. @@ -201,7 +201,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -263,7 +263,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::clear (STL/CLR) +## `hash_multiset::clear` Removes all elements. @@ -275,7 +275,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_multiset::erase (STL/CLR)](#erase)`(` [hash_multiset::begin (STL/CLR)](#begin)`(),` [hash_multiset::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -321,7 +321,7 @@ a b size() = 0 ``` -## hash_multiset::const_iterator (STL/CLR) +## `hash_multiset::const_iterator` The type of a constant iterator for the controlled sequence. @@ -363,7 +363,7 @@ int main() a b c ``` -## hash_multiset::const_reference (STL/CLR) +## `hash_multiset::const_reference` The type of a constant reference to an element. @@ -408,9 +408,9 @@ int main() a b c ``` -## hash_multiset::const_reverse_iterator (STL/CLR) +## `hash_multiset::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -450,7 +450,7 @@ int main() c b a ``` -## hash_multiset::count (STL/CLR) +## `hash_multiset::count` Finds the number of elements matching a specified key. @@ -462,12 +462,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -503,7 +503,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_multiset::difference_type (STL/CLR) +## `hash_multiset::difference_type` The types of a signed distance between two elements. @@ -558,7 +558,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_multiset::empty (STL/CLR) +## `hash_multiset::empty` Tests whether no elements are present. @@ -570,7 +570,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_multiset::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_multiset is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_multiset` is empty. ### Example @@ -610,7 +610,7 @@ size() = 0 empty() = True ``` -## hash_multiset::end (STL/CLR) +## `hash_multiset::end` Designates the end of the controlled sequence. @@ -622,7 +622,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -659,7 +659,7 @@ a b c *--end() = c ``` -## hash_multiset::equal_range (STL/CLR) +## `hash_multiset::equal_range` Finds range that matches a specified key. @@ -671,12 +671,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [hash_multiset::lower_bound (STL/CLR)](#lower_bound)`(key),` [hash_multiset::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -719,7 +719,7 @@ equal_range(L'x') empty = True b ``` -## hash_multiset::erase (STL/CLR) +## `hash_multiset::erase` Removes elements at specified positions. @@ -733,25 +733,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_multiset::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -803,7 +803,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## hash_multiset::find (STL/CLR) +## `hash_multiset::find` Finds an element that matches a specified key. @@ -815,12 +815,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_multiset::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -859,7 +859,7 @@ find b = b find C = False ``` -## hash_multiset::generic_container (STL/CLR) +## `hash_multiset::generic_container` The type of the generic interface for the container. @@ -923,7 +923,7 @@ a b c d a b c d e ``` -## hash_multiset::generic_iterator (STL/CLR) +## `hash_multiset::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -979,7 +979,7 @@ a b c a ``` -## hash_multiset::generic_reverse_iterator (STL/CLR) +## `hash_multiset::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1035,7 +1035,7 @@ a b c c ``` -## hash_multiset::generic_value (STL/CLR) +## `hash_multiset::generic_value` The type of an element for use with the generic interface for the container. @@ -1089,7 +1089,7 @@ a b c a ``` -## hash_multiset::hash_delegate (STL/CLR) +## `hash_multiset::hash_delegate` Finds an element that matches a specified key. @@ -1127,7 +1127,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multiset::hash_multiset (STL/CLR) +## `hash_multiset::hash_multiset` Constructs a container object. @@ -1156,19 +1156,19 @@ hash_multiset(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1183,25 +1183,25 @@ The constructor: `explicit hash_multiset(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_multiset(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_multiset(hash_multiset% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multiset object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multiset` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_multiset(hash_multiset^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_multiset object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_multiset` object *`right`*, with the default ordering predicate and hash function. The constructor: @@ -1213,31 +1213,31 @@ The constructor: `template hash_multiset(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_multiset(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_multiset(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_multiset(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_multiset(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1367,7 +1367,7 @@ a b c a b c ``` -## hash_multiset::hasher (STL/CLR) +## `hash_multiset::hasher` The hashing delegate for a key. @@ -1406,7 +1406,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_multiset::insert (STL/CLR) +## `hash_multiset::insert` Adds elements. @@ -1422,34 +1422,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1519,7 +1519,7 @@ a b b c x a b b c x y ``` -## hash_multiset::iterator (STL/CLR) +## `hash_multiset::iterator` The type of an iterator for the controlled sequence. @@ -1561,7 +1561,7 @@ int main() a b c ``` -## hash_multiset::key_comp (STL/CLR) +## `hash_multiset::key_comp` Copies the ordering delegate for two keys. @@ -1620,7 +1620,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multiset::key_compare (STL/CLR) +## `hash_multiset::key_compare` The ordering delegate for two keys. @@ -1680,7 +1680,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_multiset::key_type (STL/CLR) +## `hash_multiset::key_type` The type of an ordering key. @@ -1692,7 +1692,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1725,7 +1725,7 @@ int main() a b c ``` -## hash_multiset::load_factor (STL/CLR) +## `hash_multiset::load_factor` Counts the average elements per bucket. @@ -1737,7 +1737,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_multiset::size (STL/CLR)](#size)`() /` [hash_multiset::bucket_count (STL/CLR)](#count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / count()`. You use it to determine the average bucket size. ### Example @@ -1799,7 +1799,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::lower_bound (STL/CLR) +## `hash_multiset::lower_bound` Finds beginning of range that matches a specified key. @@ -1811,12 +1811,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1856,7 +1856,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## hash_multiset::make_value (STL/CLR) +## `hash_multiset::make_value` Constructs a value object. @@ -1868,12 +1868,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1902,7 +1902,7 @@ int main() a b c ``` -## hash_multiset::max_load_factor (STL/CLR) +## `hash_multiset::max_load_factor` Gets or sets the maximum elements per bucket. @@ -1915,14 +1915,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -1984,7 +1984,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::operator= (STL/CLR) +## `hash_multiset::operator=` Replaces the controlled sequence. @@ -1996,12 +1996,12 @@ hash_multiset% operator=(hash_multiset% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2039,7 +2039,7 @@ a b c a b c ``` -## hash_multiset::rbegin (STL/CLR) +## `hash_multiset::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2087,7 +2087,7 @@ a b c *++rbegin() = b ``` -## hash_multiset::reference (STL/CLR) +## `hash_multiset::reference` The type of a reference to an element. @@ -2132,7 +2132,7 @@ int main() a b c ``` -## hash_multiset::rehash (STL/CLR) +## `hash_multiset::rehash` Rebuilds the hash table. @@ -2144,7 +2144,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_multiset::load_factor (STL/CLR)](#load_factor)`() <=` [hash_multiset::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2206,7 +2206,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_multiset::rend (STL/CLR) +## `hash_multiset::rend` Designates the end of the reversed controlled sequence. @@ -2255,7 +2255,7 @@ a b c *--rend() = a ``` -## hash_multiset::reverse_iterator (STL/CLR) +## `hash_multiset::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2297,7 +2297,7 @@ int main() c b a ``` -## hash_multiset::size (STL/CLR) +## `hash_multiset::size` Counts the number of elements. @@ -2309,7 +2309,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_multiset::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`hash_multiset::empty`](#empty). ### Example @@ -2351,9 +2351,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_multiset::size_type (STL/CLR) +## `hash_multiset::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2399,7 +2399,7 @@ a b c end()-begin() = 3 ``` -## hash_multiset::swap (STL/CLR) +## `hash_multiset::swap` Swaps the contents of two containers. @@ -2411,12 +2411,12 @@ void swap(hash_multiset% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2467,7 +2467,7 @@ d e f a b c ``` -## hash_multiset::to_array (STL/CLR) +## `hash_multiset::to_array` Copies the controlled sequence to a new array. @@ -2517,7 +2517,7 @@ a b c d a b c ``` -## hash_multiset::upper_bound (STL/CLR) +## `hash_multiset::upper_bound` Finds end of range that matches a specified key. @@ -2529,12 +2529,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2574,7 +2574,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## hash_multiset::value_comp (STL/CLR) +## `hash_multiset::value_comp` Copies the ordering delegate for two element values. @@ -2618,7 +2618,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_multiset::value_compare (STL/CLR) +## `hash_multiset::value_compare` The ordering delegate for two element values. @@ -2663,7 +2663,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_multiset::value_type (STL/CLR) +## `hash_multiset::value_type` The type of an element. diff --git a/docs/dotnet/hash-set-stl-clr.md b/docs/dotnet/hash-set-stl-clr.md index fd3ce0dca71..6a4a7d6bc73 100644 --- a/docs/dotnet/hash-set-stl-clr.md +++ b/docs/dotnet/hash-set-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::hash_set", "cliext::hash_set::begin", "cliext::hash_set:: helpviewer_keywords: [" header [STL/CLR]", "hash_set class [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "bucket_count member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "hash_delegate member [STL/CLR]", "hash_set member [STL/CLR]", "hasher member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "load_factor member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "max_load_factor member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rehash member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: d110e356-ba3e-4e52-9e2d-d997bf975c96 --- -# hash_set (STL/CLR) +# `hash_set` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `hash_set` to manage a sequence of elements as a hash table, each table entry storing a bidirectional linked list of nodes, and each node storing one element. The value of each element is used as a key, for ordering the sequence. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,117 +31,117 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[hash_set::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[hash_set::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[hash_set::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[hash_set::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[hash_set::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[hash_set::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[hash_set::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[hash_set::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[hash_set::hasher (STL/CLR)](#hasher)|The hashing delegate for a key.| -|[hash_set::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[hash_set::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[hash_set::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[hash_set::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[hash_set::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[hash_set::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[hash_set::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[hash_set::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[hash_set::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[hash_set::bucket_count (STL/CLR)](#bucket_count)|Counts the number of buckets.| -|[hash_set::clear (STL/CLR)](#clear)|Removes all elements.| -|[hash_set::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[hash_set::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[hash_set::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[hash_set::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[hash_set::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[hash_set::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[hash_set::hash_delegate (STL/CLR)](#hash_delegate)|Copies the hashing delegate for a key.| -|[hash_set::hash_set (STL/CLR)](#hash_set)|Constructs a container object.| -|[hash_set::insert (STL/CLR)](#insert)|Adds elements.| -|[hash_set::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[hash_set::load_factor (STL/CLR)](#load_factor)|Counts the average elements per bucket.| -|[hash_set::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[hash_set::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[hash_set::max_load_factor (STL/CLR)](#max_load_factor)|Gets or sets the maximum elements per bucket.| -|[hash_set::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[hash_set::rehash (STL/CLR)](#rehash)|Rebuilds the hash table.| -|[hash_set::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[hash_set::size (STL/CLR)](#size)|Counts the number of elements.| -|[hash_set::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[hash_set::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[hash_set::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[hash_set::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[hash_set::operator= (STL/CLR)](#op)|Replaces the controlled sequence.| +| Type definition | Description | +|---|---| +| [`hash_set::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`hash_set::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`hash_set::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`hash_set::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`hash_set::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`hash_set::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`hash_set::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`hash_set::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`hash_set::hasher`](#hasher) | The hashing delegate for a key. | +| [`hash_set::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`hash_set::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`hash_set::key_type`](#key_type) | The type of an ordering key. | +| [`hash_set::reference`](#reference) | The type of a reference to an element. | +| [`hash_set::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`hash_set::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`hash_set::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`hash_set::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`hash_set::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`hash_set::bucket_count`](#bucket_count) | Counts the number of buckets. | +| [`hash_set::clear`](#clear) | Removes all elements. | +| [`hash_set::count`](#count) | Counts elements matching a specified key. | +| [`hash_set::empty`](#empty) | Tests whether no elements are present. | +| [`hash_set::end`](#end) | Designates the end of the controlled sequence. | +| [`hash_set::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`hash_set::erase`](#erase) | Removes elements at specified positions. | +| [`hash_set::find`](#find) | Finds an element that matches a specified key. | +| [`hash_set::hash_delegate`](#hash_delegate) | Copies the hashing delegate for a key. | +| [`hash_set::hash_set`](#hash_set) | Constructs a container object. | +| [`hash_set::insert`](#insert) | Adds elements. | +| [`hash_set::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`hash_set::load_factor`](#load_factor) | Counts the average elements per bucket. | +| [`hash_set::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`hash_set::make_value`](#make_value) | Constructs a value object. | +| [`hash_set::max_load_factor`](#max_load_factor) | Gets or sets the maximum elements per bucket. | +| [`hash_set::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`hash_set::rehash`](#rehash) | Rebuilds the hash table. | +| [`hash_set::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`hash_set::size`](#size) | Counts the number of elements. | +| [`hash_set::swap`](#swap) | Swaps the contents of two containers. | +| [`hash_set::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`hash_set::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`hash_set::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`hash_set::operator=`](#op) | Replaces the controlled sequence. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|IHash\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `IHash` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes in a bidirectional linked list. To speed access, the object also maintains a varying-length array of pointers into the list (the hash table), effectively managing the whole list as a sequence of sublists, or buckets. It inserts elements into a bucket that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders each bucket it controls by calling a stored delegate object of type [hash_set::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. +The object orders each bucket it controls by calling a stored delegate object of type [`hash_set::key_compare`](#key_compare). You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the comparison `operator<=(key_type, key_type)`. -You access the stored delegate object by calling the member function [hash_set::key_comp (STL/CLR)](#key_comp)`()`. Such a delegate object must define equivalent ordering between keys of type [hash_set::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +You access the stored delegate object by calling the member function [`hash_set::key_comp`](#key_comp). Such a delegate object must define equivalent ordering between keys of type [`hash_set::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. If `key_comp()(X, Y) && key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines eqivalent ordering. +Any ordering rule that behaves like `operator<=(key_type, key_type)`, `operator>=(key_type, key_type)` or `operator==(key_type, key_type)` defines equivalent ordering. -Note that the container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_multiset (STL/CLR)](../dotnet/hash-multiset-stl-clr.md), an object of template class `hash_set` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) +The container ensures only that elements whose keys have equivalent ordering (and which hash to the same integer value) are adjacent within a bucket. Unlike template class [hash_multiset (STL/CLR)](../dotnet/hash-multiset-stl-clr.md), an object of template class `hash_set` ensures that keys for all elements are unique. (No two keys have equivalent ordering.) -The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [hash_set::hasher (STL/CLR)](#hasher). You access this stored object by calling the member function [hash_set::hash_delegate (STL/CLR)](#hash_delegate)`()` to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: +The object determines which bucket should contain a given ordering key by calling a stored delegate object of type [`hash_set::hasher`](#hasher). You access this stored object by calling the member function [`hash_set::hash_delegate`](#hash_delegate) to obtain an integer value that depends on the key value. You can specify the stored delegate object when you construct the hash_set; if you specify no delegate object, the default is the function `System::Object::hash_value(key_type)`. That means, for any keys `X` and `Y`: `hash_delegate()(X)` returns the same integer result on every call. If `X` and `Y` have equivalent ordering, then `hash_delegate()(X)` should return the same integer result as `hash_delegate()(Y)`. -Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations that is independent of the number of elements in the sequence (constant time) -- at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in constant time. That is, the number of operations is independent of the number of elements in the sequence, at least in the best of cases. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -If hashed values are not uniformly distributed, however, a hash table can degenerate. In the extreme -- for a hash function that always returns the same value -- lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [hash_set::max_load_factor (STL/CLR)](#max_load_factor) and [hash_set::rehash (STL/CLR)](#rehash). +If hashed values aren't uniformly distributed, however, a hash table can degenerate. In the extreme (for a hash function that always returns the same value), lookup, insertion, and removal are proportional to the number of elements in the sequence (linear time). The container endeavors to choose a reasonable hash function, mean bucket size, and hash-table size (total number of buckets), but you can override any or all of these choices. See, for example, the functions [`hash_set::max_load_factor`](#max_load_factor) and [`hash_set::rehash`](#rehash). -A hash_set supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [hash_set::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a hash_set iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `hash_set` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `hash_set` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a hash_set element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `hash_set` element directly given its numerical position. That requires a random-access iterator. -A hash_set iterator stores a handle to its associated hash_set node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A hash_set iterator remains valid so long as its associated hash_set node is associated with some hash_set. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `hash_set` iterator stores a handle to its associated `hash_set` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `hash_set` iterator remains valid so long as its associated `hash_set` node is associated with some hash_set. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## hash_set::begin (STL/CLR) +## `hash_set::begin` Designates the beginning of the controlled sequence. @@ -183,7 +183,7 @@ int main() } ``` -## hash_set::bucket_count (STL/CLR) +## `hash_set::bucket_count` Counts the number of buckets. @@ -195,7 +195,7 @@ int bucket_count(); ### Remarks -The member functions returns the current number of buckets. You use it to determine the size of the hash table. +The member function returns the current number of buckets. You use it to determine the size of the hash table. ### Example @@ -257,7 +257,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_set::clear (STL/CLR) +## `hash_set::clear` Removes all elements. @@ -269,7 +269,7 @@ void clear(); ### Remarks -The member function effectively calls [hash_set::erase (STL/CLR)](#erase)`(` [hash_set::begin (STL/CLR)](#begin)`(),` [hash_set::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -315,7 +315,7 @@ a b size() = 0 ``` -## hash_set::const_iterator (STL/CLR) +## `hash_set::const_iterator` The type of a constant iterator for the controlled sequence. @@ -357,7 +357,7 @@ int main() a b c ``` -## hash_set::const_reference (STL/CLR) +## `hash_set::const_reference` The type of a constant reference to an element. @@ -402,9 +402,9 @@ int main() a b c ``` -## hash_set::const_reverse_iterator (STL/CLR) +## `hash_set::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -444,7 +444,7 @@ int main() c b a ``` -## hash_set::count (STL/CLR) +## `hash_set::count` Finds the number of elements matching a specified key. @@ -456,12 +456,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -497,7 +497,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## hash_set::difference_type (STL/CLR) +## `hash_set::difference_type` The types of a signed distance between two elements. @@ -552,7 +552,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## hash_set::empty (STL/CLR) +## `hash_set::empty` Tests whether no elements are present. @@ -564,7 +564,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [hash_set::size (STL/CLR)](#size)`() == 0`. You use it to test whether the hash_set is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `hash_set` is empty. ### Example @@ -604,7 +604,7 @@ size() = 0 empty() = True ``` -## hash_set::end (STL/CLR) +## `hash_set::end` Designates the end of the controlled sequence. @@ -616,7 +616,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -653,7 +653,7 @@ a b c *--end() = c ``` -## hash_set::equal_range (STL/CLR) +## `hash_set::equal_range` Finds range that matches a specified key. @@ -665,12 +665,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [hash_set::lower_bound (STL/CLR)](#lower_bound)`(key),` [hash_set::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -713,7 +713,7 @@ equal_range(L'x') empty = True b ``` -## hash_set::erase (STL/CLR) +## `hash_set::erase` Removes elements at specified positions. @@ -727,25 +727,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [hash_set::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -797,7 +797,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## hash_set::find (STL/CLR) +## `hash_set::find` Finds an element that matches a specified key. @@ -809,12 +809,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [hash_set::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -853,7 +853,7 @@ find b = b find C = False ``` -## hash_set::generic_container (STL/CLR) +## `hash_set::generic_container` The type of the generic interface for the container. @@ -917,7 +917,7 @@ a b c d a b c d e ``` -## hash_set::generic_iterator (STL/CLR) +## `hash_set::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -973,7 +973,7 @@ a b c a ``` -## hash_set::generic_reverse_iterator (STL/CLR) +## `hash_set::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -1029,7 +1029,7 @@ a b c c ``` -## hash_set::generic_value (STL/CLR) +## `hash_set::generic_value` The type of an element for use with the generic interface for the container. @@ -1083,7 +1083,7 @@ a b c a ``` -## hash_set::hash_delegate (STL/CLR) +## `hash_set::hash_delegate` Finds an element that matches a specified key. @@ -1121,7 +1121,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_set::hash_set (STL/CLR) +## `hash_set::hash_set` Constructs a container object. @@ -1150,19 +1150,19 @@ hash_set(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*hashfn*
+*`hashfn`*\ Hash function for mapping keys to buckets. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1177,25 +1177,25 @@ The constructor: `explicit hash_set(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the default hash function. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and the default hash function. The constructor: `hash_set(key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate and hash function. The constructor: `hash_set(hash_set% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_set object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_set` object *`right`*, with the default ordering predicate and hash function. The constructor: `hash_set(hash_set^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the hash_set object *right*, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate, and with the default hash function. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `hash_set` object *`right`*, with the default ordering predicate and hash function. The constructor: @@ -1207,31 +1207,31 @@ The constructor: `template hash_set(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and the default hash function. The constructor: `template hash_set(InIter first, InIter last, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate and hash function. The constructor: `hash_set(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate and hash function. The constructor: `hash_set(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the default hash function. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and default hash function. The constructor: `hash_set(System::Collections::Generic::IEnumerable^ right, key_compare^ pred, hasher^ hashfn);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*, and with the hash function *hashfn*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*, and with the hash function *`hashfn`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate and hash function. ### Example @@ -1361,7 +1361,7 @@ a b c a b c ``` -## hash_set::hasher (STL/CLR) +## `hash_set::hasher` The hashing delegate for a key. @@ -1400,7 +1400,7 @@ hash(L'a') = 1616896120 hash(L'b') = 570892832 ``` -## hash_set::insert (STL/CLR) +## `hash_set::insert` Adds elements. @@ -1416,34 +1416,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function endeavors to insert an element with value *val*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. +The first member function endeavors to insert an element with value *`val`*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1516,7 +1516,7 @@ a b c x a b c x y ``` -## hash_set::iterator (STL/CLR) +## `hash_set::iterator` The type of an iterator for the controlled sequence. @@ -1558,7 +1558,7 @@ int main() a b c ``` -## hash_set::key_comp (STL/CLR) +## `hash_set::key_comp` Copies the ordering delegate for two keys. @@ -1617,7 +1617,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_set::key_compare (STL/CLR) +## `hash_set::key_compare` The ordering delegate for two keys. @@ -1677,7 +1677,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## hash_set::key_type (STL/CLR) +## `hash_set::key_type` The type of an ordering key. @@ -1689,7 +1689,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1722,7 +1722,7 @@ int main() a b c ``` -## hash_set::load_factor (STL/CLR) +## `hash_set::load_factor` Counts the average elements per bucket. @@ -1734,7 +1734,7 @@ float load_factor(); ### Remarks -The member function returns `(float)`[hash_set::size (STL/CLR)](#size)`() /` [hash_set::bucket_count (STL/CLR)](#bucket_count)`()`. You use it to determine the average bucket size. +The member function returns `(float)size() / bucket_count()`. You use it to determine the average bucket size. ### Example @@ -1796,7 +1796,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_set::lower_bound (STL/CLR) +## `hash_set::lower_bound` Finds beginning of range that matches a specified key. @@ -1808,12 +1808,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, it returns [hash_set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1853,7 +1853,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## hash_set::make_value (STL/CLR) +## `hash_set::make_value` Constructs a value object. @@ -1865,12 +1865,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1899,7 +1899,7 @@ int main() a b c ``` -## hash_set::max_load_factor (STL/CLR) +## `hash_set::max_load_factor` Gets or sets the maximum elements per bucket. @@ -1912,14 +1912,14 @@ void max_load_factor(float new_factor); #### Parameters -*new_factor*
+*`new_factor`*\ New maximum load factor to store. ### Remarks The first member function returns the current stored maximum load factor. You use it to determine the maximum average bucket size. -The second member function replaces the store maximum load factor with *new_factor*. No automatic rehashing occurs until a subsequent insert. +The second member function replaces the store maximum load factor with *`new_factor`*. No automatic rehashing occurs until a subsequent insert. ### Example @@ -1966,7 +1966,7 @@ int main() } ``` -## hash_set::operator= (STL/CLR) +## `hash_set::operator=` Replaces the controlled sequence. @@ -1978,12 +1978,12 @@ hash_set% operator=(hash_set% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -2021,7 +2021,7 @@ a b c a b c ``` -## hash_set::rbegin (STL/CLR) +## `hash_set::rbegin` Designates the beginning of the reversed controlled sequence. @@ -2069,7 +2069,7 @@ a b c *++rbegin() = b ``` -## hash_set::reference (STL/CLR) +## `hash_set::reference` The type of a reference to an element. @@ -2114,7 +2114,7 @@ int main() a b c ``` -## hash_set::rehash (STL/CLR) +## `hash_set::rehash` Rebuilds the hash table. @@ -2126,7 +2126,7 @@ void rehash(); ### Remarks -The member function rebuilds the hash table, ensuring that [hash_set::load_factor (STL/CLR)](#load_factor)`() <=` [hash_set::max_load_factor (STL/CLR)](#max_load_factor). Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. +The member function rebuilds the hash table, ensuring that `load_factor() <= max_load_factor()`. Otherwise, the hash table increases in size only as needed after an insertion. (It never automatically decreases in size.) You use it to adjust the size of the hash table. ### Example @@ -2188,7 +2188,7 @@ load_factor() = 0.0234375 max_load_factor() = 0.25 ``` -## hash_set::rend (STL/CLR) +## `hash_set::rend` Designates the end of the reversed controlled sequence. @@ -2237,7 +2237,7 @@ a b c *--rend() = a ``` -## hash_set::reverse_iterator (STL/CLR) +## `hash_set::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2279,7 +2279,7 @@ int main() c b a ``` -## hash_set::size (STL/CLR) +## `hash_set::size` Counts the number of elements. @@ -2291,7 +2291,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [hash_set::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -2333,9 +2333,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## hash_set::size_type (STL/CLR) +## `hash_set::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2381,7 +2381,7 @@ a b c end()-begin() = 3 ``` -## hash_set::swap (STL/CLR) +## `hash_set::swap` Swaps the contents of two containers. @@ -2393,12 +2393,12 @@ void swap(hash_set% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2449,7 +2449,7 @@ d e f a b c ``` -## hash_set::to_array (STL/CLR) +## `hash_set::to_array` Copies the controlled sequence to a new array. @@ -2499,7 +2499,7 @@ a b c d a b c ``` -## hash_set::upper_bound (STL/CLR) +## `hash_set::upper_bound` Finds end of range that matches a specified key. @@ -2511,12 +2511,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *key* and has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [hash_set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that hashes to the same bucket as *`key`* and has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2556,7 +2556,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## hash_set::value_comp (STL/CLR) +## `hash_set::value_comp` Copies the ordering delegate for two element values. @@ -2600,7 +2600,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_set::value_compare (STL/CLR) +## `hash_set::value_compare` The ordering delegate for two element values. @@ -2645,7 +2645,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## hash_set::value_type (STL/CLR) +## `hash_set::value_type` The type of an element. diff --git a/docs/dotnet/hosting-a-windows-form-user-control-as-an-mfc-dialog-box.md b/docs/dotnet/hosting-a-windows-form-user-control-as-an-mfc-dialog-box.md index 14d59ab612a..8c35fc41ed9 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,15 @@ --- -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 +ms.topic: how-to --- # 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 +17,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 +29,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 +58,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 +76,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 +86,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 +99,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 +114,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 +126,5 @@ The process that `CWinFormsDialog` uses to host the user control is the similar ## See also - -[Using a Windows Form User Control in MFC](../dotnet/using-a-windows-form-user-control-in-mfc.md) +\ +[Using a Windows Form User Control in MFC](using-a-windows-form-user-control-in-mfc.md) diff --git a/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md b/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md index b7b889caf1a..9244b69d983 100644 --- a/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md +++ b/docs/dotnet/hosting-a-windows-form-user-control-in-an-mfc-dialog-box.md @@ -4,6 +4,7 @@ title: "Hosting a Windows Form User Control in an MFC Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["MFC [C++], Windows Forms support", "hosting Windows Forms control [C++]", "Windows Forms [C++], MFC support"] ms.assetid: 9f66ee52-b7cb-4ffd-8306-392a5da990d8 +ms.topic: concept-article --- # Hosting a Windows Form User Control in an MFC Dialog Box diff --git a/docs/dotnet/hosting-a-windows-forms-user-control-as-an-mfc-view.md b/docs/dotnet/hosting-a-windows-forms-user-control-as-an-mfc-view.md index e3968fb0fcd..7353bb36611 100644 --- a/docs/dotnet/hosting-a-windows-forms-user-control-as-an-mfc-view.md +++ b/docs/dotnet/hosting-a-windows-forms-user-control-as-an-mfc-view.md @@ -4,6 +4,7 @@ title: "Hosting a Windows Forms User Control as an MFC View" ms.date: "11/04/2016" helpviewer_keywords: ["MFC [C++], Windows Forms support", "Windows Forms controls [C++], hosting as an MFC view", "hosting Windows Forms control [C++]"] ms.assetid: 43c02ab4-1366-434c-a980-0b19326d6ea0 +ms.topic: concept-article --- # Hosting a Windows Forms User Control as an MFC View 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 1dab0f2a63f..c16e9e87202 100644 --- a/docs/dotnet/how-to-access-characters-in-a-system-string.md +++ b/docs/dotnet/how-to-access-characters-in-a-system-string.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How to: Access Characters in a System::String" title: "How to: Access Characters in a System::String" +description: "Learn more about: How to: Access Characters in a System::String" +ms.date: 11/04/2016 ms.custom: "get-started-article" -ms.date: "11/04/2016" helpviewer_keywords: ["characters [C++], accessing in System::String", "examples [C++], strings", "strings [C++], accessing characters"] -ms.assetid: cfc89756-aef3-4988-907e-fb236dcb7087 --- # How to: Access Characters in a System::String @@ -21,7 +20,7 @@ If you pass `ppchar` to a native function, then it must be a pinning pointer; th ```cpp // PtrToStringChars.cpp // compile with: /clr -#include +#include using namespace System; int main() { @@ -54,7 +53,7 @@ size_t getlen(System::String ^ s) { // make sure it doesn't move during the unmanaged call pin_ptr pinchars = PtrToStringChars(s); return wcsnlen(pinchars, maxsize); -}; +} int main() { System::Console::WriteLine(getlen("testing")); diff --git a/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md b/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md index f0987db9702..88f4ef71bbd 100644 --- a/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md +++ b/docs/dotnet/how-to-convert-from-a-stl-clr-container-to-a-dotnet-collection.md @@ -13,7 +13,7 @@ This topic shows how to convert STL/CLR containers to their equivalent .NET coll 1. Use one of the following methods: - - To convert part of a container, call the [make_collection](./adapter-stl-clr.md#make_collection) function, and pass the begin iterator and end iterator of the STL/CLR container to be copied into the .NET collection. This template function takes an STL/CLR iterator as a template argument. The first example demonstrates this method. + - To convert part of a container, call the [make_collection](./adapter-stl-clr.md#make_collection) function, and pass the begin iterator and end iterator of the STL/CLR container to be copied into the .NET collection. This function template takes an STL/CLR iterator as a template argument. The first example demonstrates this method. - To convert an entire container, cast the container to an appropriate .NET collection interface or interface collection. The second example demonstrates this method. diff --git a/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md b/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md index a84ac096d45..4bdccb60b0c 100644 --- a/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md +++ b/docs/dotnet/how-to-create-clr-console-applications-cpp-cli.md @@ -15,7 +15,7 @@ You can use the **CLR Console Application** template in the **New Project** dia You can use the **CLR Console App** template in the **New Project** dialog to create a console app project that already has essential project references and files. -C++/CLI support isn't installed by default when you install a Visual Studio C++ workload. If you don't see a CLR heading under Visual C++ in the **New Project** dialog, you may need to install C++/CLI support. For more information, see [.NET programming with C++/CLI](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md). +C++/CLI support isn't installed by default when you install a Visual Studio C++ workload. If you don't see a CLR heading under Visual C++ in the **New Project** dialog, you may need to install C++/CLI support. For more information, see [Install C++/CLI support in Visual Studio 2022](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md#install-ccli-support-in-visual-studio-2022). ::: moniker-end ::: moniker range=">=msvc-160" diff --git a/docs/dotnet/how-to-create-clr-empty-projects.md b/docs/dotnet/how-to-create-clr-empty-projects.md index 1a34671db3c..ff213eeef39 100644 --- a/docs/dotnet/how-to-create-clr-empty-projects.md +++ b/docs/dotnet/how-to-create-clr-empty-projects.md @@ -18,7 +18,8 @@ To create a CLR empty project, use the **CLR Empty Project** template, which is The **New Project** dialog box appears. -1. Under **Installed Templates**, click the **Visual C++** node; then click the **CLR** node. Choose the **CLR Empty Project** icon. +1. Under **Installed Templates**, click the **Visual C++** node; then click the **CLR** node. Choose the **CLR Empty Project** icon. If you don't see the CLR empty project templates in the Create a new project dialog, you may need to install C++/CLI support. For more information, see [Install C++/CLI support in Visual Studio 2022](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md#install-ccli-support-in-visual-studio-2022). + 1. In the **Name** box, enter a unique name for your application. diff --git a/docs/dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md b/docs/dotnet/how-to-declare-override-specifiers-in-native-compilations-cpp-cli.md index a9e25c2df5b..3eeb84d31e6 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 f2aeaa4c5bf..a0b88ce253c 100644 --- a/docs/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md +++ b/docs/dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md @@ -3,7 +3,6 @@ title: "How to: Define and consume classes and structs (C++/CLI)" description: "How to create and use user-defined class and struct types in C++/CLI code." ms.date: 09/25/2020 helpviewer_keywords: ["structs [C++]", "classes [C++], instantiating"] -ms.assetid: 1c03cb0d-1459-4b5e-af65-97d6b3094fd7 --- # How to: Define and consume classes and structs (C++/CLI) @@ -467,7 +466,7 @@ in static constructor ## Semantics of the `this` pointer -When you're using C++\CLI to define types, the **`this`** pointer in a reference type is of type *handle*. The **`this`** pointer in a value type is of type *interior pointer*. +When you're using C++/CLI to define types, the **`this`** pointer in a reference type is of type *handle*. The **`this`** pointer in a value type is of type *interior pointer*. These different semantics of the **`this`** pointer can cause unexpected behavior when a default indexer is called. The next example shows the correct way to access a default indexer in both a ref type and a value type. @@ -636,7 +635,7 @@ The following sample demonstrates when a copy constructor isn't generated. ```cpp // compile with: /clr -#include +#include struct S { int i; @@ -802,13 +801,13 @@ If your type has a finalizer, the compiler generates a `Finalize(void)` method t If a type has either a finalizer or a destructor, the compiler generates a `Dispose(bool)` method, according to the design pattern. (For information, see [Dispose Pattern](/dotnet/standard/design-guidelines/dispose-pattern)). You can't explicitly author or call `Dispose(bool)` in Visual C++. -If a type has a base class that conforms to the design pattern, the destructors for all base classes are called when the destructor for the derived class is called. (If your type is written in Visual C++, the compiler ensures that your types implement this pattern.) In other words, the destructor of a reference class chains to its bases and members as specified by the C++ standard. First, the class’s destructor is run. Then, the destructors for its members get run in the reverse of the order in which they were constructed. Finally, the destructors for its base classes get run in the reverse of the order in which they were constructed. +If a type has a base class that conforms to the design pattern, the destructors for all base classes are called when the destructor for the derived class is called. (If your type is written in Visual C++, the compiler ensures that your types implement this pattern.) In other words, the destructor of a reference class chains to its bases and members as specified by the C++ standard. First, the class's destructor is run. Then, the destructors for its members get run in the reverse of the order in which they were constructed. Finally, the destructors for its base classes get run in the reverse of the order in which they were constructed. Destructors and finalizers aren't allowed inside value types or interfaces. A finalizer can only be defined or declared in a reference type. Like a constructor and destructor, a finalizer has no return type. -After an object's finalizer runs, finalizers in any base classes are also called, beginning with the least derived type. Finalizers for data members aren't automatically chained to by a class’s finalizer. +After an object's finalizer runs, finalizers in any base classes are also called, beginning with the least derived type. Finalizers for data members aren't automatically chained to by a class's finalizer. If a finalizer deletes a native pointer in a managed type, you must ensure that references to or through the native pointer aren't prematurely collected. Call the destructor on the managed type instead of using . diff --git a/docs/dotnet/how-to-define-and-install-a-global-exception-handler.md b/docs/dotnet/how-to-define-and-install-a-global-exception-handler.md index bfed57f87c4..35af0b6fce2 100644 --- a/docs/dotnet/how-to-define-and-install-a-global-exception-handler.md +++ b/docs/dotnet/how-to-define-and-install-a-global-exception-handler.md @@ -4,6 +4,7 @@ title: "How to: Define and Install a Global Exception Handler" ms.date: "11/04/2016" helpviewer_keywords: ["handlers, global"] ms.assetid: dd88a812-3bc7-4ce8-8283-4b674c246534 +ms.topic: how-to --- # How to: Define and Install a Global Exception Handler 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 3a2235ad91a..eec4a6002ec 100644 --- a/docs/dotnet/how-to-define-and-use-delegates-cpp-cli.md +++ b/docs/dotnet/how-to-define-and-use-delegates-cpp-cli.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: How to: Define and Use Delegates (C++/CLI)" title: "How to: Define and Use Delegates (C++/CLI)" -ms.date: "11/04/2016" +description: "Learn more about: How to: Define and Use Delegates (C++/CLI)" +ms.date: 11/04/2016 helpviewer_keywords: ["delegates"] -ms.assetid: 1cdf3420-89c1-47c0-b796-aa984020e0f8 --- # How to: Define and Use Delegates (C++/CLI) @@ -442,7 +441,7 @@ int main() { Del^ d = gcnew Del(r1, &R::f); d += gcnew Del(&R::f); d(r2); -}; +} ``` **Output** diff --git a/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md b/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md index a86ffde8853..476d54cfb56 100644 --- a/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md +++ b/docs/dotnet/how-to-determine-if-an-image-is-native-or-clr.md @@ -8,9 +8,9 @@ ms.assetid: 5a854822-6172-4b22-b236-320165412568 --- # How to: Determine if an Image is Native or CLR -One way to determine whether an image was built for the common language runtime is to use **dumpbin**[/CLRHEADER](../build/reference/clrheader.md). +One way to determine whether an image was built for the common language runtime is to use the **`dumpbin /CLRHEADER`** command. For more information, see [`/CLRHEADER`](../build/reference/clrheader.md). -You can also programmatically check whether an image was built for the common language runtime. For more information, see [How to: Detect /clr Compilation](../dotnet/how-to-detect-clr-compilation.md). +You can also programmatically check whether an image was built for the common language runtime. For more information, see [How to: Detect /clr compilation](../dotnet/how-to-detect-clr-compilation.md). ## Example diff --git a/docs/dotnet/how-to-do-ddx-ddv-data-binding-with-windows-forms.md b/docs/dotnet/how-to-do-ddx-ddv-data-binding-with-windows-forms.md index 7d77830650e..098179c4ef5 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-migrate-to-clr.md b/docs/dotnet/how-to-migrate-to-clr.md index eea61e82fc1..e05adbbaf9b 100644 --- a/docs/dotnet/how-to-migrate-to-clr.md +++ b/docs/dotnet/how-to-migrate-to-clr.md @@ -1,22 +1,22 @@ --- +title: "How to: Migrate to /clr" description: "Learn more about: How to: Migrate to /clr" -title: "How to: Migrate to -clr" +ms.date: 09/18/2018 ms.custom: "get-started-article" -ms.date: "09/18/2018" +ms.topic: upgrade-and-migration-article helpviewer_keywords: ["upgrading Visual C++ applications, /clr compiler option", "compiling native code [C++]", "interoperability [C++], /clr compiler option", "interop [C++], /clr compiler option", "migration [C++], /clr compiler option", "/clr compiler option [C++], porting to"] -ms.assetid: c9290b8b-436a-4510-8b56-eae51f4a9afc --- -# How to: Migrate to /clr +# How to: Migrate to `/clr` -This topic discusses issues that arise when compiling native code with **/clr** (see [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) for more information). **/clr** allows native C++ code to invoke and be invoked from .NET assemblies in addition to other native C++ code. See [Mixed (Native and Managed) Assemblies](../dotnet/mixed-native-and-managed-assemblies.md) and [Native and .NET Interoperability](../dotnet/native-and-dotnet-interoperability.md) for more information on the advantages of compiling with **/clr**. +This article discusses issues that arise when compiling native code with **`/clr`**. For more information, see [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md). **`/clr`** allows native C++ code to invoke and be invoked from .NET assemblies in addition to other native C++ code. For more information on the advantages of compiling with **`/clr`**, see [Mixed (Native and Managed) Assemblies](../dotnet/mixed-native-and-managed-assemblies.md) and [Native and .NET Interoperability](../dotnet/native-and-dotnet-interoperability.md). -## Known Issues Compiling Library Projects with /clr +## Known issues compiling library projects with `/clr` -Visual Studio contains some known issues when compiling library projects with **/clr**: +Visual Studio contains some known issues when compiling library projects with **`/clr`**: -- Your code may query types at runtime with [CRuntimeClass::FromName](../mfc/reference/cruntimeclass-structure.md#fromname). However, if a type is in an MSIL .dll (compiled with **/clr**), the call to `FromName` may fail if it occurs before the static constructors run in the managed .dll (you will not see this problem if the FromName call happens after code has executed in the managed .dll). To work around this problem, you can force the construction of the managed static constructor by defining a function in the managed .dll, exporting it, and invoking it from the native MFC application. For example: +- Your code may query types at runtime with [`CRuntimeClass::FromName`](../mfc/reference/cruntimeclass-structure.md#fromname). However, if a type is in an MSIL DLL (compiled with **`/clr`**), the call to `FromName` may fail if it occurs before the static constructors run in the managed DLL. (You won't see this problem if the `FromName` call happens after code has executed in the managed DLL.) To work around this problem, you can force the construction of the managed static constructor: define a function in the managed DLL, export it, and invoke it from the native MFC application. For example: - ``` + ```cpp // MFC extension DLL Header file: __declspec( dllexport ) void EnsureManagedInitialization () { // managed code that won't be optimized away @@ -26,36 +26,34 @@ Visual Studio contains some known issues when compiling library projects with ** ## Compile with Visual C++ -Before using **/clr** on any module in your project, first compile and link your native project with Visual Studio 2010. - -The following steps, followed in order, provide the easiest path to a **/clr** compilation. It is important to compile and run your project after each of these steps. +Before you use **`/clr`** on any module in your project, first compile and link your native project with Visual Studio. -### Versions Prior to Visual Studio 2003 +The following steps, followed in order, provide the easiest path to a **`/clr`** compilation. It's important to compile and run your project after each of these steps. -If you are upgrading to Visual Studio 2010 from a version prior to Visual Studio 2003, you may see compiler errors related to the enhanced C++ standard conformance in Visual Studio 2003 +### Upgrading from earlier versions of Visual Studio -### Upgrading from Visual Studio 2003 +If you're upgrading Visual Studio from an earlier version, you may see compiler errors related to the enhanced Standard C++ conformance in Visual Studio. -Projects previous built with Visual Studio 2003 should also first be compiled without **/clr** as Visual Studio now has increased ANSI/ISO conformance and some breaking changes. The change that is likely to require the most attention is [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). Code that uses the CRT is very likely to produce deprecation warnings. These warnings can be suppressed, but migrating to the new [Security-Enhanced Versions of CRT Functions](../c-runtime-library/security-enhanced-versions-of-crt-functions.md) is preferred, as they provide better security and may reveal security issues in your code. +Projects built with earlier versions of Visual Studio should also first be compiled without **`/clr`**. Visual Studio now has increased Standard C++ conformance and some breaking changes. The changes that are likely to require the most attention are [Security Features in the CRT](../c-runtime-library/security-features-in-the-crt.md). Code that uses the CRT is likely to produce deprecation warnings. These warnings can be suppressed, but migrating to the new [Security-enhanced versions of CRT functions](../c-runtime-library/security-enhanced-versions-of-crt-functions.md) is preferred, as they provide better security and may reveal security issues in your code. ### Upgrading from Managed Extensions for C++ -Starting in Visual Studio 2005, code written with Managed Extensions for C++ won't compile under **/clr**. +In Visual Studio 2005 and later versions, code written with Managed Extensions for C++ won't compile under **`/clr`**. -## Convert C Code to C++ +## Convert C code to C++ -Although Visual Studio will compile C files, it is necessary to convert them to C++ for a **/clr** compilation. The actual filename doesn't have to be changed; you can use **/Tp** (see [/Tc, /Tp, /TC, /TP (Specify Source File Type)](../build/reference/tc-tp-tc-tp-specify-source-file-type.md).) Note that although C++ source code files are required for **/clr**, it is not necessary to re-factor your code to use object-oriented paradigms. +Although Visual Studio will compile C files, it's necessary to convert them to C++ for a **`/clr`** compilation. The actual filename doesn't have to be changed; you can use **`/Tp`** (see [`/Tc`, `/Tp`, `/TC`, `/TP` (Specify source file type)](../build/reference/tc-tp-tc-tp-specify-source-file-type.md).) Although C++ source code files are required for **`/clr`**, it isn't necessary to refactor your code to use object-oriented paradigms. -C code is very likely to require changes when compiled as a C++ file. The C++ type-safety rules are strict, so type conversions must be made explicit with casts. For example, malloc returns a void pointer, but can be assigned to a pointer to any type in C with a cast: +C code is likely to require changes when compiled as a C++ file. The C++ type-safety rules are strict, so type conversions must be made explicit with casts. For example, malloc returns a void pointer, but can be assigned to a pointer to any type in C with a cast: -``` +```cpp int* a = malloc(sizeof(int)); // C code int* b = (int*)malloc(sizeof(int)); // C++ equivalent ``` -Function pointers are also strictly type-safe in C++, so the following C code requires modification. In C++ it's best to create a **`typedef`** that defines the function pointer type, and then use that type to cast function pointers: +Function pointers are also strictly type-safe in C++, so the following C code requires modification. In C++, it's best to create a **`typedef`** that defines the function pointer type, and then use that type to cast function pointers: -``` +```cpp NewFunc1 = GetProcAddress( hLib, "Func1" ); // C code typedef int(*MYPROC)(int); // C++ equivalent NewFunc2 = (MYPROC)GetProcAddress( hLib, "Func2" ); @@ -63,87 +61,87 @@ NewFunc2 = (MYPROC)GetProcAddress( hLib, "Func2" ); C++ also requires that functions either be prototyped or fully defined before they can be referenced or invoked. -Identifiers used in C code that happen to be keywords in C++ (such as **`virtual`**, **`new`**, **`delete`**, **`bool`**, **`true`**, **`false`**, etc.) must be renamed. This can generally be done with simple search-and-replace operations. +Identifiers used in C code that happen to be keywords in C++ (such as **`virtual`**, **`new`**, **`delete`**, **`bool`**, **`true`**, **`false`**, etc.) must be renamed. This change can generally be done with simple search-and-replace operations. -``` +```cpp COMObj1->lpVtbl->Method(COMObj, args); // C code COMObj2->Method(args); // C++ equivalent ``` -## Reconfigure Project Settings +## Reconfigure project settings -After your project compiles and runs in Visual Studio 2010 you should create new project configurations for **/clr** rather than modifying the default configurations. **/clr** is incompatible with some compiler options and creating separate configurations lets you build your project as native or managed. When **/clr** is selected in the property pages dialog box, project settings not compatible with **/clr** are disabled (and disabled options are not automatically restored if **/clr** is subsequently unselected). +After your project compiles and runs in Visual Studio, you should create new project configurations for **`/clr`** rather than modifying the default configurations. **`/clr`** is incompatible with some compiler options. Creating separate configurations lets you build your project as native or managed. When **`/clr`** is selected in the property pages dialog box, project settings not compatible with **`/clr`** are disabled. (Disabled options aren't automatically restored if **`/clr`** is later unselected.) -### Create New Project Configurations +### Create new project configurations -You can use **Copy Settings From** option in the **New Project Configuration Dialog Box** (**Build** > **Configuration Manager** > **Active Solution Configuration** > **New**) to create a project configuration based on your existing project settings. Do this once for the Debug configuration and once for Release configuration. Subsequent changes can then be applied to the **/clr** -specific configurations only, leaving the original project configurations intact. +You can use **Copy Settings From** option in the **New Project Configuration Dialog Box** (**Build** > **Configuration Manager** > **Active Solution Configuration** > **New**) to create a project configuration based on your existing project settings. Create a copy of your configuration once for the Debug configuration, and once for Release configuration. Subsequent changes can then be applied to the **`/clr`**-specific configurations only, leaving the original project configurations intact. Projects that use custom build rules may require extra attention. -This step has different implications for projects that use makefiles. In this case a separate build-target can be configured, or version specific to **/clr** compilation can be created from a copy of the original. +This step has different implications for projects that use makefiles. In this case, a separate build-target can be configured, or a version specific to **`/clr`** compilation can be created from a copy of the original. -### Change Project Settings +### Change project settings -**/clr** can be selected in the development environment by following the instructions in [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md). As mentioned previously, this step will automatically disable conflicting project settings. +**`/clr`** can be selected in the development environment by following the instructions in [/clr (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md). As mentioned previously, this step will automatically disable conflicting project settings. > [!NOTE] -> When upgrading a managed library or web service project from Visual Studio 2003, the **/Zl** compiler option will added to the **Command Line** property page. This will cause LNK2001. Remove **/Zl** from the **Command Line** property page to resolve. See [/Zl (Omit Default Library Name)](../build/reference/zl-omit-default-library-name.md) and [Set compiler and build properties](../build/working-with-project-properties.md) for more information. Or, add msvcrt.lib and msvcmrt.lib to the linker's **Additional Dependencies** property. +> When upgrading a managed library or web service project from Visual Studio 2003, the **`/Zl`** compiler option is added to the **Command Line** property page. This causes LNK2001 errors. Remove **`/Zl`** from the **Command Line** property page to resolve the errors. For more information, see [`/Zl` (Omit default library name)](../build/reference/zl-omit-default-library-name.md) and [Set compiler and build properties](../build/working-with-project-properties.md). -For projects built with makefiles, incompatible compiler options must be disabled manually once **/clr** is added. See /[/clr Restrictions](../build/reference/clr-restrictions.md) for information on compiler options that are not compatible with **/clr**. +For projects built with makefiles, incompatible compiler options must be disabled manually once **`/clr`** is added. For information on compiler options that aren't compatible with **`/clr`**, see [`/clr` restrictions](../build/reference/clr-restrictions.md). -### Precompiled Headers +### Precompiled headers -Precompiled headers are supported under **/clr**. However, if you only compile some of your CPP files with **/clr** (compiling the rest as native) some changes will be required because precompiled headers generated with **/clr** are not compatible with those generated without **/clr**. This incompatibility is due to the fact that **/clr** generates and requires metadata. Modules compiled **/clr** can therefore not use precompiled headers that don't include metadata, and non **/clr** modules can't use precompiled header files that do contain meta data. +Precompiled headers are supported under **`/clr`**. However, if you only compile some of your CPP files with **`/clr`** (compiling the rest as native), some changes are required. Precompiled headers generated with **`/clr`** aren't compatible with precompiled headers generated without **`/clr`**, because **`/clr`** generates and requires metadata. Modules compiled with **`/clr`** can't use precompiled headers that don't include metadata, and non-**`/clr`** modules can't use precompiled header files that do contain metadata. -The easiest way to compile a project where some modules are compiled **/clr** is to disable precompiled headers entirely. (In the project Property Pages dialog, open the C/C++ node, and select Precompiled Headers. Then change the Create/Use Precompiled Headers property to "Not Using Precompiled Headers".) +The easiest way to compile a project where some modules are compiled with **`/clr`** is to disable precompiled headers entirely. (In the project Property Pages dialog, open the **C/C++** node, and select **Precompiled Headers**. Then change the **Create/Use Precompiled Headers** property to "Not Using Precompiled Headers".) -However, particularly for large projects, precompiled headers provide much better compilation speed, so disabling this feature is not desirable. In this case it's best to configure the **/clr** and non **/clr** files to use separate precompiled headers. This can be done in one step by multi-selecting the modules to be compiled **/clr** using **Solution Explorer**, right-clicking on the group, and selecting Properties. Then change both the Create/Use PCH Through File and Precompiled Header File properties to use a different header file name and PCH file respectively. +However, particularly for large projects, precompiled headers provide much better compilation speed, so disabling this feature isn't desirable. In this case, it's best to configure the **`/clr`** and non-**`/clr`** files to use separate precompiled headers. You can configure them in one step: Multi-select the modules to compile with **`/clr`** by using **Solution Explorer**. Right-click on the group, and select **Properties**. Then, change both the **Create/Use PCH Through File** and **Precompiled Header File** properties to use a different header file name and PCH file, respectively. -## Fixing Errors +## Fix errors -Compiling with **/clr** may result in compiler, linker or runtime errors. This section discusses the most common problems. +Compiling your code with **`/clr`** may result in compiler, linker or runtime errors. This section discusses the most common problems. -### Metadata Merge +### Metadata merge -Differing versions of data types can cause the linker to fail because the metadata generated for the two types doesn't match. (This is usually caused when members of a type are conditionally defined, but the conditions are not the same for all CPP files that use the type.) In this case the linker fails, reporting only the symbol name and the name of the second OBJ file where the type was defined. It is often useful to rotate the order that OBJ files are sent to the linker to discover the location of the other version of the data type. +Differing versions of data types can cause the linker to fail because the metadata generated for the two types doesn't match. (Errors occur when you conditionally define members of a type, but the conditions aren't the same for all CPP files that use the type.) In this case, the linker fails, reporting only the symbol name and the name of the second OBJ file where the type was defined. You may find it's useful to rotate the order that OBJ files are sent to the linker, to discover the location of the other version of the data type. -### Loader Lock Deadlock +### Loader lock deadlock The "loader lock deadlock" can occur, but is deterministic and is detected and reported at runtime. See [Initialization of Mixed Assemblies](../dotnet/initialization-of-mixed-assemblies.md) for detailed background, guidance, and solutions. -### Data Exports +### Data exports -Exporting DLL data is error-prone, and not recommended. This is because the data section of a DLL is not guaranteed to be initialized until some managed portion of the DLL has been executed. Reference metadata with [#using Directive](../preprocessor/hash-using-directive-cpp.md). +Exporting DLL data is error-prone, and not recommended in **`/clr`** code. It's because initialization of the data section of a DLL isn't guaranteed until some managed portion of the DLL is executed. Reference metadata with [`#using` directives](../preprocessor/hash-using-directive-cpp.md). -### Type Visibility +### Type visibility -Native types are private by default. This can result in a native type not being visible outside the DLL. Resolve this error by adding **`public`** to these types. +Native types are **`private`** by default. A **`private`** native type isn't visible outside the DLL. Resolve this error by adding **`public`** to these types. -### Floating Point and Alignment Issues +### Floating point and alignment issues -`__controlfp` is not supported on the common language runtime (see [_control87, _controlfp, \__control87_2](../c-runtime-library/reference/control87-controlfp-control87-2.md) for more information). The CLR will also not respect [align](../cpp/align-cpp.md). +`__controlfp` isn't supported in the common language runtime. For more information, see [`_control87`, `_controlfp`, `__control87_2`](../c-runtime-library/reference/control87-controlfp-control87-2.md). The CLR also doesn't respect [`align`](../cpp/align-cpp.md). -### COM Initialization +### COM initialization -The Common Language Runtime initializes COM automatically when a module is initialized (when COM is initialized automatically it’s done so as MTA). As a result, explicitly initializing COM yields return codes indicating that COM is already initialized. Attempting to explicitly initialize COM with one threading model when the CLR has already initialized COM to another threading model can cause your application to fail. +The Common Language Runtime initializes COM automatically when a module is initialized (when COM is initialized automatically it's done so as MTA). As a result, explicitly initializing COM yields return codes indicating that COM is already initialized. Attempting to explicitly initialize COM with one threading model when the CLR has already initialized COM to another threading model can cause your application to fail. -The common language runtime starts COM as MTA by default; use [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](../build/reference/clrthreadattribute-set-clr-thread-attribute.md) to modify this. +The common language runtime starts COM as MTA by default; use [`/CLRTHREADATTRIBUTE` (Set CLR thread attribute)](../build/reference/clrthreadattribute-set-clr-thread-attribute.md) to modify the COM model. -### Performance Issues +### Performance issues -You may see decreased performance when native C++ methods generated to MSIL are called indirectly (virtual function calls or using function pointers). To learn more about this, see [Double Thunking](../dotnet/double-thunking-cpp.md). +You may see decreased performance when native C++ methods generated to MSIL are called indirectly (through virtual function calls or by using function pointers). To learn more, see [Double Thunking](../dotnet/double-thunking-cpp.md). -When moving from native to MSIL, you will notice an increase in the size of your working set. This is because the common language runtime provides many features to ensure that programs run correctly. If your **/clr** application is not running correctly, you may want to enable C4793 (off by default), see [Compiler Warning (level 1 and 3) C4793](../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md) for more information. +When you move from native to MSIL, you'll notice an increase in the size of your working set. This increase happens because the common language runtime provides many features to ensure that programs run correctly. If your **`/clr`** application isn't running correctly, you may want to enable off-by-default [Compiler Warning (level 1 and 3) C4793](../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md). -### Program Crashes on Shutdown +### Program crashes on shutdown -In some cases, the CLR can shutdown before your managed code is finished running. Using `std::set_terminate` and `SIGTERM` can cause this. See [signal Constants](../c-runtime-library/signal-constants.md) and [set_terminate](../c-runtime-library/abnormal-termination.md) for more information. +In some cases, the CLR can shut down before your managed code is finished running. Use of `std::set_terminate` and `SIGTERM` can cause the shutdown. For more information, see [`signal` constants](../c-runtime-library/signal-constants.md) and [`set_terminate`](../c-runtime-library/abnormal-termination.md). -## Using New Visual C++ Features +## Using new Visual C++ features -After your application compiles, links, and runs, you can begin using .NET features in any module compiled with **/clr**. For more information, see [Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md). +After your application compiles, links, and runs, you can begin using .NET features in any module compiled with **`/clr`**. For more information, see [Component Extensions for Runtime Platforms](../extensions/component-extensions-for-runtime-platforms.md). -For information on .NET programming in Visual C++ see: +For more information on .NET programming in Visual C++, see: - [.NET Programming with C++/CLI (Visual C++)](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md) diff --git a/docs/dotnet/how-to-sink-windows-forms-events-from-native-cpp-classes.md b/docs/dotnet/how-to-sink-windows-forms-events-from-native-cpp-classes.md index 07a8fd3dcc9..71f5f0f5e8c 100644 --- a/docs/dotnet/how-to-sink-windows-forms-events-from-native-cpp-classes.md +++ b/docs/dotnet/how-to-sink-windows-forms-events-from-native-cpp-classes.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How to: Sink Windows Forms Events from Native C++ Classes" title: "How to: Sink Windows Forms Events from Native C++ Classes" +description: "Learn more about: How to: Sink Windows Forms Events from Native C++ Classes" +ms.date: 11/04/2016 ms.custom: "get-started-article" -ms.date: "11/04/2016" helpviewer_keywords: ["event handling, managed/native interop", "event handling, sinking .NET in C++", "event handling, .NET/native interop", "event handling, Windows Forms in C++"] -ms.assetid: 6e30ddee-d058-4c8d-9956-2a43d86f19d5 --- # How to: Sink Windows Forms Events from Native C++ Classes @@ -20,7 +19,7 @@ This sample continues the work you did in [How to: Do DDX/DDV Data Binding with Now, you will associate your MFC control (`m_MyControl`) with a managed event handler delegate called `OnClick` for the managed event. -### To attach the OnClick event handler: +### To attach the OnClick event handler 1. Add the following code to the implementation of BOOL CMFC01Dlg::OnInitDialog: 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 14f17299db7..6bdeba25b06 100644 --- a/docs/dotnet/how-to-use-arrays-in-cpp-cli.md +++ b/docs/dotnet/how-to-use-arrays-in-cpp-cli.md @@ -221,7 +221,7 @@ public: }; int main() { - // Aggregate initialize a multidimension managed array. + // Aggregate initialize a multidimensional managed array. array^ gc1 = gcnew array{ {"one", "two"}, {"three", "four"} }; array^ gc2 = { {"one", "two"}, {"three", "four"} }; diff --git a/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md b/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md index 3a9ba0614c7..a63bc2182fe 100644 --- a/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md +++ b/docs/dotnet/how-to-use-tracking-references-in-cpp-cli.md @@ -286,9 +286,9 @@ Boxed new copy V: 1 Original V: 4, Reference to handle of originally boxed V: 1 ``` -## Template functions that take native, value, or reference parameters +## Function templates that take native, value, or reference parameters -By using a tracking reference in the signature of a template function, you ensure that the function can be called by a parameter whose type is native, CLR value, or CLR reference. +By using a tracking reference in the signature of a function template, you ensure that the function can be called by a parameter whose type is native, CLR value, or CLR reference. ```cpp // tracking_reference_template.cpp @@ -297,7 +297,7 @@ using namespace System; class Temp { public: - // template functions + // function templates template static int f1(T% tt) { // works for object in any location Console::WriteLine("T %"); diff --git a/docs/dotnet/list-stl-clr.md b/docs/dotnet/list-stl-clr.md index 7069b4797ca..fff82c19fd8 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/lock-class.md b/docs/dotnet/lock-class.md index 62bfe76335f..98e44d2673f 100644 --- a/docs/dotnet/lock-class.md +++ b/docs/dotnet/lock-class.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: lock Class" title: "lock Class" -ms.date: "01/16/2019" +description: "Learn more about: lock Class" +ms.date: 01/16/2019 ms.topic: "reference" f1_keywords: ["msclr::lock::lock", "msclr::lock::is_locked", "msclr::lock.is_locked", "msclr::lock::acquire", "msclr::lock::try_acquire", "msclr::lock::release", "msclr::lock::operator==", "msclr::lock::operator!="] helpviewer_keywords: ["msclr::lock class"] -ms.assetid: 5123edd9-6aed-497d-9a0b-f4b6d6c0d666 --- # lock Class @@ -45,7 +44,7 @@ Internally, the lock class uses to synchronize a |Name|Description| |---------|-----------| -|[lock::operator bool](#operator-bool)|Operator for using `lock` in a conditional expression.| +|[lock::operator bool](#operator-bool)|Operator for using `lock` in a conditional expression.| |[lock::operator==](#operator-equality)|Equality operator.| |[lock::operator!=](#operator-inequality)|Inequality operator.| diff --git a/docs/dotnet/map-stl-clr.md b/docs/dotnet/map-stl-clr.md index ca5931c2442..8ed6171113c 100644 --- a/docs/dotnet/map-stl-clr.md +++ b/docs/dotnet/map-stl-clr.md @@ -7,7 +7,7 @@ f1_keywords: ["cliext::map", "cliext::map::begin", "cliext::map::clear", "cliext helpviewer_keywords: [" header [STL/CLR]", "map class [STL/CLR]", " header [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "map member [STL/CLR]", "mapped_type member [STL/CLR]", "operator= member [STL/CLR]", "operator member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]", "operator!= (map) member [STL/CLR]", "operator< (map) member [STL/CLR]", "operator<= (map) member [STL/CLR]", "operator== (map) member [STL/CLR]", "operator> (map) member [STL/CLR]", "operator>= (map) member [STL/CLR]"] ms.assetid: 8b0a7764-b5e4-4175-a802-82b72eb8662a --- -# map (STL/CLR) +# `map` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `map` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +17,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as *Key* unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as *Mapped* unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as *`Mapped`* unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -41,93 +41,93 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[map::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[map::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[map::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[map::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[map::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[map::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[map::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[map::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[map::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[map::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[map::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[map::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[map::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[map::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[map::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[map::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[map::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[map::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[map::clear (STL/CLR)](#clear)|Removes all elements.| -|[map::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[map::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[map::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[map::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[map::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[map::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[map::insert (STL/CLR)](#insert)|Adds elements.| -|[map::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[map::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[map::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[map::map (STL/CLR)](#map)|Constructs a container object.| -|[map::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[map::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[map::size (STL/CLR)](#size)|Counts the number of elements.| -|[map::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[map::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[map::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[map::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[map::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[map::operator(STL/CLR)](#op)|Maps a key to its associated mapped value.| -|[operator!= (map) (STL/CLR)](#op_neq)|Determines if a `map` object is not equal to another `map` object.| -|[operator< (map) (STL/CLR)](#op_lt)|Determines if a `map` object is less than another `map` object.| -|[operator<= (map) (STL/CLR)](#op_lteq)|Determines if a `map` object is less than or equal to another `map` object.| -|[operator== (map) (STL/CLR)](#op_eq)|Determines if a `map` object is equal to another `map` object.| -|[operator> (map) (STL/CLR)](#op_gt)|Determines if a `map` object is greater than another `map` object.| -|[operator>= (map) (STL/CLR)](#op_gteq)|Determines if a `map` object is greater than or equal to another `map` object.| +| Type definition | Description | +|---|---| +| [`map::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`map::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`map::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`map::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`map::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`map::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`map::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`map::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`map::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`map::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`map::key_type`](#key_type) | The type of an ordering key. | +| [`map::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`map::reference`](#reference) | The type of a reference to an element. | +| [`map::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`map::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`map::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`map::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`map::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`map::clear`](#clear) | Removes all elements. | +| [`map::count`](#count) | Counts elements matching a specified key. | +| [`map::empty`](#empty) | Tests whether no elements are present. | +| [`map::end`](#end) | Designates the end of the controlled sequence. | +| [`map::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`map::erase`](#erase) | Removes elements at specified positions. | +| [`map::find`](#find) | Finds an element that matches a specified key. | +| [`map::insert`](#insert) | Adds elements. | +| [`map::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`map::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`map::make_value`](#make_value) | Constructs a value object. | +| [`map::map`](#map) | Constructs a container object. | +| [`map::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`map::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`map::size`](#size) | Counts the number of elements. | +| [`map::swap`](#swap) | Swaps the contents of two containers. | +| [`map::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`map::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`map::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`map::operator=`](#op_as) | Replaces the controlled sequence. | +| [`map::operator[]`](#op) | Maps a key to its associated mapped value. | +| [`operator!=` (map)](#op_neq) | Determines if a `map` object isn't equal to another `map` object. | +| [`operator<` (map)](#op_lt) | Determines if a `map` object is less than another `map` object. | +| [`operator<=` (map)](#op_lteq) | Determines if a `map` object is less than or equal to another `map` object. | +| [`operator==` (map)](#op_eq) | Determines if a `map` object is equal to another `map` object. | +| [`operator>` (map)](#op_gt) | Determines if a `map` object is greater than another `map` object. | +| [`operator>=` (map)](#op_gteq) | Determines if a `map` object is greater than or equal to another `map` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -||Maintain group of {key, value} pairs.| -|ITree|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| | Maintain group of {key, value} pairs. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [map::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the map; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [map::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`map::key_compare`](#key_compare). You can specify the stored delegate object when you construct the map; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`map::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [map::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`map::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -137,21 +137,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map](../dotnet/map-stl-clr.md), an object of template class `map` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map](../dotnet/map-stl-clr.md), an object of template class `map` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A map supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [map::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a map iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `map` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `map` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a map element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `map` element directly given its numerical position. That requires a random-access iterator. -A map iterator stores a handle to its associated map node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A map iterator remains valid so long as its associated map node is associated with some map. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `map` iterator stores a handle to its associated `map` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `map` iterator remains valid so long as its associated `map` node is associated with some map. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## map::begin (STL/CLR) +## `map::begin` Designates the beginning of the controlled sequence. @@ -202,7 +202,7 @@ int main() *++begin() = [b 2] ``` -## map::clear (STL/CLR) +## `map::clear` Removes all elements. @@ -214,7 +214,7 @@ void clear(); ### Remarks -The member function effectively calls [map::erase (STL/CLR)](#erase)`(` [map::begin (STL/CLR)](#begin)`(),` [map::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -260,7 +260,7 @@ size() = 0 size() = 0 ``` -## map::const_iterator (STL/CLR) +## `map::const_iterator` The type of a constant iterator for the controlled sequence. @@ -302,7 +302,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::const_reference (STL/CLR) +## `map::const_reference` The type of a constant reference to an element. @@ -347,9 +347,9 @@ int main() [a 1] [b 2] [c 3] ``` -## map::const_reverse_iterator (STL/CLR) +## `map::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -389,7 +389,7 @@ int main() [c 3] [b 2] [a 1] ``` -## map::count (STL/CLR) +## `map::count` Finds the number of elements matching a specified key. @@ -401,12 +401,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -442,7 +442,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## map::difference_type (STL/CLR) +## `map::difference_type` The types of a signed distance between two elements. @@ -497,7 +497,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## map::empty (STL/CLR) +## `map::empty` Tests whether no elements are present. @@ -509,7 +509,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [map::size (STL/CLR)](#size)`() == 0`. You use it to test whether the map is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `map` is empty. ### Example @@ -549,7 +549,7 @@ size() = 0 empty() = True ``` -## map::end (STL/CLR) +## `map::end` Designates the end of the controlled sequence. @@ -561,7 +561,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -596,7 +596,7 @@ int main() } ``` -## map::equal_range (STL/CLR) +## `map::equal_range` Finds range that matches a specified key. @@ -608,12 +608,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [map::lower_bound (STL/CLR)](#lower_bound)`(key),` [map::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -657,7 +657,7 @@ equal_range(L'x') empty = True [b 2] ``` -## map::erase (STL/CLR) +## `map::erase` Removes elements at specified positions. @@ -671,25 +671,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [map::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -750,7 +750,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## map::find (STL/CLR) +## `map::find` Finds an element that matches a specified key. @@ -762,12 +762,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [map::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -809,7 +809,7 @@ find b = [b 2] find C = False ``` -## map::generic_container (STL/CLR) +## `map::generic_container` The type of the generic interface for the container. @@ -873,7 +873,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## map::generic_iterator (STL/CLR) +## `map::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -930,7 +930,7 @@ int main() [a 1] ``` -## map::generic_reverse_iterator (STL/CLR) +## `map::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -986,7 +986,7 @@ int main() [c 3] ``` -## map::generic_value (STL/CLR) +## `map::generic_value` The type of an element for use with the generic interface for the container. @@ -1040,7 +1040,7 @@ int main() [a 1] ``` -## map::insert (STL/CLR) +## `map::insert` Adds elements. @@ -1056,34 +1056,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function endeavors to insert an element with value *val*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. +The first member function endeavors to insert an element with value *`val`*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1160,7 +1160,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [c 3] [x 24] [y 25] ``` -## map::iterator (STL/CLR) +## `map::iterator` The type of an iterator for the controlled sequence. @@ -1202,7 +1202,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::key_comp (STL/CLR) +## `map::key_comp` Copies the ordering delegate for two keys. @@ -1261,7 +1261,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## map::key_compare (STL/CLR) +## `map::key_compare` The ordering delegate for two keys. @@ -1321,7 +1321,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## map::key_type (STL/CLR) +## `map::key_type` The type of an ordering key. @@ -1333,7 +1333,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1366,7 +1366,7 @@ int main() a b c ``` -## map::lower_bound (STL/CLR) +## `map::lower_bound` Finds beginning of range that matches a specified key. @@ -1378,12 +1378,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1425,7 +1425,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## map::make_value (STL/CLR) +## `map::make_value` Constructs a value object. @@ -1437,15 +1437,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1474,7 +1474,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::map (STL/CLR) +## `map::map` Constructs a container object. @@ -1497,16 +1497,16 @@ map(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1521,19 +1521,19 @@ The constructor: `explicit map(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `map(map% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the map object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `map` object *`right`*, with the default ordering predicate. The constructor: `map(map^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the map object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `map` object *`right`*, with the default ordering predicate. The constructor: @@ -1545,19 +1545,19 @@ The constructor: `template map(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `map(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `map(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1647,7 +1647,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## map::mapped_type (STL/CLR) +## `map::mapped_type` The type of a mapped value associated with each key. @@ -1659,7 +1659,7 @@ typedef Mapped mapped_type; ### Remarks -The type is a synonym for the template parameter *Mapped*. +The type is a synonym for the template parameter *`Mapped`*. ### Example @@ -1692,7 +1692,7 @@ int main() 1 2 3 ``` -## map::operator= (STL/CLR) +## `map::operator=` Replaces the controlled sequence. @@ -1704,12 +1704,12 @@ map% operator=(map% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1747,7 +1747,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::operator(STL/CLR) +## `map::operator[]` Maps a key to its associated mapped value. @@ -1759,12 +1759,12 @@ mapped_type operator[](key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member functions endeavors to find an element with equivalent ordering to *key*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. +The member functions endeavors to find an element with equivalent ordering to *`key`*. If it finds one, it returns the associated mapped value; otherwise, it inserts `value_type(key, mapped_type())` and returns the associated (default) mapped value. You use it to look up a mapped value given its associated key, or to ensure that an entry exists for the key if none is found. ### Example @@ -1814,7 +1814,7 @@ c1[b] = 2 [A 10] [a 1] [b 2] [c 13] ``` -## map::rbegin (STL/CLR) +## `map::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1865,7 +1865,7 @@ int main() *++rbegin() = [b 2] ``` -## map::reference (STL/CLR) +## `map::reference` The type of a reference to an element. @@ -1910,7 +1910,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::rend (STL/CLR) +## `map::rend` Designates the end of the reversed controlled sequence. @@ -1963,7 +1963,7 @@ int main() *--rend() = [a 1] ``` -## map::reverse_iterator (STL/CLR) +## `map::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -2005,7 +2005,7 @@ int main() [c 3] [b 2] [a 1] ``` -## map::size (STL/CLR) +## `map::size` Counts the number of elements. @@ -2017,7 +2017,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [map::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -2057,9 +2057,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## map::size_type (STL/CLR) +## `map::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2105,7 +2105,7 @@ int main() end()-begin() = 3 ``` -## map::swap (STL/CLR) +## `map::swap` Swaps the contents of two containers. @@ -2117,12 +2117,12 @@ void swap(map% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2173,7 +2173,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::to_array (STL/CLR) +## `map::to_array` Copies the controlled sequence to a new array. @@ -2223,7 +2223,7 @@ int main() [a 1] [b 2] [c 3] ``` -## map::upper_bound (STL/CLR) +## `map::upper_bound` Finds end of range that matches a specified key. @@ -2235,12 +2235,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [map::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2282,7 +2282,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## map::value_comp (STL/CLR) +## `map::value_comp` Copies the ordering delegate for two element values. @@ -2329,7 +2329,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## map::value_compare (STL/CLR) +## `map::value_compare` The ordering delegate for two element values. @@ -2377,7 +2377,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## map::value_type (STL/CLR) +## `map::value_type` The type of an element. @@ -2436,15 +2436,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two maps are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two maps are compared element by element. ### Example @@ -2492,7 +2492,7 @@ int main() [a b c] != [a b d] is True ``` -## `operator<` (map) (STL/CLR) +## `operator<` (map) List less than comparison. @@ -2507,15 +2507,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two maps are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. Use this operator to test whether *`left`* is ordered before *`right`* when the two maps are compared element by element. ### Example @@ -2563,7 +2563,7 @@ int main() [a b c] < [a b d] is True ``` -## `operator<=` (map) (STL/CLR) +## `operator<=` (map) List less than or equal comparison. @@ -2578,15 +2578,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two maps are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two maps are compared element by element. ### Example @@ -2634,7 +2634,7 @@ int main() [a b d] <= [a b c] is False ``` -## operator== (map) (STL/CLR) +## `operator==` (map) List equal comparison. @@ -2649,15 +2649,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two maps are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two maps are compared element by element. ### Example @@ -2705,7 +2705,7 @@ int main() [a b c] == [a b d] is False ``` -## `operator>` (map) (STL/CLR) +## `operator>` (map) List greater than comparison. @@ -2720,15 +2720,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two maps are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two maps are compared element by element. ### Example @@ -2776,7 +2776,7 @@ int main() [a b d] > [a b c] is True ``` -## `operator>=` (map) (STL/CLR) +## `operator>=` (map) List greater than or equal comparison. @@ -2791,15 +2791,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left` `<` `right)`. You use it to test whether *left* is not ordered before *right* when the two maps are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two maps are compared element by element. ### Example diff --git a/docs/dotnet/multimap-stl-clr.md b/docs/dotnet/multimap-stl-clr.md index c3397921226..16acca22db6 100644 --- a/docs/dotnet/multimap-stl-clr.md +++ b/docs/dotnet/multimap-stl-clr.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: multimap (STL/CLR)" title: "multimap (STL/CLR)" -ms.date: "11/04/2016" +description: "Learn more about: multimap (STL/CLR)" +ms.date: 11/04/2016 ms.topic: "reference" f1_keywords: ["cliext::multimap", "cliext::multimap::begin", "cliext::multimap::clear", "cliext::multimap::const_iterator", "cliext::multimap::const_reference", "cliext::multimap::const_reverse_iterator", "cliext::multimap::count", "cliext::multimap::difference_type", "cliext::multimap::empty", "cliext::multimap::end", "cliext::multimap::equal_range", "cliext::multimap::erase", "cliext::multimap::find", "cliext::multimap::generic_container", "cliext::multimap::generic_iterator", "cliext::multimap::generic_reverse_iterator", "cliext::multimap::generic_value", "cliext::multimap::insert", "cliext::multimap::iterator", "cliext::multimap::key_comp", "cliext::multimap::key_compare", "cliext::multimap::key_type", "cliext::multimap::lower_bound", "cliext::multimap::make_value", "cliext::multimap::mapped_type", "cliext::multimap::multimap", "cliext::multimap::operator=", "cliext::multimap::rbegin", "cliext::multimap::reference", "cliext::multimap::rend", "cliext::multimap::reverse_iterator", "cliext::multimap::size", "cliext::multimap::size_type", "cliext::multimap::swap", "cliext::multimap::to_array", "cliext::multimap::upper_bound", "cliext::multimap::value_comp", "cliext::multimap::value_compare", "cliext::multimap::value_type", "cliext::mutlimap::operator!=", "cliext::mutlimap::operator<", "cliext::mutlimap::operator<=", "cliext::mutlimap::operator==", "cliext::mutlimap::operator>", "cliext::mutlimap::operator>="] helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "multimap class [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "mapped_type member [STL/CLR]", "multimap member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]"] -ms.assetid: 3dfe329d-a078-462a-b050-7999ce6110ad --- -# multimap (STL/CLR) +# `multimap` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `multimap` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. An element consists of a key, for ordering the sequence, and a mapped value, which goes along for the ride. @@ -17,9 +16,9 @@ In the description below, `GValue` is the same as: where: -`GKey` is the same as *Key* unless the latter is a ref type, in which case it is `Key^` +`GKey` is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^` -`GMapped` is the same as *Mapped* unless the latter is a ref type, in which case it is `Mapped^` +`GMapped` is the same as *`Mapped`* unless the latter is a ref type, in which case it's `Mapped^` ## Syntax @@ -40,91 +39,91 @@ template +*`Key`*\ The type of the key component of an element in the controlled sequence. -*Mapped*
-The type of the additional component of an element in the controlled sequence. +*`Mapped`*\ +The type of the other component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[multimap::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[multimap::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[multimap::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[multimap::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[multimap::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[multimap::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[multimap::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[multimap::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[multimap::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[multimap::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[multimap::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[multimap::mapped_type (STL/CLR)](#mapped_type)|The type of the mapped value associated with each key.| -|[multimap::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[multimap::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[multimap::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[multimap::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[multimap::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[multimap::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[multimap::clear (STL/CLR)](#clear)|Removes all elements.| -|[multimap::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[multimap::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[multimap::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[multimap::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[multimap::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[multimap::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[multimap::insert (STL/CLR)](#insert)|Adds elements.| -|[multimap::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[multimap::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[multimap::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[multimap::multimap (STL/CLR)](#multimap)|Constructs a container object.| -|[multimap::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[multimap::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[multimap::size (STL/CLR)](#size)|Counts the number of elements.| -|[multimap::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[multimap::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[multimap::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[multimap::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[multimap::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (multimap) (STL/CLR)](#op_neq)|Determines if a `multimap` object is not equal to another `multimap` object.| -|[operator< (multimap) (STL/CLR)](#op_lt)|Determines if a `multimap` object is less than another `multimap` object.| -|[operator<= (multimap) (STL/CLR)](#op_lteq)|Determines if a `multimap` object is less than or equal to another `multimap` object.| -|[operator== (multimap) (STL/CLR)](#op_eq)|Determines if a `multimap` object is equal to another `multimap` object.| -|[operator> (multimap) (STL/CLR)](#op_gt)|Determines if a `multimap` object is greater than another `multimap` object.| -|[operator>= (multimap) (STL/CLR)](#op_gteq)|Determines if a `multimap` object is greater than or equal to another `multimap` object.| +| Type definition | Description | +|---|---| +| [`multimap::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`multimap::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`multimap::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`multimap::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`multimap::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`multimap::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`multimap::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`multimap::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`multimap::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`multimap::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`multimap::key_type`](#key_type) | The type of an ordering key. | +| [`multimap::mapped_type`](#mapped_type) | The type of the mapped value associated with each key. | +| [`multimap::reference`](#reference) | The type of a reference to an element. | +| [`multimap::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`multimap::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`multimap::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`multimap::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`multimap::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`multimap::clear`](#clear) | Removes all elements. | +| [`multimap::count`](#count) | Counts elements matching a specified key. | +| [`multimap::empty`](#empty) | Tests whether no elements are present. | +| [`multimap::end`](#end) | Designates the end of the controlled sequence. | +| [`multimap::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`multimap::erase`](#erase) | Removes elements at specified positions. | +| [`multimap::find`](#find) | Finds an element that matches a specified key. | +| [`multimap::insert`](#insert) | Adds elements. | +| [`multimap::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`multimap::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`multimap::make_value`](#make_value) | Constructs a value object. | +| [`multimap::multimap`](#multimap) | Constructs a container object. | +| [`multimap::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`multimap::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`multimap::size`](#size) | Counts the number of elements. | +| [`multimap::swap`](#swap) | Swaps the contents of two containers. | +| [`multimap::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`multimap::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`multimap::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`multimap::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (multimap)](#op_neq) | Determines if a `multimap` object isn't equal to another `multimap` object. | +| [`operator<` (multimap)](#op_lt) | Determines if a `multimap` object is less than another `multimap` object. | +| [`operator<=` (multimap)](#op_lteq) | Determines if a `multimap` object is less than or equal to another `multimap` object. | +| [`operator==` (multimap)](#op_eq) | Determines if a `multimap` object is equal to another `multimap` object. | +| [`operator>` (multimap)](#op_gt) | Determines if a `multimap` object is greater than another `multimap` object. | +| [`operator>=` (multimap)](#op_gteq) | Determines if a `multimap` object is greater than or equal to another `multimap` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|ITree\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [multimap::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the multimap; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [multimap::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`multimap::key_compare`](#key_compare). You can specify the stored delegate object when you construct the multimap; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`multimap::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [multimap::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`multimap::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -134,21 +133,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map (STL/CLR)](../dotnet/map-stl-clr.md), an object of template class `multimap` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [map (STL/CLR)](../dotnet/map-stl-clr.md), an object of template class `multimap` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element contains a separate key and a mapped value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A multimap supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [multimap::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a multimap iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `multimap` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `multimap` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a multimap element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `multimap` element directly given its numerical position. That requires a random-access iterator. -A multimap iterator stores a handle to its associated multimap node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A multimap iterator remains valid so long as its associated multimap node is associated with some multimap. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `multimap` iterator stores a handle to its associated `multimap` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `multimap` iterator remains valid so long as its associated `multimap` node is associated with some multimap. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## multimap::begin (STL/CLR) +## `multimap::begin` Designates the beginning of the controlled sequence. @@ -199,7 +198,7 @@ int main() *++begin() = [b 2] ``` -## multimap::clear (STL/CLR) +## `multimap::clear` Removes all elements. @@ -211,7 +210,7 @@ void clear(); ### Remarks -The member function effectively calls [multimap::erase (STL/CLR)](#erase)`(` [multimap::begin (STL/CLR)](#begin)`(),` [multimap::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -257,7 +256,7 @@ size() = 0 size() = 0 ``` -## multimap::const_iterator (STL/CLR) +## `multimap::const_iterator` The type of a constant iterator for the controlled sequence. @@ -299,7 +298,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::const_reference (STL/CLR) +## `multimap::const_reference` The type of a constant reference to an element. @@ -344,7 +343,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::const_reverse_iterator (STL/CLR) +## `multimap::const_reverse_iterator` The type of a constant reverse iterator for the controlled sequence. @@ -386,7 +385,7 @@ int main() [c 3] [b 2] [a 1] ``` -## multimap::count (STL/CLR) +## `multimap::count` Finds the number of elements matching a specified key. @@ -398,12 +397,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -439,7 +438,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## multimap::difference_type (STL/CLR) +## `multimap::difference_type` The types of a signed distance between two elements. @@ -494,7 +493,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## multimap::empty (STL/CLR) +## `multimap::empty` Tests whether no elements are present. @@ -506,7 +505,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [multimap::size (STL/CLR)](#size)`() == 0`. You use it to test whether the multimap is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `multimap` is empty. ### Example @@ -546,7 +545,7 @@ size() = 0 empty() = True ``` -## multimap::end (STL/CLR) +## `multimap::end` Designates the end of the controlled sequence. @@ -558,7 +557,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -599,24 +598,24 @@ int main() *--end() = [c 3] ``` -## multimap::equal_range (STL/CLR) +## `multimap::equal_range` Finds range that matches a specified key. ### Syntax ```cpp -pair_iter_iter equal_range(key_type _Keyval); +pair_iter_iter equal_range(key_type key); ``` #### Parameters -*_Keyval*
+*`key`*
Key value to search for. ### Remarks -The method returns a pair of iterators `-` [multimap::lower_bound (STL/CLR)](#lower_bound)`(_Keyval),` [multimap::upper_bound (STL/CLR)](#upper_bound)`(_Keyval)`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The method returns a pair of iterators, `pair_iter_iter(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -660,7 +659,7 @@ equal_range(L'x') empty = True [b 2] ``` -## multimap::erase (STL/CLR) +## `multimap::erase` Removes elements at specified positions. @@ -674,25 +673,25 @@ bool erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [multimap::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -753,7 +752,7 @@ erase(L'x') = 0 erase(L'e') = 1 ``` -## multimap::find (STL/CLR) +## `multimap::find` Finds an element that matches a specified key. @@ -765,12 +764,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [multimap::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -812,7 +811,7 @@ find b = [b 2] find C = False ``` -## multimap::generic_container (STL/CLR) +## `multimap::generic_container` The type of the generic interface for the container. @@ -876,7 +875,7 @@ int main() [a 1] [b 2] [c 3] [d 4] [e 5] ``` -## multimap::generic_iterator (STL/CLR) +## `multimap::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -933,7 +932,7 @@ int main() [a 1] ``` -## multimap::generic_reverse_iterator (STL/CLR) +## `multimap::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -989,7 +988,7 @@ int main() [c 3] ``` -## multimap::generic_value (STL/CLR) +## `multimap::generic_value` The type of an element for use with the generic interface for the container. @@ -1043,7 +1042,7 @@ int main() [a 1] ``` -## multimap::insert (STL/CLR) +## `multimap::insert` Adds elements. @@ -1059,34 +1058,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1161,7 +1160,7 @@ insert(begin(), [L'y' 25]) = [y 25] [a 1] [b 2] [b 2] [c 3] [x 24] [y 25] ``` -## multimap::iterator (STL/CLR) +## `multimap::iterator` The type of an iterator for the controlled sequence. @@ -1203,7 +1202,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::key_comp (STL/CLR) +## `multimap::key_comp` Copies the ordering delegate for two keys. @@ -1262,7 +1261,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multimap::key_compare (STL/CLR) +## `multimap::key_compare` The ordering delegate for two keys. @@ -1322,7 +1321,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multimap::key_type (STL/CLR) +## `multimap::key_type` The type of an ordering key. @@ -1334,7 +1333,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1367,7 +1366,7 @@ int main() a b c ``` -## multimap::lower_bound (STL/CLR) +## `multimap::lower_bound` Finds beginning of range that matches a specified key. @@ -1379,12 +1378,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1426,7 +1425,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = [b 2] ``` -## multimap::make_value (STL/CLR) +## `multimap::make_value` Constructs a value object. @@ -1438,15 +1437,15 @@ static value_type make_value(key_type key, mapped_type mapped); #### Parameters -*key*
+*`key`*\ Key value to use. -*mapped*
+*`mapped`*\ Mapped value to search for. ### Remarks -The member function returns a `value_type` object whose key is *key* and whose mapped value is *mapped*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`* and whose mapped value is *`mapped`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1475,7 +1474,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::mapped_type (STL/CLR) +## `multimap::mapped_type` The type of a mapped value associated with each key. @@ -1487,7 +1486,7 @@ typedef Mapped mapped_type; ### Remarks -The type is a synonym for the template parameter *Mapped*. +The type is a synonym for the template parameter *`Mapped`*. ### Example @@ -1520,7 +1519,7 @@ int main() 1 2 3 ``` -## multimap::multimap (STL/CLR) +## `multimap::multimap` Constructs a container object. @@ -1543,16 +1542,16 @@ multimap(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1567,19 +1566,19 @@ The constructor: `explicit multimap(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `multimap(multimap% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multimap object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multimap` object *`right`*, with the default ordering predicate. The constructor: `multimap(multimap^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multimap object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multimap` object *`right`*, with the default ordering predicate. The constructor: @@ -1591,19 +1590,19 @@ The constructor: `template multimap(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `multimap(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `multimap(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1693,7 +1692,7 @@ size() = 0 [a 1] [b 2] [c 3] ``` -## multimap::operator= (STL/CLR) +## `multimap::operator=` Replaces the controlled sequence. @@ -1705,12 +1704,12 @@ multimap% operator=(multimap% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1748,7 +1747,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::rbegin (STL/CLR) +## `multimap::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1799,7 +1798,7 @@ int main() *++rbegin() = [b 2] ``` -## multimap::reference (STL/CLR) +## `multimap::reference` The type of a reference to an element. @@ -1844,7 +1843,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::rend (STL/CLR) +## `multimap::rend` Designates the end of the reversed controlled sequence. @@ -1897,7 +1896,7 @@ int main() *--rend() = [a 1] ``` -## multimap::reverse_iterator (STL/CLR) +## `multimap::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -1939,7 +1938,7 @@ int main() [c 3] [b 2] [a 1] ``` -## multimap::size (STL/CLR) +## `multimap::size` Counts the number of elements. @@ -1951,7 +1950,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [multimap::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -1991,9 +1990,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## multimap::size_type (STL/CLR) +## `multimap::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -2039,7 +2038,7 @@ int main() end()-begin() = 3 ``` -## multimap::swap (STL/CLR) +## `multimap::swap` Swaps the contents of two containers. @@ -2051,12 +2050,12 @@ void swap(multimap% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2107,7 +2106,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::to_array (STL/CLR) +## `multimap::to_array` Copies the controlled sequence to a new array. @@ -2157,7 +2156,7 @@ int main() [a 1] [b 2] [c 3] ``` -## multimap::upper_bound (STL/CLR) +## `multimap::upper_bound` Finds end of range that matches a specified key. @@ -2169,12 +2168,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [multimap::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2216,7 +2215,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = [c 3] ``` -## multimap::value_comp (STL/CLR) +## `multimap::value_comp` Copies the ordering delegate for two element values. @@ -2263,7 +2262,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## multimap::value_compare (STL/CLR) +## `multimap::value_compare` The ordering delegate for two element values. @@ -2311,7 +2310,7 @@ compare([L'a', 1], [L'b', 2]) = True compare([L'b', 2], [L'a', 1]) = False ``` -## multimap::value_type (STL/CLR) +## `multimap::value_type` The type of an element. @@ -2355,7 +2354,7 @@ int main() [a 1] [b 2] [c 3] ``` -## operator!= (multimap) (STL/CLR) +## `operator!=` (multimap) List not equal comparison. @@ -2370,15 +2369,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two multimaps are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two multimaps are compared element by element. ### Example @@ -2426,7 +2425,7 @@ int main() [a b c] != [a b d] is True ``` -## `operator<` (multimap) (STL/CLR) +## `operator<` (multimap) List less than comparison. @@ -2441,15 +2440,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two multimaps are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two multimaps are compared element by element. ### Example @@ -2497,7 +2496,7 @@ int main() [a b c] < [a b d] is True ``` -## `operator<=` (multimap) (STL/CLR) +## `operator<=` (multimap) List less than or equal comparison. @@ -2512,15 +2511,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two multimaps are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two multimaps are compared element by element. ### Example @@ -2568,7 +2567,7 @@ int main() [a b d] <= [a b c] is False ``` -## operator== (multimap) (STL/CLR) +## `operator==` (multimap) List equal comparison. @@ -2583,15 +2582,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two multimaps are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two multimaps are compared element by element. ### Example @@ -2639,7 +2638,7 @@ int main() [a b c] == [a b d] is False ``` -## `operator>` (multimap) (STL/CLR) +## `operator>` (multimap) List greater than comparison. @@ -2654,15 +2653,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two multimaps are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two multimaps are compared element by element. ### Example @@ -2710,7 +2709,7 @@ int main() [a b d] > [a b c] is True ``` -## `operator>=` (multimap) (STL/CLR) +## `operator>=` (multimap) List greater than or equal comparison. @@ -2725,15 +2724,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left` `<` `right)`. You use it to test whether *left* is not ordered before *right* when the two multimaps are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two multimaps are compared element by element. ### Example diff --git a/docs/dotnet/multiset-stl-clr.md b/docs/dotnet/multiset-stl-clr.md index 33b1ab9d4af..bea1d2aad34 100644 --- a/docs/dotnet/multiset-stl-clr.md +++ b/docs/dotnet/multiset-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::multiset", "cliext::multiset::begin", "cliext::multiset:: helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "multiset class [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "map member [STL/CLR]", "mapped_type member [STL/CLR]", "operator= member [STL/CLR]", "operator member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]"] ms.assetid: 7c46e2b4-cd88-49b7-a9e6-63ad5ae7feb5 --- -# multiset (STL/CLR) +# `multiset` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `multiset` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,87 +31,87 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[multiset::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[multiset::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[multiset::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[multiset::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[multiset::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[multiset::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[multiset::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[multiset::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[multiset::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[multiset::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[multiset::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[multiset::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[multiset::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[multiset::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[multiset::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[multiset::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[multiset::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[multiset::clear (STL/CLR)](#clear)|Removes all elements.| -|[multiset::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[multiset::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[multiset::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[multiset::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[multiset::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[multiset::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[multiset::insert (STL/CLR)](#insert)|Adds elements.| -|[multiset::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[multiset::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[multiset::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[multiset::multiset (STL/CLR)](#multiset)|Constructs a container object.| -|[multiset::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[multiset::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[multiset::size (STL/CLR)](#size)|Counts the number of elements.| -|[multiset::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[multiset::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[multiset::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[multiset::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[multiset::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (multiset) (STL/CLR)](#op_neq)|Determines if a `multiset` object is not equal to another `multiset` object.| -|[operator< (multiset) (STL/CLR)](#op_lt)|Determines if a `multiset` object is less than another `multiset` object.| -|[operator<= (multiset) (STL/CLR)](#op_lteq)|Determines if a `multiset` object is less than or equal to another `multiset` object.| -|[operator== (multiset) (STL/CLR)](#op_eq)|Determines if a `multiset` object is equal to another `multiset` object.| -|[operator> (multiset) (STL/CLR)](#op_gt)|Determines if a `multiset` object is greater than another `multiset` object.| -|[operator>= (multiset) (STL/CLR)](#op_gteq)|Determines if a `multiset` object is greater than or equal to another `multiset` object.| +| Type definition | Description | +|---|---| +| [`multiset::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`multiset::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`multiset::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`multiset::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`multiset::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`multiset::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`multiset::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`multiset::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`multiset::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`multiset::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`multiset::key_type`](#key_type) | The type of an ordering key. | +| [`multiset::reference`](#reference) | The type of a reference to an element. | +| [`multiset::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`multiset::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`multiset::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`multiset::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`multiset::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`multiset::clear`](#clear) | Removes all elements. | +| [`multiset::count`](#count) | Counts elements matching a specified key. | +| [`multiset::empty`](#empty) | Tests whether no elements are present. | +| [`multiset::end`](#end) | Designates the end of the controlled sequence. | +| [`multiset::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`multiset::erase`](#erase) | Removes elements at specified positions. | +| [`multiset::find`](#find) | Finds an element that matches a specified key. | +| [`multiset::insert`](#insert) | Adds elements. | +| [`multiset::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`multiset::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`multiset::make_value`](#make_value) | Constructs a value object. | +| [`multiset::multiset`](#multiset) | Constructs a container object. | +| [`multiset::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`multiset::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`multiset::size`](#size) | Counts the number of elements. | +| [`multiset::swap`](#swap) | Swaps the contents of two containers. | +| [`multiset::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`multiset::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`multiset::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`multiset::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (multiset)](#op_neq) | Determines if a `multiset` object isn't equal to another `multiset` object. | +| [`operator<` (multiset)](#op_lt) | Determines if a `multiset` object is less than another `multiset` object. | +| [`operator<=` (multiset)](#op_lteq) | Determines if a `multiset` object is less than or equal to another `multiset` object. | +| [`operator==` (multiset)](#op_eq) | Determines if a `multiset` object is equal to another `multiset` object. | +| [`operator>` (multiset)](#op_gt) | Determines if a `multiset` object is greater than another `multiset` object. | +| [`operator>=` (multiset)](#op_gteq) | Determines if a `multiset` object is greater than or equal to another `multiset` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|ITree\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [multiset::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the multiset; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [multiset::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`multiset::key_compare`](#key_compare). You can specify the stored delegate object when you construct the multiset; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`multiset::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [multiset::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`multiset::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -121,21 +121,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set (STL/CLR)](../dotnet/set-stl-clr.md), an object of template class `multiset` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set (STL/CLR)](../dotnet/set-stl-clr.md), an object of template class `multiset` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element serves as both a ey and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A multiset supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [multiset::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a multiset iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `multiset` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `multiset` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a multiset element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `multiset` element directly given its numerical position. That requires a random-access iterator. -A multiset iterator stores a handle to its associated multiset node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A multiset iterator remains valid so long as its associated multiset node is associated with some multiset. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `multiset` iterator stores a handle to its associated `multiset` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `multiset` iterator remains valid so long as its associated `multiset` node is associated with some multiset. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## multiset::begin (STL/CLR) +## `multiset::begin` Designates the beginning of the controlled sequence. @@ -183,7 +183,7 @@ a b c *++begin() = b ``` -## multiset::clear (STL/CLR) +## `multiset::clear` Removes all elements. @@ -195,7 +195,7 @@ void clear(); ### Remarks -The member function effectively calls [multiset::erase (STL/CLR)](#erase)`(` [multiset::begin (STL/CLR)](#begin)`(),` [multiset::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -241,7 +241,7 @@ a b size() = 0 ``` -## multiset::const_iterator (STL/CLR) +## `multiset::const_iterator` The type of a constant iterator for the controlled sequence. @@ -283,7 +283,7 @@ int main() a b c ``` -## multiset::const_reference (STL/CLR) +## `multiset::const_reference` The type of a constant reference to an element. @@ -328,9 +328,9 @@ int main() a b c ``` -## multiset::const_reverse_iterator (STL/CLR) +## `multiset::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -370,7 +370,7 @@ int main() c b a ``` -## multiset::count (STL/CLR) +## `multiset::count` Finds the number of elements matching a specified key. @@ -382,12 +382,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -423,7 +423,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## multiset::difference_type (STL/CLR) +## `multiset::difference_type` The types of a signed distance between two elements. @@ -478,7 +478,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## multiset::empty (STL/CLR) +## `multiset::empty` Tests whether no elements are present. @@ -490,7 +490,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [multiset::size (STL/CLR)](#size)`() == 0`. You use it to test whether the multiset is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `multiset` is empty. ### Example @@ -530,7 +530,7 @@ size() = 0 empty() = True ``` -## multiset::end (STL/CLR) +## `multiset::end` Designates the end of the controlled sequence. @@ -542,7 +542,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -579,7 +579,7 @@ a b c *--end() = c ``` -## multiset::equal_range (STL/CLR) +## `multiset::equal_range` Finds range that matches a specified key. @@ -591,12 +591,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [multiset::lower_bound (STL/CLR)](#lower_bound)`(key),` [multiset::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -639,7 +639,7 @@ equal_range(L'x') empty = True b ``` -## multiset::erase (STL/CLR) +## `multiset::erase` Removes elements at specified positions. @@ -653,25 +653,25 @@ size_type erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [multiset::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range `[first, last)`, and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -723,7 +723,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## multiset::find (STL/CLR) +## `multiset::find` Finds an element that matches a specified key. @@ -735,12 +735,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [multiset::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -779,7 +779,7 @@ find b = b find C = False ``` -## multiset::generic_container (STL/CLR) +## `multiset::generic_container` The type of the generic interface for the container. @@ -843,7 +843,7 @@ a b c d a b c d e ``` -## multiset::generic_iterator (STL/CLR) +## `multiset::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -899,7 +899,7 @@ a b c a ``` -## multiset::generic_reverse_iterator (STL/CLR) +## `multiset::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -955,7 +955,7 @@ a b c c ``` -## multiset::generic_value (STL/CLR) +## `multiset::generic_value` The type of an element for use with the generic interface for the container. @@ -1009,7 +1009,7 @@ a b c a ``` -## multiset::insert (STL/CLR) +## `multiset::insert` Adds elements. @@ -1025,34 +1025,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function inserts an element with value *val*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. +The first member function inserts an element with value *`val`*, and returns an iterator that designates the newly inserted element. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1122,7 +1122,7 @@ a b b c x a b b c x y ``` -## multiset::iterator (STL/CLR) +## `multiset::iterator` The type of an iterator for the controlled sequence. @@ -1164,7 +1164,7 @@ int main() a b c ``` -## multiset::key_comp (STL/CLR) +## `multiset::key_comp` Copies the ordering delegate for two keys. @@ -1223,7 +1223,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multiset::key_compare (STL/CLR) +## `multiset::key_compare` The ordering delegate for two keys. @@ -1283,7 +1283,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## multiset::key_type (STL/CLR) +## `multiset::key_type` The type of an ordering key. @@ -1295,7 +1295,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1328,7 +1328,7 @@ int main() a b c ``` -## multiset::lower_bound (STL/CLR) +## `multiset::lower_bound` Finds beginning of range that matches a specified key. @@ -1340,12 +1340,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1385,7 +1385,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## multiset::make_value (STL/CLR) +## `multiset::make_value` Constructs a value object. @@ -1397,12 +1397,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1431,7 +1431,7 @@ int main() a b c ``` -## multiset::multiset (STL/CLR) +## `multiset::multiset` Constructs a container object. @@ -1454,16 +1454,16 @@ multiset(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1478,19 +1478,19 @@ The constructor: `explicit multiset(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `multiset(multiset% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multiset object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multiset` object *`right`*, with the default ordering predicate. The constructor: `multiset(multiset^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the multiset object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `multiset` object *`right`*, with the default ordering predicate. The constructor: @@ -1502,19 +1502,19 @@ The constructor: `template multiset(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `multiset(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `multiset(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1602,7 +1602,7 @@ c b a a b c ``` -## multiset::operator= (STL/CLR) +## `multiset::operator=` Replaces the controlled sequence. @@ -1614,12 +1614,12 @@ multiset% operator=(multiset% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1657,7 +1657,7 @@ a b c a b c ``` -## multiset::rbegin (STL/CLR) +## `multiset::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1705,7 +1705,7 @@ a b c *++rbegin() = b ``` -## multiset::reference (STL/CLR) +## `multiset::reference` The type of a reference to an element. @@ -1750,7 +1750,7 @@ int main() a b c ``` -## multiset::rend (STL/CLR) +## `multiset::rend` Designates the end of the reversed controlled sequence. @@ -1799,7 +1799,7 @@ a b c *--rend() = a ``` -## multiset::reverse_iterator (STL/CLR) +## `multiset::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -1841,7 +1841,7 @@ int main() c b a ``` -## multiset::size (STL/CLR) +## `multiset::size` Counts the number of elements. @@ -1853,7 +1853,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [multiset::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -1895,9 +1895,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## multiset::size_type (STL/CLR) +## `multiset::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -1943,7 +1943,7 @@ a b c end()-begin() = 3 ``` -## multiset::swap (STL/CLR) +## `multiset::swap` Swaps the contents of two containers. @@ -1955,12 +1955,12 @@ void swap(multiset% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2011,7 +2011,7 @@ d e f a b c ``` -## multiset::to_array (STL/CLR) +## `multiset::to_array` Copies the controlled sequence to a new array. @@ -2061,7 +2061,7 @@ a b c d a b c ``` -## multiset::upper_bound (STL/CLR) +## `multiset::upper_bound` Finds end of range that matches a specified key. @@ -2073,12 +2073,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [multiset::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2118,7 +2118,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## multiset::value_comp (STL/CLR) +## `multiset::value_comp` Copies the ordering delegate for two element values. @@ -2162,7 +2162,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## multiset::value_compare (STL/CLR) +## `multiset::value_compare` The ordering delegate for two element values. @@ -2207,7 +2207,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## multiset::value_type (STL/CLR) +## `multiset::value_type` The type of an element. @@ -2252,7 +2252,7 @@ int main() a b c ``` -## operator!= (multiset) (STL/CLR) +## `operator!=` (multiset) List not equal comparison. @@ -2266,15 +2266,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two multisets are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two multisets are compared element by element. ### Example @@ -2336,15 +2336,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two multisets are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two multisets are compared element by element. ### Example @@ -2392,7 +2392,7 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (multiset) (STL/CLR) +## `operator<=` (multiset) List less than or equal comparison. @@ -2406,15 +2406,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two multisets are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two multisets are compared element by element. ### Example @@ -2462,7 +2462,7 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (multiset) (STL/CLR) +## `operator==` (multiset) List equal comparison. @@ -2476,15 +2476,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two multisets are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two multisets are compared element by element. ### Example @@ -2532,7 +2532,7 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (multiset) (STL/CLR) +## `operator>` (multiset) List greater than comparison. @@ -2546,15 +2546,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two multisets are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two multisets are compared element by element. ### Example @@ -2602,7 +2602,7 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (multiset) (STL/CLR) +## `operator>=` (multiset) List greater than or equal comparison. @@ -2616,15 +2616,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two multisets are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two multisets are compared element by element. ### Example diff --git a/docs/dotnet/numeric-stl-clr.md b/docs/dotnet/numeric-stl-clr.md index 2be870dabca..2aae6eaa341 100644 --- a/docs/dotnet/numeric-stl-clr.md +++ b/docs/dotnet/numeric-stl-clr.md @@ -9,7 +9,7 @@ ms.assetid: 1dc4d9a3-e734-459c-9678-5d9be0ef4c79 --- # numeric (STL/CLR) -Defines container template functions that perform algorithms provided for numerical processing. +Defines container function templates that perform algorithms provided for numerical processing. ## Syntax diff --git a/docs/dotnet/priority-queue-stl-clr.md b/docs/dotnet/priority-queue-stl-clr.md index 3dc4e67eb65..220f5b91d1b 100644 --- a/docs/dotnet/priority-queue-stl-clr.md +++ b/docs/dotnet/priority-queue-stl-clr.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: priority_queue (STL/CLR)" title: "priority_queue (STL/CLR)" -ms.date: "11/04/2016" +description: "Learn more about: priority_queue (STL/CLR)" +ms.date: 11/04/2016 ms.topic: "reference" f1_keywords: ["cliext::priority_queue", "cliext::priority_queue::assign", "cliext::priority_queue::const_reference", "cliext::priority_queue::container_type", "cliext::priority_queue::difference_type", "cliext::priority_queue::empty", "cliext::priority_queue::generic_container", "cliext::priority_queue::generic_value", "cliext::priority_queue::get_container", "cliext::priority_queue::operator=", "cliext::priority_queue::pop", "cliext::priority_queue::priority_queue", "cliext::priority_queue::push", "cliext::priority_queue::reference", "cliext::priority_queue::size", "cliext::priority_queue::size_type", "cliext::priority_queue::to_array", "cliext::priority_queue::top", "cliext::priority_queue::top_item", "cliext::priority_queue::value_comp", "cliext::priority_queue::value_compare", "cliext::priority_queue::value_type"] helpviewer_keywords: ["priority_queue class [STL/CLR]", " header [STL/CLR]", " header [STL/CLR]", "assign member [STL/CLR]", "const_reference member [STL/CLR]", "container_type member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "generic_container member [STL/CLR]", "generic_value member [STL/CLR]", "get_container member [STL/CLR]", "operator= member [STL/CLR]", "pop member [STL/CLR]", "priority_queue member [STL/CLR]", "push member [STL/CLR]", "reference member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "to_array member [STL/CLR]", "top member [STL/CLR]", "top_item member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] -ms.assetid: 4d0000d3-68ff-4c4b-8157-7060540136f5 --- # priority_queue (STL/CLR) @@ -701,19 +700,19 @@ The constructor: `template priority_queue(InIt first, InIt last);` -creates an empty wrapped container, with the default ordering predicate, then pushes the sequence [`first`, `last`). You use it to specify an initial controlled sequence from a specified eqeuence, with the specified ordering predicate. +creates an empty wrapped container, with the default ordering predicate, then pushes the sequence [`first`, `last`). You use it to specify an initial controlled sequence from a specified sequence, with the specified ordering predicate. The constructor: `template priority_queue(InIt first, InIt last, value_compare^ pred);` -creates an empty wrapped container, with the ordering predicate *pred*, then pushes the sequence [`first`, `last`). You use it to specify an initial controlled sequence from a specified seqeuence, with the specified ordering predicate. +creates an empty wrapped container, with the ordering predicate *pred*, then pushes the sequence [`first`, `last`). You use it to specify an initial controlled sequence from a specified sequence, with the specified ordering predicate. The constructor: `template priority_queue(InIt first, InIt last, value_compare^ pred, container_type% cont);` -creates an empty wrapped container, with the ordering predicate *pred*, then pushes all the elements of *cont* plus the sequence [`first`, `last`). You use it to specify an initial controlled sequence from an existing container and a specified seqeuence, with the specified ordering predicate. +creates an empty wrapped container, with the ordering predicate *pred*, then pushes all the elements of *cont* plus the sequence [`first`, `last`). You use it to specify an initial controlled sequence from an existing container and a specified sequence, with the specified ordering predicate. ### Example diff --git a/docs/dotnet/queue-stl-clr.md b/docs/dotnet/queue-stl-clr.md index 841400c6e70..d3bc7430b5a 100644 --- a/docs/dotnet/queue-stl-clr.md +++ b/docs/dotnet/queue-stl-clr.md @@ -1,17 +1,16 @@ --- -description: "Learn more about: queue (STL/CLR)" title: "queue (STL/CLR)" -ms.date: "11/04/2016" +description: "Learn more about: queue (STL/CLR)" +ms.date: "4/20/2023" ms.topic: "reference" f1_keywords: ["cliext::queue", "cliext::queue::assign", "cliext::queue::back", "cliext::queue::back_item", "cliext::queue::const_reference", "cliext::queue::container_type", "cliext::queue::difference_type", "cliext::queue::empty", "cliext::queue::front", "cliext::queue::front_item", "cliext::queue::generic_container", "cliext::queue::generic_value", "cliext::queue::get_container", "cliext::queue::operator=", "cliext::queue::pop", "cliext::queue::push", "cliext::queue::queue", "cliext::queue::reference", "cliext::queue::size", "cliext::queue::size_type", "cliext::queue::to_array", "cliext::queue::value_type"] helpviewer_keywords: [" header [STL/CLR]", "queue class [STL/CLR]", " header [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]", "assign member [STL/CLR]", "back member [STL/CLR]", "back_item member [STL/CLR]", "const_reference member [STL/CLR]", "container_type member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "front member [STL/CLR]", "front_item member [STL/CLR]", "generic_container member [STL/CLR]", "generic_value member [STL/CLR]", "get_container member [STL/CLR]", "operator= member [STL/CLR]", "pop member [STL/CLR]", "push member [STL/CLR]", "queue member [STL/CLR]", "reference member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "to_array member [STL/CLR]", "value_type member [STL/CLR]"] -ms.assetid: 9ea7dec3-ea98-48ff-87d0-a5afc924aaf2 --- -# queue (STL/CLR) +# `queue` (STL/CLR) -The template class describes an object that controls a varying-length sequence of elements that has first-in first-out access. You use the container adapter `queue` to manage an underlying container as a queue. +The template class describes an object that controls a varying length sequence of elements that has first-in first-out access. Use the container adapter `queue` to manage an underlying container as a queue. -In the description below, `GValue` is the same as *Value* unless the latter is a ref type, in which case it is `Value^`. Similarly, `GContainer` is the same as *Container* unless the latter is a ref type, in which case it is `Container^`. +In the following description, `GValue` is the same as *`Value`* unless the latter is a ref type, in which case it's `Value^`. Similarly, `GContainer` is the same as *`Container`* unless the latter is a ref type, in which case it's `Container^`. ## Syntax @@ -27,73 +26,76 @@ template +*`Value`*\ The type of an element in the controlled sequence. -*Container*
+*`Container`*\ The type of the underlying container. ## Requirements -**Header:** \ +**Header:** `` + +**Namespace:** `cliext` -**Namespace:** cliext +> [!IMPORTANT] +> To compile the examples in this topic, ensure that you have installed C++/CLI support as described in [Install C++/CLI support in Visual Studio 2022](dotnet-programming-with-cpp-cli-visual-cpp.md#install-ccli-support-in-visual-studio-2022). For the project type, create a *CLR Console app (.NET Framework)*. ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[queue::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[queue::container_type (STL/CLR)](#container_type)|The type of the underlying container.| -|[queue::difference_type (STL/CLR)](#difference_type)|The type of a signed distance between two elements.| -|[queue::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container adapter.| -|[queue::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container adapter.| -|[queue::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[queue::size_type (STL/CLR)](#size_type)|The type of a signed distance between two elements.| -|[queue::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[queue::assign (STL/CLR)](#assign)|Replaces all elements.| -|[queue::back (STL/CLR)](#back)|Accesses the last element.| -|[queue::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[queue::front (STL/CLR)](#front)|Accesses the first element.| -|[queue::get_container (STL/CLR)](#get_container)|Accesses the underlying container.| -|[queue::pop (STL/CLR)](#pop)|Removes the first element.| -|[queue::push (STL/CLR)](#push)|Adds a new last element.| -|[queue::queue (STL/CLR)](#queue)|Constructs a container object.| -|[queue::size (STL/CLR)](#size)|Counts the number of elements.| -|[queue::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| - -|Property|Description| -|--------------|-----------------| -|[queue::back_item (STL/CLR)](#back_item)|Accesses the last element.| -|[queue::front_item (STL/CLR)](#front_item)|Accesses the first element.| - -|Operator|Description| -|--------------|-----------------| -|[queue::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (queue) (STL/CLR)](#op_neq)|Determines if a `queue` object is not equal to another `queue` object.| -|[operator< (queue) (STL/CLR)](#op_lt)|Determines if a `queue` object is less than another `queue` object.| -|[operator<= (queue) (STL/CLR)](#op_lteq)|Determines if a `queue` object is less than or equal to another `queue` object.| -|[operator== (queue) (STL/CLR)](#op_eq)|Determines if a `queue` object is equal to another `queue` object.| -|[operator> (queue) (STL/CLR)](#op_gt)|Determines if a `queue` object is greater than another `queue` object.| -|[operator>= (queue) (STL/CLR)](#op_gteq)|Determines if a `queue` object is greater than or equal to another `queue` object.| +| Type definition | Description | +|---|---| +| [`queue::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`queue::container_type`](#container_type) | The type of the underlying container. | +| [`queue::difference_type`](#difference_type) | The type of a signed distance between two elements. | +| [`queue::generic_container`](#generic_container) | The type of the generic interface for the container adapter. | +| [`queue::generic_value`](#generic_value) | The type of an element for the generic interface for the container adapter. | +| [`queue::reference`](#reference) | The type of a reference to an element. | +| [`queue::size_type`](#size_type) | The type of a signed distance between two elements. | +| [`queue::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`queue::assign`](#assign) | Replaces all elements. | +| [`queue::back`](#back) | Accesses the last element. | +| [`queue::empty`](#empty) | Tests whether no elements are present. | +| [`queue::front`](#front) | Accesses the first element. | +| [`queue::get_container`](#get_container) | Accesses the underlying container. | +| [`queue::pop`](#pop) | Removes the first element. | +| [`queue::push`](#push) | Adds a new last element. | +| [`queue::queue`](#queue) | Constructs a container object. | +| [`queue::size`](#size) | Counts the number of elements. | +| [`queue::to_array`](#to_array) | Copies the controlled sequence to a new array. | + +| Property | Description | +|---|---| +| [`queue::back_item`](#back_item) | Accesses the last element. | +| [`queue::front_item`](#front_item) | Accesses the first element. | + +| Operator | Description | +|---|---| +| [`queue::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (queue)](#op_neq) | Determines if a `queue` object isn't equal to another `queue` object. | +| [`operator<` (queue)](#op_lt) | Determines if a `queue` object is less than another `queue` object. | +| [`operator<=` (queue)](#op_lteq) | Determines if a `queue` object is less than or equal to another `queue` object. | +| [`operator==` (queue)](#op_eq) | Determines if a `queue` object is equal to another `queue` object. | +| [`operator>` (queue)](#op_gt) | Determines if a `queue` object is greater than another `queue` object. | +| [`operator>=` (queue)](#op_gteq) | Determines if a `queue` object is greater than or equal to another `queue` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -|IQueue\|Maintain generic container adapter.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| `IQueue` | Maintain generic container adapter. | ## Remarks -The object allocates and frees storage for the sequence it controls through an underlying container, of type `Container`, that stores `Value` elements and grows on demand. The object restricts access to just pushing the first element and popping the last element, implementing a first-in first-out queue (also known as a FIFO queue, or simply a queue). +The object allocates and frees storage for the sequence it controls through an underlying container of type *`Container`* that stores *`Value`* elements and grows on demand. The object restricts access to just pushing the first element and popping the last element, implementing a first-in first-out queue (also known as a FIFO queue, or simply a queue). ## Members -## queue::assign (STL/CLR) +## `queue::assign` Replaces all elements. @@ -105,7 +107,7 @@ void assign(queue% right); #### Parameters -*right*
+*`right`*\ Container adapter to insert. ### Remarks @@ -117,29 +119,30 @@ The member function assigns `right.get_container()` to the underlying container. ```cpp // cliext_queue_assign.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign a repetition of values + // assign a repetition of values Myqueue c2; c2.assign(c1); for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -147,7 +150,7 @@ a b c a b c ``` -## queue::back (STL/CLR) +## `queue::back` Accesses the last element. @@ -159,38 +162,39 @@ reference back(); ### Remarks -The member function returns a reference to the last element of the controlled sequence, which must be non-empty. You use it to access the last element, when you know it exists. +The member function returns a reference to the last element of the controlled sequence, which must be nonempty. You use it to access the last element, when you know one exists. ### Example ```cpp // cliext_queue_back.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect last item + // inspect last item System::Console::WriteLine("back() = {0}", c1.back()); -// alter last item and reinspect + // alter last item and reinspect c1.back() = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -199,7 +203,7 @@ back() = c a b x ``` -## queue::back_item (STL/CLR) +## `queue::back_item` Accesses the last element. @@ -211,38 +215,39 @@ property value_type back_item; ### Remarks -The property accesses the last element of the controlled sequence, which must be non-empty. You use it to read or write the last element, when you know it exists. +The property accesses the last element of the controlled sequence, which must be nonempty. You use it to read or write the last element, when you know one exists. ### Example ```cpp // cliext_queue_back_item.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect last item + // inspect last item System::Console::WriteLine("back_item = {0}", c1.back_item); -// alter last item and reinspect + // alter last item and reinspect c1.back_item = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -251,7 +256,7 @@ back_item = c a b x ``` -## queue::const_reference (STL/CLR) +## `queue::const_reference` The type of a constant reference to an element. @@ -270,17 +275,18 @@ The type describes a constant reference to an element. ```cpp // cliext_queue_const_reference.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for (; !c1.empty(); c1.pop()) { // get a const reference to an element Myqueue::const_reference cref = c1.front(); @@ -288,14 +294,14 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::container_type (STL/CLR) +## `queue::container_type` The type of the underlying container. @@ -314,30 +320,31 @@ The type is a synonym for the template parameter `Container`. ```cpp // cliext_queue_container_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" using container_type + // display contents "a b c" using container_type Myqueue::container_type wc1 = c1.get_container(); for each (wchar_t elem in wc1) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::difference_type (STL/CLR) +## `queue::difference_type` The types of a signed distance between two elements. @@ -356,29 +363,30 @@ The type describes a possibly negative element count. ```cpp // cliext_queue_difference_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// compute negative difference + // compute negative difference Myqueue::difference_type diff = c1.size(); c1.push(L'd'); c1.push(L'e'); diff -= c1.size(); System::Console::WriteLine("pushing 2 = {0}", diff); -// compute positive difference + // compute positive difference diff = c1.size(); c1.pop(); c1.pop(); @@ -386,7 +394,7 @@ int main() diff -= c1.size(); System::Console::WriteLine("popping 3 = {0}", diff); return (0); - } +} ``` ```Output @@ -395,7 +403,7 @@ pushing 2 = -2 popping 3 = 3 ``` -## queue::empty (STL/CLR) +## `queue::empty` Tests whether no elements are present. @@ -407,38 +415,39 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [queue::size (STL/CLR)](#size)`() == 0`. You use it to test whether the queue is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `queue` is empty. ### Example ```cpp // cliext_queue_empty.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); System::Console::WriteLine("size() = {0}", c1.size()); System::Console::WriteLine("empty() = {0}", c1.empty()); -// clear the container and reinspect + // clear the container and reinspect c1.pop(); c1.pop(); c1.pop(); System::Console::WriteLine("size() = {0}", c1.size()); System::Console::WriteLine("empty() = {0}", c1.empty()); return (0); - } +} ``` ```Output @@ -449,7 +458,7 @@ size() = 0 empty() = True ``` -## queue::front (STL/CLR) +## `queue::front` Accesses the first element. @@ -461,38 +470,39 @@ reference front(); ### Remarks -The member function returns a reference to the first element of the controlled sequence, which must be non-empty. You use it to access the first element, when you know it exists. +The member function returns a reference to the first element of the controlled sequence, which must be nonempty. You use it to access the first element, when you know one exists. ### Example ```cpp // cliext_queue_front.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect first item + // inspect first item System::Console::WriteLine("front() = {0}", c1.front()); -// alter first item and reinspect + // alter first item and reinspect c1.front() = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -501,7 +511,7 @@ front() = a x b c ``` -## queue::front_item (STL/CLR) +## `queue::front_item` Accesses the first element. @@ -513,38 +523,39 @@ property value_type front_item; ### Remarks -The property accesses the first element of the controlled sequence, which must be non-empty. You use it to read or write the first element, when you know it exists. +The property accesses the first element of the controlled sequence, which must be nonempty. You use it to read or write the first element, when you know one exists. ### Example ```cpp // cliext_queue_front_item.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// inspect last item + // inspect last item System::Console::WriteLine("front_item = {0}", c1.front_item); -// alter last item and reinspect + // alter last item and reinspect c1.front_item = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -553,7 +564,7 @@ front_item = a x b c ``` -## queue::generic_container (STL/CLR) +## `queue::generic_container` The type of the generic interface for the container adapter. @@ -573,40 +584,41 @@ The type describes the generic interface for this template container adapter cla ```cpp // cliext_queue_generic_container.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// construct a generic container + // construct a generic container Myqueue::generic_container^ gc1 = %c1; for each (wchar_t elem in gc1->get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// modify generic and display original + // modify generic and display original gc1->push(L'd'); for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// modify original and display generic + // modify original and display generic c1.push(L'e'); for each (wchar_t elem in gc1->get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -616,7 +628,7 @@ a b c d a b c d e ``` -## queue::generic_value (STL/CLR) +## `queue::generic_value` The type of an element for use with the generic interface for the container. @@ -635,28 +647,29 @@ The type describes an object of type `GValue` that describes the stored element ```cpp // cliext_queue_generic_value.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// get interface to container + // get interface to container Myqueue::generic_container^ gc1 = %c1; for each (wchar_t elem in gc1->get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// display in order using generic_value + // display in order using generic_value for (; !gc1->empty(); gc1->pop()) { Myqueue::generic_value elem = gc1->front(); @@ -665,7 +678,7 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -674,7 +687,7 @@ a b c a b c ``` -## queue::get_container (STL/CLR) +## `queue::get_container` Accesses the underlying container. @@ -693,29 +706,30 @@ The member function returns the underlying container. You use it to bypass the r ```cpp // cliext_queue_get_container.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::operator= (STL/CLR) +## `queue::operator=` Replaces the controlled sequence. @@ -727,41 +741,42 @@ queue % operator=(queue % right); #### Parameters -*right*
+*`right`*\ Container adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example ```cpp // cliext_queue_operator_as.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2 = c1; for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -769,9 +784,9 @@ a b c a b c ``` -## queue::pop (STL/CLR) +## `queue::pop` -Removes the last element. +Removes the first element. ### Syntax @@ -781,35 +796,36 @@ void pop(); ### Remarks -The member function removes the last element of the controlled sequence, which must be non-empty. You use it to shorten the queue by one element at the back. +Removes the first element of the controlled sequence, which must be nonempty. ### Example ```cpp // cliext_queue_pop.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// pop an element and redisplay + // pop an element and redisplay c1.pop(); for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -817,7 +833,7 @@ a b c b c ``` -## queue::push (STL/CLR) +## `queue::push` Adds a new last element. @@ -836,29 +852,30 @@ The member function adds an element with value `val` at the end of the queue. Yo ```cpp // cliext_queue_push.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## queue::queue (STL/CLR) +## `queue::queue` Constructs a container adapter object. @@ -873,10 +890,10 @@ explicit queue(container_type% wrapped); #### Parameters -*right*
+*`right`*\ Object to copy. -*wrapped*
+*`wrapped`*\ Wrapped container to use. ### Remarks @@ -891,25 +908,26 @@ The constructor: `queue(queue% right);` -creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the queue object *right*. +creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `queue` object *`right`*. The constructor: `queue(queue^ right);` -creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the queue object `*right`. +creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `queue` object `*right`. The constructor: `explicit queue(container_type wrapped);` -uses the existing container *wrapped* as the wrapped container. You use it to construct a queue from an existing container. +uses the existing container *`wrapped`* as the wrapped container. You use it to construct a `queue` from an existing container. ### Example ```cpp // cliext_queue_construct.cpp // compile with: /clr +#include "pch.h" #include #include @@ -917,31 +935,31 @@ typedef cliext::queue Myqueue; typedef cliext::list Mylist; typedef cliext::queue Myqueue_list; int main() - { -// construct an empty container +{ + // construct an empty container Myqueue c1; System::Console::WriteLine("size() = {0}", c1.size()); -// construct from an underlying container + // construct from an underlying container Mylist v2(5, L'x'); Myqueue_list c2(v2); for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// construct by copying another container + // construct by copying another container Myqueue_list c3(c2); for each (wchar_t elem in c3.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// construct by copying another container through handle + // construct by copying another container through handle Myqueue_list c4(%c2); for each (wchar_t elem in c4.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -951,7 +969,7 @@ x x x x x x x x x x ``` -## queue::reference (STL/CLR) +## `queue::reference` The type of a reference to an element. @@ -970,29 +988,30 @@ The type describes a reference to an element. ```cpp // cliext_queue_reference.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// modify back of queue and redisplay + // modify back of queue and redisplay Myqueue::reference ref = c1.back(); ref = L'x'; for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -1000,7 +1019,7 @@ a b c a b x ``` -## queue::size (STL/CLR) +## `queue::size` Counts the number of elements. @@ -1012,39 +1031,40 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [queue::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example ```cpp // cliext_queue_size.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); System::Console::WriteLine("size() = {0} starting with 3", c1.size()); -// pop an item and reinspect + // pop an item and reinspect c1.pop(); System::Console::WriteLine("size() = {0} after popping", c1.size()); -// add two elements and reinspect + // add two elements and reinspect c1.push(L'a'); c1.push(L'b'); System::Console::WriteLine("size() = {0} after adding 2", c1.size()); return (0); - } +} ``` ```Output @@ -1054,9 +1074,9 @@ size() = 2 after popping size() = 4 after adding 2 ``` -## queue::size_type (STL/CLR) +## `queue::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -1073,29 +1093,30 @@ The type describes a non-negative element count. ```cpp // cliext_queue_size_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display initial contents " a b c" + // display initial contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// compute positive difference + // compute positive difference Myqueue::size_type diff = c1.size(); c1.pop(); c1.pop(); diff -= c1.size(); System::Console::WriteLine("size difference = {0}", diff); return (0); - } +} ``` ```Output @@ -1103,7 +1124,7 @@ a b c size difference = 2 ``` -## queue::to_array (STL/CLR) +## `queue::to_array` Copies the controlled sequence to a new array. @@ -1122,17 +1143,18 @@ The member function returns an array containing the controlled sequence. You use ```cpp // cliext_queue_to_array.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// copy the container and modify it + // copy the container and modify it cli::array^ a1 = c1.to_array(); c1.push(L'd'); @@ -1140,12 +1162,12 @@ int main() System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// display the earlier array copy + // display the earlier array copy for each (wchar_t elem in a1) System::Console::Write("{0} ", elem); System::Console::WriteLine(); return (0); - } +} ``` ```Output @@ -1153,7 +1175,7 @@ a b c d a b c ``` -## queue::value_type (STL/CLR) +## `queue::value_type` The type of an element. @@ -1165,24 +1187,25 @@ typedef Value value_type; ### Remarks -The type is a synonym for the template parameter *Value*. +The type is a synonym for the template parameter *`Value`*. ### Example ```cpp // cliext_queue_value_type.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display reversed contents " a b c" using value_type + // display reversed contents "a b c" using value_type for (; !c1.empty(); c1.pop()) { // store element in value_type object Myqueue::value_type val = c1.front(); @@ -1191,16 +1214,16 @@ int main() } System::Console::WriteLine(); return (0); - } +} ``` ```Output a b c ``` -## operator!= (queue) (STL/CLR) +## `operator!=` (queue) -Queue not equal comparison. +`Queue` not equal comparison. ### Syntax @@ -1213,43 +1236,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two queues are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_ne.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1259,7 +1283,7 @@ int main() System::Console::WriteLine("[a b c] != [a b d] is {0}", c1 != c2); return (0); - } +} ``` ```Output @@ -1269,9 +1293,9 @@ a b d [a b c] != [a b d] is True ``` -## `operator<` (queue) (STL/CLR) +## `operator<` (queue) -Queue less than comparison. +`Queue` less than comparison. ### Syntax @@ -1284,43 +1308,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->`[queue::size (STL/CLR)](#size)`() <` `right->size()` You use it to test whether *left* is ordered before *right* when the two queues are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_lt.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1330,7 +1355,7 @@ int main() System::Console::WriteLine("[a b c] < [a b d] is {0}", c1 < c2); return (0); - } +} ``` ```Output @@ -1340,9 +1365,9 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (queue) (STL/CLR) +## `operator<=` (queue) -Queue less than or equal comparison. +`Queue` less than or equal comparison. ### Syntax @@ -1355,43 +1380,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two queues are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_le.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1401,7 +1427,7 @@ int main() System::Console::WriteLine("[a b d] <= [a b c] is {0}", c2 <= c1); return (0); - } +} ``` ```Output @@ -1411,9 +1437,9 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (queue) (STL/CLR) +## `operator==` (queue) -Queue equal comparison. +`Queue` equal comparison. ### Syntax @@ -1426,43 +1452,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two queues are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_eq.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1472,7 +1499,7 @@ int main() System::Console::WriteLine("[a b c] == [a b d] is {0}", c1 == c2); return (0); - } +} ``` ```Output @@ -1482,9 +1509,9 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (queue) (STL/CLR) +## `operator>` (queue) -Queue greater than comparison. +`Queue` greater than comparison. ### Syntax @@ -1497,43 +1524,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two queues are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_gt.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1543,7 +1571,7 @@ int main() System::Console::WriteLine("[a b d] > [a b c] is {0}", c2 > c1); return (0); - } +} ``` ```Output @@ -1553,9 +1581,9 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (queue) (STL/CLR) +## `operator>=` (queue) -Queue greater than or equal comparison. +`Queue` greater than or equal comparison. ### Syntax @@ -1568,43 +1596,44 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two queues are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two queues are compared element by element. ### Example ```cpp // cliext_queue_operator_ge.cpp // compile with: /clr +#include "pch.h" #include typedef cliext::queue Myqueue; int main() - { +{ Myqueue c1; c1.push(L'a'); c1.push(L'b'); c1.push(L'c'); -// display contents " a b c" + // display contents "a b c" for each (wchar_t elem in c1.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); -// assign to a new container + // assign to a new container Myqueue c2; c2.push(L'a'); c2.push(L'b'); c2.push(L'd'); -// display contents " a b d" + // display contents "a b d" for each (wchar_t elem in c2.get_container()) System::Console::Write("{0} ", elem); System::Console::WriteLine(); @@ -1614,7 +1643,7 @@ int main() System::Console::WriteLine("[a b c] >= [a b d] is {0}", c1 >= c2); return (0); - } +} ``` ```Output diff --git a/docs/dotnet/reflection-cpp-cli.md b/docs/dotnet/reflection-cpp-cli.md index 9b31b0a1498..5cf26a76a1f 100644 --- a/docs/dotnet/reflection-cpp-cli.md +++ b/docs/dotnet/reflection-cpp-cli.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Reflection (C++/CLI)" title: "Reflection (C++/CLI)" -ms.date: "11/04/2016" -helpviewer_keywords: ["typeid keyword [C++]", "reflection [C++}, about reflection", "metadata, reflection", "GetType method", ".NET Framework [C++], reflection", "data types [C++], reflection", "reflection [C++}", "plug-ins [C++]", "reflection [C++}, plug-ins", "assemblies [C++], enumerating data types in", "public types [C++]", "reflection [C++], external assemblies", "assemblies [C++]", "data types [C++], enumerating", "public members [C++]"] -ms.assetid: 46b6ff4a-e441-4022-8892-78e69422f230 +description: "Learn more about: Reflection (C++/CLI)" +ms.date: 11/04/2016 +helpviewer_keywords: ["typeid keyword [C++]", "reflection [C++], about reflection", "metadata, reflection", "GetType method", ".NET Framework [C++], reflection", "data types [C++], reflection", "reflection [C++]", "plug-ins [C++]", "reflection [C++], plug-ins", "assemblies [C++], enumerating data types in", "public types [C++]", "reflection [C++], external assemblies", "assemblies [C++]", "data types [C++], enumerating", "public members [C++]"] --- # Reflection (C++/CLI) diff --git a/docs/dotnet/set-stl-clr.md b/docs/dotnet/set-stl-clr.md index d028cbb1fc8..be54240cf6d 100644 --- a/docs/dotnet/set-stl-clr.md +++ b/docs/dotnet/set-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::set", "cliext::set::begin", "cliext::set::clear", "cliext helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "set class [STL/CLR]", "operator!= (set) member [STL/CLR]", "operator< (set) member [STL/CLR]", "operator<= (set) member [STL/CLR]", "operator== (set) member [STL/CLR]", "operator> (set) member [STL/CLR]", "operator>= (set) member [STL/CLR]", "begin member [STL/CLR]", "clear member [STL/CLR]", "const_iterator member [STL/CLR]", "const_reference member [STL/CLR]", "const_reverse_iterator member [STL/CLR]", "count member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "end member [STL/CLR]", "equal_range member [STL/CLR]", "erase member [STL/CLR]", "find member [STL/CLR]", "generic_container member [STL/CLR]", "generic_iterator member [STL/CLR]", "generic_reverse_iterator member [STL/CLR]", "generic_value member [STL/CLR]", "insert member [STL/CLR]", "iterator member [STL/CLR]", "key_comp member [STL/CLR]", "key_compare member [STL/CLR]", "key_type member [STL/CLR]", "lower_bound member [STL/CLR]", "make_value member [STL/CLR]", "operator= member [STL/CLR]", "rbegin member [STL/CLR]", "reference member [STL/CLR]", "rend member [STL/CLR]", "reverse_iterator member [STL/CLR]", "set member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "swap member [STL/CLR]", "to_array member [STL/CLR]", "upper_bound member [STL/CLR]", "value_comp member [STL/CLR]", "value_compare member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: 27d3628c-741a-43a7-bef1-5085536f679e --- -# set (STL/CLR) +# `set` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has bidirectional access. You use the container `set` to manage a sequence of elements as a (nearly) balanced ordered tree of nodes, each storing one element. -In the description below, `GValue` is the same as `GKey`, which in turn is the same as *Key* unless the latter is a ref type, in which case it is `Key^`. +In the description below, `GValue` is the same as `GKey`, which in turn is the same as *`Key`* unless the latter is a ref type, in which case it's `Key^`. ## Syntax @@ -31,87 +31,87 @@ template ### Parameters -*Key*
+*`Key`*\ The type of the key component of an element in the controlled sequence. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[set::const_iterator (STL/CLR)](#const_iterator)|The type of a constant iterator for the controlled sequence.| -|[set::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[set::const_reverse_iterator (STL/CLR)](#const_reverse_iterator)|The type of a constant reverse iterator for the controlled sequence.| -|[set::difference_type (STL/CLR)](#difference_type)|The type of a (possibly signed) distance between two elements.| -|[set::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container.| -|[set::generic_iterator (STL/CLR)](#generic_iterator)|The type of an iterator for the generic interface for the container.| -|[set::generic_reverse_iterator (STL/CLR)](#generic_reverse_iterator)|The type of a reverse iterator for the generic interface for the container.| -|[set::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container.| -|[set::iterator (STL/CLR)](#iterator)|The type of an iterator for the controlled sequence.| -|[set::key_compare (STL/CLR)](#key_compare)|The ordering delegate for two keys.| -|[set::key_type (STL/CLR)](#key_type)|The type of an ordering key.| -|[set::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[set::reverse_iterator (STL/CLR)](#reverse_iterator)|The type of a reverse iterator for the controlled sequence.| -|[set::size_type (STL/CLR)](#size_type)|The type of a (non-negative) distance between two elements.| -|[set::value_compare (STL/CLR)](#value_compare)|The ordering delegate for two element values.| -|[set::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[set::begin (STL/CLR)](#begin)|Designates the beginning of the controlled sequence.| -|[set::clear (STL/CLR)](#clear)|Removes all elements.| -|[set::count (STL/CLR)](#count)|Counts elements matching a specified key.| -|[set::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[set::end (STL/CLR)](#end)|Designates the end of the controlled sequence.| -|[set::equal_range (STL/CLR)](#equal_range)|Finds range that matches a specified key.| -|[set::erase (STL/CLR)](#erase)|Removes elements at specified positions.| -|[set::find (STL/CLR)](#find)|Finds an element that matches a specified key.| -|[set::insert (STL/CLR)](#insert)|Adds elements.| -|[set::key_comp (STL/CLR)](#key_comp)|Copies the ordering delegate for two keys.| -|[set::lower_bound (STL/CLR)](#lower_bound)|Finds beginning of range that matches a specified key.| -|[set::make_value (STL/CLR)](#make_value)|Constructs a value object.| -|[set::rbegin (STL/CLR)](#rbegin)|Designates the beginning of the reversed controlled sequence.| -|[set::rend (STL/CLR)](#rend)|Designates the end of the reversed controlled sequence.| -|[set::set (STL/CLR)](#set)|Constructs a container object.| -|[set::size (STL/CLR)](#size)|Counts the number of elements.| -|[set::swap (STL/CLR)](#swap)|Swaps the contents of two containers.| -|[set::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| -|[set::upper_bound (STL/CLR)](#upper_bound)|Finds end of range that matches a specified key.| -|[set::value_comp (STL/CLR)](#value_comp)|Copies the ordering delegate for two element values.| - -|Operator|Description| -|--------------|-----------------| -|[set::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (set) (STL/CLR)](#op_neq)|Determines if a `set` object is not equal to another `set` object.| -|[operator< (set) (STL/CLR)](#op_lt)|Determines if a `set` object is less than another `set` object.| -|[operator<= (set) (STL/CLR)](#op_lteq)|Determines if a `set` object is less than or equal to another `set` object.| -|[operator== (set) (STL/CLR)](#op_eq)|Determines if a `set` object is equal to another `set` object.| -|[operator> (set) (STL/CLR)](#op_gt)|Determines if a `set` object is greater than another `set` object.| -|[operator>= (set) (STL/CLR)](#op_gteq)|Determines if a `set` object is greater than or equal to another `set` object.| +| Type definition | Description | +|---|---| +| [`set::const_iterator`](#const_iterator) | The type of a constant iterator for the controlled sequence. | +| [`set::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`set::const_reverse_iterator`](#const_reverse_iterator) | The type of a constant reverse iterator for the controlled sequence. | +| [`set::difference_type`](#difference_type) | The type of a (possibly signed) distance between two elements. | +| [`set::generic_container`](#generic_container) | The type of the generic interface for the container. | +| [`set::generic_iterator`](#generic_iterator) | The type of an iterator for the generic interface for the container. | +| [`set::generic_reverse_iterator`](#generic_reverse_iterator) | The type of a reverse iterator for the generic interface for the container. | +| [`set::generic_value`](#generic_value) | The type of an element for the generic interface for the container. | +| [`set::iterator`](#iterator) | The type of an iterator for the controlled sequence. | +| [`set::key_compare`](#key_compare) | The ordering delegate for two keys. | +| [`set::key_type`](#key_type) | The type of an ordering key. | +| [`set::reference`](#reference) | The type of a reference to an element. | +| [`set::reverse_iterator`](#reverse_iterator) | The type of a reverse iterator for the controlled sequence. | +| [`set::size_type`](#size_type) | The type of a (non-negative) distance between two elements. | +| [`set::value_compare`](#value_compare) | The ordering delegate for two element values. | +| [`set::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`set::begin`](#begin) | Designates the beginning of the controlled sequence. | +| [`set::clear`](#clear) | Removes all elements. | +| [`set::count`](#count) | Counts elements matching a specified key. | +| [`set::empty`](#empty) | Tests whether no elements are present. | +| [`set::end`](#end) | Designates the end of the controlled sequence. | +| [`set::equal_range`](#equal_range) | Finds range that matches a specified key. | +| [`set::erase`](#erase) | Removes elements at specified positions. | +| [`set::find`](#find) | Finds an element that matches a specified key. | +| [`set::insert`](#insert) | Adds elements. | +| [`set::key_comp`](#key_comp) | Copies the ordering delegate for two keys. | +| [`set::lower_bound`](#lower_bound) | Finds beginning of range that matches a specified key. | +| [`set::make_value`](#make_value) | Constructs a value object. | +| [`set::rbegin`](#rbegin) | Designates the beginning of the reversed controlled sequence. | +| [`set::rend`](#rend) | Designates the end of the reversed controlled sequence. | +| [`set::set`](#set) | Constructs a container object. | +| [`set::size`](#size) | Counts the number of elements. | +| [`set::swap`](#swap) | Swaps the contents of two containers. | +| [`set::to_array`](#to_array) | Copies the controlled sequence to a new array. | +| [`set::upper_bound`](#upper_bound) | Finds end of range that matches a specified key. | +| [`set::value_comp`](#value_comp) | Copies the ordering delegate for two element values. | + +| Operator | Description | +|---|---| +| [`set::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (set)](#op_neq) | Determines if a `set` object isn't equal to another `set` object. | +| [`operator<` (set)](#op_lt) | Determines if a `set` object is less than another `set` object. | +| [`operator<=` (set)](#op_lteq) | Determines if a `set` object is less than or equal to another `set` object. | +| [`operator==` (set)](#op_eq) | Determines if a `set` object is equal to another `set` object. | +| [`operator>` (set)](#op_gt) | Determines if a `set` object is greater than another `set` object. | +| [`operator>=` (set)](#op_gteq) | Determines if a `set` object is greater than or equal to another `set` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -||Sequence through elements.| -||Maintain group of elements.| -||Sequence through typed elements.| -||Maintain group of typed elements.| -|ITree\|Maintain generic container.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| | Sequence through elements. | +| | Maintain group of elements. | +| | Sequence through typed elements. | +| | Maintain group of typed elements. | +| `ITree` | Maintain generic container. | ## Remarks The object allocates and frees storage for the sequence it controls as individual nodes. It inserts elements into a (nearly) balanced tree that it keeps ordered by altering the links between nodes, never by copying the contents of one node to another. That means you can insert and remove elements freely without disturbing remaining elements. -The object orders the sequence it controls by calling a stored delegate object of type [set::key_compare (STL/CLR)](#key_compare). You can specify the stored delegate object when you construct the set; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [set::key_comp (STL/CLR)](#key_comp)`()`. +The object orders the sequence it controls by calling a stored delegate object of type [`set::key_compare`](#key_compare). You can specify the stored delegate object when you construct the set; if you specify no delegate object, the default is the comparison `operator<(key_type, key_type)`. You access this stored object by calling the member function [`set::key_comp`](#key_comp). -Such a delegate object must impose a strict weak ordering on keys of type [set::key_type (STL/CLR)](#key_type). That means, for any two keys `X` and `Y`: +Such a delegate object must impose a strict weak ordering on keys of type [`set::key_type`](#key_type). That means, for any two keys `X` and `Y`: `key_comp()(X, Y)` returns the same Boolean result on every call. @@ -121,21 +121,21 @@ If `key_comp()(X, Y)` is true, then `X` is said to be ordered before `Y`. If `!key_comp()(X, Y) && !key_comp()(Y, X)` is true, then `X` and `Y` are said to have equivalent ordering. -For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set](../dotnet/set-stl-clr.md), an object of template class `set` does not require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) +For any element `X` that precedes `Y` in the controlled sequence, `key_comp()(Y, X)` is false. (For the default delegate object, keys never decrease in value.) Unlike template class [set](../dotnet/set-stl-clr.md), an object of template class `set` doesn't require that keys for all elements are unique. (Two or more keys can have equivalent ordering.) -Each element serves as both a ey and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element with a number of operations proportional to the logarithm of the number of elements in the sequence (logarithmic time). Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators which point at the removed element. +Each element serves as both a key and a value. The sequence is represented in a way that permits lookup, insertion, and removal of an arbitrary element in logarithmic time. That is, the number of operations is proportional to the logarithm of the number of elements in the sequence. Moreover, inserting an element invalidates no iterators, and removing an element invalidates only those iterators that point at the removed element. -A set supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [set::end (STL/CLR)](#end)`()`. You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a set iterator to reach the head node, and it will then compare equal to `end()`. But you cannot dereference the iterator returned by `end()`. +A `set` supports bidirectional iterators, which means you can step to adjacent elements given an iterator that designates an element in the controlled sequence. A special head node corresponds to the iterator returned by [`end()`](#end). You can decrement this iterator to reach the last element in the controlled sequence, if present. You can increment a `set` iterator to reach the head node, and it will then compare equal to `end()`. But you can't dereference the iterator returned by `end()`. -Note that you cannot refer to a set element directly given its numerical position -- that requires a random-access iterator. +You can't refer to a `set` element directly given its numerical position. That requires a random-access iterator. -A set iterator stores a handle to its associated set node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A set iterator remains valid so long as its associated set node is associated with some set. Moreover, a valid iterator is dereferencable -- you can use it to access or alter the element value it designates -- so long as it is not equal to `end()`. +A `set` iterator stores a handle to its associated `set` node, which in turn stores a handle to its associated container. You can use iterators only with their associated container objects. A `set` iterator remains valid so long as its associated `set` node is associated with some set. Moreover, a valid iterator is dereferencable. You can use it to access or alter the element value it designates, so long as it isn't equal to `end()`. -Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. Note, however, that a container of handles does *not* destroy its elements. +Erasing or removing an element calls the destructor for its stored value. Destroying the container erases all elements. Thus, a container whose element type is a ref class ensures that no elements outlive the container. However, a container of handles doesn't destroy its elements. ## Members -## set::begin (STL/CLR) +## `set::begin` Designates the beginning of the controlled sequence. @@ -183,7 +183,7 @@ a b c *++begin() = b ``` -## set::clear (STL/CLR) +## `set::clear` Removes all elements. @@ -195,7 +195,7 @@ void clear(); ### Remarks -The member function effectively calls [set::erase (STL/CLR)](#erase)`(` [set::begin (STL/CLR)](#begin)`(),` [set::end (STL/CLR)](#end)`())`. You use it to ensure that the controlled sequence is empty. +The member function effectively calls `erase(begin(), end())`. You use it to ensure that the controlled sequence is empty. ### Example @@ -241,7 +241,7 @@ a b size() = 0 ``` -## set::const_iterator (STL/CLR) +## `set::const_iterator` The type of a constant iterator for the controlled sequence. @@ -283,7 +283,7 @@ int main() a b c ``` -## set::const_reference (STL/CLR) +## `set::const_reference` The type of a constant reference to an element. @@ -328,9 +328,9 @@ int main() a b c ``` -## set::const_reverse_iterator (STL/CLR) +## `set::const_reverse_iterator` -The type of a constant reverse iterator for the controlled sequence.. +The type of a constant reverse iterator for the controlled sequence. ### Syntax @@ -370,7 +370,7 @@ int main() c b a ``` -## set::count (STL/CLR) +## `set::count` Finds the number of elements matching a specified key. @@ -382,12 +382,12 @@ size_type count(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function returns the number of elements in the controlled sequence that have equivalent ordering with *key*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. +The member function returns the number of elements in the controlled sequence that have equivalent ordering with *`key`*. You use it to determine the number of elements currently in the controlled sequence that match a specified key. ### Example @@ -423,7 +423,7 @@ count(L'b') = 1 count(L'C') = 0 ``` -## set::difference_type (STL/CLR) +## `set::difference_type` The types of a signed distance between two elements. @@ -478,7 +478,7 @@ end()-begin() = 3 begin()-end() = -3 ``` -## set::empty (STL/CLR) +## `set::empty` Tests whether no elements are present. @@ -490,7 +490,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [set::size (STL/CLR)](#size)`() == 0`. You use it to test whether the set is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `set` is empty. ### Example @@ -530,7 +530,7 @@ size() = 0 empty() = True ``` -## set::end (STL/CLR) +## `set::end` Designates the end of the controlled sequence. @@ -542,7 +542,7 @@ iterator end(); ### Remarks -The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn not change if the length of the controlled sequence changes. +The member function returns a bidirectional iterator that points just beyond the end of the controlled sequence. You use it to obtain an iterator that designates the end of the controlled sequence; its status doesn't change if the length of the controlled sequence changes. ### Example @@ -579,7 +579,7 @@ a b c *--end() = c ``` -## set::equal_range (STL/CLR) +## `set::equal_range` Finds range that matches a specified key. @@ -591,12 +591,12 @@ cliext::pair equal_range(key_type key); #### Parameters -*key*
+*`key`*
Key value to search for. ### Remarks -The member function returns a pair of iterators `cliext::pair(` [set::lower_bound (STL/CLR)](#lower_bound)`(key),` [set::upper_bound (STL/CLR)](#upper_bound)`(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. +The member function returns a pair of iterators `cliext::pair(lower_bound(key), upper_bound(key))`. You use it to determine the range of elements currently in the controlled sequence that match a specified key. ### Example @@ -639,7 +639,7 @@ equal_range(L'x') empty = True b ``` -## set::erase (STL/CLR) +## `set::erase` Removes elements at specified positions. @@ -653,25 +653,25 @@ size_type erase(key_type key) #### Parameters -*first*
+*`first`*\ Beginning of range to erase. -*key*
+*`key`*\ Key value to erase. -*last*
+*`last`*\ End of range to erase. -*where*
+*`where`*\ Element to erase. ### Remarks -The first member function removes the element of the controlled sequence pointed to by *where*, and returns an iterator that designates the first element remaining beyond the element removed, or [set::end (STL/CLR)](#end)`()` if no such element exists. You use it to remove a single element. +The first member function removes the element of the controlled sequence pointed to by *`where`*, and returns an iterator that designates the first element remaining beyond the element removed, or [`end()`](#end) if no such element exists. You use it to remove a single element. -The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists.. You use it to remove zero or more contiguous elements. +The second member function removes the elements of the controlled sequence in the range [`first`, `last`), and returns an iterator that designates the first element remaining beyond any elements removed, or `end()` if no such element exists. You use it to remove zero or more contiguous elements. -The third member function removes any element of the controlled sequence whose key has equivalent ordering to *key*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. +The third member function removes any element of the controlled sequence whose key has equivalent ordering to *`key`*, and returns a count of the number of elements removed. You use it to remove and count all elements that match a specified key. Each element erasure takes time proportional to the logarithm of the number of elements in the controlled sequence. @@ -723,7 +723,7 @@ erase(begin(), end()-1) = e size() = 1 ``` -## set::find (STL/CLR) +## `set::find` Finds an element that matches a specified key. @@ -735,12 +735,12 @@ iterator find(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -If at least one element in the controlled sequence has equivalent ordering with *key*, the member function returns an iterator designating one of those elements; otherwise it returns [set::end (STL/CLR)](#end)`()`. You use it to locate an element currently in the controlled sequence that matches a specified key. +If at least one element in the controlled sequence has equivalent ordering with *`key`*, the member function returns an iterator designating one of those elements; otherwise it returns [`end()`](#end). You use it to locate an element currently in the controlled sequence that matches a specified key. ### Example @@ -779,7 +779,7 @@ find b = b find C = False ``` -## set::generic_container (STL/CLR) +## `set::generic_container` The type of the generic interface for the container. @@ -843,7 +843,7 @@ a b c d a b c d e ``` -## set::generic_iterator (STL/CLR) +## `set::generic_iterator` The type of an iterator for use with the generic interface for the container. @@ -899,7 +899,7 @@ a b c a ``` -## set::generic_reverse_iterator (STL/CLR) +## `set::generic_reverse_iterator` The type of a reverse iterator for use with the generic interface for the container. @@ -955,7 +955,7 @@ a b c c ``` -## set::generic_value (STL/CLR) +## `set::generic_value` The type of an element for use with the generic interface for the container. @@ -1009,7 +1009,7 @@ a b c a ``` -## set::insert (STL/CLR) +## `set::insert` Adds elements. @@ -1025,34 +1025,34 @@ void insert(System::Collections::Generic::IEnumerable^ right); #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*right*
+*`right`*\ Enumeration to insert. -*val*
+*`val`*\ Key value to insert. -*where*
+*`where`*\ Where in container to insert (hint only). ### Remarks Each of the member functions inserts a sequence specified by the remaining operands. -The first member function endeavors to insert an element with value *val*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. +The first member function endeavors to insert an element with value *`val`*, and returns a pair of values `X`. If `X.second` is true, `X.first` designates the newly inserted element; otherwise `X.first` designates an element with equivalent ordering that already exists and no new element is inserted. You use it to insert a single element. -The second member function inserts an element with value *val*, using *where* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element which might be adjacent to an element you know. +The second member function inserts an element with value *`val`*, using *`where`* as a hint (to improve performance), and returns an iterator that designates the newly inserted element. You use it to insert a single element that might be next to an element you know. The third member function inserts the sequence [`first`, `last`). You use it to insert zero or more elements copied from another sequence. -The fourth member function inserts the sequence designated by the *right*. You use it to insert a sequence described by an enumerator. +The fourth member function inserts the sequence designated by the *`right`*. You use it to insert a sequence described by an enumerator. -Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element adjacent to the insertion point. +Each element insertion takes time proportional to the logarithm of the number of elements in the controlled sequence. Insertion can occur in amortized constant time, however, given a hint that designates an element next to the insertion point. ### Example @@ -1125,7 +1125,7 @@ a b c x a b c x y ``` -## set::iterator (STL/CLR) +## `set::iterator` The type of an iterator for the controlled sequence. @@ -1167,7 +1167,7 @@ int main() a b c ``` -## set::key_comp (STL/CLR) +## `set::key_comp` Copies the ordering delegate for two keys. @@ -1226,7 +1226,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## set::key_compare (STL/CLR) +## `set::key_compare` The ordering delegate for two keys. @@ -1286,7 +1286,7 @@ compare(L'a', L'b') = False compare(L'b', L'a') = True ``` -## set::key_type (STL/CLR) +## `set::key_type` The type of an ordering key. @@ -1298,7 +1298,7 @@ typedef Key key_type; ### Remarks -The type is a synonym for the template parameter *Key*. +The type is a synonym for the template parameter *`Key`*. ### Example @@ -1331,7 +1331,7 @@ int main() a b c ``` -## set::lower_bound (STL/CLR) +## `set::lower_bound` Finds beginning of range that matches a specified key. @@ -1343,12 +1343,12 @@ iterator lower_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, it returns [set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the first element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, it returns [`end()`](#end); otherwise it returns an iterator that designates `X`. You use it to locate the beginning of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -1388,7 +1388,7 @@ lower_bound(L'x')==end() = True *lower_bound(L'b') = b ``` -## set::make_value (STL/CLR) +## `set::make_value` Constructs a value object. @@ -1400,12 +1400,12 @@ static value_type make_value(key_type key); #### Parameters -*key*
+*`key`*\ Key value to use. ### Remarks -The member function returns a `value_type` object whose key is *key*. You use it to compose an object suitable for use with several other member functions. +The member function returns a `value_type` object whose key is *`key`*. You use it to compose an object suitable for use with several other member functions. ### Example @@ -1434,7 +1434,7 @@ int main() a b c ``` -## set::operator= (STL/CLR) +## `set::operator=` Replaces the controlled sequence. @@ -1446,12 +1446,12 @@ set% operator=(set% right); #### Parameters -*right*
+*`right`*\ Container to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -1489,7 +1489,7 @@ a b c a b c ``` -## set::rbegin (STL/CLR) +## `set::rbegin` Designates the beginning of the reversed controlled sequence. @@ -1537,7 +1537,7 @@ a b c *++rbegin() = b ``` -## set::reference (STL/CLR) +## `set::reference` The type of a reference to an element. @@ -1582,7 +1582,7 @@ int main() a b c ``` -## set::rend (STL/CLR) +## `set::rend` Designates the end of the reversed controlled sequence. @@ -1631,7 +1631,7 @@ a b c *--rend() = a ``` -## set::reverse_iterator (STL/CLR) +## `set::reverse_iterator` The type of a reverse iterator for the controlled sequence. @@ -1673,7 +1673,7 @@ int main() c b a ``` -## set::set (STL/CLR) +## `set::set` Constructs a container object. @@ -1696,16 +1696,16 @@ set(System::Collections::Generic::IEnumerable^ right, #### Parameters -*first*
+*`first`*\ Beginning of range to insert. -*last*
+*`last`*\ End of range to insert. -*pred*
+*`pred`*\ Ordering predicate for the controlled sequence. -*right*
+*`right`*\ Object or range to insert. ### Remarks @@ -1720,19 +1720,19 @@ The constructor: `explicit set(key_compare^ pred);` -initializes the controlled sequence with no elements, with the ordering predicate *pred*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. +initializes the controlled sequence with no elements, with the ordering predicate *`pred`*. You use it to specify an empty initial controlled sequence, with the specified ordering predicate. The constructor: `set(set% right);` -initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the set object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right.begin()`, `right.end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `set` object *`right`*, with the default ordering predicate. The constructor: `set(set^ right);` -initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the set object *right*, with the default ordering predicate. +initializes the controlled sequence with the sequence [`right->begin()`, `right->end()`), with the default ordering predicate. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `set` object *`right`*, with the default ordering predicate. The constructor: @@ -1744,19 +1744,19 @@ The constructor: `template set(InIter first, InIter last, key_compare^ pred);` -initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. +initializes the controlled sequence with the sequence [`first`, `last`), with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence, with the specified ordering predicate. The constructor: `set(System::Collections::Generic::IEnumerable^ right);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the default ordering predicate. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the default ordering predicate. The constructor: `set(System::Collections::Generic::IEnumerable^ right, key_compare^ pred);` -initializes the controlled sequence with the sequence designated by the enumerator *right*, with the ordering predicate *pred*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. +initializes the controlled sequence with the sequence designated by the enumerator *`right`*, with the ordering predicate *`pred`*. You use it to make the controlled sequence a copy of another sequence described by an enumerator, with the specified ordering predicate. ### Example @@ -1844,7 +1844,7 @@ c b a a b c ``` -## set::size (STL/CLR) +## `set::size` Counts the number of elements. @@ -1856,7 +1856,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [set::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`empty()`](#empty). ### Example @@ -1898,9 +1898,9 @@ size() = 0 after clearing size() = 2 after adding 2 ``` -## set::size_type (STL/CLR) +## `set::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -1946,7 +1946,7 @@ a b c end()-begin() = 3 ``` -## set::swap (STL/CLR) +## `set::swap` Swaps the contents of two containers. @@ -1958,12 +1958,12 @@ void swap(set% right); #### Parameters -*right*
+*`right`*\ Container to swap contents with. ### Remarks -The member function swaps the controlled sequences between **`this`** and *right*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. +The member function swaps the controlled sequences between **`this`** and *`right`*. It does so in constant time and it throws no exceptions. You use it as a quick way to exchange the contents of two containers. ### Example @@ -2014,7 +2014,7 @@ d e f a b c ``` -## set::to_array (STL/CLR) +## `set::to_array` Copies the controlled sequence to a new array. @@ -2064,7 +2064,7 @@ a b c d a b c ``` -## set::upper_bound (STL/CLR) +## `set::upper_bound` Finds end of range that matches a specified key. @@ -2076,12 +2076,12 @@ iterator upper_bound(key_type key); #### Parameters -*key*
+*`key`*\ Key value to search for. ### Remarks -The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *key*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [set::end (STL/CLR)](#end)`()`; otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. +The member function determines the last element `X` in the controlled sequence that has equivalent ordering to *`key`*. If no such element exists, or if `X` is the last element in the controlled sequence, it returns [`end()`](#end); otherwise it returns an iterator that designates the first element beyond `X`. You use it to locate the end of a sequence of elements currently in the controlled sequence that match a specified key. ### Example @@ -2121,7 +2121,7 @@ upper_bound(L'x')==end() = True *upper_bound(L'b') = c ``` -## set::value_comp (STL/CLR) +## `set::value_comp` Copies the ordering delegate for two element values. @@ -2165,7 +2165,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## set::value_compare (STL/CLR) +## `set::value_compare` The ordering delegate for two element values. @@ -2210,7 +2210,7 @@ compare(L'a', L'b') = True compare(L'b', L'a') = False ``` -## set::value_type (STL/CLR) +## `set::value_type` The type of an element. @@ -2255,7 +2255,7 @@ int main() a b c ``` -## operator!= (set) (STL/CLR) +## `operator!=` (set) List not equal comparison. @@ -2269,15 +2269,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two sets are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two sets are compared element by element. ### Example @@ -2325,7 +2325,7 @@ a b d [a b c] != [a b d] is True ``` -## `operator<` (set) (STL/CLR) +## `operator<` (set) List less than comparison. @@ -2339,15 +2339,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()` You use it to test whether *left* is ordered before *right* when the two sets are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two sets are compared element by element. ### Example @@ -2395,7 +2395,7 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (set) (STL/CLR) +## `operator<=` (set) List less than or equal comparison. @@ -2409,15 +2409,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two sets are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two sets are compared element by element. ### Example @@ -2465,7 +2465,7 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (set) (STL/CLR) +## `operator==` (set) List equal comparison. @@ -2479,15 +2479,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two sets are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two sets are compared element by element. ### Example @@ -2535,7 +2535,7 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (set) (STL/CLR) +## `operator>` (set) List greater than comparison. @@ -2549,15 +2549,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two sets are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two sets are compared element by element. ### Example @@ -2605,7 +2605,7 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (set) (STL/CLR) +## `operator>=` (set) List greater than or equal comparison. @@ -2619,15 +2619,15 @@ template #### Parameters -*left*
+*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two sets are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two sets are compared element by element. ### Example diff --git a/docs/dotnet/stack-stl-clr.md b/docs/dotnet/stack-stl-clr.md index 75ea0945df9..c5fae0dceb3 100644 --- a/docs/dotnet/stack-stl-clr.md +++ b/docs/dotnet/stack-stl-clr.md @@ -7,11 +7,11 @@ f1_keywords: ["cliext::stack", "cliext::stack::assign", "cliext::stack::const_re helpviewer_keywords: [" header [STL/CLR]", " header [STL/CLR]", "stack class [STL/CLR]", "operator!= member [STL/CLR]", "operator< member [STL/CLR]", "operator<= member [STL/CLR]", "operator== member [STL/CLR]", "operator> member [STL/CLR]", "operator>= member [STL/CLR]", "assign member [STL/CLR]", "const_reference member [STL/CLR]", "container_type member [STL/CLR]", "difference_type member [STL/CLR]", "empty member [STL/CLR]", "generic_container member [STL/CLR]", "generic_value member [STL/CLR]", "get_container member [STL/CLR]", "operator= member [STL/CLR]", "pop member [STL/CLR]", "push member [STL/CLR]", "reference member [STL/CLR]", "size member [STL/CLR]", "size_type member [STL/CLR]", "stack member [STL/CLR]", "to_array member [STL/CLR]", "top member [STL/CLR]", "top_item member [STL/CLR]", "value_type member [STL/CLR]"] ms.assetid: 6ee96b9f-8a33-4cf7-b7e0-6535c24bdefb --- -# stack (STL/CLR) +# `stack` (STL/CLR) The template class describes an object that controls a varying-length sequence of elements that has last-in first-out access. You use the container adapter `stack` to manage an underlying container as a push-down stack. -In the description below, `GValue` is the same as *Value* unless the latter is a ref type, in which case it is `Value^`. Similarly, `GContainer` is the same as *Container* unless the latter is a ref type, in which case it is `Container^`. +In the description below, `GValue` is the same as *`Value`* unless the latter is a ref type, in which case it's `Value^`. Similarly, `GContainer` is the same as *`Container`* unless the latter is a ref type, in which case it's `Container^`. ## Syntax @@ -27,71 +27,71 @@ template +*`Value`*\ The type of an element in the controlled sequence. -*Container*
+*`Container`*\ The type of the underlying container. ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Type Definition|Description| -|---------------------|-----------------| -|[stack::const_reference (STL/CLR)](#const_reference)|The type of a constant reference to an element.| -|[stack::container_type (STL/CLR)](#container_type)|The type of the underlying container.| -|[stack::difference_type (STL/CLR)](#difference_type)|The type of a signed distance between two elements.| -|[stack::generic_container (STL/CLR)](#generic_container)|The type of the generic interface for the container adapter.| -|[stack::generic_value (STL/CLR)](#generic_value)|The type of an element for the generic interface for the container adapter.| -|[stack::reference (STL/CLR)](#reference)|The type of a reference to an element.| -|[stack::size_type (STL/CLR)](#size_type)|The type of a signed distance between two elements.| -|[stack::value_type (STL/CLR)](#value_type)|The type of an element.| - -|Member Function|Description| -|---------------------|-----------------| -|[stack::assign (STL/CLR)](#assign)|Replaces all elements.| -|[stack::empty (STL/CLR)](#empty)|Tests whether no elements are present.| -|[stack::get_container (STL/CLR)](#get_container)|Accesses the underlying container.| -|[stack::pop (STL/CLR)](#pop)|Removes the last element.| -|[stack::push (STL/CLR)](#push)|Adds a new last element.| -|[stack::size (STL/CLR)](#size)|Counts the number of elements.| -|[stack::stack (STL/CLR)](#stack)|Constructs a container object.| -|[stack::top (STL/CLR)](#top)|Accesses the last element.| -|[stack::to_array (STL/CLR)](#to_array)|Copies the controlled sequence to a new array.| - -|Property|Description| -|--------------|-----------------| -|[stack::top_item (STL/CLR)](#top_item)|Accesses the last element.| - -|Operator|Description| -|--------------|-----------------| -|[stack::operator= (STL/CLR)](#op_as)|Replaces the controlled sequence.| -|[operator!= (stack) (STL/CLR)](#op_neq)|Determines if a `stack` object is not equal to another `stack` object.| -|[operator< (stack) (STL/CLR)](#op_lt)|Determines if a `stack` object is less than another `stack` object.| -|[operator<= (stack) (STL/CLR)](#op_lteq)|Determines if a `stack` object is less than or equal to another `stack` object.| -|[operator== (stack) (STL/CLR)](#op_eq)|Determines if a `stack` object is equal to another `stack` object.| -|[operator> (stack) (STL/CLR)](#op_gt)|Determines if a `stack` object is greater than another `stack` object.| -|[operator>= (stack) (STL/CLR)](#op_gteq)|Determines if a `stack` object is greater than or equal to another `stack` object.| +| Type definition | Description | +|---|---| +| [`stack::const_reference`](#const_reference) | The type of a constant reference to an element. | +| [`stack::container_type`](#container_type) | The type of the underlying container. | +| [`stack::difference_type`](#difference_type) | The type of a signed distance between two elements. | +| [`stack::generic_container`](#generic_container) | The type of the generic interface for the container adapter. | +| [`stack::generic_value`](#generic_value) | The type of an element for the generic interface for the container adapter. | +| [`stack::reference`](#reference) | The type of a reference to an element. | +| [`stack::size_type`](#size_type) | The type of a signed distance between two elements. | +| [`stack::value_type`](#value_type) | The type of an element. | + +| Member function | Description | +|---|---| +| [`stack::assign`](#assign) | Replaces all elements. | +| [`stack::empty`](#empty) | Tests whether no elements are present. | +| [`stack::get_container`](#get_container) | Accesses the underlying container. | +| [`stack::pop`](#pop) | Removes the last element. | +| [`stack::push`](#push) | Adds a new last element. | +| [`stack::size`](#size) | Counts the number of elements. | +| [`stack::stack`](#stack) | Constructs a container object. | +| [`stack::top`](#top) | Accesses the last element. | +| [`stack::to_array`](#to_array) | Copies the controlled sequence to a new array. | + +| Property | Description | +|---|---| +| [`stack::top_item`](#top_item) | Accesses the last element. | + +| Operator | Description | +|---|---| +| [`stack::operator=`](#op_as) | Replaces the controlled sequence. | +| [`operator!=` (stack)](#op_neq) | Determines if a `stack` object isn't equal to another `stack` object. | +| [`operator<` (stack)](#op_lt) | Determines if a `stack` object is less than another `stack` object. | +| [`operator<=` (stack)](#op_lteq) | Determines if a `stack` object is less than or equal to another `stack` object. | +| [`operator==` (stack)](#op_eq) | Determines if a `stack` object is equal to another `stack` object. | +| [`operator>` (stack)](#op_gt) | Determines if a `stack` object is greater than another `stack` object. | +| [`operator>=` (stack)](#op_gteq) | Determines if a `stack` object is greater than or equal to another `stack` object. | ## Interfaces -|Interface|Description| -|---------------|-----------------| -||Duplicate an object.| -|IStack\|Maintain generic container adapter.| +| Interface | Description | +|---|---| +| | Duplicate an object. | +| `IStack` | Maintain generic container adapter. | ## Remarks -The object allocates and frees storage for the sequence it controls through an underlying container, of type *Container*, that stores *Value* elements and grows on demand. The object restricts access to pushing and popping just the last element, implementing a last-in first-out queue (also known as a LIFO queue, or stack). +The object allocates and frees storage for the sequence it controls through an underlying container of type *`Container`* that stores *`Value`* elements and grows on demand. The object restricts access to pushing and popping just the last element, implementing a last-in first-out queue (also known as a LIFO queue, or stack). ## Members -## stack::assign (STL/CLR) +## `stack::assign` Replaces all elements. @@ -103,7 +103,7 @@ void assign(stack% right); #### Parameters -*right*
+*`right`*\ Container adapter to insert. ### Remarks @@ -145,7 +145,7 @@ a b c a b c ``` -## stack::const_reference (STL/CLR) +## `stack::const_reference` The type of a constant reference to an element. @@ -189,7 +189,7 @@ int main() c b a ``` -## stack::container_type (STL/CLR) +## `stack::container_type` The type of the underlying container. @@ -201,7 +201,7 @@ typedef Container value_type; ### Remarks -The type is a synonym for the template parameter *Container*. +The type is a synonym for the template parameter *`Container`*. ### Example @@ -231,7 +231,7 @@ int main() a b c ``` -## stack::difference_type (STL/CLR) +## `stack::difference_type` The types of a signed distance between two elements. @@ -289,7 +289,7 @@ pushing 2 = -2 popping 3 = 3 ``` -## stack::empty (STL/CLR) +## `stack::empty` Tests whether no elements are present. @@ -301,7 +301,7 @@ bool empty(); ### Remarks -The member function returns true for an empty controlled sequence. It is equivalent to [stack::size (STL/CLR)](#size)`() == 0`. You use it to test whether the stack is empty. +The member function returns true for an empty controlled sequence. It's equivalent to `size() == 0`. You use it to test whether the `stack` is empty. ### Example @@ -343,7 +343,7 @@ size() = 0 empty() = True ``` -## stack::generic_container (STL/CLR) +## `stack::generic_container` The type of the generic interface for the container adapter. @@ -406,7 +406,7 @@ a b c d a b c d e ``` -## stack::generic_value (STL/CLR) +## `stack::generic_value` The type of an element for use with the generic interface for the container. @@ -464,7 +464,7 @@ a b c c b a ``` -## stack::get_container (STL/CLR) +## `stack::get_container` Accesses the underlying container. @@ -506,24 +506,24 @@ int main() a b c ``` -## stack::operator= (STL/CLR) +## `stack::operator=` Replaces the controlled sequence. ### Syntax ```cpp -stack % operator=(stack % right); +stack% operator=(stack% right); ``` #### Parameters -*right*
+*`right`*\ Container adapter to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the controlled sequence with a copy of the controlled sequence in *`right`*. ### Example @@ -560,7 +560,7 @@ a b c a b c ``` -## stack::pop (STL/CLR) +## `stack::pop` Removes the last element. @@ -572,7 +572,7 @@ void pop(); ### Remarks -The member function removes the last element of the controlled sequence, which must be non-empty. You use it to shorten the stack by one element at the back. +The member function removes the last element of the controlled sequence, which must be non-empty. You use it to shorten the `stack` by one element at the back. ### Example @@ -608,7 +608,7 @@ a b c a b ``` -## stack::push (STL/CLR) +## `stack::push` Adds a new last element. @@ -649,7 +649,7 @@ int main() a b c ``` -## stack::reference (STL/CLR) +## `stack::reference` The type of a reference to an element. @@ -698,7 +698,7 @@ a b c a b x ``` -## stack::size (STL/CLR) +## `stack::size` Counts the number of elements. @@ -710,7 +710,7 @@ size_type size(); ### Remarks -The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [stack::empty (STL/CLR)](#empty)`()`. +The member function returns the length of the controlled sequence. You use it to determine the number of elements currently in the controlled sequence. If all you care about is whether the sequence has nonzero size, see [`stack::empty`](#empty). ### Example @@ -752,9 +752,9 @@ size() = 2 after popping size() = 4 after adding 2 ``` -## stack::size_type (STL/CLR) +## `stack::size_type` -The type of a signed distance between two element. +The type of a signed distance between two elements. ### Syntax @@ -801,7 +801,7 @@ a b c size difference = 2 ``` -## stack::stack (STL/CLR) +## `stack::stack` Constructs a container adapter object. @@ -816,10 +816,10 @@ explicit stack(container_type% wrapped); #### Parameters -*right*
+*`right`*\ Object to copy. -*wrapped*
+*`wrapped`*\ Wrapped container to use. ### Remarks @@ -834,19 +834,19 @@ The constructor: `stack(stack% right);` -creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the stack object *right*. +creates a wrapped container that is a copy of `right.get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `stack` object *`right`*. The constructor: `stack(stack^ right);` -creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the stack object `*right`. +creates a wrapped container that is a copy of `right->get_container()`. You use it to specify an initial controlled sequence that is a copy of the sequence controlled by the `stack` object `*right`. The constructor: `explicit stack(container_type% wrapped);` -uses the existing container *wrapped* as the wrapped container. You use it to construct a stack from an existing container. +uses the existing container *`wrapped`* as the wrapped container. You use it to construct a `stack` from an existing container. ### Example @@ -894,7 +894,7 @@ x x x x x x x x x x ``` -## stack::to_array (STL/CLR) +## `stack::to_array` Copies the controlled sequence to a new array. @@ -944,7 +944,7 @@ a b c d a b c ``` -## stack::top (STL/CLR) +## `stack::top` Accesses the last element. @@ -956,7 +956,7 @@ reference top(); ### Remarks -The member function returns a reference to the last element of the controlled sequence, which must be non-empty. You use it to access the last element, when you know it exists. +The member function returns a reference to the last element of the controlled sequence, which must be non-empty. You use it to access the last element, when you know one exists. ### Example @@ -996,7 +996,7 @@ top() = c a b x ``` -## stack::top_item (STL/CLR) +## `stack::top_item` Accesses the last element. @@ -1008,7 +1008,7 @@ property value_type top_item; ### Remarks -The property accesses the last element of the controlled sequence, which must be non-empty. You use it to read or write the last element, when you know it exists. +The property accesses the last element of the controlled sequence, which must be non-empty. You use it to read or write the last element, when you know one exists. ### Example @@ -1048,7 +1048,7 @@ top_item = c a b x ``` -## stack::value_type (STL/CLR) +## `stack::value_type` The type of an element. @@ -1060,7 +1060,7 @@ typedef Value value_type; ### Remarks -The type is a synonym for the template parameter *Value*. +The type is a synonym for the template parameter *`Value`*. ### Example @@ -1093,9 +1093,9 @@ int main() c b a ``` -## operator!= (stack) (STL/CLR) +## `operator!=` (stack) -Stack not equal comparison. +`Stack` not equal comparison. ### Syntax @@ -1108,15 +1108,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two stacks are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two stacks are compared element by element. ### Example @@ -1164,9 +1164,9 @@ a b d [a b c] != [a b d] is True ``` -## `operator<` (stack) (STL/CLR) +## `operator<` (stack) -Stack less than comparison. +`Stack` less than comparison. ### Syntax @@ -1179,15 +1179,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it is also true that `left[i] < right[i]`. Otherwise, it returns `left->`[stack::size (STL/CLR)](#size)`() <` `right->size()` You use it to test whether *left* is ordered before *right* when the two stacks are compared element by element. +The operator function returns true if, for the lowest position `i` for which `!(right[i] < left[i])` it's also true that `left[i] < right[i]`. Otherwise, it returns `left->size() < right->size()`. You use it to test whether *`left`* is ordered before *`right`* when the two stacks are compared element by element. ### Example @@ -1235,9 +1235,9 @@ a b d [a b c] < [a b d] is True ``` -## `operator<=` (stack) (STL/CLR) +## `operator<=` (stack) -Stack less than or equal comparison. +`Stack` less than or equal comparison. ### Syntax @@ -1250,15 +1250,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two stacks are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two stacks are compared element by element. ### Example @@ -1306,9 +1306,9 @@ a b d [a b d] <= [a b c] is False ``` -## operator== (stack) (STL/CLR) +## `operator==` (stack) -Stack equal comparison. +`Stack` equal comparison. ### Syntax @@ -1321,15 +1321,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns true only if the sequences controlled by *left* and *right* have the same length and, for each position `i`, `left[i] ==` `right[i]`. You use it to test whether *left* is ordered the same as *right* when the two stacks are compared element by element. +The operator function returns true only if the sequences controlled by *`left`* and *`right`* have the same length and, for each position `i`, `left[i] == right[i]`. You use it to test whether *`left`* is ordered the same as *`right`* when the two stacks are compared element by element. ### Example @@ -1377,9 +1377,9 @@ a b d [a b c] == [a b d] is False ``` -## `operator>` (stack) (STL/CLR) +## `operator>` (stack) -Stack greater than comparison. +`Stack` greater than comparison. ### Syntax @@ -1392,15 +1392,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two stacks are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two stacks are compared element by element. ### Example @@ -1448,9 +1448,9 @@ a b d [a b d] > [a b c] is True ``` -## `operator>=` (stack) (STL/CLR) +## `operator>=` (stack) -Stack greater than or equal comparison. +`Stack` greater than or equal comparison. ### Syntax @@ -1463,15 +1463,15 @@ template +*`left`*\ Left container to compare. -*right*
+*`right`*\ Right container to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two stacks are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two stacks are compared element by element. ### Example diff --git a/docs/dotnet/stl-clr-library-reference.md b/docs/dotnet/stl-clr-library-reference.md index e38c1906036..8b2cd934967 100644 --- a/docs/dotnet/stl-clr-library-reference.md +++ b/docs/dotnet/stl-clr-library-reference.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: STL/CLR Library Reference" title: "STL/CLR Library Reference" +description: "Learn more about: STL/CLR Library Reference" ms.date: 09/18/2018 ms.topic: "reference" helpviewer_keywords: ["STL/CLR Library", "STL/CLR, redistribution", "cliext directory"] -ms.assetid: a9d9ca00-7bf2-48c1-b205-3ae6f8c25f82 --- # STL/CLR Library Reference @@ -51,7 +50,7 @@ In addition, this section also describes the following components of STL/CLR: [`hash_multimap` (STL/CLR)](../dotnet/hash-multimap-stl-clr.md)\ [`hash_multiset` (STL/CLR)](../dotnet/hash-multiset-stl-clr.md)\ [`hash_set` (STL/CLR)](../dotnet/hash-set-stl-clr.md)\ - [`list` (STL/CLR)](../dotnet/list-stl-clr.md)\ + [`list` (STL/CLR)](../dotnet/list-stl-clr.md) :::column-end::: :::column span=""::: [`map` (STL/CLR)](../dotnet/map-stl-clr.md)\ @@ -63,7 +62,7 @@ In addition, this section also describes the following components of STL/CLR: [`set` (STL/CLR)](../dotnet/set-stl-clr.md)\ [`stack` (STL/CLR)](../dotnet/stack-stl-clr.md)\ [`utility` (STL/CLR)](../dotnet/utility-stl-clr.md)\ - [`vector` (STL/CLR)](../dotnet/vector-stl-clr.md)\ + [`vector` (STL/CLR)](../dotnet/vector-stl-clr.md) :::column-end::: :::row-end::: diff --git a/docs/dotnet/using-a-windows-form-user-control-in-mfc.md b/docs/dotnet/using-a-windows-form-user-control-in-mfc.md index d5c87478bdd..a4d8bac8ddc 100644 --- a/docs/dotnet/using-a-windows-form-user-control-in-mfc.md +++ b/docs/dotnet/using-a-windows-form-user-control-in-mfc.md @@ -4,6 +4,7 @@ title: "Using a Windows Form User Control in MFC" ms.date: "01/08/2018" helpviewer_keywords: ["MFC [C++], Windows Forms support", "interoperability [C++], Windows Forms in MFC", "interoperability [C++], MFC", "interop [C++], Windows Forms in MFC", "interop [C++], MFC", "Windows Forms [C++], MFC support"] ms.assetid: 63fb099b-1dff-469c-9e34-dab52e122fcd +ms.topic: how-to --- # Using a Windows Form User Control in MFC diff --git a/docs/dotnet/using-cpp-interop-implicit-pinvoke.md b/docs/dotnet/using-cpp-interop-implicit-pinvoke.md index b3fd4a5badb..2cb904144ed 100644 --- a/docs/dotnet/using-cpp-interop-implicit-pinvoke.md +++ b/docs/dotnet/using-cpp-interop-implicit-pinvoke.md @@ -4,6 +4,7 @@ title: "Using C++ Interop (Implicit PInvoke)" ms.date: "11/04/2016" helpviewer_keywords: ["blittable types [C++]", "platform invoke [C++], implicit", "interop [C++], features", "data marshaling [C++], C++ Interop features", "porting [C++], C++ native to .NET", "COM interfaces [C++]", "implicit platform invoke", "examples [C++], interoperability", "types [C++], blittable", "marshaling [C++], C++ Interop features", "platform invoke [C++], examples", "interoperability [C++]", "C++ Interop", "interoperability [C++], Implicit PInvoke", "C++, interop", "C++ COM Interop", ".NET [C++], porting C++ native to"] ms.assetid: 5f710bf1-88ae-4c4e-8326-b3f0b7c4c68a +ms.topic: concept-article --- # Using C++ Interop (Implicit PInvoke) diff --git a/docs/dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md b/docs/dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md index 61b35c6421e..df29926c353 100644 --- a/docs/dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md +++ b/docs/dotnet/using-explicit-pinvoke-in-cpp-dllimport-attribute.md @@ -4,6 +4,7 @@ title: "Using Explicit PInvoke in C++ (DllImport Attribute)" ms.date: "11/04/2016" helpviewer_keywords: ["marshaling [C++], platform invoke", "C++ Interop, platform invoke", "interop [C++], platform invoke", "platform invoke [C++], marshaling in C++", "data marshaling [C++], platform invoke"] ms.assetid: 18e5218c-6916-48a1-a127-f66e22ef15fc +ms.topic: concept-article --- # Using Explicit PInvoke in C++ (DllImport Attribute) diff --git a/docs/dotnet/using-verifiable-assemblies-with-sql-server-cpp-cli.md b/docs/dotnet/using-verifiable-assemblies-with-sql-server-cpp-cli.md index 93acc4fdd74..d6ce13de8ab 100644 --- a/docs/dotnet/using-verifiable-assemblies-with-sql-server-cpp-cli.md +++ b/docs/dotnet/using-verifiable-assemblies-with-sql-server-cpp-cli.md @@ -4,6 +4,7 @@ title: "Using Verifiable Assemblies with SQL Server (C++/CLI)" ms.date: "10/17/2018" helpviewer_keywords: ["verifiable assemblies [C++], with SQL Server"] ms.assetid: 5248a60d-aa88-4ff3-b30a-b791c3ea2de9 +ms.topic: how-to --- # Using Verifiable Assemblies with SQL Server (C++/CLI) diff --git a/docs/dotnet/utility-stl-clr.md b/docs/dotnet/utility-stl-clr.md index 40ae39d5eed..d014d1fc083 100644 --- a/docs/dotnet/utility-stl-clr.md +++ b/docs/dotnet/utility-stl-clr.md @@ -7,42 +7,42 @@ f1_keywords: ["", "cliext::pair", "cliext::pair::pair", "cliext: helpviewer_keywords: [" header [STL/CLR]", "utility header [STL/CLR]", " header [STL/CLR]", "first member [STL/CLR]", "first_type member [STL/CLR]", "second member [STL/CLR]", "second_type member [STL/CLR]", "swap member [STL/CLR]", "make_pair function [STL/CLR]", "pair class [STL/CLR]", "pair member [STL/CLR]", "operator== member [STL/CLR]", "operator= member [STL/CLR]", "operator>= member [STL/CLR]", "operator> member [STL/CLR]", "operator!= member [STL/CLR]", "operator<= member [STL/CLR]", "operator< member [STL/CLR]"] ms.assetid: fb48cb75-d5ef-47ce-b526-bf60dc86c552 --- -# utility (STL/CLR) +# `` (STL/CLR) -Include the STL/CLR header `` to define the template class `pair` and several supporting template functions. +Include the STL/CLR header `` to define the class template `pair` and several supporting function templates. ## Syntax ```cpp -#include +#include ``` ## Requirements **Header:** \ -**Namespace:** cliext +**Namespace:** `cliext` ## Declarations -|Class|Description| -|-----------|-----------------| -|[pair (STL/CLR)](#pair)|Wrap a pair of elements.| +| Class | Description | +|---|---| +| [`pair`](#pair) | Wrap a pair of elements. | -|Operator|Description| -|--------------|-----------------| -|[operator== (pair) (STL/CLR)](#op_eq)|Pair equal comparison.| -|[operator!= (pair) (STL/CLR)](#op_neq)|Pair not equal comparison.| -|[operator< (pair) (STL/CLR)](#op_lt)|Pair less than comparison.| -|[operator\<= (pair) (STL/CLR)](#op_lteq)|Pair less than or equal comparison.| -|[operator> (pair) (STL/CLR)](#op_gt)|Pair greater than comparison.| -|[operator>= (pair) (STL/CLR)](#op_gteq)|Pair greater than or equal comparison.| +| Operator | Description | +|---|---| +| [`operator==` (pair)](#op_eq) | `pair` equal comparison. | +| [`operator!=` (pair)](#op_neq) | `pair` not equal comparison. | +| [`operator<` (pair)](#op_lt) | `pair` less than comparison. | +| [`operator<=` (pair)](#op_lteq) | `pair` less than or equal comparison. | +| [`operator>` (pair)](#op_gt) | `pair` greater than comparison. | +| [`operator>=` (pair)](#op_gteq) | `pair` greater than or equal comparison. | -|Function|Description| -|--------------|-----------------| -|[make_pair (STL/CLR)](#make_pair)|Make a pair from a pair of values.| +| Function | Description | +|---|---| +| [`make_pair`](#make_pair) | Make a `pair` from a pair of values. | -## pair (STL/CLR) +## `pair` The template class describes an object that wraps a pair of values. @@ -56,38 +56,38 @@ template +*`Value1`*\ The type of first wrapped value. -*Value2*
+*`Value2`*\ The type of second wrapped value. ## Members -|Type Definition|Description| -|---------------------|-----------------| -|[pair::first_type (STL/CLR)](#first_type)|The type of the first wrapped value.| -|[pair::second_type (STL/CLR)](#second_type)|The type of the second wrapped value.| +| Type definition | Description | +|---|---| +| [`pair::first_type`](#first_type) | The type of the first wrapped value. | +| [`pair::second_type`](#second_type) | The type of the second wrapped value. | -|Member Object|Description| -|-------------------|-----------------| -|[pair::first (STL/CLR)](#first)|The first stored value.| -|[pair::second (STL/CLR)](#second)|The second stored value.| +| Member object | Description | +|---|---| +| [`pair::first`](#first) | The first stored value. | +| [`pair::second`](#second) | The second stored value. | -|Member Function|Description| -|---------------------|-----------------| -|[pair::pair (STL/CLR)](#pair_pair)|Constructs a pair object.| -|[pair::swap (STL/CLR)](#swap)|Swaps the contents of two pairs.| +| Member function | Description | +|---|---| +| [`pair::pair`](#pair_pair) | Constructs a `pair` object. | +| [`pair::swap`](#swap) | Swaps the contents of two `pair` objects. | -|Operator|Description| -|--------------|-----------------| -|[pair::operator= (STL/CLR)](#op_as)|Replaces the stored pair of values.| +| Operator | Description | +|---|---| +| [`pair::operator=`](#op_as) | Replaces the stored pair of values. | ## Remarks The object stores a pair of values. You use this template class to combine two values into a single object. Also, the object `cliext::pair` (described here) stores only managed types; to store a pair of unmanaged types use `std::pair`, declared in ``. -## pair::first (STL/CLR) +## `pair::first` The first wrapped value. @@ -124,7 +124,7 @@ int main() [x, 3] ``` -## pair::first_type (STL/CLR) +## `pair::first_type` The type of the first wrapped value. @@ -136,7 +136,7 @@ typedef Value1 first_type; ### Remarks -The type is a synonym for the template parameter *Value1*. +The type is a synonym for the template parameter *`Value1`*. ### Example @@ -161,7 +161,7 @@ int main() [x, 3] ``` -## pair::operator= (STL/CLR) +## `pair::operator=` Replaces the stored pair of values. @@ -173,12 +173,12 @@ pair% operator=(pair% right); #### Parameters -*right*
-Pair to copy. +*`right`*\ +`pair` to copy. ### Remarks -The member operator copies *right* to the object, then returns **`*this`**. You use it to replace the stored pair of values with a copy of the stored pair of values in *right*. +The member operator copies *`right`* to the object, then returns **`*this`**. You use it to replace the stored pair of values with a copy of the stored pair of values in *`right`*. ### Example @@ -205,9 +205,9 @@ int main() [x, 3] ``` -## pair::pair (STL/CLR) +## `pair::pair` -Constructs a pair object. +Constructs a `pair` object. ### Syntax @@ -220,13 +220,13 @@ pair(Value1 val1, Value2 val2); #### Parameters -*right*
-Pair to store. +*`right`*\ +`pair` to store. -*val1*
+*`val1`*\ First value to store. -*val2*
+*`val2`*\ Second value to store. ### Remarks @@ -241,17 +241,17 @@ The constructor: `pair(pair% right);` -initializes the stored pair with `right.`[pair::first (STL/CLR)](#first) and `right.`[pair::second (STL/CLR)](#second). +initializes the stored pair with `right.first` and `right.second`. `pair(pair^ right);` -initializes the stored pair with `right->`[pair::first (STL/CLR)](#first) and `right>`[pair::second (STL/CLR)](#second). +initializes the stored pair with `right->first` and `right->second`. The constructor: `pair(Value1 val1, Value2 val2);` -initializes the stored pair with *val1* and *val2*. +initializes the stored pair with *`val1`* and *`val2`*. ### Example @@ -290,7 +290,7 @@ int main() [x, 3] ``` -## pair::second (STL/CLR) +## `pair::second` The second wrapped value. @@ -327,7 +327,7 @@ int main() [x, 3] ``` -## pair::second_type (STL/CLR) +## `pair::second_type` The type of the second wrapped value. @@ -339,7 +339,7 @@ typedef Value2 second_type; ### Remarks -The type is a synonym for the template parameter *Value2*. +The type is a synonym for the template parameter *`Value2`*. ### Example @@ -364,9 +364,9 @@ int main() [x, 3] ``` -## pair::swap (STL/CLR) +## `pair::swap` -Swaps the contents of two pairs. +Swaps the contents of two `pair` objects. ### Syntax @@ -376,12 +376,12 @@ void swap(pair% right); #### Parameters -*right*
-Pair to swap contents with. +*`right`*\ +`pair` to swap contents with. ### Remarks -The member function swaps the stored pair of values between **`*this`** and *right*. +The member function swaps the stored pair of values between **`*this`** and *`right`*. ### Example @@ -433,7 +433,7 @@ x x x x x a b c ``` -## make_pair (STL/CLR) +## `make_pair` Make a `pair` from a pair of values. @@ -447,21 +447,21 @@ template +*`Value1`*\ The type of the first wrapped value. -*Value2*
+*`Value2`*\ The type of the second wrapped value. -*first*
+*`first`*\ First value to wrap. -*second*
+*`second`*\ Second value to wrap. ### Remarks -The template function returns `pair(first, second)`. You use it to construct a `pair` object from a pair of values. +The function template returns `pair(first, second)`. You use it to construct a `pair` object from a pair of values. ### Example @@ -486,9 +486,9 @@ int main() [y, 4] ``` -## operator!= (pair) (STL/CLR) +## `operator!=` (pair) -Pair not equal comparison. +`pair` not equal comparison. ### Syntax @@ -501,15 +501,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `!(left == right)`. You use it to test whether *left* is not ordered the same as *right* when the two pairs are compared element by element. +The operator function returns `!(left == right)`. You use it to test whether *`left`* isn't ordered the same as *`right`* when the two `pair` objects are compared element by element. ### Example @@ -540,9 +540,9 @@ int main() [x 3] != [x 4] is True ``` -## `operator<` (pair) (STL/CLR) +## `operator<` -Pair less than comparison. +`pair` less than comparison. ### Syntax @@ -555,15 +555,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `left.first <` `right.first || !(right.first <` `left.first &&` `left.second <` `right.second`. You use it to test whether *left* is ordered the before *right* when the two pairs are compared element by element. +The operator function returns `left.first < right.first || !(right.first < left.first && left.second < right.second`. You use it to test whether *`left`* is ordered the before *`right`* when the two `pair` objects are compared element by element. ### Example @@ -594,9 +594,9 @@ int main() [x 3] < [x 4] is True ``` -## `operator<=` (pair) (STL/CLR) +## `operator<=` -Pair less than or equal comparison. +`pair` less than or equal comparison. ### Syntax @@ -609,15 +609,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `!(right < left)`. You use it to test whether *left* is not ordered after *right* when the two pairs are compared element by element. +The operator function returns `!(right < left)`. You use it to test whether *`left`* isn't ordered after *`right`* when the two `pair` objects are compared element by element. ### Example @@ -648,9 +648,9 @@ int main() [x 4] <= [x 3] is False ``` -## operator== (pair) (STL/CLR) +## `operator==` -Pair equal comparison. +`pair` equal comparison. ### Syntax @@ -663,15 +663,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `left.first ==` `right.first &&` `left.second ==` `right.second`. You use it to test whether *left* is ordered the same as *right* when the two pairs are compared element by element. +The operator function returns `left.first == right.first && left.second == right.second`. You use it to test whether *`left`* is ordered the same as *`right`* when the two `pair` objects are compared element by element. ### Example @@ -702,9 +702,9 @@ int main() [x 3] == [x 4] is False ``` -## `operator>` (pair) (STL/CLR) +## `pair::operator>` -Pair greater than comparison. +`pair` greater than comparison. ### Syntax @@ -717,15 +717,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `right` `<` `left`. You use it to test whether *left* is ordered after *right* when the two pairs are compared element by element. +The operator function returns `right < left`. You use it to test whether *`left`* is ordered after *`right`* when the two `pair` objects are compared element by element. ### Example @@ -756,9 +756,9 @@ int main() [x 4] > [x 3] is True ``` -## `operator>=` (pair) (STL/CLR) +## `operator>=` -Pair greater than or equal comparison. +`pair` greater than or equal comparison. ### Syntax @@ -771,15 +771,15 @@ template -Left pair to compare. +*`left`*\ +Left `pair` to compare. -*right*
-Right pair to compare. +*`right`*\ +Right `pair` to compare. ### Remarks -The operator function returns `!(left < right)`. You use it to test whether *left* is not ordered before *right* when the two pairs are compared element by element. +The operator function returns `!(left < right)`. You use it to test whether *`left`* isn't ordered before *`right`* when the two `pair` objects are compared element by element. ### Example diff --git a/docs/dotnet/vector-stl-clr.md b/docs/dotnet/vector-stl-clr.md index d325c773972..c9469c0b712 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)" -ms.date: "11/04/2016" +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 @@ -1455,7 +1454,7 @@ Position of element to access. ### Remarks -The member operator returns a referene to the element at position *pos*. You use it to access an element whose position you know. +The member operator returns a reference to the element at position *pos*. You use it to access an element whose position you know. ### Example 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 a07c0032fc1..8152460289f 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 @@ -4,6 +4,7 @@ description: "Use Microsoft C++ to create programs and libraries that can connec ms.date: 10/28/2021 helpviewer_keywords: ["command-line applications [C++], managed code", "compiling programs [C++]", "Visual C++, managed code", "managed code [C++]"] ms.assetid: 339f89df-a5d2-4040-831a-ddbe25b5dce4 +ms.topic: how-to --- # Walkthrough: Compile a C++/CLI program that targets the CLR in Visual Studio @@ -26,7 +27,7 @@ The following steps vary depending on which version of Visual Studio you are usi 1. In **Solution Explorer**, right-click on the top to open the **Create a New Project** dialog box. -1. At the top of the dialog, type **CLR** in the search box and then choose **CLR Empty Project** from the results list. +1. At the top of the dialog, type **CLR** in the search box and then choose **CLR Empty Project (.NET Framework)** from the results list. 1. Choose the **Create** button to create the project. diff --git a/docs/embedded/download-and-install-the-embedded-tooling.md b/docs/embedded/download-and-install-the-embedded-tooling.md new file mode 100644 index 00000000000..3e7d613e7ae --- /dev/null +++ b/docs/embedded/download-and-install-the-embedded-tooling.md @@ -0,0 +1,63 @@ +--- +title: "Install the Embedded tooling in Visual Studio and Visual Studio Code" +description: "How to download and install the Embedded tooling in Visual Studio and Visual Studio Code." +ms.date: "07/12/2022" +ms.custom: intro-installation +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +ms.topic: install-set-up-deploy +--- + +# Download and install the Embedded tooling + +# [Visual Studio](#tab/visual-studio) + +In Visual Studio 2022 and later versions, you can use the Visual Studio IDE on Windows to edit and debug embedded projects. Use tools such as the [Peripheral View](./peripheral-view.md), [RTOS View](./rtos-view.md), and the [Serial Monitor](./serial-monitor.md) to help interact with and debug your embedded projects. + +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + +To use the embedded development tools in Visual Studio, you must install the required **Linux and embedded development with C++** workload. + +## To install the Linux and embedded development with C++ workload + +1. Enter "Visual Studio Installer" in the Windows search box: + + ![Screenshot showing the Windows search box.](../linux/media/visual-studio-installer-search.png) + +1. Open the Visual Studio Installer. In Visual Studio Installer, choose **Modify** next to your installation of Visual Studio, and then select the **Workloads** tab. Scroll down to **Other toolsets** and select the **Linux and embedded development with C++** workload. + + ![Screenshot showing the Microsoft C++ for Linux Development workload item in Visual Studio Installer.](media/linux-and-embedded-workload.png) + +1. Choose **Modify** to continue with the installation. + +When installation completes, you're ready to use Visual Studio for embedded development. + +# [Visual Studio Code](#tab/visual-studio-code) + +## Install the Embedded extensions in Visual Studio Code + +Microsoft provides an extension to Visual Studio Code that lets you use embedded tools such as a [Peripheral View](./peripheral-view.md), [RTOS View](./rtos-view.md), and a [Serial Monitor](./serial-monitor.md). Now you can use Microsoft tools to help debug your Linux-based embedded applications. + +## To install the embedded extensions for Visual Studio Code + +1. Enter "Visual Studio Code" in the Windows search box: + + ![Search-Visual-Studio-Code](media/windows-search-vscode.png) + +1. Open Visual Studio Code. In Visual Studio Code, open the **Extensions Pane**. + + ![Visual Studio Code Extensions Pane](media/extensions-pane.png) + +1. Search for and install the [Embedded Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-embedded-tools) extension. + + ![Embedded Tools extension](media/embedded-tools-extension.png) + +1. Search for and install the [Serial Monitor](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-serial-monitor) extension. + + ![Serial Monitor extension](media/serial-monitor-extension.png) + +When installation completes, you're ready to use Visual Studio Code for embedded development. + +--- diff --git a/docs/embedded/index.yml b/docs/embedded/index.yml new file mode 100644 index 00000000000..61a779727b7 --- /dev/null +++ b/docs/embedded/index.yml @@ -0,0 +1,59 @@ +### YamlMime:Landing +title: Embedded development with C++ | Create and debug embedded applications # < 60 chars +summary: Use Embedded tooling in Visual Studio 2022 and later to create and debug applications for Embedded. # < 160 chars + +metadata: + title: Embedded development with C++ + description: Learn how to use Embedded tooling in Visual Studio and Visual Studio Code to create and debug applications for Linux. + ms.topic: landing-page + author: gcampbell-msft + ms.author: gcampbell + ms.date: 07/12/2022 + ms.custom: intro-landing-hub + monikerRange: '>=msvc-170' + +# linkListType: architecture | concept | deploy | download | get-started | how-to-guide | learn | overview | quickstart | reference | tutorial | video | whats-new + +landingContent: +# Cards and links should be based on top customer tasks or top subjects +# Start card title with a verb + + # Card + - title: Build and debug embedded projects in Visual Studio and Visual Studio Code + linkLists: + - linkListType: get-started + links: + - text: Download the Embedded workload in Visual Studio and Visual Studio Code + url: download-and-install-the-embedded-tooling.md + - linkListType: how-to-guide + links: + - text: Getting started guides + url: https://github.com/azure-rtos/getting-started + - linkListType: tutorial + links: + - text: Embedded Software Development in Visual Studio + url: https://devblogs.microsoft.com/cppblog/visual-studio-embedded-development/ + - text: Embedded Software Development in Visual Studio Code + url: https://devblogs.microsoft.com/cppblog/vscode-embedded-development/ + - linkListType: whats-new + links: + - text: Zephyr support in Visual Studio and Visual Studio Code + url: https://devblogs.microsoft.com/cppblog/serial-and-zephyr-support/ + + - title: Embedded Tooling in Visual Studio and Visual Studio Code + linkLists: + - linkListType: reference + links: + - text: Peripheral View + url: ./peripheral-view.md + - text: RTOS View + url: ./rtos-view.md + - text: Serial Monitor + url: ./serial-monitor.md + + - title: More embedded tools + linkLists: + - linkListType: whats-new + links: + - text: Bootstrap your development environment + url: https://devblogs.microsoft.com/cppblog/vcpkg-artifacts/ diff --git a/docs/embedded/media/embedded-tools-extension.png b/docs/embedded/media/embedded-tools-extension.png new file mode 100644 index 00000000000..bc02e3316c5 Binary files /dev/null and b/docs/embedded/media/embedded-tools-extension.png differ diff --git a/docs/embedded/media/extensions-pane.png b/docs/embedded/media/extensions-pane.png new file mode 100644 index 00000000000..dce8de909ad Binary files /dev/null and b/docs/embedded/media/extensions-pane.png differ diff --git a/docs/embedded/media/linux-and-embedded-workload.png b/docs/embedded/media/linux-and-embedded-workload.png new file mode 100644 index 00000000000..72773c34eaf Binary files /dev/null and b/docs/embedded/media/linux-and-embedded-workload.png differ diff --git a/docs/embedded/media/peripheral-view-vscode.png b/docs/embedded/media/peripheral-view-vscode.png new file mode 100644 index 00000000000..0ce79cd4386 Binary files /dev/null and b/docs/embedded/media/peripheral-view-vscode.png differ diff --git a/docs/embedded/media/peripheral-view.png b/docs/embedded/media/peripheral-view.png new file mode 100644 index 00000000000..49d5127bf90 Binary files /dev/null and b/docs/embedded/media/peripheral-view.png differ diff --git a/docs/embedded/media/rtos-threads-vscode.png b/docs/embedded/media/rtos-threads-vscode.png new file mode 100644 index 00000000000..cb111aae0c7 Binary files /dev/null and b/docs/embedded/media/rtos-threads-vscode.png differ diff --git a/docs/embedded/media/rtos-threads.png b/docs/embedded/media/rtos-threads.png new file mode 100644 index 00000000000..b9adaf0e800 Binary files /dev/null and b/docs/embedded/media/rtos-threads.png differ diff --git a/docs/embedded/media/serial-monitor-extension.png b/docs/embedded/media/serial-monitor-extension.png new file mode 100644 index 00000000000..966d40ed813 Binary files /dev/null and b/docs/embedded/media/serial-monitor-extension.png differ diff --git a/docs/embedded/media/serial-monitor-vscode-tcp.png b/docs/embedded/media/serial-monitor-vscode-tcp.png new file mode 100644 index 00000000000..c1c6ae0e215 Binary files /dev/null and b/docs/embedded/media/serial-monitor-vscode-tcp.png differ diff --git a/docs/embedded/media/serial-monitor-vscode.png b/docs/embedded/media/serial-monitor-vscode.png new file mode 100644 index 00000000000..29a6c931e11 Binary files /dev/null and b/docs/embedded/media/serial-monitor-vscode.png differ diff --git a/docs/embedded/media/serial-monitor.png b/docs/embedded/media/serial-monitor.png new file mode 100644 index 00000000000..e247eef5e74 Binary files /dev/null and b/docs/embedded/media/serial-monitor.png differ diff --git a/docs/embedded/media/windows-search-vscode.png b/docs/embedded/media/windows-search-vscode.png new file mode 100644 index 00000000000..7374e0953ce Binary files /dev/null and b/docs/embedded/media/windows-search-vscode.png differ diff --git a/docs/embedded/peripheral-view.md b/docs/embedded/peripheral-view.md new file mode 100644 index 00000000000..900dbec7622 --- /dev/null +++ b/docs/embedded/peripheral-view.md @@ -0,0 +1,33 @@ +--- +title: "Peripheral View" +ms.date: "07/12/2022" +description: "Peripheral View that allows users to view and manipulate peripherals." +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +--- +# Peripheral View + +## Overview + +The Peripheral View allows embedded developers to view and manipulate registers and peripherals defined in SVD (System View Description) files while debugging. + +# [Visual Studio](#tab/visual-studio) + +![Screenshot of the Peripheral View in VS.](media/peripheral-view.png) + +# [Visual Studio Code](#tab/visual-studio-code) + +![Screenshot of the Peripheral View in Visual Studio Code.](media/peripheral-view-vscode.png) + +--- + +## Capabilities + +| Capability | Description | Instructions | Keyboard shortcuts | +|--|--|--|--| +| Navigate peripherals | Navigate the peripheral tree view by collapsing and expanding components in the tree view. | Scroll to view all of the peripherals. Select the caret on each item to expand or collapse the view. | Use the **Up** or **Down** arrow keys to scroll. Use the **Left** and **Right** arrow keys to expand or collapse the view. | +| Edit peripheral values | Modify writeable peripheral values. | Select the peripheral value to edit. Use the **Enter** key to submit that value. | Use the **F2** key to edit, **Esc** to cancel editing, and **Enter** to submit edits. | +| Access memory | View the memory locations of peripherals. | Select the linked memory addresses to view. | Use **Tab** to select the link, and **Enter** to navigate to the link. | +| Pin peripherals | Pin important peripherals to the top of the view. | Select the pin icon to pin or unpin peripherals. | Use **Tab** to select the pin icon, and **Enter** to pin or unpin it. | +| Search for peripherals | Search for peripherals that you have specific interest in | Type text into the search bar. | See **Instructions** column. | diff --git a/docs/embedded/rtos-view.md b/docs/embedded/rtos-view.md new file mode 100644 index 00000000000..e5e9b7da9b0 --- /dev/null +++ b/docs/embedded/rtos-view.md @@ -0,0 +1,81 @@ +--- +title: "RTOS Object Views" +ms.date: "07/12/2022" +description: "RTOS View that allows users to view RTOS data of their application." +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +--- +# RTOS (Real time operating system) Object View + +## Overview + +The RTOS Object View allows users to view various components of an RTOS while debugging their application. + +# [Visual Studio](#tab/visual-studio) + +![RTOS View in VS](media/rtos-threads.png) + +# [Visual Studio Code](#tab/visual-studio-code) + +![RTOS View in VS Code](media/rtos-threads-vscode.png) + +--- + +## Supported RTOSes and their supported object types + +- Azure RTOS (ThreadX) + - Block pools + - Byte pools + - Event flags + - Mutexes + - Queues + - Semaphores + - Threads + - Timers +- FreeRTOS + - Queues + - Threads +- Zephyr + - Mailboxes + - Memory slabs + - Message queues + - Mutexes + - Pipes + - Queues + - Semaphores + - Stacks + - Threads + - Timers + +## Usage + +Use the RTOS Object View to: + +- Access memory locations of various objects. +- Access thread variables or various objects in the Watch view. + +Use the arrow keys to select objects within the view. Use the **Enter** key to navigate to the linked content. + +## Configuring an embedded application for the RTOS view + +The RTOS Object View will attempt to automatically display information, but setting certain build flags can allow the RTOS Object View to display additional details. The build flags are specific to the RTOS being used. The exact mechanism used to set these flags varies depending on the build system used by the project. Consult your RTOS and build system documentation for more details. + +### Azure RTOS (ThreadX) + +All features should work by default. + +### FreeRTOS + +- Thread base priority is only available if `configUSE_MUTEXES` is enabled. +- Thread run count is only available if `configGENERATE_RUN_TIME_STATS` is enabled. +- The end address of a thread's stack space is only available if `portSTACK_GROWTH` or `configRECORD_STACK_HIGH_ADDRESS` are enabled. +- The thread list will be retrieved faster if `configMAX_PRIORITIES` is set to the lowest possible value that still satisfies the application's requirements. + +### Zephyr + +- All thread information is only available if `CONFIG_DEBUG_THREAD_INFO` is enabled. +- Thread stack usage is only available if `CONFIG_INIT_STACKS` and `CONFIG_THREAD_STACK_INFO` are enabled. +- For all object types other than threads, information is only available if `CONFIG_TRACING` and `CONFIG_TRACING_OBJECT_TRACKING` are enabled. +- The maximum usage of a memory slab is only available if `CONFIG_MEM_SLAB_TRACE_MAX_UTILIZATION` is enabled. +- The list of threads waiting on an object is only available if `CONFIG_WAITQ_SCALABLE` is disabled. diff --git a/docs/embedded/serial-monitor.md b/docs/embedded/serial-monitor.md new file mode 100644 index 00000000000..48d55fb9c04 --- /dev/null +++ b/docs/embedded/serial-monitor.md @@ -0,0 +1,96 @@ +--- +title: "Serial Monitor" +ms.date: "07/12/2022" +description: "Serial Monitor allows users to configure, monitor, and communicate with serial ports." +author: gcampbell-msft +ms.author: gcampbell +monikerRange: '>=msvc-170' +--- +# Serial Monitor + +> [!NOTE] +> This article is no longer maintained. It references a non-Microsoft extension and might not reflect the current state of the Serial Monitor 2 extension. + +## Overview + +The Serial Monitor allows users to configure, monitor, and communicate with serial ports. + +# [Visual Studio](#tab/visual-studio) + +To install Serial Monitor in Visual Studio, go to **Extensions** > **Manage Extensions**. Search for **Serial Monitor 2** in the extensions marketplace. Select **Install** and then restart Visual Studio to complete the installation. + +:::image type="complex" source="./media/serial-monitor.png" alt-text="Screenshot of the Visual Studio Serial Monitor window."::: +The window is split into two sections. The top section shows the monitoring mode (serial), Port (virtual COM port COM3), baud rate (115200), line ending (None), and a Stop monitoring button. The bottom section shows the messages, consisting of four lines of the text Hello, World! +:::image-end::: + +## Capabilities + +- **Monitor a serial port**: Choose the **Start Monitoring** or **Stop Monitoring** button to control whether to monitor data coming from the port. +- **Send data to a serial port**: Enter text into the text field at the bottom of the view. Use the **Enter** key or choose the **Send Message** arrow button to send the data. +- **Clear the Serial Monitor output**: Choose the **Clear Output** button to clear the incoming data text field. +- **Send preset control signals**: Use the split-button next to the input field to send preset control signals (Ctrl+C, Ctrl+D, Ctrl+X, and Ctrl+Z). +- **Configure Serial Monitor and port connection settings**: See the following table to learn about the settings that the Serial Monitor provides. + +## Configurable settings + +| Settings | Description | Usage | Available options | +|--|--|--|--| +| **Port** | Ports that are actively connected to a device | Use the **Port** dropdown | Serial port compatible devices connected to the machine | +| **Baud Rate** | Frequency at which the monitor attempts to communicate with the connected device | Use the **Baud Rate** dropdown | 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230000, 250000 | +| **Line Ending** | The line ending to use in messages sent to the connected device | Use the **Line Ending** dropdown | None, LF, CR, CRLF | +| **Timestamp** | Adds timestamps to the output of data received from the connected port | Use the **timestamp** toggle button | On/Off | +| **Autoscroll** | Whether to auto-scroll new content that comes from the connected port | Use the **autoscroll** toggle button | On/Off | +| **Automatic Reconnection** | Allows for automatic reconnection and monitoring of disconnected selected ports | Use the **automatic reconnection** toggle button in **Serial** mode | On/Off | +| **Message Encoding** | Can select type of encoding for messages sent to serial port | Use the **message encoding** dropdown in **Serial** mode | Text (utf8), Hex, Binary | +| **Data bits** | Can select how many data bits are used for the serial port connection | Use the **Data bits** dropdown in the **additional settings** | 5, 6, 7, 8 | +| **Stop bits** | Can select how many stop bits are used for the serial port connection | Use the **Stop bits** dropdown in the **additional settings** | 1, 1.5, 2 | +| **Parity** | Can select what parity is used for the serial port connection | Use the **Parity** dropdown in the **additional settings** | None, Odd, Even, Mark, Space | +| **File Logging** | Allows the ability to log output to a file | Use the **file logging** toggle button, as well as the **Choose Log File Directory** button to choose the desired directory in the **additional settings** | On/Off | + +# [Visual Studio Code](#tab/visual-studio-code) + +To install Serial Monitor in Visual Studio Code, open the extensions marketplace and then search for **Serial Monitor**. Select **Install**. + +:::image type="complex" source="./media/serial-monitor-vscode.png" alt-text="Screenshot of the VS Code Serial Monitor window."::: +The window is split into two sections. The top section shows the monitoring mode (serial), Port (virtual COM port COM3), baud rate (115200), line ending (None), and a Stop monitoring button. The bottom section where messages are displayed is empty. +:::image-end::: + +:::image type="complex" source="./media/serial-monitor-vscode-tcp.png" alt-text="Screenshot of the VS Code TCP Serial Monitor window."::: +The window is split into two sections. The top section shows the monitoring mode (TCP), Host (::1), Port (1234), and a Start monitoring button. The bottom section shows the messages, starting with "Opening the TCP connection on ::1:1234. Then Connected to ::1:1234. Then five lines of the text Hello, World!. Then Closed the TCP connection ::1:1234. +:::image-end::: + +## Capabilities + +- **Toggle the serial monitor mode**: Choose **Serial** or **TCP** from the **Monitor Mode** dropdown. +- **Monitor a serial/tcp port**: Choose the **Start Monitoring** or **Stop Monitoring** button to control whether to monitor data coming from the port. +- **Monitor multiple serial/tcp ports at a time**: Press the **Open an additional Monitor** button to open another monitor. +- **Send data to a serial/tcp port**: Enter text into the text field at the bottom of the view. Use the **Enter** key or choose the **Send Message** arrow button to send the data. When sending hex or binary data, bytes are automatically separated by spaces. +- **Clear the Serial Monitor output**: Choose the **Clear Output** button to clear the incoming data text field. +- **Send preset control signals**: Use the split-button next to the input field to send preset control signals (Ctrl+C, Ctrl+D, Ctrl+X, and Ctrl+Z). +- **Configure Serial Monitor and connection settings**: See the following table to learn about the settings that the Serial Monitor provides. +- **Clear the Serial Monitor output**: Choose the **Clear Output** button to clear the incoming data text field. +- **Send preset control signals**: Use the split-button next to the input field to send preset control signals (Ctrl+C, Ctrl+D, Ctrl+X, and Ctrl+Z). + +## Configurable settings + +| Settings | Description | Usage | Available options | +|--|--|--|--| +| **Port** | Ports that are actively connected to a device | Use the **Port** dropdown in **Serial** mode | Serial port compatible devices connected to the machine | +| **Baud Rate** | Frequency at which the monitor attempts to communicate with the connected device | Use the **Baud Rate** dropdown in **Serial** mode | 300, 1200, 2400, 4800, 9600, 19200, 38400, 57600, 74880, 115200, 230000, 250000 | +| **Host** | Name of your host address | Use the **Host** text box to enter your host name in **TCP** mode | Any string that matches a valid host | +| **Port** | The port number of your address | Use the **Port** text box in **TCP** mode | Any valid TCP port | +| **Line Ending** | The line ending to use in messages sent to the connected device | Use the **Line Ending** dropdown in **Serial** mode | None, LF, CR, CRLF | +| **DTR** | Allows the DTR COM output line to be manually set | Use the **DTR** checkbox | True/False | +| **RTS** | Allows the RTS COM output line to be manually set | Use the **RTS** checkbox | True/False | +| **Timestamp** | Adds timestamps to the output of data received from the connected port | Use the **timestamp** toggle button | On/Off | +| **Autoscroll** | Whether to auto-scroll new content that comes from the connected port | Use the **autoscroll** toggle button | On/Off | +| **Automatic Reconnection** | Allows for automatic reconnection and monitoring of disconnected selected ports | Use the **automatic reconnection** toggle button | On/Off| +| **Message Echoing** | Allows the ability to echo/not echo messages you send | Use the **message echoing** toggle button | On/Off | +| **Message Encoding** | Can select type of encoding for messages sent to serial port | Use the **message encoding** dropdown | Text (utf8), Hex, Binary | +| **Data bits** | Can select how many data bits are used for the serial port connection | Use the **Data bits** dropdown in the **additional settings** | 5, 6, 7, 8 | +| **Stop bits** | Can select how many stop bits are used for the serial port connection | Use the **Stop bits** dropdown in the **additional settings** | 1, 1.5, 2 | +| **Parity** | Can select what parity is used for the serial port connection | Use the **Parity** dropdown in the **additional settings** | None, Odd, Even, Mark, Space | +| **File Logging** | Allows the ability to log output to a file | Use the **file logging** toggle button, as well as the **Choose Log File Directory** button to choose the desired directory in the **additional settings** | On/Off | +| **Serial Wire Output (SWO)** | Can enable Serial Wire Output (SWO) decoding | Use the **Serial Wire Output** toggle in the **additional settings** in **TCP** mode | On/Off | + +--- diff --git a/docs/embedded/toc.yml b/docs/embedded/toc.yml new file mode 100644 index 00000000000..b948c79311e --- /dev/null +++ b/docs/embedded/toc.yml @@ -0,0 +1,25 @@ +items: +- name: Embedded development with Visual Studio and Visual Studio Code + href: ./index.yml +- name: Download and install the Embedded Tools + href: download-and-install-the-embedded-tooling.md +- name: Getting started guides + href: https://github.com/azure-rtos/getting-started +- name: Build and debug embedded projects + items: + - name: Embedded Software Development in Visual Studio + href: https://devblogs.microsoft.com/cppblog/visual-studio-embedded-development/ + - name: Embedded Software Development in Visual Studio Code + href: https://devblogs.microsoft.com/cppblog/vscode-embedded-development/ + - name: Zephyr support + href: https://devblogs.microsoft.com/cppblog/serial-and-zephyr-support/ +- name: Embedded Tooling + items: + - name: Peripheral View + href: ./peripheral-view.md + - name: RTOS View + href: ./rtos-view.md + - name: Serial Monitor + href: ./serial-monitor.md + - name: vcpkg artifacts + href: https://devblogs.microsoft.com/cppblog/vcpkg-artifacts/ diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2001.md b/docs/error-messages/compiler-errors-1/compiler-error-c2001.md index b72f3b033c9..6f34a4fc3d2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2001.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2001.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2001" title: "Compiler Error C2001" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2001" +ms.date: 11/04/2016 f1_keywords: ["C2001"] helpviewer_keywords: ["C2001"] -ms.assetid: 0c3a7821-d8e5-4398-ab5a-4116d46e8dda --- # Compiler Error C2001 -newline in constant +> newline in constant + +## Remarks A string constant cannot be continued on a second line unless you do the following: @@ -18,9 +19,9 @@ A string constant cannot be continued on a second line unless you do the followi Ending the first line with \n is not sufficient. -## Examples +## Example -The following sample generates C2001: +The following example generates C2001: ```cpp // C2001.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2002.md b/docs/error-messages/compiler-errors-1/compiler-error-c2002.md index 70d299ecd6b..418f0bc0552 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2002.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2002.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2002" title: "Compiler Error C2002" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2002" +ms.date: 11/04/2016 f1_keywords: ["C2002"] helpviewer_keywords: ["C2002"] -ms.assetid: 91982314-203a-4de1-b884-94e39a623f61 --- # Compiler Error C2002 -invalid wide-character constant +> invalid wide-character constant + +## Remarks The multibyte-character constant is not valid. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2003.md b/docs/error-messages/compiler-errors-1/compiler-error-c2003.md index 61d4e32b6b6..2fbb8924306 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2003.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2003.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2003" title: "Compiler Error C2003" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2003" +ms.date: 11/04/2016 f1_keywords: ["C2003"] helpviewer_keywords: ["C2003"] -ms.assetid: 3161bc08-593d-4448-9fd3-4e3810be9e82 --- # Compiler Error C2003 -expected 'defined id' +> expected 'defined id' + +## Remarks An identifier must follow the preprocessor keyword. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2004.md b/docs/error-messages/compiler-errors-1/compiler-error-c2004.md index a17dba2cb45..18b687d027d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2004.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2004.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C2004" title: "Compiler Error C2004" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2004" +ms.date: 11/04/2016 f1_keywords: ["C2004"] helpviewer_keywords: ["C2004"] -ms.assetid: d81526dd-3a00-4593-87b0-d910d3d29bca --- # Compiler Error C2004 -expected 'defined(id)' +> expected 'defined(id)' + +## Remarks An identifier must appear in the parentheses following the preprocessor keyword. This error can also be generated as a result of compiler conformance work that was done for Visual Studio .NET 2003: missing parenthesis in preprocessor directive. If the closing parenthesis is missing from a preprocessor directive, the compiler will generate an error. -## Examples +## Example -The following sample generates C2004: +The following example generates C2004: ```cpp // C2004.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2005.md b/docs/error-messages/compiler-errors-1/compiler-error-c2005.md index 01f56d8c3ff..d09db6738ac 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2005.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2005.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2005" title: "Compiler Error C2005" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2005" +ms.date: 11/04/2016 f1_keywords: ["C2005"] helpviewer_keywords: ["C2005"] -ms.assetid: 090530ed-e0ec-4358-833a-ca24260e7ffe --- # Compiler Error C2005 -\#line expected a line number, found 'token' +> #line expected a line number, found 'token' + +## Remarks The `#line` directive must be followed by a line number. -The following sample generates C2005: +## Example + +The following example generates C2005: ```cpp // C2005.cpp 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 a1a28744008..65c59918ffd 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,26 @@ --- -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. +## Remarks -The following sample generates C2006: +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. -```cpp -// C2006.cpp -#include stdio.h // C2006 -``` +## Example -Possible resolution: +The following example generates C2006: ```cpp -// C2006b.cpp +// C2006.cpp // compile with: /c -#include +#include iostream // C2006 +#include 'iostream' // C2006 +#include // OK ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2007.md b/docs/error-messages/compiler-errors-1/compiler-error-c2007.md index c34b64e7886..e5831f153ad 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2007.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2007.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2007" title: "Compiler Error C2007" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2007" +ms.date: 11/04/2016 f1_keywords: ["C2007"] helpviewer_keywords: ["C2007"] -ms.assetid: ecd09d99-5036-408b-9e46-bc15488f049e --- # Compiler Error C2007 -\#define syntax +> #define syntax + +## Remarks No identifier appears after a `#define`. To resolve the error, use an identifier. -The following sample generates C2007: +## Example + +The following example generates C2007: ```cpp // C2007.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2008.md b/docs/error-messages/compiler-errors-1/compiler-error-c2008.md index 3c0bc7b7c0d..56451a8c67f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2008.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2008.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2008" title: "Compiler Error C2008" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2008" +ms.date: 11/04/2016 f1_keywords: ["C2008"] helpviewer_keywords: ["C2008"] -ms.assetid: e748ccbe-ffd4-4008-aca7-e53c25225209 --- # Compiler Error C2008 -'character' : unexpected in macro definition +> 'character' : unexpected in macro definition + +## Remarks The character appears immediately following the macro name. To resolve the error, there must be a space after the macro name. -The following sample generates C2008: +## Example + +The following example generates C2008: ```cpp // C2008.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2009.md b/docs/error-messages/compiler-errors-1/compiler-error-c2009.md index fe06f1de781..22d2909681a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2009.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2009.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2009" title: "Compiler Error C2009" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2009" +ms.date: 11/04/2016 f1_keywords: ["C2009"] helpviewer_keywords: ["C2009"] -ms.assetid: fe9d94ed-20a5-4d83-b9c4-60ee69d2f30a --- # Compiler Error C2009 -reuse of macro formal 'identifier' +> reuse of macro formal 'identifier' + +## Remarks The formal parameter list of a macro definition uses the identifier more than once. Identifiers in the macro's parameter list must be unique. -## Examples +## Example -The following sample generates C2009: +The following example generates C2009: ```cpp // C2009.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2010.md b/docs/error-messages/compiler-errors-1/compiler-error-c2010.md index 0219901c98f..2deeab992f0 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2010.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2010.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2010" title: "Compiler Error C2010" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2010" +ms.date: 11/04/2016 f1_keywords: ["C2010"] helpviewer_keywords: ["C2010"] -ms.assetid: 5795ed1d-e206-410b-b7b4-528d125c67b4 --- # Compiler Error C2010 -'character' : unexpected in macro formal parameter list +> 'character' : unexpected in macro formal parameter list + +## Remarks The character is used incorrectly in the formal parameter list of a macro definition. Remove the character to resolve the error. -The following sample generates C2010: +## Example + +The following example generates C2010: ```cpp // C2010.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2011.md b/docs/error-messages/compiler-errors-1/compiler-error-c2011.md index f74c11a4a07..57533da7f97 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2011.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2011.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2011" title: "Compiler Error C2011" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2011" +ms.date: 11/04/2016 f1_keywords: ["C2011"] helpviewer_keywords: ["C2011"] -ms.assetid: 992c9d51-e850-4d53-b86b-02e73b38249c --- # Compiler Error C2011 -'identifier' : 'type' type redefinition +> 'identifier' : 'type' type redefinition + +## Remarks The identifier was already defined as `type`. Check for redefinitions of the identifier. @@ -16,7 +17,9 @@ You may also get C2011 if you import a header file or type library more than onc If you need to find the initial declaration of the redefined type, you can use the [/P](../../build/reference/p-preprocess-to-a-file.md) compiler flag to generate the preprocessed output passed to the compiler. You can use text search tools to find instances of the redefined identifier in the output file. -The following sample generates C2011 and shows one way to fix it: +## Example + +The following example generates C2011 and shows one way to fix it: ```cpp // C2011.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2012.md b/docs/error-messages/compiler-errors-1/compiler-error-c2012.md index e186eb5de56..ef35628c054 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2012.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2012.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2012" title: "Compiler Error C2012" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2012" +ms.date: 11/04/2016 f1_keywords: ["C2012"] helpviewer_keywords: ["C2012"] -ms.assetid: 9f0d8162-c0b3-4234-a41f-836fdb75c84e --- # Compiler Error C2012 -missing name following '<' +> missing name following '<' + +## Remarks An `#include` directive lacks the required filename. -The following sample generates C2012: +## Example + +The following example generates C2012: ```cpp // C2012.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2013.md b/docs/error-messages/compiler-errors-1/compiler-error-c2013.md index 88d193210e1..eeca87ca533 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2013.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2013.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2013" title: "Compiler Error C2013" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2013" +ms.date: 11/04/2016 f1_keywords: ["C2013"] helpviewer_keywords: ["C2013"] -ms.assetid: 6b5c955c-53da-48ee-8533-64ef5b905173 --- # Compiler Error C2013 -missing '>' +> missing '>' + +## Remarks An `#include` directive lacks a closing angle bracket. Add the closing bracket to resolve the error. -The following sample generates C2013: +## Example + +The following example generates C2013: ```cpp // C2013.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2014.md b/docs/error-messages/compiler-errors-1/compiler-error-c2014.md index b4369d49390..0bbac771005 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2014.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2014.md @@ -1,29 +1,31 @@ --- -description: "Learn more about: Compiler Error C2014" title: "Compiler Error C2014" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2014" +ms.date: 08/25/2025 f1_keywords: ["C2014"] helpviewer_keywords: ["C2014"] -ms.assetid: 231d8e9c-48c0-4027-99a3-245d186275ec --- # Compiler Error C2014 -preprocessor command must start as first nonwhite space +> preprocessor command must start as first nonwhite space -The `#` sign of a preprocessor directive must be the first character on a line that is not white space. +## Remarks -The following sample generates C2014: +The `#` sign of a [preprocessor directive](../../preprocessor/preprocessor-directives.md) must be the first character on a line that is not white space. Ensure that the previous line doesn't contain a trailing escape. -```cpp -// C2014.cpp -int k; #include // C2014 -``` +## Example -Possible resolution: +The following example generates C2014: ```cpp -// C2014b.cpp +// C2014.cpp // compile with: /c -int k; -#include + +int a; #define A // C2014 + +int b;\ +#define B // C2014 + +int c; +#define C // OK ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2015.md b/docs/error-messages/compiler-errors-1/compiler-error-c2015.md index 7c3cb4ed8e3..060b5b60fbe 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2015.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2015.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2015" title: "Compiler Error C2015" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2015" +ms.date: 11/04/2016 f1_keywords: ["C2015"] helpviewer_keywords: ["C2015"] -ms.assetid: 8f40af0a-3a5a-4d6a-8ed7-125966e6bfed --- # Compiler Error C2015 -too many characters in constant +> too many characters in constant + +## Remarks A character constant contains more than two characters. The limit is one character for standard character constants and two characters for long character constants. @@ -16,7 +17,7 @@ An escape sequence, such as \t, is converted to a single character. ## Examples -The following sample generates C2015: +The following example generates C2015: ```cpp // C2015.cpp @@ -26,7 +27,7 @@ char test1 = 'error'; // C2015 char test2 = 'e'; // OK ``` -C2015 can also occur when using a Microsoft extension, character constants converted to integers. The following sample generates C2015: +C2015 can also occur when using a Microsoft extension, character constants converted to integers. The following example generates C2015: ```cpp // C2015b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2016.md b/docs/error-messages/compiler-errors-1/compiler-error-c2016.md new file mode 100644 index 00000000000..563387c249a --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2016.md @@ -0,0 +1,16 @@ +--- +title: "Compiler Error C2016" +description: "Learn more about: Compiler Error C2016" +ms.date: 08/18/2022 +f1_keywords: ["C2016"] +helpviewer_keywords: ["C2016"] +--- +# Compiler Error C2016 + +> C requires that a struct or union has at least one member + +## Remarks + +The compiler found a **`struct`** or **`union`** defined with no members, which isn't allowed in C. For more information, see [Structures](../../c-language/structure-declarations.md) and [Unions](../../c-language/union-declarations.md). + +To resolve this error, create at least one member in your **`struct`** or **`union`**. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2017.md b/docs/error-messages/compiler-errors-1/compiler-error-c2017.md index fc2705d40d0..d659ba2526b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2017.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2017.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2017" title: "Compiler Error C2017" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2017" +ms.date: 11/04/2016 f1_keywords: ["C2017"] helpviewer_keywords: ["C2017"] -ms.assetid: 1083eed9-9906-4a97-883c-54e52d7e82cd --- # Compiler Error C2017 -illegal escape sequence +> illegal escape sequence + +## Remarks An escape sequence, such as \t, appears outside of a character or string constant. -The following sample generates C2017: +## Examples + +The following example generates C2017: ```cpp // C2017.cpp @@ -24,7 +27,7 @@ int main() { C2017 can occur when the stringize operator is used with strings that include escape sequences. -The following sample generates C2017: +The following example generates C2017: ```cpp // C2017b.cpp 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 5b4dda09859..16c19e66bfb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2018.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2018.md @@ -1,13 +1,26 @@ --- -description: "Learn more about: Compiler Error C2018" title: "Compiler Error C2018" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2018" +ms.date: 06/21/2025 f1_keywords: ["C2018"] helpviewer_keywords: ["C2018"] -ms.assetid: 86b54573-dca0-4446-be1a-e3ac489c073b --- # Compiler Error C2018 -unknown character 'hexnumber' +> unknown character 'hexnumber' + +## Remarks The source file contains an unexpected ASCII character, which is identified by its hex number. To resolve the error, remove the character. + +## Example + +The following example generates C2018: + +```cpp +// C2018.cpp +int main() +{ + @ // C2018 +} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2019.md b/docs/error-messages/compiler-errors-1/compiler-error-c2019.md index 8353a05ae67..e835a042526 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2019.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2019.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2019" title: "Compiler Error C2019" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2019" +ms.date: 11/04/2016 f1_keywords: ["C2019"] helpviewer_keywords: ["C2019"] -ms.assetid: 4f37b1e1-9eca-418f-a4c3-141e8512d7b6 --- # Compiler Error C2019 -expected preprocessor directive, found 'character' +> expected preprocessor directive, found 'character' + +## Remarks The character followed a `#` sign but it is not the first letter of a preprocessor directive. -The following sample generates C2019: +## Example + +The following example generates C2019: ```cpp // C2019.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2020.md b/docs/error-messages/compiler-errors-1/compiler-error-c2020.md index 1d9ecbc4945..bc32e9e64ce 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2020.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2020.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2020" title: "Compiler Error C2020" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2020" +ms.date: 11/04/2016 f1_keywords: ["C2020"] helpviewer_keywords: ["C2020"] -ms.assetid: 486f98ed-6574-4d82-89e3-74b5a61ed419 --- # Compiler Error C2020 -'member' : 'class' member redefinition +> 'member' : 'class' member redefinition + +## Remarks A member inherited from a base class or structure is redefined. Inherited members cannot be redefined unless declared as **`virtual`** in the base class. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2021.md b/docs/error-messages/compiler-errors-1/compiler-error-c2021.md index a32149660cb..e0a6ce1831a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2021.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2021.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2021" title: "Compiler Error C2021" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2021" +ms.date: 11/04/2016 f1_keywords: ["C2021"] helpviewer_keywords: ["C2021"] -ms.assetid: 064f32e2-3794-48d5-9767-991003dcb36a --- # Compiler Error C2021 -expected exponent value, not 'character' +> expected exponent value, not 'character' + +## Remarks The character used as the exponent of a floating-point constant is not a valid number. Be sure to use an exponent that is in range. -## Examples +## Example -The following sample generates C2021: +The following example generates C2021: ```cpp // C2021.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2022.md b/docs/error-messages/compiler-errors-1/compiler-error-c2022.md index a072ce76c29..619c126d667 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2022.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2022.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2022" title: "Compiler Error C2022" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2022" +ms.date: 11/04/2016 f1_keywords: ["C2022"] helpviewer_keywords: ["C2022"] -ms.assetid: 1f5c477a-d909-42d8-8588-811586e8ba1e --- # Compiler Error C2022 -'number' : too big for character +> 'number' : too big for character + +## Remarks The octal number following a backslash (\\) in a character or string constant is too big to represent a character. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2023.md b/docs/error-messages/compiler-errors-1/compiler-error-c2023.md new file mode 100644 index 00000000000..8ddc41ef919 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2023.md @@ -0,0 +1,37 @@ +--- +title: "Compiler Error C2023" +description: "Learn more about: Compiler Error C2023" +ms.date: 08/18/2022 +f1_keywords: ["C2023"] +helpviewer_keywords: ["C2023"] +--- +# Compiler Error C2023 + +> '*identifier*': Alignment (*value-1*) different from prior declaration (*value-2*) + +## Remarks + +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. + +## Example + +The following example generates C2023: + +```cpp +// C2023.cpp +class alignas(2) C; + +class alignas(4) C {}; // C2023 +``` + +Possible resolution: + +```cpp +// C2023b.cpp +// compile with: /c +class alignas(2) C; + +class alignas(2) C {}; +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2024.md b/docs/error-messages/compiler-errors-1/compiler-error-c2024.md new file mode 100644 index 00000000000..89965f73fe6 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2024.md @@ -0,0 +1,37 @@ +--- +title: "Compiler Error C2024" +description: "Learn more about: Compiler Error C2024" +ms.date: 08/18/2022 +f1_keywords: ["C2024"] +helpviewer_keywords: ["C2024"] +--- +# Compiler Error C2024 + +> 'alignas' attribute applies to variables, data members and tag types only + +## Remarks + +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. + +## Example + +The following example generates C2024: + +```cpp +// C2024.cpp +namespace alignas(2) ns { // C2024 + void func(alignas(8) int x) {} // C2024 +} +``` + +Possible resolution: + +```cpp +// C2024b.cpp +// compile with: /c +namespace ns { + void func(int x) {} +} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2025.md b/docs/error-messages/compiler-errors-1/compiler-error-c2025.md new file mode 100644 index 00000000000..edd6d5218cd --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2025.md @@ -0,0 +1,16 @@ +--- +title: "Compiler Error C2025" +description: "Learn more about: Compiler Error C2025" +ms.date: 08/18/2022 +f1_keywords: ["C2025"] +helpviewer_keywords: ["C2025"] +--- +# Compiler Error C2025 + +> invalid or corrupted binary module interface file: '*filename*' + +## Remarks + +The compiler could not read the specified IFC file. + +To resolve this error, rebuild the module interface file. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2026.md b/docs/error-messages/compiler-errors-1/compiler-error-c2026.md index c04bbb7582e..0ebf596eb09 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2026.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2026.md @@ -4,16 +4,15 @@ description: "Describes Microsoft C/C++ compiler error C2026, its causes and how ms.date: 09/25/2020 f1_keywords: ["C2026"] helpviewer_keywords: ["C2026"] -ms.assetid: 8e64b6e1-b967-479b-be97-d12dc4a8e389 --- # Compiler Error C2026 > string too big, trailing characters truncated -The string was longer than the limit of 16380 single-byte characters. - ## Remarks +The string was longer than the limit of 16380 single-byte characters. + Before adjacent strings get concatenated, a string can't be longer than 16380 single-byte characters. A Unicode string of about one half this length would also generate this error. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2027.md b/docs/error-messages/compiler-errors-1/compiler-error-c2027.md index d824942cd4c..b99589dda0a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2027.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2027.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2027" title: "Compiler Error C2027" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2027" +ms.date: 11/04/2016 f1_keywords: ["C2027"] helpviewer_keywords: ["C2027"] -ms.assetid: a39150c0-ec04-45ec-934c-a838bfe76627 --- # Compiler Error C2027 -use of undefined type 'type' +> use of undefined type 'type' + +## Remarks A type cannot be used until it is defined. To resolve the error, be sure the type is fully defined before referencing it. ## Examples -The following sample generates C2027. +The following example generates C2027. ```cpp // C2027.cpp @@ -36,7 +37,7 @@ int main() { It is possible to declare a pointer to a declared but undefined type. But C++ does not allow a reference to an undefined type. -The following sample generates C2027. +The following example generates C2027. ```cpp // C2027_b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2028.md b/docs/error-messages/compiler-errors-1/compiler-error-c2028.md index dbf89a234a8..d7adba707ec 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2028.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2028.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2028" title: "Compiler Error C2028" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2028" +ms.date: 11/04/2016 f1_keywords: ["C2028"] helpviewer_keywords: ["C2028"] -ms.assetid: 4e92e944-8fce-4443-9baf-4411ad9bde70 --- # Compiler Error C2028 -struct/union member must be inside a struct/union +> struct/union member must be inside a struct/union + +## Remarks Structure or union members must be declared within the structure or union. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2030.md b/docs/error-messages/compiler-errors-1/compiler-error-c2030.md index 6f355444f85..e13728eaddb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2030.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2030.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2030" title: "Compiler Error C2030" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2030" +ms.date: 11/04/2016 f1_keywords: ["C2030"] helpviewer_keywords: ["C2030"] -ms.assetid: 5806cead-64df-4eff-92de-52c9a3f5ee62 --- # Compiler Error C2030 -a destructor with 'protected private' accessibility cannot be a member of a class declared 'sealed' +> a destructor with 'protected private' accessibility cannot be a member of a class declared 'sealed' + +## Remarks A Windows Runtime class declared as **`sealed`** cannot have a protected private destructor. Only public virtual and private non-virtual destructors are allowed on sealed types. For more information, see [Ref classes and structs](../../cppcx/ref-classes-and-structs-c-cx.md). diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2031.md b/docs/error-messages/compiler-errors-1/compiler-error-c2031.md new file mode 100644 index 00000000000..f6ef1fa4815 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2031.md @@ -0,0 +1,17 @@ +--- +title: "Compiler Error C2031" +description: "Learn more about: Compiler Error C2031" +ms.date: 08/18/2022 +f1_keywords: ["C2031"] +helpviewer_keywords: ["C2031"] +--- +# Compiler Error C2031 + +> a virtual destructor with '*accessibility*' accessibility is not allowed for this type\ +> a virtual destructor must have 'public' accessibility + +## Remarks + +A virtual Windows Runtime class has an access specifier or **`sealed`** specifier that's not allowed for a virtual destructor. For more information, see [Ref classes and structs](../../cppcx/ref-classes-and-structs-c-cx.md). + +To fix this error, change the accessibility of the destructor. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2032.md b/docs/error-messages/compiler-errors-1/compiler-error-c2032.md index 973fedfa7ab..e2ed2b78c27 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2032.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2032.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2032" title: "Compiler Error C2032" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2032" +ms.date: 11/04/2016 f1_keywords: ["C2032"] helpviewer_keywords: ["C2032"] -ms.assetid: 625d7c83-70b6-42c2-a558-81fbc0026324 --- # Compiler Error C2032 -'identifier' : function cannot be member of struct/union 'structorunion' +> 'identifier' : function cannot be member of struct/union 'structorunion' + +## Remarks The structure or union has a member function, which is allowed in C++ but not in C. To resolve the error, either compile as a C++ program or remove the member function. -The following sample generates C2032: +## Example + +The following example generates C2032: ```c // C2032.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2033.md b/docs/error-messages/compiler-errors-1/compiler-error-c2033.md index 767ad979198..110b499acd5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2033.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2033.md @@ -1,32 +1,33 @@ --- -description: "Learn more about: Compiler Error C2033" title: "Compiler Error C2033" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2033" +ms.date: 09/10/2025 f1_keywords: ["C2033"] helpviewer_keywords: ["C2033"] -ms.assetid: fd5a1637-9db2-4c98-a7cc-b63b39737cd9 --- # Compiler Error C2033 -'identifier' : bit field cannot have indirection +> '*identifier*': bit field cannot have indirection -The bit field was declared as a pointer, which is not allowed. +## Remarks -The following sample generates C2033: +Bit fields can't be declared as a pointer, reference, or array. For more information, see [C++ Bit Fields](../../cpp/cpp-bit-fields.md). -```cpp -// C2033.cpp -struct S { - int *b : 1; // C2033 -}; -``` +## Example -Possible resolution: +The following example generates C2033: ```cpp -// C2033b.cpp +// C2033.cpp // compile with: /c -struct S { - int b : 1; + +struct S +{ + int* ptr : 1; // C2033 + int arr[3] : 1; // C2033 }; ``` + +## See also + +[Compiler Error C2531](../compiler-errors-2/compiler-error-c2531.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2034.md b/docs/error-messages/compiler-errors-1/compiler-error-c2034.md index b512dc66b2b..1f988de2b4c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2034.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2034.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2034" title: "Compiler Error C2034" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2034" +ms.date: 11/04/2016 f1_keywords: ["C2034"] helpviewer_keywords: ["C2034"] -ms.assetid: 953d70fa-bde9-4ce6-a55d-741e7bc63ff4 --- # Compiler Error C2034 -'identifier' : type of bit field too small for number of bits +> 'identifier' : type of bit field too small for number of bits + +## Remarks The number of bits in the bit-field declaration exceeds the size of the base type. -The following sample generates C2034: +## Example + +The following example generates C2034: ```cpp // C2034.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2035.md b/docs/error-messages/compiler-errors-1/compiler-error-c2035.md new file mode 100644 index 00000000000..8b4e5fe38b5 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2035.md @@ -0,0 +1,17 @@ +--- +title: "Compiler Error C2035" +description: "Learn more about: Compiler Error C2035" +ms.date: 08/18/2022 +f1_keywords: ["C2035"] +helpviewer_keywords: ["C2035"] +--- +# Compiler Error C2035 + +> a non-virtual destructor with '*accessibility*' accessibility is not allowed for this type\ +> a non-virtual destructor must have 'protected private' or 'private' accessibility + +## Remarks + +A non-virtual Windows Runtime class has an access specifier or **`sealed`** specifier that's not allowed for a non-virtual destructor. For more information, see [Ref classes and structs](../../cppcx/ref-classes-and-structs-c-cx.md). + +To fix this error, change the accessibility of the destructor. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2036.md b/docs/error-messages/compiler-errors-1/compiler-error-c2036.md index 92350e0b5b0..10f675360e0 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2036.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2036.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2036" title: "Compiler Error C2036" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2036" +ms.date: 11/04/2016 f1_keywords: ["C2036"] helpviewer_keywords: ["C2036"] -ms.assetid: 895821a9-65d1-44b5-bde1-dae827f3e486 --- # Compiler Error C2036 -'identifier' : unknown size +> 'identifier' : unknown size + +## Remarks An operation on `identifier` requires the size of the data object, which cannot be determined. ## Examples -The following sample generates C2036. +The following example generates C2036. ```c // C2036.c @@ -29,7 +30,7 @@ int main() { } ``` -The following sample generates C2036. +The following example generates C2036. ```cpp // C2036_2.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2037.md b/docs/error-messages/compiler-errors-1/compiler-error-c2037.md new file mode 100644 index 00000000000..04fffc4ba7b --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2037.md @@ -0,0 +1,16 @@ +--- +title: "Compiler Error C2037" +description: "Learn more about: Compiler Error C2037" +ms.date: 08/18/2022 +f1_keywords: ["C2037"] +helpviewer_keywords: ["C2037"] +--- +# Compiler Error C2037 + +> left of '*operator*' specifies undefined struct/union '*type*' + +## Remarks + +The operand to the left of the member-selection *operator* is not a fully defined class, structure, or union. + +This error can be caused by a left operand that is an undefined variable. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2038.md b/docs/error-messages/compiler-errors-1/compiler-error-c2038.md new file mode 100644 index 00000000000..4de865e57cd --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2038.md @@ -0,0 +1,16 @@ +--- +title: "Compiler Error C2038" +description: "Learn more about: Compiler Error C2038" +ms.date: 08/18/2022 +f1_keywords: ["C2038"] +helpviewer_keywords: ["C2038"] +--- +# Compiler Error C2038 + +> the std namespace cannot be inline + +## Remarks + +The C++ standard does not allow the `std` namespace to be declared `inline`. + +To resolve this issue, remove the `inline` specifier. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2039.md b/docs/error-messages/compiler-errors-1/compiler-error-c2039.md index f84cbdefa6c..635d97226b9 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,21 @@ --- -description: "Learn more about: Compiler Error C2039" title: "Compiler Error C2039" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2039" +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' + +## Remarks The code incorrectly calls or refers to a member of a structure, class, or union. ## Examples -The following sample generates C2039. +The following example generates C2039: ```cpp // C2039.cpp @@ -28,7 +29,7 @@ int main() { } ``` -The following sample generates C2039. +The following example generates C2039: ```cpp // C2039_b.cpp @@ -41,7 +42,7 @@ int main() { } ``` -The following sample generates C2039. +The following example generates C2039: ```cpp // C2039_c.cpp @@ -57,9 +58,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 +73,7 @@ public class B { }; ``` -The following sample generates C2039. +The following example generates C2039 when it uses the previously defined C# component's default indexer incorrectly from C++/CLI: ```cpp // C2039_e.cpp @@ -89,7 +90,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 example generates C2039: ```cpp // C2039_f.cpp @@ -114,7 +115,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 example generates C2039: ```cpp // C2039_g.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2040.md b/docs/error-messages/compiler-errors-1/compiler-error-c2040.md index 76c71d13bbf..ba66506a83d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2040.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2040.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2040" title: "Compiler Error C2040" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2040" +ms.date: 11/04/2016 f1_keywords: ["C2040"] helpviewer_keywords: ["C2040"] -ms.assetid: 74ca3592-1469-4965-ab34-a4815e2fbefe --- # Compiler Error C2040 -'operator' : 'identifier1' differs in levels of indirection from 'identifier2' +> 'operator' : 'identifier1' differs in levels of indirection from 'identifier2' + +## Remarks An expression involving the specified operands has incompatible operand types or implicitly converted operand types. If both operands are arithmetic, or both are nonarithmetic (such as array or pointer), they are used without change. If one operand is arithmetic and the other is not, the arithmetic operand is converted to the type of the nonarithmetic operand. -This sample generates C2040 and shows how to fix it. +## Example + +This example generates C2040 and shows how to fix it. ```cpp // C2040.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2041.md b/docs/error-messages/compiler-errors-1/compiler-error-c2041.md index e78711fd216..fd9ffaba7a9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2041.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2041.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2041" title: "Compiler Error C2041" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2041" +ms.date: 11/04/2016 f1_keywords: ["C2041"] helpviewer_keywords: ["C2041"] -ms.assetid: c9a33bb1-f9cf-47d6-bd21-7d867a8c37d5 --- # Compiler Error C2041 -illegal digit 'character' for base 'number' +> illegal digit 'character' for base 'number' + +## Remarks The specified character is not a valid digit for the base (such as octal or hex). -The following sample generates C2041: +## Example + +The following example generates C2041: ```cpp // C2041.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2042.md b/docs/error-messages/compiler-errors-1/compiler-error-c2042.md index a29490360b5..514b99958e3 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2042.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2042.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2042" title: "Compiler Error C2042" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2042" +ms.date: 11/04/2016 f1_keywords: ["C2042"] helpviewer_keywords: ["C2042"] -ms.assetid: e111788f-41ce-405a-9824-a4c1c26059e6 --- # Compiler Error C2042 -signed/unsigned keywords mutually exclusive +> signed/unsigned keywords mutually exclusive + +## Remarks The keywords **`signed`** and **`unsigned`** are used in a single declaration. -The following sample generates C2042: +## Example + +The following example generates C2042: ```cpp // C2042.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2043.md b/docs/error-messages/compiler-errors-1/compiler-error-c2043.md index 0ef748d8218..5cc6bae8010 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2043.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2043.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2043" title: "Compiler Error C2043" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2043" +ms.date: 11/04/2016 f1_keywords: ["C2043"] helpviewer_keywords: ["C2043"] -ms.assetid: 6cc829f3-c6ea-43ae-8a3f-303ecf6c7dc6 --- # Compiler Error C2043 -illegal break +> illegal break + +## Remarks A [break](../../cpp/break-statement-cpp.md) is legal only within a **`do`**, **`for`**, **`while`**, or **`switch`** statement. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2044.md b/docs/error-messages/compiler-errors-1/compiler-error-c2044.md index 12ec3d94b6f..5bb88a790e1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2044.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2044.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2044" title: "Compiler Error C2044" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2044" +ms.date: 11/04/2016 f1_keywords: ["C2044"] helpviewer_keywords: ["C2044"] -ms.assetid: adf4bedc-f915-4008-8b48-a06d626d8c38 --- # Compiler Error C2044 -illegal continue +> illegal continue + +## Remarks A [continue](../../cpp/continue-statement-cpp.md) is legal only within a **`do`**, **`for`**, or **`while`** statement. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2045.md b/docs/error-messages/compiler-errors-1/compiler-error-c2045.md index a694941e73a..dd805a57e02 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2045.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2045.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2045" title: "Compiler Error C2045" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2045" +ms.date: 11/04/2016 f1_keywords: ["C2045"] helpviewer_keywords: ["C2045"] -ms.assetid: 2fca668e-9b20-4933-987a-18c0fd0187df --- # Compiler Error C2045 -'identifier' : label redefined +> 'identifier' : label redefined + +## Remarks The label appears before multiple statements in the same function. -The following sample generates C2045: +## Example + +The following example generates C2045: ```cpp // C2045.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2046.md b/docs/error-messages/compiler-errors-1/compiler-error-c2046.md index 1fc5235d5d4..7831da647a4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2046.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2046.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2046" title: "Compiler Error C2046" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2046" +ms.date: 11/04/2016 f1_keywords: ["C2046"] helpviewer_keywords: ["C2046"] -ms.assetid: f0c8f9dd-dbd7-4c4a-8838-fde54208ec71 --- # Compiler Error C2046 -illegal case +> illegal case + +## Remarks The keyword `case` can appear only in a **`switch`** statement. -The following sample generates C2046: +## Example + +The following example generates C2046: ```cpp // C2046.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2047.md b/docs/error-messages/compiler-errors-1/compiler-error-c2047.md index 57ec7a835df..51b7b6470fc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2047.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2047.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2047" title: "Compiler Error C2047" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2047" +ms.date: 11/04/2016 f1_keywords: ["C2047"] helpviewer_keywords: ["C2047"] -ms.assetid: 686a5a81-3857-4753-84a0-5c2e7149cbee --- # Compiler Error C2047 -illegal default +> illegal default + +## Remarks The keyword **`default`** can appear only in a **`switch`** statement. -The following sample generates C2047: +## Example + +The following example generates C2047: ```cpp // C2047.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2048.md b/docs/error-messages/compiler-errors-1/compiler-error-c2048.md index d424fe39c4b..11ef98ecba7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2048.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2048.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2048" title: "Compiler Error C2048" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2048" +ms.date: 11/04/2016 f1_keywords: ["C2048"] helpviewer_keywords: ["C2048"] -ms.assetid: 44704726-85fc-42f0-afb9-194df8c4ca7c --- # Compiler Error C2048 -more than one default +> more than one default + +## Remarks A **`switch`** statement contains multiple **`default`** labels. Delete one of the **`default`** labels to resolve the error. -The following sample generates C2048: +## Example + +The following example generates C2048: ```cpp // C2048.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2049.md b/docs/error-messages/compiler-errors-1/compiler-error-c2049.md new file mode 100644 index 00000000000..efcbb0ca4fd --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2049.md @@ -0,0 +1,36 @@ +--- +title: "Compiler Error C2049" +description: "Learn more about: Compiler Error C2049" +ms.date: 08/18/2022 +f1_keywords: ["C2049"] +helpviewer_keywords: ["C2049"] +--- +# Compiler Error C2049 + +> '*namespace-name*': non-inline namespace cannot be reopened as inline + +## Remarks + +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. + +## Example + +The following example 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-c2050.md b/docs/error-messages/compiler-errors-1/compiler-error-c2050.md index a1815f9b37c..962b523cf2c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2050.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2050.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2050" title: "Compiler Error C2050" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2050" +ms.date: 11/04/2016 f1_keywords: ["C2050"] helpviewer_keywords: ["C2050"] -ms.assetid: 66aaed7d-00db-4ce1-a9d6-4447c1cf07ce --- # Compiler Error C2050 -switch expression not integral +> switch expression not integral + +## Remarks The **`switch`** expression evaluates to a noninteger value. To resolve the error, use only integral values in switch statements. -The following sample generates C2050: +## Example + +The following example generates C2050: ```cpp // C2050.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2051.md b/docs/error-messages/compiler-errors-1/compiler-error-c2051.md index b7a5383002d..1437749339b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2051.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2051.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2051" title: "Compiler Error C2051" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2051" +ms.date: 11/04/2016 f1_keywords: ["C2051"] helpviewer_keywords: ["C2051"] -ms.assetid: 81c0469a-78e2-49fa-bd76-97cdb135e3ea --- # Compiler Error C2051 -case expression not constant +> case expression not constant + +## Remarks Case expressions must be integer constants. -The following sample generates C2051: +## Example + +The following example generates C2051: ```cpp // C2051.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2052.md b/docs/error-messages/compiler-errors-1/compiler-error-c2052.md index a32b58543ea..4a0693ce3e8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2052.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2052.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2052" title: "Compiler Error C2052" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2052" +ms.date: 11/04/2016 f1_keywords: ["C2052"] helpviewer_keywords: ["C2052"] -ms.assetid: 922ca43b-b64b-4ef7-9611-c7313be3fd79 --- # Compiler Error C2052 -'type' : illegal type for case expression +> 'type' : illegal type for case expression + +## Remarks Case expressions must be integer constants. -The following sample generates C2052: +## Example + +The following example generates C2052: ```cpp // C2052.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2053.md b/docs/error-messages/compiler-errors-1/compiler-error-c2053.md index bc6087a46ee..8a61e880a57 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2053.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2053.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2053" title: "Compiler Error C2053" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2053" +ms.date: 11/04/2016 f1_keywords: ["C2053"] helpviewer_keywords: ["C2053"] -ms.assetid: 13324c85-13a8-4996-bd42-a31bfe7ff80f --- # Compiler Error C2053 -'identifier' : wide string mismatch +> 'identifier' : wide string mismatch + +## Remarks The wide string is assigned to an incompatible type. -The following sample generates C2053: +## Example + +The following example generates C2053: ```c // C2053.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2054.md b/docs/error-messages/compiler-errors-1/compiler-error-c2054.md index d3cbf892c7c..58ec5aff223 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2054.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2054.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2054" title: "Compiler Error C2054" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2054" +ms.date: 11/04/2016 f1_keywords: ["C2054"] helpviewer_keywords: ["C2054"] -ms.assetid: 37f7c612-0d7d-4728-9e67-ac4160555f48 --- # Compiler Error C2054 -expected '(' to follow 'identifier' +> expected '(' to follow 'identifier' + +## Remarks The function identifier is used in a context that requires trailing parentheses. This error can be caused by omitting an equal sign (=) on a complex initialization. -The following sample generates C2054: +## Example + +The following example generates C2054: ```c // C2054.c 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 fe73b75244b..c382074bc57 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,28 @@ --- -description: "Learn more about: Compiler Error C2055" -title: "Compiler Error C2055" -ms.date: "11/04/2016" +title: "Compiler error C2055" +description: "Learn more about: Microsoft Visual C++ 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 (`...`). +## Remarks -The following sample generates C2055: +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 (`...`). + +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`. + +## Example + +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-c2056.md b/docs/error-messages/compiler-errors-1/compiler-error-c2056.md index f29b08129a9..2aca685be38 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2056.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2056.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2056" title: "Compiler Error C2056" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2056" +ms.date: 11/04/2016 f1_keywords: ["C2056"] helpviewer_keywords: ["C2056"] -ms.assetid: 043a1f72-738a-487f-b7b3-055cc5ca0ae7 --- # Compiler Error C2056 -illegal expression +> illegal expression + +## Remarks An expression was invalid because of a previous error. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2057.md b/docs/error-messages/compiler-errors-1/compiler-error-c2057.md index 41049e9a070..eefd54c1e9d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2057.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2057.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2057" title: "Compiler Error C2057" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2057" +ms.date: 11/04/2016 f1_keywords: ["C2057"] helpviewer_keywords: ["C2057"] -ms.assetid: 038a99d6-1f5a-42fa-8449-03b4ff11ee0b --- # Compiler Error C2057 -expected constant expression +> expected constant expression + +## Remarks The context requires a constant expression, an expression whose value is known at compile time. @@ -16,7 +17,7 @@ The compiler must know the size of a type at compile time in order to allocate s ## Examples -The following sample generates C2057 and shows how to fix it: +The following example generates C2057 and shows how to fix it: ```cpp // C2057.cpp @@ -28,7 +29,7 @@ int main() { } ``` -C has more restrictive rules for constant expressions. The following sample generates C2057 and shows how to fix it: +C has more restrictive rules for constant expressions. The following example generates C2057 and shows how to fix it: ```c // C2057b.c 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 d8aa9725a71..04aa6b3c5ac 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2058.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2058.md @@ -1,13 +1,29 @@ --- -description: "Learn more about: Compiler Error C2058" title: "Compiler Error C2058" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2058" +ms.date: 11/04/2016 f1_keywords: ["C2058"] helpviewer_keywords: ["C2058"] -ms.assetid: 81e08e6b-15f7-41b4-980a-53763e19990c --- # Compiler Error C2058 -constant expression is not integral +> constant expression is not integral + +## Remarks The context requires an integer constant expression. + +## Example + +The following example 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-c2059.md b/docs/error-messages/compiler-errors-1/compiler-error-c2059.md index 61b19f215fd..b575bf8b277 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2059.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2059.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C2059" title: "Compiler Error C2059" -ms.date: "03/26/2019" +description: "Learn more about: Compiler Error C2059" +ms.date: 03/26/2019 f1_keywords: ["C2059"] helpviewer_keywords: ["C2059"] -ms.assetid: 2be4eb39-3f37-4b32-8e8d-75835e07c78a --- # Compiler Error C2059 -syntax error : 'token' +> syntax error : 'token' + +## Remarks The token caused a syntax error. +## Examples + The following example generates an error message for the line that declares `j`. ```cpp @@ -73,7 +76,7 @@ void func(ag_type arg = ag_type(5, 7.0)); // OK C2059 can occur for an ill-formed cast. -The following sample generates C2059: +The following example generates C2059: ```cpp // C2059c.cpp @@ -91,7 +94,7 @@ int main() { C2059 can also occur if you attempt to create a namespace name that contains a period. -The following sample generates C2059: +The following example generates C2059: ```cpp // C2059d.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2060.md b/docs/error-messages/compiler-errors-1/compiler-error-c2060.md index a6cfa82a76c..19ef4398bbc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2060.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2060.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2060" title: "Compiler Error C2060" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2060" +ms.date: 11/04/2016 f1_keywords: ["C2060"] helpviewer_keywords: ["C2060"] -ms.assetid: 2572deba-cc12-464e-9162-86252a3af061 --- # Compiler Error C2060 -syntax error : end of file found +> syntax error : end of file found + +## Remarks At least one more token was expected. 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 2a79f1cd5a8..83394157a63 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2061.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2061.md @@ -1,43 +1,70 @@ --- -description: "Learn more about: Compiler Error C2061" title: "Compiler Error C2061" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2061" +ms.date: 11/04/2016 f1_keywords: ["C2061"] helpviewer_keywords: ["C2061"] -ms.assetid: b0e61c0c-a205-4820-b9aa-301d6c6fe6eb --- # Compiler Error C2061 -syntax error : identifier 'identifier' +> syntax error : identifier 'identifier' + +## Remarks The compiler found an identifier where it wasn't expected. Make sure that `identifier` is declared before you use it. 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: +## Examples + +The following example 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-c2062.md b/docs/error-messages/compiler-errors-1/compiler-error-c2062.md index 331da15078f..b7cd52a817f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2062.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2062.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2062" title: "Compiler Error C2062" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2062" +ms.date: 11/04/2016 f1_keywords: ["C2062"] helpviewer_keywords: ["C2062"] -ms.assetid: 6cc98353-2ddf-43ab-88a2-9cc91cdd6033 --- # Compiler Error C2062 -type 'type' unexpected +> type 'type' unexpected + +## Remarks The compiler did not expect a type name. -The following sample generates C2062: +## Example + +The following example generates C2062: ```cpp // C2062.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2063.md b/docs/error-messages/compiler-errors-1/compiler-error-c2063.md index 6bb9d67d1c7..474aaa30fc7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2063.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2063.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2063" title: "Compiler Error C2063" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2063" +ms.date: 11/04/2016 f1_keywords: ["C2063"] helpviewer_keywords: ["C2063"] -ms.assetid: 0a90c18f-4029-416a-9128-e8713b53e6f1 --- # Compiler Error C2063 -'identifier' : not a function +> 'identifier' : not a function + +## Remarks The identifier is used as a function but not declared as a function. -The following sample generates C2063: +## Example + +The following example generates C2063: ```c // C2063.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2064.md b/docs/error-messages/compiler-errors-1/compiler-error-c2064.md index 6d92b1ba307..2714aee760d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2064.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2064.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2064" title: "Compiler Error C2064" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2064" +ms.date: 11/04/2016 f1_keywords: ["C2064"] helpviewer_keywords: ["C2064"] -ms.assetid: 6cda05da-f437-4f50-9813-ae69538713a3 --- # Compiler Error C2064 -term does not evaluate to a function taking N arguments +> term does not evaluate to a function taking N arguments + +## Remarks A call is made to a function through an expression. The expression does not evaluate to a pointer to a function that takes the specified number of arguments. -In this example, the code attempts to call non-functions as functions. The following sample generates C2064: +## Examples + +In this example, the code attempts to call non-functions as functions. The following example generates C2064: ```cpp // C2064.cpp @@ -24,7 +27,7 @@ void func() { } ``` -You must call pointers to non-static member functions from the context of an object instance. The following sample generates C2064, and shows how to fix it: +You must call pointers to non-static member functions from the context of an object instance. The following example generates C2064, and shows how to fix it: ```cpp // C2064b.cpp @@ -43,7 +46,7 @@ int main() { } ``` -Within a class, member function pointers must also indicate the calling object context. The following sample generates C2064 and shows how to fix it: +Within a class, member function pointers must also indicate the calling object context. The following example generates C2064 and shows how to fix it: ```cpp // C2064d.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2065.md b/docs/error-messages/compiler-errors-1/compiler-error-c2065.md index e18d5004506..9081a6fe978 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2065.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2065.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2065" title: "Compiler Error C2065" +description: "Learn more about: Compiler Error C2065" ms.date: 06/29/2022 f1_keywords: ["C2065"] helpviewer_keywords: ["C2065"] -ms.assetid: 78093376-acb7-45f5-9323-5ed7e0aab1dc --- # Compiler Error C2065 > '*identifier*' : undeclared identifier +## Remarks + The compiler can't find the declaration for an identifier. There are many possible causes for this error. The most common causes of C2065 are that the identifier hasn't been declared, the identifier is misspelled, the header where the identifier is declared isn't included in the file, or the identifier is missing a scope qualifier, for example, `cout` instead of `std::cout`. For more information on declarations in C++, see [Declarations and Definitions (C++)](../../cpp/declarations-and-definitions-cpp.md). Here are some common issues and solutions in greater detail. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2066.md b/docs/error-messages/compiler-errors-1/compiler-error-c2066.md index 8a0b42ca727..a55f64b22f2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2066.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2066.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2066" title: "Compiler Error C2066" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2066" +ms.date: 11/04/2016 f1_keywords: ["C2066"] helpviewer_keywords: ["C2066"] -ms.assetid: f1efc63f-948a-410b-bf6e-ba250d52cd38 --- # Compiler Error C2066 -cast to function type is illegal +> cast to function type is illegal + +## Remarks In ANSI C, it is not legal to cast between a function pointer and a data pointer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2067.md b/docs/error-messages/compiler-errors-1/compiler-error-c2067.md index e5e1e4ab588..892535c0560 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2067.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2067.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2067" title: "Compiler Error C2067" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2067" +ms.date: 11/04/2016 f1_keywords: ["C2067"] helpviewer_keywords: ["C2067"] -ms.assetid: 97cab473-a713-489f-8536-ca2cc5792b8c --- # Compiler Error C2067 -cast to array type is illegal +> cast to array type is illegal + +## Remarks An object was cast to an array type. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2068.md b/docs/error-messages/compiler-errors-1/compiler-error-c2068.md new file mode 100644 index 00000000000..9f31bb8a1d3 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2068.md @@ -0,0 +1,26 @@ +--- +title: "Compiler Error C2068" +description: "Learn more about: Compiler Error C2068" +ms.date: 08/18/2022 +f1_keywords: ["C2068"] +helpviewer_keywords: ["C2068"] +--- +# Compiler Error C2068 + +> illegal use of overloaded function. Missing argument list? + +## Remarks + +The compiler detected the invalid use of an overloaded function with no arguments. + +## Example + +For example: + +```cpp +void f(int x) {} +void f(char x) {} +void g() noexcept( noexcept(f) ); +``` + +To resolve this issue, include the argument types required to resolve the function overload. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2069.md b/docs/error-messages/compiler-errors-1/compiler-error-c2069.md index f0170cb6ac3..ba2b9bea9a2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2069.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2069.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2069" title: "Compiler Error C2069" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2069" +ms.date: 11/04/2016 f1_keywords: ["C2069"] helpviewer_keywords: ["C2069"] -ms.assetid: 0c87445a-9eed-4917-a733-f08217f2d64d --- # Compiler Error C2069 -cast of 'void' term to non-'void' +> cast of 'void' term to non-'void' + +## Remarks Type **`void`** cannot be cast to any other type. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2070.md b/docs/error-messages/compiler-errors-1/compiler-error-c2070.md index 76cac0d4b89..2d2828762f2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2070.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2070.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2070" title: "Compiler Error C2070" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2070" +ms.date: 11/04/2016 f1_keywords: ["C2070"] helpviewer_keywords: ["C2070"] -ms.assetid: 4c8dea63-1227-4aba-be26-2462537f86fb --- # Compiler Error C2070 -'type': illegal sizeof operand +> 'type': illegal sizeof operand + +## Remarks The [sizeof](../../cpp/sizeof-operator.md) operator requires an expression or type name. -The following sample generates C2070: +## Example + +The following example generates C2070: ```cpp // C2070.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2071.md b/docs/error-messages/compiler-errors-1/compiler-error-c2071.md index 1bfd7926e5f..40faec7cb70 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2071.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2071.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2071" title: "Compiler Error C2071" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2071" +ms.date: 11/04/2016 f1_keywords: ["C2071"] helpviewer_keywords: ["C2071"] -ms.assetid: f8c09255-a5c4-47e3-8089-3d875ae43cc5 --- # Compiler Error C2071 -'identifier' : illegal storage class +> 'identifier' : illegal storage class + +## Remarks `identifier` was declared with an invalid [storage class](../../c-language/c-storage-classes.md). This error can be caused when more than one storage class is specified for an identifier, or when the definition is incompatible with the storage class declaration. @@ -16,7 +17,7 @@ To fix this issue, understand the intended storage class of the identifier—for ## Examples -The following sample generates C2071. +The following example generates C2071. ```cpp // C2071.cpp @@ -29,7 +30,7 @@ struct D { }; ``` -The following sample generates C2071. +The following example generates C2071. ```cpp // C2071_b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2072.md b/docs/error-messages/compiler-errors-1/compiler-error-c2072.md index 027a73b4a2f..479dfaf4317 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2072.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2072.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2072" title: "Compiler Error C2072" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2072" +ms.date: 11/04/2016 f1_keywords: ["C2072"] helpviewer_keywords: ["C2072"] -ms.assetid: 0b19a847-61dd-4bc3-b54d-108a637a4424 --- # Compiler Error C2072 -'identifier' : initialization of a function +> 'identifier' : initialization of a function + +## Remarks A function initializer was specified incorrectly. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2073.md b/docs/error-messages/compiler-errors-1/compiler-error-c2073.md index d442ba8bbbc..3db2c03db5e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2073.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2073.md @@ -1,18 +1,23 @@ --- -description: "Learn more about: Compiler Error C2073" title: "Compiler Error C2073" +description: "Learn more about: Compiler Error C2073" ms.date: 06/29/2022 f1_keywords: ["C2073"] helpviewer_keywords: ["C2073"] -ms.assetid: 57908234-be7a-4ce9-b0a7-8b1ad621865e --- # Compiler Error C2073 > 'identifier' : elements of partially initialized array must have a default constructor +## Remarks + Too few initializers were specified for an array of user-defined types or constants. If an explicit initializer and its corresponding constructor are not specified for an array member, a default constructor must be supplied. -The following sample generates C2073. Source file `C2073.cpp`: +This compiler error is obsolete in Visual Studio 2022. + +## Example + +The following example generates C2073. Source file `C2073.cpp`: ```cpp // C2073.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2074.md b/docs/error-messages/compiler-errors-1/compiler-error-c2074.md index 0e2f7f6326e..8221fccd282 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2074.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2074.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2074" title: "Compiler Error C2074" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2074" +ms.date: 11/04/2016 f1_keywords: ["C2074"] helpviewer_keywords: ["C2074"] -ms.assetid: 1abe5934-61db-4374-8c48-1fa7281317f4 --- # Compiler Error C2074 -'identifier' : 'class-key' initialization needs curly braces +> 'identifier' : 'class-key' initialization needs curly braces + +## Remarks There were no curly braces around the specified class, structure, or union initializer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2075.md b/docs/error-messages/compiler-errors-1/compiler-error-c2075.md index b83c31b4f74..8e47b3cd00e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2075.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2075.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2075" title: "Compiler Error C2075" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2075" +ms.date: 11/04/2016 f1_keywords: ["C2075"] helpviewer_keywords: ["C2075"] -ms.assetid: 8b1865d2-540b-4117-b982-e7a58a0b6cf7 --- # Compiler Error C2075 -'identifier' : array initialization needs curly braces +> 'identifier' : array initialization needs curly braces + +## Remarks There were no curly braces around the specified array initializer. -The following sample generates C2075: +## Example + +The following example generates C2075: ```c // C2075.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2076.md b/docs/error-messages/compiler-errors-1/compiler-error-c2076.md new file mode 100644 index 00000000000..e20e53b4fa6 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2076.md @@ -0,0 +1,22 @@ +--- +title: "Compiler Error C2076" +description: "Learn more about: Compiler Error C2076" +ms.date: 08/18/2022 +f1_keywords: ["C2076"] +helpviewer_keywords: ["C2076"] +--- +# Compiler Error C2076 + +> a brace-enclosed initializer list cannot be used in a new-expression whose type contains 'auto/decltype(auto)' + +## Remarks + +If an **`auto`** type-specifier appears in the specifier sequence of a new type-identifier or the type-identifier of a **`new`** expression, the expression must contain an initializer of the form `( assignment-expression )`. The compiler deduces the type-identifier from the `assignment-expression` in the initializer. For example, + +```cpp +new auto(42); // new allocates int +auto c = new auto('a'); // c is of type char*, new allocates char +new (auto*)(static_cast(nullptr)); // allocates type short* +``` + +To resolve this issue, use parentheses to enclose the initialization value of the **`new`** expression. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2077.md b/docs/error-messages/compiler-errors-1/compiler-error-c2077.md index 824efd91f1f..720cf2cbf39 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2077.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2077.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2077" title: "Compiler Error C2077" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2077" +ms.date: 11/04/2016 f1_keywords: ["C2077"] helpviewer_keywords: ["C2077"] -ms.assetid: f046f0e3-1987-477a-a0af-fe543a9f5fcb --- # Compiler Error C2077 -non-scalar field initializer 'identifier' +> non-scalar field initializer 'identifier' + +## Remarks You tried to initialize a bit field with a nonscalar (struct, union, array, or class). Use an integer or floating-point value. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2078.md b/docs/error-messages/compiler-errors-1/compiler-error-c2078.md index 6cc3e1e1fe2..f2c6dfa626d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2078.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2078.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2078" title: "Compiler Error C2078" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2078" +ms.date: 11/04/2016 f1_keywords: ["C2078"] helpviewer_keywords: ["C2078"] -ms.assetid: 9bead850-4123-46cf-a634-5c77ba974b2b --- # Compiler Error C2078 -too many initializers +> too many initializers + +## Remarks The number of initializers exceeds the number of objects to be initialized. The compiler can deduce the correct assignment of initializers to objects and inner objects when inner braces are elided from the initializer list. Complete bracing also eliminates ambiguity and results in correct assignment. Partial bracing can cause C2078 because of ambiguity in the assignment of initializers to objects. -The following sample generates C2078 and shows how to fix it: +## Example + +The following example generates C2078 and shows how to fix it: ```cpp // C2078.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2079.md b/docs/error-messages/compiler-errors-1/compiler-error-c2079.md index c096d8ffb12..b4b8022579d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2079.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2079.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2079" title: "Compiler Error C2079" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2079" +ms.date: 11/04/2016 f1_keywords: ["C2079"] helpviewer_keywords: ["C2079"] -ms.assetid: ca58d6d5-eccd-40b7-ba14-c003223c5bc7 --- # Compiler Error C2079 -'identifier' uses undefined class/struct/union 'name' +> 'identifier' uses undefined class/struct/union 'name' + +## Remarks The specified identifier is an undefined class, structure, or union. This error can be caused by initializing an anonymous union. -The following sample generates C2079: +## Examples + +The following example generates C2079: ```cpp // C2079.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2080.md b/docs/error-messages/compiler-errors-1/compiler-error-c2080.md new file mode 100644 index 00000000000..43be41f7b5d --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2080.md @@ -0,0 +1,34 @@ +--- +title: "Compiler Error C2080" +description: "Learn more about: Compiler Error C2080" +ms.date: 08/18/2022 +f1_keywords: ["C2080"] +helpviewer_keywords: ["C2080"] +--- +# Compiler Error C2080 + +> '*identifier*': the type for '*type*' can only be deduced from a single initializer expression + +## Remarks + +The compiler can only deduce the type for `auto` or `decltype(auto)` if the declaration uses direct list-initialization and the initializer-list has a single element. + +## Example + +The following example shows some declarations that cause C2080: + +```cpp +auto x1(1, 2); // C2080 +auto x2({4}); // C2080 +decltype(auto) x3(1, 2); // C2080 +decltype(auto) x4({4}); // C2080 +``` + +To resolve the issue, use a single value initializer: + +```cpp +auto x1 = 1; // Valid +auto x2(1); // Valid +decltype(auto) x3 = 1; // Valid +decltype(auto) x4(1); // Valid +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2081.md b/docs/error-messages/compiler-errors-1/compiler-error-c2081.md index 39c5c3f2863..91f785dfd40 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2081.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2081.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2081" title: "Compiler Error C2081" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2081" +ms.date: 11/04/2016 f1_keywords: ["C2081"] helpviewer_keywords: ["C2081"] -ms.assetid: 7db9892d-364d-4178-a49d-f8398ece09a0 --- # Compiler Error C2081 -'identifier' : name in formal parameter list illegal +> 'identifier' : name in formal parameter list illegal + +## Remarks The identifier caused a syntax error. This error can be caused by using the old style for the formal parameter list. You must specify the type of formal parameters in the formal parameter list. -The following sample generates C2081: +## Example + +The following example generates C2081: ```c // C2081.c 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 25b3e93eed3..205cdfdc0e3 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2082.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2082.md @@ -1,23 +1,29 @@ --- -description: "Learn more about: Compiler Error C2082" title: "Compiler Error C2082" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2082" +ms.date: 11/04/2016 f1_keywords: ["C2082"] helpviewer_keywords: ["C2082"] -ms.assetid: 87a6d442-157c-46e8-9bff-8388f8338ae0 --- # Compiler Error C2082 -redefinition of formal parameter 'identifier' +> redefinition of formal parameter 'identifier' + +## Remarks A formal parameter to a function is redeclared within the function body. To resolve the error, remove the redefinition. -The following sample generates C2082: +## Example + +The following example 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-c2083.md b/docs/error-messages/compiler-errors-1/compiler-error-c2083.md index a3e24730c9d..c47d0828db9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2083.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2083.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2083" title: "Compiler Error C2083" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2083" +ms.date: 11/04/2016 f1_keywords: ["C2083"] helpviewer_keywords: ["C2083"] -ms.assetid: 5fc4f931-eab6-4d8d-a3ee-3b8e11e64b18 --- # Compiler Error C2083 -struct/union comparison illegal +> struct/union comparison illegal + +## Remarks A structure or union is compared directly with another user-defined type. This is not allowed unless a comparison operator has been defined or a conversion to a scalar type exists. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2084.md b/docs/error-messages/compiler-errors-1/compiler-error-c2084.md index 19f1c11e732..8133c53ace2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2084.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2084.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2084" title: "Compiler Error C2084" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2084" +ms.date: 11/04/2016 f1_keywords: ["C2084"] helpviewer_keywords: ["C2084"] -ms.assetid: 990b107f-3721-4851-ae8b-4b69a8c149ed --- # Compiler Error C2084 -function '*function*' already has a body +> function '*function*' already has a body + +## Remarks The function has already been defined. @@ -20,7 +21,7 @@ Before Visual Studio 2002, ## Example -The following sample generates C2084: +The following example generates C2084: ```cpp // C2084.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2085.md b/docs/error-messages/compiler-errors-1/compiler-error-c2085.md index fcd890fb8ec..ab918561c43 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2085.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2085.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2085" title: "Compiler Error C2085" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2085" +ms.date: 11/04/2016 f1_keywords: ["C2085"] helpviewer_keywords: ["C2085"] -ms.assetid: 0a86785c-8e6f-481b-8c7b-412220c1950d --- # Compiler Error C2085 -'identifier' : not in formal parameter list +> 'identifier' : not in formal parameter list + +## Remarks The identifier was declared in a function definition but not in the formal parameter list. (ANSI C only) -The following sample generates C2085: +## Example + +The following example generates C2085: ```c // C2085.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2086.md b/docs/error-messages/compiler-errors-1/compiler-error-c2086.md index 0041ca25136..a3cf0c60f0a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2086.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2086.md @@ -1,24 +1,27 @@ --- -description: "Learn more about: Compiler Error C2086" title: "Compiler Error C2086" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2086" +ms.date: 11/04/2016 f1_keywords: ["C2086"] helpviewer_keywords: ["C2086"] -ms.assetid: 4329bf72-90c8-444c-8524-4ef75e6b2139 --- # Compiler Error C2086 -'identifier' : redefinition +> 'identifier' : redefinition + +## Remarks The identifier is defined more than once, or a subsequent declaration differs from a previous one. C2086 can also be the result of incremental building for a referenced C# assembly. Rebuild the C# assembly to resolve this error. -The following sample generates C2086: +## Example + +The following example generates C2086: ```cpp // C2086.cpp -main() { +int main() { int a; int a; // C2086 not an error in ANSI C } diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2087.md b/docs/error-messages/compiler-errors-1/compiler-error-c2087.md index 990afe20506..bbda0677224 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2087.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2087.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2087" title: "Compiler Error C2087" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2087" +ms.date: 11/04/2016 f1_keywords: ["C2087"] helpviewer_keywords: ["C2087"] -ms.assetid: 89761e83-415a-4468-a4c6-b6dedfd1dd6a --- # Compiler Error C2087 -'identifier' : missing subscript +> 'identifier' : missing subscript + +## Remarks The definition of an array with multiple subscripts is missing a subscript value for a dimension higher than one. -The following sample generates C2087: +## Example + +The following example generates C2087: ```cpp // C2087.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2088.md b/docs/error-messages/compiler-errors-1/compiler-error-c2088.md index d25127ed208..372c228b7e0 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2088.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2088.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2088" title: "Compiler Error C2088" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2088" +ms.date: 11/04/2016 f1_keywords: ["C2088"] helpviewer_keywords: ["C2088"] -ms.assetid: b93f7094-185b-423d-8bb9-507cd757dbf5 --- # Compiler Error C2088 -'operator' : illegal for 'class-key' +> 'operator' : illegal for 'class-key' + +## Remarks The operator was not defined for the structure or union. This error is only valid for C code. -The following sample generates C2088 three times: +## Example + +The following example generates C2088 three times: ```c // C2088.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2089.md b/docs/error-messages/compiler-errors-1/compiler-error-c2089.md index 1bcf00bbc33..caf451167e6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2089.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2089.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2089" title: "Compiler Error C2089" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2089" +ms.date: 11/04/2016 f1_keywords: ["C2089"] helpviewer_keywords: ["C2089"] -ms.assetid: 7c777775-5535-4eea-b6a2-340b71af9560 --- # Compiler Error C2089 -'identifier' : 'class-key' too large +> 'identifier' : 'class-key' too large + +## Remarks The specified structure or union exceeds the 4GB limit. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2090.md b/docs/error-messages/compiler-errors-1/compiler-error-c2090.md index 715aaff8d3c..384319cefd7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2090.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2090.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2090" title: "Compiler Error C2090" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2090" +ms.date: 11/04/2016 f1_keywords: ["C2090"] helpviewer_keywords: ["C2090"] -ms.assetid: e8176e55-382b-453d-aa27-6597f0274afd --- # Compiler Error C2090 -function returns array +> function returns array + +## Remarks A function cannot return an array. Return a pointer to an array instead. -The following sample generates C2090: +## Example + +The following example generates C2090: ```cpp // C2090.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2091.md b/docs/error-messages/compiler-errors-1/compiler-error-c2091.md index 9b354713a20..e873a8864ef 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2091.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2091.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2091" title: "Compiler Error C2091" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2091" +ms.date: 11/04/2016 f1_keywords: ["C2091"] helpviewer_keywords: ["C2091"] -ms.assetid: 247c3b57-f123-4420-b68e-d65a364b63cb --- # Compiler Error C2091 -function returns function +> function returns function + +## Remarks A function cannot return a function. Return a pointer to a function instead. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2092.md b/docs/error-messages/compiler-errors-1/compiler-error-c2092.md index ed654b5ab5e..3b07baae29f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2092.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2092.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2092" title: "Compiler Error C2092" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2092" +ms.date: 11/04/2016 f1_keywords: ["C2092"] helpviewer_keywords: ["C2092"] -ms.assetid: 037e44ae-16c8-489a-a512-dcdf7f7795a6 --- # Compiler Error C2092 -'array name' array element type cannot be function +> 'array name' array element type cannot be function + +## Remarks Arrays of functions are not allowed. Use an array of pointers to functions. -## Examples +## Example -The following sample generates C2092: +The following example generates C2092: ```cpp // C2092.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2093.md b/docs/error-messages/compiler-errors-1/compiler-error-c2093.md index 4cf2f9332a5..ea575c36681 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2093.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2093.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2093" title: "Compiler Error C2093" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2093" +ms.date: 11/04/2016 f1_keywords: ["C2093"] helpviewer_keywords: ["C2093"] -ms.assetid: 17529a70-9169-46b5-9fc6-57a5ce224e6a --- # Compiler Error C2093 -'variable1' : cannot be initialized using address of automatic variable 'variable2' +> 'variable1' : cannot be initialized using address of automatic variable 'variable2' + +## Remarks When compiling with [/Za](../../build/reference/za-ze-disable-language-extensions.md), the program tried to use the address of an automatic variable as an initializer. -The following sample generates C2093: +## Example + +The following example generates C2093: ```c // C2093.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2094.md b/docs/error-messages/compiler-errors-1/compiler-error-c2094.md index 2fd470d2dd6..3c06cae2fe6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2094.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2094.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2094" title: "Compiler Error C2094" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2094" +ms.date: 11/04/2016 f1_keywords: ["C2094"] helpviewer_keywords: ["C2094"] -ms.assetid: 9e4f8f88-f189-46e7-91c9-481bacc7af87 --- # Compiler Error C2094 -label 'identifier' was undefined +> label 'identifier' was undefined + +## Remarks The label used by a [goto](../../cpp/goto-statement-cpp.md) statement does not exist in the function. ## Example -The following sample generates C2094: +The following example generates C2094: ```cpp // C2094.c 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 8224cfb3a8e..8a998415a2c 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,16 @@ --- -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' +> 'function' : actual parameter has type 'void' : parameter 'number' + +## Remarks -The parameter passed to the function is type **`void`**, which is not allowed. Use a pointer to void ( `void *`) instead. +The parameter passed to the function is type **`void`**, which is not allowed. Use a pointer to void (`void *`) instead. The `number` indicates which parameter is **`void`**. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2096.md b/docs/error-messages/compiler-errors-1/compiler-error-c2096.md new file mode 100644 index 00000000000..9121807028e --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2096.md @@ -0,0 +1,14 @@ +--- +title: "Compiler Error C2096" +description: "Learn more about: Compiler Error C2096" +ms.date: 08/23/2022 +f1_keywords: ["C2096"] +helpviewer_keywords: ["C2096"] +--- +# Compiler Error C2096 + +> '*identifier*': A data member cannot be initialized with a parenthesized initializer + +## Remarks + +The compiler expected a braced initializer or an equal expression initializer. To resolve the issue, replace the parenthesized initializer with a braced initializer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2097.md b/docs/error-messages/compiler-errors-1/compiler-error-c2097.md index b17f2535fbd..0c01d1f89aa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2097.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2097.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2097" title: "Compiler Error C2097" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2097" +ms.date: 11/04/2016 f1_keywords: ["C2097"] helpviewer_keywords: ["C2097"] -ms.assetid: 7e5b2fd4-f61c-4b8a-b265-93e987a04bd3 --- # Compiler Error C2097 -illegal initialization +> illegal initialization ### To fix by checking the following possible causes diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2098.md b/docs/error-messages/compiler-errors-1/compiler-error-c2098.md new file mode 100644 index 00000000000..886f3d8f80a --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2098.md @@ -0,0 +1,14 @@ +--- +title: "Compiler Error C2098" +description: "Learn more about: Compiler Error C2098" +ms.date: 08/23/2022 +f1_keywords: ["C2098"] +helpviewer_keywords: ["C2098"] +--- +# Compiler Error C2098 + +> unexpected token after data member '*identifier*' + +## Remarks + +The compiler expected a semicolon, a braced initializer or an equal expression initializer. To resolve the issue, insert a semicolon or an initializer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2099.md b/docs/error-messages/compiler-errors-1/compiler-error-c2099.md index 05dd905b4a8..1547eff225b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2099.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2099.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2099" title: "Compiler Error C2099" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2099" +ms.date: 11/04/2016 f1_keywords: ["C2099"] helpviewer_keywords: ["C2099"] -ms.assetid: 30e151ee-d458-4901-b0c0-d45054a913f5 --- # Compiler Error C2099 -initializer is not a constant +> initializer is not a constant + +## Remarks This error is issued only by the C compiler and occurs only for non-automatic variables. The compiler initializes non-automatic variables at the start of the program and the values they are initialized with must be constant. ## Examples -The following sample generates C2099. +The following example generates C2099. ```c // C2099.c @@ -31,7 +32,7 @@ To resolve this error, compile the module as a .cpp file or simplify the express For more information, see [/fp (Specify Floating-Point Behavior)](../../build/reference/fp-specify-floating-point-behavior.md). -The following sample generates C2099. +The following example generates C2099. ```c // C2099_2.c 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 8c691295285..e89c4bde438 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2100.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2100.md @@ -1,18 +1,21 @@ --- -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 +> illegal indirection + +## Remarks + +Indirection operator (`*`) is applied to a nonpointer value. -Indirection operator ( `*` ) is applied to a nonpointer value. +## Example -The following sample generates C2100: +The following example generates C2100: ```cpp // C2100.cpp 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 70d8b692fb2..e2703e5d860 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,26 @@ --- -description: "Learn more about: Compiler Error C2101" title: "Compiler Error C2101" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2101" +ms.date: 03/04/2024 f1_keywords: ["C2101"] helpviewer_keywords: ["C2101"] -ms.assetid: 42f0136f-8cc1-4f2b-be1c-721ec9278e66 --- # Compiler Error C2101 -'&' on constant +> '&' on constant + +## Remarks + +The [address-of operator (**`&`**)](../../cpp/address-of-operator-amp.md) must have an l-value as operand. -The address-of operator ( `&` ) must have an l-value as operand. +## Example -The following sample generates C2101: +The following example 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 2c71c692bea..7db34d038f0 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,31 @@ --- -description: "Learn more about: Compiler Error C2102" title: "Compiler Error C2102" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2102" +ms.date: 03/03/2024 f1_keywords: ["C2102"] helpviewer_keywords: ["C2102"] -ms.assetid: d15b5fa3-fa46-4cd4-a3d2-3661646ecb7a --- # Compiler Error C2102 -'&' requires l-value +> '&' requires l-value + +## Remarks + +The [address-of operator (**`&`**)](../../cpp/address-of-operator-amp.md) must have an l-value as operand. Address of temporary values cannot be taken. + +## Example + +The following example generates C2102: + +```cpp +// C2102.cpp +int func() +{ + return 1; +} -The address-of operator ( `&` ) must have an l-value as operand. +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 0c2a9d28ed1..af055b688c2 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,30 @@ --- -description: "Learn more about: Compiler Error C2103" title: "Compiler Error C2103" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2103" +ms.date: 03/04/2024 f1_keywords: ["C2103"] helpviewer_keywords: ["C2103"] -ms.assetid: dfe95972-35e9-469a-b8a8-52c849d4e4e4 --- # Compiler Error C2103 -'&' on register variable +> '&' on register variable + +## Remarks You cannot take the address of a register. + +## Example + +The following example 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-c2104.md b/docs/error-messages/compiler-errors-1/compiler-error-c2104.md index b2640fdd2d0..957f09c7a3f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2104.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2104.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2104" title: "Compiler Error C2104" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2104" +ms.date: 11/04/2016 f1_keywords: ["C2104"] helpviewer_keywords: ["C2104"] -ms.assetid: 2ea78896-72a6-4901-a1fa-f33ea88ad61b --- # Compiler Error C2104 -'&' on bit field ignored +> '&' on bit field ignored + +## Remarks You cannot take the address of a bit field. -The following sample generates C2104: +## Example + +The following example generates C2104: ```cpp // C2104.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2105.md b/docs/error-messages/compiler-errors-1/compiler-error-c2105.md index 68cf1a2ad6c..55de44e8302 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2105.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2105.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2105" title: "Compiler Error C2105" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2105" +ms.date: 11/04/2016 f1_keywords: ["C2105"] helpviewer_keywords: ["C2105"] -ms.assetid: 19b7f7bc-a9da-4d23-8193-005b6d09274f --- # Compiler Error C2105 -'operator' needs l-value +> 'operator' needs l-value + +## Remarks The operator must have an l-value as operand. -The following sample generates C2105: +## Examples + +The following example generates C2105: ```cpp // C2105.cpp @@ -29,7 +32,7 @@ int main() { } ``` -The following sample generates C2105: +The following example generates C2105: ```cpp // C2105b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2106.md b/docs/error-messages/compiler-errors-1/compiler-error-c2106.md index 58fec648a53..e22d82019d7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2106.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2106.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2106" title: "Compiler Error C2106" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2106" +ms.date: 11/04/2016 f1_keywords: ["C2106"] helpviewer_keywords: ["C2106"] -ms.assetid: d5c91a2e-04e4-4770-8478-788b98c52a53 --- # Compiler Error C2106 -'operator' : left operand must be l-value +> 'operator' : left operand must be l-value + +## Remarks The operator must have an l-value as its left operand. -The following sample generates C2106: +## Example + +The following example generates C2106: ```cpp // C2106.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2107.md b/docs/error-messages/compiler-errors-1/compiler-error-c2107.md index 1644f153374..51bcd37722f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2107.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2107.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2107" title: "Compiler Error C2107" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2107" +ms.date: 11/04/2016 f1_keywords: ["C2107"] helpviewer_keywords: ["C2107"] -ms.assetid: 2866a121-884e-4bb5-8613-36de5817000e --- # Compiler Error C2107 -illegal index, indirection not allowed +> illegal index, indirection not allowed + +## Remarks A subscript is applied to an expression that does not evaluate to a pointer. @@ -16,7 +17,7 @@ A subscript is applied to an expression that does not evaluate to a pointer. C2107 can occur if you incorrectly use the **`this`** pointer of a value type to access the type's default indexer. For more information, see [Semantics of the `this` pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). -The following sample generates C2107. +The following example generates C2107. ```cpp // C2107.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2108.md b/docs/error-messages/compiler-errors-1/compiler-error-c2108.md index 4560690ae78..fa7b26db53e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2108.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2108.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2108" title: "Compiler Error C2108" +description: "Learn more about: Compiler Error C2108" ms.date: 06/03/2022 f1_keywords: ["C2108"] helpviewer_keywords: ["C2108"] -ms.assetid: c84f0b47-5e2c-47d2-8edb-427a40e17c36 --- # Compiler Error C2108 @@ -18,7 +17,7 @@ The array subscript is a non-integer expression. C2108 can occur if you incorrectly use the **`this`** pointer of a value type to access the type's default indexer. For more information, see [Semantics of the `this` pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). -The following sample generates C2108. +The following example generates C2108. ```cpp // C2108.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2109.md b/docs/error-messages/compiler-errors-1/compiler-error-c2109.md index c6bff1af2df..8092ba90016 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2109.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2109.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2109" title: "Compiler Error C2109" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2109" +ms.date: 11/04/2016 f1_keywords: ["C2109"] helpviewer_keywords: ["C2109"] -ms.assetid: 2d1ac79d-a985-4904-a38b-b270578d664d --- # Compiler Error C2109 -subscript requires array or pointer type +> subscript requires array or pointer type + +## Remarks The subscript was used on a variable that was not an array. -The following sample generates C2109: +## Example + +The following example generates C2109: ```cpp // C2109.cpp 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 6136d130b17..480293e439d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2110.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2110.md @@ -1,18 +1,21 @@ --- -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 +> '+' : cannot add two pointers + +## Remarks + +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. +## Example -The following sample generates C2110: +The following example generates C2110: ```cpp // C2110.cpp 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 10ba943b728..f8a9305aa9b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2111.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2111.md @@ -1,18 +1,21 @@ --- -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 +> '+' : pointer addition requires integral operand + +## Remarks + +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. +## Example -The following sample generates C2111: +The following example generates C2111: ```cpp // C2111.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2112.md b/docs/error-messages/compiler-errors-1/compiler-error-c2112.md index 8c4236d97a3..1928506edc0 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2112.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2112.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2112" title: "Compiler Error C2112" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2112" +ms.date: 11/04/2016 f1_keywords: ["C2112"] helpviewer_keywords: ["C2112"] -ms.assetid: 527a2fea-f585-4d00-bbb4-477aee17144b --- # Compiler Error C2112 -'-' : pointer subtraction requires integral or pointer operand +> '-' : pointer subtraction requires integral or pointer operand + +## Remarks An attempt was made to subtract pointers that point to different types. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2113.md b/docs/error-messages/compiler-errors-1/compiler-error-c2113.md index e22c5d9a149..bfeb4b2390c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2113.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2113.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2113" title: "Compiler Error C2113" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2113" +ms.date: 11/04/2016 f1_keywords: ["C2113"] helpviewer_keywords: ["C2113"] -ms.assetid: be85cb5e-b0ed-4fc9-b062-032bf7f59a4e --- # Compiler Error C2113 -'-' : pointer can only be subtracted from another pointer +> '-' : pointer can only be subtracted from another pointer + +## Remarks The right operand in a subtraction operation was a pointer, but the left operand was not. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2114.md b/docs/error-messages/compiler-errors-1/compiler-error-c2114.md index ada80748121..75831e51f9d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2114.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2114.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2114" title: "Compiler Error C2114" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2114" +ms.date: 11/04/2016 f1_keywords: ["C2114"] helpviewer_keywords: ["C2114"] -ms.assetid: c1b2445f-74eb-4dc8-8d5a-6c8627775ee8 --- # Compiler Error C2114 -'operator' : pointer on left; needs integral value on right +> 'operator' : pointer on left; needs integral value on right + +## Remarks The left operand of `operator` was a pointer, so the right operand must be an integer value. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2115.md b/docs/error-messages/compiler-errors-1/compiler-error-c2115.md index 2125c5674c6..52147bca167 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2115.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2115.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2115" title: "Compiler Error C2115" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2115" +ms.date: 11/04/2016 f1_keywords: ["C2115"] helpviewer_keywords: ["C2115"] -ms.assetid: 95d76ab5-ddd7-4e29-8cac-24285dccc490 --- # Compiler Error C2115 -'identifier' : incompatible types +> 'identifier' : incompatible types + +## Remarks An expression contained incompatible types. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2116.md b/docs/error-messages/compiler-errors-1/compiler-error-c2116.md index 9dfd0d52b9c..f0b37397e6f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2116.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2116.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: Compiler Error C2116" title: "Compiler Error C2116" +description: "Learn more about: Compiler Error C2116" ms.date: 12/02/2021 f1_keywords: ["C2116"] helpviewer_keywords: ["C2116"] -ms.assetid: 0089a23f-e6bd-4956-9b58-3bcca09ab5ad --- # Compiler Error C2116 > function parameter lists do not match between declarations -The parameter list of a redeclared function doesn't match the parameter list used in an earlier declaration. - ## Remarks +The parameter list of a redeclared function doesn't match the parameter list used in an earlier declaration. + This error can occur if you use different types for the parameters when you redeclare an `extern "C"` function. This error may occur after an upgrade because of conformance changes in Visual Studio 2019. Starting in Visual Studio 2019 version 16.3, the [`/Zc:externC-`](../../build/reference/zc-externc.md) compiler option relaxes this check. The option must come after any [`/permissive-`](../../build/reference/permissive-standards-conformance.md) option on the command line. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2117.md b/docs/error-messages/compiler-errors-1/compiler-error-c2117.md index 1b5aeb3f185..9776f59ce2e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2117.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2117.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2117" title: "Compiler Error C2117" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2117" +ms.date: 11/04/2016 f1_keywords: ["C2117"] helpviewer_keywords: ["C2117"] -ms.assetid: b947379d-5861-42fc-ac26-170318579cbd --- # Compiler Error C2117 -'identifier' : array bounds overflow +> 'identifier' : array bounds overflow + +## Remarks An array has too many initializers: @@ -16,7 +17,9 @@ An array has too many initializers: - No space for the null terminator in a string. -The following sample generates C2117: +## Example + +The following example generates C2117: ```cpp // C2117.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2118.md b/docs/error-messages/compiler-errors-1/compiler-error-c2118.md index b10252e5e57..b033bb8ddc7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2118.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2118.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2118" title: "Compiler Error C2118" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2118" +ms.date: 11/04/2016 f1_keywords: ["C2118"] helpviewer_keywords: ["C2118"] -ms.assetid: bf4315d0-f085-4323-b813-96ee61a13bde --- # Compiler Error C2118 -negative subscript +> negative subscript + +## Remarks The value defining the array size is larger than the maximum array size or smaller than zero. -The following sample generates C2118: +## Example + +The following example generates C2118: ```cpp // C2118.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2120.md b/docs/error-messages/compiler-errors-1/compiler-error-c2120.md index fe8ca7df9c9..b3f630d7c1a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2120.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2120.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2120" title: "Compiler Error C2120" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2120" +ms.date: 11/04/2016 f1_keywords: ["C2120"] helpviewer_keywords: ["C2120"] -ms.assetid: b0f3f66c-6cd2-4f48-9ea3-c270b53c2b8c --- # Compiler Error C2120 -'void' illegal with all types +> 'void' illegal with all types + +## Remarks The **`void`** type is used in a declaration with another type. -The following sample generates C2120: +## Example + +The following example generates C2120: ```cpp // C2120.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2121.md b/docs/error-messages/compiler-errors-1/compiler-error-c2121.md index bcd354b2fc1..3c2b4770564 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2121.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2121.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2121" title: "Compiler Error C2121" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2121" +ms.date: 11/04/2016 f1_keywords: ["C2121"] helpviewer_keywords: ["C2121"] -ms.assetid: e04f32da-3736-4df3-8a1c-d687afcecf5c --- # Compiler Error C2121 -'#' : invalid character : possibly the result of a macro expansion +> '#' : invalid character : possibly the result of a macro expansion + +## Remarks An invalid # character may have been inserted by an incorrect macro that uses the token-pasting operator (##) instead of the stringizing operator (#). diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2122.md b/docs/error-messages/compiler-errors-1/compiler-error-c2122.md index a71d88a415f..31ae2f699a5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2122.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2122.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2122" title: "Compiler Error C2122" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2122" +ms.date: 11/04/2016 f1_keywords: ["C2122"] helpviewer_keywords: ["C2122"] -ms.assetid: bc060002-cd38-481b-a144-65af035ce851 --- # Compiler Error C2122 -'identifier' : prototype parameter in name list illegal +> 'identifier' : prototype parameter in name list illegal + +## Remarks The parameter is not a legal type. ANSI C does not support user-defined types. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2124.md b/docs/error-messages/compiler-errors-1/compiler-error-c2124.md index 66e5e748be4..e20cba89e6a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2124.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2124.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2124" title: "Compiler Error C2124" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2124" +ms.date: 11/04/2016 f1_keywords: ["C2124"] helpviewer_keywords: ["C2124"] -ms.assetid: 93392aaa-5582-4d68-8cc5-bd9c62a0ae7e --- # Compiler Error C2124 -divide or mod by zero +> divide or mod by zero + +## Remarks A constant expression has a zero denominator. To resolve the error, do not divide by zero. -The following sample generates C2124: +## Example + +The following example generates C2124: ```cpp // C2124.cpp 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 3d964e79d87..a2d21596f72 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2128.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2128.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2128" title: "Compiler Error C2128" -ms.date: "11/04/2016" -f1_keywords: ["c2128"] +description: "Learn more about: Compiler Error C2128" +ms.date: 11/04/2016 +f1_keywords: ["C2128"] helpviewer_keywords: ["C2128"] -ms.assetid: 08cbf734-75b3-49f2-9026-9b319947612d --- # Compiler Error C2128 -'function' : alloc_text/same_seg applicable only to functions with C linkage +> 'function' : alloc_text/same_seg applicable only to functions with C linkage + +## Remarks `#pragma alloc_text` can only be used with functions declared to have C linkage. -The following sample generates C2128: +## Example + +The following example generates C2128: ```cpp // C2128.cpp 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 a6945a3fc54..161c15cfb96 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2129.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2129.md @@ -1,15 +1,42 @@ --- -description: "Learn more about: Compiler Error C2129" title: "Compiler Error C2129" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2129" +ms.date: 11/04/2016 f1_keywords: ["C2129"] helpviewer_keywords: ["C2129"] -ms.assetid: 21a8223e-1d22-4baa-9ca1-922b7f751dd0 --- # Compiler Error C2129 -static function 'function' declared but not defined +> static function 'function' declared but not defined + +## Remarks 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`**. + +## Example + +The following example 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-c2130.md b/docs/error-messages/compiler-errors-1/compiler-error-c2130.md index cf56b31a742..5f1fd271618 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2130.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2130.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2130" title: "Compiler Error C2130" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2130" +ms.date: 11/04/2016 f1_keywords: ["C2130"] helpviewer_keywords: ["C2130"] -ms.assetid: c6fd5a7e-8f28-4f67-99d1-95a13b0dff90 --- # Compiler Error C2130 -\#line expected a string containing the filename, found 'token' +> #line expected a string containing the filename, found 'token' + +## Remarks The optional file name token following [#line](../../preprocessor/hash-line-directive-c-cpp.md) `linenumber` must be a string. -The following sample generates C2130: +## Example + +The following example generates C2130: ```cpp // C2130.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2131.md b/docs/error-messages/compiler-errors-1/compiler-error-c2131.md index 90733559e1d..32855ce4313 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2131.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2131.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Error C2131" title: "Compiler Error C2131" -ms.date: "02/28/2019" +description: "Learn more about: Compiler Error C2131" +ms.date: 02/28/2019 f1_keywords: ["C2131"] helpviewer_keywords: ["C2131"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["C2131"] > expression did not evaluate to a constant +## Remarks + An expression declared as **`const`** or **`constexpr`** didn't evaluate to a constant at compile time. The compiler must be able to determine the value of the expression at the point it's used. ## Example diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2132.md b/docs/error-messages/compiler-errors-1/compiler-error-c2132.md index c4c21615336..0bf9a330741 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2132.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2132.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2132" title: "Compiler Error C2132" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2132" +ms.date: 11/04/2016 f1_keywords: ["C2132"] helpviewer_keywords: ["C2132"] -ms.assetid: 32902472-49d1-4513-888f-b52d336839d5 --- # Compiler Error C2132 -syntax error : unexpected identifier +> syntax error : unexpected identifier + +## Remarks An identifier appears in an unsupported context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2133.md b/docs/error-messages/compiler-errors-1/compiler-error-c2133.md index bc9e05e319d..fbeed35e5b4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2133.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2133.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2133" title: "Compiler Error C2133" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2133" +ms.date: 11/04/2016 f1_keywords: ["C2133"] helpviewer_keywords: ["C2133"] -ms.assetid: 8942f9e8-9818-468f-97db-09dbd124fcae --- # Compiler Error C2133 -'identifier' : unknown size +> 'identifier' : unknown size + +## Remarks An unsized array is declared as a member of a class, structure, union, or enumeration. The /Za (ANSI C) option does not allow unsized member arrays. -The following sample generates C2133: +## Example + +The following example generates C2133: ```cpp // C2133.cpp 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 a46a3837848..2e79ffe2bb8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2134.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2134.md @@ -1,24 +1,28 @@ --- -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 -'function' : call does not result in a constant expression +> 'function' : call does not result in a constant expression + +## Remarks A function declared as constexpr can only call other functions declared as constexpr. -The following sample generates C2134: +## Example + +The following example generates C2134: ```cpp // C2134.cpp // 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 +35,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-c2135.md b/docs/error-messages/compiler-errors-1/compiler-error-c2135.md index d830da92acb..aff3621ccb1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2135.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2135.md @@ -1,30 +1,38 @@ --- -description: "Learn more about: Compiler Error C2135" title: "Compiler Error C2135" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2135" +ms.date: 08/13/2025 f1_keywords: ["C2135"] helpviewer_keywords: ["C2135"] -ms.assetid: aa360d22-4f79-4de1-b384-93cadd10975f --- # Compiler Error C2135 -'bit operator' : illegal bit field operation +> '*identifier*': you cannot apply '*operator*' to a bit-field + +## Remarks + +The [address-of operator (`&`)](../../cpp/address-of-operator-amp.md), [unary plus operator (`+`)](../../cpp/unary-plus-and-negation-operators-plus-and.md), [unary negation operator (`-`)](../../cpp/unary-plus-and-negation-operators-plus-and.md), [logical negation operator (`!`)](../../cpp/logical-negation-operator-exclpt.md), [one's complement operator (`~`)](../../cpp/one-s-complement-operator-tilde.md), and [indirection operator (`*`)](../../cpp/indirection-operator-star.md) cannot be applied to a bit-field in this context. -The address-of operator (`&`) cannot be applied to a bit field. +## Example -The following sample generates C2135: +The following example generates C2135: ```cpp // C2135.cpp -struct S { - int i : 1; -}; -struct T { - int j; +struct S +{ + int bit_field : 1; + int integer; }; -int main() { - &S::i; // C2135 address of a bit field - &T::j; // OK + +int main() +{ + &S::bit_field; // C2135 + &S::integer; // OK } ``` + +## See also + +[C2104](compiler-error-c2104.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2137.md b/docs/error-messages/compiler-errors-1/compiler-error-c2137.md index bb5b13eaa61..283c3c3777a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2137.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2137.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2137" title: "Compiler Error C2137" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2137" +ms.date: 11/04/2016 f1_keywords: ["C2137"] helpviewer_keywords: ["C2137"] -ms.assetid: 984687ee-7766-4f6b-ae15-0c9a010e2366 --- # Compiler Error C2137 -empty character constant +> empty character constant + +## Remarks The empty character constant ( ' ' ) is not permitted. -The following sample generates C2137: +## Example + +The following example generates C2137: ```cpp // C2137.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2138.md b/docs/error-messages/compiler-errors-1/compiler-error-c2138.md index 77a93bb632b..3b597d22ad4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2138.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2138.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2138" title: "Compiler Error C2138" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2138" +ms.date: 11/04/2016 f1_keywords: ["C2138"] helpviewer_keywords: ["C2138"] -ms.assetid: 59fd1a58-3605-45dd-b9c1-0981e8aab26d --- # Compiler Error C2138 -illegal to define an enumeration without any members +> illegal to define an enumeration without any members + +## Remarks An enumeration must have at least one member when /Za (disable Microsoft extensions) is selected. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2139.md b/docs/error-messages/compiler-errors-1/compiler-error-c2139.md index e14f1709bf4..3f09eaac25a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2139.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2139.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Error C2139" title: "Compiler Error C2139" +description: "Learn more about: Compiler Error C2139" ms.date: 05/03/2021 f1_keywords: ["C2139"] helpviewer_keywords: ["C2139"] @@ -9,15 +9,15 @@ helpviewer_keywords: ["C2139"] > '*type*' : an undefined class is not allowed as an argument to compiler intrinsic type trait '*trait*' -An invalid argument was passed to a type trait. - ## Remarks +An invalid argument was passed to a type trait. + For more information, see [Compiler Support for Type Traits](../../extensions/compiler-support-for-type-traits-cpp-component-extensions.md). ## Example -The following sample generates C2139. +The following example generates C2139. ```cpp // C2139.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2140.md b/docs/error-messages/compiler-errors-1/compiler-error-c2140.md index 59c8c1212ff..5d5a0648071 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2140.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2140.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2140" title: "Compiler Error C2140" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2140" +ms.date: 11/04/2016 f1_keywords: ["C2140"] helpviewer_keywords: ["C2140"] -ms.assetid: d44a0500-002c-4632-9e5e-c71c3a473ec4 --- # Compiler Error C2140 -'type' : a type that is dependent on a generic type parameter is not allowed as an argument to compiler intrinsic type trait 'trait' +> 'type' : a type that is dependent on a generic type parameter is not allowed as an argument to compiler intrinsic type trait 'trait' + +## Remarks An invalid type specifier was passed to a type trait. @@ -16,7 +17,7 @@ For more information, see [Compiler Support for Type Traits](../../extensions/co ## Example -The following sample generates C2140. +The following example generates C2140. ```cpp // C2140.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2141.md b/docs/error-messages/compiler-errors-1/compiler-error-c2141.md index 056b2983499..18e160df28b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2141.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2141.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2141" title: "Compiler Error C2141" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2141" +ms.date: 11/04/2016 f1_keywords: ["C2141"] helpviewer_keywords: ["C2141"] -ms.assetid: 10cf770f-0500-4220-ac90-a863b7ea5fe6 --- # Compiler Error C2141 -array size overflow +> array size overflow + +## Remarks An array exceeds the 2GB limit. Reduce the size of the array. ## Example -The following sample generates C2141. +The following example generates C2141. ```cpp // C2141.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2142.md b/docs/error-messages/compiler-errors-1/compiler-error-c2142.md index 1920a389631..63c8eae9446 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2142.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2142.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2142" title: "Compiler Error C2142" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2142" +ms.date: 11/04/2016 f1_keywords: ["C2142"] helpviewer_keywords: ["C2142"] -ms.assetid: d0dbe10e-0952-49a4-8b33-e82fb7558b19 --- # Compiler Error C2142 -function declarations differ, variable parameters specified only in one of them +> function declarations differ, variable parameters specified only in one of them + +## Remarks One declaration of the function contains a variable parameter list. Another declaration does not. ANSI C ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) only. -The following sample generates C2142: +## Example + +The following example generates C2142: ```c // C2142.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2143.md b/docs/error-messages/compiler-errors-1/compiler-error-c2143.md index 66f9011fb60..244566a6131 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2143.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2143.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2143" title: "Compiler Error C2143" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2143" +ms.date: 11/04/2016 f1_keywords: ["C2143"] helpviewer_keywords: ["C2143"] -ms.assetid: 1d8d1456-e031-4965-9240-09a6e33ba81c --- # Compiler Error C2143 -syntax error : missing 'token1' before 'token2' +> syntax error : missing 'token1' before 'token2' + +## Remarks The compiler expected a specific token (that is, a language element other than white space) and found another token instead. @@ -16,6 +17,8 @@ Check the [C++ Language Reference](../../cpp/cpp-language-reference.md) to deter C2143 can occur in different situations. +## Examples + It can occur when an operator that can qualify a name (`::`, `->`, and `.`) must be followed by the keyword **`template`**, as in this example: ```cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2144.md b/docs/error-messages/compiler-errors-1/compiler-error-c2144.md index b421b7b1e78..c50ffbe8bfc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2144.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2144.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2144" title: "Compiler Error C2144" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2144" +ms.date: 11/04/2016 f1_keywords: ["C2144"] helpviewer_keywords: ["C2144"] -ms.assetid: 49f3959b-324f-4c06-9588-c0ecef5dc5b3 --- # Compiler Error C2144 > syntax error : '*type*' should be preceded by '*token*' +## Remarks + The compiler expected *token* and found *type* instead. This error may be caused by a missing closing brace, right parenthesis, or semicolon. @@ -20,7 +21,7 @@ You may also see C2144 if you are trying to do type forwarding. See [Type Forwar ## Examples -The following sample generates C2144, and shows a way to fix it: +The following example generates C2144, and shows a way to fix it: ```cpp // C2144.cpp @@ -33,7 +34,7 @@ REF struct MyStruct0; // C2144 REF1 MyStruct1; ``` -The following sample generates C2144, and shows a way to fix it: +The following example generates C2144, and shows a way to fix it: ```cpp // C2144_2.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2145.md b/docs/error-messages/compiler-errors-1/compiler-error-c2145.md index d38fac35d8b..3f0cb125a01 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2145.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2145.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2145" title: "Compiler Error C2145" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2145" +ms.date: 11/04/2016 f1_keywords: ["C2145"] helpviewer_keywords: ["C2145"] -ms.assetid: 158e5809-8adb-4195-8ca5-684501defbc8 --- # Compiler Error C2145 -syntax error : missing 'token' before identifier +> syntax error : missing 'token' before identifier + +## Remarks The compiler expected `token` and found identifier instead. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2146.md b/docs/error-messages/compiler-errors-1/compiler-error-c2146.md index 083cfd7db76..075f911dfac 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2146.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2146.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2146" title: "Compiler Error C2146" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2146" +ms.date: 11/04/2016 f1_keywords: ["C2146"] helpviewer_keywords: ["C2146"] -ms.assetid: 6bfb7de6-6723-4486-9350-c66ef88d7a64 --- # Compiler Error C2146 -syntax error : missing 'token' before identifier 'identifier' +> syntax error : missing 'token' before identifier 'identifier' + +## Remarks The compiler expected `token` and found `identifier` instead. Possible causes: @@ -20,7 +21,7 @@ This error may be caused by a typographical error. Error [C2065](../../error-mes ## Examples -The following sample generates C2146. +The following example generates C2146. ```cpp // C2146.cpp @@ -39,7 +40,7 @@ int main() { This error can also be generated as a result of compiler conformance work that was done for Visual Studio .NET 2003: missing **`typename`** keyword. -The following sample compiles in Visual Studio .NET 2002 but will fail in Visual Studio .NET 2003: +The following example compiles in Visual Studio .NET 2002 but will fail in Visual Studio .NET 2003: ```cpp // C2146b.cpp @@ -64,7 +65,7 @@ You will also see this error as a result of compiler conformance work that was d The use of `T` from the primary template is not allowed in the explicit specialization. For code to be valid in the Visual Studio .NET 2003 and Visual Studio .NET, replace all instances of the template parameter in the specialization with the explicitly specialized type. -The following sample compiles in Visual Studio .NET but will fail in Visual Studio .NET 2003: +The following example compiles in Visual Studio .NET but will fail in Visual Studio .NET 2003: ```cpp // C2146_c.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2147.md b/docs/error-messages/compiler-errors-1/compiler-error-c2147.md index 363bd1c2862..c282a1e2bdc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2147.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2147.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2147" title: "Compiler Error C2147" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2147" +ms.date: 11/04/2016 f1_keywords: ["C2147"] helpviewer_keywords: ["C2147"] -ms.assetid: d1adb3bf-7ece-4815-922c-ad7492fb6670 --- # Compiler Error C2147 -syntax error : 'identifier' is a new keyword +> syntax error : 'identifier' is a new keyword + +## Remarks An identifier was used that is now a reserved keyword in the language. -The following sample generates C2147: +## Example + +The following example generates C2147: ```cpp // C2147.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2148.md b/docs/error-messages/compiler-errors-1/compiler-error-c2148.md index f2a12bc67bb..6caab690512 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2148.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2148.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2148" title: "Compiler Error C2148" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2148" +ms.date: 11/04/2016 f1_keywords: ["C2148"] helpviewer_keywords: ["C2148"] -ms.assetid: e510c2c9-7b57-4ce8-be03-ba363e2cc5d9 --- # Compiler Error C2148 -total size of array must not exceed 0x7fffffff bytes +> total size of array must not exceed 0x7fffffff bytes + +## Remarks An array exceeds the limit. Reduce the size of the array. ## Example -The following sample generates C2148: +The following example generates C2148: ```cpp // C2148.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2149.md b/docs/error-messages/compiler-errors-1/compiler-error-c2149.md index 5eede2573b2..e6e64526d8d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2149.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2149.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2149" title: "Compiler Error C2149" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2149" +ms.date: 11/04/2016 f1_keywords: ["C2149"] helpviewer_keywords: ["C2149"] -ms.assetid: 7a106dab-d79f-41b9-85be-f36e86e4d2ab --- # Compiler Error C2149 -'identifier' : named bit field cannot have zero width +> 'identifier' : named bit field cannot have zero width + +## Remarks Bit fields can have zero width only if unnamed. -The following sample generates C2149: +## Example + +The following example generates C2149: ```cpp // C2149.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2150.md b/docs/error-messages/compiler-errors-1/compiler-error-c2150.md index 3fc67eca0f4..c1595ba5141 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2150.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2150.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2150" title: "Compiler Error C2150" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2150" +ms.date: 11/04/2016 f1_keywords: ["C2150"] helpviewer_keywords: ["C2150"] -ms.assetid: 21e82a10-c1d4-4c0d-9dc6-c5d92ea42a31 --- # Compiler Error C2150 > '*identifier*' : bit field must have type 'int', 'signed int', or 'unsigned int' +## Remarks + The base type for a bit-field is required to be **`int`**, **`signed int`**, or **`unsigned int`**. ## Example -This sample shows how you might encounter C2150, and how you can fix it: +This example shows how you might encounter C2150, and how you can fix it: ```cpp // C2150.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2151.md b/docs/error-messages/compiler-errors-1/compiler-error-c2151.md index 9fffa41bf1f..60f0f9ebea8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2151.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2151.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2151" title: "Compiler Error C2151" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2151" +ms.date: 11/04/2016 f1_keywords: ["C2151"] helpviewer_keywords: ["C2151"] -ms.assetid: 7f8dd83a-1f41-46d8-8778-0d1f79ed36c9 --- # Compiler Error C2151 -more than one language attribute +> more than one language attribute + +## Remarks A function has more than one keyword ( **`__cdecl`**, **`__stdcall`**, or **`__fastcall`**) specifying a calling convention. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2152.md b/docs/error-messages/compiler-errors-1/compiler-error-c2152.md index 40c3988ecfd..fa096f9730a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2152.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2152.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2152" title: "Compiler Error C2152" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2152" +ms.date: 11/04/2016 f1_keywords: ["C2152"] helpviewer_keywords: ["C2152"] -ms.assetid: a9ea2b0c-d55d-41c7-ba9f-dd75592ffc8a --- # Compiler Error C2152 -'identifier' : pointers to functions with different attributes +> 'identifier' : pointers to functions with different attributes + +## Remarks A pointer to a function with one calling convention (**`__cdecl`**, **`__stdcall`**, or **`__fastcall`**) is assigned to a pointer to a function with another calling convention. 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 893455edab7..8f34dce0ada 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,30 @@ --- -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 + +## Remarks -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: +## Example + +The following example 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-c2154.md b/docs/error-messages/compiler-errors-1/compiler-error-c2154.md index a60157128dc..38192df4ca8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2154.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2154.md @@ -1,15 +1,36 @@ --- -description: "Learn more about: Compiler Error C2154" title: "Compiler Error C2154" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2154" +ms.date: 09/21/2025 f1_keywords: ["C2154"] helpviewer_keywords: ["C2154"] -ms.assetid: 98d6b044-5a3a-43ad-95fa-9b916b22468a --- # Compiler Error C2154 -'type' : only enumeration type is allowed as an argument to compiler intrinsic type trait '__underlying_type' +> '*type*': only enumeration type is allowed as an argument to compiler intrinsic type trait '__underlying_type' + +## Remarks + +You can only get the underlying type of an [enumeration](../../cpp/enumerations-cpp.md) type. + +## Example + +The following example generates C2154: + +```cpp +// C2154.cpp +// compile with: /c + +struct S {}; +enum E {}; +enum class EC {}; + +__underlying_type(S) s; // C2154 +__underlying_type(int) i; // C2154 +__underlying_type(E) e; // OK +__underlying_type(EC) ec; // OK +``` -You can only get the underlying type of an enumeration type. +## See also -For more information, see [Compiler Support for Type Traits](../../extensions/compiler-support-for-type-traits-cpp-component-extensions.md). +[`underlying_type` class](../../standard-library/underlying-type-class.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2155.md b/docs/error-messages/compiler-errors-1/compiler-error-c2155.md index d65e37535c5..7dfb22df0d8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2155.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2155.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2155" title: "Compiler Error C2155" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2155" +ms.date: 11/04/2016 f1_keywords: ["C2155"] helpviewer_keywords: ["C2155"] -ms.assetid: 54d408af-fc48-4121-9011-5e75c7072e01 --- # Compiler Error C2155 -'?' : invalid left operand, expected arithmetic or pointer type +> '?' : invalid left operand, expected arithmetic or pointer type + +## Remarks An expression on the left hand side of `?` cannot be compared to zero. You must use an arithmetic or pointer expression that can be compared to zero. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2156.md b/docs/error-messages/compiler-errors-1/compiler-error-c2156.md index 3f26c7e32e0..8ba7b0a0ca2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2156.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2156.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2156" title: "Compiler Error C2156" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2156" +ms.date: 11/04/2016 f1_keywords: ["C2156"] helpviewer_keywords: ["C2156"] -ms.assetid: 136f9c67-2c27-4f61-b7e6-ccd202eca697 --- # Compiler Error C2156 -pragma must be outside function +> pragma must be outside function + +## Remarks A pragma that must be specified at a global level (outside a function body) is within a function. -The following sample generates C2156: +## Example + +The following example generates C2156: ```cpp // C2156.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2157.md b/docs/error-messages/compiler-errors-1/compiler-error-c2157.md index 5128e4a1b95..104d98276b1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2157.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2157.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2157" title: "Compiler Error C2157" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2157" +ms.date: 11/04/2016 f1_keywords: ["C2157"] helpviewer_keywords: ["C2157"] -ms.assetid: babbca24-16dc-4b69-be14-a675029249c1 --- # Compiler Error C2157 -'function' : must be declared before use in pragma list +> 'function' : must be declared before use in pragma list + +## Remarks The function name is not declared before being referenced in the list of functions for an [alloc_text](../../preprocessor/alloc-text.md) pragma. -The following sample generates C2157: +## Example + +The following example generates C2157: ```cpp // C2157.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2158.md b/docs/error-messages/compiler-errors-1/compiler-error-c2158.md index 9701f65a703..4372aa71568 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2158.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2158.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2158" title: "Compiler Error C2158" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2158" +ms.date: 11/04/2016 f1_keywords: ["C2158"] helpviewer_keywords: ["C2158"] -ms.assetid: 39028899-e95c-4809-8e65-6111118641ee --- # Compiler Error C2158 -'type' : #pragma make_public directive is currently supported for native non-template types only +> 'type' : #pragma make_public directive is currently supported for native non-template types only + +## Remarks The [make_public](../../preprocessor/make-public.md) pragma can only be applied to a native, non-template type. ## Example -The following sample generates C2158. +The following example generates C2158. ```cpp // C2158.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2159.md b/docs/error-messages/compiler-errors-1/compiler-error-c2159.md index 70073ebc69e..1463230715d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2159.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2159.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2159" title: "Compiler Error C2159" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2159" +ms.date: 11/04/2016 f1_keywords: ["C2159"] helpviewer_keywords: ["C2159"] -ms.assetid: 925a2cbd-43c9-45ee-a373-84004350b380 --- # Compiler Error C2159 -more than one storage class specified +> more than one storage class specified + +## Remarks A declaration contains more than one storage class. -The following sample generates C2159: +## Example + +The following example generates C2159: ```cpp // C2159.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2160.md b/docs/error-messages/compiler-errors-1/compiler-error-c2160.md index 6353f84bba8..1b9174fbe60 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2160.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2160.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2160" title: "Compiler Error C2160" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2160" +ms.date: 11/04/2016 f1_keywords: ["C2160"] helpviewer_keywords: ["C2160"] -ms.assetid: a1f694a7-fb16-4437-b7f5-a1af6da94bc5 --- # Compiler Error C2160 -'##' cannot occur at the beginning of a macro definition +> '##' cannot occur at the beginning of a macro definition + +## Remarks A macro definition began with a token-pasting operator (##). -The following sample generates C2160: +## Example + +The following example generates C2160: ```cpp // C2160.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2161.md b/docs/error-messages/compiler-errors-1/compiler-error-c2161.md index e552b85448f..cab1ce72319 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2161.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2161.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2161" title: "Compiler Error C2161" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2161" +ms.date: 11/04/2016 f1_keywords: ["C2161"] helpviewer_keywords: ["C2161"] -ms.assetid: d6798821-13bb-4e60-924f-85f7bf955387 --- # Compiler Error C2161 -'##' cannot occur at the end of a macro definition +> '##' cannot occur at the end of a macro definition + +## Remarks A macro definition ended with a token-pasting operator (##). -The following sample generates C2161: +## Example + +The following example generates C2161: ```cpp // C2161.cpp 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 9255eacdab9..eb2b08aa201 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,25 @@ --- -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. +## Remarks + +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-c2163.md b/docs/error-messages/compiler-errors-1/compiler-error-c2163.md index 8cf898cc43c..1fd73ce8bd0 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2163.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2163.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2163" title: "Compiler Error C2163" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2163" +ms.date: 11/04/2016 f1_keywords: ["C2163"] helpviewer_keywords: ["C2163"] -ms.assetid: 6428d1e9-1ba1-46fc-bbf6-91d6fef2734c --- # Compiler Error C2163 -'function' : not available as an intrinsic function +> 'function' : not available as an intrinsic function + +## Remarks An `intrinsic` or `function` pragma lists a function not available in intrinsic form. For example, certain intrinsics are not available when compiling a program that uses /clr programming. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2164.md b/docs/error-messages/compiler-errors-1/compiler-error-c2164.md index 0938243a688..5110e09126a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2164.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2164.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2164" title: "Compiler Error C2164" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2164" +ms.date: 11/04/2016 f1_keywords: ["C2164"] helpviewer_keywords: ["C2164"] -ms.assetid: 55df5024-68a8-45a8-ae6c-e6dba35318a2 --- # Compiler Error C2164 -'function' : intrinsic function not declared +> 'function' : intrinsic function not declared + +## Remarks An `intrinsic` pragma uses an undeclared function (only occurs with **/Oi**). Or, one of the compiler intrinsics was used without including its header file. -The following sample generates C2164: +## Example + +The following example generates C2164: ```c // C2164.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2165.md b/docs/error-messages/compiler-errors-1/compiler-error-c2165.md index 6cc12f0dcc2..c205d3531eb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2165.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2165.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2165" title: "Compiler Error C2165" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2165" +ms.date: 11/04/2016 f1_keywords: ["C2165"] helpviewer_keywords: ["C2165"] -ms.assetid: b108313b-b8cb-4dce-b2ec-f2b31c9cdc87 --- # Compiler Error C2165 -'keyword' : cannot modify pointers to data +> 'keyword' : cannot modify pointers to data + +## Remarks The **`__stdcall`**, **`__cdecl`**, or **`__fastcall`** keyword attempts to modify a pointer to data. -The following sample generates C2165: +## Example + +The following example generates C2165: ```cpp // C2165.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2166.md b/docs/error-messages/compiler-errors-1/compiler-error-c2166.md index a4df5a11666..82508f2bf90 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2166.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2166.md @@ -1,23 +1,26 @@ --- -description: "Learn more about: Compiler Error C2166" title: "Compiler Error C2166" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2166" +ms.date: 06/29/2025 f1_keywords: ["C2166"] helpviewer_keywords: ["C2166"] -ms.assetid: 12789c3a-cc76-48bb-ae2e-64283e0964ed --- # Compiler Error C2166 -l-value specifies const object +> l-value specifies const object + +## Remarks Code attempts to modify an item declared **`const`**. -The following sample generates C2166: +## Example + +The following example generates C2166: ```cpp // C2166.cpp -int f(); -int main() { - ( (const int&) 1 ) = 5; // C2166 +int main() +{ + ((const int&)1) = 5; // C2166 } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2167.md b/docs/error-messages/compiler-errors-1/compiler-error-c2167.md index 04cfdca5904..f893c4e0ff5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2167.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2167.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2167" title: "Compiler Error C2167" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2167" +ms.date: 11/04/2016 f1_keywords: ["C2167"] helpviewer_keywords: ["C2167"] -ms.assetid: 3de3de96-12cd-47df-b24e-34cc9747ef83 --- # Compiler Error C2167 -'function' : too many actual parameters for intrinsic function +> 'function' : too many actual parameters for intrinsic function + +## Remarks A reference to an `intrinsic` function has too many parameters. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2168.md b/docs/error-messages/compiler-errors-1/compiler-error-c2168.md index 26574e9a1be..e2fe0f0550c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2168.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2168.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2168" title: "Compiler Error C2168" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2168" +ms.date: 11/04/2016 f1_keywords: ["C2168"] helpviewer_keywords: ["C2168"] -ms.assetid: 625e7dc3-ca74-4980-8268-8d5c0245e376 --- # Compiler Error C2168 -'function' : too few actual parameters for intrinsic function +> 'function' : too few actual parameters for intrinsic function + +## Remarks A reference to an `intrinsic` function has too few parameters. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2169.md b/docs/error-messages/compiler-errors-1/compiler-error-c2169.md index a4e58165941..210ec567bc1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2169.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2169.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2169" title: "Compiler Error C2169" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2169" +ms.date: 11/04/2016 f1_keywords: ["C2169"] helpviewer_keywords: ["C2169"] -ms.assetid: 97f700bd-1044-46f5-b276-3d7570ee7708 --- # Compiler Error C2169 -'function' : intrinsic function, cannot be defined +> 'function' : intrinsic function, cannot be defined + +## Remarks A function definition appears for a function already declared `intrinsic`. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2170.md b/docs/error-messages/compiler-errors-1/compiler-error-c2170.md index 599a5750112..a3e73e406fa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2170.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2170.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2170" title: "Compiler Error C2170" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2170" +ms.date: 11/04/2016 f1_keywords: ["C2170"] helpviewer_keywords: ["C2170"] -ms.assetid: d5c663f0-2459-4e11-a8bf-a52b62f3c71d --- # Compiler Error C2170 -'identifier' : not declared as a function, cannot be intrinsic +> 'identifier' : not declared as a function, cannot be intrinsic ### To fix by checking the following possible causes diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2171.md b/docs/error-messages/compiler-errors-1/compiler-error-c2171.md index f32ebc62e2e..fb4d42de908 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2171.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2171.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2171" title: "Compiler Error C2171" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2171" +ms.date: 11/04/2016 f1_keywords: ["C2171"] helpviewer_keywords: ["C2171"] -ms.assetid: a80343b5-ab3f-4413-b6f1-3ce9d7e519e5 --- # Compiler Error C2171 -'operator' : illegal on operands of type 'type' +> 'operator' : illegal on operands of type 'type' + +## Remarks A unary operator is used with an invalid operand type. ## Examples -The following sample generates C2171. +The following example generates C2171. ```cpp // C2171.cpp @@ -28,7 +29,7 @@ int main() { } ``` -The following sample generates C2171. +The following example generates C2171. ```cpp // C2171_b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2172.md b/docs/error-messages/compiler-errors-1/compiler-error-c2172.md index 8e2992bd811..55e01b5bb3a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2172.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2172.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2172" title: "Compiler Error C2172" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2172" +ms.date: 11/04/2016 f1_keywords: ["C2172"] helpviewer_keywords: ["C2172"] -ms.assetid: 31183ea7-858d-4273-932a-d865af7059b1 --- # Compiler Error C2172 -'function' : actual parameter is not a pointer : parameter number +> 'function' : actual parameter is not a pointer : parameter number + +## Remarks Parameter `number` is not a pointer. The function expects a pointer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2173.md b/docs/error-messages/compiler-errors-1/compiler-error-c2173.md index 45dc2487855..fb92234298a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2173.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2173.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2173" title: "Compiler Error C2173" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2173" +ms.date: 11/04/2016 f1_keywords: ["C2173"] helpviewer_keywords: ["C2173"] -ms.assetid: 4df592b8-609b-41a5-b4fc-966eb5bb2d1a --- # Compiler Error C2173 -'function' : actual parameter is not a pointer : parameter number1, parameter list number2 +> 'function' : actual parameter is not a pointer : parameter number1, parameter list number2 + +## Remarks Parameter `number1` passed to parameter list `number2` is not a pointer. The function expects a pointer. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2174.md b/docs/error-messages/compiler-errors-1/compiler-error-c2174.md index bc685baa294..fe6702545fe 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2174.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2174.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2174" title: "Compiler Error C2174" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2174" +ms.date: 11/04/2016 f1_keywords: ["C2174"] helpviewer_keywords: ["C2174"] -ms.assetid: 161d563c-76e9-47e9-9142-7812e9ea169e --- # Compiler Error C2174 -'function' : actual parameter has type 'void' : parameter number1, parameter list number2 +> 'function' : actual parameter has type 'void' : parameter number1, parameter list number2 + +## Remarks Parameter `number1` passed to parameter list `number2` is a **`void`** parameter. Parameters cannot have type **`void`**. Use **`void*`** instead. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2175.md b/docs/error-messages/compiler-errors-1/compiler-error-c2175.md index 4f210813ce0..32d47e23c22 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2175.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2175.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2175" title: "Compiler Error C2175" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2175" +ms.date: 11/04/2016 f1_keywords: ["C2175"] helpviewer_keywords: ["C2175"] -ms.assetid: 3a8fa90b-2b29-414a-bb55-cf27c2bf989a --- # Compiler Error C2175 -'locale' : invalid locale +> 'locale' : invalid locale + +## Remarks The specified locale is not valid. See [Language and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md) in the *Run-Time Library Reference* for supported locales. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2177.md b/docs/error-messages/compiler-errors-1/compiler-error-c2177.md index a69d0bcd35b..e448186bf1a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2177.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2177.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2177" title: "Compiler Error C2177" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2177" +ms.date: 11/04/2016 f1_keywords: ["C2177"] helpviewer_keywords: ["C2177"] -ms.assetid: 2a39a880-cddb-4d3e-a572-645a14c4c478 --- # Compiler Error C2177 -constant too big +> constant too big + +## Remarks A constant value is too large for the variable type it is assigned. -The following sample generates C2177: +## Example + +The following example generates C2177: ```cpp // C2177.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2178.md b/docs/error-messages/compiler-errors-1/compiler-error-c2178.md index b9aecbda49c..4c93e6c79d6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2178.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2178.md @@ -1,32 +1,51 @@ --- -description: "Learn more about: Compiler Error C2178" title: "Compiler Error C2178" -ms.date: "05/08/2017" +description: "Learn more about: Compiler Error C2178" +ms.date: 08/11/2025 f1_keywords: ["C2178"] helpviewer_keywords: ["C2178"] -ms.assetid: 79a14158-17f3-4221-bd06-9d675c49cef4 --- # Compiler Error C2178 -'*identifier*' cannot be declared with '*specifier*' specifier +> '*identifier*' cannot be declared with '*specifier*' specifier + +## Remarks -A **`mutable`** specifier was used in a declaration, but the specifier is not allowed in this context. +A **`mutable`** specifier was used in a declaration, but the specifier is not allowed in this context. It can only be applied to non-static, non-const, and non-reference data members. For more information, see [Mutable Data Members](../../cpp/mutable-data-members-cpp.md). -The **`mutable`** specifier can be applied only to names of class data members, and cannot be applied to names declared **`const`** or **`static`**, and cannot be applied to reference members. +A **`consteval`** specifier was used on a [destructor](../../cpp/destructors-cpp.md), allocation function, or deallocation function. -## Example +## Example: `mutable` -The following sample shows how C2178 may occur, and how to fix it. +The following example shows how C2178 may occur with the **`mutable`** specifier, and how to resolve it: ```cpp -// C2178.cpp -// compile with: cl /c /W4 C2178.cpp +// C2178_mutable.cpp +// compile with: /c -class S { - mutable const int i; // C2178 - // To fix, declare either const or mutable, not both. +struct S +{ + mutable const int i; // C2178, remove mutable or const to resolve }; -mutable int x = 4; // C2178 -// To fix, remove mutable keyword +mutable int x = 4; // C2178, remove mutable to resolve +``` + +## Example: `consteval` + +The following example shows how C2178 may occur with the **`consteval`** specifier. To resolve this error, remove all **`consteval`** specifiers: + +```cpp +// C2178_consteval.cpp +// compile with: /c /std:c++20 + +#include + +struct S +{ + consteval ~S() {} // C2178 + + consteval static void* operator new(std::size_t size); // C2178 + consteval static void operator delete(void* ptr); // C2178 +}; ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2179.md b/docs/error-messages/compiler-errors-1/compiler-error-c2179.md index d1c9b3dc115..2f9baef3385 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2179.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2179.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2179" title: "Compiler Error C2179" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2179" +ms.date: 11/04/2016 f1_keywords: ["C2179"] helpviewer_keywords: ["C2179"] -ms.assetid: f929bfc6-3964-4e54-87d6-7529b9b6c0b9 --- # Compiler Error C2179 -'type' : an attribute argument cannot use type parameters +> 'type' : an attribute argument cannot use type parameters + +## Remarks A generic type parameter is resolved at runtime. However, an attribute parameter must be resolved at compile time. Therefore, you cannot use a generic type parameter as an argument to an attribute. ## Example -The following sample generates C2179. +The following example generates C2179. ```cpp // C2179.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2180.md b/docs/error-messages/compiler-errors-1/compiler-error-c2180.md index 30c5e6e220f..d9f8803ca2b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2180.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2180.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2180" title: "Compiler Error C2180" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2180" +ms.date: 11/04/2016 f1_keywords: ["C2180"] helpviewer_keywords: ["C2180"] -ms.assetid: ea71b39e-b977-48a7-b7bd-af68ef5e263b --- # Compiler Error C2180 -controlling expression has type 'type' +> controlling expression has type 'type' + +## Remarks The controlling expression in an **`if`**, **`while`**, **`for`**, or **`do`** statement is an expression cast to **`void`**. To fix this issue, change the controlling expression to one that produces a **`bool`** or a type that can be converted to **`bool`**. -The following sample generates C2180: +## Example + +The following example generates C2180: ```c // C2180.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2181.md b/docs/error-messages/compiler-errors-1/compiler-error-c2181.md index e3ca226ad79..be880ea0e88 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2181.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2181.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2181" title: "Compiler Error C2181" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2181" +ms.date: 11/04/2016 f1_keywords: ["C2181"] helpviewer_keywords: ["C2181"] -ms.assetid: d52b2fe4-566a-40a9-b8e2-8dce1f287668 --- # Compiler Error C2181 -illegal else without matching if +> illegal else without matching if + +## Remarks Each **`else`** must have a matching **`if`**. -The following sample generates C2181: +## Example + +The following example generates C2181: ```cpp // C2181.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2182.md b/docs/error-messages/compiler-errors-1/compiler-error-c2182.md index 6aef2bbc657..cbe5f56228d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2182.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2182.md @@ -1,25 +1,28 @@ --- -description: "Learn more about: Compiler Error C2182" title: "Compiler Error C2182" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2182" +ms.date: 08/22/2025 f1_keywords: ["C2182"] helpviewer_keywords: ["C2182"] -ms.assetid: dfd8d47d-9606-496e-bd96-4bf41ba1f857 --- # Compiler Error C2182 -'identifier' : illegal use of type 'void' +> '*identifier*': this use of 'void' is not valid + +## Remarks -A variable is declared type **`void`**. +You can't create a variable or array of type **`void`**. Only pointers to **`void`** are allowed. -The following sample generates C2182: +## Example + +The following example generates C2182: ```cpp // C2182.cpp // compile with: /c -int main() { - int i = 10; - void &ir = i; // C2182 cannot have a reference to type void - int &ir = i; // OK -} + +void var; // C2182 +void arr[5]; // C2182 + +void* ptr; // OK ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2183.md b/docs/error-messages/compiler-errors-1/compiler-error-c2183.md index 85d58a53721..95d0ed0a559 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2183.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2183.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2183" title: "Compiler Error C2183" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2183" +ms.date: 11/04/2016 f1_keywords: ["C2183"] helpviewer_keywords: ["C2183"] -ms.assetid: 03d2d010-a276-4ac3-820c-159abd8b1222 --- # Compiler Error C2183 -syntax error: translation unit is empty +> syntax error: translation unit is empty + +## Remarks Preprocessing produced an empty source file. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2184.md b/docs/error-messages/compiler-errors-1/compiler-error-c2184.md index 3d038496347..bee34695f9b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2184.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2184.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2184" title: "Compiler Error C2184" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2184" +ms.date: 11/04/2016 f1_keywords: ["C2184"] helpviewer_keywords: ["C2184"] -ms.assetid: 80fc8bff-7d76-4bde-94d2-01d84bb6824a --- # Compiler Error C2184 -'type' : illegal type for __except expression, must be an integral +> 'type' : illegal type for __except expression, must be an integral + +## Remarks A type was used in an [__except](../../c-language/try-except-statement-c.md) statement, but the type is not allowed. -The following sample generates C2184: +## Example + +The following example generates C2184: ```cpp // C2184.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2185.md b/docs/error-messages/compiler-errors-1/compiler-error-c2185.md index b6db0922903..0137134698f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2185.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2185.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2185" title: "Compiler Error C2185" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2185" +ms.date: 11/04/2016 f1_keywords: ["C2185"] helpviewer_keywords: ["C2185"] -ms.assetid: 74bc9f64-7b4c-4735-ba13-67c43f8c47db --- # Compiler Error C2185 -'identifier' : illegal based allocation +> 'identifier' : illegal based allocation + +## Remarks A register variable or automatic (local) variable is declared **`__based`**. Only global variables can be declared **`__based`**. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2186.md b/docs/error-messages/compiler-errors-1/compiler-error-c2186.md index 749be6dcbc4..e2ad100f3de 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2186.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2186.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2186" title: "Compiler Error C2186" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2186" +ms.date: 11/04/2016 f1_keywords: ["C2186"] helpviewer_keywords: ["C2186"] -ms.assetid: 284bfb7e-ab85-4fcb-9864-1ddf7f6c94ae --- # Compiler Error C2186 -'operator' : illegal operand of type 'void' +> 'operator' : illegal operand of type 'void' + +## Remarks The operator has a **`void`** operand. -The following sample generates C2186: +## Example + +The following example generates C2186: ```cpp // C2186.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2188.md b/docs/error-messages/compiler-errors-1/compiler-error-c2188.md index 74433b09195..e6bc3822cd9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2188.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2188.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2188" title: "Compiler Error C2188" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2188" +ms.date: 11/04/2016 f1_keywords: ["C2188"] helpviewer_keywords: ["C2188"] -ms.assetid: 2223147f-e487-4090-acdf-75ba4e1114f6 --- # Compiler Error C2188 -'number' : too big for wide character +> 'number' : too big for wide character + +## Remarks The number exceeds the size limit for the wide-character type. Choose a larger type. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2190.md b/docs/error-messages/compiler-errors-1/compiler-error-c2190.md index a1a2c41a07e..8c9adb4ad4c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2190.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2190.md @@ -1,23 +1,32 @@ --- -description: "Learn more about: Compiler Error C2190" title: "Compiler Error C2190" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2190" +ms.date: 08/22/2025 f1_keywords: ["C2190"] helpviewer_keywords: ["C2190"] -ms.assetid: 34e15f85-d979-4948-80fc-46c414508a70 --- # Compiler Error C2190 -first parameter list longer than second +> first parameter list longer than second + +## Remarks + +A C function was declared a second time with a shorter parameter list. C does not support overloaded functions. Without [`/Za`](../../build/reference/za-ze-disable-language-extensions.md), the compiler emits [Compiler Warning (level 1) C4030](../compiler-warnings/compiler-warning-level-1-c4030.md) instead. -A C function was declared a second time with a shorter parameter list. C does not support overloaded functions. +## Example -The following sample generates C2190: +The following example generates C2190: ```c // C2190.c // compile with: /Za /c -void func( int, float ); -void func( int ); // C2190, different parameter list -void func2( int ); // OK + +void func1(int, float); +void func1(int); // C2190, shorter parameter list + +void func2(int); // OK ``` + +## See also + +[Compiler Error C2191](compiler-error-c2191.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2191.md b/docs/error-messages/compiler-errors-1/compiler-error-c2191.md index d55e9b6fc77..9644cee4889 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2191.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2191.md @@ -1,25 +1,32 @@ --- -description: "Learn more about: Compiler Error C2191" title: "Compiler Error C2191" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2191" +ms.date: 08/22/2025 f1_keywords: ["C2191"] helpviewer_keywords: ["C2191"] -ms.assetid: 051b8350-e5de-4f51-ab6e-96d32366bcef --- # Compiler Error C2191 -second parameter list longer than first +> second parameter list longer than first -A C function was declared a second time with a longer parameter list. C does not support overloaded functions. +## Remarks + +A C function was declared a second time with a longer parameter list. C does not support overloaded functions. Without [`/Za`](../../build/reference/za-ze-disable-language-extensions.md), the compiler emits [Compiler Warning (level 1) C4031](../compiler-warnings/compiler-warning-level-1-c4031.md) instead. ## Example -The following sample generates C2191: +The following example generates C2191: ```c // C2191.c // compile with: /Za /c -void func( int ); -void func( int, float ); // C2191 different parameter list -void func2( int, float ); // OK + +void func1(int); +void func1(int, float); // C2191, longer parameter list + +void func2(int, float); // OK ``` + +## See also + +[Compiler Error C2190](compiler-error-c2190.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2192.md b/docs/error-messages/compiler-errors-1/compiler-error-c2192.md index 3444f6a2d61..99ad0f1f3cd 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2192.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2192.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2192" title: "Compiler Error C2192" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2192" +ms.date: 11/04/2016 f1_keywords: ["C2192"] helpviewer_keywords: ["C2192"] -ms.assetid: a147197e-e72d-4620-939b-f9e08d7c7c12 --- # Compiler Error C2192 -parameter 'number' declaration different +> parameter 'number' declaration different + +## Remarks A C function was declared a second time with a different parameter list. C does not support overloaded functions. -The following sample generates C2192: +## Example + +The following example generates C2192: ```c // C2192.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2193.md b/docs/error-messages/compiler-errors-1/compiler-error-c2193.md index 8175641f502..3ccc804d025 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2193.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2193.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2193" title: "Compiler Error C2193" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2193" +ms.date: 11/04/2016 f1_keywords: ["C2193"] helpviewer_keywords: ["C2193"] -ms.assetid: 9813e853-d581-4f51-bb75-4e242298a844 --- # Compiler Error C2193 -'identifier' : already in a segment +> 'identifier' : already in a segment + +## Remarks A function was placed in two different segments using `alloc_text` and `code_seg` pragmas. -The following sample generates C2193: +## Example + +The following example generates C2193: ```cpp // C2193.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2194.md b/docs/error-messages/compiler-errors-1/compiler-error-c2194.md index 97e108884eb..371a93bf9f7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2194.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2194.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2194" title: "Compiler Error C2194" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2194" +ms.date: 11/04/2016 f1_keywords: ["C2194"] helpviewer_keywords: ["C2194"] -ms.assetid: df6e631c-0062-4844-9088-4cc7a0ff879f --- # Compiler Error C2194 -'identifier' : is a text segment +> 'identifier' : is a text segment + +## Remarks The `data_seg` pragma uses a segment name used with `code_seg`. -The following sample generates C2194: +## Example + +The following example generates C2194: ```cpp // C2194.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2195.md b/docs/error-messages/compiler-errors-1/compiler-error-c2195.md index 34f1655447b..04352aa63fa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2195.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2195.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2195" title: "Compiler Error C2195" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2195" +ms.date: 11/04/2016 f1_keywords: ["C2195"] helpviewer_keywords: ["C2195"] -ms.assetid: 9f9f035c-9c51-4173-a8ea-c6f907fc5c63 --- # Compiler Error C2195 -'identifier' : is a data segment +> 'identifier' : is a data segment + +## Remarks The `code_seg` pragma uses a segment name used with the `data_seg` pragma. -The following sample generates C2195: +## Example + +The following example generates C2195: ```cpp // C2195.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2196.md b/docs/error-messages/compiler-errors-1/compiler-error-c2196.md index e3e854bae89..d36f92c67ec 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2196.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2196.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2196" title: "Compiler Error C2196" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2196" +ms.date: 11/04/2016 f1_keywords: ["C2196"] helpviewer_keywords: ["C2196"] -ms.assetid: fd2f6a58-48ce-4e58-96f8-e37720feb8e7 --- # Compiler Error C2196 -case value 'value' already used. +> case value 'value' already used. + +## Remarks A switch statement uses the same case value more than once. -The following sample generates C2196: +## Example + +The following example generates C2196: ```cpp // C2196.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2197.md b/docs/error-messages/compiler-errors-1/compiler-error-c2197.md index d59180593bc..ea6795bcdd4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2197.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2197.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2197" title: "Compiler Error C2197" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2197" +ms.date: 11/04/2016 f1_keywords: ["C2197"] helpviewer_keywords: ["C2197"] -ms.assetid: 6dd5a6ec-bc80-41b9-a4ac-46f80eaca42d --- # Compiler Error C2197 -'function' : too many arguments for call +> 'function' : too many arguments for call + +## Remarks The compiler detected too many parameters for a call to the function, or an incorrect function declaration. -The following sample generates C2197: +## Example + +The following example generates C2197: ```c // C2197.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2198.md b/docs/error-messages/compiler-errors-1/compiler-error-c2198.md index 56e12832c9b..e200cd44285 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2198.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2198.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2198" title: "Compiler Error C2198" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2198" +ms.date: 11/04/2016 f1_keywords: ["C2198"] helpviewer_keywords: ["C2198"] -ms.assetid: 638a845c-9d7f-4115-a9aa-d72455605668 --- # Compiler Error C2198 -'function' : too few arguments for call +> 'function' : too few arguments for call + +## Remarks The compiler found too few parameters for a call to the function, or an incorrect function declaration. -The following sample generates C2198: +## Example + +The following example generates C2198: ```c // C2198.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2199.md b/docs/error-messages/compiler-errors-1/compiler-error-c2199.md index 74067b233cc..91384b33bda 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2199.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2199.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2199" title: "Compiler Error C2199" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2199" +ms.date: 11/04/2016 f1_keywords: ["C2199"] helpviewer_keywords: ["C2199"] -ms.assetid: 6a92a1b7-7906-49e6-a31f-e8bffbc7706a --- # Compiler Error C2199 -syntax error : found 'identifier (' at global scope (was a declaration intended?) +> syntax error : found 'identifier (' at global scope (was a declaration intended?) + +## Remarks The specified context caused a syntax error. There may be incorrect declaration syntax. -The following sample generates C2199: +## Example + +The following example generates C2199: ```cpp // C2199.cpp 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 bc39dfceb86..5ef2473a21f 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,25 @@ --- -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 + +## Remarks + +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. + +## Example + +The following example 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-c2201.md b/docs/error-messages/compiler-errors-1/compiler-error-c2201.md index aa9d5356317..4be33f800de 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2201.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2201.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Error C2201" title: "Compiler Error C2201" +description: "Learn more about: Compiler Error C2201" ms.date: 05/03/2021 f1_keywords: ["C2201"] helpviewer_keywords: ["C2201"] @@ -9,11 +9,13 @@ helpviewer_keywords: ["C2201"] > '*identifier*' : must have external linkage in order to be exported/imported +## Remarks + The exported identifier is **`static`**. ## Example -The following sample generates C2286, and shows how to fix it: +The following example generates C2201, and shows how to fix it: ```cpp // C2201.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2203.md b/docs/error-messages/compiler-errors-1/compiler-error-c2203.md index 6171c53c18a..1850f52d271 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2203.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2203.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2203" title: "Compiler Error C2203" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2203" +ms.date: 11/04/2016 f1_keywords: ["C2203"] helpviewer_keywords: ["C2203"] -ms.assetid: 5497df43-86f6-43d5-b6cb-723c4c589b10 --- # Compiler Error C2203 -delete operator cannot specify bounds for an array +> delete operator cannot specify bounds for an array + +## Remarks With the **/Za** (ANSI) option, the **`delete`** operator can delete an entire array but not parts or specific members of the array. -The following sample generates C2203: +## Example + +The following example generates C2203: ```cpp // C2203.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2204.md b/docs/error-messages/compiler-errors-1/compiler-error-c2204.md index 001aefd823c..b09f6a116a9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2204.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2204.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2204" title: "Compiler Error C2204" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2204" +ms.date: 11/04/2016 f1_keywords: ["C2204"] helpviewer_keywords: ["C2204"] -ms.assetid: bbe506d4-7863-44af-8709-161881c4b4ba --- # Compiler Error C2204 -'type' : type definition found within parentheses +> 'type' : type definition found within parentheses + +## Remarks The type is defined as an operand or in prototype scope. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2205.md b/docs/error-messages/compiler-errors-1/compiler-error-c2205.md index 933e5828067..6b073e8cc7c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2205.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2205.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2205" title: "Compiler Error C2205" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2205" +ms.date: 11/04/2016 f1_keywords: ["C2205"] helpviewer_keywords: ["C2205"] -ms.assetid: bfc19840-4a48-4da5-8e69-7069989f1d2c --- # Compiler Error C2205 -'identifier' : cannot initialize extern variables with block scope +> 'identifier' : cannot initialize extern variables with block scope + +## Remarks An **`extern`** variable cannot be initialized in a function. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2206.md b/docs/error-messages/compiler-errors-1/compiler-error-c2206.md index ecc111e042f..611865407d5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2206.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2206.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2206" title: "Compiler Error C2206" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2206" +ms.date: 11/04/2016 f1_keywords: ["C2206"] helpviewer_keywords: ["C2206"] -ms.assetid: d7fba68b-aa28-4885-a9a0-27107358f066 --- # Compiler Error C2206 -'function' : typedef cannot be used for function definition +> 'function' : typedef cannot be used for function definition + +## Remarks A **`typedef`** is used to define a function type. -The following sample generates C2206: +## Example + +The following example generates C2206: ```cpp // C2206.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2207.md b/docs/error-messages/compiler-errors-1/compiler-error-c2207.md index 1f1fffd0dd9..fab75ec1e1e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2207.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2207.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2207" title: "Compiler Error C2207" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2207" +ms.date: 11/04/2016 f1_keywords: ["C2207"] helpviewer_keywords: ["C2207"] -ms.assetid: d7d7b537-68f1-420a-9835-b5b6f2cb5cfd --- # Compiler Error C2207 -'member': a member of a class template cannot acquire a function type +> 'member': a member of a class template cannot acquire a function type + +## Remarks The `member` of the class template was previously parsed as a non-static data member. It cannot be redefined as a member function. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2208.md b/docs/error-messages/compiler-errors-1/compiler-error-c2208.md index b191a057341..6c3ca308787 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2208.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2208.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2208" title: "Compiler Error C2208" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2208" +ms.date: 11/04/2016 f1_keywords: ["C2208"] helpviewer_keywords: ["C2208"] -ms.assetid: 9ae704bc-bf70-45f1-8e47-0470f21edd4e --- # Compiler Error C2208 -'type' : no members defined using this type +> 'type' : no members defined using this type + +## Remarks An identifier resolving to a type name is in an aggregate declaration, but the compiler cannot declare a member. -The following sample generates C2208: +## Example + +The following example generates C2208: ```cpp // C2208.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2212.md b/docs/error-messages/compiler-errors-1/compiler-error-c2212.md index db3551919f0..16a9f9f198b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2212.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2212.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2212" title: "Compiler Error C2212" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2212" +ms.date: 11/04/2016 f1_keywords: ["C2212"] helpviewer_keywords: ["C2212"] -ms.assetid: 3fdab304-272c-4d07-bfd4-fad75170e536 --- # Compiler Error C2212 -'identifier' : __based not available for pointers to functions +> 'identifier' : __based not available for pointers to functions + +## Remarks Pointers to functions cannot be declared **`__based`**. If you need code-based data, use the **`__declspec`** keyword or the `data_seg` pragma. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2213.md b/docs/error-messages/compiler-errors-1/compiler-error-c2213.md index ef1d970869d..667f53b64db 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2213.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2213.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2213" title: "Compiler Error C2213" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2213" +ms.date: 11/04/2016 f1_keywords: ["C2213"] helpviewer_keywords: ["C2213"] -ms.assetid: ff012278-7f3b-4d49-aaed-2349756f6225 --- # Compiler Error C2213 -'modifier' : illegal argument to __based +> 'modifier' : illegal argument to __based + +## Remarks The argument modifying **`__based`** is invalid. -The following sample generates C2213: +## Example + +The following example generates C2213: ```cpp // C2213.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2216.md b/docs/error-messages/compiler-errors-1/compiler-error-c2216.md index 51d2a53818b..5d0d49c0e9e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2216.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2216.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2216" title: "Compiler Error C2216" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2216" +ms.date: 11/04/2016 f1_keywords: ["C2216"] helpviewer_keywords: ["C2216"] -ms.assetid: 250f6bdc-a5e1-495f-a1e8-6e8e7021ad9d --- # Compiler Error C2216 -'keyword1' cannot be used with ' keyword2' +> 'keyword1' cannot be used with ' keyword2' + +## Remarks Two keywords that are mutually exclusive were used together. ## Examples -The following sample generates C2216. +The following example generates C2216. ```cpp // C2216.cpp @@ -25,7 +26,7 @@ ref struct Y1 { }; ``` -The following sample generates C2216. +The following example generates C2216. ```cpp // C2216b.cpp @@ -36,7 +37,7 @@ public ref class X { }; ``` -The following sample generates C2216. +The following example generates C2216. ```cpp // C2216c.cpp 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 bbe71cce5aa..b13e45b5eec 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2217.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2217.md @@ -1,26 +1,21 @@ --- -description: "Learn more about: Compiler Error C2217" title: "Compiler Error C2217" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2217" +ms.date: 11/04/2016 f1_keywords: ["C2217"] helpviewer_keywords: ["C2217"] -ms.assetid: 1ce1e3f5-4171-4376-804d-967f7e612935 --- # Compiler Error C2217 -'attribute1' requires 'attribute2' - -The first function attribute requires the second attribute. - -### To fix by checking the following possible causes +> 'attribute1' requires 'attribute2' -1. Interrupt (`__interrupt`) function declared as `near`. Interrupt functions must be `far`. +## Remarks -1. Interrupt function declared with **`__stdcall`**, or **`__fastcall`**. Interrupt functions must use C calling conventions. +The first function attribute requires the second attribute. ## 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 example generates C2217. ```cpp // C2217.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2218.md b/docs/error-messages/compiler-errors-1/compiler-error-c2218.md index a5f96212403..07e17522d3b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2218.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2218.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2218" title: "Compiler Error C2218" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2218" +ms.date: 11/04/2016 f1_keywords: ["C2218"] helpviewer_keywords: ["C2218"] -ms.assetid: b0f55da4-8edb-4b45-b298-1a091981bd7b --- # Compiler Error C2218 > '__vectorcall' cannot be used with '/arch:IA32' +## Remarks + The **`__vectorcall`** calling convention is only supported in native code on x86 and x64 processors that include Streaming SIMD Extensions 2 (SSE2) and above. For more information, see [`__vectorcall`](../../cpp/vectorcall.md). To fix this error, change the compiler options to target SSE2, AVX or AVX2 instruction sets. For more information, see [`/arch` (x86)](../../build/reference/arch-x86.md). diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2219.md b/docs/error-messages/compiler-errors-1/compiler-error-c2219.md index eb2fc27f7dd..499519f546c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2219.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2219.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2219" title: "Compiler Error C2219" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2219" +ms.date: 11/04/2016 f1_keywords: ["C2219"] helpviewer_keywords: ["C2219"] -ms.assetid: 2cfe9a75-6890-46a1-a127-79a7def78e94 --- # Compiler Error C2219 -syntax error : type qualifier must be after '*' +> syntax error : type qualifier must be after '*' + +## Remarks Type qualifier (**`const`** or **`volatile`**) appears where it is not permitted. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2220.md b/docs/error-messages/compiler-errors-1/compiler-error-c2220.md index edfa71f27b2..0660cff0df4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2220.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2220.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2220" title: "Compiler Error C2220" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2220" +ms.date: 11/04/2016 f1_keywords: ["C2220"] helpviewer_keywords: ["C2220"] -ms.assetid: d610802c-64d7-40ad-a2a6-0ed0b6815a6c --- # Compiler Error C2220 -warning treated as error - no object file generated +> warning treated as error - no object file generated + +## Remarks [/WX](../../build/reference/compiler-option-warning-level.md) tells the compiler to treat all warnings as errors. Because an error occurred, no object or executable file was generated. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2222.md b/docs/error-messages/compiler-errors-1/compiler-error-c2222.md index 7d2bc23ae53..894171131f6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2222.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2222.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2222" title: "Compiler Error C2222" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2222" +ms.date: 11/04/2016 f1_keywords: ["C2222"] helpviewer_keywords: ["C2222"] -ms.assetid: 1c902054-5c77-41e6-a1cc-018f802460cd --- # Compiler Error C2222 -unexpected type 'type': a base-class or member was expected +> unexpected type 'type': a base-class or member was expected + +## Remarks The initializer list can only initialize base classes or members of a type. To fix this error, verify that only base classes or members of the type are initialized in the initializer list. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2223.md b/docs/error-messages/compiler-errors-1/compiler-error-c2223.md index cc9b7306391..4607f1838a6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2223.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2223.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2223" title: "Compiler Error C2223" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2223" +ms.date: 11/04/2016 f1_keywords: ["C2223"] helpviewer_keywords: ["C2223"] -ms.assetid: e4506f0f-0317-4a96-8a90-877a156d7939 --- # Compiler Error C2223 -left of '->identifier' must point to struct/union +> left of '->identifier' must point to struct/union + +## Remarks The operand to the left of `->` is not a pointer to a class, structure, or union. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2224.md b/docs/error-messages/compiler-errors-1/compiler-error-c2224.md index 7bd87633ef8..7d13d46a0e9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2224.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2224.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2224" title: "Compiler Error C2224" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2224" +ms.date: 11/04/2016 f1_keywords: ["C2224"] helpviewer_keywords: ["C2224"] -ms.assetid: 27b93bbf-4ce7-47a3-a9c4-f4fbed689bdf --- # Compiler Error C2224 -left of '.identifier' must have struct/union type +> left of '.identifier' must have struct/union type + +## Remarks The operand to the left of the period (.) is not a class, structure, or union. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2226.md b/docs/error-messages/compiler-errors-1/compiler-error-c2226.md index 5ad3e477754..7576eab5fea 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2226.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2226.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2226" title: "Compiler Error C2226" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2226" +ms.date: 11/04/2016 f1_keywords: ["C2226"] helpviewer_keywords: ["C2226"] -ms.assetid: b3aaa2a5-254a-46a9-a508-de2371ecffeb --- # Compiler Error C2226 -syntax error : unexpected type 'type' +> syntax error : unexpected type 'type' + +## Remarks A syntax error occurs before or in the type specifier. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2227.md b/docs/error-messages/compiler-errors-1/compiler-error-c2227.md index 15613f96e17..4c84efc13a6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2227.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2227.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2227" title: "Compiler Error C2227" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2227" +ms.date: 11/04/2016 f1_keywords: ["C2227"] helpviewer_keywords: ["C2227"] -ms.assetid: d470e8b8-7e15-468b-84fa-37d1a0132271 --- # Compiler Error C2227 -left of '->member' must point to class/struct/union/generic type +> left of '->member' must point to class/struct/union/generic type + +## Remarks The operand to the left of `->` is not a pointer to a class, structure, or union. -The following sample generates C2227: +## Example + +The following example generates C2227: ```cpp // C2227.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2228.md b/docs/error-messages/compiler-errors-1/compiler-error-c2228.md index d8cc1b4db97..f0605e69fc8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2228.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2228.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2228" title: "Compiler Error C2228" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2228" +ms.date: 11/04/2016 f1_keywords: ["C2228"] helpviewer_keywords: ["C2228"] -ms.assetid: 901cadb1-ce90-4ae0-a360-547a9ba2ca18 --- # Compiler Error C2228 -left of '.identifier' must have class/struct/union +> left of '.identifier' must have class/struct/union + +## Remarks The operand to the left of the period (.) is not a class, structure, or union. -The following sample generates C2228: +## Example + +The following example generates C2228: ```cpp // C2228.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2229.md b/docs/error-messages/compiler-errors-1/compiler-error-c2229.md index 24ce025b2cd..a77432e3f15 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2229.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2229.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2229" title: "Compiler Error C2229" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2229" +ms.date: 11/04/2016 f1_keywords: ["C2229"] helpviewer_keywords: ["C2229"] -ms.assetid: 933c7cf2-a463-4e74-b0b4-59dedad987fb --- # Compiler Error C2229 -type 'identifier' has an illegal zero-sized array +> type 'identifier' has an illegal zero-sized array + +## Remarks A member of a structure or bit field contains a zero-sized array that is not the last member. @@ -16,7 +17,9 @@ Because you can have a zero sized array as the last member of the struct, you mu If the zero sized array is not the last member of the struct, the compiler can't calculate the offset for the remaining fields. -The following sample generates C2229: +## Example + +The following example generates C2229: ```cpp // C2229.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2231.md b/docs/error-messages/compiler-errors-1/compiler-error-c2231.md index 6f95cb15e9f..a3ab0edc007 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2231.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2231.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2231" title: "Compiler Error C2231" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2231" +ms.date: 11/04/2016 f1_keywords: ["C2231"] helpviewer_keywords: ["C2231"] -ms.assetid: 677c5c66-d30f-4c3b-bbb9-760858d56477 --- # Compiler Error C2231 -'.' : left operand points to 'class-key', use '->' +> '.' : left operand points to 'class-key', use '->' + +## Remarks The operand to the left of the member-selection operation (.) is a pointer instead of a class, structure, or union. -The following sample generates C2231: +## Example + +The following example generates C2231: ```c // C2231.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2232.md b/docs/error-messages/compiler-errors-1/compiler-error-c2232.md index 46af61cbe1f..58ab4d67d20 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2232.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2232.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2232" title: "Compiler Error C2232" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2232" +ms.date: 11/04/2016 f1_keywords: ["C2232"] helpviewer_keywords: ["C2232"] -ms.assetid: 76f302b7-30a7-4a81-9a39-b4edde33b54c --- # Compiler Error C2232 -'->' : left operand has 'class-key' type, use '.' +> '->' : left operand has 'class-key' type, use '.' + +## Remarks The operand to the left of the `->` operator is not a pointer. Use the period (.) operator for a class, structure, or union. -The following sample generates C2232: +## Example + +The following example generates C2232: ```c // C2232.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2233.md b/docs/error-messages/compiler-errors-1/compiler-error-c2233.md index cb1b6646bc1..941d8ee870c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2233.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2233.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2233" title: "Compiler Error C2233" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2233" +ms.date: 11/04/2016 f1_keywords: ["C2233"] helpviewer_keywords: ["C2233"] -ms.assetid: 236bdf0b-9607-4f26-a249-d8def0b1333c --- # Compiler Error C2233 -'identifier' : arrays of objects containing zero-size arrays are illegal +> 'identifier' : arrays of objects containing zero-size arrays are illegal + +## Remarks Each object in an array must contain at least one element. -The following sample generates C2233: +## Example + +The following example generates C2233: ```cpp // C2233.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2234.md b/docs/error-messages/compiler-errors-1/compiler-error-c2234.md index 2b08baaddf2..df26be2eea1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2234.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2234.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2234" title: "Compiler Error C2234" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2234" +ms.date: 11/04/2016 f1_keywords: ["C2234"] helpviewer_keywords: ["C2234"] -ms.assetid: cfa42458-c803-4717-a017-9eca1c0cbfb0 --- # Compiler Error C2234 -'name' : arrays of references are illegal +> 'name' : arrays of references are illegal + +## Remarks Because pointers to references are not allowed, arrays of references are not possible. -The following sample generates C2234: +## Example + +The following example generates C2234: ```cpp // C2234.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2236.md b/docs/error-messages/compiler-errors-1/compiler-error-c2236.md index fee5e16f054..4fc2c582fb4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2236.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2236.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2236" title: "Compiler Error C2236" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2236" +ms.date: 11/04/2016 f1_keywords: ["C2236"] helpviewer_keywords: ["C2236"] -ms.assetid: 0b6771a7-a783-4729-9c3d-7a3339c432cc --- # Compiler Error C2236 -unexpected token 'identifier'. Did you forget a ';'? +> unexpected token 'identifier'. Did you forget a ';'? + +## Remarks The identifier is already defined as a type and cannot be overridden by a user-defined type. -The following sample generates C2236: +## Example + +The following example generates C2236: ```cpp // C2236.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2238.md b/docs/error-messages/compiler-errors-1/compiler-error-c2238.md index 26743ab065b..36610cb8a82 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2238.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2238.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2238" title: "Compiler Error C2238" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2238" +ms.date: 11/04/2016 f1_keywords: ["C2238"] helpviewer_keywords: ["C2238"] -ms.assetid: 3d53060c-d6b7-4603-b9cf-d7c65eb64cd2 --- # Compiler Error C2238 -unexpected token(s) preceding 'token' +> unexpected token(s) preceding 'token' + +## Remarks An incorrect token was found. -The following sample generates C2238: +## Example + +The following example generates C2238: ```cpp // C2238.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2241.md b/docs/error-messages/compiler-errors-1/compiler-error-c2241.md index f1793fd8d9b..1b3217d46fa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2241.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2241.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2241" title: "Compiler Error C2241" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2241" +ms.date: 11/04/2016 f1_keywords: ["C2241"] helpviewer_keywords: ["C2241"] -ms.assetid: 2f4e2c2c-b95c-4afe-bbe0-4214cd39d140 --- # Compiler Error C2241 -'identifier' : member access is restricted +> 'identifier' : member access is restricted + +## Remarks Code attempts to access a private or protected member. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2242.md b/docs/error-messages/compiler-errors-1/compiler-error-c2242.md index ccf78a2612b..d7401ce7584 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2242.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2242.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2242" title: "Compiler Error C2242" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2242" +ms.date: 11/04/2016 f1_keywords: ["C2242"] helpviewer_keywords: ["C2242"] -ms.assetid: e1b687ed-4460-4c26-9f7e-c43e65c6dd65 --- # Compiler Error C2242 -typedef name cannot follow class/struct/union +> typedef name cannot follow class/struct/union + +## Remarks A **`typedef`** name appears at the end of a qualified name. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2243.md b/docs/error-messages/compiler-errors-1/compiler-error-c2243.md index e12e7174e74..036a1ae997d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2243.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2243.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2243" title: "Compiler Error C2243" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2243" +ms.date: 11/04/2016 f1_keywords: ["C2243"] helpviewer_keywords: ["C2243"] -ms.assetid: b90065bb-d251-4ba9-8b4c-280ee13fa9c0 --- # Compiler Error C2243 -'conversion type' conversion from 'type1' to 'type2' exists, but is inaccessible +> 'conversion type' conversion from 'type1' to 'type2' exists, but is inaccessible + +## Remarks Access protection (**`protected`** or **`private`**) prevented conversion from a pointer to a derived class to a pointer to the base class. -The following sample generates C2243: +## Example + +The following example generates C2243: ```cpp // C2243.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2244.md b/docs/error-messages/compiler-errors-1/compiler-error-c2244.md index eed68eeec0e..d0ae19f3282 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2244.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2244.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2244" title: "Compiler Error C2244" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2244" +ms.date: 11/04/2016 f1_keywords: ["C2244"] helpviewer_keywords: ["C2244"] -ms.assetid: d9911c12-ceb5-4f93-ac47-b44a485215c2 --- # Compiler Error C2244 -'identifier' : unable to match function definition to an existing declaration +> 'identifier' : unable to match function definition to an existing declaration + +## Remarks An unusual use of the unary + operator was used in front of a function call that did not have parenthesis. This error only occurs in C++ projects. -The following sample generates C2244: +## Examples + +The following example generates C2244: ```cpp // C2244.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2245.md b/docs/error-messages/compiler-errors-1/compiler-error-c2245.md index cf96d1724c4..585fe22556b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2245.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2245.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2245" title: "Compiler Error C2245" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2245" +ms.date: 11/04/2016 f1_keywords: ["C2245"] helpviewer_keywords: ["C2245"] -ms.assetid: 08aaeadf-10ec-485a-b2a6-6e775289082b --- # Compiler Error C2245 -non-existent member function 'function' specified as friend (member function signature does not match any overload) +> non-existent member function 'function' specified as friend (member function signature does not match any overload) + +## Remarks A function specified as a friend was not found by the compiler. -The following sample generates C2245: +## Example + +The following example generates C2245: ```cpp // C2245.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2246.md b/docs/error-messages/compiler-errors-1/compiler-error-c2246.md index c2ebd50d80a..4055d44c346 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2246.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2246.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2246" title: "Compiler Error C2246" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2246" +ms.date: 11/04/2016 f1_keywords: ["C2246"] helpviewer_keywords: ["C2246"] -ms.assetid: 4f3e4f83-21f3-4256-af96-43e0bb060311 --- # Compiler Error C2246 -'identifier' : illegal static data member in locally defined class +> 'identifier' : illegal static data member in locally defined class + +## Remarks A member of a class, structure, or union with local scope is declared **`static`**. -The following sample generates C2246: +## Example + +The following example generates C2246: ```cpp // C2246.cpp @@ -20,5 +23,5 @@ The following sample generates C2246: void func( void ) { class A { static int i; }; // C2246 i is local to func static int j; // OK -}; +} ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2247.md b/docs/error-messages/compiler-errors-1/compiler-error-c2247.md index 6fb7fea7989..e658316482a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2247.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2247.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2247" title: "Compiler Error C2247" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2247" +ms.date: 11/04/2016 f1_keywords: ["C2247"] helpviewer_keywords: ["C2247"] -ms.assetid: 72efa03e-615e-4ef9-aede-0a98654b20fd --- # Compiler Error C2247 -'identifier' not accessible because 'class' uses 'specifier' to inherit from 'class' +> 'identifier' not accessible because 'class' uses 'specifier' to inherit from 'class' + +## Remarks `identifier` is inherited from a class declared with private or protected access. -The following sample generates C2247: +## Examples + +The following example generates C2247: ```cpp // C2247.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2248.md b/docs/error-messages/compiler-errors-1/compiler-error-c2248.md index 22b7966dbd9..6a240fa1ff8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2248.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2248.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2248" title: "Compiler Error C2248" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2248" +ms.date: 09/27/2022 f1_keywords: ["C2248"] helpviewer_keywords: ["C2248"] -ms.assetid: 7a3ba0e8-d3b9-4bb9-95db-81ef17e31d23 --- # Compiler Error C2248 -'*member*' : cannot access '*access_level*' member declared in class '*class*' +> '*member*': can't access '*access_level*' member declared in class '*class*' + +## Remarks -Members of a derived class cannot access **`private`** members of a base class. You cannot access **`private`** or **`protected`** members of class instances. +Members of a derived class can't access **`private`** members of a base class. You can't access **`private`** or **`protected`** members of class instances. -## Example +## Examples -The following sample generates C2248 when private or protected members of a class are accessed from outside the class. To fix this issue, do not access these members directly outside the class. Use public member data and member functions to interact with the class. +The following example generates C2248 when `private` or `protected` members of a class are accessed from outside the class. To fix this issue, don't access these members directly outside the class. Use `public` member data and member functions to interact with the class. ```cpp // C2248_access.cpp @@ -44,7 +45,7 @@ int main() { } ``` -Another conformance issue that exposes C2248 is the use of template friends and specialization. To fix this issue, declare friend template functions by using either an empty template parameter list <> or specific template parameters. +Another conformance issue that exposes C2248 is the use of template friends and specialization. To fix this issue, declare friend function templates by using either an empty template parameter list `<>` or specific template parameters. ```cpp // C2248_template.cpp @@ -72,7 +73,7 @@ int main() { } ``` -Another conformance issue that exposes C2248 is when you attempt to declare a friend of a class and when the class is not visible to the friend declaration in the scope of the class. To fix this issue, grant friendship to the enclosing class. +Here's another conformance issue that exposes C2248: You attempt to declare a friend of a class, but the class isn't visible to the friend declaration in the scope of the class. To fix this issue, grant friendship to the enclosing class. ```cpp // C2248_enclose.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2249.md b/docs/error-messages/compiler-errors-1/compiler-error-c2249.md index 2b33cb4e285..59bdaa2294d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2249.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2249.md @@ -1,28 +1,29 @@ --- -description: "Learn more about: Compiler Error C2249" title: "Compiler Error C2249" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2249" +ms.date: 11/04/2016 f1_keywords: ["C2249"] helpviewer_keywords: ["C2249"] -ms.assetid: bdd6697c-e04b-49b9-8e40-d9eb6d74f2b6 --- # Compiler Error C2249 -'member' : no accessible path to access member declared in virtual base 'class' +> 'member' : no accessible path to access member declared in virtual base 'class' + +## Remarks The `member` is inherited from a nonpublic **`virtual`** base class or structure. ## Examples -The following sample generates C2249. +The following example generates C2249. ```cpp // C2249.cpp class A { private: - void privFunc( void ) {}; + void privFunc( void ) {} public: - void pubFunc( void ) {}; + void pubFunc( void ) {} }; class B : virtual public A {} b; @@ -33,7 +34,7 @@ int main() { } ``` -C2249 can also occur if you try to assign a stream from the C++ Standard Library to another stream. The following sample generates C2249. +C2249 can also occur if you try to assign a stream from the C++ Standard Library to another stream. The following example generates C2249. ```cpp // C2249_2.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2250.md b/docs/error-messages/compiler-errors-1/compiler-error-c2250.md index c4ac513175e..5e30d649e82 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2250.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2250.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2250" title: "Compiler Error C2250" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2250" +ms.date: 11/04/2016 f1_keywords: ["C2250"] helpviewer_keywords: ["C2250"] -ms.assetid: f990986f-5c7d-4af4-a25c-b35540f1e217 --- # Compiler Error C2250 -'identifier' : ambiguous inheritance of 'class::member' +> 'identifier' : ambiguous inheritance of 'class::member' + +## Remarks The derived class inherits more than one override of a virtual function of a virtual base class. These overrides are ambiguous in the derived class. -The following sample generates C2286: +## Example + +The following example generates C2250: ```cpp // C2250.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2251.md b/docs/error-messages/compiler-errors-1/compiler-error-c2251.md index 77ec80c5746..f3be89655fb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2251.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2251.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2251" title: "Compiler Error C2251" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2251" +ms.date: 11/04/2016 f1_keywords: ["C2251"] helpviewer_keywords: ["C2251"] -ms.assetid: fefe050c-f8d3-4316-b237-8007dbcdd3bf --- # Compiler Error C2251 -namespace 'namespace' does not have a member 'member' - Did you mean 'member'? +> namespace 'namespace' does not have a member 'member' - Did you mean 'member'? + +## Remarks The compiler was not able to find an identifier in the specified namespace. -The following sample generates C2251: +## Example + +The following example generates C2251: ```cpp // C2251.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2252.md b/docs/error-messages/compiler-errors-1/compiler-error-c2252.md index 7eaf55a4a0f..a26bb54ffd5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2252.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2252.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2252" title: "Compiler Error C2252" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2252" +ms.date: 11/04/2016 f1_keywords: ["C2252"] helpviewer_keywords: ["C2252"] -ms.assetid: fee74ab9-1997-4615-82fe-e6d1fe3aacd9 --- # Compiler Error C2252 -cannot explicitly instantiate template in current scope +> cannot explicitly instantiate template in current scope + +## Remarks The compiler detected a problem with an explicit instantiation of a template. For example, you cannot explicitly instantiate a template in a function. -The following sample generates C2252: +## Example + +The following example generates C2252: ```cpp // C2252.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2253.md b/docs/error-messages/compiler-errors-1/compiler-error-c2253.md index 95a67878c5b..10af621f451 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2253.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2253.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2253" title: "Compiler Error C2253" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2253" +ms.date: 11/04/2016 f1_keywords: ["C2253"] helpviewer_keywords: ["C2253"] -ms.assetid: bd6445ae-b2c1-4669-9657-a8f4acf80b16 --- # Compiler Error C2253 -'function' : pure specifier or abstract override specifier only allowed on virtual function +> 'function' : pure specifier or abstract override specifier only allowed on virtual function + +## Remarks A nonvirtual function is specified as pure **`virtual`**. -The following sample generates C2253: +## Examples + +The following example generates C2253: ```cpp // C2253.cpp @@ -24,7 +27,7 @@ public: }; ``` -The following sample generates C2253: +The following example generates C2253: ```cpp // C2253_2.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2254.md b/docs/error-messages/compiler-errors-1/compiler-error-c2254.md index 0f7436b72b5..46c118163cd 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2254.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2254.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2254" title: "Compiler Error C2254" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2254" +ms.date: 11/04/2016 f1_keywords: ["C2254"] helpviewer_keywords: ["C2254"] -ms.assetid: 49bb3d7e-3bdf-4af6-937c-fa627be412a9 --- # Compiler Error C2254 -'function' : pure specifier or abstract override specifier not allowed on friend function +> 'function' : pure specifier or abstract override specifier not allowed on friend function + +## Remarks A **`friend`** function is specified as pure **`virtual`**. -The following sample generates C2254: +## Example + +The following example generates C2254: ```cpp // C2254.cpp @@ -24,6 +27,6 @@ public: friend void func3(); // OK, friend not virtual nor pure }; -void func1() {}; -void func3() {}; +void func1() {} +void func3() {} ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2255.md b/docs/error-messages/compiler-errors-1/compiler-error-c2255.md index fa25eb214a5..99711de628b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2255.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2255.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2255" title: "Compiler Error C2255" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2255" +ms.date: 11/04/2016 f1_keywords: ["C2255"] helpviewer_keywords: ["C2255"] -ms.assetid: 67dc4cb0-de6b-4405-bd64-d47736367a93 --- # Compiler Error C2255 -'element' : not allowed outside of a class definition +> 'element' : not allowed outside of a class definition + +## Remarks For example, a nonmember function is declared a **`friend`**. -The following sample generates C2255: +## Example + +The following example generates C2255: ```cpp // C2255.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2256.md b/docs/error-messages/compiler-errors-1/compiler-error-c2256.md index c0c1e5daac7..2c40773e239 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2256.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2256.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2256" title: "Compiler Error C2256" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2256" +ms.date: 11/04/2016 f1_keywords: ["C2256"] helpviewer_keywords: ["C2256"] -ms.assetid: 171fa2bc-8c72-49cd-afe5-d723b7acd3c5 --- # Compiler Error C2256 -illegal use of friend specifier on 'function' +> illegal use of friend specifier on 'function' + +## Remarks A destructor or constructor cannot be specified as a [friend](../../cpp/friend-cpp.md). -The following sample generates C2256: +## Example + +The following example generates C2256: ```cpp // C2256.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2258.md b/docs/error-messages/compiler-errors-1/compiler-error-c2258.md index 1e31e3d7671..8b04f7d245e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2258.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2258.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2258" title: "Compiler Error C2258" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2258" +ms.date: 11/04/2016 f1_keywords: ["C2258"] helpviewer_keywords: ["C2258"] -ms.assetid: 105eaa87-befb-4ecb-9a3f-e09e14d2f5bf --- # Compiler Error C2258 -illegal pure syntax, must be '= 0' +> illegal pure syntax, must be '= 0' + +## Remarks A pure virtual function is declared with incorrect syntax. -The following sample generates C2258: +## Example + +The following example generates C2258: ```cpp // C2258.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2259.md b/docs/error-messages/compiler-errors-1/compiler-error-c2259.md index 11c96f2b724..9bcb2e62f8d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2259.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2259.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Error C2259" title: "Compiler Error C2259" +description: "Learn more about: Compiler Error C2259" ms.date: 07/08/2021 f1_keywords: ["C2259"] helpviewer_keywords: ["C2259"] -ms.assetid: e458236f-bdea-4786-9aa6-a98d8bffa5f4 --- # Compiler Error C2259 > '*class*' : cannot instantiate abstract class +## Remarks + Code declares an instance of an abstract class or structure. You can't instantiate a class or structure with one or more pure virtual functions. To instantiate objects of a derived class, the derived class must override each pure virtual function. For more information, see [Implicitly abstract classes](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Implicitly_abstract_classes). -The following sample generates C2259: +## Examples + +The following example generates C2259: ```cpp // C2259.cpp @@ -41,7 +44,7 @@ To resolve this issue, don't use more restrictive access permissions for the imp C2259 can also occur because of conformance work that was done in Visual Studio 2005, **`/Zc:wchar_t`** is now on by default. In this situation, C2599 can be resolved either by compiling with **`/Zc:wchar_t-`**, to get the behavior from previous versions, or preferably, by updating your types so they're compatible. For more information, see [`/Zc:wchar_t` (wchar_t Is Native Type)](../../build/reference/zc-wchar-t-wchar-t-is-native-type.md). -The following sample generates C2259: +The following example generates C2259: ```cpp // C2259b.cpp @@ -79,7 +82,7 @@ public: MyClass4 y; ``` -The following sample generates C2259: +The following example generates C2259: ```cpp // C2259c.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2261.md b/docs/error-messages/compiler-errors-1/compiler-error-c2261.md index eb8bd54da28..3c27593063d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2261.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2261.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2261" title: "Compiler Error C2261" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2261" +ms.date: 11/04/2016 f1_keywords: ["C2261"] helpviewer_keywords: ["C2261"] -ms.assetid: 60969482-9e83-49b5-9631-a04bc844da12 --- # Compiler Error C2261 -'string' : assembly reference is invalid and cannot be resolved +> 'string' : assembly reference is invalid and cannot be resolved + +## Remarks A value was not valid. @@ -18,7 +19,7 @@ For more on the correct syntax when specifying friend assemblies, see [Friend As ## Example -The following sample generates C2261. +The following example generates C2261. ```cpp // C2261.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2262.md b/docs/error-messages/compiler-errors-1/compiler-error-c2262.md index 8aa445522b1..752d2409f8f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2262.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2262.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2262" title: "Compiler Error C2262" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2262" +ms.date: 11/04/2016 f1_keywords: ["C2262"] helpviewer_keywords: ["C2262"] -ms.assetid: 727d1c6e-53e8-40e5-b7b8-6a7ac2011727 --- # Compiler Error C2262 -'attribute_specifiers' : InternalsVisibleTo declarations cannot have a version, culture, or processor architecture specified +> 'attribute_specifiers' : InternalsVisibleTo declarations cannot have a version, culture, or processor architecture specified + +## Remarks The attribute was not specified correctly. ## Example -The following sample generates C2262. +The following example generates C2262. ```cpp // C2262.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2264.md b/docs/error-messages/compiler-errors-1/compiler-error-c2264.md index e2e1dd617ec..915f27a906d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2264.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2264.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2264" title: "Compiler Error C2264" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2264" +ms.date: 11/04/2016 f1_keywords: ["C2264"] helpviewer_keywords: ["C2264"] -ms.assetid: 158b72cc-cee9-4a08-bd79-b7a5955345a8 --- # Compiler Error C2264 -'function' : error in function definition or declaration; function not called +> 'function' : error in function definition or declaration; function not called + +## Remarks The function cannot be called due to an incorrect definition or declaration. -The following sample generates C2264: +## Example + +The following example generates C2264: ```cpp // C2264.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2266.md b/docs/error-messages/compiler-errors-1/compiler-error-c2266.md index 9fc181b416e..ecd97db4e0b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2266.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2266.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2266" title: "Compiler Error C2266" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2266" +ms.date: 11/04/2016 f1_keywords: ["C2266"] helpviewer_keywords: ["C2266"] -ms.assetid: 5c267a67-d5a1-4ad7-b6f7-a156510aee35 --- # Compiler Error C2266 -'identifier' : reference to a non-constant bounded array is illegal +> 'identifier' : reference to a non-constant bounded array is illegal + +## Remarks A reference is declared for an array with a nonconstant bound. The array must have constant bounds. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2267.md b/docs/error-messages/compiler-errors-1/compiler-error-c2267.md index 4018e13c8c5..2393a3ecdbc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2267.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2267.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2267" title: "Compiler Error C2267" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2267" +ms.date: 11/04/2016 f1_keywords: ["C2267"] helpviewer_keywords: ["C2267"] -ms.assetid: ea63bebb-6208-4367-8440-39be07f9c360 --- # Compiler Error C2267 -'function' : static functions with block scope are illegal +> 'function' : static functions with block scope are illegal + +## Remarks A local function is declared **`static`**. Static functions must have global scope. -The following sample generates C2267: +## Example + +The following example generates C2267: ```cpp // C2267.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2268.md b/docs/error-messages/compiler-errors-1/compiler-error-c2268.md index 8be93111970..6c77ca44b41 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2268.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2268.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2268" title: "Compiler Error C2268" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2268" +ms.date: 11/04/2016 f1_keywords: ["C2268"] helpviewer_keywords: ["C2268"] -ms.assetid: 0ed055c9-3c6f-4df2-a5b6-85cf0e01a249 --- # Compiler Error C2268 -'function' is a compiler predefined library helper. Library helpers are not supported with /GL; compile object file 'file' without /GL. +> 'function' is a compiler predefined library helper. Library helpers are not supported with /GL; compile object file 'file' without /GL. + +## Remarks A function defined in your source code has the same name as an internal compiler function. Compile the module containing the function without [/GL](../../build/reference/gl-whole-program-optimization.md). -The following sample generates C2268: +## Example + +The following example generates C2268: ```c // C2268.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2270.md b/docs/error-messages/compiler-errors-1/compiler-error-c2270.md index b19c40b8b21..d6400d66435 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2270.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2270.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2270" title: "Compiler Error C2270" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2270" +ms.date: 11/04/2016 f1_keywords: ["C2270"] helpviewer_keywords: ["C2270"] -ms.assetid: b52c068e-0b61-42e7-b775-4d57b3ddcba0 --- # Compiler Error C2270 -'function' : modifiers not allowed on nonmember functions +> 'function' : modifiers not allowed on nonmember functions + +## Remarks A nonmember function is declared with [const](../../cpp/const-cpp.md), [volatile](../../cpp/volatile-cpp.md), or another memory-model modifier. -The following sample generates C2270: +## Example + +The following example generates C2270: ```cpp // C2270.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2271.md b/docs/error-messages/compiler-errors-1/compiler-error-c2271.md index cb79055f4c2..5cd706b2936 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2271.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2271.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2271" title: "Compiler Error C2271" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2271" +ms.date: 11/04/2016 f1_keywords: ["C2271"] helpviewer_keywords: ["C2271"] -ms.assetid: ea47bf57-f55d-4171-8e98-95a71d62820e --- # Compiler Error C2271 -'operator' : new/delete cannot have formal list modifiers +> 'operator' : new/delete cannot have formal list modifiers + +## Remarks The operator (**`new`** or **`delete`**) is declared with a memory-model specifier. -The following sample generates C2271: +## Example + +The following example generates C2271: ```cpp // C2271.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2272.md b/docs/error-messages/compiler-errors-1/compiler-error-c2272.md index a47e01e02a9..b8915aeab7b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2272.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2272.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2272" title: "Compiler Error C2272" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2272" +ms.date: 11/04/2016 f1_keywords: ["C2272"] helpviewer_keywords: ["C2272"] -ms.assetid: 1517706a-9c27-452e-9b10-3424b3d232bc --- # Compiler Error C2272 -'function' : modifiers not allowed on static member functions +> 'function' : modifiers not allowed on static member functions + +## Remarks A **`static`** member function is declared with a memory-model specifier, such as [const](../../cpp/const-cpp.md) or [volatile](../../cpp/volatile-cpp.md), and such modifiers are not allowed on **`static`** member functions. -The following sample generates C2272: +## Example + +The following example generates C2272: ```cpp // C2272.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2273.md b/docs/error-messages/compiler-errors-1/compiler-error-c2273.md index 2000e990c36..c1bc46a2c64 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2273.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2273.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2273" title: "Compiler Error C2273" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2273" +ms.date: 11/04/2016 f1_keywords: ["C2273"] helpviewer_keywords: ["C2273"] -ms.assetid: 3c682c66-97bf-4a23-a22c-d9a26a92bf95 --- # Compiler Error C2273 -'type' : illegal as right side of '->' operator +> 'type' : illegal as right side of '->' operator + +## Remarks A type appears as the right operand of a `->` operator. This error can be caused by trying to access a user-defined type conversion. Use the keyword **`operator`** between -> and `type`. -The following sample generates C2273: +## Example + +The following example generates C2273: ```cpp // C2273.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2274.md b/docs/error-messages/compiler-errors-1/compiler-error-c2274.md index 52cd5d4fcaf..1724a0006e3 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2274.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2274.md @@ -1,32 +1,16 @@ --- -description: "Learn more about: Compiler Error C2274" title: "Compiler Error C2274" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2274" +ms.date: 11/04/2016 f1_keywords: ["C2274"] helpviewer_keywords: ["C2274"] -ms.assetid: 8e874903-f499-45ef-8291-f821eee4cc1c --- # Compiler Error C2274 -'type' : illegal as right side of '.' operator - -A type appears as the right operand of a member-access (.) operator. - -This error can be caused by trying to access a user-defined type conversion. Use the keyword **`operator`** between the period and `type`. +> 'type' : illegal as right side of '.' operator -The following sample generates C2286: +## Remarks -```cpp -// C2274.cpp -struct MyClass { - operator int() { - return 0; - } -}; +A type appears as the right operand of a member-access (.) operator. -int main() { - MyClass ClassName; - int i = ClassName.int(); // C2274 - int j = ClassName.operator int(); // OK -} -``` +This error can be caused by trying to access a user-defined type conversion. Use the keyword **`operator`** between the period and `type`. \ No newline at end of file diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2275.md b/docs/error-messages/compiler-errors-1/compiler-error-c2275.md index 5398ae9154c..b4a3a21d317 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2275.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2275.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2275" title: "Compiler Error C2275" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2275" +ms.date: 11/04/2016 f1_keywords: ["C2275"] helpviewer_keywords: ["C2275"] -ms.assetid: c1eafa71-48de-46e0-82f3-b575538ef205 --- # Compiler Error C2275 -'identifier' : illegal use of this type as an expression +> 'identifier' : illegal use of this type as an expression + +## Remarks An expression uses the `->` operator with a **`typedef`** identifier. -The following sample generates C2275: +## Example + +The following example generates C2275: ```cpp // C2275.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2276.md b/docs/error-messages/compiler-errors-1/compiler-error-c2276.md index b6fe542bb7f..e583d2541cc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2276.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2276.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Error C2276" title: "Compiler Error C2276" +description: "Learn more about: Compiler Error C2276" ms.date: 03/25/2021 f1_keywords: ["C2276"] helpviewer_keywords: ["C2276"] @@ -9,15 +9,15 @@ helpviewer_keywords: ["C2276"] > '*operator*' : illegal operation on bound member function expression -The compiler found a problem with the syntax used to create a pointer-to-member. - ## Remarks +The compiler found a problem with the syntax used to create a pointer-to-member. + Error `C2276` is often caused when you attempt to create a pointer-to-member by using an instance variable to qualify the member, instead of a class type. You may also see this error if you're trying to call a member function by using the wrong syntax. ## Example -This sample shows several ways C2276 may occur, and how to fix them: +This example shows several ways C2276 may occur, and how to fix them: ```cpp // C2276.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2277.md b/docs/error-messages/compiler-errors-1/compiler-error-c2277.md index f1aef2b07ff..20429c174ac 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2277.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2277.md @@ -1,24 +1,29 @@ --- -description: "Learn more about: Compiler Error C2277" title: "Compiler Error C2277" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2277" +ms.date: 08/27/2025 f1_keywords: ["C2277"] helpviewer_keywords: ["C2277"] -ms.assetid: 15a83b07-8731-4524-810b-267f65a7844f --- # Compiler Error C2277 -'identifier' : cannot take address of this member function +> '*function*': cannot take address of this member function + +## Remarks -You cannot take the address of a member function. +You cannot take the address of a [constructor](../../cpp/constructors-cpp.md) or [destructor](../../cpp/destructors-cpp.md). For more information, see [Address-of operator: `&`](../../cpp/address-of-operator-amp.md) and [Pointers to Members](../../cpp/pointers-to-members.md). -The following sample generates C2277: +## Example + +The following example generates C2277: ```cpp -// C2277.cpp -class A { +// compile with: /c + +class A +{ public: A(); }; -(*pctor)() = &A::A; // C2277 +(*pctor)() = &A::A; // C2277 ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2279.md b/docs/error-messages/compiler-errors-1/compiler-error-c2279.md index b7df615fbd6..0591321c482 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2279.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2279.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2279" title: "Compiler Error C2279" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2279" +ms.date: 11/04/2016 f1_keywords: ["C2279"] helpviewer_keywords: ["C2279"] -ms.assetid: 1b5c88ef-2336-49b8-9ddb-d61f97c73e14 --- # Compiler Error C2279 -exception specification cannot appear in a typedef declaration +> exception specification cannot appear in a typedef declaration + +## Remarks Under **/Za**, [exception specifications](../../cpp/exception-specifications-throw-cpp.md) are not allowed in a typedef declaration. -The following sample generates C2279: +## Example + +The following example generates C2279: ```cpp // C2279.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2280.md b/docs/error-messages/compiler-errors-1/compiler-error-c2280.md index c438dc7138a..c952f212b5e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2280.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2280.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2280" title: "Compiler Error C2280" -ms.date: "04/25/2017" +description: "Learn more about: Compiler Error C2280" +ms.date: 04/25/2017 f1_keywords: ["C2280"] helpviewer_keywords: ["C2280"] -ms.assetid: e6c5b1fb-2b9b-4554-8ff9-775eeb37161b --- # Compiler Error C2280 -'*declaration*': attempting to reference a deleted function +> '*declaration*': attempting to reference a deleted function + +## Remarks The compiler detected an attempt to reference a `deleted` function. This error can be caused by a call to a member function that has been explicitly marked as `= deleted` in the source code. This error can also be caused by a call to an implicit special member function of a struct or class that is automatically declared and marked as `deleted` by the compiler. For more information about when the compiler automatically generates **`default`** or `deleted` special member functions, see [Special member functions](../../cpp/special-member-functions.md). 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 2c01122914a..8f402a366e2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2283.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2283.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2283" title: "Compiler Error C2283" -ms.date: "11/04/2016" +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 + +## Remarks A member function of an unnamed class or structure is declared with a pure specifier, which is not permitted. -The following sample generates C2283: +## Example + +The following example generates C2283: ```cpp // C2283.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2285.md b/docs/error-messages/compiler-errors-1/compiler-error-c2285.md index cb7c1d60c9e..d11de7e744b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2285.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2285.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2285" title: "Compiler Error C2285" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2285" +ms.date: 11/04/2016 f1_keywords: ["C2285"] helpviewer_keywords: ["C2285"] -ms.assetid: 7b40a1b0-f477-49fa-b762-c3bccd88514e --- # Compiler Error C2285 -pointers to members representation has already been determined - pragma ignored +> pointers to members representation has already been determined - pragma ignored + +## Remarks Two different representations exist for class. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2286.md b/docs/error-messages/compiler-errors-1/compiler-error-c2286.md index 8479291e545..81e52facd85 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2286.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2286.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2286" title: "Compiler Error C2286" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2286" +ms.date: 11/04/2016 f1_keywords: ["C2286"] helpviewer_keywords: ["C2286"] -ms.assetid: 078e0201-35cc-42e2-8dbc-6f8cf557b098 --- # Compiler Error C2286 -pointers to members of 'identifier' representation is already set to 'inheritance' - declaration ignored +> pointers to members of 'identifier' representation is already set to 'inheritance' - declaration ignored + +## Remarks Two different pointer-to-members representations exist for class. @@ -16,7 +17,7 @@ For more information, see [Inheritance Keywords](../../cpp/inheritance-keywords. ## Example -The following sample generates C2286: +The following example generates C2286: ```cpp // C2286.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2287.md b/docs/error-messages/compiler-errors-1/compiler-error-c2287.md index 178c7c0076b..5028b594ce8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2287.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2287.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2287" title: "Compiler Error C2287" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2287" +ms.date: 11/04/2016 f1_keywords: ["C2287"] helpviewer_keywords: ["C2287"] -ms.assetid: 64556299-4e1f-4437-88b7-2464fc0b95bb --- # Compiler Error C2287 -'class': inheritance representation: 'representation1' is less general than the required 'representation2' +> 'class': inheritance representation: 'representation1' is less general than the required 'representation2' + +## Remarks A class is declared with a simpler representation than required. -The following sample generates C2287: +## Example + +The following example generates C2287: ```cpp // C2287.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2289.md b/docs/error-messages/compiler-errors-1/compiler-error-c2289.md index 485af601948..25fe25f0f2f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2289.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2289.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2289" title: "Compiler Error C2289" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2289" +ms.date: 11/04/2016 f1_keywords: ["C2289"] helpviewer_keywords: ["C2289"] -ms.assetid: cb41a29e-1b06-47dc-bfce-8d73bd63a0df --- # Compiler Error C2289 -same type qualifier used more than once +> same type qualifier used more than once + +## Remarks A type declaration or definition uses a type qualifier (**`const`**, **`volatile`**, **`signed`**, or **`unsigned`**) more than once, causing an error under ANSI compatibility (**/Za**). -The following sample generates C2286: +## Example + +The following example generates C2289: ```cpp // C2289.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2290.md b/docs/error-messages/compiler-errors-1/compiler-error-c2290.md index f69fdf273cf..41f755959b1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2290.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2290.md @@ -1,13 +1,29 @@ --- -description: "Learn more about: Compiler Error C2290" title: "Compiler Error C2290" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2290" +ms.date: 12/5/2025 f1_keywords: ["C2290"] helpviewer_keywords: ["C2290"] -ms.assetid: 78c0feec-ccde-401b-8335-5b6ea6be8a13 --- # Compiler Error C2290 -C++ asm syntax ignored. Use __asm. +> C++ 'asm' syntax ignored. Use __asm. + +## Remarks + +The **`asm`** syntax is reserved for future use. Try [`__asm`](../../assembler/inline/asm.md) instead. For more information, see [Inline Assembler](../../assembler/inline/inline-assembler.md). + +## Example + +The following example generates C2290: + +```cpp +// C2290.cpp +// Compile for 32 bit, i.e. x86 instead of x64 -The **`asm`** syntax is reserved for future use. +int main() +{ + asm("nop"); // C2290 + __asm { nop } // OK +} +``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2292.md b/docs/error-messages/compiler-errors-1/compiler-error-c2292.md index 45784ec91f4..1b9d0e238de 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2292.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2292.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2292" title: "Compiler Error C2292" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2292" +ms.date: 11/04/2016 f1_keywords: ["C2292"] helpviewer_keywords: ["C2292"] -ms.assetid: 256b392f-2b8f-4162-b578-e7633984e162 --- # Compiler Error C2292 -'identifier': best case inheritance representation: 'representation1' declared but 'representation2' required +> 'identifier': best case inheritance representation: 'representation1' declared but 'representation2' required + +## Example Compiling the following code with [/vmb](../../build/reference/vmb-vmg-representation-method.md) ("Best-case always" representation) causes C2292. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2293.md b/docs/error-messages/compiler-errors-1/compiler-error-c2293.md index 6e0833a07e3..d5eb84b0f59 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2293.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2293.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2293" title: "Compiler Error C2293" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2293" +ms.date: 11/04/2016 f1_keywords: ["C2293"] helpviewer_keywords: ["C2293"] -ms.assetid: 17e7b4e2-368b-4dd7-a01b-d82be60f8e56 --- # Compiler Error C2293 -'identifier': illegal to have a member variable as a __based specifier +> 'identifier': illegal to have a member variable as a __based specifier + +## Remarks Specifiers for **`__based`** modifier must be nonmember pointers. -The following sample generates C2293: +## Example + +The following example generates C2293: ```cpp // C2293.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2295.md b/docs/error-messages/compiler-errors-1/compiler-error-c2295.md index 484d1908b7d..f67e5222233 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2295.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2295.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2295" title: "Compiler Error C2295" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2295" +ms.date: 11/04/2016 f1_keywords: ["C2295"] helpviewer_keywords: ["C2295"] -ms.assetid: faddf446-5924-401e-b719-93390d5cd084 --- # Compiler Error C2295 -escaped 'character' : is illegal in macro definition +> escaped 'character' : is illegal in macro definition + +## Remarks A macro definition cannot contain an escape sequence with the specified character. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2296.md b/docs/error-messages/compiler-errors-1/compiler-error-c2296.md index bdd1b4b3d24..a37e7a959bf 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2296.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2296.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2296" title: "Compiler Error C2296" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2296" +ms.date: 11/04/2016 f1_keywords: ["C2296"] helpviewer_keywords: ["C2296"] -ms.assetid: 47d270f4-13ce-4c16-81e2-7d67c6c4a540 --- # Compiler Error C2296 -'operator' : bad left operand +> 'operator' : bad left operand + +## Remarks The left operand used with `operator` is invalid. For example, the compiler may see a declaration where you intended a function call. -The following sample generates C2296: +## Example + +The following example generates C2296: ```cpp // C2296.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2297.md b/docs/error-messages/compiler-errors-1/compiler-error-c2297.md index 97ed907a34a..8ce344ccd8b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2297.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2297.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2297" title: "Compiler Error C2297" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2297" +ms.date: 11/04/2016 f1_keywords: ["C2297"] helpviewer_keywords: ["C2297"] -ms.assetid: 65849fe5-17e1-4b7e-b50c-f508b05ddaa4 --- # Compiler Error C2297 -'operator' : bad right operand +> 'operator' : bad right operand + +## Remarks The right operand used with `operator` is invalid. For example, the compiler may see a declaration where you intended a function call. -The following sample generates C2297: +## Example + +The following example generates C2297: ```cpp // C2297.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2298.md b/docs/error-messages/compiler-errors-1/compiler-error-c2298.md index 529c6f15ebc..cddce97fedd 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2298.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2298.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2298" title: "Compiler Error C2298" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2298" +ms.date: 11/04/2016 f1_keywords: ["C2298"] helpviewer_keywords: ["C2298"] -ms.assetid: eb0120ad-c850-4bdd-911d-0361229cc859 --- # Compiler Error C2298 -'operation' : illegal operation on pointer to member function expression +> 'operation' : illegal operation on pointer to member function expression + +## Remarks A pointer to member-function expression must call the member function. ## Examples -The following sample generates C2298. +The following example generates C2298. ```cpp // C2298.cpp @@ -48,7 +49,7 @@ int main() { } ``` -The following sample generates C2298. +The following example generates C2298. ```cpp // C2298_b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2299.md b/docs/error-messages/compiler-errors-1/compiler-error-c2299.md index a3ad1a5dfde..ae1494b4035 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2299.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2299.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2299" title: "Compiler Error C2299" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2299" +ms.date: 11/04/2016 f1_keywords: ["C2299"] helpviewer_keywords: ["C2299"] -ms.assetid: d001c2bc-f6fd-47aa-8e42-0eb824d6441d --- # Compiler Error C2299 -'function' : behavior change: an explicit specialization can not be a copy constructor or copy assignment operator +> '*function*': behavior change: an explicit specialization can not be a copy constructor or copy assignment operator + +## Remarks + +This error can also be generated as a result of compiler conformance work that was done for Visual Studio 2005. Previous versions of Visual C++ allowed explicit specializations for a copy constructor or a copy assignment operator. -This error can also be generated as a result of compiler conformance work that was done for Visual Studio 2005: previous versions of Visual C++ allowed explicit specializations for a copy constructor or a copy assignment operator. +To resolve C2299, don't make the copy constructor or assignment operator a function template. Make them non-template functions that take a class type. Any code that calls the copy constructor or assignment operator by explicitly specifying the template arguments needs to remove the template arguments. -To resolve C2299, do not make the copy constructor or assignment operator a template function, but rather a non-template function that takes a class type. Any code that calls the copy constructor or assignment operator by explicitly specifying the template arguments needs to remove the template arguments. +## Example -The following sample generates C2299: +The following example generates C2299: ```cpp // C2299.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2300.md b/docs/error-messages/compiler-errors-1/compiler-error-c2300.md index 38fcc87e79f..5727f9ee377 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2300.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2300.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2300" title: "Compiler Error C2300" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2300" +ms.date: 11/04/2016 f1_keywords: ["C2300"] helpviewer_keywords: ["C2300"] -ms.assetid: bb8fed56-feb0-412b-ae7b-04d48b202b78 --- # Compiler Error C2300 -'identifier' : class does not have a destructor called '~identifier' +> 'identifier' : class does not have a destructor called '~identifier' + +## Remarks The class does not have a destructor with the required name. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2301.md b/docs/error-messages/compiler-errors-1/compiler-error-c2301.md index d95b81771a2..95225fd76a4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2301.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2301.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2301" title: "Compiler Error C2301" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2301" +ms.date: 11/04/2016 f1_keywords: ["C2301"] helpviewer_keywords: ["C2301"] -ms.assetid: d294a1a2-dc7a-4e18-90b3-747e1a8c51ee --- # Compiler Error C2301 -left of '->~identifier' must point to class/struct/union +> left of '->~identifier' must point to class/struct/union + +## Remarks The expression to the left of the `->` operator does not evaluate to a pointer to a class, structure, or union. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2302.md b/docs/error-messages/compiler-errors-1/compiler-error-c2302.md index b496d9de753..18abffb5de1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2302.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2302.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2302" title: "Compiler Error C2302" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2302" +ms.date: 11/04/2016 f1_keywords: ["C2302"] helpviewer_keywords: ["C2302"] -ms.assetid: 74a54bab-9d5c-446e-9b1f-c92fb57090a8 --- # Compiler Error C2302 -left of '.~identifier' must have class/struct/union type +> left of '.~identifier' must have class/struct/union type + +## Remarks The expression to the left of the period (.) operator is not a class, structure, or union. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2307.md b/docs/error-messages/compiler-errors-1/compiler-error-c2307.md index 469a7facd99..69e3890ef35 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2307.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2307.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2307" title: "Compiler Error C2307" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2307" +ms.date: 11/04/2016 f1_keywords: ["C2307"] helpviewer_keywords: ["C2307"] -ms.assetid: ce6c8033-a673-4679-9883-bedec36ae385 --- # Compiler Error C2307 -pragma 'pragma' must be outside function if incremental compilation is enabled +> pragma 'pragma' must be outside function if incremental compilation is enabled + +## Remarks You must place the `data_seg` pragma between functions if you're using incremental compilation. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2308.md b/docs/error-messages/compiler-errors-1/compiler-error-c2308.md index 83af91881dc..60d5d48ec7c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2308.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2308.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2308" title: "Compiler Error C2308" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2308" +ms.date: 11/04/2016 f1_keywords: ["C2308"] helpviewer_keywords: ["C2308"] -ms.assetid: d1eaf101-077d-4c43-97ac-410efd5b6fc9 --- # Compiler Error C2308 -concatenating mismatched strings +> concatenating mismatched strings + +## Remarks Both wide and non-wide character strings were specified for concatenation. You cannot concatenate a wide character string and non-wide character string. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2309.md b/docs/error-messages/compiler-errors-1/compiler-error-c2309.md index 631119862e5..e2d392ca6a8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2309.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2309.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2309" title: "Compiler Error C2309" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2309" +ms.date: 11/04/2016 f1_keywords: ["C2309"] helpviewer_keywords: ["C2309"] -ms.assetid: 6303d5b5-72cf-42b8-92ce-b1eb48e80d48 --- # Compiler Error C2309 -catch handler expected a parenthesized exception declaration +> catch handler expected a parenthesized exception declaration + +## Remarks A catch handler has no parenthesized type. -The following sample generates C2309: +## Example + +The following example generates C2309: ```cpp // C2309.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2310.md b/docs/error-messages/compiler-errors-1/compiler-error-c2310.md index b66045af5f2..401f5456254 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2310.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2310.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2310" title: "Compiler Error C2310" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2310" +ms.date: 11/04/2016 f1_keywords: ["C2310"] helpviewer_keywords: ["C2310"] -ms.assetid: 1969c682-b97e-43fb-b9a9-f783e7ff1710 --- # Compiler Error C2310 -catch handlers must specify one type +> catch handlers must specify one type + +## Remarks A catch handler specified no type or multiple types. -The following sample generates C2310: +## Example + +The following example generates C2310: ```cpp // C2310.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2311.md b/docs/error-messages/compiler-errors-1/compiler-error-c2311.md index 1593deabd62..8b132322598 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2311.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2311.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2311" title: "Compiler Error C2311" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2311" +ms.date: 11/04/2016 f1_keywords: ["C2311"] helpviewer_keywords: ["C2311"] -ms.assetid: 1aff9bd5-ed0b-4db6-bbc0-01ac89850cf2 --- # Compiler Error C2311 -'exception' : is caught by '...' on line number +> 'exception' : is caught by '...' on line number + +## Remarks The catch handler for the ellipsis (...) must be the last handler for a throw. -The following sample generates C2311: +## Example + +The following example generates C2311: ```cpp // C2311.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2312.md b/docs/error-messages/compiler-errors-1/compiler-error-c2312.md index 39b2968286d..81b15ceb6ff 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2312.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2312.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2312" title: "Compiler Error C2312" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2312" +ms.date: 11/04/2016 f1_keywords: ["C2312"] helpviewer_keywords: ["C2312"] -ms.assetid: c8bcfd06-12c1-4323-bb53-ba392d36daa4 --- # Compiler Error C2312 -'exception1' : is caught by 'exception2' on line number +> 'exception1' : is caught by 'exception2' on line number + +## Remarks Two handlers catch the same exception type. -The following sample generates C2312: +## Example + +The following example generates C2312: ```cpp // C2312.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2313.md b/docs/error-messages/compiler-errors-1/compiler-error-c2313.md index 01c0b6c5737..2d71495167d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2313.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2313.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2313" title: "Compiler Error C2313" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2313" +ms.date: 11/04/2016 f1_keywords: ["C2313"] helpviewer_keywords: ["C2313"] -ms.assetid: f70eb19b-c0a3-4fb2-ade1-3890a589928d --- # Compiler Error C2313 -'type1' : is caught by reference ('type2') on line number +> 'type1' : is caught by reference ('type2') on line number + +## Remarks The exception type has two handlers. The type for the second catch is a reference to the type of the first. -The following sample generates C2313: +## Example + +The following example generates C2313: ```cpp // C2313.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2315.md b/docs/error-messages/compiler-errors-1/compiler-error-c2315.md index fc0b04c563f..d6ea11e2f93 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2315.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2315.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2315" title: "Compiler Error C2315" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2315" +ms.date: 11/04/2016 f1_keywords: ["C2315"] helpviewer_keywords: ["C2315"] -ms.assetid: a0d91b81-944c-4a69-9a24-fd484aabcc5c --- # Compiler Error C2315 -'type1' : reference is caught by 'type2' on line number +> 'type1' : reference is caught by 'type2' on line number + +## Remarks The exception type is handled by a previous handler. The reference for the second catch has the type of the first. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2316.md b/docs/error-messages/compiler-errors-1/compiler-error-c2316.md index 6163529aca2..4e208a5fc5b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2316.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2316.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: Compiler Error C2316" title: "Compiler Error C2316" -ms.date: "07/08/2019" +description: "Learn more about: Compiler Error C2316" +ms.date: 07/08/2019 f1_keywords: ["C2316"] helpviewer_keywords: ["C2316"] -ms.assetid: 9ad08eb5-060b-4eb0-8d66-0dc134f7bf67 --- # Compiler Error C2316 > '*class_type*' : cannot be caught as the destructor and/or copy constructor are inaccessible or deleted -An exception was caught by value or by reference, but the copy constructor, the assignment operator, or both were inaccessible. - ## Remarks +An exception was caught by value or by reference, but the copy constructor, the assignment operator, or both were inaccessible. + Conformance changes in Visual Studio 2015 made this error apply to bad catch statements of MFC exceptions derived from `CException`. Because `CException` has an inherited private copy constructor, the class and its derivatives aren't copyable, and can't be passed by value, which also means they can't be caught by value. Catch statements that caught MFC exceptions by value previously led to uncaught exceptions at runtime. Now the compiler correctly identifies this situation and reports error C2316. To fix this issue, we recommend you use the MFC TRY/CATCH macros rather than write your own exception handlers. If that's not appropriate for your code, catch MFC exceptions by reference instead. ## Example -The following sample generates C2316, and shows a way to fix it: +The following example generates C2316, and shows a way to fix it: ```cpp // C2316.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2317.md b/docs/error-messages/compiler-errors-1/compiler-error-c2317.md index 79f823cb0e5..fc575b588a1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2317.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2317.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2317" title: "Compiler Error C2317" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2317" +ms.date: 11/04/2016 f1_keywords: ["C2317"] helpviewer_keywords: ["C2317"] -ms.assetid: e44d129b-8d3e-4ce9-9d79-6791ee77f25e --- # Compiler Error C2317 -'try' block starting on line 'number' has no catch handlers +> 'try' block starting on line 'number' has no catch handlers + +## Remarks A **`try`** block must have at least one catch handler. -The following sample generates C2317: +## Example + +The following example generates C2317: ```cpp // C2317.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2318.md b/docs/error-messages/compiler-errors-1/compiler-error-c2318.md index b5482c8358f..5a67e8cb5a3 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2318.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2318.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2318" title: "Compiler Error C2318" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2318" +ms.date: 11/04/2016 f1_keywords: ["C2318"] helpviewer_keywords: ["C2318"] -ms.assetid: 169e30b9-df78-46cb-90bf-576ad3c32fd4 --- # Compiler Error C2318 -no try block associated with this catch handler +> no try block associated with this catch handler + +## Remarks A **`catch`** handler is defined but not preceded by a **`try`** block. -The following sample generates C2318: +## Example + +The following example generates C2318: ```cpp // C2318.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2319.md b/docs/error-messages/compiler-errors-1/compiler-error-c2319.md index 0a9d1381842..87a4c1537f5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2319.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2319.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2319" title: "Compiler Error C2319" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2319" +ms.date: 11/04/2016 f1_keywords: ["C2319"] helpviewer_keywords: ["C2319"] -ms.assetid: 25263e6e-f5ba-4d2c-8727-8c2d8ca2e5ce --- # Compiler Error C2319 -'try/catch' must be followed by a compound statement. Missing '{' +> 'try/catch' must be followed by a compound statement. Missing '{' + +## Remarks A **`try`** or **`catch`** block is not found following the **`try`** or **`catch`** statement. The block must be enclosed in curly braces. -The following sample generates C2319: +## Example + +The following example generates C2319: ```cpp // C2319.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2320.md b/docs/error-messages/compiler-errors-1/compiler-error-c2320.md index 1b9cf5a1050..ea08646bec4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2320.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2320.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2320" title: "Compiler Error C2320" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2320" +ms.date: 11/04/2016 f1_keywords: ["C2320"] helpviewer_keywords: ["C2320"] -ms.assetid: ae78ae1b-364f-4b65-bfb8-8809d5151ca5 --- # Compiler Error C2320 > expected ':' to follow access specifier '*specifier*' +## Remarks + The keyword **`public`**, **`protected`**, or **`private`** must be followed by a colon. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2322.md b/docs/error-messages/compiler-errors-1/compiler-error-c2322.md index 3118e5213b8..fb2482086a5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2322.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2322.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2322" title: "Compiler Error C2322" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2322" +ms.date: 11/04/2016 f1_keywords: ["C2322"] helpviewer_keywords: ["C2322"] -ms.assetid: f9b92005-618a-42d8-80e9-67ce769a9f3b --- # Compiler Error C2322 -'identifier' : address of dllimport 'dllimport' is not static +> 'identifier' : address of dllimport 'dllimport' is not static + +## Remarks A nonstatic value is given as the address of a function declared with `dllimport`. 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 00000000000..1c00da83503 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2323.md @@ -0,0 +1,35 @@ +--- +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. + +## Remarks + +The `new` and `delete` overload operators must be non-static, defined in the global namespace or as class members. + +## Example + +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-c2324.md b/docs/error-messages/compiler-errors-1/compiler-error-c2324.md index d1ef4836f5e..fcb0fd61a1a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2324.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2324.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2324" title: "Compiler Error C2324" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2324" +ms.date: 11/04/2016 f1_keywords: ["C2324"] helpviewer_keywords: ["C2324"] -ms.assetid: 215f0544-85b0-452d-825f-17a388b6a61c --- # Compiler Error C2324 -'identifier' : unexpected to the right of 'name' +> 'identifier' : unexpected to the right of 'name' + +## Remarks A destructor is called using an incorrect identifier. -The following sample generates C2324: +## Example + +The following example generates C2324: ```cpp // C2324.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2325.md b/docs/error-messages/compiler-errors-1/compiler-error-c2325.md index 4085db3ee9c..4864fe0c516 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2325.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2325.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2325" title: "Compiler Error C2325" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2325" +ms.date: 11/04/2016 f1_keywords: ["C2325"] helpviewer_keywords: ["C2325"] -ms.assetid: e6b0a186-3f2a-4adf-beae-fadd75492bf7 --- # Compiler Error C2325 -'type' : unexpected type to the right of 'name' +> 'type' : unexpected type to the right of 'name' + +## Remarks A call is made to a destructor of incorrect type. -The following sample generates C2325: +## Example + +The following example generates C2325: ```cpp // C2325.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2326.md b/docs/error-messages/compiler-errors-1/compiler-error-c2326.md index ba0c0c01128..5168287dacd 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2326.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2326.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2326" title: "Compiler Error C2326" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2326" +ms.date: 11/04/2016 f1_keywords: ["C2326"] helpviewer_keywords: ["C2326"] -ms.assetid: 01a5ea40-de83-4e6f-a4e8-469f441258e0 --- # Compiler Error C2326 -'declarator' : function cannot access 'name' +> 'declarator' : function cannot access 'name' + +## Remarks The code tries to modify a member variable, which is not possible. ## Example -The following sample generates C2326: +The following example generates C2326: ```cpp // C2326.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2327.md b/docs/error-messages/compiler-errors-1/compiler-error-c2327.md index 1a2c9cb18a9..204783d6cb6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2327.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2327.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2327" title: "Compiler Error C2327" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2327" +ms.date: 11/04/2016 f1_keywords: ["C2327"] helpviewer_keywords: ["C2327"] -ms.assetid: 95278c95-d1f9-4487-ad27-53311f5e8112 --- # Compiler Error C2327 -'symbol' : is not a type name, static, or enumerator +> 'symbol' : is not a type name, static, or enumerator + +## Remarks Code within a nested class attempts to access a member of the enclosing class that is not a type name, a static member, or an enumerator. When compiling with **/clr**, a common cause for C2327 is a property with the same name as the property type. -The following sample generates C2327: +## Examples + +The following example generates C2327: ```cpp // C2327.cpp @@ -62,7 +65,7 @@ struct B { }; ``` -The following sample generates C2327: +The following example generates C2327: ```cpp // C2327d.cpp @@ -96,7 +99,7 @@ namespace NA { } ``` -The following sample shows C2327 when a property has the same name as the property type: +The following example shows C2327 when a property has the same name as the property type: ```cpp // C2327f.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2332.md b/docs/error-messages/compiler-errors-1/compiler-error-c2332.md index 90d950d5461..8ff2d139da5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2332.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2332.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2332" title: "Compiler Error C2332" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2332" +ms.date: 11/04/2016 f1_keywords: ["C2332"] helpviewer_keywords: ["C2332"] -ms.assetid: fb05cd68-e271-4bea-9fb7-ef4edb0a26ac --- # Compiler Error C2332 -'typedef' : missing tag name +> 'typedef' : missing tag name + +## Remarks The compiler found an incomplete type definition. -The following sample generates C2332: +## Example + +The following example generates C2332: ```cpp // C2332.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2333.md b/docs/error-messages/compiler-errors-1/compiler-error-c2333.md index b1be3f36fc8..ef87be83dac 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2333.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2333.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2333" title: "Compiler Error C2333" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2333" +ms.date: 11/04/2016 f1_keywords: ["C2333"] helpviewer_keywords: ["C2333"] -ms.assetid: 2636fc1e-d3e7-4e68-8628-3c81a99ba813 --- # Compiler Error C2333 -'function' : error in function declaration; skipping function body +> 'function' : error in function declaration; skipping function body + +## Remarks This error occurs after another error, for member functions defined inside their class. -The following sample generates C2333: +## Example + +The following example generates C2333: ```cpp // C2333.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2334.md b/docs/error-messages/compiler-errors-1/compiler-error-c2334.md index 0ba710e94ac..83f01fe91e8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2334.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2334.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Compiler Error C2334" title: "Compiler Error C2334" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2334" +ms.date: 11/04/2016 f1_keywords: ["C2334"] helpviewer_keywords: ["C2334"] -ms.assetid: 36142855-e00b-4bbf-80f5-a301edeff46e --- # Compiler Error C2334 -unexpected token(s) preceding ': or {'; skipping apparent function body +> unexpected token(s) preceding ': or {'; skipping apparent function body + +## Example -The following sample generates C2334. This error occurs after error C2059: +The following example generates C2334. This error occurs after error C2059: ```cpp // C2334.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2337.md b/docs/error-messages/compiler-errors-1/compiler-error-c2337.md index ca4fe6be894..9f5f6c91490 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2337.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2337.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2337" title: "Compiler Error C2337" -ms.date: "09/19/2019" +description: "Learn more about: Compiler Error C2337" +ms.date: 09/19/2019 f1_keywords: ["C2337"] helpviewer_keywords: ["C2337"] -ms.assetid: eccc9178-a15e-42cd-bbd0-3cea7cf2d55b --- # Compiler Error C2337 > '*attribute-name*' : attribute not found +## Remarks + Your code uses an attribute that isn't supported in this context. Or, the attribute isn't available in this version of the compiler. To resolve this issue, remove the unsupported attribute. -The following sample generates C2337: +## Example + +The following example generates C2337: ```cpp // C2337.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2338.md b/docs/error-messages/compiler-errors-1/compiler-error-c2338.md index 1ab34e8a9b8..db9b460f461 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2338.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2338.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2338" title: "Compiler Error C2338" +description: "Learn more about: Compiler Error C2338" ms.date: 02/22/2022 f1_keywords: ["C2338"] helpviewer_keywords: ["C2338"] -ms.assetid: 49bba575-1de4-4963-86c6-ce3226a2ba51 --- # Compiler Error C2338 > *Error message* +## Remarks + Error C2338 can be caused by a **`static_assert`** error during compilation. The message is supplied by the **`static_assert`** parameters. Error C2338 can also be generated by external providers to the compiler. In most cases, these errors are reported by an attribute provider DLL, such as ATLPROV. Some common forms of this message include: @@ -24,6 +25,8 @@ These errors are often unrecoverable, and may be followed by a fatal compiler er To fix these issues, correct the attribute usage. For example, in some cases, attribute parameters must be declared before they can be used. If an ATL error number is provided, check the documentation for that error for more specific information. +## Example + In Standard C++11 and later, **`constexpr`** functions are no longer considered **`noexcept`** by default when used in a constant expression. This behavior change comes from the resolution of Core Working Group (CWG) [CWG 1351](https://wg21.link/cwg1351) and is enabled in [`/permissive-`](../../build/reference/permissive-standards-conformance.md) mode. The following example compiles in Visual Studio 2019 version 16.1 and earlier, but produces C2338 in Visual Studio 2019 version 16.2: ```cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2341.md b/docs/error-messages/compiler-errors-1/compiler-error-c2341.md index 74f459a7bf2..3fe4850bb8d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2341.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2341.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2341" title: "Compiler Error C2341" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2341" +ms.date: 11/04/2016 f1_keywords: ["C2341"] helpviewer_keywords: ["C2341"] -ms.assetid: aa2a7da5-e1c8-4225-9939-5bdc50158f31 --- # Compiler Error C2341 -'section name' : segment must be defined using #pragma data_seg, code_seg or section prior to use +> 'section name' : segment must be defined using #pragma data_seg, code_seg or section prior to use + +## Remarks An [allocate](../../cpp/allocate.md) statement refers to a segment not yet defined by [code_seg](../../preprocessor/code-seg.md), [data_seg](../../preprocessor/data-seg.md), or [section](../../preprocessor/section.md) pragmas. -The following sample generates C2341: +## Example + +The following example generates C2341: ```cpp // C2341.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2344.md b/docs/error-messages/compiler-errors-1/compiler-error-c2344.md index 4fb3b3f2f7b..978a21fe0fa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2344.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2344.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C2344" title: "Compiler Error C2344" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2344" +ms.date: 11/04/2016 f1_keywords: ["C2344"] helpviewer_keywords: ["C2344"] -ms.assetid: a84c7b37-c84e-4345-8691-c23abb2dc193 --- # Compiler Error C2344 -align(#) : alignment must be power of two +> align(#) : alignment must be power of two + +## Remarks When using the [align](../../cpp/align-cpp.md) keyword, the value you pass must be a power of two. +## Example + For example, the following code generates C2344 because 3 is not a power of two: ```cpp 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 50933b2e645..6d621a6d8c2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2345.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2345.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Error C2345" title: "Compiler Error C2345" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2345" +ms.date: 11/04/2016 f1_keywords: ["C2345"] helpviewer_keywords: ["C2345"] -ms.assetid: e1cc88b0-0223-4d07-975b-fa99956a82bd --- # Compiler Error C2345 -align(value) : illegal alignment value +> align(value) : illegal alignment value + +## Remarks You passed a value to the [align](../../cpp/align-cpp.md) keyword that is outside the allowable range. -The following code generates C2345 +## Example + +The following example 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-c2346.md b/docs/error-messages/compiler-errors-1/compiler-error-c2346.md index 6c26eabe752..b4a03aaf133 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2346.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2346.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2346" title: "Compiler Error C2346" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2346" +ms.date: 11/04/2016 f1_keywords: ["C2346"] helpviewer_keywords: ["C2346"] -ms.assetid: 246145be-5645-4cd6-867c-e3bc39e33dca --- # Compiler Error C2346 -'function' cannot be compiled as native: reason +> 'function' cannot be compiled as native: reason + +## Remarks The compiler was unable to compile a function to MSIL. @@ -22,7 +23,7 @@ For more information, see [managed, unmanaged](../../preprocessor/managed-unmana ## Example -The following sample generates C2346. +The following example generates C2346. ```cpp // C2346.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2348.md b/docs/error-messages/compiler-errors-1/compiler-error-c2348.md index 66e3378836a..f2d45f255de 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2348.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2348.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2348" title: "Compiler Error C2348" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2348" +ms.date: 11/04/2016 f1_keywords: ["C2348"] helpviewer_keywords: ["C2348"] -ms.assetid: 4c4d701f-ccf1-46fe-9ddb-3f341684f269 --- # Compiler Error C2348 -'type name' : is not a C-style aggregate, cannot be exported in embedded-IDL +> 'type name' : is not a C-style aggregate, cannot be exported in embedded-IDL + +## Remarks To place a **`struct`** in a .idl file with the [export](../../windows/attributes/export.md) attribute, the **`struct`** must contain only data. -The following sample generates C2348: +## Example + +The following example generates C2348: ```cpp // C2348.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2349.md b/docs/error-messages/compiler-errors-1/compiler-error-c2349.md index 4b596fc273d..b365f1b240e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2349.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2349.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2349" title: "Compiler Error C2349" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2349" +ms.date: 11/04/2016 f1_keywords: ["C2349"] helpviewer_keywords: ["C2349"] -ms.assetid: ce9f2e65-fda0-41b6-9c4a-538607136396 --- # Compiler Error C2349 -'function' cannot be compiled as managed: 'reason'; use #pragma unmanaged +> 'function' cannot be compiled as managed: 'reason'; use #pragma unmanaged + +## Remarks -For more information see [Compiler Warning (level 1 and 3) C4793](../../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md). +For more information, see [Compiler Warning (level 1 and 3) C4793](../../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md). diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2350.md b/docs/error-messages/compiler-errors-1/compiler-error-c2350.md index f4ba948e013..8d4160dde22 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2350.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2350.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2350" title: "Compiler Error C2350" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2350" +ms.date: 11/04/2016 f1_keywords: ["C2350"] helpviewer_keywords: ["C2350"] -ms.assetid: 3a50cb94-8ced-4df4-b602-c48916fa957d --- # Compiler Error C2350 -'identifier' is not a static member +> 'identifier' is not a static member + +## Remarks Nonstatic members of a class or structure cannot be defined. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2351.md b/docs/error-messages/compiler-errors-1/compiler-error-c2351.md index cb65e6f46a4..a3f4108c1ca 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2351.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2351.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2351" title: "Compiler Error C2351" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2351" +ms.date: 11/04/2016 f1_keywords: ["C2351"] helpviewer_keywords: ["C2351"] -ms.assetid: 5439ccf6-66f6-4859-964c-c73f5eddfc1b --- # Compiler Error C2351 -obsolete C++ constructor initialization syntax +> obsolete C++ constructor initialization syntax + +## Remarks In a new-style initialization list for a constructor, you must explicitly name each direct base class, even if it is the only base class. -The following sample generates C2351: +## Example + +The following example generates C2351: ```cpp // C2351.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2352.md b/docs/error-messages/compiler-errors-1/compiler-error-c2352.md index 54c319840ee..8a5af21eae8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2352.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2352.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2352" title: "Compiler Error C2352" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2352" +ms.date: 11/04/2016 f1_keywords: ["C2352"] helpviewer_keywords: ["C2352"] -ms.assetid: 0efad8cb-659f-4b3e-8f6f-9f8ec44d345c --- # Compiler Error C2352 -'class::function' : illegal call of non-static member function +> 'class::function' : illegal call of non-static member function + +## Remarks A **`static`** member function called a nonstatic member function. Or, a nonstatic member function was called from outside the class as a static function. -The following sample generates C2352 and shows how to fix it: +## Examples + +The following example generates C2352 and shows how to fix it: ```cpp // C2352.cpp @@ -28,7 +31,7 @@ public: }; ``` -The following sample generates C2352 and shows how to fix it: +The following example generates C2352 and shows how to fix it: ```cpp // C2352b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2353.md b/docs/error-messages/compiler-errors-1/compiler-error-c2353.md index bbf3f1fdc64..50668f8cfe2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2353.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2353.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2353" title: "Compiler Error C2353" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2353" +ms.date: 11/04/2016 f1_keywords: ["C2353"] helpviewer_keywords: ["C2353"] -ms.assetid: d57f8f77-d9b1-4bba-a940-87ec269ad183 --- # Compiler Error C2353 -exception specification is not allowed +> exception specification is not allowed + +## Remarks Exception specifications are not allowed on member functions of managed classes. -The following sample generates C2353: +## Example + +The following example generates C2353: ```cpp // C2353.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2355.md b/docs/error-messages/compiler-errors-1/compiler-error-c2355.md index 3c2ec1586f3..abde37c99c8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2355.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2355.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2355" title: "Compiler Error C2355" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2355" +ms.date: 11/04/2016 f1_keywords: ["C2355"] helpviewer_keywords: ["C2355"] -ms.assetid: 0a947881-d61f-4f98-8409-32140f39500b --- # Compiler Error C2355 -'this' : can only be referenced inside non-static member functions or non-static data member initializers +> 'this' : can only be referenced inside non-static member functions or non-static data member initializers + +## Remarks The **`this`** pointer is valid only within non-static member functions or in non-static data member initializers. This error can result when the class scope of a member function definition outside of the class declaration is not properly qualified. The error can also occur when the **`this`** pointer is used in a function that is not declared in the class. To fix this issue, make sure the member function definition matches a member function declaration in the class, and that it is not declared static. For data member initializers, make sure the data member is not declared static. -The following sample generates C2355 and shows how to fix it: +## Example + +The following example generates C2355 and shows how to fix it: ```cpp // C2355.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2356.md b/docs/error-messages/compiler-errors-1/compiler-error-c2356.md index 6049b17292d..3ee44ce9730 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2356.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2356.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2356" title: "Compiler Error C2356" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2356" +ms.date: 11/04/2016 f1_keywords: ["C2356"] helpviewer_keywords: ["C2356"] -ms.assetid: 84d5a816-9a61-4d45-9978-38e485bbf767 --- # Compiler Error C2356 -initialization segment must not change during translation unit +> initialization segment must not change during translation unit + +## Remarks Possible causes: @@ -18,7 +19,9 @@ Possible causes: To resolve, move the segment initialization code to the beginning of the module. If multiple areas must be initialized, move them to separate modules. -The following sample generates C2356: +## Example + +The following example generates C2356: ```cpp // C2356.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2357.md b/docs/error-messages/compiler-errors-1/compiler-error-c2357.md index 0b06b9383d1..67b2a2901ce 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2357.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2357.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2357" title: "Compiler Error C2357" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2357" +ms.date: 11/04/2016 f1_keywords: ["C2357"] helpviewer_keywords: ["C2357"] -ms.assetid: d1083945-0ea2-4385-9e66-8c665978806c --- # Compiler Error C2357 -'identifier' : must be a function of type 'type' +> 'identifier' : must be a function of type 'type' + +## Remarks Your code declares a version of the `atexit` function that does not match the version declared internally by the compiler. Declare `atexit` as follows: @@ -18,7 +19,9 @@ int __cdecl atexit(void (__cdecl *)()); For more information, see [init_seg](../../preprocessor/init-seg.md). -The following sample generates C2357: +## Example + +The following example generates C2357: ```cpp // C2357.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2360.md b/docs/error-messages/compiler-errors-1/compiler-error-c2360.md index 3fc5204e7bb..58a393241ac 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2360.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2360.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2360" title: "Compiler Error C2360" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2360" +ms.date: 11/04/2016 f1_keywords: ["C2360"] helpviewer_keywords: ["C2360"] -ms.assetid: 51bfd2ee-8108-4777-aa93-148b9cebfa83 --- # Compiler Error C2360 -initialization of 'identifier' is skipped by 'case' label +> initialization of 'identifier' is skipped by 'case' label + +## Remarks The initialization of `identifier` can be skipped in a **`switch`** statement. You cannot jump past a declaration with an initializer unless the declaration is enclosed in a block. (Unless it is declared within a block, the variable is within scope until the end of the **`switch`** statement.) -The following sample generates C2360: +## Example + +The following example generates C2360: ```cpp // C2360.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2361.md b/docs/error-messages/compiler-errors-1/compiler-error-c2361.md index 6a7962c2d68..8c6743d7d40 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2361.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2361.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2361" title: "Compiler Error C2361" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2361" +ms.date: 11/04/2016 f1_keywords: ["C2361"] helpviewer_keywords: ["C2361"] -ms.assetid: efbdaeb9-891c-4f7d-97da-89088a8413f3 --- # Compiler Error C2361 -initialization of 'identifier' is skipped by 'default' label +> initialization of 'identifier' is skipped by 'default' label + +## Remarks The initialization of `identifier` can be skipped in a **`switch`** statement. You cannot jump past a declaration with an initializer unless the declaration is enclosed in a block. (Unless it is declared within a block, the variable is within scope until the end of the **`switch`** statement.) -The following sample generates C2361: +## Example + +The following example generates C2361: ```cpp // C2361.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2362.md b/docs/error-messages/compiler-errors-1/compiler-error-c2362.md index ee78fcd6f02..5691441c218 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2362.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2362.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2362" title: "Compiler Error C2362" -ms.date: "06/03/2019" +description: "Learn more about: Compiler Error C2362" +ms.date: 06/03/2019 f1_keywords: ["C2362"] helpviewer_keywords: ["C2362"] -ms.assetid: 7aafecbc-b3cf-45a6-9ec3-a17e3f222511 --- # Compiler Error C2362 > initialization of '*identifier*' is skipped by 'goto *label*' +## Remarks + When compiled by using [/Za](../../build/reference/za-ze-disable-language-extensions.md), a jump to the label prevents the identifier from being initialized. You can only jump past a declaration with an initializer if the declaration is enclosed in a block that isn't entered, or if the variable has already been initialized. -The following sample generates C2362: +## Example + +The following example generates C2362: ```cpp // C2362.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2364.md b/docs/error-messages/compiler-errors-1/compiler-error-c2364.md index 38050c2e713..8eeabc0bef7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2364.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2364.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2364" title: "Compiler Error C2364" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2364" +ms.date: 11/04/2016 f1_keywords: ["C2364"] helpviewer_keywords: ["C2364"] -ms.assetid: 4f550571-94b5-42ca-84cb-663fecbead44 --- # Compiler Error C2364 -'type': illegal type for custom attribute +> 'type': illegal type for custom attribute + +## Remarks Named arguments for custom attributes are limited to compile time constants. For example, integral types (int, char, etc.), System::Type^, and System::Object^. ## Example -The following sample generates C2364. +The following example generates C2364. ```cpp // c2364.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2365.md b/docs/error-messages/compiler-errors-1/compiler-error-c2365.md index 11c859cbdd7..7fd276bfe74 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2365.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2365.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2365" title: "Compiler Error C2365" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2365" +ms.date: 11/04/2016 f1_keywords: ["C2365"] helpviewer_keywords: ["C2365"] -ms.assetid: 35839b0b-4055-4b79-8957-b3a0871bdd02 --- # Compiler Error C2365 -'class member' : redefinition; previous definition was 'class member' +> 'class member' : redefinition; previous definition was 'class member' + +## Remarks You attempted to redefine a class member. -The following sample generates C2365. +## Example + +The following example generates C2365. ```cpp // C2365.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2368.md b/docs/error-messages/compiler-errors-1/compiler-error-c2368.md index a2f6d269f02..7711b7ae2c4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2368.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2368.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2368" title: "Compiler Error C2368" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2368" +ms.date: 11/04/2016 f1_keywords: ["C2368"] helpviewer_keywords: ["C2368"] -ms.assetid: a824626f-9fb5-453b-a3a4-da89d1e32218 --- # Compiler Error C2368 -'identifier' : redefinition; different allocation specifiers +> 'identifier' : redefinition; different allocation specifiers + +## Remarks The declaration and definition of the symbol specify different **`__declspec`** attributes. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2369.md b/docs/error-messages/compiler-errors-1/compiler-error-c2369.md index aab5f981a69..27a97bd4866 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2369.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2369.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2369" title: "Compiler Error C2369" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2369" +ms.date: 11/04/2016 f1_keywords: ["C2369"] helpviewer_keywords: ["C2369"] -ms.assetid: 2a3933f6-2313-40ff-800f-921b296fdbbf --- # Compiler Error C2369 -'array' : redefinition; different subscripts +> 'array' : redefinition; different subscripts + +## Remarks The array is already declared with a different subscript. -The following sample generates C2369: +## Example + +The following example generates C2369: ```cpp // C2369.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2370.md b/docs/error-messages/compiler-errors-1/compiler-error-c2370.md index 644e2724e52..256c331a639 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2370.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2370.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2370" title: "Compiler Error C2370" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2370" +ms.date: 11/04/2016 f1_keywords: ["C2370"] helpviewer_keywords: ["C2370"] -ms.assetid: 03403e8f-f393-47c4-bd25-5c1c7ea7d5cd --- # Compiler Error C2370 -'identifier' : redefinition; different storage class +> 'identifier' : redefinition; different storage class + +## Remarks The identifier is already declared with a different storage class. ## Examples -The following sample generates C2370: +The following example generates C2370: ```cpp // C2370.cpp @@ -24,7 +25,7 @@ static int i; // C2370 int i; // OK ``` -The following sample generates C2370: +The following example generates C2370: ```cpp // C2370b.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2371.md b/docs/error-messages/compiler-errors-1/compiler-error-c2371.md index 3574efe5302..bb5ba669bfc 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2371.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2371.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2371" title: "Compiler Error C2371" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2371" +ms.date: 11/04/2016 f1_keywords: ["C2371"] helpviewer_keywords: ["C2371"] -ms.assetid: d383993d-05ef-4e35-8129-3b58a6f7b7b7 --- # Compiler Error C2371 -'identifier' : redefinition; different basic types +> 'identifier' : redefinition; different basic types + +## Remarks The identifier is already declared. -The following sample generates C2371: +## Example + +The following example generates C2371: ```cpp // C2371.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2372.md b/docs/error-messages/compiler-errors-1/compiler-error-c2372.md index eac3e935a76..e893c5eb51e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2372.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2372.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2372" title: "Compiler Error C2372" -ms.date: "03/23/2020" +description: "Learn more about: Compiler Error C2372" +ms.date: 03/23/2020 f1_keywords: ["C2372"] helpviewer_keywords: ["C2372"] -ms.assetid: 406bea63-c8d3-4231-9d26-c70af6980840 --- # Compiler Error C2372 > '*identifier*' : redefinition; different types of indirection +## Remarks + The identifier is already defined with a different derived type. -The following sample generates C2372: +## Example + +The following example generates C2372: ```cpp // C2372.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2373.md b/docs/error-messages/compiler-errors-1/compiler-error-c2373.md index 2122dfb2982..1a2078adf1a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2373.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2373.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2373" title: "Compiler Error C2373" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2373" +ms.date: 11/04/2016 f1_keywords: ["C2373"] helpviewer_keywords: ["C2373"] -ms.assetid: 7a08bf0b-852d-48be-ba75-70df9f4b5951 --- # Compiler Error C2373 -'identifier' : redefinition; different type modifiers +> 'identifier' : redefinition; different type modifiers + +## Remarks The identifier is already defined with a different type modifier. -The following sample generates C2373: +## Example + +The following example generates C2373: ``` // C2373.h diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2374.md b/docs/error-messages/compiler-errors-1/compiler-error-c2374.md index 6d1b49420da..ae1d39df38d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2374.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2374.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2374" title: "Compiler Error C2374" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2374" +ms.date: 11/04/2016 f1_keywords: ["C2374"] helpviewer_keywords: ["C2374"] -ms.assetid: 73b51965-e91c-4e21-9732-f71c1449d22e --- # Compiler Error C2374 -'identifier' : redefinition; multiple initialization +> 'identifier' : redefinition; multiple initialization + +## Remarks The identifier is initialized more than once. -The following sample generates C2374: +## Example + +The following example generates C2374: ```cpp // C2374.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2375.md b/docs/error-messages/compiler-errors-1/compiler-error-c2375.md index 2a7da09bf72..a70339533a4 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2375.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2375.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2375" title: "Compiler Error C2375" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2375" +ms.date: 11/04/2016 f1_keywords: ["C2375"] helpviewer_keywords: ["C2375"] -ms.assetid: 193c5e8b-1b20-4928-8a02-8c1cddaf2a26 --- # Compiler Error C2375 -'function' : redefinition; different linkage +> 'function' : redefinition; different linkage + +## Remarks The function is already declared with a different linkage specifier. -The following sample generates C2375: +## Example + +The following example generates C2375: ```cpp // C2375.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2376.md b/docs/error-messages/compiler-errors-1/compiler-error-c2376.md index 6e089703c80..0cb73a4d373 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2376.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2376.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2376" title: "Compiler Error C2376" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2376" +ms.date: 11/04/2016 f1_keywords: ["C2376"] helpviewer_keywords: ["C2376"] -ms.assetid: 89423cf7-a24a-4bb3-a2ed-36a1ff8ba458 --- # Compiler Error C2376 -'function' : redefinition; different based allocation +> 'function' : redefinition; different based allocation + +## Remarks The function is already declared with a different based allocation. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2377.md b/docs/error-messages/compiler-errors-1/compiler-error-c2377.md index 409d365c347..5ed9e0b2649 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2377.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2377.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2377" title: "Compiler Error C2377" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2377" +ms.date: 11/04/2016 f1_keywords: ["C2377"] helpviewer_keywords: ["C2377"] -ms.assetid: f7660965-bf4c-4cd9-8307-1bd7016678a1 --- # Compiler Error C2377 -'identifier' : redefinition; typedef cannot be overloaded with any other symbol +> 'identifier' : redefinition; typedef cannot be overloaded with any other symbol + +## Remarks A **`typedef`** identifier is redefined. -The following sample generates C2377: +## Example + +The following example generates C2377: ```cpp // C2377.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2378.md b/docs/error-messages/compiler-errors-1/compiler-error-c2378.md index a42b65d5c7c..5005fb5f367 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2378.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2378.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2378" title: "Compiler Error C2378" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2378" +ms.date: 11/04/2016 f1_keywords: ["C2378"] helpviewer_keywords: ["C2378"] -ms.assetid: 507a91c6-ca72-48df-b3a4-2cf931c86806 --- # Compiler Error C2378 -'identifier' : redefinition; symbol cannot be overloaded with a typedef +> 'identifier' : redefinition; symbol cannot be overloaded with a typedef + +## Remarks The identifier was redefined as a **`typedef`**. -The following sample generates C2378: +## Example + +The following example generates C2378: ```cpp // C2378.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2379.md b/docs/error-messages/compiler-errors-1/compiler-error-c2379.md index f10e6b2a952..46c248af538 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2379.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2379.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2379" title: "Compiler Error C2379" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2379" +ms.date: 11/04/2016 f1_keywords: ["C2379"] helpviewer_keywords: ["C2379"] -ms.assetid: 37dc3015-a4af-4341-bbf3-da6150df7e51 --- # Compiler Error C2379 -formal parameter number has different type when promoted +> formal parameter number has different type when promoted + +## Remarks The type of the specified parameter is not compatible, through default promotions, with the type in a previous declaration. This is an error in ANSI C ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) and a warning with Microsoft extensions (**/Ze**). -The following sample generates C2379: +## Example + +The following example generates C2379: ```c // C2379.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2380.md b/docs/error-messages/compiler-errors-1/compiler-error-c2380.md index 4e2bdc50260..a0745e12c88 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2380.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2380.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2380" title: "Compiler Error C2380" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2380" +ms.date: 11/04/2016 f1_keywords: ["C2380"] helpviewer_keywords: ["C2380"] -ms.assetid: 717b1e6e-ddfe-4bac-a5f3-7f9a4dcb1572 --- # Compiler Error C2380 -type(s) preceding 'identifier' (constructor with return type, or illegal redefinition of current class-name?) +> type(s) preceding 'identifier' (constructor with return type, or illegal redefinition of current class-name?) + +## Remarks A constructor returns a value or redefines the class name. -The following sample generates C2326: +## Example + +The following example generates C2380: ```cpp // C2380.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2381.md b/docs/error-messages/compiler-errors-1/compiler-error-c2381.md index 86b2ef3426c..01ef31cff42 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2381.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2381.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2381" title: "Compiler Error C2381" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2381" +ms.date: 11/04/2016 f1_keywords: ["C2381"] helpviewer_keywords: ["C2381"] -ms.assetid: cc765f67-64ac-406f-93ef-ae7d548d58d7 --- # Compiler Error C2381 -'function' : redefinition; __declspec(noreturn) differs +> 'function' : redefinition; __declspec(noreturn) differs + +## Remarks A function was declared and then defined but the definition used the [noreturn](../../cpp/noreturn.md) **`__declspec`** modifier. The use of `noreturn` constitutes a redefinition of the function; the declaration and definition need to agree on the use of `noreturn`. -The following sample generates C2381: +## Example + +The following example generates C2381: ```cpp // C2381.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2382.md b/docs/error-messages/compiler-errors-1/compiler-error-c2382.md index 93ae496d52e..d4542d3dfb9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2382.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2382.md @@ -1,26 +1,25 @@ --- -description: "Learn more about: Compiler Error C2382" title: "Compiler Error C2382" +description: "Learn more about: Compiler Error C2382" ms.date: 12/10/2021 f1_keywords: ["C2382"] helpviewer_keywords: ["C2382"] -ms.assetid: 4d4436f9-d0d6-4bd0-b8ec-767b89adfb2f --- # Compiler Error C2382 > '*function*' : redefinition; different exception specifications -This error indicates that a function overload was attempted only on the [exception specification](../../cpp/exception-specifications-throw-cpp.md). - ## Remarks +This error indicates that a function overload was attempted only on the [exception specification](../../cpp/exception-specifications-throw-cpp.md). + By default, the compiler considers a `noexcept` specification to be equivalent to a `throw()` or `throw(some_type)` specification. Under [`/Za`](../../build/reference/za-ze-disable-language-extensions.md), this check is more strict. To resolve this issue, change all declarations and definitions of the function (or the specific function overload) to use the same exception specification. ## Example -The following sample generates C2382: +The following example generates C2382: ```cpp // C2382.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2383.md b/docs/error-messages/compiler-errors-1/compiler-error-c2383.md index 1e0db5c5781..07b1a0d9d32 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2383.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2383.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2383" title: "Compiler Error C2383" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2383" +ms.date: 11/04/2016 f1_keywords: ["C2383"] helpviewer_keywords: ["C2383"] -ms.assetid: 6696221d-879c-477a-a0f3-a6edc15fd3d7 --- # Compiler Error C2383 -'*symbol*' : default-arguments are not allowed on this symbol +> '*symbol*' : default-arguments are not allowed on this symbol + +## Remarks The C++ compiler does not allow default arguments on pointers to functions. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2384.md b/docs/error-messages/compiler-errors-1/compiler-error-c2384.md index ceff45b6302..19755c18cd9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2384.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2384.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Error C2384" title: "Compiler Error C2384" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2384" +ms.date: 11/04/2016 f1_keywords: ["C2384"] helpviewer_keywords: ["C2384"] -ms.assetid: 8145f7ad-31b1-406d-ac43-0d557feab635 --- # Compiler Error C2384 -'member' : cannot apply __declspec(thread) to a member of a managed or WinRT class +> 'member' : cannot apply __declspec(thread) to a member of a managed or WinRT class + +## Remarks The [thread](../../cpp/thread.md) **`__declspec`** modifier cannot be used on a member of a managed or Windows Runtime class. Static thread local storage in managed code can only be used for statically loaded DLLs—the DLL must be statically loaded when the process starts. Windows Runtime does not support thread local storage. +## Example + The following line generates C2384 and shows how to fix it in C++/CLI code: ```cpp 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 36b74b59467..1db2d3606f3 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,65 @@ --- -description: "Learn more about: Compiler Error C2385" title: "Compiler Error C2385" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2385" +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, +## Remarks -- Make the member unambiguous by providing a cast. +A member is inherited from more than one base type, making unqualified access to that member ambiguous. To resolve this error: -- 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 example 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-c2386.md b/docs/error-messages/compiler-errors-1/compiler-error-c2386.md index 012734bc39e..0c6ef1105bd 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2386.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2386.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2386" title: "Compiler Error C2386" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2386" +ms.date: 11/04/2016 f1_keywords: ["C2386"] helpviewer_keywords: ["C2386"] -ms.assetid: aaaa1284-34a0-4da2-8547-9fcbb559dae0 --- # Compiler Error C2386 -'symbol' : a symbol with this name already exists in the current scope +> 'symbol' : a symbol with this name already exists in the current scope + +## Remarks You tried to create a namespace alias, but the name you chose already exists. -The following sample generates C2386: +## Example + +The following example generates C2386: ```cpp // C2386.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2387.md b/docs/error-messages/compiler-errors-1/compiler-error-c2387.md index 9eb33692520..d14ff9cbb32 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2387.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2387.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2387" title: "Compiler Error C2387" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2387" +ms.date: 11/04/2016 f1_keywords: ["C2387"] helpviewer_keywords: ["C2387"] -ms.assetid: 6847b8e1-ffac-458d-ab88-0c92f72f2527 --- # Compiler Error C2387 -'type' : ambiguous base class +> 'type' : ambiguous base class + +## Remarks The compiler could not unambiguously resolve a function call because the function exists in more than one base class. To resolve this error, either remove one of the base classes from the inheritance, or explicitly qualify the function call. -The following sample generates C2387: +## Example + +The following example generates C2387: ```cpp // C2387.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2388.md b/docs/error-messages/compiler-errors-1/compiler-error-c2388.md index 28c5b68ad5b..8c10c31f398 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2388.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2388.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2388" title: "Compiler Error C2388" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2388" +ms.date: 11/04/2016 f1_keywords: ["C2388"] helpviewer_keywords: ["C2388"] -ms.assetid: 764ad2d7-cb04-425f-ba30-70989488c4a4 --- # Compiler Error C2388 -'symbol' : a symbol cannot be declared with both __declspec(appdomain) and \__declspec(process) +> 'symbol' : a symbol cannot be declared with both __declspec(appdomain) and \__declspec(process) + +## Remarks The `appdomain` and `process` **`__declspec`** modifiers cannot be used on the same symbol. The storage for a variable exists per process or per application domain. For more information, see [appdomain](../../cpp/appdomain.md) and [process](../../cpp/process.md). -The following sample generates C2388: +## Example + +The following example generates C2388: ```cpp // C2388.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2389.md b/docs/error-messages/compiler-errors-1/compiler-error-c2389.md index 6f13b7db12c..4c354f6d1f2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2389.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2389.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2389" title: "Compiler Error C2389" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2389" +ms.date: 11/04/2016 f1_keywords: ["C2389"] helpviewer_keywords: ["C2389"] -ms.assetid: 6122dc81-4ee3-49a5-a67d-d867808c9bac --- # Compiler Error C2389 -'operator' : illegal operand 'nullptr' +> 'operator' : illegal operand 'nullptr' + +## Remarks **`nullptr`** cannot be an operand. -The following sample generates C2389: +## Example + +The following example generates C2389: ```cpp // C2389.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2390.md b/docs/error-messages/compiler-errors-1/compiler-error-c2390.md index bab715650c8..8cb77912ec8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2390.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2390.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2390" title: "Compiler Error C2390" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2390" +ms.date: 11/04/2016 f1_keywords: ["C2390"] helpviewer_keywords: ["C2390"] -ms.assetid: 06b749ee-d072-4db1-b229-715f2c0728b5 --- # Compiler Error C2390 -'identifier' : incorrect storage class 'specifier' +> 'identifier' : incorrect storage class 'specifier' + +## Remarks The storage class is not valid for the global-scope identifier. The default storage class is used in place of the invalid class. @@ -22,7 +23,7 @@ Possible resolutions: ## Example -- The following sample generates C2390: +The following example generates C2390: ```cpp // C2390.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2391.md b/docs/error-messages/compiler-errors-1/compiler-error-c2391.md index b1895fb9ffc..283aeb7e762 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2391.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2391.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2391" title: "Compiler Error C2391" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2391" +ms.date: 11/04/2016 f1_keywords: ["C2391"] helpviewer_keywords: ["C2391"] -ms.assetid: 63a9c6b9-03cc-4517-885c-bdcd048643b3 --- # Compiler Error C2391 -'identifier' : 'friend' cannot be used during type definition +> 'identifier' : 'friend' cannot be used during type definition + +## Remarks The **`friend`** declaration includes a complete class declaration. A **`friend`** declaration can specify a member function or an elaborated type specifier, but not a complete class declaration. -The following sample generates C2326: +## Example + +The following example generates C2391: ```cpp // C2391.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2392.md b/docs/error-messages/compiler-errors-1/compiler-error-c2392.md index 81f7a1df2e4..70e6acb33cb 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2392.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2392.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2392" title: "Compiler Error C2392" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2392" +ms.date: 11/04/2016 f1_keywords: ["C2392"] helpviewer_keywords: ["C2392"] -ms.assetid: 98ced473-6383-46ed-b79c-21857d65dcb2 --- # Compiler Error C2392 -'method1' : covariant returns types are not supported in managed or WinRTtypes, otherwise 'method2' would be overridden +> 'method1' : covariant returns types are not supported in managed or WinRTtypes, otherwise 'method2' would be overridden + +## Remarks Covariant return types are not allowed for Windows Runtime member functions or when compiling with the [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) option. ## Example -The following sample generates C2392 and shows how to fix it. +The following example generates C2392 and shows how to fix it. ```cpp // C2392.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2393.md b/docs/error-messages/compiler-errors-1/compiler-error-c2393.md index 36d2868f7bf..fe80176868d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2393.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2393.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2393" title: "Compiler Error C2393" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2393" +ms.date: 11/04/2016 f1_keywords: ["C2393"] helpviewer_keywords: ["C2393"] -ms.assetid: 4bd95728-e813-4ce8-844a-c6ebe235ca82 --- # Compiler Error C2393 @@ -20,7 +19,7 @@ See [/clr (Common Language Runtime Compilation)](../../build/reference/clr-commo ## Example -The following sample generates C2393. To fix this issue, do not create a data segment. +The following example generates C2393. To fix this issue, do not create a data segment. ```cpp // C2393.cpp 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 14b86fb0447..58274a9b468 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2394.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2394.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2394" title: "Compiler Error C2394" -ms.date: "11/04/2016" +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' + +## Remarks 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. -The following sample generates C2394: +## Example + +The following example generates C2394: ```cpp // C2394.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2395.md b/docs/error-messages/compiler-errors-1/compiler-error-c2395.md index 214524e4d84..1d4a90319a9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2395.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2395.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2395" title: "Compiler Error C2395" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2395" +ms.date: 11/04/2016 f1_keywords: ["C2395"] helpviewer_keywords: ["C2395"] -ms.assetid: 2d9e3b28-8c2c-4f41-a57f-61ef88fc2af0 --- # Compiler Error C2395 -'your_type::operator'op'' : CLR or WinRT operator not valid. At least one parameter must be of the following types: 'T', 'T%', 'T&', 'T^', 'T^%', 'T^&', where T = 'your_type' +> 'your_type::operator'op'' : CLR or WinRT operator not valid. At least one parameter must be of the following types: 'T', 'T%', 'T&', 'T^', 'T^%', 'T^&', where T = 'your_type' + +## Remarks 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. -The following sample generates C2395 and shows how to fix it: +## Example + +The following example generates C2395 and shows how to fix it: ```cpp // C2395.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2396.md b/docs/error-messages/compiler-errors-1/compiler-error-c2396.md index 1bbd9657c83..8fa97066805 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2396.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2396.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2396" title: "Compiler Error C2396" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2396" +ms.date: 11/04/2016 f1_keywords: ["C2396"] helpviewer_keywords: ["C2396"] -ms.assetid: 1b515ef6-7af4-400f-b4ed-564313ea15f6 --- # Compiler Error C2396 -'your_type::operator'type'' : CLR or WinRT user-defined conversion functionnot valid. Must either convert from or convert to: 'T^', 'T^%', 'T^&', where T = 'your_type' +> 'your_type::operator'type'' : CLR or WinRT user-defined conversion functionnot valid. Must either convert from or convert to: 'T^', 'T^%', 'T^&', where T = 'your_type' + +## Remarks A conversion function in a Windows Runtime or managed type did not have at least one parameter whose type is the same as the type containing the conversion function. -The following sample generates C2396 and shows how to fix it: +## Example + +The following example generates C2396 and shows how to fix it: ```cpp // C2396.cpp 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 c73c5fe9b3e..8563bf8e4fe 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2397.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2397.md @@ -1,13 +1,15 @@ --- -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 -conversion from 'type_1' to 'type_2' requires a narrowing conversion +> conversion from 'type_1' to 'type_2' requires a narrowing conversion + +## Remarks An implicit narrowing conversion was found when using uniform initialization. @@ -15,26 +17,24 @@ 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: +## Example -``` -// C2397.cpp -- C++ narrowing conversion diagnostics -// Compile by using: cl /EHsc C2397.cpp -#include +The following example 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-c2400.md b/docs/error-messages/compiler-errors-1/compiler-error-c2400.md index 5cde822bb86..88ccb9b2eec 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2400.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2400.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2400" title: "Compiler Error C2400" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2400" +ms.date: 11/04/2016 f1_keywords: ["C2400"] helpviewer_keywords: ["C2400"] -ms.assetid: 1ba441ee-73f9-42a5-bfe9-fbeab93808eb --- # Compiler Error C2400 -inline assembler syntax error in 'context'; found 'token' +> inline assembler syntax error in 'context'; found 'token' + +## Remarks The token caused a syntax error in the specified context. -The following sample generates C2400: +## Example + +The following example generates C2400: ```cpp // C2400.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2401.md b/docs/error-messages/compiler-errors-1/compiler-error-c2401.md index 7a729d9dc0a..de3de95c5ea 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2401.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2401.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2401" title: "Compiler Error C2401" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2401" +ms.date: 11/04/2016 f1_keywords: ["C2401"] helpviewer_keywords: ["C2401"] -ms.assetid: 4c237b34-f771-4106-93e2-82dae337f1e2 --- # Compiler Error C2401 -'identifier' : register must be base in 'context' +> 'identifier' : register must be base in 'context' + +## Remarks The register used in an indirect memory operand must be a base register in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2402.md b/docs/error-messages/compiler-errors-1/compiler-error-c2402.md index 82a4fc4ea0e..18f1900886b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2402.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2402.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2402" title: "Compiler Error C2402" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2402" +ms.date: 11/04/2016 f1_keywords: ["C2402"] helpviewer_keywords: ["C2402"] -ms.assetid: 23fa63e1-ea9e-482f-be2e-a205c548ba69 --- # Compiler Error C2402 -'identifier' : register must be index in 'context' +> 'identifier' : register must be index in 'context' + +## Remarks The register used in an indirect memory operand must be an index register in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2403.md b/docs/error-messages/compiler-errors-1/compiler-error-c2403.md index c570c28dd6f..3526871fd49 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2403.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2403.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2403" title: "Compiler Error C2403" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2403" +ms.date: 11/04/2016 f1_keywords: ["C2403"] helpviewer_keywords: ["C2403"] -ms.assetid: add1f0ba-96b6-4df3-b53f-de1433d80c0c --- # Compiler Error C2403 -'identifier' : register must be base/index in 'context' +> 'identifier' : register must be base/index in 'context' + +## Remarks The register used in an indirect memory operand must be a base or index register in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2404.md b/docs/error-messages/compiler-errors-1/compiler-error-c2404.md index 220f381937d..3bb8a4dfb3a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2404.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2404.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2404" title: "Compiler Error C2404" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2404" +ms.date: 11/04/2016 f1_keywords: ["C2404"] helpviewer_keywords: ["C2404"] -ms.assetid: 51794d2f-404b-4d89-b3ea-fc5faa9c197d --- # Compiler Error C2404 -'identifier' : illegal register in 'context' +> 'identifier' : illegal register in 'context' + +## Remarks This register is invalid in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2405.md b/docs/error-messages/compiler-errors-1/compiler-error-c2405.md index f0e40a3d19c..e8fe1a73261 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2405.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2405.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2405" title: "Compiler Error C2405" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2405" +ms.date: 11/04/2016 f1_keywords: ["C2405"] helpviewer_keywords: ["C2405"] -ms.assetid: 14f6726d-e04b-4cce-8a85-4553fc38fcf7 --- # Compiler Error C2405 -illegal short forward reference with offset +> illegal short forward reference with offset + +## Remarks Short forward references must refer to a label only. An additional offset cannot be used. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2406.md b/docs/error-messages/compiler-errors-1/compiler-error-c2406.md index 6c58cf2252d..4b0c6c99dfa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2406.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2406.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2406" title: "Compiler Error C2406" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2406" +ms.date: 11/04/2016 f1_keywords: ["C2406"] helpviewer_keywords: ["C2406"] -ms.assetid: 9d3fbc4c-40bb-42c7-bfd7-7656c40e2065 --- # Compiler Error C2406 -'identifier' : name undefined in 'context' +> 'identifier' : name undefined in 'context' + +## Remarks An undefined identifier is used with the `SIZE`, `LENGTH`, or member-selection (.) operator. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2407.md b/docs/error-messages/compiler-errors-1/compiler-error-c2407.md index d6e33a822d3..f554591dff2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2407.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2407.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2407" title: "Compiler Error C2407" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2407" +ms.date: 11/04/2016 f1_keywords: ["C2407"] helpviewer_keywords: ["C2407"] -ms.assetid: faf38041-cf0f-4624-b6f8-30ce0e1efc1e --- # Compiler Error C2407 -illegal 'float' register in 'context' +> illegal 'float' register in 'context' + +## Remarks An `NDP` register was specified in an invalid context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2408.md b/docs/error-messages/compiler-errors-1/compiler-error-c2408.md index 0206666f921..d7f4e75d63f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2408.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2408.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2408" title: "Compiler Error C2408" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2408" +ms.date: 11/04/2016 f1_keywords: ["C2408"] helpviewer_keywords: ["C2408"] -ms.assetid: 3dc4881a-3c33-4c4e-b18e-a1f0e21ea931 --- # Compiler Error C2408 -illegal type on PTR operator in 'context' +> illegal type on PTR operator in 'context' + +## Remarks The first parameter of the `PTR` operator is not a legal type specification. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2409.md b/docs/error-messages/compiler-errors-1/compiler-error-c2409.md index 0cbc1b90364..f067880298e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2409.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2409.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2409" title: "Compiler Error C2409" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2409" +ms.date: 11/04/2016 f1_keywords: ["C2409"] helpviewer_keywords: ["C2409"] -ms.assetid: 5d4aa952-0752-4412-b5c2-050dde0636f4 --- # Compiler Error C2409 -illegal type used as operator in 'context' +> illegal type used as operator in 'context' + +## Remarks The type is not legal as an operator in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2410.md b/docs/error-messages/compiler-errors-1/compiler-error-c2410.md index 0e1729028bb..497da598ce8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2410.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2410.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2410" title: "Compiler Error C2410" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2410" +ms.date: 11/04/2016 f1_keywords: ["C2410"] helpviewer_keywords: ["C2410"] -ms.assetid: b69b2de1-56f3-4ebc-8913-04ac57ffe8a1 --- # Compiler Error C2410 -'identifier' : ambiguous member name in 'context' +> 'identifier' : ambiguous member name in 'context' + +## Remarks The identifier is a member of more than one structure or union in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2411.md b/docs/error-messages/compiler-errors-1/compiler-error-c2411.md index f2683b3a880..ddeca9c353c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2411.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2411.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2411" title: "Compiler Error C2411" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2411" +ms.date: 11/04/2016 f1_keywords: ["C2411"] helpviewer_keywords: ["C2411"] -ms.assetid: 453317d3-0629-4b42-b8ea-3a0b39698ca5 --- # Compiler Error C2411 -'identifier' : illegal struct/union member in 'context' +> 'identifier' : illegal struct/union member in 'context' ### To fix by checking the following possible causes diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2412.md b/docs/error-messages/compiler-errors-1/compiler-error-c2412.md index 7f80cf5952c..6b82d8b7cb2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2412.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2412.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2412" title: "Compiler Error C2412" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2412" +ms.date: 11/04/2016 f1_keywords: ["C2412"] helpviewer_keywords: ["C2412"] -ms.assetid: d1842b89-da09-4c35-89a1-84dc844a9f3e --- # Compiler Error C2412 -'label' : case-insensitive label redefined +> 'label' : case-insensitive label redefined + +## Remarks The label is defined more than once in the current function. Change the spelling of the label and its references. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2413.md b/docs/error-messages/compiler-errors-1/compiler-error-c2413.md index d48df5df859..8bda57669c2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2413.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2413.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2413" title: "Compiler Error C2413" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2413" +ms.date: 11/04/2016 f1_keywords: ["C2413"] helpviewer_keywords: ["C2413"] -ms.assetid: d0403952-f41e-4b21-840d-ab4e44171838 --- # Compiler Error C2413 -'token' : illegal align size +> 'token' : illegal align size + +## Remarks The size used with the `ALIGN` directive is missing or outside the valid range. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2414.md b/docs/error-messages/compiler-errors-1/compiler-error-c2414.md index 1a4d8639a07..d504db15d26 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2414.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2414.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2414" title: "Compiler Error C2414" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2414" +ms.date: 11/04/2016 f1_keywords: ["C2414"] helpviewer_keywords: ["C2414"] -ms.assetid: bbe94e03-862e-4990-b15e-544ae464727d --- # Compiler Error C2414 -illegal number of operands +> illegal number of operands ### To fix by checking the following possible causes diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2415.md b/docs/error-messages/compiler-errors-1/compiler-error-c2415.md index 73486e37299..d393c9ad04e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2415.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2415.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2415" title: "Compiler Error C2415" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2415" +ms.date: 11/04/2016 f1_keywords: ["C2415"] helpviewer_keywords: ["C2415"] -ms.assetid: f225c913-2bea-46b1-b096-3d358ac94a15 --- # Compiler Error C2415 -improper operand type +> improper operand type + +## Remarks The opcode does not use operands of this type. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2417.md b/docs/error-messages/compiler-errors-1/compiler-error-c2417.md index ad1ec1ba737..2627c37262a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2417.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2417.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2417" title: "Compiler Error C2417" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2417" +ms.date: 11/04/2016 f1_keywords: ["C2417"] helpviewer_keywords: ["C2417"] -ms.assetid: 8f42d7a8-5289-4f56-8404-23e5243274d2 --- # Compiler Error C2417 -divide by zero in 'context' +> divide by zero in 'context' + +## Remarks The parameter to the right of the division operator is zero in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2418.md b/docs/error-messages/compiler-errors-1/compiler-error-c2418.md index fd9efc9dec5..0134d570d69 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2418.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2418.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2418" title: "Compiler Error C2418" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2418" +ms.date: 11/04/2016 f1_keywords: ["C2418"] helpviewer_keywords: ["C2418"] -ms.assetid: 00e4690f-04a0-4159-b358-b1e0664102c1 --- # Compiler Error C2418 -cannot delete browser file: filename +> cannot delete browser file: filename + +## Remarks The compiler could not delete the browser file. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2419.md b/docs/error-messages/compiler-errors-1/compiler-error-c2419.md index 1785a274a9a..5b39fcc3e27 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2419.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2419.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2419" title: "Compiler Error C2419" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2419" +ms.date: 11/04/2016 f1_keywords: ["C2419"] helpviewer_keywords: ["C2419"] -ms.assetid: 51fe3195-34b6-445e-9f01-1e93e8714295 --- # Compiler Error C2419 -mod by zero in 'context' +> mod by zero in 'context' + +## Remarks The parameter to the right of the `MOD` operator is zero in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2420.md b/docs/error-messages/compiler-errors-1/compiler-error-c2420.md index 9f3d63e7ea4..cfe19fb2e68 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2420.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2420.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2420" title: "Compiler Error C2420" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2420" +ms.date: 11/04/2016 f1_keywords: ["C2420"] helpviewer_keywords: ["C2420"] -ms.assetid: cc11faab-a022-4702-ac8b-9864b916cfa2 --- # Compiler Error C2420 -'identifier' : illegal symbol in context +> 'identifier' : illegal symbol in context + +## Remarks The identifier is invalid in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2421.md b/docs/error-messages/compiler-errors-1/compiler-error-c2421.md index 7df9ea0208f..e55242b045f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2421.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2421.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2421" title: "Compiler Error C2421" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2421" +ms.date: 11/04/2016 f1_keywords: ["C2421"] helpviewer_keywords: ["C2421"] -ms.assetid: 0a9afb9f-60d8-4df7-b2ae-5c36e86df891 --- # Compiler Error C2421 -PTR operator used with register in 'context' +> PTR operator used with register in 'context' + +## Remarks The `PTR` operator cannot be used with a **`register`** operand. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2422.md b/docs/error-messages/compiler-errors-1/compiler-error-c2422.md index 3f23f41613c..5bec6948265 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2422.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2422.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2422" title: "Compiler Error C2422" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2422" +ms.date: 11/04/2016 f1_keywords: ["C2422"] helpviewer_keywords: ["C2422"] -ms.assetid: ef0ec302-4028-4778-b134-0b8cea4bcad9 --- # Compiler Error C2422 -illegal segment override in 'operand' +> illegal segment override in 'operand' + +## Remarks Inline assembly code incorrectly uses a segment override operator (colon) on an operand. Possible causes include: @@ -20,7 +21,9 @@ Inline assembly code incorrectly uses a segment override operator (colon) on an - The expression following the segment override operator is not an immediate operand or a memory operand. -The following sample generates C2422: +## Example + +The following example generates C2422: ```cpp // C2422.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2423.md b/docs/error-messages/compiler-errors-1/compiler-error-c2423.md index 24f2acbd023..903fb38c3e5 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2423.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2423.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2423" title: "Compiler Error C2423" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2423" +ms.date: 11/04/2016 f1_keywords: ["C2423"] helpviewer_keywords: ["C2423"] -ms.assetid: 8797fb8b-b58b-4add-b6e6-2a9a3cd9084d --- # Compiler Error C2423 -'number' : illegal scale +> 'number' : illegal scale + +## Remarks Inline assembly code uses a number other than 1, 2, 4, or 8 to scale a register. -The following sample generates C2423: +## Example + +The following example generates C2423: ```cpp // C2423.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2424.md b/docs/error-messages/compiler-errors-1/compiler-error-c2424.md index 3e87ba06f89..8828b961d38 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2424.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2424.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2424" title: "Compiler Error C2424" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2424" +ms.date: 11/04/2016 f1_keywords: ["C2424"] helpviewer_keywords: ["C2424"] -ms.assetid: 03613746-a324-4b8b-94c0-424e8b0aae94 --- # Compiler Error C2424 -'token' : improper expression in 'context' +> 'token' : improper expression in 'context' + +## Remarks The token forms part of an incorrect expression in this context. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2425.md b/docs/error-messages/compiler-errors-1/compiler-error-c2425.md index a87f7c098d7..27430083843 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2425.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2425.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2425" title: "Compiler Error C2425" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2425" +ms.date: 11/04/2016 f1_keywords: ["C2425"] helpviewer_keywords: ["C2425"] -ms.assetid: 0ce59404-9aff-4e01-aa8d-27d23e92eb30 --- # Compiler Error C2425 -'token' :non-constant expression in 'context' +> 'token' :non-constant expression in 'context' + +## Remarks The token forms part of a non-constant expression in this context. To fix this issue, replace the token with a constant literal or with a calculation. -The following sample generates C2425: +## Example + +The following example generates C2425: ```cpp // C2425.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2426.md b/docs/error-messages/compiler-errors-1/compiler-error-c2426.md index fd4668b17ba..8f4bc8c7f20 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2426.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2426.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2426" title: "Compiler Error C2426" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2426" +ms.date: 11/04/2016 f1_keywords: ["C2426"] helpviewer_keywords: ["C2426"] -ms.assetid: 3428aeed-3f78-4675-9bc4-5b72f50eaaf6 --- # Compiler Error C2426 -'token' : illegal operator in 'context' +> 'token' : illegal operator in 'context' + +## Remarks The token cannot be used as an operator in this context. Index operators, for example, cannot be nested. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2427.md b/docs/error-messages/compiler-errors-1/compiler-error-c2427.md index 8d570e65b0a..bd48ac4560f 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2427.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2427.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2427" title: "Compiler Error C2427" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2427" +ms.date: 11/04/2016 f1_keywords: ["C2427"] helpviewer_keywords: ["C2427"] -ms.assetid: a7d421af-6180-40b4-b7a6-9f3bc7dfaaf9 --- # Compiler Error C2427 -'class' : cannot define class in this scope +> 'class' : cannot define class in this scope + +## Remarks An attempt was made to define a nested class, but the nested class is a member of a base class, not the most containing class. -The following sample generates C2427: +## Example + +The following example generates C2427: ```cpp // C2427.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2428.md b/docs/error-messages/compiler-errors-1/compiler-error-c2428.md index d58660dd89f..285e59c87ec 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2428.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2428.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2428" title: "Compiler Error C2428" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2428" +ms.date: 11/04/2016 f1_keywords: ["C2428"] helpviewer_keywords: ["C2428"] -ms.assetid: 74aa5714-e930-4f9e-9061-68ccce7f0d38 --- # Compiler Error C2428 -'operation' : not allowed on operand of type 'bool' +> 'operation' : not allowed on operand of type 'bool' + +## Remarks You cannot apply a decrement operator to objects of type **`bool`**. -The following sample generates C2428: +## Example + +The following example generates C2428: ```cpp // C2428.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2429.md b/docs/error-messages/compiler-errors-1/compiler-error-c2429.md index 6b465a254d7..5e90b4c64ca 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2429.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2429.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C2429" title: "Compiler Error C2429" -ms.date: "11/16/2017" +description: "Learn more about: Compiler Error C2429" +ms.date: 11/16/2017 f1_keywords: ["C2429"] helpviewer_keywords: ["C2429"] -ms.assetid: 57ff6df9-5cf1-49f3-8bd8-4e550dfd65a0 --- # Compiler Error C2429 > '*language feature*' requires compiler flag '*compiler option*' +## Remarks + The language feature requires a specific compiler option for support. +## Example + The error **C2429: language feature 'nested-namespace-definition' requires compiler flag '/std:c++17'** is generated if you try to define a *compound namespace*, a namespace that contains one or more scope-nested namespace names, starting in Visual Studio 2015 Update 5. (In Visual Studio 2017 version 15.3, the **`/std:c++latest`** switch is required.) Compound namespace definitions are not allowed in C++ prior to C++17. The compiler supports compound namespace definitions when the [`/std:c++17`](../../build/reference/std-specify-language-standard-version.md) compiler option is specified: ```cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2430.md b/docs/error-messages/compiler-errors-1/compiler-error-c2430.md index 93fb29b3ba4..931d37287a6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2430.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2430.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2430" title: "Compiler Error C2430" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2430" +ms.date: 11/04/2016 f1_keywords: ["C2430"] helpviewer_keywords: ["C2430"] -ms.assetid: 07c20f76-63e1-4d22-b2a9-98b0d45c5cac --- # Compiler Error C2430 -more than one index register in 'identifier' +> more than one index register in 'identifier' + +## Remarks More than one register is scaled. The compiler supports scaled indexing, but you can only scale one register. ## Example -The following sample generates C2430. +The following example generates C2430. ```cpp // C2430.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2431.md b/docs/error-messages/compiler-errors-1/compiler-error-c2431.md index bf087591be9..923f9f17e1c 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2431.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2431.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2431" title: "Compiler Error C2431" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2431" +ms.date: 11/04/2016 f1_keywords: ["C2431"] helpviewer_keywords: ["C2431"] -ms.assetid: 88a5b648-c89f-47d1-a20e-63231ab4f0f7 --- # Compiler Error C2431 -illegal index register in 'identifier' +> illegal index register in 'identifier' + +## Remarks The ESP register is scaled or used as both index and base register. The SIB encoding for the x86 processor does not allow either. -The following sample generates C2431: +## Example + +The following example generates C2431: ```cpp // C2431.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2432.md b/docs/error-messages/compiler-errors-1/compiler-error-c2432.md index 03d4ba54d10..ef91964904e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2432.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2432.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2432" title: "Compiler Error C2432" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2432" +ms.date: 11/04/2016 f1_keywords: ["C2432"] helpviewer_keywords: ["C2432"] -ms.assetid: 0e3326e8-cab1-45a5-b48d-61edd33793e8 --- # Compiler Error C2432 -illegal reference to 16-bit data in 'identifier' +> illegal reference to 16-bit data in 'identifier' + +## Remarks A 16-bit register is used as an index or base register. The compiler does not support referencing 16-bit data. 16-bit registers cannot be used as index or base registers when compiling for 32-bit code. -The following sample generates C2432: +## Example + +The following example generates C2432: ```cpp // C2432.cpp 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 614e07b1be1..64fa90a70b1 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,26 @@ --- -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 + +## Remarks 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-c2434.md b/docs/error-messages/compiler-errors-1/compiler-error-c2434.md index 7a9cba1f7d9..f48832f1467 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2434.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2434.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2434" title: "Compiler Error C2434" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2434" +ms.date: 11/04/2016 f1_keywords: ["C2434"] helpviewer_keywords: ["C2434"] -ms.assetid: 01329e26-7c74-4219-b74f-69e3a40c9738 --- # Compiler Error C2434 @@ -18,7 +17,7 @@ It is not possible to dynamically initialize a per-process variable under **/clr ## Example -The following sample generates C2434. To fix this issue, use constants to initialize `process` variables. +The following example generates C2434. To fix this issue, use constants to initialize `process` variables. ```cpp // C2434.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2435.md b/docs/error-messages/compiler-errors-1/compiler-error-c2435.md index 90b82057ad1..6522c4a0255 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2435.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2435.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2435" title: "Compiler Error C2435" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2435" +ms.date: 11/04/2016 f1_keywords: ["C2435"] helpviewer_keywords: ["C2435"] -ms.assetid: be6aa8f8-579b-42ea-bdd8-2d01393646ad --- # Compiler Error C2435 @@ -20,7 +19,7 @@ For more information, see [appdomain](../../cpp/appdomain.md) and [process](../. ## Example -The following sample generates C2435: +The following example generates C2435: ```cpp // C2435.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2436.md b/docs/error-messages/compiler-errors-1/compiler-error-c2436.md index 2c21782820b..8b1879a76d8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2436.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2436.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2436" title: "Compiler Error C2436" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2436" +ms.date: 11/04/2016 f1_keywords: ["C2436"] helpviewer_keywords: ["C2436"] -ms.assetid: ca4cc813-bc1d-4c0a-9a2c-3a5fe673d084 --- # Compiler Error C2436 -'identifier' : member function or nested class in constructor initializer list +> 'identifier' : member function or nested class in constructor initializer list + +## Remarks Member functions or local classes in the constructor initializer list cannot be initialized. -The following sample generates C2436: +## Example + +The following example generates C2436: ```cpp // C2436.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2437.md b/docs/error-messages/compiler-errors-1/compiler-error-c2437.md index ad2838f1954..07b62af2655 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2437.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2437.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2437" title: "Compiler Error C2437" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2437" +ms.date: 11/04/2016 f1_keywords: ["C2437"] helpviewer_keywords: ["C2437"] -ms.assetid: 2d2b3c6c-856a-4b27-ae10-64813b3e5483 --- # Compiler Error C2437 -'identifier' : already initialized +> 'identifier' : already initialized + +## Remarks An object can be initialized only once. -The following sample generates C2437: +## Example + +The following example generates C2437: ```cpp // C2437.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2438.md b/docs/error-messages/compiler-errors-1/compiler-error-c2438.md index 5c50bbcf063..2a0e207e1df 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2438.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2438.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2438" title: "Compiler Error C2438" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2438" +ms.date: 11/04/2016 f1_keywords: ["C2438"] helpviewer_keywords: ["C2438"] -ms.assetid: 3a0ab3ba-d0e4-4d8f-971d-e503397cc827 --- # Compiler Error C2438 -'identifier' : cannot initialize static class data via constructor +> 'identifier' : cannot initialize static class data via constructor + +## Remarks A constructor is used to initialize a static member of a class. Static members must be initialized in a definition outside the class declaration. -The following sample generates C2438: +## Example + +The following example generates C2438: ```cpp // C2438.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2439.md b/docs/error-messages/compiler-errors-1/compiler-error-c2439.md index 3afca77e01e..37a5523bea6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2439.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2439.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2439" title: "Compiler Error C2439" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2439" +ms.date: 11/04/2016 f1_keywords: ["C2439"] helpviewer_keywords: ["C2439"] -ms.assetid: 3c5dbe5c-b7d3-4bb0-8619-92f6e280461e --- # Compiler Error C2439 -'identifier' : member could not be initialized +> 'identifier' : member could not be initialized + +## Remarks A class, structure, or union member cannot be initialized. 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 218b5f7a3d3..b1416ad8096 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2440.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2440.md @@ -1,28 +1,27 @@ --- -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. - ## Remarks +The compiler can't implicitly convert from *`type1`* to *`type2`*, or can't use the specified cast or conversion operator. + The compiler generates C2440 when it can't convert from one type to another, either implicitly or by using the specified cast or conversion operator. There are many ways to generate this error. We've listed some common ones in the Examples section. ## Examples ### C++ string literals are `const` -C2440 can be caused if you attempt to initialize a non-const `char*` (or `wchar_t*`) by using a string literal in C++ code, when the compiler conformance option [`/Zc:strictStrings`](../../build/reference/zc-strictstrings-disable-string-literal-type-conversion.md) is set. In C, the type of a string literal is array of **`char`**, but in C++, it's array of `const char`. This sample generates C2440: +C2440 can be caused if you attempt to initialize a non-const `char*` (or `wchar_t*`) by using a string literal in C++ code, when the compiler conformance option [`/Zc:strictStrings`](../../build/reference/zc-strictstrings-disable-string-literal-type-conversion.md) is set. In C, the type of a string literal is array of **`char`**, but in C++, it's array of `const char`. This example generates C2440: ```cpp // C2440s.cpp @@ -41,7 +40,7 @@ int main() { ### C++20 `u8` literals are `const char8_t` -In C++20 or under [`/Zc:char8_t`](../../build/reference/zc-char8-t.md), a UTF-8 literal character or string (such as `u8'a'` or `u8"String"`) is of type `const char8_t` or `const char8_t[N]`, respectively. This sample shows how compiler behavior changes between C++17 and C++20: +In C++20 or under [`/Zc:char8_t`](../../build/reference/zc-char8-t.md), a UTF-8 literal character or string (such as `u8'a'` or `u8"String"`) is of type `const char8_t` or `const char8_t[N]`, respectively. This example shows how compiler behavior changes between C++17 and C++20: ```cpp // C2440u8.cpp @@ -61,7 +60,7 @@ int main() { ### Pointer to member -You may see C2440 if you attempt to convert a pointer to member to `void*`. The next sample generates C2440: +You may see C2440 if you attempt to convert a pointer to member to `void*`. The next example generates C2440: ```cpp // C2440.cpp @@ -84,7 +83,7 @@ public: ### Cast of undefined type -The compiler emits C2440 if you attempt to cast from a type that's only forward declared but not defined. This sample generates C2440: +The compiler emits C2440 if you attempt to cast from a type that's only forward declared but not defined. This example generates C2440: ```cpp // c2440a.cpp @@ -99,7 +98,7 @@ Base * func(Derived * d) { ### Incompatible calling convention -The C2440 errors on lines 15 and 16 of the next sample are qualified with the `Incompatible calling conventions for UDT return value` message. A *UDT* is a user-defined type, such as a class, struct, or union. These kinds of incompatibility errors are caused when the calling convention of a UDT specified in the return type of a forward declaration conflicts with the actual calling convention of the UDT and when a function pointer is involved. +The C2440 errors on lines 15 and 16 of the next example are qualified with the `Incompatible calling conventions for UDT return value` message. A *UDT* is a user-defined type, such as a class, struct, or union. These kinds of incompatibility errors are caused when the calling convention of a UDT specified in the return type of a forward declaration conflicts with the actual calling convention of the UDT and when a function pointer is involved. In the example, first there are forward declarations for a struct and for a function that returns the struct. The compiler assumes that the struct uses the C++ calling convention. Next is the struct definition, which uses the C calling convention by default. Because the compiler doesn't know the calling convention of the struct until it finishes reading the entire struct, the calling convention for the struct in the return type of `get_c2` is also assumed to be C++. @@ -164,7 +163,7 @@ int main() { ### User-defined conversions -C2440 can also occur for an incorrect use of a user-defined conversion. For example, when a conversion operator has been defined as **`explicit`**, the compiler can't use it in an implicit conversion. For more information about user-defined conversions, see [User-Defined Conversions (C++/CLI)](../../dotnet/user-defined-conversions-cpp-cli.md)). This sample generates C2440: +C2440 can also occur for an incorrect use of a user-defined conversion. For example, when a conversion operator has been defined as **`explicit`**, the compiler can't use it in an implicit conversion. For more information about user-defined conversions, see [User-Defined Conversions (C++/CLI)](../../dotnet/user-defined-conversions-cpp-cli.md)). This example generates C2440: ```cpp // C2440d.cpp @@ -188,7 +187,7 @@ int main() { ### `System::Array` creation -C2440 can also occur if you try to create an instance of an array in C++/CLI whose type is a . For more information, see [Arrays](../../extensions/arrays-cpp-component-extensions.md). The next sample generates C2440: +C2440 can also occur if you try to create an instance of an array in C++/CLI whose type is a . For more information, see [Arrays](../../extensions/arrays-cpp-component-extensions.md). The next example generates C2440: ```cpp // C2440e.cpp @@ -203,7 +202,7 @@ int main() { ### Attributes -C2440 can also occur because of changes in the attributes feature. The following sample generates C2440. +C2440 can also occur because of changes in the attributes feature. The following example generates C2440. ```cpp // c2440f.cpp @@ -219,7 +218,7 @@ The Microsoft C++ compiler no longer allows the [`const_cast` operator](../../cp To resolve this C2440, use the correct cast operator. For more information, see [Casting operators](../../cpp/casting-operators.md). -This sample generates C2440: +This example generates C2440: ```cpp // c2440g.cpp @@ -238,7 +237,7 @@ int main() { C2440 can occur because of conformance changes to the compiler in Visual Studio 2015 Update 3. Previously, the compiler incorrectly treated certain distinct expressions as the same type when identifying a template match for a **`static_cast`** operation. Now the compiler distinguishes the types correctly, and code that relied on the previous **`static_cast`** behavior is broken. To fix this issue, change the template argument to match the template parameter type, or use a **`reinterpret_cast`** or C-style cast. -This sample generates C2440: +This example generates C2440: ```cpp // c2440h.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2441.md b/docs/error-messages/compiler-errors-1/compiler-error-c2441.md index 6ec4ce06501..e82e9e4cb04 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2441.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2441.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2441" title: "Compiler Error C2441" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2441" +ms.date: 11/04/2016 f1_keywords: ["C2441"] helpviewer_keywords: ["C2441"] -ms.assetid: ffbd6573-777a-48dd-892f-5cf4a758dcab --- # Compiler Error C2441 @@ -22,7 +21,7 @@ For more information, see [process](../../cpp/process.md) and [/clr (Common Lang ## Example -The following sample generates C2441. +The following example generates C2441. ```cpp // C2441.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2443.md b/docs/error-messages/compiler-errors-1/compiler-error-c2443.md index 15026511214..2246220c488 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2443.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2443.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2443" title: "Compiler Error C2443" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2443" +ms.date: 11/04/2016 f1_keywords: ["C2443"] helpviewer_keywords: ["C2443"] -ms.assetid: 315330d5-24bc-4193-a531-0642095be58f --- # Compiler Error C2443 -operand size conflict +> operand size conflict + +## Remarks The instruction requires operands to be the same size. -The following sample generates C2443: +## Example + +The following example generates C2443: ```cpp // C2443.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2444.md b/docs/error-messages/compiler-errors-1/compiler-error-c2444.md index 94cb7948fa9..8fbffad64a9 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2444.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2444.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2444" title: "Compiler Error C2444" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2444" +ms.date: 11/04/2016 f1_keywords: ["C2444"] helpviewer_keywords: ["C2444"] -ms.assetid: 6339ed82-caad-45d3-a8ff-6c746589fd03 --- # Compiler Error C2444 -'identifier' : used ANSI prototype, found 'type', expected '{' or ';' +> 'identifier' : used ANSI prototype, found 'type', expected '{' or ';' + +## Remarks The function prototype is followed by a type. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2446.md b/docs/error-messages/compiler-errors-1/compiler-error-c2446.md index de76e6c65ac..0f1951562ed 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2446.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2446.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2446" title: "Compiler Error C2446" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2446" +ms.date: 11/04/2016 f1_keywords: ["C2446"] helpviewer_keywords: ["C2446"] -ms.assetid: 4f70dd11-6baf-4b92-9a08-f88f65ffa199 --- # Compiler Error C2446 -'operator' : no conversion from 'type1' to 'type2' +> 'operator' : no conversion from 'type1' to 'type2' + +## Remarks The compiler cannot convert `type1` to `type2`. The conversion may not make sense because it violates C/C++ semantics. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2447.md b/docs/error-messages/compiler-errors-1/compiler-error-c2447.md index e88e1565f63..7191d5ad851 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2447.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2447.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2447" title: "Compiler Error C2447" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2447" +ms.date: 11/04/2016 f1_keywords: ["C2447"] helpviewer_keywords: ["C2447"] -ms.assetid: d1bd6e9a-ee42-4510-ae5e-6b0378f7b931 --- # Compiler Error C2447 -'{' : missing function header (old-style formal list?) +> '{' : missing function header (old-style formal list?) + +## Remarks The compiler encountered an unexpected open brace at global scope. In most cases, this is caused by a badly-formed function header, a misplaced declaration, or a stray semi-colon. To resolve this issue, verify that the open brace follows a correctly-formed function header, and is not preceded by a declaration or a stray semi-colon. This error can also be caused by an old-style C-language formal argument list. To resolve this issue, refactor the argument list to use modern style—that is, enclosed in parentheses. -The following sample generates C2447: +## Example + +The following example generates C2447: ```cpp // C2447.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2448.md b/docs/error-messages/compiler-errors-1/compiler-error-c2448.md index 49c7aeafb64..05ae565e92e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2448.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2448.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2448" title: "Compiler Error C2448" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2448" +ms.date: 11/04/2016 f1_keywords: ["C2448"] helpviewer_keywords: ["C2448"] -ms.assetid: e255df3c-f861-4b4d-a193-8768cef061a5 --- # Compiler Error C2448 -'identifier' : function-style initializer appears to be a function definition +> 'identifier' : function-style initializer appears to be a function definition + +## Remarks The function definition is incorrect. This error can be caused by an old-style C-language formal list. -The following sample generates C2448: +## Example + +The following example generates C2448: ```cpp // C2448.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2449.md b/docs/error-messages/compiler-errors-1/compiler-error-c2449.md index 938093971e8..b99392c66d8 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2449.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2449.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2449" title: "Compiler Error C2449" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2449" +ms.date: 11/04/2016 f1_keywords: ["C2449"] helpviewer_keywords: ["C2449"] -ms.assetid: 544bf0b6-daa0-40e8-9f21-8e583d472a2d --- # Compiler Error C2449 -found '{' at file scope (missing function header?) +> found '{' at file scope (missing function header?) + +## Remarks An open brace occurs at file scope. This error can be caused by a semicolon between a function header and the opening brace of the function definition. -The following sample generates C2499: +## Example + +The following example generates C2449: ```c // C2449.c 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 6a4d09afad1..61dc7caa663 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2450.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2450.md @@ -1,38 +1,44 @@ --- -description: "Learn more about: Compiler Error C2450" title: "Compiler Error C2450" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2450" +ms.date: 11/04/2016 f1_keywords: ["C2450"] helpviewer_keywords: ["C2450"] -ms.assetid: 929f1c06-8774-468b-be2a-f428757875a2 --- # Compiler Error C2450 -switch expression of type 'type' is illegal +> switch expression of type 'type' is illegal + +## Remarks The **`switch`** expression evaluates to an invalid type. It must evaluate to an integer type or a class type with unambiguous conversion to an integer type. If it evaluates to a user-defined type, you must supply a conversion operator. -The following sample generates C2450: +## Example + +The following example 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-c2451.md b/docs/error-messages/compiler-errors-1/compiler-error-c2451.md index cc99c291bb0..0d266179dbd 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2451.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2451.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2451" title: "Compiler Error C2451" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2451" +ms.date: 11/04/2016 f1_keywords: ["C2451"] helpviewer_keywords: ["C2451"] -ms.assetid: a64c93a5-ab8d-4d39-ae57-9ee7ef803036 --- # Compiler Error C2451 -conditional expression of type 'type' is illegal +> conditional expression of type 'type' is illegal + +## Remarks The conditional expression evaluates to an integer type. -The following sample generates C2451: +## Example + +The following example generates C2451: ```cpp // C2451.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2452.md b/docs/error-messages/compiler-errors-1/compiler-error-c2452.md index f16f583de17..fabb98fbc3e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2452.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2452.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2452" title: "Compiler Error C2452" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2452" +ms.date: 11/04/2016 f1_keywords: ["C2452"] helpviewer_keywords: ["C2452"] -ms.assetid: a4ec7642-6660-4c7a-9866-853d1cc67daf --- # Compiler Error C2452 -'type' : invalid source type for safe_cast +> 'type' : invalid source type for safe_cast + +## Remarks The source type for [safe_cast](../../extensions/safe-cast-cpp-component-extensions.md) was not valid. For example, all types in a `safe_cast` operation must be CLR types. -The following sample generates C2452: +## Example + +The following example generates C2452: ```cpp // C2452.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2457.md b/docs/error-messages/compiler-errors-1/compiler-error-c2457.md index a60da33b7bb..55e9609401a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2457.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2457.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2457" title: "Compiler Error C2457" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2457" +ms.date: 11/04/2016 f1_keywords: ["C2457"] helpviewer_keywords: ["C2457"] -ms.assetid: 347e169d-23ad-434f-8836-5b09b53980ff --- # Compiler Error C2457 > '*macro*': predefined macro cannot appear outside of a function body +## Remarks + You attempted to use a predefined macro, such as [`__FUNCTION__`](../../preprocessor/predefined-macros.md), in a global space. ## Example -The following sample generates C2457 and also shows correct usage: +The following example generates C2457 and also shows correct usage: ```cpp // C2457.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2458.md b/docs/error-messages/compiler-errors-1/compiler-error-c2458.md index ec96c8970fb..e87f8b60f8d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2458.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2458.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2458" title: "Compiler Error C2458" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2458" +ms.date: 11/04/2016 f1_keywords: ["C2458"] helpviewer_keywords: ["C2458"] -ms.assetid: ed21901f-1067-42f5-b275-19b480decf5c --- # Compiler Error C2458 -'identifier' : redefinition within definition +> 'identifier' : redefinition within definition + +## Remarks A class, structure, union, or enumeration is redefined in its own declaration. -The following sample generates C2458: +## Example + +The following example generates C2458: ```cpp // C2458.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2459.md b/docs/error-messages/compiler-errors-1/compiler-error-c2459.md index 635f08cf2e5..135799238c3 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2459.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2459.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2459" title: "Compiler Error C2459" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2459" +ms.date: 11/04/2016 f1_keywords: ["C2459"] helpviewer_keywords: ["C2459"] -ms.assetid: 81e29f4c-5b60-40fb-9557-1cdc630d77e8 --- # Compiler Error C2459 -'identifier' : is being defined; cannot add as an anonymous member +> 'identifier' : is being defined; cannot add as an anonymous member + +## Remarks A class, structure, or union is redefined in its own scope by a member of an anonymous union. -The following sample generates C2459: +## Example + +The following example generates C2459: ```cpp // C2459.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2460.md b/docs/error-messages/compiler-errors-1/compiler-error-c2460.md index e6e7bdd164b..6f13975fc47 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2460.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2460.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2460" title: "Compiler Error C2460" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2460" +ms.date: 11/04/2016 f1_keywords: ["C2460"] helpviewer_keywords: ["C2460"] -ms.assetid: d969fca9-3ac5-4e4e-88fc-df05510e2093 --- # Compiler Error C2460 -'identifier1' : uses 'identifier2', which is being defined +> 'identifier1' : uses 'identifier2', which is being defined + +## Remarks A class or structure (`identifier2`) is declared as a member of itself (`identifier1`). Recursive definitions of classes and structures are not allowed. -The following sample generates C2460: +## Example + +The following example generates C2460: ```cpp // C2460.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2461.md b/docs/error-messages/compiler-errors-1/compiler-error-c2461.md index 4d3aac6503f..7b4d94ac41d 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2461.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2461.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C2461" title: "Compiler Error C2461" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2461" +ms.date: 11/04/2016 f1_keywords: ["C2461"] helpviewer_keywords: ["C2461"] -ms.assetid: e64ba651-f441-4fdb-b5cb-4209bbbe4db4 --- # Compiler Error C2461 > '*class*' : constructor syntax missing formal parameters +## Remarks + The constructor for the class does not specify any formal parameters. The declaration of a constructor must specify a formal parameter list. The list can be empty. To fix this issue, add a pair of parentheses after the declaration of *class*::**class*. ## Example -The following sample shows how to fix C2461: +The following example shows how to fix C2461: ```cpp // C2461.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2462.md b/docs/error-messages/compiler-errors-1/compiler-error-c2462.md index b374ec31368..baad0121506 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2462.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2462.md @@ -1,22 +1,26 @@ --- -description: "Learn more about: Compiler Error C2462" title: "Compiler Error C2462" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2462" +ms.date: 11/04/2016 f1_keywords: ["C2462"] helpviewer_keywords: ["C2462"] -ms.assetid: a8601bf8-f5ce-41de-9117-e2632bd4996b --- # Compiler Error C2462 -'identifier' : cannot define a type in a 'new-expression' +> 'identifier' : cannot define a type in a 'new-expression' + +## Remarks You cannot define a type in the operand field of the **`new`** operator. Put the type definition in a separate statement. -The following sample generates C2462: +## Example + +The following example generates C2462: ```cpp // C2462.cpp -int main() { +int main() +{ new struct S { int i; }; // C2462 } ``` diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2464.md b/docs/error-messages/compiler-errors-1/compiler-error-c2464.md index 15645af89f1..10a9a5155f1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2464.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2464.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2464" title: "Compiler Error C2464" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2464" +ms.date: 11/04/2016 f1_keywords: ["C2464"] helpviewer_keywords: ["C2464"] -ms.assetid: ace953d6-b414-49ee-bfef-90578a8da00c --- # Compiler Error C2464 -'identifier' : cannot use 'new' to allocate a reference +> 'identifier' : cannot use 'new' to allocate a reference + +## Remarks A reference identifier was allocated with the **`new`** operator. References are not memory objects, so **`new`** cannot return a pointer to them. Use the standard variable declaration syntax to declare a reference. -The following sample generates C2464: +## Example + +The following example generates C2464: ```cpp // C2464.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2465.md b/docs/error-messages/compiler-errors-1/compiler-error-c2465.md index fc173014703..861458fb9ea 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2465.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2465.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2465" title: "Compiler Error C2465" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2465" +ms.date: 11/04/2016 f1_keywords: ["C2465"] helpviewer_keywords: ["C2465"] -ms.assetid: 65ba2a9f-d95e-4af3-b60b-1ac59a1e307c --- # Compiler Error C2465 -cannot define an anonymous type inside parentheses +> cannot define an anonymous type inside parentheses + +## Remarks An anonymous structure, union, or enumerated type is defined inside a parenthetical expression. This is invalid in C++ because the definition is meaningless in function scope. 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 ae382ccd5fd..05985b61cba 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2466.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2466.md @@ -1,23 +1,25 @@ --- -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 + +## Remarks 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)). -The following sample generates C2466: +## Example + +The following example 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-c2467.md b/docs/error-messages/compiler-errors-1/compiler-error-c2467.md index 05d89f1289e..a941568e44a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2467.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2467.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2467" title: "Compiler Error C2467" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2467" +ms.date: 11/04/2016 f1_keywords: ["C2467"] helpviewer_keywords: ["C2467"] -ms.assetid: f9ead270-5d0b-41cc-bdcd-586a647c67a7 --- # Compiler Error C2467 -illegal declaration of anonymous 'user-defined-type' +> illegal declaration of anonymous 'user-defined-type' + +## Remarks A nested user-defined type was declared. This is an error when compiling C source code with the ANSI compatibility option ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) enabled. -The following sample generates C2467: +## Example + +The following example generates C2467: ```c //C2467.c diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2469.md b/docs/error-messages/compiler-errors-1/compiler-error-c2469.md index 46ce44d6ee3..1a340f4bf07 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2469.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2469.md @@ -1,23 +1,38 @@ --- -description: "Learn more about: Compiler Error C2469" title: "Compiler Error C2469" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2469" +ms.date: 2/27/2026 f1_keywords: ["C2469"] helpviewer_keywords: ["C2469"] -ms.assetid: 3814bdff-581a-4d3e-8b47-8de6887cea69 --- # Compiler Error C2469 -'operator': cannot allocate 'type' object +> '`new`': cannot allocate '`void`' objects + +## Remarks + +The [`new` operator](../../cpp/new-operator-cpp.md) allocates memory and constructs an object of the specified type. Since `void` isn't a constructible type, use `::operator new(size)` to allocate raw memory without object construction. + +## Example: Wrong allocation type + +```cpp +// compile with /c +int main() +{ + void* ptr1 = new void; // C2469 + int* ptr2 = new int; // OK +} +``` -An operator was passed an invalid type. +## Example: Allocate untyped memory -The following sample generates C2469: +To allocate untyped memory, use `::operator new`: ```cpp -// C2469.cpp -int main() { - int *i = new void; // C2469 - int *i = new int; // OK +// compile with /c +int main() +{ + void* ptr1 = new void; // C2469 + void* ptr2 = ::operator new(4); // 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 1070a0128b1..228392a8ef2 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,36 @@ --- -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 + +## Remarks 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-c2471.md b/docs/error-messages/compiler-errors-1/compiler-error-c2471.md index 062241d3ee9..abf9f1606c1 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2471.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2471.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2471" title: "Compiler Error C2471" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2471" +ms.date: 11/04/2016 f1_keywords: ["C2471"] helpviewer_keywords: ["C2471"] -ms.assetid: a8928b44-20f6-4cbc-9aa5-7e86052a9c6b --- # Compiler Error C2471 -cannot update program database 'file' +> cannot update program database 'file' + +## Remarks The compiler cannot write to the database file. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2472.md b/docs/error-messages/compiler-errors-1/compiler-error-c2472.md index 7fce0f698a8..0b322bc60c3 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2472.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2472.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2472" title: "Compiler Error C2472" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2472" +ms.date: 11/04/2016 f1_keywords: ["C2472"] helpviewer_keywords: ["C2472"] -ms.assetid: 3b36bcdc-2ba5-4357-ab88-7545ba0551cd --- # Compiler Error C2472 @@ -18,7 +17,7 @@ The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual St ## Example -The following sample generates C2472. +The following example generates C2472. ```cpp // C2472.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2473.md b/docs/error-messages/compiler-errors-1/compiler-error-c2473.md index 63eb9afabf2..8577d69fade 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2473.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2473.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2473" title: "Compiler Error C2473" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2473" +ms.date: 11/04/2016 f1_keywords: ["C2473"] helpviewer_keywords: ["C2473"] -ms.assetid: 6bb7dbf5-b198-490f-860e-fd64d0c2a284 --- # Compiler Error C2473 -'identifier' : looks like a function definition, but there is no parameter list. +> 'identifier' : looks like a function definition, but there is no parameter list. + +## Remarks The compiler detected what looked like a function, without the parameter list. ## Example -The following sample generates C2473. +The following example generates C2473. ```cpp // C2473.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2474.md b/docs/error-messages/compiler-errors-1/compiler-error-c2474.md index 939b72aa8e8..a486d75c68e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2474.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2474.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2474" title: "Compiler Error C2474" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2474" +ms.date: 11/04/2016 f1_keywords: ["C2474"] helpviewer_keywords: ["C2474"] -ms.assetid: 64e6c61e-6e77-480e-bcf0-b30a2fc482ac --- # Compiler Error C2474 -'keyword' : missing an adjacent semicolon, could be either keyword or identifier. +> 'keyword' : missing an adjacent semicolon, could be either keyword or identifier. + +## Remarks The compiler expected to find a semicolon, and was unable to determine your intent. Add the semicolon to resolve this error. ## Example -The following sample generates C2474. +The following example generates C2474. ```cpp // C2474.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2477.md b/docs/error-messages/compiler-errors-1/compiler-error-c2477.md index 9979cd6338c..458ef4e497b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2477.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2477.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2477" title: "Compiler Error C2477" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2477" +ms.date: 11/04/2016 f1_keywords: ["C2477"] helpviewer_keywords: ["C2477"] -ms.assetid: 60bc324b-6605-4833-8099-a291efc712e7 --- # Compiler Error C2477 -'member' : static data member cannot be initialized via derived class +> 'member' : static data member cannot be initialized via derived class + +## Remarks A static data member of a template class was initialized incorrectly. This is a breaking change with versions of the Microsoft C++ compiler prior to Visual Studio .NET 2003, in order to conform to the ISO C++ standard. -The following sample generates C2477: +## Example + +The following example generates C2477: ```cpp // C2477.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2479.md b/docs/error-messages/compiler-errors-1/compiler-error-c2479.md index e7eca0e5cc1..9f1401b3543 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2479.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2479.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2479" title: "Compiler Error C2479" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2479" +ms.date: 11/04/2016 f1_keywords: ["C2479"] helpviewer_keywords: ["C2479"] -ms.assetid: c74c7869-e65b-4ca1-b6fa-eb39fed4458a --- # Compiler Error C2479 -'identifier' : 'allocate( )' is only valid for data items of static extent +> 'identifier' : 'allocate( )' is only valid for data items of static extent + +## Remarks The `__declspec( allocate())` syntax can be used for static data only. -The following sample generates C2479: +## Example + +The following example generates C2479: ```cpp // C2479.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2480.md b/docs/error-messages/compiler-errors-1/compiler-error-c2480.md index 53d48131942..669e3b97af6 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2480.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2480.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2480" title: "Compiler Error C2480" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2480" +ms.date: 11/04/2016 f1_keywords: ["C2480"] helpviewer_keywords: ["C2480"] -ms.assetid: 1a58d1c2-971b-4084-96fa-f94aa51c02f1 --- # Compiler Error C2480 -'identifier' : 'thread' is only valid for data items of static extent +> 'identifier' : 'thread' is only valid for data items of static extent + +## Remarks You cannot use the `thread` attribute with an automatic variable, nonstatic data member, function parameter, or on function declarations or definitions. Use the `thread` attribute for global variables, static data members, and local static variables only. -The following sample generates C2480: +## Example + +The following example generates C2480: ```cpp // C2480.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2482.md b/docs/error-messages/compiler-errors-1/compiler-error-c2482.md index 9c48b04b768..2e86bf038f7 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2482.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2482.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2482" title: "Compiler Error C2482" -ms.date: "09/15/2017" +description: "Learn more about: Compiler Error C2482" +ms.date: 09/15/2017 f1_keywords: ["C2482"] helpviewer_keywords: ["C2482"] -ms.assetid: 98c87da2-625c-4cc2-9bf7-78d15921e779 --- # Compiler Error C2482 @@ -16,7 +15,7 @@ In managed or WinRT code, variables declared by using the [__declspec(thread)](. ## Example -The following sample generates C2482 in managed (**/clr**) and in WinRT (**/ZW**) code: +The following example generates C2482 in managed (**/clr**) and in WinRT (**/ZW**) code: ```cpp // C2482.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2483.md b/docs/error-messages/compiler-errors-1/compiler-error-c2483.md index 5e225b8d6d9..b150748d853 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2483.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2483.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2483" title: "Compiler Error C2483" -ms.date: "09/15/2017" +description: "Learn more about: Compiler Error C2483" +ms.date: 09/15/2017 f1_keywords: ["C2483"] helpviewer_keywords: ["C2483"] -ms.assetid: 5762b325-914b-442d-a604-e4617ba04038 --- # Compiler Error C2483 >'*identifier*' : object with constructor or destructor cannot be declared 'thread' +## Remarks + This error message is obsolete in Visual Studio 2015 and later versions. In previous versions, variables declared with the `thread` attribute cannot be initialized with a constructor or other expression that requires run-time evaluation. A static expression is required to initialize `thread` data. ## Example -The following sample generates C2483 in Visual Studio 2013 and earlier versions. +The following example generates C2483 in Visual Studio 2013 and earlier versions. ```cpp // C2483.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2485.md b/docs/error-messages/compiler-errors-1/compiler-error-c2485.md index cc0fae6ad51..3dcdb343ffa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2485.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2485.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2485" title: "Compiler Error C2485" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2485" +ms.date: 11/04/2016 f1_keywords: ["C2485"] helpviewer_keywords: ["C2485"] -ms.assetid: daae3fc1-76cf-4a6f-b2fa-86873fb0929d --- # Compiler Error C2485 -'identifier' : unrecognized extended attribute +> 'identifier' : unrecognized extended attribute + +## Remarks The declaration attribute is not valid. diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2486.md b/docs/error-messages/compiler-errors-1/compiler-error-c2486.md index be3ef73366d..6e597959509 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2486.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2486.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2486" title: "Compiler Error C2486" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2486" +ms.date: 11/04/2016 f1_keywords: ["C2486"] helpviewer_keywords: ["C2486"] -ms.assetid: 436da349-6461-4e32-bfca-4f3e620108e2 --- # Compiler Error C2486 -'__LOCAL_SIZE' only allowed in function with the 'naked' attribute +> '__LOCAL_SIZE' only allowed in function with the 'naked' attribute + +## Remarks In inline assembly functions, the name `__LOCAL_SIZE` is reserved for functions declared with the [naked](../../cpp/naked-cpp.md) attribute. -The following sample generates C2486: +## Example + +The following example generates C2486: ```cpp // C2486.cpp 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 2f3cb106453..360a49315ca 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,33 @@ --- -description: "Learn more about: Compiler Error C2487" title: "Compiler Error C2487" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2487" +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 +> 'identifier' : member of dll interface class may not be declared with dll interface + +## Remarks 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. + +## Example + +The following example 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-error-c2488.md b/docs/error-messages/compiler-errors-1/compiler-error-c2488.md index 03afc72f646..f708e3c6c8e 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2488.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2488.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2488" title: "Compiler Error C2488" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2488" +ms.date: 11/04/2016 f1_keywords: ["C2488"] helpviewer_keywords: ["C2488"] -ms.assetid: cd435909-43e4-43c6-a57c-5d02468ef75f --- # Compiler Error C2488 -'identifier' : 'naked' can only be applied to non-member function definitions +> 'identifier' : 'naked' can only be applied to non-member function definitions + +## Remarks The [naked](../../cpp/naked-cpp.md) attribute was applied to a function declaration. -The following sample generates C2488: +## Example + +The following example generates C2488: ```cpp // C2488.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2489.md b/docs/error-messages/compiler-errors-1/compiler-error-c2489.md index b7cdbc9ed09..fb1bc4c1b20 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2489.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2489.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2489" title: "Compiler Error C2489" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2489" +ms.date: 11/04/2016 f1_keywords: ["C2489"] helpviewer_keywords: ["C2489"] -ms.assetid: 67d8cd98-db7e-4f7f-86b4-4af7bc89ec8b --- # Compiler Error C2489 -'identifier' : initialized auto or register variable not allowed at function scope in 'naked' function +> 'identifier' : initialized auto or register variable not allowed at function scope in 'naked' function + +## Remarks For more information, see [naked](../../cpp/naked-cpp.md). -The following sample generates C2489: +## Example + +The following example generates C2489: ```cpp // C2489.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2490.md b/docs/error-messages/compiler-errors-1/compiler-error-c2490.md index b675d35c6b0..56c30f37d31 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2490.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2490.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2490" title: "Compiler Error C2490" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2490" +ms.date: 11/04/2016 f1_keywords: ["C2490"] helpviewer_keywords: ["C2490"] -ms.assetid: 9de6bddd-b2e2-4ce6-b33b-201a8c2c8c54 --- # Compiler Error C2490 -'keyword' not allowed in function with 'naked' attribute +> 'keyword' not allowed in function with 'naked' attribute + +## Remarks A function defined as [naked](../../cpp/naked-cpp.md) cannot use structured exception handling. -The following sample generates C2490: +## Example + +The following example generates C2490: ```cpp // C2490.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2491.md b/docs/error-messages/compiler-errors-1/compiler-error-c2491.md index d04430cdf58..cdbaa93e35a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2491.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2491.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2491" title: "Compiler Error C2491" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2491" +ms.date: 11/04/2016 f1_keywords: ["C2491"] helpviewer_keywords: ["C2491"] -ms.assetid: 4e5a8f81-124e-402c-a5ec-d35a89b5469e --- # Compiler Error C2491 -'identifier' : definition of dllimport function not allowed +> 'identifier' : definition of dllimport function not allowed + +## Remarks Data, static data members, and functions can be declared as `dllimport`s but not defined as `dllimport`s. To fix this issue, remove the `__declspec(dllimport)` specifier from the definition of the function. -The following sample generates C2491: +## Example + +The following example generates C2491: ```cpp // C2491.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2492.md b/docs/error-messages/compiler-errors-1/compiler-error-c2492.md index 5b1d3f958a7..15b7b82c18a 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2492.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2492.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2492" title: "Compiler Error C2492" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2492" +ms.date: 11/04/2016 f1_keywords: ["C2492"] helpviewer_keywords: ["C2492"] -ms.assetid: 8c44c9bb-c366-4fe5-a0ab-882e38608aaa --- # Compiler Error C2492 -'*variable*': data with thread storage duration may not have dll interface +> '*variable*': data with thread storage duration may not have dll interface + +## Remarks The variable is declared with the [thread](../../cpp/thread.md) attribute and with the DLL interface. The address of the `thread` variable is not known until run time, so it cannot be linked to a DLL import or export. -The following sample generates C2492: +## Example + +The following example generates C2492: ```cpp // C2492.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2493.md b/docs/error-messages/compiler-errors-1/compiler-error-c2493.md index 880eb4770f3..9a594c154ba 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2493.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2493.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2493" title: "Compiler Error C2493" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2493" +ms.date: 11/04/2016 f1_keywords: ["C2493"] helpviewer_keywords: ["C2493"] -ms.assetid: 68316cd5-682b-49c3-b6ea-23c4e5d296cf --- # Compiler Error C2493 -illegal form of __based +> illegal form of __based + +## Remarks A **`__based`** expression must be based on a pointer. -The following sample generates C2493: +## Example + +The following example generates C2493: ```cpp // C2493.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2494.md b/docs/error-messages/compiler-errors-1/compiler-error-c2494.md index b8e75b82068..2d3a8755b78 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2494.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2494.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2494" title: "Compiler Error C2494" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2494" +ms.date: 11/04/2016 f1_keywords: ["C2494"] helpviewer_keywords: ["C2494"] -ms.assetid: 5dfd07ab-351d-49c9-b54e-f0a104776ab8 --- # Compiler Error C2494 > '*keyword*' cannot be called from within a filter expression or __finally/finally block +## Remarks + You cannot use *keyword* in a **`__finally`** or **`finally`** block. -The following sample generates C2494: +## Examples + +The following example generates C2494: ```cpp // C2494.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2495.md b/docs/error-messages/compiler-errors-1/compiler-error-c2495.md index 4c574088ef9..77119a710aa 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2495.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2495.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2495" title: "Compiler Error C2495" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2495" +ms.date: 11/04/2016 f1_keywords: ["C2495"] helpviewer_keywords: ["C2495"] -ms.assetid: bb7066fe-3549-4901-97e4-157f3c04dd57 --- # Compiler Error C2495 -'identifier' : 'nothrow' can only be applied to function declarations or definitions +> 'identifier' : 'nothrow' can only be applied to function declarations or definitions + +## Remarks The [nothrow](../../cpp/nothrow-cpp.md) extended attribute can be applied to function declarations or definitions only. -The following sample generates C2495: +## Example + +The following example generates C2495: ```cpp // C2495.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2496.md b/docs/error-messages/compiler-errors-1/compiler-error-c2496.md index 8e35f8ac5c5..4c8ff4c65ab 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2496.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2496.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2496" title: "Compiler Error C2496" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2496" +ms.date: 11/04/2016 f1_keywords: ["C2496"] helpviewer_keywords: ["C2496"] -ms.assetid: 9a25237d-5bbb-4112-98f3-29cd99d3f89f --- # Compiler Error C2496 -'identifier' : 'selectany' can only be applied to data items with external linkage +> 'identifier' : 'selectany' can only be applied to data items with external linkage + +## Remarks The [selectany](../../cpp/selectany.md) attribute can be applied only to externally visible and global data items. -The following sample generates C2496: +## Example + +The following example generates C2496: ```cpp // C2496.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2498.md b/docs/error-messages/compiler-errors-1/compiler-error-c2498.md index ca002045d60..fb603e31ed2 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2498.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2498.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2498" title: "Compiler Error C2498" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2498" +ms.date: 11/04/2016 f1_keywords: ["C2498"] helpviewer_keywords: ["C2498"] -ms.assetid: 0839f12c-aaa4-4a02-bb33-7f072715dd14 --- # Compiler Error C2498 -'function' : 'novtable' can only be applied to class declarations or definitions +> 'function' : 'novtable' can only be applied to class declarations or definitions + +## Remarks This error can be caused by using `__declspec(novtable)` with a function. ## Example -The following sample generates C2498: +The following example generates C2498: ```cpp // C2498.cpp diff --git a/docs/error-messages/compiler-errors-1/compiler-error-c2499.md b/docs/error-messages/compiler-errors-1/compiler-error-c2499.md index ce2ea37923d..38e8f58cd81 100644 --- a/docs/error-messages/compiler-errors-1/compiler-error-c2499.md +++ b/docs/error-messages/compiler-errors-1/compiler-error-c2499.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2499" title: "Compiler Error C2499" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2499" +ms.date: 11/04/2016 f1_keywords: ["C2499"] helpviewer_keywords: ["C2499"] -ms.assetid: b323ff4d-b3c1-4bfd-b052-ae7292d53222 --- # Compiler Error C2499 -'class' : a class cannot be its own base class +> 'class' : a class cannot be its own base class + +## Remarks You attempted to specify the class that you are defining as a base class. -The following sample generates C2499: +## Example + +The following example generates C2499: ```cpp // C2499.cpp 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 e43aa5e56b0..41ec42f58d8 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 9da4fe0ae96..d12d6a6217b 100644 --- a/docs/error-messages/compiler-errors-1/compiler-errors-c2001-through-c2099.md +++ b/docs/error-messages/compiler-errors-1/compiler-errors-c2001-through-c2099.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Compiler errors C2000 through C2099" -title: "Compiler errors C2000 through C2099" -ms.date: "04/21/2019" -f1_keywords: ["C2000", "C2016", "C2023", "C2024", "C2025", "C2029", "C2031", "C2035", "C2037", "C2038", "C2049", "C2068", "C2076", "C2080", "C2096", "C2098"] -helpviewer_keywords: ["C2000", "C2016", "C2023", "C2024", "C2025", "C2029", "C2031", "C2035", "C2037", "C2038", "C2049", "C2068", "C2076", "C2080", "C2096", "C2098"] -ms.assetid: d99a19eb-eeeb-4181-9b33-9cbe4459767b +description: "Learn more about: Compiler errors C2001 through C2099" +title: "Compiler errors C2001 through C2099" +ms.date: 08/24/2022 +f1_keywords: ["C2029"] +helpviewer_keywords: ["C2029"] --- -# Compiler errors C2000 through C2099 +# Compiler errors C2001 through C2099 The articles in this section of the documentation explain a subset of the error messages that are generated by the compiler. @@ -14,110 +13,109 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|Compiler error C2000|UNKNOWN ERROR Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| -|[Compiler error C2001](compiler-error-c2001.md)|newline in constant| -|[Compiler error C2002](compiler-error-c2002.md)|invalid wide-character constant| -|[Compiler error C2003](compiler-error-c2003.md)|expected 'defined id'| -|[Compiler error C2004](compiler-error-c2004.md)|expected 'defined(id)'| -|[Compiler error C2005](compiler-error-c2005.md)|#line expected a line number, found '*token*'| -|[Compiler error C2006](compiler-error-c2006.md)|'*directive*': expected a filename, found '*token*'| -|[Compiler error C2007](compiler-error-c2007.md)|#define syntax| -|[Compiler error C2008](compiler-error-c2008.md)|'*character*': unexpected in macro definition| -|[Compiler error C2009](compiler-error-c2009.md)|reuse of macro formal '*identifier*'| -|[Compiler error C2010](compiler-error-c2010.md)|'*character*': unexpected in macro formal parameter list| -|[Compiler error C2011](compiler-error-c2011.md)|'*identifier*': '*type*' type redefinition| -|[Compiler error C2012](compiler-error-c2012.md)|missing name following '<'| -|[Compiler error C2013](compiler-error-c2013.md)|missing '>'| -|[Compiler error C2014](compiler-error-c2014.md)|preprocessor command must start as first nonwhite space| -|[Compiler error C2015](compiler-error-c2015.md)|too many characters in constant| -|Compiler error C2016|C requires that a struct or union has at least one member| -|[Compiler error C2017](compiler-error-c2017.md)|illegal escape sequence| -|[Compiler error C2018](compiler-error-c2018.md)|unknown character '0x*value*'| -|[Compiler error C2019](compiler-error-c2019.md)|expected preprocessor directive, found '*character*'| -|[Compiler error C2020](compiler-error-c2020.md)|'*member*': '*class*' member redefinition| -|[Compiler error C2021](compiler-error-c2021.md)|expected exponent value, not '*character*'| -|[Compiler error C2022](compiler-error-c2022.md)|'*number*': too big for character| -|Compiler error C2023|'*identifier*': Alignment (*number1*) different from prior declaration (*number2*)| -|Compiler error C2024|'alignas' attribute applies to variables, data members and tag types only| -|Compiler error C2025|invalid or corrupted binary module interface file: '*filename*'| -|[Compiler error C2026](compiler-error-c2026.md)|string too big, trailing characters truncated| -|[Compiler error C2027](compiler-error-c2027.md)|use of undefined type '*type*'| -|[Compiler error C2028](compiler-error-c2028.md)|struct/union member must be inside a struct/union| -|Compiler error C2029|left of '*token*' specifies undefined class/struct/interface '*identifier*'| -|[Compiler error C2030](compiler-error-c2030.md)|a destructor with 'protected private' accessibility cannot be a member of a class declared 'sealed'| -|Compiler error C2031|a virtual destructor with '*accessibility*' accessibility is not allowed for this type| -|[Compiler error C2032](compiler-error-c2032.md)|'*identifier*': function cannot be member of struct/union '*type*'| -|[Compiler error C2033](compiler-error-c2033.md)|'*identifier*': bit field cannot have indirection| -|[Compiler error C2034](compiler-error-c2034.md)|'*identifier*': type of bit field too small for number of bits| -|Compiler error C2035|a non-virtual destructor with '*accessibility*' accessibility is not allowed for this type| -|[Compiler error C2036](compiler-error-c2036.md)|'*identifier*': unknown size| -|Compiler error C2037|left of '*identifier*' specifies undefined struct/union '*type*'| -|Compiler error C2038|the std namespace cannot be inline| -|[Compiler error C2039](compiler-error-c2039.md)|'*identifier1*': is not a member of '*identifier2*'| -|[Compiler error C2040](compiler-error-c2040.md)|'*operator*': '*identifier1*' differs in levels of indirection from '*identifier2*'| -|[Compiler error C2041](compiler-error-c2041.md)|illegal digit '*character*' for base '*number*'| -|[Compiler error C2042](compiler-error-c2042.md)|signed/unsigned keywords mutually exclusive| -|[Compiler error C2043](compiler-error-c2043.md)|illegal break| -|[Compiler error C2044](compiler-error-c2044.md)|illegal continue| -|[Compiler error C2045](compiler-error-c2045.md)|'*identifier*': label redefined| -|[Compiler error C2046](compiler-error-c2046.md)|illegal case| -|[Compiler error C2047](compiler-error-c2047.md)|illegal default| -|[Compiler error C2048](compiler-error-c2048.md)|more than one default| -|Compiler error C2049|'*identifier*': non-inline namespace cannot be reopened as inline| -|[Compiler error C2050](compiler-error-c2050.md)|switch expression not integral| -|[Compiler error C2051](compiler-error-c2051.md)|case expression not constant| -|[Compiler error C2052](compiler-error-c2052.md)|'*type*': illegal type for case expression| -|[Compiler error C2053](compiler-error-c2053.md)|'*identifier*': wide string mismatch| -|[Compiler error C2054](compiler-error-c2054.md)|expected '(' to follow '*identifier*'| -|[Compiler error C2055](compiler-error-c2055.md)|expected formal parameter list, not a type list| -|[Compiler error C2056](compiler-error-c2056.md)|illegal expression| -|[Compiler error C2057](compiler-error-c2057.md)|expected constant expression| -|[Compiler error C2058](compiler-error-c2058.md)|constant expression is not integral| -|[Compiler error C2059](compiler-error-c2059.md)|syntax error: '*token*'| -|[Compiler error C2060](compiler-error-c2060.md)|syntax error: end of file found| -|[Compiler error C2061](compiler-error-c2061.md)|syntax error: identifier '*identifier*'| -|[Compiler error C2062](compiler-error-c2062.md)|type '*type*' unexpected| -|[Compiler error C2063](compiler-error-c2063.md)|'*identifier*': not a function| -|[Compiler error C2064](compiler-error-c2064.md)|term does not evaluate to a function taking *number* arguments| -|[Compiler error C2065](compiler-error-c2065.md)|'*identifier*': undeclared identifier| -|[Compiler error C2066](compiler-error-c2066.md)|cast to function type is illegal| -|[Compiler error C2067](compiler-error-c2067.md)|cast to array type is illegal| -|Compiler error C2068|illegal use of overloaded function. Missing argument list?| -|[Compiler error C2069](compiler-error-c2069.md)|cast of 'void' term to non-'void'| -|[Compiler error C2070](compiler-error-c2070.md)|'*type*': illegal sizeof operand| -|[Compiler error C2071](compiler-error-c2071.md)|'*identifier*': illegal storage class| -|[Compiler error C2072](compiler-error-c2072.md)|'*identifier*': initialization of a function| -|[Compiler error C2073](compiler-error-c2073.md)|'*identifier*': elements of partially initialized array must have a default constructor| -|[Compiler error C2074](compiler-error-c2074.md)|'*identifier*': '*type*' initialization requires a brace-enclosed initializer list| -|[Compiler error C2075](compiler-error-c2075.md)|'*identifier*': array initialization requires a brace-enclosed initializer list| -|Compiler error C2076|a brace-enclosed initializer list cannot be used in a new-expression whose type contains '*type*'| -|[Compiler error C2077](compiler-error-c2077.md)|non-scalar field initializer '*identifier*'| -|[Compiler error C2078](compiler-error-c2078.md)|too many initializers| -|[Compiler error C2079](compiler-error-c2079.md)|'*identifier*' uses undefined struct/class/union '*type*'| -|Compiler error C2080|'*identifier*': the type for '*type*' can only be deduced from a single initializer expression| -|[Compiler error C2081](compiler-error-c2081.md)|'*identifier*': name in formal parameter list illegal| -|[Compiler error C2082](compiler-error-c2082.md)|redefinition of formal parameter '*identifier*'| -|[Compiler error C2083](compiler-error-c2083.md)|struct/union comparison illegal| -|[Compiler error C2084](compiler-error-c2084.md)|function '*identifier*' already has a body| -|[Compiler error C2085](compiler-error-c2085.md)|'*identifier*': not in formal parameter list| -|[Compiler error C2086](compiler-error-c2086.md)|'*identifier*': redefinition| -|[Compiler error C2087](compiler-error-c2087.md)|'*identifier*': missing subscript| -|[Compiler error C2088](compiler-error-c2088.md)|'*operator*': illegal for struct/class/union| -|[Compiler error C2089](compiler-error-c2089.md)|'*identifier*': '*type*' too large| -|[Compiler error C2090](compiler-error-c2090.md)|function returns array| -|[Compiler error C2091](compiler-error-c2091.md)|function returns function| -|[Compiler error C2092](compiler-error-c2092.md)|'*identifier*' array element type cannot be function| -|[Compiler error C2093](compiler-error-c2093.md)|'*identifier1*': cannot be initialized using address of automatic variable '*identifier2*'| -|[Compiler error C2094](compiler-error-c2094.md)|label '*identifier*' was undefined| -|[Compiler error C2095](compiler-error-c2095.md)|'*function*': actual parameter has type 'void': parameter *number*| -|Compiler error C2096|'*identifier*': A data member cannot be initialized with a parenthesized initializer| -|[Compiler error C2097](compiler-error-c2097.md)|illegal initialization| -|Compiler error C2098|unexpected token after data member '*identifier*'| -|[Compiler error C2099](compiler-error-c2099.md)|initializer is not a constant| +| Error | Message | +|--|--| +| [Compiler error C2001](compiler-error-c2001.md) | newline in constant | +| [Compiler error C2002](compiler-error-c2002.md) | invalid wide-character constant | +| [Compiler error C2003](compiler-error-c2003.md) | expected 'defined id' | +| [Compiler error C2004](compiler-error-c2004.md) | expected 'defined(id)' | +| [Compiler error C2005](compiler-error-c2005.md) | #line expected a line number, found '*token*' | +| [Compiler error C2006](compiler-error-c2006.md) | '*directive*': expected `"FILENAME"` or `` | +| [Compiler error C2007](compiler-error-c2007.md) | #define syntax | +| [Compiler error C2008](compiler-error-c2008.md) | '*character*': unexpected in macro definition | +| [Compiler error C2009](compiler-error-c2009.md) | cannot reuse macro parameter name '*identifier*' | +| [Compiler error C2010](compiler-error-c2010.md) | '*character*': unexpected in macro formal parameter list | +| [Compiler error C2011](compiler-error-c2011.md) | '*identifier*': '*type*' type redefinition | +| [Compiler error C2012](compiler-error-c2012.md) | missing name following '<' | +| [Compiler error C2013](compiler-error-c2013.md) | expected a '*token*' | +| [Compiler error C2014](compiler-error-c2014.md) | preprocessor command must start as first nonwhite space | +| [Compiler error C2015](compiler-error-c2015.md) | too many characters in constant | +| [Compiler error C2016](compiler-error-c2016.md) | C requires that a struct or union has at least one member | +| [Compiler error C2017](compiler-error-c2017.md) | illegal escape sequence | +| [Compiler error C2018](compiler-error-c2018.md) | unknown character '0x*value*' | +| [Compiler error C2019](compiler-error-c2019.md) | expected preprocessor directive, found '*character*' | +| [Compiler error C2020](compiler-error-c2020.md) | '*member*': '*class*' member redefinition | +| [Compiler error C2021](compiler-error-c2021.md) | expected exponent value, not '*character*' | +| [Compiler error C2022](compiler-error-c2022.md) | '*number*': too big for character | +| [Compiler error C2023](compiler-error-c2023.md) | '*identifier*': Alignment (*value-1*) different from prior declaration (*value-2*) | +| [Compiler error C2024](compiler-error-c2024.md) | 'alignas' attribute applies to variables, data members and tag types only | +| [Compiler error C2025](compiler-error-c2025.md) | invalid or corrupted binary module interface file: '*filename*' | +| [Compiler error C2026](compiler-error-c2026.md) | string too big, trailing characters truncated | +| [Compiler error C2027](compiler-error-c2027.md) | use of undefined type '*type*' | +| [Compiler error C2028](compiler-error-c2028.md) | struct/union member must be inside a struct/union | +| Compiler error C2029 | **(Obsolete)** left of '*token*' specifies undefined class/struct/interface '*identifier*' | +| [Compiler error C2030](compiler-error-c2030.md) | a destructor with 'protected private' accessibility cannot be a member of a class declared 'sealed' | +| [Compiler error C2031](compiler-error-c2031.md) | a virtual destructor with '*accessibility*' accessibility is not allowed for this type | +| [Compiler error C2032](compiler-error-c2032.md) | '*identifier*': function cannot be member of struct/union '*type*' | +| [Compiler error C2033](compiler-error-c2033.md) | '*identifier*': bit field cannot have indirection | +| [Compiler error C2034](compiler-error-c2034.md) | '*identifier*': type of bit field too small for number of bits | +| [Compiler error C2035](compiler-error-c2035.md) | a non-virtual destructor with '*accessibility*' accessibility is not allowed for this type | +| [Compiler error C2036](compiler-error-c2036.md) | '*identifier*': unknown size | +| [Compiler error C2037](compiler-error-c2037.md) | left of '*operator*' specifies undefined struct/union '*type*' | +| [Compiler error C2038](compiler-error-c2038.md) | the std namespace cannot be inline | +| [Compiler error C2039](compiler-error-c2039.md) | '*identifier1*': is not a member of '*identifier2*' | +| [Compiler error C2040](compiler-error-c2040.md) | '*operator*': '*identifier1*' differs in levels of indirection from '*identifier2*' | +| [Compiler error C2041](compiler-error-c2041.md) | illegal digit '*character*' for base '*number*' | +| [Compiler error C2042](compiler-error-c2042.md) | signed/unsigned keywords mutually exclusive | +| [Compiler error C2043](compiler-error-c2043.md) | illegal break | +| [Compiler error C2044](compiler-error-c2044.md) | illegal continue | +| [Compiler error C2045](compiler-error-c2045.md) | '*identifier*': label redefined | +| [Compiler error C2046](compiler-error-c2046.md) | illegal case | +| [Compiler error C2047](compiler-error-c2047.md) | illegal default | +| [Compiler error C2048](compiler-error-c2048.md) | more than one default | +| [Compiler error C2049](compiler-error-c2049.md) | '*namespace-name*': non-inline namespace cannot be reopened as inline | +| [Compiler error C2050](compiler-error-c2050.md) | switch expression not integral | +| [Compiler error C2051](compiler-error-c2051.md) | case expression not constant | +| [Compiler error C2052](compiler-error-c2052.md) | '*type*': illegal type for case expression | +| [Compiler error C2053](compiler-error-c2053.md) | '*identifier*': wide string mismatch | +| [Compiler error C2054](compiler-error-c2054.md) | expected '(' to follow '*identifier*' | +| [Compiler error C2055](compiler-error-c2055.md) | expected formal parameter list, not a type list | +| [Compiler error C2056](compiler-error-c2056.md) | illegal expression | +| [Compiler error C2057](compiler-error-c2057.md) | expected constant expression | +| [Compiler error C2058](compiler-error-c2058.md) | constant expression is not integral | +| [Compiler error C2059](compiler-error-c2059.md) | syntax error: '*token*' | +| [Compiler error C2060](compiler-error-c2060.md) | syntax error: end of file found | +| [Compiler error C2061](compiler-error-c2061.md) | syntax error: identifier '*identifier*' | +| [Compiler error C2062](compiler-error-c2062.md) | type '*type*' unexpected | +| [Compiler error C2063](compiler-error-c2063.md) | '*identifier*': not a function | +| [Compiler error C2064](compiler-error-c2064.md) | term does not evaluate to a function taking *number* arguments | +| [Compiler error C2065](compiler-error-c2065.md) | '*identifier*': undeclared identifier | +| [Compiler error C2066](compiler-error-c2066.md) | cast to function type is illegal | +| [Compiler error C2067](compiler-error-c2067.md) | cast to array type is illegal | +| [Compiler error C2068](compiler-error-c2068.md) | illegal use of overloaded function. Missing argument list? | +| [Compiler error C2069](compiler-error-c2069.md) | cast of 'void' term to non-'void' | +| [Compiler error C2070](compiler-error-c2070.md) | '*type*': illegal sizeof operand | +| [Compiler error C2071](compiler-error-c2071.md) | '*identifier*': illegal storage class | +| [Compiler error C2072](compiler-error-c2072.md) | '*identifier*': initialization of a function | +| [Compiler error C2073](compiler-error-c2073.md) | **(Obsolete)** '*identifier*': elements of partially initialized array must have a default constructor | +| [Compiler error C2074](compiler-error-c2074.md) | '*identifier*': '*type*' initialization requires a brace-enclosed initializer list | +| [Compiler error C2075](compiler-error-c2075.md) | '*identifier*': initialization requires a brace-enclosed initializer list | +| [Compiler error C2076](compiler-error-c2076.md) | a brace-enclosed initializer list cannot be used in a new-expression whose type contains '*type*' | +| [Compiler error C2077](compiler-error-c2077.md) | non-scalar field initializer '*identifier*' | +| [Compiler error C2078](compiler-error-c2078.md) | too many initializers | +| [Compiler error C2079](compiler-error-c2079.md) | '*identifier*' uses undefined struct/class/union '*type*' | +| [Compiler error C2080](compiler-error-c2080.md) | '*identifier*': the type for '*type*' can only be deduced from a single initializer expression | +| [Compiler error C2081](compiler-error-c2081.md) | '*identifier*': name in formal parameter list illegal | +| [Compiler error C2082](compiler-error-c2082.md) | redefinition of formal parameter '*identifier*' | +| [Compiler error C2083](compiler-error-c2083.md) | struct/union comparison illegal | +| [Compiler error C2084](compiler-error-c2084.md) | function '*identifier*' already has a body | +| [Compiler error C2085](compiler-error-c2085.md) | '*identifier*': not in formal parameter list | +| [Compiler error C2086](compiler-error-c2086.md) | '*identifier*': redefinition | +| [Compiler error C2087](compiler-error-c2087.md) | '*identifier*': missing subscript | +| [Compiler error C2088](compiler-error-c2088.md) | built-in operator '*operator*' cannot be applied to an operand of type '*class type*' | +| [Compiler error C2089](compiler-error-c2089.md) | '*identifier*': '*type*' too large | +| [Compiler error C2090](compiler-error-c2090.md) | function returns array | +| [Compiler error C2091](compiler-error-c2091.md) | function returns function | +| [Compiler error C2092](compiler-error-c2092.md) | '*identifier*' array element type cannot be function or abstract class type | +| [Compiler error C2093](compiler-error-c2093.md) | '*identifier1*': cannot be initialized using address of automatic variable '*identifier2*' | +| [Compiler error C2094](compiler-error-c2094.md) | label '*identifier*' was undefined | +| [Compiler error C2095](compiler-error-c2095.md) | '*function*': actual parameter has type 'void': parameter *number* | +| [Compiler error C2096](compiler-error-c2096.md) | '*identifier*': A data member cannot be initialized with a parenthesized initializer | +| [Compiler error C2097](compiler-error-c2097.md) | illegal initialization | +| [Compiler error C2098](compiler-error-c2098.md) | unexpected token after data member '*identifier*' | +| [Compiler error C2099](compiler-error-c2099.md) | initializer is not a constant | ## See also [C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ -[Compiler errors C2000 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) +[Compiler errors C2001 - C3999, C7000 - C7999](../compiler-errors-1/compiler-errors-c2000-c3999.md) diff --git a/docs/error-messages/compiler-errors-1/compiler-errors-c2100-through-c2199.md b/docs/error-messages/compiler-errors-1/compiler-errors-c2100-through-c2199.md index 2a62b7560f7..66e44a4ebeb 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" -ms.date: "04/21/2019" +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| @@ -70,7 +69,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2151](compiler-error-c2151.md)|more than one language attribute| |[Compiler error C2152](compiler-error-c2152.md)|'*identifier*': pointers to functions with different attributes| |[Compiler error C2153](compiler-error-c2153.md)|integer literals must have at least one digit| -|[Compiler error C2154](compiler-error-c2154.md)|'*type*': only enumeration type is allowed as an argument to compiler intrinsic type trait '*trait*'| +|[Compiler error C2154](compiler-error-c2154.md)|'*type*': only enumeration type is allowed as an argument to compiler intrinsic type trait '__underlying_type'| |[Compiler error C2155](compiler-error-c2155.md)|'?': invalid left operand, expected arithmetic or pointer type| |[Compiler error C2156](compiler-error-c2156.md)|pragma must be outside function| |[Compiler error C2157](compiler-error-c2157.md)|'*identifier*': must be declared before use in pragma list| @@ -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*| @@ -98,7 +97,7 @@ The articles in this section of the documentation explain a subset of the error |[Compiler error C2179](compiler-error-c2179.md)|'*type*': an attribute argument cannot use type parameters| |[Compiler error C2180](compiler-error-c2180.md)|controlling expression has type '*type*'| |[Compiler error C2181](compiler-error-c2181.md)|illegal else without matching if| -|[Compiler error C2182](compiler-error-c2182.md)|'*identifier*': illegal use of type 'void'| +|[Compiler error C2182](compiler-error-c2182.md)|'*identifier*': this use of 'void' is not valid| |[Compiler error C2183](compiler-error-c2183.md)|syntax error: translation unit is empty| |[Compiler error C2184](compiler-error-c2184.md)|'*type*': illegal type for __except expression| |[Compiler error C2185](compiler-error-c2185.md)|'*identifier*': illegal based allocation| @@ -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 fbb78db3629..061b94f1696 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 a78a533c3b9..3abd7f9ea41 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 a22a80372d5..d7e931c1e43 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 f24db7c8a5a..d19b4ce9368 100644 --- a/docs/error-messages/compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md +++ b/docs/error-messages/compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Compiler fatal errors C999 through C1999" -title: "Compiler fatal errors C999 through C1999" -ms.date: "04/21/2019" -f1_keywords: ["C1034", "C1036", "C1041", "C1048", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1193", "C1195", "C1300", "C1301", "C1302", "C1306", "C1384", "C1451", "C1505", "C1901"] -helpviewer_keywords: ["C1034", "C1036", "C1041", "C1048", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1193", "C1195", "C1300", "C1301", "C1302", "C1306", "C1384", "C1451", "C1505", "C1901"] -ms.assetid: 6c8df109-7594-48ed-987a-97d9fe2b04af +title: "Compiler fatal errors C1001 through C1907" +description: "Learn more about: Compiler fatal errors C1001 through C1907" +ms.date: 01/24/2025 +f1_keywords: ["C1006", "C1024", "C1027", "C1030", "C1032", "C1034", "C1036", "C1039", "C1040", "C1041", "C1042", "C1043", "C1044", "C1048", "C1056", "C1058", "C1059", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1118", "C1119", "C1127", "C1193", "C1194", "C1195", "C1198", "C1199", "C1203", "C1204", "C1212", "C1213", "C1214", "C1300", "C1301", "C1302", "C1303", "C1304", "C1306", "C1354", "C1355", "C1356", "C1357", "C1358", "C1384", "C1385", "C1451", "C1505", "C1507", "C1511", "C1604", "C1605", "C1859", "C1901", "C1906", "C1907"] +helpviewer_keywords: ["C1006", "C1024", "C1027", "C1030", "C1032", "C1034", "C1036", "C1039", "C1040", "C1041", "C1042", "C1043", "C1044", "C1048", "C1056", "C1058", "C1059", "C1063", "C1069", "C1101", "C1102", "C1105", "C1110", "C1111", "C1112", "C1114", "C1118", "C1119", "C1127", "C1193", "C1194", "C1195", "C1198", "C1199", "C1203", "C1204", "C1212", "C1213", "C1214", "C1300", "C1301", "C1302", "C1303", "C1304", "C1306", "C1354", "C1355", "C1356", "C1357", "C1358", "C1384", "C1385", "C1451", "C1505", "C1507", "C1511", "C1604", "C1605", "C1859", "C1901", "C1906", "C1907"] --- -# Compiler fatal errors C999 through C1999 +# Compiler fatal errors C1001 through C1907 The articles in this section of the documentation explain a subset of the error messages that are generated by the Microsoft C/C++ compiler. @@ -14,153 +13,202 @@ The articles in this section of the documentation explain a subset of the error ## Error messages -|Error|Message| -|-----------|-------------| -|[Fatal error C999](../../error-messages/compiler-errors-1/fatal-error-c999.md)|UNKNOWN MESSAGE Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| -|[Fatal error C1001](../../error-messages/compiler-errors-1/fatal-error-c1001.md)|An internal error has occurred in the compiler.
(compiler file '*file*', line *number*)
To work around this problem, try simplifying or changing the program near the locations listed above. Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information| -|[Fatal error C1002](../../error-messages/compiler-errors-1/fatal-error-c1002.md)|compiler is out of heap space in pass 2| -|[Fatal error C1003](../../error-messages/compiler-errors-1/fatal-error-c1003.md)|error count exceeds *number*; stopping compilation| -|[Fatal error C1004](../../error-messages/compiler-errors-1/fatal-error-c1004.md)|unexpected end-of-file found| -|[Fatal error C1005](../../error-messages/compiler-errors-1/fatal-error-c1005.md)|string too big for buffer| -|[Fatal error C1007](../../error-messages/compiler-errors-1/fatal-error-c1007.md)|unrecognized flag '*string*' in '*option*'| -|[Fatal error C1008](../../error-messages/compiler-errors-1/fatal-error-c1008.md)|no input file specified| -|[Fatal error C1009](../../error-messages/compiler-errors-1/fatal-error-c1009.md)|compiler limit: macros nested too deeply| -|[Fatal error C1010](../../error-messages/compiler-errors-1/fatal-error-c1010.md)|unexpected end of file while looking for precompiled header. Did you forget to add '#include \<*file*>' to your source?| -|[Fatal error C1012](fatal-error-c1012.md)|unmatched parenthesis: missing '*character*"| -|[Fatal error C1013](fatal-error-c1013.md)|compiler limit: too many open parentheses| -|[Fatal error C1014](fatal-error-c1014.md)|too many include files: depth = *number*| -|[Fatal error C1016](fatal-error-c1016.md)|#ifdef/#ifndef expected an identifier| -|[Fatal error C1017](../../error-messages/compiler-errors-1/fatal-error-c1017.md)|invalid integer constant expression| -|[Fatal error C1018](fatal-error-c1018.md)|unexpected #elif| -|[Fatal error C1019](fatal-error-c1019.md)|unexpected #else| -|[Fatal error C1020](fatal-error-c1020.md)|unexpected #endif| -|[Fatal error C1021](fatal-error-c1021.md)|invalid preprocessor command '*string*'| -|[Fatal error C1022](fatal-error-c1022.md)|expected #endif| -|[Fatal error C1023](fatal-error-c1023.md)|'*file*': unexpected error with pch, try rebuilding the pch| -|[Fatal error C1026](../../error-messages/compiler-errors-1/fatal-error-c1026.md)|parser stack overflow, program too complex| -|[Fatal error C1033](../../error-messages/compiler-errors-1/fatal-error-c1033.md)|cannot open program database '*file*'| -|Fatal error C1034|*file*: no include path set| -|[Fatal error C1035](fatal-error-c1035.md)|expression too complex; simplify expression| -|Fatal error C1036|cannot overwrite earlier program database format, delete '*file*' and recompile| -|[Fatal error C1037](fatal-error-c1037.md)|cannot open object file '*file*'| -|[Fatal error C1038](fatal-error-c1038.md)|compiler limit: '*function*': control flow state too complex; simplify function| -|Fatal error C1041|cannot open program database '*file*'; if multiple CL.EXE write to the same .PDB file, please use /FS| -|[Fatal error C1045](fatal-error-c1045.md)|compiler limit: linkage specifications nested too deeply| -|[Fatal error C1046](../../error-messages/compiler-errors-1/fatal-error-c1046.md)|compiler limit: *structure* nested too deeply| -|[Fatal error C1047](fatal-error-c1047.md)|The object or library file '*file*' was created with an older compiler than other objects; rebuild old objects and libraries| -|Fatal error C1048|unknown option '*string*' in '*option*'| -|[Fatal error C1049](fatal-error-c1049.md)|invalid numerical argument '*value*'| -|[Fatal error C1051](../../error-messages/compiler-errors-1/fatal-error-c1051.md)|program database file, '*file*', has an obsolete format, delete it and recompile| -|[Fatal error C1052](fatal-error-c1052.md)|program database file, '*filename*', was generated by the linker with /DEBUG:fastlink; compiler cannot update such PDB files; please delete it or use /Fd to specify a different PDB filename| -|[Fatal error C1053](fatal-error-c1053.md)|'*function*': function too large| -|[Fatal error C1054](../../error-messages/compiler-errors-1/fatal-error-c1054.md)|compiler limit: initializers nested too deeply| -|[Fatal error C1055](../../error-messages/compiler-errors-1/fatal-error-c1055.md)|compiler limit: out of keys| -|[Fatal error C1057](../../error-messages/compiler-errors-1/fatal-error-c1057.md)|unexpected end of file in macro expansion| -|[Fatal error C1060](../../error-messages/compiler-errors-1/fatal-error-c1060.md)|compiler is out of heap space| -|[Fatal error C1061](../../error-messages/compiler-errors-1/fatal-error-c1061.md)|compiler limit: blocks nested too deeply| -|Fatal error C1063|compiler limit: compiler stack overflow| -|[Fatal error C1064](../../error-messages/compiler-errors-1/fatal-error-c1064.md)|compiler limit: token overflowed internal buffer| -|[Fatal error C1065](../../error-messages/compiler-errors-1/fatal-error-c1065.md)|compiler limit: out of tags| -|[Fatal error C1067](../../error-messages/compiler-errors-1/fatal-error-c1067.md)|compiler limit: 64K limit on size of a type record has been exceeded| -|[Fatal error C1068](fatal-error-c1068.md)|cannot open file '*file*'| -|Fatal error C1069|cannot read compiler command line| -|[Fatal error C1070](fatal-error-c1070.md)|mismatched #if/#endif pair in file '*file*'| -|[Fatal error C1071](../../error-messages/compiler-errors-1/fatal-error-c1071.md)|unexpected end of file found in comment| -|[Fatal error C1073](../../error-messages/compiler-errors-1/fatal-error-c1073.md)|Internal error involving incremental compilation(compiler file '*file*', line *number*)| -|[Fatal error C1074](fatal-error-c1074.md)|'IDB' is illegal extension for PDB file: *file*| -|[Fatal error C1075](../../error-messages/compiler-errors-1/fatal-error-c1075.md)|the left *token* was unmatched at the end of the file| -|[Fatal error C1076](../../error-messages/compiler-errors-1/fatal-error-c1076.md)|compiler limit: internal heap limit reached; use /Zm to specify a higher limit| -|[Fatal error C1077](fatal-error-c1077.md)|compiler limit: cannot have more than *number* command line options| -|[Fatal error C1079](../../error-messages/compiler-errors-1/fatal-error-c1079.md)|compiler limit: PCH file size limit exceeded| -|[Fatal error C1080](../../error-messages/compiler-errors-1/fatal-error-c1080.md)|compiler limit: command line option exceeded limit of *number* characters| -|[Fatal error C1081](../../error-messages/compiler-errors-1/fatal-error-c1081.md)|'*file*': file name too long| -|[Fatal error C1082](fatal-error-c1082.md)|cannot close *type* file: '*file*': *message*| -|[Fatal error C1083](../../error-messages/compiler-errors-1/fatal-error-c1083.md)|cannot open *type* file: '*file*': *message*| -|[Fatal error C1084](../../error-messages/compiler-errors-1/fatal-error-c1084.md)|cannot read *type* file: '*file*': *message*| -|[Fatal error C1085](../../error-messages/compiler-errors-1/fatal-error-c1085.md)|cannot write *type* file: '*file*': *message*| -|[Fatal error C1086](fatal-error-c1086.md)|cannot seek *type* file: '*file*': *message*| -|[Fatal error C1087](fatal-error-c1087.md)|cannot tell *type* file: '*file*': *message*| -|[Fatal error C1088](fatal-error-c1088.md)|cannot flush *type* file: '*file*': *message*| -|[Fatal error C1089](fatal-error-c1089.md)|cannot truncate *type* file: '*file*': *message*| -|[Fatal error C1090](fatal-error-c1090.md)|PDB API call failed, error code '*code*': '*message*'| -|[Fatal error C1091](fatal-error-c1091.md)|compiler limit: string exceeds *number* bytes in length| -|[Fatal error C1092](../../error-messages/compiler-errors-1/fatal-error-c1092.md)|Edit and Continue does not support changes to data types; build required| -|[Fatal error C1093](../../error-messages/compiler-errors-1/fatal-error-c1093.md)|API call '*function*' failed '*HRESULT*' : '*description*'| -|[Fatal error C1094](../../error-messages/compiler-errors-1/fatal-error-c1094.md)|'-Zm*number*': command line option is inconsistent with value used to build precompiled header ('-Zm*number*')| -|[Fatal error C1098](fatal-error-c1098.md)|Version mismatch with Edit and Continue engine| -|[Fatal error C1099](fatal-error-c1099.md)|Edit and Continue engine terminating compile| -|[Fatal error C1100](fatal-error-c1100.md)|unable to initialize OLE: *error*| -|Fatal error C1101|cannot create handler for attribute '*identifier*'| -|Fatal error C1102|unable to initialize: *error*| -|[Fatal error C1103](fatal-error-c1103.md)|fatal error importing progid: '*message*'| -|[Fatal error C1104](fatal-error-c1104.md)|fatal error importing libid: '*message*'| -|Fatal error C1105|*message*: *error*| -|[Fatal error C1107](../../error-messages/compiler-errors-1/fatal-error-c1107.md)|could not find assembly '*assembly*': please specify the assembly search path using /AI or by setting the LIBPATH environment variable| -|[Fatal error C1108](fatal-error-c1108.md)|unable to find DLL: '*file*'| -|[Fatal error C1109](fatal-error-c1109.md)|unable to find '*symbol*' in DLL '*file*'| -|Fatal error C1110|too many nested template/generic definitions| -|Fatal error C1111|too many template/generic parameters| -|Fatal error C1112|compiler limit: '*number*' too many macro arguments, only *number* allowed| -|[Fatal error C1113](../../error-messages/compiler-errors-1/fatal-error-c1113.md)|#using failed on '*file*'| -|Fatal error C1114|'*file*': WinRT does not support #using of a managed assembly| -|[Fatal error C1120](../../error-messages/compiler-errors-1/fatal-error-c1120.md)|call to GetProcAddress failed for '*function*'| -|[Fatal error C1121](../../error-messages/compiler-errors-1/fatal-error-c1121.md)|call to CryptoAPI failed| -|[Fatal error C1126](../../error-messages/compiler-errors-1/fatal-error-c1126.md)|automatic allocation exceeds *size*| -|[Fatal error C1128](../../error-messages/compiler-errors-1/fatal-error-c1128.md)|number of sections exceeded object file format limit: compile with /bigobj| -|[Fatal error C1189](../../error-messages/compiler-errors-1/fatal-error-c1189.md)|#error: *message*| -|[Fatal error C1190](fatal-error-c1190.md)|managed targeted code requires a '/clr' option| -|[Fatal error C1191](../../error-messages/compiler-errors-1/fatal-error-c1191.md)|'*file*' can only be imported at global scope| -|[Fatal error C1192](../../error-messages/compiler-errors-1/fatal-error-c1192.md)|#using failed on '*file*'| -|Fatal error C1193|an error expected in *file*(*line*) not reached| -|Fatal error C1195|use of /Yu and /Yc on the same command line is incompatible with the /clr option| -|[Fatal error C1196](fatal-error-c1196.md)|'*identifier*' : identifier found in type library '*typelib*' is not a valid C++ identifier| -|[Fatal error C1197](../../error-messages/compiler-errors-1/fatal-error-c1197.md)|cannot reference '*file*' as the program has already referenced '*file*'| -|[Fatal error C1201](fatal-error-c1201.md)|unable to continue after syntax error in class template definition| -|[Fatal error C1202](fatal-error-c1202.md)|recursive type or function dependency context too complex| -|[Fatal error C1205](fatal-error-c1205.md)|Generics are not supported by the version of the runtime installed| -|[Fatal error C1206](fatal-error-c1206.md)|Per-appdomain data is not supported by the version of the runtime installed| -|[Fatal error C1207](fatal-error-c1207.md)|Managed templates not supported by the version of the runtime installed| -|[Fatal error C1208](fatal-error-c1208.md)|Allocating reference classes on the stack is not supported by the version of the runtime installed| -|[Fatal error C1209](fatal-error-c1209.md)|Friend assemblies not supported by the version of the runtime installed| -|[Fatal error C1210](fatal-error-c1210.md)|/clr:pure and /clr:safe are not supported by the version of the runtime installed| -|[Fatal error C1211](fatal-error-c1211.md)|The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed| -|Fatal error C1300|error accessing program database *file* (*message*)| -|Fatal error C1301|error accessing program database *file*, invalid format, please delete and rebuild| -|Fatal error C1302|no profile data for module '*module*' in profile database '*file*'| -|[Fatal error C1305](../../error-messages/compiler-errors-1/fatal-error-c1305.md)|profile database '*file*' is for a different architecture| -|Fatal error C1306|last change to profile data base '*file*' was not optimization analysis; optimization decisions may be out of date| -|[Fatal error C1307](../../error-messages/compiler-errors-1/fatal-error-c1307.md)|program has been edited since profile data was collected| -|[Fatal error C1308](../../error-messages/compiler-errors-1/fatal-error-c1308.md)|*file*: linking assemblies is not supported| -|[Fatal error C1309](../../error-messages/compiler-errors-1/fatal-error-c1309.md)|Mismatched versions of C2.DLL and pgodb*ver*.DLL| -|[Fatal error C1310](fatal-error-c1310.md)|profile guided optimizations are not available with OpenMP| -|[Fatal error C1311](../../error-messages/compiler-errors-1/fatal-error-c1311.md)|COFF format cannot statically initialize '*symbol*' with *number* byte(s) of an address| -|[Fatal error C1312](fatal-error-c1312.md)|Too many conditional branches in function. Simplify or refactor source code.| -|[Fatal error C1313](../../error-messages/compiler-errors-1/fatal-error-c1313.md)|compiler limit: *type* blocks may not be nested deeper than *number* levels| -|[Fatal error C1350](../../error-messages/compiler-errors-1/fatal-error-c1350.md)|error loading dll '*file*': dll not found| -|[Fatal error C1351](../../error-messages/compiler-errors-1/fatal-error-c1351.md)|error loading dll '*file*': incompatible version| -|[Fatal error C1352](fatal-error-c1352.md)|Invalid or corrupt MSIL in function '*function*' from module '*module*'| -|[Fatal error C1353](fatal-error-c1353.md)|metadata operation failed: runtime not installed or version mismatch| -|[Fatal error C1382](../../error-messages/compiler-errors-1/fatal-error-c1382.md)|the PCH file '*file*' has been rebuilt since '*obj*' was generated. Please rebuild this object| -|[Fatal error C1383](fatal-error-c1383.md)|compiler option /GL is incompatible with the installed version of common language runtime| -|Fatal error C1384|Incorrect setting for PGO_PATH_TRANSLATION when linking '*file*'| -|Fatal error C1451|Failed to generate debug information when compiling the call graph for the concurrency::parallel_for_each at: '*callsite*'| -|Fatal error C1505|unrecoverable parser look-ahead error| -|[Fatal error C1506](../../error-messages/compiler-errors-1/fatal-error-c1506.md)|unrecoverable block scoping error| -|[Fatal error C1508](fatal-error-c1508.md)|compiler limit: '*function*': more than 65535 argument bytes| -|[Fatal error C1509](../../error-messages/compiler-errors-1/fatal-error-c1509.md)|compiler limit: too many exception handler states in function '*function*'; simplify function| -|[Fatal error C1510](../../error-messages/compiler-errors-1/fatal-error-c1510.md)|Cannot open language resource clui.dll| -|[Fatal error C1601](../../error-messages/compiler-errors-1/fatal-error-c1601.md)|unsupported inline assembly opcode| -|[Fatal error C1602](../../error-messages/compiler-errors-1/fatal-error-c1602.md)|unsupported intrinsic| -|[Fatal error C1603](../../error-messages/compiler-errors-1/fatal-error-c1603.md)|inline assembly branch target out of range by *number* bytes| -|[Fatal error C1852](fatal-error-c1852.md)|'*file*' is not a valid precompiled header file| -|[Fatal error C1853](../../error-messages/compiler-errors-1/fatal-error-c1853.md)|'*file*' precompiled header file is from a previous version of the compiler, or the precompiled header is C++ and you are using it from C (or vice versa)| -|[Fatal error C1854](../../error-messages/compiler-errors-1/fatal-error-c1854.md)|cannot overwrite information formed during creation of the precompiled header in object file: '*file*'| -|[Fatal error C1900](../../error-messages/compiler-errors-1/fatal-error-c1900.md)|Il mismatch between '*tool*' version '*number*' and '*tool*' version '*number*'| -|Fatal error C1901|Internal memory management error| -|[Fatal error C1902](../../error-messages/compiler-errors-1/fatal-error-c1902.md)|Program database manager mismatch; please check your installation| -|[Fatal error C1903](fatal-error-c1903.md)|unable to recover from previous error(s); stopping compilation| -|[Fatal error C1904](fatal-error-c1904.md)|bad provider interaction: '*file*'| -|[Fatal error C1905](../../error-messages/compiler-errors-1/fatal-error-c1905.md)|Front end and back end not compatible (must target same processor).| +| Error | Message | +|--|--| +| [Fatal error C1001](fatal-error-c1001.md) | An internal error has occurred in the compiler.
(compiler file '*file*', line *number*)
To work around this problem, try simplifying or changing the program near the locations listed above. Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information | +| [Fatal error C1002](fatal-error-c1002.md) | compiler is out of heap space in pass 2 | +| [Fatal error C1003](fatal-error-c1003.md) | error count exceeds *number*; stopping compilation | +| [Fatal error C1004](fatal-error-c1004.md) | unexpected end-of-file found | +| [Fatal error C1005](fatal-error-c1005.md) | string too big for buffer | +| Fatal error C1006 | write error on compiler intermediate file | +| [Fatal error C1007](fatal-error-c1007.md) | unrecognized flag '*string*' in '*option*' | +| [Fatal error C1008](fatal-error-c1008.md) | no input file specified | +| [Fatal error C1009](fatal-error-c1009.md) | compiler limit: macros nested too deeply | +| [Fatal error C1010](fatal-error-c1010.md) | unexpected end of file while looking for precompiled header. Did you forget to add '`#include <`*file*`>`' to your source? | +| [Fatal error C1011](fatal-error-c1011.md) | cannot locate standard module interface. Did you install the library part of the C++ modules feature in VS setup? | +| [Fatal error C1012](fatal-error-c1012.md) | unmatched parenthesis: missing '*character*' | +| [Fatal error C1013](fatal-error-c1013.md) | compiler limit: too many open parentheses | +| [Fatal error C1014](fatal-error-c1014.md) | too many include files: depth = *number* | +| [Fatal error C1015](fatal-error-c1015.md) | header-names '*header-name*' and '*header-name*' identify the same header and cannot be used as both `/headerUnit:quoted` and `/headerUnit:angle` arguments; please provide this header-name only once | +| [Fatal error C1016](fatal-error-c1016.md) | `#ifdef`/`#ifndef` expected an identifier | +| [Fatal error C1017](fatal-error-c1017.md) | invalid integer constant expression | +| [Fatal error C1018](fatal-error-c1018.md) | unexpected `#elif` | +| [Fatal error C1019](fatal-error-c1019.md) | unexpected `#else` | +| [Fatal error C1020](fatal-error-c1020.md) | unexpected `#endif` | +| [Fatal error C1021](fatal-error-c1021.md) | invalid preprocessor command '*string*' | +| [Fatal error C1022](fatal-error-c1022.md) | expected `#endif` | +| [Fatal error C1023](fatal-error-c1023.md) | '*file*': unexpected error with pch, try rebuilding the pch | +| Fatal error C1024 | **(Obsolete)** too many symbols | +| [Fatal error C1025](fatal-error-c1025-c1115.md) | too many nested lambdas | +| [Fatal error C1026](fatal-error-c1026.md) | parser stack overflow, program too complex | +| Fatal error C1027 | **(Obsolete)** Inconsistent values for /Ym between creation and use of precompiled header | +| Fatal error C1028 | missing IFC for analysis. Please rebuild *module* '*ifc filename*' with `/analyze`. | +| [Fatal error C1029](fatal-error-c1029.md) | '*filename*': source file hash (*number* bytes) exceeds the IFC format's maximum supported hash size (*number* bytes); use a smaller hash algorithm such as SHA-256 | +| Fatal error C1030 | WMMX types not allowed in the function signature by the calling convention | +| Fatal error C1032 | `__eabi` requires VFP code generation (`/QRfpe-`) | +| [Fatal error C1033](fatal-error-c1033.md) | cannot open program database '*file*' | +| Fatal error C1034 | *file*: no include path set | +| [Fatal error C1035](fatal-error-c1035.md) | expression too complex; simplify expression | +| Fatal error C1036 | cannot overwrite earlier program database format, delete '*file*' and recompile | +| [Fatal error C1037](fatal-error-c1037.md) | cannot open object file '*file*' | +| [Fatal error C1038](fatal-error-c1038.md) | **(Obsolete)** compiler limit: '*function*': control flow state too complex; simplify function | +| Fatal error C1039 | more arguments of intrinsic type than allowed by the calling convention | +| Fatal error C1040 | intrinsic function or type not allowed in Thumb mode | +| Fatal error C1041 | cannot open program database '*file*'; if multiple CL.EXE write to the same `.PDB` file, please use `/FS` | +| Fatal error C1042 | cannot open compiler intermediate file - no such file or directory | +| Fatal error C1043 | cannot open compiler intermediate file | +| Fatal error C1044 | out of disk space for compiler intermediate file | +| [Fatal error C1045](fatal-error-c1045.md) | compiler limit: linkage specifications nested too deeply | +| [Fatal error C1046](fatal-error-c1046.md) | compiler limit: *structure* nested too deeply | +| [Fatal error C1047](fatal-error-c1047.md) | The object or library file '*file*' was created with an older compiler than other objects; rebuild old objects and libraries | +| Fatal error C1048 | unknown option '*string*' in '*option*' | +| [Fatal error C1049](fatal-error-c1049.md) | invalid numerical argument '*value*' | +| [Fatal error C1051](fatal-error-c1051.md) | program database file, '*file*', has an obsolete format, delete it and recompile | +| [Fatal error C1052](fatal-error-c1052.md) | program database file, '*filename*', was generated by the linker with `/DEBUG:fastlink`; compiler cannot update such PDB files; please delete it or use `/Fd` to specify a different PDB filename | +| [Fatal error C1053](fatal-error-c1053.md) | '*function*': function too large | +| [Fatal error C1054](fatal-error-c1054.md) | compiler limit: initializers nested too deeply | +| [Fatal error C1055](fatal-error-c1055.md) | compiler limit: out of keys | +| Fatal error C1056 | cannot update the time date stamp field in '*object-file*'; error code *error-code* | +| [Fatal error C1057](fatal-error-c1057.md) | unexpected end of file in macro expansion | +| Fatal error C1058 | compiler limit: too many attributes on symbol '*symbol-name*' | +| Fatal error C1059 | **(Obsolete)** compiler is out of near heap space | +| [Fatal error C1060](fatal-error-c1060.md) | compiler is out of heap space | +| [Fatal error C1061](fatal-error-c1061.md) | compiler limit: blocks nested too deeply | +| Fatal error C1063 | compiler limit: compiler stack overflow | +| [Fatal error C1064](fatal-error-c1064.md) | compiler limit: token overflowed internal buffer | +| [Fatal error C1065](fatal-error-c1065.md) | compiler limit: out of tags | +| [Fatal error C1067](fatal-error-c1067.md) | compiler limit: 64K limit on size of a type record has been exceeded | +| [Fatal error C1068](fatal-error-c1068.md) | cannot open file '*file*' | +| Fatal error C1069 | cannot read compiler command line | +| [Fatal error C1070](fatal-error-c1070.md) | mismatched `#if`/`#endif` pair in file '*file*' | +| [Fatal error C1071](fatal-error-c1071.md) | unexpected end of file found in comment | +| [Fatal error C1073](fatal-error-c1073.md) | **(Obsolete)** Internal error involving incremental compilation(compiler file '*file*', line *number*) | +| [Fatal error C1074](fatal-error-c1074.md) | 'IDB' is illegal extension for PDB file: *file* | +| [Fatal error C1075](fatal-error-c1075.md) | the left *token* was unmatched at the end of the file | +| [Fatal error C1076](fatal-error-c1076.md) | compiler limit: internal heap limit reached; use `/Zm` to specify a higher limit | +| [Fatal error C1077](fatal-error-c1077.md) | compiler limit: cannot have more than *number* command line options | +| [Fatal error C1079](fatal-error-c1079.md) | **(Obsolete)** compiler limit: PCH file size limit exceeded | +| [Fatal error C1080](fatal-error-c1080.md) | compiler limit: command line option exceeded limit of *number* characters | +| [Fatal error C1081](fatal-error-c1081.md) | '*file*': file name too long | +| [Fatal error C1082](fatal-error-c1082.md) | cannot close *type* file: '*file*': *message* | +| [Fatal error C1083](fatal-error-c1083.md) | cannot open *type* file: '*file*': *message* | +| [Fatal error C1084](fatal-error-c1084.md) | cannot read *type* file: '*file*': *message* | +| [Fatal error C1085](fatal-error-c1085.md) | cannot write *type* file: '*file*': *message* | +| [Fatal error C1086](fatal-error-c1086.md) | cannot seek *type* file: '*file*': *message* | +| [Fatal error C1087](fatal-error-c1087.md) | cannot tell *type* file: '*file*': *message* | +| [Fatal error C1088](fatal-error-c1088.md) | cannot flush *type* file: '*file*': *message* | +| [Fatal error C1089](fatal-error-c1089.md) | cannot truncate *type* file: '*file*': *message* | +| [Fatal error C1090](fatal-error-c1090.md) | PDB API call failed, error code '*code*': '*message*' | +| [Fatal error C1091](fatal-error-c1091.md) | compiler limit: string exceeds *number* bytes in length | +| [Fatal error C1092](fatal-error-c1092.md) | Edit and Continue does not support changes to data types; build required | +| [Fatal error C1093](fatal-error-c1093.md) | API call '*function*' failed '*HRESULT*': '*description*' | +| [Fatal error C1094](fatal-error-c1094.md) | '`-Zm`*number*': command line option is inconsistent with value used to build precompiled header ('`-Zm`*number*') | +| Fatal error C1095 | Failed to locate a free memory range. Use `/Yb` to specify a base address. | +| [Fatal error C1098](fatal-error-c1098.md) | Version mismatch with Edit and Continue engine | +| [Fatal error C1099](fatal-error-c1099.md) | Edit and Continue engine terminating compile | +| [Fatal error C1100](fatal-error-c1100.md) | unable to initialize OLE: *error* | +| Fatal error C1101 | cannot create handler for attribute '*identifier*' | +| Fatal error C1102 | unable to initialize: *error* | +| [Fatal error C1103](fatal-error-c1103.md) | fatal error importing progid: '*message*' | +| [Fatal error C1104](fatal-error-c1104.md) | fatal error importing libid: '*message*' | +| Fatal error C1105 | *message*: *HRESULT error* | +| Fatal error C1106 | compiler limit: only *number* function parameters are allowed | +| [Fatal error C1107](fatal-error-c1107.md) | could not find assembly '*assembly*': please specify the assembly search path using `/AI` or by setting the `LIBPATH` environment variable | +| [Fatal error C1108](fatal-error-c1108.md) | unable to find DLL: '*file*' | +| [Fatal error C1109](fatal-error-c1109.md) | unable to find '*symbol*' in DLL '*file*' | +| Fatal error C1110 | too many nested template/generic definitions | +| Fatal error C1111 | too many template/generic parameters | +| Fatal error C1112 | compiler limit: '*number*' too many macro arguments, only '*number*' allowed | +| [Fatal error C1113](fatal-error-c1113.md) | `#using` failed on '*file*' | +| Fatal error C1114 | '*file*': WinRT does not support `#using` of a managed assembly | +| [Fatal error C1115](fatal-error-c1025-c1115.md) | too many nested lambdas | +| [Fatal error C1116](fatal-error-c1116.md) | unrecoverable error importing module/headerunit '*name*'. Specialization of '*primary-template*' with arguments '*argument-list*' | +| [Fatal error C1117](fatal-error-c1117.md) | unrecoverable error importing module/headerunit '*name*': symbol '*symbol-name*' has already been defined | +| Fatal error C1118 | cannot expand the environment variable *variable-name* in *file-type* filename in object file '*object-file*' | +| Fatal error C1119 | unrecoverable error importing symbol '*symbol-name*' from module '*module-name*' | +| [Fatal error C1120](fatal-error-c1120.md) | call to `GetProcAddress` failed for '*function*' | +| [Fatal error C1121](fatal-error-c1121.md) | call to CryptoAPI failed | +| [Fatal error C1126](fatal-error-c1126.md) | automatic allocation exceeds *size* | +| Fatal error C1127 | *Operation* requires *option* | +| [Fatal error C1128](fatal-error-c1128.md) | number of sections exceeded object file format limit: compile with `/bigobj` | +| [Fatal error C1189](fatal-error-c1189.md) | `#error`: *message* | +| [Fatal error C1190](fatal-error-c1190.md) | `System::Object` not found, missing `/clr` option or missing import of standard assemblies? | +| [Fatal error C1191](fatal-error-c1191.md) | '*file*' can only be imported at global scope | +| [Fatal error C1192](fatal-error-c1192.md) | `#using` failed on '*file*' | +| Fatal error C1193 | an error expected in *file*(*line*) not reached | +| Fatal error C1194 | **(Obsolete)** checkpoint '*name*' expected in *file*(*line*) not reached | +| Fatal error C1195 | use of `/Yu` and `/Yc` on the same command line is incompatible with the `/clr` option | +| [Fatal error C1196](fatal-error-c1196.md) | '*identifier*' : identifier found in type library '*typelib*' is not a valid C++ identifier | +| [Fatal error C1197](fatal-error-c1197.md) | cannot reference '*file*' as the program has already referenced '*file*' | +| Fatal error C1198 | *feature* will be supported in a future release | +| Fatal error C1199 | missing reference to IFC file to resolve an import-declaration; please ensure the proper value for a '`/reference`' or '`/headerUnit`' option is provided | +| [Fatal error C1201](fatal-error-c1201.md) | unable to continue after syntax error in class template definition | +| [Fatal error C1202](fatal-error-c1202.md) | recursive type or function dependency context too complex | +| Fatal error C1203 | invalid symbol name or value specification in `#pragma extern_absolute` | +| Fatal error C1204 | symbol '*symbol-name*' specified in `#pragma extern_absolute` has different values: *value-1* and *value-2* | +| [Fatal error C1205](fatal-error-c1205.md) | **(Obsolete)** Generics are not supported by the version of the runtime installed | +| [Fatal error C1206](fatal-error-c1206.md) | **(Obsolete)** Per-appdomain data is not supported by the version of the runtime installed | +| [Fatal error C1207](fatal-error-c1207.md) | **(Obsolete)** Managed templates not supported by the version of the runtime installed | +| [Fatal error C1208](fatal-error-c1208.md) | **(Obsolete)** Allocating reference classes on the stack is not supported by the version of the runtime installed | +| [Fatal error C1209](fatal-error-c1209.md) | **(Obsolete)** Friend assemblies not supported by the version of the runtime installed | +| [Fatal error C1210](fatal-error-c1210.md) | **(Obsolete)** /clr:pure and /clr:safe are not supported by the version of the runtime installed | +| [Fatal error C1211](fatal-error-c1211.md) | **(Obsolete)** The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed | +| Fatal error C1212 | Input file was modified by another process while building: '*filename*' | +| Fatal error C1213 | Header units are unsupported without `/Zc:preprocessor` | +| Fatal error C1214 | Modules conflict with non-standard behavior requested via '*option*' | +| Fatal error C1215 | Cannot open file '*filename*' corresponding to warning set '`-W`*warning set*' | +| Fatal error C1300 | error accessing program database *file* (*message*) | +| Fatal error C1301 | error accessing program database *file*, invalid format, please delete and rebuild | +| Fatal error C1302 | no profile data for module '*module*' in profile database '*file*' | +| Fatal error C1303 | profile data corrupt in profile database '*filename*' | +| Fatal error C1304 | profile data version mismatch in profile database '*filename*' | +| [Fatal error C1305](fatal-error-c1305.md) | profile database '*file*' is for a different architecture | +| Fatal error C1306 | last change to profile data base '*file*' was not optimization analysis; optimization decisions may be out of date | +| [Fatal error C1307](fatal-error-c1307.md) | program has been edited since profile data was collected | +| [Fatal error C1308](fatal-error-c1308.md) | *file*: linking assemblies is not supported | +| [Fatal error C1309](fatal-error-c1309.md) | Mismatched versions of C2.DLL and pgodb*version*.DLL | +| [Fatal error C1310](fatal-error-c1310.md) | profile guided optimizations are not available with OpenMP | +| [Fatal error C1311](fatal-error-c1311.md) | COFF format cannot statically initialize '*symbol*' with *number* byte(s) of an address | +| [Fatal error C1312](fatal-error-c1312.md) | Too many conditional branches in function. Simplify or refactor source code. | +| [Fatal error C1313](fatal-error-c1313.md) | compiler limit: *type* blocks may not be nested deeper than *number* levels | +| [Fatal error C1350](fatal-error-c1350.md) | error loading dll '*file*': dll not found | +| [Fatal error C1351](fatal-error-c1351.md) | error loading dll '*file*': incompatible version | +| [Fatal error C1352](fatal-error-c1352.md) | Invalid or corrupt MSIL in function '*function*' from module '*module*' | +| [Fatal error C1353](fatal-error-c1353.md) | metadata operation failed: runtime not installed or version mismatch | +| Fatal error C1354 | error accessing previous object file *filename* (*reason*) | +| Fatal error C1355 | unable to find entrypoint '*function-name*' in *PDB helper* | +| Fatal error C1356 | unable to find *PDB helper* | +| Fatal error C1357 | C2.DLL unsupported flag combination *`hybrid:x86arm64, CLR`* | +| Fatal error C1358 | module (key=0x*value*) information unavailable | +| [Fatal error C1382](fatal-error-c1382.md) | the PCH file '*file*' has been rebuilt since '*obj*' was generated. Please rebuild this object | +| [Fatal error C1383](fatal-error-c1383.md) | compiler option `/GL` is incompatible with the installed version of common language runtime | +| Fatal error C1384 | Incorrect setting for PGO_PATH_TRANSLATION when linking '*file*' | +| Fatal error C1385 | profile guided optimizations not available for Thumb; compile '*filename*' as ARM or Thumb-2. | +| Fatal error C1451 | Failed to generate debug information when compiling the call graph for the `concurrency::parallel_for_each` at: '*callsite*' | +| Fatal error C1505 | unrecoverable parser look-ahead error | +| [Fatal error C1506](fatal-error-c1506.md) | unrecoverable block scoping error | +| Fatal error C1507 | previous user errors and subsequent error recovery halt further compilation | +| [Fatal error C1508](fatal-error-c1508.md) | compiler limit: '*function*': more than 65535 argument bytes | +| [Fatal error C1509](fatal-error-c1509.md) | compiler limit: too many exception handler states in function '*function*'; simplify function | +| [Fatal error C1510](fatal-error-c1510.md) | Cannot open language resource clui.dll | +| Fatal error C1511 | *Message* (used by capture_repro option) | +| [Fatal error C1601](fatal-error-c1601.md) | unsupported inline assembly opcode | +| [Fatal error C1602](fatal-error-c1602.md) | unsupported intrinsic | +| [Fatal error C1603](fatal-error-c1603.md) | inline assembly branch target out of range by *number* bytes | +| Fatal error C1604 | fatal lambda parsing error: see the lambda definition beginning on line *number* | +| Fatal error C1605 | compiler limit: object file size cannot exceed 4 GB | +| [Fatal error C1852](fatal-error-c1852.md) | '*file*' is not a valid precompiled header file | +| [Fatal error C1853](fatal-error-c1853.md) | '*file*' precompiled header file is from a previous version of the compiler, or the precompiled header is C++ and you are using it from C (or vice versa) | +| [Fatal error C1854](fatal-error-c1854.md) | cannot overwrite information formed during creation of the precompiled header in object file: '*file*' | +| Fatal error C1859 | **(Obsolete)** '*Message*' unexpected precompiled header error, simply rerunning the compiler might fix this problem | +| [Fatal error C1900](fatal-error-c1900.md) | IL mismatch between '*tool*' version '*number*' and '*tool*' version '*number*' | +| Fatal error C1901 | **(Obsolete)** Internal memory management error | +| [Fatal error C1902](fatal-error-c1902.md) | Program database manager mismatch; please check your installation | +| [Fatal error C1903](fatal-error-c1903.md) | unable to recover from previous error(s); stopping compilation | +| [Fatal error C1904](fatal-error-c1904.md) | bad provider interaction: '*file*' | +| [Fatal error C1905](fatal-error-c1905.md) | Front end and back end not compatible (must target same processor). | +| Fatal error C1906 | assembly reference '*name*' not resolved for type '*type-name*'; missing option '-FU *filename*.dll'? | +| Fatal error C1907 | unable to recover from previous error(s); stopping compilation | ## See also diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1001.md b/docs/error-messages/compiler-errors-1/fatal-error-c1001.md index d2dc62f249f..bcf89b5bd87 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1001.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1001.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1001" title: "Fatal Error C1001" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1001" +ms.date: 11/04/2016 f1_keywords: ["C1001"] helpviewer_keywords: ["C1001"] -ms.assetid: 5736cdb3-22c8-4fad-aa85-d5e0d2b232f4 --- # Fatal Error C1001 > INTERNAL COMPILER ERROR(compiler file *file*, line *number*) +## Remarks + The compiler cannot generate correct code for a construct, often due to the combination of a particular expression and an optimization option, or an issue in parsing. If the compiler file listed has a utc or C2 path segment, it is probably an optimization error. If the file has a cxxfe or c1xx path segment, or is msc1.cpp, it is probably a parser error. If the file named is cl.exe, there is no other information available. You can often fix an optimization problem by removing one or more optimization options. To determine which option is at fault, remove options one at a time and recompile until the error message goes away. The options most commonly responsible are [/Og (Global optimizations)](../../build/reference/og-global-optimizations.md) and [/Oi (Generate Intrinsic Functions)](../../build/reference/oi-generate-intrinsic-functions.md). Once you determine which optimization option is responsible, you can disable it around the function where the error occurs by using the [optimize](../../preprocessor/optimize.md) pragma, and continue to use the option for the rest of the module. For more information about optimization options, see [Optimization best practices](../../build/optimization-best-practices.md). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1002.md b/docs/error-messages/compiler-errors-1/fatal-error-c1002.md index c001659abf6..d254d4e5ced 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1002.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1002.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1002" title: "Fatal Error C1002" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1002" +ms.date: 11/04/2016 f1_keywords: ["C1002"] helpviewer_keywords: ["C1002"] -ms.assetid: bd6d274a-c7b4-43af-8bf2-23c5e442aa22 --- # Fatal Error C1002 -compiler is out of heap space in pass 2 +> compiler is out of heap space in pass 2 + +## Remarks The compiler ran out of dynamic memory space during its second pass, probably due to a program with too many symbols or complex expressions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1003.md b/docs/error-messages/compiler-errors-1/fatal-error-c1003.md index 651a5259eac..453e163d0d4 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1003.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1003.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1003" title: "Fatal Error C1003" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1003" +ms.date: 11/04/2016 f1_keywords: ["C1003"] helpviewer_keywords: ["C1003"] -ms.assetid: 27d2d009-2e0f-41fb-8bfc-372752fbe920 --- # Fatal Error C1003 -error count exceeds number; stopping compilation +> error count exceeds number; stopping compilation + +## Remarks Errors in the program are too numerous to allow recovery. The compiler must terminate. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1004.md b/docs/error-messages/compiler-errors-1/fatal-error-c1004.md index 266090b83c3..e611dbbc9ed 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1004.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1004.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1004" title: "Fatal Error C1004" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1004" +ms.date: 11/04/2016 f1_keywords: ["C1004"] helpviewer_keywords: ["C1004"] -ms.assetid: dbe034b0-6eb0-41b4-a50c-2fccf9e78ad4 --- # Fatal Error C1004 -unexpected end of file found +> unexpected end of file found + +## Remarks The compiler reached the end of a source file without resolving a construct. The code may be missing one of the following elements: @@ -28,7 +29,9 @@ To resolve this error, check for the following: - A source file does not end with a carriage return and line feed. -The following sample generates C1004: +## Example + +The following example generates C1004: ```cpp // C1004.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1005.md b/docs/error-messages/compiler-errors-1/fatal-error-c1005.md index cbb2d4aa5b2..2d2a87369b9 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1005.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1005.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1005" title: "Fatal Error C1005" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1005" +ms.date: 11/04/2016 f1_keywords: ["C1005"] helpviewer_keywords: ["C1005"] -ms.assetid: 150daf8e-a38a-4669-9c1a-a05b5a1f65ef --- # Fatal Error C1005 -string too big for buffer +> string too big for buffer + +## Remarks A string in a compiler intermediate file overflowed a buffer. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1007.md b/docs/error-messages/compiler-errors-1/fatal-error-c1007.md index 23d81272a56..55a3c31b1da 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1007.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1007.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1007" title: "Fatal Error C1007" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1007" +ms.date: 11/04/2016 f1_keywords: ["C1007"] helpviewer_keywords: ["C1007"] -ms.assetid: 224f7e2c-4522-4e09-b455-8d293bdb799d --- # Fatal Error C1007 -unrecognized flag string in option +> unrecognized flag string in option + +## Remarks The command-line option contains an invalid string. Check the **CL** command line and environment variable for errors. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1008.md b/docs/error-messages/compiler-errors-1/fatal-error-c1008.md index df73ac1ebd3..1ad6c868baf 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1008.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1008.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1008" title: "Fatal Error C1008" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1008" +ms.date: 11/04/2016 f1_keywords: ["C1008"] helpviewer_keywords: ["C1008"] -ms.assetid: 7de729e3-b2ca-4a68-95ab-8a1c920f3f2c --- # Fatal Error C1008 -no input file specified +> no input file specified + +## Remarks The compiler was not given a C or C++ source file to compile. Check the **CL** command line and environment variable for filename specifications. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1009.md b/docs/error-messages/compiler-errors-1/fatal-error-c1009.md index 358d670bec1..5ba6678782b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1009.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1009.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1009" title: "Fatal Error C1009" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1009" +ms.date: 11/04/2016 f1_keywords: ["C1009"] helpviewer_keywords: ["C1009"] -ms.assetid: dcc8383c-3362-4c47-9c26-25d2451ebd53 --- # Fatal Error C1009 -compiler limit : macros nested too deeply +> compiler limit : macros nested too deeply + +## Remarks The compiler tried to expand too many macros at the same time. The compiler has a limit of 256 levels of nested macros. Split nested macros into simpler macros. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1010.md b/docs/error-messages/compiler-errors-1/fatal-error-c1010.md index 775bed37190..eb64115ebd9 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1010.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1010.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Fatal Error C1010" title: "Fatal Error C1010" -ms.date: "09/03/2019" +description: "Learn more about: Fatal Error C1010" +ms.date: 09/03/2019 f1_keywords: ["C1010"] helpviewer_keywords: ["C1010"] -ms.assetid: dfd035f1-a7a2-40bc-bc92-dc4d7f456767 --- # Fatal Error C1010 diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1011.md b/docs/error-messages/compiler-errors-1/fatal-error-c1011.md new file mode 100644 index 00000000000..b50d6450ef6 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1011.md @@ -0,0 +1,24 @@ +--- +title: "Fatal Error C1011" +description: "Learn more about: Fatal Error C1011" +ms.date: 08/17/2022 +f1_keywords: ["C1011"] +helpviewer_keywords: ["C1011"] +--- +# Fatal Error C1011 + +> cannot locate standard module interface. Did you install the library part of the C++ modules feature in VS setup? + +## Remarks + +Use of standard modules requires the **C++ Modules for *version* build tools** component. You can add the component to your Visual Studio installation by using the Visual Studio Installer. + +## To install the C++ Modules build tools + +1. Open the Visual Studio Installer. In Visual Studio Installer, choose **Modify** next to your installation of Visual Studio, and then select the **Individual components** tab. + +1. In the **Individual components** list, scroll down to **Compilers, build tools, and runtimes** and select the **C++ Modules for *version* build tools** component. + +1. Choose **Modify** to continue with the installation. + +When installation completes, you're ready to use C++ Modules in Visual Studio. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1012.md b/docs/error-messages/compiler-errors-1/fatal-error-c1012.md index 3de04be3d2c..33245ef2b6c 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,25 @@ --- -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' + +## Remarks The parentheses in a preprocessor directive do not match. + +## Example + +The following example generates C1012: + +```cpp +// C1012.cpp +// compile with: /c +#if (0 // C1012 +#endif +``` diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1013.md b/docs/error-messages/compiler-errors-1/fatal-error-c1013.md index c8950e24e8a..f0f85a0ee1a 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1013.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1013.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1013" title: "Fatal Error C1013" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1013" +ms.date: 11/04/2016 f1_keywords: ["C1013"] helpviewer_keywords: ["C1013"] -ms.assetid: 5514a679-efe7-4055-bdd3-5693ca0c332f --- # Fatal Error C1013 -compiler limit : too many open parentheses +> compiler limit : too many open parentheses + +## Remarks An expression contains too many levels of parentheses in a single expression. Simplify the expression or break it into multiple statements. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1014.md b/docs/error-messages/compiler-errors-1/fatal-error-c1014.md index 084aa82fad9..678465c1973 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1014.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1014.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1014" title: "Fatal Error C1014" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1014" +ms.date: 11/04/2016 f1_keywords: ["C1014"] helpviewer_keywords: ["C1014"] -ms.assetid: 4c01ef70-e765-4d07-a3fe-a11c19fb610b --- # Fatal Error C1014 -too many include files : depth = level +> too many include files : depth = level + +## Remarks The nesting of `#include` directives is too deep. Nested directives can include open files. The source file containing the directive counts as one file. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1015.md b/docs/error-messages/compiler-errors-1/fatal-error-c1015.md new file mode 100644 index 00000000000..7b161e0ef81 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1015.md @@ -0,0 +1,14 @@ +--- +title: "Fatal Error C1015" +description: "Learn more about: Fatal Error C1015" +ms.date: 08/17/2022 +f1_keywords: ["C1015"] +helpviewer_keywords: ["C1015"] +--- +# Fatal Error C1015 + +> header-names '*header-name*' and '*header-name*' identify the same header and cannot be used as both `/headerUnit:quote` and `/headerUnit:angle` arguments; please provide this header-name only once + +## Remarks + +Don't include a header unit using both double-quotes and angle brackets. Use only one form, consistent with the **`/headerUnit:quote`** or **`/headerUnit:angle`** compiler option. For more information, see [`/headerUnit` (Use header unit IFC)](../../build/reference/headerunit.md). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1016.md b/docs/error-messages/compiler-errors-1/fatal-error-c1016.md index c921566c37a..5dc38afa6a8 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1016.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1016.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1016" title: "Fatal Error C1016" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1016" +ms.date: 11/04/2016 f1_keywords: ["C1016"] helpviewer_keywords: ["C1016"] -ms.assetid: 33f45c3e-2d8f-43ad-a445-c412d1d54ce1 --- # Fatal Error C1016 -\#ifdef expected an identifier#ifndef expected an identifier +> #ifdef expected an identifier#ifndef expected an identifier + +## Remarks The conditional compilation directive ([#ifdef](../../preprocessor/hash-ifdef-and-hash-ifndef-directives-c-cpp.md) or `#ifndef`) has no identifier to evaluate. To resolve the error, specify an identifier. -The following sample generates C1016: +## Example + +The following example generates C1016: ```cpp // C1016.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1017.md b/docs/error-messages/compiler-errors-1/fatal-error-c1017.md index cd6fbcbc772..7ae9f9c0d6a 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1017.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1017.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Fatal Error C1017" title: "Fatal Error C1017" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1017" +ms.date: 11/04/2016 f1_keywords: ["C1017"] helpviewer_keywords: ["C1017"] -ms.assetid: 5542e604-599d-4e36-8f83-1d454c5753c9 --- # Fatal Error C1017 -invalid integer constant expression +> invalid integer constant expression + +## Remarks The expression in an `#if` directive did not exist or did not evaluate to a constant. Constants defined using `#define` must have values that evaluate to an integer constant if they are used in an `#if`, `#elif`, or `#else` directive. -The following sample generates C1017: +## Example + +The following example generates C1017: ```cpp // C1017.cpp @@ -35,7 +38,7 @@ Possible resolution: Because `CONSTANT_NAME` evaluates to a string and not an integer, the `#if` directive generates fatal error C1017. -In other cases, the preprocessor evaluates an undefined constant as zero. This can cause unintended results, as shown in the following sample. `YES` is undefined, so it evaluates to zero. The expression `#if` `CONSTANT_NAME` evaluates to false and the code to be used on `YES` is removed by the preprocessor. `NO` is also undefined (zero), so `#elif` `CONSTANT_NAME==NO` evaluates to true (`0 == 0`), causing the preprocessor to leave the code in the `#elif` portion of the statement — exactly the opposite of the intended behavior. +In other cases, the preprocessor evaluates an undefined constant as zero. This can cause unintended results, as shown in the following example. `YES` is undefined, so it evaluates to zero. The expression `#if` `CONSTANT_NAME` evaluates to false and the code to be used on `YES` is removed by the preprocessor. `NO` is also undefined (zero), so `#elif` `CONSTANT_NAME==NO` evaluates to true (`0 == 0`), causing the preprocessor to leave the code in the `#elif` portion of the statement — exactly the opposite of the intended behavior. ```cpp // C1017c.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1018.md b/docs/error-messages/compiler-errors-1/fatal-error-c1018.md index 4283dedc9d1..6a4fd9b145c 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1018.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1018.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1018" title: "Fatal Error C1018" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1018" +ms.date: 11/04/2016 f1_keywords: ["C1018"] helpviewer_keywords: ["C1018"] -ms.assetid: 2ceb8a99-30b2-4b80-bf42-e9f3305b3c52 --- # Fatal Error C1018 -unexpected #elif +> unexpected #elif + +## Remarks The `#elif` directive appears outside an `#if`, `#ifdef`, or `#ifndef` construct. Use `#elif` only within one of these constructs. -The following sample generates C1018: +## Example + +The following example generates C1018: ```cpp // C1018.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1019.md b/docs/error-messages/compiler-errors-1/fatal-error-c1019.md index 5d51ab87de9..b03103db4e3 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1019.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1019.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1019" title: "Fatal Error C1019" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1019" +ms.date: 11/04/2016 f1_keywords: ["C1019"] helpviewer_keywords: ["C1019"] -ms.assetid: c4f8968b-bc62-4200-b3ca-69d06c163236 --- # Fatal Error C1019 -unexpected #else +> unexpected #else + +## Remarks The `#else` directive appears outside an `#if`, `#ifdef`, or `#ifndef` construct. Use `#else` only within one of these constructs. -The following sample generates C1019: +## Example + +The following example generates C1019: ```cpp // C1019.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1020.md b/docs/error-messages/compiler-errors-1/fatal-error-c1020.md index 3e377cf4739..877bba743f4 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1020.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1020.md @@ -1,18 +1,23 @@ --- -description: "Learn more about: Fatal Error C1020" title: "Fatal Error C1020" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1020" +ms.date: 07/11/2022 f1_keywords: ["C1020"] helpviewer_keywords: ["C1020"] -ms.assetid: 42f429e2-5e3b-4086-a10d-b99e032e51c5 --- # Fatal Error C1020 -unexpected #endif +> unexpected #endif + +## Remarks The `#endif` directive has no matching `#if`, `#ifdef`, or `#ifndef` directive. Be sure each `#endif` has a matching directive. -The following sample generates C1020: +This error can occur if you have conditional preprocessor directives before you include a precompiled header file. The compiler ignores everything in the file before the precompiled header, including any `#if`, `#ifdef`, or `#ifndef` directives. For more information, see [`/Yu` (Use precompiled header)](../../build/reference/yu-use-precompiled-header-file.md). + +## Example + +The following example generates C1020: ```cpp // C1020.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1021.md b/docs/error-messages/compiler-errors-1/fatal-error-c1021.md index 352339095ed..4e45879b395 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1021.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1021.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1021" title: "Fatal Error C1021" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1021" +ms.date: 11/04/2016 f1_keywords: ["C1021"] helpviewer_keywords: ["C1021"] -ms.assetid: e23171f4-ca6b-40c0-a913-a2edc6fa3766 --- # Fatal Error C1021 -invalid preprocessor command 'string' +> invalid preprocessor command 'string' + +## Remarks `string` is not a valid [preprocessor directive](../../preprocessor/preprocessor-directives.md). To resolve the error, use a valid preprocessor name for `string`. -The following sample generates C1021: +## Example + +The following example generates C1021: ```cpp // C1021.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1022.md b/docs/error-messages/compiler-errors-1/fatal-error-c1022.md index 043664fee8b..365d7c9b8f5 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1022.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1022.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1022" title: "Fatal Error C1022" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1022" +ms.date: 11/04/2016 f1_keywords: ["C1022"] helpviewer_keywords: ["C1022"] -ms.assetid: edada720-dc73-49bc-bd93-a7945a316312 --- # Fatal Error C1022 -expected #endif +> expected #endif + +## Remarks An `#if`, `#ifdef`, or `#ifndef` directive has no matching `#endif` directive. Be sure each `#if`, `#ifdef`, or `#ifndef` has a matching `#endif`. -The following sample generates C1022: +## Example + +The following example generates C1022: ```cpp // C1022.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1023.md b/docs/error-messages/compiler-errors-1/fatal-error-c1023.md index ccfc54d80c6..48c1c71a23d 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1023.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1023.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1023" title: "Fatal Error C1023" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1023" +ms.date: 11/04/2016 f1_keywords: ["C1023"] helpviewer_keywords: ["C1023"] -ms.assetid: 727b4070-7474-420b-ab11-6530f96c794f --- # Fatal Error C1023 -'file' : unexpected error with pch, try rebuilding the pch +> 'file' : unexpected error with pch, try rebuilding the pch + +## Remarks C1023 could be caused by one of several problems, the solution to which is a rebuild of the precompiled header file. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1025-c1115.md b/docs/error-messages/compiler-errors-1/fatal-error-c1025-c1115.md new file mode 100644 index 00000000000..cd5353d6cfa --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1025-c1115.md @@ -0,0 +1,14 @@ +--- +title: "Fatal Error C1025, C1115" +description: "Learn more about: Fatal Error C1025, C1115" +ms.date: 08/17/2022 +f1_keywords: ["C1025", "C1115"] +helpviewer_keywords: ["C1025", "C1115"] +--- +# Fatal Error C1025, C1115 + +> too many nested lambdas + +## Remarks + +The compiler detected more than an internal limit for nested lambdas in the same scope. The limit is 65,535 in recent versions of Visual Studio. To resolve this issue, reduce the number of nested lambdas in the current scope. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1026.md b/docs/error-messages/compiler-errors-1/fatal-error-c1026.md index b210727debf..adc8b235f2b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1026.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1026.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1026" title: "Fatal Error C1026" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1026" +ms.date: 11/04/2016 f1_keywords: ["C1026"] helpviewer_keywords: ["C1026"] -ms.assetid: 89bb9d40-673a-44aa-a9f4-b42c07b49d44 --- # Fatal Error C1026 -parser stack overflow, program too complex +> parser stack overflow, program too complex + +## Remarks The space required to parse the program caused a compiler stack overflow. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1029.md b/docs/error-messages/compiler-errors-1/fatal-error-c1029.md new file mode 100644 index 00000000000..c5e1b7e5018 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1029.md @@ -0,0 +1,17 @@ +--- +title: "Fatal error C1029" +description: "Learn more about: Fatal error C1029" +ms.date: 05/25/2026 +ai-usage: ai-assisted +f1_keywords: ["C1029"] +helpviewer_keywords: ["C1029"] +--- +# Fatal error C1029 + +> '*filename*': source file hash (*number* bytes) exceeds the IFC format's maximum supported hash size (*number* bytes); use a smaller hash algorithm such as SHA-256 + +## Remarks + +This error occurs when you compile a C++ module (or header unit) with a [`/ZH`](../../build/reference/zh.md) hash algorithm that produces a checksum larger than the current IFC format supports. The **`/ZH:SHA384`** and **`/ZH:SHA512`** options produce checksums that exceed this limit. These algorithms are available starting in Visual Studio 2026 version 18.6.0 and MSVC version 14.51. + +To fix this error, use **`/ZH:SHA_256`** or a smaller hash algorithm (such as **`/ZH:SHA1`** or **`/ZH:MD5`**) when you compile modules or header units. The default **`/ZH:SHA_256`** option works correctly with IFC files. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1033.md b/docs/error-messages/compiler-errors-1/fatal-error-c1033.md index 74b6260d6d9..5e5ab6734b9 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1033.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1033.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1033" title: "Fatal Error C1033" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1033" +ms.date: 11/04/2016 f1_keywords: ["C1033"] helpviewer_keywords: ["C1033"] -ms.assetid: 09976c03-8450-4cf7-8b43-1b91c2c2b9f9 --- # Fatal Error C1033 -cannot open program database pdb +> cannot open program database pdb + +## Remarks This error can be caused by a disk error, a temporary lock created by an anti-virus program, a previous debugger instance that has not fully shut down, or parallel build mspdbsrv.exe processes that attempt to access the same file, among other possible causes. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1035.md b/docs/error-messages/compiler-errors-1/fatal-error-c1035.md index b41d21a1702..ddeb60ad0fc 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1035.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1035.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1035" title: "Fatal Error C1035" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1035" +ms.date: 11/04/2016 f1_keywords: ["C1035"] helpviewer_keywords: ["C1035"] -ms.assetid: 28cdccee-4377-4823-a4d8-89ca7229a83e --- # Fatal Error C1035 -expression too complex; simplify expression +> expression too complex; simplify expression + +## Remarks The compiler could not generate code for a complex expression. Split the expression into simpler expressions and recompile. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1037.md b/docs/error-messages/compiler-errors-1/fatal-error-c1037.md index 80eecc85dfe..ccc83f0680e 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1037.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1037.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1037" title: "Fatal Error C1037" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1037" +ms.date: 11/04/2016 f1_keywords: ["C1037"] helpviewer_keywords: ["C1037"] -ms.assetid: 79103bca-ccfb-42e7-aef9-9b90c15b162f --- # Fatal Error C1037 -cannot open object file filename +> cannot open object file filename + +## Remarks The object file specified by [/Fo](../../build/reference/fo-object-file-name.md) cannot be opened. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1038.md b/docs/error-messages/compiler-errors-1/fatal-error-c1038.md index 8a2bd8bd22c..ac3e9b80f8d 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1038.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1038.md @@ -1,13 +1,16 @@ --- -description: "Learn more about: Fatal Error C1038" title: "Fatal Error C1038" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1038" +ms.date: 08/17/2022 f1_keywords: ["C1038"] helpviewer_keywords: ["C1038"] -ms.assetid: 560dccb8-5b45-46f0-9412-caa4a6172aef --- # Fatal Error C1038 -compiler limit : function : control flow state too complex; simplify function +> compiler limit : function : control flow state too complex; simplify function + +## Remarks The function has more control-flow states than the compiler can handle. Simplify control flow or split the function into smaller functions. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1045.md b/docs/error-messages/compiler-errors-1/fatal-error-c1045.md index ec28119696b..5251ca128ef 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1045.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1045.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1045" title: "Fatal Error C1045" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1045" +ms.date: 11/04/2016 f1_keywords: ["C1045"] helpviewer_keywords: ["C1045"] -ms.assetid: 766c2f89-4ecd-4281-adaa-14b270cc0829 --- # Fatal Error C1045 -compiler limit : linkage specifications nested too deeply +> compiler limit : linkage specifications nested too deeply + +## Remarks Nested externals exceed the compiler limit. Nested externals are allowed with the external linkage type, such as **`extern`** "C++". Reduce the number of nested externals to resolve the error. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1046.md b/docs/error-messages/compiler-errors-1/fatal-error-c1046.md index 94f902b2fda..66d20348517 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1046.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1046.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1046" title: "Fatal Error C1046" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1046" +ms.date: 11/04/2016 f1_keywords: ["C1046"] helpviewer_keywords: ["C1046"] -ms.assetid: 822ec5f5-b0b0-4711-99e1-fc237b619af6 --- # Fatal Error C1046 -compiler limit : structure nested too deeply +> compiler limit : structure nested too deeply + +## Remarks The structure, union, or class exceeded the nesting limit, which is 15 levels. Rewrite the definition to reduce the nesting level. Split the structure, union, or class into two or more parts by using **`typedef`** to define one or more of the nested structures. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1047.md b/docs/error-messages/compiler-errors-1/fatal-error-c1047.md index c868dfe4150..caf2bd6d441 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1047.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1047.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Fatal Error C1047" title: "Fatal Error C1047" +description: "Learn more about: Fatal Error C1047" ms.date: 10/22/2021 f1_keywords: ["C1047"] helpviewer_keywords: ["C1047"] diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1049.md b/docs/error-messages/compiler-errors-1/fatal-error-c1049.md index 3a658b4c494..81455150da0 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1049.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1049.md @@ -1,7 +1,7 @@ --- title: "Fatal Error C1049" description: "Describes compiler fatal error C1049, invalid numerical argument, and explains how to resolve it." -ms.date: "11/04/2019" +ms.date: 11/04/2019 f1_keywords: ["C1049"] helpviewer_keywords: ["C1049"] --- @@ -9,9 +9,11 @@ helpviewer_keywords: ["C1049"] > invalid numerical argument '*value*' +## Remarks + The CL.EXE command-line parser found *value* where it was expecting a numerical argument. -A C1049 error may occur when the compiler can’t find a numerical argument for one of these compiler options: +A C1049 error may occur when the compiler can't find a numerical argument for one of these compiler options: [/constexpr:depth](../../build/reference/constexpr-control-constexpr-evaluation.md)\ [/constexpr:backtrace](../../build/reference/constexpr-control-constexpr-evaluation.md)\ diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1051.md b/docs/error-messages/compiler-errors-1/fatal-error-c1051.md index da1b46802d4..d2aab16d092 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1051.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1051.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1051" title: "Fatal Error C1051" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1051" +ms.date: 11/04/2016 f1_keywords: ["C1051"] helpviewer_keywords: ["C1051"] -ms.assetid: 87dcbd3b-0952-499a-bd42-64f9e8de2605 --- # Fatal Error C1051 -program database file, 'pdbfile', has an obsolete format, delete it and recompile +> program database file, 'pdbfile', has an obsolete format, delete it and recompile + +## Remarks The compiler cannot update the program database file, which has an older version number. Delete the file and recompile your program with **/Zi** or **/ZI**. For more information, see [/Z7, /Zi, /ZI (Debug Information Format)](../../build/reference/z7-zi-zi-debug-information-format.md) diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1052.md b/docs/error-messages/compiler-errors-1/fatal-error-c1052.md index 7a564c3f29f..37f4cfe70cf 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1052.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1052.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1052" title: "Fatal Error C1052" -ms.date: "05/08/2017" +description: "Learn more about: Fatal Error C1052" +ms.date: 05/08/2017 f1_keywords: ["C1052"] helpviewer_keywords: ["C1052"] -ms.assetid: f2c09a2f-d3c1-4420-9501-ffcb65caf87b --- # Fatal Error C1052 > program database file, '*filename*', was generated by the linker with /DEBUG:fastlink; compiler cannot update such PDB files; please delete it or use /Fd to specify a different PDB filename +## Remarks + The compiler cannot update the same program database (PDB) files which are generated by the linker when the [/DEBUG:fastlink](../../build/reference/debug-generate-debug-info.md) option is specified. Normally the compiler-generated PDB files and the linker-generated PDB files have different names. However, if they are set to use the same names, this error can result. To fix this issue, you can explicitly delete the PDB files before you compile again, or you can create different names for the compiler-generated and linker-generated PDB files. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1053.md b/docs/error-messages/compiler-errors-1/fatal-error-c1053.md index b97c1b622f9..111e9c5fcb5 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1053.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1053.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1053" title: "Fatal Error C1053" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1053" +ms.date: 11/04/2016 f1_keywords: ["C1053"] helpviewer_keywords: ["C1053"] -ms.assetid: f50c1c6a-d9cc-42fa-984e-4e2e6e9cd1b1 --- # Fatal Error C1053 -'\' : function too large +> '\' : function too large + +## Remarks The function is too large to compile. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1054.md b/docs/error-messages/compiler-errors-1/fatal-error-c1054.md index ff4963cff7c..826abb49061 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1054.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1054.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1054" title: "Fatal Error C1054" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1054" +ms.date: 11/04/2016 f1_keywords: ["C1054"] helpviewer_keywords: ["C1054"] -ms.assetid: 9cfb7307-b22a-4418-b7c0-2621b0ab5b1b --- # Fatal Error C1054 -compiler limit : initializers nested too deeply +> compiler limit : initializers nested too deeply + +## Remarks The code exceeds the nesting limit on initializers (10-15 levels, depending on the combination of types being initialized). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1055.md b/docs/error-messages/compiler-errors-1/fatal-error-c1055.md index b60f41acd71..d3106aef984 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1055.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1055.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1055" title: "Fatal Error C1055" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1055" +ms.date: 11/04/2016 f1_keywords: ["C1055"] helpviewer_keywords: ["C1055"] -ms.assetid: a9fb9190-d7eb-4d5f-b1a2-a41e584a28c1 --- # Fatal Error C1055 -compiler limit : out of keys +> compiler limit : out of keys + +## Remarks The source file contains too many symbols. The compiler ran out of hash keys for the symbol table. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1057.md b/docs/error-messages/compiler-errors-1/fatal-error-c1057.md index 238df928a73..646398bb393 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1057.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1057.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1057" title: "Fatal Error C1057" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1057" +ms.date: 11/04/2016 f1_keywords: ["C1057"] helpviewer_keywords: ["C1057"] -ms.assetid: 1e67e727-963d-42c5-8c32-c0e370d32735 --- # Fatal Error C1057 -unexpected end of file in macro expansion +> unexpected end of file in macro expansion + +## Remarks The compiler reached the end of the source file while gathering macro-invocation arguments, probably due to a missing right parenthesis in the macro invocation. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1060.md b/docs/error-messages/compiler-errors-1/fatal-error-c1060.md index 60e1f7a1e32..d3d409b2d1a 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1060.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1060.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1060" title: "Fatal Error C1060" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1060" +ms.date: 11/04/2016 f1_keywords: ["C1060"] helpviewer_keywords: ["C1060"] -ms.assetid: feaf305c-c84c-4160-b974-50e283412849 --- # Fatal Error C1060 -compiler is out of heap space +> compiler is out of heap space + +## Remarks The operating system or run-time library cannot fill a request for memory. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1061.md b/docs/error-messages/compiler-errors-1/fatal-error-c1061.md index 9e17fd39f86..96b7691a600 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1061.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1061.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1061" title: "Fatal Error C1061" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1061" +ms.date: 11/04/2016 f1_keywords: ["C1061"] helpviewer_keywords: ["C1061"] -ms.assetid: 9366c0bc-96e0-4967-aa7d-4ebf098de806 --- # Fatal Error C1061 -compiler limit : blocks nested too deeply +> compiler limit : blocks nested too deeply + +## Remarks Nesting of code blocks exceeds the limit of 128 nesting levels. This is a hard limit in the compiler for both C and C++, in both the 32-bit and 64-bit tool set. The count of nesting levels can be increased by anything that creates a scope or block. For example, namespaces, using directives, preprocessor expansions, template expansion, exception handling, loop constructs, and else-if clauses can all increase the nesting level seen by the compiler. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1064.md b/docs/error-messages/compiler-errors-1/fatal-error-c1064.md index e3f16ff5dca..c1469fc91e9 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1064.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1064.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1064" title: "Fatal Error C1064" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1064" +ms.date: 11/04/2016 f1_keywords: ["C1064"] helpviewer_keywords: ["C1064"] -ms.assetid: d4598a28-b8f6-4e78-a0c6-db324f5bdfc3 --- # Fatal Error C1064 -compiler limit : token overflowed internal buffer +> compiler limit : token overflowed internal buffer + +## Remarks An identifier exceeds the length of the internal buffer used for identifiers. Shorten the name. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1065.md b/docs/error-messages/compiler-errors-1/fatal-error-c1065.md index 2db2bf5c213..b0650fec32c 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1065.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1065.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1065" title: "Fatal Error C1065" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1065" +ms.date: 11/04/2016 f1_keywords: ["C1065"] helpviewer_keywords: ["C1065"] -ms.assetid: 80a27e13-696d-4199-a284-0d6b07446ff3 --- # Fatal Error C1065 -compiler limit : out of tags +> compiler limit : out of tags + +## Remarks The source file contains more than 65,523 classes, structs, unions, namespaces, or enums. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1067.md b/docs/error-messages/compiler-errors-1/fatal-error-c1067.md index b9d556d5a6d..f9a3bfd24eb 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1067.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1067.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1067" title: "Fatal Error C1067" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1067" +ms.date: 11/04/2016 f1_keywords: ["C1067"] helpviewer_keywords: ["C1067"] -ms.assetid: e2c94be6-4573-4571-aac9-73d657fe9f96 --- # Fatal Error C1067 -compiler limit : 64K limit on size of a type record has been exceeded +> compiler limit : 64K limit on size of a type record has been exceeded + +## Remarks This error could occur if a symbol has a decorated name exceeding 247 characters. To resolve, shorten the symbol name. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1068.md b/docs/error-messages/compiler-errors-1/fatal-error-c1068.md index ff9d25709d3..86414b26597 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1068.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1068.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1068" title: "Fatal Error C1068" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1068" +ms.date: 11/04/2016 f1_keywords: ["C1068"] helpviewer_keywords: ["C1068"] -ms.assetid: 3b4abd16-4552-4900-84be-54f6ebb6c785 --- # Fatal Error C1068 -cannot open file 'file' +> cannot open file 'file' + +## Remarks Ensure that `file` is not in use by another program. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1070.md b/docs/error-messages/compiler-errors-1/fatal-error-c1070.md index a1cc8f0a774..df482bb1aad 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1070.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1070.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1070" title: "Fatal Error C1070" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1070" +ms.date: 11/04/2016 f1_keywords: ["C1070"] helpviewer_keywords: ["C1070"] -ms.assetid: 1058269a-5db6-4c23-a97f-b5269eb9188b --- # Fatal Error C1070 -mismatched #if/#endif pair in file 'filename' +> mismatched #if/#endif pair in file 'filename' + +## Remarks An `#if`, `#ifdef`, or `#ifndef` directive has no corresponding `#endif`. -The following sample generates C1070: +## Example + +The following example generates C1070: ```cpp // C1070.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1071.md b/docs/error-messages/compiler-errors-1/fatal-error-c1071.md index 82f1926458f..bb3ba4b6f51 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1071.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1071.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1071" title: "Fatal Error C1071" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1071" +ms.date: 11/04/2016 f1_keywords: ["C1071"] helpviewer_keywords: ["C1071"] -ms.assetid: 489f1786-370e-4ecd-af67-538fe6e5bd4e --- # Fatal Error C1071 -unexpected end of file found in comment +> unexpected end of file found in comment + +## Remarks The compiler reached the end of the file while scanning a comment. @@ -18,7 +19,9 @@ The compiler reached the end of the file while scanning a comment. 1. Missing newline character after a comment on the last line of a source file. -The following sample generates C1071: +## Example + +The following example generates C1071: ```cpp // C1071.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1073.md b/docs/error-messages/compiler-errors-1/fatal-error-c1073.md index 74e63dc932b..8a58d0814ab 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1073.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1073.md @@ -1,13 +1,16 @@ --- -description: "Learn more about: Fatal Error C1073" title: "Fatal Error C1073" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1073" +ms.date: 08/17/2022 f1_keywords: ["C1073"] helpviewer_keywords: ["C1073"] -ms.assetid: a946fcf1-674e-4a7a-a28c-b1effacbabe1 --- # Fatal Error C1073 -Internal error involving incremental compilation (compiler file 'filename', line number) +> Internal error involving incremental compilation (compiler file '*filename*', line *number*) + +## Remarks Recompile the file without using incremental compilation. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1074.md b/docs/error-messages/compiler-errors-1/fatal-error-c1074.md index 4058a24309d..0966a7fdc7c 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1074.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1074.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1074" title: "Fatal Error C1074" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1074" +ms.date: 11/04/2016 f1_keywords: ["C1074"] helpviewer_keywords: ["C1074"] -ms.assetid: 979d4ab2-0f1a-472a-85f8-71f48297274f --- # Fatal Error C1074 -'IDB' is illegal extension for PDB file: filename +> 'IDB' is illegal extension for PDB file: filename + +## Remarks The compiler expects program databases to have the .pdb extension. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1075.md b/docs/error-messages/compiler-errors-1/fatal-error-c1075.md index e63540537d6..8ecce1735e7 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1075.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1075.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1075" title: "Fatal Error C1075" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1075" +ms.date: 11/04/2016 f1_keywords: ["C1075"] helpviewer_keywords: ["C1075"] -ms.assetid: 69a74e3d-b53f-4526-a440-2c94e6403355 --- # Fatal Error C1075 -the left token was unmatched at the end of the file +> the left token was unmatched at the end of the file + +## Remarks The compiler expected matching *token* before it reached the end of file. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1076.md b/docs/error-messages/compiler-errors-1/fatal-error-c1076.md index 42d68e82109..e0851683ca6 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1076.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1076.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1076" title: "Fatal Error C1076" -ms.date: "03/08/2019" +description: "Learn more about: Fatal Error C1076" +ms.date: 03/08/2019 f1_keywords: ["C1076"] helpviewer_keywords: ["C1076"] -ms.assetid: 84ac1180-3e8a-48e8-9f77-7f18a778b964 --- # Fatal Error C1076 > compiler limit : internal heap limit reached; use /Zm to specify a higher limit +## Remarks + This error can be caused by too many symbols, or too many template instantiations. Starting in Visual Studio 2015, this message may result from Windows virtual memory pressure caused by too many parallel build processes. In this case, the recommendation to use the **/Zm** option should be ignored unless you are using a `#pragma hdrstop` directive. To resolve this error: diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1077.md b/docs/error-messages/compiler-errors-1/fatal-error-c1077.md index a759bcabfab..fb66328c987 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1077.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1077.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1077" title: "Fatal Error C1077" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1077" +ms.date: 11/04/2016 f1_keywords: ["C1077"] helpviewer_keywords: ["C1077"] -ms.assetid: 514d66f4-b512-479a-b793-ebf45c91e15b --- # Fatal Error C1077 -compiler limit : cannot have more than number command line options +> compiler limit : cannot have more than number command line options + +## Remarks The number of command-line options exceeds the internal limit. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1079.md b/docs/error-messages/compiler-errors-1/fatal-error-c1079.md index e381ae6398b..0b3c3710186 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1079.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1079.md @@ -1,13 +1,16 @@ --- -description: "Learn more about: Fatal Error C1079" title: "Fatal Error C1079" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1079" +ms.date: 08/17/2022 f1_keywords: ["C1079"] helpviewer_keywords: ["C1079"] -ms.assetid: cf06a65a-f9a5-4bd8-8128-201a6cbe2113 --- # Fatal Error C1079 -compiler limit : PCH file size limit exceeded +> compiler limit : PCH file size limit exceeded + +## Remarks The PCH file exceeds the 4 GB size limit. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1080.md b/docs/error-messages/compiler-errors-1/fatal-error-c1080.md index c5d058e6e8a..3868560b97a 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1080.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1080.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1080" title: "Fatal Error C1080" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1080" +ms.date: 11/04/2016 f1_keywords: ["C1080"] helpviewer_keywords: ["C1080"] -ms.assetid: 01e9e7c0-6a20-4539-b9d2-d27e7afcc8e6 --- # Fatal Error C1080 -compiler limit : command line option exceeded limit of number characters +> compiler limit : command line option exceeded limit of number characters + +## Remarks An argument passed to the compiler exceeds 256 characters. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1081.md b/docs/error-messages/compiler-errors-1/fatal-error-c1081.md index dabb2798dc7..8922f2cb05e 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1081.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1081.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1081" title: "Fatal Error C1081" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1081" +ms.date: 11/04/2016 f1_keywords: ["C1081"] helpviewer_keywords: ["C1081"] -ms.assetid: e58adf17-cbe1-4955-a5c7-80622bbba249 --- # Fatal Error C1081 -'symbol': file name too long +> 'symbol': file name too long + +## Remarks The length of a file pathname exceeds `_MAX_PATH` (defined by STDLIB.h as 260 characters). Shorten the name of the file. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1082.md b/docs/error-messages/compiler-errors-1/fatal-error-c1082.md index ff154134ce9..c0052079a27 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1082.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1082.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1082" title: "Fatal Error C1082" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1082" +ms.date: 11/04/2016 f1_keywords: ["C1082"] helpviewer_keywords: ["C1082"] -ms.assetid: 173179f1-1e14-4a91-9451-122f8a53c0b8 --- # Fatal Error C1082 -Cannot close filetype file: 'file': message +> Cannot close filetype file: 'file': message + +## Remarks If the message says "bad file number", the file may have been closing in the foreground while compiling in the background. 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 c5f68fc2954..06c6ff63ab1 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1083.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1083.md @@ -1,24 +1,25 @@ --- -description: "Learn more about: Fatal Error C1083" title: "Fatal Error C1083" -ms.date: "09/01/2017" +description: "Learn more about: 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. +## Remarks + +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 +27,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 +49,64 @@ but this example works: `#include "headers\myheader.h"` -Relative paths can also be used with directories on the include search path. If you add a directory to the **INCLUDE** environment variable or to your **Include Directories** path in Visual Studio, do not also add part of the path to the include directives. For example, if your header is located at *`\path\example\headers\myheader.h`*, and you add *`\path\example\headers\`* to your **Include Directories** path in Visual Studio, but your `#include` directive refers to the file as +Relative paths can also be used with directories on the include search path. If you add a directory to the **INCLUDE** environment variable or to your **Include Directories** path in Visual Studio, don't add part of the path to the include directives. For example, if your header is located at *`\path\example\headers\myheader.h`*, and you add *`\path\example\headers\`* to your **Include Directories** path in Visual Studio, but your `#include` directive refers to the file as `#include ` -then the file is not found. Use the correct path relative to the directory specified in the include search path. In this example, you could change the include search path to *`\path\example\`*, or remove the *`headers\`* path segment from the `#include` directive. +then the file isn't found. Use the correct path relative to the directory specified in the include search path. In this example, you could change the include search path to *`\path\example\`*, or remove the *`headers\`* path segment from the `#include` directive. ## Third-party library issues and vcpkg -If you see this error when you are trying to configure a third-party library as part of your build, consider using [vcpkg](https://vcpkg.io/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports), and sets all the configuration properties and dependencies required for successful builds as part of your project. +If you see this error when you're trying to configure a third-party library as part of your build, consider using [vcpkg](/vcpkg/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports), and sets all the configuration properties and dependencies required for successful builds as part of your project. ## The file is in your project, but not the include search path -Even when header files are listed in **Solution Explorer** as part of a project, the files are only found by the compiler when they are referred to by an `#include` or `#import` directive in a source file, and are located in an include search path. Different kinds of builds might use different search paths. The **`/X`** compiler option can be used to exclude directories from the include search path. This enables different builds to use different include files that have the same name, but are kept in different directories. This is an alternative to conditional compilation by using preprocessor commands. For more information about the **`/X`** compiler option, see [`/X` (Ignore Standard Include Paths)](../../build/reference/x-ignore-standard-include-paths.md). +Even when header files are listed in **Solution Explorer** as part of a project, the files are only found by the compiler when they're referred to by an `#include` or `#import` directive in a source file, and are located in an include search path. Different kinds of builds might use different search paths. The **`/X`** compiler option can be used to exclude directories from the include search path. This enables different builds to use different include files that have the same name, but are kept in different directories. This is an alternative to conditional compilation by using preprocessor commands. For more information about the **`/X`** compiler option, see [`/X` (Ignore Standard Include Paths)](../../build/reference/x-ignore-standard-include-paths.md). -To fix this issue, correct the path that the compiler uses to search for the included or imported file. A new project uses default include search paths. You may have to modify the include search path to add a directory for your project. If you are compiling on the command line, add the path to the **INCLUDE** environment variable or the **`/I`** compiler option to specify the path to the file. +To fix this issue, correct the path that the compiler uses to search for the included or imported file. A new project uses default include search paths. You might have to modify the include search path to add a directory for your project. If you're compiling on the command line, add the path to the **INCLUDE** environment variable or the **`/I`** compiler option to specify the path to the file. -To set the include directory path in Visual Studio, open the project’s **Property Pages** dialog box. Select **VC++ Directories** under **Configuration Properties** in the left pane, and then edit the **Include Directories** property. For more information about the per-user and per-project directories searched by the compiler in Visual Studio, see [VC++ Directories Property Page](../../build/reference/vcpp-directories-property-page.md). For more information about the **`/I`** compiler option, see [`/I` (Additional Include Directories)](../../build/reference/i-additional-include-directories.md). +To set the include directory path in Visual Studio, open the project's **Property Pages** dialog box. Select **VC++ Directories** under **Configuration Properties** in the left pane, and then edit the **Include Directories** property. For more information about the per-user and per-project directories searched by the compiler in Visual Studio, see [VC++ Directories Property Page](../../build/reference/vcpp-directories-property-page.md). For more information about the **`/I`** compiler option, see [`/I` (Additional Include Directories)](../../build/reference/i-additional-include-directories.md). -## The command line INCLUDE or LIB environment is not set +## The command line INCLUDE or LIB environment isn't set -When the compiler is invoked on the command line, environment variables are often used to specify search paths. If the search path described by the **INCLUDE** or **LIB** environment variable is not set correctly, a C1083 error can be generated. We strongly recommend using a developer command prompt shortcut to set the basic environment for command line builds. For more information, see [Build C/C++ on the Command Line](../../build/building-on-the-command-line.md). For more information about how to use environment variables, see [How to: Use Environment Variables in a Build](/visualstudio/msbuild/how-to-use-environment-variables-in-a-build). +When the compiler is invoked on the command line, environment variables are often used to specify search paths. If the search path described by the **INCLUDE** or **LIB** environment variable isn't set correctly, a C1083 error can be generated. We strongly recommend using a developer command prompt shortcut to set the basic environment for command line builds. For more information, see [Build C/C++ on the Command Line](../../build/building-on-the-command-line.md). For more information about how to use environment variables, see [How to: Use Environment Variables in a Build](/visualstudio/msbuild/how-to-use-environment-variables-in-a-build). -## The file may be locked or in use +## The file might be locked or in use -If you are using another program to edit or access the file, it may have the file locked. Try closing the file in the other program. Sometimes the other program can be Visual Studio itself, if you are using parallel compilation options. If turning off the parallel build option makes the error go away, then this is the problem. Other parallel build systems can also have this issue. Be careful to set file and project dependencies so build order is correct. In some cases, consider creating an intermediate project to force build dependency order for a common file that may be built by multiple projects. Sometimes antivirus programs temporarily lock recently changed files for scanning. If possible, consider excluding your project build directories from the antivirus scanner. +If you're using another program to edit or access the file, it might have the file locked. Try closing the file in the other program. Sometimes the other program can be Visual Studio itself, if you're using parallel compilation options. If turning off the parallel build option makes the error go away, then this is the problem. Other parallel build systems can also have this issue. Be careful to set file and project dependencies so build order is correct. In some cases, consider creating an intermediate project to force build dependency order for a common file that might be built by multiple projects. Sometimes antivirus programs temporarily lock recently changed files for scanning. If possible, consider excluding your project build directories from the antivirus scanner. ## The wrong version of a file name is included -A C1083 error can also indicate that the wrong version of a file is included. For example, a build could include the wrong version of a file that has an `#include` directive for a header file that is not intended for that build. For example, certain files may only apply to x86 builds, or to Debug builds. When the header file is not found, the compiler generates a C1083 error. The fix for this problem is to use the correct file, not to add the header file or directory to the build. +A C1083 error can also indicate that the wrong version of a file is included. For example, a build could include the wrong version of a file that has an `#include` directive for a header file that isn't intended for that build. For example, certain files might only apply to x86 builds, or to Debug builds. When the header file isn't found, the compiler generates a C1083 error. The fix for this problem is to use the correct file, not to add the header file or directory to the build. -## The precompiled headers are not yet precompiled +## The precompiled headers aren't yet precompiled When a project is configured to use precompiled headers, the relevant *`.pch`* files have to be created so that files that use the header contents can be compiled. For example, the *`pch.cpp`* file (*`stdafx.cpp`* in Visual Studio 2017 and earlier) is automatically created in the project directory for new projects. Compile that file first to create the precompiled header files. In the typical build process design, this is done automatically. For more information, see [Creating Precompiled Header Files](../../build/creating-precompiled-header-files.md). -## Additional causes +## Other causes -- You have installed an SDK or third-party library, but you have not opened a new developer command prompt window after the SDK or library is installed. If the SDK or library adds files to the **INCLUDE** path, you may need to open a new developer command prompt window to pick up these environment variable changes. +- You've installed an SDK or third-party library, but haven't opened a new developer command prompt. If the SDK or library adds files to the **INCLUDE** path, you might need to open a new developer command prompt window to pick up these environment variable changes. -- The file uses managed code, but the compiler option **`/clr`** is not specified. For more information, see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md). +- The file uses managed code, but the compiler option **`/clr`** isn't specified. For more information, see [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md). - The file is compiled by using a different **`/analyze`** compiler option setting than is used to precompile the headers. When the headers for a project are precompiled, all should use the same **`/analyze`** settings. For more information, see [`/analyze` (Code Analysis)](../../build/reference/analyze-code-analysis.md). -- The file or directory was created by the Windows Subsystem for Linux, per-directory case sensitivity is enabled, and the specified case of a path or file does not match the case of the path or file on disk. +- The file or directory was created by the Windows Subsystem for Linux, per-directory case sensitivity is enabled, and the specified case of a path or file doesn't match the case of the path or file on disk. - The file, the directory, or the disk is read-only. -- Visual Studio or the command line tools do not have sufficient permissions to read the file or the directory. This can happen, for example, when the project files have different ownership than the process running Visual Studio or the command line tools. Sometimes this issue can be fixed by running Visual Studio or the developer command prompt as Administrator. +- Visual Studio or the command line tools don't have sufficient permissions to read the file or the directory. This can happen, for example, when the project files have different ownership than the process running Visual Studio or the command line tools. Sometimes this issue can be fixed by running Visual Studio or the developer command prompt as Administrator. -- There are not enough file handles. Close some applications and then recompile. This condition is unusual under typical circumstances. However, it can occur when large projects are built on a computer that has limited physical memory. +- There aren't enough file handles. Close some applications and then recompile. This condition is unusual under typical circumstances. However, it can occur when large projects are built on a computer that has limited physical memory. ## Example -The following example generates a C1083 error when the header file `"test.h"` does not exist in the source directory or on the include search path. +The following example generates a C1083 error when the header file `"test.h"` doesn't exist in the source directory or on the include search path. ```cpp // C1083.cpp // compile with: /c -#include "test.h" // C1083 test.h does not exist +#include "test.h" // C1083 test.h doesn't exist #include "stdio.h" // OK ``` diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1084.md b/docs/error-messages/compiler-errors-1/fatal-error-c1084.md index f4fc81eada9..d5cfb9d0bcd 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1084.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1084.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1084" title: "Fatal Error C1084" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1084" +ms.date: 11/04/2016 f1_keywords: ["C1084"] helpviewer_keywords: ["C1084"] -ms.assetid: b2f273ef-3a14-4d5f-8ce0-7a11a0388fe6 --- # Fatal Error C1084 -Cannot read filetype file: 'file': message +> Cannot read filetype file: 'file': message + +## Remarks This error is generally the result of a failed internal system API call made by the compiler. The message shown when this error is encountered is often generated by either [_wcserror_s](../../c-runtime-library/reference/strerror-s-strerror-s-wcserror-s-wcserror-s.md) or [FormatMessage](/windows/win32/api/winbase/nf-winbase-formatmessage). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1085.md b/docs/error-messages/compiler-errors-1/fatal-error-c1085.md index dd3fff0adf3..b7a9acd4f40 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1085.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1085.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Fatal Error C1085" title: "Fatal Error C1085" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1085" +ms.date: 11/04/2016 f1_keywords: ["C1085"] helpviewer_keywords: ["C1085"] -ms.assetid: f2766365-d09b-4299-8a98-12e5aca98568 --- # Fatal Error C1085 -Cannot write filetype file: 'file': message +> Cannot write filetype file: 'file': message ### To fix by checking the following possible causes diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1086.md b/docs/error-messages/compiler-errors-1/fatal-error-c1086.md index f5686a8a742..d89d6f0efb4 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1086.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1086.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1086" title: "Fatal Error C1086" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1086" +ms.date: 11/04/2016 f1_keywords: ["C1086"] helpviewer_keywords: ["C1086"] -ms.assetid: 8e3c32c9-cafe-48bf-87bf-f70a1f0367f0 --- # Fatal Error C1086 -Cannot seek filetype file: 'file': message +> Cannot seek filetype file: 'file': message + +## Remarks The compiler cannot complete an I/O operation. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1087.md b/docs/error-messages/compiler-errors-1/fatal-error-c1087.md index 80fd48be9c6..84d1dd3314f 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1087.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1087.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1087" title: "Fatal Error C1087" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1087" +ms.date: 11/04/2016 f1_keywords: ["C1087"] helpviewer_keywords: ["C1087"] -ms.assetid: 2fb4c14e-c6ea-45e4-8ce5-a51d15811a01 --- # Fatal Error C1087 -Cannot tell filetype file: 'file': message +> Cannot tell filetype file: 'file': message + +## Remarks The compiler cannot complete an I/O operation. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1088.md b/docs/error-messages/compiler-errors-1/fatal-error-c1088.md index f037f7af44f..8359676108d 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1088.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1088.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1088" title: "Fatal Error C1088" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1088" +ms.date: 11/04/2016 f1_keywords: ["C1088"] helpviewer_keywords: ["C1088"] -ms.assetid: e61ebbb4-ab50-4a66-b2f6-3cc4400d8511 --- # Fatal Error C1088 -Cannot flush filetype file: 'file': message +> Cannot flush filetype file: 'file': message + +## Remarks The compiler cannot complete an I/O operation. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1089.md b/docs/error-messages/compiler-errors-1/fatal-error-c1089.md index 753f67e2f74..0b1c98a1e84 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1089.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1089.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1089" title: "Fatal Error C1089" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1089" +ms.date: 11/04/2016 f1_keywords: ["C1089"] helpviewer_keywords: ["C1089"] -ms.assetid: c4f1e8e5-62c5-464a-9112-99b0790a0fb7 --- # Fatal Error C1089 -Cannot truncate filetype file: 'file': message +> Cannot truncate filetype file: 'file': message + +## Remarks The compiler cannot shrink a file to zero length. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1090.md b/docs/error-messages/compiler-errors-1/fatal-error-c1090.md index 3764f4cd32c..7602b777254 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1090.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1090.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Fatal Error C1090 PDB API call failed" title: "Fatal Error C1090" +description: "Learn more about: Fatal Error C1090 PDB API call failed" ms.date: 04/01/2021 f1_keywords: ["C1090"] helpviewer_keywords: ["C1090"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["C1090"] > PDB API call failed, error code '*error-number*': *message* +## Remarks + An error occurred in processing a PDB file. Error C1090 is a catch-all for uncommon compiler PDB file errors that aren't reported separately. We only have generic advice for resolving this issue: diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1091.md b/docs/error-messages/compiler-errors-1/fatal-error-c1091.md index dfdc32778cd..fb5e7195d9b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1091.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1091.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1091" title: "Fatal Error C1091" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1091" +ms.date: 11/04/2016 f1_keywords: ["C1091"] helpviewer_keywords: ["C1091"] -ms.assetid: 812d4201-9154-48b0-b9af-5959c082ca33 --- # Fatal Error C1091 -compiler limit: string exceeds 'length' bytes in length +> compiler limit: string exceeds 'length' bytes in length + +## Remarks A string constant exceeded the current limit on the length of strings. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1092.md b/docs/error-messages/compiler-errors-1/fatal-error-c1092.md index 396f6b007a6..a34f58ab352 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1092.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1092.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1092" title: "Fatal Error C1092" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1092" +ms.date: 11/04/2016 f1_keywords: ["C1092"] helpviewer_keywords: ["C1092"] -ms.assetid: bcaa87f0-fbfc-4a33-844b-3b9f5d67f279 --- # Fatal Error C1092 -Edit and Continue does not support changes to data types; build required +> Edit and Continue does not support changes to data types; build required + +## Remarks You changed or added a data type since the last successful build. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1093.md b/docs/error-messages/compiler-errors-1/fatal-error-c1093.md index 4d6e7437f7c..b975a6552d6 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1093.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1093.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1093" title: "Fatal Error C1093" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1093" +ms.date: 11/04/2016 f1_keywords: ["C1093"] helpviewer_keywords: ["C1093"] -ms.assetid: 61b120e2-44cc-4824-981a-7eb72aa57745 --- # Fatal Error C1093 > API call '*function name*' failed '*location of call*' : '*text from run-time*' +## Remarks + A call to a .NET function failed. The *text from run-time* string may or may not be supplied by the COM runtime. For more information about system error messages, see the winerror.h system file, and [FormatMessage](/windows/win32/api/winbase/nf-winbase-formatmessage). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1094.md b/docs/error-messages/compiler-errors-1/fatal-error-c1094.md index 62706f27af6..7bc3d767268 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1094.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1094.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1094" title: "Fatal Error C1094" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1094" +ms.date: 08/17/2022 f1_keywords: ["C1094"] helpviewer_keywords: ["C1094"] -ms.assetid: 9e1193b2-cb95-44f9-bf6f-019e0d41dd97 --- # Fatal Error C1094 -'-Zmval1' : command line option is inconsistent with value used to build precompiled header ('-Zmval2') +> '-Zm*value-1*' : command line option is inconsistent with value used to build precompiled header ('-Zm*value-2*') + +## Remarks + +The value that is passed to [`/Yc`](../../build/reference/yc-create-precompiled-header-file.md) must be the same value that is passed to [`/Yu`](../../build/reference/yu-use-precompiled-header-file.md) (**`/Zm`** values must be the same in all compilations that use or create the same precompiled header file). -The value that is passed to [/Yc](../../build/reference/yc-create-precompiled-header-file.md) must be the same value that is passed to [/Yu](../../build/reference/yu-use-precompiled-header-file.md) (**/Zm** values must be the same in all compilations that use or create the same precompiled header file). +## Example -The following sample generates C1094: +The following example generates C1094: ``` // C1094.h diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1098.md b/docs/error-messages/compiler-errors-1/fatal-error-c1098.md index d28a67c5100..4a2b422fb33 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1098.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1098.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1098" title: "Fatal Error C1098" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1098" +ms.date: 11/04/2016 f1_keywords: ["C1098"] helpviewer_keywords: ["C1098"] -ms.assetid: 09a1a14b-95bd-49db-b644-192efbaf9f45 --- # Fatal Error C1098 -Version mismatch with Edit and Continue engine +> Version mismatch with Edit and Continue engine + +## Remarks The debugger version you are using does not match the compiler used to create the executable. If recompiling does not fix the problem, you may need to reinstall Visual C++ to make sure you have the proper versions of the debugger and compiler. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1099.md b/docs/error-messages/compiler-errors-1/fatal-error-c1099.md index 5cf10883dcb..0b55641fd09 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1099.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1099.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1099" title: "Fatal Error C1099" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1099" +ms.date: 11/04/2016 f1_keywords: ["C1099"] helpviewer_keywords: ["C1099"] -ms.assetid: c050b074-a06a-4026-9e10-569029cc0739 --- # Fatal Error C1099 -Edit and Continue engine terminating compile +> Edit and Continue engine terminating compile + +## Remarks Edit and Continue loaded a precompiled header file in preparation for compiling code changes, but subsequent actions (such as code changes prior to the precompiled header `#include` statement or stopping the debugger) prevented Edit and Continue from finishing the compile with that process. You do not need to take any action to fix this error. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1100.md b/docs/error-messages/compiler-errors-1/fatal-error-c1100.md index 77c7b876b76..71ab285e1b9 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1100.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1100.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1100" title: "Fatal Error C1100" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1100" +ms.date: 11/04/2016 f1_keywords: ["C1100"] helpviewer_keywords: ["C1100"] -ms.assetid: d4d877ea-acd6-4ec7-961e-55e460d98820 --- # Fatal Error C1100 -unable to initialize OLE : system error message +> unable to initialize OLE : system error message + +## Remarks The compiler cannot initialize the Component Object Model (COM) library. See [CoInitialize](/windows/win32/api/objbase/nf-objbase-coinitialize). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1103.md b/docs/error-messages/compiler-errors-1/fatal-error-c1103.md index 7b102186fe7..8d252ac10e1 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1103.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1103.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Fatal Error C1103" title: "Fatal Error C1103" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1103" +ms.date: 11/04/2016 f1_keywords: ["C1103"] helpviewer_keywords: ["C1103"] -ms.assetid: 9d276939-9c47-4235-9d20-76b8434f9731 --- # Fatal Error C1103 -fatal error importing progid: 'message' +> fatal error importing progid: 'message' + +## Remarks The compiler detected a problem importing a type library. For example, you cannot specify a type library with progid and also specify `no_registry`. For more information, see [#import Directive](../../preprocessor/hash-import-directive-cpp.md). -The following sample will generate C1103: +## Example + +The following example will generate C1103: ```cpp // C1103.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1104.md b/docs/error-messages/compiler-errors-1/fatal-error-c1104.md index d942c0c4c7c..4e5f7e9d27c 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1104.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1104.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Fatal Error C1104" title: "Fatal Error C1104" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1104" +ms.date: 11/04/2016 f1_keywords: ["C1104"] helpviewer_keywords: ["C1104"] -ms.assetid: 45bd85c4-77d3-4d3c-b167-49c563aefb4d --- # Fatal Error C1104 -fatal error importing libid: 'message' +> fatal error importing libid: 'message' + +## Remarks The compiler detected a problem importing a type library. For example, you cannot specify a type library with libid and also specify `no_registry`. For more information, see [#import Directive](../../preprocessor/hash-import-directive-cpp.md). -The following sample will generate C1104: +## Example + +The following example will generate C1104: ```cpp // C1104.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1107.md b/docs/error-messages/compiler-errors-1/fatal-error-c1107.md index 7ec4ba1fb4c..0033caaaace 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1107.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1107.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1107" title: "Fatal Error C1107" +description: "Learn more about: Fatal Error C1107" ms.date: 11/22/2021 f1_keywords: ["C1107"] helpviewer_keywords: ["C1107"] -ms.assetid: 541a4d9f-10bc-4dd8-b68e-15e548f3dc0a --- # Fatal Error C1107 > could not find assembly '*file*': please specify the assembly search path using `/AI` or by setting the `LIBPATH` environment variable +## Remarks + A metadata file was passed to a [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive that the compiler was unable to locate. LIBPATH, which is described in the article for `#using`, and the [`/AI`](../../build/reference/ai-specify-metadata-directories.md) compiler option allow you to specify directories in which the compiler will look for referenced metadata files. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1108.md b/docs/error-messages/compiler-errors-1/fatal-error-c1108.md index 98678a609eb..4e44ae651ed 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1108.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1108.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1108" title: "Fatal Error C1108" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1108" +ms.date: 11/04/2016 f1_keywords: ["C1108"] helpviewer_keywords: ["C1108"] -ms.assetid: 3cadf07b-b7a7-41c7-ad5c-06ceb8af8c3b --- # Fatal Error C1108 > unable to find DLL: '*dll name*' +## Remarks + The specified DLL (*dll name*) could not be found in the path. To resolve this error, reinstall Visual C++ or copy the appropriate .dll file from the installation to your computer. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1109.md b/docs/error-messages/compiler-errors-1/fatal-error-c1109.md index 01bc560c948..98e571d5285 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1109.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1109.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1109" title: "Fatal Error C1109" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1109" +ms.date: 11/04/2016 f1_keywords: ["C1109"] helpviewer_keywords: ["C1109"] -ms.assetid: df385e46-e54d-412c-88f8-42582b59909c --- # Fatal Error C1109 -unable to find 'entry point' in DLL 'dll' +> unable to find 'entry point' in DLL 'dll' + +## Remarks An entry point in a [delay-loaded DLL](../../build/reference/linker-support-for-delay-loaded-dlls.md) required by the compiler could not be found. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1113.md b/docs/error-messages/compiler-errors-1/fatal-error-c1113.md index c23e479a0e7..dbc382ae0b6 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1113.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1113.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1113" title: "Fatal Error C1113" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1113" +ms.date: 11/04/2016 f1_keywords: ["C1113"] helpviewer_keywords: ["C1113"] -ms.assetid: 1c7c3ce7-2827-4822-9c63-0abc8615ea39 --- # Fatal Error C1113 -\#using failed on 'file' +> #using failed on 'file' + +## Remarks Only a file in the Microsoft Intermediate Language (MSIL) format can be passed to a [#using](../../preprocessor/hash-using-directive-cpp.md) directive. The [/clr](../../build/reference/clr-common-language-runtime-compilation.md) compiler option lets you create an MSIL output file. Other Visual Studio languages also produce MSIL files. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1116.md b/docs/error-messages/compiler-errors-1/fatal-error-c1116.md new file mode 100644 index 00000000000..79274cc6b14 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1116.md @@ -0,0 +1,14 @@ +--- +title: "Fatal Error C1116" +description: "Learn more about: Fatal Error C1116" +ms.date: 08/17/2022 +f1_keywords: ["C1116"] +helpviewer_keywords: ["C1116"] +--- +# Fatal Error C1116 + +> unrecoverable error importing module/headerunit '*name*'. Specialization of '*primary-template*' with arguments '*argument-list*' + +## Remarks + +Error C1116 can happen when the creation of the specialization requires the compiler to parse a token-stream and it encounters an identifier without a matching symbol. To resolve the issue, verify that all template specification arguments are defined and spelled correctly. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1117.md b/docs/error-messages/compiler-errors-1/fatal-error-c1117.md new file mode 100644 index 00000000000..1c1856a0520 --- /dev/null +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1117.md @@ -0,0 +1,14 @@ +--- +title: "Fatal Error C1117" +description: "Learn more about: Fatal Error C1117" +ms.date: 08/17/2022 +f1_keywords: ["C1117"] +helpviewer_keywords: ["C1117"] +--- +# Fatal Error C1117 + +> unrecoverable error importing module/headerunit '*name*': symbol '*symbol-name*' has already been defined + +## Remarks + +The compiler found a redefinition of an existing type. To resolve the issue, verify that the symbol has only one definition across modules and translation units. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1120.md b/docs/error-messages/compiler-errors-1/fatal-error-c1120.md index f828f4e0129..4152492f557 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1120.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1120.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1120" title: "Fatal Error C1120" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1120" +ms.date: 11/04/2016 f1_keywords: ["C1120"] helpviewer_keywords: ["C1120"] -ms.assetid: 34212b64-f4e5-4c55-9acc-6f6b2ab5f1c0 --- # Fatal Error C1120 -call to GetProcAddress failed for 'function' +> call to GetProcAddress failed for 'function' + +## Remarks This error indicates Visual C++ needs to be reinstalled. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1121.md b/docs/error-messages/compiler-errors-1/fatal-error-c1121.md index 32816f5b502..ed1e1c77aa2 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1121.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1121.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1121" title: "Fatal Error C1121" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1121" +ms.date: 11/04/2016 f1_keywords: ["C1121"] helpviewer_keywords: ["C1121"] -ms.assetid: d16e51c5-4c50-4303-a028-ca60f7a3273c --- # Fatal Error C1121 -call to CryptoAPI failed +> call to CryptoAPI failed + +## Remarks The compiler made a call to the CryptoAPI and the call failed. Reinstall Visual Studio and possibly reinstall the operating system. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1126.md b/docs/error-messages/compiler-errors-1/fatal-error-c1126.md index 444c7d01110..cc63a251925 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1126.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1126.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1126" title: "Fatal Error C1126" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1126" +ms.date: 11/04/2016 f1_keywords: ["C1126"] helpviewer_keywords: ["C1126"] -ms.assetid: f22b26a6-8ad7-47cf-a237-196c8ea60aca --- # Fatal Error C1126 -'identifier' : automatic allocation exceeds size +> 'identifier' : automatic allocation exceeds size + +## Remarks Space allocated for local variables of a function (plus a limited amount of space used by the compiler, such as an extra 20 bytes for swappable functions) exceeds the limit. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1128.md b/docs/error-messages/compiler-errors-1/fatal-error-c1128.md index fd928239b93..3df616a6771 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1128.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1128.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1128" title: "Fatal Error C1128" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1128" +ms.date: 11/04/2016 f1_keywords: ["C1128"] helpviewer_keywords: ["C1128"] -ms.assetid: 6f9580fd-ecef-48be-9780-dcf666704279 --- # Fatal Error C1128 -number of sections exceeded object file format limit : compile with /bigobj +> number of sections exceeded object file format limit : compile with /bigobj + +## Remarks An .obj file exceeded the number of allowable sections, a COFF object file format limitation. @@ -22,4 +23,4 @@ If possible, compile without debugging information. You may also need to have specific instantiations of templates in separate source code files, rather than having the compiler emit them. -When porting code, C1128 will likely appear first when using the x64 compiler, and much later with the x86 compiler. x64 will have at least 4 sections associated with each function compiled **/Gy** or inlined from templates or class-inline: code, pdata, and debug info, and possibly xdata. X86 won’t have the pdata. +When porting code, C1128 will likely appear first when using the x64 compiler, and much later with the x86 compiler. x64 will have at least 4 sections associated with each function compiled **/Gy** or inlined from templates or class-inline: code, pdata, and debug info, and possibly xdata. X86 won't have the pdata. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1189.md b/docs/error-messages/compiler-errors-1/fatal-error-c1189.md index 91233b42997..791eb9e2253 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1189.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1189.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Fatal Error C1189" title: "Fatal Error C1189" -ms.date: "04/27/2018" +description: "Learn more about: Fatal Error C1189" +ms.date: 04/27/2018 f1_keywords: ["C1189"] helpviewer_keywords: ["C1189"] -ms.assetid: 2e5c8a78-edd4-411c-b619-558a96be148a --- # Fatal Error C1189 @@ -16,7 +15,7 @@ C1189 is generated by the `#error` directive. The developer who codes the direct ## Example -The following sample generates C1189. In the sample, the developer issues a custom error message because the `_WIN32` identifier is not defined: +The following example generates C1189. In the example, the developer issues a custom error message because the `_WIN32` identifier is not defined: ```cpp // C1189.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1190.md b/docs/error-messages/compiler-errors-1/fatal-error-c1190.md index da144884d90..b02620a88fd 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1190.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1190.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Fatal Error C1190" title: "Fatal Error C1190" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1190" +ms.date: 11/04/2016 f1_keywords: ["C1190"] helpviewer_keywords: ["C1190"] -ms.assetid: dee2266d-6c40-4f6e-91db-f01e65f8d2bc --- # Fatal Error C1190 -managed targeted code requires a '/clr' option +> managed targeted code requires a '/clr' option + +## Remarks You are using CLR constructs but you did not specify **/clr**. For more information, see [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md). -The following sample generates C1190: +## Example + +The following example generates C1190: ```cpp // C1190.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1191.md b/docs/error-messages/compiler-errors-1/fatal-error-c1191.md index 523f3574ff0..d6bf50086a0 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1191.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1191.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1191" title: "Fatal Error C1191" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1191" +ms.date: 11/04/2016 f1_keywords: ["C1191"] helpviewer_keywords: ["C1191"] -ms.assetid: 2888c6c4-b4e6-449e-8ee0-7917f31086df --- # Fatal Error C1191 -'dll' can only be imported at global scope +> 'dll' can only be imported at global scope + +## Remarks The instruction to import mscorlib.dll into a program that uses /clr programming cannot appear in a namespace or function, but must appear at global scope. -The following sample generates C1191: +## Example + +The following example generates C1191: ```cpp // C1191.cpp 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 7f4529470d0..2c374cd29f7 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1192.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1192.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1192" title: "Fatal Error C1192" -ms.date: "11/04/2016" -f1_keywords: ["c1192"] +description: "Learn more about: Fatal Error C1192" +ms.date: 11/04/2016 +f1_keywords: ["C1192"] helpviewer_keywords: ["C1192"] -ms.assetid: 54cff717-a3eb-471d-9bd4-1c2e673dbbef --- # Fatal Error C1192 -\#using failed on 'file' +> #using failed on 'file' + +## Remarks Only a file in the Microsoft Intermediate Language (MSIL) format can be passed to a [#using](../../preprocessor/hash-using-directive-cpp.md) directive. The [/clr](../../build/reference/clr-common-language-runtime-compilation.md) compiler option lets you create an MSIL output file. Other Visual Studio languages also produce MSIL files. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1196.md b/docs/error-messages/compiler-errors-1/fatal-error-c1196.md index ff1a7716283..8ae577e8b49 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1196.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1196.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1196" title: "Fatal Error C1196" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1196" +ms.date: 11/04/2016 f1_keywords: ["C1196"] helpviewer_keywords: ["C1196"] -ms.assetid: 10a79b3f-3423-4ee3-98fa-e9e59cddabb1 --- # Fatal Error C1196 -'identifier' : identifier found in type library 'typelib' is not a valid C++ identifier +> 'identifier' : identifier found in type library 'typelib' is not a valid C++ identifier + +## Remarks One of the identifiers in your type library is not a valid C++ identifier. The type library is not available for use with [#import](../../preprocessor/hash-import-directive-cpp.md). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1197.md b/docs/error-messages/compiler-errors-1/fatal-error-c1197.md index f08b1d92a2f..3a63aaa8362 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1197.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1197.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1197" title: "Fatal Error C1197" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1197" +ms.date: 11/04/2016 f1_keywords: ["C1197"] helpviewer_keywords: ["C1197"] -ms.assetid: 22b801b7-e792-41f6-a461-973c03c69f25 --- # Fatal Error C1197 -cannot reference 'mscorlib.dll_1' as the program has already referenced 'mscorlib.dll_2' +> cannot reference 'mscorlib.dll_1' as the program has already referenced 'mscorlib.dll_2' + +## Remarks The compiler is matched to a version of the common language runtime. However, an attempt was made to reference a version of a common language runtime file from a previous version. @@ -16,7 +17,7 @@ To resolve this error, only reference files from the version of the common langu ## Example -The following sample generates C1197: +The following example generates C1197: ```cpp // C1197.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1201.md b/docs/error-messages/compiler-errors-1/fatal-error-c1201.md index a318e4523e8..f726151d895 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1201.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1201.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1201" title: "Fatal Error C1201" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1201" +ms.date: 11/04/2016 f1_keywords: ["C1201"] helpviewer_keywords: ["C1201"] -ms.assetid: e58b9b9a-2c6f-454d-8719-9773aca765d1 --- # Fatal Error C1201 -unable to continue after syntax error in class template definition +> unable to continue after syntax error in class template definition + +## Remarks An unexpected error occurred while parsing a class template definition. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1202.md b/docs/error-messages/compiler-errors-1/fatal-error-c1202.md index 54eb8261043..4e2c9efccfc 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1202.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1202.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Fatal Error C1202" title: "Fatal Error C1202" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1202" +ms.date: 11/04/2016 f1_keywords: ["C1202"] helpviewer_keywords: ["C1202"] -ms.assetid: c859adb8-17a7-4fa1-a1f3-5820b7bf3849 --- # Fatal Error C1202 -recursive type or function dependency context too complex +> recursive type or function dependency context too complex + +## Remarks A template definition was recursive or exceeded complexity limits. -## Examples +## Example -The following sample generates C1202. +The following example generates C1202. ```cpp // C1202.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1205.md b/docs/error-messages/compiler-errors-1/fatal-error-c1205.md index 8dad0bb4a0d..d66fd0f7793 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1205.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1205.md @@ -1,15 +1,18 @@ --- -description: "Learn more about: Fatal Error C1205" title: "Fatal Error C1205" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1205" +ms.date: 08/17/2022 f1_keywords: ["C1205"] helpviewer_keywords: ["C1205"] -ms.assetid: f855c145-8cf7-4dd1-bb19-257ee38b8382 --- # Fatal Error C1205 -Generics are not supported by the version of the runtime installed +> Generics are not supported by the version of the runtime installed -The version of the common language runtime that the compiler is using is not a version of the runtime supported by the current compiler. For example, the generics feature requires a runtime that is matched to the compiler. +## Remarks + +The version of the common language runtime that the compiler is using isn't a version of the runtime supported by the current compiler. For example, the generics feature requires a runtime that is matched to the compiler. Your path specification may need to be modified. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1206.md b/docs/error-messages/compiler-errors-1/fatal-error-c1206.md index bfb0125715e..c519b7e27cb 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1206.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1206.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Fatal Error C1206" title: "Fatal Error C1206" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1206" +ms.date: 08/17/2022 f1_keywords: ["C1206"] helpviewer_keywords: ["C1206"] -ms.assetid: 2211428f-ad86-4f7b-82eb-f1ba89b0510e --- # Fatal Error C1206 -Per-appdomain data is not supported by the version of the runtime installed +> Per-appdomain data is not supported by the version of the runtime installed + +## Remarks Some features, such as per application domain data, are only supported by the common language runtime that supports the feature. -C1206 indicates that the latest version of the runtime is not installed on your computer. Install the common language runtime version that is intended for use with your compiler. +C1206 indicates that the latest version of the runtime isn't installed on your computer. Install the common language runtime version that is intended for use with your compiler. + +For more information, see [`appdomain`](../../cpp/appdomain.md) -See [appdomain](../../cpp/appdomain.md) for more information. +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1207.md b/docs/error-messages/compiler-errors-1/fatal-error-c1207.md index 77a59a8b13d..abcb64a7f3b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1207.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1207.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Fatal Error C1207" title: "Fatal Error C1207" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1207" +ms.date: 08/17/2022 f1_keywords: ["C1207"] helpviewer_keywords: ["C1207"] -ms.assetid: cd31b410-9523-47db-883c-e69a9351ffa2 --- # Fatal Error C1207 -Managed templates not supported by the version of the runtime installed +> Managed templates not supported by the version of the runtime installed + +## Remarks C1207 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1207 install the common language runtime version that is intended for use with your compiler. +To resolve C1207, install the common language runtime version that is intended for use with your compiler. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1208.md b/docs/error-messages/compiler-errors-1/fatal-error-c1208.md index 0609c245d97..57732dfda0e 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1208.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1208.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Fatal Error C1208" title: "Fatal Error C1208" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1208" +ms.date: 08/17/2022 f1_keywords: ["C1208"] helpviewer_keywords: ["C1208"] -ms.assetid: 4eefd8f0-5c2e-4a11-9e63-293e1139db65 --- # Fatal Error C1208 -Allocating reference classes on the stack is not supported by the version of the runtime installed +> Allocating reference classes on the stack is not supported by the version of the runtime installed + +## Remarks C1208 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. Install the common language runtime version that is intended for use with your compiler. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1209.md b/docs/error-messages/compiler-errors-1/fatal-error-c1209.md index 0d417de1bce..3967da97ec8 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1209.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1209.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Fatal Error C1209" title: "Fatal Error C1209" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1209" +ms.date: 08/17/2022 f1_keywords: ["C1209"] helpviewer_keywords: ["C1209"] -ms.assetid: aa9ee10f-abe3-4683-9792-adca4cbbabb5 --- # Fatal Error C1209 -Friend assemblies not supported by the version of the runtime installed +> Friend assemblies not supported by the version of the runtime installed + +## Remarks C1208 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1209, install the common language runtime that shipped with the compiler you are using. +To resolve C1209, install the common language runtime that shipped with the compiler you're using. For more information, see [Friend Assemblies (C++)](../../dotnet/friend-assemblies-cpp.md). + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1210.md b/docs/error-messages/compiler-errors-1/fatal-error-c1210.md index 4167d5d4565..70c37bc8c76 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1210.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1210.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Fatal Error C1210" title: "Fatal Error C1210" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1210" +ms.date: 08/17/2022 f1_keywords: ["C1210"] helpviewer_keywords: ["C1210"] -ms.assetid: e2208309-c284-425c-a7e8-48e96e66f35b --- # Fatal Error C1210 -> /clr:pure and /clr:safe are not supported by the version of the runtime installed +> `/clr:pure` and `/clr:safe` are not supported by the version of the runtime installed -The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. +## Remarks + +The **`/clr:pure`** and **`/clr:safe`** compiler options are deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017. C1210 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1210 install the common language runtime version that is intended for use with your compiler. +To resolve C1210, install the common language runtime version that is intended for use with your compiler. + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1211.md b/docs/error-messages/compiler-errors-1/fatal-error-c1211.md index 8fed88ea022..24359b9c00c 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1211.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1211.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Fatal Error C1211" title: "Fatal Error C1211" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1211" +ms.date: 08/17/2022 f1_keywords: ["C1211"] helpviewer_keywords: ["C1211"] -ms.assetid: df0ca70d-ec6e-4400-926a-b877e2599978 --- # Fatal Error C1211 -The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed +> The TypeForwardedTo Custom Attribute is not supported by the version of the runtime installed + +## Remarks C1211 occurs when you have a compiler for the current release, but a common language runtime from a previous release. Some functionality of the compiler may not work on a previous version of the run time. -To resolve C1211 install the common language runtime that shipped with the compiler you are using. +To resolve C1211, install the common language runtime that shipped with the compiler you're using. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). + +This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1305.md b/docs/error-messages/compiler-errors-1/fatal-error-c1305.md index 35a90daf3c2..398c483eb5f 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1305.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1305.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1305" title: "Fatal Error C1305" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1305" +ms.date: 11/04/2016 f1_keywords: ["C1305"] helpviewer_keywords: ["C1305"] -ms.assetid: 1629c850-e2db-4678-83d8-9bfc85323bc5 --- # Fatal Error C1305 -profile database 'pgd_file' is for a different architecture +> profile database 'pgd_file' is for a different architecture + +## Remarks A .pgd file that was generated from the /LTCG:PGINSTRUMENT operation for another platform was passed to [/LTCG:PGOPTIMIZE](../../build/reference/ltcg-link-time-code-generation.md) . [Profile-guided optimizations](../../build/profile-guided-optimizations.md) are available for x86 and x64 platforms. However, a .pgd file generated with a /LTCG:PGINSTRUMENT operation for one platform is not valid as input to a /LTCG:PGOPTIMIZE for a different platform. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1307.md b/docs/error-messages/compiler-errors-1/fatal-error-c1307.md index d358e2bbd8b..27c1ed010ea 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1307.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1307.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1307" title: "Fatal Error C1307" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1307" +ms.date: 11/04/2016 f1_keywords: ["C1307"] helpviewer_keywords: ["C1307"] -ms.assetid: 6f77d3d4-ba8a-476c-b540-aff19eb4efc4 --- # Fatal Error C1307 -program has been edited since profile data was collected +> program has been edited since profile data was collected + +## Remarks When using [/LTCG:PGOPTIMIZE](../../build/reference/ltcg-link-time-code-generation.md), the linker detected an input module that was recompiled after /LTCG:PGINSTRUMENT and that the module was changed to the point where existing profile data is no longer relevant. For example, if the call graph changed in the recompiled module, the compiler will generate C1307. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1308.md b/docs/error-messages/compiler-errors-1/fatal-error-c1308.md index 045cd2f5e42..81335e1a835 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1308.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1308.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Fatal Error C1308" title: "Fatal Error C1308" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1308" +ms.date: 11/04/2016 f1_keywords: ["C1308"] helpviewer_keywords: ["C1308"] -ms.assetid: 46177997-069e-433a-8e20-93c846d78ffd --- # Fatal Error C1308 -linking assemblies is not supported +> linking assemblies is not supported + +## Remarks A .netmodule is allowed as input to the linker, but an assembly is not. This error can be generated when an attempt is made to link an assembly compiled with `/clr:safe`. For more information, see [.netmodule Files as Linker Input](../../build/reference/netmodule-files-as-linker-input.md). -The following sample generates C1308: +## Example + +The following example generates C1308: ```cpp // C1308.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1309.md b/docs/error-messages/compiler-errors-1/fatal-error-c1309.md index f70ecf7bd42..0bd33544bfd 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1309.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1309.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1309" title: "Fatal Error C1309" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1309" +ms.date: 11/04/2016 f1_keywords: ["C1309"] helpviewer_keywords: ["C1309"] -ms.assetid: a95363d6-a4f3-45fb-9690-aa7e552093b7 --- # Fatal Error C1309 -Mismatched versions of C2.DLL and PGODB\.DLL +> Mismatched versions of C2.DLL and PGODB\.DLL + +## Remarks The toolset you are using to build and use [Profile-Guided Optimizations](../../build/profile-guided-optimizations.md) contains mismatched components. If you cannot manually resolve this error, reinstall Visual C++. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1310.md b/docs/error-messages/compiler-errors-1/fatal-error-c1310.md index 233ae5c7e4d..5fef1f9c37b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1310.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1310.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Fatal Error C1310" title: "Fatal Error C1310" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1310" +ms.date: 11/04/2016 f1_keywords: ["C1310"] helpviewer_keywords: ["C1310"] -ms.assetid: ac48aa51-8023-42fe-b844-3f8bf228fbef --- # Fatal Error C1310 -profile guided optimizations are not available with OpenMP +> profile guided optimizations are not available with OpenMP + +## Remarks You will not be able to link with [/LTCG:PGI](../../build/reference/ltcg-link-time-code-generation.md) any module that was compiled with [/GL](../../build/reference/gl-whole-program-optimization.md). -The following sample generates C1310: +## Example + +The following example generates C1310: ```cpp // C1310.cpp diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1311.md b/docs/error-messages/compiler-errors-1/fatal-error-c1311.md index 93d5084e290..fdb102ebbda 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1311.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1311.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Fatal Error C1311" title: "Fatal Error C1311" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1311" +ms.date: 11/04/2016 f1_keywords: ["C1311"] helpviewer_keywords: ["C1311"] -ms.assetid: 6590a06c-ce9d-4f17-8f62-c809343143b8 --- # Fatal Error C1311 -COFF format cannot statically initialize 'var' with number byte(s) of an address +> COFF format cannot statically initialize 'var' with number byte(s) of an address + +## Remarks An address whose value is not known at compile time cannot be statically assigned to a variable whose type has storage of less than four bytes. This error can occur on code that is otherwise valid C++. +## Example + The following example shows one condition that might cause C1311. ``` diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1312.md b/docs/error-messages/compiler-errors-1/fatal-error-c1312.md index 03699b2824c..3173bfba076 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1312.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1312.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1312" title: "Fatal Error C1312" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1312" +ms.date: 11/04/2016 f1_keywords: ["C1312"] helpviewer_keywords: ["C1312"] -ms.assetid: 1aa7cd0e-d45f-4ae7-a85d-015ebb962eaf --- # Fatal Error C1312 -Too many conditional branches in function. Simplify or refactor source code. +> Too many conditional branches in function. Simplify or refactor source code. + +## Remarks The code is too complex for the compiler to process without running out of stack memory. Simplify your code. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1313.md b/docs/error-messages/compiler-errors-1/fatal-error-c1313.md index 629767d0279..90814b3406e 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1313.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1313.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1313" title: "Fatal Error C1313" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1313" +ms.date: 11/04/2016 f1_keywords: ["C1313"] helpviewer_keywords: ["C1313"] -ms.assetid: 6c7631c8-6fd7-476a-9303-564717fda0f9 --- # Fatal Error C1313 -compiler limit : type blocks may not be nested deeper than number levels +> compiler limit : type blocks may not be nested deeper than number levels + +## Remarks Exception handling (or structured exception handling) blocks were nested too deeply. Simplify your code. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1350.md b/docs/error-messages/compiler-errors-1/fatal-error-c1350.md index 96c160733c6..dcb1474a08b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1350.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1350.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1350" title: "Fatal Error C1350" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1350" +ms.date: 11/04/2016 f1_keywords: ["C1350"] helpviewer_keywords: ["C1350"] -ms.assetid: 8bb47c23-ac9c-4a33-9ede-4d63ed9d4ba8 --- # Fatal Error C1350 -error loading dll 'dll': dll not found +> error loading dll 'dll': dll not found + +## Remarks The DLL that supports the attempted operation was not found. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1351.md b/docs/error-messages/compiler-errors-1/fatal-error-c1351.md index 9e772faf2c1..2019a263242 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1351.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1351.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1351" title: "Fatal Error C1351" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1351" +ms.date: 11/04/2016 f1_keywords: ["C1351"] helpviewer_keywords: ["C1351"] -ms.assetid: 1f8502e4-1049-49c7-bbe3-fa101c79021e --- # Fatal Error C1351 > error loading dll '*dll*': incompatible version +## Remarks + The wrong version of a DLL was found. This indicates a problem with your installation, and you should reinstall Visual Studio. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1352.md b/docs/error-messages/compiler-errors-1/fatal-error-c1352.md index 3becb52d1f7..581c2864959 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1352.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1352.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1352" title: "Fatal Error C1352" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1352" +ms.date: 11/04/2016 f1_keywords: ["C1352"] helpviewer_keywords: ["C1352"] -ms.assetid: d044e8b0-b6ef-4d57-8eb5-6254071be707 --- # Fatal Error C1352 -Invalid or corrupt MSIL in function 'function' from module 'file' +> Invalid or corrupt MSIL in function 'function' from module 'file' + +## Remarks A .netmodule was passed to the compiler, but the compiler detected corruption in the file. Ask the person who produced the .netmodule to investigate. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1353.md b/docs/error-messages/compiler-errors-1/fatal-error-c1353.md index d36fe258647..48b39279dd2 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1353.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1353.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1353" title: "Fatal Error C1353" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1353" +ms.date: 11/04/2016 f1_keywords: ["C1353"] helpviewer_keywords: ["C1353"] -ms.assetid: 37f55b1d-9e7a-4932-a41e-d593190895d3 --- # Fatal Error C1353 -metadata operation failed: runtime not installed or version mismatch +> metadata operation failed: runtime not installed or version mismatch + +## Remarks Reinstall your CLR or Visual Studio. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1382.md b/docs/error-messages/compiler-errors-1/fatal-error-c1382.md index f90ab23a6c1..f61a7a1fa02 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1382.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1382.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1382" title: "Fatal Error C1382" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1382" +ms.date: 11/04/2016 f1_keywords: ["C1382"] helpviewer_keywords: ["C1382"] -ms.assetid: 7a100f8c-3179-4927-a2f1-98de4c753850 --- # Fatal Error C1382 -the PCH file 'file' has been rebuilt since 'obj' was generated. Please rebuild this object +> the PCH file 'file' has been rebuilt since 'obj' was generated. Please rebuild this object + +## Remarks When using [/LTCG](../../build/reference/ltcg-link-time-code-generation.md), the compiler detected a .pch file that is newer than a CIL .obj that points to it. The information in the CIL .obj file is out of date. Rebuild the object. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1383.md b/docs/error-messages/compiler-errors-1/fatal-error-c1383.md index 787baf5bbae..f826a4c3a1c 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1383.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1383.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1383" title: "Fatal Error C1383" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1383" +ms.date: 11/04/2016 f1_keywords: ["C1383"] helpviewer_keywords: ["C1383"] -ms.assetid: ca224d14-d687-4fd6-80c2-8b82f28924ea --- # Fatal Error C1383 -compiler option /GL is incompatible with the installed version of common language runtime +> compiler option /GL is incompatible with the installed version of common language runtime + +## Remarks C1383 occurs when you are using a previous version of the common language runtime with a newer compiler, and when you compile with **/clr** and **/GL.** diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1506.md b/docs/error-messages/compiler-errors-1/fatal-error-c1506.md index e439909d468..2509bc5f2b6 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1506.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1506.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1506" title: "Fatal Error C1506" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1506" +ms.date: 11/04/2016 f1_keywords: ["C1506"] helpviewer_keywords: ["C1506"] -ms.assetid: c73d5702-c898-4a32-b0fa-a118601a1e14 --- # Fatal Error C1506 -unrecoverable block scoping error +> unrecoverable block scoping error + +## Remarks The block was too large to compile. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1508.md b/docs/error-messages/compiler-errors-1/fatal-error-c1508.md index 1954f3cf0b1..394368d4291 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1508.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1508.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1508" title: "Fatal Error C1508" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1508" +ms.date: 11/04/2016 f1_keywords: ["C1508"] helpviewer_keywords: ["C1508"] -ms.assetid: 1112c17d-d60f-470d-b886-fd1a9556c0ea --- # Fatal Error C1508 -compiler limit : 'function' : more than 65535 argument bytes +> compiler limit : 'function' : more than 65535 argument bytes + +## Remarks The formal parameters to the function exceed the limit of 65535 bytes. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1509.md b/docs/error-messages/compiler-errors-1/fatal-error-c1509.md index b716a1d9a16..1a17d1c7f5b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1509.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1509.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1509" title: "Fatal Error C1509" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1509" +ms.date: 11/04/2016 f1_keywords: ["C1509"] helpviewer_keywords: ["C1509"] -ms.assetid: 40dd100d-c6ba-451c-bd26-2c99ec1c36d6 --- # Fatal Error C1509 -compiler limit : too many exception handler states in function 'function'. simplify function +> compiler limit : too many exception handler states in function 'function'. simplify function + +## Remarks The code exceeds an internal limit on exception handler states (32,768 states). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1510.md b/docs/error-messages/compiler-errors-1/fatal-error-c1510.md index 382b7e07cbf..640a564c8fd 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1510.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1510.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1510" title: "Fatal Error C1510" -ms.date: "04/11/2017" +description: "Learn more about: Fatal Error C1510" +ms.date: 04/11/2017 f1_keywords: ["C1510"] helpviewer_keywords: ["C1510"] -ms.assetid: 150c827f-9514-41a9-8d7e-82f820749bcb --- # Fatal Error C1510 -Cannot open language resource clui.dll +> Cannot open language resource clui.dll + +## Remarks The compiler can't load the language resource DLL. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1601.md b/docs/error-messages/compiler-errors-1/fatal-error-c1601.md index b0ccf6cebf2..f36aca8a88d 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1601.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1601.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1601" title: "Fatal Error C1601" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1601" +ms.date: 11/04/2016 f1_keywords: ["C1601"] helpviewer_keywords: ["C1601"] -ms.assetid: 25797c39-f085-4d75-9eab-159ecd36ef49 --- # Fatal Error C1601 -unsupported inline assembly opcode +> unsupported inline assembly opcode + +## Remarks This error indicates a mismatch in your compiler .exe files, which may have occurred because of an incomplete installation. For example, you may have installed a service pack but not the Processor Pack. Install all required products. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1602.md b/docs/error-messages/compiler-errors-1/fatal-error-c1602.md index 5565ea2d137..5f29077c41f 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1602.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1602.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1602" title: "Fatal Error C1602" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1602" +ms.date: 11/04/2016 f1_keywords: ["C1602"] helpviewer_keywords: ["C1602"] -ms.assetid: a9365c58-fe66-49c4-a702-9bb75429cc1a --- # Fatal Error C1602 -unsupported intrinsic +> unsupported intrinsic + +## Remarks This error indicates a mismatch in your compiler .exe files, which may have occurred because of an incomplete installation. For example, you may have installed a service pack but not the Processor Pack. Install all required products. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1603.md b/docs/error-messages/compiler-errors-1/fatal-error-c1603.md index 4f6744a59e1..8e8fe6f3782 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1603.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1603.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1603" title: "Fatal Error C1603" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1603" +ms.date: 11/04/2016 f1_keywords: ["C1603"] helpviewer_keywords: ["C1603"] -ms.assetid: e5a06925-f916-4637-8240-6d2d280e6124 --- # Fatal Error C1603 -inline assembly branch target out of range by 'number' bytes +> inline assembly branch target out of range by 'number' bytes + +## Remarks The computed distance between a JCXZ or JECXZ instruction and its specified target label was greater than 128 bytes. Update your code so that the label is closer to the instruction. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1852.md b/docs/error-messages/compiler-errors-1/fatal-error-c1852.md index 9c42b79c0b2..06b8fd90e3b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1852.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1852.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1852" title: "Fatal Error C1852" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1852" +ms.date: 11/04/2016 f1_keywords: ["C1852"] helpviewer_keywords: ["C1852"] -ms.assetid: fa011004-b8d6-46f1-ba80-4785e4ce137f --- # Fatal Error C1852 -'filename' is not a valid precompiled header file +> 'filename' is not a valid precompiled header file + +## Remarks The file is not a precompiled header. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1853.md b/docs/error-messages/compiler-errors-1/fatal-error-c1853.md index 1b77c8c0bbb..6ff6d7e1dd8 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1853.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1853.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1853" title: "Fatal Error C1853" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1853" +ms.date: 11/04/2016 f1_keywords: ["C1853"] helpviewer_keywords: ["C1853"] -ms.assetid: ceb9b4a5-92bf-4573-8a9f-3109cc7743ce --- # Fatal Error C1853 > '*filename*' precompiled header file is from a previous version of the compiler, or the precompiled header is C++ and you are using it from C (or vice versa) +## Remarks + Possible causes: - The precompiled header was compiled with a previous compiler version. Try recompiling the header with the current compiler. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1854.md b/docs/error-messages/compiler-errors-1/fatal-error-c1854.md index 6280c869d44..460413ed4c8 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1854.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1854.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1854" title: "Fatal Error C1854" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1854" +ms.date: 11/04/2016 f1_keywords: ["C1854"] helpviewer_keywords: ["C1854"] -ms.assetid: 8c21a9cc-1737-475c-9e57-8725cd8937c1 --- # Fatal Error C1854 > cannot overwrite information formed during creation of the precompiled header in object file: '*filename*' +## Remarks + You specified the [/Yu (Use Precompiled Header File)](../../build/reference/yu-use-precompiled-header-file.md) option after specifying the [/Yc (Create Precompiled Header File)](../../build/reference/yc-create-precompiled-header-file.md) option for the same file. To fix this issue, in general, set only one file in your project to be compiled by using the **/Yc** option, and set all other files to compile by using the **/Yu** option. For details on the use of the **/Yc** option, and how to set it in the Visual Studio IDE, see [/Yc (Create Precompiled Header File)](../../build/reference/yc-create-precompiled-header-file.md). For more information on using precompiled headers, see [Creating Precompiled Header Files](../../build/creating-precompiled-header-files.md). diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1900.md b/docs/error-messages/compiler-errors-1/fatal-error-c1900.md index 5634a9b78bd..8d67b8fd8d5 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1900.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1900.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Fatal Error C1900" title: "Fatal Error C1900" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1900" +ms.date: 11/04/2016 f1_keywords: ["C1900"] helpviewer_keywords: ["C1900"] -ms.assetid: 3aaa583b-4c1a-45de-aa34-527d806f2cb5 --- # Fatal Error C1900 > Il mismatch between '*tool1*' version '*number1*' and '*tool2*' version '*number2*' +## Remarks + Tools run in various passes of the compiler do not match. *number1* and *number2* refer to the dates on the files. For example, in pass 1, the compiler front end runs (c1.dll) and in pass 2, the compiler back end runs (c2.dll). The dates on the files must match. To fix this issue, make sure that all updates have been applied to Visual Studio. If the problem persists, use **Programs and Features** in the Windows Control Panel to repair or reinstall Visual Studio. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1902.md b/docs/error-messages/compiler-errors-1/fatal-error-c1902.md index 8bde156cbf2..2433f0dc9dc 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1902.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1902.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1902" title: "Fatal Error C1902" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1902" +ms.date: 11/04/2016 f1_keywords: ["C1902"] helpviewer_keywords: ["C1902"] -ms.assetid: 2dc066cc-fcb1-4725-8bcb-9f44dd0905b7 --- # Fatal Error C1902 -program database manager mismatch; please check your installation +> program database manager mismatch; please check your installation + +## Remarks A program database file (.pdb) was created using a newer version of mspdb*XXX*.dll than the one the compiler found on your system. This error usually indicates that mspdbsrv.exe or mspdbcore.dll are missing or have different versions than mspdb*XXX*.dll. (The *XXX* placeholder in the mspdb*XXX*.dll file name changes with each product release. For example, in Visual Studio 2015, the file name is mspdb140.dll.) diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1903.md b/docs/error-messages/compiler-errors-1/fatal-error-c1903.md index 1f818efeaf3..d7d3f8cc18b 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1903.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1903.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Fatal Error C1903" title: "Fatal Error C1903" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1903" +ms.date: 11/04/2016 f1_keywords: ["C1903"] helpviewer_keywords: ["C1903"] -ms.assetid: 4b4719d6-35d2-4ca5-81ce-903ecd28dfb9 --- # Fatal Error C1903 -unable to recover from previous error(s); stopping compilation +> unable to recover from previous error(s); stopping compilation + +## Remarks The compiler found too many errors to continue. Fix the errors and recompile. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1904.md b/docs/error-messages/compiler-errors-1/fatal-error-c1904.md index a3443127d98..2fd23f23976 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1904.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1904.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1904" title: "Fatal Error C1904" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1904" +ms.date: 11/04/2016 f1_keywords: ["C1904"] helpviewer_keywords: ["C1904"] -ms.assetid: 10f66015-146f-41a7-8011-327b29dedec8 --- # Fatal Error C1904 -bad provider interaction: 'file' +> bad provider interaction: 'file' + +## Remarks This error indicates the failure of an attribute provider. diff --git a/docs/error-messages/compiler-errors-1/fatal-error-c1905.md b/docs/error-messages/compiler-errors-1/fatal-error-c1905.md index 69b567fcd5f..89b8a800a51 100644 --- a/docs/error-messages/compiler-errors-1/fatal-error-c1905.md +++ b/docs/error-messages/compiler-errors-1/fatal-error-c1905.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Fatal Error C1905" title: "Fatal Error C1905" -ms.date: "11/04/2016" +description: "Learn more about: Fatal Error C1905" +ms.date: 11/04/2016 f1_keywords: ["C1905"] helpviewer_keywords: ["C1905"] -ms.assetid: fefc6769-477f-45a2-9878-6f0a5f42472c --- # Fatal Error C1905 -Front end and back end not compatible (must target same processor) +> Front end and back end not compatible (must target same processor) + +## Remarks This error occurs when a .obj file is generated by a compiler front end (C1.dll) that targets one processor, such as x86, ARM, or x64, but is being read by a back end (C2.dll) that targets a different processor. 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 1a519a20673..00000000000 --- a/docs/error-messages/compiler-errors-1/fatal-error-c999.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -description: "Learn more about: Fatal Error C999" -title: "Fatal Error C999" -ms.date: "11/04/2016" -f1_keywords: ["C999"] -helpviewer_keywords: ["C999"] -ms.assetid: a3a49a96-a352-4ff2-aa84-84eb6a9a81f1 ---- -# Fatal Error C999 - -UNKNOWN MESSAGE Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information - -This error usually means that you have mixed files from different versions of the compiler, or your compiler installation is corrupted. Use the **Programs and Features** applet in the Control Panel to repair or reinstall the product. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2500.md b/docs/error-messages/compiler-errors-2/compiler-error-c2500.md index 172a50f9026..ca18bb6baa8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2500.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2500.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2500" title: "Compiler Error C2500" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2500" +ms.date: 11/04/2016 f1_keywords: ["C2500"] helpviewer_keywords: ["C2500"] -ms.assetid: 6bff8161-dc9a-48ca-91f1-fd2eefdbbc93 --- # Compiler Error C2500 -'identifier1' : 'identifier2' is already a direct base class +> 'identifier1' : 'identifier2' is already a direct base class + +## Remarks A class or structure appears more than once in a list of base classes. @@ -16,7 +17,9 @@ A direct base is one mentioned in the base list. An indirect base is a base clas A class cannot be specified as a direct base class more than once. A class can be used as an indirect base class more than once. -The following sample generates C2500: +## Example + +The following example generates C2500: ```cpp // C2500.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2502.md b/docs/error-messages/compiler-errors-2/compiler-error-c2502.md index 5870524c77c..682a1056c70 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2502.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2502.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2502" title: "Compiler Error C2502" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2502" +ms.date: 11/04/2016 f1_keywords: ["C2502"] helpviewer_keywords: ["C2502"] -ms.assetid: affa0b86-15fc-4e17-b7f2-6aad4a3771c4 --- # Compiler Error C2502 -'identifier' : too many access modifiers on the base class +> 'identifier' : too many access modifiers on the base class + +## Remarks The base class has more than one access modifier. Only one access modifier (**`public`**, **`private`**, or **`protected`**) is allowed. -The following sample generates C2502: +## Example + +The following example generates C2502: ```cpp // C2502.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2503.md b/docs/error-messages/compiler-errors-2/compiler-error-c2503.md index e1e75d0a6d6..2f5f2a710c1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2503.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2503.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2503" title: "Compiler Error C2503" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2503" +ms.date: 11/04/2016 f1_keywords: ["C2503"] helpviewer_keywords: ["C2503"] -ms.assetid: da86cc89-fd04-400b-aa8d-a5ffaf7e3918 --- # Compiler Error C2503 -'class' : base classes cannot contain zero-sized arrays +> 'class' : base classes cannot contain zero-sized arrays + +## Remarks A base class or structure contains a zero-sized array. An array in a class must have at least one element. -The following sample generates C2503: +## Example + +The following example generates C2503: ```cpp // C2503.cpp 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 d20e2ff8b2f..82e484fe671 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2504.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2504.md @@ -1,33 +1,32 @@ --- -description: "Learn more about: Compiler Error C2504" title: "Compiler Error C2504" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2504" +ms.date: 11/04/2016 f1_keywords: ["C2504"] helpviewer_keywords: ["C2504"] -ms.assetid: c9e002a6-a4ee-4ba7-970e-edf4adb83692 --- # Compiler Error C2504 -'class' : base class undefined +> 'class' : base class undefined -The base class is declared but never defined. Possible causes: +## Remarks + +The base class is declared but never defined. Possible causes: 1. Missing include file. 1. External base class not declared with [extern](../../cpp/extern-cpp.md). -The following sample generates C2504: +## Example + +The following example generates C2504: ```cpp // C2504.cpp // 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-c2505.md b/docs/error-messages/compiler-errors-2/compiler-error-c2505.md index e243be38013..2418358823a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2505.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2505.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2505" title: "Compiler Error C2505" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2505" +ms.date: 11/04/2016 f1_keywords: ["C2505"] helpviewer_keywords: ["C2505"] -ms.assetid: b19f5c53-399d-425e-90db-fe3ca9b40858 --- # Compiler Error C2505 -'symbol' : '__declspec(modifer)' can only be applied to declarations or definitions of global objects or static data members +> 'symbol' : '__declspec(modifer)' can only be applied to declarations or definitions of global objects or static data members + +## Remarks A **`__declspec`** modifier that is designed to only be used at global scope was used in a function. For more information, see [appdomain](../../cpp/appdomain.md) and [process](../../cpp/process.md). -The following sample generates C2505: +## Example + +The following example generates C2505: ```cpp // C2505.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2506.md b/docs/error-messages/compiler-errors-2/compiler-error-c2506.md index 58498d0b67b..6b29b6aa6a6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2506.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2506.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2506" title: "Compiler Error C2506" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2506" +ms.date: 11/04/2016 f1_keywords: ["C2506"] helpviewer_keywords: ["C2506"] -ms.assetid: cfed21cd-2404-46f2-985e-d0c2c3820830 --- # Compiler Error C2506 -'member' : '__declspec(modifier)' cannot be applied to this symbol +> 'member' : '__declspec(modifier)' cannot be applied to this symbol + +## Remarks You cannot declare per-process or per-appdomain for static members of a managed class. @@ -16,7 +17,7 @@ See [appdomain](../../cpp/appdomain.md) for more information. ## Example -The following sample generates C2506. +The following example generates C2506. ```cpp // C2506.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2507.md b/docs/error-messages/compiler-errors-2/compiler-error-c2507.md index acc9e18da98..4a586ada072 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2507.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2507.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2507" title: "Compiler Error C2507" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2507" +ms.date: 11/04/2016 f1_keywords: ["C2507"] helpviewer_keywords: ["C2507"] -ms.assetid: f102aff5-de7d-4c3f-9cac-2ddf9ce02b14 --- # Compiler Error C2507 -'identifier' : too many virtual modifiers on the base class +> 'identifier' : too many virtual modifiers on the base class + +## Remarks A class or structure is declared as **`virtual`** more than once. Only one **`virtual`** modifier can appear for each class in a list of base classes. -The following sample generates C2507: +## Example + +The following example generates C2507: ```cpp // C2507.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2509.md b/docs/error-messages/compiler-errors-2/compiler-error-c2509.md index f352ec966de..570e65755fc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2509.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2509.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2509" title: "Compiler Error C2509" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2509" +ms.date: 11/04/2016 f1_keywords: ["C2509"] helpviewer_keywords: ["C2509"] -ms.assetid: 339c1fcd-ec4a-456c-9f18-a9b24d9921af --- # Compiler Error C2509 -'identifier' : member function not declared in 'class' +> 'identifier' : member function not declared in 'class' + +## Remarks The function is not declared in the specified class. ## Example -The following sample generates C2509. +The following example generates C2509. ```cpp // C2509.cpp 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 3d234c77f0f..9a1d072e990 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2510.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2510.md @@ -1,13 +1,31 @@ --- -description: "Learn more about: Compiler Error C2510" title: "Compiler Error C2510" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2510" +ms.date: 11/04/2016 f1_keywords: ["C2510"] helpviewer_keywords: ["C2510"] -ms.assetid: bf6d28db-f2f4-48f8-8f4e-7d662ed278fe --- # Compiler Error C2510 -'identifier' : left of '::' must be a class/struct/union +> 'identifier' : left of '::' must be a class/struct/union + +## Remarks A class, structure, or union name must appear on the left side of the scope-resolution operator (`::`) operator. + +## Example + +The following example 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-c2511.md b/docs/error-messages/compiler-errors-2/compiler-error-c2511.md index 366066b72ce..9b0661a8f52 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2511.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2511.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2511" title: "Compiler Error C2511" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2511" +ms.date: 11/04/2016 f1_keywords: ["C2511"] helpviewer_keywords: ["C2511"] -ms.assetid: df999efe-fe2b-418b-bb55-4af6a0592631 --- # Compiler Error C2511 -'identifier' : overloaded member function not found in 'class' +> 'identifier' : overloaded member function not found in 'class' + +## Remarks No version of the function is declared with the specified parameters. Possible causes: @@ -18,7 +19,9 @@ No version of the function is declared with the specified parameters. Possible 1. Incorrect spelling of parameter names. -The following sample generates C2511: +## Example + +The following example generates C2511: ```cpp // C2511.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2512.md b/docs/error-messages/compiler-errors-2/compiler-error-c2512.md index 10f91ac3852..2d3eda00460 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2512.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2512.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2512" title: "Compiler Error C2512" -ms.date: "02/09/2018" +description: "Learn more about: Compiler Error C2512" +ms.date: 02/09/2018 f1_keywords: ["C2512"] helpviewer_keywords: ["C2512"] -ms.assetid: 15206da9-1164-451a-b869-280e00711aad --- # Compiler Error C2512 > '*identifier*' : no appropriate default constructor available +## Remarks + A *default constructor*, a constructor that requires no arguments, is not available for the specified class, structure, or union. The compiler supplies a default constructor only if no user-defined constructors are provided. If you provide a constructor that takes a non-void parameter, and you want to allow your class to be created with no parameters (for example, as the elements of an array), you must also provide a default constructor. The default constructor can be a constructor with default values for all parameters. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2513.md b/docs/error-messages/compiler-errors-2/compiler-error-c2513.md index a8b17632744..f473c159cb8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2513.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2513.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2513" title: "Compiler Error C2513" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2513" +ms.date: 11/04/2016 f1_keywords: ["C2513"] helpviewer_keywords: ["C2513"] -ms.assetid: ab5b21d3-61e2-4df7-8eea-6f14d6ba8620 --- # Compiler Error C2513 -'type' : no variable declared before '=' +> 'type' : no variable declared before '=' + +## Remarks The type specifier appears in declaration with no variable identifier. -The following sample generates C2513: +## Examples + +The following example generates C2513: ```cpp // C2513.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2514.md b/docs/error-messages/compiler-errors-2/compiler-error-c2514.md index 9d5d9b20d57..c42b99c7b3b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2514.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2514.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2514" title: "Compiler Error C2514" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2514" +ms.date: 11/04/2016 f1_keywords: ["C2514"] helpviewer_keywords: ["C2514"] -ms.assetid: 4b7085e5-6714-4261-80b7-bc72e64ab3e8 --- # Compiler Error C2514 -'class' : class has no constructors +> 'class' : class has no constructors + +## Remarks The class, structure, or union has no constructor with a parameter list that matches the parameters being used to instantiate it. A class must be fully declared before it can be instantiated. -The following sample generates C2514: +## Example + +The following example generates C2514: ```cpp // C2514.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2516.md b/docs/error-messages/compiler-errors-2/compiler-error-c2516.md index 187439712a0..80332510416 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2516.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2516.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2516" title: "Compiler Error C2516" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2516" +ms.date: 11/04/2016 f1_keywords: ["C2516"] helpviewer_keywords: ["C2516"] -ms.assetid: cd3accc1-0179-4a13-9587-616908c4ad1d --- # Compiler Error C2516 -'name' : is not a legal base class +> 'name' : is not a legal base class + +## Remarks The class is derived from a type name defined by a **`typedef`** statement. -The following sample generates C2516: +## Example + +The following example generates C2516: ```cpp // C2516.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2517.md b/docs/error-messages/compiler-errors-2/compiler-error-c2517.md index 4b06aacf31a..ef8d366347d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2517.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2517.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2517" title: "Compiler Error C2517" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2517" +ms.date: 11/04/2016 f1_keywords: ["C2517"] helpviewer_keywords: ["C2517"] -ms.assetid: d79348d5-e271-4aad-b973-8264515f8e90 --- # Compiler Error C2517 -'identifier' : right of '::' is undefined +> 'identifier' : right of '::' is undefined + +## Remarks The identifier on the right of the scope-resolution operator (`::`) must be a defined member of the class, structure, or union on the left. If no class, structure, or union is named, the identifier on the right must be declared with global scope. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2518.md b/docs/error-messages/compiler-errors-2/compiler-error-c2518.md index de3a5ceab9d..f87fee60c91 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2518.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2518.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2518" title: "Compiler Error C2518" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2518" +ms.date: 11/04/2016 f1_keywords: ["C2518"] helpviewer_keywords: ["C2518"] -ms.assetid: a7895b47-da90-4851-ac97-18e81479595a --- # Compiler Error C2518 -keyword 'keyword' illegal in base class list; ignored +> keyword 'keyword' illegal in base class list; ignored + +## Remarks The keywords **`class`** and **`struct`** should not appear in a base class list. -The following sample generates C2518: +## Example + +The following example generates C2518: ```cpp // C2518.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2521.md b/docs/error-messages/compiler-errors-2/compiler-error-c2521.md index dee34ce80d3..249652f2fd2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2521.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2521.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2521" title: "Compiler Error C2521" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2521" +ms.date: 11/04/2016 f1_keywords: ["C2521"] helpviewer_keywords: ["C2521"] -ms.assetid: 6042821b-e345-4a54-a7e9-a2c9019ea016 --- # Compiler Error C2521 -function does not take any arguments +> function does not take any arguments + +## Remarks You attempted to use arguments with a destructor or finalizer. @@ -16,7 +17,7 @@ For more information, see [Destructors and finalizers](../../dotnet/how-to-defin ## Example -The following sample generates C2521. +The following example generates C2521. ```cpp // C2521.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2523.md b/docs/error-messages/compiler-errors-2/compiler-error-c2523.md index 5b41bea97ec..0ae81bfb1d2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2523.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2523.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2523" title: "Compiler Error C2523" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2523" +ms.date: 11/04/2016 f1_keywords: ["C2523"] helpviewer_keywords: ["C2523"] -ms.assetid: 7951b700-8f37-45a0-beb4-a79ae0ced72e --- # Compiler Error C2523 -'class::~identifier' : destructor/finalizer tag mismatch +> 'class::~identifier' : destructor/finalizer tag mismatch + +## Remarks The name of the destructor must be the class name preceded by a tilde (`~`). The constructor and destructor are the only members that have the same name as the class. -The following sample generates C2523: +## Example + +The following example generates C2523: ```cpp // C2523.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2524.md b/docs/error-messages/compiler-errors-2/compiler-error-c2524.md index 1614c50b8dd..b5d7096731c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2524.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2524.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2524" title: "Compiler Error C2524" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2524" +ms.date: 11/04/2016 f1_keywords: ["C2524"] helpviewer_keywords: ["C2524"] -ms.assetid: e71d17f5-2fc2-416b-8dbd-e9bed85eb33a --- # Compiler Error C2524 -'destructor' : a destructor/finalizer must have a 'void' parameter list +> 'destructor' : a destructor/finalizer must have a 'void' parameter list + +## Remarks The destructor or finalizer had a parameter list that is not [void](../../cpp/void-cpp.md). Other parameter types are not allowed. 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 07b4d610a31..9e02ec15aae 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,30 @@ --- -description: "Learn more about: Compiler Error C2526" title: "Compiler Error C2526" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2526" +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' +> 'identifier1' : C linkage function cannot return C++ class 'identifier2' + +## Remarks A function defined with C linkage cannot return a user-defined type. + +## Example + +The following example 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-c2528.md b/docs/error-messages/compiler-errors-2/compiler-error-c2528.md index a70528679d2..eb69976c237 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2528.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2528.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2528" title: "Compiler Error C2528" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2528" +ms.date: 11/04/2016 f1_keywords: ["C2528"] helpviewer_keywords: ["C2528"] -ms.assetid: 2ea9d583-67a8-4b16-b35f-a50eeffc03c4 --- # Compiler Error C2528 -'name' : pointer to reference is illegal +> 'name' : pointer to reference is illegal + +## Remarks You cannot declare a pointer to a reference. Dereference the variable before declaring a pointer to it. -The following sample generates C2528: +## Example + +The following example generates C2528: ```cpp // C2528.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2529.md b/docs/error-messages/compiler-errors-2/compiler-error-c2529.md index 6a7223a5af7..bec04c6a15f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2529.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2529.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2529" title: "Compiler Error C2529" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2529" +ms.date: 11/04/2016 f1_keywords: ["C2529"] helpviewer_keywords: ["C2529"] -ms.assetid: 73a99e55-b91e-488d-9b72-cc80faaeb436 --- # Compiler Error C2529 -'name' : reference to reference is illegal +> 'name' : reference to reference is illegal + +## Remarks This error may be fixed by using pointer syntax and declaring a reference to a pointer. -The following sample generates C2529: +## Example + +The following example generates C2529: ```cpp // C2529.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2530.md b/docs/error-messages/compiler-errors-2/compiler-error-c2530.md index 4aff7437f14..17a71250c71 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2530.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2530.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2530" title: "Compiler Error C2530" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2530" +ms.date: 11/04/2016 f1_keywords: ["C2530"] helpviewer_keywords: ["C2530"] -ms.assetid: b790a312-48df-4a6a-9e27-be2c5f32f16c --- # Compiler Error C2530 -'identifier' : references must be initialized +> 'identifier' : references must be initialized + +## Remarks You must initialize a reference when it was declared, unless it is declared already: @@ -20,7 +21,9 @@ You must initialize a reference when it was declared, unless it is declared alre - As the return type of a function. -The following sample generates C2530: +## Example + +The following example generates C2530: ```cpp // C2530.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2531.md b/docs/error-messages/compiler-errors-2/compiler-error-c2531.md index ea98a6788e1..f6015c2c29f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2531.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2531.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2531" title: "Compiler Error C2531" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2531" +ms.date: 11/04/2016 f1_keywords: ["C2531"] helpviewer_keywords: ["C2531"] -ms.assetid: c49afe15-55f8-4dc8-ac01-bf653622a7db --- # Compiler Error C2531 -'identifier' : reference to a bit field illegal +> 'identifier' : reference to a bit field illegal + +## Remarks References to bit fields are not allowed. -The following sample generates C2531: +## Example + +The following example generates C2531: ```cpp // C2531.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2532.md b/docs/error-messages/compiler-errors-2/compiler-error-c2532.md index 3b23c6eeeb6..80856245d87 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2532.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2532.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2532" title: "Compiler Error C2532" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2532" +ms.date: 11/04/2016 f1_keywords: ["C2532"] helpviewer_keywords: ["C2532"] -ms.assetid: a94fdf13-5063-4206-b5a5-374930287bee --- # Compiler Error C2532 -'identifier' : illegal modifier for reference +> 'identifier' : illegal modifier for reference + +## Remarks The reference was changed. References cannot be modified to refer to another object. Use a pointer instead. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2533.md b/docs/error-messages/compiler-errors-2/compiler-error-c2533.md index bc17130d602..025404ed61d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2533.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2533.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2533" title: "Compiler Error C2533" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2533" +ms.date: 11/04/2016 f1_keywords: ["C2533"] helpviewer_keywords: ["C2533"] -ms.assetid: 5b335652-076c-4824-87c8-a741f64a3ce0 --- # Compiler Error C2533 -'identifier' : constructors not allowed a return type +> 'identifier' : constructors not allowed a return type + +## Remarks A constructor cannot have a return type (not even a **`void`** return type). A common source of this error is a missing semicolon between the end of a class definition and the first constructor implementation. The compiler sees the class as a definition of the return type for the constructor function, and generates C2533. -The following sample generates C2533, and shows how to fix it: +## Example + +The following example generates C2533, and shows how to fix it: ```cpp // C2533.cpp 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 b363a21ccd7..514403e602d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2534.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2534.md @@ -1,26 +1,39 @@ --- -description: "Learn more about: Compiler Error C2534" title: "Compiler Error C2534" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2534" +ms.date: 11/04/2016 f1_keywords: ["C2534"] helpviewer_keywords: ["C2534"] -ms.assetid: 481f9f54-5b51-4aa0-8eea-218f10807705 --- # Compiler Error C2534 -'identifier' : constructor cannot return a value +> 'identifier' : constructor cannot return a value + +## Remarks -A constructor cannot return a value or have a return type (not even a **`void`** return type). +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. -This error may be fixed by removing the **`return`** statement from the constructor definition. +## Example -The following sample generates C2534: +The following example 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-c2535.md b/docs/error-messages/compiler-errors-2/compiler-error-c2535.md index 3ead6411365..cb2505b77c7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2535.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2535.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2535" title: "Compiler Error C2535" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2535" +ms.date: 11/04/2016 f1_keywords: ["C2535"] helpviewer_keywords: ["C2535"] -ms.assetid: a958f83e-e2bf-4a59-b44b-d406ec325d7e --- # Compiler Error C2535 -'identifier' : member function already defined or declared +> 'identifier' : member function already defined or declared + +## Remarks This error could be caused by using the same formal parameter list in more than one definition or declaration of an overloaded function. If you get C2535 because of the Dispose function, see [Destructors and finalizers](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Destructors_and_finalizers) for more information. -The following sample generates C2535: +## Example + +The following example generates C2535: ```cpp // C2535.cpp 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 23c52c10d0e..2a767197bcb 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,26 @@ --- -description: "Learn more about: Compiler Error C2537" title: "Compiler Error C2537" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2537" +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 +> 'specifier' : illegal linkage specification -Possible causes: +## Remarks -1. The linkage specifier is not supported. Only the "C" linkage specifier is supported. +The linkage specifier is not supported. Only the "C" and "C++" linkage specifiers are supported. -1. "C" linkage is specified for more than one function in a set of overloaded functions. This is not allowed. +## Example -The following sample generates C2537: +The following example 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-c2540.md b/docs/error-messages/compiler-errors-2/compiler-error-c2540.md index 89a2a496ade..0278d815c0e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2540.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2540.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2540" title: "Compiler Error C2540" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2540" +ms.date: 11/04/2016 f1_keywords: ["C2540"] helpviewer_keywords: ["C2540"] -ms.assetid: 92c805a3-2dd9-46ca-a63d-3845c18ecc95 --- # Compiler Error C2540 -non-constant expression as array bound +> non-constant expression as array bound + +## Remarks An array must have a constant bound. -The following sample generates C2540: +## Example + +The following example generates C2540: ```cpp // C2540.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2541.md b/docs/error-messages/compiler-errors-2/compiler-error-c2541.md index ac2e94c4f96..54bc47b02b4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2541.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2541.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2541" title: "Compiler Error C2541" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2541" +ms.date: 11/04/2016 f1_keywords: ["C2541"] helpviewer_keywords: ["C2541"] -ms.assetid: ed95180f-00df-4e62-a8e9-1b6dab8281bf --- # Compiler Error C2541 -'delete' : delete : cannot delete objects that are not pointers +> 'delete' : delete : cannot delete objects that are not pointers + +## Remarks The [delete](../../cpp/delete-operator-cpp.md) operator was used on an object that is not a pointer. -The following sample generates C2541: +## Example + +The following example generates C2541: ```cpp // C2541.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2542.md b/docs/error-messages/compiler-errors-2/compiler-error-c2542.md index c35adf15529..b41ae2e7d22 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2542.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2542.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2542" title: "Compiler Error C2542" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2542" +ms.date: 11/04/2016 f1_keywords: ["C2542"] helpviewer_keywords: ["C2542"] -ms.assetid: a984520d-f835-4cac-ac0e-7f1d5f5c6278 --- # Compiler Error C2542 -'identifier' : class object has no constructor for initialization +> 'identifier' : class object has no constructor for initialization + +## Remarks There is no constructor with a parameter list that matches the initialization. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2543.md b/docs/error-messages/compiler-errors-2/compiler-error-c2543.md index b4167a06053..6f695891d1e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2543.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2543.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2543" title: "Compiler Error C2543" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2543" +ms.date: 11/04/2016 f1_keywords: ["C2543"] helpviewer_keywords: ["C2543"] -ms.assetid: 6e4d2d03-ef34-4514-92fe-763543a71fa8 --- # Compiler Error C2543 -expected ']' for operator '[]' +> expected ']' for operator '[]' + +## Remarks The subscripting operator is missing a left bracket. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2544.md b/docs/error-messages/compiler-errors-2/compiler-error-c2544.md index 7f975f4a00f..5a664fae23a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2544.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2544.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2544" title: "Compiler Error C2544" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2544" +ms.date: 11/04/2016 f1_keywords: ["C2544"] helpviewer_keywords: ["C2544"] -ms.assetid: 8e79b74a-4e92-4752-a5fe-c3143dfc5524 --- # Compiler Error C2544 -expected ')' for operator '()' +> expected ')' for operator '()' + +## Remarks The function call operator is missing a left parenthesis. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2545.md b/docs/error-messages/compiler-errors-2/compiler-error-c2545.md index 65bbf221f32..bbf07446c62 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2545.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2545.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2545" title: "Compiler Error C2545" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2545" +ms.date: 11/04/2016 f1_keywords: ["C2545"] helpviewer_keywords: ["C2545"] -ms.assetid: 51598eb9-0c57-4306-a0cd-3862980f3672 --- # Compiler Error C2545 -'operator' : unable to find overloaded operator +> 'operator' : unable to find overloaded operator + +## Remarks The operator cannot be used with the operands provided. You must supply an overloaded operator with the required operands. 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 607c8fad3e5..5c8525181bb 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,41 @@ --- +title: "Compiler error C2548" description: "Learn more about: Compiler Error C2548" -title: "Compiler Error C2548" -ms.date: "11/04/2016" +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 +> '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. +## Remarks + +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 example generates C2548 for: + +- `func1` because it's missing the default argument `b`. +- `func3` because it's missing the default argument `c`. + +The following example 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-c2549.md b/docs/error-messages/compiler-errors-2/compiler-error-c2549.md index 95ea293aa90..a779b7adf17 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2549.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2549.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Compiler Error C2549" title: "Compiler Error C2549" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2549" +ms.date: 11/04/2016 f1_keywords: ["C2549"] helpviewer_keywords: ["C2549"] -ms.assetid: 29310094-54a3-4605-bc6d-a312a68daf5d --- # Compiler Error C2549 -user-defined conversion cannot specify a return type +> user-defined conversion cannot specify a return type + +## Example -The following sample generates C2549: +The following example generates C2549: ```cpp // C2549.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2550.md b/docs/error-messages/compiler-errors-2/compiler-error-c2550.md index 12046ba0826..eac2acfcd2a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2550.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2550.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2550" title: "Compiler Error C2550" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2550" +ms.date: 11/04/2016 f1_keywords: ["C2550"] helpviewer_keywords: ["C2550"] -ms.assetid: 3293f53e-ee66-4035-920d-34e115c3a24c --- # Compiler Error C2550 -'identifier' : constructor initializer lists are only allowed on constructor definitions +> 'identifier' : constructor initializer lists are only allowed on constructor definitions + +## Remarks A base class initializer list is used on the definition of a function that is not a constructor. -The following sample generates C2550: +## Example + +The following example generates C2550: ```cpp // C2550.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2551.md b/docs/error-messages/compiler-errors-2/compiler-error-c2551.md index a0bff6271a9..26983767f91 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2551.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2551.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2551" title: "Compiler Error C2551" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2551" +ms.date: 11/04/2016 f1_keywords: ["C2551"] helpviewer_keywords: ["C2551"] -ms.assetid: 6f48b91d-635b-4eef-b13c-1bf2056c1053 --- # Compiler Error C2551 -'void *' type needs explicit cast +> 'void *' type needs explicit cast + +## Remarks A **`void`** pointer is assigned to a nonvoid pointer by implicit conversion. You must use an explicit cast. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2552.md b/docs/error-messages/compiler-errors-2/compiler-error-c2552.md index c3714405422..e995484a613 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2552.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2552.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2552" title: "Compiler Error C2552" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2552" +ms.date: 11/04/2016 f1_keywords: ["C2552"] helpviewer_keywords: ["C2552"] -ms.assetid: 0e0ab759-788a-4faf-9337-80d4b9e2e8c9 --- # Compiler Error C2552 -'identifier' : non-aggregates cannot be initialized with initializer list +> 'identifier' : non-aggregates cannot be initialized with initializer list + +## Remarks The aggregate identifier was incorrectly initialized. @@ -42,7 +43,9 @@ The following represent the reasons C2552 may fire when an aggregate initializat - The type has a non-fixed dimension array (zero-array) whose elements have destructors. -The following sample generates C2552: +## Example + +The following example generates C2552: ```cpp // C2552.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2553.md b/docs/error-messages/compiler-errors-2/compiler-error-c2553.md index 4db5c543e36..bf468cd7234 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2553.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2553.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2553" title: "Compiler Error C2553" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2553" +ms.date: 11/04/2016 f1_keywords: ["C2553"] helpviewer_keywords: ["C2553"] -ms.assetid: 64bc1e9a-627f-4ce9-b7bc-dc911bdb9180 --- # Compiler Error C2553 -'base_function': overriding virtual function return type differs from 'override_function' +> 'base_function': overriding virtual function return type differs from 'override_function' + +## Remarks A function in a derived class attempted to override a virtual function in a base class, but the derived class function did not have the same return type as the base class function. An override function signature must match the signature of the function being overridden. -The following sample generates C2553: +## Example + +The following example generates C2553: ```cpp // C2553.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2555.md b/docs/error-messages/compiler-errors-2/compiler-error-c2555.md index 787b255c78b..e8d97e2e695 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2555.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2555.md @@ -1,19 +1,18 @@ --- title: "Compiler Error C2555" description: "Reference for Visual Studio C++ compiler error C2555." -ms.date: "03/30/2020" +ms.date: 03/30/2020 f1_keywords: ["C2555"] helpviewer_keywords: ["C2555"] -ms.assetid: 5e49ebb8-7c90-457a-aa12-7ca7ab6574b2 --- # Compiler Error C2555 > '*class1*::*function1*': overriding virtual function return type differs and is not covariant from '*class2*::*function2*' -A virtual function and a derived overriding function have identical parameter lists but different return types. - ## Remarks +A virtual function and a derived overriding function have identical parameter lists but different return types. + In C++, an overriding function in a derived class can't differ only by return type from a virtual function in a base class. There's an exception to this rule for certain return types. When a derived class overrides a public base class, it may return a pointer or reference to the derived class instead of a base-class pointer or reference. These return types are called *covariant*, because they vary together with the type. This rule exception doesn't allow covariant reference-to-pointer or pointer-to-pointer types. @@ -34,7 +33,7 @@ is Guid CheckSources(Guid sourceID, Guid carouselIDs[]) []; ``` -The following sample generates C2555: +The following example generates C2555: ```cpp // C2555.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2556.md b/docs/error-messages/compiler-errors-2/compiler-error-c2556.md index c53302f927a..25a188c34cd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2556.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2556.md @@ -1,25 +1,26 @@ --- -description: "Learn more about: Compiler Error C2556" title: "Compiler Error C2556" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2556" +ms.date: 06/29/2025 f1_keywords: ["C2556"] helpviewer_keywords: ["C2556"] -ms.assetid: fc4399ad-45b3-49fd-be1f-0b13956a595a --- # Compiler Error C2556 -'identifier' : overloaded functions only differ by return type +> '*function1*': overloaded function differs only by return type from '*function2*' + +## Remarks The overloaded functions have different return types but the same parameter list. Each overloaded function must have a distinct formal parameter list. -The following sample generates C2556: +## Example + +The following example generates C2556: ```cpp // C2556.cpp // compile with: /c -class C { - int func(); - double func(); // C2556 - int func(int i); // ok parameter lists differ -}; +int func(); +double func(); // C2556 +int func(int i); // OK parameter lists differ ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2557.md b/docs/error-messages/compiler-errors-2/compiler-error-c2557.md index cb0f2c74826..63bc8d7a2fc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2557.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2557.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2557" title: "Compiler Error C2557" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2557" +ms.date: 11/04/2016 f1_keywords: ["C2557"] helpviewer_keywords: ["C2557"] -ms.assetid: 48a33d82-aa16-4658-b346-2311fcb39864 --- # Compiler Error C2557 -'identifier' : private and protected members cannot be initialized without a constructor +> 'identifier' : private and protected members cannot be initialized without a constructor + +## Remarks Only members and friends can assign a value to a private or protected member. Nonpublic members should be initialized in the class constructor. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2558.md b/docs/error-messages/compiler-errors-2/compiler-error-c2558.md index eb0b6683dec..0b53dfa4199 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2558.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2558.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2558" title: "Compiler Error C2558" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2558" +ms.date: 11/04/2016 f1_keywords: ["C2558"] helpviewer_keywords: ["C2558"] -ms.assetid: 822b701e-dcae-423a-b21f-47f36aff9c90 --- # Compiler Error C2558 -'identifier' : no copy constructor available or copy constructor is declared 'explicit' +> 'identifier' : no copy constructor available or copy constructor is declared 'explicit' + +## Remarks A copy constructor initializes an object from another object of the same type. (It makes a copy of the object.) The compiler generates a default copy constructor if you do not define any constructors. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2561.md b/docs/error-messages/compiler-errors-2/compiler-error-c2561.md index 474c57ced61..82c6dd35778 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2561.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2561.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2561" title: "Compiler Error C2561" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2561" +ms.date: 11/04/2016 f1_keywords: ["C2561"] helpviewer_keywords: ["C2561"] -ms.assetid: 0abe955b-53a6-4a3c-8362-b1a8eb40e8d1 --- # Compiler Error C2561 -'identifier' : function must return a value +> 'identifier' : function must return a value + +## Remarks The function was declared as returning a value, but the function definition does not contain a **`return`** statement. @@ -20,7 +21,9 @@ This error can be caused by an incorrect function prototype: 1. C++ functions containing inline assembly routines that store the return value in the `AX` register may need a return statement. Copy the value in `AX` to a temporary variable and return that variable from the function. -The following sample generates C2561: +## Example + +The following example generates C2561: ```cpp // C2561.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2562.md b/docs/error-messages/compiler-errors-2/compiler-error-c2562.md index 9e95f4fecd7..b0a67f988fc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2562.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2562.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2562" title: "Compiler Error C2562" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2562" +ms.date: 11/04/2016 f1_keywords: ["C2562"] helpviewer_keywords: ["C2562"] -ms.assetid: 2c41e511-9952-4b98-9976-6b1523613e1b --- # Compiler Error C2562 -'identifier' : 'void' function returning a value +> 'identifier' : 'void' function returning a value + +## Remarks The function is declared as **`void`** but returns a value. @@ -16,7 +17,9 @@ This error can be caused by an incorrect function prototype. This error may be fixed if you specify the return type in the function declaration. -The following sample generates C2562: +## Example + +The following example generates C2562: ```cpp // C2562.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2563.md b/docs/error-messages/compiler-errors-2/compiler-error-c2563.md index 5b7c1e30083..8a0d90be59e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2563.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2563.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2563" title: "Compiler Error C2563" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2563" +ms.date: 11/04/2016 f1_keywords: ["C2563"] helpviewer_keywords: ["C2563"] -ms.assetid: 54abba68-6458-4ca5-894d-3babdb7b3552 --- # Compiler Error C2563 -mismatch in formal parameter list +> mismatch in formal parameter list + +## Remarks The formal parameter list of a function (or a pointer to a function) does not match those of another function (or pointer to a member function). As a result, the assignment of functions or pointers cannot be made. -The following sample generates C2563: +## Example + +The following example generates C2563: ```cpp // C2563.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2566.md b/docs/error-messages/compiler-errors-2/compiler-error-c2566.md index 1deba5aad6c..728f0d13a2f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2566.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2566.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2566" title: "Compiler Error C2566" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2566" +ms.date: 11/04/2016 f1_keywords: ["C2566"] helpviewer_keywords: ["C2566"] -ms.assetid: 8fe10fb2-d974-432a-a56b-3a61b9a8dfc2 --- # Compiler Error C2566 -overloaded function in conditional expression +> overloaded function in conditional expression + +## Remarks An overloaded function in a conditional expression cannot be evaluated. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2567.md b/docs/error-messages/compiler-errors-2/compiler-error-c2567.md index cda3fa6ee81..9e75dfef04b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2567.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2567.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2567" title: "Compiler Error C2567" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2567" +ms.date: 11/04/2016 f1_keywords: ["C2567"] helpviewer_keywords: ["C2567"] -ms.assetid: 9c140ac9-7059-47e6-9ba1-e7939c8c0dc3 --- # Compiler Error C2567 -unable to open metadata in 'file', file may have been deleted or moved +> unable to open metadata in 'file', file may have been deleted or moved + +## Remarks A metadata file that was referenced in source (with `#using`) was not found in the same directory by the compiler back end process as it was by the compiler front end process. See [#using Directive](../../preprocessor/hash-using-directive-cpp.md) for more information. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2568.md b/docs/error-messages/compiler-errors-2/compiler-error-c2568.md index a68ce21d1c6..20930150ec5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2568.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2568.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2568" title: "Compiler Error C2568" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2568" +ms.date: 11/04/2016 f1_keywords: ["C2568"] helpviewer_keywords: ["C2568"] -ms.assetid: 140b4dc9-5a88-4032-9aef-a224bb796f72 --- # Compiler Error C2568 -'identifier1' : unable to resolve function overload +> 'identifier1' : unable to resolve function overload + +## Remarks The compiler cannot determine which overloaded function to call. The actual parameters passed to the function must be cast to match the formal parameters for one of the overloaded function, but no one match is unambiguously better than all others. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2569.md b/docs/error-messages/compiler-errors-2/compiler-error-c2569.md index d3ac69ec987..ca20d30dba3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2569.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2569.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2569" title: "Compiler Error C2569" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2569" +ms.date: 11/04/2016 f1_keywords: ["C2569"] helpviewer_keywords: ["C2569"] -ms.assetid: 092bed1e-f631-436c-9586-7750629f6fac --- # Compiler Error C2569 -'EnumOrUnion' : enum/union cannot be used as a base class +> 'EnumOrUnion' : enum/union cannot be used as a base class + +## Remarks If you must derive a type from the specified union or enumeration, change the union or enumeration to a class or structure. -The following sample generates C2569: +## Example + +The following example generates C2569: ```cpp // C2569.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2570.md b/docs/error-messages/compiler-errors-2/compiler-error-c2570.md index 161805be9e0..29977145390 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2570.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2570.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2570" title: "Compiler Error C2570" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2570" +ms.date: 11/04/2016 f1_keywords: ["C2570"] helpviewer_keywords: ["C2570"] -ms.assetid: d65d0b32-2fac-464a-bcdf-0ebcedf3bf32 --- # Compiler Error C2570 -'identifier' : union cannot have base classes +> 'identifier' : union cannot have base classes + +## Remarks A union derives from a class, structure, or union. This is not allowed. Declare the derived type as a class or structure instead. -The following sample generates C2570: +## Example + +The following example generates C2570: ```cpp // C2570.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2571.md b/docs/error-messages/compiler-errors-2/compiler-error-c2571.md index ac2efce8e24..358d64654b2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2571.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2571.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2571" title: "Compiler Error C2571" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2571" +ms.date: 11/04/2016 f1_keywords: ["C2571"] helpviewer_keywords: ["C2571"] -ms.assetid: c6522616-dee9-4d7d-9bf8-30a7e1deaadf --- # Compiler Error C2571 -'function' : virtual function cannot be in union 'union' +> 'function' : virtual function cannot be in union 'union' + +## Remarks A union is declared with a virtual function. You can declare a virtual function only in a class or structure. Possible resolutions: @@ -16,7 +17,9 @@ A union is declared with a virtual function. You can declare a virtual function 1. Make the function nonvirtual. -The following sample generates C2571: +## Example + +The following example generates C2571: ```cpp // C2571.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2572.md b/docs/error-messages/compiler-errors-2/compiler-error-c2572.md index eec5bbb70f0..44a23efa094 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2572.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2572.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2572" title: "Compiler Error C2572" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2572" +ms.date: 11/04/2016 f1_keywords: ["C2572"] helpviewer_keywords: ["C2572"] -ms.assetid: f1a42d69-727d-4ce5-88c8-d5f55dea66ac --- # Compiler Error C2572 -'class::member' : redefinition of default parameter : parameter param +> 'class::member' : redefinition of default parameter : parameter param + +## Remarks Default parameters cannot be redefined. If you require another value for the parameter, the default parameter should be left undefined. -The following sample generates C2572: +## Example + +The following example generates C2572: ```cpp // C2572.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2573.md b/docs/error-messages/compiler-errors-2/compiler-error-c2573.md index 435289285d2..28c8053df8d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2573.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2573.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2573" title: "Compiler Error C2573" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2573" +ms.date: 11/04/2016 f1_keywords: ["C2573"] helpviewer_keywords: ["C2573"] -ms.assetid: 2ce523da-da3c-4fb4-bad2-fbde663dbfbf --- # Compiler Error C2573 -'class' : cannot delete pointers to objects of this type; the class has no non-placement overload for 'operator delete'. +> 'class' : cannot delete pointers to objects of this type; the class has no non-placement overload for 'operator delete'. + +## Remarks The class is missing a non-placement delete operator. 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 0581e78c1fa..cc557824ff5 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-c2575.md b/docs/error-messages/compiler-errors-2/compiler-error-c2575.md index ac5c97f6e50..1e9527cef38 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2575.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2575.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2575" title: "Compiler Error C2575" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2575" +ms.date: 11/04/2016 f1_keywords: ["C2575"] helpviewer_keywords: ["C2575"] -ms.assetid: 9eb45706-37ef-4481-b373-6d193ba13634 --- # Compiler Error C2575 -'identifier' : only member functions and bases can be virtual +> 'identifier' : only member functions and bases can be virtual + +## Remarks A global function or class is declared **`virtual`**. This is not allowed. -The following sample generates C2575: +## Example + +The following example generates C2575: ```cpp // C2575.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2577.md b/docs/error-messages/compiler-errors-2/compiler-error-c2577.md index c935a62d6f2..45c7e0f6b16 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2577.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2577.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2577" title: "Compiler Error C2577" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2577" +ms.date: 11/04/2016 f1_keywords: ["C2577"] helpviewer_keywords: ["C2577"] -ms.assetid: fc79ef83-8362-40a2-9257-8037c3195ce4 --- # Compiler Error C2577 -'member' : destructor/finalizer cannot have a return type +> 'member' : destructor/finalizer cannot have a return type + +## Remarks A destructor or finalizer cannot return a value of **`void`** or any other type. Remove the **`return`** statement from the destructor definition. ## Example -The following sample generates C2577. +The following example generates C2577. ```cpp // C2577.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2579.md b/docs/error-messages/compiler-errors-2/compiler-error-c2579.md index f40da38fe60..f4e504ca778 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2579.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2579.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2579" title: "Compiler Error C2579" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2579" +ms.date: 11/04/2016 f1_keywords: ["C2579"] helpviewer_keywords: ["C2579"] -ms.assetid: ab090a8d-5462-4046-a1a6-8007e354dedb --- # Compiler Error C2579 -unable to resolve type 'type' (offset). It is expected in file +> unable to resolve type 'type' (offset). It is expected in file + +## Remarks C2579 always follows C4691. For more information, see [Compiler Warning (level 1) C4691](../../error-messages/compiler-warnings/compiler-warning-level-1-c4691.md). diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2581.md b/docs/error-messages/compiler-errors-2/compiler-error-c2581.md index c6e7b9a608c..9097b0b6b34 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2581.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2581.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2581" title: "Compiler Error C2581" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2581" +ms.date: 11/04/2016 f1_keywords: ["C2581"] helpviewer_keywords: ["C2581"] -ms.assetid: 24a4e4c1-24d3-4e42-b760-7dcaf9740b16 --- # Compiler Error C2581 -'type' : static 'operator =' function is illegal +> 'type' : static 'operator =' function is illegal + +## Remarks The assignment (`=`) operator is incorrectly declared as **`static`**. Assignment operators cannot be **`static`**. For more information, see [User-Defined Operators (C++/CLI)](../../dotnet/user-defined-operators-cpp-cli.md). ## Example -The following sample generates C2581. +The following example generates C2581. ```cpp // C2581.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2582.md b/docs/error-messages/compiler-errors-2/compiler-error-c2582.md index 82484c7c1ad..2a57df672e8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2582.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2582.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2582" title: "Compiler Error C2582" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2582" +ms.date: 11/04/2016 f1_keywords: ["C2582"] helpviewer_keywords: ["C2582"] -ms.assetid: ee1b9378-8bcd-4792-b87e-6d7a466d29ed --- # Compiler Error C2582 -'function' function is unavailable in 'type' +> 'function' function is unavailable in 'type' + +## Remarks An attempt was made to assign to an object that does not have an assignment operator. -The following sample generates C2582: +## Example + +The following example generates C2582: ```cpp // C2582.cpp 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 be529b59a76..e6a0d840758 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-c2584.md b/docs/error-messages/compiler-errors-2/compiler-error-c2584.md index e63ec9e0542..8164ce8b38c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2584.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2584.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2584" title: "Compiler Error C2584" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2584" +ms.date: 11/04/2016 f1_keywords: ["C2584"] helpviewer_keywords: ["C2584"] -ms.assetid: 836e2c0a-86c0-4742-b432-beb0191ad20e --- # Compiler Error C2584 -'Class' : direct base 'Base2' is inaccessible; already a base of 'Base1' +> 'Class' : direct base 'Base2' is inaccessible; already a base of 'Base1' + +## Remarks `Class` already derives directly from `Base1`. `Base2` also derives from `Base1`. `Class` cannot derive from `Base2` because that would mean inheriting (indirectly) from `Base1` again, which is not legal because `Base1` is already a direct base class. ## Example -The following sample generates C2584. +The following example generates C2584. ```cpp // C2584.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2585.md b/docs/error-messages/compiler-errors-2/compiler-error-c2585.md index 7ced014cea2..32c34f271a4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2585.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2585.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2585" title: "Compiler Error C2585" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2585" +ms.date: 11/04/2016 f1_keywords: ["C2585"] helpviewer_keywords: ["C2585"] -ms.assetid: 05bb1a9c-28fb-4a88-a1b5-aea85ebdee1c --- # Compiler Error C2585 -explicit conversion to 'type' is ambiguous +> explicit conversion to 'type' is ambiguous + +## Remarks The type conversion can produce more than one result. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2586.md b/docs/error-messages/compiler-errors-2/compiler-error-c2586.md index a5767ea958e..412a45f14d8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2586.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2586.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2586" title: "Compiler Error C2586" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2586" +ms.date: 11/04/2016 f1_keywords: ["C2586"] helpviewer_keywords: ["C2586"] -ms.assetid: dae703c7-5c38-4db6-8411-4d1b22713eb5 --- # Compiler Error C2586 -incorrect user-defined conversion syntax : illegal indirections +> incorrect user-defined conversion syntax : illegal indirections + +## Remarks Indirection of a conversion operator is not allowed. -The following sample generates C2586: +## Example + +The following example generates C2586: ```cpp // c2586.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2587.md b/docs/error-messages/compiler-errors-2/compiler-error-c2587.md index dd0b86bde45..f70167f35f9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2587.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2587.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2587" title: "Compiler Error C2587" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2587" +ms.date: 11/04/2016 f1_keywords: ["C2587"] helpviewer_keywords: ["C2587"] -ms.assetid: 7637a2c7-35d4-4b5a-a8f2-515a7bda98fd --- # Compiler Error C2587 -'identifier' : illegal use of local variable as default parameter +> 'identifier' : illegal use of local variable as default parameter + +## Remarks Local variables are not allowed as default parameters. -The following sample generates C2587: +## Example + +The following example generates C2587: ```cpp // C2587.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2588.md b/docs/error-messages/compiler-errors-2/compiler-error-c2588.md index 97560fa93c1..774f364b96c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2588.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2588.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2588" title: "Compiler Error C2588" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2588" +ms.date: 11/04/2016 f1_keywords: ["C2588"] helpviewer_keywords: ["C2588"] -ms.assetid: 19a0cabd-ca13-44a5-9be3-ee676abf9bc4 --- # Compiler Error C2588 -'::~identifier' : illegal global destructor +> '::~identifier' : illegal global destructor + +## Remarks The destructor is defined for something other than a class, structure, or union. This is not allowed. This error can be caused by a missing class, structure, or union name on the left side of the scope resolution (`::`) operator. -The following sample generates C2588: +## Example + +The following example generates C2588: ```cpp // C2588.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2589.md b/docs/error-messages/compiler-errors-2/compiler-error-c2589.md index e712be3b261..3f7e4fa6da6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2589.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2589.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2589" title: "Compiler Error C2589" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2589" +ms.date: 11/04/2016 f1_keywords: ["C2589"] helpviewer_keywords: ["C2589"] -ms.assetid: 1d7942c7-8a81-4bb4-b272-76a0019e8513 --- # Compiler Error C2589 -'identifier' : illegal token on right side of '::' +> 'identifier' : illegal token on right side of '::' + +## Remarks If a class, structure, or union name appears to the left of the scope-resolution operator (double colons), the token on the right must be a class, structure, or union member. Otherwise, any global identifier can appear on the right. The scope-resolution operator cannot be overloaded. -The following sample generates C2589: +## Example + +The following example generates C2589: ```cpp // C2589.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2592.md b/docs/error-messages/compiler-errors-2/compiler-error-c2592.md index 637edee9781..054f08281e8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2592.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2592.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2592" title: "Compiler Error C2592" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2592" +ms.date: 11/04/2016 f1_keywords: ["C2592"] helpviewer_keywords: ["C2592"] -ms.assetid: 833a4d7b-66ef-4d4c-ae83-a533c2b0eb07 --- # Compiler Error C2592 -'class': 'base_class_2' is inherited from 'base_class_1' and cannot be re-specified +> 'class': 'base_class_2' is inherited from 'base_class_1' and cannot be re-specified + +## Remarks You can only specify base classes that do not inherit from other base classes. In this case, only `base_class_1` is needed in the specification of **`class`** because `base_class_1` already inherits `base_class_2`. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2593.md b/docs/error-messages/compiler-errors-2/compiler-error-c2593.md index b12f1563fd6..b31ff336de4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2593.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2593.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2593" title: "Compiler Error C2593" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2593" +ms.date: 11/04/2016 f1_keywords: ["C2593"] helpviewer_keywords: ["C2593"] -ms.assetid: 4a0fe9bb-2163-447d-91f6-1890ed8250f6 --- # Compiler Error C2593 -'operator identifier' is ambiguous +> 'operator identifier' is ambiguous + +## Remarks More than one possible operator is defined for an overloaded operator. This error may be fixed if you use an explicit cast on one or more actual parameters. -The following sample generates C2593: +## Examples + +The following example generates C2593: ```cpp // C2593.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2594.md b/docs/error-messages/compiler-errors-2/compiler-error-c2594.md index a68fd0ce545..c962231113f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2594.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2594.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2594" title: "Compiler Error C2594" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2594" +ms.date: 11/04/2016 f1_keywords: ["C2594"] helpviewer_keywords: ["C2594"] -ms.assetid: 68cd708f-266e-44b0-a211-3e3ab63b11bf --- # Compiler Error C2594 -'operator' : ambiguous conversions from 'type1' to 'type2' +> 'operator' : ambiguous conversions from 'type1' to 'type2' + +## Remarks No conversion from *type1* to *type2* was more direct than any other. We suggest two possible solutions to converting from *type1* to *type2*. The first option is to define a direct conversion from *type1* to *type2*, and the second option is to specify a sequence of conversions from *type1* to *type2*. -The following sample generates C2594. The suggested resolution to the error is a sequence of conversions: +## Example + +The following example generates C2594. The suggested resolution to the error is a sequence of conversions: ```cpp // C2594.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2597.md b/docs/error-messages/compiler-errors-2/compiler-error-c2597.md index 1c77cfc6004..ed1bcf191ce 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2597.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2597.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2597" title: "Compiler Error C2597" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2597" +ms.date: 11/04/2016 f1_keywords: ["C2597"] helpviewer_keywords: ["C2597"] -ms.assetid: 2e48127d-e3ff-4a40-8156-2863e45b1a38 --- # Compiler Error C2597 -illegal reference to non-static member 'identifier' +> illegal reference to non-static member 'identifier' + +## Remarks Possible causes: @@ -18,7 +19,9 @@ Possible causes: 1. A member access operator refers to a nonmember function. -1. The following sample generates C2597 and shows how to fix it: +## Example + +1. The following example generates C2597 and shows how to fix it: ```cpp // C2597.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2598.md b/docs/error-messages/compiler-errors-2/compiler-error-c2598.md index 017757d46f4..9e996c4837a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2598.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2598.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2598" title: "Compiler Error C2598" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2598" +ms.date: 11/04/2016 f1_keywords: ["C2598"] helpviewer_keywords: ["C2598"] -ms.assetid: 40777c62-39ba-441e-b081-f49f94b43547 --- # Compiler Error C2598 -linkage specification must be at global scope +> linkage specification must be at global scope + +## Remarks The linkage specifier is declared at local scope. -The following sample generates C2598: +## Example + +The following example generates C2598: ```cpp // C2598.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2599.md b/docs/error-messages/compiler-errors-2/compiler-error-c2599.md index 4d8490f2778..56a13a45eeb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2599.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2599.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2599" title: "Compiler Error C2599" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2599" +ms.date: 11/04/2016 f1_keywords: ["C2599"] helpviewer_keywords: ["C2599"] -ms.assetid: 88515f36-7589-47e2-862e-0de8b18d6668 --- # Compiler Error C2599 -'enum' : forward declaration of enum type is not allowed +> 'enum' : forward declaration of enum type is not allowed + +## Remarks The compiler no longer supports forward declaration of a managed enumeration. Forward declaration of an enum type is not allowed under [/Za](../../build/reference/za-ze-disable-language-extensions.md). -The following sample generates C2599: +## Example + +The following example generates C2599: ```cpp // C2599.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2600.md b/docs/error-messages/compiler-errors-2/compiler-error-c2600.md index 75038e37b85..63dcc2d64a0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2600.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2600.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2600" title: "Compiler Error C2600" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2600" +ms.date: 11/04/2016 f1_keywords: ["C2600"] helpviewer_keywords: ["C2600"] -ms.assetid: cce11943-ea01-4bee-a7b0-b67d24ec6493 --- # Compiler Error C2600 -'function' : cannot define a compiler-generated special member function (must be declared in the class first) +> 'function' : cannot define a compiler-generated special member function (must be declared in the class first) + +## Remarks Before member functions such as constructors or destructors can be defined for a class, they must be declared in the class. The compiler can generate default constructors and destructors (called special member functions) if none are declared in the class. However, if you define one of these functions without a matching declaration in the class, the compiler detects a conflict. To fix this error, in the class declaration, declare each member function that you define outside the class declaration. -The following sample generates C2600: +## Example + +The following example generates C2600: ```cpp // C2600.cpp 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 451d97d15cc..0a5225628f3 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-c2602.md b/docs/error-messages/compiler-errors-2/compiler-error-c2602.md index dabc0048be8..bc32d316af0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2602.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2602.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2602" title: "Compiler Error C2602" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2602" +ms.date: 11/04/2016 f1_keywords: ["C2602"] helpviewer_keywords: ["C2602"] -ms.assetid: 6c07a40e-537e-4954-b5c5-1e0e58fe1952 --- # Compiler Error C2602 -'class::Identifier' is not a member of a base class of 'class' +> 'class::Identifier' is not a member of a base class of 'class' + +## Remarks `Identifier` cannot be accessed because it is not a member inherited from any base class. -The following sample generates C2602: +## Example + +The following example generates C2602: ```cpp // C2602.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2603.md b/docs/error-messages/compiler-errors-2/compiler-error-c2603.md index c66a5ff3e1c..c4700923f0f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2603.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2603.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2603" title: "Compiler Error C2603" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2603" +ms.date: 11/04/2016 f1_keywords: ["C2603"] helpviewer_keywords: ["C2603"] -ms.assetid: 9ca520d0-f082-4b65-933d-17c3bcf8b02c --- # Compiler Error C2603 > '*function*' : Too many block scope static objects with constructor/destructors in function +## Remarks + In versions of the Microsoft C++ compiler before Visual Studio 2015, or when the [/Zc:threadSafeInit-](../../build/reference/zc-threadsafeinit-thread-safe-local-static-initialization.md) compiler option is specified, there is a limit of 31 on the number of static objects you can have in an externally visible inline function. To resolve this issue, we recommend you adopt more recent version of the Microsoft C++ compiler toolset, or if possible, remove the /Zc:threadSafeInit- compiler option. If this is not possible, consider combining your static objects. If the objects are of the same type, consider use of a single static array of that type, and reference individual members as required. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2605.md b/docs/error-messages/compiler-errors-2/compiler-error-c2605.md index a11f99a7a35..ee73a6aa642 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2605.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2605.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2605" title: "Compiler Error C2605" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2605" +ms.date: 11/04/2016 f1_keywords: ["C2605"] helpviewer_keywords: ["C2605"] -ms.assetid: a0e6f132-5acf-4e19-b277-ddf196d182bf --- # Compiler Error C2605 -'name' : this method is reserved within a managed or WinRT class +> 'name' : this method is reserved within a managed or WinRT class + +## Remarks Certain names are reserved by the compiler for internal functions. For more information, see [Destructors and finalizers](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Destructors_and_finalizers). ## Example -The following sample generates C2605. +The following example generates C2605. ```cpp // C2605.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2611.md b/docs/error-messages/compiler-errors-2/compiler-error-c2611.md index 46d020f2d8d..9c4825ce615 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2611.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2611.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2611" title: "Compiler Error C2611" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2611" +ms.date: 11/04/2016 f1_keywords: ["C2611"] helpviewer_keywords: ["C2611"] -ms.assetid: 3f2d5253-f24f-4724-83d0-6b2aa6a4e551 --- # Compiler Error C2611 -'token' : illegal following '~' (expected identifier) +> 'token' : illegal following '~' (expected identifier) + +## Remarks The token is not an identifier. -The following sample generates C2611: +## Example + +The following example generates C2611: ```cpp // C2611.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2612.md b/docs/error-messages/compiler-errors-2/compiler-error-c2612.md index 58b1d0ff3d6..2966afaeb11 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2612.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2612.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2612" title: "Compiler Error C2612" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2612" +ms.date: 11/04/2016 f1_keywords: ["C2612"] helpviewer_keywords: ["C2612"] -ms.assetid: 6faacfd6-4455-41a2-808e-0f6799f84d6d --- # Compiler Error C2612 -trailing 'char' illegal in base/member initializer list +> trailing 'char' illegal in base/member initializer list + +## Remarks A character appears after the last base or member in an initializer list. -The following sample generates C2612: +## Example + +The following example generates C2612: ```cpp // C2612.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2613.md b/docs/error-messages/compiler-errors-2/compiler-error-c2613.md index 547668b933c..70ef49410d0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2613.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2613.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2613" title: "Compiler Error C2613" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2613" +ms.date: 11/04/2016 f1_keywords: ["C2613"] helpviewer_keywords: ["C2613"] -ms.assetid: d8fa7b32-08cb-4bb4-96e7-c04dded0e917 --- # Compiler Error C2613 -trailing ',' illegal in base class list +> trailing ',' illegal in base class list + +## Remarks A comma appears after the last base in a base class list. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2614.md b/docs/error-messages/compiler-errors-2/compiler-error-c2614.md index 7b3c6312ac8..4764e9574fa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2614.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2614.md @@ -1,32 +1,33 @@ --- -description: "Learn more about: Compiler Error C2614" title: "Compiler Error C2614" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2614" +ms.date: 11/04/2016 f1_keywords: ["C2614"] helpviewer_keywords: ["C2614"] -ms.assetid: a550c1d5-8718-4e17-a888-b2619e00fe11 --- # Compiler Error C2614 -'class1' : illegal member initialization: 'class2' is not a base or member +> 'class1' : illegal member initialization: 'class2' is not a base or member + +## Remarks Only member or base classes can appear in the initialization list for a class or structure. ## Example -The following sample generates C2614. +The following example generates C2614. ```cpp // C2614.cpp // compile with: /c struct A { int i; - A( int ia ) : B( i ) {}; // C2614 B is not a member of A + A( int ia ) : B( i ) {} // C2614 B is not a member of A }; struct A2 { int B; int i; - A2( int ia ) : B( i ) {}; // OK + A2( int ia ) : B( i ) {} // OK }; ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2616.md b/docs/error-messages/compiler-errors-2/compiler-error-c2616.md index 77c845af313..9da31ed6fe6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2616.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2616.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2616" title: "Compiler Error C2616" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2616" +ms.date: 11/04/2016 f1_keywords: ["C2616"] helpviewer_keywords: ["C2616"] -ms.assetid: 8d0c02d6-a0b0-4135-b10f-438d67da68c6 --- # Compiler Error C2616 -'conversion' : cannot implicitly convert a non-lvalue 'type1' to a 'type2' that is not const +> 'conversion' : cannot implicitly convert a non-lvalue 'type1' to a 'type2' that is not const + +## Remarks A reference cannot be initialized from a non-lvalue. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2617.md b/docs/error-messages/compiler-errors-2/compiler-error-c2617.md index 1cd6a242ae3..a868e75c05d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2617.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2617.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2617" title: "Compiler Error C2617" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2617" +ms.date: 11/04/2016 f1_keywords: ["C2617"] helpviewer_keywords: ["C2617"] -ms.assetid: d6a435d2-7d95-4dbf-ad4a-abe4744f63e8 --- # Compiler Error C2617 -'function' : inconsistent return statement +> 'function' : inconsistent return statement + +## Remarks The specified function does not have a declared return type, and a previous return statement did not supply a value. -The following sample generates C2617: +## Example + +The following example generates C2617: ```cpp // C2617.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2619.md b/docs/error-messages/compiler-errors-2/compiler-error-c2619.md index 0b31549ce06..7defff06cd1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2619.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2619.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2619" title: "Compiler Error C2619" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2619" +ms.date: 11/04/2016 f1_keywords: ["C2619"] helpviewer_keywords: ["C2619"] -ms.assetid: c826f8ab-d66a-4b79-a0b2-93b0af8c41ac --- # Compiler Error C2619 -'identifier': a static data member is not allowed in an anonymous struct or union +> 'identifier': a static data member is not allowed in an anonymous struct or union + +## Remarks A member of an anonymous struct or union is declared **`static`**. -The following sample generates C2619, and demonstrates how to fix it by removing the static keyword. +## Example + +The following example generates C2619, and demonstrates how to fix it by removing the static keyword. ```cpp // C2619.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2624.md b/docs/error-messages/compiler-errors-2/compiler-error-c2624.md index 7532dae0b40..a1e2ad3153d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2624.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2624.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2624" title: "Compiler Error C2624" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2624" +ms.date: 11/04/2016 f1_keywords: ["C2624"] helpviewer_keywords: ["C2624"] -ms.assetid: 32f2ec15-a7cd-4049-a64b-131746d3152b --- # Compiler Error C2624 -local classes cannot be used to declare 'extern' variables +> local classes cannot be used to declare 'extern' variables + +## Remarks A local class or structure cannot be used to declare **`extern`** variables. -The following sample generates C2624: +## Example + +The following example generates C2624: ```cpp // C2624.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2626.md b/docs/error-messages/compiler-errors-2/compiler-error-c2626.md index 3ee3d112c02..bc83bd476dc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2626.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2626.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2626" title: "Compiler Error C2626" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2626" +ms.date: 11/04/2016 f1_keywords: ["C2626"] helpviewer_keywords: ["C2626"] -ms.assetid: 4c283ad0-251b-4571-bc18-468b9836746f --- # Compiler Error C2626 -'identifier': a private or protected data member is not allowed in an anonymous struct or union +> 'identifier': a private or protected data member is not allowed in an anonymous struct or union + +## Remarks A member of an anonymous struct or union must have public access. -The following sample generates C2626: +## Example + +The following example generates C2626: ```cpp // C2626.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2627.md b/docs/error-messages/compiler-errors-2/compiler-error-c2627.md index f0cd09ab0b8..b35f668333b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2627.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2627.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2627" title: "Compiler Error C2627" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2627" +ms.date: 11/04/2016 f1_keywords: ["C2627"] helpviewer_keywords: ["C2627"] -ms.assetid: 7fc6c5ac-c7c9-4f0b-ad52-f52252526458 --- # Compiler Error C2627 -'function' : member function not allowed in anonymous union +> 'function' : member function not allowed in anonymous union + +## Remarks An [anonymous union](../../cpp/unions.md#anonymous_unions) cannot have member functions. -The following sample generates C2627: +## Example + +The following example generates C2627: ```cpp // C2627.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2628.md b/docs/error-messages/compiler-errors-2/compiler-error-c2628.md index 561bc2aa568..e398afc1aa4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2628.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2628.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2628" title: "Compiler Error C2628" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2628" +ms.date: 11/04/2016 f1_keywords: ["C2628"] helpviewer_keywords: ["C2628"] -ms.assetid: 19a25e77-d5be-4107-88d5-0745b6281f98 --- # Compiler Error C2628 -'type1' followed by 'type2' is illegal (did you forget a ';'?) +> 'type1' followed by 'type2' is illegal (did you forget a ';'?) + +## Remarks A semicolon may be missing. -The following sample generates C2628: +## Example + +The following example generates C2628: ```cpp // C2628.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2630.md b/docs/error-messages/compiler-errors-2/compiler-error-c2630.md index 205a06a4753..367ec0360cc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2630.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2630.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2630" title: "Compiler Error C2630" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2630" +ms.date: 11/04/2016 f1_keywords: ["C2630"] helpviewer_keywords: ["C2630"] -ms.assetid: 7a655a9c-bab4-495b-97a3-a3f34cf5369a --- # Compiler Error C2630 -'symbol' found in what should be a comma-separated list +> 'symbol' found in what should be a comma-separated list + +## Remarks The symbol appears in a context that requires a comma. -The following sample generates C2630: +## Example + +The following example generates C2630: ```cpp // C2630.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2632.md b/docs/error-messages/compiler-errors-2/compiler-error-c2632.md index 2471e652250..28b0937c21b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2632.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2632.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2632" title: "Compiler Error C2632" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2632" +ms.date: 11/04/2016 f1_keywords: ["C2632"] helpviewer_keywords: ["C2632"] -ms.assetid: b15a6b1b-42d2-4e1b-8660-e6bfde61052d --- # Compiler Error C2632 -'type1' followed by 'type2' is illegal +> 'type1' followed by 'type2' is illegal + +## Remarks This error can be caused if there is missing code between two type specifiers. -The following sample generates C2632: +## Examples + +The following example generates C2632: ```cpp // C2632.cpp @@ -21,7 +24,7 @@ int float i; // C2632 This error can also be generated as a result of compiler conformance work that was done for Visual Studio .NET 2003. **`bool`** is now a proper type. In previous versions, **`bool`** was a typedef, and you could create identifiers with that name. -The following sample generates C2632: +The following example generates C2632: ```cpp // C2632_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2633.md b/docs/error-messages/compiler-errors-2/compiler-error-c2633.md index db695cecb70..4270773097f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2633.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2633.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2633" title: "Compiler Error C2633" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2633" +ms.date: 11/04/2016 f1_keywords: ["C2633"] helpviewer_keywords: ["C2633"] -ms.assetid: a7aceb65-4255-42d6-a8fb-e3cb6c4d2270 --- # Compiler Error C2633 -'identifier' : 'inline' is the only legal storage class for constructors +> 'identifier' : 'inline' is the only legal storage class for constructors + +## Remarks A constructor is declared as a storage class other than inline. -The following sample generates C2633: +## Example + +The following example generates C2633: ```cpp // C2633.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2634.md b/docs/error-messages/compiler-errors-2/compiler-error-c2634.md index 721415f346f..234acb5b249 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2634.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2634.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2634" title: "Compiler Error C2634" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2634" +ms.date: 11/04/2016 f1_keywords: ["C2634"] helpviewer_keywords: ["C2634"] -ms.assetid: 58c8f2db-ac95-4a81-9355-ef3cfb0ba7b3 --- # Compiler Error C2634 -'&class::member' : pointer to reference member is illegal +> '&class::member' : pointer to reference member is illegal + +## Remarks A pointer to a reference member is declared. -The following sample generates C2634: +## Example + +The following example generates C2634: ```cpp // C2634.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2635.md b/docs/error-messages/compiler-errors-2/compiler-error-c2635.md index eb9ed290c46..065efac641f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2635.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2635.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2635" title: "Compiler Error C2635" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2635" +ms.date: 11/04/2016 f1_keywords: ["C2635"] helpviewer_keywords: ["C2635"] -ms.assetid: 9deca2a8-2d61-42eb-9783-6578132ee3fb --- # Compiler Error C2635 -cannot convert an 'identifier1*' to an 'identifier2\*'; conversion from a virtual base class is implied +> cannot convert an 'identifier1*' to an 'identifier2\*'; conversion from a virtual base class is implied + +## Remarks The conversion requires a cast from a **`virtual`** base class to a derived class, which is not allowed. -The following sample generates C2635: +## Example + +The following example generates C2635: ```cpp // C2635.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2636.md b/docs/error-messages/compiler-errors-2/compiler-error-c2636.md index b60fb195320..0d37fabe818 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2636.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2636.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2636" title: "Compiler Error C2636" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2636" +ms.date: 11/04/2016 f1_keywords: ["C2636"] helpviewer_keywords: ["C2636"] -ms.assetid: 379873ec-8d05-49f8-adf1-b067bc07bdb8 --- # Compiler Error C2636 -'identifier' : pointer to reference member is illegal +> 'identifier' : pointer to reference member is illegal + +## Remarks A pointer to a reference member was declared. -The following sample generates C2636: +## Example + +The following example generates C2636: ```cpp // C2636.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2637.md b/docs/error-messages/compiler-errors-2/compiler-error-c2637.md index 40cb31b6061..4eda884eb63 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2637.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2637.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2637" title: "Compiler Error C2637" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2637" +ms.date: 11/04/2016 f1_keywords: ["C2637"] helpviewer_keywords: ["C2637"] -ms.assetid: 58d94447-eb96-4d8f-a690-dd78d322462e --- # Compiler Error C2637 -'identifier' : cannot modify pointers to data members +> 'identifier' : cannot modify pointers to data members + +## Remarks A pointer to a data member cannot have a calling convention. To resolve, either remove the calling convention or declare a pointer to member function. -The following sample generates C2637: +## Example + +The following example generates C2637: ```cpp // C2637.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2638.md b/docs/error-messages/compiler-errors-2/compiler-error-c2638.md index 0f19715ed7f..bb2c3beed90 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2638.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2638.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2638" title: "Compiler Error C2638" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2638" +ms.date: 11/04/2016 f1_keywords: ["C2638"] helpviewer_keywords: ["C2638"] -ms.assetid: 9d4275e8-406d-455e-afee-3a37799230e0 --- # Compiler Error C2638 -'identifier' : __based modifier illegal on pointer to member +> 'identifier' : __based modifier illegal on pointer to member + +## Remarks The **`__based`** modifier cannot be used for pointers to members. -The following sample generates C2638: +## Example + +The following example generates C2638: ```cpp // C2638.cpp 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 c1467898ef6..365c80e4250 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,29 @@ --- -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 + +## Remarks -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: +## Example + +The following example 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-c2645.md b/docs/error-messages/compiler-errors-2/compiler-error-c2645.md index 10f903aa458..51bc814c4a6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2645.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2645.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2645" title: "Compiler Error C2645" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2645" +ms.date: 11/04/2016 f1_keywords: ["C2645"] helpviewer_keywords: ["C2645"] -ms.assetid: 6609c2fa-c3b2-4a6b-8e8d-58fb52f67175 --- # Compiler Error C2645 -no qualified name for pointer to member (found ':: *') +> no qualified name for pointer to member (found ':: *') + +## Remarks The declaration of a pointer to a member does not specify a class. -The following sample generates C2645: +## Example + +The following example generates C2645: ```cpp // C2645.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2646.md b/docs/error-messages/compiler-errors-2/compiler-error-c2646.md index 733efb98bc5..f6c33292e47 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2646.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2646.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2646" title: "Compiler Error C2646" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2646" +ms.date: 11/04/2016 f1_keywords: ["C2646"] helpviewer_keywords: ["C2646"] -ms.assetid: 92ff1f02-5eaf-40a5-8b7a-a682f149e967 --- # Compiler Error C2646 -an anonymous struct or union at global or namespace scope must be declared static +> an anonymous struct or union at global or namespace scope must be declared static + +## Remarks An anonymous struct or union has global or namespace scope but is not declared **`static`**. -The following sample generates C2646 and shows how to fix it: +## Example + +The following example generates C2646 and shows how to fix it: ```cpp // C2646.cpp 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 20f2b56c027..0a6e5dab39d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2647.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2647.md @@ -1,18 +1,21 @@ --- -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' +> 'operator': cannot dereference a 'type1' on a 'type2' + +## Remarks + +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. +## Example -The following sample generates C2647: +The following example generates C2647: ```cpp // C2647.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2648.md b/docs/error-messages/compiler-errors-2/compiler-error-c2648.md index ef44b945847..8ece835b5be 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2648.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2648.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2648" title: "Compiler Error C2648" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2648" +ms.date: 11/04/2016 f1_keywords: ["C2648"] helpviewer_keywords: ["C2648"] -ms.assetid: ce338337-9154-4f85-bb61-b05fdbfad75d --- # Compiler Error C2648 -'identifier' : use of member as default parameter requires static member +> 'identifier' : use of member as default parameter requires static member + +## Remarks A non-static member is used as a default parameter. -The following sample generates C2648: +## Example + +The following example generates C2648: ```cpp // C2648.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2649.md b/docs/error-messages/compiler-errors-2/compiler-error-c2649.md index fb6e19c4f93..5cca3fb8e7a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2649.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2649.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2649" title: "Compiler Error C2649" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2649" +ms.date: 11/04/2016 f1_keywords: ["C2649"] helpviewer_keywords: ["C2649"] -ms.assetid: 09e78f08-9b74-41e7-a76f-66bc190ba0d2 --- # Compiler Error C2649 -'identifier' : is not a 'class-key' +> 'identifier' : is not a 'class-key' + +## Remarks A class, structure, or union declaration uses an incorrect tag. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2650.md b/docs/error-messages/compiler-errors-2/compiler-error-c2650.md index 005db3ee7ac..dfaf2272cb3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2650.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2650.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2650" title: "Compiler Error C2650" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2650" +ms.date: 11/04/2016 f1_keywords: ["C2650"] helpviewer_keywords: ["C2650"] -ms.assetid: 49a8ac6e-aa6d-4616-917c-a3cfcdbad5a4 --- # Compiler Error C2650 -'operator' : cannot be a virtual function +> 'operator' : cannot be a virtual function + +## Remarks A **`new`** or **`delete`** operator is declared **`virtual`**. These operators are **`static`** member functions and cannot be **`virtual`**. ## Example -The following sample generates C2650: +The following example generates C2650: ```cpp // C2650.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2651.md b/docs/error-messages/compiler-errors-2/compiler-error-c2651.md index 1c1c8fcddf5..14c8d273955 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2651.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2651.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2651" title: "Compiler Error C2651" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2651" +ms.date: 11/04/2016 f1_keywords: ["C2651"] helpviewer_keywords: ["C2651"] -ms.assetid: c3524a89-47d1-43f6-9e20-2cda15f9ae8a --- # Compiler Error C2651 -'data type' : left of 'operator' must be a class, struct or union +> 'data type' : left of 'operator' must be a class, struct or union + +## Remarks To use a template parameter as if it is a class, specialize the class template with a class instead of an integral type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2652.md b/docs/error-messages/compiler-errors-2/compiler-error-c2652.md index 8c816d24a78..5e7e2f0ee85 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2652.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2652.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2652" title: "Compiler Error C2652" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2652" +ms.date: 11/04/2016 f1_keywords: ["C2652"] helpviewer_keywords: ["C2652"] -ms.assetid: 6e3d1a90-a989-4088-8afd-dc82f6a2d66f --- # Compiler Error C2652 -'identifier' : illegal copy constructor: first parameter must not be an 'identifier' +> 'identifier' : illegal copy constructor: first parameter must not be an 'identifier' + +## Remarks The first parameter in the copy constructor has the same type as the class, structure, or union for which it is defined. The first parameter can be a reference to the type but not the type itself. -The following sample generates C2651: +## Example + +The following example generates C2652: ```cpp // C2652.cpp 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 b1cbd557784..658521dbf31 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2653.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2653.md @@ -1,24 +1,25 @@ --- -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 > '*identifier*' : is not a class or namespace name +## Remarks + 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 -This sample generates C2653 because a scope name is used but not declared. The compiler expects a class, structure, union, or namespace name before a scope operator (::). +This example generates C2653 because a scope name is used but not declared. The compiler expects a class, structure, union, or namespace name before a scope operator (::). ```cpp // C2653.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2654.md b/docs/error-messages/compiler-errors-2/compiler-error-c2654.md index c1905fbdb7c..2c7a489eb1b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2654.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2654.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2654" title: "Compiler Error C2654" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2654" +ms.date: 11/04/2016 f1_keywords: ["C2654"] helpviewer_keywords: ["C2654"] -ms.assetid: ca7de1bd-576b-40bf-96fc-a91984827d20 --- # Compiler Error C2654 -'identifier' : attempt to access member outside a member function +> 'identifier' : attempt to access member outside a member function + +## Remarks A member is accessed in a declaration. Member data can be accessed only in member functions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2655.md b/docs/error-messages/compiler-errors-2/compiler-error-c2655.md index 77dcb0e48d4..4169ae3ee9f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2655.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2655.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2655" title: "Compiler Error C2655" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2655" +ms.date: 11/04/2016 f1_keywords: ["C2655"] helpviewer_keywords: ["C2655"] -ms.assetid: beaefa6e-51b3-4df9-9150-960f3fbf40e0 --- # Compiler Error C2655 -'identifier' : definition or redeclaration illegal in current scope +> 'identifier' : definition or redeclaration illegal in current scope + +## Remarks An identifier can be redeclared only at global scope. -The following sample generates C2655: +## Example + +The following example generates C2655: ```cpp // C2655.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2656.md b/docs/error-messages/compiler-errors-2/compiler-error-c2656.md index c76d36e6f7b..acdffd18ea1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2656.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2656.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2656" title: "Compiler Error C2656" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2656" +ms.date: 11/04/2016 f1_keywords: ["C2656"] helpviewer_keywords: ["C2656"] -ms.assetid: 1ec91186-0735-4904-859b-59da9af2d426 --- # Compiler Error C2656 -'function' : function not allowed as a bit field +> 'function' : function not allowed as a bit field + +## Remarks A function is declared as a member of a bit field. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2657.md b/docs/error-messages/compiler-errors-2/compiler-error-c2657.md index 8cb0fddc1ef..af0af9e0dd2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2657.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2657.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2657" title: "Compiler Error C2657" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2657" +ms.date: 11/04/2016 f1_keywords: ["C2657"] helpviewer_keywords: ["C2657"] -ms.assetid: f7cf29a9-684a-4605-9469-ecfee9ba4b03 --- # Compiler Error C2657 -'class::*' found at the start of a statement (did you forget to specify a type?) +> 'class::*' found at the start of a statement (did you forget to specify a type?) + +## Remarks The line began with a pointer-to-member identifier. This error can be caused by a missing type specifier in the declaration of a pointer to a member. -The following sample generates C2657: +## Example + +The following example generates C2657: ```cpp // C2657.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2658.md b/docs/error-messages/compiler-errors-2/compiler-error-c2658.md index e71e04ef906..fb3c762da11 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2658.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2658.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2658" title: "Compiler Error C2658" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2658" +ms.date: 11/04/2016 f1_keywords: ["C2658"] helpviewer_keywords: ["C2658"] -ms.assetid: 638368e8-7893-4a14-abec-13c768a9543a --- # Compiler Error C2658 -'member': redefinition in anonymous struct/union +> 'member': redefinition in anonymous struct/union + +## Remarks Two anonymous structures or unions contained member declarations with the same identifier but with different types. Under [/Za](../../build/reference/za-ze-disable-language-extensions.md), you will also get this error for members with the same identifier and type. -The following sample generates C2658: +## Example + +The following example generates C2658: ```cpp // C2658.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2659.md b/docs/error-messages/compiler-errors-2/compiler-error-c2659.md index 8971dceda1f..d02a04abd4f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2659.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2659.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Error C2659" title: "Compiler Error C2659" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2659" +ms.date: 11/04/2016 f1_keywords: ["C2659"] helpviewer_keywords: ["C2659"] -ms.assetid: b0883600-4d27-4ca7-a931-8ca6bd48654d --- # Compiler Error C2659 -'operator' : function as left operand +> 'operator' : function as left operand + +## Remarks + +A function was on the left side of the specified operator. The most common reason for this error is that the compiler has parsed the identifier on the left side of the operator as a function when the developer intended it to be a variable. For more information, see Wikipedia article [Most vexing parse](https://en.wikipedia.org/wiki/Most_vexing_parse). + +## Examples -A function was on the left side of the specified operator. The most common reason for this error is that the compiler has parsed the identifier on the left side of the operator as a function when the developer intended it to be a variable. For more information, see Wikipedia article [Most vexing parse](https://en.wikipedia.org/wiki/Most_vexing_parse). This example shows a function declaration and a variable definition that are easily confused: +This example shows a function declaration and a variable definition that are easily confused: ```cpp // C2659a.cpp @@ -30,7 +35,7 @@ int main() To resolve this issue, change the declaration of the identifier so that it is not parsed as a function declaration. -Error C2659 can also occur when the function has a type that can’t be used in the expression on the left side of the specified operator. This example generates C2659 when the code assigns a function pointer to a function: +Error C2659 can also occur when the function has a type that can't be used in the expression on the left side of the specified operator. This example generates C2659 when the code assigns a function pointer to a function: ```cpp // C2659b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2660.md b/docs/error-messages/compiler-errors-2/compiler-error-c2660.md index b825312531a..206114d0ac4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2660.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2660.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2660" title: "Compiler Error C2660" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2660" +ms.date: 11/04/2016 f1_keywords: ["C2660"] helpviewer_keywords: ["C2660"] -ms.assetid: 2e01a1db-4f00-4df6-a04d-cb6f70a6922b --- # Compiler Error C2660 -'function' : function does not take number parameters +> 'function' : function does not take number parameters + +## Remarks The function is called with an incorrect number of parameters. @@ -20,7 +21,7 @@ C2660 can occur if you accidentally call a Windows API function rather than an M ## Examples -The following sample generates C2660. +The following example generates C2660. ```cpp // C2660.cpp @@ -32,7 +33,7 @@ int main() { } ``` -C2660 can also occur if you attempt to directly call the Dispose method of a managed type. 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 C2660. +C2660 can also occur if you attempt to directly call the Dispose method of a managed type. 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 example generates C2660. ```cpp // C2660_a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2661.md b/docs/error-messages/compiler-errors-2/compiler-error-c2661.md index 9f2a5bbc1c3..720b9f3334e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2661.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2661.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2661" title: "Compiler Error C2661" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2661" +ms.date: 11/04/2016 f1_keywords: ["C2661"] helpviewer_keywords: ["C2661"] -ms.assetid: 60021467-71cd-451b-9877-23840c69309f --- # Compiler Error C2661 -'function' : no overloaded function takes number parameters +> 'function' : no overloaded function takes number parameters + +## Remarks Possible causes: @@ -16,7 +17,9 @@ Possible causes: 1. Missing function declaration. -The following sample generates C2661: +## Example + +The following example generates C2661: ```cpp // C2661.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2662.md b/docs/error-messages/compiler-errors-2/compiler-error-c2662.md index 0afdad4fbd3..b6184513912 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2662.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2662.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2662" title: "Compiler Error C2662" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2662" +ms.date: 11/04/2016 f1_keywords: ["C2662"] helpviewer_keywords: ["C2662"] -ms.assetid: e172c2a4-f29e-4034-8232-e7dc6f83689f --- # Compiler Error C2662 -'function' : cannot convert 'this' pointer from 'type1' to 'type2' +> 'function' : cannot convert 'this' pointer from 'type1' to 'type2' + +## Remarks The compiler could not convert the **`this`** pointer from `type1` to `type2`. @@ -18,7 +19,9 @@ This error can be caused by invoking a non-**`const`** member function on a **`c - Add **`const`** to the member function. -The following sample generates C2662: +## Examples + +The following example generates C2662: ```cpp // C2662.cpp @@ -60,7 +63,7 @@ ref struct N { }; ``` -The following sample generates C2662: +The following example generates C2662: ```cpp // C2662_c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2663.md b/docs/error-messages/compiler-errors-2/compiler-error-c2663.md index 8c3e53207f7..8f6ee981e2b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2663.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2663.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2663" title: "Compiler Error C2663" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2663" +ms.date: 11/04/2016 f1_keywords: ["C2663"] helpviewer_keywords: ["C2663"] -ms.assetid: 1e93e368-fd52-42bf-9908-9b6df467c8c9 --- # Compiler Error C2663 -'function' : number overloads have no legal conversions for 'this' pointer +> 'function' : number overloads have no legal conversions for 'this' pointer + +## Remarks The compiler could not convert **`this`** to any of the overloaded versions of the member function. @@ -18,7 +19,9 @@ This error can be caused by invoking a non-**`const`** member function on a **`c 1. Add **`const`** to one of the member function overloads. -The following sample generates C2663: +## Example + +The following example generates C2663: ```cpp // C2663.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2664.md b/docs/error-messages/compiler-errors-2/compiler-error-c2664.md index c7146ee907d..f08a2cb9704 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2664.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2664.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2664" title: "Compiler Error C2664" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2664" +ms.date: 11/04/2016 f1_keywords: ["C2664"] helpviewer_keywords: ["C2664"] -ms.assetid: 3595d66e-cf87-4fda-a896-c0cd81f95db4 --- # Compiler Error C2664 -'function' : cannot convert argument n from 'type1' to 'type2' +> 'function' : cannot convert argument n from 'type1' to 'type2' + +## Remarks This parameter conversion problem might happen if an instance of a class is created and an implicit conversion is attempted on a constructor marked with the **`explicit`** keyword. For more information about explicit conversions, see [User-Defined Type Conversions](../../cpp/user-defined-type-conversions-cpp.md). @@ -28,19 +29,19 @@ For more information, see [How to: Convert System::String to wchar_t* or char\*] ## Examples -The following sample generates C2664 and shows how to fix it. +The following example generates C2664 and shows how to fix it. ```cpp // C2664.cpp // C2664 struct A { - void f(int i) {}; + void f(int i) {} }; struct B : public A { // To fix, uncomment the following line. // using A::f; - void f(A a) {}; + void f(A a) {} }; int main() { @@ -50,7 +51,7 @@ int main() { } ``` -This sample also generates C2664 and shows how to fix it. +This example also generates C2664 and shows how to fix it. ```cpp // C2664b.cpp @@ -67,7 +68,7 @@ int main() { } ``` -The next sample demonstrates C2664 by using a string literal to call `Test`, and shows how to fix it. Because the parameter is an `szString` reference, an object must be created by the appropriate constructor. The result is a temporary object that cannot be used to initialize the reference. +The next example demonstrates C2664 by using a string literal to call `Test`, and shows how to fix it. Because the parameter is an `szString` reference, an object must be created by the appropriate constructor. The result is a temporary object that cannot be used to initialize the reference. ```cpp // C2664c.cpp @@ -106,7 +107,7 @@ int main() { } ``` -The compiler enforces the C++ standard requirements for applying **`const`**. This sample generates C2664: +The compiler enforces the C++ standard requirements for applying **`const`**. This example generates C2664: ```cpp // C2664d.cpp @@ -172,7 +173,7 @@ int main( ) { } ``` -An enum variable is not converted to its underlying type such that a function call will be satisfied. For more information, see [enum class](../../extensions/enum-class-cpp-component-extensions.md). The following sample generates C2664 and shows how to fix it. +An enum variable is not converted to its underlying type such that a function call will be satisfied. For more information, see [enum class](../../extensions/enum-class-cpp-component-extensions.md). The following example generates C2664 and shows how to fix it. ```cpp // C2664f.cpp @@ -215,7 +216,7 @@ library myproj1 { C2664 is also raised by using **`wchar_t`** when porting code from Visual C++ 6.0 to later versions. In Visual C++ 6.0 and earlier, **`wchar_t`** was a **`typedef`** for **`unsigned short`** and was therefore implicitly convertible to that type. After Visual C++ 6.0, **`wchar_t`** is its own built-in type, as specified in the C++ standard, and is no longer implicitly convertible to **`unsigned short`**. See [/Zc:wchar_t (wchar_t Is Native Type)](../../build/reference/zc-wchar-t-wchar-t-is-native-type.md). -The following sample generates C2664 and shows how to fix it. +The following example generates C2664 and shows how to fix it. ```cpp // C2664h.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2665.md b/docs/error-messages/compiler-errors-2/compiler-error-c2665.md index c1efc17c246..cc110cf8229 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2665.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2665.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2665" title: "Compiler Error C2665" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2665" +ms.date: 11/04/2016 f1_keywords: ["C2665"] helpviewer_keywords: ["C2665"] -ms.assetid: a7f99b61-2eae-4f2b-ba75-ea68fd1e8312 --- # Compiler Error C2665 -'function' : none of the number1 overloads can convert parameter number2 from type 'type' +> 'function' : none of the number1 overloads can convert parameter number2 from type 'type' + +## Remarks A parameter of the overloaded function cannot be converted to the required type. Possible resolutions: @@ -18,7 +19,7 @@ A parameter of the overloaded function cannot be converted to the required type. ## Example -The following sample generates C2665. +The following example generates C2665. ```cpp // C2665.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2666.md b/docs/error-messages/compiler-errors-2/compiler-error-c2666.md index 7307e34bb41..9dbac3a9b13 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2666.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2666.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2666" title: "Compiler Error C2666" +description: "Learn more about: Compiler Error C2666" ms.date: 10/18/2021 f1_keywords: ["C2666"] helpviewer_keywords: ["C2666"] -ms.assetid: 78364d15-c6eb-439a-9088-e04a0176692b --- # Compiler Error C2666 -'identifier' : number overloads have similar conversions +> 'identifier' : number overloads have similar conversions + +## Remarks An overloaded function or operator is ambiguous. Formal parameter lists may be too similar for the compiler to resolve the ambiguity. To resolve this error, explicitly cast one or more of the actual parameters. ## Examples -The following sample generates C2666: +The following example generates C2666: ```cpp // C2666.cpp @@ -141,7 +142,7 @@ int main() } ``` -The following sample generates C2666 +The following example generates C2666 ```cpp // C2666c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2667.md b/docs/error-messages/compiler-errors-2/compiler-error-c2667.md index 17887deb7b7..883874fb3d6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2667.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2667.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2667" title: "Compiler Error C2667" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2667" +ms.date: 11/04/2016 f1_keywords: ["C2667"] helpviewer_keywords: ["C2667"] -ms.assetid: 3c91d9d1-18fa-4e0d-a9ba-984d38980ca3 --- # Compiler Error C2667 -'function' : none of number overloads have a best conversion +> 'function' : none of number overloads have a best conversion + +## Remarks An overloaded function call is ambiguous and cannot be resolved. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2668.md b/docs/error-messages/compiler-errors-2/compiler-error-c2668.md index 797a39b3122..5c85dee6a57 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2668.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2668.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C2668" title: "Compiler Error C2668" +description: "Learn more about: Compiler Error C2668" ms.date: 05/03/2021 f1_keywords: ["C2668"] helpviewer_keywords: ["C2668"] -ms.assetid: 041e9627-1c76-420e-a653-cfc83f933bd3 --- # Compiler Error C2668 > 'function' : ambiguous call to overloaded function +## Remarks + The specified overloaded function call couldn't be resolved. You may want to explicitly cast one or more of the actual parameters. You can also get this error through template use. If, in the same class, you have a regular member function and a templated member function with the same signature, the templated one must come first. This limitation remains in the current implementation of Visual C++. ## Examples -The following sample generates C2668: +The following example generates C2668: ```cpp // C2668.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2669.md b/docs/error-messages/compiler-errors-2/compiler-error-c2669.md index c2145433cb5..13d58e90c33 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2669.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2669.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2669" title: "Compiler Error C2669" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2669" +ms.date: 11/04/2016 f1_keywords: ["C2669"] helpviewer_keywords: ["C2669"] -ms.assetid: f9cb8111-bcdc-484b-a863-2c42e15a0496 --- # Compiler Error C2669 -member function not allowed in anonymous union +> member function not allowed in anonymous union + +## Remarks [Anonymous unions](../../cpp/unions.md#anonymous_unions) cannot have member functions. ## Example -The following sample generates C2669: +The following example generates C2669: ```cpp // C2669.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2670.md b/docs/error-messages/compiler-errors-2/compiler-error-c2670.md index be41ed903cd..a1bfb105edc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2670.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2670.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2670" title: "Compiler Error C2670" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2670" +ms.date: 11/04/2016 f1_keywords: ["C2670"] helpviewer_keywords: ["C2670"] -ms.assetid: 4b3b74c7-a750-4b0d-abd3-216d1234461f --- # Compiler Error C2670 -'identifier' : the function template cannot convert parameter number from type 'type' +> 'identifier' : the function template cannot convert parameter number from type 'type' + +## Remarks A parameter could not be converted to the required type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2671.md b/docs/error-messages/compiler-errors-2/compiler-error-c2671.md index faa1b927d76..fd2c623dd42 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2671.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2671.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2671" title: "Compiler Error C2671" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2671" +ms.date: 11/04/2016 f1_keywords: ["C2671"] helpviewer_keywords: ["C2671"] -ms.assetid: fc0ee40f-c8f3-408f-b89d-745d149c4169 --- # Compiler Error C2671 -'function' : static member functions do not have 'this' pointers +> 'function' : static member functions do not have 'this' pointers + +## Remarks A **`static`** member function tried to access **`this`**. -The following sample generates C2671: +## Example + +The following example generates C2671: ```cpp // C2671.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2672.md b/docs/error-messages/compiler-errors-2/compiler-error-c2672.md index a43ddf67cc8..8af88f34643 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2672.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2672.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2672" title: "Compiler Error C2672" -ms.date: "10/24/2017" +description: "Learn more about: Compiler Error C2672" +ms.date: 10/24/2017 f1_keywords: ["C2672"] helpviewer_keywords: ["C2672"] -ms.assetid: 7e86338a-2d4b-40fe-9dd2-ac6886f3f31a --- # Compiler Error C2672 > '*function*': no matching overloaded function found +## Remarks + The compiler could not find an overloaded function that matches the specified function. No function was found that takes matching parameters, or no matching function has the required accessibility in context. When used by certain standard library containers or algorithms, your types must provide accessible members or friend functions that satisfy the requirements of the container or algorithm. For example, your iterator types should derive from `std::iterator<>`. Comparison operations or use of other operators on container element types may require the type be considered as both a left-hand and a right-hand operand. Use of the type as a right-hand operand can require implementation of the operator as a non-member function of the type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2673.md b/docs/error-messages/compiler-errors-2/compiler-error-c2673.md index b122a1aabbb..bd53c6d9836 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2673.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2673.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2673" title: "Compiler Error C2673" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2673" +ms.date: 11/04/2016 f1_keywords: ["C2673"] helpviewer_keywords: ["C2673"] -ms.assetid: 780230c0-619b-4a78-b01d-ff5886306741 --- # Compiler Error C2673 -'function' : global functions do not have 'this' pointers +> 'function' : global functions do not have 'this' pointers + +## Remarks A global function tried to access **`this`**. -The following sample generates C2673: +## Example + +The following example generates C2673: ```cpp // C2673.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2674.md b/docs/error-messages/compiler-errors-2/compiler-error-c2674.md index 6f86c485aaa..25f54555820 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2674.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2674.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2674" title: "Compiler Error C2674" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2674" +ms.date: 11/04/2016 f1_keywords: ["C2674"] helpviewer_keywords: ["C2674"] -ms.assetid: 7cbd70d8-d992-44d7-a5cb-dd8cf9c759d2 --- # Compiler Error C2674 -a generic declaration is not allowed in this context +> a generic declaration is not allowed in this context + +## Remarks A generic was declared incorrectly. For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The following sample generates C2674. +The following example generates C2674. ```cpp // C2674.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2675.md b/docs/error-messages/compiler-errors-2/compiler-error-c2675.md index 4bd9416580f..44d681044bb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2675.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2675.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2675" title: "Compiler Error C2675" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2675" +ms.date: 11/04/2016 f1_keywords: ["C2675"] helpviewer_keywords: ["C2675"] -ms.assetid: 4b92a12b-bff8-4dd5-a109-620065fc146c --- # Compiler Error C2675 -unary 'operator' : 'type' does not define this operator or a conversion to a type acceptable to the predefined operator +> unary 'operator' : 'type' does not define this operator or a conversion to a type acceptable to the predefined operator + +## Remarks C2675 can also occur when using a unary operator, and the type does not define the operator or a conversion to a type acceptable to the predefined operator. To use the operator, you must overload it for the specified type or define a conversion to a type for which the operator is defined. ## Example -The following sample generates C2675. +The following example generates C2675. ```cpp // C2675.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2676.md b/docs/error-messages/compiler-errors-2/compiler-error-c2676.md index c2368b92a68..f12d12d14d8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2676.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2676.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2676" title: "Compiler Error C2676" +description: "Learn more about: Compiler Error C2676" ms.date: 06/03/2022 f1_keywords: ["C2676"] helpviewer_keywords: ["C2676"] -ms.assetid: 838a5e34-c92f-4f65-a597-e150bf8cf737 --- # Compiler Error C2676 @@ -16,7 +15,7 @@ To use the operator, you must overload it for the specified type or define a con ## Examples -The following sample generates C2676. +The following example generates C2676. ```cpp // C2676.cpp @@ -50,7 +49,7 @@ C2676 can also occur if you attempt to do pointer arithmetic on the **`this`** p The **`this`** pointer is of type handle in a reference type. For more information, see [Semantics of the `this` pointer](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Semantics_of_the_this_pointer). -The following sample generates C2676. +The following example generates C2676. ```cpp // C2676_a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2677.md b/docs/error-messages/compiler-errors-2/compiler-error-c2677.md index e5e8937b497..665726d4c01 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2677.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2677.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2677" title: "Compiler Error C2677" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2677" +ms.date: 11/04/2016 f1_keywords: ["C2677"] helpviewer_keywords: ["C2677"] -ms.assetid: 76bc0b65-f52a-45a6-b6d6-0555f89da9a8 --- # Compiler Error C2677 -binary 'operator' : no global operator found which takes type 'type' (or there is no acceptable conversion) +> binary 'operator' : no global operator found which takes type 'type' (or there is no acceptable conversion) + +## Remarks To use the operator, you must overload it for the specified type or define a conversion to a type for which the operator is defined. -The following sample generates C2677: +## Example + +The following example generates C2677: ```cpp // C2677.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2678.md b/docs/error-messages/compiler-errors-2/compiler-error-c2678.md index 3c56b110b05..6719229f6e9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2678.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2678.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2678" title: "Compiler Error C2678" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2678" +ms.date: 11/04/2016 f1_keywords: ["C2678"] helpviewer_keywords: ["C2678"] -ms.assetid: 1f0a4e26-b429-44f5-9f94-cb66441220c8 --- # Compiler Error C2678 -binary 'operator' : no operator defined which takes a left-hand operand of type 'type' (or there is no acceptable conversion) +> binary 'operator' : no operator defined which takes a left-hand operand of type 'type' (or there is no acceptable conversion) + +## Remarks To use the operator, you must overload it for the specified type or define a conversion to a type for which the operator is defined. @@ -16,7 +17,7 @@ C2678 can occur when the left-hand operand is const-qualified but the operator i ## Examples -The following sample generates C2678 and shows how to fix it: +The following example generates C2678 and shows how to fix it: ```cpp // C2678a.cpp @@ -42,7 +43,7 @@ int main() { C2678 can also occur if you do not pin a native member before calling a member function on it. -The following sample generates C2678 and shows how to fix it. +The following example generates C2678 and shows how to fix it. ```cpp // C2678.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2679.md b/docs/error-messages/compiler-errors-2/compiler-error-c2679.md index 41762a92db1..88f7498add1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2679.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2679.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2679" title: "Compiler Error C2679" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2679" +ms.date: 11/04/2016 f1_keywords: ["C2679"] helpviewer_keywords: ["C2679"] -ms.assetid: 1a5f9d00-9190-4aa6-bc72-949f68ec136f --- # Compiler Error C2679 -binary 'operator' : no operator found which takes a right-hand operand of type 'type' (or there is no acceptable conversion) +> binary 'operator' : no operator found which takes a right-hand operand of type 'type' (or there is no acceptable conversion) + +## Remarks To use the operator, you must overload it for the specified type or define a conversion to a type for which the operator is defined. -The following sample generates C2679: +## Example + +The following example generates C2679: ```cpp // C2679.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2680.md b/docs/error-messages/compiler-errors-2/compiler-error-c2680.md index de9fce157af..29a2effd882 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2680.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2680.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2680" title: "Compiler Error C2680" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2680" +ms.date: 11/04/2016 f1_keywords: ["C2680"] helpviewer_keywords: ["C2680"] -ms.assetid: d6f7129e-dd17-4661-b680-18d6b925b1cc --- # Compiler Error C2680 -'type' : invalid target type for name +> 'type' : invalid target type for name + +## Remarks A casting operator tried to convert to a type that is not a pointer or reference. The [dynamic_cast](../../cpp/dynamic-cast-operator.md) operator can be used only for pointers or references. -The following sample generates C2680: +## Examples + +The following example generates C2680: ```cpp // C2680.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2681.md b/docs/error-messages/compiler-errors-2/compiler-error-c2681.md index 36739b95071..8920a1c75f2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2681.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2681.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2681" title: "Compiler Error C2681" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2681" +ms.date: 11/04/2016 f1_keywords: ["C2681"] helpviewer_keywords: ["C2681"] -ms.assetid: eb42da6d-8d2c-43fd-986b-e73e2b004885 --- # Compiler Error C2681 -'type' : invalid expression type for name +> 'type' : invalid expression type for name + +## Remarks A casting operator tried to convert from an invalid type. For example, if you use the [dynamic_cast](../../cpp/dynamic-cast-operator.md) operator to convert an expression to a pointer type, the source expression must be a pointer. -The following sample generates C2681: +## Example + +The following example generates C2681: ```cpp // C2681.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2682.md b/docs/error-messages/compiler-errors-2/compiler-error-c2682.md index 09a250de791..6dbf392b6f8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2682.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2682.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2682" title: "Compiler Error C2682" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2682" +ms.date: 11/04/2016 f1_keywords: ["C2682"] helpviewer_keywords: ["C2682"] -ms.assetid: 30c6a7c4-f5f7-4fe8-81a8-c48938521ab4 --- # Compiler Error C2682 -cannot use casting_operator to convert from 'type1' to 'type2' +> cannot use casting_operator to convert from 'type1' to 'type2' + +## Remarks A casting operator tried to convert between incompatible types. For example, you cannot use the [dynamic_cast](../../cpp/dynamic-cast-operator.md) operator to convert a pointer to a reference. The **`dynamic_cast`** operator cannot be used to cast away qualifiers. All qualifiers on the types must match. You can use the **`const_cast`** operator to remove attributes such as **`const`**, **`volatile`**, or **`__unaligned`**. -The following sample generates C2682: +## Examples + +The following example generates C2682: ```cpp // C2682.cpp @@ -26,7 +29,7 @@ void g(A* pa) { } ``` -The following sample generates C2682: +The following example generates C2682: ```cpp // C2682b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2683.md b/docs/error-messages/compiler-errors-2/compiler-error-c2683.md index 27edb0c552f..a2b7b04276a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2683.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2683.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2683" title: "Compiler Error C2683" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2683" +ms.date: 11/04/2016 f1_keywords: ["C2683"] helpviewer_keywords: ["C2683"] -ms.assetid: db605e4f-601b-4d05-92a1-c43ca24de08d --- # Compiler Error C2683 -'cast' : 'type' is not a polymorphic type +> 'cast' : 'type' is not a polymorphic type + +## Remarks You cannot use [dynamic_cast](../../cpp/dynamic-cast-operator.md) to convert from a non-polymorphic class (a class with no virtual functions). You can use [static_cast](../../cpp/static-cast-operator.md) to perform conversions of non-polymorphic types. However, **`static_cast`** does not perform a run-time check. -The following sample generates C2683: +## Example + +The following example generates C2683: ```cpp // C2683.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2687.md b/docs/error-messages/compiler-errors-2/compiler-error-c2687.md index 9284b359bc2..d61bb9d910f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2687.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2687.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2687" title: "Compiler Error C2687" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2687" +ms.date: 11/04/2016 f1_keywords: ["C2687"] helpviewer_keywords: ["C2687"] -ms.assetid: 1d24b24a-cd0f-41cc-975c-b08dcfb7f402 --- # Compiler Error C2687 -'type' : exception-declaration cannot be 'void' or denote an incomplete type or pointer or reference to an incomplete type +> 'type' : exception-declaration cannot be 'void' or denote an incomplete type or pointer or reference to an incomplete type + +## Remarks For a type to be part of an exception declaration, it must be defined and not void. -The following sample generates C2687: +## Example + +The following example generates C2687: ```cpp // C2687.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2688.md b/docs/error-messages/compiler-errors-2/compiler-error-c2688.md index ddad95bbbfa..438291e9818 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2688.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2688.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2688" title: "Compiler Error C2688" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2688" +ms.date: 11/04/2016 f1_keywords: ["C2688"] helpviewer_keywords: ["C2688"] -ms.assetid: 168c9e9d-8f65-4664-af86-db71d3e6ee46 --- # Compiler Error C2688 -'C2::fgrv' : covariant returns with multiple or virtual inheritance not supported for varargs functions +> 'C2::fgrv' : covariant returns with multiple or virtual inheritance not supported for varargs functions + +## Remarks Covariant return types are not supported in Visual C++ when a function contains variable arguments. To resolve this error, either define your functions so that they do not use variable arguments or make the return values the same for all virtual functions. -The following sample generates C2688: +## Example + +The following example generates C2688: ```cpp // C2688.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2689.md b/docs/error-messages/compiler-errors-2/compiler-error-c2689.md index 82ab8e83b9d..0fb3674eb26 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2689.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2689.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2689" title: "Compiler Error C2689" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2689" +ms.date: 11/04/2016 f1_keywords: ["C2689"] helpviewer_keywords: ["C2689"] -ms.assetid: b5216fba-524d-4194-9168-26e9dc5210ce --- # Compiler Error C2689 -'function' : a friend function cannot be defined within a local class +> 'function' : a friend function cannot be defined within a local class + +## Remarks You can declare but not define a friend function in a local class. -The following sample generates C2689: +## Example + +The following example generates C2689: ```cpp // C2689.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2690.md b/docs/error-messages/compiler-errors-2/compiler-error-c2690.md index 8d9cf9f82a5..9885b8a0b12 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2690.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2690.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2690" title: "Compiler Error C2690" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2690" +ms.date: 11/04/2016 f1_keywords: ["C2690"] helpviewer_keywords: ["C2690"] -ms.assetid: f165a806-14bd-4942-99b7-8a9fc7dea227 --- # Compiler Error C2690 -'operator' : cannot perform pointer arithmetic on a managed or WinRT array +> 'operator' : cannot perform pointer arithmetic on a managed or WinRT array + +## Remarks Pointer arithmetic is not allowed on a managed or WinRT array. Use array index notation to traverse the array. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2691.md b/docs/error-messages/compiler-errors-2/compiler-error-c2691.md index 9a6d9a67d90..b2ff8c3044d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2691.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2691.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2691" title: "Compiler Error C2691" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2691" +ms.date: 11/04/2016 f1_keywords: ["C2691"] helpviewer_keywords: ["C2691"] -ms.assetid: 6925f8f3-ea60-4909-91e6-b781492c645d --- # Compiler Error C2691 -'data type' : a managed or WinRTarray cannot have this element type +> 'data type' : a managed or WinRTarray cannot have this element type + +## Remarks The type of a managed or WinRT array element can be a value type or a reference type. -The following sample generates C2691: +## Example + +The following example generates C2691: ```cpp // C2691a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2692.md b/docs/error-messages/compiler-errors-2/compiler-error-c2692.md index cfeedd4078c..a415df2551f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2692.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2692.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2692" title: "Compiler Error C2692" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2692" +ms.date: 11/04/2016 f1_keywords: ["C2692"] helpviewer_keywords: ["C2692"] -ms.assetid: 02ade3b4-b757-448b-b065-d7d71bc3f441 --- # Compiler Error C2692 -'function_name' : fully prototyped functions required in C compiler with the '/clr' option +> 'function_name' : fully prototyped functions required in C compiler with the '/clr' option + +## Remarks When compiling for .NET managed code, the C compiler requires ANSI function declarations. In addition, if a function takes no parameters, it must explicitly declare **`void`** as the parameter type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2693.md b/docs/error-messages/compiler-errors-2/compiler-error-c2693.md index d26adbe71c5..3cbf3814c91 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2693.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2693.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2693" title: "Compiler Error C2693" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2693" +ms.date: 11/04/2016 f1_keywords: ["C2693"] helpviewer_keywords: ["C2693"] -ms.assetid: b7364ca8-b6be-48c0-97d6-6029787fb171 --- # Compiler Error C2693 -'operator' : illegal comparison for references to a managed or WinRT array +> 'operator' : illegal comparison for references to a managed or WinRT array + +## Remarks You cannot test a managed or WinRT array for any kind of inequality. For example, you can test to see if managed arrays are equal but you cannot test to see if one array is greater or less than another array. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2694.md b/docs/error-messages/compiler-errors-2/compiler-error-c2694.md index c093639deba..3b33248c161 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2694.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2694.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2694" title: "Compiler Error C2694" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2694" +ms.date: 11/04/2016 f1_keywords: ["C2694"] helpviewer_keywords: ["C2694"] -ms.assetid: 8dc2cec2-67ae-4e16-8c0c-374425aca8bc --- # Compiler Error C2694 -'override': overriding virtual function has less restrictive exception specification than base class virtual member function 'base' +> 'override': overriding virtual function has less restrictive exception specification than base class virtual member function 'base' + +## Remarks A virtual function was overridden, but under [/Za](../../build/reference/za-ze-disable-language-extensions.md), the overriding function had a less restrictive [exception specification](../../cpp/exception-specifications-throw-cpp.md). -The following sample generates C2694: +## Example + +The following example generates C2694: ```cpp // C2694.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2695.md b/docs/error-messages/compiler-errors-2/compiler-error-c2695.md index 5b24ca30b5d..4e2b58d9815 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2695.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2695.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2695" title: "Compiler Error C2695" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2695" +ms.date: 11/04/2016 f1_keywords: ["C2695"] helpviewer_keywords: ["C2695"] -ms.assetid: 3f6f2091-c38b-40ea-ab6c-f1846f5702d7 --- # Compiler Error C2695 -'function1': overriding virtual function differs from 'function2' only by calling convention +> 'function1': overriding virtual function differs from 'function2' only by calling convention + +## Remarks The signature of a function in a derived class cannot override a function in a base class and change the calling convention. -The following sample generates C2695: +## Example + +The following example generates C2695: ```cpp // C2695.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2696.md b/docs/error-messages/compiler-errors-2/compiler-error-c2696.md index 4939dc99786..27d130d222b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2696.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2696.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2696" title: "Compiler Error C2696" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2696" +ms.date: 11/04/2016 f1_keywords: ["C2696"] helpviewer_keywords: ["C2696"] -ms.assetid: 6c6eb7df-1230-4346-9a73-abf14c20785d --- # Compiler Error C2696 -Cannot create a temporary object of a managed type 'type' +> Cannot create a temporary object of a managed type 'type' + +## Remarks References to **`const`** in an unmanaged program cause the compiler to call the constructor and create a temporary object on the stack. However, a managed class can never be created on the stack. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2698.md b/docs/error-messages/compiler-errors-2/compiler-error-c2698.md index efdb26599fb..dbc7eef8618 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2698.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2698.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2698" title: "Compiler Error C2698" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2698" +ms.date: 11/04/2016 f1_keywords: ["C2698"] helpviewer_keywords: ["C2698"] -ms.assetid: 3ebfe395-c20b-4c56-9980-ca9ed8653382 --- # Compiler Error C2698 -the using-declaration for 'declaration 1' cannot co-exist with the existing using-declaration for 'declaration 2' +> the using-declaration for 'declaration 1' cannot co-exist with the existing using-declaration for 'declaration 2' + +## Remarks Once you have a [using declaration](../../cpp/using-declaration.md) for a data member, any using declaration in the same scope that uses the same name is not permitted, as only functions can be overloaded. -The following sample generates C2698: +## Example + +The following example generates C2698: ```cpp // C2698.cpp @@ -27,5 +30,5 @@ struct B { struct C : A, B { using A::x; using B::x; // C2698 -} +}; ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2700.md b/docs/error-messages/compiler-errors-2/compiler-error-c2700.md index d843b7d0d84..9032db07969 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2700.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2700.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2700" title: "Compiler Error C2700" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2700" +ms.date: 11/04/2016 f1_keywords: ["C2700"] helpviewer_keywords: ["C2700"] -ms.assetid: a231eb86-bdae-4b37-a606-06854f47929f --- # Compiler Error C2700 -'identifier' : cannot be thrown (use /W4 for more info) +> 'identifier' : cannot be thrown (use /W4 for more info) + +## Remarks The object cannot be thrown. Compile with [/W4](../../build/reference/compiler-option-warning-level.md) for more diagnostic information. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2701.md b/docs/error-messages/compiler-errors-2/compiler-error-c2701.md index ba58effeea4..6d038a0270c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2701.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2701.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2701" title: "Compiler Error C2701" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2701" +ms.date: 09/27/2022 f1_keywords: ["C2701"] helpviewer_keywords: ["C2701"] -ms.assetid: 31cf2ab7-ced9-4f75-aa51-e169e20407fb --- # Compiler Error C2701 -'function' : a function template cannot be a friend of a local class +> 'function': a function template cannot be a `friend` of a local class + +## Remarks + +A local class can't have a function template as a `friend` function. -A local class cannot have a template function as a friend function. +## Example -The following sample generates C2701: +The following example generates C2701: ```cpp // C2701.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2702.md b/docs/error-messages/compiler-errors-2/compiler-error-c2702.md index 8ab3ce78de1..d552a512152 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2702.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2702.md @@ -4,15 +4,18 @@ description: "Describes Microsoft C/C++ compiler error C2702." ms.date: 08/25/2020 f1_keywords: ["C2702"] helpviewer_keywords: ["C2702"] -ms.assetid: 6def15d4-9a8d-43e7-ae35-42d7cb57c27e --- # Compiler Error C2702 > `__except` may not appear in termination block +## Remarks + An exception handler (**`__try`**/**`__except`**) cannot be nested inside a **`__finally`** block. -The following sample generates C2702: +## Example + +The following example generates C2702: ```cpp // C2702.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2703.md b/docs/error-messages/compiler-errors-2/compiler-error-c2703.md index 113bf49c705..87adbc90511 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2703.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2703.md @@ -4,7 +4,6 @@ description: "Describes Microsoft C/C++ compiler error C2703." ms.date: 08/24/2020 f1_keywords: ["C2703"] helpviewer_keywords: ["C2703"] -ms.assetid: 384295c3-643d-47ae-a9a6-865b3036aa84 --- # Compiler Error C2703 @@ -16,7 +15,7 @@ A **`__leave`** statement must be inside a **`__try`** block. ## Example -The following sample generates C2703: +The following example generates C2703: ```cpp // C2703.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2704.md b/docs/error-messages/compiler-errors-2/compiler-error-c2704.md index 476dd462288..4d231d20a99 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2704.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2704.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2704" title: "Compiler Error C2704" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2704" +ms.date: 11/04/2016 f1_keywords: ["C2704"] helpviewer_keywords: ["C2704"] -ms.assetid: 185797e2-55b5-4c11-8493-e70eb1d15a94 --- # Compiler Error C2704 -'identifier' : __va_start intrinsic only allowed in varargs +> 'identifier' : __va_start intrinsic only allowed in varargs + +## Remarks The `__va_start` intrinsic is used in a declaration for a function with a fixed number of arguments. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2705.md b/docs/error-messages/compiler-errors-2/compiler-error-c2705.md index 39fdf0029a3..d080e7a213e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2705.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2705.md @@ -4,7 +4,6 @@ description: "Describes Microsoft C/C++ compiler error C2705." ms.date: 08/25/2020 f1_keywords: ["C2705"] helpviewer_keywords: ["C2705"] -ms.assetid: 29249ea3-4ea7-4105-944b-bdb83e8d6852 --- # Compiler Error C2705 @@ -16,7 +15,7 @@ Execution jumps to a label within a **`try`**/**`catch`**, **`__try`**/**`__exce ## Example -The following sample generates C2705: +The following example generates C2705: ```cpp // C2705.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2706.md b/docs/error-messages/compiler-errors-2/compiler-error-c2706.md index c21375885ed..0490d7807ca 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2706.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2706.md @@ -4,15 +4,18 @@ description: "Describes Microsoft C/C++ compiler error C2706." ms.date: 08/25/2020 f1_keywords: ["C2706"] helpviewer_keywords: ["C2706"] -ms.assetid: e18da924-c42d-4b09-8e29-f4e0382d7dc6 --- # Compiler Error C2706 > illegal `__except` without matching `__try` (missing '}' in `__try` block?) +## Remarks + The compiler did not find a closing brace for a **`__try`** block. -The following sample generates C2706: +## Example + +The following example generates C2706: ```cpp // C2706.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2707.md b/docs/error-messages/compiler-errors-2/compiler-error-c2707.md index ff081cdf341..3bfc8a90ae7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2707.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2707.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2707" title: "Compiler Error C2707" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2707" +ms.date: 11/04/2016 f1_keywords: ["C2707"] helpviewer_keywords: ["C2707"] -ms.assetid: 3deaf45c-74da-4c9d-acc6-b82412720b74 --- # Compiler Error C2707 -'identifier' : bad context for intrinsic function +> 'identifier' : bad context for intrinsic function + +## Remarks Structured exception-handling intrinsics are invalid in certain contexts: @@ -22,7 +23,7 @@ To resolve the error, be sure that the exception-handling intrinsics are placed ## Example -The following sample generates C2707. +The following example generates C2707. ```cpp // C2707.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2708.md b/docs/error-messages/compiler-errors-2/compiler-error-c2708.md index 72031e762ad..a8b2f3d6500 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2708.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2708.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2708" title: "Compiler Error C2708" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2708" +ms.date: 11/04/2016 f1_keywords: ["C2708"] helpviewer_keywords: ["C2708"] -ms.assetid: d52d3088-1141-42f4-829c-74755a7fcc3a --- # Compiler Error C2708 -'identifier' : actual parameters length in bytes differs from previous call or reference +> 'identifier' : actual parameters length in bytes differs from previous call or reference + +## Remarks A [__stdcall](../../cpp/stdcall.md) function must be preceded by a prototype. Otherwise, the compiler interprets the first call to the function as a prototype and this error occurs when the compiler encounters a call that does not match. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2709.md b/docs/error-messages/compiler-errors-2/compiler-error-c2709.md index 8412aaff029..36a2376616d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2709.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2709.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2709" title: "Compiler Error C2709" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2709" +ms.date: 11/04/2016 f1_keywords: ["C2709"] helpviewer_keywords: ["C2709"] -ms.assetid: e66fc7e6-0e91-4b99-a6e0-fdb069b09fbc --- # Compiler Error C2709 -'identifier' : formal parameter's length in bytes differs from previous declaration +> 'identifier' : formal parameter's length in bytes differs from previous declaration + +## Remarks The signature in a call to the specified function differs from the prototype. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2710.md b/docs/error-messages/compiler-errors-2/compiler-error-c2710.md index 5b2ddea8617..3019c67c1ca 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2710.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2710.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2710" title: "Compiler Error C2710" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2710" +ms.date: 11/04/2016 f1_keywords: ["C2710"] helpviewer_keywords: ["C2710"] -ms.assetid: a2a6bb5b-86ad-4a6c-acd0-e2bef8464e0e --- # Compiler Error C2710 -'construct' : '__declspec(modifier)' can only be applied to a function returning a pointer +> 'construct' : '__declspec(modifier)' can only be applied to a function returning a pointer + +## Remarks A function whose return value is a pointer is the only construct to which `modifier` can be applied. -The following sample generates C2710: +## Example + +The following example generates C2710: ```cpp // C2710.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2711.md b/docs/error-messages/compiler-errors-2/compiler-error-c2711.md index 137e67e9338..a0b44f38278 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2711.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2711.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2711" title: "Compiler Error C2711" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2711" +ms.date: 11/04/2016 f1_keywords: ["C2711"] helpviewer_keywords: ["C2711"] -ms.assetid: 9df9f808-7419-4e63-abdd-e6538ff0871f --- # Compiler Error C2711 -'function' : this function cannot be compiled as managed, consider using #pragma unmanaged +> 'function' : this function cannot be compiled as managed, consider using #pragma unmanaged + +## Remarks Some instructions will prevent the compiler from generating MSIL for the enclosing function. -The following sample generates C2711: +## Example + +The following example generates C2711: ```cpp // C2711.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2712.md b/docs/error-messages/compiler-errors-2/compiler-error-c2712.md index 8b1b715cb00..b1caf1ca2da 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2712.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2712.md @@ -4,7 +4,6 @@ description: "Describes Microsoft C/C++ compiler error C2712." ms.date: 08/25/2020 f1_keywords: ["C2712"] helpviewer_keywords: ["C2712"] -ms.assetid: f7d4ffcc-7ed2-459b-8067-a728ce647071 --- # Compiler Error C2712 @@ -30,7 +29,7 @@ The **`/clr:pure`** and **`/clr:safe`** compiler options are deprecated in Visua ## Example -The following sample generates C2712 and shows how to fix it. +The following example generates C2712 and shows how to fix it. ```cpp // C2712.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2713.md b/docs/error-messages/compiler-errors-2/compiler-error-c2713.md index 59ee0bf0a9e..65eeed13bdc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2713.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2713.md @@ -4,10 +4,11 @@ description: "Describes Microsoft C/C++ compiler error C2713." ms.date: 08/25/2020 f1_keywords: ["C2713"] helpviewer_keywords: ["C2713"] -ms.assetid: bae9bee3-b4b8-4be5-b6a5-02df587a7278 --- # Compiler Error C2713 > only one form of exception handling permitted per function +## Remarks + You can't use structured exception handling (**`__try`**/**`__except`**) and C++ exception handling (**`try`**/**`catch`**) in the same function. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2714.md b/docs/error-messages/compiler-errors-2/compiler-error-c2714.md index 95d86859dc7..c876015451b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2714.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2714.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: Compiler Error C2714" title: "Compiler Error C2714" +description: "Learn more about: Compiler Error C2714" ms.date: 07/22/2020 f1_keywords: ["C2714"] helpviewer_keywords: ["C2714"] -ms.assetid: 401a5a42-660c-4bad-9d63-1a2d092bc489 --- # Compiler Error C2714 > `alignof(void)` is not allowed -An invalid value was passed to an operator. - ## Remarks +An invalid value was passed to an operator. + See [`alignof` operator](../../cpp/alignof-operator.md) for more information. ## Example -The following sample generates C2714. +The following example generates C2714. ```cpp // C2714.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2715.md b/docs/error-messages/compiler-errors-2/compiler-error-c2715.md index 1321f85ca92..ddb31bc681b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2715.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2715.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: Compiler Error C2715" title: "Compiler Error C2715" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2715" +ms.date: 11/04/2016 f1_keywords: ["C2715"] helpviewer_keywords: ["C2715"] -ms.assetid: c81567a7-5b65-468f-aaf9-835f91e468e4 --- # Compiler Error C2715 -'type' : cannot throw or catch this type +> 'type' : cannot throw or catch this type + +## Remarks Value types are not valid arguments when using exception handling in managed code (see [Exception Handling](../../extensions/exception-handling-cpp-component-extensions.md) for more information). +## Example + +The following example generates C2715 and shows how to fix it: + ```cpp // C2715a.cpp // compile with: /clr diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2718.md b/docs/error-messages/compiler-errors-2/compiler-error-c2718.md index 6b67c1f9331..180afef6eac 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2718.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2718.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2718" title: "Compiler Error C2718" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2718" +ms.date: 11/04/2016 f1_keywords: ["C2718"] helpviewer_keywords: ["C2718"] -ms.assetid: 78cc71f8-c142-46fc-9aed-970635d74f0c --- # Compiler Error C2718 -'parameter': actual parameter with __declspec(align('#')) won't be aligned +> 'parameter': actual parameter with __declspec(align('#')) won't be aligned + +## Remarks The [align](../../cpp/align-cpp.md) **`__declspec`** modifier is not permitted on function parameters. -The following sample generates C2718: +## Example + +The following example generates C2718: ```cpp // C2718.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2719.md b/docs/error-messages/compiler-errors-2/compiler-error-c2719.md index 3b367a25ba2..6df11d9414e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2719.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2719.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2719" title: "Compiler Error C2719" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2719" +ms.date: 11/04/2016 f1_keywords: ["C2719"] helpviewer_keywords: ["C2719"] -ms.assetid: ea6236d3-8286-45cc-9478-c84ad3dd3c8e --- # Compiler Error C2719 -'parameter': formal parameter with __declspec(align('#')) won't be aligned +> 'parameter': formal parameter with __declspec(align('#')) won't be aligned + +## Remarks The [align](../../cpp/align-cpp.md) **`__declspec`** modifier is not permitted on function parameters. Function parameter alignment is controlled by the calling convention used. For more information, see [Calling Conventions](../../cpp/calling-conventions.md). -The following sample generates C2719 and shows how to fix it: +## Example + +The following example generates C2719 and shows how to fix it: ```cpp // C2719.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2720.md b/docs/error-messages/compiler-errors-2/compiler-error-c2720.md index 40b1afaa4e3..66fd999f7a3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2720.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2720.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2720" title: "Compiler Error C2720" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2720" +ms.date: 11/04/2016 f1_keywords: ["C2720"] helpviewer_keywords: ["C2720"] -ms.assetid: 9ee3aab7-711b-4f5a-b2f1-cb62b130f1ce --- # Compiler Error C2720 > '*identifier*' : '*specifier*' storage-class specifier illegal on members +## Remarks + The storage class cannot be used on class members outside the declaration. To fix this error, remove the unneeded [storage class](../../cpp/storage-classes-cpp.md) specifier from the definition of the member outside the class declaration. ## Example -The following sample generates C2720 and shows how to fix it: +The following example generates C2720 and shows how to fix it: ```cpp // C2720.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2721.md b/docs/error-messages/compiler-errors-2/compiler-error-c2721.md index 0bafc693b29..2bfd272ae2c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2721.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2721.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2721" title: "Compiler Error C2721" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2721" +ms.date: 11/04/2016 f1_keywords: ["C2721"] helpviewer_keywords: ["C2721"] -ms.assetid: 7a97823c-3ce1-4112-8253-fc1448685235 --- # Compiler Error C2721 -'specifier' : storage-class specifier illegal between operator keyword and type +> 'specifier' : storage-class specifier illegal between operator keyword and type + +## Remarks User-defined type conversions apply to all storage classes, so you cannot specify a storage class in a type conversion. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2722.md b/docs/error-messages/compiler-errors-2/compiler-error-c2722.md index 0240cca6d41..892e345c5cc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2722.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2722.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2722" title: "Compiler Error C2722" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2722" +ms.date: 11/04/2016 f1_keywords: ["C2722"] helpviewer_keywords: ["C2722"] -ms.assetid: 4cc2c7fa-cb12-4bcf-9df1-6d627ef62973 --- # Compiler Error C2722 -'::operator' : illegal following operator command; use 'operator operator' +> '::operator' : illegal following operator command; use 'operator operator' + +## Remarks An `operator` statement redefines `::new` or `::delete`. The `new` and `delete` operators are global, so the scope resolution operator (`::`) is meaningless. Remove the `::` operator. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2723.md b/docs/error-messages/compiler-errors-2/compiler-error-c2723.md index 48dad9d850c..b878410fa11 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2723.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2723.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2723" title: "Compiler Error C2723" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2723" +ms.date: 11/04/2016 f1_keywords: ["C2723"] helpviewer_keywords: ["C2723"] -ms.assetid: 86925601-2297-4cfd-94e2-2caf27c474c4 --- # Compiler Error C2723 -'function' : 'specifier' specifier illegal on function definition +> 'function' : 'specifier' specifier illegal on function definition + +## Remarks The specifier cannot appear with a function definition outside of a class declaration. The **`virtual`** specifier can be specified only on a member function declaration within a class declaration. -The following sample generates C2723 and shows how to fix it: +## Example + +The following example generates C2723 and shows how to fix it: ```cpp // C2723.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2724.md b/docs/error-messages/compiler-errors-2/compiler-error-c2724.md index 534107c5007..21e3b41693d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2724.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2724.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2724" title: "Compiler Error C2724" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2724" +ms.date: 11/04/2016 f1_keywords: ["C2724"] helpviewer_keywords: ["C2724"] -ms.assetid: 4e4664bc-8c96-4156-b79f-03436f532ea8 --- # Compiler Error C2724 -'identifier' : 'static' should not be used on member functions defined at file scope +> 'identifier' : 'static' should not be used on member functions defined at file scope + +## Remarks Static member functions should be declared with external linkage. -The following sample generates C2724: +## Example + +The following example generates C2724: ```cpp // C2724.cpp @@ -20,7 +23,7 @@ class C { static void func(); }; -static void C::func(){}; // C2724 +static void C::func(){} // C2724 // try the following line instead -// void C::func(){}; +// void C::func(){} ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2725.md b/docs/error-messages/compiler-errors-2/compiler-error-c2725.md index b362cad13e2..ef72d45e281 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2725.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2725.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2725" title: "Compiler Error C2725" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2725" +ms.date: 11/04/2016 f1_keywords: ["C2725"] helpviewer_keywords: ["C2725"] -ms.assetid: 13cd5b1b-e906-4cd8-9b2b-510d587c665a --- # Compiler Error C2725 -'exception' : unable to throw or catch a managed or WinRT object by value or reference +> 'exception' : unable to throw or catch a managed or WinRT object by value or reference + +## Remarks The type of a managed or WinRT exception was not correct. ## Examples -The following sample generates C2725 and shows how to fix it. +The following example generates C2725 and shows how to fix it. ```cpp // C2725.cpp @@ -33,7 +34,7 @@ int main() { } ``` -The following sample generates C2725 and shows how to fix it. +The following example generates C2725 and shows how to fix it. ```cpp // C2725b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2726.md b/docs/error-messages/compiler-errors-2/compiler-error-c2726.md index 1cf7c3f939c..22aa1b52408 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2726.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2726.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2726" title: "Compiler Error C2726" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2726" +ms.date: 11/04/2016 f1_keywords: ["C2726"] helpviewer_keywords: ["C2726"] -ms.assetid: f0191bb7-c175-450b-bf09-a3213db96d09 --- # Compiler Error C2726 -'gcnew' may only be used to create an object with managed or WinRT type +> 'gcnew' may only be used to create an object with managed or WinRT type + +## Remarks You cannot create an instance of a native type on the garbage-collected heap. -The following sample generates C2726 and shows how to fix it: +## Example + +The following example generates C2726 and shows how to fix it: ```cpp // C2726.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2728.md b/docs/error-messages/compiler-errors-2/compiler-error-c2728.md index 79660264d06..8300ece3561 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2728.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2728.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2728" title: "Compiler Error C2728" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2728" +ms.date: 11/04/2016 f1_keywords: ["C2728"] helpviewer_keywords: ["C2728"] -ms.assetid: 65635f91-1cd1-46e4-9ad7-14726d0546af --- # Compiler Error C2728 -'type' : a native array cannot contain this type +> 'type' : a native array cannot contain this type + +## Remarks Array creation syntax was used to create an array of managed or WinRT objects. You cannot create an array of managed or WinRT objects using native array syntax. For more information, see [array](../../extensions/arrays-cpp-component-extensions.md). -The following sample generates C2728 and shows how to fix it: +## Example + +The following example generates C2728 and shows how to fix it: ```cpp // C2728.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2730.md b/docs/error-messages/compiler-errors-2/compiler-error-c2730.md index b7a014e42cd..f06cf3b7fed 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2730.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2730.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2730" title: "Compiler Error C2730" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2730" +ms.date: 11/04/2016 f1_keywords: ["C2730"] helpviewer_keywords: ["C2730"] -ms.assetid: 07f0b17a-bc8e-4d79-af5a-07a07af3687b --- # Compiler Error C2730 -'class' : cannot be a base class of itself +> 'class' : cannot be a base class of itself + +## Remarks Recursive base classes are invalid. Specify another class as the base class. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2731.md b/docs/error-messages/compiler-errors-2/compiler-error-c2731.md index 3140f55a23e..beb16353908 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2731.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2731.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2731" title: "Compiler Error C2731" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2731" +ms.date: 11/04/2016 f1_keywords: ["C2731"] helpviewer_keywords: ["C2731"] -ms.assetid: 9b563999-febd-4582-9147-f355083c091e --- # Compiler Error C2731 -'identifier' : function cannot be overloaded +> 'identifier' : function cannot be overloaded + +## Remarks The functions `main`, `WinMain`, `DllMain`, and `LibMain` cannot be overloaded. -The following sample generates C2731: +## Example + +The following example generates C2731: ```cpp // C2731.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2732.md b/docs/error-messages/compiler-errors-2/compiler-error-c2732.md index a8c934d69a8..6984e65b413 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2732.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2732.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2732" title: "Compiler Error C2732" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2732" +ms.date: 11/04/2016 f1_keywords: ["C2732"] helpviewer_keywords: ["C2732"] -ms.assetid: 01b7ad2c-93cf-456f-a4c0-c5f2fdc7c07c --- # Compiler Error C2732 -linkage specification contradicts earlier specification for 'function' +> linkage specification contradicts earlier specification for 'function' + +## Remarks The function is already declared with a different linkage specifier. @@ -18,7 +19,7 @@ To fix this error, change the **`extern`** statements so that the linkages agree ## Example -The following sample generates C2732: +The following example generates C2732: ```cpp // C2732.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2733.md b/docs/error-messages/compiler-errors-2/compiler-error-c2733.md index 03a7ae6bf2f..ba6d27d4753 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2733.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2733.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C2733" title: "Compiler Error C2733" +description: "Learn more about: Compiler Error C2733" ms.date: 12/02/2021 f1_keywords: ["C2733"] helpviewer_keywords: ["C2733"] -ms.assetid: 67f83561-c633-407c-a2ee-f9fd16e165bf --- # Compiler Error C2733 > you cannot overload a function with 'C' linkage +## Remarks + More than one overloaded function is declared with `extern "C"` linkage. When using `"C"` linkage, only one form of a specified function can be external. Since overloaded functions have the same undecorated name, they can't be used with C programs. This error may occur after an upgrade because of conformance changes in Visual Studio 2019. Starting in Visual Studio 2019 version 16.3, the [`/Zc:externC-`](../../build/reference/zc-externc.md) compiler option relaxes this check. The option must come after any [`/permissive-`](../../build/reference/permissive-standards-conformance.md) option on the command line. ## Example -The following sample generates C2733: +The following example generates C2733: ```cpp // C2733.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2734.md b/docs/error-messages/compiler-errors-2/compiler-error-c2734.md index 926b55a676b..c11247bd758 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2734.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2734.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2734" title: "Compiler Error C2734" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2734" +ms.date: 11/04/2016 f1_keywords: ["C2734"] helpviewer_keywords: ["C2734"] -ms.assetid: e53a77b7-825c-42d1-a655-90e1c93b833e --- # Compiler Error C2734 -'identifier' : const object must be initialized if not extern +> 'identifier' : const object must be initialized if not extern + +## Remarks The identifier is declared **`const`** but not initialized or **`extern`**. -The following sample generates C2734: +## Example + +The following example generates C2734: ```cpp // C2734.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2735.md b/docs/error-messages/compiler-errors-2/compiler-error-c2735.md index c3549dc46d5..8f363b12b84 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2735.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2735.md @@ -1,20 +1,25 @@ --- -description: "Learn more about: Compiler Error C2735" title: "Compiler Error C2735" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2735" +ms.date: 09/12/2025 f1_keywords: ["C2735"] helpviewer_keywords: ["C2735"] -ms.assetid: 6ce45600-7148-4bc0-8699-af0ef137571e --- # Compiler Error C2735 -'keyword' keyword is not permitted in formal parameter type specifier +> '*keyword*' keyword is not permitted in formal parameter type specifier + +## Remarks The keyword is invalid in this context. -The following sample generates C2735: +## Example + +The following example generates C2735: ```cpp // C2735.cpp -void f(inline int){} // C2735 +// compile with: /c + +void func(virtual int) {} // C2735 ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2736.md b/docs/error-messages/compiler-errors-2/compiler-error-c2736.md index b0135806686..a17c5de2ad8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2736.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2736.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2736" title: "Compiler Error C2736" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2736" +ms.date: 11/04/2016 f1_keywords: ["C2736"] helpviewer_keywords: ["C2736"] -ms.assetid: 95a6bc28-c0cb-49dc-87e6-e993dbbba881 --- # Compiler Error C2736 -'keyword' keyword is not permitted in cast +> 'keyword' keyword is not permitted in cast + +## Remarks The keyword is invalid in a cast. -The following sample generates C2736: +## Example + +The following example generates C2736: ```cpp // C2736.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2738.md b/docs/error-messages/compiler-errors-2/compiler-error-c2738.md index b640ef4a018..4eeec6e77a0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2738.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2738.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2738" title: "Compiler Error C2738" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2738" +ms.date: 11/04/2016 f1_keywords: ["C2738"] helpviewer_keywords: ["C2738"] -ms.assetid: 896b4640-1ee0-4cd8-9910-de3efa30006a --- # Compiler Error C2738 -'declaration' : is ambiguous or is not a member of 'type' +> 'declaration' : is ambiguous or is not a member of 'type' + +## Remarks A function was declared incorrectly. -The following sample generates C2738: +## Example + +The following example generates C2738: ```cpp // C2738.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2739.md b/docs/error-messages/compiler-errors-2/compiler-error-c2739.md index 15c3f8b0ea8..3125f5102bb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2739.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2739.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2739" title: "Compiler Error C2739" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2739" +ms.date: 11/04/2016 f1_keywords: ["C2739"] helpviewer_keywords: ["C2739"] -ms.assetid: 5b63e435-7631-43d7-805e-f2adefb7e517 --- # Compiler Error C2739 -'number' : explicit managed or WinRT array dimensions must be between 1 and 32 +> 'number' : explicit managed or WinRT array dimensions must be between 1 and 32 + +## Remarks An array dimension was not between 1 and 32. -The following sample generates C2739 and shows how to fix it: +## Example + +The following example generates C2739 and shows how to fix it: ```cpp // C2739.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2743.md b/docs/error-messages/compiler-errors-2/compiler-error-c2743.md index 82d0b04f293..0f2118ff291 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2743.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2743.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2743" title: "Compiler Error C2743" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2743" +ms.date: 11/04/2016 f1_keywords: ["C2743"] helpviewer_keywords: ["C2743"] -ms.assetid: 644cd444-21d2-471d-a176-f5f52c5a0b73 --- # Compiler Error C2743 -'type' : cannot catch a native type with __clrcall destructor or copy constructor +> 'type' : cannot catch a native type with __clrcall destructor or copy constructor + +## Remarks A module compiled with **/clr** attempted to catch an exception of native type and where the type's destructor or copy constructor uses `__clrcall` calling convention. @@ -18,7 +19,7 @@ For more information, see [/clr (Common Language Runtime Compilation)](../../bui ## Example -The following sample generates C2743. +The following example generates C2743. ```cpp // C2743.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2745.md b/docs/error-messages/compiler-errors-2/compiler-error-c2745.md index efa92f63c9e..4fbbf13bcce 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2745.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2745.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2745" title: "Compiler Error C2745" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2745" +ms.date: 11/04/2016 f1_keywords: ["C2745"] helpviewer_keywords: ["C2745"] -ms.assetid: a1c45f13-7667-4678-aa16-265304a449a1 --- # Compiler Error C2745 -'token' : this token cannot be converted to an identifier +> 'token' : this token cannot be converted to an identifier + +## Remarks Identifiers must be comprised of legal characters. -The following sample generates C2745: +## Example + +The following example generates C2745: ```cpp // C2745.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2748.md b/docs/error-messages/compiler-errors-2/compiler-error-c2748.md index df420793898..c7a99b67943 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2748.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2748.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2748" title: "Compiler Error C2748" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2748" +ms.date: 11/04/2016 f1_keywords: ["C2748"] helpviewer_keywords: ["C2748"] -ms.assetid: b63ac78b-a200-499c-afea-15af1a1e819e --- # Compiler Error C2748 -managed or WinRT array creation must have array size or array initializer +> managed or WinRT array creation must have array size or array initializer + +## Remarks A managed or WinRT array was ill formed. For more information, see [array](../../extensions/arrays-cpp-component-extensions.md). -The following sample generates C2748 and shows how to fix it: +## Example + +The following example generates C2748 and shows how to fix it: ```cpp // C2748.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2749.md b/docs/error-messages/compiler-errors-2/compiler-error-c2749.md index 293ce1aaab8..c2bc309d835 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2749.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2749.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2749" title: "Compiler Error C2749" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2749" +ms.date: 11/04/2016 f1_keywords: ["C2749"] helpviewer_keywords: ["C2749"] -ms.assetid: a81aef36-cdca-4d78-89d5-b72eff2500b2 --- # Compiler Error C2749 -'type' : can only throw or catch handle to a managed class with /clr:safe +> 'type' : can only throw or catch handle to a managed class with /clr:safe + +## Remarks When using **/clr:safe**, you can only throw or catch a reference type. @@ -16,7 +17,7 @@ For more information, see [/clr (Common Language Runtime Compilation)](../../bui ## Example -The following sample generates C2749: +The following example generates C2749: ```cpp // C2749.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2750.md b/docs/error-messages/compiler-errors-2/compiler-error-c2750.md index f38c917907c..55899400da8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2750.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2750.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2750" title: "Compiler Error C2750" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2750" +ms.date: 11/04/2016 f1_keywords: ["C2750"] helpviewer_keywords: ["C2750"] -ms.assetid: 30450034-feb5-448c-9655-b8c5f3639695 --- # Compiler Error C2750 -'type' : cannot use 'new' on the reference type; use 'gcnew' instead +> 'type' : cannot use 'new' on the reference type; use 'gcnew' instead + +## Remarks To create an instance of a CLR type, which causes the instance to be placed on the garbage-collected heap, you must use [gcnew](../../extensions/ref-new-gcnew-cpp-component-extensions.md). -The following sample generates C2750: +## Example + +The following example generates C2750: ```cpp // C2750.cpp 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 c2d5e50061c..ef7c77075c1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2751.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2751.md @@ -1,26 +1,29 @@ --- -description: "Learn more about: Compiler Error C2751" title: "Compiler Error C2751" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2751" +ms.date: 03/11/2024 f1_keywords: ["C2751"] helpviewer_keywords: ["C2751"] -ms.assetid: 44a3abdf-8a87-4a09-b34b-532c220c310a --- # Compiler Error C2751 -'parameter' : the name of a function parameter cannot be qualified +> 'parameter' : the name of a function parameter cannot be qualified + +## Remarks You cannot use a qualified name as a function parameter. -The following sample generates C2751: +## Example + +The following example 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-c2752.md b/docs/error-messages/compiler-errors-2/compiler-error-c2752.md index 62770f96025..5c0d2337ce2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2752.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2752.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2752" title: "Compiler Error C2752" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2752" +ms.date: 11/04/2016 f1_keywords: ["C2752"] helpviewer_keywords: ["C2752"] -ms.assetid: ae42b3ec-84a9-4e9d-8d59-3d208132d0b2 --- # Compiler Error C2752 -'template' : more than one partial specialization matches the template argument list +> 'template' : more than one partial specialization matches the template argument list + +## Remarks An instantiation was ambiguous. -The following sample generates C2752: +## Example + +The following example generates C2752: ```cpp // C2752.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2753.md b/docs/error-messages/compiler-errors-2/compiler-error-c2753.md index ba0897b0d1e..9f68e282613 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2753.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2753.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2753" title: "Compiler Error C2753" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2753" +ms.date: 11/04/2016 f1_keywords: ["C2753"] helpviewer_keywords: ["C2753"] -ms.assetid: 92bfeeac-524a-4a8e-9a4f-fb8269055826 --- # Compiler Error C2753 -'*template*' : partial specialization cannot match argument list for primary template +> '*template*' : partial specialization cannot match argument list for primary template + +## Remarks If the template argument list matches the parameter list, the compiler treats it as the same template. Defining the same template twice is not allowed. ## Example -The following sample generates C2753 and shows a way to fix it: +The following example generates C2753 and shows a way to fix it: ```cpp // C2753.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2754.md b/docs/error-messages/compiler-errors-2/compiler-error-c2754.md index fafd439fa48..8b391baaa37 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2754.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2754.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2754" title: "Compiler Error C2754" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2754" +ms.date: 11/04/2016 f1_keywords: ["C2754"] helpviewer_keywords: ["C2754"] -ms.assetid: 1cab66c5-da9d-4b81-b7fb-9cdc48ff1ccc --- # Compiler Error C2754 -'specialization' : a partial specialization cannot have a dependent non-type template parameter +> 'specialization' : a partial specialization cannot have a dependent non-type template parameter + +## Remarks An attempt was made to partially specialize a template class that has a dependent non-type template parameter. This is not allowed. -The following sample generates C2754: +## Example + +The following example generates C2754: ```cpp // C2754.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2755.md b/docs/error-messages/compiler-errors-2/compiler-error-c2755.md index 99a5290a5fd..adabdd70a83 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2755.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2755.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2755" title: "Compiler Error C2755" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2755" +ms.date: 11/04/2016 f1_keywords: ["C2755"] helpviewer_keywords: ["C2755"] -ms.assetid: 8ee4eeb6-4757-4efe-9100-38ff4a96f1de --- # Compiler Error C2755 -'param' : non-type parameter of a partial specialization must be a simple identifier +> 'param' : non-type parameter of a partial specialization must be a simple identifier + +## Remarks The non-type parameter needs to be a simple identifier, something the compiler can resolve at compile time to a single identifier or a constant value. -The following sample generates C2755: +## Example + +The following example generates C2755: ```cpp // C2755.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2756.md b/docs/error-messages/compiler-errors-2/compiler-error-c2756.md index 429fa87ea10..5f7089c2367 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2756.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2756.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2756" title: "Compiler Error C2756" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2756" +ms.date: 11/04/2016 f1_keywords: ["C2756"] helpviewer_keywords: ["C2756"] -ms.assetid: 42eb988d-4043-4dee-8fd4-596949f69a55 --- # Compiler Error C2756 -'template type' : default template arguments not allowed on a partial specialization +> 'template type' : default template arguments not allowed on a partial specialization + +## Remarks The template for a partial specialization may not contain a default argument. -The following sample generates C2756 and shows how to fix it: +## Example + +The following example generates C2756 and shows how to fix it: ```cpp // C2756.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2757.md b/docs/error-messages/compiler-errors-2/compiler-error-c2757.md index 5a863c1b734..a759aa5196f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2757.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2757.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2757" title: "Compiler Error C2757" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2757" +ms.date: 11/04/2016 f1_keywords: ["C2757"] helpviewer_keywords: ["C2757"] -ms.assetid: 421f102f-8a32-4d47-a109-811ddf2c909d --- # Compiler Error C2757 -'symbol' : a symbol with this name already exists and therefore this name cannot be used as a namespace name +> 'symbol' : a symbol with this name already exists and therefore this name cannot be used as a namespace name + +## Remarks A symbol used in the current compilation as a namespace identifier is already being used in a referenced assembly. -The following sample generates C2757: +## Example + +The following example generates C2757: ```cpp // C2757a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2758.md b/docs/error-messages/compiler-errors-2/compiler-error-c2758.md index ad5301bf1e3..3b5c2bed46f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2758.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2758.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2758" title: "Compiler Error C2758" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2758" +ms.date: 11/04/2016 f1_keywords: ["C2758"] helpviewer_keywords: ["C2758"] -ms.assetid: 1d273034-194c-4926-9869-142d1b219cbe --- # Compiler Error C2758 -'member': a member of reference type must be initialized +> 'member': a member of reference type must be initialized + +## Remarks Compiler error C2758 is caused when the constructor does not initialize a member of reference type in an initializer list. The compiler leaves the member undefined. Reference member variables must initialized when declared or be given a value in the initialization list of the constructor. -The following sample generates C2758: +## Example + +The following example generates C2758: ```cpp // C2758.cpp @@ -20,8 +23,8 @@ The following sample generates C2758: struct A { const int i; - A(int n) { }; // C2758 + A(int n) { } // C2758 // try the following line instead - // A(int n) : i{n} {}; + // A(int n) : i{n} {} }; ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2760.md b/docs/error-messages/compiler-errors-2/compiler-error-c2760.md index e33c5a9552a..619d63d8c42 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2760.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2760.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2760" title: "Compiler Error C2760" +description: "Learn more about: Compiler Error C2760" ms.date: 08/12/2021 f1_keywords: ["C2760"] helpviewer_keywords: ["C2760"] -ms.assetid: 585757fd-d519-43f3-94e5-50316ac8b90b --- # Compiler Error C2760 @@ -16,9 +15,9 @@ ms.assetid: 585757fd-d519-43f3-94e5-50316ac8b90b There are several ways to cause this error. Usually, it's caused by a token sequence that the compiler can't make sense of. -## Example +## Examples -In this sample, a casting operator is used with an invalid operator. +In this example, a casting operator is used with an invalid operator. ```cpp // C2760.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2761.md b/docs/error-messages/compiler-errors-2/compiler-error-c2761.md index 1e8e60e233f..ab82d98deff 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2761.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2761.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2761" title: "Compiler Error C2761" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2761" +ms.date: 11/04/2016 f1_keywords: ["C2761"] helpviewer_keywords: ["C2761"] -ms.assetid: 38c79a05-b56d-485b-820f-95e8c0cb926f --- # Compiler Error C2761 -'function' : member function redeclaration not allowed +> 'function' : member function redeclaration not allowed + +## Remarks You cannot redeclare a member function. You can define it, but not redeclare it. ## Examples -The following sample generates C2761. +The following example generates C2761. ```cpp // C2761.cpp @@ -27,7 +28,7 @@ void a::a; // C2761 void a::test; // C2761 ``` -Nonstatic members of a class or structure cannot be defined. The following sample generates C2761. +Nonstatic members of a class or structure cannot be defined. The following example generates C2761. ```cpp // C2761_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2762.md b/docs/error-messages/compiler-errors-2/compiler-error-c2762.md index 6b64d52ba52..6892019ad37 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2762.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2762.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2762" title: "Compiler Error C2762" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2762" +ms.date: 11/04/2016 f1_keywords: ["C2762"] helpviewer_keywords: ["C2762"] -ms.assetid: 8b81a801-fd48-40a1-8bee-0748795b12e4 --- # Compiler Error C2762 -'class' : invalid expression as a template argument for 'argument' +> 'class' : invalid expression as a template argument for 'argument' + +## Remarks When using [/Za](../../build/reference/za-ze-disable-language-extensions.md), the compiler will not convert an integral to a pointer. -The following sample generates C2762: +## Example + +The following example generates C2762: ```cpp // C2762.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2764.md b/docs/error-messages/compiler-errors-2/compiler-error-c2764.md index cc1c8e94940..52a87747fd5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2764.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2764.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2764" title: "Compiler Error C2764" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2764" +ms.date: 11/04/2016 f1_keywords: ["C2764"] helpviewer_keywords: ["C2764"] -ms.assetid: 3754f5af-e094-4425-be20-d0c9a9b5baec --- # Compiler Error C2764 -'param' : template parameter not used or deducible in partial specialization 'specialization' +> 'param' : template parameter not used or deducible in partial specialization 'specialization' + +## Remarks A template parameter is not used in a partial specialization. This makes the partial specialization unusable because the template parameter cannot be deduced. ## Example -The following sample generates C2764: +The following example generates C2764: ```cpp // C2764.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2765.md b/docs/error-messages/compiler-errors-2/compiler-error-c2765.md index e00d03d4855..46067a15fc3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2765.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2765.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Error C2765" title: "Compiler Error C2765" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2765" +ms.date: 11/04/2016 f1_keywords: ["C2765"] helpviewer_keywords: ["C2765"] -ms.assetid: 47ad86f3-a7e0-47ad-85ff-0f5534458cb9 --- # Compiler Error C2765 -'function' : an explicit specialization of a function template cannot have any default arguments +> 'function' : an explicit specialization of a function template cannot have any default arguments + +## Remarks Default arguments are not allowed on an explicit specialization of a function template. For more information, see [Explicit Specialization of Function Templates](../../cpp/explicit-specialization-of-function-templates.md). -The following sample generates C2765: +## Example + +The following example generates C2765: ```cpp // C2765.cpp -template void f(T t) {}; +template void f(T t) {} template<> void f(char c = 'a') {} // C2765 // try the following line instead diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2766.md b/docs/error-messages/compiler-errors-2/compiler-error-c2766.md index 765ffaba7d7..f683b8433a2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2766.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2766.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2766" title: "Compiler Error C2766" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2766" +ms.date: 11/04/2016 f1_keywords: ["C2766"] helpviewer_keywords: ["C2766"] -ms.assetid: 8032f4ca-6827-4f04-9c61-c44643c85cc4 --- # Compiler Error C2766 -explicit specialization; 'specialization' has already been defined +> explicit specialization; 'specialization' has already been defined + +## Remarks Duplicate explicit specializations are not allowed. For more information, see [Explicit Specialization of Function Templates](../../cpp/explicit-specialization-of-function-templates.md). -The following sample generates C2766: +## Example + +The following example generates C2766: ```cpp // C2766.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2767.md b/docs/error-messages/compiler-errors-2/compiler-error-c2767.md index 0e37e783405..07706df7ad5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2767.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2767.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2767" title: "Compiler Error C2767" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2767" +ms.date: 11/04/2016 f1_keywords: ["C2767"] helpviewer_keywords: ["C2767"] -ms.assetid: e8f84178-a160-4d71-a236-07e4fcc11e96 --- # Compiler Error C2767 -managed or WinRTarray dimension mismatch : expected N argument(s) - M provided +> managed or WinRTarray dimension mismatch : expected N argument(s) - M provided + +## Remarks A managed or WinRT array declaration was ill formed. For more information, see [array](../../extensions/arrays-cpp-component-extensions.md). -The following sample generates C2767 and shows how to fix it: +## Example + +The following example generates C2767 and shows how to fix it: ```cpp // C2767.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2768.md b/docs/error-messages/compiler-errors-2/compiler-error-c2768.md index 36d6ca01579..472b925a5e1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2768.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2768.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2768" title: "Compiler Error C2768" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2768" +ms.date: 11/04/2016 f1_keywords: ["C2768"] helpviewer_keywords: ["C2768"] -ms.assetid: a7f6047a-6a80-4737-ad5c-c12868639fb5 --- # Compiler Error C2768 -'function' : illegal use of explicit template arguments +> 'function': illegal use of explicit template arguments -The compiler was unable to determine if a function definition was supposed to be an explicit specialization of a function template or if the function definition was supposed to be for a new function. +## Remarks + +The compiler was unable to determine if a function definition was an explicit specialization of a function template or if it was a new function. This error was introduced in Visual Studio .NET 2003, as part of the compiler conformance enhancements. -The following sample generates C2768: +## Example + +The following example generates C2768: ```cpp // C2768.cpp @@ -27,6 +30,6 @@ void f(int) {} // C2768 template<> void f(int) {} -// global nontemplate function overload +// global non-template function overload void f(int) {} ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2770.md b/docs/error-messages/compiler-errors-2/compiler-error-c2770.md index 93734f5356f..0e0d7839fdb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2770.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2770.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2770" title: "Compiler Error C2770" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2770" +ms.date: 11/04/2016 f1_keywords: ["C2770"] helpviewer_keywords: ["C2770"] -ms.assetid: 100001b5-80b0-4971-8ff6-9023f443c926 --- # Compiler Error C2770 -invalid explicit template_or_generic argument(s) for 'template' +> invalid explicit template_or_generic argument(s) for 'template' + +## Remarks Function template candidates with explicit template or generic arguments resulted in disallowed function types. -The following sample generates C2770: +## Example + +The following example generates C2770: ```cpp // C2770.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2771.md b/docs/error-messages/compiler-errors-2/compiler-error-c2771.md index f6d00ce5b5e..beafafe99db 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2771.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2771.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2771" title: "Compiler Error C2771" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2771" +ms.date: 11/04/2016 f1_keywords: ["C2771"] helpviewer_keywords: ["C2771"] -ms.assetid: b649cc9f-7cbc-4b42-a5e8-51dad5c55e4b --- # Compiler Error C2771 -\#import only permitted at global or namespace scope +> #import only permitted at global or namespace scope + +## Remarks The `#import` directive is not allowed in, for example, a function or structure. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2773.md b/docs/error-messages/compiler-errors-2/compiler-error-c2773.md index a5269df8cb4..01ca8986236 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2773.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2773.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2773" title: "Compiler Error C2773" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2773" +ms.date: 11/04/2016 f1_keywords: ["C2773"] helpviewer_keywords: ["C2773"] -ms.assetid: 8d564b26-1623-4d92-aabc-dff33f7b1145 --- # Compiler Error C2773 -\#import and #using available only in C++ compiler +> #import and #using available only in C++ compiler + +## Remarks The C compiler does not recognize the `#import` preprocessor directive. Compile the source as C++. Use [/TP](../../build/reference/tc-tp-tc-tp-specify-source-file-type.md) if necessary. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2774.md b/docs/error-messages/compiler-errors-2/compiler-error-c2774.md index 83bb2f1f579..6ad8e6659e4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2774.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2774.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2774" title: "Compiler Error C2774" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2774" +ms.date: 11/04/2016 f1_keywords: ["C2774"] helpviewer_keywords: ["C2774"] -ms.assetid: 10f428c6-7f49-489a-92ba-6ef978b7caaf --- # Compiler Error C2774 -'identifier' : no 'put' method is associated with this property +> 'identifier' : no 'put' method is associated with this property + +## Remarks A data member declared with [property](../../cpp/property-cpp.md) has no `put` function, but an expression tries to set its value. -The following sample generates C2774: +## Example + +The following example generates C2774: ```cpp // C2774.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2775.md b/docs/error-messages/compiler-errors-2/compiler-error-c2775.md index 0997247f838..00654e73f7a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2775.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2775.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2775" title: "Compiler Error C2775" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2775" +ms.date: 11/04/2016 f1_keywords: ["C2775"] helpviewer_keywords: ["C2775"] -ms.assetid: 9c488508-ade0-48f1-b94f-d538d15f807a --- # Compiler Error C2775 -'identifier' : no 'get' method is associated with this property +> 'identifier' : no 'get' method is associated with this property + +## Remarks A data member declared with the [property](../../cpp/property-cpp.md) extended attribute does not have a `get` function specified, but an expression tries to retrieve its value. -The following sample generates C2775: +## Example + +The following example generates C2775: ```cpp // C2775.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2776.md b/docs/error-messages/compiler-errors-2/compiler-error-c2776.md index 94145080436..a1844454dfa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2776.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2776.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2776" title: "Compiler Error C2776" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2776" +ms.date: 11/04/2016 f1_keywords: ["C2776"] helpviewer_keywords: ["C2776"] -ms.assetid: 9d80addc-62c7-40fc-a2cc-60303abb87df --- # Compiler Error C2776 -only one 'get' method can be specified per property +> only one 'get' method can be specified per property + +## Remarks You can only specify one `get` function in the [property](../../cpp/property-cpp.md) extended attribute. This error occurs when multiple `get` functions are specified. -The following sample generates C2776: +## Example + +The following example generates C2776: ```cpp // C2776.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2777.md b/docs/error-messages/compiler-errors-2/compiler-error-c2777.md index cff4aef538b..5b624a0afe0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2777.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2777.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2777" title: "Compiler Error C2777" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2777" +ms.date: 11/04/2016 f1_keywords: ["C2777"] helpviewer_keywords: ["C2777"] -ms.assetid: 5fe158c0-2a65-488a-aca2-61d4a8b32d43 --- # Compiler Error C2777 -only one 'put' method can be specified per property +> only one 'put' method can be specified per property + +## Remarks A [property](../../cpp/property-cpp.md) declspec modifier had more than one `put` property. -The following sample generates C2777: +## Example + +The following example generates C2777: ```cpp // C2777.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2778.md b/docs/error-messages/compiler-errors-2/compiler-error-c2778.md index febe7f24c82..5988f1aa528 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2778.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2778.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C2778" title: "Compiler Error C2778" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2778" +ms.date: 11/04/2016 f1_keywords: ["C2778"] helpviewer_keywords: ["C2778"] -ms.assetid: b24cb732-2914-42cc-8928-e2d87b393428 --- # Compiler Error C2778 -improperly formed GUID in __declspec(uuid()) +> improperly formed GUID in __declspec(uuid()) + +## Remarks An incorrect GUID is supplied to the [uuid](../../cpp/uuid-cpp.md) extended attribute. +## Example + The GUID must be a string of hexadecimal numbers with the following format: ```cpp @@ -23,7 +26,7 @@ struct __declspec(uuid("{00000000-0000-0000-0000-000000000000}")) B{}; The `uuid` extended attribute accepts strings recognized by [CLSIDFromString](/windows/win32/api/combaseapi/nf-combaseapi-clsidfromstring), with or without brace delimiters. -The following sample generates C2778: +The following example generates C2778: ```cpp // C2778b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2779.md b/docs/error-messages/compiler-errors-2/compiler-error-c2779.md index a5cceba3ae5..8e0b8797e1f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2779.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2779.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2779" title: "Compiler Error C2779" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2779" +ms.date: 11/04/2016 f1_keywords: ["C2779"] helpviewer_keywords: ["C2779"] -ms.assetid: 4a00e492-855a-41f3-8a18-5f60ee20c2f2 --- # Compiler Error C2779 -'declaration' : property methods can only be associated with non-static data members +> 'declaration' : property methods can only be associated with non-static data members + +## Remarks The **`property`** extended attribute is incorrectly applied to a static data member. -The following sample generates C2779: +## Example + +The following example generates C2779: ```cpp // C2779.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2780.md b/docs/error-messages/compiler-errors-2/compiler-error-c2780.md index e1d639ffdf2..6c5c901d405 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2780.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2780.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2780" title: "Compiler Error C2780" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2780" +ms.date: 11/04/2016 f1_keywords: ["C2780"] helpviewer_keywords: ["C2780"] -ms.assetid: 423793d8-a3b2-4f35-85f8-ae1d043e2b69 --- # Compiler Error C2780 -'declaration' : expects N arguments - M provided +> 'declaration' : expects N arguments - M provided + +## Remarks A function template has too few or too many arguments. -The following sample generates C2780 and shows how to fix it: +## Example + +The following example generates C2780 and shows how to fix it: ```cpp // C2780.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2781.md b/docs/error-messages/compiler-errors-2/compiler-error-c2781.md index e7ac58ef5a7..8af20a38e2d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2781.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2781.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2781" title: "Compiler Error C2781" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2781" +ms.date: 11/04/2016 f1_keywords: ["C2781"] helpviewer_keywords: ["C2781"] -ms.assetid: f29b9963-f55b-427c-8db6-50f37713df5a --- # Compiler Error C2781 -'declaration' : expects at least value1 argument - value2 provided +> 'declaration' : expects at least value1 argument - value2 provided + +## Remarks A function template with a variable parameter list has too few arguments. -The following sample generates C2781: +## Example + +The following example generates C2781: ```cpp // C2781.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2782.md b/docs/error-messages/compiler-errors-2/compiler-error-c2782.md index 0b253401473..1437c8068c4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2782.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2782.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2782" title: "Compiler Error C2782" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2782" +ms.date: 11/04/2016 f1_keywords: ["C2782"] helpviewer_keywords: ["C2782"] -ms.assetid: 8b685422-294d-4f64-9f3d-c14eaf03a93d --- # Compiler Error C2782 -'declaration' : template parameter 'identifier' is ambiguous +> 'declaration' : template parameter 'identifier' is ambiguous + +## Remarks The compiler cannot determine the type of a template argument. -The following sample generates C2782: +## Examples + +The following example generates C2782: ```cpp // C2782.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2783.md b/docs/error-messages/compiler-errors-2/compiler-error-c2783.md index c44ff86dbb7..d906f0cd87f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2783.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2783.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2783" title: "Compiler Error C2783" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2783" +ms.date: 11/04/2016 f1_keywords: ["C2783"] helpviewer_keywords: ["C2783"] -ms.assetid: 1ce94a11-bb8b-4be3-a222-f1f105da74b3 --- # Compiler Error C2783 -'declaration' : could not deduce template argument for 'identifier' +> 'declaration' : could not deduce template argument for 'identifier' + +## Remarks The compiler cannot determine a template argument. Default arguments cannot be used to deduce a template argument. -The following sample generates C2783: +## Examples + +The following example generates C2783: ```cpp // C2783.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2784.md b/docs/error-messages/compiler-errors-2/compiler-error-c2784.md index a8b82581e80..289c3733624 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2784.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2784.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2784" title: "Compiler Error C2784" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2784" +ms.date: 11/04/2016 f1_keywords: ["C2784"] helpviewer_keywords: ["C2784"] -ms.assetid: 3d761fe2-881c-48bd-afae-e2e714e20473 --- # Compiler Error C2784 -'declaration' : could not deduce template argument for 'type' from 'type' +> 'declaration' : could not deduce template argument for 'type' from 'type' + +## Remarks The compiler cannot determine a template argument from the supplied function arguments. -The following sample generates C2784 and shows how to fix it: +## Example + +The following example generates C2784 and shows how to fix it: ```cpp // C2784.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2785.md b/docs/error-messages/compiler-errors-2/compiler-error-c2785.md index db69f33c9fe..07589c43d27 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2785.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2785.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2785" title: "Compiler Error C2785" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2785" +ms.date: 11/04/2016 f1_keywords: ["C2785"] helpviewer_keywords: ["C2785"] -ms.assetid: d8d13360-0d00-4815-8475-b49c7f0dc0f3 --- # Compiler Error C2785 -'declaration1' and 'declaration2' have different return types +> 'declaration1' and 'declaration2' have different return types + +## Remarks The return type of function template specialization differs from the return type of the primary function template. @@ -18,7 +19,7 @@ The return type of function template specialization differs from the return type ## Example -The following sample generates C2785: +The following example generates C2785: ```cpp // C2785.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2786.md b/docs/error-messages/compiler-errors-2/compiler-error-c2786.md index f8befff1ee9..3cdd52ad9a4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2786.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2786.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2786" title: "Compiler Error C2786" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2786" +ms.date: 11/04/2016 f1_keywords: ["C2786"] helpviewer_keywords: ["C2786"] -ms.assetid: 6676d8c0-86dd-4a39-bdda-b75a35f4d137 --- # Compiler Error C2786 -'type' : invalid operand for __uuidof +> 'type' : invalid operand for __uuidof + +## Remarks The [__uuidof](../../cpp/uuidof-operator.md) operator takes a user-defined type with a GUID attached or an object of such a user-defined type. Possible causes: @@ -16,7 +17,9 @@ The [__uuidof](../../cpp/uuidof-operator.md) operator takes a user-defined type 1. **`__uuidof`** cannot extract the GUID from the argument. -The following sample generates C2786: +## Example + +The following example generates C2786: ```cpp // C2786.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2787.md b/docs/error-messages/compiler-errors-2/compiler-error-c2787.md index f6e3c1e6f5b..e7e92cd8d32 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2787.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2787.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2787" title: "Compiler Error C2787" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2787" +ms.date: 11/04/2016 f1_keywords: ["C2787"] helpviewer_keywords: ["C2787"] -ms.assetid: 34cb57e6-cafe-4ce7-bcc6-53d194629bd0 --- # Compiler Error C2787 -'identifier' : no GUID has been associated with this object +> 'identifier' : no GUID has been associated with this object + +## Remarks The [__uuidof](../../cpp/uuidof-operator.md) operator takes a user-defined type with a GUID attached or an object of such a user-defined type. This error occurs when the argument is a user-defined type with no GUID. -The following sample generates C2787: +## Example + +The following example generates C2787: ```cpp // C2787.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2788.md b/docs/error-messages/compiler-errors-2/compiler-error-c2788.md index 688823ae549..f45b9117036 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2788.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2788.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2788" title: "Compiler Error C2788" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2788" +ms.date: 11/04/2016 f1_keywords: ["C2788"] helpviewer_keywords: ["C2788"] -ms.assetid: 8688fc5c-e652-43b4-b407-9c488c76f2db --- # Compiler Error C2788 -'identifier' : more than one GUID associated with this object +> 'identifier' : more than one GUID associated with this object + +## Remarks The [__uuidof](../../cpp/uuidof-operator.md) operator takes a user-defined type with a GUID attached or an object of such a user-defined type. This error occurs when the argument is an object with multiple GUIDs. -The following sample generates C2788: +## Example + +The following example generates C2788: ```cpp // C2788.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2790.md b/docs/error-messages/compiler-errors-2/compiler-error-c2790.md index 7fa8d57c9bf..bf32485d812 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2790.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2790.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2790" title: "Compiler Error C2790" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2790" +ms.date: 11/04/2016 f1_keywords: ["C2790"] helpviewer_keywords: ["C2790"] -ms.assetid: 38d4fce1-ba00-413d-8bc1-e8aa43d7bc1f --- # Compiler Error C2790 -'super' : this keyword can only be used within the body of class member function +> 'super' : this keyword can only be used within the body of class member function + +## Remarks This error message appears if the user ever tries to uses the keyword [super](../../cpp/super.md) outside of the context of a member function. -The following sample generates C2790: +## Example + +The following example generates C2790: ```cpp // C2790.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2791.md b/docs/error-messages/compiler-errors-2/compiler-error-c2791.md index 127353149a4..24de65980a5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2791.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2791.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2791" title: "Compiler Error C2791" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2791" +ms.date: 11/04/2016 f1_keywords: ["C2791"] helpviewer_keywords: ["C2791"] -ms.assetid: 938ad1fb-75d9-4ce2-ad92-83d6249005b5 --- # Compiler Error C2791 -illegal use of 'super': 'class' does not have any base classes +> illegal use of 'super': 'class' does not have any base classes + +## Remarks The keyword [super](../../cpp/super.md) was used within the context of a member function of a class that does not have any base classes. -The following sample generates C2791: +## Example + +The following example generates C2791: ```cpp // C2791.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2792.md b/docs/error-messages/compiler-errors-2/compiler-error-c2792.md index 54f751a3118..5503da07a8e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2792.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2792.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2792" title: "Compiler Error C2792" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2792" +ms.date: 11/04/2016 f1_keywords: ["C2792"] helpviewer_keywords: ["C2792"] -ms.assetid: 392cf748-4f5e-4e62-a364-3118d5658408 --- # Compiler Error C2792 -'super' : this keyword must be followed by '::' +> 'super' : this keyword must be followed by '::' + +## Remarks The only token that can follow the keyword **`__super`** is `::`. -The following sample generates C2792: +## Example + +The following example generates C2792: ```cpp // C2792.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2793.md b/docs/error-messages/compiler-errors-2/compiler-error-c2793.md index 6421099661f..3581467aef3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2793.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2793.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2793" title: "Compiler Error C2793" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2793" +ms.date: 11/04/2016 f1_keywords: ["C2793"] helpviewer_keywords: ["C2793"] -ms.assetid: ce35f4e8-c357-40ca-95c4-15ff001ad69d --- # Compiler Error C2793 -'token' : unexpected token following '::', identifier or keyword 'operator' expected +> 'token' : unexpected token following '::', identifier or keyword 'operator' expected + +## Remarks The only tokens that can follow `__super::` are an identifier or the keyword **`operator`**. -The following sample generates C2793 +## Example + +The following example generates C2793 ```cpp // C2793.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2794.md b/docs/error-messages/compiler-errors-2/compiler-error-c2794.md index d9d8fbb45ff..72657858861 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2794.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2794.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2794" title: "Compiler Error C2794" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2794" +ms.date: 11/04/2016 f1_keywords: ["C2794"] helpviewer_keywords: ["C2794"] -ms.assetid: d508191c-9044-4c6a-9119-4bca668c0b93 --- # Compiler Error C2794 -'function' : is not a member of any direct or indirect base class of 'class' +> 'function' : is not a member of any direct or indirect base class of 'class' + +## Remarks You tried to use [super](../../cpp/super.md) to call a nonexistent member function. -The following sample generates C2794 +## Example + +The following example generates C2794 ```cpp // C2794.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2795.md b/docs/error-messages/compiler-errors-2/compiler-error-c2795.md index b9aaa67ad82..1505d3af111 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2795.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2795.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2795" title: "Compiler Error C2795" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2795" +ms.date: 11/04/2016 f1_keywords: ["C2795"] helpviewer_keywords: ["C2795"] -ms.assetid: 8cd8c7fe-2add-4871-85f7-9a6afe4ac588 --- # Compiler Error C2795 -'super::function' is not a member function +> 'super::function' is not a member function + +## Remarks This error message appears whenever you try to use [super](../../cpp/super.md) to access a member other than a member function. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2797.md b/docs/error-messages/compiler-errors-2/compiler-error-c2797.md index 7dc731a466a..52e3d27661b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2797.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2797.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2797" title: "Compiler Error C2797" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2797" +ms.date: 11/04/2016 f1_keywords: ["C2797"] helpviewer_keywords: ["C2797"] -ms.assetid: 9fb26d35-eb5c-46fc-9ff5-756fba5bdaff --- # Compiler Error C2797 -(Obsolete) List initialization inside member initializer list or non-static data member initializer is not implemented. +> (Obsolete) List initialization inside member initializer list or non-static data member initializer is not implemented. + +## Remarks This warning is obsolete in Visual Studio 2015. In Visual Studio 2013 and earlier versions, the Microsoft C++ compiler does not implement list initialization inside either a member initializer list or a non-static data member initializer. Before Visual Studio 2013 Update 3, this was silently converted to a function call, which could lead to bad code generation. Visual Studio 2013 Update 3 reports this as an error. +## Examples + This example generates C2797: -``` +```cpp #include struct S { S() : v1{1} {} // C2797, VS2013 RTM incorrectly calls 'vector(size_type)' @@ -26,7 +29,7 @@ struct S { This example also generates C2797: -``` +```cpp struct S1 { int i; }; @@ -40,7 +43,7 @@ struct S2 { To fix this issue, you can use explicit construction of inner lists. For example: -``` +```cpp #include typedef std::vector Vector; struct S { @@ -53,7 +56,7 @@ struct S { If you do not require list initialization: -``` +```cpp struct S { S() : s1("") {} diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2798.md b/docs/error-messages/compiler-errors-2/compiler-error-c2798.md index 9bdca5513c9..5e5d7754190 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2798.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2798.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2798" title: "Compiler Error C2798" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2798" +ms.date: 11/04/2016 f1_keywords: ["C2798"] helpviewer_keywords: ["C2798"] -ms.assetid: fb0cd861-b228-4f81-8090-e28344a727e0 --- # Compiler Error C2798 -'super::member' is ambiguous +> 'super::member' is ambiguous + +## Remarks Multiple inherited structures contain the member you referenced with [super](../../cpp/super.md). You could fix the error by either: @@ -16,7 +17,9 @@ Multiple inherited structures contain the member you referenced with [super](../ - Changing the name of the data member in B1 or B2. -The following sample generates C2798: +## Example + +The following example generates C2798: ```cpp // C2798.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2800.md b/docs/error-messages/compiler-errors-2/compiler-error-c2800.md index 31f8908e35f..7de01cf11dc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2800.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2800.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2800" title: "Compiler Error C2800" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2800" +ms.date: 11/04/2016 f1_keywords: ["C2800"] helpviewer_keywords: ["C2800"] -ms.assetid: a2f1a590-9fe6-44cb-ad09-b4505ef47c6a --- # Compiler Error C2800 -'operator operator' cannot be overloaded +> 'operator operator' cannot be overloaded + +## Remarks The following operators cannot be overloaded: class member access (`.`), pointer to member (`.*`), scope resolution (`::`), conditional expression (`? :`), and **`sizeof`**. -The following sample generates C2800: +## Example + +The following example generates C2800: ```cpp // C2800.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2801.md b/docs/error-messages/compiler-errors-2/compiler-error-c2801.md index 072efc5bada..1fc1d35138c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2801.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2801.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2801" title: "Compiler Error C2801" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2801" +ms.date: 11/04/2016 f1_keywords: ["C2801"] helpviewer_keywords: ["C2801"] -ms.assetid: 35dfc7ea-9e37-4e30-baa1-944dc61302f5 --- # Compiler Error C2801 -'operator operator' must be a non-static member +> 'operator operator' must be a non-static member + +## Remarks The following operators can be overloaded only as nonstatic members: @@ -26,7 +27,9 @@ Possible C2801 causes: - Overloaded operator is declared **`static`**. -- The following sample generates C2801: +## Example + +- The following example generates C2801: ```cpp // C2801.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2802.md b/docs/error-messages/compiler-errors-2/compiler-error-c2802.md index 6213cbba277..d7920ab5bd3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2802.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2802.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2802" title: "Compiler Error C2802" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2802" +ms.date: 11/04/2016 f1_keywords: ["C2802"] helpviewer_keywords: ["C2802"] -ms.assetid: 08b68c0e-9382-40ac-8949-39a7a2749e05 --- # Compiler Error C2802 -static member 'operator operator' has no formal parameters +> static member 'operator operator' has no formal parameters + +## Remarks An operator declared by a **`static`** member function must have at least one parameter. -The following sample generates C2802: +## Example + +The following example generates C2802: ```cpp // C2802.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2803.md b/docs/error-messages/compiler-errors-2/compiler-error-c2803.md index d3b3c841e34..56585a0492d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2803.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2803.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2803" title: "Compiler Error C2803" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2803" +ms.date: 11/04/2016 f1_keywords: ["C2803"] helpviewer_keywords: ["C2803"] -ms.assetid: 2cdbe374-8cc4-4c4e-ba15-062a7479e937 --- # Compiler Error C2803 -'operator operator' must have at least one formal parameter of class type +> 'operator operator' must have at least one formal parameter of class type + +## Remarks The overloaded operator lacks a parameter of class type. @@ -16,7 +17,9 @@ You need to pass at least one parameter by reference (not using pointers, but re If both parameters are pointers it will be a pure comparison of pointer addresses and will not use the user-defined conversion. -The following sample generates C2803: +## Example + +The following example generates C2803: ```cpp // C2803.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2804.md b/docs/error-messages/compiler-errors-2/compiler-error-c2804.md index 1ca73c5ca65..6837c7650c2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2804.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2804.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2804" title: "Compiler Error C2804" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2804" +ms.date: 11/04/2016 f1_keywords: ["C2804"] helpviewer_keywords: ["C2804"] -ms.assetid: b066e563-cca4-450c-8ba7-3b0d7a89f3ea --- # Compiler Error C2804 -binary 'operator operator' has too many parameters +> binary 'operator operator' has too many parameters + +## Remarks The overloaded binary operator member function is declared with more than one parameter. The first operand parameter of a binary operator member function, whose type is the operator's enclosing type, is implied. ## Examples -The following sample generates C2804 and shows how to fix it. +The following example generates C2804 and shows how to fix it. ```cpp // C2804.cpp @@ -31,7 +32,7 @@ int main() { } ``` -The following sample generates C2804 and shows how to fix it. +The following example generates C2804 and shows how to fix it. ```cpp // C2804_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2805.md b/docs/error-messages/compiler-errors-2/compiler-error-c2805.md index 69a25b9734a..219a8c8d65b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2805.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2805.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2805" title: "Compiler Error C2805" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2805" +ms.date: 11/04/2016 f1_keywords: ["C2805"] helpviewer_keywords: ["C2805"] -ms.assetid: c997dc56-e199-442f-b94e-ac551ec9b015 --- # Compiler Error C2805 -binary 'operator operator' has too few parameters +> binary 'operator operator' has too few parameters + +## Remarks The binary operator has no parameters. -The following sample generates C2805: +## Example + +The following example generates C2805: ```cpp // C2805.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2806.md b/docs/error-messages/compiler-errors-2/compiler-error-c2806.md index a1efc1388d3..84ff0db1dfa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2806.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2806.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2806" title: "Compiler Error C2806" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2806" +ms.date: 11/04/2016 f1_keywords: ["C2806"] helpviewer_keywords: ["C2806"] -ms.assetid: 7c9ff1f4-1590-4c47-991d-b1075a173b48 --- # Compiler Error C2806 -'operator operator' has too many formal parameters +> 'operator operator' has too many formal parameters + +## Remarks An overloaded operator has too many parameters. -The following sample generates C2806: +## Example + +The following example generates C2806: ```cpp // C2806.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2807.md b/docs/error-messages/compiler-errors-2/compiler-error-c2807.md index 1eb9f971c86..eda69103326 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2807.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2807.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2807" title: "Compiler Error C2807" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2807" +ms.date: 11/04/2016 f1_keywords: ["C2807"] helpviewer_keywords: ["C2807"] -ms.assetid: bd7a207a-f379-4de6-8ee8-c7cab78b3480 --- # Compiler Error C2807 -the second formal parameter to postfix 'operator operator' must be 'int' +> the second formal parameter to postfix 'operator operator' must be 'int' + +## Remarks The second parameter to a postfix operator has the wrong type. -The following sample generates C2807: +## Example + +The following example generates C2807: ```cpp // C2807.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2808.md b/docs/error-messages/compiler-errors-2/compiler-error-c2808.md index 438adafd4a0..7a2df195342 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2808.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2808.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2808" title: "Compiler Error C2808" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2808" +ms.date: 11/04/2016 f1_keywords: ["C2808"] helpviewer_keywords: ["C2808"] -ms.assetid: 3d745102-d3b3-4735-a7d2-ad42d5bf3cfa --- # Compiler Error C2808 -unary 'operator operator' has too many formal parameters +> unary 'operator operator' has too many formal parameters + +## Remarks The unary operator has a nonvoid parameter list. -The following sample generates C2808: +## Example + +The following example generates C2808: ```cpp // C2808.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2809.md b/docs/error-messages/compiler-errors-2/compiler-error-c2809.md index 48d236e3e85..e99316b66eb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2809.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2809.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2809" title: "Compiler Error C2809" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2809" +ms.date: 11/04/2016 f1_keywords: ["C2809"] helpviewer_keywords: ["C2809"] -ms.assetid: ce796b8e-1a8c-4074-995d-1ad09afd0e93 --- # Compiler Error C2809 -'operator operator' has no formal parameters +> 'operator operator' has no formal parameters + +## Remarks The operator lacks required parameters. -The following sample generates C2809: +## Example + +The following example generates C2809: ```cpp // C2809.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2810.md b/docs/error-messages/compiler-errors-2/compiler-error-c2810.md index 43de6906e30..822e5b9de74 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2810.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2810.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2810" title: "Compiler Error C2810" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2810" +ms.date: 11/04/2016 f1_keywords: ["C2810"] helpviewer_keywords: ["C2810"] -ms.assetid: f63e8f24-d7f6-42ac-904f-72ff49592ba6 --- # Compiler Error C2810 -'interface' : an interface can only inherit from another interface +> 'interface' : an interface can only inherit from another interface + +## Remarks An [interface](../../cpp/interface.md) may only inherit from another interface and may not inherit from a class or struct. -The following sample generates C2810: +## Example + +The following example generates C2810: ```cpp // C2810.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2811.md b/docs/error-messages/compiler-errors-2/compiler-error-c2811.md index 4f36772c6c5..e10b1d0ebea 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2811.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2811.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2811" title: "Compiler Error C2811" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2811" +ms.date: 11/04/2016 f1_keywords: ["C2811"] helpviewer_keywords: ["C2811"] -ms.assetid: 6a44b18e-44c1-49d8-9b99-e0545b9a6e7d --- # Compiler Error C2811 -'type1' : cannot inherit from 'type2', a ref class can only inherit from a ref class or interface class +> 'type1' : cannot inherit from 'type2', a ref class can only inherit from a ref class or interface class + +## Remarks You attempted to use an unmanaged class as a base class for a managed class. -The following sample generates C2811: +## Example + +The following example generates C2811: ```cpp // C2811.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2812.md b/docs/error-messages/compiler-errors-2/compiler-error-c2812.md index 5b4483c3476..247df73f444 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2812.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2812.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Error C2812" title: "Compiler Error C2812" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2812" +ms.date: 11/04/2016 f1_keywords: ["C2812"] helpviewer_keywords: ["C2812"] -ms.assetid: 22aadb8c-7232-489d-a3ad-60662dda30a8 --- # Compiler Error C2812 -> \#import is not supported with /clr:pure and /clr:safe +> #import is not supported with /clr:pure and /clr:safe ## Remarks @@ -18,7 +17,7 @@ The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual St ## Example -The following sample generates C2812. +The following example generates C2812. ```cpp // C2812.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2813.md b/docs/error-messages/compiler-errors-2/compiler-error-c2813.md index a9ae15d2023..d2c6623c52b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2813.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2813.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C2813" title: "Compiler Error C2813" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2813" +ms.date: 11/04/2016 f1_keywords: ["C2813"] helpviewer_keywords: ["C2813"] -ms.assetid: 6cf2135f-7b82-42d1-909a-5e864308a09c --- # Compiler Error C2813 -\#import is not supported with /MP +> #import is not supported with /MP + +## Remarks -C2813 is emitted if in a compiler command you specify the **/MP** compiler option and two or more files to compile, and one or more of the files contains the[#import](../../preprocessor/hash-import-directive-cpp.md) preprocessor directive. The [#import](../../preprocessor/hash-import-directive-cpp.md) directive generates C++ classes from the types in the specified type library, and then writes those classes to two header files. The [#import](../../preprocessor/hash-import-directive-cpp.md) directive is not supported because if multiple compilation units import the same type library, those units conflict when they try to write the same header files at the same time. +C2813 is emitted if in a compiler command you specify the **/MP** compiler option and two or more files to compile, and one or more of the files contains the [#import](../../preprocessor/hash-import-directive-cpp.md) preprocessor directive. The [#import](../../preprocessor/hash-import-directive-cpp.md) directive generates C++ classes from the types in the specified type library, and then writes those classes to two header files. The [#import](../../preprocessor/hash-import-directive-cpp.md) directive is not supported because if multiple compilation units import the same type library, those units conflict when they try to write the same header files at the same time. This compiler error and the **/MP** compiler option are new in Visual Studio 2008. ## Example -The following sample generates C2813. The command line in the "compile with:" comment indicates to the compiler to use the **/MP** and **/c** compiler options to compile several files. At least one of the files contains the [#import](../../preprocessor/hash-import-directive-cpp.md) directive. We use the same file twice for the sake of testing this example. +The following example generates C2813. The command line in the "compile with:" comment indicates to the compiler to use the **/MP** and **/c** compiler options to compile several files. At least one of the files contains the [#import](../../preprocessor/hash-import-directive-cpp.md) directive. We use the same file twice for the sake of testing this example. ```cpp // C2813.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2814.md b/docs/error-messages/compiler-errors-2/compiler-error-c2814.md index 3c5b827f798..a34fc692a4f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2814.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2814.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2814" title: "Compiler Error C2814" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2814" +ms.date: 11/04/2016 f1_keywords: ["C2814"] helpviewer_keywords: ["C2814"] -ms.assetid: 7d165136-a08b-4497-a76d-60a21bb19404 --- # Compiler Error C2814 -'member' : a native type cannot be nested within a managed or WinRT type 'type' +> 'member' : a native type cannot be nested within a managed or WinRT type 'type' + +## Remarks + +A native type cannot be nested in a CLR or WinRT type. ## Example -A native type cannot be nested in a CLR or WinRT type. The following sample generates C2814 and shows how to fix it. +The following example generates C2814 and shows how to fix it. ```cpp // C2814.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2815.md b/docs/error-messages/compiler-errors-2/compiler-error-c2815.md index 8c0711ede95..d4e855253e4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2815.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2815.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2815" title: "Compiler Error C2815" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2815" +ms.date: 11/04/2016 f1_keywords: ["C2815"] helpviewer_keywords: ["C2815"] -ms.assetid: d0256fd6-0721-4c99-b03c-52d96e77a613 --- # Compiler Error C2815 -'operator delete' : first formal parameter must be 'void *', but 'param' was used +> 'operator delete' : first formal parameter must be 'void *', but 'param' was used + +## Remarks Any user-defined [operator delete](../../standard-library/new-operators.md#op_delete) function must take a first formal parameter of type `void *`. -The following sample generates C2815: +## Example + +The following example generates C2815: ```cpp // C2815.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2817.md b/docs/error-messages/compiler-errors-2/compiler-error-c2817.md index b437cf9ca4e..24c59040cf3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2817.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2817.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2817" title: "Compiler Error C2817" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2817" +ms.date: 11/04/2016 f1_keywords: ["C2817"] helpviewer_keywords: ["C2817"] -ms.assetid: bca2e55a-8d86-4ddf-ba2b-4568f3bb776e --- # Compiler Error C2817 -return type for 'operator delete' must be 'void' +> return type for 'operator delete' must be 'void' + +## Remarks An overloaded [operator delete](../../standard-library/new-operators.md#op_delete) function cannot return a value. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2818.md b/docs/error-messages/compiler-errors-2/compiler-error-c2818.md index 9ca58a16377..88373838771 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2818.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2818.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2818" title: "Compiler Error C2818" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2818" +ms.date: 11/04/2016 f1_keywords: ["C2818"] helpviewer_keywords: ["C2818"] -ms.assetid: 715fc7c9-0c6d-452b-b7f5-1682cea5e907 --- # Compiler Error C2818 -application of overloaded 'operator ->' is recursive through type 'type' +> application of overloaded 'operator ->' is recursive through type 'type' + +## Remarks A redefinition of the class member access operator contains a recursive **`return`** statement. To redefine the `->` operator with recursion, you must move the recursive routine to a separate function called from the operator override function. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2819.md b/docs/error-messages/compiler-errors-2/compiler-error-c2819.md index 7021fec040b..063bf1c863a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2819.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2819.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2819" title: "Compiler Error C2819" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2819" +ms.date: 11/04/2016 f1_keywords: ["C2819"] helpviewer_keywords: ["C2819"] -ms.assetid: fcc7762d-cb82-4bb1-a715-0d82da832edf --- # Compiler Error C2819 -type 'type' does not have an overloaded member 'operator ->' +> type 'type' does not have an overloaded member 'operator ->' + +## Remarks You need to define `operator->()` to use this pointer operation. -The following sample generates C2819: +## Examples + +The following example generates C2819: ```cpp // C2819.cpp @@ -42,7 +45,7 @@ void F(D j) { } ``` -C2819 can also occur when using [C++ Stack Semantics for Reference Types](../../dotnet/cpp-stack-semantics-for-reference-types.md). The following sample generates C2819: +C2819 can also occur when using [C++ Stack Semantics for Reference Types](../../dotnet/cpp-stack-semantics-for-reference-types.md). The following example generates C2819: ```cpp // C2819_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2821.md b/docs/error-messages/compiler-errors-2/compiler-error-c2821.md index d187c402136..aff747245de 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2821.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2821.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2821" title: "Compiler Error C2821" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2821" +ms.date: 11/04/2016 f1_keywords: ["C2821"] helpviewer_keywords: ["C2821"] -ms.assetid: e8d71988-a968-4484-94db-e8c3bad74a4a --- # Compiler Error C2821 -first formal parameter to 'operator new' must be 'unsigned int' +> first formal parameter to 'operator new' must be 'unsigned int' + +## Remarks The first formal parameter of the [operator new](../../standard-library/new-operators.md#op_new) must be an unsigned **`int`**. ## Example -The following sample generates C2821: +The following example generates C2821: ```cpp // C2821.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2823.md b/docs/error-messages/compiler-errors-2/compiler-error-c2823.md index acdfe09f032..461936a5360 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2823.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2823.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2823" title: "Compiler Error C2823" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2823" +ms.date: 11/04/2016 f1_keywords: ["C2823"] helpviewer_keywords: ["C2823"] -ms.assetid: 982b1b35-1a7c-456e-b711-f80cfe2d571e --- # Compiler Error C2823 > a typedef template is illegal +## Remarks + Templates are not allowed in **`typedef`** definitions. ## Example -The following sample generates C2823, and shows one way to fix it: +The following example generates C2823, and shows one way to fix it: ```cpp // C2823.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2824.md b/docs/error-messages/compiler-errors-2/compiler-error-c2824.md index 2178beb0a79..f314fdc5d08 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2824.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2824.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2824" title: "Compiler Error C2824" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2824" +ms.date: 11/04/2016 f1_keywords: ["C2824"] helpviewer_keywords: ["C2824"] -ms.assetid: 5bd865f7-e0af-404e-80fe-e2b798b44a59 --- # Compiler Error C2824 -return type for 'operator new' must be 'void *' +> return type for 'operator new' must be 'void *' + +## Remarks With non-based pointers, overloads of operator `new` must return `void *`. -The following sample generates C2824: +## Example + +The following example generates C2824: ```cpp // C2824.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2825.md b/docs/error-messages/compiler-errors-2/compiler-error-c2825.md index fc7b5f733e7..451592c6a90 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2825.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2825.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2825" title: "Compiler Error C2825" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2825" +ms.date: 11/04/2016 f1_keywords: ["C2825"] helpviewer_keywords: ["C2825"] -ms.assetid: c832f1c1-5184-4fc2-9356-12b21daa7af3 --- # Compiler Error C2825 -var : must be a class or namespace when followed by '::' +> var : must be a class or namespace when followed by '::' + +## Remarks An unsuccessful attempt was made to form a qualified name. @@ -16,7 +17,7 @@ For example, make sure that your code does not contain a function declaration wh ## Example -The following sample generates C2825: +The following example generates C2825: ```cpp // C2825.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2827.md b/docs/error-messages/compiler-errors-2/compiler-error-c2827.md index fe90f7e62bf..77edf9d6175 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2827.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2827.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2827" title: "Compiler Error C2827" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2827" +ms.date: 11/04/2016 f1_keywords: ["C2827"] helpviewer_keywords: ["C2827"] -ms.assetid: cb3e5814-0c92-40e4-b620-98578ae3003a --- # Compiler Error C2827 -'operator operator' cannot be globally overridden with unary form +> 'operator operator' cannot be globally overridden with unary form + +## Remarks The operator cannot have a unary form outside of an object. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2828.md b/docs/error-messages/compiler-errors-2/compiler-error-c2828.md index 0273a717134..3a2f05f16f2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2828.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2828.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2828" title: "Compiler Error C2828" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2828" +ms.date: 11/04/2016 f1_keywords: ["C2828"] helpviewer_keywords: ["C2828"] -ms.assetid: d8df6ed4-5954-46c2-b59b-52881d4e923d --- # Compiler Error C2828 -'operator operator' cannot be globally overridden with binary form +> 'operator operator' cannot be globally overridden with binary form + +## Remarks The operator cannot have a binary form outside of an object. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2829.md b/docs/error-messages/compiler-errors-2/compiler-error-c2829.md index 137d653a228..785f6ffbe62 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2829.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2829.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2829" title: "Compiler Error C2829" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2829" +ms.date: 11/04/2016 f1_keywords: ["C2829"] helpviewer_keywords: ["C2829"] -ms.assetid: b3bfecb8-c8c1-45fd-bb85-4b42a6b8ed2b --- # Compiler Error C2829 -'operator operator' cannot have a variable parameter list +> 'operator operator' cannot have a variable parameter list + +## Remarks Only two operators can take variable parameter lists: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2830.md b/docs/error-messages/compiler-errors-2/compiler-error-c2830.md index 6141a2a5023..44f5c71e35d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2830.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2830.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2830" title: "Compiler Error C2830" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2830" +ms.date: 11/04/2016 f1_keywords: ["C2830"] helpviewer_keywords: ["C2830"] -ms.assetid: 91607d2d-6aab-4c1b-b253-a7b8ec37760e --- # Compiler Error C2830 -only placement parameters to 'operator new' can have default values +> only placement parameters to 'operator new' can have default values + +## Remarks The standard formal parameters for [operator new](../../standard-library/new-operators.md#op_new) cannot have default values. Only user-defined placement parameters can specify defaults. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2831.md b/docs/error-messages/compiler-errors-2/compiler-error-c2831.md index 9512ca8f412..bc27fed8ecd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2831.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2831.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2831" title: "Compiler Error C2831" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2831" +ms.date: 11/04/2016 f1_keywords: ["C2831"] helpviewer_keywords: ["C2831"] -ms.assetid: c8c04288-0889-4265-a077-17f94cbcdcc9 --- # Compiler Error C2831 -'operator operator' cannot have default parameters +> 'operator operator' cannot have default parameters + +## Remarks Only three operators can have default parameters: @@ -18,7 +19,9 @@ Only three operators can have default parameters: - Left parenthesis ( -The following sample generates C2831: +## Example + +The following example generates C2831: ```cpp // C2831.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2833.md b/docs/error-messages/compiler-errors-2/compiler-error-c2833.md index 84e1e48a152..db4f336ded0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2833.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2833.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2833" title: "Compiler Error C2833" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2833" +ms.date: 11/04/2016 f1_keywords: ["C2833"] helpviewer_keywords: ["C2833"] -ms.assetid: b9418ce1-e2ee-4599-8959-6fde89c27569 --- # Compiler Error C2833 > 'operator *operator-name*' is not a recognized operator or type +## Remarks + The word **`operator`** must be followed by an *operator-name* that you want to override or a type you want to convert. For a list of the operators that you can define in a managed type, see [User-defined Operators](../../dotnet/user-defined-operators-cpp-cli.md). -The following sample generates C2833: +## Example + +The following example generates C2833: ```cpp // C2833.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2834.md b/docs/error-messages/compiler-errors-2/compiler-error-c2834.md index 716e1c7e5a9..32d04c4ef42 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2834.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2834.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2834" title: "Compiler Error C2834" +description: "Learn more about: Compiler Error C2834" ms.date: 06/01/2022 f1_keywords: ["C2834"] helpviewer_keywords: ["C2834"] -ms.assetid: 28f9f6eb-ab2a-4e64-aaaa-9d14f955de41 --- # Compiler Error C2834 > 'operator *operator-name*' must be globally qualified +## Remarks + The `new` and `delete` operators are tied to the class where they reside. Scope resolution cannot be used to select a version of `new` or `delete` from a different class. To implement multiple forms of the `new` or `delete` operator, create a version of the operator with extra formal parameters. This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2835.md b/docs/error-messages/compiler-errors-2/compiler-error-c2835.md index 4dbcb7c9d5a..5492c49de67 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2835.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2835.md @@ -1,18 +1,21 @@ --- -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 -user-defined conversion 'type' takes no formal parameters +> user-defined conversion 'type' takes no formal parameters + +## Remarks User-defined type conversions cannot take formal parameters. -The following sample generates C2835: +## Example + +The following example generates C2835: ```cpp // C2835.cpp @@ -22,12 +25,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-c2838.md b/docs/error-messages/compiler-errors-2/compiler-error-c2838.md index 5667a087511..d25d68cdfc3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2838.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2838.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2838" title: "Compiler Error C2838" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2838" +ms.date: 11/04/2016 f1_keywords: ["C2838"] helpviewer_keywords: ["C2838"] -ms.assetid: 176b2ad6-7a84-4019-b97e-328866054457 --- # Compiler Error C2838 -'member' : illegal qualified name in member declaration +> 'member' : illegal qualified name in member declaration + +## Remarks A class, structure, or union uses a fully qualified name to redeclare a member of another class, structure, or union. -The following sample generates C2838: +## Example + +The following example generates C2838: ```cpp // C2838.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2839.md b/docs/error-messages/compiler-errors-2/compiler-error-c2839.md index f7480b7bc45..94fe1998ec3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2839.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2839.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2839" title: "Compiler Error C2839" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2839" +ms.date: 11/04/2016 f1_keywords: ["C2839"] helpviewer_keywords: ["C2839"] -ms.assetid: e4914def-2ee1-4e2e-8951-d35f9515c2b2 --- # Compiler Error C2839 -invalid return type 'type' for overloaded 'operator ->' +> invalid return type 'type' for overloaded 'operator ->' + +## Remarks The `->` operator must return a class, struct, or union, or a reference to one. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2842.md b/docs/error-messages/compiler-errors-2/compiler-error-c2842.md index 62762894e97..b31737736aa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2842.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2842.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2842" title: "Compiler Error C2842" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2842" +ms.date: 11/04/2016 f1_keywords: ["C2842"] helpviewer_keywords: ["C2842"] -ms.assetid: 8674f08d-9f50-46ad-9229-abc6b74fa0e5 --- # Compiler Error C2842 @@ -18,7 +17,7 @@ For more information, see [User-Defined Operators (C++/CLI)](../../dotnet/user-d ## Example -The following sample generates C2842. +The following example generates C2842. ```cpp // C2842.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2843.md b/docs/error-messages/compiler-errors-2/compiler-error-c2843.md index 14b5171ffa2..87266f66be2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2843.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2843.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2843" title: "Compiler Error C2843" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2843" +ms.date: 11/04/2016 f1_keywords: ["C2843"] helpviewer_keywords: ["C2843"] -ms.assetid: 9d3f2ac4-eea5-4fed-abeb-e752f442bfcc --- # Compiler Error C2843 -'member' : cannot take the address of a non-static data member or method of a managed or WinRT type +> 'member' : cannot take the address of a non-static data member or method of a managed or WinRT type + +## Remarks An instance is needed to take the address of nonstatic data members of a managed or WinRT class or interface. -The following sample generates C2843 and shows how to fix it: +## Example + +The following example generates C2843 and shows how to fix it: ```cpp // C2843_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2844.md b/docs/error-messages/compiler-errors-2/compiler-error-c2844.md index 5fd3a703db6..4560e90ad50 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2844.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2844.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2844" title: "Compiler Error C2844" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2844" +ms.date: 11/04/2016 f1_keywords: ["C2844"] helpviewer_keywords: ["C2844"] -ms.assetid: dcaf4cd2-21b0-4280-ae42-0a706c524d83 --- # Compiler Error C2844 -'member' : cannot be a member of interface 'interface' +> 'member' : cannot be a member of interface 'interface' + +## Remarks An [interface class](../../extensions/interface-class-cpp-component-extensions.md) cannot contain a data member unless it is also a property. Anything other than a property or member function is not allowed in an interface. Furthermore, constructors, destructors, and operators are not allowed. -The following sample generates C2844: +## Example + +The following example generates C2844: ```cpp // C2844a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2845.md b/docs/error-messages/compiler-errors-2/compiler-error-c2845.md index 16511963892..772b3afbfc4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2845.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2845.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2845" title: "Compiler Error C2845" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2845" +ms.date: 11/04/2016 f1_keywords: ["C2845"] helpviewer_keywords: ["C2845"] -ms.assetid: 31b28ee9-978f-403b-94d8-dbaacd24cce0 --- # Compiler Error C2845 -'operator' : pointer arithmetic not allowed on this type +> 'operator' : pointer arithmetic not allowed on this type + +## Remarks You cannot increment the pointer to a managed class. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2846.md b/docs/error-messages/compiler-errors-2/compiler-error-c2846.md index a33ecf9a560..a7e56fc19f6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2846.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2846.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2846" title: "Compiler Error C2846" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2846" +ms.date: 11/04/2016 f1_keywords: ["C2846"] helpviewer_keywords: ["C2846"] -ms.assetid: bc090ec2-5410-4112-9ec6-261325374375 --- # Compiler Error C2846 -'constructor' : an interface cannot have a constructor +> 'constructor' : an interface cannot have a constructor + +## Remarks A Visual C++ [interface](../../cpp/interface.md) cannot have a constructor. -The following sample generates C2846: +## Example + +The following example generates C2846: ```cpp // C2846.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2847.md b/docs/error-messages/compiler-errors-2/compiler-error-c2847.md index ef48d9496b8..93cc7ebfb76 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2847.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2847.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2847" title: "Compiler Error C2847" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2847" +ms.date: 11/04/2016 f1_keywords: ["C2847"] helpviewer_keywords: ["C2847"] -ms.assetid: 9ad9a0e0-8b16-49d9-a5be-f8eda2372aa9 --- # Compiler Error C2847 -cannot apply sizeof to managed or WinRT type 'class' +> cannot apply sizeof to managed or WinRT type 'class' + +## Remarks The [sizeof](../../cpp/sizeof-operator.md) operator gets the value of an object at compile time. The size of a managed or WinRT class, interface, or value type is dynamic and so cannot be known at compile time. -For example, the following sample generates C2847: +## Example + +For example, the following example generates C2847: ```cpp // C2847.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2849.md b/docs/error-messages/compiler-errors-2/compiler-error-c2849.md index 529a6699481..4b2afd8008a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2849.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2849.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2849" title: "Compiler Error C2849" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2849" +ms.date: 11/04/2016 f1_keywords: ["C2849"] helpviewer_keywords: ["C2849"] -ms.assetid: e28f6b3e-e0e7-4f92-b006-ebaa81d368e6 --- # Compiler Error C2849 -'destructor' : an interface cannot have a destructor +> 'destructor' : an interface cannot have a destructor + +## Remarks A Visual C++ [interface](../../cpp/interface.md) cannot have a destructor. -The following sample generates C2849: +## Example + +The following example generates C2849: ```cpp // C2849.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2850.md b/docs/error-messages/compiler-errors-2/compiler-error-c2850.md index 86e1d28646f..a5720a6a0bb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2850.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2850.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2850" title: "Compiler Error C2850" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2850" +ms.date: 11/04/2016 f1_keywords: ["C2850"] helpviewer_keywords: ["C2850"] -ms.assetid: f3efe86c-4168-4e76-a133-3f8314c69f51 --- # Compiler Error C2850 -'construct' : only allowed at file scope; may not be in a nested construct +> 'construct' : only allowed at file scope; may not be in a nested construct + +## Remarks Constructs, such as some pragmas, can only appear at global scope. -The following sample generates C2850: +## Example + +The following example generates C2850: ```cpp // C2850.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2854.md b/docs/error-messages/compiler-errors-2/compiler-error-c2854.md index f4c3ab89deb..881fa57914a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2854.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2854.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2854" title: "Compiler Error C2854" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2854" +ms.date: 11/04/2016 f1_keywords: ["C2854"] helpviewer_keywords: ["C2854"] -ms.assetid: 917fec9c-790a-4149-8dfc-00d17a09199c --- # Compiler Error C2854 -syntax error in #pragma hdrstop +> syntax error in #pragma hdrstop + +## Remarks The `#pragma hdrstop` gives an invalid filename. The pragma can be followed by an optional filename in parentheses and quotation marks: -The following sample generates C2854: +## Example + +The following example generates C2854: ```cpp // C2854.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2855.md b/docs/error-messages/compiler-errors-2/compiler-error-c2855.md index c67e56ab236..03760f6647a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2855.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2855.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Error C2855" title: "Compiler Error C2855" +description: "Learn more about: Compiler Error C2855" ms.date: 02/16/2021 f1_keywords: ["C2855"] helpviewer_keywords: ["C2855"] @@ -9,10 +9,10 @@ helpviewer_keywords: ["C2855"] > command-line option '*option*' inconsistent with precompiled header -This error occurs when a command-line option differs from the options used to create the precompiled header. - ## Remarks +This error occurs when a command-line option differs from the options used to create the precompiled header. + Error C2855 can occur when you make an incremental build after changing a compiler option. It can also happen if you set specific compiler options for individual source files. To resolve this error, regenerate the precompiled header by using the specified command-line option. To regenerate the precompiled header, build the associated source file. For example, projects created by a Visual Studio template usually create a source file named *`pch.cpp`* to generate the precompiled header. (In older versions of Visual Studio, this file is named *`stdafx.cpp`*.) In other projects, the source file to rebuild is the one built by using the [`/Yc` (Create precompiled header file)](../../build/reference/yc-create-precompiled-header-file.md) compiler option. We recommend you rebuild your entire project after making a change to the precompiled header. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2856.md b/docs/error-messages/compiler-errors-2/compiler-error-c2856.md index 900d8c6d6a8..1a6f8ec7dd4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2856.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2856.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2856" title: "Compiler Error C2856" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2856" +ms.date: 11/04/2016 f1_keywords: ["C2856"] helpviewer_keywords: ["C2856"] -ms.assetid: fe616c51-124e-49e3-9dd8-883ec1660680 --- # Compiler Error C2856 -\#pragma hdrstop cannot be inside an #if block +> #pragma hdrstop cannot be inside an #if block + +## Remarks The `hdrstop` pragma cannot be placed inside the body of a conditional compilation block. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2857.md b/docs/error-messages/compiler-errors-2/compiler-error-c2857.md index 8b8572462b6..f81d9f06527 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2857.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2857.md @@ -1,26 +1,25 @@ --- -description: "Learn more about: Compiler Error C2857" title: "Compiler Error C2857" -ms.date: "09/13/2018" +description: "Learn more about: Compiler Error C2857" +ms.date: 09/13/2018 f1_keywords: ["C2857"] helpviewer_keywords: ["C2857"] -ms.assetid: b57302bd-58ec-45ae-992a-1e282d5eeccc --- # Compiler Error C2857 > '#include' statement specified with the /Yc*filename* command-line option was not found in the source file -The [/Yc](../../build/reference/yc-create-precompiled-header-file.md) option specifies the name of an include file that is not included in the source file being compiled. - ## Remarks +The [/Yc](../../build/reference/yc-create-precompiled-header-file.md) option specifies the name of an include file that is not included in the source file being compiled. + When you use the **/Yc**filename option on a source file to create a precompiled header (PCH) file, that source file must include the *filename* header file. Every file included by the source file, up to and including the specified *filename*, is included in the PCH file. In other source files compiled by using the **/Yu**filename option to use the PCH file, an include of *filename* must be the first non-comment line in the file. The compiler ignores anything in the source file before this include. This error can be caused by an `#include "filename"` statement in a conditional compilation block that is not compiled in your PCH source file. ## Example -In typical usage, one source file in your project is designated as the PCH source file, and one header file is used as the PCH header file. A typical PCH header file has all of the library headers used in your project, but not local headers that are still under development. In this sample, the PCH header file is named *my_pch.h*. +In typical usage, one source file in your project is designated as the PCH source file, and one header file is used as the PCH header file. A typical PCH header file has all of the library headers used in your project, but not local headers that are still under development. In this example, the PCH header file is named *my_pch.h*. ```cpp // my_pch.h diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2858.md b/docs/error-messages/compiler-errors-2/compiler-error-c2858.md index 5c73c903ae3..5779b92df96 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2858.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2858.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2858" title: "Compiler Error C2858" +description: "Learn more about: Compiler Error C2858" ms.date: 06/01/2022 f1_keywords: ["C2858"] helpviewer_keywords: ["C2858"] -ms.assetid: 1fb1d770-307e-476e-9984-a1d8f8ce2820 --- # Compiler Error C2858 > command-line option '/Yc (/Fd*filename1*)' inconsistent with precompiled header, which used '/Fd*filename2*' +## Remarks + The program database specified by the Use Precompiled Header ([`/Yu`](../../build/reference/yu-use-precompiled-header-file.md)) option is not the one specified by the previous Create Precompiled Header ([`/Yc`](../../build/reference/yc-create-precompiled-header-file.md)) option. This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2859.md b/docs/error-messages/compiler-errors-2/compiler-error-c2859.md index 10dbcd0e841..5d2a5e941e2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2859.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2859.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2859" title: "Compiler Error C2859" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2859" +ms.date: 11/04/2016 f1_keywords: ["C2859"] helpviewer_keywords: ["C2859"] -ms.assetid: fcfbc58d-08f6-4752-9688-8aaac517e684 --- # Compiler Error C2859 -filename is not the type file that was used when this precompiled header was created, recreate the precompiled header. +> filename is not the type file that was used when this precompiled header was created, recreate the precompiled header. + +## Remarks The project database and precompiled header files must be created together to ensure consistent information. Rebuild the project to recreate the precompiled header. 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 9bd2b0bc536..3ac684a3f24 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,26 @@ --- -description: "Learn more about: Compiler Error C2860" title: "Compiler Error C2860" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2860" +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)' + +## Remarks + +A function parameter cannot be of type **`void`**. -Type **`void`** cannot be used as an argument type with other arguments. +## Example -The following sample generates C2860: +The following example 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-c2861.md b/docs/error-messages/compiler-errors-2/compiler-error-c2861.md index 2a03308508a..eeba808fa07 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2861.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2861.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2861" title: "Compiler Error C2861" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2861" +ms.date: 11/04/2016 f1_keywords: ["C2861"] helpviewer_keywords: ["C2861"] -ms.assetid: 012bb44d-6c9b-4def-b54e-b19f1f8ddd1b --- # Compiler Error C2861 -'function name' : an interface member function cannot be defined +> 'function name' : an interface member function cannot be defined + +## Remarks The compiler encountered the interface keyword or deduced a struct as an interface but then found a member function definition. An interface cannot contain a definition for a member function. ## Example -The following sample generates C2861: +The following example generates C2861: ```cpp // C2861.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2862.md b/docs/error-messages/compiler-errors-2/compiler-error-c2862.md index 1e293348d28..ccef63bbcf6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2862.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2862.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2862" title: "Compiler Error C2862" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2862" +ms.date: 11/04/2016 f1_keywords: ["C2862"] helpviewer_keywords: ["C2862"] -ms.assetid: c04d8499-b799-48a1-9fb4-7902a0b0ac8e --- # Compiler Error C2862 -'interface' : an interface can only have public members +> 'interface' : an interface can only have public members + +## Remarks Protected and private members may be accessed only from other member functions. Such members are no use in an interface, since it may not provide implementations for any of its members. -The following sample will generate C2862: +## Example + +The following example will generate C2862: ```cpp // C2862.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2863.md b/docs/error-messages/compiler-errors-2/compiler-error-c2863.md index 5df82ef31b2..dbd762cdf7e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2863.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2863.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2863" title: "Compiler Error C2863" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2863" +ms.date: 11/04/2016 f1_keywords: ["C2863"] helpviewer_keywords: ["C2863"] -ms.assetid: 32561d67-a795-486b-b3b6-4b90a1acb176 --- # Compiler Error C2863 -'interface' : an interface cannot have friends +> 'interface' : an interface cannot have friends + +## Remarks Declaring friends on an interface is not allowed. -The following sample generates C2863: +## Example + +The following example generates C2863: ```cpp // C2863.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2864.md b/docs/error-messages/compiler-errors-2/compiler-error-c2864.md index 9dd8b4fe30e..950b3a8bacb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2864.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2864.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2864" title: "Compiler Error C2864" +description: "Learn more about: Compiler Error C2864" ms.date: 10/04/2019 f1_keywords: ["C2864"] helpviewer_keywords: ["C2864"] -ms.assetid: d0ca2ad9-90a6-4aef-8511-98a3b414c102 --- # Compiler Error C2864 @@ -16,7 +15,7 @@ To initialize a **`static`** data member that's defined as **`volatile`**, non-* ## Example -This sample generates C2864: +This example generates C2864: ```cpp // C2864.cpp @@ -32,7 +31,7 @@ private: }; ``` -This sample shows how to fix C2864: +This example shows how to fix C2864: ```cpp // C2864b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2865.md b/docs/error-messages/compiler-errors-2/compiler-error-c2865.md index 798e14910ec..1f9f9040dfc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2865.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2865.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2865" title: "Compiler Error C2865" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2865" +ms.date: 11/04/2016 f1_keywords: ["C2865"] helpviewer_keywords: ["C2865"] -ms.assetid: 973eb6a0-c99a-4d25-b3e5-fe0539794d77 --- # Compiler Error C2865 -'function' : illegal comparison for handle_or_pointer +> 'function' : illegal comparison for handle_or_pointer + +## Remarks You can compare references to [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md) or managed reference types only for equality to see if they refer to the same object (==) or to different objects (!=). diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2867.md b/docs/error-messages/compiler-errors-2/compiler-error-c2867.md index 5a5373bcccf..6f82ffe3058 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2867.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2867.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2867" title: "Compiler Error C2867" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2867" +ms.date: 11/04/2016 f1_keywords: ["C2867"] helpviewer_keywords: ["C2867"] -ms.assetid: 63be26b2-d9ab-4f3d-a8b7-981ce3e4d6b9 --- # Compiler Error C2867 -'identifier' : is not a namespace +> 'identifier' : is not a namespace + +## Remarks A **`using`** directive is applied to something other than a namespace. -The following sample generates C2867: +## Example + +The following example generates C2867: ```cpp // C2867.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2868.md b/docs/error-messages/compiler-errors-2/compiler-error-c2868.md index 3c9e74506eb..aace8ea2a24 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2868.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2868.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2868" title: "Compiler Error C2868" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2868" +ms.date: 11/04/2016 f1_keywords: ["C2868"] helpviewer_keywords: ["C2868"] -ms.assetid: 6ff5837b-e66d-44d1-9d17-80af35e08d08 --- # Compiler Error C2868 > '*identifier*' : illegal syntax for using-declaration; expected qualified-name +## Remarks + A [using declaration](../../cpp/using-declaration.md) requires a *qualified name*, a scope-operator (`::`) separated sequence of namespace, class, or enumeration names that ends with the identifier name. A single scope resolution operator may be used to introduce a name from the global namespace. ## Example -The following sample generates C2868 and also shows correct usage: +The following example generates C2868 and also shows correct usage: ```cpp // C2868.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2869.md b/docs/error-messages/compiler-errors-2/compiler-error-c2869.md index e42f10940ac..74243dc953f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2869.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2869.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2869" title: "Compiler Error C2869" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2869" +ms.date: 11/04/2016 f1_keywords: ["C2869"] helpviewer_keywords: ["C2869"] -ms.assetid: 6e30c001-47f3-4101-b9f1-cc542c9fffae --- # Compiler Error C2869 -'name' : has already been defined to be a namespace +> 'name' : has already been defined to be a namespace + +## Remarks You cannot reuse a name already used as a namespace. -The following sample generates C2869: +## Example + +The following example generates C2869: ```cpp // C2869.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2870.md b/docs/error-messages/compiler-errors-2/compiler-error-c2870.md index 47ea940abcd..0aa1c8d1ccd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2870.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2870.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2870" title: "Compiler Error C2870" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2870" +ms.date: 11/04/2016 f1_keywords: ["C2870"] helpviewer_keywords: ["C2870"] -ms.assetid: 80523ee9-1fd3-4dc4-8a77-5083deb99066 --- # Compiler Error C2870 -'name' : a namespace definition must appear either at file scope or immediately within another namespace definition +> 'name' : a namespace definition must appear either at file scope or immediately within another namespace definition + +## Remarks You defined namespace `name` incorrectly. Namespaces must be defined at file scope (outside all blocks and classes) or immediately within another namespace. -The following sample generates C2870: +## Example + +The following example generates C2870: ```cpp // C2870.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2871.md b/docs/error-messages/compiler-errors-2/compiler-error-c2871.md index 2e451cbade7..c3261549f3c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2871.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2871.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2871" title: "Compiler Error C2871" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2871" +ms.date: 11/04/2016 f1_keywords: ["C2871"] helpviewer_keywords: ["C2871"] -ms.assetid: 44aeb84d-61f0-45e0-8dad-22a3cd46b7f8 --- # Compiler Error C2871 -'name' : a namespace with this name does not exist +> 'name' : a namespace with this name does not exist + +## Remarks This error will occur when you pass an identifier that is not a namespace to a [using](../../cpp/namespaces-cpp.md#using_directives) directive. ## Example -The following sample generates C2871: +The following example generates C2871: ```cpp // C2871.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2872.md b/docs/error-messages/compiler-errors-2/compiler-error-c2872.md index 8c90fb01c05..9e5f59ead02 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2872.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2872.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2872" title: "Compiler Error C2872" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2872" +ms.date: 11/04/2016 f1_keywords: ["C2872"] helpviewer_keywords: ["C2872"] -ms.assetid: c619ef97-6e0e-41d7-867c-f8d28a07d553 --- # Compiler Error C2872 -'*symbol*' : ambiguous symbol +> '*symbol*' : ambiguous symbol + +## Remarks The compiler cannot determine which symbol you are referring to. More than one symbol with the specified name is in scope. See the notes following the error message for the file locations and declarations the compiler found for the ambiguous symbol. To fix this issue, you can fully qualify the ambiguous symbol by using its namespace, for example, `std::byte` or `::byte`. You can also use a [namespace alias](../../cpp/namespaces-cpp.md#namespace_aliases) to give an included namespace a convenient short name for use when disambiguating symbols in your source code. @@ -22,7 +23,7 @@ C2872 can occur in Visual Studio 2013 due to a conflict between the `Windows::Fo ## Example -The following sample generates C2872, because an ambiguous reference is made to a variable named `i`; two variables with the same name are in scope: +The following example generates C2872, because an ambiguous reference is made to a variable named `i`; two variables with the same name are in scope: ```cpp // C2872.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2873.md b/docs/error-messages/compiler-errors-2/compiler-error-c2873.md index f68141e9cb5..befff3cf35f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2873.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2873.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2873" title: "Compiler Error C2873" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2873" +ms.date: 11/04/2016 f1_keywords: ["C2873"] helpviewer_keywords: ["C2873"] -ms.assetid: 7a10036b-400e-4364-bd2f-dcd7370c5e28 --- # Compiler Error C2873 -'symbol' : symbol cannot be used in a using-declaration +> 'symbol' : symbol cannot be used in a using-declaration + +## Remarks A **`using`** directive is missing a [namespace](../../cpp/namespaces-cpp.md) keyword. This causes the compiler to misinterpret the code as a [using declaration](../../cpp/using-declaration.md) rather than a [using directive](../../cpp/namespaces-cpp.md#using_directives). diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2874.md b/docs/error-messages/compiler-errors-2/compiler-error-c2874.md index f77e52f6aa5..2903d83b7e9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2874.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2874.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2874" title: "Compiler Error C2874" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2874" +ms.date: 11/04/2016 f1_keywords: ["C2874"] helpviewer_keywords: ["C2874"] -ms.assetid: b54fa9d8-8df5-40d9-9b3b-aa3e9dd6a3be --- # Compiler Error C2874 -using-declaration causes a multiple declaration of 'symbol' +> using-declaration causes a multiple declaration of 'symbol' + +## Remarks The declaration causes the same item to be defined twice. -The following sample generates C2874: +## Example + +The following example generates C2874: ```cpp // C2874.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2875.md b/docs/error-messages/compiler-errors-2/compiler-error-c2875.md index ed6b53506d0..2a2e0688f85 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2875.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2875.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2875" title: "Compiler Error C2875" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2875" +ms.date: 11/04/2016 f1_keywords: ["C2875"] helpviewer_keywords: ["C2875"] -ms.assetid: d589fc0c-08b2-4a79-bc0e-dca5eb80bdd5 --- # Compiler Error C2875 > using-declaration causes a multiple declaration of 'class::identifier' +## Remarks + The declaration causes the same item to be defined twice. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2875: +## Example + +The following example generates C2875: ```cpp // C2875.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2876.md b/docs/error-messages/compiler-errors-2/compiler-error-c2876.md index 4aa48c784ad..d102a7f0192 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2876.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2876.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2876" title: "Compiler Error C2876" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2876" +ms.date: 11/04/2016 f1_keywords: ["C2876"] helpviewer_keywords: ["C2876"] -ms.assetid: 8b674bf1-f9f4-4a8e-8127-e884c1d1708f --- # Compiler Error C2876 -'class::symbol' : not all overloads are accessible +> 'class::symbol' : not all overloads are accessible + +## Remarks All overloaded forms of a function in a base class must be accessible to the derived class. -The following sample generates C2876: +## Example + +The following example generates C2876: ```cpp // C2876.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2877.md b/docs/error-messages/compiler-errors-2/compiler-error-c2877.md index dfe1367cf52..62a17b4f704 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2877.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2877.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2877" title: "Compiler Error C2877" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2877" +ms.date: 11/04/2016 f1_keywords: ["C2877"] helpviewer_keywords: ["C2877"] -ms.assetid: 0b54837e-fcae-4d90-9658-623250435e24 --- # Compiler Error C2877 -'symbol' is not accessible from 'class' +> 'symbol' is not accessible from 'class' + +## Remarks All members derived from a base class must be accessible in the derived class. -The following sample generates C2877: +## Example + +The following example generates C2877: ```cpp // C2877.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2878.md b/docs/error-messages/compiler-errors-2/compiler-error-c2878.md index cc6a1320dac..d5c043adce3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2878.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2878.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2878" title: "Compiler Error C2878" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2878" +ms.date: 11/04/2016 f1_keywords: ["C2878"] helpviewer_keywords: ["C2878"] -ms.assetid: 83ee3de1-f554-49e8-a840-1f550cee7f69 --- # Compiler Error C2878 -'name' : a namespace or class of this name does not exist +> 'name' : a namespace or class of this name does not exist + +## Remarks You made reference to a namespace or class that is not defined. -The following sample generates C2878: +## Example + +The following example generates C2878: ```cpp // C2878.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2879.md b/docs/error-messages/compiler-errors-2/compiler-error-c2879.md index 90cfabfe639..0baee26805f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2879.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2879.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2879" title: "Compiler Error C2879" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2879" +ms.date: 11/04/2016 f1_keywords: ["C2879"] helpviewer_keywords: ["C2879"] -ms.assetid: ac92b645-2394-49de-8632-43d44e0553ed --- # Compiler Error C2879 -'symbol' : only an existing namespace can be given an alternative name by a namespace alias definition +> 'symbol' : only an existing namespace can be given an alternative name by a namespace alias definition + +## Remarks You cannot create a [namespace alias](../../cpp/namespaces-cpp.md#namespace_aliases) to a symbol other than a namespace. -The following sample generates C2879: +## Example + +The following example generates C2879: ```cpp // C2879.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2881.md b/docs/error-messages/compiler-errors-2/compiler-error-c2881.md index 45d454a253a..b454691769b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2881.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2881.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2881" title: "Compiler Error C2881" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2881" +ms.date: 11/04/2016 f1_keywords: ["C2881"] helpviewer_keywords: ["C2881"] -ms.assetid: b49c63c2-b064-4d4b-a75e-ddd2af947522 --- # Compiler Error C2881 -'namespace1' : is already used as an alias for 'namespace2' +> 'namespace1' : is already used as an alias for 'namespace2' + +## Remarks You cannot use the same name as an alias for two namespaces. -The following sample generates C2881: +## Example + +The following example generates C2881: ```cpp // C2881.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2882.md b/docs/error-messages/compiler-errors-2/compiler-error-c2882.md index e3a0d257e3e..a9197ff4b8f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2882.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2882.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2882" title: "Compiler Error C2882" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2882" +ms.date: 11/04/2016 f1_keywords: ["C2882"] helpviewer_keywords: ["C2882"] -ms.assetid: 617018ee-5a0d-4b8d-9612-77e8ae52679b --- # Compiler Error C2882 -'name' : illegal use of namespace identifier in expression +> 'name' : illegal use of namespace identifier in expression + +## Remarks You tried to use the name of a namespace in an expression. -The following sample generates C2882: +## Example + +The following example generates C2882: ```cpp // C2882.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2883.md b/docs/error-messages/compiler-errors-2/compiler-error-c2883.md index e503e3d6ad6..8f99b1c5f3e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2883.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2883.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2883" title: "Compiler Error C2883" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2883" +ms.date: 11/04/2016 f1_keywords: ["C2883"] helpviewer_keywords: ["C2883"] -ms.assetid: 5c6d689d-ed42-41ad-b5c0-e9c2e0b8c356 --- # Compiler Error C2883 -'name' : function declaration conflicts with 'identifier' introduced by using-declaration +> 'name' : function declaration conflicts with 'identifier' introduced by using-declaration + +## Remarks You tried to define a function more than once. The first definition was made from a namespace with a **`using`** declaration. The second was a local definition. -The following sample generates C2883: +## Example + +The following example generates C2883: ```cpp // C2883.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2884.md b/docs/error-messages/compiler-errors-2/compiler-error-c2884.md index fedd4259709..246efeaf563 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2884.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2884.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2884" title: "Compiler Error C2884" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2884" +ms.date: 11/04/2016 f1_keywords: ["C2884"] helpviewer_keywords: ["C2884"] -ms.assetid: 8b4d43e3-3fb5-4360-86c8-de59d8736d4f --- # Compiler Error C2884 -'name' : introduced by using-declaration conflicts with local function 'function' +> 'name' : introduced by using-declaration conflicts with local function 'function' + +## Remarks You tried to define a function more than once. The first definition is a local definition. The second is from a namespace with a **`using`** declaration. -The following sample generates C2884: +## Example + +The following example generates C2884: ```cpp // C2884.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2885.md b/docs/error-messages/compiler-errors-2/compiler-error-c2885.md index 018ee3660e2..05e2cc3e2a1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2885.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2885.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2885" title: "Compiler Error C2885" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2885" +ms.date: 11/04/2016 f1_keywords: ["C2885"] helpviewer_keywords: ["C2885"] -ms.assetid: 7743e5f3-a034-44b4-9ee8-5a6254c27f8c --- # Compiler Error C2885 -'class::identifier' : not a valid using-declaration at non-class scope +> 'class::identifier' : not a valid using-declaration at non-class scope + +## Remarks You used a [using](../../cpp/using-declaration.md) declaration incorrectly. @@ -16,7 +17,7 @@ This error can be generated as a result of compiler conformance work that was do ## Examples -The following sample generates C2885. +The following example generates C2885. ```cpp // C2885.cpp @@ -47,7 +48,7 @@ int main () { If you use the **`using`** keyword with a class member, C++ requires you to define that member inside another class (a derived class). -The following sample generates C2885. +The following example generates C2885. ```cpp // C2885_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2886.md b/docs/error-messages/compiler-errors-2/compiler-error-c2886.md index b93a4b5c767..485fb01d635 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2886.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2886.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2886" title: "Compiler Error C2886" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2886" +ms.date: 11/04/2016 f1_keywords: ["C2886"] helpviewer_keywords: ["C2886"] -ms.assetid: c01588a1-484c-4dc9-a3f1-f900c6e44543 --- # Compiler Error C2886 -'class::identifier' : symbol cannot be used in a member using-declaration +> 'class::identifier' : symbol cannot be used in a member using-declaration + +## Remarks A **`using`** declaration uses a symbol, such as a namespace name. A **`using`** declaration is for declaring base class members. -The following sample generates C2886: +## Example + +The following example generates C2886: ```cpp // C2886.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2888.md b/docs/error-messages/compiler-errors-2/compiler-error-c2888.md index cfc30eecb95..cc6421b7442 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2888.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2888.md @@ -1,18 +1,21 @@ --- -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 -'identifier' : symbol cannot be defined within namespace 'namespace' +> 'identifier' : symbol cannot be defined within namespace 'namespace' + +## Remarks A symbol belonging to namespace A must be defined in a namespace that encloses A. -The following sample generates C2888: +## Example + +The following example generates C2888: ```cpp // C2888.cpp @@ -23,7 +26,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-c2890.md b/docs/error-messages/compiler-errors-2/compiler-error-c2890.md index d17bdde458f..85a41dc4631 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2890.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2890.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2890" title: "Compiler Error C2890" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2890" +ms.date: 11/04/2016 f1_keywords: ["C2890"] helpviewer_keywords: ["C2890"] -ms.assetid: 49147375-182c-42b1-b170-f475cd436d47 --- # Compiler Error C2890 -'class' : a ref class can only have one non-interface base class +> 'class' : a ref class can only have one non-interface base class + +## Remarks A reference class can only have one base class. -The following sample generates C2890: +## Example + +The following example generates C2890: ```cpp // C2890.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2891.md b/docs/error-messages/compiler-errors-2/compiler-error-c2891.md index e092c0a18bf..d4068c29352 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2891.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2891.md @@ -1,24 +1,29 @@ --- -description: "Learn more about: Compiler Error C2891" title: "Compiler Error C2891" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2891" +ms.date: 11/04/2016 f1_keywords: ["C2891"] helpviewer_keywords: ["C2891"] -ms.assetid: e12cfb2d-df45-4b0d-b155-c51d17e812fa --- # Compiler Error C2891 -'parameter' : cannot take the address of a template parameter +> 'parameter' : cannot take the address of a template parameter -You can't take the address of a template parameter unless it is an lvalue. Type parameters are not lvalues because they have no address. Non-type values in template parameter lists that are not lvalues also do not have an address. This is an example of code that causes Compiler Error C2891, because the value passed as the template parameter is a compiler-generated copy of the template argument. +## Remarks -``` +You can't take the address of a template parameter unless it is an lvalue. Type parameters are not lvalues because they have no address. Non-type values in template parameter lists that are not lvalues also do not have an address. + +## Example + +This is an example of code that causes Compiler Error C2891, because the value passed as the template parameter is a compiler-generated copy of the template argument. + +```cpp template int* f() { return &i; } ``` Template parameters that are lvalues, such as reference types, can have their address taken. -``` +```cpp template int* f() { return &r; } ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2892.md b/docs/error-messages/compiler-errors-2/compiler-error-c2892.md index 4ae86e0ab38..9ac778b80eb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2892.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2892.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2892" title: "Compiler Error C2892" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2892" +ms.date: 11/04/2016 f1_keywords: ["C2892"] helpviewer_keywords: ["C2892"] -ms.assetid: c22a5084-2f50-42c2-a56b-6dfe5442edc9 --- # Compiler Error C2892 -local class shall not have member templates +> local class shall not have member templates + +## Remarks Templated member functions are not valid in a class that is defined in a function. -The following sample generates C2892: +## Example + +The following example generates C2892: ```cpp // C2892.cpp 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 7e1fab4903a..2e416b3f4fa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2893.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2893.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2893" title: "Compiler Error C2893" -ms.date: "11/04/2016" +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 -Failed to specialize function template 'template name' +> Failed to specialize function template 'template name' + +## Remarks The compiler failed to specialize a function template. There can be many causes for this error. @@ -16,12 +17,12 @@ In general, the way to resolve a C2893 error is to review the function's signatu ## Example -C2893 occurs because `f`'s template parameter `T` is deduced to be `std::map`, but `std::map` has no member `data_type` (`T::data_type` can not be instantiated with `T = std::map`.). The following sample generates C2893. +C2893 occurs because `f`'s template parameter `T` is deduced to be `std::map`, but `std::map` has no member `data_type` (`T::data_type` can not be instantiated with `T = std::map`.). The following example generates C2893. ```cpp // C2893.cpp // compile with: /c /EHsc -#include +#include using namespace std; class MyClass {}; diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2894.md b/docs/error-messages/compiler-errors-2/compiler-error-c2894.md index 1d4ddc374de..0e16df5bc87 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2894.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2894.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2894" title: "Compiler Error C2894" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2894" +ms.date: 11/04/2016 f1_keywords: ["C2894"] helpviewer_keywords: ["C2894"] -ms.assetid: 4e250579-2b59-4993-a6f4-49273e7ecf06 --- # Compiler Error C2894 -templates cannot be declared to have 'C' linkage +> templates cannot be declared to have 'C' linkage + +## Remarks This error can be caused by a template defined inside an `extern "C"` block. -The following sample generates C2894: +## Examples + +The following example generates C2894: ```cpp // C2894.cpp @@ -23,7 +26,7 @@ extern "C" { } ``` -The following sample generates C2894: +The following example generates C2894: ```cpp // C2894b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2896.md b/docs/error-messages/compiler-errors-2/compiler-error-c2896.md index 32db06f54ff..b46ff6e8c4d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2896.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2896.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2896" title: "Compiler Error C2896" +description: "Learn more about: Compiler Error C2896" ms.date: 06/01/2022 f1_keywords: ["C2896"] helpviewer_keywords: ["C2896"] -ms.assetid: b600407b-cb05-42e3-9069-2aa6960f0eaa --- # Compiler Error C2896 > '*function1*' : cannot use function template '*function2*' as argument +## Remarks + A function template can't be an argument to another function template. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2896: +## Examples + +The following example generates C2896: ```cpp // C2896.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2897.md b/docs/error-messages/compiler-errors-2/compiler-error-c2897.md index f68c4fe3304..3ecd2efb034 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2897.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2897.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2897" title: "Compiler Error C2897" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2897" +ms.date: 11/04/2016 f1_keywords: ["C2897"] helpviewer_keywords: ["C2897"] -ms.assetid: a88349e2-823f-42a0-8660-0653b677afa4 --- # Compiler Error C2897 -a destructor/finalizer cannot be a function template +> a destructor/finalizer cannot be a function template + +## Remarks Destructors or finalizers cannot be overloaded, so declaring a destructor as a template (which would define a set of destructors) is not allowed. ## Examples -The following sample generates C2897. +The following example generates C2897. ```cpp // C2897.cpp @@ -25,7 +26,7 @@ public: }; ``` -The following sample generates C2897. +The following example generates C2897. ```cpp // C2897_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2898.md b/docs/error-messages/compiler-errors-2/compiler-error-c2898.md index f4dd5343894..2a75f55d76f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2898.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2898.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Compiler Error C2898" title: "Compiler Error C2898" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2898" +ms.date: 11/04/2016 f1_keywords: ["C2898"] helpviewer_keywords: ["C2898"] -ms.assetid: 68466e11-2541-4f6b-b772-13a642f30dfb --- # Compiler Error C2898 -'declaration' : member function templates cannot be virtual +> 'declaration' : member function templates cannot be virtual + +## Example -The following sample generates C2898: +The following example generates C2898: ```cpp // C2898.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2902.md b/docs/error-messages/compiler-errors-2/compiler-error-c2902.md index 1769f12a7de..4c05069ed3d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2902.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2902.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2902" title: "Compiler Error C2902" +description: "Learn more about: Compiler Error C2902" ms.date: 06/01/2022 f1_keywords: ["C2902"] helpviewer_keywords: ["C2902"] -ms.assetid: 89d78d0e-78e5-4c2c-a0f9-a60110e9395e --- # Compiler Error C2902 > '*token*' : unexpected token following '*template*', identifier expected +## Remarks + The token following the keyword **`template`** was not an identifier. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2902: +## Examples + +The following example generates C2902: ```cpp // C2902.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2903.md b/docs/error-messages/compiler-errors-2/compiler-error-c2903.md index 4b8619c11ef..0024b394e0d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2903.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2903.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2903" title: "Compiler Error C2903" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2903" +ms.date: 11/04/2016 f1_keywords: ["C2903"] helpviewer_keywords: ["C2903"] -ms.assetid: bf6b223f-4921-48c7-82b9-ff318b42c801 --- # Compiler Error C2903 -'identifier' : symbol is neither a class template nor a function template +> 'identifier' : symbol is neither a class template nor a function template + +## Remarks Code attempts explicit instantiation of something that is not a template. -The following sample generates C2903: +## Examples + +The following example generates C2903: ```cpp // C2903.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2904.md b/docs/error-messages/compiler-errors-2/compiler-error-c2904.md index c499ffed634..f7193434586 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2904.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2904.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2904" title: "Compiler Error C2904" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2904" +ms.date: 11/04/2016 f1_keywords: ["C2904"] helpviewer_keywords: ["C2904"] -ms.assetid: d5802f2e-d3fc-473d-aa04-36957b4eaca5 --- # Compiler Error C2904 -'identifier' : name already used for a template in the current scope +> 'identifier' : name already used for a template in the current scope + +## Remarks Check the code for duplicate names. -The following sample generates C2904: +## Example + +The following example generates C2904: ```cpp // C2904.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2906.md b/docs/error-messages/compiler-errors-2/compiler-error-c2906.md index f48e4457855..9a081d51aa9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2906.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2906.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2906" title: "Compiler Error C2906" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2906" +ms.date: 11/04/2016 f1_keywords: ["C2906"] helpviewer_keywords: ["C2906"] -ms.assetid: 30f652f1-6af6-4a2f-a69e-a1a4876cc8c6 --- # Compiler Error C2906 -'specialization' : explicit specialization requires 'template <>' +> 'specialization' : explicit specialization requires 'template <>' + +## Remarks You must use the new syntax for explicit specialization of templates. -The following sample generates C2906: +## Example + +The following example generates C2906: ```cpp // C2906.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2908.md b/docs/error-messages/compiler-errors-2/compiler-error-c2908.md index 19d7588b5f4..c440d9f60f0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2908.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2908.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2908" title: "Compiler Error C2908" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2908" +ms.date: 11/04/2016 f1_keywords: ["C2908"] helpviewer_keywords: ["C2908"] -ms.assetid: 49cd2a21-cad8-4ba0-9a0b-3a0190d9344c --- # Compiler Error C2908 -explicit specialization; 'template' has already been instantiated +> explicit specialization; 'template' has already been instantiated + +## Remarks A specialization of the primary template occurs before the explicit specialization. -The following sample generates C2908: +## Example + +The following example generates C2908: ```cpp // C2908.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2909.md b/docs/error-messages/compiler-errors-2/compiler-error-c2909.md index 6483ee73dad..d665e604712 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2909.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2909.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2909" title: "Compiler Error C2909" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2909" +ms.date: 11/04/2016 f1_keywords: ["C2909"] helpviewer_keywords: ["C2909"] -ms.assetid: 1c9df8ae-925d-4002-a5f8-a71413c45f9e --- # Compiler Error C2909 -'identifier': explicit instantiation of function template requires return type +> 'identifier': explicit instantiation of function template requires return type + +## Remarks An explicit instantiation of a function template requires explicit specification of its return type. Implicit return type specification does not work. -The following sample generates C2909: +## Example + +The following example generates C2909: ```cpp // C2909.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2910.md b/docs/error-messages/compiler-errors-2/compiler-error-c2910.md index 1aa3cc27a3d..aa2f41b2086 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2910.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2910.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2910" title: "Compiler Error C2910" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2910" +ms.date: 11/04/2016 f1_keywords: ["C2910"] helpviewer_keywords: ["C2910"] -ms.assetid: 09c50e6a-e099-42f6-8ed6-d80e292a7a36 --- # Compiler Error C2910 -'function' : cannot be explicitly specialized +> 'function' : cannot be explicitly specialized + +## Remarks The compiler detected an attempt to explicitly specialize a function twice. -The following sample generates C2910: +## Examples + +The following example generates C2910: ```cpp // C2910.cpp @@ -26,7 +29,7 @@ template <> void S::f() {} // C2910 delete this specialization C2910 can also be generated if you try to explicitly specialize a non-template member. That is, you can only explicitly specialize a function template. -The following sample generates C2910: +The following example generates C2910: ```cpp // C2910b.cpp @@ -51,7 +54,7 @@ This error will also be generated as a result of compiler conformance work that For code will be valid in the Visual Studio .NET 2003 and Visual Studio .NET versions of Visual C++, remove `template <>`. -The following sample generates C2910: +The following example generates C2910: ```cpp // C2910c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2911.md b/docs/error-messages/compiler-errors-2/compiler-error-c2911.md index 980b21e196c..89012b64268 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2911.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2911.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2911" title: "Compiler Error C2911" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2911" +ms.date: 11/04/2016 f1_keywords: ["C2911"] helpviewer_keywords: ["C2911"] -ms.assetid: 83c7c01a-ab6a-4179-9fb0-289a9ec8d44e --- # Compiler Error C2911 -'member' : cannot be declared or defined in the current scope +> 'member' : cannot be declared or defined in the current scope + +## Remarks Inside a namespace, class, or function, you can only define a member of the same namespace, class, or function or a member that is enclosed by the same namespace, class, or function. -The following sample generates C2911: +## Example + +The following example generates C2911: ```cpp // C2911.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2912.md b/docs/error-messages/compiler-errors-2/compiler-error-c2912.md index 70fe8cd6599..3184529521a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2912.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2912.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2912" title: "Compiler Error C2912" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2912" +ms.date: 11/04/2016 f1_keywords: ["C2912"] helpviewer_keywords: ["C2912"] -ms.assetid: bd55cecd-ab1a-4636-ab8a-a00393fe7b3d --- # Compiler Error C2912 -explicit specialization 'declaration' is not a specialization of a function template +> explicit specialization 'declaration' is not a specialization of a function template + +## Remarks You cannot specialize a non-template function. -The following sample generates C2912: +## Examples + +The following example generates C2912: ```cpp // C2912.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2913.md b/docs/error-messages/compiler-errors-2/compiler-error-c2913.md index 4b9adf22edd..db8bc5ec90c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2913.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2913.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2913" title: "Compiler Error C2913" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2913" +ms.date: 11/04/2016 f1_keywords: ["C2913"] helpviewer_keywords: ["C2913"] -ms.assetid: c6cf6090-02e8-49a5-913f-5bc6f864b769 --- # Compiler Error C2913 -explicit specialization; 'declaration' is not a specialization of a class template +> explicit specialization; 'declaration' is not a specialization of a class template + +## Remarks You cannot specialize a non-template class. -The following sample generates C2913: +## Example + +The following example generates C2913: ```cpp // C2913.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2914.md b/docs/error-messages/compiler-errors-2/compiler-error-c2914.md index dc67e9f0658..89cb2921fca 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2914.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2914.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2914" title: "Compiler Error C2914" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2914" +ms.date: 11/04/2016 f1_keywords: ["C2914"] helpviewer_keywords: ["C2914"] -ms.assetid: fc6a0592-f53e-4f5a-88cb-780bbed4acf2 --- # Compiler Error C2914 -'identifier' : cannot deduce type argument as function argument is ambiguous +> 'identifier' : cannot deduce type argument as function argument is ambiguous + +## Remarks The compiler cannot determine which overloaded functions to use for a generic or template argument. -The following sample generates C2914: +## Examples + +The following example generates C2914: ```cpp // C2914.cpp @@ -25,7 +28,7 @@ void h() { g(f); } // C2914 // void h() { g(f); } ``` -C2914 can also occur when using generics. The following sample generates C2914: +C2914 can also occur when using generics. The following example generates C2914: ```cpp // C2914b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2917.md b/docs/error-messages/compiler-errors-2/compiler-error-c2917.md index f7b627b4264..f572ec0664c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2917.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2917.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C2917" title: "Compiler Error C2917" +description: "Learn more about: Compiler Error C2917" ms.date: 06/01/2022 f1_keywords: ["C2917"] helpviewer_keywords: ["C2917"] -ms.assetid: ec9da9ee-0f37-47b3-87dd-19ef5a14dc4c --- # Compiler Error C2917 @@ -18,7 +17,7 @@ This error is obsolete in Visual Studio 2022 and later versions. ## Example -The following sample generates C2917. +The following example generates C2917. ```cpp // C2917.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2918.md b/docs/error-messages/compiler-errors-2/compiler-error-c2918.md index a32dfb09d0d..805c9907a4b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2918.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2918.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2918" title: "Compiler Error C2918" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2918" +ms.date: 11/04/2016 f1_keywords: ["C2918"] helpviewer_keywords: ["C2918"] -ms.assetid: e452f7ef-0590-45e6-9c7c-ee75dc014670 --- # Compiler Error C2918 -'name': Indexed properties cannot be used on the published surface of a WinRT type +> 'name': Indexed properties cannot be used on the published surface of a WinRT type + +## Remarks Indexed properties are not supported on the published surface of a WinRT type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2919.md b/docs/error-messages/compiler-errors-2/compiler-error-c2919.md index 4a127dde77d..0c922ead41a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2919.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2919.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2919" title: "Compiler Error C2919" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2919" +ms.date: 11/04/2016 f1_keywords: ["C2919"] helpviewer_keywords: ["C2919"] -ms.assetid: 140a6db9-eb48-4c5e-84a7-a09d2653605b --- # Compiler Error C2919 -'type': Operators cannot be used on the published surface of a WinRT type +> 'type': Operators cannot be used on the published surface of a WinRT type + +## Remarks The Windows Runtime type system does not support operator member functions in the published surface of a type. This is because not all languages can consume operator member functions. You can create private or internal operator member functions that can be called from C++ code in the same class or compilation unit. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2920.md b/docs/error-messages/compiler-errors-2/compiler-error-c2920.md index 09e52d53e3c..d93a9e6731b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2920.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2920.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2920" title: "Compiler Error C2920" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2920" +ms.date: 11/04/2016 f1_keywords: ["C2920"] helpviewer_keywords: ["C2920"] -ms.assetid: 0a4cb2de-00a0-4209-8160-c7ce6ed7d9ab --- # Compiler Error C2920 -redefinition : 'class' : class template or generic has already been declared as 'type' +> redefinition : 'class' : class template or generic has already been declared as 'type' + +## Remarks A generic or template class has multiple declarations, which are not equivalent. To fix this error, use different names for different types, or remove the redefinition of the type name. -The following sample generates C2920 and shows how to fix it: +## Examples + +The following example generates C2920 and shows how to fix it: ```cpp // C2920.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2921.md b/docs/error-messages/compiler-errors-2/compiler-error-c2921.md index 9e54aedc97d..1e95a49174b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2921.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2921.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2921" title: "Compiler Error C2921" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2921" +ms.date: 11/04/2016 f1_keywords: ["C2921"] helpviewer_keywords: ["C2921"] -ms.assetid: 323642a0-bfc4-4942-9f41-c3adf5c54296 --- # Compiler Error C2921 -redefinition : 'class' : class template or generic is being redeclared as 'type' +> redefinition : 'class' : class template or generic is being redeclared as 'type' + +## Remarks A generic or template class has multiple declarations that are not equivalent. To fix this error, use different names for different types, or remove the redefinition of the type name. -The following sample generates C2921: +## Examples + +The following example generates C2921: ```cpp // C2921.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2923.md b/docs/error-messages/compiler-errors-2/compiler-error-c2923.md index aa7b7cb9f12..d5867c16777 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2923.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2923.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2923" title: "Compiler Error C2923" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2923" +ms.date: 11/04/2016 f1_keywords: ["C2923"] helpviewer_keywords: ["C2923"] -ms.assetid: 6b92933b-13ef-4124-99d9-b89f9fdae030 --- # Compiler Error C2923 -'type' : 'identifier' is not a valid template type argument for parameter 'param' +> 'type' : 'identifier' is not a valid template type argument for parameter 'param' + +## Remarks The argument list is missing a type needed to instantiate the template or generic. Check the template or generic declaration. -The following sample generates C2923: +## Examples + +The following example generates C2923: ```cpp // C2923.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2927.md b/docs/error-messages/compiler-errors-2/compiler-error-c2927.md index 2421022f3aa..eefb7751741 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2927.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2927.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2927" title: "Compiler Error C2927" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2927" +ms.date: 11/04/2016 f1_keywords: ["C2927"] helpviewer_keywords: ["C2927"] -ms.assetid: 3f75beec-ff5c-44e1-9085-990ecd55198d --- # Compiler Error C2927 -'function' : a function template must be called with at least one argument +> 'function' : a function template must be called with at least one argument + +## Remarks -You cannot call a template function without arguments. The type of the template arguments determines what version of the function to generate. +You cannot call a function template without arguments. The type of the template arguments determines what version of the function to generate. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2928.md b/docs/error-messages/compiler-errors-2/compiler-error-c2928.md index 87bc5a29d23..d2660e9a556 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2928.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2928.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2928" title: "Compiler Error C2928" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2928" +ms.date: 11/04/2016 f1_keywords: ["C2928"] helpviewer_keywords: ["C2928"] -ms.assetid: 869e57f4-7024-4cbe-b47b-6e1e2a6005c5 --- # Compiler Error C2928 > explicit instantiation; '*identifier*' is not a function or static data member of template-class '*class-name*' +## Remarks + You cannot explicitly instantiate a member of *class-name* that is not a function or **`static`** variable. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2929.md b/docs/error-messages/compiler-errors-2/compiler-error-c2929.md index 64c2ad0086f..9ebb6d95a29 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2929.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2929.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2929" title: "Compiler Error C2929" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2929" +ms.date: 11/04/2016 f1_keywords: ["C2929"] helpviewer_keywords: ["C2929"] -ms.assetid: 11134027-6adc-4733-b6bd-b94486bd1933 --- # Compiler Error C2929 -'identifier' : explicit instantiation; cannot explicitly force and suppress instantiation of template-class member +> 'identifier' : explicit instantiation; cannot explicitly force and suppress instantiation of template-class member + +## Remarks You cannot explicitly instantiate an identifier while preventing it from being instantiated. -The following sample generates C2929: +## Example + +The following example generates C2929: ```cpp // C2929.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2930.md b/docs/error-messages/compiler-errors-2/compiler-error-c2930.md index 882645295d0..5cfc1f444e4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2930.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2930.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2930" title: "Compiler Error C2930" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2930" +ms.date: 11/04/2016 f1_keywords: ["C2930"] helpviewer_keywords: ["C2930"] -ms.assetid: f07eecd1-e5d1-4518-bd89-b1fd2a003a17 --- # Compiler Error C2930 -'class' : type-class-id redefined as an enumerator of 'enum identifier' +> 'class' : type-class-id redefined as an enumerator of 'enum identifier' + +## Remarks You cannot use a generic or template class as a member of an enumeration. This error can be caused if braces are improperly matched. -The following sample generates C2930: +## Examples + +The following example generates C2930: ```cpp // C2930.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2931.md b/docs/error-messages/compiler-errors-2/compiler-error-c2931.md index 569af1e5875..a282986af7b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2931.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2931.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2931" title: "Compiler Error C2931" +description: "Learn more about: Compiler Error C2931" ms.date: 06/01/2022 f1_keywords: ["C2931"] helpviewer_keywords: ["C2931"] -ms.assetid: 33430407-b149-4ba3-baf8-b0dae1ea3a5d --- # Compiler Error C2931 -'*class*' : type-class-id redefined as a member function of '*identifier*' +> '*class*' : type-class-id redefined as a member function of '*identifier*' + +## Remarks You can't use a generic or template class as a member function of another class. @@ -16,7 +17,9 @@ This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. -The following sample generates C2931: +## Examples + +The following example generates C2931: ```cpp // C2931.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2932.md b/docs/error-messages/compiler-errors-2/compiler-error-c2932.md index 3ec4a323b08..e42e9e08fde 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2932.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2932.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2932" title: "Compiler Error C2932" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2932" +ms.date: 11/04/2016 f1_keywords: ["C2932"] helpviewer_keywords: ["C2932"] -ms.assetid: c28e88d9-e654-4367-bfb4-13c780bca9bd --- # Compiler Error C2932 > '*class*' : type-class-id redefined as a data member of '*identifier*' +## Remarks + You can't use a generic or template class as a data member. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2932: +## Examples + +The following example generates C2932: ```cpp // C2932.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2933.md b/docs/error-messages/compiler-errors-2/compiler-error-c2933.md index c908e2a05c6..93b6124a889 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2933.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2933.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2933" title: "Compiler Error C2933" +description: "Learn more about: Compiler Error C2933" ms.date: 06/01/2022 f1_keywords: ["C2933"] helpviewer_keywords: ["C2933"] -ms.assetid: 394891e3-6b52-4b61-83d2-a1c5125d9bd5 --- # Compiler Error C2933 > '*class*' : type-class-id redefined as a typedef member of '*identifier*' +## Remarks + You can't use a generic or template class as a **`typedef`** member. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2933: +## Examples + +The following example generates C2933: ```cpp // C2933.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2934.md b/docs/error-messages/compiler-errors-2/compiler-error-c2934.md index f95f66da05f..43f7ec8c538 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2934.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2934.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2934" title: "Compiler Error C2934" +description: "Learn more about: Compiler Error C2934" ms.date: 06/01/2022 f1_keywords: ["C2934"] helpviewer_keywords: ["C2934"] -ms.assetid: b7f7e7aa-2d4c-4e17-8564-2c005ab81fd5 --- # Compiler Error C2934 -'*class*' : type-class-id redefined as a nested 'item' of '*identifier*' +> '*class*' : type-class-id redefined as a nested 'item' of '*identifier*' + +## Remarks You can't use a generic or template class as a nested item. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2935.md b/docs/error-messages/compiler-errors-2/compiler-error-c2935.md index 277c0cafd58..7c8f46a10f6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2935.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2935.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Error C2935" title: "Compiler Error C2935" +description: "Learn more about: Compiler Error C2935" ms.date: 06/01/2022 f1_keywords: ["C2935"] helpviewer_keywords: ["C2935"] -ms.assetid: e11ef90d-0756-4e43-8a09-4974c6aa72a3 --- # Compiler Error C2935 > '*class*' : type-class-id redefined as a global function +## Remarks + You can't use a generic or template class as a global function. This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. -The following sample generates C2935: +## Examples + +The following example generates C2935: ```cpp // C2935.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2936.md b/docs/error-messages/compiler-errors-2/compiler-error-c2936.md index 0b7ee74a590..803199c6e6e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2936.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2936.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Error C2936" title: "Compiler Error C2936" +description: "Learn more about: Compiler Error C2936" ms.date: 06/01/2022 f1_keywords: ["C2936"] helpviewer_keywords: ["C2936"] -ms.assetid: 5d1ba0fc-0c78-4a37-a83b-1ef8527763be --- # Compiler Error C2936 > '*class*' : type-class-id redefined as a global data variable +## Remarks + You can't use a generic or template class as a global data variable. This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. -The following sample generates C2936: +## Examples + +The following example generates C2936: ```cpp // C2936.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2937.md b/docs/error-messages/compiler-errors-2/compiler-error-c2937.md index 7c14567bc23..d69d2a883a8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2937.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2937.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2937" title: "Compiler Error C2937" +description: "Learn more about: Compiler Error C2937" ms.date: 06/01/2022 f1_keywords: ["C2937"] helpviewer_keywords: ["C2937"] -ms.assetid: 95671ca3-79f7-4b56-a5f2-a92296da1629 --- # Compiler Error C2937 > '*class*' : type-class-id redefined as a global typedef +## Remarks + You can't use a generic or template class as a global **`typedef`**. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2937: +## Examples + +The following example generates C2937: ```cpp // C2937.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2939.md b/docs/error-messages/compiler-errors-2/compiler-error-c2939.md index 602ed451dc0..50bf40c9c39 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2939.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2939.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Error C2939" title: "Compiler Error C2939" +description: "Learn more about: Compiler Error C2939" ms.date: 06/01/2022 f1_keywords: ["C2939"] helpviewer_keywords: ["C2939"] -ms.assetid: 455b050b-f2dc-4b5b-bd6a-e1f81d3d1644 --- # Compiler Error C2939 > '*class*' : type-class-id redefined as a local data variable +## Remarks + You can't use a generic or template class as a local data variable. This error is obsolete in Visual Studio 2022 and later versions. This error can be caused if braces are improperly matched. -The following sample generates C2939: +## Examples + +The following example generates C2939: ```cpp // C2939.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2940.md b/docs/error-messages/compiler-errors-2/compiler-error-c2940.md index dec4f0abd4a..583db713d13 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2940.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2940.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2940" title: "Compiler Error C2940" +description: "Learn more about: Compiler Error C2940" ms.date: 06/01/2022 f1_keywords: ["C2940"] helpviewer_keywords: ["C2940"] -ms.assetid: af6bf2bf-8de6-4cfd-bbf0-4c6b32a30edf --- # Compiler Error C2940 > '*class*' : type-class-id redefined as a local typedef +## Remarks + You can't use a generic or template class as a local **`typedef`**. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2940: +## Examples + +The following example generates C2940: ```cpp // C2940.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2941.md b/docs/error-messages/compiler-errors-2/compiler-error-c2941.md index 53c28a6c841..4d14d929168 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2941.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2941.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C2941" title: "Compiler Error C2941" +description: "Learn more about: Compiler Error C2941" ms.date: 06/01/2022 f1_keywords: ["C2941"] helpviewer_keywords: ["C2941"] -ms.assetid: 1bba94eb-5bf6-468d-8f84-96a6391a7048 --- # Compiler Error C2941 > '*class*' : type-class-id redefined as a local 'item' +## Remarks + You can't use a generic or template class as an item. This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2942.md b/docs/error-messages/compiler-errors-2/compiler-error-c2942.md index 83426631265..f806be05068 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2942.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2942.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2942" title: "Compiler Error C2942" +description: "Learn more about: Compiler Error C2942" ms.date: 06/01/2022 f1_keywords: ["C2942"] helpviewer_keywords: ["C2942"] -ms.assetid: 13abf744-8fa1-450d-886d-e5717c04956e --- # Compiler Error C2942 > '*class*' : type-class-id redefined as a formal argument of a function +## Remarks + You can't use a generic or template class as a formal argument. You cannot pass an argument directly to the constructor of a generic or template class. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2942: +## Examples + +The following example generates C2942: ```cpp // C2942.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2943.md b/docs/error-messages/compiler-errors-2/compiler-error-c2943.md index 99b4d8f7abd..d2ede6f3564 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2943.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2943.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2943" title: "Compiler Error C2943" +description: "Learn more about: Compiler Error C2943" ms.date: 06/01/2022 f1_keywords: ["C2943"] helpviewer_keywords: ["C2943"] -ms.assetid: ede6565e-d892-44c0-8eee-c69545f3be2e --- # Compiler Error C2943 > '*class*' : type-class-id redefined as a type argument of a template +## Remarks + You can't use a generic or template class, instead of a symbol, as a generic or template type argument. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2943: +## Example + +The following example generates C2943: ```cpp // C2943.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2944.md b/docs/error-messages/compiler-errors-2/compiler-error-c2944.md index 68866586941..4c2a3a33869 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2944.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2944.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2944" title: "Compiler Error C2944" +description: "Learn more about: Compiler Error C2944" ms.date: 06/01/2022 f1_keywords: ["C2944"] helpviewer_keywords: ["C2944"] -ms.assetid: f209e668-e72f-442a-a438-8c4ff43a404a --- # Compiler Error C2944 > '*class*' : type-class-id redefined as a value argument of a template +## Remarks + You can't use a generic or template class, instead of a symbol, as a template value argument. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C2944: +## Examples + +The following example generates C2944: ```cpp // C2944.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2945.md b/docs/error-messages/compiler-errors-2/compiler-error-c2945.md index 2d13eb9f49e..9674071222b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2945.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2945.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2945" title: "Compiler Error C2945" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2945" +ms.date: 11/04/2016 f1_keywords: ["C2945"] helpviewer_keywords: ["C2945"] -ms.assetid: be640257-7017-45d1-986a-9fe8caab52f3 --- # Compiler Error C2945 -explicit instantiation does not refer to a template-class specialization +> explicit instantiation does not refer to a template-class specialization + +## Remarks You cannot explicitly instantiate something that is not templated. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2946.md b/docs/error-messages/compiler-errors-2/compiler-error-c2946.md index 382b205402a..01b72d1aeb9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2946.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2946.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2946" title: "Compiler Error C2946" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2946" +ms.date: 11/04/2016 f1_keywords: ["C2946"] helpviewer_keywords: ["C2946"] -ms.assetid: c86dfbfc-7702-4f09-8a53-d205710e99c2 --- # Compiler Error C2946 -explicit instantiation; 'class' is not a template-class specialization +> explicit instantiation; 'class' is not a template-class specialization + +## Remarks You cannot explicitly instantiate a nontemplated class. ## Example -The following sample generates C2946. +The following example generates C2946. ```cpp // C2946.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2947.md b/docs/error-messages/compiler-errors-2/compiler-error-c2947.md index 77faf9893e2..ef70b5db307 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2947.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2947.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2947" title: "Compiler Error C2947" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2947" +ms.date: 11/04/2016 f1_keywords: ["C2947"] helpviewer_keywords: ["C2947"] -ms.assetid: 6c056f62-ec90-4883-8a67-aeeb6ec13546 --- # Compiler Error C2947 -expecting '>' to terminate construct, found 'syntax' +> expecting '>' to terminate construct, found 'syntax' + +## Remarks A generic or template argument list may not have been terminated correctly. C2947 can also be generated by syntax errors. -The following sample generates C2947: +## Example + +The following example generates C2947: ```cpp // C2947.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2948.md b/docs/error-messages/compiler-errors-2/compiler-error-c2948.md index b3a878a050a..18dda3d7874 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2948.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2948.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2948" title: "Compiler Error C2948" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2948" +ms.date: 11/04/2016 f1_keywords: ["C2948"] helpviewer_keywords: ["C2948"] -ms.assetid: 780c6ed3-43a0-4112-8d00-b7bf79086c05 --- # Compiler Error C2948 -explicit instantiation; storage class specifier 'specifier' not permitted on specialization +> explicit instantiation; storage class specifier 'specifier' not permitted on specialization + +## Remarks You cannot use storage-class specifiers (such as **`extern`**) in a specialization of a template class that was previously explicitly instantiated. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2951.md b/docs/error-messages/compiler-errors-2/compiler-error-c2951.md index a38b41dfaf7..993bf2811b4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2951.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2951.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2951" title: "Compiler Error C2951" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2951" +ms.date: 11/04/2016 f1_keywords: ["C2951"] helpviewer_keywords: ["C2951"] -ms.assetid: c6f95aa2-c894-425b-a51c-d40d70c8daa1 --- # Compiler Error C2951 -type declarations are only permitted at global, namespace, or class scope +> type declarations are only permitted at global, namespace, or class scope + +## Remarks You cannot declare a generic or template class outside global or namespace scope. If you make your generic or template declarations in an include file, make sure the include file is at global scope. -The following sample generates C2951: +## Examples + +The following example generates C2951: ```cpp // C2951.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2952.md b/docs/error-messages/compiler-errors-2/compiler-error-c2952.md index 9998595a1ca..59b2ce3c7f4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2952.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2952.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2952" title: "Compiler Error C2952" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2952" +ms.date: 11/04/2016 f1_keywords: ["C2952"] helpviewer_keywords: ["C2952"] -ms.assetid: a40e18a2-d02c-4511-854f-6c6fd6789a1a --- # Compiler Error C2952 -'declaration' : type declaration missing template parameter list +> 'declaration' : type declaration missing template parameter list + +## Remarks A template declaration was ill formed. -The following sample generates C2952: +## Examples + +The following example generates C2952: ```cpp // C2952.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2953.md b/docs/error-messages/compiler-errors-2/compiler-error-c2953.md index 6e0d8091d5c..a9f3ae8178a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2953.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2953.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2953" title: "Compiler Error C2953" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2953" +ms.date: 11/04/2016 f1_keywords: ["C2953"] helpviewer_keywords: ["C2953"] -ms.assetid: 8dbcfa24-8296-4e40-bdc4-5526c07d8892 --- # Compiler Error C2953 -'identifier' : class template has already been defined +> 'identifier' : class template has already been defined + +## Remarks Check the source file and include files for other definitions. -The following sample generates C2953: +## Example + +The following example generates C2953: ```cpp // C2953.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2955.md b/docs/error-messages/compiler-errors-2/compiler-error-c2955.md index 521cf7a352c..93996879010 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2955.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2955.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2955" title: "Compiler Error C2955" -ms.date: "03/28/2017" +description: "Learn more about: Compiler Error C2955" +ms.date: 03/28/2017 f1_keywords: ["C2955"] helpviewer_keywords: ["C2955"] -ms.assetid: 77709fb6-d69b-46fd-a62f-e8564563d01b --- # Compiler Error C2955 -'identifier' : use of class template or alias generic requires template or generic argument list +> 'identifier' : use of class template or alias generic requires template or generic argument list + +## Remarks You cannot use a class template or class generic as an identifier without a template or generic argument list. For more information, see [Class Templates](../../cpp/class-templates.md). -The following sample generates C2955 and shows how to fix it: +## Examples + +The following example generates C2955 and shows how to fix it: ```cpp // C2955.cpp @@ -61,8 +64,6 @@ int main() { } ``` -## Example - **Visual Studio 2017 and later:** The compiler correctly diagnoses missing template argument lists when the template appears in a template parameter list (for example as part of a default template argument or a non-type template parameter). The following code compiles in Visual Studio 2015 but produces an error in Visual Studio 2017. ``` 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 e44cae489ff..77f9fee4e42 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2956.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2956.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Error C2956" title: "Compiler Error C2956" +description: "Learn more about: Compiler Error C2956" ms.date: 04/05/2022 f1_keywords: ["C2956"] helpviewer_keywords: ["C2956"] @@ -9,15 +9,15 @@ helpviewer_keywords: ["C2956"] > usual deallocation function '*function*' would be chosen as placement deallocation function -The deallocation function found for the placement new expression matches one of the usual deallocation functions. Either an implicit compiler-generated deallocation or an explicit `delete` (or `delete[]`) would use the wrong deallocation function. - ## Remarks +The deallocation function found for the placement new expression matches one of the usual deallocation functions. Either an implicit compiler-generated deallocation or an explicit `delete` (or `delete[]`) would use the wrong deallocation function. + Error C2956 indicates you used a *placement new expression* (a `new` expression that takes parameters) in a way that can cause a memory leak or runtime crash. It usually means the resulting value can't be deleted in a typical way. That is, either an explicit `delete` (or `delete[]`) expression in your code, or the implicit deallocation when a constructor throws an exception, could invoke the wrong `operator delete` or supply it with the wrong parameters. The C++ standard specifies *usual deallocation functions* as overloads of `operator delete` or `operator delete[]` that take extra parameters of type `std::size_t` (C++14 or later), `std::align_val_t` (C++17 or later), and `std::destroying_delete_t` (C++20 or later). When you use a placement new expression, the compiler looks for a matching `operator delete` function that takes the same parameters (after the first one). If one is found and its signature matches a usual deallocation function, the compiler reports error C2956. -The way to resolve the issue depends in part on your intent. For example, in C++ 11, you could define an `operator new` overload that takes an extra `size_t` parameter in your class to pass a value to the allocator. In C++ 14, the same code now causes an error: +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-c2957.md b/docs/error-messages/compiler-errors-2/compiler-error-c2957.md index e2d17ce3dd2..2c1e921c6a3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2957.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2957.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2957" title: "Compiler Error C2957" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2957" +ms.date: 11/04/2016 f1_keywords: ["C2957"] helpviewer_keywords: ["C2957"] -ms.assetid: 9cb4526f-4af8-47e9-b786-56192627ca72 --- # Compiler Error C2957 -'delim' : invalid left delimiter : expected '<' +> 'delim' : invalid left delimiter : expected '<' + +## Remarks A generic class was ill formed. -The following sample generates C2957: +## Example + +The following example generates C2957: ```cpp // C2957.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2958.md b/docs/error-messages/compiler-errors-2/compiler-error-c2958.md index 72706383992..341ff3c1dd6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2958.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2958.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2958" title: "Compiler Error C2958" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2958" +ms.date: 11/04/2016 f1_keywords: ["C2958"] helpviewer_keywords: ["C2958"] -ms.assetid: 332bf6d3-7cd1-4b1a-8ddb-d4a8cbf01115 --- # Compiler Error C2958 -the left delimiter found at 'location' was not matched correctly +> the left delimiter found at 'location' was not matched correctly + +## Remarks A delimiter is not properly matched. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2959.md b/docs/error-messages/compiler-errors-2/compiler-error-c2959.md index 6855bf67bb9..af70755a70c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2959.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2959.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2959" title: "Compiler Error C2959" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2959" +ms.date: 11/04/2016 f1_keywords: ["C2959"] helpviewer_keywords: ["C2959"] -ms.assetid: d66bb2a8-70c3-4209-a358-b0c47f111a50 --- # Compiler Error C2959 -a generic class or function may not be a member of a template +> a generic class or function may not be a member of a template + +## Remarks For more information, see [Windows Runtime and Managed Templates](../../extensions/windows-runtime-and-managed-templates-cpp-component-extensions.md) and [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The following sample generates C2959. +The following example generates C2959. ```cpp // C2959.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2962.md b/docs/error-messages/compiler-errors-2/compiler-error-c2962.md index 9059b4b8787..87f5149e549 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2962.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2962.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C2962" title: "Compiler Error C2962" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2962" +ms.date: 11/04/2016 f1_keywords: ["C2962"] helpviewer_keywords: ["C2962"] -ms.assetid: 6f966aec-4eea-4221-8e1b-fe66808c6f5c --- # Compiler Error C2962 -syntax error : 'token' : expected template-class member function definition to end with '}' +> syntax error : 'token' : expected template-class member function definition to end with '}' + +## Remarks The token caused a syntax error in a template declaration. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2969.md b/docs/error-messages/compiler-errors-2/compiler-error-c2969.md index 47b9816261f..76d07d11952 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2969.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2969.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2969" title: "Compiler Error C2969" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2969" +ms.date: 11/04/2016 f1_keywords: ["C2969"] helpviewer_keywords: ["C2969"] -ms.assetid: e4ea3d66-b937-4b2c-b42a-96e03fb11579 --- # Compiler Error C2969 -syntax error : 'symbol' : expected member function definition to end with '}' +> syntax error : 'symbol' : expected member function definition to end with '}' + +## Remarks A template member function definition has an unmatched closing brace. -The following sample generates C2969: +## Example + +The following example generates C2969: ```cpp // C2969.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2970.md b/docs/error-messages/compiler-errors-2/compiler-error-c2970.md index 4f25c08138b..f92b1c41441 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2970.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2970.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2970" title: "Compiler Error C2970" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2970" +ms.date: 11/04/2016 f1_keywords: ["C2970"] helpviewer_keywords: ["C2970"] -ms.assetid: 21d90348-20d3-438c-b278-efdbfb93a7d2 --- # Compiler Error C2970 -'class' : template parameter 'param' : 'arg' : an expression involving objects with internal linkage cannot be used as a non-type argument +> 'class' : template parameter 'param' : 'arg' : an expression involving objects with internal linkage cannot be used as a non-type argument + +## Remarks You cannot use the name or address of a static variable as a template argument. The template class expects a const value that can be evaluated at compile time. -The following sample generates C2970: +## Example + +The following example generates C2970: ```cpp // C2970.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2971.md b/docs/error-messages/compiler-errors-2/compiler-error-c2971.md index 2ff75e440c6..667d494be2d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2971.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2971.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2971" title: "Compiler Error C2971" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2971" +ms.date: 11/04/2016 f1_keywords: ["C2971"] helpviewer_keywords: ["C2971"] -ms.assetid: fdb5467b-9a41-41ef-ac20-2e9428d5a4fc --- # Compiler Error C2971 -'class' : template parameter 'param' : 'arg' : a local variable cannot be used as a non-type argument +> 'class' : template parameter 'param' : 'arg' : a local variable cannot be used as a non-type argument + +## Remarks You cannot use the name or address of a local variable as a template argument. -The following sample generates C2971: +## Example + +The following example generates C2971: ```cpp // C2971.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2973.md b/docs/error-messages/compiler-errors-2/compiler-error-c2973.md index 2a06b243465..79b7b4ab806 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2973.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2973.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2973" title: "Compiler Error C2973" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2973" +ms.date: 11/04/2016 f1_keywords: ["C2973"] helpviewer_keywords: ["C2973"] -ms.assetid: 18b4a1c1-0ef6-43af-887a-1b5b1ab88d5b --- # Compiler Error C2973 -invalid template argument 'number' +> invalid template argument 'number' + +## Remarks Check the template definition to find the correct types. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2974.md b/docs/error-messages/compiler-errors-2/compiler-error-c2974.md index 1b9610dfcde..1ae52a62674 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2974.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2974.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2974" title: "Compiler Error C2974" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2974" +ms.date: 11/04/2016 f1_keywords: ["C2974"] helpviewer_keywords: ["C2974"] -ms.assetid: 1b444260-f2bf-48d7-ab1e-35573d8c4a0e --- # Compiler Error C2974 -invalid type argument 'number', type expected +> invalid type argument 'number', type expected + +## Remarks The generic or template argument does not match the generic or template declaration. A type should appear within the angle brackets. Check the generic or template definition to find the correct types. -The following sample generates C2974: +## Examples + +The following example generates C2974: ```cpp // C2974.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2975.md b/docs/error-messages/compiler-errors-2/compiler-error-c2975.md index 5e91d46fa5c..e9254cb923f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2975.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2975.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2975" title: "Compiler Error C2975" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2975" +ms.date: 11/04/2016 f1_keywords: ["C2975"] helpviewer_keywords: ["C2975"] -ms.assetid: 526f6b9d-6c76-4c12-9252-1b1d7c1e06c7 --- # Compiler Error C2975 > '*argument*' : invalid template argument for '*type*', expected compile-time constant expression +## Remarks + The template argument does not match the template declaration; a constant expression should appear within the angle brackets. Variables are not allowed as template actual arguments. Check the template definition to find the correct types. -## Example +## Examples -The following sample generates C2975 and also shows correct usage: +The following example generates C2975 and also shows correct usage: ```cpp // C2975.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2976.md b/docs/error-messages/compiler-errors-2/compiler-error-c2976.md index 3ed9ac47998..d9b7e0953b0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2976.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2976.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C2976" title: "Compiler Error C2976" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2976" +ms.date: 11/04/2016 f1_keywords: ["C2976"] helpviewer_keywords: ["C2976"] -ms.assetid: d9bf9836-325e-4f72-a7e3-a67cf19d32e7 --- # Compiler Error C2976 -'identifier' : too few type arguments +> 'identifier' : too few type arguments + +## Remarks A generic or template is missing one or more actual arguments. Check the generic or template declaration to find the correct number of parameters. This error can be caused by missing template arguments in C++ Standard Library components. -The following sample generates C2976: +## Examples + +The following example generates C2976: ```cpp // C2976.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2977.md b/docs/error-messages/compiler-errors-2/compiler-error-c2977.md index 4be0207cbb0..302846e67d7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2977.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2977.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2977" title: "Compiler Error C2977" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2977" +ms.date: 11/04/2016 f1_keywords: ["C2977"] helpviewer_keywords: ["C2977"] -ms.assetid: 3c4218e0-5d03-4a2b-b757-c507c35f3542 --- # Compiler Error C2977 -'identifier' : too many type arguments +> 'identifier' : too many type arguments + +## Remarks A generic or template has too many actual arguments. Check the generic or template declaration to find the correct number of parameters. -The following sample generates C2977: +## Examples + +The following example generates C2977: ```cpp // C2977.cpp 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 4426147e9a7..d9bee87b88d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2978.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2978.md @@ -1,20 +1,21 @@ --- -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 +> syntax error : expected 'keyword1' or 'keyword2'; found type 'keyword3'; non-type parameters are not supported in generics + +## Remarks -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 -The following sample generates C2978. +The following example generates C2978. ```cpp // C2978.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2979.md b/docs/error-messages/compiler-errors-2/compiler-error-c2979.md index c880a70db6b..691bd16a70c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2979.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2979.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C2979" title: "Compiler Error C2979" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2979" +ms.date: 11/04/2016 f1_keywords: ["C2979"] helpviewer_keywords: ["C2979"] -ms.assetid: 98bd9043-ec44-451e-a482-3a8e35fc7464 --- # Compiler Error C2979 -explicit specializations are not supported in generics +> explicit specializations are not supported in generics + +## Remarks A generic class was declared incorrectly. See [Generics](../../extensions/generics-cpp-component-extensions.md) for more information. ## Example -The following sample generates C2979. +The following example generates C2979. ```cpp // C2979.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2988.md b/docs/error-messages/compiler-errors-2/compiler-error-c2988.md index a7abd23cc3a..06f37437baa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2988.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2988.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2988" title: "Compiler Error C2988" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2988" +ms.date: 11/04/2016 f1_keywords: ["C2988"] helpviewer_keywords: ["C2988"] -ms.assetid: c07ada8d-7cdf-4496-8656-cc3851e76b46 --- # Compiler Error C2988 -unrecognizable template declaration/definition +> unrecognizable template declaration/definition + +## Remarks The template declaration does not parse correctly. Check delimiters. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2989.md b/docs/error-messages/compiler-errors-2/compiler-error-c2989.md index 7b6991ded17..973a9e9107e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2989.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2989.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2989" title: "Compiler Error C2989" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2989" +ms.date: 11/04/2016 f1_keywords: ["C2989"] helpviewer_keywords: ["C2989"] -ms.assetid: 936303d8-eb3b-4746-82ec-2f18020a6f64 --- # Compiler Error C2989 -'class' : class type has already been declared as a non-class type +> 'class' : class type has already been declared as a non-class type + +## Remarks The class generic or template redefines a non-template or non-generic class. Check header files for conflicts. -The following sample generates C2989: +## Examples + +The following example generates C2989: ```cpp // C2989.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2990.md b/docs/error-messages/compiler-errors-2/compiler-error-c2990.md index b0132230ba9..02ecde2c786 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2990.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2990.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2990" title: "Compiler Error C2990" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2990" +ms.date: 11/04/2016 f1_keywords: ["C2990"] helpviewer_keywords: ["C2990"] -ms.assetid: 674e9f6a-6743-4af0-a7ed-cbe11103a2f8 --- # Compiler Error C2990 -'class' : non-class type as already been declared as a class type +> 'class' : non-class type as already been declared as a class type + +## Remarks The non generic or template class redefines a generic or template class. Check header files for conflicts. -The following sample generates C2990: +## Examples + +The following example generates C2990: ```cpp // C2990.cpp @@ -35,7 +38,7 @@ ref struct GC {}; // C2990 C2990 can also occur due to a breaking change in the Microsoft C++ compiler for Visual Studio 2005; the compiler now requires that multiple declarations for the same type be identical with respect to template specification. -The following sample generates C2990: +The following example generates C2990: ```cpp // C2990c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2991.md b/docs/error-messages/compiler-errors-2/compiler-error-c2991.md index 6a972a047e6..7b9c8c2bc13 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2991.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2991.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2991" title: "Compiler Error C2991" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2991" +ms.date: 11/04/2016 f1_keywords: ["C2991"] helpviewer_keywords: ["C2991"] -ms.assetid: a87e4404-26e8-4927-b3ee-5d02b3b8bee1 --- # Compiler Error C2991 -redefinition of type parameter 'parameter' +> redefinition of type parameter 'parameter' + +## Remarks There was a type conflict between two generic or template definitions of `parameter`. When defining multiple generic or template parameters, you must use equivalent types. -The following sample generates C2991: +## Examples + +The following example generates C2991: ```cpp // C2991.cpp 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 228162b189d..023ef93a9b3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2992.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2992.md @@ -1,49 +1,54 @@ --- -description: "Learn more about: Compiler Error C2992" title: "Compiler Error C2992" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2992" +ms.date: 11/04/2016 f1_keywords: ["C2992"] helpviewer_keywords: ["C2992"] -ms.assetid: 01b16447-43fe-4e91-9a5a-af884a166a31 --- # Compiler Error C2992 -'class' : invalid or missing type parameter list +> 'class' : invalid or missing type parameter list + +## Remarks The class is preceded by a **`template`** or **generic** keyword with missing or invalid parameters. -## Example +## Examples -The following sample generates C2992: +The following example generates C2992: ```cpp // 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 27ca013f1e5..dc9f175046f 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,55 @@ --- -description: "Learn more about: Compiler Error C2993" title: "Compiler Error C2993" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2993" +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' +> 'identifier' : illegal type for non-type template parameter 'parameter' + +## Remarks -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: +## Examples + +The following example 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-c2994.md b/docs/error-messages/compiler-errors-2/compiler-error-c2994.md index 506170906f5..9aa9c4f11a1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2994.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2994.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2994" title: "Compiler Error C2994" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2994" +ms.date: 11/04/2016 f1_keywords: ["C2994"] helpviewer_keywords: ["C2994"] -ms.assetid: b03570b5-e5fd-41d8-bdf1-dfadc2b1e116 --- # Compiler Error C2994 -unnamed class in template parameter list +> unnamed class in template parameter list + +## Remarks You cannot use the **`class`** keyword as a template argument without specifying a class name. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2995.md b/docs/error-messages/compiler-errors-2/compiler-error-c2995.md index c720f6294c5..03f7125d169 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2995.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2995.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C2995" title: "Compiler Error C2995" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2995" +ms.date: 11/04/2016 f1_keywords: ["C2995"] helpviewer_keywords: ["C2995"] -ms.assetid: a57cdfe0-b40b-4a67-a95c-1a49ace4842b --- # Compiler Error C2995 -'function' : function template has already been defined +> 'function' : function template has already been defined + +## Remarks Make sure that there is only one definition for each member function of a templated class. -The following sample generates C2995: +## Example + +The following example generates C2995: ```cpp // C2995.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2996.md b/docs/error-messages/compiler-errors-2/compiler-error-c2996.md index d21aa58ca7f..8222baa8df3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2996.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2996.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C2996" title: "Compiler Error C2996" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2996" +ms.date: 11/04/2016 f1_keywords: ["C2996"] helpviewer_keywords: ["C2996"] -ms.assetid: f0ca9f8b-1751-4182-adab-1424f0c5e0c0 --- # Compiler Error C2996 -'function' : recursive function template definition +> 'function' : recursive function template definition + +## Remarks A function definition attempts to instantiate its root templated class. Recursive template instantiations are not allowed. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c2998.md b/docs/error-messages/compiler-errors-2/compiler-error-c2998.md index 78bb2293253..f1401071122 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c2998.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c2998.md @@ -1,21 +1,14 @@ --- -description: "Learn more about: Compiler Error C2998" title: "Compiler Error C2998" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C2998" +ms.date: 06/29/2025 f1_keywords: ["C2998"] helpviewer_keywords: ["C2998"] -ms.assetid: 8193d491-b5d9-4477-acb1-cf166889c070 --- # Compiler Error C2998 -'identifier' : cannot be a template definition +> '*identifier*': cannot be a template definition -The compiler could not process the syntax used in the template definition. +## Remarks -The following sample generates C2998: - -```cpp -// C2998.cpp -// compile with: /c -template int x = 1018; // C2998 -``` +The compiler could not process the syntax used in the template definition. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3001.md b/docs/error-messages/compiler-errors-2/compiler-error-c3001.md index 8839791989f..617f88cb018 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3001.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3001.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3001" title: "Compiler Error C3001" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3001" +ms.date: 11/04/2016 f1_keywords: ["C3001"] helpviewer_keywords: ["C3001"] -ms.assetid: d0e03478-1b44-47e5-8f5b-70415fa1f8bc --- # Compiler Error C3001 -'error_text' : expected an OpenMP directive name +> 'error_text' : expected an OpenMP directive name + +## Remarks The `omp` pragma must be followed by a directive. -The following sample generates C3001: +## Example + +The following example generates C3001: ```c // C3001.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3002.md b/docs/error-messages/compiler-errors-2/compiler-error-c3002.md index 0bc4652dba0..ee452060426 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3002.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3002.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3002" title: "Compiler Error C3002" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3002" +ms.date: 11/04/2016 f1_keywords: ["C3002"] helpviewer_keywords: ["C3002"] -ms.assetid: 2d4241a7-c8eb-4d43-a128-dca255d137bc --- # Compiler Error C3002 -'name1 name2' : multiple OpenMP directive names +> 'name1 name2' : multiple OpenMP directive names + +## Remarks Multiple directive names are not allowed. -The following sample generates C3002: +## Example + +The following example generates C3002: ```c // C3002.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3003.md b/docs/error-messages/compiler-errors-2/compiler-error-c3003.md index 9bec4bf3c4a..c9a04e0dbb2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3003.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3003.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3003" title: "Compiler Error C3003" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3003" +ms.date: 11/04/2016 f1_keywords: ["C3003"] helpviewer_keywords: ["C3003"] -ms.assetid: 22e74f99-bb7f-4518-ab0d-934d5d49bcc7 --- # Compiler Error C3003 -'directive' : OpenMP directive name not allowed after directive clauses +> 'directive' : OpenMP directive name not allowed after directive clauses + +## Remarks An OpenMP directive name cannot follow an OpenMP directive clause. -The following sample generates C3003: +## Example + +The following example generates C3003: ```c // C3003.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3004.md b/docs/error-messages/compiler-errors-2/compiler-error-c3004.md index 47e57c17a04..7d9edc3a448 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3004.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3004.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3004" title: "Compiler Error C3004" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3004" +ms.date: 11/04/2016 f1_keywords: ["C3004"] helpviewer_keywords: ["C3004"] -ms.assetid: 819c2b57-8366-4ca7-9135-1f0c5e5b6bb6 --- # Compiler Error C3004 -'clause' : clause not valid on OpenMP 'directive' directive +> 'clause' : clause not valid on OpenMP 'directive' directive + +## Remarks An OpenMP clause was used on a directive for which it is not enabled. -The following sample generates C3004: +## Example + +The following example generates C3004: ```c // C3004.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3005.md b/docs/error-messages/compiler-errors-2/compiler-error-c3005.md index 6548d72a0f2..83f3fcf62df 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3005.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3005.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3005" title: "Compiler Error C3005" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3005" +ms.date: 11/04/2016 f1_keywords: ["C3005"] helpviewer_keywords: ["C3005"] -ms.assetid: 30bad565-e79f-4c3f-82cb-a74bd0baab8f --- # Compiler Error C3005 -'error_text' : unexpected token encountered on OpenMP 'directive' directive +> 'error_text' : unexpected token encountered on OpenMP 'directive' directive + +## Remarks An OpenMP directive was ill formed. -The following sample generates C3005: +## Examples + +The following example generates C3005: ```c // C3005.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3006.md b/docs/error-messages/compiler-errors-2/compiler-error-c3006.md index 13bc64c5b49..278771bdba0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3006.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3006.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3006" title: "Compiler Error C3006" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3006" +ms.date: 11/04/2016 f1_keywords: ["C3006"] helpviewer_keywords: ["C3006"] -ms.assetid: 449082ec-fd45-4c47-8ab3-ba6a719e4dc4 --- # Compiler Error C3006 -'clause' : clause on OpenMP 'directive' directive is missing an expected argument +> 'clause' : clause on OpenMP 'directive' directive is missing an expected argument + +## Remarks An OpenMP directive did not have an expected argument. -The following sample generates C3006: +## Example + +The following example generates C3006: ```c // C3006.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3007.md b/docs/error-messages/compiler-errors-2/compiler-error-c3007.md index f4d9bd13b97..a18f67035f8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3007.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3007.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3007" title: "Compiler Error C3007" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3007" +ms.date: 11/04/2016 f1_keywords: ["C3007"] helpviewer_keywords: ["C3007"] -ms.assetid: e415ef42-bdc9-4f32-8198-5e25b289a089 --- # Compiler Error C3007 -'arg' : clause on OpenMP 'directive' directive does not take an argument +> 'arg' : clause on OpenMP 'directive' directive does not take an argument + +## Remarks An OpenMP directive had an argument, but the directive does not take an argument. -The following sample generates C3007: +## Example + +The following example generates C3007: ```c // C3007.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3008.md b/docs/error-messages/compiler-errors-2/compiler-error-c3008.md index 41bbfcc6010..e9578e2930f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3008.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3008.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3008" title: "Compiler Error C3008" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3008" +ms.date: 11/04/2016 f1_keywords: ["C3008"] helpviewer_keywords: ["C3008"] -ms.assetid: 04d93201-28e5-4be0-945c-aad616376f4b --- # Compiler Error C3008 -'arg' : argument is missing closing ')' on OpenMP 'directive' directive +> 'arg' : argument is missing closing ')' on OpenMP 'directive' directive + +## Remarks An OpenMP directive that takes an argument did not have a closing parenthesis. -The following sample generates C3008: +## Example + +The following example generates C3008: ```c // C3008.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3009.md b/docs/error-messages/compiler-errors-2/compiler-error-c3009.md index 83fd8c99acc..7a3a7aa8252 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3009.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3009.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3009" title: "Compiler Error C3009" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3009" +ms.date: 11/04/2016 f1_keywords: ["C3009"] helpviewer_keywords: ["C3009"] -ms.assetid: aded5985-f5fd-4c3e-a157-16be55ec1313 --- # Compiler Error C3009 -'label' : jump into OpenMP structured block not allowed +> 'label' : jump into OpenMP structured block not allowed + +## Remarks Code cannot jump into or out of an OpenMP block. -The following sample generates C3009: +## Example + +The following example generates C3009: ```c // C3009.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3010.md b/docs/error-messages/compiler-errors-2/compiler-error-c3010.md index dc715809c72..def3dcb1b98 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3010.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3010.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3010" title: "Compiler Error C3010" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3010" +ms.date: 11/04/2016 f1_keywords: ["C3010"] helpviewer_keywords: ["C3010"] -ms.assetid: e959d038-bba6-432a-9c0a-0470474de7d9 --- # Compiler Error C3010 -'label' : jump out of OpenMP structured block not allowed +> 'label' : jump out of OpenMP structured block not allowed + +## Remarks Code cannot jump into or out of an OpenMP block. -The following sample generates C3010: +## Example + +The following example generates C3010: ```c // C3010.c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3011.md b/docs/error-messages/compiler-errors-2/compiler-error-c3011.md index 830e14b0863..65e8f9cd82b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3011.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3011.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3011" title: "Compiler Error C3011" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3011" +ms.date: 11/04/2016 f1_keywords: ["C3011"] helpviewer_keywords: ["C3011"] -ms.assetid: 24c3a917-ebff-4deb-9155-23adf6468531 --- # Compiler Error C3011 -inline assembly not allowed directly within a parallel region +> inline assembly not allowed directly within a parallel region + +## Remarks An `omp` parallel region cannot contain inline assembly instructions. -The following sample generates C3011: +## Example + +The following example generates C3011: ```cpp // C3011.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3012.md b/docs/error-messages/compiler-errors-2/compiler-error-c3012.md index 8754ce80f9b..e6abf61a319 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3012.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3012.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3012" title: "Compiler Error C3012" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3012" +ms.date: 11/04/2016 f1_keywords: ["C3012"] helpviewer_keywords: ["C3012"] -ms.assetid: cc7040b1-b3fb-4da6-a474-877914d30332 --- # Compiler Error C3012 > '*intrinsic*' : intrinsic function not allowed directly within a parallel region +## Remarks + A [compiler intrinsic](../../intrinsics/compiler-intrinsics.md) function is not allowed in an `omp parallel` region. To fix this issue, move intrinsics out of the region, or replace them with non-intrinsic equivalents. ## Example -The following sample generates C3012, and shows one way to fix it: +The following example generates C3012, and shows one way to fix it: ```cpp // C3012.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3013.md b/docs/error-messages/compiler-errors-2/compiler-error-c3013.md index cd9019d1f11..744d28b348c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3013.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3013.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3013" title: "Compiler Error C3013" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3013" +ms.date: 11/04/2016 f1_keywords: ["C3013"] helpviewer_keywords: ["C3013"] -ms.assetid: f896777d-27e6-4b6d-baab-1567317f3374 --- # Compiler Error C3013 -'clause' : clause may only appear once on OpenMP 'directive' directive +> 'clause' : clause may only appear once on OpenMP 'directive' directive + +## Remarks A clause appeared twice on the same directive. Delete one occurrence of the clause. -The following sample generates C3013: +## Example + +The following example generates C3013: ```cpp // C3013.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3014.md b/docs/error-messages/compiler-errors-2/compiler-error-c3014.md index 6f59ffd243c..b57685ca12d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3014.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3014.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3014" title: "Compiler Error C3014" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3014" +ms.date: 11/04/2016 f1_keywords: ["C3014"] helpviewer_keywords: ["C3014"] -ms.assetid: af1c5b0c-dbf9-4274-b06a-c6c2cdcf2a52 --- # Compiler Error C3014 -expected a for loop following OpenMP 'directive' directive +> expected a for loop following OpenMP 'directive' directive + +## Remarks It is an error for anything other than a **`for`** loop to immediately follow a `#pragma omp for` directive. -The following sample generates C3014: +## Example + +The following example generates C3014: ```cpp // C3014.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3015.md b/docs/error-messages/compiler-errors-2/compiler-error-c3015.md index cbc3d828a33..57be2b65cd9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3015.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3015.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3015" title: "Compiler Error C3015" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3015" +ms.date: 11/04/2016 f1_keywords: ["C3015"] helpviewer_keywords: ["C3015"] -ms.assetid: d5e8e50b-7542-4b2d-8665-1b22072a5bc6 --- # Compiler Error C3015 -initialization in OpenMP 'for' statement has improper form +> initialization in OpenMP 'for' statement has improper form + +## Remarks A **`for`** loop in an OpenMP statement must be fully and explicitly specified. -The following sample generates C3015: +## Example + +The following example generates C3015: ```cpp // C3015.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3016.md b/docs/error-messages/compiler-errors-2/compiler-error-c3016.md index ef990e16bb7..4da397545bc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3016.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3016.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3016" title: "Compiler Error C3016" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3016" +ms.date: 11/04/2016 f1_keywords: ["C3016"] helpviewer_keywords: ["C3016"] -ms.assetid: 3423467e-e8bb-4f35-b4db-7925cafa74c1 --- # Compiler Error C3016 -'var' : index variable in OpenMP 'for' statement must have signed integral type +> 'var' : index variable in OpenMP 'for' statement must have signed integral type + +## Remarks The index variable in an OpenMP **`for`** statement must be a signed integral type. -The following sample generates C3016: +## Example + +The following example generates C3016: ```cpp // C3016.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3017.md b/docs/error-messages/compiler-errors-2/compiler-error-c3017.md index 35ffc5aecf9..5a9bcff8460 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3017.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3017.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3017" title: "Compiler Error C3017" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3017" +ms.date: 11/04/2016 f1_keywords: ["C3017"] helpviewer_keywords: ["C3017"] -ms.assetid: 12ab2c2a-d0d2-4900-9cbf-39be0af590dd --- # Compiler Error C3017 -termination test in OpenMP 'for' statement has improper form +> termination test in OpenMP 'for' statement has improper form + +## Remarks A **`for`** loop in an OpenMP statement must be fully and explicitly specified. -The following sample generates C3017: +## Example + +The following example generates C3017: ```cpp // C3017.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3018.md b/docs/error-messages/compiler-errors-2/compiler-error-c3018.md index 9843c07518c..4dc33cbf6a4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3018.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3018.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3018" title: "Compiler Error C3018" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3018" +ms.date: 11/04/2016 f1_keywords: ["C3018"] helpviewer_keywords: ["C3018"] -ms.assetid: 685be45f-f116-43a8-a88d-05ab6616e2f1 --- # Compiler Error C3018 -'var1' : OpenMP 'for' test or increment must use index variable 'var2' +> 'var1' : OpenMP 'for' test or increment must use index variable 'var2' + +## Remarks A **`for`** loop in an OpenMP statement must use the same variable for its test and increment as it uses for its index. -The following sample generates C3018: +## Example + +The following example generates C3018: ```cpp // C3018.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3019.md b/docs/error-messages/compiler-errors-2/compiler-error-c3019.md index 72a6e03a165..ad39fe669ac 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3019.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3019.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3019" title: "Compiler Error C3019" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3019" +ms.date: 11/04/2016 f1_keywords: ["C3019"] helpviewer_keywords: ["C3019"] -ms.assetid: 31a6d9b6-d29f-4499-9ad8-48dd751e87c7 --- # Compiler Error C3019 -increment in OpenMP 'for' statement has improper form +> increment in OpenMP 'for' statement has improper form + +## Remarks The increment part of an OpenMP **`for`** loop must use the index variable both on the left and right side of the operator. -The following sample generates C3019: +## Example + +The following example generates C3019: ```cpp // C3019.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3020.md b/docs/error-messages/compiler-errors-2/compiler-error-c3020.md index 4f67e28e54e..ca7e3d3f787 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3020.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3020.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3020" title: "Compiler Error C3020" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3020" +ms.date: 11/04/2016 f1_keywords: ["C3020"] helpviewer_keywords: ["C3020"] -ms.assetid: f625c7a3-afaa-4bd8-9c1b-51891b832f36 --- # Compiler Error C3020 -'var' : index variable of OpenMP 'for' loop cannot be modified in loop body +> 'var' : index variable of OpenMP 'for' loop cannot be modified in loop body + +## Remarks An OpenMP **`for`** loop may not modify the index (loop counter) in the body of the **`for`** loop. -The following sample generates C3020: +## Examples + +The following example generates C3020: ```cpp // C3020.cpp @@ -33,7 +36,7 @@ int main() { A variable declared with [lastprivate](../../parallel/openmp/reference/openmp-clauses.md#lastprivate) cannot be used as the index inside a parallelized loop. -The following sample will give C3020 for the second lastprivate because that lastprivate will trigger a write to idx_a within the outermost for loop. The first lastprivate doesn't give an error because that lastprivate triggers a write to idx_a outside the outermost for loop (technically, at the very end of the last iteration). The following sample generates C3020. +The following example will give C3020 for the second lastprivate because that lastprivate will trigger a write to idx_a within the outermost for loop. The first lastprivate doesn't give an error because that lastprivate triggers a write to idx_a outside the outermost for loop (technically, at the very end of the last iteration). The following example generates C3020. ```cpp // C3020b.cpp @@ -52,7 +55,7 @@ void test(int first, int last) } ``` -The following sample demonstrates a possible resolution: +The following example demonstrates a possible resolution: ```cpp // C3020c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3021.md b/docs/error-messages/compiler-errors-2/compiler-error-c3021.md index 5a016f5608e..c144f991470 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3021.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3021.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3021" title: "Compiler Error C3021" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3021" +ms.date: 11/04/2016 f1_keywords: ["C3021"] helpviewer_keywords: ["C3021"] -ms.assetid: 0cef6d97-e267-438a-ac8b-0daf5bbbc2cf --- # Compiler Error C3021 -'arg' : argument is empty on OpenMP directive 'directive' +> 'arg' : argument is empty on OpenMP directive 'directive' + +## Remarks An argument is required for an OpenMP directive. ## Example -The following sample generates C3021: +The following example generates C3021: ```cpp // C3021.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3022.md b/docs/error-messages/compiler-errors-2/compiler-error-c3022.md index ca6749b8abb..a833519ab11 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3022.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3022.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3022" title: "Compiler Error C3022" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3022" +ms.date: 11/04/2016 f1_keywords: ["C3022"] helpviewer_keywords: ["C3022"] -ms.assetid: 9f1d444c-6c6e-48d9-9346-69128390aa33 --- # Compiler Error C3022 -'clause' : invalid schedule kind of 'value' on OpenMP 'directive' directive +> 'clause' : invalid schedule kind of 'value' on OpenMP 'directive' directive + +## Remarks An unsupported value was passed to a clause. -The following sample generates C3022: +## Example + +The following example generates C3022: ```cpp // C3022.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3023.md b/docs/error-messages/compiler-errors-2/compiler-error-c3023.md index 5cc79ab4b52..76419763f3a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3023.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3023.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3023" title: "Compiler Error C3023" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3023" +ms.date: 11/04/2016 f1_keywords: ["C3023"] helpviewer_keywords: ["C3023"] -ms.assetid: 89dcce98-3cd7-4931-a50f-87df1d2ebc9b --- # Compiler Error C3023 -'value' : unexpected token encountered in argument to OpenMP 'clause' clause +> 'value' : unexpected token encountered in argument to OpenMP 'clause' clause + +## Remarks The values passed to a clause were not valid. -The following sample generates C3023: +## Example + +The following example generates C3023: ```cpp // C3023.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3024.md b/docs/error-messages/compiler-errors-2/compiler-error-c3024.md index a9c91358b3c..4fd7152b8fb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3024.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3024.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3024" title: "Compiler Error C3024" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3024" +ms.date: 11/04/2016 f1_keywords: ["C3024"] helpviewer_keywords: ["C3024"] -ms.assetid: 1c031c28-ce37-4de3-aead-cfe76b261856 --- # Compiler Error C3024 -'schedule(runtime)' : chunk_size expression is not allowed +> 'schedule(runtime)' : chunk_size expression is not allowed + +## Remarks A value cannot be passed to the run-time parameter of the schedule clause. -The following sample generates C3024: +## Example + +The following example generates C3024: ```cpp // C3024.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3025.md b/docs/error-messages/compiler-errors-2/compiler-error-c3025.md index ef52fb54153..5f8148aa80d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3025.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3025.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3025" title: "Compiler Error C3025" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3025" +ms.date: 11/04/2016 f1_keywords: ["C3025"] helpviewer_keywords: ["C3025"] -ms.assetid: 4442f5a3-d9ea-4873-b1fb-e7e5bd3cbe5e --- # Compiler Error C3025 -'clause' : integral expression expected +> 'clause' : integral expression expected + +## Remarks A clause requires an integer expression but was given a noninteger expression. ## Example -The following sample generates C3025. +The following example generates C3025. ```cpp // C3025.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3026.md b/docs/error-messages/compiler-errors-2/compiler-error-c3026.md index cf7c5487239..458980db4a8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3026.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3026.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3026" title: "Compiler Error C3026" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3026" +ms.date: 11/04/2016 f1_keywords: ["C3026"] helpviewer_keywords: ["C3026"] -ms.assetid: 3297060e-cc5b-4600-a2db-09bfc4ffa21f --- # Compiler Error C3026 -'clause' : constant expression must be positive +> 'clause' : constant expression must be positive + +## Remarks A clause was passed an integer value, but the value was not a positive number. The number must be positive. ## Example -The following sample generates C3026: +The following example generates C3026: ```cpp // C3026.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3027.md b/docs/error-messages/compiler-errors-2/compiler-error-c3027.md index 8276f6de600..853563e4b62 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3027.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3027.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3027" title: "Compiler Error C3027" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3027" +ms.date: 11/04/2016 f1_keywords: ["C3027"] helpviewer_keywords: ["C3027"] -ms.assetid: 6562a5c2-2f28-4b36-91ca-2a64c0f0501a --- # Compiler Error C3027 -'clause' : arithmetic or pointer expression expected +> 'clause' : arithmetic or pointer expression expected + +## Remarks A clause that requires an arithmetic or pointer expression was passed another kind of expression. ## Example -The following sample generates C3027: +The following example generates C3027: ```cpp // C3027.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3028.md b/docs/error-messages/compiler-errors-2/compiler-error-c3028.md index d64d33f2004..c4a24a6afbe 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3028.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3028.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3028" title: "Compiler Error C3028" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3028" +ms.date: 11/04/2016 f1_keywords: ["C3028"] helpviewer_keywords: ["C3028"] -ms.assetid: 175e697f-8e8f-492a-8456-6240ffbbb900 --- # Compiler Error C3028 -'member' : only a variable or static data member can be used in a data-sharing clause +> 'member' : only a variable or static data member can be used in a data-sharing clause + +## Remarks A symbol other than a variable or static data member was passed to the reduction clause. -The following sample generates C3028: +## Example + +The following example generates C3028: ```cpp // C3028.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3029.md b/docs/error-messages/compiler-errors-2/compiler-error-c3029.md index 8b2b019ed48..a92c60fda2a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3029.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3029.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3029" title: "Compiler Error C3029" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3029" +ms.date: 11/04/2016 f1_keywords: ["C3029"] helpviewer_keywords: ["C3029"] -ms.assetid: 655eb04d-504a-468d-8c0c-bda1e5f297b7 --- # Compiler Error C3029 -'symbol' : can only appear once in data-sharing clauses in an OpenMP directive +> 'symbol' : can only appear once in data-sharing clauses in an OpenMP directive + +## Remarks A symbol was used more than once in one or more clauses in a directive. The symbol can only be used once in the directive. -The following sample generates C3029: +## Example + +The following example generates C3029: ```cpp // C3029.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3030.md b/docs/error-messages/compiler-errors-2/compiler-error-c3030.md index daf295ebe76..96dde7dad6e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3030.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3030.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3030" title: "Compiler Error C3030" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3030" +ms.date: 11/04/2016 f1_keywords: ["C3030"] helpviewer_keywords: ["C3030"] -ms.assetid: de92fd7e-29ba-46e8-b43b-f4b985cd74de --- # Compiler Error C3030 -'var' : variable in 'reduction' clause/directive cannot have reference type +> 'var' : variable in 'reduction' clause/directive cannot have reference type + +## Remarks You can only pass value parameters to certain clauses, such as the reduction clause. -The following sample generates C3030: +## Example + +The following example generates C3030: ```cpp // C3030.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3031.md b/docs/error-messages/compiler-errors-2/compiler-error-c3031.md index ad1689a82f3..583e25e206f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3031.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3031.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3031" title: "Compiler Error C3031" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3031" +ms.date: 11/04/2016 f1_keywords: ["C3031"] helpviewer_keywords: ["C3031"] -ms.assetid: 7e621e7e-eda7-45b5-8836-29599cd05255 --- # Compiler Error C3031 -'var' : variable in 'reduction' clause must have scalar arithmetic type +> 'var' : variable in 'reduction' clause must have scalar arithmetic type + +## Remarks A variable of the wrong type was passed to a reduction clause. -The following sample generates C3031: +## Example + +The following example generates C3031: ```cpp // C3031.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3032.md b/docs/error-messages/compiler-errors-2/compiler-error-c3032.md index 0feba15df8c..02ada4cb731 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3032.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3032.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3032" title: "Compiler Error C3032" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3032" +ms.date: 11/04/2016 f1_keywords: ["C3032"] helpviewer_keywords: ["C3032"] -ms.assetid: 6a92bd8e-319f-4a99-aef4-a9021f6f9928 --- # Compiler Error C3032 -'var' : variable in 'clause' clause cannot have incomplete type 'type' +> 'var' : variable in 'clause' clause cannot have incomplete type 'type' + +## Remarks Types passed to certain clauses must be fully visible to the compiler. -The following sample generates C3032: +## Example + +The following example generates C3032: ```cpp // C3032.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3033.md b/docs/error-messages/compiler-errors-2/compiler-error-c3033.md index b1dcebc9f78..420ba6376bd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3033.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3033.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3033" title: "Compiler Error C3033" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3033" +ms.date: 11/04/2016 f1_keywords: ["C3033"] helpviewer_keywords: ["C3033"] -ms.assetid: 8628b6bb-a650-4ed2-af13-57acd2f7ddbb --- # Compiler Error C3033 -'var' : variable in 'clause' clause cannot have const-qualified type +> 'var' : variable in 'clause' clause cannot have const-qualified type + +## Remarks Values passed to certain clauses cannot be **`const`** variables. -The following sample generates C3033: +## Example + +The following example generates C3033: ```cpp // C3033.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3034.md b/docs/error-messages/compiler-errors-2/compiler-error-c3034.md index c6581ba1b3e..9d76496fe4f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3034.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3034.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3034" title: "Compiler Error C3034" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3034" +ms.date: 11/04/2016 f1_keywords: ["C3034"] helpviewer_keywords: ["C3034"] -ms.assetid: 49db8bac-2720-4622-94e3-7988f1603fa3 --- # Compiler Error C3034 -OpenMP 'directive1' directive cannot be directly nested within 'directive2' directive +> OpenMP 'directive1' directive cannot be directly nested within 'directive2' directive + +## Remarks Some directives cannot be nested. To fix this error, you can merge the statements of both directives into the block of one directive, or you can construct consecutive directives. -The following sample generates C3034: +## Example + +The following example generates C3034: ```cpp // C3034.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3035.md b/docs/error-messages/compiler-errors-2/compiler-error-c3035.md index 3fcf1e25f17..fd2006a31d5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3035.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3035.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3035" title: "Compiler Error C3035" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3035" +ms.date: 11/04/2016 f1_keywords: ["C3035"] helpviewer_keywords: ["C3035"] -ms.assetid: af34fad2-2b45-42d0-a9ff-04eab3e91c37 --- # Compiler Error C3035 -OpenMP 'ordered' directive must bind directly to a 'for' or 'parallel for' directive with the 'ordered' clause +> OpenMP 'ordered' directive must bind directly to a 'for' or 'parallel for' directive with the 'ordered' clause + +## Remarks An ordered clause was ill formed. -The following sample generates C3035: +## Example + +The following example generates C3035: ```cpp // C3035.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3036.md b/docs/error-messages/compiler-errors-2/compiler-error-c3036.md index 597adf0ff4f..0584a878e54 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3036.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3036.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3036" title: "Compiler Error C3036" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3036" +ms.date: 11/04/2016 f1_keywords: ["C3036"] helpviewer_keywords: ["C3036"] -ms.assetid: 10c6993e-bc42-4a07-85c7-cdc34ac30906 --- # Compiler Error C3036 -'operator' : invalid operator token in OpenMP 'reduction' clause +> 'operator' : invalid operator token in OpenMP 'reduction' clause + +## Remarks A [reduction](../../parallel/openmp/reference/openmp-clauses.md#reduction) clause was not specified correctly. -The following sample generates C3036: +## Example + +The following example generates C3036: ```cpp // C3036.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3037.md b/docs/error-messages/compiler-errors-2/compiler-error-c3037.md index 13cb9a96f50..fce1f7b9649 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3037.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3037.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3037" title: "Compiler Error C3037" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3037" +ms.date: 11/04/2016 f1_keywords: ["C3037"] helpviewer_keywords: ["C3037"] -ms.assetid: 9ba8a890-d3c7-4cce-93c5-d358e2bfad28 --- # Compiler Error C3037 -'var' : variable in 'reduction' clause must be shared in enclosing context +> 'var' : variable in 'reduction' clause must be shared in enclosing context + +## Remarks A variable specified in a [reduction](../../parallel/openmp/reference/openmp-clauses.md#reduction) clause may not be private to each thread in the context. -The following sample generates C3037: +## Example + +The following example generates C3037: ```cpp // C3037.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3038.md b/docs/error-messages/compiler-errors-2/compiler-error-c3038.md index 1219fcdd1e3..9819029d531 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3038.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3038.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3038" title: "Compiler Error C3038" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3038" +ms.date: 11/04/2016 f1_keywords: ["C3038"] helpviewer_keywords: ["C3038"] -ms.assetid: 140ada3e-5636-43ef-a4ee-22a9f66a771f --- # Compiler Error C3038 -'var' : variable in 'private' clause cannot be a reduction variable in enclosing context +> 'var' : variable in 'private' clause cannot be a reduction variable in enclosing context + +## Remarks Variables that appear in the [reduction](../../parallel/openmp/reference/openmp-clauses.md#reduction) clause of a parallel directive cannot be specified in a [private](../../parallel/openmp/reference/openmp-clauses.md#private-openmp) clause on a work-sharing directive that binds to the parallel construct. -The following sample generates C3038: +## Example + +The following example generates C3038: ```cpp // C3038.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3039.md b/docs/error-messages/compiler-errors-2/compiler-error-c3039.md index c5029592752..92bc1abf4be 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3039.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3039.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3039" title: "Compiler Error C3039" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3039" +ms.date: 11/04/2016 f1_keywords: ["C3039"] helpviewer_keywords: ["C3039"] -ms.assetid: 02776f16-f57a-4ffd-b7f7-9c696b633e08 --- # Compiler Error C3039 -'var' : index variable in OpenMP 'for' statement cannot be a reduction variable +> 'var' : index variable in OpenMP 'for' statement cannot be a reduction variable + +## Remarks An index variable is implicitly private, so the variable cannot be used in a [reduction](../../parallel/openmp/reference/openmp-clauses.md#reduction) clause in the enclosing [parallel](../../parallel/openmp/reference/openmp-directives.md#parallel) directive. ## Example -The following sample generates C3039: +The following example generates C3039: ```cpp // C3039.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3040.md b/docs/error-messages/compiler-errors-2/compiler-error-c3040.md index 33c117e5f43..82f04a80bcd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3040.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3040.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3040" title: "Compiler Error C3040" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3040" +ms.date: 11/04/2016 f1_keywords: ["C3040"] helpviewer_keywords: ["C3040"] -ms.assetid: 29e857ac-74f0-4ec6-becf-9026e38c160e --- # Compiler Error C3040 -'var' : type of variable in 'reduction' clause is incompatible with reduction operator 'operator' +> 'var' : type of variable in 'reduction' clause is incompatible with reduction operator 'operator' + +## Remarks A variable in a [reduction](../../parallel/openmp/reference/openmp-clauses.md#reduction) clause cannot be used with the reduction operator. -The following sample generates C3040: +## Example + +The following example generates C3040: ```cpp // C3040.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3041.md b/docs/error-messages/compiler-errors-2/compiler-error-c3041.md index fb2a1a285d7..5c60eb3ff1a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3041.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3041.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3041" title: "Compiler Error C3041" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3041" +ms.date: 11/04/2016 f1_keywords: ["C3041"] helpviewer_keywords: ["C3041"] -ms.assetid: 9df1ae44-3ac7-4c6c-899f-f35ffe7ccf0d --- # Compiler Error C3041 -'var' : variable in 'copyprivate' clause must be private in enclosing context +> 'var' : variable in 'copyprivate' clause must be private in enclosing context + +## Remarks A variable passed to [copyprivate](../../parallel/openmp/reference/openmp-clauses.md#copyprivate) cannot be shared in the enclosing context. -The following sample generates C3041: +## Example + +The following example generates C3041: ```cpp // C3041.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3042.md b/docs/error-messages/compiler-errors-2/compiler-error-c3042.md index ba13716ff03..8b52b9ae987 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3042.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3042.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3042" title: "Compiler Error C3042" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3042" +ms.date: 11/04/2016 f1_keywords: ["C3042"] helpviewer_keywords: ["C3042"] -ms.assetid: bf73f61e-5bd2-40a8-9b06-6244e6a15a41 --- # Compiler Error C3042 -'copyprivate' and 'nowait' clauses cannot appear together on OpenMP 'directive' directive +> 'copyprivate' and 'nowait' clauses cannot appear together on OpenMP 'directive' directive + +## Remarks The [copyprivate](../../parallel/openmp/reference/openmp-clauses.md#copyprivate) and [nowait](../../parallel/openmp/reference/openmp-clauses.md#nowait) clauses are mutually exclusive on the specified directive. To fix this error, remove one or both of the `copyprivate` or `nowait` clauses. -The following sample generates C3042: +## Example + +The following example generates C3042: ```cpp // C3042.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3043.md b/docs/error-messages/compiler-errors-2/compiler-error-c3043.md index 2e2a807aa5e..ceb6883d661 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3043.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3043.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3043" title: "Compiler Error C3043" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3043" +ms.date: 11/04/2016 f1_keywords: ["C3043"] helpviewer_keywords: ["C3043"] -ms.assetid: 0ef55e63-e82b-48eb-9d44-690950ac34c6 --- # Compiler Error C3043 -OpenMP 'critical' directive cannot be nested in 'critical' directive with same name +> OpenMP 'critical' directive cannot be nested in 'critical' directive with same name + +## Remarks A [critical](../../parallel/openmp/reference/openmp-directives.md#critical) directive cannot be nested in a `critical` directive that uses the same name. -The following sample generates C3043: +## Example + +The following example generates C3043: ```cpp // C3043.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3044.md b/docs/error-messages/compiler-errors-2/compiler-error-c3044.md index 26b146188d2..ae3ed18c230 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3044.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3044.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3044" title: "Compiler Error C3044" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3044" +ms.date: 11/04/2016 f1_keywords: ["C3044"] helpviewer_keywords: ["C3044"] -ms.assetid: 9f3e25b2-4676-49ab-97bf-6c88cd0fa377 --- # Compiler Error C3044 -'section' : only allowed directly nested under an OpenMP 'sections' directive +> 'section' : only allowed directly nested under an OpenMP 'sections' directive + +## Remarks The compiler found a `section` directive was used incorrectly. For more information, see [sections](../../parallel/openmp/reference/openmp-directives.md#sections-openmp). -The following sample generates C3044: +## Example + +The following example generates C3044: ```cpp // C3044.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3045.md b/docs/error-messages/compiler-errors-2/compiler-error-c3045.md index 67891c401ee..6c59aff18d6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3045.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3045.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3045" title: "Compiler Error C3045" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3045" +ms.date: 11/04/2016 f1_keywords: ["C3045"] helpviewer_keywords: ["C3045"] -ms.assetid: 9351ba3e-3d3f-455f-ac90-a810fa9fd947 --- # Compiler Error C3045 -Expected a compound statement following OpenMP 'sections' directive. Missing '{' +> Expected a compound statement following OpenMP 'sections' directive. Missing '{' + +## Remarks A code block delimited by braces must follow a [sections](../../parallel/openmp/reference/openmp-directives.md#sections-openmp) directive. -The following sample generates C3045: +## Example + +The following example generates C3045: ```cpp // C3045.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3046.md b/docs/error-messages/compiler-errors-2/compiler-error-c3046.md index da74cf83c76..3633da04abd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3046.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3046.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3046" title: "Compiler Error C3046" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3046" +ms.date: 11/04/2016 f1_keywords: ["C3046"] helpviewer_keywords: ["C3046"] -ms.assetid: 2e53d835-faa1-4ec0-9807-41f3dc552635 --- # Compiler Error C3046 -Missing structured block in an OpenMP '#pragma omp sections' region +> Missing structured block in an OpenMP '#pragma omp sections' region + +## Remarks A [sections](../../parallel/openmp/reference/openmp-directives.md#sections-openmp) directive has an empty code block. -The following sample generates C3046: +## Example + +The following example generates C3046: ```cpp // C3046.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3047.md b/docs/error-messages/compiler-errors-2/compiler-error-c3047.md index 33412373c1d..850e45397bb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3047.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3047.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3047" title: "Compiler Error C3047" +description: "Learn more about: Compiler Error C3047" ms.date: 06/01/2022 f1_keywords: ["C3047"] helpviewer_keywords: ["C3047"] -ms.assetid: 91c14566-5958-433d-8549-0e8bc3196f76 --- # Compiler Error C3047 > Structured block in an OpenMP 'sections' region must be preceded by '#pragma omp section' +## Remarks + Any code in a code block introduced by a [sections](../../parallel/openmp/reference/openmp-directives.md#sections-openmp) directive must be in a code block introduced by a `section` directive. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C3047: +## Example + +The following example generates C3047: ```cpp // C3047.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3048.md b/docs/error-messages/compiler-errors-2/compiler-error-c3048.md index 62ceeb6d4e4..20c553cc781 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3048.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3048.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3048" title: "Compiler Error C3048" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3048" +ms.date: 11/04/2016 f1_keywords: ["C3048"] helpviewer_keywords: ["C3048"] -ms.assetid: 48e07091-94d9-471d-befe-7e2507631edd --- # Compiler Error C3048 -Expression following '#pragma omp atomic' has improper form +> Expression following '#pragma omp atomic' has improper form + +## Remarks An atomic directive was incorrectly specified. -The following sample generates C3048: +## Example + +The following example generates C3048: ```cpp // C3048.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3049.md b/docs/error-messages/compiler-errors-2/compiler-error-c3049.md index 3b87b0f3746..b89c25bb6dc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3049.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3049.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3049" title: "Compiler Error C3049" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3049" +ms.date: 11/04/2016 f1_keywords: ["C3049"] helpviewer_keywords: ["C3049"] -ms.assetid: 6ddf54f6-2c30-4d04-b637-98c6c922c533 --- # Compiler Error C3049 -'arg' : invalid argument in OpenMP 'default' clause +> 'arg' : invalid argument in OpenMP 'default' clause + +## Remarks An incorrect value was passed to a [default](../../parallel/openmp/reference/openmp-clauses.md#default-openmp) clause. -The following sample generates C3049: +## Example + +The following example generates C3049: ```cpp // C3049.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3050.md b/docs/error-messages/compiler-errors-2/compiler-error-c3050.md index 95167d41bce..853b205551f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3050.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3050.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3050" title: "Compiler Error C3050" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3050" +ms.date: 11/04/2016 f1_keywords: ["C3050"] helpviewer_keywords: ["C3050"] -ms.assetid: ee090a0b-29cc-4215-a2f9-d82af79b8e82 --- # Compiler Error C3050 -'type1' : a ref class cannot inherit from 'type1' +> 'type1' : a ref class cannot inherit from 'type1' + +## Remarks `System::ValueType` cannot be a base class for a reference type. -The following sample generates C3050: +## Example + +The following example generates C3050: ```cpp // C3050.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3052.md b/docs/error-messages/compiler-errors-2/compiler-error-c3052.md index 2eaaa547883..57d7f03c1d8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3052.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3052.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3052" title: "Compiler Error C3052" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3052" +ms.date: 11/04/2016 f1_keywords: ["C3052"] helpviewer_keywords: ["C3052"] -ms.assetid: 87480c42-1ceb-4775-8d20-88c54a7bb6a6 --- # Compiler Error C3052 -'var' : variable doesn't appear in a data-sharing clause under a default(none) clause +> 'var' : variable doesn't appear in a data-sharing clause under a default(none) clause + +## Remarks If [default(none)](../../parallel/openmp/reference/openmp-clauses.md#default-openmp) is used, any variable used in the structured block must be explicitly specified as either [shared](../../parallel/openmp/reference/openmp-clauses.md#shared-openmp) or [private](../../parallel/openmp/reference/openmp-clauses.md#private-openmp). -The following sample generates C3052: +## Example + +The following example generates C3052: ```cpp // C3052.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3053.md b/docs/error-messages/compiler-errors-2/compiler-error-c3053.md index e2ca4233799..62bcc0b3055 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3053.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3053.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3053" title: "Compiler Error C3053" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3053" +ms.date: 11/04/2016 f1_keywords: ["C3053"] helpviewer_keywords: ["C3053"] -ms.assetid: ab9a25f3-e341-4f6e-8e69-069b4a963a64 --- # Compiler Error C3053 -'symbol' : 'threadprivate' is only valid for global or static data items +> 'symbol' : 'threadprivate' is only valid for global or static data items + +## Remarks Symbols passed to [threadprivate](../../parallel/openmp/reference/openmp-directives.md#threadprivate) must either be global or static. -The following sample generates C3053: +## Example + +The following example generates C3053: ```cpp // C3053.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3054.md b/docs/error-messages/compiler-errors-2/compiler-error-c3054.md index 4961c563e50..be1a516fcf8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3054.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3054.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3054" title: "Compiler Error C3054" +description: "Learn more about: Compiler Error C3054" ms.date: 06/01/2022 f1_keywords: ["C3054"] helpviewer_keywords: ["C3054"] -ms.assetid: 6f4b7ac5-0d12-474b-b611-76ff26ee41ac --- # Compiler Error C3054 @@ -18,7 +17,7 @@ This error is obsolete in Visual Studio 2022 and later versions. ## Example -The following sample generates C3054. +The following example generates C3054. ```cpp // C3054.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3055.md b/docs/error-messages/compiler-errors-2/compiler-error-c3055.md index a3e046633f4..c27fbebbe56 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3055.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3055.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3055" title: "Compiler Error C3055" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3055" +ms.date: 11/04/2016 f1_keywords: ["C3055"] helpviewer_keywords: ["C3055"] -ms.assetid: 60446ee0-18dd-48fc-9059-f0a14229dce8 --- # Compiler Error C3055 -'symbol' : symbol cannot be referenced before it is used in 'threadprivate' directive +> 'symbol' : symbol cannot be referenced before it is used in 'threadprivate' directive + +## Remarks A symbol was referenced and then used in a [threadprivate](../../parallel/openmp/reference/openmp-directives.md#threadprivate) clause, which is not allowed. -The following sample generates C3055: +## Example + +The following example generates C3055: ```cpp // C3055.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3056.md b/docs/error-messages/compiler-errors-2/compiler-error-c3056.md index cf9e92e01a6..48b72cc3463 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3056.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3056.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3056" title: "Compiler Error C3056" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3056" +ms.date: 11/04/2016 f1_keywords: ["C3056"] helpviewer_keywords: ["C3056"] -ms.assetid: 9500173d-870b-49b3-8e88-0ee93586d19a --- # Compiler Error C3056 -'symbol' : symbol is not in the same scope with 'threadprivate' directive +> 'symbol' : symbol is not in the same scope with 'threadprivate' directive + +## Remarks A symbol used in a [threadprivate](../../parallel/openmp/reference/openmp-directives.md#threadprivate) clause must be in the same scope as the `threadprivate` clause. -The following sample generates C3056: +## Example + +The following example generates C3056: ```cpp // C3056.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3057.md b/docs/error-messages/compiler-errors-2/compiler-error-c3057.md index e2b10e3f31f..009ad60d670 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3057.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3057.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3057" title: "Compiler Error C3057" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3057" +ms.date: 11/04/2016 f1_keywords: ["C3057"] helpviewer_keywords: ["C3057"] -ms.assetid: b0b2ba88-9c74-4bec-bf60-8fc72eade34c --- # Compiler Error C3057 -'symbol' : dynamic initialization of 'threadprivate' symbols is not currently supported +> 'symbol' : dynamic initialization of 'threadprivate' symbols is not currently supported + +## Remarks The initialized value of a symbol used in a [threadprivate](../../parallel/openmp/reference/openmp-directives.md#threadprivate) clause must be known at compile time. -The following sample generates C3057: +## Examples + +The following example generates C3057: ```cpp // C3057.cpp @@ -38,7 +41,7 @@ int main() { } ``` -The following sample generates C3057: +The following example generates C3057: ```cpp // C3057b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3058.md b/docs/error-messages/compiler-errors-2/compiler-error-c3058.md index 2e52864c0de..b02ea0b7cd4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3058.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3058.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3058" title: "Compiler Error C3058" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3058" +ms.date: 11/04/2016 f1_keywords: ["C3058"] helpviewer_keywords: ["C3058"] -ms.assetid: 669d08c8-0b58-4351-88aa-c6e6e1af481c --- # Compiler Error C3058 -'symbol' : symbol not declared as 'threadprivate' before it is used in the 'copyin' clause +> 'symbol' : symbol not declared as 'threadprivate' before it is used in the 'copyin' clause + +## Remarks A symbol must first be declared [threadprivate](../../parallel/openmp/reference/openmp-directives.md#threadprivate) before it can be used in a [copyin](../../parallel/openmp/reference/openmp-clauses.md#copyin) clause. -The following sample generates C3058: +## Example + +The following example generates C3058: ```cpp // C3058.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3059.md b/docs/error-messages/compiler-errors-2/compiler-error-c3059.md index 0385160ecf1..d7518ccc873 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3059.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3059.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3059" title: "Compiler Error C3059" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3059" +ms.date: 11/04/2016 f1_keywords: ["C3059"] helpviewer_keywords: ["C3059"] -ms.assetid: 57220324-8286-4cab-a1ab-45385eb1eae0 --- # Compiler Error C3059 -'var' : 'threadprivate' symbol cannot be used in the 'clause' clause +> 'var' : 'threadprivate' symbol cannot be used in the 'clause' clause + +## Remarks A [threadprivate](../../parallel/openmp/reference/openmp-directives.md#threadprivate) symbol was used in a clause. -The following sample generates C3059: +## Example + +The following example generates C3059: ```cpp // C3059.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3060.md b/docs/error-messages/compiler-errors-2/compiler-error-c3060.md index 56687093106..1745f7c3480 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3060.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3060.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3060" title: "Compiler Error C3060" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3060" +ms.date: 11/04/2016 f1_keywords: ["C3060"] helpviewer_keywords: ["C3060"] -ms.assetid: 6282bb92-0546-4b59-9435-d3840bf93bdb --- # Compiler Error C3060 -'member' : a friend function may not be defined inside a class using a qualified name (it may only be declared) +> 'member' : a friend function may not be defined inside a class using a qualified name (it may only be declared) + +## Remarks A friend function was defined using a qualified name, which is not allowed. -The following sample generates C3060: +## Example + +The following example generates C3060: ```cpp // C3060.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3062.md b/docs/error-messages/compiler-errors-2/compiler-error-c3062.md index ecd02c05848..bb87d31e352 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3062.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3062.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3062" title: "Compiler Error C3062" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3062" +ms.date: 11/04/2016 f1_keywords: ["C3062"] helpviewer_keywords: ["C3062"] -ms.assetid: 78632e6d-255f-42c3-b124-31a9194ff86d --- # Compiler Error C3062 -'enum': enumerator requires value since the underlying type is 'type' +> 'enum': enumerator requires value since the underlying type is 'type' + +## Remarks You can specify an underlying type for an enumeration. However, some types require you to assign values to each enumerator. For more information on enums, see [enum class](../../extensions/enum-class-cpp-component-extensions.md). -The following sample generates C3062: +## Example + +The following example generates C3062: ```cpp // C3062.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3063.md b/docs/error-messages/compiler-errors-2/compiler-error-c3063.md index 14672ef7f5f..00e1890b694 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3063.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3063.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3063" title: "Compiler Error C3063" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3063" +ms.date: 11/04/2016 f1_keywords: ["C3063"] helpviewer_keywords: ["C3063"] -ms.assetid: 0ecf6f1f-e4a7-487a-9fd5-79d8ac470001 --- # Compiler Error C3063 -operator 'operator': all operands must have the same enumeration type +> operator 'operator': all operands must have the same enumeration type + +## Remarks When using operators on enumerators, both operands must be of the enumeration type. For more information, see [How to: Define and consume enums in C++/CLI](../../dotnet/how-to-define-and-consume-enums-in-cpp-cli.md). ## Example -The following sample generates C3063 and shows how to fix it: +The following example generates C3063 and shows how to fix it: ```cpp // C3063.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3065.md b/docs/error-messages/compiler-errors-2/compiler-error-c3065.md index 38985064a54..6c8a2fdb26e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3065.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3065.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3065" title: "Compiler Error C3065" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3065" +ms.date: 11/04/2016 f1_keywords: ["C3065"] helpviewer_keywords: ["C3065"] -ms.assetid: e7a0bc69-1c68-459e-a7c4-93c65609ff7c --- # Compiler Error C3065 -property declaration at non-class scope is not allowed +> property declaration at non-class scope is not allowed + +## Remarks The [property](../../cpp/property-cpp.md) __declspec modifier was used outside a class. A property can only be declared inside a class. -The following sample generates C3065: +## Example + +The following example generates C3065: ```cpp // C3065.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3066.md b/docs/error-messages/compiler-errors-2/compiler-error-c3066.md index 59508836a8e..2829acc296f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3066.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3066.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3066" title: "Compiler Error C3066" -ms.date: "03/28/2017" +description: "Learn more about: Compiler Error C3066" +ms.date: 03/28/2017 f1_keywords: ["C3066"] helpviewer_keywords: ["C3066"] -ms.assetid: 226f6de5-c4c5-41e2-b31a-2e30a37fbbeb --- # Compiler Error C3066 -there are multiple ways that an object of this type can be called with these arguments +> there are multiple ways that an object of this type can be called with these arguments + +## Remarks The compiler detected an ambiguous function call involving surrogates. -The following sample generates C3066: +## Examples + +The following example generates C3066: ```cpp // C3066.cpp @@ -46,12 +49,12 @@ int main() { } ``` -## Copy-list-initialization +### Copy-list-initialization In Visual Studio 2015, the compiler erroneously treated copy-list-initialization in the same way as regular copy-initialization; it considered only converting constructors for overload resolution. In the following example, Visual Studio 2015 chooses MyInt(23) but Visual Studio 2017 correctly raises the error. ``` -// From http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_closed.html#1228 +// From https://www.open-std.org/jtc1/sc22/wg21/docs/cwg_closed.html#1228 struct MyList { explicit MyStore(int initialCapacity); }; diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3068.md b/docs/error-messages/compiler-errors-2/compiler-error-c3068.md index ef02c390227..70488a70967 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3068.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3068.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3068" title: "Compiler Error C3068" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3068" +ms.date: 11/04/2016 f1_keywords: ["C3068"] helpviewer_keywords: ["C3068"] -ms.assetid: 613e3447-b4a8-4268-a661-297bed63ccdf --- # Compiler Error C3068 -'function' : a 'naked' function cannot contain objects that would require unwinding if a C++ exception occurred +> 'function' : a 'naked' function cannot contain objects that would require unwinding if a C++ exception occurred + +## Remarks The compiler was unable to perform stack unwinding on a [naked](../../cpp/naked-cpp.md) function that threw an exception because a temporary object was created in the function and C++ exception handling ([/EHsc](../../build/reference/eh-exception-handling-model.md)) was specified. @@ -26,7 +27,7 @@ When an exception is thrown, compiler generated code, called the prolog and epil ## Example -The following sample generates C3068: +The following example generates C3068: ```cpp // C3068.cpp @@ -42,5 +43,5 @@ void b(A){} __declspec(naked) void c() { b(A()); // C3068 -}; +} ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3069.md b/docs/error-messages/compiler-errors-2/compiler-error-c3069.md index 34a45c96c9d..e334e11aaa5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3069.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3069.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3069" title: "Compiler Error C3069" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3069" +ms.date: 11/04/2016 f1_keywords: ["C3069"] helpviewer_keywords: ["C3069"] -ms.assetid: ca94291b-2bb4-4e3f-9acf-534234b83513 --- # Compiler Error C3069 -'operator': not allowed for enumeration type +> 'operator': not allowed for enumeration type + +## Remarks An operator is not supported for CLR enumerations. For more information, see [How to: Define and consume enums in C++/CLI](../../dotnet/how-to-define-and-consume-enums-in-cpp-cli.md). ## Example -The following sample generates C3069: +The following example generates C3069: ```cpp // C3069.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3070.md b/docs/error-messages/compiler-errors-2/compiler-error-c3070.md index 9740fc45eeb..3e5cd8cee5e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3070.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3070.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3070" title: "Compiler Error C3070" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3070" +ms.date: 11/04/2016 f1_keywords: ["C3070"] helpviewer_keywords: ["C3070"] -ms.assetid: ac88584d-40a6-4176-90f3-2371c3c935f2 --- # Compiler Error C3070 -'property': property does not have a 'set' method +> 'property': property does not have a 'set' method + +## Remarks A property's set accessor method was not defined. For more information, see [property](../../extensions/property-cpp-component-extensions.md). -The following sample generates C3070: +## Example + +The following example generates C3070: ```cpp // C3070.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3071.md b/docs/error-messages/compiler-errors-2/compiler-error-c3071.md index 2b25f530af2..b8f37bba23f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3071.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3071.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3071" title: "Compiler Error C3071" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3071" +ms.date: 11/04/2016 f1_keywords: ["C3071"] helpviewer_keywords: ["C3071"] -ms.assetid: 69879e66-a60e-4058-9bbd-d5c5e2d8ee37 --- # Compiler Error C3071 -operator 'operator' can only be applied to an instance of a ref class or a value-type +> operator 'operator' can only be applied to an instance of a ref class or a value-type + +## Remarks A CLR operator cannot be used on a native type. The operator can be used on a ref class or a ref struct (a value type) but not a native type such as int or an alias for a native type such as System::Int32. These types can't be boxed from C++ code in a way that refers to the native variable, so the operator cannot be used. @@ -16,7 +17,7 @@ For more information, see [Tracking Reference Operator](../../extensions/trackin ## Example -The following sample generates C3071. +The following example generates C3071. ```cpp // C3071.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3072.md b/docs/error-messages/compiler-errors-2/compiler-error-c3072.md index 3fc36b7657a..c4a4aa4d695 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3072.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3072.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3072" title: "Compiler Error C3072" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3072" +ms.date: 11/04/2016 f1_keywords: ["C3072"] helpviewer_keywords: ["C3072"] -ms.assetid: cdd5cb6b-c478-4698-adfa-c40188d34a18 --- # Compiler Error C3072 > operator '*operator-name*' cannot be applied to an instance of a ref class +## Remarks + use the unary *operator-name* operator to convert an instance of a ref class to a handle type A CLR type requires CLR operators, not native (or standard) operators. For more information, see [Tracking Reference Operator](../../extensions/tracking-reference-operator-cpp-component-extensions.md). ## Example -The following sample generates C3072. +The following example generates C3072. ```cpp // C3072.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3073.md b/docs/error-messages/compiler-errors-2/compiler-error-c3073.md index abfadfab32d..ee969551dee 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3073.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3073.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3073" title: "Compiler Error C3073" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3073" +ms.date: 11/04/2016 f1_keywords: ["C3073"] helpviewer_keywords: ["C3073"] -ms.assetid: b24b9b8b-f9fb-4c3c-a1a0-97fad2081bfc --- # Compiler Error C3073 -'type' : ref class does not have a user-defined copy constructor +> 'type' : ref class does not have a user-defined copy constructor + +## Remarks In a [/clr (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md) compilation, the compiler will not generate a copy constructor for a reference type. In any **/clr** compilation, you must define your own copy constructor for a reference type if you expect an instance of the type to be copied. @@ -16,7 +17,7 @@ For more information, see [C++ Stack Semantics for Reference Types](../../dotnet ## Example -The following sample generates C3073. +The following example generates C3073. ```cpp // C3073.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3075.md b/docs/error-messages/compiler-errors-2/compiler-error-c3075.md index edb6485a4cd..eddf91c56cb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3075.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3075.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3075" title: "Compiler Error C3075" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3075" +ms.date: 11/04/2016 f1_keywords: ["C3075"] helpviewer_keywords: ["C3075"] -ms.assetid: f431daa9-e0fa-48f0-a5c3-f99be96b55e3 --- # Compiler Error C3075 -'instance' : you cannot embed an instance of a reference type, 'type', in a value-type +> 'instance' : you cannot embed an instance of a reference type, 'type', in a value-type + +## Remarks A value type cannot contain an instance of a reference type. @@ -16,7 +17,7 @@ For more information, see [C++ Stack Semantics for Reference Types](../../dotnet ## Example -The following sample generates C3075. +The following example generates C3075. ```cpp // C3075.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3076.md b/docs/error-messages/compiler-errors-2/compiler-error-c3076.md index 35183fa19d4..62da9d235f0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3076.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3076.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3076" title: "Compiler Error C3076" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3076" +ms.date: 11/04/2016 f1_keywords: ["C3076"] helpviewer_keywords: ["C3076"] -ms.assetid: 8a87b3e4-2c17-4b87-9622-ef0962d6a34e --- # Compiler Error C3076 -'instance' : you cannot embed an instance of a reference type, 'type', in a native type +> 'instance' : you cannot embed an instance of a reference type, 'type', in a native type + +## Remarks A native type cannot contain an instance of a CLR type. @@ -16,7 +17,7 @@ For more information, see [C++ Stack Semantics for Reference Types](../../dotnet ## Example -The following sample generates C3076. +The following example generates C3076. ```cpp // C3076.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3077.md b/docs/error-messages/compiler-errors-2/compiler-error-c3077.md index 4ceb95d997d..db80911f95c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3077.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3077.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3077" title: "Compiler Error C3077" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3077" +ms.date: 11/04/2016 f1_keywords: ["C3077"] helpviewer_keywords: ["C3077"] -ms.assetid: d9f3c619-d1e2-4656-81a5-a35a9586a7d4 --- # Compiler Error C3077 -'finalizer' : a finalizer can only be a member of a reference type +> 'finalizer' : a finalizer can only be a member of a reference type + +## Remarks You cannot declare a finalizer in a native or value type. @@ -16,7 +17,7 @@ For more information, see [Destructors and finalizers in How to: Define and cons ## Example -The following sample generates C3077. +The following example generates C3077. ```cpp // C3077.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3080.md b/docs/error-messages/compiler-errors-2/compiler-error-c3080.md index 14b0241f785..88cbc6ca129 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3080.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3080.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3080" title: "Compiler Error C3080" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3080" +ms.date: 11/04/2016 f1_keywords: ["C3080"] helpviewer_keywords: ["C3080"] -ms.assetid: ff62a3f7-9b3b-44bd-b8d9-f3a8e5354560 --- # Compiler Error C3080 -'finalizer_function' : a finalizer cannot have a storage-class-specifier +> 'finalizer_function' : a finalizer cannot have a storage-class-specifier + +## Remarks For more information, see [Destructors and finalizers in How to: Define and consume classes and structs (C++/CLI)](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Destructors_and_finalizers). ## Example -The following sample generates C3080. +The following example generates C3080. ```cpp // C3080.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3083.md b/docs/error-messages/compiler-errors-2/compiler-error-c3083.md index 35cefa54416..8b0ec411136 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3083.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3083.md @@ -1,32 +1,31 @@ --- -description: "Learn more about: Compiler Error C3083" title: "Compiler Error C3083" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3083" +ms.date: 08/14/2025 f1_keywords: ["C3083"] helpviewer_keywords: ["C3083"] -ms.assetid: 05ff791d-52bb-41eb-9511-3ef89d7f4710 --- # Compiler Error C3083 -'function': the symbol to the left of a '::' must be a type +> '*identifier*': the symbol to the left of a '::' must be a type -A function was called incorrectly. +## Remarks + +The qualification used is invalid. Ensure that no extra symbols were used in the qualification and that you included all required headers. ## Example -The following sample generates C3083. +The following example generates C3083: ```cpp // C3083.cpp // compile with: /c -struct N { - ~N(); -}; -struct N1 { - ~N1(); +struct S +{ + S(); }; -N::N::~N() {} // C3083 -N1::~N1() {} // OK +S::Extra::S() {} // C3083 +S::S() {} // OK ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3084.md b/docs/error-messages/compiler-errors-2/compiler-error-c3084.md index aebe230b47a..a07399b74d7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3084.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3084.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3084" title: "Compiler Error C3084" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3084" +ms.date: 11/04/2016 f1_keywords: ["C3084"] helpviewer_keywords: ["C3084"] -ms.assetid: 0362cb70-e24e-476f-a24d-8f5bb97c3afd --- # Compiler Error C3084 -'function': a finalizer/destructor cannot be 'keyword' +> 'function': a finalizer/destructor cannot be 'keyword' + +## Remarks A finalizer or destructor was declared incorrectly. @@ -16,7 +17,7 @@ For example, a destructor should not be marked as sealed. The destructor will b ## Example -The following sample generates C3084. +The following example generates C3084. ```cpp // C3084.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3085.md b/docs/error-messages/compiler-errors-2/compiler-error-c3085.md index 7fe1b774584..74751546f6d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3085.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3085.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3085" title: "Compiler Error C3085" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3085" +ms.date: 11/04/2016 f1_keywords: ["C3085"] helpviewer_keywords: ["C3085"] -ms.assetid: 1ac40bf2-f63e-439e-8921-47e6dadc8354 --- # Compiler Error C3085 -'constructor': a constructor cannot be 'keyword' +> 'constructor': a constructor cannot be 'keyword' + +## Remarks A constructor was declared incorrectly. See [Override Specifiers](../../extensions/override-specifiers-cpp-component-extensions.md) for more information. ## Example -The following sample generates C3085. +The following example generates C3085. ```cpp // C3085.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3087.md b/docs/error-messages/compiler-errors-2/compiler-error-c3087.md index a55aa67f4bd..1ab7a8e1e53 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3087.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3087.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3087" title: "Compiler Error C3087" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3087" +ms.date: 11/04/2016 f1_keywords: ["C3087"] helpviewer_keywords: ["C3087"] -ms.assetid: 4f5bdd52-a853-4f02-b160-6868e9190b9d --- # Compiler Error C3087 -'named_argument': call of 'attribute' already initializes this member +> 'named_argument': call of 'attribute' already initializes this member + +## Remarks A named argument was specified in the same attribute block as an unnamed argument for the same value. Specify only a named or unnamed argument. ## Example -The following sample generates C3087. +The following example generates C3087. ```cpp // C3087.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3094.md b/docs/error-messages/compiler-errors-2/compiler-error-c3094.md index a97f0f43706..83e295f29c3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3094.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3094.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3094" title: "Compiler Error C3094" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3094" +ms.date: 11/04/2016 f1_keywords: ["C3094"] helpviewer_keywords: ["C3094"] -ms.assetid: 10da9b7c-e72d-4013-9925-c83e1bb142db --- # Compiler Error C3094 -'attribute': anonymous usage not allowed +> 'attribute': anonymous usage not allowed + +## Remarks An attribute was not scoped correctly. For more information, see [User-Defined Attributes](../../extensions/user-defined-attributes-cpp-component-extensions.md). ## Example -The following sample generates C3094. +The following example generates C3094. ```cpp // C3094.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3095.md b/docs/error-messages/compiler-errors-2/compiler-error-c3095.md index bd8be003cbd..5cae3a92d4e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3095.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3095.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3095" title: "Compiler Error C3095" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3095" +ms.date: 11/04/2016 f1_keywords: ["C3095"] helpviewer_keywords: ["C3095"] -ms.assetid: cde725be-0936-40f6-9e57-e1d7d0710f83 --- # Compiler Error C3095 -'attribute': attribute cannot be repeated +> 'attribute': attribute cannot be repeated + +## Remarks Some attributes are declared such that, multiple occurrences of the attribute cannot be applied to a target. @@ -16,7 +17,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3095. +The following example generates C3095. ```cpp // C3095.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3096.md b/docs/error-messages/compiler-errors-2/compiler-error-c3096.md index aef61fc0947..65387f15584 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3096.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3096.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3096" title: "Compiler Error C3096" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3096" +ms.date: 11/04/2016 f1_keywords: ["C3096"] helpviewer_keywords: ["C3096"] -ms.assetid: 56353c9a-800c-474f-b428-3e5d2a7afc9a --- # Compiler Error C3096 -'attribute': attribute is allowed on data members of attribute classes only +> 'attribute': attribute is allowed on data members of attribute classes only + +## Remarks An attribute was applied incorrectly. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3097.md b/docs/error-messages/compiler-errors-2/compiler-error-c3097.md index b8147494239..0df9c143f97 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3097.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3097.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3097" title: "Compiler Error C3097" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3097" +ms.date: 11/04/2016 f1_keywords: ["C3097"] helpviewer_keywords: ["C3097"] -ms.assetid: b24bd8f8-e04f-4fbb-be57-4feb9165572e --- # Compiler Error C3097 -'attribute': attribute must be scoped with 'assembly:' or 'module:' +> 'attribute': attribute must be scoped with 'assembly:' or 'module:' + +## Remarks A global attribute was used incorrectly. @@ -16,7 +17,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3097. +The following example generates C3097. ```cpp // C3097.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3099.md b/docs/error-messages/compiler-errors-2/compiler-error-c3099.md index ae0c8f89aa8..715d0b0c786 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3099.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3099.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3099" title: "Compiler Error C3099" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3099" +ms.date: 11/04/2016 f1_keywords: ["C3099"] helpviewer_keywords: ["C3099"] -ms.assetid: b3dded0f-76c9-42c1-991b-532eb8619661 --- # Compiler Error C3099 -'keyword': use [System::AttributeUsageAttribute] for managed attributes; use [Windows::Foundation::Metadata::AttributeUsageAttribute] for WinRT attributes +> 'keyword': use [System::AttributeUsageAttribute] for managed attributes; use [Windows::Foundation::Metadata::AttributeUsageAttribute] for WinRT attributes + +## Remarks Use to declare **/clr** attributes. Use `Windows::Foundation::Metadata::AttributeUsageAttribute` to declare Windows Runtime attributes. @@ -16,7 +17,7 @@ For more information about /CLR attributes, see [User-Defined Attributes](../../ ## Example -The following sample generates C3099 and shows how to fix it. +The following example generates C3099 and shows how to fix it. ```cpp // C3099.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3100.md b/docs/error-messages/compiler-errors-2/compiler-error-c3100.md index 5fa251c5129..c67b602e9a6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3100.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3100.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3100" title: "Compiler Error C3100" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3100" +ms.date: 11/04/2016 f1_keywords: ["C3100"] helpviewer_keywords: ["C3100"] -ms.assetid: 7a9c9eaf-08ef-442d-94a0-e457beee8549 --- # Compiler Error C3100 -'target' : unknown attribute qualifier +> 'target' : unknown attribute qualifier + +## Remarks An invalid attribute target was specified. @@ -16,7 +17,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3100. +The following example generates C3100. ```cpp // C3100.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3101.md b/docs/error-messages/compiler-errors-2/compiler-error-c3101.md index 045856000f7..6c5f88063b5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3101.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3101.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3101" title: "Compiler Error C3101" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3101" +ms.date: 11/04/2016 f1_keywords: ["C3101"] helpviewer_keywords: ["C3101"] -ms.assetid: 4f673766-d4f7-4632-94a5-d36a83f7f4b5 --- # Compiler Error C3101 -illegal expression for named attribute argument 'field' +> illegal expression for named attribute argument 'field' + +## Remarks When initializing a named attribute argument, the value must be a compile time constant. @@ -16,7 +17,7 @@ For more information on attributes, see [User-Defined Attributes](../../extensio ## Example -The following sample generates C3101. +The following example generates C3101. ```cpp // C3101.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3103.md b/docs/error-messages/compiler-errors-2/compiler-error-c3103.md index c877baa9b96..46b7d95b5f6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3103.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3103.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3103" title: "Compiler Error C3103" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3103" +ms.date: 11/04/2016 f1_keywords: ["C3103"] helpviewer_keywords: ["C3103"] -ms.assetid: 7984bd3e-d51d-43e4-b6f4-08c1e9fb9704 --- # Compiler Error C3103 -'argument': repeated named argument +> 'argument': repeated named argument + +## Remarks An attribute can not repeat named arguments. @@ -16,7 +17,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3103. +The following example generates C3103. ```cpp // C3103.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3104.md b/docs/error-messages/compiler-errors-2/compiler-error-c3104.md index 1dec0a81074..b2b05bdc091 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3104.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3104.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3104" title: "Compiler Error C3104" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3104" +ms.date: 11/04/2016 f1_keywords: ["C3104"] helpviewer_keywords: ["C3104"] -ms.assetid: b5648d47-e5d3-4b45-a3c0-f46e04eae731 --- # Compiler Error C3104 -illegal attribute argument +> illegal attribute argument + +## Remarks You specified an invalid argument to an attribute. @@ -18,7 +19,7 @@ This error can be generated as a result of compiler conformance work that was do ## Examples -The following sample generates C3104. +The following example generates C3104. ```cpp // C3104a.cpp @@ -37,7 +38,7 @@ public ref struct ABC : public Attribute { ref struct AStruct{}; ``` -The following sample generates C3104. +The following example generates C3104. ```cpp // C3104b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3106.md b/docs/error-messages/compiler-errors-2/compiler-error-c3106.md index 0722bc47ab8..e44c24da629 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3106.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3106.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3106" title: "Compiler Error C3106" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3106" +ms.date: 11/04/2016 f1_keywords: ["C3106"] helpviewer_keywords: ["C3106"] -ms.assetid: 39d97a32-0905-4702-87d3-7f8ce473fb93 --- # Compiler Error C3106 -'attribute': unnamed arguments must precede named arguments +> 'attribute': unnamed arguments must precede named arguments + +## Remarks Unnamed arguments must be passed to an attribute before named arguments. @@ -16,7 +17,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3106. +The following example generates C3106. ```cpp // C3106.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3110.md b/docs/error-messages/compiler-errors-2/compiler-error-c3110.md index d9394cedf03..9cf78b27444 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3110.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3110.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3110" title: "Compiler Error C3110" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3110" +ms.date: 11/04/2016 f1_keywords: ["C3110"] helpviewer_keywords: ["C3110"] -ms.assetid: 821dc71f-896e-4b2d-af0e-aa9932934b7b --- # Compiler Error C3110 -'function_name' : you cannot overload a COM interface method +> 'function_name' : you cannot overload a COM interface method + +## Remarks An interface that is prefaced by an interface attribute, such as: @@ -20,7 +21,11 @@ An interface that is prefaced by an interface attribute, such as: - [object](../../windows/attributes/object-cpp.md) -cannot be overloaded. For example: +cannot be overloaded. + +## Example + +For example: ```cpp // C3110.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3113.md b/docs/error-messages/compiler-errors-2/compiler-error-c3113.md index 970f7590709..640eb8d5bb1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3113.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3113.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3113" title: "Compiler Error C3113" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3113" +ms.date: 11/04/2016 f1_keywords: ["C3113"] helpviewer_keywords: ["C3113"] -ms.assetid: 3afdc668-b29e-474e-9ea3-aa027d42db7c --- # Compiler Error C3113 -an 'structure' cannot be a template/generic +> an 'structure' cannot be a template/generic + +## Remarks You attempted to make a class template or class generic out of an interface or an enum. -The following sample generates C3113: +## Example + +The following example generates C3113: ```cpp // C3113.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3114.md b/docs/error-messages/compiler-errors-2/compiler-error-c3114.md index 6fac377ccb8..0d6fdb2e633 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3114.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3114.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3114" title: "Compiler Error C3114" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3114" +ms.date: 11/04/2016 f1_keywords: ["C3114"] helpviewer_keywords: ["C3114"] -ms.assetid: b5d2df4f-87d0-4292-9981-25c6a6013c05 --- # Compiler Error C3114 -'argument': not a valid named attribute argument +> 'argument': not a valid named attribute argument + +## Remarks In order for an attribute class data member to be a valid named argument, it must not be marked **`static`**, **`const`**, or **`literal`**. If a property, the property must not be **`static`** and must have get and set accessors. @@ -16,7 +17,7 @@ For more information, see [property](../../extensions/property-cpp-component-ext ## Example -The following sample generates C3114. +The following example generates C3114. ```cpp // C3114.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3115.md b/docs/error-messages/compiler-errors-2/compiler-error-c3115.md index 217ea876771..f6be15f40d3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3115.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3115.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3115" title: "Compiler Error C3115" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3115" +ms.date: 11/04/2016 f1_keywords: ["C3115"] helpviewer_keywords: ["C3115"] -ms.assetid: 51726145-9782-4ec9-84b9-286f366d9cbd --- # Compiler Error C3115 -'attribute': this attribute is not allowed on 'construct' +> 'attribute': this attribute is not allowed on 'construct' + +## Remarks An attribute was applied to a construct for which it was not intended. See [Attributes by Usage](../../windows/attributes/attributes-by-usage.md) for more information. ## Example -The following sample generates C3115. +The following example generates C3115. ```cpp // C3115.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3116.md b/docs/error-messages/compiler-errors-2/compiler-error-c3116.md index 57dbf504d7f..4a3b9237bc0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3116.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3116.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3116" title: "Compiler Error C3116" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3116" +ms.date: 11/04/2016 f1_keywords: ["C3116"] helpviewer_keywords: ["C3116"] -ms.assetid: 597463e1-a5cc-4ed3-a917-eae9a61d3312 --- # Compiler Error C3116 -'storage specifier' : invalid storage class for interface method +> 'storage specifier' : invalid storage class for interface method + +## Remarks You used **`typedef`**, **`register`**, or **`static`** as the storage class for an interface method. These storage classes are not permitted on interface members. -The following sample generates C3116: +## Example + +The following example generates C3116: ```cpp // C3116.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3117.md b/docs/error-messages/compiler-errors-2/compiler-error-c3117.md index d8564c19483..67f914ff316 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3117.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3117.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3117" title: "Compiler Error C3117" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3117" +ms.date: 11/04/2016 f1_keywords: ["C3117"] helpviewer_keywords: ["C3117"] -ms.assetid: dceee392-d4c7-4599-b75e-7aaac7c36fdd --- # Compiler Error C3117 -'%$S' : an interface can only have one base class +> '%$S' : an interface can only have one base class + +## Remarks You declared an interface that inherits from multiple base classes. -The following sample generates C3117: +## Example + +The following example generates C3117: ```cpp // C3117.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3118.md b/docs/error-messages/compiler-errors-2/compiler-error-c3118.md index 336a3aaf927..48d11292d5f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3118.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3118.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Error C3118" title: "Compiler Error C3118" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3118" +ms.date: 11/04/2016 f1_keywords: ["C3118"] helpviewer_keywords: ["C3118"] -ms.assetid: 40fbe681-8868-4cb2-a2b2-4db4449319a7 --- # Compiler Error C3118 -'interface' : interfaces do not support virtual inheritance +> 'interface' : interfaces do not support virtual inheritance + +## Remarks + +You tried to virtually inherit from an interface. + +## Example -You tried to virtually inherit from an interface. For example, +For example, ```cpp // C3118.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3120.md b/docs/error-messages/compiler-errors-2/compiler-error-c3120.md index b9d10eea8a6..a292987bc60 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3120.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3120.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Error C3120" title: "Compiler Error C3120" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3120" +ms.date: 11/04/2016 f1_keywords: ["C3120"] helpviewer_keywords: ["C3120"] -ms.assetid: 9b6b210f-9948-4517-a4cc-b4aaadebde68 --- # Compiler Error C3120 -'method_name' : interface methods cannot take a variable argument list +> 'method_name' : interface methods cannot take a variable argument list + +## Remarks + +An interface method cannot take a variable argument list. + +## Example -An interface method cannot take a variable argument list. For example, the following interface definition generates C3120: +For example, the following interface definition generates C3120: ```cpp // C3120.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3121.md b/docs/error-messages/compiler-errors-2/compiler-error-c3121.md index 227db69a1d0..463bcaba93a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3121.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3121.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C3121" title: "Compiler Error C3121" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3121" +ms.date: 11/04/2016 f1_keywords: ["C3121"] helpviewer_keywords: ["C3121"] -ms.assetid: 1d3c7be4-d42d-4def-8d53-182c0c5cc237 --- # Compiler Error C3121 -cannot change GUID for class 'class_name' +> cannot change GUID for class 'class_name' + +## Remarks You attempted to change the class ID with [__declspec(uuid)](../../cpp/uuid-cpp.md). +## Example + For example, the following code generates C3121: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3126.md b/docs/error-messages/compiler-errors-2/compiler-error-c3126.md index 2822c84cc6a..2b8904f94d5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3126.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3126.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3126" title: "Compiler Error C3126" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3126" +ms.date: 11/04/2016 f1_keywords: ["C3126"] helpviewer_keywords: ["C3126"] -ms.assetid: e72658a3-5d85-4a31-89a4-dbc3d475973d --- # Compiler Error C3126 -cannot define a union 'union' inside of managed type 'type' +> cannot define a union 'union' inside of managed type 'type' + +## Remarks A union cannot be defined inside a managed type. -The following sample generates C3126: +## Example + +The following example generates C3126: ```cpp // C3126_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3130.md b/docs/error-messages/compiler-errors-2/compiler-error-c3130.md index 4da60e51e93..ebd75f87f3b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3130.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3130.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3130" title: "Compiler Error C3130" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3130" +ms.date: 11/04/2016 f1_keywords: ["C3130"] helpviewer_keywords: ["C3130"] -ms.assetid: c1462f33-434f-41f0-937e-392864916850 --- # Compiler Error C3130 -Internal Compiler Error: failed to write injected code block to PDB +> Internal Compiler Error: failed to write injected code block to PDB + +## Remarks This error occurs if the compiler failed to write an injected code block to the .pdb file. The most common reason for the failure is lack of disk space. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3131.md b/docs/error-messages/compiler-errors-2/compiler-error-c3131.md index 54a1b28c50b..6206cebbdfa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3131.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3131.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3131" title: "Compiler Error C3131" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3131" +ms.date: 11/04/2016 f1_keywords: ["C3131"] helpviewer_keywords: ["C3131"] -ms.assetid: 38f20fac-83c9-4cd9-b7b5-74ca8f650ea6 --- # Compiler Error C3131 -project must have a 'module' attribute with a 'name' property +> project must have a 'module' attribute with a 'name' property + +## Remarks The [module](../../windows/attributes/module-cpp.md) attribute must have a name parameter. -The following sample generates C3131: +## Example + +The following example generates C3131: ```cpp // C3131.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3132.md b/docs/error-messages/compiler-errors-2/compiler-error-c3132.md index d61facc1aab..83bbc2fe187 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3132.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3132.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3132" title: "Compiler Error C3132" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3132" +ms.date: 11/04/2016 f1_keywords: ["C3132"] helpviewer_keywords: ["C3132"] -ms.assetid: d54a3d12-336a-4ed0-ad4e-43cddac33b5e --- # Compiler Error C3132 -'function-parameter' : parameter arrays can only be applied to a formal argument of type 'single-dimensional managed array' +> 'function-parameter' : parameter arrays can only be applied to a formal argument of type 'single-dimensional managed array' + +## Remarks The attribute was applied to a parameter that was not a single-dimension array. -The following sample generates C3132: +## Example + +The following example generates C3132: ```cpp // C3132.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3133.md b/docs/error-messages/compiler-errors-2/compiler-error-c3133.md index d26c091a66a..cb737253640 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3133.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3133.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3133" title: "Compiler Error C3133" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3133" +ms.date: 11/04/2016 f1_keywords: ["C3133"] helpviewer_keywords: ["C3133"] -ms.assetid: 4a709405-b67b-4061-8a2a-19fa5fb34a2a --- # Compiler Error C3133 -Attributes cannot be applied to C++ varargs +> Attributes cannot be applied to C++ varargs + +## Remarks An attribute was applied incorrectly. Attributes can not be applied to an ellipsis representing variable arguments. @@ -16,7 +17,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3133. +The following example generates C3133. ```cpp // C3133.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3134.md b/docs/error-messages/compiler-errors-2/compiler-error-c3134.md index f8e04a9e7b5..ee6d5ab7c78 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3134.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3134.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3134" title: "Compiler Error C3134" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3134" +ms.date: 11/04/2016 f1_keywords: ["C3134"] helpviewer_keywords: ["C3134"] -ms.assetid: f887e4d2-7740-49e4-9972-7edceb8fa77b --- # Compiler Error C3134 -'value' : value of attribute argument 'attribute' does not have valid type 'type' +> 'value' : value of attribute argument 'attribute' does not have valid type 'type' + +## Remarks A syntax error was detected when a value was assigned to an attribute. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3135.md b/docs/error-messages/compiler-errors-2/compiler-error-c3135.md index 1b97325d54a..9e421773ca1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3135.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3135.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3135" title: "Compiler Error C3135" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3135" +ms.date: 11/04/2016 f1_keywords: ["C3135"] helpviewer_keywords: ["C3135"] -ms.assetid: e92ee007-5a26-47f4-8ef4-339f2d9528d1 --- # Compiler Error C3135 -'property' : a property cannot have a 'const' or 'volatile' type +> 'property' : a property cannot have a 'const' or 'volatile' type + +## Remarks The [const](../../cpp/const-cpp.md) and [volatile](../../cpp/volatile-cpp.md) keywords are not permitted on properties. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3136.md b/docs/error-messages/compiler-errors-2/compiler-error-c3136.md index d7f66d04349..6a3a0d24b47 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3136.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3136.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C3136" title: "Compiler Error C3136" -ms.date: "10/03/2018" +description: "Learn more about: Compiler Error C3136" +ms.date: 10/03/2018 f1_keywords: ["C3136"] helpviewer_keywords: ["C3136"] -ms.assetid: c77103cd-00f7-408e-b74b-4f8562039d31 --- # Compiler Error C3136 -'interface' : a COM interface can only inherit from another COM interface, 'interface' is not a COM interface +> 'interface' : a COM interface can only inherit from another COM interface, 'interface' is not a COM interface + +## Remarks An interface to which you applied an [interface attribute](../../windows/attributes/interface-attributes.md) inherits from an interface that is not a COM interface. A COM interface ultimately inherits from `IUnknown`. Any interface preceded by an interface attribute is a COM interface. +## Example + The following example generates C3136: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3137.md b/docs/error-messages/compiler-errors-2/compiler-error-c3137.md index 1ac5395685b..6e731bc7062 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3137.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3137.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C3137" title: "Compiler Error C3137" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3137" +ms.date: 11/04/2016 f1_keywords: ["C3137"] helpviewer_keywords: ["C3137"] -ms.assetid: 70bb1313-2e87-43ed-a0d8-33fa6ff475e4 --- # Compiler Error C3137 -'property' : a property cannot be initialized +> 'property' : a property cannot be initialized + +## Remarks A property cannot be initialized, for example, in a constructor's initialization list. +## Example + The following example generates C3137: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3138.md b/docs/error-messages/compiler-errors-2/compiler-error-c3138.md index d02f0ad8c55..d7f229b6067 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3138.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3138.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C3138" title: "Compiler Error C3138" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3138" +ms.date: 11/04/2016 f1_keywords: ["C3138"] helpviewer_keywords: ["C3138"] -ms.assetid: 364ee9e8-9358-410e-bd35-9c4a226a3753 --- # Compiler Error C3138 -'interface' : a 'attribute' interface must inherit from IDispatch, or from an interface that inherits from IDispatch +> 'interface' : a 'attribute' interface must inherit from IDispatch, or from an interface that inherits from IDispatch + +## Remarks An interface with the [dual](../../windows/attributes/dual.md) or [dispinterface](../../windows/attributes/dispinterface.md) attributes does not have `IDispatch` as a direct or indirect base interface. +## Example + The following example generates C3138: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3139.md b/docs/error-messages/compiler-errors-2/compiler-error-c3139.md index 7d5df2ca7ad..2fd93ca5493 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3139.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3139.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Error C3139" title: "Compiler Error C3139" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3139" +ms.date: 11/04/2016 f1_keywords: ["C3139"] helpviewer_keywords: ["C3139"] -ms.assetid: 95c92263-10ac-4ff3-b385-6312dd92adbc --- # Compiler Error C3139 -'struct' : cannot export a UDT without members +> 'struct' : cannot export a UDT without members + +## Remarks + +You attempted to apply the [export](../../windows/attributes/export.md) attribute to an empty UDT (user-defined type). + +## Example -You attempted to apply the [export](../../windows/attributes/export.md) attribute to an empty UDT (user-defined type). For example: +For example: ```cpp // C3139.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3140.md b/docs/error-messages/compiler-errors-2/compiler-error-c3140.md index 4339d3f6bd6..6141df55509 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3140.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3140.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3140" title: "Compiler Error C3140" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3140" +ms.date: 11/04/2016 f1_keywords: ["C3140"] helpviewer_keywords: ["C3140"] -ms.assetid: 122f8943-fac3-4db8-a3a8-2c5d19233de6 --- # Compiler Error C3140 -cannot have multiple 'module' attributes in the same compilation unit +> cannot have multiple 'module' attributes in the same compilation unit + +## Remarks The [module](../../windows/attributes/module-cpp.md) attribute can only be defined once per project. -The following sample generates C3140: +## Example + +The following example generates C3140: ```cpp // C3140.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3141.md b/docs/error-messages/compiler-errors-2/compiler-error-c3141.md index 6811def6fc9..a46f2847091 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3141.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3141.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3141" title: "Compiler Error C3141" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3141" +ms.date: 11/04/2016 f1_keywords: ["C3141"] helpviewer_keywords: ["C3141"] -ms.assetid: b4fd65c3-50cc-46cd-8de0-6a6d24cb9cda --- # Compiler Error C3141 -'interface_name' : interfaces only support public inheritance +> 'interface_name' : interfaces only support public inheritance + +## Remarks Interfaces defined with the [interface (or __interface)](../../cpp/interface.md) keyword only support public inheritance. -The following sample generates C3141: +## Example + +The following example generates C3141: ```cpp // C3141.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3142.md b/docs/error-messages/compiler-errors-2/compiler-error-c3142.md index 0a7e12997f3..ac7aaeb13d2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3142.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3142.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3142" title: "Compiler Error C3142" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3142" +ms.date: 11/04/2016 f1_keywords: ["C3142"] helpviewer_keywords: ["C3142"] -ms.assetid: 795137ad-d00a-4a9c-9665-0cd8bfb5da8b --- # Compiler Error C3142 -'property_name' : you cannot take the address of a property +> 'property_name' : you cannot take the address of a property + +## Remarks The address of a property is not available to the developer. -The following sample generates C3142: +## Example + +The following example generates C3142: ```cpp // C3142_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3145.md b/docs/error-messages/compiler-errors-2/compiler-error-c3145.md index 0105f33cfee..fad9fdabf3f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3145.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3145.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3145" title: "Compiler Error C3145" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3145" +ms.date: 11/04/2016 f1_keywords: ["C3145"] helpviewer_keywords: ["C3145"] -ms.assetid: f165c874-0f51-45c7-85e8-ebe321cbc168 --- # Compiler Error C3145 -'object' : global or static variable may not have managed or WinRT type 'type' +> 'object' : global or static variable may not have managed or WinRT type 'type' + +## Remarks You can only define CLR or WinRT objects within function scope. -The following sample generates C3145 and shows how to fix it: +## Examples + +The following example generates C3145 and shows how to fix it: ```cpp // C3145.cpp @@ -35,7 +38,7 @@ int main() { } ``` -The following sample generates C3145: +The following example generates C3145: ```cpp // C3145b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3149.md b/docs/error-messages/compiler-errors-2/compiler-error-c3149.md index d28f9366044..241585d1b14 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3149.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3149.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3149" title: "Compiler Error C3149" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3149" +ms.date: 11/04/2016 f1_keywords: ["C3149"] helpviewer_keywords: ["C3149"] -ms.assetid: cf6e2616-2f06-46da-8a8a-d449cb481c51 --- # Compiler Error C3149 -'type' : cannot use this type here without a top-level 'char' +> 'type' : cannot use this type here without a top-level 'char' + +## Remarks A declaration was not specified correctly. @@ -16,7 +17,9 @@ For example, you may have defined a CLR type at global scope and tried to create To resolve this error, declare variables of CLR types inside a function or type definition. -The following sample generates C3149: +## Examples + +The following example generates C3149: ```cpp // C3149.cpp @@ -29,7 +32,7 @@ int main() { } ``` -The following sample generates C3149: +The following example generates C3149: ```cpp // C3149b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3150.md b/docs/error-messages/compiler-errors-2/compiler-error-c3150.md index 3145de7e129..2c26b49381a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3150.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3150.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3150" title: "Compiler Error C3150" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3150" +ms.date: 11/04/2016 f1_keywords: ["C3150"] helpviewer_keywords: ["C3150"] -ms.assetid: c1ff28f5-52fe-4fd4-81d0-2e0ad8548631 --- # Compiler Error C3150 -'element' : 'attribute' can only be applied to a class, interface, array or pointer +> 'element' : 'attribute' can only be applied to a class, interface, array or pointer + +## Remarks **`__gc`** can only be used on a class, interface, or array. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3152.md b/docs/error-messages/compiler-errors-2/compiler-error-c3152.md index 2208919a996..6372b7c33e0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3152.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3152.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3152" title: "Compiler Error C3152" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3152" +ms.date: 11/04/2016 f1_keywords: ["C3152"] helpviewer_keywords: ["C3152"] -ms.assetid: 4ee6e2cd-5d19-4b73-833d-765c35797e4b --- # Compiler Error C3152 -'construct' : 'keyword' can only be applied to a class, struct, or virtual member function +> 'construct' : 'keyword' can only be applied to a class, struct, or virtual member function + +## Remarks Certain keywords can only be applied to a C++ class. -The following sample generates C3152 and shows how to fix it: +## Example + +The following example generates C3152 and shows how to fix it: ```cpp // C3152.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3153.md b/docs/error-messages/compiler-errors-2/compiler-error-c3153.md index 5aacbbacaae..8f85face4cc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3153.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3153.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3153" title: "Compiler Error C3153" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3153" +ms.date: 11/04/2016 f1_keywords: ["C3153"] helpviewer_keywords: ["C3153"] -ms.assetid: d775d97e-2480-484f-81f1-88406b10f947 --- # Compiler Error C3153 -'interface' : you cannot create an instance of an interface +> 'interface' : you cannot create an instance of an interface + +## Remarks An interface cannot be instantiated. To use the members of an interface, derive a class from the interface, implement the interface members, and then use the members. -The following sample generates C3153: +## Example + +The following example generates C3153: ```cpp // C3153.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3154.md b/docs/error-messages/compiler-errors-2/compiler-error-c3154.md index 1a22ee051b2..6d9110b55cf 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3154.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3154.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3154" title: "Compiler Error C3154" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3154" +ms.date: 11/04/2016 f1_keywords: ["C3154"] helpviewer_keywords: ["C3154"] -ms.assetid: 78005c74-eaaf-4ac2-88ae-6c25d01a302a --- # Compiler Error C3154 -Expected ',' before ellipsis. Non-comma separated ellipsis not supported on parameter array functions. +> Expected ',' before ellipsis. Non-comma separated ellipsis not supported on parameter array functions. + +## Remarks A variable argument function was not declared correctly. @@ -16,7 +17,7 @@ For more information, see [Variable Argument Lists (...) (C++/CLI)](../../extens ## Example -The following sample generates C3154. +The following example generates C3154. ```cpp // C3154.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3155.md b/docs/error-messages/compiler-errors-2/compiler-error-c3155.md index 313c3c080a6..8fadcc0c30c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3155.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3155.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3155" title: "Compiler Error C3155" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3155" +ms.date: 11/04/2016 f1_keywords: ["C3155"] helpviewer_keywords: ["C3155"] -ms.assetid: b04a42e1-64e7-40f8-81fe-c7945348b2cf --- # Compiler Error C3155 -attributes are not allowed in a property indexer +> attributes are not allowed in a property indexer + +## Remarks An indexed property was declared incorrectly. For more information, see [How to: Use Properties in C++/CLI](../../dotnet/how-to-use-properties-in-cpp-cli.md). ## Example -The following sample generates C3155. +The following example generates C3155. ```cpp // C3155.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3156.md b/docs/error-messages/compiler-errors-2/compiler-error-c3156.md index 6fdca14c852..8f70a06967b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3156.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3156.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3156" title: "Compiler Error C3156" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3156" +ms.date: 11/04/2016 f1_keywords: ["C3156"] helpviewer_keywords: ["C3156"] -ms.assetid: 1876da78-b94e-4af7-9795-28f72b209b3e --- # Compiler Error C3156 -'class' : you cannot have a local definition of a managed or WinRT type +> 'class' : you cannot have a local definition of a managed or WinRT type + +## Remarks A function cannot contain the definition, or declaration, of a managed or WinRT class, struct, or interface. ## Example -The following sample generates C3156. +The following example generates C3156. ```cpp // C3156.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3157.md b/docs/error-messages/compiler-errors-2/compiler-error-c3157.md index bc9741e6078..445bf3ff9ca 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3157.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3157.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3157" title: "Compiler Error C3157" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3157" +ms.date: 11/04/2016 f1_keywords: ["C3157"] helpviewer_keywords: ["C3157"] -ms.assetid: fe94d97f-612e-4729-8b2b-b057d84822a1 --- # Compiler Error C3157 -ParamArray attribute can only be applied to the last parameter +> ParamArray attribute can only be applied to the last parameter + +## Remarks The attribute was applied to the wrong parameter. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3159.md b/docs/error-messages/compiler-errors-2/compiler-error-c3159.md index 92cdaba9c63..c1090d08ec0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3159.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3159.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3159" title: "Compiler Error C3159" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3159" +ms.date: 11/04/2016 f1_keywords: ["C3159"] helpviewer_keywords: ["C3159"] -ms.assetid: e115cc76-0021-4568-95fd-61a324c41a85 --- # Compiler Error C3159 -'pointer' : array of pointers to value type cannot be declared +> 'pointer' : array of pointers to value type cannot be declared + +## Remarks An array of pointers to a value type cannot be declared. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3160.md b/docs/error-messages/compiler-errors-2/compiler-error-c3160.md index b28eace9bbe..a509272d5a4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3160.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3160.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3160" title: "Compiler Error C3160" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3160" +ms.date: 11/04/2016 f1_keywords: ["C3160"] helpviewer_keywords: ["C3160"] -ms.assetid: a250c433-8adf-43b9-8dee-c3794e09b0a5 --- # Compiler Error C3160 -'pointer' : a data member of a managed or WinRT class cannot have this type +> 'pointer' : a data member of a managed or WinRT class cannot have this type + +## Remarks Interior garbage collection pointers may point to the interior of a managed or WinRT class. Because they are slower than whole-object pointers and require special handling by the garbage collector, you cannot declare interior managed pointers as members of a class. -The following sample generates C3160: +## Example + +The following example generates C3160: ```cpp // C3160.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3161.md b/docs/error-messages/compiler-errors-2/compiler-error-c3161.md index 2dbb59b9051..f462c3b2494 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3161.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3161.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3161" title: "Compiler Error C3161" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3161" +ms.date: 11/04/2016 f1_keywords: ["C3161"] helpviewer_keywords: ["C3161"] -ms.assetid: 1fe2be85-a343-487b-8476-bf9e257eb29d --- # Compiler Error C3161 -'interface' : nesting class, struct, union or interface in an interface is illegal; nesting interface in a class, struct or union is illegal +> 'interface' : nesting class, struct, union or interface in an interface is illegal; nesting interface in a class, struct or union is illegal + +## Remarks An [__interface](../../cpp/interface.md) can only appear at global scope or within a namespace. A class, struct, or union cannot appear in an interface. ## Example -The following sample generates C3161. +The following example generates C3161. ```cpp // C3161.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3162.md b/docs/error-messages/compiler-errors-2/compiler-error-c3162.md index 6c059c9c65b..8823e0e12ec 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3162.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3162.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3162" title: "Compiler Error C3162" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3162" +ms.date: 11/04/2016 f1_keywords: ["C3162"] helpviewer_keywords: ["C3162"] -ms.assetid: 0d4c4a24-1456-4191-b7d8-c38cb7b17c32 --- # Compiler Error C3162 -'type' : a reference type which has a destructor cannot be used as the type of static data member 'member' +> 'type' : a reference type which has a destructor cannot be used as the type of static data member 'member' + +## Remarks The common language runtime cannot know when to run a user-defined destructor when the class also contains static member function. @@ -22,7 +23,7 @@ For more information, see, ## Example -The following sample generates C3162. +The following example generates C3162. ```cpp // C3162.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3163.md b/docs/error-messages/compiler-errors-2/compiler-error-c3163.md index efd0231c211..f8d07d28b1b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3163.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3163.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3163" title: "Compiler Error C3163" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3163" +ms.date: 11/04/2016 f1_keywords: ["C3163"] helpviewer_keywords: ["C3163"] -ms.assetid: 17dcafa3-f416-4e04-a232-f9569218ba75 --- # Compiler Error C3163 > '*construct*': attributes inconsistent with previous declaration +## Remarks + The attribute(s) that are applied to a definition conflict with the attribute(s) that are applied to a declaration. One way to resolve C3163 is to eliminate attributes on the forward declaration. Any attributes on a forward declaration should be less than the attributes on the definition or, at most, equal to them. @@ -18,7 +19,7 @@ A possible cause of the C3163 error involves the Microsoft source code annotatio ## Example -The following sample generates C3163. +The following example generates C3163. ```cpp // C3163.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3166.md b/docs/error-messages/compiler-errors-2/compiler-error-c3166.md index 6b12aa26515..4c7d4cdb3f7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3166.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3166.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3166" title: "Compiler Error C3166" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3166" +ms.date: 11/04/2016 f1_keywords: ["C3166"] helpviewer_keywords: ["C3166"] -ms.assetid: ec3e330d-c15d-4158-8268-09101486c566 --- # Compiler Error C3166 > 'pointer' : cannot declare a pointer to an interior __gc pointer as a member of 'type' +## Remarks + The compiler found an invalid pointer declaration (a **`__nogc`** pointer to a **`__gc`** pointer.). C3166 is only reachable using the obsolete compiler option **`/clr:oldSyntax`**. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3167.md b/docs/error-messages/compiler-errors-2/compiler-error-c3167.md index 32c75e4d421..62b80984084 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3167.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3167.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3167" title: "Compiler Error C3167" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3167" +ms.date: 11/04/2016 f1_keywords: ["C3167"] helpviewer_keywords: ["C3167"] -ms.assetid: 58c25fe7-8562-4a18-ad3f-487f081ff173 --- # Compiler Error C3167 -Unable to initialize .NET Framework: make sure it is installed +> Unable to initialize .NET Framework: make sure it is installed + +## Remarks The .NET Framework is not installed on this computer; install the .NET Framework. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3168.md b/docs/error-messages/compiler-errors-2/compiler-error-c3168.md index bdfd093a15a..fe5c27dd2ce 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3168.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3168.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3168" title: "Compiler Error C3168" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3168" +ms.date: 11/04/2016 f1_keywords: ["C3168"] helpviewer_keywords: ["C3168"] -ms.assetid: 4c36fcfb-c351-48ff-b4eb-78d2aa1b4d55 --- # Compiler Error C3168 -'type' : illegal underlying type for enum +> 'type' : illegal underlying type for enum + +## Remarks The underlying type you specified for the **`enum`** type was not valid. The underlying type must be an integral C++ type or a corresponding CLR type. -The following sample generates C3168: +## Example + +The following example generates C3168: ```cpp // C3168.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3170.md b/docs/error-messages/compiler-errors-2/compiler-error-c3170.md index 10e9b317c49..5613a0ec2d4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3170.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3170.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Error C3170" title: "Compiler Error C3170" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3170" +ms.date: 11/04/2016 f1_keywords: ["C3170"] helpviewer_keywords: ["C3170"] -ms.assetid: ca9a59d6-7df3-42f0-b028-c09d0af3ac2a --- # Compiler Error C3170 -cannot have different module identifiers in a project +> cannot have different module identifiers in a project + +## Remarks [module](../../windows/attributes/module-cpp.md) attributes with different names were found in two of the files in a compilation. Only one unique `module` attribute can be specified per compilation. Identical `module` attributes can be specified in more than one source code file. +## Example + For example, if the following module attributes were found: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3171.md b/docs/error-messages/compiler-errors-2/compiler-error-c3171.md index b51a5d11dd0..63f770be44f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3171.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3171.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Error C3171" title: "Compiler Error C3171" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3171" +ms.date: 11/04/2016 f1_keywords: ["C3171"] helpviewer_keywords: ["C3171"] -ms.assetid: 1ce26997-7ef1-4c9f-84da-003ea1a4251e --- # Compiler Error C3171 -'module': cannot specify different module attributes in a project +> 'module': cannot specify different module attributes in a project + +## Remarks [module](../../windows/attributes/module-cpp.md) attributes with different parameter lists were found in two of the files in a compilation. Only one unique `module` attribute can be specified per compilation. Identical `module` attributes can be specified in more than one source code file. +## Example + For example, if the following `module` attributes were found: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3172.md b/docs/error-messages/compiler-errors-2/compiler-error-c3172.md index 832aaa9c403..5bcbd0ef9ef 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3172.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3172.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Error C3172" title: "Compiler Error C3172" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3172" +ms.date: 11/04/2016 f1_keywords: ["C3172"] helpviewer_keywords: ["C3172"] -ms.assetid: 1834e2fd-6036-4c33-aff2-b51bc7c99441 --- # Compiler Error C3172 -'module_name': cannot specify different idl_module attributes in a project +> 'module_name': cannot specify different idl_module attributes in a project + +## Remarks [idl_module](../../windows/attributes/idl-module.md) attributes with the same name but different `dllname` or `version` parameters were found in two of the files in a compilation. Only one unique `idl_module` attribute can be specified per compilation. Identical `idl_module` attributes can be specified in more than one source code file. +## Example + For example, if the following `idl_module` attributes were found: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3173.md b/docs/error-messages/compiler-errors-2/compiler-error-c3173.md index 264132ec13c..39d61590982 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3173.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3173.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3173" title: "Compiler Error C3173" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3173" +ms.date: 11/04/2016 f1_keywords: ["C3173"] helpviewer_keywords: ["C3173"] -ms.assetid: edf79e10-e8cf-4f76-8d33-ab9d05e974e9 --- # Compiler Error C3173 -version mismatch in idl merge +> version mismatch in idl merge + +## Remarks This error occurs when an object file contains embedded idl that was generated with a previous version of the compiler. The compiler encodes a version number to ensure that the same compiler used to generate the idl content that is embedded in the .obj files is also the same compiler used to merge the embedded idl. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3174.md b/docs/error-messages/compiler-errors-2/compiler-error-c3174.md index 43fbd18675c..c73157a2997 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3174.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3174.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3174" title: "Compiler Error C3174" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3174" +ms.date: 11/04/2016 f1_keywords: ["C3174"] helpviewer_keywords: ["C3174"] -ms.assetid: fe6b3b5a-8196-485f-a45f-0b2e51df4086 --- # Compiler Error C3174 -module attribute was not specified +> module attribute was not specified + +## Remarks A program that uses Visual C++ attributes did not also use the [module](../../windows/attributes/module-cpp.md) attribute, which is required in any program that uses attributes. -The following sample generates C3174: +## Example + +The following example generates C3174: ```cpp // C3174.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3175.md b/docs/error-messages/compiler-errors-2/compiler-error-c3175.md index 410de47bc69..8cce6182a2d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3175.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3175.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3175" title: "Compiler Error C3175" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3175" +ms.date: 11/04/2016 f1_keywords: ["C3175"] helpviewer_keywords: ["C3175"] -ms.assetid: 3f19d513-a05a-4b6c-806f-276fe5c36b90 --- # Compiler Error C3175 -'function1' : cannot call a method of a managed type from unmanaged function 'function2' +> 'function1' : cannot call a method of a managed type from unmanaged function 'function2' + +## Remarks Unmanaged functions cannot call member functions of managed classes. -The following sample generates C3175: +## Example + +The following example generates C3175: ```cpp // C3175_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3176.md b/docs/error-messages/compiler-errors-2/compiler-error-c3176.md index 9252c20ad4c..dac1b4f9bdc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3176.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3176.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3176" title: "Compiler Error C3176" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3176" +ms.date: 11/04/2016 f1_keywords: ["C3176"] helpviewer_keywords: ["C3176"] -ms.assetid: 6cc8d602-8e15-47a7-b1b5-e93e5d50e271 --- # Compiler Error C3176 -'type' : cannot declare local value type +> 'type' : cannot declare local value type + +## Remarks A class can only be declared as a value type at global scope. ## Example -The following sample generates C3176. +The following example generates C3176. ```cpp // C3176.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3179.md b/docs/error-messages/compiler-errors-2/compiler-error-c3179.md index 3ae78d152d7..20752c024d2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3179.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3179.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3179" title: "Compiler Error C3179" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3179" +ms.date: 11/04/2016 f1_keywords: ["C3179"] helpviewer_keywords: ["C3179"] -ms.assetid: 60d7e41b-25fd-48ac-8b79-830c062f4dcd --- # Compiler Error C3179 -an unnamed managed or WinRT type is not allowed +> an unnamed managed or WinRT type is not allowed + +## Remarks All CLR and WinRT classes and structs must have names. -The following sample generates C3179 and shows how to fix it: +## Example + +The following example generates C3179 and shows how to fix it: ```cpp // C3179a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3180.md b/docs/error-messages/compiler-errors-2/compiler-error-c3180.md index 7c795d00663..c5e39e638b9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3180.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3180.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3180" title: "Compiler Error C3180" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3180" +ms.date: 11/04/2016 f1_keywords: ["C3180"] helpviewer_keywords: ["C3180"] -ms.assetid: 5281f583-7df7-418a-8507-d4da67ed6572 --- # Compiler Error C3180 -'type name' : name exceeds meta-data limit of 'limit' characters +> 'type name' : name exceeds meta-data limit of 'limit' characters + +## Remarks The compiler truncated the name for a managed type in metadata. The truncation will make the type unusable with the `#using` directive (or the equivalent in another language). diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3181.md b/docs/error-messages/compiler-errors-2/compiler-error-c3181.md index 1af9f7eccf5..4c71262029e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3181.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3181.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3181" title: "Compiler Error C3181" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3181" +ms.date: 11/04/2016 f1_keywords: ["C3181"] helpviewer_keywords: ["C3181"] -ms.assetid: 5d450f8b-6cef-4452-a0c4-2076e967451d --- # Compiler Error C3181 -'type' : invalid operand for operator +> 'type' : invalid operand for operator + +## Remarks An invalid parameter was passed to the [typeid](../../extensions/typeid-cpp-component-extensions.md) operator. The parameter must be a managed type. Note that the compiler uses aliases for native types that map to types in the common language runtime. -The following sample generates C3181: +## Example + +The following example generates C3181: ```cpp // C3181a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3182.md b/docs/error-messages/compiler-errors-2/compiler-error-c3182.md index 9c3772dff9c..56822448225 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3182.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3182.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3182" title: "Compiler Error C3182" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3182" +ms.date: 11/04/2016 f1_keywords: ["C3182"] helpviewer_keywords: ["C3182"] -ms.assetid: f3681266-308e-4990-a979-8eef8920e186 --- # Compiler Error C3182 -'class' : a member using-declaration or access declaration is illegal within a managed or WinRTtype +> 'class' : a member using-declaration or access declaration is illegal within a managed or WinRTtype + +## Remarks A [using](../../cpp/using-declaration.md) declaration is invalid within all forms of managed classes. -The following sample generates C3182 and shows how to fix it. +## Example + +The following example generates C3182 and shows how to fix it. ```cpp // C3182a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3183.md b/docs/error-messages/compiler-errors-2/compiler-error-c3183.md index 82ad13cdc56..c23ae7054a4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3183.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3183.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3183" title: "Compiler Error C3183" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3183" +ms.date: 11/04/2016 f1_keywords: ["C3183"] helpviewer_keywords: ["C3183"] -ms.assetid: dbd0f020-c739-43c9-947e-9ce21537331b --- # Compiler Error C3183 -cannot define unnamed class, struct or union inside of managed or WinRT type 'type' +> cannot define unnamed class, struct or union inside of managed or WinRT type 'type' + +## Remarks A type that is embedded in a managed or WinRT type must be named. -The following sample generates C3183: +## Example + +The following example generates C3183: ```cpp // C3183a.cpp 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 cad61481f3e..a4b6c832e37 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3185.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3185.md @@ -1,18 +1,21 @@ --- -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 -'typeid' used on managed or WinRT type 'type', use 'operator' instead +> 'typeid' used on managed or WinRT type 'type', use 'operator' instead + +## Remarks You cannot apply the [typeid](../../cpp/typeid-operator.md) operator to a managed or WinRT type; use [typeid](../../extensions/typeid-cpp-component-extensions.md) instead. -The following sample generates C3185 and shows how to fix it: +## Example + +The following example generates C3185 and shows how to fix it: ```cpp // C3185a.cpp @@ -25,5 +28,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-c3187.md b/docs/error-messages/compiler-errors-2/compiler-error-c3187.md index 4ef3efeedb4..1bb673cd78a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3187.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3187.md @@ -1,15 +1,39 @@ --- -description: "Learn more about: Compiler Error C3187" title: "Compiler Error C3187" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3187" +ms.date: 01/28/2026 f1_keywords: ["C3187"] helpviewer_keywords: ["C3187"] -ms.assetid: 9d2ebf55-1a6a-4087-bf5b-5274baae6351 --- # Compiler Error C3187 -> '`__func__`' : is only available within the body of a function +> '`__func__`': is only available within the body of a function + +## Remarks + +The predefined identifier [`__func__`](../../cpp/func.md) is not available outside the body of a function. + +To correct this error, move the identifier inside the body of a function. + +## Example + +The following example generates C3187: + +```cpp +// compile with: /c + +#include + +auto global = __func__; // C3187, usage in global scope +void func(const char* f = __func__); // C3187, usage in parameter list + +// correct usage inside a function +void test() +{ + std::cout << __func__; // outputs: test +} +``` -The predefined macro is not available outside the body of a function. +## See also -To correct this error, move the macro inside the body of a function. +[C2457](../compiler-errors-1/compiler-error-c2457.md) diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3189.md b/docs/error-messages/compiler-errors-2/compiler-error-c3189.md index 6197c274ae7..90248e75159 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3189.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3189.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3189" title: "Compiler Error C3189" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3189" +ms.date: 11/04/2016 f1_keywords: ["C3189"] helpviewer_keywords: ["C3189"] -ms.assetid: b254de79-931e-4a59-a9f4-1c690d90ca5e --- # Compiler Error C3189 > 'typeid\': this syntax is no longer supported, use ::typeid instead +## Remarks + An obsolete form of [typeid](../../extensions/typeid-cpp-component-extensions.md) was used, use the new form. This error is obsolete in Visual Studio 2022 and later versions. -The following sample generates C3189: +## Example + +The following example generates C3189: ```cpp // C3189.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3190.md b/docs/error-messages/compiler-errors-2/compiler-error-c3190.md index a1fd356cb1b..3b55ad91f4e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3190.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3190.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3190" title: "Compiler Error C3190" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3190" +ms.date: 11/04/2016 f1_keywords: ["C3190"] helpviewer_keywords: ["C3190"] -ms.assetid: 7c701afa-85a7-4f7a-8881-0662436ac244 --- # Compiler Error C3190 -'instantiation' with the provided template arguments is not the explicit instantiation of any member function of 'type' +> 'instantiation' with the provided template arguments is not the explicit instantiation of any member function of 'type' + +## Remarks The compiler detected an attempt to make an explicit function instantiation; however, the provided type arguments do not match any of the possible functions. -The following sample generates C3190: +## Example + +The following example generates C3190: ```cpp // C3190.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3192.md b/docs/error-messages/compiler-errors-2/compiler-error-c3192.md index b9e9dd8a921..28b5f9c2d5a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3192.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3192.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3192" title: "Compiler Error C3192" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3192" +ms.date: 11/04/2016 f1_keywords: ["C3192"] helpviewer_keywords: ["C3192"] -ms.assetid: 8b0083d4-706f-46f6-858a-e1d9af464cf8 --- # Compiler Error C3192 -syntax error : '^' is not a prefix operator (did you mean '*'?) +> syntax error : '^' is not a prefix operator (did you mean '*'?) + +## Remarks A handle cannot be used as a dereference operator. -The following sample generates C3192: +## Example + +The following example generates C3192: ```cpp // C3192.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3194.md b/docs/error-messages/compiler-errors-2/compiler-error-c3194.md index a33d63090f6..8db7784857a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3194.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3194.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3194" title: "Compiler Error C3194" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3194" +ms.date: 11/04/2016 f1_keywords: ["C3194"] helpviewer_keywords: ["C3194"] -ms.assetid: 49d3ffc6-eff6-4b46-865b-18811692a8bb --- # Compiler Error C3194 -'member' : a value-type cannot have an assignment operator +> 'member' : a value-type cannot have an assignment operator + +## Remarks Special member functions that require automatic invocation by the compiler, such as a copy constructor or copy assignment operator are not supported within a value class. ## Example -The following sample generates C3194. +The following example generates C3194. ```cpp // C3194.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3195.md b/docs/error-messages/compiler-errors-2/compiler-error-c3195.md index 415527ec2dd..ec488b88ac7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3195.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3195.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3195" title: "Compiler Error C3195" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3195" +ms.date: 11/04/2016 f1_keywords: ["C3195"] helpviewer_keywords: ["C3195"] -ms.assetid: 97e4f681-812b-49e8-ba57-24b7817e3cd8 --- # Compiler Error C3195 -'operator' : is reserved and cannot be used as a member of a ref class or value type. CLR or WinRT operators must be defined using the 'operator' keyword +> 'operator' : is reserved and cannot be used as a member of a ref class or value type. CLR or WinRT operators must be defined using the 'operator' keyword + +## Remarks The compiler detected an operator definition using the Managed Extensions for C++ syntax. You must use the C++ syntax for operators. -The following sample generates C3195 and shows how to fix it: +## Example + +The following example generates C3195 and shows how to fix it: ```cpp // C3195.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3196.md b/docs/error-messages/compiler-errors-2/compiler-error-c3196.md index 38cf9afdc32..070c0c87ed4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3196.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3196.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3196" title: "Compiler Error C3196" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3196" +ms.date: 11/04/2016 f1_keywords: ["C3196"] helpviewer_keywords: ["C3196"] -ms.assetid: d9c38a13-191d-472d-aa2b-f61a6459d16c --- # Compiler Error C3196 -'keyword' : used more than once +> 'keyword' : used more than once + +## Remarks A keyword was used more than once. -The following sample generates C3196: +## Example + +The following example generates C3196: ```cpp // C3196.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3197.md b/docs/error-messages/compiler-errors-2/compiler-error-c3197.md index b5153e95918..3362584a4a0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3197.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3197.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3197" title: "Compiler Error C3197" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3197" +ms.date: 11/04/2016 f1_keywords: ["C3197"] helpviewer_keywords: ["C3197"] -ms.assetid: 4e385c3b-222e-425c-9612-46e83ed41650 --- # Compiler Error C3197 -'keyword' : can only be used in definitions +> 'keyword' : can only be used in definitions + +## Remarks A keyword was used in a declaration but is only valid in a definition. -The following sample generates C3197: +## Example + +The following example generates C3197: ```cpp // C3197.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3198.md b/docs/error-messages/compiler-errors-2/compiler-error-c3198.md index d853ab33b43..b871f254a6e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3198.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3198.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3198" title: "Compiler Error C3198" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3198" +ms.date: 11/04/2016 f1_keywords: ["C3198"] helpviewer_keywords: ["C3198"] -ms.assetid: ec4ecf61-0067-4aa4-b443-a91013a1e59d --- # Compiler Error C3198 -invalid use of floating-point pragmas: fenv_access pragma operates only in precise mode +> invalid use of floating-point pragmas: fenv_access pragma operates only in precise mode + +## Remarks [fenv_access](../../preprocessor/fenv-access.md) pragma was used under an [/fp](../../build/reference/fp-specify-floating-point-behavior.md) setting other than **/fp:precise**. -The following sample generates C3198: +## Example + +The following example generates C3198: ```cpp // C3198.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3199.md b/docs/error-messages/compiler-errors-2/compiler-error-c3199.md index 724e71a9f0d..fd0da44ace7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3199.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3199.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3199" title: "Compiler Error C3199" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3199" +ms.date: 11/04/2016 f1_keywords: ["C3199"] helpviewer_keywords: ["C3199"] -ms.assetid: e7a478d3-115a-40a3-991b-c7454fd2e28e --- # Compiler Error C3199 -invalid use of floating-point pragmas: exceptions are not supported in non-precise mode +> invalid use of floating-point pragmas: exceptions are not supported in non-precise mode + +## Remarks The [float_control](../../preprocessor/float-control.md) pragma was used to specify floating-point exception model under an [/fp](../../build/reference/fp-specify-floating-point-behavior.md) setting other than **/fp:precise**. -The following sample generates C3199: +## Example + +The following example generates C3199: ```cpp // C3199.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3200.md b/docs/error-messages/compiler-errors-2/compiler-error-c3200.md index e4b6fe76163..548a0b21c5a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3200.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3200.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Error C3200" title: "Compiler Error C3200" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3200" +ms.date: 11/04/2016 f1_keywords: ["C3200"] helpviewer_keywords: ["C3200"] -ms.assetid: 44bb5e77-f0ec-421c-a732-b9ee7c0a3529 --- # Compiler Error C3200 -'template' : invalid template argument for template parameter 'parameter', expected a class template +> 'template' : invalid template argument for template parameter 'parameter', expected a class template + +## Remarks + +You passed an invalid argument to a class template. The class template expects template as a parameter. + +## Example -You passed an invalid argument to a class template. The class template expects template as a parameter. In the following example, calling `Y aY` will generate C3200. The first parameter needs to be a template, such as `Y aY`. +In the following example, calling `Y aY` will generate C3200. The first parameter needs to be a template, such as `Y aY`. ```cpp // C3200.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3201.md b/docs/error-messages/compiler-errors-2/compiler-error-c3201.md index a8042c538fe..6799ee98060 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3201.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3201.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: Compiler Error C3201" title: "Compiler Error C3201" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3201" +ms.date: 11/04/2016 f1_keywords: ["C3201"] helpviewer_keywords: ["C3201"] -ms.assetid: ec19cd64-1789-40a3-b2db-dff2852b9d98 --- # Compiler Error C3201 -the template parameter list for class template 'template' does not match the template parameter list for template parameter 'template' +> the template parameter list for class template 'template' does not match the template parameter list for template parameter 'template' + +## Remarks You passed a class template in the argument to a class template that does not take a template parameter, or you passed a mismatched number of template arguments for the default template argument. +## Example + +The following example generates C3201: + ```cpp // C3201.cpp template diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3202.md b/docs/error-messages/compiler-errors-2/compiler-error-c3202.md index 30bd9a0ebd0..f84c285a958 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3202.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3202.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3202" title: "Compiler Error C3202" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3202" +ms.date: 11/04/2016 f1_keywords: ["C3202"] helpviewer_keywords: ["C3202"] -ms.assetid: 23528a0c-5493-4804-9789-cd3c38e49fb9 --- # Compiler Error C3202 -'arg name' : invalid default argument for template parameter 'parameter', expected a class template +> 'arg name' : invalid default argument for template parameter 'parameter', expected a class template + +## Remarks You passed an invalid default argument for a template parameter. -The following sample generates C3202: +## Example + +The following example generates C3202: ```cpp // C3202.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3203.md b/docs/error-messages/compiler-errors-2/compiler-error-c3203.md index f06d5ca3de2..9eda8670397 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3203.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3203.md @@ -1,19 +1,24 @@ --- -description: "Learn more about: Compiler Error C3203" title: "Compiler Error C3203" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3203" +ms.date: 11/04/2016 f1_keywords: ["C3203"] helpviewer_keywords: ["C3203"] -ms.assetid: 6356770e-22c1-434c-91fe-f60b0aa23b91 --- # Compiler Error C3203 -'type' : unspecialized class template or generic can't be used as a template or generic argument for template or generic parameter 'param', expected a real type +> 'type' : unspecialized class template or generic can't be used as a template or generic argument for template or generic parameter 'param', expected a real type + +## Remarks You passed an invalid argument to a class template or generic. The class template or generic expects a type as a parameter. This error can be generated as a result of compiler conformance work that was done for Visual Studio 2005: an unspecialized class template can't be used as a template argument in a base class list. To resolve C3203, explicitly add the template type parameter(s) to the template class name when using it as a template parameter in a base class list. +## Examples + +The following example generates C3203: + ```cpp // C3203.cpp template< typename T > @@ -33,7 +38,7 @@ int main() { } ``` -The following sample generates C3203 and shows how to fix it: +The following example generates C3203 and shows how to fix it: ```cpp // C3203_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3204.md b/docs/error-messages/compiler-errors-2/compiler-error-c3204.md index 60063fce8c1..fcbc33e8a80 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3204.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3204.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3204" title: "Compiler Error C3204" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3204" +ms.date: 11/04/2016 f1_keywords: ["C3204"] helpviewer_keywords: ["C3204"] -ms.assetid: 06e578da-0262-48c8-b2ae-be1cd6d28884 --- # Compiler Error C3204 -'_alloca' cannot be called from within a catch block +> '_alloca' cannot be called from within a catch block + +## Remarks This error occurs when you use a call to [_alloca](../../c-runtime-library/reference/alloca.md) from within a catch block. ## Example -The following sample generates C3204: +The following example generates C3204: ```cpp // C3204.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3205.md b/docs/error-messages/compiler-errors-2/compiler-error-c3205.md index 40350e71348..0e0223a4cd1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3205.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3205.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3205" title: "Compiler Error C3205" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3205" +ms.date: 11/04/2016 f1_keywords: ["C3205"] helpviewer_keywords: ["C3205"] -ms.assetid: 802d306e-5ff3-4491-8a22-c5f1c072d005 --- # Compiler Error C3205 -argument list for template parameter 'parameter' is missing +> argument list for template parameter 'parameter' is missing + +## Remarks A [template](../../cpp/templates-cpp.md) parameter is missing. ## Example -The following sample generates C3205: +The following example generates C3205: ```cpp // C3205.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3206.md b/docs/error-messages/compiler-errors-2/compiler-error-c3206.md index 0a8b1244403..188fa575037 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3206.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3206.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3206" title: "Compiler Error C3206" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3206" +ms.date: 11/04/2016 f1_keywords: ["C3206"] helpviewer_keywords: ["C3206"] -ms.assetid: d62995b5-e349-4418-bbe8-8a5e776ca7b0 --- # Compiler Error C3206 -'function' : invalid type argument for 'param', missing type argument list on class type 'typename' +> 'function' : invalid type argument for 'param', missing type argument list on class type 'typename' + +## Remarks + +A function template is defined as taking a template type argument. However, a template template argument was passed. -A template function is defined as taking a template type argument. However, a template template argument was passed. +## Examples -The following sample generates C3206: +The following example generates C3206: ```cpp // C3206.cpp @@ -77,7 +80,7 @@ int main() { } ``` -A class template is not allowed as a template type argument. The following sample raises C3206: +A class template is not allowed as a template type argument. The following example raises C3206: ```cpp // C3206e.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3207.md b/docs/error-messages/compiler-errors-2/compiler-error-c3207.md index 4fc51223a19..b26b866d47d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3207.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3207.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3207" title: "Compiler Error C3207" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3207" +ms.date: 11/04/2016 f1_keywords: ["C3207"] helpviewer_keywords: ["C3207"] -ms.assetid: 4a28b976-142a-4cff-aa2f-480b892c50ca --- # Compiler Error C3207 -'function' : invalid template argument for 'arg', class template expected +> 'function' : invalid template argument for 'arg', class template expected + +## Remarks + +A function template is defined as taking a template template argument. However, a template type argument was passed. -A template function is defined as taking a template template argument. However, a template type argument was passed. +## Example -The following sample generates C3207: +The following example generates C3207: ```cpp // C3207.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3208.md b/docs/error-messages/compiler-errors-2/compiler-error-c3208.md index 503703f98ee..f8478e5ba06 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3208.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3208.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3208" title: "Compiler Error C3208" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3208" +ms.date: 11/04/2016 f1_keywords: ["C3208"] helpviewer_keywords: ["C3208"] -ms.assetid: 6d060bfe-52cf-4599-8f70-bdeb5a670df3 --- # Compiler Error C3208 -'function' : template parameter list for class template 'class' does not match template parameter list for template template parameter 'parameter' +> 'function' : template parameter list for class template 'class' does not match template parameter list for template template parameter 'parameter' + +## Remarks A template template parameter does not have the same number of template parameters as the provided class template. -The following sample generates C3208: +## Example + +The following example generates C3208: ```cpp // C3208.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3209.md b/docs/error-messages/compiler-errors-2/compiler-error-c3209.md index 333144c305b..7be3106af49 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3209.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3209.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3209" title: "Compiler Error C3209" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3209" +ms.date: 11/04/2016 f1_keywords: ["C3209"] helpviewer_keywords: ["C3209"] -ms.assetid: 1de44e39-69d1-4894-8f89-ff92136e8e5d --- # Compiler Error C3209 -'class' : generic class must be a managed or WinRTclass +> 'class' : generic class must be a managed or WinRTclass + +## Remarks A generic class must be a managed class or a Windows Runtime class. -The following sample generates C3209 and shows how to fix it: +## Example + +The following example generates C3209 and shows how to fix it: ```cpp // C3209.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3210.md b/docs/error-messages/compiler-errors-2/compiler-error-c3210.md index 53f447d6de6..bea665dad72 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3210.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3210.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3210" title: "Compiler Error C3210" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3210" +ms.date: 11/04/2016 f1_keywords: ["C3210"] helpviewer_keywords: ["C3210"] -ms.assetid: c6e9d309-fabc-4e7d-b526-be20d9fe3f6a --- # Compiler Error C3210 -'type' : access declaration can only be applied to a base class member +> 'type' : access declaration can only be applied to a base class member + +## Remarks A [using declaration](../../cpp/using-declaration.md) was specified incorrectly. ## Example -The following sample generates C3210. +The following example generates C3210. ```cpp // C3210.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3211.md b/docs/error-messages/compiler-errors-2/compiler-error-c3211.md index 964563891f5..be567ccd716 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3211.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3211.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3211" title: "Compiler Error C3211" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3211" +ms.date: 11/04/2016 f1_keywords: ["C3211"] helpviewer_keywords: ["C3211"] -ms.assetid: 85e33fed-3b59-4315-97e6-20d31c6a985a --- # Compiler Error C3211 -'explicit specialization' : explicit specialization is using partial specialization syntax, use template <> instead +> 'explicit specialization' : explicit specialization is using partial specialization syntax, use template <> instead + +## Remarks An explicit specialization was ill formed. -The following sample generates C3211: +## Example + +The following example generates C3211: ```cpp // C3211.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3212.md b/docs/error-messages/compiler-errors-2/compiler-error-c3212.md index 0930774cd11..0364fb2ac86 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3212.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3212.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3212" title: "Compiler Error C3212" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3212" +ms.date: 11/04/2016 f1_keywords: ["C3212"] helpviewer_keywords: ["C3212"] -ms.assetid: 9e271bb6-a51f-4b96-b26b-9f4ca28fca0a --- # Compiler Error C3212 -'specialization' : an explicit specialization of a template member must be a member of an explicit specialization +> 'specialization' : an explicit specialization of a template member must be a member of an explicit specialization + +## Remarks An explicit specialization was ill formed. -The following sample generates C3212: +## Example + +The following example generates C3212: ```cpp // C3212.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3213.md b/docs/error-messages/compiler-errors-2/compiler-error-c3213.md index 9e56eefd1b3..92f037e2fc1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3213.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3213.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3213" title: "Compiler Error C3213" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3213" +ms.date: 11/04/2016 f1_keywords: ["C3213"] helpviewer_keywords: ["C3213"] -ms.assetid: 1f079e36-b3e9-40f8-8e95-08eeba3adc82 --- # Compiler Error C3213 -base class 'base_type' is less accessible than 'derived_type' +> base class 'base_type' is less accessible than 'derived_type' + +## Remarks A type that will be visible from an assembly must use publicly visible base classes. -The following sample generates C3213: +## Example + +The following example generates C3213: ```cpp // C3213.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3214.md b/docs/error-messages/compiler-errors-2/compiler-error-c3214.md index 7eeb9bc371a..7f83f18b2e9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3214.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3214.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3214" title: "Compiler Error C3214" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3214" +ms.date: 11/04/2016 f1_keywords: ["C3214"] helpviewer_keywords: ["C3214"] -ms.assetid: 49ee4a9a-2549-4adb-9d3a-38e154303c2e --- # Compiler Error C3214 -'type' : invalid type argument for generic parameter 'param' of generic 'generic_type', does not meet constraint 'constraint' +> 'type' : invalid type argument for generic parameter 'param' of generic 'generic_type', does not meet constraint 'constraint' + +## Remarks The type was specified for an instantiation of a generic class that does not meet the generic class's constraint. -The following sample generates C3214: +## Example + +The following example generates C3214: ```cpp // C3214.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3215.md b/docs/error-messages/compiler-errors-2/compiler-error-c3215.md index 6a6ca708566..23799ce938e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3215.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3215.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3215" title: "Compiler Error C3215" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3215" +ms.date: 11/04/2016 f1_keywords: ["C3215"] helpviewer_keywords: ["C3215"] -ms.assetid: d0d16007-8885-42e0-b086-2d3a61f348c5 --- # Compiler Error C3215 -'type1' : generic type parameter already constrained by 'type2' +> 'type1' : generic type parameter already constrained by 'type2' + +## Remarks A constraint was specified more than once. For more information on generics, see [Generics](../../extensions/generics-cpp-component-extensions.md). -The following sample generates C3215: +## Example + +The following example generates C3215: ```cpp // C3215.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3216.md b/docs/error-messages/compiler-errors-2/compiler-error-c3216.md index bbb2967e39e..22291b161a0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3216.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3216.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3216" title: "Compiler Error C3216" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3216" +ms.date: 11/04/2016 f1_keywords: ["C3216"] helpviewer_keywords: ["C3216"] -ms.assetid: bbab1efe-8779-4489-8bb0-b11e45f5cbe5 --- # Compiler Error C3216 -constraint must be a generic parameter, not 'type' +> constraint must be a generic parameter, not 'type' + +## Remarks A constraint was ill formed. -The following sample generates C3216: +## Example + +The following example generates C3216: ```cpp // C3216.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3217.md b/docs/error-messages/compiler-errors-2/compiler-error-c3217.md index 8cacbfeb157..c2628b1b6b8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3217.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3217.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3217" title: "Compiler Error C3217" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3217" +ms.date: 11/04/2016 f1_keywords: ["C3217"] helpviewer_keywords: ["C3217"] -ms.assetid: 99070417-c23a-4d82-bdd2-04be1a07adea --- # Compiler Error C3217 -'param' : generic parameter cannot be constrained in this declaration +> 'param' : generic parameter cannot be constrained in this declaration + +## Remarks A constraint was ill formed; the constraint generic parameter must agree with the generic class template parameter. -The following sample generates C3217: +## Example + +The following example generates C3217: ```cpp // C3217.cpp @@ -27,7 +30,7 @@ ref class C { }; ``` -The following sample demonstrates a possible resolution: +The following example demonstrates a possible resolution: ```cpp // C3217b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3218.md b/docs/error-messages/compiler-errors-2/compiler-error-c3218.md index c1abbab3d5a..691dc13049b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3218.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3218.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3218" title: "Compiler Error C3218" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3218" +ms.date: 11/04/2016 f1_keywords: ["C3218"] helpviewer_keywords: ["C3218"] -ms.assetid: 0eea19e0-503e-4e07-ae8b-2cb2e95922cd --- # Compiler Error C3218 -'type' : type not allowed as a constraint +> 'type' : type not allowed as a constraint + +## Remarks For a type to be a constraint, it must be either a value type or reference to a managed class or interface. ## Example -The following sample generates C3218. +The following example generates C3218. ```cpp // C3218.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3219.md b/docs/error-messages/compiler-errors-2/compiler-error-c3219.md index 4ee80752f48..4800bece797 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3219.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3219.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3219" title: "Compiler Error C3219" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3219" +ms.date: 11/04/2016 f1_keywords: ["C3219"] helpviewer_keywords: ["C3219"] -ms.assetid: 9c9757b0-1256-4cdf-9d8c-a3a72f300ce5 --- # Compiler Error C3219 -'param' : generic parameter cannot be constrained by multiple non-interfaces : 'class' +> 'param' : generic parameter cannot be constrained by multiple non-interfaces : 'class' + +## Remarks It is not valid to constrain a generic parameter by two or more managed classes. -The following sample generates C3219: +## Example + +The following example generates C3219: ```cpp // C3219.cpp @@ -25,7 +28,7 @@ where T : A, B ref class E {}; // C3219 ``` -The following sample demonstrates a possible resolution: +The following example demonstrates a possible resolution: ```cpp // C3219b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3222.md b/docs/error-messages/compiler-errors-2/compiler-error-c3222.md index 09815402d91..0bf257f399f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3222.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3222.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3222" title: "Compiler Error C3222" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3222" +ms.date: 11/04/2016 f1_keywords: ["C3222"] helpviewer_keywords: ["C3222"] -ms.assetid: 5624bde8-2fd0-4b8b-92ce-5dfbaf91cf93 --- # Compiler Error C3222 -'parameter' : cannot declare default arguments for member functions of a managed or WinRT type or generic functions +> 'parameter' : cannot declare default arguments for member functions of a managed or WinRT type or generic functions + +## Remarks It is not permitted to declare a method parameter with a default argument. An overloaded form of the method is one way to work around this issue. That is, define a method with the same name with no parameters and then initialize the variable in the method body. -The following sample generates C3222: +## Example + +The following example generates C3222: ```cpp // C3222_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3223.md b/docs/error-messages/compiler-errors-2/compiler-error-c3223.md index 0895d06aaa9..778004eaa27 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3223.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3223.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3223" title: "Compiler Error C3223" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3223" +ms.date: 11/04/2016 f1_keywords: ["C3223"] helpviewer_keywords: ["C3223"] -ms.assetid: 1f4380b4-0413-40db-a868-62f97babaf78 --- # Compiler Error C3223 -'property' : you cannot apply 'typeid' to a property +> 'property' : you cannot apply 'typeid' to a property + +## Remarks You cannot apply [typeid](../../extensions/typeid-cpp-component-extensions.md) to a property. ## Example -The following sample generates C3223. +The following example generates C3223. ```cpp // C3223.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3224.md b/docs/error-messages/compiler-errors-2/compiler-error-c3224.md index 3262737e78b..83735abdfb6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3224.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3224.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3224" title: "Compiler Error C3224" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3224" +ms.date: 11/04/2016 f1_keywords: ["C3224"] helpviewer_keywords: ["C3224"] -ms.assetid: 129be22f-8f3e-4fc6-9ccd-d27d8ef91251 --- # Compiler Error C3224 -'type' : no overloaded generic class takes 'number' generic type arguments +> 'type' : no overloaded generic class takes 'number' generic type arguments + +## Remarks The compiler failed to find an appropriate overload. -The following sample generates C3224: +## Example + +The following example generates C3224: ``` // C3224.cs diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3225.md b/docs/error-messages/compiler-errors-2/compiler-error-c3225.md index d43f5993964..c0bb2c4af55 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3225.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3225.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3225" title: "Compiler Error C3225" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3225" +ms.date: 11/04/2016 f1_keywords: ["C3225"] helpviewer_keywords: ["C3225"] -ms.assetid: f5f66973-256e-4298-ac46-c87819cbde34 --- # Compiler Error C3225 -generic type argument for 'arg' cannot be 'type', it must be a value type or handle type +> generic type argument for 'arg' cannot be 'type', it must be a value type or handle type + +## Remarks The generic type argument was not of the correct type. @@ -16,7 +17,7 @@ For more information, see [Generics](../../extensions/generics-cpp-component-ext ## Examples -You cannot instantiate a generic type with a native type. The following sample generates C3225. +You cannot instantiate a generic type with a native type. The following example generates C3225. ```cpp // C3225.cpp @@ -34,7 +35,7 @@ int main() { } ``` -The following sample creates a component using C#. Notice that the constraint specifies that the generic type can only be instantiated with a value type. +The following example creates a component using C#. Notice that the constraint specifies that the generic type can only be instantiated with a value type. ``` // C3225_b.cs @@ -43,7 +44,7 @@ The following sample creates a component using C#. Notice that the constraint sp public class MyList where T: struct {} ``` -This sample consumes the C#-authored component, and violates the constraint that MyList can only be instantiated with a value type other than . The following sample generates C3225. +This example consumes the C#-authored component, and violates the constraint that MyList can only be instantiated with a value type other than . The following example generates C3225. ```cpp // C3225_c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3226.md b/docs/error-messages/compiler-errors-2/compiler-error-c3226.md index ecdbe62b7b5..298a2d8a275 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3226.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3226.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3226" title: "Compiler Error C3226" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3226" +ms.date: 11/04/2016 f1_keywords: ["C3226"] helpviewer_keywords: ["C3226"] -ms.assetid: 636106ca-6f4e-4303-a6a0-8803221ec67d --- # Compiler Error C3226 -A template declaration is not allowed inside a generic declaration +> A template declaration is not allowed inside a generic declaration + +## Remarks Use a generic declaration inside a generic class. -The following sample generates C3226: +## Example + +The following example generates C3226: ```cpp // C3226.cpp @@ -24,7 +27,7 @@ ref class C { }; ``` -The following sample demonstrates a possible resolution: +The following example demonstrates a possible resolution: ```cpp // C3226b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3227.md b/docs/error-messages/compiler-errors-2/compiler-error-c3227.md index 4917215a910..1674ac4f55c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3227.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3227.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3227" title: "Compiler Error C3227" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3227" +ms.date: 11/04/2016 f1_keywords: ["C3227"] helpviewer_keywords: ["C3227"] -ms.assetid: 7939c23a-96c8-43c2-89e9-f217d132d155 --- # Compiler Error C3227 -'parameter' : cannot use 'keyword' to allocate a generic type +> 'parameter' : cannot use 'keyword' to allocate a generic type + +## Remarks In order to instantiate a type, an appropriate constructor is required. However, the compiler is not able to ensure that an appropriate constructor is available. @@ -16,7 +17,7 @@ You can use templates instead of generics to resolve this error, or you can use ## Example -The following sample generates C3227. +The following example generates C3227. ```cpp // C3227.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3228.md b/docs/error-messages/compiler-errors-2/compiler-error-c3228.md index 78fa2305b55..99d9de708f6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3228.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3228.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3228" title: "Compiler Error C3228" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3228" +ms.date: 11/04/2016 f1_keywords: ["C3228"] helpviewer_keywords: ["C3228"] -ms.assetid: 9015adf9-17b0-4312-b4a7-c1f33e4126f4 --- # Compiler Error C3228 -'function' : generic type argument for 'param' cannot be 'type', it must be a valuetype or handle type +> 'function' : generic type argument for 'param' cannot be 'type', it must be a valuetype or handle type + +## Remarks An incorrect type was passed as a generic type argument. -The following sample generates C3228: +## Example + +The following example generates C3228: ```cpp // C3228.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3229.md b/docs/error-messages/compiler-errors-2/compiler-error-c3229.md index ed9e525ef2c..c19f6c0bf8c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3229.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3229.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3229" title: "Compiler Error C3229" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3229" +ms.date: 11/04/2016 f1_keywords: ["C3229"] helpviewer_keywords: ["C3229"] -ms.assetid: f2d90923-aa8b-444f-ab10-1f37dbb864e1 --- # Compiler Error C3229 -'type' : indirections on a generic type parameter are not allowed +> 'type' : indirections on a generic type parameter are not allowed + +## Remarks You cannot use generic parameters with `*`, `^`, or `&`. ## Examples -The following sample generates C3229. +The following example generates C3229. ```cpp // C3229.cpp @@ -31,7 +32,7 @@ ref class D { }; ``` -The following sample generates C3229. +The following example generates C3229. ```cpp // C3229_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3230.md b/docs/error-messages/compiler-errors-2/compiler-error-c3230.md index 75fbf6d7d1c..c58e94c7255 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3230.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3230.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3230" title: "Compiler Error C3230" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3230" +ms.date: 11/04/2016 f1_keywords: ["C3230"] helpviewer_keywords: ["C3230"] -ms.assetid: 5ec53f25-59f6-4801-81e7-7b68bf04994d --- # Compiler Error C3230 -'function' : template type argument for 'template' cannot contain a generic type parameter: 'param' +> 'function' : template type argument for 'template' cannot contain a generic type parameter: 'param' + +## Remarks Templates are instantiated at compile time, but generics are instantiated at run time. Therefore, it is not possible to generate generic code that can call the template because the template cannot be instantiated at run time when the generic type is finally known. -The following sample generates C3230: +## Example + +The following example generates C3230: ```cpp // C3230.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3231.md b/docs/error-messages/compiler-errors-2/compiler-error-c3231.md index 8b4b8d161bf..f6d1c264985 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3231.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3231.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3231" title: "Compiler Error C3231" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3231" +ms.date: 11/04/2016 f1_keywords: ["C3231"] helpviewer_keywords: ["C3231"] -ms.assetid: fe5dc352-e634-45fa-9534-3da176294c98 --- # Compiler Error C3231 -'arg' : template type argument cannot use a generic type parameter +> 'arg' : template type argument cannot use a generic type parameter + +## Remarks Templates are instantiated at compile time, but generics are instantiated at run time. Therefore, it is not possible to generate generic code that can call the template because the template cannot be instantiated at run time when the generic type is finally known. -The following sample generates C3231: +## Example + +The following example generates C3231: ```cpp // C3231.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3232.md b/docs/error-messages/compiler-errors-2/compiler-error-c3232.md index ed8f0a32c43..9608a4d798f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3232.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3232.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3232" title: "Compiler Error C3232" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3232" +ms.date: 11/04/2016 f1_keywords: ["C3232"] helpviewer_keywords: ["C3232"] -ms.assetid: 3119b3a9-0eff-4a3f-b805-e4d160af9e39 --- # Compiler Error C3232 -'param' : a generic type parameter cannot be used in a qualified name +> 'param' : a generic type parameter cannot be used in a qualified name + +## Remarks A generic type parameter was used incorrectly. -The following sample generates C3232: +## Example + +The following example generates C3232: ```cpp // C3232.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3233.md b/docs/error-messages/compiler-errors-2/compiler-error-c3233.md index cab7999c98c..93f9a1bbf8e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3233.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3233.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3233" title: "Compiler Error C3233" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3233" +ms.date: 11/04/2016 f1_keywords: ["C3233"] helpviewer_keywords: ["C3233"] -ms.assetid: a9210830-1136-4f02-ba41-030c85f93547 --- # Compiler Error C3233 -'type' : generic type parameter already constrained +> 'type' : generic type parameter already constrained + +## Remarks It is not valid to constrain a generic parameter in more than one `where` clause. -The following sample generates C3233: +## Example + +The following example generates C3233: ```cpp // C3233.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3234.md b/docs/error-messages/compiler-errors-2/compiler-error-c3234.md index 0239ec60f31..e6b26096cb8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3234.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3234.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3234" title: "Compiler Error C3234" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3234" +ms.date: 11/04/2016 f1_keywords: ["C3234"] helpviewer_keywords: ["C3234"] -ms.assetid: ebefc15a-e40d-424b-a3dd-d7e185d0ed7b --- # Compiler Error C3234 -a generic class may not derive from a generic type parameter +> a generic class may not derive from a generic type parameter + +## Remarks A generic class cannot inherit from a generic type parameter. ## Example -The following sample generates C3234. +The following example generates C3234. ```cpp // C3234.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3235.md b/docs/error-messages/compiler-errors-2/compiler-error-c3235.md index 40c569e6718..e88284ee42d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3235.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3235.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3235" title: "Compiler Error C3235" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3235" +ms.date: 11/04/2016 f1_keywords: ["C3235"] helpviewer_keywords: ["C3235"] -ms.assetid: 0554d6c7-e1dc-4c99-8934-cbcf491c8203 --- # Compiler Error C3235 -'specialization' : explicit or partial specialization of a generic class is not allowed +> 'specialization' : explicit or partial specialization of a generic class is not allowed + +## Remarks Generic classes cannot be used for explicit or partial specializations. ## Example -The following sample generates C3235. +The following example generates C3235. ```cpp // C3235.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3236.md b/docs/error-messages/compiler-errors-2/compiler-error-c3236.md index 7bdd011603e..40f1e394497 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3236.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3236.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3236" title: "Compiler Error C3236" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3236" +ms.date: 11/04/2016 f1_keywords: ["C3236"] helpviewer_keywords: ["C3236"] -ms.assetid: 4ef1871f-a348-44ae-922b-1e2081de20d0 --- # Compiler Error C3236 -explicit instantiation of a generic is not allowed +> explicit instantiation of a generic is not allowed + +## Remarks The compiler does not allow explicit instantiation of generic classes. -The following sample generates C3236: +## Example + +The following example generates C3236: ```cpp // C3236.cpp @@ -23,7 +26,7 @@ public ref class X {}; generic ref class X; // C3236 ``` -The following sample demonstrates a possible resolution: +The following example demonstrates a possible resolution: ```cpp // C3236b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3237.md b/docs/error-messages/compiler-errors-2/compiler-error-c3237.md index 5faaa77e2c8..7e528bc49d1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3237.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3237.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3237" title: "Compiler Error C3237" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3237" +ms.date: 11/04/2016 f1_keywords: ["C3237"] helpviewer_keywords: ["C3237"] -ms.assetid: 690970c8-e13b-4ff3-96e3-5fd93c4d356b --- # Compiler Error C3237 -'generic_class' : a generic class cannot be a custom attribute +> 'generic_class' : a generic class cannot be a custom attribute + +## Remarks Generic classes cannot be user-defined attributes. ## Example -The following sample generates C3237. +The following example generates C3237. ```cpp // C3237.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3238.md b/docs/error-messages/compiler-errors-2/compiler-error-c3238.md index fa015df2c29..f2c99fe1706 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3238.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3238.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3238" title: "Compiler Error C3238" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3238" +ms.date: 11/04/2016 f1_keywords: ["C3238"] helpviewer_keywords: ["C3238"] -ms.assetid: 19942497-b3c5-4df0-9144-142ced92468b --- # Compiler Error C3238 -'type' : a type with this name has already been forwarded to assembly 'assembly' +> 'type' : a type with this name has already been forwarded to assembly 'assembly' + +## Remarks A type was defined in a client application that is also defined, via type forwarding syntax, in a referenced assembly. Both types cannot be defined in the scope of the application. @@ -16,7 +17,7 @@ See [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md) for ## Examples -The following sample creates an assembly that contains a type that was forwarded from another assembly. +The following example creates an assembly that contains a type that was forwarded from another assembly. ```cpp // C3238.cpp @@ -24,7 +25,7 @@ The following sample creates an assembly that contains a type that was forwarded public ref class R {}; ``` -The following sample creates an assembly that used to contain the type definition, but not only contains type forwarding syntax. +The following example creates an assembly that used to contain the type definition, but not only contains type forwarding syntax. ```cpp // C3238_b.cpp @@ -33,7 +34,7 @@ The following sample creates an assembly that used to contain the type definitio [ assembly:TypeForwardedTo(R::typeid) ]; ``` -The following sample generates C3238. +The following example generates C3238. ```cpp // C3238_c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3239.md b/docs/error-messages/compiler-errors-2/compiler-error-c3239.md index 9c080208e2a..c214f06fe32 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3239.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3239.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3239" title: "Compiler Error C3239" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3239" +ms.date: 11/04/2016 f1_keywords: ["C3239"] helpviewer_keywords: ["C3239"] -ms.assetid: 22a518b7-020f-4f3c-9963-a094667fd1ac --- # Compiler Error C3239 -'type' : pointer to interior/pin pointer is disallowed by the common language runtime +> 'type' : pointer to interior/pin pointer is disallowed by the common language runtime + +## Remarks The compiler encountered an invalid type. -The following sample generates C3229: +## Example + +The following example generates C3239: ```cpp // C3239.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3240.md b/docs/error-messages/compiler-errors-2/compiler-error-c3240.md index 4dd2cc0d81f..19d9853fa83 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3240.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3240.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3240" title: "Compiler Error C3240" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3240" +ms.date: 11/04/2016 f1_keywords: ["C3240"] helpviewer_keywords: ["C3240"] -ms.assetid: 1a8dc213-b80c-47ae-ada0-e9554b635d1e --- # Compiler Error C3240 -'function' : must be a non-overloaded abstract member function of 'type' +> 'function' : must be a non-overloaded abstract member function of 'type' + +## Remarks A base type contained a function that was defined. Function must be virtual. ## Example -The following sample generates C3240. +The following example generates C3240. ```cpp // C3240.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3241.md b/docs/error-messages/compiler-errors-2/compiler-error-c3241.md index 34ba8ad6560..9151758b840 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3241.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3241.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3241" title: "Compiler Error C3241" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3241" +ms.date: 11/04/2016 f1_keywords: ["C3241"] helpviewer_keywords: ["C3241"] -ms.assetid: 2ca14879-bba0-4a23-b22a-72cfff92d6a4 --- # Compiler Error C3241 -'method' : this method was not introduced by 'interface' +> 'method' : this method was not introduced by 'interface' + +## Remarks When you explicitly override a function, the function signature must exactly match the declaration for the function that you are overriding. -The following sample generates C3241: +## Example + +The following example generates C3241: ```cpp // C3241.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3242.md b/docs/error-messages/compiler-errors-2/compiler-error-c3242.md index 323f6db037c..290e2ae1513 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3242.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3242.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3242" title: "Compiler Error C3242" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3242" +ms.date: 11/04/2016 f1_keywords: ["C3242"] helpviewer_keywords: ["C3242"] -ms.assetid: c7621ced-d5c7-4595-904b-bd871676784c --- # Compiler Error C3242 -'function' : you can only explicitly override virtual functions +> 'function' : you can only explicitly override virtual functions + +## Remarks You tried to explicitly override a nonvirtual method. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3243.md b/docs/error-messages/compiler-errors-2/compiler-error-c3243.md index a250dd83090..3a52311b95c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3243.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3243.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3243" title: "Compiler Error C3243" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3243" +ms.date: 11/04/2016 f1_keywords: ["C3243"] helpviewer_keywords: ["C3243"] -ms.assetid: 35d8ad1a-377d-47df-be9d-c55eea23340f --- # Compiler Error C3243 -none of the overload functions were introduced by 'interface' +> none of the overload functions were introduced by 'interface' + +## Remarks You tried to [explicitly override](../../cpp/explicit-overrides-cpp.md) a member that does not exist in the specified interface. -The following sample generates C3243: +## Example + +The following example generates C3243: ```cpp // C3243.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3244.md b/docs/error-messages/compiler-errors-2/compiler-error-c3244.md index acaad50b54a..f94ccbfce06 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3244.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3244.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3244" title: "Compiler Error C3244" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3244" +ms.date: 11/04/2016 f1_keywords: ["C3244"] helpviewer_keywords: ["C3244"] -ms.assetid: dae6c49b-5212-4206-8f61-d4010c0b9969 --- # Compiler Error C3244 -'method' : this method was introduced by 'interface' not by 'interface' +> 'method' : this method was introduced by 'interface' not by 'interface' + +## Remarks You tried to [explicitly override](../../cpp/explicit-overrides-cpp.md) a member that does not exist in the specified interface but does exist in another base class. -The following sample generates C3244: +## Example + +The following example generates C3244: ```cpp // C3244.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3246.md b/docs/error-messages/compiler-errors-2/compiler-error-c3246.md index e3150e1036a..6458e051d45 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3246.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3246.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3246" title: "Compiler Error C3246" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3246" +ms.date: 11/04/2016 f1_keywords: ["C3246"] helpviewer_keywords: ["C3246"] -ms.assetid: ad85224a-e540-479b-a5eb-a3bc3964c30b --- # Compiler Error C3246 -'class' : cannot inherit from 'type' as it has been declared as 'sealed' +> 'class' : cannot inherit from 'type' as it has been declared as 'sealed' + +## Remarks A class that is marked as [sealed](../../extensions/sealed-cpp-component-extensions.md) cannot be the base class for any other classes. -The following sample generates C3246: +## Example + +The following example generates C3246: ```cpp // C3246_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3247.md b/docs/error-messages/compiler-errors-2/compiler-error-c3247.md index b5fa60f4205..93888a5ddb5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3247.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3247.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3247" title: "Compiler Error C3247" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3247" +ms.date: 11/04/2016 f1_keywords: ["C3247"] helpviewer_keywords: ["C3247"] -ms.assetid: f9a2bbb5-3fce-40bf-9fd3-835a5f164dbb --- # Compiler Error C3247 -'class1' : a coclass cannot inherit from another coclass 'class2' +> 'class1' : a coclass cannot inherit from another coclass 'class2' + +## Remarks A class marked with the [coclass](../../windows/attributes/coclass.md) attribute cannot inherit from another class marked with the `coclass` attribute. -The following sample generates C3247: +## Example + +The following example generates C3247: ```cpp // C3247.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3248.md b/docs/error-messages/compiler-errors-2/compiler-error-c3248.md index 700129cccdd..f2edd92a462 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3248.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3248.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3248" title: "Compiler Error C3248" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3248" +ms.date: 11/04/2016 f1_keywords: ["C3248"] helpviewer_keywords: ["C3248"] -ms.assetid: d00b9d7d-b6be-4a5b-bb52-48174ea71fc4 --- # Compiler Error C3248 -'function1': function declared as '__sealed' cannot be overridden by 'function2' +> 'function1': function declared as '__sealed' cannot be overridden by 'function2' + +## Remarks A derived class tried to override a **__sealed** virtual method. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3251.md b/docs/error-messages/compiler-errors-2/compiler-error-c3251.md index 8756c4429db..ff7203c63a0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3251.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3251.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3251" title: "Compiler Error C3251" +description: "Learn more about: Compiler Error C3251" ms.date: 06/01/2022 f1_keywords: ["C3251"] helpviewer_keywords: ["C3251"] -ms.assetid: 541c163e-5ee9-457c-a1e5-da860788b10d --- # Compiler Error C3251 > cannot invoke base class method on a value type instance +## Remarks + The following error occurs because `GetClass` is a member of `Microsoft.Runtime.Object`, not of `Microsoft.Runtime.Integer4`. This error is obsolete in Visual Studio 2022 and later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3252.md b/docs/error-messages/compiler-errors-2/compiler-error-c3252.md index 979108c12a0..0313cb3e10d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3252.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3252.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3252" title: "Compiler Error C3252" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3252" +ms.date: 11/04/2016 f1_keywords: ["C3252"] helpviewer_keywords: ["C3252"] -ms.assetid: aa9ad096-e9ac-41c7-8ad9-b966751c7c75 --- # Compiler Error C3252 -'method' : cannot reduce accessibility of a virtual method in a managed or WinRT type +> 'method' : cannot reduce accessibility of a virtual method in a managed or WinRT type + +## Remarks A class that implements a virtual method from a base class or any method from an interface cannot reduce the access of that method. Note that all methods in an interface are public. -The following sample generates C3252 and shows how to fix it: +## Example + +The following example generates C3252 and shows how to fix it: ```cpp // C3252.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3253.md b/docs/error-messages/compiler-errors-2/compiler-error-c3253.md index 789a18bd235..3fc664e8ad4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3253.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3253.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3253" title: "Compiler Error C3253" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3253" +ms.date: 11/04/2016 f1_keywords: ["C3253"] helpviewer_keywords: ["C3253"] -ms.assetid: da40be26-0f78-4730-8727-ad11cddf8869 --- # Compiler Error C3253 -'function' : error with explicit override +> 'function' : error with explicit override + +## Remarks An explicit override was specified incorrectly. For example, you cannot specify an implementation for an override that you also specify as pure. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3253: +## Example + +The following example generates C3253: ```cpp // C3253.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3254.md b/docs/error-messages/compiler-errors-2/compiler-error-c3254.md index 8d7f4685f95..564020dfafb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3254.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3254.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3254" title: "Compiler Error C3254" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3254" +ms.date: 11/04/2016 f1_keywords: ["C3254"] helpviewer_keywords: ["C3254"] -ms.assetid: 93427b10-fa72-4e43-80d1-1a6e122f9f40 --- # Compiler Error C3254 -'explicit override' : class contains explicit override 'override' but does not derive from an interface that contains the function declaration +> 'explicit override' : class contains explicit override 'override' but does not derive from an interface that contains the function declaration + +## Remarks When you [explicitly override](../../cpp/explicit-overrides-cpp.md) a method, the class that contains the override must derive, directly or indirectly, from the type that contains the function you are overriding. -The following sample generates C3254: +## Example + +The following example generates C3254: ```cpp // C3254.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3255.md b/docs/error-messages/compiler-errors-2/compiler-error-c3255.md index 5e2b71a8530..85780e5caf6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3255.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3255.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3255" title: "Compiler Error C3255" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3255" +ms.date: 11/04/2016 f1_keywords: ["C3255"] helpviewer_keywords: ["C3255"] -ms.assetid: 877ffca2-fd92-44b6-9060-6091b928b1c1 --- # Compiler Error C3255 -'value type' : cannot dynamically allocate this value type object on native heap +> 'value type' : cannot dynamically allocate this value type object on native heap + +## Remarks Instances of a value type (see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md)) that contain managed members can be created on the stack but not on the heap. -The following sample generates C3255: +## Example + +The following example generates C3255: ```cpp // C3255.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3262.md b/docs/error-messages/compiler-errors-2/compiler-error-c3262.md index aeff907ea7f..a03b9b56756 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3262.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3262.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3262" title: "Compiler Error C3262" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3262" +ms.date: 11/04/2016 f1_keywords: ["C3262"] helpviewer_keywords: ["C3262"] -ms.assetid: 3e74b9aa-de3c-4492-9331-ee73012b958b --- # Compiler Error C3262 -invalid array indexing: '#' dimension(s) specified for '#'-dimensional 'array type' +> invalid array indexing: '#' dimension(s) specified for '#'-dimensional 'array type' + +## Remarks An array was improperly subscripted. The number of indices may not match the number of dimensions in the array. -The following sample generates C3262: +## Example + +The following example generates C3262: ```cpp // C3262.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3264.md b/docs/error-messages/compiler-errors-2/compiler-error-c3264.md index 2f620f59858..67246af20c0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3264.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3264.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3264" title: "Compiler Error C3264" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3264" +ms.date: 11/04/2016 f1_keywords: ["C3264"] helpviewer_keywords: ["C3264"] -ms.assetid: 94ece687-2364-4f7a-8ebb-7afd3ae9d63d --- # Compiler Error C3264 -'class' : a class-constructor cannot have a return type +> 'class' : a class-constructor cannot have a return type + +## Remarks Class constructors cannot have return types. -The following sample generates C3264: +## Example + +The following example generates C3264: ```cpp // C3264_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3265.md b/docs/error-messages/compiler-errors-2/compiler-error-c3265.md index c1b01d64d2f..0a42b012bb7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3265.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3265.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3265" title: "Compiler Error C3265" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3265" +ms.date: 11/04/2016 f1_keywords: ["C3265"] helpviewer_keywords: ["C3265"] -ms.assetid: 10ab3e17-4a9f-4120-bab5-21473869b70f --- # Compiler Error C3265 -cannot declare a managed 'managed construct' in an unmanaged 'unmanaged construct' +> cannot declare a managed 'managed construct' in an unmanaged 'unmanaged construct' + +## Remarks You cannot include a managed object in an unmanaged context. -The following sample reproduces C3265: +## Example + +The following example reproduces C3265: ```cpp // C3265_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3266.md b/docs/error-messages/compiler-errors-2/compiler-error-c3266.md index 80ca7c50aaa..74c180fce42 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3266.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3266.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3266" title: "Compiler Error C3266" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3266" +ms.date: 11/04/2016 f1_keywords: ["C3266"] helpviewer_keywords: ["C3266"] -ms.assetid: 7375c099-acb7-42f6-898d-57cfefa010b8 --- # Compiler Error C3266 -'class' : a class-constructor must have a 'void' parameter list +> 'class' : a class-constructor must have a 'void' parameter list + +## Remarks Class-constructors in a class using /clr programming cannot take parameters. -The following sample generates C3266: +## Example + +The following example generates C3266: ```cpp // C3266.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3268.md b/docs/error-messages/compiler-errors-2/compiler-error-c3268.md index f58d77ec0de..48c86a4db5a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3268.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3268.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3268" title: "Compiler Error C3268" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3268" +ms.date: 11/04/2016 f1_keywords: ["C3268"] helpviewer_keywords: ["C3268"] -ms.assetid: d74a630c-daea-4e29-9759-83efef7fb184 --- # Compiler Error C3268 @@ -18,7 +17,7 @@ See [Generics](../../extensions/generics-cpp-component-extensions.md) for more i ## Example -The following sample generates C3268. +The following example generates C3268. ```cpp // C3268.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3269.md b/docs/error-messages/compiler-errors-2/compiler-error-c3269.md index 30e3769f27f..dda026a75a8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3269.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3269.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3269" title: "Compiler Error C3269" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3269" +ms.date: 11/04/2016 f1_keywords: ["C3269"] helpviewer_keywords: ["C3269"] -ms.assetid: c575f067-244d-4dd5-bf58-9e7630ea58b7 --- # Compiler Error C3269 -'function' : a member-function of a managed or WinRTtype cannot be declared with '...' +> 'function' : a member-function of a managed or WinRTtype cannot be declared with '...' + +## Remarks Managed and WinRT class member functions cannot declare variable-length parameter lists. -The following sample generates C3269 and shows how to fix it: +## Example + +The following example generates C3269 and shows how to fix it: ```cpp // C3269_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3270.md b/docs/error-messages/compiler-errors-2/compiler-error-c3270.md index 1fbce5730df..67d801e0485 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3270.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3270.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3270" title: "Compiler Error C3270" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3270" +ms.date: 11/04/2016 f1_keywords: ["C3270"] helpviewer_keywords: ["C3270"] -ms.assetid: 70e6e76b-7415-48f5-a61e-2ed50caf08e4 --- # Compiler Error C3270 -'field': the FieldOffset attribute can only be used in the context of StructLayout(Explicit), in which case it is required +> 'field': the FieldOffset attribute can only be used in the context of StructLayout(Explicit), in which case it is required + +## Remarks A field was marked with **FieldOffset**, which is only allowed when **StructLayout(Explicit)** is in effect. -The following sample generates C3270: +## Example + +The following example generates C3270: ```cpp // C3270_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3271.md b/docs/error-messages/compiler-errors-2/compiler-error-c3271.md index 13e5aa3832a..d40c824e597 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3271.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3271.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3271" title: "Compiler Error C3271" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3271" +ms.date: 11/04/2016 f1_keywords: ["C3271"] helpviewer_keywords: ["C3271"] -ms.assetid: 16d8bd1d-2e30-4c6a-a07f-0c4f3342fab5 --- # Compiler Error C3271 -'member': invalid value 'value' for the FieldOffset attribute +> 'member': invalid value 'value' for the FieldOffset attribute + +## Remarks A negative number was passed to the **FieldOffset** attribute. -The following sample generates C3271: +## Example + +The following example generates C3271: ```cpp // C3271.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3272.md b/docs/error-messages/compiler-errors-2/compiler-error-c3272.md index 6431d6dcf5b..6cdc82dc549 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3272.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3272.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3272" title: "Compiler Error C3272" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3272" +ms.date: 11/04/2016 f1_keywords: ["C3272"] helpviewer_keywords: ["C3272"] -ms.assetid: 7cdf254d-f207-4116-a1bf-7386f3b82a6f --- # Compiler Error C3272 -'symbol' : symbol requires FieldOffset, as it is a member of type typename defined with StructLayout(LayoutKind::Explicit) +> 'symbol' : symbol requires FieldOffset, as it is a member of type typename defined with StructLayout(LayoutKind::Explicit) + +## Remarks When `StructLayout(LayoutKind::Explicit)` is in effect, fields must be marked with `FieldOffset`. -The following sample generates C3272: +## Example + +The following example generates C3272: ```cpp // C3272_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3273.md b/docs/error-messages/compiler-errors-2/compiler-error-c3273.md index c1d5a9f6802..c19397dfa91 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3273.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3273.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Compiler Error C3273" title: "Compiler Error C3273" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3273" +ms.date: 11/04/2016 f1_keywords: ["C3273"] helpviewer_keywords: ["C3273"] -ms.assetid: 1d2ce9d9-222b-4cab-94e2-d2c1a9f5ebe0 --- # Compiler Error C3273 -__finally cannot be used on an exception block in unmanaged code. +> __finally cannot be used on an exception block in unmanaged code. + +## Example -The following sample generates C3273: +The following example generates C3273: ```cpp // C3273.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3274.md b/docs/error-messages/compiler-errors-2/compiler-error-c3274.md index b3732ce47ae..59a9dfa237a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3274.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3274.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3274" title: "Compiler Error C3274" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3274" +ms.date: 11/04/2016 f1_keywords: ["C3274"] helpviewer_keywords: ["C3274"] -ms.assetid: 1f03f18e-b569-48eb-9249-11c70122a305 --- # Compiler Error C3274 -__finally/finally without matching try +> __finally/finally without matching try + +## Remarks A [__finally](../../cpp/try-finally-statement.md) or [finally](../../dotnet/finally.md) statement was found without a matching **`try`**. To resolve this, either delete the **`__finally`** statement or add a **`try`** statement for the **`__finally`**. -The following sample generates C3274: +## Example + +The following example generates C3274: ```cpp // C3274.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3275.md b/docs/error-messages/compiler-errors-2/compiler-error-c3275.md index ec6d61c49ef..8164db7e728 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3275.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3275.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3275" title: "Compiler Error C3275" +description: "Learn more about: Compiler Error C3275" ms.date: 06/01/2022 f1_keywords: ["C3275"] helpviewer_keywords: ["C3275"] -ms.assetid: 5752680f-7d3e-4c42-ba9c-845e09d32e7a --- # Compiler Error C3275 > 'enum member' : cannot use this symbol without qualifier +## Remarks + When using managed code and when two or more enumerations contain an identifier with the same name, you must explicitly qualify references to the identifier. C3275 is only reachable using the obsolete compiler option **`/clr:oldSyntax`**. It's not generated in Visual Studio 2022 or later versions. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3276.md b/docs/error-messages/compiler-errors-2/compiler-error-c3276.md index 7734a6efa52..2acd2f43475 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3276.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3276.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3276" title: "Compiler Error C3276" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3276" +ms.date: 11/04/2016 f1_keywords: ["C3276"] helpviewer_keywords: ["C3276"] -ms.assetid: dd6b4fd2-094d-4d34-a467-a9afd59789f7 --- # Compiler Error C3276 -'keyword' : jump out of __finally/finally block has undefined behavior during termination handling +> 'keyword' : jump out of __finally/finally block has undefined behavior during termination handling + +## Remarks This error is the same as the [C4532](../../error-messages/compiler-warnings/compiler-warning-level-1-c4532.md) warning. However, when you are using /clr, this condition cannot be disabled with the [warning](../../preprocessor/warning.md) pragma. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3277.md b/docs/error-messages/compiler-errors-2/compiler-error-c3277.md index 5dda1f60f5e..99686122c80 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3277.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3277.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3277" title: "Compiler Error C3277" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3277" +ms.date: 11/04/2016 f1_keywords: ["C3277"] helpviewer_keywords: ["C3277"] -ms.assetid: 8ac5f476-e30c-4879-92c6-f03cdbd74045 --- # Compiler Error C3277 -cannot define an unmanaged enum 'enum' inside managed 'type' +> cannot define an unmanaged enum 'enum' inside managed 'type' + +## Remarks An enumeration was defined incorrectly inside a managed type. -The following sample generates C3277: +## Example + +The following example generates C3277: ```cpp // C3277a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3278.md b/docs/error-messages/compiler-errors-2/compiler-error-c3278.md index 633bd972416..4fa4676b8f1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3278.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3278.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3278" title: "Compiler Error C3278" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3278" +ms.date: 11/04/2016 f1_keywords: ["C3278"] helpviewer_keywords: ["C3278"] -ms.assetid: 56f818f5-85a6-4792-843b-54fe16327658 --- # Compiler Error C3278 @@ -16,7 +15,7 @@ A call was made to an interface method or a pure method, which is not allowed. ## Example -The following sample generates C3278: +The following example generates C3278: ```cpp // C3278_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3279.md b/docs/error-messages/compiler-errors-2/compiler-error-c3279.md index ed97e7991d8..2c8c603fabc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3279.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3279.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3279" title: "Compiler Error C3279" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3279" +ms.date: 11/04/2016 f1_keywords: ["C3279"] helpviewer_keywords: ["C3279"] -ms.assetid: 639afc20-984c-4a95-be35-8bf9409f02d5 --- # Compiler Error C3279 -partial and explicit specializations as well as explicit instantiations of class templates declared in the cli namespace are disallowed +> partial and explicit specializations as well as explicit instantiations of class templates declared in the cli namespace are disallowed + +## Remarks The `cli` namespace is defined by Microsoft and contains pseudo-templates. The Microsoft C++ compiler does not allow user-defined, partial and explicit specializations, and explicit instantiations of class templates in this namespace. -The following sample generates C3279: +## Example + +The following example generates C3279: ```cpp // C3279.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3280.md b/docs/error-messages/compiler-errors-2/compiler-error-c3280.md index c4d98cceae1..f0e23ff5668 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3280.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3280.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3280" title: "Compiler Error C3280" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3280" +ms.date: 11/04/2016 f1_keywords: ["C3280"] helpviewer_keywords: ["C3280"] -ms.assetid: 86dc5bbc-8818-4786-a728-9334268d308b --- # Compiler Error C3280 -'class' : a member-function of a managed type cannot be compiled as an unmanaged function +> 'class' : a member-function of a managed type cannot be compiled as an unmanaged function + +## Remarks Managed class member functions cannot be compiled as unmanaged functions. -The following sample generates C3280: +## Example + +The following example generates C3280: ```cpp // C3280_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3282.md b/docs/error-messages/compiler-errors-2/compiler-error-c3282.md index f424b4ccf18..741de4d6c9f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3282.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3282.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3282" title: "Compiler Error C3282" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3282" +ms.date: 11/04/2016 f1_keywords: ["C3282"] helpviewer_keywords: ["C3282"] -ms.assetid: bac2ac89-c360-4c24-bb81-c20c62ece9ba --- # Compiler Error C3282 -generic parameter lists can only appear on managed or WinRTclasses, structs, or functions +> generic parameter lists can only appear on managed or WinRTclasses, structs, or functions + +## Remarks A generic parameter list was used incorrectly. For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The following sample generates C3282 and shows how to fix it. +The following example generates C3282 and shows how to fix it. ```cpp // C3282.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3283.md b/docs/error-messages/compiler-errors-2/compiler-error-c3283.md index a21e84993f8..bdd801d2ffd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3283.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3283.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3283" title: "Compiler Error C3283" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3283" +ms.date: 11/04/2016 f1_keywords: ["C3283"] helpviewer_keywords: ["C3283"] -ms.assetid: c51d912c-cde3-4928-904e-26734c8954ce --- # Compiler Error C3283 -'type' : an interface cannot have an instance constructor +> 'type' : an interface cannot have an instance constructor + +## Remarks A CLR [interface](../../extensions/interface-class-cpp-component-extensions.md) cannot have an instance constructor. A static constructor is allowed. -The following sample generates C3283: +## Example + +The following example generates C3283: ```cpp // C3283.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3284.md b/docs/error-messages/compiler-errors-2/compiler-error-c3284.md index c2e17582e38..20908966346 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3284.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3284.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3284" title: "Compiler Error C3284" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3284" +ms.date: 11/04/2016 f1_keywords: ["C3284"] helpviewer_keywords: ["C3284"] -ms.assetid: e582f316-e9db-4d27-9c70-fdfa737a9d5f --- # Compiler Error C3284 -the constraints for generic parameter 'parameter' of function 'function' must match the constraints for generic parameter 'parameter' of function 'function' +> the constraints for generic parameter 'parameter' of function 'function' must match the constraints for generic parameter 'parameter' of function 'function' + +## Remarks A virtual generic function must use the same constraints as a virtual function with the same name and set of arguments in the base class. -The following sample generates C3284: +## Example + +The following example generates C3284: ```cpp // C3284.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3285.md b/docs/error-messages/compiler-errors-2/compiler-error-c3285.md index 59d5d68b7b2..fdd60a3eda7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3285.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3285.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3285" title: "Compiler Error C3285" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3285" +ms.date: 11/04/2016 f1_keywords: ["C3285"] helpviewer_keywords: ["C3285"] -ms.assetid: 04e8f210-d67e-4810-b153-e1efe2986c8f --- # Compiler Error C3285 -for each statement cannot operate on variables of type 'type' +> for each statement cannot operate on variables of type 'type' + +## Remarks The `for each` statement repeats a group of embedded statements for each element in an array or an object collection. @@ -16,7 +17,7 @@ See [for each, in](../../dotnet/for-each-in.md) for more information. ## Example -The following sample generates C3285. +The following example generates C3285. ```cpp // C3285.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3286.md b/docs/error-messages/compiler-errors-2/compiler-error-c3286.md index 9efe53c1c97..7a93263d5ff 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3286.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3286.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3286" title: "Compiler Error C3286" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3286" +ms.date: 11/04/2016 f1_keywords: ["C3286"] helpviewer_keywords: ["C3286"] -ms.assetid: 554328c8-cf44-4f7d-a8d2-def74d28ecdd --- # Compiler Error C3286 > '*specifier*': an iteration variable cannot have any storage-class specifiers +## Remarks + A storage class can't be specified on an iteration variable. For more information, see [Storage classes (C++)](../../cpp/storage-classes-cpp.md) and [for each, in](../../dotnet/for-each-in.md). ## Example -The following sample generates C3286, and also shows correct usage. +The following example generates C3286, and also shows correct usage. ```cpp // C3286.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3287.md b/docs/error-messages/compiler-errors-2/compiler-error-c3287.md index 787b4508cff..f039ff49189 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3287.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3287.md @@ -4,7 +4,6 @@ description: "Describes Microsoft C++ compiler error C3287." ms.date: 09/25/2020 f1_keywords: ["C3287"] helpviewer_keywords: ["C3287"] -ms.assetid: c1fa73d2-2c82-4136-a7da-0e75e3b420ad --- # Compiler Error C3287 @@ -18,7 +17,7 @@ For more information, see [for each, in](../../dotnet/for-each-in.md). ## Example -The following sample generates C3287. +The following example generates C3287. ```cpp // C3287.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3288.md b/docs/error-messages/compiler-errors-2/compiler-error-c3288.md index 4f9b011915a..6597067eb90 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3288.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3288.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3288" title: "Compiler Error C3288" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3288" +ms.date: 11/04/2016 f1_keywords: ["C3288"] helpviewer_keywords: ["C3288"] -ms.assetid: ed08a540-9751-46e1-9cbe-c51d6a49ffab --- # Compiler Error C3288 -'type' : illegal dereference of a handle type +> 'type' : illegal dereference of a handle type + +## Remarks The compiler detected an illegal dereference of a handle type. You can dereference a handle type and assign it to a reference. For more information, see [Tracking Reference Operator](../../extensions/tracking-reference-operator-cpp-component-extensions.md). ## Example -The following sample generates C3288. +The following example generates C3288. ```cpp // C3288.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3289.md b/docs/error-messages/compiler-errors-2/compiler-error-c3289.md index 9aec61ca772..d4823e99655 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3289.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3289.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3289" title: "Compiler Error C3289" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3289" +ms.date: 11/04/2016 f1_keywords: ["C3289"] helpviewer_keywords: ["C3289"] -ms.assetid: 3c1c623b-7fcf-43ab-a89a-8722532a8d29 --- # Compiler Error C3289 -'property' : a trivial property cannot be indexed +> 'property' : a trivial property cannot be indexed + +## Remarks A property was declared incorrectly. Accessors must be defined for an indexed property. See [property](../../extensions/property-cpp-component-extensions.md) for more information. ## Example -The following sample generates C3289. +The following example generates C3289. ```cpp // C3289.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3290.md b/docs/error-messages/compiler-errors-2/compiler-error-c3290.md index 0c418160ac2..86166548898 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3290.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3290.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3290" title: "Compiler Error C3290" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3290" +ms.date: 11/04/2016 f1_keywords: ["C3290"] helpviewer_keywords: ["C3290"] -ms.assetid: 0baf684b-1143-4953-ac99-a2fa267d8017 --- # Compiler Error C3290 -'type' : a trivial property cannot have reference type +> 'type' : a trivial property cannot have reference type + +## Remarks A property was declared incorrectly. When you declare a trivial property, the compiler creates a variable that the property will update, and it is not possible to have a tracking reference variable in a class. @@ -16,7 +17,7 @@ See [property](../../extensions/property-cpp-component-extensions.md) and [Track ## Example -The following sample generates C3290. +The following example generates C3290. ```cpp // C3290.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3291.md b/docs/error-messages/compiler-errors-2/compiler-error-c3291.md index 7786861b99d..ae67efb8b3a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3291.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3291.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3291" title: "Compiler Error C3291" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3291" +ms.date: 11/04/2016 f1_keywords: ["C3291"] helpviewer_keywords: ["C3291"] -ms.assetid: ed2e9f89-8dbc-4387-bc26-cc955e840858 --- # Compiler Error C3291 -'default' : cannot be the name of a trivial property +> 'default' : cannot be the name of a trivial property + +## Remarks A trivial property cannot be named **`default`**. See [property](../../extensions/property-cpp-component-extensions.md) for more information. ## Example -The following sample generates C3291. +The following example generates C3291. ```cpp // C3291.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3292.md b/docs/error-messages/compiler-errors-2/compiler-error-c3292.md index 06b23f7f6fa..6951f30c688 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3292.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3292.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3292" title: "Compiler Error C3292" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3292" +ms.date: 11/04/2016 f1_keywords: ["C3292"] helpviewer_keywords: ["C3292"] -ms.assetid: ead485cc-5471-4e10-b361-300589ff5b70 --- # Compiler Error C3292 -the cli namespace cannot be reopened +> the cli namespace cannot be reopened + +## Remarks The cli namespace cannot be declared in your code. For more information, see [Platform, default, and cli Namespaces](../../extensions/platform-default-and-cli-namespaces-cpp-component-extensions.md). ## Example -The following sample generates C3292. +The following example generates C3292. ```cpp // C3292.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3293.md b/docs/error-messages/compiler-errors-2/compiler-error-c3293.md index 6ce9d649914..e62c1f37089 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3293.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3293.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3293" title: "Compiler Error C3293" -ms.date: "07/21/2017" +description: "Learn more about: Compiler Error C3293" +ms.date: 07/21/2017 f1_keywords: ["C3293"] helpviewer_keywords: ["C3293"] -ms.assetid: b772cf98-52e0-4e24-be23-1f5d87d999ac --- # Compiler Error C3293 -'accessor': use 'default' to access the default property (indexer) for class 'type' +> 'accessor': use 'default' to access the default property (indexer) for class 'type' + +## Remarks An indexed property was accessed incorrectly. See [How to: Use Properties in C++/CLI](../../dotnet/how-to-use-properties-in-cpp-cli.md) for more information. @@ -16,7 +17,7 @@ An indexed property was accessed incorrectly. See [How to: Use Properties in C+ ## Example -The following sample generates C3293 in Visual Studio 2015 and earlier. +The following example generates C3293 in Visual Studio 2015 and earlier. ```cpp // C3293.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3295.md b/docs/error-messages/compiler-errors-2/compiler-error-c3295.md index 422e2296b2b..262bb7979b0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3295.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3295.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: Compiler Error C3295" title: "Compiler Error C3295" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3295" +ms.date: 11/04/2016 f1_keywords: ["C3295"] helpviewer_keywords: ["C3295"] -ms.assetid: 83f0aa4d-0e0a-4905-9f66-fcf9991fc07a --- # Compiler Error C3295 '#pragma pragma' can only be used at global or namespace scope -Some pragmas cannot be used in a function. See [Pragma Directives and the __Pragma Keyword](../../preprocessor/pragma-directives-and-the-pragma-keyword.md) for more information. +Some pragmas cannot be used in a function. See [Pragma directives and the `__pragma` and `_Pragma` keywords](../../preprocessor/pragma-directives-and-the-pragma-keyword.md) for more information. ## Example diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3296.md b/docs/error-messages/compiler-errors-2/compiler-error-c3296.md index 46a10a2ae6e..cc62bb8e34a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3296.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3296.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3296" title: "Compiler Error C3296" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3296" +ms.date: 11/04/2016 f1_keywords: ["C3296"] helpviewer_keywords: ["C3296"] -ms.assetid: fc4c9dcd-16cf-4eee-a1ac-c43e7c29e443 --- # Compiler Error C3296 -'property' : a property with this name already exists +> 'property' : a property with this name already exists + +## Remarks The compiler encountered more than one property with the same name. Each property in a type must have a unique name. @@ -16,7 +17,7 @@ For more information, see [property](../../extensions/property-cpp-component-ext ## Example -The following sample generates C3296. +The following example generates C3296. ```cpp // C3296.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3297.md b/docs/error-messages/compiler-errors-2/compiler-error-c3297.md index 569007694b7..8a2ba2122a7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3297.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3297.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3297" title: "Compiler Error C3297" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3297" +ms.date: 11/04/2016 f1_keywords: ["C3297"] helpviewer_keywords: ["C3297"] -ms.assetid: 2a718b4c-6cdb-4418-92c0-fc3a259431c4 --- # Compiler Error C3297 -'constraint_2' : cannot use 'constraint_1' as a constraint because 'constraint_1' has the value constraint +> 'constraint_2' : cannot use 'constraint_1' as a constraint because 'constraint_1' has the value constraint + +## Remarks Value classes are sealed. If a constraint is a value class, another constraint can never derive from it. @@ -16,7 +17,7 @@ For more information, see [Constraints on Generic Type Parameters (C++/CLI)](../ ## Example -The following sample generates C3297. +The following example generates C3297. ```cpp // C3297.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3298.md b/docs/error-messages/compiler-errors-2/compiler-error-c3298.md index 38cb9191d8c..5b6d1155d9c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3298.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3298.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3298" title: "Compiler Error C3298" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3298" +ms.date: 11/04/2016 f1_keywords: ["C3298"] helpviewer_keywords: ["C3298"] -ms.assetid: 458c2680-95bb-4d5e-895f-ce4115844193 --- # Compiler Error C3298 -'constraint_1' : cannot use 'constraint_2' as a constraint because 'constraint_2' has the ref constraint and 'constraint_1' has the value constraint +> 'constraint_1' : cannot use 'constraint_2' as a constraint because 'constraint_2' has the ref constraint and 'constraint_1' has the value constraint + +## Remarks You cannot specify mutually exclusive characteristics for a constraint. For example, a generic type parameter cannot be constrained to both a value type and a reference type. @@ -16,7 +17,7 @@ For more information, see [Constraints on Generic Type Parameters (C++/CLI)](../ ## Example -The following sample generates C3298. +The following example generates C3298. ```cpp // C3298.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3299.md b/docs/error-messages/compiler-errors-2/compiler-error-c3299.md index c9b8510b600..2ddb3da5245 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3299.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3299.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3299" title: "Compiler Error C3299" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3299" +ms.date: 11/04/2016 f1_keywords: ["C3299"] helpviewer_keywords: ["C3299"] -ms.assetid: 7cabdf01-bceb-404f-9401-cdd9c7fc1641 --- # Compiler Error C3299 -'member_function' : cannot specify constraints, they are inherited from the base method +> 'member_function' : cannot specify constraints, they are inherited from the base method + +## Remarks When overriding a generic member function, you cannot specify constraint clauses (repeating the constraints implies that the constraints are not inherited). @@ -18,7 +19,7 @@ For more information, see [Constraints on Generic Type Parameters (C++/CLI)](../ ## Example -The following sample generates C3299. +The following example generates C3299. ```cpp // C3299.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3303.md b/docs/error-messages/compiler-errors-2/compiler-error-c3303.md index 323f0832162..db42b47058e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3303.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3303.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3303" title: "Compiler Error C3303" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3303" +ms.date: 11/04/2016 f1_keywords: ["C3303"] helpviewer_keywords: ["C3303"] -ms.assetid: c6f6ea3d-f6b7-4401-8bbb-f283a2c05540 --- # Compiler Error C3303 -'attribute': attribute can only be used on 'usage' +> 'attribute': attribute can only be used on 'usage' + +## Remarks An attempt was made to use an attribute where it is not valid. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3309.md b/docs/error-messages/compiler-errors-2/compiler-error-c3309.md index 651e7c8c0f9..779f2c44544 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3309.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3309.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3309" title: "Compiler Error C3309" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3309" +ms.date: 11/04/2016 f1_keywords: ["C3309"] helpviewer_keywords: ["C3309"] -ms.assetid: 75ee16e3-7d4e-4c41-b3cb-64e9849c3aab --- # Compiler Error C3309 -'macro_name': module name cannot be a macro or a keyword +> 'macro_name': module name cannot be a macro or a keyword + +## Remarks The value that you pass to the name property of the module attribute cannot be a symbol for the preprocessor to expand; it must be a string literal. -The following sample generates C3309: +## Example + +The following example generates C3309: ```cpp // C3309.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3320.md b/docs/error-messages/compiler-errors-2/compiler-error-c3320.md index 50975948b9a..54472b937f7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3320.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3320.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3320" title: "Compiler Error C3320" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3320" +ms.date: 11/04/2016 f1_keywords: ["C3320"] helpviewer_keywords: ["C3320"] -ms.assetid: 2ef72d9a-1f1d-4b2e-b244-9fd3f3e70cb6 --- # Compiler Error C3320 -'type': type cannot have the same name as the module 'name' property +> 'type': type cannot have the same name as the module 'name' property + +## Remarks An exported user-defined type (UDT), which could be a struct, class, enum, or union, cannot have the same name as the parameter passed to the [module](../../windows/attributes/module-cpp.md) attribute's name property. ## Example -The following sample generates C3320: +The following example generates C3320: ```cpp // C3320.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3322.md b/docs/error-messages/compiler-errors-2/compiler-error-c3322.md index 374af497ee7..b8a614d504e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3322.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3322.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3322" title: "Compiler Error C3322" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3322" +ms.date: 11/04/2016 f1_keywords: ["C3322"] helpviewer_keywords: ["C3322"] -ms.assetid: d8a0ad95-30df-4337-b0c8-4747de0bef50 --- # Compiler Error C3322 -'property': is not a valid property for attribute 'attribute' +> 'property': is not a valid property for attribute 'attribute' + +## Remarks An invalid or unrecognized property (or parameter) was passed to an attribute. Check the documentation for the attribute. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3333.md b/docs/error-messages/compiler-errors-2/compiler-error-c3333.md index 731607d8c59..6279bcb307d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3333.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3333.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3333" title: "Compiler Error C3333" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3333" +ms.date: 11/04/2016 f1_keywords: ["C3333"] helpviewer_keywords: ["C3333"] -ms.assetid: 51693978-fba6-435a-a696-74735cc875de --- # Compiler Error C3333 -'type library': cannot #import corrupt type library +> 'type library': cannot #import corrupt type library + +## Remarks The type library specified in the `#import` statement is unreadable by the compiler. You may want to either regenerate the type library, if possible, or request a new type library from your supplier. You may want to use the OLE Viewer, supplied with Visual C++, to view the type library file to see what is the matter with it. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3334.md b/docs/error-messages/compiler-errors-2/compiler-error-c3334.md index 4710d310457..017856ba7c0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3334.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3334.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3334" title: "Compiler Error C3334" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3334" +ms.date: 11/04/2016 f1_keywords: ["C3334"] helpviewer_keywords: ["C3334"] -ms.assetid: e972c625-77e7-4022-8aba-e1db01d7a0d7 --- # Compiler Error C3334 -cannot #import corrupt type library +> cannot #import corrupt type library + +## Remarks The library file in a `#import` statement is corrupt and can't be consumed by the compiler. Corruption can come from bad generation of the module, disk corruption, or if the binary file was somehow edited and modified. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3340.md b/docs/error-messages/compiler-errors-2/compiler-error-c3340.md index 8eea083c5d9..0c76035b527 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3340.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3340.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3340" title: "Compiler Error C3340" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3340" +ms.date: 11/04/2016 f1_keywords: ["C3340"] helpviewer_keywords: ["C3340"] -ms.assetid: 23b12298-b92a-4717-8380-f165c998cb8a --- # Compiler Error C3340 -'interface': interface cannot be both 'restricted' and 'default' in coclass 'class' +> 'interface': interface cannot be both 'restricted' and 'default' in coclass 'class' + +## Remarks The [restricted](../../windows/attributes/restricted.md) attribute and the [default](../../windows/attributes/default-cpp.md) attribute are mutually exclusive. -The following sample generates C3340: +## Example + +The following example generates C3340: ```cpp // C3340.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3342.md b/docs/error-messages/compiler-errors-2/compiler-error-c3342.md index f14134d5da0..e4edbd8c142 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3342.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3342.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3342" title: "Compiler Error C3342" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3342" +ms.date: 11/04/2016 f1_keywords: ["C3342"] helpviewer_keywords: ["C3342"] -ms.assetid: 5c6d784f-bebe-4f7e-8615-44ca6f78bfba --- # Compiler Error C3342 -'attribute': ambiguous attribute +> 'attribute': ambiguous attribute + +## Remarks The compiler found more than one definition of an attribute. @@ -18,7 +19,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3342. +The following example generates C3342. ```cpp // C3342.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3345.md b/docs/error-messages/compiler-errors-2/compiler-error-c3345.md index 7cbcbd255c2..852653abaa3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3345.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3345.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3345" title: "Compiler Error C3345" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3345" +ms.date: 11/04/2016 f1_keywords: ["C3345"] helpviewer_keywords: ["C3345"] -ms.assetid: 1dda4c79-73bb-441b-b939-746154c3afba --- # Compiler Error C3345 -'identifier': invalid identifier for module name +> 'identifier': invalid identifier for module name + +## Remarks The *identifier* for a module contains one or more unacceptable characters. An identifier is valid if the first character is an alphabetical, underscore, or high ANSI (0x80-FF) character, and any subsequent character is an alphanumeric, underscore, or high ANSI character. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3347.md b/docs/error-messages/compiler-errors-2/compiler-error-c3347.md index 4fe6b20eb35..3433ff4fd12 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3347.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3347.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3347" title: "Compiler Error C3347" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3347" +ms.date: 11/04/2016 f1_keywords: ["C3347"] helpviewer_keywords: ["C3347"] -ms.assetid: e939ad29-0b78-4681-9618-9bdae5675cee --- # Compiler Error C3347 -'arg': required argument is not specified in attribute idl_module +> 'arg': required argument is not specified in attribute idl_module + +## Remarks A required argument was not passed to the [idl_module](../../windows/attributes/idl-module.md) attribute. -The following sample generates C3347: +## Example + +The following example generates C3347: ```cpp // C3347.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3350.md b/docs/error-messages/compiler-errors-2/compiler-error-c3350.md index 832d21b80ca..57907de24ac 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3350.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3350.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3350" title: "Compiler Error C3350" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3350" +ms.date: 11/04/2016 f1_keywords: ["C3350"] helpviewer_keywords: ["C3350"] -ms.assetid: cfbbc338-92b5-4f34-999e-aa2d2376bc70 --- # Compiler Error C3350 -'delegate' : a delegate constructor expects number argument(s) +> 'delegate' : a delegate constructor expects number argument(s) + +## Remarks When you create an instance of a delegate, you must pass two arguments, an instance of the type containing the delegate function, and the function. -The following sample generates C3350: +## Example + +The following example generates C3350: ```cpp // C3350.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3351.md b/docs/error-messages/compiler-errors-2/compiler-error-c3351.md index 3962af7b367..0734f32ab3f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3351.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3351.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3351" title: "Compiler Error C3351" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3351" +ms.date: 11/04/2016 f1_keywords: ["C3351"] helpviewer_keywords: ["C3351"] -ms.assetid: c021bbbe-1067-4f51-af4f-940d2b792eb5 --- # Compiler Error C3351 -'object' : delegate constructor: second argument must be address of a static member function or global function +> 'object' : delegate constructor: second argument must be address of a static member function or global function + +## Remarks The compiler expected the address of a function declared **`static`**. -The following sample generates C3351: +## Example + +The following example generates C3351: ```cpp // C3351a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3352.md b/docs/error-messages/compiler-errors-2/compiler-error-c3352.md index 60bf88d2fa8..1268b23389d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3352.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3352.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3352" title: "Compiler Error C3352" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3352" +ms.date: 11/04/2016 f1_keywords: ["C3352"] helpviewer_keywords: ["C3352"] -ms.assetid: f233bed7-474e-425f-aad2-7801578169d4 --- # Compiler Error C3352 -'function' : the specified function does not match the delegate type 'type' +> 'function' : the specified function does not match the delegate type 'type' + +## Remarks The parameter lists for `function` and the delegate do not match. For more information, see [delegate (C++ Component Extensions)](../../extensions/delegate-cpp-component-extensions.md). -The following sample generates C3352: +## Example + +The following example generates C3352: ```cpp // C3352.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3353.md b/docs/error-messages/compiler-errors-2/compiler-error-c3353.md index de559c94332..1499d4c19ef 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3353.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3353.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3353" title: "Compiler Error C3353" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3353" +ms.date: 11/04/2016 f1_keywords: ["C3353"] helpviewer_keywords: ["C3353"] -ms.assetid: 5699c04b-d504-46ce-bf71-c200318fed71 --- # Compiler Error C3353 -'delegate' : a delegate can only be created from a global function or a member function of a managed or WinRT type +> 'delegate' : a delegate can only be created from a global function or a member function of a managed or WinRT type + +## Remarks Delegates, declared with the [delegate](../../extensions/delegate-cpp-component-extensions.md) keyword, can only be declared at global scope. -The following sample generates C3353: +## Example + +The following example generates C3353: ```cpp // C3353.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3354.md b/docs/error-messages/compiler-errors-2/compiler-error-c3354.md index ba44cfdb382..a3f9b768b05 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3354.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3354.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3354" title: "Compiler Error C3354" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3354" +ms.date: 11/04/2016 f1_keywords: ["C3354"] helpviewer_keywords: ["C3354"] -ms.assetid: 185de401-231e-4999-a149-172ee4c69d84 --- # Compiler Error C3354 -'function' : the function used to create a delegate cannot have return type 'type' +> 'function' : the function used to create a delegate cannot have return type 'type' + +## Remarks The following types are invalid as return types for a **`delegate`**: @@ -22,7 +23,9 @@ The following types are invalid as return types for a **`delegate`**: - Reference to member function -The following sample generates C3354: +## Example + +The following example generates C3354: ```cpp // C3354_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3356.md b/docs/error-messages/compiler-errors-2/compiler-error-c3356.md index 507aa851102..d4ead99fde5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3356.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3356.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3356" title: "Compiler Error C3356" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3356" +ms.date: 11/04/2016 f1_keywords: ["C3356"] helpviewer_keywords: ["C3356"] -ms.assetid: 6c1094f6-ac85-480a-b78b-e92fcf38641a --- # Compiler Error C3356 -'attribute': cannot call a multicast attribute with a fully qualified name +> 'attribute': cannot call a multicast attribute with a fully qualified name + +## Remarks An attribute that is processed by more than one process, for example, the compiler and ATL provider, was specified incorrectly. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3358.md b/docs/error-messages/compiler-errors-2/compiler-error-c3358.md index 44e865694af..e433cbf1dce 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3358.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3358.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3358" title: "Compiler Error C3358" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3358" +ms.date: 11/04/2016 f1_keywords: ["C3358"] helpviewer_keywords: ["C3358"] -ms.assetid: 180b93df-e78f-441a-91fb-1594c681f7f0 --- # Compiler Error C3358 -'symbol': symbol not found +> 'symbol': symbol not found + +## Remarks The required symbol was not found. -The following sample generates C3358: +## Example + +The following example generates C3358: ```cpp // C3358.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3360.md b/docs/error-messages/compiler-errors-2/compiler-error-c3360.md index f8f06342a45..312db01e736 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3360.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3360.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3360" title: "Compiler Error C3360" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3360" +ms.date: 11/04/2016 f1_keywords: ["C3360"] helpviewer_keywords: ["C3360"] -ms.assetid: 6acf983a-dbb6-422b-b045-a34bb4ba6761 --- # Compiler Error C3360 -'string': cannot create name +> 'string': cannot create name + +## Remarks The value that was passed to the [uuid](../../windows/attributes/uuid-cpp-attributes.md) attribute was not valid. -The following sample generates C3360: +## Example + +The following example generates C3360: ```cpp // C3360.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3363.md b/docs/error-messages/compiler-errors-2/compiler-error-c3363.md index d224e476b45..11a8d33c1f1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3363.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3363.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3363" title: "Compiler Error C3363" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3363" +ms.date: 11/04/2016 f1_keywords: ["C3363"] helpviewer_keywords: ["C3363"] -ms.assetid: 41aa922f-608e-4f7a-ba66-451fc1161935 --- # Compiler Error C3363 -'type' : 'typeid' can only be applied to a type +> 'type' : 'typeid' can only be applied to a type + +## Remarks The [typeid](../../extensions/typeid-cpp-component-extensions.md) operator was used incorrectly. ## Example -The following sample generates C3363. +The following example generates C3363. ```cpp // C3363.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3364.md b/docs/error-messages/compiler-errors-2/compiler-error-c3364.md index 252a5951662..97e7ec74e88 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3364.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3364.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3364" title: "Compiler Error C3364" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3364" +ms.date: 11/04/2016 f1_keywords: ["C3364"] helpviewer_keywords: ["C3364"] -ms.assetid: 98654741-60fe-4472-a6af-e580f8c0a6e1 --- # Compiler Error C3364 -'delegate': delegate constructor: argument must be pointer to member function of managed class or global function +> 'delegate': delegate constructor: argument must be pointer to member function of managed class or global function + +## Remarks The second parameter of the delegate's constructor takes either the address of a member function or the address of a static member function of any class. Both are treated as simple addresses. -The following sample generates C3364: +## Example + +The following example generates C3364: ```cpp // C3364_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3365.md b/docs/error-messages/compiler-errors-2/compiler-error-c3365.md index 2966274d70a..4d6ea4ed4f7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3365.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3365.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3365" title: "Compiler Error C3365" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3365" +ms.date: 11/04/2016 f1_keywords: ["C3365"] helpviewer_keywords: ["C3365"] -ms.assetid: 875ec3a4-522c-4e3d-9b67-48808b857f6d --- # Compiler Error C3365 -operator 'operator' : differing operands of type 'type1' and 'type2' +> operator 'operator' : differing operands of type 'type1' and 'type2' + +## Remarks An attempt was made to compose delegates with different types. See [How to: Define and Use Delegates (C++/CLI)](../../dotnet/how-to-define-and-use-delegates-cpp-cli.md) for more information about delegates. ## Example -The following sample generates C3365: +The following example generates C3365: ```cpp // C3365.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3366.md b/docs/error-messages/compiler-errors-2/compiler-error-c3366.md index e29cedffa30..084e2ae3240 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3366.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3366.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Error C3366" title: "Compiler Error C3366" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3366" +ms.date: 11/04/2016 f1_keywords: ["C3366"] helpviewer_keywords: ["C3366"] -ms.assetid: efc55bcf-c16d-43c1-a36f-87a6165fa2a8 --- # Compiler Error C3366 -'variable' : static data members of managed or WinRTtypes must be defined within the class definition +> 'variable' : static data members of managed or WinRTtypes must be defined within the class definition + +## Remarks You attempted to reference a static member of a WinRT or .NET class or interface outside the definition of that class or interface. The compiler needs to know the full definition of the class (to emit the meta-data after one pass) and requires static data members to be initialized within the class. +## Example + For example, the following example generates C3366 and shows how to fix it: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3367.md b/docs/error-messages/compiler-errors-2/compiler-error-c3367.md index c7b9e199930..906b2d970b5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3367.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3367.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3367" title: "Compiler Error C3367" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3367" +ms.date: 11/04/2016 f1_keywords: ["C3367"] helpviewer_keywords: ["C3367"] -ms.assetid: e675d42b-f5b0-4d43-aab1-1f5024233102 --- # Compiler Error C3367 -'static_member_function' : cannot use static function to create an unbound delegate +> 'static_member_function' : cannot use static function to create an unbound delegate + +## Remarks When you call an unbound delegate, you must pass an instance of an object. Since a static member function is called through the class name, you can only instantiate an unbound delegate with an instance member function. @@ -16,7 +17,7 @@ For more information about unbound delegates, see [How to: Define and Use Delega ## Example -The following sample generates C3367. +The following example generates C3367. ```cpp // C3367.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3368.md b/docs/error-messages/compiler-errors-2/compiler-error-c3368.md index 56c588043ec..8b719026039 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3368.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3368.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3368" title: "Compiler Error C3368" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3368" +ms.date: 11/04/2016 f1_keywords: ["C3368"] helpviewer_keywords: ["C3368"] -ms.assetid: 5bfd5be4-dfa9-4b33-9612-010561b40955 --- # Compiler Error C3368 -'function declaration' : invalid calling convention for IDL +> 'function declaration' : invalid calling convention for IDL + +## Remarks You can only use the [__stdcall](../../cpp/stdcall.md) or [__cdecl](../../cpp/cdecl.md) calling conventions in an .idl file. -The following sample generates C3368: +## Example + +The following example generates C3368: ```cpp // C3368.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3369.md b/docs/error-messages/compiler-errors-2/compiler-error-c3369.md index 55cbcf23004..fd633c461d1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3369.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3369.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3369" title: "Compiler Error C3369" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3369" +ms.date: 11/04/2016 f1_keywords: ["C3369"] helpviewer_keywords: ["C3369"] -ms.assetid: c6ceb9cb-3df9-4334-9a5c-d16db351d476 --- # Compiler Error C3369 -'module name': idl_module already defined +> 'module name': idl_module already defined + +## Remarks The [idl_module](../../windows/attributes/idl-module.md) usage where you define the DLL can only occur once in a program. -The following sample generates C3369: +## Example + +The following example generates C3369: ```cpp // C3369.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3370.md b/docs/error-messages/compiler-errors-2/compiler-error-c3370.md index 519ed9ab92b..c6771ad1148 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3370.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3370.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3370" title: "Compiler Error C3370" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3370" +ms.date: 11/04/2016 f1_keywords: ["C3370"] helpviewer_keywords: ["C3370"] -ms.assetid: ee6d4c85-78fc-42b2-836e-5cc491a3b2ba --- # Compiler Error C3370 -'idl_module name': idl_module not yet defined +> 'idl_module name': idl_module not yet defined + +## Remarks Before you can use [idl_module](../../windows/attributes/idl-module.md) to specify an entry point in a DLL, you must first use `idl_module` to specify the DLL name. -The following sample generates C3370: +## Example + +The following example generates C3370: ```cpp // C3370.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3371.md b/docs/error-messages/compiler-errors-2/compiler-error-c3371.md index 3eed2c81fba..d6003778a7f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3371.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3371.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3371" title: "Compiler Error C3371" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3371" +ms.date: 11/04/2016 f1_keywords: ["C3371"] helpviewer_keywords: ["C3371"] -ms.assetid: f7ecf1aa-ed0a-4f73-81e5-62cf98f88ea1 --- # Compiler Error C3371 -'idl_module': only the 'name' property is allowed here +> 'idl_module': only the 'name' property is allowed here + +## Remarks [idl_module](../../windows/attributes/idl-module.md) usage directly on a function declaration cannot have any parameters other than name. -The following sample generates C3371: +## Example + +The following example generates C3371: ```cpp // C3371.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3372.md b/docs/error-messages/compiler-errors-2/compiler-error-c3372.md index 52307011d61..91cb56aa842 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3372.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3372.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3372" title: "Compiler Error C3372" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3372" +ms.date: 11/04/2016 f1_keywords: ["C3372"] helpviewer_keywords: ["C3372"] -ms.assetid: 38ee39ed-03ff-4e6d-9104-f1977b96645d --- # Compiler Error C3372 -must specify at least 1 interface for attribute 'source' on a coclass +> must specify at least 1 interface for attribute 'source' on a coclass + +## Remarks For certain attributes, you must pass an interface name as a parameter. -The following sample generates C3372: +## Example + +The following example generates C3372: ```cpp // C3372.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3373.md b/docs/error-messages/compiler-errors-2/compiler-error-c3373.md index 373f91ea803..5df76fc80d5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3373.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3373.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3373" title: "Compiler Error C3373" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3373" +ms.date: 11/04/2016 f1_keywords: ["C3373"] helpviewer_keywords: ["C3373"] -ms.assetid: 6e7586c3-1a15-4773-ad20-f90090a400dc --- # Compiler Error C3373 -attribute 'attribute' takes no arguments except on a coclass +> attribute 'attribute' takes no arguments except on a coclass + +## Remarks Some attributes can be applied to more than one C++ construct, but arguments to the attribute may only be allowed on some constructs. -The following sample generates C3373: +## Example + +The following example generates C3373: ```cpp // C3373.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3374.md b/docs/error-messages/compiler-errors-2/compiler-error-c3374.md index 5b1012f661c..3256f943241 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3374.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3374.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3374" title: "Compiler Error C3374" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3374" +ms.date: 11/04/2016 f1_keywords: ["C3374"] helpviewer_keywords: ["C3374"] -ms.assetid: 41431299-bd20-47d4-a0c8-1334dd79018b --- # Compiler Error C3374 -can't take address of 'function' unless creating delegate instance +> can't take address of 'function' unless creating delegate instance + +## Remarks The address of a function was taken in a context other than the creation of a delegate instance. -The following sample generates C3374: +## Example + +The following example generates C3374: ```cpp // C3374.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3375.md b/docs/error-messages/compiler-errors-2/compiler-error-c3375.md index 5e7405e0170..41c91468995 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3375.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3375.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3375" title: "Compiler Error C3375" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3375" +ms.date: 11/04/2016 f1_keywords: ["C3375"] helpviewer_keywords: ["C3375"] -ms.assetid: f1df78c6-e6ca-48f3-8b29-4e1710002bf3 --- # Compiler Error C3375 -'function' : ambiguous delegate function +> 'function' : ambiguous delegate function + +## Remarks A delegate instantiation could have been to a static member function, or as an unbound delegate to an instance function, so the compiler issued this error. @@ -16,7 +17,7 @@ For more information, see [delegate (C++ Component Extensions)](../../extension ## Example -The following sample generates C3375. +The following example generates C3375. ```cpp // C3375.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3379.md b/docs/error-messages/compiler-errors-2/compiler-error-c3379.md index baacee8b4ed..3d953bb8c7d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3379.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3379.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3379" title: "Compiler Error C3379" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3379" +ms.date: 11/04/2016 f1_keywords: ["C3379"] helpviewer_keywords: ["C3379"] -ms.assetid: a66c2c4e-091c-4426-9cde-7c4cfb2ffce1 --- # Compiler Error C3379 -'class' : a nested class cannot have an assembly access specifier as part of its declaration +> 'class' : a nested class cannot have an assembly access specifier as part of its declaration + +## Remarks When applied to a managed type, such as class or struct, the [public](../../cpp/public-cpp.md) and [private](../../cpp/private-cpp.md) keywords indicate whether the class will be exposed through assembly metadata. `public` or `private` cannot be applied to a nested class, which will inherit the assembly access of the enclosing class. When used with [/clr](../../build/reference/clr-common-language-runtime-compilation.md), the `ref` and `value` keywords indicate that a class is managed (see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md)). -The following sample generates C3379: +## Example + +The following example generates C3379: ```cpp // C3379a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3380.md b/docs/error-messages/compiler-errors-2/compiler-error-c3380.md index a150009936f..124b958b0d2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3380.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3380.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3380" title: "Compiler Error C3380" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3380" +ms.date: 11/04/2016 f1_keywords: ["C3380"] helpviewer_keywords: ["C3380"] -ms.assetid: 86f1f4ec-4ad8-4a1a-9b6c-2d9b6129df6b --- # Compiler Error C3380 -'class' : invalid assembly access specifier - only 'public' or 'private' are allowed +> 'class' : invalid assembly access specifier - only 'public' or 'private' are allowed + +## Remarks When applied to a managed class or struct, the [public](../../cpp/public-cpp.md) and [private](../../cpp/private-cpp.md) keywords indicate whether the class will be exposed through assembly metadata. Only `public` or `private` can be applied to a class in a program compiled with [/clr](../../build/reference/clr-common-language-runtime-compilation.md). The `ref` and `value` keywords, when used with [/clr](../../build/reference/clr-common-language-runtime-compilation.md), indicate that a class is managed (see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md)). -The following sample generates C3380: +## Example + +The following example generates C3380: ```cpp // C3380_2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3381.md b/docs/error-messages/compiler-errors-2/compiler-error-c3381.md index 36a5ded5ce2..913b50fe2cd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3381.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3381.md @@ -4,23 +4,22 @@ description: "Microsoft C++ compiler error C3381, its causes and how to resolve ms.date: 09/28/2020 f1_keywords: ["C3381"] helpviewer_keywords: ["C3381"] -ms.assetid: d276c89f-8377-4cb6-a8d4-7770885f06c4 --- # Compiler Error C3381 > '*identifier*' : assembly access specifiers are only available in code compiled with a /clr option -A type was declared or defined by using an access specifier, which is only permitted in code compiled by using **`/clr`**. - ## Remarks +A type was declared or defined by using an access specifier, which is only permitted in code compiled by using **`/clr`**. + This error may result from a misplaced **`public`**, **`protected`**, or **`private`** keyword, or a missing colon (**`:`**) after an access specifier within a **`class`** or **`struct`**. In C++/CLI, native types can be visible outside an assembly, but you can only specify assembly access for native types in a **`/clr`** compilation. For more information, see [Type visibility](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Type_visibility) and [`/clr` (Common Language Runtime Compilation)](../../build/reference/clr-common-language-runtime-compilation.md). ## Example -The following sample generates C3381. To fix it, first either remove the **`public`** specifier from the `class A` definition, or compile by using the **`/clr`** option. Next, add a colon after **`private`** to specify access for `class B {} b;`. That's because a nested class can't have an assembly access specifier as part of its declaration. +The following example generates C3381. To fix it, first either remove the **`public`** specifier from the `class A` definition, or compile by using the **`/clr`** option. Next, add a colon after **`private`** to specify access for `class B {} b;`. That's because a nested class can't have an assembly access specifier as part of its declaration. ```cpp // C3381.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3382.md b/docs/error-messages/compiler-errors-2/compiler-error-c3382.md index e66b793fc50..1314e1265cd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3382.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3382.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3382" title: "Compiler Error C3382" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3382" +ms.date: 11/04/2016 f1_keywords: ["C3382"] helpviewer_keywords: ["C3382"] -ms.assetid: a7603abd-ac4e-4ae6-a02b-3bdc6d1908a6 --- # Compiler Error C3382 -'sizeof' is not supported with /clr:safe +> 'sizeof' is not supported with /clr:safe + +## Remarks The output file of a **/clr:safe** compilation is a file that is verifiably type safe, and sizeof is not supported because the return value of the sizeof operator is size_t, whose size varies depending on the operating system. @@ -22,7 +23,7 @@ For more information, see, ## Example -The following sample generates C3382. +The following example generates C3382. ```cpp // C3382.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3383.md b/docs/error-messages/compiler-errors-2/compiler-error-c3383.md index 2c45ba4d14d..1a7f753626c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3383.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3383.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3383" title: "Compiler Error C3383" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3383" +ms.date: 11/04/2016 f1_keywords: ["C3383"] helpviewer_keywords: ["C3383"] -ms.assetid: ceb7f725-f417-4dc3-8496-0f413bb76687 --- # Compiler Error C3383 -'operator new' is not supported with /clr:safe +> 'operator new' is not supported with /clr:safe + +## Remarks The output file of a **/clr:safe** compilation is a file that is verifiably type safe, and pointers are not supported. @@ -20,7 +21,7 @@ For more information, see, ## Example -The following sample generates C3383. +The following example generates C3383. ```cpp // C3383.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3384.md b/docs/error-messages/compiler-errors-2/compiler-error-c3384.md index 29c4ae7a09f..b9652439d74 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3384.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3384.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3384" title: "Compiler Error C3384" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3384" +ms.date: 11/04/2016 f1_keywords: ["C3384"] helpviewer_keywords: ["C3384"] -ms.assetid: c9f92c6a-62a9-4333-b2b1-bc55c7f288b6 --- # Compiler Error C3384 -'type_parameter' : the value constraint and the ref constraint are mutually exclusive +> 'type_parameter' : the value constraint and the ref constraint are mutually exclusive + +## Remarks You cannot constrain a generic type to both **`value class`** and **`ref class`**. @@ -16,7 +17,7 @@ See [Constraints on Generic Type Parameters (C++/CLI)](../../extensions/constrai ## Example -The following sample generates C3384. +The following example generates C3384. ```cpp // C3384.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3385.md b/docs/error-messages/compiler-errors-2/compiler-error-c3385.md index 84eb77cee46..4bdd233dd9a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3385.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3385.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3385" title: "Compiler Error C3385" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3385" +ms.date: 11/04/2016 f1_keywords: ["C3385"] helpviewer_keywords: ["C3385"] -ms.assetid: 5f1838c1-986e-47db-8dbc-e06976b83cf3 --- # Compiler Error C3385 -'class::function' : a function that has a DllImport Custom attribute cannot return an instance of a class +> 'class::function' : a function that has a DllImport Custom attribute cannot return an instance of a class + +## Remarks A function defined as being in a .dll file specified with the `DllImport` attribute cannot return an instance of a class. -The following sample generates C3385: +## Example + +The following example generates C3385: ```cpp // C3385.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3386.md b/docs/error-messages/compiler-errors-2/compiler-error-c3386.md index 0c91775a21d..b6e8bef3bad 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3386.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3386.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3386" title: "Compiler Error C3386" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3386" +ms.date: 11/04/2016 f1_keywords: ["C3386"] helpviewer_keywords: ["C3386"] -ms.assetid: 93fa8c33-0f10-402b-8eec-b0a217a1f8dc --- # Compiler Error C3386 > '*type-name*' : `__declspec(dllexport)`/`__declspec(dllimport)` cannot be applied to a managed or WinRT type +## Remarks + The [`dllimport`](../../cpp/dllexport-dllimport.md) and [`dllexport`](../../cpp/dllexport-dllimport.md) **`__declspec`** modifiers aren't valid on a managed or Windows Runtime type. -The following sample generates C3386 and shows how to fix it: +## Example + +The following example generates C3386 and shows how to fix it: ```cpp // C3386.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3387.md b/docs/error-messages/compiler-errors-2/compiler-error-c3387.md index e4ebc2bbf6b..1aa8d110eef 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3387.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3387.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3387" title: "Compiler Error C3387" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3387" +ms.date: 11/04/2016 f1_keywords: ["C3387"] helpviewer_keywords: ["C3387"] -ms.assetid: c54d9925-ed14-4976-b8db-e8d4dc84e536 --- # Compiler Error C3387 -'member' : __declspec(dllexport)/\__declspec(dllimport) cannot be applied to a member of a managed or WinRT type +> 'member' : __declspec(dllexport)/\__declspec(dllimport) cannot be applied to a member of a managed or WinRT type + +## Remarks The `dllimport` and [dllexport](../../cpp/dllexport-dllimport.md) **`__declspec`** modifiers are not valid on members of a managed or Windows Runtime type. -The following sample generates C3387 and shows how to fix it: +## Example + +The following example generates C3387 and shows how to fix it: ```cpp // C3387a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3388.md b/docs/error-messages/compiler-errors-2/compiler-error-c3388.md index 570db2843a3..1b69e8c4669 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3388.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3388.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3388" title: "Compiler Error C3388" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3388" +ms.date: 11/04/2016 f1_keywords: ["C3388"] helpviewer_keywords: ["C3388"] -ms.assetid: 34336545-ed13-4d81-ab5f-f869799fe4c2 --- # Compiler Error C3388 -'type' : not allowed as a constraint, assuming 'ref class' to continue parsing +> 'type' : not allowed as a constraint, assuming 'ref class' to continue parsing + +## Remarks A constraint was specified on a generic type, but the constraint was not specified correctly. See [Constraints on Generic Type Parameters (C++/CLI)](../../extensions/constraints-on-generic-type-parameters-cpp-cli.md) for more information. ## Example -The following sample generates C3388. +The following example generates C3388. ```cpp // C3388.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3389.md b/docs/error-messages/compiler-errors-2/compiler-error-c3389.md index 01353be5e88..4f662925f08 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3389.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3389.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3389" title: "Compiler Error C3389" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3389" +ms.date: 11/04/2016 f1_keywords: ["C3389"] helpviewer_keywords: ["C3389"] -ms.assetid: eaaffe17-23f2-413c-b1ad-f7220cfa1334 --- # Compiler Error C3389 @@ -18,7 +17,7 @@ A [`__declspec`](../../cpp/declspec.md) modifier used implies a per-process stat ## Example -The following sample generates C3389: +The following example generates C3389: ```cpp // C3389.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3390.md b/docs/error-messages/compiler-errors-2/compiler-error-c3390.md index ecd8d608dd0..ff243fdbd3e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3390.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3390.md @@ -4,21 +4,20 @@ description: "Microsoft C++ compiler error C3390, its causes and how to resolve ms.date: 09/26/2020 f1_keywords: ["C3390"] helpviewer_keywords: ["C3390"] -ms.assetid: 84800a87-c8e6-45aa-82ae-02f816dc8d97 --- # Compiler Error C3390 > '*type_arg*' : invalid type argument for generic parameter '*param*' of generic '*generic_type*', must be a reference type -A generic type was instantiated incorrectly. Check the type definition. - ## Remarks +A generic type was instantiated incorrectly. Check the type definition. + For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The first sample uses C# to create a component that contains a generic type. This type has certain constraints that aren't supported when authoring generic types in C++/CLI. For more information, see [Constraints on Type Parameters](/dotnet/csharp/programming-guide/generics/constraints-on-type-parameters). +The first example uses C# to create a component that contains a generic type. This type has certain constraints that aren't supported when authoring generic types in C++/CLI. For more information, see [Constraints on Type Parameters](/dotnet/csharp/programming-guide/generics/constraints-on-type-parameters). ```csharp // C3390.cs @@ -30,7 +29,7 @@ where V : struct where N : new() {} ``` -When the C3390.dll component is available, the following sample generates C3390. +When the C3390.dll component is available, the following example generates C3390. ```cpp // C3390_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3391.md b/docs/error-messages/compiler-errors-2/compiler-error-c3391.md index 6960f3ffb04..32d4d18f191 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3391.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3391.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3391" title: "Compiler Error C3391" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3391" +ms.date: 11/04/2016 f1_keywords: ["C3391"] helpviewer_keywords: ["C3391"] -ms.assetid: c32532b9-7db4-4ccd-84b9-479e5a1a19d1 --- # Compiler Error C3391 -'type_arg' : invalid type argument for generic parameter 'param' of generic 'generic_type', must be a non-nullable value type +> 'type_arg' : invalid type argument for generic parameter 'param' of generic 'generic_type', must be a non-nullable value type + +## Remarks A generic type was instantiated incorrectly. Check the type definition. For more information, see and [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The following sample uses C# to create a component that contains a generic type that has certain constraints that are not supported when authoring generic types in C++/CLI. For more information, see [Constraints on Type Parameters](/dotnet/csharp/programming-guide/generics/constraints-on-type-parameters). +The following example uses C# to create a component that contains a generic type that has certain constraints that are not supported when authoring generic types in C++/CLI. For more information, see [Constraints on Type Parameters](/dotnet/csharp/programming-guide/generics/constraints-on-type-parameters). ```csharp // C3391.cs @@ -24,7 +25,7 @@ public class GR where N : struct {} ``` -When the C3391.dll component is available, the following sample generates C3391. +When the C3391.dll component is available, the following example generates C3391. ```cpp // C3391_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3392.md b/docs/error-messages/compiler-errors-2/compiler-error-c3392.md index 79b2f3c2bb8..57b89416bf3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3392.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3392.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3392" title: "Compiler Error C3392" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3392" +ms.date: 11/04/2016 f1_keywords: ["C3392"] helpviewer_keywords: ["C3392"] -ms.assetid: e4757596-e2aa-4314-b01e-5c4bfd2110e9 --- # Compiler Error C3392 -'type_arg' : invalid type argument for generic parameter 'param' of generic 'generic_type', must have a public parameterless constructor +> 'type_arg' : invalid type argument for generic parameter 'param' of generic 'generic_type', must have a public parameterless constructor + +## Remarks A generic type was instantiated incorrectly. Check the type definition. For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The following sample uses C# to create a component that contains a generic type that has certain constraints that are not supported when authoring generic types in C++/CLI. For more information, see [Constraints on Type Parameters](/dotnet/csharp/programming-guide/generics/constraints-on-type-parameters). +The following example uses C# to create a component that contains a generic type that has certain constraints that are not supported when authoring generic types in C++/CLI. For more information, see [Constraints on Type Parameters](/dotnet/csharp/programming-guide/generics/constraints-on-type-parameters). ```csharp // C3392.cs @@ -26,7 +27,7 @@ where V : struct where N : new() {} ``` -When the C3392.dll component is available, the following sample generates C3392. +When the C3392.dll component is available, the following example generates C3392. ```cpp // C3392_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3393.md b/docs/error-messages/compiler-errors-2/compiler-error-c3393.md index f302d672a06..82ca666acc1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3393.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3393.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3393" title: "Compiler Error C3393" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3393" +ms.date: 11/04/2016 f1_keywords: ["C3393"] helpviewer_keywords: ["C3393"] -ms.assetid: d57f7c69-0a02-4fe3-9e45-bc62644fd77c --- # Compiler Error C3393 -syntax error in constraint clause: 'identifier' is not a type +> syntax error in constraint clause: 'identifier' is not a type + +## Remarks The identifier passed to a constraint, which must be a type, was not a type. For more information, see [Constraints on Generic Type Parameters (C++/CLI)](../../extensions/constraints-on-generic-type-parameters-cpp-cli.md). ## Example -The following sample generates C3393: +The following example generates C3393: ```cpp // C3393.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3394.md b/docs/error-messages/compiler-errors-2/compiler-error-c3394.md index 8586236b83c..a2866af1438 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3394.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3394.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3394" title: "Compiler Error C3394" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3394" +ms.date: 11/04/2016 f1_keywords: ["C3394"] helpviewer_keywords: ["C3394"] -ms.assetid: 4e025d79-27ba-43c8-b0d9-839ecef98126 --- # Compiler Error C3394 -syntax error in constraint clause: found 'identifier' expected a type +> syntax error in constraint clause: found 'identifier' expected a type + +## Remarks A constraint was ill formed. For more information, see [Constraints on Generic Type Parameters (C++/CLI)](../../extensions/constraints-on-generic-type-parameters-cpp-cli.md). ## Example -The following sample generates C3394: +The following example generates C3394: ```cpp // C3394.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3395.md b/docs/error-messages/compiler-errors-2/compiler-error-c3395.md index 932858dc94a..5c14e3a6380 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3395.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3395.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3395" title: "Compiler Error C3395" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3395" +ms.date: 11/04/2016 f1_keywords: ["C3395"] helpviewer_keywords: ["C3395"] -ms.assetid: 26a9ebc9-ed97-47ce-b436-19aa2bcf6e50 --- # Compiler Error C3395 -'function' : __declspec(dllexport) cannot be applied to a function with the \__clrcall calling convention +> 'function' : __declspec(dllexport) cannot be applied to a function with the \__clrcall calling convention + +## Remarks `__declspec(dllexport)` and [__clrcall](../../cpp/clrcall.md) are not compatible. For more information, see [dllexport, dllimport](../../cpp/dllexport-dllimport.md). -The following sample generates C3395: +## Example + +The following example generates C3395: ```cpp // C3395.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3396.md b/docs/error-messages/compiler-errors-2/compiler-error-c3396.md index 3d79f79eec6..958845bb38e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3396.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3396.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3396" title: "Compiler Error C3396" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3396" +ms.date: 11/04/2016 f1_keywords: ["C3396"] helpviewer_keywords: ["C3396"] -ms.assetid: e3580e32-72ec-4c3e-8afa-755603ffd25c --- # Compiler Error C3396 -'attribute' : custom attribute not found in 'namespace' +> 'attribute' : custom attribute not found in 'namespace' + +## Remarks C3396 indicates that you are not using an up-to-date common language runtime. Reinstall your CLR to resolve. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3397.md b/docs/error-messages/compiler-errors-2/compiler-error-c3397.md index 92b7b3b5ae7..62ff9b28448 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3397.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3397.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3397" title: "Compiler Error C3397" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3397" +ms.date: 11/04/2016 f1_keywords: ["C3397"] helpviewer_keywords: ["C3397"] -ms.assetid: a8536e87-79c4-4ed7-bd96-42704d06391f --- # Compiler Error C3397 -Aggregate initialization is not allowed in default arguments +> Aggregate initialization is not allowed in default arguments + +## Remarks An array was declared incorrectly. See [Arrays](../../extensions/arrays-cpp-component-extensions.md) for more information. ## Example -The following sample generates C3397. +The following example generates C3397. ```cpp // C3397.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3398.md b/docs/error-messages/compiler-errors-2/compiler-error-c3398.md index 27441e24516..12e80fd4613 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3398.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3398.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3398" title: "Compiler Error C3398" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3398" +ms.date: 11/04/2016 f1_keywords: ["C3398"] helpviewer_keywords: ["C3398"] -ms.assetid: 26f8c8a4-526f-415b-8047-155c5cd4f180 --- # Compiler Error C3398 -'operator' : cannot convert from 'function_signature' to 'function_pointer'. Source expression must be a function symbol +> 'operator' : cannot convert from 'function_signature' to 'function_pointer'. Source expression must be a function symbol + +## Remarks When the [__clrcall](../../cpp/clrcall.md) calling convention is not specified when compiling with **/clr**, the compiler generates two entry points (addresses) for each function, a native entry point and a managed entry point. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3399.md b/docs/error-messages/compiler-errors-2/compiler-error-c3399.md index 55794507286..dd6950693e9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3399.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3399.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3399" title: "Compiler Error C3399" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3399" +ms.date: 11/04/2016 f1_keywords: ["C3399"] helpviewer_keywords: ["C3399"] -ms.assetid: 306ad199-d150-4f6c-bcf1-24a7948b93be --- # Compiler Error C3399 -'type' : cannot provide arguments when creating an instance of a generic parameter +> 'type' : cannot provide arguments when creating an instance of a generic parameter + +## Remarks When you specify the `gcnew()` constraint, you specify that the constraint type will have a parameterless constructor. Therefore, it is an error to attempt to instantiate that type and pass a parameter. @@ -16,7 +17,7 @@ See [Constraints on Generic Type Parameters (C++/CLI)](../../extensions/constrai ## Example -The following sample generates C3399. +The following example generates C3399. ```cpp // C3399.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3400.md b/docs/error-messages/compiler-errors-2/compiler-error-c3400.md index df57d95cb79..68f42cc0a03 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3400.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3400.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3400" title: "Compiler Error C3400" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3400" +ms.date: 11/04/2016 f1_keywords: ["C3400"] helpviewer_keywords: ["C3400"] -ms.assetid: d44169a8-73b6-4766-b406-b3a6c93f2a4d --- # Compiler Error C3400 -circular constraint dependency involving 'constraint_1' and 'constraint_2' +> circular constraint dependency involving 'constraint_1' and 'constraint_2' + +## Remarks The compiler detected circular constraints. @@ -16,7 +17,7 @@ For more information, see [Constraints on Generic Type Parameters (C++/CLI)](../ ## Example -The following sample generates C3400. +The following example generates C3400. ```cpp // C3400.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3408.md b/docs/error-messages/compiler-errors-2/compiler-error-c3408.md index 9774072606f..b0239c3bd19 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3408.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3408.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3408" title: "Compiler Error C3408" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3408" +ms.date: 11/04/2016 f1_keywords: ["C3408"] helpviewer_keywords: ["C3408"] -ms.assetid: 1f5ea979-fb1e-4214-b310-6fd6ca8249b1 --- # Compiler Error C3408 -'attribute': attribute is not allowed on template definitions +> 'attribute': attribute is not allowed on template definitions + +## Remarks Attributes cannot be applied to template definitions. ## Example -The following sample generates C3408. +The following example generates C3408. ```cpp // C3408.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3409.md b/docs/error-messages/compiler-errors-2/compiler-error-c3409.md index 393e09c5d88..6603ef05435 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3409.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3409.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3409" title: "Compiler Error C3409" -ms.date: "11/06/2018" +description: "Learn more about: Compiler Error C3409" +ms.date: 11/06/2018 f1_keywords: ["C3409"] helpviewer_keywords: ["C3409"] -ms.assetid: e372d9fa-230c-4b28-b6d3-6ad81ccf9dbb --- # Compiler Error C3409 diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3412.md b/docs/error-messages/compiler-errors-2/compiler-error-c3412.md index f9aab8f46cd..5209a9eca05 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3412.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3412.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3412" title: "Compiler Error C3412" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3412" +ms.date: 11/04/2016 f1_keywords: ["C3412"] helpviewer_keywords: ["C3412"] -ms.assetid: aa4dd43b-54ce-4cda-85c1-1a77dd6e34fa --- # Compiler Error C3412 -'template' : cannot specialize template in current scope +> 'template' : cannot specialize template in current scope + +## Remarks A template cannot be specialized at class scope, only in global or namespace scope. -## Examples +## Example -The following sample generates C3412. +The following example generates C3412. ```cpp // C3412.cpp @@ -25,7 +26,7 @@ struct S { }; ``` -The following sample shows a possible resolution. +The following example shows a possible resolution. ```cpp // C3412b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3413.md b/docs/error-messages/compiler-errors-2/compiler-error-c3413.md index 6e569181037..d5c4e89b153 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3413.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3413.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3413" title: "Compiler Error C3413" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3413" +ms.date: 11/04/2016 f1_keywords: ["C3413"] helpviewer_keywords: ["C3413"] -ms.assetid: de6c9b05-c373-4bd8-8cb0-12c2cd2e5674 --- # Compiler Error C3413 -'name' : invalid explicit instantiation +> 'name' : invalid explicit instantiation + +## Remarks The compiler detected an ill-formed explicit instantiation. -The following sample generates C3413: +## Example + +The following example generates C3413: ```cpp // C3413.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3414.md b/docs/error-messages/compiler-errors-2/compiler-error-c3414.md index 44d295535b0..5ff2d2b3ae5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3414.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3414.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3414" title: "Compiler Error C3414" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3414" +ms.date: 11/04/2016 f1_keywords: ["C3414"] helpviewer_keywords: ["C3414"] -ms.assetid: 715f5432-b509-4f8f-84f5-e1463bac490f --- # Compiler Error C3414 -'member' : imported member function can't be defined +> 'member' : imported member function can't be defined + +## Remarks A member was defined in code that is also defined in a referenced assembly. -The following sample generates C3414: +## Example + +The following example generates C3414: ```cpp // C3414a2.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3415.md b/docs/error-messages/compiler-errors-2/compiler-error-c3415.md index afda211990f..30450c07d51 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3415.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3415.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3415" title: "Compiler Error C3415" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3415" +ms.date: 11/04/2016 f1_keywords: ["C3415"] helpviewer_keywords: ["C3415"] -ms.assetid: fa2db8ab-2820-4ec3-a740-fb5e2adcfb29 --- # Compiler Error C3415 -multiple 'section_name' sections found with different attributes ('value') +> multiple 'section_name' sections found with different attributes ('value') + +## Remarks Conflicting values were specified in [section](../../preprocessor/section.md) pragmas. @@ -33,7 +34,9 @@ Conflicting values were specified in [section](../../preprocessor/section.md) pr #define IMAGE_SCN_MEM_WRITE 0x80000000 ``` -The following sample generates C3415: +## Example + +The following example generates C3415: ```cpp // C3415.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3417.md b/docs/error-messages/compiler-errors-2/compiler-error-c3417.md index debcd0ffbc3..e7fdaddf9e7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3417.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3417.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3417" title: "Compiler Error C3417" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3417" +ms.date: 11/04/2016 f1_keywords: ["C3417"] helpviewer_keywords: ["C3417"] -ms.assetid: 3e7869ea-8948-42fb-ba30-6ccafe499c35 --- # Compiler Error C3417 -'member' : value types cannot contain user-defined special member functions +> 'member' : value types cannot contain user-defined special member functions + +## Remarks Value types cannot contain functions such as a default instance constructor, destructor, or copy constructor. -The following sample generates C3517: +## Example + +The following example generates C3417: ```cpp // C3417.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3418.md b/docs/error-messages/compiler-errors-2/compiler-error-c3418.md index e49e934d0bd..2d7e3ab6a67 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3418.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3418.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3418" title: "Compiler Error C3418" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3418" +ms.date: 11/04/2016 f1_keywords: ["C3418"] helpviewer_keywords: ["C3418"] -ms.assetid: 54042c04-3c45-41c1-bad7-90f9ee05a21b --- # Compiler Error C3418 -access specifier 'specifier' is not supported +> access specifier 'specifier' is not supported + +## Remarks A CLR access specifier was specified incorrectly. For more information, see Type visibility and Member visibility in [How to: Define and Consume Classes and Structs (C++/CLI)](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md). ## Example -The following sample generates C3418. +The following example generates C3418. ```cpp // C3418.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3420.md b/docs/error-messages/compiler-errors-2/compiler-error-c3420.md index da90a0cbaa3..5ae784e3d77 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3420.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3420.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3420" title: "Compiler Error C3420" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3420" +ms.date: 11/04/2016 f1_keywords: ["C3420"] helpviewer_keywords: ["C3420"] -ms.assetid: 99b53c77-f36b-4574-9199-b53111becccb --- # Compiler Error C3420 -'finalizer' : a finalizer cannot be virtual +> 'finalizer' : a finalizer cannot be virtual + +## Remarks A finalizer can only be called non-virtually from its enclosing type. Therefore, it is an error to declare a virtual finalizer. @@ -16,7 +17,7 @@ For more information, see [Destructors and finalizers in How to: Define and cons ## Example -The following sample generates C3420. +The following example generates C3420. ```cpp // C3420.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3421.md b/docs/error-messages/compiler-errors-2/compiler-error-c3421.md index f80f790e6b6..d3c41e7bdab 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3421.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3421.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3421" title: "Compiler Error C3421" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3421" +ms.date: 11/04/2016 f1_keywords: ["C3421"] helpviewer_keywords: ["C3421"] -ms.assetid: b52050c6-17a4-424a-8894-337b0cec7010 --- # Compiler Error C3421 -'type' : you cannot call the finalizer for this class as it is either inaccessible or it does not exist +> 'type' : you cannot call the finalizer for this class as it is either inaccessible or it does not exist + +## Remarks A finalizer is implicitly private, so it cannot be called from outside its enclosing type. @@ -16,7 +17,7 @@ For more information, see [Destructors and finalizers in How to: Define and cons ## Example -The following sample generates C3421. +The following example generates C3421. ```cpp // C3421.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3445.md b/docs/error-messages/compiler-errors-2/compiler-error-c3445.md index 3fc2bcb631b..7add75b0312 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3445.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3445.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3445" title: "Compiler Error C3445" -ms.date: "04/10/2017" +description: "Learn more about: Compiler Error C3445" +ms.date: 04/10/2017 f1_keywords: ["C3445"] helpviewer_keywords: ["C3445"] -ms.assetid: 0d272bfc-136b-4025-a9ba-5e4eea5f8215 --- # Compiler Error C3445 > copy-list-initialization of '*type*' cannot use an explicit constructor +## Remarks + According to the ISO C++17 standard, the compiler is required to consider an explicit constructor for overload resolution in copy-list-initialization, but must raise an error if that overload is actually chosen. Starting in Visual Studio 2017, the compiler finds errors related to object creation by using an initializer list that were not found by Visual Studio 2015. These errors could lead to crashes or undefined behavior at runtime. ## Example -The following sample generates C3445. +The following example generates C3445. ```cpp // C3445.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3446.md b/docs/error-messages/compiler-errors-2/compiler-error-c3446.md index 0a6ae8b11ee..46fe4603c2f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3446.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3446.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3446" title: "Compiler Error C3446" -ms.date: "07/21/2017" +description: "Learn more about: Compiler Error C3446" +ms.date: 07/21/2017 f1_keywords: ["C3446"] helpviewer_keywords: ["C3446"] -ms.assetid: 33064548-24e4-46f1-beb1-476e3c3b3fbf --- # Compiler Error C3446 ->'*class*': a default member initializer is not allowed for a member of a value class +> '*class*': a default member initializer is not allowed for a member of a value class + +## Remarks In Visual Studio 2015 and earlier, the compiler permitted (but ignored) a default member initializer for a member of a value class. Default initialization of a value class always zero-initializes the members; a default constructor is not permitted. In Visual Studio 2017, default member initializers raise a compiler error, as shown in this example: ## Example -The following sample generates C3446 in Visual Studio 2017 and later: +The following example generates C3446 in Visual Studio 2017 and later: ```cpp // C3446.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3450.md b/docs/error-messages/compiler-errors-2/compiler-error-c3450.md index ffdbc286a20..1b8c1d6bf6f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3450.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3450.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3450" title: "Compiler Error C3450" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3450" +ms.date: 11/04/2016 f1_keywords: ["C3450"] helpviewer_keywords: ["C3450"] -ms.assetid: 78892cf7-0b82-4589-90d0-e06666247003 --- # Compiler Error C3450 -'type': not an attribute; cannot specify [System::AttributeUsageAttribute] or [Windows::Foundation::Metadata::AttributeUsageAttribute] +> 'type': not an attribute; cannot specify [System::AttributeUsageAttribute] or [Windows::Foundation::Metadata::AttributeUsageAttribute] + +## Remarks A user-defined managed attribute must inherit from . A Windows Runtime attribute must be defined in the `Windows::Foundation::Metadata` namespace. @@ -16,7 +17,7 @@ For more information, see [User-Defined Attributes](../../extensions/user-define ## Example -The following sample generates C3450 and shows how to fix it. +The following example generates C3450 and shows how to fix it. ```cpp // C3450.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3451.md b/docs/error-messages/compiler-errors-2/compiler-error-c3451.md index 6e7e9dbe75e..17b42bf6a51 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3451.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3451.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3451" title: "Compiler Error C3451" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3451" +ms.date: 11/04/2016 f1_keywords: ["C3451"] helpviewer_keywords: ["C3451"] -ms.assetid: a4897a69-e3e7-40bb-bb1c-598644904012 --- # Compiler Error C3451 -'attribute': cannot apply unmanaged attribute to 'type' +> 'attribute': cannot apply unmanaged attribute to 'type' + +## Remarks A C++ attribute cannot be applied to a CLR type. See [C++ Attributes Reference](../../windows/attributes/attributes-alphabetical-reference.md) for more information. @@ -18,7 +19,7 @@ This error can be generated as a result of compiler conformance work that was do ## Example -The following sample generates C3451. +The following example generates C3451. ```cpp // C3451.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3452.md b/docs/error-messages/compiler-errors-2/compiler-error-c3452.md index b40ab656fc2..4a112bc3935 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3452.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3452.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3452" title: "Compiler Error C3452" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3452" +ms.date: 11/04/2016 f1_keywords: ["C3452"] helpviewer_keywords: ["C3452"] -ms.assetid: e5293dcf-cb70-4133-ae2a-0bb496950ba0 --- # Compiler Error C3452 -list argument member not constant +> list argument member not constant + +## Remarks An argument was passed to an attribute that expected a constant, a value that can be evaluated at compile time. ## Example -The following sample generates C3452. +The following example generates C3452. ```cpp // C3452.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3453.md b/docs/error-messages/compiler-errors-2/compiler-error-c3453.md index edd640d730a..d04287ade5b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3453.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3453.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3453" title: "Compiler Error C3453" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3453" +ms.date: 11/04/2016 f1_keywords: ["C3453"] helpviewer_keywords: ["C3453"] -ms.assetid: dbefdbcf-f697-4239-b7a5-1d99b85e9e7f --- # Compiler Error C3453 -'attribute': attribute not applied because qualifier 'assembly' did not match +> 'attribute': attribute not applied because qualifier 'assembly' did not match + +## Remarks Assembly or module level attributes can only be specified as stand-alone instructions. ## Example -The following sample generates C3453. +The following example generates C3453. ```cpp // C3453.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3454.md b/docs/error-messages/compiler-errors-2/compiler-error-c3454.md index f051c32753f..c7034d16637 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3454.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3454.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3454" title: "Compiler Error C3454" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3454" +ms.date: 11/04/2016 f1_keywords: ["C3454"] helpviewer_keywords: ["C3454"] -ms.assetid: dc4e6d57-5b4d-4114-8d6f-22f9ae62925b --- # Compiler Error C3454 -[attribute] not allowed on class declaration +> [attribute] not allowed on class declaration + +## Remarks A class must be defined for it to be an attribute. @@ -16,7 +17,7 @@ For more information, see [attribute](../../windows/attributes/attribute.md). ## Example -The following sample generates C3454. +The following example generates C3454. ```cpp // C3454.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3455.md b/docs/error-messages/compiler-errors-2/compiler-error-c3455.md index f32ad44b44c..5cdd85744c9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3455.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3455.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3455" title: "Compiler Error C3455" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3455" +ms.date: 11/04/2016 f1_keywords: ["C3455"] helpviewer_keywords: ["C3455"] -ms.assetid: 218e5cfe-5391-4eeb-81c2-85c47e3a6cd2 --- # Compiler Error C3455 -'attribute': none of the attribute constructors matched the arguments +> 'attribute': none of the attribute constructors matched the arguments + +## Remarks An invalid value was used to declare an attribute. See [attribute](../../windows/attributes/attribute.md) for more information. ## Example -The following sample generates C3455. +The following example generates C3455. ```cpp // C3455.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3456.md b/docs/error-messages/compiler-errors-2/compiler-error-c3456.md index 73d326827fd..996bf27c057 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3456.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3456.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3456" title: "Compiler Error C3456" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3456" +ms.date: 11/04/2016 f1_keywords: ["C3456"] helpviewer_keywords: ["C3456"] -ms.assetid: 9f781919-aaf2-4725-94a4-44a0b80cc64a --- # Compiler Error C3456 -[source_annotation_attribute] not allowed on managed or WinRT class declaration +> [source_annotation_attribute] not allowed on managed or WinRT class declaration + +## Remarks source_annotation_attribute is used to define custom attributes to be used by code analysis. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3457.md b/docs/error-messages/compiler-errors-2/compiler-error-c3457.md index 151c01319fe..dc7ffe0c88b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3457.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3457.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3457" title: "Compiler Error C3457" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3457" +ms.date: 11/04/2016 f1_keywords: ["C3457"] helpviewer_keywords: ["C3457"] -ms.assetid: 5c1e366a-fa75-4cca-b9a3-86d4ebe4090e --- # Compiler Error C3457 -'attribute': attribute does not support unnamed arguments +> 'attribute': attribute does not support unnamed arguments + +## Remarks Source annotation attributes, unlike CLR custom attribute or compiler attributes, only support named arguments. ## Example -The following sample generates C3457. +The following example generates C3457. -``` +```cpp #include "SourceAnnotations.h" [vc_attributes::Post( 1 )] int f(); // C3457 [vc_attributes::Post( Valid=vc_attributes::Yes )] int f2(); // OK diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3458.md b/docs/error-messages/compiler-errors-2/compiler-error-c3458.md index 345783c0e18..a6d8238079d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3458.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3458.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3458" title: "Compiler Error C3458" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3458" +ms.date: 11/04/2016 f1_keywords: ["C3458"] helpviewer_keywords: ["C3458"] -ms.assetid: 940202fd-8dcc-4042-9c96-3f9e9127d2f1 --- # Compiler Error C3458 -'attribute1': attribute 'attribute2' already specified for 'construct' +> 'attribute1': attribute 'attribute2' already specified for 'construct' + +## Remarks Two attributes that are mutually exclusive were specified for the same construct. ## Example -The following sample generates C3458 +The following example generates C3458 ```cpp // C3458.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3459.md b/docs/error-messages/compiler-errors-2/compiler-error-c3459.md index 98298a38e28..4c8ad60d6f9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3459.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3459.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3459" title: "Compiler Error C3459" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3459" +ms.date: 11/04/2016 f1_keywords: ["C3459"] helpviewer_keywords: ["C3459"] -ms.assetid: 3d290a20-d313-4c07-9bd8-c5c159cb169f --- # Compiler Error C3459 -'attribute': attribute allowed only on class indexer (default indexed property) +> 'attribute': attribute allowed only on class indexer (default indexed property) + +## Remarks An attribute that is designed to be applied to a class indexer property was used incorrectly. @@ -16,7 +17,7 @@ For more information, see [How to: Use Properties in C++/CLI](../../dotnet/how-t ## Example -The following sample generates C3459. +The following example generates C3459. ```cpp // C3459.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3460.md b/docs/error-messages/compiler-errors-2/compiler-error-c3460.md index 58c67af4f7f..e002f487f9e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3460.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3460.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3460" title: "Compiler Error C3460" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3460" +ms.date: 11/04/2016 f1_keywords: ["C3460"] helpviewer_keywords: ["C3460"] -ms.assetid: adbf8775-10ca-4654-acdf-58dd765351cd --- # Compiler Error C3460 -'type': only a user-defined type can be forwarded +> 'type': only a user-defined type can be forwarded + +## Remarks For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C3460.cpp @@ -22,7 +23,7 @@ The following sample creates a component. public ref class R {}; ``` -The following sample generates C3460. +The following example generates C3460. ```cpp // C3460_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3461.md b/docs/error-messages/compiler-errors-2/compiler-error-c3461.md index 4c45c0a6eac..9c801ba167e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3461.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3461.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3461" title: "Compiler Error C3461" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3461" +ms.date: 11/04/2016 f1_keywords: ["C3461"] helpviewer_keywords: ["C3461"] -ms.assetid: bd66833a-545d-445a-bdfe-dee771a450a4 --- # Compiler Error C3461 -'type': only a managed type can be forwarded +> 'type': only a managed type can be forwarded + +## Remarks Type forwarding can only occur on CLR types. See [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md) for more information. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C3461.cpp @@ -24,7 +25,7 @@ The following sample creates a component. public ref class R {}; ``` -The following sample generates C3461. +The following example generates C3461. ```cpp // C3461b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3462.md b/docs/error-messages/compiler-errors-2/compiler-error-c3462.md index 1711df90e85..1c48adb2f45 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3462.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3462.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3462" title: "Compiler Error C3462" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3462" +ms.date: 11/04/2016 f1_keywords: ["C3462"] helpviewer_keywords: ["C3462"] -ms.assetid: 56b75f35-9fad-42d9-a969-eeca5d709bec --- # Compiler Error C3462 -'type': only an imported type can be forwarded +> 'type': only an imported type can be forwarded + +## Remarks The TypeForwardedTo attribute must be applied to a type in referenced metadata. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C3462.cpp @@ -24,7 +25,7 @@ The following sample creates a component. public ref class R {}; ``` -The following sample generates C3462. +The following example generates C3462. ```cpp // C3462b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3463.md b/docs/error-messages/compiler-errors-2/compiler-error-c3463.md index 96fbcf90c51..e2b9d5fff23 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3463.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3463.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3463" title: "Compiler Error C3463" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3463" +ms.date: 11/04/2016 f1_keywords: ["C3463"] helpviewer_keywords: ["C3463"] -ms.assetid: 153efcc0-085c-4615-84ea-d22942618bdf --- # Compiler Error C3463 -'type': type not allowed in attribute 'implements' +> 'type': type not allowed in attribute 'implements' + +## Remarks An invalid type was passed to the [implements](../../windows/attributes/implements-cpp.md) attribute. For example, you can pass an interface to `implements`, but you cannot pass a pointer to an interface. ## Example -The following sample generates C3463. +The following example generates C3463. ```cpp // C3463.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3464.md b/docs/error-messages/compiler-errors-2/compiler-error-c3464.md index 4def91d2596..684c143ea61 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3464.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3464.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3464" title: "Compiler Error C3464" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3464" +ms.date: 11/04/2016 f1_keywords: ["C3464"] helpviewer_keywords: ["C3464"] -ms.assetid: 0ede05dc-4486-4921-8e8c-78ab5a2e09c5 --- # Compiler Error C3464 -'type' a nested type cannot be forwarded +> 'type' a nested type cannot be forwarded + +## Remarks Type forwarding does not work on nested types. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C3464.cpp @@ -27,7 +28,7 @@ public: }; ``` -The following sample generates C3464. +The following example generates C3464. ```cpp // C3464_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3465.md b/docs/error-messages/compiler-errors-2/compiler-error-c3465.md index 453ced5d660..b49fc9e1f2e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3465.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3465.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3465" title: "Compiler Error C3465" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3465" +ms.date: 11/04/2016 f1_keywords: ["C3465"] helpviewer_keywords: ["C3465"] -ms.assetid: aeb815e5-b3fc-4525-afe2-d738e9321df1 --- # Compiler Error C3465 -to use type 'type' you must reference the assembly 'assembly' +> to use type 'type' you must reference the assembly 'assembly' + +## Remarks Type forwarding will work for a client application until you recompile the client. When you recompile, you will need a reference for every assembly containing the definition of a type used in your client application. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample builds an assembly that contains the new location of a type. +The following example builds an assembly that contains the new location of a type. ```cpp // C3465.cpp @@ -27,7 +28,7 @@ public: }; ``` -The following sample builds an assembly that used to contain the definition of the type, but now contains forwarding syntax for the type. +The following example builds an assembly that used to contain the definition of the type, but now contains forwarding syntax for the type. ```cpp // C3465_b.cpp @@ -36,7 +37,7 @@ The following sample builds an assembly that used to contain the definition of t [ assembly:TypeForwardedTo(R::typeid) ]; ``` -The following sample generates C3465. +The following example generates C3465. ```cpp // C3465_c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3466.md b/docs/error-messages/compiler-errors-2/compiler-error-c3466.md index 2f1b223aa91..9183287145d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3466.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3466.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3466" title: "Compiler Error C3466" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3466" +ms.date: 11/04/2016 f1_keywords: ["C3466"] helpviewer_keywords: ["C3466"] -ms.assetid: 69a877d9-a749-474b-bfc3-8d3fd53ba8fd --- # Compiler Error C3466 -'type' : a specialization of a generic class cannot be forwarded +> 'type' : a specialization of a generic class cannot be forwarded + +## Remarks You cannot use type forwarding on a specialization of a generic class. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C3466.cpp @@ -27,7 +28,7 @@ public ref class GR {}; public ref class GR2 {}; ``` -The following sample generates C3466. +The following example generates C3466. ```cpp // C3466_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3467.md b/docs/error-messages/compiler-errors-2/compiler-error-c3467.md index 05af0ad696d..4b253247f2d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3467.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3467.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3467" title: "Compiler Error C3467" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3467" +ms.date: 11/04/2016 f1_keywords: ["C3467"] helpviewer_keywords: ["C3467"] -ms.assetid: e2b844d0-4920-412f-99fd-cd8051c4aa41 --- # Compiler Error C3467 -'type' : this type has already been forwarded +> 'type' : this type has already been forwarded + +## Remarks The compiler found more than one forward type declaration for the same type. Only one declaration per type is allowed. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C3467.cpp @@ -24,7 +25,7 @@ The following sample creates a component. public ref class R {}; ``` -The following sample generates C3467. +The following example generates C3467. ```cpp // C3467_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3468.md b/docs/error-messages/compiler-errors-2/compiler-error-c3468.md index 62e82fd9136..e101a28857d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3468.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3468.md @@ -1,24 +1,23 @@ --- -description: "Learn more about: Compiler Error C3468" title: "Compiler Error C3468" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3468" +ms.date: 11/04/2016 f1_keywords: ["C3468"] helpviewer_keywords: ["C3468"] -ms.assetid: cfd320db-2f6e-4e0d-ba02-e79ece87e1e0 --- # Compiler Error C3468 -'type' : you can only forward a type to an assembly: +> '*type*': you can only forward a type to an assembly: '*identifier*' is not an assembly -'`file`' is not an assembly +## Remarks Only types in an assembly can be forwarded. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a module. +The following example creates a module. ```cpp // C3468.cpp @@ -26,7 +25,7 @@ The following sample creates a module. public ref class R {}; ``` -The following sample generates C3468. +The following example generates C3468. ```cpp // C3468_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3469.md b/docs/error-messages/compiler-errors-2/compiler-error-c3469.md index e45fb32a382..e835ecfbecf 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3469.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3469.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3469" title: "Compiler Error C3469" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3469" +ms.date: 11/04/2016 f1_keywords: ["C3469"] helpviewer_keywords: ["C3469"] -ms.assetid: e23b0e5c-c704-4e67-a868-bf02c2055d85 --- # Compiler Error C3469 -'type' : a generic class cannot be forwarded +> 'type' : a generic class cannot be forwarded + +## Remarks You cannot use type forwarding on a generic class. For more information, see [Type Forwarding (C++/CLI)](../../extensions/type-forwarding-cpp-cli.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C3469.cpp @@ -27,7 +28,7 @@ public ref class GR {}; public ref class GR2 {}; ``` -The following sample generates C3466. +The following example generates C3469. ```cpp // C3469_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3470.md b/docs/error-messages/compiler-errors-2/compiler-error-c3470.md index a487c4e889b..ebbbfbe2096 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3470.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3470.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3470" title: "Compiler Error C3470" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3470" +ms.date: 11/04/2016 f1_keywords: ["C3470"] helpviewer_keywords: ["C3470"] -ms.assetid: 170c7a9d-214d-41b1-8f15-d4a4fc38aaa5 --- # Compiler Error C3470 -'type' : a class cannot have both an indexer (default indexed property) and an operator[] +> 'type' : a class cannot have both an indexer (default indexed property) and an operator[] + +## Remarks A type cannot define both a default indexer and an operator[]. ## Example -The following sample generates C3470 +The following example generates C3470 ```cpp // C3470.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3480.md b/docs/error-messages/compiler-errors-2/compiler-error-c3480.md index 261faca8ab3..a032ea4e1b8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3480.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3480.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3480" title: "Compiler Error C3480" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3480" +ms.date: 11/04/2016 f1_keywords: ["C3480"] helpviewer_keywords: ["C3480"] -ms.assetid: 7b2e055a-9604-4d13-861b-b38bda1a6940 --- # Compiler Error C3480 -'var': a lambda capture variable must be from an enclosing function scope +> 'var': a lambda capture variable must be from an enclosing function scope + +## Remarks The lambda capture variable is not from an enclosing function scope. @@ -16,7 +17,7 @@ The lambda capture variable is not from an enclosing function scope. - Remove the variable from the capture list of the lambda expression. -## Examples +## Example The following example generates C3480 because the variable `global` is not from an enclosing function scope: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3481.md b/docs/error-messages/compiler-errors-2/compiler-error-c3481.md index 775cbc06826..7e07537f533 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3481.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3481.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3481" title: "Compiler Error C3481" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3481" +ms.date: 11/04/2016 f1_keywords: ["C3481"] helpviewer_keywords: ["C3481"] -ms.assetid: 5d09375a-5ed3-4b61-86ed-45e91fd734c7 --- # Compiler Error C3481 -'var': lambda capture variable not found +> 'var': lambda capture variable not found + +## Remarks The compiler could not find the definition of a variable that you passed to the capture list of a lambda expression. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3482.md b/docs/error-messages/compiler-errors-2/compiler-error-c3482.md index 8e471aea04c..3b396c9bedc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3482.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3482.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3482" title: "Compiler Error C3482" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3482" +ms.date: 11/04/2016 f1_keywords: ["C3482"] helpviewer_keywords: ["C3482"] -ms.assetid: bf99558e-bef4-421c-bb16-dcd9c54c1011 --- # Compiler Error C3482 -'this' can only be used as a lambda capture within a non-static member function +> 'this' can only be used as a lambda capture within a non-static member function + +## Remarks You cannot pass **`this`** to the capture list of a lambda expression that is declared in a static method or a global function. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3483.md b/docs/error-messages/compiler-errors-2/compiler-error-c3483.md index 0664764558f..2fee0c0075b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3483.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3483.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3483" title: "Compiler Error C3483" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3483" +ms.date: 11/04/2016 f1_keywords: ["C3483"] helpviewer_keywords: ["C3483"] -ms.assetid: 18b3a2c5-dfc9-4661-9653-08a5798474cf --- # Compiler Error C3483 -'var' is already part of the lambda capture list +> 'var' is already part of the lambda capture list + +## Remarks You passed the same variable to the capture list of a lambda expression more than one time. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3484.md b/docs/error-messages/compiler-errors-2/compiler-error-c3484.md index 43a0e771a38..1da53a08ba9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3484.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3484.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3484" title: "Compiler Error C3484" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3484" +ms.date: 11/04/2016 f1_keywords: ["C3484"] helpviewer_keywords: ["C3484"] -ms.assetid: 2fe847fa-f6ee-4978-bc1d-b6dc6ae906ac --- # Compiler Error C3484 -expected '->' before the return type +> expected '->' before the return type + +## Remarks You must provide `->` before the return type of a lambda expression. @@ -16,7 +17,7 @@ You must provide `->` before the return type of a lambda expression. - Provide `->` before the return type. -## Examples +## Example The following example generates C3484: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3485.md b/docs/error-messages/compiler-errors-2/compiler-error-c3485.md index f1a62610292..30fa2541210 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3485.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3485.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3485" title: "Compiler Error C3485" +description: "Learn more about: Compiler Error C3485" ms.date: 06/01/2022 f1_keywords: ["C3485"] helpviewer_keywords: ["C3485"] -ms.assetid: d67536f9-67a1-4ad9-9a94-d8bbbca3d0dc --- # Compiler Error C3485 diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3487.md b/docs/error-messages/compiler-errors-2/compiler-error-c3487.md index 6af8420b559..7a34600a5aa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3487.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3487.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3487" title: "Compiler Error C3487" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3487" +ms.date: 11/04/2016 f1_keywords: ["C3487"] helpviewer_keywords: ["C3487"] -ms.assetid: 39bda474-4418-4a79-98bf-2b22fa92eaaa --- # Compiler Error C3487 -'return type': all return expressions must deduce to the same type: previously it was 'return type' +> 'return type': all return expressions must deduce to the same type: previously it was 'return type' + +## Remarks A lambda must specify its return type unless it contains a single return statement. If a lambda contains multiple return statements, they must all have the same type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3488.md b/docs/error-messages/compiler-errors-2/compiler-error-c3488.md index 7a38d4c1158..407a19b00e1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3488.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3488.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3488" title: "Compiler Error C3488" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3488" +ms.date: 11/04/2016 f1_keywords: ["C3488"] helpviewer_keywords: ["C3488"] -ms.assetid: 0a6fcd76-dd3b-48d7-abb3-22eccda96034 --- # Compiler Error C3488 -'var' is not allowed when the default capture mode is by-reference +> 'var' is not allowed when the default capture mode is by-reference + +## Remarks When you specify that the default capture mode for a lambda expression is by-reference, you cannot pass a variable by reference to the capture clause of that expression. @@ -22,7 +23,7 @@ When you specify that the default capture mode for a lambda expression is by-ref - Pass the variable by value to the capture clause. (This might change the behavior of the lambda expression.) -## Examples +## Example The following example generates C3488 because a reference to the variable `n` appears in the capture clause of a lambda expression whose default mode is by-reference: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3489.md b/docs/error-messages/compiler-errors-2/compiler-error-c3489.md index fbd175529d6..3aa45bc46d6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3489.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3489.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3489" title: "Compiler Error C3489" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3489" +ms.date: 11/04/2016 f1_keywords: ["C3489"] helpviewer_keywords: ["C3489"] -ms.assetid: 47b58d69-459d-4499-abc7-5f0b9303d773 --- # Compiler Error C3489 -'var' is required when the default capture mode is by-value +> 'var' is required when the default capture mode is by-value + +## Remarks When you specify that the default capture mode for a lambda expression is by-value, you cannot pass a variable by value to the capture clause of that expression. @@ -22,7 +23,7 @@ When you specify that the default capture mode for a lambda expression is by-val - Pass the variable by reference to the capture clause. (This might change the behavior of the lambda expression.) -## Examples +## Example The following example generates C3489 variable `n` appears by value in the capture clause of a lambda expression whose default mode is by-value: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3490.md b/docs/error-messages/compiler-errors-2/compiler-error-c3490.md index 55fda1bfc02..191d54b3881 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3490.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3490.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3490" title: "Compiler Error C3490" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3490" +ms.date: 11/04/2016 f1_keywords: ["C3490"] helpviewer_keywords: ["C3490"] -ms.assetid: 7638559a-fd06-4527-a9c1-0c8ae68b3123 --- # Compiler Error C3490 -'var' cannot be modified because it is being accessed through a const object +> 'var' cannot be modified because it is being accessed through a const object + +## Remarks A lambda expression that is declared in a **`const`** method cannot modify non-mutable member data. @@ -16,7 +17,7 @@ A lambda expression that is declared in a **`const`** method cannot modify non-m - Remove the **`const`** modifier from your method declaration. -## Examples +## Example The following example generates C3490 because it modifies the member variable `_i` in a **`const`** method: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3491.md b/docs/error-messages/compiler-errors-2/compiler-error-c3491.md index f941d825ccb..4183526cc84 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3491.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3491.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3491" title: "Compiler Error C3491" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3491" +ms.date: 11/04/2016 f1_keywords: ["C3491"] helpviewer_keywords: ["C3491"] -ms.assetid: 7f0e71b2-46a0-4d25-bd09-6158a280f509 --- # Compiler Error C3491 -'var': a by-value capture cannot be modified in a non-mutable lambda +> 'var': a by-value capture cannot be modified in a non-mutable lambda + +## Remarks A non-mutable lambda expression cannot modify the value of a variable that is captured by value. @@ -18,7 +19,7 @@ A non-mutable lambda expression cannot modify the value of a variable that is ca - Pass the variable by reference to the capture list of the lambda expression. -## Examples +## Example The following example generates C3491 because the body of a non-mutable lambda expression modifies the capture variable `m`: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3492.md b/docs/error-messages/compiler-errors-2/compiler-error-c3492.md index 3883b98b062..6993760f29a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3492.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3492.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3492" title: "Compiler Error C3492" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3492" +ms.date: 11/04/2016 f1_keywords: ["C3492"] helpviewer_keywords: ["C3492"] -ms.assetid: b1dc6342-9133-4b1f-a9c3-e8c65d20d121 --- # Compiler Error C3492 -'var': you cannot capture a member of an anonymous union +> 'var': you cannot capture a member of an anonymous union + +## Remarks You cannot capture a member of an unnamed union. @@ -16,7 +17,7 @@ You cannot capture a member of an unnamed union. - Give the union a name and pass the complete union structure to the capture list of the lambda expression. -## Examples +## Example The following example generates C3492 because it captures a member of an anonymous union: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3493.md b/docs/error-messages/compiler-errors-2/compiler-error-c3493.md index f711ca6cabf..6101fd828c6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3493.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3493.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3493" title: "Compiler Error C3493" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3493" +ms.date: 11/04/2016 f1_keywords: ["C3493"] helpviewer_keywords: ["C3493"] -ms.assetid: 734b4257-12a3-436f-8488-c8c55ec81634 --- # Compiler Error C3493 -'var' cannot be implicitly captured because no default capture mode has been specified +> 'var' cannot be implicitly captured because no default capture mode has been specified + +## Remarks The empty lambda expression capture, `[]`, specifies that the lambda expression does not explicitly or implicitly capture any variables. @@ -18,7 +19,7 @@ The empty lambda expression capture, `[]`, specifies that the lambda expression - Explicitly capture one or more variables. -## Examples +## Example The following example generates C3493 because it modifies an external variable but specifies the empty capture clause: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3495.md b/docs/error-messages/compiler-errors-2/compiler-error-c3495.md index 361a6225925..be74c020b84 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3495.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3495.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3495" title: "Compiler Error C3495" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3495" +ms.date: 11/04/2016 f1_keywords: ["C3495"] helpviewer_keywords: ["C3495"] -ms.assetid: 1fd40cb8-8373-403d-b8a8-f08424a50807 --- # Compiler Error C3495 -'var': a lambda capture must have automatic storage duration +> 'var': a lambda capture must have automatic storage duration + +## Remarks You cannot capture a variable that does not have automatic storage duration, such as a variable that is marked **`static`** or **`extern`**. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3496.md b/docs/error-messages/compiler-errors-2/compiler-error-c3496.md index b766b396aff..b859690dd96 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3496.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3496.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3496" title: "Compiler Error C3496" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3496" +ms.date: 11/04/2016 f1_keywords: ["C3496"] helpviewer_keywords: ["C3496"] -ms.assetid: e19885f2-677f-4c1e-bc69-e35852262dc3 --- # Compiler Error C3496 -'this' is always captured by value: '&' ignored +> 'this' is always captured by value: '&' ignored + +## Remarks You cannot capture the **`this`** pointer by reference. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3498.md b/docs/error-messages/compiler-errors-2/compiler-error-c3498.md index 353b893e20b..71ba1c6542b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3498.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3498.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3498" title: "Compiler Error C3498" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3498" +ms.date: 11/04/2016 f1_keywords: ["C3498"] helpviewer_keywords: ["C3498"] -ms.assetid: 0a5a7817-0872-4119-83bf-980a19113374 --- # Compiler Error C3498 -'var': you cannot capture a variable that has a managed or WinRTtype +> 'var': you cannot capture a variable that has a managed or WinRTtype + +## Remarks You cannot capture a variable that has a managed type or a Windows Runtime type in a lambda. @@ -16,7 +17,7 @@ You cannot capture a variable that has a managed type or a Windows Runtime type - Pass the managed or Windows Runtime variable to the parameter list of the lambda expression. -## Examples +## Example The following example generates C3498 because a variable that has a managed type appears in the capture list of a lambda expression: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3499.md b/docs/error-messages/compiler-errors-2/compiler-error-c3499.md index 0004f9b25bc..390975bf586 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3499.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3499.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3499" title: "Compiler Error C3499" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3499" +ms.date: 11/04/2016 f1_keywords: ["C3499"] helpviewer_keywords: ["C3499"] -ms.assetid: 6717de5c-ae0f-4024-bdf2-b5598009e7b6 --- # Compiler Error C3499 -a lambda that has been specified to have a void return type cannot return a value +> a lambda that has been specified to have a void return type cannot return a value + +## Remarks The compiler generates this error when a lambda expression that specifies **`void`** as the return type returns a value; or when a lambda expression contains more than one statement and returns a value, but does not specify its return type. @@ -20,7 +21,7 @@ The compiler generates this error when a lambda expression that specifies **`voi - Combine the statements that make up the body of the lambda expression into a single statement. -## Examples +## Example The following example generates C3499 because the body of a lambda expression contains multiple statements and returns a value, but the lambda expression does not specify the return type: diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3500.md b/docs/error-messages/compiler-errors-2/compiler-error-c3500.md index 7498428d7d6..7de809c495b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3500.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3500.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3500" title: "Compiler Error C3500" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3500" +ms.date: 11/04/2016 f1_keywords: ["C3500"] helpviewer_keywords: ["C3500"] -ms.assetid: 77336f16-04f5-4943-bfc0-faba4cd8bb51 --- # Compiler Error C3500 -invalid ProgID 'progid' +> invalid ProgID 'progid' + +## Remarks An invalid progid was specified with the `#import` statement. Check the Windows registry to ensure that you are specifying a valid progid. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3501.md b/docs/error-messages/compiler-errors-2/compiler-error-c3501.md index 87053046e34..980a2f5a0bb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3501.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3501.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3501" title: "Compiler Error C3501" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3501" +ms.date: 11/04/2016 f1_keywords: ["C3501"] helpviewer_keywords: ["C3501"] -ms.assetid: cad69fab-2687-41ac-961f-25dc4c51b167 --- # Compiler Error C3501 -there is no typelib registered for ProgID 'progid' +> there is no typelib registered for ProgID 'progid' + +## Remarks The class ID for a given progid does not have an associated type library. Therefore, you cannot pass this progid to the `#import` statement. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3505.md b/docs/error-messages/compiler-errors-2/compiler-error-c3505.md index f3d6d67d2c2..c383d2d03e1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3505.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3505.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3505" title: "Compiler Error C3505" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3505" +ms.date: 11/04/2016 f1_keywords: ["C3505"] helpviewer_keywords: ["C3505"] -ms.assetid: ed73c99e-93a1-4f3a-bac7-ba7ed5d836e4 --- # Compiler Error C3505 > cannot load type library '*guid*' +## Remarks + C3505 can be caused if you are running the 32-bit, x86-hosted cross-compiler for 64-bit, x64 targets on a 64-bit machine, because the compiler is running under WOW64 and can only read from the 32-bit registry hive. You can resolve this error by building both 32-bit and 64-bit versions of the type library you are trying to import, and then register them both. Or you can use the native 64-bit compiler, which requires you to change your **VC++ Directories** property in the IDE to point to the 64-bit compiler. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3506.md b/docs/error-messages/compiler-errors-2/compiler-error-c3506.md index 9ff1a9b7fda..8a2a8d3b71c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3506.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3506.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3506" title: "Compiler Error C3506" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3506" +ms.date: 11/04/2016 f1_keywords: ["C3506"] helpviewer_keywords: ["C3506"] -ms.assetid: d382c067-5fad-42ca-acf3-9e6d8cbdb2c5 --- # Compiler Error C3506 -there is no typelib registered for LIBID 'id' +> there is no typelib registered for LIBID 'id' + +## Remarks A typelib was not registered correctly. Use regsvr32.exe to register a type library. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3507.md b/docs/error-messages/compiler-errors-2/compiler-error-c3507.md index e28427a5e8b..ed79db7afe0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3507.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3507.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3507" title: "Compiler Error C3507" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3507" +ms.date: 11/04/2016 f1_keywords: ["C3507"] helpviewer_keywords: ["C3507"] -ms.assetid: 75f89767-f6f9-40f6-9820-81a49e09abdf --- # Compiler Error C3507 -a ProgID can have no more than 39 characters 'id'; nor contain any punctuation apart from '.'; nor start with a digit +> a ProgID can have no more than 39 characters 'id'; nor contain any punctuation apart from '.'; nor start with a digit + +## Remarks The [progid](../../windows/attributes/progid.md) attribute has restrictions on the values that it can take. -The following sample generates C3507: +## Example + +The following example generates C3507: ```cpp // C3507.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3508.md b/docs/error-messages/compiler-errors-2/compiler-error-c3508.md index d179185e372..189788fc259 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3508.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3508.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3508" title: "Compiler Error C3508" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3508" +ms.date: 11/04/2016 f1_keywords: ["C3508"] helpviewer_keywords: ["C3508"] -ms.assetid: 16d08f89-2f32-44eb-9421-68acecddf49b --- # Compiler Error C3508 -'type': is not a valid Automation type +> 'type': is not a valid Automation type + +## Remarks An invalid type was specified. ## Example -The following sample generates C3508: +The following example generates C3508: ```cpp // C3508.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3509.md b/docs/error-messages/compiler-errors-2/compiler-error-c3509.md index 2b68307157e..4504363ff30 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3509.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3509.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3509" title: "Compiler Error C3509" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3509" +ms.date: 11/04/2016 f1_keywords: ["C3509"] helpviewer_keywords: ["C3509"] -ms.assetid: cc2db39a-2f98-4e40-b803-496e585494e6 --- # Compiler Error C3509 -'type': invalid Automation return type; when a parameter is marked 'retval', the return type must be 'void', 'HRESULT' or 'SCODE' +> 'type': invalid Automation return type; when a parameter is marked 'retval', the return type must be 'void', 'HRESULT' or 'SCODE' + +## Remarks A method in a COM interface must return either void or an HRESULT. -The following sample generates C3509: +## Example + +The following example generates C3509: ```cpp // C3509.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3510.md b/docs/error-messages/compiler-errors-2/compiler-error-c3510.md index 7149143be10..c992a78b251 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3510.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3510.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3510" title: "Compiler Error C3510" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3510" +ms.date: 11/04/2016 f1_keywords: ["C3510"] helpviewer_keywords: ["C3510"] -ms.assetid: c48387bc-0300-4a4d-97f7-3fb90f82a451 --- # Compiler Error C3510 -cannot locate dependent type library 'type_lib' +> cannot locate dependent type library 'type_lib' + +## Remarks [no_registry](../../preprocessor/no-registry.md) and [auto_search](../../preprocessor/auto-search.md) were passed to `#import` but the compiler was not able to find a referenced type library. To resolve this error, make sure that all type libraries and referenced type libraries are available to the compiler. -The following sample generates C3510: +## Example + +The following example generates C3510: Assume that the following two type libraries were built, and that C3510a.tlb was deleted or not on the path. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3519.md b/docs/error-messages/compiler-errors-2/compiler-error-c3519.md index af93d7018e6..94e81b7cdbd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3519.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3519.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3519" title: "Compiler Error C3519" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3519" +ms.date: 11/04/2016 f1_keywords: ["C3519"] helpviewer_keywords: ["C3519"] -ms.assetid: ca24b2bc-7e90-4448-ae84-3fedddf9bca7 --- # Compiler Error C3519 -'invalid_param' : invalid parameter to embedded_idl attribute +> 'invalid_param' : invalid parameter to embedded_idl attribute + +## Remarks A parameter was passed to the `embedded_idl` attribute of [#import](../../preprocessor/hash-import-directive-cpp.md), but the compiler did not recognize the parameter. The only parameters that are allowed for `embedded_idl` are `emitidl` and `no_emitidl`. -The following sample generates C3519: +## Example + +The following example generates C3519: ```cpp // C3519.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3530.md b/docs/error-messages/compiler-errors-2/compiler-error-c3530.md index 9a1a7467a25..bc8713e3bd4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3530.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3530.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3530" title: "Compiler Error C3530" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3530" +ms.date: 11/04/2016 f1_keywords: ["C3530"] helpviewer_keywords: ["C3530"] -ms.assetid: 21be81ce-b699-4c74-81bc-80a0c34d2d5a --- # Compiler Error C3530 -'auto' cannot be combined with any other type-specifier +> 'auto' cannot be combined with any other type-specifier + +## Remarks A type specifier is used with the **`auto`** keyword. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3531.md b/docs/error-messages/compiler-errors-2/compiler-error-c3531.md index 5881579fcb1..af8e3c7faad 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3531.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3531.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3531" title: "Compiler Error C3531" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3531" +ms.date: 11/04/2016 f1_keywords: ["C3531"] helpviewer_keywords: ["C3531"] -ms.assetid: 2bdb9fdc-9ddf-403e-8b92-02763d434487 --- # Compiler Error C3531 -'symbol': a symbol whose type contains 'auto' must have an initializer +> 'symbol': a symbol whose type contains 'auto' must have an initializer + +## Remarks The specified variable does not have an initializer expression. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3532.md b/docs/error-messages/compiler-errors-2/compiler-error-c3532.md index ab9dd8b31e9..ae31df7e246 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3532.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3532.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3532" title: "Compiler Error C3532" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3532" +ms.date: 11/04/2016 f1_keywords: ["C3532"] helpviewer_keywords: ["C3532"] -ms.assetid: 51067853-eda8-4f59-86e8-8924e16d3a95 --- # Compiler Error C3532 -'type': incorrect usage of 'auto' +> 'type': incorrect usage of 'auto' + +## Remarks The indicated type cannot be declared with the **`auto`** keyword. For example, you cannot use the **`auto`** keyword to declare an array or a method return type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3533.md b/docs/error-messages/compiler-errors-2/compiler-error-c3533.md index eea7dbe64db..0b56398b7bd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3533.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3533.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3533" title: "Compiler Error C3533" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3533" +ms.date: 11/04/2016 f1_keywords: ["C3533"] helpviewer_keywords: ["C3533"] -ms.assetid: a68b1ba5-466e-4190-a1a4-505ccfe548b7 --- # Compiler Error C3533 -'type': a parameter cannot have a type that contains 'auto' +> 'type': a parameter cannot have a type that contains 'auto' + +## Remarks A method or template parameter cannot be declared with the **`auto`** keyword if the default [/Zc:auto](../../build/reference/zc-auto-deduce-variable-type.md) compiler option is in effect. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3535.md b/docs/error-messages/compiler-errors-2/compiler-error-c3535.md index 05d22de8d0a..7ea0627d720 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3535.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3535.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3535" title: "Compiler Error C3535" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3535" +ms.date: 11/04/2016 f1_keywords: ["C3535"] helpviewer_keywords: ["C3535"] -ms.assetid: 24449c98-f681-484d-a00b-32533dca3a88 --- # Compiler Error C3535 -cannot deduce type for 'type1' from 'type2' +> cannot deduce type for 'type1' from 'type2' + +## Remarks The type of the variable declared by the **`auto`** keyword cannot be deduced from the type of the initialization expression. For example, this error occurs if the initialization expression evaluates to **`void`**, which is not a type. 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 1701d26b5ab..cb8018a28dc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3536.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3536.md @@ -1,14 +1,15 @@ --- -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 -'symbol': cannot be used before it is initialized +> 'symbol': cannot be used before it is initialized + +## Remarks The indicated symbol cannot be used before it is initialized. In practice, this means that a variable cannot be used to initialize itself. @@ -31,7 +32,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-c3537.md b/docs/error-messages/compiler-errors-2/compiler-error-c3537.md index d7562baaf89..1daeb6d5e7a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3537.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3537.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3537" title: "Compiler Error C3537" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3537" +ms.date: 11/04/2016 f1_keywords: ["C3537"] helpviewer_keywords: ["C3537"] -ms.assetid: f537ebd1-4fb0-4e09-a453-4f38db2c6881 --- # Compiler Error C3537 -'type': you cannot cast to a type that contains 'auto' +> 'type': you cannot cast to a type that contains 'auto' + +## Remarks You cannot cast a variable to the indicated type because the type contains the **`auto`** keyword and the default [/Zc:auto](../../build/reference/zc-auto-deduce-variable-type.md) compiler option is in effect. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3538.md b/docs/error-messages/compiler-errors-2/compiler-error-c3538.md index 3f503e35509..58df9218dba 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3538.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3538.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3538" title: "Compiler Error C3538" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3538" +ms.date: 11/04/2016 f1_keywords: ["C3538"] helpviewer_keywords: ["C3538"] -ms.assetid: ef3698a5-7356-4c62-b9af-5d3a4baed958 --- # Compiler Error C3538 -in a declarator-list 'auto' must always deduce to the same type +> in a declarator-list 'auto' must always deduce to the same type + +## Remarks All the declared variables in a declaration list do not resolve to the same type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3539.md b/docs/error-messages/compiler-errors-2/compiler-error-c3539.md index c7235b2ddd4..2ace0616df1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3539.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3539.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3539" title: "Compiler Error C3539" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3539" +ms.date: 11/04/2016 f1_keywords: ["C3539"] helpviewer_keywords: ["C3539"] -ms.assetid: 34a33a0f-d1b6-498f-b312-ffad2d4799b3 --- # Compiler Error C3539 -'type': a template-argument cannot be a type that contains 'auto' +> 'type': a template-argument cannot be a type that contains 'auto' + +## Remarks The indicated template argument type cannot contain a usage of the **`auto`** keyword. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3540.md b/docs/error-messages/compiler-errors-2/compiler-error-c3540.md index 38339db5a72..b1688781639 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3540.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3540.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3540" title: "Compiler Error C3540" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3540" +ms.date: 11/04/2016 f1_keywords: ["C3540"] helpviewer_keywords: ["C3540"] -ms.assetid: 3c0c959c-e3b7-40eb-b922-ccac44bd9d85 --- # Compiler Error C3540 -'type': sizeof cannot be applied to a type that contains 'auto' +> 'type': sizeof cannot be applied to a type that contains 'auto' + +## Remarks The [sizeof](../../cpp/sizeof-operator.md) operator cannot be applied to the indicated type because it contains the **`auto`** specifier. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3541.md b/docs/error-messages/compiler-errors-2/compiler-error-c3541.md index 10701262c51..c29ca9eebf6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3541.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3541.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3541" title: "Compiler Error C3541" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3541" +ms.date: 11/04/2016 f1_keywords: ["C3541"] helpviewer_keywords: ["C3541"] -ms.assetid: 252cfd4c-5fd2-415e-a17d-6b0c254350db --- # Compiler Error C3541 -'type': typeid cannot be applied to a type that contains 'auto' +> 'type': typeid cannot be applied to a type that contains 'auto' + +## Remarks The [typeid](../../extensions/typeid-cpp-component-extensions.md) operator cannot be applied to the indicated type because it contains the **`auto`** specifier. 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 abecd370eee..c77d30507be 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3550.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3550.md @@ -1,16 +1,33 @@ --- -description: "Learn more about: Compiler Error C3550" title: "Compiler Error C3550" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3550" +ms.date: 11/04/2016 f1_keywords: ["C3550"] helpviewer_keywords: ["C3550"] -ms.assetid: 9f2d5ffc-e429-41a1-89e3-7acc4fd47e14 --- # Compiler Error C3550 -only plain 'decltype(auto)' is allowed in this context +> only plain 'decltype(auto)' is allowed in this context + +## Remarks + +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 example generates C3550: + +```cpp +// C3550.cpp +// compile with: /c +decltype(auto)* func1(); // C3550 +decltype(auto)& func2(); // C3550 +decltype(auto)&& func3(); // C3550 + +auto* func4(); // OK +``` -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. +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 1220d333bff..5496151097d 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,30 @@ --- -description: "Learn more about: Compiler Error C3551" title: "Compiler Error C3551" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3551" +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`**. +## Remarks -``` -auto myFunction()->int(*)[4]; -``` +The leading return type in [trailing return type](../../cpp/functions-cpp.md#trailing-return-types) syntax must contain only `auto`. -## See also +## Example -[auto](../../cpp/auto-cpp.md) +The following example generates C3551: + +```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 + +auto func6() -> int; // OK +``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3552.md b/docs/error-messages/compiler-errors-2/compiler-error-c3552.md index 6d6c214ea1c..157c8b64b31 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3552.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3552.md @@ -1,15 +1,20 @@ --- -description: "Learn more about: Compiler Error C3552" title: "Compiler Error C3552" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3552" +ms.date: 11/04/2016 f1_keywords: ["C3552"] helpviewer_keywords: ["C3552"] -ms.assetid: 83401524-1bf1-44c0-8aca-a6eb35c4224c --- # Compiler Error C3552 -'typename': a late specified return type cannot contain 'auto' +> 'typename': a late specified return type cannot contain 'auto' + +## Remarks + +If you use the **`auto`** keyword as a placeholder for the return type of a function, you must provide a late-specified return type. However, you cannot use another **`auto`** keyword to specify the late-specified return type. + +## Example -If you use the **`auto`** keyword as a placeholder for the return type of a function, you must provide a late-specified return type. However, you cannot use another **`auto`** keyword to specify the late-specified return type. For example, the following code fragment yields error C3552. +For example, the following code fragment yields error C3552. `auto myFunction->auto; // C3552` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3553.md b/docs/error-messages/compiler-errors-2/compiler-error-c3553.md index aa032de7ddc..ad12e1f1f4c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3553.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3553.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Error C3553" title: "Compiler Error C3553" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3553" +ms.date: 11/04/2016 f1_keywords: ["C3553"] helpviewer_keywords: ["C3553"] -ms.assetid: 7f84bf37-6419-4ad3-ab30-64266100b930 --- # Compiler Error C3553 > decltype expects an expression not a type -The `decltype()` keyword requires an expression as an argument, not the name of a type. For example, the last statement in the following code fragment yields error C3553. +## Remarks + +The `decltype()` keyword requires an expression as an argument, not the name of a type. + +## Example + +For example, the last statement in the following code fragment yields error C3553. ```cpp int x = 0; diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3554.md b/docs/error-messages/compiler-errors-2/compiler-error-c3554.md index bb36c2a954d..d05cfaf3689 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3554.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3554.md @@ -1,18 +1,23 @@ --- -description: "Learn more about: Compiler Error C3554" title: "Compiler Error C3554" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3554" +ms.date: 11/04/2016 f1_keywords: ["C3554"] helpviewer_keywords: ["C3554"] -ms.assetid: aede18d5-fefc-4da9-9b69-adfe90bfa742 --- # Compiler Error C3554 -'decltype' cannot be combined with any other type-specifier +> 'decltype' cannot be combined with any other type-specifier -You cannot qualify the `decltype()` keyword with any type specifier. For example, the following code fragment yields error C3554. +## Remarks -``` +You cannot qualify the `decltype()` keyword with any type specifier. + +## Example + +For example, the following code fragment yields error C3554. + +```cpp int x; unsigned decltype(x); // C3554 ``` diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3555.md b/docs/error-messages/compiler-errors-2/compiler-error-c3555.md index 20d3a809439..3f716381455 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3555.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3555.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3555" title: "Compiler Error C3555" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3555" +ms.date: 11/04/2016 f1_keywords: ["C3555"] helpviewer_keywords: ["C3555"] -ms.assetid: b4311bd3-851b-479a-9965-d03f39dd8fd4 --- # Compiler Error C3555 > incorrect argument to 'decltype' +## Remarks + The argument to the `decltype(`*expression*`)` type specifier is not a valid expression. > [!NOTE] diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3556.md b/docs/error-messages/compiler-errors-2/compiler-error-c3556.md index d6f25c1171d..dbfbe198704 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3556.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3556.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3556" title: "Compiler Error C3556" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3556" +ms.date: 11/04/2016 f1_keywords: ["C3556"] helpviewer_keywords: ["C3556"] -ms.assetid: 9b002dcc-494e-414f-9587-20c2a0a39333 --- # Compiler Error C3556 > '*expression*': incorrect argument to 'decltype' +## Remarks + The compiler cannot deduce the type of the expression that is the argument to the `decltype(`*expression*`)` type specifier. ## Example diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3603.md b/docs/error-messages/compiler-errors-2/compiler-error-c3603.md index 7e37da6a646..d3e6f9a8806 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3603.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3603.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3603" title: "Compiler Error C3603" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3603" +ms.date: 11/04/2016 f1_keywords: ["C3603"] helpviewer_keywords: ["C3603"] -ms.assetid: d0cdc7d3-f25a-4242-9ee8-51fe044a9959 --- # Compiler Error C3603 -'Symbol' : type 'Type' not yet supported +> 'Symbol' : type 'Type' not yet supported + +## Remarks You attempted to use a data type that is not yet supported by the .NET runtime in a managed object. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3609.md b/docs/error-messages/compiler-errors-2/compiler-error-c3609.md index b667614aedd..e0a7eca6c11 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3609.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3609.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3609" title: "Compiler Error C3609" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3609" +ms.date: 11/04/2016 f1_keywords: ["C3609"] helpviewer_keywords: ["C3609"] -ms.assetid: 801e7f79-4ac6-4f8f-955f-703cdf095d00 --- # Compiler Error C3609 -'member': a sealed or final function must be virtual +> 'member': a sealed or final function must be virtual + +## Remarks The [sealed](../../extensions/sealed-cpp-component-extensions.md) and [final](../../cpp/final-specifier.md) keywords are only allowed on a class, struct, or member function marked **`virtual`**. -The following sample generates C3609: +## Example + +The following example generates C3609: ```cpp // C3609.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3610.md b/docs/error-messages/compiler-errors-2/compiler-error-c3610.md index 81720af72c7..8d7ddb5eeda 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3610.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3610.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3610" title: "Compiler Error C3610" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3610" +ms.date: 11/04/2016 f1_keywords: ["C3610"] helpviewer_keywords: ["C3610"] -ms.assetid: 9349a348-9d37-4a00-9eab-481039268d31 --- # Compiler Error C3610 -'valuetype': value type must be 'boxed' before method 'method' can be called +> 'valuetype': value type must be 'boxed' before method 'method' can be called + +## Remarks By default, a value type is not on the managed heap. Before you can call methods from .NET runtime classes, such as `Object`, you need to move the value type to the managed heap. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3611.md b/docs/error-messages/compiler-errors-2/compiler-error-c3611.md index 53a3ecfdb1d..985c54d27e6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3611.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3611.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3611" title: "Compiler Error C3611" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3611" +ms.date: 11/04/2016 f1_keywords: ["C3611"] helpviewer_keywords: ["C3611"] -ms.assetid: 42f3e320-41de-420a-bd05-8924cab765aa --- # Compiler Error C3611 -'function': a sealed function cannot have a pure-specifier +> 'function': a sealed function cannot have a pure-specifier + +## Remarks A sealed function was declared incorrectly. For more information, see [sealed](../../extensions/sealed-cpp-component-extensions.md). ## Example -The following sample generates C3611. +The following example generates C3611. ```cpp // C3611.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3612.md b/docs/error-messages/compiler-errors-2/compiler-error-c3612.md index 133fdce7452..f8b2ed8dc3e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3612.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3612.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3612" title: "Compiler Error C3612" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3612" +ms.date: 11/04/2016 f1_keywords: ["C3612"] helpviewer_keywords: ["C3612"] -ms.assetid: aa6e3a2b-4afa-481c-98c1-1b6d1f82f869 --- # Compiler Error C3612 -'type': a sealed class cannot be abstract +> 'type': a sealed class cannot be abstract + +## Remarks Types defined by using `value` are sealed by default, and a class is abstract unless it implements all methods of its base. A sealed abstract class can neither be a base class nor can it be instantiated. @@ -16,7 +17,7 @@ For more information, see [Classes and Structs](../../extensions/classes-and-str ## Example -The following sample generates C3612: +The following example generates C3612: ```cpp // C3612.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3615.md b/docs/error-messages/compiler-errors-2/compiler-error-c3615.md index a66992f97d8..43d833dbcec 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3615.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3615.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Error C3615" title: "Compiler Error C3615" -ms.date: "10/24/2017" +description: "Learn more about: Compiler Error C3615" +ms.date: 10/24/2017 f1_keywords: ["C3615"] helpviewer_keywords: ["C3615"] -ms.assetid: 5ce96ba9-3d31-49f3-9aa8-24e5cdf6dcfc --- # Compiler Error C3615 > constexpr function '*function*' cannot result in a constant expression +## Remarks + The function *function* could not be evaluated as **`constexpr`** at compile time. To be **`constexpr`**, a function can only call other **`constexpr`** functions. ## Example diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3618.md b/docs/error-messages/compiler-errors-2/compiler-error-c3618.md index facaf056dbb..0ee128a4473 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3618.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3618.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3618" title: "Compiler Error C3618" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3618" +ms.date: 11/04/2016 f1_keywords: ["C3618"] helpviewer_keywords: ["C3618"] -ms.assetid: cacc105d-4389-4cb8-ae6c-41a3622e9a86 --- # Compiler Error C3618 -'function': a method marked DllImport cannot be defined +> 'function': a method marked DllImport cannot be defined + +## Remarks A method marked with is defined in the specified.DLL. ## Example -The following sample generates C3618. +The following example generates C3618. ```cpp // C3618.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3619.md b/docs/error-messages/compiler-errors-2/compiler-error-c3619.md index 6867cad9b73..53c17536203 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3619.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3619.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3619" title: "Compiler Error C3619" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3619" +ms.date: 11/04/2016 f1_keywords: ["C3619"] helpviewer_keywords: ["C3619"] -ms.assetid: 76ae80d0-9fbe-4297-a1ef-b1503377fdcf --- # Compiler Error C3619 -a template cannot be declared within a managed or WinRT type +> a template cannot be declared within a managed or WinRT type + +## Remarks Class templates are not allowed in a managed or WinRT class or interface. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3622.md b/docs/error-messages/compiler-errors-2/compiler-error-c3622.md index 7301a8b96aa..60241213166 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3622.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3622.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3622" title: "Compiler Error C3622" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3622" +ms.date: 11/04/2016 f1_keywords: ["C3622"] helpviewer_keywords: ["C3622"] -ms.assetid: 02836f78-0cf2-4947-b87e-710187d81014 --- # Compiler Error C3622 -'class' : a class declared as 'keyword' cannot be instantiated +> 'class' : a class declared as 'keyword' cannot be instantiated + +## Remarks An attempt was made to instantiate a class marked as [abstract](../../extensions/abstract-cpp-component-extensions.md). A class marked as **`abstract`** can be a base class, but it cannot be instantiated. ## Example -The following sample generates C3622. +The following example generates C3622. ```cpp // C3622.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3623.md b/docs/error-messages/compiler-errors-2/compiler-error-c3623.md index 07627ca798e..f19e798bd68 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3623.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3623.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3623" title: "Compiler Error C3623" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3623" +ms.date: 11/04/2016 f1_keywords: ["C3623"] helpviewer_keywords: ["C3623"] -ms.assetid: a0341b45-062a-4f67-beb9-ba74201ed1ed --- # Compiler Error C3623 -'variable': bit fields are not supported in managed or WinRT types +> 'variable': bit fields are not supported in managed or WinRT types + +## Remarks The use of bit fields is not permitted on variables in a managed or WinRT class. -The following sample generates C3623: +## Example + +The following example generates C3623: ```cpp // C3623.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3624.md b/docs/error-messages/compiler-errors-2/compiler-error-c3624.md index 8a9eba82beb..81196f32bb3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3624.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3624.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3624" title: "Compiler Error C3624" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3624" +ms.date: 11/04/2016 f1_keywords: ["C3624"] helpviewer_keywords: ["C3624"] -ms.assetid: eaac6a4f-eb11-4e4d-ab12-124ba995c5cf --- # Compiler Error C3624 -'type': use of this type requires a reference to assembly 'assembly' +> 'type': use of this type requires a reference to assembly 'assembly' + +## Remarks An assembly (reference) needed to compile your code was not specified; pass the assembly to the [#using](../../preprocessor/hash-using-directive-cpp.md) directive. ## Example -The following sample generates C3624: +The following example generates C3624: ```cpp // C3624.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3625.md b/docs/error-messages/compiler-errors-2/compiler-error-c3625.md index eed0c1f02bf..46ae1ba8349 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3625.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3625.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3625" title: "Compiler Error C3625" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3625" +ms.date: 11/04/2016 f1_keywords: ["C3625"] helpviewer_keywords: ["C3625"] -ms.assetid: fdf49f21-d6b1-42f4-9eec-23b04ae8b4aa --- # Compiler Error C3625 -'native_type': a native type cannot derive from a managed or WinRT type 'type' +> 'native_type': a native type cannot derive from a managed or WinRT type 'type' + +## Remarks A native class cannot inherit from a managed or WinRT class. For more information, see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md). ## Example -The following sample generates C3625: +The following example generates C3625: ```cpp // C3625.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3626.md b/docs/error-messages/compiler-errors-2/compiler-error-c3626.md index dd04cfe1a42..b28d6ad76c1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3626.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3626.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3626" title: "Compiler Error C3626" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3626" +ms.date: 11/04/2016 f1_keywords: ["C3626"] helpviewer_keywords: ["C3626"] -ms.assetid: 43926e2b-1ba9-4a43-9343-c58449cbb336 --- # Compiler Error C3626 -'keyword': '__event' keyword can only be used on COM interfaces, member functions and data members that are pointers to delegates +> 'keyword': '__event' keyword can only be used on COM interfaces, member functions and data members that are pointers to delegates + +## Remarks A keyword was used incorrectly. -The following sample generates C3626: +## Example + +The following example generates C3626: ```cpp // C3626.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3627.md b/docs/error-messages/compiler-errors-2/compiler-error-c3627.md index cddb376d1bb..1512ff7a55f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3627.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3627.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3627" title: "Compiler Error C3627" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3627" +ms.date: 11/04/2016 f1_keywords: ["C3627"] helpviewer_keywords: ["C3627"] -ms.assetid: 905ad0a0-8c49-4187-b66e-b375f5a1fae5 --- # Compiler Error C3627 -Only a value type can be boxed +> Only a value type can be boxed + +## Remarks Only value classes can be boxed. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3628.md b/docs/error-messages/compiler-errors-2/compiler-error-c3628.md index cd3c08937af..9ee013b88bc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3628.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3628.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3628" title: "Compiler Error C3628" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3628" +ms.date: 11/04/2016 f1_keywords: ["C3628"] helpviewer_keywords: ["C3628"] -ms.assetid: 0ff5a4a4-fcc9-47a0-a4d8-8af9cf2815f6 --- # Compiler Error C3628 -'base class' : managed or WinRTclasses only support public inheritance +> 'base class' : managed or WinRTclasses only support public inheritance + +## Remarks An attempt was made to use a managed or WinRT class as a [private](../../cpp/private-cpp.md) or [protected](../../cpp/protected-cpp.md) base class. A managed or WinRT class can only be used as a base class with [public](../../cpp/public-cpp.md) access. -The following sample generates C3628 and shows how to fix it: +## Example + +The following example generates C3628 and shows how to fix it: ```cpp // C3628a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3630.md b/docs/error-messages/compiler-errors-2/compiler-error-c3630.md index d5fd6878985..26adba75358 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3630.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3630.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3630" title: "Compiler Error C3630" +description: "Learn more about: Compiler Error C3630" ms.date: 05/25/2022 f1_keywords: ["C3630"] helpviewer_keywords: ["C3630"] -ms.assetid: 865626a9-98cc-465d-acde-44d4574c019a --- # Compiler Error C3630 > error when processing the token '*token*' +## Remarks + A token in source code couldn't be processed. This error is obsolete in Visual Studio 2022. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3631.md b/docs/error-messages/compiler-errors-2/compiler-error-c3631.md index 202b12ae211..2feb0d3e348 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3631.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3631.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3631" title: "Compiler Error C3631" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3631" +ms.date: 11/04/2016 f1_keywords: ["C3631"] helpviewer_keywords: ["C3631"] -ms.assetid: 88cbd2d5-6fef-4940-be34-d8cbe816d3da --- # Compiler Error C3631 -'function': cannot overload managed or WinRT events +> 'function': cannot overload managed or WinRT events + +## Remarks A managed or WinRT event cannot be overloaded. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3632.md b/docs/error-messages/compiler-errors-2/compiler-error-c3632.md index c9151e571fa..337489011a3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3632.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3632.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3632" title: "Compiler Error C3632" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3632" +ms.date: 11/04/2016 f1_keywords: ["C3632"] helpviewer_keywords: ["C3632"] -ms.assetid: a04e3217-f5a1-4461-a1db-d69fd096d468 --- # Compiler Error C3632 -'event': illegal style of event for construct +> 'event': illegal style of event for construct + +## Remarks [__event](../../cpp/event.md) declarations are not valid in all constructs. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3633.md b/docs/error-messages/compiler-errors-2/compiler-error-c3633.md index fb0ba09ac2e..acefca20c78 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3633.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3633.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3633" title: "Compiler Error C3633" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3633" +ms.date: 11/04/2016 f1_keywords: ["C3633"] helpviewer_keywords: ["C3633"] -ms.assetid: 7d65babf-2191-4d67-a69f-f5c4c2ddf946 --- # Compiler Error C3633 -cannot define 'member' as a member of managed 'type' +> cannot define 'member' as a member of managed 'type' + +## Remarks CLR reference class data members cannot be of a non-POD C++ type. You can only instantiate a POD native type in a CLR type. For example, a POD type cannot contain a copy constructor or an assignment operator. ## Example -The following sample generates C3633. +The following example generates C3633. ```cpp // C3633.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3634.md b/docs/error-messages/compiler-errors-2/compiler-error-c3634.md index 390f9d9b044..5a003e3be6d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3634.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3634.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3634" title: "Compiler Error C3634" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3634" +ms.date: 11/04/2016 f1_keywords: ["C3634"] helpviewer_keywords: ["C3634"] -ms.assetid: fd09f10c-f863-483b-9756-71c16b760b02 --- # Compiler Error C3634 -'function' : cannot define an abstract method of a managed or WinRTclass +> 'function' : cannot define an abstract method of a managed or WinRTclass + +## Remarks An abstract method can be declared in a managed or WinRT class, but it cannot be defined. ## Example -The following sample generates C3634: +The following example generates C3634: ```cpp // C3634.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3637.md b/docs/error-messages/compiler-errors-2/compiler-error-c3637.md index b49fbc33968..0ff30315570 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3637.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3637.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3637" title: "Compiler Error C3637" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3637" +ms.date: 11/04/2016 f1_keywords: ["C3637"] helpviewer_keywords: ["C3637"] -ms.assetid: 72391377-8519-43d9-870a-73a6423deb74 --- # Compiler Error C3637 -'function' : a friend function definition cannot be a specialization of a function type +> 'function' : a friend function definition cannot be a specialization of a function type + +## Remarks A friend function was defined incorrectly for a template or generic. -The following sample generates C3637: +## Examples + +The following example generates C3637: ```cpp // C3637.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3638.md b/docs/error-messages/compiler-errors-2/compiler-error-c3638.md index 2fcff4c27d4..0f0c2e3c61a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3638.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3638.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3638" title: "Compiler Error C3638" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3638" +ms.date: 11/04/2016 f1_keywords: ["C3638"] helpviewer_keywords: ["C3638"] -ms.assetid: 8d8bc5ca-75aa-480e-b6b6-3178fab51b1d --- # Compiler Error C3638 -'operator' : the standard boxing and unboxing conversion operators cannot be redefined +> 'operator' : the standard boxing and unboxing conversion operators cannot be redefined + +## Remarks The compiler defines a conversion operator for each managed class to support implicit boxing. This operator cannot be redefined. For more information, see [Implicit Boxing](../../extensions/boxing-cpp-component-extensions.md). -The following sample generates C3638: +## Example + +The following example generates C3638: ```cpp // C3638.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3640.md b/docs/error-messages/compiler-errors-2/compiler-error-c3640.md index 88cd60658d6..dae63059c1e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3640.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3640.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3640" title: "Compiler Error C3640" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3640" +ms.date: 11/04/2016 f1_keywords: ["C3640"] helpviewer_keywords: ["C3640"] -ms.assetid: fcc56894-0f98-48af-8561-3bf7c7b2b93f --- # Compiler Error C3640 -'member' : a referenced or virtual member function of a local class must be defined +> 'member' : a referenced or virtual member function of a local class must be defined + +## Remarks The compiler requires certain functions to be defined. -The following sample generates C3640: +## Example + +The following example generates C3640: ```cpp // C3640.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3641.md b/docs/error-messages/compiler-errors-2/compiler-error-c3641.md index fbca71d1025..46835413dba 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3641.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3641.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3641" title: "Compiler Error C3641" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3641" +ms.date: 11/04/2016 f1_keywords: ["C3641"] helpviewer_keywords: ["C3641"] -ms.assetid: e8d3613e-5e8d-46fe-a516-eb7d1de7cd21 --- # Compiler Error C3641 @@ -18,7 +17,7 @@ Only [__clrcall](../../cpp/clrcall.md) calling convention is allowed with [/clr: ## Example -The following sample generates C3641: +The following example generates C3641: ```cpp // C3641.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3642.md b/docs/error-messages/compiler-errors-2/compiler-error-c3642.md index 6408f3f41d4..9ad9ca91d3e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3642.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3642.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3642" title: "Compiler Error C3642" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3642" +ms.date: 11/04/2016 f1_keywords: ["C3642"] helpviewer_keywords: ["C3642"] -ms.assetid: 429790c2-9614-4d85-b31c-687c8d8f83ff --- # Compiler Error C3642 -'return_type/args' : cannot call a function with __clrcall calling convention from native code +> 'return_type/args' : cannot call a function with __clrcall calling convention from native code + +## Remarks A function that is marked with the [__clrcall](../../cpp/clrcall.md) calling convention cannot be called from native (unmanaged) code. @@ -16,7 +17,9 @@ A function that is marked with the [__clrcall](../../cpp/clrcall.md) calling con To call a managed function from a native context, you can add a "wrapper" function that will call the `__clrcall` function. Or, you can use the CLR marshalling mechanism; see [How to: Marshal Function Pointers Using PInvoke](../../dotnet/how-to-marshal-function-pointers-using-pinvoke.md) for more information. -The following sample generates C3642: +## Example + +The following example generates C3642: ```cpp // C3642.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3644.md b/docs/error-messages/compiler-errors-2/compiler-error-c3644.md index 1798239f263..78613404658 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3644.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3644.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3644" title: "Compiler Error C3644" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3644" +ms.date: 11/04/2016 f1_keywords: ["C3644"] helpviewer_keywords: ["C3644"] -ms.assetid: 2e3f6c41-3ec5-4a01-82bc-f11b61ebe68e --- # Compiler Error C3644 -'function' : cannot compile the function to generate managed code +> 'function' : cannot compile the function to generate managed code + +## Remarks The presence of some keywords in a function will cause the function to be compiled to native. -The following sample generates C3644: +## Example + +The following example generates C3644: ```cpp // C3644.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3645.md b/docs/error-messages/compiler-errors-2/compiler-error-c3645.md index b58af9dcfdb..4667e877425 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3645.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3645.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3645" title: "Compiler Error C3645" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3645" +ms.date: 11/04/2016 f1_keywords: ["C3645"] helpviewer_keywords: ["C3645"] -ms.assetid: 346da528-ae86-4cd0-9654-f41bee26ac0d --- # Compiler Error C3645 -'function' : __clrcall cannot be used on functions compiled to native code +> 'function' : __clrcall cannot be used on functions compiled to native code + +## Remarks The presence of some keywords in a function will cause the function to be compiled to native. ## Example -The following sample generates C3645. +The following example generates C3645. ```cpp // C3645.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3646.md b/docs/error-messages/compiler-errors-2/compiler-error-c3646.md index 21c1177f7d6..330b23f3339 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3646.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3646.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3646" title: "Compiler Error C3646" -ms.date: "06/14/2018" +description: "Learn more about: Compiler Error C3646" +ms.date: 06/14/2018 f1_keywords: ["C3646"] helpviewer_keywords: ["C3646"] -ms.assetid: 4391ead2-9637-4ca3-aeda-5a991b18d66d --- # Compiler Error C3646 @@ -20,7 +19,7 @@ For more information, see [Override Specifiers](../../extensions/override-specif ## Example -The following sample generates C3646 and shows a way to fix it: +The following example generates C3646 and shows a way to fix it: ```cpp // C3646.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3648.md b/docs/error-messages/compiler-errors-2/compiler-error-c3648.md index 273693bbe46..0eacdf8cfcf 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3648.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3648.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3648" title: "Compiler Error C3648" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3648" +ms.date: 11/04/2016 f1_keywords: ["C3648"] helpviewer_keywords: ["C3648"] -ms.assetid: 5d042989-41cb-4cd0-aa50-976b70146aaf --- # Compiler Error C3648 -this explicit override syntax requires /clr:oldSyntax +> this explicit override syntax requires /clr:oldSyntax + +## Remarks When compiling for the latest managed syntax, the compiler found explicit override syntax for previous versions that is no longer supported. @@ -16,7 +17,7 @@ For more information, see [Explicit Overrides](../../extensions/explicit-overrid ## Example -The following sample generates C3648: +The following example generates C3648: ```cpp // C3648.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3650.md b/docs/error-messages/compiler-errors-2/compiler-error-c3650.md index e77e5ac394f..7687b504002 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3650.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3650.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3650" title: "Compiler Error C3650" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3650" +ms.date: 11/04/2016 f1_keywords: ["C3650"] helpviewer_keywords: ["C3650"] -ms.assetid: ca4d8de4-b027-4d13-9b9f-03ca62905c33 --- # Compiler Error C3650 -'interface_method' : cannot be used as an explicit override, must be a virtual member function of a base class +> 'interface_method' : cannot be used as an explicit override, must be a virtual member function of a base class + +## Remarks An attempt was made to perform an explicit override on a member that was not virtual. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3650: +## Example + +The following example generates C3650: ```cpp // C3650.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3651.md b/docs/error-messages/compiler-errors-2/compiler-error-c3651.md index f50b6090be8..05a811b6625 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3651.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3651.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3651" title: "Compiler Error C3651" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3651" +ms.date: 11/04/2016 f1_keywords: ["C3651"] helpviewer_keywords: ["C3651"] -ms.assetid: a03e692e-c219-4654-9827-8415cfa5a22d --- # Compiler Error C3651 -'member' : cannot be used as an explicit override, must be a member of a base class +> 'member' : cannot be used as an explicit override, must be a member of a base class + +## Remarks An explicit override was specified, but the function being overridden was in a type that is not a base type. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3651: +## Example + +The following example generates C3651: ```cpp // C3651.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3652.md b/docs/error-messages/compiler-errors-2/compiler-error-c3652.md index 81541733938..d4cff5ba850 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3652.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3652.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3652" title: "Compiler Error C3652" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3652" +ms.date: 11/04/2016 f1_keywords: ["C3652"] helpviewer_keywords: ["C3652"] -ms.assetid: 15d68737-177e-41f1-80e0-7c3e2afdf0fc --- # Compiler Error C3652 -'override' : a function that explicitly overrides must be virtual +> 'override' : a function that explicitly overrides must be virtual + +## Remarks A function that does an explicit override must be virtual. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3652: +## Example + +The following example generates C3652: ```cpp // C3652.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3653.md b/docs/error-messages/compiler-errors-2/compiler-error-c3653.md index 4f6aeb2eeca..0dff663b5c9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3653.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3653.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3653" title: "Compiler Error C3653" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3653" +ms.date: 11/04/2016 f1_keywords: ["C3653"] helpviewer_keywords: ["C3653"] -ms.assetid: 316549d7-f7ef-4578-a2ba-57adc8aac527 --- # Compiler Error C3653 -'function' : cannot be used as a named override: a function being overridden not found; did you forget to name the function explicitly, using a :: operator? +> 'function' : cannot be used as a named override: a function being overridden not found; did you forget to name the function explicitly, using a :: operator? + +## Remarks An explicit override specified a function that was not found in any interface. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3653: +## Example + +The following example generates C3653: ```cpp // C3653.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3654.md b/docs/error-messages/compiler-errors-2/compiler-error-c3654.md index 593ca9bd654..f3cb4716ef2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3654.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3654.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3654" title: "Compiler Error C3654" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3654" +ms.date: 11/04/2016 f1_keywords: ["C3654"] helpviewer_keywords: ["C3654"] -ms.assetid: 57d96e3f-6bbb-4eaa-934b-26c23b4ceb2e --- # Compiler Error C3654 -'text' : syntax error in explicit override +> 'text' : syntax error in explicit override + +## Remarks An unexpected string was in an explicit override. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3654: +## Example + +The following example generates C3654: ```cpp // C3654.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3655.md b/docs/error-messages/compiler-errors-2/compiler-error-c3655.md index e2b51a05bb3..cca99c6c609 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3655.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3655.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3655" title: "Compiler Error C3655" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3655" +ms.date: 11/04/2016 f1_keywords: ["C3655"] helpviewer_keywords: ["C3655"] -ms.assetid: 724919ab-2915-4b61-8794-44648e162d62 --- # Compiler Error C3655 -'function' : function already explicitly overridden +> 'function' : function already explicitly overridden + +## Remarks A function can only be explicitly overridden once. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3655: +## Example + +The following example generates C3655: ```cpp // C3655.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3656.md b/docs/error-messages/compiler-errors-2/compiler-error-c3656.md index 1825ce5c157..da9a9fb22c7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3656.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3656.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3656" title: "Compiler Error C3656" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3656" +ms.date: 11/04/2016 f1_keywords: ["C3656"] helpviewer_keywords: ["C3656"] -ms.assetid: 88965d85-73b0-4b35-8020-0650c9c94cd8 --- # Compiler Error C3656 -'override' : override specifier cannot be repeated +> 'override' : override specifier cannot be repeated + +## Remarks An explicit override keyword can only be specified once. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3656: +## Example + +The following example generates C3656: ```cpp // C3656.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3657.md b/docs/error-messages/compiler-errors-2/compiler-error-c3657.md index a778329f3c9..155f032d990 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3657.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3657.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3657" title: "Compiler Error C3657" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3657" +ms.date: 11/04/2016 f1_keywords: ["C3657"] helpviewer_keywords: ["C3657"] -ms.assetid: 89a28a18-4c17-43a1-bda6-deb52c32d203 --- # Compiler Error C3657 -destructors cannot explicitly override or be explicitly overridden +> destructors cannot explicitly override or be explicitly overridden + +## Remarks Destructors or finalizers cannot be explicitly overridden. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). ## Example -The following sample generates C3657. +The following example generates C3657. ```cpp // C3657.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3661.md b/docs/error-messages/compiler-errors-2/compiler-error-c3661.md index 8f0e21753b5..7429b9de5ac 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3661.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3661.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3661" title: "Compiler Error C3661" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3661" +ms.date: 11/04/2016 f1_keywords: ["C3661"] helpviewer_keywords: ["C3661"] -ms.assetid: 50793fd1-1829-4b29-ad0d-094ef2068b43 --- # Compiler Error C3661 -explicit override list did not find any methods to override +> explicit override list did not find any methods to override + +## Remarks An explicit override specified one or more type names. However, there was no function with the necessary signature in the type(s) that matched the overriding function's signature. If you attempt to override based on type name, there must be one or more virtual functions in the specified type(s) that match the signature of the overriding function. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3662.md b/docs/error-messages/compiler-errors-2/compiler-error-c3662.md index 6ba37b24059..e5edfda336a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3662.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3662.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3662" title: "Compiler Error C3662" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3662" +ms.date: 11/04/2016 f1_keywords: ["C3662"] helpviewer_keywords: ["C3662"] -ms.assetid: 61bd3e41-a86b-42c0-be89-d992d3906ff1 --- # Compiler Error C3662 -'member' : override specifier 'specifier' only allowed on member functions of managed or WinRT classes +> 'member' : override specifier 'specifier' only allowed on member functions of managed or WinRT classes + +## Remarks An override specifier was used on a member of native type, which is not allowed. @@ -16,7 +17,7 @@ For more information, see [Explicit Overrides](../../extensions/explicit-overrid ## Example -The following sample generates C3662. +The following example generates C3662. ```cpp // C3662.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3665.md b/docs/error-messages/compiler-errors-2/compiler-error-c3665.md index 936a2255bf1..969f276e9c6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3665.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3665.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3665" title: "Compiler Error C3665" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3665" +ms.date: 11/04/2016 f1_keywords: ["C3665"] helpviewer_keywords: ["C3665"] -ms.assetid: 893bb47e-8de1-43aa-af7d-fa47ad149ee9 --- # Compiler Error C3665 -'destructor' : override specifier 'keyword' not allowed on a destructor/finalizer +> 'destructor' : override specifier 'keyword' not allowed on a destructor/finalizer + +## Remarks A keyword was used that is not allowed on a destructor or finalizer. For example, a new slot cannot be requested on a destructor or finalizer. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md) and [Destructors and finalizers](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Destructors_and_finalizers). -The following sample generates C3665: +## Example + +The following example generates C3665: ```cpp // C3665.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3666.md b/docs/error-messages/compiler-errors-2/compiler-error-c3666.md index c2aa130de78..b516ef72145 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3666.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3666.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3666" title: "Compiler Error C3666" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3666" +ms.date: 11/04/2016 f1_keywords: ["C3666"] helpviewer_keywords: ["C3666"] -ms.assetid: 459e51dd-cefb-4346-99b3-644f2d8b65b2 --- # Compiler Error C3666 -'constructor' : override specifier 'keyword' not allowed on a constructor +> 'constructor' : override specifier 'keyword' not allowed on a constructor + +## Remarks An override specifier was used on a constructor, and that is not allowed. For more information, see [Override Specifiers](../../extensions/override-specifiers-cpp-component-extensions.md). ## Example -The following sample generates C3666. +The following example generates C3666. ```cpp // C3666.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3668.md b/docs/error-messages/compiler-errors-2/compiler-error-c3668.md index 079daf488b1..e8640f0b6b5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3668.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3668.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3668" title: "Compiler Error C3668" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3668" +ms.date: 11/04/2016 f1_keywords: ["C3668"] helpviewer_keywords: ["C3668"] -ms.assetid: 53a96698-bde4-4447-95b5-b5108291f60c --- # Compiler Error C3668 -'method' : method with override specifier 'override' did not override any base class methods +> 'method' : method with override specifier 'override' did not override any base class methods + +## Remarks A function attempted to override a non-existent function. @@ -16,7 +17,7 @@ For more information, see [Explicit Overrides](../../extensions/explicit-overrid ## Example -The following sample generates C3668. +The following example generates C3668. ```cpp // C3668.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3669.md b/docs/error-messages/compiler-errors-2/compiler-error-c3669.md index 4b1fcf62295..c4e896e88fe 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3669.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3669.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3669" title: "Compiler Error C3669" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3669" +ms.date: 11/04/2016 f1_keywords: ["C3669"] helpviewer_keywords: ["C3669"] -ms.assetid: be9c7ae4-e96f-47ab-922a-39a3537d5ca6 --- # Compiler Error C3669 -'member' : override specifier 'override' not allowed on static member functions or constructors +> 'member' : override specifier 'override' not allowed on static member functions or constructors + +## Remarks An override was specified incorrectly. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). ## Example -The following sample generates C3669. +The following example generates C3669. ```cpp // C3669.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3670.md b/docs/error-messages/compiler-errors-2/compiler-error-c3670.md index 6c0d1e1786d..7db7a7f9bc4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3670.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3670.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3670" title: "Compiler Error C3670" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3670" +ms.date: 11/04/2016 f1_keywords: ["C3670"] helpviewer_keywords: ["C3670"] -ms.assetid: d0fa9c6e-8f90-48c7-9066-31b4fa5942eb --- # Compiler Error C3670 -'override' : cannot override inaccessible base class method 'method' +> 'override' : cannot override inaccessible base class method 'method' + +## Remarks An override can only take place on a function whose access level makes it available in a derived type. For more information, see [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md). -The following sample generates C3670: +## Example + +The following example generates C3670: ```cpp // C3670.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3671.md b/docs/error-messages/compiler-errors-2/compiler-error-c3671.md index 8a310719b59..81d0cefecf9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3671.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3671.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3671" title: "Compiler Error C3671" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3671" +ms.date: 11/04/2016 f1_keywords: ["C3671"] helpviewer_keywords: ["C3671"] -ms.assetid: d684e4ae-87e2-4424-80bb-6f346652c831 --- # Compiler Error C3671 -'function_1' : function does not override 'function_2' +> 'function_1' : function does not override 'function_2' + +## Remarks When using explicit override syntax, the compiler generates an error if a function is not overridden. See [Explicit Overrides](../../extensions/explicit-overrides-cpp-component-extensions.md) for more information. ## Example -The following sample generates C3671. +The following example generates C3671. ```cpp // C3671.cpp 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 3624f2563d0..6a013789552 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3672.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3672.md @@ -1,20 +1,21 @@ --- -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 -pseudo-destructor expression can only be used as part of a function call +> pseudo-destructor expression can only be used as part of a function call + +## Remarks A destructor was called incorrectly. For more information, see [Destructors](../../cpp/destructors-cpp.md). ## Example -The following sample generates C3672. +The following example generates C3672. ```cpp // C3672.cpp @@ -22,7 +23,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-c3673.md b/docs/error-messages/compiler-errors-2/compiler-error-c3673.md index 80458100b76..5781848d703 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3673.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3673.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3673" title: "Compiler Error C3673" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3673" +ms.date: 11/04/2016 f1_keywords: ["C3673"] helpviewer_keywords: ["C3673"] -ms.assetid: bb6d2079-05af-4e2c-be0e-75c892e6c590 --- # Compiler Error C3673 -'type' : class does not have a copy-constructor +> 'type' : class does not have a copy-constructor + +## Remarks A user-defined constructor is needed to copy objects of CLR ref types. For more information, see [C++ Stack Semantics for Reference Types](../../dotnet/cpp-stack-semantics-for-reference-types.md). ## Examples -The following sample generates C3673. +The following example generates C3673. ```cpp // C3673.cpp @@ -32,7 +33,7 @@ int main() { } ``` -The following sample generates C3673. +The following example generates C3673. ```cpp // C3673_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3675.md b/docs/error-messages/compiler-errors-2/compiler-error-c3675.md index 8ef0cbf41f7..437cd7bb1ae 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3675.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3675.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3675" title: "Compiler Error C3675" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3675" +ms.date: 11/04/2016 f1_keywords: ["C3675"] helpviewer_keywords: ["C3675"] -ms.assetid: 87461613-6633-430b-b95d-c7cb1bb63776 --- # Compiler Error C3675 -'function' : is reserved because 'property' is defined +> 'function' : is reserved because 'property' is defined + +## Remarks When you declare a simple property, the compiler generates the get and set accessor methods, and those names are present in the scope of your program. The compiler-generated names are formed by prepending get_ and set_ to the property name. Therefore, you cannot declare functions with the same name as the compiler-generated accessors. @@ -16,7 +17,7 @@ See [property](../../extensions/property-cpp-component-extensions.md) for more i ## Example -The following sample generates C3675. +The following example generates C3675. ```cpp // C3675.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3697.md b/docs/error-messages/compiler-errors-2/compiler-error-c3697.md index aa3cb7f3396..dbb5120276b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3697.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3697.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3697" title: "Compiler Error C3697" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3697" +ms.date: 11/04/2016 f1_keywords: ["C3697"] helpviewer_keywords: ["C3697"] -ms.assetid: 2d3f63c4-b7f8-421d-a7a5-2bf17fd054f9 --- # Compiler Error C3697 -'qualifier' : cannot use this qualifier on '^' +> 'qualifier' : cannot use this qualifier on '^' + +## Remarks The tracking handle (^) was applied to a qualifier for which it was not designed. -The following sample generates C3697: +## Example + +The following example generates C3697: ```cpp // C3697.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3698.md b/docs/error-messages/compiler-errors-2/compiler-error-c3698.md index f3be544edad..76dac5ebdc7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3698.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3698.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3698" title: "Compiler Error C3698" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3698" +ms.date: 11/04/2016 f1_keywords: ["C3698"] helpviewer_keywords: ["C3698"] -ms.assetid: 3c02fb08-7ba4-4637-a06f-19926cb2b5f1 --- # Compiler Error C3698 -'type' : cannot use this type as argument of 'operator' +> 'type' : cannot use this type as argument of 'operator' + +## Remarks A managed object was declared incorrectly. -The following sample generates C3698: +## Example + +The following example generates C3698: ```cpp // C3698.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3699.md b/docs/error-messages/compiler-errors-2/compiler-error-c3699.md index 98d2020bbf0..962b767cd4f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3699.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3699.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3699" title: "Compiler Error C3699" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3699" +ms.date: 11/04/2016 f1_keywords: ["C3699"] helpviewer_keywords: ["C3699"] -ms.assetid: 47c29afc-ab8b-4238-adfe-788dd6e00b3b --- # Compiler Error C3699 -'operator' : cannot use this indirection on type 'type' +> 'operator' : cannot use this indirection on type 'type' + +## Remarks An attempt was made to use indirection that is not allowed on `type`. ## Examples -The following sample generates C3699. +The following example generates C3699. ```cpp // C3699.cpp @@ -27,7 +28,7 @@ int main() { } ``` -A trivial property cannot have reference type. See [property](../../extensions/property-cpp-component-extensions.md) for more information. The following sample generates C3699. +A trivial property cannot have reference type. See [property](../../extensions/property-cpp-component-extensions.md) for more information. The following example generates C3699. ```cpp // C3699_b.cpp @@ -38,7 +39,7 @@ ref struct C { }; ``` -The equivalent of a "pointer to a pointer" syntax is a handle to a tracking reference. The following sample generates C3699. +The equivalent of a "pointer to a pointer" syntax is a handle to a tracking reference. The following example generates C3699. ```cpp // C3699_c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3701.md b/docs/error-messages/compiler-errors-2/compiler-error-c3701.md index 5ddae9dc5cf..4194641c39f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3701.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3701.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3701" title: "Compiler Error C3701" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3701" +ms.date: 11/04/2016 f1_keywords: ["C3701"] helpviewer_keywords: ["C3701"] -ms.assetid: a7faaa87-d2f5-4d6a-9a2f-5cab2d24a648 --- # Compiler Error C3701 -'function' : event_source has no events +> 'function' : event_source has no events + +## Remarks You attempted to use [event_source](../../windows/attributes/event-source.md) on a class that has no event methods. To fix this error, add one or more events to the class. -The following sample generates C3701: +## Example + +The following example generates C3701: ```cpp // C3701.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3702.md b/docs/error-messages/compiler-errors-2/compiler-error-c3702.md index c405d39324e..8c101ecfb71 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3702.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3702.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3702" title: "Compiler Error C3702" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3702" +ms.date: 11/04/2016 f1_keywords: ["C3702"] helpviewer_keywords: ["C3702"] -ms.assetid: 14fcc20e-4404-45d7-be54-e4f09332fa5a --- # Compiler Error C3702 -'function' : ATL is required for COM events +> 'function' : ATL is required for COM events + +## Remarks You attempted to use COM events without including the necessary ATL header files. -The following sample generates C3702: +## Example + +The following example generates C3702: ```cpp // C3702.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3703.md b/docs/error-messages/compiler-errors-2/compiler-error-c3703.md index 674971f02c2..3061a7f300e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3703.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3703.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3703" title: "Compiler Error C3703" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3703" +ms.date: 11/04/2016 f1_keywords: ["C3703"] helpviewer_keywords: ["C3703"] -ms.assetid: 7e3677d9-f2be-4c26-998f-423564e9023c --- # Compiler Error C3703 -'event handler': an event handler method must have the same storage class as the source 'event' +> 'event handler': an event handler method must have the same storage class as the source 'event' + +## Remarks An [event](../../cpp/event-handling.md) has a different storage class than the event handler to which it is hooked. For example, this error occurs if the event handler is a static member function and the event is not static. To fix this error, give the event and the event handler the same storage class. -The following sample generates C3703: +## Example + +The following example generates C3703: ```cpp // C3703.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3704.md b/docs/error-messages/compiler-errors-2/compiler-error-c3704.md index 619885fc8a2..7b218f85226 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3704.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3704.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3704" title: "Compiler Error C3704" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3704" +ms.date: 11/04/2016 f1_keywords: ["C3704"] helpviewer_keywords: ["C3704"] -ms.assetid: ee40ea35-a214-4dec-9489-d7f155dd0ac2 --- # Compiler Error C3704 -'function' : a vararg method cannot fire events +> 'function' : a vararg method cannot fire events + +## Remarks + +You attempted to use [__event](../../cpp/event.md) on a vararg method. To fix this error, replace the `fireEvent(int i, ...)` call with the `fireEvent(int i)` call as shown in the following code example. -You attempted to use [__event](../../cpp/event.md) on a vararg method. To fix this error, replace the `fireEvent(int i, ...)` call with the `fireEvent(int i)` call as shown in the following code sample. +## Example -The following sample generates C3704: +The following example generates C3704: ```cpp // C3704.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3705.md b/docs/error-messages/compiler-errors-2/compiler-error-c3705.md index d0aafaf4e3d..7408c255823 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3705.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3705.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3705" title: "Compiler Error C3705" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3705" +ms.date: 11/04/2016 f1_keywords: ["C3705"] helpviewer_keywords: ["C3705"] -ms.assetid: 8361017d-5782-4214-a9d7-e9825fd29bc8 --- # Compiler Error C3705 -'function' : cannot find eventing interface +> 'function' : cannot find eventing interface + +## Remarks + +You must define an event interface to use COM events. Note that the `#include` lines of the ATL header files shown in the example below are required for using COM events. To fix this error, uncomment the definition of the `IEvents` interface in the example code. -You must define an event interface to use COM events. Note that the `#include` lines of the ATL header files shown in the sample below are required for using COM events. To fix this error, uncomment the definition of the `IEvents` interface in the sample code. +## Example -The following sample generates C3705: +The following example generates C3705: ```cpp // C3705.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3706.md b/docs/error-messages/compiler-errors-2/compiler-error-c3706.md index 82e34020d09..3a64b432952 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3706.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3706.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Error C3706" title: "Compiler Error C3706" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3706" +ms.date: 11/04/2016 f1_keywords: ["C3706"] helpviewer_keywords: ["C3706"] -ms.assetid: d20a33eb-d625-46c5-ac87-32075a590d07 --- # Compiler Error C3706 -'function' : must be a COM interface to fire COM events +> 'function' : must be a COM interface to fire COM events + +## Remarks The event interface that you use to fire COM events must be a COM interface. In this situation, the interface should either be defined using a Visual C++ attribute, or imported using [#import](../../preprocessor/hash-import-directive-cpp.md) from a type library with #import's embedded_idl attribute. -Note that the `#include` lines of the ATL header files shown in the sample below are required for using COM events. To fix this error, make `IEvents` (the eventing interface) a COM interface by applying one of the following attributes to the interface definition: [object](../../windows/attributes/object-cpp.md), [dual](../../windows/attributes/dual.md), or [dispinterface](../../windows/attributes/dispinterface.md). +Note that the `#include` lines of the ATL header files shown in the example below are required for using COM events. To fix this error, make `IEvents` (the eventing interface) a COM interface by applying one of the following attributes to the interface definition: [object](../../windows/attributes/object-cpp.md), [dual](../../windows/attributes/dual.md), or [dispinterface](../../windows/attributes/dispinterface.md). If an interface is from a header file generated by MIDL, the compiler will not recognize it as a COM interface. -The following sample generates C3706: +## Example + +The following example generates C3706: ```cpp // C3706.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3707.md b/docs/error-messages/compiler-errors-2/compiler-error-c3707.md index 66e76dcccbd..1d3d66e45fa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3707.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3707.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3707" title: "Compiler Error C3707" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3707" +ms.date: 11/04/2016 f1_keywords: ["C3707"] helpviewer_keywords: ["C3707"] -ms.assetid: ac63a5dd-7a4b-48d2-9f2a-be9cb090134c --- # Compiler Error C3707 -'function' : dispinterface method must have a dispid +> 'function' : dispinterface method must have a dispid + +## Remarks + +If you use a `dispinterface` method, you must assign it a `dispid`. To fix this error, assign a `dispid` to the `dispinterface` method, for example, by uncommenting the `id` attribute on the method in the example below. For more information, see the attributes [dispinterface](../../windows/attributes/dispinterface.md) and [id](../../windows/attributes/id.md). -If you use a `dispinterface` method, you must assign it a `dispid`. To fix this error, assign a `dispid` to the `dispinterface` method, for example, by uncommenting the `id` attribute on the method in the sample below. For more information, see the attributes [dispinterface](../../windows/attributes/dispinterface.md) and [id](../../windows/attributes/id.md). +## Example -The following sample generates C3707: +The following example generates C3707: ```cpp // C3707.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3708.md b/docs/error-messages/compiler-errors-2/compiler-error-c3708.md index 4d171cc1b67..a611b94ccf0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3708.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3708.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3708" title: "Compiler Error C3708" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3708" +ms.date: 11/04/2016 f1_keywords: ["C3708"] helpviewer_keywords: ["C3708"] -ms.assetid: 45e71564-9c7f-437f-98d8-a735ce162ed0 --- # Compiler Error C3708 -'interface': improper use of 'keyword'; must be a member of a compatible event source +> 'interface': improper use of 'keyword'; must be a member of a compatible event source + +## Remarks To declare an interface as an event, the event declaration must be in an event source. -The following sample generates C3708: +## Example + +The following example generates C3708: ```cpp // C3708.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3709.md b/docs/error-messages/compiler-errors-2/compiler-error-c3709.md index c357f96034f..9c0750d1cc0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3709.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3709.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3709" title: "Compiler Error C3709" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3709" +ms.date: 11/04/2016 f1_keywords: ["C3709"] helpviewer_keywords: ["C3709"] -ms.assetid: d5576b04-2f93-420a-8f3e-8b8e987e8dab --- # Compiler Error C3709 -'function': improper syntax for specifying event in __hook/\__unhook +> 'function': improper syntax for specifying event in __hook/\__unhook + +## Remarks When you specify an event source with [__hook](../../cpp/hook.md) or [__unhook](../../cpp/unhook.md), the first parameter must be a valid event method and the second parameter must be a valid event source object (not a method). -The following sample generates C3709: +## Example + +The following example generates C3709: ```cpp // C3709.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3710.md b/docs/error-messages/compiler-errors-2/compiler-error-c3710.md index a3e0b13c6c7..7616ac9a947 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3710.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3710.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3710" title: "Compiler Error C3710" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3710" +ms.date: 11/04/2016 f1_keywords: ["C3710"] helpviewer_keywords: ["C3710"] -ms.assetid: 18bec009-5b6f-464a-a21e-5d58a6936504 --- # Compiler Error C3710 -'function': improper syntax for specifying event handler in __hook/\__unhook +> 'function': improper syntax for specifying event handler in __hook/\__unhook + +## Remarks When you specify an event handler with [__hook](../../cpp/hook.md) or [__unhook](../../cpp/unhook.md), the handler must be a valid method. ## Example -The following sample generates C3710 +The following example generates C3710 ```cpp // C3710.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3711.md b/docs/error-messages/compiler-errors-2/compiler-error-c3711.md index 16b395e4bfd..8b7399ff2e6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3711.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3711.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3711" title: "Compiler Error C3711" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3711" +ms.date: 11/04/2016 f1_keywords: ["C3711"] helpviewer_keywords: ["C3711"] -ms.assetid: 26d581cc-2153-4ee0-b814-a371184be3e1 --- # Compiler Error C3711 -'method': an non-managed event source method must return void or an integral type +> 'method': an non-managed event source method must return void or an integral type + +## Remarks You defined a method in the event source that did not return void or an integral type. To fix this error, make the event and event handler have a return type of **`void`** or an integral type such as **`int`** or **`long`**. -The following sample generates C3711: +## Example + +The following example generates C3711: ```cpp // C3711.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3712.md b/docs/error-messages/compiler-errors-2/compiler-error-c3712.md index 99094e6ddab..d7ac31955f0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3712.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3712.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3712" title: "Compiler Error C3712" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3712" +ms.date: 11/04/2016 f1_keywords: ["C3712"] helpviewer_keywords: ["C3712"] -ms.assetid: 65b1fcaf-be89-4c55-9e40-25ec03457253 --- # Compiler Error C3712 -'method': an event handler method must return the same type as the source 'method' +> 'method': an event handler method must return the same type as the source 'method' + +## Remarks You defined an event handler method that did not return the same type as the source event method. To fix this error, give the event handler method the same return type as that of the source event method. -The following sample generates C3712: +## Example + +The following example generates C3712: ```cpp // C3712.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3713.md b/docs/error-messages/compiler-errors-2/compiler-error-c3713.md index 9ab74b96bbc..8949eafa8a0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3713.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3713.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3713" title: "Compiler Error C3713" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3713" +ms.date: 11/04/2016 f1_keywords: ["C3713"] helpviewer_keywords: ["C3713"] -ms.assetid: 75c6b9b6-955b-49bd-9bc8-ced88b496a1f --- # Compiler Error C3713 -'method': an event handler method must have the same function parameters as the source 'method' +> 'method': an event handler method must have the same function parameters as the source 'method' + +## Remarks You defined an event handler method that did not use the same parameters as the source event method. To fix this error, give the event handler method the same parameters as those of the source event method. -The following sample generates C3713: +## Example + +The following example generates C3713: ```cpp // C3713.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3714.md b/docs/error-messages/compiler-errors-2/compiler-error-c3714.md index 2f230ab4060..a623be6a03d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3714.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3714.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3714" title: "Compiler Error C3714" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3714" +ms.date: 11/04/2016 f1_keywords: ["C3714"] helpviewer_keywords: ["C3714"] -ms.assetid: 17718f75-5a37-4e42-912b-487e91008a95 --- # Compiler Error C3714 -'method': an event handler method must have the same calling convention as the source 'method' +> 'method': an event handler method must have the same calling convention as the source 'method' + +## Remarks You defined an event handler method that did not use the same calling convention as the source event method. To fix this error, give the event handler method the same calling conventions as those of the source event method. For example, in the code below, make the calling conventions of `handler1` and `event1` match ([__cdecl](../../cpp/cdecl.md) or [__stdcall](../../cpp/stdcall.md) or others). Removing calling convention keywords from both declarations will also solve the problem, and cause `event1` and `handler1` to default to the [thiscall](../../cpp/thiscall.md) calling convention. See [Calling Conventions](../../cpp/calling-conventions.md) for more information. -The following sample generates C3714: +## Example + +The following example generates C3714: ```cpp // C3714.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3715.md b/docs/error-messages/compiler-errors-2/compiler-error-c3715.md index 3357231814a..807db400d6b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3715.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3715.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3715" title: "Compiler Error C3715" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3715" +ms.date: 11/04/2016 f1_keywords: ["C3715"] helpviewer_keywords: ["C3715"] -ms.assetid: ee5dce88-ddc4-4bdb-9464-47467ce1674f --- # Compiler Error C3715 -'pointer': must be a pointer to 'class' +> 'pointer': must be a pointer to 'class' + +## Remarks You specified a pointer in [`__hook`](../../cpp/hook.md) or [`__unhook`](../../cpp/unhook.md) that did not point to a valid class. To fix this error, ensure that your **`__hook`** and **`__unhook`** calls specify pointers to valid classes. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3717.md b/docs/error-messages/compiler-errors-2/compiler-error-c3717.md index 6aead02f76c..26f54ec56c1 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3717.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3717.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3717" title: "Compiler Error C3717" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3717" +ms.date: 11/04/2016 f1_keywords: ["C3717"] helpviewer_keywords: ["C3717"] -ms.assetid: ae4fceb1-2583-4577-b2f1-40971a017055 --- # Compiler Error C3717 -'method': a method that fires events cannot be defined +> 'method': a method that fires events cannot be defined + +## Remarks You declared an event method that includes an implementation. An [__event](../../cpp/event.md) method declaration cannot have a definition. To fix this error, ensure that no event method declarations have definitions. For example, in the code below, remove the function body from the `event1` declaration as indicated by the comments. -The following sample generates C3717: +## Example + +The following example generates C3717: ```cpp // C3717.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3718.md b/docs/error-messages/compiler-errors-2/compiler-error-c3718.md index ad3cb130088..63b08e810fb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3718.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3718.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3718" title: "Compiler Error C3718" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3718" +ms.date: 11/04/2016 f1_keywords: ["C3718"] helpviewer_keywords: ["C3718"] -ms.assetid: 346b5205-c44d-49d3-b66a-96417d3d6986 --- # Compiler Error C3718 > can only call '*event*' in the context of a member function of the receiving class +## Remarks + The event can only be called from the receiving class. ## Example -The following sample generates C3718: +The following example generates C3718: ```cpp // C3718.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3719.md b/docs/error-messages/compiler-errors-2/compiler-error-c3719.md index 777a99eabac..7dad0a67d1c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3719.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3719.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3719" title: "Compiler Error C3719" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3719" +ms.date: 11/04/2016 f1_keywords: ["C3719"] helpviewer_keywords: ["C3719"] -ms.assetid: d0d59d4e-babb-4480-9ef7-70cf1a28165c --- # Compiler Error C3719 -'interface': an interface based event source can only be used for COM events +> 'interface': an interface based event source can only be used for COM events + +## Remarks You declared an interface in a non-COM context. -The following sample generates C3719: +## Example + +The following example generates C3719: ```cpp // C3719a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3721.md b/docs/error-messages/compiler-errors-2/compiler-error-c3721.md index fbfee81eae7..9b2aa843ac7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3721.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3721.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3721" title: "Compiler Error C3721" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3721" +ms.date: 11/04/2016 f1_keywords: ["C3721"] helpviewer_keywords: ["C3721"] -ms.assetid: c696ca38-3e00-4875-abbe-7bce0f46930e --- # Compiler Error C3721 -'signature': incompatible signature for event +> 'signature': incompatible signature for event + +## Remarks An event was declared incorrectly. For more information, see [__event](../../cpp/event.md). diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3722.md b/docs/error-messages/compiler-errors-2/compiler-error-c3722.md index c526c8d8924..e852c92d29f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3722.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3722.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3722" title: "Compiler Error C3722" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3722" +ms.date: 11/04/2016 f1_keywords: ["C3722"] helpviewer_keywords: ["C3722"] -ms.assetid: 3cb28363-5eff-4548-bd0d-d5c615846353 --- # Compiler Error C3722 -a generic event is not allowed +> a generic event is not allowed + +## Remarks The compiler only allows generic classes, structs, and functions. For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md). -The following sample generates C3722: +## Example + +The following example generates C3722: ```cpp // C3722.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3723.md b/docs/error-messages/compiler-errors-2/compiler-error-c3723.md index 1723435e049..c40274a831f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3723.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3723.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3723" title: "Compiler Error C3723" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3723" +ms.date: 11/04/2016 f1_keywords: ["C3723"] helpviewer_keywords: ["C3723"] -ms.assetid: ef0fb1ff-3f9a-4093-a6b6-894d1ab0c4b9 --- # Compiler Error C3723 > 'function': could not resolve event +## Remarks + `function` could not resolve which event to call. -The following sample generates C3723: +## Examples + +The following example generates C3723: ```cpp // C3723.cpp @@ -37,7 +40,7 @@ int main() { **`__hook`** and **`__unhook`** are not compatible with **`/clr`** programming. Use the += and -= operators instead. -The following sample generates C3723: +The following example generates C3723: ```cpp // C3723b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3724.md b/docs/error-messages/compiler-errors-2/compiler-error-c3724.md index 227b770bdc2..78cc2f268c4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3724.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3724.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: Compiler Error C3724" title: "Compiler Error C3724" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3724" +ms.date: 11/04/2016 f1_keywords: ["C3724"] helpviewer_keywords: ["C3724"] -ms.assetid: cab8aba7-14fc-406f-8cc6-32744c8f31c1 --- # Compiler Error C3724 -must #include \ to use multi-threading with events +> must #include \ to use multi-threading with events + +## Remarks The windows.h file is required if you use multi-threading with events. To fix this error, add `#include ` to the top of the file in which event sources and event receivers are defined. +## Example + +The following example generates C3724: + ```cpp // C3724.cpp // uncomment the following line to resolve diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3727.md b/docs/error-messages/compiler-errors-2/compiler-error-c3727.md index 9bd6172470b..a431ad71bcc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3727.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3727.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3727" title: "Compiler Error C3727" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3727" +ms.date: 11/04/2016 f1_keywords: ["C3727"] helpviewer_keywords: ["C3727"] -ms.assetid: 17b9fe7b-ee9e-483f-9c27-1f709255a9e0 --- # Compiler Error C3727 -'event': a managed event must be a member function or a data member that is a pointer to a delegate +> 'event': a managed event must be a member function or a data member that is a pointer to a delegate + +## Remarks .NET events must be a pointer to a delegate type. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3728.md b/docs/error-messages/compiler-errors-2/compiler-error-c3728.md index a99650d9999..a67b6d6b90c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3728.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3728.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3728" title: "Compiler Error C3728" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3728" +ms.date: 11/04/2016 f1_keywords: ["C3728"] helpviewer_keywords: ["C3728"] -ms.assetid: 6b510cb1-887f-4fcd-9a1f-3bb720417ed1 --- # Compiler Error C3728 -'event': event does not have a raise method +> 'event': event does not have a raise method + +## Remarks Metadata created with a language, such as C#, that does not allow an event to be raised from outside the class in which it was defined, was included with the [#using](../../preprocessor/hash-using-directive-cpp.md) directive, and a Visual C++ program using CLR programming attempted to raise the event. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3731.md b/docs/error-messages/compiler-errors-2/compiler-error-c3731.md index 3336cfa957f..7b8d9f51f09 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3731.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3731.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3731" title: "Compiler Error C3731" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3731" +ms.date: 11/04/2016 f1_keywords: ["C3731"] helpviewer_keywords: ["C3731"] -ms.assetid: 45f89fcd-464c-4bc8-8a42-edcb5416d26c --- # Compiler Error C3731 -incompatible event 'function1' and handler 'function2'; event source and event handler must be the same type +> incompatible event 'function1' and handler 'function2'; event source and event handler must be the same type + +## Remarks The event source and event receiver must have the same type (for example `native` vs. `com` types). To fix this error, make the types of the event source and the event handler match. -The following sample generates C3731: +## Example + +The following example generates C3731: ```cpp // C3731.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3732.md b/docs/error-messages/compiler-errors-2/compiler-error-c3732.md index 5b02bbd1e22..b8a783b4e74 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3732.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3732.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Error C3732" title: "Compiler Error C3732" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3732" +ms.date: 11/04/2016 f1_keywords: ["C3732"] helpviewer_keywords: ["C3732"] -ms.assetid: 2d55a7e1-9c39-4379-a093-2f7beb27e2ca --- # Compiler Error C3732 -'interface': a custom interface that fires COM events cannot inherit from IDispatch +> 'interface': a custom interface that fires COM events cannot inherit from IDispatch + +## Remarks An interface that supports COM events cannot inherit from `IDispatch`. For more information, see [Event Handling in COM](../../cpp/event-handling-in-com.md). +## Example + The following error generates C3732: ```cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3733.md b/docs/error-messages/compiler-errors-2/compiler-error-c3733.md index 7a889e735f7..e5fdcabd78d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3733.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3733.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3733" title: "Compiler Error C3733" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3733" +ms.date: 11/04/2016 f1_keywords: ["C3733"] helpviewer_keywords: ["C3733"] -ms.assetid: 0cc1a9fe-1400-4be3-b35a-16435cba7a5a --- # Compiler Error C3733 -'event': improper syntax for specifying a COM event; did you forget '__interface'? +> 'event': improper syntax for specifying a COM event; did you forget '__interface'? + +## Remarks The wrong syntax was used for a COM event. To fix this error, change the event type or correct the syntax to comply with the COM event rules. -The following sample generates C3733: +## Example -``` +The following example generates C3733: + +```cpp #define _ATL_ATTRIBUTES 1 #include "atlbase.h" #include "atlcom.h" diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3734.md b/docs/error-messages/compiler-errors-2/compiler-error-c3734.md index e324edba416..3b4e5624503 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3734.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3734.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3734" title: "Compiler Error C3734" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3734" +ms.date: 11/04/2016 f1_keywords: ["C3734"] helpviewer_keywords: ["C3734"] -ms.assetid: 4e2afdcc-7da9-45a1-9c96-85f25e2986e8 --- # Compiler Error C3734 -'class': a managed or WinRT class cannot be a coclass +> 'class': a managed or WinRT class cannot be a coclass + +## Remarks The [coclass](../../windows/attributes/coclass.md) attribute cannot be used with managed or WinRT classes. -The following sample generates C3734 and shows how to fix it: +## Example + +The following example generates C3734 and shows how to fix it: ```cpp // C3734.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3736.md b/docs/error-messages/compiler-errors-2/compiler-error-c3736.md index fcd2b8d333d..e95ba8acaf9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3736.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3736.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3736" title: "Compiler Error C3736" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3736" +ms.date: 11/04/2016 f1_keywords: ["C3736"] helpviewer_keywords: ["C3736"] -ms.assetid: 579b773c-41e7-40ea-8382-2e3ce2667f4c --- # Compiler Error C3736 -'event': must be a method or, in the case of managed events, optionally a data member +> 'event': must be a method or, in the case of managed events, optionally a data member + +## Remarks Native and COM events must be methods. .NET events can also be data members. -The following sample generates C3736: +## Example + +The following example generates C3736: ```cpp // C3736.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3737.md b/docs/error-messages/compiler-errors-2/compiler-error-c3737.md index b6b4efa9ffc..1ca3f1a46cf 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3737.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3737.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3737" title: "Compiler Error C3737" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3737" +ms.date: 11/04/2016 f1_keywords: ["C3737"] helpviewer_keywords: ["C3737"] -ms.assetid: ca2aeb23-2491-4ccb-8838-884abf7065c8 --- # Compiler Error C3737 -'delegate': a delegate may not have an explicit calling convention +> 'delegate': a delegate may not have an explicit calling convention + +## Remarks You cannot specify the [calling convention](../../cpp/calling-conventions.md) for a **`delegate`**. ## Example -The following sample generates C3737: +The following example generates C3737: ```cpp // C3737a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3738.md b/docs/error-messages/compiler-errors-2/compiler-error-c3738.md index 319585c5184..d31a1c9b75a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3738.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3738.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3738" title: "Compiler Error C3738" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3738" +ms.date: 11/04/2016 f1_keywords: ["C3738"] helpviewer_keywords: ["C3738"] -ms.assetid: dd3ee011-e204-4264-bf3a-da32c4ef7038 --- # Compiler Error C3738 -'calling_convention': the calling convention of the explicit instantiation must match that of the template being instantiated +> 'calling_convention': the calling convention of the explicit instantiation must match that of the template being instantiated + +## Remarks It is recommended that you do not specify a calling convention on an explicit instantiation. If you must, though, the calling conventions must match. ## Example -The following sample generates C3738. +The following example generates C3738. ```cpp // C3738.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3739.md b/docs/error-messages/compiler-errors-2/compiler-error-c3739.md index 88b29cba22b..f666f3bdc4b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3739.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3739.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3739" title: "Compiler Error C3739" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3739" +ms.date: 11/04/2016 f1_keywords: ["C3739"] helpviewer_keywords: ["C3739"] -ms.assetid: acffe894-08b8-4bf2-9249-9501e6e2bad3 --- # Compiler Error C3739 -'class': syntax is only supported when the 'layout_dependent' parameter of event_receiver is true +> 'class': syntax is only supported when the 'layout_dependent' parameter of event_receiver is true + +## Remarks You tried to hook an entire interface of events but `layout_dependent` on [event_receiver](../../windows/attributes/event-receiver.md) attribute is not true; you must hook a single event at a time. -The following sample generates C3739: +## Example + +The following example generates C3739: ```cpp // C3739.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3740.md b/docs/error-messages/compiler-errors-2/compiler-error-c3740.md index a660236cdf5..b71adc946a8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3740.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3740.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3740" title: "Compiler Error C3740" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3740" +ms.date: 11/04/2016 f1_keywords: ["C3740"] helpviewer_keywords: ["C3740"] -ms.assetid: edb17a90-2307-4df6-943d-580460d26d2b --- # Compiler Error C3740 -templates cannot source or receive events +> templates cannot source or receive events + +## Remarks A templated class or struct cannot contain [events](../../cpp/event-handling.md). -The following sample generates C3740: +## Example + +The following example generates C3740: ```cpp // C3740.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3741.md b/docs/error-messages/compiler-errors-2/compiler-error-c3741.md index eda0e59dd9b..9fabe12afba 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3741.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3741.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3741" title: "Compiler Error C3741" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3741" +ms.date: 11/04/2016 f1_keywords: ["C3741"] helpviewer_keywords: ["C3741"] -ms.assetid: ed311315-cc32-49c9-97fa-01b293d81526 --- # Compiler Error C3741 -'class': must be a coclass when the 'layout_dependent' parameter of event_receiver = true +> 'class': must be a coclass when the 'layout_dependent' parameter of event_receiver = true + +## Remarks When `layout_dependent=true` for an [event_receiver](../../windows/attributes/event-receiver.md) class, then the class must also have the [coclass](../../windows/attributes/coclass.md) attribute. -The following sample generates C3741 +## Example + +The following example generates C3741 ```cpp // C3741.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3743.md b/docs/error-messages/compiler-errors-2/compiler-error-c3743.md index 6cabeee37af..eeb1dc1a848 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3743.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3743.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3743" title: "Compiler Error C3743" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3743" +ms.date: 11/04/2016 f1_keywords: ["C3743"] helpviewer_keywords: ["C3743"] -ms.assetid: 7ca9a76e-7b60-46d1-ab8b-18600cf1a306 --- # Compiler Error C3743 -can only hook/unhook an entire interface when the 'layout_dependent' parameter of event_receiver is true +> can only hook/unhook an entire interface when the 'layout_dependent' parameter of event_receiver is true + +## Remarks The [__unhook](../../cpp/unhook.md) function varies in the number of parameters that it takes based on the value passed to the `layout_dependent` parameter in the [event_receiver](../../windows/attributes/event-receiver.md) class. -The following sample generates C3743: +## Example + +The following example generates C3743: ```cpp // C3743.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3744.md b/docs/error-messages/compiler-errors-2/compiler-error-c3744.md index 289ae4d140b..7edb6d976b9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3744.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3744.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3744" title: "Compiler Error C3744" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3744" +ms.date: 11/04/2016 f1_keywords: ["C3744"] helpviewer_keywords: ["C3744"] -ms.assetid: a447d050-80d1-406a-9a6e-f15c527d717c --- # Compiler Error C3744 -__unhook must have at least 3 arguments for managed events +> __unhook must have at least 3 arguments for managed events + +## Remarks The [`__unhook`](../../cpp/unhook.md) function must take three parameters when used in a program that is compiled for Managed Extensions for C++. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3745.md b/docs/error-messages/compiler-errors-2/compiler-error-c3745.md index 1959d9bdeca..480fca90e6a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3745.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3745.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3745" title: "Compiler Error C3745" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3745" +ms.date: 11/04/2016 f1_keywords: ["C3745"] helpviewer_keywords: ["C3745"] -ms.assetid: 1e64aec5-7e53-47e5-bc7d-3905230cfc66 --- # Compiler Error C3745 -'function': only an event can be 'raised' +> 'function': only an event can be 'raised' + +## Remarks Only a function defined with the [__event](../../cpp/event.md) keyword can be passed to the [__raise](../../cpp/raise.md) keyword. -The following sample generates C3745: +## Example + +The following example generates C3745: ```cpp // C3745.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3747.md b/docs/error-messages/compiler-errors-2/compiler-error-c3747.md index 0b9fbeab007..deba5ccb381 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3747.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3747.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3747" title: "Compiler Error C3747" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3747" +ms.date: 11/04/2016 f1_keywords: ["C3747"] helpviewer_keywords: ["C3747"] -ms.assetid: a9a4be67-5d9c-4dcc-9ae9-baae46cbecde --- # Compiler Error C3747 -missing default type parameter : parameter param +> missing default type parameter : parameter param + +## Remarks Generic or template parameters with default values cannot be followed in the parameter list by parameters that do not have default values. -The following sample generates C3747: +## Example + +The following example generates C3747: ```cpp // C3747.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3748.md b/docs/error-messages/compiler-errors-2/compiler-error-c3748.md index f2f54266dfc..ba2b46ba8f0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3748.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3748.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3748" title: "Compiler Error C3748" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3748" +ms.date: 11/04/2016 f1_keywords: ["C3748"] helpviewer_keywords: ["C3748"] -ms.assetid: 6fe71a0a-dd93-4ce6-9729-b9616360cf34 --- # Compiler Error C3748 -'interface': managed interfaces may not fire events +> 'interface': managed interfaces may not fire events + +## Remarks The [__event](../../cpp/event.md) keyword cannot appear inside an interface. -The following sample generates C3748: +## Example + +The following example generates C3748: ```cpp // C3748.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3749.md b/docs/error-messages/compiler-errors-2/compiler-error-c3749.md index d31c3c0c67a..605a68c8fc6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3749.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3749.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3749" title: "Compiler Error C3749" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3749" +ms.date: 11/04/2016 f1_keywords: ["C3749"] helpviewer_keywords: ["C3749"] -ms.assetid: 3d26b468-4757-41b8-b5a2-78022a5295fb --- # Compiler Error C3749 -'attribute': a custom attribute may not be used inside a function +> 'attribute': a custom attribute may not be used inside a function + +## Remarks A custom attribute cannot be used inside a function. For more information on custom attributes, see the topic [attribute](../../windows/attributes/attribute.md). ## Example -The following sample generates C3749: +The following example generates C3749: ```cpp // C3749a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3752.md b/docs/error-messages/compiler-errors-2/compiler-error-c3752.md index 31df4234c49..3e8f4de3350 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3752.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3752.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3752" title: "Compiler Error C3752" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3752" +ms.date: 11/04/2016 f1_keywords: ["C3752"] helpviewer_keywords: ["C3752"] -ms.assetid: 1ac81d85-0f5a-4f39-95b6-42fd43cb18d5 --- # Compiler Error C3752 -'attribute class': cannot classify attribute; 'keyword' should not be used in this context +> 'attribute class': cannot classify attribute; 'keyword' should not be used in this context + +## Remarks A user-defined attribute was applied incorrectly. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3753.md b/docs/error-messages/compiler-errors-2/compiler-error-c3753.md index 54464a9469b..a455bba26fb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3753.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3753.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3753" title: "Compiler Error C3753" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3753" +ms.date: 11/04/2016 f1_keywords: ["C3753"] helpviewer_keywords: ["C3753"] -ms.assetid: a5b99e28-796c-4107-a673-97c2ae3bb2b9 --- # Compiler Error C3753 -a generic property is not allowed +> a generic property is not allowed + +## Remarks Generic parameter lists can only appear on managed classes, structs, or functions. @@ -16,7 +17,7 @@ For more information, see [Generics](../../extensions/generics-cpp-component-ext ## Example -The following sample generates C3753. +The following example generates C3753. ```cpp // C3753.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3754.md b/docs/error-messages/compiler-errors-2/compiler-error-c3754.md index f35e3c280a1..648b8bd64e0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3754.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3754.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3754" title: "Compiler Error C3754" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3754" +ms.date: 11/04/2016 f1_keywords: ["C3754"] helpviewer_keywords: ["C3754"] -ms.assetid: 14b877bc-9277-40ec-af1c-196a58b45f10 --- # Compiler Error C3754 -delegate constructor: member function 'function' cannot be called on an instance of type 'type' +> delegate constructor: member function 'function' cannot be called on an instance of type 'type' + +## Remarks A call was made to a function through a pointer to a type that does not contain the function. ## Example -The following sample generates C3754: +The following example generates C3754: ```cpp // C3754a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3755.md b/docs/error-messages/compiler-errors-2/compiler-error-c3755.md index 0f31bab3a5a..2ef2709d235 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3755.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3755.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3755" title: "Compiler Error C3755" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3755" +ms.date: 11/04/2016 f1_keywords: ["C3755"] helpviewer_keywords: ["C3755"] -ms.assetid: 9317b55e-a52e-4b87-b915-5a208d6eda38 --- # Compiler Error C3755 -'delegate': a delegate may not be defined +> 'delegate': a delegate may not be defined + +## Remarks A [delegate (C++ Component Extensions)](../../extensions/delegate-cpp-component-extensions.md) can be declared but not defined. ## Examples -The following sample generates C3755. +The following example generates C3755. ```cpp // C3755.cpp @@ -22,7 +23,7 @@ The following sample generates C3755. delegate void MyDel() {}; // C3755 ``` -C3755 can also occur if you attempt to create a delegate template. The following sample generates C3755. +C3755 can also occur if you attempt to create a delegate template. The following example generates C3755. ```cpp // C3755_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3761.md b/docs/error-messages/compiler-errors-2/compiler-error-c3761.md index 3b30366f458..7e0d0f90e8d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3761.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3761.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3761" title: "Compiler Error C3761" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3761" +ms.date: 11/04/2016 f1_keywords: ["C3761"] helpviewer_keywords: ["C3761"] -ms.assetid: 0c16f093-7a78-4838-b90b-0c67ef6e9270 --- # Compiler Error C3761 -'function': 'retval' can only appear on the last argument of a function +> 'function': 'retval' can only appear on the last argument of a function + +## Remarks The [retval](../../windows/attributes/retval.md) attribute was used on a function argument that was not the last argument in the list. -The following sample generates C3761: +## Example + +The following example generates C3761: ```cpp // C3761.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3762.md b/docs/error-messages/compiler-errors-2/compiler-error-c3762.md index 03925fb2115..a732ee83512 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3762.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3762.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3762" title: "Compiler Error C3762" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3762" +ms.date: 11/04/2016 f1_keywords: ["C3762"] helpviewer_keywords: ["C3762"] -ms.assetid: b79b6506-2cea-44a0-855a-5fdcb9fd7ad9 --- # Compiler Error C3762 -unable to process attribute 'attribute' +> unable to process attribute 'attribute' + +## Remarks A user-defined attribute that inherits from `System.Security.Permissions.SecurityAttribute` is being used to define a security attribute. Such an attribute cannot be used in the same assembly where it is defined. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3763.md b/docs/error-messages/compiler-errors-2/compiler-error-c3763.md index 0166ca13a41..f056026f670 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3763.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3763.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3763" title: "Compiler Error C3763" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3763" +ms.date: 11/04/2016 f1_keywords: ["C3763"] helpviewer_keywords: ["C3763"] -ms.assetid: 58b1f079-cd1d-46e0-9431-ea18210106b7 --- # Compiler Error C3763 -'type': 'retval' and 'out' can only appear on a data-pointer type +> 'type': 'retval' and 'out' can only appear on a data-pointer type + +## Remarks The [out](../../windows/attributes/out-cpp.md) or [retval](../../windows/attributes/retval.md) attributes can only appear on parameters of type pointer. Either remove the attribute or make the parameter of type pointer. -The following sample generates C3763: +## Example + +The following example generates C3763: ```cpp // C3763.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3764.md b/docs/error-messages/compiler-errors-2/compiler-error-c3764.md index ea866633a68..aa4d0782cbc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3764.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3764.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3764" title: "Compiler Error C3764" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3764" +ms.date: 11/04/2016 f1_keywords: ["C3764"] helpviewer_keywords: ["C3764"] -ms.assetid: af5d254c-8d4a-4dda-aad9-3c5c1257c868 --- # Compiler Error C3764 -'override_function': cannot override base class method 'base_class_function' +> 'override_function': cannot override base class method 'base_class_function' + +## Remarks The compiler detected an ill-formed override. For example, the base class function was not **`virtual`**. For more information, see [override](../../extensions/override-cpp-component-extensions.md). ## Examples -The following sample generates C3764. +The following example generates C3764. ```cpp // C3764.cpp @@ -30,7 +31,7 @@ public ref struct B : A { }; ``` -C3764 can also occur when a base class method is both explicitly and named overridden. The following sample generates C3764. +C3764 can also occur when a base class method is both explicitly and named overridden. The following example generates C3764. ```cpp // C3764_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3765.md b/docs/error-messages/compiler-errors-2/compiler-error-c3765.md index 6091aaa1b07..cba25055ecc 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3765.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3765.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3765" title: "Compiler Error C3765" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3765" +ms.date: 11/04/2016 f1_keywords: ["C3765"] helpviewer_keywords: ["C3765"] -ms.assetid: feadee7a-fcfb-402c-af2f-0e656f814a13 --- # Compiler Error C3765 -'event': cannot define an event in a class/struct 'type' marked as an event_receiver +> 'event': cannot define an event in a class/struct 'type' marked as an event_receiver + +## Remarks If a class is marked with the [event_receiver](../../windows/attributes/event-receiver.md) attribute, the class cannot contain an [__event](../../cpp/event.md) declaration. -The following sample generates C3765: +## Example + +The following example generates C3765: ```cpp // C3765.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3766.md b/docs/error-messages/compiler-errors-2/compiler-error-c3766.md index 9e4127d7f5d..996e2b80d35 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3766.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3766.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3766" title: "Compiler Error C3766" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3766" +ms.date: 11/04/2016 f1_keywords: ["C3766"] helpviewer_keywords: ["C3766"] -ms.assetid: b5af2089-2e1e-4e45-a41d-495b6c55656e --- # Compiler Error C3766 -'type' must provide an implementation for the interface method 'function' +> 'type' must provide an implementation for the interface method 'function' + +## Remarks A class that inherits from an interface must implement the interface members. ## Example -The following sample generates C3766. +The following example generates C3766. ```cpp // C3766.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3767.md b/docs/error-messages/compiler-errors-2/compiler-error-c3767.md index 9a9ed09b2b3..c3019dc8a11 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3767.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3767.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Error C3767" title: "Compiler Error C3767" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3767" +ms.date: 11/04/2016 f1_keywords: ["C3767"] helpviewer_keywords: ["C3767"] -ms.assetid: 5247cdcd-639c-4527-bd37-37e74c4e8fab --- # Compiler Error C3767 -'function' candidate function(s) not accessible +> 'function' candidate function(s) not accessible + +## Remarks A friend function defined in a class is not supposed to be treated as if it were defined and declared in the global namespace scope. It can, however, be found by argument-dependent lookup. C3767 may also be caused by a breaking change: native types are now private by default in a **/clr** compilation; see [Type visibility](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Type_visibility) for more information. -## Example +## Examples -The following sample generates C3767: +The following example generates C3767: ```cpp // C3767a.cpp @@ -47,7 +48,7 @@ int main() { }; ``` -The following sample generates C3767: +The following example generates C3767: ```cpp // C3767c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3768.md b/docs/error-messages/compiler-errors-2/compiler-error-c3768.md index 8bf47793aea..0d49df0bf52 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3768.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3768.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3768" title: "Compiler Error C3768" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3768" +ms.date: 11/04/2016 f1_keywords: ["C3768"] helpviewer_keywords: ["C3768"] -ms.assetid: 091f0d53-1dff-43fd-813d-5c43c85b6ab0 --- # Compiler Error C3768 @@ -18,7 +17,7 @@ When compiling with **/clr:pure**, you cannot take the address of a virtual `var ## Example -The following sample generates C3768: +The following example generates C3768: ```cpp // C3768.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3769.md b/docs/error-messages/compiler-errors-2/compiler-error-c3769.md index 47aa0fda651..1109fddfcde 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3769.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3769.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3769" title: "Compiler Error C3769" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3769" +ms.date: 11/04/2016 f1_keywords: ["C3769"] helpviewer_keywords: ["C3769"] -ms.assetid: 341675e1-7428-4da6-8275-1b2f0a70dacc --- # Compiler Error C3769 -'type' : a nested class cannot have the same name as the immediately enclosing class +> 'type' : a nested class cannot have the same name as the immediately enclosing class + +## Remarks A nested class cannot have the same name as the immediately enclosing class. ## Example -The following sample generates C3769. +The following example generates C3769. ```cpp // C3769.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3771.md b/docs/error-messages/compiler-errors-2/compiler-error-c3771.md index 3daf52e4047..3b950fed268 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3771.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3771.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3771" title: "Compiler Error C3771" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3771" +ms.date: 11/04/2016 f1_keywords: ["C3771"] helpviewer_keywords: ["C3771"] -ms.assetid: 68c23b25-7f21-4eaa-8f7e-38fda1130a69 --- # Compiler Error C3771 -"identifier" : friend declaration cannot be found in the nearest namespace scope +> "identifier" : friend declaration cannot be found in the nearest namespace scope + +## Remarks The class template declaration for the specified template *identifier* cannot be found within the current namespace. @@ -26,7 +27,7 @@ The following code example declares a class template and function in namespace ` namespace NA { template class A { - void aFunction(T t) {}; + void aFunction(T t) {} }; } // using namespace NA; diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3772.md b/docs/error-messages/compiler-errors-2/compiler-error-c3772.md index 042a708d93a..1cf537711b4 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3772.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3772.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3772" title: "Compiler Error C3772" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3772" +ms.date: 11/04/2016 f1_keywords: ["C3772"] helpviewer_keywords: ["C3772"] -ms.assetid: 63e938d4-088d-41cc-a562-5881a05b5710 --- # Compiler Error C3772 -"name" : invalid friend template declaration +> "name" : invalid friend template declaration + +## Remarks It is invalid to declare a friend of a class template specialization. You cannot declare an explicit or partial specialization of a class template and in the same statement declare a friend of that specialization. The *name* placeholder identifies the invalid declaration. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3779.md b/docs/error-messages/compiler-errors-2/compiler-error-c3779.md index 1f113ff903b..b1029535d73 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3779.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3779.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Error C3779" title: "Compiler Error C3779" +description: "Learn more about: Compiler Error C3779" ms.date: 05/19/2021 f1_keywords: ["C3779"] helpviewer_keywords: ["C3779"] @@ -9,15 +9,15 @@ helpviewer_keywords: ["C3779"] > '*function*': a function that returns '*auto or decltype(auto)*' cannot be used before it is defined -The **`auto`** return type of the specified function call couldn't be deduced. The compiler didn't have enough information at the call site. - ## Remarks +The **`auto`** return type of the specified function call couldn't be deduced. The compiler didn't have enough information at the call site. + This error can occur when you call a forward-declared member function that has an **`auto`** return type but no body or trailing return type. You can also get this error when the compiler can't find a candidate return type when it instantiates a template specialization. A common cause of this error is a missing interface header. The missing type can often be determined from the typename mentioned in a note that follows this error. To resolve this issue, for every type you use, include the header for the namespace the type is in. -## Examples +## Example -The following C++/WinRT sample generates C3779: +The following C++/WinRT example generates C3779: ```cpp // C3779.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3797.md b/docs/error-messages/compiler-errors-2/compiler-error-c3797.md index 22e95517bff..fd98c9b12f8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3797.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3797.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3797" title: "Compiler Error C3797" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3797" +ms.date: 11/04/2016 f1_keywords: ["C3797"] helpviewer_keywords: ["C3797"] -ms.assetid: ab27ff34-8c1d-4297-b004-9e39bd3a4f25 --- # Compiler Error C3797 -'override': event declaration cannot have override specifier (should be placed on event add/remove/raise methods instead) +> 'override': event declaration cannot have override specifier (should be placed on event add/remove/raise methods instead) + +## Remarks You cannot override a trivial event (an event without explicitly defined accessor methods) with another trivial event. The overriding event must define its behavior with accessor functions. @@ -16,7 +17,7 @@ For more information, see [event](../../extensions/event-cpp-component-extension ## Example -The following sample generates C3797. +The following example generates C3797. ```cpp // C3797.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3798.md b/docs/error-messages/compiler-errors-2/compiler-error-c3798.md index c0916d81b5b..40ce4ddd31b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3798.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3798.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3798" title: "Compiler Error C3798" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3798" +ms.date: 11/04/2016 f1_keywords: ["C3798"] helpviewer_keywords: ["C3798"] -ms.assetid: b2f8b1d8-8812-49b8-a346-28e48f02ba5c --- # Compiler Error C3798 -'specifier': property declaration cannot have override specifier (should be placed on property get/set methods instead) +> 'specifier': property declaration cannot have override specifier (should be placed on property get/set methods instead) + +## Remarks A property was declared incorrectly. For more information, see @@ -20,7 +21,7 @@ A property was declared incorrectly. For more information, see ## Example -The following sample generates C3798 +The following example generates C3798 ```cpp // C3798.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3799.md b/docs/error-messages/compiler-errors-2/compiler-error-c3799.md index 7a9f3980f9e..7824ef85cb5 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3799.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3799.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3799" title: "Compiler Error C3799" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3799" +ms.date: 11/04/2016 f1_keywords: ["C3799"] helpviewer_keywords: ["C3799"] -ms.assetid: 336a2811-9370-4e6e-b03b-325bda470805 --- # Compiler Error C3799 -indexed property cannot have an empty parameter list +> indexed property cannot have an empty parameter list + +## Remarks An indexed property was declared incorrectly. For more information, see [How to: Use Properties in C++/CLI](../../dotnet/how-to-use-properties-in-cpp-cli.md). ## Example -The following sample generates C3799 and shows how to fix it. +The following example generates C3799 and shows how to fix it. ```cpp // C3799.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3800.md b/docs/error-messages/compiler-errors-2/compiler-error-c3800.md index 4d21036576b..c2bf14ce9aa 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3800.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3800.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3800" title: "Compiler Error C3800" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3800" +ms.date: 11/04/2016 f1_keywords: ["C3800"] helpviewer_keywords: ["C3800"] -ms.assetid: c653240a-b6db-4437-8d65-fa58f0e6fcf4 --- # Compiler Error C3800 -'declaration': cannot mix properties and events +> 'declaration': cannot mix properties and events + +## Remarks You cannot declare a construct to be both a property and an event. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3803.md b/docs/error-messages/compiler-errors-2/compiler-error-c3803.md index af817ec77d1..367696019e8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3803.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3803.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3803" title: "Compiler Error C3803" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3803" +ms.date: 11/04/2016 f1_keywords: ["C3803"] helpviewer_keywords: ["C3803"] -ms.assetid: bad5fb9a-ed9a-4c15-96e7-cf06e200a50d --- # Compiler Error C3803 -'property': property has a type that is incompatible with one of its accessors 'accessor' +> 'property': property has a type that is incompatible with one of its accessors 'accessor' + +## Remarks The type of a property defined with [property](../../cpp/property-cpp.md) does not match the return type for one of its accessor functions. -The following sample generates C3803: +## Example + +The following example generates C3803: ```cpp // C3803.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3804.md b/docs/error-messages/compiler-errors-2/compiler-error-c3804.md index 78038af3c8d..243706cab93 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3804.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3804.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3804" title: "Compiler Error C3804" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3804" +ms.date: 11/04/2016 f1_keywords: ["C3804"] helpviewer_keywords: ["C3804"] -ms.assetid: 7c4cda28-ec96-4d04-937b-36dbd9944722 --- # Compiler Error C3804 -'property_accessor': the accessor methods for a property must either be all static or all non-static +> 'property_accessor': the accessor methods for a property must either be all static or all non-static + +## Remarks When defining a non-trivial property, the accessor functions can be either static or instance, but not both. @@ -16,7 +17,7 @@ See [property](../../extensions/property-cpp-component-extensions.md) for more i ## Example -The following sample generates C3804. +The following example generates C3804. ```cpp // C3804.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3805.md b/docs/error-messages/compiler-errors-2/compiler-error-c3805.md index 405f04301ed..b889e2d7e73 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3805.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3805.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3805" title: "Compiler Error C3805" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3805" +ms.date: 11/04/2016 f1_keywords: ["C3805"] helpviewer_keywords: ["C3805"] -ms.assetid: 166bbc35-5488-46b4-8e4c-9cd26ee5644e --- # Compiler Error C3805 -'token' : unexpected token, expected either '}' or an identifier +> 'token' : unexpected token, expected either '}' or an identifier + +## Remarks When defining a property, an invalid token was encountered. Remove the invalid token. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3807.md b/docs/error-messages/compiler-errors-2/compiler-error-c3807.md index 836ea5b2fe2..c951650c6d0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3807.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3807.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3807" title: "Compiler Error C3807" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3807" +ms.date: 11/04/2016 f1_keywords: ["C3807"] helpviewer_keywords: ["C3807"] -ms.assetid: 7e2b0aab-8c61-4e71-b9c1-fcaeb6a1b5ea --- # Compiler Error C3807 -'type' : a class with the ComImport attribute cannot derive from 'type2', only interface implementation is allowed +> 'type' : a class with the ComImport attribute cannot derive from 'type2', only interface implementation is allowed + +## Remarks A type that derived from can only implement an interface. ## Example -The following sample generates C3807. +The following example generates C3807. ```cpp // C3807.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3808.md b/docs/error-messages/compiler-errors-2/compiler-error-c3808.md index 33e19c9ba8a..d55d364f37d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3808.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3808.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3808" title: "Compiler Error C3808" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3808" +ms.date: 11/04/2016 f1_keywords: ["C3808"] helpviewer_keywords: ["C3808"] -ms.assetid: 2ee8ac97-3ea4-417a-8710-be73a7f98cf4 --- # Compiler Error C3808 @@ -18,7 +17,7 @@ The **/clr:pure** and **/clr:safe** compiler options are deprecated in Visual St ## Example -The following sample generates C3808. +The following example generates C3808. ```cpp // C3808.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3809.md b/docs/error-messages/compiler-errors-2/compiler-error-c3809.md index 33561ee925b..90fdd8856ac 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3809.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3809.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3809" title: "Compiler Error C3809" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3809" +ms.date: 11/04/2016 f1_keywords: ["C3809"] helpviewer_keywords: ["C3809"] -ms.assetid: 37eca584-c20c-464e-8e45-a987214b7ce4 --- # Compiler Error C3809 -'class' : a managed or WinRT type cannot have any friend functions/classes/interfaces +> 'class' : a managed or WinRT type cannot have any friend functions/classes/interfaces + +## Remarks Managed types and Windows Runtime types do not allow friends. To fix this error, do not declare friends inside managed or Windows Runtime types. -The following sample generates C3809: +## Example + +The following example generates C3809: ```cpp // C3809a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3812.md b/docs/error-messages/compiler-errors-2/compiler-error-c3812.md index 01948fe0827..b2618d099ba 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3812.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3812.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3812" title: "Compiler Error C3812" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3812" +ms.date: 11/04/2016 f1_keywords: ["C3812"] helpviewer_keywords: ["C3812"] -ms.assetid: 326ac706-9a5f-4851-b9d2-b90c64c75532 --- # Compiler Error C3812 -'property' must be the first token in a property declaration +> 'property' must be the first token in a property declaration + +## Remarks When declaring a property, the `__property` keyword must be the first token on the line. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3813.md b/docs/error-messages/compiler-errors-2/compiler-error-c3813.md index 191a711ea7f..4f384bab29a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3813.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3813.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3813" title: "Compiler Error C3813" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3813" +ms.date: 11/04/2016 f1_keywords: ["C3813"] helpviewer_keywords: ["C3813"] -ms.assetid: ffdbc489-71bf-4cd6-988c-f824c9ab3ceb --- # Compiler Error C3813 -a property declaration can only appear within the definition of a managed or WinRT type +> a property declaration can only appear within the definition of a managed or WinRT type + +## Remarks A [property](../../dotnet/how-to-use-properties-in-cpp-cli.md) can only be declared within a managed or Windows Runtime type. Native types do not support the **`property`** keyword. ## Example -The following sample generates C3813 and shows how to fix it: +The following example generates C3813 and shows how to fix it: ```cpp // C3813.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3815.md b/docs/error-messages/compiler-errors-2/compiler-error-c3815.md index 5ba2bf28ee5..b60ddbf7dd0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3815.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3815.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3815" title: "Compiler Error C3815" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3815" +ms.date: 11/04/2016 f1_keywords: ["C3815"] helpviewer_keywords: ["C3815"] -ms.assetid: c5a3b404-6341-4fd3-92af-152b404c4dde --- # Compiler Error C3815 -return type of method 'get_accessor' must match type of the last parameter of a setter +> return type of method 'get_accessor' must match type of the last parameter of a setter + +## Remarks When declaring properties, the return value of the `get_accessor` method must match the last parameter in the declaration of the set accessor method. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3816.md b/docs/error-messages/compiler-errors-2/compiler-error-c3816.md index 555ed517ecc..e489ee5545d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3816.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3816.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3816" title: "Compiler Error C3816" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3816" +ms.date: 11/04/2016 f1_keywords: ["C3816"] helpviewer_keywords: ["C3816"] -ms.assetid: 2e52cc7f-e31c-41a3-8d6f-9f5fab3648c0 --- # Compiler Error C3816 -'declaration' was previously declared or defined with a different managed or WinRTmodifier +> 'declaration' was previously declared or defined with a different managed or WinRTmodifier + +## Remarks A forward declaration and an actual declaration require that there be no conflicts or inconsistencies in the declaration of attributes. -The following sample generates C3816 and shows how to fix it: +## Example + +The following example generates C3816 and shows how to fix it: ```cpp // C3816a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3817.md b/docs/error-messages/compiler-errors-2/compiler-error-c3817.md index 763d7fecb84..2485dc8edf8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3817.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3817.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3817" title: "Compiler Error C3817" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3817" +ms.date: 11/04/2016 f1_keywords: ["C3817"] helpviewer_keywords: ["C3817"] -ms.assetid: c6dbb57a-c65e-4040-8dd2-85bd9d4fd337 --- # Compiler Error C3817 -'declaration' : property can only be applied to a function +> 'declaration' : property can only be applied to a function + +## Remarks The **`property`** keyword can only be a applied to a function definition. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3818.md b/docs/error-messages/compiler-errors-2/compiler-error-c3818.md index e89b0f982be..142477f6753 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3818.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3818.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3818" title: "Compiler Error C3818" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3818" +ms.date: 11/04/2016 f1_keywords: ["C3818"] helpviewer_keywords: ["C3818"] -ms.assetid: f9502f6a-0690-4135-ab88-cc97cf490f5c --- # Compiler Error C3818 -array property declaration 'property1' shall not overload an index property 'property2' +> array property declaration 'property1' shall not overload an index property 'property2' + +## Remarks An overload is not possible for properties when one is an indexer and the other is an array property. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3820.md b/docs/error-messages/compiler-errors-2/compiler-error-c3820.md index f9398c914e6..31f296f9bcd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3820.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3820.md @@ -4,7 +4,6 @@ description: "Microsoft C/C++ compiler error C3820 causes and remedies." ms.date: 09/26/2020 f1_keywords: ["C3820"] helpviewer_keywords: ["C3820"] -ms.assetid: 98638838-068f-4a62-b8d5-1068368a0ff1 --- # Compiler Error C3820 diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3821.md b/docs/error-messages/compiler-errors-2/compiler-error-c3821.md index 40b92e5f159..408630cab82 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3821.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3821.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3821" title: "Compiler Error C3821" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3821" +ms.date: 11/04/2016 f1_keywords: ["C3821"] helpviewer_keywords: ["C3821"] -ms.assetid: 2b327c7a-5faf-443c-ae82-944fae25b4df --- # Compiler Error C3821 -'function': managed type or function cannot be used in an unmanaged function +> 'function': managed type or function cannot be used in an unmanaged function + +## Remarks Functions with inline assembly or [setjmp](../../c-runtime-library/reference/setjmp.md) cannot contain value types or managed classes. To fix this error, remove the inline assembly and `setjmp` or remove the managed objects. @@ -16,7 +17,7 @@ C3821 can also occur if you try to use automatic storage in a vararg function. ## Examples -The following sample generates C3821. +The following example generates C3821. ```cpp // C3821a.cpp @@ -27,7 +28,7 @@ void test1(...) { } ``` -The following sample generates C3821. +The following example generates C3821. ```cpp // C3821b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3824.md b/docs/error-messages/compiler-errors-2/compiler-error-c3824.md index 9287340b195..37daec6fadf 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3824.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3824.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3824" title: "Compiler Error C3824" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3824" +ms.date: 11/04/2016 f1_keywords: ["C3824"] helpviewer_keywords: ["C3824"] -ms.assetid: b6c6adf1-0a29-401c-a06e-616fd50d4c37 --- # Compiler Error C3824 -'member': this type cannot appear in this context (function parameter, return type, or a static member) +> 'member': this type cannot appear in this context (function parameter, return type, or a static member) + +## Remarks Pinning pointers cannot be function parameters, return types, or declared **`static`**. ## Example -The following sample generates C3824: +The following example generates C3824: ```cpp // C3824a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3825.md b/docs/error-messages/compiler-errors-2/compiler-error-c3825.md index 9b05b9a696c..40293c4ae53 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3825.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3825.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3825" title: "Compiler Error C3825" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3825" +ms.date: 11/04/2016 f1_keywords: ["C3825"] helpviewer_keywords: ["C3825"] -ms.assetid: 18e204a1-f26e-42c6-8d74-2b49cc95f940 --- # Compiler Error C3825 -'class': a managed or WinRTclass can only support managed or WinRTevents +> 'class': a managed or WinRTclass can only support managed or WinRTevents + +## Remarks Only .NET events are supported in managed classes. Only Windows Runtime events are supported in Windows Runtime classes. To fix this error in managed code, change type parameter of `event_source` and `event_receiver` from `native` to `managed`. Alternatively, remove the attribute. ## Example -The following sample generates C3825 and shows how to fix it: +The following example generates C3825 and shows how to fix it: ```cpp // C3825a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3828.md b/docs/error-messages/compiler-errors-2/compiler-error-c3828.md index 42507113264..9fe4e6f0102 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3828.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3828.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3828" title: "Compiler Error C3828" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3828" +ms.date: 11/04/2016 f1_keywords: ["C3828"] helpviewer_keywords: ["C3828"] -ms.assetid: 8d9cee75-9504-4bc8-88b6-2413618a3f45 --- # Compiler Error C3828 -'object type': placement arguments not allowed while creating instances of managed or WinRTclasses +> 'object type': placement arguments not allowed while creating instances of managed or WinRTclasses + +## Remarks When creating an object of a managed type or Windows Runtime type, you cannot use the placement form of operator [ref new, gcnew](../../extensions/ref-new-gcnew-cpp-component-extensions.md) or [new](../../cpp/new-operator-cpp.md). -The following sample generates C3828 and shows how to fix it: +## Example + +The following example generates C3828 and shows how to fix it: ```cpp // C3828a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3830.md b/docs/error-messages/compiler-errors-2/compiler-error-c3830.md index 8ea57b4157b..cbcf4775975 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3830.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3830.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3830" title: "Compiler Error C3830" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3830" +ms.date: 11/04/2016 f1_keywords: ["C3830"] helpviewer_keywords: ["C3830"] -ms.assetid: c9798f88-5001-4067-9fb1-09957ddc6fa8 --- # Compiler Error C3830 -'type1': cannot inherit from 'type2', value types can only inherit from interface classes +> 'type1': cannot inherit from 'type2', value types can only inherit from interface classes + +## Remarks A value type cannot inherit a base class. For more information, see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md). ## Example -The following sample generates C3830: +The following example generates C3830: ```cpp // C3830a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3831.md b/docs/error-messages/compiler-errors-2/compiler-error-c3831.md index 60e02f58a61..2b861984944 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3831.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3831.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3831" title: "Compiler Error C3831" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3831" +ms.date: 11/04/2016 f1_keywords: ["C3831"] helpviewer_keywords: ["C3831"] -ms.assetid: a125d8dc-b75a-4ea0-b6c7-fe7b119dba25 --- # Compiler Error C3831 -'member': 'class' cannot have a pinned data member or a member function returning a pinning pointer +> 'member': 'class' cannot have a pinned data member or a member function returning a pinning pointer + +## Remarks [pin_ptr (C++/CLI)](../../extensions/pin-ptr-cpp-cli.md) was used incorrectly. ## Example -The following sample generates C3831: +The following example generates C3831: ```cpp // C3831a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3832.md b/docs/error-messages/compiler-errors-2/compiler-error-c3832.md index caeebc3ea94..e1e3bdfaa45 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3832.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3832.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Error C3832" title: "Compiler Error C3832" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3832" +ms.date: 11/04/2016 f1_keywords: ["C3832"] helpviewer_keywords: ["C3832"] -ms.assetid: 9a41df82-42e1-4908-958c-76cff9235de0 --- # Compiler Error C3832 -'type library': type library looks as if it was built for 32-bit pointers; please change the 'ptrsize' qualifier +> 'type library': type library looks as if it was built for 32-bit pointers; please change the 'ptrsize' qualifier + +## Remarks Explicit information supplied with the `ptrsize` attribute of the [#import](../../preprocessor/hash-import-directive-cpp.md) directive did not agree with what the compiler found in the type library. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3833.md b/docs/error-messages/compiler-errors-2/compiler-error-c3833.md index a57735b84a7..b129c53c0af 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3833.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3833.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3833" title: "Compiler Error C3833" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3833" +ms.date: 11/04/2016 f1_keywords: ["C3833"] helpviewer_keywords: ["C3833"] -ms.assetid: 8152be53-e01e-48cd-9eef-9de38723664c --- # Compiler Error C3833 -'type' : invalid target type for pointer_type +> 'type' : invalid target type for pointer_type + +## Remarks An [interior_ptr](../../extensions/interior-ptr-cpp-cli.md) or [pin_ptr](../../extensions/pin-ptr-cpp-cli.md) was declared incorrectly. -The following sample generates C3833: +## Examples + +The following example generates C3833: ```cpp // C3833.cpp @@ -34,7 +37,7 @@ int main() { } ``` -The following sample generates C3833: +The following example generates C3833: ```cpp // C3833b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3834.md b/docs/error-messages/compiler-errors-2/compiler-error-c3834.md index 957ff8062bb..f20bfc9b040 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3834.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3834.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3834" title: "Compiler Error C3834" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3834" +ms.date: 11/04/2016 f1_keywords: ["C3834"] helpviewer_keywords: ["C3834"] -ms.assetid: 059e0dc4-300b-4e74-b6c2-41a57831fe2a --- # Compiler Error C3834 -illegal explicit cast to a pinning pointer; use a pinned local variable instead +> illegal explicit cast to a pinning pointer; use a pinned local variable instead + +## Remarks Explicit casts to a pinned pointer are not allowed. ## Example -The following sample generates C3834. +The following example generates C3834. ```cpp // C3834.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3836.md b/docs/error-messages/compiler-errors-2/compiler-error-c3836.md index d033952fdc1..47bcc280d81 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3836.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3836.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3836" title: "Compiler Error C3836" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3836" +ms.date: 11/04/2016 f1_keywords: ["C3836"] helpviewer_keywords: ["C3836"] -ms.assetid: 254f851b-7b7d-4c34-a740-fcf72f6a636a --- # Compiler Error C3836 -static constructor is not allowed to have a member initializer list +> static constructor is not allowed to have a member initializer list + +## Remarks A managed class cannot have a static constructor that also has a member initialization list. Static class constructors are called by the common language runtime to do class initialization, initializing static data members. ## Example -The following sample generates C3836: +The following example generates C3836: ```cpp // C3836a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3838.md b/docs/error-messages/compiler-errors-2/compiler-error-c3838.md index 88b0263bba7..10518be7bfe 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3838.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3838.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3838" title: "Compiler Error C3838" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3838" +ms.date: 11/04/2016 f1_keywords: ["C3838"] helpviewer_keywords: ["C3838"] -ms.assetid: d6f470c2-131a-4a8c-843a-254acd43da83 --- # Compiler Error C3838 -cannot explicitly inherit from 'type' +> cannot explicitly inherit from 'type' + +## Remarks The specified `type` cannot act as a base class in any class. ## Example -The following sample generates C3838: +The following example generates C3838: ```cpp // C3838a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3839.md b/docs/error-messages/compiler-errors-2/compiler-error-c3839.md index 0979234a149..6cc03dfe858 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3839.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3839.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3839" title: "Compiler Error C3839" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3839" +ms.date: 11/04/2016 f1_keywords: ["C3839"] helpviewer_keywords: ["C3839"] -ms.assetid: 0957faff-1e9f-439b-876b-85bd8d2c578d --- # Compiler Error C3839 -cannot change alignment in a managed or WinRT type +> cannot change alignment in a managed or WinRT type + +## Remarks Alignment of variables in managed or Windows Runtime types is controlled by the CLR or Windows Runtime and cannot be modified with [align](../../cpp/align-cpp.md). -The following sample generates C3839: +## Example + +The following example generates C3839: ```cpp // C3839a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3842.md b/docs/error-messages/compiler-errors-2/compiler-error-c3842.md index 283392fcc7e..5149f7f4d13 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3842.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3842.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3842" title: "Compiler Error C3842" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3842" +ms.date: 11/04/2016 f1_keywords: ["C3842"] helpviewer_keywords: ["C3842"] -ms.assetid: 41a1a44a-c618-40a2-8d26-7da27d14095d --- # Compiler Error C3842 -'function': 'const' and 'volatile' qualifiers on member functions of WinRT or managed types are not supported +> 'function': 'const' and 'volatile' qualifiers on member functions of WinRT or managed types are not supported + +## Remarks [const](../../cpp/const-cpp.md) and [volatile](../../cpp/volatile-cpp.md) are not supported on member functions of Windows Runtime or managed types. -The following sample generates C3842: +## Example + +The following example generates C3842: ```cpp // C3842a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3846.md b/docs/error-messages/compiler-errors-2/compiler-error-c3846.md index 8196ca04b3f..4a9caf6f2d3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3846.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3846.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3846" title: "Compiler Error C3846" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3846" +ms.date: 11/04/2016 f1_keywords: ["C3846"] helpviewer_keywords: ["C3846"] -ms.assetid: c470f8a5-106b-4efb-b8dc-e1319e04130f --- # Compiler Error C3846 -'symbol' : cannot import symbol from 'assembly2': as 'symbol' has already been imported from another assembly 'assembly1' +> 'symbol' : cannot import symbol from 'assembly2': as 'symbol' has already been imported from another assembly 'assembly1' + +## Remarks A symbol could not be imported from a referenced assembly because it was previously imported from a referenced assembly. ## Example -The following sample generates C3846: +The following example generates C3846: ```cpp // C3846a.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3848.md b/docs/error-messages/compiler-errors-2/compiler-error-c3848.md index c67ffd0065f..f9bd3b6ac87 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3848.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3848.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3848" title: "Compiler Error C3848" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3848" +ms.date: 11/04/2016 f1_keywords: ["C3848"] helpviewer_keywords: ["C3848"] -ms.assetid: 32d3ccef-01ec-4f8b-bbff-fb9b1a76b4c4 --- # Compiler Error C3848 -expression having type 'type' would lose some const-volatile qualifiers in order to call 'function' +> expression having type 'type' would lose some const-volatile qualifiers in order to call 'function' + +## Remarks A variable with a specified const-volatile type can only call member functions defined with same or greater const-volatile qualifications. -The following samples generate C3848: +## Example + +The following example generate C3848: ```cpp // C3848.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3849.md b/docs/error-messages/compiler-errors-2/compiler-error-c3849.md index 2945bd37e2b..923c5269c4b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3849.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3849.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3849" title: "Compiler Error C3849" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3849" +ms.date: 11/04/2016 f1_keywords: ["C3849"] helpviewer_keywords: ["C3849"] -ms.assetid: 5347140e-1a81-4841-98c0-b63d98264b64 --- # Compiler Error C3849 -function-style call on an expression of type 'type' would lose const and/or volatile qualifiers for all number available operator overloads +> function-style call on an expression of type 'type' would lose const and/or volatile qualifiers for all number available operator overloads + +## Remarks A variable with a specified const-volatile type can only call member functions defined with same or greater const-volatile qualifications. To fix this error, provide an appropriate member function. You cannot execute a conversion on a const or volatile qualified object when the conversion causes loss of qualification. You can gain qualifiers but you cannot lose qualifiers in a conversion. -The following samples generate C3849: +## Example + +The following example generate C3849: ```cpp // C3849.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3850.md b/docs/error-messages/compiler-errors-2/compiler-error-c3850.md index e5add0470c0..e5ae957dc8f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3850.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3850.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3850" title: "Compiler Error C3850" -ms.date: "09/05/2018" +description: "Learn more about: Compiler Error C3850" +ms.date: 09/05/2018 f1_keywords: ["C3850"] helpviewer_keywords: ["C3850"] -ms.assetid: 028f3a37-f3ad-4ebc-9168-3cdea47524d4 --- # Compiler Error C3850 @@ -20,7 +19,7 @@ In code compiled as C++, a universal character name may use any valid Unicode co ## Example -The following sample generates C3850, and shows how to fix it: +The following example generates C3850, and shows how to fix it: ```cpp // C3850.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3851.md b/docs/error-messages/compiler-errors-2/compiler-error-c3851.md index 50a7a94eabb..a505013ce14 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3851.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3851.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3851" title: "Compiler Error C3851" -ms.date: "09/05/2018" +description: "Learn more about: Compiler Error C3851" +ms.date: 09/05/2018 f1_keywords: ["C3851"] helpviewer_keywords: ["C3851"] -ms.assetid: da30c21c-33aa-4439-8fb3-2f5021ea4985 --- # Compiler Error C3851 @@ -16,7 +15,7 @@ In code compiled as C++, you cannot use a universal character name that represen ## Example -The following samples generate C3851, and show how to fix it: +The following example generates C3851, and show how to fix it: ```cpp // C3851.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3852.md b/docs/error-messages/compiler-errors-2/compiler-error-c3852.md index af2bf00c9e5..79818b2719a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3852.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3852.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3852" title: "Compiler Error C3852" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3852" +ms.date: 11/04/2016 f1_keywords: ["C3852"] helpviewer_keywords: ["C3852"] -ms.assetid: 194e5c5e-0dfb-414e-86db-791c11eb610c --- # Compiler Error C3852 -'member' having type 'type': aggregate initialization could not initialize this member +> 'member' having type 'type': aggregate initialization could not initialize this member + +## Remarks An attempt was made to assign a default initialization as part of an aggregate initialization to a data member that cannot receive a default initialization in an aggregate initialization. -The following samples generate C3852: +## Example + +The following example generate C3852: ```cpp // C3852.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3853.md b/docs/error-messages/compiler-errors-2/compiler-error-c3853.md index cc8cc07302f..49307be38a6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3853.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3853.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3853" title: "Compiler Error C3853" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3853" +ms.date: 11/04/2016 f1_keywords: ["C3853"] helpviewer_keywords: ["C3853"] -ms.assetid: 5b71805d-52b4-44ec-80ae-37c68d876f6a --- # Compiler Error C3853 -'=': re-initializing a reference or assignment through a reference-to-function is illegal +> '=': re-initializing a reference or assignment through a reference-to-function is illegal + +## Remarks Cannot assign to a reference through a function because functions are not lvalues. -The following samples generate C3853: +## Example + +The following example generates C3853: ```cpp // C3853.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3854.md b/docs/error-messages/compiler-errors-2/compiler-error-c3854.md index 5726a0af135..1884381f47f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3854.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3854.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3854" title: "Compiler Error C3854" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3854" +ms.date: 11/04/2016 f1_keywords: ["C3854"] helpviewer_keywords: ["C3854"] -ms.assetid: 32a9ead0-c6c7-485a-8802-c7b1fe921d3a --- # Compiler Error C3854 -expression to left of '=' evaluates to a function. Cannot assign to a function (a function is not an l-value) +> expression to left of '=' evaluates to a function. Cannot assign to a function (a function is not an l-value) + +## Remarks A reference cannot be reinitialized. Dereferencing a reference to a function yields a function, which is an rvalue, to which you cannot assign. Therefore, you cannot assign through a reference to a function. -The following sample generates C3854: +## Example + +The following example generates C3854: ```cpp // C3854.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3855.md b/docs/error-messages/compiler-errors-2/compiler-error-c3855.md index 94133ecbfa7..070460053f8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3855.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3855.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3855" title: "Compiler Error C3855" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3855" +ms.date: 11/04/2016 f1_keywords: ["C3855"] helpviewer_keywords: ["C3855"] -ms.assetid: ed90f8c0-4154-4243-b066-493913df5727 --- # Compiler Error C3855 -'class': type parameter 'param' is incompatible with the declaration +> 'class': type parameter 'param' is incompatible with the declaration + +## Remarks The compiler found nontype template or generic parameters with different names. This can occur when a specified template parameter in the definition of a template specialization is incompatible with its declaration. -The following sample generates C3855: +## Examples + +The following example generates C3855: ```cpp // C3855.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3856.md b/docs/error-messages/compiler-errors-2/compiler-error-c3856.md index 8ce44778f3f..e4241d6dcc0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3856.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3856.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3856" title: "Compiler Error C3856" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3856" +ms.date: 11/04/2016 f1_keywords: ["C3856"] helpviewer_keywords: ["C3856"] -ms.assetid: 242d9322-c325-4f20-be58-b2be6da56d60 --- # Compiler Error C3856 -'type': class is not a class type +> 'type': class is not a class type + +## Remarks The most common cause for this error is when there are more generic or template parameter lists at the point of definition than there were at the point of declaration. -The following sample generates C3856: +## Examples + +The following example generates C3856: ```cpp // C3856.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3857.md b/docs/error-messages/compiler-errors-2/compiler-error-c3857.md index f1696e055f2..0a64becf2b8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3857.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3857.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3857" title: "Compiler Error C3857" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3857" +ms.date: 11/04/2016 f1_keywords: ["C3857"] helpviewer_keywords: ["C3857"] -ms.assetid: 9f746d1e-9708-4945-bc29-3150d5371d3c --- # Compiler Error C3857 -'type': multiple type parameter lists are not allowed +> 'type': multiple type parameter lists are not allowed + +## Remarks More than one template or generic was specified for the same type, which is not allowed. -The following sample generates C3857: +## Examples + +The following example generates C3857: ```cpp // C3857.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3858.md b/docs/error-messages/compiler-errors-2/compiler-error-c3858.md index 00ac4027fa4..249ac5979b0 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3858.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3858.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3858" title: "Compiler Error C3858" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3858" +ms.date: 11/04/2016 f1_keywords: ["C3858"] helpviewer_keywords: ["C3858"] -ms.assetid: 46e178d5-a55f-4ac6-a9dc-561fbcba5c1f --- # Compiler Error C3858 -'type': cannot be redeclared in current scope +> 'type': cannot be redeclared in current scope + +## Remarks The type cannot be declared twice in the same scope. -The following sample generates C3858: +## Example + +The following example generates C3858: ```cpp // C3858.cpp 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 f2f7e9ae44c..b9c63f460ab 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3859.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3859.md @@ -1,15 +1,36 @@ --- -description: "Learn more about: Compiler Error C3859" title: "Compiler Error C3859" +description: "Learn more about: 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 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 + +## Remarks + +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 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 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. -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). +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-c3860.md b/docs/error-messages/compiler-errors-2/compiler-error-c3860.md index 173f2736ae8..b33bd7e9836 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3860.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3860.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3860" title: "Compiler Error C3860" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3860" +ms.date: 11/04/2016 f1_keywords: ["C3860"] helpviewer_keywords: ["C3860"] -ms.assetid: 1fb5110d-594e-4f1c-8773-888233af1313 --- # Compiler Error C3860 -type argument list following class type name must list parameters in the order used in type parameter list +> type argument list following class type name must list parameters in the order used in type parameter list + +## Remarks A generic or template argument list was ill formed. -The following sample generates C3860: +## Examples + +The following example generates C3860: ```cpp // C3860.cpp 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 3675124e82f..b45f6623ab7 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3861.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3861.md @@ -1,19 +1,18 @@ --- -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 > '*identifier*': identifier not found -The compiler was unable to resolve a reference to an identifier, even using argument-dependent lookup. - ## Remarks +The compiler was unable to resolve a reference to an identifier, even using argument-dependent lookup. + To fix this error, compare use of *identifier* to the identifier declaration for case and spelling. Verify that [scope resolution operators](../../cpp/scope-resolution-operator.md) and namespace [`using` directives](../../cpp/namespaces-cpp.md#using_directives) are used correctly. If the identifier is declared in a header file, verify that the header is included before the identifier is referenced. If the identifier is meant to be externally visible, make sure that it's declared in any source file that uses it. Also check that the identifier declaration or definition isn't excluded by [conditional compilation directives](../../preprocessor/hash-if-hash-elif-hash-else-and-hash-endif-directives-c-cpp.md). Changes to remove obsolete functions from the C Runtime Library in Visual Studio 2015 can cause C3861. To resolve this error, remove references to these functions or replace them with their secure alternatives, if any. For more information, see [Obsolete functions](../../c-runtime-library/obsolete-functions.md). @@ -24,7 +23,7 @@ If error C3861 appears after project migration from older versions of the compil ### Undefined identifier -The following sample generates C3861 because the identifier isn't defined. +The following example generates C3861 because the identifier isn't defined. ```cpp // C3861.cpp @@ -37,7 +36,7 @@ int main() { ### Identifier not in scope -The following sample generates C3861, because an identifier is only visible in the file scope of its definition, unless it's declared in other source files that use it. +The following example generates C3861, because an identifier is only visible in the file scope of its definition, unless it's declared in other source files that use it. Source file `C3861_a1.cpp`: @@ -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 example 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-c3862.md b/docs/error-messages/compiler-errors-2/compiler-error-c3862.md index 583cd4c16f4..8bfa574489d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3862.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3862.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Error C3862" title: "Compiler Error C3862" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3862" +ms.date: 11/04/2016 f1_keywords: ["C3862"] helpviewer_keywords: ["C3862"] -ms.assetid: ba547366-4189-4077-8c00-ab45e08a9533 --- # Compiler Error C3862 @@ -20,7 +19,7 @@ For more information, see [/clr (Common Language Runtime Compilation)](../../bui ## Example -The following sample generates C3862: +The following example generates C3862: ```cpp // C3862.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3865.md b/docs/error-messages/compiler-errors-2/compiler-error-c3865.md index 587ea10aba1..147494f98db 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3865.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3865.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3865" title: "Compiler Error C3865" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3865" +ms.date: 11/04/2016 f1_keywords: ["C3865"] helpviewer_keywords: ["C3865"] -ms.assetid: 9bc62bb0-4fb8-4856-a5cf-c7cb4029a596 --- # Compiler Error C3865 -'calling_convention' : can only be used on native member functions +> 'calling_convention' : can only be used on native member functions + +## Remarks A calling convention was used on a function that was either a global function or on a managed member function. The calling convention can only be used on a native (not managed) member function. For more information, see [Calling Conventions](../../cpp/calling-conventions.md). -The following sample generates C3865: +## Example + +The following example generates C3865: ```cpp // C3865.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3866.md b/docs/error-messages/compiler-errors-2/compiler-error-c3866.md index 71d634a4b5e..655db97c3ad 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3866.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3866.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3866" title: "Compiler Error C3866" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3866" +ms.date: 11/04/2016 f1_keywords: ["C3866"] helpviewer_keywords: ["C3866"] -ms.assetid: 685870af-2440-4cdf-a6cb-284a5b96ef9d --- # Compiler Error C3866 -function call missing argument list +> function call missing argument list + +## Remarks Inside a nonstatic member function, a destructor or finalizer call did not have an argument list. -The following sample generates C3866: +## Example + +The following example generates C3866: ```cpp // C3866.cpp 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 8a22a876fe6..a3426c61f3b 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3867.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3867.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3867" title: "Compiler Error C3867" -ms.date: "11/04/2016" +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 -'func': function call missing argument list; use '&func' to create a pointer to member +> 'func': function call missing argument list; use '&func' to create a pointer to member + +## Remarks You tried to take the address of a member function without qualifying the member function with its class name and the address-of operator. @@ -18,7 +19,7 @@ This error can also be generated as a result of compiler conformance work that w C3867 can be issued from the compiler with a misleading suggested resolution. Whenever possible, use the most derived class. -The following sample generates C3867 and shows how to fix it. +The following example generates C3867 and shows how to fix it. ```cpp // C3867_1.cpp @@ -38,11 +39,11 @@ void Derived::Bar() { } ``` -The following sample generates C3867 and shows how to fix it. +The following example generates C3867 and shows how to fix it. ```cpp // C3867_2.cpp -#include +#include struct S { char *func() { @@ -68,7 +69,7 @@ int main() { } ``` -The following sample generates C3867 and shows how to fix it. +The following example generates C3867 and shows how to fix it. ```cpp // C3867_3.cpp @@ -85,7 +86,7 @@ int main() { } ``` -The following sample generates C3867. +The following example generates C3867. ```cpp // C3867_4.cpp @@ -107,7 +108,7 @@ public: }; ``` -The following sample generates C3867. +The following example generates C3867. ```cpp // C3867_5.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3868.md b/docs/error-messages/compiler-errors-2/compiler-error-c3868.md index d3eb1d2f2e4..3276521fff2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3868.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3868.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3868" title: "Compiler Error C3868" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3868" +ms.date: 11/04/2016 f1_keywords: ["C3868"] helpviewer_keywords: ["C3868"] -ms.assetid: f0e45c2a-2149-4885-a03b-0d230069f03a --- # Compiler Error C3868 -'type': constraints on generic parameter 'parameter' differ from those on the declaration +> 'type': constraints on generic parameter 'parameter' differ from those on the declaration + +## Remarks Multiple declarations must have the same generic constraints. For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The following sample generates C3868. +The following example generates C3868. ```cpp // C3868.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3869.md b/docs/error-messages/compiler-errors-2/compiler-error-c3869.md index 6df2c9c037f..6264bd6bdf2 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3869.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3869.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3869" title: "Compiler Error C3869" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3869" +ms.date: 11/04/2016 f1_keywords: ["C3869"] helpviewer_keywords: ["C3869"] -ms.assetid: 85b2ad72-95c1-4ed6-9761-6ef66c3802b7 --- # Compiler Error C3869 -gcnew constraint is missing empty parameter list '()' +> gcnew constraint is missing empty parameter list '()' + +## Remarks The **`gcnew`** special constraint was specified without the empty parameter list. See [Constraints on Generic Type Parameters (C++/CLI)](../../extensions/constraints-on-generic-type-parameters-cpp-cli.md) for more information. ## Example -The following sample generates C3869. +The following example generates C3869. ```cpp // C3869.cpp 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 134462ee8fc..3a5499f3518 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3872.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3872.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3872" title: "Compiler Error C3872" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3872" +ms.date: 11/04/2016 f1_keywords: ["C3872"] helpviewer_keywords: ["C3872"] -ms.assetid: 519e95be-5641-40cc-894c-da4819506604 --- # Compiler Error C3872 -'char': this character is not allowed in an identifier +> 'char': this character is not allowed in an identifier + +## Remarks 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/). + +## Example -The following sample generates C3872: +The following example generates C3872: ```cpp // C3872.cpp 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 4ecff3c14d5..829b2a9a342 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3873.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3873.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3873" title: "Compiler Error C3873" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3873" +ms.date: 11/04/2016 f1_keywords: ["C3873"] helpviewer_keywords: ["C3873"] -ms.assetid: e68fd3be-2391-492b-ac3f-d2428901b2e9 --- # Compiler Error C3873 -'char': this character is not allowed as a first character of an identifier +> 'char': this character is not allowed as a first character of an identifier + +## Remarks 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/). + +## Example -The following sample generates C3873: +The following example generates C3873: ```cpp // C3873.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3874.md b/docs/error-messages/compiler-errors-2/compiler-error-c3874.md index 596ca9d98d1..b6461f75e73 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3874.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3874.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3874" title: "Compiler Error C3874" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3874" +ms.date: 11/04/2016 f1_keywords: ["C3874"] helpviewer_keywords: ["C3874"] -ms.assetid: fd55fc05-69a7-4237-b3b7-dca1d5400b4f --- # Compiler Error C3874 -return type of 'function' should be 'int' instead of 'type' +> return type of 'function' should be 'int' instead of 'type' + +## Remarks A function does not have the return type that was expected by the compiler. -The following sample generates C3874: +## Example + +The following example generates C3874: ```cpp // C3874b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3880.md b/docs/error-messages/compiler-errors-2/compiler-error-c3880.md index 6a0ac4d45c6..cb33548783f 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3880.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3880.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3880" title: "Compiler Error C3880" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3880" +ms.date: 11/04/2016 f1_keywords: ["C3880"] helpviewer_keywords: ["C3880"] -ms.assetid: b0e05d1e-32d0-4034-9246-f37d23573ea9 --- # Compiler Error C3880 -'var' : cannot be a literal data member +> 'var' : cannot be a literal data member + +## Remarks The type of a [literal](../../extensions/literal-cpp-component-extensions.md) attribute must be, or compile-time convertible to, one of the following types: @@ -18,7 +19,9 @@ The type of a [literal](../../extensions/literal-cpp-component-extensions.md) at - enum with an integral or underlying type -The following sample generates C3880: +## Example + +The following example generates C3880: ```cpp // C3880.cpp 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 5ffa8913d6f..12fcbf17f42 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3883.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3883.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3883" title: "Compiler Error C3883" -ms.date: "11/04/2016" +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 + +## Remarks A variable marked with [initonly](../../dotnet/initonly-cpp-cli.md) was not initialized correctly. -The following sample generates C3883: +## Example + +The following example generates C3883: ```cpp // C3883.cpp @@ -23,7 +26,7 @@ ref struct Y1 { }; ``` -The following sample demonstrates a possible resolution: +The following example demonstrates a possible resolution: ```cpp // C3883b.cpp @@ -34,7 +37,7 @@ ref struct Y1 { }; ``` -The following sample shows how to initialize in a static constructor: +The following example shows how to initialize in a static constructor: ```cpp // C3883c.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3886.md b/docs/error-messages/compiler-errors-2/compiler-error-c3886.md index e1973ceb117..5464660fa41 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3886.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3886.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3886" title: "Compiler Error C3886" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3886" +ms.date: 11/04/2016 f1_keywords: ["C3886"] helpviewer_keywords: ["C3886"] -ms.assetid: 485f6c12-cc1b-4146-9034-409a0a5e615e --- # Compiler Error C3886 -'var' : a literal data member must be initialized +> 'var' : a literal data member must be initialized + +## Remarks A [literal](../../extensions/literal-cpp-component-extensions.md) variable must be initialized when it is declaraed. -The following sample generates C3886: +## Example + +The following example generates C3886: ```cpp // C3886.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3887.md b/docs/error-messages/compiler-errors-2/compiler-error-c3887.md index 65c16cb61d9..fae154f26b9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3887.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3887.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3887" title: "Compiler Error C3887" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3887" +ms.date: 11/04/2016 f1_keywords: ["C3887"] helpviewer_keywords: ["C3887"] -ms.assetid: a7e82426-ef99-437b-9562-2822004e18fe --- # Compiler Error C3887 -'var' : the initializer for a literal data member must be a constant expression +> 'var' : the initializer for a literal data member must be a constant expression + +## Remarks A [literal](../../extensions/literal-cpp-component-extensions.md) data member can only be initialized with a constant expresion. -The following sample generates C3887: +## Example + +The following example generates C3887: ```cpp // C3887.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3888.md b/docs/error-messages/compiler-errors-2/compiler-error-c3888.md index b7a9a19d216..42306cab20a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3888.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3888.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3888" title: "Compiler Error C3888" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3888" +ms.date: 11/04/2016 f1_keywords: ["C3888"] helpviewer_keywords: ["C3888"] -ms.assetid: 40820812-79c5-4dcd-a19d-b4164d25fc8a --- # Compiler Error C3888 -'name' : the const expression associated with this literal data member is not supported by C++/CLI +> 'name' : the const expression associated with this literal data member is not supported by C++/CLI + +## Remarks The *name* data member that is declared with the [literal](../../extensions/literal-cpp-component-extensions.md) keyword is initialized with a value the compiler does not support. The compiler supports only constant integral, enum, or string types. The likely cause for the **C3888** error is that the data member is initialized with a byte array. diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3890.md b/docs/error-messages/compiler-errors-2/compiler-error-c3890.md index 22c57edd6cd..5034b0196cf 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3890.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3890.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3890" title: "Compiler Error C3890" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3890" +ms.date: 11/04/2016 f1_keywords: ["C3890"] helpviewer_keywords: ["C3890"] -ms.assetid: 2f22c2fd-c14e-45e1-b936-b739ffc0b135 --- # Compiler Error C3890 -'var' : you cannot take the address of a literal data member +> 'var' : you cannot take the address of a literal data member + +## Remarks A literal data member exists on the garbage-collected heap. An object on the garbage-collected heap can be moved, so taking the address is not useful. -The following sample generates C3890: +## Example + +The following example generates C3890: ```cpp // C3890.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3891.md b/docs/error-messages/compiler-errors-2/compiler-error-c3891.md index d21a7d8e696..e59a0a50479 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3891.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3891.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3891" title: "Compiler Error C3891" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3891" +ms.date: 11/04/2016 f1_keywords: ["C3891"] helpviewer_keywords: ["C3891"] -ms.assetid: 6e1a9458-97f5-4580-bc0f-aa97a1bfd20d --- # Compiler Error C3891 -'var' : a literal data member cannot be used as a l-value +> 'var' : a literal data member cannot be used as a l-value + +## Remarks A [literal](../../extensions/literal-cpp-component-extensions.md) variable is const, and its value cannot be changed after it is initialized in the declaration. -The following sample generates C3891: +## Example + +The following example generates C3891: ```cpp // C3891.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3892.md b/docs/error-messages/compiler-errors-2/compiler-error-c3892.md index 283ef497cad..a046e7e6d0e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3892.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3892.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3892" title: "Compiler Error C3892" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3892" +ms.date: 11/04/2016 f1_keywords: ["C3892"] helpviewer_keywords: ["C3892"] -ms.assetid: 83fff42c-ea48-442f-bc2e-b33a6b99d890 --- # Compiler Error C3892 -'var' : you cannot assign to a variable that is const +> 'var' : you cannot assign to a variable that is const + +## Remarks A const variable cannot be changed after it is declared and initialized. -The following sample generates C3892: +## Example + +The following example generates C3892: ```cpp // C3892.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3893.md b/docs/error-messages/compiler-errors-2/compiler-error-c3893.md index b77022a2fd5..3585d8de062 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3893.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3893.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3893" title: "Compiler Error C3893" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3893" +ms.date: 11/04/2016 f1_keywords: ["C3893"] helpviewer_keywords: ["C3893"] -ms.assetid: 90d52eae-6ef2-4db1-b7ad-92f9e8b140fb --- # Compiler Error C3893 -'var' : l-value use of initonly data member is only allowed in an instance constructor of class 'type_name' +> 'var' : l-value use of initonly data member is only allowed in an instance constructor of class 'type_name' + +## Remarks Static [initonly](../../dotnet/initonly-cpp-cli.md) data members can only have their address taken in a static constructor. Instance (non-static) initonly data members can only have their address taken in instance (non-static) constructors. -The following sample generates C3893: +## Example + +The following example generates C3893: ```cpp // C3893.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3894.md b/docs/error-messages/compiler-errors-2/compiler-error-c3894.md index 15508ee9ee6..72eeb3433d8 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3894.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3894.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3894" title: "Compiler Error C3894" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3894" +ms.date: 11/04/2016 f1_keywords: ["C3894"] helpviewer_keywords: ["C3894"] -ms.assetid: 6d5ac903-1dea-431d-8e3a-cebca4342983 --- # Compiler Error C3894 -'var' : l-value use of initonly static data member is only allowed in the class constructor of class 'class' +> 'var' : l-value use of initonly static data member is only allowed in the class constructor of class 'class' + +## Remarks Static [initonly](../../dotnet/initonly-cpp-cli.md) data members can only be used as l-values at their point of declaration, or in a static constructor. Instance (non-static) initonly data members can only be used as l-values at their point of declaration, or in instance (non-static) constructors. -The following sample generates C3894: +## Example + +The following example generates C3894: ```cpp // C3894.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3895.md b/docs/error-messages/compiler-errors-2/compiler-error-c3895.md index 1bdeb12441e..3b970022dbf 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3895.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3895.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3895" title: "Compiler Error C3895" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3895" +ms.date: 11/04/2016 f1_keywords: ["C3895"] helpviewer_keywords: ["C3895"] -ms.assetid: 771b9fe5-d6d4-4297-bf57-e2f857722155 --- # Compiler Error C3895 -'var' : type data members cannot be 'volatile' +> 'var' : type data members cannot be 'volatile' + +## Remarks Certain kinds of data members, for example [literal](../../extensions/literal-cpp-component-extensions.md) or [initonly](../../dotnet/initonly-cpp-cli.md), cannot be [volatile](../../cpp/volatile-cpp.md). -The following sample generates C3895: +## Example + +The following example generates C3895: ```cpp // C3895.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3896.md b/docs/error-messages/compiler-errors-2/compiler-error-c3896.md index fb207c3e781..99836883967 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3896.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3896.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3896" title: "Compiler Error C3896" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3896" +ms.date: 11/04/2016 f1_keywords: ["C3896"] helpviewer_keywords: ["C3896"] -ms.assetid: eb8be0f6-5b4e-4d71-8285-8a2a94f8ba29 --- # Compiler Error C3896 -'member' : improper initializer: this literal data member can only be initialized with 'nullptr' +> 'member' : improper initializer: this literal data member can only be initialized with 'nullptr' + +## Remarks A [literal](../../extensions/literal-cpp-component-extensions.md) data member was initialized incorrectly. See [nullptr](../../extensions/nullptr-cpp-component-extensions.md) for more information. -The following sample generates C3896: +## Example + +The following example generates C3896: ```cpp // C3896.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3898.md b/docs/error-messages/compiler-errors-2/compiler-error-c3898.md index 0665bbe6c7c..dd2fdddb61e 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3898.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3898.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3898" title: "Compiler Error C3898" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3898" +ms.date: 11/04/2016 f1_keywords: ["C3898"] helpviewer_keywords: ["C3898"] -ms.assetid: d9a90df6-87e4-4fe7-ab01-c226ee86bf10 --- # Compiler Error C3898 -'var' : type data members can only be members of managed types +> 'var' : type data members can only be members of managed types + +## Remarks An [initonly](../../dotnet/initonly-cpp-cli.md) data member was declared in a native class. An **`initonly`** data member can only be declared in a CLR class. -The following sample generates C3898: +## Example + +The following example generates C3898: ```cpp // C3898.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3899.md b/docs/error-messages/compiler-errors-2/compiler-error-c3899.md index b8e55730c7f..cd8558439ef 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3899.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3899.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3899" title: "Compiler Error C3899" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3899" +ms.date: 11/04/2016 f1_keywords: ["C3899"] helpviewer_keywords: ["C3899"] -ms.assetid: 14e07e4a-f7a7-4309-baaa-649d69e12e23 --- # Compiler Error C3899 -'var' : l-value use of initonly data member is not allowed directly within a parallel region in class 'class' +> 'var' : l-value use of initonly data member is not allowed directly within a parallel region in class 'class' + +## Remarks An [initonly (C++/CLI)](../../dotnet/initonly-cpp-cli.md) data member cannot be initialized inside that part of a constructor that is in a [parallel](../../parallel/openmp/reference/openmp-directives.md#parallel) region. This is because the compiler does an internal relocation of that code, such that, it is effectively no longer part of the constructor. @@ -16,7 +17,7 @@ To resolve, initialize the initonly data member in the constructor, but outside ## Example -The following sample generates C3899. +The following example generates C3899. ```cpp // C3899.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3900.md b/docs/error-messages/compiler-errors-2/compiler-error-c3900.md index 75f0af0b487..197aefade42 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3900.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3900.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3900" title: "Compiler Error C3900" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3900" +ms.date: 11/04/2016 f1_keywords: ["C3900"] helpviewer_keywords: ["C3900"] -ms.assetid: a94cc561-8fa8-4344-9e01-e81ff462fae5 --- # Compiler Error C3900 -'member': not allowed in current scope +> 'member': not allowed in current scope + +## Remarks Property blocks can contain function declarations and inline function definitions only. No members other than functions are allowed in property blocks. No typedefs, operators, or friend functions are allowed. For more information, see [property](../../extensions/property-cpp-component-extensions.md). Event definitions can only contain access methods and functions. -The following sample generates C3900: +## Examples + +The following example generates C3900: ```cpp // C3900.cpp @@ -27,7 +30,7 @@ ref class X { }; ``` -The following sample generates C3900: +The following example generates C3900: ```cpp // C3900b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3901.md b/docs/error-messages/compiler-errors-2/compiler-error-c3901.md index 391b3327368..65d317906bb 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3901.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3901.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3901" title: "Compiler Error C3901" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3901" +ms.date: 11/04/2016 f1_keywords: ["C3901"] helpviewer_keywords: ["C3901"] -ms.assetid: 19af4141-39ad-4c16-a68f-3ae76f648186 --- # Compiler Error C3901 -'accessor_function': must have return type 'type' +> 'accessor_function': must have return type 'type' + +## Remarks At least one get method's return type must match the property type. For more information, see [property](../../extensions/property-cpp-component-extensions.md). -The following sample generates C3901: +## Example + +The following example generates C3901: ```cpp // C3901.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3902.md b/docs/error-messages/compiler-errors-2/compiler-error-c3902.md index 0dd340d0e69..baf0a90f30a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3902.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3902.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3902" title: "Compiler Error C3902" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3902" +ms.date: 11/04/2016 f1_keywords: ["C3902"] helpviewer_keywords: ["C3902"] -ms.assetid: feb3bb29-f836-4d77-ba71-3876f7f4f216 --- # Compiler Error C3902 -'accessor': type of last parameter must be 'type' +> 'accessor': type of last parameter must be 'type' + +## Remarks The type of the last parameter of at least one set method must match the type of the property. For more information, see [property](../../extensions/property-cpp-component-extensions.md). -The following sample generates C3902: +## Example + +The following example generates C3902: ```cpp // C3902.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3903.md b/docs/error-messages/compiler-errors-2/compiler-error-c3903.md index d64e3d81a8b..98033fe2afd 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3903.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3903.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3903" title: "Compiler Error C3903" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3903" +ms.date: 11/04/2016 f1_keywords: ["C3903"] helpviewer_keywords: ["C3903"] -ms.assetid: cf47d7ad-a3bd-4f75-a253-71586e7a3be6 --- # Compiler Error C3903 -'property': does not have set or get method +> 'property': does not have set or get method + +## Remarks A property must have at least a `get` or a `set` method. For more information, see [property](../../extensions/property-cpp-component-extensions.md). -The following sample generates C3903: +## Example + +The following example generates C3903: ```cpp // C3903.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3904.md b/docs/error-messages/compiler-errors-2/compiler-error-c3904.md index 948b386d8d0..1da734c8c62 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3904.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3904.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3904" title: "Compiler Error C3904" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3904" +ms.date: 11/04/2016 f1_keywords: ["C3904"] helpviewer_keywords: ["C3904"] -ms.assetid: 08297605-e4f2-4c6c-b637-011f1fd40631 --- # Compiler Error C3904 -'property_accessor': must specify number parameter(s) +> 'property_accessor': must specify number parameter(s) + +## Remarks Check the number of parameters in your `get` and `set` methods against property dimensions. @@ -20,7 +21,7 @@ For more information, see [property](../../extensions/property-cpp-component-ext ## Examples -The following sample generates C3904. +The following example generates C3904. ```cpp // C3904.cpp @@ -40,7 +41,7 @@ ref class X { }; ``` -The following sample generates C3904. +The following example generates C3904. ```cpp // C3904b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3908.md b/docs/error-messages/compiler-errors-2/compiler-error-c3908.md index dfbf987ce71..5c4f692b586 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3908.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3908.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3908" title: "Compiler Error C3908" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3908" +ms.date: 11/04/2016 f1_keywords: ["C3908"] helpviewer_keywords: ["C3908"] -ms.assetid: 3c322482-c79e-4197-a578-2ad9bc379d1a --- # Compiler Error C3908 -access level less restrictive than 'construct' +> access level less restrictive than 'construct' + +## Remarks A property accessor method (get or set) cannot have less restrictive access than the access specified on the property itself. Similarly, for event accessor methods. For more information, see [property](../../extensions/property-cpp-component-extensions.md) and [event](../../extensions/event-cpp-component-extensions.md). -The following sample generates C3908: +## Example + +The following example generates C3908: ```cpp // C3908.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3909.md b/docs/error-messages/compiler-errors-2/compiler-error-c3909.md index 0ab76f3c406..205c07d12ce 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3909.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3909.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3909" title: "Compiler Error C3909" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3909" +ms.date: 11/04/2016 f1_keywords: ["C3909"] helpviewer_keywords: ["C3909"] -ms.assetid: 0a443132-e53f-42dc-a58b-f086da3e7bfd --- # Compiler Error C3909 -aWinRT or managed event declaration must occur in a WinRT or managed type +> a WinRT or managed event declaration must occur in a WinRT or managed type + +## Remarks A Windows Runtime event or managed event was declared in a native type. To fix this error, declare events in Windows Runtime types or managed types. For more information, see [event](../../extensions/event-cpp-component-extensions.md). -The following sample generates C3909 and shows how to fix it: +## Example + +The following example generates C3909 and shows how to fix it: ```cpp // C3909.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3910.md b/docs/error-messages/compiler-errors-2/compiler-error-c3910.md index 9b78fc9761a..ddd865d127d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3910.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3910.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3910" title: "Compiler Error C3910" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3910" +ms.date: 11/04/2016 f1_keywords: ["C3910"] helpviewer_keywords: ["C3910"] -ms.assetid: cfcbe620-b463-463b-95ea-2d60ad33ebb5 --- # Compiler Error C3910 -'event': must define member 'method' +> 'event': must define member 'method' + +## Remarks An event was defined, but did not contain the specified, required accessor method. For more information, see [event](../../extensions/event-cpp-component-extensions.md). -The following sample generates C3910: +## Example + +The following example generates C3910: ```cpp // C3910.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3911.md b/docs/error-messages/compiler-errors-2/compiler-error-c3911.md index 06637b605a0..57fa57784be 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3911.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3911.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3911" title: "Compiler Error C3911" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3911" +ms.date: 11/04/2016 f1_keywords: ["C3911"] helpviewer_keywords: ["C3911"] -ms.assetid: b786da59-0e99-479d-bc0d-551126e940f2 --- # Compiler Error C3911 -'event_accessor_method': function must have type 'signature' +> 'event_accessor_method': function must have type 'signature' + +## Remarks An event's accessor method was not properly declared. For more information, see [event](../../extensions/event-cpp-component-extensions.md). -The following sample generates C3911: +## Example + +The following example generates C3911: ```cpp // C3911.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3912.md b/docs/error-messages/compiler-errors-2/compiler-error-c3912.md index 60a7683cfe9..57daf670a72 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3912.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3912.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3912" title: "Compiler Error C3912" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3912" +ms.date: 11/04/2016 f1_keywords: ["C3912"] helpviewer_keywords: ["C3912"] -ms.assetid: 674e050c-11fb-4db1-8bdf-a3e95b41161d --- # Compiler Error C3912 -'event': type of event must be a delegate type +> 'event': type of event must be a delegate type + +## Remarks An event was declared but was not of the proper type. For more information, see [event](../../extensions/event-cpp-component-extensions.md). -The following sample generates C3912: +## Example + +The following example generates C3912: ```cpp // C3912.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3913.md b/docs/error-messages/compiler-errors-2/compiler-error-c3913.md index 29bf729fda1..b9e510d71f6 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3913.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3913.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3913" title: "Compiler Error C3913" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3913" +ms.date: 11/04/2016 f1_keywords: ["C3913"] helpviewer_keywords: ["C3913"] -ms.assetid: a678bfce-9524-470d-9f23-7d08ecb972c8 --- # Compiler Error C3913 -default property must be indexed +> default property must be indexed + +## Remarks A default property was defined incorrectly. For more information, see [property](../../extensions/property-cpp-component-extensions.md). -The following sample generates C3913: +## Example + +The following example generates C3913: ```cpp // C3913.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3914.md b/docs/error-messages/compiler-errors-2/compiler-error-c3914.md index e50e306dc7e..e97f908f234 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3914.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3914.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3914" title: "Compiler Error C3914" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3914" +ms.date: 11/04/2016 f1_keywords: ["C3914"] helpviewer_keywords: ["C3914"] -ms.assetid: 8f3190e6-ee50-4916-9ecc-3b8748b2e1e7 --- # Compiler Error C3914 -a default property cannot be static +> a default property cannot be static + +## Remarks A default property was declared incorrectly. For more information, see [How to: Use Properties in C++/CLI](../../dotnet/how-to-use-properties-in-cpp-cli.md). ## Example -The following sample generates C3914 and shows how to fix it. +The following example generates C3914 and shows how to fix it. ```cpp // C3914.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3915.md b/docs/error-messages/compiler-errors-2/compiler-error-c3915.md index 8c882d38401..afda8542b14 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3915.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3915.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3915" title: "Compiler Error C3915" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3915" +ms.date: 11/04/2016 f1_keywords: ["C3915"] helpviewer_keywords: ["C3915"] -ms.assetid: 2b0a5e5f-3aec-4a4b-9157-233031817084 --- # Compiler Error C3915 -'type' has no default indexed property (class indexer) +> 'type' has no default indexed property (class indexer) + +## Remarks A type does not have a default, indexed property. @@ -16,7 +17,7 @@ For more information, see [property](../../extensions/property-cpp-component-ext ## Examples -The following sample generates C3915. +The following example generates C3915. ```cpp // C3915.cpp @@ -41,7 +42,7 @@ int main() { C3915 can also occur if you attempt to consume a default indexer in the same compiland where it was defined with . -The following sample generates C3915. +The following example generates C3915. ```cpp // C3915_b.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3917.md b/docs/error-messages/compiler-errors-2/compiler-error-c3917.md index 1fceea56f9f..9ecc4cdf305 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3917.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3917.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Error C3917" title: "Compiler Error C3917" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3917" +ms.date: 11/04/2016 f1_keywords: ["C3917"] helpviewer_keywords: ["C3917"] -ms.assetid: a24cd0c9-262f-46e5-9488-1c01f945933d --- # Compiler Error C3917 -'*property*': obsolete construct declaration style +> '*property*': obsolete construct declaration style + +## Remarks A property or event definition used syntax from a version before Visual Studio 2005. @@ -16,6 +17,8 @@ For more information, see [property](../../extensions/property-cpp-component-ext ## Example +The following example generates C3917: + ```cpp // C3917.cpp // compile with: /clr /c diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3918.md b/docs/error-messages/compiler-errors-2/compiler-error-c3918.md index 77d654ba213..b85f5c2b89c 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3918.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3918.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Error C3918" title: "Compiler Error C3918" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3918" +ms.date: 11/04/2016 f1_keywords: ["C3918"] helpviewer_keywords: ["C3918"] -ms.assetid: a8b3a90a-3fe1-4244-a5ff-a31cdae97d98 --- # Compiler Error C3918 -usage requires 'member' to be a data member +> usage requires 'member' to be a data member + +## Remarks C3918 can occur for several reasons related to events. ## Examples -C3918 can occur because a class member is required in the current context. The following sample generates C3918. +C3918 can occur because a class member is required in the current context. The following example generates C3918. ```cpp // C3918.cpp @@ -36,7 +37,7 @@ public: C3918 is also caused if you try to check a trivial event for null (the event name will no longer provide direct access to the backing store delegate for the event). -The following sample generates C3918. +The following example generates C3918. ```cpp // C3918_2.cpp @@ -57,7 +58,7 @@ ref struct EventSource : public IEFace { }; ``` -C3918 can also occur if you incorrectly subscribe to an event. The following sample generates C3918. +C3918 can also occur if you incorrectly subscribe to an event. The following example generates C3918. ```cpp // C3918_3.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3919.md b/docs/error-messages/compiler-errors-2/compiler-error-c3919.md index 97f0dacc47f..c81a7c540df 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3919.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3919.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Error C3919" title: "Compiler Error C3919" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3919" +ms.date: 11/04/2016 f1_keywords: ["C3919"] helpviewer_keywords: ["C3919"] -ms.assetid: 5f8eddda-d751-478b-930d-e18f7191ddfb --- # Compiler Error C3919 -'event_method': function must have type 'type' +> 'event_method': function must have type 'type' + +## Remarks An event accessor method was not declared correctly. For more information about events, see [event](../../extensions/event-cpp-component-extensions.md). -The following sample generates C3919: +## Example + +The following example generates C3919: ```cpp // C3919.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3920.md b/docs/error-messages/compiler-errors-2/compiler-error-c3920.md index 0784fc24d37..47b2bb58c3a 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3920.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3920.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Error C3920" title: "Compiler Error C3920" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3920" +ms.date: 11/04/2016 f1_keywords: ["C3920"] helpviewer_keywords: ["C3920"] -ms.assetid: 66e91f28-ed82-4ce2-bf22-c0c74905b1ed --- # Compiler Error C3920 -'operator'' : cannot define a postfix increment/decrement WinRT or CLR operator Calling the postfix WinRT or CLR operator will call the corresponding prefix WinRT or CLR operator (op_Increment/op_Decrement), but with postfix semantics +> 'operator'' : cannot define a postfix increment/decrement WinRT or CLR operator Calling the postfix WinRT or CLR operator will call the corresponding prefix WinRT or CLR operator (op_Increment/op_Decrement), but with postfix semantics + +## Remarks The Windows Runtime and CLR do not support the postfix operator and user-defined postfix operators are not allowed. You can define a prefix operator and the prefix operator will be used for both pre- and post-increment operations. -The following sample generates C3920 and shows how to fix it: +## Example + +The following example generates C3920 and shows how to fix it: ```cpp // C3920.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c3923.md b/docs/error-messages/compiler-errors-2/compiler-error-c3923.md index 8b30a7fb64b..5ab80466ed9 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c3923.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c3923.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Compiler Error C3923" title: "Compiler Error C3923" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Error C3923" +ms.date: 11/04/2016 f1_keywords: ["C3923"] helpviewer_keywords: ["C3923"] -ms.assetid: db8838e9-6344-4cd6-83e0-a8abeb12c4c0 --- # Compiler Error C3923 -'member' : local class, struct, or union definitions are not allowed in a member function of a WinRT or managed class +> 'member' : local class, struct, or union definitions are not allowed in a member function of a WinRT or managed class ## Example -The following sample generates C3923. +The following example generates C3923. ```cpp // C3923.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c7510.md b/docs/error-messages/compiler-errors-2/compiler-error-c7510.md index c528336d5bd..b22fad3bdd3 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c7510.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c7510.md @@ -1,6 +1,6 @@ --- -description: "Learn about the causes of Compiler error C7510 and how to fix it." title: "Compiler Error C7510" +description: "Learn about the causes of Compiler error C7510 and how to fix it." ms.date: 04/21/2021 f1_keywords: ["C7510"] helpviewer_keywords: ["C7510"] @@ -10,10 +10,10 @@ helpviewer_keywords: ["C7510"] > '*type-name*': use of dependent template name must be prefixed with 'template'\ > '*type-name*': use of dependent type name must be prefixed with 'typename' -In [`/permissive-`](../../build/reference/permissive-standards-conformance.md) mode, the compiler requires the **`template`** keyword to precede a template name when it comes after a dependent [`nested-name-specifier`](../../cpp/scope-resolution-operator.md). Similar rules hold for types qualified by **`typename`**. - ## Remarks +In [`/permissive-`](../../build/reference/permissive-standards-conformance.md) mode, the compiler requires the **`template`** keyword to precede a template name when it comes after a dependent [`nested-name-specifier`](../../cpp/scope-resolution-operator.md). Similar rules hold for types qualified by **`typename`**. + Compiler behavior has changed starting in Visual Studio 2017 version 15.8 under [`/permissive-`](../../build/reference/permissive-standards-conformance.md) mode. The compiler requires the **`template`** or **`typename`** keyword to precede a template or type name when it comes after a dependent *`nested-name-specifier`*. For more information, see [Name resolution for dependent types](../../cpp/name-resolution-for-dependent-types.md) and [Templates and name resolution](../../cpp/templates-and-name-resolution.md). ## Examples @@ -58,7 +58,7 @@ struct X : Base }; ``` -In Visual Studio 2019 under **`/std:c++20`** or later, template function bodies that have **`if constexpr`** statements have extra parsing-related checks enabled. For example, in Visual Studio 2017 the following code produces C7510 only if the **`/permissive-`** option is set. In Visual Studio 2019 the same code raises errors even when the **`/permissive`** option is set: +In Visual Studio 2019 under **`/std:c++20`** or later, function template bodies that have **`if constexpr`** statements have extra parsing-related checks enabled. For example, in Visual Studio 2017 the following code produces C7510 only if the **`/permissive-`** option is set. In Visual Studio 2019 the same code raises errors even when the **`/permissive`** option is set: ```cpp // C7510.cpp diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c7536.md b/docs/error-messages/compiler-errors-2/compiler-error-c7536.md index a2f4751a33a..dad516b4b11 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c7536.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c7536.md @@ -1,6 +1,6 @@ --- -description: "Learn about the causes of Compiler error C7536 and how to fix it." title: "Compiler Error C7536" +description: "Learn about the causes of Compiler error C7536 and how to fix it." ms.date: 05/03/2021 f1_keywords: ["C7536"] helpviewer_keywords: ["C7536"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["C7536"] > ifc failed integrity checks. Expected SHA2: '*hash-value*' +## Remarks + The compiler raises C7536 whenever the *`.ifc`* file has been tampered with. The header of the module interface contains an SHA2 hash of the contents below it. On import, the *`.ifc`* file is hashed, then checked against the hash provided in the header. If these don't match, error C7536 is raised: ```Output diff --git a/docs/error-messages/compiler-errors-2/compiler-error-c7553.md b/docs/error-messages/compiler-errors-2/compiler-error-c7553.md index 63cd4464c52..c0f40017200 100644 --- a/docs/error-messages/compiler-errors-2/compiler-error-c7553.md +++ b/docs/error-messages/compiler-errors-2/compiler-error-c7553.md @@ -1,6 +1,6 @@ --- title: "Compiler Error C7553" -description: Compiler Error C7553 description and solution. +description: "Compiler Error C7553 description and solution." ms.date: 02/22/2022 f1_keywords: ["C7553"] helpviewer_keywords: ["C7553"] 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 00000000000..bad39dc8ab9 --- /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 example 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-error-c7742.md b/docs/error-messages/compiler-errors-2/compiler-error-c7742.md new file mode 100644 index 00000000000..dd7fd0b64fd --- /dev/null +++ b/docs/error-messages/compiler-errors-2/compiler-error-c7742.md @@ -0,0 +1,47 @@ +--- +title: "Compiler Error C7742" +description: "Learn more about: Compiler Error C7742" +ms.date: 07/02/2025 +ai-usage: ai-assisted +f1_keywords: ["C7742"] +helpviewer_keywords: ["C7742"] +--- +# Compiler Error C7742 + +> *Identifier*: a forward declaration of an enum can only use a simple identifier + +## Remarks + +The C++ Standard doesn't allow declaring an opaque enumeration using a qualified-id. An opaque enum declaration specifies the name and the underlying type, but doesn't list the enumerators or their values. + +## Example + +The following example generates C7742: + +```cpp +// C7742.cpp +class MyClass +{ +public: + enum MyEnum + { + e1, + e2 + }; +}; + +enum MyClass::MyEnum; // C7742 +``` + +To fix this error, remove the opaque enumeration declaration because it doesn't add anything to the program. + +However, you can define an enumeration with a qualified-id. For example: + +```cpp +struct S +{ + enum E : int; +}; + +enum S::E : int { e1, e2, e3 }; +``` 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 dc47e09a5b9..d018f827b7c 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" -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 +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", "C2554", "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", "C2554", "C2559", "C2560", "C2564", "C2565", "C2576", "C2578", "C2580", "C2590", "C2591", "C2595", "C2596"] --- # 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,14 +63,15 @@ 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 C2556](compiler-error-C2556.md)|'*function1*': overloaded function differs only by return type from '*function2*'| |[Compiler error C2557](compiler-error-C2557.md)|'*identifier*': private and protected members cannot be initialized without a constructor| |[Compiler error C2558](compiler-error-C2558.md)|class '*class*': no copy constructor available or copy constructor is declared 'explicit'| |Compiler error C2559|'*identifier*': cannot overload a member function without ref-qualifier with a member function with ref-qualifier| @@ -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 4c6182230c5..e8cbf106a75 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 9d44ce11f4c..1a597951d4d 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 bd932ee66fb..6ad3bb045bf 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 57c8482859c..f426601753e 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 | @@ -114,8 +113,7 @@ The articles in this section of the documentation explain a subset of the error | [Compiler error C2995](compiler-error-c2995.md) | '*declaration*': function template has already been defined | | [Compiler error C2996](compiler-error-c2996.md) | '*function*': recursive function template definition | | Compiler error C2997 | '*function*': array bound cannot be deduced from a default member initializer | -| [Compiler error C2998](compiler-error-c2998.md) | '*declarator*': cannot be a template definition | -| Compiler error C2999 | UNKNOWN ERROR Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information | +| [Compiler error C2998](compiler-error-c2998.md) | '*identifier*': cannot be a template definition | ## See also diff --git a/docs/error-messages/compiler-errors-2/compiler-errors-c3000-through-c3099.md b/docs/error-messages/compiler-errors-2/compiler-errors-c3000-through-c3099.md index a4abebdc6d7..bcdc2b953e2 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 9bec78ffec9..92e4a1b994d 100644 --- a/docs/error-messages/compiler-errors-2/compiler-errors-c3100-through-c3199.md +++ b/docs/error-messages/compiler-errors-2/compiler-errors-c3100-through-c3199.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler errors C3100 Through C3199" title: "Compiler errors C3100 Through C3199" +description: "Learn more about: 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*' | @@ -103,7 +102,7 @@ The articles in this section of the documentation explain a subset of the error | Compiler error C3184 | Obsolete. | | [Compiler error C3185](compiler-error-c3185.md) | 'typeid': used on managed/WinRT type '*type*', use '*operator*' instead | | Compiler error C3186 | Obsolete. | -| [Compiler error C3187](compiler-error-c3187.md) | '*identifier*': is only available within the body of a function | +| [Compiler error C3187](compiler-error-c3187.md) | '`__func__`': is only available within the body of a function | | Compiler error C3188 | Obsolete. | | [Compiler error C3189](compiler-error-c3189.md) | 'typeid<*declarator*>': this syntax is no longer supported, use::typeid instead (Obsolete in Visual Studio 2022.) | | [Compiler error C3190](compiler-error-c3190.md) | '*declarator*' with the provided template arguments is not the explicit instantiation of any member function of '*type*' | 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 e835858c672..87483c7cfe9 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 550a6e1eb62..691f9c0e369 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 ce25161b6d6..688a5b80ca1 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 414f0b1067e..e1469d0230f 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 8ffe57121de..02b5801c7bd 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"] +description: "Learn more about: Compiler errors C7500 through C7999" +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", "C7598", "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", "C7665", "C7666", "C7667", "C7668", "C7669", "C7670", "C7671", "C7672", "C7673", "C7674", "C7675", "C7676", "C7677", "C7678", "C7679", "C7680", "C7682", "C7683", "C7684", "C7685", "C7686", "C7687", "C7689", "C7690", "C7691", "C7692", "C7693", "C7694", "C7695", "C7696", "C7697", "C7698", "C7699", "C7700", "C7701", "C7702", "C7703", "C7704", "C7705", "C7706", "C7707", "C7708", "C7709", "C7710", "C7711", "C7712", "C7713", "C7714", "C7720", "C7730", "C7731", "C7732", "C7733", "C7734", "C7735", "C7736", "C7737", "C7738", "C7739", "C7740", "C7741", "C7800", "C7801", "C7802", "C7803", "C7804", "C7806", "C7807"] +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", "C7598", "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", "C7665", "C7666", "C7667", "C7668", "C7669", "C7670", "C7671", "C7672", "C7673", "C7674", "C7675", "C7676", "C7677", "C7678", "C7679", "C7680", "C7682", "C7683", "C7684", "C7685", "C7686", "C7687", "C7689", "C7690", "C7691", "C7692", "C7693", "C7694", "C7695", "C7696", "C7697", "C7698", "C7699", "C7700", "C7701", "C7702", "C7703", "C7704", "C7705", "C7706", "C7707", "C7708", "C7709", "C7710", "C7711", "C7712", "C7713", "C7714", "C7720", "C7730", "C7731", "C7732", "C7733", "C7734", "C7735", "C7736", "C7737", "C7738", "C7739", "C7740", "C7741", "C7800", "C7801", "C7802", "C7803", "C7804", "C7806", "C7807"] --- # 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,81 @@ 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 C7742](compiler-error-c7742.md) | '*identifier*': a forward declaration of an enum can only use a simple identifier | +| Compiler error C7743 | [`__preserve_none` calling convention](../../cpp/preserve-none.md) is not supported | +| 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 0e51dcf410b..44dfa2efae5 100644 --- a/docs/error-messages/compiler-warnings/c4371.md +++ b/docs/error-messages/compiler-warnings/c4371.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4371" -title: "Compiler Warning (level 3) C4371" -ms.date: "01/31/2018" +title: "Compiler Warning (level 3, off) C4371" +description: "Learn more about: Compiler Warning (level 3, off) C4371" +ms.date: 01/31/2018 f1_keywords: ["C4371"] helpviewer_keywords: ["C4371"] --- @@ -9,6 +9,8 @@ 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. +## Remarks + +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 1f8cc6b7f95..5f4c698f08e 100644 --- a/docs/error-messages/compiler-warnings/c4388.md +++ b/docs/error-messages/compiler-warnings/c4388.md @@ -1,25 +1,25 @@ --- -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 -Using the *token* operator to compare a **`signed`** and a larger **`unsigned`** number required the compiler to convert the **`signed`** value to the larger **`unsigned`** type. - ## Remarks +Using the *token* operator to compare a **`signed`** and a larger **`unsigned`** number required the compiler to convert the **`signed`** value to the larger **`unsigned`** type. + One way to fix this warning is if you cast one of the two types when you compare **`signed`** and larger **`unsigned`** types. This warning is off by default. You can use [/Wall](../../build/reference/compiler-option-warning-level.md) or **`/w44388`** to enable it on the command line as a level 4 warning. Or, use [`#pragma warning(default:4388)`](../../preprocessor/warning.md) in your source file. For more information, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). ## Example -This sample generates C4388 and shows how to fix it: +This example generates C4388 and shows how to fix it: ```cpp // C4388.cpp diff --git a/docs/error-messages/compiler-warnings/c4473.md b/docs/error-messages/compiler-warnings/c4473.md index b10194290b8..5dfe94c2862 100644 --- a/docs/error-messages/compiler-warnings/c4473.md +++ b/docs/error-messages/compiler-warnings/c4473.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4473" title: "Compiler Warning C4473" -ms.date: "02/16/2018" +description: "Learn more about: Compiler Warning (level 1) C4473" +ms.date: 02/16/2018 f1_keywords: ["C4473"] helpviewer_keywords: ["C4473"] --- @@ -54,3 +54,7 @@ void scan_func(int a, float f) ``` In this example, **scanf_s** requires two arguments for each placeholder, one to supply the address to write to, and a second to supply the size of the first. Check the documentation for each library function for an explanation of the required arguments. + +## See also + +[C6064](../../code-quality/c6064.md) diff --git a/docs/error-messages/compiler-warnings/c4477.md b/docs/error-messages/compiler-warnings/c4477.md index 6a661707d9b..e9d25f97453 100644 --- a/docs/error-messages/compiler-warnings/c4477.md +++ b/docs/error-messages/compiler-warnings/c4477.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4477" title: "Compiler Warning C4477" -ms.date: "02/16/2018" +description: "Learn more about: Compiler Warning (level 1) C4477" +ms.date: 02/16/2018 f1_keywords: ["C4477"] helpviewer_keywords: ["C4477"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["C4477"] > '*function*' : format string '*string*' requires an argument of type '*type*', but variadic argument *number* has type '*type*' +## Remarks + The compiler detected a mismatch between the type of argument required to satisfy the placeholder in a format string, and the type of argument supplied. Correct use of the printf and scanf families of variadic functions requires that you supply arguments of the types specified by the format string. A mismatch generally means there is a bug in your code. For information on the arguments associated with printf family format string placeholders, see [Format specification syntax: printf and wprintf functions](../../c-runtime-library/format-specification-syntax-printf-and-wprintf-functions.md). See the documentation for information specific to function *function*. @@ -17,7 +19,7 @@ This warning is new in Visual Studio 2015. ## Example -This sample shows two C4477 warnings for the first printf_s function, when two arguments are found to be of the wrong type, and also shows how to fix the issues. +This example shows two C4477 warnings for the first printf_s function, when two arguments are found to be of the wrong type, and also shows how to fix the issues. ```cpp // C4477p.cpp diff --git a/docs/error-messages/compiler-warnings/c4596.md b/docs/error-messages/compiler-warnings/c4596.md index 9c7afed4d11..1f2156b3c89 100644 --- a/docs/error-messages/compiler-warnings/c4596.md +++ b/docs/error-messages/compiler-warnings/c4596.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4596" title: "Compiler Warning (Level 4) C4596" -ms.date: "08/15/2019" +description: "Learn more about: Compiler Warning (level 4) C4596" +ms.date: 08/15/2019 f1_keywords: ["C4596"] helpviewer_keywords: ["C4596"] --- @@ -19,7 +19,7 @@ This warning is available starting in Visual Studio 2015 Update 3. Code that com ## Example -This sample generates C4596, and shows a way to fix it: +This example generates C4596, and shows a way to fix it: ```cpp // C4596.cpp diff --git a/docs/error-messages/compiler-warnings/c4597.md b/docs/error-messages/compiler-warnings/c4597.md index 9d3a66071fa..55790a29b4f 100644 --- a/docs/error-messages/compiler-warnings/c4597.md +++ b/docs/error-messages/compiler-warnings/c4597.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Warning (error) C4597" title: "Compiler Warning (error) C4597" +description: "Learn more about: Compiler Warning (error) C4597" ms.date: 05/03/2021 f1_keywords: ["C4597"] helpviewer_keywords: ["C4597"] @@ -9,10 +9,10 @@ helpviewer_keywords: ["C4597"] > undefined behavior: `offsetof` applied to a member of a virtual base -Using `offsetof(T, m)` where *`m`* refers to a static data member or a member function results in C4597. - ## Remarks +Using `offsetof(T, m)` where *`m`* refers to a static data member or a member function results in C4597. + This warning is new in Visual Studio 2017 version 15.3. It's reported as an error by default. For information on how to disable warnings by compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). ## Example diff --git a/docs/error-messages/compiler-warnings/c4698.md b/docs/error-messages/compiler-warnings/c4698.md index cc66fdd20a6..91fb47a5c74 100644 --- a/docs/error-messages/compiler-warnings/c4698.md +++ b/docs/error-messages/compiler-warnings/c4698.md @@ -1,6 +1,6 @@ --- -description: "Learn about the cause and fixes for Compiler warning (level 3) C4698." title: "Compiler warning (Level 4) C4698" +description: "Learn about the cause and fixes for Compiler warning (level 3) C4698." ms.date: 04/18/2021 f1_keywords: ["C4698"] helpviewer_keywords: ["C4698"] diff --git a/docs/error-messages/compiler-warnings/c4768.md b/docs/error-messages/compiler-warnings/c4768.md index ac07f56f108..d2338975995 100644 --- a/docs/error-messages/compiler-warnings/c4768.md +++ b/docs/error-messages/compiler-warnings/c4768.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4768" title: "Compiler Warning (level 3) C4768" +description: "Learn more about: Compiler Warning (level 3) C4768" ms.date: 05/03/2021 f1_keywords: ["C4768"] helpviewer_keywords: ["C4768"] @@ -9,10 +9,10 @@ helpviewer_keywords: ["C4768"] > `__declspec` attributes before linkage specification are ignored -The compiler warns if `__declspec(...)` is applied before the `extern "C"` linkage specification. Previously, the compiler would ignore the attribute, which could have runtime implications. - ## Remarks +The compiler warns if `__declspec(...)` is applied before the `extern "C"` linkage specification. Previously, the compiler would ignore the attribute, which could have runtime implications. + This warning is new in Visual Studio 2017 version 15.3, which left it off by default. It's enabled by default as a level 3 warning starting in Visual Studio 2017 version 15.5. For information on how to disable warnings by compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). ## Example diff --git a/docs/error-messages/compiler-warnings/c4770.md b/docs/error-messages/compiler-warnings/c4770.md new file mode 100644 index 00000000000..f82f6915475 --- /dev/null +++ b/docs/error-messages/compiler-warnings/c4770.md @@ -0,0 +1,53 @@ +--- +title: "Compiler Warning (level 4) C4770" +description: "Learn more about: Compiler Warning (level 4) C4770" +ms.date: 11/02/2022 +f1_keywords: ["C4770"] +helpviewer_keywords: ["C4770"] +--- +# Compiler Warning (level 4) C4770 + +> partially validated enum '*symbol*' used as index + +## Remarks + +The compiler warns if an enum value is cast or aliased to an integer type, but the result isn't checked for non-negative or excessive values. + +This warning is new in Visual Studio 2013. It's not enabled by default. To enable it as a level 1 warning, use `/w14770`. For information on how to disable warnings by compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). + +## Example + +The following code produces warning C4770: + +```cpp +// c4770.cpp +// compile by using: cl /GL /w14770 c4770.cpp + +enum E { a 0, b, c, E_MAX }; + +int main(int argc, char *argv[]) +{ + const E e1 = E(argc); // value unknown at compile time + + if ((int)(e1) >= E_MAX) + return 0; + + const int n = e1 + e1; // C4770 partially validated enum used as index + + return argv[n][n]; +} +``` + +To fix the warning, you could cast the value in the check to `unsigned int`, which implicitly forces a non-negative value: + +```cpp + if ((unsigned int)(e1) >= E_MAX) + return 0; +``` + +Or, explicitly check for a non-negative value: + +```cpp + if ((int)(e1) >= E_MAX || (int)(e1) < 0) + return 0; +``` diff --git a/docs/error-messages/compiler-warnings/c4834.md b/docs/error-messages/compiler-warnings/c4834.md index 99cb8784ad3..aca33a0eb14 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 +description: "Learn about the cause and fixes for Compiler warning (level 1) C4834." +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 example 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/c4841.md b/docs/error-messages/compiler-warnings/c4841.md index 89b7db20d63..d4b9c5b80f3 100644 --- a/docs/error-messages/compiler-warnings/c4841.md +++ b/docs/error-messages/compiler-warnings/c4841.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4841" title: "Compiler Warning (level 4) C4841" +description: "Learn more about: Compiler Warning (level 4) C4841" ms.date: 05/03/2021 f1_keywords: ["C4841"] helpviewer_keywords: ["C4841"] diff --git a/docs/error-messages/compiler-warnings/c4843.md b/docs/error-messages/compiler-warnings/c4843.md index f867eaa11b6..857df4af62d 100644 --- a/docs/error-messages/compiler-warnings/c4843.md +++ b/docs/error-messages/compiler-warnings/c4843.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4843" title: "Compiler Warning (level 4) C4843" +description: "Learn more about: Compiler Warning (level 4) C4843" ms.date: 05/03/2021 f1_keywords: ["C4843"] helpviewer_keywords: ["C4843"] @@ -17,7 +17,7 @@ This warning is new in Visual Studio 2017 version 15.5. For information on how t ## Example -This sample shows several **`catch`** statements that cause C4843: +This example shows several **`catch`** statements that cause C4843: ```cpp // C4843_warning.cpp diff --git a/docs/error-messages/compiler-warnings/c4866.md b/docs/error-messages/compiler-warnings/c4866.md index 66c73becda2..5a5400220b3 100644 --- a/docs/error-messages/compiler-warnings/c4866.md +++ b/docs/error-messages/compiler-warnings/c4866.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4866" title: "Compiler Warning (Level 4) C4866" -ms.date: "09/30/2018" +description: "Learn more about: Compiler Warning (level 4) C4866" +ms.date: 09/30/2018 f1_keywords: ["C4866"] helpviewer_keywords: ["C4866"] --- @@ -25,11 +25,11 @@ This warning was introduced in Visual Studio 2017 version 15.9 as a result of co To resolve this warning, first consider whether left-to-right evaluation of the operator elements is necessary, such as when evaluation of the elements might produce order-dependent side-effects. In many cases, the order in which elements are evaluated does not have an observable effect. -If the order of evaluation must be left-to-right, consider whether you can pass the elements by **`const`** reference instead. This change eliminates the warning in the following code sample. +If the order of evaluation must be left-to-right, consider whether you can pass the elements by **`const`** reference instead. This change eliminates the warning in the following code example. ## Example -This sample generates C4866, and shows a way to fix it: +This example generates C4866, and shows a way to fix it: ```cpp // C4866.cpp diff --git a/docs/error-messages/compiler-warnings/c5033.md b/docs/error-messages/compiler-warnings/c5033.md index d60b67afabf..c816d98078c 100644 --- a/docs/error-messages/compiler-warnings/c5033.md +++ b/docs/error-messages/compiler-warnings/c5033.md @@ -1,6 +1,6 @@ --- title: "Compiler warning C5033" -description: Describes the causes and fixes for compiler warning C5033. +description: "Describes the causes and fixes for compiler warning C5033." ms.date: 05/03/2021 f1_keywords: ["C5033"] helpviewer_keywords: ["C5033"] @@ -9,10 +9,10 @@ helpviewer_keywords: ["C5033"] > '*storage-class-keyword*' is no longer a supported storage class -The **`auto`** and **`register`** storage class keywords have been deprecated or removed from the C++ language. - ## Remarks +The **`auto`** and **`register`** storage class keywords have been deprecated or removed from the C++ language. + **Visual Studio 2010 and later:** In C++11, the **`auto`** keyword is no longer a C++ storage-class specifier, and the **`register`** keyword is deprecated. **Visual Studio 2017 version 15.7 and later:** (available in [`/std:c++17`](../../build/reference/std-specify-language-standard-version.md) mode and later): The **`register`** keyword is removed from the C++ language in C++17 and later standards. diff --git a/docs/error-messages/compiler-warnings/c5037.md b/docs/error-messages/compiler-warnings/c5037.md index 95c12967f23..d55293db78a 100644 --- a/docs/error-messages/compiler-warnings/c5037.md +++ b/docs/error-messages/compiler-warnings/c5037.md @@ -1,6 +1,6 @@ --- title: "Compiler warning C5037" -description: Describes the causes and fixes for compiler warning C5037. +description: "Describes the causes and fixes for compiler warning C5037." ms.date: 04/18/2021 f1_keywords: ["C5037"] helpviewer_keywords: ["C5037"] diff --git a/docs/error-messages/compiler-warnings/c5038.md b/docs/error-messages/compiler-warnings/c5038.md index a5ecba20d56..9046d2792d6 100644 --- a/docs/error-messages/compiler-warnings/c5038.md +++ b/docs/error-messages/compiler-warnings/c5038.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5038" -description: Describes the causes and fixes for compiler warning C5038. +description: "Describes the causes and fixes for compiler warning C5038." ms.date: 05/03/2021 f1_keywords: ["C5038"] helpviewer_keywords: ["C5038"] diff --git a/docs/error-messages/compiler-warnings/c5045.md b/docs/error-messages/compiler-warnings/c5045.md index 13e3406a604..d9d9bc3aea7 100644 --- a/docs/error-messages/compiler-warnings/c5045.md +++ b/docs/error-messages/compiler-warnings/c5045.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning C5045" title: "Compiler Warning C5045" -ms.date: "06/21/2018" +description: "Learn more about: Compiler Warning C5045" +ms.date: 06/21/2018 f1_keywords: ["C5045"] helpviewer_keywords: ["C5045"] --- diff --git a/docs/error-messages/compiler-warnings/c5046.md b/docs/error-messages/compiler-warnings/c5046.md index 83c0ba4b116..2cfd74a6498 100644 --- a/docs/error-messages/compiler-warnings/c5046.md +++ b/docs/error-messages/compiler-warnings/c5046.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning (level 2) C5046" title: "Compiler Warning C5046" -ms.date: "03/21/2019" +description: "Learn more about: Compiler Warning (level 2) C5046" +ms.date: 03/21/2019 f1_keywords: ["C5046"] helpviewer_keywords: ["C5046"] --- @@ -25,7 +25,7 @@ This warning is new in Visual Studio 2017 version 15.8. ## Example -This sample shows two C5046 warnings: +This example shows two C5046 warnings: ```cpp // C5046p.cpp diff --git a/docs/error-messages/compiler-warnings/c5050.md b/docs/error-messages/compiler-warnings/c5050.md index 37158601358..7df6abc376f 100644 --- a/docs/error-messages/compiler-warnings/c5050.md +++ b/docs/error-messages/compiler-warnings/c5050.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5050" -description: Compiler warning C5050 description and solution. +description: "Compiler warning C5050 description and solution." ms.date: 05/03/2021 f1_keywords: ["C5050"] helpviewer_keywords: ["C5050"] diff --git a/docs/error-messages/compiler-warnings/c5054.md b/docs/error-messages/compiler-warnings/c5054.md index ba2e219746f..669dbdd5b40 100644 --- a/docs/error-messages/compiler-warnings/c5054.md +++ b/docs/error-messages/compiler-warnings/c5054.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5054" -description: Compiler warning C5054 description and solution. +description: "Compiler warning C5054 description and solution." ms.date: 02/22/2022 f1_keywords: ["C5054"] helpviewer_keywords: ["C5054"] diff --git a/docs/error-messages/compiler-warnings/c5055.md b/docs/error-messages/compiler-warnings/c5055.md index 4cca582e6c3..4a469b06fd3 100644 --- a/docs/error-messages/compiler-warnings/c5055.md +++ b/docs/error-messages/compiler-warnings/c5055.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5055" -description: Compiler warning C5055 description and solution. +description: "Compiler warning C5055 description and solution." ms.date: 02/22/2022 f1_keywords: ["C5055"] helpviewer_keywords: ["C5055"] diff --git a/docs/error-messages/compiler-warnings/c5056.md b/docs/error-messages/compiler-warnings/c5056.md index cb757f7ad98..8d775f210eb 100644 --- a/docs/error-messages/compiler-warnings/c5056.md +++ b/docs/error-messages/compiler-warnings/c5056.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5056" -description: Compiler warning C5056 description and solution. +description: "Compiler warning C5056 description and solution." ms.date: 02/22/2022 f1_keywords: ["C5056"] helpviewer_keywords: ["C5056"] diff --git a/docs/error-messages/compiler-warnings/c5105.md b/docs/error-messages/compiler-warnings/c5105.md index e7167acca07..e1f17302e9a 100644 --- a/docs/error-messages/compiler-warnings/c5105.md +++ b/docs/error-messages/compiler-warnings/c5105.md @@ -1,7 +1,7 @@ --- title: "Compiler Warning C5105" -description: Compiler warning C5105 description and solution. -ms.date: "09/22/2019" +description: "Compiler warning C5105 description and solution." +ms.date: 09/22/2019 f1_keywords: ["C5105"] helpviewer_keywords: ["C5105"] --- @@ -29,7 +29,7 @@ To turn off the warning for an entire project in the Visual Studio IDE: ## Example -This sample program shows how to generate warning C5105, and how to fix it. +This example program shows how to generate warning C5105, and how to fix it. ```cpp // C5105.cpp diff --git a/docs/error-messages/compiler-warnings/c5208.md b/docs/error-messages/compiler-warnings/c5208.md index 53a7f3b9eaf..a1369dcd380 100644 --- a/docs/error-messages/compiler-warnings/c5208.md +++ b/docs/error-messages/compiler-warnings/c5208.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5208, Error C7626" -description: Compiler warning C5208 and error C7626 description and solution. +description: "Compiler warning C5208 and error C7626 description and solution." ms.date: 04/18/2021 f1_keywords: ["C5208", "C7626"] helpviewer_keywords: ["C5208", "C7626"] @@ -33,7 +33,7 @@ To turn off the warning for an entire project in the Visual Studio IDE: ## Example -The following sample shows the constructs that are no longer allowed in unnamed structs. Depending on the standards mode specified, C5208 or C7626 errors or warnings are emitted: +The following example shows the constructs that are no longer allowed in unnamed structs. Depending on the standards mode specified, C5208 or C7626 errors or warnings are emitted: ```cpp struct Base { }; diff --git a/docs/error-messages/compiler-warnings/c5240.md b/docs/error-messages/compiler-warnings/c5240.md index 8389182d68d..942056d2bcd 100644 --- a/docs/error-messages/compiler-warnings/c5240.md +++ b/docs/error-messages/compiler-warnings/c5240.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5240" -description: Compiler warning C5240 description and solution. +description: "Compiler warning C5240 description and solution." ms.date: 02/22/2022 f1_keywords: ["C5240"] helpviewer_keywords: ["C5240"] diff --git a/docs/error-messages/compiler-warnings/c5243.md b/docs/error-messages/compiler-warnings/c5243.md index a2fabbb18e4..3a14cbf8fee 100644 --- a/docs/error-messages/compiler-warnings/c5243.md +++ b/docs/error-messages/compiler-warnings/c5243.md @@ -1,6 +1,6 @@ --- -title: "Compiler Warning C5243" -description: Compiler warning C5243 description and solution. +title: "Compiler warning C5243" +description: "Compiler warning C5243 description and solution." ms.date: 08/09/2021 f1_keywords: ["C5243"] helpviewer_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/c5247.md b/docs/error-messages/compiler-warnings/c5247.md index 6ac55f629e1..f3d1101d2c1 100644 --- a/docs/error-messages/compiler-warnings/c5247.md +++ b/docs/error-messages/compiler-warnings/c5247.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5247" -description: Compiler warning C5247 description and solution. +description: "Compiler warning C5247 description and solution." ms.date: 08/02/2021 f1_keywords: ["C5247"] helpviewer_keywords: ["C5247"] diff --git a/docs/error-messages/compiler-warnings/c5248.md b/docs/error-messages/compiler-warnings/c5248.md index 255771462ec..ea45b79264c 100644 --- a/docs/error-messages/compiler-warnings/c5248.md +++ b/docs/error-messages/compiler-warnings/c5248.md @@ -1,6 +1,6 @@ --- title: "Compiler Warning C5248" -description: Compiler warning C5248 description and solution. +description: "Compiler warning C5248 description and solution." ms.date: 08/02/2021 f1_keywords: ["C5248"] helpviewer_keywords: ["C5248"] diff --git a/docs/error-messages/compiler-warnings/c5262.md b/docs/error-messages/compiler-warnings/c5262.md new file mode 100644 index 00000000000..48fcd340ecc --- /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 example 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 00000000000..a43a8ec9824 --- /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 00000000000..4bc84869d81 --- /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 example 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 3ec3cdd5d39..2f17fe0d623 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4335.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4335.md @@ -1,24 +1,25 @@ --- -description: "Learn more about: Compiler Warning C4335" -title: "Compiler Warning C4335" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1) C4335" +description: "Learn more about: 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'). +## Remarks -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. +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 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. ## Example -The following sample generates C4335. +The following example generates C4335: ```cpp // C4335 expected diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4355.md b/docs/error-messages/compiler-warnings/compiler-warning-c4355.md index 24633d26bd7..132a3ccf66b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4355.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4355.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Warning C4355" -title: "Compiler Warning C4355" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1 and level 4, off) C4355" +description: "Learn more about: 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. +## Remarks -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 `this` pointer is valid only within nonstatic member functions. It can't be used in the initializer list for a 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. +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. -The following sample generates C4355: +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 + +The following example generates C4355: ```cpp // C4355.cpp @@ -26,7 +29,7 @@ The following sample generates C4355: class CDerived; class CBase { public: - CBase(CDerived *derived): m_pDerived(derived) {}; + CBase(CDerived *derived): m_pDerived(derived) {} ~CBase(); virtual void function() = 0; @@ -35,8 +38,8 @@ public: class CDerived : public CBase { public: - CDerived() : CBase(this) {}; // C4355 "this" used in derived c'tor - virtual void function() {}; + CDerived() : CBase(this) {} // C4355 "this" used in derived c'tor + virtual void function() {} }; CBase::~CBase() { diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4368.md b/docs/error-messages/compiler-warnings/compiler-warning-c4368.md index 7808f627b50..94a975c3cd8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4368.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4368.md @@ -1,24 +1,25 @@ --- -description: "Learn more about: Compiler Warning C4368" -title: "Compiler Warning C4368" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4368" +description: "Learn more about: 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. +## Remarks -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'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). This warning is always issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable C4368. ## Example -The following sample generates C4368. +The following example generates C4368. ```cpp // C4368.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4394.md b/docs/error-messages/compiler-warnings/compiler-warning-c4394.md index 95e4d0660aa..128be88cbc4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4394.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4394.md @@ -1,24 +1,25 @@ --- -description: "Learn more about: Compiler Warning C4394" -title: "Compiler Warning C4394" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4394" +description: "Learn more about: 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. +## Remarks + +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 -The following sample generates C4394. +The following example generates C4394. ```cpp // C4394.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4430.md b/docs/error-messages/compiler-warnings/compiler-warning-c4430.md index 15c04e3b0fd..82777f11454 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4430.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4430.md @@ -1,36 +1,35 @@ --- -description: "Learn more about: Compiler Warning C4430" -title: "Compiler Warning C4430" -ms.date: "11/04/2016" +title: "Compiler warning (level 1, error) C4430" +description: "Learn more about: 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. +## Remarks -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. +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`. 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 example 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 f8d402b8386..b4b5b4ffc3e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4439.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4439.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning C4439" -title: "Compiler Warning C4439" -ms.date: "11/04/2016" +title: "Compiler warning (level 1, error) C4439" +description: "Learn more about: 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 + +## Remarks 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 example generates C4439: ```cpp // C4439.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4484.md b/docs/error-messages/compiler-warnings/compiler-warning-c4484.md index fc6a823d68f..72034be28b7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4484.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4484.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning C4484" title: "Compiler Warning C4484" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4484" +ms.date: 11/04/2016 f1_keywords: ["C4484"] helpviewer_keywords: ["C4484"] -ms.assetid: 3d30e5b3-2297-45b7-a37a-1360056fdd0e --- # Compiler Warning C4484 -'override_function' : matches base ref class method 'base_class_function', but is not marked 'virtual', 'new' or 'override'; 'new' (and not 'virtual') is assumed +> 'override_function' : matches base ref class method 'base_class_function', but is not marked 'virtual', 'new' or 'override'; 'new' (and not 'virtual') is assumed + +## Remarks When compiling with **/clr**, the compiler will not implicitly override a base class function, which means the function will get a new slot in the vtable. To resolve, explicitly specify whether a function is an override. @@ -24,7 +25,7 @@ C4484 is always issued as an error. Use the [warning](../../preprocessor/warning ## Example -The following sample generates C4484. +The following example generates C4484. ```cpp // C4484.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4485.md b/docs/error-messages/compiler-warnings/compiler-warning-c4485.md index 29ce3800cd3..6711406f3e3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4485.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4485.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning C4485" title: "Compiler Warning C4485" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4485" +ms.date: 11/04/2016 f1_keywords: ["C4485"] helpviewer_keywords: ["C4485"] -ms.assetid: a6f2b437-ca93-4dcd-b9cb-df415e10df86 --- # Compiler Warning C4485 -'override_function' : matches base ref class method 'base_class_function ', but is not marked 'new' or 'override'; 'new' (and 'virtual') is assumed +> 'override_function' : matches base ref class method 'base_class_function ', but is not marked 'new' or 'override'; 'new' (and 'virtual') is assumed + +## Remarks An accessor overrides, with or without the **`virtual`** keyword, a base class accessor function, but the `override` or **`new`** specifier was not part of the overriding function signature. Add the **`new`** or `override` specifier to resolve this warning. @@ -18,7 +19,7 @@ C4485 is always issued as an error. Use the [warning](../../preprocessor/warning ## Example -The following sample generates C4485 +The following example generates C4485 ```cpp // C4485.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4687.md b/docs/error-messages/compiler-warnings/compiler-warning-c4687.md index 6414748bd3f..c4d55b15351 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4687.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4687.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning C4687" title: "Compiler Warning C4687" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4687" +ms.date: 11/04/2016 f1_keywords: ["C4687"] helpviewer_keywords: ["C4687"] -ms.assetid: 2f28e0b1-7358-4c88-bd70-aad8f0aa004c --- # Compiler Warning C4687 @@ -20,7 +19,7 @@ C4687 is issued as an error by default. You can suppress C4687 with the [warning ## Example -The following sample generates C4687. +The following example generates C4687. ```cpp // C4687.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4693.md b/docs/error-messages/compiler-warnings/compiler-warning-c4693.md index 9603aea04d9..cd9461c3e9a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4693.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4693.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning C4693" title: "Compiler Warning C4693" -ms.date: "10/25/2017" +description: "Learn more about: Compiler Warning C4693" +ms.date: 10/25/2017 f1_keywords: ["C4693"] helpviewer_keywords: ["C4693"] -ms.assetid: 72d8db01-5e6f-4794-8731-76107e8f064a --- # Compiler Warning C4693 > 'class': a sealed abstract class cannot have any instance members 'Test' +## Remarks + If a type is marked [sealed](../../extensions/sealed-cpp-component-extensions.md) and [abstract](../../extensions/abstract-cpp-component-extensions.md), it can only have static members. This warning is automatically promoted to an error. If you wish to modify this behavior, use [#pragma warning](../../preprocessor/warning.md). ## Example -The following sample generates C4693. +The following example generates C4693. ```cpp // C4693.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4694.md b/docs/error-messages/compiler-warnings/compiler-warning-c4694.md index 69a3a53382e..42b5c6af3af 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4694.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4694.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning C4694" title: "Compiler Warning C4694" -ms.date: "10/25/2017" +description: "Learn more about: Compiler Warning C4694" +ms.date: 10/25/2017 f1_keywords: ["C4694"] helpviewer_keywords: ["C4694"] -ms.assetid: 5ca122bb-34f3-43ee-a21f-95802cd515f7 --- # Compiler Warning C4694 > '*class*': a sealed abstract class cannot have a base-class '*base_class*' +## Remarks + An abstract and sealed class cannot inherit from a reference type; a sealed and abstract class can neither implement the base class functions nor allow itself to be used as a base class. For more information, see [abstract](../../extensions/abstract-cpp-component-extensions.md), [sealed](../../extensions/sealed-cpp-component-extensions.md), and [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md). @@ -18,7 +19,7 @@ This warning is automatically promoted to an error. If you wish to modify this b ## Example -The following sample generates C4694. +The following example generates C4694. ```cpp // C4694.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4746.md b/docs/error-messages/compiler-warnings/compiler-warning-c4746.md index 04491bb8f18..529e25e81c6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4746.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4746.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning C4746" title: "Compiler Warning C4746" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4746" +ms.date: 11/04/2016 f1_keywords: ["C4746"] helpviewer_keywords: ["C4746"] -ms.assetid: 5e79ab46-6031-499a-a986-716c866b6c0e --- # Compiler Warning C4746 -volatile access of '\' is subject to /volatile:[iso\|ms] setting; consider using __iso_volatile_load/store intrinsic functions. +> volatile access of '\' is subject to /volatile:[iso\|ms] setting; consider using __iso_volatile_load/store intrinsic functions. + +## Remarks C4746 is emitted whenever a volatile variable is accessed directly. It's intended to help developers identify code locations that are affected by the specific volatile model currently specified (which can be controlled with the [`/volatile`](../../build/reference/volatile-volatile-keyword-interpretation.md) compiler option). In particular, it can be useful in locating compiler-generated hardware memory barriers when `/volatile:ms` is used. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4867.md b/docs/error-messages/compiler-warnings/compiler-warning-c4867.md index 2d3ddc1217c..3826e9e0ecc 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4867.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4867.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning C4867" title: "Compiler Warning C4867" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4867" +ms.date: 11/04/2016 f1_keywords: ["C4867"] helpviewer_keywords: ["C4867"] -ms.assetid: 8a257d70-c3a7-462d-b285-e57c952a8bf7 --- # Compiler Warning C4867 -'function': function call missing argument list; use 'call' to create a pointer to member +> 'function': function call missing argument list; use 'call' to create a pointer to member + +## Remarks A pointer to member function was initialized incorrectly. @@ -18,7 +19,7 @@ This warning is always issued as an error. Use the [warning](../../preprocessor/ ## Example -The following sample generates C4867. +The following example generates C4867. ```cpp // C4867.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4868.md b/docs/error-messages/compiler-warnings/compiler-warning-c4868.md index 8857a084f10..d863beaad53 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4868.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4868.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4868" title: "Compiler Warning C4868" -ms.date: "10/26/2017" +description: "Learn more about: Compiler Warning (level 4) C4868" +ms.date: 10/26/2017 f1_keywords: ["C4868"] helpviewer_keywords: ["C4868"] -ms.assetid: fc6aa7e5-34dd-4ec2-88bd-16e430361dc7 --- # Compiler Warning (level 4) C4868 > '_file_(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initializer list +## Remarks + The elements of a braced initializer list are to be evaluated in left-to-right order. There are two cases in which the compiler is unable to guarantee this order: the first is when some of the elements are objects passed by value; the second is when compiling with `/clr` and some of the elements are fields of objects or are array elements. When the compiler can't guarantee left-to-right evaluation it emits warning C4868. This warning can be generated as a result of compiler conformance work that was done for Visual Studio 2015 Update 2. Code that compiled prior to Visual Studio 2015 Update 2 can now generate C4868. @@ -18,11 +19,11 @@ This warning is off by default. Use `/Wall` to activate this warning. To resolve this warning, first consider whether left-to-right evaluation of the initializer list elements is necessary, such as when evaluation of the elements might produce order-dependent side-effects. In many cases, the order in which elements are evaluated does not have an observable effect. -If the order of evaluation must be left-to-right, consider if it's possible to pass the elements by **`const`** reference instead. A change such as this eliminates the warning in the following code sample. +If the order of evaluation must be left-to-right, consider if it's possible to pass the elements by **`const`** reference instead. A change such as this eliminates the warning in the following code example. ## Example -This sample generates C4868, and shows a way to fix it: +This example generates C4868, and shows a way to fix it: ```cpp // C4868.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4936.md b/docs/error-messages/compiler-warnings/compiler-warning-c4936.md index bd5d2d26f79..73342f7523e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4936.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4936.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning C4936" title: "Compiler Warning C4936" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4936" +ms.date: 11/04/2016 f1_keywords: ["C4936"] helpviewer_keywords: ["C4936"] -ms.assetid: 6676de35-bf1b-4d0b-a70f-b5734130336c --- # Compiler Warning C4936 @@ -22,7 +21,7 @@ C4936 is always issued as an error. You can disable C4936 with the [warning](.. ## Example -The following sample generates C4936: +The following example generates C4936: ```cpp // C4936.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4950.md b/docs/error-messages/compiler-warnings/compiler-warning-c4950.md index e4ca8421480..e7fef9ffffd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4950.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4950.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning C4950" title: "Compiler Warning C4950" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4950" +ms.date: 11/04/2016 f1_keywords: ["C4950"] helpviewer_keywords: ["C4950"] -ms.assetid: 50226a5c-c664-4d09-ac59-e9e874ca244f --- # Compiler Warning C4950 -'type_or_member' : marked as obsolete +> 'type_or_member' : marked as obsolete + +## Remarks A member or type was marked as obsolete with the attribute. @@ -16,7 +17,7 @@ C4950 is always issued as an error. You can turn off this warning by using the [ ## Example -The following sample generates C4950: +The following example generates C4950: ```cpp // C4950.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4956.md b/docs/error-messages/compiler-warnings/compiler-warning-c4956.md index cd8382e9920..d2be88d6b50 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4956.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4956.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning C4956" title: "Compiler Warning C4956" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4956" +ms.date: 11/04/2016 f1_keywords: ["C4956"] helpviewer_keywords: ["C4956"] -ms.assetid: 9154f2d1-d49f-4e07-90d2-0e9bc028011a --- # Compiler Warning C4956 @@ -20,7 +19,7 @@ This warning is issued as an error and can be disabled with the [warning](../../ ## Example -The following sample generates C4956: +The following example generates C4956: ```cpp // C4956.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4957.md b/docs/error-messages/compiler-warnings/compiler-warning-c4957.md index 762111b68af..cf4900c21d3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4957.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4957.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning C4957" title: "Compiler Warning C4957" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4957" +ms.date: 11/04/2016 f1_keywords: ["C4957"] helpviewer_keywords: ["C4957"] -ms.assetid: a18c52d4-23e2-44f1-b4b5-f7fa5a7f3987 --- # Compiler Warning C4957 @@ -24,7 +23,7 @@ This warning is issued as an error and can be disabled with the [warning](../../ ## Example -The following sample generates C4957: +The following example generates C4957: ```cpp // C4957.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4958.md b/docs/error-messages/compiler-warnings/compiler-warning-c4958.md index dffd446ceec..5f8f2fd50c3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4958.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4958.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning C4958" title: "Compiler Warning C4958" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4958" +ms.date: 11/04/2016 f1_keywords: ["C4958"] helpviewer_keywords: ["C4958"] -ms.assetid: e79b9e9c-d572-4a3a-a3b6-60962b70864a --- # Compiler Warning C4958 @@ -20,9 +19,9 @@ The **/clr:safe** compiler option is deprecated in Visual Studio 2015 and unsupp This warning is issued as an error and can be disabled with the [warning](../../preprocessor/warning.md) pragma or the [/wd](../../build/reference/compiler-option-warning-level.md) compiler option. -## Example +## Examples -The following sample generates C4958: +The following example generates C4958: ```cpp // C4958.cpp @@ -39,7 +38,7 @@ int main( ) { The compiler implements array operations with pointer arithmetic. Therefore, native arrays are not verifiable; use a CLR array instead. For more information, see [array](../../extensions/arrays-cpp-component-extensions.md). -The following sample generates C4958: +The following example generates C4958: ```cpp // C4958b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4959.md b/docs/error-messages/compiler-warnings/compiler-warning-c4959.md index f1ac31d8d2e..98be05f3e47 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4959.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4959.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning C4959" title: "Compiler Warning C4959" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4959" +ms.date: 11/04/2016 f1_keywords: ["C4959"] helpviewer_keywords: ["C4959"] -ms.assetid: 3a128f3e-4d8a-4565-ba1a-5d32fdeb5982 --- # Compiler Warning C4959 @@ -22,7 +21,7 @@ This warning is issued as an error and can be disabled with the [warning](../../ ## Example -The following sample generates C4959: +The following example generates C4959: ```cpp // C4959.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4961.md b/docs/error-messages/compiler-warnings/compiler-warning-c4961.md index 59298487148..19f28ac5064 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4961.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4961.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning C4961" title: "Compiler Warning C4961" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4961" +ms.date: 11/04/2016 f1_keywords: ["C4961"] helpviewer_keywords: ["C4961"] -ms.assetid: fe22d99f-5a12-45d3-a7cf-867773a71e16 --- # Compiler Warning C4961 -No profile data was merged into '.pgd file', profile-guided optimizations disabled +> No profile data was merged into '.pgd file', profile-guided optimizations disabled + +## Remarks No profile data (.pgc files) were available, so profile-guided optimizations cannot take place. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4962.md b/docs/error-messages/compiler-warnings/compiler-warning-c4962.md index 3a1468d7299..68e7379ebe0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4962.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4962.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning C4962" title: "Compiler Warning C4962" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4962" +ms.date: 11/04/2016 f1_keywords: ["C4962"] helpviewer_keywords: ["C4962"] -ms.assetid: 62b156fe-04e5-4a6e-9339-6ab148185f87 --- # Compiler Warning C4962 -'function' : Profile-guided optimizations disabled because optimizations caused profile data to become inconsistent" +> 'function' : Profile-guided optimizations disabled because optimizations caused profile data to become inconsistent" + +## Remarks A function was not compiled with /LTCG:PGO, because count (profile) data for the function was unreliable. Redo profiling to regenerate the .pgc file that contains the unreliable profile data for that function. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4972.md b/docs/error-messages/compiler-warnings/compiler-warning-c4972.md index 95e783ed6a2..b115d03e149 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4972.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4972.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning C4972" title: "Compiler Warning C4972" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4972" +ms.date: 11/04/2016 f1_keywords: ["C4972"] helpviewer_keywords: ["C4972"] -ms.assetid: d18e8e65-b2ef-4d75-a207-fbd0c17c9060 --- # Compiler Warning C4972 -Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable +> Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable + +## Remarks Dereferencing a handle to a value type, also known as unboxing, and then assigning to it is not verifiable. @@ -16,7 +17,7 @@ For more information, see [Boxing](../../extensions/boxing-cpp-component-extensi ## Example -The following sample generates C4972. +The following example generates C4972. ```cpp // C4972.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4984.md b/docs/error-messages/compiler-warnings/compiler-warning-c4984.md index 6fb4984b33d..c30dbf85bd3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4984.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4984.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning C4984" title: "Compiler Warning C4984" -ms.date: "08/19/2019" +description: "Learn more about: Compiler Warning C4984" +ms.date: 08/19/2019 f1_keywords: ["C4984"] helpviewer_keywords: ["C4984"] --- @@ -19,7 +19,7 @@ This warning is available starting in Visual Studio 2017 version 15.3. For infor ## Example -This sample generates C4984, and shows ways to fix it: +This example generates C4984, and shows ways to fix it: ```cpp // C4984.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-c4986.md b/docs/error-messages/compiler-warnings/compiler-warning-c4986.md index 7cb4e24c1de..975f37ff915 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-c4986.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-c4986.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning C4986" title: "Compiler Warning C4986" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning C4986" +ms.date: 11/04/2016 f1_keywords: ["C4986"] helpviewer_keywords: ["C4986"] -ms.assetid: a3a7b008-29dd-4203-85f3-7740ab6790bb --- # Compiler Warning C4986 -'function': exception specification does not match previous declaration +> 'function': exception specification does not match previous declaration + +## Remarks This warning can be generated when there is an exception specification in one declaration and not the other. By default, C4986 is off. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). -## Examples +## Example -The following sample generates C4986. +The following example generates C4986. ```cpp class X { }; @@ -28,7 +29,7 @@ void f1() } ``` -The following sample eliminates this warning. +The following example eliminates this warning. ```cpp class X { }; 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 00000000000..ad186122f61 --- /dev/null +++ b/docs/error-messages/compiler-warnings/compiler-warning-c5072.md @@ -0,0 +1,32 @@ +--- +title: "Compiler Warning (level 1) C5072" +description: "Learn more about: Compiler Warning (level 1) C5072" +ms.date: 09/10/2025 +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 + +## Remarks + +This warning occurs when you compile with [Address Sanitizer](../../sanitizers/asan.md) (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: + +```cmd +cl /fsanitize=address /EHsc test.cpp +``` + +To fix it, have the compiler generate debug information by using a switch like [`/Zi`](../../build/reference/z7-zi-zi-debug-information-format.md#zi) or [`/Z7`](../../build/reference/z7-zi-zi-debug-information-format.md#z7), like this: + +```cmd +cl /fsanitize=address /EHsc /Zi test.cpp +``` + +## See also + +[Address Sanitizer (ASAN)](../../sanitizers/asan.md) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md index ae937e3ff24..fadac33d1d3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1 and 3) C4793" title: "Compiler Warning (level 1 and 3) C4793" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1 and 3) C4793" +ms.date: 11/04/2016 f1_keywords: ["C4793"] helpviewer_keywords: ["C6634", "C6635", "C6640", "C6630", "C6639", "C6636", "C6638", "C6631", "C6637", "C4793"] -ms.assetid: 819ada53-1d9c-49b8-a629-baf8c12314e6 --- # Compiler Warning (level 1 and 3) C4793 @@ -30,9 +29,9 @@ The following table lists all possible continuation messages. |A non-__clrcall virtual function thunk must be compiled as native|A non-[__clrcall](../../cpp/clrcall.md) virtual function thunk must use an unmanaged address.| |A function using '_setjmp' must be compiled as native|The CLR must be able to control program execution. However, the [setjmp](../../cpp/using-setjmp-longjmp.md) function bypasses regular program execution by saving and restoring low-level information such as registers and execution state.| -## Example +## Examples -The following sample generates C4793. +The following example generates C4793. ```cpp // C4793.cpp @@ -50,7 +49,7 @@ warning C4793: 'asmfunc' : function is compiled as native code: Inline native assembly ('__asm') is not supported in managed code ``` -The following sample generates C4793. +The following example generates C4793. ```cpp // C4793_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md index 81b4c94e931..17e3df14c6b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4700.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Warning (level 1 and level 4) C4700" title: "Compiler Warning (level 1 and level 4) C4700" -ms.date: "02/21/2018" +description: "Learn more about: Compiler Warning (level 1 and level 4) C4700" +ms.date: 08/30/2022 f1_keywords: ["C4700"] helpviewer_keywords: ["C4700"] -ms.assetid: 2da0deb4-77dd-4b05-98d3-b78d74ac4ca7 --- # Compiler Warning (level 1 and level 4) C4700 > uninitialized local variable '*name*' used -The local variable *name* has been *used*, that is, read from, before it has been assigned a value. In C and C++, local variables are not initialized by default. Uninitialized variables can contain any value, and their use leads to undefined behavior. Warning C4700 almost always indicates a bug that can cause unpredictable results or crashes in your program. +## Remarks + +The local variable *name* has been *used*, that is, read from, before it has been assigned a value. In C and C++, local variables aren't initialized by default. Uninitialized variables can contain any value, and their use leads to undefined behavior. Warning C4700 almost always indicates a bug that can cause unpredictable results or crashes in your program. + +To fix this issue, you can initialize local variables when they're declared, or assign a value to them before they're used. A function can be used to initialize a variable that's passed as a reference parameter, or when its address is passed as a pointer parameter. -To fix this issue, you can initialize local variables when they are declared, or assign a value to them before they are used. A function can be used to initialize a variable that's passed as a reference parameter, or when its address is passed as a pointer parameter. +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example -This sample generates C4700 when variables t, u, and v are used before they are initialized, and shows the kind of garbage value that can result. Variables x, y, and z do not cause the warning, because they are initialized before use: +This example generates C4700 when variables `t`, `u`, and `v` are used before they're initialized, and shows the kind of garbage value that can result. Variables `x`, `y`, and `z` don't cause the warning, because they're initialized before use: ```cpp // c4700.cpp @@ -46,7 +49,7 @@ int main() } ``` -When this code is run, t, u, and v are uninitialized, and the output for s is unpredictable: +When this code is run, `t`, `u`, and `v` are uninitialized, and the output for `s` is unpredictable: ```Output Value in s: 37816963 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4949.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4949.md index 896988405d4..e4dd9831b20 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4949.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-and-level-4-c4949.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1 and level 4) C4949" title: "Compiler Warning (level 1 and level 4) C4949" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1 and level 4) C4949" +ms.date: 11/04/2016 f1_keywords: ["C4949"] helpviewer_keywords: ["C4949"] -ms.assetid: 34f45a05-c115-49cb-9f67-0bd4f0735d9b --- # Compiler Warning (level 1 and level 4) C4949 -pragmas 'managed' and 'unmanaged' are meaningful only when compiled with '/clr[:option]' +> pragmas 'managed' and 'unmanaged' are meaningful only when compiled with '/clr[:option]' + +## Remarks The compiler ignores the [managed](../../preprocessor/managed-unmanaged.md) and unmanaged pragmas if the source code is not compiled with [/clr](../../build/reference/clr-common-language-runtime-compilation.md). This warning is informational. -The following sample generates C4949: +## Example + +The following example generates C4949: ```cpp // C4949.cpp @@ -22,7 +25,7 @@ The following sample generates C4949: When **#pragma unmanaged** is used without **/clr**, C4949 is a level 4 warning. -The following sample generates C4949: +The following example generates C4949: ```cpp // C4949b.cpp 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 eb79eb1e82b..c97bb7d1227 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4002" -title: "Compiler Warning (level 1) C4002" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4002" +description: "Learn more about: 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*' + +## Remarks 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). + +## Example -The following sample generates C4002: +The following example generates C4002: ```cpp // C4002.cpp @@ -32,7 +35,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 da9d1a36c96..45a2adcf25c 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,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4003" -title: "Compiler Warning (level 1) C4003" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4003" +description: "Learn more about: 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*' + +## Remarks 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. -The following sample generates C4003: +## Example + +The following example generates C4003: ```cpp // C4003.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4005.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4005.md index 53cbf804f6d..69a14d6e511 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4005.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4005.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4005" title: "Compiler Warning (level 1) C4005" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4005" +ms.date: 11/04/2016 f1_keywords: ["C4005"] helpviewer_keywords: ["C4005"] -ms.assetid: 7f2dc79a-9fcb-4d5b-be61-120d9cb487ad --- # Compiler Warning (level 1) C4005 -'identifier' : macro redefinition +> 'identifier' : macro redefinition + +## Remarks The macro identifier is defined twice. The compiler uses the second macro definition. @@ -24,7 +25,9 @@ The macro identifier is defined twice. The compiler uses the second macro defini 1. Use an [#undef](../../preprocessor/hash-undef-directive-c-cpp.md) directive before the second definition. -The following sample generates C4005: +## Example + +The following example generates C4005: ```cpp // C4005.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4006.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4006.md index fead77c55d7..c39751f601c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4006.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4006.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4006" title: "Compiler Warning (level 1) C4006" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4006" +ms.date: 11/04/2016 f1_keywords: ["C4006"] helpviewer_keywords: ["C4006"] -ms.assetid: f1a59819-0fd2-4361-8e3a-99e4b514b8e1 --- # Compiler Warning (level 1) C4006 -\#undef expected an identifier +> #undef expected an identifier + +## Remarks + +The `#undef` directive did not specify an identifier to undefine. The directive is ignored. To resolve the warning, be sure to specify an identifier. + +## Example -The `#undef` directive did not specify an identifier to undefine. The directive is ignored. To resolve the warning, be sure to specify an identifier. The following sample generates C4006: +The following example generates C4006: ```cpp // C4006.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4010.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4010.md index 4f3d6f55eb1..ae54258c558 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4010.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4010.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4010" title: "Compiler Warning (level 1) C4010" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4010" +ms.date: 11/04/2016 f1_keywords: ["C4010"] helpviewer_keywords: ["C4010"] -ms.assetid: d607a9ff-8f8f-45c0-b07b-3b2f439e5485 --- # Compiler Warning (level 1) C4010 -single-line comment contains line-continuation character +> single-line comment contains line-continuation character + +## Remarks A single-line comment, which is introduced by //, contains a backslash (\\) that serves as a line-continuation character. The compiler considers the next line to be a continuation and treats it as a comment. Some syntax-directed editors do not indicate the line following the continuation character as a comment. Ignore syntax coloring on any lines that cause this warning. -The following sample generates C4010: +## Example + +The following example generates C4010: ```cpp // C4010.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4015.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4015.md index 5ad3ccbb8cb..17fcd129fdb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4015.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4015.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4015" title: "Compiler Warning (level 1) C4015" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4015" +ms.date: 11/04/2016 f1_keywords: ["C4015"] helpviewer_keywords: ["C4015"] -ms.assetid: 7242ab90-c869-482f-8152-46728575837e --- # Compiler Warning (level 1) C4015 -'identifier' : type of bit field must be integral +> 'identifier' : type of bit field must be integral + +## Remarks The bit field is not declared as an integer type. The compiler assumes the base type of the bit field to be unsigned. Bit fields must be declared as unsigned integer types. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4020.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4020.md index a5fb74a51a3..587b65dc88e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4020.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4020.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4020" title: "Compiler Warning (level 1) C4020" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4020" +ms.date: 11/04/2016 f1_keywords: ["C4020"] helpviewer_keywords: ["C4020"] -ms.assetid: 8c4cd6be-9371-4c8c-b0ff-a5ad367bbab0 --- # Compiler Warning (level 1) C4020 -'function' : too many actual parameters +> 'function' : too many actual parameters + +## Remarks The number of actual parameters in a function call exceeds the number of formal parameters in the function prototype or definition. The compiler passes the extra actual parameters according to the calling convention of the function. -The following sample generates C4020: +## Example + +The following example generates C4020: ```c // C4020.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4022.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4022.md index 051feb44a3c..ee13a0d21af 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4022.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4022.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4022" title: "Compiler Warning (level 1) C4022" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4022" +ms.date: 11/04/2016 f1_keywords: ["C4022"] helpviewer_keywords: ["C4022"] -ms.assetid: 9586ca84-4b40-4602-91a4-2e2415b1ab63 --- # Compiler Warning (level 1) C4022 -'function' : pointer mismatch for actual parameter 'number' +> 'function' : pointer mismatch for actual parameter 'number' + +## Remarks The pointer type of the actual parameter differs from the pointer type of the corresponding formal parameter. The actual parameter is passed without change. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4024.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4024.md index eb23ea6c5f2..f4fb400f3cf 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4024.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4024.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4024" title: "Compiler Warning (level 1) C4024" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4024" +ms.date: 11/04/2016 f1_keywords: ["C4024"] helpviewer_keywords: ["C4024"] -ms.assetid: f6cb1b70-686a-4747-a01c-de673208209a --- # Compiler Warning (level 1) C4024 -'function' : different types for formal and actual parameter 'number' +> 'function' : different types for formal and actual parameter 'number' + +## Remarks Corresponding formal and actual parameters have different types. The compiler passes the actual parameter without change. The receiving function converts the parameter type to the type expected. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4025.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4025.md index 505f3d85979..d9c89fd4608 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4025.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4025.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4025" title: "Compiler Warning (level 1) C4025" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4025" +ms.date: 11/04/2016 f1_keywords: ["C4025"] helpviewer_keywords: ["C4025"] -ms.assetid: c4f6a651-0641-4446-973e-8290065e49ad --- # Compiler Warning (level 1) C4025 -'number' : based pointer passed to function with variable arguments: parameter number +> 'number' : based pointer passed to function with variable arguments: parameter number + +## Remarks Passing a based pointer to a function with variable arguments causes the pointer to be normalized, with unpredictable results. Do not pass based pointers to functions with variable arguments. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4026.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4026.md index 57b763bec5b..4aa8c4d8323 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4026.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4026.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4026" title: "Compiler Warning (level 1) C4026" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4026" +ms.date: 11/04/2016 f1_keywords: ["C4026"] helpviewer_keywords: ["C4026"] -ms.assetid: 2c8ff616-8d7f-4784-8037-77f8b6a67698 --- # Compiler Warning (level 1) C4026 -function declared with formal parameter list +> function declared with formal parameter list + +## Remarks The function declaration has formal parameters, but the function definition does not. Subsequent calls to this function assume that the function takes no parameters. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4027.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4027.md index c3a3de1492d..cf626d581a8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4027.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4027.md @@ -1,6 +1,6 @@ --- -description: "Learn more about compiler warning (level 1) C4027" title: "Compiler Warning (level 1) C4027" +description: "Learn more about compiler warning (level 1) C4027" ms.date: 12/16/2020 f1_keywords: ["C4027"] helpviewer_keywords: ["C4027"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["C4027"] > function declared without formal parameter list +## Remarks + The function declaration had no formal parameters, but there are formal parameters in the function definition or actual parameters in a call. The compiler accepts, but warns, on an old C-style forward declaration of a function name without a parameter list. On later calls to this function, the compiler assumes that the function takes actual parameters of the types found in the function definition or call. We recommend you modify your function declaration diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4028.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4028.md index abc7bff802b..8b090d3b4ba 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4028.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4028.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4028" title: "Compiler Warning (level 1) C4028" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4028" +ms.date: 11/04/2016 f1_keywords: ["C4028"] helpviewer_keywords: ["C4028"] -ms.assetid: c3e8b70b-e870-416c-a285-bba5f71dbfc6 --- # Compiler Warning (level 1) C4028 -formal parameter 'number' different from declaration +> formal parameter 'number' different from declaration + +## Remarks The type of the formal parameter does not agree with the corresponding parameter in the declaration. The type in the original declaration is used. @@ -16,7 +17,7 @@ This warning is only valid for C source code. ## Example -The following sample generates C4028. +The following example generates C4028. ```c // C4028.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4029.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4029.md index d34c5ff797c..fc2983d339e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4029.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4029.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4029" title: "Compiler Warning (level 1) C4029" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4029" +ms.date: 11/04/2016 f1_keywords: ["C4029"] helpviewer_keywords: ["C4029"] -ms.assetid: a5c50bab-a189-44c9-aa5c-4377c7c8443a --- # Compiler Warning (level 1) C4029 -declared formal parameter list different from definition +> declared formal parameter list different from definition + +## Remarks Formal parameter types in the function declaration do not agree with those in the function definition. The compiler uses the parameter list from the definition. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4030.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4030.md index 9440c168978..c36e7b4667b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4030.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4030.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4030" title: "Compiler Warning (level 1) C4030" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4030" +ms.date: 11/04/2016 f1_keywords: ["C4030"] helpviewer_keywords: ["C4030"] -ms.assetid: 155b290e-4777-4704-ad35-02968b1e4c5e --- # Compiler Warning (level 1) C4030 -**first formal parameter list longer than the second list** +> first formal parameter list longer than the second list + +## Remarks A function was redeclared with different formal parameters. The compiler uses the formal parameters given in the first declaration. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4031.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4031.md index d7291b5939d..f87f4f40fd2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4031.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4031.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4031" title: "Compiler Warning (level 1) C4031" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4031" +ms.date: 11/04/2016 f1_keywords: ["C4031"] helpviewer_keywords: ["C4031"] -ms.assetid: 8ac4965d-75e2-42db-9763-3f6ae707e1e1 --- # Compiler Warning (level 1) C4031 -second formal parameter list longer than the first list +> second formal parameter list longer than the first list + +## Remarks A function is redeclared with different formal parameters. The compiler uses the formal parameters given in the first declaration. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4033.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4033.md index 9e90e7cd31b..0243da64091 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4033.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4033.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4033" title: "Compiler Warning (level 1) C4033" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4033" +ms.date: 11/04/2016 f1_keywords: ["C4033"] helpviewer_keywords: ["C4033"] -ms.assetid: 189a9ec3-ff6d-49dd-b9b2-530b28bbb7c9 --- # Compiler Warning (level 1) C4033 -'function' must return a value +> 'function' must return a value + +## Remarks The function does not return a value. An undefined value is returned. @@ -16,7 +17,9 @@ Functions that use **`return`** without a return value must be declared as type This error is for C language code. -The following sample generates C4033: +## Example + +The following example generates C4033: ```c // C4033.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4034.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4034.md index fa3394aaf44..b1f4596f19e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4034.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4034.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4034" title: "Compiler Warning (level 1) C4034" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4034" +ms.date: 11/04/2016 f1_keywords: ["C4034"] helpviewer_keywords: ["C4034"] -ms.assetid: 1d2f598d-bdfc-4a95-9617-424b591ed3e8 --- # Compiler Warning (level 1) C4034 -sizeof returns 0 +> sizeof returns 0 + +## Remarks The **`sizeof`** operator is applied to an operand of size zero (an empty structure, union, class, or enumerated type, or type **`void`**). diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4036.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4036.md index 5741b71a91a..6cd5d9f50a5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4036.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4036.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4036" title: "Compiler Warning (level 1) C4036" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4036" +ms.date: 11/04/2016 f1_keywords: ["C4036"] helpviewer_keywords: ["C4036"] -ms.assetid: f0b15359-4d62-48ec-8cb1-a7b36587a47f --- # Compiler Warning (level 1) C4036 -unnamed 'type' as actual parameter +> unnamed 'type' as actual parameter + +## Remarks No type name is given for a structure, union, enumeration, or class used as an actual parameter. If you are using [/Zg](../../build/reference/zg-generate-function-prototypes.md) to generate function prototypes, the compiler issues this warning and comments out the formal parameter in the generated prototype. @@ -16,7 +17,7 @@ Specify a type name to resolve this warning. ## Example -The following sample generates C4036. +The following example generates C4036 and shows how to fix it by providing a type name. ```c // C4036.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4038.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4038.md index 5fefad3f82d..1ae8f389eee 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4038.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4038.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4038" title: "Compiler Warning (level 1) C4038" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4038" +ms.date: 11/04/2016 f1_keywords: ["C4038"] helpviewer_keywords: ["C4038"] -ms.assetid: 54c7f4ed-9386-436e-b4be-bf6c338ded64 --- # Compiler Warning (level 1) C4038 -'modifier' : illegal ambient class modifier +> 'modifier' : illegal ambient class modifier + +## Remarks This modifier cannot be used for classes with **`dllimport`** or [dllexport](../../cpp/dllexport-dllimport.md) attributes. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4041.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4041.md index 1dc226cd33f..522bdd17d0d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4041.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4041.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4041" title: "Compiler Warning (level 1) C4041" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4041" +ms.date: 11/04/2016 f1_keywords: ["C4041"] helpviewer_keywords: ["C4041"] -ms.assetid: 107ee9fd-4b88-4f22-a18f-a20726831095 --- # Compiler Warning (level 1) C4041 -compiler limit : terminating browser output +> compiler limit : terminating browser output + +## Remarks Browser information exceeded the compiler limit. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4042.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4042.md index 4ec209f86f8..aad89002ff8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4042.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4042.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4042" title: "Compiler Warning (level 1) C4042" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4042" +ms.date: 11/04/2016 f1_keywords: ["C4042"] helpviewer_keywords: ["C4042"] -ms.assetid: e4bd861b-1194-426b-bf79-68c5b021eb0a --- # Compiler Warning (level 1) C4042 -'identifier' : has bad storage class +> 'identifier' : has bad storage class + +## Remarks The specified storage class cannot be used with this identifier in this context. The compiler uses the default storage class instead: @@ -20,7 +21,9 @@ The specified storage class cannot be used with this identifier in this context. This warning can be caused by specifying a storage class other than **`register`** in a parameter declaration. -The following sample generates C4042 +## Example + +The following example generates C4042: ```cpp // C4042.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4045.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4045.md index 92468659928..3a866f8ae5f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4045.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4045.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4045" title: "Compiler Warning (level 1) C4045" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4045" +ms.date: 11/04/2016 f1_keywords: ["C4045"] helpviewer_keywords: ["C4045"] -ms.assetid: 3c6f7373-da91-45cd-b224-f49f7d8b4df0 --- # Compiler Warning (level 1) C4045 -'array' : array bounds overflow +> 'array' : array bounds overflow + +## Remarks The array has too many initializers. Extra initializers are ignored. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4047.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4047.md index 229da7ccbde..4a9b1b9a0ba 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4047.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4047.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4047" title: "Compiler Warning (level 1) C4047" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4047" +ms.date: 11/04/2016 f1_keywords: ["C4047"] helpviewer_keywords: ["C4047"] -ms.assetid: b75ad6fb-5c93-4434-a85f-c4083051a5de --- # Compiler Warning (level 1) C4047 -'operator' : 'identifier1' differs in levels of indirection from 'identifier2' +> 'operator' : 'identifier1' differs in levels of indirection from 'identifier2' + +## Remarks A pointer can point to a variable (one level of indirection), to another pointer that points to a variable (two levels of indirection), and so on. ## Examples -The following sample generates C4047: +The following example generates C4047: ```c // C4047.c @@ -32,7 +33,7 @@ int main() { } ``` -The following sample generates C4047: +The following example generates C4047: ```c // C4047b.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4048.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4048.md index a3786cb575b..bf07d4838c3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4048.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4048.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4048" title: "Compiler Warning (level 1) C4048" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4048" +ms.date: 11/04/2016 f1_keywords: ["C4048"] helpviewer_keywords: ["C4048"] -ms.assetid: 8429f513-4732-40f1-8e56-4c224e723bcb --- # Compiler Warning (level 1) C4048 -different declared array subscripts : 'identifier1' and 'identifier2' +> different declared array subscripts : 'identifier1' and 'identifier2' + +## Remarks An expression involves pointers to arrays of different size. The pointers are used without conversion. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4049.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4049.md index d13fb15e544..8e31d5fcc0e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4049.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4049.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4049" title: "Compiler Warning (level 1) C4049" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4049" +ms.date: 11/04/2016 f1_keywords: ["C4049"] helpviewer_keywords: ["C4049"] -ms.assetid: d11c1870-bcfc-4d71-8945-b87ec6ec3514 --- # Compiler Warning (level 1) C4049 -compiler limit : terminating line number emission +> compiler limit : terminating line number emission + +## Remarks The file contains more than 16,777,215 (224-1) source lines. The compiler stops numbering at 16,777,215. 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 889c7e063ba..d2c29d924f1 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,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4052" -title: "Compiler Warning (level 1) C4052" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1 and level 4) C4052" +description: "Learn more about: 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. +## Remarks -The following sample generates C4052: +One declaration of the function doesn't contain variable arguments. The empty declaration is ignored. + +## Example + +The following example generates C4052: ```c // C4052.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4055.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4055.md index 29d27d3b0e8..766f8180af8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4055.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4055.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4055" title: "Compiler Warning (level 1) C4055" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4055" +ms.date: 11/04/2016 f1_keywords: ["C4055"] helpviewer_keywords: ["C4055"] -ms.assetid: f9955421-16ab-46e5-8f9d-bf1639a519ef --- # Compiler Warning (level 1) C4055 @@ -18,7 +17,7 @@ A data pointer is cast (possibly incorrectly) to a function pointer. This is a l ## Example -The following sample generates C4055: +The following example generates C4055: ```C // C4055.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4067.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4067.md index 10e6a99d949..6091facabd8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4067.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4067.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4067" title: "Compiler Warning (level 1) C4067" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4067" +ms.date: 11/04/2016 f1_keywords: ["C4067"] helpviewer_keywords: ["C4067"] -ms.assetid: 1d10353e-8cd5-4b01-9184-a06189b965a4 --- # Compiler Warning (level 1) C4067 @@ -16,6 +15,8 @@ The compiler found and ignored extra characters following a preprocessor directi ## Example +The following example generates C4067: + ```cpp // C4067a.cpp // compile with: cl /EHsc /DX /W1 /Za C4067a.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4068.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4068.md index f6f9cadd5f9..138b6715dff 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4068.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4068.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4068" title: "Compiler Warning (level 1) C4068" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4068" +ms.date: 11/04/2016 f1_keywords: ["C4068"] helpviewer_keywords: ["C4068"] -ms.assetid: 96a7397a-4eab-44ab-b3bb-36747503f7e5 --- # Compiler Warning (level 1) C4068 -unknown pragma +> unknown pragma + +## Remarks + +The compiler ignored an unrecognized [pragma](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). Be sure the **pragma** is allowed by the compiler you are using. + +## Example -The compiler ignored an unrecognized [pragma](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). Be sure the **pragma** is allowed by the compiler you are using. The following sample generates C4068: +The following example generates C4068: ```cpp // C4068.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4074.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4074.md index 8d4fbe8f3a6..ce3eb6ac36d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4074.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4074.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4074" title: "Compiler Warning (level 1) C4074" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4074" +ms.date: 11/04/2016 f1_keywords: ["C4074"] helpviewer_keywords: ["C4074"] -ms.assetid: cd510e66-c338-4a86-a4d7-bfa1df9b16c3 --- # Compiler Warning (level 1) C4074 -initializers put in compiler reserved initialization area +> initializers put in compiler reserved initialization area + +## Remarks The compiler initialization area, which is specified by [#pragma init_seg](../../preprocessor/init-seg.md), is reserved by Microsoft. Code in this area may be executed before initialization of the C run-time library. -The following sample generates C4074: +## Example + +The following example generates C4074: ```cpp // C4074.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4075.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4075.md index 4fe1b0c563a..5e99eb14589 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4075.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4075.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4075" title: "Compiler Warning (level 1) C4075" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4075" +ms.date: 11/04/2016 f1_keywords: ["C4075"] helpviewer_keywords: ["C4075"] -ms.assetid: 19a700b6-f210-4b9d-a2f2-76cfe39ab178 --- # Compiler Warning (level 1) C4075 -initializers put in unrecognized initialization area +> initializers put in unrecognized initialization area + +## Remarks A [#pragma init_seg](../../preprocessor/init-seg.md) uses an unrecognized section name. The compiler ignores the **pragma** command. -The following sample generates C4075: +## Example + +The following example generates C4075: ```cpp // C4075.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4076.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4076.md index ba24a51e7f3..0361ba89332 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4076.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4076.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4076" title: "Compiler Warning (level 1) C4076" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4076" +ms.date: 11/04/2016 f1_keywords: ["C4076"] helpviewer_keywords: ["C4076"] -ms.assetid: 04581066-313a-4a11-bb60-721e6d038d75 --- # Compiler Warning (level 1) C4076 @@ -16,7 +15,7 @@ A type modifier, whether it is **`signed`** or **`unsigned`**, cannot be used wi ## Example -The following sample generates C4076; to fix it, remove the **`unsigned`** type modifier: +The following example generates C4076; to fix it, remove the **`unsigned`** type modifier: ```cpp // C4076.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4077.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4077.md index c6c140c75ae..de0009d557a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4077.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4077.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4077" title: "Compiler Warning (level 1) C4077" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4077" +ms.date: 11/04/2016 f1_keywords: ["C4077"] helpviewer_keywords: ["C4077"] -ms.assetid: c2d28805-b33f-41ad-afba-33b3f788c649 --- # Compiler Warning (level 1) C4077 -unknown check_stack option +> unknown check_stack option + +## Remarks The old form of the **check_stack** pragma is used with an unknown argument. The argument must be `+`, `-`, `(on)`, `(off)`, or empty. @@ -16,6 +17,8 @@ The compiler ignores the pragma and leaves the stack checking unchanged. ## Example +The following example generates C4077: + ```cpp // C4077.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4079.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4079.md index aa3914ce05d..89ec4207fdb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4079.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4079.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4079" title: "Compiler Warning (level 1) C4079" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4079" +ms.date: 11/04/2016 f1_keywords: ["C4079"] helpviewer_keywords: ["C4079"] -ms.assetid: 549759f0-e168-47e9-8c9a-de93ac843689 --- # Compiler Warning (level 1) C4079 -unexpected token 'token' +> unexpected token 'token' + +## Remarks An unexpected separator token occurs in a pragma argument list. The remainder of the pragma was ignored. -The following sample generates C4079: +## Example + +The following example generates C4079: ```cpp // C4079.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4080.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4080.md index 4c78d21774f..60c2c69d85b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4080.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4080.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4080" title: "Compiler Warning (level 1) C4080" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4080" +ms.date: 11/04/2016 f1_keywords: ["C4080"] helpviewer_keywords: ["C4080"] -ms.assetid: 964fb3f4-b9fd-450b-aa23-35cece126172 --- # Compiler Warning (level 1) C4080 -expected identifier for segment name; found 'symbol' +> expected identifier for segment name; found 'symbol' + +## Remarks The name of the segment in [#pragma alloc_text](../../preprocessor/alloc-text.md) must be a string or an identifier. The compiler ignores the pragma if a valid identifier is not found. -The following sample generates C4080: +## Example + +The following example generates C4080: ```cpp // C4080.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4081.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4081.md index a266ad55b2d..fff7ef70eca 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4081.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4081.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4081" title: "Compiler Warning (level 1) C4081" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4081" +ms.date: 11/04/2016 f1_keywords: ["C4081"] helpviewer_keywords: ["C4081"] -ms.assetid: 6f656373-a080-4989-bbc9-e2f894b03293 --- # Compiler Warning (level 1) C4081 -expected 'token1'; found 'token2' +> expected 'token1'; found 'token2' + +## Remarks The compiler expected a different token in this context. ## Example +The following example generates C4081: + ```cpp // C4081.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4083.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4083.md index 87918fc4491..2796ab139eb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4083.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4083.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4083" title: "Compiler Warning (level 1) C4083" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4083" +ms.date: 11/04/2016 f1_keywords: ["C4083"] helpviewer_keywords: ["C4083"] -ms.assetid: e7d3344e-5645-4d56-8460-d1acc9145ada --- # Compiler Warning (level 1) C4083 -expected 'token'; found identifier 'identifier' +> expected 'token'; found identifier 'identifier' + +## Remarks An identifier occurs in the wrong place in a **#pragma** statement. ## Example +The following example generates C4083: + ```cpp // C4083.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4085.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4085.md index af90990a225..98a8afd3948 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4085.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4085.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4085" title: "Compiler Warning (level 1) C4085" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4085" +ms.date: 11/04/2016 f1_keywords: ["C4085"] helpviewer_keywords: ["C4085"] -ms.assetid: 2bc6eb25-058f-4597-b351-fd69587b5170 --- # Compiler Warning (level 1) C4085 -expected pragma parameter to be 'on' or 'off' +> expected pragma parameter to be 'on' or 'off' + +## Remarks The pragma requires an **on** or **off** parameter. The pragma is ignored. -The following sample generates C4085: +## Example + +The following example generates C4085: ```cpp // C4085.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4086.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4086.md index 1c8cf29e1b9..f64ee275649 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4086.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4086.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4086" title: "Compiler Warning (level 1) C4086" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4086" +ms.date: 11/04/2016 f1_keywords: ["C4086"] helpviewer_keywords: ["C4086"] -ms.assetid: 9248831b-22bf-47af-8684-bfadb17e94fc --- # Compiler Warning (level 1) C4086 -expected pragma parameter to be '1', '2', '4', '8', or '16' +> expected pragma parameter to be '1', '2', '4', '8', or '16' + +## Remarks The pragma parameter does not have the required value (1, 2, 4, 8, or 16). ## Example +The following example generates C4086: + ```cpp // C4086.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4087.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4087.md index 631fbd9d8c8..b8d7e4fa763 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4087.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4087.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4087" title: "Compiler Warning (level 1) C4087" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4087" +ms.date: 11/04/2016 f1_keywords: ["C4087"] helpviewer_keywords: ["C4087"] -ms.assetid: 546e4d57-5c8e-422c-8ef1-92657336dad5 --- # Compiler Warning (level 1) C4087 -'function' : declared with 'void' parameter list +> 'function' : declared with 'void' parameter list + +## Remarks The function declaration has no formal parameters, but the function call has actual parameters. Extra parameters are passed according to the calling convention of the function. @@ -16,6 +17,8 @@ This warning is for the C compiler. ## Example +The following example generates C4087: + ```c // C4087.c // compile with: /W1 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4088.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4088.md index 743a55b292b..24b6a432788 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4088.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4088.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4088" title: "Compiler Warning (level 1) C4088" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4088" +ms.date: 11/04/2016 f1_keywords: ["C4088"] helpviewer_keywords: ["C4088"] -ms.assetid: 9bab817c-16b2-4324-be5e-f9cbb06b702e --- # Compiler Warning (level 1) C4088 -'function' : pointer mismatch in actual parameter 'number', formal parameter 'number' +> 'function' : pointer mismatch in actual parameter 'number', formal parameter 'number' + +## Remarks The corresponding formal and actual parameters have a different level of indirection. The actual parameter is passed without change. The called function interprets its value as a pointer. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4089.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4089.md index c5a33f3524b..90895290376 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4089.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4089.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4089" title: "Compiler Warning (level 1) C4089" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4089" +ms.date: 11/04/2016 f1_keywords: ["C4089"] helpviewer_keywords: ["C4089"] -ms.assetid: 7c8f929b-9bf9-4063-9b7e-4affd98c1acc --- # Compiler Warning (level 1) C4089 -'function' : different types in actual parameter 'number', formal parameter 'number' +> 'function' : different types in actual parameter 'number', formal parameter 'number' + +## Remarks The corresponding formal and actual parameters have different types. The actual parameter is passed without change. The function casts the actual parameter to the type specified in the function definition. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4090.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4090.md index 4bb401cbcb1..716f99228f5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4090.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4090.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4090" title: "Compiler Warning (level 1) C4090" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4090" +ms.date: 11/04/2016 f1_keywords: ["C4090"] helpviewer_keywords: ["C4090"] -ms.assetid: baad469d-23d4-45aa-ad9c-305b32d61e9a --- # Compiler Warning (level 1) C4090 -'operation' : different 'modifier' qualifiers +> 'operation' : different 'modifier' qualifiers + +## Remarks A variable used in an operation is defined with a specified modifier that prevents it from being modified without detection by the compiler. The expression is compiled without modification. @@ -16,7 +17,9 @@ This warning can be caused when a pointer to a **`const`** or **`volatile`** ite This warning is issued for C programs. In a C++ program, the compiler issues an error: [C2440](../../error-messages/compiler-errors-1/compiler-error-c2440.md). -The following sample generates C4090: +## Example + +The following example generates C4090: ```c // C4090.c 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 89745ffea5d..100e44a0e12 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,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4091" -title: "Compiler Warning (level 1) C4091" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1 and level 2) C4091" +description: "Learn more about: 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. +## Remarks + +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 -A **`__declspec`** attribute at the beginning of a user-defined type declaration applies to the variable of that type. C4091 indicates no variable is declared. The following sample generates C4091. +A **`__declspec`** attribute at the beginning of a user-defined type declaration applies to the variable of that type. C4091 indicates no variable is declared. The following example generates C4091. ```cpp // C4091.cpp @@ -29,7 +30,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 example generates C4091. ```cpp // C4091_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4096.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4096.md index 1013ef52740..95738c23070 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4096.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4096.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4096" title: "Compiler Warning (level 1) C4096" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4096" +ms.date: 11/04/2016 f1_keywords: ["C4096"] helpviewer_keywords: ["C4096"] -ms.assetid: abf3cca2-2f21-45d8-b025-6b513b00681e --- # Compiler Warning (level 1) C4096 -'a': interface is not a COM interface; will not be emitted to IDL +> 'a': interface is not a COM interface; will not be emitted to IDL + +## Remarks An interface definition that you may have intended as a COM interface was not defined as a COM interface and therefore will not be emitted to the IDL file. See [Interface Attributes](../../windows/attributes/interface-attributes.md) for a list attributes that indicate an interface is a COM interface. -The following sample generates C4096: +## Example + +The following example generates C4096: ```cpp // C4096.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4097.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4097.md index c9c9d9688d8..36cde34b27c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4097.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4097.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4097" title: "Compiler Warning (level 1) C4097" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4097" +ms.date: 11/04/2016 f1_keywords: ["C4097"] helpviewer_keywords: ["C4097"] -ms.assetid: 2525be51-fac2-43b2-b57c-3bbf1a2268f7 --- # Compiler Warning (level 1) C4097 -expected pragma parameter to be 'restore' or 'off' +> expected pragma parameter to be 'restore' or 'off' + +## Remarks A pragma was passed an invalid value. -The following sample generates C4097: +## Example + +The following example generates C4097: ```cpp // C4097.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4098.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4098.md index 02da792a1f2..c90d530b284 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4098.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4098.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4098" title: "Compiler Warning (level 1) C4098" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4098" +ms.date: 11/04/2016 f1_keywords: ["C4098"] helpviewer_keywords: ["C4098"] -ms.assetid: 8c8aef1c-1639-44ec-a3dd-c0dfe9aa727d --- # Compiler Warning (level 1) C4098 -'function' : void function returning a value +> 'function' : void function returning a value + +## Remarks A function declared with return type [void](../../cpp/void-cpp.md) has a **`return`** statement that returns a value. The compiler assumes the function returns a value of type **`int`**. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4103.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4103.md index a61f63ece8c..c9365e43be1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4103.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4103.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4103" title: "Compiler Warning (level 1) C4103" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4103" +ms.date: 11/04/2016 f1_keywords: ["C4103"] helpviewer_keywords: ["C4103"] -ms.assetid: 9021b514-375e-4d62-b261-ccb06f299e8e --- # Compiler Warning (level 1) C4103 -'filename' : alignment changed after including header, may be due to missing #pragma pack(pop) +> 'filename' : alignment changed after including header, may be due to missing #pragma pack(pop) + +## Remarks Packing affects the layout of classes, and commonly, if packing changes across header files, there can be problems. Use #pragma [pack](../../preprocessor/pack.md)(pop) before exiting the header file to resolve this warning. -The following sample generates C4103: +## Example + +The following example generates C4103: ```cpp // C4103.h diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4109.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4109.md index 3c6de78389d..dfa71b61be9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4109.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4109.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4109" title: "Compiler Warning (level 1) C4109" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4109" +ms.date: 11/04/2016 f1_keywords: ["C4109"] helpviewer_keywords: ["C4109"] -ms.assetid: 9e8d95c6-e05d-47e0-bd87-78974b3cc06c --- # Compiler Warning (level 1) C4109 -unexpected identifier 'identifier' +> unexpected identifier 'identifier' + +## Remarks The pragma containing the unexpected identifier is ignored. ## Example +The following example generates C4109: + ```cpp // C4109.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4113.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4113.md index 7a93cc5ec61..336d4c75cb1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4113.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4113.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4113" title: "Compiler Warning (level 1) C4113" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4113" +ms.date: 11/04/2016 f1_keywords: ["C4113"] helpviewer_keywords: ["C4113"] -ms.assetid: ec7a7c4a-d2ee-431c-89dc-31b0f9bfd975 --- # Compiler Warning (level 1) C4113 -'identifier1' differs in parameter lists from 'identifier2' +> 'identifier1' differs in parameter lists from 'identifier2' + +## Remarks A function pointer is assigned to another function pointer, but the formal parameter lists of the functions do not agree. The assignment is compiled without modification. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4114.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4114.md index ef6514dddea..57c02abc3a4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4114.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4114.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4114" title: "Compiler Warning (level 1) C4114" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4114" +ms.date: 11/04/2016 f1_keywords: ["C4114"] helpviewer_keywords: ["C4114"] -ms.assetid: 3983e1c6-e8bb-46dc-8894-e1827db48797 --- # Compiler Warning (level 1) C4114 -same type qualifier used more than once +> same type qualifier used more than once + +## Remarks A type declaration or definition uses a type qualifier (**`const`**, **`volatile`**, **`signed`**, or **`unsigned`**) more than once. This causes a warning with Microsoft extensions (/Ze) and an error under ANSI compatibility (/Za). -The following sample generates C4114: +## Examples + +The following example generates C4114: ```cpp // C4114.cpp @@ -20,7 +23,7 @@ The following sample generates C4114: volatile volatile int i; // C4114 ``` -The following sample generates C4114: +The following example generates C4114: ```cpp // C4114_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4116.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4116.md index 4c64a7d9d08..b650d740844 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4116.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4116.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4116" title: "Compiler Warning (level 1) C4116" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4116" +ms.date: 11/04/2016 f1_keywords: ["C4116"] helpviewer_keywords: ["C4116"] -ms.assetid: 25434ef3-061e-4252-91a5-0fe2a4b2ffb3 --- # Compiler Warning (level 1) C4116 -unnamed type definition in parentheses +> unnamed type definition in parentheses + +## Remarks A structure, union, or enumerated type with no name is defined in a parenthetical expression. The type definition is meaningless. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4117.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4117.md index 1b76610289e..8355fc6923a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4117.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4117.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4117" title: "Compiler Warning (level 1) C4117" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4117" +ms.date: 11/04/2016 f1_keywords: ["C4117"] helpviewer_keywords: ["C4117"] -ms.assetid: c45aa281-4cc1-4dfd-bd32-bd7a60ddd577 --- # Compiler Warning (level 1) C4117 -macro name 'name' is reserved; 'Command' ignored +> macro name 'name' is reserved; 'Command' ignored + +## Remarks ### To fix by checking the following possible causes @@ -16,7 +17,9 @@ macro name 'name' is reserved; 'Command' ignored 1. Trying to define or undefine the preprocessor operator **defined**. -The following sample generates C4117: +## Example + +The following example generates C4117: ```cpp // C4117.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4119.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4119.md index 6734a6e402b..4cdf1d4876f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4119.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4119.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4119" title: "Compiler Warning (level 1) C4119" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4119" +ms.date: 11/04/2016 f1_keywords: ["C4119"] helpviewer_keywords: ["C4119"] -ms.assetid: 0052ce92-033a-4dce-a11e-b7388f4f5c2b --- # Compiler Warning (level 1) C4119 -different bases 'base1' and 'base2' specified +> different bases 'base1' and 'base2' specified + +## Remarks Two based pointers are incompatible because they have different bases. The compiler cannot convert between them. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4120.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4120.md index 65f329119b9..04227416fd6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4120.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4120.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4120" title: "Compiler Warning (level 1) C4120" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4120" +ms.date: 11/04/2016 f1_keywords: ["C4120"] helpviewer_keywords: ["C4120"] -ms.assetid: 9faa9265-34b4-41dd-b7a2-e2f3969b1d91 --- # Compiler Warning (level 1) C4120 -based/unbased mismatch +> based/unbased mismatch + +## Remarks The compiler cannot convert between the two pointers because one is based and the other is not. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4122.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4122.md index 61cba8a38be..bdb3071ce53 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4122.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4122.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4122" title: "Compiler Warning (level 1) C4122" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4122" +ms.date: 11/04/2016 f1_keywords: ["C4122"] helpviewer_keywords: ["C4122"] -ms.assetid: 9a83eb0d-8708-42f7-988a-b0b6f2f646a0 --- # Compiler Warning (level 1) C4122 -'function' : alloc_text applicable only to functions with C linkage +> 'function' : alloc_text applicable only to functions with C linkage + +## Remarks The **alloc_text** pragma applies only to functions declared with **extern c**. It cannot be used with external C++ functions. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4124.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4124.md index 504d71c8ed4..6e38358a92c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4124.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4124.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4124" title: "Compiler Warning (level 1) C4124" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4124" +ms.date: 11/04/2016 f1_keywords: ["C4124"] helpviewer_keywords: ["C4124"] -ms.assetid: c08c3a65-9584-47a1-a147-44f00c4b230e --- # Compiler Warning (level 1) C4124 -__fastcall with stack checking is inefficient +> __fastcall with stack checking is inefficient + +## Remarks The **`__fastcall`** keyword was used with stack checking enabled. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4129.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4129.md index 1dc06732e56..d75dddc8ccd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4129.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4129.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4129" title: "Compiler Warning (level 1) C4129" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4129" +ms.date: 11/04/2016 f1_keywords: ["C4129"] helpviewer_keywords: ["C4129"] -ms.assetid: a4190c64-4bfb-48fd-8e98-52720bc0d878 --- # Compiler Warning (level 1) C4129 -'character' : unrecognized character escape sequence +> 'character' : unrecognized character escape sequence + +## Remarks The `character` following a backslash (\\) in a character or string constant is not recognized as a valid escape sequence. The backslash is ignored and not printed. The character following the backslash is printed. @@ -16,7 +17,9 @@ To print a single backslash, specify a double backslash (\\\\). The C++ standard, in section 2.13.2 discusses escape sequences. -The following sample generates C4129: +## Example + +The following example generates C4129: ```cpp // C4129.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4138.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4138.md index 8a5d005a472..e6971ba8739 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4138.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4138.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4138" title: "Compiler Warning (level 1) C4138" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4138" +ms.date: 11/04/2016 f1_keywords: ["C4138"] helpviewer_keywords: ["C4138"] -ms.assetid: 65ebf929-bba0-4237-923b-c1b66adfe17d --- # Compiler Warning (level 1) C4138 -'*/' found outside of comment +> '*/' found outside of comment + +## Remarks The closing-comment delimiter is not preceded by an opening-comment delimiter. The compiler assumes a space between the asterisk (\*) and the forward slash (/). ## Example +The following example generates C4138: + ```cpp // C4138a.cpp // compile with: /W1 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 abe11df5f5e..7a38f03c082 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,17 +1,18 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4141" -title: "Compiler Warning (level 1) C4141" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4141" +description: "Learn more about: 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 +The following example generates C4141: + ```cpp // C4141.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4142.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4142.md index 202399a686d..90f6cc10a7b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4142.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4142.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4142" title: "Compiler Warning (level 1) C4142" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4142" +ms.date: 11/04/2016 f1_keywords: ["C4142"] helpviewer_keywords: ["C4142"] -ms.assetid: 1fdfc3dc-60a2-4f00-b133-20e400f9b7a6 --- # Compiler Warning (level 1) C4142 -benign redefinition of type +> benign redefinition of type + +## Remarks A type is redefined in a manner that has no effect on the generated code. @@ -18,7 +19,9 @@ To fix by checking the following possible causes: - A type defined with the **`typedef`** command is redefined using different syntax. -The following sample generates C4142: +## Example + +The following example generates C4142: ```c // C4142.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4143.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4143.md index 5ae6a8f9ad2..d4e1d6c8ab3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4143.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4143.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4143" title: "Compiler Warning (level 1) C4143" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4143" +ms.date: 11/04/2016 f1_keywords: ["C4143"] helpviewer_keywords: ["same_seg", "C4143"] -ms.assetid: ef0bd19f-d169-4034-8710-b22971bd642d --- # Compiler Warning (level 1) C4143 -pragma 'same_seg' not supported; use __based allocation +> pragma 'same_seg' not supported; use __based allocation + +## Remarks The **#pragma same_seg** is no longer supported. Use the [__based](../../cpp/based-pointers-cpp.md) keyword instead. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4144.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4144.md index 9a5b1400ff6..19e46906093 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4144.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4144.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4144" title: "Compiler Warning (level 1) C4144" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4144" +ms.date: 11/04/2016 f1_keywords: ["C4144"] helpviewer_keywords: ["C4144"] -ms.assetid: a37b445d-dbc6-43b4-8d95-ffd0e4225464 --- # Compiler Warning (level 1) C4144 -'expression' : relational expression as switch expression +> 'expression' : relational expression as switch expression + +## Remarks + +The specified relational expression was used as the control expression of a [switch](../../cpp/switch-statement-cpp.md) statement. The associated case statements will be offered Boolean values. + +## Example -The specified relational expression was used as the control expression of a [switch](../../cpp/switch-statement-cpp.md) statement. The associated case statements will be offered Boolean values. The following sample generates C4144: +The following example generates C4144: ```cpp // C4144.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4145.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4145.md index 5d2abaa9db8..4ef4b5f5e37 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4145.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4145.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4145" title: "Compiler Warning (level 1) C4145" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4145" +ms.date: 11/04/2016 f1_keywords: ["C4145"] helpviewer_keywords: ["C4145"] -ms.assetid: 0440777a-cca2-4159-aff5-e67a254ad64a --- # Compiler Warning (level 1) C4145 -'expression1' : relational expression as switch expression; possible confusion with 'expression2' +> 'expression1' : relational expression as switch expression; possible confusion with 'expression2' + +## Remarks A **`switch`** statement uses a relational expression as its control expression, which results in a Boolean value for the **`case`** statements. Did you mean *expression2*? ## Example -The following sample generates C4145: +The following example generates C4145: ```cpp // C4145.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4153.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4153.md index 452c1f40feb..0f80d1e4c9d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4153.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4153.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4153" title: "Compiler Warning (level 1) C4153" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4153" +ms.date: 11/04/2016 f1_keywords: ["C4153"] helpviewer_keywords: ["C4153"] -ms.assetid: 37a15754-9dba-470b-adda-c4b888064b3e --- # Compiler Warning (level 1) C4153 -function/data pointer conversion in expression +> function/data pointer conversion in expression + +## Remarks A function pointer is converted to or from a data pointer. This conversion is allowed under Microsoft extensions (/Ze) but not under ANSI C. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4154.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4154.md index a46730e0c11..bd590178ea3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4154.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4154.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4154" title: "Compiler Warning (level 1) C4154" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4154" +ms.date: 11/04/2016 f1_keywords: ["C4154"] helpviewer_keywords: ["C4154"] -ms.assetid: 4511afeb-e893-4cc6-83b6-4c7a0477f76b --- # Compiler Warning (level 1) C4154 -deletion of an array expression; conversion to pointer supplied +> deletion of an array expression; conversion to pointer supplied + +## Remarks You cannot use **`delete`** on an array, so the compiler converts the array to a pointer. ## Example +The following example generates C4154: + ```cpp // C4154.cpp // compile with: /c /W1 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4155.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4155.md index bb736d60391..8ae584b843a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4155.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4155.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4155" title: "Compiler Warning (level 1) C4155" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4155" +ms.date: 11/04/2016 f1_keywords: ["C4155"] helpviewer_keywords: ["C4155"] -ms.assetid: ba233353-09e3-4195-8127-13a27ddd8d70 --- # Compiler Warning (level 1) C4155 -deletion of an array expression without using the array form of 'delete' +> deletion of an array expression without using the array form of 'delete' + +## Remarks The array form of **`delete`** should be used to delete an array. This warning occurs only under ANSI-compatibility (/Za). ## Example -The following sample generates C4155: +The following example generates C4155: ```cpp // C4155.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4157.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4157.md index db705ad99ec..1f1864aff51 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4157.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4157.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4157" title: "Compiler Warning (level 1) C4157" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4157" +ms.date: 11/04/2016 f1_keywords: ["C4157"] helpviewer_keywords: ["C4157"] -ms.assetid: 6dabc303-eba1-4a8e-a124-a6e1dc84f4bd --- # Compiler Warning (level 1) C4157 -pragma was ignored by C compiler +> pragma was ignored by C compiler + +## Remarks Only the C++ compiler recognizes **init_seg()**. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md index 0c5e3fe14ca..72fbc895e57 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4158.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4158" title: "Compiler Warning (level 1) C4158" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4158" +ms.date: 11/04/2016 f1_keywords: ["C4158"] helpviewer_keywords: ["C4158"] -ms.assetid: 6513c6b9-6772-4849-b96c-5bb093d54de6 --- # Compiler Warning (level 1) C4158 > assuming #pragma pointers_to_members(full_generality, inheritance) +## Remarks + A `#pragma pointers_to_members( single | multiple | virtual )` was issued without an accompanying `#pragma pointers_to_members(full_generality)`. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4160.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4160.md index a0765747a33..6eea80c6c9e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4160.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4160.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4160" title: "Compiler Warning (level 1) C4160" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4160" +ms.date: 08/27/2018 f1_keywords: ["C4160"] helpviewer_keywords: ["C4160"] -ms.assetid: a9610cb7-cac4-4a74-8b4e-049030ebb92b --- # Compiler Warning (level 1) C4160 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4162.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4162.md index 151a1a95050..41936b10c1f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4162.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4162.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4162" title: "Compiler Warning (level 1) C4162" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4162" +ms.date: 11/04/2016 f1_keywords: ["C4162"] helpviewer_keywords: ["C4162"] -ms.assetid: 21ae3c92-501d-4689-ad7d-13753cb65eff --- # Compiler Warning (level 1) C4162 -'identifier' : no function with C linkage found +> 'identifier' : no function with C linkage found + +## Remarks A function with C linkage is declared but cannot be found. To resolve this warning, compile in a .c file (invoke the C compiler). If you must invoke the C++ compiler, place extern "C" before the function declaration. -The following sample generates C4162 +## Example + +The following example generates C4162: ```cpp // C4162.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4163.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4163.md index b49a2aed3ae..a66c5cf9508 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4163.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4163.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4163" title: "Compiler Warning (level 1) C4163" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4163" +ms.date: 11/04/2016 f1_keywords: ["C4163"] helpviewer_keywords: ["C4163"] -ms.assetid: b08413fd-03fc-4f41-9167-a98976ac12f2 --- # Compiler Warning (level 1) C4163 -'identifier' : not available as an intrinsic function +> 'identifier' : not available as an intrinsic function + +## Remarks The specified function cannot be used as an [intrinsic](../../preprocessor/intrinsic.md) function. The compiler ignores the invalid function name. -The following sample generates C4163: +## Example + +The following example generates C4163: ```cpp // C4163.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4164.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4164.md index 37bbf267a15..ba0cc3fa68d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4164.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4164.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4164" title: "Compiler Warning (level 1) C4164" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4164" +ms.date: 11/04/2016 f1_keywords: ["C4164"] helpviewer_keywords: ["C4164"] -ms.assetid: 6d7e4a36-8227-4419-880f-44576033493e --- # Compiler Warning (level 1) C4164 -'identifier' : intrinsic function not declared +> 'identifier' : intrinsic function not declared + +## Remarks The specified intrinsic function is not declared; you may need to #include the appropriate header file. 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 22390f5cf93..eb54234ee06 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,29 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4165" -title: "Compiler Warning (level 1) C4165" -ms.date: "11/04/2016" +title: "Compiler Warning (level 3, off) C4165" +description: "Learn more about: 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. +## Remarks + +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 example 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-c4166.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4166.md index 081a79b459b..b3b8268a78d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4166.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4166.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4166" title: "Compiler Warning (level 1) C4166" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4166" +ms.date: 11/04/2016 f1_keywords: ["C4166"] helpviewer_keywords: ["C4166"] -ms.assetid: 4e5398a1-d913-4791-a470-06fc99c36ac5 --- # Compiler Warning (level 1) C4166 -**illegal calling convention for constructor/destructor** +> illegal calling convention for constructor/destructor + +## Remarks Constructors and destructors cannot have calling conventions other than the default for the platform (except when you explicitly specify **__clrcall**). diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4167.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4167.md index ba1b58c8861..4ab61233a5d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4167.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4167.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4167" title: "Compiler Warning (level 1) C4167" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4167" +ms.date: 11/04/2016 f1_keywords: ["C4167"] helpviewer_keywords: ["C4167"] -ms.assetid: 74a420bd-9371-4167-b1ee-74dd8680f97b --- # Compiler Warning (level 1) C4167 -function : only available as an intrinsic function +> function : only available as an intrinsic function + +## Remarks The **#pragma function** tries to force the compiler to use a conventional call to a function that must be used in intrinsic form. The pragma is ignored. @@ -16,6 +17,8 @@ To avoid this warning, remove the **#pragma function**. ## Example +The following example generates C4167: + ```cpp // C4167.cpp // compile with: /W1 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4168.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4168.md index 18cc19630d2..6c487ba5d60 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4168.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4168.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4168" title: "Compiler Warning (level 1) C4168" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4168" +ms.date: 11/04/2016 f1_keywords: ["C4168"] helpviewer_keywords: ["C4168"] -ms.assetid: 1feefa6c-37be-4f7d-856e-f4b648f2fff8 --- # Compiler Warning (level 1) C4168 -compiler limit : out of debugger types, delete program database 'database' and rebuild +> compiler limit : out of debugger types, delete program database 'database' and rebuild + +## Remarks The program database file must be rebuilt to accommodate all types in the program. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4172.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4172.md index 45e27ccfbd7..393c35c0c60 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4172.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4172.md @@ -1,29 +1,43 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4172" title: "Compiler Warning (level 1) C4172" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4172" +ms.date: 06/25/2025 f1_keywords: ["C4172"] helpviewer_keywords: ["C4172"] -ms.assetid: a8d2bf65-d8b1-4fe3-8340-a223d7e7fde6 --- # Compiler Warning (level 1) C4172 -returning address of local variable or temporary +> returning address of local variable or temporary : *optional_context* + +## Remarks A function returns the address of a local variable or temporary object. Local variables and temporary objects are destroyed when a function returns, so the address returned is not valid. Redesign the function so that it does not return the address of a local object. -The following sample generates C4172: +## Example + +The following example generates C4172: ```cpp // C4172.cpp -// compile with: /W1 /LD -float f = 10; +// compile with: /c /W1 + +const int* func1() +{ + int i = 42; + return &i; // C4172 +} + +float f = 1.f; -const double& bar() { -// try the following line instead -// const float& bar() { - return f; // C4172 +const double& func2() +// Try one of the following lines instead: +// const float& func2() +// const auto& func2() +{ + // The problem is that a temporary is created to convert f to a double. + // C4172 in this case refers to returning the address of a temporary. + return f; // C4172 } ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4174.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4174.md index 4f3fdd7da9b..7f02878573c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4174.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4174.md @@ -1,17 +1,18 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4174" title: "Compiler Warning (level 1) C4174" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4174" +ms.date: 11/04/2016 f1_keywords: ["C4174"] helpviewer_keywords: ["C4174"] -ms.assetid: 63301e51-24bc-43c4-bb11-252f7d513e9e --- # Compiler Warning (level 1) C4174 -'name' : not available as a #pragma component +> 'name' : not available as a #pragma component ## Example +The following example generates C4174: + ```cpp // C4174.cpp // compile with: /W1 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4175.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4175.md index 5840c607830..275c235f0b5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4175.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4175.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4175" title: "Compiler Warning (level 1) C4175" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4175" +ms.date: 11/04/2016 f1_keywords: ["C4175"] helpviewer_keywords: ["C4175"] -ms.assetid: 11407a07-127c-4d0d-b262-61f9f2b035ba --- # Compiler Warning (level 1) C4175 -\#pragma component(browser, on) : browser info must initially be specified on the command line +> #pragma component(browser, on) : browser info must initially be specified on the command line + +## Remarks To use [component](../../preprocessor/component.md) pragma, you must generate browse information during compilation ([/FR](../../build/reference/fr-fr-create-dot-sbr-file.md)). diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4176.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4176.md index 209b15d9bfc..22aa2aa22bd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4176.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4176.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4176" title: "Compiler Warning (level 1) C4176" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4176" +ms.date: 11/04/2016 f1_keywords: ["C4176"] helpviewer_keywords: ["C4176"] -ms.assetid: cfffb934-219a-4a63-9df6-ba54405bf766 --- # Compiler Warning (level 1) C4176 -'subcomponent' : unknown subcomponent for #pragma component browser +> 'subcomponent' : unknown subcomponent for #pragma component browser + +## Remarks The **component** pragma contains an invalid subcomponent. To exclude references to a particular name, you must use the **references** option before the name. ## Example +The following example generates C4176: + ```cpp // C4176.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4177.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4177.md index d01e1cdba15..39115e3e153 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4177.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4177.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4177" title: "Compiler Warning (level 1) C4177" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4177" +ms.date: 11/04/2016 f1_keywords: ["C4177"] helpviewer_keywords: ["C4177"] -ms.assetid: 2b05a5b3-696e-4f21-818e-227b9335e748 --- # Compiler Warning (level 1) C4177 -\#pragma pragma should be at global scope +> #pragma pragma should be at global scope + +## Remarks The [pragma](../../preprocessor/pragma-directives-and-the-pragma-keyword.md) pragma should not be used within a local scope. The **pragma** will not be valid until global scope is encountered after the current scope. -The following sample generates C4177: +## Example + +The following example generates C4177: ```cpp // C4177.cpp 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 216d7cb61aa..9500322b58e 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,31 +1,34 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4178" title: "Compiler Warning (level 1) C4178" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4178" +ms.date: 03/06/2024 f1_keywords: ["C4178"] helpviewer_keywords: ["C4178"] -ms.assetid: 2c2c8f97-a5c4-47cd-8dd2-beea172613f3 --- # Compiler Warning (level 1) C4178 -case constant 'constant' too big for the type of the switch expression +> case constant 'constant' too big for the type of the switch expression + +## Remarks A case constant in a **`switch`** expression does not fit in the type to which it is assigned. ## Example +The following example generates C4178: + ```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-c4179.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4179.md index 79ed15e5d51..7ee0442c813 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4179.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4179.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4179" title: "Compiler Warning (level 1) C4179" +description: "Learn more about: Compiler Warning (level 1) C4179" ms.date: 05/03/2021 f1_keywords: ["C4179"] helpviewer_keywords: ["C4179"] @@ -9,14 +9,18 @@ helpviewer_keywords: ["C4179"] > '`//*`' : parsed as '`/`' and '`/*`': confusion with standard '`//`' comments -In standard C89, **`//*`** is an incorrect comment delimiter. Use **`/*`** under **`/Za`** instead. - ## Remarks +In standard C89, **`//*`** is an incorrect comment delimiter. Use **`/*`** under **`/Za`** instead. + Before Visual Studio 2017 version 15.5, under **`/Za`**, the C compiler emits C4179 for a non-standard comment delimiter. In Visual Studio 2017 version 15.5, the C compiler no longer emits warnings C4001 and C4179. The warnings aren't needed because single-line comments have been part of the C standard since C99. +## Example + +The following example generates C4179: + ```C /* C only */ #pragma warning(disable:4001) // C4619 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4180.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4180.md index c1134d1c3d7..e29467a8dea 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4180.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4180.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4180" title: "Compiler Warning (level 1) C4180" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4180" +ms.date: 11/04/2016 f1_keywords: ["C4180"] helpviewer_keywords: ["C4180"] -ms.assetid: 40c91bd4-37f1-4d59-a4f3-d5ddab68239b --- # Compiler Warning (level 1) C4180 -qualifier applied to function type has no meaning; ignored +> qualifier applied to function type has no meaning; ignored + +## Remarks A qualifier, such as **`const`**, is applied to a function type defined by **`typedef`**. ## Example +The following example generates C4180: + ```cpp // C4180.cpp // compile with: /W1 /c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4182.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4182.md index 0983b499fa9..c5097e114ba 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4182.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4182.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4182" title: "Compiler Warning (level 1) C4182" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4182" +ms.date: 11/04/2016 f1_keywords: ["C4182"] helpviewer_keywords: ["C4182"] -ms.assetid: 8970f3c6-e2dd-407e-b2ec-964360eb8b43 --- # Compiler Warning (level 1) C4182 -\#include nesting level is 'number' deep; possible infinite recursion +> #include nesting level is 'number' deep; possible infinite recursion + +## Remarks The compiler ran out of space on the heap because of the number of nested include files. An include file is nested when it is included from another include file. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4183.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4183.md index f6151e2d0f2..1b3233348c9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4183.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4183.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4183" title: "Compiler Warning (level 1) C4183" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4183" +ms.date: 11/04/2016 f1_keywords: ["C4183"] helpviewer_keywords: ["C4183"] -ms.assetid: dc48312c-4b34-44dd-80ff-eb5f11d5ca47 --- # Compiler Warning (level 1) C4183 -'identifier': missing return type; assumed to be a member function returning 'int' +> 'identifier': missing return type; assumed to be a member function returning 'int' + +## Remarks The inline definition of a member function in a class or a structure does not have a return type. This member function is assumed to have a default return type of **`int`**. -The following sample generates C4183: +## Example + +The following example generates C4183: ```cpp // C4183.cpp @@ -20,6 +23,6 @@ The following sample generates C4183: #pragma warning(disable : 4430) class MyClass1; class MyClass2 { - MyClass1() {}; // C4183 + MyClass1() {} // C4183 }; ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4185.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4185.md index 92f1ada3b6b..d2bfec209ad 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4185.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4185.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4185" title: "Compiler Warning (level 1) C4185" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4185" +ms.date: 11/04/2016 f1_keywords: ["C4185"] helpviewer_keywords: ["C4185"] -ms.assetid: 37e7063a-35b1-4e05-ae31-e811dced02b9 --- # Compiler Warning (level 1) C4185 -ignoring unknown #import attribute 'attribute' +> ignoring unknown #import attribute 'attribute' + +## Remarks The attribute is not a valid attribute of `#import`. It is ignored. ## Example +The following example generates C4185: + ```cpp // C4185.cpp // compile with: /W1 /c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4186.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4186.md index 5e4248063e1..0f6985e5d1a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4186.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4186.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4186" title: "Compiler Warning (level 1) C4186" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4186" +ms.date: 11/04/2016 f1_keywords: ["C4186"] helpviewer_keywords: ["C4186"] -ms.assetid: caf3f7d8-f305-426b-8d4e-2b96f5c269ea --- # Compiler Warning (level 1) C4186 -\#import attribute 'attribute' requires count arguments; ignored +> #import attribute 'attribute' requires count arguments; ignored + +## Remarks A `#import` attribute has the wrong number of arguments. ## Example +The following example generates C4186: + ```cpp // C4186.cpp // compile with: /W1 /c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4187.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4187.md index 7690c5eca1f..8ff6b94d85c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4187.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4187.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4187" title: "Compiler Warning (level 1) C4187" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4187" +ms.date: 11/04/2016 f1_keywords: ["C4187"] helpviewer_keywords: ["C4187"] -ms.assetid: 2443d948-ab7b-472c-af43-5d81e09af677 --- # Compiler Warning (level 1) C4187 -\#import attributes 'attribute1' and 'attribute2' are incompatible; both ignored +> #import attributes 'attribute1' and 'attribute2' are incompatible; both ignored + +## Remarks A [#import](../../preprocessor/hash-import-directive-cpp.md) statement specified `no_implementation` and `implementation_only` attributes. Both are ignored. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4190.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4190.md index 7870bbed65c..57257424bda 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4190.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4190.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4190" title: "Compiler Warning (level 1) C4190" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4190" +ms.date: 11/04/2016 f1_keywords: ["C4190"] helpviewer_keywords: ["C4190"] -ms.assetid: a4d0ad93-a19a-4063-addd-36d605831567 --- # Compiler Warning (level 1) C4190 -'identifier1' has C-linkage specified, but returns UDT 'identifier2' which is incompatible with C +> 'identifier1' has C-linkage specified, but returns UDT 'identifier2' which is incompatible with C + +## Remarks A function or pointer to function has a UDT (user-defined type, which is a class, structure, enum, or union) as return type and `extern "C"` linkage. This is legal if: @@ -18,6 +19,8 @@ A function or pointer to function has a UDT (user-defined type, which is a class ## Example +The following example generates C4190: + ```cpp // C4190.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4215.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4215.md index ee07bacbca1..27a4c3ce647 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4215.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4215.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4215" title: "Compiler Warning (level 1) C4215" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4215" +ms.date: 11/04/2016 f1_keywords: ["C4215"] helpviewer_keywords: ["C4215"] -ms.assetid: f2aab64d-1bab-4f75-95ee-89e1263047b1 --- # Compiler Warning (level 1) C4215 -nonstandard extension used : long float +> nonstandard extension used : long float + +## Remarks The default Microsoft extensions (/Ze) treat **long float** as **`double`**. ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) does not. Use **`double`** to maintain compatibility. -The following sample generates C4215: +## Example + +The following example generates C4215: ```cpp // C4215.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4216.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4216.md index 26fd546e18b..aa54762a695 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4216.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4216.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4216" title: "Compiler Warning (level 1) C4216" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4216" +ms.date: 11/04/2016 f1_keywords: ["C4216"] helpviewer_keywords: ["C4216"] -ms.assetid: 211079dc-59d0-42a7-801c-2ddab21d7232 --- # Compiler Warning (level 1) C4216 -nonstandard extension used : float long +> nonstandard extension used : float long + +## Remarks + +The default Microsoft extensions (/Ze) treat **float long** as **`double`**. ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) does not. Use **`double`** to maintain compatibility. + +## Example -The default Microsoft extensions (/Ze) treat **float long** as **`double`**. ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)) does not. Use **`double`** to maintain compatibility. The following sample generates C4216: +The following example generates C4216: ```cpp // C4216.cpp 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 a93576090b4..21910d55dfc 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,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4218" -title: "Compiler Warning (level 1) C4218" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4) C4218" +description: "Learn more about: 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`**. +## Remarks + +With the default Microsoft extensions (`/Ze`), you can declare a variable without specifying a type or storage class. The default type is **`int`**. ## Example +The following example generates C4218: + ```cpp // C4218.c // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4224.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4224.md index 58abd03fe9a..9eea04e97ed 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4224.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4224.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4224" title: "Compiler Warning (level 1) C4224" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4224" +ms.date: 11/04/2016 f1_keywords: ["C4224"] helpviewer_keywords: ["C4224"] -ms.assetid: 1531cae0-5040-49fd-b149-005bb5085391 --- # Compiler Warning (level 1) C4224 -nonstandard extension used : formal parameter 'identifier' was previously defined as a type +> nonstandard extension used : formal parameter 'identifier' was previously defined as a type + +## Remarks The identifier was previously used as a **`typedef`**. This causes a warning under ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)). ## Example +The following example generates C4224: + ```cpp // C4224.cpp // compile with: /Za /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4226.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4226.md index 8861456c970..19124a35a03 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4226.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4226.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4226" title: "Compiler Warning (level 1) C4226" -ms.date: "10/25/2017" +description: "Learn more about: Compiler Warning (level 1) C4226" +ms.date: 10/25/2017 f1_keywords: ["C4226"] helpviewer_keywords: ["C4226"] -ms.assetid: 69d6bbde-1300-4e48-8a9c-3648c80ab441 --- # Compiler Warning (level 1) C4226 > nonstandard extension used : '*keyword*' is an obsolete keyword +## Remarks + The current version of Visual C++ does not use this keyword. This warning is automatically promoted to an error. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4227.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4227.md index b07ac66855a..d59944fbccf 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4227.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4227.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4227" title: "Compiler Warning (level 1) C4227" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4227" +ms.date: 11/04/2016 f1_keywords: ["C4227"] helpviewer_keywords: ["C4227"] -ms.assetid: 78f98374-c00b-4000-aefa-1b1c67b4666b --- # Compiler Warning (level 1) C4227 -anachronism used : qualifiers on reference are ignored +> anachronism used : qualifiers on reference are ignored + +## Remarks Using qualifiers like **`const`** or **`volatile`** with C++ references is an outdated practice. ## Example +The following example generates C4227: + ```cpp // C4227.cpp // compile with: /W1 /c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4228.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4228.md index 9d10d770f9b..da9cdeefa90 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4228.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4228.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4228" title: "Compiler Warning (level 1) C4228" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4228" +ms.date: 11/04/2016 f1_keywords: ["C4228"] helpviewer_keywords: ["C4228"] -ms.assetid: 9301d660-d601-464e-83f5-7ed844a3c6dc --- # Compiler Warning (level 1) C4228 -nonstandard extension used : qualifiers after comma in declarator list are ignored +> nonstandard extension used : qualifiers after comma in declarator list are ignored + +## Remarks Use of qualifiers like **`const`** or **`volatile`** after a comma when declaring variables is a Microsoft extension ([/Ze](../../build/reference/za-ze-disable-language-extensions.md)). ## Example +The following example generates C4228: + ```cpp // C4228.cpp // compile with: /W1 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 e4be2c9181b..cbc55d7f30d 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,21 +1,24 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4229" -title: "Compiler Warning (level 1) C4229" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4229" +description: "Learn more about: 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 + +## Remarks Using a Microsoft modifier such as **`__cdecl`** on a data declaration is an outdated practice. ## Example +The following example generates C4229: + ```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-c4230.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4230.md index 0365bac51a4..37dd1af4b1c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4230.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4230.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4230" title: "Compiler Warning (level 1) C4230" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4230" +ms.date: 11/04/2016 f1_keywords: ["C4230"] helpviewer_keywords: ["C4230"] -ms.assetid: a4be8729-74b6-44df-a5ea-e3f45aad0f8f --- # Compiler Warning (level 1) C4230 -anachronism used : modifiers/qualifiers interspersed; qualifier ignored +> anachronism used : modifiers/qualifiers interspersed; qualifier ignored + +## Remarks Using a qualifier before a Microsoft modifier such as **`__cdecl`** is an outdated practice. ## Example +The following example generates C4230: + ```cpp // C4230.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4237.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4237.md index 30336fc8024..122af024123 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4237.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4237.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4237" title: "Compiler Warning (level 1) C4237" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4237" +ms.date: 11/04/2016 f1_keywords: ["C4237"] helpviewer_keywords: ["C4237"] -ms.assetid: f2e86c4b-80d8-460e-9429-83c5f3f5d7ca --- # Compiler Warning (level 1) C4237 -'keyword' keyword is not yet supported, but reserved for future use +> 'keyword' keyword is not yet supported, but reserved for future use + +## Remarks A keyword in the C++ specification is not implemented in the Microsoft C++ compiler, but the keyword is not available as a user-defined symbol. -The following sample generates C4237: +## Example + +The following example generates C4237: ```cpp // C4237.cpp 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 b47e246b650..b0b11764a1c 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,75 @@ --- -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: + +- Defining your class to have virtual functions. +- Defining a virtual destructor. +- Defining functions to instantiate and delete instances of the type. + +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`. -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`. +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. ## Example -This sample exports a specialized class `VecWrapper` derived from `std::vector`. +The following example generates C4251: ```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-c4258.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4258.md index f2131c6a91c..a29bd856a5b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4258.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4258.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4258" title: "Compiler Warning (level 1) C4258" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4258" +ms.date: 11/04/2016 f1_keywords: ["C4258"] helpviewer_keywords: ["C4258"] -ms.assetid: bbb75e6d-6693-4e62-8ed3-b006a0ec55e3 --- # Compiler Warning (level 1) C4258 -'variable' : definition from the for loop is ignored; the definition from the enclosing scope is used" +> 'variable' : definition from the for loop is ignored; the definition from the enclosing scope is used" + +## Remarks + +Under [/Ze](../../build/reference/za-ze-disable-language-extensions.md) and [/Zc:forScope](../../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md), variables defined in a [for](../../cpp/for-statement-cpp.md) loop go out of scope after the **`for`** loop ends. This warning occurs if a variable with the same name as the loop variable, but defined in the enclosing loop, is used again in the scope containing the **`for`** loop. + +## Example -Under [/Ze](../../build/reference/za-ze-disable-language-extensions.md) and [/Zc:forScope](../../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md), variables defined in a [for](../../cpp/for-statement-cpp.md) loop go out of scope after the **`for`** loop ends. This warning occurs if a variable with the same name as the loop variable, but defined in the enclosing loop, is used again in the scope containing the **`for`** loop. For example: +For example: ```cpp // C4258.cpp 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 23996076bb1..a781621f80a 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,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4264" -title: "Compiler Warning (level 1) C4264" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4264" +description: "Learn more about: 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 + +## Remarks 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 3a8fdd16f45..d5b610b7592 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,19 +1,22 @@ --- -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 -'identifier' : 'const' automatic data initialized with compiler generated default constructor produces unreliable results +> 'identifier' : 'const' automatic data initialized with compiler generated default constructor produces unreliable results + +## Remarks A **`const`** automatic instance of a non-trivial class is initialized with a compiler-generated default constructor. ## Example +The following example generates C4269: + ```cpp // C4269.cpp // compile with: /c /LD /W1 @@ -24,7 +27,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-c4272.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4272.md index 6ef913aa807..d4f042ea5c1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4272.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4272.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4272" title: "Compiler Warning (level 1) C4272" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4272" +ms.date: 11/04/2016 f1_keywords: ["C4272"] helpviewer_keywords: ["C4272"] -ms.assetid: 0d6c1de4-2eef-42c4-b861-c221f8b495ef --- # Compiler Warning (level 1) C4272 -'function' : is marked __declspec(dllimport); must specify native calling convention when importing a function. +> 'function' : is marked __declspec(dllimport); must specify native calling convention when importing a function. + +## Remarks It is an error to export a function marked with the [__clrcall](../../cpp/clrcall.md) calling convention, and the compiler issues this warning if you attempt to import a function marked `__clrcall`. -The following sample generates C4272: +## Example + +The following example generates C4272: ```cpp // C4272.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md index 4bd91a8079a..d53d8ece27c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4273.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4273" title: "Compiler Warning (level 1) C4273" +description: "Learn more about: Compiler Warning (level 1) C4273" ms.date: 05/23/2022 f1_keywords: ["C4273"] helpviewer_keywords: ["C4273"] -ms.assetid: cc18611d-9454-40a4-ad73-69823d5888fb --- # Compiler Warning (level 1) C4273 > '*function*' : inconsistent DLL linkage +## Remarks + Two definitions in a file differ in their use of [`dllimport`](../../cpp/dllexport-dllimport.md). ## Examples -The following sample generates C4273, and shows how to fix it. +The following example generates C4273, and shows how to fix it. ```cpp // C4273.cpp @@ -23,7 +24,7 @@ char __declspec(dllimport) c; char c; // C4273, delete this line or the line above to resolve ``` -The following sample generates C4273. To fix it, delete the redeclaration of `printf_s`. +The following example generates C4273. To fix it, delete the redeclaration of `printf_s`. ```cpp // C4273_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4274.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4274.md index 2588a0e4a21..6e7ea2759ce 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4274.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4274.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4274" title: "Compiler Warning (level 1) C4274" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4274" +ms.date: 11/04/2016 f1_keywords: ["C4274"] helpviewer_keywords: ["C4274"] -ms.assetid: 5a948680-7ed1-469f-978d-ae99d154e161 --- # Compiler Warning (level 1) C4274 -\#ident ignored; see documentation for #pragma comment(exestr, 'string') +> #ident ignored; see documentation for #pragma comment(exestr, 'string') + +## Remarks The `#ident` directive, which inserts a user-specified string in the object or executable file, is deprecated. Consequently, the compiler ignores the directive. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4276.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4276.md index 7e8473bae3d..cd9812fc4e8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4276.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4276.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4276" title: "Compiler Warning (level 1) C4276" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4276" +ms.date: 11/04/2016 f1_keywords: ["C4276"] helpviewer_keywords: ["C4276"] -ms.assetid: 9d738c2d-29e5-408a-b9ff-be1a850b2238 --- # Compiler Warning (level 1) C4276 -'function' : no prototype provided; assumed no parameters +> 'function' : no prototype provided; assumed no parameters + +## Remarks When you take the address of a function with the [__stdcall](../../cpp/stdcall.md) calling convention, you must give a prototype so the compiler can create the function's decorated name. Since *function* has no prototype, the compiler, when creating the decorated name, assumes the function has no parameters. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4286.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4286.md index a83f7124352..248b4040981 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4286.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4286.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4286" title: "Compiler Warning (level 1) C4286" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4286" +ms.date: 11/04/2016 f1_keywords: ["C4286"] helpviewer_keywords: ["C4286"] -ms.assetid: 93eadd6c-6f36-413b-ba91-c9aa2314685a --- # Compiler Warning (level 1) C4286 -'type1' : is caught by base class ('type2') on line number +> 'type1' : is caught by base class ('type2') on line number + +## Remarks The specified exception type is handled by a previous handler. The type for the second catch is derived from the type of the first. Exceptions for a base class catch exceptions for a derived class. ## Example +The following example generates C4286: + ```cpp //C4286.cpp // compile with: /W1 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4288.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4288.md index 67b2cfa8515..5a7b2f7bc3d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4288.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4288.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4288" title: "Compiler Warning (level 1) C4288" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4288" +ms.date: 11/04/2016 f1_keywords: ["C4288"] helpviewer_keywords: ["C4288"] -ms.assetid: 6aaeb139-90cd-457a-9d37-65687042736f --- # Compiler Warning (level 1) C4288 > nonstandard extension used : 'var' : loop control variable declared in the for-loop is used outside the for-loop scope; it conflicts with the declaration in the outer scope +## Remarks + When compiling with [`/Ze`](../../build/reference/za-ze-disable-language-extensions.md) and **/Zc:forscope-**, a variable declared in a **`for`** loop was used after the [for](../../cpp/for-statement-cpp.md)-loop scope. A Microsoft extension to the C++ language allows this variable to remain in scope, and C4288 reminds you that the first declaration of the variable is not used. See [`/Zc:forScope`](../../build/reference/zc-forscope-force-conformance-in-for-loop-scope.md) for information about how to specify the Microsoft extension in **`for`** loops with /Ze. -The following sample generates C4288: +## Example + +The following example generates C4288: ```cpp // C4288.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4291.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4291.md index e1e251737f2..fb8a23defbe 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4291.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4291.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4291" title: "Compiler Warning (level 1) C4291" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4291" +ms.date: 11/04/2016 f1_keywords: ["C4291"] helpviewer_keywords: ["C4291"] -ms.assetid: c2b95dea-38f2-4609-9104-707c30798da4 --- # Compiler Warning (level 1) C4291 -'declaration' : no matching operator delete found; memory will not be freed if initialization throws an exception +> 'declaration' : no matching operator delete found; memory will not be freed if initialization throws an exception + +## Remarks A placement [new](../../cpp/new-operator-cpp.md) is used for which there is no placement [delete](../../cpp/delete-operator-cpp.md). @@ -16,7 +17,11 @@ When memory is allocated for an object with operator **`new`**, the object's con If you use the operator **`new`** without any extra arguments and compile with [/GX](../../build/reference/gx-enable-exception-handling.md), [/EHs](../../build/reference/eh-exception-handling-model.md), or /EHa options to enable exception handling, the compiler will generate code to call operator **`delete`** if the constructor throws an exception. -If you use the placement form of the **`new`** operator (the form with arguments in addition to the size of the allocation) and the object's constructor throws an exception, the compiler will still generate code to call operator **`delete`**; but it will only do so if a placement form of operator **`delete`** exists matching the placement form of the operator **`new`** that allocated the memory. For example: +If you use the placement form of the **`new`** operator (the form with arguments in addition to the size of the allocation) and the object's constructor throws an exception, the compiler will still generate code to call operator **`delete`**; but it will only do so if a placement form of operator **`delete`** exists matching the placement form of the operator **`new`** that allocated the memory. + +## Example + +For example: ```cpp // C4291.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4293.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4293.md index 288d303e446..cb24eb825ba 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4293.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4293.md @@ -4,21 +4,20 @@ description: "Describes the causes of MSVC compiler warning C4293, and shows how ms.date: 07/15/2020 f1_keywords: ["C4293"] helpviewer_keywords: ["C4293"] -ms.assetid: babecd96-eb51-41a5-9835-462c7a46dbad --- # Compiler Warning (level 1) C4293 > '*operator*' : shift count negative or too big, undefined behavior -If a shift count is negative or too large, the behavior of the resulting image is undefined. - ## Remarks +If a shift count is negative or too large, the behavior of the resulting image is undefined. + To resolve this issue, you can use a cast on the first operand to expand it to the size of the result type. ## Example -The following sample generates C4293, and shows ways to fix it: +The following example generates C4293, and shows ways to fix it: ```cpp // C4293.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4297.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4297.md index c300a5b4f1d..25b6d26a536 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4297.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4297.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4297" title: "Compiler Warning (level 1) C4297" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4297" +ms.date: 11/04/2016 f1_keywords: ["C4297"] helpviewer_keywords: ["C4297"] -ms.assetid: ba92fcdc-9f70-4f60-abe6-281f9582ca59 --- # Compiler Warning (level 1) C4297 -'function' : function assumed not to throw an exception but does +> 'function' : function assumed not to throw an exception but does + +## Remarks A function declaration contains a (possibly implicit) **`noexcept`** specifier, an empty **`throw`** exception specifier, or a [__declspec(nothrow)](../../cpp/nothrow-cpp.md) attribute, and the definition contains one or more [throw](../../cpp/try-throw-and-catch-statements-cpp.md) statements. To resolve C4297, do not attempt to throw exceptions in functions that are declared `__declspec(nothrow)`, `noexcept(true)` or `throw()`. Alternatively, remove the **`noexcept`**, `throw()`, or `__declspec(nothrow)` specification. @@ -18,7 +19,9 @@ For more information on exception specifications, see [Exception Specifications This warning is also generated for __declspec([dllexport](../../cpp/dllexport-dllimport.md)) functions marked extern "C", even if they are C++ functions. -The following sample generates C4297: +## Example + +The following example generates C4297: ```cpp // C4297.cpp 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 d7faa04094d..b34e71b9984 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" -ms.date: "01/17/2018" +title: "Compiler Warning (level 1 and level 2 and level 4) C4305" +description: "Learn more about: 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 @@ -15,7 +15,7 @@ This warning is issued when a value is converted to a smaller type in an initial ## Example -This sample shows two ways you might see this warning: +This example shows two ways you might see this warning: ```cpp // C4305.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4311.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4311.md index 241e383b04a..f27b08010af 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4311.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4311.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4311" title: "Compiler Warning (level 1) C4311" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4311" +ms.date: 11/04/2016 f1_keywords: ["C4311"] helpviewer_keywords: ["C4311"] -ms.assetid: ddc579d0-d051-47bc-915d-71ffb32323c9 --- # Compiler Warning (level 1) C4311 -'variable' : pointer truncation from 'type' to 'type' +> 'variable' : pointer truncation from 'type' to 'type' + +## Remarks This warning detects 64-bit pointer truncation issues. For example, if code is compiled for a 64-bit architecture, the value of a pointer (64 bits) will be truncated if it is assigned to an **`int`** (32 bits). For more information, see [Rules for Using Pointers](/windows/win32/WinProg64/rules-for-using-pointers). For additional information about common causes of warning C4311, see [Common Compiler Errors](/windows/win32/WinProg64/common-compiler-errors). +## Example + The following code example generates C4311 when compiled for a 64-bit target, and then demonstrates how to fix it: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4312.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4312.md index 3bb9426aab6..4cbe2bf10b6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4312.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4312.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4312" title: "Compiler Warning (level 1) C4312" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4312" +ms.date: 11/04/2016 f1_keywords: ["C4312"] helpviewer_keywords: ["C4312"] -ms.assetid: 541906ed-4f62-4bcb-947f-cf9ae7411bcb --- # Compiler Warning (level 1) C4312 -'operation' : conversion from 'type1' to 'type2' of greater size +> 'operation' : conversion from 'type1' to 'type2' of greater size + +## Remarks This warning detects an attempt to assign a 32-bit value to a 64-bit pointer type, for example, casting a 32-bit **`int`** or **`long`** to a 64-bit pointer. @@ -16,6 +17,8 @@ This can be an unsafe conversion even for pointer values that fit in 32 bits whe This warning is only issued for 64-bit compilation targets. For more information, see [Rules for Using Pointers](/windows/win32/WinProg64/rules-for-using-pointers). +## Example + The following code example generates C4312 when it is compiled for 64-bit targets: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4313.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4313.md index 44d7f2e2556..64050afef86 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4313.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4313.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4313" title: "Compiler Warning (level 1) C4313" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4313" +ms.date: 11/04/2016 f1_keywords: ["C4313"] helpviewer_keywords: ["C4313"] -ms.assetid: bcf64191-e2cf-452e-97b4-423fcec2d07c --- # Compiler Warning (level 1) C4313 -'function' : 'format specifier' in format string conflicts with argument number of type 'type' +> 'function' : 'format specifier' in format string conflicts with argument number of type 'type' + +## Remarks There is a conflict between the format specified and the value that you are passing. For example, you passed a 64-bit parameter to an unqualified %d format specifier, which expects a 32-bit integer parameter. This warning is only in effect when the code is compiled for 64-bit targets. ## Example -The following code sample generates C4313 when it is compiled for a 64-bit target. +The following code example generates C4313 when it is compiled for a 64-bit target. ```cpp // C4313.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4319.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4319.md index af4e194b373..486da6781bd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4319.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4319.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4319" title: "Compiler Warning (level 1) C4319" -ms.date: "01/18/2018" +description: "Learn more about: Compiler Warning (level 1) C4319" +ms.date: 01/18/2018 f1_keywords: ["C4319"] helpviewer_keywords: ["C4319"] -ms.assetid: 1fac8048-9bd6-4552-a21c-192c67772bb9 --- # Compiler Warning (level 1) C4319 > '~' : zero extending '*type1*' to '*type2*' of greater size +## Remarks + The result of the **~** (bitwise complement) operator is unsigned and then zero-extended when it is converted to a larger type. ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4325.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4325.md index bb1233d0d72..7ac44c2fca2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4325.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4325.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4325" title: "Compiler Warning (level 1) C4325" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4325" +ms.date: 08/27/2018 f1_keywords: ["C4325"] helpviewer_keywords: ["C4325"] -ms.assetid: 8127a08c-d626-481b-aa7b-04a3fdc9a9ec --- # Compiler Warning (level 1) C4325 @@ -12,7 +11,11 @@ ms.assetid: 8127a08c-d626-481b-aa7b-04a3fdc9a9ec ## Remarks -You may not change the attributes of a standard section. For example: +You may not change the attributes of a standard section. + +## Example + +For example: ```cpp #pragma section(".sdata", long) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4326.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4326.md index 4cad0b88a46..53d3f74109a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4326.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4326.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4326" title: "Compiler Warning (level 1) C4326" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4326" +ms.date: 08/27/2018 f1_keywords: ["C4326"] helpviewer_keywords: ["C4326"] -ms.assetid: d44d2c4e-9456-42d3-b35b-4ba4b2d42ec7 --- # Compiler Warning (level 1) C4326 @@ -16,7 +15,7 @@ A function returned a type other than *type1*. For example, using [/Za](../../bu ## Example -The following sample generates C4326 and shows how to fix it: +The following example generates C4326 and shows how to fix it: ```cpp // C4326.cpp 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 22106ed141b..63d963b4898 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 @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4329" title: "Compiler Warning (level 1) C4329" -ms.date: "11/04/2016" +description: "Learn more about: 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 + +## Remarks + +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. + +## Example -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: +The following example generates C4329: ```cpp // C4329.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4333.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4333.md index 972196b570d..7f2ed906c9a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4333.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4333.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4333" title: "Compiler Warning (level 1) C4333" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4333" +ms.date: 11/04/2016 f1_keywords: ["C4333"] helpviewer_keywords: ["C4333"] -ms.assetid: d3763c52-6110-4da0-84db-5264e3f3f166 --- # Compiler Warning (level 1) C4333 -'operator' : right shift by too large amount, data loss +> 'operator' : right shift by too large amount, data loss + +## Remarks A right shift operation was too large an amount. All significant bits are shifted out and the result will always be zero. ## Example -The following sample generates C4333. +The following example generates C4333. ```cpp // C4333.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4340.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4340.md index 58981026e43..004d0d3c45f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4340.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4340.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4340" title: "Compiler Warning (level 1) C4340" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4340" +ms.date: 11/04/2016 f1_keywords: ["C4340"] helpviewer_keywords: ["C4340"] -ms.assetid: ddd5344b-5167-4c55-a318-20615052fd54 --- # Compiler Warning (level 1) C4340 -'value' : value wrapped from positive to negative value +> 'value' : value wrapped from positive to negative value + +## Remarks The **`enum`** value is greater than the largest **`enum`** positive value wrapped around to a negative value. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4342.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4342.md index b16363c5117..63ce40a82f9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4342.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4342.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4342" title: "Compiler Warning (level 1) C4342" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4342" +ms.date: 11/04/2016 f1_keywords: ["C4342"] helpviewer_keywords: ["C4342"] -ms.assetid: 47d4d5ab-069f-4cdc-98c3-10d649577a37 --- # Compiler Warning (level 1) C4342 -behavior change: '*function*' called, but a member operator was called in previous versions +> behavior change: '*function*' called, but a member operator was called in previous versions + +## Remarks In versions of Visual C++ before Visual Studio 2002, a member was called, but this behavior has been changed and the compiler now finds the best match in namespace scope. @@ -18,7 +19,9 @@ This warning should be disabled after you successfully port your code to the cur 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 C4342: +## Example + +The following example generates C4342: ```cpp // C4342.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4344.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4344.md index 24e2d0b749f..49eccaec8b4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4344.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4344.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4344" title: "Compiler Warning (level 1) C4344" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4344" +ms.date: 11/04/2016 f1_keywords: ["C4344"] helpviewer_keywords: ["C4344"] -ms.assetid: cd20859d-f07f-4c70-904b-cb756a53b1ed --- # Compiler Warning (level 1) C4344 -behavior change: use of explicit template arguments results in call to 'function' +> behavior change: use of explicit template arguments results in call to 'function' + +## Remarks A call to a function using explicit template arguments calls a different function than it would if explicit arguments had not been specified diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4346.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4346.md index a508a599219..568ad7cd845 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4346.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4346.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4346" title: "Compiler Warning (level 1) C4346" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4346" +ms.date: 11/04/2016 f1_keywords: ["C4346"] helpviewer_keywords: ["C4346"] -ms.assetid: 68ee562d-cca9-4a2a-9a1b-14ad1a1e7396 --- # Compiler Warning (level 1) C4346 -'name' : dependent name is not a type +> 'name' : dependent name is not a type + +## Remarks The [typename](../../cpp/typename.md) keyword is required if a dependent name is to be treated as a type. For code that works the same in all versions of Visual C++, add **`typename`** to the declaration. -The following sample generates C4346: +## Examples + +The following example generates C4346: ```cpp // C4346.cpp @@ -25,7 +28,7 @@ struct C { }; ``` -The following samples shows other examples where the **`typename`** keyword is required: +The following shows other examples where the **`typename`** keyword is required: ```cpp // C4346b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4348.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4348.md index 9a691ded0a2..e123b095dc9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4348.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4348.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4348" title: "Compiler Warning (level 1) C4348" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4348" +ms.date: 11/04/2016 f1_keywords: ["C4348"] helpviewer_keywords: ["C4348"] -ms.assetid: 816010eb-6079-48d5-a41b-0fc4d67cfe4c --- # Compiler Warning (level 1) C4348 -'type' : redefinition of default parameter : parameter number +> 'type' : redefinition of default parameter : parameter number + +## Remarks A template parameter was redefined. -The following sample generates C4348: +## Example + +The following example generates C4348: ```cpp // C4348.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4350.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4350.md index 99f15243ebb..04e98691df3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4350.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4350.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4350" title: "Compiler Warning (level 1) C4350" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4350" +ms.date: 11/04/2016 f1_keywords: ["C4350"] helpviewer_keywords: ["C4350"] -ms.assetid: 4cc8ed67-64c4-4da5-a7a5-a639232baa23 --- # Compiler Warning (level 1) C4350 -behavior change: 'member1' called instead of 'member2' +> behavior change: 'member1' called instead of 'member2' + +## Remarks An rvalue cannot be bound to a non-const reference. In versions of Visual C++ before Visual Studio 2003, it was possible to bind an rvalue to a non-const reference in a direct initialization. This code now gives a warning. @@ -20,7 +21,9 @@ If you get this warning, examine your code to see if it depends on binding rvalu 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 C4350: +## Example + +The following example generates C4350: ```cpp // C4350.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4353.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4353.md index afade9f92fb..ced2c8a0687 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4353.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4353.md @@ -1,23 +1,26 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4353" title: "Compiler Warning (level 1) C4353" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4353" +ms.date: 11/04/2016 f1_keywords: ["C4353"] helpviewer_keywords: ["C4353"] -ms.assetid: 6e79f186-ed82-4c95-9923-0ad5bb9c4db1 --- # Compiler Warning (level 1) C4353 -nonstandard extension used: constant 0 as function expression. Use '__noop' function intrinsic instead +> nonstandard extension used: constant 0 as function expression. Use '__noop' function intrinsic instead + +## Remarks You cannot use the constant zero (0) as a function expression. For more information, see [__noop](../../intrinsics/noop.md). -The following sample generates C4353: +## Example + +The following example generates C4353: ```cpp // C4353.cpp // compile with: /W1 -void MyPrintf(void){}; +void MyPrintf(void){} #define X 0 #if X #define DBPRINT MyPrint diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4358.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4358.md index 02e7ffc810f..4c4832aa51b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4358.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4358.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4358" title: "Compiler Warning (level 1) C4358" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4358" +ms.date: 11/04/2016 f1_keywords: ["C4358"] helpviewer_keywords: ["C4358"] -ms.assetid: a9848f84-14b3-405e-81bf-ee3e91a51511 --- # Compiler Warning (level 1) C4358 -'operator': return type of combined delegates is not 'void'; returned value is undefined +> 'operator': return type of combined delegates is not 'void'; returned value is undefined + +## Remarks Two delegates were combined and the return value is not void. If two delegates with non-void return values are combined, the compiler will not be able to do a proper assignment if the return value of the delegate is used. -The following sample generates C4358: +## Example + +The following example generates C4358: ```cpp // C4358.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4364.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4364.md index 3b84470325b..43cd2ffc11f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4364.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4364.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4364" title: "Compiler Warning (level 1) C4364" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4364" +ms.date: 11/04/2016 f1_keywords: ["C4364"] helpviewer_keywords: ["C4364"] -ms.assetid: 1477634c-d60f-4570-ad16-1aaeae24ac7f --- # Compiler Warning (level 1) C4364 -\#using for assembly 'file' previously seen at location(line_number) without as_friend attribute; as_friend not applied +> #using for assembly 'file' previously seen at location(line_number) without as_friend attribute; as_friend not applied + +## Remarks A `#using` directive was repeated for a given metadata file, but the **`as_friend`** qualifier was not used in the first occurrence; the compiler will ignore the second **`as_friend`**. For more information, see [Friend Assemblies (C++)](../../dotnet/friend-assemblies-cpp.md). -## Examples +## Example -The following sample creates a component. +The following example creates a component. ```cpp // C4364.cpp @@ -24,7 +25,7 @@ The following sample creates a component. ref class A {}; ``` -The following sample generates C4364. +The following example generates C4364. ```cpp // C4364_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4369.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4369.md index d3d741d7755..23fc40ea41b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4369.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4369.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4369" title: "Compiler Warning (level 1) C4369" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4369" +ms.date: 11/04/2016 f1_keywords: ["C4369"] helpviewer_keywords: ["C4369"] -ms.assetid: ade87e84-36be-4e00-be99-2930af848feb --- # Compiler Warning (level 1) C4369 -'enumerator' : enumerator value 'value' cannot be represented as 'type', value is 'new_value' +> 'enumerator' : enumerator value 'value' cannot be represented as 'type', value is 'new_value' + +## Remarks An enumerator was calculated to be greater than the greatest value for the specified underlying type. This caused an overflow and the compiler wrapped the enumerator value to the lowest possible value for the type. ## Example -The following sample generates C4369. +The following example generates C4369. ```cpp // C4369.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4374.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4374.md index 836a46f41a8..4341cfc2032 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4374.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4374.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4374" title: "Compiler Warning (level 1) C4374" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4374" +ms.date: 11/04/2016 f1_keywords: ["C4374"] helpviewer_keywords: ["C4374"] -ms.assetid: 4ac9aaec-d815-4b6e-825f-fa872092dd3b --- # Compiler Warning (level 1) C4374 -'function1': interface method will not be implemented by non-virtual method 'function2' +> 'function1': interface method will not be implemented by non-virtual method 'function2' + +## Remarks The compiler expected to find the [virtual](../../cpp/virtual-specifier.md) keyword on a method definition. -The following sample generates C4374: +## Example + +The following example generates C4374: ```cpp // C4374.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4375.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4375.md index ccd68495cc6..33fe16a7dfc 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4375.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4375.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4375" title: "Compiler Warning (level 1) C4375" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4375" +ms.date: 11/04/2016 f1_keywords: ["C4375"] helpviewer_keywords: ["C4375"] -ms.assetid: a19821b5-e9b6-4228-abe7-d812507d6a2a --- # Compiler Warning (level 1) C4375 -non-public method 'method2' does not override 'method1' +> non-public method 'method2' does not override 'method1' + +## Remarks A type that implements another type defined an override method, but the override was not public. Therefore, the method does not override the base type method. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4376.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4376.md index fd0d5d27dde..ad88d8b6893 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4376.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4376.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4376" title: "Compiler Warning (level 1) C4376" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4376" +ms.date: 11/04/2016 f1_keywords: ["C4376"] helpviewer_keywords: ["C4376"] -ms.assetid: 5f202c74-9489-48fe-b36f-19cd882b1589 --- # Compiler Warning (level 1) C4376 -access specifier 'old_specifier:' is no longer supported: please use 'new_specifier:' instead +> access specifier 'old_specifier:' is no longer supported: please use 'new_specifier:' instead + +## Remarks For more information on specifying type and member accessibility in metadata, 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) in [How to: Define and Consume Classes and Structs (C++/CLI)](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md). ## Example -The following sample generates C4376. +The following example generates C4376. ```cpp // C4376.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4377.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4377.md index 2c5b708fa07..1c326f787a2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4377.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4377.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4377" title: "Compiler Warning (level 1) C4377" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4377" +ms.date: 11/04/2016 f1_keywords: ["C4377"] helpviewer_keywords: ["C4377"] -ms.assetid: a1c797b8-cd5e-4a56-b430-d07932e811cf --- # Compiler Warning (level 1) C4377 -native types are private by default; -d1PrivateNativeTypes is deprecated +> native types are private by default; -d1PrivateNativeTypes is deprecated + +## Remarks In previous releases, native types in assemblies were public by default, and an internal, undocumented compiler option (**/d1PrivateNativeTypes**) was used to make them private. @@ -16,7 +17,7 @@ All types, native and CLR, are now private by default in an assembly, so **/d1Pr ## Example -The following sample generates C4377. +The following example generates C4377. ```cpp // C4377.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4378.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4378.md index d46842152e7..2573597b3fc 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4378.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4378.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4378" title: "Compiler Warning (level 1) C4378" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4378" +ms.date: 11/04/2016 f1_keywords: ["C4378"] helpviewer_keywords: ["C4378"] -ms.assetid: d08e11ef-891a-4752-9a5e-360e7394acf7 --- # Compiler Warning (level 1) C4378 -Must obtain function pointers to run initializers; consider System::ModuleHandle::ResolveMethodHandle +> Must obtain function pointers to run initializers; consider System::ModuleHandle::ResolveMethodHandle + +## Remarks Under **/clr**, initializer symbols contain function tokens, not functions pointers. You need to convert tokens to pointers using . -## Examples +## Example -The following sample generates C4378. +The following example generates C4378. ```cpp // C4378.cpp @@ -56,7 +57,7 @@ int main () { } ``` -The following sample shows how to resolve C4378. +The following example shows how to resolve C4378. ```cpp // C4378_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4379.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4379.md index 8f56e1419a0..9ed0d1e208b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4379.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4379.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4379" title: "Compiler Warning (level 1) C4379" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4379" +ms.date: 11/04/2016 f1_keywords: ["C4379"] helpviewer_keywords: ["C4379"] -ms.assetid: b23e8132-69aa-4649-9c1e-09813b9fb5b7 --- # Compiler Warning (level 1) C4379 -Version version of the common language runtime is not supported by this compiler. Using this version may cause unexpected results. +> Version version of the common language runtime is not supported by this compiler. Using this version may cause unexpected results. + +## Remarks You have a previous version of the common language runtime on your machine, but not the current version. To resolve C4379, install the version of the common language runtime that shipped with your compiler. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4381.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4381.md index 29e6cc6ddcc..40eb33d0d75 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4381.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4381.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4381" title: "Compiler Warning (level 1) C4381" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4381" +ms.date: 11/04/2016 f1_keywords: ["C4381"] helpviewer_keywords: ["C4381"] -ms.assetid: f67a6db3-b334-4b2e-8182-b30c7a3c7c32 --- # Compiler Warning (level 1) C4381 -'function1': interface method will not be implemented by non-public method 'function2' +> 'function1': interface method will not be implemented by non-public method 'function2' + +## Remarks A class must implement all function in an interface. A class can satisfy this condition if one of its base classes implements the function. However, the function must be implemented as a public function. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4382.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4382.md index a0ba7993101..18d02708b01 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4382.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4382.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4382" title: "Compiler Warning (level 1) C4382" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4382" +ms.date: 11/04/2016 f1_keywords: ["C4382"] helpviewer_keywords: ["C4382"] -ms.assetid: 34be9ad3-bae6-411a-8f80-0c8fd0d2c092 --- # Compiler Warning (level 1) C4382 @@ -22,7 +21,7 @@ For more information, see [/clr (Common Language Runtime Compilation)](../../bui ## Example -The following sample generates C4382. +The following example generates C4382. ```cpp // C4382.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4383.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4383.md index bd6efac7c97..77526a9e69a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4383.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4383.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4383" title: "Compiler Warning (level 1) C4383" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4383" +ms.date: 11/04/2016 f1_keywords: ["C4383"] helpviewer_keywords: ["C4383"] -ms.assetid: 96c0e52d-874e-4b57-a154-0e49b6a00fae --- # Compiler Warning (level 1) C4383 -'instance_dereference_operator' : 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 +> 'instance_dereference_operator' : 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 + +## Remarks When you add a user-defined instance override of the dereference operator in a managed type, you potentially override the ability of the type's dereference operator to return the handle's object. Consider writing a static, user-defined dereference operator. @@ -18,7 +19,7 @@ Also, an instance operator is not available to other language compilers via refe ## Example -The following sample generates C4383. +The following example generates C4383. ```cpp // C4383.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 a4c538bc31f..bc7bcf67f1e 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 @@ -1,20 +1,26 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4384" title: "Compiler Warning (level 1) C4384" -ms.date: "11/04/2016" +description: "Learn more about: 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 + +## Remarks + +A `pragma` directive that must be applied at a global scope, was found in a different scope. -The [make_public](../../preprocessor/make-public.md) pragma was applied incorrectly. +The warning applies to the following `pragma` directives: +* [`detect_mismatch`](../../preprocessor/detect-mismatch.md) +* `extern_absolute` +* [`make_public`](../../preprocessor/make-public.md) ## Example -The following sample generates C4384. +The following example generates C4384. ```cpp // C4384.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4391.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4391.md index be45ba9d293..fd71f025e23 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4391.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4391.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4391" title: "Compiler Warning (level 1) C4391" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4391" +ms.date: 11/04/2016 f1_keywords: ["C4391"] helpviewer_keywords: ["C4391"] -ms.assetid: 95c6182c-fae9-4174-8f7b-98aa352e68ca --- # Compiler Warning (level 1) C4391 -'signature' : incorrect return type for intrinsic function, expected 'type' +> 'signature' : incorrect return type for intrinsic function, expected 'type' + +## Remarks A function declaration for a compiler intrinsic had the wrong return type. The resulting image may not run correctly. To fix this warning, either correct the declaration or delete the declaration and simply #include the appropriate header file. -The following sample generates C4391: +## Example + +The following example generates C4391: ```cpp // C4391.cpp 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 3e6c6317c5c..01aadb254d1 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4392" -title: "Compiler Warning (level 1) C4392" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4392" +description: "Learn more about: 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. +## Remarks -To fix this warning, either correct the declaration or delete the declaration and simply #include the appropriate header file. +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. -The following sample generates C4392: +This warning is always issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable or change the warning level. + +## Example + +The following example generates C4392: ```cpp // C4392.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4393.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4393.md index 2e0d6b6e8e9..82cf3e5048c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4393.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4393.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4393" title: "Compiler Warning (level 1) C4393" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4393" +ms.date: 11/04/2016 f1_keywords: ["C4393"] helpviewer_keywords: ["C4393"] -ms.assetid: 353a0539-d1ea-4c1b-8849-c9b321ec9842 --- # Compiler Warning (level 1) C4393 -'var' : const has no effect on literal data member; ignored +> 'var' : const has no effect on literal data member; ignored + +## Remarks A [literal](../../extensions/literal-cpp-component-extensions.md) data member was also specified as const. Since a literal data member implies const, you do not need to add const to the declaration. -The following sample generates C4393: +## Example + +The following example generates C4393: ```cpp // C4393.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4395.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4395.md index 98523b30ba7..eb6c4a27418 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4395.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4395.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4395" title: "Compiler Warning (level 1) C4395" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4395" +ms.date: 11/04/2016 f1_keywords: ["C4395"] helpviewer_keywords: ["C4395"] -ms.assetid: 8051469a-3a39-4677-80f7-1300fbffe8ea --- # Compiler Warning (level 1) C4395 -'function' : member function will be invoked on a copy of the initonly data member 'member' +> 'function' : member function will be invoked on a copy of the initonly data member 'member' + +## Remarks A member function was called on an [initonly (C++/CLI)](../../dotnet/initonly-cpp-cli.md) data member. C4395 warns that the **initonly** data member cannot be modified by the function. -The following sample generates C4395: +## Example + +The following example generates C4395: ```cpp // C4395.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4397.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4397.md index f957af30e6f..2e639136c27 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4397.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4397.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4397" title: "Compiler Warning (level 1) C4397" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4397" +ms.date: 11/04/2016 f1_keywords: ["C4397"] helpviewer_keywords: ["C4397"] -ms.assetid: 6346fdc2-dbbf-4fba-803a-32b0d0a707be --- # Compiler Warning (level 1) C4397 -DefaultCharSetAttribute is ignored +> DefaultCharSetAttribute is ignored + +## Remarks is ignored by the Microsoft C++ compiler. To specify a character set for the DLL, use the CharSet option of DllImport. For more information, see [Using C++ Interop (Implicit PInvoke)](../../dotnet/using-cpp-interop-implicit-pinvoke.md). ## Example -The following sample generates C4397. +The following example generates C4397. ```cpp // C4397.cpp 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 a99bfcba5c7..b3d523f9ed6 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,11 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4399" -title: "Compiler Warning (level 1) C4399" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4399" +description: "Learn more about: 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,11 +13,13 @@ 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 -The following sample generates C4399. +The following example generates C4399. ```cpp // C4399.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4401.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4401.md index 8bc6447524d..0e77fd61c51 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4401.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4401.md @@ -1,18 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4401" title: "Compiler Warning (level 1) C4401" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4401" +ms.date: 11/04/2016 f1_keywords: ["C4401"] helpviewer_keywords: ["C4401"] -ms.assetid: 2e7ca136-f144-4b40-b847-82976e8643fc --- # Compiler Warning (level 1) C4401 -'bitfield' : member is bit field +> 'bitfield' : member is bit field + +## Remarks Inline assembly code tries to access a bit-field member. Inline assembly cannot access bit-field members, so the last packing boundary before the bit-field member is used. -To avoid this warning, cast the bit field to an appropriate type before making the reference in inline assembly code. The following sample generates C4401: +To avoid this warning, cast the bit field to an appropriate type before making the reference in inline assembly code. + +## Example + +The following example generates C4401: ```cpp // C4401.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4402.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4402.md index 564054771a1..986cfddad83 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4402.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4402.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4402" title: "Compiler Warning (level 1) C4402" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4402" +ms.date: 11/04/2016 f1_keywords: ["C4402"] helpviewer_keywords: ["C4402"] -ms.assetid: 2aaecfae-1e79-4787-87e8-0973f7ec0efe --- # Compiler Warning (level 1) C4402 -must use PTR operator +> must use PTR operator + +## Remarks A type is used on an operand without a PTR operator when referring to or casting to a type in inline assembly code. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4403.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4403.md index 1d3e599dcba..afb02f7bd0b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4403.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4403.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4403" title: "Compiler Warning (level 1) C4403" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4403" +ms.date: 11/04/2016 f1_keywords: ["C4403"] helpviewer_keywords: ["C4403"] -ms.assetid: d95597c9-4762-4f33-86e4-1d98f0e80d52 --- # Compiler Warning (level 1) C4403 -illegal PTR operator +> illegal PTR operator + +## Remarks A PTR operator is used inappropriately in inline assembler code. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4405.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4405.md index b2ad983ac70..92efb9f9abd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4405.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4405.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4405" title: "Compiler Warning (level 1) C4405" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4405" +ms.date: 11/04/2016 f1_keywords: ["C4405"] helpviewer_keywords: ["C4405"] -ms.assetid: 155c64d6-58ae-4455-b61f-ccd711c5da96 --- # Compiler Warning (level 1) C4405 -'identifier' : identifier is reserved word +> 'identifier' : identifier is reserved word + +## Remarks + +A word reserved for inline assembly is used as a variable name. This may cause unpredictable results. To fix this warning, avoid naming variables with words reserved for inline assembly. + +## Example -A word reserved for inline assembly is used as a variable name. This may cause unpredictable results. To fix this warning, avoid naming variables with words reserved for inline assembly. The following sample generates C4405: +The following example generates C4405: ```cpp // C4405.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4406.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4406.md index 56566edc0fe..e600ed36ea4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4406.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4406.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4406" title: "Compiler Warning (level 1) C4406" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4406" +ms.date: 11/04/2016 f1_keywords: ["C4406"] helpviewer_keywords: ["C4406"] -ms.assetid: a3204731-2285-401c-b73b-af98586a86fa --- # Compiler Warning (level 1) C4406 -operand on directive ignored +> operand on directive ignored + +## Remarks The directive does not take any operands, but an operand was specified. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md index c8376a2dad2..88b9df38c30 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4407.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4407" title: "Compiler Warning (level 1) C4407" +description: "Learn more about: Compiler Warning (level 1) C4407" ms.date: 04/13/2021 f1_keywords: ["C4407"] helpviewer_keywords: ["C4407"] @@ -9,17 +9,17 @@ helpviewer_keywords: ["C4407"] > cast between different pointer to member representations, compiler may generate incorrect code -An incorrect cast between pointer-to-member types was detected. - ## Remarks +An incorrect cast between pointer-to-member types was detected. + C4407 can be generated because of compiler conformance work that was done in Visual Studio 2005. Pointer-to-member now requires a qualified name and the address-of operator (&). -C4407 can occur if you cast between a multiple inheritance pointer-to-member to a single inheritance pointer-to-member. Sometimes this can work, but sometimes it can’t because the single inheritance pointer-to-member representation doesn’t hold sufficient information. Compiling with the **`/vmm`** might help. For more information, see [`/vmm`, `/vms`, `/vmv` (General purpose representation)](../../build/reference/vmm-vms-vmv-general-purpose-representation.md). You can also try rearranging your base classes; the compiler is detecting a loss of information in the conversion because a base class is at a non-zero offset from the derived. +C4407 can occur if you cast between a multiple inheritance pointer-to-member to a single inheritance pointer-to-member. Sometimes this can work, but sometimes it can't because the single inheritance pointer-to-member representation doesn't hold sufficient information. Compiling with the **`/vmm`** might help. For more information, see [`/vmm`, `/vms`, `/vmv` (General purpose representation)](../../build/reference/vmm-vms-vmv-general-purpose-representation.md). You can also try rearranging your base classes; the compiler is detecting a loss of information in the conversion because a base class is at a non-zero offset from the derived. ## Example -The following sample generates C4407 and shows how to fix it: +The following example generates C4407 and shows how to fix it: ```cpp // C4407.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4409.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4409.md index 66f2c9b2a9e..6f4a121e0bc 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4409.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4409.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4409" title: "Compiler Warning (level 1) C4409" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4409" +ms.date: 11/04/2016 f1_keywords: ["C4409"] helpviewer_keywords: ["C4409"] -ms.assetid: 2be63c86-d9c9-4073-ab71-e654dd9f450f --- # Compiler Warning (level 1) C4409 -illegal instruction size +> illegal instruction size + +## Remarks The instruction did not have a form with the specified size. The smallest legal size was used. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4410.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4410.md index 99784780d9a..391e7ca2304 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4410.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4410.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4410" title: "Compiler Warning (level 1) C4410" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4410" +ms.date: 11/04/2016 f1_keywords: ["C4410"] helpviewer_keywords: ["C4410"] -ms.assetid: 7dcdb720-118a-4823-ba73-575f6ad79a71 --- # Compiler Warning (level 1) C4410 -illegal size for operand +> illegal size for operand + +## Remarks One of the operands on the instruction had an incorrect size. The smallest legal size for the operand was used. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4411.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4411.md index 3170200a5f5..04ee68c961b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4411.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4411.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4411" title: "Compiler Warning (level 1) C4411" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4411" +ms.date: 11/04/2016 f1_keywords: ["C4411"] helpviewer_keywords: ["C4411"] -ms.assetid: d209452c-83bd-4333-8d0b-759ca9b4864e --- # Compiler Warning (level 1) C4411 -'identifier' : symbol resolves to displacement register +> 'identifier' : symbol resolves to displacement register + +## Remarks The identifier is a local symbol that resolves to a displacement register and therefore may be used on an operand with another symbol. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4420.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4420.md index e506c3e258f..912f91fef5e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4420.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4420.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4420" title: "Compiler Warning (level 1) C4420" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4420" +ms.date: 11/04/2016 f1_keywords: ["C4420"] helpviewer_keywords: ["C4420"] -ms.assetid: 44a37754-7ddd-4764-a5f7-d33e05c20091 --- # Compiler Warning (level 1) C4420 -'operator' : operator not available, using 'operator' instead; run-time checking may be compromised +> 'operator' : operator not available, using 'operator' instead; run-time checking may be compromised + +## Remarks This warning is generated when you use the [/RTCv](../../build/reference/rtc-run-time-error-checks.md) (vector new/delete checking) and when no vector form is found. In this case, the non-vector form is used. 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 2e6e126eadc..e2565cf0115 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,33 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4436" -title: "Compiler Warning (level 1) C4436" -ms.date: "11/04/2016" +title: "Compiler warning (level 1 and level 4) C4436" +description: "Learn more about: 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. +## Remarks -- The cast is from a base class pointer to a derived class pointer. +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 example 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 +46,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 +66,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-c4440.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4440.md index a85bcc3b98c..27027d44236 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4440.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4440.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4440" title: "Compiler Warning (level 1) C4440" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4440" +ms.date: 11/04/2016 f1_keywords: ["C4440"] helpviewer_keywords: ["C4440"] -ms.assetid: 78b9642a-a93e-401e-9d92-372f6451bc5d --- # Compiler Warning (level 1) C4440 -calling convention redefinition from 'calling_convention1' to 'calling_convention2' ignored +> calling convention redefinition from 'calling_convention1' to 'calling_convention2' ignored + +## Remarks An attempt to change the calling convention was ignored. -The following sample generates C4440: +## Example + +The following example generates C4440: ```cpp // C4440.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4441.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4441.md index be07663a0d2..d4c727635c3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4441.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4441.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4441" title: "Compiler Warning (level 1) C4441" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4441" +ms.date: 11/04/2016 f1_keywords: ["C4441"] helpviewer_keywords: ["C4441"] -ms.assetid: 7fc540a5-e41f-47cf-aa37-b2b699c2685e --- # Compiler Warning (level 1) C4441 -calling convention of 'cc1' ignored; 'cc2' used instead +> calling convention of 'cc1' ignored; 'cc2' used instead + +## Remarks Member functions in managed user-defined types and global function generics must use the [__clrcall](../../cpp/clrcall.md) calling convention. The compiler used `__clrcall`. ## Example -The following sample generates C4441. +The following example generates C4441. ```cpp // C4441.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4445.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4445.md index 4312f592b2f..d50740c4fd0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4445.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4445.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4445" title: "Compiler Warning (level 1) C4445" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4445" +ms.date: 11/04/2016 f1_keywords: ["C4445"] helpviewer_keywords: ["C4445"] -ms.assetid: 535e92a0-ba08-4dfc-89b2-af2dcdd7caeb --- # Compiler Warning (level 1) C4445 -'function' : in a WinRT or managed type a virtual method cannot be private +> 'function' : in a WinRT or managed type a virtual method cannot be private + +## Remarks If a virtual function is private, it cannot be accessed by a derived type. To fix this error, change the accessibility of the virtual member function to protected or public. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4461.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4461.md index ec88b65c40d..62fa36aa89a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4461.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4461.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4461" title: "Compiler Warning (level 1) C4461" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4461" +ms.date: 11/04/2016 f1_keywords: ["C4461"] helpviewer_keywords: ["C4461"] -ms.assetid: 104ffecc-3dd4-4cb1-89a8-81154fbe46d9 --- # Compiler Warning (level 1) C4461 -'type' : this class has a finalizer 'finalizer' but no destructor 'dtor' +> 'type' : this class has a finalizer 'finalizer' but no destructor 'dtor' + +## Remarks The presence of a finalizer in a type implies resources to delete. Unless a finalizer is explicitly called from the type's destructor, the common language runtime determines when to run the finalizer, after your object goes out of scope. @@ -18,7 +19,7 @@ For more information, see [Destructors and finalizers](../../dotnet/how-to-defin ## Example -The following sample generates C4461. +The following example generates C4461. ```cpp // C4461.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4462.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4462.md index 63d4762be21..ce4fe63e11b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4462.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4462.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4462" title: "Compiler Warning (level 1) C4462" -ms.date: "10/25/2017" +description: "Learn more about: Compiler Warning (level 1) C4462" +ms.date: 10/25/2017 f1_keywords: ["C4462"] helpviewer_keywords: ["C4462"] -ms.assetid: 4e20aca4-293e-4c75-a83d-961c27ab7840 --- # Compiler Warning (level 1) C4462 > cannot determine the GUID of the type. Program may fail at runtime. +## Remarks + Warning C4462 occurs in a Windows Runtime app or component when a public `TypedEventHandler` has as one of its type parameters a reference to the enclosing class. 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 C4462 into a level 4 warning issue, add this line to your source code file: @@ -20,7 +21,7 @@ This warning is automatically promoted to an error. If you wish to modify this b ## Example -This sample generates warning C4462: +This example generates warning C4462: ```cpp namespace N diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4470.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4470.md index 74f847fd992..8cc35e1f593 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4470.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4470.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4470" title: "Compiler Warning (level 1) C4470" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4470" +ms.date: 11/04/2016 f1_keywords: ["C4470"] helpviewer_keywords: ["C4470"] -ms.assetid: f52a3eaa-a235-4747-a47d-9ec4ad4cb0ea --- # Compiler Warning (level 1) C4470 -floating-point control pragmas ignored under /clr +> floating-point control pragmas ignored under /clr + +## Remarks The float-control pragmas: @@ -20,7 +21,9 @@ The float-control pragmas: have no effect under [/clr](../../build/reference/clr-common-language-runtime-compilation.md). -The following sample generates C4470: +## Example + +The following example generates C4470: ```cpp // C4470.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4486.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4486.md index 319dbc7c1d9..0d0fc68d539 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4486.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4486.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4486" title: "Compiler Warning (level 1) C4486" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4486" +ms.date: 11/04/2016 f1_keywords: ["C4486"] helpviewer_keywords: ["C4486"] -ms.assetid: 2c0c59e3-d025-4d97-8da2-fa27df1402fc --- # Compiler Warning (level 1) C4486 -'function' : a private virtual method of a ref class or value class should be marked 'sealed' +> 'function' : a private virtual method of a ref class or value class should be marked 'sealed' + +## Remarks Since a private virtual member function of a managed class or struct cannot be accessed or overridden, it should be marked [sealed](../../extensions/sealed-cpp-component-extensions.md). -## Examples +## Example -The following sample generates C4486. +The following example generates C4486. ```cpp // C4486.cpp @@ -26,7 +27,7 @@ private: }; ``` -The following sample shows one possible use of a private sealed, virtual function. +The following example shows one possible use of a private sealed, virtual function. ```cpp // C4486_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4488.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4488.md index 9faef2a3235..972d534a5a2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4488.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4488.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4488" title: "Compiler Warning (level 1) C4488" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4488" +ms.date: 11/04/2016 f1_keywords: ["C4488"] helpviewer_keywords: ["C4488"] -ms.assetid: 55625e46-ddb5-4c7c-99c7-cd4aa9f879bd --- # Compiler Warning (level 1) C4488 -'function' : requires 'keyword' keyword to implement the interface method 'interface_method' +> 'function' : requires 'keyword' keyword to implement the interface method 'interface_method' + +## Remarks A class must implement all members of an interface from which it directly inherits. An implemented member must have public accessibility, and must be marked virtual. ## Examples -C4488 can occur if an implemented member is not public. The following sample generates C4488. +C4488 can occur if an implemented member is not public. The following example generates C4488. ```cpp // C4488.cpp @@ -33,7 +34,7 @@ public: }; ``` -C4488 can occur if an implemented member is not marked virtual. The following sample generates C4488. +C4488 can occur if an implemented member is not marked virtual. The following example generates C4488. ```cpp // C4488_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4489.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4489.md index e0882054020..a5709ed8687 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4489.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4489.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4489" title: "Compiler Warning (level 1) C4489" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4489" +ms.date: 11/04/2016 f1_keywords: ["C4489"] helpviewer_keywords: ["C4489"] -ms.assetid: 43b51c8c-27b5-44c9-b974-fe4b48f4896f --- # Compiler Warning (level 1) C4489 -'specifier' : not allowed on interface method 'method'; override specifiers are only allowed on ref class and value class methods +> 'specifier' : not allowed on interface method 'method'; override specifiers are only allowed on ref class and value class methods + +## Remarks A specifier keyword was incorrectly used on an interface method. @@ -16,7 +17,7 @@ For more information, see [Override Specifiers](../../extensions/override-specif ## Example -The following sample generates C4489. +The following example generates C4489. ```cpp // C4489.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4490.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4490.md index 533ee9f3bb5..cf731a936b9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4490.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4490.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4490" title: "Compiler Warning (level 1) C4490" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4490" +ms.date: 11/04/2016 f1_keywords: ["C4490"] helpviewer_keywords: ["C4490"] -ms.assetid: f9b03ecf-41a1-4f4d-a74c-2c1e88234ccc --- # Compiler Warning (level 1) C4490 -'override' : incorrect use of override specifier; 'function' does not match a base ref class method +> 'override' : incorrect use of override specifier; 'function' does not match a base ref class method + +## Remarks An override specifier was used incorrectly. For example, you do not override an interface function, you implement it. @@ -16,7 +17,7 @@ For more information, see [Override Specifiers](../../extensions/override-specif ## Example -The following sample generates C4490. +The following example generates C4490. ```cpp // C4490.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4502.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4502.md index 7ed4e44ea8e..febc9be3e3b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4502.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4502.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4502" title: "Compiler Warning (level 1) C4502" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4502" +ms.date: 11/04/2016 f1_keywords: ["C4502"] helpviewer_keywords: ["C4502"] -ms.assetid: d8d43153-a40c-4b96-bc11-64028a144d70 --- # Compiler Warning (level 1) C4502 -'linkage specification' requires use of keyword 'extern' and must precede all other specifiers +> 'linkage specification' requires use of keyword 'extern' and must precede all other specifiers + +## Remarks A linkage was specified without the **`extern`** keyword. Linkage is not relevant to non-extern types. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4503.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4503.md index 866586d4ea8..bd1f2733869 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4503.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4503.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4503" title: "Compiler Warning (level 1) C4503" -ms.date: "05/14/2018" +description: "Learn more about: Compiler Warning (level 1) C4503" +ms.date: 05/14/2018 f1_keywords: ["C4503"] helpviewer_keywords: ["C4503"] -ms.assetid: 7c5a98ae-5b6d-41d8-b881-12d3ffd5e392 --- # Compiler Warning (level 1) C4503 @@ -22,7 +21,7 @@ You might, however, decide to not restructure your code. It is possible to ship ## Example -The following sample generates C4503 in compilers before Visual Studio 2017: +The following example generates C4503 in compilers before Visual Studio 2017: ```cpp // C4503.cpp @@ -40,7 +39,7 @@ typedef std::map Hello; Hello MyWAT; ``` -This sample shows one way to rewrite your code to resolve C4503: +This example shows one way to rewrite your code to resolve C4503: ```cpp // C4503b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4506.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4506.md index 85662502e78..d2960d7acf3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4506.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4506.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4506" title: "Compiler Warning (level 1) C4506" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4506" +ms.date: 11/04/2016 f1_keywords: ["C4506"] helpviewer_keywords: ["C4506"] -ms.assetid: aa682869-65d1-4dad-ba32-198f10b44f91 --- # Compiler Warning (level 1) C4506 -no definition for inline function 'function' +> no definition for inline function 'function' + +## Remarks The given function was declared and marked for inlining but was not defined. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4508.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4508.md index f4ce654e68a..34c87bb27a2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4508.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4508.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4508" title: "Compiler Warning (level 1) C4508" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4508" +ms.date: 11/04/2016 f1_keywords: ["C4508"] helpviewer_keywords: ["C4508"] -ms.assetid: c05f113b-b789-4df0-a4ef-78bce4767021 --- # Compiler Warning (level 1) C4508 -'function' : function should return a value; 'void' return type assumed +> 'function' : function should return a value; 'void' return type assumed + +## Remarks The function has no return type specified. In this case, C4430 should also fire and the compiler implements the fix reported by C4430 (default value is int). To resolve this warning, explicitly declare the return type of functions. -The following sample generates C4508: +## Example + +The following example generates C4508: ```cpp // C4508.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4518.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4518.md index 717e2457340..d63e8b14aaf 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4518.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4518.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4518" title: "Compiler Warning (level 1) C4518" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4518" +ms.date: 11/04/2016 f1_keywords: ["C4518"] helpviewer_keywords: ["C4518"] -ms.assetid: 4ad21004-f076-43fd-99f4-4bf1f9be4c0b --- # Compiler Warning (level 1) C4518 -'specifier' : storage-class or type specifier(s) unexpected here; ignored +> 'specifier' : storage-class or type specifier(s) unexpected here; ignored + +## Example -The following sample generates C4518: +The following example generates C4518: ```cpp // C4518.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4526.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4526.md index f3b0427593c..ea7f5d89922 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4526.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4526.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4526" title: "Compiler Warning (level 1) C4526" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4526" +ms.date: 11/04/2016 f1_keywords: ["C4526"] helpviewer_keywords: ["C4526"] -ms.assetid: 490f8916-5fdc-4cad-b412-76c3382a5976 --- # Compiler Warning (level 1) C4526 -'function' : static member function cannot override virtual function 'virtual function'override ignored, virtual function will be hidden +> 'function' : static member function cannot override virtual function 'virtual function'override ignored, virtual function will be hidden + +## Remarks The static member function meets the criteria to override the virtual function, which makes the member function both virtual and static. +## Example + The following code generates C4526: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4530.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4530.md index 0575689ff83..a1b5e544b17 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4530.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4530.md @@ -1,19 +1,18 @@ --- title: "Compiler Warning (level 1) C4530" description: "Reference guide to Microsoft C++ compiler warning C4530." -ms.date: "04/02/2020" +ms.date: 04/02/2020 f1_keywords: ["C4530"] helpviewer_keywords: ["C4530"] -ms.assetid: a04dcdb2-84db-459d-9e5e-4e743887465f --- # Compiler Warning (level 1) C4530 > C++ exception handler used, but unwind semantics are not enabled. Specify /EHsc -The code uses C++ exception handling, but [/EHsc](../../build/reference/eh-exception-handling-model.md) wasn't included in the compiler options. - ## Remarks +The code uses C++ exception handling, but [/EHsc](../../build/reference/eh-exception-handling-model.md) wasn't included in the compiler options. + The compiler requires the **`/EHsc`** option to build C++ code that follows the C++ standard for exception handling. Standard C++ *unwind semantics* specifies that objects and stack frames constructed between where an exception is thrown and where it's caught must be destroyed and their resources recovered. This process is known as *unwinding the stack*. The **`/EHsc`** option tells the compiler to generate code that calls the destructors on automatic storage objects when an exception passes through the containing stack frame. *Automatic storage* objects are objects allocated on the stack, such as local variables. It's called automatic storage because it's allocated automatically when functions are called, and released automatically when they return. A *stack frame* is the data placed on the stack when a function is called, along with its automatic storage. @@ -26,7 +25,7 @@ If no exceptions can possibly be thrown in your executable, you may safely ignor ## Example -The following sample generates C4530: +The following example generates C4530: ```cpp // C4530.cpp @@ -36,4 +35,4 @@ int main() { } ``` -Compile the sample with **`/EHsc`** to resolve the warning. +Compile the example with **`/EHsc`** to resolve the warning. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md index 2303da79ab7..ec19e1c3051 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4532.md @@ -1,30 +1,35 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4532" title: "Compiler Warning (level 1) C4532" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4532" +ms.date: 08/30/2022 f1_keywords: ["C4532"] helpviewer_keywords: ["C4532"] -ms.assetid: 4e2a286a-d233-4106-9f65-29be1a94ca02 --- # Compiler Warning (level 1) C4532 -'continue' : jump out of __finally/finally block has undefined behavior during termination handling +> 'continue' : jump out of __finally/finally block has undefined behavior during termination handling + +## Remarks The compiler encountered one of the following keywords: -- [continue](../../cpp/continue-statement-cpp.md) +- [`continue`](../../cpp/continue-statement-cpp.md) -- [break](../../cpp/break-statement-cpp.md) +- [`break`](../../cpp/break-statement-cpp.md) -- [goto](../../cpp/goto-statement-cpp.md) +- [`goto`](../../cpp/goto-statement-cpp.md) -causing a jump out of a [__finally](../../cpp/try-finally-statement.md) or [finally](../../dotnet/finally.md) block during abnormal termination. +causing a jump out of a [`__finally`](../../cpp/try-finally-statement.md) or [`finally`](../../dotnet/finally.md) block during abnormal termination. If an exception occurs, and while the stack is being unwound during execution of the termination handlers (the **`__finally`** or finally blocks), and your code jumps out of a **`__finally`** block before the **`__finally`** block ends, the behavior is undefined. Control may not return to the unwinding code, so the exception may not be handled properly. If you must jump out of a **`__finally`** block, check for abnormal termination first. -The following sample generates C4532; simply comment out the jump statements to resolve the warnings. +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. + +## Example + +The following example generates C4532; delete or comment out the jump statements to resolve the warnings. ```cpp // C4532.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md index af1f372eaf3..9a446f09372 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4533.md @@ -1,16 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4533" title: "Compiler Warning (level 1) C4533" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4533" +ms.date: 08/30/2022 f1_keywords: ["C4533"] helpviewer_keywords: ["C4533"] -ms.assetid: 359fecda-d540-46e5-b214-dbabe9ef50d2 --- # Compiler Warning (level 1) C4533 -initialization of 'variable' is skipped by 'instruction' +> initialization of '*variable*' is skipped by '*instruction*' + +## Remarks + +An instruction in your program changed the flow of control, so an instruction that initialized a variable wasn't executed. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. + +## Example -An instruction in your program changed the flow of control, such that, an instruction that initialized a variable was not executed. The following sample generates C4533: +The following example generates C4533. To resolve the issue, move the initialization before the jump instruction or after the target of the jump. ```cpp // C4533.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4537.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4537.md index 36bf23c975a..9c20b0c8ca1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4537.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4537.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4537" title: "Compiler Warning (level 1) C4537" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4537" +ms.date: 08/27/2018 f1_keywords: ["C4537"] helpviewer_keywords: ["C4537"] -ms.assetid: 9454493c-d419-475e-8f35-9c00233c9329 --- # Compiler Warning (level 1) C4537 @@ -16,7 +15,7 @@ A reference was passed where an object (user-defined type) was expected. A refer ## Example -The following sample generates C4537 and shows how to fix it: +The following example generates C4537 and shows how to fix it: ```cpp // C4537.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4540.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4540.md index cdbd4967530..d14b6b6e38a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4540.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4540.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4540" title: "Compiler Warning (level 1) C4540" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4540" +ms.date: 11/04/2016 f1_keywords: ["C4540"] helpviewer_keywords: ["C4540"] -ms.assetid: 8085e748-5f4d-43c2-b06d-eaf794edbf72 --- # Compiler Warning (level 1) C4540 -dynamic_cast used to convert to inaccessible or ambiguous base; run-time test will fail ('type1' to 'type2') +> dynamic_cast used to convert to inaccessible or ambiguous base; run-time test will fail ('type1' to 'type2') + +## Remarks You used **`dynamic_cast`** to convert from one type to another. The compiler determined that the cast would always fail (return **NULL**) because a base class is inaccessible (**`private`**, for instance) or ambiguous (appears more than once in the class hierarchy, for instance). +## Example + The following shows an example of this warning. Class **B** is derived from class **A**. The program uses **`dynamic_cast`** to cast from class **B** (the derived class) to class **A**, which will always fail because class **B** is **`private`** and thus inaccessible. Changing the access of **A** to **`public`** will resolve the warning. ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4541.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4541.md index ed2547e029a..5b5982d38a6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4541.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4541.md @@ -1,13 +1,43 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4541" title: "Compiler Warning (level 1) C4541" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4541" +ms.date: 08/24/2025 f1_keywords: ["C4541"] helpviewer_keywords: ["C4541"] -ms.assetid: b57b8f3e-117d-4fc2-bba6-faec17e5fa9d --- # Compiler Warning (level 1) C4541 -'identifier' used on polymorphic type 'type' with /GR-; unpredictable behavior may result +> '*operator*' used on polymorphic type '*type*' with /GR-; unpredictable behavior may result + +## Remarks + +You tried to use the [`dynamic_cast` operator](../../cpp/dynamic-cast-operator.md) or [`typeid` operator](../../cpp/typeid-operator.md), which requires [Run-Time Type Information](../../cpp/run-time-type-information.md) (RTTI), without enabling it. To enable RTTI, recompile with [`/GR`](../../build/reference/gr-enable-run-time-type-information.md). + +## Example + +The following example generates C4541: + +```cpp +// C4541.cpp +// compile with: /W1 /GR- + +#include + +struct Base +{ + virtual ~Base() {} +}; + +struct Derived : Base {}; + +int main() +{ + Derived derived; + Base* pointer_to_base = &derived; + + dynamic_cast(pointer_to_base); // C4541 -You tried to use a feature that requires run-time type information without enabling run-time type information. Recompile with [/GR](../../build/reference/gr-enable-run-time-type-information.md). + typeid(*pointer_to_base); // C4541 + typeid(pointer_to_base); // OK +} +``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4544.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4544.md index 8d72e0375aa..d8c3396c024 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4544.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4544.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4544" title: "Compiler Warning (level 1) C4544" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4544" +ms.date: 11/04/2016 f1_keywords: ["C4544"] helpviewer_keywords: ["C4544"] -ms.assetid: 11ee04df-41ae-435f-af44-881e801315a8 --- # Compiler Warning (level 1) C4544 -'declaration': Default template argument ignored on this template declaration +> 'declaration': Default template argument ignored on this template declaration + +## Remarks A default template argument was specified in an incorrect location and was ignored. A default template argument for a class template can only be specified in the declaration or definition of the class template and not on a member of the class template. -This sample generates C4545, and the next sample shows how to fix it: +## Example + +This example generates C4544, and the next example shows how to fix it: ```cpp // C4544.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4545.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4545.md index 747aeba94f2..6add8aa635e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4545.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4545.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4545" title: "Compiler Warning (level 1) C4545" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4545" +ms.date: 11/04/2016 f1_keywords: ["C4545"] helpviewer_keywords: ["C4545"] -ms.assetid: 43f8f34f-ed46-4661-95c0-c588c577ff73 --- # Compiler Warning (level 1) C4545 -expression before comma evaluates to a function which is missing an argument list +> expression before comma evaluates to a function which is missing an argument list + +## Remarks The compiler detected an ill-formed comma expression. 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 C4545: +## Example + +The following example generates C4545: ```cpp // C4545.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4546.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4546.md index e79fac645f6..bb9d1835428 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4546.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4546.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4546" title: "Compiler Warning (level 1) C4546" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4546" +ms.date: 11/04/2016 f1_keywords: ["C4546"] helpviewer_keywords: ["C4546"] -ms.assetid: 071e1709-3841-46c1-8e71-96109cd22041 --- # Compiler Warning (level 1) C4546 -function call before comma missing argument list +> function call before comma missing argument list + +## Remarks The compiler detected an ill-formed comma expression. @@ -16,7 +17,7 @@ This warning is off by default. For more information, see [Compiler Warnings Tha ## Example -The following sample generates C4546: +The following example generates C4546: ```cpp // C4546.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4547.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4547.md index 8f29a08438b..fcf23c66dda 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4547.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4547.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4547" title: "Compiler Warning (level 1) C4547" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4547" +ms.date: 11/04/2016 f1_keywords: ["C4547"] helpviewer_keywords: ["C4547"] -ms.assetid: 3edf1c2e-c0d5-444d-ae83-44a7cce24bb2 --- # Compiler Warning (level 1) C4547 -'operator' : operator before comma has no effect; expected operator with side-effect +> 'operator' : operator before comma has no effect; expected operator with side-effect + +## Remarks The compiler detected an ill-formed comma expression. 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 C4547: +## Example + +The following example generates C4547: ```cpp // C4547.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4548.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4548.md index c5ca0459485..62d604feaa4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4548.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4548.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4548" title: "Compiler Warning (level 1) C4548" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4548" +ms.date: 11/04/2016 f1_keywords: ["C4548"] helpviewer_keywords: ["C4548"] -ms.assetid: 2cee817e-e463-4d90-bbd2-de120d48c101 --- # Compiler Warning (level 1) C4548 -expression before comma has no effect; expected expression with side-effect +> expression before comma has no effect; expected expression with side-effect + +## Remarks The compiler detected an ill-formed comma expression. 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 C4548: +## Example + +The following example generates C4548: ```cpp // C4548.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4549.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4549.md index fd330c52a08..fb6610064fa 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4549.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4549.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4549" title: "Compiler Warning (level 1) C4549" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4549" +ms.date: 11/04/2016 f1_keywords: ["C4549"] helpviewer_keywords: ["C4549"] -ms.assetid: 81a07676-625b-4f58-9b0c-3ee22830b04a --- # Compiler Warning (level 1) C4549 -'operator' : operator before comma has no effect; did you intend 'operator'? +> 'operator' : operator before comma has no effect; did you intend 'operator'? + +## Remarks The compiler detected an ill-formed comma expression. 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 C4549: +## Example + +The following example generates C4549: ```cpp // C4549.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4550.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4550.md index 11dd28ec1b2..f9c004fec9c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4550.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4550.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4550" title: "Compiler Warning (level 1) C4550" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4550" +ms.date: 11/04/2016 f1_keywords: ["C4550"] helpviewer_keywords: ["C4550"] -ms.assetid: f902b4ed-5f17-48ea-b693-92f4fb8c8054 --- # Compiler Warning (level 1) C4550 -expression evaluates to a function which is missing an argument list +> expression evaluates to a function which is missing an argument list + +## Remarks A dereferenced pointer to a function is missing an argument list. ## Example +The following example generates C4550: + ```cpp // C4550.cpp // compile with: /W1 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4551.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4551.md index 2ac75c88a32..a7e1b9fe013 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4551.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4551.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4551" title: "Compiler Warning (level 1) C4551" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4551" +ms.date: 11/04/2016 f1_keywords: ["C4551"] helpviewer_keywords: ["C4551"] -ms.assetid: 458b59bd-e2d7-425f-9ba6-268ff200424f --- # Compiler Warning (level 1) C4551 -function call missing argument list +> function call missing argument list + +## Remarks A function call must include the open and close parentheses after the function name even if the function takes no parameters. -The following sample generates C4551: +## Example + +The following example generates C4551: ```cpp // C4551.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4552.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4552.md index a48817856db..6cea7cc2d46 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4552.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4552.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4552" title: "Compiler Warning (level 1) C4552" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4552" +ms.date: 11/04/2016 f1_keywords: ["C4552"] helpviewer_keywords: ["C4552"] -ms.assetid: ebbbb5ee-1c19-45bd-b386-41a19630fc76 --- # Compiler Warning (level 1) C4552 -'operator' : operator has no effect; expected operator with side-effect +> 'operator' : operator has no effect; expected operator with side-effect + +## Remarks If an expression statement has an operator with no side effect as the top of the expression, it's probably a mistake. To override this warning, put the expression in parentheses. -The following sample generates C4552: +## Example + +The following example generates C4552: ```cpp // C4552.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4553.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4553.md index d8ded153113..c8c357eb293 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4553.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4553.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4553" title: "Compiler Warning (level 1) C4553" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4553" +ms.date: 11/04/2016 f1_keywords: ["C4553"] helpviewer_keywords: ["C4553"] -ms.assetid: d8aacbe0-3cb5-4367-a6e5-fd7e28f0ff9d --- # Compiler Warning (level 1) C4553 -'operator' : operator has no effect; did you intend 'operator'? +> 'operator' : operator has no effect; did you intend 'operator'? + +## Remarks If an expression statement has an operator with no side effect as the top of the expression, it's probably a mistake. -The following sample generates C4553: +## Example + +The following example generates C4553: ```cpp // C4553.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4555.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4555.md index f00425ae350..f98f2f75afb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4555.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4555.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4555" title: "Compiler Warning (level 1) C4555" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4555" +ms.date: 11/04/2016 f1_keywords: ["C4555"] helpviewer_keywords: ["C4555"] -ms.assetid: 50b286c1-f7bf-4292-b1fa-baaac9538611 --- # Compiler Warning (level 1) C4555 -expression has no effect; expected expression with side-effect +> expression has no effect; expected expression with side-effect + +## Remarks This warning informs you when an expression has no effect. 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. +## Example + For example: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4556.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4556.md index 371adf13d23..361ee46a496 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-c4558.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4558.md index 33ca5b15716..730b37887ab 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4558.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4558.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4558" title: "Compiler Warning (level 1) C4558" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4558" +ms.date: 11/04/2016 f1_keywords: ["C4558"] helpviewer_keywords: ["C4558"] -ms.assetid: 52bb0324-7bec-468c-b35b-13a08d38e578 --- # Compiler Warning (level 1) C4558 -value of operand 'value' is out of range 'lowerbound - upperbound' +> value of operand 'value' is out of range 'lowerbound - upperbound' + +## Remarks The value passed to an assembly language instruction is out of the range specified for the parameter. The value will be truncated. -The following sample generates C4558: +## Example + +The following example generates C4558: ```cpp // C4558.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4561.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4561.md index 5b0d3ae7272..9c92d5ffb96 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4561.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4561.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4561" title: "Compiler Warning (level 1) C4561" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4561" +ms.date: 11/04/2016 f1_keywords: ["C4561"] helpviewer_keywords: ["C4561"] -ms.assetid: 3a10c12c-601b-4b6c-9861-331fd022e021 --- # Compiler Warning (level 1) C4561 -'__fastcall' incompatible with the '/clr' option: converting to '\__stdcall' +> '__fastcall' incompatible with the '/clr' option: converting to '\__stdcall' + +## Remarks The [__fastcall](../../cpp/fastcall.md) function-calling convention cannot be used with the [/clr](../../build/reference/clr-common-language-runtime-compilation.md) compiler option. The compiler ignores the calls to **`__fastcall`**. To fix this warning, either remove the calls to **`__fastcall`** or compile without **/clr**. -The following sample generates C4561: +## Example + +The following example generates C4561: ```cpp // C4561.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4566.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4566.md index 425026f9603..b20a4c38cdb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4566.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4566.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4566" title: "Compiler Warning (level 1) C4566" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4566" +ms.date: 11/04/2016 f1_keywords: ["C4566"] helpviewer_keywords: ["C4566"] -ms.assetid: 65f40730-e86f-447c-b37b-16caadcfe311 --- # Compiler Warning (level 1) C4566 -character represented by universal-character-name 'char' cannot be represented in the current code page (page) +> character represented by universal-character-name 'char' cannot be represented in the current code page (page) + +## Remarks Not every Unicode character can be represented in your current ANSI code page. Narrow strings (one-byte characters) are converted to multi-byte characters whereas wide strings (two-byte characters) are not. -The following sample generates C4566: +## Example + +The following example generates C4566: ```cpp // C4566.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4572.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4572.md index 2ecaa73a316..6e42a081081 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4572.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4572.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4572" title: "Compiler Warning (level 1) C4572" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4572" +ms.date: 11/04/2016 f1_keywords: ["C4572"] helpviewer_keywords: ["C4572"] -ms.assetid: 482dee5a-29bd-4fc3-b769-9dfd4cd2a964 --- # Compiler Warning (level 1) C4572 -[ParamArray] attribute is deprecated under /clr, use '...' instead +> [ParamArray] attribute is deprecated under /clr, use '...' instead + +## Remarks An obsolete style for specifying a variable argument list was used. When compiling for the CLR, use ellipsis syntax instead of . For more information, see [Variable Argument Lists (...) (C++/CLI)](../../extensions/variable-argument-lists-dot-dot-dot-cpp-cli.md). ## Example -The following sample generates C4572. +The following example generates C4572. ```cpp // C4572.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4577.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4577.md index f6b51626645..9ba3d67ccb1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4577.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4577.md @@ -1,7 +1,7 @@ --- title: "Compiler Warning C4577" -description: Compiler warning C4577 description and solution. -ms.date: "09/18/2019" +description: "Compiler warning C4577 description and solution." +ms.date: 09/18/2019 f1_keywords: ["C4577"] helpviewer_keywords: ["C4577"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["C4577"] > 'noexcept' used with no exception handling mode specified; termination on exception is not guaranteed. Specify /EHsc +## Remarks + The compiler detected a **`noexcept`** specification, but standard C++ exception handling wasn't specified. The compiler doesn't fully support exception handling according to the C++ standard unless the [/EHsc](../../build/reference/eh-exception-handling-model.md) compiler option is specified. To resolve this issue, set the **/EHsc** compiler option. This warning is new in Visual Studio 2015, and 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-c4581.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4581.md index acdece26660..f68c67ae615 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4581.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4581.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4581" title: "Compiler Warning (level 1) C4581" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4581" +ms.date: 11/04/2016 f1_keywords: ["C4581"] helpviewer_keywords: ["C4581"] -ms.assetid: 598bcd87-257d-4eb3-94e4-15bb31aadc99 --- # Compiler Warning (level 1) C4581 -deprecated behavior: '"string1"' replaced with 'string2' to process attribute +> deprecated behavior: '"string1"' replaced with 'string2' to process attribute + +## Remarks This error can be generated as a result of compiler conformance work that was done for Visual Studio 2005: parameter checking for Visual C++ attributes. @@ -16,7 +17,7 @@ In previous versions, attribute values were accepted whether or not they were en ## Example -The following sample generates C4581. +The following example generates C4581. ```cpp // C4581.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4584.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4584.md index 4db3442c590..92ff0980142 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4584.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4584.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4584" title: "Compiler Warning (level 1) C4584" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4584" +ms.date: 11/04/2016 f1_keywords: ["C4584"] helpviewer_keywords: ["C4584"] -ms.assetid: ad86582f-cb8c-4d21-8c4c-a6c800059e25 --- # Compiler Warning (level 1) C4584 -'class1' : base-class 'class2' is already a base-class of 'class3' +> 'class1' : base-class 'class2' is already a base-class of 'class3' + +## Remarks + +The class you defined inherits from two classes, one of which inherits from the other. + +## Example -The class you defined inherits from two classes, one of which inherits from the other. For example: +For example: ```cpp // C4584.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4600.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4600.md index 446ec164f35..187cda9ee3e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4600.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4600.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4600" title: "Compiler Warning (level 1) C4600" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4600" +ms.date: 11/04/2016 f1_keywords: ["C4600"] helpviewer_keywords: ["C4600"] -ms.assetid: f023a2a1-7fc4-463f-a434-dc93fcd3f4e9 --- # Compiler Warning (level 1) C4600 -\#pragma 'macro name' : expected a valid non-empty string +> #pragma 'macro name' : expected a valid non-empty string + +## Remarks You cannot specify an empty string when you push or pop a macro name with either the [pop_macro](../../preprocessor/pop-macro.md) or [push_macro](../../preprocessor/push-macro.md). -The following sample generates C4600: +## Example + +The following example generates C4600: ```cpp // C4600.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4602.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4602.md index a8a3b121f42..215e76f9799 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4602.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4602.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4602" title: "Compiler Warning (level 1) C4602" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4602" +ms.date: 11/04/2016 f1_keywords: ["C4602"] helpviewer_keywords: ["C4602"] -ms.assetid: c1f0300f-e2a2-4c9e-a7c3-4c7318d10509 --- # Compiler Warning (level 1) C4602 -\#pragma pop_macro : 'macro name' no previous #pragma push_macro for this identifier +> #pragma pop_macro : 'macro name' no previous #pragma push_macro for this identifier + +## Remarks + +If you use [pop_macro](../../preprocessor/pop-macro.md) for a particular macro, you must first have passed that macro name to [push_macro](../../preprocessor/push-macro.md). + +## Example -If you use [pop_macro](../../preprocessor/pop-macro.md) for a particular macro, you must first have passed that macro name to [push_macro](../../preprocessor/push-macro.md). For example, the following sample generates C4602: +For example, the following example generates C4602: ```cpp // C4602.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4603.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4603.md index a8b8f597828..56bb27c36d7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4603.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4603.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4603" title: "Compiler Warning (level 1) C4603" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4603" +ms.date: 11/04/2016 f1_keywords: ["C4603"] helpviewer_keywords: ["C4603"] -ms.assetid: f065994e-e3e5-4694-b868-c124472b3342 --- # Compiler Warning (level 1) C4603 -'\' : macro is not defined or definition is different after precompiled header use +> '\' : macro is not defined or definition is different after precompiled header use + +## Remarks The macro specified by the *identifier* placeholder is either different or no longer defined after the precompiler header is used. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4606.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4606.md index 1eeecf2f663..acfb5694aae 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4606.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4606.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4606" title: "Compiler Warning (level 1) C4606" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4606" +ms.date: 11/04/2016 f1_keywords: ["C4606"] helpviewer_keywords: ["C4606"] -ms.assetid: c1b45fb6-672b-42eb-9e1c-c67b3e4150d3 --- # Compiler Warning (level 1) C4606 -\#pragma warning : 'warning_number' ignored; Code Analysis warnings are not associated with warning levels +> #pragma warning : 'warning_number' ignored; Code Analysis warnings are not associated with warning levels + +## Remarks For Code Analysis warnings, only `error`, `once`, and `default` are supported with the [warning](../../preprocessor/warning.md) pragma. ## Example -The following sample generates C4606. +The following example generates C4606. ```cpp // C4606.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4612.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4612.md index 49a8294c0ff..461fe57021d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4612.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4612.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4612" title: "Compiler Warning (level 1) C4612" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4612" +ms.date: 08/27/2018 f1_keywords: ["C4612"] helpviewer_keywords: ["C4612"] -ms.assetid: 21ac02b2-51cd-4aff-9b70-d543511d5962 --- # Compiler Warning (level 1) C4612 @@ -18,6 +17,8 @@ The arguments to the **#pragma include_alias** statement can use the quote form ## Example +The following example generates C4612: + ```cpp // C4612.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4613.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4613.md index a1d1ba5b233..b38c95c4b13 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4613.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4613.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4613" title: "Compiler Warning (level 1) C4613" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4613" +ms.date: 11/04/2016 f1_keywords: ["C4613"] helpviewer_keywords: ["C4613"] -ms.assetid: 399f521b-651c-4997-bc91-f40198e9a4d4 --- # Compiler Warning (level 1) C4613 -'segment' : class of segment cannot be changed +> 'segment' : class of segment cannot be changed + +## Remarks You tried to create a segment with the same class name as a segment used by the compiler. No new segment class was created. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4615.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4615.md index 8f4b9c9c1c2..9fa4a67263d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4615.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4615.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4615" title: "Compiler Warning (level 1) C4615" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4615" +ms.date: 11/04/2016 f1_keywords: ["C4615"] helpviewer_keywords: ["C4615"] -ms.assetid: 7b107c01-0da2-4e01-8b40-93813e30b94c --- # Compiler Warning (level 1) C4615 -\#pragma warning : unknown user warning type +> #pragma warning : unknown user warning type + +## Remarks An invalid warning specifier was used with **pragma** [warning](../../preprocessor/warning.md). To resolve the error, use a valid warning specifier. -The following sample generates C4615: +## Example + +The following example generates C4615: ```cpp // C4615.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4616.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4616.md index b3228cd32c3..1fb7f99a29e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4616.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4616.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4616" title: "Compiler Warning (level 1) C4616" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4616" +ms.date: 11/04/2016 f1_keywords: ["C4616"] helpviewer_keywords: ["C4616"] -ms.assetid: 71e15265-c5bc-42ce-a6a9-4879892472b1 --- # Compiler Warning (level 1) C4616 -\#pragma warning : warning number 'number' not a valid compiler warning +> #pragma warning : warning number 'number' not a valid compiler warning + +## Remarks The warning number specified in the [warning](../../preprocessor/warning.md) pragma cannot be reassigned. The pragma was ignored. -The following sample generates C4616: +## Example + +The following example generates C4616: ```cpp // C4616.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4618.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4618.md index 577c7875f91..ef7b1fba645 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4618.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4618.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4618" title: "Compiler Warning (level 1) C4618" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4618" +ms.date: 11/04/2016 f1_keywords: ["C4618"] helpviewer_keywords: ["C4618"] -ms.assetid: 6ff10d0a-6d5b-4373-8196-1d57bb6b1611 --- # Compiler Warning (level 1) C4618 -pragma parameters included an empty string; pragma ignored +> pragma parameters included an empty string; pragma ignored + +## Remarks A null string was given as an argument to a **#pragma**. The pragma was processed without the argument. -The following sample generates C4618: +## Example + +The following example generates C4618: ```cpp // C4618.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4620.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4620.md index c70c10ef526..76b04214dec 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4620.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4620.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4620" title: "Compiler Warning (level 1) C4620" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4620" +ms.date: 11/04/2016 f1_keywords: ["C4620"] helpviewer_keywords: ["C4620"] -ms.assetid: fed29934-b797-47e8-bbea-c7e5f8dd6e93 --- # Compiler Warning (level 1) C4620 -no postfix form of 'operator ++' found for type 'type', using prefix form +> no postfix form of 'operator ++' found for type 'type', using prefix form + +## Remarks There is no postfix increment operator defined for the given type. The compiler used the overloaded prefix operator. +## Example + This warning can be avoided by defining a postfix `++` operator. Create a two-argument version of the `++` operator as shown here: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4621.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4621.md index 575f6c2d426..f32fce06aad 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4621.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4621.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4621" title: "Compiler Warning (level 1) C4621" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4621" +ms.date: 11/04/2016 f1_keywords: ["C4621"] helpviewer_keywords: ["C4621"] -ms.assetid: 40931bd9-cb89-497e-86f0-cec9f016c63c --- # Compiler Warning (level 1) C4621 -no postfix form of 'operator --' found for type 'type', using prefix form +> no postfix form of 'operator --' found for type 'type', using prefix form + +## Remarks There was no postfix decrement operator defined for the given type. The compiler used the overloaded prefix operator. +## Example + This warning can be avoided by defining a postfix `--` operator. Create a two-argument version of the `--` operator as shown below: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4624.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4624.md index 977cd630768..d3bb234530d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4624.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4624.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4624" title: "Compiler Warning (level 1) C4624" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4624" +ms.date: 11/04/2016 f1_keywords: ["C4624"] helpviewer_keywords: ["C4624"] -ms.assetid: 14f61769-d92e-482b-9515-debd87b30a66 --- # Compiler Warning (level 1) C4624 -'derived class' : destructor was implicitly defined as deleted because a base class destructor is inaccessible or deleted +> 'derived class' : destructor was implicitly defined as deleted because a base class destructor is inaccessible or deleted + +## Remarks A destructor was not accessible or deleted in a base class and was therefore not generated for a derived class. Any attempt to create an object of this type on the stack will cause a compiler error. -The following sample generates C4624 and shows how to fix it: +## Example + +The following example generates C4624 and shows how to fix it: ```cpp // C4624.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4627.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4627.md index d8e7bfaf5d0..6689bdba0b9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4627.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4627.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4627" title: "Compiler Warning (level 1) C4627" -ms.date: "09/09/2018" +description: "Learn more about: Compiler Warning (level 1) C4627" +ms.date: 09/09/2018 f1_keywords: ["C4627"] helpviewer_keywords: ["C4627"] -ms.assetid: 8840f3e6-b496-423a-8635-eb55d5f854a2 --- # Compiler Warning (level 1) C4627 > '*header_file*': skipped when looking for precompiled header use +## Remarks + If the current source file has the [/Yu \(Use precompiled header file)](../../build/reference/yu-use-precompiled-header-file.md) option set, then the compiler ignores everything in the file before the precompiled header is included. Warning **C4627** is generated in Visual Studio 2015 and earlier versions if *header_file* is included before the precompiled header file, and if the precompiled header does not also include *header_file*. ## Example -This sample demonstrates how the error can occur, and shows how to fix it: +This example demonstrates how the error can occur, and shows how to fix it: ```cpp // c4627.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4628.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4628.md index 98acc3132b9..e66578e986d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4628.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4628.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4628" title: "Compiler Warning (level 1) C4628" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4628" +ms.date: 11/04/2016 f1_keywords: ["C4628"] helpviewer_keywords: ["C4628"] -ms.assetid: 20fdc6f8-5f6a-40cc-aff8-c7ccf3d8ec26 --- # Compiler Warning (level 1) C4628 -digraphs not supported with -Ze. Character sequence 'digraph' not interpreted as alternate token for 'char' +> digraphs not supported with -Ze. Character sequence 'digraph' not interpreted as alternate token for 'char' + +## Remarks Digraphs are not supported under [/Ze](../../build/reference/za-ze-disable-language-extensions.md). This warning will be followed by an error. This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. -The following sample generates C4628: +## Example + +The following example generates C4628: ```cpp // C4628.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4630.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4630.md index 3f80c7b419e..43df3fea625 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4630.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4630.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4630" title: "Compiler Warning (level 1) C4630" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4630" +ms.date: 11/04/2016 f1_keywords: ["C4630"] helpviewer_keywords: ["C4630"] -ms.assetid: d8926376-7acc-4fc7-8438-6f0de3468870 --- # Compiler Warning (level 1) C4630 -'symbol' : 'extern' storage class specifier illegal on member definition +> 'symbol' : 'extern' storage class specifier illegal on member definition + +## Remarks + +A data member or member function is defined as **`extern`**. Members cannot be external, although entire objects can. The compiler ignores the **`extern`** keyword. + +## Example -A data member or member function is defined as **`extern`**. Members cannot be external, although entire objects can. The compiler ignores the **`extern`** keyword. The following sample generates C4630: +The following example generates C4630: ```cpp // C4630.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4631.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4631.md index 63815b39c47..894e783d2c9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4631.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4631.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4631" title: "Compiler Warning (level 1) C4631" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4631" +ms.date: 11/04/2016 f1_keywords: ["C4631"] helpviewer_keywords: ["C4631"] -ms.assetid: d8636ff6-29a7-4fec-b9a6-e201d121c3ca --- # Compiler Warning (level 1) C4631 -MSXML or XPath unavailable, XML document comments will not be processed. reason +> MSXML or XPath unavailable, XML document comments will not be processed. reason + +## Remarks Your common language runtime installation did not have the necessary files to support processing doc comment. Reinstall the common language runtime. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4632.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4632.md index eb92db81390..7d4b05da68b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4632.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4632.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4632" title: "Compiler Warning (level 1) C4632" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4632" +ms.date: 11/04/2016 f1_keywords: ["C4632"] helpviewer_keywords: ["C4632"] -ms.assetid: 9e35d205-cf21-4e34-8bd5-e1e7b0e2cdd3 --- # Compiler Warning (level 1) C4632 -XML document comment: file - access denied: reason +> XML document comment: file - access denied: reason + +## Remarks The path to .xdc file (`file`) was not valid, and no .xdc file created. -The following sample generates C4632: +## Example + +The following example generates C4632: ```cpp // C4632.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4650.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4650.md index 6eb867c876c..ded99d3b702 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4650.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4650.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4650" title: "Compiler Warning (level 1) C4650" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4650" +ms.date: 11/04/2016 f1_keywords: ["C4650"] helpviewer_keywords: ["C4650"] -ms.assetid: 3190b3e3-dcd6-4846-939b-f900ab652b2a --- # Compiler Warning (level 1) C4650 -debugging information not in precompiled header; only global symbols from the header will be available +> debugging information not in precompiled header; only global symbols from the header will be available + +## Remarks The precompiled header file was not compiled with Microsoft symbolic debugging information. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4651.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4651.md index ad0334aba73..34a4d06f1e6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4651.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4651.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4651" title: "Compiler Warning (level 1) C4651" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4651" +ms.date: 11/04/2016 f1_keywords: ["C4651"] helpviewer_keywords: ["C4651"] -ms.assetid: f1ea82aa-4dc1-4972-b55a-57fdb962f0dd --- # Compiler Warning (level 1) C4651 -'definition' specified for precompiled header but not for current compile +> 'definition' specified for precompiled header but not for current compile + +## Remarks The definition was specified when the precompiled header was generated, but not in this compilation. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4652.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4652.md index b8130b1bd48..a70abbd28b7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4652.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4652.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4652" title: "Compiler Warning (level 1) C4652" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4652" +ms.date: 11/04/2016 f1_keywords: ["C4652"] helpviewer_keywords: ["C4652"] -ms.assetid: 2cf2c666-8cdd-4dd9-bda0-662921498b03 --- # Compiler Warning (level 1) C4652 -compiler option 'option' inconsistent with precompiled header; current command-line option will override that defined in the precompiled header +> compiler option 'option' inconsistent with precompiled header; current command-line option will override that defined in the precompiled header + +## Remarks The given command-line option differed from that given when the precompiled header (.pch) was created. The option specified in the current command line was used. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4655.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4655.md index 7a3e26979a8..f8d307ae981 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4655.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4655.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4655" title: "Compiler Warning (level 1) C4655" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4655" +ms.date: 08/27/2018 f1_keywords: ["C4655"] helpviewer_keywords: ["C4655"] -ms.assetid: 540f2c7a-e4a1-49af-84b4-03eeea1bbf41 --- # Compiler Warning (level 1) C4655 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4656.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4656.md index 4d7a41a0736..cf56b54f864 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4656.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4656.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4656" title: "Compiler Warning (level 1) C4656" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4656" +ms.date: 11/04/2016 f1_keywords: ["C4656"] helpviewer_keywords: ["C4656"] -ms.assetid: b5aaef74-2320-4345-a6ae-b813881a491c --- # Compiler Warning (level 1) C4656 -'symbol' : data type is new or has changed since the last build, or is defined differently elsewhere +> 'symbol' : data type is new or has changed since the last build, or is defined differently elsewhere + +## Remarks You added or changed a data type, making it new to your source code since the last successful build. Edit and Continue does not support changes to existing data types. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4657.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4657.md index 2fe16f7f35d..2122b6d551a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4657.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4657.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4657" title: "Compiler Warning (level 1) C4657" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4657" +ms.date: 11/04/2016 f1_keywords: ["C4657"] helpviewer_keywords: ["C4657"] -ms.assetid: eb750050-cea6-4ead-b80c-d5dcd4971cfc --- # Compiler Warning (level 1) C4657 -expression involves a data type that is new since the last build +> expression involves a data type that is new since the last build + +## Remarks You added or changed a data type, making it new to your source code since the last successful build. Edit and Continue does not support changes to existing data types. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4659.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4659.md index 88e61092e69..a38cf4cf7ae 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4659.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4659.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4659" title: "Compiler Warning (level 1) C4659" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4659" +ms.date: 11/04/2016 f1_keywords: ["C4659"] helpviewer_keywords: ["C4659"] -ms.assetid: e29ba8db-7917-43f6-8e34-868b752279ae --- # Compiler Warning (level 1) C4659 -\#pragma 'pragma' : use of reserved segment 'segment' has undefined behavior, use #pragma comment(linker, ...) +> #pragma 'pragma' : use of reserved segment 'segment' has undefined behavior, use #pragma comment(linker, ...) + +## Remarks The .drectve option was used to pass an option to the linker. Instead use pragma [comment](../../preprocessor/comment-c-cpp.md) for passing a linker option. +## Example + +The following example generates C4659: + ```cpp // C4659.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4661.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4661.md index e3f0cbbf69d..b4d9e92a60c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4661.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4661.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4661" title: "Compiler Warning (level 1) C4661" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4661" +ms.date: 11/04/2016 f1_keywords: ["C4661"] helpviewer_keywords: ["C4661"] -ms.assetid: 603bb8b7-356d-4eef-924b-64d769bac5bd --- # Compiler Warning (level 1) C4661 -'identifier' : no suitable definition provided for explicit template instantiation request +> 'identifier' : no suitable definition provided for explicit template instantiation request + +## Remarks A member of the template class is not defined. ## Example +The following example generates C4661: + ```cpp // C4661.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4662.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4662.md index 3d92cd2b859..68beca85087 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4662.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4662.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4662" title: "Compiler Warning (level 1) C4662" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4662" +ms.date: 11/04/2016 f1_keywords: ["C4662"] helpviewer_keywords: ["C4662"] -ms.assetid: 7efda273-d04a-47b7-ad65-ff1ff94b5ffc --- # Compiler Warning (level 1) C4662 -explicit instantiation; template-class 'identifier1' has no definition from which to specialize 'identifier2' +> explicit instantiation; template-class 'identifier1' has no definition from which to specialize 'identifier2' + +## Remarks The specified template-class was declared, but not defined. ## Example +The following example generates C4662: + ```cpp // C4662.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4667.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4667.md index 2170e220116..6de3394c5d8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4667.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4667.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4667" title: "Compiler Warning (level 1) C4667" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4667" +ms.date: 11/04/2016 f1_keywords: ["C4667"] helpviewer_keywords: ["C4667"] -ms.assetid: 5d2b7fe0-4f0e-4cd6-b432-ca02c3d194ab --- # Compiler Warning (level 1) C4667 -'function' : no function template defined that matches forced instantiation +> 'function' : no function template defined that matches forced instantiation + +## Remarks You cannot instantiate a function template that has not been declared. -The following sample will cause C4667: +## Example + +The following example will cause C4667: ```cpp // C4667a.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4669.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4669.md index ff9b92c50a9..3d19bad6cd0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4669.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4669.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4669" title: "Compiler Warning (level 1) C4669" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4669" +ms.date: 11/04/2016 f1_keywords: ["C4669"] helpviewer_keywords: ["C4669"] -ms.assetid: 97730679-e3dc-44d4-b2a8-aa65badc17f2 --- # Compiler Warning (level 1) C4669 -'cast' : unsafe conversion: 'class' is a managed or WinRT type object +> 'cast' : unsafe conversion: 'class' is a managed or WinRT type object + +## Remarks A cast contains a Windows Runtime or managed type. The compiler completes the cast by performing a bit-wise copy of one pointer to the other, but provides no other checking. To resolve this warning, do not cast classes containing managed members or Windows Runtime types. -The following sample generates C4669 and shows how to fix it: +## Example + +The following example generates C4669 and shows how to fix it: ```cpp // C4669.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4674.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4674.md index 5bdc7b61cab..37e020cd33e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4674.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4674.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4674" title: "Compiler Warning (level 1) C4674" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4674" +ms.date: 11/04/2016 f1_keywords: ["C4674"] helpviewer_keywords: ["C4674"] -ms.assetid: 638dae0b-b82c-4865-9599-72630827ca09 --- # Compiler Warning (level 1) C4674 -'method' should be declared 'static' and have exactly one parameter +> 'method' should be declared 'static' and have exactly one parameter + +## Remarks The signature of a conversion operator was not correct. The method is not considered a user-defined conversion. For more information on defining operators, see [User-Defined Operators (C++/CLI)](../../dotnet/user-defined-operators-cpp-cli.md) and [User-Defined Conversions (C++/CLI)](../../dotnet/user-defined-conversions-cpp-cli.md). ## Example -The following sample generates C4674. +The following example generates C4674. ```cpp // C4674.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4677.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4677.md index 40eb235d544..1a86bd31b69 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4677.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4677.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4677" title: "Compiler Warning (level 1) C4677" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4677" +ms.date: 11/04/2016 f1_keywords: ["C4677"] helpviewer_keywords: ["C4677"] -ms.assetid: a8d656a1-e2ff-4f8b-9028-201765131026 --- # Compiler Warning (level 1) C4677 -'function': signature of non-private member contains assembly private type 'private_type' +> 'function': signature of non-private member contains assembly private type 'private_type' + +## Remarks A type that has public accessibility outside the assembly uses a type that has private access outside the assembly. A component that references the public assembly type will not be able to use the type member or members that reference the assembly private type. ## Example -The following sample generates C4677. +The following example generates C4677. ```cpp // C4677.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4678.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4678.md index ef63fce96f9..cfe99eaf282 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4678.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4678.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4678" title: "Compiler Warning (level 1) C4678" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4678" +ms.date: 11/04/2016 f1_keywords: ["C4678"] helpviewer_keywords: ["C4678"] -ms.assetid: 0c588f34-595d-4e5c-9470-8723fca2cc06 --- # Compiler Warning (level 1) C4678 -base class 'base_type' is less accessible than 'derived_type' +> base class 'base_type' is less accessible than 'derived_type' + +## Remarks A public type derives from a private type. If the public type is instantiated in a referenced assembly, members of the private base type will not be accessible. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4679.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4679.md index 60432e84ec0..ada9e31dc9c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4679.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4679.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4679" title: "Compiler Warning (level 1) C4679" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4679" +ms.date: 08/27/2018 f1_keywords: ["C4679"] helpviewer_keywords: ["C4679"] -ms.assetid: 3cc74150-42a8-4116-94cd-4ef0fd6dcf32 --- # Compiler Warning (level 1) C4679 > '*member*' : could not import member +## Remarks + The compiler encountered a construct that it cannot support, that cannot be imported from metadata. Do not try to use the construct. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4683.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4683.md index 4e49d32e524..f403e48f03d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4683.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4683.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4683" title: "Compiler Warning (level 1) C4683" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4683" +ms.date: 08/27/2018 f1_keywords: ["C4683"] helpviewer_keywords: ["C4683"] -ms.assetid: e6e77364-dba1-46dd-ae1d-03da23070bce --- # Compiler Warning (level 1) C4683 @@ -24,7 +23,7 @@ The reason for the leak is that the out parameter will be set by more than one h ## Example -The following sample generates C4683 and shows how to fix it: +The following example generates C4683 and shows how to fix it: ```cpp // C4683.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4684.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4684.md index d48b01c07b8..ab66c25bf43 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4684.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4684.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4684" title: "Compiler Warning (level 1) C4684" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4684" +ms.date: 11/04/2016 f1_keywords: ["C4684"] helpviewer_keywords: ["C4684"] -ms.assetid: e95f1a83-2784-4b05-ae94-12148e056e26 --- # Compiler Warning (level 1) C4684 -'attribute' : WARNING!! attribute may cause invalid code generation: use with caution +> 'attribute' : WARNING!! attribute may cause invalid code generation: use with caution + +## Remarks You used an attribute that should not commonly be used. -The following sample generates C4684: +## Example + +The following example generates C4684: ```cpp // C4684.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4685.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4685.md index 484436b8714..a9fdc182960 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4685.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4685.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4685" title: "Compiler Warning (level 1) C4685" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4685" +ms.date: 11/04/2016 f1_keywords: ["C4685"] helpviewer_keywords: ["C4685"] -ms.assetid: 16e859b8-a8e8-4a0d-a1d0-37ec4e59a9d7 --- # Compiler Warning (level 1) C4685 -expecting '> >' found '>>' when parsing template parameters +> expecting '> >' found '>>' when parsing template parameters + +## Remarks A template definition was not terminated correctly. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4688.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4688.md index 59bedf3f0fb..d257f2f4acc 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4688.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4688.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4688" title: "Compiler Warning (level 1) C4688" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4688" +ms.date: 11/04/2016 f1_keywords: ["C4688"] helpviewer_keywords: ["C4688"] -ms.assetid: a027df3c-b2b8-4c49-8539-c2bc42db74e8 --- # Compiler Warning (level 1) C4688 -'constraint': constraint list contains assembly private type 'type' +> 'constraint': constraint list contains assembly private type 'type' + +## Remarks A constraint list has an assembly private type, meaning it will not be available when the type is accessed from outside the assembly. For more information, see [Generics](../../extensions/generics-cpp-component-extensions.md). ## Example -The following sample generates C4688. +The following example generates C4688. ```cpp // C4688.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4691.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4691.md index 16750c821ca..ae062d85d15 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4691.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4691.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4691" title: "Compiler Warning (level 1) C4691" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4691" +ms.date: 11/04/2016 f1_keywords: ["C4691"] helpviewer_keywords: ["C4691"] -ms.assetid: 722133d9-87f6-46c1-9e86-9825453d6999 --- # Compiler Warning (level 1) C4691 -'type' : type referenced was expected in unreferenced assembly 'file', type defined in current translation unit used instead +> 'type' : type referenced was expected in unreferenced assembly 'file', type defined in current translation unit used instead + +## Remarks The metadata file containing the original type definition is not referenced, and the compiler is using a local type definition. @@ -16,9 +17,9 @@ In the case where you are rebuilding *file*, C4691 can be ignored or turned off However, unexpected behavior can occur if the compiler uses a definition that is not from the same assembly that is referenced in metadata; CLR types are typed not only by the name of the type, but also by the assembly. That is, a type Z from assembly z.dll is different from a type Z from assembly y.dll. -## Examples +## Example -This sample contains the original type definition. +This example contains the original type definition. ```cpp // C4691_a.cpp @@ -26,7 +27,7 @@ This sample contains the original type definition. public ref class Original_Type {}; ``` -This sample references C4691_a.dll and declares a field of type Original_Type. +This example references C4691_a.dll and declares a field of type Original_Type. ```cpp // C4691_b.cpp @@ -38,7 +39,7 @@ public: }; ``` -The following sample generates C4691. Notice this sample contains a definition for Original_Type and does not reference C4691a.dll. +The following example generates C4691. Notice this example contains a definition for Original_Type and does not reference C4691a.dll. To resolve, reference the metadata file that contains the original type definition and remove the local declaration and definition. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4692.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4692.md index d9421493012..44cc03e03b4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4692.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4692.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4692" title: "Compiler Warning (level 1) C4692" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4692" +ms.date: 11/04/2016 f1_keywords: ["C4692"] helpviewer_keywords: ["C4692"] -ms.assetid: f6fb3acc-8228-491a-9c30-ce302d8a9c75 --- # Compiler Warning (level 1) C4692 -'function': signature of non-private member contains assembly private native type 'native_type' +> 'function': signature of non-private member contains assembly private native type 'native_type' + +## Remarks A type that is visible outside the assembly contains a member function whose signature contains a native type that is not visible outside the assembly. Therefore, the member function should not be called if its containing type is instantiated outside the assembly. @@ -18,7 +19,7 @@ This warning is off by default. For more information, see [Compiler Warnings Tha ## Example -The following sample generates C4692. +The following example generates C4692. ```cpp // C4692.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4711.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4711.md index 264ef9afb52..1f8acf57625 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4711.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4711.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4711" title: "Compiler Warning (level 1) C4711" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4711" +ms.date: 11/04/2016 f1_keywords: ["C4711"] helpviewer_keywords: ["C4711"] -ms.assetid: 270506ab-fead-4328-b714-2978113be238 --- # Compiler Warning (level 1) C4711 -function 'function' selected for inline expansion +> function 'function' selected for inline expansion + +## Remarks The compiler performed inlining on the given function, although it was not marked for inlining. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4715.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4715.md index c4f1d16eda7..7350b2edfe6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4715.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4715.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4715" title: "Compiler Warning (level 1) C4715" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4715" +ms.date: 11/04/2016 f1_keywords: ["C4715"] helpviewer_keywords: ["C4715"] -ms.assetid: 1c819bf7-0d8b-4f5e-b338-9cc292870439 --- # Compiler Warning (level 1) C4715 -'function' : not all control paths return a value +> 'function' : not all control paths return a value + +## Remarks The specified function can potentially not return a value. ## Example +The following example generates C4715: + ```cpp // C4715a.cpp // compile with: /W1 /LD diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4716.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4716.md index a01e32efc2c..ed6196b2104 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4716.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4716.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4716" title: "Compiler Warning (level 1) C4716" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4716" +ms.date: 11/04/2016 f1_keywords: ["C4716"] helpviewer_keywords: ["C4716"] -ms.assetid: d95ecfe5-870f-461f-a746-7913af98414b --- # Compiler Warning (level 1) C4716 -'function' must return a value +> 'function' must return a value + +## Remarks The given function did not return a value. @@ -18,7 +19,9 @@ An undefined value will be returned when this function is called. This warning is automatically promoted to an error. If you wish to modify this behavior, use [#pragma warning](../../preprocessor/warning.md). -The following sample generates C4716: +## Example + +The following example generates C4716: ```cpp // C4716.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4717.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4717.md index 3a0de8742fd..a546f804471 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4717.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4717.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4717" title: "Compiler Warning (level 1) C4717" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4717" +ms.date: 11/04/2016 f1_keywords: ["C4717"] helpviewer_keywords: ["C4717"] -ms.assetid: 5ef3c6c7-8599-4714-a973-0f5b69cdab3c --- # Compiler Warning (level 1) C4717 -'function' : recursive on all control paths, function will cause runtime stack overflow +> 'function' : recursive on all control paths, function will cause runtime stack overflow + +## Remarks Every path through a function contains a call to the function. Since there is no way to exit the function without first calling itself recursively, the function will never exit. -The following sample generates C4717: +## Example + +The following example generates C4717: ```cpp // C4717.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4722.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4722.md index 14ff9e25bdb..badb5a14db1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4722.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4722.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4722" title: "Compiler Warning (level 1) C4722" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4722" +ms.date: 11/04/2016 f1_keywords: ["C4722"] helpviewer_keywords: ["C4722"] -ms.assetid: d8660710-f67b-4f59-a5fd-59259475529e --- # Compiler Warning (level 1) C4722 -'function' : destructor never returns, potential memory leak +> 'function' : destructor never returns, potential memory leak + +## Remarks The flow of control terminates in a destructor. The thread or the entire program will terminate and allocated resources may not be released. Furthermore, if a destructor will be called for stack unwinding during exception processing, the behavior of executable is undefined. @@ -16,7 +17,7 @@ To resolve, remove the function call that causes the destructor to not return. ## Example -The following sample generates C4722: +The following example generates C4722: ```cpp // C4722.cpp @@ -25,7 +26,7 @@ The following sample generates C4722: class C { public: C(); - ~C() { exit(1); }; // C4722 + ~C() { exit(1); } // C4722 }; extern void func (C*); diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4727.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4727.md index 821b7447a7f..d791c9190ce 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4727.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4727.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4727" title: "Compiler Warning (level 1) C4727" -ms.date: "08/19/2019" +description: "Learn more about: Compiler Warning (level 1) C4727" +ms.date: 08/19/2019 f1_keywords: ["C4727"] helpviewer_keywords: ["C4727"] -ms.assetid: 991b0087-3a50-40f5-9cdb-cdc367cd472c --- # Compiler Warning (level 1) C4727 -"PCH named pch_file with same timestamp found in obj_file_1 and obj_file_2. Using first PCH. +> "PCH named pch_file with same timestamp found in obj_file_1 and obj_file_2. Using first PCH. + +## Remarks > [!NOTE] > In Visual Studio 2017 and earlier, the precompiled header is called *stdafx.h* by default, and in Visual Studio 2019 and later, it is called *pch.h* by default. @@ -17,6 +18,8 @@ C4727 occurs when compiling multiple compilands with **/Yc**, and where the comp To resolve, compile one source file with **/Yc /c** (creates pch), and the others compile separately with **/Yu /c** (uses pch), then link them together. +## Example + So, if you did the following and it generates C4727: ::: moniker range="<=msvc-150" diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4729.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4729.md index 5bb7c836a4f..d8b24fc3922 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4729.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4729.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4729" title: "Compiler Warning (Level 1) C4729" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 1) C4729" +ms.date: 11/04/2016 f1_keywords: ["C4729"] helpviewer_keywords: ["C4729"] -ms.assetid: 36a0151f-f258-48d9-9444-ae6d41ff70a4 --- # Compiler Warning (Level 1) C4729 -function too big for flow graph based warnings +> function too big for flow graph based warnings + +## Remarks This warning is generated when a function is too big to be compiled with reliable checking for situations that would generate a warning. This warning is only generated when the [/Od](../../build/reference/od-disable-debug.md) compiler option used. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4730.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4730.md index 69e3190a359..3856100db3a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4730.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4730.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4730" title: "Compiler Warning (Level 1) C4730" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 1) C4730" +ms.date: 11/04/2016 f1_keywords: ["C4730"] helpviewer_keywords: ["C4730"] -ms.assetid: 11303e3f-162b-4b19-970a-479686123a68 --- # Compiler Warning (Level 1) C4730 -'main' : mixing _m64 and floating point expressions may result in incorrect code +> 'main' : mixing _m64 and floating point expressions may result in incorrect code + +## Remarks A function uses [__m64](../../cpp/m64.md) and **`float`**/**`double`** types. Because the MMX and floating-point registers share the same physical register space (cannot be used simultaneously), using **`__m64`** and **`float`**/**`double`** types in the same function can result in data corruption, possibly causing an exception. To safely use **`__m64`** types and floating-point types in the same function, each instruction that uses one of the types should be separated by the **_m_empty()** (for MMX) or **_m_femms()** (for 3DNow!) intrinsic. -The following sample generates C4730: +## Example + +The following example generates C4730: ```cpp // C4730.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4731.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4731.md index 4e758090b5a..cdefa78d6b8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4731.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4731.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4731" title: "Compiler Warning (Level 1) C4731" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 1) C4731" +ms.date: 11/04/2016 f1_keywords: ["C4731"] helpviewer_keywords: ["C4731"] -ms.assetid: 5658c24c-3e6f-4505-835b-1fb92d47cab0 --- # Compiler Warning (Level 1) C4731 -'pointer' : frame pointer register 'register' modified by inline assembly code +> 'pointer' : frame pointer register 'register' modified by inline assembly code + +## Remarks A frame pointer register was modified. You must save and restore the register in your inline assembly block or frame variable (local or parameter, depending on the register modified), or your code may not work properly. -The following sample generates C4731: +## Example + +The following example generates C4731: ```cpp // C4731.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4733.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4733.md index 1c64dd7cbb5..d4e0f431ea3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4733.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4733.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4733" title: "Compiler Warning (Level 1) C4733" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 1) C4733" +ms.date: 11/04/2016 f1_keywords: ["C4733"] helpviewer_keywords: ["C4733"] -ms.assetid: 7ef4f577-772d-4b66-a7bf-8958a6b250bc --- # Compiler Warning (Level 1) C4733 -Inline asm assigning to 'FS:0' : handler not registered as safe handler +> Inline asm assigning to 'FS:0' : handler not registered as safe handler + +## Remarks A function modifying the value at FS:0 to add a new exception handler may not work with Safe Exceptions, because the handler may not be registered as a valid exception handler (see [/SAFESEH](../../build/reference/safeseh-image-has-safe-exception-handlers.md)). To resolve this warning, either remove the FS:0 definition or turn off this warning and use [.SAFESEH](../../assembler/masm/dot-safeseh.md) to specify the safe exception handlers. -The following sample generates C4733: +## Example + +The following example generates C4733: ```cpp // C4733.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4739.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4739.md index 83340c734c5..d9fb0cb42b1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4739.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4739.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4739" title: "Compiler Warning (Level 1) C4739" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 1) C4739" +ms.date: 11/04/2016 f1_keywords: ["C4739"] helpviewer_keywords: ["C4739"] -ms.assetid: 600873b3-7c85-4cd4-944e-cd8e01bfcbb0 --- # Compiler Warning (Level 1) C4739 -reference to variable 'var' exceeds its storage space +> reference to variable 'var' exceeds its storage space + +## Remarks A value was assigned to a variable, but the value is greater than the size of the variable. Memory will be written beyond the variable's memory location, and data loss is possible. To resolve this warning, only assign a value to a variable whose size can accommodate the value. -The following sample generates C4739: +## Example + +The following example generates C4739: ```cpp // C4739.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4742.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4742.md index c25caf63912..65aee758f44 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4742.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4742.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4742" title: "Compiler Warning (Level 1) C4742" +description: "Learn more about: Compiler Warning (Level 1) C4742" ms.date: 07/22/2020 f1_keywords: ["C4742"] helpviewer_keywords: ["C4742"] -ms.assetid: e520881d-1eeb-48b1-9df0-8017ee8ba076 --- # Compiler Warning (Level 1) C4742 > '*variable*' has different alignment in '*file1*' and '*file2*': *number1* and *number2* -An external variable that was referenced or defined in two files has different alignment in those files. - ## Remarks +An external variable that was referenced or defined in two files has different alignment in those files. + This warning is emitted when compiler finds that **`alignof`** for the variable in *file1* differs from **`alignof`** for the variable in *file2*. This can be caused by using incompatible types when declaring variable in different files, or by using non-matching `#pragma pack` in different files. To resolve this warning, either use the same type definition or use different names for the variables. @@ -32,7 +31,7 @@ struct X { } global; ``` -The following sample generates C4742. +The following example generates C4742. ```c // C4742b.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md index 7587043b9dc..3eb845751b1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4743.md @@ -1,26 +1,25 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4743" title: "Compiler Warning (Level 1) C4743" +description: "Learn more about: Compiler Warning (Level 1) C4743" ms.date: 06/16/2022 f1_keywords: ["C4743"] helpviewer_keywords: ["C4743"] -ms.assetid: 2ee76ea3-77f3-4c2f-9a57-0751823c89fd --- # Compiler Warning (Level 1) C4743 > '*type*' has different size in '*file1*' and '*file2*': *size_1* and *size_2* bytes -An external variable referenced or defined in two files has different types in those files, and the compiler determined that the size of the variable in *file1* differs from the size of the variable in *file2*. - ## Remarks +An external variable referenced or defined in two files has different types in those files, and the compiler determined that the size of the variable in *file1* differs from the size of the variable in *file2*. + There's an important case when this warning can be emitted for C++. If you declare class types with the same name in two different files, if those declarations contain virtual functions, and if the declarations aren't the same, then the compiler can emit warning C4744 for the virtual function tables. The warning occurs because there are two different-sized virtual function tables for the same type, and the linker must choose one of them to incorporate into the executable. It's possible that it can result in your program calling the wrong virtual function. To resolve this warning, either use the same type definition or use different names for the types or variables. ## Example -The following sample generates C4743. To compile it, place both files in the same folder, then run this command in a developer command prompt: +The following example generates C4743. To compile it, place both files in the same folder, then run this command in a developer command prompt: ```cmd cl /EHsc /W1 /GL /O2 C4743a.cpp C4743b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md index e4cb1f2a3fb..df60c3ad08e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4744.md @@ -1,25 +1,26 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4744" title: "Compiler Warning (Level 1) C4744" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 1) C4744" +ms.date: 11/04/2016 f1_keywords: ["C4744"] helpviewer_keywords: ["C4744"] -ms.assetid: f2a7d0b5-afd5-4926-abc3-cfbd367e3ff5 --- # Compiler Warning (Level 1) C4744 -'var' has different type in 'file1' and 'file2': 'type1' and 'type2' +> 'var' has different type in 'file1' and 'file2': 'type1' and 'type2' + +## Remarks An external variable referenced or defined in two files has different types in those files. To resolve, either make the type definitions the same, or change variable name in one of the files. C4744 is emitted only when files are compiled with /GL. For more information, see [/GL (Whole Program Optimization)](../../build/reference/gl-whole-program-optimization.md). > [!NOTE] -> C4744 usually occurs in C (not C++) files, because in C++ a variable name is decorated with type information. When the sample (below) is compiles as C++, you’ll get linker error LNK2019. +> C4744 usually occurs in C (not C++) files, because in C++ a variable name is decorated with type information. When the example (below) is compiles as C++, you'll get linker error LNK2019. -## Examples +## Example -This sample contains the first definition. +This example contains the first definition. ```c // C4744.c @@ -27,7 +28,7 @@ This sample contains the first definition. int global; ``` -The following sample generates C4744. +The following example generates C4744. ```c // C4744b.c @@ -37,7 +38,7 @@ The following sample generates C4744. extern unsigned global; -main() +int main() { printf_s("%d\n", global); } diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4747.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4747.md index 9b7dd217972..4354ddd8827 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4747.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4747.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4747" title: "Compiler Warning (level 1) C4747" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4747" +ms.date: 11/04/2016 f1_keywords: ["C4747"] helpviewer_keywords: ["C4747"] -ms.assetid: af37befd-ba1f-4bdc-96e1-a953f7a2ad9c --- # Compiler Warning (level 1) C4747 -Calling managed 'entrypoint': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint +> Calling managed 'entrypoint': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint + +## Remarks The compiler found a (probable) DLL entry point compiled to MSIL. Because of potential problems with loading a DLL whose entry point has been compiled to MSIL, you are strongly discouraged from compiling a DLL entry point function to MSIL. @@ -22,7 +23,7 @@ For more information, see [Initialization of Mixed Assemblies](../../dotnet/init ## Example -The following sample generates C4747. +The following example generates C4747. ```cpp // C4747.cpp @@ -35,5 +36,5 @@ The following sample generates C4747. BOOL WINAPI DllMain(HANDLE hInstance, ULONG Command, LPVOID Reserved) { return TRUE; -}; +} ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4750.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4750.md index da0b7a82489..8739b355309 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4750.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4750.md @@ -4,7 +4,6 @@ description: "Describes MSVC compiler warning C4750 about a possible stack overf ms.date: 07/08/2020 f1_keywords: ["C4750"] helpviewer_keywords: ["C4750"] -ms.assetid: b0b2c938-7d2a-4c36-8270-7daee15ffee3 --- # Compiler Warning (level 1) C4750 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4772.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4772.md index efe45fc03e2..4f8fba1457b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4772.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4772.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4772" title: "Compiler Warning (level 1) C4772" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4772" +ms.date: 11/04/2016 f1_keywords: ["C4772"] helpviewer_keywords: ["C4772"] -ms.assetid: dafe6fd8-9faf-41f5-9d66-a55838742c14 --- # Compiler Warning (level 1) C4772 -> \#import referenced a type from a missing type library; '*missing-type*' used as a placeholder +> #import referenced a type from a missing type library; '*missing-type*' used as a placeholder + +## Remarks A type library was referenced with the [#import](../../preprocessor/hash-import-directive-cpp.md) directive. However, the type library contained a reference to another type library that was not referenced with `#import`. This other .tlb file was not found by the compiler. @@ -51,7 +52,7 @@ library C4772bLib }; ``` -The following sample generates C4772: +The following example generates C4772: ```cpp // C4772.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md index dd4276de107..a9c8bdd271a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4788.md @@ -1,20 +1,25 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4788" title: "Compiler Warning (Level 1) C4788" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 1) C4788" +ms.date: 11/04/2016 f1_keywords: ["C4788"] helpviewer_keywords: ["C4788"] -ms.assetid: 47d75bda-f833-4bdd-93a0-a134df0cd303 --- # Compiler Warning (Level 1) C4788 -'identifier' : identifier was truncated to 'number' characters +> 'identifier' : identifier was truncated to 'number' characters + +## Remarks The compiler limits the maximum length allowed for a function name. When the compiler generates funclets for EH/SEH code, it forms the funclet name by prepending the function name with some text, for example "__catch", "\__unwind", or another string. The resulting funclet name can be too long, and the compiler will truncate it and generate C4788. -To resolve this warning, shorten the original function name. If the function is a C++ template function or method, use a typedef for part of the name. For example: +To resolve this warning, shorten the original function name. If the function is a C++ function template or method, use a typedef for part of the name. + +## Example + +For example: ```cpp C1>::C2::f diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md index 2d5fa6daeb3..65ff8705ae4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4789.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (Level 1) C4789" title: "Compiler Warning (Level 1) C4789" -ms.date: "03/25/2019" +description: "Learn more about: Compiler Warning (Level 1) C4789" +ms.date: 08/30/2022 f1_keywords: ["C4789"] helpviewer_keywords: ["C4789"] -ms.assetid: 5800c301-5afb-4af0-85c1-ceb54d775234 --- # Compiler Warning (Level 1) C4789 @@ -18,11 +17,9 @@ ms.assetid: 5800c301-5afb-4af0-85c1-ceb54d775234 The warning occurs if the copy uses the intrinsic form of one of these CRT functions: -- [strcpy](../../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md) - -- [memset](../../c-runtime-library/reference/memset-wmemset.md) - -- [memcpy](../../c-runtime-library/reference/memcpy-wmemcpy.md), [wmemcpy](../../c-runtime-library/reference/memcpy-wmemcpy.md) +- [`strcpy`](../../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md) +- [`memset`](../../c-runtime-library/reference/memset-wmemset.md) +- [`memcpy`](../../c-runtime-library/reference/memcpy-wmemcpy.md), [`wmemcpy`](../../c-runtime-library/reference/memcpy-wmemcpy.md) The warning also appears when you cast a parameter to a larger data type, and then make a copy assignment from an lvalue reference. @@ -31,15 +28,17 @@ Visual C++ might generate this warning for a code path that never executes. You ```cpp #pragma warning( push ) #pragma warning( disable : 4789 ) -// unused code that generates compiler warning C4789` +// unused code that generates compiler warning C4789 #pragma warning( pop ) ``` -This idiom keeps Visual C++ from generating the warning for that specific block of code. The `#pragma warning(push)` preserves the existing state before `#pragma warning(disable: 4789)` changes it. The `#pragma warning(pop)` restores the pushed state, and removes the effects of the `#pragma warning(disable:4789)`. For more information about the C++ preprocessor directive `#pragma`, see [warning](../../preprocessor/warning.md) and [Pragma Directives and the __Pragma Keyword](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). +This idiom keeps Visual C++ from generating the warning for that specific block of code. The `#pragma warning(push)` preserves the existing state before `#pragma warning(disable: 4789)` changes it. The `#pragma warning(pop)` restores the pushed state, and removes the effects of the `#pragma warning(disable:4789)`. For more information about the C++ preprocessor directive `#pragma`, see [`warning`](../../preprocessor/warning.md) and [Pragma directives and the `__pragma` and `_Pragma` keywords](../../preprocessor/pragma-directives-and-the-pragma-keyword.md). + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Examples -The following sample generates C4789. +The following example generates C4789: ```cpp // C4789.cpp @@ -61,7 +60,7 @@ int main() } ``` -The following sample also generates C4789. +The following example also generates C4789: ```cpp // C4789b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4794.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4794.md index 909387c2dc9..fec3c297b94 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4794.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4794.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4794" title: "Compiler Warning (level 1) C4794" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4794" +ms.date: 11/04/2016 f1_keywords: ["C4794"] helpviewer_keywords: ["C4794"] -ms.assetid: badc9c36-fa1a-4fec-929b-7bfda7a7b79f --- # Compiler Warning (level 1) C4794 -segment of thread local storage variable 'variable' changed from 'section name' to '.tls$' +> segment of thread local storage variable 'variable' changed from 'section name' to '.tls$' + +## Remarks You used [#pragma data_seg](../../preprocessor/data-seg.md) to put a tls variable in a section not starting with .tls$. @@ -16,7 +17,7 @@ The .tls$*x* section will exist in the object file where [__declspec(thread)](.. ## Example -The following sample generates C4794: +The following example generates C4794: ```cpp // C4794.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 ec6ba0260ef..4de2401b823 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,37 @@ --- -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. +## Remarks -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. +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 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-c4803.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4803.md index 8a242d9c74d..160cd494ab1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4803.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4803.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4803" title: "Compiler Warning (level 1) C4803" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4803" +ms.date: 11/04/2016 f1_keywords: ["C4803"] helpviewer_keywords: ["C4803"] -ms.assetid: 2552f3a6-c418-49f4-98a2-a929857be658 --- # Compiler Warning (level 1) C4803 -'method' : the raise method has a different storage class from that of the event, 'event' +> 'method' : the raise method has a different storage class from that of the event, 'event' + +## Remarks Event methods must have the same storage class as the event declaration. The compiler adjusts the event's methods so that the storage classes are the same. @@ -18,7 +19,7 @@ See [warning](../../preprocessor/warning.md) pragma for information on how to tu ## Example -The following sample generates C4803. +The following example generates C4803. ```cpp // C4803.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4804.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4804.md index 3d6298288d6..a8d9c239b19 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4804.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4804.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4804" title: "Compiler Warning (level 1) C4804" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4804" +ms.date: 11/04/2016 f1_keywords: ["C4804"] helpviewer_keywords: ["C4804"] -ms.assetid: 069e8f44-3ef6-43bb-8524-4116fc6eea83 --- # Compiler Warning (level 1) C4804 -'operation' : unsafe use of type 'bool' in operation +> 'operation' : unsafe use of type 'bool' in operation + +## Remarks This warning is for when you used a **`bool`** variable or value in an unexpected way. For example, C4804 is generated if you use operators such as the negative unary operator (**-**) or the complement operator (`~`). The compiler evaluates the expression. ## Example -The following sample generates C4804: +The following example generates C4804: ```cpp // C4804.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4805.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4805.md index 02304303c4f..e85756333b8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4805.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4805.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4805" title: "Compiler Warning (level 1) C4805" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4805" +ms.date: 11/04/2016 f1_keywords: ["C4805"] helpviewer_keywords: ["C4805"] -ms.assetid: 99c7b7e2-272e-4ab5-8580-17c42e62e2ef --- # Compiler Warning (level 1) C4805 -'operation' : unsafe mix of type 'type' and type 'type' in operation +> 'operation' : unsafe mix of type 'type' and type 'type' in operation + +## Remarks + +This warning is generated for comparison operations between [bool](../../cpp/bool-cpp.md) and [int](../../c-language/integer-types.md). + +## Example -This warning is generated for comparison operations between [bool](../../cpp/bool-cpp.md) and [int](../../c-language/integer-types.md). The following sample generates C4805: +The following example generates C4805: ```cpp // C4805.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4806.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4806.md index 276e5adc69e..a86050abde4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4806.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4806.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4806" title: "Compiler Warning (level 1) C4806" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4806" +ms.date: 11/04/2016 f1_keywords: ["C4806"] helpviewer_keywords: ["C4806"] -ms.assetid: 79eb74cd-b925-4b5b-84e1-8ae6f33e38b3 --- # Compiler Warning (level 1) C4806 -'operation' : unsafe operation: no value of type 'type' promoted to type 'type' can equal the given constant +> 'operation' : unsafe operation: no value of type 'type' promoted to type 'type' can equal the given constant + +## Remarks + +This message warns against code such as `b == 3`, where `b` has type **`bool`**. The promotion rules cause **`bool`** to be promoted to **`int`**. This is legal, but it can never be **`true`**. + +## Example -This message warns against code such as `b == 3`, where `b` has type **`bool`**. The promotion rules cause **`bool`** to be promoted to **`int`**. This is legal, but it can never be **`true`**. The following sample generates C4806: +The following example generates C4806: ```cpp // C4806.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4807.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4807.md index 1bfb761d9af..9696970dd32 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4807.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4807.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4807" title: "Compiler Warning (level 1) C4807" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4807" +ms.date: 11/04/2016 f1_keywords: ["C4807"] helpviewer_keywords: ["C4807"] -ms.assetid: 089c9f87-fd81-402e-9826-66a8ef1ef1fe --- # Compiler Warning (level 1) C4807 -'operation' : unsafe mix of type 'type' and signed bitfield of type 'type' +> 'operation' : unsafe mix of type 'type' and signed bitfield of type 'type' + +## Remarks This warning is generated when comparing a one-bit signed bit field to a **`bool`** variable. Because a one-bit, signed bit field can only contain the values -1 or 0, it is dangerous to compare it to **`bool`**. No warnings are generated about mixing **`bool`** and one-bit, unsigned bitfields since they are identical to **`bool`** and can only hold 0 or 1. ## Example -The following sample generates C4807: +The following example generates C4807: ```cpp // C4807.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4810.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4810.md index 50bdb9be685..81d413dedb2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4810.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4810.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4810" title: "Compiler Warning (level 1) C4810" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4810" +ms.date: 11/04/2016 f1_keywords: ["C4810"] helpviewer_keywords: ["C4810"] -ms.assetid: 39e2cae0-9c1c-4ac1-aaa0-5f661d06085b --- # Compiler Warning (level 1) C4810 -value of pragma pack(show) == n +> value of pragma pack(show) == n + +## Remarks This warning is issued when you use the **show** option of the [pack](../../preprocessor/pack.md) pragma. *n* is the current pack value. +## Example + For example, the following code shows how the C4810 warning works with the pack pragma: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4811.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4811.md index 5a5797e5809..dc0f0521926 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4811.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4811.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4811" title: "Compiler Warning (level 1) C4811" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4811" +ms.date: 11/04/2016 f1_keywords: ["C4811"] helpviewer_keywords: ["C4811"] -ms.assetid: fbd79351-3dc1-45cf-b5b3-411f48c1590f --- # Compiler Warning (level 1) C4811 -value of pragma conform(forScope, show) == value +> value of pragma conform(forScope, show) == value + +## Remarks This warning is issued when you use the **show** option of the [conform](../../preprocessor/conform.md) pragma. *value* is the current conform value. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4812.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4812.md index 07221f45109..5c5d3d2394d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4812.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4812.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4812" title: "Compiler Warning (level 1) C4812" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4812" +ms.date: 11/04/2016 f1_keywords: ["C4812"] helpviewer_keywords: ["C4812"] -ms.assetid: a7f5721f-2019-44de-ad62-ed30bac8b1f3 --- # Compiler Warning (level 1) C4812 -obsolete declaration style: please use 'new_syntax' instead +> obsolete declaration style: please use 'new_syntax' instead + +## Remarks In the current release of Visual C++, the explicit constructor specialization is still supported, but it may not be supported in a future release. -The following sample generates C4812: +## Example + +The following example generates C4812: ```cpp // C4812.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4813.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4813.md index 532b62c42aa..a2d30e711ae 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4813.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4813.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4813" title: "Compiler Warning (level 1) C4813" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4813" +ms.date: 11/04/2016 f1_keywords: ["C4813"] helpviewer_keywords: ["C4813"] -ms.assetid: c30bf877-ab04-4fe4-897e-8162092426f0 --- # Compiler Warning (level 1) C4813 -'function' : a friend function of a local class must have been previously declared +> 'function' : a friend function of a local class must have been previously declared + +## Remarks A friend function in an inner class was not declared in the outer class. -The following sample generates C4813: +## Example + +The following example generates C4813: ```cpp // C4813.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4817.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4817.md index 1bd7d8b68af..9273163849b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4817.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4817.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4817" title: "Compiler Warning (level 1) C4817" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4817" +ms.date: 11/04/2016 f1_keywords: ["C4817"] helpviewer_keywords: ["C4817"] -ms.assetid: a68f5486-6940-4934-9f93-bfd4d71f92a9 --- # Compiler Warning (level 1) C4817 -'member' : illegal use of '.' to access this member; compiler replaced with '->' +> 'member' : illegal use of '.' to access this member; compiler replaced with '->' + +## Remarks The wrong member access operator was used. ## Example -The following sample generates C4817. +The following example generates C4817. ```cpp // C4817.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4819.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4819.md index 46f611babf6..a55bf43ca8c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4819.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4819.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4819" title: "Compiler Warning (level 1) C4819" -ms.date: "04/08/2019" +description: "Learn more about: Compiler Warning (level 1) C4819" +ms.date: 04/08/2019 f1_keywords: ["C4819"] helpviewer_keywords: ["C4819"] -ms.assetid: c0316e85-249c-414d-9df0-622d077c6bc2 --- # Compiler Warning (level 1) 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. +## Remarks + C4819 occurs when you compile an ANSI source file on a system using a codepage that can't represent all characters in the file. There are several ways to resolve C4819. One simple way is to remove the offending character, if you don't need it, for example, if it's in a comment. You can set the system codepage in the Control Panel to one that supports the character set used by your source code. You can use Unicode [escape sequences](../../c-language/escape-sequences.md) to create characters or strings that use only the basic ANSI character set in your source code. Finally, you can save the file in a Unicode format with a signature, also known as a byte-order mark (BOM). diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4821.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4821.md index 0cb5746cef3..fbd1d0e8f17 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4821.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4821.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4821" title: "Compiler Warning (level 1) C4821" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4821" +ms.date: 11/04/2016 f1_keywords: ["C4821"] helpviewer_keywords: ["C4821"] -ms.assetid: c7768e77-0ee5-491e-8aa4-3915bf5bcbdf --- # Compiler Warning (level 1) C4821 > Unable to determine Unicode encoding type, please save the file with signature (BOM) +## Remarks + The compiler could not determine the encoding type for a file. To resolve this warning, save the file with a byte order marker. See [Manage Files with Encoding](/sql/ssms/solution/manage-files-with-encoding) for more information. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md index 51968a971dc..47a396a2d93 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4822.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4822" title: "Compiler Warning (level 1) C4822" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4822" +ms.date: 11/04/2016 f1_keywords: ["C4822"] helpviewer_keywords: ["C4822"] -ms.assetid: 0f231a30-2eb0-4722-aaa0-e2d19d3e7eea --- # Compiler Warning (level 1) C4822 -'member' : local class member function does not have a body +> 'member' : local class member function does not have a body ## Remarks @@ -20,7 +19,7 @@ In Visual Studio 2019 and later, C4822 is an [off-by-default](../../preprocessor ## Example -The following sample generates C4822: +The following example generates C4822: ```cpp // C4822.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4829.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4829.md index 42a6d4cced6..7b3a1ffe750 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4829.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4829.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4829" title: "Compiler Warning (level 1) C4829" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4829" +ms.date: 11/04/2016 f1_keywords: ["C4829"] helpviewer_keywords: ["C4829"] -ms.assetid: 4ffabe2b-2ddc-4c52-8564-d1355c93cfa6 --- # Compiler Warning (level 1) C4829 -Possibly incorrect parameters to function main. Consider 'intmain(Platform::Array\^ argv)' +> Possibly incorrect parameters to function main. Consider 'intmain(Platform::Array\^ argv)' + +## Remarks Certain functions, such as main, cannot take reference type parameters. While compilation will succeed, the resulting image will probably not run. -The following sample generates C4829: +## Example + +The following example generates C4829: ```cpp // C4829.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4835.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4835.md index 220089e424e..f3b67e23a05 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4835.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4835.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4835" title: "Compiler Warning (level 1) C4835" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4835" +ms.date: 11/04/2016 f1_keywords: ["C4835"] helpviewer_keywords: ["C4835"] -ms.assetid: d2e44c62-7b0e-4a45-943d-97903e27ed9d --- # Compiler Warning (level 1) C4835 -'variable' : the initializer for exported data will not be run until managed code is first executed in the host assembly +> 'variable' : the initializer for exported data will not be run until managed code is first executed in the host assembly + +## Remarks When accessing data between managed components, it is recommended that you not use native C++ import and export mechanisms. Instead, declare your data members inside a managed type and reference the metadata with `#using` in the client. For more information, see [#using Directive](../../preprocessor/hash-using-directive-cpp.md). ## Examples -The following sample generates C4835. +The following example generates C4835. ```cpp // C4835.cpp @@ -26,7 +27,7 @@ __declspec(dllexport) int m = f(); // C4835 __declspec(dllexport) int *p = &n; // C4835 ``` -The following sample consumes the component built in the previous sample, showing that the value of the variables is not as expected. +The following example consumes the component built in the previous example, showing that the value of the variables is not as expected. ```cpp // C4835_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4838.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4838.md index 0c5faf751c8..ed58e4bc6ab 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4838.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4838.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4838" title: "Compiler Warning (level 1) C4838" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4838" +ms.date: 11/04/2016 f1_keywords: ["C4838"] helpviewer_keywords: ["C4838"] -ms.assetid: fea07924-5feb-4ed4-99b5-1a8c41d28db6 --- # Compiler Warning (level 1) C4838 -conversion from 'type_1' to 'type_2' requires a narrowing conversion +> conversion from 'type_1' to 'type_2' requires a narrowing conversion + +## Remarks An implicit narrowing conversion was found when using aggregate or list initialization. @@ -16,7 +17,9 @@ 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 warning message almost always indicates that 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 C4838 and shows one way to fix it: +## Example + +The following example generates C4838 and shows one way to fix it: ```cpp // C4838.cpp -- C++ narrowing conversion diagnostics diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4900.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4900.md index 7ab98d4f470..9d0a5cc4187 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4900.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4900.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4900" title: "Compiler Warning (level 1) C4900" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4900" +ms.date: 11/04/2016 f1_keywords: ["C4900"] helpviewer_keywords: ["C4900"] -ms.assetid: 826997ec-0803-4794-ad35-bb463f679658 --- # Compiler Warning (level 1) C4900 -intermediate language mismatch between 'tool1' version 'version1' and 'tool2' version 'version2' +> intermediate language mismatch between 'tool1' version 'version1' and 'tool2' version 'version2' + +## Remarks The intermediate language used in *tool1* and *tool2* did not match. Check that the most current version of each tool has been installed. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4905.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4905.md index c8dd24cadec..43a136c259d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4905.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4905.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4905" title: "Compiler Warning (level 1) C4905" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4905" +ms.date: 11/04/2016 f1_keywords: ["C4905"] helpviewer_keywords: ["C4905"] -ms.assetid: 40240bf4-b14e-4c22-aeb2-52f2851532f6 --- # Compiler Warning (level 1) C4905 -wide string literal cast to 'LPSTR' +> wide string literal cast to 'LPSTR' + +## Remarks The compiler detected an unsafe cast. The cast did succeed, but you should use a conversion routine. @@ -16,7 +17,7 @@ This warning is off by default. See [Compiler Warnings That Are Off by Default]( ## Example -The following sample generates C4905. +The following example generates C4905. ```cpp // C4905.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4906.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4906.md index 395fe28c5d5..8e2c92d2274 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4906.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4906.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4906" title: "Compiler Warning (level 1) C4906" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4906" +ms.date: 11/04/2016 f1_keywords: ["C4906"] helpviewer_keywords: ["C4906"] -ms.assetid: 05318e74-799b-412a-9dce-f02b8161d762 --- # Compiler Warning (level 1) C4906 -string literal cast to 'LPWSTR' +> string literal cast to 'LPWSTR' + +## Remarks The compiler detected an unsafe cast. The cast did succeed, but you should use a conversion routine. @@ -16,7 +17,7 @@ This warning is off by default. See [Compiler Warnings That Are Off by Default]( ## Example -The following sample generates C4906: +The following example generates C4906: ```cpp // C4906.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4910.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4910.md index b923b43d27e..588f5372c28 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4910.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4910.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4910" title: "Compiler Warning (level 1) C4910" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4910" +ms.date: 11/04/2016 f1_keywords: ["C4910"] helpviewer_keywords: ["C4910"] -ms.assetid: 67963560-fbca-4ca7-93db-06beaf7055f0 --- # Compiler Warning (level 1) C4910 -'\' : '__declspec(dllexport)' and 'extern' are incompatible on an explicit instantiation +> '\' : '__declspec(dllexport)' and 'extern' are incompatible on an explicit instantiation + +## Remarks The explicit template instantiation named *\* is modified by both the `__declspec(dllexport)` and **`extern`** keywords. However, these keywords are mutually exclusive. The `__declspec(dllexport)` keyword means instantiate the template class, while the **`extern`** keyword means do not automatically instantiate the template class. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4912.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4912.md index fbaf6ce0afc..1bfd258713c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4912.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4912.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4912" title: "Compiler Warning (level 1) C4912" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4912" +ms.date: 11/04/2016 f1_keywords: ["C4912"] helpviewer_keywords: ["C4912"] -ms.assetid: ba1f1a66-8c20-4792-9ac8-43e49f729ae2 --- # Compiler Warning (level 1) C4912 -'attribute': attribute has undefined behavior on a nested UDT +> 'attribute': attribute has undefined behavior on a nested UDT + +## Remarks Attributes that apply to nested UDTs (user-defined type, which could be a typedef, union, or struct) may be ignored. +## Example + The following code shows how this warning would be generated: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4917.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4917.md index e0be915a7cf..5174941c517 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4917.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4917.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4917" title: "Compiler Warning (level 1) C4917" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4917" +ms.date: 11/04/2016 f1_keywords: ["C4917"] helpviewer_keywords: ["C4917"] -ms.assetid: c05e2610-4a5d-4f4b-a99b-c15fd7f1d5f1 --- # Compiler Warning (level 1) C4917 -'declarator' : a GUID can only be associated with a class, interface or namespace +> 'declarator' : a GUID can only be associated with a class, interface or namespace + +## Remarks A user-defined structure other than [class](../../cpp/class-cpp.md), [interface](../../cpp/interface.md), or [namespace](../../cpp/namespaces-cpp.md) cannot have a GUID. @@ -16,7 +17,7 @@ This warning is off by default. See [Compiler Warnings That Are Off by Default]( ## Example -The following code sample generates C4917: +The following code example generates C4917: ```cpp // C4917.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4920.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4920.md index dc1fc90aba8..cd04ce20506 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4920.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4920.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4920" title: "Compiler Warning (level 1) C4920" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4920" +ms.date: 11/04/2016 f1_keywords: ["C4920"] helpviewer_keywords: ["C4920"] -ms.assetid: 1e501f2e-93c1-4d27-a4fa-54fc86271ae7 --- # Compiler Warning (level 1) C4920 -enum enum member member=value already seen in enum enum as member=value +> enum enum member member=value already seen in enum enum as member=value + +## Remarks If a .tlb that you pass to #import has the same symbol defined in two or more enums, this warning indicates that subsequent identical symbols are ignored and will be commented out in the .tlh file. +## Example + Assuming a .tlb that contains: ``` @@ -27,7 +30,7 @@ library MyLib }; ``` -the following samples generates C4920, +the following example generates C4920, ```cpp // C4920.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4925.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4925.md index fefc0eea093..70e1c27766b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4925.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4925.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4925" title: "Compiler Warning (level 1) C4925" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4925" +ms.date: 11/04/2016 f1_keywords: ["C4925"] helpviewer_keywords: ["C4925"] -ms.assetid: a4b206c0-016a-4f28-873a-bb8bb41bad50 --- # Compiler Warning (level 1) C4925 -'method': dispinterface method cannot be called from script +> 'method': dispinterface method cannot be called from script + +## Remarks Scripting languages cannot create a VT_BYREF 'in' parameter, it can only create VT_BYREF 'out' parameters. Another way to resolve this warning is not make the parameter (in the definition and implementation) a pointer type. -The following sample generates C4925: +## Example + +The following example generates C4925: ```cpp // C4925.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4926.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4926.md index e1b980f6b58..2ef1c363482 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4926.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4926.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4926" title: "Compiler Warning (level 1) C4926" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4926" +ms.date: 11/04/2016 f1_keywords: ["C4926"] helpviewer_keywords: ["C4926"] -ms.assetid: 5717fce0-146f-4ef2-bde0-e9a01c0922d1 --- # Compiler Warning (level 1) C4926 -'identifier': symbol is already defined: attributes ignored +> 'identifier': symbol is already defined: attributes ignored + +## Remarks A forward declaration was found but an attributed construct with the same name already exists. The attributes for the forward declaration are ignored. -The following sample generates C4926: +## Example + +The following example generates C4926: ```cpp // C4926.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4927.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4927.md index 1edc84ab0e3..97680f685f0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4927.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4927.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4927" title: "Compiler Warning (level 1) C4927" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4927" +ms.date: 11/04/2016 f1_keywords: ["C4927"] helpviewer_keywords: ["C4927"] -ms.assetid: 7009e740-a2ef-4130-96ba-482e092f717a --- # Compiler Warning (level 1) C4927 -illegal conversion; more than one user-defined conversion has been implicitly applied +> illegal conversion; more than one user-defined conversion has been implicitly applied + +## Remarks More than one user-defined conversion is implicitly applied to a single value -- the compiler did not find an explicit conversion but did find a conversion, which it used. -The following sample generates C4927: +## Example + +The following example generates C4927: ```cpp // C4927.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4928.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4928.md index 2842251ec40..7ad37a31713 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4928.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4928.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4928" title: "Compiler Warning (level 1) C4928" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4928" +ms.date: 11/04/2016 f1_keywords: ["C4928"] helpviewer_keywords: ["C4928"] -ms.assetid: 77235d7f-9360-45cb-8348-d148c605c4a3 --- # Compiler Warning (level 1) C4928 -illegal copy-initialization; more than one user-defined conversion has been implicitly applied +> illegal copy-initialization; more than one user-defined conversion has been implicitly applied + +## Remarks More than one user-defined conversion routine was found. The compiler executed the code in all such routines. 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. -The following sample generates C4928: +## Example + +The following example generates C4928: ```cpp // C4928.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4929.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4929.md index 96e3168e904..0914856a997 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4929.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4929.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4929" title: "Compiler Warning (level 1) C4929" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4929" +ms.date: 11/04/2016 f1_keywords: ["C4929"] helpviewer_keywords: ["C4929"] -ms.assetid: 95f8ab4f-4468-4caa-acd5-8f4592f03b3c --- # Compiler Warning (level 1) C4929 -'file': typelibrary contains a union; ignoring the 'embedded_idl' qualifier +> 'file': typelibrary contains a union; ignoring the 'embedded_idl' qualifier + +## Remarks The embedded_idl attribute of [#import](../../preprocessor/hash-import-directive-cpp.md) could not be applied to the type library because a union is present in the type library. To resolve this warning, don't use embedded_idl. -## Examples +## Example -The following sample defines a component. +The following example defines a component. ```cpp // C4929a.cpp @@ -46,7 +47,7 @@ struct C : I { }; ``` -The following sample generates C4929. +The following example generates C4929. ```cpp // C4929b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4930.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4930.md index 7d708e9b826..261fff84ad3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4930.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4930.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4930" title: "Compiler Warning (level 1) C4930" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4930" +ms.date: 11/04/2016 f1_keywords: ["C4930"] helpviewer_keywords: ["C4930"] -ms.assetid: 89a206c9-c536-4186-8e81-1cde3e7f4f5b --- # Compiler Warning (level 1) C4930 -'prototype': prototyped function not called (was a variable definition intended?) +> 'prototype': prototyped function not called (was a variable definition intended?) + +## Remarks The compiler detected an unused function prototype. If the prototype was intended as a variable declaration, remove the open/close parentheses. -The following sample generates C4930: +## Examples + +The following example generates C4930: ```cpp // C4930.cpp @@ -34,7 +37,7 @@ int main() { C4930 can also occur when the compiler cannot distinguish between a function prototype declaration and a function call. -The following sample generates C4930: +The following example generates C4930: ```cpp // C4930b.cpp @@ -105,4 +108,4 @@ int main() } ``` -In the above sample, the result of a method that takes zero arguments is passed as an argument to the constructor of an unnamed local class variable. The call can be disambiguated by either naming the local variable or prefixing the method call with an object instance along with the appropriate pointer-to-member operator. +In the above example, the result of a method that takes zero arguments is passed as an argument to the constructor of an unnamed local class variable. The call can be disambiguated by either naming the local variable or prefixing the method call with an object instance along with the appropriate pointer-to-member operator. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4935.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4935.md index 09fadd7e4d9..a37cde7e6c5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4935.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4935.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4935" title: "Compiler Warning (level 1) C4935" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4935" +ms.date: 11/04/2016 f1_keywords: ["C4935"] helpviewer_keywords: ["C4935"] -ms.assetid: a36c56d3-571a-44dd-bb0f-bcc6b020e134 --- # Compiler Warning (level 1) C4935 -assembly access specifier modified from 'access' +> assembly access specifier modified from 'access' + +## Remarks The assembly visibility of a type was modified. The compiler uses the last specifier that it encounters. For example, the assembly visibility of a forward declaration may be different from the assembly visibility of the class definition. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4939.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4939.md index 97fffd379e0..4568b2300b1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4939.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4939.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4939" title: "Compiler Warning (level 1) C4939" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4939" +ms.date: 11/04/2016 f1_keywords: ["C4939"] helpviewer_keywords: ["C4939"] -ms.assetid: 07096008-ba47-436c-a84c-2b03ad90d0b3 --- # Compiler Warning (level 1) C4939 -\#pragma vtordisp is deprecated and will be removed in a future release of Visual C++ +> #pragma vtordisp is deprecated and will be removed in a future release of Visual C++ + +## Remarks The [vtordisp](../../preprocessor/vtordisp.md) pragma will be removed in a future release of Visual C++. ## Example -The following sample generates C4939. +The following example generates C4939. ```cpp // C4939.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4944.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4944.md index ab27de2d54f..6d314e924af 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4944.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4944.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4944" title: "Compiler Warning (level 1) C4944" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4944" +ms.date: 11/04/2016 f1_keywords: ["C4944"] helpviewer_keywords: ["C4944"] -ms.assetid: e2905eb1-2e3b-4fab-a48b-c0cae0fd997f --- # Compiler Warning (level 1) C4944 -'symbol' : cannot import symbol from 'assembly1': as 'symbol' already exists in the current scope +> 'symbol' : cannot import symbol from 'assembly1': as 'symbol' already exists in the current scope + +## Remarks A symbol was defined in a source code file and then a #using statement referenced an assembly that also defined the symbol. The symbol in the assembly is ignored. -## Examples +## Example -The following sample creates a component with a type called ClassA. +The following example creates a component with a type called ClassA. ```csharp // C4944.cs @@ -25,7 +26,7 @@ public class ClassA { } ``` -The following samples generate C4944. +The following example generate C4944. ```cpp // C4944b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4945.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4945.md index 501700a2582..8b96288228f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4945.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4945.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4945" title: "Compiler Warning (level 1) C4945" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4945" +ms.date: 11/04/2016 f1_keywords: ["C4945"] helpviewer_keywords: ["C4945"] -ms.assetid: 6d2079ea-dc59-4611-bc68-9a22c06f7587 --- # Compiler Warning (level 1) C4945 -'symbol' : cannot import symbol from 'assembly2': as 'symbol' has already been imported from another assembly 'assembly1' +> 'symbol' : cannot import symbol from 'assembly2': as 'symbol' has already been imported from another assembly 'assembly1' + +## Remarks A symbol was imported from a referenced assembly but that symbol was already imported from another referenced assembly. Either do not reference one of the assemblies or get the symbol name changed in one of the assemblies. -The following samples generate C4945. +## Example + +The following example generate C4945. ```csharp // C4945a.cs diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4946.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4946.md index 2ef397abc1c..284b2424ac7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4946.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4946.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4946" title: "Compiler Warning (level 1) C4946" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4946" +ms.date: 11/04/2016 f1_keywords: ["C4946"] helpviewer_keywords: ["C4946"] -ms.assetid: b85cbef0-e053-4de6-9b14-7b0f82d40495 --- # Compiler Warning (level 1) C4946 -reinterpret_cast used between related classes: 'class1' and 'class2' +> reinterpret_cast used between related classes: 'class1' and 'class2' + +## Remarks Do not use [reinterpret_cast](../../cpp/reinterpret-cast-operator.md) to cast between related types. Use [static_cast](../../cpp/static-cast-operator.md) instead, or for polymorphic types, use [dynamic_cast](../../cpp/dynamic-cast-operator.md). By default, this warning is off. For more information, see [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). +## Example + The following code example generates C4946: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4947.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4947.md index 84cfafa4c9c..db09f0cf6ad 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4947.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4947.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4947" title: "Compiler Warning (level 1) C4947" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4947" +ms.date: 11/04/2016 f1_keywords: ["C4947"] helpviewer_keywords: ["C4947"] -ms.assetid: 5a1d484e-b4c7-4de2-a145-d8dcfc2fc1d2 --- # Compiler Warning (level 1) C4947 -'type_or_member' : marked as obsolete +> 'type_or_member' : marked as obsolete + +## Remarks A member or type was marked as obsolete with the class. ## Example -The following sample generates C4947: +The following example generates C4947: ```cpp // C4947.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4951.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4951.md index ed00316f198..a9b0be26170 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4951.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4951.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4951" title: "Compiler Warning (level 1) C4951" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4951" +ms.date: 08/27/2018 f1_keywords: ["C4951"] helpviewer_keywords: ["C4951"] -ms.assetid: 669d8bb7-5efa-4ba9-99db-4e65addbf054 --- # Compiler Warning (level 1) C4951 > '*function*' has been edited since profile data was collected, function profile data not used +## Remarks + A function has been edited in an input module to [/LTCG:PGUPDATE](../../build/reference/ltcg-link-time-code-generation.md), so that the profile data is now not valid. The input module was recompiled after **/LTCG:PGINSTRUMENT** and has a function (*function*) with a different flow of control than was in the module at the time of the **/LTCG:PGINSTRUMENT** operation. This warning is informational. To resolve this warning, run **/LTCG:PGINSTRUMENT**, redo all test runs, and run **/LTCG:PGOPTIMIZE**. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4952.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4952.md index 5ad02204e02..fbf7a1a79f8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4952.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4952.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4952" title: "Compiler Warning (level 1) C4952" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4952" +ms.date: 08/27/2018 f1_keywords: ["C4952"] helpviewer_keywords: ["C4952"] -ms.assetid: 593324f0-5cfe-42fb-b221-2f71308765dd --- # Compiler Warning (level 1) C4952 > '*function*' : no profile data found in program database '*pgd_file*' +## Remarks + When using [/LTCG:PGUPDATE](../../build/reference/ltcg-link-time-code-generation.md), the compiler detected an input module that was recompiled after `/LTCG:PGINSTRUMENT` and has a new function (*function*) present. This warning is informational. To resolve this warning, run `/LTCG:PGINSTRUMENT`, redo all test runs, and run `/LTCG:PGOPTIMIZE`. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4953.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4953.md index 4f6f49e7184..4fb025030e8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4953.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4953.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4953" title: "Compiler Warning (level 1) C4953" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 1) C4953" +ms.date: 08/27/2018 f1_keywords: ["C4953"] helpviewer_keywords: ["C4953"] -ms.assetid: 3c4f6ac6-3976-41ab-8a27-3c41d7472ea7 --- # Compiler Warning (level 1) C4953 > Inlinee '*function*' has been edited since profile data was collected, profile data not used +## Remarks + When using [/LTCG:PGUPDATE](../../build/reference/ltcg-link-time-code-generation.md), the compiler detected an input module that was recompiled after `/LTCG:PGINSTRUMENT` and has a function (*function*) that was edited and where existing test runs identified the function as a candidate for inlining. However, as a result of recompiling the module, the function will no longer be a candidate for inlining. This warning is informational. To resolve this warning, run `/LTCG:PGINSTRUMENT`, redo all test runs, and run `/LTCG:PGOPTIMIZE`. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4964.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4964.md index e97a33d9184..9eb7097fa26 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4964.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4964.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4964" title: "Compiler Warning (level 1) C4964" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4964" +ms.date: 11/04/2016 f1_keywords: ["C4964"] helpviewer_keywords: ["C4964"] -ms.assetid: b89c9274-8a92-4b7c-aa30-3fbb1b68ac73 --- # Compiler Warning (level 1) C4964 -No optimization options were specified; profile info will not be collected +> No optimization options were specified; profile info will not be collected + +## Remarks [/GL](../../build/reference/gl-whole-program-optimization.md) and [/LTCG](../../build/reference/ltcg-link-time-code-generation.md) were specified, but no optimizations were requested, so no .pgc files will be generated and, therefore, no profile-guided optimizations will be possible. If you want .pgc files to be generated when you run your application, specify one of the [/O](../../build/reference/o-options-optimize-code.md) compiler options. -The following sample generates C4964: +## Example + +The following example generates C4964: ```cpp // C4964.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4965.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4965.md index b7f9f1365af..384ae158bc3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4965.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4965.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4965" title: "Compiler Warning (level 1) C4965" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4965" +ms.date: 11/04/2016 f1_keywords: ["C4965"] helpviewer_keywords: ["C4965"] -ms.assetid: 47f3f6dc-459b-4a25-9947-f394c8966cb5 --- # Compiler Warning (level 1) C4965 -implicit box of integer 0; use nullptr or explicit cast +> implicit box of integer 0; use nullptr or explicit cast + +## Remarks Visual C++ features implicit boxing of value types. An instruction that resulted in a null assignment using Managed Extensions for C++ now becomes an assignment to a boxed int. @@ -16,7 +17,7 @@ For more information, see [Boxing](../../extensions/boxing-cpp-component-extensi ## Example -The following sample generates C4965. +The following example generates C4965. ```cpp // C4965.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4997.md b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4997.md index 22694be7d30..2741b6f61ef 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4997.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-1-c4997.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 1) C4997" title: "Compiler Warning (level 1) C4997" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 1) C4997" +ms.date: 11/04/2016 f1_keywords: ["C4997"] helpviewer_keywords: ["C4997"] -ms.assetid: d39678fd-0c1a-4104-8a45-9e3f20de0407 --- # Compiler Warning (level 1) C4997 -'class': coclass does not implement a COM interface or pseudo-interface +> 'class': coclass does not implement a COM interface or pseudo-interface + +## Remarks A class marked with the [coclass](../../windows/attributes/coclass.md) attribute did not implement an interface. -The following sample generates C4997: +## Example + +The following example generates C4997: ```cpp // C4997.cpp 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 d1add86f498..00000000000 --- 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 7b38ae77bb2..b9e5c6c8da4 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,14 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4007" -title: "Compiler Warning (level 2) C4007" -ms.date: "11/04/2016" +title: "Compiler Warning (level 3) C4007" +description: "Learn more about: 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. +## Remarks + +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-c4051.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4051.md index d512d8c5c57..8d405b80739 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4051.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4051.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4051" title: "Compiler Warning (level 2) C4051" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4051" +ms.date: 11/04/2016 f1_keywords: ["C4051"] helpviewer_keywords: ["C4051"] -ms.assetid: 8c964e70-df12-45ff-93b9-496ad4271191 --- # Compiler Warning (level 2) C4051 -type conversion; possible loss of data +> type conversion; possible loss of data + +## Remarks An expression contains two data items with different base types. Converting one type causes the data item to be truncated. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4056.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4056.md index e619ad2ebb1..f327965b82d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4056.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4056.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4056" title: "Compiler Warning (level 2) C4056" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4056" +ms.date: 11/04/2016 f1_keywords: ["C4056"] helpviewer_keywords: ["C4056"] -ms.assetid: a3c3a9b8-ec30-452d-96cb-3694adcce789 --- # Compiler Warning (level 2) C4056 -overflow in floating point constant arithmetic +> overflow in floating point constant arithmetic + +## Remarks Floating-point constant arithmetic generates a result that exceeds the maximum allowable value. This warning can be caused by compiler optimizations performed during constant arithmetic. You can safely ignore this warning if it goes away when you turn off optimization ([/Od](../../build/reference/od-disable-debug.md)). -The following sample generates C4056: +## Example + +The following example generates C4056: ```cpp // C4056.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4094.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4094.md index fe8f42e4001..aa4ef8419c3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4094.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4094.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4094" title: "Compiler Warning (level 2) C4094" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4094" +ms.date: 11/04/2016 f1_keywords: ["C4094"] helpviewer_keywords: ["C4094"] -ms.assetid: e68929fb-3a1c-4be7-920b-d5f79f534f99 --- # Compiler Warning (level 2) C4094 -untagged 'token' declared no symbols +> untagged 'token' declared no symbols + +## Remarks The compiler detected an empty declaration using an untagged structure, union, or class. The declaration is ignored. ## Example +The following example generates C4094: + ```cpp // C4094.cpp // compile with: /W2 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 40fd5f19018..1739a47480f 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,24 +1,25 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4099" title: "Compiler Warning (level 2) C4099" -ms.date: "11/04/2016" +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*' + +## Remarks 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. ## Example -The following sample generates C4099. +The following example generates C4099. ```cpp // 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 146880f2530..42ff1e16f22 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4146.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4146.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler warning (level 2) C4146" title: "Compiler warning (level 2) C4146" -ms.date: 11/18/2021 +description: "Learn more about: Compiler warning (level 2) C4146" +ms.date: 04/22/2025 f1_keywords: ["C4146"] helpviewer_keywords: ["C4146"] --- @@ -9,25 +9,26 @@ 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. - ## 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. +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. -This warning often occurs when you try to express the minimum **`int`** value, -2147483648, or the minimum **`long long`** value, -9223372036854775808. These values can't be written as -2147483648 or -9223372036854775808ll, respectively. That's because the compiler processes the expression in two stages: first, it parses the numeric value, then it applies the negation operator. For example, when the compiler parses -2147483648, it follows these steps: +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. -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`**. +This warning often occurs when you try to express the minimum **`int`** value, -2147483648, or the minimum **`long long`** value, -9223372036854775808. These values can't be written as -2147483648 or -9223372036854775808ll. The reason is because the compiler processes the expression in two stages: first, it parses the numeric value, then it applies the negation operator. For example, when the compiler parses -2147483648, it follows these steps: +1. The number 2147483648 is evaluated. Because it's greater than the maximum **`int`** value of 2147483647, but still fits in an **`unsigned int`**, the type of 2147483648 is **`unsigned int`**. 1. Unary minus is applied to the unsigned value, with an unsigned result, which also happens to be 2147483648. The unsigned type of the result can cause unexpected behavior. If the result is used in a comparison, then an unsigned comparison might be used, for example, when the other operand is an **`int`**. -You can avoid C4146 by using `INT_MIN` or `LLONG_MIN` from *``* or the C++ equivalent, *``*. These values have signed types. +You can avoid **C4146** by using `INT_MIN` or `LLONG_MIN` from *``* or the C++ equivalent, *``*. These values have signed types. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example -The following sample demonstrates the unexpected behavior that can happen when the compiler generates warning C4146: +The following example demonstrates the unexpected behavior that can happen when the compiler generates warning C4146: ```cpp // C4146.cpp 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 1d141e54d15..4e373271a61 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,85 @@ --- +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. +## Remarks -The following sample generates C4150: +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`. + +## Example + +The following example 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-c4156.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4156.md index c2b9d9baa66..c72e3d2f1da 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4156.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4156.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4156" title: "Compiler Warning (level 2) C4156" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4156" +ms.date: 11/04/2016 f1_keywords: ["C4156"] helpviewer_keywords: ["C4156"] -ms.assetid: 9adf3acb-c0fe-42a8-a4db-5822b1493f77 --- # Compiler Warning (level 2) C4156 -deletion of an array expression without using the array form of 'delete'; array form substituted +> deletion of an array expression without using the array form of 'delete'; array form substituted + +## Remarks The non-array form of **`delete`** cannot delete an array. The compiler translated **`delete`** to the array form. @@ -16,6 +17,8 @@ This warning occurs only under Microsoft extensions (/Ze). ## Example +The following example generates C4156: + ```cpp // C4156.cpp // compile with: /W2 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4244.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4244.md index f1b15944392..e2c76f5572e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4244.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4244.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4244" title: "Compiler Warning (level 2) C4244" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4244" +ms.date: 11/04/2016 f1_keywords: ["C4244"] helpviewer_keywords: ["C4244"] -ms.assetid: 2c19d157-21d1-42c2-a6c0-3f30f2ce3813 --- # Compiler Warning (level 2) C4244 -'argument' : conversion from 'type1' to 'type2', possible loss of data +> 'argument' : conversion from 'type1' to 'type2', possible loss of data + +## Remarks A floating point type was converted to an integer type. A possible loss of data may have occurred. @@ -18,7 +19,7 @@ C4244 can also fire at level 3, and 4; see [Compiler Warning (levels 3 and 4) C4 ## Example -The following sample generates C4244: +The following example generates C4244: ```cpp // C4244_level2.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4250.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4250.md index 3ec69fa0134..b42f61f058e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4250.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4250.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4250" title: "Compiler Warning (level 2) C4250" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4250" +ms.date: 11/04/2016 f1_keywords: ["C4250"] helpviewer_keywords: ["C4250"] -ms.assetid: d47f7249-6b5a-414b-b2d4-56e5d246a782 --- # Compiler Warning (level 2) C4250 -'class1' : inherits 'class2::member' via dominance +> 'class1' : inherits 'class2::member' via dominance + +## Remarks Two or more members have the same name. The one in `class2` is inherited because it is a base class for the other classes that contained this member. @@ -18,6 +19,8 @@ Because a virtual base class is shared among multiple derived classes, a name in ## Examples +The following example generates C4250: + ```cpp // C4250.cpp // compile with: /c /W2 @@ -40,7 +43,7 @@ int main() { } ``` -The following sample generates C4250. +The following example generates C4250. ```cpp // C4250_b.cpp @@ -71,7 +74,7 @@ int main() { } ``` -This sample shows a more complex situation. The following sample generates C4250. +This example shows a more complex situation. The following example generates C4250. ```cpp // C4250_c.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4275.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4275.md index cd48f23132a..1488b7a2b6d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4275.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4275.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4275" title: "Compiler Warning (level 2) C4275" -ms.date: "02/08/2019" +description: "Learn more about: Compiler Warning (level 2) C4275" +ms.date: 02/08/2019 f1_keywords: ["C4275"] helpviewer_keywords: ["C4275"] -ms.assetid: 18de967a-0a44-4dbc-a2e8-fc4c067ba909 --- # Compiler Warning (level 2) C4275 > non - DLL-interface class '*class_1*' used as base for DLL-interface class '*class_2*' +## Remarks + An exported class was derived from a class that wasn't exported. To minimize the possibility of data corruption when exporting a class with [__declspec(dllexport)](../../cpp/dllexport-dllimport.md), make sure that: @@ -28,6 +29,10 @@ You can avoid exporting classes by defining a DLL that defines a class with virt C4275 can be ignored in Visual C++ if you are deriving from a type in the C++ Standard Library, compiling a debug release (**/MTd**) and where the compiler error message refers to `_Container_base`. +## Example + +The following example generates C4275: + ```cpp // C4275.cpp // compile with: /EHsc /MTd /W2 /c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4285.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4285.md index 7b65391add0..dec38cac563 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4285.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4285.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4285" title: "Compiler Warning (level 2) C4285" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4285" +ms.date: 11/04/2016 f1_keywords: ["C4285"] helpviewer_keywords: ["C4285"] -ms.assetid: fa14de1f-fc19-4eec-8bea-81003636e12f --- # Compiler Warning (level 2) C4285 -return type for 'identifier::operator ->' is recursive if applied using infix notation +> return type for 'identifier::operator ->' is recursive if applied using infix notation + +## Remarks The specified **operator->()** function cannot return the type for which it is defined or a reference to the type for which it is defined. -The following sample generates C4285: +## Example + +The following example generates C4285: ```cpp // C4285.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4302.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4302.md index 92c0d2d4556..9631ebfbff3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4302.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4302.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4302" title: "Compiler Warning (level 2) C4302" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4302" +ms.date: 11/04/2016 f1_keywords: ["C4302"] helpviewer_keywords: ["C4302"] -ms.assetid: f5e1c939-e134-4cca-ba1e-9b15a81549ae --- # Compiler Warning (level 2) C4302 -'conversion' : truncation from 'type 1' to 'type 2' +> 'conversion' : truncation from 'type 1' to 'type 2' + +## Remarks The compiler detected a conversion from a larger type to a smaller type. Information may be lost. 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. -The following sample generates C4302: +## Example + +The following example generates C4302: ```cpp // C4302.cpp 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 0bfaf972729..8dffb8c1508 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 @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4307" title: "Compiler Warning (level 2) C4307" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4307" +ms.date: 11/04/2016 f1_keywords: ["C4307"] helpviewer_keywords: ["C4307"] -ms.assetid: 7cca11e9-be61-49e4-8b15-88b84f0cbf07 --- # Compiler Warning (level 2) C4307 -'operator' : integral constant overflow +> 'operator' : signed integral constant overflow + +## Remarks 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. -The following sample generates C4307: +## Example + +The following example generates C4307: ```cpp // C4307.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md index 65171067b59..10ca720e0fa 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4308.md @@ -1,19 +1,24 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4308" title: "Compiler Warning (level 2) C4308" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4308" +ms.date: 08/30/2022 f1_keywords: ["C4308"] helpviewer_keywords: ["C4308"] -ms.assetid: d4e5c53c-71b2-4bbc-8a7c-3a2a3180d9d9 --- # Compiler Warning (level 2) C4308 -negative integral constant converted to unsigned type +> negative integral constant converted to unsigned type + +## Remarks An expression converts a negative integer constant to an unsigned type. The result of the expression is probably meaningless. +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. + ## Example +The following example generates C4308: + ```cpp // C4308.cpp // compile with: /W2 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4309.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4309.md index 5ae796582c4..fecac92eab3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4309.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4309.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4309" title: "Compiler Warning (level 2) C4309" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4309" +ms.date: 11/04/2016 f1_keywords: ["C4309"] helpviewer_keywords: ["C4309"] -ms.assetid: cb3f41ef-fd8a-4def-baa1-924e751fca68 --- # Compiler Warning (level 2) C4309 -'conversion' : truncation of constant value +> 'conversion' : truncation of constant value + +## Remarks The type conversion causes a constant to exceed the space allocated for it. You may need to use a larger type for the constant. -The following sample generates C4309: +## Example + +The following example generates C4309: ```cpp // C4309.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4356.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4356.md index 9134afc4376..1b77d903071 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4356.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4356.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4356" title: "Compiler Warning (level 2) C4356" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4356" +ms.date: 11/04/2016 f1_keywords: ["C4356"] helpviewer_keywords: ["C4356"] -ms.assetid: 3af3defe-de33-43b6-bd6c-2c2e09e34f3f --- # Compiler Warning (level 2) C4356 -'member' : static data member cannot be initialized via derived class +> 'member' : static data member cannot be initialized via derived class + +## Remarks The initialization of a static data member was ill formed. The compiler accepted the initialization. To avoid the warning, initialize the member through the base class. Use the [warning](../../preprocessor/warning.md) pragma to suppress this warning. -The following sample generates C4356: +## Example + +The following example generates C4356: ```cpp // C4356.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4396.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4396.md index e4306463bc4..5bb56d3be8f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4396.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4396.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4396" title: "Compiler Warning (level 2) C4396" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4396" +ms.date: 11/04/2016 f1_keywords: ["C4396"] helpviewer_keywords: ["C4396"] -ms.assetid: 7cd6b283-db17-4574-b299-03e0b913ad70 --- # Compiler Warning (level 2) C4396 -"name" : the inline specifier cannot be used when a friend declaration refers to a specialization of a function template +> "name" : the inline specifier cannot be used when a friend declaration refers to a specialization of a function template + +## Remarks A specialization of a function template cannot specify any of the [inline](../../cpp/inline-functions-cpp.md) specifiers. The compiler issues warning C4396 and ignores the inline specifier. 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 2c6d5bb4fa7..a8072422312 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" +title: "Compiler warning (level 2, off) C4412" +description: "Learn more about: 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 -The following sample generates C4412. +The following example 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 example 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 example 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 example generates C4412 and throws an exception at runtime: ```cpp // C4412_3.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4653.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4653.md index f731d8824bb..45fc49654bb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4653.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4653.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4653" title: "Compiler Warning (level 2) C4653" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4653" +ms.date: 11/04/2016 f1_keywords: ["C4653"] helpviewer_keywords: ["C4653"] -ms.assetid: 90ec3317-3d39-4b4c-bcd1-97e7c799e1b6 --- # Compiler Warning (level 2) C4653 -compiler option 'option' inconsistent with precompiled header; current command-line option ignored +> compiler option 'option' inconsistent with precompiled header; current command-line option ignored + +## Remarks An option specified with the Use Precompiled Headers ([/Yu](../../build/reference/yu-use-precompiled-header-file.md)) option was inconsistent with the options specified when the precompiled header was created. This compilation used the option specified when the precompiled header was created. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4756.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4756.md index 41c25723109..1e61db8e9b8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4756.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4756.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4756" title: "Compiler Warning (level 2) C4756" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4756" +ms.date: 11/04/2016 f1_keywords: ["C4756"] helpviewer_keywords: ["C4756"] -ms.assetid: 5a16df83-6b82-4619-83bd-319af4ef1d1d --- # Compiler Warning (level 2) C4756 -overflow in constant arithmetic +> overflow in constant arithmetic + +## Remarks The compiler generated an exception while doing constant arithmetic during compilation. -The following sample generates C4756: +## Example + +The following example generates C4756: ```cpp // C4756.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4948.md b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4948.md index 26347529fbf..0fb05310069 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4948.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-2-c4948.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 2) C4948" title: "Compiler Warning (level 2) C4948" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 2) C4948" +ms.date: 11/04/2016 f1_keywords: ["C4948"] helpviewer_keywords: ["C4948"] -ms.assetid: d006cb17-754a-4c70-ba7f-c3200e2cd8fa --- # Compiler Warning (level 2) C4948 -return type of 'accessor' does not match the last parameter type of the corresponding setter +> return type of 'accessor' does not match the last parameter type of the corresponding setter + +## Remarks The compiler found a mismatch between what data type is being get and set for an indexed property. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4013.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4013.md index 599a4caf8d4..d31e60b7584 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4013.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4013.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4013" title: "Compiler Warning (level 3) C4013" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4013" +ms.date: 11/04/2016 f1_keywords: ["C4013"] helpviewer_keywords: ["C4013"] -ms.assetid: 9f9afc71-6e78-463d-9d66-3012d6a3cd5d --- # Compiler Warning (level 3) C4013 -'function' undefined; assuming extern returning int +> 'function' undefined; assuming extern returning int + +## Remarks The compiler encountered a call to an undefined function. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4018.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4018.md index 9dd5d2ec50a..83dab0c48c0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4018.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4018.md @@ -9,15 +9,15 @@ helpviewer_keywords: ["C4018"] > '*token*' : signed/unsigned mismatch -Using the *token* operator to compare **`signed`** and **`unsigned`** numbers required the compiler to convert the **`signed`** value to **`unsigned`**. - ## Remarks +Using the *token* operator to compare **`signed`** and **`unsigned`** numbers required the compiler to convert the **`signed`** value to **`unsigned`**. + One way to fix this warning is if you cast one of the two types when you compare **`signed`** and **`unsigned`** types. ## Example -This sample generates C4018 and shows how to fix it: +This example generates C4018 and shows how to fix it: ```cpp // C4018.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4023.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4023.md index af8177c4fa2..f11f88a5ed2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4023.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4023.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4023" title: "Compiler Warning (level 3) C4023" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4023" +ms.date: 11/04/2016 f1_keywords: ["C4023"] helpviewer_keywords: ["C4023"] -ms.assetid: 615d5374-d7c1-42eb-acfd-917c053270c8 --- # Compiler Warning (level 3) C4023 -'symbol' : based pointer passed to unprototyped function : parameter number +> 'symbol' : based pointer passed to unprototyped function : parameter number + +## Remarks Passing a based pointer to an unprototyped function causes the pointer to be normalized, with unpredictable results. 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 509d435b2fd..3fcd48bfc7d 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,35 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4066" title: "Compiler Warning (level 3) C4066" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4066" +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 +> characters beyond first in wide-character constant ignored + +## Remarks The compiler processes only the first character of a wide-character constant. + +## Example + +The following example generates C4066: + +```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-c4073.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4073.md index 18ebb50854c..eb4beeba089 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4073.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4073.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4073" title: "Compiler Warning (level 3) C4073" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4073" +ms.date: 11/04/2016 f1_keywords: ["C4073"] helpviewer_keywords: ["C4073"] -ms.assetid: 50081a6e-6acd-45ff-8484-9b1ea926cc5c --- # Compiler Warning (level 3) C4073 -initializers put in library initialization area +> initializers put in library initialization area + +## Remarks + +Only third-party library developers should use the library initialization area, which is specified by [#pragma init_seg](../../preprocessor/init-seg.md). + +## Example -Only third-party library developers should use the library initialization area, which is specified by [#pragma init_seg](../../preprocessor/init-seg.md). The following sample generates C4073: +The following example generates C4073: ```cpp // C4073.cpp 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 8044b98d738..bf61764db50 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,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4101" -title: "Compiler Warning (level 3) C4101" -ms.date: "11/04/2016" +title: "Compiler Warning (level 3 and level 4) C4101" +description: "Learn more about: 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: +## Remarks + +The local variable is never used. + +## Examples + +This warning occurs in the obvious situation: ```cpp // C4101a.cpp @@ -20,7 +25,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 +44,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-c4102.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4102.md index 379c3a7b12b..63b13fa15f5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4102.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4102.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4102" title: "Compiler Warning (level 3) C4102" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4102" +ms.date: 11/04/2016 f1_keywords: ["C4102"] helpviewer_keywords: ["C4102"] -ms.assetid: 349f308a-daf3-48c6-bd53-6c38b73f8880 --- # Compiler Warning (level 3) C4102 -'label' : unreferenced label +> 'label' : unreferenced label + +## Remarks The label is defined but never referenced. The compiler ignores the label. -The following sample generates C4102: +## Example + +The following example generates C4102: ```cpp // C4102.cpp 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 77a80d13263..adfd70c3826 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,16 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4133" -title: "Compiler Warning (level 3) C4133" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1 and level 3) C4133" +description: "Learn more about: 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. +## Remarks + +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-c4159.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4159.md index 6f6a163564f..74670b18999 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4159.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4159.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4159" title: "Compiler Warning (level 3) C4159" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4159" +ms.date: 11/04/2016 f1_keywords: ["C4159"] helpviewer_keywords: ["C4159"] -ms.assetid: e2cf964e-f4b8-4b2c-9569-1abb94307232 --- # Compiler Warning (level 3) C4159 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4161.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4161.md index c38bf184951..672a08b13f6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4161.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4161.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4161" title: "Compiler Warning (level 3) C4161" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 3) C4161" +ms.date: 08/27/2018 f1_keywords: ["C4161"] helpviewer_keywords: ["C4161"] -ms.assetid: 03d3be61-83f1-4009-8310-8758ab67055f --- # Compiler Warning (level 3) C4161 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 a0bdee8047a..db68e28e735 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,15 @@ --- -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 + +## Remarks Several operations involving function pointers are considered unsafe: @@ -18,17 +19,19 @@ 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). + +## Example -The following sample generates C4191: +The following example generates C4191: ```cpp // C4191.cpp @@ -47,5 +50,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-c4192.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4192.md index 83450512bc4..c02e74aba58 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4192.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4192.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4192" title: "Compiler Warning (level 3) C4192" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4192" +ms.date: 11/04/2016 f1_keywords: ["C4192"] helpviewer_keywords: ["C4192"] -ms.assetid: ea5f91fa-8c96-4f3f-ac42-0c8a86d4e5df --- # Compiler Warning (level 3) C4192 -automatically excluding 'name' while importing type library 'library' +> automatically excluding 'name' while importing type library 'library' + +## Remarks A `#import` library contains an item, *name*, that is also defined in the Win32 system headers. Due to limitations of type libraries, names such as **IUnknown** or GUID are often defined in a type library, duplicating the definition from the system headers. `#import` will detect these items and refuse to incorporate them in the .tlh and .tli header files. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4197.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4197.md index d6fb5bfb8b8..4fabcf299da 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4197.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4197.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4197" title: "Compiler Warning (level 3) C4197" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4197" +ms.date: 11/04/2016 f1_keywords: ["C4197"] helpviewer_keywords: ["C4197"] -ms.assetid: f766feef-82b0-4d81-8a65-33628c7db196 --- # Compiler Warning (level 3) C4197 -'type' : top-level volatile in cast is ignored +> 'type' : top-level volatile in cast is ignored + +## Remarks The compiler detected a cast to an r-value type which is qualified with [volatile](../../cpp/volatile-cpp.md), or a cast of an r-value type to some type that is qualified with volatile. According to the C standard (6.5.3), properties associated with qualified types are meaningful only for l-value expressions. -The following sample generates C4197: +## Example + +The following example generates C4197: ```cpp // C4197.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4240.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4240.md index 66fc798b058..529f6f70f31 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4240.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4240.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4240" title: "Compiler Warning (level 3) C4240" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4240" +ms.date: 11/04/2016 f1_keywords: ["C4240"] helpviewer_keywords: ["C4240"] -ms.assetid: a2657cdb-18e1-493f-882b-4e10c0bca71d --- # Compiler Warning (level 3) C4240 -nonstandard extension used : access to 'classname' now defined to be 'access specifier', previously it was defined to be 'access specifier' +> nonstandard extension used : access to 'classname' now defined to be 'access specifier', previously it was defined to be 'access specifier' + +## Remarks Under ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)), you cannot change the access to a nested class. Under the default Microsoft extensions (/Ze), you can, with this warning. ## Example +The following example generates C4240: + ```cpp // C4240.cpp // compile with: /W3 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 ea6813c8f3a..6b8dd2c801f 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,18 +1,21 @@ --- -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 -'conversion type' conversion exists from 'type1' to 'type2', but is inaccessible +> 'conversion type' conversion exists from 'type1' to 'type2', but is inaccessible + +## Remarks A pointer to a derived class is converted to a pointer to a base class, but the derived class inherits the base class with private or protected access. -The following sample generates C4243: +## Example + +The following example generates C4243: ```cpp // C4243.cpp @@ -21,7 +24,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 fdee3d43de6..7fecde7c7ef 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4265" -title: "Compiler Warning (level 3) C4265" -ms.date: "11/04/2016" +title: "Compiler Warning (level 3, off) C4265" +description: "Learn more about: 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 + +## Remarks 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). + +## Example -The following sample generates C4265: +The following example generates C4265: ```cpp // C4265.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4267.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4267.md index bca3c8da4a9..3b6989d6744 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4267.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4267.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4267" title: "Compiler Warning (level 3) C4267" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4267" +ms.date: 11/04/2016 f1_keywords: ["C4267"] helpviewer_keywords: ["C4267"] -ms.assetid: 2fa2f13f-fa4f-47bb-ad8f-6cb19cfc91e6 --- # Compiler Warning (level 3) C4267 -'var' : conversion from 'size_t' to 'type', possible loss of data +> 'var' : conversion from 'size_t' to 'type', possible loss of data + +## Remarks The compiler detected a conversion from `size_t` to a smaller type. 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 bed46555980..86dd293c9a9 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,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4278" -title: "Compiler Warning (level 3) C4278" -ms.date: "08/27/2018" +title: "Compiler Warning (level 3 and level 4) C4278" +description: "Learn more about: 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. +## Remarks -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-c4280.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4280.md index 09130a82582..4ae40b56b8b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4280.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4280.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4280" title: "Compiler Warning (level 3) C4280" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4280" +ms.date: 11/04/2016 f1_keywords: ["C4280"] helpviewer_keywords: ["C4280"] -ms.assetid: 153fb639-3ee1-4fee-baf9-71420abcf3f6 --- # Compiler Warning (level 3) C4280 -'operator ->' was self recursive through type 'type' +> 'operator ->' was self recursive through type 'type' + +## Remarks Your code incorrectly allows **operator->** to call itself. -The following sample generates C4280: +## Example + +The following example generates C4280: ```cpp // C4280.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4281.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4281.md index 02df9c778a9..9426d177374 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4281.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4281.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4281" title: "Compiler Warning (level 3) C4281" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4281" +ms.date: 11/04/2016 f1_keywords: ["C4281"] helpviewer_keywords: ["C4281"] -ms.assetid: a9771261-5725-4fc6-87b6-16cf92113a25 --- # Compiler Warning (level 3) C4281 -'operator ->' recursion occurred through type 'type' +> 'operator ->' recursion occurred through type 'type' + +## Remarks Your code allows **operator->** to call itself. -The following sample generates C4281: +## Example + +The following example generates C4281: ```cpp // C4281.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4282.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4282.md index 151121d5b21..397b03cdf2a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4282.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4282.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4282" title: "Compiler Warning (level 3) C4282" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4282" +ms.date: 11/04/2016 f1_keywords: ["C4282"] helpviewer_keywords: ["C4282"] -ms.assetid: 155bef24-7bd1-497b-a24b-4a0d784b44cd --- # Compiler Warning (level 3) C4282 -then through type 'type' +> then through type 'type' + +## Remarks This continuation of warning C4281shows that **operator->** calls itself through `type`. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4283.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4283.md index 0e2d86ccf6e..98f9c84badd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4283.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4283.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4283" title: "Compiler Warning (level 3) C4283" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4283" +ms.date: 11/04/2016 f1_keywords: ["C4283"] helpviewer_keywords: ["C4283"] -ms.assetid: c8823f1f-e746-42e2-85ef-270745764c05 --- # Compiler Warning (level 3) C4283 -and through type 'type' +> and through type 'type' + +## Remarks This continuation of warning [C4281](../../error-messages/compiler-warnings/compiler-warning-level-3-c4281.md) shows that **operator->** calls itself through `type`. 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 4834efa3a10..99d48f7475c 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,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4287" -title: "Compiler Warning (level 3) C4287" -ms.date: "11/04/2016" +title: "Compiler Warning (level 3, off) C4287" +description: "Learn more about: 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 + +## Remarks 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 -The following sample generates C4287: +The following example generates C4287: ```cpp // C4287.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4290.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4290.md index aaa839fdef3..ad2acf66d4e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4290.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4290.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4290" title: "Compiler Warning (level 3) C4290" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4290" +ms.date: 11/04/2016 f1_keywords: ["C4290"] helpviewer_keywords: ["C4290"] -ms.assetid: d1c6d85b-28e0-4a1f-9d48-23593337a6fb --- # Compiler Warning (level 3) C4290 -C++ exception specification ignored except to indicate a function is not __declspec(nothrow) +> C++ exception specification ignored except to indicate a function is not __declspec(nothrow) + +## Remarks A function is declared using exception specification, which Visual C++ accepts but does not implement. Code with exception specifications that are ignored during compilation may need to be recompiled and linked to be reused in future versions supporting exception specifications. @@ -20,7 +21,9 @@ You can avoid this warning by using the [warning](../../preprocessor/warning.md) #pragma warning( disable : 4290 ) ``` -The following code sample generates C4290: +## Example + +The following example generates C4290: ```cpp // C4290.cpp 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 21157e1bbc6..aba692f1c11 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,16 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4306" -title: "Compiler Warning (level 3) C4306" -ms.date: "08/27/2018" +title: "Compiler Warning (level 4) C4306" +description: "Learn more about: 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. +## Remarks + +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 0daee29ed46..f929a873d2b 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,27 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4310" -title: "Compiler Warning (level 3) C4310" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4) C4310" +description: "Learn more about: 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: +## Remarks + +A constant value is cast to a smaller type. The compiler performs the cast, which truncates data. + +## Example + +The following example 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-c4316.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4316.md index 5094e9de73e..984e7f71f21 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4316.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4316.md @@ -1,16 +1,21 @@ --- title: "Compiler Warning (level 3) C4316" description: "Description of C++ compiler warning C4316" -ms.date: "11/04/2016" +ms.date: 11/04/2016 f1_keywords: ["C4316"] helpviewer_keywords: ["C4316"] -ms.assetid: 10371f01-aeb8-40ac-a290-59e63efa5ad4 --- # Compiler Warning (level 3) C4316 -Object allocated on the heap may not be aligned for this type. +> Object allocated on the heap may not be aligned for this type. -An over-aligned object allocated by using `operator new` may not have the specified alignment. Override [operator new](../../c-runtime-library/new-operator-crt.md) and [operator delete](../../c-runtime-library/delete-operator-crt.md) for over-aligned types so that they use the aligned allocation routines—for example, [_aligned_malloc](../../c-runtime-library/reference/aligned-malloc.md) and [_aligned_free](../../c-runtime-library/reference/aligned-free.md). The following sample generates C4316: +## Remarks + +An over-aligned object allocated by using `operator new` may not have the specified alignment. Override [operator new](../../c-runtime-library/new-operator-crt.md) and [operator delete](../../c-runtime-library/delete-operator-crt.md) for over-aligned types so that they use the aligned allocation routines—for example, [_aligned_malloc](../../c-runtime-library/reference/aligned-malloc.md) and [_aligned_free](../../c-runtime-library/reference/aligned-free.md). + +## Example + +The following example generates C4316: ```cpp // C4316.cpp 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 2f372281b89..6c410d831f7 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 @@ -1,26 +1,29 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4334" title: "Compiler Warning (level 3) C4334" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4334" +ms.date: 11/04/2016 f1_keywords: ["C4334"] helpviewer_keywords: ["C4334"] -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?) + +## Remarks -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 -The following sample generates C4334. +The following example generates C4334. ```cpp // 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-c4357.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4357.md index 008ffaca3b8..6e2208ff1fb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4357.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4357.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4357" title: "Compiler Warning (level 3) C4357" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4357" +ms.date: 11/04/2016 f1_keywords: ["C4357"] helpviewer_keywords: ["C4357"] -ms.assetid: 9259c633-3c02-4900-b94a-2d8d366d61cd --- # Compiler Warning (level 3) C4357 -param array argument in formal argument list for delegate 'del' ignored when generating 'function' +> param array argument in formal argument list for delegate 'del' ignored when generating 'function' + +## Remarks The `ParamArray` attribute was ignored, and `function` cannot be called with variable arguments. -The following sample generates C4357: +## Example + +The following example generates C4357: ```cpp // C4357.cpp 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 f4f62e9759a..7058b2598e2 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,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4359" -title: "Compiler Warning (level 3) C4359" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1 and level 3) C4359" +description: "Learn more about: 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). +## Remarks + +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 -The following sample generates C4359. +The following example generates C4359. ```cpp // C4359.cpp 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 ee956ccc2e3..1394a4e481f 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,28 +1,27 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4373" -title: "Compiler Warning (level 3) C4373" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4) C4373" +description: "Learn more about: 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 -// compile with: /c /W3 +// compile with: /c /W4 #include struct Base { diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4390.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4390.md index 813df6cac74..6ed88b3ea82 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4390.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4390.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4390" title: "Compiler Warning (level 3) C4390" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4390" +ms.date: 11/04/2016 f1_keywords: ["C4390"] helpviewer_keywords: ["C4390"] -ms.assetid: c95c2f1b-9bce-4b1f-a80c-565d4cde0b1e --- # Compiler Warning (level 3) C4390 -';' : empty controlled statement found; is this the intent? +> ';' : empty controlled statement found; is this the intent? + +## Remarks A semicolon was found after a control statement that contains no instructions. If you get C4390 because of a macro, you should use the [warning](../../preprocessor/warning.md) pragma to disable C4390 in the module containing the macro. -The following sample generates C4390: +## Example + +The following example generates C4390: ```cpp // C4390.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4398.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4398.md index 394219283d5..fd2f161dca1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4398.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4398.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4398" title: "Compiler Warning (level 3) C4398" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4398" +ms.date: 11/04/2016 f1_keywords: ["C4398"] helpviewer_keywords: ["C4398"] -ms.assetid: b6221432-9fed-4272-a547-a73f587904e6 --- # Compiler Warning (level 3) C4398 @@ -20,7 +19,7 @@ For more information, see [appdomain](../../cpp/appdomain.md) and [Application D ## Example -The following sample generates C4398. +The following example generates C4398. ```cpp // C4398.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4404.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4404.md index 27677fa9728..9284eab853c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4404.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4404.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4404" title: "Compiler Warning (level 3) C4404" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4404" +ms.date: 11/04/2016 f1_keywords: ["C4404"] helpviewer_keywords: ["C4404"] -ms.assetid: 78ce9985-0ccd-4ec2-92bf-289475109cdd --- # Compiler Warning (level 3) C4404 -period on directive ignored +> period on directive ignored + +## Remarks The optional period preceding the directive is ignored. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4414.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4414.md index 0a4b595c122..e9002be53f4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4414.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4414.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4414" title: "Compiler Warning (level 3) C4414" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4414" +ms.date: 11/04/2016 f1_keywords: ["C4414"] helpviewer_keywords: ["C4414"] -ms.assetid: bc81d3ad-55dc-4a6b-a6f2-ec0ef38347df --- # Compiler Warning (level 3) C4414 -'function' : short jump to function converted to near +> 'function' : short jump to function converted to near + +## Remarks Short jumps generate compact instruction which branches to an address within a limited range from the instruction. The instruction includes a short offset that represents the distance between the jump and the target address, the function definition. During linking a function may be moved or subject to link-time optimizations that cause the function to be moved out of the range reachable from a short offset. The compiler must generate a special record for the jump, which requires the jmp instruction to be either NEAR or FAR. The compiler made the conversion. +## Example + For example, the following code generates C4414: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4511.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4511.md index 198c5895880..609b70accec 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4511.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4511.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4511" title: "Compiler Warning (level 3) C4511" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4511" +ms.date: 11/04/2016 f1_keywords: ["C4511"] helpviewer_keywords: ["C4511"] -ms.assetid: a01286b2-3dd9-4a97-a5ee-dd0e7b63ef8b --- # Compiler Warning (level 3) C4511 -'class' : copy constructor could not be generated +> 'class' : copy constructor could not be generated + +## Remarks The compiler could not generate a default copy-constructor for a class; a base class may have a private copy-constructor. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4521.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4521.md index fc0524f6646..835726ea232 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4521.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4521.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4521" title: "Compiler Warning (level 3) C4521" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4521" +ms.date: 11/04/2016 f1_keywords: ["C4521"] helpviewer_keywords: ["C4521"] -ms.assetid: 057d770c-ebcf-44cd-b943-1b1bb1ceaa8c --- # Compiler Warning (level 3) C4521 -'class' : multiple copy constructors specified +> 'class' : multiple copy constructors specified + +## Remarks The class has multiple copy constructors of a single type. This warning is informational; the constructors are callable in your program. @@ -16,7 +17,7 @@ Use the [warning](../../preprocessor/warning.md) pragma to suppress this warning ## Example -The following sample generates C4521. +The following example generates C4521. ```cpp // C4521.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4522.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4522.md index 3930d4347d2..51cad339419 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4522.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4522.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4522" title: "Compiler Warning (level 3) C4522" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4522" +ms.date: 11/04/2016 f1_keywords: ["C4522"] helpviewer_keywords: ["C4522"] -ms.assetid: 7065dc27-0b6c-4e68-a345-c51cdb99a20b --- # Compiler Warning (level 3) C4522 -'class' : multiple assignment operators specified +> 'class' : multiple assignment operators specified + +## Remarks The class has multiple assignment operators of a single type. This warning is informational; the constructors are callable in your program. @@ -16,7 +17,7 @@ Use the [warning](../../preprocessor/warning.md) pragma to suppress this warning ## Example -The following sample generates C4522. +The following example generates C4522. ```cpp // C4522.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4523.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4523.md index 1054bb6008c..1f9497e7f01 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4523.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4523.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4523" title: "Compiler Warning (level 3) C4523" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4523" +ms.date: 11/04/2016 f1_keywords: ["C4523"] helpviewer_keywords: ["C4523"] -ms.assetid: 0f28761d-999f-43fe-9481-d02afd9b4f60 --- # Compiler Warning (level 3) C4523 -'class' : multiple destructors specified +> 'class' : multiple destructors specified + +## Remarks The class has multiple destructors. 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 82420cf1d01..02b4492a1fd 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 @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4534" title: "Compiler Warning (level 3) C4534" -ms.date: "11/04/2016" -f1_keywords: ["c4534"] +description: "Learn more about: Compiler Warning (level 3) C4534" +ms.date: 11/04/2016 +f1_keywords: ["C4534"] helpviewer_keywords: ["C4534"] -ms.assetid: ec2adf3b-d7a1-4005-bb0c-5d219df78dc8 --- # Compiler Warning (level 3) C4534 -'constructor' will not be a default constructor for class 'class' due to the default argument +> 'constructor' will not be a default constructor for class 'class' due to the default argument + +## Remarks An unmanaged class can have a constructor with parameters that have default values and the compiler will use this as the default constructor. A class marked with the `value` keyword will not use a constructor with default values for its parameters as a default constructor. For more information, see [Classes and Structs](../../extensions/classes-and-structs-cpp-component-extensions.md). -The following sample generates C4534: +## Example + +The following example generates C4534: ```cpp // C4534.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4535.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4535.md index 254257c0bab..a98e2fb5ec1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4535.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4535.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4535" title: "Compiler Warning (level 3) C4535" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4535" +ms.date: 11/04/2016 f1_keywords: ["C4535"] helpviewer_keywords: ["C4535"] -ms.assetid: 2c5ad1aa-2558-41d1-8f06-47fef74c8d9b --- # Compiler Warning (level 3) C4535 -calling _set_se_translator() requires /EHa +> calling _set_se_translator() requires /EHa + +## Remarks The use of [_set_se_translator](../../c-runtime-library/reference/set-se-translator.md) requires the [/EHa](../../build/reference/eh-exception-handling-model.md) compiler option and not **/EHs**. ## Example -The following sample generates C4535. +The following example generates C4535. ```cpp // C4535.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4538.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4538.md index 255ed1ba17c..6bfa7556556 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4538.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4538.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4538" title: "Compiler Warning (level 3) C4538" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4538" +ms.date: 11/04/2016 f1_keywords: ["C4538"] helpviewer_keywords: ["C4538"] -ms.assetid: 747e3d51-b6d0-41c1-a726-7af3253b59d7 --- # Compiler Warning (level 3) C4538 -'type' : const/volatile qualifiers on this type are not supported +> 'type' : const/volatile qualifiers on this type are not supported + +## Remarks A qualifier keyword was applied to an array incorrectly. For more information, see [array](../../extensions/arrays-cpp-component-extensions.md). -The following sample generates C4538: +## Example + +The following example generates C4538: ```cpp // C4538.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4543.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4543.md index 56157264165..a36b2bff456 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4543.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4543.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4543" title: "Compiler Warning (level 3) C4543" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4543" +ms.date: 11/04/2016 f1_keywords: ["C4543"] helpviewer_keywords: ["C4543"] -ms.assetid: a09b39a7-d3b8-435c-86a3-2233c512f24b --- # Compiler Warning (level 3) C4543 -Injected text suppressed by attribute 'no_injected_text' +> Injected text suppressed by attribute 'no_injected_text' + +## Remarks The [no_injected_text](../../windows/attributes/no-injected-text.md) attribute appeared in source code, which means the compiler will prevent attributes from injecting code. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4554.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4554.md index 47742011a04..46786ef9159 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4554.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4554.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4554" title: "Compiler Warning (level 3) C4554" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4554" +ms.date: 11/04/2016 f1_keywords: ["C4554"] helpviewer_keywords: ["C4554"] -ms.assetid: 55bb68f0-2e80-4330-8921-51083c4f8d53 --- # Compiler Warning (level 3) C4554 -'operator' : check operator precedence for possible error; use parentheses to clarify precedence +> 'operator' : check operator precedence for possible error; use parentheses to clarify precedence + +## Example -The following sample generates C4554: +The following example generates C4554: ```cpp // C4554.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4557.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4557.md index 45a74eb0f47..b6495e22283 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4557.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4557.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4557" title: "Compiler Warning (level 3) C4557" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4557" +ms.date: 11/04/2016 f1_keywords: ["C4557"] helpviewer_keywords: ["C4557"] -ms.assetid: 7d9db716-03b2-4ee5-9b09-ba8aa5aa7e4c --- # Compiler Warning (level 3) C4557 -'__assume' contains effect 'effect' +> '__assume' contains effect 'effect' + +## Remarks The value passed to an [__assume](../../intrinsics/assume.md) statement2 was modified. 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. -The following sample generates C4557: +## Example + +The following example generates C4557: ```cpp // C4557.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4570.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4570.md index a3090361bf4..6ae41dad8d9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4570.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4570.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4570" title: "Compiler Warning (level 3) C4570" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4570" +ms.date: 11/04/2016 f1_keywords: ["C4570"] helpviewer_keywords: ["C4570"] -ms.assetid: feec1225-e6ad-4995-8d96-c22e864a77bd --- # Compiler Warning (level 3) C4570 -'type' : is not explicitly declared as abstract but has abstract functions +> 'type' : is not explicitly declared as abstract but has abstract functions + +## Remarks A type that contains [abstract](../../extensions/abstract-cpp-component-extensions.md) functions should itself be marked as abstract. ## Example -The following sample generates C4570. +The following example generates C4570. ```cpp // C4570.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4580.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4580.md index 5be25424956..f8d07e1f61a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4580.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4580.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4580" title: "Compiler Warning (level 3) C4580" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4580" +ms.date: 11/04/2016 f1_keywords: ["C4580"] helpviewer_keywords: ["C4580"] -ms.assetid: fef6e8e0-0d6a-44fa-b22a-2fe7ba2ef379 --- # Compiler Warning (level 3) C4580 -[attribute] is deprecated; instead specify System::Attribute or Platform::Metadata as a base class +> [attribute] is deprecated; instead specify System::Attribute or Platform::Metadata as a base class + +## Remarks [[attribute](../../windows/attributes/attribute.md)] is no longer the preferred syntax for creating user-defined attributes. For more information, see [User-Defined Attributes](../../extensions/user-defined-attributes-cpp-component-extensions.md). For CLR code, derive attributes from `System::Attribute`. For Windows Runtime code, derive attributes from `Platform::Metadata`. ## Example -The following sample generates C3454 and shows how to fix it. +The following example generates C4580 and shows how to fix it. ```cpp // C4580.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4608.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4608.md index 40bb5d55bdb..f924e7ab0e4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4608.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4608.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4608" title: "Compiler Warning (level 3) C4608" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4608" +ms.date: 11/04/2016 f1_keywords: ["C4608"] helpviewer_keywords: ["C4608"] -ms.assetid: 8b8f5f28-8ce9-457e-9d3d-a8c0efce9b6a --- # Compiler Warning (level 3) C4608 -'union_member' has already been initialized by another union member in the initializer list, 'union_member' +> 'union_member' has already been initialized by another union member in the initializer list, 'union_member' + +## Remarks Two members of the same union were initialized in an initialization list. You can only access one member of the union. -The following sample generates C4608: +## Example + +The following example generates C4608: ```cpp // C4608.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4619.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4619.md index d088f9e025e..fb98a1c9d61 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4619.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4619.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4619" title: "Compiler Warning (level 3) C4619" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4619" +ms.date: 11/04/2016 f1_keywords: ["C4619"] helpviewer_keywords: ["C4619"] -ms.assetid: 701fea21-01aa-4bea-93d4-1cb8824170b0 --- # Compiler Warning (level 3) C4619 -\#pragma warning : there is no warning number 'number' +> #pragma warning : there is no warning number 'number' + +## Remarks An attempt was made to disable a warning that does not exist. 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. -The following sample generates C4619: +## Example + +The following example generates C4619: ```cpp // C4619.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4622.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4622.md index 2a33076a976..ba45d4c3827 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4622.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4622.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4622" title: "Compiler Warning (level 3) C4622" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4622" +ms.date: 11/04/2016 f1_keywords: ["C4622"] helpviewer_keywords: ["C4622"] -ms.assetid: d3c879f0-4492-4f4b-b26d-230993f3a933 --- # Compiler Warning (level 3) C4622 -Overwriting debug information formed during creation of the precompiled header in object file: 'file' +> Overwriting debug information formed during creation of the precompiled header in object file: 'file' + +## Remarks CodeView information in the specified file was lost when it was compiled with the [/Yu](../../build/reference/yu-use-precompiled-header-file.md) (Use Precompiled Headers) option. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4633.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4633.md index 8a008df2686..5767c5613aa 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4633.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4633.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4633" title: "Compiler Warning (level 3) C4633" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4633" +ms.date: 11/04/2016 f1_keywords: ["C4633"] helpviewer_keywords: ["C4633"] -ms.assetid: 6d76f268-ba8c-448b-8e83-b903a18b583b --- # Compiler Warning (level 3) C4633 -XML document comment target: error: reason +> XML document comment target: error: reason + +## Remarks A name passed to the [\](../../build/reference/param-visual-cpp.md) tag was not found by the compiler. -The following sample generates C4633: +## Example + +The following example generates C4633: ```cpp // C4633.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4635.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4635.md index dec16024a92..ea7c5b80a03 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4635.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4635.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4635" title: "Compiler Warning (level 3) C4635" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4635" +ms.date: 11/04/2016 f1_keywords: ["C4635"] helpviewer_keywords: ["C4635"] -ms.assetid: b2ba90de-c093-4a76-8076-b65878467574 --- # Compiler Warning (level 3) C4635 -XML document comment target: badly-formed XML: reason +> XML document comment target: badly-formed XML: reason + +## Remarks The compiler found some problem with the XML tags. Fix the problem and recompile -The following sample generates C4635: +## Example + +The following example generates C4635: ```cpp // C4635.cpp @@ -26,6 +29,6 @@ The following sample generates C4635: public ref class Test {}; ``` -Notice that the output for this sample says: **End tag 'member' does not match the start tag 'summary'.** +Notice that the output for this example says: **End tag 'member' does not match the start tag 'summary'.** -The problem with this sample is that the end tag for \ is poorly formed, and the compiler does not recognize it as the \ end tag. The \ tag is embedded in the .xdc file by the compiler in every /doc compilation. So, the problem here is that the end tag \, does not match the previous start tag that the compiler processed (\. +The problem with this example is that the end tag for \ is poorly formed, and the compiler does not recognize it as the \ end tag. The \ tag is embedded in the .xdc file by the compiler in every /doc compilation. So, the problem here is that the end tag \, does not match the previous start tag that the compiler processed (\. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4636.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4636.md index 4591d9dcc8a..ee0b25a5f6b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4636.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4636.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4636" title: "Compiler Warning (level 3) C4636" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4636" +ms.date: 11/04/2016 f1_keywords: ["C4636"] helpviewer_keywords: ["C4636"] -ms.assetid: 59112a0f-850f-41c6-bd84-8ae8dc84706a --- # Compiler Warning (level 3) C4636 -XML document comment applied to 'construct': tag requires non-empty '' attribute. +> XML document comment applied to 'construct': tag requires non-empty '' attribute. + +## Remarks A tag, such as `cref`, did not have a value. ## Example -The following sample generates C4636. +The following example generates C4636. ```cpp // C4636.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4637.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4637.md index 3617d5b4ace..4426328632f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4637.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4637.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4637" title: "Compiler Warning (level 3) C4637" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4637" +ms.date: 11/04/2016 f1_keywords: ["C4637"] helpviewer_keywords: ["C4637"] -ms.assetid: 5fd347c1-2de9-408f-9136-1bf1ff273622 --- # Compiler Warning (level 3) C4637 -XML document comment target: \ tag discarded. reason +> XML document comment target: \ tag discarded. reason + +## Remarks The syntax of an [\](../../build/reference/include-visual-cpp.md) tag was not correct. -The following sample generates C4637: +## Example + +The following example generates C4637: ```cpp // C4637.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4638.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4638.md index cbe5cbcc601..1ac1da97a49 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4638.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4638.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4638" title: "Compiler Warning (level 3) C4638" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 3) C4638" +ms.date: 08/27/2018 f1_keywords: ["C4638"] helpviewer_keywords: ["C4638"] -ms.assetid: 2c07923a-e103-4e40-bd11-fdfed428a5ec --- # Compiler Warning (level 3) C4638 @@ -16,7 +15,7 @@ The compiler was unable to resolve a symbol (*symbol*). The symbol must be valid ## Example -The following sample generates C4638: +The following example generates C4638: ```cpp // C4638.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4640.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4640.md index 99e0026cb1a..f66a7e4ebda 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4640.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4640.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4640" title: "Compiler Warning (level 3) C4640" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4640" +ms.date: 11/04/2016 f1_keywords: ["C4640"] helpviewer_keywords: ["C4640"] -ms.assetid: f76871f6-e436-4c35-9793-d2f22f7e1c7f --- # Compiler Warning (level 3) C4640 -'instance' : construction of local static object is not thread-safe +> 'instance' : construction of local static object is not thread-safe + +## Remarks A static instance of an object is not thread safe. 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. -The following sample generates C4640: +## Example + +The following example generates C4640: ```cpp // C4640.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4641.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4641.md index 86cf77948f0..5f110fcce54 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4641.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4641.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4641" title: "Compiler Warning (level 3) C4641" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4641" +ms.date: 11/04/2016 f1_keywords: ["C4641"] helpviewer_keywords: ["C4641"] -ms.assetid: 28fe5c3e-6039-42da-9100-1312b5b15aea --- # Compiler Warning (level 3) C4641 -XML document comment has an ambiguous cross reference +> XML document comment has an ambiguous cross reference + +## Remarks The compiler was unable to unambiguously resolve a reference. To resolve this warning, specify the parameter information necessary to make the reference unambiguous. @@ -16,7 +17,7 @@ For more information, see [XML Documentation](../../build/reference/xml-document ## Example -The following sample generates C4641. +The following example generates C4641. ```cpp // C4641.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4645.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4645.md index 278a1ffe4c4..84ffd10a7f4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4645.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4645.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4645" title: "Compiler Warning (level 3) C4645" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4645" +ms.date: 11/04/2016 f1_keywords: ["C4645"] helpviewer_keywords: ["C4645"] -ms.assetid: fd7c1ddf-f0d0-4e10-bab9-ccb4c3476298 --- # Compiler Warning (level 3) C4645 -function declared with __declspec(noreturn) has a return statement +> function declared with __declspec(noreturn) has a return statement + +## Remarks A [return](../../cpp/program-termination.md) statement was found in a function that is marked with the [noreturn](../../cpp/noreturn.md) **`__declspec`** modifier. The **`return`** statement was ignored. -The following sample generates C4645: +## Example + +The following example generates C4645: ```cpp // C4645.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4646.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4646.md index 427f282b514..84233c3a05e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4646.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4646.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4646" title: "Compiler Warning (level 3) C4646" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4646" +ms.date: 11/04/2016 f1_keywords: ["C4646"] helpviewer_keywords: ["C4646"] -ms.assetid: 23677e8e-603e-40e0-b99a-2e4894a1278e --- # Compiler Warning (level 3) C4646 -function declared with __declspec(noreturn) has non-void return type +> function declared with __declspec(noreturn) has non-void return type + +## Remarks A function marked with the [noreturn](../../cpp/noreturn.md) **`__declspec`** modifier should have a [void](../../cpp/void-cpp.md) return type. -The following sample generates C4646: +## Example + +The following example generates C4646: ```cpp // C4646.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4686.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4686.md index 28ac87a590c..eeda17ff133 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4686.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4686.md @@ -4,7 +4,6 @@ description: "Microsoft C++ compiler warning C4686." ms.date: 08/29/2020 f1_keywords: ["C4686"] helpviewer_keywords: ["C4686"] -ms.assetid: 767c83c2-9e4b-4f9e-88c8-02128ba563f4 --- # Compiler Warning (level 3) C4686 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4723.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4723.md index 7893ae678ed..d41de92232c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4723.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4723.md @@ -4,11 +4,12 @@ description: "Describes the MSVC compiler warning C4723 for potential divide by ms.date: 07/08/2020 f1_keywords: ["C4723"] helpviewer_keywords: ["C4723"] -ms.assetid: 07669d14-3fd8-4a43-94bc-b61c50e58460 --- # Compiler Warning (level 3) C4723 -> `potential divide by 0` +> potential divide by 0 + +## Remarks The second operand in a divide operation evaluated to zero at compile time, giving undefined results. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4724.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4724.md index e9bb992d3ad..d1cdf080f8a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4724.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4724.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4724" title: "Compiler Warning (level 3) C4724" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4724" +ms.date: 11/04/2016 f1_keywords: ["C4724"] helpviewer_keywords: ["C4724"] -ms.assetid: 3be4305b-e8fe-49a9-abbf-b20dfbd71a19 --- # Compiler Warning (level 3) C4724 -potential mod by 0 +> potential mod by 0 + +## Remarks The second operand in a remainder operation evaluated to zero at compile time, giving undefined results. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4738.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4738.md index b8ef08780a1..418c5042309 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4738.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4738.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (Level 3) C4738" title: "Compiler Warning (Level 3) C4738" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 3) C4738" +ms.date: 11/04/2016 f1_keywords: ["C4738"] helpviewer_keywords: ["C4738"] -ms.assetid: 9094895f-7eec-46c2-83d3-249b761d585e --- # Compiler Warning (Level 3) C4738 -storing 32-bit float result in memory, possible loss of performance +> storing 32-bit float result in memory, possible loss of performance + +## Remarks C4738 warns that the result of an assignment, cast, passed argument, or other operation may need to be rounded or that the operation ran out of registers and needed to use memory (spilling). This can result in performance loss. @@ -20,7 +21,7 @@ This warning is off by default. For more information, see [Compiler Warnings Tha ## Example -The following sample generates C4738: +The following example generates C4738: ```cpp // C4738.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4792.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4792.md index a4e6e483aea..ab042b9b95a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4792.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4792.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4792" title: "Compiler Warning (level 3) C4792" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4792" +ms.date: 11/04/2016 f1_keywords: ["C4792"] helpviewer_keywords: ["C4792"] -ms.assetid: c047ce69-a622-44e1-9425-d41aa9261c61 --- # Compiler Warning (level 3) C4792 -function 'function' declared using sysimport and referenced from native code; import library required to link +> function 'function' declared using sysimport and referenced from native code; import library required to link + +## Remarks A native function that was imported into the program with DllImport was called from an unmanaged function. Therefore, you must link to the import library for the DLL. This warning cannot be resolved in code or by changing the way you compile. Use the [warning](../../preprocessor/warning.md) pragma to disable this warning. -The following sample generates C4792: +## Example + +The following example generates C4792: ```cpp // C4792.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4800.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4800.md index 128c92c9bb6..7d0eaddd3ac 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4800.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4800.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4800" title: "Compiler Warning (level 4) C4800" -ms.date: "03/14/2019" +description: "Learn more about: Compiler Warning (level 4) C4800" +ms.date: 03/14/2019 f1_keywords: ["C4800"] helpviewer_keywords: ["C4800"] -ms.assetid: 4f409799-a250-45ed-bb5f-657691b0d9f7 --- # Compiler Warning (level 4) C4800 @@ -16,6 +15,8 @@ Visual Studio 2019 and later: C4800 is a level 3 warning in Visual Studio 2015 and earlier: > '*type*' : forcing value to bool 'true' or 'false' (performance warning) +## Remarks + This warning is generated when a value is implicitly converted into type **`bool`**. Typically, this message is caused by assigning **`int`** variables to **`bool`** variables where the **`int`** variable contains only values **`true`** and **`false`**, and could be redeclared as type **`bool`**. If you can't rewrite the expression to use type **`bool`**, then you can add "`!=0`" to the expression, which gives the expression type **`bool`**. Casting the expression to type **`bool`** doesn't disable the warning, which is by design. ::: moniker range=">= msvc-150" @@ -28,7 +29,7 @@ This warning is off by default starting in Visual Studio 2019. Use __/w__*n*__48 ## Example -The following sample generates C4800 and shows how to fix it: +The following example generates C4800 and shows how to fix it: ```cpp // C4800.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4823.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4823.md index 3a8f659d426..0e5cbf011de 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4823.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4823.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4823" title: "Compiler Warning (level 3) C4823" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4823" +ms.date: 11/04/2016 f1_keywords: ["C4823"] helpviewer_keywords: ["C4823"] -ms.assetid: 8a77560d-dcea-4cae-aebb-8ebf1b4cef85 --- # Compiler Warning (level 3) C4823 -'function' : uses pinning pointers but unwind semantics are not enabled. Consider using /EHa +> 'function' : uses pinning pointers but unwind semantics are not enabled. Consider using /EHa + +## Remarks To unpin an object on the managed heap pointed to by a pinning pointer declared in a block scope, the compiler simulates the behavior of destructors of local classes, "pretending" the pinning pointer has a destructor that nullifies the pointer. To enable a call to a destructor after throwing an exception, you must enable object unwinding, which you can do by using [/EHsc](../../build/reference/eh-exception-handling-model.md). @@ -16,7 +17,7 @@ You can also manually unpin the object and ignore the warning. ## Example -The following sample generates C4823. +The following example generates C4823. ```cpp // C4823.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4839.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4839.md index 93f5ae72111..0179dad250c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4839.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4839.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4839" title: "Compiler Warning (level 3) C4839" -ms.date: "09/13/2018" +description: "Learn more about: Compiler Warning (level 3) C4839" +ms.date: 09/13/2018 f1_keywords: ["C4839"] helpviewer_keywords: ["C4839"] -ms.assetid: f4f99066-9258-4330-81a8-f4a75a1d95ee --- # Compiler Warning (level 3) C4839 > non-standard use of class '*type*' as an argument to a variadic function +## Remarks + Classes or structs that are passed to a variadic function such as `printf` must be trivially copyable. When passing such objects, the compiler simply makes a bitwise copy and does not call the constructor or destructor. This warning is available beginning in Visual Studio 2017. ## Example -The following sample generates C4839: +The following example generates C4839: ```cpp // C4839.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md index 40a319396a3..76e0eb019a0 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4995.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 3) C4995" title: "Compiler Warning (level 3) C4995" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 3) C4995" +ms.date: 08/30/2022 f1_keywords: ["C4995"] helpviewer_keywords: ["C4995"] -ms.assetid: c6b61755-4730-4947-ad4d-d1c2bc82585a --- # Compiler Warning (level 3) C4995 -'function': name was marked as #pragma deprecated +> '*function*': name was marked as `#pragma deprecated` + +## Remarks + +The compiler encountered a function that was marked with [`#pragma deprecated`](../../preprocessor/deprecated-c-cpp.md). The function may no longer be supported in a future release. You can turn off this warning by using [`#pragma warning`](../../preprocessor/warning.md). -The compiler encountered a function that was marked with pragma [deprecated](../../preprocessor/deprecated-c-cpp.md). The function may no longer be supported in a future release. You can turn this warning off with the [warning](../../preprocessor/warning.md) pragma (example below). +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example -The following sample generates C4995: +The following example generates C4995. Uncomment the `#pragma warning` line to disable the warning. ```cpp // C4995.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md index 4385832759e..2180d283941 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-3-c4996.md @@ -1,10 +1,9 @@ --- title: "Compiler Warning (level 3) C4996" description: "Explains why Compiler warning C4996 happens, and describes what to do about it." -ms.date: 07/09/2020 +ms.date: 08/30/2022 f1_keywords: ["C4996"] helpviewer_keywords: ["C4996"] -ms.assetid: 926c7cc2-921d-43ed-ae75-634f560dd317 --- # Compiler Warning (level 3) C4996 @@ -15,7 +14,9 @@ Your code uses a function, class member, variable, or typedef that's marked *dep ## Remarks -Many functions, member functions, template functions, and global variables in Visual Studio libraries are *deprecated*. Some, such as POSIX and Microsoft-specific functions, are deprecated because they now have a different preferred name. Some C runtime library functions are deprecated because they're insecure and have a more secure variant. Others are deprecated because they're obsolete. The deprecation messages usually include a suggested replacement for the deprecated function or global variable. +Many functions, member functions, function templates, and global variables in Visual Studio libraries are *deprecated*. Some, such as POSIX and Microsoft-specific functions, are deprecated because they now have a different preferred name. Some C runtime library functions are deprecated because they're insecure and have a more secure variant. Others are deprecated because they're obsolete. The deprecation messages usually include a suggested replacement for the deprecated function or global variable. + +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Turn off the warning @@ -61,7 +62,7 @@ Here are some of the common sources of C4996 warnings and errors: ## POSIX function names -**`The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name:`** _`new-name.`_ **`See online help for details.`** +> The POSIX name for this item is deprecated. Instead, use the ISO C and C++ conformant name: *`new-name`*. See online help for details. Microsoft renamed some POSIX and Microsoft-specific library functions in the CRT to conform with C99 and C++03 constraints on reserved and global implementation-defined names. *Only the names are deprecated, not the functions themselves*. In most cases, a leading underscore was added to the function name to create a conforming name. The compiler issues a deprecation warning for the original function name, and suggests the preferred name. @@ -71,7 +72,7 @@ To turn off deprecation warnings for these functions, define the preprocessor ma ## Unsafe CRT Library functions -**`This function or variable may be unsafe. Consider using`** _`safe-version`_ **`instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details.`** +> This function or variable may be unsafe. Consider using *`safe-version`* instead. To disable deprecation, use _CRT_SECURE_NO_WARNINGS. See online help for details. Microsoft deprecated some CRT and C++ Standard Library functions and globals because more secure versions are available. Most of the deprecated functions allow unchecked read or write access to buffers. Their misuse can lead to serious security issues. The compiler issues a deprecation warning for these functions, and suggests the preferred function. @@ -85,9 +86,9 @@ For more information about these deprecated functions and globals, see [Security ## Unsafe Standard Library functions -**`'std::`** *`function_name`* **`::_Unchecked_iterators::_Deprecate' Call to std::`** *`function_name`* **`with parameters that may be unsafe - this call relies on the caller to check that the passed values are correct. To disable this warning, use -D_SCL_SECURE_NO_WARNINGS. See documentation on how to use Visual C++ 'Checked Iterators'`** +> 'std:: *`function_name`* ::_Unchecked_iterators::_Deprecate' Call to std:: *`function_name`* with parameters that may be unsafe - this call relies on the caller to check that the passed values are correct. To disable this warning, use -D_SCL_SECURE_NO_WARNINGS. See documentation on how to use Visual C++ 'Checked Iterators' -In Visual Studio 2015, this warning appears in debug builds because certain C++ Standard Library template functions don't check parameters for correctness. Often it's because not enough information is available to the function to check container bounds. Or, because iterators may be used incorrectly with the function. This warning helps you identify these functions, because they may be a source of serious security holes in your program. For more information, see [Checked iterators](../../standard-library/checked-iterators.md). +In Visual Studio 2015, this warning appears in debug builds because certain C++ Standard Library function templates don't check parameters for correctness. Often it's because not enough information is available to the function to check container bounds. Or, because iterators may be used incorrectly with the function. This warning helps you identify these functions, because they may be a source of serious security holes in your program. For more information, see [Checked iterators](../../standard-library/checked-iterators.md). For example, this warning appears in Debug mode if you pass an element pointer to `std::copy`, instead of a plain array. To fix this issue, use an appropriately declared array, so the library can check the array extents and do bounds checking. @@ -246,7 +247,7 @@ For information on how to suppress these warnings, see [`_AFX_SECURE_NO_WARNINGS ## Obsolete CRT functions and variables -**`This function or variable has been superseded by newer library or operating system functionality. Consider using`** *`new_item`* **`instead. See online help for details.`** +> This function or variable has been superseded by newer library or operating system functionality. Consider using *`new_item`* instead. See online help for details. Some library functions and global variables are deprecated as obsolete. These functions and variables may be removed in a future version of the library. The compiler issues a deprecation warning for these items, and suggests the preferred alternative. 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 cea9a5aa4a7..f5c0cdd330b 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,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4001" -title: "Compiler Warning (level 4) C4001" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, no longer emitted) C4001" +description: "Learn more about: 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 + +## Remarks > [!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 0a68e08ae7a..cdb8721b010 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 @@ -1,21 +1,27 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4019" title: "Compiler Warning (level 4) C4019" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4019" +ms.date: 11/04/2016 f1_keywords: ["C4019"] helpviewer_keywords: ["C4019"] -ms.assetid: 4ecfe85d-673f-4334-8154-36fe7f0b3444 --- # Compiler Warning (level 4) C4019 -empty statement at global scope +> empty statement at global scope + +## Remarks -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 +The following example generates C4019: + ```c // C4019.c // compile with: /Za /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4032.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4032.md index cfe32c9fdea..b5e045ee4f2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4032.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4032.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4032" title: "Compiler Warning (level 4) C4032" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4032" +ms.date: 11/04/2016 f1_keywords: ["C4032"] helpviewer_keywords: ["C4032"] -ms.assetid: 70dd0c85-0239-43f9-bb06-507f6a57d206 --- # Compiler Warning (level 4) C4032 -formal parameter 'number' has different type when promoted +> formal parameter 'number' has different type when promoted + +## Remarks The parameter type is not compatible, through default promotions, with the type in a previous declaration. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4053.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4053.md index dec8704399d..b18683f19f2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4053.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4053.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4053" title: "Compiler Warning (level 4) C4053" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4053" +ms.date: 11/04/2016 f1_keywords: ["C4053"] helpviewer_keywords: ["C4053"] -ms.assetid: e3b8c46e-e36d-412c-99b9-3db860b6e307 --- # Compiler Warning (level 4) C4053 -one void operand for '?:' +> one void operand for '?:' + +## Remarks The `?:` operator is given an expression of type **`void`**. The value of the **`void`** operand is undefined. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4057.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4057.md index d335a6fab05..a7cac9d610c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4057.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4057.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4057" title: "Compiler Warning (level 4) C4057" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4057" +ms.date: 11/04/2016 f1_keywords: ["C4057"] helpviewer_keywords: ["C4057"] -ms.assetid: e75d0645-84c9-4bef-a812-942ed9879aa3 --- # Compiler Warning (level 4) C4057 -'operator' : 'identifier1' indirection to slightly different base types from 'identifier2' +> 'operator' : 'identifier1' indirection to slightly different base types from 'identifier2' + +## Remarks Two pointer expressions refer to different base types. The expressions are used without conversion. 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 fb09ff4c507..828c339d2f7 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,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4061" -title: "Compiler Warning (level 4) C4061" -ms.date: "04/05/2019" +title: "Compiler Warning (level 4, off) C4061" +description: "Learn more about: 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). +## Remarks + +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). ## Example -The following sample generates C4061; add a case for the missing enumerator to fix: +The following example generates C4061; add a case for the missing enumerator to fix: ```cpp // C4061.cpp @@ -34,10 +35,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 7a88ec1ecc7..2862f25d899 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,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4062" -title: "Compiler Warning (level 4) C4062" -ms.date: "04/05/2019" +title: "Compiler Warning (level 4, off) C4062" +description: "Learn more about: 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). +## Remarks + +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). ## Example -The following sample generates C4062, and shows how to fix it: +The following example generates C4062, and shows how to fix it: ```cpp // C4062.cpp @@ -31,9 +32,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-c4092.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4092.md index 5f3cc5c9b67..d926a41d768 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4092.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4092.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4092" title: "Compiler Warning (level 4) C4092" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4092" +ms.date: 11/04/2016 f1_keywords: ["C4092"] helpviewer_keywords: ["C4092"] -ms.assetid: 396ae826-a892-4327-bd66-f4762376d72b --- # Compiler Warning (level 4) C4092 > sizeof returns 'unsigned long' +## Remarks + The operand of the **`sizeof`** operator was very large, so **`sizeof`** returned an **`unsigned long`**. This warning occurs under the Microsoft extensions ([`/Ze`](../../build/reference/za-ze-disable-language-extensions.md)). Under ANSI compatibility (**`/Za`**), the result is truncated instead. 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 189fa4462c3..c0b6b54f40f 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,29 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4100" title: "Compiler Warning (level 4) C4100" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4100" +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 + +## Remarks 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. + +## Example -The following sample generates C4100: +The following example 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-c4121.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4121.md index ab0179a1064..0d8b34944c4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4121.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4121.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4121" title: "Compiler Warning (level 4) C4121" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4121" +ms.date: 11/04/2016 f1_keywords: ["C4121"] helpviewer_keywords: ["C4121"] -ms.assetid: 8c5b85c9-2543-426b-88bc-319c50158c7e --- # Compiler Warning (level 4) C4121 -'symbol' : alignment of a member was sensitive to packing +> 'symbol' : alignment of a member was sensitive to packing + +## Remarks + +The compiler added padding to align a structure member on the packing boundary but the packing value is less than the member's size. + +## Example -The compiler added padding to align a structure member on the packing boundary but the packing value is less than the member's size. For example, the following code snippet produces C4121: +For example, the following code snippet produces C4121: ```cpp // C4121.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4125.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4125.md index 8e5089b3f3d..78acc7ec0f4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4125.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4125.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4125" title: "Compiler Warning (level 4) C4125" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4125" +ms.date: 11/04/2016 f1_keywords: ["C4125"] helpviewer_keywords: ["C4125"] -ms.assetid: a081d1f4-0789-4915-91df-7ff0b28ca245 --- # Compiler Warning (level 4) C4125 -decimal digit terminates octal escape sequence +> decimal digit terminates octal escape sequence + +## Remarks The compiler evaluates the octal number without the decimal digit and assumes the decimal digit is a character. ## Example +The following example generates C4125: + ```cpp // C4125a.cpp // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4127.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4127.md index 6edd099df73..b1187b11e15 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4127.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4127.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4127" title: "Compiler Warning (level 4) C4127" -ms.date: "10/16/2019" +description: "Learn more about: Compiler Warning (level 4) C4127" +ms.date: 10/16/2019 f1_keywords: ["C4127"] helpviewer_keywords: ["C4127"] -ms.assetid: f59ded9e-5227-45bd-ac43-2aa861581363 --- # Compiler Warning (level 4) C4127 @@ -16,9 +15,9 @@ The controlling expression of an **`if`** statement or **`while`** loop evaluate If the controlling expression of a **`while`** loop is a constant because the loop exits in the middle, consider replacing the **`while`** loop with a **`for`** loop. You can omit the initialization, termination test and loop increment of a **`for`** loop, which causes the loop to be infinite, just like `while(1)`, and you can exit the loop from the body of the **`for`** statement. -## Example +## Examples -The following sample shows two ways C4127 is generated, and shows how to use a for loop to avoid the warning: +The following example shows two ways C4127 is generated, and shows how to use a for loop to avoid the warning: ```cpp // C4127.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4130.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4130.md index b50e7d32d72..ab33396c73f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4130.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4130.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4130" title: "Compiler Warning (level 4) C4130" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4130" +ms.date: 11/04/2016 f1_keywords: ["C4130"] helpviewer_keywords: ["C4130"] -ms.assetid: 45e4c7b2-6b51-41c7-ba5e-941aa5c7d3dc --- # Compiler Warning (level 4) C4130 -'operator' : logical operation on address of string constant +> 'operator' : logical operation on address of string constant + +## Remarks Using the operator with the address of a string literal produces unexpected code. -The following sample generates C4130: +## Example + +The following example generates C4130: ```cpp // C4130.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4131.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4131.md index 4104ac0109e..d02d901579d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4131.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4131.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4131" title: "Compiler Warning (level 4) C4131" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4131" +ms.date: 11/04/2016 f1_keywords: ["C4131"] helpviewer_keywords: ["C4131"] -ms.assetid: 7903b3e1-454f-4be2-aa9b-230992f96a2d --- # Compiler Warning (level 4) C4131 -'function' : uses old-style declarator +> 'function' : uses old-style declarator + +## Remarks The specified function declaration is not in prototype form. Old-style function declarations should be converted to prototype form. +## Example + The following example shows an old-style function declaration: ```c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4132.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4132.md index 29b10b01926..a5cb7d8a4c9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4132.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4132.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4132" title: "Compiler Warning (level 4) C4132" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4132" +ms.date: 11/04/2016 f1_keywords: ["C4132"] helpviewer_keywords: ["C4132"] -ms.assetid: b60e5b4a-53ac-4503-8456-235477f48afd --- # Compiler Warning (level 4) C4132 -'object' : const object should be initialized +> 'object' : const object should be initialized + +## Remarks The constant is not initialized. The value of a symbol with the **`const`** attribute cannot be changed after its definition, it should be given an initialization value. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4152.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4152.md index 0209f54d2aa..de346a27ecd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4152.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4152.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4152" title: "Compiler Warning (level 4) C4152" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4152" +ms.date: 11/04/2016 f1_keywords: ["C4152"] helpviewer_keywords: ["C4152"] -ms.assetid: 6025ab70-d7cf-4730-913a-3ca0b1186a3a --- # Compiler Warning (level 4) C4152 -non standard extension, function/data ptr conversion in expression +> non standard extension, function/data ptr conversion in expression + +## Remarks A function pointer is converted to or from a data pointer. This conversion is allowed under Microsoft extensions (/Ze) but not under ANSI C. 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 7c3e2d6bf6a..93423778f89 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,34 +1,36 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4189" -title: "Compiler Warning (level 4) C4189" +title: "Compiler Warning (level 3 and level 4) C4189" +description: "Learn more about: 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 +## Remarks + A variable is declared and initialized but not used. ## Examples -The following sample generates C4189: +The following example generates C4189: ```cpp // 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-c4201.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4201.md index 1486e4023c5..ceebc5ca0a2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4201.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4201.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4201" title: "Compiler Warning (level 4) C4201" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4201" +ms.date: 11/04/2016 f1_keywords: ["C4201"] helpviewer_keywords: ["C4201"] -ms.assetid: 6156f508-9393-4d77-9e73-1ec3e1c32d0d --- # Compiler Warning (level 4) C4201 -nonstandard extension used : nameless struct/union +> nonstandard extension used : nameless struct/union + +## Remarks Under Microsoft extensions (/Ze), you can specify a structure without a declarator as members of another structure or union. These structures generate an error under ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)). ## Example +The following example generates C4201: + ```cpp // C4201.cpp // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4202.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4202.md index 4e740e1cfd7..a1ddd986de8 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4202.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4202.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4202" title: "Compiler Warning (level 4) C4202" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4202" +ms.date: 11/04/2016 f1_keywords: ["C4202"] helpviewer_keywords: ["C4202"] -ms.assetid: 253293aa-97a3-4878-a2e8-c6cc9e20b1cb --- # Compiler Warning (level 4) C4202 -nonstandard extension used : '...': prototype parameter in name list illegal +> nonstandard extension used : '...': prototype parameter in name list illegal + +## Remarks An old-style function definition contains variable arguments. These definitions generate an error under ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)). ## Example +The following example generates C4202: + ```c // C4202.c // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4204.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4204.md index 6b59366825f..9ad06ae599c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4204.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4204.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4204" title: "Compiler Warning (level 4) C4204" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4204" +ms.date: 11/04/2016 f1_keywords: ["C4204"] helpviewer_keywords: ["C4204"] -ms.assetid: 298d2880-6737-448e-b711-15572d540200 --- # Compiler Warning (level 4) C4204 -nonstandard extension used : non-constant aggregate initializer +> nonstandard extension used : non-constant aggregate initializer + +## Remarks With Microsoft extensions (/Ze), you can initialize aggregate types (arrays, structures, unions, and classes) with values that are not constants. ## Example +The following example generates C4204: + ```c // C4204.c // compile with: /W4 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 82848a4a960..0d25190bf0f 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,26 +1,29 @@ --- -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 -nonstandard extension used : static function declaration in function scope +> nonstandard extension used : static function declaration in function scope + +## Remarks With Microsoft extensions (/Ze), **`static`** functions can be declared inside another function. The function is given global scope. ## Example +The following example generates C4205: + ```c // C4205.c // compile with: /W4 void func1() { static int func2(); // C4205 -}; +} int main() { diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4206.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4206.md index 524ca3cc46d..606a827b03a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4206.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4206.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4206" title: "Compiler Warning (level 4) C4206" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4206" +ms.date: 11/04/2016 f1_keywords: ["C4206"] helpviewer_keywords: ["C4206"] -ms.assetid: 3df97812-3ed7-4003-9769-057acf97ce3c --- # Compiler Warning (level 4) C4206 -**nonstandard extension used : translation unit is empty** +> nonstandard extension used : translation unit is empty + +## Remarks The file was empty after preprocessing. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4207.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4207.md index 42e3e542084..0d9439f1572 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4207.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4207.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4207" title: "Compiler Warning (level 4) C4207" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4207" +ms.date: 11/04/2016 f1_keywords: ["C4207"] helpviewer_keywords: ["C4207"] -ms.assetid: f4e09e3e-ac87-4489-8e3f-c8f76b82e721 --- # Compiler Warning (level 4) C4207 -nonstandard extension used : extended initializer form +> nonstandard extension used : extended initializer form + +## Remarks With Microsoft extensions (/Ze), you can initialize an unsized array of **`char`** using a string within braces. ## Example +The following example generates C4207: + ```c // C4207.c // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4208.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4208.md index 401c638542e..2c0de261003 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4208.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4208.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4208" title: "Compiler Warning (level 4) C4208" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4208" +ms.date: 11/04/2016 f1_keywords: ["C4208"] helpviewer_keywords: ["C4208"] -ms.assetid: 5cb0a36e-3fb5-422f-a5f9-e40b70776c27 --- # Compiler Warning (level 4) C4208 -nonstandard extension used : delete [exp] - exp evaluated but ignored +> nonstandard extension used : delete [exp] - exp evaluated but ignored + +## Remarks With Microsoft extensions (/Ze), you can delete an array using a value within brackets with the [delete operator](../../cpp/delete-operator-cpp.md). The value is ignored. +## Example + +The following example generates C4208: + ```cpp // C4208.cpp // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4210.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4210.md index ba96a096f66..95522de60e4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4210.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4210.md @@ -1,17 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4210" title: "Compiler Warning (level 4) C4210" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4210" +ms.date: 11/04/2016 f1_keywords: ["C4210"] helpviewer_keywords: ["C4210"] -ms.assetid: f8600adf-dfe2-4022-a37a-3d4997641dfd --- # Compiler Warning (level 4) C4210 -nonstandard extension used : function given file scope +> nonstandard extension used : function given file scope + +## Remarks With the default Microsoft extensions ([/Ze](../../build/reference/za-ze-disable-language-extensions.md)), function declarations have file scope. +## Example + +The following example generates C4210: + ```c // C4210.c // compile with: /W4 /c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4211.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4211.md index 59e1af613ce..98e88e30c24 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4211.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4211.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4211" title: "Compiler Warning (level 4) C4211" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4211" +ms.date: 11/04/2016 f1_keywords: ["C4211"] helpviewer_keywords: ["C4211"] -ms.assetid: 3eea3455-6faa-4cdb-8730-73db7026bd1f --- # Compiler Warning (level 4) C4211 -nonstandard extension used : redefined extern to static +> nonstandard extension used : redefined extern to static + +## Remarks With the default Microsoft extensions (/Ze), you can redefine an **`extern`** identifier as **`static`**. ## Example +The following example generates C4211: + ```c // C4211.c // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4212.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4212.md index d780d7bba34..4509562c90a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4212.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4212.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4212" title: "Compiler Warning (level 4) C4212" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4212" +ms.date: 11/04/2016 f1_keywords: ["C4212"] helpviewer_keywords: ["C4212"] -ms.assetid: df781ea1-182d-4f9f-9a31-55b6ce80c711 --- # Compiler Warning (level 4) C4212 -nonstandard extension used : function declaration used ellipsis +> nonstandard extension used : function declaration used ellipsis + +## Remarks The function prototype has a variable number of arguments. The function definition does not. -The following sample generates C4212: +## Example + +The following example generates C4212: ```c // C4212.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4213.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4213.md index e36443c5d57..eda0670bcba 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4213.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4213.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4213" title: "Compiler Warning (level 4) C4213" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4213" +ms.date: 11/04/2016 f1_keywords: ["C4213"] helpviewer_keywords: ["C4213"] -ms.assetid: 59fc3f61-ebd2-499e-99d7-f57bec11eda1 --- # Compiler Warning (level 4) C4213 -nonstandard extension used : cast on l-value +> nonstandard extension used : cast on l-value + +## Remarks With the default Microsoft extensions (/Ze), you can use casts on the left side of an assignment statement. ## Example +The following example generates C4213: + ```c // C4213.c // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4214.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4214.md index 06fb277525e..26e6071374a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4214.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4214.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4214" title: "Compiler Warning (level 4) C4214" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4214" +ms.date: 11/04/2016 f1_keywords: ["C4214"] helpviewer_keywords: ["C4214"] -ms.assetid: 9b8db279-1f12-4a6b-a923-2db22acd1947 --- # Compiler Warning (level 4) C4214 -nonstandard extension used : bit field types other than int +> nonstandard extension used : bit field types other than int + +## Remarks With the default Microsoft extensions (/Ze), bitfield structure members can be of any integer type. ## Example +The following example generates C4214: + ```c // C4214.c // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4220.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4220.md index bf894af5583..2eba4fa6522 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4220.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4220.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4220" title: "Compiler Warning (level 4) C4220" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4220" +ms.date: 11/04/2016 f1_keywords: ["C4220"] helpviewer_keywords: ["C4220"] -ms.assetid: aba18868-825f-4763-9af6-3296406a80e4 --- # Compiler Warning (level 4) C4220 -varargs matches remaining parameters +> varargs matches remaining parameters + +## Remarks Under the default Microsoft extensions (/Ze), a pointer to a function matches a pointer to a function with similar, but variable, arguments. ## Example +The following example generates C4220: + ```c // C4220.c // compile with: /W4 @@ -23,7 +26,7 @@ int ( *pFunc2) ( int a, int b); int main() { - if ( pFunc1 != pFunc2 ) {}; // C4220 + if ( pFunc1 != pFunc2 ) {} // C4220 } ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4221.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4221.md index e88f2068aa2..95c742a069a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4221.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4221.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4221" title: "Compiler Warning (level 4) C4221" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4221" +ms.date: 11/04/2016 f1_keywords: ["C4221"] helpviewer_keywords: ["C4221"] -ms.assetid: 8532bd68-54dc-4526-8597-f61dcb0a0129 --- # Compiler Warning (level 4) C4221 -nonstandard extension used : 'identifier' : cannot be initialized using address of automatic variable +> nonstandard extension used : 'identifier' : cannot be initialized using address of automatic variable + +## Remarks With the default Microsoft extensions (/Ze), you can initialize an aggregate type (**array**, **`struct`**, or **`union`**) with the address of a local (automatic) variable. ## Example +The following example generates C4221: + ```c // C4221.c // compile with: /W4 diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4232.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4232.md index 78d4e5ed200..392aa103b9b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4232.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4232.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4232" title: "Compiler Warning (level 4) C4232" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4232" +ms.date: 11/04/2016 f1_keywords: ["C4232"] helpviewer_keywords: ["C4232"] -ms.assetid: f92028a5-4ddd-43c1-97f5-4f724e5e14af --- # Compiler Warning (level 4) C4232 -nonstandard extension used : 'identifier' : address of dllimport 'dllimport' is not static, identity not guaranteed +> nonstandard extension used : 'identifier' : address of dllimport 'dllimport' is not static, identity not guaranteed + +## Remarks Under Microsoft extensions (/Ze), you can give a nonstatic value as the address of a function declared with the **`dllimport`** modifier. Under ANSI compatibility ([/Za](../../build/reference/za-ze-disable-language-extensions.md)), this causes an error. -The following sample generates C4232: +## Example + +The following example generates C4232: ```c // C4232.c 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 92cb29c0fe5..0ada63cf907 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,16 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4233" -title: "Compiler Warning (level 4) C4233" -ms.date: "10/25/2017" +title: "Compiler Warning (level 1, Error) C4233" +description: "Learn more about: 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). +## Remarks -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: +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). -```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-c4234.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4234.md index 3b2bc5eacb5..65c487e016e 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4234.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4234.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4234" title: "Compiler Warning (level 4) C4234" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4234" +ms.date: 11/04/2016 f1_keywords: ["C4234"] helpviewer_keywords: ["C4234"] -ms.assetid: f7fecd5c-8248-4fde-8446-502aedc357ca --- # Compiler Warning (level 4) C4234 -nonstandard extension used: 'keyword' keyword reserved for future use +> nonstandard extension used: 'keyword' keyword reserved for future use + +## Remarks The compiler does not yet implement the keyword you used. 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 4c75a0cdcac..b1fa9f92226 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,30 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4235" -title: "Compiler Warning (level 4) C4235" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1, Error) C4235" +description: "Learn more about: Compiler Warning (level 1, Error) C4235" +ms.date: 07/27/2025 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. +## Remarks -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 +The compiler doesn't support the keyword you used on the architecture your build is targeting. For example, the [`__asm`](../../assembler/inline/asm.md) keyword is not supported in x64 builds. + +This warning is always issued as an error. Use the [warning](../../preprocessor/warning.md) pragma to disable. + +## Example + +The following example generates C4235 as the [Inline Assembler](../../assembler/inline/inline-assembler.md) is only supported on x86: ```cpp -#pragma warning(2:4235) -``` +// C4235.cpp +// processor: x64 (set compiler environment with vcvars64.bat) -in your source code file. +int main() +{ + __asm nop // C4235 +} +``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4238.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4238.md index 679d603ef69..686daa1f665 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4238.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4238.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4238" title: "Compiler Warning (level 4) C4238" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4238" +ms.date: 11/04/2016 f1_keywords: ["C4238"] helpviewer_keywords: ["C4238"] -ms.assetid: 5d4051d3-7b0f-43ea-8c8d-d194bfdceb71 --- # Compiler Warning (level 4) C4238 -nonstandard extension used : class rvalue used as lvalue +> nonstandard extension used : class rvalue used as lvalue + +## Remarks For compatibility with previous versions of Visual C++, Microsoft extensions (**/Ze**) allow you to use a class type as an rvalue in a context that implicitly or explicitly takes its address. In some cases, such as the example below, this can be dangerous. ## Example +The following example generates C4238: + ```cpp // C4238.cpp // compile with: /W4 /c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4239.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4239.md index c68de7e669a..ead032c4b05 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4239.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4239.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4239" title: "Compiler Warning (level 4) C4239" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4239" +ms.date: 11/04/2016 f1_keywords: ["C4239"] helpviewer_keywords: ["C4239"] -ms.assetid: a23dc16a-649e-4870-9a24-275de1584fcd --- # Compiler Warning (level 4) C4239 -nonstandard extension used : 'token' : conversion from 'type' to 'type' +> nonstandard extension used : 'token' : conversion from 'type' to 'type' + +## Remarks This type conversion is not allowed by the C++ standard, but it is permitted here as an extension. This warning is always followed by at least one line of explanation describing the language rule being violated. ## Examples -The following sample generates C4239. +The following example generates C4239. ```cpp // C4239.cpp @@ -32,7 +33,7 @@ void func(void) { Conversion from integral type to enum type is not strictly allowed. -The following sample generates C4239. +The following example generates C4239. ```cpp // C4239b.cpp 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 21960637822..e122d51b7c7 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,22 +1,25 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4242" -title: "Compiler Warning (level 4) C4242" -ms.date: "11/04/2016" +title: "Compiler Warning (level 3, off) C4242" +description: "Learn more about: 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 + +## Remarks 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 more information on C4242, see [Common Compiler Errors](/windows/win32/WinProg64/common-compiler-errors). -For additional information on C4242, see [Common Compiler Errors](/windows/win32/WinProg64/common-compiler-errors). +## Example -The following sample generates C4242: +The following example generates C4242: ```cpp // C4242.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4245.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4245.md index 45dd045a043..051b3240354 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4245.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4245.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4245" title: "Compiler Warning (level 4) C4245" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4245" +ms.date: 11/04/2016 f1_keywords: ["C4245"] helpviewer_keywords: ["C4245"] -ms.assetid: 85083d53-9cc2-4d12-b58c-6dad28f15cbe --- # Compiler Warning (level 4) C4245 > '*conversion*' : conversion from '*type1*' to '*type2*', signed/unsigned mismatch +## Remarks + You tried to convert a **`signed const`** type that has a negative value to an **`unsigned`** type. -The following sample generates C4245: +## Example + +The following example generates C4245: ```cpp // C4245.cpp 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 a5a4987a122..03aa6d9f421 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,20 +1,23 @@ --- -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 + +## Remarks 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). + +## Example -The following sample generates C4254: +The following example generates C4254: ```cpp // C4254.cpp @@ -32,5 +35,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 ff98dea558b..0627f04d951 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4255" -title: "Compiler Warning (level 4) C4255" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4255" +description: "Learn more about: 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. +## Remarks -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. +The compiler didn't find an explicit list of arguments to a function. This warning is for the C compiler only. -The following sample generates C4255: +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 + +The following example generates C4255: ```c // C4255.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4256.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4256.md index 8ce1d40f266..c7a310e4c0d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4256.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4256.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4256" title: "Compiler Warning (level 4) C4256" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4256" +ms.date: 11/04/2016 f1_keywords: ["C4256"] helpviewer_keywords: ["C4256"] -ms.assetid: a755a32e-895a-4837-a2b5-4ea06b736798 --- # Compiler Warning (level 4) C4256 -'function' : constructor for class with virtual bases has '...'; calls may not be compatible with older versions of Visual C++ +> 'function' : constructor for class with virtual bases has '...'; calls may not be compatible with older versions of Visual C++ + +## Remarks Possible incompatibility. @@ -20,7 +21,9 @@ To fix this warning, 1. Make sure that all components in their project are built with the current version (including any libraries that may define or reference this class), then disable the warning using the [warning](../../preprocessor/warning.md) pragma. -The following sample generates C4256: +## Example + +The following example generates C4256: ```cpp // C4256.cpp 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 7fa9923092f..a12a0c9846e 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4263" -title: "Compiler Warning (level 4) C4263" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4263" +description: "Learn more about: 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. +## Remarks -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. +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. -The following sample generates C4263: +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 + +The following example generates C4263: ```cpp // C4263.cpp 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 fccff4b84fa..9d1dcb0c856 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4266" -title: "Compiler Warning (level 4) C4266" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4266" +description: "Learn more about: 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. +## Remarks -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. +A derived class didn't override all overloads of a virtual function. -The following sample generates C4266: +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 + +The following example generates C4266: ```cpp // C4266.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4268.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4268.md index 7ec668928d4..1ec1be39767 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4268.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4268.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4268" title: "Compiler Warning (level 4) C4268" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4268" +ms.date: 11/04/2016 f1_keywords: ["C4268"] helpviewer_keywords: ["C4268"] -ms.assetid: d0511e80-904f-4ee1-b4d7-39b5c0bd8234 --- # Compiler Warning (level 4) C4268 -'identifier' : 'const' static/global data initialized with compiler generated default constructor fills the object with zeros +> 'identifier' : 'const' static/global data initialized with compiler generated default constructor fills the object with zeros + +## Remarks A **`const`** global or static instance of a non-trivial class is initialized with a compiler-generated default constructor. ## Example +The following example generates C4268: + ```cpp // C4268.cpp // compile with: /c /LD /W4 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 3f29ff0cfa7..62b99960d88 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,22 +1,25 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4289" -title: "Compiler Warning (level 4) C4289" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4289" +description: "Learn more about: 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. +## Remarks + +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). + +## Example -The following sample generates C4289: +The following example generates C4289: ```cpp // C4289.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4295.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4295.md index f14ac9570c2..05a88c4b3b7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4295.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4295.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4295" title: "Compiler Warning (level 4) C4295" -ms.date: "01/09/2018" +description: "Learn more about: Compiler Warning (level 4) C4295" +ms.date: 01/09/2018 f1_keywords: ["C4295"] helpviewer_keywords: ["C4295"] -ms.assetid: 20dbff85-9f62-4ca3-8fe9-079d4512006d --- # Compiler Warning (level 4) C4295 > '*array*' : array is too small to include a terminating null character +## Remarks + An array was initialized but the last character in the array is not a null; accessing the array as a string may produce unexpected results. ## Example -The following sample generates C4295. To fix this issue, you could declare the array size larger, to hold a terminating null from the initializer string, or you could use an array initializer list to make the intent clear that this is an array of **`char`**, not a null-terminated string. +The following example generates C4295. To fix this issue, you could declare the array size larger, to hold a terminating null from the initializer string, or you could use an array initializer list to make the intent clear that this is an array of **`char`**, not a null-terminated string. ```C // C4295.c 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 eb4f2ed99ee..3f8d63d993a 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4296" -title: "Compiler Warning (level 4) C4296" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4296" +description: "Learn more about: 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 + +## Remarks 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). + +## Example -The following sample generates C4296: +The following example generates C4296: ```cpp // C4296.cpp 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 f50703025a2..0d36a85e2ca 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 @@ -1,28 +1,49 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4324" title: "Compiler Warning (level 4) C4324" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4324" +ms.date: 07/22/2025 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()) +> '*type*': structure was padded due to alignment specifier + +## Remarks -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 class/struct/union because you specified an alignment specifier, such as [`alignas`](../../cpp/alignas-specifier.md) or [`__declspec(align)`](../../cpp/align-cpp.md). -For example, the following code generates C4324: +## Example + +For example, `S1`, `U1`, and `C1` generate C4324 because padding is added when the specified alignment is greater than the natural alignment for each. `S2` doesn't generate a warning because the specified alignment matches the natural alignment: ```cpp // C4324.cpp -// compile with: /W4 -struct __declspec(align(32)) A +// compile with: /W4 /c + +// natural 4 byte alignment +struct alignas(8) S1 // C4324 { - char a; + int i; }; // C4324 -int main() +// natural 4 byte alignment +struct alignas(4) S2 +{ + int i; +}; // OK + +// natural 4 byte alignment +union alignas(16) U1 +{ + int i; + char c; +}; // C4324 + +// natural 4 byte alignment +class alignas(8) C1 { -} +public: + int i = 0; +}; // C4324 ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4336.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4336.md index 4a777866930..2506a4b3f12 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4336.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4336.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4336" title: "Compiler Warning (level 4) C4336" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4336" +ms.date: 11/04/2016 f1_keywords: ["C4336"] helpviewer_keywords: ["C4336"] -ms.assetid: 93f199dd-d6dd-42c0-82d8-c12d101a7235 --- # Compiler Warning (level 4) C4336 -import cross-referenced type library 'type_lib1' before importing 'type_lib2' +> import cross-referenced type library 'type_lib1' before importing 'type_lib2' + +## Remarks A type library was referenced with the [#import](../../preprocessor/hash-import-directive-cpp.md) directive. However, the type library contained a reference to another type library that was not referenced with `#import`. This other .tlb file was found by the compiler. +## Example + Given two type libraries on disk created from the following two files (compiled with midl.exe): ``` @@ -43,7 +46,7 @@ library C4336bLib }; ``` -The following sample generates C4336: +The following example generates C4336: ```cpp // C4336.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4337.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4337.md index ada48dd852b..6d7bd6bc2d7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4337.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4337.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4337" title: "Compiler Warning (level 4) C4337" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4337" +ms.date: 11/04/2016 f1_keywords: ["C4337"] helpviewer_keywords: ["C4337"] -ms.assetid: 70bc72d9-aac5-45cd-abd3-ebe42a05897b --- # Compiler Warning (level 4) C4337 -cross-referenced type library 'typelib1' in 'typelib2' is being automatically imported +> cross-referenced type library 'typelib1' in 'typelib2' is being automatically imported + +## Remarks The auto_search attribute of [the #import directive](../../preprocessor/hash-import-directive-cpp.md) caused a type library to be implicitly imported. +## Example + Given two type libraries on disk created from the following two files (compiled with midl.exe): ``` @@ -51,7 +54,7 @@ library C4337bLib }; ``` -The following sample generates C4337: +The following example generates C4337: ```cpp // C4337.cpp 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 4b868b05e11..5b6c4e3b290 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,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4339" -title: "Compiler Warning (level 4) C4339" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4339" +description: "Learn more about: 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. +## Remarks -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. +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. -The following sample generates C4339 and shows how to fix it: +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 + +The following example generates C4339 and shows how to fix it: ```cpp // C4339.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4343.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4343.md index 57b03021c75..675978f9976 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4343.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4343.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4343" title: "Compiler Warning (level 4) C4343" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4343" +ms.date: 11/04/2016 f1_keywords: ["C4343"] helpviewer_keywords: ["C4343"] -ms.assetid: a721b710-e04f-4d15-b678-e4a2c8fd0181 --- # Compiler Warning (level 4) C4343 -\#pragma optimize("g",off) overrides /Og option +> #pragma optimize("g",off) overrides /Og option + +## Remarks This warning, only valid in the Itanium Processor Family (IPF) compiler, reports that a pragma [optimize](../../preprocessor/optimize.md) overrode a [/Og](../../build/reference/og-global-optimizations.md) compiler option. -The following sample generates C4343: +## Example + +The following example generates C4343: ```cpp // C4343.cpp 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 931b249b132..25320e16d28 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,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4365" -title: "Compiler Warning (level 4) C4365" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4365" +description: "Learn more about: 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. +## Remarks -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). +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). ## Example -The following sample generates C4365. +The following example generates C4365. ```cpp // C4365.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4366.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4366.md index 8ffd8a63f5d..91679dc7baf 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4366.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4366.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4366" title: "Compiler Warning (level 4) C4366" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4366" +ms.date: 11/04/2016 f1_keywords: ["C4366"] helpviewer_keywords: ["C4366"] -ms.assetid: 65d2942f-3741-42f4-adf2-4920d5a055ca --- # Compiler Warning (level 4) C4366 -The result of the unary 'operator' operator may be unaligned +> The result of the unary 'operator' operator may be unaligned + +## Remarks If a structure member could ever be unaligned because of packing, the compiler will warn when that member's address is assigned to an aligned pointer. By default, all pointers are aligned. @@ -18,7 +19,7 @@ For more information, see __unaligned and [pack](../../preprocessor/pack.md). ## Example -The following sample generates C4366. +The following example generates C4366. ```cpp // C4366.cpp 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 77af090278b..0de7bed8b0d 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,23 +1,23 @@ --- 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 > '*equality-operator*' : signed/unsigned mismatch -An **`==`** or **`!=`** operation involved **`signed`** and **`unsigned`** variables. This could result in a loss of data. - ## Remarks +An **`==`** or **`!=`** operation involved **`signed`** and **`unsigned`** variables. This could result in a loss of data. + One way to fix this warning is if you cast one of the two types when you compare **`signed`** and **`unsigned`** types. ## Example -The following sample generates C4389: +The following example generates C4389: ```cpp // C4389.cpp 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 071fc9c192d..75de9e5fcd0 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,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4400" -title: "Compiler Warning (level 4) C4400" -ms.date: "11/04/2016" +title: "Compiler warning (level 4, error) C4400" +description: "Learn more about: 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. +## Remarks + +The [`const`](../../cpp/const-cpp.md) and [`volatile`](../../cpp/volatile-cpp.md) qualifiers don't work with common language runtime typed variables. ## Example -The following sample generates C4400. +The following example generates C4400. ```cpp // C4400.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4408.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4408.md index b41f58b75a0..80c566c3d8a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4408.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4408.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4408" title: "Compiler Warning (level 4) C4408" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4408" +ms.date: 11/04/2016 f1_keywords: ["C4408"] helpviewer_keywords: ["C4408"] -ms.assetid: 8488a186-ed1d-425c-aaeb-c72472c1da68 --- # Compiler Warning (level 4) C4408 -anonymousstruct or union did not declare any data members +> anonymousstruct or union did not declare any data members + +## Remarks An anonymous struct or union must have at least one data member. -The following sample generates C4408: +## Example + +The following example generates C4408: ```cpp // C4408.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4429.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4429.md index 145ec9b1aa3..f4fae6bd4dc 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4429.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4429.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4429" title: "Compiler Warning (level 4) C4429" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4429" +ms.date: 11/04/2016 f1_keywords: ["C4429"] helpviewer_keywords: ["C4429"] -ms.assetid: a3e4cf1f-a869-4e47-834a-850c21eb5297 --- # Compiler Warning (level 4) C4429 -possible incomplete or improperly formed universal-character-name +> possible incomplete or improperly formed universal-character-name + +## Remarks The compiler detected a character sequence that may be a badly formed universal character name. A universal character name is `\u` followed by four hex digits, or `\U` followed by eight hex digits. -The following sample generates C4429: +## Example + +The following example generates C4429: ```cpp // C4429.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4431.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4431.md index bba0bbce56a..68660c09337 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4431.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4431.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4431" title: "Compiler Warning (level 4) C4431" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4431" +ms.date: 11/04/2016 f1_keywords: ["C4431"] helpviewer_keywords: ["C4431"] -ms.assetid: 58434ab6-dd8d-427b-953a-602fb7453ae6 --- # Compiler Warning (level 4) C4431 -missing type specifier - int assumed. Note: C no longer supports default-int +> missing type specifier - int assumed. Note: C no longer supports default-int + +## Remarks This error can be generated as a result of compiler conformance work that was done for Visual Studio 2005: Visual C++ no longer creates untyped identifiers as int by default. The type of an identifier must be specified explicitly. @@ -16,7 +17,7 @@ This warning is off by default. See [Compiler Warnings That Are Off by Default]( ## Example -The following sample generates C4431. +The following example generates C4431. ```c // C4431.c diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4434.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4434.md index 0315bf031dc..6b7e6b52ba9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4434.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4434.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4434" title: "Compiler Warning (level 4) C4434" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4434" +ms.date: 11/04/2016 f1_keywords: ["C4434"] helpviewer_keywords: ["C4434"] -ms.assetid: 24b8785e-353a-4c37-8bed-ed61001a871d --- # Compiler Warning (level 4) C4434 -a class constructor must have private accessibility; changing to private access +> a class constructor must have private accessibility; changing to private access + +## Remarks C4434 indicates that the compiler changed the accessibility of a static constructor. Static constructors must have private accessibility, as they are only meant to be called by the common language runtime. For more information, see [Static constructors](../../dotnet/how-to-define-and-consume-classes-and-structs-cpp-cli.md#BKMK_Static_constructors). ## Example -The following sample generates C4434. +The following example generates C4434. ```cpp // C4434.cpp 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 c60d859b888..aa094d91d24 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,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4435" -title: "Compiler Warning (level 4) C4435" -ms.date: "11/04/2016" +title: "Compiler Warning (level 4, off) C4435" +description: "Learn more about: 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. +## Remarks -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. +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 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 -The following sample generates C4435. +The following example generates C4435. ```cpp // C4435.cpp @@ -34,5 +35,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 a2207a1ad8e..5e09076edc4 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,30 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4437" -title: "Compiler Warning (level 4) C4437" -ms.date: "11/04/2016" +title: "Compiler warning (level 1 and level 4, off) C4437" +description: "Learn more about: 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. +## Remarks -The compiler has encountered a **`dynamic_cast`** operation with the following characteristics. +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 cast is from a base class pointer to a derived class pointer. +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 example generates C4437 and demonstrates the code generation issue that arises from the missing `vtordisp` field: ```cpp // C4437.cpp @@ -76,6 +74,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-c4456.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4456.md index 3860789485b..a86eb36dd45 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4456.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4456.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4456" title: "Compiler Warning (level 4) C4456" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4456" +ms.date: 11/04/2016 f1_keywords: ["C4456"] helpviewer_keywords: ["C4456"] -ms.assetid: 5ab39fc1-0e19-461b-842b-4da80560b044 --- # Compiler Warning (level 4) C4456 > declaration of '*identifier*' hides previous local declaration +## Remarks + The declaration of *identifier* in the local scope hides the declaration of the previous local declaration of the same name. This warning lets you know that references to *identifier* in the local scope resolve to the locally declared version, not the previous local, which may or may not be your intent. To fix this issue, we recommend you give local variables names that do not conflict with other local names. ## Example -The following sample generates C4456 because the loop control variable `int x` and the local variable `double x` in `member_fn` have the same names. To fix this issue, use different names for the local variables. +The following example generates C4456 because the loop control variable `int x` and the local variable `double x` in `member_fn` have the same names. To fix this issue, use different names for the local variables. ```cpp // C4456_hide.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4457.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4457.md index af7a117ea6a..7f39af8da85 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4457.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4457.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4457" title: "Compiler Warning (level 4) C4457" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4457" +ms.date: 11/04/2016 f1_keywords: ["C4457"] helpviewer_keywords: ["C4457"] -ms.assetid: 02fd149a-917d-4f67-97a6-eb714572271f --- # Compiler Warning (level 4) C4457 > declaration of '*identifier*' hides function parameter +## Remarks + The declaration of *identifier* in the local scope hides the declaration of the identically-named function parameter. This warning lets you know that references to *identifier* in the local scope resolve to the locally declared version, not the parameter, which may or may not be your intent. To fix this issue, we recommend you give local variables names that do not conflict with parameter names. ## Example -The following sample generates C4457 because the parameter `x` and the local variable `x` in `member_fn` have the same names. To fix this issue, use different names for the parameters and local variables. +The following example generates C4457 because the parameter `x` and the local variable `x` in `member_fn` have the same names. To fix this issue, use different names for the parameters and local variables. ```cpp // C4457_hide.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4458.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4458.md index 0aaf058dd0c..c1189b04ffb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4458.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4458.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4458" title: "Compiler Warning (level 4) C4458" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4458" +ms.date: 11/04/2016 f1_keywords: ["C4458"] helpviewer_keywords: ["C4458"] -ms.assetid: 7bdaa1b1-0caf-4d68-98c4-6bdd441c23fb --- # Compiler Warning (level 4) C4458 > declaration of '*identifier*' hides class member +## Remarks + The declaration of *identifier* in the local scope hides the declaration of the identically-named *identifier* at class scope. This warning lets you know that references to *identifier* in this scope resolve to the locally declared version, not the class member version, which may or may not be your intent. To fix this issue, we recommend you give local variables names that do not conflict with class member names. ## Example -The following sample generates C4458 because the parameter `x` and the local variable `y` in `member_fn` have the same names as data members in the class. To fix this issue, use different names for the parameters and local variables. +The following example generates C4458 because the parameter `x` and the local variable `y` in `member_fn` have the same names as data members in the class. To fix this issue, use different names for the parameters and local variables. ```cpp // C4458_hide.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4459.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4459.md index ec827f8b2f7..417dfe669c4 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4459.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4459.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4459" title: "Compiler Warning (level 4) C4459" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4459" +ms.date: 11/04/2016 f1_keywords: ["C4459"] helpviewer_keywords: ["C4459"] -ms.assetid: ee9f6287-9c70-4b10-82a0-add82a13997f --- # Compiler Warning (level 4) C4459 > declaration of '*identifier*' hides global declaration +## Remarks + The declaration of *identifier* in the local scope hides the declaration of the identically-named *identifier* in global scope. This warning lets you know that references to *identifier* in this scope resolve to the locally declared version, not the global version, which may or may not be your intent. Generally, we recommend you minimize the use of global variables as a good engineering practice. To minimize pollution of the global namespace, we recommend use of a named namespace for global variables. This warning was new in Visual Studio 2015, in Microsoft C++ compiler version 18.00. To suppress warnings from that version of the compiler or later while migrating your code, use the [/Wv:18](../../build/reference/compiler-option-warning-level.md) compiler option. ## Example -The following sample generates C4459: +The following example generates C4459: ```cpp // C4459_hide.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4460.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4460.md index 6a990f6f678..df25079de59 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4460.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4460.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4460" title: "Compiler Warning (level 4) C4460" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4460" +ms.date: 11/04/2016 f1_keywords: ["C4460"] helpviewer_keywords: ["C4460"] -ms.assetid: c97ac1c9-598d-479e-bfff-c993690c4f3d --- # Compiler Warning (level 4) C4460 -WinRT or CLR operator 'operator', has parameter passed by reference. WinRT or CLR operator 'operator' has different semantics from C++ operator 'operator', did you intend to pass by value? +> WinRT or CLR operator 'operator', has parameter passed by reference. WinRT or CLR operator 'operator' has different semantics from C++ operator 'operator', did you intend to pass by value? + +## Remarks You passed a value by reference to a user-defined Windows Runtime or CLR operator. If the value is changed inside the function, note that the value returned after the function call will be assigned the return value of the function. In standard C++, the changed value is reflected after the function call. ## Example -The following sample generates C4460 and shows how to fix it. +The following example generates C4460 and shows how to fix it. ```cpp // C4460.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4463.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4463.md index 11df8f1e4da..ea4619ef50c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4463.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4463.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4463" title: "Compiler Warning (level 4) C4463" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4463" +ms.date: 11/04/2016 f1_keywords: ["C4463"] helpviewer_keywords: ["C4463"] -ms.assetid: a07ae70c-db4e-472b-8b58-9137d9997323 --- # Compiler Warning (level 4) C4463 > overflow; assigning *value* to bit-field that can only hold values from *low_value* to *high_value* +## Remarks + The assigned *value* is outside the range of values that the bit-field can hold. Signed bit-field types use the high-order bit for the sign, so if *n* is the bit-field size, the range for signed bit-fields is -2n-1 to 2n-1-1, while unsigned bit-fields have a range from 0 to 2n-1. ## Example diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md index de023ee9076..ed8362ff037 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4464.md @@ -1,30 +1,44 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4464" title: "Compiler Warning (level 4) C4464" -ms.date: "03/13/2018" +description: "Learn more about: Compiler Warning (level 4, off) C4464" +ms.date: 09/14/2022 f1_keywords: ["C4464"] helpviewer_keywords: ["C4464"] --- -# Compiler Warning (level 4) C4464 +# Compiler Warning (level 4, off) C4464 -> **relative include path contains '..'** - -A `#include` directive has a path that includes a '..' parent directory specifier. +> relative include path contains '..' ## Remarks -Starting in Visual Studio 2015 Update 1, the compiler can detect an include directive that contains a '..' path segment and issue a warning, if enabled. Code written in this way is usually intended to include headers that exist outside of the project by incorrectly using project-relative paths. This creates a risk that the program could be compiled by including a different source file than the programmer intends, or that these relative paths would not be portable to other build environments. Although there is no specific warning for it, we also recommend that you do not use a parent directory path segment to specify your project include directories. +A `#include` directive has a path that includes a parent directory specifier (a `..` path segment). + +In Visual Studio 2015 Update 1 and later versions, if enabled, the compiler can detect and issue a warning for a `#include` directive that contains a parent directory path segment (`..`). Code is sometimes written that uses parent directory relative paths to include headers from external libraries. When these parent directory-relative header paths are specified in source files, it creates a risk: The program could be compiled by including a different header file than the programmer intends. These relative paths may not be portable to other developers' build environments. -This warning is new in Visual Studio 2015 Update 1, and is off by default. Use [/Wall](../../build/reference/compiler-option-warning-level.md) to enable all warnings that are off by default, or __/w__*n*__4464__ to enable C4464 as a level *n* warning. For more information, see [Compiler Warnings That Are Off By Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). For information on how to disable warnings by compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). +Instead, we recommend you specify the paths to such headers in the build environment, such as in the `INCLUDE` environment variable or in parameters to the [`/I` (Additional include directories)](../../build/reference/i-additional-include-directories.md) compiler option. In the Visual Studio IDE, you can set the paths in your project's **Configuration Properties** > **C/C++** > **General** property page, in the **Additional Include Directories** property. Although there's no specific warning for it, we also don't recommend use of parent directory path segments when you specify your project's include directories. + +Warning C4464 is new in Visual Studio 2015 Update 1, and is off by default. Use [`/Wall`](../../build/reference/compiler-option-warning-level.md) to enable all warnings that are off by default. Use **`/wN4464`** to enable C4464 as a level `N` warning (where `N` is 1-4). For more information, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). For information on how to disable warnings introduced in or after a specific compiler version, see [Compiler warnings by compiler version](compiler-warnings-by-compiler-version.md). ## Example -Source code files that use '..' path segments can trigger this warning when the **/Wall** option is specified: +Source code files that use `..` path segments in `#include` directives can trigger this warning when C4464 is enabled or when the **`/Wall`** option is specified. + +In this example, the project source is in *`C:\project\source`* and an external library's header files are in *`C:\other_lib\headers`*: ```cpp -#include "..\headers\C4426.h" // emits warning C4464 +// C:\project\source\C4464.cpp +// Compile by using: cl /w14464 C4464.cpp +#include "..\..\other_lib\headers\other.h" // C4464 +#include "..\..\other_lib\headers\extras\nested.h" // C4464 +// . . . +``` + +To fix this issue, add the path *`C:\other_lib\headers`* to your project's include directories. Then, change the source to include the header files as external headers: -// To fix this issue, specify only the header file name, and add -// the absolute path to 'headers\' to your project's include directories -#include "C4426.h" +```cpp +// C:\project\source\C4464b.cpp +// Compile by using: cl /w14464 /I"C:\other_lib\headers" C4464b.cpp +#include // OK +#include // OK +// . . . ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md index 958561ae411..fdba3fbfe5b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4471.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4471" title: "Compiler Warning (level 4) C4471" -ms.date: "04/24/2017" +description: "Learn more about: Compiler Warning (level 4) C4471" +ms.date: 04/24/2017 f1_keywords: ["C4471"] helpviewer_keywords: ["C4471"] -ms.assetid: ccfd8bd5-bc1b-4be7-a6ea-0e3a7add6607 --- # Compiler Warning (level 4) C4471 -'*enumeration*': a forward declaration of an unscoped enumeration must have an underlying type (int assumed) +> '*enumeration*': a forward declaration of an unscoped enumeration must have an underlying type (int assumed) + +## Remarks A forward declaration of an unscoped enumeration was found without a specifier for the underlying type. By default, Visual C++ assumes **`int`** is the underlying type for an enumeration. This can cause issues if a different type is used in the enumeration definition, for example, if a different explicit type is specified, or if a different type is implicitly set by an initializer. You may also have portability issues; other compilers do not assume **`int`** is the underlying type of an enumeration. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4481.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4481.md index 3320ac5730d..adcda6aff5f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4481.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4481.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4481" title: "Compiler Warning (level 4) C4481" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4481" +ms.date: 11/04/2016 f1_keywords: ["C4481"] helpviewer_keywords: ["C4481"] -ms.assetid: 7bfd4e0c-b452-4e6c-b7c4-ac5cc93fe4ea --- # Compiler Warning (level 4) C4481 -nonstandard extension used: override specifier 'keyword' +> nonstandard extension used: override specifier 'keyword' + +## Remarks A keyword was used that is not in the C++ standard, for example, one of the override specifiers that also works under /clr. For more information, see, @@ -18,7 +19,7 @@ A keyword was used that is not in the C++ standard, for example, one of the over ## Example -The following sample generates C4481. +The following example generates C4481. ```cpp // C4481.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4487.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4487.md index 376ae3a09e2..d51cec97ca6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4487.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4487.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4487" title: "Compiler Warning (level 4) C4487" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4487" +ms.date: 11/04/2016 f1_keywords: ["C4487"] helpviewer_keywords: ["C4487"] -ms.assetid: 796144cf-cd3c-4edc-b6a4-96192b7eb4f0 --- # Compiler Warning (level 4) C4487 -'derived_class_function' : matches inherited non-virtual method 'base_class_function' but is not explicitly marked 'new' +> 'derived_class_function' : matches inherited non-virtual method 'base_class_function' but is not explicitly marked 'new' + +## Remarks A function in a derived class has the same signature as a non-virtual base class function. C4487 reminds you that the derived class function does not override the base class function. Explicitly mark the derived class function as **`new`** to resolve this warning. @@ -16,7 +17,7 @@ For more information, see [new (new slot in vtable)](../../extensions/new-new-sl ## Example -The following sample generates C4487. +The following example generates C4487. ```cpp // C4487.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4505.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4505.md index 018e89e157d..9c7d9989148 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4505.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4505.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4505" title: "Compiler Warning (level 4) C4505" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4505" +ms.date: 11/04/2016 f1_keywords: ["C4505"] helpviewer_keywords: ["C4505"] -ms.assetid: 068716a0-7dd2-40af-abf4-478f893b48c5 --- # Compiler Warning (level 4) C4505 -'function' : unreferenced local function has been removed +> 'function' : unreferenced local function has been removed + +## Remarks The given function is local and not referenced in the body of the module; therefore, the function is dead code. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4510.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4510.md index 7026350d29e..3ed173e3f0a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4510.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4510.md @@ -1,15 +1,16 @@ --- title: "Compiler Warning (level 4) C4510" -description: Compiler warning C4510 description and solution. -ms.date: "09/22/2019" +description: "Compiler warning C4510 description and solution." +ms.date: 09/22/2019 f1_keywords: ["C4510"] helpviewer_keywords: ["C4510"] -ms.assetid: fd28d1d4-ad27-4dad-94c0-9dba46c93180 --- # Compiler Warning (level 4) C4510 > '*class*' : default constructor could not be generated +## Remarks + The compiler can't generate a default constructor for the specified class, which has no user-defined constructors. Objects of this type can't be created. There are several situations that prevent the compiler from generating a default constructor, including: diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4512.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4512.md index 2a43b103223..ab781a65058 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4512.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4512.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4512" title: "Compiler Warning (level 4) C4512" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4512" +ms.date: 11/04/2016 f1_keywords: ["C4512"] helpviewer_keywords: ["C4512"] -ms.assetid: afb68995-684a-4be5-a73a-38d7a16dc030 --- # Compiler Warning (level 4) C4512 -'class' : assignment operator could not be generated +> 'class' : assignment operator could not be generated + +## Remarks The compiler cannot generate an assignment operator for the given class. No assignment operator was created. @@ -28,7 +29,7 @@ You can resolve the C4512 warning for your code in one of three ways: ## Example -The following sample generates C4512. +The following example generates C4512. ```cpp // C4512.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4513.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4513.md index ebc5ecc71f9..9261d6c13dd 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4513.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4513.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4513" title: "Compiler Warning (level 4) C4513" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4513" +ms.date: 11/04/2016 f1_keywords: ["C4513"] helpviewer_keywords: ["C4513"] -ms.assetid: 6877334a-f30a-4184-9483-dac3348737a4 --- # Compiler Warning (level 4) C4513 -'class' : destructor could not be generated +> 'class' : destructor could not be generated + +## Remarks The compiler cannot generate a default destructor for the given class; no destructor was created. The destructor is in a base class that is not accessible to the derived class. If the base class has a private destructor, make it public or protected. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4514.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4514.md index ea7cba7688b..f0098802be9 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4514.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4514.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4514" title: "Compiler Warning (level 4) C4514" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4514" +ms.date: 11/04/2016 f1_keywords: ["C4514"] helpviewer_keywords: ["C4514"] -ms.assetid: cdae966a-9cd4-4e31-af30-2a014e68f614 --- # Compiler Warning (level 4) C4514 -'function' : unreferenced inline function has been removed +> 'function' : unreferenced inline function has been removed + +## Remarks The optimizer removed an inline function that is not called. 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. -The following sample generates C4514: +## Example + +The following example generates C4514: ```cpp // C4514.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4515.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4515.md index 525da292979..b6633afa237 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4515.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4515.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4515" title: "Compiler Warning (level 4) C4515" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4515" +ms.date: 11/04/2016 f1_keywords: ["C4515"] helpviewer_keywords: ["C4515"] -ms.assetid: 167b5177-3f89-418b-b6c8-7de634f6b28f --- # Compiler Warning (level 4) C4515 -'namespace' : namespace uses itself +> 'namespace' : namespace uses itself + +## Remarks A namespace is used recursively. -The following sample generates C4515: +## Example + +The following example generates C4515: ```cpp // C4515.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4516.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4516.md index 95e905c9ac8..0ac56deda3b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4516.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4516.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4516" title: "Compiler Warning (level 4) C4516" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4516" +ms.date: 11/04/2016 f1_keywords: ["C4516"] helpviewer_keywords: ["C4516"] -ms.assetid: 6677bb1f-d26e-4ab9-8644-6b5a2a8f4ff8 --- # Compiler Warning (level 4) C4516 -'class::symbol' : access-declarations are deprecated; member using-declarations provide a better alternative +> 'class::symbol' : access-declarations are deprecated; member using-declarations provide a better alternative + +## Remarks The ANSI C++ committee has declared access declarations (changing the access of a member in a derived class without the [using](../../cpp/using-declaration.md) keyword) to be outdated. Access declarations may not be supported by future versions of C++. -The following sample generates C4516: +## Example + +The following example generates C4516: ```cpp // C4516.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4517.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4517.md index bcc52f94383..b64a35c0020 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4517.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4517.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4517" title: "Compiler Warning (level 4) C4517" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4517" +ms.date: 11/04/2016 f1_keywords: ["C4517"] helpviewer_keywords: ["C4517"] -ms.assetid: 87cc12b8-7331-4f3a-a863-d6a75d9599c3 --- # Compiler Warning (level 4) C4517 -access-declarations are deprecated; member using-declarations provide a better alternative +> access-declarations are deprecated; member using-declarations provide a better alternative + +## Remarks The ANSI C++ committee has declared access declarations (changing the access of a member in a derived class without the [using](../../cpp/using-declaration.md) keyword) to be outdated. Access declarations may not be supported by future versions of C++. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4536.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4536.md index 68bd5482f94..666741bf888 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4536.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4536.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4536" title: "Compiler Warning (level 4) C4536" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4536" +ms.date: 11/04/2016 f1_keywords: ["C4536"] helpviewer_keywords: ["C4536"] -ms.assetid: ab4d0686-f813-4e88-a264-b40d3630ed6c --- # Compiler Warning (level 4) C4536 -'type name' : type-name exceeds meta-data limit of 'limit' characters +> 'type name' : type-name exceeds meta-data limit of 'limit' characters + +## Remarks A type name would be truncated in metadata if it was a managed type. See [C3180](../../error-messages/compiler-errors-2/compiler-error-c3180.md) for more information. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4559.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4559.md index 0a41fa8b052..342ceb0c727 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4559.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4559.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4559" title: "Compiler Warning (level 4) C4559" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 4) C4559" +ms.date: 08/27/2018 f1_keywords: ["C4559"] helpviewer_keywords: ["C4559"] -ms.assetid: ed542f60-454d-45cb-85da-987ede61b1ab --- # Compiler Warning (level 4) C4559 @@ -16,7 +15,7 @@ A function was redefined or redeclared and the second definition or declaration ## Example -The following sample generates C4559: +The following example generates C4559: ```cpp // C4559.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4564.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4564.md index 629202c137e..92a33b38705 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4564.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4564.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4564" title: "Compiler Warning (level 4) C4564" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4564" +ms.date: 11/04/2016 f1_keywords: ["C4564"] helpviewer_keywords: ["C4564"] -ms.assetid: 555b301b-313e-4262-9f81-eb878674be60 --- # Compiler Warning (level 4) C4564 -method 'method' of class 'class' defines unsupported default parameter 'parameter' +> method 'method' of class 'class' defines unsupported default parameter 'parameter' + +## Remarks The compiler detected a method with one or more parameters with default values. The default value(s) for the parameters will be ignored when the method is invoked; explicitly specify values for those parameters. If you do not explicitly specify values for those parameters, the C++ compiler will generate an error. +## Example + Given the following .dll created with Visual Basic, which allows default parameters on method arguments: ```vb @@ -24,7 +27,7 @@ Public class TestClass End class ``` -And the following C++ sample that uses the .dll created with Visual Basic, +And the following C++ example that uses the .dll created with Visual Basic, ```cpp // C4564.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4565.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4565.md index 293f34c42c8..c1f9e7d3e2b 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4565.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4565.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4565" title: "Compiler Warning (level 4) C4565" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 4) C4565" +ms.date: 08/27/2018 f1_keywords: ["C4565"] helpviewer_keywords: ["C4565"] -ms.assetid: a71f1341-a4a1-4060-ad1e-9322531883ed --- # Compiler Warning (level 4) C4565 @@ -16,7 +15,7 @@ A symbol was redefined or redeclared and the second definition or declaration, u ## Example -The following sample generates C4565: +The following example generates C4565: ```cpp // C4565.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4571.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4571.md index 54845383a3c..a45338491c2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4571.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4571.md @@ -4,16 +4,15 @@ description: "Documents the Microsoft C++ compiler warning C4571." ms.date: 08/24/2020 f1_keywords: ["C4571"] helpviewer_keywords: ["C4571"] -ms.assetid: 07aa17bd-b15c-4266-824c-57cc445e8edd --- # Compiler Warning (level 4) C4571 > Informational: `catch(...)` semantics changed since Visual C++ 7.1; structured exceptions (SEH) are no longer caught -C4571 is generated for every `catch(...)` block when you specify the **`/EHs`** compiler option. - ## Remarks +C4571 is generated for every `catch(...)` block when you specify the **`/EHs`** compiler option. + When you specify the **`/EHs`** compiler option, `catch(...)` blocks don't catch structured exceptions. (Divide by zero, or null pointer exceptions, for example.) A `catch(...)` block only catches explicitly thrown C++ exceptions. For more information, see [Exception Handling](../../cpp/exception-handling-in-visual-cpp.md). This warning is off by default. Turn this warning on to ensure that when you compile with **`/EHs`** your `catch (...)` blocks don't catch structured exceptions. For more information, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). @@ -28,7 +27,7 @@ You can resolve C4571 in one of the following ways: ## Example -The following sample generates C4571. +The following example generates C4571. ```cpp // C4571.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4610.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4610.md index 4786d9b171f..7f3a940728a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4610.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4610.md @@ -1,16 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4610" title: "Compiler Warning (level 4) C4610" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4610" +ms.date: 11/04/2016 f1_keywords: ["C4610"] helpviewer_keywords: ["C4610"] -ms.assetid: 23c1a16c-9ca9-4bf6-9911-a72b785560c2 --- # Compiler Warning (level 4) C4610 -object 'class' can never be instantiated - user-defined constructor required +> object 'class' can never be instantiated - user-defined constructor required + +## Remarks + +The class has no user-defined or default constructors. No instantiation is performed. + +## Example -The class has no user-defined or default constructors. No instantiation is performed. The following sample generates C4610: +The following example generates C4610: ```cpp // C4610.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4611.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4611.md index f584d23463c..0a08bc7d430 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4611.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4611.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4611" title: "Compiler Warning (level 4) C4611" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4611" +ms.date: 11/04/2016 f1_keywords: ["C4611"] helpviewer_keywords: ["C4611"] -ms.assetid: bd90d0a6-75f9-4e97-968d-dda6773e9fd8 --- # Compiler Warning (level 4) C4611 -interaction between 'function' and C++ object destruction is non-portable +> interaction between 'function' and C++ object destruction is non-portable + +## Remarks On some platforms, functions that include **`catch`** may not support C++ object semantics of destruction when out of scope. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md index d5831092ade..6cc61710058 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4623.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4623" title: "Compiler Warning (level 4) C4623" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4623" +ms.date: 10/27/2022 f1_keywords: ["C4623"] helpviewer_keywords: ["C4623"] -ms.assetid: e630d8d0-f6ea-469c-a74f-07b027587225 --- # Compiler Warning (level 4) C4623 -'`derived class`' : default constructor was implicitly defined as deleted because a base class default constructor is inaccessible or deleted +> '`derived class`' : default constructor was implicitly defined as deleted + +## Remarks -A constructor was not accessible in a base class and was not generated for the derived class. Any attempt to create an object of this type on the stack will cause a compiler error. +Because the default constructor is deleted or inaccessible in a base class, the compiler can't generate a default constructor for the derived class. Attempts to create an object of this type by using the default constructor (for example, in an array) cause a compiler error. -This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. +This warning is off by default. For more information, see [Compiler warnings that are off by default](../../preprocessor/compiler-warnings-that-are-off-by-default.md). ## Example -The following sample generates C4623. +The following example generates C4623. ```cpp // C4623.cpp @@ -35,6 +36,6 @@ class D : public B {}; // C4623 - to fix, make B's constructor public class E : public C {}; // OK - class C constructor is public int main() { - // D d; will cause an error + // D d; // Error C2280 } ``` diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4625.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4625.md index 769736cbd7b..c066dbcd982 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4625.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4625.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4625" title: "Compiler Warning (level 4) C4625" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4625" +ms.date: 11/04/2016 f1_keywords: ["C4625"] helpviewer_keywords: ["C4625"] -ms.assetid: 4cc99e50-846c-4784-97da-48b977067851 --- # Compiler Warning (level 4) C4625 -'derived class' : copy constructor was implicitly defined as deleted because a base class copy constructor is inaccessible or deleted +> 'derived class' : copy constructor was implicitly defined as deleted because a base class copy constructor is inaccessible or deleted + +## Remarks A copy constructor was deleted or not accessible in a base class and was therefore not generated for a derived class. Any attempt to copy an object of this type will cause a compiler error. @@ -16,7 +17,7 @@ This warning is off by default. See [Compiler Warnings That Are Off by Default]( ## Example -The following sample generates C4625 and shows how to fix it. +The following example generates C4625 and shows how to fix it. ```cpp // C4625.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4626.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4626.md index 289950c660d..7115d1f328a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4626.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4626.md @@ -1,22 +1,25 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4626" title: "Compiler Warning (level 4) C4626" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4626" +ms.date: 11/04/2016 f1_keywords: ["C4626"] helpviewer_keywords: ["C4626"] -ms.assetid: 7f822ff4-a4a3-4f17-b45b-e8b7b4659a14 --- # Compiler Warning (level 4) C4626 -'derived class' : assignment operator was implicitly defined as deleted because a base class assignment operator is inaccessible or deleted +> 'derived class' : assignment operator was implicitly defined as deleted because a base class assignment operator is inaccessible or deleted + +## Remarks An assignment operator was deleted or not accessible in a base class and was therefore not generated for a derived class. Any attempt to assign objects of this type will cause a compiler error. This warning is off by default. See [Compiler Warnings That Are Off by Default](../../preprocessor/compiler-warnings-that-are-off-by-default.md) for more information. -The following sample generates C4626 and shows how to fix it: +## Example -``` +The following example generates C4626 and shows how to fix it: + +```cpp // C4626 // compile with: /W4 #pragma warning(default : 4626) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4629.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4629.md index 31618dd3700..39e76d38d59 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4629.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4629.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4629" title: "Compiler Warning (level 4) C4629" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4629" +ms.date: 11/04/2016 f1_keywords: ["C4629"] helpviewer_keywords: ["C4629"] -ms.assetid: 158cde12-bae5-4d43-b575-b52b35aaa0b9 --- # Compiler Warning (level 4) C4629 -digraph used, character sequence 'digraph' interpreted as token 'char' (insert a space between the two characters if this is not what you intended) +> digraph used, character sequence 'digraph' interpreted as token 'char' (insert a space between the two characters if this is not what you intended) + +## Remarks Under [/Za](../../build/reference/za-ze-disable-language-extensions.md), the compiler warns when it detects a digraph. -The following sample generates C4629: +## Example + +The following example generates C4629: ```cpp // C4629.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4634.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4634.md index 9b1ac75158a..b0eb31c8844 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4634.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4634.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4634" title: "Compiler Warning (level 4) C4634" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4634" +ms.date: 11/04/2016 f1_keywords: ["C4634"] helpviewer_keywords: ["C4634"] -ms.assetid: 3e3496ce-2ac7-43d0-a48a-f514c950e81d --- # Compiler Warning (level 4) C4634 -XML document comment: cannot be applied: reason +> XML document comment: cannot be applied: reason + +## Remarks XML documentation tags can not be applied to all C++ constructs. For example, you cannot add a documentation comment to a namespace or template. @@ -16,7 +17,7 @@ For more information, see [XML Documentation](../../build/reference/xml-document ## Examples -The following sample generates C4634. +The following example generates C4634. ```cpp // C4634.cpp @@ -27,7 +28,7 @@ namespace hello { }; ``` -The following sample generates C4634. +The following example generates C4634. ```cpp // C4634_b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4639.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4639.md index 8d5ddea0f74..0f952a6f795 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4639.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4639.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4639" title: "Compiler Warning (level 4) C4639" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4639" +ms.date: 11/04/2016 f1_keywords: ["C4639"] helpviewer_keywords: ["C4639"] -ms.assetid: f94f7392-cdbb-4bf4-8a00-20dc90d3efe9 --- # Compiler Warning (level 4) C4639 -MSXML error, XML document comments will not be processed. reason +> MSXML error, XML document comments will not be processed. reason + +## Remarks This warning can occur for any number of reasons. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4668.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4668.md index 691fe7a8f4b..ac3527c10fa 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4668.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4668.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4668" title: "Compiler Warning (level 4) C4668" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4668" +ms.date: 11/04/2016 f1_keywords: ["C4668"] helpviewer_keywords: ["C4668"] -ms.assetid: c6585460-bc4a-4a15-9242-4cbfce53c961 --- # Compiler Warning (level 4) C4668 -'symbol' is not defined as a preprocessor macro, replacing with '0' for 'directives' +> 'symbol' is not defined as a preprocessor macro, replacing with '0' for 'directives' + +## Remarks A symbol that was not defined was used with a preprocessor directive. The symbol will evaluate to false. To define a symbol, you can use either the [#define directive](../../preprocessor/hash-define-directive-c-cpp.md) or [/D](../../build/reference/d-preprocessor-definitions.md) compiler option. @@ -16,7 +17,7 @@ This warning is off by default. See [Compiler Warnings That Are Off by Default]( ## Example -The following sample generates C4668: +The following example generates C4668: ```cpp // C4668.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4670.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4670.md index 16a09cd423c..0fe80da2049 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4670.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4670.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4670" title: "Compiler Warning (level 4) C4670" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4670" +ms.date: 11/04/2016 f1_keywords: ["C4670"] helpviewer_keywords: ["C4670"] -ms.assetid: e172b134-b1fb-4dfe-8e9d-209ea08b73c7 --- # Compiler Warning (level 4) C4670 -'identifier' : this base class is inaccessible +> 'identifier' : this base class is inaccessible + +## Remarks The specified base class of an object to be thrown in a **`try`** block is not accessible. The object cannot be instantiated if it is thrown. Check that the base class is inherited with the correct access specifier. -The following sample generates C4670: +## Example + +The following example generates C4670: ```cpp // C4670.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4672.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4672.md index 71c8c6eabdb..79592299553 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4672.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4672.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4672" title: "Compiler Warning (level 4) C4672" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4672" +ms.date: 11/04/2016 f1_keywords: ["C4672"] helpviewer_keywords: ["C4672"] -ms.assetid: 3ae1b9cd-e53e-41e7-a330-7238b7aa0679 --- # Compiler Warning (level 4) C4672 -'identifier1' : ambiguous. First seen as 'identifier2' +> 'identifier1' : ambiguous. First seen as 'identifier2' + +## Remarks The specified object to be thrown in a **`try`** block is ambiguous. The object cannot be disambiguated if it is thrown. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4673.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4673.md index 72d0d3c2645..e78645787d5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4673.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4673.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4673" title: "Compiler Warning (level 4) C4673" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4673" +ms.date: 11/04/2016 f1_keywords: ["C4673"] helpviewer_keywords: ["C4673"] -ms.assetid: 95626ec6-f05b-43c7-8b9a-a60a6f98dd30 --- # Compiler Warning (level 4) C4673 -throwing 'identifier' the following types will not be considered at the catch site +> throwing 'identifier' the following types will not be considered at the catch site + +## Remarks A throw object cannot be handled in the **`catch`** block. Each type that cannot be handled is listed in the error output immediately following the line containing this warning. Each unhandled type has its own warning. Read the warning for each specific type for more information. -The following sample generates C4673: +## Example + +The following example generates C4673: ```cpp // C4673.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4680.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4680.md index 84991356ab2..b1c2f47d90a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4680.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4680.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4680" title: "Compiler Warning (level 4) C4680" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4680" +ms.date: 11/04/2016 f1_keywords: ["C4680"] helpviewer_keywords: ["C4680"] -ms.assetid: 6e043f4c-c601-4b77-8130-920cff1d912e --- # Compiler Warning (level 4) C4680 -'class' : coclass does not specify a default interface +> 'class' : coclass does not specify a default interface + +## Remarks A [default](../../windows/attributes/default-cpp.md) interface was not specified for a class that was marked with the [coclass](../../windows/attributes/coclass.md) attribute. In order for an object to be useful, it must implement an interface. -The following sample generates C4680: +## Example + +The following example generates C4680: ```cpp // C4680.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4681.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4681.md index 111c36c8bba..361aa89790a 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4681.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4681.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4681" title: "Compiler Warning (level 4) C4681" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4681" +ms.date: 11/04/2016 f1_keywords: ["C4681"] helpviewer_keywords: ["C4681"] -ms.assetid: a4e6d85f-3e21-4b45-a551-c23d3c554d3f --- # Compiler Warning (level 4) C4681 -'class' : coclass does not specify a default interface that is an event source +> 'class' : coclass does not specify a default interface that is an event source + +## Remarks A [source](../../windows/attributes/source-cpp.md) interface was not specified for a class. -The following sample generates C4681: +## Example + +The following example generates C4681: ```cpp // C4681.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4682.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4682.md index b0ca72b2f48..24a2e74a7f7 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4682.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4682.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4682" title: "Compiler Warning (level 4) C4682" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4682" +ms.date: 11/04/2016 f1_keywords: ["C4682"] helpviewer_keywords: ["C4682"] -ms.assetid: 858ea157-1244-4a61-85df-97b3de43d418 --- # Compiler Warning (level 4) C4682 -'parameter' : no directional parameter attribute specified, defaulting to [in] +> 'parameter' : no directional parameter attribute specified, defaulting to [in] + +## Remarks A method on a parameter in an attributed interface does not have one of the directional attributes: [in](../../windows/attributes/in-cpp.md) or [out](../../windows/attributes/out-cpp.md). The parameter defaults to in. 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. -The following sample generates C4682: +## Example + +The following example generates C4682: ```cpp // C4682.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4690.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4690.md index 13c663986aa..2b60bad381f 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4690.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4690.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4690" title: "Compiler Warning (level 4) C4690" -ms.date: "07/03/2018" +description: "Learn more about: Compiler Warning (level 4) C4690" +ms.date: 07/03/2018 f1_keywords: ["C4690"] helpviewer_keywords: ["C4690"] -ms.assetid: 080a0ea1-458b-477b-a37a-4a34c94709ff --- # Compiler Warning (level 4) C4690 @@ -16,7 +15,7 @@ The [emitidl](../../windows/attributes/emitidl.md) attribute was popped one more ## Example -The following sample generates C4690. To fix this issue, make sure the attribute is popped exactly as many times as it is pushed. +The following example generates C4690. To fix this issue, make sure the attribute is popped exactly as many times as it is pushed. ```cpp // C4690.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4701.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4701.md index 9ebcdda802f..9200e630f18 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4701.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4701.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4701" title: "Compiler Warning (level 4) C4701" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4701" +ms.date: 11/04/2016 f1_keywords: ["C4701"] helpviewer_keywords: ["C4701"] -ms.assetid: d7c76c66-1f3f-4d3c-abe4-5d94c84a5a1f --- # Compiler Warning (level 4) C4701 -Potentially uninitialized local variable 'name' used +> Potentially uninitialized local variable 'name' used + +## Remarks The local variable *name* might have been used without being assigned a value. This could lead to unpredictable results. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4702.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4702.md index c87a88e66cb..04cc02f7efe 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4702.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4702.md @@ -1,22 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4702" title: "Compiler Warning (level 4) C4702" +description: "Learn more about: Compiler Warning (level 4) C4702" ms.date: 09/20/2021 f1_keywords: ["C4702"] helpviewer_keywords: ["C4702"] -ms.assetid: d8198c1e-8762-42a6-9e6b-cb568b7a1686 --- # Compiler Warning (level 4) C4702 > unreachable code +## Remarks + When the compiler back end detects unreachable code, it generates C4702 as a level 4 warning. To address this warning, remove the unreachable code or assure that all source code is reachable by some flow of execution. ## Examples -The following sample generates C4702. To fix it, remove the unreachable code. +The following example generates C4702. To fix it, remove the unreachable code. ```cpp // C4702.cpp @@ -33,7 +34,7 @@ Error C4702 can occur in some versions of the compiler when you compile using th For more information, see [`/EH` (Exception Handling Model)](../../build/reference/eh-exception-handling-model.md). -The following sample generates C4702: +The following example generates C4702: ```cpp // C4702b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md index edc45556355..b15a4cd6a68 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4703.md @@ -1,16 +1,19 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4703" title: "Compiler Warning (level 4) C4703" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4703" +ms.date: 08/30/2022 f1_keywords: ["C4703"] helpviewer_keywords: ["C4703"] -ms.assetid: 5dad454e-69e3-4931-9168-050a861c05f8 --- # Compiler Warning (level 4) C4703 -Potentially uninitialized local pointer variable 'name' used +> Potentially uninitialized local pointer variable 'name' used + +## Remarks + +The local pointer variable *name* might have been used without being assigned a value. This access could lead to unpredictable results. -The local pointer variable *name* might have been used without being assigned a value. This could lead to unpredictable results. +The [`/sdl` (Enable Additional Security Checks)](../../build/reference/sdl-enable-additional-security-checks.md) compiler option elevates this warning to an error. ## Example @@ -65,5 +68,5 @@ int main() ## See also -[Compiler Warning (level 4) C4701](../../error-messages/compiler-warnings/compiler-warning-level-4-c4701.md)
-[Warnings, /sdl, and improving uninitialized variable detection](https://www.microsoft.com/security/blog/2012/06/06/warnings-sdl-and-improving-uninitialized-variable-detection/) +[Compiler Warning (level 4) C4701](../../error-messages/compiler-warnings/compiler-warning-level-4-c4701.md)\ +[Warnings, `/sdl`, and improving uninitialized variable detection](https://www.microsoft.com/security/blog/2012/06/06/warnings-sdl-and-improving-uninitialized-variable-detection/) diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4706.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4706.md index 6fa2feebb00..314f98a8a40 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,69 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4706" title: "Compiler Warning (level 4) C4706" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4706" +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. +## Remarks + +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: +## Example + +The following example 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-c4709.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4709.md index ce1711cf545..4061b8eaabb 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4709.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4709.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4709" title: "Compiler Warning (level 4) C4709" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4709" +ms.date: 11/04/2016 f1_keywords: ["C4709"] helpviewer_keywords: ["C4709"] -ms.assetid: 8abfdd45-8c70-4c27-b0fb-ca0c3f0fccf9 --- # Compiler Warning (level 4) C4709 -comma operator within array index expression +> comma operator within array index expression + +## Remarks When a comma occurs in an array index expression, the compiler uses the value after the last comma. ## Example -The following sample generates C4709: +The following example generates C4709: ```cpp // C4709.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4710.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4710.md index d2cc5e90759..7e6ab51b762 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4710.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4710.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4710" title: "Compiler Warning (level 4) C4710" +description: "Learn more about: Compiler Warning (level 4) C4710" ms.date: 10/19/2021 f1_keywords: ["C4710"] helpviewer_keywords: ["C4710"] -ms.assetid: 76381ec7-3fc1-4bee-9a0a-c2c8307b92e2 --- # Compiler Warning (level 4) C4710 > '*function*' : function not inlined +## Remarks + The specified function was marked for inline expansion, but the compiler didn't inline the function. Inlining is done at the compiler's discretion. The **`inline`** keyword, like the deprecated (and, in C++17 and later standards, removed) **`register`** keyword, is used as a hint for the compiler. The compiler uses heuristics to determine if it should inline a particular function to speed up the code when it optimizes for speed, or if it should inline a particular function to make the code smaller when it optimizes for space. The compiler inlines only the smallest functions when compiling for space. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4714.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4714.md index 4742aa9d22e..1e8cb117833 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4714.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4714.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4714" title: "Compiler Warning (level 4) C4714" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4714" +ms.date: 11/04/2016 f1_keywords: ["C4714"] helpviewer_keywords: ["C4714"] -ms.assetid: 22c7fd0c-899d-4e9b-95f3-725b2c49fb46 --- # Compiler Warning (level 4) C4714 > function 'function' marked as __forceinline not inlined +## Remarks + The given function was selected for inline expansion, but the compiler did not perform the inlining. Although **`__forceinline`** is a stronger indication to the compiler than **`__inline`**, inlining is still performed at the compiler's discretion, but no heuristics are used to determine the benefits from inlining this function. @@ -28,7 +29,9 @@ In some cases, the compiler will not inline a particular function for mechanical - A function with a **`try`** (C++ exception handling) statement. -The following sample generates C4714: +## Example + +The following example generates C4714: ```cpp // C4714.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4718.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4718.md index f5f3e29ecc3..0d1e87cd79d 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4718.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4718.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4718" title: "Compiler Warning (level 4) C4718" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4718" +ms.date: 11/04/2016 f1_keywords: ["C4718"] helpviewer_keywords: ["C4718"] -ms.assetid: 29507f8a-b024-42c1-a3b8-f35d1f2641f3 --- # Compiler Warning (level 4) C4718 -'function call' : recursive call has no side effects, deleting +> 'function call' : recursive call has no side effects, deleting + +## Remarks A function contains a recursive call, but otherwise has no side effects. A call to this function is being deleted. The correctness of the program is not affected, but the behavior is. Whereas leaving the call in could result in a runtime stack overflow exception, deleting the call removes that possibility. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4725.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4725.md index 33d4ee8068d..e758e619545 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4725.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4725.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4725" title: "Compiler Warning (level 4) C4725" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4725" +ms.date: 11/04/2016 f1_keywords: ["C4725"] helpviewer_keywords: ["C4725"] -ms.assetid: effa0335-71c3-4b3b-8618-da4b9b46a95d --- # Compiler Warning (level 4) C4725 -instruction may be inaccurate on some Pentiums +> instruction may be inaccurate on some Pentiums + +## Remarks Your code contains an inline assembly instruction that may not produce accurate results on some Pentium microprocessors. -The following sample generates C4725: +## Example + +The following example generates C4725: ```cpp // C4725.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4740.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4740.md index dbd34c62da4..9caf86e10b1 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4740.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4740.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (Level 4) C4740" title: "Compiler Warning (Level 4) C4740" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (Level 4) C4740" +ms.date: 11/04/2016 f1_keywords: ["C4740"] helpviewer_keywords: ["C4740"] -ms.assetid: 85528969-966a-44b4-8a2f-971704c64477 --- # Compiler Warning (Level 4) C4740 -flow in or out of inline asm code suppresses global optimization +> flow in or out of inline asm code suppresses global optimization + +## Remarks When there is a jump in to or out of an **`asm`** block, global optimizations are disabled for that function. -The following sample generates C4740: +## Example + +The following example generates C4740: ```cpp // C4740.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4754.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4754.md index b5fcf28fe24..25e27f20145 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4754.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4754.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4754" title: "Compiler Warning (level 4) C4754" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4754" +ms.date: 11/04/2016 f1_keywords: ["C4754"] helpviewer_keywords: ["C4754"] -ms.assetid: e0e4606a-754a-4f42-a274-21a34978d21d --- # Compiler Warning (level 4) C4754 -Conversion rules for arithmetic operations in a comparison mean that one branch cannot be executed. +> Conversion rules for arithmetic operations in a comparison mean that one branch cannot be executed. + +## Remarks The C4754 warning is issued because the result of the comparison is always the same. This indicates that one of the branches of the condition is never executed, most likely because the associated integer expression is incorrect. This code defect often occurs in incorrect integer overflow checks on 64-bit architectures. @@ -16,7 +17,7 @@ Integer conversion rules are complex and there are many subtle pitfalls. As an a ## Examples -This sample generates C4754: +This example generates C4754: ```cpp // C4754a.cpp @@ -52,7 +53,7 @@ unsigned long long x = (unsigned long long)a + (unsigned long long)b; ``` -The next sample also generates C4754. +The next example also generates C4754. ```cpp // C4754b.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md index c6b5ccc34d8..7886044e2ab 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4764.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4764" title: "Compiler Warning (level 4) C4764" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4764" +ms.date: 11/04/2016 f1_keywords: ["C4764"] helpviewer_keywords: ["C4764"] -ms.assetid: 7bd4296f-966b-484c-bf73-8dbc8e85b4a9 --- # Compiler Warning (level 4) C4764 -Cannot align catch objects to greater than 16 bytes +> Cannot align catch objects to greater than 16 bytes + +## Remarks An alignment greater than 16 was specified, but on some platforms, if the function throws an exception, the stack will force an alignment of not greater than 16. ## Example -The following sample generates C4764: +The following example generates C4764: ```cpp // C4764.cpp @@ -38,7 +39,7 @@ int main() a.x = 15; throw a; } - catch (ALIGNEDA b) // can’t align b to > 16 bytes + catch (ALIGNEDA b) // can't align b to > 16 bytes { printf_s("%d\n", b.x); } diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4816.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4816.md index 2adb8e107e5..f7046a8be89 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4816.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4816.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4816" title: "Compiler Warning (level 4) C4816" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4816" +ms.date: 11/04/2016 f1_keywords: ["C4816"] helpviewer_keywords: ["C4816"] -ms.assetid: 60f730ae-d942-4db9-ab97-41d4a874d8da --- # Compiler Warning (level 4) C4816 -'param' : parameter has a zero-sized array which will be truncated (unless the object is passed by reference) +> 'param' : parameter has a zero-sized array which will be truncated (unless the object is passed by reference) + +## Remarks A parameter to an object with a zero-size array was not passed by reference. The array will not get copied when the object is passed. ## Example -The following sample generates C4816: +The following example generates C4816: ```cpp // C4816.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4820.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4820.md index 4a2288a609d..18f9f82fb36 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4820.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4820.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4820" title: "Compiler Warning (level 4) C4820" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4820" +ms.date: 11/04/2016 f1_keywords: ["C4820"] helpviewer_keywords: ["C4820"] -ms.assetid: 17aa29f4-c287-49b8-bc43-8ed82ffed5ea --- # Compiler Warning (level 4) C4820 -'bytes' bytes padding added after construct 'member_name' +> 'bytes' bytes padding added after construct 'member_name' + +## Remarks The type and order of elements caused the compiler to add padding to the end of a struct. See [align](../../cpp/align-cpp.md) for more information on padding in a struct. 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. -The following sample generates C4820: +## Example + +The following example generates C4820: ```cpp // C4820.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4840.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4840.md index 417cd684ad3..0c10fc635b5 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4840.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4840.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4840" title: "Compiler Warning (level 4) C4840" -ms.date: "09/13/2018" +description: "Learn more about: Compiler Warning (level 4) C4840" +ms.date: 09/13/2018 f1_keywords: ["C4840"] helpviewer_keywords: ["C4840"] --- @@ -17,7 +17,7 @@ This warning is available beginning in Visual Studio 2017. ## Example -The following sample generates C4840 and shows how to fix it: +The following example generates C4840 and shows how to fix it: ```cpp // C4840.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4913.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4913.md index 4c7e6651a22..15d4c3e2211 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4913.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4913.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4913" title: "Compiler Warning (level 4) C4913" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4913" +ms.date: 11/04/2016 f1_keywords: ["C4913"] helpviewer_keywords: ["C4913"] -ms.assetid: b94aa52e-6029-4170-9134-017714931546 --- # Compiler Warning (level 4) C4913 -**user defined binary operator ',' exists but no overload could convert all operands, default built-in binary operator ',' used** +> user defined binary operator ',' exists but no overload could convert all operands, default built-in binary operator ',' used + +## Remarks A call to the built-in comma operator occurred in a program that also had an overloaded comma operator; a conversion that you thought may have occurred did not. -The following code sample generates C4913: +## Example + +The following code example generates C4913: ```cpp // C4913.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4918.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4918.md index 1954636c04d..2b0b70e3636 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4918.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4918.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4918" title: "Compiler Warning (level 4) C4918" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4918" +ms.date: 11/04/2016 f1_keywords: ["C4918"] helpviewer_keywords: ["C4918"] -ms.assetid: 1bcf6d35-3467-4aa8-b2ef-cb33f4e70238 --- # Compiler Warning (level 4) C4918 -'character' : invalid character in pragma optimization list +> 'character' : invalid character in pragma optimization list + +## Remarks An unknown character was found in the optimization list of an [optimize](../../preprocessor/optimize.md) pragma statement. +## Example + For example, the following statement generates C4918: ```cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4931.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4931.md index a6312926814..26f191977ec 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4931.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4931.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4931" title: "Compiler Warning (level 4) C4931" -ms.date: "08/27/2018" +description: "Learn more about: Compiler Warning (level 4) C4931" +ms.date: 08/27/2018 f1_keywords: ["C4931"] helpviewer_keywords: ["C4931"] -ms.assetid: cfbf08c7-94e4-4a91-a691-479d1dbe527a --- # Compiler Warning (level 4) C4931 > we are assuming the type library was built for *number*-bit pointers +## Remarks + Explicit information was not supplied with the **ptrsize** attribute of the [#import](../../preprocessor/hash-import-directive-cpp.md) directive; the compiler concluded that pointer size of the type library is *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. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4932.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4932.md index 873855d305f..db065cb5d56 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4932.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4932.md @@ -4,15 +4,18 @@ description: "Describes Microsoft C/C++ compiler warning C4932." ms.date: 08/25/2020 f1_keywords: ["C4932"] helpviewer_keywords: ["C4932"] -ms.assetid: 0b8d88cc-21f6-45cb-a9f5-1795b7db0dfa --- # Compiler Warning (level 4) C4932 > `__identifier(identifier_1)` and `__identifier(identifier_2)` are indistinguishable +## Remarks + The compiler is unable to distinguish between **`_finally`** and **`__finally`** or **`__try`** and **`_try`** as a parameter passed to [`__identifier`](../../extensions/identifier-cpp-cli.md). You should not attempt to use them both as identifiers in the same program, as it will result in a [C2374](../../error-messages/compiler-errors-1/compiler-error-c2374.md) error. -The following sample generates C4932: +## Example + +The following example generates C4932: ```cpp // C4932.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4937.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4937.md index f6f28b3469d..5789faac8d6 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4937.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4937.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4937" title: "Compiler Warning (level 4) C4937" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4937" +ms.date: 11/04/2016 f1_keywords: ["C4937"] helpviewer_keywords: ["C4937"] -ms.assetid: 2bb9f0e7-bbd6-4697-84de-95955e32ae29 --- # Compiler Warning (level 4) C4937 -'text1' and 'text2' are indistinguishable as arguments to 'directive' +> 'text1' and 'text2' are indistinguishable as arguments to 'directive' + +## Remarks Because of the way the compiler processes arguments to directives, names that have meaning to the compiler, such as keywords with multiple text representations (single and double underscore forms), cannot be distinguished. Examples of such strings are __cdecl and \__forceinline. Note, under /Za, only the double underscore forms are enabled. -The following sample generates C4937: +## Example + +The following example generates C4937: ```cpp // C4937.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4938.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4938.md index 86361dc2f44..d2fe0f2e961 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4938.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4938.md @@ -1,18 +1,21 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4938" title: "Compiler Warning (level 4) C4938" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4938" +ms.date: 11/04/2016 f1_keywords: ["C4938"] helpviewer_keywords: ["C4938"] -ms.assetid: 6acac81a-9d23-465e-b700-ed4b6e8edcd0 --- # Compiler Warning (level 4) C4938 -'var' : Floating point reduction variable may cause inconsistent results under /fp:strict or #pragma fenv_access +> 'var' : Floating point reduction variable may cause inconsistent results under /fp:strict or #pragma fenv_access + +## Remarks You should not use [/fp:strict](../../build/reference/fp-specify-floating-point-behavior.md) or [fenv_access](../../preprocessor/fenv-access.md) with OpenMP floating-point reductions, because the sum is computed in a different order. Thus, results can differ from the results without /openmp. -The following sample generates C4938: +## Example + +The following example generates C4938: ```cpp // C4938.cpp diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4960.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4960.md index b2cef66503f..fb44b5e555c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4960.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4960.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4960" title: "Compiler Warning (level 4) C4960" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4960" +ms.date: 11/04/2016 f1_keywords: ["C4960"] helpviewer_keywords: ["C4960"] -ms.assetid: 3b4ed286-9e8d-46f1-af0c-00ba669693a9 --- # Compiler Warning (level 4) C4960 -'function' is too big to be profiled +> 'function' is too big to be profiled + +## Remarks When using [/LTCG:PGOPTIMIZE](../../build/reference/ltcg-link-time-code-generation.md), the compiler detected an input module with a function larger than 65,535 instructions. Such a large function is not available for profile-guided optimizations. diff --git a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4985.md b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4985.md index c073d5dd2cd..4be7325fba3 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4985.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c4985.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Compiler Warning (level 4) C4985" title: "Compiler Warning (level 4) C4985" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (level 4) C4985" +ms.date: 11/04/2016 f1_keywords: ["C4985"] helpviewer_keywords: ["C4985"] -ms.assetid: 832f001c-afe7-403d-a8b4-02334724c79e --- # Compiler Warning (level 4) C4985 > '*symbol-name*': attributes not present on previous declaration. +## Remarks + The Microsoft source code annotation language (SAL) annotations on the current method declaration or definition differ from the annotations on an earlier declaration. The same SAL annotations must be used in the definition and declarations of a method. The SAL provides a set of annotations that you can use to describe how a function uses its parameters, the assumptions it makes about them, and the guarantees it makes on finishing. The annotations are defined in the sal.h header file. 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 00000000000..840a8a254bb --- /dev/null +++ b/docs/error-messages/compiler-warnings/compiler-warning-level-4-c5266.md @@ -0,0 +1,36 @@ +--- +title: "Compiler Warning (level 4) C5266" +description: "Learn more about: 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 + +## Remarks + +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 example 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 e8ca7c73d09..96a81a8c9a0 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,28 @@ --- -description: "Learn more about: Compiler Warning (levels 1 and 4) C4112" -title: "Compiler Warning (levels 1 and 4) C4112" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1 and level 4) C4112" +description: "Learn more about: 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*' + +## Remarks 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)). + +## Example -The following sample generates C4112: +The following example 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-c4115.md b/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4115.md index d881c7f2c15..34868cd3197 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4115.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-levels-1-and-4-c4115.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (levels 1 and 4) C4115" title: "Compiler Warning (levels 1 and 4) C4115" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (levels 1 and 4) C4115" +ms.date: 11/04/2016 f1_keywords: ["C4115"] helpviewer_keywords: ["C4115"] -ms.assetid: f3f94e72-fc49-4d09-b3e7-23d68e61152f --- # Compiler Warning (levels 1 and 4) C4115 -'type' : named type definition in parentheses +> 'type' : named type definition in parentheses + +## Remarks The given symbol is used to define a structure, union, or enumerated type inside a parenthetical expression. The scope of the definition may be unexpected. 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 1cd6fb3afc5..e9f2a839c88 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,14 @@ --- -description: "Learn more about: Compiler Warning (levels 1 and 4) C4223" -title: "Compiler Warning (levels 1 and 4) C4223" -ms.date: "11/04/2016" +title: "Compiler Warning (level 1 and level 4) C4223" +description: "Learn more about: 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. +## Remarks + +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-3-c4008.md b/docs/error-messages/compiler-warnings/compiler-warning-levels-2-and-3-c4008.md index fb62ce06ead..0b0adbc8898 100644 --- a/docs/error-messages/compiler-warnings/compiler-warning-levels-2-and-3-c4008.md +++ b/docs/error-messages/compiler-warnings/compiler-warning-levels-2-and-3-c4008.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Compiler Warning (levels 2 and 3) C4008" title: "Compiler Warning (levels 2 and 3) C4008" -ms.date: "11/04/2016" +description: "Learn more about: Compiler Warning (levels 2 and 3) C4008" +ms.date: 11/04/2016 f1_keywords: ["C4008"] helpviewer_keywords: ["C4008"] -ms.assetid: fb45e535-cb68-4743-80e9-a6e34cfffeca --- # Compiler Warning (levels 2 and 3) C4008 -'identifier' : 'attribute' attribute ignored +> 'identifier' : 'attribute' attribute ignored + +## Remarks The compiler ignored the **`__fastcall`**, **`static`**, or **`inline`** attribute for a function (level 3 warning) or data (level 2 warning). 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 8a6bd71ddf1..b02bcecf7c6 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,40 +1,42 @@ --- -description: "Learn more about: Compiler Warning (levels 2 and 4) C4200" -title: "Compiler Warning (levels 2 and 4) C4200" -ms.date: "11/04/2016" +title: "Compiler Warning (level 2 and level 4) C4200" +description: "Learn more about: 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. +C++ only: +> This member will be ignored by a defaulted constructor or copy/move assignment operator -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: +## Remarks + +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. + +## Example + +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: - -## Example +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: ```cpp // C4200b.cpp // 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 6e064a47f81..68800ee8c01 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,53 +1,62 @@ --- -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 +description: "Learn more about: Compiler Warning (levels 3 and 4) C4244" +ms.date: 11/6/2023 --- # Compiler Warning (levels 3 and 4) C4244 -'conversion' conversion from 'type1' to 'type2', possible loss of data +> 'conversion' conversion from 'type1' to 'type2', possible loss of data + +## Remarks -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. +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 conversion may have a problem due to implicit conversions. +## Examples -The following sample generates C4244: +The following example 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; + + short short1 = int1; // C4244 + short short2 = (short)int1; // warning silenced - explicit cast - bb += c; // C4244 - bb = bb + c; // C4244 - bb += (unsigned short)aa; // C4244 - bb = bb + (unsigned short)aa; // OK + 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: +The following example generates C4244 when compiled for 64-bit targets: ```cpp // C4244_level3_b.cpp 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 772903fbd20..d5706dfc19c 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-by-compiler-version.md @@ -1,7 +1,7 @@ --- title: "Compiler Warnings by compiler version" description: "Table of Microsoft C/C++ compiler warnings by compiler version." -ms.date: 12/01/2021 +ms.date: 01/18/2024 helpviewer_keywords: ["warnings, by compiler version", "cl.exe compiler, setting warning options"] --- # Compiler Warnings by compiler version @@ -12,38 +12,51 @@ 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.14 | 19.44 | +| Visual Studio 2022 version 17.13 | 19.43 | +| Visual Studio 2022 version 17.12 | 19.42 | +| Visual Studio 2022 version 17.11 | 19.41 | +| Visual Studio 2022 version 17.10 | 19.40 | +| Visual Studio 2022 version 17.9 | 19.39 | +| Visual Studio 2022 version 17.8 | 19.38 | +| Visual Studio 2022 version 17.7 | 19.37 | +| Visual Studio 2022 version 17.6 | 19.36 | +| Visual Studio 2022 version 17.5 | 19.35 | +| Visual Studio 2022 version 17.4 | 19.34 | +| Visual Studio 2022 version 17.3 | 19.33 | +| Visual Studio 2022 version 17.2 | 19.32 | | Visual Studio 2022 version 17.1 | 19.31 | +| Visual Studio 2022 version 17.0 RTW | 19.30 | +| Visual Studio 2019 version 16.11 | 19.29.30100.0 | +| Visual Studio 2019 version 16.10 | 19.29.30000.0 | +| Visual Studio 2019 version 16.9 | 19.28.29700.0 | +| Visual Studio 2019 version 16.8 | 19.28.29333.0 | +| Visual Studio 2019 version 16.7 | 19.27.29112.0 | +| Visual Studio 2019 version 16.6 | 19.26.28805.0 | +| Visual Studio 2019 version 16.5 | 19.25.28610.0 | +| Visual Studio 2019 version 16.4 | 19.24.28314.0 | +| Visual Studio 2019 version 16.3 | 19.23.28105.0 | +| Visual Studio 2019 version 16.2 | 19.22.27905.0 | +| Visual Studio 2019 version 16.1 | 19.21.27702.0 | +| Visual Studio 2019 RTM | 19.20.27004.0 | +| Visual Studio 2017 version 15.9 | 19.16.26926.0 | +| Visual Studio 2017 version 15.8 | 19.15.26726.0 | +| Visual Studio 2017 version 15.7 | 19.14.26428.0 | +| Visual Studio 2017 version 15.6 | 19.13.26128.0 | +| Visual Studio 2017 version 15.5 | 19.12.25830.0 | +| Visual Studio 2017 version 15.3 | 19.11.25506.0 | +| Visual Studio 2017 RTM | 19.10.25017.0 | +| Visual Studio 2015 Update 3 | 19.00.24215.1 | +| Visual Studio 2015 Update 2 | 19.00.23918.0 | +| Visual Studio 2015 Update 1 | 19.00.23506.0 | +| Visual Studio 2015 RTM | 19.00.23026.0 | +| Visual Studio 2013 | 18.00.21005.1 | +| Visual Studio 2012 | 17.00.51106.1 | +| Visual Studio 2010 | 16.00.40219.01 | +| Visual Studio 2008 | 15.00.21022.08 | +| Visual Studio 2005 | 14.00.50727.762 | +| Visual Studio 2003 | 13.10.3077 | +| Visual Studio 2002 | 13.00.9466 | You can specify only the major number, the major and minor numbers, or the major, minor, and build numbers to the **`/Wv`** option. The compiler reports all warnings that match versions that begin with the specified number. It suppresses all warnings for versions greater than the specified number. For example, **`/Wv:17`** reports warnings introduced in or before any version of Visual Studio 2012, and suppresses warnings introduced by any compiler from Visual Studio 2013 (version 18) or later. To suppress warnings introduced in Visual Studio 2015 update 2 and later, you can use **`/Wv:19.00.23506`**. Use **`/Wv:19.11`** to report the warnings introduced in any version of Visual Studio before Visual Studio 2017 version 15.5, but suppress warnings introduced in Visual Studio 2017 version 15.5 and later. @@ -51,9 +64,143 @@ 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.14 (compiler version 19.44) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.43`**. + +| Warning | Message | +|--|--| +| C4862 | justification property is not allowed with more than one warning number | + +## Warnings introduced in Visual Studio 2022 version 17.13 (compiler version 19.43) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.42`**. + +| Warning | Message | +|--|--| +|C5277| type trait optimization for '*class name*' is disabled +|C5308| Modifying reserved macro name '*macro name*' may cause undefined behavior +|C5309| literal suffix '*name*' requires at least '*language version*' + +## Warnings introduced in Visual Studio 2022 version 17.12 (compiler version 19.42) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.41`**. + +| Warning | Message | +|--|--| +|C5086| Arch setting *arch* and vector length *number* are not allowed. Using the default vector length - *number*. +|C5276| `/experimental:ifcDebugRecords` currently requires `/Z7` to be enabled. Please recompile with `/Z7` enabled. +|C5306| parameter array behavior change: overload '*identifier 1*' resolved to '*identifier 2*'; previously, it would have resolved to '*identifier 3*'. Use `/clr:ECMAParamArray` to revert to old behavior +|C5307| '*function*': argument (*argument number*) converted from '*type 1*' to '*type 2*'. Missing '`L`' encoding-prefix for character literal? + + +## Warnings introduced in Visual Studio 2022 version 17.11 (compiler version 19.41) + +There were no new warnings introduced in 17.11 + +## Warnings introduced in Visual Studio 2022 version 17.10 (compiler version 19.40) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.39`**. + +| Warning | Message | +|--|--| +|C4859 | '*value*' is not a valid argument for '`/presetWarn`': it must be a decimal value > 0. Command-line flag ignored| +|C4860 | '*object name*': compiler zero initialized '*number*' bytes of storage| +|C4861 | compiler zero initialized '*number*' bytes of storage| +|C5273 | behavior change: `_Alignas` on anonymous type no longer ignored (promoted members will align)| +|C5274 | behavior change: `_Alignas` no longer applies to the type '*type*' (only applies to declared data objects)| +|C5275 | facade assembly '*name*' being imported under '`/clr`'; missing option '`/clr:netcore`'?| +|C5304 | a declaration designated by the using-declaration '*name1*' exported from this module has internal linkage and using such a name outside the module is ill-formed; consider declaring '*name2*' '`inline`' to use it outside of this module| +|C5305 | '*name*': an explicit instantiation declaration that follows an explicit instantiation definition is ignored| + +## Warnings introduced in Visual Studio 2022 version 17.9 (compiler version 19.39) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.38`**. + +| Warning | Message | +|--|--| +|C4975 | modopt '[*modifier*]' was ignored for formal parameter '*parameter*'| +|C5272 | throwing an object of non-copyable type '*type*' is non-standard. If a copy is needed at runtime it will be made as if by `memcpy`.| + +## Warnings introduced in Visual Studio 2022 version 17.8 (compiler version 19.38) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.37`**. + +| Warning | Message | +|--|--| +|C5109|`__VA_OPT__` use in macro requires '`/Zc:preprocessor`'| +|C5110|`__VA_OPT__` is an extension prior to C++20 or C23| +|C5271 | previously imported assembly '*assembly1*' has the same name as assembly '*assembly2*' being imported. Is this intentional?| +|C5303 | function marked with `[[msvc::intrinsic]]` did not result in a no-op cast| + +## Warnings introduced in Visual Studio 2022 version 17.7 (compiler version 19.37) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.36`**. + +| Warning | Message | +|--|--| +|C4907|multiple calling conventions cannot be specified; last given will be used| +|[C5267](c5267.md) | definition of implicit copy constructor/assignment operator for '*type*' is deprecated because it has a user-provided assignment operator/copy constructor| +|C5268 | Failed to allocate memory at fixed address 0x*address*. Use `/Yb` to specify a specific address base if bit-identical .pch files are required.| +|C5269 | Failed to allocate PCH memory at fixed address 0x*address*. Use `/Ym` to specify a specific address base if bit-identical .pch files are required.| +|C5270 | '*value*' is not allowed for option '*switch name*'; allowed values are: *value list*| + +## Warnings introduced in Visual Studio 2022 version 17.6 (compiler version 19.36) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.35`**. + +| Warning | Message | +|--|--| +|[C5266](compiler-warning-level-4-c5266.md) | 'const' qualifier on return type has no effect| + +## Warnings introduced in Visual Studio 2022 version 17.5 (compiler version 19.35) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.34`**. + +| Warning | Message | +|--|--| +|C5082|second argument to 'va_start' is not the last named parameter| +|C5265 | cannot open search path '*path*'| + +## Warnings introduced in Visual Studio 2022 version 17.4 (compiler version 19.34) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.33`**. + +| Warning | Message | +|--|--| +| C5260 | the constant variable '*variable-name*' has internal linkage in an included header file context, but external linkage in imported header unit context; consider declaring it '`inline`' as well if it will be shared across translation units, or '`static`' to express intent to use it local to this translation unit | +| C5261 | no integer type can represent all enumerator values in enumeration '*enum-name*' | +| [C5262](c5262.md) | implicit fall-through occurs here; are you missing a `break` statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases | +| C5263 | calling '`std::move`' on a temporary object prevents copy elision | +| C5264 | '*variable-name*': '`const`' variable is not used | + +## Warnings introduced in Visual Studio 2022 version 17.3 (compiler version 19.33) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.32`**. + +| Warning | Message | +|--|--| +| C5259 | '*specialized-type*': explicit specialization requires 'template <>' | + +## Warnings introduced in Visual Studio 2022 version 17.2 (compiler version 19.32) + +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.31`**. + +| Warning | Message | +|--|--| +| C4983 | '/analyze:sarif:hashname' ignored because the argument to '/analyze:log' is a single file rather than a directory | +| C5081 | Secure hotpatch is not supported with /GENPROFILE, /FASTGENPROFILE or /LTCG:PGI, disabling secure hotpatch. | +| C5255 | unterminated bidirectional character encountered: 'U+XXXX' | +| C5256 | '*enumeration*': a non-defining declaration of an enumeration with a fixed underlying type is only permitted as a standalone declaration | +| C5257 | '*enumeration*': enumeration was previously declared without a fixed underlying type | +| C5258 | explicit capture of '*symbol*' is not required for this use | +| C5300 | '#pragma omp atomic': left operand of '*operator*' must match left hand side of assignment-expression | +|[C5301](c5301-c5302.md) | '#pragma omp for': '*loop-index*' increases while loop condition uses '*comparison*'; non-terminating loop?| +|[C5302](c5301-c5302.md) | '#pragma omp for': '*loop-index*' decreases while loop condition uses '*comparison*'; non-terminating loop?| + ## Warnings introduced in Visual Studio 2022 version 17.1 (compiler version 19.31) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.30`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.30`**. | Warning | Message | |--|--| @@ -63,7 +210,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2022 version 17.0 (compiler version 19.30) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.29`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.29`**. | Warning | Message | |--|--| @@ -80,16 +227,16 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.11 (compiler version 19.29.30100.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.29.30099`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.29.30099`**. | Warning | Message | |--|--| -| C5247 | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior | -| C5248 | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified | +| [C5247](c5247.md) | section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior | +| [C5248](c5248.md) | section '*section-name*' is reserved for C++ dynamic initialization. Variables manually put into the section may be optimized out and their order relative to compiler generated dynamic initializers is unspecified | ## Warnings introduced in Visual Studio 2019 version 16.10 (compiler version 19.29.30000.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.28`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.28`**. | Warning | Message | |--|--| @@ -100,14 +247,14 @@ These warnings and all warnings in later versions are suppressed by using the co | C5237 | cannot resolve header unit entry '*string*' to a header file in '*filename*'; ignoring entry | | C5238 | file system error: cannot open '*filename*' for reading; ignoring | | C5239 | '*Symbol*': potentially-throwing function called from a function declared `__declspec(nothrow)`. Undefined behavior may occur if an exception is thrown. | -| C5240 | '*attribute-string*': attribute is ignored in this syntactic position | +| [C5240](c5240.md) | '*attribute-string*': attribute is ignored in this syntactic position | | C5241 | '`/exportHeader`' usage to lookup header-name is deprecated; prefer '`/headerName:arg-1 arg-2=filename`' | | C5242 | syntax error in pragma '*pragma-name*' | -| C5243 | '*Type-name*': using incomplete class '*symbol*' can cause potential one definition rule violation due to ABI limitation | +| [C5243](c5243.md) | '*Type-name*': using incomplete class '*symbol*' can cause potential one definition rule violation due to ABI limitation | ## Warnings introduced in Visual Studio 2019 version 16.9 (compiler version 19.28.29700.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.28.29699`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.28.29699`**. | Warning | Message | |--|--| @@ -115,11 +262,11 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.8 (compiler version 19.28.29333.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.27`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.27`**. | Warning | Message | |--|--| -| C5072 | `ASAN enabled without debug information emission. Enable debug info for better ASAN error reporting` | +| [C5072](compiler-warning-c5072.md) | `ASAN enabled without debug information emission. Enable debug info for better ASAN error reporting` | | C5211 | `'keyword-1' has been deprecated; prefer using 'keyword-2' instead` | | C5222 | `'attribute-name': all unscoped attribute names are reserved for future standardization` | | C5223 | `all attribute names in the attribute namespace 'msvc' are reserved for the implementation` | @@ -134,7 +281,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.7 (compiler version 19.27.29112.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.26`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.26`**. | Warning | Message | |--|--| @@ -154,16 +301,16 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.6 (compiler version 19.26.28805.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.25`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.25`**. | Warning | Message | |--|--| | C5207 | `the simple requirement asserts the validity of expression 'e->id'. Did you mean '{ e } -> id'? You can suppress the warning using '{ e->id }'` | -| C5208 | `unnamed class used in typedef name cannot declare members other than non-static data members, member enumerations, or member classes` | +| [C5208](c5208.md) | `unnamed class used in typedef name cannot declare members other than non-static data members, member enumerations, or member classes` | ## Warnings introduced in Visual Studio 2019 version 16.5 (compiler version 19.25.28610.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.24`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.24`**. |Warning|Message| |-|-| @@ -177,7 +324,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.4 (compiler version 19.24.28314.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.23`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.23`**. | Warning | Message | |--|--| @@ -188,7 +335,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.3 (compiler version 19.23.28105.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.22`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.22`**. | Warning | Message | |--|--| @@ -197,14 +344,14 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.2 (compiler version 19.22.27905.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.21`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.21`**. | Warning | Message | |--|--| | C4855 | `implicit capture of 'this' via '[=]' is deprecated in 'version'` | -| C5054 | `operator 'operator-name': deprecated between enumerations of different types` | -| C5055 | `operator 'operator-name': deprecated between enumerations and floating-point types` | -| C5056 | `operator 'operator-name': deprecated for array types` | +| [C5054](c5054.md) | `operator 'operator-name': deprecated between enumerations of different types` | +| [C5055](c5055.md) | `operator 'operator-name': deprecated between enumerations and floating-point types` | +| [C5056](c5056.md) | `operator 'operator-name': deprecated for array types` | | C5057 | `header unit reference to 'name' already exists. Ignoring header unit 'header-name'` | | C5058 | `file system error: cannot find header file 'file-name' for header unit 'unit-name'` | | C5059 | `runtime checks and address sanitizer is not currently supported - disabling runtime checks` | @@ -212,7 +359,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 version 16.1 (compiler version 19.21.27702.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.20`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.20`**. | Warning | Message | |--|--| @@ -221,7 +368,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2019 RTW (compiler version 19.20.27004.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.15`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.15`**. | Warning | Message | |--|--| @@ -234,7 +381,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2017 version 15.8 (compiler version 19.15.26726.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.14`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.14`**. | Warning | Message | |--|--| @@ -244,32 +391,32 @@ These warnings and all warnings in later versions are suppressed by using the co | C4846 | `'value' is not a valid argument for '/d1initall': command-line flag ignored` | | C4847 | `'__declspec(no_init_all)' can only be applied to a function, a class type, or a local variable: ignored` | | C4866 | `compiler may not enforce left-to-right evaluation order for call to 'function'` | -| C5046 | `'function': Symbol involving type with internal linkage not defined` | +| [C5046](c5046.md) | `'function': Symbol involving type with internal linkage not defined` | | C5047 | `use of nonstandard __if_exists with modules is not supported` | | C5048 | `Use of macro 'macroname' may result in non-deterministic output` | | C5049 | `'string': Embedding a full path may result in machine-dependent output` | -| C5050 | `Possible incompatible environment while importing module 'module_name': issue` | +| [C5050](c5050.md) | `Possible incompatible environment while importing module 'module_name': issue` | | C5100 | `__VA_ARGS__ is reserved for use in variadic macros` | | C5101 | `use of preprocessor directive in function-like macro argument list is undefined behavior` | | C5102 | `ignoring invalid command-line macro definition 'value'` | | C5103 | `pasting 'token1' and 'token2' does not result in a valid preprocessing token` | | C5104 | `found 'string1#string2' in macro replacement list, did you mean 'string1""#string2'?` | -| C5105 | `macro expansion producing 'defined' has undefined behavior` | +| [C5105](c5105.md) | `macro expansion producing 'defined' has undefined behavior` | | C5106 | `macro redefined with different parameter names` | | C5107 | `missing terminating 'char' character` | ## Warnings introduced in Visual Studio 2017 version 15.7 (compiler version 19.14.26428.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.13`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.13`**. | Warning | Message | |--|--| | C4642 | `'issue': could not import the constraints for generic parameter 'parameter'` | -| C5045 | `Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified` | +| [C5045](c5045.md) | `Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified` | ## Warnings introduced in Visual Studio 2017 version 15.6 (compiler version 19.13.26128.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.12`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.12`**. | Warning | Message | |--|--| @@ -277,11 +424,11 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2017 version 15.5 (compiler version 19.12.25830.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.11`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.11`**. | Warning | Message | |--|--| -| C4843 | `'type1': An exception handler of reference to array or function type is unreachable, use 'type2' instead` | +| [C4843](c4843.md) | `'type1': An exception handler of reference to array or function type is unreachable, use 'type2' instead` | | C4844 | `'export module module_name;' is now the preferred syntax for declaring a module interface` | | C5039 | `'function': pointer or reference to potentially throwing function passed to extern C function under -EHc. Undefined behavior may occur if this function throws an exception.` | | C5040 | `dynamic exception specifications are valid only in C++14 and earlier; treating as noexcept(false)` | @@ -291,64 +438,64 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2017 version 15.3 (compiler version 19.11.25506.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.10`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.10`**. | Warning | Message | |--|--| -| C4597 | `undefined behavior: description` | +| [C4597](c4597.md) | `undefined behavior: description` | | C4604 | `'type': passing argument by value across native and managed boundary requires valid copy constructor. Otherwise the runtime behavior is undefined` | | C4749 | `conditionally supported: description` | -| C4768 | `__declspec attributes before linkage specification are ignored` | -| C4834 | `discarding return value of function with 'nodiscard' attribute` | -| C4841 | `non-standard extension used: extension` | +| [C4768](c4768.md) | `__declspec attributes before linkage specification are ignored` | +| [C4834](c4834.md) | `discarding return value of function with 'nodiscard' attribute` | +| [C4841](c4841.md) | `non-standard extension used: extension` | | C4842 | `the result of 'offsetof' applied to a type using multiple inheritance is not guaranteed to be consistent between compiler releases` | | C4869 | `'nodiscard' may only be applied to classes, enumerations, and functions with non-void return type` | -| C4984 | `'if constexpr' is a C++17 language extension` | -| C5033 | `'*storage-class*' is no longer a supported storage class` | +| [C4984](compiler-warning-c4984.md) | `'if constexpr' is a C++17 language extension` | +| [C5033](c5033.md) | `'*storage-class*' is no longer a supported storage class` | | C5034 | `use of intrinsic 'intrinsic' causes function function to be compiled as guest code` | | C5035 | `use of feature 'feature' causes function function to be compiled as guest code` | | C5036 | `varargs function pointer conversion when compiling with /hybrid:x86arm64 'type1' to 'type2'` | -| C5037 | `'*member-function*': an out-of-line definition of a member of a class template cannot have default arguments` | -| C5038 | `data member 'member1' will be initialized after data member 'member2'` | +| [C5037](c5037.md) | `'*member-function*': an out-of-line definition of a member of a class template cannot have default arguments` | +| [C5038](c5038.md) | `data member 'member1' will be initialized after data member 'member2'` | ## Warnings introduced in Visual Studio 2017 RTM (compiler version 19.10.25017.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00`**. | Warning | Message | |--|--| | C4468 | `'fallthrough': attribute must be followed by a case label or a default label` | -| C4698 | `'feature' is for evaluation purposes only and is subject to change or removal in future updates.` | -| C4839 | `non-standard use of class 'class' as an argument to a variadic function` | -| C4840 | `non-portable use of class 'class' as an argument to a variadic function` | +| [C4698](c4698.md) | `'feature' is for evaluation purposes only and is subject to change or removal in future updates.` | +| [C4839](compiler-warning-level-3-c4839.md) | `non-standard use of class 'class' as an argument to a variadic function` | +| [C4840](compiler-warning-level-4-c4840.md) | `non-portable use of class 'class' as an argument to a variadic function` | ::: moniker-end ## Warnings introduced in Visual Studio 2015 Update 3 (compiler version 19.00.24215.1) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00.23918`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00.23918`**. | Warning | Message | |--|--| | C4467 | `usage of ATL attributes is deprecated` | -| C4596 | `'name': illegal qualified name in member declaration` | +| [C4596](c4596.md) | `'name': illegal qualified name in member declaration` | | C4598 | `'#include
': header number number in the source does not match source at that position` | | C4599 | `'argument': source argument number number does not match source` | ## Warnings introduced in Visual Studio 2015 Update 2 (compiler version 19.00.23918.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00.23506`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00.23506`**. | Warning | Message | |--|--| | C4466 | `Could not perform coroutine heap elision` | | C4595 | `'class': non-member operator new or delete functions may not be declared inline` | | C4828 | `The file contains a character starting at offset 0xvalue that is illegal in the current source character set (codepage number).` | -| C4868 | `compiler may not enforce left-to-right evaluation order in braced initializer list` | +| [C4868](compiler-warning-c4868.md) | `compiler may not enforce left-to-right evaluation order in braced initializer list` | ## Warnings introduced in Visual Studio 2015 Update 1 (compiler version 19.00.23506.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:19.00.23026`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:19.00.23026`**. | Warning | Message | |--|--| @@ -359,24 +506,24 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2015 RTM (compiler version 19.00.23026.0) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:18`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:18`**. | Warning | Message | |--|--| | C4427 | `'error': overflow in constant division, undefined behavior` | | C4438 | `'type': cannot be called safely in /await:clrcompat mode. If 'type' calls into the CLR it may result in CLR head corruption` | | C4455 | `'operator name': literal suffix identifiers that do not start with an underscore are reserved` | -| C4456 | `declaration of 'name' hides previous local declaration` | -| C4457 | `declaration of 'name' hides function parameter` | -| C4458 | `declaration of 'name' hides class member` | -| C4459 | `declaration of 'name' hides global declaration` | -| C4462 | `'type' : cannot determine the GUID of the type. Program may fail at runtime.` | -| C4463 | `overflow; assigning value to bit-field that can only hold values from value to value` | -| C4473 | `'function' : not enough arguments passed for format string` | +| [C4456](compiler-warning-level-4-c4456.md) | `declaration of 'name' hides previous local declaration` | +| [C4457](compiler-warning-level-4-c4457.md) | `declaration of 'name' hides function parameter` | +| [C4458](compiler-warning-level-4-c4458.md) | `declaration of 'name' hides class member` | +| [C4459](compiler-warning-level-4-c4459.md) | `declaration of 'name' hides global declaration` | +| [C4462](compiler-warning-level-1-c4462.md) | `'type' : cannot determine the GUID of the type. Program may fail at runtime.` | +| [C4463](compiler-warning-level-4-c4463.md) | `overflow; assigning value to bit-field that can only hold values from value to value` | +| [C4473](c4473.md) | `'function' : not enough arguments passed for format string` | | C4474 | `'function' : too many arguments passed for format string` | | C4475 | `'function' : length modifier 'modifier' cannot be used with type field character 'character' in format specifier` | | C4476 | `'function' : unknown type field character 'character' in format specifier` | -| C4477 | `'function' : format string 'string' requires an argument of type 'type', but variadic argument number has type 'type'` | +| [C4477](c4477.md) | `'function' : format string 'string' requires an argument of type 'type', but variadic argument number has type 'type'` | | C4478 | `'function' : positional and non-positional placeholders cannot be mixed in the same format string` | | C4494 | `'type' : Ignoring __declspec(allocator) because the function return type is not a pointer or reference` | | C4495 | `nonstandard extension '__super' used: replace with explicit base class name` | @@ -385,7 +532,7 @@ These warnings and all warnings in later versions are suppressed by using the co | C4498 | `nonstandard extension used: 'extension'` | | C4499 | `'specialization': an explicit specialization cannot have a storage class (ignored)` | | C4576 | `a parenthesized type followed by an initializer list is a non-standard explicit type conversion syntax` | -| C4577 | `'noexcept' used with no exception handling mode specified; termination on exception is not guaranteed. Specify /EHsc` | +| [C4577](compiler-warning-level-1-c4577.md) | `'noexcept' used with no exception handling mode specified; termination on exception is not guaranteed. Specify /EHsc` | | C4578 | `'abs': conversion from 'type' to 'type', possible loss of data (Did you mean to call 'name' or to #include ?)` | | C4582 | `'type': constructor is not implicitly called` | | C4583 | `'type': destructor is not implicitly called` | @@ -405,7 +552,7 @@ These warnings and all warnings in later versions are suppressed by using the co | C4776 | `'%character' is not allowed in the format string of function 'function'` | | C4777 | `'description' : format string 'string' requires an argument of type 'type', but variadic argument number has type 'type'` | | C4778 | `'description' : unterminated format string 'string'` | -| C4838 | `conversion from 'type' to 'type' requires a narrowing conversion` | +| [C4838](compiler-warning-level-1-c4838.md) | `conversion from 'type' to 'type' requires a narrowing conversion` | | C5022 | `'type': multiple move constructors specified` | | C5023 | `'type': multiple move assignment operators specified` | | C5024 | `'declaration': move constructor was implicitly defined as deleted` | @@ -418,24 +565,24 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2013 (compiler version 18.00.21005.1) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:17`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:17`**. | Warning | Message | |--|--| | C4301 | `'type': overriding virtual function only differs from 'declaration' by const/volatile qualifier` | -| C4316 | `'type': object allocated on the heap may not be aligned number` | +| [C4316](compiler-warning-level-3-c4316.md) | `'type': object allocated on the heap may not be aligned number` | | C4380 | `'type': A default constructor cannot be deprecated` | -| C4388 | `'token': signed/unsigned mismatch` | +| [C4388](c4388.md) | `'token': signed/unsigned mismatch` | | C4423 | `'std::bad_alloc': will be caught by class ('type') on line number` | | C4424 | `catch for 'type' preceded by 'type' on line number; unpredictable behavior may result if 'std::bad_alloc' is thrown` | | C4425 | `A SAL annotation cannot be applied to '...'` | -| C4464 | `relative include path contains '..'` | +| [C4464](compiler-warning-level-4-c4464.md) | `relative include path contains '..'` | | C4575 | `'__vectorcall' incompatible with the '/clr' option: converting to '__stdcall'` | | C4609 | `'type' derives from default interface 'type' on type 'type'. Use a different default interface for 'type', or break the base/derived relationship.` | -| C4754 | `Conversion rules for arithmetic operations in the comparison at description(number) mean that one branch cannot be executed. Cast 'type' to 'type' (or similar type of number bytes).` | +| [C4754](compiler-warning-level-4-c4754.md) | `Conversion rules for arithmetic operations in the comparison at description(number) mean that one branch cannot be executed. Cast 'type' to 'type' (or similar type of number bytes).` | | C4755 | `Conversion rules for arithmetic operations in the comparison at description(number) mean that one branch cannot be executed in an inlined function. Cast 'type' to 'type' (or similar type of number bytes).` | | C4767 | `section name 'name' is longer than 8 characters and will be truncated by the linker` | -| C4770 | `partially validated enum 'name' used as index` | +| [C4770](c4770.md) | `partially validated enum 'name' used as index` | | C4827 | `A public 'ToString' method with 0 parameters should be marked as virtual and override` | | C4882 | `passing functors with non-const call operators to concurrency::parallel_for_each is deprecated` | | C4973 | `'type': marked as deprecated` | @@ -447,7 +594,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2012 (compiler version 17.00.51106.1) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:16`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:16`**. | Warning | Message | |--|--| @@ -457,9 +604,9 @@ These warnings and all warnings in later versions are suppressed by using the co | C4417 | `an explicit template instantiation cannot have __declspec(code_seg(...)): ignored` | | C4418 | `__declspec(code_seg(...)) ignored on an enum` | | C4419 | `'name' has no effect when applied to private ref class 'type'.` | -| C4435 | `'type': Object layout under /vd2 will change due to virtual base 'type'` | -| C4436 | `dynamic_cast from virtual base 'type' to 'type' in constructor or destructor could fail with partially-constructed object` | -| C4437 | `dynamic_cast from virtual base 'type' to 'type' could fail in some contexts` | +| [C4435](compiler-warning-level-4-c4435.md) | `'type': Object layout under /vd2 will change due to virtual base 'type'` | +| [C4436](compiler-warning-level-1-c4436.md) | `dynamic_cast from virtual base 'type' to 'type' in constructor or destructor could fail with partially-constructed object` | +| [C4437](compiler-warning-level-4-c4437.md) | `dynamic_cast from virtual base 'type' to 'type' could fail in some contexts` | | C4443 | `expected pragma parameter to be '0', '1', or '2'` | | C4446 | `'type': cannot map member 'name' into this type, due to conflict with the type name. The method was renamed to 'name'` | | C4447 | `'main' signature found without threading model. Consider using 'int main(Platform::Array^ args)'.` | @@ -470,17 +617,17 @@ These warnings and all warnings in later versions are suppressed by using the co | C4452 | `'type': public type cannot be at global scope. It must be in a namespace that is a child of the name of the output .winmd file.` | | C4453 | `'type': A '[WebHostHidden]' type should not be used on the published surface of a public type that is not '[WebHostHidden]'` | | C4454 | `'type' is overloaded by more than the number of input parameters without having [DefaultOverload] specified. Picking 'declaration' as the default overload` | -| C4471 | `'name': a forward declaration of an unscoped enumeration must have an underlying type (int assumed)` | +| [C4471](compiler-warning-level-4-c4471.md) | `'name': a forward declaration of an unscoped enumeration must have an underlying type (int assumed)` | | C4472 | `'name' is a native enum: add an access specifier (private/public) to declare a managed/WinRT enum` | | C4492 | `'type': matches base ref class method 'type', but is not marked 'override'` | | C4493 | `delete expression has no effect as the destructor of 'type' does not have 'public' accessibility` | | C4585 | `'type': A WinRT 'public ref class' must either be sealed or derive from an existing unsealed class` | | C4586 | `'type': A public type cannot be declared in a top-level namespace called 'Windows'` | | C4695 | `#pragma execution_character_set: 'argument' is not a supported argument: currently only 'UTF-8' is supported` | -| C4703 | `potentially uninitialized local pointer variable 'name' used` | +| [C4703](compiler-warning-level-4-c4703.md) | `potentially uninitialized local pointer variable 'name' used` | | C4728 | `/Yl- option ignored because PCH reference is required` | | C4745 | `volatile access of 'name' cannot be honored due to its size` | -| C4746 | `volatile access of 'name' is subject to /volatile: setting; consider using __iso_volatile_load/store intrinsic functions` | +| [C4746](compiler-warning-c4746.md) | `volatile access of 'name' is subject to /volatile: setting; consider using __iso_volatile_load/store intrinsic functions` | | C4872 | `floating point division by zero detected when compiling the call graph for the concurrency::parallel_for_each at: 'description'` | | C4880 | `casting from 'type' to 'type': casting away constness from a pointer or reference may result in undefined behavior in an amp restricted function` | | C4881 | `the constructor and/or the destructor will not be invoked for tile_static variable 'type'` | @@ -490,7 +637,7 @@ These warnings and all warnings in later versions are suppressed by using the co ## Warnings introduced in Visual Studio 2010 (compiler version 16.00.40219.01) -These warnings and all warnings in later versions are suppressed by using the compiler option **`/Wv:15`**. +These warnings, and all warnings in later versions, are suppressed by using the compiler option **`/Wv:15`**. | Warning | Message | |--|--| @@ -501,350 +648,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 36315ad4e83..08f6b5cf34b 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 90331c83097..83f1da2def0 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 4961aca1fd5..e91e5e89600 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)|'*type*': 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 bc648f2588e..e0ce42c2539 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)|'*operator*' 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 e121d8ff1aa..26ff337deb2 100644 --- a/docs/error-messages/compiler-warnings/compiler-warnings-c4600-through-c4799.md +++ b/docs/error-messages/compiler-warnings/compiler-warnings-c4600-through-c4799.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Compiler warnings C4600 Through C4799" -title: "Compiler warnings C4600 Through C4799" +title: "Microsoft C/C++ compiler (MSVC) warnings C4600 through C4799" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings C4600 through C4799" ms.date: 05/03/2021 -f1_keywords: ["C4609", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4728", "C4732", "C4751", "C4752", "C4755", "C4757", "C4767", "C4770"] -helpviewer_keywords: ["C4609", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4728", "C4732", "C4751", "C4752", "C4755", "C4757", "C4767", "C4770"] -ms.assetid: 22bd4392-f3be-445c-9f23-6126aebac901 +f1_keywords: ["C4604", "C4605", "C4609", "C4631", "C4642", "C4643", "C4644", "C4647", "C4648", "C4649", "C4654", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4725", "C4726", "C4728", "C4729", "C4732", "C4734", "C4735", "C4736", "C4745", "C4749", "C4751", "C4752", "C4753", "C4755", "C4757", "C4761", "C4767", "C4771", "C4774", "C4775", "C4776", "C4777", "C4778", "C4792", "C4798"] +helpviewer_keywords: ["C4604", "C4605", "C4609", "C4631", "C4642", "C4643", "C4644", "C4647", "C4648", "C4649", "C4654", "C4658", "C4671", "C4676", "C4689", "C4695", "C4696", "C4719", "C4720", "C4721", "C4725", "C4726", "C4728", "C4729", "C4732", "C4734", "C4735", "C4736", "C4745", "C4749", "C4751", "C4752", "C4753", "C4755", "C4757", "C4761", "C4767", "C4771", "C4774", "C4775", "C4776", "C4777", "C4778", "C4792", "C4798"] --- -# Compiler warnings C4600 Through C4799 +# Microsoft C/C++ compiler warnings C4600 through C4799 -The articles in this section of the documentation explain a subset of the warning messages that are generated by the compiler. +The articles in this section describe Microsoft C/C++ compiler warning messages C4600 through C4799. [!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] @@ -16,153 +15,165 @@ 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 C4737| Unable to perform required tail call. Performance may be degraded. See [`[[msvc::musttail]]`](../../cpp/attributes.md#msvcmusttail)| +|[Compiler warning (Level 3) C4738](compiler-warning-level-3-c4738.md)|storing 32-bit float result in memory, possible loss of performance| |[Compiler warning (level 1) C4739](compiler-warning-level-1-c4739.md)|reference to variable 'var' exceeds its storage space| -|[Compiler warning (Level 4) C4740](../../error-messages/compiler-warnings/compiler-warning-level-4-c4740.md)|flow in or out of inline asm code suppresses global optimization| -|[Compiler warning (Level 1) C4742](../../error-messages/compiler-warnings/compiler-warning-level-1-c4742.md)|'var' has different alignment in 'file1' and 'file2': number and number| -|[Compiler warning (Level 1) C4743](../../error-messages/compiler-warnings/compiler-warning-level-1-c4743.md)|'type' has different size in 'file1' and 'file2': number and number bytes| -|[Compiler warning (Level 1) C4744](../../error-messages/compiler-warnings/compiler-warning-level-1-c4744.md)|'var' has different type in 'file1' and 'file2': 'type1' and 'type2'| -|[Compiler warning C4746](../../error-messages/compiler-warnings/compiler-warning-c4746.md)|volatile access of '*expression*' is subject to /volatile:\ setting; consider using __iso_volatile_load/store intrinsic functions| -|[Compiler warning (level 1) C4747](../../error-messages/compiler-warnings/compiler-warning-level-1-c4747.md)|Calling managed 'entrypoint': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint| -|Compiler warning (level 4) C4749|conditionally supported: offsetof applied to non-standard-layout type '*type*'| -|[Compiler warning (level 1) C4750](compiler-warning-level-1-c4750.md)|'identifier': function with _alloca() inlined into a loop| -|Compiler warning (level 4) C4751|/arch:AVX does not apply to Intel(R) Streaming SIMD Extensions that are within inline ASM| -|Compiler warning (level 4) C4752|found Intel(R) Advanced Vector Extensions; consider using /arch:AVX| +|[Compiler warning (Level 4) C4740](compiler-warning-level-4-c4740.md)|flow in or out of inline asm code suppresses global optimization| +|[Compiler warning (Level 1) C4742](compiler-warning-level-1-c4742.md)|'var' has different alignment in 'file1' and 'file2': number and number| +|[Compiler warning (Level 1) C4743](compiler-warning-level-1-c4743.md)|'type' has different size in 'file1' and 'file2': number and number bytes| +|[Compiler warning (Level 1) C4744](compiler-warning-level-1-c4744.md)|'var' has different type in 'file1' and 'file2': 'type1' and 'type2'| +|Compiler warning C4745|volatile access of 'name' cannot be honored due to its size| +|[Compiler warning C4746](compiler-warning-c4746.md)|volatile access of '*expression*' is subject to `/volatile:` setting; consider using `__iso_volatile_load/store intrinsic functions`| +|[Compiler warning (level 1) C4747](compiler-warning-level-1-c4747.md)|Calling managed 'entrypoint': Managed code may not be run under loader lock, including the DLL entrypoint and calls reached from the DLL entrypoint| +|Compiler warning (level 4, off) C4749|conditionally supported: *message*| +|[Compiler warning (level 1) C4750](compiler-warning-level-1-c4750.md)|'identifier': function with `_alloca()` inlined into a loop| +|Compiler warning (level 4) C4751|`/arch:AVX` does not apply to Intel(R) Streaming SIMD Extensions that are within inline ASM| +|Compiler warning (level 4) C4752|found Intel(R) Advanced Vector Extensions; consider using `/arch:AVX`| +|Compiler warning C4753|Cannot find bounds for pointer; MPX intrinsic function ignored| |[Compiler warning (level 4) C4754](compiler-warning-level-4-c4754.md)|Conversion rules for arithmetic operations in the comparison at %s(%d) mean that one branch cannot be executed. Cast '%s' to '%s' (or similar type of %d bytes).| |Compiler warning C4755|Conversion rules for arithmetic operations in the comparison at %s(%d) mean that one branch cannot be executed in an inlined function. Cast '%s' to '%s' (or similar type of %d bytes).| -|[Compiler warning (level 2) C4756](../../error-messages/compiler-warnings/compiler-warning-level-2-c4756.md)|overflow in constant arithmetic| +|[Compiler warning (level 2) C4756](compiler-warning-level-2-c4756.md)|overflow in constant arithmetic| |Compiler warning (level 4) C4757|subscript is a large unsigned value, did you intend a negative constant?| +|Compiler warning C4761|integral size mismatch in argument; conversion supplied| |[Compiler warning (level 4) C4764](compiler-warning-level-4-c4764.md)|Can not align catch objects to greater than 16 bytes| -|Compiler warning (level 4) C4767|section name '%s' is longer than 8 characters and will be truncated by the linker| -|[Compiler warning (level 3) C4768](c4768.md)|__declspec attributes before linkage specification are ignored| -|Compiler warning C4770|partially validated enum '*name*' used as index| +|Compiler warning (level 4, off) C4767|section name '%s' is longer than 8 characters and will be truncated by the linker| +|[Compiler warning (level 3, off) C4768](c4768.md)|`__declspec` attributes before linkage specification are ignored| +| [Compiler warning (level 4) C4770](./c4770.md) | partially validated enum '*name*' used as index | |Compiler warning C4771|Bounds must be created using a simple pointer; MPX intrinsic function ignored| -|[Compiler warning (level 1, Error) C4772](../../error-messages/compiler-warnings/compiler-warning-level-1-c4772.md)|#import referenced a type from a missing type library; 'missing_type' used as a placeholder| -|Compiler warning (level 4) C4774|'*string*' : format string expected in argument *number* is not a string literal| +|[Compiler warning (level 1, error) C4772](compiler-warning-level-1-c4772.md)|`#import` referenced a type from a missing type library; '*missing_type*' used as a placeholder| +|Compiler warning (level 4, off) C4774|'*string*' : format string expected in argument *number* is not a string literal| |Compiler warning (level 3) C4775|nonstandard extension used in format string '*string*' of function '*function*'| -|Compiler warning (level 1) C4776|'%*character*' is not allowed in the format string of function '*function*'| -|Compiler warning (level 4) C4777|'*function*' : format string '*string*' requires an argument of type '*type1*', but variadic argument *number* has type '*type2*'| +|Compiler warning (level 1) C4776|'`%`*character*' is not allowed in the format string of function '*function*'| +|Compiler warning (level 4, off) C4777|'*function*' : format string '*string*' requires an argument of type '*type1*', but variadic argument *number* has type '*type2*'| |Compiler warning (level 3) C4778|'*function*' : unterminated format string '*string*'| -|[Compiler warning (Level 1) C4788](../../error-messages/compiler-warnings/compiler-warning-level-1-c4788.md)|'identifier': identifier was truncated to 'number' characters| -|[Compiler warning (Level 1) C4789](../../error-messages/compiler-warnings/compiler-warning-level-1-c4789.md)|buffer 'identifier' of size N bytes will be overrun; M bytes will be written starting at offset L| -|Compiler warning (level 2) C4792|function '%s' declared using sysimport and referenced from native code; import library required to link| -|[Compiler warning (level 1 and 3) C4793](../../error-messages/compiler-warnings/compiler-warning-level-1-and-3-c4793.md)|'function': function compiled as native: 'reason'| +|[Compiler warning (Level 1) C4788](compiler-warning-level-1-c4788.md)|'identifier': identifier was truncated to 'number' characters| +|[Compiler warning (Level 1) C4789](compiler-warning-level-1-c4789.md)|buffer 'identifier' of size N bytes will be overrun; M bytes will be written starting at offset L| +|Compiler warning (level 2) C4792|function '%s' declared using `sysimport` and referenced from native code; import library required to link| +|[Compiler warning (level 1 and level 3) C4793](compiler-warning-level-1-and-3-c4793.md)|'*function*': function compiled as native:
*reason*| |[Compiler warning (level 1) C4794](compiler-warning-level-1-c4794.md)|segment of thread local storage variable '%s' changed from '%s' to '%s'| -|[Compiler warning (level 1) C4799](../../error-messages/compiler-warnings/compiler-warning-level-1-c4799.md)|function 'function' has no EMMS instruction| +|Compiler warning C4798|native code generated for p-code function 'name' with exception handler or unwind semantics| +|[Compiler warning (level 1) C4799](compiler-warning-level-1-c4799.md)|function '*function*' has no EMMS instruction| ## See also -[C/C++ Compiler and build tools errors and warnings](../compiler-errors-1/c-cpp-build-errors.md) \ +[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-c4800-through-c4999.md b/docs/error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md index 43b04684186..3ac4f3718a5 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: 02/22/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", "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", "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"] -helpviewer_keywords: ["C4808", "C4809", "C4825", "C4827", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4854", "C4855", "C4856", "C4857", "C4872", "C4880", "C4881", "C4882", "C4916", "C4921", "C4934", "C4954", "C4955", "C4963", "C4966", "C4970", "C4971", "C4973", "C4974", "C4981", "C4987", "C4988", "C4989", "C4990", "C4991", "C4992", "C4998", "C5022", "C5023", "C5024", "C5025", "C5026", "C5027", "C5028", "C5029", "C5030", "C5031", "C5032", "C5034", "C5035", "C5036", "C5039", "C5040", "C5041", "C5042", "C5043", "C5044", "C5047", "C5048", "C5049", "C5051", "C5052", "C5053", "C5057", "C5058", "C5059", "C5060", "C5061", "C5062", "C5063", "C5100", "C5101", "C5102", "C5103", "C5104", "C5106", "C5107", "C5108", "C5200", "C5201", "C5202", "C5203", "C5204", "C5205", "C5206", "C5207", "C5209", "C5210", "C5211", "C5212", "C5213", "C5214", "C5215", "C5216", "C5217", "C5218", "C5219", "C5220", "C5221", "C5222", "C5223", "C5224", "C5225", "C5226", "C5227", "C5228", "C5229", "C5230", "C5231", "C5232", "C5233", "C5234", "C5235", "C5236", "C5237", "C5238", "C5239", "C5241", "C5242", "C5244", "C5245", "C5246", "C5249", "C5250", "C5251", "C5252", "C5253", "C5254"] +title: "Microsoft C/C++ compiler (MSVC) warnings C4800 through C4999" +description: "Table of Microsoft C/C++ compiler (MSVC) warnings C4800 through C4999." +ms.date: 04/17/2024 +f1_keywords: ["C4801", "C4808", "C4809", "C4815", "C4826", "C4827", "C4828", "C4837", "C4842", "C4844", "C4845", "C4846", "C4847", "C4848", "C4849", "C4854", "C4855", "C4856", "C4857", "C4858", "C4859", "C4860", "C4861", "C4862", "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", "C4862", "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,218 +24,126 @@ 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 1) C4862 | justification property is not allowed with more than one warning number | | [Compiler warning (level 4) C4866](c4866.md) | compiler may not enforce left-to-right evaluation order for call to *operator_name* | -| [Compiler warning (level 1, error) C4867](compiler-warning-c4867.md) | '*function*': function call missing argument list; use '*call*' to create a pointer to member | -| [Compiler warning (level 4) C4868](compiler-warning-c4868.md) | '_file_(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | +| [Compiler warning (level 1, error) C4867](compiler-warning-c4867.md) |'*function name*': non-standard syntax; use '`&`' to create a pointer to member| +| [Compiler warning (level 4) C4868](compiler-warning-c4868.md) | '*file*(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | +| Compiler warning (level 3) C4869 | '`nodiscard`' may only be applied to classes, enumerations, and functions | | Compiler warning (level 2) C4872 | floating point division by zero detected when compiling the call graph for the `concurrency::parallel_for_each` at: '*location*' | -| Compiler warning (level 1) C4880 | casting from 'const *type_1*' to '*type_2*': casting away constness from a pointer or reference may result in undefined behavior in an amp restricted function | +| Compiler warning (level 1) C4880 | casting from '*const type_1*' to '*type_2*': casting away constness from a pointer or reference may result in undefined behavior in an `amp` restricted function | | Compiler warning (level 4) C4881 | the constructor and/or the destructor will not be invoked for `tile_static` variable '*variable-name*' | | Compiler warning (level 1) C4882 | passing functors with non-const call operators to `concurrency::parallel_for_each` is deprecated | +| Compiler warning C4883 | '*function name*': function size suppresses optimizations | | [Compiler warning C4900](compiler-warning-level-1-c4900.md) | Il mismatch between '*tool1*' version '*version1*' and '*tool2*' version '*version2*' | -| [Compiler warning (level 1, off) C4905](compiler-warning-level-1-c4905.md) | wide string literal cast to '`LPSTR`' | -| [Compiler warning (level 1, off) C4906](compiler-warning-level-1-c4906.md) | string literal cast to '`LPWSTR`' | -| [Compiler warning (level 1) C4910](compiler-warning-level-1-c4910.md) | '\: '__declspec(dllexport)' and 'extern' are incompatible on an explicit instantiation | +| [Compiler warning (level 1, off) C4905](compiler-warning-level-1-c4905.md) | wide string literal cast to '*type*' | +| [Compiler warning (level 1, off) C4906](compiler-warning-level-1-c4906.md) | string literal cast to '*type*' | +| Compiler warning (error) C4907 | multiple calling conventions cannot be specified; last given will be used | +| [Compiler warning (level 1) C4910](compiler-warning-level-1-c4910.md) |'*identifier*': '`__declspec(dllexport)`' and '`extern`' are incompatible on an explicit instantiation| | [Compiler warning (level 1) C4912](compiler-warning-level-1-c4912.md) | '*attribute*': attribute has undefined behavior on a nested UDT | | [Compiler warning (level 4) C4913](compiler-warning-level-4-c4913.md) | user defined binary operator '`,`' exists but no overload could convert all operands, default built-in binary operator '`,`' used | | Compiler warning (level 1) C4916 | in order to have a `dispid`, '*description*': must be introduced by an interface | | [Compiler warning (level 1, off) C4917](compiler-warning-level-1-c4917.md) | '*declarator*': a GUID can only be associated with a class, interface or namespace | | [Compiler warning (level 4) C4918](compiler-warning-level-4-c4918.md) | '*character*': invalid character in pragma optimization list | -| [Compiler warning (level 1) C4920](compiler-warning-level-1-c4920.md) | enum *enum-name* member *member_1*=*value_1* already seen in enum *enum-name* as *member_2*=*value_2* | +| [Compiler warning (level 1) C4920](compiler-warning-level-1-c4920.md) | `enum` *enum-name* member *member_1*`=`*value_1* already seen in `enum` *enum-name* as *member_2*`=`*value_2* | | Compiler warning (level 3) C4921 | '*description*': attribute value '*attribute*' should not be multiply specified | -| [Compiler warning (level 1) C4925](compiler-warning-level-1-c4925.md) | '*method*': dispinterface method cannot be called from script | +| [Compiler warning (level 1) C4925](compiler-warning-level-1-c4925.md) | '*method*': `dispinterface` method cannot be called from script | | [Compiler warning (level 1) C4926](compiler-warning-level-1-c4926.md) | '*identifier*': symbol is already defined: attributes ignored | | [Compiler warning (level 1) C4927](compiler-warning-level-1-c4927.md) | illegal conversion; more than one user-defined conversion has been implicitly applied | | [Compiler warning (level 1, off) C4928](compiler-warning-level-1-c4928.md) | illegal copy-initialization; more than one user-defined conversion has been implicitly applied | -| [Compiler warning (level 1) C4929](compiler-warning-level-1-c4929.md) | '*file*': typelibrary contains a union; ignoring the 'embedded_idl' qualifier | +| [Compiler warning (level 1) C4929](compiler-warning-level-1-c4929.md) | '*file*': `typelibrary` contains a union; ignoring the '`embedded_idl`' qualifier | | [Compiler warning (level 1) C4930](compiler-warning-level-1-c4930.md) | '*prototype*': prototyped function not called (was a variable definition intended?) | | [Compiler warning (level 4, off) C4931](compiler-warning-level-4-c4931.md) | we are assuming the type library was built for *number*-bit pointers | | [Compiler warning (level 4) C4932](compiler-warning-level-4-c4932.md) | `__identifier(`*identifier*`)` and `__identifier(`*identifier*`)` are indistinguishable | | Compiler warning (level 1) C4934 | '`__delegate(multicast)`' is deprecated, use '`__delegate`' instead | | [Compiler warning (level 1) C4935](compiler-warning-level-1-c4935.md) | assembly access specifier modified from '*access*' | -| [Compiler warning (level 1, Error) C4936](compiler-warning-c4936.md) | this __declspec is supported only when compiled with `/clr` or `/clr:pure` | +| [Compiler warning (level 1, error) C4936](compiler-warning-c4936.md) | this `__declspec` is supported only when compiled with `/clr` or `/clr:pure` | | [Compiler warning (level 4) C4937](compiler-warning-level-4-c4937.md) | '*text1*' and '*text2*' are indistinguishable as arguments to '*directive*' | | [Compiler warning (level 4) C4938](compiler-warning-level-4-c4938.md) | '*var*': Floating point reduction variable may cause inconsistent results under `/fp:strict` or `#pragma fenv_access` | -| [Compiler warning C4939](compiler-warning-level-1-c4939.md) | #pragma vtordisp is deprecated and will be removed in a future release of Visual C++ | +| [Compiler warning (level 1) C4939](compiler-warning-level-1-c4939.md) | `#pragma vtordisp` is deprecated and will be removed in a future release of Visual C++ | | [Compiler warning (level 1) C4944](compiler-warning-level-1-c4944.md) | '*symbol*': cannot import symbol from '*assembly1*': as '*symbol*' already exists in the current scope | | [Compiler warning (level 1) C4945](compiler-warning-level-1-c4945.md) | '*symbol*': cannot import symbol from '*assembly1*': as '*symbol*' has already been imported from another assembly '*assembly2*' | | [Compiler warning (level 1, off) C4946](compiler-warning-level-1-c4946.md) | `reinterpret_cast` used between related classes: '*class1*' and '*class2*' | | [Compiler warning (level 1) C4947](compiler-warning-level-1-c4947.md) | '*type_or_member*': marked as obsolete | | [Compiler warning (level 2) C4948](compiler-warning-level-2-c4948.md) | return type of '*accessor*' does not match the last parameter type of the corresponding setter | -| [Compiler warning (level 1 and level 4) C4949](compiler-warning-level-1-and-level-4-c4949.md) | pragmas '`managed`' and '`unmanaged`' are meaningful only when compiled with '`/clr[:option]`' | -| [Compiler warning (level 1, Error) C4950](compiler-warning-c4950.md) | '*type_or_member*': marked as obsolete | +| [Compiler warning (level 1 and level 4) C4949](compiler-warning-level-1-and-level-4-c4949.md) | `pragma` '*pragma*' is meaningful only when compiled with '`/clr[:option]`'| +| [Compiler warning (level 1, error) C4950](compiler-warning-c4950.md) | '*type_or_member*': marked as obsolete | | [Compiler warning (level 1) C4951](compiler-warning-level-1-c4951.md) | '*function*' has been edited since profile data was collected, function profile data not used | | [Compiler warning (level 1) C4952](compiler-warning-level-1-c4952.md) | '*function*': no profile data found in program database '*pgd-file*' | | [Compiler warning (level 1) C4953](compiler-warning-level-1-c4953.md) | Inlinee '*function*' has been edited since profile data was collected, profile data not used | | Compiler warning C4954 | '*function*': not profiled (contains `__int64` switch expression) | | Compiler warning C4955 | '*import2*': import ignored; already imported from '*import1*' | -| [Compiler warning (level 1, Error) C4956](compiler-warning-c4956.md) | '*type*': this type is not verifiable | -| [Compiler warning (level 1, Error) C4957](compiler-warning-c4957.md) | '*cast*': explicit cast from '*cast_from*' to '*cast_to*' is not verifiable | -| [Compiler warning (level 1, Error) C4958](compiler-warning-c4958.md) | '*operation*': pointer arithmetic is not verifiable | -| [Compiler warning (level 1, Error) C4959](compiler-warning-c4959.md) | cannot define unmanaged type '*type*' in `/clr:safe` because accessing its members yields unverifiable code | +| [Compiler warning (level 1, error) C4956](compiler-warning-c4956.md) | '*type*': this type is not verifiable | +| [Compiler warning (level 1, error) C4957](compiler-warning-c4957.md) | '*cast*': explicit cast from '*cast_from*' to '*cast_to*' is not verifiable | +| [Compiler warning (level 1, error) C4958](compiler-warning-c4958.md) | '*operation*': pointer arithmetic is not verifiable | +| [Compiler warning (level 1, error) C4959](compiler-warning-c4959.md) | cannot define unmanaged *type* '*identifier*' in `/clr:safe` because accessing its members yields unverifiable code | | [Compiler warning (level 4) C4960](compiler-warning-level-4-c4960.md) | '*function*' is too big to be profiled | | [Compiler warning (level 1) C4961](compiler-warning-c4961.md) | No profile data was merged into '*pgd-file*', profile-guided optimizations disabled | | [Compiler warning (level 4, off) C4962](compiler-warning-c4962.md) | '*function*': Profile-guided optimizations disabled because optimizations caused profile data to become inconsistent | | Compiler warning (level 1) C4963 | '*description*': no profile data found; different compiler options were used in instrumented build | | [Compiler warning (level 1) C4964](compiler-warning-level-1-c4964.md) | No optimization options were specified; profile info will not be collected | -| [Compiler warning (level 1) C4965](compiler-warning-level-1-c4965.md) | implicit box of integer 0; use nullptr or explicit cast | +| [Compiler warning (level 1) C4965](compiler-warning-level-1-c4965.md) | implicit box of integer `0`; use `nullptr` or explicit cast | | Compiler warning (level 1) C4966 | '*function*' has `__code_seg` annotation with unsupported segment name, annotation ignored | | Compiler warning C4970 | delegate constructor: target object ignored since '*type*' is static | -| Compiler warning (level 1) C4971 | Argument order: \, \ for delegate constructor is deprecated, use \, \ | -| [Compiler warning (level 1, Error) C4972](compiler-warning-c4972.md) | Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable | +| Compiler warning (level 1, no longer emitted) C4971 |Argument order: ``, `` for delegate constructor is deprecated, use ``, ``| +| [Compiler warning (level 1, error) C4972](compiler-warning-c4972.md) | Directly modifying or treating the result of an unbox operation as an lvalue is unverifiable | | Compiler warning (level 1) C4973 | '*symbol*': marked as deprecated | | Compiler warning (level 1) C4974 | '*symbol*': marked as deprecated | -| Compiler warning (level 3) C4981 | Warbird: function '*function*' marked as __forceinline not inlined because it contains exception semantics | -| [Compiler warning C4984](compiler-warning-c4984.md) | '`if constexpr`' is a C++17 language extension | -| [Compiler warning (level 4) C4985](compiler-warning-level-4-c4985.md) | '*symbol_name*': attributes not present on previous declaration. | -| [Compiler warning (level 4, off) C4986](compiler-warning-c4986.md) | '*declaration*': exception specification does not match previous declaration | +| Compiler warning (level 1) C4975 | modopt '[*modifier*]' was ignored for formal parameter '*parameter*' | +| Compiler warning (level 1) C4976 | invalid value '*value*' for '`/W`'; assuming '`1`' | +| Compiler warning (level 3) C4981 | Warbird: function '*function*' marked as `__forceinline` not inlined because it contains exception semantics | +| Compiler warning (level 3) C4983 | '`/analyze:sarif:hashname`' ignored because the argument to '`/analyze:log`' is a single file rather than a directory | +| [Compiler warning (level 1) C4984](compiler-warning-c4984.md) | '`if constexpr`' is a C++17 language extension | +| [Compiler warning (level 3) C4985](compiler-warning-level-4-c4985.md) | '*symbol_name*': attributes not present on previous declaration. | +| [Compiler warning (level 2 and level 4, off) C4986](compiler-warning-c4986.md) | '*declaration*': exception specification does not match previous declaration | | Compiler warning (level 4, off) C4987 | nonstandard extension used: '`throw (...)`' | | Compiler warning (level 4, off) C4988 | '*variable*': variable declared outside class/function scope | | Compiler warning (level 4) C4989 | '*type*': type has conflicting definitions. | | Compiler warning (level 3) C4990 | Warbird: *message* | | Compiler warning (level 3) C4991 | Warbird: function '*function*' marked as `__forceinline` not inlined because protection level of inlinee is greater than the parent | | Compiler warning (level 3) C4992 | Warbird: function '*function-name*' marked as `__forceinline` not inlined because it contains inline assembly which cannot be protected | -| [Compiler warning (level 3) C4995](compiler-warning-level-3-c4995.md) | '*function*': name was marked as #pragma deprecated | -| [Compiler warning (level 3) C4996](compiler-warning-level-3-c4996.md) | '*deprecated-declaration*': *deprecation-message* (or "was declared deprecated") | -| [Compiler warning (level 1) C4997](compiler-warning-level-1-c4997.md) | '*class*': coclass does not implement a COM interface or pseudo-interface | +| [Compiler warning (level 3) C4995](compiler-warning-level-3-c4995.md) | '*function*': name was marked as `#pragma deprecated` | +| [Compiler warning (level 3) C4996](compiler-warning-level-3-c4996.md) | '*deprecated-declaration*': *deprecation-message* | +| [Compiler warning (level 1) C4997](compiler-warning-level-1-c4997.md) | '*class*': `coclass` does not implement a COM interface or pseudo-interface | | Compiler warning (level 1) C4998 | EXPECTATION FAILED: *expectation*(*value*) | -| [Compiler warning C4999](compiler-warning-level-1-c4999.md) | UNKNOWN WARNING Please choose the Technical Support command on the Visual C++ Help menu, or open the Technical Support help file for more information | -| Compiler warning C5022 | '*type*': multiple move constructors specified | -| Compiler warning C5023 | '*type*': multiple move assignment operators specified | -| Compiler warning (level 4, off) C5024 | '*type*': move constructor was implicitly defined as deleted | -| Compiler warning (level 4, off) C5025 | '*type*': move assignment operator was implicitly defined as deleted | -| Compiler warning (level 1 and level 4, off) C5026 | '*type*': move constructor was implicitly defined as deleted | -| Compiler warning (level 1 and level 4, off) C5027 | '*type*': move assignment operator was implicitly defined as deleted | -| Compiler warning (level 1) C5028 | '*name*': Alignment specified in prior declaration (*number*) not specified in definition | -| Compiler warning (level 4, off) C5029 | nonstandard extension used: alignment attributes in C++ apply to variables, data members and tag types only | -| Compiler warning (level 3) C5030 | attribute '*attribute-name*' is not recognized | -| Compiler warning (level 4, off) C5031 | `#pragma warning(pop)`: likely mismatch, popping warning state pushed in different file | -| Compiler warning (level 4, off) C5032 | detected `#pragma warning(push)` with no corresponding `#pragma warning(pop)` | -| [Compiler warning (level 1) C5033](c5033.md) | '*storage-class*' is no longer a supported storage class | -| Compiler warning (level 5, off) C5034 | use of intrinsic '*intrinsic*' causes function *function-name* to be compiled as guest code | -| Compiler warning (level 5, off) C5035 | use of feature '*feature*' causes function *function-name* to be compiled as guest code | -| Compiler warning (level 1) C5036 | varargs function pointer conversion when compiling with `/hybrid:x86arm64` '*type1*' to '*type2*' | -| [Compiler warning (error) C5037](c5037.md) | '*member-function*': an out-of-line definition of a member of a class template cannot have default arguments | -| [Compiler warning (level 4, off) C5038](c5038.md) | data member '*member1*' will be initialized after data member '*member2*' | -| Compiler warning (level 4, off) C5039 | '*function*': pointer or reference to potentially throwing function passed to `extern C` function under `-EHc`. Undefined behavior may occur if this function throws an exception. | -| Compiler warning (level 3) C5040 | dynamic exception specifications are valid only in C++14 and earlier; treating as noexcept(false) | -| Compiler warning (level 1, off) C5041 | '*definition*': out-of-line definition for constexpr static data member is not needed and is deprecated in C++17 | -| Compiler warning (level 3, off) C5042 | '*declaration*': function declarations at block scope cannot be specified 'inline' in standard C++; remove 'inline' specifier | -| Compiler warning (level 2) C5043 | '*specification*': exception specification does not match previous declaration | -| Compiler warning (level 4) C5044 | An argument to command-line option *option-name* points to a path '*path-name*' that does not exist | -| [Compiler warning (level 4) C5045](c5045.md) | Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified | -| [Compiler warning (level 2) C5046](c5046.md) | '*function*': Symbol involving type with internal linkage not defined | -| Compiler warning (level 1) C5047 | use of nonstandard `__if_exists` with modules is not supported | -| Compiler warning (level 1) C5048 | Use of macro '*macroname*' may result in non-deterministic output | -| Compiler warning (level 1) C5049 | '*string*': Embedding a full path may result in machine-dependent output | -| [Compiler warning (level 1) C5050](c5050.md) | Possible incompatible environment while importing module '*module_name*': *issue* | -| Compiler warning (level 1) C5051 | attribute 'attribute-name' requires at least 'standard-level'; ignored | -| Compiler warning (level 3, off) C5052 | Keyword 'keyword-name' was introduced in C++\ and requires use of the 'option-name' command-line option | -| Compiler warning (level 1) C5053 | support for '`explicit()`' in C++17 and earlier is a vendor extension | -| [Compiler warning (level 4) C5054](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) 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*'. 17.0 | -| Compiler warning (level 3, off) C5250 | '*function_name*': intrinsic function not declared. 17.0 | -| Compiler warning (level 4, off) C5251 | *segment-name* changed after including header 17.1 | -| Compiler warning (level 4) C5252 | Multiple different types resulted in the same XFG type-hash *hash-value*; the PDB will only record information for one of them 17.0 | -| Compiler warning (level 4) C5253 | a non-local lambda cannot have a capture default 17.1 | -| Compiler warning (level 4, off) C5254 | language feature 'terse static assert' requires compiler flag '/std:c++17' 17.1 | ## See also 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 00000000000..38f4e448954 --- /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 00000000000..0bebc97caa6 --- /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", "C5276", "C5277", "C5278", "C5279", "C5280", "C5281", "C5282", "C5283", "C5284", "C5285", "C5286", "C5287", "C5300", "C5303", "C5304", "C5305", "C5306", "C5307", "C5308", "C5309"] +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", "C5276", "C5277", "C5278", "C5279", "C5280", "C5281", "C5282", "C5283", "C5284", "C5285", "C5286", "C5287", "C5300", "C5303", "C5304", "C5305", "C5306", "C5307", "C5308", "C5309"] +--- +# 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 c94b2ac74fb..d7eba2d5c8c 100644 --- a/docs/error-messages/includes/error-boilerplate.md +++ b/docs/error-messages/includes/error-boilerplate.md @@ -1,11 +1,11 @@ > [!IMPORTANT] -> The Visual Studio compilers and build tools can report many kinds of errors and warnings. After an error or warning is found, the build tools may make assumptions about code intent and attempt to continue, so that more issues can be reported at the same time. If the tools make the wrong assumption, later errors or warnings may not apply to your project. When you correct issues in your project, always start with the first error or warning that's reported, and rebuild often. One fix may make many subsequent errors go away. +> The Visual Studio compilers and build tools can report many kinds of errors and warnings. After an error or warning is found, the build tools may make assumptions about code intent and attempt to continue, so that more issues can be reported at the same time. If the tools make the wrong assumption, later errors or warnings may not apply to your project. When you correct issues in your project, always start with the first error or warning that's reported, and rebuild often. One fix may resolve multiple subsequent errors. To get help on a particular diagnostic message in Visual Studio, select it in the **Output** window and press the **F1** key. Visual Studio opens the documentation page for that error, if one exists. You can also use the search tool at the top of the page to find articles about specific errors or warnings. Or, browse the list of errors and warnings by tool and type in the table of contents on this page. > [!NOTE] -> Not every Visual Studio error or warning is documented. In many cases, the diagnostic message provides all of the information that's available. If you landed on this page when you used **F1** and you think the error or warning message needs additional explanation, let us know. You can use the feedback buttons on this page to raise a documentation issue on [GitHub](https://github.com/MicrosoftDocs/cpp-docs/issues). If you think the error or warning is wrong, or you've found another problem with the toolset, report a product issue on the [Developer Community](https://aka.ms/feedback/report?space=62) site. You can also send feedback and enter bugs within the IDE. In Visual Studio, go to the menu bar and choose **Help > Send Feedback > Report a Problem**, or submit a suggestion by using **Help > Send Feedback > Send a Suggestion**. +> Not every Visual Studio error or warning is documented. In many cases, the diagnostic message provides all of the information that's available. If you landed on this page and think the error or warning message needs additional explanation, let us know by using the feedback buttons on this page. If you think the error or warning is wrong, or you've found another problem with the toolset, report a product issue on the [Developer Community](https://aka.ms/feedback/report?space=62) site. You can also send feedback and enter bugs within the IDE. In Visual Studio, go to the menu bar and choose **Help > Send Feedback > Report a Problem**, or submit a suggestion by using **Help > Send Feedback > Suggest a Feature**. Some compiler error topics were created that are not emitted by the compiler and now redirect to this page instead. -You may find additional assistance for errors and warnings in [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html) forums. Or, search for the error or warning number on the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) site. You can also search [Stack Overflow](https://stackoverflow.com/) to find solutions. +You may find additional assistance for errors and warnings in [Microsoft Q&A C++](/answers/tags/314/cpp) forums. Or, search for the error or warning number on the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) site. You can also search [Stack Overflow](https://stackoverflow.com/) to find solutions. For links to additional help and community resources, see [Visual C++ Help and Community](../../overview/visual-cpp-help-and-community.md). diff --git a/docs/error-messages/toc.yml b/docs/error-messages/toc.yml index 6cbff2a16a1..fe34e4d9634 100644 --- a/docs/error-messages/toc.yml +++ b/docs/error-messages/toc.yml @@ -86,251 +86,261 @@ items: - name: Compiler fatal errors expanded: false items: - - name: Compiler fatal errors C999 through C1999 + - name: Compiler fatal errors C1001 through C1907 href: compiler-errors-1/compiler-fatal-errors-c999-through-c1999.md - - name: fatal error C999 - href: compiler-errors-1/fatal-error-c999.md - - name: fatal error C1001 + - name: Fatal error C1001 href: compiler-errors-1/fatal-error-c1001.md - - name: fatal error C1002 + - name: Fatal error C1002 href: compiler-errors-1/fatal-error-c1002.md - - name: fatal error C1003 + - name: Fatal error C1003 href: compiler-errors-1/fatal-error-c1003.md - - name: fatal error C1004 + - name: Fatal error C1004 href: compiler-errors-1/fatal-error-c1004.md - - name: fatal error C1005 + - name: Fatal error C1005 href: compiler-errors-1/fatal-error-c1005.md - - name: fatal error C1007 + - name: Fatal error C1007 href: compiler-errors-1/fatal-error-c1007.md - - name: fatal error C1008 + - name: Fatal error C1008 href: compiler-errors-1/fatal-error-c1008.md - - name: fatal error C1009 + - name: Fatal error C1009 href: compiler-errors-1/fatal-error-c1009.md - - name: fatal error C1010 + - name: Fatal error C1010 href: compiler-errors-1/fatal-error-c1010.md - - name: fatal error C1012 + - name: Fatal error C1011 + href: compiler-errors-1/fatal-error-c1011.md + - name: Fatal error C1012 href: compiler-errors-1/fatal-error-c1012.md - - name: fatal error C1013 + - name: Fatal error C1013 href: compiler-errors-1/fatal-error-c1013.md - - name: fatal error C1014 + - name: Fatal error C1014 href: compiler-errors-1/fatal-error-c1014.md - - name: fatal error C1016 + - name: Fatal error C1015 + href: compiler-errors-1/fatal-error-c1015.md + - name: Fatal error C1016 href: compiler-errors-1/fatal-error-c1016.md - - name: fatal error C1017 + - name: Fatal error C1017 href: compiler-errors-1/fatal-error-c1017.md - - name: fatal error C1018 + - name: Fatal error C1018 href: compiler-errors-1/fatal-error-c1018.md - - name: fatal error C1019 + - name: Fatal error C1019 href: compiler-errors-1/fatal-error-c1019.md - - name: fatal error C1020 + - name: Fatal error C1020 href: compiler-errors-1/fatal-error-c1020.md - - name: fatal error C1021 + - name: Fatal error C1021 href: compiler-errors-1/fatal-error-c1021.md - - name: fatal error C1022 + - name: Fatal error C1022 href: compiler-errors-1/fatal-error-c1022.md - - name: fatal error C1023 + - name: Fatal error C1023 href: compiler-errors-1/fatal-error-c1023.md - - name: fatal error C1026 + - name: Fatal error C1025, C1115 + href: compiler-errors-1/fatal-error-c1025-c1115.md + - name: Fatal error C1026 href: compiler-errors-1/fatal-error-c1026.md - - name: fatal error C1033 + - name: Fatal error C1029 + href: compiler-errors-1/fatal-error-c1029.md + - name: Fatal error C1033 href: compiler-errors-1/fatal-error-c1033.md - - name: fatal error C1035 + - name: Fatal error C1035 href: compiler-errors-1/fatal-error-c1035.md - - name: fatal error C1037 + - name: Fatal error C1037 href: compiler-errors-1/fatal-error-c1037.md - - name: fatal error C1038 + - name: Fatal error C1038 href: compiler-errors-1/fatal-error-c1038.md - - name: fatal error C1045 + - name: Fatal error C1045 href: compiler-errors-1/fatal-error-c1045.md - - name: fatal error C1046 + - name: Fatal error C1046 href: compiler-errors-1/fatal-error-c1046.md - - name: fatal error C1047 + - name: Fatal error C1047 href: compiler-errors-1/fatal-error-c1047.md - - name: fatal error C1049 + - name: Fatal error C1049 href: compiler-errors-1/fatal-error-c1049.md - - name: fatal error C1051 + - name: Fatal error C1051 href: compiler-errors-1/fatal-error-c1051.md - - name: fatal error C1052 + - name: Fatal error C1052 href: compiler-errors-1/fatal-error-c1052.md - - name: fatal error C1053 + - name: Fatal error C1053 href: compiler-errors-1/fatal-error-c1053.md - - name: fatal error C1054 + - name: Fatal error C1054 href: compiler-errors-1/fatal-error-c1054.md - - name: fatal error C1055 + - name: Fatal error C1055 href: compiler-errors-1/fatal-error-c1055.md - - name: fatal error C1057 + - name: Fatal error C1057 href: compiler-errors-1/fatal-error-c1057.md - - name: fatal error C1060 + - name: Fatal error C1060 href: compiler-errors-1/fatal-error-c1060.md - - name: fatal error C1061 + - name: Fatal error C1061 href: compiler-errors-1/fatal-error-c1061.md - - name: fatal error C1064 + - name: Fatal error C1064 href: compiler-errors-1/fatal-error-c1064.md - - name: fatal error C1065 + - name: Fatal error C1065 href: compiler-errors-1/fatal-error-c1065.md - - name: fatal error C1067 + - name: Fatal error C1067 href: compiler-errors-1/fatal-error-c1067.md - - name: fatal error C1068 + - name: Fatal error C1068 href: compiler-errors-1/fatal-error-c1068.md - - name: fatal error C1070 + - name: Fatal error C1070 href: compiler-errors-1/fatal-error-c1070.md - - name: fatal error C1071 + - name: Fatal error C1071 href: compiler-errors-1/fatal-error-c1071.md - - name: fatal error C1073 + - name: Fatal error C1073 href: compiler-errors-1/fatal-error-c1073.md - - name: fatal error C1074 + - name: Fatal error C1074 href: compiler-errors-1/fatal-error-c1074.md - - name: fatal error C1075 + - name: Fatal error C1075 href: compiler-errors-1/fatal-error-c1075.md - - name: fatal error C1076 + - name: Fatal error C1076 href: compiler-errors-1/fatal-error-c1076.md - - name: fatal error C1077 + - name: Fatal error C1077 href: compiler-errors-1/fatal-error-c1077.md - - name: fatal error C1079 + - name: Fatal error C1079 href: compiler-errors-1/fatal-error-c1079.md - - name: fatal error C1080 + - name: Fatal error C1080 href: compiler-errors-1/fatal-error-c1080.md - - name: fatal error C1081 + - name: Fatal error C1081 href: compiler-errors-1/fatal-error-c1081.md - - name: fatal error C1082 + - name: Fatal error C1082 href: compiler-errors-1/fatal-error-c1082.md - - name: fatal error C1083 + - name: Fatal error C1083 href: compiler-errors-1/fatal-error-c1083.md - - name: fatal error C1084 + - name: Fatal error C1084 href: compiler-errors-1/fatal-error-c1084.md - - name: fatal error C1085 + - name: Fatal error C1085 href: compiler-errors-1/fatal-error-c1085.md - - name: fatal error C1086 + - name: Fatal error C1086 href: compiler-errors-1/fatal-error-c1086.md - - name: fatal error C1087 + - name: Fatal error C1087 href: compiler-errors-1/fatal-error-c1087.md - - name: fatal error C1088 + - name: Fatal error C1088 href: compiler-errors-1/fatal-error-c1088.md - - name: fatal error C1089 + - name: Fatal error C1089 href: compiler-errors-1/fatal-error-c1089.md - - name: fatal error C1090 + - name: Fatal error C1090 href: compiler-errors-1/fatal-error-c1090.md - - name: fatal error C1091 + - name: Fatal error C1091 href: compiler-errors-1/fatal-error-c1091.md - - name: fatal error C1092 + - name: Fatal error C1092 href: compiler-errors-1/fatal-error-c1092.md - - name: fatal error C1093 + - name: Fatal error C1093 href: compiler-errors-1/fatal-error-c1093.md - - name: fatal error C1094 + - name: Fatal error C1094 href: compiler-errors-1/fatal-error-c1094.md - - name: fatal error C1098 + - name: Fatal error C1098 href: compiler-errors-1/fatal-error-c1098.md - - name: fatal error C1099 + - name: Fatal error C1099 href: compiler-errors-1/fatal-error-c1099.md - - name: fatal error C1100 + - name: Fatal error C1100 href: compiler-errors-1/fatal-error-c1100.md - - name: fatal error C1103 + - name: Fatal error C1103 href: compiler-errors-1/fatal-error-c1103.md - - name: fatal error C1104 + - name: Fatal error C1104 href: compiler-errors-1/fatal-error-c1104.md - - name: fatal error C1107 + - name: Fatal error C1107 href: compiler-errors-1/fatal-error-c1107.md - - name: fatal error C1108 + - name: Fatal error C1108 href: compiler-errors-1/fatal-error-c1108.md - - name: fatal error C1109 + - name: Fatal error C1109 href: compiler-errors-1/fatal-error-c1109.md - - name: fatal error C1113 + - name: Fatal error C1113 href: compiler-errors-1/fatal-error-c1113.md - - name: fatal error C1120 + - name: Fatal error C1116 + href: compiler-errors-1/fatal-error-c1116.md + - name: Fatal error C1117 + href: compiler-errors-1/fatal-error-c1117.md + - name: Fatal error C1120 href: compiler-errors-1/fatal-error-c1120.md - - name: fatal error C1121 + - name: Fatal error C1121 href: compiler-errors-1/fatal-error-c1121.md - - name: fatal error C1126 + - name: Fatal error C1126 href: compiler-errors-1/fatal-error-c1126.md - - name: fatal error C1128 + - name: Fatal error C1128 href: compiler-errors-1/fatal-error-c1128.md - - name: fatal error C1189 + - name: Fatal error C1189 href: compiler-errors-1/fatal-error-c1189.md - - name: fatal error C1190 + - name: Fatal error C1190 href: compiler-errors-1/fatal-error-c1190.md - - name: fatal error C1191 + - name: Fatal error C1191 href: compiler-errors-1/fatal-error-c1191.md - - name: fatal error C1192 + - name: Fatal error C1192 href: compiler-errors-1/fatal-error-c1192.md - - name: fatal error C1196 + - name: Fatal error C1196 href: compiler-errors-1/fatal-error-c1196.md - - name: fatal error C1197 + - name: Fatal error C1197 href: compiler-errors-1/fatal-error-c1197.md - - name: fatal error C1201 + - name: Fatal error C1201 href: compiler-errors-1/fatal-error-c1201.md - - name: fatal error C1202 + - name: Fatal error C1202 href: compiler-errors-1/fatal-error-c1202.md - - name: fatal error C1205 + - name: Fatal error C1205 href: compiler-errors-1/fatal-error-c1205.md - - name: fatal error C1206 + - name: Fatal error C1206 href: compiler-errors-1/fatal-error-c1206.md - - name: fatal error C1207 + - name: Fatal error C1207 href: compiler-errors-1/fatal-error-c1207.md - - name: fatal error C1208 + - name: Fatal error C1208 href: compiler-errors-1/fatal-error-c1208.md - - name: fatal error C1209 + - name: Fatal error C1209 href: compiler-errors-1/fatal-error-c1209.md - - name: fatal error C1210 + - name: Fatal error C1210 href: compiler-errors-1/fatal-error-c1210.md - - name: fatal error C1211 + - name: Fatal error C1211 href: compiler-errors-1/fatal-error-c1211.md - - name: fatal error C1305 + - name: Fatal error C1305 href: compiler-errors-1/fatal-error-c1305.md - - name: fatal error C1307 + - name: Fatal error C1307 href: compiler-errors-1/fatal-error-c1307.md - - name: fatal error C1308 + - name: Fatal error C1308 href: compiler-errors-1/fatal-error-c1308.md - - name: fatal error C1309 + - name: Fatal error C1309 href: compiler-errors-1/fatal-error-c1309.md - - name: fatal error C1310 + - name: Fatal error C1310 href: compiler-errors-1/fatal-error-c1310.md - - name: fatal error C1311 + - name: Fatal error C1311 href: compiler-errors-1/fatal-error-c1311.md - - name: fatal error C1312 + - name: Fatal error C1312 href: compiler-errors-1/fatal-error-c1312.md - - name: fatal error C1313 + - name: Fatal error C1313 href: compiler-errors-1/fatal-error-c1313.md - - name: fatal error C1350 + - name: Fatal error C1350 href: compiler-errors-1/fatal-error-c1350.md - - name: fatal error C1351 + - name: Fatal error C1351 href: compiler-errors-1/fatal-error-c1351.md - - name: fatal error C1352 + - name: Fatal error C1352 href: compiler-errors-1/fatal-error-c1352.md - - name: fatal error C1353 + - name: Fatal error C1353 href: compiler-errors-1/fatal-error-c1353.md - - name: fatal error C1382 + - name: Fatal error C1382 href: compiler-errors-1/fatal-error-c1382.md - - name: fatal error C1383 + - name: Fatal error C1383 href: compiler-errors-1/fatal-error-c1383.md - - name: fatal error C1506 + - name: Fatal error C1506 href: compiler-errors-1/fatal-error-c1506.md - - name: fatal error C1508 + - name: Fatal error C1508 href: compiler-errors-1/fatal-error-c1508.md - - name: fatal error C1509 + - name: Fatal error C1509 href: compiler-errors-1/fatal-error-c1509.md - - name: fatal error C1510 + - name: Fatal error C1510 href: compiler-errors-1/fatal-error-c1510.md - - name: fatal error C1601 + - name: Fatal error C1601 href: compiler-errors-1/fatal-error-c1601.md - - name: fatal error C1602 + - name: Fatal error C1602 href: compiler-errors-1/fatal-error-c1602.md - - name: fatal error C1603 + - name: Fatal error C1603 href: compiler-errors-1/fatal-error-c1603.md - - name: fatal error C1852 + - name: Fatal error C1852 href: compiler-errors-1/fatal-error-c1852.md - - name: fatal error C1853 + - name: Fatal error C1853 href: compiler-errors-1/fatal-error-c1853.md - - name: fatal error C1854 + - name: Fatal error C1854 href: compiler-errors-1/fatal-error-c1854.md - - name: fatal error C1900 + - name: Fatal error C1900 href: compiler-errors-1/fatal-error-c1900.md - - name: fatal error C1902 + - name: Fatal error C1902 href: compiler-errors-1/fatal-error-c1902.md - - name: fatal error C1903 + - name: Fatal error C1903 href: compiler-errors-1/fatal-error-c1903.md - - name: fatal error C1904 + - name: Fatal error C1904 href: compiler-errors-1/fatal-error-c1904.md - - name: fatal error C1905 + - name: Fatal error C1905 href: compiler-errors-1/fatal-error-c1905.md - name: Compiler errors expanded: false @@ -372,6 +382,8 @@ items: href: compiler-errors-1/compiler-error-c2014.md - name: Compiler error C2015 href: compiler-errors-1/compiler-error-c2015.md + - name: Compiler error C2016 + href: compiler-errors-1/compiler-error-c2016.md - name: Compiler error C2017 href: compiler-errors-1/compiler-error-c2017.md - name: Compiler error C2018 @@ -384,6 +396,12 @@ items: href: compiler-errors-1/compiler-error-c2021.md - name: Compiler error C2022 href: compiler-errors-1/compiler-error-c2022.md + - name: Compiler error C2023 + href: compiler-errors-1/compiler-error-c2023.md + - name: Compiler error C2024 + href: compiler-errors-1/compiler-error-c2024.md + - name: Compiler error C2025 + href: compiler-errors-1/compiler-error-c2025.md - name: Compiler error C2026 href: compiler-errors-1/compiler-error-c2026.md - name: Compiler error C2027 @@ -392,14 +410,22 @@ items: href: compiler-errors-1/compiler-error-c2028.md - name: Compiler error C2030 href: compiler-errors-1/compiler-error-c2030.md + - name: Compiler error C2031 + href: compiler-errors-1/compiler-error-c2031.md - name: Compiler error C2032 href: compiler-errors-1/compiler-error-c2032.md - name: Compiler error C2033 href: compiler-errors-1/compiler-error-c2033.md - name: Compiler error C2034 href: compiler-errors-1/compiler-error-c2034.md + - name: Compiler error C2035 + href: compiler-errors-1/compiler-error-c2035.md - name: Compiler error C2036 href: compiler-errors-1/compiler-error-c2036.md + - name: Compiler error C2037 + href: compiler-errors-1/compiler-error-c2037.md + - name: Compiler error C2038 + href: compiler-errors-1/compiler-error-c2038.md - name: Compiler error C2039 href: compiler-errors-1/compiler-error-c2039.md - name: Compiler error C2040 @@ -420,6 +446,8 @@ items: href: compiler-errors-1/compiler-error-c2047.md - name: Compiler error C2048 href: compiler-errors-1/compiler-error-c2048.md + - name: Compiler error C2049 + href: compiler-errors-1/compiler-error-c2049.md - name: Compiler error C2050 href: compiler-errors-1/compiler-error-c2050.md - name: Compiler error C2051 @@ -456,6 +484,8 @@ items: href: compiler-errors-1/compiler-error-c2066.md - name: Compiler error C2067 href: compiler-errors-1/compiler-error-c2067.md + - name: Compiler error C2068 + href: compiler-errors-1/compiler-error-c2068.md - name: Compiler error C2069 href: compiler-errors-1/compiler-error-c2069.md - name: Compiler error C2070 @@ -470,12 +500,16 @@ items: href: compiler-errors-1/compiler-error-c2074.md - name: Compiler error C2075 href: compiler-errors-1/compiler-error-c2075.md + - name: Compiler error C2076 + href: compiler-errors-1/compiler-error-c2076.md - name: Compiler error C2077 href: compiler-errors-1/compiler-error-c2077.md - name: Compiler error C2078 href: compiler-errors-1/compiler-error-c2078.md - name: Compiler error C2079 href: compiler-errors-1/compiler-error-c2079.md + - name: Compiler error C2080 + href: compiler-errors-1/compiler-error-c2080.md - name: Compiler error C2081 href: compiler-errors-1/compiler-error-c2081.md - name: Compiler error C2082 @@ -506,8 +540,12 @@ items: href: compiler-errors-1/compiler-error-c2094.md - name: Compiler error C2095 href: compiler-errors-1/compiler-error-c2095.md + - name: Compiler error C2096 + href: compiler-errors-1/compiler-error-c2096.md - name: Compiler error C2097 href: compiler-errors-1/compiler-error-c2097.md + - name: Compiler error C2098 + href: compiler-errors-1/compiler-error-c2098.md - name: Compiler error C2099 href: compiler-errors-1/compiler-error-c2099.md - name: Compiler errors C2100 through C2199 @@ -852,10 +890,10 @@ items: href: compiler-errors-1/compiler-error-c2298.md - name: Compiler error C2299 href: compiler-errors-1/compiler-error-c2299.md - - name: Compiler errors C2300 Through C2399 + - name: Compiler errors C2300 through C2399 expanded: false items: - - name: Compiler errors C2300 Through C2399 + - name: Compiler errors C2300 through C2399 href: compiler-errors-1/compiler-errors-c2300-through-c2399.md - name: Compiler error C2300 href: compiler-errors-1/compiler-error-c2300.md @@ -891,6 +929,8 @@ items: href: compiler-errors-1/compiler-error-c2320.md - name: Compiler error C2322 href: compiler-errors-1/compiler-error-c2322.md + - name: Compiler error C2323 + href: compiler-errors-1/compiler-error-c2323.md - name: Compiler error C2324 href: compiler-errors-1/compiler-error-c2324.md - name: Compiler error C2325 @@ -1005,10 +1045,10 @@ items: href: compiler-errors-1/compiler-error-c2396.md - name: Compiler error C2397 href: compiler-errors-1/compiler-error-c2397.md - - name: Compiler errors C2400 Through C2499 + - name: Compiler errors C2400 through C2499 expanded: false items: - - name: Compiler errors C2400 Through C2499 + - name: Compiler errors C2400 through C2499 href: compiler-errors-1/compiler-errors-c2400-through-c2499.md - name: Compiler error C2400 href: compiler-errors-1/compiler-error-c2400.md @@ -1180,10 +1220,10 @@ items: href: compiler-errors-1/compiler-error-c2498.md - name: Compiler error C2499 href: compiler-errors-1/compiler-error-c2499.md - - name: Compiler errors C2500 Through C2599 + - name: Compiler errors C2500 through C2599 expanded: false items: - - name: Compiler errors C2500 Through C2599 + - name: Compiler errors C2500 through C2599 href: compiler-errors-2/compiler-errors-c2500-through-c2599.md - name: Compiler error C2500 href: compiler-errors-2/compiler-error-c2500.md @@ -1335,10 +1375,10 @@ items: href: compiler-errors-2/compiler-error-c2598.md - name: Compiler error C2599 href: compiler-errors-2/compiler-error-c2599.md - - name: Compiler errors C2600 Through C2699 + - name: Compiler errors C2600 through C2699 expanded: false items: - - name: Compiler errors C2600 Through C2699 + - name: Compiler errors C2600 through C2699 href: compiler-errors-2/compiler-errors-c2600-through-c2699.md - name: Compiler error C2600 href: compiler-errors-2/compiler-error-c2600.md @@ -1490,10 +1530,10 @@ items: href: compiler-errors-2/compiler-error-c2696.md - name: Compiler error C2698 href: compiler-errors-2/compiler-error-c2698.md - - name: Compiler errors C2700 Through C2799 + - name: Compiler errors C2700 through C2799 expanded: false items: - - name: Compiler errors C2700 Through C2799 + - name: Compiler errors C2700 through C2799 href: compiler-errors-2/compiler-errors-c2700-through-c2799.md - name: Compiler error C2700 href: compiler-errors-2/compiler-error-c2700.md @@ -1659,10 +1699,10 @@ items: href: compiler-errors-2/compiler-error-c2797.md - name: Compiler error C2798 href: compiler-errors-2/compiler-error-c2798.md - - name: Compiler errors C2800 Through C2899 + - name: Compiler errors C2800 through C2899 expanded: false items: - - name: Compiler errors C2800 Through C2899 + - name: Compiler errors C2800 through C2899 href: compiler-errors-2/compiler-errors-c2800-through-c2899.md - name: Compiler error C2800 href: compiler-errors-2/compiler-error-c2800.md @@ -1826,10 +1866,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 @@ -1965,10 +2005,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 @@ -2134,10 +2174,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 @@ -2275,10 +2315,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 @@ -2450,10 +2490,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 @@ -2559,10 +2599,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 @@ -3129,27 +3169,31 @@ 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 error C7742 + href: compiler-errors-2/compiler-error-c7742.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 @@ -3209,7 +3253,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 @@ -3219,9 +3263,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 @@ -3259,7 +3303,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 @@ -3275,7 +3319,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 @@ -3283,7 +3327,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 @@ -3317,11 +3361,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 @@ -3361,7 +3405,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 @@ -3395,20 +3439,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 @@ -3492,19 +3536,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 @@ -3522,7 +3566,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 @@ -3536,11 +3580,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 @@ -3550,7 +3594,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 @@ -3566,7 +3610,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 @@ -3590,17 +3634,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 @@ -3610,7 +3654,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 @@ -3622,21 +3666,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 @@ -3658,7 +3702,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 @@ -3666,11 +3710,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 @@ -3680,14 +3724,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 @@ -3711,7 +3755,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 @@ -3719,19 +3763,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 @@ -3739,13 +3783,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 @@ -3755,21 +3799,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 @@ -3793,13 +3837,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 @@ -3827,7 +3871,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 @@ -3841,15 +3885,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 @@ -3861,11 +3905,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 @@ -3893,14 +3937,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 @@ -4116,6 +4160,8 @@ items: href: compiler-warnings/compiler-warning-level-4-c4764.md - name: Compiler warning (level 4) C4768 href: compiler-warnings/c4768.md + - name: Compiler warning (level 4) C4770 + href: compiler-warnings/c4770.md - name: Compiler warning (level 1) C4772 href: compiler-warnings/compiler-warning-level-1-c4772.md - name: Compiler warning (Level 1) C4788 @@ -4130,10 +4176,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 @@ -4287,8 +4333,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 @@ -4307,8 +4356,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 @@ -4319,6 +4375,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 @@ -4375,7 +4439,7 @@ items: href: tool-errors/cvtres-fatal-error-cvt1105.md - name: CVTRES warning CVT4001 href: tool-errors/cvtres-warning-cvt4001.md -- name: Expression evaluator errors +- name: Expression evaluator errors expanded: false items: - name: Expression evaluator errors (CXXxxxx) @@ -4779,10 +4843,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/bscmake-error-bk1503.md b/docs/error-messages/tool-errors/bscmake-error-bk1503.md index 64c12bd2413..2a3e2f43d4e 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1503.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1503.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1503" title: "BSCMAKE Error BK1503" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1503" +ms.date: 11/04/2016 f1_keywords: ["BK1503"] helpviewer_keywords: ["BK1503"] -ms.assetid: e6582344-b91e-486f-baf3-4f9028d83c3b --- # BSCMAKE Error BK1503 -cannot write to file 'filename' [: reason] +> cannot write to file 'filename' [: reason] + +## Remarks BSCMAKE combines the .sbr files generated during compilation into one browser database. If the resulting browser database exceeds 64 MB, or if the number of input (.sbr) files exceeds 4092, this error will be emitted. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1504.md b/docs/error-messages/tool-errors/bscmake-error-bk1504.md index ec37c7671e0..80c657373fe 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1504.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1504.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1504" title: "BSCMAKE Error BK1504" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1504" +ms.date: 11/04/2016 f1_keywords: ["BK1504"] helpviewer_keywords: ["BK1504"] -ms.assetid: e6d1a171-1472-4b7e-a04b-1a68a561675f --- # BSCMAKE Error BK1504 -cannot position in file 'filename' [: reason] +> cannot position in file 'filename' [: reason] + +## Remarks BSCMAKE could not move to a location in the file. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1505.md b/docs/error-messages/tool-errors/bscmake-error-bk1505.md index 5d63471bec0..2b06a6fcb9b 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1505.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1505.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1505" title: "BSCMAKE Error BK1505" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1505" +ms.date: 11/04/2016 f1_keywords: ["BK1505"] helpviewer_keywords: ["BK1505"] -ms.assetid: a25765f8-e950-4ca8-9f16-419d779e2744 --- # BSCMAKE Error BK1505 -cannot read from file 'filename' [: reason] +> cannot read from file 'filename' [: reason] + +## Remarks BSCMAKE cannot read from the file. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1506.md b/docs/error-messages/tool-errors/bscmake-error-bk1506.md index 158a93e679f..b95c897bc0a 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1506.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1506.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1506" title: "BSCMAKE Error BK1506" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1506" +ms.date: 11/04/2016 f1_keywords: ["BK1506"] helpviewer_keywords: ["BK1506"] -ms.assetid: f51f8cea-f8fc-4323-bcf2-b7bd119792ee --- # BSCMAKE Error BK1506 -cannot open file 'filename' [: reason] +> cannot open file 'filename' [: reason] + +## Remarks BSCMAKE cannot open the file. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1507.md b/docs/error-messages/tool-errors/bscmake-error-bk1507.md index 6ad648f99d8..520aed46343 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1507.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1507.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1507" title: "BSCMAKE Error BK1507" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1507" +ms.date: 11/04/2016 f1_keywords: ["BK1507"] helpviewer_keywords: ["BK1507"] -ms.assetid: 3c5220d7-ccb3-45b4-9da0-cb06147311f6 --- # BSCMAKE Error BK1507 -cannot open temporary file 'filename' [: reason] +> cannot open temporary file 'filename' [: reason] + +## Remarks BSCMAKE cannot open a temporary file. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1508.md b/docs/error-messages/tool-errors/bscmake-error-bk1508.md index 1e278052eca..123e73b57ce 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1508.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1508.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1508" title: "BSCMAKE Error BK1508" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1508" +ms.date: 11/04/2016 f1_keywords: ["BK1508"] helpviewer_keywords: ["BK1508"] -ms.assetid: 03ea22b8-c7b4-4e73-8553-35b41112e066 --- # BSCMAKE Error BK1508 -cannot delete temporary file 'filename' [: reason] +> cannot delete temporary file 'filename' [: reason] + +## Remarks BSCMAKE cannot delete one of its temporary files. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1509.md b/docs/error-messages/tool-errors/bscmake-error-bk1509.md index c998612a2ef..b25c7cf5d4a 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1509.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1509.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1509" title: "BSCMAKE Error BK1509" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1509" +ms.date: 11/04/2016 f1_keywords: ["BK1509"] helpviewer_keywords: ["BK1509"] -ms.assetid: 53df7037-1913-4b63-b425-c0bf44081792 --- # BSCMAKE Error BK1509 -out of heap space +> out of heap space + +## Remarks BSCMAKE ran out of memory, including virtual memory. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1510.md b/docs/error-messages/tool-errors/bscmake-error-bk1510.md index c4ec735b4ff..59159959d58 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1510.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1510.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: BSCMAKE Error BK1510" title: "BSCMAKE Error BK1510" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1510" +ms.date: 11/04/2016 f1_keywords: ["BK1510"] helpviewer_keywords: ["BK1510"] -ms.assetid: e67290c0-58cf-44da-ad01-f8dffc34ea2d --- # BSCMAKE Error BK1510 -corrupt .SBR file filename +> corrupt .SBR file filename + +## Remarks The given .sbr file does not have the expected format. Recompile to create a new .sbr. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1512.md b/docs/error-messages/tool-errors/bscmake-error-bk1512.md index 0b701544058..912758c02a0 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1512.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1512.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1512" title: "BSCMAKE Error BK1512" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1512" +ms.date: 11/04/2016 f1_keywords: ["BK1512"] helpviewer_keywords: ["BK1512"] -ms.assetid: 0a626ff3-63db-4797-abe4-31545ce2c2c1 --- # BSCMAKE Error BK1512 -filename: capacity exceeded +> filename: capacity exceeded + +## Remarks BSCMAKE cannot build a browse information file because the number of definitions, references, modules, or other information exceeds the limit. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1513.md b/docs/error-messages/tool-errors/bscmake-error-bk1513.md index 0ebe59771f8..c08f45b6cce 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1513.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1513.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1513" title: "BSCMAKE Error BK1513" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1513" +ms.date: 11/04/2016 f1_keywords: ["BK1513"] helpviewer_keywords: ["BK1513"] -ms.assetid: 9ba87c09-8d82-4c80-b0cf-a8de63dcf9da --- # BSCMAKE Error BK1513 -nonincremental update requires all .SBR files +> nonincremental update requires all .SBR files + +## Remarks BSCMAKE cannot build a new browse information (.bsc) file because one or more .sbr files are truncated. To find the names of the truncated .sbr files, read the [BK4502](../../error-messages/tool-errors/bscmake-warning-bk4502.md) warnings that accompany this error. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1514.md b/docs/error-messages/tool-errors/bscmake-error-bk1514.md index ab008394b13..4ee5c208140 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1514.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1514.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Error BK1514" title: "BSCMAKE Error BK1514" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1514" +ms.date: 11/04/2016 f1_keywords: ["BK1514"] helpviewer_keywords: ["BK1514"] -ms.assetid: 7c7e2504-a490-44ab-bb1f-47385ee2f4b0 --- # BSCMAKE Error BK1514 -all .SBR files truncated, none found in filename +> all .SBR files truncated, none found in filename + +## Remarks None of the .sbr files specified for an update were part of the original browse information (.bsc) file. To find the names of the .sbr files that caused this error, read the [BK4502](../../error-messages/tool-errors/bscmake-warning-bk4502.md) warnings that precede it. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1515.md b/docs/error-messages/tool-errors/bscmake-error-bk1515.md index 23050c88db7..d0a082d2e7a 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1515.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1515.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: BSCMAKE Error BK1515" title: "BSCMAKE Error BK1515" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1515" +ms.date: 11/04/2016 f1_keywords: ["BK1515"] helpviewer_keywords: ["BK1515"] -ms.assetid: 4cf2aedb-10c4-4ae8-abe6-c681fd4d617d --- # BSCMAKE Error BK1515 -bscfile: incompatible version: cannot incrementally update +> bscfile: incompatible version: cannot incrementally update + +## Remarks The .bsc file was created with another version of BSCMAKE. Recreate the .bsc file. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1516.md b/docs/error-messages/tool-errors/bscmake-error-bk1516.md index a21e9704718..2b9fce5d192 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1516.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1516.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: BSCMAKE Error BK1516" title: "BSCMAKE Error BK1516" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1516" +ms.date: 11/04/2016 f1_keywords: ["BK1516"] helpviewer_keywords: ["BK1516"] -ms.assetid: 7f4a8391-f857-4ee8-8e26-34868ca84e29 --- # BSCMAKE Error BK1516 -bscfile corrupt; cannot incrementally update +> bscfile corrupt; cannot incrementally update + +## Remarks The .bsc file was corrupted, possibly due to a system failure during the build. Delete the .bsc file, rebuild all .sbr files, then rebuild the .bsc file. diff --git a/docs/error-messages/tool-errors/bscmake-error-bk1517.md b/docs/error-messages/tool-errors/bscmake-error-bk1517.md index a8d301b2354..e4a4b9fa70f 100644 --- a/docs/error-messages/tool-errors/bscmake-error-bk1517.md +++ b/docs/error-messages/tool-errors/bscmake-error-bk1517.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: BSCMAKE Error BK1517" title: "BSCMAKE Error BK1517" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Error BK1517" +ms.date: 11/04/2016 f1_keywords: ["BK1517"] helpviewer_keywords: ["BK1517"] -ms.assetid: 24391f42-0a3e-40a9-9991-c8b9a6a7b1c7 --- # BSCMAKE Error BK1517 -source file for sbrfile compiled with both /Yc and /Yu +> source file for sbrfile compiled with both /Yc and /Yu + +## Remarks The .sbr file refers to itself. It was probably recompiled with /Yu after compiling with /Yc. Reset the compiler option for the source file to /Yc, then select **Rebuild** to generate new .sbr files. Do not recompile the source file with /Yu. diff --git a/docs/error-messages/tool-errors/bscmake-errors-bk1500-through-bk4505.md b/docs/error-messages/tool-errors/bscmake-errors-bk1500-through-bk4505.md index cf53a0fd929..59030414a39 100644 --- a/docs/error-messages/tool-errors/bscmake-errors-bk1500-through-bk4505.md +++ b/docs/error-messages/tool-errors/bscmake-errors-bk1500-through-bk4505.md @@ -1,39 +1,42 @@ --- -description: "Learn more about: BSCMAKE errors and warnings (BKxxxx)" title: "BSCMAKE errors and warnings" -ms.date: "04/16/2019" -ms.assetid: 3767baa6-e639-472e-99fd-7543fd945cd3 +description: "Learn more about: BSCMAKE errors and warnings (BKxxxx)" +ms.date: 04/16/2019 --- # BSCMAKE errors and warnings (BKxxxx) This section is a reference to the errors and warnings generated by the BSCMAKE build tool. BSCMAKE errors and warnings have the form BK*xxxx*, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Error messages -[BSCMAKE error BK1503](bscmake-error-bk1503.md) \ -[BSCMAKE error BK1504](bscmake-error-bk1504.md) \ -[BSCMAKE error BK1505](bscmake-error-bk1505.md) \ -[BSCMAKE error BK1506](bscmake-error-bk1506.md) \ -[BSCMAKE error BK1507](bscmake-error-bk1507.md) \ -[BSCMAKE error BK1508](bscmake-error-bk1508.md) \ -[BSCMAKE error BK1509](bscmake-error-bk1509.md) \ -[BSCMAKE error BK1510](bscmake-error-bk1510.md) \ -[BSCMAKE error BK1512](bscmake-error-bk1512.md) \ -[BSCMAKE error BK1513](bscmake-error-bk1513.md) \ -[BSCMAKE error BK1514](bscmake-error-bk1514.md) \ -[BSCMAKE error BK1515](bscmake-error-bk1515.md) \ -[BSCMAKE error BK1516](bscmake-error-bk1516.md) \ -[BSCMAKE error BK1517](bscmake-error-bk1517.md) +| Error | Message | +|--|--| +| [BSCMAKE error BK1503](bscmake-error-bk1503.md) | cannot write to file 'filename' [: reason] | +| [BSCMAKE error BK1504](bscmake-error-bk1504.md) | cannot position in file 'filename' [: reason] | +| [BSCMAKE error BK1505](bscmake-error-bk1505.md) | cannot read from file 'filename' [: reason] | +| [BSCMAKE error BK1506](bscmake-error-bk1506.md) | cannot open file 'filename' [: reason] | +| [BSCMAKE error BK1507](bscmake-error-bk1507.md) | cannot open temporary file 'filename' [: reason] | +| [BSCMAKE error BK1508](bscmake-error-bk1508.md) | cannot delete temporary file 'filename' [: reason] | +| [BSCMAKE error BK1509](bscmake-error-bk1509.md) | out of heap space | +| [BSCMAKE error BK1510](bscmake-error-bk1510.md) | corrupt .SBR file filename | +| [BSCMAKE error BK1512](bscmake-error-bk1512.md) | filename: capacity exceeded | +| [BSCMAKE error BK1513](bscmake-error-bk1513.md) | nonincremental update requires all .SBR files | +| [BSCMAKE error BK1514](bscmake-error-bk1514.md) | all .SBR files truncated, none found in filename | +| [BSCMAKE error BK1515](bscmake-error-bk1515.md) | bscfile: incompatible version: cannot incrementally update | +| [BSCMAKE error BK1516](bscmake-error-bk1516.md) | bscfile corrupt; cannot incrementally update | +| [BSCMAKE error BK1517](bscmake-error-bk1517.md) | source file for sbrfile compiled with both /Yc and /Yu | ## Warning messages -[BSCMAKE warning BK4502](bscmake-warning-bk4502.md) \ -[BSCMAKE warning BK4503](bscmake-warning-bk4503.md) \ -[BSCMAKE warning BK4504](bscmake-warning-bk4504.md) +| Warning | Message | +|--|--| +| [BSCMAKE warning BK4502](bscmake-warning-bk4502.md) | truncated .SBR file 'filename' not in filename | +| [BSCMAKE warning BK4503](bscmake-warning-bk4503.md) | minor error in .SBR file filename ignored | +| [BSCMAKE warning BK4504](bscmake-warning-bk4504.md) | file contains too many references; ignoring further references from this source | ## 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)\ [BSCMake reference](../../build/reference/bscmake-reference.md) diff --git a/docs/error-messages/tool-errors/bscmake-warning-bk4502.md b/docs/error-messages/tool-errors/bscmake-warning-bk4502.md index 3833aaf85e3..611b37bdcf7 100644 --- a/docs/error-messages/tool-errors/bscmake-warning-bk4502.md +++ b/docs/error-messages/tool-errors/bscmake-warning-bk4502.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Warning BK4502" title: "BSCMAKE Warning BK4502" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Warning BK4502" +ms.date: 11/04/2016 f1_keywords: ["BK4502"] helpviewer_keywords: ["BK4502"] -ms.assetid: ee412ec8-df03-4cdb-91ee-5d609ded8691 --- # BSCMAKE Warning BK4502 -truncated .SBR file 'filename' not in filename +> truncated .SBR file 'filename' not in filename + +## Remarks A zero-length .sbr file that was not originally part of the .bsc file was specified during an update. diff --git a/docs/error-messages/tool-errors/bscmake-warning-bk4503.md b/docs/error-messages/tool-errors/bscmake-warning-bk4503.md index cf38c46292b..3baa637cf37 100644 --- a/docs/error-messages/tool-errors/bscmake-warning-bk4503.md +++ b/docs/error-messages/tool-errors/bscmake-warning-bk4503.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: BSCMAKE Warning BK4503" title: "BSCMAKE Warning BK4503" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Warning BK4503" +ms.date: 11/04/2016 f1_keywords: ["BK4503"] helpviewer_keywords: ["BK4503"] -ms.assetid: 68abcf23-6987-4bc5-9745-8b65d2578bbc --- # BSCMAKE Warning BK4503 -minor error in .SBR file filename ignored +> minor error in .SBR file filename ignored + +## Remarks The .sbr file contained an error that did not halt the build, but the resulting .bsc file may be incorrect. To fix this issue, recompile to create a new .sbr. diff --git a/docs/error-messages/tool-errors/bscmake-warning-bk4504.md b/docs/error-messages/tool-errors/bscmake-warning-bk4504.md index 7bb4fbdd2d2..de69a7e2c05 100644 --- a/docs/error-messages/tool-errors/bscmake-warning-bk4504.md +++ b/docs/error-messages/tool-errors/bscmake-warning-bk4504.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: BSCMAKE Warning BK4504" title: "BSCMAKE Warning BK4504" -ms.date: "11/04/2016" +description: "Learn more about: BSCMAKE Warning BK4504" +ms.date: 11/04/2016 f1_keywords: ["BK4504"] helpviewer_keywords: ["BK4504"] -ms.assetid: b56ee2d4-ad44-40f4-98c0-75934ea44a6c --- # BSCMAKE Warning BK4504 -file contains too many references; ignoring further references from this source +> file contains too many references; ignoring further references from this source + +## Remarks The .cpp file contains more than 64,000 symbol references. When BSCMAKE has encountered 64,000 references in a file, it ignores all further references. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6002.md b/docs/error-messages/tool-errors/c-runtime-error-r6002.md index c6ecb60c462..99e8028297a 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6002.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6002.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6002" title: "C Runtime Error R6002" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6002" +ms.date: 11/04/2016 f1_keywords: ["R6002"] helpviewer_keywords: ["R6002"] -ms.assetid: 8fbbe65a-9c43-459e-8342-e1f6d1cef7d0 --- # C Runtime Error R6002 -floating-point support not loaded +> floating-point support not loaded + +## Remarks The necessary floating-point library was not linked. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6008.md b/docs/error-messages/tool-errors/c-runtime-error-r6008.md index 16ca16630ab..d2cd9fc478a 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6008.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6008.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6008" title: "C Runtime Error R6008" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6008" +ms.date: 11/04/2016 f1_keywords: ["R6008"] helpviewer_keywords: ["R6008"] -ms.assetid: f0f304fc-709a-4843-bc7e-bad1ae0d1649 --- # C Runtime Error R6008 -not enough space for arguments +> not enough space for arguments + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. There are several possible reasons for this error, but often it's caused by an extremely low memory condition, too much memory taken by environment variables, or a bug in the program. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6009.md b/docs/error-messages/tool-errors/c-runtime-error-r6009.md index 9b67d996f5f..e064cc34025 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6009.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6009.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6009" title: "C Runtime Error R6009" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6009" +ms.date: 11/04/2016 f1_keywords: ["R6009"] helpviewer_keywords: ["R6009"] -ms.assetid: edfb1f8b-3807-48f4-a994-318923b747ae --- # C Runtime Error R6009 -not enough space for environment +> not enough space for environment + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. There are several possible reasons for this error, but often it's caused by an extremely low memory condition, too much memory taken by environment variables, or a bug in the program. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6016.md b/docs/error-messages/tool-errors/c-runtime-error-r6016.md index 245c9bae9df..2398a1e6028 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6016.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6016.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6016" title: "C Runtime Error R6016" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6016" +ms.date: 11/04/2016 f1_keywords: ["R6016"] helpviewer_keywords: ["R6016"] -ms.assetid: 7bd3f274-d9c4-4bc4-8252-80bf168c4c3a --- # C Runtime Error R6016 -not enough space for thread data +> not enough space for thread data + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. There are many possible reasons for this error, but often it's caused by an extremely low memory condition, a bug in the app, or by a bug in an add-in or extension used by the app. 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 45d4f87130b..737bf6e90f6 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6017.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6017.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6017" title: "C Runtime Error R6017" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6017" +ms.date: 11/04/2016 f1_keywords: ["R6017"] helpviewer_keywords: ["R6017"] -ms.assetid: df3ec5f5-6771-4648-ba06-0e26c6a1cc6a --- # C Runtime Error R6017 -unexpected multithread lock error +> unexpected multithread lock error + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal problem. There are several possible reasons for this error, but often it's caused by a defect in the app's code. @@ -23,4 +24,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 fc357363316..e2010a13a18 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6018.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6018.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6018" title: "C Runtime Error R6018" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6018" +ms.date: 11/04/2016 f1_keywords: ["R6018"] helpviewer_keywords: ["R6018"] -ms.assetid: f6dd40d1-a119-4d8b-b39e-97350ea23349 --- # C Runtime Error R6018 -unexpected heap error +> unexpected heap error + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal problem. There are several possible reasons for this error, but often it's caused by a defect in the app's code. @@ -25,4 +26,4 @@ The program encountered an unexpected error while performing a memory-management This error usually occurs if the program inadvertently alters the run-time heap data. However, it can also be caused by an internal error in the runtime or operating-system code. -To fix this issue, check for heap corruption bugs in your code. For more information and examples, see [CRT Debug Heap Details](/visualstudio/debugger/crt-debug-heap-details). Next, check that you are using the latest redistributables for your app deployment. For information, see [Deployment in Visual C++](../../windows/deployment-in-visual-cpp.md). +To fix this issue, check for heap corruption bugs in your code. For more information and examples, see [CRT Debug Heap Details](../../c-runtime-library/crt-debug-heap-details.md). Next, check that you are using the latest redistributables for your app deployment. For information, see [Deployment in Visual C++](../../windows/deployment-in-visual-cpp.md). diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6019.md b/docs/error-messages/tool-errors/c-runtime-error-r6019.md index 5c5bd53c170..51987fa5a60 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6019.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6019.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6019" title: "C Runtime Error R6019" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6019" +ms.date: 11/04/2016 f1_keywords: ["R6019"] helpviewer_keywords: ["R6019"] -ms.assetid: 8129923e-7db2-40ee-9602-def9365f8d28 --- # C Runtime Error R6019 -unable to open console device +> unable to open console device + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it attempted to access the console, but it didn't have sufficient permission. There are several possible reasons for this error, but it's usually because the program must be run as an administrator, or there is a bug in the program. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6024.md b/docs/error-messages/tool-errors/c-runtime-error-r6024.md index 7df58f0607f..d9657a8a397 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6024.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6024.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6024" title: "C Runtime Error R6024" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6024" +ms.date: 11/04/2016 f1_keywords: ["R6024"] helpviewer_keywords: ["R6024"] -ms.assetid: 0fb11c0f-9b81-4cab-81bd-4785742946a5 --- # C Runtime Error R6024 -not enough space for _onexit/atexit table +> not enough space for _onexit/atexit table + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. This error is usually caused by an extremely low memory condition, or rarely, by a bug in the program or by corruption of the Visual C++ libraries that it uses. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6025.md b/docs/error-messages/tool-errors/c-runtime-error-r6025.md index 42a2c6f4a3a..c081ab74720 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6025.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6025.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6025" title: "C Runtime Error R6025" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6025" +ms.date: 11/04/2016 f1_keywords: ["R6025"] helpviewer_keywords: ["R6025"] -ms.assetid: afa06d98-9c36-445b-b3e7-b6409bc8e779 --- # C Runtime Error R6025 -pure virtual function call +> pure virtual function call + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal problem. The most common reason for this error is a bug in the app, or a corrupted installation. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6026.md b/docs/error-messages/tool-errors/c-runtime-error-r6026.md index b1074266a4b..f54bf8f33ba 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6026.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6026.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6026" title: "C Runtime Error R6026" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6026" +ms.date: 11/04/2016 f1_keywords: ["R6026"] helpviewer_keywords: ["R6026"] -ms.assetid: 7ea751f8-fc20-46ab-99ef-84c95ca0b6b4 --- # C Runtime Error R6026 -not enough space for stdio initialization +> not enough space for stdio initialization + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. There are several possible reasons for this error, but usually it's caused by an extremely low memory condition. It can also be caused by a bug in the app, by corruption of the Visual C++ libraries that it uses, or by a driver. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6027.md b/docs/error-messages/tool-errors/c-runtime-error-r6027.md index 69dae0ca617..f399ec1a9ad 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6027.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6027.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6027" title: "C Runtime Error R6027" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6027" +ms.date: 11/04/2016 f1_keywords: ["R6027"] helpviewer_keywords: ["R6027"] -ms.assetid: c06a62b3-08d9-4bf5-bcad-8340ec552f69 --- # C Runtime Error R6027 -not enough space for lowio initialization +> not enough space for lowio initialization + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. There are several possible reasons for this error, but usually it's caused by an extremely low memory condition. It can also be caused by a bug in the app, by corruption of the Visual C++ libraries that it uses, or by a driver. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6028.md b/docs/error-messages/tool-errors/c-runtime-error-r6028.md index 7213f00140e..cb4c0697bf0 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6028.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6028.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6028" title: "C Runtime Error R6028" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6028" +ms.date: 11/04/2016 f1_keywords: ["R6028"] helpviewer_keywords: ["R6028"] -ms.assetid: 81e99079-4388-4244-a4f7-4641c508871c --- # C Runtime Error R6028 -unable to initialize heap +> unable to initialize heap + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. There are many possible reasons for this error, but often it's caused by an extremely low memory condition, a bug in the program, or by defective hardware drivers. @@ -25,4 +26,4 @@ unable to initialize heap This error occurs when the operating system failed to create the memory pool for the application. Specifically, the C Runtime (CRT) called the Win32 function `HeapCreate`, which returned NULL indicating failure. -If this error occurs during app startup, the system may be unable to satisfy heap requests because defective drivers are loaded. Check Windows Update or your hardware vendor’s web site for updated drivers. +If this error occurs during app startup, the system may be unable to satisfy heap requests because defective drivers are loaded. Check Windows Update or your hardware vendor's web site for updated drivers. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6030.md b/docs/error-messages/tool-errors/c-runtime-error-r6030.md index f190792505a..ad7dc5bd756 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6030.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6030.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6030" title: "C Runtime Error R6030" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6030" +ms.date: 11/04/2016 f1_keywords: ["R6030"] helpviewer_keywords: ["R6030"] -ms.assetid: 0238a6c3-a033-4046-8adc-f8f99d961153 --- # C Runtime Error R6030 -CRT not initialized +> CRT not initialized + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal problem. This problem is most often caused by certain security software programs, or rarely, by a bug in the program. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6031.md b/docs/error-messages/tool-errors/c-runtime-error-r6031.md index 94855e80c82..2a362dcdfad 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6031.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6031.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6031" title: "C Runtime Error R6031" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6031" +ms.date: 11/04/2016 f1_keywords: ["R6031"] helpviewer_keywords: ["R6031"] -ms.assetid: 805d4cd1-cb2f-43fe-87e6-e7bd5b7329c5 --- # C Runtime Error R6031 -Attempt to initialize the CRT more than once. This indicates a bug in your application. +> Attempt to initialize the CRT more than once. This indicates a bug in your application. + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal problem. This may be caused bug in the app, or by a bug in an add-on or extension that the app uses. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6032.md b/docs/error-messages/tool-errors/c-runtime-error-r6032.md index 85bf96da8f0..e50b73b5f87 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6032.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6032.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6032" title: "C Runtime Error R6032" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6032" +ms.date: 11/04/2016 f1_keywords: ["R6032"] helpviewer_keywords: ["R6032"] -ms.assetid: 52092a63-cc51-444a-bfc3-fad965a3558e --- # C Runtime Error R6032 -Not enough space for locale information +> Not enough space for locale information + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal memory problem. There are several possible reasons for this error, but often it's caused by an extremely low memory condition, or by a bug in the program. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6033.md b/docs/error-messages/tool-errors/c-runtime-error-r6033.md index fd113c60325..b308f6db468 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6033.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6033.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6033" title: "C Runtime Error R6033" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6033" +ms.date: 11/04/2016 f1_keywords: ["R6033"] helpviewer_keywords: ["R6033"] -ms.assetid: f9cffdc9-81bd-4a64-a698-02762cbd82c9 --- # C Runtime Error R6033 -Attempt to use MSIL code from this assembly during native code initialization. This indicates a bug in your application. It is most likely the result of calling an MSIL-compiled (/clr) function from a native constructor or from DllMain. +> Attempt to use MSIL code from this assembly during native code initialization. This indicates a bug in your application. It is most likely the result of calling an MSIL-compiled (/clr) function from a native constructor or from DllMain. + +## Remarks > [!NOTE] > If you encounter this error message while running an app, the app was shut down because it has an internal problem. This error can be caused by a bug in the app, or by a bug in an add-in or extension that it uses. diff --git a/docs/error-messages/tool-errors/c-runtime-error-r6035.md b/docs/error-messages/tool-errors/c-runtime-error-r6035.md index 7fba797b1e2..4dd704a367b 100644 --- a/docs/error-messages/tool-errors/c-runtime-error-r6035.md +++ b/docs/error-messages/tool-errors/c-runtime-error-r6035.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: C Runtime Error R6035" title: "C Runtime Error R6035" -ms.date: "11/04/2016" +description: "Learn more about: C Runtime Error R6035" +ms.date: 11/04/2016 f1_keywords: ["R6035"] helpviewer_keywords: ["R6035"] -ms.assetid: f8fb50b8-18bf-4258-b96a-b0a9de468d16 --- # C Runtime Error R6035 -Microsoft Visual C++ Runtime Library, Error R6035 - A module in this application is initializing the module's global security cookie while a function relying on that security cookie is active. Call __security_init_cookie earlier. +> A module in this application is initializing the module's global security cookie while a function relying on that security cookie is active. Call __security_init_cookie earlier. + +## Remarks [__security_init_cookie](../../c-runtime-library/reference/security-init-cookie.md) must be called before the first use of the global security cookie. @@ -16,6 +17,8 @@ The global security cookie is used for buffer overrun protection in code compile Error R6035 indicates that a call to `__security_init_cookie` was made after a protected function was entered. If execution were to continue, a spurious buffer overrun would be detected because the cookie on the stack would no longer match the global cookie. +## Example + Consider the following DLL example. The DLL entry point is set to DllEntryPoint through the linker [/ENTRY (Entry-Point Symbol)](../../build/reference/entry-entry-point-symbol.md) option. This bypasses the CRT's initialization which would ordinarily initialize the global security cookie, so the DLL itself must call `__security_init_cookie`. ``` diff --git a/docs/error-messages/tool-errors/c-runtime-errors-r6002-through-r6035.md b/docs/error-messages/tool-errors/c-runtime-errors-r6002-through-r6035.md index 97bc308ef10..8eac48f7d14 100644 --- a/docs/error-messages/tool-errors/c-runtime-errors-r6002-through-r6035.md +++ b/docs/error-messages/tool-errors/c-runtime-errors-r6002-through-r6035.md @@ -1,33 +1,36 @@ --- -description: "Learn more about: C Runtime errors (Rxxxx)" title: "C Runtime errors" -ms.date: "04/16/2019" +description: "Learn more about: C Runtime errors (Rxxxx)" +ms.date: 04/16/2019 f1_keywords: ["c.errors", "R6000", "R6003", "R6010", "R6022", "R6023", "R6034"] -ms.assetid: 78019050-9a30-4b61-8250-a5702e0e2393 --- # C Runtime errors (Rxxxx) The C Runtime library (CRT) may report a runtime error when your app is loaded or running. Even though each message refers to the Microsoft Visual C++ runtime library, it doesn't mean there's a bug in the library. These errors indicate either a bug in your app's code, or a condition that the runtime library can't handle, such as low memory. End users of your app may see these errors unless your write your app to prevent them, or to capture the errors and present a friendly error message to your users instead. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## C Runtime errors -[C Runtime Error R6002](../../error-messages/tool-errors/c-runtime-error-r6002.md) \ -[C Runtime Error R6008](../../error-messages/tool-errors/c-runtime-error-r6008.md) \ -[C Runtime Error R6009](../../error-messages/tool-errors/c-runtime-error-r6009.md) \ -[C Runtime Error R6016](../../error-messages/tool-errors/c-runtime-error-r6016.md) \ -[C Runtime Error R6017](../../error-messages/tool-errors/c-runtime-error-r6017.md) \ -[C Runtime Error R6018](../../error-messages/tool-errors/c-runtime-error-r6018.md) \ -[C Runtime Error R6019](../../error-messages/tool-errors/c-runtime-error-r6019.md) \ -[C Runtime Error R6024](../../error-messages/tool-errors/c-runtime-error-r6024.md) \ -[C Runtime Error R6025](../../error-messages/tool-errors/c-runtime-error-r6025.md) \ -[C Runtime Error R6028](../../error-messages/tool-errors/c-runtime-error-r6028.md) \ -[C Runtime Error R6030](../../error-messages/tool-errors/c-runtime-error-r6030.md) \ -[C Runtime Error R6031](../../error-messages/tool-errors/c-runtime-error-r6031.md) \ -[C Runtime Error R6032](../../error-messages/tool-errors/c-runtime-error-r6032.md) \ -[C Runtime Error R6033](../../error-messages/tool-errors/c-runtime-error-r6033.md) \ -[C Runtime Error R6035](../../error-messages/tool-errors/c-runtime-error-r6035.md) +| Error | Message | +|--|--| +| [C Runtime Error R6002](c-runtime-error-r6002.md) | floating-point support not loaded | +| [C Runtime Error R6008](c-runtime-error-r6008.md) | not enough space for arguments | +| [C Runtime Error R6009](c-runtime-error-r6009.md) | not enough space for environment | +| [C Runtime Error R6016](c-runtime-error-r6016.md) | not enough space for thread data | +| [C Runtime Error R6017](c-runtime-error-r6017.md) | unexpected multithread lock error | +| [C Runtime Error R6018](c-runtime-error-r6018.md) | unexpected heap error | +| [C Runtime Error R6019](c-runtime-error-r6019.md) | unable to open console device | +| [C Runtime Error R6024](c-runtime-error-r6024.md) | not enough space for _onexit/atexit table | +| [C Runtime Error R6025](c-runtime-error-r6025.md) | pure virtual function call | +| [C Runtime Error R6026](c-runtime-error-r6026.md) | not enough space for stdio initialization | +| [C Runtime Error R6027](c-runtime-error-r6027.md) | not enough space for lowio initialization | +| [C Runtime Error R6028](c-runtime-error-r6028.md) | unable to initialize heap | +| [C Runtime Error R6030](c-runtime-error-r6030.md) | CRT not initialized | +| [C Runtime Error R6031](c-runtime-error-r6031.md) | Attempt to initialize the CRT more than once. This indicates a bug in your application. | +| [C Runtime Error R6032](c-runtime-error-r6032.md) | Not enough space for locale information | +| [C Runtime Error R6033](c-runtime-error-r6033.md) | Attempt to use MSIL code from this assembly during native code initialization. This indicates a bug in your application. It is most likely the result of calling an MSIL-compiled (/clr) function from a native constructor or from DllMain. | +| [C Runtime Error R6035](c-runtime-error-r6035.md) | A module in this application is initializing the module's global security cookie while a function relying on that security cookie is active. Call __security_init_cookie earlier. | ## See also diff --git a/docs/error-messages/tool-errors/command-line-error-d8016.md b/docs/error-messages/tool-errors/command-line-error-d8016.md index e71b3d6cd07..6378c6f5ad7 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8016.md +++ b/docs/error-messages/tool-errors/command-line-error-d8016.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Error D8016" title: "Command-Line Error D8016" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Error D8016" +ms.date: 11/04/2016 f1_keywords: ["D8016"] helpviewer_keywords: ["D8016"] -ms.assetid: eec51312-7471-4f92-94b2-d517cafc8ef5 --- # Command-Line Error D8016 -'option1' and 'option2' command-line options are incompatible +> 'option1' and 'option2' command-line options are incompatible + +## Remarks The command-line options cannot be specified together. diff --git a/docs/error-messages/tool-errors/command-line-error-d8021.md b/docs/error-messages/tool-errors/command-line-error-d8021.md index 5daada8340c..67f23270441 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8021.md +++ b/docs/error-messages/tool-errors/command-line-error-d8021.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Command-Line Error D8021" title: "Command-Line Error D8021" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Error D8021" +ms.date: 11/04/2016 f1_keywords: ["D8021"] helpviewer_keywords: ["D8021"] -ms.assetid: 8ec85441-d0d8-42d8-b777-1e4636ea9878 --- # Command-Line Error D8021 -invalid numeric argument 'number' +> invalid numeric argument 'number' + +## Remarks A number greater than 65,534 was specified as a numeric argument. diff --git a/docs/error-messages/tool-errors/command-line-error-d8022.md b/docs/error-messages/tool-errors/command-line-error-d8022.md index 0fde42f9251..430d8c3d87a 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8022.md +++ b/docs/error-messages/tool-errors/command-line-error-d8022.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Error D8022" title: "Command-Line Error D8022" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Error D8022" +ms.date: 11/04/2016 f1_keywords: ["D8022"] helpviewer_keywords: ["D8022"] -ms.assetid: eb18ec34-d32d-4636-a852-abf2063e886b --- # Command-Line Error D8022 -cannot open 'messagefile' +> cannot open 'messagefile' + +## Remarks The given file was not in the current directory or in a directory specified in the PATH environment variable. The message file contains a brief summary of compiler command-line syntax and options. diff --git a/docs/error-messages/tool-errors/command-line-error-d8027.md b/docs/error-messages/tool-errors/command-line-error-d8027.md index 9fb55846634..886b134653b 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8027.md +++ b/docs/error-messages/tool-errors/command-line-error-d8027.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Error D8027" title: "Command-Line Error D8027" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Error D8027" +ms.date: 11/04/2016 f1_keywords: ["D8027"] helpviewer_keywords: ["D8027"] -ms.assetid: f228220f-0c7f-49a6-a6e0-1f7bd4745aa6 --- # Command-Line Error D8027 -cannot execute 'component' +> cannot execute 'component' + +## Remarks The compiler could not run the given compiler component or linker. diff --git a/docs/error-messages/tool-errors/command-line-error-d8036.md b/docs/error-messages/tool-errors/command-line-error-d8036.md index 86973440583..986134ce3d3 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8036.md +++ b/docs/error-messages/tool-errors/command-line-error-d8036.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Error D8036" title: "Command-Line Error D8036" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Error D8036" +ms.date: 11/04/2016 f1_keywords: ["D8036"] helpviewer_keywords: ["D8036"] -ms.assetid: 420a8daf-1873-49cd-95ea-a603d77b9410 --- # Command-Line Error D8036 -'/option' not allowed with multiple source files +> '/option' not allowed with multiple source files + +## Remarks These compiler options cannot be used with multiple source files: diff --git a/docs/error-messages/tool-errors/command-line-error-d8037.md b/docs/error-messages/tool-errors/command-line-error-d8037.md index d85b75168da..be3f25d3a85 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8037.md +++ b/docs/error-messages/tool-errors/command-line-error-d8037.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Error D8037" title: "Command-Line Error D8037" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Error D8037" +ms.date: 11/04/2016 f1_keywords: ["D8037"] helpviewer_keywords: ["D8037"] -ms.assetid: acddaaa0-bd84-426f-a37b-8f680b379c9d --- # Command-Line Error D8037 -cannot create temporary il file; clean temp directory of old il files +> cannot create temporary il file; clean temp directory of old il files + +## Remarks There is not enough space to create temporary compiler intermediate files. To remedy this error, remove any old MSIL files in the directory specified by the **TMP** environment variable. These files will be of the form _CL_hhhhhhhh.ss, where h represents a random hexadecimal digit and ss represents the type of IL file. Also, be sure to update your machine with the latest operating system patches. diff --git a/docs/error-messages/tool-errors/command-line-error-d8045.md b/docs/error-messages/tool-errors/command-line-error-d8045.md index fad1a656cf8..0297b0dbfcc 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8045.md +++ b/docs/error-messages/tool-errors/command-line-error-d8045.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Error D8045" title: "Command-Line Error D8045" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Error D8045" +ms.date: 11/04/2016 f1_keywords: ["D8045"] helpviewer_keywords: ["D8045"] -ms.assetid: 01c8808c-bac1-4b4d-8a90-b595f95e9318 --- # Command-Line Error D8045 -cannot compile C file 'file' with the /clr option +> cannot compile C file 'file' with the /clr option + +## Remarks Only C++ source code files can be passed to a compilation that uses **/clr**. Use **/TP** to compile a .c file as a .cpp file; see [/Tc, /Tp, /TC, /TP (Specify Source File Type)](../../build/reference/tc-tp-tc-tp-specify-source-file-type.md) for more information. diff --git a/docs/error-messages/tool-errors/command-line-error-d8048.md b/docs/error-messages/tool-errors/command-line-error-d8048.md index 65fa5514cab..39dcd944558 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8048.md +++ b/docs/error-messages/tool-errors/command-line-error-d8048.md @@ -1,6 +1,6 @@ --- -description: "Learn about causes and solutions for command-line error D8048" title: "Command-Line Error D8048" +description: "Learn about causes and solutions for command-line error D8048" ms.date: 04/18/2021 f1_keywords: ["D8048"] helpviewer_keywords: ["D8048"] @@ -9,10 +9,10 @@ helpviewer_keywords: ["D8048"] > cannot compile C file '*file-name*' with /ZW option -Only C++ source code files can be passed to the compiler when you use the [`/ZW` (Windows Runtime compilation)](../../build/reference/zw-windows-runtime-compilation.md) compiler option. - ## Remarks +Only C++ source code files can be passed to the compiler when you use the [`/ZW` (Windows Runtime compilation)](../../build/reference/zw-windows-runtime-compilation.md) compiler option. + By default, all files in a C++ Universal Windows platform (UWP) project are compiled by using the **`/ZW`** compiler option. The **`/ZW`** option enables the Windows Runtime compiler extensions, or C++/CX. Unfortunately, **`/ZW`** doesn't work on C source files. You can disable C++/CX compilation selectively for C files in Visual Studio projects. Select your C file in Solution Explorer, then right-click to choose **Properties** from the shortcut menu. In the **Property Pages** dialog, select the **Configuration Properties** > **C/C++** -> **General** property page. Set the **Consume Windows Runtime Extension** property to *`No`*. Choose **OK** to save your changes. diff --git a/docs/error-messages/tool-errors/command-line-error-d8049.md b/docs/error-messages/tool-errors/command-line-error-d8049.md index ec848363813..24c359f7583 100644 --- a/docs/error-messages/tool-errors/command-line-error-d8049.md +++ b/docs/error-messages/tool-errors/command-line-error-d8049.md @@ -1,6 +1,6 @@ --- -description: "Learn about the cause and solutions for command-line error D8049" title: "Command-Line Error D8049" +description: "Learn about the cause and solutions for command-line error D8049" ms.date: 10/28/2021 f1_keywords: ["D8049"] helpviewer_keywords: ["D8049"] @@ -9,10 +9,10 @@ helpviewer_keywords: ["D8049"] > cannot execute '*compiler-component*': command line is too long to fit in debug record -An internal length limit on debug record include paths was exceeded. - ## Remarks +An internal length limit on debug record include paths was exceeded. + When the compiler creates debug records in an object file, it uses the full path for each included file. Absolute paths are recorded as specified. For relative include paths, the debug record prepends the build's current working directory to the relative path. If your build runs in a relatively deep path, the corresponding path records get longer. The total length of too many long paths can exceed the internal limits of the compiler. ## To resolve this issue diff --git a/docs/error-messages/tool-errors/command-line-errors-d8000-through-d9999.md b/docs/error-messages/tool-errors/command-line-errors-d8000-through-d9999.md index 5eb48e048e6..14a992e335f 100644 --- a/docs/error-messages/tool-errors/command-line-errors-d8000-through-d9999.md +++ b/docs/error-messages/tool-errors/command-line-errors-d8000-through-d9999.md @@ -1,39 +1,43 @@ --- -description: "Learn more about: Command-line errors and warnings" title: "Command-line errors and warnings" -ms.date: "04/17/2019" -ms.assetid: d02ec7df-26a5-4198-ac92-87b29ec9d5c8 +description: "Learn more about: Command-line errors and warnings" +ms.date: 04/17/2019 --- # Command-line errors and warnings The articles in this section provide a reference to the command-line errors and warnings generated by the build tools. These messages have the form `Dxxxx`, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Command-line error messages -[Command-Line Error D8016](../../error-messages/tool-errors/command-line-error-d8016.md) \ -[Command-Line Error D8021](../../error-messages/tool-errors/command-line-error-d8021.md) \ -[Command-Line Error D8022](../../error-messages/tool-errors/command-line-error-d8022.md) \ -[Command-Line Error D8027](../../error-messages/tool-errors/command-line-error-d8027.md) \ -[Command-Line Error D8036](../../error-messages/tool-errors/command-line-error-d8036.md) \ -[Command-Line Error D8037](../../error-messages/tool-errors/command-line-error-d8037.md) \ -[Command-Line Error D8045](../../error-messages/tool-errors/command-line-error-d8045.md) \ -[Command-Line Error D8048](../../error-messages/tool-errors/command-line-error-d8048.md) \ -[Command-Line Error D8049](../../error-messages/tool-errors/command-line-error-d8049.md) +| Error | Message | +|--|--| +| [Command-Line Error D8016](command-line-error-d8016.md) | 'option1' and 'option2' command-line options are incompatible | +| [Command-Line Error D8021](command-line-error-d8021.md) | invalid numeric argument 'number' | +| [Command-Line Error D8022](command-line-error-d8022.md) | cannot open 'messagefile' | +| [Command-Line Error D8027](command-line-error-d8027.md) | cannot execute 'component' | +| [Command-Line Error D8036](command-line-error-d8036.md) | '/option' not allowed with multiple source files | +| [Command-Line Error D8037](command-line-error-d8037.md) | cannot create temporary il file; clean temp directory of old il files | +| [Command-Line Error D8045](command-line-error-d8045.md) | cannot compile C file 'file' with the /clr option | +| [Command-Line Error D8048](command-line-error-d8048.md) | cannot compile C file '*file-name*' with /ZW option | +| [Command-Line Error D8049](command-line-error-d8049.md) | cannot execute '*compiler-component*': command line is too long to fit in debug record | ## Command-line warning messages -[Command-Line Warning D9024](../../error-messages/tool-errors/command-line-warning-d9024.md) \ -[Command-Line Warning D9025](../../error-messages/tool-errors/command-line-warning-d9025.md) \ -[Command-Line Warning D9026](../../error-messages/tool-errors/command-line-warning-d9026.md) \ -[Command-Line Warning D9027](../../error-messages/tool-errors/command-line-warning-d9027.md) \ -[Command-Line Warning D9028](../../error-messages/tool-errors/command-line-warning-d9028.md) \ -[Command-Line Warning D9035](../../error-messages/tool-errors/command-line-warning-d9035.md) \ -[Command-Line Warning D9036](../../error-messages/tool-errors/command-line-warning-d9036.md) \ -[Command-Line Warning D9040](../../error-messages/tool-errors/command-line-warning-d9040.md) \ -[Command-Line Warning D9041](../../error-messages/tool-errors/command-line-warning-d9041.md) \ -[Command-Line Warning D9043](../../error-messages/tool-errors/command-line-warning-d9043.md) +| Warning | Message | +|--|--| +| Command-Line Warning D9014 | invalid value for 'processMax'. The compiler ignores the invalid value and assumes a value of 1.| +| [Command-Line Warning D9024](command-line-warning-d9024.md) | unrecognized source file type 'filename', object file assumed. Occurs when a command‑line argument looks like a filename but doesn’t match a recognized source or object file extension. The compiler assumes it's an object file and passes it to the linker. | +| [Command-Line Warning D9025](command-line-warning-d9025.md) | overriding 'option1' with 'option2' | +| [Command-Line Warning D9026](command-line-warning-d9026.md) | options apply to entire command line | +| [Command-Line Warning D9027](command-line-warning-d9027.md) | source file '\' ignored | +| [Command-Line Warning D9028](command-line-warning-d9028.md) | minimal rebuild failure, reverting to normal build | +| [Command-Line Warning D9035](command-line-warning-d9035.md) | option '*option*' has been deprecated and will be removed in a future release | +| [Command-Line Warning D9036](command-line-warning-d9036.md) | '*option\_2*' instead of '*option\_1*' | +| [Command-Line Warning D9040](command-line-warning-d9040.md) | ignoring option '/analyze'; Code Analysis warnings are not available in this edition of the compiler | +| [Command-Line Warning D9041](command-line-warning-d9041.md) | invalid value '*option-value*' for '/*option-name*'; assuming '*assumed-value*'; add '/analyze' to command-line options when specifying this warning | +| [Command-Line Warning D9043](command-line-warning-d9043.md) | invalid value 'warning_level' for 'compiler_option'; assuming '4999'; Code Analysis warnings are not associated with warning levels | ## See also diff --git a/docs/error-messages/tool-errors/command-line-warning-d9024.md b/docs/error-messages/tool-errors/command-line-warning-d9024.md index e161eb89438..5af7073689e 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9024.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9024.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Warning D9024" title: "Command-Line Warning D9024" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Warning D9024" +ms.date: 11/04/2016 f1_keywords: ["D9024"] helpviewer_keywords: ["D9024"] -ms.assetid: daf4896d-223d-4af0-9b6d-89109cf3d1bb --- # Command-Line Warning D9024 -unrecognized source file type 'filename', object file assumed +> unrecognized source file type 'filename', object file assumed + +## Remarks The extension of the specified file was not recognized. The file was assumed to be an object file and was passed to the linker. diff --git a/docs/error-messages/tool-errors/command-line-warning-d9025.md b/docs/error-messages/tool-errors/command-line-warning-d9025.md index 156400af5db..43d872d40fc 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9025.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9025.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Command-Line Warning D9025" title: "Command-Line Warning D9025" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Warning D9025" +ms.date: 11/04/2016 f1_keywords: ["D9025"] helpviewer_keywords: ["D9025"] -ms.assetid: 6edff72c-1508-46c2-99f4-0e4b3c5e60c9 --- # Command-Line Warning D9025 -overriding 'option1' with 'option2' +> overriding 'option1' with 'option2' + +## Remarks The *option1* option was specified but was then overridden by *option2*. The *option2* option was used. diff --git a/docs/error-messages/tool-errors/command-line-warning-d9026.md b/docs/error-messages/tool-errors/command-line-warning-d9026.md index 1b28c6a30e2..ec76878b14d 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9026.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9026.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: Command-line warning D9026" title: "Command-line warning D9026" +description: "Learn more about: Command-line warning D9026" ms.date: 12/09/2021 f1_keywords: ["D9026"] helpviewer_keywords: ["D9026"] -ms.assetid: 149fe5e3-5329-4be8-b871-49dfd423aaba --- # Command-line warning D9026 > options apply to entire command line +## Remarks + A global option was specified after one or more filenames were specified. The option was also applied to the files that preceded it. +## Example + For example, consider this command line: `CL verdi.c /O2 puccini.c` diff --git a/docs/error-messages/tool-errors/command-line-warning-d9027.md b/docs/error-messages/tool-errors/command-line-warning-d9027.md index a4eefa41805..89064f31aa7 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9027.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9027.md @@ -1,25 +1,30 @@ --- -description: "Learn more about: Command-Line Warning D9027" title: "Command-Line Warning D9027" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Warning D9027" +ms.date: 11/04/2016 f1_keywords: ["D9027"] helpviewer_keywords: ["D9027"] -ms.assetid: 2a29edc5-5649-48f2-9058-2057c747284c --- # Command-Line Warning D9027 -source file '\' ignored +> source file '\' ignored + +## Remarks CL.exe ignored the input source file. -This warning can be caused by a space between the /Fo option and an output filename on a command line with the /c option. For example: +This warning can be caused by a space between the /Fo option and an output filename on a command line with the /c option. -``` +## Example + +For example: + +```cmd cl /c /Fo output.obj input.c ``` Because there is a space between /Fo and `output.obj`, CL.exe takes `output.obj` as the name of the input file. To fix the problem, remove the space: -``` +```cmd cl /c /Fooutput.obj input.c ``` diff --git a/docs/error-messages/tool-errors/command-line-warning-d9028.md b/docs/error-messages/tool-errors/command-line-warning-d9028.md index 0c538f76ea5..35b38a28518 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9028.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9028.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Command-Line Warning D9028" title: "Command-Line Warning D9028" -ms.date: "04/08/2019" +description: "Learn more about: Command-Line Warning D9028" +ms.date: 04/08/2019 f1_keywords: ["D9028"] helpviewer_keywords: ["D9028"] -ms.assetid: 03852b51-fa59-4114-ab1f-2af0509119af --- # Command-Line Warning D9028 > minimal rebuild failure, reverting to normal build +## Remarks + The project .idb file is corrupt. Delete the file and rebuild. For more information on minimal rebuilds and the .idb file, see the deprecated [/Gm compiler option](../../build/reference/gm-enable-minimal-rebuild.md). diff --git a/docs/error-messages/tool-errors/command-line-warning-d9035.md b/docs/error-messages/tool-errors/command-line-warning-d9035.md index d7d3262869e..eb8cf111ac6 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9035.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9035.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Command-Line Warning D9035" title: "Command-Line Warning D9035" -ms.date: "12/10/2018" +description: "Learn more about: Command-Line Warning D9035" +ms.date: 12/10/2018 f1_keywords: ["D9035"] helpviewer_keywords: ["D9035"] -ms.assetid: 6254f933-e37a-45ba-b860-1a870d1bc8e8 --- # Command-Line Warning D9035 diff --git a/docs/error-messages/tool-errors/command-line-warning-d9036.md b/docs/error-messages/tool-errors/command-line-warning-d9036.md index d26818460c1..6f1363ee3b9 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9036.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9036.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Command-Line Warning D9036" title: "Command-Line Warning D9036" -ms.date: "12/10/2018" +description: "Learn more about: Command-Line Warning D9036" +ms.date: 12/10/2018 f1_keywords: ["D9036"] helpviewer_keywords: ["D9036"] -ms.assetid: 68276e84-8d4e-4d4a-a9db-2874c81dfe66 --- # Command-Line Warning D9036 diff --git a/docs/error-messages/tool-errors/command-line-warning-d9040.md b/docs/error-messages/tool-errors/command-line-warning-d9040.md index 3f9c925fb41..900922a82cd 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9040.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9040.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Command-Line Warning D9040" title: "Command-Line Warning D9040" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Warning D9040" +ms.date: 11/04/2016 f1_keywords: ["D9040"] helpviewer_keywords: ["D9040"] -ms.assetid: 415e7f04-c1bd-4ac1-924a-03efa4645140 --- # Command-Line Warning D9040 > ignoring option '/analyze'; Code Analysis warnings are not available in this edition of the compiler +## Remarks + The **`/analyze`** command line option is not available in all editions of Visual Studio. To remedy this warning, either switch to a supported edition of Visual Studio, or remove the command line option. ## See also diff --git a/docs/error-messages/tool-errors/command-line-warning-d9041.md b/docs/error-messages/tool-errors/command-line-warning-d9041.md index b477d13c8c7..80f0bb4e6da 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9041.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9041.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Command-Line Warning D9041" title: "Command-Line Warning D9041" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Warning D9041" +ms.date: 11/04/2016 f1_keywords: ["D9041"] helpviewer_keywords: ["D9041"] -ms.assetid: ada8815f-4246-4e25-b57d-a7f16fa107cc --- # Command-Line Warning D9041 > invalid value '*option-value*' for '/*option-name*'; assuming '*assumed-value*'; add '/analyze' to command-line options when specifying this warning +## Remarks + A Code Analysis warning number was added to the **`/wd`**, **`/we`**, **`/wo`**, or **`/wl`** command line option without also specifying the **`/analyze`** command line option. To remedy this error, either add the **`/analyze`** command line option, or remove the invalid warning number from the appropriate **`/w`** command line option. ## Example diff --git a/docs/error-messages/tool-errors/command-line-warning-d9043.md b/docs/error-messages/tool-errors/command-line-warning-d9043.md index 44bc3eb9b8f..099489e25ac 100644 --- a/docs/error-messages/tool-errors/command-line-warning-d9043.md +++ b/docs/error-messages/tool-errors/command-line-warning-d9043.md @@ -1,18 +1,17 @@ --- -description: "Learn more about: Command-Line Warning D9043" title: "Command-Line Warning D9043" -ms.date: "11/04/2016" +description: "Learn more about: Command-Line Warning D9043" +ms.date: 11/04/2016 f1_keywords: ["D9043"] helpviewer_keywords: ["D9043"] -ms.assetid: 9263e28d-217b-414c-bfb6-86efd3c27a77 --- # Command-Line Warning D9043 -invalid value 'warning_level' for 'compiler_option'; assuming '4999'; Code Analysis warnings are not associated with warning levels +> invalid value 'warning_level' for 'compiler_option'; assuming '4999'; Code Analysis warnings are not associated with warning levels ## Example -The following sample generates C9043. +The following example generates D9043. ```cpp // D9043.cpp diff --git a/docs/error-messages/tool-errors/cvtres-errors-cvt1100-through-cvt4001.md b/docs/error-messages/tool-errors/cvtres-errors-cvt1100-through-cvt4001.md index 633159c3ad0..0b2040cb66b 100644 --- a/docs/error-messages/tool-errors/cvtres-errors-cvt1100-through-cvt4001.md +++ b/docs/error-messages/tool-errors/cvtres-errors-cvt1100-through-cvt4001.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: CVTRES errors and warnings (CVTxxxx)" title: "CVTRES errors and warnings" -ms.date: "04/16/2019" +description: "Learn more about: CVTRES errors and warnings (CVTxxxx)" +ms.date: 04/16/2019 f1_keywords: ["CVT1101", "CVT1102", "CVT1104", "CVT1106", "CVT1107", "CVT1108", "CVT1109", "CVT1110"] -ms.assetid: ac94d0fb-0da3-4327-b3d9-ceaeb3fc2e4d --- # CVTRES errors and warnings (CVTxxxx) @@ -13,13 +12,17 @@ This section is a reference to the errors and warnings generated by the CVTRES b ## Fatal error messages -[CVTRES fatal error CVT1100](cvtres-fatal-error-cvt1100.md) \ -[CVTRES fatal error CVT1103](cvtres-fatal-error-cvt1103.md) \ -[CVTRES fatal error CVT1105](cvtres-fatal-error-cvt1105.md) +| Error | Message | +|--|--| +| [CVTRES fatal error CVT1100](cvtres-fatal-error-cvt1100.md) | duplicate resource — type:type, name:name, language:language, flags:flags, size:size | +| [CVTRES fatal error CVT1103](cvtres-fatal-error-cvt1103.md) | cannot read filename | +| [CVTRES fatal error CVT1105](cvtres-fatal-error-cvt1105.md) | cannot seek in file | ## Warning messages -[CVTRES warning CVT4001](cvtres-warning-cvt4001.md) +| Warning | Message | +|--|--| +| [CVTRES warning CVT4001](cvtres-warning-cvt4001.md) | machine type not specified; assumed *type* | ## See also diff --git a/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1100.md b/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1100.md index d4f1ee842da..29fd15d3c3d 100644 --- a/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1100.md +++ b/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1100.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: CVTRES Fatal Error CVT1100" title: "CVTRES Fatal Error CVT1100" -ms.date: "11/04/2016" +description: "Learn more about: CVTRES Fatal Error CVT1100" +ms.date: 11/04/2016 f1_keywords: ["CVT1100"] helpviewer_keywords: ["CVT1100"] -ms.assetid: 886e88dd-5818-4b5f-84f2-d2a3d75f0aaf --- # CVTRES Fatal Error CVT1100 -duplicate resource — type:type, name:name, language:language, flags:flags, size:size +> duplicate resource — type:type, name:name, language:language, flags:flags, size:size + +## Remarks The given resource was specified more than once. diff --git a/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1103.md b/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1103.md index 5ca0766f957..b73038b1032 100644 --- a/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1103.md +++ b/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1103.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: CVTRES Fatal Error CVT1103" title: "CVTRES Fatal Error CVT1103" -ms.date: "11/04/2016" +description: "Learn more about: CVTRES Fatal Error CVT1103" +ms.date: 11/04/2016 f1_keywords: ["CVT1103"] helpviewer_keywords: ["CVT1103"] -ms.assetid: 5ba5f44c-c3c3-4861-92c5-13c51ee667ef --- # CVTRES Fatal Error CVT1103 -cannot read filename +> cannot read filename + +## Remarks An unrecoverable error occurred when CVTRES attempted to read the given file. diff --git a/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1105.md b/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1105.md index bc43ec10d2a..8bedfeeb3eb 100644 --- a/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1105.md +++ b/docs/error-messages/tool-errors/cvtres-fatal-error-cvt1105.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: CVTRES Fatal Error CVT1105" title: "CVTRES Fatal Error CVT1105" -ms.date: "11/04/2016" +description: "Learn more about: CVTRES Fatal Error CVT1105" +ms.date: 11/04/2016 f1_keywords: ["CVT1105"] helpviewer_keywords: ["CVT1105"] -ms.assetid: 6fb98e2b-836e-4e1e-9bd8-4e1465ad4e85 --- # CVTRES Fatal Error CVT1105 -cannot seek in file +> cannot seek in file + +## Remarks CVTRES could not go to a location in the file. diff --git a/docs/error-messages/tool-errors/cvtres-warning-cvt4001.md b/docs/error-messages/tool-errors/cvtres-warning-cvt4001.md index c5a1257e706..31ce4a14981 100644 --- a/docs/error-messages/tool-errors/cvtres-warning-cvt4001.md +++ b/docs/error-messages/tool-errors/cvtres-warning-cvt4001.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: CVTRES Warning CVT4001" title: "CVTRES Warning CVT4001" -ms.date: "08/27/2018" +description: "Learn more about: CVTRES Warning CVT4001" +ms.date: 08/27/2018 f1_keywords: ["CVT4001"] helpviewer_keywords: ["CVT4001"] -ms.assetid: 39c13bc2-92fa-4d79-8171-039b27329dcc --- # CVTRES Warning CVT4001 > machine type not specified; assumed *type* +## Remarks + CVTRES did not find a machine specification. It assumed the given machine type. If the default is incorrect, rerun CVTRES using the /MACHINE option. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0000.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0000.md index cfc74ee7552..36257d65814 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0000.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0000.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0000" title: "Expression Evaluator Error CXX0000" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0000" +ms.date: 11/04/2016 f1_keywords: ["CXX0000"] helpviewer_keywords: ["CAN0000", "CXX0000"] -ms.assetid: 95a7f17d-88ea-4a6c-a3af-2289bf0529fe --- # Expression Evaluator Error CXX0000 -no error condition +> no error condition + +## Remarks No error has occurred. You can continue debugging normally. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0001.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0001.md index 73944dbf0b0..6eaffca2052 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0001.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0001.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0001" title: "Expression Evaluator Error CXX0001" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0001" +ms.date: 11/04/2016 f1_keywords: ["CXX0001"] helpviewer_keywords: ["CXX0001", "CAN0001"] -ms.assetid: 39cdf175-e4b8-49c1-bf84-ed41e0fd8600 --- # Expression Evaluator Error CXX0001 -exception executing user function +> exception executing user function + +## Remarks The code being executed caused a general protection fault. This error is identical to CAN0001. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0002.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0002.md index 8070e98c160..5cdf941c8d9 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0002.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0002.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0002" title: "Expression Evaluator Error CXX0002" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0002" +ms.date: 11/04/2016 f1_keywords: ["CXX0002"] helpviewer_keywords: ["CXX0002", "CAN0002"] -ms.assetid: 5f136470-505f-4224-a29a-2d34e896d78b --- # Expression Evaluator Error CXX0002 -error accessing user memory +> error accessing user memory + +## Remarks The expression attempts to reference memory that is not allocated to the program being debugged. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0004.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0004.md index 1bac7f4b77c..dbf174f51fe 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0004.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0004.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0004" title: "Expression Evaluator Error CXX0004" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0004" +ms.date: 11/04/2016 f1_keywords: ["CXX0004"] helpviewer_keywords: ["CAN0004", "CXX0004"] -ms.assetid: a4063eda-0335-4ae7-9595-29cf10669376 --- # Expression Evaluator Error CXX0004 -syntax error +> syntax error + +## Remarks The syntax of the expression is incorrect. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0005.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0005.md index b7c786053a7..9aac32814d1 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0005.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0005.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0005" title: "Expression Evaluator Error CXX0005" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0005" +ms.date: 11/04/2016 f1_keywords: ["CXX0005"] helpviewer_keywords: ["CXX0005", "CAN0005"] -ms.assetid: b88e83e4-10aa-4e9c-94d3-92aa8c688748 --- # Expression Evaluator Error CXX0005 -operator not supported +> operator not supported + +## Remarks An unsupported C operator was specified in an expression. Write an equivalent expression using the supported C operators. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0006.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0006.md index bd78c131518..2a172e02f87 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0006.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0006.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0006" title: "Expression Evaluator Error CXX0006" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0006" +ms.date: 11/04/2016 f1_keywords: ["CXX0006"] helpviewer_keywords: ["CAN0006", "CXX0006"] -ms.assetid: 34a8e21c-5443-4817-aad9-bb3143cfcaa6 --- # Expression Evaluator Error CXX0006 -missing left parenthesis +> missing left parenthesis + +## Remarks Unbalanced parentheses were found in the expression. Retype the expression with balanced parentheses. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0007.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0007.md index 27956d6b228..886c1987ad8 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0007.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0007.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0007" title: "Expression Evaluator Error CXX0007" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0007" +ms.date: 11/04/2016 f1_keywords: ["CXX0007"] helpviewer_keywords: ["CXX0007", "CAN0007"] -ms.assetid: 270a6d2d-ea6b-4a94-9871-841a6a133292 --- # Expression Evaluator Error CXX0007 -missing right parenthesis +> missing right parenthesis + +## Remarks Unbalanced parentheses were found in the expression. Retype the expression with balanced parentheses. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0008.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0008.md index bca96bf5fa0..201553ebca2 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0008.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0008.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0008" title: "Expression Evaluator Error CXX0008" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0008" +ms.date: 11/04/2016 f1_keywords: ["CXX0008"] helpviewer_keywords: ["CXX0008", "CAN0008"] -ms.assetid: 49e0968c-a6ce-4ba9-9762-02a55c08124e --- # Expression Evaluator Error CXX0008 -**missing " at end of string** +> missing " at end of string + +## Remarks The double quote expected at the end of the string literal was missing. Retype the expression, enclosing the string literal in double quotation marks. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0009.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0009.md index 74dc99854fd..22cebf0aa8c 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0009.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0009.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0009" title: "Expression Evaluator Error CXX0009" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0009" +ms.date: 11/04/2016 f1_keywords: ["CXX0009"] helpviewer_keywords: ["CXX0009", "CAN0009"] -ms.assetid: b6f26a46-56f3-430f-a6db-b42934ddf331 --- # Expression Evaluator Error CXX0009 -missing ' after character constant +> missing ' after character constant + +## Remarks The single quote expected at the end of the character constant was missing. Retype the expression, enclosing the character constant in single quotation marks. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0010.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0010.md index 9412b3c4c7b..d3eb52bb8cc 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0010.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0010.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0010" title: "Expression Evaluator Error CXX0010" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0010" +ms.date: 11/04/2016 f1_keywords: ["CXX0010"] helpviewer_keywords: ["CAN0010", "CXX0010"] -ms.assetid: 8bd474b0-da12-4990-8569-6392f09f05f6 --- # Expression Evaluator Error CXX0010 -missing left bracket +> missing left bracket + +## Remarks The expression contains unbalanced square brackets. Retype the expression with balanced square brackets. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0011.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0011.md index f2eda30c029..73e96763e91 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0011.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0011.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0011" title: "Expression Evaluator Error CXX0011" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0011" +ms.date: 11/04/2016 f1_keywords: ["CXX0011"] helpviewer_keywords: ["CAN0011", "CXX0011"] -ms.assetid: c2252e89-ad66-43fc-93e4-b886dcbd3f19 --- # Expression Evaluator Error CXX0011 -missing right bracket +> missing right bracket + +## Remarks The expression contains unbalanced square brackets. Retype the expression with balanced square brackets. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0012.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0012.md index f35e2ee2907..367224bbc98 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0012.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0012.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0012" title: "Expression Evaluator Error CXX0012" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0012" +ms.date: 11/04/2016 f1_keywords: ["CXX0012"] helpviewer_keywords: ["CXX0012", "CAN0012"] -ms.assetid: bf547e21-6708-4854-ad23-2ae5a889fd82 --- # Expression Evaluator Error CXX0012 -missing left curly brace +> missing left curly brace + +## Remarks The expression contains an unbalanced curly brace. Retype the expression with balanced curly braces. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0013.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0013.md index 0b88ec11273..91bcbb1a834 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0013.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0013.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0013" title: "Expression Evaluator Error CXX0013" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0013" +ms.date: 11/04/2016 f1_keywords: ["CXX0013"] helpviewer_keywords: ["CAN0013", "CXX0013"] -ms.assetid: cf571e37-008d-47cd-80fa-59e96b1146e1 --- # Expression Evaluator Error CXX0013 -missing operator +> missing operator + +## Remarks An operator was expected in the expression but was not found. Check the syntax of the expression. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0014.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0014.md index 640a86da34f..9876536b5c0 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0014.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0014.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0014" title: "Expression Evaluator Error CXX0014" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0014" +ms.date: 11/04/2016 f1_keywords: ["CXX0014"] helpviewer_keywords: ["CAN0014", "CXX0014"] -ms.assetid: 3bb0278d-3dd6-4626-9945-3cf29afbbacb --- # Expression Evaluator Error CXX0014 -missing operand +> missing operand + +## Remarks An operator was specified without a required operand. Check the syntax of the expression. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0015.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0015.md index 31160b46a72..bb5d1ed5373 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0015.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0015.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0015" title: "Expression Evaluator Error CXX0015" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0015" +ms.date: 11/04/2016 f1_keywords: ["CXX0015"] helpviewer_keywords: ["CXX0015", "CAN0015"] -ms.assetid: 35efaf77-d578-48d8-bfc5-fdeb2a46a8b5 --- # Expression Evaluator Error CXX0015 -expression too complex (stack overflow) +> expression too complex (stack overflow) + +## Remarks The expression entered was too complex or nested too deeply for the amount of storage available to the C expression evaluator. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0016.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0016.md index 4feb05578b6..b1707a48dd8 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0016.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0016.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0016" title: "Expression Evaluator Error CXX0016" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0016" +ms.date: 11/04/2016 f1_keywords: ["CXX0016"] helpviewer_keywords: ["CAN0016", "CXX0016"] -ms.assetid: af94a2ae-e835-4da6-8d2f-5c879f72eda2 --- # Expression Evaluator Error CXX0016 -constant too big +> constant too big + +## Remarks The C expression evaluator cannot accept an unsigned integer constant larger than 4,294,967,295 (0FFFFFFFF hexadecimal), or a floating-point constant whose magnitude is larger than approximately 1.8E+308. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0017.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0017.md index f6c81de30cc..6c938f71ef0 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0017.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0017.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0017" title: "Expression Evaluator Error CXX0017" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0017" +ms.date: 11/04/2016 f1_keywords: ["CXX0017"] helpviewer_keywords: ["CAN0017", "CXX0017"] -ms.assetid: af74db02-a64d-49ca-8363-3e044a107580 --- # Expression Evaluator Error CXX0017 -symbol not found +> symbol not found + +## Remarks A symbol specified in an expression could not be found. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0018.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0018.md index 9f7e92345ca..dac98b60f4d 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0018.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0018.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0018" title: "Expression Evaluator Error CXX0018" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0018" +ms.date: 11/04/2016 f1_keywords: ["CXX0018"] helpviewer_keywords: ["CAN0018", "CXX0018"] -ms.assetid: d3d115d6-8981-4651-b615-566de867a263 --- # Expression Evaluator Error CXX0018 -bad register name +> bad register name + +## Remarks A specified register does not exist or cannot be displayed. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0019.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0019.md index 680e0ee45f5..80ad76d78e5 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0019.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0019.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0019" title: "Expression Evaluator Error CXX0019" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0019" +ms.date: 11/04/2016 f1_keywords: ["CXX0019"] helpviewer_keywords: ["CXX0019", "CAN0019"] -ms.assetid: 4c6431fd-3310-4a61-934d-58b070b330fe --- # Expression Evaluator Error CXX0019 -bad type cast +> bad type cast + +## Remarks The C expression evaluator cannot perform the type cast as written. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0020.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0020.md index c34f0f55823..2b553478ee1 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0020.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0020.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0020" title: "Expression Evaluator Error CXX0020" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0020" +ms.date: 11/04/2016 f1_keywords: ["CXX0020"] helpviewer_keywords: ["CXX0020", "CAN0020"] -ms.assetid: 9dc57c25-e976-44e8-9a4e-db5a79e35bd7 --- # Expression Evaluator Error CXX0020 -operand types bad for this operation +> operand types bad for this operation + +## Remarks An operator was applied to an expression with an invalid type for that operator. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0021.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0021.md index 162380237e5..1b1bbf92e52 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0021.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0021.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0021" title: "Expression Evaluator Error CXX0021" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0021" +ms.date: 11/04/2016 f1_keywords: ["CXX0021"] helpviewer_keywords: ["CXX0021", "CAN0021"] -ms.assetid: d6c0c35a-16c2-42c0-a7d2-e910350a47f0 --- # Expression Evaluator Error CXX0021 -struct or union used as scalar +> struct or union used as scalar + +## Remarks A structure or union was used in an expression, but no element was specified. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0022.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0022.md index 1c06fe8c2a0..9e22b714a45 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0022.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0022.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0022" title: "Expression Evaluator Error CXX0022" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0022" +ms.date: 11/04/2016 f1_keywords: ["CXX0022"] helpviewer_keywords: ["CXX0022", "CAN0022"] -ms.assetid: f6b299ac-a4ee-492c-bd9f-6fff005bc537 --- # Expression Evaluator Error CXX0022 -function call before _main +> function call before _main + +## Remarks The C expression evaluator cannot evaluate a function before the debugger has entered the function **_main**. The program is not properly initialized until **_main** has been called. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0023.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0023.md index d71fb7f9703..b052cd60af5 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0023.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0023.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0023" title: "Expression Evaluator Error CXX0023" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0023" +ms.date: 11/04/2016 f1_keywords: ["CXX0023"] helpviewer_keywords: ["CXX0023", "CAN0023"] -ms.assetid: 2de27692-dfb5-433f-82b3-80f118756eec --- # Expression Evaluator Error CXX0023 -bad radix +> bad radix + +## Remarks The C expression evaluator does not recognize the radix specified. Only decimal, hexadecimal, and octal radixes are valid. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0024.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0024.md index 92cf0e9e802..e43cd889199 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0024.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0024.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0024" title: "Expression Evaluator Error CXX0024" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0024" +ms.date: 11/04/2016 f1_keywords: ["CXX0024"] helpviewer_keywords: ["CXX0024", "CAN0024"] -ms.assetid: eca6adbd-8ff2-4f51-a1cc-a2e9d5d0a47d --- # Expression Evaluator Error CXX0024 -operation needs l-value +> operation needs l-value + +## Remarks An expression that does not evaluate to an l-value was specified for an operation that requires an l-value. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0025.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0025.md index 10467f5b2ab..ed2c8ec0b45 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0025.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0025.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0025" title: "Expression Evaluator Error CXX0025" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0025" +ms.date: 11/04/2016 f1_keywords: ["CXX0025"] helpviewer_keywords: ["CAN0025", "CXX0025"] -ms.assetid: 3e2fb541-63b3-46ac-9f93-3dadb253bcf6 --- # Expression Evaluator Error CXX0025 -operator needs struct/union +> operator needs struct/union + +## Remarks An operator that takes an expression of **`struct`** or **`union`** type was applied to an expression that is not a **`struct`** or **`union`**. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0026.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0026.md index ed489fd094c..2cc930c9869 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0026.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0026.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0026" title: "Expression Evaluator Error CXX0026" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0026" +ms.date: 11/04/2016 f1_keywords: ["CXX0026"] helpviewer_keywords: ["CXX0026", "CAN0026"] -ms.assetid: b5bc15f2-f179-4b87-ae88-a57e08e43bfa --- # Expression Evaluator Error CXX0026 -bad format string +> bad format string + +## Remarks A format string was improperly specified. Check the syntax of the expression. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0027.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0027.md index 20755a40dbe..d69c9d7659d 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0027.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0027.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0027" title: "Expression Evaluator Error CXX0027" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0027" +ms.date: 11/04/2016 f1_keywords: ["CXX0027"] helpviewer_keywords: ["CAN0027", "CXX0027"] -ms.assetid: 0127cfc0-c292-4923-a58b-25542343cdad --- # Expression Evaluator Error CXX0027 -tp addr not l-value +> tp addr not l-value + +## Remarks Check the syntax of the expression. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0028.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0028.md index 78d2a0aa519..8cfb6900d31 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0028.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0028.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0028" title: "Expression Evaluator Error CXX0028" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0028" +ms.date: 11/04/2016 f1_keywords: ["CXX0028"] helpviewer_keywords: ["CAN0028", "CXX0028"] -ms.assetid: 172eb81f-c0b0-43b1-b418-766f35f1a561 --- # Expression Evaluator Error CXX0028 -not struct/union element +> not struct/union element + +## Remarks An expression of the form 'Struct.Member' or 'pStruct->Member' was specified, but \ is not an element of the structure. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0029.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0029.md index 2e7ea0170bb..6ca03e1d0e0 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0029.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0029.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0029" title: "Expression Evaluator Error CXX0029" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0029" +ms.date: 11/04/2016 f1_keywords: ["CXX0029"] helpviewer_keywords: ["CXX0029", "CAN0029"] -ms.assetid: 562b2132-e9cb-4591-a5bf-bc7179a7f40e --- # Expression Evaluator Error CXX0029 -not struct pointer +> not struct pointer + +## Remarks The member-selection operator (**->**) was applied to an expression that is not a pointer to a structure. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0030.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0030.md index 64a58f4ddbf..8c980d87cca 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0030.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0030.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0030" title: "Expression Evaluator Error CXX0030" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0030" +ms.date: 11/04/2016 f1_keywords: ["CXX0030"] helpviewer_keywords: ["CAN0030", "CXX0030"] -ms.assetid: ada8b48c-09c8-49bf-ae23-313ed663c4fe --- # Expression Evaluator Error CXX0030 -expression not evaluatable +> expression not evaluatable + +## Remarks The debugger's expression evaluator could not obtain a value for the expression as written. One likely cause is that the expression refers to memory that is outside the program's address space (dereferencing a null pointer is one example). Windows does not allow access to memory that is outside of the program's address space. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0031.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0031.md index 255307a8bbf..6b95122dad0 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0031.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0031.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0031" title: "Expression Evaluator Error CXX0031" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0031" +ms.date: 11/04/2016 f1_keywords: ["CXX0031"] helpviewer_keywords: ["CAN0031", "CXX0031"] -ms.assetid: adafbcb7-982f-495f-a34d-72e95d7e54c7 --- # Expression Evaluator Error CXX0031 -expression not expandable +> expression not expandable + +## Remarks The expression evaluator encountered an internal error. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0032.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0032.md index a9902fe416c..505f99fbb2b 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0032.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0032.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0032" title: "Expression Evaluator Error CXX0032" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0032" +ms.date: 11/04/2016 f1_keywords: ["CXX0032"] helpviewer_keywords: ["CXX0032", "CAN0032"] -ms.assetid: 78f56977-6b6d-42e2-b71d-c392525bb18b --- # Expression Evaluator Error CXX0032 -divide by 0 +> divide by 0 + +## Remarks The expression contains a divisor of zero, which is illegal. This divisor may be the literal number zero, or it may be an expression that evaluates to zero. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0033.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0033.md index 198a6def252..759e150bbef 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0033.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0033.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0033" title: "Expression Evaluator Error CXX0033" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0033" +ms.date: 11/04/2016 f1_keywords: ["CXX0033"] helpviewer_keywords: ["CAN0033", "CXX0033"] -ms.assetid: 0bd62c5b-de89-481f-9b12-88fe84805afe --- # Expression Evaluator Error CXX0033 -error in OMF type information +> error in OMF type information + +## Remarks The executable file did not have a valid object module format (OMF) for debugging. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0034.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0034.md index 829dacf515a..ef6ccecab13 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0034.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0034.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0034" title: "Expression Evaluator Error CXX0034" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0034" +ms.date: 11/04/2016 f1_keywords: ["CXX0034"] helpviewer_keywords: ["CAN0034", "CXX0034"] -ms.assetid: afcee5f1-beff-489f-aea6-04f55e76364f --- # Expression Evaluator Error CXX0034 -**types incompatible with operator** +> types incompatible with operator + +## Remarks The operand types specified are not legal for the operation. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0036.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0036.md index 6c86cd2b0b7..d9f203ab553 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0036.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0036.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0036" title: "Expression Evaluator Error CXX0036" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0036" +ms.date: 11/04/2016 f1_keywords: ["CXX0036"] helpviewer_keywords: ["CXX0036", "CAN0036"] -ms.assetid: 383404be-df5b-4eec-b113-df21bb5d269d --- # Expression Evaluator Error CXX0036 -bad context {...} specification +> bad context {...} specification + +## Remarks This message can be generated by any of several errors in the use of the context operator (**{}**). diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0037.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0037.md index 48e93579abb..f09a73432f8 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0037.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0037.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0037" title: "Expression Evaluator Error CXX0037" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0037" +ms.date: 11/04/2016 f1_keywords: ["CXX0037"] helpviewer_keywords: ["CAN0037", "CXX0037"] -ms.assetid: 8059ad65-78b7-465a-98fa-387fd5873ea6 --- # Expression Evaluator Error CXX0037 -out of memory +> out of memory + +## Remarks The C expression evaluator ran out of memory evaluating the expression. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0038.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0038.md index 51969d57d34..e1dfdca5443 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0038.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0038.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0038" title: "Expression Evaluator Error CXX0038" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0038" +ms.date: 11/04/2016 f1_keywords: ["CXX0038"] helpviewer_keywords: ["CXX0038", "CAN0038"] -ms.assetid: 3327dc4e-1726-4924-a519-6ffd766a389c --- # Expression Evaluator Error CXX0038 -function argument count and/or type mismatch +> function argument count and/or type mismatch + +## Remarks The function call as specified does not match the prototype for the function. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0039.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0039.md index 8b0274bd435..b6aeebdb00f 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0039.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0039.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0039" title: "Expression Evaluator Error CXX0039" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0039" +ms.date: 11/04/2016 f1_keywords: ["CXX0039"] helpviewer_keywords: ["CXX0039", "CAN0039"] -ms.assetid: 8bf698d2-e015-4595-944f-72b81aa43d22 --- # Expression Evaluator Error CXX0039 -symbol is ambiguous +> symbol is ambiguous + +## Remarks The C expression evaluator cannot determine which instance of a symbol to use in an expression. The symbol occurs more than once in the inheritance tree. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0040.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0040.md index b1cb02f95b6..448fd76bc9e 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0040.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0040.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0040" title: "Expression Evaluator Error CXX0040" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0040" +ms.date: 11/04/2016 f1_keywords: ["CXX0040"] helpviewer_keywords: ["CXX0040", "CAN0040"] -ms.assetid: 1914e605-d80b-4abc-9e8f-dbcbefec095b --- # Expression Evaluator Error CXX0040 -function requires implicit conversion +> function requires implicit conversion + +## Remarks The C expression evaluator does not support implicit conversions involving constructor calls. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0041.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0041.md index cd956d21484..37a50b38381 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0041.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0041.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0041" title: "Expression Evaluator Error CXX0041" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0041" +ms.date: 11/04/2016 f1_keywords: ["CXX0041"] helpviewer_keywords: ["CAN0041", "CXX0041"] -ms.assetid: ce8a2366-758f-481b-8c03-ed7d779091b2 --- # Expression Evaluator Error CXX0041 -class element must be static member or member function +> class element must be static member or member function + +## Remarks A nonstatic member of a class (or structure or union) was used without specifying which instantiation of the class to use. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0043.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0043.md index 9ee2d06229f..97a455ab4d8 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0043.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0043.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0043" title: "Expression Evaluator Error CXX0043" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0043" +ms.date: 11/04/2016 f1_keywords: ["CXX0043"] helpviewer_keywords: ["CXX0043", "CAN0043"] -ms.assetid: 5e5d55bb-0f3e-40e6-b3c3-d0dfb701a65c --- # Expression Evaluator Error CXX0043 -this pointer used outside member function +> this pointer used outside member function + +## Remarks The **`this`** pointer can only be used for nonstatic member functions. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0044.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0044.md index b71528aecc9..ebb048927d8 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0044.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0044.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0044" title: "Expression Evaluator Error CXX0044" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0044" +ms.date: 11/04/2016 f1_keywords: ["CXX0044"] helpviewer_keywords: ["CXX0044", "CAN0044"] -ms.assetid: d59868b5-c1ec-46ac-91d6-5d575a4d6b49 --- # Expression Evaluator Error CXX0044 -use of _based(void) pointer requires :> operator +> use of _based(void) pointer requires :> operator + +## Remarks A pointer based on **`void`** cannot be used directly. You must form a complete pointer using the **:>** operator. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0045.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0045.md index b6e4004e883..1bf5578f642 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0045.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0045.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0045" title: "Expression Evaluator Error CXX0045" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0045" +ms.date: 11/04/2016 f1_keywords: ["CXX0045"] helpviewer_keywords: ["CXX0045", "CAN0045"] -ms.assetid: 32181bc8-e79c-4ad7-a82f-47c62ec06d7d --- # Expression Evaluator Error CXX0045 -not a function +> not a function + +## Remarks An argument list was supplied for a symbol in the program that is not the name of a function. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0046.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0046.md index cd6e216b644..e3d1398c1d7 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0046.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0046.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0046" title: "Expression Evaluator Error CXX0046" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0046" +ms.date: 11/04/2016 f1_keywords: ["CXX0046"] helpviewer_keywords: ["CXX0046", "CAN0046"] -ms.assetid: a76e657b-c018-415b-b426-ce9e72eb645d --- # Expression Evaluator Error CXX0046 -argument list required for member function +> argument list required for member function + +## Remarks An expression called a member function but did not specify any actual parameters. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0047.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0047.md index 09112a2f074..ac89429f3cf 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0047.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0047.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0047" title: "Expression Evaluator Error CXX0047" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0047" +ms.date: 11/04/2016 f1_keywords: ["CXX0047"] helpviewer_keywords: ["CAN0047", "CXX0047"] -ms.assetid: db23d0db-fce2-4d86-b391-6e1d6ad13fd4 --- # Expression Evaluator Error CXX0047 -argument list does not match a function +> argument list does not match a function + +## Remarks An expression called a function with an actual parameter list that did not match the formal parameter list of any function with the same name defined in the program. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0048.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0048.md index 5effef18e61..c081babcfb8 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0048.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0048.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0048" title: "Expression Evaluator Error CXX0048" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0048" +ms.date: 11/04/2016 f1_keywords: ["CXX0048"] helpviewer_keywords: ["CAN0048", "CXX0048"] -ms.assetid: 294416f9-5e38-4450-8713-c13bcbaaf615 --- # Expression Evaluator Error CXX0048 -calling sequence not supported +> calling sequence not supported + +## Remarks A function specified in the expression uses a calling sequence not supported by the C expression evaluator. You cannot call this function in a Watch window expression. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0049.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0049.md index 621a8825611..a064fa348cd 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0049.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0049.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0049" title: "Expression Evaluator Error CXX0049" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0049" +ms.date: 11/04/2016 f1_keywords: ["CXX0049"] helpviewer_keywords: ["CXX0049", "CAN0049"] -ms.assetid: 6dcfece4-39ed-489d-b7be-2a17c7b94656 --- # Expression Evaluator Error CXX0049 -obsolete OMF - please relink program +> obsolete OMF - please relink program + +## Remarks The program used an old OMF (Object Module Format). diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0050.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0050.md index e096ec70438..689436e2b00 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0050.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0050.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0050" title: "Expression Evaluator Error CXX0050" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0050" +ms.date: 11/04/2016 f1_keywords: ["CXX0050"] helpviewer_keywords: ["CAN0050", "CXX0050"] -ms.assetid: 214cd193-c6dc-41b9-9ebe-5a4b1689d3ab --- # Expression Evaluator Error CXX0050 -left side of :: must be class/struct/union +> left side of :: must be class/struct/union + +## Remarks The symbol on the left side of the scope-resolution operator (`::`) was not a class, structure, or union. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0051.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0051.md index 5b1d1ec0327..fc6eec58a37 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0051.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0051.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0051" title: "Expression Evaluator Error CXX0051" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0051" +ms.date: 11/04/2016 f1_keywords: ["CXX0051"] helpviewer_keywords: ["CAN0051", "CXX0051"] -ms.assetid: 031cd2ed-d9bb-4aa5-9858-71581bcca49c --- # Expression Evaluator Error CXX0051 -more than one overloaded symbol specified in breakpoint +> more than one overloaded symbol specified in breakpoint + +## Remarks The expression evaluator could not determine which of more than one overloaded symbol to use as a breakpoint. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0052.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0052.md index d8b78b97660..dc68472dc00 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0052.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0052.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0052" title: "Expression Evaluator Error CXX0052" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0052" +ms.date: 11/04/2016 f1_keywords: ["CXX0052"] helpviewer_keywords: ["CXX0052", "CAN0052"] -ms.assetid: 5060d479-d0a4-4682-b858-c8b9a4f324e6 --- # Expression Evaluator Error CXX0052 -member function not present +> member function not present + +## Remarks A member function was specified as a breakpoint but could not be found. Setting a breakpoint at a function that has been inlined can cause this error. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0053.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0053.md index 7760402f7fc..377bf54a6d7 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0053.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0053.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0053" title: "Expression Evaluator Error CXX0053" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0053" +ms.date: 11/04/2016 f1_keywords: ["CXX0053"] helpviewer_keywords: ["CAN0053", "CXX0053"] -ms.assetid: fe74ed9e-9241-4df1-881f-104348e296c6 --- # Expression Evaluator Error CXX0053 -nonfunction symbol match while binding breakpoints +> nonfunction symbol match while binding breakpoints + +## Remarks A symbol used as a breakpoint was not a function. Specifying a data member as a breakpoint can cause this error. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0054.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0054.md index 2e504742e30..d8c42073585 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0054.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0054.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0054" title: "Expression Evaluator Error CXX0054" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0054" +ms.date: 11/04/2016 f1_keywords: ["CXX0054"] helpviewer_keywords: ["CXX0054", "CAN0054"] -ms.assetid: d5d4a093-6a7a-45c0-8aa7-e555023353ef --- # Expression Evaluator Error CXX0054 -register in breakpoint expression illegal +> register in breakpoint expression illegal + +## Remarks A register cannot be used in a breakpoint expression. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0055.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0055.md index 3a625d08968..c0539bf5118 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0055.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0055.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0055" title: "Expression Evaluator Error CXX0055" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0055" +ms.date: 11/04/2016 f1_keywords: ["CXX0055"] helpviewer_keywords: ["CAN0055", "CXX0055"] -ms.assetid: bb2a81f9-35ea-4b02-a49e-6b2c7023aebd --- # Expression Evaluator Error CXX0055 -ambiguous symbol in context operator +> ambiguous symbol in context operator + +## Remarks A symbol in the context operator (**{}**) referred to more than one symbol in the program. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0056.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0056.md index 5c0937c856a..2c5f48a2a20 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0056.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0056.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0056" title: "Expression Evaluator Error CXX0056" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0056" +ms.date: 11/04/2016 f1_keywords: ["CXX0056"] helpviewer_keywords: ["CXX0056", "CAN0056"] -ms.assetid: a67c90e0-933c-43f2-a548-0ba272920331 --- # Expression Evaluator Error CXX0056 -error in line number +> error in line number + +## Remarks An invalid line number was specified. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0057.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0057.md index b3fec54b4e8..5b31455260d 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0057.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0057.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0057" title: "Expression Evaluator Error CXX0057" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0057" +ms.date: 11/04/2016 f1_keywords: ["CXX0057"] helpviewer_keywords: ["CAN0057", "CXX0057"] -ms.assetid: b1a86998-c642-4061-9f37-9c493f3852cc --- # Expression Evaluator Error CXX0057 -no code at line number +> no code at line number + +## Remarks No code was generated for the specified line number. It cannot be used as a breakpoint. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0058.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0058.md index 01b1de640fd..e96576696fb 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0058.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0058.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0058" title: "Expression Evaluator Error CXX0058" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0058" +ms.date: 11/04/2016 f1_keywords: ["CXX0058"] helpviewer_keywords: ["CXX0058", "CAN0058"] -ms.assetid: b6246c6e-5845-4ad5-ac2a-e6c4faf8f3f9 --- # Expression Evaluator Error CXX0058 -overloaded operator not found +> overloaded operator not found + +## Remarks A class type was specified as the left operand in an expression, but an overloaded operator was not defined for the class. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0059.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0059.md index bf9ea31ecda..67c0a953c68 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0059.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0059.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0059" title: "Expression Evaluator Error CXX0059" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0059" +ms.date: 11/04/2016 f1_keywords: ["CXX0059"] helpviewer_keywords: ["CXX0059", "CAN0059"] -ms.assetid: e8bdcb74-1315-4083-b24d-e47eac7d1ec0 --- # Expression Evaluator Error CXX0059 -left operand is class not a function name +> left operand is class not a function name + +## Remarks The left operand of a function call was a class name and could not be resolved to a function call. Omitting the name of a member function in an expression can cause this error. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0060.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0060.md index d4796731c77..e3daf580ae6 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0060.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0060.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0060" title: "Expression Evaluator Error CXX0060" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0060" +ms.date: 11/04/2016 f1_keywords: ["CXX0060"] helpviewer_keywords: ["CAN0060", "CXX0060"] -ms.assetid: 40c0ff02-ca6b-4232-b1e3-1f3a213ee2a3 --- # Expression Evaluator Error CXX0060 -register is not available +> register is not available + +## Remarks An expression specified a register that cannot be used. This error can be caused by trying to access a register that does not exist on the machine running. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0061.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0061.md index 7afc6294ae4..35275227563 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0061.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0061.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0061" title: "Expression Evaluator Error CXX0061" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0061" +ms.date: 11/04/2016 f1_keywords: ["CXX0061"] helpviewer_keywords: ["CXX0061", "CAN0061"] -ms.assetid: fa84dcca-87ef-4546-9dce-636ed39e0713 --- # Expression Evaluator Error CXX0061 -function nesting depth exceeded +> function nesting depth exceeded + +## Remarks The expression contains a function nesting depth greater than the limit. Modify the expression to reduce the nesting depth. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0062.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0062.md index 72ec432ce17..3265d6746bc 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0062.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0062.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0062" title: "Expression Evaluator Error CXX0062" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0062" +ms.date: 11/04/2016 f1_keywords: ["CXX0062"] helpviewer_keywords: ["CAN0062", "CGopherFile class, operations"] -ms.assetid: 8e4165c4-7753-4f45-90e9-4542cbb9fc7a --- # Expression Evaluator Error CXX0062 -constructor calls not supported +> constructor calls not supported + +## Remarks An expression made a call to a constructor. Expressions cannot make explicit calls to constructors or make conversions that require a call to a constructor. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0063.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0063.md index 34e824c32bd..4e753d841e6 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0063.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0063.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0063" title: "Expression Evaluator Error CXX0063" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0063" +ms.date: 11/04/2016 f1_keywords: ["CXX0063"] helpviewer_keywords: ["CXX0063", "CAN0063"] -ms.assetid: 2e131b7a-9c8f-4aa1-acac-8d87f602c24c --- # Expression Evaluator Error CXX0063 -overloaded operator -> not supported +> overloaded operator -> not supported + +## Remarks The expression used an overloaded class member access operator (**->**). diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0064.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0064.md index 74c67df4ac8..ceebc4c6727 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0064.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0064.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0064" title: "Expression Evaluator Error CXX0064" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0064" +ms.date: 11/04/2016 f1_keywords: ["CXX0064"] helpviewer_keywords: ["CAN0064", "CXX0064"] -ms.assetid: aa509e71-0616-41ca-a94e-6c376b041e57 --- # Expression Evaluator Error CXX0064 -can't set breakpoint on bound virtual member function +> can't set breakpoint on bound virtual member function + +## Example A breakpoint was set on a virtual member function through a pointer to an object, such as: diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0065.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0065.md index f768cdc47b6..494f6ff1bfc 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0065.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0065.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0065" title: "Expression Evaluator Error CXX0065" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0065" +ms.date: 11/04/2016 f1_keywords: ["CXX0065"] helpviewer_keywords: ["CAN0065", "CXX0065"] -ms.assetid: aac68f87-0b90-4c19-afa6-1c587625a5fd --- # Expression Evaluator Error CXX0065 -variable needs stack frame +> variable needs stack frame + +## Remarks An expression contained a variable that exists within the current scope but hasn't been created yet. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0066.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0066.md index 0ef4bf1d8c0..e31743fe4a9 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0066.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0066.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0066" title: "Expression Evaluator Error CXX0066" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0066" +ms.date: 11/04/2016 f1_keywords: ["CXX0066"] helpviewer_keywords: ["CXX0066", "CAN0066"] -ms.assetid: 1321e4e1-b441-424b-9e76-c208d4a6f6ea --- # Expression Evaluator Error CXX0066 -static member not present +> static member not present + +## Remarks A static member of a class could not be found or was not defined. This error can result from a static class member that is declared but not defined, or is only defined and referenced in modules that do not contain debug information. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0067.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0067.md index daa7e12991d..27d75853cce 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0067.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0067.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0067" title: "Expression Evaluator Error CXX0067" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0067" +ms.date: 11/04/2016 f1_keywords: ["CXX0067"] helpviewer_keywords: ["CXX0067", "CAN0067"] -ms.assetid: 9a3e642b-4746-41ac-b665-bd98a6fa0cb3 --- # Expression Evaluator Error CXX0067 -function evaluation not supported +> function evaluation not supported + +## Remarks The expression contained a function call. Some expression evaluators do not support function calls. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0069.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0069.md index 70808d356e4..0fefde08dbf 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0069.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0069.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0069" title: "Expression Evaluator Error CXX0069" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0069" +ms.date: 11/04/2016 f1_keywords: ["CXX0069"] helpviewer_keywords: ["CXX0069"] -ms.assetid: cf334b23-1e17-4d37-acc5-18597ee84164 --- # Expression Evaluator Error CXX0069 -variable needs stack frame +> variable needs stack frame + +## Remarks The expression evaluator cannot evaluate the variable because it does not occur in a stack frame. This may be caused by variables declared as part of an inline function. diff --git a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0072.md b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0072.md index b731c03e1db..e7abb58a2dd 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-error-cxx0072.md +++ b/docs/error-messages/tool-errors/expression-evaluator-error-cxx0072.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Expression Evaluator Error CXX0072" title: "Expression Evaluator Error CXX0072" -ms.date: "11/04/2016" +description: "Learn more about: Expression Evaluator Error CXX0072" +ms.date: 11/04/2016 f1_keywords: ["CXX0072"] helpviewer_keywords: ["CAN0072", "CXX0072"] -ms.assetid: fd04e197-cfa9-4097-a070-8fa2111e876d --- # Expression Evaluator Error CXX0072 -Error: type information missing or unknown +> Error: type information missing or unknown + +## Remarks The .pch file did not get linked in, or the code has a reference to a type that is in a module not compiled with /Zi. diff --git a/docs/error-messages/tool-errors/expression-evaluator-errors-cxx0000-through-cxx0072.md b/docs/error-messages/tool-errors/expression-evaluator-errors-cxx0000-through-cxx0072.md index 3347b385f8a..a35f769cf05 100644 --- a/docs/error-messages/tool-errors/expression-evaluator-errors-cxx0000-through-cxx0072.md +++ b/docs/error-messages/tool-errors/expression-evaluator-errors-cxx0000-through-cxx0072.md @@ -1,84 +1,85 @@ --- -description: "Learn more about: Expression evaluator errors (CXXxxxx)" title: "Expression evaluator errors" -ms.date: "04/16/2019" -ms.assetid: a47a9866-7fb2-4b21-978c-2b77402c7105 +description: "Learn more about: Expression evaluator errors (CXXxxxx)" +ms.date: 04/16/2019 --- # Expression evaluator errors (CXXxxxx) This section is a reference to the errors generated by the debugger and diagnostics tools. These tools generate errors of the form CXX*xxxx* or CAN*xxxx*, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Expression evaluator error messages -[Expression evaluator error CXX0000](expression-evaluator-error-cxx0000.md) \ -[Expression evaluator error CXX0001](expression-evaluator-error-cxx0001.md) \ -[Expression evaluator error CXX0002](expression-evaluator-error-cxx0002.md) \ -[Expression evaluator error CXX0004](expression-evaluator-error-cxx0004.md) \ -[Expression evaluator error CXX0005](expression-evaluator-error-cxx0005.md) \ -[Expression evaluator error CXX0006](expression-evaluator-error-cxx0006.md) \ -[Expression evaluator error CXX0007](expression-evaluator-error-cxx0007.md) \ -[Expression evaluator error CXX0008](expression-evaluator-error-cxx0008.md) \ -[Expression evaluator error CXX0009](expression-evaluator-error-cxx0009.md) \ -[Expression evaluator error CXX0010](expression-evaluator-error-cxx0010.md) \ -[Expression evaluator error CXX0011](expression-evaluator-error-cxx0011.md) \ -[Expression evaluator error CXX0012](expression-evaluator-error-cxx0012.md) \ -[Expression evaluator error CXX0013](expression-evaluator-error-cxx0013.md) \ -[Expression evaluator error CXX0014](expression-evaluator-error-cxx0014.md) \ -[Expression evaluator error CXX0015](expression-evaluator-error-cxx0015.md) \ -[Expression evaluator error CXX0016](expression-evaluator-error-cxx0016.md) \ -[Expression evaluator error CXX0017](expression-evaluator-error-cxx0017.md) \ -[Expression evaluator error CXX0018](expression-evaluator-error-cxx0018.md) \ -[Expression evaluator error CXX0019](expression-evaluator-error-cxx0019.md) \ -[Expression evaluator error CXX0020](expression-evaluator-error-cxx0020.md) \ -[Expression evaluator error CXX0021](expression-evaluator-error-cxx0021.md) \ -[Expression evaluator error CXX0022](expression-evaluator-error-cxx0022.md) \ -[Expression evaluator error CXX0023](expression-evaluator-error-cxx0023.md) \ -[Expression evaluator error CXX0024](expression-evaluator-error-cxx0024.md) \ -[Expression evaluator error CXX0025](expression-evaluator-error-cxx0025.md) \ -[Expression evaluator error CXX0026](expression-evaluator-error-cxx0026.md) \ -[Expression evaluator error CXX0027](expression-evaluator-error-cxx0027.md) \ -[Expression evaluator error CXX0028](expression-evaluator-error-cxx0028.md) \ -[Expression evaluator error CXX0029](expression-evaluator-error-cxx0029.md) \ -[Expression evaluator error CXX0030](expression-evaluator-error-cxx0030.md) \ -[Expression evaluator error CXX0031](expression-evaluator-error-cxx0031.md) \ -[Expression evaluator error CXX0032](expression-evaluator-error-cxx0032.md) \ -[Expression evaluator error CXX0033](expression-evaluator-error-cxx0033.md) \ -[Expression evaluator error CXX0034](expression-evaluator-error-cxx0034.md) \ -[Expression evaluator error CXX0036](expression-evaluator-error-cxx0036.md) \ -[Expression evaluator error CXX0037](expression-evaluator-error-cxx0037.md) \ -[Expression evaluator error CXX0038](expression-evaluator-error-cxx0038.md) \ -[Expression evaluator error CXX0039](expression-evaluator-error-cxx0039.md) \ -[Expression evaluator error CXX0040](expression-evaluator-error-cxx0040.md) \ -[Expression evaluator error CXX0041](expression-evaluator-error-cxx0041.md) \ -[Expression evaluator error CXX0043](expression-evaluator-error-cxx0043.md) \ -[Expression evaluator error CXX0044](expression-evaluator-error-cxx0044.md) \ -[Expression evaluator error CXX0045](expression-evaluator-error-cxx0045.md) \ -[Expression evaluator error CXX0046](expression-evaluator-error-cxx0046.md) \ -[Expression evaluator error CXX0047](expression-evaluator-error-cxx0047.md) \ -[Expression evaluator error CXX0048](expression-evaluator-error-cxx0048.md) \ -[Expression evaluator error CXX0049](expression-evaluator-error-cxx0049.md) \ -[Expression evaluator error CXX0050](expression-evaluator-error-cxx0050.md) \ -[Expression evaluator error CXX0051](expression-evaluator-error-cxx0051.md) \ -[Expression evaluator error CXX0052](expression-evaluator-error-cxx0052.md) \ -[Expression evaluator error CXX0053](expression-evaluator-error-cxx0053.md) \ -[Expression evaluator error CXX0054](expression-evaluator-error-cxx0054.md) \ -[Expression evaluator error CXX0055](expression-evaluator-error-cxx0055.md) \ -[Expression evaluator error CXX0056](expression-evaluator-error-cxx0056.md) \ -[Expression evaluator error CXX0057](expression-evaluator-error-cxx0057.md) \ -[Expression evaluator error CXX0058](expression-evaluator-error-cxx0058.md) \ -[Expression evaluator error CXX0059](expression-evaluator-error-cxx0059.md) \ -[Expression evaluator error CXX0060](expression-evaluator-error-cxx0060.md) \ -[Expression evaluator error CXX0061](expression-evaluator-error-cxx0061.md) \ -[Expression evaluator error CXX0062](expression-evaluator-error-cxx0062.md) \ -[Expression evaluator error CXX0063](expression-evaluator-error-cxx0063.md) \ -[Expression evaluator error CXX0064](expression-evaluator-error-cxx0064.md) \ -[Expression evaluator error CXX0065](expression-evaluator-error-cxx0065.md) \ -[Expression evaluator error CXX0066](expression-evaluator-error-cxx0066.md) \ -[Expression evaluator error CXX0067](expression-evaluator-error-cxx0067.md) \ -[Expression evaluator error CXX0069](expression-evaluator-error-cxx0069.md) \ -[Expression evaluator error CXX0072](expression-evaluator-error-cxx0072.md) +| Error | Message | +|--|--| +| [Expression evaluator error CXX0000](expression-evaluator-error-cxx0000.md) | no error condition | +| [Expression evaluator error CXX0001](expression-evaluator-error-cxx0001.md) | exception executing user function | +| [Expression evaluator error CXX0002](expression-evaluator-error-cxx0002.md) | error accessing user memory | +| [Expression evaluator error CXX0004](expression-evaluator-error-cxx0004.md) | syntax error | +| [Expression evaluator error CXX0005](expression-evaluator-error-cxx0005.md) | operator not supported | +| [Expression evaluator error CXX0006](expression-evaluator-error-cxx0006.md) | missing left parenthesis | +| [Expression evaluator error CXX0007](expression-evaluator-error-cxx0007.md) | missing right parenthesis | +| [Expression evaluator error CXX0008](expression-evaluator-error-cxx0008.md) | missing " at end of string | +| [Expression evaluator error CXX0009](expression-evaluator-error-cxx0009.md) | missing ' after character constant | +| [Expression evaluator error CXX0010](expression-evaluator-error-cxx0010.md) | missing left bracket | +| [Expression evaluator error CXX0011](expression-evaluator-error-cxx0011.md) | missing right bracket | +| [Expression evaluator error CXX0012](expression-evaluator-error-cxx0012.md) | missing left curly brace | +| [Expression evaluator error CXX0013](expression-evaluator-error-cxx0013.md) | missing operator | +| [Expression evaluator error CXX0014](expression-evaluator-error-cxx0014.md) | missing operand | +| [Expression evaluator error CXX0015](expression-evaluator-error-cxx0015.md) | expression too complex (stack overflow) | +| [Expression evaluator error CXX0016](expression-evaluator-error-cxx0016.md) | constant too big | +| [Expression evaluator error CXX0017](expression-evaluator-error-cxx0017.md) | symbol not found | +| [Expression evaluator error CXX0018](expression-evaluator-error-cxx0018.md) | bad register name | +| [Expression evaluator error CXX0019](expression-evaluator-error-cxx0019.md) | bad type cast | +| [Expression evaluator error CXX0020](expression-evaluator-error-cxx0020.md) | operand types bad for this operation | +| [Expression evaluator error CXX0021](expression-evaluator-error-cxx0021.md) | struct or union used as scalar | +| [Expression evaluator error CXX0022](expression-evaluator-error-cxx0022.md) | function call before _main | +| [Expression evaluator error CXX0023](expression-evaluator-error-cxx0023.md) | bad radix | +| [Expression evaluator error CXX0024](expression-evaluator-error-cxx0024.md) | operation needs l-value | +| [Expression evaluator error CXX0025](expression-evaluator-error-cxx0025.md) | operator needs struct/union | +| [Expression evaluator error CXX0026](expression-evaluator-error-cxx0026.md) | bad format string | +| [Expression evaluator error CXX0027](expression-evaluator-error-cxx0027.md) | tp addr not l-value | +| [Expression evaluator error CXX0028](expression-evaluator-error-cxx0028.md) | not struct/union element | +| [Expression evaluator error CXX0029](expression-evaluator-error-cxx0029.md) | not struct pointer | +| [Expression evaluator error CXX0030](expression-evaluator-error-cxx0030.md) | expression not evaluatable | +| [Expression evaluator error CXX0031](expression-evaluator-error-cxx0031.md) | expression not expandable | +| [Expression evaluator error CXX0032](expression-evaluator-error-cxx0032.md) | divide by 0 | +| [Expression evaluator error CXX0033](expression-evaluator-error-cxx0033.md) | error in OMF type information | +| [Expression evaluator error CXX0034](expression-evaluator-error-cxx0034.md) | types incompatible with operator | +| [Expression evaluator error CXX0036](expression-evaluator-error-cxx0036.md) | bad context {...} specification | +| [Expression evaluator error CXX0037](expression-evaluator-error-cxx0037.md) | out of memory | +| [Expression evaluator error CXX0038](expression-evaluator-error-cxx0038.md) | function argument count and/or type mismatch | +| [Expression evaluator error CXX0039](expression-evaluator-error-cxx0039.md) | symbol is ambiguous | +| [Expression evaluator error CXX0040](expression-evaluator-error-cxx0040.md) | function requires implicit conversion | +| [Expression evaluator error CXX0041](expression-evaluator-error-cxx0041.md) | class element must be static member or member function | +| [Expression evaluator error CXX0043](expression-evaluator-error-cxx0043.md) | this pointer used outside member function | +| [Expression evaluator error CXX0044](expression-evaluator-error-cxx0044.md) | use of _based(void) pointer requires :> operator | +| [Expression evaluator error CXX0045](expression-evaluator-error-cxx0045.md) | not a function | +| [Expression evaluator error CXX0046](expression-evaluator-error-cxx0046.md) | argument list required for member function | +| [Expression evaluator error CXX0047](expression-evaluator-error-cxx0047.md) | argument list does not match a function | +| [Expression evaluator error CXX0048](expression-evaluator-error-cxx0048.md) | calling sequence not supported | +| [Expression evaluator error CXX0049](expression-evaluator-error-cxx0049.md) | obsolete OMF - please relink program | +| [Expression evaluator error CXX0050](expression-evaluator-error-cxx0050.md) | left side of :: must be class/struct/union | +| [Expression evaluator error CXX0051](expression-evaluator-error-cxx0051.md) | more than one overloaded symbol specified in breakpoint | +| [Expression evaluator error CXX0052](expression-evaluator-error-cxx0052.md) | member function not present | +| [Expression evaluator error CXX0053](expression-evaluator-error-cxx0053.md) | nonfunction symbol match while binding breakpoints | +| [Expression evaluator error CXX0054](expression-evaluator-error-cxx0054.md) | register in breakpoint expression illegal | +| [Expression evaluator error CXX0055](expression-evaluator-error-cxx0055.md) | ambiguous symbol in context operator | +| [Expression evaluator error CXX0056](expression-evaluator-error-cxx0056.md) | error in line number | +| [Expression evaluator error CXX0057](expression-evaluator-error-cxx0057.md) | no code at line number | +| [Expression evaluator error CXX0058](expression-evaluator-error-cxx0058.md) | overloaded operator not found | +| [Expression evaluator error CXX0059](expression-evaluator-error-cxx0059.md) | left operand is class not a function name | +| [Expression evaluator error CXX0060](expression-evaluator-error-cxx0060.md) | register is not available | +| [Expression evaluator error CXX0061](expression-evaluator-error-cxx0061.md) | function nesting depth exceeded | +| [Expression evaluator error CXX0062](expression-evaluator-error-cxx0062.md) | constructor calls not supported | +| [Expression evaluator error CXX0063](expression-evaluator-error-cxx0063.md) | overloaded operator -> not supported | +| [Expression evaluator error CXX0064](expression-evaluator-error-cxx0064.md) | can't set breakpoint on bound virtual member function | +| [Expression evaluator error CXX0065](expression-evaluator-error-cxx0065.md) | variable needs stack frame | +| [Expression evaluator error CXX0066](expression-evaluator-error-cxx0066.md) | static member not present | +| [Expression evaluator error CXX0067](expression-evaluator-error-cxx0067.md) | function evaluation not supported | +| [Expression evaluator error CXX0069](expression-evaluator-error-cxx0069.md) | variable needs stack frame | +| [Expression evaluator error CXX0072](expression-evaluator-error-cxx0072.md) | Error: type information missing or unknown | ## See also diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1000.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1000.md index 31e9114a632..d769aac9547 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1000.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1000.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Error LNK1000" title: "Linker Tools Error LNK1000" -ms.date: "06/18/2018" +description: "Learn more about: Linker Tools Error LNK1000" +ms.date: 06/18/2018 f1_keywords: ["LNK1000"] helpviewer_keywords: ["LNK1000"] -ms.assetid: 86421b9a-460a-4285-8dce-9b8257d78122 --- # Linker Tools Error LNK1000 > unknown error; consult documentation for technical support options +## Remarks + Note the circumstances of the error, then try to isolate the problem and create a reproducible test case. For information on how to investigate and report these errors, see [How to report a problem with the Visual C++ toolset or documentation](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md). You may get this error if you mix standard header files (for example, Windows.h) and your own files. Include a precompiled header, if any, first, then the standard headers, followed by your own header files. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1103.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1103.md index 69a19334cb3..f49a578deee 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1103.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1103.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1103" title: "Linker Tools Error LNK1103" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1103" +ms.date: 11/04/2016 f1_keywords: ["LNK1103"] helpviewer_keywords: ["LNK1103"] -ms.assetid: c8e9bc54-6a71-471c-899e-6f98122ee3c4 --- # Linker Tools Error LNK1103 -debugging information corrupt; recompile module +> debugging information corrupt; recompile module + +## Remarks This error can be caused because the compilation was terminated before a valid object file was created. 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 a54749be023..cade1e6b606 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1104.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1104.md @@ -1,15 +1,16 @@ --- title: "Linker Tools Error LNK1104" description: "Describes the Microsoft C and C++ (MSVC) linker error LNK1104, its causes, and possible solutions." -ms.date: "12/13/2019" +ms.date: 12/13/2019 f1_keywords: ["LNK1104"] helpviewer_keywords: ["LNK1104"] -ms.assetid: 9ca6f929-0efc-4055-8354-3cf5b4e636dc --- # Linker Tools Error LNK1104 > cannot open file '*filename*' +## Remarks + This error is reported when the linker fails to open a file, either for reading or for writing. The two most common causes of the issue are: - your program is already running or is loaded in the debugger, and @@ -20,9 +21,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 +33,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 +97,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 +105,15 @@ When you specify individual libraries in the **Additional Dependencies** propert ### Paths that are too long -You may see this error when the path for *filename* expands to more than 260 characters. If needed, rearrange your directory structure or shorten your folder and file names to shorten the paths. +You might see this error when the path for *filename* expands to more than 260 characters. If needed, rearrange your directory structure or shorten your folder and file names to shorten the paths. ### Files that are too large -This error can occur because the file is too large. Libraries or object files more than a gigabyte in size may cause problems for the 32-bit linker. A possible fix for this issue is to use the 64-bit toolset. For more information on how to use the 64-bit toolset at the command line, see [How to: Enable a 64-Bit Visual C++ Toolset on the Command Line](../../build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md). For information on how to use the 64-bit toolset in the IDE, see [Using MSBuild with the 64-bit Compiler and Tools](../../build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md#using-msbuild-to-build-your-project). Also see this Stack Overflow post: [How to make Visual Studio use the native amd64 toolchain](https://stackoverflow.com/questions/19820718/how-to-make-visual-studio-use-the-native-amd64-toolchain/23793055). +This error can occur because the file is too large. Libraries or object files more than a gigabyte in size might cause problems for the 32-bit linker. A possible fix for this issue is to use the 64-bit toolset. For more information on how to use the 64-bit toolset at the command line, see [How to: Enable a 64-Bit Visual C++ Toolset on the Command Line](../../build/how-to-enable-a-64-bit-visual-cpp-toolset-on-the-command-line.md). For information on how to use the 64-bit toolset in the IDE, see [Using MSBuild with the 64-bit Compiler and Tools](../../build/walkthrough-using-msbuild-to-create-a-visual-cpp-project.md#using-msbuild-to-build-your-project). Also see this Stack Overflow post: [How to make Visual Studio use the native amd64 toolchain](https://stackoverflow.com/questions/19820718/how-to-make-visual-studio-use-the-native-amd64-toolchain/23793055). ### Incorrect file permissions -This error can occur if you have insufficient file permissions to access *filename*. It may happen if you use an ordinary user account to access library files in protected system directories. Or, if you use files copied from other users that still have their original permissions set. To fix this issue, move the file to a writeable project directory. If the moved file has inaccessible permissions, run the takeown.exe command in an Administrator command window to take ownership of the file. +This error can occur if you have insufficient file permissions to access *filename*. It might happen if you use an ordinary user account to access library files in protected system directories. Or, if you use files copied from other users that still have their original permissions set. To fix this issue, move the file to a writeable project directory. If the moved file has inaccessible permissions, run the takeown.exe command in an Administrator command window to take ownership of the file. ### Insufficient disk space @@ -120,10 +121,10 @@ The error can occur when you don't have enough disk space. The linker uses tempo ### Problems in the TMP environment variable -If the *filename* is named LNK*nnn*, it's a filename generated by the linker for a temporary file. The directory specified in the TMP environment variable may not exist. Or, more than one directory may be specified for the TMP environment variable. Only one directory path should be specified for the TMP environment variable. +If the *filename* is named LNK*nnn*, it's a filename generated by the linker for a temporary file. The directory specified in the TMP environment variable might not exist. Or, more than one directory might be specified for the TMP environment variable. Only one directory path should be specified for the TMP environment variable. ## Help, my issue isn't listed here! -When none of the issues listed here apply, you can use the feedback tools in Visual Studio for help. In the IDE, go to the menu bar and choose **Help > Send Feedback > Report a Problem**. Or, submit a suggestion by using **Help > Send Feedback > Send a Suggestion**. You can also use the [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html) site for questions, and the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) website. Use these sites to search for answers to questions and ask for help. For more information, see [How to report a problem with the Visual C++ toolset or documentation](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md). +When none of the issues listed here apply, you can use the feedback tools in Visual Studio for help. In the IDE, go to the menu bar and choose **Help > Send Feedback > Report a Problem**. Or, submit a suggestion by using **Help > Send Feedback > Send a Suggestion**. You can also use the [Microsoft Learn Q&A](/answers/topics/c%2B%2B.html) site for questions, and the Visual Studio C++ [Developer Community](https://aka.ms/vsfeedback/browsecpp) website. Use these sites to search for answers to questions and ask for help. For more information, see [How to report a problem with the Visual C++ toolset or documentation](../../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md). If you've discovered a new way to fix this issue that we should add to this article, let us know. You can send us feedback by using the button below for **This page**. Use it to create a new issue in our [C++ documentation GitHub repo](https://github.com/MicrosoftDocs/cpp-docs/issues). Thanks! diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1106.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1106.md index f1227a53aa8..662214bd59b 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1106.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1106.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1106" title: "Linker Tools Error LNK1106" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1106" +ms.date: 11/04/2016 f1_keywords: ["LNK1106"] helpviewer_keywords: ["LNK1106"] -ms.assetid: 528f7e65-04be-4966-b8af-9276837c7cda --- # Linker Tools Error LNK1106 -invalid file or disk full: cannot seek to location +> invalid file or disk full: cannot seek to location + +## Remarks The tool could not read or write to `location` in a memory-mapped file. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1107.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1107.md index af391885733..75ae3cc8c30 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1107.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1107.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Linker tools error LNK1107" title: "Linker tools error LNK1107" +description: "Learn more about: Linker tools error LNK1107" ms.date: 12/10/2021 f1_keywords: ["LNK1107"] helpviewer_keywords: ["LNK1107"] @@ -9,10 +9,10 @@ helpviewer_keywords: ["LNK1107"] > invalid or corrupt file: cannot read at location *address* -The tool couldn't read the file. The file may be corrupt, or have an unexpected file type. - ## Remarks +The tool couldn't read the file. The file may be corrupt, or have an unexpected file type. + LNK1107 can occur if a file passed to the linker or related tools is corrupt. To resolve this issue, rebuild the file. LNK1107 can also occur if your build process puts an unexpected file type in the list of files passed to the tool. The linker and related tools expect to work on specific file types. For example, the linker can use object files, library files, compiled resources, and manifests to create an executable. It can't create an executable by using source files or DLLs. To resolve this issue, verify that your build process passes only the expected file types to the tool. For example, pass *`.obj`*, *`.lib`*, and *`.res`* files, not *`.cpp`*, *`.h`*, *`.dll`*, or *`.rc`* files. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md index 0e62d587977..67286e66572 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1112.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Error LNK1112" title: "Linker Tools Error LNK1112" +description: "Learn more about: Linker Tools Error LNK1112" ms.date: 05/23/2022 f1_keywords: ["LNK1112"] helpviewer_keywords: ["LNK1112"] -ms.assetid: 425793d8-37e6-4072-9b6e-c3d4e9c12562 --- # Linker Tools Error LNK1112 diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1113.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1113.md index aaafcbbcded..feb9df5031f 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1113.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1113.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1113" title: "Linker Tools Error LNK1113" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1113" +ms.date: 11/04/2016 f1_keywords: ["LNK1113"] helpviewer_keywords: ["LNK1113"] -ms.assetid: 269ff166-b143-48e9-bdf7-db6a0db59fe4 --- # Linker Tools Error LNK1113 -invalid machine type type +> invalid machine type type + +## Remarks The machine type specified in the object header is not valid. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1120.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1120.md index 62a290603e5..852a5668232 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1120.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1120.md @@ -1,15 +1,16 @@ --- title: "Linker tools error LNK1120" description: "Describes the LNK1120 linker error, which reports the number of unresolved external symbol errors in the link." -ms.date: "10/31/2019" +ms.date: 10/31/2019 f1_keywords: ["LNK1120"] helpviewer_keywords: ["LNK1120"] -ms.assetid: 56aa7d36-921f-4daf-b44d-cca0d4fb1b51 --- # Linker tools error LNK1120 > *number* unresolved externals +## Remarks + Error LNK1120 reports the number of [unresolved external symbol](linker-tools-error-lnk2001.md#what-is-an-unresolved-external-symbol) errors in the current link. Each unresolved external symbol first gets reported by a [LNK2001](linker-tools-error-lnk2001.md) or [LNK2019](linker-tools-error-lnk2019.md) error. The LNK1120 message comes last, and shows the unresolved symbol error count. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1123.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1123.md index 07bfa2d8cc8..3059a757de8 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1123.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1123.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Linker Tools Error LNK1123" title: "Linker Tools Error LNK1123" -ms.date: "12/29/2017" +description: "Learn more about: Linker Tools Error LNK1123" +ms.date: 12/29/2017 f1_keywords: ["LNK1123"] helpviewer_keywords: ["LNK1123"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["LNK1123"] > failure during conversion to COFF: file invalid or corrupt +## Remarks + Input files must have the Common Object File Format (COFF) format. If an input file is not COFF, the linker automatically tries to convert 32-bit OMF objects to COFF, or runs CVTRES.EXE to convert resource files. This message indicates that the linker could not convert the file. This can also occur when using an incompatible version of CVTRES.EXE from another installation of Visual Studio, the Windows Development Kit, or .NET Framework. > [!NOTE] diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1127.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1127.md index 85695de1e0c..d2acd271220 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1127.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1127.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1127" title: "Linker Tools Error LNK1127" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1127" +ms.date: 11/04/2016 f1_keywords: ["LNK1127"] helpviewer_keywords: ["LNK1127"] -ms.assetid: 45404700-1420-4f24-97e1-efb7252ffd8f --- # Linker Tools Error LNK1127 -library is corrupt +> library is corrupt + +## Remarks The library file is corrupt. Rebuild the library. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1136.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1136.md index 3178558c899..0c4dee8bb92 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1136.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1136.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1136" title: "Linker Tools Error LNK1136" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1136" +ms.date: 11/04/2016 f1_keywords: ["LNK1136"] helpviewer_keywords: ["LNK1136"] -ms.assetid: 40c6d909-eb3f-4045-a0fc-4caa2f6db506 --- # Linker Tools Error LNK1136 -invalid or corrupt file +> invalid or corrupt file + +## Remarks The input file either has a corrupt header or is zero size or abnormally small. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1140.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1140.md index 122f869f78d..28bd6c168d8 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1140.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1140.md @@ -1,21 +1,23 @@ --- -description: "Learn more about: Linker Tools Error LNK1140" title: "Linker Tools Error LNK1140" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1140" +ms.date: 11/04/2016 f1_keywords: ["LNK1140"] helpviewer_keywords: ["LNK1140"] -ms.assetid: 468d7651-a7cd-47b9-aead-5bb2fab56121 --- # Linker Tools Error LNK1140 -too many modules for program database; link with /PDB:NONE +> too many modules for program database; link with /PDB:NONE + +## Remarks -The project contains more than 4096 modules. +The project exceeds the maximum number of modules allowed in a program database (PDB) file. This limit was originally 4,096 modules and was later increased to 65,533. + +This error can also occur when other PDB size limits are exceeded, such as too many symbols or an excessive number of types. ### To fix by using the following possible solutions 1. Relink using [/PDB:NONE](../../build/reference/pdb-use-program-database.md). - 1. Compile some modules without debugging information. - 1. Reduce the number of modules. +1. Split your project into multiple smaller libraries or DLLs. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1141.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1141.md index 6f75fcc90a4..11f1c42106c 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1141.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1141.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1141" title: "Linker Tools Error LNK1141" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1141" +ms.date: 11/04/2016 f1_keywords: ["LNK1141"] helpviewer_keywords: ["LNK1141"] -ms.assetid: 83b78606-6dd3-43a7-88e2-152f5359cbd8 --- # Linker Tools Error LNK1141 -failure during build of exports file +> failure during build of exports file + +## Remarks [LINK](../../build/reference/linking.md) could not build the exports (.exp) file. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1143.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1143.md index 0e06f04ee32..3d852635bb1 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1143.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1143.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1143" title: "Linker Tools Error LNK1143" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1143" +ms.date: 11/04/2016 f1_keywords: ["LNK1143"] helpviewer_keywords: ["LNK1143"] -ms.assetid: 5dc6b634-d142-4448-b5ea-48e8fb10c10a --- # Linker Tools Error LNK1143 -invalid or corrupt file: no symbol for COMDAT section number +> invalid or corrupt file: no symbol for COMDAT section number + +## Remarks This error can be caused if the object file is corrupt. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1152.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1152.md index 5929d7abbf6..94733880e80 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1152.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1152.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1152" title: "Linker Tools Error LNK1152" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1152" +ms.date: 11/04/2016 f1_keywords: ["LNK1152"] helpviewer_keywords: ["LNK1152"] -ms.assetid: 2523b61a-1359-4612-9c16-7d1f705f32e6 --- # Linker Tools Error LNK1152 -cannot resolve one or more undecorated symbols +> cannot resolve one or more undecorated symbols + +## Remarks This error is preceded by one warning [LNK4022](../../error-messages/tool-errors/linker-tools-warning-lnk4022.md) for each undecorated symbol that could not be resolved and by at least two warnings [LNK4002](../../error-messages/tool-errors/linker-tools-warning-lnk4002.md) for the duplicate symbols found for the undecorated symbol. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1158.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1158.md index f2350017bc0..c439b181dde 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1158.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1158.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1158" title: "Linker Tools Error LNK1158" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1158" +ms.date: 11/04/2016 f1_keywords: ["LNK1158"] helpviewer_keywords: ["LNK1158"] -ms.assetid: 45febf16-d9e1-42db-af91-532e2717fd6a --- # Linker Tools Error LNK1158 -cannot run 'filename' +> cannot run 'filename' + +## Remarks The given executable file called by [LINK](../../build/reference/linking.md) is not in the directory that contains LINK nor in a directory specified in the PATH environment variable. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1164.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1164.md index dbcffd442ea..065ff3d8f75 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1164.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1164.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1164" title: "Linker Tools Error LNK1164" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1164" +ms.date: 11/04/2016 f1_keywords: ["LNK1164"] helpviewer_keywords: ["LNK1164"] -ms.assetid: da89765c-affa-4f88-b170-6d6b19a577cf --- # Linker Tools Error LNK1164 -section section alignment (number) greater than /ALIGN value +> section section alignment (number) greater than /ALIGN value + +## Remarks The alignment size for the given section in the object file exceeds the value specified with the [/ALIGN](../../build/reference/align-section-alignment.md) option. The **/ALIGN** value must be a power of 2 and must equal or exceed the section alignment given in the object file. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1166.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1166.md index b67c5fb58e5..e9afdd5624e 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1166.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1166.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1166" title: "Linker Tools Error LNK1166" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1166" +ms.date: 11/04/2016 f1_keywords: ["LNK1166"] helpviewer_keywords: ["LNK1166"] -ms.assetid: d69548a8-0efb-44e1-90b7-b27636a4b575 --- # Linker Tools Error LNK1166 -cannot adjust code at offset=offset, va=value +> cannot adjust code at offset=offset, va=value + +## Remarks LINK was unable to pad the code as required. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md index b383fbe74fd..fd72aa34b40 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1168.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Linker Tools Error LNK1168" title: "Linker Tools Error LNK1168" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1168" +ms.date: 11/04/2016 f1_keywords: ["LNK1168"] helpviewer_keywords: ["LNK1168"] -ms.assetid: 97ead151-fd99-46fe-9a1d-7e84dc0b8cc8 --- # Linker Tools Error LNK1168 -cannot open filename for writing +> cannot open filename for writing + +## Remarks -The linker can’t write to `filename`. The file may be in use and its file handle locked by another process, or you may not have write permission for the file, or for the directory or network share it is located in. This error is often caused by a transient condition—for example, a lock held by an anti-virus program, a file search indexing process, or a delay in releasing a lock held by the Visual Studio build system. +The linker can't write to `filename`. The file may be in use and its file handle locked by another process, or you may not have write permission for the file, or for the directory or network share it is located in. This error is often caused by a transient condition—for example, a lock held by an anti-virus program, a file search indexing process, or a delay in releasing a lock held by the Visual Studio build system. To fix this issue, verify that the `filename` file handle is not locked, and that you have write permission for the file. If it is an executable, verify that it is not already running. @@ -20,4 +21,4 @@ If the file is locked by an anti-virus program, you can fix this issue by exclud If the file is locked by a search indexing service, you can fix this issue by excluding your build output directories from automatic indexing. Consult the documentation for the indexing service for more information. To change the Windows search indexing service, use **Indexing Options** in the Windows **Control Panel**. For more information, see [Search indexing in Windows 10: FAQ](https://support.microsoft.com/help/4098843/windows-10-search-indexing-faq). -If your executable can’t be overwritten by the build process, it may be locked by File Explorer. If the **Application Experience** service has been disabled, File Explorer may hold on to an executable file handle lock for an extended time. To fix this issue, run **services.msc** and then open the **Properties** dialog box for the **Application Experience** service. Change the **Startup type** from **Disabled** to **Manual**. +If your executable can't be overwritten by the build process, it may be locked by File Explorer. If the **Application Experience** service has been disabled, File Explorer may hold on to an executable file handle lock for an extended time. To fix this issue, run **services.msc** and then open the **Properties** dialog box for the **Application Experience** service. Change the **Startup type** from **Disabled** to **Manual**. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1169.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1169.md index f3355d082cd..20e35c0d767 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1169.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1169.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1169" title: "Linker Tools Error LNK1169" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1169" +ms.date: 11/04/2016 f1_keywords: ["LNK1169"] helpviewer_keywords: ["LNK1169"] -ms.assetid: e079d518-f184-48cd-8b38-969bf137af54 --- # Linker Tools Error LNK1169 -one or more multiply defined symbols found +> one or more multiply defined symbols found + +## Remarks The build failed due to multiple definitions of one or more symbols. This error is preceded by error [LNK2005](../../error-messages/tool-errors/linker-tools-error-lnk2005.md). diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1170.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1170.md index 7b4979f8e5b..1bfdd6a7cb1 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1170.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1170.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker tools Error LNK1170" title: "Linker tools Error LNK1170" +description: "Learn more about: Linker tools Error LNK1170" ms.date: 05/17/2022 f1_keywords: ["LNK1170"] helpviewer_keywords: ["LNK1170"] -ms.assetid: e079d518-f184-48cd-8b38-969bf137af54 --- # Linker tools Error LNK1170 > line in command file contains *maximum-length* or more characters +## Remarks + The build failed because a line in a command response file was too long. A line in an automatically generated response file may be too long for many reasons. For example, this error may occur if the number of object file names is too high. Or, if the combined lengths of the paths included in object file names is too long. The appropriate fix for this issue depends on the cause. For example, if it's caused by long paths in object file names, you may try to shorten the directory names in the path. Or, move the project tree into a directory closer to the root of the drive. You may want to break up how response files are generated and consumed by your build system, for instance, by generating some code as static libraries. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1179.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1179.md index 6b95e3bc95d..9007d33d95c 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1179.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1179.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1179" title: "Linker Tools Error LNK1179" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1179" +ms.date: 11/04/2016 f1_keywords: ["LNK1179"] helpviewer_keywords: ["LNK1179"] -ms.assetid: 4b1536d7-0d3d-4f29-a9c1-6fa5cf6cb665 --- # Linker Tools Error LNK1179 -invalid or corrupt file: duplicate COMDAT 'filename' +> invalid or corrupt file: duplicate COMDAT 'filename' + +## Remarks An object module contains two or more COMDATs with the same name. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1181.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1181.md index 0a8bdc45693..3212fbf52a1 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1181.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1181.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1181" title: "Linker Tools Error LNK1181" -ms.date: "08/22/2018" +description: "Learn more about: Linker Tools Error LNK1181" +ms.date: 08/22/2018 f1_keywords: ["LNK1181"] helpviewer_keywords: ["LNK1181"] -ms.assetid: 984b0db6-e331-4284-b2a7-a212fe96c486 --- # Linker Tools Error LNK1181 -cannot open input file 'filename' +> cannot open input file 'filename' + +## Remarks The linker could not find `filename` because it does not exist or the path was not found. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1188.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1188.md index f5800616ee0..fa68aa2479c 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1188.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1188.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1188" title: "Linker Tools Error LNK1188" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1188" +ms.date: 11/04/2016 f1_keywords: ["LNK1188"] helpviewer_keywords: ["LNK1188"] -ms.assetid: 4af574b0-5b41-4580-9a37-52a634add995 --- # Linker Tools Error LNK1188 -BADFIXUPSECTION:: invalid fixup target 'symbol'; possible zero length section +> BADFIXUPSECTION:: invalid fixup target 'symbol'; possible zero length section + +## Remarks During a VxD link, the target of a relocation did not have a section. With LINK386 (an older version), an OMF GROUP record (generated by a MASM GROUP directive) may have been used to combine the zero length section with another non-zero length section. COFF format does not support the GROUP directive and zero-length sections. When LINK automatically converts this type of OMF objects to COFF, this error may occur. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1189.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1189.md index fc1bfb4f8d4..3638265d0cc 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1189.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1189.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1189" title: "Linker Tools Error LNK1189" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1189" +ms.date: 11/04/2016 f1_keywords: ["LNK1189"] helpviewer_keywords: ["LNK1189"] -ms.assetid: 40c45302-6967-497e-9a6e-c2ca039fc1ed --- # Linker Tools Error LNK1189 -LIBTOOMANYMEMBERS:: library limit of number objects exceeded +> LIBTOOMANYMEMBERS:: library limit of number objects exceeded + +## Remarks The limit of 65535 objects or members in a library has been exceeded. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1196.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1196.md index 050af899a89..8b9f7cff7de 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1196.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1196.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1196" title: "Linker Tools Error LNK1196" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1196" +ms.date: 11/04/2016 f1_keywords: ["LNK1196"] helpviewer_keywords: ["LNK1196"] -ms.assetid: d0c6859b-85aa-45cc-9f5f-fc1f7070ab5a --- # Linker Tools Error LNK1196 -invalid or corrupt import object: unknown version +> invalid or corrupt import object: unknown version + +## Remarks The import library is corrupted. Rebuild the library. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1200.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1200.md index c07c0b16e83..cbf43a2a49b 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1200.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1200.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1200" title: "Linker Tools Error LNK1200" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1200" +ms.date: 11/04/2016 f1_keywords: ["LNK1200"] helpviewer_keywords: ["LNK1200"] -ms.assetid: 55771145-915e-4006-ac6c-ac702041eb2f --- # Linker Tools Error LNK1200 -error reading program database 'filename' +> error reading program database 'filename' + +## Remarks The program database (PDB) could not be read. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1201.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1201.md index 8e8f1888c04..4dc5e1a5bce 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1201.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1201.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1201" title: "Linker Tools Error LNK1201" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1201" +ms.date: 11/04/2016 f1_keywords: ["LNK1201"] helpviewer_keywords: ["LNK1201"] -ms.assetid: 64c3f496-a428-4b54-981e-faa82ef9c8a1 --- # Linker Tools Error LNK1201 -error writing to program database 'filename'; check for insufficient disk space, invalid path, or insufficient privilege +> error writing to program database 'filename'; check for insufficient disk space, invalid path, or insufficient privilege + +## Remarks LINK could not write to the program database (PDB) for the output file. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1211.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1211.md index 0cdaf996a71..dffce63c093 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1211.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1211.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Error LNK1211" title: "Linker Tools Error LNK1211" -ms.date: "12/05/2017" +description: "Learn more about: Linker Tools Error LNK1211" +ms.date: 12/05/2017 f1_keywords: ["LNK1211"] helpviewer_keywords: ["LNK1211"] -ms.assetid: 607400eb-4180-4892-817f-eedfa628af61 --- # Linker Tools Error LNK1211 > precompiled type information not found; '*filename*' not linked or overwritten +## Remarks + The *filename* object file, compiled by using [/Yc](../../build/reference/yc-create-precompiled-header-file.md), was not specified in the LINK command or was overwritten. If you are creating a debug library that uses precompiled headers and if you specify **/Yc** and [/Z7](../../build/reference/z7-zi-zi-debug-information-format.md), Visual C++ generates a precompiled object file that contains debug information. The error occurs only when you store the precompiled object file in a library, use the library to build an executable image, and the object files that are referenced have no transitive references to any of the functions the precompiled object file defines. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1215.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1215.md index 2323a27f564..96a368bdc10 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1215.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1215.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1215" title: "Linker Tools Error LNK1215" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1215" +ms.date: 11/04/2016 f1_keywords: ["LNK1215"] helpviewer_keywords: ["LNK1215"] -ms.assetid: 0774d8e6-f0c1-4efb-8723-7e1be6863d81 --- # Linker Tools Error LNK1215 -metadata operation failed (HRESULT) : error +> metadata operation failed (HRESULT) : error + +## Remarks The linker received an error from the .NET runtime while attempting to do a metadata update through the .NET runtime. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1218.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1218.md index 624fcb6ca33..cd40d43678a 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1218.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1218.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1218" title: "Linker Tools Error LNK1218" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1218" +ms.date: 11/04/2016 f1_keywords: ["LNK1218"] helpviewer_keywords: ["LNK1218"] -ms.assetid: bf599350-be03-4344-be43-91e29c4f1556 --- # Linker Tools Error LNK1218 -warning treated as error; no output file generated +> warning treated as error; no output file generated + +## Remarks When you link with **/WX**, any linker warnings will be treated as errors, and no output file will be created. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1221.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1221.md index f200e10465f..cf0e8c002f1 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1221.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1221.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1221" title: "Linker Tools Error LNK1221" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1221" +ms.date: 11/04/2016 f1_keywords: ["LNK1221"] helpviewer_keywords: ["LNK1221"] -ms.assetid: 70654bf9-1520-4fa3-a063-1219dd88abf7 --- # Linker Tools Error LNK1221 -a subsystem can't be inferred and must be defined +> a subsystem can't be inferred and must be defined + +## Remarks The linker does not have enough information to infer which subsystem you want to target. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1223.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1223.md index 54a615674d0..5f13930590d 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1223.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1223.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1223" title: "Linker Tools Error LNK1223" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1223" +ms.date: 11/04/2016 f1_keywords: ["LNK1223"] helpviewer_keywords: ["LNK1223"] -ms.assetid: c4728c36-daee-462f-a1c7-8733dcdec88e --- # Linker Tools Error LNK1223 -invalid or corrupt file: file contains invalid .pdata contributions +> invalid or corrupt file: file contains invalid .pdata contributions + +## Remarks For RISC platforms that use pdata, this error will occur if the compiler emitted a .pdata section with unsorted entries. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1224.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1224.md index 36dd5b331dc..49e0c86b868 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1224.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1224.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1224" title: "Linker Tools Error LNK1224" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1224" +ms.date: 11/04/2016 f1_keywords: ["LNK1224"] helpviewer_keywords: ["LNK1224"] -ms.assetid: e190b5d0-ce0c-4f65-8cc0-753f1cc9758a --- # Linker Tools Error LNK1224 -invalid image base address +> invalid image base address + +## Remarks You specified an invalid base address for the image. Base addresses must be 64KB aligned (the last four hex digits must be zero) and image base must fit within a 32-bit signed or unsigned value. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md index 46248f9a0b2..153938e7ce3 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1237.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Error LNK1237" title: "Linker Tools Error LNK1237" +description: "Learn more about: Linker Tools Error LNK1237" ms.date: 06/29/2022 f1_keywords: ["LNK1237"] helpviewer_keywords: ["LNK1237"] -ms.assetid: 8722ffa8-096a-4bb0-85f9-f3aa0e10872a --- # Linker Tools Error LNK1237 @@ -20,7 +19,7 @@ To resolve LNK1237, don't use **`/GL`** to compile the symbol, or use [`/INCLUDE ## Example -The following sample generates LNK1237. To resolve this error, don't initialize the array in `LNK1237_a.cpp` and add **`/include:__chkstk`** to the link command. +The following example generates LNK1237. To resolve this error, don't initialize the array in `LNK1237_a.cpp` and add **`/include:__chkstk`** to the link command. Source file `LNK1237_a.cpp`: diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1240.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1240.md index d899064a26b..74f3f8900d1 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1240.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1240.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1240" title: "Linker Tools Error LNK1240" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1240" +ms.date: 11/04/2016 f1_keywords: ["LNK1240"] helpviewer_keywords: ["LNK1240"] -ms.assetid: 7d0e065d-1015-4df0-8370-79c3cf045e1c --- # Linker Tools Error LNK1240 -failed to compile IDL content +> failed to compile IDL content + +## Remarks The linker spawned MIDL to compile embedded IDL but there was a problem. Check the errors specified by MIDL. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1241.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1241.md index 2b423a6bec7..1c3975105b1 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1241.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1241.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1241" title: "Linker Tools Error LNK1241" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1241" +ms.date: 11/04/2016 f1_keywords: ["LNK1241"] helpviewer_keywords: ["LNK1241"] -ms.assetid: 7b8b52eb-0231-4521-b52a-2bce8d3e8956 --- # Linker Tools Error LNK1241 -resource file 'resource file' already specified +> resource file 'resource file' already specified + +## Remarks This error is generated if you run **cvtres** manually from the command line and if you then pass the resulting .obj file to the linker in addition to other .res files. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1245.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1245.md index 4622d688ed5..5ef7756cbed 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1245.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1245.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1245" title: "Linker Tools Error LNK1245" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1245" +ms.date: 11/04/2016 f1_keywords: ["LNK1245"] helpviewer_keywords: ["LNK1245"] -ms.assetid: 179c8165-ffbb-44cd-9f24-5250f29577cc --- # Linker Tools Error LNK1245 -invalid subsystem 'subsystem' specified; /SUBSYSTEM must be WINDOWS, WINDOWSCE, or CONSOLE +> invalid subsystem 'subsystem' specified; /SUBSYSTEM must be WINDOWS, WINDOWSCE, or CONSOLE + +## Remarks [/clr](../../build/reference/clr-common-language-runtime-compilation.md) was used to compile the object and one of the following conditions was true: diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md index b1813f04202..f0beb0694ef 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1248.md @@ -1,12 +1,21 @@ --- -description: "Learn more about: Linker Tools Error LNK1248" title: "Linker Tools Error LNK1248" -ms.date: "12/28/2017" +description: "Learn more about: Linker Tools Error LNK1248" +ms.date: 08/31/2022 f1_keywords: ["LNK1248"] helpviewer_keywords: ["LNK1248"] --- # Linker Tools Error LNK1248 -> image size ('*size*') exceeds maximum allowable size (80000000) +> image size ('*output_size*') exceeds maximum allowable size (*maximum_size*) + +## Remarks + +The linker determined that the size of an output file will exceed the largest possible size for a 32-bit program image or object file (PE or COFF file). + +To resolve this issue if the file is an executable or DLL, you may want to refactor your program to move some functionality into a separate DLL. If the file is an object file, you may want to refactor your source file into multiple translation units. If the file is a *`.iobj`* file created by [`/LTCGOUT` (Name LTCG incremental object file)](../../build/reference/ltcgout.md) and you aren't using **`/LTCG:INCREMENTAL`**, then remove the **`/LTCGOUT`** option. If you're using **`/LTCG:INCREMENTAL`**, then consider refactoring your executable to reduce the size of the component that causes the error. + +## See also -The linker determined that the size of the output file will exceed the largest possible size for a 32-bit program image. You may want to make your program into multiple DLLs. +[`/GL` (Whole Program Optimization)](../../build/reference/gl-whole-program-optimization.md)\ +[`/LTCG` (Link-time code generation)](../../build/reference/ltcg-link-time-code-generation.md) diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1256.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1256.md index 8d1a5d87b2d..f2b1838e570 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1256.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1256.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1256" title: "Linker Tools Error LNK1256" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1256" +ms.date: 11/04/2016 f1_keywords: ["LNK1256"] helpviewer_keywords: ["LNK1256"] -ms.assetid: 55b64b2b-a56b-436c-a55e-ec9c6dcb050e --- # Linker Tools Error LNK1256 -ALINK operation failed : reason +> ALINK operation failed : reason + +## Remarks A common reason for LNK1256 is an incorrect version number for an assembly. The value 65535 is not allowed for any part of the assembly version number. The valid range for assembly versions is 0 - 65534. @@ -16,7 +17,9 @@ LNK1256 can also be caused if ALINK could not find the named key container. Dele Another reason for LNK1256 is a version mismatch between the linker and Alink.dll. This can be caused by a corrupted Visual Studio installation. Use **Programs and Features** in the Windows Control Panel to repair or reinstall Visual Studio. -The following sample generates LNK1256: +## Example + +The following example generates LNK1256: ```cpp // LNK1256.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1264.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1264.md index 56602f576dc..b95262a2d15 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1264.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1264.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1264" title: "Linker Tools Error LNK1264" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1264" +ms.date: 11/04/2016 f1_keywords: ["LNK1264"] helpviewer_keywords: ["LNK1264"] -ms.assetid: 23b1aad7-d382-42c1-bae8-db68575c57a8 --- # Linker Tools Error LNK1264 -/LTCG:PGINSTRUMENT specified but no code generation required; instrumentation failed +> /LTCG:PGINSTRUMENT specified but no code generation required; instrumentation failed + +## Remarks **/LTCG:PGINSTRUMENT** was specified but no .obj files were found that were compiled with [/GL](../../build/reference/gl-whole-program-optimization.md). Instrumentation cannot take place and the link failed. There must be at least one .obj file on the command line that is compiled with **/GL** so that the instrumentation can occur. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1277.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1277.md index b7b4ad87f8b..79b41ded64f 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1277.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1277.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1277" title: "Linker Tools Error LNK1277" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1277" +ms.date: 11/04/2016 f1_keywords: ["LNK1277"] helpviewer_keywords: ["LNK1277"] -ms.assetid: afca3de0-50cc-4140-af7a-13493a170835 --- # Linker Tools Error LNK1277 -object record not found in pgd (filename) +> object record not found in pgd (filename) + +## Remarks When using [/LTCG:PGOPTIMZE](../../build/reference/ltcg-link-time-code-generation.md), the path of one of the input .lib, def, or .obj files was different from the path on which they were found during /LTCG:PGINSTRUMENT. This may be explained by a change in the LIB environment variable after /LTCG:PGINSTRUMENT. The full path to the input files is stored in the .pgd file. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1282.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1282.md index f5a4ef3c70b..2b61b724474 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1282.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1282.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1282" title: "Linker Tools Error LNK1282" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1282" +ms.date: 11/04/2016 f1_keywords: ["LNK1282"] helpviewer_keywords: ["LNK1282"] -ms.assetid: 99c13f52-eb80-46ce-a5b9-4537583e32a9 --- # Linker Tools Error LNK1282 -unable to /REBASE file; it has been signed +> unable to /REBASE file; it has been signed + +## Remarks You attempted to change the base address of a signed assembly with the /REBASE option for [editbin](../../build/reference/editbin-reference.md). To do this, first change the base address and then sign the assembly. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1287.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1287.md index 0e007f7611e..00f78ebdfb7 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1287.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1287.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK1287" title: "Linker Tools Error LNK1287" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1287" +ms.date: 11/04/2016 f1_keywords: ["LNK1287"] helpviewer_keywords: ["LNK1287"] -ms.assetid: 48dc379d-370c-42f6-8028-5bbcf1cc88bd --- # Linker Tools Error LNK1287 -invalid managed entry point function +> invalid managed entry point function + +## Remarks The entry point is not valid for a managed image. The return type of a managed entry point function can only be **`void`** or **`int`**. The type of the parameter of a managed entry point function can only be **`void`** or `String []`. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1296.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1296.md index ae48da8e2e0..608d27548f6 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1296.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1296.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1296" title: "Linker Tools Error LNK1296" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1296" +ms.date: 11/04/2016 f1_keywords: ["LNK1296"] helpviewer_keywords: ["LNK1296"] -ms.assetid: f94a3d18-5411-456b-966f-89810fdcfe60 --- # Linker Tools Error LNK1296 -unable to load filename +> unable to load filename + +## Remarks The given DLL was unavailable. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1301.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1301.md index 32ddbeb1ea6..7cb0c945cef 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1301.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1301.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1301" title: "Linker Tools Error LNK1301" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1301" +ms.date: 11/04/2016 f1_keywords: ["LNK1301"] helpviewer_keywords: ["LNK1301"] -ms.assetid: 760da428-7182-4b25-b20a-de90d4b9a9cd --- # Linker Tools Error LNK1301 -LTCG clr modules found, incompatible with /LTCG:parameter +> LTCG clr modules found, incompatible with /LTCG:parameter + +## Remarks A module compiled with /clr and /GL was passed to the linker along with one of the profile guided optimizations (PGO) parameters of /LTCG. @@ -30,7 +31,7 @@ For more information, see: ## Example -The following sample generates LNK1301: +The following example generates LNK1301: ```cpp // LNK1301.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1302.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1302.md index 575fa0381d0..8a3ef7ae5a2 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1302.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1302.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1302" title: "Linker Tools Error LNK1302" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1302" +ms.date: 11/04/2016 f1_keywords: ["LNK1302"] helpviewer_keywords: ["LNK1302"] -ms.assetid: aea3c753-c2c4-4249-bbc3-f2d4f0164b5e --- # Linker Tools Error LNK1302 -only support linking safe .netmodules; unable to link file .netmodule +> only support linking safe .netmodules; unable to link file .netmodule + +## Remarks A .netmodule (compiled with **/LN**) was passed to the linker in a user attempt to invoke MSIL linking. A C++ module is valid for MSIL linking if it is compiled with **/clr:safe**. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1306.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1306.md index 81531f6bc3c..eb8fec1dbf8 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1306.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1306.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Error LNK1306" title: "Linker Tools Error LNK1306" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1306" +ms.date: 11/04/2016 f1_keywords: ["LNK1306"] helpviewer_keywords: ["LNK1306"] -ms.assetid: fad1df6a-0bd9-412f-b0d1-7c9bc749c584 --- # Linker Tools Error LNK1306 > DLL entry point function cannot be managed; compile to native +## Remarks + `DllMain` cannot be compiled to MSIL; it must be compiled to native. To resolve this issue, @@ -30,7 +31,7 @@ For more information, see: ## Example -The following sample generates LNK1306. +The following example generates LNK1306. ```cpp // LNK1306.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1309.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1309.md index 3d4c3acd986..821728c7960 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1309.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1309.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Error LNK1309" title: "Linker Tools Error LNK1309" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1309" +ms.date: 11/04/2016 f1_keywords: ["LNK1309"] helpviewer_keywords: ["LNK1309"] -ms.assetid: 10146071-883f-4849-97d1-c7468f90efbb --- # Linker Tools Error LNK1309 diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1312.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1312.md index c4a7b56c971..06fc1cabccd 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1312.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1312.md @@ -1,20 +1,21 @@ --- -description: "Learn more about: Linker Tools Error LNK1312" title: "Linker Tools Error LNK1312" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1312" +ms.date: 11/04/2016 f1_keywords: ["LNK1312"] helpviewer_keywords: ["LNK1312"] -ms.assetid: 48284abb-d849-43fc-ab53-45aded14fd8a --- # Linker Tools Error LNK1312 -invalid or corrupt file: unable to import assembly +> invalid or corrupt file: unable to import assembly + +## Remarks When building an assembly, a file other than a module or assembly compiled with **/clr** was passed to the **/ASSEMBLYMODULE** linker option. If you passed an object file to **/ASSEMBLYMODULE**, just pass the object directly to the linker, instead of to **/ASSEMBLYMODULE**. -## Examples +## Example -The following sample created the .obj file. +The following example created the .obj file. ```cpp // LNK1312.cpp @@ -25,7 +26,7 @@ public: }; ``` -The following sample generates LNK1312. +The following example generates LNK1312. ```cpp // LNK1312_b.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md index 0028bd2e487..d32e1e04cdd 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1313.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Error LNK1313" title: "Linker Tools Error LNK1313" +description: "Learn more about: Linker Tools Error LNK1313" ms.date: 06/29/2022 f1_keywords: ["LNK1313"] helpviewer_keywords: ["LNK1313"] -ms.assetid: 5df0b72e-bb3f-428c-8d84-6084238f9827 --- # Linker Tools Error LNK1313 @@ -16,7 +15,7 @@ The current version of Visual C++ does not support linking native or mixed manag The **`/clr:pure`** compiler option is deprecated in Visual Studio 2015 and unsupported in Visual Studio 2017 and later. -## Examples +## Example Source file `LNK1313.cpp`: @@ -36,7 +35,7 @@ Source file `LNK1313_b.cpp`: void test(){} ``` -The following sample will generate LNK1313. +The following example will generate LNK1313. ```cpp // LNK1313_c.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1314.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1314.md index 91bcd50de0c..aaa27458f30 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1314.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1314.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1314" title: "Linker Tools Error LNK1314" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1314" +ms.date: 11/04/2016 f1_keywords: ["LNK1314"] helpviewer_keywords: ["LNK1314"] -ms.assetid: 0b5cd599-61ea-4ac7-8f25-c6d3a8b14655 --- # Linker Tools Error LNK1314 -corrupt or invalid COFF symbol table (undefined static or label symbol) +> corrupt or invalid COFF symbol table (undefined static or label symbol) + +## Remarks The compiler-generated content for a section in the given object appears to be corrupt. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1318.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1318.md index 8724382c59b..cf8a6f59de0 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1318.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1318.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Linker Tools Error LNK1318" title: "Linker Tools Error LNK1318" -ms.date: "05/29/2018" +description: "Learn more about: Linker Tools Error LNK1318" +ms.date: 05/29/2018 f1_keywords: ["LNK1318"] helpviewer_keywords: ["LNK1318"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["LNK1318"] > Unexpected PDB error; *cause* '*details*' +## Remarks + The linker encountered an unexpected error when opening, reading, or writing to a PDB file. This error message is produced for uncommon issues in PDB files. The *cause* and *details* represent the information available to the linker when the failure occurred. This may not be very useful, as common errors when dealing with PDB files have separate, more informative error messages. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1332.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1332.md index ff537294c8d..1c650843fc0 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1332.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1332.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1332" title: "Linker Tools Error LNK1332" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1332" +ms.date: 11/04/2016 f1_keywords: ["LNK1332"] helpviewer_keywords: ["LNK1332"] -ms.assetid: b31d5ca0-c27f-4177-896b-2637dccbde24 --- # Linker Tools Error LNK1332 -detected\ Windows Runtime types imported in one module and defined in another module +> detected\ Windows Runtime types imported in one module and defined in another module + +## Remarks When it produced the current target, the linker detected <`count`> Windows Runtime types, each of which is imported in one module and also defined in another module. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1352.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1352.md index c3d83f4fe6f..387d5699946 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1352.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1352.md @@ -1,7 +1,7 @@ --- title: "Linker Tools Error LNK1352" -description: Linker Tools Error LNK1352 occurs when an unsupported section merge is attempted. -ms.date: "09/10/2019" +description: "Linker Tools Error LNK1352 occurs when an unsupported section merge is attempted." +ms.date: 09/10/2019 f1_keywords: ["LNK1352"] helpviewer_keywords: ["LNK1352"] --- diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk1561.md b/docs/error-messages/tool-errors/linker-tools-error-lnk1561.md index 02cda93ab58..38e2cf273a2 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk1561.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk1561.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK1561" title: "Linker Tools Error LNK1561" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK1561" +ms.date: 11/04/2016 f1_keywords: ["LNK1561"] helpviewer_keywords: ["LNK1561"] -ms.assetid: cb0b709b-7c9c-4496-8a4e-9e1e4aefe447 --- # Linker Tools Error LNK1561 -entry point must be defined +> entry point must be defined + +## Remarks The linker did not find an *entry point*, the initial function to call in your executable. By default, the linker looks for a `main` or `wmain` function for a console app, a `WinMain` or `wWinMain` function for a Windows app, or `DllMain` for a DLL that requires initialization. You can specify another function by using the [/ENTRY](../../build/reference/entry-entry-point-symbol.md) linker option. @@ -24,7 +25,7 @@ When building an app, the linker looks for an entry point function to call to st ## Example -The following sample generates LNK1561: +The following example generates LNK1561: ```cpp // LNK1561.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2001.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2001.md index 4b3626bc8fe..15a53502f97 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2001.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2001.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Error LNK2001" title: "Linker Tools Error LNK2001" +description: "Learn more about: Linker Tools Error LNK2001" ms.date: 10/22/2021 f1_keywords: ["LNK2001"] helpviewer_keywords: ["LNK2001"] -ms.assetid: dc1cf267-c984-486c-abd2-fd07c799f7ef --- # Linker Tools Error LNK2001 > unresolved external symbol "*symbol*" +## Remarks + The compiled code makes a reference or call to *symbol*. The symbol isn't defined in any libraries or object files searched by the linker. This error message is followed by fatal error [LNK1120](../../error-messages/tool-errors/linker-tools-error-lnk1120.md). To fix error LNK1120, first fix all LNK2001 and LNK2019 errors. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2004.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2004.md index 79d704a0dc4..2d6d59c7ec4 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2004.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2004.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2004" title: "Linker Tools Error LNK2004" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2004" +ms.date: 11/04/2016 f1_keywords: ["LNK2004"] helpviewer_keywords: ["LNK2004"] -ms.assetid: 07645371-e67b-4a2c-b0e0-dde24c94ef7e --- # Linker Tools Error LNK2004 -gp relative fixup overflow to 'target'; short section 'section' is too large or out of range. +> gp relative fixup overflow to 'target'; short section 'section' is too large or out of range. + +## Remarks The section was too large. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2005.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2005.md index 68ddf0e345b..32354e573ea 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2005.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2005.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Error LNK2005" title: "Linker Tools Error LNK2005" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2005" +ms.date: 11/04/2016 f1_keywords: ["LNK2005"] helpviewer_keywords: ["LNK2005"] -ms.assetid: d9587adc-68be-425c-8a30-15dbc86717a4 --- # Linker Tools Error LNK2005 > *symbol* already defined in object +## Remarks + The symbol *symbol* was defined more than once. This error is followed by fatal error [LNK1169](../../error-messages/tool-errors/linker-tools-error-lnk1169.md). diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2008.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2008.md index 1d56c3f3aaf..e5cf01c5917 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2008.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2008.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2008" title: "Linker Tools Error LNK2008" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2008" +ms.date: 11/04/2016 f1_keywords: ["LNK2008"] helpviewer_keywords: ["LNK2008"] -ms.assetid: bbcd83c5-c8ae-439e-a033-63643a5bb373 --- # Linker Tools Error LNK2008 -Fixup target is not aligned 'symbol_name' +> Fixup target is not aligned 'symbol_name' + +## Remarks LINK found a fixup target in your object file that was not aligned properly. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2011.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2011.md index aee174c7840..1e4c6ffb5ee 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2011.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2011.md @@ -1,20 +1,23 @@ --- -description: "Learn more about: Linker Tools Error LNK2011" title: "Linker Tools Error LNK2011" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2011" +ms.date: 11/04/2016 f1_keywords: ["LNK2011"] helpviewer_keywords: ["LNK2011"] -ms.assetid: 04991ef5-49d5-46c7-8eee-a9d1d3fc541e --- # Linker Tools Error LNK2011 -precompiled object not linked in; image may not run +> precompiled object not linked in; image may not run + +## Remarks If you use precompiled headers, LINK requires that all of the object files created with precompiled headers must be linked in. If you have a source file that you use to generate a precompiled header for use with other source files, you now must include the object file created along with the precompiled header. +## Example + For example, if you compile a file called STUB.cpp to create a precompiled header for use with other source files, you must link with STUB.obj or you will get this error. In the following command lines, line one is used to create a precompiled header, COMMON.pch, which is used with PROG1.cpp and PROG2.cpp in lines two and three. The file STUB.cpp contains only `#include` lines (the same `#include` lines as in PROG1.cpp and PROG2.cpp) and is used only to generate precompiled headers. In the last line, STUB.obj must be linked in to avoid LNK2011. -``` +```cmd cl /c /Yccommon.h stub.cpp cl /c /Yucommon.h prog1.cpp cl /c /Yucommon.h prog2.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2013.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2013.md index c977734a5a8..c45fba1baeb 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2013.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2013.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2013" title: "Linker Tools Error LNK2013" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2013" +ms.date: 11/04/2016 f1_keywords: ["LNK2013"] helpviewer_keywords: ["LNK2013"] -ms.assetid: 21408e2d-3f56-4d1f-a031-00df70785ed4 --- # Linker Tools Error LNK2013 -fixup type fixup overflow. Target 'symbol name' is out of range +> fixup type fixup overflow. Target 'symbol name' is out of range + +## Remarks The linker cannot fit the necessary address or offset into the given instruction because the target symbol is too far away from the instruction's location. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2017.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2017.md index b0b30a605a4..8ec341849b6 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2017.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2017.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2017" title: "Linker Tools Error LNK2017" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2017" +ms.date: 11/04/2016 f1_keywords: ["LNK2017"] helpviewer_keywords: ["LNK2017"] -ms.assetid: f7c21733-b0fb-4888-a295-9b453ba6ee77 --- # Linker Tools Error LNK2017 -'symbol' relocation to 'segment' invalid without /LARGEADDRESSAWARE:NO +> 'symbol' relocation to 'segment' invalid without /LARGEADDRESSAWARE:NO + +## Remarks You are trying to build a 64-bit image with 32-bit addresses. To do this, you must: 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 1890ccfeff5..8c07ef83d0f 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2019.md @@ -1,7 +1,7 @@ --- title: "Linker Tools Error LNK2019" description: "All about the Microsoft Visual Studio Linker error LNK2019 and how to diagnose and correct it in C and C++ code." -ms.date: "01/15/2020" +ms.date: 09/07/2022 f1_keywords: ["LNK2019"] helpviewer_keywords: ["nochkclr.obj", "LNK2019", "_check_commonlanguageruntime_version"] no-loc: [main, WinMain, wmain, wWinMain, __cdecl, __stdcall, __fastcall, __vectorcall, extern, static, const, ARCH, AVX2, wchar_t, VERBOSE, EXPORTS, SYMBOLS, DUMPBIN, UNDNAME] @@ -10,19 +10,21 @@ no-loc: [main, WinMain, wmain, wWinMain, __cdecl, __stdcall, __fastcall, __vecto > unresolved external symbol '*symbol*' referenced in function '*function*' -The compiled code for *function* makes a reference or call to *symbol*, but the linker can't find the symbol definition in any of the libraries or object files to link. +## Remarks + +The compiled code for *function* makes a reference or call to *symbol*, but the linker can't find the symbol definition in any of the libraries or object files. This error message is followed by fatal error [LNK1120](../../error-messages/tool-errors/linker-tools-error-lnk1120.md). To fix error LNK1120, you must fix all LNK2001 and LNK2019 errors first. ## Possible causes -There are many ways to get this error. All of them involve a reference to a function or variable that the linker couldn't *resolve*, or find a definition for. The compiler can identify when a symbol isn't *declared*, but it can't tell when the symbol isn't *defined*. That's because the definition may be in a different source file or library. If a symbol is referred to but never defined, the linker generates an unresolved external symbol error. +There are many ways to get this error. All of them involve a reference to a function or variable that the linker couldn't *resolve*, or find a definition for. The compiler can identify when a symbol isn't *declared*, but it can't tell when the symbol isn't *defined*. It's because the definition might be in a different source file or library. If a symbol is referred to but never defined, the linker generates an unresolved external symbol error. Here are some common problems that cause LNK2019: ### The source file that contains the definition of the symbol isn't compiled -In Visual Studio, make sure the source file that defines the symbol gets compiled as part of your project. Check the intermediate build output directory for a matching .obj file. If the source file isn't compiled, right-click on the file in Solution Explorer and choose **Properties** to check the properties of the file. The **Configuration Properties** > **General** page should show an **Item Type** of **C/C++ Compiler**. On the command line, make sure the source file that contains the definition is compiled. +In Visual Studio, make sure the source file that defines the symbol gets compiled as part of your project. Check the intermediate build output directory for a matching .obj file. If the source file isn't compiled, right-click on the file in Solution Explorer, and then choose **Properties** to check the properties of the file. The **Configuration Properties** > **General** page should show an **Item Type** of **C/C++ Compiler**. On the command line, make sure the source file that contains the definition is compiled. ### The object file or library that contains the definition of the symbol isn't linked @@ -34,7 +36,7 @@ Verify you use the correct spelling and capitalization in both the declaration a ### A function is used but the type or number of the parameters don't match the function definition -The function declaration must match the definition. Make sure the function call matches the declaration, and that the declaration matches the definition. Code that invokes template functions must also have matching template function declarations that include the same template parameters as the definition. For an example of a template declaration mismatch, see sample LNK2019e.cpp in the Examples section. +The function declaration must match the definition. Make sure the function call matches the declaration, and that the declaration matches the definition. Code that invokes function templates must also have matching function template declarations that include the same template parameters as the definition. For an example of a template declaration mismatch, see sample LNK2019e.cpp in the Examples section. ### A function or variable is declared but not defined @@ -42,11 +44,11 @@ LNK2019 can occur when a declaration exists in a header file, but no matching de ### The calling convention is different between the function declaration and the function definition -Calling conventions ([__cdecl](../../cpp/cdecl.md), [__stdcall](../../cpp/stdcall.md), [__fastcall](../../cpp/fastcall.md), or [__vectorcall](../../cpp/vectorcall.md)) are encoded as part of the decorated name. Make sure the calling convention is the same. +Some calling conventions ([`__cdecl`](../../cpp/cdecl.md), [`__stdcall`](../../cpp/stdcall.md), [`__fastcall`](../../cpp/fastcall.md), and [`__vectorcall`](../../cpp/vectorcall.md)) are encoded as part of the decorated name. Make sure the calling convention is the same. -### A symbol is defined in a C file, but declared without using extern "C" in a C++ file +### A symbol is defined in a C file, but declared without using `extern "C"` in a C++ file -Symbols defined in a file that is compiled as C have different decorated names than symbols declared in a C++ file unless you use an [extern "C"](../../cpp/extern-cpp.md) modifier. Make sure the declaration matches the compilation linkage for each symbol. Similarly, if you define a symbol in a C++ file that will be used by a C program, use `extern "C"` in the definition. +A file that's compiled as C creates decorated names for symbols that are different from the decorated names for the same symbols declared in a C++ file, unless you use an [`extern "C"`](../../cpp/extern-cpp.md) modifier. Make sure the declaration matches the compilation linkage for each symbol. Similarly, if you define a symbol in a C++ file that will be used by a C program, use `extern "C"` in the definition. ### A symbol is defined as static and then later referenced outside the file @@ -58,19 +60,19 @@ A static class member must have a unique definition, or it will violate the one- ### A build dependency is only defined as a project dependency in the solution -In earlier versions of Visual Studio, this level of dependency was sufficient. However, starting with Visual Studio 2010, Visual Studio requires a [project-to-project reference](/visualstudio/ide/managing-references-in-a-project). If your project doesn't have a project-to-project reference, you may receive this linker error. Add a project-to-project reference to fix it. +In earlier versions of Visual Studio, this level of dependency was sufficient. However, starting with Visual Studio 2010, Visual Studio requires a [project-to-project reference](/visualstudio/ide/managing-references-in-a-project). If your project doesn't have a project-to-project reference, you might receive this linker error. Add a project-to-project reference to fix it. ### An entry point isn't defined -The application code must define an appropriate entry point: `main` or `wmain` for console applications, and `WinMain` or `wWinMain` for Windows applications. For more information, see [main function and command-line arguments](../../cpp/main-function-command-line-args.md) or [WinMain function](/windows/win32/api/winbase/nf-winbase-winmain). To use a custom entry point, specify the [/ENTRY (Entry-Point Symbol)](../../build/reference/entry-entry-point-symbol.md) linker option. +The application code must define an appropriate entry point: `main` or `wmain` for console applications, and `WinMain` or `wWinMain` for Windows applications. For more information, see [`main` function and command-line arguments](../../cpp/main-function-command-line-args.md) or [`WinMain` function](/windows/win32/api/winbase/nf-winbase-winmain). To use a custom entry point, specify the [`/ENTRY` (Entry-Point Symbol)](../../build/reference/entry-entry-point-symbol.md) linker option. ### You build a console application by using settings for a Windows application -If the error message is similar to **unresolved external symbol WinMain referenced in function** *function_name*, link by using **/SUBSYSTEM:CONSOLE** instead of **/SUBSYSTEM:WINDOWS**. For more information about this setting, and for instructions on how to set this property in Visual Studio, see [/SUBSYSTEM (Specify Subsystem)](../../build/reference/subsystem-specify-subsystem.md). +If the error message is similar to **unresolved external symbol WinMain referenced in function** *function_name*, link by using **`/SUBSYSTEM:CONSOLE`** instead of **`/SUBSYSTEM:WINDOWS`**. For more information about this setting, and for instructions on how to set this property in Visual Studio, see [`/SUBSYSTEM` (Specify Subsystem)](../../build/reference/subsystem-specify-subsystem.md). ### You attempt to link 64-bit libraries to 32-bit code, or 32-bit libraries to 64-bit code -Libraries and object files linked to your code must be compiled for the same architecture as your code. Make sure the libraries your project references are compiled for the same architecture as your project. Make sure the [/LIBPATH](../../build/reference/libpath-additional-libpath.md) or **Additional Library Directories** property points to libraries built for the correct architecture. +Libraries and object files linked to your code must be compiled for the same architecture as your code. Make sure the libraries your project references are compiled for the same architecture as your project. Make sure the [`/LIBPATH`](../../build/reference/libpath-additional-libpath.md) or **Additional Library Directories** property points to libraries built for the correct architecture. ### You use different compiler options for function inlining in different source files @@ -82,29 +84,33 @@ Automatic (function scope) variables can only be used in the scope of that funct ### You call intrinsic functions or pass argument types to intrinsic functions that aren't supported on your target architecture -For example, if you use an AVX2 intrinsic, but don't specify the [/ARCH:AVX2](../../build/reference/arch-x86.md) compiler option, the compiler assumes that the intrinsic is an external function. Instead of generating an inline instruction, the compiler generates a call to an external symbol with the same name as the intrinsic. When the linker tries to find the definition of this missing function, it generates LNK2019. Make sure you only use intrinsics and types supported by your target architecture. +For example, if you use an AVX2 intrinsic, but don't specify the [`/ARCH:AVX2`](../../build/reference/arch-x86.md) compiler option, the compiler assumes that the intrinsic is an external function. Instead of generating an inline instruction, the compiler generates a call to an external symbol with the same name as the intrinsic. When the linker tries to find the definition of this missing function, it generates LNK2019. Make sure you only use intrinsics and types supported by your target architecture. + +### You mix code that uses native `wchar_t` with code that doesn't + +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 mix code that uses native wchar_t with code that doesn't +### You get errors for *`printf`* and *`scanf`* functions when you link a legacy static library -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. +A static library that was built using a version of Visual Studio before Visual Studio 2015 might cause LNK2019 errors when linked with the UCRT. The UCRT header files ``, ``, and ``now define many *`printf`* and *`scanf`* variations as **`inline`** functions. The inlined functions are implemented by a smaller set of common functions. Individual exports for the inlined functions aren't available in the standard UCRT libraries, which only export the common functions. There are a couple of ways to resolve this issue. The method we recommend is to rebuild the legacy library with your current version of Visual Studio. Make sure the library code uses the standard headers for the definitions of the *`printf`* and *`scanf`* functions that caused the errors. Another option for a legacy library that you can't rebuild is to add `legacy_stdio_definitions.lib` to the list of libraries you link. This library file provides symbols for the *`printf`* and *`scanf`* functions that are inlined in the UCRT headers. For more information, see the **Libraries** section in [Overview of potential upgrade issues](../../porting/overview-of-potential-upgrade-issues-visual-cpp.md#libraries). ## Third-party library issues and vcpkg -If you see this error when you're trying to configure a third-party library as part of your build, consider using [vcpkg](https://vcpkg.io/), a C++ package manager, to install and build the library. vcpkg supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports). It sets all the configuration properties and dependencies required for successful builds as part of your project. +If you see this error when you're trying to configure a third-party library as part of your build, consider using [vcpkg](/vcpkg/). **vcpkg** is a C++ package manager that uses your existing Visual Studio tools to install and build the library. **vcpkg** supports a large and growing [list of third-party libraries](https://github.com/Microsoft/vcpkg/tree/master/ports). It sets all the configuration properties and dependencies required for successful builds as part of your project. ## Diagnosis tools Sometimes it's difficult to tell why the linker can't find a particular symbol definition. Often the problem is that you haven't included the code that contains the definition in your build. Or, build options have created different decorated names for external symbols. There are several tools and options that can help you diagnose LNK2019 errors. -- The [/VERBOSE](../../build/reference/verbose-print-progress-messages.md) linker option can help you determine which files the linker references. This option can help you verify whether the file that contains the definition of the symbol is included in your build. +- The [`/VERBOSE`](../../build/reference/verbose-print-progress-messages.md) linker option can help you determine which files the linker references. This option can help you verify whether the file that contains the definition of the symbol is included in your build. -- The [/EXPORTS](../../build/reference/dash-exports.md) and [/SYMBOLS](../../build/reference/symbols.md) options of the **DUMPBIN** utility can help you discover which symbols are defined in your .dll and object or library files. Make sure the exported decorated names match the decorated names the linker searches for. +- The [`/EXPORTS`](../../build/reference/dash-exports.md) and [`/SYMBOLS`](../../build/reference/symbols.md) options of the **DUMPBIN** utility can help you discover which symbols are defined in your .dll and object or library files. Make sure the exported decorated names match the decorated names the linker searches for. - The **UNDNAME** utility can show you the equivalent undecorated external symbol for a decorated name. ## Examples -Here are several examples of code that causes a LNK2019 error, together with information about how to fix the error. +Here are several examples of code that causes LNK2019 errors, together with information about how to fix the errors. ### A symbol is declared but not defined @@ -120,7 +126,7 @@ int main() { } ``` -Here is another example where a variable and function are declared as **`extern`** but no definition is provided: +Here's another example where a variable and function are declared as **`extern`** but no definition is provided: ```cpp // LNK2019c.cpp @@ -135,11 +141,11 @@ void f() { int main() {} ``` -Unless `i` and `g` are defined in one of the files included in the build, the linker generates LNK2019. You can fix the errors by including the source code file that contains the definitions as part of the compilation. Alternatively, you can pass .obj files or .lib files that contain the definitions to the linker. +Unless `i` and `g` are defined in one of the files included in the build, the linker generates LNK2019. You can fix the errors by including the source code file that contains the definitions as part of the compilation. Alternatively, you can pass `.obj` files or `.lib` files that contain the definitions to the linker. ### A static data member is declared but not defined -LNK2019 can also occur when a static data member is declared but not defined. The following sample generates LNK2019, and shows how to fix it. +LNK2019 can also occur when a static data member is declared but not defined. The following example generates LNK2019, and shows how to fix it. ```cpp // LNK2019b.cpp @@ -160,7 +166,7 @@ int main() { ### Declaration parameters don't match the definition -Code that invokes template functions must have matching template function declarations. Declarations must include the same template parameters as the definition. The following sample generates LNK2019 on a user-defined operator, and shows how to fix it. +Code that invokes function templates must have matching function template declarations. Declarations must include the same template parameters as the definition. The following example generates LNK2019 on a user-defined operator, and shows how to fix it. ```cpp // LNK2019e.cpp @@ -190,7 +196,7 @@ int main() { ### Inconsistent wchar_t type definitions -This sample creates a DLL that has an export that uses `WCHAR`, which resolves to **`wchar_t`**. +This example creates a DLL that has an export that uses `WCHAR`, which resolves to **`wchar_t`**. ```cpp // LNK2019g.cpp @@ -200,7 +206,7 @@ This sample creates a DLL that has an export that uses `WCHAR`, which resolves t __declspec(dllexport) void func(WCHAR*) {} ``` -The next sample uses the DLL in the previous sample, and generates LNK2019 because the types `unsigned short*` and `WCHAR*` aren't the same. +The next example uses the DLL in the previous example, and generates LNK2019 because the types `unsigned short*` and `WCHAR*` aren't the same. ```cpp // LNK2019h.cpp @@ -213,8 +219,8 @@ int main() { } ``` -To fix this error, change **`unsigned short`** to **`wchar_t`** or `WCHAR`, or compile LNK2019g.cpp by using **/Zc:wchar_t-**. +To fix this error, change **`unsigned short`** to **`wchar_t`** or `WCHAR`, or compile LNK2019g.cpp by using **`/Zc:wchar_t-`**. -## Additional resources +## See also -For more information about possible causes and solutions for LNK2001, see the Stack Overflow question [What is an undefined reference/unresolved external symbol error and how do I fix it?](https://stackoverflow.com/q/12573816/2002113). +For more information about possible causes and solutions for LNK2019, LNK2001, and LNK1120 errors, see the Stack Overflow question: [`What is an undefined reference/unresolved external symbol error and how do I fix it?`](https://stackoverflow.com/q/12573816/2002113). diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md index 36de7722e04..67a107c88ec 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2020.md @@ -1,14 +1,15 @@ --- -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 -unresolved token 'token' +> unresolved token 'token' + +## Remarks Similar to an undefined external error, except that the reference is via metadata. In metadata, all functions and data must be defined. @@ -20,7 +21,7 @@ To resolve: ## Examples -The following sample generates LNK2020. +The following example generates LNK2020. ```cpp // LNK2020.cpp @@ -39,7 +40,7 @@ ref struct B { LNK2020 will also occur if you create a variable of a managed template type, but do not also instantiate the type. -The following sample generates LNK2020. +The following example generates LNK2020. ```cpp // LNK2020_b.cpp @@ -47,16 +48,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-lnk2022.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2022.md index eee9aa2821e..56c9f16627b 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2022.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2022.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Error LNK2022" title: "Linker Tools Error LNK2022" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2022" +ms.date: 11/04/2016 f1_keywords: ["LNK2022"] helpviewer_keywords: ["LNK2022"] -ms.assetid: d2128c73-dde3-4b8e-a9b2-0a153acefb3b --- # Linker Tools Error LNK2022 @@ -16,7 +15,7 @@ One way to diagnose this problem is to run **ildasm -tokens** on the object file One reason for LNK2022 is when a type (such as a struct) exists in multiple compilands with the same name, but with conflicting definitions, and when you compile with [/clr](../../build/reference/clr-common-language-runtime-compilation.md). In this case, make sure that the type has an identical definition in all compilands. The type name is listed in `error_message`. -Another possible cause for LNK2022 is when the linker finds a metadata file in a different location than was specified to the compiler (with [#using](../../preprocessor/hash-using-directive-cpp.md) ). Make sure that the metadata file (.dll or .netmodule) is in the same location when passed to the linker, as it was when it was passed to the compiler. +Another possible cause for LNK2022 is when the linker finds a metadata file in a different location than was specified to the compiler (with [#using](../../preprocessor/hash-using-directive-cpp.md)). Make sure that the metadata file (.dll or .netmodule) is in the same location when passed to the linker, as it was when it was passed to the compiler. When building an ATL application, the use of the macro `_ATL_MIXED` is required in all compilands, if it is used in at least one. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2023.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2023.md index 3294c30bff2..9cafc696e3a 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2023.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2023.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2023" title: "Linker Tools Error LNK2023" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2023" +ms.date: 11/04/2016 f1_keywords: ["LNK2023"] helpviewer_keywords: ["LNK2023"] -ms.assetid: c99e35a8-739a-4a20-a715-29b8c3744703 --- # Linker Tools Error LNK2023 -bad dll or entry point \ +> bad dll or entry point \ + +## Remarks The linker is loading an incorrect version of msobj90.dll. Ensure that link.exe and msobj90.dll in your path have the same version. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2026.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2026.md index f1018137f86..13bf2776bd7 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2026.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2026.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Error LNK2026" title: "Linker Tools Error LNK2026" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2026" +ms.date: 11/04/2016 f1_keywords: ["LNK2026"] helpviewer_keywords: ["LNK2026"] -ms.assetid: 9955bf7c-59b5-4fa1-8481-147db0d7df45 --- # Linker Tools Error LNK2026 -module unsafe for SAFESEH image +> module unsafe for SAFESEH image + +## Remarks [/SAFESEH](../../build/reference/safeseh-image-has-safe-exception-handlers.md) was specified, but a module was not compatible with the safe exception handling feature. If you want to use this module with **/SAFESEH**, then you will need to recompile the module. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2027.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2027.md index 7b2c24ce08e..c95f4d0ad62 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2027.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2027.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2027" title: "Linker Tools Error LNK2027" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2027" +ms.date: 11/04/2016 f1_keywords: ["LNK2027"] helpviewer_keywords: ["LNK2027"] -ms.assetid: e2f857a8-8e8a-4697-bbff-12ccb84a35c1 --- # Linker Tools Error LNK2027 -unresolved module reference 'module' +> unresolved module reference 'module' + +## Remarks A file passed to the linker has a dependency on a module that was neither specified with **/ASSEMBLYMODULE** nor passed directly to the linker. diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2028.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2028.md index a43928ba548..82760815f9d 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2028.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2028.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Linker Tools Error LNK2028" title: "Linker Tools Error LNK2028" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2028" +ms.date: 11/04/2016 f1_keywords: ["LNK2028"] helpviewer_keywords: ["LNK2028"] -ms.assetid: e2b03293-6066-464d-a050-ce747bcf7f0e --- # Linker Tools Error LNK2028 -"*exported_function*" (*decorated_name*) referenced in function "*function_containing_function_call*" (*decorated_name*) +> "*exported_function*" (*decorated_name*) referenced in function "*function_containing_function_call*" (*decorated_name*) ## Remarks @@ -18,7 +17,7 @@ The **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupp ## Examples -This code sample generates a component with an exported, native, function whose calling convention is implicitly [__cdecl](../../cpp/cdecl.md). +This code example generates a component with an exported, native, function whose calling convention is implicitly [__cdecl](../../cpp/cdecl.md). ```cpp // LNK2028.cpp @@ -28,7 +27,7 @@ __declspec(dllexport) int func() { } ``` -The following sample creates a pure client that consumes the native function. However, the calling convention under **/clr:pure** is [__clrcall](../../cpp/clrcall.md). The following sample generates LNK2028. +The following example creates a pure client that consumes the native function. However, the calling convention under **/clr:pure** is [__clrcall](../../cpp/clrcall.md). The following example generates LNK2028. ```cpp // LNK2028_b.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-error-lnk2031.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2031.md index f95b8cc24b0..69581fa9667 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2031.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2031.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Error LNK2031" title: "Linker Tools Error LNK2031" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2031" +ms.date: 11/04/2016 f1_keywords: ["LNK2031"] helpviewer_keywords: ["LNK2031"] -ms.assetid: 18ed4b6e-3e75-443c-bbd8-2f6030dc89ee --- # Linker Tools Error LNK2031 @@ -18,7 +17,7 @@ The **/clr:pure** compiler option is deprecated in Visual Studio 2015 and unsupp ## Examples -This code sample generates a component with an exported, native, function whose calling convention is implicitly [__cdecl](../../cpp/cdecl.md). +This code example generates a component with an exported, native, function whose calling convention is implicitly [__cdecl](../../cpp/cdecl.md). ```cpp // LNK2031.cpp @@ -28,7 +27,7 @@ extern "C" { }; ``` -The following sample creates a pure client that consumes the native function. However, the calling convention under **/clr:pure** is [__clrcall](../../cpp/clrcall.md). The following sample generates LNK2031. +The following example creates a pure client that consumes the native function. However, the calling convention under **/clr:pure** is [__clrcall](../../cpp/clrcall.md). The following example generates LNK2031. ```cpp // LNK2031_b.cpp @@ -41,7 +40,7 @@ int main() { } ``` -The following sample shows how to consume the native function from a pure image. Note the explicit **`__cdecl`** calling convention specifier. +The following example shows how to consume the native function from a pure image. Note the explicit **`__cdecl`** calling convention specifier. ```cpp // LNK2031_c.cpp 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 02a0ccc9a81..2e84c4cfbc7 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2033.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2033.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Linker Tools Error LNK2033" title: "Linker Tools Error LNK2033" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2033" +ms.date: 11/04/2016 f1_keywords: ["LNK2033"] helpviewer_keywords: ["LNK2033"] -ms.assetid: d61db467-9328-4788-bf54-e2a20537f13f --- # Linker Tools Error LNK2033 -unresolved typeref token (token) for 'type' +> unresolved typeref token (token) for 'type' + +## Remarks -A type doesn’t have a definition in MSIL metadata. +A type doesn't have a definition in MSIL metadata. LNK2033 can occur when compiling with **/clr:safe** and where there is only a forward declaration for a type in an MSIL module, where the type is referenced in the MSIL module. @@ -20,7 +21,7 @@ For more information, see [/clr (Common Language Runtime Compilation)](../../bui ## Example -The following sample generates LNK2033. +The following example generates LNK2033. ```cpp // LNK2033.cpp @@ -32,5 +33,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 46faa30469d..64c8c87a92e 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2038.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2038.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Linker Tools Error LNK2038" title: "Linker Tools Error LNK2038" -ms.date: "12/15/2017" +description: "Learn more about: Linker Tools Error LNK2038" +ms.date: 12/15/2017 f1_keywords: ["LNK2038"] helpviewer_keywords: ["LNK2038"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["LNK2038"] > mismatch detected for '*name*': value '*value_1*' doesn't match value '*value_2*' in *filename.obj* +## Remarks + A symbol mismatch has been detected by the linker. This error indicates that different parts of an app, including libraries or other object code that the app links to, use conflicting definitions of the symbol. The [detect mismatch](../../preprocessor/detect-mismatch.md) pragma is used to define such symbols and detect their conflicting values. ## Possible causes and solutions @@ -18,24 +20,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-error-lnk2039.md b/docs/error-messages/tool-errors/linker-tools-error-lnk2039.md index 1f0ffa47935..6f441c91161 100644 --- a/docs/error-messages/tool-errors/linker-tools-error-lnk2039.md +++ b/docs/error-messages/tool-errors/linker-tools-error-lnk2039.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Error LNK2039" title: "Linker Tools Error LNK2039" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Error LNK2039" +ms.date: 11/04/2016 f1_keywords: ["LNK2039"] helpviewer_keywords: ["LNK2039"] -ms.assetid: eaa296bd-4901-41f6-8410-6d03ee827144 --- # Linker Tools Error LNK2039 -importing ref class '\' that is defined in another.obj; it should be either imported or defined, but not both +> importing ref class '\' that is defined in another.obj; it should be either imported or defined, but not both + +## Remarks The ref class '<`type`>' is imported in the specified .obj file but is also defined in another .obj file. This condition can cause runtime failure or other unexpected behavior. 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 f99364bedef..102d426b6e8 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,144 +1,149 @@ --- -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) The linker tools LINK, LIB, DUMPBIN, and EDITBIN share a common executable that generates these errors and warnings. The tools generate warnings of the form LNK*xxxx*, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Linker tools errors -[Linker Tools Error LNK1000](../../error-messages/tool-errors/linker-tools-error-lnk1000.md) \ -[Linker Tools Error LNK1103](../../error-messages/tool-errors/linker-tools-error-lnk1103.md) \ -[Linker Tools Error LNK1104](../../error-messages/tool-errors/linker-tools-error-lnk1104.md) \ -[Linker Tools Error LNK1106](../../error-messages/tool-errors/linker-tools-error-lnk1106.md) \ -[Linker Tools Error LNK1107](../../error-messages/tool-errors/linker-tools-error-lnk1107.md) \ -[Linker Tools Error LNK1112](../../error-messages/tool-errors/linker-tools-error-lnk1112.md) \ -[Linker Tools Error LNK1113](../../error-messages/tool-errors/linker-tools-error-lnk1113.md) \ -[Linker Tools Error LNK1120](../../error-messages/tool-errors/linker-tools-error-lnk1120.md) \ -[Linker Tools Error LNK1123](../../error-messages/tool-errors/linker-tools-error-lnk1123.md) \ -[Linker Tools Error LNK1127](../../error-messages/tool-errors/linker-tools-error-lnk1127.md) \ -[Linker Tools Error LNK1136](../../error-messages/tool-errors/linker-tools-error-lnk1136.md) \ -[Linker Tools Error LNK1140](../../error-messages/tool-errors/linker-tools-error-lnk1140.md) \ -[Linker Tools Error LNK1141](../../error-messages/tool-errors/linker-tools-error-lnk1141.md) \ -[Linker Tools Error LNK1143](../../error-messages/tool-errors/linker-tools-error-lnk1143.md) \ -[Linker Tools Error LNK1152](../../error-messages/tool-errors/linker-tools-error-lnk1152.md) \ -[Linker Tools Error LNK1158](../../error-messages/tool-errors/linker-tools-error-lnk1158.md) \ -[Linker Tools Error LNK1164](../../error-messages/tool-errors/linker-tools-error-lnk1164.md) \ -[Linker Tools Error LNK1166](../../error-messages/tool-errors/linker-tools-error-lnk1166.md) \ -[Linker Tools Error LNK1168](../../error-messages/tool-errors/linker-tools-error-lnk1168.md) \ -[Linker Tools Error LNK1169](../../error-messages/tool-errors/linker-tools-error-lnk1169.md) \ -[Linker Tools Error LNK1170](../../error-messages/tool-errors/linker-tools-error-lnk1170.md) \ -[Linker Tools Error LNK1179](../../error-messages/tool-errors/linker-tools-error-lnk1179.md) \ -[Linker Tools Error LNK1181](../../error-messages/tool-errors/linker-tools-error-lnk1181.md) \ -[Linker Tools Error LNK1188](../../error-messages/tool-errors/linker-tools-error-lnk1188.md) \ -[Linker Tools Error LNK1189](../../error-messages/tool-errors/linker-tools-error-lnk1189.md) \ -[Linker Tools Error LNK1196](../../error-messages/tool-errors/linker-tools-error-lnk1196.md) \ -[Linker Tools Error LNK1200](../../error-messages/tool-errors/linker-tools-error-lnk1200.md) \ -[Linker Tools Error LNK1201](../../error-messages/tool-errors/linker-tools-error-lnk1201.md) \ -[Linker Tools Error LNK1211](../../error-messages/tool-errors/linker-tools-error-lnk1211.md) \ -[Linker Tools Error LNK1215](../../error-messages/tool-errors/linker-tools-error-lnk1215.md) \ -[Linker Tools Error LNK1218](../../error-messages/tool-errors/linker-tools-error-lnk1218.md) \ -[Linker Tools Error LNK1221](../../error-messages/tool-errors/linker-tools-error-lnk1221.md) \ -[Linker Tools Error LNK1223](../../error-messages/tool-errors/linker-tools-error-lnk1223.md) \ -[Linker Tools Error LNK1224](../../error-messages/tool-errors/linker-tools-error-lnk1224.md) \ -[Linker Tools Error LNK1237](../../error-messages/tool-errors/linker-tools-error-lnk1237.md) \ -[Linker Tools Error LNK1240](../../error-messages/tool-errors/linker-tools-error-lnk1240.md) \ -[Linker Tools Error LNK1241](../../error-messages/tool-errors/linker-tools-error-lnk1241.md) \ -[Linker Tools Error LNK1245](../../error-messages/tool-errors/linker-tools-error-lnk1245.md) \ -[Linker Tools Error LNK1248](../../error-messages/tool-errors/linker-tools-error-lnk1248.md) \ -[Linker Tools Error LNK1256](../../error-messages/tool-errors/linker-tools-error-lnk1256.md) \ -[Linker Tools Error LNK1264](../../error-messages/tool-errors/linker-tools-error-lnk1264.md) \ -[Linker Tools Error LNK1277](../../error-messages/tool-errors/linker-tools-error-lnk1277.md) \ -[Linker Tools Error LNK1282](../../error-messages/tool-errors/linker-tools-error-lnk1282.md) \ -[Linker Tools Error LNK1287](../../error-messages/tool-errors/linker-tools-error-lnk1287.md) \ -[Linker Tools Error LNK1296](../../error-messages/tool-errors/linker-tools-error-lnk1296.md) \ -[Linker Tools Error LNK1301](../../error-messages/tool-errors/linker-tools-error-lnk1301.md) \ -[Linker Tools Error LNK1302](../../error-messages/tool-errors/linker-tools-error-lnk1302.md) \ -[Linker Tools Error LNK1306](../../error-messages/tool-errors/linker-tools-error-lnk1306.md) \ -[Linker Tools Error LNK1309](../../error-messages/tool-errors/linker-tools-error-lnk1309.md) \ -[Linker Tools Error LNK1312](../../error-messages/tool-errors/linker-tools-error-lnk1312.md) \ -[Linker Tools Error LNK1313](../../error-messages/tool-errors/linker-tools-error-lnk1313.md) \ -[Linker Tools Error LNK1314](../../error-messages/tool-errors/linker-tools-error-lnk1314.md) \ -[Linker Tools Error LNK1318](../../error-messages/tool-errors/linker-tools-error-lnk1318.md) \ -[Linker Tools Error LNK1332](../../error-messages/tool-errors/linker-tools-error-lnk1332.md) \ -[Linker Tools Error LNK1352](../../error-messages/tool-errors/linker-tools-error-lnk1352.md) \ -[Linker Tools Error LNK1561](../../error-messages/tool-errors/linker-tools-error-lnk1561.md) \ -[Linker Tools Error LNK2001](../../error-messages/tool-errors/linker-tools-error-lnk2001.md) \ -[Linker Tools Error LNK2004](../../error-messages/tool-errors/linker-tools-error-lnk2004.md) \ -[Linker Tools Error LNK2005](../../error-messages/tool-errors/linker-tools-error-lnk2005.md) \ -[Linker Tools Error LNK2008](../../error-messages/tool-errors/linker-tools-error-lnk2008.md) \ -[Linker Tools Error LNK2011](../../error-messages/tool-errors/linker-tools-error-lnk2011.md) \ -[Linker Tools Error LNK2013](../../error-messages/tool-errors/linker-tools-error-lnk2013.md) \ -[Linker Tools Error LNK2017](../../error-messages/tool-errors/linker-tools-error-lnk2017.md) \ -[Linker Tools Error LNK2019](../../error-messages/tool-errors/linker-tools-error-lnk2019.md) \ -[Linker Tools Error LNK2020](../../error-messages/tool-errors/linker-tools-error-lnk2020.md) \ -[Linker Tools Error LNK2022](../../error-messages/tool-errors/linker-tools-error-lnk2022.md) \ -[Linker Tools Error LNK2023](../../error-messages/tool-errors/linker-tools-error-lnk2023.md) \ -[Linker Tools Error LNK2026](../../error-messages/tool-errors/linker-tools-error-lnk2026.md) \ -[Linker Tools Error LNK2027](../../error-messages/tool-errors/linker-tools-error-lnk2027.md) \ -[Linker Tools Error LNK2028](../../error-messages/tool-errors/linker-tools-error-lnk2028.md) \ -[Linker Tools Error LNK2031](../../error-messages/tool-errors/linker-tools-error-lnk2031.md) \ -[Linker Tools Error LNK2033](../../error-messages/tool-errors/linker-tools-error-lnk2033.md) \ -[Linker Tools Error LNK2038](../../error-messages/tool-errors/linker-tools-error-lnk2038.md) \ -[Linker Tools Error LNK2039](../../error-messages/tool-errors/linker-tools-error-lnk2039.md) +| Error | Message | +|--|--| +| [Linker Tools Error LNK1000](linker-tools-error-lnk1000.md) | unknown error; consult documentation for technical support options | +| [Linker Tools Error LNK1103](linker-tools-error-lnk1103.md) | debugging information corrupt; recompile module | +| [Linker Tools Error LNK1104](linker-tools-error-lnk1104.md) | cannot open file '*filename*' | +| [Linker Tools Error LNK1106](linker-tools-error-lnk1106.md) | invalid file or disk full: cannot seek to location | +| [Linker Tools Error LNK1107](linker-tools-error-lnk1107.md) | invalid or corrupt file: cannot read at location *address* | +| [Linker Tools Error LNK1112](linker-tools-error-lnk1112.md) | module machine type '*type1*' conflicts with target machine type '*type2*' | +| [Linker Tools Error LNK1113](linker-tools-error-lnk1113.md) | invalid machine type type | +| [Linker Tools Error LNK1120](linker-tools-error-lnk1120.md) | *number* unresolved externals | +| [Linker Tools Error LNK1123](linker-tools-error-lnk1123.md) | failure during conversion to COFF: file invalid or corrupt | +| [Linker Tools Error LNK1127](linker-tools-error-lnk1127.md) | library is corrupt | +| [Linker Tools Error LNK1136](linker-tools-error-lnk1136.md) | invalid or corrupt file | +| [Linker Tools Error LNK1140](linker-tools-error-lnk1140.md) | too many modules for program database; link with /PDB:NONE | +| [Linker Tools Error LNK1141](linker-tools-error-lnk1141.md) | failure during build of exports file | +| [Linker Tools Error LNK1143](linker-tools-error-lnk1143.md) | invalid or corrupt file: no symbol for COMDAT section number | +| [Linker Tools Error LNK1152](linker-tools-error-lnk1152.md) | cannot resolve one or more undecorated symbols | +| [Linker Tools Error LNK1158](linker-tools-error-lnk1158.md) | cannot run 'filename' | +| [Linker Tools Error LNK1164](linker-tools-error-lnk1164.md) | section section alignment (number) greater than /ALIGN value | +| [Linker Tools Error LNK1166](linker-tools-error-lnk1166.md) | cannot adjust code at offset=offset, va=value | +| [Linker Tools Error LNK1168](linker-tools-error-lnk1168.md) | cannot open filename for writing | +| [Linker Tools Error LNK1169](linker-tools-error-lnk1169.md) | one or more multiply defined symbols found | +| [Linker Tools Error LNK1170](linker-tools-error-lnk1170.md) | line in command file contains *maximum-length* or more characters | +| [Linker Tools Error LNK1179](linker-tools-error-lnk1179.md) | invalid or corrupt file: duplicate COMDAT 'filename' | +| [Linker Tools Error LNK1181](linker-tools-error-lnk1181.md) | cannot open input file 'filename' | +| [Linker Tools Error LNK1188](linker-tools-error-lnk1188.md) | BADFIXUPSECTION:: invalid fixup target 'symbol'; possible zero length section | +| [Linker Tools Error LNK1189](linker-tools-error-lnk1189.md) | LIBTOOMANYMEMBERS:: library limit of number objects exceeded | +| [Linker Tools Error LNK1196](linker-tools-error-lnk1196.md) | invalid or corrupt import object: unknown version | +| [Linker Tools Error LNK1200](linker-tools-error-lnk1200.md) | error reading program database 'filename' | +| [Linker Tools Error LNK1201](linker-tools-error-lnk1201.md) | error writing to program database 'filename'; check for insufficient disk space, invalid path, or insufficient privilege | +| [Linker Tools Error LNK1211](linker-tools-error-lnk1211.md) | precompiled type information not found; '*filename*' not linked or overwritten | +| [Linker Tools Error LNK1215](linker-tools-error-lnk1215.md) | metadata operation failed (HRESULT) : error | +| [Linker Tools Error LNK1218](linker-tools-error-lnk1218.md) | warning treated as error; no output file generated | +| [Linker Tools Error LNK1221](linker-tools-error-lnk1221.md) | a subsystem can't be inferred and must be defined | +| [Linker Tools Error LNK1223](linker-tools-error-lnk1223.md) | invalid or corrupt file: file contains invalid .pdata contributions | +| [Linker Tools Error LNK1224](linker-tools-error-lnk1224.md) | invalid image base address | +| [Linker Tools Error LNK1237](linker-tools-error-lnk1237.md) | during code generation, compiler introduced reference to symbol 'symbol' defined in module 'module' compiled with /GL | +| [Linker Tools Error LNK1240](linker-tools-error-lnk1240.md) | failed to compile IDL content | +| [Linker Tools Error LNK1241](linker-tools-error-lnk1241.md) | resource file 'resource file' already specified | +| [Linker Tools Error LNK1245](linker-tools-error-lnk1245.md) | invalid subsystem 'subsystem' specified; /SUBSYSTEM must be WINDOWS, WINDOWSCE, or CONSOLE | +| [Linker Tools Error LNK1248](linker-tools-error-lnk1248.md) | image size ('*output_size*') exceeds maximum allowable size (*maximum_size*) | +| [Linker Tools Error LNK1256](linker-tools-error-lnk1256.md) | ALINK operation failed : reason | +| [Linker Tools Error LNK1264](linker-tools-error-lnk1264.md) | /LTCG:PGINSTRUMENT specified but no code generation required; instrumentation failed | +| [Linker Tools Error LNK1277](linker-tools-error-lnk1277.md) | object record not found in pgd (filename) | +| [Linker Tools Error LNK1282](linker-tools-error-lnk1282.md) | unable to /REBASE file; it has been signed | +| [Linker Tools Error LNK1287](linker-tools-error-lnk1287.md) | invalid managed entry point function | +| [Linker Tools Error LNK1296](linker-tools-error-lnk1296.md) | unable to load filename | +| [Linker Tools Error LNK1301](linker-tools-error-lnk1301.md) | LTCG clr modules found, incompatible with /LTCG:parameter | +| [Linker Tools Error LNK1302](linker-tools-error-lnk1302.md) | only support linking safe .netmodules; unable to link file .netmodule | +| [Linker Tools Error LNK1306](linker-tools-error-lnk1306.md) | DLL entry point function cannot be managed; compile to native | +| [Linker Tools Error LNK1309](linker-tools-error-lnk1309.md) | *type1* module detected; invalid with switch /CLRIMAGETYPE:*type2* | +| [Linker Tools Error LNK1312](linker-tools-error-lnk1312.md) | invalid or corrupt file: unable to import assembly | +| [Linker Tools Error LNK1313](linker-tools-error-lnk1313.md) | ijw/native module detected; cannot link with pure modules | +| [Linker Tools Error LNK1314](linker-tools-error-lnk1314.md) | corrupt or invalid COFF symbol table (undefined static or label symbol) | +| [Linker Tools Error LNK1318](linker-tools-error-lnk1318.md) | Unexpected PDB error; *cause* '*details*' | +| [Linker Tools Error LNK1332](linker-tools-error-lnk1332.md) | detected \ Windows Runtime types imported in one module and defined in another module | +| [Linker Tools Error LNK1352](linker-tools-error-lnk1352.md) | '*section_name_1*' and '*section_name_2*' cannot be merged into different sections | +| [Linker Tools Error LNK1561](linker-tools-error-lnk1561.md) | entry point must be defined | +| [Linker Tools Error LNK2001](linker-tools-error-lnk2001.md) | unresolved external symbol "*symbol*" | +| [Linker Tools Error LNK2004](linker-tools-error-lnk2004.md) | gp relative fixup overflow to 'target'; short section 'section' is too large or out of range. | +| [Linker Tools Error LNK2005](linker-tools-error-lnk2005.md) | *symbol* already defined in object | +| [Linker Tools Error LNK2008](linker-tools-error-lnk2008.md) | Fixup target is not aligned 'symbol_name' | +| [Linker Tools Error LNK2011](linker-tools-error-lnk2011.md) | precompiled object not linked in; image may not run | +| [Linker Tools Error LNK2013](linker-tools-error-lnk2013.md) | fixup type fixup overflow. Target 'symbol name' is out of range | +| [Linker Tools Error LNK2017](linker-tools-error-lnk2017.md) | 'symbol' relocation to 'segment' invalid without /LARGEADDRESSAWARE:NO | +| [Linker Tools Error LNK2019](linker-tools-error-lnk2019.md) | unresolved external symbol '*symbol*' referenced in function '*function*' | +| [Linker Tools Error LNK2020](linker-tools-error-lnk2020.md) | unresolved token 'token' | +| [Linker Tools Error LNK2022](linker-tools-error-lnk2022.md) | metadata operation failed (*HRESULT*) : *error_message* | +| [Linker Tools Error LNK2023](linker-tools-error-lnk2023.md) | bad dll or entry point \ | +| [Linker Tools Error LNK2026](linker-tools-error-lnk2026.md) | module unsafe for SAFESEH image | +| [Linker Tools Error LNK2027](linker-tools-error-lnk2027.md) | unresolved module reference 'module' | +| [Linker Tools Error LNK2028](linker-tools-error-lnk2028.md) | "*exported_function*" (*decorated_name*) referenced in function "*function_containing_function_call*" (*decorated_name*) | +| [Linker Tools Error LNK2031](linker-tools-error-lnk2031.md) | unable to generate p/invoke for "*function_declaration*" *decorated_name*; calling convention missing in metadata | +| [Linker Tools Error LNK2033](linker-tools-error-lnk2033.md) | unresolved typeref token (token) for 'type' | +| [Linker Tools Error LNK2038](linker-tools-error-lnk2038.md) | mismatch detected for '*name*': value '*value_1*' doesn't match value '*value_2*' in *filename.obj* | +| [Linker Tools Error LNK2039](linker-tools-error-lnk2039.md) | importing ref class \ that is defined in another.obj; it should be either imported or defined, but not both | ## Linker tools warnings -[Linker Tools Warning LNK4001](../../error-messages/tool-errors/linker-tools-warning-lnk4001.md) \ -[Linker Tools Warning LNK4002](../../error-messages/tool-errors/linker-tools-warning-lnk4002.md) \ -[Linker Tools Warning LNK4006](../../error-messages/tool-errors/linker-tools-warning-lnk4006.md) \ -[Linker Tools Warning LNK4010](../../error-messages/tool-errors/linker-tools-warning-lnk4010.md) \ -[Linker Tools Warning LNK4014](../../error-messages/tool-errors/linker-tools-warning-lnk4014.md) \ -[Linker Tools Warning LNK4020](../../error-messages/tool-errors/linker-tools-warning-lnk4020.md) \ -[Linker Tools Warning LNK4022](../../error-messages/tool-errors/linker-tools-warning-lnk4022.md) \ -[Linker Tools Warning LNK4039](../../error-messages/tool-errors/linker-tools-warning-lnk4039.md) \ -[Linker Tools Warning LNK4044](../../error-messages/tool-errors/linker-tools-warning-lnk4044.md) \ -[Linker Tools Warning LNK4049](../../error-messages/tool-errors/linker-tools-warning-lnk4049.md) \ -[Linker Tools Warning LNK4065](../../error-messages/tool-errors/linker-tools-warning-lnk4065.md) \ -[Linker Tools Warning LNK4070](../../error-messages/tool-errors/linker-tools-warning-lnk4070.md) \ -[Linker Tools Warning LNK4071](../../error-messages/tool-errors/linker-tools-warning-lnk4071.md) \ -[Linker Tools Warning LNK4073](../../error-messages/tool-errors/linker-tools-warning-lnk4073.md) \ -[Linker Tools Warning LNK4075](../../error-messages/tool-errors/linker-tools-warning-lnk4075.md) \ -[Linker Tools Warning LNK4076](../../error-messages/tool-errors/linker-tools-warning-lnk4076.md) \ -[Linker Tools Warning LNK4078](../../error-messages/tool-errors/linker-tools-warning-lnk4078.md) \ -[Linker Tools Warning LNK4086](../../error-messages/tool-errors/linker-tools-warning-lnk4086.md) \ -[Linker Tools Warning LNK4092](../../error-messages/tool-errors/linker-tools-warning-lnk4092.md) \ -[Linker Tools Warning LNK4096](../../error-messages/tool-errors/linker-tools-warning-lnk4096.md) \ -[Linker Tools Warning LNK4098](../../error-messages/tool-errors/linker-tools-warning-lnk4098.md) \ -[Linker Tools Warning LNK4099](../../error-messages/tool-errors/linker-tools-warning-lnk4099.md) \ -[Linker Tools Warning LNK4102](../../error-messages/tool-errors/linker-tools-warning-lnk4102.md) \ -[Linker Tools Warning LNK4104](../../error-messages/tool-errors/linker-tools-warning-lnk4104.md) \ -[Linker Tools Warning LNK4105](../../error-messages/tool-errors/linker-tools-warning-lnk4105.md) \ -[Linker Tools Warning LNK4194](../../error-messages/tool-errors/linker-tools-warning-lnk4194.md) \ -[Linker Tools Warning LNK4197](../../error-messages/tool-errors/linker-tools-warning-lnk4197.md) \ -[Linker Tools Warning LNK4199](../../error-messages/tool-errors/linker-tools-warning-lnk4199.md) \ -[Linker Tools Warning LNK4200](../../error-messages/tool-errors/linker-tools-warning-lnk4200.md) \ -[Linker Tools Warning LNK4204](../../error-messages/tool-errors/linker-tools-warning-lnk4204.md) \ -[Linker Tools Warning LNK4205](../../error-messages/tool-errors/linker-tools-warning-lnk4205.md) \ -[Linker Tools Warning LNK4206](../../error-messages/tool-errors/linker-tools-warning-lnk4206.md) \ -[Linker Tools Warning LNK4210](../../error-messages/tool-errors/linker-tools-warning-lnk4210.md) \ -[Linker Tools Warning LNK4216](../../error-messages/tool-errors/linker-tools-warning-lnk4216.md) \ -[Linker Tools Warning LNK4217](../../error-messages/tool-errors/linker-tools-warning-lnk4217.md) \ -[Linker Tools Warning LNK4219](../../error-messages/tool-errors/linker-tools-warning-lnk4219.md) \ -[Linker Tools Warning LNK4220](../../error-messages/tool-errors/linker-tools-warning-lnk4220.md) \ -[Linker Tools Warning LNK4221](../../error-messages/tool-errors/linker-tools-warning-lnk4221.md) \ -[Linker Tools Warning LNK4222](../../error-messages/tool-errors/linker-tools-warning-lnk4222.md) \ -[Linker Tools Warning LNK4224](../../error-messages/tool-errors/linker-tools-warning-lnk4224.md) \ -[Linker Tools Warning LNK4227](../../error-messages/tool-errors/linker-tools-warning-lnk4227.md) \ -[Linker Tools Warning LNK4229](../../error-messages/tool-errors/linker-tools-warning-lnk4229.md) \ -[Linker Tools Warning LNK4237](../../error-messages/tool-errors/linker-tools-warning-lnk4237.md) \ -[Linker Tools Warning LNK4247](../../error-messages/tool-errors/linker-tools-warning-lnk4247.md) \ -[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) +| Warning | Message | +|--|--| +| [Linker Tools Warning LNK4001](linker-tools-warning-lnk4001.md) | no object files specified; libraries used | +| [Linker Tools Warning LNK4002](linker-tools-warning-lnk4002.md) | symbol defined in object | +| [Linker Tools Warning LNK4006](linker-tools-warning-lnk4006.md) | symbol already defined in object; second definition ignored | +| [Linker Tools Warning LNK4010](linker-tools-warning-lnk4010.md) | invalid subsystem version number number; default subsystem version assumed | +| [Linker Tools Warning LNK4014](linker-tools-warning-lnk4014.md) | cannot find member object "objectname" | +| [Linker Tools Warning LNK4020](linker-tools-warning-lnk4020.md) | a type record in '*filename*' is corrupted; some symbols and types may not be accessible from the debugger | +| [Linker Tools Warning LNK4022](linker-tools-warning-lnk4022.md) | cannot find unique match for symbol 'symbol' | +| [Linker Tools Warning LNK4039](linker-tools-warning-lnk4039.md) | section 'name' specified with /SECTION option does not exist | +| [Linker Tools Warning LNK4044](linker-tools-warning-lnk4044.md) | unrecognized option 'option'; ignored | +| [Linker Tools Warning LNK4049](linker-tools-warning-lnk4049.md) | symbol '*symbol*' defined in '*filename.obj*' is imported | +| [Linker Tools Warning LNK4065](linker-tools-warning-lnk4065.md) | 'function' cannot be ordered; ignored | +| [Linker Tools Warning LNK4070](linker-tools-warning-lnk4070.md) | /OUT:filename directive in .EXP differs from output filename 'filename'; ignoring directive | +| [Linker Tools Warning LNK4071](linker-tools-warning-lnk4071.md) | cannot be incrementally linked on subsequent links | +| [Linker Tools Warning LNK4073](linker-tools-warning-lnk4073.md) | cannot create map for .ilk file; linking nonincrementally | +| [Linker Tools Warning LNK4075](linker-tools-warning-lnk4075.md) | ignoring "option1" due to "option2" specification | +| [Linker Tools Warning LNK4076](linker-tools-warning-lnk4076.md) | invalid incremental status file 'filename'; linking nonincrementally | +| [Linker Tools Warning LNK4078](linker-tools-warning-lnk4078.md) | multiple 'section name' sections found with different attributes | +| [Linker Tools Warning LNK4086](linker-tools-warning-lnk4086.md) | entrypoint 'function' is not __stdcall with 'number' bytes of arguments; image may not run | +| [Linker Tools Warning LNK4092](linker-tools-warning-lnk4092.md) | shared writable section 'section' contains relocations; image may not run correctly | +| [Linker Tools Warning LNK4096](linker-tools-warning-lnk4096.md) | /BASE value "number" is invalid for Windows 95 and Windows 98; image may not run | +| [Linker Tools Warning LNK4098](linker-tools-warning-lnk4098.md) | defaultlib '*library*' conflicts with use of other libs; use /NODEFAULTLIB:*library* | +| [Linker Tools Warning LNK4099](linker-tools-warning-lnk4099.md) | PDB 'filename' was not found with 'object/library' or at 'path'; linking object as if no debug info | +| [Linker Tools Warning LNK4102](linker-tools-warning-lnk4102.md) | export of deleting destructor 'name'; image may not run correctly | +| [Linker Tools Warning LNK4104](linker-tools-warning-lnk4104.md) | export of symbol 'symbol' should be PRIVATE | +| [Linker Tools Warning LNK4105](linker-tools-warning-lnk4105.md) | no argument specified with option 'option'; ignoring option | +| [Linker Tools Warning LNK4194](linker-tools-warning-lnk4194.md) | /DELAYLOAD:dll name ignored | +| [Linker Tools Warning LNK4197](linker-tools-warning-lnk4197.md) | export '*exportname*' specified multiple times; using first specification | +| [Linker Tools Warning LNK4199](linker-tools-warning-lnk4199.md) | /DELAYLOAD:dllname ignored; no imports found from dllname | +| [Linker Tools Warning LNK4200](linker-tools-warning-lnk4200.md) | corrupt line number information in object file; ignored | +| [Linker Tools Warning LNK4204](linker-tools-warning-lnk4204.md) | 'filename' is missing debugging information for referencing module; linking object as if no debug info | +| [Linker Tools Warning LNK4205](linker-tools-warning-lnk4205.md) | 'filename' is missing current debugging information for referencing module; linking object as if no debug info | +| [Linker Tools Warning LNK4206](linker-tools-warning-lnk4206.md) | precompiled type information not found; '*filename*' not linked or overwritten; linking object as if no debug info | +| [Linker Tools Warning LNK4210](linker-tools-warning-lnk4210.md) | section *section* exists; there may be unhandled static initializers or terminators | +| [Linker Tools Warning LNK4216](linker-tools-warning-lnk4216.md) | Exported entry point entry | +| [Linker Tools Warning LNK4217](linker-tools-warning-lnk4217.md) | symbol '*symbol*' defined in '*filename_1.obj*' is imported by '*filename_2.obj*' in function '*function*' | +| [Linker Tools Warning LNK4219](linker-tools-warning-lnk4219.md) | fixup name fixup overflow. Target 'target symbol name' is out of range, inserting thunk | +| [Linker Tools Warning LNK4220](linker-tools-warning-lnk4220.md) | invalid 'linker option' value 'value'; assumed default | +| [Linker Tools Warning LNK4221](linker-tools-warning-lnk4221.md) | This object file does not define any previously undefined public symbols, so it will not be used by any link operation that consumes this library | +| [Linker Tools Warning LNK4222](linker-tools-warning-lnk4222.md) | exported symbol 'symbol' should not be assigned an ordinal | +| [Linker Tools Warning LNK4224](linker-tools-warning-lnk4224.md) | *option* is no longer supported; ignored | +| [Linker Tools Warning LNK4227](linker-tools-warning-lnk4227.md) | metadata operation warning (*HRESULT*) : *warning_message* | +| [Linker Tools Warning LNK4229](linker-tools-warning-lnk4229.md) | invalid directive /directive found; ignored | +| [Linker Tools Warning LNK4237](linker-tools-warning-lnk4237.md) | /SUBSYSTEM:NATIVE specified when importing from 'dll'; Use /SUBSYSTEM:CONSOLE or /SUBSYSTEM:WINDOWS. | +| [Linker Tools Warning LNK4247](linker-tools-warning-lnk4247.md) | entry point 'decorated_function_name' already has a thread attribute; 'attribute' ignored | +| [Linker Tools Warning LNK4248](linker-tools-warning-lnk4248.md) | unresolved typeref token (token) for 'type'; image may not run | +| [Linker Tools Warning LNK4253](linker-tools-warning-lnk4253.md) | section 'section1' not merged into 'section2'; already merged into 'section3' | +| [Linker Tools Warning LNK4254](linker-tools-warning-lnk4254.md) | section 'section1' (offset) merged into 'section2' (offset) with different attributes | +| [Linker Tools Warning LNK4286](linker-tools-warning-lnk4286.md) | symbol '*symbol*' defined in '*filename_1.obj*' is imported by '*filename_2.obj*' | +| [Linker Tools Warning LNK4306](linker-tools-warning-lnk4306.md) | The auxiliary delayload import address table is not properly aligned with the primary delayload import address table. This may have negative perf impact. | +| [Linker Tools Warning LNK4307](linker-tools-warning-lnk4307.md) | The auxiliary delayload import address table copy is not properly aligned with the auxiliary delayload import address table. This may have negative perf impact. | ## See also diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4001.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4001.md index acead2979da..5a3f63068cc 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4001.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4001.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4001" title: "Linker Tools Warning LNK4001" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4001" +ms.date: 11/04/2016 f1_keywords: ["LNK4001"] helpviewer_keywords: ["LNK4001"] -ms.assetid: 0a8b1c3a-64ce-4311-b7c0-065995059246 --- # Linker Tools Warning LNK4001 -no object files specified; libraries used +> no object files specified; libraries used + +## Remarks The linker was passed one or more .lib files, but no .obj files. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4002.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4002.md index ac15b1573cc..71cff124cea 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4002.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4002.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4002" title: "Linker Tools Warning LNK4002" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4002" +ms.date: 11/04/2016 f1_keywords: ["LNK4002"] helpviewer_keywords: ["LNK4002"] -ms.assetid: 09f81af5-e51c-496c-a6eb-2863e85375c3 --- # Linker Tools Warning LNK4002 -symbol defined in object +> symbol defined in object + +## Remarks The symbol, displayed in its decorated form, was specified in its undecorated form in `object`, but a unique match to a decorated symbol could not be found. This warning is always preceded by warning [LNK4022](../../error-messages/tool-errors/linker-tools-warning-lnk4022.md) and followed by fatal error [LNK1152](../../error-messages/tool-errors/linker-tools-error-lnk1152.md). diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4006.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4006.md index b53d91f7c4a..8fd9e721fe0 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4006.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4006.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4006" title: "Linker Tools Warning LNK4006" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4006" +ms.date: 11/04/2016 f1_keywords: ["LNK4006"] helpviewer_keywords: ["LNK4006"] -ms.assetid: 3a637d17-1676-4ea6-bd8b-290137d28d3b --- # Linker Tools Warning LNK4006 -symbol already defined in object; second definition ignored +> symbol already defined in object; second definition ignored + +## Remarks The given `symbol`, displayed in its decorated form, was multiply defined. When this warning is encountered, `symbol` will be added twice, but only its first form will be used. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4010.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4010.md index 64f217c9de3..a586214ca26 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4010.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4010.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4010" title: "Linker Tools Warning LNK4010" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4010" +ms.date: 11/04/2016 f1_keywords: ["LNK4010"] helpviewer_keywords: ["LNK4010"] -ms.assetid: 2824cf99-4174-4b60-a6e2-c01e9f1ee52d --- # Linker Tools Warning LNK4010 -invalid subsystem version number number; default subsystem version assumed +> invalid subsystem version number number; default subsystem version assumed + +## Remarks You can specify a version for the image's subsystem ([/SUBSYSTEM](../../build/reference/subsystem-specify-subsystem.md)). Each subsystem has a minimum version requirement. If the specified version is lower than the minimum, this warning will occur and the linker will just use the default subsystem. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4014.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4014.md index fed59984e71..d073124ac8c 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4014.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4014.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4014" title: "Linker Tools Warning LNK4014" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4014" +ms.date: 11/04/2016 f1_keywords: ["LNK4014"] helpviewer_keywords: ["LNK4014"] -ms.assetid: 394903e9-3ded-4ea4-b7c0-a3535d4b4da4 --- # Linker Tools Warning LNK4014 -cannot find member object "objectname" +> cannot find member object "objectname" + +## Remarks LIB could not find `objectname` in the library. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4020.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4020.md index 264bda4b079..913227f12fa 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4020.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4020.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Linker Tools Warning LNK4020" title: "Linker Tools Warning LNK4020" -ms.date: "05/29/2018" +description: "Learn more about: Linker Tools Warning LNK4020" +ms.date: 05/29/2018 f1_keywords: ["LNK4020"] helpviewer_keywords: ["LNK4020"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["LNK4020"] > a type record in '*filename*' is corrupted; some symbols and types may not be accessible from the debugger +## Remarks + The PDB file *filename* has a corrupted type record. This issue is often secondary to other build issues; unless this is the first reported build issue, deal with the other errors and warnings first. If this is the first reported issue, you may need to clean your build directories and rebuild your project. If you use parallel build processes, see if the error persists when you serialize your build. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4022.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4022.md index 49b2a8b1866..b8629ec6796 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4022.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4022.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4022" title: "Linker Tools Warning LNK4022" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4022" +ms.date: 11/04/2016 f1_keywords: ["LNK4022"] helpviewer_keywords: ["LNK4022"] -ms.assetid: 890f487e-db98-45dd-a226-c7ccead82b1e --- # Linker Tools Warning LNK4022 -cannot find unique match for symbol 'symbol' +> cannot find unique match for symbol 'symbol' + +## Remarks LINK or LIB found multiple matches for the given undecorated symbol and it could not resolve the ambiguity. No output file (.exe, .dll, .exp, or .lib) is produced. This warning is followed by one warning [LNK4002](../../error-messages/tool-errors/linker-tools-warning-lnk4002.md) for each duplicate symbol and is finally followed by fatal error [LNK1152](../../error-messages/tool-errors/linker-tools-error-lnk1152.md). diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4037.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4037.md index 271d321252a..2eafbb1026b 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4037.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4037.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4037" title: "Linker Tools Warning LNK4037" -ms.date: "10/04/2017" +description: "Learn more about: Linker Tools Warning LNK4037" +ms.date: 10/04/2017 f1_keywords: ["LNK4037"] helpviewer_keywords: ["LNK4037"] -ms.assetid: 9ba02fd3-b04f-4679-bab9-26fa82cf09bb --- # Linker Tools Warning LNK4037 ->'*symbol*' does not exist; ignored +> '*symbol*' does not exist; ignored + +## Remarks The decorated name *symbol* could not be ordered by using the [/ORDER](../../build/reference/order-put-functions-in-order.md) option because it could not be found in the program. Check the specification of *symbol* in the order response file. For more information, see the [/ORDER (Put functions in order)](../../build/reference/order-put-functions-in-order.md) linker option. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4039.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4039.md index 408939d9f3f..c86c2783939 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4039.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4039.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4039" title: "Linker Tools Warning LNK4039" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4039" +ms.date: 11/04/2016 f1_keywords: ["LNK4039"] helpviewer_keywords: ["LNK4039"] -ms.assetid: ed7b1783-a7b2-4d3e-8afb-ca1648dae2c2 --- # Linker Tools Warning LNK4039 -section 'name' specified with /SECTION option does not exist +> section 'name' specified with /SECTION option does not exist + +## Remarks [DUMPBIN](../../build/reference/dumpbin-reference.md) or [EDITBIN](../../build/reference/editbin-reference.md) could not find a section called `name` in the input file. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4044.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4044.md index 6f46ad0a097..3852e8bb3b7 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4044.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4044.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4044" title: "Linker Tools Warning LNK4044" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4044" +ms.date: 11/04/2016 f1_keywords: ["LNK4044"] helpviewer_keywords: ["LNK4044"] -ms.assetid: f3a67a15-98c0-42ed-afcb-f5f9540e2671 --- # Linker Tools Warning LNK4044 -unrecognized option 'option'; ignored +> unrecognized option 'option'; ignored + +## Remarks The given option is not a valid option for this tool. The tool ignored the option. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4049.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4049.md index 2a99ccb7648..7f6c8738fa3 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4049.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4049.md @@ -1,19 +1,18 @@ --- -description: "Learn more about: Linker Tools Warning LNK4049" title: "Linker Tools Warning LNK4049" -ms.date: "04/15/2019" +description: "Learn more about: Linker Tools Warning LNK4049" +ms.date: 04/15/2019 f1_keywords: ["LNK4049"] helpviewer_keywords: ["LNK4049"] -ms.assetid: 5fd5fb24-c860-4149-a557-0ac26a65d97c --- # Linker Tools Warning LNK4049 > symbol '*symbol*' defined in '*filename.obj*' is imported -[__declspec(dllimport)](../../cpp/dllexport-dllimport.md) was specified for *symbol* even though the symbol is defined in object file *filename.obj* in the same image. Remove the `__declspec(dllimport)` modifier to resolve this warning. - ## Remarks +[__declspec(dllimport)](../../cpp/dllexport-dllimport.md) was specified for *symbol* even though the symbol is defined in object file *filename.obj* in the same image. Remove the `__declspec(dllimport)` modifier to resolve this warning. + This warning is generated by the linker when you define a symbol in one object file and reference it by using the `__declspec(dllimport)` declaration modifier in another. Warning LNK4049 is a more general version of [Linker Tools Warning LNK4217](linker-tools-warning-lnk4217.md). The linker generates warning LNK4049 when it can't determine which function or object file referenced the imported symbol. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4065.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4065.md index 0313df14016..866c8e515fb 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4065.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4065.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4065" title: "Linker Tools Warning LNK4065" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4065" +ms.date: 11/04/2016 f1_keywords: ["LNK4065"] helpviewer_keywords: ["LNK4065"] -ms.assetid: aa5c9e2c-9ad3-4460-8605-4c12bbc6d423 --- # Linker Tools Warning LNK4065 -'function' cannot be ordered; ignored +> 'function' cannot be ordered; ignored + +## Remarks The given function was not compiled as a packaged function. Recompile using [/Gy](../../build/reference/gy-enable-function-level-linking.md). diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4070.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4070.md index 2d4a8c774ae..73002b55e0a 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4070.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4070.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4070" title: "Linker Tools Warning LNK4070" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4070" +ms.date: 11/04/2016 f1_keywords: ["LNK4070"] helpviewer_keywords: ["LNK4070"] -ms.assetid: f95f179a-fff9-427e-bd51-466b3934517f --- # Linker Tools Warning LNK4070 -/OUT:filename directive in .EXP differs from output filename 'filename'; ignoring directive +> /OUT:filename directive in .EXP differs from output filename 'filename'; ignoring directive + +## Remarks The `filename` specified in the [NAME](../../build/reference/name-c-cpp.md) or [LIBRARY](../../build/reference/library.md) statement when the .exp file was created differs from the output `filename` that was either assumed by default or specified with the [/OUT](../../build/reference/out-output-file-name.md) option. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4071.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4071.md index 83437b5126a..f11ad7b9b8f 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4071.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4071.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4071" title: "Linker Tools Warning LNK4071" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4071" +ms.date: 11/04/2016 f1_keywords: ["LNK4071"] helpviewer_keywords: ["LNK4071"] -ms.assetid: 803f8c34-8219-4f55-a4ae-7133ceff2ba3 --- # Linker Tools Warning LNK4071 -cannot be incrementally linked on subsequent links +> cannot be incrementally linked on subsequent links + +## Remarks LINK found multiple definitions for one or more symbols, but [/FORCE](../../build/reference/force-force-file-output.md) or **/FORCE:MULTIPLE** was used to create an output file regardless of errors. LINK deleted the incremental status (.ilk) file. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4073.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4073.md index 121c6eaadbc..0347c6cd330 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4073.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4073.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4073" title: "Linker Tools Warning LNK4073" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4073" +ms.date: 11/04/2016 f1_keywords: ["LNK4073"] helpviewer_keywords: ["LNK4073"] -ms.assetid: a0c80242-3395-45bd-bbe7-4f31d7ac9e3a --- # Linker Tools Warning LNK4073 -cannot create map for .ilk file; linking nonincrementally +> cannot create map for .ilk file; linking nonincrementally + +## Remarks There was not a large enough contiguous space in shared memory for LINK to create the incremental status (.ilk) file. LINK performed a nonincremental build. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4075.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4075.md index d68c11580e0..30c7c247f9c 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4075.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4075.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4075" title: "Linker Tools Warning LNK4075" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4075" +ms.date: 11/04/2016 f1_keywords: ["LNK4075"] helpviewer_keywords: ["LNK4075"] -ms.assetid: f39ad3f9-c263-4cf0-9d70-259fc56ac96d --- # Linker Tools Warning LNK4075 -ignoring "option1" due to "option2" specification +> ignoring "option1" due to "option2" specification + +## Remarks The second option overrides the first. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4076.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4076.md index 34b7ca35901..2f5ab3ac799 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4076.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4076.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4076" title: "Linker Tools Warning LNK4076" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4076" +ms.date: 11/04/2016 f1_keywords: ["LNK4076"] helpviewer_keywords: ["LNK4076"] -ms.assetid: c424d43b-abb3-4df4-be66-8907b859a555 --- # Linker Tools Warning LNK4076 -invalid incremental status file 'filename'; linking nonincrementally +> invalid incremental status file 'filename'; linking nonincrementally + +## Remarks LINK cannot write to the incremental status (.ilk) file. Either `filename` is corrupt or it is not an incremental linking database. Remove the file and relink. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4078.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4078.md index 407078f7750..977fec14c67 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4078.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4078.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4078" title: "Linker Tools Warning LNK4078" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4078" +ms.date: 11/04/2016 f1_keywords: ["LNK4078"] helpviewer_keywords: ["LNK4078"] -ms.assetid: 5a16796d-6caf-42d9-8f65-b042843eafb8 --- # Linker Tools Warning LNK4078 -multiple 'section name' sections found with different attributes +> multiple 'section name' sections found with different attributes + +## Remarks LINK found two or more sections that have the same name but different attributes. @@ -20,7 +21,7 @@ Recreate the file and relink. LNK4078 can also be caused by a breaking change: the section named by [init_seg](../../preprocessor/init-seg.md) on x86 was read/write, it is now read only. -The following sample generates LNK4078. +The following example generates LNK4078. ```cpp // LNK4078.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4086.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4086.md index c41c539e819..3e04f4741cd 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4086.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4086.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4086" title: "Linker Tools Warning LNK4086" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4086" +ms.date: 11/04/2016 f1_keywords: ["LNK4086"] helpviewer_keywords: ["LNK4086"] -ms.assetid: ea1eecbb-ba2c-41bb-9a4f-fa0808a4b92d --- # Linker Tools Warning LNK4086 -entrypoint 'function' is not __stdcall with 'number' bytes of arguments; image may not run +> entrypoint 'function' is not __stdcall with 'number' bytes of arguments; image may not run + +## Remarks The entry point for a DLL must be **`__stdcall`**. Either recompile the function with the [/Gz](../../build/reference/gd-gr-gv-gz-calling-convention.md) option or specify **`__stdcall`** or WINAPI when you define the function. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4092.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4092.md index 952fb421cd8..8db800d129a 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4092.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4092.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4092" title: "Linker Tools Warning LNK4092" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4092" +ms.date: 11/04/2016 f1_keywords: ["LNK4092"] helpviewer_keywords: ["LNK4092"] -ms.assetid: d569ec47-a338-40e1-940b-8a8061459acb --- # Linker Tools Warning LNK4092 -shared writable section 'section' contains relocations; image may not run correctly +> shared writable section 'section' contains relocations; image may not run correctly + +## Remarks The linker emits this warning whenever you have a shared section to warn you of a potentially serious problem. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4096.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4096.md index 51afe7b4cf2..239b7d127b1 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4096.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4096.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4096" title: "Linker Tools Warning LNK4096" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4096" +ms.date: 11/04/2016 f1_keywords: ["LNK4096"] helpviewer_keywords: ["LNK4096"] -ms.assetid: ef6fba38-59a1-4d86-bcac-cadf44d87a36 --- # Linker Tools Warning LNK4096 -/BASE value "number" is invalid for Windows 95 and Windows 98; image may not run +> /BASE value "number" is invalid for Windows 95 and Windows 98; image may not run + +## Remarks The base address you specified is invalid. Windows 95 and Windows 98 executable files must have a base address greater than 0x400000. For more information on base addresses, see the [/BASE](../../build/reference/base-base-address.md) linker option. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4098.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4098.md index 114be4256bc..d978b129442 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4098.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4098.md @@ -1,15 +1,16 @@ --- title: "Linker Tools Warning LNK4098" description: "Describes how incompatible libraries cause linker tools warning LNK4098, and how to use /NODEFAULTLIB to fix it." -ms.date: "12/02/2019" +ms.date: 12/02/2019 f1_keywords: ["LNK4098"] helpviewer_keywords: ["LNK4098"] -ms.assetid: 1f1b1408-1316-4e34-80f5-6a02f2db0ac1 --- # Linker Tools Warning LNK4098 > defaultlib '*library*' conflicts with use of other libs; use /NODEFAULTLIB:*library* +## Remarks + You're trying to link with incompatible libraries. > [!NOTE] diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4099.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4099.md index 1883d934dfa..658a4303a78 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4099.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4099.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4099" title: "Linker Tools Warning LNK4099" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4099" +ms.date: 11/04/2016 f1_keywords: ["LNK4099"] helpviewer_keywords: ["LNK4099"] -ms.assetid: 358170a4-07cd-43fe-918f-82c32757ffc5 --- # Linker Tools Warning LNK4099 -PDB 'filename' was not found with 'object/library' or at 'path'; linking object as if no debug info +> PDB 'filename' was not found with 'object/library' or at 'path'; linking object as if no debug info + +## Remarks The linker was unable to find your .pdb file. Copy it into the directory that contains `object/library`. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4102.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4102.md index 126e92d5743..946bbf5a630 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4102.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4102.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4102" title: "Linker Tools Warning LNK4102" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4102" +ms.date: 11/04/2016 f1_keywords: ["LNK4102"] helpviewer_keywords: ["LNK4102"] -ms.assetid: bfd1b17e-05c7-4bc2-80d6-2888b1a425b2 --- # Linker Tools Warning LNK4102 -export of deleting destructor 'name'; image may not run correctly +> export of deleting destructor 'name'; image may not run correctly + +## Remarks The program has attempted to export a deleting destructor. The resulting delete may occur across a DLL boundary such that a process can free memory that it does not own. Make sure that the given symbol is not listed in your .def file, and that the symbol is not listed as an argument of the **/IMPORT** or **/EXPORT** option in the linker command line. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4104.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4104.md index 3b3226b097e..f606c690933 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4104.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4104.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4104" title: "Linker Tools Warning LNK4104" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4104" +ms.date: 11/04/2016 f1_keywords: ["LNK4104"] helpviewer_keywords: ["LNK4104"] -ms.assetid: ca6728db-d616-419a-a570-65e8445c6079 --- # Linker Tools Warning LNK4104 -export of symbol 'symbol' should be PRIVATE +> export of symbol 'symbol' should be PRIVATE + +## Remarks The `symbol` can be one of the following: diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4105.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4105.md index eb82ea21e7c..aebda983258 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4105.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4105.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4105" title: "Linker Tools Warning LNK4105" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4105" +ms.date: 11/04/2016 f1_keywords: ["LNK4105"] helpviewer_keywords: ["LNK4105"] -ms.assetid: 6c7bebf4-4ea6-4533-a6ed-e563d43abbd7 --- # Linker Tools Warning LNK4105 -no argument specified with option 'option'; ignoring option +> no argument specified with option 'option'; ignoring option + +## Remarks This warning occurs only when the [/LIBPATH](../../build/reference/libpath-additional-libpath.md) option is set. If no directory is specified with this option, then the linker ignores the option and generates this warning message. @@ -16,7 +17,7 @@ If you do not need to override the existing environmental library settings, remo ## Example -``` +```cmd link /libpath:c:\filepath\lib bar.obj ``` diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4194.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4194.md index f22bd2a4fc2..c9c5896215b 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4194.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4194.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4194" title: "Linker Tools Warning LNK4194" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4194" +ms.date: 11/04/2016 f1_keywords: ["LNK4194"] helpviewer_keywords: ["LNK4194"] -ms.assetid: a45f437e-33b5-487e-b3cd-ff1560041e7e --- # Linker Tools Warning LNK4194 -/DELAYLOAD:dll name ignored +> /DELAYLOAD:dll name ignored + +## Remarks The linker cannot [delay load](../../build/reference/delayload-delay-load-import.md) the requested DLL. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4197.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4197.md index 2bddca715ac..9bbeb584794 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4197.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4197.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Warning LNK4197" title: "Linker Tools Warning LNK4197" -ms.date: "09/05/2018" +description: "Learn more about: Linker Tools Warning LNK4197" +ms.date: 09/05/2018 f1_keywords: ["LNK4197"] helpviewer_keywords: ["LNK4197"] -ms.assetid: 8a976fd7-a74b-4c83-ab66-a9e7d7073c4a --- # Linker Tools Warning LNK4197 > export '*exportname*' specified multiple times; using first specification +## Remarks + An export is specified in multiple and different ways. The linker uses the first specification and ignores the rest. If you are rebuilding the C run-time library, you can ignore this message. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4199.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4199.md index 04a8983c778..e4656fa2516 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4199.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4199.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4199" title: "Linker Tools Warning LNK4199" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4199" +ms.date: 11/04/2016 f1_keywords: ["LNK4199"] helpviewer_keywords: ["LNK4199"] -ms.assetid: 724f1ca8-ee9a-4ca3-b5c6-c0284a5195e7 --- # Linker Tools Warning LNK4199 -/DELAYLOAD:dllname ignored; no imports found from dllname +> /DELAYLOAD:dllname ignored; no imports found from dllname + +## Remarks The linker ignores `dllname` because it does not need any of the functions that `dllname` exports. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4200.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4200.md index 558e5ec0f5e..d9c40abaeb2 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4200.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4200.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4200" title: "Linker Tools Warning LNK4200" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4200" +ms.date: 11/04/2016 f1_keywords: ["LNK4200"] helpviewer_keywords: ["LNK4200"] -ms.assetid: 0d335e69-8766-455b-beb5-a3ba6247274e --- # Linker Tools Warning LNK4200 -corrupt line number information in object file; ignored +> corrupt line number information in object file; ignored + +## Remarks The line number information in the object file is corrupt. Rebuild. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4204.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4204.md index f9949c94b46..96f393a24fa 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4204.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4204.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4204" title: "Linker Tools Warning LNK4204" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4204" +ms.date: 11/04/2016 f1_keywords: ["LNK4204"] helpviewer_keywords: ["LNK4204"] -ms.assetid: 14adda20-0cbe-407b-90f6-9f81c93530e2 --- # Linker Tools Warning LNK4204 -'filename' is missing debugging information for referencing module; linking object as if no debug info +> 'filename' is missing debugging information for referencing module; linking object as if no debug info + +## Remarks The .pdb file has an erroneous signature. The linker will continue to link the object without debug information. You may want to recompile the object file using the [/Zi](../../build/reference/z7-zi-zi-debug-information-format.md) option. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4205.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4205.md index 6f77534f6fc..f693330b8d4 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4205.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4205.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4205" title: "Linker Tools Warning LNK4205" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4205" +ms.date: 11/04/2016 f1_keywords: ["LNK4205"] helpviewer_keywords: ["LNK4205"] -ms.assetid: d63b9d18-ef3c-4081-9d8d-93077dad13c2 --- # Linker Tools Warning LNK4205 -'filename' is missing current debugging information for referencing module; linking object as if no debug info +> 'filename' is missing current debugging information for referencing module; linking object as if no debug info + +## Remarks The .pdb file has out-of-date information. The linker will continue to link object without debug information. You may want to recompile the object file using the [/Zi](../../build/reference/z7-zi-zi-debug-information-format.md) option. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4206.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4206.md index 6d954982e46..61b490f8294 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4206.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4206.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Warning LNK4206" title: "Linker Tools Warning LNK4206" -ms.date: "12/05/2017" +description: "Learn more about: Linker Tools Warning LNK4206" +ms.date: 12/05/2017 f1_keywords: ["LNK4206"] helpviewer_keywords: ["LNK4206"] -ms.assetid: 6c108e33-00cf-4c5a-830d-d65d470930a7 --- # Linker Tools Warning LNK4206 > precompiled type information not found; '*filename*' not linked or overwritten; linking object as if no debug info +## Remarks + The *filename* object file, compiled by using [/Yc](../../build/reference/yc-create-precompiled-header-file.md), was either not specified in the LINK command or was overwritten. A common scenario for this warning is when the .obj that was compiled with /Yc is in a library, and where there are no symbol references to that .obj from your code. In that case, the linker will not use (or even see) the .obj file. In this situation, you should recompile your code and use [/Yl](../../build/reference/yl-inject-pch-reference-for-debug-library.md) for the objects compiled by using [/Yu](../../build/reference/yu-use-precompiled-header-file.md). diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4210.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4210.md index 437489e9ad0..56405b00d56 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4210.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4210.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Warning LNK4210" title: "Linker Tools Warning LNK4210" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4210" +ms.date: 11/04/2016 f1_keywords: ["LNK4210"] helpviewer_keywords: ["LNK4210"] -ms.assetid: db48cff8-a2be-4a77-8d03-552b42c228fa --- # Linker Tools Warning LNK4210 diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4216.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4216.md index 167ab652430..4b1dddb3f23 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4216.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4216.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4216" title: "Linker Tools Warning LNK4216" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4216" +ms.date: 11/04/2016 f1_keywords: ["LNK4216"] helpviewer_keywords: ["LNK4216"] -ms.assetid: 68512095-acbc-47aa-96bf-9eb0e73b24a3 --- # Linker Tools Warning LNK4216 -Exported entry point entry +> Exported entry point entry + +## Remarks An entry point was exported from a DLL. The entry point of a DLL does not need to be exported. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md index 5c414ede438..b1dfa793fb4 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4217.md @@ -1,23 +1,24 @@ --- -description: "Learn more about: Linker Tools Warning LNK4217" title: "Linker Tools Warning LNK4217" -ms.date: "07/23/2019" +description: "Learn more about: Linker Tools Warning LNK4217" +ms.date: 07/23/2019 f1_keywords: ["LNK4217"] helpviewer_keywords: ["LNK4217"] -ms.assetid: 280dc03e-5933-4e8d-bb8c-891fbe788738 --- # Linker Tools Warning LNK4217 > symbol '*symbol*' defined in '*filename_1.obj*' is imported by '*filename_2.obj*' in function '*function*' -[__declspec(dllimport)](../../cpp/dllexport-dllimport.md) was specified for a symbol even though the symbol is defined in an object file in the same image. Remove the `__declspec(dllimport)` modifier to resolve this warning. - ## Remarks +[__declspec(dllimport)](../../cpp/dllexport-dllimport.md) was specified for a symbol even though the symbol is defined in an object file in the same image. Remove the `__declspec(dllimport)` modifier to resolve this warning. + *symbol* is the symbol name that's defined within the image. *function* is the function that's importing the symbol. This warning doesn't appear when you compile by using the [/clr](../../build/reference/clr-common-language-runtime-compilation.md) option. +## Example + LNK4217 can also occur if you attempt to link two modules together, when instead you should compile the second module with the import library of the first module. ```cpp @@ -29,7 +30,6 @@ int main() func(); return 0; } - ``` And then, diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4219.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4219.md index ca1f30a8c38..1088a47bd68 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4219.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4219.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4219" title: "Linker Tools Warning LNK4219" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4219" +ms.date: 11/04/2016 f1_keywords: ["LNK4219"] helpviewer_keywords: ["LNK4219"] -ms.assetid: 363fedf4-b10c-4985-811a-55a9fba688d6 --- # Linker Tools Warning LNK4219 -fixup name fixup overflow. Target 'target symbol name' is out of range, inserting thunk +> fixup name fixup overflow. Target 'target symbol name' is out of range, inserting thunk + +## Remarks The linker inserted a thunk in a situation where the address or offset was unable to fit in the given instruction because the target symbol is too far away from the instruction's location. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4220.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4220.md index 3bd2a43b6ec..11b83b45f5e 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4220.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4220.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4220" title: "Linker Tools Warning LNK4220" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4220" +ms.date: 11/04/2016 f1_keywords: ["LNK4220"] helpviewer_keywords: ["LNK4220"] -ms.assetid: ba0cddfc-9c56-4a09-8207-f7b840a24b4d --- # Linker Tools Warning LNK4220 -invalid 'linker option' value 'value'; assumed default +> invalid 'linker option' value 'value'; assumed default + +## Remarks An out-of-range value was specified with the [/TLBID](../../build/reference/tlbid-specify-resource-id-for-typelib.md) option. The default value for **/TLBID** is 1. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md index 9fae0c56fd9..e137bfa2f46 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4221.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Warning LNK4221" title: "Linker Tools Warning LNK4221" +description: "Learn more about: Linker Tools Warning LNK4221" ms.date: 06/29/2022 f1_keywords: ["LNK4221"] helpviewer_keywords: ["LNK4221"] -ms.assetid: 8e2eb2de-9532-4b85-908a-8c9ff5c4cccb --- # Linker Tools Warning LNK4221 > This object file does not define any previously undefined public symbols, so it will not be used by any link operation that consumes this library +## Example + Consider the following two code snippets, `a.cpp`: ```cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4222.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4222.md index e55acea5515..3f20f3c7ae0 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4222.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4222.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4222" title: "Linker Tools Warning LNK4222" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4222" +ms.date: 11/04/2016 f1_keywords: ["LNK4222"] helpviewer_keywords: ["LNK4222"] -ms.assetid: b7bb1794-41fb-4c83-b9b0-59c0d786a7da --- # Linker Tools Warning LNK4222 -exported symbol 'symbol' should not be assigned an ordinal +> exported symbol 'symbol' should not be assigned an ordinal + +## Remarks The following symbols should not be exported by ordinal: diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4224.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4224.md index 0c52b3130a7..a9794db869a 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4224.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4224.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Linker Tools Warning LNK4224" title: "Linker Tools Warning LNK4224" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4224" +ms.date: 11/04/2016 f1_keywords: ["LNK4224"] helpviewer_keywords: ["LNK4224"] -ms.assetid: 8624b70e-0b93-43cf-b457-834d38632d0b --- # Linker Tools Warning LNK4224 @@ -20,7 +19,7 @@ If possible, modify the source for the .obj and remove the pragma. If you do ign ## Example -The following sample generates LNK4224. +The following example generates LNK4224. ```cpp // LNK4224.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4227.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4227.md index 4437621ee75..6cab69aeb42 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4227.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4227.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Linker Tools Warning LNK4227" title: "Linker Tools Warning LNK4227" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4227" +ms.date: 11/04/2016 f1_keywords: ["LNK4227"] helpviewer_keywords: ["LNK4227"] -ms.assetid: 941a0414-9964-4e02-8487-f9daa42ef7f9 --- # Linker Tools Warning LNK4227 > metadata operation warning (*HRESULT*) : *warning_message* +## Remarks + The linker detected metadata differences when merging: - One or more referenced assemblies with the assembly currently being built. @@ -26,7 +27,7 @@ The metadata problems must be fixed to resolve the warning. LNK4227 is generated when a referenced assembly was signed differently than the assembly that references it. -The following sample generates LNK4227: +The following example generates LNK4227: ```cpp // LNK4227.cpp @@ -57,7 +58,7 @@ ref class MyClass LNK4227 can also be generated when version numbers in the wrong format are passed to assembly attributes. The '*' notation is specific to the `AssemblyVersionAttribute`. To resolve this warning, use only numbers in the version attributes other than `AssemblyVersionAttribute`. -The following sample generates LNK4227: +The following example generates LNK4227: ```cpp // LNK4227e.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4229.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4229.md index 1000e70de37..7452fa173e5 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4229.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4229.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Linker Tools Warning LNK4229" title: "Linker Tools Warning LNK4229" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4229" +ms.date: 11/04/2016 f1_keywords: ["LNK4229"] helpviewer_keywords: ["LNK4229"] -ms.assetid: 00e70d09-efd8-4e4e-8d48-6ba282c32ec1 --- # Linker Tools Warning LNK4229 -invalid directive /directive found; ignored +> invalid directive /directive found; ignored + +## Remarks A directive passed via the [comment](../../preprocessor/comment-c-cpp.md) pragma was not valid. The linker ignores `/directive`. diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4237.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4237.md index 412f1348d52..3cc9490ee77 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4237.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4237.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4237" title: "Linker Tools Warning LNK4237" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4237" +ms.date: 11/04/2016 f1_keywords: ["LNK4237"] helpviewer_keywords: ["LNK4237"] -ms.assetid: 87bfec39-5241-464f-9feb-517b49f352ea --- # Linker Tools Warning LNK4237 -/SUBSYSTEM:NATIVE specified when importing from 'dll'; Use /SUBSYSTEM:CONSOLE or /SUBSYSTEM:WINDOWS. +> /SUBSYSTEM:NATIVE specified when importing from 'dll'; Use /SUBSYSTEM:CONSOLE or /SUBSYSTEM:WINDOWS. + +## Remarks [/SUBSYSTEM:NATIVE](../../build/reference/subsystem-specify-subsystem.md) was specified when building a windows (Win32) application that directly uses one or more of the following: diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4247.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4247.md index f0f4ec5f2ce..c72d8eb71d3 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4247.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4247.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4247" title: "Linker Tools Warning LNK4247" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4247" +ms.date: 11/04/2016 f1_keywords: ["LNK4247"] helpviewer_keywords: ["LNK4247"] -ms.assetid: 085d7fdf-9eaf-4641-8473-6eaadd073c7b --- # Linker Tools Warning LNK4247 -entry point 'decorated_function_name' already has a thread attribute; 'attribute' ignored +> entry point 'decorated_function_name' already has a thread attribute; 'attribute' ignored + +## Remarks An entry point, specified with [/ENTRY (Entry-Point Symbol)](../../build/reference/entry-entry-point-symbol.md), had a threading attribute, but [/CLRTHREADATTRIBUTE (Set CLR Thread Attribute)](../../build/reference/clrthreadattribute-set-clr-thread-attribute.md) was also specified, with a different threading model. @@ -26,7 +27,9 @@ To resolve this warning: - Change the attribute in source, such that, it agrees with the value passed to /CLRTHREADATTRIBUTE. -The following sample generates LNK4247 +## Example + +The following example generates LNK4247 ```cpp // LNK4247.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md index 51158a3942d..6cf871ff31f 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4248.md @@ -1,16 +1,17 @@ --- -description: "Learn more about: Linker Tools Warning LNK4248" title: "Linker Tools Warning LNK4248" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4248" +ms.date: 11/04/2016 f1_keywords: ["LNK4248"] helpviewer_keywords: ["LNK4248"] -ms.assetid: e40523ff-e3cb-4ba6-ab79-23f0f339f6cf --- # Linker Tools Warning LNK4248 -unresolved typeref token (token) for 'type'; image may not run +> unresolved typeref token (token) for 'type'; image may not run + +## Remarks -A type doesn’t have a definition in MSIL metadata. +A type doesn't have a definition in MSIL metadata. LNK4248 can occur when there is only a forward declaration for a type in an MSIL module (compiled with **/clr**), where the type is referenced in the MSIL module, and where the MSIL module is linked with a native module that has a definition for the type. @@ -26,7 +27,7 @@ For more information, see [/clr (Common Language Runtime Compilation)](../../bui ## Examples -The following sample generates LNK4248. Define struct A to resolve. +The following example generates LNK4248. Define struct A to resolve. ```cpp // LNK4248.cpp @@ -40,7 +41,7 @@ int main() { } ``` -The following sample has a forward definition of a type. +The following example has a forward definition of a type. ```cpp // LNK4248_2.cpp @@ -55,7 +56,7 @@ int main() { } ``` -The following sample generates LNK4248. +The following example generates LNK4248. ```cpp // LNK4248_3.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4253.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4253.md index 38406cb0aca..5ccccd7822f 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4253.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4253.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4253" title: "Linker Tools Warning LNK4253" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4253" +ms.date: 11/04/2016 f1_keywords: ["LNK4253"] helpviewer_keywords: ["LNK4253"] -ms.assetid: ec7433a9-aa9c-495a-a9f2-075e7bc3e7bc --- # Linker Tools Warning LNK4253 -section 'section1' not merged into 'section2'; already merged into 'section3' +> section 'section1' not merged into 'section2'; already merged into 'section3' + +## Remarks The linker detected multiple, conflicting merge requests. The linker will ignore one of the requests. @@ -26,7 +27,7 @@ For more information, see, ## Example -In the following sample, the linker is instructed to merge the `.rdata` section twice, but into different sections. The following sample generates LNK4253. +In the following example, the linker is instructed to merge the `.rdata` section twice, but into different sections. The following example generates LNK4253. ```cpp // LNK4253.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4254.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4254.md index cad2b204d0a..a43282f7879 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4254.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4254.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Linker Tools Warning LNK4254" title: "Linker Tools Warning LNK4254" -ms.date: "11/04/2016" +description: "Learn more about: Linker Tools Warning LNK4254" +ms.date: 11/04/2016 f1_keywords: ["LNK4254"] helpviewer_keywords: ["LNK4254"] -ms.assetid: 6f41dfb3-ca21-40d3-bac7-b637e578efa4 --- # Linker Tools Warning LNK4254 -section 'section1' (offset) merged into 'section2' (offset) with different attributes +> section 'section1' (offset) merged into 'section2' (offset) with different attributes + +## Remarks The contents of one section were merged into another, but the attributes of the two sections are different. Your program may give unexpected results. For example, data you wanted to be read only may now be in a writable section. @@ -24,7 +25,7 @@ For more information, see, ## Example -The following sample generates LNK4254. +The following example generates LNK4254. ```cpp // LNK4254.cpp diff --git a/docs/error-messages/tool-errors/linker-tools-warning-lnk4286.md b/docs/error-messages/tool-errors/linker-tools-warning-lnk4286.md index 7ba15860964..41cd2a2ed46 100644 --- a/docs/error-messages/tool-errors/linker-tools-warning-lnk4286.md +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4286.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Linker Tools Warning LNK4286" title: "Linker Tools Warning LNK4286" -ms.date: "04/15/2019" +description: "Learn more about: Linker Tools Warning LNK4286" +ms.date: 04/15/2019 f1_keywords: ["LNK4286"] helpviewer_keywords: ["LNK4286"] --- @@ -9,10 +9,10 @@ helpviewer_keywords: ["LNK4286"] > symbol '*symbol*' defined in '*filename_1.obj*' is imported by '*filename_2.obj*' -[__declspec(dllimport)](../../cpp/dllexport-dllimport.md) was specified for *symbol* even though the symbol is defined in object file *filename_1.obj* in the same image. Remove the `__declspec(dllimport)` modifier to resolve this warning. - ## Remarks +[__declspec(dllimport)](../../cpp/dllexport-dllimport.md) was specified for *symbol* even though the symbol is defined in object file *filename_1.obj* in the same image. Remove the `__declspec(dllimport)` modifier to resolve this warning. + Warning LNK4286 is a more general version of [Linker Tools Warning LNK4217](linker-tools-warning-lnk4217.md). The linker generates Warning LNK4286 when it can tell which object file referenced the symbol, but not which function. To resolve LNK4286, remove the `__declspec(dllimport)` declaration modifier from the forward declaration of *symbol* referenced in *filename_2.obj*. 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 00000000000..399ff2c7d4c --- /dev/null +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4306.md @@ -0,0 +1,16 @@ +--- +title: "Linker tools warning LNK4306" +description: "Learn more about: 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. + +## Remarks + +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 00000000000..3c9e72ff11c --- /dev/null +++ b/docs/error-messages/tool-errors/linker-tools-warning-lnk4307.md @@ -0,0 +1,16 @@ +--- +title: "Linker Tools warning LNK4307" +description: "Learn more about: 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. + +## Remarks + +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-error-m6101.md b/docs/error-messages/tool-errors/math-error-m6101.md index 2a134c383a9..97393e3598c 100644 --- a/docs/error-messages/tool-errors/math-error-m6101.md +++ b/docs/error-messages/tool-errors/math-error-m6101.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6101" title: "Math Error M6101" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6101" +ms.date: 11/04/2016 f1_keywords: ["M6101"] helpviewer_keywords: ["M6101"] -ms.assetid: 8c8d5097-d725-4a2c-92e9-fcf28c871d74 --- # Math Error M6101 -invalid +> invalid + +## Remarks Invalid operation. diff --git a/docs/error-messages/tool-errors/math-error-m6102.md b/docs/error-messages/tool-errors/math-error-m6102.md index 0500853cac0..d9503b18f96 100644 --- a/docs/error-messages/tool-errors/math-error-m6102.md +++ b/docs/error-messages/tool-errors/math-error-m6102.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Math Error M6102" title: "Math Error M6102" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6102" +ms.date: 11/04/2016 f1_keywords: ["M6102"] helpviewer_keywords: ["M6102"] -ms.assetid: dbd2241f-6595-431e-9597-d9dbdb3a0ca2 --- # Math Error M6102 -denormal +> denormal + +## Remarks -An operation generated a very small floating-point number, which be invalid due loss of significance. Denormal floating-point exceptions are usually masked, causing them to be trapped and operated upon. +An operation generated a very small floating-point number, which may be invalid due to loss of significance. Denormal floating-point exceptions are usually masked, causing them to be trapped and operated upon. Program terminates with exit code 130. diff --git a/docs/error-messages/tool-errors/math-error-m6107.md b/docs/error-messages/tool-errors/math-error-m6107.md index bf01ca4d03e..96e69ec23ae 100644 --- a/docs/error-messages/tool-errors/math-error-m6107.md +++ b/docs/error-messages/tool-errors/math-error-m6107.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6107" title: "Math Error M6107" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6107" +ms.date: 11/04/2016 f1_keywords: ["M6107"] helpviewer_keywords: ["M6107"] -ms.assetid: a827a2a4-40b7-4e28-8e8d-530c6ffcf0c9 --- # Math Error M6107 -unemulated +> unemulated + +## Remarks An attempt was made to execute a coprocessor instruction that is invalid or is not supported by the emulator. diff --git a/docs/error-messages/tool-errors/math-error-m6108.md b/docs/error-messages/tool-errors/math-error-m6108.md index 7155419b33d..c0fd950f914 100644 --- a/docs/error-messages/tool-errors/math-error-m6108.md +++ b/docs/error-messages/tool-errors/math-error-m6108.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6108" title: "Math Error M6108" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6108" +ms.date: 11/04/2016 f1_keywords: ["M6108"] helpviewer_keywords: ["M6108"] -ms.assetid: 054893b4-49bc-45d9-882f-7cb50ba387c0 --- # Math Error M6108 -square root +> square root + +## Remarks The operand in a square-root operation was negative. diff --git a/docs/error-messages/tool-errors/math-error-m6110.md b/docs/error-messages/tool-errors/math-error-m6110.md index cbc7337ca7b..6d6b24e2d75 100644 --- a/docs/error-messages/tool-errors/math-error-m6110.md +++ b/docs/error-messages/tool-errors/math-error-m6110.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6110" title: "Math Error M6110" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6110" +ms.date: 11/04/2016 f1_keywords: ["M6110"] helpviewer_keywords: ["M6110"] -ms.assetid: aac9ae37-6a6d-46e9-85d4-dfe03f1c3e11 --- # Math Error M6110 -stack overflow +> stack overflow + +## Remarks A floating-point expression caused a floating-point stack overflow. diff --git a/docs/error-messages/tool-errors/math-error-m6111.md b/docs/error-messages/tool-errors/math-error-m6111.md index 123e1601bee..a63eb57ba48 100644 --- a/docs/error-messages/tool-errors/math-error-m6111.md +++ b/docs/error-messages/tool-errors/math-error-m6111.md @@ -1,22 +1,27 @@ --- -description: "Learn more about: Math Error M6111" title: "Math Error M6111" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6111" +ms.date: 11/04/2016 f1_keywords: ["M6111"] helpviewer_keywords: ["M6111"] -ms.assetid: c0fc13f8-33c8-4e3f-a440-126cc623441b --- # Math Error M6111 -stack underflow +> stack underflow + +## Remarks A floating-point operation resulted in a stack underflow on the 8087/287/387 coprocessor or the emulator. -This error is often caused by a call to a **`long double`** function that does not return a value. For example, the following generates this error when compiled and run: +This error is often caused by a call to a **`long double`** function that does not return a value. -``` -long double ld() {}; -main () +## Example + +For example, the following generates this error when compiled and run: + +```c +long double ld() {} +int main () { ld(); } diff --git a/docs/error-messages/tool-errors/math-error-m6201.md b/docs/error-messages/tool-errors/math-error-m6201.md index 5bc92535e0e..02fe9b07f20 100644 --- a/docs/error-messages/tool-errors/math-error-m6201.md +++ b/docs/error-messages/tool-errors/math-error-m6201.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6201" title: "Math Error M6201" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6201" +ms.date: 11/04/2016 f1_keywords: ["M6201"] helpviewer_keywords: ["M6201"] -ms.assetid: 4041c331-d9aa-4dd4-b565-7dbe0218538c --- # Math Error M6201 -'function' : _DOMAIN error +> 'function' : _DOMAIN error + +## Remarks An argument to the given function was outside the domain of legal input values for that function. diff --git a/docs/error-messages/tool-errors/math-error-m6202.md b/docs/error-messages/tool-errors/math-error-m6202.md index 1f9514fda1c..b26b2653ddc 100644 --- a/docs/error-messages/tool-errors/math-error-m6202.md +++ b/docs/error-messages/tool-errors/math-error-m6202.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6202" title: "Math Error M6202" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6202" +ms.date: 11/04/2016 f1_keywords: ["M6202"] helpviewer_keywords: ["M6202"] -ms.assetid: 4d17045f-c6dc-4705-9512-e9af12c35fb4 --- # Math Error M6202 -'function' : _SING error +> 'function' : _SING error + +## Remarks An argument to the given function was a singularity value for this function. The function is not defined for that argument. diff --git a/docs/error-messages/tool-errors/math-error-m6203.md b/docs/error-messages/tool-errors/math-error-m6203.md index 7677ddc0174..d2d66863f38 100644 --- a/docs/error-messages/tool-errors/math-error-m6203.md +++ b/docs/error-messages/tool-errors/math-error-m6203.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6203" title: "Math Error M6203" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6203" +ms.date: 11/04/2016 f1_keywords: ["M6203"] helpviewer_keywords: ["M6203"] -ms.assetid: bd7fdd1c-83e4-4d6a-901e-10a0308bf5be --- # Math Error M6203 -'function' : _OVERFLOW error +> 'function' : _OVERFLOW error + +## Remarks The given function result was too large to be represented. diff --git a/docs/error-messages/tool-errors/math-error-m6205.md b/docs/error-messages/tool-errors/math-error-m6205.md index a65999a49ef..2b92bda1950 100644 --- a/docs/error-messages/tool-errors/math-error-m6205.md +++ b/docs/error-messages/tool-errors/math-error-m6205.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Math Error M6205" title: "Math Error M6205" -ms.date: "11/04/2016" +description: "Learn more about: Math Error M6205" +ms.date: 11/04/2016 f1_keywords: ["M6205"] helpviewer_keywords: ["M6205"] -ms.assetid: fd28e7c9-a463-4a9c-a863-cc9e75315550 --- # Math Error M6205 -'function' : _TLOSS error +> 'function' : _TLOSS error + +## Remarks A total loss of significance (precision) occurred. 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 5c934acfb5a..f376b2a389d 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,29 +1,30 @@ --- +title: "Math errors (M6101 through M6205)" description: "Learn more about: Math errors (Mxxxx)" -title: "Math errors" -ms.date: "04/16/2019" -ms.assetid: bdf3dc2a-d993-4f53-b0f2-9604e4914127 +ms.date: 04/16/2019 --- -# 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. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Math errors -[Math error M6101](math-error-m6101.md) \ -[Math error M6102](math-error-m6102.md) \ -[Math error M6107](math-error-m6107.md) \ -[Math error M6108](math-error-m6108.md) \ -[Math error M6110](math-error-m6110.md) \ -[Math error M6111](math-error-m6111.md) \ -[Math error M6201](math-error-m6201.md) \ -[Math error M6202](math-error-m6202.md) \ -[Math error M6203](math-error-m6203.md) \ -[Math error M6205](math-error-m6205.md) +| Error | Message | +|--|--| +| [Math error M6101](math-error-m6101.md) | invalid | +| [Math error M6102](math-error-m6102.md) | denormal | +| [Math error M6107](math-error-m6107.md) | unemulated | +| [Math error M6108](math-error-m6108.md) | square root | +| [Math error M6110](math-error-m6110.md) | stack overflow | +| [Math error M6111](math-error-m6111.md) | stack underflow | +| [Math error M6201](math-error-m6201.md) | 'function' : _DOMAIN error | +| [Math error M6202](math-error-m6202.md) | 'function' : _SING error | +| [Math error M6203](math-error-m6203.md) | 'function' : _OVERFLOW error | +| [Math error M6205](math-error-m6205.md) | 'function' : _TLOSS error | ## 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)\ [Math and floating-point support](../../c-runtime-library/floating-point-support.md) diff --git a/docs/error-messages/tool-errors/name-decoration.md b/docs/error-messages/tool-errors/name-decoration.md index b6f77174881..2a4b3e4f6cf 100644 --- a/docs/error-messages/tool-errors/name-decoration.md +++ b/docs/error-messages/tool-errors/name-decoration.md @@ -19,6 +19,7 @@ The following table shows the linker name for various calling conventions. |Fast call naming convention (**`__fastcall`**)|`@test@0`|`?test@@YIXXZ`| |Standard call naming convention (**`__stdcall`**)|`_test@0`|`?test@@YGXXZ`| |Vector call naming convention (**`__vectorcall`**)|`test@@0`|`?test@@YQXXZ`| +|Preserve None naming convention (**`__preserve_none`**)|`test@@_A`|`NA`| Use `extern "C"` to call a C function from C++. `extern "C"` forces use of the C naming convention for non-class C++ functions. Be aware of compiler switches **/Tc** or **/Tp**, which tell the compiler to ignore the filename extension and compile the file as C or C++, respectively. These options may cause linker names you don't expect. diff --git a/docs/error-messages/tool-errors/nmake-errors-u1000-through-u4011.md b/docs/error-messages/tool-errors/nmake-errors-u1000-through-u4011.md index 6b68d4ece1f..f0d916c427b 100644 --- a/docs/error-messages/tool-errors/nmake-errors-u1000-through-u4011.md +++ b/docs/error-messages/tool-errors/nmake-errors-u1000-through-u4011.md @@ -1,60 +1,63 @@ --- -description: "Learn more about: NMAKE errors and warnings (Uxxxx)" title: "NMAKE errors and warnings" -ms.date: "04/16/2019" +description: "Learn more about: NMAKE errors and warnings (Uxxxx)" +ms.date: 04/16/2019 f1_keywords: ["nmake"] -ms.assetid: 9dbe2e12-88ca-4df4-b935-17756112bb79 --- # NMAKE errors and warnings (Uxxxx) This section is a reference to the errors and warnings generated by the NMAKE build tool. NMAKE errors and warnings have the form U*xxxx*, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## NMAKE fatal errors -[NMAKE fatal error U1000](nmake-fatal-error-u1000.md) \ -[NMAKE fatal error U1001](nmake-fatal-error-u1001.md) \ -[NMAKE fatal error U1007](nmake-fatal-error-u1007.md) \ -[NMAKE fatal error U1023](nmake-fatal-error-u1023.md) \ -[NMAKE fatal error U1033](nmake-fatal-error-u1033.md) \ -[NMAKE fatal error U1034](nmake-fatal-error-u1034.md) \ -[NMAKE fatal error U1035](nmake-fatal-error-u1035.md) \ -[NMAKE fatal error U1036](nmake-fatal-error-u1036.md) \ -[NMAKE fatal error U1045](nmake-fatal-error-u1045.md) \ -[NMAKE fatal error U1050](nmake-fatal-error-u1050.md) \ -[NMAKE fatal error U1051](nmake-fatal-error-u1051.md) \ -[NMAKE fatal error U1052](nmake-fatal-error-u1052.md) \ -[NMAKE fatal error U1055](nmake-fatal-error-u1055.md) \ -[NMAKE fatal error U1056](nmake-fatal-error-u1056.md) \ -[NMAKE fatal error U1059](nmake-fatal-error-u1059.md) \ -[NMAKE fatal error U1064](nmake-fatal-error-u1064.md) \ -[NMAKE fatal error U1065](nmake-fatal-error-u1065.md) \ -[NMAKE fatal error U1070](nmake-fatal-error-u1070.md) \ -[NMAKE fatal error U1071](nmake-fatal-error-u1071.md) \ -[NMAKE fatal error U1073](nmake-fatal-error-u1073.md) \ -[NMAKE fatal error U1076](nmake-fatal-error-u1076.md) \ -[NMAKE fatal error U1077](nmake-fatal-error-u1077.md) \ -[NMAKE fatal error U1078](nmake-fatal-error-u1078.md) \ -[NMAKE fatal error U1083](nmake-fatal-error-u1083.md) \ -[NMAKE fatal error U1086](nmake-fatal-error-u1086.md) \ -[NMAKE fatal error U1087](nmake-fatal-error-u1087.md) \ -[NMAKE fatal error U1088](nmake-fatal-error-u1088.md) \ -[NMAKE fatal error U1095](nmake-fatal-error-u1095.md) \ -[NMAKE fatal error U1097](nmake-fatal-error-u1097.md) \ -[NMAKE fatal error U1099](nmake-fatal-error-u1099.md) \ -[NMAKE fatal error U1100](nmake-fatal-error-u1100.md) +| Error | Message | +|--|--| +| [NMAKE fatal error U1000](nmake-fatal-error-u1000.md) | syntax error : ')' missing in macro invocation | +| [NMAKE fatal error U1001](nmake-fatal-error-u1001.md) | syntax error : illegal character 'character' in macro | +| [NMAKE fatal error U1007](nmake-fatal-error-u1007.md) | double quotation mark not allowed in name | +| [NMAKE fatal error U1023](nmake-fatal-error-u1023.md) | syntax error in expression | +| [NMAKE fatal error U1033](nmake-fatal-error-u1033.md) | syntax error : 'string' unexpected | +| [NMAKE fatal error U1034](nmake-fatal-error-u1034.md) | syntax error : separator missing | +| [NMAKE fatal error U1035](nmake-fatal-error-u1035.md) | syntax error : expected ':' or '=' separator | +| [NMAKE fatal error U1036](nmake-fatal-error-u1036.md) | syntax error : too many names to left of '=' | +| [NMAKE fatal error U1045](nmake-fatal-error-u1045.md) | spawn failed : *message* | +| [NMAKE fatal error U1050](nmake-fatal-error-u1050.md) | *message* | +| [NMAKE fatal error U1051](nmake-fatal-error-u1051.md) | out of memory | +| [NMAKE fatal error U1052](nmake-fatal-error-u1052.md) | file '*filename*' not found | +| [NMAKE fatal error U1055](nmake-fatal-error-u1055.md) | out of environment space | +| [NMAKE fatal error U1056](nmake-fatal-error-u1056.md) | cannot find command processor | +| [NMAKE fatal error U1059](nmake-fatal-error-u1059.md) | syntax error : '}' missing in dependent | +| [NMAKE fatal error U1064](nmake-fatal-error-u1064.md) | MAKEFILE not found and no target specified | +| [NMAKE fatal error U1065](nmake-fatal-error-u1065.md) | invalid option 'option' | +| [NMAKE fatal error U1070](nmake-fatal-error-u1070.md) | cycle in macro definition 'macroname' | +| [NMAKE fatal error U1071](nmake-fatal-error-u1071.md) | cycle in dependency tree for target 'targetname' | +| [NMAKE fatal error U1073](nmake-fatal-error-u1073.md) | don't know how to make 'targetname' | +| [NMAKE fatal error U1076](nmake-fatal-error-u1076.md) | name too long | +| [NMAKE fatal error U1077](nmake-fatal-error-u1077.md) | 'program' : return code 'value' | +| [NMAKE fatal error U1078](nmake-fatal-error-u1078.md) | constant overflow at 'expression' | +| [NMAKE fatal error U1083](nmake-fatal-error-u1083.md) | target macro 'target' expands to nothing | +| [NMAKE fatal error U1086](nmake-fatal-error-u1086.md) | inference rule cannot have dependents | +| [NMAKE fatal error U1087](nmake-fatal-error-u1087.md) | cannot have : and :: dependents for same target | +| [NMAKE fatal error U1088](nmake-fatal-error-u1088.md) | invalid separator '::' on inference rule | +| [NMAKE fatal error U1095](nmake-fatal-error-u1095.md) | expanded command line 'commandline' too long | +| [NMAKE fatal error U1097](nmake-fatal-error-u1097.md) | filename-parts syntax requires dependent | +| [NMAKE fatal error U1099](nmake-fatal-error-u1099.md) | stack overflow | +| [NMAKE fatal error U1100](nmake-fatal-error-u1100.md) | macro '*macro-name*' is illegal in the context of batch rule '*rule-name*' | ## NMAKE warnings -[NMAKE warning U4001](nmake-warning-u4001.md) \ -[NMAKE warning U4004](nmake-warning-u4004.md) \ -[NMAKE warning U4006](nmake-warning-u4006.md) \ -[NMAKE warning U4007](nmake-warning-u4007.md) \ -[NMAKE warning U4010](nmake-warning-u4010.md) \ -[NMAKE warning U4011](nmake-warning-u4011.md) +| Warning | Message | +|--|--| +| [NMAKE warning U4001](nmake-warning-u4001.md) | command file can be invoked only from command line | +| [NMAKE warning U4004](nmake-warning-u4004.md) | too many rules for target 'targetname' | +| [NMAKE warning U4006](nmake-warning-u4006.md) | special macro undefined : 'macroname' | +| [NMAKE warning U4007](nmake-warning-u4007.md) | filename 'filename' too long; truncating to 8.3 | +| [NMAKE warning U4010](nmake-warning-u4010.md) | 'target' : build failed; /K specified, continuing ... | +| [NMAKE warning U4011](nmake-warning-u4011.md) | 'target' : not all dependents available; target not built | ## 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)\ [NMAKE reference](../../build/reference/nmake-reference.md) diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1000.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1000.md index f30b782f076..24a842f48bd 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1000.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1000.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1000" title: "NMAKE Fatal Error U1000" -ms.date: "08/27/2018" +description: "Learn more about: NMAKE Fatal Error U1000" +ms.date: 08/27/2018 f1_keywords: ["U1000"] helpviewer_keywords: ["U1000"] -ms.assetid: 49b9bd9e-f1bc-4b55-a171-c748e40b195e --- # NMAKE Fatal Error U1000 > syntax error : ')' missing in macro invocation +## Remarks + A left parenthesis, **(**, appeared without a matching right parenthesis, **)**, in a macro invocation. The correct form is **$(**name**)**; **$**n is allowed for one-character names. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1001.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1001.md index 2b0e13a756c..08ea984cff1 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1001.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1001.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1001" title: "NMAKE Fatal Error U1001" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1001" +ms.date: 11/04/2016 f1_keywords: ["U1001"] helpviewer_keywords: ["U1001"] -ms.assetid: 5d7da559-6cbd-44d6-848c-aaf54cae0d1a --- # NMAKE Fatal Error U1001 -syntax error : illegal character 'character' in macro +> syntax error : illegal character 'character' in macro + +## Remarks The given character appears in a macro but is not a letter, number, or underscore. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1007.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1007.md index 2b2e8d222f2..60ea2b957f9 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1007.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1007.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1007" title: "NMAKE Fatal Error U1007" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1007" +ms.date: 11/04/2016 f1_keywords: ["U1007"] helpviewer_keywords: ["U1007"] -ms.assetid: 64fd78a6-5b27-4aa8-92ea-f1c55e6e5edd --- # NMAKE Fatal Error U1007 -double quotation mark not allowed in name +> double quotation mark not allowed in name + +## Remarks The specified target name or filename contained a double quotation mark (**"**). diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1023.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1023.md index a3bbd00e45e..9588301e045 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1023.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1023.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1023" title: "NMAKE Fatal Error U1023" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1023" +ms.date: 11/04/2016 f1_keywords: ["U1023"] helpviewer_keywords: ["U1023"] -ms.assetid: 22d4c469-85da-43ee-86d1-171b1b99217d --- # NMAKE Fatal Error U1023 -syntax error in expression +> syntax error in expression + +## Remarks An expression is invalid. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1033.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1033.md index 5eff0091be8..ddb90f3b15f 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1033.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1033.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1033" title: "NMAKE Fatal Error U1033" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1033" +ms.date: 11/04/2016 f1_keywords: ["U1033"] helpviewer_keywords: ["U1033"] -ms.assetid: c146f7b5-7d5c-4329-a522-28a648546016 --- # NMAKE Fatal Error U1033 -syntax error : 'string' unexpected +> syntax error : 'string' unexpected + +## Remarks The string is not part of the valid syntax for a makefile. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1034.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1034.md index 5388c11124a..038db41936b 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1034.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1034.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1034" title: "NMAKE Fatal Error U1034" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1034" +ms.date: 11/04/2016 f1_keywords: ["U1034"] helpviewer_keywords: ["U1034"] -ms.assetid: 27e678c2-23e2-4247-87f7-66493784af33 --- # NMAKE Fatal Error U1034 -syntax error : separator missing +> syntax error : separator missing + +## Remarks The colon (**:**) that separates targets and dependents is missing. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1035.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1035.md index 88c3fedee2d..3b552b7199a 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1035.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1035.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1035" title: "NMAKE Fatal Error U1035" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1035" +ms.date: 11/04/2016 f1_keywords: ["U1035"] helpviewer_keywords: ["U1035"] -ms.assetid: 68f0cc59-007e-4109-ac30-7ac4ac447e6d --- # NMAKE Fatal Error U1035 -syntax error : expected ':' or '=' separator +> syntax error : expected ':' or '=' separator + +## Remarks Either a colon (**:**) or an equal sign (**=**) was expected. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1036.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1036.md index 4d738221c3b..23cb6149762 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1036.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1036.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1036" title: "NMAKE Fatal Error U1036" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1036" +ms.date: 11/04/2016 f1_keywords: ["U1036"] helpviewer_keywords: ["U1036"] -ms.assetid: b1d03b6b-ce82-4bbb-9904-d392ba72b437 --- # NMAKE Fatal Error U1036 -syntax error : too many names to left of '=' +> syntax error : too many names to left of '=' + +## Remarks Only one string is allowed to the left of a macro definition. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1045.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1045.md index 06ea660ec4e..28278195d4d 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1045.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1045.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: NMAKE Fatal Error U1045" title: "NMAKE Fatal Error U1045" -ms.date: "08/11/2019" +description: "Learn more about: NMAKE Fatal Error U1045" +ms.date: 08/11/2019 f1_keywords: ["U1045"] helpviewer_keywords: ["U1045"] -ms.assetid: dc70d162-14b9-4107-9237-7514044d72e3 --- # NMAKE Fatal Error U1045 > spawn failed : *message* +## Remarks + A program or command called by NMAKE failed for reason in *message*. When NMAKE calls another program, for example, the compiler or linker, the call may fail. Or, an error may be returned by the called program. This message is used to report the error. To fix this issue, first determine the cause of the error. You can use the commands reported by the NMAKE [/N](../../build/reference/running-nmake.md#nmake-options) option to verify the environment settings and to repeat the actions done by NMAKE on the command line. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1050.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1050.md index a8872865701..a1e59028650 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1050.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1050.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1050" title: "NMAKE Fatal Error U1050" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1050" +ms.date: 11/04/2016 f1_keywords: ["U1050"] helpviewer_keywords: ["U1050"] -ms.assetid: 3bb2937e-a804-4592-a9e6-afb63360f554 --- # NMAKE Fatal Error U1050 -message +> message + +## Remarks The message specified with the **!ERROR** directive was displayed. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1051.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1051.md index 4d4aa782c14..14d5188d58a 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1051.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1051.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1051" title: "NMAKE Fatal Error U1051" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1051" +ms.date: 11/04/2016 f1_keywords: ["U1051"] helpviewer_keywords: ["U1051"] -ms.assetid: fede5cd5-dac3-47b7-b86d-e1acfb78699f --- # NMAKE Fatal Error U1051 -out of memory +> out of memory + +## Remarks NMAKE ran out of memory, including virtual memory, because the makefile was too large or complex. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1052.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1052.md index 2db5efd3c49..3a75ff6737c 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1052.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1052.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: NMAKE Fatal Error U1052" title: "NMAKE Fatal Error U1052" -ms.date: "09/05/2018" +description: "Learn more about: NMAKE Fatal Error U1052" +ms.date: 09/05/2018 f1_keywords: ["U1052"] helpviewer_keywords: ["U1052"] -ms.assetid: b19b3691-e60b-46bd-8822-8426740a9bc7 --- # NMAKE Fatal Error U1052 > file '*filename*' not found +## Remarks + NMAKE could not find the file specified with one of the following: - **/F** option diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1055.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1055.md index 2d6990c1b7d..de37ff89129 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1055.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1055.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1055" title: "NMAKE Fatal Error U1055" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1055" +ms.date: 11/04/2016 f1_keywords: ["U1055"] helpviewer_keywords: ["U1055"] -ms.assetid: 1d453922-ba7e-497f-a795-d8d959c40555 --- # NMAKE Fatal Error U1055 -out of environment space +> out of environment space + +## Remarks The operating system ran out of room for environment variables. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1056.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1056.md index 21829ca80bb..06285d3dc4d 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1056.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1056.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1056" title: "NMAKE Fatal Error U1056" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1056" +ms.date: 11/04/2016 f1_keywords: ["U1056"] helpviewer_keywords: ["U1056"] -ms.assetid: da855728-b69e-413c-83ed-df912126215e --- # NMAKE Fatal Error U1056 -cannot find command processor +> cannot find command processor + +## Remarks The command processor was not in the path specified in the **COMSPEC** or **PATH** environment variables. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1059.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1059.md index b6492fff8af..2918a3f6507 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1059.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1059.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: NMAKE Fatal Error U1059" title: "NMAKE Fatal Error U1059" -ms.date: "08/27/2018" +description: "Learn more about: NMAKE Fatal Error U1059" +ms.date: 08/27/2018 f1_keywords: ["U1059"] helpviewer_keywords: ["U1059"] -ms.assetid: b21d9198-9c63-40d0-b589-80e17294ce24 --- # NMAKE Fatal Error U1059 > syntax error : '}' missing in dependent +## Remarks + A search path for a dependent was incorrectly specified. Either a space existed in the path or the closing brace (**}**) was omitted. The syntax for a directory specification for a dependent is diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1064.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1064.md index cd17c2018a2..79fe444306d 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1064.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1064.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1064" title: "NMAKE Fatal Error U1064" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1064" +ms.date: 11/04/2016 f1_keywords: ["U1064"] helpviewer_keywords: ["U1064"] -ms.assetid: 7141e66e-cde6-4173-84df-a391f3ebcdd1 --- # NMAKE Fatal Error U1064 -MAKEFILE not found and no target specified +> MAKEFILE not found and no target specified + +## Remarks The NMAKE command line did not specify a makefile or a target, and the current directory did not contain a file named MAKEFILE. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1065.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1065.md index be07276b6aa..77762393f2b 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1065.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1065.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1065" title: "NMAKE Fatal Error U1065" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1065" +ms.date: 11/04/2016 f1_keywords: ["U1065"] helpviewer_keywords: ["U1065"] -ms.assetid: bc890f20-ff46-4073-ab3b-4a5db879f9bd --- # NMAKE Fatal Error U1065 -invalid option 'option' +> invalid option 'option' + +## Remarks The option is not valid for NMAKE. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1070.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1070.md index 3636b2a3f10..b2691ac1dfa 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1070.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1070.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1070" title: "NMAKE Fatal Error U1070" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1070" +ms.date: 11/04/2016 f1_keywords: ["U1070"] helpviewer_keywords: ["U1070"] -ms.assetid: 8639fc39-b4b1-48f5-ac91-0e9fb61680fd --- # NMAKE Fatal Error U1070 -cycle in macro definition 'macroname' +> cycle in macro definition 'macroname' + +## Remarks The given macro definition contained a macro whose definition contained the given macro. Circular macro definitions are invalid. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1071.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1071.md index fd851f84ff0..1f2a4cedcee 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1071.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1071.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1071" title: "NMAKE Fatal Error U1071" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1071" +ms.date: 11/04/2016 f1_keywords: ["U1071"] helpviewer_keywords: ["U1071"] -ms.assetid: 328a0c1f-a867-410e-943d-7b6b75a975ab --- # NMAKE Fatal Error U1071 -cycle in dependency tree for target 'targetname' +> cycle in dependency tree for target 'targetname' + +## Remarks A circular dependency exists in the dependency tree for the given target. The given target is a dependent of one of the dependents of the given target. Circular dependencies are invalid. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1073.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1073.md index 572d421d61a..84cb579e0ce 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1073.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1073.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1073" title: "NMAKE Fatal Error U1073" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1073" +ms.date: 11/04/2016 f1_keywords: ["U1073"] helpviewer_keywords: ["U1073"] -ms.assetid: d46bf2dd-400a-4802-9db2-f832e1c97f02 --- # NMAKE Fatal Error U1073 -don't know how to make 'targetname' +> don't know how to make 'targetname' + +## Remarks The specified target does not exist, and there is no command to execute or inference rule to apply. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1076.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1076.md index 8c95ad3f7dd..5015af36911 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1076.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1076.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1076" title: "NMAKE Fatal Error U1076" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1076" +ms.date: 11/04/2016 f1_keywords: ["U1076"] helpviewer_keywords: ["U1076"] -ms.assetid: f8a6c646-0c49-4ee3-bb74-ab916a7aa6ff --- # NMAKE Fatal Error U1076 -name too long +> name too long + +## Remarks A string exceeded one of the following limits: diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1077.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1077.md index 57120c5e205..cf389cf8dd7 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1077.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1077.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1077" title: "NMAKE Fatal Error U1077" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1077" +ms.date: 11/04/2016 f1_keywords: ["U1077"] helpviewer_keywords: ["U1077"] -ms.assetid: 70d989f8-ef34-4ad7-8fe0-5b800556b2a1 --- # NMAKE Fatal Error U1077 -'program' : return code 'value' +> 'program' : return code 'value' + +## Remarks The given command or program called by NMAKE failed and returned the given exit code. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1078.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1078.md index efcae0f8b0d..ee1e637a341 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1078.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1078.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1078" title: "NMAKE Fatal Error U1078" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1078" +ms.date: 11/04/2016 f1_keywords: ["U1078"] helpviewer_keywords: ["U1078"] -ms.assetid: 24087955-9362-4ddf-9966-e0de43ea4647 --- # NMAKE Fatal Error U1078 -constant overflow at 'expression' +> constant overflow at 'expression' + +## Remarks The given expression contained a constant that exceeded the range - 2,147,483,648 to 2,147,483,647. The constant appeared in one of the following situations: diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1083.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1083.md index 2b42dcbecf5..22be01d0e95 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1083.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1083.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1083" title: "NMAKE Fatal Error U1083" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1083" +ms.date: 11/04/2016 f1_keywords: ["U1083"] helpviewer_keywords: ["U1083"] -ms.assetid: b09bc34d-35d5-4676-b000-fd7d434400d9 --- # NMAKE Fatal Error U1083 -target macro 'target' expands to nothing +> target macro 'target' expands to nothing + +## Remarks The given target is an invocation of a macro that has not been defined or has a null value. NMAKE cannot process a null target. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1086.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1086.md index 6143eaf3d76..4705fc28e11 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1086.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1086.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1086" title: "NMAKE Fatal Error U1086" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1086" +ms.date: 11/04/2016 f1_keywords: ["U1086"] helpviewer_keywords: ["U1086"] -ms.assetid: 6d3cd68a-ead6-4a6d-a205-01324785de7e --- # NMAKE Fatal Error U1086 -**inference rule cannot have dependents** +> inference rule cannot have dependents + +## Remarks The colon (**:**) in an inference rule must be followed by one of these: diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1087.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1087.md index 6f5406a2315..7082f6c6d19 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1087.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1087.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1087" title: "NMAKE Fatal Error U1087" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1087" +ms.date: 11/04/2016 f1_keywords: ["U1087"] helpviewer_keywords: ["U1087"] -ms.assetid: 5236ab54-e117-484d-99c3-852b061fd3d0 --- # NMAKE Fatal Error U1087 -cannot have : and :: dependents for same target +> cannot have : and :: dependents for same target + +## Remarks A target cannot be specified in both a single-colon (**:**) and a double-colon (`::`) dependency. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1088.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1088.md index 6ed23ef6eef..5f62fb6e7af 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1088.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1088.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1088" title: "NMAKE Fatal Error U1088" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1088" +ms.date: 11/04/2016 f1_keywords: ["U1088"] helpviewer_keywords: ["U1088"] -ms.assetid: 75f3527b-9923-408b-a66e-701322c63803 --- # NMAKE Fatal Error U1088 -invalid separator '::' on inference rule +> invalid separator '::' on inference rule + +## Remarks An inference rule must be followed by a single colon (**:**). diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1095.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1095.md index 012f7e0d104..87e702a9d06 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1095.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1095.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1095" title: "NMAKE Fatal Error U1095" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1095" +ms.date: 11/04/2016 f1_keywords: ["U1095"] helpviewer_keywords: ["U1095"] -ms.assetid: a392582b-06db-4568-9c13-450293a4fbda --- # NMAKE Fatal Error U1095 -expanded command line 'commandline' too long +> expanded command line 'commandline' too long + +## Remarks After macro expansion, the given command line exceeded the limit on length of command lines for the operating system. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1097.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1097.md index 1dd82ea7b90..7c9958d77e2 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1097.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1097.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Fatal Error U1097" title: "NMAKE Fatal Error U1097" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1097" +ms.date: 11/04/2016 f1_keywords: ["U1097"] helpviewer_keywords: ["U1097"] -ms.assetid: dc6868b3-8425-4920-858a-774ad0c4c5f1 --- # NMAKE Fatal Error U1097 -filename-parts syntax requires dependent +> filename-parts syntax requires dependent + +## Remarks The current dependency does not have either an explicit dependent or an implicit dependent. Filename-parts syntax, which uses the percent (`%`) specifier, represents components of the first dependent of the current target. diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1099.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1099.md index bd672f6cf98..d2645925c72 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1099.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1099.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Fatal Error U1099" title: "NMAKE Fatal Error U1099" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Fatal Error U1099" +ms.date: 11/04/2016 f1_keywords: ["U1099"] helpviewer_keywords: ["U1099"] -ms.assetid: 6688a805-43e6-4247-a2d0-14be082f0b13 --- # NMAKE Fatal Error U1099 -stack overflow +> stack overflow + +## Remarks The makefile being processed was too complex for the current stack allocation in NMAKE. NMAKE has an allocation of 0x3000 (12K). diff --git a/docs/error-messages/tool-errors/nmake-fatal-error-u1100.md b/docs/error-messages/tool-errors/nmake-fatal-error-u1100.md index 497a02ea3dc..4ae01cd7b7e 100644 --- a/docs/error-messages/tool-errors/nmake-fatal-error-u1100.md +++ b/docs/error-messages/tool-errors/nmake-fatal-error-u1100.md @@ -4,12 +4,13 @@ description: "A description of the causes of Microsoft NMAKE fatal error U1100." ms.date: 07/17/2020 f1_keywords: ["U1100"] helpviewer_keywords: ["U1100"] -ms.assetid: c71910a7-c581-4d9c-a38c-d2d557d56289 --- # NMAKE Fatal Error U1100 > macro '*macro-name*' is illegal in the context of batch rule '*rule-name*' +## Remarks + NMAKE generates this error when the command block of a batch-mode rule directly or indirectly references a special file macro that isn't `$<`. `$<` is the only allowed macro for batch-mode rules. diff --git a/docs/error-messages/tool-errors/nmake-warning-u4001.md b/docs/error-messages/tool-errors/nmake-warning-u4001.md index 950ef74f800..a23091484ad 100644 --- a/docs/error-messages/tool-errors/nmake-warning-u4001.md +++ b/docs/error-messages/tool-errors/nmake-warning-u4001.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Warning U4001" title: "NMAKE Warning U4001" -ms.date: "09/05/2018" +description: "Learn more about: NMAKE Warning U4001" +ms.date: 09/05/2018 f1_keywords: ["U4001"] helpviewer_keywords: ["U4001"] -ms.assetid: ed3b4068-2ad8-4ffc-b7c7-33897d2a55d7 --- # NMAKE Warning U4001 > command file can be invoked only from command line +## Remarks + A command file, which is invoked by the at sign (**\@**) specifier, cannot contain a specification for another command file. Such nesting is not allowed. The specification was ignored. diff --git a/docs/error-messages/tool-errors/nmake-warning-u4004.md b/docs/error-messages/tool-errors/nmake-warning-u4004.md index 4ab084062d1..93f0ea200fe 100644 --- a/docs/error-messages/tool-errors/nmake-warning-u4004.md +++ b/docs/error-messages/tool-errors/nmake-warning-u4004.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Warning U4004" title: "NMAKE Warning U4004" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Warning U4004" +ms.date: 11/04/2016 f1_keywords: ["U4004"] helpviewer_keywords: ["U4004"] -ms.assetid: 5086bbcb-42d7-4677-a877-1a02202a86a2 --- # NMAKE Warning U4004 -too many rules for target 'targetname' +> too many rules for target 'targetname' + +## Remarks More than one description block was specified for the given target using single colons (**:**) as separators. NMAKE executed the commands in the first description block and ignored later blocks. diff --git a/docs/error-messages/tool-errors/nmake-warning-u4006.md b/docs/error-messages/tool-errors/nmake-warning-u4006.md index 8ed54357ead..7a0b31901f0 100644 --- a/docs/error-messages/tool-errors/nmake-warning-u4006.md +++ b/docs/error-messages/tool-errors/nmake-warning-u4006.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: NMAKE Warning U4006" title: "NMAKE Warning U4006" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Warning U4006" +ms.date: 11/04/2016 f1_keywords: ["U4006"] helpviewer_keywords: ["U4006"] -ms.assetid: 830ad63c-d454-47a3-840c-c272f29ef3d2 --- # NMAKE Warning U4006 -special macro undefined : 'macroname' +> special macro undefined : 'macroname' + +## Remarks The given special macro name is undefined and expands to nothing. diff --git a/docs/error-messages/tool-errors/nmake-warning-u4007.md b/docs/error-messages/tool-errors/nmake-warning-u4007.md index 15e4b79e462..392d4529ecd 100644 --- a/docs/error-messages/tool-errors/nmake-warning-u4007.md +++ b/docs/error-messages/tool-errors/nmake-warning-u4007.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Warning U4007" title: "NMAKE Warning U4007" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Warning U4007" +ms.date: 11/04/2016 f1_keywords: ["U4007"] helpviewer_keywords: ["U4007"] -ms.assetid: 61ec0417-6961-43c1-ade8-f9d6e93289e9 --- # NMAKE Warning U4007 -filename 'filename' too long; truncating to 8.3 +> filename 'filename' too long; truncating to 8.3 + +## Remarks The base name of the given file has more than eight characters, or the extension has more than three characters. NMAKE truncated the name to an eight-character base and a three-character extension. diff --git a/docs/error-messages/tool-errors/nmake-warning-u4010.md b/docs/error-messages/tool-errors/nmake-warning-u4010.md index 99cc38a56ff..44fa515eee6 100644 --- a/docs/error-messages/tool-errors/nmake-warning-u4010.md +++ b/docs/error-messages/tool-errors/nmake-warning-u4010.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Warning U4010" title: "NMAKE Warning U4010" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Warning U4010" +ms.date: 11/04/2016 f1_keywords: ["U4010"] helpviewer_keywords: ["U4010"] -ms.assetid: 99d8eb9a-ae31-40d1-b8c5-8c66732127d3 --- # NMAKE Warning U4010 -'target' : build failed; /K specified, continuing ... +> 'target' : build failed; /K specified, continuing ... + +## Remarks A command in the commands block for the given target returned a nonzero exit code. The /K option told NMAKE to continue processing unrelated parts of the build and to issue an exit code 1 when the NMAKE session is finished. diff --git a/docs/error-messages/tool-errors/nmake-warning-u4011.md b/docs/error-messages/tool-errors/nmake-warning-u4011.md index cde7c27e7d4..9e8040a5f54 100644 --- a/docs/error-messages/tool-errors/nmake-warning-u4011.md +++ b/docs/error-messages/tool-errors/nmake-warning-u4011.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: NMAKE Warning U4011" title: "NMAKE Warning U4011" -ms.date: "11/04/2016" +description: "Learn more about: NMAKE Warning U4011" +ms.date: 11/04/2016 f1_keywords: ["U4011"] helpviewer_keywords: ["U4011"] -ms.assetid: e8244514-eba6-4285-8853-7baeefdcd8a4 --- # NMAKE Warning U4011 -'target' : not all dependents available; target not built +> 'target' : not all dependents available; target not built + +## Remarks A dependent of the given target either did not exist or was out-of-date, and a command for updating the dependent returned a nonzero exit code. The /K option told NMAKE to continue processing unrelated parts of the build and to issue an exit code 1 when the NMAKE session is finished. diff --git a/docs/error-messages/tool-errors/profile-guided-optimization-errors-and-warnings.md b/docs/error-messages/tool-errors/profile-guided-optimization-errors-and-warnings.md index d3eae644ae7..9afd0a1d993 100644 --- a/docs/error-messages/tool-errors/profile-guided-optimization-errors-and-warnings.md +++ b/docs/error-messages/tool-errors/profile-guided-optimization-errors-and-warnings.md @@ -1,26 +1,29 @@ --- -description: "Learn more about: Profile-Guided Optimization errors and warnings (PGxxxx)" title: "Profile-Guided Optimization errors and warnings" -ms.date: "04/17/2019" +description: "Learn more about: Profile-Guided Optimization errors and warnings (PGxxxx)" +ms.date: 04/17/2019 f1_keywords: ["PG0001", "PG0002", "PG0003", "PG0061", "PG0062", "PG0063", "PG0065", "PG0066", "PG0067", "PG0068", "PG0069", "PG0070", "PG0071", "PG0081", "PG0087", "PG0090", "PG0091", "PG0092", "PG0094", "PG0096", "PG0168", "PG0169", "PG0181", "PG0188", "PG1000", "PG1001", "PG1032", "PG1033", "PG1035", "PG1036", "PG1038", "PG1051", "PG1052", "PG1053", "PG1056", "PG1058", "PG1060", "PG1061", "PG1065", "PG1066", "PG1067"] -ms.assetid: f67b1011-fb64-4df3-9356-d52c9423ff3f --- # Profile-Guided Optimization errors and warnings (PGxxxx) This section is a reference to the errors generated by the Profile-Guided Optimization (PGO) tools. PGO errors and warnings have the form PG*xxxx*, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## PGO errors -[Profile-Guided Optimization Error PG0165](../../error-messages/tool-errors/profile-guided-optimization-error-pg0165.md) +| Error | Message | +|--|--| +| [Profile-Guided Optimization Error PG0165](profile-guided-optimization-error-pg0165.md) | Reading '*filename.pgd*' : '*message*'. | ## PGO warnings -[Profile-Guided Optimization Warning PG1039](../../error-messages/tool-errors/profile-guided-optimization-warning-pg1039.md) \ -[Profile-Guided Optimization Warning PG1087](../../error-messages/tool-errors/profile-guided-optimization-warning-pg1087.md) +| Warning | Message | +|--|--| +| [Profile-Guided Optimization Warning PG1039](profile-guided-optimization-warning-pg1039.md) | Failed waiting for quiet time to sweep. | +| [Profile-Guided Optimization Warning PG1087](profile-guided-optimization-warning-pg1087.md) | The PGC file 'file' is not valid. | ## 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)\ [Profile-Guided Optimizations](../../build/profile-guided-optimizations.md) diff --git a/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1039.md b/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1039.md index 1bab31de79d..1205a811698 100644 --- a/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1039.md +++ b/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1039.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Profile-Guided Optimization Warning PG1039" title: "Profile-Guided Optimization Warning PG1039" -ms.date: "11/04/2016" +description: "Learn more about: Profile-Guided Optimization Warning PG1039" +ms.date: 11/04/2016 f1_keywords: ["PG1039"] helpviewer_keywords: ["PG1039"] -ms.assetid: a67dfd66-b610-4d78-9658-2bcf7a506b9f --- # Profile-Guided Optimization Warning PG1039 -Failed waiting for quiet time to sweep. +> Failed waiting for quiet time to sweep. + +## Remarks The application did not allow [pgosweep](../../build/pgosweep.md) to run. If possible, run pgosweep when the application is in an idle state. diff --git a/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1087.md b/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1087.md index 873b38173a2..d68d8413ca6 100644 --- a/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1087.md +++ b/docs/error-messages/tool-errors/profile-guided-optimization-warning-pg1087.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Profile-Guided Optimization Warning PG1087" title: "Profile-Guided Optimization Warning PG1087" -ms.date: "11/04/2016" +description: "Learn more about: Profile-Guided Optimization Warning PG1087" +ms.date: 11/04/2016 f1_keywords: ["PG1087"] helpviewer_keywords: ["PG1087"] -ms.assetid: 50785d68-17a2-4d82-bee2-8c514faf61c6 --- # Profile-Guided Optimization Warning PG1087 -The PGC file 'file' is not valid. +> The PGC file 'file' is not valid. + +## Remarks A .pgc file is corrupt, possibly due to an abnormal end to a profiling session. Rerun the profiling scenario and terminate normally. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0002.md b/docs/error-messages/tool-errors/project-build-error-prj0002.md index b61c38b32bb..25cdd328c58 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0002.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0002.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0002" title: "Project Build Error PRJ0002" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0002" +ms.date: 08/27/2018 f1_keywords: ["PRJ0002"] helpviewer_keywords: ["PRJ0002"] -ms.assetid: 1c820b1f-9a24-4681-80ed-4fcbfd7caa00 --- # Project Build Error PRJ0002 > error result returned from '*command line*'. +## Remarks + A command, *command line*, which was formed from user input in the **Property Pages** dialog box, returned an error code but no information will appear in the **Output** window. The resolution to this error depends on which tool generated the error. For MIDL, you will get an idea of what went wrong if /o (Redirect Output) is defined. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0003.md b/docs/error-messages/tool-errors/project-build-error-prj0003.md index 0ae0473610d..3a8e09419da 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0003.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0003.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0003" title: "Project Build Error PRJ0003" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0003" +ms.date: 11/04/2016 f1_keywords: ["PRJ0003"] helpviewer_keywords: ["PRJ0003"] -ms.assetid: fc5a84bb-c6d3-41d6-8dd6-475455820778 --- # Project Build Error PRJ0003 > Error spawning '*command line*'. +## Remarks + The *command line* command formed from input in the **Property Pages** dialog box returned an error code, but no information appears in the **Output** window. Possible reasons for this error include: diff --git a/docs/error-messages/tool-errors/project-build-error-prj0004.md b/docs/error-messages/tool-errors/project-build-error-prj0004.md index 387c00e6be2..07cfd3b1d1c 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0004.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0004.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0004" title: "Project Build Error PRJ0004" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0004" +ms.date: 08/27/2018 f1_keywords: ["PRJ0004"] helpviewer_keywords: ["PRJ0004"] -ms.assetid: 1858769f-0be4-40ed-ab70-2cee550488c7 --- # Project Build Error PRJ0004 > Could not generate command line for the '*tool*' tool. +## Remarks + One or more properties were specified in such a way as to make the syntax of the call to *tool* illegal: - You may have specified badly formed or unknown macros. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0005.md b/docs/error-messages/tool-errors/project-build-error-prj0005.md index 8e2e34587c2..1daca41960c 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0005.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0005.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0005" title: "Project Build Error PRJ0005" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0005" +ms.date: 11/04/2016 f1_keywords: ["PRJ0005"] helpviewer_keywords: ["PRJ0005"] -ms.assetid: 00c1821b-16aa-4bd9-9cf6-a778e5ed4ad9 --- # Project Build Error PRJ0005 -Unable to create a temporary file in directory 'directory'. +> Unable to create a temporary file in directory 'directory'. + +## Remarks The call to create a temporary file failed. Reasons for failure include: diff --git a/docs/error-messages/tool-errors/project-build-error-prj0006.md b/docs/error-messages/tool-errors/project-build-error-prj0006.md index 9a98972aba4..c5ddbebb489 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0006.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0006.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0006" title: "Project Build Error PRJ0006" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0006" +ms.date: 11/04/2016 f1_keywords: ["PRJ0006"] helpviewer_keywords: ["PRJ0006"] -ms.assetid: ce092be4-1652-414f-8cb5-b97ef5841f89 --- # Project Build Error PRJ0006 -Could not open the temporary file 'file'. Make sure the file exists and that the directory is not write-protected. +> Could not open the temporary file 'file'. Make sure the file exists and that the directory is not write-protected. + +## Remarks Visual C++ could not create a temporary file during the build process. Reasons for this include: diff --git a/docs/error-messages/tool-errors/project-build-error-prj0007.md b/docs/error-messages/tool-errors/project-build-error-prj0007.md index 5c661e392d1..315b84e1a2e 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0007.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0007.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0007" title: "Project Build Error PRJ0007" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0007" +ms.date: 11/04/2016 f1_keywords: ["PRJ0007"] helpviewer_keywords: ["PRJ0007"] -ms.assetid: d923948b-acc9-498f-bf3b-f14e41bed61a --- # Project Build Error PRJ0007 -Could not create output directory 'directory'. +> Could not create output directory 'directory'. + +## Remarks Visual C++ failed to create an output directory. Possible reasons include: diff --git a/docs/error-messages/tool-errors/project-build-error-prj0008.md b/docs/error-messages/tool-errors/project-build-error-prj0008.md index 9371e7b0056..ab916e188be 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0008.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0008.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0008" title: "Project Build Error PRJ0008" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0008" +ms.date: 11/04/2016 f1_keywords: ["PRJ0008"] helpviewer_keywords: ["PRJ0008"] -ms.assetid: 6bf7f17a-d2a8-4826-99c7-d600d846952f --- # Project Build Error PRJ0008 -Could not delete file 'file'. +> Could not delete file 'file'. + +## Remarks **Make sure that the file is not open by another process and is not write-protected.** diff --git a/docs/error-messages/tool-errors/project-build-error-prj0009.md b/docs/error-messages/tool-errors/project-build-error-prj0009.md index e2ba86e6546..cb3d58ba79c 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0009.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0009.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0009" title: "Project Build Error PRJ0009" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0009" +ms.date: 11/04/2016 f1_keywords: ["PRJ0009"] helpviewer_keywords: ["PRJ0009"] -ms.assetid: 89291778-cda4-495d-983f-ddcc06dfc98b --- # Project Build Error PRJ0009 -Build log could not be opened for writing. +> Build log could not be opened for writing. + +## Remarks **Make sure that the file is not open by another process and is not write-protected.** diff --git a/docs/error-messages/tool-errors/project-build-error-prj0013.md b/docs/error-messages/tool-errors/project-build-error-prj0013.md index 9c83ecf9f8b..004cd1fa41c 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0013.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0013.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0013" title: "Project Build Error PRJ0013" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0013" +ms.date: 11/04/2016 f1_keywords: ["PRJ0013"] helpviewer_keywords: ["PRJ0013"] -ms.assetid: 95e7bafd-63c8-4b2d-b778-f19cdf9ba36c --- # Project Build Error PRJ0013 -System resource could be critically low. Unable to create a pipe required to launch a build. +> System resource could be critically low. Unable to create a pipe required to launch a build. + +## Remarks This error indicates that system resources are low. To resolve this error, decrease system resource usage by other processes/applications. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0014.md b/docs/error-messages/tool-errors/project-build-error-prj0014.md index c865d37ae13..e2a69bf636d 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0014.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0014.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0014" title: "Project Build Error PRJ0014" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0014" +ms.date: 11/04/2016 f1_keywords: ["PRJ0014"] helpviewer_keywords: ["PRJ0014"] -ms.assetid: b08c6df1-1df1-4573-9fca-49de6c5a0c17 --- # Project Build Error PRJ0014 -The job object used to control the spawned processes has failed. The build cannot continue. +> The job object used to control the spawned processes has failed. The build cannot continue. + +## Remarks An error occurred in the development environment. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0015.md b/docs/error-messages/tool-errors/project-build-error-prj0015.md index 06083644403..7cf85655166 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0015.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0015.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0015" title: "Project Build Error PRJ0015" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0015" +ms.date: 11/04/2016 f1_keywords: ["PRJ0015"] helpviewer_keywords: ["PRJ0015"] -ms.assetid: 2096c8f1-e96c-49a4-a690-1cb893a8bf6f --- # Project Build Error PRJ0015 -The NULL device is missing from your system. We are unable to launch a build. +> The NULL device is missing from your system. We are unable to launch a build. + +## Remarks This error can be caused by low system resources. Close some applications or reboot. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0016.md b/docs/error-messages/tool-errors/project-build-error-prj0016.md index d187b7b7db7..a4432287490 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0016.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0016.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0016" title: "Project Build Error PRJ0016" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0016" +ms.date: 11/04/2016 f1_keywords: ["PRJ0016"] helpviewer_keywords: ["PRJ0016"] -ms.assetid: e9745336-883a-4c70-9c40-7753e02f0325 --- # Project Build Error PRJ0016 -The user's security settings prevent the process from being created. These settings are required for building. +> The user's security settings prevent the process from being created. These settings are required for building. + +## Remarks You are logged in as a user who does not have permissions to create processes using a process. You must change the permission levels for this user account, or contact your account administrator. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0017.md b/docs/error-messages/tool-errors/project-build-error-prj0017.md index 58cc800c983..4f5d3e8d954 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0017.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0017.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Project Build Error PRJ0017" title: "Project Build Error PRJ0017" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0017" +ms.date: 11/04/2016 f1_keywords: ["PRJ0017"] helpviewer_keywords: ["PRJ0017"] -ms.assetid: a192729f-bb10-486a-bfda-a7843fa259b2 --- # Project Build Error PRJ0017 -The current working directory is invalid. +> The current working directory is invalid. + +## Remarks The path to the current working directory is longer than _MAXPATH. To resolve this error, do not create your project at such a deep level. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0019.md b/docs/error-messages/tool-errors/project-build-error-prj0019.md index 1945c29a55c..5780072ddec 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0019.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0019.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0019" title: "Project Build Error PRJ0019" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0019" +ms.date: 11/04/2016 f1_keywords: ["PRJ0019"] helpviewer_keywords: ["PRJ0019"] -ms.assetid: 5390a62b-aacf-4bc8-b9d7-08f1e0233423 --- # Project Build Error PRJ0019 -A tool returned an error code from +> A tool returned an error code from + +## Remarks An error level was nonzero for a custom build step or build event. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0020.md b/docs/error-messages/tool-errors/project-build-error-prj0020.md index f853411257b..2dbf934ea7d 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0020.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0020.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0020" title: "Project Build Error PRJ0020" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0020" +ms.date: 08/27/2018 f1_keywords: ["PRJ0020"] helpviewer_keywords: ["PRJ0020"] -ms.assetid: 54bb8cd4-af7c-4d62-8125-3ab5ff5f2cc4 --- # Project Build Error PRJ0020 > Tool '*tool*', Property '*property*' contains invalid file name '*file*'. +## Remarks + The file name *file*, specified in the property *property* for the tool *tool*, was invalid. You may have used an unknown or invalid macro. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0021.md b/docs/error-messages/tool-errors/project-build-error-prj0021.md index 335cba2b63a..ca4900c35c4 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0021.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0021.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0021" title: "Project Build Error PRJ0021" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0021" +ms.date: 08/27/2018 f1_keywords: ["PRJ0021"] helpviewer_keywords: ["PRJ0021"] -ms.assetid: bcab794d-4a6d-4b4d-aaca-73676c0cec75 --- # Project Build Error PRJ0021 > Tool '*tool*', Property '*property*' contains invalid file name. +## Remarks + The file name specified in the property *property* for the tool *tool* was invalid. You may have used an unknown or invalid macro. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0022.md b/docs/error-messages/tool-errors/project-build-error-prj0022.md index 7d1cf48c185..2dd36de88b6 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0022.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0022.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0022" title: "Project Build Error PRJ0022" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0022" +ms.date: 08/27/2018 f1_keywords: ["PRJ0022"] helpviewer_keywords: ["PRJ0022"] -ms.assetid: 691344a8-fc70-4aeb-9372-dde72f4588a4 --- # Project Build Error PRJ0022 > Unknown Tool, Property '*property*' contains invalid file name '*file*'. +## Remarks + The file name *file* specified in the property *property* was invalid. You may have used an unknown or invalid macro. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0023.md b/docs/error-messages/tool-errors/project-build-error-prj0023.md index 377423e3135..a0604f9e768 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0023.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0023.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0023" title: "Project Build Error PRJ0023" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0023" +ms.date: 08/27/2018 f1_keywords: ["PRJ0023"] helpviewer_keywords: ["PRJ0023"] -ms.assetid: ed55a320-e7c8-489f-886e-825feee0d576 --- # Project Build Error PRJ0023 > Tool '*tool*', Unknown Property contains invalid file name '*file*'. +## Remarks + The file name *file* specified for the tool *tool* was invalid. You may have used an unknown or invalid macro. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0024.md b/docs/error-messages/tool-errors/project-build-error-prj0024.md index 600cb4212a7..0511d1e1f07 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0024.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0024.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Error PRJ0024" title: "Project Build Error PRJ0024" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0024" +ms.date: 08/27/2018 f1_keywords: ["PRJ0024"] helpviewer_keywords: ["PRJ0024"] -ms.assetid: 8bde6368-6c1b-4e04-bc5e-3c6d0b8fa1d7 --- # Project Build Error PRJ0024 > Unicode path '*path*' could not be translated to user's ANSI code page. +## Remarks + *path* is the original Unicode version of the path string. This error can occur in cases where there is a Unicode path that cannot be directly translated to ANSI for the current system code page. This error may occur if you are working with a project that was developed on a system using a code page that is not on your computer. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0025.md b/docs/error-messages/tool-errors/project-build-error-prj0025.md index 835df947fff..44c275ba9e7 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0025.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0025.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Project Build Error PRJ0025" title: "Project Build Error PRJ0025" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0025" +ms.date: 08/27/2018 f1_keywords: ["PRJ0025"] helpviewer_keywords: ["PRJ0025"] -ms.assetid: 57725c78-bc63-44f3-9667-2969b2d7c41d --- # Project Build Error PRJ0025 @@ -12,6 +11,8 @@ ms.assetid: 57725c78-bc63-44f3-9667-2969b2d7c41d > > *UNICODE contents of file* +## Remarks + The project system found Unicode contents in a custom build rule or build event that cannot be translated properly to the user's current ANSI code page. The resolution for this error is to update the contents of the build rule or build event to use ANSI or to install the code page on your computer and set it as the system default. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0026.md b/docs/error-messages/tool-errors/project-build-error-prj0026.md index b839afbf8bf..3e31ffebaf3 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0026.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0026.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Project Build Error PRJ0026" title: "Project Build Error PRJ0026" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0026" +ms.date: 08/27/2018 f1_keywords: ["PRJ0026"] helpviewer_keywords: ["PRJ0026"] -ms.assetid: c52bc9b5-8b22-4015-b477-8645ae56c489 --- # Project Build Error PRJ0026 @@ -12,6 +11,8 @@ ms.assetid: c52bc9b5-8b22-4015-b477-8645ae56c489 > > *UNICODE contents of file* +## Remarks + The project system found Unicode contents in a response file that cannot be translated properly to the user's current ANSI code page. The resolution for this error is to update the contents of the response file to use ANSI or to install the code page on your computer and set it as the system default. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0027.md b/docs/error-messages/tool-errors/project-build-error-prj0027.md index 36d7d27b448..d6a3617908f 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0027.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0027.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0027" title: "Project Build Error PRJ0027" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0027" +ms.date: 11/04/2016 f1_keywords: ["PRJ0027"] helpviewer_keywords: ["PRJ0027"] -ms.assetid: 85d73a78-4b9e-4553-9f5d-2d76c48a790a --- # Project Build Error PRJ0027 -Unicode log message 'contents' contains content that could not be translated to the user's ANSI code page. +> Unicode log message 'contents' contains content that could not be translated to the user's ANSI code page. + +## Remarks You will typically only see this warning in conjunction with errors in creating batch and/or response files. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0028.md b/docs/error-messages/tool-errors/project-build-error-prj0028.md index f6beac1e882..a161469f323 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0028.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0028.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0028" title: "Project Build Error PRJ0028" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0028" +ms.date: 11/04/2016 f1_keywords: ["PRJ0028"] helpviewer_keywords: ["PRJ0028"] -ms.assetid: 0a6e0da7-cb3d-40b6-81a6-6196a9c2526b --- # Project Build Error PRJ0028 -Temporary file 'file' contains Unicode contents that could not be translated to user's ANSI code page. +> Temporary file 'file' contains Unicode contents that could not be translated to user's ANSI code page. + +## Remarks A value was specified with the [/MIDL (Specify MIDL Command Line Options)](../../build/reference/midl-specify-midl-command-line-options.md) linker option that could not be resolved by the system code page. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0030.md b/docs/error-messages/tool-errors/project-build-error-prj0030.md index 74d695229ae..0484a509b7f 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0030.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0030.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0030" title: "Project Build Error PRJ0030" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0030" +ms.date: 11/04/2016 f1_keywords: ["PRJ0030"] helpviewer_keywords: ["PRJ0030"] -ms.assetid: c48b3727-e166-46e7-bcd7-3e5b2ac5c1d4 --- # Project Build Error PRJ0030 -Macro expansion error. Evaluate recursion exceeded 32 levels for $(macro). +> Macro expansion error. Evaluate recursion exceeded 32 levels for $(macro). + +## Remarks This error is caused by recursion in your macros. For example, if you set the **Intermediate Directory** property (see [General Property Page (Project)](../../build/reference/general-property-page-project.md)) to $(IntDir), you will have recursion. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0031.md b/docs/error-messages/tool-errors/project-build-error-prj0031.md index 5b40281db8b..7584eabdb47 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0031.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0031.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0031" title: "Project Build Error PRJ0031" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0031" +ms.date: 11/04/2016 f1_keywords: ["PRJ0031"] helpviewer_keywords: ["PRJ0031"] -ms.assetid: b42435c6-e570-4f8e-9ad5-12a7ea69ccb2 --- # Project Build Error PRJ0031 -The 'Outputs' property for the custom build step for file 'file' contained 'macro' which evaluates out to 'macro_expansion'. +> The 'Outputs' property for the custom build step for file 'file' contained 'macro' which evaluates out to 'macro_expansion'. + +## Remarks A custom build step on a file had bad output probably due to a macro evaluation problem. This error could also mean that the path is badly formed, containing characters or combinations of characters that are illegal in a file path. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0032.md b/docs/error-messages/tool-errors/project-build-error-prj0032.md index 2659dca6ce3..d324d45d78c 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0032.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0032.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0032" title: "Project Build Error PRJ0032" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0032" +ms.date: 11/04/2016 f1_keywords: ["PRJ0032"] helpviewer_keywords: ["PRJ0032"] -ms.assetid: bc6acbea-4041-4237-8b5a-f0434705d89f --- # Project Build Error PRJ0032 -The 'Outputs' property for the project-level custom build step contained 'macro' which evaluates out to 'macro_expansion'. +> The 'Outputs' property for the project-level custom build step contained 'macro' which evaluates out to 'macro_expansion'. + +## Remarks A custom build step on a project had bad output probably due to a macro evaluation problem. This error could also mean that the path is badly formed, containing characters or combinations of characters that are illegal in a file path. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0033.md b/docs/error-messages/tool-errors/project-build-error-prj0033.md index 445a667d8d8..66b3196d043 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0033.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0033.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0033" title: "Project Build Error PRJ0033" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0033" +ms.date: 11/04/2016 f1_keywords: ["PRJ0033"] helpviewer_keywords: ["PRJ0033"] -ms.assetid: 84d4a052-0586-4b78-9315-81c1e8386c1e --- # Project Build Error PRJ0033 -The 'Additional Dependencies' property for the custom build step for file 'file' contained 'macro' which evaluates out to 'macro_expansion'. +> The 'Additional Dependencies' property for the custom build step for file 'file' contained 'macro' which evaluates out to 'macro_expansion'. + +## Remarks A custom build step on a file contained an error in its additional dependency probably due to a macro evaluation problem. This error could also mean that the path is badly formed, containing characters or combinations of characters that are illegal in a file path. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0034.md b/docs/error-messages/tool-errors/project-build-error-prj0034.md index dcfc2b8fb53..00b59e0ae24 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0034.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0034.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0034" title: "Project Build Error PRJ0034" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0034" +ms.date: 11/04/2016 f1_keywords: ["PRJ0034"] helpviewer_keywords: ["PRJ0034"] -ms.assetid: 1da4a55b-231b-4476-8545-6997628fbc00 --- # Project Build Error PRJ0034 -The 'Additional Dependencies' property for the project-level custom build step contained 'macro' which evaluates out to 'macro_expansion'. +> The 'Additional Dependencies' property for the project-level custom build step contained 'macro' which evaluates out to 'macro_expansion'. + +## Remarks A custom build step on a project contained an error in its additional dependency probably due to a macro evaluation problem. This error could also mean that the path is badly formed, containing characters or combinations of characters that are illegal in a file path. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0035.md b/docs/error-messages/tool-errors/project-build-error-prj0035.md index ecfd160c80a..0bfd95e4b65 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0035.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0035.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: Project Build Error PRJ0035" title: "Project Build Error PRJ0035" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Error PRJ0035" +ms.date: 08/27/2018 f1_keywords: ["PRJ0035"] helpviewer_keywords: ["PRJ0035"] -ms.assetid: 0667116d-338c-40a4-972c-da875f778cb5 --- # Project Build Error PRJ0035 @@ -12,6 +11,8 @@ ms.assetid: 0667116d-338c-40a4-972c-da875f778cb5 > > *UNICODE contents of file* +## Remarks + *file* is the XML file created as the command line to the Web Deployment tool. The project system found Unicode characters in some property on the Web Deployment property page that can't properly be translated to ANSI. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0036.md b/docs/error-messages/tool-errors/project-build-error-prj0036.md index 078ae4b5220..51622101d0b 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0036.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0036.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0036" title: "Project Build Error PRJ0036" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0036" +ms.date: 11/04/2016 f1_keywords: ["PRJ0036"] helpviewer_keywords: ["PRJ0036"] -ms.assetid: ee215cd1-2d66-474d-9a63-b9096f1c4923 --- # Project Build Error PRJ0036 -The 'Additional Files' property for the Web Deployment Tool contained an invalid entry. +> The 'Additional Files' property for the Web Deployment Tool contained an invalid entry. + +## Remarks The Additional Files property on the Web Deployment property page contained an error, possibly due to a macro evaluation problem. This error could also mean that the path is badly formed, containing characters or combinations of characters that are illegal in a file path. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0040.md b/docs/error-messages/tool-errors/project-build-error-prj0040.md index c9d2860e395..5007bb30d4d 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0040.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0040.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0040" title: "Project Build Error PRJ0040" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0040" +ms.date: 11/04/2016 f1_keywords: ["PRJ0040"] helpviewer_keywords: ["PRJ0040"] -ms.assetid: 6549ac62-c87b-4edf-b541-32221abe97ec --- # Project Build Error PRJ0040 -Internal error on build. Cannot continue. Please reload project and try again. +> Internal error on build. Cannot continue. Please reload project and try again. + +## Remarks The project system was unable to process your project. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0044.md b/docs/error-messages/tool-errors/project-build-error-prj0044.md index 0168bd57f8d..1521e028e80 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0044.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0044.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0044" title: "Project Build Error PRJ0044" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0044" +ms.date: 11/04/2016 f1_keywords: ["PRJ0044"] helpviewer_keywords: ["PRJ0044"] -ms.assetid: 5d78c45a-f9e9-4d2b-a3b6-5a5d1421ab84 --- # Project Build Error PRJ0044 -The 'Additional Dependencies' property for custom build rule 'rule' assigned to file 'file' is invalid. The property contained 'string' which evaluates to 'value'. +> The 'Additional Dependencies' property for custom build rule 'rule' assigned to file 'file' is invalid. The property contained 'string' which evaluates to 'value'. + +## Remarks The **Additional Dependencies** property evaluated to an empty string, or to a string that contained invalid characters (any character that could not be in a file or directory name). Custom build rules need the output of the build action. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0046.md b/docs/error-messages/tool-errors/project-build-error-prj0046.md index 4c773d14331..85972cd2536 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0046.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0046.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Project Build Error PRJ0046" title: "Project Build Error PRJ0046" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0046" +ms.date: 11/04/2016 f1_keywords: ["PRJ0046"] helpviewer_keywords: ["PRJ0046"] -ms.assetid: 59442319-4481-4b97-a4a5-16f52fc718e7 --- # Project Build Error PRJ0046 -Could not spawn command line because the one specified was empty. +> Could not spawn command line because the one specified was empty. + +## Remarks An empty command line was specified for a makefile configuration; the command line is required. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0047.md b/docs/error-messages/tool-errors/project-build-error-prj0047.md index 77037f5823a..74eeb76498a 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0047.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0047.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0047" title: "Project Build Error PRJ0047" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0047" +ms.date: 11/04/2016 f1_keywords: ["PRJ0047"] helpviewer_keywords: ["PRJ0047"] -ms.assetid: 7c79149d-4b7c-4a24-830e-904d92c1f0b4 --- # Project Build Error PRJ0047 -Could not resume the suspended process. The build has failed. +> Could not resume the suspended process. The build has failed. + +## Remarks An error occurred in the development environment. diff --git a/docs/error-messages/tool-errors/project-build-error-prj0050.md b/docs/error-messages/tool-errors/project-build-error-prj0050.md index 1d7c06e4027..842578f2ae6 100644 --- a/docs/error-messages/tool-errors/project-build-error-prj0050.md +++ b/docs/error-messages/tool-errors/project-build-error-prj0050.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Error PRJ0050" title: "Project Build Error PRJ0050" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Error PRJ0050" +ms.date: 11/04/2016 f1_keywords: ["PRJ0050"] helpviewer_keywords: ["PRJ0050"] -ms.assetid: ceef3b37-0acf-4abd-ac62-aa830b4fa145 --- # Project Build Error PRJ0050 -Failed to register output. Please ensure you have the appropriate permissions to modify the registry. +> Failed to register output. Please ensure you have the appropriate permissions to modify the registry. + +## Remarks The Visual C++ build system was not able to register the output of the build (dll or .exe). You need to be logged on as an administrator to modify the registry. diff --git a/docs/error-messages/tool-errors/project-build-errors-and-warnings-prjxxxx.md b/docs/error-messages/tool-errors/project-build-errors-and-warnings-prjxxxx.md index 8622e006449..e05ebacd66b 100644 --- a/docs/error-messages/tool-errors/project-build-errors-and-warnings-prjxxxx.md +++ b/docs/error-messages/tool-errors/project-build-errors-and-warnings-prjxxxx.md @@ -1,62 +1,65 @@ --- -description: "Learn more about: Project build errors and warnings (PRJxxxx)" title: "Project build errors and warnings" -ms.date: "04/16/2019" -ms.assetid: 79d223ed-986a-4536-8299-aec8356b449c +description: "Learn more about: Project build errors and warnings (PRJxxxx)" +ms.date: 04/16/2019 --- # Project build errors and warnings (PRJxxxx) This section is a reference to the errors generated by the Project build tools. Project build errors and warnings have the form PRJ*xxxx*, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Project build errors -[Project build error PRJ0002](project-build-error-prj0002.md) \ -[Project build error PRJ0003](project-build-error-prj0003.md) \ -[Project build error PRJ0004](project-build-error-prj0004.md) \ -[Project build error PRJ0005](project-build-error-prj0005.md) \ -[Project build error PRJ0006](project-build-error-prj0006.md) \ -[Project build error PRJ0007](project-build-error-prj0007.md) \ -[Project build error PRJ0008](project-build-error-prj0008.md) \ -[Project build error PRJ0009](project-build-error-prj0009.md) \ -[Project build error PRJ0013](project-build-error-prj0013.md) \ -[Project build error PRJ0014](project-build-error-prj0014.md) \ -[Project build error PRJ0015](project-build-error-prj0015.md) \ -[Project build error PRJ0016](project-build-error-prj0016.md) \ -[Project build error PRJ0017](project-build-error-prj0017.md) \ -[Project build error PRJ0019](project-build-error-prj0019.md) \ -[Project build error PRJ0020](project-build-error-prj0020.md) \ -[Project build error PRJ0021](project-build-error-prj0021.md) \ -[Project build error PRJ0022](project-build-error-prj0022.md) \ -[Project build error PRJ0023](project-build-error-prj0023.md) \ -[Project build error PRJ0024](project-build-error-prj0024.md) \ -[Project build error PRJ0025](project-build-error-prj0025.md) \ -[Project build error PRJ0026](project-build-error-prj0026.md) \ -[Project build error PRJ0027](project-build-error-prj0027.md) \ -[Project build error PRJ0028](project-build-error-prj0028.md) \ -[Project build error PRJ0030](project-build-error-prj0030.md) \ -[Project build error PRJ0031](project-build-error-prj0031.md) \ -[Project build error PRJ0032](project-build-error-prj0032.md) \ -[Project build error PRJ0033](project-build-error-prj0033.md) \ -[Project build error PRJ0034](project-build-error-prj0034.md) \ -[Project build error PRJ0035](project-build-error-prj0035.md) \ -[Project build error PRJ0036](project-build-error-prj0036.md) \ -[Project build error PRJ0040](project-build-error-prj0040.md) \ -[Project build error PRJ0044](project-build-error-prj0044.md) \ -[Project build error PRJ0046](project-build-error-prj0046.md) \ -[Project build error PRJ0047](project-build-error-prj0047.md) \ -[Project build error PRJ0050](project-build-error-prj0050.md) +| Error | Message | +|--|--| +| [Project build error PRJ0002](project-build-error-prj0002.md) | error result returned from '*command line*'. | +| [Project build error PRJ0003](project-build-error-prj0003.md) | Error spawning '*command line*'. | +| [Project build error PRJ0004](project-build-error-prj0004.md) | Could not generate command line for the '*tool*' tool. | +| [Project build error PRJ0005](project-build-error-prj0005.md) | Unable to create a temporary file in directory 'directory'. | +| [Project build error PRJ0006](project-build-error-prj0006.md) | Could not open the temporary file 'file'. Make sure the file exists and that the directory is not write-protected. | +| [Project build error PRJ0007](project-build-error-prj0007.md) | Could not create output directory 'directory'. | +| [Project build error PRJ0008](project-build-error-prj0008.md) | Could not delete file 'file'. | +| [Project build error PRJ0009](project-build-error-prj0009.md) | Build log could not be opened for writing. | +| [Project build error PRJ0013](project-build-error-prj0013.md) | System resource could be critically low. Unable to create a pipe required to launch a build. | +| [Project build error PRJ0014](project-build-error-prj0014.md) | The job object used to control the spawned processes has failed. The build cannot continue. | +| [Project build error PRJ0015](project-build-error-prj0015.md) | The NULL device is missing from your system. We are unable to launch a build. | +| [Project build error PRJ0016](project-build-error-prj0016.md) | The user's security settings prevent the process from being created. These settings are required for building. | +| [Project build error PRJ0017](project-build-error-prj0017.md) | The current working directory is invalid. | +| [Project build error PRJ0019](project-build-error-prj0019.md) | A tool returned an error code from | +| [Project build error PRJ0020](project-build-error-prj0020.md) | Tool '*tool*', Property '*property*' contains invalid file name '*file*'. | +| [Project build error PRJ0021](project-build-error-prj0021.md) | Tool '*tool*', Property '*property*' contains invalid file name. | +| [Project build error PRJ0022](project-build-error-prj0022.md) | Unknown Tool, Property '*property*' contains invalid file name '*file*'. | +| [Project build error PRJ0023](project-build-error-prj0023.md) | Tool '*tool*', Unknown Property contains invalid file name '*file*'. | +| [Project build error PRJ0024](project-build-error-prj0024.md) | Unicode path '*path*' could not be translated to user's ANSI code page. | +| [Project build error PRJ0025](project-build-error-prj0025.md) | Batch file '*file*' contains Unicode contents that could not be translated to user's ANSI code page. | +| [Project build error PRJ0026](project-build-error-prj0026.md) | Response file '*file*' contains Unicode contents that could not be translated to user's ANSI code page. | +| [Project build error PRJ0027](project-build-error-prj0027.md) | Unicode log message 'contents' contains content that could not be translated to the user's ANSI code page. | +| [Project build error PRJ0028](project-build-error-prj0028.md) | Temporary file 'file' contains Unicode contents that could not be translated to user's ANSI code page. | +| [Project build error PRJ0030](project-build-error-prj0030.md) | Macro expansion error. Evaluate recursion exceeded 32 levels for $(macro). | +| [Project build error PRJ0031](project-build-error-prj0031.md) | The 'Outputs' property for the custom build step for file 'file' contained 'macro' which evaluates out to 'macro_expansion'. | +| [Project build error PRJ0032](project-build-error-prj0032.md) | The 'Outputs' property for the project-level custom build step contained 'macro' which evaluates out to 'macro_expansion'. | +| [Project build error PRJ0033](project-build-error-prj0033.md) | The 'Additional Dependencies' property for the custom build step for file 'file' contained 'macro' which evaluates out to 'macro_expansion'. | +| [Project build error PRJ0034](project-build-error-prj0034.md) | The 'Additional Dependencies' property for the project-level custom build step contained 'macro' which evaluates out to 'macro_expansion'. | +| [Project build error PRJ0035](project-build-error-prj0035.md) | XML file '*file*' contains Unicode contents that could not be translated to user's ANSI code page. | +| [Project build error PRJ0036](project-build-error-prj0036.md) | The 'Additional Files' property for the Web Deployment Tool contained an invalid entry. | +| [Project build error PRJ0040](project-build-error-prj0040.md) | Internal error on build. Cannot continue. Please reload project and try again. | +| [Project build error PRJ0044](project-build-error-prj0044.md) | The 'Additional Dependencies' property for custom build rule 'rule' assigned to file 'file' is invalid. The property contained 'string' which evaluates to 'value'. | +| [Project build error PRJ0046](project-build-error-prj0046.md) | Could not spawn command line because the one specified was empty. | +| [Project build error PRJ0047](project-build-error-prj0047.md) | Could not resume the suspended process. The build has failed. | +| [Project build error PRJ0050](project-build-error-prj0050.md) | Failed to register output. Please ensure you have the appropriate permissions to modify the registry. | ## Project build warnings -[Project build warning PRJ0018](project-build-warning-prj0018.md) \ -[Project build warning PRJ0029](project-build-warning-prj0029.md) \ -[Project build warning PRJ0041](project-build-warning-prj0041.md) \ -[Project build warning PRJ0042](project-build-warning-prj0042.md) \ -[Project build warning PRJ0049](project-build-warning-prj0049.md) +| Warning | Message | +|--|--| +| [Project build warning PRJ0018](project-build-warning-prj0018.md) | The following environment variables were not found: | +| [Project build warning PRJ0029](project-build-warning-prj0029.md) | The 'Outputs' property for the project-level custom build step is not set. The custom build step will be skipped. | +| [Project build warning PRJ0041](project-build-warning-prj0041.md) | Cannot find missing dependency 'dependency' for file 'file'. Your project may still build, but may continue to appear out of date until this file is found. | +| [Project build warning PRJ0042](project-build-warning-prj0042.md) | The 'Outputs' property for the custom build step for file '*file*' is not set. The custom build step will be skipped. | +| [Project build warning PRJ0049](project-build-warning-prj0049.md) | Referenced target '\' requires .NET Framework \ and will fail to run on this project's target framework | ## 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)\ [Visual Studio projects | C++](../../build/creating-and-managing-visual-cpp-projects.md) diff --git a/docs/error-messages/tool-errors/project-build-warning-prj0018.md b/docs/error-messages/tool-errors/project-build-warning-prj0018.md index e02b3c1b322..a5ec336c93a 100644 --- a/docs/error-messages/tool-errors/project-build-warning-prj0018.md +++ b/docs/error-messages/tool-errors/project-build-warning-prj0018.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Warning PRJ0018" title: "Project Build Warning PRJ0018" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Warning PRJ0018" +ms.date: 11/04/2016 f1_keywords: ["PRJ0018"] helpviewer_keywords: ["PRJ0018"] -ms.assetid: 1a3d9e40-6a35-4a74-b6ba-8079f7a82217 --- # Project Build Warning PRJ0018 -The following environment variables were not found: +> The following environment variables were not found: + +## Remarks An environment variable is not defined. This error lists the environment variables that were not defined. diff --git a/docs/error-messages/tool-errors/project-build-warning-prj0029.md b/docs/error-messages/tool-errors/project-build-warning-prj0029.md index cebf87396e8..78a22ac3bac 100644 --- a/docs/error-messages/tool-errors/project-build-warning-prj0029.md +++ b/docs/error-messages/tool-errors/project-build-warning-prj0029.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Warning PRJ0029" title: "Project Build Warning PRJ0029" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Warning PRJ0029" +ms.date: 11/04/2016 f1_keywords: ["PRJ0029"] helpviewer_keywords: ["PRJ0029"] -ms.assetid: f02c09c6-09f3-4d44-8cd4-9a25336be1ea --- # Project Build Warning PRJ0029 -The 'Outputs' property for the project-level custom build step is not set. The custom build step will be skipped. +> The 'Outputs' property for the project-level custom build step is not set. The custom build step will be skipped. + +## Remarks A custom build step was not executed because no output was specified. diff --git a/docs/error-messages/tool-errors/project-build-warning-prj0041.md b/docs/error-messages/tool-errors/project-build-warning-prj0041.md index 7241c771d4a..4a500c4ce83 100644 --- a/docs/error-messages/tool-errors/project-build-warning-prj0041.md +++ b/docs/error-messages/tool-errors/project-build-warning-prj0041.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Project Build Warning PRJ0041" title: "Project Build Warning PRJ0041" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Warning PRJ0041" +ms.date: 11/04/2016 f1_keywords: ["PRJ0041"] helpviewer_keywords: ["PRJ0041"] -ms.assetid: dc9f4cf9-6bd5-4222-89e8-7802a59bb96b --- # Project Build Warning PRJ0041 -Cannot find missing dependency 'dependency' for file 'file'. Your project may still build, but may continue to appear out of date until this file is found. +> Cannot find missing dependency 'dependency' for file 'file'. Your project may still build, but may continue to appear out of date until this file is found. + +## Remarks A file (resource file or .idl/.odl file, for example, contained an include statement that the project system could not resolve. diff --git a/docs/error-messages/tool-errors/project-build-warning-prj0042.md b/docs/error-messages/tool-errors/project-build-warning-prj0042.md index 3951812d71c..a85189952fa 100644 --- a/docs/error-messages/tool-errors/project-build-warning-prj0042.md +++ b/docs/error-messages/tool-errors/project-build-warning-prj0042.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Project Build Warning PRJ0042" title: "Project Build Warning PRJ0042" -ms.date: "08/27/2018" +description: "Learn more about: Project Build Warning PRJ0042" +ms.date: 08/27/2018 f1_keywords: ["PRJ0042"] helpviewer_keywords: ["PRJ0042"] -ms.assetid: 682c9999-6f85-409f-b102-00c93243f74f --- # Project Build Warning PRJ0042 > The 'Outputs' property for the custom build step for file '*file*' is not set. The custom build step will be skipped. +## Remarks + A custom build step was not executed because no output was specified. To resolve this error, do one the following: diff --git a/docs/error-messages/tool-errors/project-build-warning-prj0049.md b/docs/error-messages/tool-errors/project-build-warning-prj0049.md index ee21f0e2b2a..0073df2310b 100644 --- a/docs/error-messages/tool-errors/project-build-warning-prj0049.md +++ b/docs/error-messages/tool-errors/project-build-warning-prj0049.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: Project Build Warning PRJ0049" title: "Project Build Warning PRJ0049" -ms.date: "11/04/2016" +description: "Learn more about: Project Build Warning PRJ0049" +ms.date: 11/04/2016 +f1_keywords: ["PRJ0049"] helpviewer_keywords: ["PRJ0049"] -ms.assetid: 8b38afa1-e080-4efd-ae89-776cfd044413 --- # Project Build Warning PRJ0049 -Referenced target '\' requires .NET Framework \ and will fail to run on this project's target framework +> Referenced target '\' requires .NET Framework \ and will fail to run on this project's target framework + +## Remarks Applications created by using Visual Studio 2008 can specify which version of the .NET Framework they should target. If you add a reference to an assembly or project that depends on a version of the .NET Framework that is later than the targeted version, you will get this warning at compile time. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2001.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2001.md index a6dc03c0ac6..b807eea4e4a 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2001.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2001.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2001" title: "Resource Compiler Error RC2001" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2001" +ms.date: 11/04/2016 f1_keywords: ["RC2001"] helpviewer_keywords: ["RC2001"] -ms.assetid: 92bfb4c0-1879-4606-bb9f-ef7368707b4a --- # Resource Compiler Error RC2001 -newline in constant +> newline in constant + +## Remarks A string constant was continued on a second line without either a backslash (**\\**) or closing and opening double quotation marks (**"**). diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2007.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2007.md index 7273ed71fdf..dbfac5c5bfb 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2007.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2007.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2007" title: "Resource Compiler Error RC2007" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2007" +ms.date: 11/04/2016 f1_keywords: ["RC2007"] helpviewer_keywords: ["RC2007"] -ms.assetid: a616e506-bef2-4155-9fe0-dbccac8954d3 --- # Resource Compiler Error RC2007 -\#define syntax +> #define syntax + +## Remarks An identifier was expected following `#define` in a preprocessing directive. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2015.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2015.md index 5b717ab7cbc..035bfd9f4fd 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2015.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2015.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2015" title: "Resource Compiler Error RC2015" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2015" +ms.date: 11/04/2016 f1_keywords: ["RC2015"] helpviewer_keywords: ["RC2015"] -ms.assetid: 99691683-fb9e-4e61-beb1-12e484858570 --- # Resource Compiler Error RC2015 -too many chars in constant +> too many chars in constant + +## Remarks A character constant contained more than two characters. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2017.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2017.md index abba418bcbe..f0ea17ecac3 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2017.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2017.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2017" title: "Resource Compiler Error RC2017" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2017" +ms.date: 11/04/2016 f1_keywords: ["RC2017"] helpviewer_keywords: ["RC2017"] -ms.assetid: 5fcc0135-cd60-4b1d-a7dd-8a4f2312697b --- # Resource Compiler Error RC2017 -illegal escape sequence +> illegal escape sequence + +## Remarks An escape sequence appeared where one was not expected. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2101.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2101.md index 90d7026affd..95a520dc668 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2101.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2101.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2101" title: "Resource Compiler Error RC2101" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2101" +ms.date: 11/04/2016 f1_keywords: ["RC2101"] helpviewer_keywords: ["RC2101"] -ms.assetid: 580f9d74-162f-41e9-9438-ddbe3457c359 --- # Resource Compiler Error RC2101 -Invalid directive in preprocessed RC file +> Invalid directive in preprocessed RC file + +## Remarks The Resource Compiler file contains a **#pragma** directive. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2103.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2103.md index c49524f2c12..2399c255c57 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2103.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2103.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2103" title: "Resource Compiler Error RC2103" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2103" +ms.date: 11/04/2016 f1_keywords: ["RC2103"] helpviewer_keywords: ["RC2103"] -ms.assetid: eedf2366-d1c3-4e7e-815c-d367d976b3f6 --- # Resource Compiler Error RC2103 -unexpected end of file in string literal +> unexpected end of file in string literal + +## Remarks An end of file was found before the end of a string. The string is probably missing a closing double quotation mark (**"**). diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2104.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2104.md index eb9bbcda543..1ce67b04525 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2104.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2104.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2104" title: "Resource Compiler Error RC2104" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2104" +ms.date: 11/04/2016 f1_keywords: ["RC2104"] helpviewer_keywords: ["RC2104"] -ms.assetid: 792a3bd8-cb4c-4817-b288-4ce37082b582 --- # Resource Compiler Error RC2104 -undefined keyword or key name: key +> undefined keyword or key name: key + +## Remarks The specified keyword or key name is not defined. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2107.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2107.md index 329977b1988..9258f3d82c9 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2107.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2107.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2107" title: "Resource Compiler Error RC2107" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2107" +ms.date: 11/04/2016 f1_keywords: ["RC2107"] helpviewer_keywords: ["RC2107"] -ms.assetid: f1786128-aa86-4cdb-a095-05a0b66b5608 --- # Resource Compiler Error RC2107 -**expected numeric command value** +> expected numeric command value + +## Remarks The Resource Compiler was expecting a numeric *idvalue* field in the **ACCELERATORS** statement. Make sure that you have used a `#define` constant to specify the value and that the constant is spelled correctly. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2109.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2109.md index f94aac2e868..28eaffebead 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2109.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2109.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2109" title: "Resource Compiler Error RC2109" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2109" +ms.date: 11/04/2016 f1_keywords: ["RC2109"] helpviewer_keywords: ["RC2109"] -ms.assetid: b800aa67-33c0-42f5-81a2-7a64a3b6b824 --- # Resource Compiler Error RC2109 -expected numerical dialog constant +> expected numerical dialog constant + +## Remarks A **DIALOG** statement requires integer values for the *x, y, width*, and *height* fields. Make sure these values are included after the **DIALOG** keyword and that they are not negative. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2111.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2111.md index 20b4cc9b36d..159bd5e1ed8 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2111.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2111.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2111" title: "Resource Compiler Error RC2111" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2111" +ms.date: 11/04/2016 f1_keywords: ["RC2111"] helpviewer_keywords: ["RC2111"] -ms.assetid: 118cba57-82a4-4199-acf4-9d9561946218 --- # Resource Compiler Error RC2111 -invalid control type +> invalid control type + +## Remarks Each CONTROL statement in a **DIALOG** statement must be one of the following: 3STATE, AUTO3, AUTOCHECK, AUTORADIO, BEDIT, CHECKBOX, COMBOBOX, CONTROL, CTEXT, DEFPUSHBUTTON, EDITTEXT, GROUPBOX, HEDIT, ICON, IEDIT, LISTBOX, LTEXT, PUSHBOX, PUSHBUTTON, RADIOBUTTON, RTEXT, SCROLLBAR, USERBUTTON. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2112.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2112.md index 452c0280680..e03480d20e3 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2112.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2112.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2112" title: "Resource Compiler Error RC2112" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2112" +ms.date: 11/04/2016 f1_keywords: ["RC2112"] helpviewer_keywords: ["RC2112"] -ms.assetid: e9f29540-a90d-4989-a6e8-5f8f32015bd9 --- # Resource Compiler Error RC2112 -BEGIN expected in dialog +> BEGIN expected in dialog + +## Remarks The **BEGIN** keyword must immediately follow the **DIALOG** keyword. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2113.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2113.md index c62fc7fcbf1..d33a9cd82ca 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2113.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2113.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2113" title: "Resource Compiler Error RC2113" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2113" +ms.date: 11/04/2016 f1_keywords: ["RC2113"] helpviewer_keywords: ["RC2113"] -ms.assetid: cbf52e93-ab14-49b7-9ce8-fb55877602ec --- # Resource Compiler Error RC2113 -END expected in dialog +> END expected in dialog + +## Remarks The **END** keyword must occur at the end of a **DIALOG** statement. Make sure there are no open quotes left from the preceding statement. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2114.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2114.md index 87705494bec..d43e41ab86f 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2114.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2114.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2114" title: "Resource Compiler Error RC2114" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2114" +ms.date: 11/04/2016 f1_keywords: ["RC2114"] helpviewer_keywords: ["RC2114"] -ms.assetid: abdfdc46-6601-451f-8e81-81e92bcd2208 --- # Resource Compiler Error RC2114 -expected control class name +> expected control class name + +## Remarks The `class` field of a CONTROL statement in the **DIALOG** statement must be one of the following types: BUTTON, COMBOBOX, EDIT, LISTBOX, SCROLLBAR, STATIC, or user-defined. Make sure the class is spelled correctly. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2116.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2116.md index c43b2deabbb..1b227079bfe 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2116.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2116.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2116" title: "Resource Compiler Error RC2116" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2116" +ms.date: 11/04/2016 f1_keywords: ["RC2116"] helpviewer_keywords: ["RC2116"] -ms.assetid: d9203ddf-798d-490b-be41-0dd3f7d53653 --- # Resource Compiler Error RC2116 -expecting number for ID +> expecting number for ID + +## Remarks Expecting a number for the `id` field of a control statement in the **DIALOG** statement. Make sure you have a number or `#define` statement for the control ID. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2122.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2122.md index 7a8d7e682d3..d275f06f2a9 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2122.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2122.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2122" title: "Resource Compiler Error RC2122" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2122" +ms.date: 11/04/2016 f1_keywords: ["RC2122"] helpviewer_keywords: ["RC2122"] -ms.assetid: c2f02ec1-1ce8-4a13-b35e-7cd416fa9f41 --- # Resource Compiler Error RC2122 -unknown menu subtype +> unknown menu subtype + +## Remarks The *item-definition* field of the **MENU** statement can contain only **MENUITEM** and **POPUP** statements. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2124.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2124.md index a7b4b921d33..eb59025dd5f 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2124.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2124.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2124" title: "Resource Compiler Error RC2124" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2124" +ms.date: 11/04/2016 f1_keywords: ["RC2124"] helpviewer_keywords: ["RC2124"] -ms.assetid: 4eb5c4ec-ca9b-46a0-805b-35e040e9ed41 --- # Resource Compiler Error RC2124 -empty menus not allowed +> empty menus not allowed + +## Remarks An **END** keyword appears before any menu items are defined in the **MENU** statement. The Resource Compiler does not permit empty menus. Make sure you do not have any open quotation marks within the **MENU** statement. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2127.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2127.md index c3a1a1018d4..a82cf52c6db 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2127.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2127.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2127" title: "Resource Compiler Error RC2127" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2127" +ms.date: 11/04/2016 f1_keywords: ["RC2127"] helpviewer_keywords: ["RC2127"] -ms.assetid: 13c1599d-ac4c-4044-a59a-48e69511ef7e --- # Resource Compiler Error RC2127 -version WORDs separated by commas expected +> version WORDs separated by commas expected + +## Remarks Version numbers in a version resource should be of type **WORD**, and separated by commas. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2135.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2135.md index 81091b335fb..e4a11942710 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2135.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2135.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2135" title: "Resource Compiler Error RC2135" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2135" +ms.date: 11/04/2016 f1_keywords: ["RC2135"] helpviewer_keywords: ["RC2135"] -ms.assetid: 1509a0fa-1cb7-4654-bcb3-ad5ac973e659 --- # Resource Compiler Error RC2135 -file not found: filename +> file not found: filename + +## Remarks The file specified in the Resource Compiler command line was not found. Check to see whether the file has been moved to another directory and whether the file name and path are typed correctly. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2144.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2144.md index 18382c57438..7fe5c107fca 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2144.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2144.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2144" title: "Resource Compiler Error RC2144" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2144" +ms.date: 11/04/2016 f1_keywords: ["RC2144"] helpviewer_keywords: ["RC2144"] -ms.assetid: 1b3ff39a-92cd-4a04-b1a3-b1fa6a805813 --- # Resource Compiler Error RC2144 -PRIMARY LANGUAGE ID not a number +> PRIMARY LANGUAGE ID not a number + +## Remarks The PRIMARY LANGUAGE ID must be a hexadecimal language ID. See [Language and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md) in the *Run-Time Library Reference* for a list of valid Language IDs. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2147.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2147.md index 6e29e0a636e..09009bcb002 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2147.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2147.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2147" title: "Resource Compiler Error RC2147" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2147" +ms.date: 11/04/2016 f1_keywords: ["RC2147"] helpviewer_keywords: ["RC2147"] -ms.assetid: 09974f06-1731-4e70-b373-f9218e0ee8d9 --- # Resource Compiler Error RC2147 -SUBLANGUAGE ID not a number +> SUBLANGUAGE ID not a number + +## Remarks The SUBLANGUAGE ID value must be a number. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2148.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2148.md index a5db826be2f..40d6110c5cc 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2148.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2148.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2148" title: "Resource Compiler Error RC2148" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2148" +ms.date: 11/04/2016 f1_keywords: ["RC2148"] helpviewer_keywords: ["RC2148"] -ms.assetid: 0290065c-35d3-4815-80c5-40bf7132ae1d --- # Resource Compiler Error RC2148 -SUBLANGUAGE ID too large +> SUBLANGUAGE ID too large + +## Remarks The SUBLANGUAGE ID value was out of range. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2151.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2151.md index 5f5b597acdd..3ed804bfabf 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2151.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2151.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2151" title: "Resource Compiler Error RC2151" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2151" +ms.date: 11/04/2016 f1_keywords: ["RC2151"] helpviewer_keywords: ["RC2151"] -ms.assetid: 3c47e535-c78d-4338-aab9-9b47e2c34728 --- # Resource Compiler Error RC2151 -cannot re-use string constants +> cannot re-use string constants + +## Remarks You are using the same value twice in a **STRINGTABLE** statement. Make sure you are not mixing overlapping decimal and hexadecimal values. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2152.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2152.md index 543e1ca9945..ff275d02746 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2152.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2152.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2152" title: "Resource Compiler Error RC2152" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2152" +ms.date: 11/04/2016 f1_keywords: ["RC2152"] helpviewer_keywords: ["RC2152"] -ms.assetid: 8efcba8f-9971-43cc-a1cd-8d7c9aec133c --- # Resource Compiler Error RC2152 -invalid control character +> invalid control character + +## Remarks A control character in the **ACCELERATORS** statement is invalid. A valid control character consists of one letter (only) following a caret (**^**). diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2162.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2162.md index b88dac5c06d..9a45dc6be3e 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2162.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2162.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2162" title: "Resource Compiler Error RC2162" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2162" +ms.date: 11/04/2016 f1_keywords: ["RC2162"] helpviewer_keywords: ["RC2162"] -ms.assetid: 4ac713b7-3067-436c-83fd-4180438c4f2c --- # Resource Compiler Error RC2162 -expected macro formal parameter +> expected macro formal parameter + +## Remarks The token following a stringizing operator (**#**) was not a formal parameter name. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2163.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2163.md index 236af060128..6db89f5ffed 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2163.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2163.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2163" title: "Resource Compiler Error RC2163" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2163" +ms.date: 11/04/2016 f1_keywords: ["RC2163"] helpviewer_keywords: ["RC2163"] -ms.assetid: a7e95939-9267-4262-9b49-90dc4157a7da --- # Resource Compiler Error RC2163 -accelerator type required [ASCII or VIRTKEY] +> accelerator type required [ASCII or VIRTKEY] + +## Remarks The `type` field in the **ACCELERATORS** statement must contain either the ASCII or VIRTKEY value. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2164.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2164.md index b6ea0321840..532f85db497 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2164.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2164.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2164" title: "Resource Compiler Error RC2164" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2164" +ms.date: 11/04/2016 f1_keywords: ["RC2164"] helpviewer_keywords: ["RC2164"] -ms.assetid: 23d7691d-80f3-4979-a519-378e5498d2d1 --- # Resource Compiler Error RC2164 -unexpected value in RCDATA +> unexpected value in RCDATA + +## Remarks The *raw-data* values in the **RCDATA** statement must be integers or strings, each separated by a comma. Make sure you did not leave out a comma or leave out a quotation mark around a string. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2165.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2165.md index d0fc2be2f2b..f18cebc686b 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2165.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2165.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2165" title: "Resource Compiler Error RC2165" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2165" +ms.date: 11/04/2016 f1_keywords: ["RC2165"] helpviewer_keywords: ["RC2165"] -ms.assetid: bf7d4630-9355-47e3-87fa-6693fcf0ef0d --- # Resource Compiler Error RC2165 -string not found in DLGINCLUDE statement +> string not found in DLGINCLUDE statement + +## Remarks The statement did not specify a valid include file. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2167.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2167.md index 930bd48228a..ac84004be8e 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2167.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2167.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2167" title: "Resource Compiler Error RC2167" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2167" +ms.date: 11/04/2016 f1_keywords: ["RC2167"] helpviewer_keywords: ["RC2167"] -ms.assetid: 9b24a8eb-367b-4ff6-8266-b0c215f32d6a --- # Resource Compiler Error RC2167 -unrecognized VERSIONINFO field; BEGIN or comma expected +> unrecognized VERSIONINFO field; BEGIN or comma expected + +## Remarks An unrecognized field was found in the **FIXED** part of a **VERSIONINFO** structure declaration. A **VERSIONINFO** field must be DWORDS separated by a comma. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2169.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2169.md index 361c09d9706..78767f39494 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2169.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2169.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2169" title: "Resource Compiler Error RC2169" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2169" +ms.date: 11/04/2016 f1_keywords: ["RC2169"] helpviewer_keywords: ["RC2169"] -ms.assetid: 832c19ad-a2e2-4f50-b493-26b791877600 --- # Resource Compiler Error RC2169 -resource file filename is not in 2.03 format +> resource file filename is not in 2.03 format + +## Remarks The specified resource used a format earlier than version 2.03. The resource file must be converted or recreated using the format for version 3.00 or later. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2170.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2170.md index 4aba900e450..c0ed41f444d 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2170.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2170.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RC2170" title: "Resource Compiler Error RC2170" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2170" +ms.date: 11/04/2016 f1_keywords: ["RC2170"] helpviewer_keywords: ["RC2170"] -ms.assetid: 6ea80c98-0942-41a8-b0b2-2c16c255adf5 --- # Resource Compiler Error RC2170 -bitmap file filename is not in 3.00 format +> bitmap file filename is not in 3.00 format + +## Remarks Bitmaps using the Windows version 2.x format cannot be used in version 3.x resource files. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2171.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2171.md index 13e76b8e9c9..c8b1c0605d8 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2171.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2171.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2171" title: "Resource Compiler Error RC2171" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2171" +ms.date: 11/04/2016 f1_keywords: ["RC2171"] helpviewer_keywords: ["RC2171"] -ms.assetid: 0c959938-e744-43f3-b460-f05547ffea2a --- # Resource Compiler Error RC2171 -unknown DIB header format +> unknown DIB header format + +## Remarks The bitmap header is not a **BITMAPCOREHEADER** or **BITMAPINFOHEADER** structure. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rc2175.md b/docs/error-messages/tool-errors/resource-compiler-error-rc2175.md index 41d4e56fa14..3c74a7ea3c4 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rc2175.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rc2175.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Error RC2175" title: "Resource Compiler Error RC2175" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RC2175" +ms.date: 11/04/2016 f1_keywords: ["RC2175"] helpviewer_keywords: ["RC2175"] -ms.assetid: 3864a371-dba8-41a7-962c-e792709774f1 --- # Resource Compiler Error RC2175 -resource file filename is not in 3.00 format +> resource file filename is not in 3.00 format + +## Remarks The specified resource used a format earlier than version 3.00. The resource file must be converted or recreated using the format for version 3.00 or later. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rw2001.md b/docs/error-messages/tool-errors/resource-compiler-error-rw2001.md index 197696abe86..c4ae99cc7aa 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rw2001.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rw2001.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Error RW2001" title: "Resource Compiler Error RW2001" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RW2001" +ms.date: 11/04/2016 f1_keywords: ["RW2001"] helpviewer_keywords: ["RW2001"] -ms.assetid: 963bdc7d-6ebe-4378-8bbc-47dfcf5d330c --- # Resource Compiler Error RW2001 -Invalid directive in preprocessed RC file +> Invalid directive in preprocessed RC file + +## Remarks The RC file contains a **#pragma** directive. diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rw2002.md b/docs/error-messages/tool-errors/resource-compiler-error-rw2002.md index c2e99143b32..f840e80f4ea 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rw2002.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rw2002.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Resource Compiler Error RW2002" title: "Resource Compiler Error RW2002" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RW2002" +ms.date: 11/04/2016 f1_keywords: ["RW2002"] helpviewer_keywords: ["RW2002"] -ms.assetid: b1d1a49b-b50b-4b0b-9f09-c7762e2dbe8f --- # Resource Compiler Error RW2002 -Parsing error +> Parsing error ### To fix by checking the following possible causes diff --git a/docs/error-messages/tool-errors/resource-compiler-error-rw2003.md b/docs/error-messages/tool-errors/resource-compiler-error-rw2003.md index 13968d07395..22346f8261c 100644 --- a/docs/error-messages/tool-errors/resource-compiler-error-rw2003.md +++ b/docs/error-messages/tool-errors/resource-compiler-error-rw2003.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Resource Compiler Error RW2003" title: "Resource Compiler Error RW2003" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Error RW2003" +ms.date: 11/04/2016 f1_keywords: ["RW2003"] helpviewer_keywords: ["RW2003"] -ms.assetid: 9dc0ba70-6776-4aef-b316-5f1711d8e42e --- # Resource Compiler Error RW2003 -Generation Error +> Generation Error ### To fix by checking the following possible causes 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 86313c39160..74e0908987d 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,98 +1,103 @@ --- -description: "Learn more about: Resource compiler errors and warnings (RCxxxx, RWxxxx)" title: "Resource compiler errors and warnings" -ms.date: "04/17/2019" -ms.assetid: 0819f955-0561-491d-af3d-2453f4e2d035 +description: "Learn more about: Resource compiler errors and warnings (RCxxxx, RWxxxx)" +ms.date: 04/17/2019 --- # Resource compiler errors and warnings (RCxxxx, RWxxxx) This section is a reference to the errors generated by the resource compiler. Resource compiler errors and warnings have the form RC*xxxx* or RW*xxxx*, where *xxxx* is a four-digit number. -[!INCLUDE[error-boilerplate](../../error-messages/includes/error-boilerplate.md)] +[!INCLUDE[error-boilerplate](../includes/error-boilerplate.md)] ## Resource compiler fatal errors -[Resource compiler fatal error RC1002](resource-compiler-fatal-error-rc1002.md) \ -[Resource compiler fatal error RC1004](resource-compiler-fatal-error-rc1004.md) \ -[Resource compiler fatal error RC1009](resource-compiler-fatal-error-rc1009.md) \ -[Resource compiler fatal error RC1011](resource-compiler-fatal-error-rc1011.md) \ -[Resource compiler fatal error RC1015](resource-compiler-fatal-error-rc1015.md) \ -[Resource compiler fatal error RC1017](resource-compiler-fatal-error-rc1017.md) \ -[Resource compiler fatal error RC1018](resource-compiler-fatal-error-rc1018.md) \ -[Resource compiler fatal error RC1019](resource-compiler-fatal-error-rc1019.md) \ -[Resource compiler fatal error RC1020](resource-compiler-fatal-error-rc1020.md) \ -[Resource compiler fatal error RC1021](resource-compiler-fatal-error-rc1021.md) \ -[Resource compiler fatal error RC1022](resource-compiler-fatal-error-rc1022.md) \ -[Resource compiler fatal error RC1047](resource-compiler-fatal-error-rc1047.md) \ -[Resource compiler fatal error RC1052](resource-compiler-fatal-error-rc1052.md) \ -[Resource compiler fatal error RC1067](resource-compiler-fatal-error-rc1067.md) \ -[Resource compiler fatal error RC1101](resource-compiler-fatal-error-rc1101.md) \ -[Resource compiler fatal error RC1102](resource-compiler-fatal-error-rc1102.md) \ -[Resource compiler fatal error RC1105](resource-compiler-fatal-error-rc1105.md) \ -[Resource compiler fatal error RC1109](resource-compiler-fatal-error-rc1109.md) \ -[Resource compiler fatal error RC1116](resource-compiler-fatal-error-rc1116.md) \ -[Resource compiler fatal error RC1120](resource-compiler-fatal-error-rc1120.md) \ -[Resource compiler fatal error RC1121](resource-compiler-fatal-error-rc1121.md) \ -[Resource compiler fatal error RC1203](resource-compiler-fatal-error-rc1203.md) \ -[Resource compiler fatal error RC1205](resource-compiler-fatal-error-rc1205.md) \ -[Resource compiler fatal error RC1208](resource-compiler-fatal-error-rc1208.md) \ -[Resource compiler fatal error RW1004](resource-compiler-fatal-error-rw1004.md) \ -[Resource compiler fatal error RW1009](resource-compiler-fatal-error-rw1009.md) \ -[Resource compiler fatal error RW1016](resource-compiler-fatal-error-rw1016.md) \ -[Resource compiler fatal error RW1022](resource-compiler-fatal-error-rw1022.md) \ -[Resource compiler fatal error RW1023](resource-compiler-fatal-error-rw1023.md) \ -[Resource compiler fatal error RW1025](resource-compiler-fatal-error-rw1025.md) \ -[Resource compiler fatal error RW1030](resource-compiler-fatal-error-rw1030.md) +| Error | Message | +|--|--| +| [Resource compiler fatal error RC1002](resource-compiler-fatal-error-rc1002.md) | out of heap space | +| [Resource compiler fatal error RC1004](resource-compiler-fatal-error-rc1004.md) | unexpected end of file found | +| [Resource compiler fatal error RC1009](resource-compiler-fatal-error-rc1009.md) | compiler limit : macros too deeply nested 'macro' | +| [Resource compiler fatal error RC1011](resource-compiler-fatal-error-rc1011.md) | compiler limit : 'identifier' : macro definition too big | +| [Resource compiler fatal error RC1015](resource-compiler-fatal-error-rc1015.md) | cannot open include file 'filename' | +| [Resource compiler fatal error RC1017](resource-compiler-fatal-error-rc1017.md) | invalid integer constant expression | +| [Resource compiler fatal error RC1018](resource-compiler-fatal-error-rc1018.md) | unexpected '#elif' | +| [Resource compiler fatal error RC1019](resource-compiler-fatal-error-rc1019.md) | unexpected '#else' | +| [Resource compiler fatal error RC1020](resource-compiler-fatal-error-rc1020.md) | unexpected '#endif' | +| [Resource compiler fatal error RC1021](resource-compiler-fatal-error-rc1021.md) | invalid preprocessor command 'string' | +| [Resource compiler fatal error RC1022](resource-compiler-fatal-error-rc1022.md) | expected '#endif' | +| [Resource compiler fatal error RC1047](resource-compiler-fatal-error-rc1047.md) | too many option options, 'string' | +| [Resource compiler fatal error RC1052](resource-compiler-fatal-error-rc1052.md) | compiler limit : `#if` or `#ifdef` blocks nested too deeply | +| [Resource compiler fatal error RC1067](resource-compiler-fatal-error-rc1067.md) | compiler limit : identifier overflowed internal buffer | +| [Resource compiler fatal error RC1101](resource-compiler-fatal-error-rc1101.md) | no resource binary filename specified | +| [Resource compiler fatal error RC1102](resource-compiler-fatal-error-rc1102.md) | internal error : too many arguments to RCPP | +| [Resource compiler fatal error RC1105](resource-compiler-fatal-error-rc1105.md) | invalid switch, option: too many /d switches | +| [Resource compiler fatal error RC1109](resource-compiler-fatal-error-rc1109.md) | error creating resource-name | +| [Resource compiler fatal error RC1116](resource-compiler-fatal-error-rc1116.md) | RC terminating after preprocessor errors | +| [Resource compiler fatal error RC1120](resource-compiler-fatal-error-rc1120.md) | out of memory, needed number bytes | +| [Resource compiler fatal error RC1121](resource-compiler-fatal-error-rc1121.md) | I/O error reading file | +| [Resource compiler fatal error RC1203](resource-compiler-fatal-error-rc1203.md) | invalid hexadecimal default language ID specified. | +| [Resource compiler fatal error RC1205](resource-compiler-fatal-error-rc1205.md) | invalid code page | +| [Resource compiler fatal error RC1208](resource-compiler-fatal-error-rc1208.md) | input file has .RES extension | +| [Resource compiler fatal error RW1004](resource-compiler-fatal-error-rw1004.md) | Unexpected end of file | +| [Resource compiler fatal error RW1009](resource-compiler-fatal-error-rw1009.md) | Error creating resource-name | +| [Resource compiler fatal error RW1016](resource-compiler-fatal-error-rw1016.md) | RC terminating after preprocessor errors | +| [Resource compiler fatal error RW1022](resource-compiler-fatal-error-rw1022.md) | I/O error writing file | +| [Resource compiler fatal error RW1023](resource-compiler-fatal-error-rw1023.md) | I/O error writing file, drive full | +| [Resource compiler fatal error RW1025](resource-compiler-fatal-error-rw1025.md) | Out of far heap memory | +| [Resource compiler fatal error RW1030](resource-compiler-fatal-error-rw1030.md) | Output Error | ## Resource compiler errors -[Resource compiler error RC2001](resource-compiler-error-rc2001.md) \ -[Resource compiler error RC2007](resource-compiler-error-rc2007.md) \ -[Resource compiler error RC2015](resource-compiler-error-rc2015.md) \ -[Resource compiler error RC2017](resource-compiler-error-rc2017.md) \ -[Resource compiler error RC2101](resource-compiler-error-rc2101.md) \ -[Resource compiler error RC2103](resource-compiler-error-rc2103.md) \ -[Resource compiler error RC2104](resource-compiler-error-rc2104.md) \ -[Resource compiler error RC2107](resource-compiler-error-rc2107.md) \ -[Resource compiler error RC2109](resource-compiler-error-rc2109.md) \ -[Resource compiler error RC2111](resource-compiler-error-rc2111.md) \ -[Resource compiler error RC2112](resource-compiler-error-rc2112.md) \ -[Resource compiler error RC2113](resource-compiler-error-rc2113.md) \ -[Resource compiler error RC2114](resource-compiler-error-rc2114.md) \ -[Resource compiler error RC2116](resource-compiler-error-rc2116.md) \ -[Resource compiler error RC2122](resource-compiler-error-rc2122.md) \ -[Resource compiler error RC2124](resource-compiler-error-rc2124.md) \ -[Resource compiler error RC2127](resource-compiler-error-rc2127.md) \ -[Resource compiler error RC2135](resource-compiler-error-rc2135.md) \ -[Resource compiler error RC2144](resource-compiler-error-rc2144.md) \ -[Resource compiler error RC2147](resource-compiler-error-rc2147.md) \ -[Resource compiler error RC2148](resource-compiler-error-rc2148.md) \ -[Resource compiler error RC2151](resource-compiler-error-rc2151.md) \ -[Resource compiler error RC2152](resource-compiler-error-rc2152.md) \ -[Resource compiler error RC2162](resource-compiler-error-rc2162.md) \ -[Resource compiler error RC2163](resource-compiler-error-rc2163.md) \ -[Resource compiler error RC2164](resource-compiler-error-rc2164.md) \ -[Resource compiler error RC2165](resource-compiler-error-rc2165.md) \ -[Resource compiler error RC2167](resource-compiler-error-rc2167.md) \ -[Resource compiler error RC2169](resource-compiler-error-rc2169.md) \ -[Resource compiler error RC2170](resource-compiler-error-rc2170.md) \ -[Resource compiler error RC2171](resource-compiler-error-rc2171.md) \ -[Resource compiler error RC2175](resource-compiler-error-rc2175.md) \ -[Resource compiler error RW2001](resource-compiler-error-rw2001.md) \ -[Resource compiler error RW2002](resource-compiler-error-rw2002.md) \ -[Resource compiler error RW2003](resource-compiler-error-rw2003.md) +| Error | Message | +|--|--| +| [Resource compiler error RC2001](resource-compiler-error-rc2001.md) | newline in constant | +| [Resource compiler error RC2007](resource-compiler-error-rc2007.md) | #define syntax | +| [Resource compiler error RC2015](resource-compiler-error-rc2015.md) | too many chars in constant | +| [Resource compiler error RC2017](resource-compiler-error-rc2017.md) | illegal escape sequence | +| [Resource compiler error RC2101](resource-compiler-error-rc2101.md) | Invalid directive in preprocessed RC file | +| [Resource compiler error RC2103](resource-compiler-error-rc2103.md) | unexpected end of file in string literal | +| [Resource compiler error RC2104](resource-compiler-error-rc2104.md) | undefined keyword or key name: key | +| [Resource compiler error RC2107](resource-compiler-error-rc2107.md) | expected numeric command value | +| [Resource compiler error RC2109](resource-compiler-error-rc2109.md) | expected numerical dialog constant | +| [Resource compiler error RC2111](resource-compiler-error-rc2111.md) | invalid control type | +| [Resource compiler error RC2112](resource-compiler-error-rc2112.md) | `BEGIN` expected in dialog | +| [Resource compiler error RC2113](resource-compiler-error-rc2113.md) | `END` expected in dialog | +| [Resource compiler error RC2114](resource-compiler-error-rc2114.md) | expected control class name | +| [Resource compiler error RC2116](resource-compiler-error-rc2116.md) | expecting number for ID | +| [Resource compiler error RC2122](resource-compiler-error-rc2122.md) | unknown menu subtype | +| [Resource compiler error RC2124](resource-compiler-error-rc2124.md) | empty menus not allowed | +| [Resource compiler error RC2127](resource-compiler-error-rc2127.md) | version WORDs separated by commas expected | +| [Resource compiler error RC2135](resource-compiler-error-rc2135.md) | file not found: filename | +| [Resource compiler error RC2144](resource-compiler-error-rc2144.md) | PRIMARY LANGUAGE ID not a number | +| [Resource compiler error RC2147](resource-compiler-error-rc2147.md) | SUBLANGUAGE ID not a number | +| [Resource compiler error RC2148](resource-compiler-error-rc2148.md) | SUBLANGUAGE ID too large | +| [Resource compiler error RC2151](resource-compiler-error-rc2151.md) | cannot re-use string constants | +| [Resource compiler error RC2152](resource-compiler-error-rc2152.md) | invalid control character | +| [Resource compiler error RC2162](resource-compiler-error-rc2162.md) | expected macro formal parameter | +| [Resource compiler error RC2163](resource-compiler-error-rc2163.md) | accelerator type required [ASCII or VIRTKEY] | +| [Resource compiler error RC2164](resource-compiler-error-rc2164.md) | unexpected value in `RCDATA` | +| [Resource compiler error RC2165](resource-compiler-error-rc2165.md) | string not found in `DLGINCLUDE` statement | +| [Resource compiler error RC2167](resource-compiler-error-rc2167.md) | unrecognized `VERSIONINFO` field; `BEGIN` or comma expected | +| [Resource compiler error RC2169](resource-compiler-error-rc2169.md) | resource file filename is not in 2.03 format | +| [Resource compiler error RC2170](resource-compiler-error-rc2170.md) | bitmap file filename is not in 3.00 format | +| [Resource compiler error RC2171](resource-compiler-error-rc2171.md) | unknown DIB header format | +| [Resource compiler error RC2175](resource-compiler-error-rc2175.md) | resource file filename is not in 3.00 format | +| [Resource compiler error RW2001](resource-compiler-error-rw2001.md) | Invalid directive in preprocessed RC file | +| [Resource compiler error RW2002](resource-compiler-error-rw2002.md) | Parsing error | +| [Resource compiler error RW2003](resource-compiler-error-rw2003.md) | Generation Error | ## Resource compiler warnings -[Resource compiler warning RC4002](resource-compiler-warning-rc4002.md) \ -[Resource compiler warning RC4005](resource-compiler-warning-rc4005.md) \ -[Resource compiler warning RC4093](resource-compiler-warning-rc4093.md) \ -[Resource compiler warning RC4214](resource-compiler-warning-rc4214.md) \ -[Resource compiler warning RW4001](resource-compiler-warning-rw4001.md) \ -[Resource compiler warning RW4003](resource-compiler-warning-rw4003.md) \ -[Resource compiler warning RW4004](resource-compiler-warning-rw4004.md) +| Warning | Message | +|--|--| +| [Resource compiler warning RC4002](resource-compiler-warning-rc4002.md) | too many actual parameters for macro 'identifier' | +| [Resource compiler warning RC4005](resource-compiler-warning-rc4005.md) | 'identifier' : macro redefinition | +| [Resource compiler warning RC4093](resource-compiler-warning-rc4093.md) | unescaped newline in character constant in inactive code | +| [Resource compiler warning RC4214](resource-compiler-warning-rc4214.md) | Codepage not valid : ignored | +| [Resource compiler warning RW4001](resource-compiler-warning-rw4001.md) | .EXE processing options (/L /M /P /T /K /E /31 or /30) | +| [Resource compiler warning RW4003](resource-compiler-warning-rw4003.md) | `SHIFT` or `CONTROL` used without `VIRTKEY` | +| [Resource compiler warning RW4004](resource-compiler-warning-rw4004.md) | ASCII character not equivalent to virtual key code | ## 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/error-messages/tool-errors/resource-compiler-fatal-error-rc1002.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1002.md index fbff190aed7..7c7a2f888cc 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1002.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1002.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1002" title: "Resource Compiler Fatal Error RC1002" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1002" +ms.date: 11/04/2016 f1_keywords: ["RC1002"] helpviewer_keywords: ["RC1002"] -ms.assetid: b43dfece-0dc3-4d0b-9d8f-509699b9ae80 --- # Resource Compiler Fatal Error RC1002 -out of heap space +> out of heap space ### To fix by using the following possible solutions diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1004.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1004.md index 22db02bbda8..ad47b438b10 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1004.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1004.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1004" title: "Resource Compiler Fatal Error RC1004" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1004" +ms.date: 11/04/2016 f1_keywords: ["RC1004"] helpviewer_keywords: ["RC1004"] -ms.assetid: f9b703d4-6767-4721-9450-37079bcc7152 --- # Resource Compiler Fatal Error RC1004 -unexpected end of file found +> unexpected end of file found + +## Remarks This error can be caused by missing line feed and carriage return characters on the last line of a text file. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1009.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1009.md index 2f39079e129..edebbfee426 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1009.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1009.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1009" title: "Resource Compiler Fatal Error RC1009" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1009" +ms.date: 11/04/2016 f1_keywords: ["RC1009"] helpviewer_keywords: ["RC1009"] -ms.assetid: c377a068-bcc3-4ec4-b725-eb6927e10128 --- # Resource Compiler Fatal Error RC1009 -compiler limit : macros too deeply nested 'macro' +> compiler limit : macros too deeply nested 'macro' + +## Remarks The file exceeds the Resource Compiler limit for macro nesting. Revise the specified source file to decrease the nesting depth of its macros. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1011.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1011.md index b734e138b82..bcfe253dd25 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1011.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1011.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1011" title: "Resource Compiler Fatal Error RC1011" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1011" +ms.date: 11/04/2016 f1_keywords: ["RC1011"] helpviewer_keywords: ["RC1011"] -ms.assetid: ae0b89ec-0a31-4f8e-b9d0-f974152c185e --- # Resource Compiler Fatal Error RC1011 -compiler limit : 'identifier' : macro definition too big +> compiler limit : 'identifier' : macro definition too big + +## Remarks Try to split the definition into shorter definitions. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1015.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1015.md index b7031ac9c68..71057ea62f5 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1015.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1015.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1015" title: "Resource Compiler Fatal Error RC1015" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1015" +ms.date: 11/04/2016 f1_keywords: ["RC1015"] helpviewer_keywords: ["RC1015"] -ms.assetid: 23f187e1-5538-40b5-9042-edd2888f55c2 --- # Resource Compiler Fatal Error RC1015 -cannot open include file 'filename' +> cannot open include file 'filename' + +## Remarks The given include file does not exist, could not be opened, or was not found. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1017.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1017.md index d27bdb374da..361883e2bc9 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1017.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1017.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1017" title: "Resource Compiler Fatal Error RC1017" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1017" +ms.date: 11/04/2016 f1_keywords: ["RC1017"] helpviewer_keywords: ["RC1017"] -ms.assetid: 62ac1356-4481-49a0-8873-36daf42ffdcd --- # Resource Compiler Fatal Error RC1017 -invalid integer constant expression +> invalid integer constant expression + +## Remarks The expression in an `#if` directive either did not exist or does not evaluate to a constant. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1018.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1018.md index 0917185e27d..1f3808ee3ee 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1018.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1018.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1018" title: "Resource Compiler Fatal Error RC1018" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1018" +ms.date: 11/04/2016 f1_keywords: ["RC1018"] helpviewer_keywords: ["RC1018"] -ms.assetid: bb1d2efd-6898-412f-bb03-9ff94c54e4dc --- # Resource Compiler Fatal Error RC1018 -unexpected '#elif' +> unexpected '#elif' + +## Remarks The `#elif` directive did not appear within an `#if`, **#ifdef**, or **#ifndef** construct. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1019.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1019.md index b6056dd12f1..2ce46126549 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1019.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1019.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1019" title: "Resource Compiler Fatal Error RC1019" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1019" +ms.date: 11/04/2016 f1_keywords: ["RC1019"] helpviewer_keywords: ["RC1019"] -ms.assetid: 432fff44-04a9-4e13-91c6-870df6f0b4e4 --- # Resource Compiler Fatal Error RC1019 -unexpected '#else' +> unexpected '#else' + +## Remarks The `#else` directive did not appear within an `#if`, **#ifdef**, or **#ifndef** construct. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1020.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1020.md index bc34220daff..5454a1ef52e 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1020.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1020.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1020" title: "Resource Compiler Fatal Error RC1020" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1020" +ms.date: 11/04/2016 f1_keywords: ["RC1020"] helpviewer_keywords: ["RC1020"] -ms.assetid: 3e073ebf-9136-4bf8-ac6a-3c642ed64594 --- # Resource Compiler Fatal Error RC1020 -unexpected '#endif' +> unexpected '#endif' + +## Remarks An `#endif` directive appeared without a matching `#if`, **#ifdef**, or **#ifndef** directive. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1021.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1021.md index 1a2f34d860e..ccaa3ab1152 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1021.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1021.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1021" title: "Resource Compiler Fatal Error RC1021" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1021" +ms.date: 11/04/2016 f1_keywords: ["RC1021"] helpviewer_keywords: ["RC1021"] -ms.assetid: 9bc8858c-aa50-4b94-b60e-daf75ab45d77 --- # Resource Compiler Fatal Error RC1021 -invalid preprocessor command 'string' +> invalid preprocessor command 'string' + +## Remarks The characters following the number sign (**#**) did not form a valid preprocessor directive. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1022.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1022.md index dc3ef2c2b15..b85384b0a86 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1022.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1022.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1022" title: "Resource Compiler Fatal Error RC1022" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1022" +ms.date: 11/04/2016 f1_keywords: ["RC1022"] helpviewer_keywords: ["RC1022"] -ms.assetid: 30a0f3c7-08a8-4c40-b0de-46ee5feb789d --- # Resource Compiler Fatal Error RC1022 -expected '#endif' +> expected '#endif' + +## Remarks An `#if`, **#ifdef**, or **#ifndef** directive was not terminated with an `#endif` directive. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1047.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1047.md index 08e433d25b4..a3b544b8fb5 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1047.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1047.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1047" title: "Resource Compiler Fatal Error RC1047" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1047" +ms.date: 11/04/2016 f1_keywords: ["RC1047"] helpviewer_keywords: ["RC1047"] -ms.assetid: cd794a87-2634-4d25-9fd3-8c934e3c4d1e --- # Resource Compiler Fatal Error RC1047 -"too many option options, 'string'" +> "too many option options, 'string'" + +## Remarks The given option was specified too many times. The given string is the argument to the option that caused the error. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1052.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1052.md index c537dcb4165..ddda49f8d46 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1052.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1052.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1052" title: "Resource Compiler Fatal Error RC1052" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1052" +ms.date: 11/04/2016 f1_keywords: ["RC1052"] helpviewer_keywords: ["RC1052"] -ms.assetid: 59803673-492b-44fa-80fa-df93b8aaf9fb --- # Resource Compiler Fatal Error RC1052 -compiler limit : #if or #ifdef blocks nested too deeply +> compiler limit : #if or #ifdef blocks nested too deeply + +## Remarks The program exceeded the maximum allowable nesting levels for `#if` and `#ifdef` directives. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1067.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1067.md index 56528097fbf..a8a87351368 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1067.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1067.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1067" title: "Resource Compiler Fatal Error RC1067" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1067" +ms.date: 11/04/2016 f1_keywords: ["RC1067"] helpviewer_keywords: ["RC1067"] -ms.assetid: 6b23677d-428d-47c6-9207-8b85f7718e03 --- # Resource Compiler Fatal Error RC1067 -compiler limit : identifier overflowed internal buffer +> compiler limit : identifier overflowed internal buffer + +## Remarks An internal compiler limit was exceeded. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1101.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1101.md index df4bef463ad..889f6601ddd 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1101.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1101.md @@ -1,15 +1,16 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1101" title: "Resource Compiler Fatal Error RC1101" -ms.date: "08/27/2018" +description: "Learn more about: Resource Compiler Fatal Error RC1101" +ms.date: 08/27/2018 f1_keywords: ["RC1101"] helpviewer_keywords: ["RC1101"] -ms.assetid: ff273384-b819-464a-8c0e-d5951e4a28b4 --- # Resource Compiler Fatal Error RC1101 > no resource binary filename specified +## Remarks + The Rename Output (/fo) option was not followed by a filename. Use the following syntax for the /fo option: diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1102.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1102.md index ff54132abfa..9074d14d03f 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1102.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1102.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1102" title: "Resource Compiler Fatal Error RC1102" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1102" +ms.date: 11/04/2016 f1_keywords: ["RC1102"] helpviewer_keywords: ["RC1102"] -ms.assetid: bd2091f8-ef5e-4151-a8d6-98043e9422b6 --- # Resource Compiler Fatal Error RC1102 -internal error : too many arguments to RCPP +> internal error : too many arguments to RCPP + +## Remarks Too many arguments were passed to the Resource Compiler preprocessor. Reduce the number of symbols defined with the Define Symbols (/d) option by defining them in your source. This error can also be caused by specifying too many include file search paths using the Include Search Path option (/i). diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1105.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1105.md index 1bdddf86718..0e0c81d1668 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1105.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1105.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1105" title: "Resource Compiler Fatal Error RC1105" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1105" +ms.date: 11/04/2016 f1_keywords: ["RC1105"] helpviewer_keywords: ["RC1105"] -ms.assetid: 80ce18e7-44ee-4844-bede-321fe0844d56 --- # Resource Compiler Fatal Error RC1105 -invalid switch, option: too many /d switches +> invalid switch, option: too many /d switches + +## Remarks Too many symbols were defined using the Define Symbols (/d) option. Define some symbols in your source and recompile. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1109.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1109.md index 37e4d29ac92..0e23c8176dd 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1109.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1109.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1109" title: "Resource Compiler Fatal Error RC1109" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1109" +ms.date: 11/04/2016 f1_keywords: ["RC1109"] helpviewer_keywords: ["RC1109"] -ms.assetid: 2d3ec1c9-86fd-4d53-aa52-840c310b8328 --- # Resource Compiler Fatal Error RC1109 -error creating resource-name +> error creating resource-name + +## Remarks Could not create specified .res file. Make sure it is not being created on a read-only drive. Use the /V option to find out whether the file is being created. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1116.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1116.md index a2799212719..50acf9d9525 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1116.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1116.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1116" title: "Resource Compiler Fatal Error RC1116" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1116" +ms.date: 11/04/2016 f1_keywords: ["RC1116"] helpviewer_keywords: ["RC1116"] -ms.assetid: 1eacc5c3-d946-4615-83e4-1b8ebd472139 --- # Resource Compiler Fatal Error RC1116 -RC terminating after preprocessor errors +> RC terminating after preprocessor errors + +## Remarks The Resource Compiler halted due to other errors. Fix the other errors and recompile. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1120.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1120.md index 383bf936aee..cda7bd1fa63 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1120.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1120.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1120" title: "Resource Compiler Fatal Error RC1120" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1120" +ms.date: 11/04/2016 f1_keywords: ["RC1120"] helpviewer_keywords: ["RC1120"] -ms.assetid: 4e462931-e42e-42e3-8bfc-847677194286 --- # Resource Compiler Fatal Error RC1120 -out of memory, needed number bytes +> out of memory, needed number bytes + +## Remarks The Resource Compiler ran out of storage for items that it stores in its heap. Usually this is the result of having too many symbols. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1121.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1121.md index e8530fad72c..c9fc4d8f16a 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1121.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1121.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1121" title: "Resource Compiler Fatal Error RC1121" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1121" +ms.date: 11/04/2016 f1_keywords: ["RC1121"] helpviewer_keywords: ["RC1121"] -ms.assetid: 19ed8c71-d63a-4ff4-8652-a3ef52318a55 --- # Resource Compiler Fatal Error RC1121 -I/O error reading file +> I/O error reading file + +## Remarks The Resource Compiler was not able to read a file. Check that the drive containing the file is available and that the file is valid. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1203.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1203.md index 963dc534d54..405a2606b77 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1203.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1203.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1203" title: "Resource Compiler Fatal Error RC1203" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1203" +ms.date: 11/04/2016 f1_keywords: ["RC1203"] helpviewer_keywords: ["RC1203"] -ms.assetid: 60d08fb1-6a51-407c-854e-9a68080cfe2d --- # Resource Compiler Fatal Error RC1203 -invalid hexadecimal default language ID specified. +> invalid hexadecimal default language ID specified. + +## Remarks The Specify Default Language (/l) option was followed by an invalid hexadecimal language ID. See [Language and Country/Region Strings](../../c-runtime-library/locale-names-languages-and-country-region-strings.md) in the *Run-Time Library Reference* for a list of valid language IDs. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1205.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1205.md index abdce3697b0..445ae2739e7 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1205.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1205.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1205" title: "Resource Compiler Fatal Error RC1205" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1205" +ms.date: 11/04/2016 f1_keywords: ["RC1205"] helpviewer_keywords: ["RC1205"] -ms.assetid: 6cfbe019-ad8a-4267-b4b9-0d675bb3819a --- # Resource Compiler Fatal Error RC1205 -invalid code page +> invalid code page + +## Remarks The Specify Code Page (/c) option was followed by an invalid code page. See [Code Pages](../../c-runtime-library/code-pages.md) in the *Run-Time Library Reference* for more information. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1208.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1208.md index 1ceb943027e..4e98e6ab616 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1208.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rc1208.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RC1208" title: "Resource Compiler Fatal Error RC1208" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RC1208" +ms.date: 11/04/2016 f1_keywords: ["RC1208"] helpviewer_keywords: ["RC1208"] -ms.assetid: 7dacc4ec-3ebd-49b3-ba4c-1a2982bac720 --- # Resource Compiler Fatal Error RC1208 -input file has .RES extension +> input file has .RES extension + +## Remarks The .RES extension is used for Resource Compiler output. The .RC extension should be used for Resource Compiler scripts. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1004.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1004.md index 9c5b2e88282..be2236c6d44 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1004.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1004.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RW1004" title: "Resource Compiler Fatal Error RW1004" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RW1004" +ms.date: 11/04/2016 f1_keywords: ["RW1004"] helpviewer_keywords: ["RW1004"] -ms.assetid: 89cfcb02-a5d3-4271-be4f-df2ec3f94f3e --- # Resource Compiler Fatal Error RW1004 -Unexpected end of file +> Unexpected end of file + +## Remarks This error can be caused by missing line feed and carriage-return characters on the last line of a text file. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1009.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1009.md index b67063c43d9..c3865536102 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1009.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1009.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RW1009" title: "Resource Compiler Fatal Error RW1009" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RW1009" +ms.date: 11/04/2016 f1_keywords: ["RW1009"] helpviewer_keywords: ["RW1009"] -ms.assetid: c11aceaf-3527-4509-867d-e7b22254e276 --- # Resource Compiler Fatal Error RW1009 -Error creating resource-name +> Error creating resource-name + +## Remarks Could not create specified .res file. Make sure it is not being created on a read-only drive. Use /V to find out whether the file is being created. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1016.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1016.md index a7267fa6023..1475a9c5de5 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1016.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1016.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RW1016" title: "Resource Compiler Fatal Error RW1016" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RW1016" +ms.date: 11/04/2016 f1_keywords: ["RW1016"] helpviewer_keywords: ["RW1016"] -ms.assetid: 7c93b6b6-3684-4b09-b71d-160c400f75a5 --- # Resource Compiler Fatal Error RW1016 -RC terminating after preprocessor errors +> RC terminating after preprocessor errors + +## Remarks The Resource Compiler halted due to other errors. Fix the other errors and recompile. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1022.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1022.md index 1831781a0d5..c30a6760206 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1022.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1022.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RW1022" title: "Resource Compiler Fatal Error RW1022" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RW1022" +ms.date: 11/04/2016 f1_keywords: ["RW1022"] helpviewer_keywords: ["RW1022"] -ms.assetid: 6747c8a9-9c9b-4422-b414-0645d22092d0 --- # Resource Compiler Fatal Error RW1022 -**I/O error writing file** +> I/O error writing file + +## Remarks The Resource Compiler could not write to a file. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1023.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1023.md index 6a5c84c99e7..1d72a674995 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1023.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1023.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RW1023" title: "Resource Compiler Fatal Error RW1023" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RW1023" +ms.date: 11/04/2016 f1_keywords: ["RW1023"] helpviewer_keywords: ["RW1023"] -ms.assetid: 1fe0964a-a8cc-4ffa-a427-dbce39f23173 --- # Resource Compiler Fatal Error RW1023 -I/O error writing file, drive full +> I/O error writing file, drive full + +## Remarks Free space must equal at least twice the size of the executable file you are creating. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1025.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1025.md index 4e3a45b966d..036bafa0f34 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1025.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1025.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RW1025" title: "Resource Compiler Fatal Error RW1025" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RW1025" +ms.date: 11/04/2016 f1_keywords: ["RW1025"] helpviewer_keywords: ["RW1025"] -ms.assetid: 561a02af-e7e0-442a-8ad3-a00b2ca1b62e --- # Resource Compiler Fatal Error RW1025 -Out of far heap memory +> Out of far heap memory + +## Remarks Check for memory-resident software that might be taking up too much space. Use the CHKDSK program to find out how much memory you have. diff --git a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1030.md b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1030.md index b737df8c45d..35842f821ab 100644 --- a/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1030.md +++ b/docs/error-messages/tool-errors/resource-compiler-fatal-error-rw1030.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Fatal Error RW1030" title: "Resource Compiler Fatal Error RW1030" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Fatal Error RW1030" +ms.date: 11/04/2016 f1_keywords: ["RW1030"] helpviewer_keywords: ["RW1030"] -ms.assetid: 10727997-9ded-4afc-93b3-58fb435c3da8 --- # Resource Compiler Fatal Error RW1030 -Output Error +> Output Error + +## Remarks This error can be caused if the Resource Compiler was not able to create the destination file. Make sure that there is enough disk space and that you have write permission on the volume. diff --git a/docs/error-messages/tool-errors/resource-compiler-warning-rc4002.md b/docs/error-messages/tool-errors/resource-compiler-warning-rc4002.md index 7c41643dbe8..e85fed2d962 100644 --- a/docs/error-messages/tool-errors/resource-compiler-warning-rc4002.md +++ b/docs/error-messages/tool-errors/resource-compiler-warning-rc4002.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Warning RC4002" title: "Resource Compiler Warning RC4002" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Warning RC4002" +ms.date: 11/04/2016 f1_keywords: ["RC4002"] helpviewer_keywords: ["RC4002"] -ms.assetid: a157bc55-1a75-4337-aee4-e2ba61ff8cfa --- # Resource Compiler Warning RC4002 -too many actual parameters for macro 'identifier' +> too many actual parameters for macro 'identifier' + +## Remarks The number of actual parameters specified with the given identifier was greater than the number of formal parameters given in the macro definition of the identifier. diff --git a/docs/error-messages/tool-errors/resource-compiler-warning-rc4005.md b/docs/error-messages/tool-errors/resource-compiler-warning-rc4005.md index 15f614c9056..fba7a496464 100644 --- a/docs/error-messages/tool-errors/resource-compiler-warning-rc4005.md +++ b/docs/error-messages/tool-errors/resource-compiler-warning-rc4005.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Warning RC4005" title: "Resource Compiler Warning RC4005" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Warning RC4005" +ms.date: 11/04/2016 f1_keywords: ["RC4005"] helpviewer_keywords: ["RC4005"] -ms.assetid: 71f03b4a-c9a9-415d-920f-bf2e58507f93 --- # Resource Compiler Warning RC4005 -'identifier' : macro redefinition +> 'identifier' : macro redefinition + +## Remarks The identifier is defined twice. The compiler used the second macro definition. diff --git a/docs/error-messages/tool-errors/resource-compiler-warning-rc4093.md b/docs/error-messages/tool-errors/resource-compiler-warning-rc4093.md index ac1b20c66e7..a5729c8a6bf 100644 --- a/docs/error-messages/tool-errors/resource-compiler-warning-rc4093.md +++ b/docs/error-messages/tool-errors/resource-compiler-warning-rc4093.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Warning RC4093" title: "Resource Compiler Warning RC4093" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Warning RC4093" +ms.date: 11/04/2016 f1_keywords: ["RC4093"] helpviewer_keywords: ["RC4093"] -ms.assetid: 3c61b4a4-b418-465b-a4fd-cb1ff0adb8dd --- # Resource Compiler Warning RC4093 -unescaped newline in character constant in inactive code +> unescaped newline in character constant in inactive code + +## Remarks The constant expression of an `#if`, `#elif`, **#ifdef**, or **#ifndef** preprocessor directive evaluated to zero, making the code that follows inactive. Within that inactive code, a newline character appeared within a set of single or double quotation marks. diff --git a/docs/error-messages/tool-errors/resource-compiler-warning-rc4214.md b/docs/error-messages/tool-errors/resource-compiler-warning-rc4214.md index d1ba52ccd48..e8612428191 100644 --- a/docs/error-messages/tool-errors/resource-compiler-warning-rc4214.md +++ b/docs/error-messages/tool-errors/resource-compiler-warning-rc4214.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Warning RC4214" title: "Resource Compiler Warning RC4214" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Warning RC4214" +ms.date: 11/04/2016 f1_keywords: ["RC4214"] helpviewer_keywords: ["RC4214"] -ms.assetid: 79a8bf0d-8cc7-4159-a6a2-d0e543749069 --- # Resource Compiler Warning RC4214 -Codepage not valid : ignored +> Codepage not valid : ignored + +## Remarks The .rc file contained a codepage argument and the codepage specified is invalid. See [IsValidCodePage](/windows/win32/api/winnls/nf-winnls-isvalidcodepage) for more information. diff --git a/docs/error-messages/tool-errors/resource-compiler-warning-rw4001.md b/docs/error-messages/tool-errors/resource-compiler-warning-rw4001.md index 1218c5f7b8a..e800d8c2c8b 100644 --- a/docs/error-messages/tool-errors/resource-compiler-warning-rw4001.md +++ b/docs/error-messages/tool-errors/resource-compiler-warning-rw4001.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Warning RW4001" title: "Resource Compiler Warning RW4001" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Warning RW4001" +ms.date: 11/04/2016 f1_keywords: ["RW4001"] helpviewer_keywords: ["RW4001"] -ms.assetid: 7c2d35eb-9899-46f5-848d-7ef49c39d706 --- # Resource Compiler Warning RW4001 -.EXE processing options (/L /M /P /T /K /E /31 or /30) +> .EXE processing options (/L /M /P /T /K /E /31 or /30) + +## Remarks You specified EXE processing options, but there was no executable file to process. Don't use these options with a .res file. diff --git a/docs/error-messages/tool-errors/resource-compiler-warning-rw4003.md b/docs/error-messages/tool-errors/resource-compiler-warning-rw4003.md index 2ff11e08bfe..5d5c68ffcc1 100644 --- a/docs/error-messages/tool-errors/resource-compiler-warning-rw4003.md +++ b/docs/error-messages/tool-errors/resource-compiler-warning-rw4003.md @@ -1,13 +1,14 @@ --- -description: "Learn more about: Resource Compiler Warning RW4003" title: "Resource Compiler Warning RW4003" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Warning RW4003" +ms.date: 11/04/2016 f1_keywords: ["RW4003"] helpviewer_keywords: ["RW4003"] -ms.assetid: e9c289f2-c065-4f26-bc24-991953742abc --- # Resource Compiler Warning RW4003 -SHIFT or CONTROL used without VIRTKEY +> SHIFT or CONTROL used without VIRTKEY + +## Remarks In an accelerator table resource, SHIFT or CONTROL requires VIRTKEY. Because SHIFT and CONTROL are indicated as flag bits in a VIRTKEY type accelerator, they cannot exist independent from a VIRTKEY. diff --git a/docs/error-messages/tool-errors/resource-compiler-warning-rw4004.md b/docs/error-messages/tool-errors/resource-compiler-warning-rw4004.md index 16d53e49d0d..e54b5ee855d 100644 --- a/docs/error-messages/tool-errors/resource-compiler-warning-rw4004.md +++ b/docs/error-messages/tool-errors/resource-compiler-warning-rw4004.md @@ -1,14 +1,15 @@ --- -description: "Learn more about: Resource Compiler Warning RW4004" title: "Resource Compiler Warning RW4004" -ms.date: "11/04/2016" +description: "Learn more about: Resource Compiler Warning RW4004" +ms.date: 11/04/2016 f1_keywords: ["RW4004"] helpviewer_keywords: ["RW4004"] -ms.assetid: 596b6a89-9ce7-4ba7-bdcb-e8054c7efafa --- # Resource Compiler Warning RW4004 -ASCII character not equivalent to virtual key code +> ASCII character not equivalent to virtual key code + +## Remarks A string literal was used for the virtual key code in a VIRTKEY type accelerator. diff --git a/docs/error-messages/tool-errors/vectorizer-and-parallelizer-messages.md b/docs/error-messages/tool-errors/vectorizer-and-parallelizer-messages.md index 07ff21fb4e3..c364ea1966d 100644 --- a/docs/error-messages/tool-errors/vectorizer-and-parallelizer-messages.md +++ b/docs/error-messages/tool-errors/vectorizer-and-parallelizer-messages.md @@ -30,12 +30,16 @@ The 5*xx* reason codes apply to both the parallelizer and the vectorizer. | Reason code | Explanation | |--|--| -| 500 | A generic message that covers several cases: For example, the loop includes multiple exits, or the loop header doesn't end by incrementing the induction variable. | +| 500 | Induction variable discovery or recurrence failure. | | 501 | Induction variable isn't local; or upper bound isn't loop-invariant. | | 502 | Induction variable is stepped in some manner other than a simple +1. | | 503 | Loop includes exception-handling or switch statements. | | 504 | Loop body may throw an exception that requires destruction of a C++ object. | | 505 | Outer loop has a pre-incremented induction variable. Exiting analysis. | +| 506 | Loop structural or canonical form failure. | +| 507 | Bounds, initialization, termination, or compare consistency failure. | +| 508 | Stride derivation or usage failure | +| 509 | Loop direction acceptability failure. | ```cpp void code_500(int *A) diff --git a/docs/extensions/abstract-cpp-component-extensions.md b/docs/extensions/abstract-cpp-component-extensions.md index bb6484969db..495eb80faf8 100644 --- a/docs/extensions/abstract-cpp-component-extensions.md +++ b/docs/extensions/abstract-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: abstract (C++/CLI and C++/CX)" -title: "abstract (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "abstract (C++/CLI and C++/CX)" +description: "Learn more about: abstract (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["abstract", "abstract_cpp"] helpviewer_keywords: ["abstract keyword [C++]"] -ms.assetid: cbae3408-0378-4ac8-b70d-c016b381a6d5 --- -# abstract (C++/CLI and C++/CX) +# abstract (C++/CLI and C++/CX) The **abstract** keyword declares either: @@ -25,7 +24,7 @@ The **abstract** keyword declares either: ### Remarks -The first example syntax declares a class to be abstract. The *class-declaration* component can be either a native C++ declaration (**`class`**** or **`struct`**), or a C++ extension declaration (**ref class** or **ref struct**) if the `/ZW` or `/clr` compiler option is specified. +The first example syntax declares a class to be abstract. The *class-declaration* component can be either a native C++ declaration (**`class`** or **`struct`**), or a C++ extension declaration (**ref class** or **ref struct**) if the `/ZW` or `/clr` compiler option is specified. The second example syntax declares a virtual member function to be abstract. Declaring a function abstract is the same as declaring it a pure virtual function. Declaring a member function abstract also causes the enclosing class to be declared abstract. diff --git a/docs/extensions/attribute-parameter-types-cpp-component-extensions.md b/docs/extensions/attribute-parameter-types-cpp-component-extensions.md index fd508895ddc..6b54f8b8807 100644 --- a/docs/extensions/attribute-parameter-types-cpp-component-extensions.md +++ b/docs/extensions/attribute-parameter-types-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Attribute Parameter Types (C++/CLI and C++/CX)" -title: "Attribute Parameter Types (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Attribute Parameter Types (C++/CLI and C++/CX)" +description: "Learn more about: Attribute Parameter Types (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["custom attributes, parameter types"] -ms.assetid: d9f127a3-7f08-456f-acc6-256805632712 --- -# Attribute Parameter Types (C++/CLI and C++/CX) +# Attribute Parameter Types (C++/CLI and C++/CX) Values passed to attributes must be known to the compiler at compile time. Attribute parameters can be of the following types: diff --git a/docs/extensions/boxing-cpp-component-extensions.md b/docs/extensions/boxing-cpp-component-extensions.md index 6de754d4753..a25066d75d9 100644 --- a/docs/extensions/boxing-cpp-component-extensions.md +++ b/docs/extensions/boxing-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Boxing (C++/CLI and C++/CX)" -title: "Boxing (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Boxing (C++/CLI and C++/CX)" +description: "Learn more about: Boxing (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["boxing, C++"] -ms.assetid: b5fd2c98-c578-4f83-8257-6dd663478665 --- -# Boxing (C++/CLI and C++/CX) +# Boxing (C++/CLI and C++/CX) The conversion of value types to objects is called *boxing*, and the conversion of objects to value types is called *unboxing*. diff --git a/docs/extensions/classes-and-structs-cpp-component-extensions.md b/docs/extensions/classes-and-structs-cpp-component-extensions.md index 7f1310a5b73..43ca041916a 100644 --- a/docs/extensions/classes-and-structs-cpp-component-extensions.md +++ b/docs/extensions/classes-and-structs-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: ref class and ref struct (C++/CLI and C++/CX)" title: "ref class and ref struct (C++/CLI and C++/CX)" -ms.date: "05/30/2019" +description: "Learn more about: ref class and ref struct (C++/CLI and C++/CX)" +ms.date: 05/30/2019 ms.topic: "reference" f1_keywords: ["ref class", "value class", "ref struct", "value struct",] helpviewer_keywords: ["ref class keyword [C++]", "value class keyword [C++]", "value struct keyword [C++]", "ref struct keyword [C++]"] -ms.assetid: 5c360764-b229-49c6-9357-66213afbc372 --- -# ref class and ref struct (C++/CLI and C++/CX) +# ref class and ref struct (C++/CLI and C++/CX) The **ref class** or **ref struct** extensions declare a class or struct whose *object lifetime* is administered automatically. When the object is no longer accessible or goes out of scope, the memory is released. 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 98f1acc1285..c88366385c7 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/context-sensitive-keywords-cpp-component-extensions.md b/docs/extensions/context-sensitive-keywords-cpp-component-extensions.md index 443571ea5e2..8205699fbb6 100644 --- a/docs/extensions/context-sensitive-keywords-cpp-component-extensions.md +++ b/docs/extensions/context-sensitive-keywords-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: Context-Sensitive Keywords (C++/CLI and C++/CX)" -title: "Context-Sensitive Keywords (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Context-Sensitive Keywords (C++/CLI and C++/CX)" +description: "Learn more about: Context-Sensitive Keywords (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["internal_CPP"] helpviewer_keywords: ["context-sensitive keywords"] -ms.assetid: e33da089-f434-44e9-8cce-4668d05a8939 --- -# Context-Sensitive Keywords (C++/CLI and C++/CX) +# Context-Sensitive Keywords (C++/CLI and C++/CX) *Context-sensitive keywords* are language elements that are recognized only in specific contexts. Outside the specific context, a context-sensitive keyword can be a user-defined symbol. diff --git a/docs/extensions/delegate-cpp-component-extensions.md b/docs/extensions/delegate-cpp-component-extensions.md index 127af663e74..917f4954096 100644 --- a/docs/extensions/delegate-cpp-component-extensions.md +++ b/docs/extensions/delegate-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: delegate (C++/CLI and C++/CX)" -title: "delegate (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "delegate (C++/CLI and C++/CX)" +description: "Learn more about: delegate (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["delegate_cpp", "delegate"] helpviewer_keywords: ["delegate keyword [C++]"] -ms.assetid: 03caf23d-7873-4a23-9b34-becf42aaf429 --- -# delegate (C++/CLI and C++/CX) +# delegate (C++/CLI and C++/CX) Declares a type that represents a function pointer. diff --git a/docs/extensions/enum-class-cpp-component-extensions.md b/docs/extensions/enum-class-cpp-component-extensions.md index 38e1b9b11f0..9d90a533304 100644 --- a/docs/extensions/enum-class-cpp-component-extensions.md +++ b/docs/extensions/enum-class-cpp-component-extensions.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: enum class (C++/CLI and C++/CX)" -title: "enum class (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "enum class (C++/CLI and C++/CX)" +description: "Learn more about: enum class (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" -ms.assetid: 8010fa8c-bad6-45b4-8214-b4db64d7ffe1 --- -# enum class (C++/CLI and C++/CX) +# enum class (C++/CLI and C++/CX) Declares an enumeration at namespace scope, which is a user-defined type consisting of a set of named constants called enumerators. diff --git a/docs/extensions/exception-handling-cpp-component-extensions.md b/docs/extensions/exception-handling-cpp-component-extensions.md index 3c16ee20c28..56a65971ca7 100644 --- a/docs/extensions/exception-handling-cpp-component-extensions.md +++ b/docs/extensions/exception-handling-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Exception Handling (C++/CLI and C++/CX)" -title: "Exception Handling (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Exception Handling (C++/CLI and C++/CX)" +description: "Learn more about: Exception Handling (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["structured exception handling [C++], managed exceptions", "Exception class, managed applications", "exception handling", "C++ exception handling", "exception handling, types of", "System::Exception class in managed applications"] -ms.assetid: ccb11fe8-6938-41ac-b477-a183e85865b9 --- -# Exception Handling (C++/CLI and C++/CX) +# Exception Handling (C++/CLI and C++/CX) Applications compiled with the `/ZW` compiler option or `/clr` compiler option both use *exceptions* to handle unexpected errors during program execution. The following topics discuss exception handling in either C++/CX or C++/CLI applications. diff --git a/docs/extensions/explicit-overrides-cpp-component-extensions.md b/docs/extensions/explicit-overrides-cpp-component-extensions.md index cb5e4288ab6..7a5a8f8bb22 100644 --- a/docs/extensions/explicit-overrides-cpp-component-extensions.md +++ b/docs/extensions/explicit-overrides-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Explicit Overrides (C++/CLI and C++/CX)" -title: "Explicit Overrides (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Explicit Overrides (C++/CLI and C++/CX)" +description: "Learn more about: Explicit Overrides (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["overriding, override [C++]"] -ms.assetid: 4ec3eaf5-163b-4df8-8f16-7a2ec04c3d0f --- -# Explicit Overrides (C++/CLI and C++/CX) +# Explicit Overrides (C++/CLI and C++/CX) This topic discusses how to explicitly override a member of a base class or interface. A named (explicit) override should only be used to override a method with a derived method that has a different name. diff --git a/docs/extensions/generic-functions-cpp-cli.md b/docs/extensions/generic-functions-cpp-cli.md index ac022d7d72b..76441f7d41a 100644 --- a/docs/extensions/generic-functions-cpp-cli.md +++ b/docs/extensions/generic-functions-cpp-cli.md @@ -101,7 +101,7 @@ Generic functions are functions declared with one or more generic type parameter A `class` or `struct` constructor may not be declared with generic type parameters. -When called, the generic type parameter is replaced by an actual type. The actual type may be explicitly specified in angled brackets using syntax similar to a template function call. If called without the type parameters, the compiler will attempt to deduce the actual type from the parameters supplied in the function call. The compiler reports an error if the intended type argument can't be deduced from the parameters used. +When called, the generic type parameter is replaced by an actual type. The actual type may be explicitly specified in angled brackets using syntax similar to a function template call. If called without the type parameters, the compiler will attempt to deduce the actual type from the parameters supplied in the function call. The compiler reports an error if the intended type argument can't be deduced from the parameters used. ### Requirements diff --git a/docs/extensions/generic-interfaces-visual-cpp.md b/docs/extensions/generic-interfaces-visual-cpp.md index 29f3456ca9a..5fa795e2ef7 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/generics-cpp-component-extensions.md b/docs/extensions/generics-cpp-component-extensions.md index 6d268126910..3826f8d3dbe 100644 --- a/docs/extensions/generics-cpp-component-extensions.md +++ b/docs/extensions/generics-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -title: "Generics (C++/CLI and C++/CX)" +title: "Generics (C++/CLI and C++/CX)" description: "Links to content about the C++/CLI and C++/CX generics features, types, and methods." ms.date: 09/25/2020 ms.topic: "reference" f1_keywords: ["generic_cpp", "generic"] helpviewer_keywords: ["generics [C++]"] -ms.assetid: c7ccc316-a411-4c00-b2e2-f0c0eadc6cfd --- -# Generics (C++/CLI and C++/CX) +# Generics (C++/CLI and C++/CX) Generics are parameterized types and methods. In this section, find out which generic features both the Windows Runtime and the common language runtime support, and which ones only the common language runtime supports. You'll also find out how to author your own generic methods and types in C++/CLI, and how to use generic types authored in a .NET Framework language in C++/CLI. Finally, this section provides a comparison of generics and C++ templates. diff --git a/docs/extensions/handle-to-object-operator-hat-cpp-component-extensions.md b/docs/extensions/handle-to-object-operator-hat-cpp-component-extensions.md index 089f64f26e2..8bed5655da4 100644 --- a/docs/extensions/handle-to-object-operator-hat-cpp-component-extensions.md +++ b/docs/extensions/handle-to-object-operator-hat-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Handle to Object Operator (^) (C++/CLI and C++/CX)" -title: "Handle to Object Operator (^) (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Handle to Object Operator (^) (C++/CLI and C++/CX)" +description: "Learn more about: Handle to Object Operator (^) (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["^ handle to object [C++]"] -ms.assetid: 70c411e6-be57-4468-a944-6ea7be89f392 --- -# Handle to Object Operator (^) (C++/CLI and C++/CX) +# Handle to Object Operator (^) (C++/CLI and C++/CX) The *handle declarator* (`^`, pronounced "hat"), modifies the type [specifier](../cpp/declarations-and-definitions-cpp.md) to mean that the declared object should be automatically deleted when the system determines that the object is no longer accessible. 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 cc911e9bcb5..7a4bb01bf45 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-improve-performance-with-generics-visual-cpp.md b/docs/extensions/how-to-improve-performance-with-generics-visual-cpp.md index 583458caaa4..f9eba24de2f 100644 --- a/docs/extensions/how-to-improve-performance-with-generics-visual-cpp.md +++ b/docs/extensions/how-to-improve-performance-with-generics-visual-cpp.md @@ -1,24 +1,24 @@ --- -description: "Learn more about: How to: Improve Performance with Generics (C++/CLI)" -title: "How to: Improve Performance with Generics (C++/CLI)" -ms.date: "10/12/2018" +description: "Learn more about: How to: Improve performance with generics (C++/CLI)" +title: "How to: Improve performance with generics (C++/CLI)" +ms.date: 10/03/2022 ms.topic: "reference" helpviewer_keywords: ["performance, C++", "C++, performance", "C++, generics", "generics [C++], performance"] ms.assetid: f14a175b-301f-46cc-86e4-c82d35f9aa3e --- -# How to: Improve Performance with Generics (C++/CLI) +# How to: Improve performance with generics (C++/CLI) With generics, you can create reusable code based on a type parameter. The actual type of the type parameter is deferred until called by client code. For more information on generics, see [Generics](generics-cpp-component-extensions.md). -This article will discuss how generics can help increase the performance of an application that uses collections. +This article discusses how generics can help increase the performance of an application that uses collections. ## Example: Two main drawbacks of .NET Framework collections -The .NET Framework comes with many collection classes in the namespace. Most of these collections operate on objects of type . This allows collections to store any type, since all types in the .NET Framework, even value types, derive from . However, there are two drawbacks to this approach. +The .NET Framework comes with many collection classes in the namespace. Most of these collections operate on objects of type . Collections can store any type, since all types in the .NET Framework, even value types, derive from . However, there are two drawbacks to this approach. -First, if the collection is storing value types such as integers, the value must be boxed before being added to the collection and unboxed when the value is retrieved from the collection. These are expensive operations. +First, if the collection is storing value types such as integers, the value must be boxed before being added to the collection and unboxed when the value is retrieved from the collection. These operations are expensive. -Second, there is no way to control which types can be added to a collection. It is perfectly legal to add an integer and a string to the same collection, even though this is probably not what was intended. Therefore, in order for your code to be type safe, you have to check that the type retrieved from the collection really is what was expected. +Second, there's no way to control which types can be added to a collection. It's perfectly legal to add an integer and a string to the same collection, even though it's probably not what was intended. Therefore, in order for your code to be type safe, you have to check that the type retrieved from the collection really is what was expected. The following code example shows the two main drawbacks of the .NET Framework collections before generics. @@ -71,7 +71,7 @@ Popped an int: 7 ## Example: Benefit of using generic collection -The new namespace contains many of the same collections found in the namespace, but they have been modified to accept generic type parameters. This eliminates the two drawbacks of non-generic collections: the boxing and unboxing of value types and the inability to specify the types to be stored in the collections. Operations on the two collections are identical; they differ only in how they are instantiated. +The new namespace contains many of the same collections found in the namespace, but they've been modified to accept generic type parameters. This change eliminates the two drawbacks of non-generic collections: the boxing and unboxing of value types and the inability to specify the types to be stored in the collections. Operations on the two collections are identical; they differ only in how they're instantiated. Compare the example written above with this example that uses a generic collection. On large collections that are frequently accessed, the performance of this example will be significantly greater than the preceding example. @@ -89,8 +89,8 @@ int main() // This Stack can only contain integers. Stack ^s = gcnew Stack(); - // Push an integer to the Stack. - // A boxing operation is performed here. + // Push an integer to the Stack. + // No boxing operation is performed here. s->Push(7); s->Push(14); diff --git a/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md b/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md index 0065f44486a..5caafaeebf6 100644 --- a/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md +++ b/docs/extensions/how-to-overload-functions-with-interior-pointers-and-native-pointers-cpp-cli.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI)" title: "How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI)" -ms.date: "10/12/2018" +description: "Learn more about: How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["Functions with interior and native pointers, overloading"] -ms.assetid: d70df625-4aad-457c-84f5-70a0a290cc1f --- # How to: Overload Functions with Interior Pointers and Native Pointers (C++/CLI) @@ -49,7 +48,7 @@ int main() { G ^pG = gcnew G; // common language runtime heap f( &pS->i ); f( &pG->i ); -}; +} ``` ```Output diff --git a/docs/extensions/interface-class-cpp-component-extensions.md b/docs/extensions/interface-class-cpp-component-extensions.md index 9688279ef0a..d4e614dc8ac 100644 --- a/docs/extensions/interface-class-cpp-component-extensions.md +++ b/docs/extensions/interface-class-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- +title: "interface class (C++/CLI and C++/CX)" description: "Learn more about: interface class (C++/CLI and C++/CX)" -title: "interface class (C++/CLI and C++/CX)" ms.date: 04/15/2022 ms.topic: "reference" f1_keywords: ["interface_CPP", "interface class", "interface class_CPP"] helpviewer_keywords: ["interface class keyword", "interface struct keyword"] -ms.assetid: 3ccea701-f50b-4da7-ad6b-f0ee1203e2b9 --- -# `interface class` (C++/CLI and C++/CX) +# `interface class` (C++/CLI and C++/CX) Declares an interface. For information on native interfaces, see [`__interface`](../cpp/interface.md). diff --git a/docs/extensions/new-new-slot-in-vtable-cpp-component-extensions.md b/docs/extensions/new-new-slot-in-vtable-cpp-component-extensions.md index adba09017e4..4c1932c3068 100644 --- a/docs/extensions/new-new-slot-in-vtable-cpp-component-extensions.md +++ b/docs/extensions/new-new-slot-in-vtable-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: new (new slot in vtable) (C++/CLI and C++/CX)" -title: "new (new slot in vtable) (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "new (new slot in vtable) (C++/CLI and C++/CX)" +description: "Learn more about: new (new slot in vtable) (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["new keyword [C++]"] -ms.assetid: 1a9a5704-f02f-46ae-ad65-f0f2b6dbabc3 --- -# new (new slot in vtable) (C++/CLI and C++/CX) +# new (new slot in vtable) (C++/CLI and C++/CX) The **`new`** keyword indicates that a virtual member will get a new slot in the vtable. diff --git a/docs/extensions/nullptr-cpp-component-extensions.md b/docs/extensions/nullptr-cpp-component-extensions.md index e9972a7c692..e0784388095 100644 --- a/docs/extensions/nullptr-cpp-component-extensions.md +++ b/docs/extensions/nullptr-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: nullptr (C++/CLI and C++/CX)" -title: "nullptr (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "nullptr (C++/CLI and C++/CX)" +description: "Learn more about: nullptr (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["__nullptr keyword (C++)", "nullptr keyword [C++]"] -ms.assetid: 594cfbf7-06cb-4366-9ede-c0b703e1d095 --- -# nullptr (C++/CLI and C++/CX) +# nullptr (C++/CLI and C++/CX) The **`nullptr`** keyword represents a *null pointer value*. Use a null pointer value to indicate that an object handle, interior pointer, or native pointer type does not point to an object. diff --git a/docs/extensions/override-cpp-component-extensions.md b/docs/extensions/override-cpp-component-extensions.md index 5f6305c840c..3dbe034d525 100644 --- a/docs/extensions/override-cpp-component-extensions.md +++ b/docs/extensions/override-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: override (C++/CLI and C++/CX)" -title: "override (C++/CLI and C++/CX)" -ms.date: "11/04/2016" +title: "override (C++/CLI and C++/CX)" +description: "Learn more about: override (C++/CLI and C++/CX)" +ms.date: 11/04/2016 ms.topic: "reference" helpviewer_keywords: ["overriding, override keyword [C++]", "override keyword [C++]"] -ms.assetid: 34d19257-1686-4fcd-96f5-af07c70ba914 --- -# override (C++/CLI and C++/CX) +# override (C++/CLI and C++/CX) The **override** context-sensitive keyword indicates that a member of a type overrides a base class or a base interface member. diff --git a/docs/extensions/override-specifiers-cpp-component-extensions.md b/docs/extensions/override-specifiers-cpp-component-extensions.md index 0534d54ecb9..ea644986a34 100644 --- a/docs/extensions/override-specifiers-cpp-component-extensions.md +++ b/docs/extensions/override-specifiers-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: Override Specifiers (C++/CLI and C++/CX)" -title: "Override Specifiers (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Override Specifiers (C++/CLI and C++/CX)" +description: "Learn more about: Override Specifiers (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["override specifiers, C++", "override specifiers"] -ms.assetid: 155bbf6f-4722-4654-afb1-9cb52af799fb --- -# Override Specifiers (C++/CLI and C++/CX) +# Override Specifiers (C++/CLI and C++/CX) *Override specifiers* modify how inherited types and members of inherited types behave in derived types. diff --git a/docs/extensions/overview-of-generics-in-visual-cpp.md b/docs/extensions/overview-of-generics-in-visual-cpp.md index 108be1e564c..5e0760fcad8 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/partial-cpp-component-extensions.md b/docs/extensions/partial-cpp-component-extensions.md index 90084a64c30..4a133fd0ded 100644 --- a/docs/extensions/partial-cpp-component-extensions.md +++ b/docs/extensions/partial-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: partial (C++/CLI and C++/CX)" -title: "partial (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "partial (C++/CLI and C++/CX)" +description: "Learn more about: partial (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["partial_CPP"] helpviewer_keywords: ["partial", "C++/CX, partial"] -ms.assetid: 43adf1f5-10c5-44aa-a66f-7507e2bdabf8 --- -# partial (C++/CLI and C++/CX) +# partial (C++/CLI and C++/CX) The **partial** keyword enables different parts of the same ref class to be authored independently and in different files. @@ -45,7 +44,7 @@ The name of the defined type. A partial class supports scenarios where you modify one part of a class definition in one file, and automatic code-generating software—for example, the XAML designer—modifies code in the same class in another file. By using a partial class, you can prevent the automatic code generator from overwriting your code. In a Visual Studio project, the **partial** modifier is applied automatically to the generated file. -Contents: With two exceptions, a partial class definition can contain anything that the full class definition could contain if the **partial** keyword was omitted. However, you can't specify class accessibility (for example, `public partial class X { ... };`), or a **declspec**. +Contents: With two exceptions, a partial class definition can contain anything that the full class definition could contain if the **partial** keyword was omitted. However, you can't specify class accessibility (for example, `public partial class X { ... };`), or a **declspec**. Access specifiers used in a partial class definition for *identifier* do not affect the default accessibility in a subsequent partial or full class definition for *identifier*. Inline definitions of static data members are allowed. diff --git a/docs/extensions/pin-ptr-cpp-cli.md b/docs/extensions/pin-ptr-cpp-cli.md index c5c3f29afd2..ea3baddba4c 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/platform-default-and-cli-namespaces-cpp-component-extensions.md b/docs/extensions/platform-default-and-cli-namespaces-cpp-component-extensions.md index 7915908d659..ee36ff73725 100644 --- a/docs/extensions/platform-default-and-cli-namespaces-cpp-component-extensions.md +++ b/docs/extensions/platform-default-and-cli-namespaces-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: Platform, default, and cli Namespaces (C++/CLI and C++/CX)" -title: "Platform, default, and cli Namespaces (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "Platform, default, and cli Namespaces (C++/CLI and C++/CX)" +description: "Learn more about: Platform, default, and cli Namespaces (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["lang", "cli"] helpviewer_keywords: ["lang namespace", "cli namespace"] -ms.assetid: 9d38bd1e-dc78-47d1-a84b-9b4683e52c9c --- -# Platform, default, and cli Namespaces (C++/CLI and C++/CX) +# Platform, default, and cli Namespaces (C++/CLI and C++/CX) A namespace qualifies the names of language elements so the names do not conflict with otherwise identical names elsewhere in the source code. For example, a name collision might prevent the compiler from recognizing [Context-Sensitive Keywords](context-sensitive-keywords-cpp-component-extensions.md). Namespaces are used by the compiler but are not preserved in the compiled assembly. diff --git a/docs/extensions/ref-new-gcnew-cpp-component-extensions.md b/docs/extensions/ref-new-gcnew-cpp-component-extensions.md index c2a9a423422..13c1a6812be 100644 --- a/docs/extensions/ref-new-gcnew-cpp-component-extensions.md +++ b/docs/extensions/ref-new-gcnew-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: ref new, gcnew (C++/CLI and C++/CX)" -title: "ref new, gcnew (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "ref new, gcnew (C++/CLI and C++/CX)" +description: "Learn more about: ref new, gcnew (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["gcnew", "ref new", "gcnew_cpp"] helpviewer_keywords: ["ref new keyword (C++)", "gcnew keyword [C++]"] -ms.assetid: 388a62da-c2df-4a94-a9a2-205b53e577da --- -# ref new, gcnew (C++/CLI and C++/CX) +# ref new, gcnew (C++/CLI and C++/CX) The **ref new** aggregate keyword allocates an instance of a type that is garbage collected when the object becomes inaccessible, and that returns a handle ([^](handle-to-object-operator-hat-cpp-component-extensions.md)) to the allocated object. diff --git a/docs/extensions/safe-cast-cpp-component-extensions.md b/docs/extensions/safe-cast-cpp-component-extensions.md index 1a192940e9b..a35a3a2af94 100644 --- a/docs/extensions/safe-cast-cpp-component-extensions.md +++ b/docs/extensions/safe-cast-cpp-component-extensions.md @@ -5,11 +5,10 @@ ms.date: "10/12/2018" ms.topic: "reference" f1_keywords: ["safe_cast", "safe_cast_cpp", "stdcli::language::safe_cast"] helpviewer_keywords: ["safe_cast keyword [C++]"] -ms.assetid: 4fa688bf-a8ec-49bc-a4c5-f48134efa4f7 --- # safe_cast (C++/CLI and C++/CX) -The **safe_cast** operation returns the specified expression as the specified type, if successful; otherwise, throws `InvalidCastException`. +The **`safe_cast`** operation returns the specified expression as the specified type. If the operation isn't successful, it throws an `InvalidCastException`. ## All Runtimes @@ -23,7 +22,7 @@ The **safe_cast** operation returns the specified expression as the specified ty ## Windows Runtime -**safe_cast** allows you to change the type of a specified expression. In situations where you fully expect a variable or parameter to be convertible to a certain type, you can use **safe_cast** without a **try-catch** block to detect programming errors during development. For more information, see [Casting (C++/CX)](../cppcx/casting-c-cx.md). +Use **`safe_cast`** to change the type of a specified expression. If you expect a variable or parameter to be convertible to a certain type, use **`safe_cast`** without a **try-catch** block to detect programming errors during development. For more information, see [Casting (C++/CX)](../cppcx/casting-c-cx.md). ### Syntax @@ -41,7 +40,7 @@ An expression that evaluates to a handle to a reference or value type, a value t ### Remarks -**safe_cast** throws `InvalidCastException` if it cannot convert *expression* to the type specified by *type-id*. To catch `InvalidCastException`, specify the [/EH (Exception Handling Model)](../build/reference/eh-exception-handling-model.md) compiler option, and use a **try/catch** statement. +**`safe_cast`** throws `InvalidCastException` if it can't convert *expression* to the type specified by *type-id*. To catch `InvalidCastException`, specify the [/EH (Exception Handling Model)](../build/reference/eh-exception-handling-model.md) compiler option, and use a **try/catch** statement. ### Requirements @@ -49,7 +48,7 @@ Compiler option: `/ZW` ### Examples -The following code example demonstrates how to use **safe_cast** with the Windows Runtime. +The following code example demonstrates how to use **`safe_cast`** with the Windows Runtime. ```cpp // safe_cast_ZW.cpp @@ -83,7 +82,7 @@ Caught expected exception: InvalidCastException ## Common Language Runtime -**safe_cast** allows you to change the type of an expression and generate verifiable MSIL code. +**`safe_cast`** changes the type of an expression and generates verifiable MSIL code. ### Syntax @@ -93,30 +92,29 @@ Caught expected exception: InvalidCastException ### Parameters -*type-id*
+*`type-id`*\ A handle to a reference or value type, a value type, or a tracking reference to a reference or value type. -*expression*
+*`expression`* An expression that evaluates to a handle to a reference or value type, a value type, or a tracking reference to a reference or value type. ### Remarks 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 accepts a [`static_cast`](../cpp/static-cast-operator.md) in most places that it accepts a **`safe_cast`**. However, **`safe_cast`** always produces verifiable MSIL, whereas a **`static_cast`** might produce unverifiable MSIL. For more information on verifiable code, 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). -Like **`static_cast`**, **safe_cast** invokes user-defined conversions. +Like **`static_cast`**, **`safe_cast`** invokes user-defined conversions. For more information about casts, see [Casting Operators](../cpp/casting-operators.md). -**safe_cast** does not apply a **`const_cast`** (cast away **`const`**). +**`safe_cast`** doesn't apply a **`const_cast`** (cast away **`const`**). -**safe_cast** is in the cli namespace. See [Platform, default, and cli Namespaces](platform-default-and-cli-namespaces-cpp-component-extensions.md) for more information. +**`safe_cast`** is in the cli namespace. For more information, see [Platform, default, and cli Namespaces](platform-default-and-cli-namespaces-cpp-component-extensions.md). -For more information on **safe_cast**, see: +For more information on **`safe_cast`**, see: - [C-Style Casts with /clr (C++/CLI)](c-style-casts-with-clr-cpp-cli.md) - - [How to: Use safe_cast in C++/CLI](../dotnet/how-to-use-safe-cast-in-cpp-cli.md) ### Requirements @@ -125,7 +123,7 @@ Compiler option: `/clr` ### Examples -One example of where the compiler will not accept a **`static_cast`** but will accept a **safe_cast** is for casts between unrelated interface types. With **safe_cast**, the compiler will not issue a conversion error and will perform a check at runtime to see if the cast is possible +One example of where the compiler doesn't accept a **`static_cast`** but accepts a **`safe_cast`** is for casts between unrelated interface types. With **`safe_cast`**, the compiler doesn't issue a conversion error and performs a check at runtime to see if the cast is possible. ```cpp // safe_cast.cpp diff --git a/docs/extensions/sealed-cpp-component-extensions.md b/docs/extensions/sealed-cpp-component-extensions.md index 1229c6747d0..e44afac2b7d 100644 --- a/docs/extensions/sealed-cpp-component-extensions.md +++ b/docs/extensions/sealed-cpp-component-extensions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: sealed (C++/CLI and C++/CX)" -title: "sealed (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "sealed (C++/CLI and C++/CX)" +description: "Learn more about: sealed (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" f1_keywords: ["sealed_cpp", "sealed"] helpviewer_keywords: ["sealed keyword [C++]"] -ms.assetid: 3d0d688a-41aa-45f5-a25a-65c44206521e --- -# sealed (C++/CLI and C++/CX) +# sealed (C++/CLI and C++/CX) **sealed** is a context-sensitive keyword for ref classes that indicates that a virtual member cannot be overridden, or that a type cannot be used as a base type. diff --git a/docs/extensions/string-cpp-component-extensions.md b/docs/extensions/string-cpp-component-extensions.md index 57a1c3d6380..972ab5c2329 100644 --- a/docs/extensions/string-cpp-component-extensions.md +++ b/docs/extensions/string-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: String (C++/CLI and C++/CX)" -title: "String (C++/CLI and C++/CX)" -ms.date: "10/08/2018" +title: "String (C++/CLI and C++/CX)" +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) +# String (C++/CLI and C++/CX) The Windows Runtime and common language runtime represent strings as objects whose allocated memory is managed automatically. That is, you are not required to explicitly discard the memory for a string when the string variable goes out of scope or your application ends. To indicate that the lifetime of a string object is to be managed automatically, declare the string type with the [handle-to-object (^)](handle-to-object-operator-hat-cpp-component-extensions.md) modifier. @@ -50,7 +49,7 @@ When passed a , the compiler will box, if necessary, and the > [!NOTE] > The caret ("^") indicates that the declared variable is a handle to a C++/CLI managed object. -For more information see [String and Character Literals](../cpp/string-and-character-literals-cpp.md). +For more information, see [String and Character Literals](../cpp/string-and-character-literals-cpp.md). ### Requirements @@ -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/extensions/typeid-cpp-component-extensions.md b/docs/extensions/typeid-cpp-component-extensions.md index 3d8cb2389cd..fe3b1ffcb1e 100644 --- a/docs/extensions/typeid-cpp-component-extensions.md +++ b/docs/extensions/typeid-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: typeid (C++/CLI and C++/CX)" -title: "typeid (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "typeid (C++/CLI and C++/CX)" +description: "Learn more about: typeid (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["typeid keyword [C++]"] -ms.assetid: e9706cae-e7c4-4d6d-b474-646d73df3e70 --- -# typeid (C++/CLI and C++/CX) +# typeid (C++/CLI and C++/CX) Gets a value that indicates the type of an object. @@ -41,7 +40,7 @@ A type name. ### Remarks -In C++/CX, typeid returns a [Platform::Type](../cppcx/platform-type-class.md) that is constructed from runtime type information. +In C++/CX, typeid returns a [Platform::Type](../cppcx/platform-type-class.md) that is constructed from runtime type information. ### Requirements diff --git a/docs/extensions/user-defined-attributes-cpp-component-extensions.md b/docs/extensions/user-defined-attributes-cpp-component-extensions.md index bf6add627c2..f9f9b7c0346 100644 --- a/docs/extensions/user-defined-attributes-cpp-component-extensions.md +++ b/docs/extensions/user-defined-attributes-cpp-component-extensions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: User-Defined Attributes (C++/CLI and C++/CX)" -title: "User-Defined Attributes (C++/CLI and C++/CX)" -ms.date: "10/12/2018" +title: "User-Defined Attributes (C++/CLI and C++/CX)" +description: "Learn more about: User-Defined Attributes (C++/CLI and C++/CX)" +ms.date: 10/12/2018 ms.topic: "reference" helpviewer_keywords: ["metadata, extending", "custom attributes, extending metadata"] -ms.assetid: 98b29048-a3ea-4698-8441-f149cdaec9fb --- -# User-Defined Attributes (C++/CLI and C++/CX) +# User-Defined Attributes (C++/CLI and C++/CX) C++/CLI and C++/CX enable you to create platform-specific attributes that extend the metadata of an interface, class or structure, method, parameter, or enumeration. These attributes are distinct from the [standard C++ attributes](../cpp/attributes.md). diff --git a/docs/get-started/includes/git-source-control.md b/docs/get-started/includes/git-source-control.md index 86a7efc76a0..c1d17bec684 100644 --- a/docs/get-started/includes/git-source-control.md +++ b/docs/get-started/includes/git-source-control.md @@ -20,7 +20,7 @@ To associate your code with Git, you start by creating a new Git repository wher 1. In the **Create a Git repository** dialog box, sign in to GitHub. - :::image type="content" source="../media/vs-2022/git-create-repo.png" alt-text="Screenshot of the Create a Git Repository dialog window where you can sign in to GitHub."::: + :::image type="content" source="../media/vs-2022/git-create-repo.png" alt-text="Screenshot of the Create a Git Repository dialog window where you create a new GitHub repository."::: The repository name auto-populates based on your folder location. By default, your new repository is private, which means you're the only one who can access it. @@ -29,9 +29,9 @@ To associate your code with Git, you start by creating a new Git repository wher 1. Select **Create and Push**. - After you create your repository, you see status details in the status bar. + After you create your repository, status details appear in the status bar. - :::image type="content" source="../media/vs-2022/git-new-private-repo-status-details.png" alt-text="Screenshot of the repo status bar that's below the Solution Explorer pane in Visual Studio."::: + :::image type="content" source="../media/vs-2022/git-new-private-repo-status-details.png" alt-text="Screenshot of the repo status bar located below the Visual Studio Solution Explorer pane, showing the branch name and number of outstanding changes."::: The first icon with the arrows shows how many outgoing/incoming commits are in your current branch. You can use this icon to pull any incoming commits or push any outgoing commits. You can also choose to view these commits first. To do so, select the icon, and then select **View Outgoing/Incoming**. diff --git a/docs/get-started/index.yml b/docs/get-started/index.yml index 092c41ca070..f179d269b5f 100644 --- a/docs/get-started/index.yml +++ b/docs/get-started/index.yml @@ -1,6 +1,6 @@ ### YamlMime:Landing -title: Visual Studio tutorials | C++ +title: Visual Studio tutorials | C++ summary: Create C++ apps with Visual Studio. metadata: @@ -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 00000000000..aabbef891ac 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 00000000000..7ed460ef3c2 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 00000000000..a68503955a6 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 00000000000..ff3accfbe2c 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 00000000000..8782a1404ea 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 00000000000..5a8c1e203d7 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 00000000000..eee553c4187 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 00000000000..3fc57e66265 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 00000000000..bb80014a162 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 00000000000..df4c6b693bf 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 2fc5b19b4eb..733930b8a2a 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 57501b418ca..00000000000 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 037e8d4875f..00000000000 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 99b438d4657..00000000000 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 80036567434..00000000000 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 2e9988c00ef..00000000000 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 1ac14bd8307..00000000000 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 eb7befa4aad..00000000000 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 f1bbd82c34a..b6aac8a07e0 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 7fdca8eeb37..9d56d7808bf 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 2a1cd21703b..16bfc349e1e 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 1df9186a443..00000000000 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 00000000000..6dfdf8199ea 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 00000000000..b4c5e574a53 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 00000000000..0d25a762f8b 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 00000000000..79eeff423aa 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 00000000000..6b034ba9712 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 00000000000..c96f8008f1f 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 00000000000..3266b4b4e21 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 00000000000..2e16e63a35d 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 f37534789a8..b807d690bae 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 00000000000..b90dd134580 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 3f0d8778eaf..00000000000 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 ec477879fb0..00000000000 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 028f3a22ac3..00000000000 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 5a3f002d42d..00000000000 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 50f1c18dc98..00000000000 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 8b1e09fda5d..da42b04840f 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 49c8588febb..00000000000 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 54ffdcd7113..00000000000 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 00000000000..43c8547c948 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 4d8f0ffde73..885c023879c 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 40b3e63569d..5f804bb016b 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 9e430ec801e..00000000000 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 b3c43caaa16..03890a10657 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 459dee0c1db..00000000000 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 fb2686bdc9c..00000000000 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 d736a4217d5..00000000000 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 bb7db5c40fc..00000000000 Binary files a/docs/get-started/media/calculator-undefined-zero.gif and /dev/null differ diff --git a/docs/get-started/toc.yml b/docs/get-started/toc.yml index 224ea3f49a3..32d38ad40ef 100644 --- a/docs/get-started/toc.yml +++ b/docs/get-started/toc.yml @@ -1,11 +1,13 @@ items: -- name: Get started with Visual C++ +- name: Get started with Microsoft C++ expanded: true items: - name: Install C++ support in Visual Studio href: ../build/vscpp-step-0-installation.md - name: Visual Studio guided tour href: /visualstudio/get-started/visual-studio-ide + - name: Use AI to create a C++ console application in Visual Studio + href: ../build/use-github-copilot-create-cpp-console-app.md - name: Create and edit a C++ console app project href: ../build/vscpp-step-1-create.md - name: Build and run a C++ console app project @@ -25,7 +27,7 @@ items: items: - name: Create a console app href: tutorial-console-cpp.md - - name: Create a Universal Windows Platform app + - name: Create a Universal Windows Platform app href: /windows/uwp/cpp-and-winrt-apis/get-started - name: Create a Windows Desktop app href: /windows/desktop/learnwin32/learn-to-program-for-windows @@ -44,9 +46,9 @@ items: items: - name: Open code from a repo href: /visualstudio/get-started/tutorial-open-project-from-repo - - name: Write and edit code + - name: Write and edit code href: /visualstudio/get-started/tutorial-editor - - name: Compile and build + - name: Compile and build href: /visualstudio/ide/compiling-and-building-in-visual-studio - name: Debug your C++ code href: /visualstudio/debugger/quickstart-debug-with-cplusplus diff --git a/docs/get-started/tutorial-console-cpp.md b/docs/get-started/tutorial-console-cpp.md index 0383f331c2e..608ab706e06 100644 --- a/docs/get-started/tutorial-console-cpp.md +++ b/docs/get-started/tutorial-console-cpp.md @@ -1,44 +1,46 @@ --- title: "Create a console calculator in C++" -description: "Create a Hello World console app and a calculator app in Visual C++" +description: "Create a Hello World console app and a calculator app in Visual Studio C++" ms.custom: "acquisition, mvc" -ms.date: 08/31/2021 +ms.date: 10/08/2024 ms.topic: "tutorial" ms.devlang: "cpp" -ms.assetid: 45138d70-719d-42dc-90d7-1d0ca31a2f54 --- # Create a console calculator in C++ ::: moniker range=">=msvc-160" -The usual starting point for a C++ programmer is a "Hello, world!" application that runs on the command line. That's what you'll create first in Visual Studio in this article, and then we'll move on to something more challenging: a calculator app. +The usual starting point for a C++ programmer is a "Hello, world!" application that runs on the command line. You start with that in this article, and then move on to something more challenging: a calculator app. ## Prerequisites -- Have Visual Studio with the **Desktop development with C++** workload installed and running on your computer. If it's not installed yet, see [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md). +- Visual Studio with the **Desktop development with C++** workload installed and running on your computer. To install it, see [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md). +- This tutorial demonstrates a feature called edit and continue which allows you to make changes to your code while the app is running. To enable edit and continue, from the main menu select **Tools** > **Options** > **Debugging** > **General** and ensure that **Require source files to exactly match the original version** is checked. ## Create your app project -Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize your projects. A project contains all the options, configurations, and rules used to build your apps. It also manages the relationship between all the project's files and any external files. To create your app, first, you'll create a new project and solution. +Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize one or more projects. A project contains all the options, configurations, and rules used to build an app. It also manages the relationship between all the project's files and any external files. To create your app, first, create a new project and solution. -1. If you've just started Visual Studio, you'll see the Visual Studio Start dialog box. Choose **Create a new project** to get started. +1. Start Visual Studio--the Visual Studio Start dialog box appears. Select **Create a new project** to get started. - ![Screenshot of the Visual Studio 2022 initial dialog.](./media/calc-vs2022-initial-dialog.png) + :::image type="complex" source="./media/calc-vs2022-initial-dialog.png" alt-text="Screenshot of dialog that appears when Visual Studio 2022 starts."::: + The dialog has options to clone a repository, open a project or solution, open a local folder, and create a new project." + :::image-end::: - Otherwise, on the menubar in Visual Studio, choose **File** > **New** > **Project**. The **Create a new project** window opens. +1. In the **Create a new project** dialog, set the language dropdown to **C++**, set the platform dropdown to **Windows**, select **Console App** from the list of project types, then select **Next**. -1. In the list of project templates, choose **Console App**, then choose **Next**. - - ![Screenshot of choosing the Console App template.](./media/calc-vs2019-choose-console-app.png "Choose the Console App template") + :::image type="complex" source="./media/calc-vs2022-choose-console-app.png" alt-text="Screenshot of the Visual Studio Create a new project dialog."::: + The language dropdown is set to C++, the platform dropdown is set to Windows, and project types like Empty Project, Console App, CMake Project, Windows Desktop Wizard, and so on, appear in the list of project types." + :::image-end::: > [!Important] - > Make sure you choose the C++ version of the **Console App** template. It has the **C++**, **Windows**, and **Console** tags, and the icon has "++" in the corner. + > Make sure you select the C++ version of the **Console App** template. It has the **C++**, **Windows**, and **Console** tags, and the icon has "++" in the corner. -1. In the **Configure your new project** dialog box, select the **Project name** edit box, name your new project *CalculatorTutorial*, then choose **Create**. +1. In the **Configure your new project** dialog box, select the **Project name** text box, name your new project *CalculatorTutorial*, then select **Create**. - ![Name your project in the Configure your new project dialog.](./media/calc-vs2019-name-your-project.png "Name your project in the Configure your new project dialog") + :::image type="content" source="./media/calc-vs2019-name-your-project.png" alt-text="Screenshot of the Visual Studio Configure your new project dialog. It has fields for project name, project location, and Solution name."::: - An empty C++ Windows console application gets created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: + An empty C++ Windows console application 'Hello World' app is created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -67,25 +69,29 @@ Visual Studio uses *projects* to organize the code for an app, and *solutions* t The template for a new Windows console application creates a simple C++ "Hello World" app. At this point, you can see how Visual Studio builds and runs the apps you create right from the IDE. -1. To build your project, choose **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. +1. To build your project, select **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. + + :::image type="content" source="./media/calc-vs2019-build-your-project.png" alt-text="Screenshot of the Visual Studio Output window. It's displaying a message that the build succeeded."::: + +1. To run the code, on the menu bar, select **Debug** > **Start without debugging** (Ctrl+F5). - ![Screenshot of Visual Studio 2019 with the Output window showing the result of the build process.](./media/calc-vs2019-build-your-project.png "Build the project") + :::image type="content" source="./media/calc-vs2019-hello-world-console.png" alt-text="Screenshot of the Visual Studio Debug Console displaying the output of the application: Hello World!"::: -1. To run the code, on the menu bar, choose **Debug**, **Start without debugging**. + A console window opens and your app runs within it. - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the code ran successfully.](./media/calc-vs2019-hello-world-console.png "Start the project") + When you start a console app in Visual Studio, it runs your code, then prints "Press any key to close this window . . ." to give you a chance to see the output. - A console window opens and then runs your app. When you start a console app in Visual Studio, it runs your code, then prints "Press any key to close this window . . ." to give you a chance to see the output. Congratulations! You've created your first "Hello, world!" console app in Visual Studio! + Congratulations! You created your first "Hello, world!" console app in Visual Studio! 1. Press a key to dismiss the console window and return to Visual Studio. -You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we'll show you how to debug it if it doesn't. +You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we show you how to debug it if it doesn't. ## Edit the code -Now let's turn the code in this template into a calculator app. +Now let's modify the code in this template to be a calculator app. -1. In the *CalculatorTutorial.cpp* file, edit the code to match this example: +1. Replace the contents of the *`CalculatorTutorial.cpp`* file with the following code so that it matches this example: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -116,35 +122,41 @@ Now let's turn the code in this template into a calculator app. > Understanding the code: > - > - The `#include` statements allow you to reference code located in other files. Sometimes, you may see a filename surrounded by angle brackets (**\<\>**); other times, it's surrounded by quotes (**" "**). In general, angle brackets are used when referencing the C++ Standard Library, while quotes are used for other files. - > - The `using namespace std;` line tells the compiler to expect stuff from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with a `std::`, to denote its scope. For instance, without that line, each reference to `cout` would have to be written as `std::cout`. The **`using`** statement is added to make the code look more clean. - > - The `cout` keyword is used to print to standard output in C++. The **\<\<** operator tells the compiler to send whatever is to the right of it to the standard output. - > - The **endl** keyword is like the Enter key; it ends the line and moves the cursor to the next line. It is a better practice to put a `\n` inside the string (contained by "") to do the same thing, as `endl` always flushes the buffer and can hurt the performance of the program, but since this is a very small app, `endl` is used instead for better readability. + > - The `#include` statement brings in code in other files. Sometimes, you may see a filename surrounded by angle brackets like ``. The angle brackets instruct the compiler to look for the `iostream` header file first in the standard system directories, and if not found, to look in directories specific to the project. Other times, you may see a filename surrounded by quotes like `"someHeader.h"`. The quotes instruct the compiler to skip looking in the standard system directories and instead only look in directories specific to the project. + > - The `using namespace std;` tells the compiler to expect code from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with `std::` to denote its scope. For instance, without that line, each reference to `cout` would be written as `std::cout`. The **`using`** statement is added to make it more convenient to access code in another namespace. + > - The `cout` keyword is used to print to standard output in C++. The `<<` operator tells the compiler to send whatever is to the right of it to the standard output. + > - The `endl` keyword is like the Enter key; it ends the line and moves the cursor to the next line. It's a better practice to put a `\n` inside the string (contained by `""`) to do the same thing because `endl` always flushes the buffer which can hurt the performance of the program. But since this is a very small app, `endl` is used instead. > - All C++ statements must end with semicolons and all C++ applications must contain a `main()` function. This function is what the program runs at the start. All code must be accessible from `main()` in order to be used. -1. To save the file, enter **Ctrl+S**, or choose the **Save** icon near the top of the IDE, the floppy disk icon in the toolbar under the menu bar. +1. To save the file, press **Ctrl+S**, or select the floppy disk icon in the toolbar under the menu bar. -1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and choose **Start Without Debugging**. You should see a console window appear that displays the text specified in the code. +1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and select **Start Without Debugging**. You should see a console window appear that looks like this. 1. Close the console window when you're done. ## Add code to do some math -It's time to add some math logic. +A class is like a blueprint for an object that does something. In this case, we define a calculator class to contain the math logic. -### To add a Calculator class +### Add a Calculator class -1. Go to the **Project** menu and choose **Add Class**. In the **Class Name** edit box, enter *Calculator*. Choose **OK**. Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss any files when you save. +1. Go to the **Project** menu and select **Add Class**. In the **Class Name** edit box, enter *Calculator*. Select **OK**. - ![Screenshot of the Add Class dialog box with Calculator typed in the Class Name text box.](./media/calc-vs2019-create-calculator-class.png "Create the Calculator class") + :::image type="complex" source="./media/calc-vs2022-create-calculator-class.png" alt-text="Screenshot of the Visual Studio Add Class dialog box."::: + The class name field contains the text calculator. The .h file field contains Calculator.h. The .cpp file field contains Calculator.cpp. The base class field is empty. The options for inline, and Managed are unchecked. + :::image-end::: - A class is like a blueprint for an object that does something. In this case, we define a calculator and how it should work. The **Add Class** wizard you used above created .h and .cpp files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the window isn't visible, you can open it from the menu bar: choose **View** > **Solution Explorer**. + Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss saving any changes. - ![Screenshot of the Visual Studio 2019 Solution Explorer window displaying the Calculator Tutorial project.](./media/calc-vs2019-solution-explorer.png "Solution Explorer") + The **Add Class** wizard creates `.h` and `.cpp` files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the window isn't visible, open it from the menu bar via **View** > **Solution Explorer**. - You should now have three tabs open in the editor: *CalculatorTutorial.cpp*, *Calculator.h*, and *Calculator.cpp*. If you accidentally close one of them, you can reopen it by double-clicking it in the **Solution Explorer** window. + :::image type="complex" source="./media/calc-vs2019-solution-explorer.png" alt-text="Screenshot of the Visual Studio Solution Explorer window."::: + The calculator tutorial project has a header files node containing Calculator.h. A Source Files node contains Calculator.cpp and CalculatorTutorial.cpp. Nodes for references, external dependencies, and resource files are visible but closed. + :::image-end::: -1. In **Calculator.h**, remove the `Calculator();` and `~Calculator();` lines that were generated, since you won't need them here. Next, add the following line of code so the file now looks like this: + You can open a file by double-clicking it in the **Solution Explorer** window. Double-click `Calculator.h` to open it. + +1. Replace the contents of **`Calculator.h`** with the following code so that the file now looks like this: ```cpp #pragma once @@ -157,26 +169,25 @@ It's time to add some math logic. > Understanding the code > - > - The line you added declares a new function called `Calculate`, which we'll use to run math operations for addition, subtraction, multiplication, and division. - > - C++ code is organized into *header* (.h) files and *source* (.cpp) files. Several other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where 'filename.h' is the name of the file that declares the variables or functions you want to use. - > - The two lines you deleted declared a *constructor* and *destructor* for the class. For a simple class like this one, the compiler creates them for you, and their uses are beyond the scope of this tutorial. + > - This code declares a new function called `Calculate`, which handles math operations for addition, subtraction, multiplication, and division. + > - C++ code is organized into *header* (`.h`) files and *source* (`.cpp`) files. Some other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where `filename.h` is the name of the file that declares the variables or functions you want to use. > - It's good practice to organize your code into different files based on what it does, so it's easy to find the code you need later. In our case, we define the `Calculator` class separately from the file containing the `main()` function, but we plan to reference the `Calculator` class in `main()`. -1. You'll see a green squiggle appear under `Calculate`. It's because we haven't defined the `Calculate` function in the .cpp file. Hover over the word, click the lightbulb (in this case, a screwdriver) that pops up, and choose **Create definition of 'Calculate' in Calculator.cpp**. +1. A green squiggle appears under `Calculate` because although the `Calculate` function is *declared*, it isn't *defined*. Hover over `Calculate`, click the down arrow on the screwdriver icon, and select **Create definition of 'Calculate' in `Calculator.cpp`**. - ![Screenshot of Visual Studio 2019 showing the Create definition of Calculate in Calculator C P P option highlighted.](./media/calc-vs2019-create-definition.png "Create definition of Calculate") + :::image type="content" source="./media/calc-vs2022-create-definition.png" alt-text="Screenshot of a screwdriver dropdown in the Visual Studio editor window. The option 'Create definition of Calculate in Calculator.cpp' is highlighted."::: - A pop-up appears that gives you a peek of the code change that was made in the other file. The code was added to *Calculator.cpp*. + This code is added to *`Calculator.cpp`*: - ![Pop-up with definition of Calculate.](./media/calc-vs2019-pop-up-definition.png "Pop-up with definition of Calculate") + :::image type="complex" source="./media/calc-vs2022-ctor-definition.png" alt-text="Screenshot of the Visual Studio editor showing the definition of the 'Calculate' function."::: + The definition of the function is: double Calculator::Calculate( double x, char oper, double y) { return 0.0; } + :::image-end::: - Currently, it just returns 0.0. Let's change that. Press **Esc** to close the pop-up. + Currently, it just returns 0.0. Let's change that. -1. Switch to the *Calculator.cpp* file in the editor window. Remove the `Calculator()` and `~Calculator()` sections (as you did in the .h file) and add the following code to `Calculate()`: +1. Switch to the *`Calculator.cpp`* file in the editor window. Replace the contents of *`Calculator::Calculate(double x, char oper, double y)`* with: ```cpp - #include "Calculator.h" - double Calculator::Calculate(double x, char oper, double y) { switch(oper) @@ -197,16 +208,16 @@ It's time to add some math logic. > Understanding the code > - > - The function `Calculate` consumes a number, an operator, and a second number, then performs the requested operation on the numbers. - > - The switch statement checks which operator was provided, and only executes the case corresponding to that operation. The default: case is a fallback in case the user types an operator that isn't accepted, so the program doesn't break. In general, it's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. - > - The **`double`** keyword denotes a type of number that supports decimals. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return such a number due to the **`double`** at the very start of the code (this denotes the function's return type), which is why we return 0.0 even in the default case. - > - The .h file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The .cpp file has all the implementation details of the function. + > - The function `Calculate` takes a number, an operator, and a second number. Then it performs the requested operation on the two numbers. + > - The `switch` statement checks which operator was provided, and executes the case corresponding to that operation. The `default:` case is a fallback in case the user types an operator that isn't handled by any of the preceding `case` statements. It's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. + > - The **`double`** keyword denotes a type of number that supports decimals. This type of number is called a floating-point number, and `double` means a floating point number that has extra precision. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return a double-precision floating point number due to the **`double`** at the start of the code (this denotes the function's return type), which is why we return 0.0 in the default case. + > - The `.h` file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The `.cpp` file has all the implementation details of the function. -If you build and run the code again at this point, it will still exit after asking which operation to perform. Next, you'll modify the `main` function to do some calculations. +If you build and run the code again at this point, it immediately exits after asking which operation to perform. So, modify the `main` function to do multiple calculations. -### To call the Calculator class member functions +### Call the `Calculator` class member functions -1. Now let's update the `main` function in *CalculatorTutorial.cpp*: +1. Update the `main` function in *`CalculatorTutorial.cpp`* as follows: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -233,7 +244,7 @@ If you build and run the code again at this point, it will still exit after aski { cin >> x >> oper >> y; result = c.Calculate(x, oper, y); - cout << "Result is: " << result << endl; + cout << "Result " << "of " << x << oper << y << " is: " << result << endl; } return 0; @@ -242,75 +253,95 @@ If you build and run the code again at this point, it will still exit after aski > Understanding the code > - > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so a `#include` statement is needed. - > - Some initial variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It is always good practice to give them some initial values to avoid undefined behavior, which is what is done here. - > - The `Calculator c;` line declares an object named 'c' as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. - > - The `while (true)` statement is a loop. The code inside the loop continues to execute over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. - > - The `cin` keyword is used to accept input from the user. This input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order, assuming the user input matches the required specification. You can modify this line to accept different types of input, for instance, more than two numbers, though the `Calculate()` function would also need to be updated to handle this. - > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values. The function then returns a number that gets stored in `result`. - > - Finally, `result` is printed to the console, so the user sees the result of the calculation. + > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so an `#include` statement is needed to make that code visible to our `main()` function. + > - The variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It's always good practice to give them some initial values to avoid undefined behavior, which is what is done here. + > - The `Calculator c;` line declares an object named `c` as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. + > - The `while (true)` statement is a loop. The code inside the loop executes over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. + > - The `cin` keyword accepts input from the user. The input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order. + > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values and the requested operation. The function then returns a number that is stored in `result`. + > - Finally, `result` is printed to the console and the user sees the result of the calculation. ### Build and test the code again -Now it's time to test the program again to make sure everything works properly. +Now test the program again to make sure everything works properly. 1. Press **Ctrl+F5** to rebuild and start the app. +1. Enter `5+5`, and press **Enter**. Verify that the result is 10. -1. Enter `5 + 5`, and press **Enter**. Verify that the result is 10. - - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the correct result of 5 + 5.](./media/calc-vs2019-five-plus-five.png "The result of 5 + 5") + :::image type="complex" source="./media/calc-vs2019-five-plus-five.png" alt-text="Screenshot of a command window showing the results of running the program."::: + The app output the message: Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The user entered 5+5. The app output: Result of 5+5 is: 10 + :::image-end::: +1. Stop the program by closing the console window. ## Debug the app -Since the user is free to type anything into the console window, let's make sure the calculator handles some input as expected. Instead of running the program, let's debug it instead, so we can inspect what it's doing in detail, step-by-step. +Since the user is free to type anything into the console window, let's make sure the calculator handles unexpected input. Instead of running the program, let's debug it so we can inspect what it's doing step-by-step. -### To run the app in the debugger +### Run the app in the debugger -1. Set a breakpoint on the `result = c.Calculate(x, oper, y);` line, just after the user was asked for input. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window. A red dot appears. +1. In `CalcuatorTutorial.cpp`, set a breakpoint on the line: `result = c.Calculate(x, oper, y);`. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window so that a red dot appears. - ![Screenshot of Visual Studio 2019 showing the red dot that represents a breakpoint.](./media/calc-vs2019-set-breakpoint.png "Set a breakpoint") + :::image type="content" source="./media/calc-vs2022-set-breakpoint.png" alt-text="Screenshot of the Visual Studio editor. A red dot representing a breakpoint appears on the line: result = c.Calculate(x, oper, y)."::: - Now when we debug the program, it always pauses execution at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time, let's make the breakpoint conditional. + Now when we debug the program, execution pauses at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time we call `Calculate()`, let's make the breakpoint conditional. -1. Right-click the red dot that represents the breakpoint, and choose **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Choose the **Close** button when you're done. The condition is saved automatically. +1. Right-click the red dot that represents the breakpoint, and select **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Select the **Close** button to save the breakpoint condition. - ![Screenshot of Visual Studio 2019 showing the Breakpoint Settings section and a condition added to the Is true value.](./media/calc-vs2019-conditional-breakpoint.png "Set a conditional breakpoint") + :::image type="complex" source="./media/calc-vs2022-conditional-breakpoint.png" alt-text="Screenshot of a set breakpoint"::: + The breakpoint is on the line: result = c dot Calculate ( x, oper, y). 'Conditions...' The Condition option is checked. The Conditions dropdown is set to "Conditional Expression". The condition dropdown is set to "Is true". The condition is set to y == 0 && oper == '/'. + :::image-end::: - Now we pause execution at the breakpoint specifically if a division by 0 is attempted. + Now, execution pauses at the breakpoint when the app tries to divide by 0. -1. To debug the program, press **F5**, or choose the **Local Windows Debugger** toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can even put any number of spaces between the operator and numbers: `cin` is smart enough to parse the input appropriately. +1. To debug the program, press **F5**, or select the **Local Windows Debugger** debugger toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can put any number of spaces between the operator and numbers: `cin` is smart enough to parse the input appropriately. - ![Screenshot of Visual Studios 2019 showing that the program paused at the conditional breakpoint.](./media/calc-vs2019-debug-breakpoint.png "Pause at the conditional breakpoint") + :::image type="content" source="./media/calc-vs2022-debug-breakpoint.png" alt-text="Screenshot of Visual Studio editor. Program execution halted at the conditional breakpoint on the line: result = c.Calculate(x, oper, y);."::: ### Useful windows in the debugger -Whenever you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. To see all of the variables from that function, switch to the **Locals** window. You can actually modify the values of these variables while debugging, to see what effect they would have on the program. In this case, we'll leave them alone. +When you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. If you don't see the **Autos** window, from the main menu select **Debug** > **Windows** > **Autos**. - ![Screenshot of the Locals window in Visual Studio 2019.](./media/calc-vs2019-debug-locals.png "The Locals window") + :::image type="complex" source="./media/calc-vs2022-autos.png" alt-text="Screenshot of the Visual Studio debugger Autos window."::: + The value of oper is 47 '/', result is 5, x is 10, and y is 0. + :::image-end::: -You can also just hover over variables in the code itself to see their current values where the execution is currently paused. Make sure the editor window is in focus by clicking on it first. +To see all of the variables from that function, switch to the **Locals** window. Because this is a small function, the Autos and Locals window show the same variables. But you can modify the values of these variables in the Locals window while debugging to see what effect they would have on the program. In this case, we leave them alone. Open the **Locals** window by selecting **Locals** at the bottom of the **Autos** window, or by selecting from the main menu **Debug** > **Windows** > **Locals**. - ![Screenshot of Visual Studio 2019 showing the tooltip that appears displaying the value of the variable.](./media/calc-vs2019-hover-tooltip.png "Hover to view current variable values") + :::image type="complex" source="./media/calc-vs2019-debug-locals.png" alt-text="Screenshot of the Locals window in Visual Studio, displaying the current values of local variables while debugging."::: + The value of oper is 47 '/', result is 0, x is 10, and y is 0. + :::image-end::: -### To continue debugging +You can also hover over variables in the code to see their current values at the point where execution is currently paused. Make sure the editor window is in focus by clicking on it first. -1. The yellow line on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function. You'll find yourself in the body of the `Calculate` function. Be careful with **Step Into**; if you do it too much, you may waste a lot of time. It goes into any code you use on the line you are on, including standard library functions. + :::image type="content" source="./media/calc-vs2019-hover-tooltip.png" alt-text="Screenshot of a tooltip showing the value of the variable 'oper', which is 47 or '/'."::: -1. Now that the point of execution is at the start of the `Calculate` function, press **F10** to move to the next line in the program's execution. **F10** is also known as **Step Over**. You can use **Step Over** to move from line to line, without delving into the details of what is occurring in each part of the line. In general you should use **Step Over** instead of **Step Into**, unless you want to dive more deeply into code that is being called from elsewhere (as you did to reach the body of `Calculate`). +### Continue debugging + +1. The yellow arrow on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function. Now you're executing code in the body of the `Calculate` function. Be careful with **Step Into** because it steps into any functions on the line you're on, including standard library functions. It's fine to step into the standard library, but you may be more interested in focusing on your code instead of library code. + +1. Now that the point of execution is at the start of the `Calculate` function, press **F10** to move to the next line in the program's execution. **F10** is also known as **Step Over**. You can use **Step Over** to move from line to line, without delving into the details of what is occurring in each part of the line. In general, you should use **Step Over** instead of **Step Into** unless you want to dive more deeply into code that is being called from elsewhere (as you did to reach the body of `Calculate`). 1. Continue using **F10** to **Step Over** each line until you get back to the `main()` function in the other file, and stop on the `cout` line. - It looks like the program is doing what is expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. You'll see its value is listed as "inf", which doesn't look right, so let's fix it. The `cout` line just outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: + The program is doing what's expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. Its value is `inf`, which doesn't look right. + + :::image type="complex" source="./media/calc-vs2022-debug-inf.png" alt-text="Screenshot of debugging the calculator."::: + The current statement in the debugger is cout << "Result is: " << result << endl; In the autos window, result is inf. + :::image-end::: - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the result of dividing by zero.](./media/calc-vs2019-divide-by-zero-fail.png "The result of divide by zero") + Let's fix it. The `cout` line outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: - This result happens because division by zero is undefined, so the program doesn't have a numerical answer to the requested operation. + :::image type="complex" source="./media/calc-divide-by-zero-fail.png" alt-text="Screenshot of the Visual Studio Debug Console displaying the result of a division by zero operation."::: + The app outputs: Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The user entered 5-0. The app output: Result is: 5. The user entered 10/0. The app output: Result is: inf + :::image-end::: -### To fix the "divide by zero" error + This result is because division by zero is undefined, so the program doesn't have a numerical answer for the requested operation. -Let's handle division by zero more gracefully, so a user can understand the problem. +### Fix the "divide by zero" error -1. Make the following changes in *CalculatorTutorial.cpp*. (You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**): +Let's handle division by zero more gracefully so that it's easier for the user to understand the problem. + +1. Make the following changes in *`CalculatorTutorial.cpp`*. You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**. Add an `if` statement following `cin >> x >> oper >> y;` to check for division by zero and output a message to the user if it happens. Otherwise, the result is printed. ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. @@ -334,46 +365,50 @@ Let's handle division by zero more gracefully, so a user can understand the prob Calculator c; while (true) { - cin >> x >> oper >> y; + cin >> x >> oper >> y; if (oper == '/' && y == 0) { - cout << "Division by 0 exception" << endl; + cout << "Math error: Attempted to divide by zero!" << endl; continue; } else { result = c.Calculate(x, oper, y); } - cout << "Result is: " << result << endl; + cout << "Result " << "of " << x << oper << y << " is: " << result << endl; } return 0; } ``` -1. Now press **F5** once. Program execution continues all the way until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. +1. Press **F5** once. Program execution continues until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. - ![Screenshot of the Visual Studio 2019 Microsoft Visual Studio Debug Console showing the final result after changes.](./media/calc-vs2019-final-verification.png "The final result after changes") + :::image type="complex" source="./media/calc-final-verification.png" alt-text="Screenshot of a console window showing the final output after implementing changes to handle division by zero."::: + The console window displays two lines: 10 / 0 Result is: inf, followed by, 10 / 0 Math error: Attempted to divide by zero. + :::image-end::: > [!Note] - > When you edit code while in debugging mode, there is a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger pops up a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, you'll need to step out of the function, then back into it again to get the updated code. If that doesn't work for some reason and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > When you edit code while in debugging mode, there's a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger displays a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, you need to step out of the function, then back into it again to get the updated code. If that doesn't work and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > + > Another reason edit and continue may fail is if you see a message that says "The Require source files to exactly match the original version setting under Debug->Options->General needs to be enabled..." To fix this, from the main menu select **Tools** > **Options** > **Debugging** > **General** and ensure that **Require source files to exactly match the original version** is checked. > Understanding the Run and Debug shortcuts > - > - **F5** (or **Debug** > **Start Debugging**) starts a debugging session if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If you have something like a "Hello World" program to run, use **Ctrl+F5** or set a breakpoint before you enter **F5** to keep the window open. - > - **Ctrl+F5** (or **Debug** > **Start Without Debugging**) runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. - > - **F10** (known as **Step Over**) lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. - > - **F11** (known as **Step Into**) works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. + > - **F5**, or **Debug** > **Start Debugging**, starts a debugging session, if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If your program outputs to the console, use **Ctrl+F5** or set a breakpoint before you press **F5** to keep the window open. + > - **Ctrl+F5**, or **Debug** > **Start Without Debugging**, runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. + > - **F10**, known as **Step Over**, lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. + > - **F11**, known as **Step Into**, works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. ### Close the app -- If it's still running, close the console window for the calculator app. +- If it's still running, close the console window to stop the calculator app. [!INCLUDE[includes/git-source-control.md](includes/git-source-control.md)] ## The finished app -Congratulations! You've completed the code for the calculator app, built and debugged it, and added it to a repo, all in Visual Studio. +Congratulations! You completed the code for the calculator app, built and debugged it, and added it to a repo, all in Visual Studio. ## Next steps @@ -383,31 +418,30 @@ Congratulations! You've completed the code for the calculator app, built and deb ::: moniker range=" **New** > **Project**. The **New Project** window opens. +Visual Studio uses *projects* to organize the code for an app, and *solutions* to organize one or more projects. A project contains all the options, configurations, and rules used to build an app. It also manages the relationship between all the project's files and any external files. To create your app, first, create a new project and solution. -2. On the left sidebar, make sure **Visual C++** is selected. In the center, choose **Windows Console Application**. +1. On the menubar in Visual Studio, select **File** > **New** > **Project**. The **New Project** window opens. +2. On the left sidebar, ensure that **Visual C++** is selected. In the center, select **Console App**. +3. In the **Name** textbox at the bottom, name the new project *CalculatorTutorial*, then select **OK**. -3. In the **Name** edit box at the bottom, name the new project *CalculatorTutorial*, then choose **OK**. + :::image type="complex" source="./media/calc-vs2017-new-project-dialog.png" alt-text="Screenshot of the New Project dialog."::: + On the left, Other Languages > Visual C++ is selected. In the center, the Console App project type is selected. The Name text box contains CalculatorTutorial. + :::image-end::: - ![The New Project dialog.](./media/calculator-new-project-dialog.png "The New Project dialog") - - An empty C++ Windows console application gets created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: + An empty C++ Windows console application 'Hello World' app is created. Console applications use a Windows console window to display output and accept user input. In Visual Studio, an editor window opens and shows the generated code: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include int main() @@ -431,31 +465,34 @@ Visual Studio uses *projects* to organize the code for an app, and *solutions* t The template for a new windows console application creates a simple C++ "Hello World" app. At this point, you can see how Visual Studio builds and runs the apps you create right from the IDE. -1. To build your project, choose **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. +1. To build your project, select **Build Solution** from the **Build** menu. The **Output** window shows the results of the build process. + + :::image type="content" source="./media/calculator-initial-build-output.png" alt-text="Screenshot of the Visual Studio Output window showing that the build was successful."::: + +1. To run the code, on the menu bar, select **Debug**, **Start without debugging** (Ctrl+F5). - ![Screenshot Visual Studio with the Output window showing the result of the build process.](./media/calculator-initial-build-output.png "Build the project") + :::image type="content" source="./media/calculator-hello-world-console.png" alt-text="Screenshot of the Visual Studio Debug Console showing the output: Hello World!"::: -1. To run the code, on the menu bar, choose **Debug**, **Start without debugging**. + A console window opens and your app runs within it. - ![Screenshot of the Microsoft Visual Studio Debug Console showing the code ran successfully.](./media/calculator-hello-world-console.png "Start the project") + When you start a console app in Visual Studio, it runs your code, then prints `Press any key to close this window . . .` to give you a chance to see the output. - A console window opens and then runs your app. When you start a console app in Visual Studio, it runs your code, then prints "Press any key to continue . . ." to give you a chance to see the output. Congratulations! You've created your first "Hello, world!" console app in Visual Studio! + Congratulations! You created your first "Hello, world!" console app in Visual Studio! 1. Press a key to dismiss the console window and return to Visual Studio. -You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we'll show you how to debug it if it doesn't. +You now have the tools to build and run your app after every change, to verify that the code still works as you expect. Later, we show you how to debug it if it doesn't. ## Edit the code -Now let's turn the code in this template into a calculator app. +Now let's turn the code in this template to be a calculator app. -1. In the *CalculatorTutorial.cpp* file, edit the code to match this example: +1. Replace the contents of the *`CalculatorTutorial.cpp`* file with the following code so that it matches this example: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include using namespace std; @@ -463,8 +500,7 @@ Now let's turn the code in this template into a calculator app. int main() { cout << "Calculator Console Application" << endl << endl; - cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" - << endl; + cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" << endl; return 0; } @@ -481,38 +517,47 @@ Now let's turn the code in this template into a calculator app. > Understanding the code: > - > - The `#include` statements allow you to reference code located in other files. Sometimes, you may see a filename surrounded by angle brackets (**\<\>**); other times, it's surrounded by quotes (**" "**). In general, angle brackets are used when referencing the C++ Standard Library, while quotes are used for other files. - > - The `#include "pch.h"` (or in Visual Studio 2017 and earlier, `#include "stdafx.h"`) line references something known as a precompiled header. These are often used by professional programmers to improve compilation times, but they are beyond the scope of this tutorial. - > - The `using namespace std;` line tells the compiler to expect stuff from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with a `std::`, to denote its scope. For instance, without that line, each reference to `cout` would have to be written as `std::cout`. The **`using`** statement is added to make the code look more clean. - > - The `cout` keyword is used to print to standard output in C++. The **\<\<** operator tells the compiler to send whatever is to the right of it to the standard output. - > - The **endl** keyword is like the Enter key; it ends the line and moves the cursor to the next line. It is a better practice to put a `\n` inside the string (contained by "") to do the same thing, as `endl` always flushes the buffer and can hurt the performance of the program, but since this is a very small app, `endl` is used instead for better readability. + > - The `#include` statement brings in code in other files. Sometimes, you may see a filename surrounded by angle brackets like ``. The angle brackets instruct the compiler to look for the `iostream` header file first in the standard system directories, and if not found, to look in directories specific to the project. Other times, you may see a filename surrounded by quotes like `"someHeader.h"`. The quotes instruct the compiler to skip looking in the standard system directories and instead only look in directories specific to the project. + > - The `using namespace std;` tells the compiler to expect code from the C++ Standard Library to be used in this file. Without this line, each keyword from the library would have to be preceded with `std::` to denote its scope. For instance, without that line, each reference to `cout` would be written as `std::cout`. The **`using`** statement is added to make it more convenient to access code in another namespace. + > - The `cout` keyword prints to standard output in C++. The `<<` operator tells the compiler to send whatever is to the right of it to the standard output. + > - The `endl` keyword is like the Enter key; it ends the line and moves the cursor to the next line. It's a better practice to put a `\n` inside the string (contained by `""`) to do the same thing because `endl` always flushes the buffer and can hurt the performance of the program. But since this is a very small app, `endl` is used instead. > - All C++ statements must end with semicolons and all C++ applications must contain a `main()` function. This function is what the program runs at the start. All code must be accessible from `main()` in order to be used. -1. To save the file, enter **Ctrl+S**, or choose the **Save** icon near the top of the IDE, the floppy disk icon in the toolbar under the menu bar. +1. To save the file, press **Ctrl+S**, or select the floppy disk icon in the toolbar under the menu bar. -1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and choose **Start Without Debugging**. If you get a pop-up that says **This project is out of date**, you may select **Do not show this dialog again**, and then choose **Yes** to build your application. You should see a console window appear that displays the text specified in the code. +1. To run the application, press **Ctrl+F5** or go to the **Debug** menu and select **Start Without Debugging**. If you get a pop-up that says **This project is out of date**, you may select **Do not show this dialog again**, and then select **Yes** to build your application. You should see a console window appear that looks like this: - ![Build and start your application.](./media/calculator-first-launch.gif "Build and start your application") + :::image type="complex" source="./media/calculator-first-launch.png" alt-text="Screenshot of the calculator app running in a console window."::: + The console app shows the output which is: Calculator Console Application. Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The process exited with code 0 and there's a message that to automatically close the console when debugging stops, enable Tools > Options > Debugging > Automatically close the console when debugging stops. Lastly, there's a message to press any key to close this window. + :::image-end::: 1. Close the console window when you're done. ## Add code to do some math -It's time to add some math logic. +A class is like a blueprint for an object that does something. In this case, we define a calculator class to contain the math logic. + +### Add a Calculator class -### To add a Calculator class +1. Go to the **Project** menu and select **Add Class**. In the **Class Name** edit box, enter *Calculator*. Select **OK**. -1. Go to the **Project** menu and choose **Add Class**. In the **Class Name** edit box, enter *Calculator*. Choose **OK**. Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss any files when you save. + :::image type="complex" source="./media/calc-vs2017-create-calculator-class.png" alt-text="Screenshot of the Visual Studio Add Class dialog box."::: + The class name field contains the text calculator. The .h file field contains Calculator.h. The .cpp file field contains Calculator.cpp. The base class field is empty. The options for inline, and Managed are unchecked. + :::image-end::: - ![Short video showing the user opening the Add Class dialog box, typing Calculator in the Class Name field, and selecting O K.](./media/calculator-create-class.gif "Create the Calculator class") + A class is like a blueprint for an object that does something. In this case, we define a calculator and how it should work. - A class is like a blueprint for an object that does something. In this case, we define a calculator and how it should work. The **Add Class** wizard you used above created .h and .cpp files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the window isn't visible, you can open it from the menu bar: choose **View** > **Solution Explorer**. + Two new files get added to your project. To save all your changed files at once, press **Ctrl+Shift+S**. It's a keyboard shortcut for **File** > **Save All**. There's also a toolbar button for **Save All**, an icon of two floppy disks, found beside the **Save** button. In general, it's good practice to do **Save All** frequently, so you don't miss any files when you save. - ![Screenshot of the Solution Explorer window displaying the Calculator Tutorial project.](./media/calculator-solution-explorer.png "Solution Explorer") + The **Add Class** wizard creates `.h` and `.cpp` files that have the same name as the class. You can see a full list of your project files in the **Solution Explorer** window, visible on the side of the IDE. If the **Solution Explorer** isn't visible, open it from the menu bar: select **View** > **Solution Explorer**. - You should now have three tabs open in the editor: *CalculatorTutorial.cpp*, *Calculator.h*, and *Calculator.cpp*. If you accidentally close one of them, you can reopen it by double-clicking it in the **Solution Explorer** window. + :::image type="complex" source="./media/calculator-solution-explorer.png" alt-text="Screenshot of the Visual Studio Solution Explorer window."::: + The calculator tutorial project has a header files node containing Calculator.h, stdafx.h, and targetver.h. A Source Files node contains Calculator.cpp, CalculatorTutorial.cpp, and stdafx.cpp. Nodes for references, external dependencies, and resource files are visible but closed. + :::image-end::: -1. In **Calculator.h**, remove the `Calculator();` and `~Calculator();` lines that were generated, since you won't need them here. Next, add the following line of code so the file now looks like this: + You can open a file by double-clicking it in the **Solution Explorer** window. Double-click `Calculator.h` to open it. + +1. Replace the contents of **`Calculator.h`** with the following code so that the file now looks like this: ```cpp #pragma once @@ -525,21 +570,19 @@ It's time to add some math logic. > Understanding the code > - > - The line you added declares a new function called `Calculate`, which we'll use to run math operations for addition, subtraction, multiplication, and division. - > - C++ code is organized into *header* (.h) files and *source* (.cpp) files. Several other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where 'filename.h' is the name of the file that declares the variables or functions you want to use. - > - The two lines you deleted declared a *constructor* and *destructor* for the class. For a simple class like this one, the compiler creates them for you, and their uses are beyond the scope of this tutorial. + > - This code declares a new function called `Calculate`, which handles math operations for addition, subtraction, multiplication, and division. + > - C++ code is organized into *header* (`.h`) files and *source* (`.cpp`) files. Some other file extensions are supported by various compilers, but these are the main ones to know about. Functions and variables are normally *declared*, that is, given a name and a type, in header files, and *implemented*, or given a definition, in source files. To access code defined in another file, you can use `#include "filename.h"`, where `filename.h` is the name of the file that declares the variables or functions you want to use. > - It's good practice to organize your code into different files based on what it does, so it's easy to find the code you need later. In our case, we define the `Calculator` class separately from the file containing the `main()` function, but we plan to reference the `Calculator` class in `main()`. -1. You'll see a green squiggle appear under `Calculate`. It's because we haven't defined the `Calculate` function in the .cpp file. Hover over the word, click the lightbulb that pops up, and choose **Create definition of 'Calculate' in Calculator.cpp**. A pop-up appears that gives you a peek of the code change that was made in the other file. The code was added to *Calculator.cpp*. +1. A green squiggle appears under `Calculate` because although the `Calculate` function is *declared*, it isn't *defined*. Hover over `Calculate`, click the down arrow on the light bulb, and select **Create definition of 'Calculate' in `Calculator.cpp`**. A pop-up appears that gives you a peek of the code change that was made in the other file. The code was added to *`Calculator.cpp`*. - ![Short video showing the user selecting the Create definition of Calculate in Calculator C P P option.](./media/calculator-create-definition.gif "Create definition of Calculate") + :::image type="content" source="./media/calc-vs2017-create-definition.png" alt-text="Video showing using the light bulb dropdown to select Create definition of Calculate in Calculator.cpp."::: - Currently, it just returns 0.0. Let's change that. Press **Esc** to close the pop-up. + Currently, it just returns 0.0. Let's change that. Press **Esc** to close the pop-up and choose **Yes** to save the changes. -1. Switch to the *Calculator.cpp* file in the editor window. Remove the `Calculator()` and `~Calculator()` sections (as you did in the .h file) and add the following code to `Calculate()`: +1. Switch to the *`Calculator.cpp`* file in the editor window. Replace the contents of the file with the following code: ```cpp - #include "pch.h" #include "Calculator.h" double Calculator::Calculate(double x, char oper, double y) @@ -562,22 +605,21 @@ It's time to add some math logic. > Understanding the code > - > - The function `Calculate` consumes a number, an operator, and a second number, then performs the requested operation on the numbers. - > - The switch statement checks which operator was provided, and only executes the case corresponding to that operation. The default: case is a fallback in case the user types an operator that isn't accepted, so the program doesn't break. In general, it's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. - > - The **`double`** keyword denotes a type of number that supports decimals. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return such a number due to the **`double`** at the very start of the code (this denotes the function's return type), which is why we return 0.0 even in the default case. - > - The .h file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The .cpp file has all the implementation details of the function. + > - The function `Calculate` takes a number, an operator, and a second number. Then it performs the requested operation on the two numbers. + > - The `switch` statement checks which operator was provided, and executes the case corresponding to that operation. The `default:` case is a fallback in case the user types an operator that isn't handled by any of the preceding `case` statements. It's best to handle invalid user input in a more elegant way, but this is beyond the scope of this tutorial. + > - The **`double`** keyword denotes a type of number that supports decimals. This type of number is called a floating-point number, and `double` means a floating point number that has extra precision. This way, the calculator can handle both decimal math and integer math. The `Calculate` function is required to always return a double-precision floating point number due to the **`double`** at the start of the code (this denotes the function's return type), which is why we return 0.0 in the default case. + > - The `.h` file declares the function *prototype*, which tells the compiler upfront what parameters it requires, and what return type to expect from it. The `.cpp` file has all the implementation details of the function. -If you build and run the code again at this point, it will still exit after asking which operation to perform. Next, you'll modify the `main` function to do some calculations. +If you build and run the code again at this point, it still exits after asking which operation to perform. Next, modify the `main` function to do some calculations. -### To call the Calculator class member functions +### Call the Calculator class member functions -1. Now let's update the `main` function in *CalculatorTutorial.cpp*: +1. Update the `main` function in *`CalculatorTutorial.cpp`* as follows: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include #include "Calculator.h" @@ -591,8 +633,7 @@ If you build and run the code again at this point, it will still exit after aski char oper = '+'; cout << "Calculator Console Application" << endl << endl; - cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" - << endl; + cout << "Please enter the operation to perform. Format: a+b | a-b | a*b | a/b" << endl; Calculator c; while (true) @@ -608,87 +649,100 @@ If you build and run the code again at this point, it will still exit after aski > Understanding the code > - > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so a `#include` statement is needed. - > - Some initial variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It is always good practice to give them some initial values to avoid undefined behavior, which is what is done here. - > - The `Calculator c;` line declares an object named 'c' as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. - > - The `while (true)` statement is a loop. The code inside the loop continues to execute over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. - > - The `cin` keyword is used to accept input from the user. This input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order, assuming the user input matches the required specification. You can modify this line to accept different types of input, for instance, more than two numbers, though the `Calculate()` function would also need to be updated to handle this. - > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values. The function then returns a number that gets stored in `result`. - > - Finally, `result` is printed to the console, so the user sees the result of the calculation. + > - Since C++ programs always start at the `main()` function, we need to call our other code from there, so an `#include` statement is needed to make that code visible to our `main()` function. + > - The variables `x`, `y`, `oper`, and `result` are declared to store the first number, second number, operator, and final result, respectively. It's always good practice to give them some initial values to avoid undefined behavior, which is what is done here. + > - The `Calculator c;` line declares an object named `c` as an instance of the `Calculator` class. The class itself is just a blueprint for how calculators work; the object is the specific calculator that does the math. + > - The `while (true)` statement is a loop. The code inside the loop execute over and over again as long as the condition inside the `()` holds true. Since the condition is simply listed as **`true`**, it's always true, so the loop runs forever. To close the program, the user must manually close the console window. Otherwise, the program always waits for new input. + > - The `cin` keyword accepts input from the user. The input stream is smart enough to process a line of text entered in the console window and place it inside each of the variables listed, in order. + > - The `c.Calculate(x, oper, y);` expression calls the `Calculate` function defined earlier, and supplies the entered input values and the requested operation. The function then returns a number that is stored in `result`. + > - Finally, `result` is printed to the console and the user sees the result of the calculation. ### Build and test the code again -Now it's time to test the program again to make sure everything works properly. +Test the program again to make sure everything works properly. 1. Press **Ctrl+F5** to rebuild and start the app. +1. Enter `5+5`, and press **Enter**. Verify that the result is 10. -1. Enter `5 + 5`, and press **Enter**. Verify that the result is 10. - - ![Screenshot of the Microsoft Visual Studio Debug Console showing the correct result of 5 + 5.](./media/calculator-five-plus-five.png "The result of 5 + 5") + :::image type="content" source="./media/calculator-five-plus-five.png" alt-text="Screenshot of a command window running the Calculator app. It shows that the result of 5 + 5 is 10."::: +1. Stop the program by closing the console window. ## Debug the app -Since the user is free to type anything into the console window, let's make sure the calculator handles some input as expected. Instead of running the program, let's debug it instead, so we can inspect what it's doing in detail, step-by-step. +Since the user is free to type anything into the console window, let's make sure the calculator handles unexpected input. Instead of running the program, let's debug it instead, so we can inspect what it's doing step-by-step. -### To run the app in the debugger +### Run the app in the debugger -1. Set a breakpoint on the `result = c.Calculate(x, oper, y);` line, just after the user was asked for input. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window. A red dot appears. +1. In `CalcuatorTutorial.cpp`, set a breakpoint on the `result = c.Calculate(x, oper, y);` line. To set the breakpoint, click next to the line in the gray vertical bar along the left edge of the editor window so that a red dot appears. - ![Short video of Visual Studios showing the user creating the red dot that represents a breakpoint.](./media/calculator-set-breakpoint.gif "Set a breakpoint") + :::image type="content" source="./media/calc-vs2017-set-breakpoint.png" alt-text="Screenshot of the user setting a breakpoint on line 23: result = c.Calculate(x, oper, y);."::: - Now when we debug the program, it always pauses execution at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time, let's make the breakpoint conditional. + Now when you debug the program, it always pauses execution at that line. We already have a rough idea that the program works for simple cases. Since we don't want to pause execution every time, let's make the breakpoint conditional. -1. Right-click the red dot that represents the breakpoint, and choose **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Choose the **Close** button when you're done. The condition is saved automatically. +1. Right-click the red dot that represents the breakpoint, and select **Conditions**. In the edit box for the condition, enter `(y == 0) && (oper == '/')`. Select the **Close** button when you're done to save the breakpoint condition. - ![Short video of Visual Studio 2019 showing the user opening the Breakpoint Settings section and setting a conditional breakpoint.](./media/calculator-conditional-breakpoint.gif "Set a conditional breakpoint") + :::image type="complex" source="./media/calc-vs2017-conditional-breakpoint.png" alt-text="Screenshot showing the conditional breakpoint window."::: + The breakpoint is on the line: result = c dot Calculate ( x, oper, y). 'Conditions...' The Condition option is checked. The Conditions dropdown is set to "Conditional Expression". The condition dropdown is set to "Is true". The condition is set to y == 0 && oper == '/'. + :::image-end::: - Now we pause execution at the breakpoint specifically if a division by 0 is attempted. + Execution will pause at the breakpoint if a division by 0 is attempted. -1. To debug the program, press **F5**, or choose the **Local Windows Debugger** toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can even put any number of spaces between the operator and numbers; `cin` is smart enough to parse the input appropriately. +1. To debug the program, press **F5**, or select the **Local Windows Debugger** toolbar button that has the green arrow icon. In your console app, if you enter something like "5 - 0", the program behaves normally and keeps running. However, if you type "10 / 0", it pauses at the breakpoint. You can even put any number of spaces between the operator and numbers; `cin` is smart enough to parse the input appropriately. - ![Short video of Visual Studios showing that the program paused at the conditional breakpoint.](./media/calculator-debug-conditional.gif "Pause at the conditional breakpoint") + :::image type="complex" source="./media/calc-vs2017-debug-breakpoint.png" alt-text="Video showing the program execution paused at the conditional breakpoint."::: + The user enters 5 - 0. The app outputs: Result is 5. The user then enters 10/0 and because the condition for the conditional breakpoint is met, execution stops on the line: result = c.Calculate(x, oper, y); + :::image-end::: ### Useful windows in the debugger -Whenever you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. +When you debug your code, you may notice that some new windows appear. These windows can assist your debugging experience. Take a look at the **Autos** window. The **Autos** window shows you the current values of variables used at least three lines before and up to the current line. If you don't see the **Autos** window, from the main menu select **Debug** > **Windows** > **Autos**. - ![The Autos window.](./media/calculator-autos.png "The Autos window") + :::image type="complex" source="./media/calculator-autos.png" alt-text="Screenshot of the Visual Studio debugger Autos window."::: + The value of oper is 47 '/', result is 5, x is 10, and y is 0. + :::image-end::: -To see all of the variables from that function, switch to the **Locals** window. You can actually modify the values of these variables while debugging, to see what effect they would have on the program. In this case, we'll leave them alone. +To see all of the variables from that function, switch to the **Locals** window. Because this is a small function, the Autos and Locals window show the same variables. But you can modify the values of these variables while debugging, to see what effect they would have on the program. In this case, we leave them alone. Open the **Locals** window by selecting **Locals** at the bottom of the **Autos** window, or by selecting from the main menu **Debug** > **Windows** > **Locals**. - ![Screenshot of the Locals window.](./media/calculator-locals.png "The Locals window") + :::image type="complex" source="./media/calculator-locals.png" alt-text="Screenshot of the Locals window in Visual Studio, displaying the current values of local variables while debugging."::: + The value of oper is 47 '/', result is 0, x is 10, and y is 0. + :::image-end::: -You can also just hover over variables in the code itself to see their current values where the execution is currently paused. Make sure the editor window is in focus by clicking on it first. +You can also hover over variables in the code itself to see their current values where the execution is currently paused. Make sure the editor window is in focus by clicking on it first. - ![Short video showing the tooltip that appears displaying the value of the variable.](./media/calculator-hover-tooltip.gif "Hover to view current variable values") + :::image type="content" source="./media/calc-vs2017-hover-tooltip.png" alt-text="Video demonstrating a tooltip that appears while hovering over the variable y. It displays y's current value, which is 0."::: -### To continue debugging +### Continue debugging -1. The yellow line on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function. You'll find yourself in the body of the `Calculate` function. Be careful with **Step Into**; if you do it too much, you may waste a lot of time. It goes into any code you use on the line you are on, including standard library functions. +1. The yellow arrow on the left shows the current point of execution. The current line calls `Calculate`, so press **F11** to **Step Into** the function, which takes you into the body of the `Calculate` function. Be careful with **Step Into** because it steps into any functions on the line you're on, including standard library functions. It's fine to step into the standard library, but you may be more interested in focusing on your code instead of library code. 1. Now that the point of execution is at the start of the `Calculate` function, press **F10** to move to the next line in the program's execution. **F10** is also known as **Step Over**. You can use **Step Over** to move from line to line, without delving into the details of what is occurring in each part of the line. In general you should use **Step Over** instead of **Step Into**, unless you want to dive more deeply into code that is being called from elsewhere (as you did to reach the body of `Calculate`). 1. Continue using **F10** to **Step Over** each line until you get back to the `main()` function in the other file, and stop on the `cout` line. - ![Step out of Calculate and check result.](./media/calculator-undefined-zero.gif "Step out of Calculate and check result") + The program is doing what's expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. Its value is `inf`, which doesn't look right. + + :::image type="complex" source="./media/calc-vs2017-debug-inf.png" alt-text="Screenshot of debugging the calculator."::: + The current statement in the debugger is cout << "Result is: " << result << endl; In the autos window, result is inf. + :::image-end::: - It looks like the program is doing what is expected: it takes the first number, and divides it by the second. On the `cout` line, hover over the `result` variable or take a look at `result` in the **Autos** window. You'll see its value is listed as "inf", which doesn't look right, so let's fix it. The `cout` line just outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: + Let's fix it. The `cout` line outputs whatever value is stored in `result`, so when you step one more line forward using **F10**, the console window displays: - ![Screenshot of the Microsoft Visual Studio Debug Console showing the result of dividing by zero.](./media/calculator-divide-by-zero-fail.png "The result of divide by zero") + :::image type="complex" source="./media/calc-divide-by-zero-fail.png" alt-text="Screenshot of the Visual Studio Debug Console displaying the result of a division by zero operation."::: + The app outputs: Please enter the operation to perform. Format: a+b | a-b | a*b | a/b. The user entered 5-0. The app output: Result is: 5. The user entered 10/0. The app output: Result is: inf + :::image-end::: - This result happens because division by zero is undefined, so the program doesn't have a numerical answer to the requested operation. + This result is because division by zero is undefined, so the program doesn't have a numerical answer for the requested operation. -### To fix the "divide by zero" error +### Fix the "divide by zero" error -Let's handle division by zero more gracefully, so a user can understand the problem. +Let's handle division by zero more gracefully so that it's easier for the user to understand the problem. -1. Make the following changes in *CalculatorTutorial.cpp*. (You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**): +1. Make the following changes in *`CalculatorTutorial.cpp`*. (You can leave the program running as you edit, thanks to a debugger feature called **Edit and Continue**). The change is to add an `if` statement following `cin >> x >> oper >> y;` to check for division by zero and output a message to the user if it happens. Otherwise, the result is printed: ```cpp // CalculatorTutorial.cpp : This file contains the 'main' function. Program execution begins and ends there. // - #include "pch.h" #include #include "Calculator.h" @@ -707,7 +761,7 @@ Let's handle division by zero more gracefully, so a user can understand the prob Calculator c; while (true) { - cin >> x >> oper >> y; + cin >> x >> oper >> y; if (oper == '/' && y == 0) { cout << "Division by 0 exception" << endl; @@ -724,25 +778,29 @@ Let's handle division by zero more gracefully, so a user can understand the prob } ``` -1. Now press **F5** once. Program execution continues all the way until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. +1. Press **F5** once. Program execution continues until it has to pause to ask for user input. Enter `10 / 0` again. Now, a more helpful message is printed. The user is asked for more input, and the program continues executing normally. - ![Short video of the Microsoft Visual Studio Debug Console showing the final result after changes.](./media/calculator-final-verification.gif "The final result after changes") + :::image type="content" source="./media/calc-final-verification.png" alt-text="Video of the Debug Console showing the final result after code changes. 10 / 0 is entered and the program displays 'Division by 0 exception'."::: > [!Note] - > When you edit code while in debugging mode, there is a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger pops up a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, you'll need to step out of the function, then back into it again to get the updated code. If that doesn't work for some reason and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > When you edit code while in debugging mode, there's a risk of code becoming stale. This happens when the debugger is still running your old code, and has not yet updated it with your changes. The debugger pops up a dialog to inform you when this happens. Sometimes, you may need to press **F5** to refresh the code being executed. In particular, if you make a change inside a function while the point of execution is inside that function, step out of the function, then back into it again to get the updated code. If that doesn't work for some reason and you see an error message, you can stop debugging by clicking on the red square in the toolbar under the menus at the top of the IDE, then start debugging again by entering **F5** or by choosing the green "play" arrow beside the stop button on the toolbar. + > + > Another reason edit and continue may fail is that you need to go to the main menu and select **Tools** > **Options** > **Debugging** > **General** and ensure that **Require source files to exactly match the original version** is checked. > Understanding the Run and Debug shortcuts > - > - **F5** (or **Debug** > **Start Debugging**) starts a debugging session if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If you have something like a "Hello World" program to run, use **Ctrl+F5** or set a breakpoint before you enter **F5** to keep the window open. - > - **Ctrl+F5** (or **Debug** > **Start Without Debugging**) runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. - > - **F10** (known as **Step Over**) lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. - > - **F11** (known as **Step Into**) works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. + > - **F5**, or **Debug** > **Start Debugging**, starts a debugging session, if one isn't already active, and runs the program until a breakpoint is hit or the program needs user input. If no user input is needed and no breakpoint is available to hit, the program terminates and the console window closes itself when the program finishes running. If your program outputs to the console, use **Ctrl+F5** or set a breakpoint before you press **F5** to keep the window open. + > - **Ctrl+F5**, or **Debug** > **Start Without Debugging**, runs the application without going into debug mode. This is slightly faster than debugging, and the console window stays open after the program finishes executing. + > - **F10**, known as **Step Over**, lets you iterate through code, line-by-line, and visualize how the code is run and what variable values are at each step of execution. + > - **F11**, known as **Step Into**, works similarly to **Step Over**, except it steps into any functions called on the line of execution. For example, if the line being executed calls a function, pressing **F11** moves the pointer into the body of the function, so you can follow the function's code being run before coming back to the line you started at. Pressing **F10** steps over the function call and just moves to the next line; the function call still happens, but the program doesn't pause to show you what it's doing. ### Close the app -- If it's still running, close the console window for the calculator app. +- If it's still running, close the console window to stop the calculator app. + +## The finished app -Congratulations! You've completed the code for the calculator app, and built and debugged it in Visual Studio. +Congratulations! You completed the code for the calculator app, and built and debugged it in Visual Studio. ## Next steps diff --git a/docs/ide/add-interface-definition-library-method-wizard.md b/docs/ide/add-interface-definition-library-method-wizard.md index e371aa47e91..af92363f297 100644 --- a/docs/ide/add-interface-definition-library-method-wizard.md +++ b/docs/ide/add-interface-definition-library-method-wizard.md @@ -1,10 +1,11 @@ --- -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"] ms.custom: devdivchpfy22 +ms.topic: how-to --- # Add an IDL method @@ -20,7 +21,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 +43,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/add-interface-definition-library-property-wizard.md b/docs/ide/add-interface-definition-library-property-wizard.md index c12abece36d..8391d750929 100644 --- a/docs/ide/add-interface-definition-library-property-wizard.md +++ b/docs/ide/add-interface-definition-library-property-wizard.md @@ -5,6 +5,7 @@ ms.date: 04/14/2022 f1_keywords: ["vc.codewiz.prop.overview", "vc.codewiz.prop.idlattributes"] helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "IDL attributes", "stock properties, about stock properties", "stock properties"] ms.custom: devdivchpfy22 +ms.topic: how-to --- # Add an IDL property 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 afc07efc569..7fceea68e7c 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,15 @@ --- 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 +ms.topic: how-to --- # 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 +26,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/adding-a-generic-cpp-class.md b/docs/ide/adding-a-generic-cpp-class.md index 9d7342c49c2..48e95baf99b 100644 --- a/docs/ide/adding-a-generic-cpp-class.md +++ b/docs/ide/adding-a-generic-cpp-class.md @@ -1,10 +1,10 @@ --- -description: "Learn more about: Add a generic C++ class" title: "Add a generic C++ class" -ms.date: "11/09/2018" +description: "Learn more about: Add a generic C++ class" +ms.date: 11/09/2018 +ms.topic: how-to f1_keywords: ["vc.codewiz.classes.adding.generic", "vc.codewiz.class.generic"] helpviewer_keywords: ["Visual C++, classes", "generic classes, adding", "generic classes", "generic C++ class wizard [C++]"] -ms.assetid: e95a5a14-dbed-4edc-8551-344fe48613cb --- # Add a generic C++ class @@ -12,7 +12,7 @@ You can add a generic C++ class by using **Class View**. A generic C++ class is ::: moniker range="msvc-140" -## To add a generic C++ class to a project: +## To add a generic C++ class to a project 1. In **Class View**, right-click the project to which you want to add the new class, choose **Add**, and then choose **Class**. diff --git a/docs/ide/adding-a-member-function-visual-cpp.md b/docs/ide/adding-a-member-function-visual-cpp.md index 4dd50a46717..0ae5d7ab880 100644 --- a/docs/ide/adding-a-member-function-visual-cpp.md +++ b/docs/ide/adding-a-member-function-visual-cpp.md @@ -5,6 +5,7 @@ ms.date: "11/09/2018" f1_keywords: ["vc.codewiz.classes.member.function", "vc.codewiz.function.overview"] helpviewer_keywords: ["member functions, adding to classes", "classes [C++], adding members", "add member function wizard [C++]"] ms.assetid: 55b25ddb-541d-44ed-957c-974ef91cfc85 +ms.topic: how-to --- # Add a member function diff --git a/docs/ide/adding-a-member-variable-visual-cpp.md b/docs/ide/adding-a-member-variable-visual-cpp.md index 853f4385133..76a6a69fd16 100644 --- a/docs/ide/adding-a-member-variable-visual-cpp.md +++ b/docs/ide/adding-a-member-variable-visual-cpp.md @@ -5,6 +5,7 @@ ms.date: "11/09/2018" f1_keywords: ["vc.codewiz.classes.member.variable", "vc.codewiz.variable.overview"] helpviewer_keywords: ["member variables, adding", "member variables", "add member variable wizard [C++]", "dialog box controls, member variables", "dialog box controls, variable types", "variables, dialog box control member variables"] ms.assetid: 437783bd-8eb4-4508-8b73-7380116e9d71 +ms.topic: how-to --- # Add a member variable diff --git a/docs/ide/adding-a-method-visual-cpp.md b/docs/ide/adding-a-method-visual-cpp.md index 6fdc77ce36e..c5e2c1e9944 100644 --- a/docs/ide/adding-a-method-visual-cpp.md +++ b/docs/ide/adding-a-method-visual-cpp.md @@ -5,6 +5,7 @@ ms.date: "03/31/2022" f1_keywords: ["vc.codewiz.method.overview", "vc.codewiz.method.idlattrib"] helpviewer_keywords: ["add method wizard [C++]", "methods [C++], adding", "methods [C++], adding using wizards", "IDL attributes, add method wizard"] ms.custom: devdivchpfy22 +ms.topic: how-to --- # Add a method @@ -59,4 +60,4 @@ Add a method to an interface by using the add method wizard: [Add an IDL method wizard](add-interface-definition-library-method-wizard.md)\ [Add an IDL MFC method wizard](../mfc/reference/add-idl-mfc-method-wizard.md)\ -[Adding functionality with code wizards](adding-functionality-with-code-wizards-cpp.md) \ No newline at end of file +[Adding functionality with code wizards](adding-functionality-with-code-wizards-cpp.md) diff --git a/docs/ide/adding-a-property-visual-cpp.md b/docs/ide/adding-a-property-visual-cpp.md index f710a05befb..4ec27fc8d6f 100644 --- a/docs/ide/adding-a-property-visual-cpp.md +++ b/docs/ide/adding-a-property-visual-cpp.md @@ -1,10 +1,11 @@ --- -description: "Learn more about: Add a property to an interface in a Microsoft Visual Studio C++ project" title: "Add a property" +description: "Learn more about: Add a property to an interface in a Microsoft Visual Studio C++ project" ms.date: 04/12/2022 f1_keywords: ["vc.codewiz.prop.overview"] helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "add property wizard", "stock properties, about stock properties", "stock properties"] ms.custom: devdivchpfy22 +ms.topic: how-to --- # Add a property @@ -52,8 +53,8 @@ The following section describes the UI that you'll use to add a property: For ATL interfaces **Put function** makes the property writable; that is, it creates the `Put` method for setting, or "putting," this property of the object. Select **Get**, **Put**, or both. -## See Also +## See also [Add IDL Property](add-interface-definition-library-property-wizard.md) -[Add IDL MFC Property](../mfc/reference/add-interface-definition-library-mfc-property-wizard.md) \ No newline at end of file +[Add IDL MFC Property](../mfc/reference/add-interface-definition-library-mfc-property-wizard.md) diff --git a/docs/ide/adding-an-event-handler-visual-cpp.md b/docs/ide/adding-an-event-handler-visual-cpp.md index b5bb5ac8e0b..0990bfb6222 100644 --- a/docs/ide/adding-an-event-handler-visual-cpp.md +++ b/docs/ide/adding-an-event-handler-visual-cpp.md @@ -5,6 +5,7 @@ ms.date: "11/12/2018" f1_keywords: ["vc.codewiz.eventhandler.overview"] helpviewer_keywords: ["event handlers, adding", "properties [Visual Studio], MSBuild", "MSBuild, properties", "event handler wizard [C++]"] ms.assetid: 050bebf0-a9e0-474b-905c-796fe5ac8fc3 +ms.topic: how-to --- # Add an event handler diff --git a/docs/ide/adding-an-event-visual-cpp.md b/docs/ide/adding-an-event-visual-cpp.md index 68c78c71bde..7a28e7de1ad 100644 --- a/docs/ide/adding-an-event-visual-cpp.md +++ b/docs/ide/adding-an-event-visual-cpp.md @@ -5,6 +5,7 @@ ms.date: "11/12/2018" f1_keywords: ["vc.codewiz.event.overview"] helpviewer_keywords: ["ActiveX controls [C++], adding events to", "MFC ActiveX controls [C++], adding events", "events [C++], ActiveX controls", "add event wizard [C++]"] ms.assetid: fe34832a-edfc-4f86-aacb-8df77001873d +ms.topic: how-to --- # Add an event diff --git a/docs/ide/adding-functionality-with-code-wizards-cpp.md b/docs/ide/adding-functionality-with-code-wizards-cpp.md index d2d5cf313d5..4921258492d 100644 --- a/docs/ide/adding-functionality-with-code-wizards-cpp.md +++ b/docs/ide/adding-functionality-with-code-wizards-cpp.md @@ -4,13 +4,14 @@ title: "Adding Functionality with Code Wizards (C++)" ms.date: "05/14/2019" helpviewer_keywords: ["code wizards [C++]"] ms.assetid: 6afb7ef9-7056-423d-b244-91bb4236d1d7 +ms.topic: concept-article --- # Adding Functionality with Code Wizards (C++) Once you have created a project, you will want to change or add to that project's functionality. Such tasks include creating new classes, adding new member functions and variables, and adding Automation methods and properties. The code wizards are designed to let you do all these things. > [!NOTE] -> The following rarely-used code wizards are removed in Visual Studio 2019. General support for ATL and MFC is not impacted by the removal of these wizards. Sample code for these technologies is archived at Microsoft Docs and the VCSamples GitHub repository. +> The following rarely-used code wizards are removed in Visual Studio 2019. General support for ATL and MFC is not impacted by the removal of these wizards. Sample code for these technologies is archived in Microsoft Learn and the VCSamples GitHub repository. - ATL COM+ 1.0 Component Wizard - ATL Active Server Pages Component Wizard diff --git a/docs/ide/cpp-linter-overview.md b/docs/ide/cpp-linter-overview.md index a6bda09ef76..e6c987576c8 100644 --- a/docs/ide/cpp-linter-overview.md +++ b/docs/ide/cpp-linter-overview.md @@ -2,7 +2,7 @@ description: "Learn more about: IntelliSense code linter for C++" title: IntelliSense code linter for C++ overview ms.date: 09/30/2021 -ms.topic: conceptual +ms.topic: overview helpviewer_keywords: - "C/C++, linter" - "C++, linter" @@ -16,7 +16,9 @@ monikerRange: ">=msvc-160" The IntelliSense code linter for C++ helps developers find and fix common C++ problems right inside Visual Studio. It's based on the same engine that provides C++ IntelliSense, so problems are flagged as soon as you type them. -![Animation showing the C plus plus linter in action.](../ide/media/linter-demo-animation.gif) +:::image type="complex" source="media/linter-demo-animation.gif" alt-text="Animation showing the C plus plus linter in action."::: +As the user types if (i = 3), a popup appears suggesting the correction i == 3, which is selected and updates the code to read if (i == 3) +:::image-end::: ## Find problems @@ -26,7 +28,7 @@ Starting in Visual Studio 2022, the C++ Linter is enabled by default. To use it, Most of the linter checks have suggestions for fixing the problem. Hover over the error squiggle and choose the light bulb that pops up to see the suggestions. A preview diff of the suggested change is shown, so you can confirm the change makes sense before you apply it. -## Configure the linter +## Configure the linter You can enable or disable the linter, or configure the severity level for each check, in the C++ Code Style options. @@ -38,7 +40,7 @@ When you change the check severity level, it changes how the problem is shown in ::: moniker range=">=msvc-170" -![Screenshot that shows the C plus plus linter configuration.](../ide/media/linter-settings.png) +![Screenshot of the linter configuration window with options such as warning on accidental assignment, uninitialized local variable, and more.](media/linter-settings.png) (The presentation in Visual Studio 2019 is slightly different, but the options are similar.) diff --git a/docs/ide/how-to-set-preferences.md b/docs/ide/how-to-set-preferences.md index fe492600dc5..a4acc288624 100644 --- a/docs/ide/how-to-set-preferences.md +++ b/docs/ide/how-to-set-preferences.md @@ -16,7 +16,7 @@ You can make your C++ coding experience more convenient, productive, and pleasur - Specify C++ formatting rules, including several styles of ClangFormat. - Create custom keyboard shortcuts. -You can synchronize your preferences across multiple machines, and create and store multiple sets of preferences and share them with teammates. You can install extensions from the Visual Studio Marketplace, giving you additional options for customizing behavior. For more information, see [Personalize the Visual Studio IDE](/visualstudio/ide/personalizing-the-visual-studio-ide). +You can synchronize your preferences across multiple machines, and create and store multiple sets of preferences and share them with teammates. You can install extensions from the Visual Studio Marketplace, giving you more options for customizing behavior. For more information, see [Personalize the Visual Studio IDE](/visualstudio/ide/personalizing-the-visual-studio-ide). ## Arrange window layout @@ -24,7 +24,7 @@ Within the Visual Studio window, the space is divided into the main menu, the to The following screenshot shows the **Team Explorer** window being dragged from its default position to a new, docked position on the left side of the code editor. The blue shaded area shows where the window will be placed when the mouse button is released. -![Screenshot of Visual Studio Team Explorer window, with layout change highlighted.](media/window-layout-move-team-explorer.png) +![Screenshot of Visual Studio Team Explorer window, with the blue shaded area highlighted where the window will be placed when the mouse is released.](media/window-layout-move-team-explorer.png) In the document window, each open file is contained in a tabbed frame. You can float or lock these tabs, just like tool windows. For more information, see [Customize window layouts in Visual Studio](/visualstudio/ide/customizing-window-layouts-in-visual-studio). @@ -34,7 +34,7 @@ To hide all the tool windows and maximize the Code Editor window, press **Alt** You can specify many individual code formatting options, such as indentation and brace positions. To do so, go to **Tools** > **Options** > **Text Editor** > **C/C++** > **Formatting** (or type **Ctrl + Q** and search for "Formatting"). Alternatively, you can specify one of the [ClangFormat](https://clang.llvm.org/docs/ClangFormat.html) styles (or your own custom ClangFormat style). -![Screenshot of ClangFormat options.](media/clang-format-ide.png) +![Screenshot of the Options pane with Text Editor > C / C plus plus > Formatting > General selected. In the right pane the ClangFormat options appear.](media/clang-format-ide.png) For more information about all the formatting options, see [Options, Text Editor, C/C++, Formatting](/visualstudio/ide/reference/options-text-editor-c-cpp-formatting). @@ -42,25 +42,25 @@ For more information about all the formatting options, see [Options, Text Editor To set a light or dark background, type **Ctrl + Q** and search for "Color Theme". You can also find these by going to **Tools** > **Options** > **Environment**, and choosing **Color Theme**. -![Screenshot of color themes.](media/tools-options-color-theme.png) +![Screenshot of the Options pane. Environment > General is selected. On the right, the color theme dropdown shows options for Light, Dark, and more.](media/tools-options-color-theme.png) For example, here's the dark theme: -![Screenshot of Visual Studio with dark color theme.](media/tools-options-dark-theme.png) +![Screenshot of Visual Studio with the dark color theme.](media/tools-options-dark-theme.png) ## Customize code colorization In Visual Studio 2019, you can choose from three predefined *color schemes*. These specify how code elements are colorized in the editor. To choose a theme, go to **Tools** > **Options** > **Text Editor** > **C/C++** > **View**, and choose **Color Scheme**: -![Screenshot of C++ Color Scheme options, with Enhanced highlighted.](media/color-schemes.png) +![Screenshot of C++ Color Scheme dropdown options. Of the available options, Enhanced is highlighted.](media/color-schemes.png) -In the color scheme called **Visual Studio 2017**, most code elements are simply black. In the **Enhanced** color scheme, functions, local variables, macros, and other elements are colorized. In the **Enhanced (Globals vs. Members)** scheme, global functions and variables are colorized to contrast with class members. The default mode is **Enhanced**, and it looks like this: +In the color scheme called **Visual Studio 2017**, most code elements are black. In the **Enhanced** color scheme, functions, local variables, macros, and other elements are colorized. In the **Enhanced (Globals vs. Members)** scheme, global functions and variables are colorized to contrast with class members. The default mode is **Enhanced**, and it looks like this: -![Screenshot of enhanced color scheme.](media/color-scheme-enhanced.png) +![Screenshot of the enhanced color scheme which has a black background and colors for C++ keywords such as blue for int and green for comments.](media/color-scheme-enhanced.png) Regardless of which theme or color scheme is active, you can customize the font and colors for individual code elements. To do this, go to **Tools** > **Options** > **Environment** > **Fonts and Colors** (or type **Ctrl + Q** and search for "Fonts"). Scroll down the list of display items until you see the C++ options. -![Screenshot of C++ font and color options.](media/tools-options-cpp-colors.png) +![Screenshot of C++ font and color options that shows you can set colors for C++ code elements such as enums, functions, keywords, macros, and so on.](media/tools-options-cpp-colors.png) Colors that you set here override the values defined for the color schemes. If you want to go back to the default colors for the color scheme, set a color back to **Default**. @@ -70,11 +70,11 @@ The toolbars provide a convenient way to issue commands with a single click, rat Hover over the icons in the toolbar to see which command it represents: -![Screenshot of toolbar icons, with example of command information available on hover.](media/toolbar-mouse-hover.png) +![Screenshot of hovering over the bookmark icon. The tooltip says: "Toggle a bookmark on the current line", along with the keyboard shortcut Ctrl+K, Ctrl+K.](media/toolbar-mouse-hover.png) You can add or remove commands, or create a custom toolbar, by selecting the down-arrow. To move the toolbar to a new location, drag it by the dotted bar on the left. -![Screenshot of toolbar, with down-arrow and dotted bar highlighted.](media/toolbar-move-edit.png). +![Screenshot of a toolbar with the dotted bar on the left highlighted where you move the toolbar with the mouse. The down arrow is also highlighted.](media/toolbar-move-edit.png). For more information, see [How to: Customize menus and toolbars in Visual Studio](/visualstudio/ide/how-to-customize-menus-and-toolbars-in-visual-studio). @@ -82,7 +82,7 @@ For more information, see [How to: Customize menus and toolbars in Visual Studio You can specify whether line numbers show on the left of the editor windows. In **Options**, under **C/C++**, select **General**. In the **Settings** section, select or clear **Line numbers**, depending on your preference. -![Screenshot of General options, with Line numbers highlighted.](media/tools-options-line-numbers.png) +![Screenshot of General options (Text Editor > C / C plus plus > General). The Line numbers checkbox is highlighted.](media/tools-options-line-numbers.png) ## Create keyboard shortcuts diff --git a/docs/ide/implementing-a-connection-point-visual-cpp.md b/docs/ide/implementing-a-connection-point-visual-cpp.md index 20e7d83b8aa..252f5ff9310 100644 --- a/docs/ide/implementing-a-connection-point-visual-cpp.md +++ b/docs/ide/implementing-a-connection-point-visual-cpp.md @@ -4,6 +4,7 @@ title: "Implement a connection point" ms.date: "05/14/2019" helpviewer_keywords: ["connection points [C++], implementing", "implement connection point wizard [C++]"] ms.assetid: 5b37e4f9-73c9-4bef-b26d-365bc0662260 +ms.topic: how-to --- # Implement a connection point diff --git a/docs/ide/implementing-an-interface-visual-cpp.md b/docs/ide/implementing-an-interface-visual-cpp.md index 7696bdfd9a2..fcb5cb92f34 100644 --- a/docs/ide/implementing-an-interface-visual-cpp.md +++ b/docs/ide/implementing-an-interface-visual-cpp.md @@ -5,6 +5,7 @@ ms.date: "11/12/2018" f1_keywords: ["vc.codewiz.impl.interface.overview"] helpviewer_keywords: ["interfaces, implementing", "implement interface wizard [C++]"] ms.assetid: 72f8731b-7e36-45db-8b10-7ef211a773cd +ms.topic: how-to --- # Implement an interface diff --git a/docs/ide/include-cleanup-config.md b/docs/ide/include-cleanup-config.md new file mode 100644 index 00000000000..0f2b6d59871 --- /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: 01/23/2026 +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`

Suppress messages for indirect includes. For example, if you `#include ` and only use content from its indirectly included headers `winerror.h` or `minwindef.h`, the tool won't suggest adding them. | *file1*:*file2*[:*file3*...][,*file4*:*file5*...] | `cpp_include_cleanup_alternate_files = windows.h:winerror.h:minwindef.h`
or
`cpp_include_cleanup_alternate_files = windows.h:winerror.h:minwindef.h,umbrella.h:internal.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 00000000000..e3dfcb4af6b --- /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 00000000000..423b16a3440 --- /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 00000000000..c28d372ff29 --- /dev/null +++ b/docs/ide/include-diagnostics.md @@ -0,0 +1,106 @@ +--- +title: "C++ Include Diagnostics" +description: "Learn how to use #include Diagnostics in Visual Studio to analyze how often something from an include file is used and how an #include impacts build time." +ms.date: 10/10/2023 +ms.topic: "how-to" +f1_keywords: ["include diagnostics"] +helpviewer_keywords: ["include diagnostics"] +--- +# C++ Include Diagnostics in Visual Studio + +Starting with Visual Studio 17.8, Visual Studio helps you analyze your C++ `#include` files: + +- Displays how often, and where, something from each header file is used. +- Displays the build time for each `#include` file--which helps you identify opportunities to optimize your build time. + +## Enable C++ Include Diagnostics and CodeLens + +The C++ Include Diagnostics feature is off by default. To turn it on, right-click in the code editor to bring up the context menu, and choose **Include Directives** > **Turn #include Diagnostics On**. + +:::image type="complex" source="media/vs2022-enable-include-diagnostics.png" alt-text="A screenshot of the context menu that appears when you right-click in the code editor area."::: +The context menu shows the include directives option highlighted, which reveals two options: Sort # include directives and turn # include diagnostics on. +:::image-end::: + +Information about your `#include` files is displayed via CodeLens, which is off by default. To turn on the relevant CodeLens settings, navigate to **Tools** > **Options** > **Text Editor** > **All Languages** > **CodeLens** and confirm both **Show C++ #include references** and **Show C++ compilation times** are enabled. + +:::image type="complex" source="media/vs2022-enable-code-lens-for-includes.png" alt-text="A screenshot of the options window."::: +The options window is set to Text Editor > All Languages > CodeLens. The Show C++ # include references and Show C++ compilation times options are highlighted. +:::image-end::: + +## View `#include` references + +To try out Include Diagnostics, create a new C++ console project. Replace the contents of the main `.cpp` file with the following code: + +```cpp +#include +#include + +// a function that takes a vector of integers and prints them out +void print(std::vector &vec) +{ + for (int i : vec) + { + std::cout << i << std::endl; + } + std::cout << std::endl; +} + +// a function that takes a vector of integers and adds 10 to each element of the vector and store the result in a new vector +std::vector add10(std::vector& vec) +{ + std::vector newVec; + for (int i : vec) + { + newVec.push_back(i + 10); + } + return newVec; +} + +int main() +{ + std::vector vec = { 7, 5, 16, 8 }; + + print(vec); + auto newVec = add10(vec); + print(newVec); +} +``` + +When C++ Include Diagnostics are turned on, the number of times code from a header file is referenced in the current code file is displayed above the header file. It looks like this for the previous code sample: + +```cpp +6 references +#include +5 references +#include +``` + +In the code editor, select **5 references** above `#include ` and a summary of locations where code from `` is used in this file is displayed: + +:::image type="complex" source="media/visual-studio-2022-codelens-include-references.png" alt-text="A screenshot of the C++ Include Diagnostics context window showing where code from the vector header file is used."::: +The C++ Include Diagnostics context window shows that there are five places in the code where code from the vector header file is used in the current code file. For example, it's used twice on the definition of the add10 function, as a return value and parameter. It's used on line 17 in the declaration of newVec, and so on. +:::image-end::: + +Select an item to go to its location in your code. + +## View `#include` build time + +To see the build time for each file you `#include`, first build using Build Insights. + +Turn on Build Insights from the main menu bar by selecting **Build** > **Run Build Insights on Solution** > **Build**. After the build completes, a window appears to list the build times for the various files that are compiled. Return to the source code window, and the build time for each `#include` file is displayed in CodeLens. It looks similar to this: + +```cpp +6 references | Build: 0.3560s +#include +5 references | Build 0.0360s +#include +``` + +If you have an `#include` directive that is used infrequently, but significantly impacts your compile time, this tool can help you identify it. + +In this article, you've seen how to turn on C++ Include Diagnostics and CodeLens, and how to use C++ Include Diagnostics to analyze how often something from an include file is used and how an `#include` impacts build time. + +## See also + +[C/C++ Include Cleanup overview](include-cleanup-overview.md)\ +[Include Cleanup messages](include-cleanup-messages.md) \ No newline at end of file diff --git a/docs/ide/live-share-cpp.md b/docs/ide/live-share-cpp.md index ef99caa6b01..6825a02fc28 100644 --- a/docs/ide/live-share-cpp.md +++ b/docs/ide/live-share-cpp.md @@ -1,19 +1,19 @@ --- title: "Collaborate with Live Share for C++ in Visual Studio" description: "Use Live Share for C++ in Visual Studio to collaborate and share code in real time." -ms.date: "05/24/2019" +ms.date: 05/24/2019 --- # Collaborate using Live Share for C++ In Visual Studio 2019 and Visual Studio Code, you can use **Live Share** to collaborate on C++ projects in real-time. With **Live Share** another person can edit and debug your code without having to install your project or any of its dependencies. You see each other's edits as they occur, and each edit is tagged with the name of the person who made it. -![Screenshot of C plus plus Live Share Editing.](../ide/media/live-share-edit-cpp.png) +![Screenshot of C plus plus Live Share Editing. A change to the code specifying a color is highlighted and annotated with the name of the person making it.](../ide/media/live-share-edit-cpp.png) ## Live Share host and guests -In a Live Share session there is a host and one or more guests. Both host and guests can use either Visual Studio or Visual Studio Code. A Visual Studio 2019 host on Windows can share with a Visual Studio Code guest on Linux. +In a Live Share session, there's a host and one or more guests. Both host and guests can use either Visual Studio or Visual Studio Code. A Visual Studio 2019 host on Windows can share with a Visual Studio Code guest on Linux. -The host provides the guests with everything they need to be productive. Guests are not required to have the source code, compiler, external dependencies, or even the same installed components. +The host provides the guests with everything they need to be productive. Guests aren't required to have the source code, compiler, external dependencies, or even the same installed components. The host and guests can use these IntelliSense features: @@ -27,7 +27,7 @@ The host and guests can use these IntelliSense features: - Reference Highlighting - Diagnostics/Errors/Squiggles -![Screenshot of C plus plus Live Share Debugging.](../ide/media/live-share-debug-cpp.png) +![A side-by-side screenshot of a C plus plus Live Share Debugging intended to show two people seeing the debugging experience on their own screen.](../ide/media/live-share-debug-cpp.png) ## Start and end a Live Share session @@ -44,7 +44,7 @@ To end a session, select **End Collaboration Session** from the **Sharing** drop For more information about **Live Share** in Visual Studio, see [What is Visual Studio Live Share?](/visualstudio/liveshare/). For more information about Live Share in Visual Studio Code, see [ Live Share](https://marketplace.visualstudio.com/items?itemName=ms-vsliveshare.vsliveshare). -## See Also +## See also [Edit and refactor code (C++)](writing-and-refactoring-code-cpp.md)
[Navigate your C++ code base in Visual Studio](navigate-code-cpp.md)
diff --git a/docs/ide/lnt-arithmetic-overflow.md b/docs/ide/lnt-arithmetic-overflow.md index 0025e19be16..c1719c26aaf 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-logical-bitwise-mismatch.md b/docs/ide/lnt-logical-bitwise-mismatch.md index 9104b18bf1c..c501a731b4d 100644 --- a/docs/ide/lnt-logical-bitwise-mismatch.md +++ b/docs/ide/lnt-logical-bitwise-mismatch.md @@ -23,7 +23,6 @@ void example(bool a, bool b) { bool c = a & b; // Flagged: Bitwise AND operator used with Boolean variables. bool d = a || b; // OK: Logical OR operator used with Boolean variables. } - ``` Only use bitwise operators on integer values. diff --git a/docs/ide/lnt-make-member-function-const.md b/docs/ide/lnt-make-member-function-const.md new file mode 100644 index 00000000000..1e3439c952e --- /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 00000000000..d0a503be4b3 --- /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 44466eb134f..1be51a46df0 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 00000000000..c2f9f6381a5 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 00000000000..0d6eeba3ad6 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 00000000000..9a5aff92ced 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 b5499ae2f8f..775d8730a70 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 00000000000..607e6579cfa 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 00000000000..5a0f2426a23 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 00000000000..f024ebba6e7 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 00000000000..ed1386ec931 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 00000000000..2f6a11030b3 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 00000000000..34c864afe38 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 00000000000..cb77d384a59 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 00000000000..2cbdb0d3aa1 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 00000000000..57dfd9200a2 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 85284c9080d..4838fd20573 100644 --- a/docs/ide/navigate-code-cpp.md +++ b/docs/ide/navigate-code-cpp.md @@ -11,7 +11,7 @@ Visual Studio provides a suite of tools that you can use to navigate around your Right-click an `#include` directive, and select **Go To Document**. Or, select **F12** with the cursor over that line to open the file. -![Screenshot of the C plus plus Go To Document menu option.](../ide/media/go-to-document.png) +![Screenshot of the C plus plus Go To Document menu option in the context of some include statements.](media/go-to-document.png) ## Toggle Header/Code File @@ -19,17 +19,17 @@ You can switch between a header file and its corresponding source file. Right-cl ## Go To Definition/Declaration -You can navigate to the definition of a code symbol by right-clicking it in the editor and selecting **Go To Definition**, or by selecting **F12**. You can navigate to a declaration similarly by right-clicking to open the context menu, or by selecting **Ctrl+F12**. +You can navigate to the definition of a code element with a right-click in the editor and selecting **Go To Definition**, or by selecting **F12**. You can navigate to a declaration similarly by right-clicking to open the context menu, or by selecting **Ctrl+F12**. -![Screenshot of C plus plus Go To Definition.](../ide/media/go-to-def.png) +![Screenshot of options that appear when you right-click a code element. Includes Go To Definition, Peek Definition, and Go To Declaration.](media/go-to-def.png) ## Go To -**Go To** refers to a set of navigation features that each provide a specific kind of result based on filters you specify. +**Go To** refers to a set of navigation features that each provide a specific result based on filters you specify. You can open **Go To** with **Ctrl+,**. This action creates a search box over the document you're editing. -![Screenshot of C plus plus Go To.](../ide/media/go-to-cpp.png) +![Screenshot of the search box that appears when you open Go To. There's a text box for your search terms, and filters for types, recent files, etc.](media/go-to-cpp.png) **Go To** includes these search filters: @@ -47,7 +47,7 @@ You can open **Go To** with **Ctrl+,**. This action creates a search box over th - Properties and events. - **Go To Symbol** (**Ctrl 1, S**): Search results include: - Results from Go To Types and Go To Members. - - All remaining C++ language constructs, which includes macros. + - All remaining C++ language constructs, which include macros. When you first invoke **Go To** with **Ctrl +**, **Go To All** is activated (no filters on search results). You then can select the filter you want by using the buttons near the search box. You can invoke a specific filter using its corresponding keyboard shortcut. Doing so opens the **Go To** search box with that filter preselected. All keyboard shortcuts are configurable. @@ -62,11 +62,11 @@ To apply a text filter, start your search query with the filter's corresponding The following example shows results from a *Go To Files* operation by using the "f" filter: -![Screenshot of the Go to Files menu.](../ide/media/vs2017-go-to-results.png "Go To Menu") +![Screenshot of Go to Files results. The user typed 'f str' and string_utils.cpp and string_utils.h appear because they contain `str` in the name.](media/vs2017-go-to-results.png "Go To Menu") To see the list of text filters, type a ? followed by a space. You also can access the **Go To** commands with the **Edit** menu. This is another way to remind yourself of the main **Go To** keyboard shortcuts. -![Screenshot of the Go To menu.](../ide/media/go-to-menu-cpp.png "Go To Menu") +![Screenshot of the Go To menu which has options like Go To Line (Ctrl + G), Go to File (Ctrl + 1, Ctrl + F), and more.](media/go-to-menu-cpp.png "Go To Menu") ## Find or Find in Files @@ -74,15 +74,15 @@ You can run a text search for anything in your solution with **Find** (**Ctrl+F* **Find** can be scoped to a selection, the current document, all open documents, the current project, or the entire solution. You can use regular expressions and plain text. It also highlights all matches automatically in the IDE. -![Screenshot of C plus plus Find.](../ide/media/find-cpp.png) +![Screenshot of the Find dialog. The user has searched `channel`. Yellow highlights in the file show all the places `Channel` is found.](media/find-cpp.png) **Find in Files** is a more powerful version of **Find** that displays results in the **Find Results** window. You can search external code dependencies, filter by file types, and more. -![Screenshot of the Find and Replace window showing the Find in Files page.](../ide/media/find-in-files-cpp.png "Find in Files") +![Screenshot of the Find and Replace dialog. The Find in Files page is selected. Options are shown for matching case, the whole word, and so on.](media/find-in-files-cpp.png "Find in Files") You can organize **Find in Files** results in two windows. You can append results from multiple searches together. Select a result to go to that location in the file. -![Screenshot showing a Find in File search result.](../ide/media/vs2017-find-in-files-results.png "Find in Files") +![Screenshot showing a Find in Files search result listing files containing text that matches the search string and an excerpt of each match.](media/vs2017-find-in-files-results.png "Find in Files") For more information, see [Find in Files](/visualstudio/ide/find-in-files) in the Visual Studio documentation. @@ -90,9 +90,9 @@ For more information, see [Find in Files](/visualstudio/ide/find-in-files) in th To find all usages of a symbol in your codebase, place the caret in or just after the symbol, right-click, and then select **Find All References**. You can filter, sort, or group results in many different ways. Results populate incrementally. They're classified as Reads or Writes to help you see what's in your solution as opposed to system headers or other libraries. -![Screenshot of C plus plus Find all references.](../ide/media/find-all-references-results-cpp.png) +![Screenshot of Find all references results which shows the line where the symbol was found, which file and project it is located in, and so on.](media/find-all-references-results-cpp.png) -You group results by the following categories: +You can group results by the following categories: - Project then Definition - Definition Only @@ -104,13 +104,13 @@ You group results by the following categories: To filter results, hover over a column and select the filtering icon that pops up. You can filter results from the first column to hide things like string and comment references that you might not want to see. -![Screenshot of C plus plus Find all references filters.](../ide/media/find-all-references-filters-cpp.png) +![Screenshot of filtering options. Includes Confirmed, Disconfirmed, In comment, and unprocessed. Each shows how many results apply to that category.](media/find-all-references-filters-cpp.png) - **Confirmed results**: Actual code references to the symbol being searched for. For example, searching for a member function called `Size` returns all references to `Size` that match the scope of the class that defines `Size`. - **Disconfirmed results**: This filter is off by default because it shows symbols whose name matches but aren't actual references to the symbol you're searching for. For example, if you have two classes that each define a member function called `Size`, and you run a search for `Size` on a reference from an object of `Class1`, any references to `Size` from `Class2` appear as disconfirmed. -- **Unprocessed results**: **Find All References** operations can take time to complete on larger codebases, so the Results list shows "unprocessed" results here. Unprocessed results match the name of the symbol being searched for but haven't yet been confirmed as actual code references. You can turn on this filter to get faster results. Just be aware that some results might not be actual references. +- **Unprocessed results**: **Find All References** operations can take time to complete on larger codebases, so the Results list shows "unprocessed" results here. Unprocessed results match the name of the symbol being searched for but haven't yet been confirmed as actual code references. You can turn on this filter to get faster results. Some results might not be actual references. #### Sort results @@ -120,10 +120,10 @@ You can sort results by any column by selecting that column. You can swap betwee You can navigate to the definition of a type in a file, or to type members, by using the **Navigation Bar** that's above the editor window. -![Screenshot of the C plus plus Navigation Bar.](../ide/media/navbar-cpp.png) +![Screenshot of the Navigation Bar above the editor window. It shows cryptlib > ChannelSwitch > ChannelMessageSeriesEnd().](media/navbar-cpp.png) ## See also -- [Read and understand C++ code](read-and-understand-code-cpp.md)
-- [Edit and refactor C++ code](read-and-understand-code-cpp.md)
+- [Read and understand C++ code](read-and-understand-code-cpp.md) +- [Edit and refactor C++ code](read-and-understand-code-cpp.md) - [Collaborate with Live Share for C++](live-share-cpp.md) diff --git a/docs/ide/overriding-a-virtual-function-visual-cpp.md b/docs/ide/overriding-a-virtual-function-visual-cpp.md index 3f552708ee2..e681a20f791 100644 --- a/docs/ide/overriding-a-virtual-function-visual-cpp.md +++ b/docs/ide/overriding-a-virtual-function-visual-cpp.md @@ -5,6 +5,7 @@ ms.date: "11/12/2018" f1_keywords: ["vc.codewiz.virtualfunc.override"] helpviewer_keywords: ["virtual functions, overriding", "base classes, overriding virtual functions defined in", "Properties window, overriding virtual functions in"] ms.assetid: 2d8c76f2-7a6b-4c9c-8de5-4282ce7755b6 +ms.topic: how-to --- # Override a virtual function diff --git a/docs/ide/read-and-understand-code-cpp.md b/docs/ide/read-and-understand-code-cpp.md index cdc0bd5c7ed..ff4d5bdb93a 100644 --- a/docs/ide/read-and-understand-code-cpp.md +++ b/docs/ide/read-and-understand-code-cpp.md @@ -1,7 +1,8 @@ --- 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 +ms.topic: concept-article --- # Read and understand C++ code in Visual Studio @@ -11,19 +12,19 @@ The C++ code editor and Visual Studio IDE provide many coding aids. Some are uni Visual Studio colorizes syntax elements to differentiate between types of symbols such as language keywords, type names, variable names, function parameters, string literals, and so on. -![Screenshot showing code colorization in the editor.](../ide/media/code-outline-colorization.png "C++ colorization") +![Screenshot showing code colorization in the editor. Keywords are shown in different colors such as blue for if, while and green for comments](../ide/media/code-outline-colorization.png "C++ colorization") Unused code (such as code under an #if 0) is more faded in color. -![Screenshot showing inactive code in the editor.](../ide/media/inactive-code-cpp.png "C++ inactive code") +![Screenshot showing inactive code in the editor, which appears faded compared to active code.](../ide/media/inactive-code-cpp.png "C++ inactive code") -You can customize the colors by typing "Fonts" in **Quick Launch**, and then choosing **Fonts and Colors**. In the **Fonts and Colors** dialog scroll down to the C/C++ options and then choose a custom font and/or color. +You can customize the colors by typing "Fonts" in **Quick Launch**, and then choosing **Fonts and Colors**. In the **Fonts and Colors** dialog, scroll down to the C/C++ options and then choose a custom font and/or color. ## Outlining -Right-click anywhere in a source code file and choose **Outlining** to collapse or expand code blocks and/or custom regions to make it easier to browse only the code you are interested in. For more information, see [Outlining](/visualstudio/ide/outlining). +Right-click anywhere in a source code file and choose **Outlining** to collapse or expand code blocks and/or custom regions to make it easier to browse only the code you're interested in. For more information, see [Outlining](/visualstudio/ide/outlining). -![Screenshot of C plus plus Outlining.](../ide/media/vs2015_cpp_outlining.png) +![Screenshot of the outlining window shows the body of classes collapsed. Options for Collapse to Definitions, Toggle All Outlining, etc. are visible.](../ide/media/vs2015_cpp_outlining.png) When you place your cursor in front of a curly brace, '{' or '}', the editor highlights its matching counterpart. @@ -37,11 +38,11 @@ You can add line numbers to your project by going to **Tools** > **Options** > * You can zoom in or out in the editor by pressing the **Ctrl** key and scrolling with your mouse wheel. You can also zoom by using the zoom setting in the bottom left corner. -![Screenshot of the C plus plus Zoom Control.](../ide/media/zoom-control.png) +![Screenshot of the Zoom Control in the lower left of the screen. It's a dropdown with various zoom options like 133%.](../ide/media/zoom-control.png) Scrollbar **Map Mode** enables you to quickly scroll and browse through a code file without leaving your current location. You can click anywhere on the code map to go directly to that location. -![Screenshot of the Code Map in C plus plus.](../ide/media/vs2015-cpp-code-map.png) +![Screenshot of the Code Map which shows an outline of the entire file on the right and a window displaying the code from the selected part of the map.](../ide/media/vs2015-cpp-code-map.png) To turn on **Map Mode**, type "map" in the **Quick Launch** search box in the main toolbar and choose **Use scroll map mode**. For more information, see [How to: Track your code by customizing the scrollbar](/visualstudio/ide/how-to-track-your-code-by-customizing-the-scrollbar). @@ -53,13 +54,13 @@ Hover over any variable, function, or other symbol to get information about it, ::: moniker range=">=msvc-160" -![Screenshot showing the Quick Info tooltip in Visual Studio 2019.](../ide/media/quick-info-vs2019.png "Quick Info") +![Screenshot of the Quick Info tooltip displaying the definition of a function that the user is hovering over in the code window.](../ide/media/quick-info-vs2019.png "Quick Info") The **Quick Info** tooltip has a **Search Online** link. Go to **Tools** > **Options** > **Text Editor** > **C++** > **View** to specify the search provider. -If there is an error in your code, you can hover over it and **Quick Info** will display the error message. You can also find the error message in the Error List window. +If there's an error in your code, you can hover over it, and **Quick Info** will display the error message. You can also find the error message in the Error List window. -![Screenshot showing Quick Info on error.](../ide/media/quickinfo-on-error.png "Quick Info on error") +![Screenshot of the Quick Info tooltip showing the error associated with a code squiggle.](../ide/media/quickinfo-on-error.png "Quick Info on error") ::: moniker-end @@ -67,45 +68,45 @@ If there is an error in your code, you can hover over it and **Quick Info** will ![Screenshot showing the Quick Info tooltip in Visual Studio 2017.](../ide/media/quick-info.png "Quick Info") -If there is an error in your code, you can hover over it and **Quick Info** will display the error message. You can also find the error message in the **Error List** window. +If there's an error in your code, you can hover over it, and **Quick Info** will display the error message. You can also find the error message in the **Error List** window. -![Screenshot showing Quick Info on error.](../ide/media/quickinfo-on-error.png "Quick Info on error") +![Screenshot of the Quick Info tooltip showing the error associated with a code squiggle.](../ide/media/quickinfo-on-error.png "Quick Info on error") ::: moniker-end -When you call a function, **Parameter Info** shows the types of parameters and the order in which they are expected. +When you call a function, **Parameter Info** shows the types of parameters and the order in which they're expected. -![Screenshot of Parameter Info in C plus plus.](../ide/media/parameter-info.png) +![Screenshot of parameter info showing the parameters for the function resize on vector v. The parameter info is: const size_t _Newsize, const int & _Val.](../ide/media/parameter-info.png) ## Peek Definition Hover over a variable or function declaration, right-click, then choose **Peek Definition** to see an inline view of its definition without navigating away from your current location. For more information, see [Peek Definition (Alt+F12)](/visualstudio/ide/how-to-view-and-edit-code-by-using-peek-definition-alt-plus-f12). -![Screenshot of C plus plus Peek Definition.](../ide/media/vs2015_cpp_peek_definition.png) +![Screenshot of the drop-down that appears when you right-click a function. Peek Definition appears in the menu along with the shortcut Alt + F 12.](../ide/media/vs2015_cpp_peek_definition.png) ## F1 Help -Place the cursor on or just after any type, keyword or function and press **F1** to go directly to the relevant reference topic on docs.microsoft.com. **F1** also works on items in the error list, and in many dialog boxes. +Place the cursor on or just after any type, keyword or function and press **F1** to go directly to the relevant reference topic on Microsoft Learn. **F1** also works on items in the error list and in many dialog boxes. ## Class View **Class View** displays a searchable set of trees of all code symbols and their scope and parent/child hierarchies, organized on a per-project basis. You can configure what **Class View** displays from **Class View Settings** (click the gear box icon at the top of the window). -![Screenshot of Class View in C plus plus.](../ide/media/class-view.png) +![Screenshot of the Class View window displaying the classes in the project such as CipherFactory, FilterTester, and so on.](../ide/media/class-view.png) ## Generate graph of include files Right click on a code file in your project and choose **Generate graph of include files** to see a graph of which files are included by other files. -![Screenshot of C plus plus graph of include files.](../ide/media/vs2015_cpp_include_graph.png) +![Screenshot of a graph of include files. The graph shows that NAMESPACE DLL .CPP includes Namespace DLL .h, which includes V_10 .H, among other files.](../ide/media/vs2015_cpp_include_graph.png) ## View Call Hierarchy Right click on any function call and view a recursive list of all the functions that it calls, and all the functions that call it. Each function in the list can be expanded in the same way. For more information, see [Call Hierarchy](/visualstudio/ide/reference/call-hierarchy). -![Screenshot of C plus plus Call Hierarchy.](../ide/media/vs2015_cpp_call_hierarchy.png) +![Screenshot of the Call Hierarchy window which shows calls to and from Floating_to_wstring(). For example, to_wstring() calls Floating_to_wstring().](../ide/media/vs2015_cpp_call_hierarchy.png) -## See Also +## See also [Edit and refactor code (C++)](writing-and-refactoring-code-cpp.md)
[Navigate your C++ code base in Visual Studio](navigate-code-cpp.md)
diff --git a/docs/ide/refactoring/change-signature.md b/docs/ide/refactoring/change-signature.md index c6ca40fa162..e8b15f90056 100644 --- a/docs/ide/refactoring/change-signature.md +++ b/docs/ide/refactoring/change-signature.md @@ -1,14 +1,14 @@ --- description: "Learn more about: Change Signature" title: "Change Signature" -ms.date: "11/16/2016" -ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 +ms.date: "09/18/2022" +f1_keywords: ["vc.pkg.refactoring.changesignaturedlg"] --- # Change Signature **What:** Lets you modify a function's parameters. -**When:** You want to re-order, add, remove, or modify a function's parameters that is currently being used in a variety of locations. +**When:** You want to reorder, add, remove, or modify a function's parameters that are used in various locations. **Why:** You could manually change these parameters yourself, and then find all calls to that function and change them one-by-one, but that could lead to errors. This refactoring tool will perform the task automatically. @@ -16,11 +16,11 @@ ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 1. Place the text or mouse cursor inside the name of the method to modify, or one of its usages: - ![Screenshot showing highlighted code.](images/changesignature_highlight.png) + ![Screenshot of code with the mouse cursor on the function ChangeUserInfo.](images/changesignature_highlight.png) 1. Next, do one of the following: * **Keyboard** - * Press **Ctrl+R**, then **Ctrl+O**. (Note that your keyboard shortcut may be different based on which profile you've selected.) + * Press **Ctrl+R**, then **Ctrl+O**. (Your keyboard shortcut may be different depending on which profile you've selected.) * Press **Ctrl+.** to trigger the **Quick Actions and Refactorings** menu and select **Change Signature** from the context menu. * **Mouse** * Select **Edit > Refactor > Reorder Parameters**. @@ -28,23 +28,23 @@ ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 1. In the **Change Signature** dialog that pops up, you can use the buttons on the right side to change the method signature: - ![Screenshot showing the Change Signature dialog.](images/changesignature_dialog.png) + ![Screenshot of the Change Signature dialog for the ChangeName() function. Parameters are listed by name, type, and associated value, if any.](images/changesignature_dialog.png) | Button | Description | ------ | --- | **Up/Down** | Move the selected parameter up and down the list | **Add** | Add a new parameter to the list | **Remove** | Remove the selected parameter from the list - | **Modify** | Modify the selected parameter by changing its type, name, and whether it is optional, and what its injected value would be + | **Modify** | Modify the selected parameter by changing its type, name, and whether it's optional, and what its injected value would be | **Revert** | Restore the selected parameter its original state | **Revert All** | Restore all parameters to their original state > [!TIP] > Use the **Skip preview reference changes if all references are confirmed** checkbox to make the changes immediately without the preview window popping up first. - When adding or modifying a parameter, you will see the **Add Parameter** or **Edit Parameter** window. + When adding or modifying a parameter, you'll see the **Add Parameter** or **Edit Parameter** window. - ![Screenshot showing the Add Modify parameter.](images/changesignature_addmodify.png) + ![Screenshot of the Add parameter window where you can edit or set a parameter's type, name, and whether its default or optional.](images/changesignature_addmodify.png) Here, you can do the following: @@ -52,16 +52,16 @@ ms.assetid: 8daaa060-7305-4035-99d2-8b460b4f4454 | ----- | --- | **Type** | The type of the parameter (int, double, float, etc.) | **Name** | The name of the parameter - | **Optional Parameter** | Makes the parameter optionally specified + | **Optional Parameter** | Make the parameter optionally specified | **Injected Value** | The value inserted into any calls to the function where the parameter isn't specified (only valid for **Add**) | **Default value** | The value used by the function if the caller doesn't specify one (only valid for **Optional Parameters**) -1. Use the **Search scope** drop down to select if the changes will apply to the project or the entire solution. +1. Use the **Search scope** drop-down to select if the changes will apply to the project or the entire solution. -1. When you are finished, press the **OK** button to make the changes. Ensure that the changes you are requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. +1. When you're finished, press the **OK** button to make the changes. Ensure that the changes you're requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. - ![Screenshot showing the Change Signature preview.](images/changesignature_preview.png) + ![Screenshot of a Change Signature preview. Everywhere the function is called is previewed so you can verify each change.](images/changesignature_preview.png) -1. When everything looks good, click the **Apply** button and the function will be changed in your source code. +1. When everything looks good, click the **Apply** button, and the function will be changed in your source code. - ![Screenshot showing the Change Signature result.](images/changesignature_result.png) + ![Screenshot of the resulting change. The parameters to ChangeUserInfo() are now: std::string lastName, std::string firstname, int age = -1).](images/changesignature_result.png) diff --git a/docs/ide/refactoring/convert-to-raw-string-literal.md b/docs/ide/refactoring/convert-to-raw-string-literal.md index ea55cc97fa6..4657d34f5dd 100644 --- a/docs/ide/refactoring/convert-to-raw-string-literal.md +++ b/docs/ide/refactoring/convert-to-raw-string-literal.md @@ -1,30 +1,29 @@ --- description: "Learn more about: Convert to Raw String Literal" title: "Convert to Raw String Literal" -ms.date: "11/16/2016" -ms.assetid: fffbfee4-66ee-42ba-aeb9-df07fb702c51 +ms.date: "09/19/2022" --- # Convert to Raw String Literal -**What:** Lets you turn any string into a C++ raw string literal. +**What:** Turn any string into a C++ raw string literal. -**When:** You have a string with escaped characters which shouldn't be processed as escaped characters. +**When:** You have a string with escaped characters, which shouldn't be processed as escaped characters. -**Why:** You could double-escape characters, but this often leads to confusing and unreadable strings. Using raw string literals makes strings much easier to read. +**Why:** You could double-escape characters, but this often leads to confusing and strings. Raw string literals make strings much easier to read. **How:** 1. Place text or mouse cursor over the escaped string to convert. - ![Screenshot showing highlighted code.](images/stringliteral_highlight.png) + ![Screenshot of the cursor in the middle of the word quoted on the line of code that reads: auto MyString = "A \"quoted\" string".](images/stringliteral_highlight.png) 1. Next, do one of the following: * **Keyboard** * Press **Ctrl+.** to trigger the **Quick Actions and Refactorings** menu and select **Convert to Raw String Literal** from the context menu. * **Mouse** * Right-click the code, select the **Quick Actions and Refactorings** menu and select **Convert to Raw String Literal** from the context menu. - * Click the ![Lightbulb.](images/bulb.png) icon which appears in the left margin and select **Convert to Raw String Literal** from the context menu. + * Click the ![Lightbulb.](images/bulb.png) icon that appears in the left margin and select **Convert to Raw String Literal** from the context menu. 1. The string will be immediately converted into a raw string literal. - ![Raw String Literal result.](images/stringliteral_result.png) + ![Screenshot showing that the line of code now reads: auto myString = R"(A "quoted" string.)" The interior quotes are no longer escaped.](images/stringliteral_result.png) diff --git a/docs/ide/refactoring/create-declaration-definition.md b/docs/ide/refactoring/create-declaration-definition.md index ce0b0e40431..0fe31ad5743 100644 --- a/docs/ide/refactoring/create-declaration-definition.md +++ b/docs/ide/refactoring/create-declaration-definition.md @@ -1,8 +1,7 @@ --- description: "Learn more about: Create Declaration / Definition" title: "Create Declaration / Definition" -ms.date: "10/19/2018" -ms.assetid: 6b1cdcb2-765e-4b93-8cef-92b861f64eba +ms.date: "09/19/2022" --- # Create Declaration / Definition @@ -10,13 +9,13 @@ ms.assetid: 6b1cdcb2-765e-4b93-8cef-92b861f64eba **When:** You have a function that needs a declaration, or vice-versa. -**Why:** You could manually create the declaration/definition, but this will create it automatically, creating the header/code file if required. +**Why:** You could manually create the declaration/definition, but this will create it automatically, creating the header/code file if necessary. **How:** 1. Place your text or mouse cursor over the function for which you want to create the declaration or definition. - ![Screenshot showing highlighted code.](images/createdefinition_highlight.png) + ![Screenshot showing the code: void MyFunction(int x). The cursor is on MyFunction.](images/createdefinition_highlight.png) 1. Next, do one of the following: * **Keyboard** @@ -24,6 +23,6 @@ ms.assetid: 6b1cdcb2-765e-4b93-8cef-92b861f64eba * **Mouse** * Right-click and select the **Quick Actions and Refactorings** menu and select **Create Declaration / Definition** from the context menu. -1. The function's declaration/definition will be created in the source or header file, which you will see in a popup preview window. If the source or header file does not exist, it will also be created and placed in the project. +1. The function's declaration/definition will be created in the source or header file, which you'll see in a popup preview window. If the source or header file doesn't exist, it will also be created and placed in the project. - ![Create Declaration / Definition result.](images/createdefinition_result.png) + ![Screenshot showing a popup window containing the header file Source.h with the created declaration: void MyFunction(int x);.](images/createdefinition_result.png) diff --git a/docs/ide/refactoring/extract-function.md b/docs/ide/refactoring/extract-function.md index 6dd777335f9..91a9fc7d797 100644 --- a/docs/ide/refactoring/extract-function.md +++ b/docs/ide/refactoring/extract-function.md @@ -1,36 +1,36 @@ --- description: "Learn more about: Extract Function" title: "Extract Function" -ms.date: "11/16/2016" -ms.assetid: e31d1249-9705-4511-acbd-9f6fe73bdf2d +ms.date: "09/18/2022" +f1_keywords: ["vc.pkg.refactoring.extractfuncdlg"] --- # Extract Function -**What:** Lets you turn a fragment of code into its own function. +**What:** Turn a fragment of code into its own function. **When:** You have a fragment of existing code in some function that needs to be called from another function. -**Why:** You could copy/paste that code, but that would lead to duplication. A better solution is to refactor that fragment into its own function which can be called freely by any other function. +**Why:** You could copy/paste that code, but that would lead to duplication. A better solution is to refactor that fragment into its own function, which can be called by any other function. **How:** 1. Highlight the code to be extracted: - ![Screenshot showing highlighted code.](images/extractfunction_highlight.png) + ![Screenshot showing the following code that is highlighted prepartory to being extracted: double area = M_PI * readious * radious;.](images/extractfunction_highlight.png) 1. Next, do one of the following: * **Keyboard** - * Press **Ctrl+R**, then **Ctrl+M**. (Note that your keyboard shortcut may be different based on which profile you've selected.) + * Press **Ctrl+R**, then **Ctrl+M**. (Your keyboard shortcut may be different depending on which profile you've selected.) * Press **Ctrl+.** to trigger the **Quick Actions and Refactorings** menu and select **Extract Function (Experimental)** from the context menu. * **Mouse** * Select **Edit > Refactor > Extract Function (Experimental)**. * Right-click the code, select the **Quick Actions and Refactorings** menu and select **Extract Function (Experimental)** from the context menu. - * Click the ![Lightbulb.](images/bulb.png) icon which appears in the left margin and select **Extract Function (Experimental)** from the context menu. + * Click the ![Lightbulb.](images/bulb.png) icon that appears in the left margin and select **Extract Function (Experimental)** from the context menu. 1. In the **Extract Function/Method (Experimental)** window, enter the new function name, select where you want the code to be placed, and click the **OK** button. - ![Extract function dialog.](images/extractfunction_dialog.png) + ![Screenshot of the extract function dialog which takes the function name and whether to create it above or below the current function.](images/extractfunction_dialog.png) 1. The new function will be created where you specified, a function prototype in the corresponding header file, and the original code will be changed to call that function. - ![Extract function result.](images/extractfunction_result.png) + ![Screenshot of the created function that contains the extracted code. The definition is void CalculateArea(double radius).](images/extractfunction_result.png) diff --git a/docs/ide/refactoring/images/changesignature_dialog.png b/docs/ide/refactoring/images/changesignature_dialog.png index c90b13a54ea..c4d48f38773 100644 Binary files a/docs/ide/refactoring/images/changesignature_dialog.png and b/docs/ide/refactoring/images/changesignature_dialog.png differ diff --git a/docs/ide/refactoring/images/extractfunction_dialog.png b/docs/ide/refactoring/images/extractfunction_dialog.png index 99a47848a5f..72a8235aaa7 100644 Binary files a/docs/ide/refactoring/images/extractfunction_dialog.png and b/docs/ide/refactoring/images/extractfunction_dialog.png differ diff --git a/docs/ide/refactoring/implement-pure-virtuals.md b/docs/ide/refactoring/implement-pure-virtuals.md index de4fdbfe6bc..5ee582745ad 100644 --- a/docs/ide/refactoring/implement-pure-virtuals.md +++ b/docs/ide/refactoring/implement-pure-virtuals.md @@ -1,12 +1,11 @@ --- description: "Learn more about: Implement Pure Virtuals" title: "Implement Pure Virtuals" -ms.date: "11/16/2016" -ms.assetid: ea9b4719-34a3-474a-b4ec-05b1859f80f1 +ms.date: "09/19/2022" --- # Implement Pure Virtuals -**What:** Lets you immediately generate the code required to implement all pure virtual methods in a class. +**What:** Generate the code required to implement all pure virtual methods in a class. **When:** You want to inherit from a class with pure virtual functions. @@ -16,7 +15,7 @@ ms.assetid: ea9b4719-34a3-474a-b4ec-05b1859f80f1 1. Place your text or mouse cursor over the class in which you want to implement the pure virtual functions of the base class. - ![Screenshot showing highlighted code.](images/virtuals_highlight.png) + ![Screenshot of a class that has two pure virtual functions named Method1 and Method2. An empty class named MyInheritedClass derives from it.](images/virtuals_highlight.png) 1. Next, do one of the following: * **Keyboard** @@ -26,4 +25,4 @@ ms.assetid: ea9b4719-34a3-474a-b4ec-05b1859f80f1 1. The pure virtual method signatures will be created automatically, ready to be implemented. - ![Implement Pure Virtuals result.](images/virtuals_result.png) + ![Screenshot of MyInheritedClass which now has 2 virtual method definitions that match the names and signatures of the declarations in the base class.](images/virtuals_result.png) diff --git a/docs/ide/refactoring/move-definition-location.md b/docs/ide/refactoring/move-definition-location.md index 2336e86efdf..5ee8c82f8b1 100644 --- a/docs/ide/refactoring/move-definition-location.md +++ b/docs/ide/refactoring/move-definition-location.md @@ -1,22 +1,21 @@ --- description: "Learn more about: Move Definition Location" title: "Move Definition Location" -ms.date: "11/16/2016" -ms.assetid: c6d507ac-c61e-4da2-95c8-d504b42e2520 +ms.date: "09/19/2022" --- # Move Definition Location -**What:** Lets you immediately move a function definition to the corresponding header file. +**What:** Move a function definition to the corresponding header file. **When:** You have a function that you want to move to a header file. -**Why:** You could manually move the function, but this feature will move it automatically, creating the header file if required. +**Why:** You could manually move the function, but this feature will move it automatically, and create the header file if necessary. **How:** 1. Place your text or mouse cursor over the function for which you want to move. - ![Screenshot showing highlighted code.](images/movedefinition_highlight.png) + ![Screenshot of a function, with the cursor on the function name.](images/movedefinition_highlight.png) 1. Next, do one of the following: * **Keyboard** @@ -24,6 +23,6 @@ ms.assetid: c6d507ac-c61e-4da2-95c8-d504b42e2520 * **Mouse** * Right-click and select the **Quick Actions and Refactorings** menu and select **Move Definition Location** from the context menu. -1. The function will be moved to the corresponding header file, which you will see in a popup preview window. If the header file does not exist, it will also be created and placed in the project. +1. The function will be moved to the corresponding header file, which you'll see in a popup preview window. If the header file doesn't exist, it will also be created and placed in the project. - ![Create Declaration / Definition result.](images/movedefinition_result.png) + ![Screenshot of a pop-up window containing a header file that the function was moved to.](images/movedefinition_result.png) diff --git a/docs/ide/refactoring/rename.md b/docs/ide/refactoring/rename.md index a01c365f10c..69bf660156c 100644 --- a/docs/ide/refactoring/rename.md +++ b/docs/ide/refactoring/rename.md @@ -1,39 +1,39 @@ --- description: "Learn more about: Rename" title: "Rename" -ms.date: "11/16/2016" -ms.assetid: 64b42a88-3bd9-4399-8b96-75bceffc353b +ms.date: "09/19/2022" +f1_keywords: ["vc.pkg.refactoring.renamedlg"] --- # Rename -**What:** Lets you rename identifiers for code symbols, such as fields, local variables, methods, namespaces, properties and types. +**What:** Rename identifiers for code symbols such as fields, local variables, methods, namespaces, properties and types. **When:** You want to safely rename something without having to find all instances, and copy/paste the new name. -**Why:** Copy and pasting the new name across an entire project would likely result in errors. This refactoring tool will accurately perform the renaming action. +**Why:** Copy and pasting the new name across an entire project could result in errors. This feature accurately performs the rename. **How:** 1. Highlight or place the text cursor inside the item to be renamed: - ![Screenshot showing highlighted code.](images/rename_highlight.png) + ![Screenshot showing the variable r highlighted. The line reads: double r = 1.23;.](images/rename_highlight.png) 1. Next, do one of the following: * **Keyboard** - * Press **Ctrl+R**, then **Ctrl+R**. (Note that your keyboard shortcut may be different based on which profile you've selected.) + * Press **Ctrl+R**, then **Ctrl+R**. (Your keyboard shortcut may be different depending on which profile you've selected.) * **Mouse** * Select **Edit > Refactor > Rename**. * Right-click the code and select **Rename**. 1. In the **Rename** window that pops up, enter the new name for the selected item and click the **Preview** button. Change the **Search scope** if you need to widen or narrow the scope of the renaming. - ![Rename dialog.](images/rename_dialog.png) + ![Screenshot of the Rename dialog. It asks for the new name of the symbol and allows you to specify the scope of the changes.](images/rename_dialog.png) > [!TIP] > You can skip the preview by checking the **Skip preview changes if references are all confirmed** option. -1. When the **Preview Changes - Rename** window appears, ensure that the changes you are requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. +1. When the **Preview Changes - Rename** window appears, ensure that the changes you're requesting are being made appropriately. Use the checkboxes in the top half of the window to enable or disable the renaming of any item. - ![Rename preview.](images/rename_preview.png) + ![Screenshot of the rename preview dialog which shows the proposed changes and allows you to deselect those you don't want.](images/rename_preview.png) -1. When everything looks good, click the **Apply** button and the item will be renamed in your source code. +1. When everything looks good, click the **Apply** button, and the item will be renamed in your source code. diff --git a/docs/ide/toc.yml b/docs/ide/toc.yml index a149cbb552d..0b58b7607e9 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 @@ -79,7 +93,7 @@ items: - name: Add a method href: ../ide/adding-a-method-visual-cpp.md - name: Add an IDL method - href: ../ide/add-interface-definition-library-method-wizard.md + href: ../ide/add-interface-definition-library-method-wizard.md - name: Add a property href: ../ide/adding-a-property-visual-cpp.md - name: Add an IDL property diff --git a/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md b/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md index 330552cf38a..5f115d743cc 100644 --- a/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md +++ b/docs/ide/using-the-visual-studio-ide-for-cpp-desktop-development.md @@ -4,6 +4,7 @@ title: "Using the Visual Studio IDE for C++ Desktop Development" ms.date: "04/25/2019" helpviewer_keywords: ["IDE [C++]", "Visual Studio IDE [C++]"] ms.assetid: d985c230-8e81-49d6-92be-2db9cac8d023 +ms.topic: concept-article --- # Using the Visual Studio IDE for C++ Desktop Development @@ -15,7 +16,7 @@ If you haven't installed Visual Studio yet, now is the time. For download links These walkthroughs assume that you've installed Visual Studio and the C++ components required for Windows Desktop development. We also assume you understand the fundamentals of the C++ language. If you need to learn C++, there are many books and web resources available. One good place to start is the [Get Started](https://isocpp.org/get-started) page of the Standard C++ Foundation website. -In general, we highly recommend that you use the latest version of Visual Studio even if you need to compile your code using an earlier version of the compiler toolset. For more information, see [Use native multi-targeting in Visual Studio to build old projects](../porting/use-native-multi-targeting.md). +In general, we highly recommend that you use the latest version of Visual Studio even if you need to compile your code using an earlier version of the Microsoft C++ (MSVC) Build Tools. For more information, see [Use native multi-targeting in Visual Studio to build old projects](../porting/use-native-multi-targeting.md). Once your Visual Studio installation is complete, you are ready to continue. @@ -35,7 +36,7 @@ To get started using the Visual Studio IDE to build C++ apps, work through each ## Next steps -Once you've completed these walkthroughs, you're ready to start building your own projects. For more information and resources for C++ development, see [Visual C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md). +Once you've completed these walkthroughs, you're ready to start building your own projects. For more information and resources for C++ development, see [Microsoft C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md). ## See also diff --git a/docs/ide/visualize-macro-expansion.md b/docs/ide/visualize-macro-expansion.md new file mode 100644 index 00000000000..fffabf0ef07 --- /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 44cdf605b43..366b51534ee 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 0bb96cb8a3b..990ce0c8d2e 100644 --- a/docs/ide/walkthrough-working-with-projects-and-solutions-cpp.md +++ b/docs/ide/walkthrough-working-with-projects-and-solutions-cpp.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Walkthrough: Working with Projects and Solutions (C++)" title: "Walkthrough: Working with Projects and Solutions (C++)" -ms.date: 10/27/2021 +ms.date: 02/23/2023 helpviewer_keywords: ["solutions [C++]", "projects [C++], about projects", "projects [C++]", "solutions [C++], about solutions"] ms.assetid: 93a3f290-e294-46e3-876e-e3084d9ae833 --- @@ -19,7 +19,7 @@ It helps if you understand the fundamentals of the C++ language, and know what a ## Create a project -To create a project, first choose a project-type template. For each project type, Visual Studio sets compiler settings and—depending on the type—generates starter code that you can modify later. The following steps vary depending on which version of Visual Studio you are using. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. +To create a project, first choose a project-type template. For each project type, Visual Studio sets compiler settings and—depending on the type—generates starter code that you can modify later. The following steps vary depending on which version of Visual Studio you're using. To see the documentation for your preferred version of Visual Studio, use the **Version** selector control. It's found at the top of the table of contents on this page. ::: moniker range=">=msvc-160" @@ -49,7 +49,7 @@ To create a project, first choose a project-type template. For each project type 1. In the left pane of the **New Project** dialog box, expand **Installed** and select **Visual C++**, if it isn't open already. -1. In the list of installed templates in the center pane, select **Windows Console Application**. +1. In the list of installed templates in the center pane, select **Console App**. 1. Enter a name for the project in the **Name** box. For this example, enter *Game*. @@ -79,7 +79,11 @@ To create a project, first choose a project-type template. For each project type When you create a project, Visual Studio puts the project in a solution. By default, the solution has the same name as the project. You can change the name in the **Solution name** box, but for this example, keep the default name. -1. Choose the **OK** button to create the project. +1. Choose the **OK** button to dismiss the **New Project** dialog and start the **Win32 Application Wizard**. + +1. In the wizard, choose the **Next** button. On the **Application Settings** page, under **Additional options**, clear the **Precompiled header** check box. + +1. Choose the **Finish** button to create the project. Visual Studio creates your new solution and project files, and opens the editor for the Game.cpp source code file it generated. @@ -99,7 +103,7 @@ This part of the walkthrough shows how to add a class to the project. When you a 1. In the **Add Class** dialog, enter *Cardgame* in the **Class Name** box. Don't modify the default file names and settings. Choose the **OK** button. - Visual Studio creates new files and adds them to your project. You can see them in the **Solution Explorer** window. The Cardgame.h and Cardgame.cpp files are opened in the editor. + Visual Studio creates new files and adds them to your project. You can see them in the **Solution Explorer** window. Visual Studio opens the Cardgame.h and Cardgame.cpp files in the editor. 1. Edit the Cardgame.h file, and make these changes: @@ -120,12 +124,12 @@ This part of the walkthrough shows how to add a class to the project. When you a `Cardgame(int players);` - - After the default destructor, add an inline declaration for a `static int` member function named *GetParticipants* that takes no parameters and returns the `totalParticipants` value. + - After the default destructor, add an inline declaration for a `static int` member function named `GetParticipants` that takes no parameters and returns the `totalParticipants` value. `static int GetParticipants() { return totalParticipants; }` - The Cardgame.h file should resemble the code below after you change it: + The Cardgame.h file should resemble this code after you change it: @@ -142,7 +146,7 @@ This part of the walkthrough shows how to add a class to the project. When you a }; ``` - The line `#pragma once` tells the compiler to include the header file only one time. For more information, see [once](../preprocessor/once.md). For information about other C++ keywords in the header file above, see [class](../cpp/class-cpp.md), [int](../cpp/fundamental-types-cpp.md), [static](../cpp/storage-classes-cpp.md), and [public](../cpp/public-cpp.md). + The line `#pragma once` tells the compiler to include the header file only one time. For more information, see [`once`](../preprocessor/once.md). For information about other C++ keywords in the header file, see [`class`](../cpp/class-cpp.md), [`int`](../cpp/fundamental-types-cpp.md), [`static`](../cpp/storage-classes-cpp.md), and [`public`](../cpp/public-cpp.md). 1. Choose the **Cardgame.cpp** tab at the top of the editing pane to open it for editing. @@ -151,7 +155,6 @@ This part of the walkthrough shows how to add a class to the project. When you a ```cpp - #include "pch.h" // remove this line in Visual Studio 2019 #include "Cardgame.h" #include @@ -164,7 +167,7 @@ This part of the walkthrough shows how to add a class to the project. When you a { totalParticipants += players; cout << players << " players have started a new game. There are now " - << totalParticipants << " players in total." << endl; + << totalParticipants << " players in total.\n"; } Cardgame::~Cardgame() @@ -189,7 +192,6 @@ Add some code to your app that tests the new functions. // Game.cpp : Defines the entry point for the console application. // - #include "pch.h" // remove this line in Visual Studio 2019 #include "Cardgame.h" #include diff --git a/docs/ide/writing-and-refactoring-code-cpp.md b/docs/ide/writing-and-refactoring-code-cpp.md index d68c9dec492..cfb3dbfdead 100644 --- a/docs/ide/writing-and-refactoring-code-cpp.md +++ b/docs/ide/writing-and-refactoring-code-cpp.md @@ -1,8 +1,7 @@ --- title: "Edit and refactor C++ code in Visual Studio" description: "Use the C++ code editor in Visual Studio to format, navigate, understand and refactor your code." -ms.date: "05/31/2019" -ms.assetid: 56ffb9e9-514f-41f4-a3cf-fd9ce2daf3b6 +ms.date: 09/20/2022 ms.topic: "overview" ms.custom: intro-overview --- @@ -14,24 +13,24 @@ Visual Studio provides several tools to help you write, edit, and refactor your IntelliSense is a powerful code completion tool that suggests symbols and code snippets for you as you type. C++ IntelliSense in Visual Studio runs in real time, analyzing your codebase as you update it and providing recommendations. As you type more characters, the list of recommended results narrows down. -![Screenshot of the C plus plus member list drop down.](../ide/media/cpp-statement-completion.png) +![Screenshot of the C plus plus member list drop down showing the methods available for string such as append, assign, and so on.](../ide/media/cpp-statement-completion.png) -Some symbols are omitted automatically to help narrow down the results. For example, when accessing a class object's members from outside the class, you will not be able to see private members by default, or protected members (if you are not in the context of a child class). You can adjust the filtering by using the buttons at the bottom. +Some symbols are omitted automatically to help narrow down the results. For example, when accessing a class object's members from outside the class, you won't be able to see private members by default, or protected members (if you aren't in the context of a child class). You can adjust the filtering by using the buttons at the bottom. After you choose the symbol from the drop-down list, you can autocomplete it with **Tab**, **Enter**, or one of the other commit characters (by default: `{ } [ ] ( ) . , : ; + - * / % & | ^ ! = ? @ # \`). To add or remove characters from this list, search for "IntelliSense" in **Quick Launch** (Ctrl + Q) and choose the **Text Editor > C/C++ > Advanced** option. The **Member List Commit Characters** option enables you to customize the list with the changes you want. -The **Member List Filter Mode** option controls what kinds of IntelliSense autocomplete suggestions you see. By default, it is set to **Fuzzy**. In a fuzzy search, if you have a symbol called *MyAwesomeClass*, you can type "MAC" and find the class in your autocomplete suggestions. The fuzzy algorithm sets a minimum threshold that symbols must meet to show up in the list. **Smart** filtering displays all symbols containing substrings that match what you typed. **Prefix** filtering searches for strings that begin with what you typed. +The **Member List Filter Mode** option controls what kinds of IntelliSense autocomplete suggestions you see. By default, it's set to **Fuzzy**. In a fuzzy search, if you have a symbol called *MyAwesomeClass*, you can type "MAC" and find the class in your autocomplete suggestions. The fuzzy algorithm sets a minimum threshold that symbols must meet to show up in the list. **Smart** filtering displays all symbols containing substrings that match what you typed. **Prefix** filtering searches for strings that begin with what you typed. -For more information about C++ IntelliSense, see [Visual C++ IntelliSense](/visualstudio/ide/visual-cpp-intellisense) and [Configure a C++ project for IntelliSense](/visualstudio/ide/visual-cpp-intellisense-configuration). +For more information about C++ IntelliSense, see [Visual Studio C++ IntelliSense](/visualstudio/ide/visual-cpp-intellisense) and [Configure a C++ project for IntelliSense](/visualstudio/ide/visual-cpp-intellisense-configuration). ## IntelliCode IntelliCode is AI-assisted IntelliSense. It puts the most likely candidate at the top of your completion list. IntelliCode recommendations are based on thousands of open source projects on GitHub each with over 100 stars. When combined with the context of your code, the completion list is tailored to promote common practices. -When writing C++, IntelliCode will assist when using popular libraries such as the C++ Standard Library. The context of your code is used to provide the most useful recommendations first. In the following example, the `size` member function is commonly used with the `sort` function, so it is surfaced to the top of the results list. +When writing C++, IntelliCode will assist when using popular libraries such as the C++ Standard Library. The context of your code is used to provide the most useful recommendations first. In the following example, the `size` member function is commonly used with the `sort` function, so it's surfaced to the top of the results list. -![Screenshot of C plus plus IntelliCode.](../ide/media/intellicode-cpp.png) +![Screenshot of C plus plus IntelliCode dropdown which shows the members of the vector class sorted by which are most commonly used in your code.](../ide/media/intellicode-cpp.png) ::: moniker range=">=msvc-160" @@ -47,7 +46,7 @@ In Visual Studio 2017, IntelliCode is available as an extension in the Visual St ## Predictive IntelliSense (Experimental) -**Predictive IntelliSense** is an experimental feature that uses contextual awareness to limit the number of results displayed in the IntelliSense dropdown list. The algorithm applies type matching so that it shows only those results that match the expected type. In the simplest case, if you type `int x =` and invoke the IntelliSense dropdown, you will see only integers or functions returning integers. This feature is off by default because it is still in development. It works best with global symbols; member functions are not yet supported. You can turn it on by typing "Predictive" in **Quick Launch** or by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Experimental** > **Enable Predictive IntelliSense**. +**Predictive IntelliSense** is an experimental feature that uses contextual awareness to limit the number of results displayed in the IntelliSense dropdown list. The algorithm applies type matching so that it shows only those results that match the expected type. In the simplest case, if you type `int x =` and invoke the IntelliSense dropdown, you will see only integers or functions returning integers. This feature is off by default because it's still in development. It works best with global symbols; member functions aren't yet supported. You can turn it on by typing "Predictive" in **Quick Launch** or by going to **Tools** > **Options** > **Text Editor** > **C/C++** > **Experimental** > **Enable Predictive IntelliSense**. To override **Predictive IntelliSense** and show the longer list, press **Ctrl + J**. If **Predictive IntelliSense** is on, invoking **Ctrl + J** removes the Predictive filter. Pressing **Ctrl + J** again removes the accessibility filter from Member List results where relevant. The ([+]) button under the IntelliSense dropdown list does the same thing as **Ctrl + J**. Hover over the button to see tooltip information about what is being shown. @@ -62,39 +61,37 @@ The preceding screenshot shows several buttons under the dropdown list. These en - Enums - Namespaces -A button is displayed only if it is relevant to your current IntelliSense session. You typically do not see all the buttons at the same time. +A button is displayed only if it's relevant to your current IntelliSense session. You typically don't see all the buttons at the same time. ## Template IntelliSense -When the caret is inside a template definition, a **Template Bar** appears, which enables you to provide sample template arguments for IntelliSense. +The template bar is a UI element that appears when your cursor is on a template definition. It's useful because you can provide sample template arguments for intellisense that will appear when you edit the template body. For example, you could specify that a template argument is of type `std::vector`. Then, when you use that argument in the template body, you'll see the members of `std::vector`in intellisense. -![Screenshot of C plus plus Template IntelliSense Show Existing Instantiations.](../ide/media/template-intellisense-cpp-1.png) +![Screenshot of the template bar which has the Add All Existing Instantiations option highlighted.](../ide/media/template-intellisense-cpp-1.png) -Click the **\** icon to expand/collapse the **Template Bar**. Click the pencil icon or double-click the **Template Bar** to open the **Edit** window. +Click the **\** icon to expand/collapse the **Template Bar**. Click the pencil icon or double-click the **Template Bar** to open the **Edit** window where you specify argument types for the parameters. -![Screenshot of C plus plus Template IntelliSense.](../ide/media/template-intellisense-cpp-3.png) +![Screenshot of the editing experience inside the template bar where you enter a type for each template parameter.](../ide/media/template-intellisense-cpp-3.png) -Edits that you make in the window are applied directly to the source code, so that you can see the effects in real time. +The Template Bar can auto-populate parameter types based on instantiations of the template in your code. Click on **Add All Existing Instantiations** to see a list of all concrete arguments that have been used to instantiate the template throughout your code base. -The Template Bar can auto-populate candidates based on instantiations in your code. Click on **Add All Existing Instantiations** to see a list of all concrete arguments that have been used to instantiate the template throughout your code base. +![Screenshot of the Template IntelliSense Results listing the different types used to instantiate template parameter C such as C = AmbientLight, C = Candle, and others.](../ide/media/template-intellisense-cpp-2.png) -![Screenshot of C plus plus Template IntelliSense Results List.](../ide/media/template-intellisense-cpp-2.png) +A window at the bottom of the editor shows where each instantiation was found, and what its arguments were. You can select an instantiation to go to the location in your code where that instantiation was found. -A window at the bottom of the editor shows where each instantiation was found, and what its arguments were. +![Screenshot of the list of instantiations of the template in your code. The instantion, file, location, and arguments are listed.](../ide/media/template-intellisense-cpp-4.png) -![Screenshot of C plus plus Template IntelliSense Instantiation Map.](../ide/media/template-intellisense-cpp-4.png) - -**Template Bar** information is treated as user-specific. It is stored in the .vs folder and is not committed to source control. +**Template Bar** information is user-specific. It's stored in the `.vs` folder and isn't committed to source control. ## Error squiggles and quick fixes If the editor detects problems with your code, it will add colored squiggles under the problem. Red squiggles indicate code that won't compile. Green squiggles indicate other kinds of problems that might still be potentially serious. You can open the **Error List** window to get more information about the problems. -For some kinds of errors, as well as common coding patterns, the editor will offer a **Quick Fix** in the form of a light bulb that appears when you hover over the squiggle. Click the down arrow to see the suggestions. +For some kinds of errors, and common coding patterns, the editor will offer a **Quick Fix** in the form of a light bulb that appears when you hover over the squiggle. Click the down arrow to see the suggestions. In the following example, a `vector` was declared but no definition was found, so the editor offers to include the necessary header file: -![Screenshot showing error squiggles and the quick fix that the editor offers.](../ide/media/quick-fix-for-header-cpp.png "C++ Quick Fix") +![Screenshot of an error and the proposed quick fix to # include vector.](../ide/media/quick-fix-for-header-cpp.png "C++ Quick Fix") The editor also offers Quick Fixes for some refactoring opportunities. For example, if you declare a class in a header file, Visual Studio will offer to create a definition for it in a separate .cpp file. @@ -104,7 +101,7 @@ The editor also offers Quick Fixes for some refactoring opportunities. For examp Whenever you make a change to a file, a yellow bar appears on the left to indicate that unsaved changes were made. When you save the file, the bar turns green. The green and yellow bars are preserved as long as the document is open in the editor. They represent the changes that were made since you last opened the document. -![Screenshot of C plus plus change tracking.](../ide/media/change-tracking-cpp.png) +![Screenshot of C plus plus change tracking. A yellow bar down the left appears to indicate changes.](../ide/media/change-tracking-cpp.png) ## Move code @@ -112,19 +109,21 @@ You can move lines of code up and down by selecting them, holding down Alt, and ## Insert snippets -A snippet is a predefined piece of source code. Right-click on a single point or on selected text to either insert a snippet or surround the selected text with the snippet. The following illustration shows the three steps to surround a selected statement with a for loop. The yellow highlights in the final image are editable fields that you access with the tab key. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). +A snippet is a predefined piece of source code. Right-click on a single point or on selected text and select Snippet to either insert a snippet or surround the selected text with the snippet. The following illustration shows the three steps to surround a selected statement with a for loop. The yellow highlights in the final image are editable fields that you access with the tab key. For more information, see [Code Snippets](/visualstudio/ide/code-snippets). -![Screenshot of C plus plus Insert Snippet Drop down control.](../ide/media/vs2015_cpp_surround_with.png) +:::image type="complex" source="../ide/media/vs2015_cpp_surround_with.png" alt-text="Screenshot of the Insert Snippet Drop down control."::: +A function is selected. In the dropdown that appears after a right-click on the function name, Surround With... is highlighted in yellow. In the Surround With: dropdown, the snippet for a `for` loop is selected. This results in putting a for loop around the function. The loop variable and limit are shown in yellow to indicate that they are editable fields. +:::image-end::: ## Add Class Add a new class from the **Project** menu, or from the context menu in **Solution Explorer**: -![Add New Class in C plus plus.](../ide/media/vs2017-add-class.png) +![Screenshot of the Add New Class dialog. It has fields for the class name, accessibility, files to put the declaration and implementation, and so on.](../ide/media/vs2017-add-class.png) You can also use Class Wizard to modify or examine an existing class. -![C plus plus Class Wizard.](../ide/media/vs2017-class-wizard.png) +![Screenshot of the Class Wizard which has options for adding methods, member variables, and much more.](../ide/media/vs2017-class-wizard.png) For more information, see [Adding Functionality with Code Wizards (C++)](../ide/adding-functionality-with-code-wizards-cpp.md). @@ -151,35 +150,35 @@ Visual Studio 2017 and later comes with built-in support for [ClangFormat](https - WebKit - Visual Studio -You can also provide your own .clang-format or _clang-format file to apply custom rules to all code files at the same level or below. +You can also provide your own `.clang-format` or `_clang-format` file to apply custom rules to all code files at the same level or below. The files are easily shareable via source control, so you can enforce coding conventions across your whole development team. -![Screenshot showing C plus plus Clang Format.](../ide/media/clang-format-cpp.png) +![Screenshot showing a .clang-format file which has many options such as the column limit, indent width, tab width, and so on.](../ide/media/clang-format-cpp.png) Visual Studio 2017 and later also supports [EditorConfig](https://editorconfig.org/), which works in a similar way. ClangFormat, however, has more style options than EditorConfig, including rules that are specific to C++. With **EditorConfig**, you create **.editorconfig** files and place them in different folders of your codebase to specify code styles for those folders and their subfolders. An **.editorconfig** file supersedes any other **.editorconfig** files in parent folders and overwrites any formatting settings configured via **Tools** > **Options**. You can set rules for tabs vs. spaces, indent size, and more. For more information, see [Create portable, custom editor settings with EditorConfig](/visualstudio/ide/create-portable-custom-editor-options). ## Other formatting options -The **Quick Launch** search box provides the fastest way to find a setting or tool. It is located on the main menu. Just start typing and the auto-completion list will filter the results. +The **Quick Launch** search box provides the fastest way to find a setting or tool. It's located on the main menu. Just start typing and the auto-completion list will filter the results. -![Screenshot showing Visual Studio Quick Launch.](../ide/media/vs2015_cpp_quick_launch.png "Quick Launch") +![Screenshot of the Quick Launch search box. It shows searching C plus plus advanced which results in options for the text editor.](../ide/media/vs2015_cpp_quick_launch.png "Quick Launch") To set formatting options such as indents, brace completion, and colorization, type "C++ Formatting" into the **Quick Launch** window. -![Screenshot showing C++ formatting options.](media/cpp-formatting-options.png) +![Screenshot showing C++ formatting options such as whether to automatically indent when you type a tab.](media/cpp-formatting-options.png) Other formatting options are found under **Edit** > **Advanced** in the main menu. -![Screenshot showing C++ advanced editing options.](media/edit-advanced-cpp.png) +![Screenshot showing advanced editing options such a viewing white space, word wrap, commenting a selection, increasing line indent, and more.](media/edit-advanced-cpp.png) Options for enabling and configuring C++-specific editing features are located under **Tools** > **Options** > **Text Editor** > **C/C++**. After choosing which option you want to set, you can get more help by pressing **F1** when the dialog is in focus. For general code formatting options, type `Editor C++` into **Quick Launch**. -![Screenshot showing Visual Studio Tools > Options dialog editor options.](../ide/media/tools-options.png "Editor options") +![Screenshot showing the Visual Studio menu item Tools selected, and the Options menu item highlighted.](../ide/media/tools-options.png "Editor options") Experimental features, which may or may not be included in a future version of Visual Studio, are found in the [Text Editor C++ Experimental](/visualstudio/ide/reference/options-text-editor-c-cpp-experimental) dialog. In Visual Studio 2017 and later you can enable **Predictive IntelliSense** in this dialog. -## See Also +## See also [Read and understand C++ code](read-and-understand-code-cpp.md)
[Navigate your C++ code base in Visual Studio](navigate-code-cpp.md)
diff --git a/docs/index.yml b/docs/index.yml index cb91f700a04..a2bdc2a4d8b 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -1,16 +1,16 @@ ### 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 - ms.date: 06/04/2020 + author: tylermsft + ms.author: twhitney + ms.date: 11/06/2025 ms.custom: intro-landing-hub # highlightedContent section (optional) @@ -118,7 +118,7 @@ conceptualContent: - text: Use C++ on Linux url: https://code.visualstudio.com/docs/cpp/config-linux itemType: tutorial - - text: Use C++ on MacOS + - text: Use C++ on macOS url: https://code.visualstudio.com/docs/cpp/config-clang-mac itemType: tutorial @@ -127,19 +127,19 @@ tools: title: Languages and frameworks items: - title: C++ - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: cpp/index.yml - title: C - imageSrc: https://docs.microsoft.com/media/logos/logo_C.svg + imageSrc: /media/logos/logo_C.svg url: c-language/index.yml - title: Microsoft Assembler imageSrc: media/index/logo-asm.svg url: intrinsics/index.yml - title: C++/CX for Windows Runtime - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: cppcx/visual-c-language-reference-c-cx.md - title: C++/CLI for .NET - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md - title: Active Template Library (ATL) imageSrc: media/index/logo-atl.svg @@ -148,7 +148,7 @@ tools: imageSrc: media/index/logo-mfc.svg url: mfc/mfc-desktop-applications.md - title: C++/WinRT for Windows Runtime - imageSrc: https://docs.microsoft.com/media/logos/logo_Cplusplus.svg + imageSrc: /media/logos/logo_Cplusplus.svg url: /windows/uwp/cpp-and-winrt-apis/ # additionalContent section (optional) @@ -164,16 +164,20 @@ additionalContent: - text: Universal Windows Platform development url: cppcx/universal-windows-apps-cpp.md - text: Windows Desktop development - url: ./windows/desktop-applications-visual-cpp.md + url: windows/overview-of-windows-programming-in-cpp.md - text: Linux development url: linux/index.yml + - text: Embedded development + url: embedded/index.yml - text: Mobile development url: cross-platform/index.yml - text: Game development - url: /windows/uwp/gaming/e2e/ + url: /visualstudio/gamedev/ # Card - title: Features links: + - text: Build reliable and secure programs + url: code-quality/build-reliable-secure-programs.md - text: Edit and refactor code url: ide/writing-and-refactoring-code-cpp.md - text: Build code projects @@ -201,7 +205,11 @@ additionalContent: url: parallel/parallel-programming-in-visual-cpp.md - text: Cloud and networking libraries url: cloud/cloud-and-web-programming-in-visual-cpp.md + - text: Azure SDK for C++ + url: /azure/developer/cpp/sdk/overview/ - text: Universal Windows Platform libraries url: cppcx/namespaces-reference-c-cx.md + - text: vcpkg package manager + url: /vcpkg/ # footer (optional) - footer: "[Microsoft Docs Q&A](/answers/topics/c%2B%2B.html) - [C++ Team Blog](https://devblogs.microsoft.com/cppblog/) - [Twitter](https://twitter.com/visualc) - [Developer Community](https://aka.ms/vsfeedback/browsecpp) - [Stack Overflow](https://stackoverflow.com/questions/tagged/visual-c++) - [How to report an issue](overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md) - [Suggest a feature](https://aka.ms/feedback/suggest?space=62) - Contribute to C++ docs: Read our [contributor guide](/contribute/)." + footer: "[Microsoft Learn Q&A](/answers/topics/c%2B%2B.html) - [C++ Team Blog](https://devblogs.microsoft.com/cppblog/) - [Twitter](https://twitter.com/visualc) - [Developer Community](https://aka.ms/vsfeedback/browsecpp) - [Stack Overflow](https://stackoverflow.com/questions/tagged/visual-c++) - [How to report an issue](overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md) - [Suggest a feature](https://aka.ms/feedback/suggest?space=62) - Contribute to C++ docs: Read our [contributor guide](/contribute/)." diff --git a/docs/intrinsics/addressofreturnaddress.md b/docs/intrinsics/addressofreturnaddress.md index 62708c065e9..62ed8bddb97 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 cf4ffa03934..f0fcca5fb36 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 3f8bbd62a7b..bde0f7c5627 100644 --- a/docs/intrinsics/arm-intrinsics.md +++ b/docs/intrinsics/arm-intrinsics.md @@ -4,11 +4,10 @@ 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 -The Microsoft C++ compiler (MSVC) makes the following intrinsics available on the ARM architecture. For more information about ARM, see the Architecture and Software Development Tools sections of the [ARM Developer Documentation](https://developer.arm.com/docs) website. +The Microsoft C++ (MSVC) compiler makes the following intrinsics available on the ARM architecture. For more information about ARM, see the Architecture and Software Development Tools sections of the [ARM Developer Documentation](https://developer.arm.com/docs) website. ## NEON @@ -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 0ceb607571b..c610e426be3 100644 --- a/docs/intrinsics/arm64-intrinsics.md +++ b/docs/intrinsics/arm64-intrinsics.md @@ -9,16 +9,18 @@ ms.date: "11/14/2019" --- # ARM64 intrinsics -The Microsoft C++ compiler (MSVC) makes the following intrinsics available on the ARM64 architecture. For more information about ARM, see the Architecture and Software Development Tools sections of the [ARM Developer Documentation](https://developer.arm.com/docs) website. +The Microsoft C++ (MSVC) compiler makes the following intrinsics available on the ARM64 architecture. For more information about ARM, see the Architecture and Software Development Tools sections of the [ARM Developer Documentation](https://developer.arm.com/docs) website. ## NEON The NEON vector instruction set extensions for ARM64 provide Single Instruction Multiple Data (SIMD) capabilities. They resemble the ones in the MMX and SSE vector instruction sets that are common to x86 and x64 architecture processors. -NEON intrinsics are supported, as provided in the header file *arm64_neon.h*. The MSVC support for NEON intrinsics resembles that of the ARM64 compiler, which is documented in the [ARM NEON Intrinsic Reference](https://developer.arm.com/architectures/instruction-sets/simd-isas/neon/intrinsics) on the ARM Infocenter website. +NEON intrinsics are supported, as provided in the header file `arm64_neon.h`. The MSVC support for NEON intrinsics resembles that of the ARM64 compiler, which is documented in the [ARM NEON Intrinsic Reference](https://developer.arm.com/architectures/instruction-sets/simd-isas/neon/intrinsics) on the ARM Infocenter website. ## ARM64-specific intrinsics listing +ARM64-specific intrinsics are supported, as provided in the header file `intrin.h`. + |Function Name|Instruction|Function Prototype| |-------------------|-----------------|------------------------| |__break|BRK|void __break(int)| @@ -131,6 +133,8 @@ NEON intrinsics are supported, as provided in the header file *arm64_neon.h*. Th |_CountLeadingSigns64||unsigned int _CountLeadingSigns64(\__int64)| |_CountLeadingZeros||unsigned int _CountLeadingZeros(unsigned long)| |_CountLeadingZeros64||unsigned int _CountLeadingZeros64(unsigned \__int64)| +|_CountTrailingZeros||unsigned int _CountTrailingZeros(unsigned long)| +|_CountTrailingZeros64||unsigned int _CountTrailingZeros64(unsigned __int64)| |_CountOneBits||unsigned int _CountOneBits(unsigned long)| |_CountOneBits64||unsigned int _CountOneBits64(unsigned \__int64)| |_ReadStatusReg|MRS|\__int64 _ReadStatusReg(int)| diff --git a/docs/intrinsics/assume.md b/docs/intrinsics/assume.md index 320a7a467a9..7a5f8c8c2d8 100644 --- a/docs/intrinsics/assume.md +++ b/docs/intrinsics/assume.md @@ -1,12 +1,12 @@ --- description: "Learn more about: __assume" title: "__assume" -ms.date: "09/02/2019" +ms.date: 08/03/2022 f1_keywords: ["__assume", "_assume", "__assume_cpp"] helpviewer_keywords: ["__assume keyword [C++]"] ms.assetid: d8565123-b132-44b1-8235-5a8c8bff85a7 --- -# __assume +# `__assume` **Microsoft Specific** @@ -22,85 +22,80 @@ __assume( ### Parameters -*expression*\ -Any expression that is assumed to evaluate to true. +*`expression`*\ +For reachable code, any expression that is assumed to evaluate to **`true`**. Use `0` to indicate unreachable code to the optimizer. ## Remarks -The optimizer assumes that the condition represented by `expression` is true at the point where the keyword appears and remains true until `expression` is modified (for example, by assignment to a variable). Selective use of hints passed to the optimizer by **`__assume`** can improve optimization. +The optimizer assumes that the condition represented by `expression` is **`true`** at the point where the keyword appears and remains true until `expression` is modified (for example, by assignment to a variable). Selective use of hints passed to the optimizer by **`__assume`** can improve optimization. -If the **`__assume`** statement is written as a contradiction (an expression that always evaluates to false), it is always treated as `__assume(0)`. If your code isn’t behaving as expected, ensure that the `expression` you defined is valid and true, as described earlier. For more information about expected `__assume(0)` behavior, see the later remarks. +If the **`__assume`** statement is written as a contradiction (an expression that always evaluates to **`false`**), it's always treated as `__assume(0)`. If your code isn't behaving as expected, ensure that the `expression` you defined is valid and **`true`**, as described earlier. The `__assume(0)` statement is a special case. Use `__assume(0)` to indicate a code path that can't be reached. > [!WARNING] > A program must not contain an invalid **`__assume`** statement on a reachable path. If the compiler can reach an invalid **`__assume`** statement, the program might cause unpredictable and potentially dangerous behavior. -`__assume` is not a genuine intrinsic. It does not have to be declared as a function and it cannot be used in a `#pragma intrinsic` directive. Although no code is generated, the code generated by the optimizer is affected. +For compatibility with previous versions, **`_assume`** is a synonym for **`__assume`** unless compiler option [`/Za` (Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. -Use **`__assume`** in an [ASSERT](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) only when the assert is not recoverable. Do not use **`__assume`** in an assert for which you have subsequent error recovery code because the compiler might optimize away the error-handling code. +`__assume` isn't a genuine intrinsic. It doesn't have to be declared as a function and it can't be used in a `#pragma intrinsic` directive. Although no code is generated, the code generated by the optimizer is affected. -The `__assume(0)` statement is a special case. Use `__assume(0)` to indicate a code path that cannot be reached. The following example shows how to use `__assume(0)` to indicate that the default case of a switch statement cannot be reached. This shows the most typical use of `__assume(0)`. - -For compatibility with previous versions, **`_assume`** is a synonym for **`__assume`** unless compiler option [/Za \(Disable language extensions)](../build/reference/za-ze-disable-language-extensions.md) is specified. +Use **`__assume`** in an [`ASSERT`](../c-runtime-library/reference/assert-asserte-assert-expr-macros.md) only when the assertion isn't recoverable. Don't use **`__assume`** in an assertion for which you have subsequent error recovery code because the compiler might optimize away the error-handling code. ## Requirements -|Intrinsic|Architecture| -|---------------|------------------| -|**`__assume`**|x86, ARM, x64, ARM64| +| Intrinsic | Architecture | +|--|--| +| **`__assume`** | x86, ARM, x64, ARM64, ARM64EC | ## Example +The following example shows how to use `__assume(0)` to indicate that the **`default`** case of a **`switch`** statement can't be reached. It's the most typical use of `__assume(0)`. Here, the programmer knows that the only possible inputs for `p` will be 1 or 2. If another value is passed in for `p`, the program becomes invalid and causes unpredictable behavior. + ```cpp // compiler_intrinsics__assume.cpp -#ifdef DEBUG -# define ASSERT(e) ( ((e) || assert(__FILE__, __LINE__) ) -#else -# define ASSERT(e) ( __assume(e) ) -#endif -void func1(int i) +void func1(int /*ignored*/) { } int main(int p) { - switch(p){ - case 1: - func1(1); - break; - case 2: - func1(-1); - break; - default: - __assume(0); - // This tells the optimizer that the default - // cannot be reached. As so, it does not have to generate - // the extra code to check that 'p' has a value - // not represented by a case arm. This makes the switch - // run faster. + switch(p) + { + case 1: + func1(1); + break; + case 2: + func1(-1); + break; + default: + __assume(0); + // This tells the optimizer that the default + // cannot be reached. As so, it does not have to generate + // the extra code to check that 'p' has a value + // not represented by a case arm. This makes the switch + // run faster. } } ``` -The use of `__assume(0)` tells the optimizer that the default case cannot be reached. The example demonstrates that the programmer knows that the only possible inputs for `p` will be 1 or 2. If another value is passed in for `p`, the program becomes invalid and causes unpredictable behavior. +As a result of the `__assume(0)` statement, the compiler doesn't generate code to test whether `p` has a value that isn't represented in a case statement. -As a result of the `__assume(0)` statement, the compiler does not generate code to test whether `p` has a value that is not represented in a case statement. For this to work, the `__assume(0)` statement must be the first statement in the body of the default case. - -Because the compiler generates code based on **`__assume`**, that code might not run correctly if the expression inside the **`__assume`** statement is false at run time. If you are not sure that the expression will always be true at run time, you can use the `assert` function to protect the code. +If you aren't sure that the expression will always be **`true`** at runtime, you can use the `assert` function to protect the code. This macro definition wraps the **`__assume`** statement with a check: ```C -#define ASSERT(e) ( ((e) || assert(__FILE__, __LINE__)), __assume(e) ) +#define ASSUME(e) (((e) || (assert(e), (e))), __assume(e)) ``` -Unfortunately, this use of `assert` prevents the compiler from performing the default-case optimization that was described earlier in this document. As an alternative, you can use a separate macro, as follows. +For the **`default`** case optimization to work, the `__assume(0)` statement must be the first statement in the body of the **`default`** case. Unfortunately, the `assert` in the `ASSUME` macro prevents the compiler from performing this optimization. As an alternative, you can use a separate macro, as shown here: ```C #ifdef DEBUG -# define NODEFAULT ASSERT(0) +// This code is supposed to be unreachable, so assert +# define NODEFAULT assert(0) #else # define NODEFAULT __assume(0) #endif - +// . . . default: NODEFAULT; ``` diff --git a/docs/intrinsics/bitscanforward-bitscanforward64.md b/docs/intrinsics/bitscanforward-bitscanforward64.md index 5e53a1c64c2..04d5f4db30f 100644 --- a/docs/intrinsics/bitscanforward-bitscanforward64.md +++ b/docs/intrinsics/bitscanforward-bitscanforward64.md @@ -39,7 +39,7 @@ unsigned char _BitScanForward64( ## Remarks -If a set bit is found, the bit position of the first set bit found is returned in the first parameter. If no set bit is found, 0 is returned; otherwise, 1 is returned. +If a set bit is found, the bit position of the first set bit is written to the address specified in the first parameter and the function returns 1. If no bit is found, the function returns 0 and the value written to the address in the first parameter is undefined. ## Requirements diff --git a/docs/intrinsics/check-isa-arch-support.md b/docs/intrinsics/check-isa-arch-support.md new file mode 100644 index 00000000000..00b066b54b9 --- /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/compiler-intrinsics.md b/docs/intrinsics/compiler-intrinsics.md index ea886301346..381e8610042 100644 --- a/docs/intrinsics/compiler-intrinsics.md +++ b/docs/intrinsics/compiler-intrinsics.md @@ -13,7 +13,7 @@ Most functions are contained in libraries, but some functions are built in (that If a function is an intrinsic, the code for that function is usually inserted inline, avoiding the overhead of a function call and allowing highly efficient machine instructions to be emitted for that function. An intrinsic is often faster than the equivalent inline assembly, because the optimizer has a built-in knowledge of how many intrinsics behave, so some optimizations can be available that are not available when inline assembly is used. Also, the optimizer can expand the intrinsic differently, align buffers differently, or make other adjustments depending on the context and arguments of the call. -The use of intrinsics affects the portability of code, because intrinsics that are available in Visual C++ might not be available if the code is compiled with other compilers and some intrinsics that might be available for some target architectures are not available for all architectures. However, intrinsics are usually more portable than inline assembly. The intrinsics are required on 64-bit architectures where inline assembly is not supported. +The use of intrinsics affects the portability of code, because intrinsics that are available in Microsoft C++ might not be available if the code is compiled with other compilers and some intrinsics that might be available for some target architectures are not available for all architectures. However, intrinsics are usually more portable than inline assembly. The intrinsics are required on 64-bit architectures where inline assembly is not supported. Some intrinsics, such as **`__assume`** and `__ReadWriteBarrier`, provide information to the compiler, which affects the behavior of the optimizer. diff --git a/docs/intrinsics/debugbreak.md b/docs/intrinsics/debugbreak.md index 4b752926d38..ed576d932d1 100644 --- a/docs/intrinsics/debugbreak.md +++ b/docs/intrinsics/debugbreak.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: __debugbreak" title: "__debugbreak" -ms.date: "09/02/2019" +description: "Learn more about: __debugbreak" +ms.date: 09/02/2019 f1_keywords: ["__debugbreak_cpp", "__debugbreak"] helpviewer_keywords: ["breakpoints, __debugbreak intrinsic", "__debugbreak intrinsic"] -ms.assetid: 1d1e1c0c-891a-4613-ae4b-d790094ba830 --- # __debugbreak @@ -34,7 +33,7 @@ The `__debugbreak` compiler intrinsic, similar to [DebugBreak](/windows/win32/ap For example: ```C -main() { +int main() { __debugbreak(); } ``` @@ -42,7 +41,7 @@ main() { is similar to: ```C -main() { +int main() { __asm { int 3 } diff --git a/docs/intrinsics/fastfail.md b/docs/intrinsics/fastfail.md index 592749c4e0b..ffafc9ee25d 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 a6d53048f00..9a0f48891fb 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 db8af5eed10..591cbf07979 100644 --- a/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md +++ b/docs/intrinsics/interlockedcompareexchange-intrinsic-functions.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: _InterlockedCompareExchange intrinsic functions" title: "_InterlockedCompareExchange intrinsic functions" -ms.date: 10/27/2021 +description: "Learn more about: _InterlockedCompareExchange intrinsic functions" +ms.date: 08/03/2022 f1_keywords: ["_InterlockedCompareExchange", "_InterlockedCompareExchange_acq", "_InterlockedCompareExchange_acq_cpp", "_InterlockedCompareExchange_cpp", "_InterlockedCompareExchange_HLEAcquire", "_InterlockedCompareExchange_HLERelease", "_InterlockedCompareExchange_nf", "_InterlockedCompareExchange_np", "_InterlockedCompareExchange_rel", "_InterlockedCompareExchange_rel_cpp", "_InterlockedCompareExchange8", "_InterlockedCompareExchange8_acq", "_InterlockedCompareExchange8_nf", "_InterlockedCompareExchange8_rel", "_InterlockedCompareExchange16", "_InterlockedCompareExchange16_acq", "_InterlockedCompareExchange16_acq_cpp", "_InterlockedCompareExchange16_cpp", "_InterlockedCompareExchange16_nf", "_InterlockedCompareExchange16_rel", "_InterlockedCompareExchange16_rel_cpp", "_InterlockedCompareExchange64", "_InterlockedCompareExchange64_acq", "_InterlockedCompareExchange64_acq_cpp", "_InterlockedCompareExchange64_cpp", "_InterlockedCompareExchange64_HLEAcquire", "_InterlockedCompareExchange64_HLERelease", "_InterlockedCompareExchange64_nf", "_InterlockedCompareExchange64_np", "_InterlockedCompareExchange64_rel", "_InterlockedCompareExchange64_rel_cpp"] helpviewer_keywords: ["_InterlockedCompareExchange intrinsic", "_InterlockedCompareExchange_acq intrinsic", "_InterlockedCompareExchange_acq_cpp intrinsic", "_InterlockedCompareExchange_cpp intrinsic", "_InterlockedCompareExchange_HLEAcquire intrinsic", "_InterlockedCompareExchange_HLERelease intrinsic", "_InterlockedCompareExchange_nf intrinsic", "_InterlockedCompareExchange_np intrinsic", "_InterlockedCompareExchange_rel intrinsic", "_InterlockedCompareExchange_rel_cpp intrinsic", "_InterlockedCompareExchange8 intrinsic", "_InterlockedCompareExchange8_acq intrinsic", "_InterlockedCompareExchange8_nf intrinsic", "_InterlockedCompareExchange8_rel intrinsic", "_InterlockedCompareExchange16 intrinsic", "_InterlockedCompareExchange16_acq intrinsic", "_InterlockedCompareExchange16_acq_cpp intrinsic", "_InterlockedCompareExchange16_cpp intrinsic", "_InterlockedCompareExchange16_nf intrinsic", "_InterlockedCompareExchange16_rel intrinsic", "_InterlockedCompareExchange16_rel_cpp intrinsic", "_InterlockedCompareExchange64 intrinsic", "_InterlockedCompareExchange64_acq intrinsic", "_InterlockedCompareExchange64_acq_cpp intrinsic", "_InterlockedCompareExchange64_cpp intrinsic", "_InterlockedCompareExchange64_HLEAcquire intrinsic", "_InterlockedCompareExchange64_HLERelease intrinsic", "_InterlockedCompareExchange64_nf intrinsic", "_InterlockedCompareExchange64_np intrinsic", "_InterlockedCompareExchange64_rel intrinsic", "_InterlockedCompareExchange64_rel_cpp intrinsic"] -ms.assetid: c3ad79c0-a523-4930-a3a4-69a65d7d5c81 --- -# _InterlockedCompareExchange intrinsic functions +# `_InterlockedCompareExchange` intrinsic functions **Microsoft Specific** @@ -134,37 +133,37 @@ __int64 _InterlockedCompareExchange64_rel( ### Parameters -*Destination*\ +*`Destination`*\ [in, out] Pointer to the destination value. The sign is ignored. -*Exchange*\ +*`Exchange`*\ [in] Exchange value. The sign is ignored. -*Comparand*\ -[in] Value to compare to destination. The sign is ignored. +*`Comparand`*\ +[in] Value to compare to the value pointed at by *`Destination`*. The sign is ignored. ## Return value -The return value is the initial value of the `Destination` pointer. +The return value is the initial value pointed at by the `Destination` pointer. ## Requirements -|Intrinsic|Architecture|Header| -|---------------|------------------|------------| -|`_InterlockedCompareExchange`, `_InterlockedCompareExchange8`, `_InterlockedCompareExchange16`, `_InterlockedCompareExchange64`|x86, ARM, x64, ARM64|\| -|`_InterlockedCompareExchange_acq`, `_InterlockedCompareExchange_nf`, `_InterlockedCompareExchange_rel`, `_InterlockedCompareExchange8_acq`, `_InterlockedCompareExchange8_nf`, `_InterlockedCompareExchange8_rel`,`_InterlockedCompareExchange16_acq`, `_InterlockedCompareExchange16_nf`, `_InterlockedCompareExchange16_rel`, `_InterlockedCompareExchange64_acq`, `_InterlockedCompareExchange64_nf`, `_InterlockedCompareExchange64_rel`,|ARM, ARM64|\| -|`_InterlockedCompareExchange_np`, `_InterlockedCompareExchange16_np`, `_InterlockedCompareExchange64_np`|x64|\| -|`_InterlockedCompareExchange_HLEAcquire`, `_InterlockedCompareExchange_HLERelease`, `_InterlockedCompareExchange64_HLEAcquire`, `_InterlockedCompareExchange64_HLERelease`|x86, x64|\| +| Intrinsic | Architecture | Header | +|--|--|--| +| `_InterlockedCompareExchange`, `_InterlockedCompareExchange8`, `_InterlockedCompareExchange16`, `_InterlockedCompareExchange64` | x86, ARM, x64, ARM64 | \ | +| `_InterlockedCompareExchange_acq`, `_InterlockedCompareExchange_nf`, `_InterlockedCompareExchange_rel`, `_InterlockedCompareExchange8_acq`, `_InterlockedCompareExchange8_nf`, `_InterlockedCompareExchange8_rel`, `_InterlockedCompareExchange16_acq`, `_InterlockedCompareExchange16_nf`, `_InterlockedCompareExchange16_rel`, `_InterlockedCompareExchange64_acq`, `_InterlockedCompareExchange64_nf`, `_InterlockedCompareExchange64_rel` | ARM, ARM64 | \ | +| `_InterlockedCompareExchange_np`, `_InterlockedCompareExchange16_np`, `_InterlockedCompareExchange64_np` | x64 | \ | +| `_InterlockedCompareExchange_HLEAcquire`, `_InterlockedCompareExchange_HLERelease`, `_InterlockedCompareExchange64_HLEAcquire`, `_InterlockedCompareExchange64_HLERelease` | x86, x64 | \ | ## Remarks -`_InterlockedCompareExchange` does an atomic comparison of the `Destination` value with the `Comparand` value. If the `Destination` value is equal to the `Comparand` value, the `Exchange` value is stored in the address specified by `Destination`. Otherwise, does no operation. +`_InterlockedCompareExchange` does an atomic comparison of the value pointed at by `Destination` with the `Comparand` value. If the `Destination` value is equal to the `Comparand` value, the `Exchange` value is stored in the address specified by `Destination`. Otherwise, does no operation. -`_InterlockedCompareExchange` provides compiler intrinsic support for the Win32 Windows SDK [InterlockedCompareExchange](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange) function. +`_InterlockedCompareExchange` provides compiler intrinsic support for the Win32 Windows SDK [`InterlockedCompareExchange`](/windows/win32/api/winnt/nf-winnt-interlockedcompareexchange) function. There are several variations on `_InterlockedCompareExchange` that vary based on the data types they involve and whether processor-specific acquire or release semantics are used. -While the `_InterlockedCompareExchange` function operates on long integer values, `_InterlockedCompareExchange8` operates on 8-bit integer values, `_InterlockedCompareExchange16` operates on short integer values, and `_InterlockedCompareExchange64` operates on 64-bit integer values. +While the `_InterlockedCompareExchange` function operates on 32-bit **`long`** integer values, `_InterlockedCompareExchange8` operates on 8-bit integer values, `_InterlockedCompareExchange16` operates on 16-bit **`short`** integer values, and `_InterlockedCompareExchange64` operates on 64-bit integer values. For more information on similar intrinsics for 128-bit values, see [`_InterlockedCompareExchange128`](./interlockedcompareexchange128.md). On all ARM platforms, use the intrinsics with `_acq` and `_rel` suffixes for acquire and release semantics, such as at the beginning and end of a critical section. The ARM intrinsics with an `_nf` ("no fence") suffix don't act as a memory barrier. @@ -390,8 +389,8 @@ int main( ## See also -[_InterlockedCompareExchange128](../intrinsics/interlockedcompareexchange128.md)\ -[_InterlockedCompareExchangePointer intrinsic functions](../intrinsics/interlockedcompareexchangepointer-intrinsic-functions.md)\ +[`_InterlockedCompareExchange128`](../intrinsics/interlockedcompareexchange128.md)\ +[`_InterlockedCompareExchangePointer` intrinsic functions](../intrinsics/interlockedcompareexchangepointer-intrinsic-functions.md)\ [Compiler intrinsics](../intrinsics/compiler-intrinsics.md)\ [Keywords](../cpp/keywords-cpp.md)\ [Conflicts with the x86 Compiler](../build/x64-software-conventions.md#conflicts-with-the-x86-compiler) diff --git a/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md b/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md index a105513296d..a5e5134fc01 100644 --- a/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md +++ b/docs/intrinsics/interlockedexchangeadd-intrinsic-functions.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: _InterlockedExchangeAdd intrinsic functions" title: "_InterlockedExchangeAdd intrinsic functions" +description: "Learn more about: _InterlockedExchangeAdd intrinsic functions" ms.date: "09/02/2019" f1_keywords: ["_InterlockedExchangeAdd64_nf", "_InterlockedExchangeAdd64_rel", "_InterlockedExchangeAdd16_rel", "_InterlockedExchangeAdd_acq", "_InterlockedExchangeAdd_nf", "_InterlockedExchangeAdd_rel", "_InterlockedExchangeAdd8_acq", "_InterlockedExchangeAdd16_nf", "_InterlockedExchangeAdd_acq_cpp", "_InterlockedExchangeAdd64_acq_cpp", "_InterlockedExchangeAdd16_acq", "_InterlockedExchangeAdd_HLERelease", "_InterlockedExchangeAdd64_cpp", "_InterlockedExchangeAdd64_HLERelease", "_InterlockedExchangeAdd64_acq", "_InterlockedExchangeAdd8", "_InterlockedExchangeAdd64", "_InterlockedExchangeAdd8_nf", "_InterlockedExchangeAdd16", "_InterlockedExchangeAdd64_rel_cpp", "_InterlockedExchangeAdd_cpp", "_InterlockedExchangeAdd8_rel", "_InterlockedExchangeAdd_HLEAcquire", "_InterlockedExchangeAdd64_HLEAcquire", "_InterlockedExchangeAdd"] helpviewer_keywords: ["_InterlockedExchangeAdd8_nf intrinsic", "InterlockedExchangeAdd64_acq intrinsic", "_InterlockedExchangeAdd8_acq intrinsic", "_InterlockedExchangeAdd64 intrinsic", "_InterlockedExchangeAdd intrinsic", "_InterlockedExchangeAdd8_rel intrinsic", "_InterlockedExchangeAdd_acq intrinsic", "_InterlockedExchangeAdd_HLEAcquire intrinsic", "_InterlockedExchangeAdd8 intrinsic", "_InterlockedExchangeAdd_rel intrinsic", "_InterlockedExchangeAdd64_HLERelease intrinsic", "_InterlockedExchangeAdd64_nf intrinsic", "InterlockedExchangeAdd_rel intrinsic", "InterlockedExchangeAdd intrinsic", "_InterlockedExchangeAdd_nf intrinsic", "_InterlockedExchangeAdd16_rel intrinsic", "InterlockedExchangeAdd_acq intrinsic", "_InterlockedExchangeAdd64_HLEAcquire intrinsic", "_InterlockedExchangeAdd16 intrinsic", "_InterlockedExchangeAdd64_acq intrinsic", "InterlockedExchangeAdd64_rel intrinsic", "_InterlockedExchangeAdd16_acq intrinsic", "InterlockedExchangeAdd64 intrinsic", "_InterlockedExchangeAdd_HLERelease intrinsic", "_InterlockedExchangeAdd16_nf intrinsic", "_InterlockedExchangeAdd64_rel intrinsic"] -ms.assetid: 25809e1f-9c60-4492-9f7c-0fb59c8d13d2 --- # _InterlockedExchangeAdd intrinsic functions @@ -115,7 +114,7 @@ The return value is the initial value of the variable pointed to by the `Addend` |---------------|------------------|------------| |`_InterlockedExchangeAdd`, `_InterlockedExchangeAdd8`, `_InterlockedExchangeAdd16`|x86, ARM, x64, ARM64|\| |`_InterlockedExchangeAdd64`|ARM, x64, ARM64|\| -|`_InterlockedExchangeAdd_acq`, `_InterlockedExchangeAdd_rel`, `_InterlockedExchangeAdd_nf`, `_InterlockedExchangeAdd8_acq`, `_InterlockedExchangeAdd8_rel`, `_InterlockedExchangeAdd8_nf`,`_InterlockedExchangeAdd16_acq`, `_InterlockedExchangeAdd16_rel`, `_InterlockedExchangeAdd16_nf`, `_InterlockedExchangeAdd64_acq`, `_InterlockedExchangeAdd64_rel`, `_InterlockedExchangeAdd64_nf`|ARM, ARM64|\| +|`_InterlockedExchangeAdd_acq`, `_InterlockedExchangeAdd_rel`, `_InterlockedExchangeAdd_nf`, `_InterlockedExchangeAdd8_acq`, `_InterlockedExchangeAdd8_rel`, `_InterlockedExchangeAdd8_nf`, `_InterlockedExchangeAdd16_acq`, `_InterlockedExchangeAdd16_rel`, `_InterlockedExchangeAdd16_nf`, `_InterlockedExchangeAdd64_acq`, `_InterlockedExchangeAdd64_rel`, `_InterlockedExchangeAdd64_nf`|ARM, ARM64|\| |`_InterlockedExchangeAdd_HLEAcquire`, `_InterlockedExchangeAdd_HLERelease`|x86, x64|\| |`_InterlockedExchangeAdd64_HLEAcquire`, `_InterlockedExchangeAdd64_HLErelease`|x64|\| diff --git a/docs/intrinsics/intrinsics-available-on-all-architectures.md b/docs/intrinsics/intrinsics-available-on-all-architectures.md index 9eb339997c2..93cad134b48 100644 --- a/docs/intrinsics/intrinsics-available-on-all-architectures.md +++ b/docs/intrinsics/intrinsics-available-on-all-architectures.md @@ -1,7 +1,7 @@ --- description: "Learn more about: Intrinsics available on all architectures" title: "Intrinsics available on all architectures" -ms.date: 02/04/2021 +ms.date: 08/30/2022 helpviewer_keywords: ["cl.exe compiler, intrinsics"] --- # Intrinsics available on all architectures @@ -153,6 +153,13 @@ The following UCRT functions have intrinsic forms on all architectures: | [`wcslen`](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md) | string.h | | [`_wcsset`](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) | string.h | +In Visual Studio 2022 version 17.2 and later, these functions have intrinsic forms on x64 and ARM64 platforms: + +| Intrinsic | Header | +|--|--| +| [`log2`](../c-runtime-library/reference/log2-log2f-log2l.md) | math.h | +| [`log2f`](../c-runtime-library/reference/log2-log2f-log2l.md) | math.h | + ## See also [ARM intrinsics](../intrinsics/arm-intrinsics.md)\ diff --git a/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md b/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md index 3c6f905373e..aad03f0a479 100644 --- a/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md +++ b/docs/intrinsics/mm-insert-si64-mm-inserti-si64.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: _mm_insert_si64, _mm_inserti_si64" title: "_mm_insert_si64, _mm_inserti_si64" +description: "Learn more about: _mm_insert_si64, _mm_inserti_si64" ms.date: "09/02/2019" f1_keywords: ["_mm_inserti_si64", "_mm_insert_si64"] helpviewer_keywords: ["insertq instruction", "_mm_insert_si64 intrinsic", "_mm_inserti_si64 intrinsic"] -ms.assetid: 897a4b36-8b08-4b00-a18f-7850f5732d7d --- # _mm_insert_si64, _mm_inserti_si64 @@ -21,7 +20,7 @@ __m128i _mm_insert_si64( ); __m128i _mm_inserti_si64( __m128i Source1, - __m128i Source2 + __m128i Source2, int Length, int Index ); diff --git a/docs/intrinsics/mm-stream-ss.md b/docs/intrinsics/mm-stream-ss.md index 5c460ea215c..6c99fef1545 100644 --- a/docs/intrinsics/mm-stream-ss.md +++ b/docs/intrinsics/mm-stream-ss.md @@ -1,12 +1,12 @@ --- description: "Learn more about: _mm_stream_ss" title: "_mm_stream_ss" -ms.date: "09/02/2019" +ms.date: 01/04/2023 f1_keywords: ["_mm_stream_ss"] helpviewer_keywords: ["movntss instruction", "_mm_stream_ss intrinsic"] ms.assetid: c53dffe9-0dfe-4063-85d3-e8987b870fce --- -# _mm_stream_ss +# `_mm_stream_ss` **Microsoft Specific** @@ -35,9 +35,9 @@ None. ## Requirements -|Intrinsic|Architecture| -|---------------|------------------| -|`_mm_stream_ss`|SSE4a| +| Intrinsic | Architecture | +|---|---| +| `_mm_stream_ss` | SSE4a | **Header file** \ @@ -70,7 +70,7 @@ int main() vals.m128_f32[3] = 3.; _mm_stream_ss(&f[3], vals); cout << "f[0] = " << f[0] << ", f[1] = " << f[1] << endl; - cout << "f[1] = " << f[1] << ", f[3] = " << f[3] << endl; + cout << "f[2] = " << f[2] << ", f[3] = " << f[3] << endl; } ``` @@ -85,8 +85,8 @@ Portions Copyright 2007 by Advanced Micro Devices, Inc. All rights reserved. Rep ## See also -[_mm_stream_sd](../intrinsics/mm-stream-sd.md)\ -[_mm_stream_ps](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_stream_ps)\ -[_mm_store_ss](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ss)\ -[_mm_sfence](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sfence)\ +[`_mm_stream_sd`](../intrinsics/mm-stream-sd.md)\ +[`_mm_stream_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_stream_ps)\ +[`_mm_store_ss`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_store_ss)\ +[`_mm_sfence`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm_sfence)\ [Compiler intrinsics](../intrinsics/compiler-intrinsics.md) diff --git a/docs/intrinsics/rdtsc.md b/docs/intrinsics/rdtsc.md index 1bf37dc8e6f..09268f21f7b 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 92816d45dec..0bd25672bd8 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/rotl8-rotl16.md b/docs/intrinsics/rotl8-rotl16.md index 7c12f13c465..e7316f19589 100644 --- a/docs/intrinsics/rotl8-rotl16.md +++ b/docs/intrinsics/rotl8-rotl16.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: _rotl8, _rotl16" title: "_rotl8, _rotl16" -ms.date: "09/02/2019" +description: "Learn more about: _rotl8, _rotl16" +ms.date: 09/02/2019 f1_keywords: ["_rotl8", "_rotl16"] helpviewer_keywords: ["_rotl8 intrinsic", "_rotl16 intrinsic"] -ms.assetid: 8c519ab6-aef9-4f07-a387-daee8408368f --- -# _rotl8, _rotl16 +# `_rotl8`, `_rotl16` **Microsoft Specific** @@ -27,10 +26,10 @@ unsigned short _rotl16( ### Parameters -*value*\ +*`value`*\ [in] The value to rotate. -*shift*\ +*`shift`*\ [in] The number of bits to rotate. ## Return value @@ -44,7 +43,7 @@ The rotated value. |`_rotl8`|x86, ARM, x64, ARM64| |`_rotl16`|x86, ARM, x64, ARM64| -**Header file** \ +**Header file**: `` ## Remarks @@ -61,7 +60,7 @@ Unlike a left-shift operation, when executing a left rotation, the high-order bi int main() { - unsigned char c = 'A', c1, c2; + unsigned char c = 'A'; for (int i = 0; i < 8; i++) { @@ -93,5 +92,5 @@ Rotating unsigned short 0x12 left by 10 bits gives 0x4800 ## See also -[_rotr8, _rotr16](../intrinsics/rotr8-rotr16.md)\ -[Compiler intrinsics](../intrinsics/compiler-intrinsics.md) +[`_rotr8`, `_rotr16`](rotr8-rotr16.md)\ +[Compiler intrinsics](compiler-intrinsics.md) diff --git a/docs/intrinsics/rotr8-rotr16.md b/docs/intrinsics/rotr8-rotr16.md index fcc9a07e5aa..71a519a1793 100644 --- a/docs/intrinsics/rotr8-rotr16.md +++ b/docs/intrinsics/rotr8-rotr16.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: _rotr8, _rotr16" title: "_rotr8, _rotr16" -ms.date: "09/02/2019" +description: "Learn more about: _rotr8, _rotr16" +ms.date: 09/02/2019 f1_keywords: ["_rotr16", "_rotr8"] helpviewer_keywords: ["_rotr8 intrinsic", "_rotr16 intrinsic"] -ms.assetid: dfbd2c82-82b4-427a-ad52-51609027ebff --- -# _rotr8, _rotr16 +# `_rotr8`, `_rotr16` **Microsoft Specific** @@ -27,10 +26,10 @@ unsigned short _rotr16( ### Parameters -*value*\ +*`value`*\ [in] The value to rotate. -*shift*\ +*`shift`*\ [in] The number of bits to rotate. ## Return value @@ -44,7 +43,7 @@ The rotated value. |`_rotr8`|x86, ARM, x64, ARM64| |`_rotr16`|x86, ARM, x64, ARM64| -**Header file** \ +**Header file**: `` ## Remarks @@ -61,7 +60,7 @@ Unlike a right-shift operation, when executing a right rotation, the low-order b int main() { - unsigned char c = 'A', c1, c2; + unsigned char c = 'A'; for (int i = 0; i < 8; i++) { @@ -94,5 +93,5 @@ Rotating unsigned short 0x12 right by 10 bits gives 0x480 ## See also -[_rotl8, _rotl16](../intrinsics/rotl8-rotl16.md)\ -[Compiler intrinsics](../intrinsics/compiler-intrinsics.md) +[`_rotl8`, `_rotl16`](rotl8-rotl16.md)\ +[Compiler intrinsics](compiler-intrinsics.md) diff --git a/docs/intrinsics/sentinel-conversion-functions.md b/docs/intrinsics/sentinel-conversion-functions.md index fda826a7a04..f044aa16f1c 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 37afa238225..bd1487ead2f 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 cfbc51772b9..0c9053c8c38 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 a92840bf598..6aa9851d39c 100644 --- a/docs/intrinsics/umulh.md +++ b/docs/intrinsics/umulh.md @@ -1,12 +1,12 @@ --- description: "Learn more about: __umulh" title: "__umulh" -ms.date: "09/02/2019" +ms.date: 09/19/2022 f1_keywords: ["__umulh"] helpviewer_keywords: ["__umulh intrinsic"] ms.assetid: d241b53a-e6f7-4af1-9f6e-84e149158f03 --- -# __umulh +# `__umulh` **Microsoft Specific** @@ -23,10 +23,10 @@ unsigned __int64 __umulh( ### Parameters -*a*\ +*`a`*\ [in] The first number to multiply. -*b*\ +*`b`*\ [in] The second number to multiply. ## Return value @@ -35,9 +35,9 @@ The high 64 bits of the 128-bit result of the multiplication. ## Requirements -|Intrinsic|Architecture| -|---------------|------------------| -|`__umulh`|x64| +| Intrinsic | Architecture | +|--|--| +| `__umulh` | x64, ARM64 | **Header file** \ @@ -62,13 +62,13 @@ int main() unsigned __int64 result; result = __umulh(i, j); // result has the high 64 bits // of the product. - printf_s("0x%I64x * 0x%I64x = 0x%I64x%I64x \n", i, j, result, k); + printf_s("0x%016I64x * 0x%016I64x = 0x%016I64x_%016I64x \n", i, j, result, k); return 0; } ``` ```Output -0x10 * 0xfedcba9876543210 = 0xfedcba98765432100 +0x0000000000000010 * 0xfedcba9876543210 = 0x000000000000000f_edcba98765432100 ``` **END Microsoft Specific** diff --git a/docs/intrinsics/vmx-on.md b/docs/intrinsics/vmx-on.md index 31a83a04453..2bea8d2e6c6 100644 --- a/docs/intrinsics/vmx-on.md +++ b/docs/intrinsics/vmx-on.md @@ -35,7 +35,7 @@ unsigned char __vmx_on( ## Remarks -The `__vmx_on` function corresponds to the `VMXON` machine instruction. This function supports the interaction of a host's virtual machine monitor with a guest operating system and its applications. For more information, see "Intel 64 and IA-32 Architectures Software Developer’s Manual, Volume 3C: System Programming Guide, Part 3" in the [Intel 64 and IA-32 Architecture Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html). +The `__vmx_on` function corresponds to the `VMXON` machine instruction. This function supports the interaction of a host's virtual machine monitor with a guest operating system and its applications. For more information, see "Intel 64 and IA-32 Architectures Software Developer's Manual, Volume 3C: System Programming Guide, Part 3" in the [Intel 64 and IA-32 Architecture Developer Manuals](https://www.intel.com/content/www/us/en/developer/articles/technical/intel-sdm.html). ## Requirements diff --git a/docs/intrinsics/x64-amd64-intrinsics-list.md b/docs/intrinsics/x64-amd64-intrinsics-list.md index ce8dbcfde89..948b93ee9d9 100644 --- a/docs/intrinsics/x64-amd64-intrinsics-list.md +++ b/docs/intrinsics/x64-amd64-intrinsics-list.md @@ -1,9 +1,9 @@ --- title: "x64 (amd64) intrinsics list" description: "Reference list of x64 (AMD64) intrinsics supported by the Microsoft C++ compiler in Visual Studio." -ms.date: 07/01/2022 -f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u64", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "immintrin/_addcarryx_u64", "ammintrin/_andn_u32", "ammintrin/_andn_u64", "ammintrin/_bextr_u32", "ammintrin/_bextr_u64", "ammintrin/_bextri_u32", "ammintrin/_bextri_u64", "ammintrin/_blcfill_u32", "ammintrin/_blcfill_u64", "ammintrin/_blci_u32", "ammintrin/_blci_u64", "ammintrin/_blcic_u32", "ammintrin/_blcic_u64", "ammintrin/_blcmsk_u32", "ammintrin/_blcmsk_u64", "ammintrin/_blcs_u32", "ammintrin/_blcs_u64", "ammintrin/_blsfill_u32", "ammintrin/_blsfill_u64", "ammintrin/_blsi_u32", "ammintrin/_blsi_u64", "ammintrin/_blsic_u32", "ammintrin/_blsic_u64", "ammintrin/_blsmsk_u32", "ammintrin/_blsmsk_u64", "ammintrin/_blsr_u32", "ammintrin/_blsr_u64", "immintrin/_bzhi_u32", "immintrin/_bzhi_u64", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxrstor64", "immintrin/_fxsave", "immintrin/_fxsave64", "immintrin/_invpcid", "intrin/_lgdt", "ammintrin/__llwpcb", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "immintrin/_load_be_u64", "immintrin/_loadbe_i64", "ammintrin/__lwpins32", "ammintrin/__lwpins64", "ammintrin/__lwpval32", "ammintrin/__lwpval64", "ammintrin/_lzcnt_u32", "ammintrin/_lzcnt_u64", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u64", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_si64", "intrin/_mm_cvtsd_si64x", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi128_si64", "intrin/_mm_cvtsi128_si64x", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "intrin/_mm_cvtsi64_sd", "intrin/_mm_cvtsi64_si128", "intrin/_mm_cvtsi64_ss", "intrin/_mm_cvtsi64x_sd", "intrin/_mm_cvtsi64x_si128", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtss_si64", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_cvttsd_si64", "intrin/_mm_cvttsd_si64x", "intrin/_mm_cvttss_si64", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi64", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi64", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_popcnt_u64", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64x", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64x", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi64x", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi64x", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi64x", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "immintrin/_mulx_u64", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pdep_u64", "immintrin/_pext_u32", "immintrin/_pext_u64", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdrand64_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rdseed64_step", "immintrin/_readfsbase_u32", "immintrin/_readfsbase_u64", "immintrin/_readgsbase_u32", "immintrin/_readgsbase_u64", "immintrin/_rorx_u32", "immintrin/_rorx_u64", "intrin/_rsm", "immintrin/_sarx_i32", "immintrin/_sarx_i64", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shlx_u64", "immintrin/_shrx_u32", "immintrin/_shrx_u64", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_store_be_u64", "immintrin/_storebe_i64", "immintrin/_Store_HLERelease", "immintrin/_Store64_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u64", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_t1mskc_u64", "ammintrin/_tzcnt_u32", "ammintrin/_tzcnt_u64", "ammintrin/_tzmsk_u32", "ammintrin/_tzmsk_u64", "immintrin/_writefsbase_u32", "immintrin/_writefsbase_u64", "immintrin/_writegsbase_u32", "immintrin/_writegsbase_u64", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xrstor64", "immintrin/_xsave", "immintrin/_xsave64", "immintrin/_xsaveopt", "immintrin/_xsaveopt64", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_mm_add_ps", "XMMINTRIN/_mm_add_ss", "XMMINTRIN/_mm_and_ps", "XMMINTRIN/_mm_andnot_ps", "XMMINTRIN/_mm_cmpeq_ps", "XMMINTRIN/_mm_cmpeq_ss", "XMMINTRIN/_mm_cmpge_ps", "XMMINTRIN/_mm_cmpge_ss", "XMMINTRIN/_mm_cmpgt_ps", "XMMINTRIN/_mm_cmpgt_ss", "XMMINTRIN/_mm_cmple_ps", "XMMINTRIN/_mm_cmple_ss", "XMMINTRIN/_mm_cmplt_ps", "XMMINTRIN/_mm_cmplt_ss", "XMMINTRIN/_mm_cmpneq_ps", "XMMINTRIN/_mm_cmpneq_ss", "XMMINTRIN/_mm_cmpnge_ps", "XMMINTRIN/_mm_cmpnge_ss", "XMMINTRIN/_mm_cmpngt_ps", "XMMINTRIN/_mm_cmpngt_ss", "XMMINTRIN/_mm_cmpnle_ps", "XMMINTRIN/_mm_cmpnle_ss", "XMMINTRIN/_mm_cmpnlt_ps", "XMMINTRIN/_mm_cmpnlt_ss", "XMMINTRIN/_mm_cmpord_ps", "XMMINTRIN/_mm_cmpord_ss", "XMMINTRIN/_mm_cmpunord_ps", "XMMINTRIN/_mm_cmpunord_ss", "XMMINTRIN/_mm_comieq_ss", "XMMINTRIN/_mm_comige_ss", "XMMINTRIN/_mm_comigt_ss", "XMMINTRIN/_mm_comile_ss", "XMMINTRIN/_mm_comilt_ss", "XMMINTRIN/_mm_comineq_ss", "XMMINTRIN/_mm_cvt_si2ss", "XMMINTRIN/_mm_cvt_ss2si", "XMMINTRIN/_mm_cvtpi16_ps", "XMMINTRIN/_mm_cvtpi32x2_ps", "XMMINTRIN/_mm_cvtpi8_ps", "XMMINTRIN/_mm_cvtps_pi16", "XMMINTRIN/_mm_cvtps_pi8", "XMMINTRIN/_mm_cvtpu16_ps", "XMMINTRIN/_mm_cvtpu8_ps", "XMMINTRIN/_mm_cvtsi32_ss", "XMMINTRIN/_mm_cvtsi64_ss", "XMMINTRIN/_mm_cvtss_f32", "XMMINTRIN/_mm_cvtss_si32", "XMMINTRIN/_mm_cvtss_si64", "XMMINTRIN/_mm_cvtt_ss2si", "XMMINTRIN/_mm_cvttss_si32", "XMMINTRIN/_mm_cvttss_si64", "XMMINTRIN/_mm_div_ps", "XMMINTRIN/_mm_div_ss", "XMMINTRIN/_mm_getcsr", "XMMINTRIN/_mm_load_ps", "XMMINTRIN/_mm_load_ps1", "XMMINTRIN/_mm_load_ss", "XMMINTRIN/_mm_load1_ps", "XMMINTRIN/_mm_loadh_pi", "XMMINTRIN/_mm_loadl_pi", "XMMINTRIN/_mm_loadr_ps", "XMMINTRIN/_mm_loadu_ps", "XMMINTRIN/_mm_max_ps", "XMMINTRIN/_mm_max_ss", "XMMINTRIN/_mm_min_ps", "XMMINTRIN/_mm_min_ss", "XMMINTRIN/_mm_move_ss", "XMMINTRIN/_mm_movehl_ps", "XMMINTRIN/_mm_movelh_ps", "XMMINTRIN/_mm_movemask_ps", "XMMINTRIN/_mm_mul_ps", "XMMINTRIN/_mm_mul_ss", "XMMINTRIN/_mm_or_ps", "XMMINTRIN/_mm_prefetch", "XMMINTRIN/_mm_rcp_ps", "XMMINTRIN/_mm_rcp_ss", "XMMINTRIN/_mm_rsqrt_ps", "XMMINTRIN/_mm_rsqrt_ss", "XMMINTRIN/_mm_set_ps", "XMMINTRIN/_mm_set_ps1", "XMMINTRIN/_mm_set_ss", "XMMINTRIN/_mm_set1_ps", "XMMINTRIN/_mm_setcsr", "XMMINTRIN/_mm_setr_ps", "XMMINTRIN/_mm_setzero_ps", "XMMINTRIN/_mm_sfence", "XMMINTRIN/_mm_shuffle_ps", "XMMINTRIN/_mm_sqrt_ps", "XMMINTRIN/_mm_sqrt_ss", "XMMINTRIN/_mm_store_ps", "XMMINTRIN/_mm_store_ps1", "XMMINTRIN/_mm_store_ss", "XMMINTRIN/_mm_store1_ps", "XMMINTRIN/_mm_storeh_pi", "XMMINTRIN/_mm_storel_pi", "XMMINTRIN/_mm_storer_ps", "XMMINTRIN/_mm_storeu_ps", "XMMINTRIN/_mm_stream_ps", "XMMINTRIN/_mm_sub_ps", "XMMINTRIN/_mm_sub_ss", "XMMINTRIN/_mm_ucomieq_ss", "XMMINTRIN/_mm_ucomige_ss", "XMMINTRIN/_mm_ucomigt_ss", "XMMINTRIN/_mm_ucomile_ss", "XMMINTRIN/_mm_ucomilt_ss", "XMMINTRIN/_mm_ucomineq_ss", "XMMINTRIN/_mm_unpackhi_ps", "XMMINTRIN/_mm_unpacklo_ps", "XMMINTRIN/_mm_xor_ps"] -helpviewer_keywords: ["cl-exe compiler, intrinsics", "intrinsics, x64", "intrinsics, amd64", "_addcarry_u16 x64 intrinsic", "_addcarry_u32 x64 intrinsic", "_addcarry_u64 x64 intrinsic", "_addcarry_u8 x64 intrinsic", "_addcarryx_u32 x64 intrinsic", "_addcarryx_u64 x64 intrinsic", "_andn_u32 x64 intrinsic", "_andn_u64 x64 intrinsic", "_bextr_u32 x64 intrinsic", "_bextr_u64 x64 intrinsic", "_bextri_u32 x64 intrinsic", "_bextri_u64 x64 intrinsic", "_blcfill_u32 x64 intrinsic", "_blcfill_u64 x64 intrinsic", "_blci_u32 x64 intrinsic", "_blci_u64 x64 intrinsic", "_blcic_u32 x64 intrinsic", "_blcic_u64 x64 intrinsic", "_blcmsk_u32 x64 intrinsic", "_blcmsk_u64 x64 intrinsic", "_blcs_u32 x64 intrinsic", "_blcs_u64 x64 intrinsic", "_blsfill_u32 x64 intrinsic", "_blsfill_u64 x64 intrinsic", "_blsi_u32 x64 intrinsic", "_blsi_u64 x64 intrinsic", "_blsic_u32 x64 intrinsic", "_blsic_u64 x64 intrinsic", "_blsmsk_u32 x64 intrinsic", "_blsmsk_u64 x64 intrinsic", "_blsr_u32 x64 intrinsic", "_blsr_u64 x64 intrinsic", "_bzhi_u32 x64 intrinsic", "_bzhi_u64 x64 intrinsic", "_clac x64 intrinsic", "_fxrstor x64 intrinsic", "_fxrstor64 x64 intrinsic", "_fxsave x64 intrinsic", "_fxsave64 x64 intrinsic", "_invpcid x64 intrinsic", "_lgdt x64 intrinsic", "__llwpcb x64 intrinsic", "_load_be_u16 x64 intrinsic", "_loadbe_i16 x64 intrinsic", "_load_be_u32 x64 intrinsic", "_loadbe_i32 x64 intrinsic", "_load_be_u64 x64 intrinsic", "_loadbe_i64 x64 intrinsic", "__lwpins32 x64 intrinsic", "__lwpins64 x64 intrinsic", "__lwpval32 x64 intrinsic", "__lwpval64 x64 intrinsic", "_lzcnt_u32 x64 intrinsic", "_lzcnt_u64 x64 intrinsic", "_m_prefetch x64 intrinsic", "_m_prefetchw x64 intrinsic", "_mm_abs_epi16 x64 intrinsic", "_mm_abs_epi32 x64 intrinsic", "_mm_abs_epi8 x64 intrinsic", "_mm_add_epi16 x64 intrinsic", "_mm_add_epi32 x64 intrinsic", "_mm_add_epi64 x64 intrinsic", "_mm_add_epi8 x64 intrinsic", "_mm_add_pd x64 intrinsic", "_mm_add_ps x64 intrinsic", "_mm_add_sd x64 intrinsic", "_mm_add_ss x64 intrinsic", "_mm_adds_epi16 x64 intrinsic", "_mm_adds_epi8 x64 intrinsic", "_mm_adds_epu16 x64 intrinsic", "_mm_adds_epu8 x64 intrinsic", "_mm_addsub_pd x64 intrinsic", "_mm_addsub_ps x64 intrinsic", "_mm_aesdec_si128 x64 intrinsic", "_mm_aesdeclast_si128 x64 intrinsic", "_mm_aesenc_si128 x64 intrinsic", "_mm_aesenclast_si128 x64 intrinsic", "_mm_aesimc_si128 x64 intrinsic", "_mm_aeskeygenassist_si128 x64 intrinsic", "_mm_alignr_epi8 x64 intrinsic", "_mm_and_pd x64 intrinsic", "_mm_and_ps x64 intrinsic", "_mm_and_si128 x64 intrinsic", "_mm_andnot_pd x64 intrinsic", "_mm_andnot_ps x64 intrinsic", "_mm_andnot_si128 x64 intrinsic", "_mm_avg_epu16 x64 intrinsic", "_mm_avg_epu8 x64 intrinsic", "_mm_blend_epi16 x64 intrinsic", "_mm_blend_epi32 x64 intrinsic", "_mm_blend_pd x64 intrinsic", "_mm_blend_ps x64 intrinsic", "_mm_blendv_epi8 x64 intrinsic", "_mm_blendv_pd x64 intrinsic", "_mm_blendv_ps x64 intrinsic", "_mm_broadcast_ss x64 intrinsic", "_mm_broadcastb_epi8 x64 intrinsic", "_mm_broadcastd_epi32 x64 intrinsic", "_mm_broadcastq_epi64 x64 intrinsic", "_mm_broadcastsd_pd x64 intrinsic", "_mm_broadcastss_ps x64 intrinsic", "_mm_broadcastw_epi16 x64 intrinsic", "_mm_castpd_ps x64 intrinsic", "_mm_castpd_si128 x64 intrinsic", "_mm_castps_pd x64 intrinsic", "_mm_castps_si128 x64 intrinsic", "_mm_castsi128_pd x64 intrinsic", "_mm_castsi128_ps x64 intrinsic", "_mm_clflush x64 intrinsic", "_mm_clmulepi64_si128 x64 intrinsic", "_mm_cmov_si128 x64 intrinsic", "_mm_cmp_pd x64 intrinsic", "_mm_cmp_ps x64 intrinsic", "_mm_cmp_sd x64 intrinsic", "_mm_cmp_ss x64 intrinsic", "_mm_cmpeq_epi16 x64 intrinsic", "_mm_cmpeq_epi32 x64 intrinsic", "_mm_cmpeq_epi64 x64 intrinsic", "_mm_cmpeq_epi8 x64 intrinsic", "_mm_cmpeq_pd x64 intrinsic", "_mm_cmpeq_ps x64 intrinsic", "_mm_cmpeq_sd x64 intrinsic", "_mm_cmpeq_ss x64 intrinsic", "_mm_cmpestra x64 intrinsic", "_mm_cmpestrc x64 intrinsic", "_mm_cmpestri x64 intrinsic", "_mm_cmpestrm x64 intrinsic", "_mm_cmpestro x64 intrinsic", "_mm_cmpestrs x64 intrinsic", "_mm_cmpestrz x64 intrinsic", "_mm_cmpge_pd x64 intrinsic", "_mm_cmpge_ps x64 intrinsic", "_mm_cmpge_sd x64 intrinsic", "_mm_cmpge_ss x64 intrinsic", "_mm_cmpgt_epi16 x64 intrinsic", "_mm_cmpgt_epi32 x64 intrinsic", "_mm_cmpgt_epi64 x64 intrinsic", "_mm_cmpgt_epi8 x64 intrinsic", "_mm_cmpgt_pd x64 intrinsic", "_mm_cmpgt_ps x64 intrinsic", "_mm_cmpgt_sd x64 intrinsic", "_mm_cmpgt_ss x64 intrinsic", "_mm_cmpistra x64 intrinsic", "_mm_cmpistrc x64 intrinsic", "_mm_cmpistri x64 intrinsic", "_mm_cmpistrm x64 intrinsic", "_mm_cmpistro x64 intrinsic", "_mm_cmpistrs x64 intrinsic", "_mm_cmpistrz x64 intrinsic", "_mm_cmple_pd x64 intrinsic", "_mm_cmple_ps x64 intrinsic", "_mm_cmple_sd x64 intrinsic", "_mm_cmple_ss x64 intrinsic", "_mm_cmplt_epi16 x64 intrinsic", "_mm_cmplt_epi32 x64 intrinsic", "_mm_cmplt_epi8 x64 intrinsic", "_mm_cmplt_pd x64 intrinsic", "_mm_cmplt_ps x64 intrinsic", "_mm_cmplt_sd x64 intrinsic", "_mm_cmplt_ss x64 intrinsic", "_mm_cmpneq_pd x64 intrinsic", "_mm_cmpneq_ps x64 intrinsic", "_mm_cmpneq_sd x64 intrinsic", "_mm_cmpneq_ss x64 intrinsic", "_mm_cmpnge_pd x64 intrinsic", "_mm_cmpnge_ps x64 intrinsic", "_mm_cmpnge_sd x64 intrinsic", "_mm_cmpnge_ss x64 intrinsic", "_mm_cmpngt_pd x64 intrinsic", "_mm_cmpngt_ps x64 intrinsic", "_mm_cmpngt_sd x64 intrinsic", "_mm_cmpngt_ss x64 intrinsic", "_mm_cmpnle_pd x64 intrinsic", "_mm_cmpnle_ps x64 intrinsic", "_mm_cmpnle_sd x64 intrinsic", "_mm_cmpnle_ss x64 intrinsic", "_mm_cmpnlt_pd x64 intrinsic", "_mm_cmpnlt_ps x64 intrinsic", "_mm_cmpnlt_sd x64 intrinsic", "_mm_cmpnlt_ss x64 intrinsic", "_mm_cmpord_pd x64 intrinsic", "_mm_cmpord_ps x64 intrinsic", "_mm_cmpord_sd x64 intrinsic", "_mm_cmpord_ss x64 intrinsic", "_mm_cmpunord_pd x64 intrinsic", "_mm_cmpunord_ps x64 intrinsic", "_mm_cmpunord_sd x64 intrinsic", "_mm_cmpunord_ss x64 intrinsic", "_mm_com_epi16 x64 intrinsic", "_mm_com_epi32 x64 intrinsic", "_mm_com_epi64 x64 intrinsic", "_mm_com_epi8 x64 intrinsic", "_mm_com_epu16 x64 intrinsic", "_mm_com_epu32 x64 intrinsic", "_mm_com_epu64 x64 intrinsic", "_mm_com_epu8 x64 intrinsic", "_mm_comieq_sd x64 intrinsic", "_mm_comieq_ss x64 intrinsic", "_mm_comige_sd x64 intrinsic", "_mm_comige_ss x64 intrinsic", "_mm_comigt_sd x64 intrinsic", "_mm_comigt_ss x64 intrinsic", "_mm_comile_sd x64 intrinsic", "_mm_comile_ss x64 intrinsic", "_mm_comilt_sd x64 intrinsic", "_mm_comilt_ss x64 intrinsic", "_mm_comineq_sd x64 intrinsic", "_mm_comineq_ss x64 intrinsic", "_mm_crc32_u16 x64 intrinsic", "_mm_crc32_u32 x64 intrinsic", "_mm_crc32_u64 x64 intrinsic", "_mm_crc32_u8 x64 intrinsic", "_mm_cvt_si2ss x64 intrinsic", "_mm_cvt_ss2si x64 intrinsic", "_mm_cvtepi16_epi32 x64 intrinsic", "_mm_cvtepi16_epi64 x64 intrinsic", "_mm_cvtepi32_epi64 x64 intrinsic", "_mm_cvtepi32_pd x64 intrinsic", "_mm_cvtepi32_ps x64 intrinsic", "_mm_cvtepi8_epi16 x64 intrinsic", "_mm_cvtepi8_epi32 x64 intrinsic", "_mm_cvtepi8_epi64 x64 intrinsic", "_mm_cvtepu16_epi32 x64 intrinsic", "_mm_cvtepu16_epi64 x64 intrinsic", "_mm_cvtepu32_epi64 x64 intrinsic", "_mm_cvtepu8_epi16 x64 intrinsic", "_mm_cvtepu8_epi32 x64 intrinsic", "_mm_cvtepu8_epi64 x64 intrinsic", "_mm_cvtpd_epi32 x64 intrinsic", "_mm_cvtpd_ps x64 intrinsic", "_mm_cvtph_ps x64 intrinsic", "_mm_cvtps_epi32 x64 intrinsic", "_mm_cvtps_pd x64 intrinsic", "_mm_cvtps_ph x64 intrinsic", "_mm_cvtsd_f64 x64 intrinsic", "_mm_cvtsd_si32 x64 intrinsic", "_mm_cvtsd_si64 x64 intrinsic", "_mm_cvtsd_si64x x64 intrinsic", "_mm_cvtsd_ss x64 intrinsic", "_mm_cvtsi128_si32 x64 intrinsic", "_mm_cvtsi128_si64 x64 intrinsic", "_mm_cvtsi128_si64x x64 intrinsic", "_mm_cvtsi32_sd x64 intrinsic", "_mm_cvtsi32_si128 x64 intrinsic", "_mm_cvtsi64_sd x64 intrinsic", "_mm_cvtsi64_si128 x64 intrinsic", "_mm_cvtsi64_ss x64 intrinsic", "_mm_cvtsi64x_sd x64 intrinsic", "_mm_cvtsi64x_si128 x64 intrinsic", "_mm_cvtss_f32 x64 intrinsic", "_mm_cvtss_sd x64 intrinsic", "_mm_cvtss_si64 x64 intrinsic", "_mm_cvtt_ss2si x64 intrinsic", "_mm_cvttpd_epi32 x64 intrinsic", "_mm_cvttps_epi32 x64 intrinsic", "_mm_cvttsd_si32 x64 intrinsic", "_mm_cvttsd_si64 x64 intrinsic", "_mm_cvttsd_si64x x64 intrinsic", "_mm_cvttss_si64 x64 intrinsic", "_mm_div_pd x64 intrinsic", "_mm_div_ps x64 intrinsic", "_mm_div_sd x64 intrinsic", "_mm_div_ss x64 intrinsic", "_mm_dp_pd x64 intrinsic", "_mm_dp_ps x64 intrinsic", "_mm_extract_epi16 x64 intrinsic", "_mm_extract_epi32 x64 intrinsic", "_mm_extract_epi64 x64 intrinsic", "_mm_extract_epi8 x64 intrinsic", "_mm_extract_ps x64 intrinsic", "_mm_fmadd_pd x64 intrinsic", "_mm_fmadd_ps x64 intrinsic", "_mm_fmadd_sd x64 intrinsic", "_mm_fmadd_ss x64 intrinsic", "_mm_fmaddsub_pd x64 intrinsic", "_mm_fmaddsub_ps x64 intrinsic", "_mm_fmsub_pd x64 intrinsic", "_mm_fmsub_ps x64 intrinsic", "_mm_fmsub_sd x64 intrinsic", "_mm_fmsub_ss x64 intrinsic", "_mm_fmsubadd_pd x64 intrinsic", "_mm_fmsubadd_ps x64 intrinsic", "_mm_fnmadd_pd x64 intrinsic", "_mm_fnmadd_ps x64 intrinsic", "_mm_fnmadd_sd x64 intrinsic", "_mm_fnmadd_ss x64 intrinsic", "_mm_fnmsub_pd x64 intrinsic", "_mm_fnmsub_ps x64 intrinsic", "_mm_fnmsub_sd x64 intrinsic", "_mm_fnmsub_ss x64 intrinsic", "_mm_frcz_pd x64 intrinsic", "_mm_frcz_ps x64 intrinsic", "_mm_frcz_sd x64 intrinsic", "_mm_frcz_ss x64 intrinsic", "_mm_getcsr x64 intrinsic", "_mm_hadd_epi16 x64 intrinsic", "_mm_hadd_epi32 x64 intrinsic", "_mm_hadd_pd x64 intrinsic", "_mm_hadd_ps x64 intrinsic", "_mm_haddd_epi16 x64 intrinsic", "_mm_haddd_epi8 x64 intrinsic", "_mm_haddd_epu16 x64 intrinsic", "_mm_haddd_epu8 x64 intrinsic", "_mm_haddq_epi16 x64 intrinsic", "_mm_haddq_epi32 x64 intrinsic", "_mm_haddq_epi8 x64 intrinsic", "_mm_haddq_epu16 x64 intrinsic", "_mm_haddq_epu32 x64 intrinsic", "_mm_haddq_epu8 x64 intrinsic", "_mm_hadds_epi16 x64 intrinsic", "_mm_haddw_epi8 x64 intrinsic", "_mm_haddw_epu8 x64 intrinsic", "_mm_hsub_epi16 x64 intrinsic", "_mm_hsub_epi32 x64 intrinsic", "_mm_hsub_pd x64 intrinsic", "_mm_hsub_ps x64 intrinsic", "_mm_hsubd_epi16 x64 intrinsic", "_mm_hsubq_epi32 x64 intrinsic", "_mm_hsubs_epi16 x64 intrinsic", "_mm_hsubw_epi8 x64 intrinsic", "_mm_i32gather_epi32 x64 intrinsic", "_mm_i32gather_epi64 x64 intrinsic", "_mm_i32gather_pd x64 intrinsic", "_mm_i32gather_ps x64 intrinsic", "_mm_i64gather_epi32 x64 intrinsic", "_mm_i64gather_epi64 x64 intrinsic", "_mm_i64gather_pd x64 intrinsic", "_mm_i64gather_ps x64 intrinsic", "_mm_insert_epi16 x64 intrinsic", "_mm_insert_epi32 x64 intrinsic", "_mm_insert_epi64 x64 intrinsic", "_mm_insert_epi8 x64 intrinsic", "_mm_insert_ps x64 intrinsic", "_mm_lddqu_si128 x64 intrinsic", "_mm_lfence x64 intrinsic", "_mm_load_pd x64 intrinsic", "_mm_load_ps x64 intrinsic", "_mm_load_ps1 x64 intrinsic", "_mm_load_sd x64 intrinsic", "_mm_load_si128 x64 intrinsic", "_mm_load_ss x64 intrinsic", "_mm_load1_pd x64 intrinsic", "_mm_loaddup_pd x64 intrinsic", "_mm_loadh_pd x64 intrinsic", "_mm_loadh_pi x64 intrinsic", "_mm_loadl_epi64 x64 intrinsic", "_mm_loadl_pd x64 intrinsic", "_mm_loadl_pi x64 intrinsic", "_mm_loadr_pd x64 intrinsic", "_mm_loadr_ps x64 intrinsic", "_mm_loadu_pd x64 intrinsic", "_mm_loadu_ps x64 intrinsic", "_mm_loadu_si128 x64 intrinsic", "_mm_macc_epi16 x64 intrinsic", "_mm_macc_epi32 x64 intrinsic", "_mm_macc_pd x64 intrinsic", "_mm_macc_ps x64 intrinsic", "_mm_macc_sd x64 intrinsic", "_mm_macc_ss x64 intrinsic", "_mm_maccd_epi16 x64 intrinsic", "_mm_macchi_epi32 x64 intrinsic", "_mm_macclo_epi32 x64 intrinsic", "_mm_maccs_epi16 x64 intrinsic", "_mm_maccs_epi32 x64 intrinsic", "_mm_maccsd_epi16 x64 intrinsic", "_mm_maccshi_epi32 x64 intrinsic", "_mm_maccslo_epi32 x64 intrinsic", "_mm_madd_epi16 x64 intrinsic", "_mm_maddd_epi16 x64 intrinsic", "_mm_maddsd_epi16 x64 intrinsic", "_mm_maddsub_pd x64 intrinsic", "_mm_maddsub_ps x64 intrinsic", "_mm_maddubs_epi16 x64 intrinsic", "_mm_mask_i32gather_epi32 x64 intrinsic", "_mm_mask_i32gather_epi64 x64 intrinsic", "_mm_mask_i32gather_pd x64 intrinsic", "_mm_mask_i32gather_ps x64 intrinsic", "_mm_mask_i64gather_epi32 x64 intrinsic", "_mm_mask_i64gather_epi64 x64 intrinsic", "_mm_mask_i64gather_pd x64 intrinsic", "_mm_mask_i64gather_ps x64 intrinsic", "_mm_maskload_epi32 x64 intrinsic", "_mm_maskload_epi64 x64 intrinsic", "_mm_maskload_pd x64 intrinsic", "_mm_maskload_ps x64 intrinsic", "_mm_maskmoveu_si128 x64 intrinsic", "_mm_maskstore_epi32 x64 intrinsic", "_mm_maskstore_epi64 x64 intrinsic", "_mm_maskstore_pd x64 intrinsic", "_mm_maskstore_ps x64 intrinsic", "_mm_max_epi16 x64 intrinsic", "_mm_max_epi32 x64 intrinsic", "_mm_max_epi8 x64 intrinsic", "_mm_max_epu16 x64 intrinsic", "_mm_max_epu32 x64 intrinsic", "_mm_max_epu8 x64 intrinsic", "_mm_max_pd x64 intrinsic", "_mm_max_ps x64 intrinsic", "_mm_max_sd x64 intrinsic", "_mm_max_ss x64 intrinsic", "_mm_mfence x64 intrinsic", "_mm_min_epi16 x64 intrinsic", "_mm_min_epi32 x64 intrinsic", "_mm_min_epi8 x64 intrinsic", "_mm_min_epu16 x64 intrinsic", "_mm_min_epu32 x64 intrinsic", "_mm_min_epu8 x64 intrinsic", "_mm_min_pd x64 intrinsic", "_mm_min_ps x64 intrinsic", "_mm_min_sd x64 intrinsic", "_mm_min_ss x64 intrinsic", "_mm_minpos_epu16 x64 intrinsic", "_mm_monitor x64 intrinsic", "_mm_move_epi64 x64 intrinsic", "_mm_move_sd x64 intrinsic", "_mm_move_ss x64 intrinsic", "_mm_movedup_pd x64 intrinsic", "_mm_movehdup_ps x64 intrinsic", "_mm_movehl_ps x64 intrinsic", "_mm_moveldup_ps x64 intrinsic", "_mm_movelh_ps x64 intrinsic", "_mm_movemask_epi8 x64 intrinsic", "_mm_movemask_pd x64 intrinsic", "_mm_movemask_ps x64 intrinsic", "_mm_mpsadbw_epu8 x64 intrinsic", "_mm_msub_pd x64 intrinsic", "_mm_msub_ps x64 intrinsic", "_mm_msub_sd x64 intrinsic", "_mm_msub_ss x64 intrinsic", "_mm_msubadd_pd x64 intrinsic", "_mm_msubadd_ps x64 intrinsic", "_mm_mul_epi32 x64 intrinsic", "_mm_mul_epu32 x64 intrinsic", "_mm_mul_pd x64 intrinsic", "_mm_mul_ps x64 intrinsic", "_mm_mul_sd x64 intrinsic", "_mm_mul_ss x64 intrinsic", "_mm_mulhi_epi16 x64 intrinsic", "_mm_mulhi_epu16 x64 intrinsic", "_mm_mulhrs_epi16 x64 intrinsic", "_mm_mullo_epi16 x64 intrinsic", "_mm_mullo_epi32 x64 intrinsic", "_mm_mwait x64 intrinsic", "_mm_nmacc_pd x64 intrinsic", "_mm_nmacc_ps x64 intrinsic", "_mm_nmacc_sd x64 intrinsic", "_mm_nmacc_ss x64 intrinsic", "_mm_nmsub_pd x64 intrinsic", "_mm_nmsub_ps x64 intrinsic", "_mm_nmsub_sd x64 intrinsic", "_mm_nmsub_ss x64 intrinsic", "_mm_or_pd x64 intrinsic", "_mm_or_ps x64 intrinsic", "_mm_or_si128 x64 intrinsic", "_mm_packs_epi16 x64 intrinsic", "_mm_packs_epi32 x64 intrinsic", "_mm_packus_epi16 x64 intrinsic", "_mm_packus_epi32 x64 intrinsic", "_mm_pause x64 intrinsic", "_mm_perm_epi8 x64 intrinsic", "_mm_permute_pd x64 intrinsic", "_mm_permute_ps x64 intrinsic", "_mm_permute2_pd x64 intrinsic", "_mm_permute2_ps x64 intrinsic", "_mm_permutevar_pd x64 intrinsic", "_mm_permutevar_ps x64 intrinsic", "_mm_popcnt_u32 x64 intrinsic", "_mm_popcnt_u64 x64 intrinsic", "_mm_prefetch x64 intrinsic", "_mm_rcp_ps x64 intrinsic", "_mm_rcp_ss x64 intrinsic", "_mm_rot_epi16 x64 intrinsic", "_mm_rot_epi32 x64 intrinsic", "_mm_rot_epi64 x64 intrinsic", "_mm_rot_epi8 x64 intrinsic", "_mm_roti_epi16 x64 intrinsic", "_mm_roti_epi32 x64 intrinsic", "_mm_roti_epi64 x64 intrinsic", "_mm_roti_epi8 x64 intrinsic", "_mm_round_pd x64 intrinsic", "_mm_round_ps x64 intrinsic", "_mm_round_sd x64 intrinsic", "_mm_round_ss x64 intrinsic", "_mm_rsqrt_ps x64 intrinsic", "_mm_rsqrt_ss x64 intrinsic", "_mm_sad_epu8 x64 intrinsic", "_mm_set_epi16 x64 intrinsic", "_mm_set_epi32 x64 intrinsic", "_mm_set_epi64x x64 intrinsic", "_mm_set_epi8 x64 intrinsic", "_mm_set_pd x64 intrinsic", "_mm_set_ps x64 intrinsic", "_mm_set_ps1 x64 intrinsic", "_mm_set_sd x64 intrinsic", "_mm_set_ss x64 intrinsic", "_mm_set1_epi16 x64 intrinsic", "_mm_set1_epi32 x64 intrinsic", "_mm_set1_epi64x x64 intrinsic", "_mm_set1_epi8 x64 intrinsic", "_mm_set1_pd x64 intrinsic", "_mm_setcsr x64 intrinsic", "_mm_setl_epi64 x64 intrinsic", "_mm_setr_epi16 x64 intrinsic", "_mm_setr_epi32 x64 intrinsic", "_mm_setr_epi8 x64 intrinsic", "_mm_setr_pd x64 intrinsic", "_mm_setr_ps x64 intrinsic", "_mm_setzero_pd x64 intrinsic", "_mm_setzero_ps x64 intrinsic", "_mm_setzero_si128 x64 intrinsic", "_mm_sfence x64 intrinsic", "_mm_sha_epi16 x64 intrinsic", "_mm_sha_epi32 x64 intrinsic", "_mm_sha_epi64 x64 intrinsic", "_mm_sha_epi8 x64 intrinsic", "_mm_shl_epi16 x64 intrinsic", "_mm_shl_epi32 x64 intrinsic", "_mm_shl_epi64 x64 intrinsic", "_mm_shl_epi8 x64 intrinsic", "_mm_shuffle_epi32 x64 intrinsic", "_mm_shuffle_epi8 x64 intrinsic", "_mm_shuffle_pd x64 intrinsic", "_mm_shuffle_ps x64 intrinsic", "_mm_shufflehi_epi16 x64 intrinsic", "_mm_shufflelo_epi16 x64 intrinsic", "_mm_sign_epi16 x64 intrinsic", "_mm_sign_epi32 x64 intrinsic", "_mm_sign_epi8 x64 intrinsic", "_mm_sll_epi16 x64 intrinsic", "_mm_sll_epi32 x64 intrinsic", "_mm_sll_epi64 x64 intrinsic", "_mm_slli_epi16 x64 intrinsic", "_mm_slli_epi32 x64 intrinsic", "_mm_slli_epi64 x64 intrinsic", "_mm_slli_si128 x64 intrinsic", "_mm_sllv_epi32 x64 intrinsic", "_mm_sllv_epi64 x64 intrinsic", "_mm_sqrt_pd x64 intrinsic", "_mm_sqrt_ps x64 intrinsic", "_mm_sqrt_sd x64 intrinsic", "_mm_sqrt_ss x64 intrinsic", "_mm_sra_epi16 x64 intrinsic", "_mm_sra_epi32 x64 intrinsic", "_mm_srai_epi16 x64 intrinsic", "_mm_srai_epi32 x64 intrinsic", "_mm_srav_epi32 x64 intrinsic", "_mm_srl_epi16 x64 intrinsic", "_mm_srl_epi32 x64 intrinsic", "_mm_srl_epi64 x64 intrinsic", "_mm_srli_epi16 x64 intrinsic", "_mm_srli_epi32 x64 intrinsic", "_mm_srli_epi64 x64 intrinsic", "_mm_srli_si128 x64 intrinsic", "_mm_srlv_epi32 x64 intrinsic", "_mm_srlv_epi64 x64 intrinsic", "_mm_store_pd x64 intrinsic", "_mm_store_ps x64 intrinsic", "_mm_store_ps1 x64 intrinsic", "_mm_store_sd x64 intrinsic", "_mm_store_si128 x64 intrinsic", "_mm_store_ss x64 intrinsic", "_mm_store1_pd x64 intrinsic", "_mm_storeh_pd x64 intrinsic", "_mm_storeh_pi x64 intrinsic", "_mm_storel_epi64 x64 intrinsic", "_mm_storel_pd x64 intrinsic", "_mm_storel_pi x64 intrinsic", "_mm_storer_pd x64 intrinsic", "_mm_storer_ps x64 intrinsic", "_mm_storeu_pd x64 intrinsic", "_mm_storeu_ps x64 intrinsic", "_mm_storeu_si128 x64 intrinsic", "_mm_stream_load_si128 x64 intrinsic", "_mm_stream_pd x64 intrinsic", "_mm_stream_ps x64 intrinsic", "_mm_stream_si128 x64 intrinsic", "_mm_stream_si32 x64 intrinsic", "_mm_sub_epi16 x64 intrinsic", "_mm_sub_epi32 x64 intrinsic", "_mm_sub_epi64 x64 intrinsic", "_mm_sub_epi8 x64 intrinsic", "_mm_sub_pd x64 intrinsic", "_mm_sub_ps x64 intrinsic", "_mm_sub_sd x64 intrinsic", "_mm_sub_ss x64 intrinsic", "_mm_subs_epi16 x64 intrinsic", "_mm_subs_epi8 x64 intrinsic", "_mm_subs_epu16 x64 intrinsic", "_mm_subs_epu8 x64 intrinsic", "_mm_testc_pd x64 intrinsic", "_mm_testc_ps x64 intrinsic", "_mm_testc_si128 x64 intrinsic", "_mm_testnzc_pd x64 intrinsic", "_mm_testnzc_ps x64 intrinsic", "_mm_testnzc_si128 x64 intrinsic", "_mm_testz_pd x64 intrinsic", "_mm_testz_ps x64 intrinsic", "_mm_testz_si128 x64 intrinsic", "_mm_ucomieq_sd x64 intrinsic", "_mm_ucomieq_ss x64 intrinsic", "_mm_ucomige_sd x64 intrinsic", "_mm_ucomige_ss x64 intrinsic", "_mm_ucomigt_sd x64 intrinsic", "_mm_ucomigt_ss x64 intrinsic", "_mm_ucomile_sd x64 intrinsic", "_mm_ucomile_ss x64 intrinsic", "_mm_ucomilt_sd x64 intrinsic", "_mm_ucomilt_ss x64 intrinsic", "_mm_ucomineq_sd x64 intrinsic", "_mm_ucomineq_ss x64 intrinsic", "_mm_unpackhi_epi16 x64 intrinsic", "_mm_unpackhi_epi32 x64 intrinsic", "_mm_unpackhi_epi64 x64 intrinsic", "_mm_unpackhi_epi8 x64 intrinsic", "_mm_unpackhi_pd x64 intrinsic", "_mm_unpackhi_ps x64 intrinsic", "_mm_unpacklo_epi16 x64 intrinsic", "_mm_unpacklo_epi32 x64 intrinsic", "_mm_unpacklo_epi64 x64 intrinsic", "_mm_unpacklo_epi8 x64 intrinsic", "_mm_unpacklo_pd x64 intrinsic", "_mm_unpacklo_ps x64 intrinsic", "_mm_xor_pd x64 intrinsic", "_mm_xor_ps x64 intrinsic", "_mm_xor_si128 x64 intrinsic", "_mm256_abs_epi16 x64 intrinsic", "_mm256_abs_epi32 x64 intrinsic", "_mm256_abs_epi8 x64 intrinsic", "_mm256_add_epi16 x64 intrinsic", "_mm256_add_epi32 x64 intrinsic", "_mm256_add_epi64 x64 intrinsic", "_mm256_add_epi8 x64 intrinsic", "_mm256_add_pd x64 intrinsic", "_mm256_add_ps x64 intrinsic", "_mm256_adds_epi16 x64 intrinsic", "_mm256_adds_epi8 x64 intrinsic", "_mm256_adds_epu16 x64 intrinsic", "_mm256_adds_epu8 x64 intrinsic", "_mm256_addsub_pd x64 intrinsic", "_mm256_addsub_ps x64 intrinsic", "_mm256_alignr_epi8 x64 intrinsic", "_mm256_and_pd x64 intrinsic", "_mm256_and_ps x64 intrinsic", "_mm256_and_si256 x64 intrinsic", "_mm256_andnot_pd x64 intrinsic", "_mm256_andnot_ps x64 intrinsic", "_mm256_andnot_si256 x64 intrinsic", "_mm256_avg_epu16 x64 intrinsic", "_mm256_avg_epu8 x64 intrinsic", "_mm256_blend_epi16 x64 intrinsic", "_mm256_blend_epi32 x64 intrinsic", "_mm256_blend_pd x64 intrinsic", "_mm256_blend_ps x64 intrinsic", "_mm256_blendv_epi8 x64 intrinsic", "_mm256_blendv_pd x64 intrinsic", "_mm256_blendv_ps x64 intrinsic", "_mm256_broadcast_pd x64 intrinsic", "_mm256_broadcast_ps x64 intrinsic", "_mm256_broadcast_sd x64 intrinsic", "_mm256_broadcast_ss x64 intrinsic", "_mm256_broadcastb_epi8 x64 intrinsic", "_mm256_broadcastd_epi32 x64 intrinsic", "_mm256_broadcastq_epi64 x64 intrinsic", "_mm256_broadcastsd_pd x64 intrinsic", "_mm256_broadcastsi128_si256 x64 intrinsic", "_mm256_broadcastss_ps x64 intrinsic", "_mm256_broadcastw_epi16 x64 intrinsic", "_mm256_castpd_ps x64 intrinsic", "_mm256_castpd_si256 x64 intrinsic", "_mm256_castpd128_pd256 x64 intrinsic", "_mm256_castpd256_pd128 x64 intrinsic", "_mm256_castps_pd x64 intrinsic", "_mm256_castps_si256 x64 intrinsic", "_mm256_castps128_ps256 x64 intrinsic", "_mm256_castps256_ps128 x64 intrinsic", "_mm256_castsi128_si256 x64 intrinsic", "_mm256_castsi256_pd x64 intrinsic", "_mm256_castsi256_ps x64 intrinsic", "_mm256_castsi256_si128 x64 intrinsic", "_mm256_cmov_si256 x64 intrinsic", "_mm256_cmp_pd x64 intrinsic", "_mm256_cmp_ps x64 intrinsic", "_mm256_cmpeq_epi16 x64 intrinsic", "_mm256_cmpeq_epi32 x64 intrinsic", "_mm256_cmpeq_epi64 x64 intrinsic", "_mm256_cmpeq_epi8 x64 intrinsic", "_mm256_cmpgt_epi16 x64 intrinsic", "_mm256_cmpgt_epi32 x64 intrinsic", "_mm256_cmpgt_epi64 x64 intrinsic", "_mm256_cmpgt_epi8 x64 intrinsic", "_mm256_cvtepi16_epi32 x64 intrinsic", "_mm256_cvtepi16_epi64 x64 intrinsic", "_mm256_cvtepi32_epi64 x64 intrinsic", "_mm256_cvtepi32_pd x64 intrinsic", "_mm256_cvtepi32_ps x64 intrinsic", "_mm256_cvtepi8_epi16 x64 intrinsic", "_mm256_cvtepi8_epi32 x64 intrinsic", "_mm256_cvtepi8_epi64 x64 intrinsic", "_mm256_cvtepu16_epi32 x64 intrinsic", "_mm256_cvtepu16_epi64 x64 intrinsic", "_mm256_cvtepu32_epi64 x64 intrinsic", "_mm256_cvtepu8_epi16 x64 intrinsic", "_mm256_cvtepu8_epi32 x64 intrinsic", "_mm256_cvtepu8_epi64 x64 intrinsic", "_mm256_cvtpd_epi32 x64 intrinsic", "_mm256_cvtpd_ps x64 intrinsic", "_mm256_cvtph_ps x64 intrinsic", "_mm256_cvtps_epi32 x64 intrinsic", "_mm256_cvtps_pd x64 intrinsic", "_mm256_cvtps_ph x64 intrinsic", "_mm256_cvttpd_epi32 x64 intrinsic", "_mm256_cvttps_epi32 x64 intrinsic", "_mm256_div_pd x64 intrinsic", "_mm256_div_ps x64 intrinsic", "_mm256_dp_ps x64 intrinsic", "_mm256_extractf128_pd x64 intrinsic", "_mm256_extractf128_ps x64 intrinsic", "_mm256_extractf128_si256 x64 intrinsic", "_mm256_extracti128_si256 x64 intrinsic", "_mm256_fmadd_pd x64 intrinsic", "_mm256_fmadd_ps x64 intrinsic", "_mm256_fmaddsub_pd x64 intrinsic", "_mm256_fmaddsub_ps x64 intrinsic", "_mm256_fmsub_pd x64 intrinsic", "_mm256_fmsub_ps x64 intrinsic", "_mm256_fmsubadd_pd x64 intrinsic", "_mm256_fmsubadd_ps x64 intrinsic", "_mm256_fnmadd_pd x64 intrinsic", "_mm256_fnmadd_ps x64 intrinsic", "_mm256_fnmsub_pd x64 intrinsic", "_mm256_fnmsub_ps x64 intrinsic", "_mm256_frcz_pd x64 intrinsic", "_mm256_frcz_ps x64 intrinsic", "_mm256_hadd_epi16 x64 intrinsic", "_mm256_hadd_epi32 x64 intrinsic", "_mm256_hadd_pd x64 intrinsic", "_mm256_hadd_ps x64 intrinsic", "_mm256_hadds_epi16 x64 intrinsic", "_mm256_hsub_epi16 x64 intrinsic", "_mm256_hsub_epi32 x64 intrinsic", "_mm256_hsub_pd x64 intrinsic", "_mm256_hsub_ps x64 intrinsic", "_mm256_hsubs_epi16 x64 intrinsic", "_mm256_i32gather_epi32 x64 intrinsic", "_mm256_i32gather_epi64 x64 intrinsic", "_mm256_i32gather_pd x64 intrinsic", "_mm256_i32gather_ps x64 intrinsic", "_mm256_i64gather_epi32 x64 intrinsic", "_mm256_i64gather_epi64 x64 intrinsic", "_mm256_i64gather_pd x64 intrinsic", "_mm256_i64gather_ps x64 intrinsic", "_mm256_insertf128_pd x64 intrinsic", "_mm256_insertf128_ps x64 intrinsic", "_mm256_insertf128_si256 x64 intrinsic", "_mm256_inserti128_si256 x64 intrinsic", "_mm256_lddqu_si256 x64 intrinsic", "_mm256_load_pd x64 intrinsic", "_mm256_load_ps x64 intrinsic", "_mm256_load_si256 x64 intrinsic", "_mm256_loadu_pd x64 intrinsic", "_mm256_loadu_ps x64 intrinsic", "_mm256_loadu_si256 x64 intrinsic", "_mm256_macc_pd x64 intrinsic", "_mm256_macc_ps x64 intrinsic", "_mm256_madd_epi16 x64 intrinsic", "_mm256_maddsub_pd x64 intrinsic", "_mm256_maddsub_ps x64 intrinsic", "_mm256_maddubs_epi16 x64 intrinsic", "_mm256_mask_i32gather_epi32 x64 intrinsic", "_mm256_mask_i32gather_epi64 x64 intrinsic", "_mm256_mask_i32gather_pd x64 intrinsic", "_mm256_mask_i32gather_ps x64 intrinsic", "_mm256_mask_i64gather_epi32 x64 intrinsic", "_mm256_mask_i64gather_epi64 x64 intrinsic", "_mm256_mask_i64gather_pd x64 intrinsic", "_mm256_mask_i64gather_ps x64 intrinsic", "_mm256_maskload_epi32 x64 intrinsic", "_mm256_maskload_epi64 x64 intrinsic", "_mm256_maskload_pd x64 intrinsic", "_mm256_maskload_ps x64 intrinsic", "_mm256_maskstore_epi32 x64 intrinsic", "_mm256_maskstore_epi64 x64 intrinsic", "_mm256_maskstore_pd x64 intrinsic", "_mm256_maskstore_ps x64 intrinsic", "_mm256_max_epi16 x64 intrinsic", "_mm256_max_epi32 x64 intrinsic", "_mm256_max_epi8 x64 intrinsic", "_mm256_max_epu16 x64 intrinsic", "_mm256_max_epu32 x64 intrinsic", "_mm256_max_epu8 x64 intrinsic", "_mm256_max_pd x64 intrinsic", "_mm256_max_ps x64 intrinsic", "_mm256_min_epi16 x64 intrinsic", "_mm256_min_epi32 x64 intrinsic", "_mm256_min_epi8 x64 intrinsic", "_mm256_min_epu16 x64 intrinsic", "_mm256_min_epu32 x64 intrinsic", "_mm256_min_epu8 x64 intrinsic", "_mm256_min_pd x64 intrinsic", "_mm256_min_ps x64 intrinsic", "_mm256_movedup_pd x64 intrinsic", "_mm256_movehdup_ps x64 intrinsic", "_mm256_moveldup_ps x64 intrinsic", "_mm256_movemask_epi8 x64 intrinsic", "_mm256_movemask_pd x64 intrinsic", "_mm256_movemask_ps x64 intrinsic", "_mm256_mpsadbw_epu8 x64 intrinsic", "_mm256_msub_pd x64 intrinsic", "_mm256_msub_ps x64 intrinsic", "_mm256_msubadd_pd x64 intrinsic", "_mm256_msubadd_ps x64 intrinsic", "_mm256_mul_epi32 x64 intrinsic", "_mm256_mul_epu32 x64 intrinsic", "_mm256_mul_pd x64 intrinsic", "_mm256_mul_ps x64 intrinsic", "_mm256_mulhi_epi16 x64 intrinsic", "_mm256_mulhi_epu16 x64 intrinsic", "_mm256_mulhrs_epi16 x64 intrinsic", "_mm256_mullo_epi16 x64 intrinsic", "_mm256_mullo_epi32 x64 intrinsic", "_mm256_nmacc_pd x64 intrinsic", "_mm256_nmacc_ps x64 intrinsic", "_mm256_nmsub_pd x64 intrinsic", "_mm256_nmsub_ps x64 intrinsic", "_mm256_or_pd x64 intrinsic", "_mm256_or_ps x64 intrinsic", "_mm256_or_si256 x64 intrinsic", "_mm256_packs_epi16 x64 intrinsic", "_mm256_packs_epi32 x64 intrinsic", "_mm256_packus_epi16 x64 intrinsic", "_mm256_packus_epi32 x64 intrinsic", "_mm256_permute_pd x64 intrinsic", "_mm256_permute_ps x64 intrinsic", "_mm256_permute2_pd x64 intrinsic", "_mm256_permute2_ps x64 intrinsic", "_mm256_permute2f128_pd x64 intrinsic", "_mm256_permute2f128_ps x64 intrinsic", "_mm256_permute2f128_si256 x64 intrinsic", "_mm256_permute2x128_si256 x64 intrinsic", "_mm256_permute4x64_epi64 x64 intrinsic", "_mm256_permute4x64_pd x64 intrinsic", "_mm256_permutevar_pd x64 intrinsic", "_mm256_permutevar_ps x64 intrinsic", "_mm256_permutevar8x32_epi32 x64 intrinsic", "_mm256_permutevar8x32_ps x64 intrinsic", "_mm256_rcp_ps x64 intrinsic", "_mm256_round_pd x64 intrinsic", "_mm256_round_ps x64 intrinsic", "_mm256_rsqrt_ps x64 intrinsic", "_mm256_sad_epu8 x64 intrinsic", "_mm256_set_epi16 x64 intrinsic", "_mm256_set_epi32 x64 intrinsic", "_mm256_set_epi64x x64 intrinsic", "_mm256_set_epi8 x64 intrinsic", "_mm256_set_pd x64 intrinsic", "_mm256_set_ps x64 intrinsic", "_mm256_set1_epi16 x64 intrinsic", "_mm256_set1_epi32 x64 intrinsic", "_mm256_set1_epi64x x64 intrinsic", "_mm256_set1_epi8 x64 intrinsic", "_mm256_set1_pd x64 intrinsic", "_mm256_set1_ps x64 intrinsic", "_mm256_setr_epi16 x64 intrinsic", "_mm256_setr_epi32 x64 intrinsic", "_mm256_setr_epi64x x64 intrinsic", "_mm256_setr_epi8 x64 intrinsic", "_mm256_setr_pd x64 intrinsic", "_mm256_setr_ps x64 intrinsic", "_mm256_setzero_pd x64 intrinsic", "_mm256_setzero_ps x64 intrinsic", "_mm256_setzero_si256 x64 intrinsic", "_mm256_shuffle_epi32 x64 intrinsic", "_mm256_shuffle_epi8 x64 intrinsic", "_mm256_shuffle_pd x64 intrinsic", "_mm256_shuffle_ps x64 intrinsic", "_mm256_shufflehi_epi16 x64 intrinsic", "_mm256_shufflelo_epi16 x64 intrinsic", "_mm256_sign_epi16 x64 intrinsic", "_mm256_sign_epi32 x64 intrinsic", "_mm256_sign_epi8 x64 intrinsic", "_mm256_sll_epi16 x64 intrinsic", "_mm256_sll_epi32 x64 intrinsic", "_mm256_sll_epi64 x64 intrinsic", "_mm256_slli_epi16 x64 intrinsic", "_mm256_slli_epi32 x64 intrinsic", "_mm256_slli_epi64 x64 intrinsic", "_mm256_slli_si256 x64 intrinsic", "_mm256_sllv_epi32 x64 intrinsic", "_mm256_sllv_epi64 x64 intrinsic", "_mm256_sqrt_pd x64 intrinsic", "_mm256_sqrt_ps x64 intrinsic", "_mm256_sra_epi16 x64 intrinsic", "_mm256_sra_epi32 x64 intrinsic", "_mm256_srai_epi16 x64 intrinsic", "_mm256_srai_epi32 x64 intrinsic", "_mm256_srav_epi32 x64 intrinsic", "_mm256_srl_epi16 x64 intrinsic", "_mm256_srl_epi32 x64 intrinsic", "_mm256_srl_epi64 x64 intrinsic", "_mm256_srli_epi16 x64 intrinsic", "_mm256_srli_epi32 x64 intrinsic", "_mm256_srli_epi64 x64 intrinsic", "_mm256_srli_si256 x64 intrinsic", "_mm256_srlv_epi32 x64 intrinsic", "_mm256_srlv_epi64 x64 intrinsic", "_mm256_store_pd x64 intrinsic", "_mm256_store_ps x64 intrinsic", "_mm256_store_si256 x64 intrinsic", "_mm256_storeu_pd x64 intrinsic", "_mm256_storeu_ps x64 intrinsic", "_mm256_storeu_si256 x64 intrinsic", "_mm256_stream_load_si256 x64 intrinsic", "_mm256_stream_pd x64 intrinsic", "_mm256_stream_ps x64 intrinsic", "_mm256_stream_si256 x64 intrinsic", "_mm256_sub_epi16 x64 intrinsic", "_mm256_sub_epi32 x64 intrinsic", "_mm256_sub_epi64 x64 intrinsic", "_mm256_sub_epi8 x64 intrinsic", "_mm256_sub_pd x64 intrinsic", "_mm256_sub_ps x64 intrinsic", "_mm256_subs_epi16 x64 intrinsic", "_mm256_subs_epi8 x64 intrinsic", "_mm256_subs_epu16 x64 intrinsic", "_mm256_subs_epu8 x64 intrinsic", "_mm256_testc_pd x64 intrinsic", "_mm256_testc_ps x64 intrinsic", "_mm256_testc_si256 x64 intrinsic", "_mm256_testnzc_pd x64 intrinsic", "_mm256_testnzc_ps x64 intrinsic", "_mm256_testnzc_si256 x64 intrinsic", "_mm256_testz_pd x64 intrinsic", "_mm256_testz_ps x64 intrinsic", "_mm256_testz_si256 x64 intrinsic", "_mm256_unpackhi_epi16 x64 intrinsic", "_mm256_unpackhi_epi32 x64 intrinsic", "_mm256_unpackhi_epi64 x64 intrinsic", "_mm256_unpackhi_epi8 x64 intrinsic", "_mm256_unpackhi_pd x64 intrinsic", "_mm256_unpackhi_ps x64 intrinsic", "_mm256_unpacklo_epi16 x64 intrinsic", "_mm256_unpacklo_epi32 x64 intrinsic", "_mm256_unpacklo_epi64 x64 intrinsic", "_mm256_unpacklo_epi8 x64 intrinsic", "_mm256_unpacklo_pd x64 intrinsic", "_mm256_unpacklo_ps x64 intrinsic", "_mm256_xor_pd x64 intrinsic", "_mm256_xor_ps x64 intrinsic", "_mm256_xor_si256 x64 intrinsic", "_mm256_zeroall x64 intrinsic", "_mm256_zeroupper x64 intrinsic", "_mulx_u32 x64 intrinsic", "_mulx_u64 x64 intrinsic", "__nvreg_restore_fence x64 intrinsic", "__nvreg_save_fence x64 intrinsic", "_pdep_u32 x64 intrinsic", "_pdep_u64 x64 intrinsic", "_pext_u32 x64 intrinsic", "_pext_u64 x64 intrinsic", "_rdrand16_step x64 intrinsic", "_rdrand32_step x64 intrinsic", "_rdrand64_step x64 intrinsic", "_rdseed16_step x64 intrinsic", "_rdseed32_step x64 intrinsic", "_rdseed64_step x64 intrinsic", "_readfsbase_u32 x64 intrinsic", "_readfsbase_u64 x64 intrinsic", "_readgsbase_u32 x64 intrinsic", "_readgsbase_u64 x64 intrinsic", "_rorx_u32 x64 intrinsic", "_rorx_u64 x64 intrinsic", "_rsm x64 intrinsic", "_sarx_i32 x64 intrinsic", "_sarx_i64 x64 intrinsic", "_sgdt x64 intrinsic", "_shlx_u32 x64 intrinsic", "_shlx_u64 x64 intrinsic", "_shrx_u32 x64 intrinsic", "_shrx_u64 x64 intrinsic", "__slwpcb x64 intrinsic", "_stac x64 intrinsic", "_store_be_u16 x64 intrinsic", "_storebe_i16 x64 intrinsic", "_store_be_u32 x64 intrinsic", "_storebe_i32 x64 intrinsic", "_store_be_u64 x64 intrinsic", "_storebe_i64 x64 intrinsic", "_Store_HLERelease x64 intrinsic", "_Store64_HLERelease x64 intrinsic", "_StorePointer_HLERelease x64 intrinsic", "_subborrow_u16 x64 intrinsic", "_subborrow_u32 x64 intrinsic", "_subborrow_u64 x64 intrinsic", "_subborrow_u8 x64 intrinsic", "_t1mskc_u32 x64 intrinsic", "_t1mskc_u64 x64 intrinsic", "_tzcnt_u32 x64 intrinsic", "_tzcnt_u64 x64 intrinsic", "_tzmsk_u32 x64 intrinsic", "_tzmsk_u64 x64 intrinsic", "_writefsbase_u32 x64 intrinsic", "_writefsbase_u64 x64 intrinsic", "_writegsbase_u32 x64 intrinsic", "_writegsbase_u64 x64 intrinsic", "_xabort x64 intrinsic", "_xbegin x64 intrinsic", "_xend x64 intrinsic", "_xgetbv x64 intrinsic", "_xrstor x64 intrinsic", "_xrstor64 x64 intrinsic", "_xsave x64 intrinsic", "_xsave64 x64 intrinsic", "_xsaveopt x64 intrinsic", "_xsaveopt64 x64 intrinsic", "_xsetbv x64 intrinsic", "_xtest x64 intrinsic"] +ms.date: 08/30/2022 +f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u64", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "immintrin/_addcarryx_u64", "ammintrin/_andn_u32", "ammintrin/_andn_u64", "ammintrin/_bextr_u32", "ammintrin/_bextr_u64", "ammintrin/_bextri_u32", "ammintrin/_bextri_u64", "ammintrin/_blcfill_u32", "ammintrin/_blcfill_u64", "ammintrin/_blci_u32", "ammintrin/_blci_u64", "ammintrin/_blcic_u32", "ammintrin/_blcic_u64", "ammintrin/_blcmsk_u32", "ammintrin/_blcmsk_u64", "ammintrin/_blcs_u32", "ammintrin/_blcs_u64", "ammintrin/_blsfill_u32", "ammintrin/_blsfill_u64", "ammintrin/_blsi_u32", "ammintrin/_blsi_u64", "ammintrin/_blsic_u32", "ammintrin/_blsic_u64", "ammintrin/_blsmsk_u32", "ammintrin/_blsmsk_u64", "ammintrin/_blsr_u32", "ammintrin/_blsr_u64", "immintrin/_bzhi_u32", "immintrin/_bzhi_u64", "immintrin/_castf32_u32", "immintrin/_castf64_u64", "immintrin/_castu32_f32", "immintrin/_castu64_f64", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxrstor64", "immintrin/_fxsave", "immintrin/_fxsave64", "immintrin/_invpcid", "intrin/_lgdt", "ammintrin/__llwpcb", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "immintrin/_load_be_u64", "immintrin/_loadbe_i64", "ammintrin/__lwpins32", "ammintrin/__lwpins64", "ammintrin/__lwpval32", "ammintrin/__lwpval64", "ammintrin/_lzcnt_u32", "ammintrin/_lzcnt_u64", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u64", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_si64", "intrin/_mm_cvtsd_si64x", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi128_si64", "intrin/_mm_cvtsi128_si64x", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "intrin/_mm_cvtsi64_sd", "intrin/_mm_cvtsi64_si128", "intrin/_mm_cvtsi64_ss", "intrin/_mm_cvtsi64x_sd", "intrin/_mm_cvtsi64x_si128", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtss_si64", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_cvttsd_si64", "intrin/_mm_cvttsd_si64x", "intrin/_mm_cvttss_si64", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi64", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi64", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_popcnt_u64", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64x", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64x", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi64x", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi64x", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi64x", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "immintrin/_mulx_u64", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pdep_u64", "immintrin/_pext_u32", "immintrin/_pext_u64", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdrand64_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rdseed64_step", "immintrin/_readfsbase_u32", "immintrin/_readfsbase_u64", "immintrin/_readgsbase_u32", "immintrin/_readgsbase_u64", "immintrin/_rorx_u32", "immintrin/_rorx_u64", "intrin/_rsm", "immintrin/_sarx_i32", "immintrin/_sarx_i64", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shlx_u64", "immintrin/_shrx_u32", "immintrin/_shrx_u64", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_store_be_u64", "immintrin/_storebe_i64", "immintrin/_Store_HLERelease", "immintrin/_Store64_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u64", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_t1mskc_u64", "ammintrin/_tzcnt_u32", "ammintrin/_tzcnt_u64", "ammintrin/_tzmsk_u32", "ammintrin/_tzmsk_u64", "immintrin/_writefsbase_u32", "immintrin/_writefsbase_u64", "immintrin/_writegsbase_u32", "immintrin/_writegsbase_u64", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xrstor64", "immintrin/_xsave", "immintrin/_xsave64", "immintrin/_xsaveopt", "immintrin/_xsaveopt64", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_mm_add_ps", "XMMINTRIN/_mm_add_ss", "XMMINTRIN/_mm_and_ps", "XMMINTRIN/_mm_andnot_ps", "XMMINTRIN/_mm_cmpeq_ps", "XMMINTRIN/_mm_cmpeq_ss", "XMMINTRIN/_mm_cmpge_ps", "XMMINTRIN/_mm_cmpge_ss", "XMMINTRIN/_mm_cmpgt_ps", "XMMINTRIN/_mm_cmpgt_ss", "XMMINTRIN/_mm_cmple_ps", "XMMINTRIN/_mm_cmple_ss", "XMMINTRIN/_mm_cmplt_ps", "XMMINTRIN/_mm_cmplt_ss", "XMMINTRIN/_mm_cmpneq_ps", "XMMINTRIN/_mm_cmpneq_ss", "XMMINTRIN/_mm_cmpnge_ps", "XMMINTRIN/_mm_cmpnge_ss", "XMMINTRIN/_mm_cmpngt_ps", "XMMINTRIN/_mm_cmpngt_ss", "XMMINTRIN/_mm_cmpnle_ps", "XMMINTRIN/_mm_cmpnle_ss", "XMMINTRIN/_mm_cmpnlt_ps", "XMMINTRIN/_mm_cmpnlt_ss", "XMMINTRIN/_mm_cmpord_ps", "XMMINTRIN/_mm_cmpord_ss", "XMMINTRIN/_mm_cmpunord_ps", "XMMINTRIN/_mm_cmpunord_ss", "XMMINTRIN/_mm_comieq_ss", "XMMINTRIN/_mm_comige_ss", "XMMINTRIN/_mm_comigt_ss", "XMMINTRIN/_mm_comile_ss", "XMMINTRIN/_mm_comilt_ss", "XMMINTRIN/_mm_comineq_ss", "XMMINTRIN/_mm_cvt_si2ss", "XMMINTRIN/_mm_cvt_ss2si", "XMMINTRIN/_mm_cvtpi16_ps", "XMMINTRIN/_mm_cvtpi32x2_ps", "XMMINTRIN/_mm_cvtpi8_ps", "XMMINTRIN/_mm_cvtps_pi16", "XMMINTRIN/_mm_cvtps_pi8", "XMMINTRIN/_mm_cvtpu16_ps", "XMMINTRIN/_mm_cvtpu8_ps", "XMMINTRIN/_mm_cvtsi32_ss", "XMMINTRIN/_mm_cvtsi64_ss", "XMMINTRIN/_mm_cvtss_f32", "XMMINTRIN/_mm_cvtss_si32", "XMMINTRIN/_mm_cvtss_si64", "XMMINTRIN/_mm_cvtt_ss2si", "XMMINTRIN/_mm_cvttss_si32", "XMMINTRIN/_mm_cvttss_si64", "XMMINTRIN/_mm_div_ps", "XMMINTRIN/_mm_div_ss", "XMMINTRIN/_mm_getcsr", "XMMINTRIN/_mm_load_ps", "XMMINTRIN/_mm_load_ps1", "XMMINTRIN/_mm_load_ss", "XMMINTRIN/_mm_load1_ps", "XMMINTRIN/_mm_loadh_pi", "XMMINTRIN/_mm_loadl_pi", "XMMINTRIN/_mm_loadr_ps", "XMMINTRIN/_mm_loadu_ps", "XMMINTRIN/_mm_max_ps", "XMMINTRIN/_mm_max_ss", "XMMINTRIN/_mm_min_ps", "XMMINTRIN/_mm_min_ss", "XMMINTRIN/_mm_move_ss", "XMMINTRIN/_mm_movehl_ps", "XMMINTRIN/_mm_movelh_ps", "XMMINTRIN/_mm_movemask_ps", "XMMINTRIN/_mm_mul_ps", "XMMINTRIN/_mm_mul_ss", "XMMINTRIN/_mm_or_ps", "XMMINTRIN/_mm_prefetch", "XMMINTRIN/_mm_rcp_ps", "XMMINTRIN/_mm_rcp_ss", "XMMINTRIN/_mm_rsqrt_ps", "XMMINTRIN/_mm_rsqrt_ss", "XMMINTRIN/_mm_set_ps", "XMMINTRIN/_mm_set_ps1", "XMMINTRIN/_mm_set_ss", "XMMINTRIN/_mm_set1_ps", "XMMINTRIN/_mm_setcsr", "XMMINTRIN/_mm_setr_ps", "XMMINTRIN/_mm_setzero_ps", "XMMINTRIN/_mm_sfence", "XMMINTRIN/_mm_shuffle_ps", "XMMINTRIN/_mm_sqrt_ps", "XMMINTRIN/_mm_sqrt_ss", "XMMINTRIN/_mm_store_ps", "XMMINTRIN/_mm_store_ps1", "XMMINTRIN/_mm_store_ss", "XMMINTRIN/_mm_store1_ps", "XMMINTRIN/_mm_storeh_pi", "XMMINTRIN/_mm_storel_pi", "XMMINTRIN/_mm_storer_ps", "XMMINTRIN/_mm_storeu_ps", "XMMINTRIN/_mm_stream_ps", "XMMINTRIN/_mm_sub_ps", "XMMINTRIN/_mm_sub_ss", "XMMINTRIN/_mm_ucomieq_ss", "XMMINTRIN/_mm_ucomige_ss", "XMMINTRIN/_mm_ucomigt_ss", "XMMINTRIN/_mm_ucomile_ss", "XMMINTRIN/_mm_ucomilt_ss", "XMMINTRIN/_mm_ucomineq_ss", "XMMINTRIN/_mm_unpackhi_ps", "XMMINTRIN/_mm_unpacklo_ps", "XMMINTRIN/_mm_xor_ps"] +helpviewer_keywords: ["cl-exe compiler, intrinsics", "intrinsics, x64", "intrinsics, amd64", "_addcarry_u16 x64 intrinsic", "_addcarry_u32 x64 intrinsic", "_addcarry_u64 x64 intrinsic", "_addcarry_u8 x64 intrinsic", "_addcarryx_u32 x64 intrinsic", "_addcarryx_u64 x64 intrinsic", "_andn_u32 x64 intrinsic", "_andn_u64 x64 intrinsic", "_bextr_u32 x64 intrinsic", "_bextr_u64 x64 intrinsic", "_bextri_u32 x64 intrinsic", "_bextri_u64 x64 intrinsic", "_blcfill_u32 x64 intrinsic", "_blcfill_u64 x64 intrinsic", "_blci_u32 x64 intrinsic", "_blci_u64 x64 intrinsic", "_blcic_u32 x64 intrinsic", "_blcic_u64 x64 intrinsic", "_blcmsk_u32 x64 intrinsic", "_blcmsk_u64 x64 intrinsic", "_blcs_u32 x64 intrinsic", "_blcs_u64 x64 intrinsic", "_blsfill_u32 x64 intrinsic", "_blsfill_u64 x64 intrinsic", "_blsi_u32 x64 intrinsic", "_blsi_u64 x64 intrinsic", "_blsic_u32 x64 intrinsic", "_blsic_u64 x64 intrinsic", "_blsmsk_u32 x64 intrinsic", "_blsmsk_u64 x64 intrinsic", "_blsr_u32 x64 intrinsic", "_blsr_u64 x64 intrinsic", "_bzhi_u32 x64 intrinsic", "_bzhi_u64 x64 intrinsic", "_castf32_u32 x64 intrinsic", "_castf64_u64 x64 intrinsic", "_castu32_f32 x64 intrinsic", "_castu64_f64 x64 intrinsic", "_clac x64 intrinsic", "_fxrstor x64 intrinsic", "_fxrstor64 x64 intrinsic", "_fxsave x64 intrinsic", "_fxsave64 x64 intrinsic", "_invpcid x64 intrinsic", "_lgdt x64 intrinsic", "__llwpcb x64 intrinsic", "_load_be_u16 x64 intrinsic", "_loadbe_i16 x64 intrinsic", "_load_be_u32 x64 intrinsic", "_loadbe_i32 x64 intrinsic", "_load_be_u64 x64 intrinsic", "_loadbe_i64 x64 intrinsic", "__lwpins32 x64 intrinsic", "__lwpins64 x64 intrinsic", "__lwpval32 x64 intrinsic", "__lwpval64 x64 intrinsic", "_lzcnt_u32 x64 intrinsic", "_lzcnt_u64 x64 intrinsic", "_m_prefetch x64 intrinsic", "_m_prefetchw x64 intrinsic", "_mm_abs_epi16 x64 intrinsic", "_mm_abs_epi32 x64 intrinsic", "_mm_abs_epi8 x64 intrinsic", "_mm_add_epi16 x64 intrinsic", "_mm_add_epi32 x64 intrinsic", "_mm_add_epi64 x64 intrinsic", "_mm_add_epi8 x64 intrinsic", "_mm_add_pd x64 intrinsic", "_mm_add_ps x64 intrinsic", "_mm_add_sd x64 intrinsic", "_mm_add_ss x64 intrinsic", "_mm_adds_epi16 x64 intrinsic", "_mm_adds_epi8 x64 intrinsic", "_mm_adds_epu16 x64 intrinsic", "_mm_adds_epu8 x64 intrinsic", "_mm_addsub_pd x64 intrinsic", "_mm_addsub_ps x64 intrinsic", "_mm_aesdec_si128 x64 intrinsic", "_mm_aesdeclast_si128 x64 intrinsic", "_mm_aesenc_si128 x64 intrinsic", "_mm_aesenclast_si128 x64 intrinsic", "_mm_aesimc_si128 x64 intrinsic", "_mm_aeskeygenassist_si128 x64 intrinsic", "_mm_alignr_epi8 x64 intrinsic", "_mm_and_pd x64 intrinsic", "_mm_and_ps x64 intrinsic", "_mm_and_si128 x64 intrinsic", "_mm_andnot_pd x64 intrinsic", "_mm_andnot_ps x64 intrinsic", "_mm_andnot_si128 x64 intrinsic", "_mm_avg_epu16 x64 intrinsic", "_mm_avg_epu8 x64 intrinsic", "_mm_blend_epi16 x64 intrinsic", "_mm_blend_epi32 x64 intrinsic", "_mm_blend_pd x64 intrinsic", "_mm_blend_ps x64 intrinsic", "_mm_blendv_epi8 x64 intrinsic", "_mm_blendv_pd x64 intrinsic", "_mm_blendv_ps x64 intrinsic", "_mm_broadcast_ss x64 intrinsic", "_mm_broadcastb_epi8 x64 intrinsic", "_mm_broadcastd_epi32 x64 intrinsic", "_mm_broadcastq_epi64 x64 intrinsic", "_mm_broadcastsd_pd x64 intrinsic", "_mm_broadcastss_ps x64 intrinsic", "_mm_broadcastw_epi16 x64 intrinsic", "_mm_castpd_ps x64 intrinsic", "_mm_castpd_si128 x64 intrinsic", "_mm_castps_pd x64 intrinsic", "_mm_castps_si128 x64 intrinsic", "_mm_castsi128_pd x64 intrinsic", "_mm_castsi128_ps x64 intrinsic", "_mm_clflush x64 intrinsic", "_mm_clmulepi64_si128 x64 intrinsic", "_mm_cmov_si128 x64 intrinsic", "_mm_cmp_pd x64 intrinsic", "_mm_cmp_ps x64 intrinsic", "_mm_cmp_sd x64 intrinsic", "_mm_cmp_ss x64 intrinsic", "_mm_cmpeq_epi16 x64 intrinsic", "_mm_cmpeq_epi32 x64 intrinsic", "_mm_cmpeq_epi64 x64 intrinsic", "_mm_cmpeq_epi8 x64 intrinsic", "_mm_cmpeq_pd x64 intrinsic", "_mm_cmpeq_ps x64 intrinsic", "_mm_cmpeq_sd x64 intrinsic", "_mm_cmpeq_ss x64 intrinsic", "_mm_cmpestra x64 intrinsic", "_mm_cmpestrc x64 intrinsic", "_mm_cmpestri x64 intrinsic", "_mm_cmpestrm x64 intrinsic", "_mm_cmpestro x64 intrinsic", "_mm_cmpestrs x64 intrinsic", "_mm_cmpestrz x64 intrinsic", "_mm_cmpge_pd x64 intrinsic", "_mm_cmpge_ps x64 intrinsic", "_mm_cmpge_sd x64 intrinsic", "_mm_cmpge_ss x64 intrinsic", "_mm_cmpgt_epi16 x64 intrinsic", "_mm_cmpgt_epi32 x64 intrinsic", "_mm_cmpgt_epi64 x64 intrinsic", "_mm_cmpgt_epi8 x64 intrinsic", "_mm_cmpgt_pd x64 intrinsic", "_mm_cmpgt_ps x64 intrinsic", "_mm_cmpgt_sd x64 intrinsic", "_mm_cmpgt_ss x64 intrinsic", "_mm_cmpistra x64 intrinsic", "_mm_cmpistrc x64 intrinsic", "_mm_cmpistri x64 intrinsic", "_mm_cmpistrm x64 intrinsic", "_mm_cmpistro x64 intrinsic", "_mm_cmpistrs x64 intrinsic", "_mm_cmpistrz x64 intrinsic", "_mm_cmple_pd x64 intrinsic", "_mm_cmple_ps x64 intrinsic", "_mm_cmple_sd x64 intrinsic", "_mm_cmple_ss x64 intrinsic", "_mm_cmplt_epi16 x64 intrinsic", "_mm_cmplt_epi32 x64 intrinsic", "_mm_cmplt_epi8 x64 intrinsic", "_mm_cmplt_pd x64 intrinsic", "_mm_cmplt_ps x64 intrinsic", "_mm_cmplt_sd x64 intrinsic", "_mm_cmplt_ss x64 intrinsic", "_mm_cmpneq_pd x64 intrinsic", "_mm_cmpneq_ps x64 intrinsic", "_mm_cmpneq_sd x64 intrinsic", "_mm_cmpneq_ss x64 intrinsic", "_mm_cmpnge_pd x64 intrinsic", "_mm_cmpnge_ps x64 intrinsic", "_mm_cmpnge_sd x64 intrinsic", "_mm_cmpnge_ss x64 intrinsic", "_mm_cmpngt_pd x64 intrinsic", "_mm_cmpngt_ps x64 intrinsic", "_mm_cmpngt_sd x64 intrinsic", "_mm_cmpngt_ss x64 intrinsic", "_mm_cmpnle_pd x64 intrinsic", "_mm_cmpnle_ps x64 intrinsic", "_mm_cmpnle_sd x64 intrinsic", "_mm_cmpnle_ss x64 intrinsic", "_mm_cmpnlt_pd x64 intrinsic", "_mm_cmpnlt_ps x64 intrinsic", "_mm_cmpnlt_sd x64 intrinsic", "_mm_cmpnlt_ss x64 intrinsic", "_mm_cmpord_pd x64 intrinsic", "_mm_cmpord_ps x64 intrinsic", "_mm_cmpord_sd x64 intrinsic", "_mm_cmpord_ss x64 intrinsic", "_mm_cmpunord_pd x64 intrinsic", "_mm_cmpunord_ps x64 intrinsic", "_mm_cmpunord_sd x64 intrinsic", "_mm_cmpunord_ss x64 intrinsic", "_mm_com_epi16 x64 intrinsic", "_mm_com_epi32 x64 intrinsic", "_mm_com_epi64 x64 intrinsic", "_mm_com_epi8 x64 intrinsic", "_mm_com_epu16 x64 intrinsic", "_mm_com_epu32 x64 intrinsic", "_mm_com_epu64 x64 intrinsic", "_mm_com_epu8 x64 intrinsic", "_mm_comieq_sd x64 intrinsic", "_mm_comieq_ss x64 intrinsic", "_mm_comige_sd x64 intrinsic", "_mm_comige_ss x64 intrinsic", "_mm_comigt_sd x64 intrinsic", "_mm_comigt_ss x64 intrinsic", "_mm_comile_sd x64 intrinsic", "_mm_comile_ss x64 intrinsic", "_mm_comilt_sd x64 intrinsic", "_mm_comilt_ss x64 intrinsic", "_mm_comineq_sd x64 intrinsic", "_mm_comineq_ss x64 intrinsic", "_mm_crc32_u16 x64 intrinsic", "_mm_crc32_u32 x64 intrinsic", "_mm_crc32_u64 x64 intrinsic", "_mm_crc32_u8 x64 intrinsic", "_mm_cvt_si2ss x64 intrinsic", "_mm_cvt_ss2si x64 intrinsic", "_mm_cvtepi16_epi32 x64 intrinsic", "_mm_cvtepi16_epi64 x64 intrinsic", "_mm_cvtepi32_epi64 x64 intrinsic", "_mm_cvtepi32_pd x64 intrinsic", "_mm_cvtepi32_ps x64 intrinsic", "_mm_cvtepi8_epi16 x64 intrinsic", "_mm_cvtepi8_epi32 x64 intrinsic", "_mm_cvtepi8_epi64 x64 intrinsic", "_mm_cvtepu16_epi32 x64 intrinsic", "_mm_cvtepu16_epi64 x64 intrinsic", "_mm_cvtepu32_epi64 x64 intrinsic", "_mm_cvtepu8_epi16 x64 intrinsic", "_mm_cvtepu8_epi32 x64 intrinsic", "_mm_cvtepu8_epi64 x64 intrinsic", "_mm_cvtpd_epi32 x64 intrinsic", "_mm_cvtpd_ps x64 intrinsic", "_mm_cvtph_ps x64 intrinsic", "_mm_cvtps_epi32 x64 intrinsic", "_mm_cvtps_pd x64 intrinsic", "_mm_cvtps_ph x64 intrinsic", "_mm_cvtsd_f64 x64 intrinsic", "_mm_cvtsd_si32 x64 intrinsic", "_mm_cvtsd_si64 x64 intrinsic", "_mm_cvtsd_si64x x64 intrinsic", "_mm_cvtsd_ss x64 intrinsic", "_mm_cvtsi128_si32 x64 intrinsic", "_mm_cvtsi128_si64 x64 intrinsic", "_mm_cvtsi128_si64x x64 intrinsic", "_mm_cvtsi32_sd x64 intrinsic", "_mm_cvtsi32_si128 x64 intrinsic", "_mm_cvtsi64_sd x64 intrinsic", "_mm_cvtsi64_si128 x64 intrinsic", "_mm_cvtsi64_ss x64 intrinsic", "_mm_cvtsi64x_sd x64 intrinsic", "_mm_cvtsi64x_si128 x64 intrinsic", "_mm_cvtss_f32 x64 intrinsic", "_mm_cvtss_sd x64 intrinsic", "_mm_cvtss_si64 x64 intrinsic", "_mm_cvtt_ss2si x64 intrinsic", "_mm_cvttpd_epi32 x64 intrinsic", "_mm_cvttps_epi32 x64 intrinsic", "_mm_cvttsd_si32 x64 intrinsic", "_mm_cvttsd_si64 x64 intrinsic", "_mm_cvttsd_si64x x64 intrinsic", "_mm_cvttss_si64 x64 intrinsic", "_mm_div_pd x64 intrinsic", "_mm_div_ps x64 intrinsic", "_mm_div_sd x64 intrinsic", "_mm_div_ss x64 intrinsic", "_mm_dp_pd x64 intrinsic", "_mm_dp_ps x64 intrinsic", "_mm_extract_epi16 x64 intrinsic", "_mm_extract_epi32 x64 intrinsic", "_mm_extract_epi64 x64 intrinsic", "_mm_extract_epi8 x64 intrinsic", "_mm_extract_ps x64 intrinsic", "_mm_fmadd_pd x64 intrinsic", "_mm_fmadd_ps x64 intrinsic", "_mm_fmadd_sd x64 intrinsic", "_mm_fmadd_ss x64 intrinsic", "_mm_fmaddsub_pd x64 intrinsic", "_mm_fmaddsub_ps x64 intrinsic", "_mm_fmsub_pd x64 intrinsic", "_mm_fmsub_ps x64 intrinsic", "_mm_fmsub_sd x64 intrinsic", "_mm_fmsub_ss x64 intrinsic", "_mm_fmsubadd_pd x64 intrinsic", "_mm_fmsubadd_ps x64 intrinsic", "_mm_fnmadd_pd x64 intrinsic", "_mm_fnmadd_ps x64 intrinsic", "_mm_fnmadd_sd x64 intrinsic", "_mm_fnmadd_ss x64 intrinsic", "_mm_fnmsub_pd x64 intrinsic", "_mm_fnmsub_ps x64 intrinsic", "_mm_fnmsub_sd x64 intrinsic", "_mm_fnmsub_ss x64 intrinsic", "_mm_frcz_pd x64 intrinsic", "_mm_frcz_ps x64 intrinsic", "_mm_frcz_sd x64 intrinsic", "_mm_frcz_ss x64 intrinsic", "_mm_getcsr x64 intrinsic", "_mm_hadd_epi16 x64 intrinsic", "_mm_hadd_epi32 x64 intrinsic", "_mm_hadd_pd x64 intrinsic", "_mm_hadd_ps x64 intrinsic", "_mm_haddd_epi16 x64 intrinsic", "_mm_haddd_epi8 x64 intrinsic", "_mm_haddd_epu16 x64 intrinsic", "_mm_haddd_epu8 x64 intrinsic", "_mm_haddq_epi16 x64 intrinsic", "_mm_haddq_epi32 x64 intrinsic", "_mm_haddq_epi8 x64 intrinsic", "_mm_haddq_epu16 x64 intrinsic", "_mm_haddq_epu32 x64 intrinsic", "_mm_haddq_epu8 x64 intrinsic", "_mm_hadds_epi16 x64 intrinsic", "_mm_haddw_epi8 x64 intrinsic", "_mm_haddw_epu8 x64 intrinsic", "_mm_hsub_epi16 x64 intrinsic", "_mm_hsub_epi32 x64 intrinsic", "_mm_hsub_pd x64 intrinsic", "_mm_hsub_ps x64 intrinsic", "_mm_hsubd_epi16 x64 intrinsic", "_mm_hsubq_epi32 x64 intrinsic", "_mm_hsubs_epi16 x64 intrinsic", "_mm_hsubw_epi8 x64 intrinsic", "_mm_i32gather_epi32 x64 intrinsic", "_mm_i32gather_epi64 x64 intrinsic", "_mm_i32gather_pd x64 intrinsic", "_mm_i32gather_ps x64 intrinsic", "_mm_i64gather_epi32 x64 intrinsic", "_mm_i64gather_epi64 x64 intrinsic", "_mm_i64gather_pd x64 intrinsic", "_mm_i64gather_ps x64 intrinsic", "_mm_insert_epi16 x64 intrinsic", "_mm_insert_epi32 x64 intrinsic", "_mm_insert_epi64 x64 intrinsic", "_mm_insert_epi8 x64 intrinsic", "_mm_insert_ps x64 intrinsic", "_mm_lddqu_si128 x64 intrinsic", "_mm_lfence x64 intrinsic", "_mm_load_pd x64 intrinsic", "_mm_load_ps x64 intrinsic", "_mm_load_ps1 x64 intrinsic", "_mm_load_sd x64 intrinsic", "_mm_load_si128 x64 intrinsic", "_mm_load_ss x64 intrinsic", "_mm_load1_pd x64 intrinsic", "_mm_loaddup_pd x64 intrinsic", "_mm_loadh_pd x64 intrinsic", "_mm_loadh_pi x64 intrinsic", "_mm_loadl_epi64 x64 intrinsic", "_mm_loadl_pd x64 intrinsic", "_mm_loadl_pi x64 intrinsic", "_mm_loadr_pd x64 intrinsic", "_mm_loadr_ps x64 intrinsic", "_mm_loadu_pd x64 intrinsic", "_mm_loadu_ps x64 intrinsic", "_mm_loadu_si128 x64 intrinsic", "_mm_macc_epi16 x64 intrinsic", "_mm_macc_epi32 x64 intrinsic", "_mm_macc_pd x64 intrinsic", "_mm_macc_ps x64 intrinsic", "_mm_macc_sd x64 intrinsic", "_mm_macc_ss x64 intrinsic", "_mm_maccd_epi16 x64 intrinsic", "_mm_macchi_epi32 x64 intrinsic", "_mm_macclo_epi32 x64 intrinsic", "_mm_maccs_epi16 x64 intrinsic", "_mm_maccs_epi32 x64 intrinsic", "_mm_maccsd_epi16 x64 intrinsic", "_mm_maccshi_epi32 x64 intrinsic", "_mm_maccslo_epi32 x64 intrinsic", "_mm_madd_epi16 x64 intrinsic", "_mm_maddd_epi16 x64 intrinsic", "_mm_maddsd_epi16 x64 intrinsic", "_mm_maddsub_pd x64 intrinsic", "_mm_maddsub_ps x64 intrinsic", "_mm_maddubs_epi16 x64 intrinsic", "_mm_mask_i32gather_epi32 x64 intrinsic", "_mm_mask_i32gather_epi64 x64 intrinsic", "_mm_mask_i32gather_pd x64 intrinsic", "_mm_mask_i32gather_ps x64 intrinsic", "_mm_mask_i64gather_epi32 x64 intrinsic", "_mm_mask_i64gather_epi64 x64 intrinsic", "_mm_mask_i64gather_pd x64 intrinsic", "_mm_mask_i64gather_ps x64 intrinsic", "_mm_maskload_epi32 x64 intrinsic", "_mm_maskload_epi64 x64 intrinsic", "_mm_maskload_pd x64 intrinsic", "_mm_maskload_ps x64 intrinsic", "_mm_maskmoveu_si128 x64 intrinsic", "_mm_maskstore_epi32 x64 intrinsic", "_mm_maskstore_epi64 x64 intrinsic", "_mm_maskstore_pd x64 intrinsic", "_mm_maskstore_ps x64 intrinsic", "_mm_max_epi16 x64 intrinsic", "_mm_max_epi32 x64 intrinsic", "_mm_max_epi8 x64 intrinsic", "_mm_max_epu16 x64 intrinsic", "_mm_max_epu32 x64 intrinsic", "_mm_max_epu8 x64 intrinsic", "_mm_max_pd x64 intrinsic", "_mm_max_ps x64 intrinsic", "_mm_max_sd x64 intrinsic", "_mm_max_ss x64 intrinsic", "_mm_mfence x64 intrinsic", "_mm_min_epi16 x64 intrinsic", "_mm_min_epi32 x64 intrinsic", "_mm_min_epi8 x64 intrinsic", "_mm_min_epu16 x64 intrinsic", "_mm_min_epu32 x64 intrinsic", "_mm_min_epu8 x64 intrinsic", "_mm_min_pd x64 intrinsic", "_mm_min_ps x64 intrinsic", "_mm_min_sd x64 intrinsic", "_mm_min_ss x64 intrinsic", "_mm_minpos_epu16 x64 intrinsic", "_mm_monitor x64 intrinsic", "_mm_move_epi64 x64 intrinsic", "_mm_move_sd x64 intrinsic", "_mm_move_ss x64 intrinsic", "_mm_movedup_pd x64 intrinsic", "_mm_movehdup_ps x64 intrinsic", "_mm_movehl_ps x64 intrinsic", "_mm_moveldup_ps x64 intrinsic", "_mm_movelh_ps x64 intrinsic", "_mm_movemask_epi8 x64 intrinsic", "_mm_movemask_pd x64 intrinsic", "_mm_movemask_ps x64 intrinsic", "_mm_mpsadbw_epu8 x64 intrinsic", "_mm_msub_pd x64 intrinsic", "_mm_msub_ps x64 intrinsic", "_mm_msub_sd x64 intrinsic", "_mm_msub_ss x64 intrinsic", "_mm_msubadd_pd x64 intrinsic", "_mm_msubadd_ps x64 intrinsic", "_mm_mul_epi32 x64 intrinsic", "_mm_mul_epu32 x64 intrinsic", "_mm_mul_pd x64 intrinsic", "_mm_mul_ps x64 intrinsic", "_mm_mul_sd x64 intrinsic", "_mm_mul_ss x64 intrinsic", "_mm_mulhi_epi16 x64 intrinsic", "_mm_mulhi_epu16 x64 intrinsic", "_mm_mulhrs_epi16 x64 intrinsic", "_mm_mullo_epi16 x64 intrinsic", "_mm_mullo_epi32 x64 intrinsic", "_mm_mwait x64 intrinsic", "_mm_nmacc_pd x64 intrinsic", "_mm_nmacc_ps x64 intrinsic", "_mm_nmacc_sd x64 intrinsic", "_mm_nmacc_ss x64 intrinsic", "_mm_nmsub_pd x64 intrinsic", "_mm_nmsub_ps x64 intrinsic", "_mm_nmsub_sd x64 intrinsic", "_mm_nmsub_ss x64 intrinsic", "_mm_or_pd x64 intrinsic", "_mm_or_ps x64 intrinsic", "_mm_or_si128 x64 intrinsic", "_mm_packs_epi16 x64 intrinsic", "_mm_packs_epi32 x64 intrinsic", "_mm_packus_epi16 x64 intrinsic", "_mm_packus_epi32 x64 intrinsic", "_mm_pause x64 intrinsic", "_mm_perm_epi8 x64 intrinsic", "_mm_permute_pd x64 intrinsic", "_mm_permute_ps x64 intrinsic", "_mm_permute2_pd x64 intrinsic", "_mm_permute2_ps x64 intrinsic", "_mm_permutevar_pd x64 intrinsic", "_mm_permutevar_ps x64 intrinsic", "_mm_popcnt_u32 x64 intrinsic", "_mm_popcnt_u64 x64 intrinsic", "_mm_prefetch x64 intrinsic", "_mm_rcp_ps x64 intrinsic", "_mm_rcp_ss x64 intrinsic", "_mm_rot_epi16 x64 intrinsic", "_mm_rot_epi32 x64 intrinsic", "_mm_rot_epi64 x64 intrinsic", "_mm_rot_epi8 x64 intrinsic", "_mm_roti_epi16 x64 intrinsic", "_mm_roti_epi32 x64 intrinsic", "_mm_roti_epi64 x64 intrinsic", "_mm_roti_epi8 x64 intrinsic", "_mm_round_pd x64 intrinsic", "_mm_round_ps x64 intrinsic", "_mm_round_sd x64 intrinsic", "_mm_round_ss x64 intrinsic", "_mm_rsqrt_ps x64 intrinsic", "_mm_rsqrt_ss x64 intrinsic", "_mm_sad_epu8 x64 intrinsic", "_mm_set_epi16 x64 intrinsic", "_mm_set_epi32 x64 intrinsic", "_mm_set_epi64x x64 intrinsic", "_mm_set_epi8 x64 intrinsic", "_mm_set_pd x64 intrinsic", "_mm_set_ps x64 intrinsic", "_mm_set_ps1 x64 intrinsic", "_mm_set_sd x64 intrinsic", "_mm_set_ss x64 intrinsic", "_mm_set1_epi16 x64 intrinsic", "_mm_set1_epi32 x64 intrinsic", "_mm_set1_epi64x x64 intrinsic", "_mm_set1_epi8 x64 intrinsic", "_mm_set1_pd x64 intrinsic", "_mm_setcsr x64 intrinsic", "_mm_setl_epi64 x64 intrinsic", "_mm_setr_epi16 x64 intrinsic", "_mm_setr_epi32 x64 intrinsic", "_mm_setr_epi8 x64 intrinsic", "_mm_setr_pd x64 intrinsic", "_mm_setr_ps x64 intrinsic", "_mm_setzero_pd x64 intrinsic", "_mm_setzero_ps x64 intrinsic", "_mm_setzero_si128 x64 intrinsic", "_mm_sfence x64 intrinsic", "_mm_sha_epi16 x64 intrinsic", "_mm_sha_epi32 x64 intrinsic", "_mm_sha_epi64 x64 intrinsic", "_mm_sha_epi8 x64 intrinsic", "_mm_shl_epi16 x64 intrinsic", "_mm_shl_epi32 x64 intrinsic", "_mm_shl_epi64 x64 intrinsic", "_mm_shl_epi8 x64 intrinsic", "_mm_shuffle_epi32 x64 intrinsic", "_mm_shuffle_epi8 x64 intrinsic", "_mm_shuffle_pd x64 intrinsic", "_mm_shuffle_ps x64 intrinsic", "_mm_shufflehi_epi16 x64 intrinsic", "_mm_shufflelo_epi16 x64 intrinsic", "_mm_sign_epi16 x64 intrinsic", "_mm_sign_epi32 x64 intrinsic", "_mm_sign_epi8 x64 intrinsic", "_mm_sll_epi16 x64 intrinsic", "_mm_sll_epi32 x64 intrinsic", "_mm_sll_epi64 x64 intrinsic", "_mm_slli_epi16 x64 intrinsic", "_mm_slli_epi32 x64 intrinsic", "_mm_slli_epi64 x64 intrinsic", "_mm_slli_si128 x64 intrinsic", "_mm_sllv_epi32 x64 intrinsic", "_mm_sllv_epi64 x64 intrinsic", "_mm_sqrt_pd x64 intrinsic", "_mm_sqrt_ps x64 intrinsic", "_mm_sqrt_sd x64 intrinsic", "_mm_sqrt_ss x64 intrinsic", "_mm_sra_epi16 x64 intrinsic", "_mm_sra_epi32 x64 intrinsic", "_mm_srai_epi16 x64 intrinsic", "_mm_srai_epi32 x64 intrinsic", "_mm_srav_epi32 x64 intrinsic", "_mm_srl_epi16 x64 intrinsic", "_mm_srl_epi32 x64 intrinsic", "_mm_srl_epi64 x64 intrinsic", "_mm_srli_epi16 x64 intrinsic", "_mm_srli_epi32 x64 intrinsic", "_mm_srli_epi64 x64 intrinsic", "_mm_srli_si128 x64 intrinsic", "_mm_srlv_epi32 x64 intrinsic", "_mm_srlv_epi64 x64 intrinsic", "_mm_store_pd x64 intrinsic", "_mm_store_ps x64 intrinsic", "_mm_store_ps1 x64 intrinsic", "_mm_store_sd x64 intrinsic", "_mm_store_si128 x64 intrinsic", "_mm_store_ss x64 intrinsic", "_mm_store1_pd x64 intrinsic", "_mm_storeh_pd x64 intrinsic", "_mm_storeh_pi x64 intrinsic", "_mm_storel_epi64 x64 intrinsic", "_mm_storel_pd x64 intrinsic", "_mm_storel_pi x64 intrinsic", "_mm_storer_pd x64 intrinsic", "_mm_storer_ps x64 intrinsic", "_mm_storeu_pd x64 intrinsic", "_mm_storeu_ps x64 intrinsic", "_mm_storeu_si128 x64 intrinsic", "_mm_stream_load_si128 x64 intrinsic", "_mm_stream_pd x64 intrinsic", "_mm_stream_ps x64 intrinsic", "_mm_stream_si128 x64 intrinsic", "_mm_stream_si32 x64 intrinsic", "_mm_sub_epi16 x64 intrinsic", "_mm_sub_epi32 x64 intrinsic", "_mm_sub_epi64 x64 intrinsic", "_mm_sub_epi8 x64 intrinsic", "_mm_sub_pd x64 intrinsic", "_mm_sub_ps x64 intrinsic", "_mm_sub_sd x64 intrinsic", "_mm_sub_ss x64 intrinsic", "_mm_subs_epi16 x64 intrinsic", "_mm_subs_epi8 x64 intrinsic", "_mm_subs_epu16 x64 intrinsic", "_mm_subs_epu8 x64 intrinsic", "_mm_testc_pd x64 intrinsic", "_mm_testc_ps x64 intrinsic", "_mm_testc_si128 x64 intrinsic", "_mm_testnzc_pd x64 intrinsic", "_mm_testnzc_ps x64 intrinsic", "_mm_testnzc_si128 x64 intrinsic", "_mm_testz_pd x64 intrinsic", "_mm_testz_ps x64 intrinsic", "_mm_testz_si128 x64 intrinsic", "_mm_ucomieq_sd x64 intrinsic", "_mm_ucomieq_ss x64 intrinsic", "_mm_ucomige_sd x64 intrinsic", "_mm_ucomige_ss x64 intrinsic", "_mm_ucomigt_sd x64 intrinsic", "_mm_ucomigt_ss x64 intrinsic", "_mm_ucomile_sd x64 intrinsic", "_mm_ucomile_ss x64 intrinsic", "_mm_ucomilt_sd x64 intrinsic", "_mm_ucomilt_ss x64 intrinsic", "_mm_ucomineq_sd x64 intrinsic", "_mm_ucomineq_ss x64 intrinsic", "_mm_unpackhi_epi16 x64 intrinsic", "_mm_unpackhi_epi32 x64 intrinsic", "_mm_unpackhi_epi64 x64 intrinsic", "_mm_unpackhi_epi8 x64 intrinsic", "_mm_unpackhi_pd x64 intrinsic", "_mm_unpackhi_ps x64 intrinsic", "_mm_unpacklo_epi16 x64 intrinsic", "_mm_unpacklo_epi32 x64 intrinsic", "_mm_unpacklo_epi64 x64 intrinsic", "_mm_unpacklo_epi8 x64 intrinsic", "_mm_unpacklo_pd x64 intrinsic", "_mm_unpacklo_ps x64 intrinsic", "_mm_xor_pd x64 intrinsic", "_mm_xor_ps x64 intrinsic", "_mm_xor_si128 x64 intrinsic", "_mm256_abs_epi16 x64 intrinsic", "_mm256_abs_epi32 x64 intrinsic", "_mm256_abs_epi8 x64 intrinsic", "_mm256_add_epi16 x64 intrinsic", "_mm256_add_epi32 x64 intrinsic", "_mm256_add_epi64 x64 intrinsic", "_mm256_add_epi8 x64 intrinsic", "_mm256_add_pd x64 intrinsic", "_mm256_add_ps x64 intrinsic", "_mm256_adds_epi16 x64 intrinsic", "_mm256_adds_epi8 x64 intrinsic", "_mm256_adds_epu16 x64 intrinsic", "_mm256_adds_epu8 x64 intrinsic", "_mm256_addsub_pd x64 intrinsic", "_mm256_addsub_ps x64 intrinsic", "_mm256_alignr_epi8 x64 intrinsic", "_mm256_and_pd x64 intrinsic", "_mm256_and_ps x64 intrinsic", "_mm256_and_si256 x64 intrinsic", "_mm256_andnot_pd x64 intrinsic", "_mm256_andnot_ps x64 intrinsic", "_mm256_andnot_si256 x64 intrinsic", "_mm256_avg_epu16 x64 intrinsic", "_mm256_avg_epu8 x64 intrinsic", "_mm256_blend_epi16 x64 intrinsic", "_mm256_blend_epi32 x64 intrinsic", "_mm256_blend_pd x64 intrinsic", "_mm256_blend_ps x64 intrinsic", "_mm256_blendv_epi8 x64 intrinsic", "_mm256_blendv_pd x64 intrinsic", "_mm256_blendv_ps x64 intrinsic", "_mm256_broadcast_pd x64 intrinsic", "_mm256_broadcast_ps x64 intrinsic", "_mm256_broadcast_sd x64 intrinsic", "_mm256_broadcast_ss x64 intrinsic", "_mm256_broadcastb_epi8 x64 intrinsic", "_mm256_broadcastd_epi32 x64 intrinsic", "_mm256_broadcastq_epi64 x64 intrinsic", "_mm256_broadcastsd_pd x64 intrinsic", "_mm256_broadcastsi128_si256 x64 intrinsic", "_mm256_broadcastss_ps x64 intrinsic", "_mm256_broadcastw_epi16 x64 intrinsic", "_mm256_castpd_ps x64 intrinsic", "_mm256_castpd_si256 x64 intrinsic", "_mm256_castpd128_pd256 x64 intrinsic", "_mm256_castpd256_pd128 x64 intrinsic", "_mm256_castps_pd x64 intrinsic", "_mm256_castps_si256 x64 intrinsic", "_mm256_castps128_ps256 x64 intrinsic", "_mm256_castps256_ps128 x64 intrinsic", "_mm256_castsi128_si256 x64 intrinsic", "_mm256_castsi256_pd x64 intrinsic", "_mm256_castsi256_ps x64 intrinsic", "_mm256_castsi256_si128 x64 intrinsic", "_mm256_cmov_si256 x64 intrinsic", "_mm256_cmp_pd x64 intrinsic", "_mm256_cmp_ps x64 intrinsic", "_mm256_cmpeq_epi16 x64 intrinsic", "_mm256_cmpeq_epi32 x64 intrinsic", "_mm256_cmpeq_epi64 x64 intrinsic", "_mm256_cmpeq_epi8 x64 intrinsic", "_mm256_cmpgt_epi16 x64 intrinsic", "_mm256_cmpgt_epi32 x64 intrinsic", "_mm256_cmpgt_epi64 x64 intrinsic", "_mm256_cmpgt_epi8 x64 intrinsic", "_mm256_cvtepi16_epi32 x64 intrinsic", "_mm256_cvtepi16_epi64 x64 intrinsic", "_mm256_cvtepi32_epi64 x64 intrinsic", "_mm256_cvtepi32_pd x64 intrinsic", "_mm256_cvtepi32_ps x64 intrinsic", "_mm256_cvtepi8_epi16 x64 intrinsic", "_mm256_cvtepi8_epi32 x64 intrinsic", "_mm256_cvtepi8_epi64 x64 intrinsic", "_mm256_cvtepu16_epi32 x64 intrinsic", "_mm256_cvtepu16_epi64 x64 intrinsic", "_mm256_cvtepu32_epi64 x64 intrinsic", "_mm256_cvtepu8_epi16 x64 intrinsic", "_mm256_cvtepu8_epi32 x64 intrinsic", "_mm256_cvtepu8_epi64 x64 intrinsic", "_mm256_cvtpd_epi32 x64 intrinsic", "_mm256_cvtpd_ps x64 intrinsic", "_mm256_cvtph_ps x64 intrinsic", "_mm256_cvtps_epi32 x64 intrinsic", "_mm256_cvtps_pd x64 intrinsic", "_mm256_cvtps_ph x64 intrinsic", "_mm256_cvttpd_epi32 x64 intrinsic", "_mm256_cvttps_epi32 x64 intrinsic", "_mm256_div_pd x64 intrinsic", "_mm256_div_ps x64 intrinsic", "_mm256_dp_ps x64 intrinsic", "_mm256_extractf128_pd x64 intrinsic", "_mm256_extractf128_ps x64 intrinsic", "_mm256_extractf128_si256 x64 intrinsic", "_mm256_extracti128_si256 x64 intrinsic", "_mm256_fmadd_pd x64 intrinsic", "_mm256_fmadd_ps x64 intrinsic", "_mm256_fmaddsub_pd x64 intrinsic", "_mm256_fmaddsub_ps x64 intrinsic", "_mm256_fmsub_pd x64 intrinsic", "_mm256_fmsub_ps x64 intrinsic", "_mm256_fmsubadd_pd x64 intrinsic", "_mm256_fmsubadd_ps x64 intrinsic", "_mm256_fnmadd_pd x64 intrinsic", "_mm256_fnmadd_ps x64 intrinsic", "_mm256_fnmsub_pd x64 intrinsic", "_mm256_fnmsub_ps x64 intrinsic", "_mm256_frcz_pd x64 intrinsic", "_mm256_frcz_ps x64 intrinsic", "_mm256_hadd_epi16 x64 intrinsic", "_mm256_hadd_epi32 x64 intrinsic", "_mm256_hadd_pd x64 intrinsic", "_mm256_hadd_ps x64 intrinsic", "_mm256_hadds_epi16 x64 intrinsic", "_mm256_hsub_epi16 x64 intrinsic", "_mm256_hsub_epi32 x64 intrinsic", "_mm256_hsub_pd x64 intrinsic", "_mm256_hsub_ps x64 intrinsic", "_mm256_hsubs_epi16 x64 intrinsic", "_mm256_i32gather_epi32 x64 intrinsic", "_mm256_i32gather_epi64 x64 intrinsic", "_mm256_i32gather_pd x64 intrinsic", "_mm256_i32gather_ps x64 intrinsic", "_mm256_i64gather_epi32 x64 intrinsic", "_mm256_i64gather_epi64 x64 intrinsic", "_mm256_i64gather_pd x64 intrinsic", "_mm256_i64gather_ps x64 intrinsic", "_mm256_insertf128_pd x64 intrinsic", "_mm256_insertf128_ps x64 intrinsic", "_mm256_insertf128_si256 x64 intrinsic", "_mm256_inserti128_si256 x64 intrinsic", "_mm256_lddqu_si256 x64 intrinsic", "_mm256_load_pd x64 intrinsic", "_mm256_load_ps x64 intrinsic", "_mm256_load_si256 x64 intrinsic", "_mm256_loadu_pd x64 intrinsic", "_mm256_loadu_ps x64 intrinsic", "_mm256_loadu_si256 x64 intrinsic", "_mm256_macc_pd x64 intrinsic", "_mm256_macc_ps x64 intrinsic", "_mm256_madd_epi16 x64 intrinsic", "_mm256_maddsub_pd x64 intrinsic", "_mm256_maddsub_ps x64 intrinsic", "_mm256_maddubs_epi16 x64 intrinsic", "_mm256_mask_i32gather_epi32 x64 intrinsic", "_mm256_mask_i32gather_epi64 x64 intrinsic", "_mm256_mask_i32gather_pd x64 intrinsic", "_mm256_mask_i32gather_ps x64 intrinsic", "_mm256_mask_i64gather_epi32 x64 intrinsic", "_mm256_mask_i64gather_epi64 x64 intrinsic", "_mm256_mask_i64gather_pd x64 intrinsic", "_mm256_mask_i64gather_ps x64 intrinsic", "_mm256_maskload_epi32 x64 intrinsic", "_mm256_maskload_epi64 x64 intrinsic", "_mm256_maskload_pd x64 intrinsic", "_mm256_maskload_ps x64 intrinsic", "_mm256_maskstore_epi32 x64 intrinsic", "_mm256_maskstore_epi64 x64 intrinsic", "_mm256_maskstore_pd x64 intrinsic", "_mm256_maskstore_ps x64 intrinsic", "_mm256_max_epi16 x64 intrinsic", "_mm256_max_epi32 x64 intrinsic", "_mm256_max_epi8 x64 intrinsic", "_mm256_max_epu16 x64 intrinsic", "_mm256_max_epu32 x64 intrinsic", "_mm256_max_epu8 x64 intrinsic", "_mm256_max_pd x64 intrinsic", "_mm256_max_ps x64 intrinsic", "_mm256_min_epi16 x64 intrinsic", "_mm256_min_epi32 x64 intrinsic", "_mm256_min_epi8 x64 intrinsic", "_mm256_min_epu16 x64 intrinsic", "_mm256_min_epu32 x64 intrinsic", "_mm256_min_epu8 x64 intrinsic", "_mm256_min_pd x64 intrinsic", "_mm256_min_ps x64 intrinsic", "_mm256_movedup_pd x64 intrinsic", "_mm256_movehdup_ps x64 intrinsic", "_mm256_moveldup_ps x64 intrinsic", "_mm256_movemask_epi8 x64 intrinsic", "_mm256_movemask_pd x64 intrinsic", "_mm256_movemask_ps x64 intrinsic", "_mm256_mpsadbw_epu8 x64 intrinsic", "_mm256_msub_pd x64 intrinsic", "_mm256_msub_ps x64 intrinsic", "_mm256_msubadd_pd x64 intrinsic", "_mm256_msubadd_ps x64 intrinsic", "_mm256_mul_epi32 x64 intrinsic", "_mm256_mul_epu32 x64 intrinsic", "_mm256_mul_pd x64 intrinsic", "_mm256_mul_ps x64 intrinsic", "_mm256_mulhi_epi16 x64 intrinsic", "_mm256_mulhi_epu16 x64 intrinsic", "_mm256_mulhrs_epi16 x64 intrinsic", "_mm256_mullo_epi16 x64 intrinsic", "_mm256_mullo_epi32 x64 intrinsic", "_mm256_nmacc_pd x64 intrinsic", "_mm256_nmacc_ps x64 intrinsic", "_mm256_nmsub_pd x64 intrinsic", "_mm256_nmsub_ps x64 intrinsic", "_mm256_or_pd x64 intrinsic", "_mm256_or_ps x64 intrinsic", "_mm256_or_si256 x64 intrinsic", "_mm256_packs_epi16 x64 intrinsic", "_mm256_packs_epi32 x64 intrinsic", "_mm256_packus_epi16 x64 intrinsic", "_mm256_packus_epi32 x64 intrinsic", "_mm256_permute_pd x64 intrinsic", "_mm256_permute_ps x64 intrinsic", "_mm256_permute2_pd x64 intrinsic", "_mm256_permute2_ps x64 intrinsic", "_mm256_permute2f128_pd x64 intrinsic", "_mm256_permute2f128_ps x64 intrinsic", "_mm256_permute2f128_si256 x64 intrinsic", "_mm256_permute2x128_si256 x64 intrinsic", "_mm256_permute4x64_epi64 x64 intrinsic", "_mm256_permute4x64_pd x64 intrinsic", "_mm256_permutevar_pd x64 intrinsic", "_mm256_permutevar_ps x64 intrinsic", "_mm256_permutevar8x32_epi32 x64 intrinsic", "_mm256_permutevar8x32_ps x64 intrinsic", "_mm256_rcp_ps x64 intrinsic", "_mm256_round_pd x64 intrinsic", "_mm256_round_ps x64 intrinsic", "_mm256_rsqrt_ps x64 intrinsic", "_mm256_sad_epu8 x64 intrinsic", "_mm256_set_epi16 x64 intrinsic", "_mm256_set_epi32 x64 intrinsic", "_mm256_set_epi64x x64 intrinsic", "_mm256_set_epi8 x64 intrinsic", "_mm256_set_pd x64 intrinsic", "_mm256_set_ps x64 intrinsic", "_mm256_set1_epi16 x64 intrinsic", "_mm256_set1_epi32 x64 intrinsic", "_mm256_set1_epi64x x64 intrinsic", "_mm256_set1_epi8 x64 intrinsic", "_mm256_set1_pd x64 intrinsic", "_mm256_set1_ps x64 intrinsic", "_mm256_setr_epi16 x64 intrinsic", "_mm256_setr_epi32 x64 intrinsic", "_mm256_setr_epi64x x64 intrinsic", "_mm256_setr_epi8 x64 intrinsic", "_mm256_setr_pd x64 intrinsic", "_mm256_setr_ps x64 intrinsic", "_mm256_setzero_pd x64 intrinsic", "_mm256_setzero_ps x64 intrinsic", "_mm256_setzero_si256 x64 intrinsic", "_mm256_shuffle_epi32 x64 intrinsic", "_mm256_shuffle_epi8 x64 intrinsic", "_mm256_shuffle_pd x64 intrinsic", "_mm256_shuffle_ps x64 intrinsic", "_mm256_shufflehi_epi16 x64 intrinsic", "_mm256_shufflelo_epi16 x64 intrinsic", "_mm256_sign_epi16 x64 intrinsic", "_mm256_sign_epi32 x64 intrinsic", "_mm256_sign_epi8 x64 intrinsic", "_mm256_sll_epi16 x64 intrinsic", "_mm256_sll_epi32 x64 intrinsic", "_mm256_sll_epi64 x64 intrinsic", "_mm256_slli_epi16 x64 intrinsic", "_mm256_slli_epi32 x64 intrinsic", "_mm256_slli_epi64 x64 intrinsic", "_mm256_slli_si256 x64 intrinsic", "_mm256_sllv_epi32 x64 intrinsic", "_mm256_sllv_epi64 x64 intrinsic", "_mm256_sqrt_pd x64 intrinsic", "_mm256_sqrt_ps x64 intrinsic", "_mm256_sra_epi16 x64 intrinsic", "_mm256_sra_epi32 x64 intrinsic", "_mm256_srai_epi16 x64 intrinsic", "_mm256_srai_epi32 x64 intrinsic", "_mm256_srav_epi32 x64 intrinsic", "_mm256_srl_epi16 x64 intrinsic", "_mm256_srl_epi32 x64 intrinsic", "_mm256_srl_epi64 x64 intrinsic", "_mm256_srli_epi16 x64 intrinsic", "_mm256_srli_epi32 x64 intrinsic", "_mm256_srli_epi64 x64 intrinsic", "_mm256_srli_si256 x64 intrinsic", "_mm256_srlv_epi32 x64 intrinsic", "_mm256_srlv_epi64 x64 intrinsic", "_mm256_store_pd x64 intrinsic", "_mm256_store_ps x64 intrinsic", "_mm256_store_si256 x64 intrinsic", "_mm256_storeu_pd x64 intrinsic", "_mm256_storeu_ps x64 intrinsic", "_mm256_storeu_si256 x64 intrinsic", "_mm256_stream_load_si256 x64 intrinsic", "_mm256_stream_pd x64 intrinsic", "_mm256_stream_ps x64 intrinsic", "_mm256_stream_si256 x64 intrinsic", "_mm256_sub_epi16 x64 intrinsic", "_mm256_sub_epi32 x64 intrinsic", "_mm256_sub_epi64 x64 intrinsic", "_mm256_sub_epi8 x64 intrinsic", "_mm256_sub_pd x64 intrinsic", "_mm256_sub_ps x64 intrinsic", "_mm256_subs_epi16 x64 intrinsic", "_mm256_subs_epi8 x64 intrinsic", "_mm256_subs_epu16 x64 intrinsic", "_mm256_subs_epu8 x64 intrinsic", "_mm256_testc_pd x64 intrinsic", "_mm256_testc_ps x64 intrinsic", "_mm256_testc_si256 x64 intrinsic", "_mm256_testnzc_pd x64 intrinsic", "_mm256_testnzc_ps x64 intrinsic", "_mm256_testnzc_si256 x64 intrinsic", "_mm256_testz_pd x64 intrinsic", "_mm256_testz_ps x64 intrinsic", "_mm256_testz_si256 x64 intrinsic", "_mm256_unpackhi_epi16 x64 intrinsic", "_mm256_unpackhi_epi32 x64 intrinsic", "_mm256_unpackhi_epi64 x64 intrinsic", "_mm256_unpackhi_epi8 x64 intrinsic", "_mm256_unpackhi_pd x64 intrinsic", "_mm256_unpackhi_ps x64 intrinsic", "_mm256_unpacklo_epi16 x64 intrinsic", "_mm256_unpacklo_epi32 x64 intrinsic", "_mm256_unpacklo_epi64 x64 intrinsic", "_mm256_unpacklo_epi8 x64 intrinsic", "_mm256_unpacklo_pd x64 intrinsic", "_mm256_unpacklo_ps x64 intrinsic", "_mm256_xor_pd x64 intrinsic", "_mm256_xor_ps x64 intrinsic", "_mm256_xor_si256 x64 intrinsic", "_mm256_zeroall x64 intrinsic", "_mm256_zeroupper x64 intrinsic", "_mulx_u32 x64 intrinsic", "_mulx_u64 x64 intrinsic", "__nvreg_restore_fence x64 intrinsic", "__nvreg_save_fence x64 intrinsic", "_pdep_u32 x64 intrinsic", "_pdep_u64 x64 intrinsic", "_pext_u32 x64 intrinsic", "_pext_u64 x64 intrinsic", "_rdrand16_step x64 intrinsic", "_rdrand32_step x64 intrinsic", "_rdrand64_step x64 intrinsic", "_rdseed16_step x64 intrinsic", "_rdseed32_step x64 intrinsic", "_rdseed64_step x64 intrinsic", "_readfsbase_u32 x64 intrinsic", "_readfsbase_u64 x64 intrinsic", "_readgsbase_u32 x64 intrinsic", "_readgsbase_u64 x64 intrinsic", "_rorx_u32 x64 intrinsic", "_rorx_u64 x64 intrinsic", "_rsm x64 intrinsic", "_sarx_i32 x64 intrinsic", "_sarx_i64 x64 intrinsic", "_sgdt x64 intrinsic", "_shlx_u32 x64 intrinsic", "_shlx_u64 x64 intrinsic", "_shrx_u32 x64 intrinsic", "_shrx_u64 x64 intrinsic", "__slwpcb x64 intrinsic", "_stac x64 intrinsic", "_store_be_u16 x64 intrinsic", "_storebe_i16 x64 intrinsic", "_store_be_u32 x64 intrinsic", "_storebe_i32 x64 intrinsic", "_store_be_u64 x64 intrinsic", "_storebe_i64 x64 intrinsic", "_Store_HLERelease x64 intrinsic", "_Store64_HLERelease x64 intrinsic", "_StorePointer_HLERelease x64 intrinsic", "_subborrow_u16 x64 intrinsic", "_subborrow_u32 x64 intrinsic", "_subborrow_u64 x64 intrinsic", "_subborrow_u8 x64 intrinsic", "_t1mskc_u32 x64 intrinsic", "_t1mskc_u64 x64 intrinsic", "_tzcnt_u32 x64 intrinsic", "_tzcnt_u64 x64 intrinsic", "_tzmsk_u32 x64 intrinsic", "_tzmsk_u64 x64 intrinsic", "_writefsbase_u32 x64 intrinsic", "_writefsbase_u64 x64 intrinsic", "_writegsbase_u32 x64 intrinsic", "_writegsbase_u64 x64 intrinsic", "_xabort x64 intrinsic", "_xbegin x64 intrinsic", "_xend x64 intrinsic", "_xgetbv x64 intrinsic", "_xrstor x64 intrinsic", "_xrstor64 x64 intrinsic", "_xsave x64 intrinsic", "_xsave64 x64 intrinsic", "_xsaveopt x64 intrinsic", "_xsaveopt64 x64 intrinsic", "_xsetbv x64 intrinsic", "_xtest x64 intrinsic"] --- # x64 (amd64) intrinsics list @@ -13,7 +13,7 @@ For information about individual intrinsics, see these resources, as appropriate - The header file. Many intrinsics are documented in comments in the header file. -- [Intel Intrinsics Guide](https://software.intel.com/sites/landingpage/IntrinsicsGuide). Use the search box to find specific intrinsics. +- [Intel Intrinsics Guide](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html). Use the search box to find specific intrinsics. - [Intel 64 and IA-32 Architectures Software Developer Manuals](https://software.intel.com/articles/intel-sdm) @@ -80,6 +80,12 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_blsr_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsr_u64) | BMI | ammintrin.h, immintrin.h | `unsigned __int64 _blsr_u64(unsigned __int64);` | | [`_bzhi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u32) | BMI | immintrin.h | `unsigned int _bzhi_u32(unsigned int, unsigned int);` | | [`_bzhi_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u64) | BMI | immintrin.h | `unsigned __int64 _bzhi_u64(unsigned __int64, unsigned int);` | +| [`_castf32_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf32_u32) | | immintrin.h | `unsigned __int32 _castf32_u32 (float);` | +| [`_castf64_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf64_u64) | | immintrin.h | `unsigned __int64 _castf64_u64 (double);` | +| [`_castu32_f32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu32_f32) | | immintrin.h | `float _castu32_f32 (unsigned __int32);` | +| [`_castu64_f64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu64_f64) | | immintrin.h | `double _castu64_f64 (unsigned __int64 a);` | +| [`__check_isa_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_isa_support(unsigned int, unsigned int);` | +| [`__check_arch_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_arch_support(unsigned int, unsigned int);` | | `_clac` | SMAP | intrin.h | `void _clac(void);` | | [`__cpuid`](cpuid-cpuidex.md) | | intrin.h | `void __cpuid(int *, int);` | | [`__cpuidex`](cpuid-cpuidex.md) | | intrin.h | `void __cpuidex(int *, int, int);` | @@ -96,7 +102,7 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_fxrstor64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor64) | FXSR | immintrin.h | `void _fxrstor64(void const*);` | | [`_fxsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave) | FXSR | immintrin.h | `void _fxsave(void*);` | | [`_fxsave64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave64) | FXSR | immintrin.h | `void _fxsave64(void*);` | -| [`__getcallerseflags`](getcallerseflags.md) | | intrin.h | `(unsigned int __getcallerseflags());` | +| [`__getcallerseflags`](getcallerseflags.md) | | intrin.h | `unsigned int __getcallerseflags();` | | [`__halt`](halt.md) | | intrin.h | `void __halt(void);` | | [`__inbyte`](inbyte.md) | | intrin.h | `unsigned char __inbyte(unsigned short);` | | [`__inbytestring`](inbytestring.md) | | intrin.h | `void __inbytestring(unsigned short, unsigned char *, unsigned long);` | @@ -1027,7 +1033,7 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm256_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_ps) | AVX | immintrin.h | `__m256 _mm256_round_ps(__m256, int);` | | [`_mm256_rsqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rsqrt_ps) | AVX | immintrin.h | `__m256 _mm256_rsqrt_ps(__m256);` | | [`_mm256_sad_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sad_epu8) | AVX2 | immintrin.h | `__m256i _mm256_sad_epu8(__m256i, __m256i);` | -| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX | immintrin.h | `(__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX | immintrin.h | `__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | | [`_mm256_set_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi32) | AVX | immintrin.h | `__m256i _mm256_set_epi32(int, int, int, int, int, int, int, int);` | | [`_mm256_set_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi64x) | AVX | immintrin.h | `__m256i _mm256_set_epi64x(long long, long long, long long, long long);` | | [`_mm256_set_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi8) | AVX | immintrin.h | `__m256i _mm256_set_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | @@ -1039,10 +1045,10 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`_mm256_set1_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi8) | AVX | immintrin.h | `__m256i _mm256_set1_epi8(char);` | | [`_mm256_set1_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_pd) | AVX | immintrin.h | `__m256d _mm256_set1_pd(double);` | | [`_mm256_set1_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_ps) | AVX | immintrin.h | `__m256 _mm256_set1_ps(float);` | -| [`_mm256_setr_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi16) | AVX | immintrin.h | `(__m256i _mm256_setr_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_setr_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi16) | AVX | immintrin.h | `__m256i _mm256_setr_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | | [`_mm256_setr_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi32) | AVX | immintrin.h | `__m256i _mm256_setr_epi32(int, int, int, int, int, int, int, int);` | | [`_mm256_setr_epi64x`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi64x) | AVX | immintrin.h | `__m256i _mm256_setr_epi64x(long long, long long, long long, long long);` | -| [`_mm256_setr_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi8) | AVX | immintrin.h | `(__m256i _mm256_setr_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | +| [`_mm256_setr_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);` | @@ -1134,8 +1140,8 @@ The following table lists the intrinsics available on x64 processors. The Techno | [`__movsw`](movsw.md) | | intrin.h | `VOID __movsw(unsigned short *, unsigned short const *, size_t);` | | [`_mul128`](mul128.md) | | intrin.h | `__int64 _mul128(__int64, __int64, __int64 *);` | | [`__mulh`](mulh.md) | | intrin.h | `__int64 __mulh(__int64, __int64);` | -| `_mulx_u32` | BMI | immintrin.h | `unsigned int _mulx_u32(unsigned int, unsigned int, unsigned int*);` | -| `_mulx_u64` | BMI | immintrin.h | `unsigned __int64 _mulx_u64(unsigned __int64, unsigned __int64, unsigned __int64*);` | +| [`_mulx_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mulx_u32) | BMI | immintrin.h | `unsigned int _mulx_u32(unsigned int, unsigned int, unsigned int*);` | +| [`_mulx_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mulx_u64) | BMI | immintrin.h | `unsigned __int64 _mulx_u64(unsigned __int64, unsigned __int64, unsigned __int64*);` | | [`__nop`](nop.md) | | intrin.h | `void __nop(void);` | | `__nvreg_restore_fence` | | intrin.h | `void __nvreg_restore_fence(void);` | | `__nvreg_save_fence` | | intrin.h | `void __nvreg_save_fence(void);` | diff --git a/docs/intrinsics/x86-intrinsics-list.md b/docs/intrinsics/x86-intrinsics-list.md index dfe0bd7ac54..0cc8c485387 100644 --- a/docs/intrinsics/x86-intrinsics-list.md +++ b/docs/intrinsics/x86-intrinsics-list.md @@ -1,9 +1,9 @@ --- title: "x86 intrinsics list" description: "Reference list of x86 intrinsics supported by the Microsoft C++ compiler in Visual Studio." -ms.date: 02/04/2021 -f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "ammintrin/_andn_u32", "ammintrin/_bextr_u32", "ammintrin/_bextri_u32", "ammintrin/_blcfill_u32", "ammintrin/_blci_u32", "ammintrin/_blcic_u32", "ammintrin/_blcmsk_u32", "ammintrin/_blcs_u32", "ammintrin/_blsfill_u32", "ammintrin/_blsi_u32", "ammintrin/_blsic_u32", "ammintrin/_blsmsk_u32", "ammintrin/_blsr_u32", "immintrin/_bzhi_u32", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxsave", "immintrin/_invpcid", "intrin/_lgdt", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "ammintrin/__llwpcb", "ammintrin/__lwpins32", "ammintrin/__lwpval32", "ammintrin/_lzcnt_u32", "intrin/_m_empty", "intrin/_m_femms", "intrin/_m_from_float", "intrin/_m_from_int", "intrin/_m_maskmovq", "intrin/_m_packssdw", "intrin/_m_packsswb", "intrin/_m_packuswb", "intrin/_m_paddb", "intrin/_m_paddd", "intrin/_m_paddsb", "intrin/_m_paddsw", "intrin/_m_paddusb", "intrin/_m_paddusw", "intrin/_m_paddw", "intrin/_m_pand", "intrin/_m_pandn", "intrin/_m_pavgb", "intrin/_m_pavgusb", "intrin/_m_pavgw", "intrin/_m_pcmpeqb", "intrin/_m_pcmpeqd", "intrin/_m_pcmpeqw", "intrin/_m_pcmpgtb", "intrin/_m_pcmpgtd", "intrin/_m_pcmpgtw", "intrin/_m_pextrw", "intrin/_m_pf2id", "intrin/_m_pf2iw", "intrin/_m_pfacc", "intrin/_m_pfadd", "intrin/_m_pfcmpeq", "intrin/_m_pfcmpge", "intrin/_m_pfcmpgt", "intrin/_m_pfmax", "intrin/_m_pfmin", "intrin/_m_pfmul", "intrin/_m_pfnacc", "intrin/_m_pfpnacc", "intrin/_m_pfrcp", "intrin/_m_pfrcpit1", "intrin/_m_pfrcpit2", "intrin/_m_pfrsqit1", "intrin/_m_pfrsqrt", "intrin/_m_pfsub", "intrin/_m_pfsubr", "intrin/_m_pi2fd", "intrin/_m_pi2fw", "intrin/_m_pinsrw", "intrin/_m_pmaddwd", "intrin/_m_pmaxsw", "intrin/_m_pmaxub", "intrin/_m_pminsw", "intrin/_m_pminub", "intrin/_m_pmovmskb", "intrin/_m_pmulhrw", "intrin/_m_pmulhuw", "intrin/_m_pmulhw", "intrin/_m_pmullw", "intrin/_m_por", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_m_psadbw", "intrin/_m_pshufw", "intrin/_m_pslld", "intrin/_m_pslldi", "intrin/_m_psllq", "intrin/_m_psllqi", "intrin/_m_psllw", "intrin/_m_psllwi", "intrin/_m_psrad", "intrin/_m_psradi", "intrin/_m_psraw", "intrin/_m_psrawi", "intrin/_m_psrld", "intrin/_m_psrldi", "intrin/_m_psrlq", "intrin/_m_psrlqi", "intrin/_m_psrlw", "intrin/_m_psrlwi", "intrin/_m_psubb", "intrin/_m_psubd", "intrin/_m_psubsb", "intrin/_m_psubsw", "intrin/_m_psubusb", "intrin/_m_psubusw", "intrin/_m_psubw", "intrin/_m_pswapd", "intrin/_m_punpckhbw", "intrin/_m_punpckhdq", "intrin/_m_punpckhwd", "intrin/_m_punpcklbw", "intrin/_m_punpckldq", "intrin/_m_punpcklwd", "intrin/_m_pxor", "intrin/_m_to_float", "intrin/_m_to_int", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_abs_pi16", "intrin/_mm_abs_pi32", "intrin/_mm_abs_pi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "mmintrin/_mm_add_pi8", "mmintrin/_mm_add_pi16", "mmintrin/_mm_add_pi32", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_si64", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "mmintrin/_mm_adds_pi8", "mmintrin/_mm_adds_pi16", "mmintrin/_mm_adds_pu8", "mmintrin/_mm_adds_pu16", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_alignr_pi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "mmintrin/_mm_and_si64", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "mmintrin/_mm_andnot_si64", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "mmintrin/_mm_cmpeq_pi8", "mmintrin/_mm_cmpeq_pi16", "mmintrin/_mm_cmpeq_pi32", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "mmintrin/_mm_cmpgt_pi8", "mmintrin/_mm_cmpgt_pi16", "mmintrin/_mm_cmpgt_pi32", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_pi2ps", "intrin/_mm_cvt_ps2pi", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_pi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtpi32_pd", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "mmintrin/_mm_cvtsi32_si64", "mmintrin/_mm_cvtsi64_si32", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtt_ps2pi", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttpd_pi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "mmintrin/_mm_empty", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_pi16", "intrin/_mm_hadd_pi32", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "intrin/_mm_hadds_pi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_pi16", "intrin/_mm_hsub_pi32", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "intrin/_mm_hsubs_pi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "mmintrin/_mm_madd_pi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "intrin/_mm_maddubs_pi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_movepi64_pi64", "intrin/_mm_movpi64_epi64", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mul_su32", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "mmintrin/_mm_mulhi_pi16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mulhrs_pi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "mmintrin/_mm_mullo_pi16", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "mmintrin/_mm_or_si64", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "mmintrin/_mm_packs_pi16", "mmintrin/_mm_packs_pi32", "mmintrin/_mm_packs_pu16", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_pi16", "intrin/_mm_set_pi32", "intrin/_mm_set_pi8", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_set1_pi16", "intrin/_mm_set1_pi32", "intrin/_mm_set1_pi8", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi64", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_pi16", "intrin/_mm_setr_pi32", "intrin/_mm_setr_pi8", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_setzero_si64", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_pi8", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sign_pi16", "intrin/_mm_sign_pi32", "intrin/_mm_sign_pi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "mmintrin/_mm_sll_pi16", "mmintrin/_mm_sll_pi32", "mmintrin/_mm_sll_si64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "mmintrin/_mm_slli_pi16", "mmintrin/_mm_slli_pi32", "mmintrin/_mm_slli_si64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "mmintrin/_mm_sra_pi16", "mmintrin/_mm_sra_pi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "mmintrin/_mm_srai_pi16", "mmintrin/_mm_srai_pi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "mmintrin/_mm_srl_pi16", "mmintrin/_mm_srl_pi32", "mmintrin/_mm_srl_si64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "mmintrin/_mm_srli_pi16", "mmintrin/_mm_srli_pi32", "mmintrin/_mm_srli_si64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_pi", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "mmintrin/_mm_sub_pi8", "mmintrin/_mm_sub_pi16", "mmintrin/_mm_sub_pi32", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_si64", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "mmintrin/_mm_subs_pi8", "mmintrin/_mm_subs_pi16", "mmintrin/_mm_subs_pu8", "mmintrin/_mm_subs_pu16", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "mmintrin/_mm_unpackhi_pi8", "mmintrin/_mm_unpackhi_pi16", "mmintrin/_mm_unpackhi_pi32", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "mmintrin/_mm_unpacklo_pi8", "mmintrin/_mm_unpacklo_pi16", "mmintrin/_mm_unpacklo_pi32", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "mmintrin/_mm_xor_si64", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pext_u32", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rorx_u32", "intrin/_rsm", "immintrin/_sarx_i32", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shrx_u32", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_Store_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_tzcnt_u32", "ammintrin/_tzmsk_u32", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xsave", "immintrin/_xsaveopt", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_m_maskmovq", "XMMINTRIN/_m_pavgb", "XMMINTRIN/_m_pavgw", "XMMINTRIN/_m_pextrw", "XMMINTRIN/_m_pinsrw", "XMMINTRIN/_m_pmaxsw", "XMMINTRIN/_m_pmaxub", "XMMINTRIN/_m_pminsw", "XMMINTRIN/_m_pminub", "XMMINTRIN/_m_pmovmskb", "XMMINTRIN/_m_pmulhuw", "XMMINTRIN/_m_psadbw", "XMMINTRIN/_m_pshufw", "XMMINTRIN/_mm_avg_pu16", "XMMINTRIN/_mm_avg_pu8", "XMMINTRIN/_mm_cvt_pi2ps", "XMMINTRIN/_mm_cvt_ps2pi", "XMMINTRIN/_mm_cvtpi32_ps", "XMMINTRIN/_mm_cvtps_pi32", "XMMINTRIN/_mm_cvtt_ps2pi", "XMMINTRIN/_mm_cvttps_pi32", "XMMINTRIN/_mm_extract_pi16", "XMMINTRIN/_mm_insert_pi16", "XMMINTRIN/_mm_maskmove_si64", "XMMINTRIN/_mm_max_pi16", "XMMINTRIN/_mm_max_pu8", "XMMINTRIN/_mm_min_pi16", "XMMINTRIN/_mm_min_pu8", "XMMINTRIN/_mm_movemask_pi8", "XMMINTRIN/_mm_mulhi_pu16", "XMMINTRIN/_mm_sad_pu8", "XMMINTRIN/_mm_shuffle_pi16", "XMMINTRIN/_mm_stream_pi"] -helpviewer_keywords: ["cl.exe compiler, intrinsics", "intrinsics, x86", "_addcarry_u16 x86 intrinsic", "_addcarry_u32 x86 intrinsic", "_addcarry_u8 x86 intrinsic", "_addcarryx_u32 x86 intrinsic", "_andn_u32 x86 intrinsic", "_bextr_u32 x86 intrinsic", "_bextri_u32 x86 intrinsic", "_blcfill_u32 x86 intrinsic", "_blci_u32 x86 intrinsic", "_blcic_u32 x86 intrinsic", "_blcmsk_u32 x86 intrinsic", "_blcs_u32 x86 intrinsic", "_blsfill_u32 x86 intrinsic", "_blsi_u32 x86 intrinsic", "_blsic_u32 x86 intrinsic", "_blsmsk_u32 x86 intrinsic", "_blsr_u32 x86 intrinsic", "_bzhi_u32 x86 intrinsic", "_clac x86 intrinsic", "_fxrstor x86 intrinsic", "_fxsave x86 intrinsic", "_invpcid x86 intrinsic", "_lgdt x86 intrinsic", "_load_be_u16 x86 intrinsic", "_loadbe_i16 x86 intrinsic", "_load_be_u32 x86 intrinsic", "_loadbe_i32 x86 intrinsic", "__llwpcb x86 intrinsic", "__lwpins32 x86 intrinsic", "__lwpval32 x86 intrinsic", "_lzcnt_u32 x86 intrinsic", "_m_empty x86 intrinsic", "_m_femms x86 intrinsic", "_m_from_float x86 intrinsic", "_m_from_int x86 intrinsic", "_m_maskmovq x86 intrinsic", "_m_packssdw x86 intrinsic", "_m_packsswb x86 intrinsic", "_m_packuswb x86 intrinsic", "_m_paddb x86 intrinsic", "_m_paddd x86 intrinsic", "_m_paddsb x86 intrinsic", "_m_paddsw x86 intrinsic", "_m_paddusb x86 intrinsic", "_m_paddusw x86 intrinsic", "_m_paddw x86 intrinsic", "_m_pand x86 intrinsic", "_m_pandn x86 intrinsic", "_m_pavgb x86 intrinsic", "_m_pavgusb x86 intrinsic", "_m_pavgw x86 intrinsic", "_m_pcmpeqb x86 intrinsic", "_m_pcmpeqd x86 intrinsic", "_m_pcmpeqw x86 intrinsic", "_m_pcmpgtb x86 intrinsic", "_m_pcmpgtd x86 intrinsic", "_m_pcmpgtw x86 intrinsic", "_m_pextrw x86 intrinsic", "_m_pf2id x86 intrinsic", "_m_pf2iw x86 intrinsic", "_m_pfacc x86 intrinsic", "_m_pfadd x86 intrinsic", "_m_pfcmpeq x86 intrinsic", "_m_pfcmpge x86 intrinsic", "_m_pfcmpgt x86 intrinsic", "_m_pfmax x86 intrinsic", "_m_pfmin x86 intrinsic", "_m_pfmul x86 intrinsic", "_m_pfnacc x86 intrinsic", "_m_pfpnacc x86 intrinsic", "_m_pfrcp x86 intrinsic", "_m_pfrcpit1 x86 intrinsic", "_m_pfrcpit2 x86 intrinsic", "_m_pfrsqit1 x86 intrinsic", "_m_pfrsqrt x86 intrinsic", "_m_pfsub x86 intrinsic", "_m_pfsubr x86 intrinsic", "_m_pi2fd x86 intrinsic", "_m_pi2fw x86 intrinsic", "_m_pinsrw x86 intrinsic", "_m_pmaddwd x86 intrinsic", "_m_pmaxsw x86 intrinsic", "_m_pmaxub x86 intrinsic", "_m_pminsw x86 intrinsic", "_m_pminub x86 intrinsic", "_m_pmovmskb x86 intrinsic", "_m_pmulhrw x86 intrinsic", "_m_pmulhuw x86 intrinsic", "_m_pmulhw x86 intrinsic", "_m_pmullw x86 intrinsic", "_m_por x86 intrinsic", "_m_prefetch x86 intrinsic", "_m_prefetchw x86 intrinsic", "_m_psadbw x86 intrinsic", "_m_pshufw x86 intrinsic", "_m_pslld x86 intrinsic", "_m_pslldi x86 intrinsic", "_m_psllq x86 intrinsic", "_m_psllqi x86 intrinsic", "_m_psllw x86 intrinsic", "_m_psllwi x86 intrinsic", "_m_psrad x86 intrinsic", "_m_psradi x86 intrinsic", "_m_psraw x86 intrinsic", "_m_psrawi x86 intrinsic", "_m_psrld x86 intrinsic", "_m_psrldi x86 intrinsic", "_m_psrlq x86 intrinsic", "_m_psrlqi x86 intrinsic", "_m_psrlw x86 intrinsic", "_m_psrlwi x86 intrinsic", "_m_psubb x86 intrinsic", "_m_psubd x86 intrinsic", "_m_psubsb x86 intrinsic", "_m_psubsw x86 intrinsic", "_m_psubusb x86 intrinsic", "_m_psubusw x86 intrinsic", "_m_psubw x86 intrinsic", "_m_pswapd x86 intrinsic", "_m_punpckhbw x86 intrinsic", "_m_punpckhdq x86 intrinsic", "_m_punpckhwd x86 intrinsic", "_m_punpcklbw x86 intrinsic", "_m_punpckldq x86 intrinsic", "_m_punpcklwd x86 intrinsic", "_m_pxor x86 intrinsic", "_m_to_float x86 intrinsic", "_m_to_int x86 intrinsic", "_mm_abs_epi16 x86 intrinsic", "_mm_abs_epi32 x86 intrinsic", "_mm_abs_epi8 x86 intrinsic", "_mm_abs_pi16 x86 intrinsic", "_mm_abs_pi32 x86 intrinsic", "_mm_abs_pi8 x86 intrinsic", "_mm_add_epi16 x86 intrinsic", "_mm_add_epi32 x86 intrinsic", "_mm_add_epi64 x86 intrinsic", "_mm_add_epi8 x86 intrinsic", "_mm_add_pd x86 intrinsic", "_mm_add_pi8 x86 intrinsic", "_mm_add_pi16 x86 intrinsic", "_mm_add_pi32 x86 intrinsic", "_mm_add_ps x86 intrinsic", "_mm_add_sd x86 intrinsic", "_mm_add_si64 x86 intrinsic", "_mm_add_ss x86 intrinsic", "_mm_adds_epi16 x86 intrinsic", "_mm_adds_epi8 x86 intrinsic", "_mm_adds_epu16 x86 intrinsic", "_mm_adds_epu8 x86 intrinsic", "_mm_adds_pi8 x86 intrinsic", "_mm_adds_pi16 x86 intrinsic", "_mm_adds_pu8 x86 intrinsic", "_mm_adds_pu16 x86 intrinsic", "_mm_addsub_pd x86 intrinsic", "_mm_addsub_ps x86 intrinsic", "_mm_aesdec_si128 x86 intrinsic", "_mm_aesdeclast_si128 x86 intrinsic", "_mm_aesenc_si128 x86 intrinsic", "_mm_aesenclast_si128 x86 intrinsic", "_mm_aesimc_si128 x86 intrinsic", "_mm_aeskeygenassist_si128 x86 intrinsic", "_mm_alignr_epi8 x86 intrinsic", "_mm_alignr_pi8 x86 intrinsic", "_mm_and_pd x86 intrinsic", "_mm_and_ps x86 intrinsic", "_mm_and_si64 x86 intrinsic", "_mm_and_si128 x86 intrinsic", "_mm_andnot_pd x86 intrinsic", "_mm_andnot_ps x86 intrinsic", "_mm_andnot_si64 x86 intrinsic", "_mm_andnot_si128 x86 intrinsic", "_mm_avg_epu16 x86 intrinsic", "_mm_avg_epu8 x86 intrinsic", "_mm_blend_epi16 x86 intrinsic", "_mm_blend_epi32 x86 intrinsic", "_mm_blend_pd x86 intrinsic", "_mm_blend_ps x86 intrinsic", "_mm_blendv_epi8 x86 intrinsic", "_mm_blendv_pd x86 intrinsic", "_mm_blendv_ps x86 intrinsic", "_mm_broadcast_ss x86 intrinsic", "_mm_broadcastb_epi8 x86 intrinsic", "_mm_broadcastd_epi32 x86 intrinsic", "_mm_broadcastq_epi64 x86 intrinsic", "_mm_broadcastsd_pd x86 intrinsic", "_mm_broadcastss_ps x86 intrinsic", "_mm_broadcastw_epi16 x86 intrinsic", "_mm_castpd_ps x86 intrinsic", "_mm_castpd_si128 x86 intrinsic", "_mm_castps_pd x86 intrinsic", "_mm_castps_si128 x86 intrinsic", "_mm_castsi128_pd x86 intrinsic", "_mm_castsi128_ps x86 intrinsic", "_mm_clflush x86 intrinsic", "_mm_clmulepi64_si128 x86 intrinsic", "_mm_cmov_si128 x86 intrinsic", "_mm_cmp_pd x86 intrinsic", "_mm_cmp_ps x86 intrinsic", "_mm_cmp_sd x86 intrinsic", "_mm_cmp_ss x86 intrinsic", "_mm_cmpeq_epi16 x86 intrinsic", "_mm_cmpeq_epi32 x86 intrinsic", "_mm_cmpeq_epi64 x86 intrinsic", "_mm_cmpeq_epi8 x86 intrinsic", "_mm_cmpeq_pd x86 intrinsic", "_mm_cmpeq_pi8 x86 intrinsic", "_mm_cmpeq_pi16 x86 intrinsic", "_mm_cmpeq_pi32 x86 intrinsic", "_mm_cmpeq_ps x86 intrinsic", "_mm_cmpeq_sd x86 intrinsic", "_mm_cmpeq_ss x86 intrinsic", "_mm_cmpestra x86 intrinsic", "_mm_cmpestrc x86 intrinsic", "_mm_cmpestri x86 intrinsic", "_mm_cmpestrm x86 intrinsic", "_mm_cmpestro x86 intrinsic", "_mm_cmpestrs x86 intrinsic", "_mm_cmpestrz x86 intrinsic", "_mm_cmpge_pd x86 intrinsic", "_mm_cmpge_ps x86 intrinsic", "_mm_cmpge_sd x86 intrinsic", "_mm_cmpge_ss x86 intrinsic", "_mm_cmpgt_epi16 x86 intrinsic", "_mm_cmpgt_epi32 x86 intrinsic", "_mm_cmpgt_epi64 x86 intrinsic", "_mm_cmpgt_epi8 x86 intrinsic", "_mm_cmpgt_pi8 x86 intrinsic", "_mm_cmpgt_pi16 x86 intrinsic", "_mm_cmpgt_pi32 x86 intrinsic", "_mm_cmpgt_pd x86 intrinsic", "_mm_cmpgt_ps x86 intrinsic", "_mm_cmpgt_sd x86 intrinsic", "_mm_cmpgt_ss x86 intrinsic", "_mm_cmpistra x86 intrinsic", "_mm_cmpistrc x86 intrinsic", "_mm_cmpistri x86 intrinsic", "_mm_cmpistrm x86 intrinsic", "_mm_cmpistro x86 intrinsic", "_mm_cmpistrs x86 intrinsic", "_mm_cmpistrz x86 intrinsic", "_mm_cmple_pd x86 intrinsic", "_mm_cmple_ps x86 intrinsic", "_mm_cmple_sd x86 intrinsic", "_mm_cmple_ss x86 intrinsic", "_mm_cmplt_epi16 x86 intrinsic", "_mm_cmplt_epi32 x86 intrinsic", "_mm_cmplt_epi8 x86 intrinsic", "_mm_cmplt_pd x86 intrinsic", "_mm_cmplt_ps x86 intrinsic", "_mm_cmplt_sd x86 intrinsic", "_mm_cmplt_ss x86 intrinsic", "_mm_cmpneq_pd x86 intrinsic", "_mm_cmpneq_ps x86 intrinsic", "_mm_cmpneq_sd x86 intrinsic", "_mm_cmpneq_ss x86 intrinsic", "_mm_cmpnge_pd x86 intrinsic", "_mm_cmpnge_ps x86 intrinsic", "_mm_cmpnge_sd x86 intrinsic", "_mm_cmpnge_ss x86 intrinsic", "_mm_cmpngt_pd x86 intrinsic", "_mm_cmpngt_ps x86 intrinsic", "_mm_cmpngt_sd x86 intrinsic", "_mm_cmpngt_ss x86 intrinsic", "_mm_cmpnle_pd x86 intrinsic", "_mm_cmpnle_ps x86 intrinsic", "_mm_cmpnle_sd x86 intrinsic", "_mm_cmpnle_ss x86 intrinsic", "_mm_cmpnlt_pd x86 intrinsic", "_mm_cmpnlt_ps x86 intrinsic", "_mm_cmpnlt_sd x86 intrinsic", "_mm_cmpnlt_ss x86 intrinsic", "_mm_cmpord_pd x86 intrinsic", "_mm_cmpord_ps x86 intrinsic", "_mm_cmpord_sd x86 intrinsic", "_mm_cmpord_ss x86 intrinsic", "_mm_cmpunord_pd x86 intrinsic", "_mm_cmpunord_ps x86 intrinsic", "_mm_cmpunord_sd x86 intrinsic", "_mm_cmpunord_ss x86 intrinsic", "_mm_com_epi16 x86 intrinsic", "_mm_com_epi32 x86 intrinsic", "_mm_com_epi64 x86 intrinsic", "_mm_com_epi8 x86 intrinsic", "_mm_com_epu16 x86 intrinsic", "_mm_com_epu32 x86 intrinsic", "_mm_com_epu64 x86 intrinsic", "_mm_com_epu8 x86 intrinsic", "_mm_comieq_sd x86 intrinsic", "_mm_comieq_ss x86 intrinsic", "_mm_comige_sd x86 intrinsic", "_mm_comige_ss x86 intrinsic", "_mm_comigt_sd x86 intrinsic", "_mm_comigt_ss x86 intrinsic", "_mm_comile_sd x86 intrinsic", "_mm_comile_ss x86 intrinsic", "_mm_comilt_sd x86 intrinsic", "_mm_comilt_ss x86 intrinsic", "_mm_comineq_sd x86 intrinsic", "_mm_comineq_ss x86 intrinsic", "_mm_crc32_u16 x86 intrinsic", "_mm_crc32_u32 x86 intrinsic", "_mm_crc32_u8 x86 intrinsic", "_mm_cvt_pi2ps x86 intrinsic", "_mm_cvt_ps2pi x86 intrinsic", "_mm_cvt_si2ss x86 intrinsic", "_mm_cvt_ss2si x86 intrinsic", "_mm_cvtepi16_epi32 x86 intrinsic", "_mm_cvtepi16_epi64 x86 intrinsic", "_mm_cvtepi32_epi64 x86 intrinsic", "_mm_cvtepi32_pd x86 intrinsic", "_mm_cvtepi32_ps x86 intrinsic", "_mm_cvtepi8_epi16 x86 intrinsic", "_mm_cvtepi8_epi32 x86 intrinsic", "_mm_cvtepi8_epi64 x86 intrinsic", "_mm_cvtepu16_epi32 x86 intrinsic", "_mm_cvtepu16_epi64 x86 intrinsic", "_mm_cvtepu32_epi64 x86 intrinsic", "_mm_cvtepu8_epi16 x86 intrinsic", "_mm_cvtepu8_epi32 x86 intrinsic", "_mm_cvtepu8_epi64 x86 intrinsic", "_mm_cvtpd_epi32 x86 intrinsic", "_mm_cvtpd_pi32 x86 intrinsic", "_mm_cvtpd_ps x86 intrinsic", "_mm_cvtph_ps x86 intrinsic", "_mm_cvtpi32_pd x86 intrinsic", "_mm_cvtps_epi32 x86 intrinsic", "_mm_cvtps_pd x86 intrinsic", "_mm_cvtps_ph x86 intrinsic", "_mm_cvtsd_f64 x86 intrinsic", "_mm_cvtsd_si32 x86 intrinsic", "_mm_cvtsd_ss x86 intrinsic", "_mm_cvtsi128_si32 x86 intrinsic", "_mm_cvtsi32_sd x86 intrinsic", "_mm_cvtsi32_si128 x86 intrinsic", "_mm_cvtsi32_si64 x86 intrinsic", "_mm_cvtsi64_si32 x86 intrinsic", "_mm_cvtss_f32 x86 intrinsic", "_mm_cvtss_sd x86 intrinsic", "_mm_cvtt_ps2pi x86 intrinsic", "_mm_cvtt_ss2si x86 intrinsic", "_mm_cvttpd_epi32 x86 intrinsic", "_mm_cvttpd_pi32 x86 intrinsic", "_mm_cvttps_epi32 x86 intrinsic", "_mm_cvttsd_si32 x86 intrinsic", "_mm_div_pd x86 intrinsic", "_mm_div_ps x86 intrinsic", "_mm_div_sd x86 intrinsic", "_mm_div_ss x86 intrinsic", "_mm_dp_pd x86 intrinsic", "_mm_dp_ps x86 intrinsic", "_mm_empty x86 intrinsic", "_mm_extract_epi16 x86 intrinsic", "_mm_extract_epi32 x86 intrinsic", "_mm_extract_epi8 x86 intrinsic", "_mm_extract_ps x86 intrinsic", "_mm_fmadd_pd x86 intrinsic", "_mm_fmadd_ps x86 intrinsic", "_mm_fmadd_sd x86 intrinsic", "_mm_fmadd_ss x86 intrinsic", "_mm_fmaddsub_pd x86 intrinsic", "_mm_fmaddsub_ps x86 intrinsic", "_mm_fmsub_pd x86 intrinsic", "_mm_fmsub_ps x86 intrinsic", "_mm_fmsub_sd x86 intrinsic", "_mm_fmsub_ss x86 intrinsic", "_mm_fmsubadd_pd x86 intrinsic", "_mm_fmsubadd_ps x86 intrinsic", "_mm_fnmadd_pd x86 intrinsic", "_mm_fnmadd_ps x86 intrinsic", "_mm_fnmadd_sd x86 intrinsic", "_mm_fnmadd_ss x86 intrinsic", "_mm_fnmsub_pd x86 intrinsic", "_mm_fnmsub_ps x86 intrinsic", "_mm_fnmsub_sd x86 intrinsic", "_mm_fnmsub_ss x86 intrinsic", "_mm_frcz_pd x86 intrinsic", "_mm_frcz_ps x86 intrinsic", "_mm_frcz_sd x86 intrinsic", "_mm_frcz_ss x86 intrinsic", "_mm_getcsr x86 intrinsic", "_mm_hadd_epi16 x86 intrinsic", "_mm_hadd_epi32 x86 intrinsic", "_mm_hadd_pd x86 intrinsic", "_mm_hadd_pi16 x86 intrinsic", "_mm_hadd_pi32 x86 intrinsic", "_mm_hadd_ps x86 intrinsic", "_mm_haddd_epi16 x86 intrinsic", "_mm_haddd_epi8 x86 intrinsic", "_mm_haddd_epu16 x86 intrinsic", "_mm_haddd_epu8 x86 intrinsic", "_mm_haddq_epi16 x86 intrinsic", "_mm_haddq_epi32 x86 intrinsic", "_mm_haddq_epi8 x86 intrinsic", "_mm_haddq_epu16 x86 intrinsic", "_mm_haddq_epu32 x86 intrinsic", "_mm_haddq_epu8 x86 intrinsic", "_mm_hadds_epi16 x86 intrinsic", "_mm_hadds_pi16 x86 intrinsic", "_mm_haddw_epi8 x86 intrinsic", "_mm_haddw_epu8 x86 intrinsic", "_mm_hsub_epi16 x86 intrinsic", "_mm_hsub_epi32 x86 intrinsic", "_mm_hsub_pd x86 intrinsic", "_mm_hsub_pi16 x86 intrinsic", "_mm_hsub_pi32 x86 intrinsic", "_mm_hsub_ps x86 intrinsic", "_mm_hsubd_epi16 x86 intrinsic", "_mm_hsubq_epi32 x86 intrinsic", "_mm_hsubs_epi16 x86 intrinsic", "_mm_hsubs_pi16 x86 intrinsic", "_mm_hsubw_epi8 x86 intrinsic", "_mm_i32gather_epi32 x86 intrinsic", "_mm_i32gather_epi64 x86 intrinsic", "_mm_i32gather_pd x86 intrinsic", "_mm_i32gather_ps x86 intrinsic", "_mm_i64gather_epi32 x86 intrinsic", "_mm_i64gather_epi64 x86 intrinsic", "_mm_i64gather_pd x86 intrinsic", "_mm_i64gather_ps x86 intrinsic", "_mm_insert_epi16 x86 intrinsic", "_mm_insert_epi32 x86 intrinsic", "_mm_insert_epi8 x86 intrinsic", "_mm_insert_ps x86 intrinsic", "_mm_lddqu_si128 x86 intrinsic", "_mm_lfence x86 intrinsic", "_mm_load_pd x86 intrinsic", "_mm_load_ps x86 intrinsic", "_mm_load_ps1 x86 intrinsic", "_mm_load_sd x86 intrinsic", "_mm_load_si128 x86 intrinsic", "_mm_load_ss x86 intrinsic", "_mm_load1_pd x86 intrinsic", "_mm_loaddup_pd x86 intrinsic", "_mm_loadh_pd x86 intrinsic", "_mm_loadh_pi x86 intrinsic", "_mm_loadl_epi64 x86 intrinsic", "_mm_loadl_pd x86 intrinsic", "_mm_loadl_pi x86 intrinsic", "_mm_loadr_pd x86 intrinsic", "_mm_loadr_ps x86 intrinsic", "_mm_loadu_pd x86 intrinsic", "_mm_loadu_ps x86 intrinsic", "_mm_loadu_si128 x86 intrinsic", "_mm_macc_epi16 x86 intrinsic", "_mm_macc_epi32 x86 intrinsic", "_mm_macc_pd x86 intrinsic", "_mm_macc_ps x86 intrinsic", "_mm_macc_sd x86 intrinsic", "_mm_macc_ss x86 intrinsic", "_mm_maccd_epi16 x86 intrinsic", "_mm_macchi_epi32 x86 intrinsic", "_mm_macclo_epi32 x86 intrinsic", "_mm_maccs_epi16 x86 intrinsic", "_mm_maccs_epi32 x86 intrinsic", "_mm_maccsd_epi16 x86 intrinsic", "_mm_maccshi_epi32 x86 intrinsic", "_mm_maccslo_epi32 x86 intrinsic", "_mm_madd_epi16 x86 intrinsic", "_mm_madd_pi16 x86 intrinsic", "_mm_maddd_epi16 x86 intrinsic", "_mm_maddsd_epi16 x86 intrinsic", "_mm_maddsub_pd x86 intrinsic", "_mm_maddsub_ps x86 intrinsic", "_mm_maddubs_epi16 x86 intrinsic", "_mm_maddubs_pi16 x86 intrinsic", "_mm_mask_i32gather_epi32 x86 intrinsic", "_mm_mask_i32gather_epi64 x86 intrinsic", "_mm_mask_i32gather_pd x86 intrinsic", "_mm_mask_i32gather_ps x86 intrinsic", "_mm_mask_i64gather_epi32 x86 intrinsic", "_mm_mask_i64gather_epi64 x86 intrinsic", "_mm_mask_i64gather_pd x86 intrinsic", "_mm_mask_i64gather_ps x86 intrinsic", "_mm_maskload_epi32 x86 intrinsic", "_mm_maskload_epi64 x86 intrinsic", "_mm_maskload_pd x86 intrinsic", "_mm_maskload_ps x86 intrinsic", "_mm_maskmoveu_si128 x86 intrinsic", "_mm_maskstore_epi32 x86 intrinsic", "_mm_maskstore_epi64 x86 intrinsic", "_mm_maskstore_pd x86 intrinsic", "_mm_maskstore_ps x86 intrinsic", "_mm_max_epi16 x86 intrinsic", "_mm_max_epi32 x86 intrinsic", "_mm_max_epi8 x86 intrinsic", "_mm_max_epu16 x86 intrinsic", "_mm_max_epu32 x86 intrinsic", "_mm_max_epu8 x86 intrinsic", "_mm_max_pd x86 intrinsic", "_mm_max_ps x86 intrinsic", "_mm_max_sd x86 intrinsic", "_mm_max_ss x86 intrinsic", "_mm_mfence x86 intrinsic", "_mm_min_epi16 x86 intrinsic", "_mm_min_epi32 x86 intrinsic", "_mm_min_epi8 x86 intrinsic", "_mm_min_epu16 x86 intrinsic", "_mm_min_epu32 x86 intrinsic", "_mm_min_epu8 x86 intrinsic", "_mm_min_pd x86 intrinsic", "_mm_min_ps x86 intrinsic", "_mm_min_sd x86 intrinsic", "_mm_min_ss x86 intrinsic", "_mm_minpos_epu16 x86 intrinsic", "_mm_monitor x86 intrinsic", "_mm_move_epi64 x86 intrinsic", "_mm_move_sd x86 intrinsic", "_mm_move_ss x86 intrinsic", "_mm_movedup_pd x86 intrinsic", "_mm_movehdup_ps x86 intrinsic", "_mm_movehl_ps x86 intrinsic", "_mm_moveldup_ps x86 intrinsic", "_mm_movelh_ps x86 intrinsic", "_mm_movemask_epi8 x86 intrinsic", "_mm_movemask_pd x86 intrinsic", "_mm_movemask_ps x86 intrinsic", "_mm_movepi64_pi64 x86 intrinsic", "_mm_movpi64_epi64 x86 intrinsic", "_mm_mpsadbw_epu8 x86 intrinsic", "_mm_msub_pd x86 intrinsic", "_mm_msub_ps x86 intrinsic", "_mm_msub_sd x86 intrinsic", "_mm_msub_ss x86 intrinsic", "_mm_msubadd_pd x86 intrinsic", "_mm_msubadd_ps x86 intrinsic", "_mm_mul_epi32 x86 intrinsic", "_mm_mul_epu32 x86 intrinsic", "_mm_mul_pd x86 intrinsic", "_mm_mul_ps x86 intrinsic", "_mm_mul_sd x86 intrinsic", "_mm_mul_ss x86 intrinsic", "_mm_mul_su32 x86 intrinsic", "_mm_mulhi_epi16 x86 intrinsic", "_mm_mulhi_epu16 x86 intrinsic", "_mm_mulhi_pi16 x86 intrinsic", "_mm_mulhrs_epi16 x86 intrinsic", "_mm_mulhrs_pi16 x86 intrinsic", "_mm_mullo_epi16 x86 intrinsic", "_mm_mullo_epi32 x86 intrinsic", "_mm_mullo_pi16 x86 intrinsic", "_mm_mwait x86 intrinsic", "_mm_nmacc_pd x86 intrinsic", "_mm_nmacc_ps x86 intrinsic", "_mm_nmacc_sd x86 intrinsic", "_mm_nmacc_ss x86 intrinsic", "_mm_nmsub_pd x86 intrinsic", "_mm_nmsub_ps x86 intrinsic", "_mm_nmsub_sd x86 intrinsic", "_mm_nmsub_ss x86 intrinsic", "_mm_or_pd x86 intrinsic", "_mm_or_ps x86 intrinsic", "_mm_or_si64 x86 intrinsic", "_mm_or_si128 x86 intrinsic", "_mm_packs_epi16 x86 intrinsic", "_mm_packs_epi32 x86 intrinsic", "_mm_packs_pi16 x86 intrinsic", "_mm_packs_pi32 x86 intrinsic", "_mm_packs_pu16 x86 intrinsic", "_mm_packus_epi16 x86 intrinsic", "_mm_packus_epi32 x86 intrinsic", "_mm_pause x86 intrinsic", "_mm_perm_epi8 x86 intrinsic", "_mm_permute_pd x86 intrinsic", "_mm_permute_ps x86 intrinsic", "_mm_permute2_pd x86 intrinsic", "_mm_permute2_ps x86 intrinsic", "_mm_permutevar_pd x86 intrinsic", "_mm_permutevar_ps x86 intrinsic", "_mm_popcnt_u32 x86 intrinsic", "_mm_prefetch x86 intrinsic", "_mm_rcp_ps x86 intrinsic", "_mm_rcp_ss x86 intrinsic", "_mm_rot_epi16 x86 intrinsic", "_mm_rot_epi32 x86 intrinsic", "_mm_rot_epi64 x86 intrinsic", "_mm_rot_epi8 x86 intrinsic", "_mm_roti_epi16 x86 intrinsic", "_mm_roti_epi32 x86 intrinsic", "_mm_roti_epi64 x86 intrinsic", "_mm_roti_epi8 x86 intrinsic", "_mm_round_pd x86 intrinsic", "_mm_round_ps x86 intrinsic", "_mm_round_sd x86 intrinsic", "_mm_round_ss x86 intrinsic", "_mm_rsqrt_ps x86 intrinsic", "_mm_rsqrt_ss x86 intrinsic", "_mm_sad_epu8 x86 intrinsic", "_mm_set_epi16 x86 intrinsic", "_mm_set_epi32 x86 intrinsic", "_mm_set_epi64 x86 intrinsic", "_mm_set_epi8 x86 intrinsic", "_mm_set_pd x86 intrinsic", "_mm_set_pi16 x86 intrinsic", "_mm_set_pi32 x86 intrinsic", "_mm_set_pi8 x86 intrinsic", "_mm_set_ps x86 intrinsic", "_mm_set_ps1 x86 intrinsic", "_mm_set_sd x86 intrinsic", "_mm_set_ss x86 intrinsic", "_mm_set1_epi16 x86 intrinsic", "_mm_set1_epi32 x86 intrinsic", "_mm_set1_epi64 x86 intrinsic", "_mm_set1_epi8 x86 intrinsic", "_mm_set1_pd x86 intrinsic", "_mm_set1_pi16 x86 intrinsic", "_mm_set1_pi32 x86 intrinsic", "_mm_set1_pi8 x86 intrinsic", "_mm_setcsr x86 intrinsic", "_mm_setl_epi64 x86 intrinsic", "_mm_setr_epi16 x86 intrinsic", "_mm_setr_epi32 x86 intrinsic", "_mm_setr_epi64 x86 intrinsic", "_mm_setr_epi8 x86 intrinsic", "_mm_setr_pd x86 intrinsic", "_mm_setr_pi16 x86 intrinsic", "_mm_setr_pi32 x86 intrinsic", "_mm_setr_pi8 x86 intrinsic", "_mm_setr_ps x86 intrinsic", "_mm_setzero_pd x86 intrinsic", "_mm_setzero_ps x86 intrinsic", "_mm_setzero_si128 x86 intrinsic", "_mm_setzero_si64 x86 intrinsic", "_mm_sfence x86 intrinsic", "_mm_sha_epi16 x86 intrinsic", "_mm_sha_epi32 x86 intrinsic", "_mm_sha_epi64 x86 intrinsic", "_mm_sha_epi8 x86 intrinsic", "_mm_shl_epi16 x86 intrinsic", "_mm_shl_epi32 x86 intrinsic", "_mm_shl_epi64 x86 intrinsic", "_mm_shl_epi8 x86 intrinsic", "_mm_shuffle_epi32 x86 intrinsic", "_mm_shuffle_epi8 x86 intrinsic", "_mm_shuffle_pd x86 intrinsic", "_mm_shuffle_pi8 x86 intrinsic", "_mm_shuffle_ps x86 intrinsic", "_mm_shufflehi_epi16 x86 intrinsic", "_mm_shufflelo_epi16 x86 intrinsic", "_mm_sign_epi16 x86 intrinsic", "_mm_sign_epi32 x86 intrinsic", "_mm_sign_epi8 x86 intrinsic", "_mm_sign_pi16 x86 intrinsic", "_mm_sign_pi32 x86 intrinsic", "_mm_sign_pi8 x86 intrinsic", "_mm_sll_epi16 x86 intrinsic", "_mm_sll_epi32 x86 intrinsic", "_mm_sll_epi64 x86 intrinsic", "_mm_sll_pi16 x86 intrinsic", "_mm_sll_pi32 x86 intrinsic", "_mm_sll_si64 x86 intrinsic", "_mm_slli_epi16 x86 intrinsic", "_mm_slli_epi32 x86 intrinsic", "_mm_slli_epi64 x86 intrinsic", "_mm_slli_pi16 x86 intrinsic", "_mm_slli_pi32 x86 intrinsic", "_mm_slli_si64 x86 intrinsic", "_mm_slli_si128 x86 intrinsic", "_mm_sllv_epi32 x86 intrinsic", "_mm_sllv_epi64 x86 intrinsic", "_mm_sqrt_pd x86 intrinsic", "_mm_sqrt_ps x86 intrinsic", "_mm_sqrt_sd x86 intrinsic", "_mm_sqrt_ss x86 intrinsic", "_mm_sra_epi16 x86 intrinsic", "_mm_sra_epi32 x86 intrinsic", "_mm_sra_pi16 x86 intrinsic", "_mm_sra_pi32 x86 intrinsic", "_mm_srai_epi16 x86 intrinsic", "_mm_srai_epi32 x86 intrinsic", "_mm_srai_pi16 x86 intrinsic", "_mm_srai_pi32 x86 intrinsic", "_mm_srav_epi32 x86 intrinsic", "_mm_srl_epi16 x86 intrinsic", "_mm_srl_epi32 x86 intrinsic", "_mm_srl_epi64 x86 intrinsic", "_mm_srl_pi16 x86 intrinsic", "_mm_srl_pi32 x86 intrinsic", "_mm_srl_si64 x86 intrinsic", "_mm_srli_epi16 x86 intrinsic", "_mm_srli_epi32 x86 intrinsic", "_mm_srli_epi64 x86 intrinsic", "_mm_srli_pi16 x86 intrinsic", "_mm_srli_pi32 x86 intrinsic", "_mm_srli_si64 x86 intrinsic", "_mm_srli_si128 x86 intrinsic", "_mm_srlv_epi32 x86 intrinsic", "_mm_srlv_epi64 x86 intrinsic", "_mm_store_pd x86 intrinsic", "_mm_store_ps x86 intrinsic", "_mm_store_ps1 x86 intrinsic", "_mm_store_sd x86 intrinsic", "_mm_store_si128 x86 intrinsic", "_mm_store_ss x86 intrinsic", "_mm_store1_pd x86 intrinsic", "_mm_storeh_pd x86 intrinsic", "_mm_storeh_pi x86 intrinsic", "_mm_storel_epi64 x86 intrinsic", "_mm_storel_pd x86 intrinsic", "_mm_storel_pi x86 intrinsic", "_mm_storer_pd x86 intrinsic", "_mm_storer_ps x86 intrinsic", "_mm_storeu_pd x86 intrinsic", "_mm_storeu_ps x86 intrinsic", "_mm_storeu_si128 x86 intrinsic", "_mm_stream_load_si128 x86 intrinsic", "_mm_stream_pd x86 intrinsic", "_mm_stream_pi x86 intrinsic", "_mm_stream_ps x86 intrinsic", "_mm_stream_si128 x86 intrinsic", "_mm_stream_si32 x86 intrinsic", "_mm_sub_epi16 x86 intrinsic", "_mm_sub_epi32 x86 intrinsic", "_mm_sub_epi64 x86 intrinsic", "_mm_sub_epi8 x86 intrinsic", "_mm_sub_pd x86 intrinsic", "_mm_sub_pi8 x86 intrinsic", "_mm_sub_pi16 x86 intrinsic", "_mm_sub_pi32 x86 intrinsic", "_mm_sub_ps x86 intrinsic", "_mm_sub_sd x86 intrinsic", "_mm_sub_si64 x86 intrinsic", "_mm_sub_ss x86 intrinsic", "_mm_subs_epi16 x86 intrinsic", "_mm_subs_epi8 x86 intrinsic", "_mm_subs_epu16 x86 intrinsic", "_mm_subs_epu8 x86 intrinsic", "_mm_subs_pi8 x86 intrinsic", "_mm_subs_pi16 x86 intrinsic", "_mm_subs_pu8 x86 intrinsic", "_mm_subs_pu16 x86 intrinsic", "_mm_testc_pd x86 intrinsic", "_mm_testc_ps x86 intrinsic", "_mm_testc_si128 x86 intrinsic", "_mm_testnzc_pd x86 intrinsic", "_mm_testnzc_ps x86 intrinsic", "_mm_testnzc_si128 x86 intrinsic", "_mm_testz_pd x86 intrinsic", "_mm_testz_ps x86 intrinsic", "_mm_testz_si128 x86 intrinsic", "_mm_ucomieq_sd x86 intrinsic", "_mm_ucomieq_ss x86 intrinsic", "_mm_ucomige_sd x86 intrinsic", "_mm_ucomige_ss x86 intrinsic", "_mm_ucomigt_sd x86 intrinsic", "_mm_ucomigt_ss x86 intrinsic", "_mm_ucomile_sd x86 intrinsic", "_mm_ucomile_ss x86 intrinsic", "_mm_ucomilt_sd x86 intrinsic", "_mm_ucomilt_ss x86 intrinsic", "_mm_ucomineq_sd x86 intrinsic", "_mm_ucomineq_ss x86 intrinsic", "_mm_unpackhi_epi16 x86 intrinsic", "_mm_unpackhi_epi32 x86 intrinsic", "_mm_unpackhi_epi64 x86 intrinsic", "_mm_unpackhi_epi8 x86 intrinsic", "_mm_unpackhi_pd x86 intrinsic", "_mm_unpackhi_pi8 x86 intrinsic", "_mm_unpackhi_pi16 x86 intrinsic", "_mm_unpackhi_pi32 x86 intrinsic", "_mm_unpackhi_ps x86 intrinsic", "_mm_unpacklo_epi16 x86 intrinsic", "_mm_unpacklo_epi32 x86 intrinsic", "_mm_unpacklo_epi64 x86 intrinsic", "_mm_unpacklo_epi8 x86 intrinsic", "_mm_unpacklo_pd x86 intrinsic", "_mm_unpacklo_pi8 x86 intrinsic", "_mm_unpacklo_pi16 x86 intrinsic", "_mm_unpacklo_pi32 x86 intrinsic", "_mm_unpacklo_ps x86 intrinsic", "_mm_xor_pd x86 intrinsic", "_mm_xor_ps x86 intrinsic", "_mm_xor_si64 x86 intrinsic", "_mm_xor_si128 x86 intrinsic", "_mm256_abs_epi16 x86 intrinsic", "_mm256_abs_epi32 x86 intrinsic", "_mm256_abs_epi8 x86 intrinsic", "_mm256_add_epi16 x86 intrinsic", "_mm256_add_epi32 x86 intrinsic", "_mm256_add_epi64 x86 intrinsic", "_mm256_add_epi8 x86 intrinsic", "_mm256_add_pd x86 intrinsic", "_mm256_add_ps x86 intrinsic", "_mm256_adds_epi16 x86 intrinsic", "_mm256_adds_epi8 x86 intrinsic", "_mm256_adds_epu16 x86 intrinsic", "_mm256_adds_epu8 x86 intrinsic", "_mm256_addsub_pd x86 intrinsic", "_mm256_addsub_ps x86 intrinsic", "_mm256_alignr_epi8 x86 intrinsic", "_mm256_and_pd x86 intrinsic", "_mm256_and_ps x86 intrinsic", "_mm256_and_si256 x86 intrinsic", "_mm256_andnot_pd x86 intrinsic", "_mm256_andnot_ps x86 intrinsic", "_mm256_andnot_si256 x86 intrinsic", "_mm256_avg_epu16 x86 intrinsic", "_mm256_avg_epu8 x86 intrinsic", "_mm256_blend_epi16 x86 intrinsic", "_mm256_blend_epi32 x86 intrinsic", "_mm256_blend_pd x86 intrinsic", "_mm256_blend_ps x86 intrinsic", "_mm256_blendv_epi8 x86 intrinsic", "_mm256_blendv_pd x86 intrinsic", "_mm256_blendv_ps x86 intrinsic", "_mm256_broadcast_pd x86 intrinsic", "_mm256_broadcast_ps x86 intrinsic", "_mm256_broadcast_sd x86 intrinsic", "_mm256_broadcast_ss x86 intrinsic", "_mm256_broadcastb_epi8 x86 intrinsic", "_mm256_broadcastd_epi32 x86 intrinsic", "_mm256_broadcastq_epi64 x86 intrinsic", "_mm256_broadcastsd_pd x86 intrinsic", "_mm256_broadcastsi128_si256 x86 intrinsic", "_mm256_broadcastss_ps x86 intrinsic", "_mm256_broadcastw_epi16 x86 intrinsic", "_mm256_castpd_ps x86 intrinsic", "_mm256_castpd_si256 x86 intrinsic", "_mm256_castpd128_pd256 x86 intrinsic", "_mm256_castpd256_pd128 x86 intrinsic", "_mm256_castps_pd x86 intrinsic", "_mm256_castps_si256 x86 intrinsic", "_mm256_castps128_ps256 x86 intrinsic", "_mm256_castps256_ps128 x86 intrinsic", "_mm256_castsi128_si256 x86 intrinsic", "_mm256_castsi256_pd x86 intrinsic", "_mm256_castsi256_ps x86 intrinsic", "_mm256_castsi256_si128 x86 intrinsic", "_mm256_cmov_si256 x86 intrinsic", "_mm256_cmp_pd x86 intrinsic", "_mm256_cmp_ps x86 intrinsic", "_mm256_cmpeq_epi16 x86 intrinsic", "_mm256_cmpeq_epi32 x86 intrinsic", "_mm256_cmpeq_epi64 x86 intrinsic", "_mm256_cmpeq_epi8 x86 intrinsic", "_mm256_cmpgt_epi16 x86 intrinsic", "_mm256_cmpgt_epi32 x86 intrinsic", "_mm256_cmpgt_epi64 x86 intrinsic", "_mm256_cmpgt_epi8 x86 intrinsic", "_mm256_cvtepi16_epi32 x86 intrinsic", "_mm256_cvtepi16_epi64 x86 intrinsic", "_mm256_cvtepi32_epi64 x86 intrinsic", "_mm256_cvtepi32_pd x86 intrinsic", "_mm256_cvtepi32_ps x86 intrinsic", "_mm256_cvtepi8_epi16 x86 intrinsic", "_mm256_cvtepi8_epi32 x86 intrinsic", "_mm256_cvtepi8_epi64 x86 intrinsic", "_mm256_cvtepu16_epi32 x86 intrinsic", "_mm256_cvtepu16_epi64 x86 intrinsic", "_mm256_cvtepu32_epi64 x86 intrinsic", "_mm256_cvtepu8_epi16 x86 intrinsic", "_mm256_cvtepu8_epi32 x86 intrinsic", "_mm256_cvtepu8_epi64 x86 intrinsic", "_mm256_cvtpd_epi32 x86 intrinsic", "_mm256_cvtpd_ps x86 intrinsic", "_mm256_cvtph_ps x86 intrinsic", "_mm256_cvtps_epi32 x86 intrinsic", "_mm256_cvtps_pd x86 intrinsic", "_mm256_cvtps_ph x86 intrinsic", "_mm256_cvttpd_epi32 x86 intrinsic", "_mm256_cvttps_epi32 x86 intrinsic", "_mm256_div_pd x86 intrinsic", "_mm256_div_ps x86 intrinsic", "_mm256_dp_ps x86 intrinsic", "_mm256_extractf128_pd x86 intrinsic", "_mm256_extractf128_ps x86 intrinsic", "_mm256_extractf128_si256 x86 intrinsic", "_mm256_extracti128_si256 x86 intrinsic", "_mm256_fmadd_pd x86 intrinsic", "_mm256_fmadd_ps x86 intrinsic", "_mm256_fmaddsub_pd x86 intrinsic", "_mm256_fmaddsub_ps x86 intrinsic", "_mm256_fmsub_pd x86 intrinsic", "_mm256_fmsub_ps x86 intrinsic", "_mm256_fmsubadd_pd x86 intrinsic", "_mm256_fmsubadd_ps x86 intrinsic", "_mm256_fnmadd_pd x86 intrinsic", "_mm256_fnmadd_ps x86 intrinsic", "_mm256_fnmsub_pd x86 intrinsic", "_mm256_fnmsub_ps x86 intrinsic", "_mm256_frcz_pd x86 intrinsic", "_mm256_frcz_ps x86 intrinsic", "_mm256_hadd_epi16 x86 intrinsic", "_mm256_hadd_epi32 x86 intrinsic", "_mm256_hadd_pd x86 intrinsic", "_mm256_hadd_ps x86 intrinsic", "_mm256_hadds_epi16 x86 intrinsic", "_mm256_hsub_epi16 x86 intrinsic", "_mm256_hsub_epi32 x86 intrinsic", "_mm256_hsub_pd x86 intrinsic", "_mm256_hsub_ps x86 intrinsic", "_mm256_hsubs_epi16 x86 intrinsic", "_mm256_i32gather_epi32 x86 intrinsic", "_mm256_i32gather_epi64 x86 intrinsic", "_mm256_i32gather_pd x86 intrinsic", "_mm256_i32gather_ps x86 intrinsic", "_mm256_i64gather_epi32 x86 intrinsic", "_mm256_i64gather_epi64 x86 intrinsic", "_mm256_i64gather_pd x86 intrinsic", "_mm256_i64gather_ps x86 intrinsic", "_mm256_insertf128_pd x86 intrinsic", "_mm256_insertf128_ps x86 intrinsic", "_mm256_insertf128_si256 x86 intrinsic", "_mm256_inserti128_si256 x86 intrinsic", "_mm256_lddqu_si256 x86 intrinsic", "_mm256_load_pd x86 intrinsic", "_mm256_load_ps x86 intrinsic", "_mm256_load_si256 x86 intrinsic", "_mm256_loadu_pd x86 intrinsic", "_mm256_loadu_ps x86 intrinsic", "_mm256_loadu_si256 x86 intrinsic", "_mm256_macc_pd x86 intrinsic", "_mm256_macc_ps x86 intrinsic", "_mm256_madd_epi16 x86 intrinsic", "_mm256_maddsub_pd x86 intrinsic", "_mm256_maddsub_ps x86 intrinsic", "_mm256_maddubs_epi16 x86 intrinsic", "_mm256_mask_i32gather_epi32 x86 intrinsic", "_mm256_mask_i32gather_epi64 x86 intrinsic", "_mm256_mask_i32gather_pd x86 intrinsic", "_mm256_mask_i32gather_ps x86 intrinsic", "_mm256_mask_i64gather_epi32 x86 intrinsic", "_mm256_mask_i64gather_epi64 x86 intrinsic", "_mm256_mask_i64gather_pd x86 intrinsic", "_mm256_mask_i64gather_ps x86 intrinsic", "_mm256_maskload_epi32 x86 intrinsic", "_mm256_maskload_epi64 x86 intrinsic", "_mm256_maskload_pd x86 intrinsic", "_mm256_maskload_ps x86 intrinsic", "_mm256_maskstore_epi32 x86 intrinsic", "_mm256_maskstore_epi64 x86 intrinsic", "_mm256_maskstore_pd x86 intrinsic", "_mm256_maskstore_ps x86 intrinsic", "_mm256_max_epi16 x86 intrinsic", "_mm256_max_epi32 x86 intrinsic", "_mm256_max_epi8 x86 intrinsic", "_mm256_max_epu16 x86 intrinsic", "_mm256_max_epu32 x86 intrinsic", "_mm256_max_epu8 x86 intrinsic", "_mm256_max_pd x86 intrinsic", "_mm256_max_ps x86 intrinsic", "_mm256_min_epi16 x86 intrinsic", "_mm256_min_epi32 x86 intrinsic", "_mm256_min_epi8 x86 intrinsic", "_mm256_min_epu16 x86 intrinsic", "_mm256_min_epu32 x86 intrinsic", "_mm256_min_epu8 x86 intrinsic", "_mm256_min_pd x86 intrinsic", "_mm256_min_ps x86 intrinsic", "_mm256_movedup_pd x86 intrinsic", "_mm256_movehdup_ps x86 intrinsic", "_mm256_moveldup_ps x86 intrinsic", "_mm256_movemask_epi8 x86 intrinsic", "_mm256_movemask_pd x86 intrinsic", "_mm256_movemask_ps x86 intrinsic", "_mm256_mpsadbw_epu8 x86 intrinsic", "_mm256_msub_pd x86 intrinsic", "_mm256_msub_ps x86 intrinsic", "_mm256_msubadd_pd x86 intrinsic", "_mm256_msubadd_ps x86 intrinsic", "_mm256_mul_epi32 x86 intrinsic", "_mm256_mul_epu32 x86 intrinsic", "_mm256_mul_pd x86 intrinsic", "_mm256_mul_ps x86 intrinsic", "_mm256_mulhi_epi16 x86 intrinsic", "_mm256_mulhi_epu16 x86 intrinsic", "_mm256_mulhrs_epi16 x86 intrinsic", "_mm256_mullo_epi16 x86 intrinsic", "_mm256_mullo_epi32 x86 intrinsic", "_mm256_nmacc_pd x86 intrinsic", "_mm256_nmacc_ps x86 intrinsic", "_mm256_nmsub_pd x86 intrinsic", "_mm256_nmsub_ps x86 intrinsic", "_mm256_or_pd x86 intrinsic", "_mm256_or_ps x86 intrinsic", "_mm256_or_si256 x86 intrinsic", "_mm256_packs_epi16 x86 intrinsic", "_mm256_packs_epi32 x86 intrinsic", "_mm256_packus_epi16 x86 intrinsic", "_mm256_packus_epi32 x86 intrinsic", "_mm256_permute_pd x86 intrinsic", "_mm256_permute_ps x86 intrinsic", "_mm256_permute2_pd x86 intrinsic", "_mm256_permute2_ps x86 intrinsic", "_mm256_permute2f128_pd x86 intrinsic", "_mm256_permute2f128_ps x86 intrinsic", "_mm256_permute2f128_si256 x86 intrinsic", "_mm256_permute2x128_si256 x86 intrinsic", "_mm256_permute4x64_epi64 x86 intrinsic", "_mm256_permute4x64_pd x86 intrinsic", "_mm256_permutevar_pd x86 intrinsic", "_mm256_permutevar_ps x86 intrinsic", "_mm256_permutevar8x32_epi32 x86 intrinsic", "_mm256_permutevar8x32_ps x86 intrinsic", "_mm256_rcp_ps x86 intrinsic", "_mm256_round_pd x86 intrinsic", "_mm256_round_ps x86 intrinsic", "_mm256_rsqrt_ps x86 intrinsic", "_mm256_sad_epu8 x86 intrinsic", "_mm256_set_epi16 x86 intrinsic", "_mm256_set_epi32 x86 intrinsic", "_mm256_set_epi8 x86 intrinsic", "_mm256_set_pd x86 intrinsic", "_mm256_set_ps x86 intrinsic", "_mm256_set1_epi16 x86 intrinsic", "_mm256_set1_epi32 x86 intrinsic", "_mm256_set1_epi8 x86 intrinsic", "_mm256_set1_pd x86 intrinsic", "_mm256_set1_ps x86 intrinsic", "_mm256_setr_epi16 x86 intrinsic", "_mm256_setr_epi32 x86 intrinsic", "_mm256_setr_epi8 x86 intrinsic", "_mm256_setr_pd x86 intrinsic", "_mm256_setr_ps x86 intrinsic", "_mm256_setzero_pd x86 intrinsic", "_mm256_setzero_ps x86 intrinsic", "_mm256_setzero_si256 x86 intrinsic", "_mm256_shuffle_epi32 x86 intrinsic", "_mm256_shuffle_epi8 x86 intrinsic", "_mm256_shuffle_pd x86 intrinsic", "_mm256_shuffle_ps x86 intrinsic", "_mm256_shufflehi_epi16 x86 intrinsic", "_mm256_shufflelo_epi16 x86 intrinsic", "_mm256_sign_epi16 x86 intrinsic", "_mm256_sign_epi32 x86 intrinsic", "_mm256_sign_epi8 x86 intrinsic", "_mm256_sll_epi16 x86 intrinsic", "_mm256_sll_epi32 x86 intrinsic", "_mm256_sll_epi64 x86 intrinsic", "_mm256_slli_epi16 x86 intrinsic", "_mm256_slli_epi32 x86 intrinsic", "_mm256_slli_epi64 x86 intrinsic", "_mm256_slli_si256 x86 intrinsic", "_mm256_sllv_epi32 x86 intrinsic", "_mm256_sllv_epi64 x86 intrinsic", "_mm256_sqrt_pd x86 intrinsic", "_mm256_sqrt_ps x86 intrinsic", "_mm256_sra_epi16 x86 intrinsic", "_mm256_sra_epi32 x86 intrinsic", "_mm256_srai_epi16 x86 intrinsic", "_mm256_srai_epi32 x86 intrinsic", "_mm256_srav_epi32 x86 intrinsic", "_mm256_srl_epi16 x86 intrinsic", "_mm256_srl_epi32 x86 intrinsic", "_mm256_srl_epi64 x86 intrinsic", "_mm256_srli_epi16 x86 intrinsic", "_mm256_srli_epi32 x86 intrinsic", "_mm256_srli_epi64 x86 intrinsic", "_mm256_srli_si256 x86 intrinsic", "_mm256_srlv_epi32 x86 intrinsic", "_mm256_srlv_epi64 x86 intrinsic", "_mm256_store_pd x86 intrinsic", "_mm256_store_ps x86 intrinsic", "_mm256_store_si256 x86 intrinsic", "_mm256_storeu_pd x86 intrinsic", "_mm256_storeu_ps x86 intrinsic", "_mm256_storeu_si256 x86 intrinsic", "_mm256_stream_load_si256 x86 intrinsic", "_mm256_stream_pd x86 intrinsic", "_mm256_stream_ps x86 intrinsic", "_mm256_stream_si256 x86 intrinsic", "_mm256_sub_epi16 x86 intrinsic", "_mm256_sub_epi32 x86 intrinsic", "_mm256_sub_epi64 x86 intrinsic", "_mm256_sub_epi8 x86 intrinsic", "_mm256_sub_pd x86 intrinsic", "_mm256_sub_ps x86 intrinsic", "_mm256_subs_epi16 x86 intrinsic", "_mm256_subs_epi8 x86 intrinsic", "_mm256_subs_epu16 x86 intrinsic", "_mm256_subs_epu8 x86 intrinsic", "_mm256_testc_pd x86 intrinsic", "_mm256_testc_ps x86 intrinsic", "_mm256_testc_si256 x86 intrinsic", "_mm256_testnzc_pd x86 intrinsic", "_mm256_testnzc_ps x86 intrinsic", "_mm256_testnzc_si256 x86 intrinsic", "_mm256_testz_pd x86 intrinsic", "_mm256_testz_ps x86 intrinsic", "_mm256_testz_si256 x86 intrinsic", "_mm256_unpackhi_epi16 x86 intrinsic", "_mm256_unpackhi_epi32 x86 intrinsic", "_mm256_unpackhi_epi64 x86 intrinsic", "_mm256_unpackhi_epi8 x86 intrinsic", "_mm256_unpackhi_pd x86 intrinsic", "_mm256_unpackhi_ps x86 intrinsic", "_mm256_unpacklo_epi16 x86 intrinsic", "_mm256_unpacklo_epi32 x86 intrinsic", "_mm256_unpacklo_epi64 x86 intrinsic", "_mm256_unpacklo_epi8 x86 intrinsic", "_mm256_unpacklo_pd x86 intrinsic", "_mm256_unpacklo_ps x86 intrinsic", "_mm256_xor_pd x86 intrinsic", "_mm256_xor_ps x86 intrinsic", "_mm256_xor_si256 x86 intrinsic", "_mm256_zeroall x86 intrinsic", "_mm256_zeroupper x86 intrinsic", "_mulx_u32 x86 intrinsic", "__nvreg_restore_fence x86 intrinsic", "__nvreg_save_fence x86 intrinsic", "_pdep_u32 x86 intrinsic", "_pext_u32 x86 intrinsic", "_rdrand16_step x86 intrinsic", "_rdrand32_step x86 intrinsic", "_rdseed16_step x86 intrinsic", "_rdseed32_step x86 intrinsic", "_rorx_u32 x86 intrinsic", "_rsm x86 intrinsic", "_sarx_i32 x86 intrinsic", "_sgdt x86 intrinsic", "_shlx_u32 x86 intrinsic", "_shrx_u32 x86 intrinsic", "__slwpcb x86 intrinsic", "_stac x86 intrinsic", "_store_be_u16 x86 intrinsic", "_storebe_i16 x86 intrinsic", "_store_be_u32 x86 intrinsic", "_storebe_i32 x86 intrinsic", "_Store_HLERelease x86 intrinsic", "_StorePointer_HLERelease x86 intrinsic", "_subborrow_u16 x86 intrinsic", "_subborrow_u32 x86 intrinsic", "_subborrow_u8 x86 intrinsic", "_t1mskc_u32 x86 intrinsic", "_tzcnt_u32 x86 intrinsic", "_tzmsk_u32 x86 intrinsic", "_xabort x86 intrinsic", "_xbegin x86 intrinsic", "_xend x86 intrinsic", "_xgetbv x86 intrinsic", "_xrstor x86 intrinsic", "_xsave x86 intrinsic", "_xsaveopt x86 intrinsic", "_xsetbv x86 intrinsic", "_xtest x86 intrinsic"] +ms.date: 08/30/2022 +f1_keywords: ["intrin/_addcarry_u16", "intrin/_addcarry_u32", "intrin/_addcarry_u8", "immintrin/_addcarryx_u32", "ammintrin/_andn_u32", "ammintrin/_bextr_u32", "ammintrin/_bextri_u32", "ammintrin/_blcfill_u32", "ammintrin/_blci_u32", "ammintrin/_blcic_u32", "ammintrin/_blcmsk_u32", "ammintrin/_blcs_u32", "ammintrin/_blsfill_u32", "ammintrin/_blsi_u32", "ammintrin/_blsic_u32", "ammintrin/_blsmsk_u32", "ammintrin/_blsr_u32", "immintrin/_bzhi_u32", "immintrin/_castf32_u32", "immintrin/_castf64_u64", "immintrin/_castu32_f32", "immintrin/_castu64_f64", "intrin/_clac", "immintrin/_fxrstor", "immintrin/_fxsave", "immintrin/_invpcid", "intrin/_lgdt", "immintrin/_load_be_u16", "immintrin/_loadbe_i16", "immintrin/_load_be_u32", "immintrin/_loadbe_i32", "ammintrin/__llwpcb", "ammintrin/__lwpins32", "ammintrin/__lwpval32", "ammintrin/_lzcnt_u32", "intrin/_m_empty", "intrin/_m_femms", "intrin/_m_from_float", "intrin/_m_from_int", "intrin/_m_maskmovq", "intrin/_m_packssdw", "intrin/_m_packsswb", "intrin/_m_packuswb", "intrin/_m_paddb", "intrin/_m_paddd", "intrin/_m_paddsb", "intrin/_m_paddsw", "intrin/_m_paddusb", "intrin/_m_paddusw", "intrin/_m_paddw", "intrin/_m_pand", "intrin/_m_pandn", "intrin/_m_pavgb", "intrin/_m_pavgusb", "intrin/_m_pavgw", "intrin/_m_pcmpeqb", "intrin/_m_pcmpeqd", "intrin/_m_pcmpeqw", "intrin/_m_pcmpgtb", "intrin/_m_pcmpgtd", "intrin/_m_pcmpgtw", "intrin/_m_pextrw", "intrin/_m_pf2id", "intrin/_m_pf2iw", "intrin/_m_pfacc", "intrin/_m_pfadd", "intrin/_m_pfcmpeq", "intrin/_m_pfcmpge", "intrin/_m_pfcmpgt", "intrin/_m_pfmax", "intrin/_m_pfmin", "intrin/_m_pfmul", "intrin/_m_pfnacc", "intrin/_m_pfpnacc", "intrin/_m_pfrcp", "intrin/_m_pfrcpit1", "intrin/_m_pfrcpit2", "intrin/_m_pfrsqit1", "intrin/_m_pfrsqrt", "intrin/_m_pfsub", "intrin/_m_pfsubr", "intrin/_m_pi2fd", "intrin/_m_pi2fw", "intrin/_m_pinsrw", "intrin/_m_pmaddwd", "intrin/_m_pmaxsw", "intrin/_m_pmaxub", "intrin/_m_pminsw", "intrin/_m_pminub", "intrin/_m_pmovmskb", "intrin/_m_pmulhrw", "intrin/_m_pmulhuw", "intrin/_m_pmulhw", "intrin/_m_pmullw", "intrin/_m_por", "intrin/_m_prefetch", "intrin/_m_prefetchw", "intrin/_m_psadbw", "intrin/_m_pshufw", "intrin/_m_pslld", "intrin/_m_pslldi", "intrin/_m_psllq", "intrin/_m_psllqi", "intrin/_m_psllw", "intrin/_m_psllwi", "intrin/_m_psrad", "intrin/_m_psradi", "intrin/_m_psraw", "intrin/_m_psrawi", "intrin/_m_psrld", "intrin/_m_psrldi", "intrin/_m_psrlq", "intrin/_m_psrlqi", "intrin/_m_psrlw", "intrin/_m_psrlwi", "intrin/_m_psubb", "intrin/_m_psubd", "intrin/_m_psubsb", "intrin/_m_psubsw", "intrin/_m_psubusb", "intrin/_m_psubusw", "intrin/_m_psubw", "intrin/_m_pswapd", "intrin/_m_punpckhbw", "intrin/_m_punpckhdq", "intrin/_m_punpckhwd", "intrin/_m_punpcklbw", "intrin/_m_punpckldq", "intrin/_m_punpcklwd", "intrin/_m_pxor", "intrin/_m_to_float", "intrin/_m_to_int", "intrin/_mm_abs_epi16", "intrin/_mm_abs_epi32", "intrin/_mm_abs_epi8", "intrin/_mm_abs_pi16", "intrin/_mm_abs_pi32", "intrin/_mm_abs_pi8", "intrin/_mm_add_epi16", "intrin/_mm_add_epi32", "intrin/_mm_add_epi64", "intrin/_mm_add_epi8", "intrin/_mm_add_pd", "mmintrin/_mm_add_pi8", "mmintrin/_mm_add_pi16", "mmintrin/_mm_add_pi32", "intrin/_mm_add_ps", "intrin/_mm_add_sd", "intrin/_mm_add_si64", "intrin/_mm_add_ss", "intrin/_mm_adds_epi16", "intrin/_mm_adds_epi8", "intrin/_mm_adds_epu16", "intrin/_mm_adds_epu8", "mmintrin/_mm_adds_pi8", "mmintrin/_mm_adds_pi16", "mmintrin/_mm_adds_pu8", "mmintrin/_mm_adds_pu16", "intrin/_mm_addsub_pd", "intrin/_mm_addsub_ps", "immintrin/_mm_aesdec_si128", "immintrin/_mm_aesdeclast_si128", "immintrin/_mm_aesenc_si128", "immintrin/_mm_aesenclast_si128", "immintrin/_mm_aesimc_si128", "immintrin/_mm_aeskeygenassist_si128", "intrin/_mm_alignr_epi8", "intrin/_mm_alignr_pi8", "intrin/_mm_and_pd", "intrin/_mm_and_ps", "mmintrin/_mm_and_si64", "intrin/_mm_and_si128", "intrin/_mm_andnot_pd", "intrin/_mm_andnot_ps", "mmintrin/_mm_andnot_si64", "intrin/_mm_andnot_si128", "intrin/_mm_avg_epu16", "intrin/_mm_avg_epu8", "intrin/_mm_blend_epi16", "immintrin/_mm_blend_epi32", "intrin/_mm_blend_pd", "intrin/_mm_blend_ps", "intrin/_mm_blendv_epi8", "intrin/_mm_blendv_pd", "intrin/_mm_blendv_ps", "immintrin/_mm_broadcast_ss", "immintrin/_mm_broadcastb_epi8", "immintrin/_mm_broadcastd_epi32", "immintrin/_mm_broadcastq_epi64", "immintrin/_mm_broadcastsd_pd", "immintrin/_mm_broadcastss_ps", "immintrin/_mm_broadcastw_epi16", "intrin/_mm_castpd_ps", "intrin/_mm_castpd_si128", "intrin/_mm_castps_pd", "intrin/_mm_castps_si128", "intrin/_mm_castsi128_pd", "intrin/_mm_castsi128_ps", "intrin/_mm_clflush", "immintrin/_mm_clmulepi64_si128", "ammintrin/_mm_cmov_si128", "immintrin/_mm_cmp_pd", "immintrin/_mm_cmp_ps", "immintrin/_mm_cmp_sd", "immintrin/_mm_cmp_ss", "intrin/_mm_cmpeq_epi16", "intrin/_mm_cmpeq_epi32", "intrin/_mm_cmpeq_epi64", "intrin/_mm_cmpeq_epi8", "intrin/_mm_cmpeq_pd", "mmintrin/_mm_cmpeq_pi8", "mmintrin/_mm_cmpeq_pi16", "mmintrin/_mm_cmpeq_pi32", "intrin/_mm_cmpeq_ps", "intrin/_mm_cmpeq_sd", "intrin/_mm_cmpeq_ss", "intrin/_mm_cmpestra", "intrin/_mm_cmpestrc", "intrin/_mm_cmpestri", "intrin/_mm_cmpestrm", "intrin/_mm_cmpestro", "intrin/_mm_cmpestrs", "intrin/_mm_cmpestrz", "intrin/_mm_cmpge_pd", "intrin/_mm_cmpge_ps", "intrin/_mm_cmpge_sd", "intrin/_mm_cmpge_ss", "intrin/_mm_cmpgt_epi16", "intrin/_mm_cmpgt_epi32", "intrin/_mm_cmpgt_epi64", "intrin/_mm_cmpgt_epi8", "mmintrin/_mm_cmpgt_pi8", "mmintrin/_mm_cmpgt_pi16", "mmintrin/_mm_cmpgt_pi32", "intrin/_mm_cmpgt_pd", "intrin/_mm_cmpgt_ps", "intrin/_mm_cmpgt_sd", "intrin/_mm_cmpgt_ss", "intrin/_mm_cmpistra", "intrin/_mm_cmpistrc", "intrin/_mm_cmpistri", "intrin/_mm_cmpistrm", "intrin/_mm_cmpistro", "intrin/_mm_cmpistrs", "intrin/_mm_cmpistrz", "intrin/_mm_cmple_pd", "intrin/_mm_cmple_ps", "intrin/_mm_cmple_sd", "intrin/_mm_cmple_ss", "intrin/_mm_cmplt_epi16", "intrin/_mm_cmplt_epi32", "intrin/_mm_cmplt_epi8", "intrin/_mm_cmplt_pd", "intrin/_mm_cmplt_ps", "intrin/_mm_cmplt_sd", "intrin/_mm_cmplt_ss", "intrin/_mm_cmpneq_pd", "intrin/_mm_cmpneq_ps", "intrin/_mm_cmpneq_sd", "intrin/_mm_cmpneq_ss", "intrin/_mm_cmpnge_pd", "intrin/_mm_cmpnge_ps", "intrin/_mm_cmpnge_sd", "intrin/_mm_cmpnge_ss", "intrin/_mm_cmpngt_pd", "intrin/_mm_cmpngt_ps", "intrin/_mm_cmpngt_sd", "intrin/_mm_cmpngt_ss", "intrin/_mm_cmpnle_pd", "intrin/_mm_cmpnle_ps", "intrin/_mm_cmpnle_sd", "intrin/_mm_cmpnle_ss", "intrin/_mm_cmpnlt_pd", "intrin/_mm_cmpnlt_ps", "intrin/_mm_cmpnlt_sd", "intrin/_mm_cmpnlt_ss", "intrin/_mm_cmpord_pd", "intrin/_mm_cmpord_ps", "intrin/_mm_cmpord_sd", "intrin/_mm_cmpord_ss", "intrin/_mm_cmpunord_pd", "intrin/_mm_cmpunord_ps", "intrin/_mm_cmpunord_sd", "intrin/_mm_cmpunord_ss", "ammintrin/_mm_com_epi16", "ammintrin/_mm_com_epi32", "ammintrin/_mm_com_epi64", "ammintrin/_mm_com_epi8", "ammintrin/_mm_com_epu16", "ammintrin/_mm_com_epu32", "ammintrin/_mm_com_epu64", "ammintrin/_mm_com_epu8", "intrin/_mm_comieq_sd", "intrin/_mm_comieq_ss", "intrin/_mm_comige_sd", "intrin/_mm_comige_ss", "intrin/_mm_comigt_sd", "intrin/_mm_comigt_ss", "intrin/_mm_comile_sd", "intrin/_mm_comile_ss", "intrin/_mm_comilt_sd", "intrin/_mm_comilt_ss", "intrin/_mm_comineq_sd", "intrin/_mm_comineq_ss", "intrin/_mm_crc32_u16", "intrin/_mm_crc32_u32", "intrin/_mm_crc32_u8", "intrin/_mm_cvt_pi2ps", "intrin/_mm_cvt_ps2pi", "intrin/_mm_cvt_si2ss", "intrin/_mm_cvt_ss2si", "intrin/_mm_cvtepi16_epi32", "intrin/_mm_cvtepi16_epi64", "intrin/_mm_cvtepi32_epi64", "intrin/_mm_cvtepi32_pd", "intrin/_mm_cvtepi32_ps", "intrin/_mm_cvtepi8_epi16", "intrin/_mm_cvtepi8_epi32", "intrin/_mm_cvtepi8_epi64", "intrin/_mm_cvtepu16_epi32", "intrin/_mm_cvtepu16_epi64", "intrin/_mm_cvtepu32_epi64", "intrin/_mm_cvtepu8_epi16", "intrin/_mm_cvtepu8_epi32", "intrin/_mm_cvtepu8_epi64", "intrin/_mm_cvtpd_epi32", "intrin/_mm_cvtpd_pi32", "intrin/_mm_cvtpd_ps", "immintrin/_mm_cvtph_ps", "intrin/_mm_cvtpi32_pd", "intrin/_mm_cvtps_epi32", "intrin/_mm_cvtps_pd", "immintrin/_mm_cvtps_ph", "intrin/_mm_cvtsd_f64", "intrin/_mm_cvtsd_si32", "intrin/_mm_cvtsd_ss", "intrin/_mm_cvtsi128_si32", "intrin/_mm_cvtsi32_sd", "intrin/_mm_cvtsi32_si128", "mmintrin/_mm_cvtsi32_si64", "mmintrin/_mm_cvtsi64_si32", "intrin/_mm_cvtss_f32", "intrin/_mm_cvtss_sd", "intrin/_mm_cvtt_ps2pi", "intrin/_mm_cvtt_ss2si", "intrin/_mm_cvttpd_epi32", "intrin/_mm_cvttpd_pi32", "intrin/_mm_cvttps_epi32", "intrin/_mm_cvttsd_si32", "intrin/_mm_div_pd", "intrin/_mm_div_ps", "intrin/_mm_div_sd", "intrin/_mm_div_ss", "intrin/_mm_dp_pd", "intrin/_mm_dp_ps", "mmintrin/_mm_empty", "intrin/_mm_extract_epi16", "intrin/_mm_extract_epi32", "intrin/_mm_extract_epi8", "intrin/_mm_extract_ps", "immintrin/_mm_fmadd_pd", "immintrin/_mm_fmadd_ps", "immintrin/_mm_fmadd_sd", "immintrin/_mm_fmadd_ss", "immintrin/_mm_fmaddsub_pd", "immintrin/_mm_fmaddsub_ps", "immintrin/_mm_fmsub_pd", "immintrin/_mm_fmsub_ps", "immintrin/_mm_fmsub_sd", "immintrin/_mm_fmsub_ss", "immintrin/_mm_fmsubadd_pd", "immintrin/_mm_fmsubadd_ps", "immintrin/_mm_fnmadd_pd", "immintrin/_mm_fnmadd_ps", "immintrin/_mm_fnmadd_sd", "immintrin/_mm_fnmadd_ss", "immintrin/_mm_fnmsub_pd", "immintrin/_mm_fnmsub_ps", "immintrin/_mm_fnmsub_sd", "immintrin/_mm_fnmsub_ss", "ammintrin/_mm_frcz_pd", "ammintrin/_mm_frcz_ps", "ammintrin/_mm_frcz_sd", "ammintrin/_mm_frcz_ss", "intrin/_mm_getcsr", "intrin/_mm_hadd_epi16", "intrin/_mm_hadd_epi32", "intrin/_mm_hadd_pd", "intrin/_mm_hadd_pi16", "intrin/_mm_hadd_pi32", "intrin/_mm_hadd_ps", "ammintrin/_mm_haddd_epi16", "ammintrin/_mm_haddd_epi8", "ammintrin/_mm_haddd_epu16", "ammintrin/_mm_haddd_epu8", "ammintrin/_mm_haddq_epi16", "ammintrin/_mm_haddq_epi32", "ammintrin/_mm_haddq_epi8", "ammintrin/_mm_haddq_epu16", "ammintrin/_mm_haddq_epu32", "ammintrin/_mm_haddq_epu8", "intrin/_mm_hadds_epi16", "intrin/_mm_hadds_pi16", "ammintrin/_mm_haddw_epi8", "ammintrin/_mm_haddw_epu8", "intrin/_mm_hsub_epi16", "intrin/_mm_hsub_epi32", "intrin/_mm_hsub_pd", "intrin/_mm_hsub_pi16", "intrin/_mm_hsub_pi32", "intrin/_mm_hsub_ps", "ammintrin/_mm_hsubd_epi16", "ammintrin/_mm_hsubq_epi32", "intrin/_mm_hsubs_epi16", "intrin/_mm_hsubs_pi16", "ammintrin/_mm_hsubw_epi8", "immintrin/_mm_i32gather_epi32", "immintrin/_mm_i32gather_epi64", "immintrin/_mm_i32gather_pd", "immintrin/_mm_i32gather_ps", "immintrin/_mm_i64gather_epi32", "immintrin/_mm_i64gather_epi64", "immintrin/_mm_i64gather_pd", "immintrin/_mm_i64gather_ps", "intrin/_mm_insert_epi16", "intrin/_mm_insert_epi32", "intrin/_mm_insert_epi8", "intrin/_mm_insert_ps", "intrin/_mm_lddqu_si128", "intrin/_mm_lfence", "intrin/_mm_load_pd", "intrin/_mm_load_ps", "intrin/_mm_load_ps1", "intrin/_mm_load_sd", "intrin/_mm_load_si128", "intrin/_mm_load_ss", "intrin/_mm_load1_pd", "intrin/_mm_loaddup_pd", "intrin/_mm_loadh_pd", "intrin/_mm_loadh_pi", "intrin/_mm_loadl_epi64", "intrin/_mm_loadl_pd", "intrin/_mm_loadl_pi", "intrin/_mm_loadr_pd", "intrin/_mm_loadr_ps", "intrin/_mm_loadu_pd", "intrin/_mm_loadu_ps", "intrin/_mm_loadu_si128", "ammintrin/_mm_macc_epi16", "ammintrin/_mm_macc_epi32", "ammintrin/_mm_macc_pd", "ammintrin/_mm_macc_ps", "ammintrin/_mm_macc_sd", "ammintrin/_mm_macc_ss", "ammintrin/_mm_maccd_epi16", "ammintrin/_mm_macchi_epi32", "ammintrin/_mm_macclo_epi32", "ammintrin/_mm_maccs_epi16", "ammintrin/_mm_maccs_epi32", "ammintrin/_mm_maccsd_epi16", "ammintrin/_mm_maccshi_epi32", "ammintrin/_mm_maccslo_epi32", "intrin/_mm_madd_epi16", "mmintrin/_mm_madd_pi16", "ammintrin/_mm_maddd_epi16", "ammintrin/_mm_maddsd_epi16", "ammintrin/_mm_maddsub_pd", "ammintrin/_mm_maddsub_ps", "intrin/_mm_maddubs_epi16", "intrin/_mm_maddubs_pi16", "immintrin/_mm_mask_i32gather_epi32", "immintrin/_mm_mask_i32gather_epi64", "immintrin/_mm_mask_i32gather_pd", "immintrin/_mm_mask_i32gather_ps", "immintrin/_mm_mask_i64gather_epi32", "immintrin/_mm_mask_i64gather_epi64", "immintrin/_mm_mask_i64gather_pd", "immintrin/_mm_mask_i64gather_ps", "immintrin/_mm_maskload_epi32", "immintrin/_mm_maskload_epi64", "immintrin/_mm_maskload_pd", "immintrin/_mm_maskload_ps", "intrin/_mm_maskmoveu_si128", "immintrin/_mm_maskstore_epi32", "immintrin/_mm_maskstore_epi64", "immintrin/_mm_maskstore_pd", "immintrin/_mm_maskstore_ps", "intrin/_mm_max_epi16", "intrin/_mm_max_epi32", "intrin/_mm_max_epi8", "intrin/_mm_max_epu16", "intrin/_mm_max_epu32", "intrin/_mm_max_epu8", "intrin/_mm_max_pd", "intrin/_mm_max_ps", "intrin/_mm_max_sd", "intrin/_mm_max_ss", "intrin/_mm_mfence", "intrin/_mm_min_epi16", "intrin/_mm_min_epi32", "intrin/_mm_min_epi8", "intrin/_mm_min_epu16", "intrin/_mm_min_epu32", "intrin/_mm_min_epu8", "intrin/_mm_min_pd", "intrin/_mm_min_ps", "intrin/_mm_min_sd", "intrin/_mm_min_ss", "intrin/_mm_minpos_epu16", "intrin/_mm_monitor", "intrin/_mm_move_epi64", "intrin/_mm_move_sd", "intrin/_mm_move_ss", "intrin/_mm_movedup_pd", "intrin/_mm_movehdup_ps", "intrin/_mm_movehl_ps", "intrin/_mm_moveldup_ps", "intrin/_mm_movelh_ps", "intrin/_mm_movemask_epi8", "intrin/_mm_movemask_pd", "intrin/_mm_movemask_ps", "intrin/_mm_movepi64_pi64", "intrin/_mm_movpi64_epi64", "intrin/_mm_mpsadbw_epu8", "ammintrin/_mm_msub_pd", "ammintrin/_mm_msub_ps", "ammintrin/_mm_msub_sd", "ammintrin/_mm_msub_ss", "ammintrin/_mm_msubadd_pd", "ammintrin/_mm_msubadd_ps", "intrin/_mm_mul_epi32", "intrin/_mm_mul_epu32", "intrin/_mm_mul_pd", "intrin/_mm_mul_ps", "intrin/_mm_mul_sd", "intrin/_mm_mul_ss", "intrin/_mm_mul_su32", "intrin/_mm_mulhi_epi16", "intrin/_mm_mulhi_epu16", "mmintrin/_mm_mulhi_pi16", "intrin/_mm_mulhrs_epi16", "intrin/_mm_mulhrs_pi16", "intrin/_mm_mullo_epi16", "intrin/_mm_mullo_epi32", "mmintrin/_mm_mullo_pi16", "intrin/_mm_mwait", "ammintrin/_mm_nmacc_pd", "ammintrin/_mm_nmacc_ps", "ammintrin/_mm_nmacc_sd", "ammintrin/_mm_nmacc_ss", "ammintrin/_mm_nmsub_pd", "ammintrin/_mm_nmsub_ps", "ammintrin/_mm_nmsub_sd", "ammintrin/_mm_nmsub_ss", "intrin/_mm_or_pd", "intrin/_mm_or_ps", "mmintrin/_mm_or_si64", "intrin/_mm_or_si128", "intrin/_mm_packs_epi16", "intrin/_mm_packs_epi32", "mmintrin/_mm_packs_pi16", "mmintrin/_mm_packs_pi32", "mmintrin/_mm_packs_pu16", "intrin/_mm_packus_epi16", "intrin/_mm_packus_epi32", "intrin/_mm_pause", "ammintrin/_mm_perm_epi8", "immintrin/_mm_permute_pd", "immintrin/_mm_permute_ps", "ammintrin/_mm_permute2_pd", "ammintrin/_mm_permute2_ps", "immintrin/_mm_permutevar_pd", "immintrin/_mm_permutevar_ps", "intrin/_mm_popcnt_u32", "intrin/_mm_prefetch", "intrin/_mm_rcp_ps", "intrin/_mm_rcp_ss", "ammintrin/_mm_rot_epi16", "ammintrin/_mm_rot_epi32", "ammintrin/_mm_rot_epi64", "ammintrin/_mm_rot_epi8", "ammintrin/_mm_roti_epi16", "ammintrin/_mm_roti_epi32", "ammintrin/_mm_roti_epi64", "ammintrin/_mm_roti_epi8", "intrin/_mm_round_pd", "intrin/_mm_round_ps", "intrin/_mm_round_sd", "intrin/_mm_round_ss", "intrin/_mm_rsqrt_ps", "intrin/_mm_rsqrt_ss", "intrin/_mm_sad_epu8", "intrin/_mm_set_epi16", "intrin/_mm_set_epi32", "intrin/_mm_set_epi64", "intrin/_mm_set_epi8", "intrin/_mm_set_pd", "intrin/_mm_set_pi16", "intrin/_mm_set_pi32", "intrin/_mm_set_pi8", "intrin/_mm_set_ps", "intrin/_mm_set_ps1", "intrin/_mm_set_sd", "intrin/_mm_set_ss", "intrin/_mm_set1_epi16", "intrin/_mm_set1_epi32", "intrin/_mm_set1_epi64", "intrin/_mm_set1_epi8", "intrin/_mm_set1_pd", "intrin/_mm_set1_pi16", "intrin/_mm_set1_pi32", "intrin/_mm_set1_pi8", "intrin/_mm_setcsr", "intrin/_mm_setl_epi64", "intrin/_mm_setr_epi16", "intrin/_mm_setr_epi32", "intrin/_mm_setr_epi64", "intrin/_mm_setr_epi8", "intrin/_mm_setr_pd", "intrin/_mm_setr_pi16", "intrin/_mm_setr_pi32", "intrin/_mm_setr_pi8", "intrin/_mm_setr_ps", "intrin/_mm_setzero_pd", "intrin/_mm_setzero_ps", "intrin/_mm_setzero_si128", "intrin/_mm_setzero_si64", "intrin/_mm_sfence", "ammintrin/_mm_sha_epi16", "ammintrin/_mm_sha_epi32", "ammintrin/_mm_sha_epi64", "ammintrin/_mm_sha_epi8", "ammintrin/_mm_shl_epi16", "ammintrin/_mm_shl_epi32", "ammintrin/_mm_shl_epi64", "ammintrin/_mm_shl_epi8", "intrin/_mm_shuffle_epi32", "intrin/_mm_shuffle_epi8", "intrin/_mm_shuffle_pd", "intrin/_mm_shuffle_pi8", "intrin/_mm_shuffle_ps", "intrin/_mm_shufflehi_epi16", "intrin/_mm_shufflelo_epi16", "intrin/_mm_sign_epi16", "intrin/_mm_sign_epi32", "intrin/_mm_sign_epi8", "intrin/_mm_sign_pi16", "intrin/_mm_sign_pi32", "intrin/_mm_sign_pi8", "intrin/_mm_sll_epi16", "intrin/_mm_sll_epi32", "intrin/_mm_sll_epi64", "mmintrin/_mm_sll_pi16", "mmintrin/_mm_sll_pi32", "mmintrin/_mm_sll_si64", "intrin/_mm_slli_epi16", "intrin/_mm_slli_epi32", "intrin/_mm_slli_epi64", "mmintrin/_mm_slli_pi16", "mmintrin/_mm_slli_pi32", "mmintrin/_mm_slli_si64", "intrin/_mm_slli_si128", "immintrin/_mm_sllv_epi32", "immintrin/_mm_sllv_epi64", "intrin/_mm_sqrt_pd", "intrin/_mm_sqrt_ps", "intrin/_mm_sqrt_sd", "intrin/_mm_sqrt_ss", "intrin/_mm_sra_epi16", "intrin/_mm_sra_epi32", "mmintrin/_mm_sra_pi16", "mmintrin/_mm_sra_pi32", "intrin/_mm_srai_epi16", "intrin/_mm_srai_epi32", "mmintrin/_mm_srai_pi16", "mmintrin/_mm_srai_pi32", "immintrin/_mm_srav_epi32", "intrin/_mm_srl_epi16", "intrin/_mm_srl_epi32", "intrin/_mm_srl_epi64", "mmintrin/_mm_srl_pi16", "mmintrin/_mm_srl_pi32", "mmintrin/_mm_srl_si64", "intrin/_mm_srli_epi16", "intrin/_mm_srli_epi32", "intrin/_mm_srli_epi64", "mmintrin/_mm_srli_pi16", "mmintrin/_mm_srli_pi32", "mmintrin/_mm_srli_si64", "intrin/_mm_srli_si128", "immintrin/_mm_srlv_epi32", "immintrin/_mm_srlv_epi64", "intrin/_mm_store_pd", "intrin/_mm_store_ps", "intrin/_mm_store_ps1", "intrin/_mm_store_sd", "intrin/_mm_store_si128", "intrin/_mm_store_ss", "intrin/_mm_store1_pd", "intrin/_mm_storeh_pd", "intrin/_mm_storeh_pi", "intrin/_mm_storel_epi64", "intrin/_mm_storel_pd", "intrin/_mm_storel_pi", "intrin/_mm_storer_pd", "intrin/_mm_storer_ps", "intrin/_mm_storeu_pd", "intrin/_mm_storeu_ps", "intrin/_mm_storeu_si128", "intrin/_mm_stream_load_si128", "intrin/_mm_stream_pd", "intrin/_mm_stream_pi", "intrin/_mm_stream_ps", "intrin/_mm_stream_si128", "intrin/_mm_stream_si32", "intrin/_mm_sub_epi16", "intrin/_mm_sub_epi32", "intrin/_mm_sub_epi64", "intrin/_mm_sub_epi8", "intrin/_mm_sub_pd", "mmintrin/_mm_sub_pi8", "mmintrin/_mm_sub_pi16", "mmintrin/_mm_sub_pi32", "intrin/_mm_sub_ps", "intrin/_mm_sub_sd", "intrin/_mm_sub_si64", "intrin/_mm_sub_ss", "intrin/_mm_subs_epi16", "intrin/_mm_subs_epi8", "intrin/_mm_subs_epu16", "intrin/_mm_subs_epu8", "mmintrin/_mm_subs_pi8", "mmintrin/_mm_subs_pi16", "mmintrin/_mm_subs_pu8", "mmintrin/_mm_subs_pu16", "immintrin/_mm_testc_pd", "immintrin/_mm_testc_ps", "intrin/_mm_testc_si128", "immintrin/_mm_testnzc_pd", "immintrin/_mm_testnzc_ps", "intrin/_mm_testnzc_si128", "immintrin/_mm_testz_pd", "immintrin/_mm_testz_ps", "intrin/_mm_testz_si128", "intrin/_mm_ucomieq_sd", "intrin/_mm_ucomieq_ss", "intrin/_mm_ucomige_sd", "intrin/_mm_ucomige_ss", "intrin/_mm_ucomigt_sd", "intrin/_mm_ucomigt_ss", "intrin/_mm_ucomile_sd", "intrin/_mm_ucomile_ss", "intrin/_mm_ucomilt_sd", "intrin/_mm_ucomilt_ss", "intrin/_mm_ucomineq_sd", "intrin/_mm_ucomineq_ss", "intrin/_mm_unpackhi_epi16", "intrin/_mm_unpackhi_epi32", "intrin/_mm_unpackhi_epi64", "intrin/_mm_unpackhi_epi8", "intrin/_mm_unpackhi_pd", "mmintrin/_mm_unpackhi_pi8", "mmintrin/_mm_unpackhi_pi16", "mmintrin/_mm_unpackhi_pi32", "intrin/_mm_unpackhi_ps", "intrin/_mm_unpacklo_epi16", "intrin/_mm_unpacklo_epi32", "intrin/_mm_unpacklo_epi64", "intrin/_mm_unpacklo_epi8", "intrin/_mm_unpacklo_pd", "mmintrin/_mm_unpacklo_pi8", "mmintrin/_mm_unpacklo_pi16", "mmintrin/_mm_unpacklo_pi32", "intrin/_mm_unpacklo_ps", "intrin/_mm_xor_pd", "intrin/_mm_xor_ps", "mmintrin/_mm_xor_si64", "intrin/_mm_xor_si128", "immintrin/_mm256_abs_epi16", "immintrin/_mm256_abs_epi32", "immintrin/_mm256_abs_epi8", "immintrin/_mm256_add_epi16", "immintrin/_mm256_add_epi32", "immintrin/_mm256_add_epi64", "immintrin/_mm256_add_epi8", "immintrin/_mm256_add_pd", "immintrin/_mm256_add_ps", "immintrin/_mm256_adds_epi16", "immintrin/_mm256_adds_epi8", "immintrin/_mm256_adds_epu16", "immintrin/_mm256_adds_epu8", "immintrin/_mm256_addsub_pd", "immintrin/_mm256_addsub_ps", "immintrin/_mm256_alignr_epi8", "immintrin/_mm256_and_pd", "immintrin/_mm256_and_ps", "immintrin/_mm256_and_si256", "immintrin/_mm256_andnot_pd", "immintrin/_mm256_andnot_ps", "immintrin/_mm256_andnot_si256", "immintrin/_mm256_avg_epu16", "immintrin/_mm256_avg_epu8", "immintrin/_mm256_blend_epi16", "immintrin/_mm256_blend_epi32", "immintrin/_mm256_blend_pd", "immintrin/_mm256_blend_ps", "immintrin/_mm256_blendv_epi8", "immintrin/_mm256_blendv_pd", "immintrin/_mm256_blendv_ps", "immintrin/_mm256_broadcast_pd", "immintrin/_mm256_broadcast_ps", "immintrin/_mm256_broadcast_sd", "immintrin/_mm256_broadcast_ss", "immintrin/_mm256_broadcastb_epi8", "immintrin/_mm256_broadcastd_epi32", "immintrin/_mm256_broadcastq_epi64", "immintrin/_mm256_broadcastsd_pd", "immintrin/_mm256_broadcastsi128_si256", "immintrin/_mm256_broadcastss_ps", "immintrin/_mm256_broadcastw_epi16", "immintrin/_mm256_castpd_ps", "immintrin/_mm256_castpd_si256", "immintrin/_mm256_castpd128_pd256", "immintrin/_mm256_castpd256_pd128", "immintrin/_mm256_castps_pd", "immintrin/_mm256_castps_si256", "immintrin/_mm256_castps128_ps256", "immintrin/_mm256_castps256_ps128", "immintrin/_mm256_castsi128_si256", "immintrin/_mm256_castsi256_pd", "immintrin/_mm256_castsi256_ps", "immintrin/_mm256_castsi256_si128", "ammintrin/_mm256_cmov_si256", "immintrin/_mm256_cmp_pd", "immintrin/_mm256_cmp_ps", "immintrin/_mm256_cmpeq_epi16", "immintrin/_mm256_cmpeq_epi32", "immintrin/_mm256_cmpeq_epi64", "immintrin/_mm256_cmpeq_epi8", "immintrin/_mm256_cmpgt_epi16", "immintrin/_mm256_cmpgt_epi32", "immintrin/_mm256_cmpgt_epi64", "immintrin/_mm256_cmpgt_epi8", "immintrin/_mm256_cvtepi16_epi32", "immintrin/_mm256_cvtepi16_epi64", "immintrin/_mm256_cvtepi32_epi64", "immintrin/_mm256_cvtepi32_pd", "immintrin/_mm256_cvtepi32_ps", "immintrin/_mm256_cvtepi8_epi16", "immintrin/_mm256_cvtepi8_epi32", "immintrin/_mm256_cvtepi8_epi64", "immintrin/_mm256_cvtepu16_epi32", "immintrin/_mm256_cvtepu16_epi64", "immintrin/_mm256_cvtepu32_epi64", "immintrin/_mm256_cvtepu8_epi16", "immintrin/_mm256_cvtepu8_epi32", "immintrin/_mm256_cvtepu8_epi64", "immintrin/_mm256_cvtpd_epi32", "immintrin/_mm256_cvtpd_ps", "immintrin/_mm256_cvtph_ps", "immintrin/_mm256_cvtps_epi32", "immintrin/_mm256_cvtps_pd", "immintrin/_mm256_cvtps_ph", "immintrin/_mm256_cvttpd_epi32", "immintrin/_mm256_cvttps_epi32", "immintrin/_mm256_div_pd", "immintrin/_mm256_div_ps", "immintrin/_mm256_dp_ps", "immintrin/_mm256_extractf128_pd", "immintrin/_mm256_extractf128_ps", "immintrin/_mm256_extractf128_si256", "immintrin/_mm256_extracti128_si256", "immintrin/_mm256_fmadd_pd", "immintrin/_mm256_fmadd_ps", "immintrin/_mm256_fmaddsub_pd", "immintrin/_mm256_fmaddsub_ps", "immintrin/_mm256_fmsub_pd", "immintrin/_mm256_fmsub_ps", "immintrin/_mm256_fmsubadd_pd", "immintrin/_mm256_fmsubadd_ps", "immintrin/_mm256_fnmadd_pd", "immintrin/_mm256_fnmadd_ps", "immintrin/_mm256_fnmsub_pd", "immintrin/_mm256_fnmsub_ps", "ammintrin/_mm256_frcz_pd", "ammintrin/_mm256_frcz_ps", "immintrin/_mm256_hadd_epi16", "immintrin/_mm256_hadd_epi32", "immintrin/_mm256_hadd_pd", "immintrin/_mm256_hadd_ps", "immintrin/_mm256_hadds_epi16", "immintrin/_mm256_hsub_epi16", "immintrin/_mm256_hsub_epi32", "immintrin/_mm256_hsub_pd", "immintrin/_mm256_hsub_ps", "immintrin/_mm256_hsubs_epi16", "immintrin/_mm256_i32gather_epi32", "immintrin/_mm256_i32gather_epi64", "immintrin/_mm256_i32gather_pd", "immintrin/_mm256_i32gather_ps", "immintrin/_mm256_i64gather_epi32", "immintrin/_mm256_i64gather_epi64", "immintrin/_mm256_i64gather_pd", "immintrin/_mm256_i64gather_ps", "immintrin/_mm256_insertf128_pd", "immintrin/_mm256_insertf128_ps", "immintrin/_mm256_insertf128_si256", "immintrin/_mm256_inserti128_si256", "immintrin/_mm256_lddqu_si256", "immintrin/_mm256_load_pd", "immintrin/_mm256_load_ps", "immintrin/_mm256_load_si256", "immintrin/_mm256_loadu_pd", "immintrin/_mm256_loadu_ps", "immintrin/_mm256_loadu_si256", "ammintrin/_mm256_macc_pd", "ammintrin/_mm256_macc_ps", "immintrin/_mm256_madd_epi16", "ammintrin/_mm256_maddsub_pd", "ammintrin/_mm256_maddsub_ps", "immintrin/_mm256_maddubs_epi16", "immintrin/_mm256_mask_i32gather_epi32", "immintrin/_mm256_mask_i32gather_epi64", "immintrin/_mm256_mask_i32gather_pd", "immintrin/_mm256_mask_i32gather_ps", "immintrin/_mm256_mask_i64gather_epi32", "immintrin/_mm256_mask_i64gather_epi64", "immintrin/_mm256_mask_i64gather_pd", "immintrin/_mm256_mask_i64gather_ps", "immintrin/_mm256_maskload_epi32", "immintrin/_mm256_maskload_epi64", "immintrin/_mm256_maskload_pd", "immintrin/_mm256_maskload_ps", "immintrin/_mm256_maskstore_epi32", "immintrin/_mm256_maskstore_epi64", "immintrin/_mm256_maskstore_pd", "immintrin/_mm256_maskstore_ps", "immintrin/_mm256_max_epi16", "immintrin/_mm256_max_epi32", "immintrin/_mm256_max_epi8", "immintrin/_mm256_max_epu16", "immintrin/_mm256_max_epu32", "immintrin/_mm256_max_epu8", "immintrin/_mm256_max_pd", "immintrin/_mm256_max_ps", "immintrin/_mm256_min_epi16", "immintrin/_mm256_min_epi32", "immintrin/_mm256_min_epi8", "immintrin/_mm256_min_epu16", "immintrin/_mm256_min_epu32", "immintrin/_mm256_min_epu8", "immintrin/_mm256_min_pd", "immintrin/_mm256_min_ps", "immintrin/_mm256_movedup_pd", "immintrin/_mm256_movehdup_ps", "immintrin/_mm256_moveldup_ps", "immintrin/_mm256_movemask_epi8", "immintrin/_mm256_movemask_pd", "immintrin/_mm256_movemask_ps", "immintrin/_mm256_mpsadbw_epu8", "ammintrin/_mm256_msub_pd", "ammintrin/_mm256_msub_ps", "ammintrin/_mm256_msubadd_pd", "ammintrin/_mm256_msubadd_ps", "immintrin/_mm256_mul_epi32", "immintrin/_mm256_mul_epu32", "immintrin/_mm256_mul_pd", "immintrin/_mm256_mul_ps", "immintrin/_mm256_mulhi_epi16", "immintrin/_mm256_mulhi_epu16", "immintrin/_mm256_mulhrs_epi16", "immintrin/_mm256_mullo_epi16", "immintrin/_mm256_mullo_epi32", "ammintrin/_mm256_nmacc_pd", "ammintrin/_mm256_nmacc_ps", "ammintrin/_mm256_nmsub_pd", "ammintrin/_mm256_nmsub_ps", "immintrin/_mm256_or_pd", "immintrin/_mm256_or_ps", "immintrin/_mm256_or_si256", "immintrin/_mm256_packs_epi16", "immintrin/_mm256_packs_epi32", "immintrin/_mm256_packus_epi16", "immintrin/_mm256_packus_epi32", "immintrin/_mm256_permute_pd", "immintrin/_mm256_permute_ps", "ammintrin/_mm256_permute2_pd", "ammintrin/_mm256_permute2_ps", "immintrin/_mm256_permute2f128_pd", "immintrin/_mm256_permute2f128_ps", "immintrin/_mm256_permute2f128_si256", "immintrin/_mm256_permute2x128_si256", "immintrin/_mm256_permute4x64_epi64", "immintrin/_mm256_permute4x64_pd", "immintrin/_mm256_permutevar_pd", "immintrin/_mm256_permutevar_ps", "immintrin/_mm256_permutevar8x32_epi32", "immintrin/_mm256_permutevar8x32_ps", "immintrin/_mm256_rcp_ps", "immintrin/_mm256_round_pd", "immintrin/_mm256_round_ps", "immintrin/_mm256_rsqrt_ps", "immintrin/_mm256_sad_epu8", "immintrin/_mm256_set_epi16", "immintrin/_mm256_set_epi32", "immintrin/_mm256_set_epi8", "immintrin/_mm256_set_pd", "immintrin/_mm256_set_ps", "immintrin/_mm256_set1_epi16", "immintrin/_mm256_set1_epi32", "immintrin/_mm256_set1_epi8", "immintrin/_mm256_set1_pd", "immintrin/_mm256_set1_ps", "immintrin/_mm256_setr_epi16", "immintrin/_mm256_setr_epi32", "immintrin/_mm256_setr_epi8", "immintrin/_mm256_setr_pd", "immintrin/_mm256_setr_ps", "immintrin/_mm256_setzero_pd", "immintrin/_mm256_setzero_ps", "immintrin/_mm256_setzero_si256", "immintrin/_mm256_shuffle_epi32", "immintrin/_mm256_shuffle_epi8", "immintrin/_mm256_shuffle_pd", "immintrin/_mm256_shuffle_ps", "immintrin/_mm256_shufflehi_epi16", "immintrin/_mm256_shufflelo_epi16", "immintrin/_mm256_sign_epi16", "immintrin/_mm256_sign_epi32", "immintrin/_mm256_sign_epi8", "immintrin/_mm256_sll_epi16", "immintrin/_mm256_sll_epi32", "immintrin/_mm256_sll_epi64", "immintrin/_mm256_slli_epi16", "immintrin/_mm256_slli_epi32", "immintrin/_mm256_slli_epi64", "immintrin/_mm256_slli_si256", "immintrin/_mm256_sllv_epi32", "immintrin/_mm256_sllv_epi64", "immintrin/_mm256_sqrt_pd", "immintrin/_mm256_sqrt_ps", "immintrin/_mm256_sra_epi16", "immintrin/_mm256_sra_epi32", "immintrin/_mm256_srai_epi16", "immintrin/_mm256_srai_epi32", "immintrin/_mm256_srav_epi32", "immintrin/_mm256_srl_epi16", "immintrin/_mm256_srl_epi32", "immintrin/_mm256_srl_epi64", "immintrin/_mm256_srli_epi16", "immintrin/_mm256_srli_epi32", "immintrin/_mm256_srli_epi64", "immintrin/_mm256_srli_si256", "immintrin/_mm256_srlv_epi32", "immintrin/_mm256_srlv_epi64", "immintrin/_mm256_store_pd", "immintrin/_mm256_store_ps", "immintrin/_mm256_store_si256", "immintrin/_mm256_storeu_pd", "immintrin/_mm256_storeu_ps", "immintrin/_mm256_storeu_si256", "immintrin/_mm256_stream_load_si256", "immintrin/_mm256_stream_pd", "immintrin/_mm256_stream_ps", "immintrin/_mm256_stream_si256", "immintrin/_mm256_sub_epi16", "immintrin/_mm256_sub_epi32", "immintrin/_mm256_sub_epi64", "immintrin/_mm256_sub_epi8", "immintrin/_mm256_sub_pd", "immintrin/_mm256_sub_ps", "immintrin/_mm256_subs_epi16", "immintrin/_mm256_subs_epi8", "immintrin/_mm256_subs_epu16", "immintrin/_mm256_subs_epu8", "immintrin/_mm256_testc_pd", "immintrin/_mm256_testc_ps", "immintrin/_mm256_testc_si256", "immintrin/_mm256_testnzc_pd", "immintrin/_mm256_testnzc_ps", "immintrin/_mm256_testnzc_si256", "immintrin/_mm256_testz_pd", "immintrin/_mm256_testz_ps", "immintrin/_mm256_testz_si256", "immintrin/_mm256_unpackhi_epi16", "immintrin/_mm256_unpackhi_epi32", "immintrin/_mm256_unpackhi_epi64", "immintrin/_mm256_unpackhi_epi8", "immintrin/_mm256_unpackhi_pd", "immintrin/_mm256_unpackhi_ps", "immintrin/_mm256_unpacklo_epi16", "immintrin/_mm256_unpacklo_epi32", "immintrin/_mm256_unpacklo_epi64", "immintrin/_mm256_unpacklo_epi8", "immintrin/_mm256_unpacklo_pd", "immintrin/_mm256_unpacklo_ps", "immintrin/_mm256_xor_pd", "immintrin/_mm256_xor_ps", "immintrin/_mm256_xor_si256", "immintrin/_mm256_zeroall", "immintrin/_mm256_zeroupper", "immintrin/_mulx_u32", "intrin/__nvreg_restore_fence", "intrin/__nvreg_save_fence", "immintrin/_pdep_u32", "immintrin/_pext_u32", "immintrin/_rdrand16_step", "immintrin/_rdrand32_step", "immintrin/_rdseed16_step", "immintrin/_rdseed32_step", "immintrin/_rorx_u32", "intrin/_rsm", "immintrin/_sarx_i32", "intrin/_sgdt", "immintrin/_shlx_u32", "immintrin/_shrx_u32", "ammintrin/__slwpcb", "intrin/_stac", "immintrin/_store_be_u16", "immintrin/_storebe_i16", "immintrin/_store_be_u32", "immintrin/_storebe_i32", "immintrin/_Store_HLERelease", "immintrin/_StorePointer_HLERelease", "intrin/_subborrow_u16", "intrin/_subborrow_u32", "intrin/_subborrow_u8", "ammintrin/_t1mskc_u32", "ammintrin/_tzcnt_u32", "ammintrin/_tzmsk_u32", "immintrin/_xabort", "immintrin/_xbegin", "immintrin/_xend", "immintrin/_xgetbv", "immintrin/_xrstor", "immintrin/_xsave", "immintrin/_xsaveopt", "immintrin/_xsetbv", "immintrin/_xtest", "XMMINTRIN/_m_maskmovq", "XMMINTRIN/_m_pavgb", "XMMINTRIN/_m_pavgw", "XMMINTRIN/_m_pextrw", "XMMINTRIN/_m_pinsrw", "XMMINTRIN/_m_pmaxsw", "XMMINTRIN/_m_pmaxub", "XMMINTRIN/_m_pminsw", "XMMINTRIN/_m_pminub", "XMMINTRIN/_m_pmovmskb", "XMMINTRIN/_m_pmulhuw", "XMMINTRIN/_m_psadbw", "XMMINTRIN/_m_pshufw", "XMMINTRIN/_mm_avg_pu16", "XMMINTRIN/_mm_avg_pu8", "XMMINTRIN/_mm_cvt_pi2ps", "XMMINTRIN/_mm_cvt_ps2pi", "XMMINTRIN/_mm_cvtpi32_ps", "XMMINTRIN/_mm_cvtps_pi32", "XMMINTRIN/_mm_cvtt_ps2pi", "XMMINTRIN/_mm_cvttps_pi32", "XMMINTRIN/_mm_extract_pi16", "XMMINTRIN/_mm_insert_pi16", "XMMINTRIN/_mm_maskmove_si64", "XMMINTRIN/_mm_max_pi16", "XMMINTRIN/_mm_max_pu8", "XMMINTRIN/_mm_min_pi16", "XMMINTRIN/_mm_min_pu8", "XMMINTRIN/_mm_movemask_pi8", "XMMINTRIN/_mm_mulhi_pu16", "XMMINTRIN/_mm_sad_pu8", "XMMINTRIN/_mm_shuffle_pi16", "XMMINTRIN/_mm_stream_pi"] +helpviewer_keywords: ["cl.exe compiler, intrinsics", "intrinsics, x86", "_addcarry_u16 x86 intrinsic", "_addcarry_u32 x86 intrinsic", "_addcarry_u8 x86 intrinsic", "_addcarryx_u32 x86 intrinsic", "_andn_u32 x86 intrinsic", "_bextr_u32 x86 intrinsic", "_bextri_u32 x86 intrinsic", "_blcfill_u32 x86 intrinsic", "_blci_u32 x86 intrinsic", "_blcic_u32 x86 intrinsic", "_blcmsk_u32 x86 intrinsic", "_blcs_u32 x86 intrinsic", "_blsfill_u32 x86 intrinsic", "_blsi_u32 x86 intrinsic", "_blsic_u32 x86 intrinsic", "_blsmsk_u32 x86 intrinsic", "_blsr_u32 x86 intrinsic", "_bzhi_u32 x86 intrinsic", "_castf32_u32 x64 intrinsic", "_castf64_u64 x64 intrinsic", "_castu32_f32 x64 intrinsic", "_castu64_f64 x64 intrinsic", "_clac x86 intrinsic", "_fxrstor x86 intrinsic", "_fxsave x86 intrinsic", "_invpcid x86 intrinsic", "_lgdt x86 intrinsic", "_load_be_u16 x86 intrinsic", "_loadbe_i16 x86 intrinsic", "_load_be_u32 x86 intrinsic", "_loadbe_i32 x86 intrinsic", "__llwpcb x86 intrinsic", "__lwpins32 x86 intrinsic", "__lwpval32 x86 intrinsic", "_lzcnt_u32 x86 intrinsic", "_m_empty x86 intrinsic", "_m_femms x86 intrinsic", "_m_from_float x86 intrinsic", "_m_from_int x86 intrinsic", "_m_maskmovq x86 intrinsic", "_m_packssdw x86 intrinsic", "_m_packsswb x86 intrinsic", "_m_packuswb x86 intrinsic", "_m_paddb x86 intrinsic", "_m_paddd x86 intrinsic", "_m_paddsb x86 intrinsic", "_m_paddsw x86 intrinsic", "_m_paddusb x86 intrinsic", "_m_paddusw x86 intrinsic", "_m_paddw x86 intrinsic", "_m_pand x86 intrinsic", "_m_pandn x86 intrinsic", "_m_pavgb x86 intrinsic", "_m_pavgusb x86 intrinsic", "_m_pavgw x86 intrinsic", "_m_pcmpeqb x86 intrinsic", "_m_pcmpeqd x86 intrinsic", "_m_pcmpeqw x86 intrinsic", "_m_pcmpgtb x86 intrinsic", "_m_pcmpgtd x86 intrinsic", "_m_pcmpgtw x86 intrinsic", "_m_pextrw x86 intrinsic", "_m_pf2id x86 intrinsic", "_m_pf2iw x86 intrinsic", "_m_pfacc x86 intrinsic", "_m_pfadd x86 intrinsic", "_m_pfcmpeq x86 intrinsic", "_m_pfcmpge x86 intrinsic", "_m_pfcmpgt x86 intrinsic", "_m_pfmax x86 intrinsic", "_m_pfmin x86 intrinsic", "_m_pfmul x86 intrinsic", "_m_pfnacc x86 intrinsic", "_m_pfpnacc x86 intrinsic", "_m_pfrcp x86 intrinsic", "_m_pfrcpit1 x86 intrinsic", "_m_pfrcpit2 x86 intrinsic", "_m_pfrsqit1 x86 intrinsic", "_m_pfrsqrt x86 intrinsic", "_m_pfsub x86 intrinsic", "_m_pfsubr x86 intrinsic", "_m_pi2fd x86 intrinsic", "_m_pi2fw x86 intrinsic", "_m_pinsrw x86 intrinsic", "_m_pmaddwd x86 intrinsic", "_m_pmaxsw x86 intrinsic", "_m_pmaxub x86 intrinsic", "_m_pminsw x86 intrinsic", "_m_pminub x86 intrinsic", "_m_pmovmskb x86 intrinsic", "_m_pmulhrw x86 intrinsic", "_m_pmulhuw x86 intrinsic", "_m_pmulhw x86 intrinsic", "_m_pmullw x86 intrinsic", "_m_por x86 intrinsic", "_m_prefetch x86 intrinsic", "_m_prefetchw x86 intrinsic", "_m_psadbw x86 intrinsic", "_m_pshufw x86 intrinsic", "_m_pslld x86 intrinsic", "_m_pslldi x86 intrinsic", "_m_psllq x86 intrinsic", "_m_psllqi x86 intrinsic", "_m_psllw x86 intrinsic", "_m_psllwi x86 intrinsic", "_m_psrad x86 intrinsic", "_m_psradi x86 intrinsic", "_m_psraw x86 intrinsic", "_m_psrawi x86 intrinsic", "_m_psrld x86 intrinsic", "_m_psrldi x86 intrinsic", "_m_psrlq x86 intrinsic", "_m_psrlqi x86 intrinsic", "_m_psrlw x86 intrinsic", "_m_psrlwi x86 intrinsic", "_m_psubb x86 intrinsic", "_m_psubd x86 intrinsic", "_m_psubsb x86 intrinsic", "_m_psubsw x86 intrinsic", "_m_psubusb x86 intrinsic", "_m_psubusw x86 intrinsic", "_m_psubw x86 intrinsic", "_m_pswapd x86 intrinsic", "_m_punpckhbw x86 intrinsic", "_m_punpckhdq x86 intrinsic", "_m_punpckhwd x86 intrinsic", "_m_punpcklbw x86 intrinsic", "_m_punpckldq x86 intrinsic", "_m_punpcklwd x86 intrinsic", "_m_pxor x86 intrinsic", "_m_to_float x86 intrinsic", "_m_to_int x86 intrinsic", "_mm_abs_epi16 x86 intrinsic", "_mm_abs_epi32 x86 intrinsic", "_mm_abs_epi8 x86 intrinsic", "_mm_abs_pi16 x86 intrinsic", "_mm_abs_pi32 x86 intrinsic", "_mm_abs_pi8 x86 intrinsic", "_mm_add_epi16 x86 intrinsic", "_mm_add_epi32 x86 intrinsic", "_mm_add_epi64 x86 intrinsic", "_mm_add_epi8 x86 intrinsic", "_mm_add_pd x86 intrinsic", "_mm_add_pi8 x86 intrinsic", "_mm_add_pi16 x86 intrinsic", "_mm_add_pi32 x86 intrinsic", "_mm_add_ps x86 intrinsic", "_mm_add_sd x86 intrinsic", "_mm_add_si64 x86 intrinsic", "_mm_add_ss x86 intrinsic", "_mm_adds_epi16 x86 intrinsic", "_mm_adds_epi8 x86 intrinsic", "_mm_adds_epu16 x86 intrinsic", "_mm_adds_epu8 x86 intrinsic", "_mm_adds_pi8 x86 intrinsic", "_mm_adds_pi16 x86 intrinsic", "_mm_adds_pu8 x86 intrinsic", "_mm_adds_pu16 x86 intrinsic", "_mm_addsub_pd x86 intrinsic", "_mm_addsub_ps x86 intrinsic", "_mm_aesdec_si128 x86 intrinsic", "_mm_aesdeclast_si128 x86 intrinsic", "_mm_aesenc_si128 x86 intrinsic", "_mm_aesenclast_si128 x86 intrinsic", "_mm_aesimc_si128 x86 intrinsic", "_mm_aeskeygenassist_si128 x86 intrinsic", "_mm_alignr_epi8 x86 intrinsic", "_mm_alignr_pi8 x86 intrinsic", "_mm_and_pd x86 intrinsic", "_mm_and_ps x86 intrinsic", "_mm_and_si64 x86 intrinsic", "_mm_and_si128 x86 intrinsic", "_mm_andnot_pd x86 intrinsic", "_mm_andnot_ps x86 intrinsic", "_mm_andnot_si64 x86 intrinsic", "_mm_andnot_si128 x86 intrinsic", "_mm_avg_epu16 x86 intrinsic", "_mm_avg_epu8 x86 intrinsic", "_mm_blend_epi16 x86 intrinsic", "_mm_blend_epi32 x86 intrinsic", "_mm_blend_pd x86 intrinsic", "_mm_blend_ps x86 intrinsic", "_mm_blendv_epi8 x86 intrinsic", "_mm_blendv_pd x86 intrinsic", "_mm_blendv_ps x86 intrinsic", "_mm_broadcast_ss x86 intrinsic", "_mm_broadcastb_epi8 x86 intrinsic", "_mm_broadcastd_epi32 x86 intrinsic", "_mm_broadcastq_epi64 x86 intrinsic", "_mm_broadcastsd_pd x86 intrinsic", "_mm_broadcastss_ps x86 intrinsic", "_mm_broadcastw_epi16 x86 intrinsic", "_mm_castpd_ps x86 intrinsic", "_mm_castpd_si128 x86 intrinsic", "_mm_castps_pd x86 intrinsic", "_mm_castps_si128 x86 intrinsic", "_mm_castsi128_pd x86 intrinsic", "_mm_castsi128_ps x86 intrinsic", "_mm_clflush x86 intrinsic", "_mm_clmulepi64_si128 x86 intrinsic", "_mm_cmov_si128 x86 intrinsic", "_mm_cmp_pd x86 intrinsic", "_mm_cmp_ps x86 intrinsic", "_mm_cmp_sd x86 intrinsic", "_mm_cmp_ss x86 intrinsic", "_mm_cmpeq_epi16 x86 intrinsic", "_mm_cmpeq_epi32 x86 intrinsic", "_mm_cmpeq_epi64 x86 intrinsic", "_mm_cmpeq_epi8 x86 intrinsic", "_mm_cmpeq_pd x86 intrinsic", "_mm_cmpeq_pi8 x86 intrinsic", "_mm_cmpeq_pi16 x86 intrinsic", "_mm_cmpeq_pi32 x86 intrinsic", "_mm_cmpeq_ps x86 intrinsic", "_mm_cmpeq_sd x86 intrinsic", "_mm_cmpeq_ss x86 intrinsic", "_mm_cmpestra x86 intrinsic", "_mm_cmpestrc x86 intrinsic", "_mm_cmpestri x86 intrinsic", "_mm_cmpestrm x86 intrinsic", "_mm_cmpestro x86 intrinsic", "_mm_cmpestrs x86 intrinsic", "_mm_cmpestrz x86 intrinsic", "_mm_cmpge_pd x86 intrinsic", "_mm_cmpge_ps x86 intrinsic", "_mm_cmpge_sd x86 intrinsic", "_mm_cmpge_ss x86 intrinsic", "_mm_cmpgt_epi16 x86 intrinsic", "_mm_cmpgt_epi32 x86 intrinsic", "_mm_cmpgt_epi64 x86 intrinsic", "_mm_cmpgt_epi8 x86 intrinsic", "_mm_cmpgt_pi8 x86 intrinsic", "_mm_cmpgt_pi16 x86 intrinsic", "_mm_cmpgt_pi32 x86 intrinsic", "_mm_cmpgt_pd x86 intrinsic", "_mm_cmpgt_ps x86 intrinsic", "_mm_cmpgt_sd x86 intrinsic", "_mm_cmpgt_ss x86 intrinsic", "_mm_cmpistra x86 intrinsic", "_mm_cmpistrc x86 intrinsic", "_mm_cmpistri x86 intrinsic", "_mm_cmpistrm x86 intrinsic", "_mm_cmpistro x86 intrinsic", "_mm_cmpistrs x86 intrinsic", "_mm_cmpistrz x86 intrinsic", "_mm_cmple_pd x86 intrinsic", "_mm_cmple_ps x86 intrinsic", "_mm_cmple_sd x86 intrinsic", "_mm_cmple_ss x86 intrinsic", "_mm_cmplt_epi16 x86 intrinsic", "_mm_cmplt_epi32 x86 intrinsic", "_mm_cmplt_epi8 x86 intrinsic", "_mm_cmplt_pd x86 intrinsic", "_mm_cmplt_ps x86 intrinsic", "_mm_cmplt_sd x86 intrinsic", "_mm_cmplt_ss x86 intrinsic", "_mm_cmpneq_pd x86 intrinsic", "_mm_cmpneq_ps x86 intrinsic", "_mm_cmpneq_sd x86 intrinsic", "_mm_cmpneq_ss x86 intrinsic", "_mm_cmpnge_pd x86 intrinsic", "_mm_cmpnge_ps x86 intrinsic", "_mm_cmpnge_sd x86 intrinsic", "_mm_cmpnge_ss x86 intrinsic", "_mm_cmpngt_pd x86 intrinsic", "_mm_cmpngt_ps x86 intrinsic", "_mm_cmpngt_sd x86 intrinsic", "_mm_cmpngt_ss x86 intrinsic", "_mm_cmpnle_pd x86 intrinsic", "_mm_cmpnle_ps x86 intrinsic", "_mm_cmpnle_sd x86 intrinsic", "_mm_cmpnle_ss x86 intrinsic", "_mm_cmpnlt_pd x86 intrinsic", "_mm_cmpnlt_ps x86 intrinsic", "_mm_cmpnlt_sd x86 intrinsic", "_mm_cmpnlt_ss x86 intrinsic", "_mm_cmpord_pd x86 intrinsic", "_mm_cmpord_ps x86 intrinsic", "_mm_cmpord_sd x86 intrinsic", "_mm_cmpord_ss x86 intrinsic", "_mm_cmpunord_pd x86 intrinsic", "_mm_cmpunord_ps x86 intrinsic", "_mm_cmpunord_sd x86 intrinsic", "_mm_cmpunord_ss x86 intrinsic", "_mm_com_epi16 x86 intrinsic", "_mm_com_epi32 x86 intrinsic", "_mm_com_epi64 x86 intrinsic", "_mm_com_epi8 x86 intrinsic", "_mm_com_epu16 x86 intrinsic", "_mm_com_epu32 x86 intrinsic", "_mm_com_epu64 x86 intrinsic", "_mm_com_epu8 x86 intrinsic", "_mm_comieq_sd x86 intrinsic", "_mm_comieq_ss x86 intrinsic", "_mm_comige_sd x86 intrinsic", "_mm_comige_ss x86 intrinsic", "_mm_comigt_sd x86 intrinsic", "_mm_comigt_ss x86 intrinsic", "_mm_comile_sd x86 intrinsic", "_mm_comile_ss x86 intrinsic", "_mm_comilt_sd x86 intrinsic", "_mm_comilt_ss x86 intrinsic", "_mm_comineq_sd x86 intrinsic", "_mm_comineq_ss x86 intrinsic", "_mm_crc32_u16 x86 intrinsic", "_mm_crc32_u32 x86 intrinsic", "_mm_crc32_u8 x86 intrinsic", "_mm_cvt_pi2ps x86 intrinsic", "_mm_cvt_ps2pi x86 intrinsic", "_mm_cvt_si2ss x86 intrinsic", "_mm_cvt_ss2si x86 intrinsic", "_mm_cvtepi16_epi32 x86 intrinsic", "_mm_cvtepi16_epi64 x86 intrinsic", "_mm_cvtepi32_epi64 x86 intrinsic", "_mm_cvtepi32_pd x86 intrinsic", "_mm_cvtepi32_ps x86 intrinsic", "_mm_cvtepi8_epi16 x86 intrinsic", "_mm_cvtepi8_epi32 x86 intrinsic", "_mm_cvtepi8_epi64 x86 intrinsic", "_mm_cvtepu16_epi32 x86 intrinsic", "_mm_cvtepu16_epi64 x86 intrinsic", "_mm_cvtepu32_epi64 x86 intrinsic", "_mm_cvtepu8_epi16 x86 intrinsic", "_mm_cvtepu8_epi32 x86 intrinsic", "_mm_cvtepu8_epi64 x86 intrinsic", "_mm_cvtpd_epi32 x86 intrinsic", "_mm_cvtpd_pi32 x86 intrinsic", "_mm_cvtpd_ps x86 intrinsic", "_mm_cvtph_ps x86 intrinsic", "_mm_cvtpi32_pd x86 intrinsic", "_mm_cvtps_epi32 x86 intrinsic", "_mm_cvtps_pd x86 intrinsic", "_mm_cvtps_ph x86 intrinsic", "_mm_cvtsd_f64 x86 intrinsic", "_mm_cvtsd_si32 x86 intrinsic", "_mm_cvtsd_ss x86 intrinsic", "_mm_cvtsi128_si32 x86 intrinsic", "_mm_cvtsi32_sd x86 intrinsic", "_mm_cvtsi32_si128 x86 intrinsic", "_mm_cvtsi32_si64 x86 intrinsic", "_mm_cvtsi64_si32 x86 intrinsic", "_mm_cvtss_f32 x86 intrinsic", "_mm_cvtss_sd x86 intrinsic", "_mm_cvtt_ps2pi x86 intrinsic", "_mm_cvtt_ss2si x86 intrinsic", "_mm_cvttpd_epi32 x86 intrinsic", "_mm_cvttpd_pi32 x86 intrinsic", "_mm_cvttps_epi32 x86 intrinsic", "_mm_cvttsd_si32 x86 intrinsic", "_mm_div_pd x86 intrinsic", "_mm_div_ps x86 intrinsic", "_mm_div_sd x86 intrinsic", "_mm_div_ss x86 intrinsic", "_mm_dp_pd x86 intrinsic", "_mm_dp_ps x86 intrinsic", "_mm_empty x86 intrinsic", "_mm_extract_epi16 x86 intrinsic", "_mm_extract_epi32 x86 intrinsic", "_mm_extract_epi8 x86 intrinsic", "_mm_extract_ps x86 intrinsic", "_mm_fmadd_pd x86 intrinsic", "_mm_fmadd_ps x86 intrinsic", "_mm_fmadd_sd x86 intrinsic", "_mm_fmadd_ss x86 intrinsic", "_mm_fmaddsub_pd x86 intrinsic", "_mm_fmaddsub_ps x86 intrinsic", "_mm_fmsub_pd x86 intrinsic", "_mm_fmsub_ps x86 intrinsic", "_mm_fmsub_sd x86 intrinsic", "_mm_fmsub_ss x86 intrinsic", "_mm_fmsubadd_pd x86 intrinsic", "_mm_fmsubadd_ps x86 intrinsic", "_mm_fnmadd_pd x86 intrinsic", "_mm_fnmadd_ps x86 intrinsic", "_mm_fnmadd_sd x86 intrinsic", "_mm_fnmadd_ss x86 intrinsic", "_mm_fnmsub_pd x86 intrinsic", "_mm_fnmsub_ps x86 intrinsic", "_mm_fnmsub_sd x86 intrinsic", "_mm_fnmsub_ss x86 intrinsic", "_mm_frcz_pd x86 intrinsic", "_mm_frcz_ps x86 intrinsic", "_mm_frcz_sd x86 intrinsic", "_mm_frcz_ss x86 intrinsic", "_mm_getcsr x86 intrinsic", "_mm_hadd_epi16 x86 intrinsic", "_mm_hadd_epi32 x86 intrinsic", "_mm_hadd_pd x86 intrinsic", "_mm_hadd_pi16 x86 intrinsic", "_mm_hadd_pi32 x86 intrinsic", "_mm_hadd_ps x86 intrinsic", "_mm_haddd_epi16 x86 intrinsic", "_mm_haddd_epi8 x86 intrinsic", "_mm_haddd_epu16 x86 intrinsic", "_mm_haddd_epu8 x86 intrinsic", "_mm_haddq_epi16 x86 intrinsic", "_mm_haddq_epi32 x86 intrinsic", "_mm_haddq_epi8 x86 intrinsic", "_mm_haddq_epu16 x86 intrinsic", "_mm_haddq_epu32 x86 intrinsic", "_mm_haddq_epu8 x86 intrinsic", "_mm_hadds_epi16 x86 intrinsic", "_mm_hadds_pi16 x86 intrinsic", "_mm_haddw_epi8 x86 intrinsic", "_mm_haddw_epu8 x86 intrinsic", "_mm_hsub_epi16 x86 intrinsic", "_mm_hsub_epi32 x86 intrinsic", "_mm_hsub_pd x86 intrinsic", "_mm_hsub_pi16 x86 intrinsic", "_mm_hsub_pi32 x86 intrinsic", "_mm_hsub_ps x86 intrinsic", "_mm_hsubd_epi16 x86 intrinsic", "_mm_hsubq_epi32 x86 intrinsic", "_mm_hsubs_epi16 x86 intrinsic", "_mm_hsubs_pi16 x86 intrinsic", "_mm_hsubw_epi8 x86 intrinsic", "_mm_i32gather_epi32 x86 intrinsic", "_mm_i32gather_epi64 x86 intrinsic", "_mm_i32gather_pd x86 intrinsic", "_mm_i32gather_ps x86 intrinsic", "_mm_i64gather_epi32 x86 intrinsic", "_mm_i64gather_epi64 x86 intrinsic", "_mm_i64gather_pd x86 intrinsic", "_mm_i64gather_ps x86 intrinsic", "_mm_insert_epi16 x86 intrinsic", "_mm_insert_epi32 x86 intrinsic", "_mm_insert_epi8 x86 intrinsic", "_mm_insert_ps x86 intrinsic", "_mm_lddqu_si128 x86 intrinsic", "_mm_lfence x86 intrinsic", "_mm_load_pd x86 intrinsic", "_mm_load_ps x86 intrinsic", "_mm_load_ps1 x86 intrinsic", "_mm_load_sd x86 intrinsic", "_mm_load_si128 x86 intrinsic", "_mm_load_ss x86 intrinsic", "_mm_load1_pd x86 intrinsic", "_mm_loaddup_pd x86 intrinsic", "_mm_loadh_pd x86 intrinsic", "_mm_loadh_pi x86 intrinsic", "_mm_loadl_epi64 x86 intrinsic", "_mm_loadl_pd x86 intrinsic", "_mm_loadl_pi x86 intrinsic", "_mm_loadr_pd x86 intrinsic", "_mm_loadr_ps x86 intrinsic", "_mm_loadu_pd x86 intrinsic", "_mm_loadu_ps x86 intrinsic", "_mm_loadu_si128 x86 intrinsic", "_mm_macc_epi16 x86 intrinsic", "_mm_macc_epi32 x86 intrinsic", "_mm_macc_pd x86 intrinsic", "_mm_macc_ps x86 intrinsic", "_mm_macc_sd x86 intrinsic", "_mm_macc_ss x86 intrinsic", "_mm_maccd_epi16 x86 intrinsic", "_mm_macchi_epi32 x86 intrinsic", "_mm_macclo_epi32 x86 intrinsic", "_mm_maccs_epi16 x86 intrinsic", "_mm_maccs_epi32 x86 intrinsic", "_mm_maccsd_epi16 x86 intrinsic", "_mm_maccshi_epi32 x86 intrinsic", "_mm_maccslo_epi32 x86 intrinsic", "_mm_madd_epi16 x86 intrinsic", "_mm_madd_pi16 x86 intrinsic", "_mm_maddd_epi16 x86 intrinsic", "_mm_maddsd_epi16 x86 intrinsic", "_mm_maddsub_pd x86 intrinsic", "_mm_maddsub_ps x86 intrinsic", "_mm_maddubs_epi16 x86 intrinsic", "_mm_maddubs_pi16 x86 intrinsic", "_mm_mask_i32gather_epi32 x86 intrinsic", "_mm_mask_i32gather_epi64 x86 intrinsic", "_mm_mask_i32gather_pd x86 intrinsic", "_mm_mask_i32gather_ps x86 intrinsic", "_mm_mask_i64gather_epi32 x86 intrinsic", "_mm_mask_i64gather_epi64 x86 intrinsic", "_mm_mask_i64gather_pd x86 intrinsic", "_mm_mask_i64gather_ps x86 intrinsic", "_mm_maskload_epi32 x86 intrinsic", "_mm_maskload_epi64 x86 intrinsic", "_mm_maskload_pd x86 intrinsic", "_mm_maskload_ps x86 intrinsic", "_mm_maskmoveu_si128 x86 intrinsic", "_mm_maskstore_epi32 x86 intrinsic", "_mm_maskstore_epi64 x86 intrinsic", "_mm_maskstore_pd x86 intrinsic", "_mm_maskstore_ps x86 intrinsic", "_mm_max_epi16 x86 intrinsic", "_mm_max_epi32 x86 intrinsic", "_mm_max_epi8 x86 intrinsic", "_mm_max_epu16 x86 intrinsic", "_mm_max_epu32 x86 intrinsic", "_mm_max_epu8 x86 intrinsic", "_mm_max_pd x86 intrinsic", "_mm_max_ps x86 intrinsic", "_mm_max_sd x86 intrinsic", "_mm_max_ss x86 intrinsic", "_mm_mfence x86 intrinsic", "_mm_min_epi16 x86 intrinsic", "_mm_min_epi32 x86 intrinsic", "_mm_min_epi8 x86 intrinsic", "_mm_min_epu16 x86 intrinsic", "_mm_min_epu32 x86 intrinsic", "_mm_min_epu8 x86 intrinsic", "_mm_min_pd x86 intrinsic", "_mm_min_ps x86 intrinsic", "_mm_min_sd x86 intrinsic", "_mm_min_ss x86 intrinsic", "_mm_minpos_epu16 x86 intrinsic", "_mm_monitor x86 intrinsic", "_mm_move_epi64 x86 intrinsic", "_mm_move_sd x86 intrinsic", "_mm_move_ss x86 intrinsic", "_mm_movedup_pd x86 intrinsic", "_mm_movehdup_ps x86 intrinsic", "_mm_movehl_ps x86 intrinsic", "_mm_moveldup_ps x86 intrinsic", "_mm_movelh_ps x86 intrinsic", "_mm_movemask_epi8 x86 intrinsic", "_mm_movemask_pd x86 intrinsic", "_mm_movemask_ps x86 intrinsic", "_mm_movepi64_pi64 x86 intrinsic", "_mm_movpi64_epi64 x86 intrinsic", "_mm_mpsadbw_epu8 x86 intrinsic", "_mm_msub_pd x86 intrinsic", "_mm_msub_ps x86 intrinsic", "_mm_msub_sd x86 intrinsic", "_mm_msub_ss x86 intrinsic", "_mm_msubadd_pd x86 intrinsic", "_mm_msubadd_ps x86 intrinsic", "_mm_mul_epi32 x86 intrinsic", "_mm_mul_epu32 x86 intrinsic", "_mm_mul_pd x86 intrinsic", "_mm_mul_ps x86 intrinsic", "_mm_mul_sd x86 intrinsic", "_mm_mul_ss x86 intrinsic", "_mm_mul_su32 x86 intrinsic", "_mm_mulhi_epi16 x86 intrinsic", "_mm_mulhi_epu16 x86 intrinsic", "_mm_mulhi_pi16 x86 intrinsic", "_mm_mulhrs_epi16 x86 intrinsic", "_mm_mulhrs_pi16 x86 intrinsic", "_mm_mullo_epi16 x86 intrinsic", "_mm_mullo_epi32 x86 intrinsic", "_mm_mullo_pi16 x86 intrinsic", "_mm_mwait x86 intrinsic", "_mm_nmacc_pd x86 intrinsic", "_mm_nmacc_ps x86 intrinsic", "_mm_nmacc_sd x86 intrinsic", "_mm_nmacc_ss x86 intrinsic", "_mm_nmsub_pd x86 intrinsic", "_mm_nmsub_ps x86 intrinsic", "_mm_nmsub_sd x86 intrinsic", "_mm_nmsub_ss x86 intrinsic", "_mm_or_pd x86 intrinsic", "_mm_or_ps x86 intrinsic", "_mm_or_si64 x86 intrinsic", "_mm_or_si128 x86 intrinsic", "_mm_packs_epi16 x86 intrinsic", "_mm_packs_epi32 x86 intrinsic", "_mm_packs_pi16 x86 intrinsic", "_mm_packs_pi32 x86 intrinsic", "_mm_packs_pu16 x86 intrinsic", "_mm_packus_epi16 x86 intrinsic", "_mm_packus_epi32 x86 intrinsic", "_mm_pause x86 intrinsic", "_mm_perm_epi8 x86 intrinsic", "_mm_permute_pd x86 intrinsic", "_mm_permute_ps x86 intrinsic", "_mm_permute2_pd x86 intrinsic", "_mm_permute2_ps x86 intrinsic", "_mm_permutevar_pd x86 intrinsic", "_mm_permutevar_ps x86 intrinsic", "_mm_popcnt_u32 x86 intrinsic", "_mm_prefetch x86 intrinsic", "_mm_rcp_ps x86 intrinsic", "_mm_rcp_ss x86 intrinsic", "_mm_rot_epi16 x86 intrinsic", "_mm_rot_epi32 x86 intrinsic", "_mm_rot_epi64 x86 intrinsic", "_mm_rot_epi8 x86 intrinsic", "_mm_roti_epi16 x86 intrinsic", "_mm_roti_epi32 x86 intrinsic", "_mm_roti_epi64 x86 intrinsic", "_mm_roti_epi8 x86 intrinsic", "_mm_round_pd x86 intrinsic", "_mm_round_ps x86 intrinsic", "_mm_round_sd x86 intrinsic", "_mm_round_ss x86 intrinsic", "_mm_rsqrt_ps x86 intrinsic", "_mm_rsqrt_ss x86 intrinsic", "_mm_sad_epu8 x86 intrinsic", "_mm_set_epi16 x86 intrinsic", "_mm_set_epi32 x86 intrinsic", "_mm_set_epi64 x86 intrinsic", "_mm_set_epi8 x86 intrinsic", "_mm_set_pd x86 intrinsic", "_mm_set_pi16 x86 intrinsic", "_mm_set_pi32 x86 intrinsic", "_mm_set_pi8 x86 intrinsic", "_mm_set_ps x86 intrinsic", "_mm_set_ps1 x86 intrinsic", "_mm_set_sd x86 intrinsic", "_mm_set_ss x86 intrinsic", "_mm_set1_epi16 x86 intrinsic", "_mm_set1_epi32 x86 intrinsic", "_mm_set1_epi64 x86 intrinsic", "_mm_set1_epi8 x86 intrinsic", "_mm_set1_pd x86 intrinsic", "_mm_set1_pi16 x86 intrinsic", "_mm_set1_pi32 x86 intrinsic", "_mm_set1_pi8 x86 intrinsic", "_mm_setcsr x86 intrinsic", "_mm_setl_epi64 x86 intrinsic", "_mm_setr_epi16 x86 intrinsic", "_mm_setr_epi32 x86 intrinsic", "_mm_setr_epi64 x86 intrinsic", "_mm_setr_epi8 x86 intrinsic", "_mm_setr_pd x86 intrinsic", "_mm_setr_pi16 x86 intrinsic", "_mm_setr_pi32 x86 intrinsic", "_mm_setr_pi8 x86 intrinsic", "_mm_setr_ps x86 intrinsic", "_mm_setzero_pd x86 intrinsic", "_mm_setzero_ps x86 intrinsic", "_mm_setzero_si128 x86 intrinsic", "_mm_setzero_si64 x86 intrinsic", "_mm_sfence x86 intrinsic", "_mm_sha_epi16 x86 intrinsic", "_mm_sha_epi32 x86 intrinsic", "_mm_sha_epi64 x86 intrinsic", "_mm_sha_epi8 x86 intrinsic", "_mm_shl_epi16 x86 intrinsic", "_mm_shl_epi32 x86 intrinsic", "_mm_shl_epi64 x86 intrinsic", "_mm_shl_epi8 x86 intrinsic", "_mm_shuffle_epi32 x86 intrinsic", "_mm_shuffle_epi8 x86 intrinsic", "_mm_shuffle_pd x86 intrinsic", "_mm_shuffle_pi8 x86 intrinsic", "_mm_shuffle_ps x86 intrinsic", "_mm_shufflehi_epi16 x86 intrinsic", "_mm_shufflelo_epi16 x86 intrinsic", "_mm_sign_epi16 x86 intrinsic", "_mm_sign_epi32 x86 intrinsic", "_mm_sign_epi8 x86 intrinsic", "_mm_sign_pi16 x86 intrinsic", "_mm_sign_pi32 x86 intrinsic", "_mm_sign_pi8 x86 intrinsic", "_mm_sll_epi16 x86 intrinsic", "_mm_sll_epi32 x86 intrinsic", "_mm_sll_epi64 x86 intrinsic", "_mm_sll_pi16 x86 intrinsic", "_mm_sll_pi32 x86 intrinsic", "_mm_sll_si64 x86 intrinsic", "_mm_slli_epi16 x86 intrinsic", "_mm_slli_epi32 x86 intrinsic", "_mm_slli_epi64 x86 intrinsic", "_mm_slli_pi16 x86 intrinsic", "_mm_slli_pi32 x86 intrinsic", "_mm_slli_si64 x86 intrinsic", "_mm_slli_si128 x86 intrinsic", "_mm_sllv_epi32 x86 intrinsic", "_mm_sllv_epi64 x86 intrinsic", "_mm_sqrt_pd x86 intrinsic", "_mm_sqrt_ps x86 intrinsic", "_mm_sqrt_sd x86 intrinsic", "_mm_sqrt_ss x86 intrinsic", "_mm_sra_epi16 x86 intrinsic", "_mm_sra_epi32 x86 intrinsic", "_mm_sra_pi16 x86 intrinsic", "_mm_sra_pi32 x86 intrinsic", "_mm_srai_epi16 x86 intrinsic", "_mm_srai_epi32 x86 intrinsic", "_mm_srai_pi16 x86 intrinsic", "_mm_srai_pi32 x86 intrinsic", "_mm_srav_epi32 x86 intrinsic", "_mm_srl_epi16 x86 intrinsic", "_mm_srl_epi32 x86 intrinsic", "_mm_srl_epi64 x86 intrinsic", "_mm_srl_pi16 x86 intrinsic", "_mm_srl_pi32 x86 intrinsic", "_mm_srl_si64 x86 intrinsic", "_mm_srli_epi16 x86 intrinsic", "_mm_srli_epi32 x86 intrinsic", "_mm_srli_epi64 x86 intrinsic", "_mm_srli_pi16 x86 intrinsic", "_mm_srli_pi32 x86 intrinsic", "_mm_srli_si64 x86 intrinsic", "_mm_srli_si128 x86 intrinsic", "_mm_srlv_epi32 x86 intrinsic", "_mm_srlv_epi64 x86 intrinsic", "_mm_store_pd x86 intrinsic", "_mm_store_ps x86 intrinsic", "_mm_store_ps1 x86 intrinsic", "_mm_store_sd x86 intrinsic", "_mm_store_si128 x86 intrinsic", "_mm_store_ss x86 intrinsic", "_mm_store1_pd x86 intrinsic", "_mm_storeh_pd x86 intrinsic", "_mm_storeh_pi x86 intrinsic", "_mm_storel_epi64 x86 intrinsic", "_mm_storel_pd x86 intrinsic", "_mm_storel_pi x86 intrinsic", "_mm_storer_pd x86 intrinsic", "_mm_storer_ps x86 intrinsic", "_mm_storeu_pd x86 intrinsic", "_mm_storeu_ps x86 intrinsic", "_mm_storeu_si128 x86 intrinsic", "_mm_stream_load_si128 x86 intrinsic", "_mm_stream_pd x86 intrinsic", "_mm_stream_pi x86 intrinsic", "_mm_stream_ps x86 intrinsic", "_mm_stream_si128 x86 intrinsic", "_mm_stream_si32 x86 intrinsic", "_mm_sub_epi16 x86 intrinsic", "_mm_sub_epi32 x86 intrinsic", "_mm_sub_epi64 x86 intrinsic", "_mm_sub_epi8 x86 intrinsic", "_mm_sub_pd x86 intrinsic", "_mm_sub_pi8 x86 intrinsic", "_mm_sub_pi16 x86 intrinsic", "_mm_sub_pi32 x86 intrinsic", "_mm_sub_ps x86 intrinsic", "_mm_sub_sd x86 intrinsic", "_mm_sub_si64 x86 intrinsic", "_mm_sub_ss x86 intrinsic", "_mm_subs_epi16 x86 intrinsic", "_mm_subs_epi8 x86 intrinsic", "_mm_subs_epu16 x86 intrinsic", "_mm_subs_epu8 x86 intrinsic", "_mm_subs_pi8 x86 intrinsic", "_mm_subs_pi16 x86 intrinsic", "_mm_subs_pu8 x86 intrinsic", "_mm_subs_pu16 x86 intrinsic", "_mm_testc_pd x86 intrinsic", "_mm_testc_ps x86 intrinsic", "_mm_testc_si128 x86 intrinsic", "_mm_testnzc_pd x86 intrinsic", "_mm_testnzc_ps x86 intrinsic", "_mm_testnzc_si128 x86 intrinsic", "_mm_testz_pd x86 intrinsic", "_mm_testz_ps x86 intrinsic", "_mm_testz_si128 x86 intrinsic", "_mm_ucomieq_sd x86 intrinsic", "_mm_ucomieq_ss x86 intrinsic", "_mm_ucomige_sd x86 intrinsic", "_mm_ucomige_ss x86 intrinsic", "_mm_ucomigt_sd x86 intrinsic", "_mm_ucomigt_ss x86 intrinsic", "_mm_ucomile_sd x86 intrinsic", "_mm_ucomile_ss x86 intrinsic", "_mm_ucomilt_sd x86 intrinsic", "_mm_ucomilt_ss x86 intrinsic", "_mm_ucomineq_sd x86 intrinsic", "_mm_ucomineq_ss x86 intrinsic", "_mm_unpackhi_epi16 x86 intrinsic", "_mm_unpackhi_epi32 x86 intrinsic", "_mm_unpackhi_epi64 x86 intrinsic", "_mm_unpackhi_epi8 x86 intrinsic", "_mm_unpackhi_pd x86 intrinsic", "_mm_unpackhi_pi8 x86 intrinsic", "_mm_unpackhi_pi16 x86 intrinsic", "_mm_unpackhi_pi32 x86 intrinsic", "_mm_unpackhi_ps x86 intrinsic", "_mm_unpacklo_epi16 x86 intrinsic", "_mm_unpacklo_epi32 x86 intrinsic", "_mm_unpacklo_epi64 x86 intrinsic", "_mm_unpacklo_epi8 x86 intrinsic", "_mm_unpacklo_pd x86 intrinsic", "_mm_unpacklo_pi8 x86 intrinsic", "_mm_unpacklo_pi16 x86 intrinsic", "_mm_unpacklo_pi32 x86 intrinsic", "_mm_unpacklo_ps x86 intrinsic", "_mm_xor_pd x86 intrinsic", "_mm_xor_ps x86 intrinsic", "_mm_xor_si64 x86 intrinsic", "_mm_xor_si128 x86 intrinsic", "_mm256_abs_epi16 x86 intrinsic", "_mm256_abs_epi32 x86 intrinsic", "_mm256_abs_epi8 x86 intrinsic", "_mm256_add_epi16 x86 intrinsic", "_mm256_add_epi32 x86 intrinsic", "_mm256_add_epi64 x86 intrinsic", "_mm256_add_epi8 x86 intrinsic", "_mm256_add_pd x86 intrinsic", "_mm256_add_ps x86 intrinsic", "_mm256_adds_epi16 x86 intrinsic", "_mm256_adds_epi8 x86 intrinsic", "_mm256_adds_epu16 x86 intrinsic", "_mm256_adds_epu8 x86 intrinsic", "_mm256_addsub_pd x86 intrinsic", "_mm256_addsub_ps x86 intrinsic", "_mm256_alignr_epi8 x86 intrinsic", "_mm256_and_pd x86 intrinsic", "_mm256_and_ps x86 intrinsic", "_mm256_and_si256 x86 intrinsic", "_mm256_andnot_pd x86 intrinsic", "_mm256_andnot_ps x86 intrinsic", "_mm256_andnot_si256 x86 intrinsic", "_mm256_avg_epu16 x86 intrinsic", "_mm256_avg_epu8 x86 intrinsic", "_mm256_blend_epi16 x86 intrinsic", "_mm256_blend_epi32 x86 intrinsic", "_mm256_blend_pd x86 intrinsic", "_mm256_blend_ps x86 intrinsic", "_mm256_blendv_epi8 x86 intrinsic", "_mm256_blendv_pd x86 intrinsic", "_mm256_blendv_ps x86 intrinsic", "_mm256_broadcast_pd x86 intrinsic", "_mm256_broadcast_ps x86 intrinsic", "_mm256_broadcast_sd x86 intrinsic", "_mm256_broadcast_ss x86 intrinsic", "_mm256_broadcastb_epi8 x86 intrinsic", "_mm256_broadcastd_epi32 x86 intrinsic", "_mm256_broadcastq_epi64 x86 intrinsic", "_mm256_broadcastsd_pd x86 intrinsic", "_mm256_broadcastsi128_si256 x86 intrinsic", "_mm256_broadcastss_ps x86 intrinsic", "_mm256_broadcastw_epi16 x86 intrinsic", "_mm256_castpd_ps x86 intrinsic", "_mm256_castpd_si256 x86 intrinsic", "_mm256_castpd128_pd256 x86 intrinsic", "_mm256_castpd256_pd128 x86 intrinsic", "_mm256_castps_pd x86 intrinsic", "_mm256_castps_si256 x86 intrinsic", "_mm256_castps128_ps256 x86 intrinsic", "_mm256_castps256_ps128 x86 intrinsic", "_mm256_castsi128_si256 x86 intrinsic", "_mm256_castsi256_pd x86 intrinsic", "_mm256_castsi256_ps x86 intrinsic", "_mm256_castsi256_si128 x86 intrinsic", "_mm256_cmov_si256 x86 intrinsic", "_mm256_cmp_pd x86 intrinsic", "_mm256_cmp_ps x86 intrinsic", "_mm256_cmpeq_epi16 x86 intrinsic", "_mm256_cmpeq_epi32 x86 intrinsic", "_mm256_cmpeq_epi64 x86 intrinsic", "_mm256_cmpeq_epi8 x86 intrinsic", "_mm256_cmpgt_epi16 x86 intrinsic", "_mm256_cmpgt_epi32 x86 intrinsic", "_mm256_cmpgt_epi64 x86 intrinsic", "_mm256_cmpgt_epi8 x86 intrinsic", "_mm256_cvtepi16_epi32 x86 intrinsic", "_mm256_cvtepi16_epi64 x86 intrinsic", "_mm256_cvtepi32_epi64 x86 intrinsic", "_mm256_cvtepi32_pd x86 intrinsic", "_mm256_cvtepi32_ps x86 intrinsic", "_mm256_cvtepi8_epi16 x86 intrinsic", "_mm256_cvtepi8_epi32 x86 intrinsic", "_mm256_cvtepi8_epi64 x86 intrinsic", "_mm256_cvtepu16_epi32 x86 intrinsic", "_mm256_cvtepu16_epi64 x86 intrinsic", "_mm256_cvtepu32_epi64 x86 intrinsic", "_mm256_cvtepu8_epi16 x86 intrinsic", "_mm256_cvtepu8_epi32 x86 intrinsic", "_mm256_cvtepu8_epi64 x86 intrinsic", "_mm256_cvtpd_epi32 x86 intrinsic", "_mm256_cvtpd_ps x86 intrinsic", "_mm256_cvtph_ps x86 intrinsic", "_mm256_cvtps_epi32 x86 intrinsic", "_mm256_cvtps_pd x86 intrinsic", "_mm256_cvtps_ph x86 intrinsic", "_mm256_cvttpd_epi32 x86 intrinsic", "_mm256_cvttps_epi32 x86 intrinsic", "_mm256_div_pd x86 intrinsic", "_mm256_div_ps x86 intrinsic", "_mm256_dp_ps x86 intrinsic", "_mm256_extractf128_pd x86 intrinsic", "_mm256_extractf128_ps x86 intrinsic", "_mm256_extractf128_si256 x86 intrinsic", "_mm256_extracti128_si256 x86 intrinsic", "_mm256_fmadd_pd x86 intrinsic", "_mm256_fmadd_ps x86 intrinsic", "_mm256_fmaddsub_pd x86 intrinsic", "_mm256_fmaddsub_ps x86 intrinsic", "_mm256_fmsub_pd x86 intrinsic", "_mm256_fmsub_ps x86 intrinsic", "_mm256_fmsubadd_pd x86 intrinsic", "_mm256_fmsubadd_ps x86 intrinsic", "_mm256_fnmadd_pd x86 intrinsic", "_mm256_fnmadd_ps x86 intrinsic", "_mm256_fnmsub_pd x86 intrinsic", "_mm256_fnmsub_ps x86 intrinsic", "_mm256_frcz_pd x86 intrinsic", "_mm256_frcz_ps x86 intrinsic", "_mm256_hadd_epi16 x86 intrinsic", "_mm256_hadd_epi32 x86 intrinsic", "_mm256_hadd_pd x86 intrinsic", "_mm256_hadd_ps x86 intrinsic", "_mm256_hadds_epi16 x86 intrinsic", "_mm256_hsub_epi16 x86 intrinsic", "_mm256_hsub_epi32 x86 intrinsic", "_mm256_hsub_pd x86 intrinsic", "_mm256_hsub_ps x86 intrinsic", "_mm256_hsubs_epi16 x86 intrinsic", "_mm256_i32gather_epi32 x86 intrinsic", "_mm256_i32gather_epi64 x86 intrinsic", "_mm256_i32gather_pd x86 intrinsic", "_mm256_i32gather_ps x86 intrinsic", "_mm256_i64gather_epi32 x86 intrinsic", "_mm256_i64gather_epi64 x86 intrinsic", "_mm256_i64gather_pd x86 intrinsic", "_mm256_i64gather_ps x86 intrinsic", "_mm256_insertf128_pd x86 intrinsic", "_mm256_insertf128_ps x86 intrinsic", "_mm256_insertf128_si256 x86 intrinsic", "_mm256_inserti128_si256 x86 intrinsic", "_mm256_lddqu_si256 x86 intrinsic", "_mm256_load_pd x86 intrinsic", "_mm256_load_ps x86 intrinsic", "_mm256_load_si256 x86 intrinsic", "_mm256_loadu_pd x86 intrinsic", "_mm256_loadu_ps x86 intrinsic", "_mm256_loadu_si256 x86 intrinsic", "_mm256_macc_pd x86 intrinsic", "_mm256_macc_ps x86 intrinsic", "_mm256_madd_epi16 x86 intrinsic", "_mm256_maddsub_pd x86 intrinsic", "_mm256_maddsub_ps x86 intrinsic", "_mm256_maddubs_epi16 x86 intrinsic", "_mm256_mask_i32gather_epi32 x86 intrinsic", "_mm256_mask_i32gather_epi64 x86 intrinsic", "_mm256_mask_i32gather_pd x86 intrinsic", "_mm256_mask_i32gather_ps x86 intrinsic", "_mm256_mask_i64gather_epi32 x86 intrinsic", "_mm256_mask_i64gather_epi64 x86 intrinsic", "_mm256_mask_i64gather_pd x86 intrinsic", "_mm256_mask_i64gather_ps x86 intrinsic", "_mm256_maskload_epi32 x86 intrinsic", "_mm256_maskload_epi64 x86 intrinsic", "_mm256_maskload_pd x86 intrinsic", "_mm256_maskload_ps x86 intrinsic", "_mm256_maskstore_epi32 x86 intrinsic", "_mm256_maskstore_epi64 x86 intrinsic", "_mm256_maskstore_pd x86 intrinsic", "_mm256_maskstore_ps x86 intrinsic", "_mm256_max_epi16 x86 intrinsic", "_mm256_max_epi32 x86 intrinsic", "_mm256_max_epi8 x86 intrinsic", "_mm256_max_epu16 x86 intrinsic", "_mm256_max_epu32 x86 intrinsic", "_mm256_max_epu8 x86 intrinsic", "_mm256_max_pd x86 intrinsic", "_mm256_max_ps x86 intrinsic", "_mm256_min_epi16 x86 intrinsic", "_mm256_min_epi32 x86 intrinsic", "_mm256_min_epi8 x86 intrinsic", "_mm256_min_epu16 x86 intrinsic", "_mm256_min_epu32 x86 intrinsic", "_mm256_min_epu8 x86 intrinsic", "_mm256_min_pd x86 intrinsic", "_mm256_min_ps x86 intrinsic", "_mm256_movedup_pd x86 intrinsic", "_mm256_movehdup_ps x86 intrinsic", "_mm256_moveldup_ps x86 intrinsic", "_mm256_movemask_epi8 x86 intrinsic", "_mm256_movemask_pd x86 intrinsic", "_mm256_movemask_ps x86 intrinsic", "_mm256_mpsadbw_epu8 x86 intrinsic", "_mm256_msub_pd x86 intrinsic", "_mm256_msub_ps x86 intrinsic", "_mm256_msubadd_pd x86 intrinsic", "_mm256_msubadd_ps x86 intrinsic", "_mm256_mul_epi32 x86 intrinsic", "_mm256_mul_epu32 x86 intrinsic", "_mm256_mul_pd x86 intrinsic", "_mm256_mul_ps x86 intrinsic", "_mm256_mulhi_epi16 x86 intrinsic", "_mm256_mulhi_epu16 x86 intrinsic", "_mm256_mulhrs_epi16 x86 intrinsic", "_mm256_mullo_epi16 x86 intrinsic", "_mm256_mullo_epi32 x86 intrinsic", "_mm256_nmacc_pd x86 intrinsic", "_mm256_nmacc_ps x86 intrinsic", "_mm256_nmsub_pd x86 intrinsic", "_mm256_nmsub_ps x86 intrinsic", "_mm256_or_pd x86 intrinsic", "_mm256_or_ps x86 intrinsic", "_mm256_or_si256 x86 intrinsic", "_mm256_packs_epi16 x86 intrinsic", "_mm256_packs_epi32 x86 intrinsic", "_mm256_packus_epi16 x86 intrinsic", "_mm256_packus_epi32 x86 intrinsic", "_mm256_permute_pd x86 intrinsic", "_mm256_permute_ps x86 intrinsic", "_mm256_permute2_pd x86 intrinsic", "_mm256_permute2_ps x86 intrinsic", "_mm256_permute2f128_pd x86 intrinsic", "_mm256_permute2f128_ps x86 intrinsic", "_mm256_permute2f128_si256 x86 intrinsic", "_mm256_permute2x128_si256 x86 intrinsic", "_mm256_permute4x64_epi64 x86 intrinsic", "_mm256_permute4x64_pd x86 intrinsic", "_mm256_permutevar_pd x86 intrinsic", "_mm256_permutevar_ps x86 intrinsic", "_mm256_permutevar8x32_epi32 x86 intrinsic", "_mm256_permutevar8x32_ps x86 intrinsic", "_mm256_rcp_ps x86 intrinsic", "_mm256_round_pd x86 intrinsic", "_mm256_round_ps x86 intrinsic", "_mm256_rsqrt_ps x86 intrinsic", "_mm256_sad_epu8 x86 intrinsic", "_mm256_set_epi16 x86 intrinsic", "_mm256_set_epi32 x86 intrinsic", "_mm256_set_epi8 x86 intrinsic", "_mm256_set_pd x86 intrinsic", "_mm256_set_ps x86 intrinsic", "_mm256_set1_epi16 x86 intrinsic", "_mm256_set1_epi32 x86 intrinsic", "_mm256_set1_epi8 x86 intrinsic", "_mm256_set1_pd x86 intrinsic", "_mm256_set1_ps x86 intrinsic", "_mm256_setr_epi16 x86 intrinsic", "_mm256_setr_epi32 x86 intrinsic", "_mm256_setr_epi8 x86 intrinsic", "_mm256_setr_pd x86 intrinsic", "_mm256_setr_ps x86 intrinsic", "_mm256_setzero_pd x86 intrinsic", "_mm256_setzero_ps x86 intrinsic", "_mm256_setzero_si256 x86 intrinsic", "_mm256_shuffle_epi32 x86 intrinsic", "_mm256_shuffle_epi8 x86 intrinsic", "_mm256_shuffle_pd x86 intrinsic", "_mm256_shuffle_ps x86 intrinsic", "_mm256_shufflehi_epi16 x86 intrinsic", "_mm256_shufflelo_epi16 x86 intrinsic", "_mm256_sign_epi16 x86 intrinsic", "_mm256_sign_epi32 x86 intrinsic", "_mm256_sign_epi8 x86 intrinsic", "_mm256_sll_epi16 x86 intrinsic", "_mm256_sll_epi32 x86 intrinsic", "_mm256_sll_epi64 x86 intrinsic", "_mm256_slli_epi16 x86 intrinsic", "_mm256_slli_epi32 x86 intrinsic", "_mm256_slli_epi64 x86 intrinsic", "_mm256_slli_si256 x86 intrinsic", "_mm256_sllv_epi32 x86 intrinsic", "_mm256_sllv_epi64 x86 intrinsic", "_mm256_sqrt_pd x86 intrinsic", "_mm256_sqrt_ps x86 intrinsic", "_mm256_sra_epi16 x86 intrinsic", "_mm256_sra_epi32 x86 intrinsic", "_mm256_srai_epi16 x86 intrinsic", "_mm256_srai_epi32 x86 intrinsic", "_mm256_srav_epi32 x86 intrinsic", "_mm256_srl_epi16 x86 intrinsic", "_mm256_srl_epi32 x86 intrinsic", "_mm256_srl_epi64 x86 intrinsic", "_mm256_srli_epi16 x86 intrinsic", "_mm256_srli_epi32 x86 intrinsic", "_mm256_srli_epi64 x86 intrinsic", "_mm256_srli_si256 x86 intrinsic", "_mm256_srlv_epi32 x86 intrinsic", "_mm256_srlv_epi64 x86 intrinsic", "_mm256_store_pd x86 intrinsic", "_mm256_store_ps x86 intrinsic", "_mm256_store_si256 x86 intrinsic", "_mm256_storeu_pd x86 intrinsic", "_mm256_storeu_ps x86 intrinsic", "_mm256_storeu_si256 x86 intrinsic", "_mm256_stream_load_si256 x86 intrinsic", "_mm256_stream_pd x86 intrinsic", "_mm256_stream_ps x86 intrinsic", "_mm256_stream_si256 x86 intrinsic", "_mm256_sub_epi16 x86 intrinsic", "_mm256_sub_epi32 x86 intrinsic", "_mm256_sub_epi64 x86 intrinsic", "_mm256_sub_epi8 x86 intrinsic", "_mm256_sub_pd x86 intrinsic", "_mm256_sub_ps x86 intrinsic", "_mm256_subs_epi16 x86 intrinsic", "_mm256_subs_epi8 x86 intrinsic", "_mm256_subs_epu16 x86 intrinsic", "_mm256_subs_epu8 x86 intrinsic", "_mm256_testc_pd x86 intrinsic", "_mm256_testc_ps x86 intrinsic", "_mm256_testc_si256 x86 intrinsic", "_mm256_testnzc_pd x86 intrinsic", "_mm256_testnzc_ps x86 intrinsic", "_mm256_testnzc_si256 x86 intrinsic", "_mm256_testz_pd x86 intrinsic", "_mm256_testz_ps x86 intrinsic", "_mm256_testz_si256 x86 intrinsic", "_mm256_unpackhi_epi16 x86 intrinsic", "_mm256_unpackhi_epi32 x86 intrinsic", "_mm256_unpackhi_epi64 x86 intrinsic", "_mm256_unpackhi_epi8 x86 intrinsic", "_mm256_unpackhi_pd x86 intrinsic", "_mm256_unpackhi_ps x86 intrinsic", "_mm256_unpacklo_epi16 x86 intrinsic", "_mm256_unpacklo_epi32 x86 intrinsic", "_mm256_unpacklo_epi64 x86 intrinsic", "_mm256_unpacklo_epi8 x86 intrinsic", "_mm256_unpacklo_pd x86 intrinsic", "_mm256_unpacklo_ps x86 intrinsic", "_mm256_xor_pd x86 intrinsic", "_mm256_xor_ps x86 intrinsic", "_mm256_xor_si256 x86 intrinsic", "_mm256_zeroall x86 intrinsic", "_mm256_zeroupper x86 intrinsic", "_mulx_u32 x86 intrinsic", "__nvreg_restore_fence x86 intrinsic", "__nvreg_save_fence x86 intrinsic", "_pdep_u32 x86 intrinsic", "_pext_u32 x86 intrinsic", "_rdrand16_step x86 intrinsic", "_rdrand32_step x86 intrinsic", "_rdseed16_step x86 intrinsic", "_rdseed32_step x86 intrinsic", "_rorx_u32 x86 intrinsic", "_rsm x86 intrinsic", "_sarx_i32 x86 intrinsic", "_sgdt x86 intrinsic", "_shlx_u32 x86 intrinsic", "_shrx_u32 x86 intrinsic", "__slwpcb x86 intrinsic", "_stac x86 intrinsic", "_store_be_u16 x86 intrinsic", "_storebe_i16 x86 intrinsic", "_store_be_u32 x86 intrinsic", "_storebe_i32 x86 intrinsic", "_Store_HLERelease x86 intrinsic", "_StorePointer_HLERelease x86 intrinsic", "_subborrow_u16 x86 intrinsic", "_subborrow_u32 x86 intrinsic", "_subborrow_u8 x86 intrinsic", "_t1mskc_u32 x86 intrinsic", "_tzcnt_u32 x86 intrinsic", "_tzmsk_u32 x86 intrinsic", "_xabort x86 intrinsic", "_xbegin x86 intrinsic", "_xend x86 intrinsic", "_xgetbv x86 intrinsic", "_xrstor x86 intrinsic", "_xsave x86 intrinsic", "_xsaveopt x86 intrinsic", "_xsetbv x86 intrinsic", "_xtest x86 intrinsic"] --- # x86 intrinsics list @@ -57,6 +57,12 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_blsmsk_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsmsk_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsmsk_u32(unsigned int);` | | [`_blsr_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_blsr_u32) | BMI | ammintrin.h, immintrin.h | `unsigned int _blsr_u32(unsigned int);` | | [`_bzhi_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_bzhi_u32) | BMI | immintrin.h | `unsigned int _bzhi_u32(unsigned int, unsigned int);` | +| [`_castf32_u32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf32_u32) | | immintrin.h | `unsigned __int32 _castf32_u32 (float);` | +| [`_castf64_u64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castf64_u64) | | immintrin.h | `unsigned __int64 _castf64_u64 (double);` | +| [`_castu32_f32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu32_f32) | | immintrin.h | `float _castu32_f32 (unsigned __int32);` | +| [`_castu64_f64`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_castu64_f64) | | immintrin.h | `double _castu64_f64 (unsigned __int64 a);` | +| [`__check_isa_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_isa_support(unsigned int, unsigned int);` | +| [`__check_arch_support`](check-isa-arch-support.md) | | immintrin.h | `bool __check_arch_support(unsigned int, unsigned int);` | | `_clac` | SMAP | intrin.h | `void _clac(void);` | | [`__cpuid`](cpuid-cpuidex.md) | | intrin.h | `void __cpuid(int *, int);` | | [`__cpuidex`](cpuid-cpuidex.md) | | intrin.h | `void __cpuidex(int *, int, int);` | @@ -69,7 +75,7 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`__fastfail`](fastfail.md) | | intrin.h | `void __fastfail(unsigned int);` | | [`_fxrstor`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxrstor) | FXSR | immintrin.h | `void _fxrstor(void const*);` | | [`_fxsave`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_fxsave) | FXSR | immintrin.h | `void _fxsave(void*);` | -| [`__getcallerseflags`](getcallerseflags.md) | | intrin.h | `(unsigned int __getcallerseflags());` | +| [`__getcallerseflags`](getcallerseflags.md) | | intrin.h | `unsigned int __getcallerseflags();` | | [`__halt`](halt.md) | | intrin.h | `void __halt(void);` | | [`__inbyte`](inbyte.md) | | intrin.h | `unsigned char __inbyte(unsigned short);` | | [`__inbytestring`](inbytestring.md) | | intrin.h | `void __inbytestring(unsigned short, unsigned char *, unsigned long);` | @@ -1121,7 +1127,7 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm256_round_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_round_ps) | AVX | immintrin.h | `__m256 _mm256_round_ps(__m256, int);` | | [`_mm256_rsqrt_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_rsqrt_ps) | AVX | immintrin.h | `__m256 _mm256_rsqrt_ps(__m256);` | | [`_mm256_sad_epu8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_sad_epu8) | AVX2 | immintrin.h | `__m256i _mm256_sad_epu8(__m256i, __m256i);` | -| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX | immintrin.h | `(__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_set_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi16) | AVX | immintrin.h | `__m256i _mm256_set_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | | [`_mm256_set_epi32`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi32) | AVX | immintrin.h | `__m256i _mm256_set_epi32(int, int, int, int, int, int, int, int);` | | [`_mm256_set_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_epi8) | AVX | immintrin.h | `__m256i _mm256_set_epi8(char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char, char);` | | [`_mm256_set_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set_pd) | AVX | immintrin.h | `__m256d _mm256_set_pd(double, double, double, double);` | @@ -1131,9 +1137,9 @@ The following table lists the intrinsics available on x86 processors. The Techno | [`_mm256_set1_epi8`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_epi8) | AVX | immintrin.h | `__m256i _mm256_set1_epi8(char);` | | [`_mm256_set1_pd`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_pd) | AVX | immintrin.h | `__m256d _mm256_set1_pd(double);` | | [`_mm256_set1_ps`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_set1_ps) | AVX | immintrin.h | `__m256 _mm256_set1_ps(float);` | -| [`_mm256_setr_epi16`](https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#text=_mm256_setr_epi16) | AVX | immintrin.h | `(__m256i _mm256_setr_epi16(short, short, short, short, short, short, short, short, short, short, short, short, short, short, short, short);` | +| [`_mm256_setr_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/cmake-linux-configure.md b/docs/linux/cmake-linux-configure.md index e2badf94a20..195a0cbd832 100644 --- a/docs/linux/cmake-linux-configure.md +++ b/docs/linux/cmake-linux-configure.md @@ -2,6 +2,7 @@ title: "Configure a Linux CMake project in Visual Studio" description: "How to configure Linux CMake settings in Visual Studio" ms.date: 01/03/2022 +ms.topic: how-to --- # Configure a Linux CMake project in Visual Studio @@ -108,7 +109,7 @@ When you do a build: ## Choose a Linux target -When you open a CMake project folder, Visual Studio parses the *CMakeLists.txt* file and specifies a Windows target of **x86-Debug**. To target a remote Linux system, you'll change the project settings based on your Linux compiler. For example, if you're using GCC on Linux and compiling with debug info, choose: **Linux-GCC-Debug** or **Linux-GCC-Release**. +When you open a CMake project folder, Visual Studio parses the *CMakeLists.txt* file, and specifies a Windows target of **x86-Debug**. To target a remote Linux system, you'll change the project settings based on your Linux compiler. For example, if you're using GCC on Linux and compiling with debug info, choose: **Linux-GCC-Debug** or **Linux-GCC-Release**. If you specify a remote Linux target, your source is copied to the remote system. @@ -125,11 +126,11 @@ If you're targeting Windows Subsystem for Linux (WSL), you don't need to add a r To target WSL, select **Manage Configurations** in the configuration dropdown in the main toolbar: -![CMake Manage Configurations.](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down") +![CMake configurations drop-down with Manage Configurations selected](../build/media/vs2019-cmake-manage-configurations.png "CMake configurations drop-down") The **CMakeSettings.json** window appears. -![Add configuration.](media/cmake-linux-configurations.png "Add a configuration to CMake settings") +![CMake settings dialog with the plus button highlighted which adds the selected configuration, which is Linux-GCC-debug.](media/cmake-linux-configurations.png) Press **Add Configuration** (the green '+' button) and then choose **Linux-GCC-Debug** or **Linux-GCC-Release** if using GCC. Use the Clang variants if you're using the Clang/LLVM toolset. Press **Select** and then **Ctrl+S** to save the configuration. diff --git a/docs/linux/cmake-linux-project.md b/docs/linux/cmake-linux-project.md index 821cbc5e046..538d0fb2005 100644 --- a/docs/linux/cmake-linux-project.md +++ b/docs/linux/cmake-linux-project.md @@ -3,6 +3,7 @@ title: "Create a CMake Linux project in Visual Studio" description: "How to create a Linux CMake project in Visual Studio" ms.date: "08/06/2020" ms.assetid: f8707b32-f90d-494d-ae0b-1d44425fdc25 +ms.topic: how-to --- # Create a CMake Linux project in Visual Studio diff --git a/docs/linux/configure-a-linux-project.md b/docs/linux/configure-a-linux-project.md index 88ef152274b..ac65f32b525 100644 --- a/docs/linux/configure-a-linux-project.md +++ b/docs/linux/configure-a-linux-project.md @@ -3,6 +3,7 @@ title: "Configure a Linux MSBuild C++ project in Visual Studio" ms.date: "10/16/2020" description: "Configure a MSBuild-based Linux project in Visual Studio so you can build it." ms.assetid: 4d7c6adf-54b9-4b23-bd23-5de0c825b768 +ms.custom: sfi-image-nochange --- # Configure a Linux MSBuild C++ project in Visual Studio diff --git a/docs/linux/connect-to-your-remote-linux-computer.md b/docs/linux/connect-to-your-remote-linux-computer.md index 2199001c80e..0ffc8a5aba9 100644 --- a/docs/linux/connect-to-your-remote-linux-computer.md +++ b/docs/linux/connect-to-your-remote-linux-computer.md @@ -1,9 +1,11 @@ --- -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 +ms.custom: sfi-image-nochange --- -# 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 +27,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 +42,7 @@ To build the project, Visual Studio copies the source code to your remote Linux ::: moniker range=">=msvc-150" -## Set up the SSH server on the remote system +## Set up the SSH server on the remote machine If `ssh` isn't already set up and running on your Linux system, follow these steps to install it. The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7.6. However, the instructions should be the same for any distro using a moderately recent version of OpenSSH. @@ -50,7 +53,7 @@ If `ssh` isn't already set up and running on your Linux system, follow these ste sudo service ssh start ``` -1. If you’d like the ssh server to start automatically when the system boots, enable it using systemctl: +1. If you'd like the ssh server to start automatically when the system boots, enable it using systemctl: ```bash sudo systemctl enable ssh @@ -58,17 +61,21 @@ If `ssh` isn't already set up and running on your Linux system, follow these ste ## Set up the remote connection -1. In Visual Studio, choose **Tools > Options** on the menu bar to open the **Options** dialog. Then select **Cross Platform > Connection Manager** to open the Connection Manager dialog. +1. In Visual Studio on your local Windows system, choose **Tools > Options** on the menu bar to open the **Options** dialog. Then select **Cross Platform > Connection Manager** to open the Connection Manager dialog. If you haven't set up a connection in Visual Studio before, when you build your project for the first time, Visual Studio opens the Connection Manager dialog for you. 1. In the Connection Manager dialog, choose the **Add** button to add a new connection. - ![Screenshot showing the Connection Manager dialog.](media/settings_connectionmanager.png) + :::image type="complex" source="media/connect-to-your-remote-linux-computer/settings-connection-manager-updated.png" alt-text="Screenshot of the Visual Studio options pane."::: + In the options pane, CrossPlatform > C++ > Connection Manager is selected and the Add button is highlighted. + :::image-end::: - In either scenario, the **Connect to Remote System** window is displayed. + To edit an existing connection, choose **Edit**. In either scenario, the **Connect to Remote System** window is displayed. - ![Screenshot showing the Connect to Remote System window.](media/connect.png) + :::image type="complex" source="media/connect-to-your-remote-linux-computer/connect-updated.png" alt-text="Screenshot of the Visual Studio Connect to Remote System window."::: + In the Connect to Remote System window, there are fields for host name, port, user name, authentication type, and password. Port is set to 22. Authentication type is set to 'Password'. + :::image-end::: 1. Enter the following information: @@ -80,17 +87,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. - You can use either a password or a key file and passphrase for authentication. For many development scenarios, password authentication is sufficient, but key files are more secure. If you already have a key pair, it's possible to reuse it. Currently Visual Studio only supports RSA and DSA keys for remote connections. + Versions of Visual Studio before 17.10 support Elliptic Curve (EC), Rivert-Shamir-Adleman (RSA), and Digital signature algorithm (DSA) keys for remote connections. Because of security concerns, DSA keys are no longer supported in VS 17.10 and later. RSA keys were also not supported in VS 17.10 and VS 17.11 but some types are supported again in VS 17.12 and later. To create a key pair compatible with the connection manager, you can use the command: + `ssh-keygen -m pem -t ecdsa -f ` + + > [!NOTE] + > If using `ssh-keygen` to create the private key, you must specify the switch `-m pem`, or the key isn't accepted by Visual Studio. If your private key begins with `-----BEGIN OPENSSH PRIVATE KEY-----`, you must convert it with `ssh-keygen -p -f -m pem`. 1. Choose the **Connect** button to attempt a connection to the remote computer. If the connection succeeds, Visual Studio configures IntelliSense to use the remote headers. For more information, see [IntelliSense for headers on remote systems](configure-a-linux-project.md#remote_intellisense). - If the connection fails, the entry boxes that need to be changed are outlined in red. + If the connection fails, an info bar with error information appears and the fields that you might need to change are outlined in red. - ![Screenshot showing a Connection Manager Error.](media/settings_connectionmanagererror.png) + :::image type="content" source="media/connect-to-your-remote-linux-computer/settings-connection-manager-error-updated.png" alt-text="Screenshot of the Visual Studio Connect to Remote System window. The host name and port fields are outlined in red to indicate incorrect entries."::: If you use key files for authentication, make sure the target machine's SSH server is running and configured properly. @@ -102,36 +117,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-cbc`
`aes192-cbc`
`aes192-ctr`
`aes256-cbc`
`aes256-ctr` | -| HMAC | `hmac-sha2-256`
`hmac-sha2-256` | +| Encryption | `aes128-cbc`
`aes128-ctr`
`aes192-cbc`
`aes192-ctr`
`aes256-cbc`
`aes256-ctr` | +| HMAC | `hmac-sha2-256`
`hmac-sha2-512` | | Key exchange | `diffie-hellman-group14-sha256`
`diffie-hellman-group16-sha512`
`diffie-hellman-group-exchange-sha256`
`ecdh-sha2-nistp256`
`ecdh-sha2-nistp384`
`ecdh-sha2-nistp521` | -| Host key | `ecdsa-sha2-nistp256`
`ecdsa-sha2-nistp384`
`ecdsa-sha2-nistp521`
`ssh-dss`
`ssh-rsa` | +| Host key | `ecdsa-sha2-nistp256`
`ecdsa-sha2-nistp384`
`ecdsa-sha2-nistp521`
`rsa-sha2-512`
`rsa-sha2-256` | ### Configure the SSH server First, a little background. You can't select the SSH algorithm to use from Visual Studio. Instead, the algorithm is determined during the initial handshake with the SSH server. Each side (client and server) provides a list of algorithms it supports, and then the first algorithm common to both is selected. The connection succeeds as long as there's at least one algorithm in common between Visual Studio and the server for encryption, HMAC, key exchange, and so on. -The Open SSH configuration file (*`sshd_config`*) doesn't configure which algorithm to use by default. The SSH server should use secure defaults when no algorithms are specified. Those defaults depend on the version and vendor of the SSH server. If Visual Studio doesn't support those defaults, you'll likely see an error like: "Could not connect to the remote system. No common client to server HMAC algorithm was found." The error may also appear if the SSH server is configured to use algorithms that Visual Studio doesn't support. +The Open SSH configuration file (*`sshd_config`*) doesn't configure which algorithm to use by default. The SSH server should use secure defaults when no algorithms are specified. Those defaults depend on the version and vendor of the SSH server. If Visual Studio doesn't support those defaults, you'll likely see an error like: *Could not connect to the remote system. No common client to server HMAC algorithm was found.* The error might also appear if the SSH server is configured to use algorithms that Visual Studio doesn't support. -The default SSH server on most modern Linux distributions should work with Visual Studio. However, you may be running an older SSH server that's configured to use older, insecure algorithms. The following example explains how to update to more secure versions. +The default SSH server on most modern Linux distributions should work with Visual Studio. However, you might be running an older SSH server that's configured to use older, insecure algorithms. The following example explains how to update to more secure versions. -In the following example, the SSH server uses the insecure `hmac-sha1` algorithm, which isn't supported by Visual Studio 16.9. If the SSH server uses OpenSSH, you can edit the `/etc/ssh/sshd_config` file as shown below to enable more secure algorithms. For other SSH servers, refer to the server's documentation for how to configure them. +In this example, the SSH server uses the insecure `hmac-sha1` algorithm, which Visual Studio 16.9 doesn't support. If the SSH server uses OpenSSH, you can edit the `/etc/ssh/sshd_config` file to enable more secure algorithms. For other SSH servers, refer to the server's documentation for how to configure them. -First, verify that the set of algorithms your server is using includes algorithms supported by Visual Studio. Run the following command on the remote machine to list the algorithms supported by the server: +First, verify that the set of algorithms your server is using includes algorithms supported by Visual Studio. Run the following command on the remote machine to list the algorithms supported by the server: ```bash ssh -Q cipher; ssh -Q mac; ssh -Q kex; ssh -Q key @@ -149,7 +164,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 +172,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,37 +190,39 @@ For example: `KexAlgorithms ecdh-sha2-nistp256,ecdh-sha2-nistp384` #### Host key example Add: `HostKeyAlgorithms ` -For example: `HostKeyAlgorithms ssh-dss,ssh-rsa` +For example: `HostKeyAlgorithms ecdsa-sha2-nistp256,ecdsa-sha2-nistp384` ## Logging for remote connections - You can enable logging to help troubleshoot connection problems. On the menu bar, select **Tools > Options**. In the **Options** dialog, select **Cross Platform > Logging**: +You can enable logging to help troubleshoot connection problems. On the menu bar, select **Tools > Options**. In the **Options** dialog, select **Cross Platform > Logging**: - ![Screenshot showing Remote Logging.](media/remote-logging-vs2019.png) +:::image type="complex" source="media/remote-logging-vs2019.png" alt-text="Screenshot of the Visual Studio options screen."::: +The options are open to Cross Platform > Connection Manager > Logging. Enable logging is checked, log to a file is checked, the logfile directory is set the documents folder, and log to the 'Cross Platform Logging' pane in the output window is checked. +:::image-end::: - Logs include connections, all commands sent to the remote machine (their text, exit code and execution time), and all output from Visual Studio to the shell. Logging works for any cross-platform CMake project or MSBuild-based Linux project in Visual Studio. +Logs include connections, all commands sent to the remote machine (their text, exit code and execution time), and all output from Visual Studio to the shell. Logging works for any cross-platform CMake project or MSBuild-based Linux project in Visual Studio. - You can configure the output to go to a file or to the **Cross Platform Logging** pane in the Output window. For MSBuild-based Linux projects, MSBuild commands sent to the remote machine aren't routed to the **Output Window** because they're emitted out-of-process. Instead, they're logged to a file, with a prefix of "msbuild_". +You can configure the output to go to a file or to the **Cross Platform Logging** pane in the Output window. For MSBuild-based Linux projects, MSBuild commands sent to the remote machine aren't routed to the **Output Window** because they're emitted out-of-process. Instead, they're logged to a file, with a prefix of `msbuild_`. -## Command-line utility for the Connection Manager +## 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 - -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: - -![Screenshot showing a Headers Error.](media/port-forwarding-headers-error.png) +## 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, this error appears when the download of remote headers for IntelliSense begins: +:::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 showing an Rsync Error.](media/port-forwarding-copy-error.png) +:::image type="complex" source="media/port-forwarding-copy-error.png" alt-text="Screenshot of the Visual Studio output window displaying a Rsync Error message."::: +The output window includes these messages: Verify that TCP forwarding is enabled on the server, rsync: did not see server greeting, rsync error: error starting client-server protocol (code 5) at main.c(1675) [sender=3.1.3], An SSH channel couldn't be opened. +:::image-end::: `gdbserver` can be used for debugging on embedded devices. If you can't enable TCP port forwarding, then you must use `gdb` for all remote debugging scenarios. `gdb` is used by default when debugging projects on a remote system. @@ -217,7 +234,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 @@ -233,7 +250,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 @@ -256,9 +273,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 3fff906968f..14b4e8c152c 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/create-a-new-linux-project.md b/docs/linux/create-a-new-linux-project.md index d2d98e79f44..20a574b8603 100644 --- a/docs/linux/create-a-new-linux-project.md +++ b/docs/linux/create-a-new-linux-project.md @@ -2,7 +2,7 @@ title: "Create a Linux MSBuild C++ project in Visual Studio" ms.date: "10/15/2020" description: "Create a new MSBuild-based Linux project in Visual Studio." -ms.assetid: 5d7c1d67-bc31-4f96-8622-2b4cf91372fd +ms.topic: how-to --- # Create a Linux MSBuild C++ project in Visual Studio @@ -25,7 +25,7 @@ To create a new Linux project in Visual Studio 2017, follow these steps: 1. Select **File > New Project** in Visual Studio, or press **Ctrl + Shift + N**. 1. Select the **Visual C++ > Cross Platform > Linux** node, and then select the project type to create. Enter a **Name** and **Location**, and choose **OK**. - ![Screenshot showing the New Project dialog box with Visual C plus plus > Cross Platform > Linux selected, all of the project types called out, and the Name and Location text boxes also called out.](media/newproject.png) +![The New Project dialog box with Visual C plus plus > Cross Platform > Linux selected and all project types and Name and Location text boxes called out.](media/newproject.png) | Project Type | Description | | ------------ | --- | @@ -52,7 +52,7 @@ To create a new Linux project in Visual Studio, follow these steps: 1. In the **Search for templates** textbox, enter **Linux** to list the available templates for Linux projects. 1. Select the project type to create, for example **Console Application**, and then choose **Next**. Enter a **Name** and **Location**, and choose **Create**. - ![Screenshot of the new project dialog box with the language drop-down set to C++ and the platform drop-down set to Linux.](media/newproject-vs2019.png) + ![Screenshot of the new project dialog box with the language drop-down set to C plus plus and the platform drop-down set to Linux.](media/newproject-vs2019.png) | Project Type | Description | | ------------ | --- | diff --git a/docs/linux/deploy-run-and-debug-your-linux-project.md b/docs/linux/deploy-run-and-debug-your-linux-project.md index e7911b3e5bc..999f3e19c0d 100644 --- a/docs/linux/deploy-run-and-debug-your-linux-project.md +++ b/docs/linux/deploy-run-and-debug-your-linux-project.md @@ -1,9 +1,10 @@ --- title: "Deploy, run, and debug your Linux MSBuild C++ project in Visual Studio" description: "Describes how to compile, execute, and debug code on the remote target from inside a MSBuild-based Linux C++ project in Visual Studio." -ms.date: "08/08/2020" -ms.assetid: f7084cdb-17b1-4960-b522-f84981bea879 -ms.custom: intro-deployment +ms.date: 12/5/2024 +ms.custom: + - intro-deployment + - sfi-image-nochange --- # Deploy, run, and debug your Linux MSBuild project @@ -34,72 +35,67 @@ There are several ways to interact with and debug your Linux project. GDB is used to debug applications running on Linux. When debugging on a remote system (not WSL) GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page: ![Screenshot of the Visual Studio Linux Console App Property Pages dialog box with Configuration Properties > Debugging selected and Debugging Mode highlighted with G D B selected and highlighted from the dropdown list.](media/vs2019-debugger-settings.png) + + ::: moniker-end - ::: moniker-end + ::: moniker range="msvc-150" - ::: moniker range="msvc-150" - - GDB is used to debug applications running on Linux. GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page: + GDB is used to debug applications running on Linux. GDB can run in two different modes, which can be selected from the **Debugging Mode** option in the project's **Debugging** property page: ![Screenshot of the Visual Studio 2017 Linux Console App Property Pages dialog box with Configuration Properties > Debugging selected and Debugging Mode highlighted with G D B selected and highlighted from the dropdown list.](media/vs2017-debugger-settings.png) + + ::: moniker-end - ::: moniker-end - - - In **gdbserver** mode, GDB is run locally, which connects to gdbserver on the remote system. + - In **gdbserver** mode, GDB is run locally, which connects to gdbserver on the remote system. To use this, you must provide a local Windows path to GDB under **Debugger Path** in **Visual Studio 2022 version 17.6** and later, or under **GDB Path** in **Visual Studio 2019 version 16.11** and earlier. For more information about where to provide the path to GDB for CMake projects, see [Additional options allowed with the gdbserver configuration (16.7 or later)](../build/configure-cmake-debugging-sessions.md#additional-options-allowed-with-the-gdbserver-configuration-167-or-later). - In **gdb** mode, the Visual Studio debugger drives GDB on the remote system. This is a better option if the local version of GDB isn't compatible with the version installed on the target computer. This is the only mode that the Linux Console window supports. - > [!NOTE] - > If you are unable to hit breakpoints in gdbserver debugging mode, try gdb mode. gdb must first be [installed](download-install-and-setup-the-linux-development-workload.md) on the remote target. + > [!NOTE] + > If you are unable to hit breakpoints in gdbserver debugging mode, try gdb mode. gdb must first be [installed](download-install-and-setup-the-linux-development-workload.md) on the remote target. 1. Select the remote target using the standard **Debug** toolbar in Visual Studio. - When the remote target is available, you'll see it listed by either name or IP address. - - ![Screenshot showing a Remote target.](media/remote_target.png) - - If you haven't connected to the remote target yet, you'll see an instruction to use [Linux Connection Manager](connect-to-your-remote-linux-computer.md) to connect to the remote target. + When the remote target is available, you see it listed by name or IP address: - ![Screenshot showing the Remote Architecture.](media/architecture.png) + ![Screenshot showing a Remote target IP address.](media/remote_target.png) + + If you haven't connected to the remote target yet, you see instructions to use [Linux Connection Manager](connect-to-your-remote-linux-computer.md) to connect to the remote target: -1. Set a breakpoint by clicking in the left gutter of some code that you know will execute. - - A red dot appears on the line of code where you set the breakpoint. + ![Screenshot showing the Remote Architecture, which is x64.](media/architecture.png) + +1. Set a breakpoint by clicking in the left gutter of some code that you know will execute. A red dot appears on the line of code where you set the breakpoint. 1. Press **F5** (or **Debug > Start Debugging**) to start debugging. - When you start debugging, the application is compiled on the remote target before it starts. Any compilation errors will appear in the **Error List** window. + When you start debugging, the application is compiled on the remote target before it starts. Any compilation errors appear in the **Error List** window. - If there are no errors, the app will start and the debugger will pause at the breakpoint. + If there are no errors, the app starts and the debugger pauses at the breakpoint: ![Screenshot showing the app has hit a breakpoint.](media/hit_breakpoint.png) - - Now, you can interact with the application in its current state, view variables, and step through code by pressing command keys such as **F10** or **F11**. + + Now, you can interact with the application in its current state, view variables, and step through code by pressing command keys such as **F10** or **F11**. 1. If you want to use the Linux Console to interact with your app, select **Debug > Linux Console**. ![Screenshot showing the Linux Console menu item.](media/consolemenu.png) - - This console will display any console output from the target computer and take input and send it to the target computer. + + This console displays console output from the target computer and takes input and sends it to the target computer. ![Screenshot showing the Linux Console window.](media/consolewindow.png) - + ## Configure other debugging options (MSBuild projects) - Command-line arguments can be passed to the executable using the **Program Arguments** item in the project's **Debugging** property page. - You can export the `DISPLAY` environment variable by using the **Pre-Launch Command** in the project's **Debugging** property pages. For example: `export DISPLAY=:0.0` ![Screenshot showing the Program Arguments property in the Property Pages dialog.](media/settings_programarguments.png) - -- Specific debugger options can be passed to GDB using the **Additional Debugger Commands** entry. For example, you might want to ignore SIGILL (illegal instruction) signals. You could use the **handle** command to achieve this by adding the following to the **Additional Debugger Commands** entry as shown above: - - `handle SIGILL nostop noprint` - -- You can specify the path to the GDB used by Visual Studio using the **GDB Path** item in the project's **Debugging** property page. This property is available in Visual Studio 2019 version 16.9 and later. + +- Specific debugger options can be passed to GDB using the **Additional Debugger Commands** entry. For example, you might want to ignore SIGILL (illegal instruction) signals. You could use the **handle** command to achieve this by adding the following to the **Additional Debugger Commands** entry shown above: `handle SIGILL nostop noprint`. +- Specify the path to the GDB used by Visual Studio using the **GDB Path** item in the project's **Debugging** property page. This property is available in Visual Studio 2019 version 16.9 and later. ## Debug with Attach to Process -The [Debugging](prop-pages/debugging-linux.md) property page for Visual Studio projects, and the **Launch.vs.json** settings for CMake projects, have settings that enable you to attach to a running process. If you require additional control beyond what is provided in those settings, you can place a file named `Microsoft.MIEngine.Options.xml` in the root of your solution or workspace. Here is a simple example: +The [Debugging](prop-pages/debugging-linux.md) property page for Visual Studio projects, and the **Launch.vs.json** settings for CMake projects, have settings that enable you to attach to a running process. If you require more control beyond what is provided in those settings, you can place a file named `Microsoft.MIEngine.Options.xml` in the root of your solution or workspace. Here's a simple example: ```xml @@ -116,7 +112,7 @@ ExePath="C:\temp\ConsoleApplication17\ConsoleApplication17\bin\x64\Debug\Console ``` -The **AttachOptionsForConnection** has most of the attributes you might need. The example above shows how to specify a location to search for additional .so libraries. The child element **ServerOptions** enables attaching to the remote process with gdbserver instead. To do that, you need to specify a local gdb client (the one shipped in Visual Studio 2017 is shown above) and a local copy of the binary with symbols. The **SetupCommands** element enables you to pass commands directly to gdb. You can find all the options available in the [LaunchOptions.xsd schema](https://github.com/Microsoft/MIEngine/blob/master/src/MICore/LaunchOptions.xsd) on GitHub. +The **AttachOptionsForConnection** has most of the attributes you might need. The example above shows how to specify a location to search for more `.so` libraries. The child element **ServerOptions** enables attaching to the remote process with gdbserver instead. To do that, you need to specify a local gdb client (the one shipped in Visual Studio 2017 is shown above) and a local copy of the binary with symbols. The **SetupCommands** element enables you to pass commands directly to gdb. You can find all the options available in the [LaunchOptions.xsd schema](https://github.com/Microsoft/MIEngine/blob/main/src/MICore/LaunchOptions.xsd) on GitHub. ::: moniker range=">=msvc-160" @@ -124,22 +120,23 @@ The **AttachOptionsForConnection** has most of the attributes you might need. Th You can separate your remote build machine from your remote debug machine for both MSBuild-based Linux projects and CMake projects that target a remote Linux machine. For example, you can now cross-compile on x64 and deploy to an ARM device when targeting IoT scenarios. -By default, the remote debug machine is the same as the remote build machine (**Configuration Properties** > **General** > **Remote Build Machine**). To specify a new remote debug machine, right-click on the project in **Solution Explorer** and go to **Configuration Properties** > **Debugging** > **Remote Debug Machine**. +By default, the remote debug machine is the same as the remote build machine (**Configuration Properties** > **General** > **Remote Build Machine**). To specify a new remote debug machine, right-click on the project in **Solution Explorer** and go to **Configuration Properties** > **Debugging** > **Remote Debug Machine**: + +![Screenshot showing the Linux remote debug machine property in the Property Pages dialog which shows the username, authentication type, and port.](media/linux-remote-debug-machine.png) -![Screenshot showing the Linux remote debug machine property in the Property Pages dialog.](media/linux-remote-debug-machine.png) +The drop-down menu for **Remote Debug Machine** is populated with all established remote connections. -The drop-down menu for **Remote Debug Machine** is populated with all established remote connections. To add a new remote connection, navigate to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or search for "Connection Manager" in **Quick Launch**. You can also specify a new remote deploy directory in the project's Property Pages (**Configuration Properties** > **General** > **Remote Deploy Directory**). +To add a new remote connection, navigate to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or search for "Connection Manager" in **Quick Launch**. You can also specify a new remote deploy directory in the project's Property Pages (**Configuration Properties** > **General** > **Remote Deploy Directory**). -By default, only the files necessary for the process to debug will be deployed to the remote debug machine. You can use **Solution Explorer** to configure which source files will be deployed to the remote debug machine. When you click on a source file, you'll see a preview of its File Properties directly below the Solution Explorer. +By default, only the files necessary for the process to debug are deployed to the remote debug machine. You can use **Solution Explorer** to configure which source files are deployed to the remote debug machine. When you click on a source file, you see a preview of its File Properties directly below the Solution Explorer: -![Screenshot showing the Linux deployable files specified in the Properties window.](media/linux-deployable-content.png) +![Screenshot showing the properties of the file main.cpp with the property content = False highlighted.](media/linux-deployable-content.png) The **Content** property specifies whether the file will be deployed to the remote debug machine. You can disable deployment entirely by navigating to **Property Pages** > **Configuration Manager** and unchecking **Deploy** for the desired configuration. In some cases, you may require more control over your project's deployment. For example, some files that you want to deploy might be outside of your solution or you want to customize your remote deploy directory per file or directory. In these cases, append the following code block(s) to your .vcxproj file and replace "example.cpp" with the actual file names: ```xml - @@ -157,11 +154,11 @@ In some cases, you may require more control over your project's deployment. For ### CMake projects -For CMake projects that target a remote Linux machine, you can specify a new remote debug machine in launch.vs.json. By default, the value of "remoteMachineName" is synchronized with the "remoteMachineName" property in CMakeSettings.json, which corresponds to your remote build machine. These properties no longer need to match, and the value of "remoteMachineName" in launch.vs.json will dictate which remote machine is used for deploy and debug. +For CMake projects that target a remote Linux machine, you can specify a new remote debug machine in launch.vs.json. By default, the value of `"remoteMachineName"` is synchronized with the `"remoteMachineName"` property in `CMakeSettings.json`, which corresponds to your remote build machine. These properties no longer need to match, and the value of `"remoteMachineName"` in `launch.vs.json` dictate which remote machine is used for deploy and debug. -![The CMake remote debug machine specified in the launch.vs.json file.](media/cmake-remote-debug-machine.png) +![The CMake remote debug machine specified in the launch_schema.json file. The remote Machine Name is ${debugInfo . remoteMachineName}](media/cmake-remote-debug-machine.png) -IntelliSense will suggest all a list of all established remote connections. You can add a new remote connection by navigating to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or searching for "Connection Manager" in **Quick Launch**. +IntelliSense suggests a list of all established remote connections. You can add a new remote connection by navigating to **Tools** > **Options** > **Cross Platform** > **Connection Manager** or searching for "Connection Manager" in **Quick Launch**. If you want complete control over your deployment, you can append the following code block(s) to the launch.vs.json file. Remember to replace the placeholder values with real values: diff --git a/docs/linux/download-install-and-setup-the-linux-development-workload.md b/docs/linux/download-install-and-setup-the-linux-development-workload.md index 102bfca8ada..7187b8f44d6 100644 --- a/docs/linux/download-install-and-setup-the-linux-development-workload.md +++ b/docs/linux/download-install-and-setup-the-linux-development-workload.md @@ -1,15 +1,15 @@ --- -title: "Install the C++ Linux workload in Visual Studio" -description: "How to download, install, and set up the Linux workload for C++ in Visual Studio." -ms.date: "05/03/2020" -ms.assetid: e11b40b2-f3a4-4f06-b788-73334d58dfd9 +title: "Install the C++ Linux Workload in Visual Studio" +description: "Learn how to download, install, and set up the Linux workload for C++ in Visual Studio." +ms.date: 03/25/2025 +ms.topic: how-to ms.custom: intro-installation --- # Download, install, and set up the Linux workload ::: moniker range="msvc-140" -Linux projects are supported in Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector control for this article to Visual Studio 2017 or Visual Studio 2019. It's found at the top of the table of contents on this page. +Linux projects are supported in Visual Studio 2017 and later. To see the documentation for these versions, set the Visual Studio **Version** selector for this article to Visual Studio 2017, Visual Studio 2019, or Visual Studio 2022. It's found at the top of the table of contents on this page. ::: moniker-end @@ -19,7 +19,7 @@ You can use the Visual Studio IDE on Windows to create, edit, and debug C++ proj You can work on your existing code base that uses CMake without having to convert it to a Visual Studio project. If your code base is cross-platform, you can target both Windows and Linux from within Visual Studio. For example, you can edit, build, and debug your code on Windows using Visual Studio. Then, quickly retarget the project for Linux to build and debug in a Linux environment. Linux header files are automatically copied to your local machine. Visual Studio uses them to provide full IntelliSense support (Statement Completion, Go to Definition, and so on). -For any of these scenarios, the **Linux development with C++** workload is required. +For any of these scenarios, the **Linux and embedded development with C++** workload is required. ::: moniker-end @@ -27,23 +27,25 @@ For any of these scenarios, the **Linux development with C++** workload is requi ## Visual Studio setup -1. Type "Visual Studio Installer" in the Windows search box: +1. Open the Visual Studio Installer from your Start menu. If you can't find it, type *Visual Studio Installer* in the Windows search box and look for the installer under the **Apps** results. - ![Screenshot showing the Windows search box.](media/visual-studio-installer-search.png) + :::image type="content" source="media/visual-studio-installer-search.png" alt-text="Screenshot of the Windows search box that contains the text visual studio installer."::: -1. Look for the installer under the **Apps** results and double-click it. When the installer opens, choose **Modify**, and then click on the **Workloads** tab. Scroll down to **Other toolsets** and select the **Linux development with C++** workload. +1. When the installer opens, choose **Modify**, and then click on the **Workloads** tab. Scroll down to **Other toolsets** and select the **Linux and embedded development with C++** workload. - ![Screenshot showing the Visual C++ for Linux Development workload item in Visual Studio Installer.](media/linuxworkload.png) + :::image type="complex" source="./media/linux-workload.png" alt-text="Screenshot highlighting the Visual C++ for Linux and embedded development workload item in Visual Studio Installer."::: + The Linux and embedded development workload is selected. The Installation details pane is highlighted, which lists what's included in the workload. Which includes: Visual Studio C++ core features, Windows Universal C runtime, Visual C++ for Linux development. An optional component is also selected: Visual C++ tools for CMake and Linux. + :::image-end::: -1. If you're targeting IoT or embedded platforms, go to the **Installation details** pane on the right. Under **Linux development with C++**, expand **Optional Components**, and choose the components you need. CMake support for Linux is selected by default. +1. If you're targeting IoT or embedded platforms, go to the **Installation details** pane on the right. Under **Linux and embedded development with C++**, expand **Optional Components**, and choose the components you need. CMake support for Linux is selected by default. 1. Click **Modify** to continue with the installation. ## Options for creating a Linux environment -If you don't already have a Linux machine, you can create a Linux Virtual Machine on Azure. For more information, see [Quickstart: Create a Linux virtual machine in the Azure portal](/azure/virtual-machines/linux/quick-create-portal). +If you don't already have a Linux machine, you can create a Linux virtual machine on Azure. For more information, see [Quickstart: Create a Linux virtual machine in the Azure portal](/azure/virtual-machines/linux/quick-create-portal). -On Windows 10 and later, you can install and target your favorite Linux distro on the Windows Subsystem for Linux (WSL). For more information, see [Windows Subsystem for Linux Installation Guide for Windows 10](/windows/wsl/install-win10). If you're unable to access the Windows Store, you can [manually download the WSL distro packages](/windows/wsl/install-manual). WSL is a convenient console environment, but it's not recommended for graphical applications. +On Windows 10 and later, you can install and target your favorite Linux distro on the Windows Subsystem for Linux (WSL). For more information, see [How to install Linux on Windows with WSL](/windows/wsl/install). If you're unable to access the Windows Store, you can [manually download the WSL distro packages](/windows/wsl/install-manual). WSL is a convenient console environment, but it's not recommended for graphical applications. ::: moniker-end @@ -100,9 +102,9 @@ The target Linux system must have **openssh-server**, **g++**, **gdb**, and **ma sudo apt-get install openssh-server g++ gdb make ninja-build rsync zip ``` - You may be prompted for your root password to run the sudo command. If so, enter it and continue. Once complete, the required services and tools are installed. + You might be prompted for your root password to run the `sudo` command. If so, enter it and continue. Once complete, the required services and tools are installed. -1. Ensure the ssh service is running on your Linux computer by running: +1. Ensure the ssh service is running on your Linux computer: ```bash sudo service ssh start @@ -138,9 +140,9 @@ The target machine running Fedora uses the **dnf** package installer. To downloa sudo dnf install openssh-server gcc-g++ gdb ninja-build make rsync zip ``` - You may be prompted for your root password to run the sudo command. If so, enter it and continue. Once complete, the required services and tools are installed. + You might be prompted for your root password to run the sudo command. If so, enter it and continue. Once complete, the required services and tools are installed. -1. Ensure the ssh service is running on your Linux computer by running: +1. Ensure the ssh service is running on your Linux computer: ```bash sudo systemctl start sshd @@ -148,11 +150,9 @@ The target machine running Fedora uses the **dnf** package installer. To downloa This command starts the service and runs it in the background, ready to accept connections. -## Next Steps +## Related content -You're now ready to create or open a Linux project and configure it to run on the target system. For more information, see: - -- [Create a new Linux MSBuild C++ project](create-a-new-linux-project.md) -- [Configure a Linux CMake project](cmake-linux-project.md) +- [Create a Linux MSBuild C++ project in Visual Studio](create-a-new-linux-project.md) +- [Create a CMake Linux project in Visual Studio](cmake-linux-project.md) ::: moniker-end diff --git a/docs/linux/index.yml b/docs/linux/index.yml index 206faf4104d..0883a98df6e 100644 --- a/docs/linux/index.yml +++ b/docs/linux/index.yml @@ -6,8 +6,8 @@ metadata: title: Linux development with C++ description: Learn how to use C++ in Visual Studio 2017 and later to create and debug applications for Linux. ms.topic: landing-page - author: corob-msft - ms.author: corob + author: tylermsft + ms.author: twhitney ms.date: 04/26/2020 ms.custom: intro-landing-hub diff --git a/docs/linux/linux-asan-configuration.md b/docs/linux/linux-asan-configuration.md index 127ad261d92..11c959116f9 100644 --- a/docs/linux/linux-asan-configuration.md +++ b/docs/linux/linux-asan-configuration.md @@ -2,6 +2,7 @@ title: "Configure Linux projects to use Address Sanitizer" description: "Describes how to configure C++ Linux projects in Visual Studio to use Address Sanitizer." ms.date: "10/7/2020" +ms.topic: how-to --- # Configure Linux projects to use Address Sanitizer @@ -20,7 +21,7 @@ ASan is a runtime memory error detector for C/C++ that catches the following err When ASan detects an error, it stops execution immediately. If you run an ASan-enabled program in the debugger, you see a message that describes the type of error, the memory address, and the location in the source file where the error occurred: - ![Screenshot showing an ASan error message.](media/asan-error.png) + ![Screenshot showing the address sanitizer error message: heap use after free.](media/asan-error.png) You can also view the full ASan output (including where the corrupted memory was allocated/deallocated) in the Debug pane of the output window. @@ -31,26 +32,26 @@ You can also view the full ASan output (including where the corrupted memory was To enable ASan for MSBuild-based Linux projects, right-click on the project in **Solution Explorer** and select **Properties**. Next, navigate to **Configuration Properties** > **C/C++** > **Sanitizers**. ASan is enabled via compiler and linker flags, and requires your project to be recompiled to work. -![Enable ASan for an MSBuild project.](media/msbuild-asan-prop-page.png) +![Screenshot of the project property page with Configuration Properties > C/C plus plus > Sanitizers selected. Enable Address Sanitizer is set to Yes.](media/msbuild-asan-prop-page.png) You can pass optional ASan runtime flags by navigating to **Configuration Properties** > **Debugging** > **AddressSanitizer Runtime Flags**. Click the down-arrow to add or remove flags. -![Configure ASan runtime flags.](media/msbuild-asan-runtime-flags.png) +![Screenshot of the project property page with Configuration Properties > Debugging selected. Address Sanitizer Runtime Flags is `detect_leaks = 0`.](media/msbuild-asan-runtime-flags.png) ## Enable ASan for Visual Studio CMake projects > [!NOTE] > To build with CMake Presets, first enable ASan in your CMakeLists.txt file. For more information, see [Enable AddressSanitizer for Windows and Linux](../build/cmake-presets-vs.md#enable-addresssanitizer-for-windows-and-linux). -To enable ASan for CMake, right-click on the CMakeLists.txt file in **Solution Explorer** and choose **CMake Settings for Project**. +To enable ASan for CMake, right-click on the `CMakeLists.txt` file in **Solution Explorer** and choose **CMake Settings for Project**. Make sure you have a Linux configuration (for example, **Linux-Debug**) selected in the left pane of the dialog: -![Screenshot of the left pane with Linux Debug listed as one of the Configuration options.](media/linux-debug-configuration.png) +![Screenshot of the Configurations pane with x64-Debug and Linux Debug listed as the options.](media/linux-debug-configuration.png) The ASan options are under **General**. Enter the ASan runtime flags in the format "flag=value", separated by spaces. The UI incorrectly suggests using semi-colons. Use spaces or colons to separate flags. -![Screenshot of the Enable Address Sanitizer option showing some Address Sanitizer run time flags.](media/cmake-settings-asan-options.png) +![Screenshot of the Enable Address Sanitizer option showing some Address Sanitizer run time flags like detect_leaks=0.](media/cmake-settings-asan-options.png) ## Install the ASan debug symbols diff --git a/docs/linux/media/connect-to-your-remote-linux-computer/connect-updated.png b/docs/linux/media/connect-to-your-remote-linux-computer/connect-updated.png new file mode 100644 index 00000000000..7c8bb50e8ab 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 00000000000..b3e8fee6ef8 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 00000000000..42b4e92a168 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 d4da0b9797e..cfeec7a3e27 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 7ca6c7ead41..00000000000 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 1ad440c8686..17eb4d3f002 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 00000000000..8a8baa1142d 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 5904de11ec7..00000000000 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 48fed59dbc2..9d9d1c23cd9 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 00000000000..befc41cb081 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 00000000000..a118df5a61a 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 00000000000..95e524bf70f 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 00000000000..16ea87e721b 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 00000000000..062b589e60b 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 00000000000..db9ab3b2225 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 e2571dfe45b..ccbea26f723 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 465474497cc..549f9cec33a 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 43d7f8787be..676aa732cbd 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 09c96b4892f..e6ca60889fd 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 6d0a0bba913..4b13726858e 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 00000000000..2f4ca5327eb --- /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 791a759d80e..c771087b836 100644 --- a/docs/linux/set-up-fips-compliant-secure-remote-linux-development.md +++ b/docs/linux/set-up-fips-compliant-secure-remote-linux-development.md @@ -1,7 +1,9 @@ --- title: "Set up FIPS-compliant secure remote Linux development" description: "How to set up a FIPS-compliant cryptographic connection between Visual Studio and a Linux machine for remote development." -ms.date: "01/17/2020" +ms.date: 07/06/2022 +ms.topic: how-to +ms.custom: sfi-image-nochange --- # Set up FIPS-compliant secure remote Linux development @@ -32,13 +34,13 @@ The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7. sudo service ssh start ``` -1. If you’d like the ssh server to start automatically when the system boots, enable it using systemctl: +1. If you'd like the `ssh` server to start automatically when the system boots, enable it using `systemctl`: ```bash sudo systemctl enable ssh ``` -1. Open */etc/ssh/sshd_config* as root. Edit (or add, if they don’t exist) the following lines: +1. Open *`/etc/ssh/sshd_config`* as root. Edit (or add, if they don't exist) the following lines: ```config Ciphers aes256-cbc,aes192-cbc,aes128-cbc,3des-cbc @@ -48,48 +50,48 @@ The examples in this article use Ubuntu 18.04 LTS with OpenSSH server version 7. ``` > [!NOTE] - > ssh-rsa is the only FIPS compliant host key algorithm VS supports. The aes\*-ctr algorithms are also FIPS compliant, but the implementation in Visual Studio isn't approved. The ecdh-\* key exchange algorithms are FIPS compliant, but Visual Studio doesn't support them. + > `ssh-rsa`, `rsa-sha2-*`, and `ecdsa-sha2-*` are the only FIPS compliant host key algorithms VS supports. For more information about the algorithms Visual Studio supports, see [Supported SSH Algorithms](connect-to-your-remote-linux-computer.md#supported-ssh-algorithms). - You're not limited to these options. You can configure ssh to use additional ciphers, host key algorithms, and so on. Some other relevant security options you may want to consider are `PermitRootLogin`, `PasswordAuthentication`, and `PermitEmptyPasswords`. For more information, see the man page for sshd_config or the article [SSH Server Configuration](https://www.ssh.com/ssh/sshd_config). + You're not limited to these options. You can configure `ssh` to use other ciphers, host key algorithms, and so on. Some other relevant security options you may want to consider are `PermitRootLogin`, `PasswordAuthentication`, and `PermitEmptyPasswords`. For more information, see the `man` page for `sshd_config` or the article [SSH Server Configuration](https://www.ssh.com/ssh/sshd_config). -1. After saving and closing sshd_config, restart the ssh server to apply the new configuration: +1. After saving and closing `sshd_config`, restart the ssh server to apply the new configuration: ```bash sudo service ssh restart ``` -Next, you'll create an RSA key pair on your Windows computer. Then you'll copy the public key to the remote Linux system for use by ssh. +Next, you'll create an ECDSA key pair on your Windows computer. Then you'll copy the public key to the remote Linux system for use by ssh. -### To create and use an RSA key file +### To create and use an ECDSA key file -1. On the Windows machine, generate a public/private RSA key pair by using this command: +1. On the Windows machine, generate a public/private ECDSA key pair by using this command: ```cmd - ssh-keygen -t rsa -b 4096 + ssh-keygen -t ecdsa -m PEM ``` - The command creates a public key and a private key. By default, the keys are saved to *%USERPROFILE%\\.ssh\\id_rsa* and *%USERPROFILE%\\.ssh\\id_rsa.pub*. (In Powershell, use `$env:USERPROFILE` instead of the cmd macro `%USERPROFILE%`) If you change the key name, use the changed name in the steps that follow. We recommend you use a passphrase for increased security. + The command creates a public key and a private key. By default, the keys are saved to %USERPROFILE%\.ssh\id_ecdsa and %USERPROFILE%\.ssh\id_ecdsa.pub. (In PowerShell, use $env:USERPROFILE instead of the cmd macro %USERPROFILE%) Keys generated with RSA are also supported. If you change the key name, use the changed name in the steps that follow. We recommend you use a passphrase for increased security. 1. From Windows, copy the public key to the Linux machine: ```cmd - scp %USERPROFILE%\.ssh\id_rsa.pub user@hostname: + scp %USERPROFILE%\.ssh\id_ecdsa.pub user@hostname: ``` 1. On the Linux system, add the key to the list of authorized keys, and ensure the file has the correct permissions: ```bash - cat ~/id_rsa.pub >> ~/.ssh/authorized_keys + cat ~/id_ecdsa.pub >> ~/.ssh/authorized_keys chmod 600 ~/.ssh/authorized_keys ``` -1. Now, you can test to see if the new key works in ssh. Use it to sign in from Windows: +1. Now, you can test to see if the new key works in `ssh`. Use it to sign in from Windows: ```cmd - ssh -i %USERPROFILE%\.ssh\id_rsa user@hostname + ssh -i %USERPROFILE%\.ssh\id_ecdsa user@hostname ``` -You've successfully set up ssh, created and deployed encryption keys, and tested your connection. Now you're ready to set up the Visual Studio connection. +You've successfully set up `ssh`, created and deployed encryption keys, and tested your connection. Now you're ready to set up the Visual Studio connection. ## Connect to the remote system in Visual Studio @@ -99,22 +101,22 @@ You've successfully set up ssh, created and deployed encryption keys, and tested 1. In the Connection Manager dialog, choose the **Add** button to add a new connection. - ![Screenshot showing the Connection Manager dialog.](media/settings_connectionmanager.png) + ![Screenshot showing the options pane in the Connection Manager dialog. Cross Platform > C plus plus > Connection Manager is highlighted.](media/settings_connectionmanager.png) The **Connect to Remote System** window is displayed. - ![Screenshot showing the Connect to Remote System window.](media/connect.png) + ![Screenshot showing the Connect to Remote System window, which has text boxes for the host name, port, user name, auth type, and password.](media/connect.png) 1. In the **Connect to Remote System** dialog, enter the connection details of your remote machine. - | Entry | Description - | ----- | --- - | **Host Name** | Name or IP address of your target device - | **Port** | Port that the SSH service is running on, typically 22 - | **User name** | User to authenticate as - | **Authentication type** | Choose Private Key for a FIPS-compliant connection - | **Private key file** | Private key file created for ssh connection - | **Passphrase** | Passphrase used with private key selected above + | Entry | Description | + |--|--| + | **Host Name** | Name or IP address of your target device | + | **Port** | Port that the SSH service is running on, typically 22 | + | **User name** | User to authenticate as | + | **Authentication type** | Choose **Private Key** for a FIPS-compliant connection | + | **Private key file** | Private key file created for ssh connection | + | **Passphrase** | Passphrase used with private key selected above | Change the authentication type to **Private Key**. Enter the path to your private key in the **Private key file** field. You can use the **Browse** button to navigate to your private key file instead. Then, enter the passphrase used to encrypt your private key file in the **Passphrase** field. @@ -124,19 +126,19 @@ You've successfully set up ssh, created and deployed encryption keys, and tested If the connection fails, the entry boxes that need to be changed are outlined in red. - ![Screenshot showing a Connection Manager Error.](media/settings_connectionmanagererror.png) + ![Screenshot of the Connect to Remote System window which has host name and port text boxes outlined in red to indicate they need to be changed.](media/settings_connectionmanagererror.png) For more information on troubleshooting your connection, see [Connect to your remote Linux computer](connect-to-your-remote-linux-computer.md). -## Command-line utility for the Connection Manager +## Command-line utility for the Connection Manager -**Visual Studio 2019 version 16.5 or later**: ConnectionManager.exe is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, you can use it to set up Visual Studio for continuous integration. For examples and a complete reference to the ConnectionManager command, see [ConnectionManager reference](connectionmanager-reference.md). +**Visual Studio 2019 version 16.5 or later**: `ConnectionManager.exe` is a command-line utility to manage remote development connections outside of Visual Studio. It's useful for tasks such as provisioning a new development machine. Or, you can use it to set up Visual Studio for continuous integration. For examples and a complete reference to the ConnectionManager command, see [ConnectionManager reference](connectionmanager-reference.md). ## Optional: Enable or disable FIPS mode It's possible to enable FIPS mode globally in Windows. -1. To enable FIPS mode, press **Windows+R** to open the Run dialog, and then run gpedit.msc. +1. To enable FIPS mode, press **Windows+R** to open the **Run** dialog, and then run `gpedit.msc`. 1. Expand **Local Computer Policy > Computer Configuration > Windows Settings > Security Settings > Local Policies** and select **Security Options**. @@ -145,7 +147,7 @@ It's possible to enable FIPS mode globally in Windows. 1. In the **Local Security Setting** tab, select **Enabled** or **Disabled**, and then choose **OK** to save your changes. > [!WARNING] -> Enabling FIPS mode may cause some applications to break or behave unexpectedly. For more information, see the blog post [Why We’re Not Recommending "FIPS mode" Anymore](https://techcommunity.microsoft.com/t5/microsoft-security-baselines/why-we-8217-re-not-recommending-8220-fips-mode-8221-anymore/ba-p/701037). +> Enabling FIPS mode may cause some applications to break or behave unexpectedly. ## Additional resources @@ -155,11 +157,9 @@ It's possible to enable FIPS mode globally in Windows. [Cryptographic Algorithm Validation Program: Validation Notes](https://csrc.nist.gov/projects/cryptographic-algorithm-validation-program/Validation-Notes) (from NIST) -Microsoft blog post on [Why We’re Not Recommending "FIPS mode" Anymore](https://techcommunity.microsoft.com/t5/microsoft-security-baselines/why-we-8217-re-not-recommending-8220-fips-mode-8221-anymore/ba-p/701037) - [SSH Server Configuration](https://www.ssh.com/ssh/sshd_config) -## See Also +## See also [Configure a Linux project](configure-a-linux-project.md)\ [Configure a Linux CMake project](cmake-linux-project.md)\ diff --git a/docs/linux/toc.yml b/docs/linux/toc.yml index 06e66952719..34c5c53245d 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/a-portrait-of-the-document-view-architecture.md b/docs/mfc/a-portrait-of-the-document-view-architecture.md index 2fa6b524004..de319b5b0da 100644 --- a/docs/mfc/a-portrait-of-the-document-view-architecture.md +++ b/docs/mfc/a-portrait-of-the-document-view-architecture.md @@ -3,10 +3,12 @@ description: "Learn more about: A Portrait of the Document/View Architecture" title: "A Portrait of the Document-View Architecture" ms.date: "11/04/2016" helpviewer_keywords: ["documents [MFC], views", "multiple views [MFC], updating from document", "document/view architecture [MFC]", "views [MFC], and user input", "documents [MFC], accessing data from view", "views [MFC], updating", "input [MFC], view class", "documents [MFC], multiple views", "document/view architecture [MFC], accessing data from view", "document/view architecture [MFC], about document/view architecture", "views [MFC], accessing document data from"] -ms.assetid: 4e7f65dc-b166-45d8-bcd5-9bb0d399b946 --- # A Portrait of the Document/View Architecture +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Documents and views are paired in a typical MFC application. Data is stored in the document, but the view has privileged access to the data. The separation of document from view separates the storage and maintenance of data from its display. ## Gaining Access to Document Data from the View diff --git a/docs/mfc/accessing-all-members-of-a-collection.md b/docs/mfc/accessing-all-members-of-a-collection.md index df7b900c87a..3ee1f74208c 100644 --- a/docs/mfc/accessing-all-members-of-a-collection.md +++ b/docs/mfc/accessing-all-members-of-a-collection.md @@ -3,10 +3,13 @@ description: "Learn more about: Accessing All Members of a Collection" title: "Accessing All Members of a Collection" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, collections", "enumerations [MFC]", "enumerating collections [MFC]", "collections [MFC], accessing", "collection classes [MFC]", ", ", ", ", ", ", ", ", ", ", ", ", ", "] -ms.assetid: 7bbae518-062e-4393-81f9-b22abd2e5f59 +ms.topic: how-to --- # Accessing All Members of a Collection +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The MFC array collection classes — both template-based and not — use indexes to access their elements. The MFC list and map collection classes — both template-based and not — use an indicator of type **POSITION** to describe a given position within the collection. To access one or more members of these collections, you first initialize the position indicator and then repeatedly pass that position to the collection and ask it to return the next element. The collection is not responsible for maintaining state information about the progress of the iteration. That information is kept in the position indicator. But, given a particular position, the collection is responsible for returning the next element. The following procedures show how to iterate over the three main types of collections provided with MFC: diff --git a/docs/mfc/accessing-file-status.md b/docs/mfc/accessing-file-status.md index e6b649aa51d..6e75ed88b8d 100644 --- a/docs/mfc/accessing-file-status.md +++ b/docs/mfc/accessing-file-status.md @@ -3,10 +3,13 @@ description: "Learn more about: Accessing File Status" title: "Accessing File Status" ms.date: "11/04/2016" helpviewer_keywords: ["files [MFC], status information", "examples [MFC], file status", "files [MFC], accessing", "file status [MFC]", "status of files [MFC]"] -ms.assetid: 1b8891d6-eb0f-4037-a837-4928fe595222 +ms.topic: how-to --- # Accessing File Status +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CFile` also supports getting file status, including whether the file exists, creation and modification dates and times, logical size, and path. ### To get file status diff --git a/docs/mfc/accessing-run-time-class-information.md b/docs/mfc/accessing-run-time-class-information.md index b0fd0b53c76..167bf60b463 100644 --- a/docs/mfc/accessing-run-time-class-information.md +++ b/docs/mfc/accessing-run-time-class-information.md @@ -3,10 +3,13 @@ description: "Learn more about: Accessing Run-Time Class Information" title: "Accessing Run-Time Class Information" ms.date: "11/04/2016" helpviewer_keywords: ["CObject class [MFC], and RTTI", "CObject class [MFC], using IsKindOf method [MFC]", "run time [MFC], class information", "RUNTIME_CLASS macro [MFC]", "CObject class [MFC], using RUNTIME_CLASS macro [MFC]", "RTTI compiler option [MFC]", "CObject class [MFC], accessing run-time class information", "run time [MFC]", "IsKindOf method method [MFC]", "run-time class [MFC], accessing information", "classes [MFC], run-time class information", "run-time class [MFC]", "RUNTIME_CLASS macro, using"] -ms.assetid: 3445a9af-0bd6-4496-95c3-aa59b964570b +ms.topic: how-to --- # Accessing Run-Time Class Information +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to access information about the class of an object at run time. > [!NOTE] @@ -33,7 +36,7 @@ You will rarely need to access the run-time class object directly. A more common 1. Call the `IsKindOf` member function for objects of that class, using the `RUNTIME_CLASS` macro to generate the `CRuntimeClass` argument, as shown here: [!code-cpp[NVC_MFCCObjectSample#2](codesnippet/cpp/accessing-run-time-class-information_2.h)] - +   [!code-cpp[NVC_MFCCObjectSample#5](codesnippet/cpp/accessing-run-time-class-information_3.cpp)] > [!NOTE] diff --git a/docs/mfc/accessing-the-embedded-month-calendar-control.md b/docs/mfc/accessing-the-embedded-month-calendar-control.md index 05c19058476..d325e55ce73 100644 --- a/docs/mfc/accessing-the-embedded-month-calendar-control.md +++ b/docs/mfc/accessing-the-embedded-month-calendar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Accessing the Embedded Month Calendar Control" title: "Accessing the Embedded Month Calendar Control" ms.date: "11/04/2016" helpviewer_keywords: ["DateTimePicker control [MFC], accessing month calendar", "CDateTimeCtrl class [MFC], accessing embedded control", "month calendar controls [MFC], embedded in date/time picker", "CMonthCalCtrl class [MFC], changing the font", "month calendar controls [MFC], changing the font", "DateTimePicker control [MFC]"] -ms.assetid: 355e97ed-cf81-4df3-a2f8-9ddbbde93227 +ms.topic: concept-article --- # Accessing the Embedded Month Calendar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The embedded month calendar control object can be accessed from the `CDateTimeCtrl` object with a call to the [GetMonthCalCtrl](reference/cdatetimectrl-class.md#getmonthcalctrl) member function. > [!NOTE] diff --git a/docs/mfc/activation-cpp.md b/docs/mfc/activation-cpp.md index 89aafcdbd30..d40b7871b57 100644 --- a/docs/mfc/activation-cpp.md +++ b/docs/mfc/activation-cpp.md @@ -3,10 +3,12 @@ description: "Learn more about: Activation (C++)" title: "Activation (C++)" ms.date: "11/04/2016" helpviewer_keywords: ["OLE server applications [MFC], activation", "OLE items [MFC], visual editing", "activation [MFC]", "OLE [MFC], in-place activation", "OLE [MFC], activation", "in-place activation, embedded and linked items", "activating objects", "visual editing, activation", "visual editing", "documents [MFC], OLE", "embedded objects [MFC]", "OLE [MFC], editing", "in-place activation", "activation [MFC], embedded OLE items", "OLE activation [MFC]"] -ms.assetid: ed8357d9-e487-4aaa-aa6b-2edc4de25dfa --- # Activation (C++) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the role of activation in the visual editing of OLE items. After a user has embedded an OLE item in a container document, it may need to be used. To do this, the user double-clicks the item, which activates that item. The most frequent activity for activation is editing. Many current OLE items, when activated for editing, cause the menus and toolbars in the current frame window to change to reflect those belonging to the server application that created the item. This behavior, known as in-place activation, allows the user to edit any embedded item in a compound document without leaving the container document's window. It is also possible to edit embedded OLE items in a separate window. This will happen if either the container or server application does not support in-place activation. In this case, when the user double-clicks an embedded item, the server application is launched in a separate window and the embedded item appears as its own document. The user edits the item in this window. When editing is complete, the user closes the server application and returns to the container application. diff --git a/docs/mfc/activation-verbs.md b/docs/mfc/activation-verbs.md index 5c97e74cb58..44f8e4f2030 100644 --- a/docs/mfc/activation-verbs.md +++ b/docs/mfc/activation-verbs.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the role primary and secondary verbs play in OLE [activation](activation-cpp.md). Usually, double-clicking an embedded item allows the user to edit it. However, certain items do not behave this way. For example, double-clicking an item created with the Sound Recorder application does not open the server in a separate window; instead, it plays the sound. diff --git a/docs/mfc/active-document-classes.md b/docs/mfc/active-document-classes.md index b5d917abefd..2e21e90ff3e 100644 --- a/docs/mfc/active-document-classes.md +++ b/docs/mfc/active-document-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Active Document Classes" title: "Active Document Classes" ms.date: "11/04/2016" helpviewer_keywords: ["Active document classes [MFC]"] -ms.assetid: cc20af37-b658-406d-8148-7670737f4c03 --- # Active Document Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Active documents can be displayed either in the entire client window of a Web browser, such as Internet Explorer 5.5, or in an Active container, such as the Microsoft Office Binder, that supports Active documents. [CDocObjectServer](reference/cdocobjectserver-class.md)
diff --git a/docs/mfc/active-document-containers.md b/docs/mfc/active-document-containers.md index 1a73274136f..04fd6aedac2 100644 --- a/docs/mfc/active-document-containers.md +++ b/docs/mfc/active-document-containers.md @@ -3,10 +3,12 @@ description: "Learn more about: Active Document Containers" title: "Active Document Containers" ms.date: "11/19/2018" helpviewer_keywords: ["active documents [MFC], containers", "active document containers [MFC]", "containers [MFC], active document", "MFC COM, active document containment"] -ms.assetid: ba20183a-8b4c-440f-9031-e5fcc41d391b --- # Active Document Containers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An active document container, such as Microsoft Office Binder or Internet Explorer, allows you to work with several documents of different application types within a single frame (instead of forcing you to create and use multiple application frames for each document type). MFC provides full support for active document containers in the `COleDocObjectItem` class. You can use the MFC Application Wizard to create an active document container by selecting the **Active document container** check box on the **Compound Document Support** page of the MFC Application Wizard. For more information, see [Creating an Active Document Container Application](creating-an-active-document-container-application.md). diff --git a/docs/mfc/active-document-containment.md b/docs/mfc/active-document-containment.md index 0220c7fe079..457e75cb97b 100644 --- a/docs/mfc/active-document-containment.md +++ b/docs/mfc/active-document-containment.md @@ -3,10 +3,12 @@ description: "Learn more about: Active Document Containment" title: "Active Document Containment" ms.date: "11/04/2016" helpviewer_keywords: ["active documents [MFC], containers", "containers [MFC], active document", "MFC, COM support", "active document containers [MFC], about active document containers", "MFC COM, active document containment"] -ms.assetid: b8dfa74b-75ce-47df-b75e-fc87b7f7d687 --- # Active Document Containment +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Active document containment is a technology that provides a single frame in which to work with documents, instead of forcing you to create and use multiple application frames for each document type. It differs from basic OLE technology in that OLE works with embedded objects within a compound document in which only a single piece of content can be active. With active document containment, you activate an entire document (that is, an entire application, including associated menus, toolbars, and so on) within the context of a single frame. The active document containment technology was originally developed for Microsoft Office to implement Office Binder. However, the technology is flexible enough to support active document containers other than Office Binder and can support document servers other than Office and Office-compatible applications. diff --git a/docs/mfc/active-document-servers.md b/docs/mfc/active-document-servers.md index e277d81825e..441a9c8f1be 100644 --- a/docs/mfc/active-document-servers.md +++ b/docs/mfc/active-document-servers.md @@ -3,10 +3,12 @@ description: "Learn more about: Active Document Servers" title: "Active Document Servers" ms.date: "11/04/2016" helpviewer_keywords: ["active documents [MFC], servers", "servers [MFC], active document", "active document servers [MFC]"] -ms.assetid: 131fec1e-02a0-4305-a7ab-903b911232a7 --- # Active Document Servers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Active document servers such as Word, Excel, or PowerPoint host documents of other application types called active documents. Unlike OLE embedded objects (which are simply displayed within the page of another document), Active documents provide the full interface and complete native functionality of the server application that creates them. Users can create documents using the full power of their favorite applications (if they are active document enabled), yet can treat the resulting project as a single entity. Active documents can have more than one page and are always in-place active. Active documents control part of the user interface, merging their menus with the **File** and **Help** menus of the container. They occupy the entire editing area of the container and control the views and the layout of the printer page (margins, footers, and so on). diff --git a/docs/mfc/active-documents.md b/docs/mfc/active-documents.md index bbaebd0e747..235ed0d653c 100644 --- a/docs/mfc/active-documents.md +++ b/docs/mfc/active-documents.md @@ -3,10 +3,12 @@ description: "Learn more about: Active Documents" title: "Active Documents" ms.date: "11/04/2016" helpviewer_keywords: ["active documents [MFC]", "active documents [MFC], requirements", "view objects [MFC], requirements", "OLE [MFC], active documents", "views [MFC], active documents", "active documents [MFC], views"] -ms.assetid: 1378f18e-aaa6-420b-8501-4b974905baa0 --- # Active Documents +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Active documents extend the compound document technology of OLE. These extensions are provided in the form of additional interfaces that manage views, so that objects can function within containers and yet retain control over their display and printing functions. This process makes it possible to display documents both in foreign frames (such as the Microsoft Office Binder or Microsoft Internet Explorer) and in native frames (such as the product's own view ports). This section describes the functional [requirements for active documents](#requirements_for_active_documents). The active document owns a set of data and has access to storage where the data can be saved and retrieved. It can create and manage one or more views on its data. In addition to supporting the usual embedding and in-place activation interfaces of OLE documents, the active document communicates its ability to create views through `IOleDocument`. Through this interface, the container can ask to create (and possibly enumerate) the views that the active document can display. Through this interface, the active document can also provide miscellaneous information about itself, such as whether it supports multiple views or complex rectangles. diff --git a/docs/mfc/active-technology-on-the-internet.md b/docs/mfc/active-technology-on-the-internet.md index 6a0a0ae5513..18e010b6426 100644 --- a/docs/mfc/active-technology-on-the-internet.md +++ b/docs/mfc/active-technology-on-the-internet.md @@ -3,10 +3,12 @@ description: "Learn more about: Active Technology on the Internet" title: "Active Technology on the Internet" ms.date: "09/12/2018" helpviewer_keywords: ["Internet applications [MFC], Active technology"] -ms.assetid: 6f782aa1-5c2f-47a2-9e63-ddd0829d5a08 --- # Active Technology on the Internet +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Active technology is an open platform that lets developers create exciting, dynamic content and applications for the global Internet, or for a company's internal network, known as an intranet. The major technologies provided by Microsoft for Internet programming are described below. >[!IMPORTANT] diff --git a/docs/mfc/activex-control-containers-connecting-an-activex-control-to-a-member-variable.md b/docs/mfc/activex-control-containers-connecting-an-activex-control-to-a-member-variable.md index 1fa92bf4510..cd88ec1938a 100644 --- a/docs/mfc/activex-control-containers-connecting-an-activex-control-to-a-member-variable.md +++ b/docs/mfc/activex-control-containers-connecting-an-activex-control-to-a-member-variable.md @@ -3,10 +3,12 @@ description: "Learn more about: ActiveX Control Containers: Connecting an Active title: "ActiveX Control Containers: Connecting an ActiveX Control to a Member Variable" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX control containers [MFC], accessing ActiveX controls", "ActiveX controls [MFC], member variables of project", "connecting ActiveX controls to container member variables", "ActiveX controls [MFC], accessing", "member variables [MFC], ActiveX controls in project", "ActiveX control containers [MFC], ActiveX controls as member variables"] -ms.assetid: 7898a336-440d-4a60-be43-cb062b807aee --- # ActiveX Control Containers: Connecting an ActiveX Control to a Member Variable +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The easiest way to access an ActiveX control from within its control container application is to associate the ActiveX control with a member variable of the dialog class that will contain the control. > [!NOTE] diff --git a/docs/mfc/activex-control-containers-handling-events-from-an-activex-control.md b/docs/mfc/activex-control-containers-handling-events-from-an-activex-control.md index 5052a8c4c3d..acd9cb66f89 100644 --- a/docs/mfc/activex-control-containers-handling-events-from-an-activex-control.md +++ b/docs/mfc/activex-control-containers-handling-events-from-an-activex-control.md @@ -3,10 +3,12 @@ description: "Learn more about: ActiveX Control Containers: Handling Events from title: "ActiveX Control Containers: Handling Events from an ActiveX Control" ms.date: "09/12/2018" helpviewer_keywords: ["event handlers [MFC], ActiveX controls", "ActiveX control containers [MFC], event sinks", "event handling [MFC], ActiveX controls", "ON_EVENT macro [MFC]", "ActiveX controls [MFC], events [MFC]", "END_EVENTSINK_MAP macro, using", "events [MFC], ActiveX controls", "BEGIN_EVENTSINK_MAP macro"] -ms.assetid: f9c106db-052f-4e32-82ad-750646aa760b --- # ActiveX Control Containers: Handling Events from an ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses using the **Properties** window (in **Class View**) to install event handlers for ActiveX controls in an ActiveX control container. The event handlers are used to receive notifications (from the control) of certain events and perform some action in response. This notification is called "firing" the event. >[!IMPORTANT] @@ -15,7 +17,7 @@ This article discusses using the **Properties** window (in **Class View**) to in > [!NOTE] > This article uses a dialog-based ActiveX control container project named Container and an embedded control named Circ as examples in the procedures and code. -Using the Events button in the **Properties** window (in **Class View**), you can create a map of events that can occur in your ActiveX control container application. This map, called an "event sink map,'' is created and maintained by Visual C++ when you add event handlers to the control container class. Each event handler, implemented with an event map entry, maps a specific event to a container event handler member function. This event handler function is called when the specified event is fired by the ActiveX control object. +Using the Events button in the **Properties** window (in **Class View**), you can create a map of events that can occur in your ActiveX control container application. This map, called an "event sink map,'' is created and maintained by Visual Studio when you add event handlers to the control container class. Each event handler, implemented with an event map entry, maps a specific event to a container event handler member function. This event handler function is called when the specified event is fired by the ActiveX control object. For more information on event sink maps, see [Event Sink Maps](reference/event-sink-maps.md) in the *Class Library Reference*. diff --git a/docs/mfc/activex-control-containers-manually-enabling-activex-control-containment.md b/docs/mfc/activex-control-containers-manually-enabling-activex-control-containment.md index f4e37044710..f7cb6480473 100644 --- a/docs/mfc/activex-control-containers-manually-enabling-activex-control-containment.md +++ b/docs/mfc/activex-control-containers-manually-enabling-activex-control-containment.md @@ -3,10 +3,12 @@ description: "Learn more about: ActiveX Control Containers: Manually Enabling Ac title: "ActiveX Control Containers: Manually Enabling ActiveX Control Containment" ms.date: "09/12/2018" helpviewer_keywords: ["AfxEnableControlContainer method [MFC]", "ActiveX control containers [MFC], enabling", "ActiveX controls [MFC], enabling containers"] -ms.assetid: 833bcde9-c9ad-4709-ad12-2fc2150fb6a5 --- # ActiveX Control Containers: Manually Enabling ActiveX Control Containment +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you did not enable ActiveX control support when you used the MFC Application Wizard to generate your application, you will have to add this support manually. This article describes the process for manually adding ActiveX control containment to an existing OLE container application. If you know in advance that you want ActiveX control support in your OLE container, see the article [Creating an MFC ActiveX Control Container](reference/creating-an-mfc-activex-control-container.md). >[!IMPORTANT] diff --git a/docs/mfc/activex-control-containers-using-controls-in-a-non-dialog-container.md b/docs/mfc/activex-control-containers-using-controls-in-a-non-dialog-container.md index 9c54a250016..516e4ac55a1 100644 --- a/docs/mfc/activex-control-containers-using-controls-in-a-non-dialog-container.md +++ b/docs/mfc/activex-control-containers-using-controls-in-a-non-dialog-container.md @@ -3,11 +3,13 @@ description: "Learn more about: ActiveX Control Containers: Using Controls in a title: "ActiveX Control Containers: Using Controls in a Non-Dialog Container" ms.date: "11/04/2016" helpviewer_keywords: ["Create method [MFC], ActiveX controls", "CreateControl method [MFC]", "ActiveX controls [MFC], creating", "ActiveX control containers [MFC], non-dialog containers", "ActiveX control containers [MFC], inserting controls"] -ms.assetid: 46f195b0-b8ca-4409-8cca-fbfaf2c9ab9f --- # ActiveX Control Containers: Using Controls in a Non-Dialog Container -In some applications, such as an SDI or MDI application, you will want to embed a control in a window of the application. The **Create** member function of the wrapper class, inserted by Visual C++, can create an instance of the control dynamically, without the need for a dialog box. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +In some applications, such as an SDI or MDI application, you will want to embed a control in a window of the application. The **Create** member function of the wrapper class, inserted by Visual Studio, can create an instance of the control dynamically, without the need for a dialog box. The **Create** member function has the following parameters: diff --git a/docs/mfc/activex-control-containers-viewing-and-modifying-control-properties.md b/docs/mfc/activex-control-containers-viewing-and-modifying-control-properties.md index a9609867536..201a108b84d 100644 --- a/docs/mfc/activex-control-containers-viewing-and-modifying-control-properties.md +++ b/docs/mfc/activex-control-containers-viewing-and-modifying-control-properties.md @@ -3,11 +3,13 @@ description: "Learn more about: ActiveX Control Containers: Viewing and Modifyin title: "ActiveX Control Containers: Viewing and Modifying Control Properties" ms.date: "11/04/2016" helpviewer_keywords: ["properties [MFC], viewing and modifying", "ActiveX control containers [MFC], viewing and modifying properties", "resource editors, viewing and modifying ActiveX controls", "ActiveX controls [MFC], properties", "controls [MFC], properties"] -ms.assetid: 14ce5152-742b-4e0d-a9ab-c7b456e32918 --- # ActiveX Control Containers: Viewing and Modifying Control Properties -When you insert an ActiveX control into a project, it is useful to view and change the properties supported by the ActiveX control. This article discusses how to use the Visual C++ resource editor to do this. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +When you insert an ActiveX control into a project, it is useful to view and change the properties supported by the ActiveX control. This article discusses how to use the Visual Studio resource editor to do this. If your ActiveX control container application uses embedded controls, you can view and modify the control's properties while in the resource editor. You can also use the resource editor to set property values during design time. The resource editor then automatically saves these values in the project's resource file. Any instance of the control will then have its properties initialized to these values. diff --git a/docs/mfc/activex-control-containers.md b/docs/mfc/activex-control-containers.md index 0201f13955c..30261c43b4f 100644 --- a/docs/mfc/activex-control-containers.md +++ b/docs/mfc/activex-control-containers.md @@ -3,10 +3,12 @@ description: "Learn more about: ActiveX Control Containers" title: "ActiveX Control Containers" ms.date: "09/12/2018" helpviewer_keywords: ["ActiveX control containers [MFC]", "OLE controls [MFC], containers"] -ms.assetid: 0eb1a713-e607-4c79-a0c7-67c5f1fd5fab --- # ActiveX Control Containers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An ActiveX control container is a container that fully supports ActiveX controls and can incorporate them into its own windows or dialogs. An ActiveX control is a reusable software element that you can use in many development projects. Controls allow your application's user to access databases, monitor data, and make various selections within your applications. For more information on ActiveX controls, see the article [MFC ActiveX Controls](mfc-activex-controls.md). >[!IMPORTANT] @@ -20,7 +22,7 @@ Control containers typically take two forms in a project: The ActiveX control container interacts with the control via exposed [methods](mfc-activex-controls-methods.md) and [properties](mfc-activex-controls-properties.md). These methods and properties, which can be accessed and modified by the control container, are accessed through a wrapper class in the ActiveX control container project. The embedded ActiveX control can also interact with the container by firing (sending) [events](mfc-activex-controls-events.md) to notify the container that an action has occurred. The control container can choose to act upon these notifications or not. -Additional articles discuss several topics, from creating an ActiveX control container project to basic implementation issues related to ActiveX control containers built with Visual C++: +Additional articles discuss several topics, from creating an ActiveX control container project to basic implementation issues related to ActiveX control containers built with Visual Studio: - [Creating an MFC ActiveX Control Container](reference/creating-an-mfc-activex-control-container.md) @@ -42,7 +44,7 @@ Additional articles discuss several topics, from creating an ActiveX control con For more information about using ActiveX controls in a dialog box, see the [Dialog Editor](../windows/dialog-editor.md) topics. -For a list of articles that explain the details of developing ActiveX controls using Visual C++ and the MFC ActiveX control classes, see [MFC ActiveX controls](mfc-activex-controls.md). The articles are grouped by functional categories. +For a list of articles that explain the details of developing ActiveX controls using Visual Studio and the MFC ActiveX control classes, see [MFC ActiveX controls](mfc-activex-controls.md). The articles are grouped by functional categories. ## See also diff --git a/docs/mfc/activex-controls-on-the-internet.md b/docs/mfc/activex-controls-on-the-internet.md index 9a73da8ce82..915bab82eb5 100644 --- a/docs/mfc/activex-controls-on-the-internet.md +++ b/docs/mfc/activex-controls-on-the-internet.md @@ -3,10 +3,12 @@ description: "Learn more about: ActiveX Controls on the Internet" title: "ActiveX Controls on the Internet" ms.date: "09/12/2018" helpviewer_keywords: ["ActiveX controls [MFC], creating", "ActiveX controls [MFC], Internet", "downloading data with ActiveX controls", "OLE controls [MFC], upgrading to ActiveX", "Internet applications [MFC], ActiveX controls", "networks [MFC], downloading with ActiveX controls"] -ms.assetid: 7ab943c8-2022-41df-9065-d629b616eeec --- # ActiveX Controls on the Internet +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + ActiveX controls are the updated version of the OLE control specification. >[!IMPORTANT] diff --git a/docs/mfc/activex-controls.md b/docs/mfc/activex-controls.md index af9ca221c6c..936df4c4773 100644 --- a/docs/mfc/activex-controls.md +++ b/docs/mfc/activex-controls.md @@ -3,17 +3,18 @@ description: "Learn more about: ActiveX Controls" title: "ActiveX Controls" ms.date: "09/12/2018" helpviewer_keywords: ["ActiveX controls [MFC]"] -ms.assetid: 52aaec4d-3889-402e-b57d-758078f8ac57 --- # ActiveX Controls -In Visual C++ you can create ActiveX controls using MFC or ATL. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library and Active Template Library (ATL) continue to be supported. However, we're no longer adding features or updating the documentation. + +In Visual Studio you can create ActiveX controls using MFC or ATL. >[!IMPORTANT] > ActiveX is a legacy technology that should not be used for new development. Many capabilities of ActiveX controls can be performed in a simpler and much more secure way with modern technologies such as HTML5 and JavaScript, modern browser extensions, or WebAssembly modules. For more information, see [A break from the past, part 2: Saying goodbye to ActiveX, VBScript, attachEvent](https://blogs.windows.com/msedgedev/2015/05/06/a-break-from-the-past-part-2-saying-goodbye-to-activex-vbscript-attachevent/) and [Native Messaging](/microsoft-edge/extensions/guides/native-messaging) and [Microsoft Edge extensions](/microsoft-edge/extensions) and [WebAssembly](https://webassembly.org/). - [MFC ActiveX Controls](mfc-activex-controls.md) - - [ATL](../atl/active-template-library-atl-concepts.md) ## See also diff --git a/docs/mfc/adding-columns-to-the-control-report-view.md b/docs/mfc/adding-columns-to-the-control-report-view.md index a2bf092bca5..825e9915515 100644 --- a/docs/mfc/adding-columns-to-the-control-report-view.md +++ b/docs/mfc/adding-columns-to-the-control-report-view.md @@ -3,10 +3,13 @@ description: "Learn more about: Adding Columns to the Control (Report View)" title: "Adding Columns to the Control (Report View)" ms.date: "11/04/2016" helpviewer_keywords: ["CListCtrl class [MFC], adding columns", "report view in CListCtrl class [MFC]", "views [MFC], report", "columns [MFC], adding to CListCtrl", "CListCtrl class [MFC], report view"] -ms.assetid: 7392c0d7-f8a5-4e7b-9ae7-b53dc9dd80ae +ms.topic: concept-article --- # Adding Columns to the Control (Report View) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following procedure applies to either a [CListView](reference/clistview-class.md) or [CListCtrl](reference/clistctrl-class.md) object. diff --git a/docs/mfc/adding-controls-by-hand.md b/docs/mfc/adding-controls-by-hand.md index 74ae5dee489..1ccec0f6760 100644 --- a/docs/mfc/adding-controls-by-hand.md +++ b/docs/mfc/adding-controls-by-hand.md @@ -3,10 +3,13 @@ description: "Learn more about: Adding Controls By Hand" title: "Adding Controls By Hand" ms.date: "11/04/2016" helpviewer_keywords: ["Windows common controls [MFC], adding", "dialog box controls [MFC], adding to dialog boxes", "controlling input focus", "input focus control", "focus, controlling input [MFC]", "controls [MFC], adding to dialog boxes", "common controls [MFC], adding"] -ms.assetid: bc843e59-0c51-4b5b-8bf2-343f716469d2 +ms.topic: concept-article --- # Adding Controls By Hand +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can either [add controls to a dialog box with the dialog editor](using-the-dialog-editor-to-add-controls.md) or add them yourself, with code. To create a control object yourself, you will usually embed the C++ control object in a C++ dialog or frame-window object. Like many other objects in the framework, controls require two-stage construction. You should call the control's **Create** member function as part of creating the parent dialog box or frame window. For dialog boxes, this is usually done in [OnInitDialog](reference/cdialog-class.md#oninitdialog), and for frame windows, in [OnCreate](reference/cwnd-class.md#oncreate). diff --git a/docs/mfc/adding-controls-to-a-property-sheet.md b/docs/mfc/adding-controls-to-a-property-sheet.md index b11b5c5177d..c9f162f38b7 100644 --- a/docs/mfc/adding-controls-to-a-property-sheet.md +++ b/docs/mfc/adding-controls-to-a-property-sheet.md @@ -3,10 +3,13 @@ description: "Learn more about: Adding Controls to a Property Sheet" title: "Adding Controls to a Property Sheet" ms.date: "11/04/2016" helpviewer_keywords: ["controls [MFC], adding to property sheets", "property sheets, adding controls"] -ms.assetid: 24ad4c0b-c1db-4850-b9f0-34aae8d74571 +ms.topic: concept-article --- # Adding Controls to a Property Sheet +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By default, a property sheet allocates window area for the property pages, the tab index, and the OK, Cancel, and Apply buttons. (A modeless property sheet does not have the OK, Cancel, and Apply buttons.) You can add other controls to the property sheet. For example, you can add a preview window to the right of the property page area to show the user what the current settings would look like if applied to an external object. You can add controls to the property sheet dialog in the `OnCreate` handler. Accommodating additional controls usually requires expanding the size of the property sheet dialog. After calling the base class **CPropertySheet::OnCreate**, call [GetWindowRect](reference/cwnd-class.md#getwindowrect) to get the width and height of the currently allocated property sheet window, expand the rectangle's dimensions, and call [MoveWindow](reference/cwnd-class.md#movewindow) to change the size of the property sheet window. diff --git a/docs/mfc/adding-items-to-the-control.md b/docs/mfc/adding-items-to-the-control.md index 4f98db97a09..8d8a14a0003 100644 --- a/docs/mfc/adding-items-to-the-control.md +++ b/docs/mfc/adding-items-to-the-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Adding Items to the Control" title: "Adding Items to the Control" ms.date: "11/04/2016" helpviewer_keywords: ["CListCtrl class [MFC], adding items"] -ms.assetid: 715994bd-340d-4ad2-9882-411654137830 +ms.topic: concept-article --- # Adding Items to the Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To add items to the list control ([CListCtrl](reference/clistctrl-class.md)), call one of several versions of the [InsertItem](reference/clistctrl-class.md#insertitem) member function, depending on what information you have. One version takes a [LVITEM](/windows/win32/api/commctrl/ns-commctrl-lvitemw) structure that you prepare. Because the `LVITEM` structure contains numerous members, you have greater control over the attributes of the list control item. Two important members (in regard to the report view) of the `LVITEM` structure are the `iItem` and `iSubItem` members. The `iItem` member is the zero-based index of the item the structure is referencing and the `iSubItem` member is the one-based index of a subitem, or zero if the structure contains information about an item. With these two members you determine, per item, the type and value of subitem information that is displayed when the list control is in report view. For more information, see [CListCtrl::SetItem](reference/clistctrl-class.md#setitem). diff --git a/docs/mfc/adding-items-to-the-header-control.md b/docs/mfc/adding-items-to-the-header-control.md index 6b7b7469978..359e8a45b4f 100644 --- a/docs/mfc/adding-items-to-the-header-control.md +++ b/docs/mfc/adding-items-to-the-header-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Adding Items to the Header Control" title: "Adding Items to the Header Control" ms.date: "11/04/2016" helpviewer_keywords: ["controls [MFC], header", "CHeaderCtrl class [MFC], adding items", "header controls [MFC], adding items to"] -ms.assetid: 2e9a28b1-7302-4a93-8037-c5a4183e589a +ms.topic: how-to --- # Adding Items to the Header Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + After creating your header control ([CHeaderCtrl](reference/cheaderctrl-class.md)) in its parent window, add as many "header items" as you need: usually one per column. ### To add a header item diff --git a/docs/mfc/adding-multiple-views-to-a-single-document.md b/docs/mfc/adding-multiple-views-to-a-single-document.md index 1f808c9a0e8..500f35c74f9 100644 --- a/docs/mfc/adding-multiple-views-to-a-single-document.md +++ b/docs/mfc/adding-multiple-views-to-a-single-document.md @@ -3,10 +3,13 @@ description: "Learn more about: Adding Multiple Views to a Single Document" title: "Adding Multiple Views to a Single Document" ms.date: "11/04/2016" helpviewer_keywords: ["multiple views [MFC], SDI applications", "documents [MFC], multiple views", "single document interface (SDI), adding views", "views [MFC], SDI applications"] -ms.assetid: 86d0c134-01d5-429c-b672-36cfb956dc01 +ms.topic: concept-article --- # Adding Multiple Views to a Single Document +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In a single-document interface (SDI) application created with the Microsoft Foundation Class (MFC) Library, each document type is associated with a single view type. In some cases, it is desirable to have the ability to switch the current view of a document with a new view. > [!TIP] diff --git a/docs/mfc/adding-tabs-to-a-tab-control.md b/docs/mfc/adding-tabs-to-a-tab-control.md index c0d93509083..860f6ce1ea2 100644 --- a/docs/mfc/adding-tabs-to-a-tab-control.md +++ b/docs/mfc/adding-tabs-to-a-tab-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Adding Tabs to a Tab Control" title: "Adding Tabs to a Tab Control" ms.date: "11/04/2016" helpviewer_keywords: ["tab controls [MFC], adding tabs", "putting tabs on CTabCtrls [MFC]", "CTabCtrl class [MFC], adding tabs", "tabs [MFC], adding to CTabCtrl class [MFC]"] -ms.assetid: 7f3d9340-e3c7-4c71-9912-be57534ecc78 +ms.topic: how-to --- # Adding Tabs to a Tab Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + After creating the tab control ([CTabCtrl](reference/ctabctrl-class.md)), add as many tabs as you need. ### To add a tab item diff --git a/docs/mfc/advantages-of-the-document-view-architecture.md b/docs/mfc/advantages-of-the-document-view-architecture.md index 68755dbc77f..5baaa817716 100644 --- a/docs/mfc/advantages-of-the-document-view-architecture.md +++ b/docs/mfc/advantages-of-the-document-view-architecture.md @@ -3,10 +3,12 @@ description: "Learn more about: Advantages of the Document/View Architecture" title: "Advantages of the Document-View Architecture" ms.date: "11/04/2016" helpviewer_keywords: ["views [MFC], advantages", "document/view architecture [MFC], advantages of"] -ms.assetid: 0bc27071-e120-4889-939c-ce1e61fb9cb3 --- # Advantages of the Document/View Architecture +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The key advantage to using the MFC document/view architecture is that the architecture supports multiple views of the same document particularly well. (If you don't need multiple views and the small overhead of document/view is excessive in your application, you can avoid the architecture. [Alternatives to the Document/View Architecture](alternatives-to-the-document-view-architecture.md).) Suppose your application lets users view numerical data either in spreadsheet form or in chart form. A user might want to see simultaneously both the raw data, in spreadsheet form, and a chart that results from the data. You display these separate views in separate frame windows or in splitter panes within a single window. Now suppose the user can edit the data in the spreadsheet and see the changes instantly reflected in the chart. diff --git a/docs/mfc/allocating-and-deallocating-window-memory.md b/docs/mfc/allocating-and-deallocating-window-memory.md index f3992156864..c8fb0b9f318 100644 --- a/docs/mfc/allocating-and-deallocating-window-memory.md +++ b/docs/mfc/allocating-and-deallocating-window-memory.md @@ -3,10 +3,13 @@ description: "Learn more about: Allocating and Deallocating Window Memory" title: "Allocating and Deallocating Window Memory" ms.date: "11/04/2016" helpviewer_keywords: ["memory allocation, window objects", "memory deallocation", "storage for window objects [MFC]", "memory deallocation, window memory", "window objects [MFC], deallocating memory for", "storage for window objects [MFC], allocating"] -ms.assetid: 7c962539-8461-4846-b5ca-fe3b15c313dc +ms.topic: concept-article --- # Allocating and Deallocating Window Memory +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Do not use the C++ **`delete`** operator to destroy a frame window or view. Instead, call the `CWnd` member function `DestroyWindow`. Frame windows, therefore, should be allocated on the heap with operator **`new`**. Be careful when allocating frame windows on the stack frame or globally. Other windows should be allocated on the stack frame whenever possible. ## What do you want to know more about diff --git a/docs/mfc/allocating-gdi-resources.md b/docs/mfc/allocating-gdi-resources.md index 1a1e83e8231..fb4dc60d44d 100644 --- a/docs/mfc/allocating-gdi-resources.md +++ b/docs/mfc/allocating-gdi-resources.md @@ -3,10 +3,13 @@ description: "Learn more about: Allocating GDI Resources" title: "Allocating GDI Resources" ms.date: "06/03/2019" helpviewer_keywords: ["resources [MFC], printing", "GDI objects [MFC], allocating during printing", "printing [MFC], allocating GDI resources"] -ms.assetid: cef7e94d-5a27-4aea-a9ee-8369fc895d3a +ms.topic: concept-article --- # Allocating GDI Resources +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to allocate and deallocate the Windows graphics device interface (GDI) objects needed for printing. > [!NOTE] diff --git a/docs/mfc/alternatives-to-the-document-view-architecture.md b/docs/mfc/alternatives-to-the-document-view-architecture.md index 5254b76bd37..aea82ec47b9 100644 --- a/docs/mfc/alternatives-to-the-document-view-architecture.md +++ b/docs/mfc/alternatives-to-the-document-view-architecture.md @@ -3,10 +3,12 @@ description: "Learn more about: Alternatives to the Document/View Architecture" title: "Alternatives to the Document-View Architecture" ms.date: "11/04/2016" helpviewer_keywords: ["documents [MFC], applications without", "CDocument class [MFC], space requirements", "views [MFC], applications without"] -ms.assetid: 2c22f352-a137-45ce-9971-c142173496fb --- # Alternatives to the Document/View Architecture +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC applications normally use the document/view architecture to manage information, file formats, and the visual representation of data to users. For the majority of desktop applications, the document/view architecture is an appropriate and efficient application architecture. This architecture separates data from viewing and, in most cases, simplifies your application and reduces redundant code. However, the document/view architecture is not appropriate for some situations. Consider these examples: @@ -22,7 +24,7 @@ To create an application that does not use the document/view architecture, clear > [!NOTE] > Dialog-based applications produced by the MFC Application Wizard do not use the document/view architecture, so the **Document/View architecture support** check box is disabled if you select the dialog application type. -The Visual C++ wizards, as well as the source and dialog editors, work with the generated application just as they would with any other Wizard-generated application. The application can support toolbars, scrollbars, and a status bar, and has an **About** box. Your application will not register any document templates, and it will not contain a document class. +The Visual Studio wizards, as well as the source and dialog editors, work with the generated application just as they would with any other Wizard-generated application. The application can support toolbars, scrollbars, and a status bar, and has an **About** box. Your application will not register any document templates, and it will not contain a document class. Note that your generated application has a view class, `CChildView`, derived from `CWnd`. MFC creates and positions one instance of the view class within the frame windows created by your application. MFC still enforces using a view window, because it simplifies positioning and managing the application's content. You can add painting code to the `OnPaint` member of this class. Your code should add scrollbars to the view rather than to the frame. diff --git a/docs/mfc/application-and-thread-support-classes.md b/docs/mfc/application-and-thread-support-classes.md index b05bbbcc85f..dd028a163fd 100644 --- a/docs/mfc/application-and-thread-support-classes.md +++ b/docs/mfc/application-and-thread-support-classes.md @@ -4,10 +4,12 @@ title: "Application and Thread Support Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.support"] helpviewer_keywords: ["application objects [MFC], thread support classes", "lock classes [MFC]", "thread support classes [MFC]", "threading [MFC]", "synchronization classes [MFC], multithreading", "application support classes [MFC]"] -ms.assetid: 3c1d14fd-c35c-48f1-86ce-1e0f9a32c36d --- # Application and Thread Support Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Each application has one and only one application object; this object coordinates other objects in the running program and is derived from `CWinApp`. The Microsoft Foundation Class (MFC) Library supports multiple threads of execution within an application. All applications must have at least one thread; the thread used by your `CWinApp` object is this primary thread. diff --git a/docs/mfc/application-design-choices.md b/docs/mfc/application-design-choices.md index 398024a1216..c4d54447abd 100644 --- a/docs/mfc/application-design-choices.md +++ b/docs/mfc/application-design-choices.md @@ -3,10 +3,12 @@ description: "Learn more about: Application Design Choices" title: "Application Design Choices" ms.date: "09/12/2019" helpviewer_keywords: ["design", "application design [MFC], design goals", "application design [MFC], Internet applications", "Internet applications [MFC], designing applications", "Internet [MFC], vs. intranets", "applications [MFC], Internet", "server applications [MFC], vs. client applications on Internet", "client applications [MFC], vs. server applications on Internet"] -ms.assetid: 9b96172c-b4d4-4c69-bfb2-226ce0de6d08 --- # Application Design Choices +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses some of the design issues to consider when programming for the Internet. Topics covered in this article include: diff --git a/docs/mfc/application-framework.md b/docs/mfc/application-framework.md index 3d7b573f4a3..247ee9f23cd 100644 --- a/docs/mfc/application-framework.md +++ b/docs/mfc/application-framework.md @@ -3,10 +3,12 @@ description: "Learn more about: Application Framework" title: "Application Framework" ms.date: "11/04/2016" helpviewer_keywords: ["application framework [MFC], building applications", "applications [MFC]", "application framework [MFC]"] -ms.assetid: 912684e6-4418-49dc-9877-a4cd19d69d20 --- # Application Framework +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The core of the Microsoft Foundation Class (MFC) Library is an encapsulation of a large portion of the Windows API in C++ form. Library classes represent windows, dialog boxes, device contexts, common GDI objects such as brushes and pens, controls, and other standard Windows items. These classes provide a convenient C++ member function interface to the structures in Windows that they encapsulate. For more about using these classes, see [Window Object Topics](window-objects.md). But the MFC Library also supplies a layer of additional application functionality built on the C++ encapsulation of the Windows API. This layer is a working application framework for Windows that provides most of the common user interface expected of programs for Windows, including toolbars, status bars, printing, print preview, database support, and ActiveX support. [Using the Classes to Write Applications for Windows](using-the-classes-to-write-applications-for-windows.md) explains the framework in detail. diff --git a/docs/mfc/array-list-and-map-classes.md b/docs/mfc/array-list-and-map-classes.md index b0fa8481746..381ad523acb 100644 --- a/docs/mfc/array-list-and-map-classes.md +++ b/docs/mfc/array-list-and-map-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Array, List, and Map Classes" title: "Array, List, and Map Classes" ms.date: "11/04/2016" helpviewer_keywords: ["arrays [MFC], classes", "list classes [MFC]", "collection classes [MFC], maps", "map classes [MFC]", "collection classes [MFC], lists"] -ms.assetid: 81a13a7f-0c2c-4efd-b6bb-b4e624a0743d --- # Array, List, and Map Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For handling aggregates of data, the class library provides a group of collection classes — arrays, lists, and maps — that can hold a variety of object and predefined types. The collections are dynamically sized. These classes can be used in any program, whether written for Windows or not. However, they are most useful for implementing the data structures that define your document classes in the application framework. You can readily derive specialized collection classes from these, or you can create them based on the template classes. For more information about these approaches, see the article [Collections](collections.md). For a list of the template collection classes, see the article [Template Classes for Arrays, Lists, and Maps](template-classes-for-arrays-lists-and-maps.md). Arrays are one-dimensional data structures that are stored contiguously in memory. They support very fast random access since the memory address of any given element can be calculated by multiplying the index of the element by the size of an element and adding the result to the base address of the array. But arrays are very expensive if you have to insert elements into the array, since the entire array past the element inserted has to be moved to make room for the element to be inserted. Arrays can grow and shrink as necessary. diff --git a/docs/mfc/asynchronous-monikers-on-the-internet.md b/docs/mfc/asynchronous-monikers-on-the-internet.md index f9ea5ad99cd..0387ba229f9 100644 --- a/docs/mfc/asynchronous-monikers-on-the-internet.md +++ b/docs/mfc/asynchronous-monikers-on-the-internet.md @@ -3,10 +3,12 @@ description: "Learn more about: Asynchronous Monikers on the Internet" title: "Asynchronous Monikers on the Internet" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX controls [MFC], asynchronous", "MFC, asynchronous monikers", "asynchronous monikers [MFC]", "Web applications [MFC], asynchronous", "downloading Internet resources and asynchronous monikers", "optimization [MFC], asynchronous downloading across Internet", "Internet [MFC], asynchronous downloading"] -ms.assetid: 418b0c64-0046-4dae-8118-c9c762b5822e --- # Asynchronous Monikers on the Internet +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Internet requires new approaches to application design because of its slow network access. Applications should perform network access asynchronously to avoid stalling the user interface. The MFC class [CAsyncMonikerFile](reference/casyncmonikerfile-class.md) provides asynchronous support for downloading files. With asynchronous monikers, you can extend your COM application to download asynchronously across the Internet and to provide progressive rendering of large objects such as bitmaps and VRML objects. Asynchronous monikers enable an ActiveX control property or a file on the Internet to be downloaded without blocking the response of the user interface. diff --git a/docs/mfc/automation-clients-using-type-libraries.md b/docs/mfc/automation-clients-using-type-libraries.md index d5c6ccb2cc8..5f0c32dc7aa 100644 --- a/docs/mfc/automation-clients-using-type-libraries.md +++ b/docs/mfc/automation-clients-using-type-libraries.md @@ -4,19 +4,21 @@ title: "Automation Clients: Using Type Libraries" ms.date: "11/04/2016" f1_keywords: ["MkTypLib"] helpviewer_keywords: ["clients, Automation", "dispatch class [MFC]", "Automation clients, type libraries", "type libraries, Automation clients", "ODL (Object Description Language)", "ODL files", "classes [MFC], dispatch", "MkTypLib tool", ".odl files"] -ms.assetid: d405bc47-118d-4786-b371-920d035b2047 --- # Automation Clients: Using Type Libraries +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Automation clients must have information about server objects' properties and methods if the clients are to manipulate the servers' objects. Properties have data types; methods often return values and accept parameters. The client requires information about the data types of all of these in order to statically bind to the server object type. This type information can be made known in several ways. The recommended way is to create a type library. For information on [MkTypLib](/windows/win32/Midl/differences-between-midl-and-mktyplib), see the Windows SDK. -Visual C++ can read a type-library file and create a dispatch class derived from [COleDispatchDriver](reference/coledispatchdriver-class.md). An object of that class has properties and operations duplicating those of the server object. Your application calls this object's properties and operations, and functionality inherited from `COleDispatchDriver` routes these calls to the OLE system, which in turn routes them to the server object. +Visual Studio can read a type-library file and create a dispatch class derived from [COleDispatchDriver](reference/coledispatchdriver-class.md). An object of that class has properties and operations duplicating those of the server object. Your application calls this object's properties and operations, and functionality inherited from `COleDispatchDriver` routes these calls to the OLE system, which in turn routes them to the server object. -Visual C++ automatically maintains this type-library file for you if you chose to include Automation when the project was created. As part of each build, the .tlb file will be built with MkTypLib. +Visual Studio automatically maintains this type-library file for you if you chose to include Automation when the project was created. As part of each build, the .tlb file will be built with MkTypLib. ### To create a dispatch class from a type-library (.tlb) file diff --git a/docs/mfc/automation-clients.md b/docs/mfc/automation-clients.md index 989c65eed90..f54f51f9a75 100644 --- a/docs/mfc/automation-clients.md +++ b/docs/mfc/automation-clients.md @@ -3,10 +3,12 @@ description: "Learn more about: Automation Clients" title: "Automation Clients" ms.date: "11/04/2016" helpviewer_keywords: ["clients, Automation", "Automation clients", "type libraries, Automation clients", "clients"] -ms.assetid: 84e34a79-06f6-4752-a33b-ae0ede1d8ecf --- # Automation Clients +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Automation makes it possible for your application to manipulate objects implemented in another application, or to expose objects so they can be manipulated. An Automation client is an application that can manipulate exposed objects belonging to another application. The application that exposes the objects is called the Automation server. The client manipulates the server application's objects by accessing those objects' properties and functions. ### Types of Automation Clients diff --git a/docs/mfc/automation-servers-object-lifetime-issues.md b/docs/mfc/automation-servers-object-lifetime-issues.md index 457ac5ea555..6f33844414c 100644 --- a/docs/mfc/automation-servers-object-lifetime-issues.md +++ b/docs/mfc/automation-servers-object-lifetime-issues.md @@ -3,10 +3,12 @@ description: "Learn more about: Automation Servers: Object-Lifetime Issues" title: "Automation Servers: Object-Lifetime Issues" ms.date: "11/04/2016" helpviewer_keywords: ["objects [MFC], lifetime", "lifetime, automation server", "Automation servers, object lifetime", "servers, lifetime of Automation"] -ms.assetid: 342baacf-4015-4a0e-be2f-321424f1cb43 --- # Automation Servers: Object-Lifetime Issues +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When an Automation client creates or activates an OLE item, the server passes the client a pointer to that object. The client establishes a reference to the object through a call to the OLE function [IUnknown::AddRef](/windows/win32/api/unknwn/nf-unknwn-iunknown-addref). This reference is in effect until the client calls [IUnknown::Release](/windows/win32/api/unknwn/nf-unknwn-iunknown-release). (Client applications written with the Microsoft Foundation Class Library's OLE classes need not make these calls; the framework does so.) The OLE system and the server itself may establish references to the object. A server should not destroy an object as long as external references to the object remain in effect. The framework maintains an internal count of the number of references to any server object derived from [CCmdTarget](reference/ccmdtarget-class.md). This count is updated when an Automation client or other entity adds or releases a reference to the object. diff --git a/docs/mfc/automation-servers.md b/docs/mfc/automation-servers.md index 5a8b3b31a32..18100344f5f 100644 --- a/docs/mfc/automation-servers.md +++ b/docs/mfc/automation-servers.md @@ -3,10 +3,12 @@ description: "Learn more about: Automation Servers" title: "Automation Servers" ms.date: "11/04/2016" helpviewer_keywords: ["Automation servers", "COM components, Automation servers", "dispatch maps [MFC], Automation servers", "servers, Automation"] -ms.assetid: 523fd155-51ce-4f91-b986-b74bdbdd7d92 --- # Automation Servers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Automation makes it possible for your application to manipulate objects implemented in another application, or to expose objects so they can be manipulated. An Automation server is an application that exposes programmable objects (called Automation objects) to other applications (called [Automation clients](automation-clients.md)). Automation servers are sometimes called Automation components. Exposing Automation objects enables clients to automate certain procedures by directly accessing the objects and functionality the server makes available. Exposing objects this way is beneficial when applications provide functionality that is useful for other applications. For example, a word processor might expose its spell-checking functionality so that other programs can use it. Exposure of objects thus enables vendors to improve their applications' functionality by using the ready-made functionality of other applications. @@ -20,7 +22,7 @@ By exposing application functionality through a common, well-defined interface, ## Support for Automation Servers -Visual C++ and the MFC framework provide extensive support for Automation servers. They handle much of the overhead involved in making an Automation server, so you can focus your efforts on the functionality of your application. +Visual Studio and the MFC framework provide extensive support for Automation servers. They handle much of the overhead involved in making an Automation server, so you can focus your efforts on the functionality of your application. The framework's principal mechanism for supporting Automation is the dispatch map, a set of macros that expands into the declarations and calls needed to expose methods and properties for OLE. A typical dispatch map looks like this: diff --git a/docs/mfc/automation.md b/docs/mfc/automation.md index beca853d89d..82f2e62b4e8 100644 --- a/docs/mfc/automation.md +++ b/docs/mfc/automation.md @@ -3,10 +3,12 @@ description: "Learn more about: Automation" title: "Automation" ms.date: "11/04/2016" helpviewer_keywords: ["Automation servers, about Automation servers", "clients, Automation", "programmatic control [MFC]", "properties [MFC], Automation", "MFC, COM support", "OLE Automation", "Automation", "servers [MFC], Automation", "Automation clients", "sample applications [MFC], Automation", "methods [MFC]", "passing parameters, Automation", "Automation method [MFC]", "Automation, passing parameters", "Automation property [MFC]", "MFC COM, Automation", "methods [MFC], Automation"] -ms.assetid: 329117f0-c1aa-4680-a901-bfb71277dfba --- # Automation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Automation (formerly known as OLE Automation) makes it possible for one application to manipulate objects implemented in another application, or to expose objects so they can be manipulated. An [Automation server](automation-servers.md) is an application (a type of COM server) that exposes its functionality through COM interfaces to other applications, called [Automation clients](automation-clients.md). The exposure enables Automation clients to automate certain functions by directly accessing objects and using the services they provide. @@ -23,7 +25,7 @@ As another example, a word processor might expose its spell-checking functionali More important is the support Automation provides to users and solution providers. By exposing application functionality through a common, well-defined interface, Automation makes it possible to build comprehensive solutions in a single general programming language, such as Microsoft Visual Basic, instead of in diverse application-specific macro languages. -Many commercial applications, such as Microsoft Excel and Microsoft Visual C++, allow you to automate much of their functionality. For example, in Visual C++, you can write VBScript macros to automate builds, aspects of code editing, or debugging tasks. +Many commercial applications, such as Microsoft Excel and Visual Studio, allow you to automate much of their functionality. For example, in Visual Studio, you can write VBScript macros to automate builds, aspects of code editing, or debugging tasks. ## Passing Parameters in Automation diff --git a/docs/mfc/bottomless-rich-edit-controls.md b/docs/mfc/bottomless-rich-edit-controls.md index c157bbf3bd6..a967cd0b048 100644 --- a/docs/mfc/bottomless-rich-edit-controls.md +++ b/docs/mfc/bottomless-rich-edit-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Bottomless Rich Edit Controls" title: "Bottomless Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["bottomless rich edit controls", "rich edit controls [MFC], bottomless", "CRichEditCtrl class [MFC], bottomless"] -ms.assetid: 2877dd32-1e9a-4fd1-98c0-66dcbbeef1de --- # Bottomless Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your application can resize a rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)) as needed so that it is always the same size as its contents. A rich edit control supports this so-called "bottomless" functionality by sending its parent window an [EN_REQUESTRESIZE](/windows/win32/Controls/en-requestresize) notification message whenever the size of its contents changes. When processing the **EN_REQUESTRESIZE** notification message, an application should resize the control to the dimensions in the specified [REQRESIZE](/windows/win32/api/richedit/ns-richedit-reqresize) structure. An application might also move any information near the control to accommodate the control's change in height. To resize the control, you can use the `CWnd` function [SetWindowPos](reference/cwnd-class.md#setwindowpos). diff --git a/docs/mfc/build-requirements-for-windows-vista-common-controls.md b/docs/mfc/build-requirements-for-windows-vista-common-controls.md index 57617f2e267..b54c1c9796d 100644 --- a/docs/mfc/build-requirements-for-windows-vista-common-controls.md +++ b/docs/mfc/build-requirements-for-windows-vista-common-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Build Requirements for Windows Common Controls" title: "Build Requirements for Windows Common Controls" ms.date: "08/19/2019" helpviewer_keywords: ["Common Controls (MFC), build requirements", "Common Controls (MFC)"] -ms.assetid: 025f7d55-55a2-4dcd-8f62-02424e3dcc04 +ms.topic: how-to --- # Build Requirements for Windows Common Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class (MFC) library supports [Windows Common Controls](/windows/win32/controls/common-controls-intro). The Common Controls are included in Windows and the library is included in Visual Studio. The MFC library provides new methods that enhance existing classes, and additional classes and methods that support Windows Common Controls. When you build your application, you should follow the compilation and migration requirements that are described in the following sections. ## Compilation Requirements diff --git a/docs/mfc/building-on-the-framework.md b/docs/mfc/building-on-the-framework.md index 1cd5cb09897..e11f3d9f318 100644 --- a/docs/mfc/building-on-the-framework.md +++ b/docs/mfc/building-on-the-framework.md @@ -3,10 +3,13 @@ description: "Learn more about: Building on the Framework" title: "Building on the Framework" ms.date: "11/04/2016" helpviewer_keywords: ["application-specific classes [MFC]", "application framework [MFC], building applications", "applications [MFC]", "MFC, application development"] -ms.assetid: 883f0f19-866f-4221-8a3d-5607941dc8d0 +ms.topic: concept-article --- # Building on the Framework +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your role in configuring an application with the MFC framework is to supply the application-specific source code and to connect the components by defining what messages and commands to which they respond. You use the C++ language and standard C++ techniques to derive your own application-specific classes from those supplied by the class library and to override and augment the base class's behavior. In related topics, the following tables describe the general sequence of operations you will typically follow and your responsibilities versus the framework's responsibilities: diff --git a/docs/mfc/bypassing-the-serialization-mechanism.md b/docs/mfc/bypassing-the-serialization-mechanism.md index ff376ebe45d..0ea67bc23c5 100644 --- a/docs/mfc/bypassing-the-serialization-mechanism.md +++ b/docs/mfc/bypassing-the-serialization-mechanism.md @@ -3,10 +3,13 @@ description: "Learn more about: Bypassing the Serialization Mechanism" title: "Bypassing the Serialization Mechanism" ms.date: "11/04/2016" helpviewer_keywords: ["archive objects [MFC]", "bypassing serialization", "archives [MFC], serialization", "serialization [MFC], bypassing", "archives [MFC]", "serialization [MFC], role of framework", "serialization [MFC], overriding"] -ms.assetid: 48d4a279-b51c-4ba5-81cd-ed043312b582 +ms.topic: concept-article --- # Bypassing the Serialization Mechanism +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As you have seen, the framework provides a default way to read and write data to and from files. Serializing through an archive object suits the needs of a great many applications. Such an application reads a file entirely into memory, lets the user update the file, and then writes the updated version to disk again. However, some applications operate on data very differently, and for these applications serialization through an archive is not suitable. Examples include database programs, programs that edit only parts of large files, programs that write text-only files, and programs that share data files. diff --git a/docs/mfc/callback-items-and-the-callback-mask.md b/docs/mfc/callback-items-and-the-callback-mask.md index d94e970a78f..b130b9c51b1 100644 --- a/docs/mfc/callback-items-and-the-callback-mask.md +++ b/docs/mfc/callback-items-and-the-callback-mask.md @@ -3,10 +3,12 @@ description: "Learn more about: Callback Items and the Callback Mask" title: "Callback Items and the Callback Mask" ms.date: "11/04/2016" helpviewer_keywords: ["callback items in CListCtrl class [MFC]", "CListCtrl class [MFC], callback item and callback mask"] -ms.assetid: 67c1f76f-6144-453e-9376-6712f89430ae --- # Callback Items and the Callback Mask +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For each of its items, a list view control typically stores the label text, the image list index of the item's icons, and a set of bit flags for the item's state. You can define individual items as callback items, which are useful if your application already stores some of the information for an item. You define an item as a callback item by specifying appropriate values for the `pszText` and `iImage` members of the `LVITEM` structure (see [CListCtrl::GetItem](reference/clistctrl-class.md#getitem)). If the application maintains the item's or subitem's text, specify the **LPSTR_TEXTCALLBACK** value for the `pszText` member. If the application keeps track of the icon for the item, specify the **I_IMAGECALLBACK** value for the `iImage` member. diff --git a/docs/mfc/changing-list-control-styles.md b/docs/mfc/changing-list-control-styles.md index 37be34f1043..3dbf36eb17a 100644 --- a/docs/mfc/changing-list-control-styles.md +++ b/docs/mfc/changing-list-control-styles.md @@ -3,10 +3,13 @@ description: "Learn more about: Changing List Control Styles" title: "Changing List Control Styles" ms.date: "11/04/2016" helpviewer_keywords: ["styles [MFC], CListCtrl", "CListCtrl class [MFC], styles", "CListCtrl class [MFC], changing styles"] -ms.assetid: be74a005-0795-417c-9056-f6342aa74b26 +ms.topic: concept-article --- # Changing List Control Styles +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can change the window style of a list control ([CListCtrl](reference/clistctrl-class.md)) at any time after you create it. By changing the window style, you change the kind of view the control uses. For example, to emulate the Explorer, you might supply menu items or toolbar buttons for switching the control between different views: icon view, list view, and so on. For example, when the user selects your menu item, you could make a call to [GetWindowLong](/windows/win32/api/winuser/nf-winuser-getwindowlongw) to retrieve the current style of the control and then call [SetWindowLong](/windows/win32/api/winuser/nf-winuser-setwindowlongw) to reset the style. For more information, see [Using List View Controls](/windows/win32/Controls/using-list-view-controls) in the Windows SDK. diff --git a/docs/mfc/changing-the-styles-of-a-window-created-by-mfc.md b/docs/mfc/changing-the-styles-of-a-window-created-by-mfc.md index 772b7b1a296..cd497f782a3 100644 --- a/docs/mfc/changing-the-styles-of-a-window-created-by-mfc.md +++ b/docs/mfc/changing-the-styles-of-a-window-created-by-mfc.md @@ -3,10 +3,13 @@ description: "Learn more about: Changing the Styles of a Window Created by MFC" title: "Changing the Styles of a Window Created by MFC" ms.date: "11/04/2016" helpviewer_keywords: ["window styles [MFC]", "WS_OVERLAPPEDWINDOW macro [MFC]", "single document interface (SDI), changing window attributes", "MDI [MFC], window styles", "windows [MFC], MFC", "child windows [MFC], styles", "MFC, windows", "CFrameWnd class [MFC], window styles", "CREATESTRUCT macro [MFC]", "CMDIChildWnd class [MFC], changing window styles", "multidocument interface style", "PreCreateWindow method [MFC], window styles", "single document interface (SDI), style", "default window style", "defaults [MFC], window style", "PreCreateWindow method [MFC], changing window styles", "CMainFrame class [MFC]", "styles [MFC], windows"] -ms.assetid: 77fa4f03-96b4-4687-9ade-41e46f7e4b0a +ms.topic: concept-article --- # Changing the Styles of a Window Created by MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In its version of the `WinMain` function, MFC registers several standard window classes for you. Because you don't normally edit MFC's `WinMain`, that function gives you no opportunity to change the MFC default window styles. This article explains how you can change the styles of such a preregistered window class in an existing application. ## Changing Styles in a New MFC Application diff --git a/docs/mfc/character-formatting-in-rich-edit-controls.md b/docs/mfc/character-formatting-in-rich-edit-controls.md index 640717720d1..ed92e73f6da 100644 --- a/docs/mfc/character-formatting-in-rich-edit-controls.md +++ b/docs/mfc/character-formatting-in-rich-edit-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Character Formatting in Rich Edit Controls" title: "Character Formatting in Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["formatting [MFC], characters", "rich edit controls [MFC], character formatting in", "CRichEditCtrl class [MFC], character formatting in"] -ms.assetid: c80f4305-75ad-45f9-8d17-d83d0fe79be5 --- # Character Formatting in Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use member functions of the rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)) to format characters and to retrieve formatting information. For characters, you can specify typeface, size, color, and effects such as bold, italic, and protected. You can apply character formatting by using the [SetSelectionCharFormat](reference/cricheditctrl-class.md#setselectioncharformat) and [SetWordCharFormat](reference/cricheditctrl-class.md#setwordcharformat) member functions. To determine the current character formatting for the selected text, use the [GetSelectionCharFormat](reference/cricheditctrl-class.md#getselectioncharformat) member function. The [CHARFORMAT](/windows/win32/api/richedit/ns-richedit-charformata) structure is used with these member functions to specify character attributes. One of the important members of **CHARFORMAT** is **dwMask**. In `SetSelectionCharFormat` and `SetWordCharFormat`, **dwMask** specifies which character attributes will be set by this function call. `GetSelectionCharFormat` reports the attributes of the first character in the selection; **dwMask** specifies the attributes that are consistent throughout the selection. diff --git a/docs/mfc/class-library-overview.md b/docs/mfc/class-library-overview.md index f30e76f9ec3..95f1076e12d 100644 --- a/docs/mfc/class-library-overview.md +++ b/docs/mfc/class-library-overview.md @@ -4,10 +4,13 @@ title: "Class Library Overview" ms.date: "09/17/2019" f1_keywords: ["vc.classes.mfc"] helpviewer_keywords: ["grouping MFC classes", "MFC, class library", "classes [MFC], MFC", "class libraries, MFC", "class libraries"] -ms.assetid: 9b0e3152-ac39-4f52-91b4-f20aa3a674aa +ms.topic: concept-article --- # Class Library Overview +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This overview categorizes and describes the classes in the Microsoft Foundation Class Library (MFC) version 9.0. The classes in MFC, taken together, constitute an application framework — the framework of an application written for the Windows API. Your programming task is to fill in the code that is specific to your application. The library's classes are presented here in the following categories: diff --git a/docs/mfc/classes-related-to-rich-edit-controls.md b/docs/mfc/classes-related-to-rich-edit-controls.md index 2f7155637b6..de2b4a37401 100644 --- a/docs/mfc/classes-related-to-rich-edit-controls.md +++ b/docs/mfc/classes-related-to-rich-edit-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Classes Related to Rich Edit Controls" title: "Classes Related to Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["rich edit controls [MFC], and CRichEditItem", "CRichEditCtrl class [MFC], related classes", "CRichEditDoc class [MFC], Rich Edit controls", "rich edit controls [MFC], classes related to", "classes [MFC], related to rich edit controls", "rich edit controls [MFC], and CRichEditView", "CRichEditCtrlItem class and CRichEditCtrl", "rich edit controls [MFC], and CRichEditDoc", "CRichEditView class [MFC], and CRichEditCtrl"] -ms.assetid: 4b31c2cc-6ea1-4146-b7c5-b0b5b419f14d --- # Classes Related to Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CRichEditView](reference/cricheditview-class.md), [CRichEditDoc](reference/cricheditdoc-class.md), and [CRichEditCntrItem](reference/cricheditcntritem-class.md) classes provide the functionality of the rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)) within the context of MFC's document/view architecture. `CRichEditView` maintains the text and formatting characteristic of text. `CRichEditDoc` maintains the list of OLE client items that are in the view. `CRichEditCntrItem` provides container-side access to the OLE client item. To modify the contents of a `CRichEditView`, use [CRichEditView::GetRichEditCtrl](reference/cricheditview-class.md#getricheditctrl) to access the underlying rich edit control. ## See also diff --git a/docs/mfc/cleaning-up-documents-and-views.md b/docs/mfc/cleaning-up-documents-and-views.md index 9903e1e53d8..91b6ec01c28 100644 --- a/docs/mfc/cleaning-up-documents-and-views.md +++ b/docs/mfc/cleaning-up-documents-and-views.md @@ -3,10 +3,13 @@ description: "Learn more about: Cleaning Up Documents and Views" title: "Cleaning Up Documents and Views" ms.date: "11/04/2016" helpviewer_keywords: ["views [MFC], cleaning up", "documents [MFC], cleaning up", "documents [MFC], closing"] -ms.assetid: 0c454db2-3644-434d-9e53-8108a7aedfe1 +ms.topic: concept-article --- # Cleaning Up Documents and Views +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When a document is closing, the framework first calls its [DeleteContents](reference/cdocument-class.md#deletecontents) member function. If you allocated any memory on the heap during the course of the document's operation, `DeleteContents` is the best place to deallocate it. > [!NOTE] diff --git a/docs/mfc/clipboard-adding-other-formats.md b/docs/mfc/clipboard-adding-other-formats.md index f3e9ef9e30b..235d391e58c 100644 --- a/docs/mfc/clipboard-adding-other-formats.md +++ b/docs/mfc/clipboard-adding-other-formats.md @@ -3,10 +3,12 @@ description: "Learn more about: Clipboard: Adding Other Formats" title: "Clipboard: Adding Other Formats" ms.date: "11/04/2016" helpviewer_keywords: ["formats [MFC], Clipboard", "Clipboard, formats", "custom formats, placing on Clipboard", "custom formats", "registering custom Clipboard data formats", "custom Clipboard data formats"] -ms.assetid: aea58159-65ed-4385-aeaa-3d9d5281903b --- # Clipboard: Adding Other Formats +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic explains how to expand the list of supported formats, particularly for OLE support. The topic [Clipboard: Copying and Pasting Data](clipboard-copying-and-pasting-data.md) describes the minimum implementation necessary to support copying and pasting from the Clipboard. If this is all you implement, the only formats placed on the Clipboard are **CF_METAFILEPICT**, **CF_EMBEDSOURCE**, **CF_OBJECTDESCRIPTOR**, and possibly **CF_LINKSOURCE**. Most applications will need more formats on the Clipboard than these three. ## Registering Custom Formats diff --git a/docs/mfc/clipboard-copying-and-pasting-data.md b/docs/mfc/clipboard-copying-and-pasting-data.md index 4225da141bf..f2e50f84159 100644 --- a/docs/mfc/clipboard-copying-and-pasting-data.md +++ b/docs/mfc/clipboard-copying-and-pasting-data.md @@ -3,10 +3,12 @@ description: "Learn more about: Clipboard: Copying and Pasting Data" title: "Clipboard: Copying and Pasting Data" ms.date: "11/04/2016" helpviewer_keywords: ["Clipboard, copying data to", "Clipboard, pasting"] -ms.assetid: 580e10be-241f-4f9f-94cf-8302edc5beef --- # Clipboard: Copying and Pasting Data +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic describes the minimum work necessary to implement copying to and pasting from the Clipboard in your OLE application. It is recommended that you read the [Data Objects and Data Sources (OLE)](data-objects-and-data-sources-ole.md) topics before proceeding. Before you can implement either copying or pasting, you must first provide functions to handle the Copy, Cut, and Paste options on the Edit menu. diff --git a/docs/mfc/clipboard-operations-in-rich-edit-controls.md b/docs/mfc/clipboard-operations-in-rich-edit-controls.md index 972af313345..08b46730de2 100644 --- a/docs/mfc/clipboard-operations-in-rich-edit-controls.md +++ b/docs/mfc/clipboard-operations-in-rich-edit-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Clipboard Operations in Rich Edit Controls" title: "Clipboard Operations in Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["pasting Clipboard data", "CRichEditCtrl class [MFC], paste operation", "cut operation in CRichEditCtrl class [MFC]", "CRichEditCtrl class [MFC], Clipboard operations", "copy operations in rich edit controls", "Clipboard, operations in CRichEditCtrl", "rich edit controls [MFC], Clipboard operations"] -ms.assetid: 15ce66bc-2636-4a35-a2ae-d52285dc1af6 --- # Clipboard Operations in Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your application can paste the contents of the Clipboard into a rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)) using either the best available Clipboard format or a specific Clipboard format. You can also determine whether a rich edit control is capable of pasting a Clipboard format. You can copy or cut the contents of the current selection by using the [Copy](reference/cricheditctrl-class.md#copy) or [Cut](reference/cricheditctrl-class.md#cut) member function. Similarly, you can paste the contents of the Clipboard into a rich edit control by using the [Paste](reference/cricheditctrl-class.md#paste) member function. The control pastes the first available format that it recognizes, which presumably is the most descriptive format. diff --git a/docs/mfc/clipboard-using-the-ole-clipboard-mechanism.md b/docs/mfc/clipboard-using-the-ole-clipboard-mechanism.md index 53da3be2654..288e42cffd2 100644 --- a/docs/mfc/clipboard-using-the-ole-clipboard-mechanism.md +++ b/docs/mfc/clipboard-using-the-ole-clipboard-mechanism.md @@ -3,10 +3,12 @@ description: "Learn more about: Clipboard: Using the OLE Clipboard Mechanism" title: "Clipboard: Using the OLE Clipboard Mechanism" ms.date: "11/04/2016" helpviewer_keywords: ["applications [OLE], Clipboard", "OLE Clipboard", "Clipboard [MFC], OLE formats", "OLE Clipboard, formats", "formats [MFC], Clipboard for OLE"] -ms.assetid: 229cc610-5bb1-435e-bd20-2c8b9964d1af --- # Clipboard: Using the OLE Clipboard Mechanism +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + OLE uses standard formats and some OLE-specific formats for transferring data through the Clipboard. When you cut or copy data from an application, the data is stored on the Clipboard to be used later in paste operations. This data is in a variety of formats. When a user chooses to paste data from the Clipboard, the application can choose which of these formats to use. The application should be written to choose the format that provides the most information, unless the user specifically asks for a certain format, using Paste Special. Before continuing, you may want to read the [Data Objects and Data Sources (OLE)](data-objects-and-data-sources-ole.md) topics. They describe the fundamentals of how data transfers work, and how to implement them in your applications. diff --git a/docs/mfc/clipboard-using-the-windows-clipboard.md b/docs/mfc/clipboard-using-the-windows-clipboard.md index 64d3123609b..648e989ca4f 100644 --- a/docs/mfc/clipboard-using-the-windows-clipboard.md +++ b/docs/mfc/clipboard-using-the-windows-clipboard.md @@ -3,10 +3,12 @@ description: "Learn more about: Clipboard: Using the Windows Clipboard" title: "Clipboard: Using the Windows Clipboard" ms.date: "11/04/2016" helpviewer_keywords: ["Clipboard commands", "Cut/Copy and Paste command handler functions [MFC]", "handler functions, Cut/Copy and Paste commands", "Clipboard [MFC], commands", "commands [MFC], implementing Edit", "Clipboard commands [MFC], implementing", "Windows Clipboard [MFC]", "Clipboard [MFC], Windows Clipboard API"] -ms.assetid: 24415b42-9301-4a70-b69a-44c97918319f --- # Clipboard: Using the Windows Clipboard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic describes how to use the standard Windows Clipboard API within your MFC application. Most applications for Windows support cutting or copying data to the Windows Clipboard and pasting data from the Clipboard. The Clipboard data formats vary among applications. The framework supports only a limited number of Clipboard formats for a limited number of classes. You will normally implement the Clipboard-related commands — Cut, Copy, and Paste — on the Edit menu for your view. The class library defines the command IDs for these commands: **ID_EDIT_CUT**, **ID_EDIT_COPY**, and **ID_EDIT_PASTE**. Their message-line prompts are also defined. @@ -19,7 +21,7 @@ The Cut, Copy, and Paste commands are only meaningful in certain contexts. The C The Microsoft Foundation Class Library does provide Clipboard support for text editing with the `CEdit` and `CEditView` classes. The OLE classes also simplify implementing Clipboard operations that involve OLE items. For more information on the OLE classes, see [Clipboard: Using the OLE Clipboard Mechanism](clipboard-using-the-ole-clipboard-mechanism.md). -Implementing other Edit menu commands, such as Undo (**ID_EDIT_UNDO**) and Redo (**ID_EDIT_REDO**), is also left to you. If your application does not support these commands, you can easily delete them from your resource file using the Visual C++ resource editors. +Implementing other Edit menu commands, such as Undo (**ID_EDIT_UNDO**) and Redo (**ID_EDIT_REDO**), is also left to you. If your application does not support these commands, you can easily delete them from your resource file using the Visual Studio resource editors. ## What do you want to know more about diff --git a/docs/mfc/clipboard-when-to-use-each-clipboard-mechanism.md b/docs/mfc/clipboard-when-to-use-each-clipboard-mechanism.md index b9c8f734ae9..28de3cdfcfc 100644 --- a/docs/mfc/clipboard-when-to-use-each-clipboard-mechanism.md +++ b/docs/mfc/clipboard-when-to-use-each-clipboard-mechanism.md @@ -3,10 +3,12 @@ description: "Learn more about: Clipboard: When to Use Each Clipboard Mechanism" title: "Clipboard: When to Use Each Clipboard Mechanism" ms.date: "11/04/2016" helpviewer_keywords: ["applications [OLE], Clipboard", "OLE Clipboard, guidelines", "Clipboard [MFC], mechanisms", "OLE Clipboard, formats", "formats [MFC], Clipboard for OLE", "Clipboard [MFC], formats"] -ms.assetid: fd071996-ef8c-488b-81bd-89057095a201 --- # Clipboard: When to Use Each Clipboard Mechanism +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Follow these guidelines in using the Clipboard: - Use the OLE Clipboard mechanism now to enable new capabilities in the future. While the standard Clipboard API will be maintained, the OLE mechanism is the future of data transfer. diff --git a/docs/mfc/clipboard.md b/docs/mfc/clipboard.md index 9e667377481..cbbc987570c 100644 --- a/docs/mfc/clipboard.md +++ b/docs/mfc/clipboard.md @@ -3,10 +3,12 @@ description: "Learn more about: Clipboard" title: "Clipboard" ms.date: "11/04/2016" helpviewer_keywords: ["cutting and copying data", "copying data", "Clipboard", "Clipboard, programming", "transferring data"] -ms.assetid: a71b2824-1f14-4914-8816-54578d73ad4e --- # Clipboard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This family of articles explains how to implement support for the Windows Clipboard in MFC applications. The Windows Clipboard is used in two ways: - Implementing standard Edit menu commands, such as Cut, Copy, and Paste. diff --git a/docs/mfc/closing-files.md b/docs/mfc/closing-files.md index 19a3e35aa51..84f96abc670 100644 --- a/docs/mfc/closing-files.md +++ b/docs/mfc/closing-files.md @@ -3,10 +3,13 @@ description: "Learn more about: Closing Files" title: "Closing Files" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, file operations", "files [MFC], closing"] -ms.assetid: 8415a3a8-3c75-45b0-ac2a-d5385f49bdb3 +ms.topic: how-to --- # Closing Files +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As usual in I/O operations, once you finish with a file, you must close it. #### To close a file diff --git a/docs/mfc/closing-the-dialog-box.md b/docs/mfc/closing-the-dialog-box.md index aa6b937c30c..bd987c2dd53 100644 --- a/docs/mfc/closing-the-dialog-box.md +++ b/docs/mfc/closing-the-dialog-box.md @@ -3,10 +3,13 @@ description: "Learn more about: Closing the Dialog Box" title: "Closing the Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["MFC dialog boxes [MFC], closing", "dialog boxes [MFC], closing"] -ms.assetid: 946f5675-c482-46a4-a5dd-34fe138ffae5 +ms.topic: concept-article --- # Closing the Dialog Box +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A modal dialog box closes when the user chooses one of its buttons, typically the OK button or the Cancel button. Choosing the OK or Cancel button causes Windows to send the dialog object a **BN_CLICKED** control-notification message with the button's ID, either **IDOK** or **IDCANCEL**. `CDialog` provides default handler functions for these messages: `OnOK` and `OnCancel`. The default handlers call the `EndDialog` member function to close the dialog window. You can also call `EndDialog` from your own code. For more information, see the [EndDialog](reference/cdialog-class.md#enddialog) member function of class `CDialog` in the *MFC Reference*. To arrange for closing and deleting a modeless dialog box, override `PostNcDestroy` and invoke the **`delete`** operator on the **`this`** pointer. [Destroying the Dialog Box](destroying-the-dialog-box.md) explains what happens next. diff --git a/docs/mfc/cobject-class-frequently-asked-questions.md b/docs/mfc/cobject-class-frequently-asked-questions.md index 564c284e612..9e356260f82 100644 --- a/docs/mfc/cobject-class-frequently-asked-questions.md +++ b/docs/mfc/cobject-class-frequently-asked-questions.md @@ -3,10 +3,13 @@ description: "Learn more about: CObject Class: Frequently Asked Questions" title: "CObject Class: Frequently Asked Questions" ms.date: "11/04/2016" helpviewer_keywords: ["CObject class [MFC], FAQ"] -ms.assetid: 809a8b99-a2f8-4e16-8b4b-023c94f4125c +ms.topic: faq --- # CObject Class: Frequently Asked Questions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This section covers questions on class `CObject`. ## What do you want to know more about 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 240dd065e73..fbc30334bf0 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/activex-control-containers-using-controls-in-a-non-dialog-container_3.h b/docs/mfc/codesnippet/CPP/activex-control-containers-using-controls-in-a-non-dialog-container_3.h index b28bf3a66d0..bdd7ac78c82 100644 --- a/docs/mfc/codesnippet/CPP/activex-control-containers-using-controls-in-a-non-dialog-container_3.h +++ b/docs/mfc/codesnippet/CPP/activex-control-containers-using-controls-in-a-non-dialog-container_3.h @@ -3,5 +3,4 @@ CCirc m_myCtl; public: afx_msg void OnViewCircdlg(); -} -; \ No newline at end of file +}; diff --git a/docs/mfc/codesnippet/CPP/cbitmapbutton-class_3.cpp b/docs/mfc/codesnippet/CPP/cbitmapbutton-class_3.cpp index 5bb7063b2af..a54aeb90492 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/cdialog-class_2.cpp b/docs/mfc/codesnippet/CPP/cdialog-class_2.cpp index 3c7a6357e16..e3100864ebd 100644 --- a/docs/mfc/codesnippet/CPP/cdialog-class_2.cpp +++ b/docs/mfc/codesnippet/CPP/cdialog-class_2.cpp @@ -26,5 +26,5 @@ void CMyDialog::OnMenuShowAboutDialog() default: // Do something break; - }; + } } \ No newline at end of file diff --git a/docs/mfc/codesnippet/CPP/clistbox-class_23.cpp b/docs/mfc/codesnippet/CPP/clistbox-class_23.cpp index 7301b4da087..f7c839534b6 100644 --- a/docs/mfc/codesnippet/CPP/clistbox-class_23.cpp +++ b/docs/mfc/codesnippet/CPP/clistbox-class_23.cpp @@ -1,6 +1,6 @@ -// Initialize the storage of the list box to be 256 strings with -// about 10 characters per string, performance improvement. -int n = m_myListBox.InitStorage(256, 16 * sizeof(TCHAR)); +// Reserve space in the list box for 256 additional strings with +// about 15 characters per string. +int n = m_myListBox.InitStorage(256, 256 * (15 + 1) * sizeof(TCHAR)); ASSERT(n != LB_ERRSPACE); // Add 256 items to the list box. diff --git a/docs/mfc/codesnippet/CPP/cmultidoctemplate-class_2.cpp b/docs/mfc/codesnippet/CPP/cmultidoctemplate-class_2.cpp index 0583ae03fbc..63f44247ad4 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 cffe2a236b3..cab527dac6f 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 7fd1ae018ac..8e5eed54a3a 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 e8114302897..bcd02c9f95b 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/collections.md b/docs/mfc/collections.md index 7d2d849f052..233816a3beb 100644 --- a/docs/mfc/collections.md +++ b/docs/mfc/collections.md @@ -3,10 +3,12 @@ description: "Learn more about: Collections" title: "Collections" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, collections", "arrays [MFC], classes", "MFC collection classes", "shapes, collection", "collection classes [MFC], MFC", "collections, about collections", "array templates [MFC]", "collection classes [MFC], template-based", "collection classes [MFC], about collection classes", "collection classes [MFC], maps", "collection classes [MFC], arrays", "shapes", "collection classes [MFC], lists", "collection classes [MFC], shapes"] -ms.assetid: 02586e4c-851d-41d0-a722-feb11c17c74c --- # Collections +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class Library provides collection classes to manage groups of objects. These classes are of two types: - [Collection classes created from C++ templates](#_core_the_template_based_collection_classes) diff --git a/docs/mfc/com-interface-entry-points.md b/docs/mfc/com-interface-entry-points.md index 1a35f4c9324..b91a767e41c 100644 --- a/docs/mfc/com-interface-entry-points.md +++ b/docs/mfc/com-interface-entry-points.md @@ -3,10 +3,12 @@ description: "Learn more about: COM Interface Entry Points" title: "COM Interface Entry Points" ms.date: "03/27/2019" helpviewer_keywords: ["entry points, COM interfaces", "state management, OLE/COM interfaces", "MFC COM, COM interface entry points", "OLE, interface entry points", "MFC, managing state data", "COM interfaces, entry points"] -ms.assetid: 9e7421dc-0731-4748-9e1b-90acbaf26d77 --- # COM Interface Entry Points +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For member functions of a COM interface, use the `METHOD_PROLOGUE` macro to maintain the proper global state when calling methods of an exported interface. Typically, member functions of interfaces implemented by `CCmdTarget`-derived objects already use this macro to provide automatic initialization of the `pThis` pointer. For example: diff --git a/docs/mfc/command-ids.md b/docs/mfc/command-ids.md index aacb5c805f9..250be8c082e 100644 --- a/docs/mfc/command-ids.md +++ b/docs/mfc/command-ids.md @@ -3,15 +3,17 @@ description: "Learn more about: Command IDs" title: "Command IDs" ms.date: "11/04/2016" helpviewer_keywords: ["command IDs, MFC", "command IDs"] -ms.assetid: e0171a2b-45b9-41fa-945d-ec2f7602ded0 --- # Command IDs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A command is fully described by its command ID alone (encoded in the **WM_COMMAND** message). This ID is assigned to the user-interface object that generates the command. Typically, IDs are named for the functionality of the user-interface object they are assigned to. For example, a Clear All item in the Edit menu might be assigned an ID such as **ID_EDIT_CLEAR_ALL**. The class library predefines some IDs, particularly for commands that the framework handles itself, such as **ID_EDIT_CLEAR_ALL** or **ID_FILE_OPEN**. You will create other command IDs yourself. -When you create your own menus in the Visual C++ menu editor, it is a good idea to follow the class library's naming convention as illustrated by **ID_FILE_OPEN**. [Standard Commands](standard-commands.md) explains the standard commands defined by the class library. +When you create your own menus in the Visual Studio menu editor, it is a good idea to follow the class library's naming convention as illustrated by **ID_FILE_OPEN**. [Standard Commands](standard-commands.md) explains the standard commands defined by the class library. ## See also diff --git a/docs/mfc/command-routing-classes.md b/docs/mfc/command-routing-classes.md index 267d4b9b8ef..e77f0a2b5bd 100644 --- a/docs/mfc/command-routing-classes.md +++ b/docs/mfc/command-routing-classes.md @@ -4,10 +4,12 @@ title: "Command Routing Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.command"] helpviewer_keywords: ["MFC, command routing", "command routing [MFC], classes"] -ms.assetid: 4b50e689-2c54-4e6c-90f0-37333e22b2a1 --- # Command Routing Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As the user interacts with the application by choosing menus or control-bar buttons with the mouse, the application sends messages from the affected user-interface object to an appropriate command-target object. Command-target classes derived from `CCmdTarget` include [CWinApp](reference/cwinapp-class.md), [CWnd](reference/cwnd-class.md), [CDocTemplate](reference/cdoctemplate-class.md), [CDocument](reference/cdocument-class.md), [CView](reference/cview-class.md), and the classes derived from them. The framework supports automatic command routing so that commands can be handled by the most appropriate object currently active in the application. An object of class `CCmdUI` is passed to your command targets' update command UI ([ON_UPDATE_COMMAND_UI](reference/message-map-macros-mfc.md#on_update_command_ui)) handlers to allow you to update the state of the user interface for a particular command (for instance, to check or remove the check from menu items). You call member functions of the `CCmdUI` object to update the state of the UI object. This process is the same whether the UI object associated with a particular command is a menu item or a button or both. diff --git a/docs/mfc/command-routing-illustration.md b/docs/mfc/command-routing-illustration.md index 53adb566465..4274d6930bd 100644 --- a/docs/mfc/command-routing-illustration.md +++ b/docs/mfc/command-routing-illustration.md @@ -3,10 +3,13 @@ description: "Learn more about: Command Routing Illustration" title: "Command Routing Illustration" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, command routing", "command handling [MFC], routing commands", "command routing [MFC], OnCmdMsg handler"] -ms.assetid: 4b7b4741-565f-4878-b076-fd85c670f87f +ms.topic: how-to --- # Command Routing Illustration +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To illustrate, consider a command message from a Clear All menu item in an MDI application's Edit menu. Suppose the handler function for this command happens to be a member function of the application's document class. Here's how that command reaches its handler after the user chooses the menu item: 1. The main frame window receives the command message first. diff --git a/docs/mfc/command-routing.md b/docs/mfc/command-routing.md index edb23094cdc..8f140daaf38 100644 --- a/docs/mfc/command-routing.md +++ b/docs/mfc/command-routing.md @@ -3,10 +3,13 @@ description: "Learn more about: Command Routing" title: "Command Routing" ms.date: "09/06/2019" helpviewer_keywords: ["MFC, command routing", "command handling [MFC], routing commands", "handlers [MFC]", "handlers, command [MFC]", "command routing"] -ms.assetid: 9393a956-bdd4-47c5-9013-dbd680433f93 +ms.topic: how-to --- # Command Routing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your responsibility in working with commands is limited to making message-map connections between commands and their handler functions, a task for which you use the [MFC Class Wizard](reference/mfc-class-wizard.md). You must also write the code for the command handlers. Windows messages are usually sent to the main frame window, but command messages are then routed to other objects. The framework routes commands through a standard sequence of command-target objects, one of which is expected to have a handler for the command. Each command-target object checks its message map to see if it can handle the incoming message. diff --git a/docs/mfc/command-targets.md b/docs/mfc/command-targets.md index 5e7a2bf8afd..74b9485cd3e 100644 --- a/docs/mfc/command-targets.md +++ b/docs/mfc/command-targets.md @@ -3,10 +3,12 @@ description: "Learn more about: Command Targets" title: "Command Targets" ms.date: "11/04/2016" helpviewer_keywords: ["command targets", "command mapping", "messages, command [MFC]", "command routing [MFC], command targets"] -ms.assetid: b0f784e5-c6dc-4391-9e71-aa7b7dcbe9f0 --- # Command Targets +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The figure [Commands in the Framework](user-interface-objects-and-command-ids.md) shows the connection between a user-interface object, such as a menu item, and the handler function that the framework calls to carry out the resulting command when the object is clicked. Windows sends messages that are not command messages directly to a window whose handler for the message is then called. However, the framework routes commands to a number of candidate objects — called "command targets" — one of which normally invokes a handler for the command. The handler functions work the same way for both commands and standard Windows messages, but the mechanisms by which they are called are different, as explained in [How the Framework Calls a Handler](how-the-framework-calls-a-handler.md). diff --git a/docs/mfc/common-control-sample-list.md b/docs/mfc/common-control-sample-list.md index 4f4e326f4d2..b28e441457f 100644 --- a/docs/mfc/common-control-sample-list.md +++ b/docs/mfc/common-control-sample-list.md @@ -3,10 +3,12 @@ description: "Learn more about: Common Control Sample List" title: "Common Control Sample List" ms.date: "11/04/2016" helpviewer_keywords: ["sample applications [MFC], common controls"] -ms.assetid: 8ae39e2d-12a8-4b17-909d-5bf155749123 --- # Common Control Sample List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + See the following sample programs that illustrate common controls: - [CMNCTRL1](../overview/visual-cpp-samples.md) diff --git a/docs/mfc/common-dialog-classes.md b/docs/mfc/common-dialog-classes.md index f6221b488d6..329144187af 100644 --- a/docs/mfc/common-dialog-classes.md +++ b/docs/mfc/common-dialog-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Common Dialog Classes" title: "Common Dialog Classes" ms.date: "11/04/2016" helpviewer_keywords: ["dialog classes [MFC]", "dialog boxes [MFC], Windows common dialogs", "common dialog boxes [MFC], common dialog classes", "common dialog classes [MFC]", "MFC dialog boxes [MFC], Windows common dialogs", "Windows common dialogs [MFC]", "dialog classes [MFC], common", "common dialog boxes [MFC]"] -ms.assetid: 5c4f6443-896c-4b05-a7df-8169fdadc71d --- # Common Dialog Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In addition to class [CDialog](reference/cdialog-class.md), MFC supplies several classes derived from `CDialog` that encapsulate commonly used dialog boxes, as shown in the following table. The dialog boxes encapsulated are called the "common dialog boxes" and are part of the Windows common dialog library (COMMDLG.DLL). The dialog-template resources and code for these classes are provided in the Windows common dialog boxes that are part of Windows versions 3.1 and later. ### Common Dialog Classes diff --git a/docs/mfc/commonly-added-member-functions.md b/docs/mfc/commonly-added-member-functions.md index b5fb6d99fda..0fb89df0040 100644 --- a/docs/mfc/commonly-added-member-functions.md +++ b/docs/mfc/commonly-added-member-functions.md @@ -3,10 +3,12 @@ description: "Learn more about: Commonly Added Member Functions" title: "Commonly Added Member Functions" ms.date: "11/04/2016" helpviewer_keywords: ["CDialog class [MFC], members", "MFC dialog boxes [MFC], control-notification messages", "dialog classes [MFC], commonly added member functions"] -ms.assetid: f6bd50e8-872a-4039-9996-a85bfccea18d --- # Commonly Added Member Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If your dialog box contains pushbuttons other than OK or Cancel, you need to write message-handler member functions in your dialog class to respond to the control-notification messages they generate. For an example, see the [Scribble](../overview/visual-cpp-samples.md) sample program. You can also handle control-notification messages from other controls in your dialog box. ## See also diff --git a/docs/mfc/commonly-overridden-member-functions.md b/docs/mfc/commonly-overridden-member-functions.md index 41cd982858e..5e25df0d7ef 100644 --- a/docs/mfc/commonly-overridden-member-functions.md +++ b/docs/mfc/commonly-overridden-member-functions.md @@ -3,10 +3,12 @@ description: "Learn more about: Commonly Overridden Member Functions" title: "Commonly Overridden Member Functions" ms.date: "09/06/2019" helpviewer_keywords: ["CDialog class [MFC], members", "OnInitDialog function", "dialog classes [MFC], commonly overridden member functions", "OnCancel function", "overriding, dialog class members", "OnOK function", "MFC dialog boxes [MFC], overriding member functions"] -ms.assetid: 78eb566c-e361-4c86-8db5-c7e2791b249a --- # Commonly Overridden Member Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table lists the most likely member functions to override in your `CDialog`-derived class. ### Commonly Overridden Member Functions of Class CDialog diff --git a/docs/mfc/communicating-with-a-tree-control.md b/docs/mfc/communicating-with-a-tree-control.md index 621df475e70..cc35ab04f2f 100644 --- a/docs/mfc/communicating-with-a-tree-control.md +++ b/docs/mfc/communicating-with-a-tree-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Communicating with a Tree Control" title: "Communicating with a Tree Control" ms.date: "11/04/2016" helpviewer_keywords: ["tree controls [MFC], communicating with", "CTreeCtrl class [MFC], calling member functions", "communications, tree controls", "tree controls"] -ms.assetid: 680ad9ee-b11f-452d-93fa-501ca7d7e069 +ms.topic: concept-article --- # Communicating with a Tree Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You use different methods for calling member functions in a [CTreeCtrl](reference/ctreectrl-class.md) object depending on how the object was created: - If the tree control is in a dialog box, use a member variable of type `CTreeCtrl` that you create in the dialog box class. diff --git a/docs/mfc/connection-points.md b/docs/mfc/connection-points.md index fff0b34d7c8..239f9206513 100644 --- a/docs/mfc/connection-points.md +++ b/docs/mfc/connection-points.md @@ -4,10 +4,12 @@ title: "Connection Points" ms.date: "11/19/2018" f1_keywords: ["IConnectionPoint"] helpviewer_keywords: ["IConnectionPoint interface", "connections, connection points", "OLE COM connection points", "MFC COM, connection points", "COM, connection points", "interfaces, IConnectionPoint", "MFC, COM support", "connection points [MFC]", "CCmdTarget class [MFC], and connection points", "sinks, connection points"] -ms.assetid: bc9fd7c7-8df6-4752-ac8c-0b177442c88d --- # Connection Points +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to implement connection points (formerly known as OLE connection points) using the MFC classes `CCmdTarget` and `CConnectionPoint`. In the past, the Component Object Model (COM) defined a general mechanism (`IUnknown::QueryInterface`*) that allowed objects to implement and expose functionality in interfaces. However, a corresponding mechanism that allowed objects to expose their capability to call specific interfaces was not defined. That is, COM defined how incoming pointers to objects (pointers to that object's interfaces) were handled, but it did not have an explicit model for outgoing interfaces (pointers the object holds to other objects' interfaces). COM now has a model, called connection points, that supports this functionality. diff --git a/docs/mfc/containers-advanced-features.md b/docs/mfc/containers-advanced-features.md index 41c1ce872bf..e4eff569a72 100644 --- a/docs/mfc/containers-advanced-features.md +++ b/docs/mfc/containers-advanced-features.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers: Advanced Features" title: "Containers: Advanced Features" ms.date: "11/04/2016" helpviewer_keywords: ["links [MFC], to embedded OLE objects", "containers [MFC], links to embedded OLE objects", "containers [MFC], advanced features", "container/server applications [MFC]", "embedded objects [MFC]", "OLE controls [MFC], containers", "OLE containers [MFC], advanced features", "server/container applications [MFC]", "containers [MFC], container applications"] -ms.assetid: 221fd99c-b138-40fa-ad6a-974e3b3ad1f8 --- # Containers: Advanced Features +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the steps necessary to incorporate optional advanced features into existing container applications. These features are: - [An application that is both a container and a server](#_core_creating_a_container_server_application) diff --git a/docs/mfc/containers-client-item-notifications.md b/docs/mfc/containers-client-item-notifications.md index aff7be898fc..81b3d44d4b9 100644 --- a/docs/mfc/containers-client-item-notifications.md +++ b/docs/mfc/containers-client-item-notifications.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers: Client-Item Notifications" title: "Containers: Client-Item Notifications" ms.date: "11/04/2016" helpviewer_keywords: ["notifications [MFC], container client item", "OLE containers [MFC], client-item notifications", "client items and OLE containers"] -ms.assetid: e1f1c427-01f5-45f2-b496-c5bce3d76340 --- # Containers: Client-Item Notifications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses the overridable functions that the MFC framework calls when server applications modify items in your client application's document. [COleClientItem](reference/coleclientitem-class.md) defines several overridable functions that are called in response to requests from the component application, which is also called the server application. These overridables usually act as notifications. They inform the container application of various events, such as scrolling, activation, or a change of position, and of changes that the user makes when editing or otherwise manipulating the item. diff --git a/docs/mfc/containers-client-item-states.md b/docs/mfc/containers-client-item-states.md index 3c0cd589309..a457c8b1b25 100644 --- a/docs/mfc/containers-client-item-states.md +++ b/docs/mfc/containers-client-item-states.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers: Client-Item States" title: "Containers: Client-Item States" ms.date: "11/04/2016" helpviewer_keywords: ["OLE containers [MFC], client-item states", "states, OLE container client-item", "lifetime, lifetime states and OLE container client items", "client items and OLE containers"] -ms.assetid: e7021caa-bd07-4adb-976e-f5f3d025bc53 --- # Containers: Client-Item States +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the different states a client item passes through in its lifetime. A client item passes through several states as it is created, activated, modified, and saved. Each time the item's state changes, the framework calls [COleClientItem::OnChange](reference/coleclientitem-class.md#onchange) with the **OLE_CHANGED_STATE** notification. The second parameter is a value from the `COleClientItem::ItemState` enumeration. It can be one of the following: diff --git a/docs/mfc/containers-client-items.md b/docs/mfc/containers-client-items.md index f2e17257faa..9778f9c51c1 100644 --- a/docs/mfc/containers-client-items.md +++ b/docs/mfc/containers-client-items.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers: Client Items" title: "Containers: Client Items" ms.date: "11/04/2016" helpviewer_keywords: ["OLE containers [MFC], client items", "client items and OLE containers"] -ms.assetid: 231528b5-0744-4f83-8897-083bf55ed087 --- # Containers: Client Items +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains what client items are and from what classes your application should derive its client items. Client items are data items belonging to another application that are either contained in or referenced by an OLE container application's document. Client items whose data is contained within the document are embedded; those whose data is stored in another location referenced by the container document are linked. diff --git a/docs/mfc/containers-compound-files.md b/docs/mfc/containers-compound-files.md index 0ae34087ac0..bfd759966e5 100644 --- a/docs/mfc/containers-compound-files.md +++ b/docs/mfc/containers-compound-files.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers: Compound Files" title: "Containers: Compound Files" ms.date: "11/04/2016" helpviewer_keywords: ["compound files [MFC]", "compound documents", "containers [MFC], compound files", "OLE documents [MFC], compound files", "performance [MFC], compound files", "files [MFC], compound", "standardized file structure compound files", "documents [MFC], compound", "documents [MFC], OLE", "OLE containers [MFC], compound files", "access modes for files [MFC]"] -ms.assetid: 8b83cb3e-76c8-4bbe-ba16-737092b36f49 --- # Containers: Compound Files +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the components and implementation of compound files and the advantages and disadvantages of using compound files in your OLE applications. Compound files are an integral part of OLE. They are used to facilitate data transfer and OLE document storage. Compound files are an implementation of the Active structured storage model. Consistent interfaces exist that support serialization to a storage, a stream, or a file object. Compound files are supported in the Microsoft Foundation Class Library by the classes `COleStreamFile` and `COleDocument`. diff --git a/docs/mfc/containers-for-activex-controls.md b/docs/mfc/containers-for-activex-controls.md index 6f6926c793a..08fb52eff64 100644 --- a/docs/mfc/containers-for-activex-controls.md +++ b/docs/mfc/containers-for-activex-controls.md @@ -3,11 +3,13 @@ description: "Learn more about: Containers for ActiveX Controls" title: "Containers for ActiveX Controls" ms.date: "09/12/2018" helpviewer_keywords: ["ActiveX control containers [MFC], application support"] -ms.assetid: 5ff0bf37-07f4-49aa-ad9c-c63d3756243a --- # Containers for ActiveX Controls -You can use ActiveX controls developed in Visual C++ in other applications, as long as they support ActiveX control containment. A number of Microsoft applications, beginning with the versions listed, support ActiveX control containment. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +You can use ActiveX controls developed in Visual Studio in other applications, as long as they support ActiveX control containment. A number of Microsoft applications, beginning with the versions listed, support ActiveX control containment. >[!IMPORTANT] > ActiveX is a legacy technology that should not be used for new development. For more information about modern technologies that supersede ActiveX, see [ActiveX Controls](activex-controls.md). diff --git a/docs/mfc/containers-implementing-a-container.md b/docs/mfc/containers-implementing-a-container.md index c6dbc10dc32..4fa39bc520c 100644 --- a/docs/mfc/containers-implementing-a-container.md +++ b/docs/mfc/containers-implementing-a-container.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers: Implementing a Container" title: "Containers: Implementing a Container" ms.date: "11/04/2016" helpviewer_keywords: ["applications [OLE], OLE container", "OLE containers [MFC], implementing"] -ms.assetid: af1e2079-619a-4eac-9327-985ad875823a --- # Containers: Implementing a Container +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article summarizes the procedure for implementing a container and points you to other articles that provide more detailed explanations about implementing containers. It also lists some optional OLE features you may want to implement and the articles describing these features. #### To prepare your CWinApp-derived class diff --git a/docs/mfc/containers-user-interface-issues.md b/docs/mfc/containers-user-interface-issues.md index 1e9cd232f72..94b3f0aa1d9 100644 --- a/docs/mfc/containers-user-interface-issues.md +++ b/docs/mfc/containers-user-interface-issues.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers: User-Interface Issues" title: "Containers: User-Interface Issues" ms.date: "11/04/2016" helpviewer_keywords: ["containers [MFC], user-interface issues", "OLE containers [MFC], user interface", "user interface issues"] -ms.assetid: c833c249-a633-4f1c-82d6-ec6b4892863a --- # Containers: User-Interface Issues +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You must add a number of features to a container application's user interface to adequately manage linked and embedded items. These features involve changes to the menu structure and to the events that the application handles. For detailed information about them, see the following articles: |For information on|See| diff --git a/docs/mfc/containers.md b/docs/mfc/containers.md index a7fff2b8a52..8936ef14fca 100644 --- a/docs/mfc/containers.md +++ b/docs/mfc/containers.md @@ -3,10 +3,12 @@ description: "Learn more about: Containers" title: "Containers" ms.date: "11/04/2016" helpviewer_keywords: ["containers [MFC]", "OLE containers", "application containers [MFC]", "containers [MFC], OLE container applications", "containers [MFC], container applications"] -ms.assetid: b19d7c05-4d02-44bd-b76a-4a6c25994a62 --- # Containers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A container application is an application that can incorporate embedded or linked items into its own documents. The documents managed by a container application must be able to store and display OLE compound document components as well as data created by the application itself. A container application must also allow users to insert new items or edit existing items. ## In This Section diff --git a/docs/mfc/control-bar-classes.md b/docs/mfc/control-bar-classes.md index 83d7dc63c7e..e24776d9fd5 100644 --- a/docs/mfc/control-bar-classes.md +++ b/docs/mfc/control-bar-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Control Bar Classes" title: "Control Bar Classes" ms.date: "11/04/2016" helpviewer_keywords: ["control bars [MFC], classes"] -ms.assetid: 11009103-cad8-4309-85ce-3d2e858e1818 --- # Control Bar Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Control bars are attached to a frame window. They contain buttons, status panes, or a dialog template. Free-floating control bars, also called tool palettes, are implemented by attaching them to a [CMiniFrameWnd](reference/cminiframewnd-class.md) object. ## Framework Control Bars diff --git a/docs/mfc/control-bars.md b/docs/mfc/control-bars.md index 70b65d5e778..d4aa5c879e2 100644 --- a/docs/mfc/control-bars.md +++ b/docs/mfc/control-bars.md @@ -3,10 +3,12 @@ description: "Learn more about: Control Bars" title: "Control Bars" ms.date: "11/04/2016" helpviewer_keywords: ["command bars [MFC], types of", "toolbars [MFC], control bars", "control bars [MFC]", "MFC, control bars", "control bars [MFC], types of", "CDialogBar class [MFC], control bars", "status bars [MFC], control bars", "CControlBar class [MFC], MFC control bars", "dialog bars [MFC], control bars", "CToolBar class [MFC], control bars", "CStatusBar class [MFC], control bars"] -ms.assetid: 31831910-3d23-4d70-9e71-03cc02f01ec4 --- # Control Bars +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + "Control bar" is the general name for toolbars, status bars, and dialog bars. MFC classes `CToolBar`, `CStatusBar`, `CDialogBar`, `COleResizeBar`, and `CReBar` derive from class [CControlBar](reference/ccontrolbar-class.md), which implements their common functionality. Control bars are windows that display rows of controls with which users can select options, execute commands, or obtain program information. Types of control bars include toolbars, dialog bars, and status bars. diff --git a/docs/mfc/control-classes.md b/docs/mfc/control-classes.md index 39a211802cc..10517c135b1 100644 --- a/docs/mfc/control-classes.md +++ b/docs/mfc/control-classes.md @@ -4,10 +4,12 @@ title: "Control Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.control"] helpviewer_keywords: ["static display controls [MFC]", "control classes [MFC]", "buttons, MFC control classes", "controls [MFC], MFC control classes", "controls [MFC]", "list boxes [MFC], MFC control classes", "control classes [MFC], MFC", "text, controls for input [MFC]", "user input [MFC], MFC control classes"] -ms.assetid: f9876606-9f5b-44cb-9135-213298d1df8f --- # Control Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Control classes encapsulate a wide variety of standard Windows controls ranging from static text controls to tree controls. In addition, MFC provides some new controls, including buttons with bitmaps and control bars. The controls whose class names end in "**Ctrl**" were new in Windows 95 and Windows NT version 3.51. diff --git a/docs/mfc/controls-mfc.md b/docs/mfc/controls-mfc.md index fda1eeccf12..c5801b29796 100644 --- a/docs/mfc/controls-mfc.md +++ b/docs/mfc/controls-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Controls (MFC)" title: "Controls (MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["Windows common controls [MFC]", "common controls [MFC]", "controls [MFC]"] -ms.assetid: b2842884-6435-4b8f-933b-21671bf8af95 --- # Controls (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Controls are objects that users can interact with to enter or manipulate data. They commonly appear in dialog boxes or on toolbars. This topic family covers three main kinds of controls: - Windows common controls, including owner-drawn controls @@ -17,7 +19,7 @@ Controls are objects that users can interact with to enter or manipulate data. T ## Windows Common Controls -The Windows operating system has always provided a number of Windows common controls. These control objects are programmable, and the Visual C++ dialog editor supports adding them to your dialog boxes. The Microsoft Foundation Class Library (MFC) supplies classes that encapsulate each of these controls, as shown in the table [Windows Common Controls and MFC Classes](#_core_windows_common_controls_and_mfc_classes). (Some items in the table have related topics that describe them further. For controls that lack topics, see the documentation for the MFC class.) +The Windows operating system has always provided a number of Windows common controls. These control objects are programmable, and the Visual Studio dialog editor supports adding them to your dialog boxes. The Microsoft Foundation Class Library (MFC) supplies classes that encapsulate each of these controls, as shown in the table [Windows Common Controls and MFC Classes](#_core_windows_common_controls_and_mfc_classes). (Some items in the table have related topics that describe them further. For controls that lack topics, see the documentation for the MFC class.) Class [CWnd](reference/cwnd-class.md) is the base class of all window classes, including all of the control classes. diff --git a/docs/mfc/creating-a-ctoolbarctrl-object.md b/docs/mfc/creating-a-ctoolbarctrl-object.md index 8e8af2739ef..f5bc8b35611 100644 --- a/docs/mfc/creating-a-ctoolbarctrl-object.md +++ b/docs/mfc/creating-a-ctoolbarctrl-object.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating a CToolBarCtrl Object" title: "Creating a CToolBarCtrl Object" ms.date: "11/04/2016" helpviewer_keywords: ["toolbar controls [MFC], creating", "CToolBarCtrl class [MFC], creating toolbars"] -ms.assetid: a4f6bf0c-0195-4dbf-a09e-aee503e19dc3 +ms.topic: how-to --- # Creating a CToolBarCtrl Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [CToolBarCtrl](reference/ctoolbarctrl-class.md) objects contain several internal data structures — a list of button image bitmaps, a list of button label strings, and a list of `TBBUTTON` structures — that associate an image and/or string with the position, style, state, and command ID of the button. Each of the elements of these data structures is referred to by a zero-based index. Before you can use a `CToolBarCtrl` object, you must set up these data structures. For a list of the data structures, see [Toolbar Controls](controls-mfc.md) in the Windows SDK. The list of strings can only be used for button labels; you cannot retrieve strings from the toolbar. To use a `CToolBarCtrl` object, you will typically follow these steps: diff --git a/docs/mfc/creating-a-dialog-class-with-code-wizards.md b/docs/mfc/creating-a-dialog-class-with-code-wizards.md index 372dc65cd7b..392782ede1d 100644 --- a/docs/mfc/creating-a-dialog-class-with-code-wizards.md +++ b/docs/mfc/creating-a-dialog-class-with-code-wizards.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating a Dialog Class with Code Wizards" title: "Creating a Dialog Class with Code Wizards" ms.date: "11/04/2016" helpviewer_keywords: ["dialog boxes [MFC], creating", "MFC dialog boxes, creating", "code wizards", "dialog classes [MFC], creating"] -ms.assetid: a7157b9d-f1a8-4381-a4cf-180cd2c7f1b2 +ms.topic: concept-article --- # Creating a Dialog Class with Code Wizards +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table lists dialog-related tasks that Code Wizards help you manage. ### Dialog-Related Tasks diff --git a/docs/mfc/creating-a-modeless-property-sheet.md b/docs/mfc/creating-a-modeless-property-sheet.md index 83f9ef25951..0301f3ffcbc 100644 --- a/docs/mfc/creating-a-modeless-property-sheet.md +++ b/docs/mfc/creating-a-modeless-property-sheet.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating a Modeless Property Sheet" title: "Creating a Modeless Property Sheet" ms.date: "11/04/2016" helpviewer_keywords: ["modeless property sheets", "property sheets, modeless", "Create method [MFC], property sheets"] -ms.assetid: eafd8a92-cc67-4a69-a5fb-742c920d1ae8 +ms.topic: concept-article --- # Creating a Modeless Property Sheet +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Normally, the property sheets you create will be modal. When using a modal property sheet, the user must close the property sheet before using any other part of the application. This article describes methods you can use to create a modeless property sheet that allows the user to keep the property sheet open while using other parts of the application. To display a property sheet as a modeless dialog box instead of as a modal dialog box, call [CPropertySheet::Create](reference/cpropertysheet-class.md#create) instead of [DoModal](reference/cpropertysheet-class.md#domodal). You must also implement some extra tasks to support a modeless property sheet. diff --git a/docs/mfc/creating-a-rebar-control.md b/docs/mfc/creating-a-rebar-control.md index 8aec855df37..08b253503eb 100644 --- a/docs/mfc/creating-a-rebar-control.md +++ b/docs/mfc/creating-a-rebar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating a Rebar Control" title: "Creating a Rebar Control" ms.date: "11/04/2016" helpviewer_keywords: ["rebar controls [MFC], creating", "CReBarCtrl class [MFC], creating"] -ms.assetid: 0a012e08-772b-4f6a-af86-7cb651d11d3e +ms.topic: how-to --- # Creating a Rebar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [CReBarCtrl](reference/crebarctrl-class.md) objects should be created before the parent object is visible. This minimizes the possibilities of painting problems. For instance, rebar controls (used in frame window objects) are commonly used as parent windows for toolbar controls. Therefore, the parent of the rebar control is the frame window object. Because the frame window object is the parent, the `OnCreate` member function (of the parent) is an excellent place to create the rebar control. diff --git a/docs/mfc/creating-an-active-document-container-application.md b/docs/mfc/creating-an-active-document-container-application.md index f0cd926a641..397172bbc4c 100644 --- a/docs/mfc/creating-an-active-document-container-application.md +++ b/docs/mfc/creating-an-active-document-container-application.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating an Active Document Container Applicatio title: "Creating an Active Document Container Application" ms.date: "11/04/2016" helpviewer_keywords: ["active documents [MFC], containers", "containers [MFC], active document", "active document containers [MFC], creating", "MFC COM, active document containment", "applications [MFC], active document container"] -ms.assetid: 14e2d022-a6c5-4249-8712-706b0f4433f7 +ms.topic: how-to --- # Creating an Active Document Container Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The simplest and most recommended way to create an active document container application is to create an MFC EXE container application using the MFC Application Wizard, then modify the application to support active document containment. #### To create an active document container application diff --git a/docs/mfc/creating-an-extended-combo-box-control.md b/docs/mfc/creating-an-extended-combo-box-control.md index 9f266d75164..3d49c2a16d3 100644 --- a/docs/mfc/creating-an-extended-combo-box-control.md +++ b/docs/mfc/creating-an-extended-combo-box-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating an Extended Combo Box Control" title: "Creating an Extended Combo Box Control" ms.date: "11/04/2016" helpviewer_keywords: ["extended combo boxes", "CComboBoxEx class [MFC], creating extended combo box controls", "extended combo boxes [MFC], creating"] -ms.assetid: a964267e-97b6-4e77-9f89-55bb5c68913f +ms.topic: how-to --- # Creating an Extended Combo Box Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + How the extended combo box control is created depends on whether you are using the control in a dialog box or creating it in a nondialog window. ### To use CComboBoxEx directly in a dialog box diff --git a/docs/mfc/creating-and-displaying-dialog-boxes.md b/docs/mfc/creating-and-displaying-dialog-boxes.md index 918e0c938bd..cb4c355f408 100644 --- a/docs/mfc/creating-and-displaying-dialog-boxes.md +++ b/docs/mfc/creating-and-displaying-dialog-boxes.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating and Displaying Dialog Boxes" title: "Creating and Displaying Dialog Boxes" ms.date: "11/04/2016" helpviewer_keywords: ["modal dialog boxes [MFC], creating", "opening dialog boxes", "modeless dialog boxes [MFC], creating", "MFC dialog boxes [MFC], creating", "MFC dialog boxes [MFC], displaying"] -ms.assetid: 1c5219ee-8b46-44bc-9708-83705d4f248b +ms.topic: concept-article --- # Creating and Displaying Dialog Boxes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Creating a dialog object is a two-phase operation. First, construct the dialog object, then create the dialog window. Modal and modeless dialog boxes differ somewhat in the process used to create and display them. The following table lists how modal and modeless dialog boxes are normally constructed and displayed. ### Dialog Creation diff --git a/docs/mfc/creating-document-frame-windows.md b/docs/mfc/creating-document-frame-windows.md index b79b488838c..8004e63a1ac 100644 --- a/docs/mfc/creating-document-frame-windows.md +++ b/docs/mfc/creating-document-frame-windows.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating Document Frame Windows" title: "Creating Document Frame Windows" ms.date: "11/04/2016" helpviewer_keywords: ["frame windows [MFC], creating", "document templates [MFC], and document frame windows", "windows [MFC], creating", "runtime, class information", "run-time class [MFC], and document frame window creation", "document frame windows [MFC], creating", "MFC, frame windows"] -ms.assetid: 8671e239-b76f-4dea-afa8-7024e6e58ff5 +ms.topic: concept-article --- # Creating Document Frame Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [Document/View Creation](document-view-creation.md) shows how the [CDocTemplate](reference/cdoctemplate-class.md) object orchestrates creating the frame window, document, and view and connecting them all together. Three [CRuntimeClass](reference/cruntimeclass-structure.md) arguments to the `CDocTemplate` constructor specify the frame window, document, and view classes that the document template creates dynamically in response to user commands such as the New command on the File menu or the New Window command on an MDI Window menu. The document template stores this information for later use when it creates a frame window for a view and document. For the [RUNTIME_CLASS](reference/run-time-object-model-services.md#runtime_class) mechanism to work correctly, your derived frame-window classes must be declared with the [DECLARE_DYNCREATE](reference/run-time-object-model-services.md#declare_dyncreate) macro. This is because the framework needs to create document frame windows using the dynamic construction mechanism of class `CObject`. diff --git a/docs/mfc/creating-modal-dialog-boxes.md b/docs/mfc/creating-modal-dialog-boxes.md index 269f02812d0..a9a4c045f99 100644 --- a/docs/mfc/creating-modal-dialog-boxes.md +++ b/docs/mfc/creating-modal-dialog-boxes.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating Modal Dialog Boxes" title: "Creating Modal Dialog Boxes" ms.date: "11/04/2016" helpviewer_keywords: ["modal dialog boxes [MFC], creating", "MFC dialog boxes [MFC], creating", "MFC dialog boxes [MFC], modal"] -ms.assetid: 26c7a68c-79f6-4862-a5a8-6024984644d2 +ms.topic: concept-article --- # Creating Modal Dialog Boxes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To create a modal dialog box, call either of the two public constructors declared in [CDialog](reference/cdialog-class.md). Next, call the dialog object's [DoModal](reference/cdialog-class.md#domodal) member function to display the dialog box and manage interaction with it until the user chooses OK or Cancel. This management by `DoModal` is what makes the dialog box modal. For modal dialog boxes, `DoModal` loads the dialog resource. ## See also diff --git a/docs/mfc/creating-modeless-dialog-boxes.md b/docs/mfc/creating-modeless-dialog-boxes.md index 44fdf5e7405..4c730a660a6 100644 --- a/docs/mfc/creating-modeless-dialog-boxes.md +++ b/docs/mfc/creating-modeless-dialog-boxes.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating Modeless Dialog Boxes" title: "Creating Modeless Dialog Boxes" ms.date: "11/04/2016" helpviewer_keywords: ["MFC dialog boxes [MFC], modeless", "modeless dialog boxes [MFC], creating", "MFC dialog boxes [MFC], creating"] -ms.assetid: 70d78c7f-3d40-477b-9f78-0f33c359f88b +ms.topic: concept-article --- # Creating Modeless Dialog Boxes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For a modeless dialog box, you must provide your own public constructor in your dialog class. To create a modeless dialog box, call your public constructor and then call the dialog object's [Create](reference/cdialog-class.md#create) member function to load the dialog resource. You can call **Create** either during or after the constructor call. If the dialog resource has the property **WS_VISIBLE**, the dialog box appears immediately. If not, you must call its [ShowWindow](reference/cwnd-class.md#showwindow) member function. ## See also diff --git a/docs/mfc/creating-new-documents-windows-and-views.md b/docs/mfc/creating-new-documents-windows-and-views.md index 2137a6f149a..43a0eca8ee3 100644 --- a/docs/mfc/creating-new-documents-windows-and-views.md +++ b/docs/mfc/creating-new-documents-windows-and-views.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating New Documents, Windows, and Views" title: "Creating New Documents, Windows, and Views" ms.date: "11/19/2018" helpviewer_keywords: ["MDI [MFC], creating windows", "window objects [MFC], creating", "objects [MFC], creating document objects", "MFC default objects", "frame windows [MFC], creating", "windows [MFC], MDI", "MFC, documents", "view objects [MFC], creating", "windows [MFC], creating", "overriding, default view behavior", "views [MFC], initializing", "customizing MFC default objects", "MFC, frame windows", "MFC, views", "MDI [MFC], frame windows", "child windows [MFC], creating MDI", "view objects [MFC]", "document objects [MFC], creating", "MFC default objects [MFC], customizing", "views [MFC], overriding default behavior", "initializing views [MFC]"] -ms.assetid: 88aa1f5f-2078-4603-b16b-a2b4c7b4a2a3 +ms.topic: concept-article --- # Creating New Documents, Windows, and Views +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following figures give an overview of the creation process for documents, views, and frame windows. Other articles that focus on the participating objects provide further details. Upon completion of this process, the cooperating objects exist and store pointers to each other. The following figures show the sequence in which objects are created. You can follow the sequence from figure to figure. diff --git a/docs/mfc/creating-stack-and-queue-collections.md b/docs/mfc/creating-stack-and-queue-collections.md index 36c7c40c713..f61a62a9391 100644 --- a/docs/mfc/creating-stack-and-queue-collections.md +++ b/docs/mfc/creating-stack-and-queue-collections.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating Stack and Queue Collections" title: "Creating Stack and Queue Collections" ms.date: "11/04/2016" helpviewer_keywords: ["MFC collection classes [MFC], stack collections", "collections, stack", "stack", "collection classes [MFC], creating", "queue collections", "MFC collection classes [MFC], queue collections", "stack collections", "collections, queue"] -ms.assetid: 3c7bc198-35f0-4fc3-aaed-6005a0f22638 +ms.topic: how-to --- # Creating Stack and Queue Collections +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to create other data structures, such as [stacks](#_core_stacks) and [queues](#_core_queues), from MFC list classes. The examples use classes derived from `CList`, but you can use `CList` directly unless you need to add functionality. ## Stacks diff --git a/docs/mfc/creating-the-date-and-time-picker-control.md b/docs/mfc/creating-the-date-and-time-picker-control.md index 7e9b2348967..633c5441142 100644 --- a/docs/mfc/creating-the-date-and-time-picker-control.md +++ b/docs/mfc/creating-the-date-and-time-picker-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating the Date and Time Picker Control" title: "Creating the Date and Time Picker Control" ms.date: "11/04/2016" helpviewer_keywords: ["DateTimePicker control [MFC], creating", "CDateTimeCtrl class [MFC], creating"] -ms.assetid: 764ec2fb-98cd-478b-a5f2-d63f0bb12279 +ms.topic: how-to --- # Creating the Date and Time Picker Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + How the date and time picker control is created depends on whether you are using the control in a dialog box or creating it in a nondialog window. ### To use CDateTimeCtrl directly in a dialog box diff --git a/docs/mfc/creating-the-dialog-resource.md b/docs/mfc/creating-the-dialog-resource.md index 7ccf5adb5b8..811a843a8aa 100644 --- a/docs/mfc/creating-the-dialog-resource.md +++ b/docs/mfc/creating-the-dialog-resource.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating the Dialog Resource" title: "Creating the Dialog Resource" ms.date: "11/04/2016" helpviewer_keywords: ["dialog resources", "MFC dialog boxes [MFC], creating", "dialog templates [MFC], creating dialog resource", "templates [MFC], creating", "resources [MFC], creating dialog boxes", "MFC dialog boxes [MFC], dialog resource"] -ms.assetid: 0b83bd33-14d3-4611-8129-fccdae18053e +ms.topic: concept-article --- # Creating the Dialog Resource +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To design the [dialog box](dialog-boxes.md) and create the dialog resource, you use the [dialog editor](../windows/dialog-editor.md). In the dialog editor, you can: - Adjust the size and location your dialog box will have when it appears. diff --git a/docs/mfc/creating-the-header-control.md b/docs/mfc/creating-the-header-control.md index 2afab96c98b..9ed0680f794 100644 --- a/docs/mfc/creating-the-header-control.md +++ b/docs/mfc/creating-the-header-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating the Header Control" title: "Creating the Header Control" ms.date: "11/04/2016" helpviewer_keywords: ["CHeaderCtrl class [MFC], creating", "header controls [MFC], creating"] -ms.assetid: 7864d9d2-4a2c-4622-b58b-7b110a1e28d2 +ms.topic: how-to --- # Creating the Header Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The header control is not directly available in the dialog editor (although you can add a list control, which includes a header control). ### To put a header control in a dialog box diff --git a/docs/mfc/creating-the-image-lists.md b/docs/mfc/creating-the-image-lists.md index 537f21582c2..39744f3dc26 100644 --- a/docs/mfc/creating-the-image-lists.md +++ b/docs/mfc/creating-the-image-lists.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating the Image Lists" title: "Creating the Image Lists" ms.date: "11/04/2016" helpviewer_keywords: ["CListCtrl class [MFC], creating image lists for", "image lists [MFC], creating for CListCtrl", "lists [MFC], image"] -ms.assetid: c2768515-deba-49e8-a6f3-5be6482afb19 +ms.topic: concept-article --- # Creating the Image Lists +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Creating image lists is the same whether you use [CListView](reference/clistview-class.md) or [CListCtrl](reference/clistctrl-class.md). > [!NOTE] diff --git a/docs/mfc/creating-the-list-control.md b/docs/mfc/creating-the-list-control.md index 3d3ae78237d..d5944f1b37b 100644 --- a/docs/mfc/creating-the-list-control.md +++ b/docs/mfc/creating-the-list-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating the List Control" title: "Creating the List Control" ms.date: "11/04/2016" helpviewer_keywords: ["CListCtrl class [MFC], creating control", "list controls [MFC]"] -ms.assetid: a4cb1729-31b6-4d2b-a44b-367474848a39 +ms.topic: how-to --- # Creating the List Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + How the list control ([CListCtrl](reference/clistctrl-class.md)) is created depends on whether you're using the control directly or using class [CListView](reference/clistview-class.md) instead. If you use `CListView`, the framework constructs the view as part of its document/view creation sequence. Creating the list view creates the list control as well (the two are the same thing). The control is created in the view's [OnCreate](reference/cwnd-class.md#oncreate) handler function. In this case, the control is ready for you to add items, via a call to [GetListCtrl](reference/clistview-class.md#getlistctrl). ### To use CListCtrl directly in a dialog box diff --git a/docs/mfc/creating-the-month-calendar-control.md b/docs/mfc/creating-the-month-calendar-control.md index 623738f5816..92ff0854f8e 100644 --- a/docs/mfc/creating-the-month-calendar-control.md +++ b/docs/mfc/creating-the-month-calendar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating the Month Calendar Control" title: "Creating the Month Calendar Control" ms.date: "11/04/2016" helpviewer_keywords: ["CMonthCalCtrl class [MFC], creating", "month calendar controls [MFC], creating", "month calendar controls [MFC]"] -ms.assetid: 185cc642-85e9-4365-8a4c-d90b75b010f7 +ms.topic: how-to --- # Creating the Month Calendar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + How the month calendar control is created depends on whether you are using the control in a dialog box or creating it in a nondialog window. ### To use CMonthCalCtrl directly in a dialog box diff --git a/docs/mfc/creating-the-tab-control.md b/docs/mfc/creating-the-tab-control.md index 4cad7fbd53d..f8db4aabfc9 100644 --- a/docs/mfc/creating-the-tab-control.md +++ b/docs/mfc/creating-the-tab-control.md @@ -4,10 +4,13 @@ title: "Creating the Tab Control" ms.date: "11/04/2016" f1_keywords: ["TCS_EX_REGISTERDROP", "TCS_EX_FLATSEPARATORS"] helpviewer_keywords: ["TCS_EX_REGISTERDROP extended style [MFC]", "tab controls [MFC], creating", "CTabCtrl class [MFC], creating", "TCS_EX_FLATSEPARATORS extended style"] -ms.assetid: 3a9c2d64-f5f4-41ea-84ab-fceb73c3dbdc +ms.topic: how-to --- # Creating the Tab Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + How the tab control is created depends on whether you are using the control in a dialog box or creating it in a nondialog window. ### To use CTabCtrl directly in a dialog box diff --git a/docs/mfc/creating-windows.md b/docs/mfc/creating-windows.md index 93dd62fceb4..0c1a016b3bb 100644 --- a/docs/mfc/creating-windows.md +++ b/docs/mfc/creating-windows.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating Windows" title: "Creating Windows" ms.date: "11/04/2016" helpviewer_keywords: ["object creation [MFC], windows", "windows [MFC], creating", "CWnd objects [MFC]", "CWnd objects [MFC], creating"] -ms.assetid: f5ff91a6-4069-47d7-9177-1e6c80d3792c +ms.topic: concept-article --- # Creating Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The framework automatically creates most of the windows you need in a framework program. [Document/View Creation](document-view-creation.md) shows how the framework creates the frame windows associated with documents and views. But for special purposes you can create your own windows — including your own child windows of frame windows or views — in addition to the windows supplied by the framework. ## What do you want to know more about diff --git a/docs/mfc/creating-your-dialog-class.md b/docs/mfc/creating-your-dialog-class.md index 2c750d4504c..c637e47bc34 100644 --- a/docs/mfc/creating-your-dialog-class.md +++ b/docs/mfc/creating-your-dialog-class.md @@ -3,10 +3,13 @@ description: "Learn more about: Creating Your Dialog Class" title: "Creating Your Dialog Class" ms.date: "09/06/2019" helpviewer_keywords: ["dialog boxes [MFC], creating", "MFC dialog boxes [MFC], creating", "files [MFC], creating", "dialog classes [MFC], Add Class Wizard", "dialog classes [MFC], creating"] -ms.assetid: d5321741-da41-47a8-bb1c-6a0e8b28c4c1 +ms.topic: concept-article --- # Creating Your Dialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For each dialog box in your program, create a new dialog class to work with the dialog resource. [Adding a Class](../ide/adding-a-class-visual-cpp.md) explains how to create a new dialog class. When you create a dialog class with the [Class Wizard](reference/mfc-class-wizard.md), it writes the following items in the .h and .cpp files you specify: diff --git a/docs/mfc/crebar-vs-crebarctrl.md b/docs/mfc/crebar-vs-crebarctrl.md index 6750c3db526..8e03bf97fca 100644 --- a/docs/mfc/crebar-vs-crebarctrl.md +++ b/docs/mfc/crebar-vs-crebarctrl.md @@ -3,15 +3,17 @@ description: "Learn more about: CReBar vs. CReBarCtrl" title: "CReBar vs. CReBarCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CReBar class [MFC], vs. CReBarCtrl", "rebar controls [MFC], CReBarCtrl class [MFC]", "GetReBarCtrl class [MFC]"] -ms.assetid: 7f9c1d7e-5d5f-4956-843c-69ed3df688d0 --- # CReBar vs. CReBarCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC provides two classes to create rebars: [CReBar](reference/crebar-class.md) and [CReBarCtrl](reference/crebarctrl-class.md) (which wraps the Windows common control API). `CReBar` provides all of the functionality of the rebar common control, and it handles many of the required common control settings and structures for you. `CReBarCtrl` is a wrapper class for the Win32 rebar control, and therefore may be easier to implement if you do not intend to integrate the rebar into the MFC architecture. If you plan to use `CReBarCtrl` and integrate the rebar into the MFC architecture, you must take additional care to communicate rebar control manipulations to MFC. This communication is not difficult; however, it is additional work that is unneeded when you use `CReBar`. -Visual C++ provides two ways to take advantage of the rebar common control. +Visual Studio provides two ways to take advantage of the rebar common control. - Create the rebar using `CReBar`, and then call [CReBar::GetReBarCtrl](reference/crebar-class.md#getrebarctrl) to get access to the `CReBarCtrl` member functions. diff --git a/docs/mfc/ctreectrl-vs-ctreeview.md b/docs/mfc/ctreectrl-vs-ctreeview.md index bc46617de0a..08205c2d697 100644 --- a/docs/mfc/ctreectrl-vs-ctreeview.md +++ b/docs/mfc/ctreectrl-vs-ctreeview.md @@ -3,10 +3,12 @@ description: "Learn more about: CTreeCtrl vs. CTreeView" title: "CTreeCtrl vs. CTreeView" ms.date: "11/04/2016" helpviewer_keywords: ["tree view controls", "CTreeCtrl class [MFC], vs. CTreeView class [MFC]", "CTreeView class [MFC], vs. CTreeCtrl class [MFC]", "tree controls [MFC], and tree view"] -ms.assetid: bba5af25-103f-4b53-84d3-071bc9bd6494 --- # CTreeCtrl vs. CTreeView +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC provides two classes that encapsulate tree controls: [CTreeCtrl](reference/ctreectrl-class.md) and [CTreeView](reference/ctreeview-class.md). Each class is useful in different situations. Use `CTreeCtrl` when you need a plain child window control; for instance, in a dialog box. You'd especially want to use `CTreeCtrl` if there will be other child controls in the window, as in a typical dialog box. diff --git a/docs/mfc/current-selection-in-a-rich-edit-control.md b/docs/mfc/current-selection-in-a-rich-edit-control.md index 71ba0c09d26..77b23d0394b 100644 --- a/docs/mfc/current-selection-in-a-rich-edit-control.md +++ b/docs/mfc/current-selection-in-a-rich-edit-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Current Selection in a Rich Edit Control" title: "Current Selection in a Rich Edit Control" ms.date: "11/04/2016" helpviewer_keywords: ["current selection in CRichEditCtrls", "CRichEditCtrl class [MFC], current selection in", "rich edit controls [MFC], current selection in", "selection, current in CRichEditCtrl"] -ms.assetid: f6b2a2b6-5481-4ad3-9720-6dd772ea6fc8 --- # Current Selection in a Rich Edit Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The user can select text in a rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)) by using the mouse or the keyboard. The current selection is the range of selected characters, or the position of the insertion point if no characters are selected. An application can get information about the current selection, set the current selection, determine when the current selection changes, and show or hide the selection highlight. To determine the current selection in a rich edit control, use the [GetSel](reference/cricheditctrl-class.md#getsel) member function. To set the current selection, use the [SetSel](reference/cricheditctrl-class.md#setsel) member function. The [CHARRANGE](/windows/win32/api/richedit/ns-richedit-charrange) structure is used with these functions to specify a range of characters. To retrieve information about the contents of the current selection, you can use the [GetSelectionType](reference/cricheditctrl-class.md#getselectiontype) member function. diff --git a/docs/mfc/customization-for-mfc.md b/docs/mfc/customization-for-mfc.md index 2ab4a09f1d1..f8e4330ef35 100644 --- a/docs/mfc/customization-for-mfc.md +++ b/docs/mfc/customization-for-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Customization for MFC" title: "Customization for MFC" ms.date: "11/04/2016" helpviewer_keywords: ["customizations, MFC Extensions"] -ms.assetid: 3b1b7532-8cc9-48dc-9bbe-7fd4060530b5 --- # Customization for MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic provides tips for customizing an MFC application. ## General Customizations diff --git a/docs/mfc/customizing-the-appearance-of-a-toolbar-control.md b/docs/mfc/customizing-the-appearance-of-a-toolbar-control.md index f69fbb571af..5825ee08448 100644 --- a/docs/mfc/customizing-the-appearance-of-a-toolbar-control.md +++ b/docs/mfc/customizing-the-appearance-of-a-toolbar-control.md @@ -4,10 +4,13 @@ title: "Customizing the Appearance of a Toolbar Control" ms.date: "11/04/2016" f1_keywords: ["TBSTYLE_"] helpviewer_keywords: ["flat toolbars", "CToolBar class [MFC], styles", "transparent toolbars", "TBSTYLE_ styles [MFC]", "CToolBarCtrl class [MFC], object styles", "toolbar controls [MFC], style"] -ms.assetid: fd0a73db-7ad1-4fe4-889b-02c3980f49e8 +ms.topic: concept-article --- # Customizing the Appearance of a Toolbar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Class `CToolBarCtrl` provides many styles that affect the appearance (and, occasionally, the behavior) of the toolbar object. Modify the toolbar object by setting the `dwCtrlStyle` parameter of the `CToolBarCtrl::Create` (or `CToolBar::CreateEx`) member function, when you first create the toolbar control. The following styles affect the "3D" aspect of the toolbar buttons and the placement of the button text: diff --git a/docs/mfc/customizing-the-header-item-s-appearance.md b/docs/mfc/customizing-the-header-item-s-appearance.md index 8a47aec3d32..990ecb305fe 100644 --- a/docs/mfc/customizing-the-header-item-s-appearance.md +++ b/docs/mfc/customizing-the-header-item-s-appearance.md @@ -3,10 +3,13 @@ description: "Learn more about: Customizing the Header Item's Appearance" title: "Customizing the Header Item's Appearance" ms.date: "11/04/2016" helpviewer_keywords: ["header controls [MFC], customization of items", "CHeaderCtrl class [MFC], customizing the items", "HDS_ styles"] -ms.assetid: b1e1e326-ec7d-4dbd-a46f-96a3e2055618 +ms.topic: concept-article --- # Customizing the Header Item's Appearance +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By setting the *dwStyle* parameter when you first create a header control ([CHeaderCtrl::Create](reference/cheaderctrl-class.md#create)), you can define the appearance and behavior of header items or of the header control itself. Here is a sampling of the styles you can set, and their purpose: diff --git a/docs/mfc/cwinapp-and-the-mfc-application-wizard.md b/docs/mfc/cwinapp-and-the-mfc-application-wizard.md index 530934f7d79..7e8e4cd5464 100644 --- a/docs/mfc/cwinapp-and-the-mfc-application-wizard.md +++ b/docs/mfc/cwinapp-and-the-mfc-application-wizard.md @@ -3,10 +3,12 @@ description: "Learn more about: CWinApp and the MFC Application Wizard" title: "CWinApp and the MFC Application Wizard" ms.date: "11/04/2016" helpviewer_keywords: ["application wizards [MFC], and CWinApp", "CWinApp class [MFC], and MFC Application Wizard", "MFC, wizards"] -ms.assetid: f8ac0491-3302-4e46-981d-0790624eb8a2 --- # CWinApp and the MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When it creates a skeleton application, the MFC Application Wizard declares an application class derived from [CWinApp](reference/cwinapp-class.md). The MFC Application Wizard also generates an implementation file that contains the following items: - A message map for the application class. diff --git a/docs/mfc/cwinapp-the-application-class.md b/docs/mfc/cwinapp-the-application-class.md index ba5a5f0062f..b24b92f4b3f 100644 --- a/docs/mfc/cwinapp-the-application-class.md +++ b/docs/mfc/cwinapp-the-application-class.md @@ -3,10 +3,12 @@ description: "Learn more about: CWinApp: The Application Class" title: "CWinApp: The Application Class" ms.date: "11/04/2016" helpviewer_keywords: ["application class [MFC]", "CWinApp class [MFC], CWinThread", "MFC, WinMain and", "CWinApp class [MFC], multithreading", "CWinThread class [MFC], and CWinApp", "InitApplication method [MFC]", "WinMain method [MFC]", "WinMain method [MFC], in MFC", "CWinApp class [MFC], WinMain"] -ms.assetid: 935822bb-d463-481b-a5f6-9719d68ed1d5 --- # CWinApp: The Application Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The main application class in MFC encapsulates the initialization, running, and termination of an application for the Windows operating system. An application built on the framework must have one and only one object of a class derived from [CWinApp](reference/cwinapp-class.md). This object is constructed before windows are created. `CWinApp` is derived from `CWinThread`, which represents the main thread of execution for your application, which might have one or more threads. In recent versions of MFC, the `InitInstance`, **Run**, `ExitInstance`, and `OnIdle` member functions are actually in class `CWinThread`. These functions are discussed here as if they were `CWinApp` members instead, because the discussion concerns the object's role as application object rather than as primary thread. @@ -19,7 +21,7 @@ Like any program for the Windows operating system, your framework application ha To initialize the application, `WinMain` calls your application object's `InitApplication` and `InitInstance` member functions. To run the application's message loop, `WinMain` calls the **Run** member function. On termination, `WinMain` calls the application object's `ExitInstance` member function. > [!NOTE] -> Names shown in **bold** in this documentation indicate elements supplied by the Microsoft Foundation Class Library and Visual C++. Names shown in `monospaced` type indicate elements that you create or override. +> Names shown in **bold** in this documentation indicate elements supplied by the Microsoft Foundation Class Library and Visual Studio. Names shown in `monospaced` type indicate elements that you create or override. ## See also diff --git a/docs/mfc/dao-classes.md b/docs/mfc/dao-classes.md index ad16f3fe673..f7dcafbd128 100644 --- a/docs/mfc/dao-classes.md +++ b/docs/mfc/dao-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: DAO Classes" title: "DAO Classes" ms.date: "09/17/2019" helpviewer_keywords: ["database classes [MFC], DAO", "DAO [MFC], classes"] -ms.assetid: b15d0cd6-328b-4288-9c19-d037a795db57 --- # DAO Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. These classes work with the other application framework classes to give easy access to Data Access Object (DAO) databases, which use the same database engine as Microsoft Visual Basic and Microsoft Access. The DAO classes can also access a wide variety of databases for which Open Database Connectivity (ODBC) drivers are available. @@ -14,7 +16,7 @@ These classes work with the other application framework classes to give easy acc Programs that use DAO databases will have at least a `CDaoDatabase` object and a `CDaoRecordset` object. > [!NOTE] -> The Visual C++ environment and wizards no longer support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use ODBC for new MFC projects. You should only use DAO in maintaining existing applications. +> The Visual Studio environment and wizards no longer support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use ODBC for new MFC projects. You should only use DAO in maintaining existing applications. [CDaoWorkspace](reference/cdaoworkspace-class.md)
Manages a named, password-protected database session from login to logoff. Most programs use the default workspace. diff --git a/docs/mfc/data-objects-and-data-sources-creation-and-destruction.md b/docs/mfc/data-objects-and-data-sources-creation-and-destruction.md index 440ec543ee4..55a6a472b33 100644 --- a/docs/mfc/data-objects-and-data-sources-creation-and-destruction.md +++ b/docs/mfc/data-objects-and-data-sources-creation-and-destruction.md @@ -3,10 +3,12 @@ description: "Learn more about: Data Objects and Data Sources: Creation and Dest title: "Data Objects and Data Sources: Creation and Destruction" ms.date: "11/04/2016" helpviewer_keywords: ["destroying data objects [MFC]", "object creation [MFC], data source objects", "data sources [MFC], and data objects", "data source objects [MFC], creating", "destruction [MFC], data sources", "data source objects [MFC], destroying", "data objects [MFC], creating", "data objects [MFC], destroying", "data sources [MFC], role", "data sources [MFC], destroying", "destruction [MFC], data objects", "data sources [MFC], creating"] -ms.assetid: ac216d54-3ca5-4ce7-850d-cd1f6a90d4f1 --- # Data Objects and Data Sources: Creation and Destruction +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As explained in the article [Data Objects and Data Sources (OLE)](data-objects-and-data-sources-ole.md), data objects and data sources represent both sides of a data transfer. This article explains when to create and destroy these objects and sources to perform your data transfers properly, including: - [Creating data objects](#_core_creating_data_objects) diff --git a/docs/mfc/data-objects-and-data-sources-manipulation.md b/docs/mfc/data-objects-and-data-sources-manipulation.md index 012da4d435b..44b560e727f 100644 --- a/docs/mfc/data-objects-and-data-sources-manipulation.md +++ b/docs/mfc/data-objects-and-data-sources-manipulation.md @@ -3,10 +3,12 @@ description: "Learn more about: Data Objects and Data Sources: Manipulation" title: "Data Objects and Data Sources: Manipulation" ms.date: "11/04/2016" helpviewer_keywords: ["data objects [MFC], manipulating", "data sources [MFC], data operations", "data sources [MFC], inserting data", "Clipboard [MFC], determining available formats", "OLE [MFC], data objects", "Clipboard [MFC], passing format information", "data sources [MFC], determining available formats", "delayed rendering [MFC]", "OLE [MFC], data sources"] -ms.assetid: f7f27e77-bb5d-4131-b819-d71bf929ebaf --- # Data Objects and Data Sources: Manipulation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + After a data object or data source has been created, you can perform a number of common operations on the data, such as inserting and removing data, enumerating the formats the data is in, and more. This article describes the techniques necessary to complete the most common operations. Topics include: - [Inserting data into a data source](#_core_inserting_data_into_a_data_source) diff --git a/docs/mfc/data-objects-and-data-sources-ole.md b/docs/mfc/data-objects-and-data-sources-ole.md index 5b5e949d4f0..a3b803d8bd8 100644 --- a/docs/mfc/data-objects-and-data-sources-ole.md +++ b/docs/mfc/data-objects-and-data-sources-ole.md @@ -3,10 +3,12 @@ description: "Learn more about: Data Objects and Data Sources (OLE)" title: "Data Objects and Data Sources (OLE)" ms.date: "11/04/2016" helpviewer_keywords: ["data objects [MFC], definition", "data transfer [MFC]", "OLE [MFC], data transfer", "data sources [MFC], definition", "data transfer [MFC], definition", "OLE [MFC], data objects", "OLE [MFC], data sources"] -ms.assetid: 8f68eed8-0ce8-4489-a4cc-f95554f89090 --- # Data Objects and Data Sources (OLE) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you perform a data transfer, either by using the Clipboard or drag and drop, the data has a source and a destination. One application provides the data for copying and another application accepts it for pasting. Each side of the transfer needs to perform different operations on the same data for the transfer to succeed. The Microsoft Foundation Class (MFC) Library provides two classes that represent each side of this transfer: - Data sources (as implemented by `COleDataSource` objects) represent the source side of the data transfer. They are created by the source application when data is to be copied to the Clipboard, or when data is provided for a drag-and-drop operation. diff --git a/docs/mfc/date-and-time-picker-control-examples.md b/docs/mfc/date-and-time-picker-control-examples.md index 26eb0b317a0..10d189a5237 100644 --- a/docs/mfc/date-and-time-picker-control-examples.md +++ b/docs/mfc/date-and-time-picker-control-examples.md @@ -3,10 +3,12 @@ description: "Learn more about: Date and Time Picker Control Examples" title: "Date and Time Picker Control Examples" ms.date: "11/04/2016" helpviewer_keywords: ["DateTimePicker control [MFC]"] -ms.assetid: f03c3a22-7725-45eb-8f8e-dddb2d15c3ca --- # Date and Time Picker Control Examples +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CMNCTRL1](../overview/visual-cpp-samples.md) sample demonstrates the various attributes of the `CDateTimeCtrl` class. A separate page contains a date and time picker control that the user can manipulate by changing various attributes and testing the basic functionality of the control. ## See also diff --git a/docs/mfc/debugging-and-exception-classes.md b/docs/mfc/debugging-and-exception-classes.md index 74df8a9f60a..aa2e150d6cf 100644 --- a/docs/mfc/debugging-and-exception-classes.md +++ b/docs/mfc/debugging-and-exception-classes.md @@ -4,10 +4,13 @@ title: "Debugging and Exception Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.debug"] helpviewer_keywords: ["debugging [MFC], exception classes", "debugging [MFC], classes for debugging"] -ms.assetid: 0d158efd-2e62-452e-9d2a-d3c30dfee7f9 +ms.topic: concept-article --- # Debugging and Exception Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes provide support for debugging dynamic memory allocation and for passing exception information from the function where the exception is thrown to the function where it is caught. Use classes [CDumpContext](reference/cdumpcontext-class.md) and [CMemoryState](reference/cmemorystate-structure.md) during development to assist with debugging, as described in [Debugging MFC Applications](/visualstudio/debugger/mfc-debugging-techniques). Use [CRuntimeClass](reference/cruntimeclass-structure.md) to determine the class of any object at run time, as described in the article [Accessing Run-Time Class Information](accessing-run-time-class-information.md). The framework uses `CRuntimeClass` to create objects of a particular class dynamically. diff --git a/docs/mfc/debugging-support-classes.md b/docs/mfc/debugging-support-classes.md index 558f225543e..1e40250262b 100644 --- a/docs/mfc/debugging-support-classes.md +++ b/docs/mfc/debugging-support-classes.md @@ -3,10 +3,13 @@ description: "Learn more about: Debugging Support Classes" title: "Debugging Support Classes" ms.date: "11/04/2016" helpviewer_keywords: ["debugging memory leaks, MFC", "memory allocation, debugging dynamic", "debugging [MFC], classes for debugging", "memory allocation, debugging dynamic allocation", "dynamic memory allocation", "debugging [MFC], memory leaks", "memory leaks, MFC debug classes"] -ms.assetid: d79e084a-8326-4251-8700-4efac07c511e +ms.topic: concept-article --- # Debugging Support Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC provides the following classes to help you debug dynamic memory allocation problems. [CDumpContext](reference/cdumpcontext-class.md)
diff --git a/docs/mfc/declaring-message-handler-functions.md b/docs/mfc/declaring-message-handler-functions.md index 04adeb9627f..d917ba04e53 100644 --- a/docs/mfc/declaring-message-handler-functions.md +++ b/docs/mfc/declaring-message-handler-functions.md @@ -3,10 +3,13 @@ description: "Learn more about: Declaring Message Handler Functions" title: "Declaring Message Handler Functions" ms.date: "11/04/2016" helpviewer_keywords: ["declaring functions, message handler functions [MFC]"] -ms.assetid: f8d3dbc1-4500-4f1e-a18d-7371edf36386 +ms.topic: concept-article --- # Declaring Message Handler Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Certain rules and conventions govern the names of your message-handler functions. These depend on the message category, as described in the following topics: - [Handlers for standard Windows messages](handlers-for-standard-windows-messages.md) diff --git a/docs/mfc/deleting-all-objects-in-a-cobject-collection.md b/docs/mfc/deleting-all-objects-in-a-cobject-collection.md index 116c8782044..8e78fc10564 100644 --- a/docs/mfc/deleting-all-objects-in-a-cobject-collection.md +++ b/docs/mfc/deleting-all-objects-in-a-cobject-collection.md @@ -3,10 +3,13 @@ description: "Learn more about: Deleting All Objects in a CObject Collection" title: "Deleting All Objects in a CObject Collection" ms.date: "11/04/2016" helpviewer_keywords: ["objects [MFC], deleting in collections", "objects in CObject collections, deleting", "CObject class [MFC], deleting in collection", "collection classes [MFC], deleting all objects", "CObject class collection", "objects in CObject collections", "collection classes [MFC], shared objects"] -ms.assetid: 81d2c1d5-a0a5-46e1-8ab9-82b45cf7afd2 +ms.topic: how-to --- # Deleting All Objects in a CObject Collection +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to delete all objects in a collection (without deleting the collection object itself). To delete all the objects in a collection of `CObject`s (or of objects derived from `CObject`), you use one of the iteration techniques described in the article [Accessing All Members of a Collection](accessing-all-members-of-a-collection.md) to delete each object in turn. diff --git a/docs/mfc/deprecated-ansi-apis.md b/docs/mfc/deprecated-ansi-apis.md index 6268b9613e7..6fd26ff2d70 100644 --- a/docs/mfc/deprecated-ansi-apis.md +++ b/docs/mfc/deprecated-ansi-apis.md @@ -3,10 +3,12 @@ description: "Learn more about: Deprecated ANSI APIs" title: "Deprecated ANSI APIs" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, ANSI deprecated methods"] -ms.assetid: c7c5a6fd-95e4-4bee-b3d5-d3826c30947d --- # Deprecated ANSI APIs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class (MFC) library is migrating toward classes and methods that are based on the Unicode character set. Consequently, the ANSI versions of several MFC methods are deprecated. Use the Unicode versions of these methods in your future applications. Starting with Windows Common Controls version 6.1, which ships in Windows Vista, the following ANSI methods are deprecated. diff --git a/docs/mfc/derived-message-maps.md b/docs/mfc/derived-message-maps.md index 97dd244acdc..f178feedb75 100644 --- a/docs/mfc/derived-message-maps.md +++ b/docs/mfc/derived-message-maps.md @@ -3,10 +3,12 @@ title: "Derived Message Maps" description: "Describes MFC message handling." ms.date: "09/23/2020" helpviewer_keywords: ["message handling [MFC], derived message handlers", "messages, routing", "message maps [MFC], derived", "derived message maps"] -ms.assetid: 21829556-6e64-40c3-8279-fed85d99de77 --- # Derived Message Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + During message handling, checking a class's own message map is not the end of the message-map story. What happens if class `CMyView` (derived from `CView`) has no matching entry for a message? Keep in mind that `CView`, the base class of `CMyView`, is derived in turn from `CWnd`. Thus `CMyView` *is* a `CView` and *is* a `CWnd`. Each of those classes has its own message map. The figure below shows the hierarchical relationship of the classes, but keep in mind that a `CMyView` object is a single object that has the characteristics of all three classes. diff --git a/docs/mfc/derived-view-classes-available-in-mfc.md b/docs/mfc/derived-view-classes-available-in-mfc.md index e0831af6ac6..852150b4b4a 100644 --- a/docs/mfc/derived-view-classes-available-in-mfc.md +++ b/docs/mfc/derived-view-classes-available-in-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Derived View Classes Available in MFC" title: "Derived View Classes Available in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["CView class [MFC], classes derived from", "classes [MFC], derived", "derived classes [MFC], view classes", "view classes [MFC], derived"] -ms.assetid: dba42178-7459-4ccc-b025-f3d9b8a4b737 --- # Derived View Classes Available in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows MFC's view classes and their relationships to one another. The capabilities of your view class depend on the MFC view class from which it derives. ### View Classes @@ -18,7 +20,7 @@ The following table shows MFC's view classes and their relationships to one anot |[CEditView](reference/ceditview-class.md)|A simple view based on the Windows edit box control. Allows entering and editing text and can be used as the basis for a simple text editor application. See also `CRichEditView`.| |[CRichEditView](reference/cricheditview-class.md)|A view containing a [CRichEditCtrl](reference/cricheditctrl-class.md) object. This class is analogous to `CEditView`, but unlike `CEditView`, `CRichEditView` handles formatted text.| |[CListView](reference/clistview-class.md)|A view containing a [CListCtrl](reference/clistctrl-class.md) object.| -|[CTreeView](reference/ctreeview-class.md)|A view containing a [CTreeCtrl](reference/ctreectrl-class.md) object, for views that resemble the Solution Explorer window in Visual C++.| +|[CTreeView](reference/ctreeview-class.md)|A view containing a [CTreeCtrl](reference/ctreectrl-class.md) object, for views that resemble the Solution Explorer window in Visual Studio.| |[CScrollView](reference/cscrollview-class.md)|Base class of `CFormView`, `CRecordView`, and `CDaoRecordView`. Implements scrolling the view's contents.| |[CFormView](reference/cformview-class.md)|A form view, a view that contains controls. A forms-based application provides one or more such form interfaces.| |[CHtmlView](reference/chtmlview-class.md)|A Web browser view with which the application's user can browse sites on the World Wide Web, as well as folders in the local file system and on a network. The Web browser view can also work as an Active document container.| diff --git a/docs/mfc/derived-window-classes.md b/docs/mfc/derived-window-classes.md index 8102ecae4f0..2f6f1b9221c 100644 --- a/docs/mfc/derived-window-classes.md +++ b/docs/mfc/derived-window-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Derived window classes" title: "Derived window classes" ms.date: "11/04/2016" helpviewer_keywords: ["window class hierarchy", "hierarchies, window classes", "classes [MFC], derived", "CWnd class [MFC], classes derived from", "derived classes [MFC], window classes", "window classes [MFC], derived"] -ms.assetid: 6f7e437e-fbde-4a06-bfab-72d9dbf05292 --- # Derived window classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can create windows directly from [`CWnd`](reference/cwnd-class.md), or derive new window classes from `CWnd`. It's how you typically create your own custom windows. However, most windows used in a framework program are instead created from one of the `CWnd`-derived frame-window classes supplied by MFC. ## Frame window classes diff --git a/docs/mfc/deriving-a-class-from-cobject.md b/docs/mfc/deriving-a-class-from-cobject.md index 3e290c2a4c5..20793426d80 100644 --- a/docs/mfc/deriving-a-class-from-cobject.md +++ b/docs/mfc/deriving-a-class-from-cobject.md @@ -3,10 +3,13 @@ description: "Learn more about: Deriving a Class from CObject" title: "Deriving a Class from CObject" ms.date: "11/04/2016" helpviewer_keywords: ["DECLARE_DYNCREATE macro [MFC]", "DECLARE_SERIAL macro [MFC]", "macros [MFC], serialization", "serialization [MFC], macros", "DECLARE_DYNAMIC macro [MFC]", "derived classes [MFC], from CObject", "CObject class [MFC], deriving serializable classes", "CObject class [MFC], deriving from"] -ms.assetid: 5ea4ea41-08b5-4bd8-b247-c5de8c152a27 +ms.topic: how-to --- # Deriving a Class from CObject +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the minimum steps necessary to derive a class from [CObject](reference/cobject-class.md). Other `CObject` class articles describe the steps needed to take advantage of specific `CObject` features, such as serialization and diagnostic debugging support. In the discussions of `CObject`, the terms "interface file" and "implementation file" are used frequently. The interface file (often called the header file, or .H file) contains the class declaration and any other information needed to use the class. The implementation file (or .CPP file) contains the class definition as well as the code that implements the class member functions. For example, for a class named `CPerson`, you would typically create an interface file named PERSON.H and an implementation file named PERSON.CPP. However, for some small classes that will not be shared among applications, it is sometimes easier to combine the interface and implementation into a single .CPP file. diff --git a/docs/mfc/deriving-a-document-class-from-cdocument.md b/docs/mfc/deriving-a-document-class-from-cdocument.md index db461ebc77c..67e3cbdb776 100644 --- a/docs/mfc/deriving-a-document-class-from-cdocument.md +++ b/docs/mfc/deriving-a-document-class-from-cdocument.md @@ -3,10 +3,13 @@ description: "Learn more about: Deriving a Document Class from CDocument" title: "Deriving a Document Class from CDocument" ms.date: "11/04/2016" helpviewer_keywords: ["CDocument class [MFC], deriving from", "classes [MFC], deriving from CDocument", "document objects [MFC], derived", "derived classes [MFC], functions often overridden", "document classes [MFC], functions often overridden"] -ms.assetid: e6a198e0-9799-43c0-83c5-04174d8b532c +ms.topic: concept-article --- # Deriving a Document Class from CDocument +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Documents contain and manage your application's data. To use the MFC Application Wizard-supplied document class, you must do the following: - Derive a class from `CDocument` for each type of document. diff --git a/docs/mfc/deriving-controls-from-a-standard-control.md b/docs/mfc/deriving-controls-from-a-standard-control.md index 87576b2f0fb..eec1f103ace 100644 --- a/docs/mfc/deriving-controls-from-a-standard-control.md +++ b/docs/mfc/deriving-controls-from-a-standard-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Deriving Controls from a Standard Control" title: "Deriving Controls from a Standard Control" ms.date: "11/04/2016" helpviewer_keywords: ["standard controls [MFC], deriving controls from", "common controls [MFC], deriving from", "derived controls", "controls [MFC], derived", "Windows common controls [MFC], deriving from", "standard controls"] -ms.assetid: a6f84315-7007-4e0e-8576-78be81254802 +ms.topic: how-to --- # Deriving Controls from a Standard Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As with any [CWnd](reference/cwnd-class.md)-derived class, you can modify a control's behavior by deriving a new class from an existing control class. ### To create a derived control class diff --git a/docs/mfc/destroying-frame-windows.md b/docs/mfc/destroying-frame-windows.md index a640fe5351f..ae0d33b240c 100644 --- a/docs/mfc/destroying-frame-windows.md +++ b/docs/mfc/destroying-frame-windows.md @@ -4,10 +4,13 @@ title: "Destroying Frame Windows" ms.date: "11/04/2016" f1_keywords: ["PostNcDestroy"] helpviewer_keywords: ["Default method [MFC]", "DestroyWindow method [MFC]", "frame windows [MFC], destroying", "OnNcDestroy method, and frame windows", "document frame windows [MFC], destroying", "destroying frame windows", "MFC, frame windows", "windows [MFC], destroying", "OnClose method [MFC]", "PostNcDestroy method [MFC]"] -ms.assetid: 5affca77-1999-4507-a2b2-9aa226611b4b +ms.topic: concept-article --- # Destroying Frame Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The MFC framework manages window destruction as well as creation for those windows associated with framework documents and views. If you create additional windows, you are responsible for destroying them. In the framework, when the user closes the frame window, the window's default [OnClose](reference/cwnd-class.md#onclose) handler calls [DestroyWindow](reference/cwnd-class.md#destroywindow). The last member function called when the Windows window is destroyed is [OnNcDestroy](reference/cwnd-class.md#onncdestroy), which does some cleanup, calls the [Default](reference/cwnd-class.md#default) member function to perform Windows cleanup, and lastly calls the virtual member function [PostNcDestroy](reference/cwnd-class.md#postncdestroy). The [CFrameWnd](reference/cframewnd-class.md) implementation of `PostNcDestroy` deletes the C++ window object. You should never use the C++ **`delete`** operator on a frame window. Use `DestroyWindow` instead. diff --git a/docs/mfc/destroying-the-dialog-box.md b/docs/mfc/destroying-the-dialog-box.md index 1c0da1b3a81..b519e064233 100644 --- a/docs/mfc/destroying-the-dialog-box.md +++ b/docs/mfc/destroying-the-dialog-box.md @@ -3,10 +3,13 @@ description: "Learn more about: Destroying the Dialog Box" title: "Destroying the Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["dialog boxes [MFC], deleting", "destruction, dialog box", "dialog boxes [MFC], destroying", "dialog boxes [MFC], removing", "modeless dialog boxes [MFC], destroying", "MFC dialog boxes [MFC], destroying", "modal dialog boxes [MFC], destroying"] -ms.assetid: dabceee7-3639-4d85-bf34-73515441b3d0 +ms.topic: concept-article --- # Destroying the Dialog Box +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Modal dialog boxes are normally created on the stack frame and destroyed when the function that created them ends. The dialog object's destructor is called when the object goes out of scope. Modeless dialog boxes are normally created and owned by a parent view or frame window — the application's main frame window or a document frame window. The default [OnClose](reference/cwnd-class.md#onclose) handler calls [DestroyWindow](reference/cwnd-class.md#destroywindow), which destroys the dialog-box window. If the dialog box stands alone, with no pointers to it or other special ownership semantics, you should override [PostNcDestroy](reference/cwnd-class.md#postncdestroy) to destroy the C++ dialog object. You should also override [OnCancel](reference/cdialog-class.md#oncancel) and call `DestroyWindow` from within it. If not, the owner of the dialog box should destroy the C++ object when it is no longer necessary. diff --git a/docs/mfc/destroying-the-list-control.md b/docs/mfc/destroying-the-list-control.md index ac0a7fbcdf0..38792c165d3 100644 --- a/docs/mfc/destroying-the-list-control.md +++ b/docs/mfc/destroying-the-list-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Destroying the List Control" title: "Destroying the List Control" ms.date: "11/04/2016" helpviewer_keywords: ["list controls [MFC], destroying", "CListCtrl class [MFC], destroying controls"] -ms.assetid: 513ec820-3a02-49d2-b073-a6a7a3fc91b3 +ms.topic: concept-article --- # Destroying the List Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you embed your [CListCtrl](reference/clistctrl-class.md) object as a data member of a view or dialog class, it is destroyed when its owner is destroyed. If you use a [CListView](reference/clistview-class.md), the framework destroys the control when it destroys the view. If you arrange for some of your list data to be stored in the application rather than the list control, you will need to arrange for its deallocation. For more information, see [Callback Items and the Callback Mask](/windows/win32/Controls/using-list-view-controls) in the Windows SDK. diff --git a/docs/mfc/destroying-window-objects.md b/docs/mfc/destroying-window-objects.md index 462e4a379f5..9ef30b2dc40 100644 --- a/docs/mfc/destroying-window-objects.md +++ b/docs/mfc/destroying-window-objects.md @@ -3,10 +3,13 @@ description: "Learn more about: Destroying Window Objects" title: "Destroying Window Objects" ms.date: "11/04/2016" helpviewer_keywords: ["frame windows [MFC], destroying", "window objects [MFC], deleting", "window objects [MFC], destroying", "window objects [MFC], removing"] -ms.assetid: 3241fea0-c614-4a25-957d-20f21bd5fd0c +ms.topic: concept-article --- # Destroying Window Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Care must be taken with your own child windows to destroy the C++ window object when the user is finished with the window. If these objects are not destroyed, your application will not recover their memory. Fortunately, the framework manages window destruction as well as creation for frame windows, views, and dialog boxes. If you create additional windows, you are responsible for destroying them. ## What do you want to know more about diff --git a/docs/mfc/detaching-a-cwnd-from-its-hwnd.md b/docs/mfc/detaching-a-cwnd-from-its-hwnd.md index 213b8ed1995..ce2d2c3d3e2 100644 --- a/docs/mfc/detaching-a-cwnd-from-its-hwnd.md +++ b/docs/mfc/detaching-a-cwnd-from-its-hwnd.md @@ -3,10 +3,13 @@ description: "Learn more about: Detaching a CWnd from Its HWND" title: "Detaching a CWnd from Its HWND" ms.date: "11/04/2016" helpviewer_keywords: ["HWND, detaching CWnd from", "removing HWNDs from CWnds", "CWnd objects [MFC], detaching from HWND", "detaching CWnds from HWNDs", "Detach method (CWnd class)"] -ms.assetid: 6efadf84-0517-4a3f-acfd-216e088f19c6 +ms.topic: concept-article --- # Detaching a CWnd from Its HWND +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you need to circumvent the object-`HWND` relationship, MFC provides another `CWnd` member function, [Detach](reference/cwnd-class.md#detach), which disconnects the C++ window object from the Windows window. This prevents the destructor from destroying the Windows window when the object is destroyed. ## What do you want to know more about diff --git a/docs/mfc/device-contexts.md b/docs/mfc/device-contexts.md index 6662d7c60ec..535c3f4debf 100644 --- a/docs/mfc/device-contexts.md +++ b/docs/mfc/device-contexts.md @@ -3,10 +3,12 @@ description: "Learn more about: Device Contexts" title: "Device Contexts" ms.date: "11/04/2016" helpviewer_keywords: ["OnPrepareDC method [MFC]", "windows [MFC], and device context", "drawing [MFC], device context", "CClientDC class [MFC], and GetDC method [MFC]", "drawing [MFC], in mouse and device contexts", "CDC class [MFC], objects", "device contexts [MFC]", "client areas", "CMetaFileDC class [MFC], and OnPrepareDC method [MFC]", "GDI objects [MFC], device contexts", "graphic objects [MFC], device contexts", "frame windows [MFC], device contexts", "metafiles and device contexts", "EndPaint method [MFC]", "printers [MFC], device contexts", "mouse [MFC], drawing and device contexts", "BeginPaint method, CPaintDC", "CPaintDC class [MFC], device context for painting", "windows [MFC], drawing directly into", "client areas, and device context", "device contexts [MFC], CDC class [MFC]", "user interface [MFC], device contexts", "device-independent drawing", "GetDC method and CClientDC class [MFC]", "CClientDC class [MFC], and ReleaseDC method [MFC]", "ReleaseDC method [MFC]", "device contexts [MFC], about device contexts", "drawing [MFC], directly into windows", "painting and device context"] -ms.assetid: d0cd51f1-f778-4c7e-bf50-d738d10433c7 --- # Device Contexts +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A device context is a Windows data structure containing information about the drawing attributes of a device such as a display or a printer. All drawing calls are made through a device-context object, which encapsulates the Windows APIs for drawing lines, shapes, and text. Device contexts allow device-independent drawing in Windows. Device contexts can be used to draw to the screen, to the printer, or to a metafile. [CPaintDC](reference/cpaintdc-class.md) objects encapsulate the common idiom of Windows, calling the `BeginPaint` function, then drawing in the device context, then calling the `EndPaint` function. The `CPaintDC` constructor calls `BeginPaint` for you, and the destructor calls `EndPaint`. The simplified process is to create the [CDC](reference/cdc-class.md) object, draw, and then destroy the `CDC` object. In the framework, much of even this process is automated. In particular, your `OnDraw` function is passed a `CPaintDC` already prepared (via `OnPrepareDC`), and you simply draw into it. It is destroyed by the framework and the underlying device context is released to Windows upon return from the call to your `OnDraw` function. diff --git a/docs/mfc/dialog-bars.md b/docs/mfc/dialog-bars.md index 3e1b3cb5fba..269c5c03e94 100644 --- a/docs/mfc/dialog-bars.md +++ b/docs/mfc/dialog-bars.md @@ -3,13 +3,15 @@ description: "Learn more about: Dialog Bars" title: "Dialog Bars" ms.date: "11/19/2018" helpviewer_keywords: ["MFC, control bars", "CDialogBar class [MFC], dialog bars", "control bars [MFC], dialog bars", "dialog bars", "dialog bars [MFC], about dialog bars"] -ms.assetid: 485c8055-6bb0-4051-8417-dd2971499321 --- # Dialog Bars +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A dialog bar is a toolbar, a kind of [control bar](control-bars.md) that can contain any kind of control. Because it has the characteristics of a modeless dialog box, a [CDialogBar](reference/cdialogbar-class.md) object provides a more powerful toolbar. -There are several key differences between a toolbar and a `CDialogBar` object. A `CDialogBar` object is created from a dialog-template resource, which you can create with the Visual C++ dialog editor and which can contain any kind of Windows control. The user can tab from control to control. And you can specify an alignment style to align the dialog bar with any part of the parent frame window or even to leave it in place if the parent is resized. The following figure shows a dialog bar with a variety of controls. +There are several key differences between a toolbar and a `CDialogBar` object. A `CDialogBar` object is created from a dialog-template resource, which you can create with the Visual Studio dialog editor and which can contain any kind of Windows control. The user can tab from control to control. And you can specify an alignment style to align the dialog bar with any part of the parent frame window or even to leave it in place if the parent is resized. The following figure shows a dialog bar with a variety of controls. ![Example of a VC Dialog Bar.](../mfc/media/vc378t1.gif "VC Dialog Bar")
A Dialog Bar diff --git a/docs/mfc/dialog-box-classes.md b/docs/mfc/dialog-box-classes.md index 2924f1f55a3..d0bb082decc 100644 --- a/docs/mfc/dialog-box-classes.md +++ b/docs/mfc/dialog-box-classes.md @@ -4,10 +4,12 @@ title: "Dialog Box Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.dialog"] helpviewer_keywords: ["property sheet classes", "dialog box classes", "OLE common dialog classes", "common dialog classes [MFC]", "tab dialog boxes"] -ms.assetid: db75da23-4eff-4c6c-beae-79cf046fbce9 --- # Dialog Box Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Class `CDialog` and its derived classes encapsulate dialog-box functionality. Since a dialog box is a special kind of window, `CDialog` is derived from `CWnd`. Derive your dialog classes from `CDialog` or use one of the common dialog classes for standard dialog boxes, such as opening or saving a file, printing, selecting a font or color, initiating a search-and-replace operation, or performing various OLE-related operations. [CDialog](reference/cdialog-class.md)
diff --git a/docs/mfc/dialog-box-components-in-the-framework.md b/docs/mfc/dialog-box-components-in-the-framework.md index 84a07119c71..3f47a6a863e 100644 --- a/docs/mfc/dialog-box-components-in-the-framework.md +++ b/docs/mfc/dialog-box-components-in-the-framework.md @@ -3,10 +3,12 @@ description: "Learn more about: Dialog-Box Components in the Framework" title: "Dialog-Box Components in the Framework" ms.date: "11/04/2016" helpviewer_keywords: ["MFC dialog boxes [MFC], creating", "dialog classes [MFC], dialog box components", "MFC dialog boxes [MFC], about MFC dialog boxes", "dialog templates [MFC], MFC framework", "MFC dialog boxes [MFC], dialog resource"] -ms.assetid: 592db160-0a8a-49be-ac72-ead278aca53f --- # Dialog-Box Components in the Framework +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In the MFC framework, a dialog box has two components: - A dialog-template resource that specifies the dialog box's controls and their placement. diff --git a/docs/mfc/dialog-boxes-in-ole.md b/docs/mfc/dialog-boxes-in-ole.md index dbd432b73d1..c9bbb23247c 100644 --- a/docs/mfc/dialog-boxes-in-ole.md +++ b/docs/mfc/dialog-boxes-in-ole.md @@ -3,10 +3,12 @@ description: "Learn more about: Dialog boxes in OLE" title: "Dialog boxes in OLE" ms.date: "11/04/2016" helpviewer_keywords: ["MFC dialog boxes [MFC], OLE dialog boxes", "OLE dialog boxes", "dialog boxes", "OLE dialog boxes [MFC], about OLE dialog boxes", "dialog boxes [MFC], about dialog boxes", "dialog boxes [MFC], OLE", "Insert object"] -ms.assetid: 73c41eb8-738a-4d02-9212-d3395bb09a3a --- # Dialog boxes in OLE +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + While a user runs an OLE-enabled application, there are times when the application needs information from the user to carry out the operation. The MFC OLE classes provide default dialog boxes to gather the required information. This article lists the tasks handled by the OLE dialog boxes and the classes needed to display those dialog boxes. For details on OLE dialog boxes and the structures used to customize their behavior, see [MFC Reference](mfc-desktop-applications.md). ## Common dialog boxes diff --git a/docs/mfc/dialog-boxes.md b/docs/mfc/dialog-boxes.md index 780520efb62..542ef59b938 100644 --- a/docs/mfc/dialog-boxes.md +++ b/docs/mfc/dialog-boxes.md @@ -3,11 +3,13 @@ description: "Learn more about: Dialog Boxes" title: "Dialog Boxes" ms.date: "11/04/2016" helpviewer_keywords: ["modeless dialog boxes [MFC], MFC dialog boxes", "MFC, dialog boxes", "modal dialog boxes [MFC], MFC dialog boxes", "CDialog class [MFC], MFC dialog boxes", "MFC dialog boxes"] -ms.assetid: e4feea1a-8360-4ccb-9b84-507f1ccd9ef3 --- # Dialog Boxes -Applications for Windows frequently communicate with the user through dialog boxes. Class [CDialog](reference/cdialog-class.md) provides an interface for managing dialog boxes, the Visual C++ dialog editor makes it easy to design dialog boxes and create their dialog-template resources, and Code wizards simplify the process of initializing and validating the controls in a dialog box and of gathering the values entered by the user. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +Applications for Windows frequently communicate with the user through dialog boxes. Class [CDialog](reference/cdialog-class.md) provides an interface for managing dialog boxes, the Visual Studio dialog editor makes it easy to design dialog boxes and create their dialog-template resources, and Code wizards simplify the process of initializing and validating the controls in a dialog box and of gathering the values entered by the user. Dialog boxes contain controls, including: diff --git a/docs/mfc/dialog-data-exchange-and-validation.md b/docs/mfc/dialog-data-exchange-and-validation.md index 7ed85e5f7ed..c8742600b4a 100644 --- a/docs/mfc/dialog-data-exchange-and-validation.md +++ b/docs/mfc/dialog-data-exchange-and-validation.md @@ -3,10 +3,12 @@ description: "Learn more about: Dialog Data Exchange and Validation" title: "Dialog Data Exchange and Validation" ms.date: "11/04/2016" helpviewer_keywords: ["data validation [MFC], dialog boxes", "dialog box data [MFC]", "dialog boxes [MFC], validating data", "validating data [MFC], dialog box data entry", "DDX (dialog data exchange) [MFC], data validation", "dialog box data [MFC], retrieving", "Windows common controls [MFC], dialog boxes", "DDV (dialog data validation) [MFC]", "data [MFC], dialog boxes", "common controls [MFC], dialog boxes", "dialog boxes [MFC], retrieving data", "retrieving dialog box data"] -ms.assetid: 7d373554-7330-43ae-abf1-4bb14e437b4a --- # Dialog Data Exchange and Validation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Dialog data exchange (DDX) is an easy way to initialize the controls in your dialog box and to gather data input by the user. Dialog data validation (DDV) is an easy way to validate data entry in a dialog box. To take advantage of DDX and DDV in your dialog boxes, use the [Add Member Variable Wizard](../ide/adding-a-member-variable-visual-cpp.md#add-member-variable-wizard) to create the data members and set their data types and specify validation rules. ## What do you want to know more about diff --git a/docs/mfc/dialog-data-exchange.md b/docs/mfc/dialog-data-exchange.md index ca1f737fc19..0e039bd13c1 100644 --- a/docs/mfc/dialog-data-exchange.md +++ b/docs/mfc/dialog-data-exchange.md @@ -3,10 +3,12 @@ description: "Learn more about: Dialog Data Exchange" title: "Dialog Data Exchange" ms.date: "11/19/2018" helpviewer_keywords: ["initializing dialog boxes", "canceling data exchange", "dialog box data, retrieving", "DDX (dialog data exchange), data exchange mechanism", "dialog boxes [MFC], initializing", "dialog boxes [MFC], retrieving user input using DDX", "dialog box data", "dialog boxes [MFC], data exchange", "CDataExchange class [MFC], using DDX", "DoDataExchange method [MFC]", "user input [MFC], retrieving from MFC dialog boxes", "capturing user input [MFC]", "transferring dialog box data", "DDX (dialog data exchange), canceling", "UpdateData method [MFC]", "retrieving dialog box data [MFC]"] -ms.assetid: 4675f63b-41d2-45ed-b6c3-235ad8ab924b --- # Dialog Data Exchange +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you use the DDX mechanism, you set the initial values of the dialog object's member variables, typically in your `OnInitDialog` handler or the dialog constructor. Immediately before the dialog is displayed, the framework's DDX mechanism transfers the values of the member variables to the controls in the dialog box, where they appear when the dialog box itself appears in response to `DoModal` or `Create`. The default implementation of `OnInitDialog` in `CDialog` calls the `UpdateData` member function of class `CWnd` to initialize the controls in the dialog box. The same mechanism transfers values from the controls to the member variables when the user clicks the OK button (or whenever you call the `UpdateData` member function with the argument **TRUE**). The dialog data validation mechanism validates any data items for which you specified validation rules. diff --git a/docs/mfc/dialog-data-validation.md b/docs/mfc/dialog-data-validation.md index 0be1815d2cc..9814f2715db 100644 --- a/docs/mfc/dialog-data-validation.md +++ b/docs/mfc/dialog-data-validation.md @@ -3,10 +3,12 @@ description: "Learn more about: Dialog Data Validation" title: "Dialog Data Validation" ms.date: "11/04/2016" helpviewer_keywords: ["validating data [MFC], message boxes", "data validation [MFC], dialog boxes", "dialog boxes [MFC], validating data", "validating data [MFC], dialog box data entry", "DDV (dialog data validation) [MFC]", "data validation [MFC], message boxes"] -ms.assetid: f070c309-2044-4ff2-8c92-1ec1ea84af58 --- # Dialog Data Validation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can specify validation in addition to data exchange by calling DDV functions, as shown in the example in [Dialog Data Exchange](dialog-data-exchange.md). The `DDV_MaxChars` call in the example validates that the string entered in the text-box control is not longer than 20 characters. The DDV function typically alerts the user with a message box if the validation fails and puts the focus on the offending control so the user can reenter the data. A DDV function for a given control must be called immediately after the DDX function for the same control. You can also define your own custom DDX and DDV routines. For details on this and other aspects of DDX and DDV, see [MFC Technical Note 26](tn026-ddx-and-ddv-routines.md). diff --git a/docs/mfc/dialog-sample-list.md b/docs/mfc/dialog-sample-list.md index f68785df172..cc8169fc3c6 100644 --- a/docs/mfc/dialog-sample-list.md +++ b/docs/mfc/dialog-sample-list.md @@ -3,10 +3,12 @@ description: "Learn more about: Dialog Sample List" title: "Dialog Sample List" ms.date: "11/04/2016" helpviewer_keywords: ["sample applications [MFC], dialog boxes"] -ms.assetid: 3fc7dd7c-d758-4c43-96bb-0ea638ca1ad7 --- # Dialog Sample List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + See the following sample programs that illustrate dialog boxes and property sheets: *MDI Sample Application with Dialog Boxes* diff --git a/docs/mfc/do-i-have-to-derive-new-classes-from-cobject-q.md b/docs/mfc/do-i-have-to-derive-new-classes-from-cobject-q.md index 4881b3a4054..9e391415b09 100644 --- a/docs/mfc/do-i-have-to-derive-new-classes-from-cobject-q.md +++ b/docs/mfc/do-i-have-to-derive-new-classes-from-cobject-q.md @@ -3,10 +3,12 @@ description: "Learn more about: Do I Have to Derive New Classes from CObject?" title: "Do I Have to Derive New Classes from CObject?" ms.date: "11/04/2016" helpviewer_keywords: ["derived classes [MFC], from CObject", "CObject class [MFC], when to use"] -ms.assetid: 26021031-feaf-424c-80d1-9547c4409d6a --- # Do I Have to Derive New Classes from CObject? +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + No, you don't. Derive a class from [CObject](reference/cobject-class.md) when you need the facilities it provides, such as serialization or dynamic creatability. Many data classes need to be serialized to files, so it's often a good idea to derive them from `CObject`. For an example of a class derived from `CObject`, see the [Scribble sample](../overview/visual-cpp-samples.md). diff --git a/docs/mfc/docking-and-floating-toolbars.md b/docs/mfc/docking-and-floating-toolbars.md index 06db3ca56cd..ed02a6e6554 100644 --- a/docs/mfc/docking-and-floating-toolbars.md +++ b/docs/mfc/docking-and-floating-toolbars.md @@ -4,10 +4,13 @@ title: "Docking and Floating Toolbars" ms.date: "11/04/2016" f1_keywords: ["CBRS_SIZE_DYNAMIC", "CBRS_SIZE_FIXED"] helpviewer_keywords: ["size [MFC], toolbars", "size", "frame windows [MFC], toolbar docking", "CBRS_ALIGN_ANY constant [MFC]", "palettes, floating", "toolbars [MFC], docking", "CBRS_SIZE_DYNAMIC constant [MFC]", "floating toolbars", "toolbars [MFC], size", "toolbars [MFC], floating", "fixed-size toolbars", "CBRS_SIZE_FIXED constant [MFC]", "toolbar controls [MFC], wrapping", "toolbars [MFC], wrapping", "floating palettes"] -ms.assetid: b7f9f9d4-f629-47d2-a3c4-2b33fa6b51e4 +ms.topic: concept-article --- # Docking and Floating Toolbars +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class Library supports dockable toolbars. A dockable toolbar can be attached, or docked, to any side of its parent window, or it can be detached, or floated, in its own mini-frame window. This article explains how to use dockable toolbars in your applications. If you use the Application Wizard to generate the skeleton of your application, you are asked to choose whether you want dockable toolbars. By default, the Application Wizard generates the code that performs the three actions necessary to place a dockable toolbar in your application: diff --git a/docs/mfc/document-and-view-classes-created-by-the-mfc-application-wizard.md b/docs/mfc/document-and-view-classes-created-by-the-mfc-application-wizard.md index 6003a3f8dc8..926435cf6f8 100644 --- a/docs/mfc/document-and-view-classes-created-by-the-mfc-application-wizard.md +++ b/docs/mfc/document-and-view-classes-created-by-the-mfc-application-wizard.md @@ -3,11 +3,13 @@ description: "Learn more about: Document and View Classes Created by the MFC App title: "Document and View Classes Created by the MFC Application Wizard" ms.date: "11/04/2016" helpviewer_keywords: ["document classes [MFC]", "document classes [MFC], created by application wizards", "application wizards [MFC], document/view classes created", "view classes [MFC], created by application wizards"] -ms.assetid: 70c34a60-2701-4981-acea-c08a5787d8e6 --- # Document and View Classes Created by the MFC Application Wizard -The MFC Application Wizard gives you a head start on your program development by creating skeletal document and view classes for you. You can then [map commands and messages to these classes](reference/mapping-messages-to-functions.md) and use the Visual C++ source code editor to write their member functions. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +The MFC Application Wizard gives you a head start on your program development by creating skeletal document and view classes for you. You can then [map commands and messages to these classes](reference/mapping-messages-to-functions.md) and use the Visual Studio source code editor to write their member functions. The document class created by the MFC Application Wizard is derived from class [CDocument](reference/cdocument-class.md). The view class is derived from [CView](reference/cview-class.md). The names that the Application Wizard gives these classes and the files that contain them are based on the project name you supply in the Application Wizard dialog box. In the Application Wizard, you can use the Generated Classes page to alter the default names. diff --git a/docs/mfc/document-classes.md b/docs/mfc/document-classes.md index 7e160a90e8c..85f0ffe26cf 100644 --- a/docs/mfc/document-classes.md +++ b/docs/mfc/document-classes.md @@ -4,10 +4,12 @@ title: "Document Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.document"] helpviewer_keywords: ["document classes [MFC]"] -ms.assetid: 4bf19b02-0a4f-4319-b68e-cddcba2705cb --- # Document Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Document class objects, created by document-template objects, manage the application's data. You will derive a class for your documents from one of these classes. Document class objects interact with view objects. View objects represent the client area of a window, display a document's data, and allow users to interact with it. Documents and views are created by a document-template object. diff --git a/docs/mfc/document-template-classes.md b/docs/mfc/document-template-classes.md index d4eb01a7d6e..ba612259b59 100644 --- a/docs/mfc/document-template-classes.md +++ b/docs/mfc/document-template-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Document-Template Classes" title: "Document-Template Classes" ms.date: "11/04/2016" helpviewer_keywords: ["document templates [MFC], classes"] -ms.assetid: 901749e9-8048-44a0-b5e2-361554650a73 --- # Document-Template Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Document-template objects coordinate the creation of document, view, and frame window objects when a new document or view is created. [CDocTemplate](reference/cdoctemplate-class.md)
diff --git a/docs/mfc/document-template-creation.md b/docs/mfc/document-template-creation.md index e4506f1132f..1aab92815f0 100644 --- a/docs/mfc/document-template-creation.md +++ b/docs/mfc/document-template-creation.md @@ -3,17 +3,19 @@ description: "Learn more about: Document Template Creation" title: "Document Template Creation" ms.date: "11/04/2016" helpviewer_keywords: ["document templates [MFC]", "constructors [MFC], document template", "document templates [MFC], creating", "MFC, document templates", "templates [MFC], document templates"] -ms.assetid: c87f1821-7cbf-442e-9690-f126ae7fb783 --- # Document Template Creation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When creating a new document in response to a **New** or **Open** command from the **File** menu, the document template also creates a new frame window through which to view the document. The document-template constructor specifies what types of documents, windows, and views the template will be able to create. This is determined by the arguments you pass to the document-template constructor. The following code illustrates creation of a [CMultiDocTemplate](reference/cmultidoctemplate-class.md) for a sample application: [!code-cpp[NVC_MFCDocView#7](codesnippet/cpp/document-template-creation_1.cpp)] -The pointer to a new `CMultiDocTemplate` object is used as an argument to [AddDocTemplate](reference/cwinapp-class.md#adddoctemplate). Arguments to the `CMultiDocTemplate` constructor include the resource ID associated with the document type's menus and accelerators, and three uses of the [RUNTIME_CLASS](reference/run-time-object-model-services.md#runtime_class) macro. `RUNTIME_CLASS` returns the [CRuntimeClass](reference/cruntimeclass-structure.md) object for the C++ class named as its argument. The three `CRuntimeClass` objects passed to the document-template constructor supply the information needed to create new objects of the specified classes during the document creation process. The example shows creation of a document template that creates `CScribDoc` objects with `CScribView` objects attached. The views are framed by standard MDI child frame windows. +The pointer to a new `CMultiDocTemplate` object is used as an argument to [AddDocTemplate](reference/cwinapp-class.md#adddoctemplate). Arguments to the `CMultiDocTemplate` constructor include the resource ID associated with the document type's menus and accelerators, and three uses of the [RUNTIME_CLASS](reference/run-time-object-model-services.md#runtime_class) macro. `RUNTIME_CLASS` returns the [CRuntimeClass](reference/cruntimeclass-structure.md) object for the C++ class named as its argument. The three `CRuntimeClass` objects passed to the document-template constructor supply the information needed to create new objects of the specified classes during the document creation process. The example shows creation of a document template that creates `CMyDoc` objects with `CMyView` objects attached. The views are framed by custom MDI child frame windows `CChildFrame`. ## See also diff --git a/docs/mfc/document-templates-and-the-document-view-creation-process.md b/docs/mfc/document-templates-and-the-document-view-creation-process.md index a768e96d1e7..977df497b81 100644 --- a/docs/mfc/document-templates-and-the-document-view-creation-process.md +++ b/docs/mfc/document-templates-and-the-document-view-creation-process.md @@ -3,10 +3,12 @@ description: "Learn more about: Document Templates and the Document/View Creatio title: "Document Templates and the Document-View Creation Process" ms.date: "11/19/2018" helpviewer_keywords: ["icons, for multiple document templates", "document templates [MFC], and views", "document/view architecture [MFC], creating document/view", "single document template", "MFC, document templates", "multiple document template", "CDocTemplate class [MFC]", "templates [MFC], document templates"] -ms.assetid: 311ce4cd-fbdf-4ea1-a51b-5bb043abbcee --- # Document Templates and the Document/View Creation Process +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To manage the complex process of creating documents with their associated views and frame windows, the framework uses two document template classes: [CSingleDocTemplate](reference/csingledoctemplate-class.md) for SDI applications and [CMultiDocTemplate](reference/cmultidoctemplate-class.md) for MDI applications. A `CSingleDocTemplate` can create and store one document of one type at a time. A `CMultiDocTemplate` keeps a list of many open documents of one type. Some applications support multiple document types. For example, an application might support text documents and graphics documents. In such an application, when the user chooses the New command on the File menu, a dialog box shows a list of possible new document types to open. For each supported document type, the application uses a distinct document template object. The following figure illustrates the configuration of an MDI application that supports two document types and shows several open documents. diff --git a/docs/mfc/document-view-architecture.md b/docs/mfc/document-view-architecture.md index 1f09850246f..e782f90ac5b 100644 --- a/docs/mfc/document-view-architecture.md +++ b/docs/mfc/document-view-architecture.md @@ -3,10 +3,12 @@ description: "Learn more about: Document/View Architecture" title: "Document-View Architecture" ms.date: "11/19/2018" helpviewer_keywords: ["CView class [MFC], view architecture", "CDocument class [MFC]", "MFC, views", "views [MFC], MFC document/view model", "document objects [MFC]", "document objects [MFC], MFC document/view model", "MFC, documents", "documents [MFC], MFC document/view model", "document objects [MFC], document/view architecture"] -ms.assetid: 6127768a-553f-462a-b01b-a5ee6068c81e --- # Document/View Architecture +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By default, the MFC Application Wizard creates an application skeleton with a document class and a view class. MFC separates data management into these two classes. The document stores the data and manages printing the data and coordinates updating multiple views of the data. The view displays the data and manages user interaction with it, including selection and editing. In this model, an MFC document object reads and writes data to persistent storage. The document may also provide an interface to the data wherever it resides (such as in a database). A separate view object manages data display, from rendering the data in a window to user selection and editing of data. The view obtains display data from the document and communicates back to the document any data changes. diff --git a/docs/mfc/document-view-creation.md b/docs/mfc/document-view-creation.md index 094a7ff5e85..dbdaa81bd3b 100644 --- a/docs/mfc/document-view-creation.md +++ b/docs/mfc/document-view-creation.md @@ -3,10 +3,12 @@ description: "Learn more about: Document/View Creation" title: "Document-View Creation" ms.date: "11/04/2016" helpviewer_keywords: ["documents [MFC], creating", "views [MFC], and frame windows", "views [MFC], creating", "tables [MFC]", "MFC, views", "document/view architecture [MFC], creating document/view", "object creators", "MFC, documents", "tables [MFC], objects each MFC object creates"] -ms.assetid: bda14f41-ed50-439d-af9e-591174e7dd64 --- # Document/View Creation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The framework supplies implementations of the **New** and **Open** commands (among others) on the **File** menu. Creation of a new document and its associated view and frame window is a cooperative effort among the application object, a document template, the newly created document, and the newly created frame window. The following table summarizes which objects create what. ### Object Creators diff --git a/docs/mfc/document-view-sample-list.md b/docs/mfc/document-view-sample-list.md index c72a073f76c..9bb5f66511c 100644 --- a/docs/mfc/document-view-sample-list.md +++ b/docs/mfc/document-view-sample-list.md @@ -2,10 +2,12 @@ description: "Learn more about: Document/View Sample List" title: "Document-View Sample List" ms.date: "11/04/2016" -ms.assetid: 6f087ce8-2f46-433c-b674-4c110743b289 --- # Document/View Sample List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + See the following sample programs that illustrate using MFC's document/view architecture in interesting ways: *Document/View Variations* diff --git a/docs/mfc/documents-views-and-the-framework.md b/docs/mfc/documents-views-and-the-framework.md index 4c9fca0aceb..cf396b37ddd 100644 --- a/docs/mfc/documents-views-and-the-framework.md +++ b/docs/mfc/documents-views-and-the-framework.md @@ -3,10 +3,12 @@ title: "Documents, views, and the Microsoft Foundation Class (MFC) library frame description: "A description of documents and views in the Microsoft Foundation Class (MFC) library." ms.date: "09/25/2020" helpviewer_keywords: ["document templates [MFC], template objects", "applications [MFC]", "MFC, application framework", "application objects [MFC], relation to other MFC objects", "documents [MFC]", "MFC, documents", "document objects [MFC], in relation to other MFC objects", "view objects [MFC], relation to other MFC objects", "MFC, views", "document/view architecture [MFC], about document/view architecture", "objects [MFC], MFC applications", "MFC object relationships", "thread objects [MFC]"] -ms.assetid: 409ddd9b-66ad-4625-84f7-bf55a41d697b --- # Documents, views, and the framework +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + At the heart of the MFC framework are the concepts of document and view. A document is a data object with which the user interacts in an editing session. It's created by the **New** or **Open** command on the **File** menu and is typically saved in a file. (Standard MFC documents, derived from class `CDocument`, are different from Active documents and OLE compound documents.) A view is a window object through which the user interacts with a document. The key objects in a running application are: diff --git a/docs/mfc/drag-and-drop-ole.md b/docs/mfc/drag-and-drop-ole.md index 3e7d26ae827..f87bbd28647 100644 --- a/docs/mfc/drag-and-drop-ole.md +++ b/docs/mfc/drag-and-drop-ole.md @@ -3,10 +3,12 @@ title: "OLE drag and drop" description: "Overview of Microsoft Foundation Classes (MFC) OLE drag and drop, how to implement a drop source, a drop target, and how to customize drag and drop." ms.date: "02/09/2020" helpviewer_keywords: ["OLE server applications [MFC], drag and drop", "drag and drop [MFC]", "OLE applications [MFC], drag and drop", "File Manager drag and drop support [MFC]", "drag and drop [MFC], about OLE drag and drop", "OLE drag and drop [MFC]", ] -ms.assetid: a4595350-ca06-4400-88a1-f0175c76b77b --- # OLE drag and drop +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The drag-and-drop feature of OLE is primarily a shortcut for copying and pasting data. When you use the Clipboard to copy or paste data, a number of steps are required. You select the data, and choose **Cut** or **Copy** from the **Edit** menu. Then you move to the destination app or window, and place the cursor in the target location. Finally, you choose **Edit** > **Paste** from the menu. The OLE drag-and-drop feature is different from the File Manager drag-and-drop mechanism. The File Manager can only handle filenames, and is designed specifically to pass filenames to applications. Drag and drop in OLE is much more general. It allows you to drag and drop any data that could also be placed on the Clipboard. diff --git a/docs/mfc/dragging-and-dropping-files-in-a-frame-window.md b/docs/mfc/dragging-and-dropping-files-in-a-frame-window.md index 0371f4f3556..d59c75f98b1 100644 --- a/docs/mfc/dragging-and-dropping-files-in-a-frame-window.md +++ b/docs/mfc/dragging-and-dropping-files-in-a-frame-window.md @@ -3,10 +3,13 @@ description: "Learn more about: Dragging and Dropping Files in a Frame Window" title: "Dragging and Dropping Files in a Frame Window" ms.date: "11/04/2016" helpviewer_keywords: ["drag and drop [MFC], files", "drag and drop [MFC], File Manager", "Windows Explorer [MFC]", "File Manager drag and drop support [MFC]", "files [MFC], drag and drop", "frame windows [MFC], dragging and dropping files in", "drag and drop [MFC], Windows Explorer"] -ms.assetid: 85560fe9-121b-4105-bd7b-216b966e19fa +ms.topic: concept-article --- # Dragging and Dropping Files in a Frame Window +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The frame window manages a relationship with File Explorer or File Manager. By adding a few initializing calls in your override of the `CWinApp` member function `InitInstance`, as described in [CWinApp: The Application Class](cwinapp-the-application-class.md), you can have your frame window indirectly open files dragged from File Explorer or File Manager and dropped in the frame window. See [File Manager Drag and Drop](special-cwinapp-services.md). diff --git a/docs/mfc/dragging-images-from-an-image-list.md b/docs/mfc/dragging-images-from-an-image-list.md index d1978d040d1..3d782945ac2 100644 --- a/docs/mfc/dragging-images-from-an-image-list.md +++ b/docs/mfc/dragging-images-from-an-image-list.md @@ -3,10 +3,13 @@ description: "Learn more about: Dragging Images from an Image List" title: "Dragging Images from an Image List" ms.date: "11/04/2016" helpviewer_keywords: ["CImageList class [MFC], dragging images from", "dragging images from image lists [MFC]", "image lists [MFC], dragging images from", "images [MFC], dragging from image lists"] -ms.assetid: af691db8-e4f0-4046-b7b9-9acc68d3713d +ms.topic: concept-article --- # Dragging Images from an Image List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [CImageList](reference/cimagelist-class.md) includes functions for dragging an image on the screen. The dragging functions move an image smoothly, in color, and without any flashing of the cursor. Both masked and unmasked images can be dragged. The [BeginDrag](reference/cimagelist-class.md#begindrag) member function begins a drag operation. The parameters include the index of the image to drag and the location of the hot spot within the image. The hot spot is a single pixel that the dragging functions recognize as the exact screen location of the image. Typically, an application sets the hot spot so that it coincides with the hot spot of the mouse cursor. The [DragMove](reference/cimagelist-class.md#dragmove) member function moves the image to a new location. diff --git a/docs/mfc/drawing-and-printing-classes.md b/docs/mfc/drawing-and-printing-classes.md index 69a545ce583..97c8131d852 100644 --- a/docs/mfc/drawing-and-printing-classes.md +++ b/docs/mfc/drawing-and-printing-classes.md @@ -3,10 +3,13 @@ description: "Learn more about: Drawing and Printing Classes" title: "Drawing and Printing Classes" ms.date: "11/04/2016" helpviewer_keywords: ["output [MFC], graphical classes", "drawing [MFC], classes", "printing classes [MFC]", "graphics [MFC], graphical output classes"] -ms.assetid: 2781c599-a038-462a-98ca-634b07ee22b0 +ms.topic: concept-article --- # Drawing and Printing Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In Windows, all graphical output is drawn on a virtual drawing area called a device context (DC). MFC provides classes to encapsulate the various types of DCs, as well as encapsulations for Windows drawing tools such as bitmaps, brushes, palettes, and pens. ## See also diff --git a/docs/mfc/drawing-images-from-an-image-list.md b/docs/mfc/drawing-images-from-an-image-list.md index 12206237232..a2e7dc7581a 100644 --- a/docs/mfc/drawing-images-from-an-image-list.md +++ b/docs/mfc/drawing-images-from-an-image-list.md @@ -3,10 +3,13 @@ description: "Learn more about: Drawing Images from an Image List" title: "Drawing Images from an Image List" ms.date: "11/04/2016" helpviewer_keywords: ["CImageList class [MFC], drawing images from", "drawing [MFC], images from image lists", "image lists [MFC], drawing images from", "images [MFC], drawing"] -ms.assetid: 2f6063fb-1c28-45f8-a333-008c064db11c +ms.topic: concept-article --- # Drawing Images from an Image List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To draw an image, use the [CImageList::Draw](reference/cimagelist-class.md#draw) member function. You'll specify a pointer to a device context object, the index of the image to draw, the location in the device context at which to draw the image, and a set of flags to indicate the drawing style. When you specify the **ILD_TRANSPARENT** style, `Draw` uses a two-step process to draw a masked image. First, it performs a logical-AND operation on the bits of the image and the bits of the mask. Then it performs a logical-XOR operation on the results of the first operation and the background bits of the destination device context. This process creates transparent areas in the resulting image; that is, each white bit in the mask causes the corresponding bit in the resulting image to be transparent. diff --git a/docs/mfc/drawing-in-a-view.md b/docs/mfc/drawing-in-a-view.md index 88d9d6fd1b5..5993704da68 100644 --- a/docs/mfc/drawing-in-a-view.md +++ b/docs/mfc/drawing-in-a-view.md @@ -3,10 +3,13 @@ description: "Learn more about: Drawing in a View" title: "Drawing in a View" ms.date: "11/04/2016" helpviewer_keywords: ["drawing [MFC], in views", "views [MFC], printing", "views [MFC], updating", "printing [MFC], views", "views [MFC], rendering", "printing views [MFC]", "paint messages in view class [MFC]", "device contexts, screen drawings"] -ms.assetid: e3761db6-0f19-4482-a4cd-ac38ef7c4d3a +ms.topic: how-to --- # Drawing in a View +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Nearly all drawing in your application occurs in the view's `OnDraw` member function, which you must override in your view class. (The exception is mouse drawing, discussed in [Interpreting User Input Through a View](interpreting-user-input-through-a-view.md).) Your `OnDraw` override: 1. Gets data by calling the document member functions you provide. diff --git a/docs/mfc/drawing-tool-classes.md b/docs/mfc/drawing-tool-classes.md index 3e7fda79fab..05411c8d738 100644 --- a/docs/mfc/drawing-tool-classes.md +++ b/docs/mfc/drawing-tool-classes.md @@ -4,10 +4,13 @@ title: "Drawing Tool Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.drawing"] helpviewer_keywords: ["drawing [MFC], tool classes", "screen output classes [MFC]", "output classes [MFC]"] -ms.assetid: e907bd89-38b5-47c9-b76a-95e0bf3bb41d +ms.topic: concept-article --- # Drawing Tool Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes encapsulate drawing tools that are used to draw on a device context. [CGdiObject](reference/cgdiobject-class.md)
diff --git a/docs/mfc/dynamic-layout.md b/docs/mfc/dynamic-layout.md index f92eca0ea56..460b4f46d7f 100644 --- a/docs/mfc/dynamic-layout.md +++ b/docs/mfc/dynamic-layout.md @@ -2,10 +2,12 @@ description: "Learn more about: Dynamic Layout" title: "Dynamic Layout" ms.date: "09/09/2019" -ms.assetid: 8598cfb2-c8d4-4f5a-bf2b-59dc4653e042 --- # Dynamic Layout +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + With MFC in Visual Studio 2015, you can create dialogs that the user can resize, and you can control the way the layout adjusts to the change in size. For example, you can attach buttons at the bottom of a dialog to the bottom edge so they always stay at the bottom. You can also set up certain controls such as listboxes, editboxes, and text fields to expand as the user expands the dialog. ## Specifying dynamic layout settings for an MFC dialog box diff --git a/docs/mfc/dynamic-object-creation.md b/docs/mfc/dynamic-object-creation.md index 508a2012a9e..e41eb57dc31 100644 --- a/docs/mfc/dynamic-object-creation.md +++ b/docs/mfc/dynamic-object-creation.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to create an object dynamically at run time. The procedure uses run-time class information, as discussed in the article [Accessing Run-Time Class Information](accessing-run-time-class-information.md). #### Dynamically create an object given its run-time class @@ -17,5 +19,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/enabling-tool-tips.md b/docs/mfc/enabling-tool-tips.md index c101a6b1fb1..f29d9439621 100644 --- a/docs/mfc/enabling-tool-tips.md +++ b/docs/mfc/enabling-tool-tips.md @@ -3,10 +3,13 @@ description: "Learn more about: Enabling Tool Tips" title: "Enabling Tool Tips" ms.date: "11/04/2016" helpviewer_keywords: ["initializing tool tips [MFC]", "enabling tool tips [MFC]", "tool tips [MFC], initializing", "tool tips [MFC], enabling"] -ms.assetid: 06b7c889-7722-4ce6-8b88-9efa50fe6369 +ms.topic: how-to --- # Enabling Tool Tips +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can enable tool tip support for the child controls of a window (such as the controls on a form view or dialog box). ### To enable tool tips for the child controls of a window diff --git a/docs/mfc/example-displaying-a-dialog-box-via-a-menu-command.md b/docs/mfc/example-displaying-a-dialog-box-via-a-menu-command.md index b357a9e58f3..03c56551940 100644 --- a/docs/mfc/example-displaying-a-dialog-box-via-a-menu-command.md +++ b/docs/mfc/example-displaying-a-dialog-box-via-a-menu-command.md @@ -3,10 +3,12 @@ description: "Learn more about: Example: Displaying a Dialog Box via a Menu Comm title: "Example: Displaying a Dialog Box via a Menu Command" ms.date: "09/07/2019" helpviewer_keywords: ["MFC dialog boxes [MFC], examples", "MFC dialog boxes [MFC], displaying", "modeless dialog boxes [MFC], displaying", "dialog boxes [MFC], MFC", "modal dialog boxes [MFC], displaying", "examples [MFC], dialog boxes", "menu items [MFC], examples"] -ms.assetid: e8692549-acd7-478f-9c5e-ba310ce8cccd --- # Example: Displaying a Dialog Box via a Menu Command +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic contains procedures to: - Display a modal dialog box through a menu command. diff --git a/docs/mfc/example-of-active-document-containment-office-binder.md b/docs/mfc/example-of-active-document-containment-office-binder.md index 81ef5fd2faf..e09e13f91c3 100644 --- a/docs/mfc/example-of-active-document-containment-office-binder.md +++ b/docs/mfc/example-of-active-document-containment-office-binder.md @@ -3,10 +3,12 @@ description: "Learn more about: Example of Active Document Containment: Office B title: "Example of Active Document Containment: Office Binder" ms.date: "11/04/2016" helpviewer_keywords: ["active documents [MFC], containers", "examples [MFC], active document containment", "containers [MFC], active document", "active document containers [MFC], examples", "Office Binder [MFC]", "MFC COM, active document containment"] -ms.assetid: 70dd8568-e8bc-44ac-bf5e-678767efe8e3 --- # Example of Active Document Containment: Office Binder +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Office Binder is an example of an active document container. An Office Binder includes two primary panes, as containers typically do. The left pane contains icons that correspond to active documents in the Binder. Each document is called a *section* within the Binder. For example, a Binder can contain Word documents, PowerPoint files, Excel spreadsheets, and so on. Clicking an icon in the left pane activates the corresponding active document. The right pane of the Binder then displays the contents of the currently selected active document. diff --git a/docs/mfc/exception-classes.md b/docs/mfc/exception-classes.md index beaf14841a8..2b4a56ffe2a 100644 --- a/docs/mfc/exception-classes.md +++ b/docs/mfc/exception-classes.md @@ -4,10 +4,12 @@ title: "Exception Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.exception"] helpviewer_keywords: ["exception classes [MFC]", "exception handling [MFC], exception classes", "MFC, exceptions"] -ms.assetid: 1a2caf12-b3e9-4189-86d2-bf7a595bf025 --- # Exception Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The class library provides an exception-handling mechanism based on class `CException`. The application framework uses exceptions in its code; you can also use them in yours. For more information, see the article [Exceptions](exception-handling-in-mfc.md). You can derive your own exception types from `CException`. MFC provides an exception class from which you can derive your own exception as well as exception classes for all of the exceptions it supports. diff --git a/docs/mfc/exception-handling-in-mfc.md b/docs/mfc/exception-handling-in-mfc.md index 3d16c77f89e..e91a99ec97f 100644 --- a/docs/mfc/exception-handling-in-mfc.md +++ b/docs/mfc/exception-handling-in-mfc.md @@ -1,12 +1,14 @@ --- -description: "Learn more about: Exception Handling in MFC" title: "Exception Handling in MFC" -ms.date: "11/19/2019" +description: "Learn more about: Exception Handling in MFC" +ms.date: 11/19/2019 helpviewer_keywords: ["DAO [MFC], exceptions", "assertions [MFC], When to use exceptions", "exception handling [MFC], MFC", "resource allocation exception", "resources [MFC], allocating", "keywords [MFC], exception handling", "errors [MFC], detected by assertions", "ODBC exceptions [MFC]", "serialization [MFC], exceptions", "Automation [MFC], exceptions", "exception macros [MFC]", "predefined exceptions [MFC]", "C++ exception handling [MFC], enabling", "C++ exception handling [MFC], MFC applications", "requests for unsupported services [MFC]", "database exceptions [MFC]", "archive exceptions [MFC]", "MFC, exceptions", "C++ exception handling [MFC], types of", "macros [MFC], exception handling", "abnormal program execution [MFC]", "OLE exceptions [MFC], MFC exception handling", "error handling [MFC], exceptions and", "class libraries [MFC], exception support", "exceptions [MFC], MFC macros vs. C++ keywords", "memory [MFC], out-of-memory exceptions", "Windows [MFC], resource allocation exceptions", "macros [MFC], MFC exception macros", "function calls [MFC], results", "out-of-memory exceptions [MFC]"] -ms.assetid: 0926627d-2ba7-44a6-babe-d851a4a2517c --- # Exception Handling in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the exception-handling mechanisms available in MFC. Two mechanisms are available: - C++ exceptions, available in MFC version 3.0 and later @@ -40,7 +42,7 @@ Three categories of outcomes can occur when a function is called during program - Erroneous execution - The caller makes some mistake in passing arguments to the function or calls the function in an inappropriate context. This situation causes an error, and it should be detected by an assertion during program development. (For more information on assertions, see [C/C++ Assertions](/visualstudio/debugger/c-cpp-assertions).) + The caller makes some mistake in passing arguments to the function or calls the function in an inappropriate context. This situation causes an error, and it should be detected by an assertion during program development. For more information on assertions, see [C/C++ Assertions](/visualstudio/debugger/c-cpp-assertions). - Abnormal execution diff --git a/docs/mfc/exceptions-catching-and-deleting-exceptions.md b/docs/mfc/exceptions-catching-and-deleting-exceptions.md index cd5ef814784..afd5555844f 100644 --- a/docs/mfc/exceptions-catching-and-deleting-exceptions.md +++ b/docs/mfc/exceptions-catching-and-deleting-exceptions.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Catching and Deleting Exceptions" title: "Exceptions: Catching and Deleting Exceptions" ms.date: "11/04/2016" helpviewer_keywords: ["exceptions [MFC], deleting", "AND_CATCH macro [MFC]", "try-catch exception handling [MFC], catching and deleting exceptions", "exception handling [MFC], catching and deleting exceptions", "catch blocks [MFC], catching and deleting exceptions", "execution [MFC], returns from within catch block"] -ms.assetid: 7c233ff0-89de-4de0-a68a-9e9cdb164311 --- # Exceptions: Catching and Deleting Exceptions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following instructions and examples show you how to catch and delete exceptions. For more information on the **`try`**, **`catch`**, and **`throw`** keywords, see [Modern C++ best practices for exceptions and error handling](../cpp/errors-and-exception-handling-modern-cpp.md). Your exception handlers must delete exception objects they handle, because failure to delete the exception causes a memory leak whenever that code catches an exception. diff --git a/docs/mfc/exceptions-changes-to-exception-macros-in-version-3-0.md b/docs/mfc/exceptions-changes-to-exception-macros-in-version-3-0.md index 0dde24bae2e..9304a90cde0 100644 --- a/docs/mfc/exceptions-changes-to-exception-macros-in-version-3-0.md +++ b/docs/mfc/exceptions-changes-to-exception-macros-in-version-3-0.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Changes to Exception Macros in Versi title: "Exceptions: Changes to Exception Macros in Version 3.0" ms.date: "11/04/2016" helpviewer_keywords: ["C++ exception handling [MFC], upgrade considerations", "CATCH macro [MFC]", "exceptions [MFC], what's changed", "THROW_LAST macro [MFC]"] -ms.assetid: 3aa20d8c-229e-449c-995c-ab879eac84bc --- # Exceptions: Changes to Exception Macros in Version 3.0 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This is an advanced topic. In MFC version 3.0 and later, the exception-handling macros have been changed to use C++ exceptions. This article tells how those changes can affect the behavior of existing code that uses the macros. diff --git a/docs/mfc/exceptions-converting-from-mfc-exception-macros.md b/docs/mfc/exceptions-converting-from-mfc-exception-macros.md index 70337d79971..e258734d362 100644 --- a/docs/mfc/exceptions-converting-from-mfc-exception-macros.md +++ b/docs/mfc/exceptions-converting-from-mfc-exception-macros.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Converting from MFC Exception Macros title: "Exceptions: Converting from MFC Exception Macros" ms.date: "08/27/2018" helpviewer_keywords: ["converting exceptions [MFC]", "exception objects [MFC]", "conversions [MFC], code written with MFC macros", "keywords [MFC], macros", "macrosv, C++ keywords", "exception objects [MFC], deleting", "CException class [MFC], deleting CException class objects", "exceptions [MFC], converting", "exceptions [MFC], deleting exception objects", "catch blocks [MFC], delimiting", "exception handling [MFC], converting exceptions"] -ms.assetid: bd3ac3b3-f3ce-4fdd-a168-a2cff13ed796 --- # Exceptions: Converting from MFC Exception Macros +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This is an advanced topic. This article explains how to convert existing code written with Microsoft Foundation Class macros — **TRY**, **CATCH**, **THROW**, and so on — to use the C++ exception-handling keywords **`try`**, **`catch`**, and **`throw`**. Topics include: diff --git a/docs/mfc/exceptions-database-exceptions.md b/docs/mfc/exceptions-database-exceptions.md index 097ddc2d7ff..ceb25baab4d 100644 --- a/docs/mfc/exceptions-database-exceptions.md +++ b/docs/mfc/exceptions-database-exceptions.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Database Exceptions" title: "Exceptions: Database Exceptions" ms.date: "09/17/2019" helpviewer_keywords: ["DAO [MFC], exceptions", "exceptions [MFC], database", "exception handling [MFC], databases", "ODBC exceptions [MFC]", "ODBC [MFC], exceptions", "database exceptions [MFC]", "databases [MFC], exception handling", "error codes [MFC], database exception handling"] -ms.assetid: 28daf260-f824-4be6-aecc-1f859e6dec26 --- # Exceptions: Database Exceptions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to handle database exceptions. Most of the material in this article applies whether you are working with the MFC classes for Open Database Connectivity (ODBC) or the MFC classes for Data Access Objects (DAO). Material specific to one or the other model is explicitly marked. Topics include: - [Approaches to exception handling](#_core_approaches_to_exception_handling) diff --git a/docs/mfc/exceptions-examining-exception-contents.md b/docs/mfc/exceptions-examining-exception-contents.md index f2bedc83ebb..ea65efd6985 100644 --- a/docs/mfc/exceptions-examining-exception-contents.md +++ b/docs/mfc/exceptions-examining-exception-contents.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Examining Exception Contents" title: "Exceptions: Examining Exception Contents" ms.date: "11/04/2016" helpviewer_keywords: ["exception handling [MFC], MFC", "try-catch exception handling [MFC], MFC function exceptions", "catch blocks, MFC function exceptions", "CException class [MFC], class exceptions", "try-catch exception handling [MFC], exception contents", "throwing exceptions [MFC], exception contents"] -ms.assetid: dfda4782-b969-4f60-b867-cc204ea7f33a --- # Exceptions: Examining Exception Contents +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Although a **`catch`** block's argument can be of almost any data type, the MFC functions throw exceptions of types derived from the class `CException`. To catch an exception thrown by an MFC function, then, you write a **`catch`** block whose argument is a pointer to a `CException` object (or an object derived from `CException`, such as `CMemoryException`). Depending on the exact type of the exception, you can examine the data members of the exception object to gather information about the specific cause of the exception. For example, the `CFileException` type has the `m_cause` data member, which contains an enumerated type that specifies the cause of the file exception. Some examples of the possible return values are `CFileException::fileNotFound` and `CFileException::readOnly`. diff --git a/docs/mfc/exceptions-exceptions-in-constructors.md b/docs/mfc/exceptions-exceptions-in-constructors.md index 239bf4c5625..e2d860490cf 100644 --- a/docs/mfc/exceptions-exceptions-in-constructors.md +++ b/docs/mfc/exceptions-exceptions-in-constructors.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Exceptions in Constructors" title: "Exceptions: Exceptions in Constructors" ms.date: "11/04/2016" helpviewer_keywords: ["constructors [MFC], exceptions", "throwing exceptions [MFC], in constructors", "exceptions [MFC], in constructors"] -ms.assetid: a78eae5a-5821-4b27-9478-1436320ed1e1 --- # Exceptions: Exceptions in Constructors +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When throwing an exception in a constructor, clean up whatever objects and memory allocations you have made prior to throwing the exception, as explained in [Exceptions: Throwing Exceptions from Your Own Functions](exceptions-throwing-exceptions-from-your-own-functions.md). When throwing an exception in a constructor, the memory for the object itself has already been allocated by the time the constructor is called. So, the compiler will automatically deallocate the memory occupied by the object after the exception is thrown. diff --git a/docs/mfc/exceptions-freeing-objects-in-exceptions.md b/docs/mfc/exceptions-freeing-objects-in-exceptions.md index de0c17158d3..f3057b12262 100644 --- a/docs/mfc/exceptions-freeing-objects-in-exceptions.md +++ b/docs/mfc/exceptions-freeing-objects-in-exceptions.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Freeing Objects in Exceptions" title: "Exceptions: Freeing Objects in Exceptions" ms.date: "11/04/2016" helpviewer_keywords: ["throwing exceptions [MFC], freeing objects in exceptions", "local exception handling", "memory leaks, caused by exception", "try-catch exception handling [MFC], destroying objects", "destroying objects [MFC]", "freeing objects [MFC]", "throwing exceptions [MFC], after destroying", "exception handling [MFC], destroying objects"] -ms.assetid: 3b14b4ee-e789-4ed2-b8e3-984950441d97 --- # Exceptions: Freeing Objects in Exceptions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the need and the method of freeing objects when an exception occurs. Topics include: - [Handling the exception locally](#_core_handling_the_exception_locally) diff --git a/docs/mfc/exceptions-ole-exceptions.md b/docs/mfc/exceptions-ole-exceptions.md index edf6080508e..0f58a8466ee 100644 --- a/docs/mfc/exceptions-ole-exceptions.md +++ b/docs/mfc/exceptions-ole-exceptions.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: OLE Exceptions" title: "Exceptions: OLE Exceptions" ms.date: "11/04/2016" helpviewer_keywords: ["OLE, exceptions", "OLE exceptions [MFC]", "exceptions [MFC], OLE", "exception handling [MFC], OLE", "OLE exceptions [MFC], classes for handling"] -ms.assetid: 2f8e0161-b94f-48bb-a5a2-6f644b192527 --- # Exceptions: OLE Exceptions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The techniques and facilities for handling exceptions in OLE are the same as those for handling other exceptions. For further information on exception handling, see the article [Modern C++ best practices for exceptions and error handling](../cpp/errors-and-exception-handling-modern-cpp.md). All exception objects are derived from the abstract base class `CException`. MFC provides two classes for handling OLE exceptions: diff --git a/docs/mfc/exceptions-throwing-exceptions-from-your-own-functions.md b/docs/mfc/exceptions-throwing-exceptions-from-your-own-functions.md index acc4fcb8df0..2eeea63f2be 100644 --- a/docs/mfc/exceptions-throwing-exceptions-from-your-own-functions.md +++ b/docs/mfc/exceptions-throwing-exceptions-from-your-own-functions.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Throwing Exceptions from Your Own Fu title: "Exceptions: Throwing Exceptions from Your Own Functions" ms.date: "11/04/2016" helpviewer_keywords: ["throwing exceptions [MFC], from functions", "functions [MFC], throwing exceptions", "exceptions [MFC], throwing"] -ms.assetid: 492976e8-8804-4234-8e8f-30dffd0501be --- # Exceptions: Throwing Exceptions from Your Own Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + It is possible to use the MFC exception-handling paradigm solely to catch exceptions thrown by functions in MFC or other libraries. In addition to catching exceptions thrown by library code, you can throw exceptions from your own code if you are writing functions that can encounter exceptional conditions. When an exception is thrown, execution of the current function is stopped and jumps directly to the **`catch`** block of the innermost exception frame. The exception mechanism bypasses the normal exit path from a function. Therefore, you must be sure to delete those memory blocks that would be deleted in a normal exit. diff --git a/docs/mfc/exceptions-using-mfc-macros-and-cpp-exceptions.md b/docs/mfc/exceptions-using-mfc-macros-and-cpp-exceptions.md index e8816115764..5a1929373cb 100644 --- a/docs/mfc/exceptions-using-mfc-macros-and-cpp-exceptions.md +++ b/docs/mfc/exceptions-using-mfc-macros-and-cpp-exceptions.md @@ -3,10 +3,12 @@ description: "Learn more about: Exceptions: Using MFC Macros and C++ Exceptions" title: "Exceptions: Using MFC Macros and C++ Exceptions" ms.date: "11/04/2016" helpviewer_keywords: ["exception objects [MFC]", "memory leaks [MFC], exception object not deleted", "exception handling [MFC], MFC", "try-catch exception handling [MFC], mixing MFC macros and C++ keywords", "exception objects [MFC], deleting", "exceptions [MFC], MFC macros vs. C++ keywords", "catch blocks [MFC], mixed", "exception handling [MFC], mixed-language", "nested try blocks [MFC]", "catch blocks [MFC], explicitly deleting code in", "try-catch exception handling [MFC], nested try blocks", "heap corruption [MFC]", "nested catch blocks [MFC]"] -ms.assetid: d664a83d-879b-44d4-bdf0-029f0aca69e9 --- # Exceptions: Using MFC Macros and C++ Exceptions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses considerations for writing code that uses both the MFC exception-handling macros and the C++ exception-handling keywords. This article covers the following topics: diff --git a/docs/mfc/exchanging-data.md b/docs/mfc/exchanging-data.md index ad56d4f5976..82d3ffc820b 100644 --- a/docs/mfc/exchanging-data.md +++ b/docs/mfc/exchanging-data.md @@ -3,10 +3,13 @@ description: "Learn more about: Exchanging Data" title: "Exchanging Data" ms.date: "11/04/2016" helpviewer_keywords: ["property sheets [MFC], data exchange", "exchanging data with property sheets [MFC]", "DDX (dialog data exchange) [MFC], property sheets"] -ms.assetid: 689f02d0-51a9-455b-8ffb-5b44f0aefa28 +ms.topic: concept-article --- # Exchanging Data +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As with most dialog boxes, the exchange of data between the property sheet and the application is one of the most important functions of the property sheet. This article describes how to accomplish this task. Exchanging data with a property sheet is actually a matter of exchanging data with the individual property pages of the property sheet. The procedure for exchanging data with a property page is the same as for exchanging data with a dialog box, since a [CPropertyPage](reference/cpropertypage-class.md) object is just a specialized [CDialog](reference/cdialog-class.md) object. The procedure takes advantage of the framework's dialog data exchange (DDX) facility, which exchanges data between controls in a dialog box and member variables of the dialog box object. diff --git a/docs/mfc/exitinstance-member-function.md b/docs/mfc/exitinstance-member-function.md index 7cf3e1afdee..fe4fa52c6b6 100644 --- a/docs/mfc/exitinstance-member-function.md +++ b/docs/mfc/exitinstance-member-function.md @@ -4,10 +4,12 @@ title: "ExitInstance Member Function" ms.date: "11/04/2016" f1_keywords: [] helpviewer_keywords: ["programs [MFC], terminating", "CWinApp class [MFC], ExitInstance", "ExitInstance method [MFC]"] -ms.assetid: 5bb597bd-8dab-4d49-8bcf-9c45aa8be4a2 --- # ExitInstance Member Function +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [ExitInstance](reference/cwinapp-class.md#exitinstance) member function of class [CWinApp](reference/cwinapp-class.md) is called each time a copy of your application terminates, usually as a result of the user quitting the application. Override `ExitInstance` if you need special cleanup processing, such as freeing graphics device interface (GDI) resources or deallocating memory used during program execution. Cleanup of standard items such as documents and views, however, is provided by the framework, with other overridable functions for doing special cleanup specific to those objects. diff --git a/docs/mfc/exported-dll-function-entry-points.md b/docs/mfc/exported-dll-function-entry-points.md index 0a9cbd7ae47..92c099b46ed 100644 --- a/docs/mfc/exported-dll-function-entry-points.md +++ b/docs/mfc/exported-dll-function-entry-points.md @@ -3,10 +3,12 @@ description: "Learn more about: Exported DLL Function Entry Points" title: "Exported DLL Function Entry Points" ms.date: "11/04/2016" helpviewer_keywords: ["exporting DLLs [MFC], functions", "MFC, managing state data", "state management [MFC], exported DLLs"] -ms.assetid: 3268666e-d24b-44f2-80e8-7c80f73b93ca --- # Exported DLL Function Entry Points +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For exported functions of a DLL, use the [AFX_MANAGE_STATE](reference/extension-dll-macros.md#afx_manage_state) macro to maintain the proper global state when switching from the DLL module to the calling application's DLL. When called, this macro sets `pModuleState`, a pointer to an `AFX_MODULE_STATE` structure containing global data for the module, as the effective module state for the remainder of the containing scope of the function. Upon leaving the scope containing the macro, the previous effective module state is automatically restored. diff --git a/docs/mfc/file-and-database-classes.md b/docs/mfc/file-and-database-classes.md index 0ac75d36c90..59b0f159140 100644 --- a/docs/mfc/file-and-database-classes.md +++ b/docs/mfc/file-and-database-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: File and Database Classes" title: "File and Database Classes" ms.date: "11/04/2016" helpviewer_keywords: ["database classes [MFC], MFC", "database classes [MFC]", "file classes [MFC]"] -ms.assetid: 580b169c-e26e-4395-b128-5408d08c98fe --- # File and Database Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes allow you to store information to a database or a disk file. There are three sets of database classes — OLE DB, ODBC, and DAO — that provide similar functionality. The OLE DB group is implemented using OLE DB and works with the OLE DB consumer templates, the DAO group is implemented using the Data Access Object, and the ODBC group is implemented using Open Database Connectivity. There are also a set of classes for manipulating standard files, Active streams, and HTML streams. The following categories of classes support data persistence. diff --git a/docs/mfc/file-i-o-classes.md b/docs/mfc/file-i-o-classes.md index f9b697305f7..6a988af054b 100644 --- a/docs/mfc/file-i-o-classes.md +++ b/docs/mfc/file-i-o-classes.md @@ -4,10 +4,12 @@ title: "File I-O Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.file"] helpviewer_keywords: ["disk file classes [MFC]", "stdio classes [MFC]", "OLE streams [MFC]", "I/O [MFC], MFC classes", "translated stream classes [MFC]", "file I/O classes [MFC]", "I/O [MFC], classes", "sockets classes [MFC]", "stream classes [MFC]", "memory file classes [MFC]"] -ms.assetid: 92821c3f-d9e1-47f6-98c9-3b632d86e811 --- # File I/O Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes provide an interface to traditional disk files, in-memory files, Active streams, and Windows sockets. All of the classes derived from `CFile` can be used with a `CArchive` object to perform serialization. Use the following classes, particularly `CArchive` and `CFile`, if you write your own input/output processing. Normally you do not need to derive from these classes. If you use the application framework, the default implementations of the **Open** and **Save** commands on the **File** menu will handle file I/O (using class `CArchive`), as long as you override your document's `Serialize` function to supply details about how a document serializes its contents. For more information about the file classes and serialization, see the article [Files in MFC](files-in-mfc.md) and the article [Serialization](serialization-in-mfc.md). diff --git a/docs/mfc/file-menu-in-an-mfc-database-application.md b/docs/mfc/file-menu-in-an-mfc-database-application.md index adfb60edf14..c246ff31b94 100644 --- a/docs/mfc/file-menu-in-an-mfc-database-application.md +++ b/docs/mfc/file-menu-in-an-mfc-database-application.md @@ -3,10 +3,12 @@ description: "Learn more about: File Menu in an MFC Database Application" title: "File Menu in an MFC Database Application" ms.date: "11/04/2016" helpviewer_keywords: ["File menu", "database applications [MFC], File menu commands"] -ms.assetid: 92dafb75-c1b3-4860-80a0-87a83bfc36f2 --- # File Menu in an MFC Database Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you create an MFC database application and don't use serialization, how should you interpret the Open, Close, Save, and Save As commands on the File menu While there are no style guidelines for this question, here are a few suggestions: - Eliminate the File menu's Open command entirely. diff --git a/docs/mfc/files-in-mfc.md b/docs/mfc/files-in-mfc.md index e942e997405..8c6b346b7e6 100644 --- a/docs/mfc/files-in-mfc.md +++ b/docs/mfc/files-in-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Files in MFC" title: "Files in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["serialization [MFC], MFC files", "I/O [MFC], MFC classes", "files [MFC], MFC", "files [MFC], serialization", "binary access, binary file operations in MFC", "file I/O classes [MFC]", "I/O [MFC]", "persistence [MFC]", "MFC, file operations", "files [MFC], manipulating", "binary access [MFC]"] -ms.assetid: ae25e2c5-2859-4679-ab97-438824e93ce1 --- # Files in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In the Microsoft Foundation Class Library (MFC), class [CFile](reference/cfile-class.md) handles normal file I/O operations. This family of articles explains how to open and close files as well as read and write data to those files. It also discusses file status operations. For a description of how to use the object-based serialization features of MFC as an alternative way of reading and writing data in files, see the article [Serialization](serialization-in-mfc.md). > [!NOTE] diff --git a/docs/mfc/form-views-mfc.md b/docs/mfc/form-views-mfc.md index 05801af5441..d776257f447 100644 --- a/docs/mfc/form-views-mfc.md +++ b/docs/mfc/form-views-mfc.md @@ -3,18 +3,20 @@ description: "Learn more about: Form Views (MFC)" title: "Form Views (MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["user interfaces [MFC], forms", "forms [MFC]", "applications [MFC], forms-based", "forms-based applications [MFC]", "forms [MFC], adding to applications"] -ms.assetid: efbe73c1-4ca4-4613-aac2-30d916e92c0e --- # Form Views (MFC) -You can add forms to any Visual C++ application that supports the MFC libraries, including a [forms-based application](reference/creating-a-forms-based-mfc-application.md) (one whose view class is derived from `CFormView`). If you did not initially create your application to support forms, Visual C++ will add this support for you when you insert a new form. In an SDI or MDI application, which implements the default [document/view architecture](document-view-architecture.md), when the user chooses the **New** command (by default, on the **File** menu), Visual C++ prompts the user to choose from the available forms. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +You can add forms to any Visual C++ application that supports the MFC libraries, including a [forms-based application](reference/creating-a-forms-based-mfc-application.md) (one whose view class is derived from `CFormView`). If you did not initially create your application to support forms, Visual Studio will add this support for you when you insert a new form. In an SDI or MDI application, which implements the default [document/view architecture](document-view-architecture.md), when the user chooses the **New** command (by default, on the **File** menu), Visual Studio prompts the user to choose from the available forms. With an SDI application, when the user chooses the **New** command, the current instance of the form continues to run but a new instance of the application with the selected form is created if one is not found. In an MDI application, the current instance of the form continues to run when the user chooses the **New** command. > [!NOTE] -> You can insert a form into a dialog-based application (one whose dialog class is based on `CDialog` and one in which no view class is implemented). However, without the document/view architecture, Visual C++ does not automatically implement the **File** > **New** functionality. You must create a way for the user to view additional forms, such as by implementing a tabbed dialog box with various property pages. +> You can insert a form into a dialog-based application (one whose dialog class is based on `CDialog` and one in which no view class is implemented). However, without the document/view architecture, Visual Studio does not automatically implement the **File** > **New** functionality. You must create a way for the user to view additional forms, such as by implementing a tabbed dialog box with various property pages. -When you insert a new form into your application, Visual C++ does the following: +When you insert a new form into your application, Visual Studio does the following: - Creates a class based on one of the form-style classes that you choose (`CFormView`, `CRecordView`, `CDaoRecordView`, or `CDialog`). @@ -42,7 +44,7 @@ For applications based on the document/view architecture, the **New Form** comma - Adds a call to `AddDocumentTemplate` in your application's `InitInstance` code. - Visual C++ adds this code for each new form you create, which adds the form to the list of available forms when the user chooses the **New** command. This code includes the form's associated resource ID and the names of the associated document, view, and frame classes that together make up the new form object. + Visual Studio adds this code for each new form you create, which adds the form to the list of available forms when the user chooses the **New** command. This code includes the form's associated resource ID and the names of the associated document, view, and frame classes that together make up the new form object. Document templates serve as the connection between documents, frame windows, and views. For a single document, you can create many templates. diff --git a/docs/mfc/frame-window-classes-architecture.md b/docs/mfc/frame-window-classes-architecture.md index 9ec58fb318a..0ce3de51c25 100644 --- a/docs/mfc/frame-window-classes-architecture.md +++ b/docs/mfc/frame-window-classes-architecture.md @@ -3,10 +3,12 @@ description: "Learn more about: Frame Window Classes (Architecture)" title: "Frame Window Classes (Architecture)" ms.date: "11/04/2016" helpviewer_keywords: ["frame window classes [MFC], document/view architecture"] -ms.assetid: 5da01fb4-f531-46cc-914f-e422e4f07f5d --- # Frame Window Classes (Architecture) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In document/view architecture, frame windows are windows that contain a view window. They also support having control bars attached to them. In multiple document interface (MDI) applications, the main window is derived from `CMDIFrameWnd`. It indirectly contains the documents' frames, which are `CMDIChildWnd` objects. The `CMDIChildWnd` objects, in turn, contain the documents' views. diff --git a/docs/mfc/frame-window-classes-created-by-the-application-wizard.md b/docs/mfc/frame-window-classes-created-by-the-application-wizard.md index 746bebc3b4e..d6ff9610d4c 100644 --- a/docs/mfc/frame-window-classes-created-by-the-application-wizard.md +++ b/docs/mfc/frame-window-classes-created-by-the-application-wizard.md @@ -4,10 +4,12 @@ title: "Frame-Window Classes Created by the Application Wizard" ms.date: "11/04/2016" f1_keywords: ["CMainFrame"] helpviewer_keywords: ["application wizards [MFC], frame window classes created by", "window classes [MFC]", "classes [MFC], frame-window", "CMDIFrameWnd class [MFC], frame windows", "window classes [MFC], frame", "CFrameWnd class [MFC], frame windows", "CMDIChildWnd class [MFC], frame windows", "frame window classes [MFC], created by application wizards", "CMainFrame class [MFC]"] -ms.assetid: 9947df73-4470-49a0-ac61-7b6ee401a74e --- # Frame-Window Classes Created by the Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you to create a new MFC project from the **New Project** dialog, in addition to application, document, and view classes, the Application Wizard creates a derived frame-window class for your application's main frame window. The class is called `CMainFrame` by default, and the files that contain it are named MAINFRM.H and MAINFRM.CPP. If your application is SDI, your `CMainFrame` class is derived from class [CFrameWnd](reference/cframewnd-class.md). diff --git a/docs/mfc/frame-window-classes-windows.md b/docs/mfc/frame-window-classes-windows.md index 0f875746e21..ee535bfbb9d 100644 --- a/docs/mfc/frame-window-classes-windows.md +++ b/docs/mfc/frame-window-classes-windows.md @@ -4,10 +4,12 @@ title: "Frame Window Classes (Windows)" ms.date: "11/04/2016" f1_keywords: ["vc.classes.frame"] helpviewer_keywords: ["frame window classes [MFC], reference"] -ms.assetid: 6342ec5f-f922-4da8-a78e-2f5f994c7142 --- # Frame Window Classes (Windows) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Frame windows are windows that frame an application or a part of an application. Frame windows usually contain other windows, such as views, tool bars, and status bars. In the case of `CMDIFrameWnd`, they may contain `CMDIChildWnd` objects indirectly. [CFrameWnd](reference/cframewnd-class.md)
diff --git a/docs/mfc/frame-window-classes.md b/docs/mfc/frame-window-classes.md index b0c19b7b4d5..6b3ddcc18b3 100644 --- a/docs/mfc/frame-window-classes.md +++ b/docs/mfc/frame-window-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Frame-Window Classes" title: "Frame-Window Classes" ms.date: "11/04/2016" helpviewer_keywords: ["frame window classes [MFC], about frame window classes", "frame window classes [MFC]", "windows [MFC], MDI", "document frame windows [MFC], classes", "single document interface (SDI), frame windows", "window classes [MFC], frame", "MFC, frame windows", "MDI [MFC], frame windows", "classes [MFC], window"] -ms.assetid: c27e43a7-8ad0-4759-b1b7-43f4725f4132 --- # Frame-Window Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Each application has one "main frame window," a desktop window that usually has the application name in its caption. Each document usually has one "document frame window." A document frame window contains at least one view, which presents the document's data. ## Frame Windows in SDI and MDI Applications diff --git a/docs/mfc/frame-window-styles-cpp.md b/docs/mfc/frame-window-styles-cpp.md index 68735c8e2b4..8a8c08fbcb7 100644 --- a/docs/mfc/frame-window-styles-cpp.md +++ b/docs/mfc/frame-window-styles-cpp.md @@ -3,10 +3,12 @@ description: "Learn more about: Frame-Window Styles (C++)" title: "Frame-Window Styles (C++)" ms.date: "11/04/2016" helpviewer_keywords: ["window styles [MFC]", "PreCreateWindow method, setting window styles", "windows [MFC], MFC", "frame windows [MFC], styles", "MFC, frame windows", "styles [MFC], windows"] -ms.assetid: fc5058c1-eec8-48d8-9f76-3fc01cfa53f7 --- # Frame-Window Styles (C++) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The frame windows you get with the framework are suitable for most programs, but you can gain additional flexibility by using the advanced functions [PreCreateWindow](reference/cwnd-class.md#precreatewindow) and the MFC global function [AfxRegisterWndClass](reference/application-information-and-management.md#afxregisterwndclass). `PreCreateWindow` is a member function of `CWnd`. If you apply the **WS_HSCROLL** and **WS_VSCROLL** styles to the main frame window, they are instead applied to the **MDICLIENT** window so users can scroll the **MDICLIENT** area. diff --git a/docs/mfc/frame-windows.md b/docs/mfc/frame-windows.md index 8c8089e2eac..1bd2f9d2309 100644 --- a/docs/mfc/frame-windows.md +++ b/docs/mfc/frame-windows.md @@ -3,10 +3,12 @@ description: "Learn more about: Frame Windows" title: "Frame Windows" ms.date: "11/19/2018" helpviewer_keywords: ["document frame windows [MFC]", "windows [MFC], MDI", "window classes [MFC], frame", "single document interface (SDI) [MFC]", "single document interface (SDI) [MFC], frame windows", "views [MFC], and frame windows", "CFrameWnd class [MFC], frame windows", "frame windows [MFC]", "frame windows [MFC], about frame windows", "MFC, frame windows", "MDI [MFC], frame windows", "splitter windows [MFC], and frame windows"] -ms.assetid: 40677339-8135-4f5e-aba6-3fced3078077 --- # Frame Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When an application runs under Windows, the user interacts with documents displayed in frame windows. A document frame window has two major components: the frame and the contents that it frames. A document frame window can be a [single document interface](sdi-and-mdi.md) (SDI) frame window or a [multiple document interface](sdi-and-mdi.md) (MDI) child window. Windows manages most of the user's interaction with the frame window: moving and resizing the window, closing it, and minimizing and maximizing it. You manage the contents inside the frame. ## Frame Windows and Views diff --git a/docs/mfc/framework-mfc.md b/docs/mfc/framework-mfc.md index 0bd459a85d7..e7db2e8352d 100644 --- a/docs/mfc/framework-mfc.md +++ b/docs/mfc/framework-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Framework (MFC)" title: "Framework (MFC)" ms.date: "09/17/2019" helpviewer_keywords: ["encapsulation [MFC], Win32 API", "MFC, application framework", "wrapper classes [MFC], explained", "Win32 [MFC], API encapsulation by MFC", "application framework [MFC], about MFC application framework", "APIs [MFC], encapsulation by MFC Win32", "encapsulation [MFC]", "Windows API [MFC], encapsulation by MFC", "encapsulated Win32 API [MFC]"] -ms.assetid: 3be0fec8-9843-4119-ae42-ece993ef500b --- # Framework (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your work with the Microsoft Foundation Class (MFC) Library framework is based largely on a few major classes and several Visual C++ tools. Some classes encapsulate a large portion of the Win32 application programming interface (API). Other classes encapsulate application concepts such as documents, views, and the application itself. Still others encapsulate OLE features and ODBC and DAO data-access functionality. (DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete.) For example, Win32's concept of window is encapsulated by MFC class `CWnd`. That is, a C++ class called `CWnd` encapsulates or "wraps" the `HWND` handle that represents a Windows window. Likewise, class `CDialog` encapsulates Win32 dialog boxes. diff --git a/docs/mfc/general-class-design-philosophy.md b/docs/mfc/general-class-design-philosophy.md index 0057725329e..f38f1d3c423 100644 --- a/docs/mfc/general-class-design-philosophy.md +++ b/docs/mfc/general-class-design-philosophy.md @@ -3,10 +3,12 @@ description: "Learn more about: General Class Design Philosophy" title: "General Class Design Philosophy" ms.date: "11/04/2016" helpviewer_keywords: ["designing classes [MFC]", "MFC, Windows API", "Visual C, Windows API calls", "classes [MFC], MFC class design", "Windows API [MFC], and MFC"] -ms.assetid: e6861ae0-1581-4d9c-9ddf-63f9afcdb913 --- # General Class Design Philosophy +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Microsoft Windows was designed long before the C++ language became popular. Because thousands of applications use the C-language Windows application programming interface (API), that interface will be maintained for the foreseeable future. Any C++ Windows interface must therefore be built on top of the procedural C-language API. This guarantees that C++ applications will be able to coexist with C applications. The Microsoft Foundation Class Library is an object-oriented interface to Windows that meets the following design goals: diff --git a/docs/mfc/general-mfc-topics.md b/docs/mfc/general-mfc-topics.md index d1164397dce..2f263111a30 100644 --- a/docs/mfc/general-mfc-topics.md +++ b/docs/mfc/general-mfc-topics.md @@ -3,10 +3,12 @@ description: "Learn more about: General MFC Topics" title: "General MFC Topics" ms.date: "09/17/2019" helpviewer_keywords: ["MFC", "class libraries [MFC], MFC", "MFC, application development"] -ms.assetid: 617e9945-9bb3-471d-a3ba-e235fcfb55d1 --- # General MFC Topics +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This family of articles includes technical details about the Microsoft Foundation Class (MFC) Library and provides an overview of the MFC framework and its key components and subsystems. The Microsoft Foundation Class Library is an application framework for programming in Microsoft Windows. Written in C++, MFC provides much of the code necessary for managing windows, menus, and dialog boxes; performing basic input/output; storing collections of data objects; and so on. All you need to do is add your application-specific code into this framework. Given the nature of C++ class programming, it is easy to extend or override the basic functionality that [the MFC framework](framework-mfc.md) supplies. diff --git a/docs/mfc/general-window-creation-sequence.md b/docs/mfc/general-window-creation-sequence.md index ae89ab7bece..b8c0f220f2c 100644 --- a/docs/mfc/general-window-creation-sequence.md +++ b/docs/mfc/general-window-creation-sequence.md @@ -3,10 +3,12 @@ description: "Learn more about: General Window Creation Sequence" title: "General Window Creation Sequence" ms.date: "11/04/2016" helpviewer_keywords: ["sequence [MFC], window creation", "frame windows [MFC], creating", "windows [MFC], creating", "sequence [MFC]"] -ms.assetid: 9cd8c7ea-5e24-429e-b6d9-d7b6041d8ba6 --- # General Window Creation Sequence +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you create a window of your own, such as a child window, the framework uses much the same process as that described in [Document/View Creation](document-view-creation.md). All the window classes provided by MFC employ [two-stage construction](one-stage-and-two-stage-construction-of-objects.md). That is, during an invocation of the C++ **`new`** operator, the constructor allocates and initializes a C++ object but does not create a corresponding Windows window. That is done afterward by calling the [Create](reference/cwnd-class.md#create) member function of the window object. diff --git a/docs/mfc/global-hot-keys.md b/docs/mfc/global-hot-keys.md index 004ba568eab..4387b3750b4 100644 --- a/docs/mfc/global-hot-keys.md +++ b/docs/mfc/global-hot-keys.md @@ -3,10 +3,12 @@ description: "Learn more about: Global Hot Keys" title: "Global Hot Keys" ms.date: "11/04/2016" helpviewer_keywords: ["keyboard shortcuts [MFC], hot keys", "CHotKeyCtrl class [MFC], global hot keys", "access keys [MFC], hot keys", "global hot keys [MFC]"] -ms.assetid: e0b95d14-c571-4c9a-9cd1-e7fc1f0e278d --- # Global Hot Keys +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A global hot key is associated with a particular nonchild window. It allows the user to activate the window from any part of the system. An application sets a global hot key for a particular window by sending the [WM_SETHOTKEY](/windows/win32/inputdev/wm-sethotkey) message to that window. For instance, if `m_HotKeyCtrl` is the [CHotKeyCtrl](reference/chotkeyctrl-class.md) object and `pMainWnd` is a pointer to the window to be activated when the hot key is pressed, you could use the following code to associate the hot key specified in the control with the window pointed to by `pMainWnd`. [!code-cpp[NVC_MFCControlLadenDialog#18](codesnippet/cpp/global-hot-keys_1.cpp)] diff --git a/docs/mfc/graphic-objects.md b/docs/mfc/graphic-objects.md index 5d7445e9f6e..196ecb4edba 100644 --- a/docs/mfc/graphic-objects.md +++ b/docs/mfc/graphic-objects.md @@ -4,10 +4,12 @@ title: "Graphic Objects" ms.date: "11/04/2016" f1_keywords: ["HRGN", "HFONT", "HBITMAP"] helpviewer_keywords: ["CRgn class [MFC], HRGN handle type", "HPEN [MFC]", "objects [MFC], graphic", "palettes [MFC], creating in device context", "pens [MFC], creating in device context", "bitmaps [MFC], creating in device contexts", "palette objects [MFC]", "memory [MFC], display contexts", "MFC, graphic objects", "regions [MFC], creating in device context", "CPen class [MFC], HPEN handle type", "GDI objects [MFC]", "HRGN [MFC]", "graphic objects [MFC]", "GDI objects [MFC], graphic-object classes", "CFont class [MFC], HFONT handle type", "HFONT and class CFont [MFC]", "HBITMAP and class CBitmap [MFC]", "fonts [MFC], creating in device context", "images [MFC], graphic objects [MFC]", "CBitmap class [MFC], HBITMAP handle type", "HPALETTE and class CPalette [MFC]", "CBrush class [MFC], HBRUSH handle type", "objects [MFC], graphic objects", "drawing [MFC], in device contexts", "device contexts [MFC], graphic objects [MFC]", "brushes [MFC], creating in device context", "region objects [MFC]", "pen objects [MFC]", "GDI [MFC], graphic-object classes", "graphic objects [MFC], creating in device context", "HBRUSH and class CBrush [MFC]", "painting and device context [MFC]", "CPalette class [MFC], HPALETTE handle type"] -ms.assetid: 41963b25-34b7-4343-8446-34ba516b83ca --- # Graphic Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Windows provides a variety of drawing tools to use in device contexts. It provides pens to draw lines, brushes to fill interiors, and fonts to draw text. MFC provides graphic-object classes equivalent to the drawing tools in Windows. The table below shows the available classes and the equivalent Windows graphics device interface (GDI) handle types. > [!NOTE] diff --git a/docs/mfc/handlers-for-commands-and-control-notifications.md b/docs/mfc/handlers-for-commands-and-control-notifications.md index 739d0f6dcf0..dda508b3e70 100644 --- a/docs/mfc/handlers-for-commands-and-control-notifications.md +++ b/docs/mfc/handlers-for-commands-and-control-notifications.md @@ -3,10 +3,12 @@ description: "Learn more about: Handlers for Commands and Control Notifications" title: "Handlers for Commands and Control Notifications" ms.date: "11/04/2016" helpviewer_keywords: ["commands [MFC], handlers for", "functions [MFC], handler", "handlers [MFC]", "controls [MFC], notifications", "handlers [MFC], control notification [MFC]", "notifications [MFC], handlers for control", "handlers [MFC], command"] -ms.assetid: 20f57f4a-f577-4c09-80a2-43faf32a1c2e --- # Handlers for Commands and Control Notifications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are no default handlers for commands or control-notification messages. Therefore, you are bound only by convention in naming your handlers for these categories of messages. When you map the command or control notification to a handler, the [Class Wizard](reference/mfc-class-wizard.md) proposes a name based on the command ID or control-notification code. You can accept the proposed name, change it, or replace it. Convention suggests that you name handlers in both categories for the user-interface object they represent. Thus a handler for the Cut command on the Edit menu might be named diff --git a/docs/mfc/handlers-for-message-map-ranges.md b/docs/mfc/handlers-for-message-map-ranges.md index 6e74a048aaf..d7e36d824a8 100644 --- a/docs/mfc/handlers-for-message-map-ranges.md +++ b/docs/mfc/handlers-for-message-map-ranges.md @@ -3,10 +3,12 @@ description: "Learn more about: Handlers for Message-Map Ranges" title: "Handlers for Message-Map Ranges" ms.date: "11/04/2016" helpviewer_keywords: ["message handlers [MFC]", "handlers [MFC], message-map ranges", "message maps [MFC], message handler functions", "message maps [MFC], ranges", "control-notification messages [MFC]", "command IDs [MFC], message mapping", "message-map ranges [MFC]", "handlers [MFC]", "message handling [MFC], message handler functions", "mappings [MFC], message ranges", "command handling [MFC], command update handlers", "controls [MFC], notifications", "handler functions [MFC], message-map ranges", "handler functions [MFC]", "command update handlers [MFC]", "command routing [MFC], command update handlers", "message ranges [MFC]", "handler functions [MFC], declaring", "message ranges [MFC], mapping"] -ms.assetid: a271478b-5e1c-46f5-9f29-e5be44b27d08 --- # Handlers for Message-Map Ranges +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to map a range of messages to a single message handler function (instead of mapping one message to only one function). There are times when you need to process more than one message or control notification in exactly the same way. At such times, you might wish to map all of the messages to a single handler function. Message-map ranges allow you to do this for a contiguous range of messages: diff --git a/docs/mfc/handlers-for-standard-windows-messages.md b/docs/mfc/handlers-for-standard-windows-messages.md index 7554c3d59ea..5292702cde8 100644 --- a/docs/mfc/handlers-for-standard-windows-messages.md +++ b/docs/mfc/handlers-for-standard-windows-messages.md @@ -4,10 +4,12 @@ title: "Handlers for Standard Windows Messages" ms.date: "11/04/2016" f1_keywords: ["afx_msg"] helpviewer_keywords: ["Windows messages [MFC], handlers", "message handling [MFC], Windows message handlers", "handler functions, standard Windows messages", "functions [MFC], handler", "messages [MFC], Windows"] -ms.assetid: 19412a8b-2c38-4502-81da-13c823c7e36c --- # Handlers for Standard Windows Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Default handlers for standard Windows messages (**WM_**) are predefined in class `CWnd`. The class library bases names for these handlers on the message name. For example, the handler for the **WM_PAINT** message is declared in `CWnd` as: `afx_msg void OnPaint();` diff --git a/docs/mfc/handling-commands-in-the-document.md b/docs/mfc/handling-commands-in-the-document.md index 9d43c35b0d5..48f29840f9e 100644 --- a/docs/mfc/handling-commands-in-the-document.md +++ b/docs/mfc/handling-commands-in-the-document.md @@ -3,10 +3,13 @@ description: "Learn more about: Handling Commands in the Document" title: "Handling Commands in the Document" ms.date: "11/04/2016" helpviewer_keywords: ["message maps [MFC], in document class", "command handling [MFC]", "documents [MFC], message maps", "message handling [MFC], WM_COMMAND messages", "command handling [MFC], commands in documents", "documents [MFC], handling messages in"] -ms.assetid: c7375584-27af-4275-b2fd-afea476785d0 +ms.topic: concept-article --- # Handling Commands in the Document +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your document class may also handle certain commands generated by menu items, toolbar buttons, or accelerator keys. By default, `CDocument` handles the Save and Save As commands on the File menu, using serialization. Other commands that affect the data may also be handled by member functions of your document. For example, in the Scribble program, class `CScribDoc` provides a handler for the Edit Clear All command, which deletes all of the data currently stored in the document. Documents can have message maps, but unlike views, documents cannot handle standard Windows messages — only **WM_COMMAND** messages, or "commands." ## See also diff --git a/docs/mfc/handling-customization-notifications.md b/docs/mfc/handling-customization-notifications.md index 86936b07f95..9a28ecd13b4 100644 --- a/docs/mfc/handling-customization-notifications.md +++ b/docs/mfc/handling-customization-notifications.md @@ -4,10 +4,13 @@ title: "Handling Customization Notifications" ms.date: "11/04/2016" f1_keywords: ["TBN_CUSTHELP", "TBN_QUERYINSERT", "TBNOTIFY", "NMHDR", "TBN_TOOLBARCHANGE", "TBN_ENDDRAG", "NM_SETFOCUS", "TBN_RESET", "NM_RETURN", "NM_ENDWAIT", "NM_STARTWAIT", "TBN_BEGINDRAG", "NM_OUTOFMEMORY", "TBN_QUERYDELETE", "NM_DBLCLK", "TBN_ENDADJUST", "NM_KILLFOCUS", "NM_RCLICK", "TBN_BEGINADJUST", "NM_CLICK"] helpviewer_keywords: ["TBN_ENDADJUST notification [MFC]", "TBNOTIFY notification [MFC]", "TBN_BEGINDRAG notification [MFC]", "TBN_TOOLBARCHANGE notification [MFC]", "NM_CLICK notification [MFC]", "NM_RETURN notification [MFC]", "NM_RCLICK notification [MFC]", "TBN_ENDDRAG notification [MFC]", "TBN_BEGINADJUST notification [MFC]", "NM_ENDWAIT notification [MFC]", "NM_KILLFOCUS notification [MFC]", "NM_SETFOCUS notification [MFC]", "NM_OUTOFMEMORY notification [MFC]", "TBN_QUERYINSERT notification [MFC]", "NMHDR [MFC]", "NM_STARTWAIT notification [MFC]", "CToolBarCtrl class [MFC], handling notifications", "TBN_CUSTHELP notification [MFC]", "TBN_RESET notification [MFC]", "NM_DBLCLK notification [MFC]", "TBN_QUERYDELETE notification [MFC]", "NM_RDBLCLK notification [MFC]", "TBN_GETBUTTONINFO notification [MFC]"] -ms.assetid: 219ea08e-7515-4b98-85cb-47120f08c0a2 +ms.topic: concept-article --- # Handling Customization Notifications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A Windows toolbar common control has built-in customization features, including a system-defined customization dialog box, which allow the user to insert, delete, or rearrange toolbar buttons. The application determines whether the customization features are available and controls the extent to which the user can customize the toolbar. You can make these customization features available to the user by giving the toolbar the **CCS_ADJUSTABLE** style. The customization features allow the user to drag a button to a new position or to remove a button by dragging it off the toolbar. In addition, the user can double-click the toolbar to display the **Customize Toolbar** dialog box, which allows the user to add, delete, and rearrange toolbar buttons. The application can display the dialog box by using the [Customize](reference/ctoolbarctrl-class.md#customize) member function. diff --git a/docs/mfc/handling-reflected-messages.md b/docs/mfc/handling-reflected-messages.md index 95b15f8a980..ccb42f01c17 100644 --- a/docs/mfc/handling-reflected-messages.md +++ b/docs/mfc/handling-reflected-messages.md @@ -3,10 +3,13 @@ description: "Learn more about: Handling Reflected Messages" title: "Handling Reflected Messages" ms.date: "11/04/2016" helpviewer_keywords: ["message handling [MFC], reflected messages", "reflected messages, handling"] -ms.assetid: 147a4e0c-51cc-4447-a8e1-c28b4cece578 +ms.topic: concept-article --- # Handling Reflected Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Message reflection lets you handle messages for a control, such as **WM_CTLCOLOR**, **WM_COMMAND**, and **WM_NOTIFY**, within the control itself. This makes the control more self-contained and portable. The mechanism works with Windows common controls as well as with ActiveX controls (formerly called OLE controls). Message reflection lets you reuse your `CWnd`-derived classes more readily. Message reflection works via [CWnd::OnChildNotify](reference/cwnd-class.md#onchildnotify), using special **ON_XXX_REFLECT** message map entries: for example, **ON_CTLCOLOR_REFLECT** and **ON_CONTROL_REFLECT**. [Technical Note 62](tn062-message-reflection-for-windows-controls.md) explains message reflection in more detail. diff --git a/docs/mfc/handling-the-apply-button.md b/docs/mfc/handling-the-apply-button.md index 0c1e31e8d0d..bb46aa7c06c 100644 --- a/docs/mfc/handling-the-apply-button.md +++ b/docs/mfc/handling-the-apply-button.md @@ -3,10 +3,13 @@ description: "Learn more about: Handling the Apply Button" title: "Handling the Apply Button" ms.date: "11/04/2016" helpviewer_keywords: ["Apply button in property sheet", "property sheets, Apply button"] -ms.assetid: 7e977015-59b8-406f-b545-aad0bfd8d55b +ms.topic: concept-article --- # Handling the Apply Button +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Property sheets have a capability that standard dialog boxes do not: They allow the user to apply changes they have made before closing the property sheet. This is done using the Apply button. This article discusses methods you can use to implement this feature properly. Modal dialog boxes usually apply the settings to an external object when the user clicks OK to close the dialog box. The same is true for a property sheet: When the user clicks OK, the new settings in the property sheet take effect. diff --git a/docs/mfc/handling-tool-tip-notifications.md b/docs/mfc/handling-tool-tip-notifications.md index d950042ea4e..8d03fb75ae9 100644 --- a/docs/mfc/handling-tool-tip-notifications.md +++ b/docs/mfc/handling-tool-tip-notifications.md @@ -3,10 +3,13 @@ description: "Learn more about: Handling Tool Tip Notifications" title: "Handling Tool Tip Notifications" ms.date: "11/04/2016" helpviewer_keywords: ["TOOLTIPTEXT structure [MFC]", "CToolBarCtrl class [MFC], handling notifications", "notifications [MFC], tool tips", "tool tips [MFC], notifications"] -ms.assetid: ddb93b5f-2e4f-4537-8053-3453c86e2bbb +ms.topic: concept-article --- # Handling Tool Tip Notifications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you specify the **TBSTYLE_TOOLTIPS** style, the toolbar creates and manages a tool tip control. A tool tip is a small pop-up window that contains a line of text describing a toolbar button. The tool tip is hidden, appearing only when the user puts the cursor on a toolbar button and leaves it there for approximately one-half second. The tool tip is displayed near the cursor. Before the tool tip is displayed, the **TTN_NEEDTEXT** notification message is sent to the toolbar's owner window to retrieve the descriptive text for the button. If the toolbar's owner window is a `CFrameWnd` window, tool tips are displayed without any extra effort, because `CFrameWnd` has a default handler for the **TTN_NEEDTEXT** notification. If the toolbar's owner window is not derived from `CFrameWnd`, such as a dialog box or form view, you must add an entry to your owner window's message map and provide a notification handler in the message map. The entry to your owner window's message map is as follows: diff --git a/docs/mfc/handling-ttn-needtext-notification-for-tool-tips.md b/docs/mfc/handling-ttn-needtext-notification-for-tool-tips.md index 982332e7103..8e0115299df 100644 --- a/docs/mfc/handling-ttn-needtext-notification-for-tool-tips.md +++ b/docs/mfc/handling-ttn-needtext-notification-for-tool-tips.md @@ -4,10 +4,13 @@ title: "Handling TTN_NEEDTEXT Notification for Tool Tips" ms.date: "11/04/2016" f1_keywords: ["TTN_NEEDTEXT"] helpviewer_keywords: ["TTN_NEEDTEXT message [MFC]", "notifications [MFC], tool tips", "tool tips [MFC], notifications"] -ms.assetid: d0370a65-21ba-4676-bcc5-8cf851bbb15c +ms.topic: concept-article --- # Handling TTN_NEEDTEXT Notification for Tool Tips +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As part of [enabling tool tips](enabling-tool-tips.md), you handle the **TTN_NEEDTEXT** message by adding the following entry to your owner window's message map: [!code-cpp[NVC_MFCControlLadenDialog#40](codesnippet/cpp/handling-ttn-needtext-notification-for-tool-tips_1.cpp)] diff --git a/docs/mfc/handling-windows-messages-in-your-dialog-box.md b/docs/mfc/handling-windows-messages-in-your-dialog-box.md index 170b2d46512..d2c9173a4d9 100644 --- a/docs/mfc/handling-windows-messages-in-your-dialog-box.md +++ b/docs/mfc/handling-windows-messages-in-your-dialog-box.md @@ -3,10 +3,13 @@ description: "Learn more about: Handling Windows Messages in Your Dialog Box" title: "Handling Windows Messages in Your Dialog Box" ms.date: "09/05/2019" helpviewer_keywords: ["MFC dialog boxes [MFC], Windows messages", "Windows messages [MFC], handling", "message handling [MFC], in dialog boxes"] -ms.assetid: 4af0c9cb-09da-4b15-97df-a1cfb89def79 +ms.topic: concept-article --- # Handling Windows Messages in Your Dialog Box +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Dialog boxes are windows, so they can handle Windows messages if you supply the appropriate handler functions. When you create your dialog class with the [Class Wizard](reference/mfc-class-wizard.md), the wizard adds an empty message map to the class. Use the wizard to map any Windows messages or commands you want your class to handle. See [Mapping Windows Messages to Your Dialog Class](mapping-windows-messages-to-your-class.md) for more information. diff --git a/docs/mfc/header-control-and-list-control.md b/docs/mfc/header-control-and-list-control.md index 447a06ef773..fe9450fb237 100644 --- a/docs/mfc/header-control-and-list-control.md +++ b/docs/mfc/header-control-and-list-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Header Control and List Control" title: "Header Control and List Control" ms.date: "11/04/2016" helpviewer_keywords: ["CListCtrl class [MFC], with CHeaderCtrl", "CListCtrl class [MFC], header controls", "CHeaderCtrl class [MFC], with CListCtrl", "controls [MFC], header", "header controls [MFC]", "header controls [MFC], list controls used with"] -ms.assetid: b20194b1-1a6b-4e2f-b890-1b3cca6650bc --- # Header Control and List Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In most cases, you will use the header control that is embedded in a [CListCtrl](reference/clistctrl-class.md) or [CListView](reference/clistview-class.md) object. However, there are cases where a separate header control object is desirable, such as manipulating data, arranged in columns or rows, in a [CView](reference/cview-class.md)-derived object. In these cases, you need greater control over the appearance and default behavior of an embedded header control. In the common case that you want a header control to provide standard, default behavior, you may want to use [CListCtrl](reference/clistctrl-class.md) or [CListView](reference/clistview-class.md) instead. Use `CListCtrl` when you want the functionality of a default header control, embedded in a list view common control. Use [CListView](reference/clistview-class.md) when you want the functionality of a default header control, embedded in a view object. diff --git a/docs/mfc/header-control-examples.md b/docs/mfc/header-control-examples.md index 19e93cf27ee..831c040b22e 100644 --- a/docs/mfc/header-control-examples.md +++ b/docs/mfc/header-control-examples.md @@ -3,10 +3,12 @@ description: "Learn more about: Header Control Examples" title: "Header Control Examples" ms.date: "11/04/2016" helpviewer_keywords: ["sample applications [MFC], header controls", "controls [MFC], header"] -ms.assetid: 30050732-d53e-4eab-88d7-61aac52914c9 --- # Header Control Examples +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For examples of header controls, see the [Header Controls](/windows/win32/Controls/header-controls) in the Windows SDK. ## See also diff --git a/docs/mfc/header-items-in-a-header-control.md b/docs/mfc/header-items-in-a-header-control.md index 86592027737..6090d24d31c 100644 --- a/docs/mfc/header-items-in-a-header-control.md +++ b/docs/mfc/header-items-in-a-header-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Header Items in a Header Control" title: "Header Items in a Header Control" ms.date: "11/04/2016" helpviewer_keywords: ["header controls [MFC], header items in", "header items in header controls [MFC]", "CHeaderCtrl class [MFC], header items in", "controls [MFC], header"] -ms.assetid: ac79ef1f-a671-4ab2-93e9-b1aa016a48bf --- # Header Items in a Header Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You have considerable control over the appearance and behavior of the header items that make up a header control ([CHeaderCtrl](reference/cheaderctrl-class.md)). Each header item can have a string, a bitmapped image, an image from an associated image list, or an application-defined 32-bit value associated with it. The string, bitmap, or image is displayed in the header item. You can customize the appearance and contents of new items when they are created by making a call [CHeaderCtrl::InsertItem](reference/cheaderctrl-class.md#insertitem) or by modifying an existing item, with a call to [CHeaderCtrl::GetItem](reference/cheaderctrl-class.md#getitem) and [CHeaderCtrl::SetItem](reference/cheaderctrl-class.md#setitem). diff --git a/docs/mfc/headers-and-footers.md b/docs/mfc/headers-and-footers.md index 52ce6bbb624..56c7002ac02 100644 --- a/docs/mfc/headers-and-footers.md +++ b/docs/mfc/headers-and-footers.md @@ -3,10 +3,12 @@ description: "Learn more about: Headers and Footers" title: "Headers and Footers" ms.date: "11/04/2016" helpviewer_keywords: ["printing [MFC], multipage documents", "page headers [MFC], printing", "headers [MFC], printing", "footers [MFC], printing", "page footers [MFC], printing", "page headers [MFC]", "printing [MFC], headers and footers", "page footers [MFC]"] -ms.assetid: b0be9c53-5773-4955-a777-3c15da745128 --- # Headers and Footers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to add headers and footers to a printed document. When you look at a document on the screen, the name of the document and your current location in the document are commonly displayed in a title bar and a status bar. When looking at a printed copy of a document, it's useful to have the name and page number shown in a header or footer. This is a common way in which even WYSIWYG programs differ in how they perform printing and screen display. diff --git a/docs/mfc/help-menu-merging.md b/docs/mfc/help-menu-merging.md index 39addc15747..4034238ed17 100644 --- a/docs/mfc/help-menu-merging.md +++ b/docs/mfc/help-menu-merging.md @@ -3,10 +3,12 @@ description: "Learn more about: Help Menu Merging" title: "Help Menu Merging" ms.date: "11/04/2016" helpviewer_keywords: ["menus [MFC], merging", "merging Help menus [MFC]", "Help [MFC], for active document containers"] -ms.assetid: 9d615999-79ba-471a-9288-718f0c903d49 --- # Help Menu Merging +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When an object is active within a container, the menu merging protocol of OLE Documents gives the object complete control of the **Help** menu. As a result, the container's Help topics are not available unless the user deactivates the object. The active document containment architecture expands on the rules for in-place menu merging to allow both the container and an active document that is active to share the menu. The new rules are simply additional conventions about what component owns what part of the menu and how the shared menu is constructed. The new convention is simple. In active documents, the **Help** menu has two top-level menu items organized as follows: diff --git a/docs/mfc/hierarchy-chart-categories.md b/docs/mfc/hierarchy-chart-categories.md index 288eb786579..4dc22030a09 100644 --- a/docs/mfc/hierarchy-chart-categories.md +++ b/docs/mfc/hierarchy-chart-categories.md @@ -3,10 +3,12 @@ description: "Learn more about: Hierarchy Chart Categories" title: "Hierarchy Chart Categories" ms.date: "11/19/2018" helpviewer_keywords: ["MFC, hierarchy"] -ms.assetid: 1f109428-4b84-4f7c-90a9-e71fe071311e --- # Hierarchy Chart Categories +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + ![MFC hierarchy chart categories.](../mfc/media/vc369r1.png "MFC hierarchy chart categories") ## See also diff --git a/docs/mfc/hierarchy-chart.md b/docs/mfc/hierarchy-chart.md index 7f7b93ff509..97e09c128bd 100644 --- a/docs/mfc/hierarchy-chart.md +++ b/docs/mfc/hierarchy-chart.md @@ -3,10 +3,12 @@ description: "See the MFC class hierarchy in chart form." title: "MFC class hierarchy chart" ms.date: 09/10/2021 helpviewer_keywords: ["object models, MFC", "classes [MFC], MFC hierarchy", "MFC, object model"] -ms.assetid: 19d70341-e391-4a72-94c6-35755ce975d4 --- # MFC class hierarchy chart +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following illustration represents the MFC classes derived from `CObject`: :::image type="content" source="../mfc/media/mfc-hierarchy-chart-part-1-of-3.png" alt-text="Chart that lists the MFC classes derived from CObject."::: diff --git a/docs/mfc/how-default-printing-is-done.md b/docs/mfc/how-default-printing-is-done.md index 1226570b146..df9f6291768 100644 --- a/docs/mfc/how-default-printing-is-done.md +++ b/docs/mfc/how-default-printing-is-done.md @@ -3,10 +3,12 @@ description: "Learn more about: How Default Printing Is Done" title: "How Default Printing Is Done" ms.date: "11/04/2016" helpviewer_keywords: ["default printing", "printing [MFC], default", "defaults, printing"] -ms.assetid: 0f698459-0fc9-4d43-97da-29cf0f65daa2 --- # How Default Printing Is Done +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the default printing process in Windows in terms of the MFC framework. In MFC applications, the view class has a member function named `OnDraw` that contains all the drawing code. `OnDraw` takes a pointer to a [CDC](reference/cdc-class.md) object as a parameter. That `CDC` object represents the device context to receive the image produced by `OnDraw`. When the window displaying the document receives a [WM_PAINT](/windows/win32/gdi/wm-paint) message, the framework calls `OnDraw` and passes it a device context for the screen (a [CPaintDC](reference/cpaintdc-class.md) object, to be specific). Accordingly, `OnDraw`'s output goes to the screen. diff --git a/docs/mfc/how-mfc-makes-it-easier-to-create-internet-client-applications.md b/docs/mfc/how-mfc-makes-it-easier-to-create-internet-client-applications.md index 543a3124945..ec12c0c8a4c 100644 --- a/docs/mfc/how-mfc-makes-it-easier-to-create-internet-client-applications.md +++ b/docs/mfc/how-mfc-makes-it-easier-to-create-internet-client-applications.md @@ -3,10 +3,12 @@ description: "Learn more about: How MFC Makes It Easier to Create Internet Clien title: "How MFC Makes It Easier to Create Internet Client Applications" ms.date: "11/04/2016" helpviewer_keywords: ["Internet client applications [MFC], MFC", "Internet applications [MFC], MFC", "MFC, Internet applications"] -ms.assetid: 94437b3f-f15c-437d-b5fd-264a2efec9ab --- # How MFC Makes It Easier to Create Internet Client Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Classes encapsulate the Win32 Internet Extension (WinInet) functions in a manner that provides a familiar context for MFC programmers. MFC provides three Internet file classes ([CInternetFile](reference/cinternetfile-class.md), [CHttpFile](reference/chttpfile-class.md), and [CGopherFile](reference/cgopherfile-class.md)) derived from the [CStdioFile](reference/cstdiofile-class.md) class. Not only do these classes make retrieving and manipulating Internet data familiar to programmers who have used `CStdioFile` for local files, but with these classes you can handle local files and Internet files in a consistent, transparent manner. The MFC WinInet classes provide the same functionality as `CStdioFile` for data that is transferred across the Internet. These classes abstract the Internet protocols for HTTP, FTP, and gopher into a high-level application programming interface, providing a fast and straightforward path to making applications Internet-aware. For example, connecting to an FTP server still requires several steps at a low level, but as an MFC developer, you only need to make one call to `CInternetSession::GetFTPConnection` to create that connection. diff --git a/docs/mfc/how-noncommand-messages-reach-their-handlers.md b/docs/mfc/how-noncommand-messages-reach-their-handlers.md index 8f7350006f1..ff32666a224 100644 --- a/docs/mfc/how-noncommand-messages-reach-their-handlers.md +++ b/docs/mfc/how-noncommand-messages-reach-their-handlers.md @@ -3,10 +3,12 @@ description: "Learn more about: How Noncommand Messages Reach Their Handlers" title: "How Noncommand Messages Reach Their Handlers" ms.date: "11/04/2016" helpviewer_keywords: ["messages [MFC], routing", "noncommand messages", "Windows messages [MFC], routing", "message handling [MFC], noncommand messages"] -ms.assetid: e7df8aef-9fae-41f4-9c11-881d8465f602 --- # How Noncommand Messages Reach Their Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Unlike commands, standard Windows messages do not get routed through a chain of command targets but are usually handled by the window to which Windows sends the message. The window might be a main frame window, an MDI child window, a standard control, a dialog box, a view, or some other kind of child window. At run time, each Windows window is attached to a window object (derived directly or indirectly from `CWnd`) that has its own associated message map and handler functions. The framework uses the message map — as for a command — to map incoming messages to handlers. diff --git a/docs/mfc/how-the-framework-calls-a-handler.md b/docs/mfc/how-the-framework-calls-a-handler.md index 9faf7aa2bb0..b3989ca0b58 100644 --- a/docs/mfc/how-the-framework-calls-a-handler.md +++ b/docs/mfc/how-the-framework-calls-a-handler.md @@ -3,10 +3,12 @@ description: "Learn more about: How the Framework Calls a Handler" title: "How the Framework Calls a Handler" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, command routing", "handler functions, MFC framework", "command handling [MFC], calling handlers and code in MFC", "command routing [MFC], MFC"] -ms.assetid: d79bceba-4ff6-417a-9d52-6b6af62a909d --- # How the Framework Calls a Handler +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following topics first examine how the framework routes commands, then examine how other messages and control notifications are sent to windows: - [Message sending and receiving](message-sending-and-receiving.md) diff --git a/docs/mfc/how-the-framework-calls-your-code.md b/docs/mfc/how-the-framework-calls-your-code.md index af6f336b695..eb3f6d02366 100644 --- a/docs/mfc/how-the-framework-calls-your-code.md +++ b/docs/mfc/how-the-framework-calls-your-code.md @@ -3,10 +3,12 @@ description: "Learn more about: How the Framework Calls Your Code" title: "How the Framework Calls Your Code" ms.date: "11/04/2016" helpviewer_keywords: ["control flow [MFC], MFC framework and your code", "events [MFC], command routing in MFC", "command routing [MFC], framework", "command handling [MFC], calling handlers and code in MFC", "events [MFC], event-driven programming", "MFC, calling code from", "MFC, calling code", "application-specific events [MFC]", "command routing [MFC], MFC"] -ms.assetid: 39e68189-a580-40d0-9e35-bf5cd24a8ecf --- # How the Framework Calls Your Code +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + It is crucial to understand the relationship between your source code and the code in the MFC framework. When your application runs, most of the flow of control resides in the framework's code. The framework manages the message loop that gets messages from Windows as the user chooses commands and edits data in a view. Events that the framework can handle by itself do not rely on your code at all. For example, the framework knows how to close windows and how to exit the application in response to user commands. As it handles these tasks, the framework uses message handlers and C++ virtual functions to give you opportunities to respond to these events as well. Your code is not in control, however; the framework is. The framework calls your code for application-specific events. For example, when the user chooses a menu command, the framework routes the command along a sequence of C++ objects: the current view and frame window, the document associated with the view, the document's document template, and the application object. If one of these objects can handle the command, it does so, calling the appropriate message-handler function. For any given command, the code called may be yours or it may be the framework's. diff --git a/docs/mfc/how-the-framework-searches-message-maps.md b/docs/mfc/how-the-framework-searches-message-maps.md index f5b25c415ba..02d172cda6d 100644 --- a/docs/mfc/how-the-framework-searches-message-maps.md +++ b/docs/mfc/how-the-framework-searches-message-maps.md @@ -3,10 +3,12 @@ description: "Learn more about: How the Framework Searches Message Maps" title: "How the Framework Searches Message Maps" ms.date: "11/04/2016" helpviewer_keywords: ["message maps [MFC], searching"] -ms.assetid: fd1df878-5601-45d7-bd1f-b8f8e65b9a17 --- # How the Framework Searches Message Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The framework searches the message-map table for matches with incoming messages. Once you write a message-map entry for each message you want a class to handle and write the corresponding handlers, the framework calls your handlers automatically. The following topics explain message-map searching: - [Where to find message maps](where-to-find-message-maps.md) diff --git a/docs/mfc/how-to-add-restart-manager-support.md b/docs/mfc/how-to-add-restart-manager-support.md index f568efe5421..18bf6bfd20f 100644 --- a/docs/mfc/how-to-add-restart-manager-support.md +++ b/docs/mfc/how-to-add-restart-manager-support.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Add Restart Manager Support" title: "How to: Add Restart Manager Support" ms.date: "11/04/2016" helpviewer_keywords: ["Restart manager [MFC]", "C++, application crash support"] -ms.assetid: 7f3f5867-d4bc-4ba8-b3c9-dc1e7be93642 --- # How to: Add Restart Manager Support +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The restart manager is a feature added to Visual Studio for Windows Vista or later operating systems. The restart manager adds support for your application if it unexpectedly closes or restarts. The behavior of the restart manager depends on the type of your application. If your application is a document editor, the restart manager enabled your application to automatically save the state and content of any open documents and restarts your application after an unexpected closure. If your application is not a document editor, the restart manager will restart the application, but it cannot save the state of the application by default. After restart, the application displays a task dialog box if the application is Unicode. If it is an ANSI application, the application displays a Windows Message box. At this point, the user chooses whether to restore the automatically saved documents. If the user does not restore the automatically saved documents, the restart manager discards the temporary files. diff --git a/docs/mfc/how-to-add-ribbon-controls-and-event-handlers.md b/docs/mfc/how-to-add-ribbon-controls-and-event-handlers.md index 803855f0314..ce22746e9f4 100644 --- a/docs/mfc/how-to-add-ribbon-controls-and-event-handlers.md +++ b/docs/mfc/how-to-add-ribbon-controls-and-event-handlers.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Add Ribbon Controls and Event Handlers" title: "How to: Add Ribbon Controls and Event Handlers" ms.date: "11/04/2016" helpviewer_keywords: ["event handlers [MFC], adding", "ribbon controls [MFC], adding"] -ms.assetid: b31f25bc-ede7-49c3-9e3c-dffe4e174a69 --- # How to: Add Ribbon Controls and Event Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Ribbon controls are elements, such as buttons and combo boxes, that you add to panels. Panels are areas of the ribbon bar that display a group of related controls. In this topic, you will open the Ribbon Designer, add a button, and then link an event that displays "Hello World". diff --git a/docs/mfc/how-to-convert-an-existing-mfc-ribbon-to-a-ribbon-resource.md b/docs/mfc/how-to-convert-an-existing-mfc-ribbon-to-a-ribbon-resource.md index e0e84a33917..c33c9d6e5f6 100644 --- a/docs/mfc/how-to-convert-an-existing-mfc-ribbon-to-a-ribbon-resource.md +++ b/docs/mfc/how-to-convert-an-existing-mfc-ribbon-to-a-ribbon-resource.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Convert an Existing MFC Ribbon to a Ribb title: "How to: Convert an Existing MFC Ribbon to a Ribbon Resource" ms.date: "11/04/2016" helpviewer_keywords: ["ribbon resource, converting from an MFC ribbon", "MFC ribbon, converting to a ribbon resource"] -ms.assetid: 324b7ff6-58f9-4691-96a9-9836a79d0fb6 --- # How to: Convert an Existing MFC Ribbon to a Ribbon Resource +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Ribbon resources are easier to visualize, modify, and maintain than manually coded ribbons. This topic describes how to convert a manually coded ribbon in an MFC Project into a ribbon resource. You must have an existing MFC project that has code that uses the MFC ribbon classes, for example, [CMFCRibbonBar Class](reference/cmfcribbonbar-class.md). diff --git a/docs/mfc/how-to-create-a-message-map-for-a-template-class.md b/docs/mfc/how-to-create-a-message-map-for-a-template-class.md index 39e4c4ec594..56465c75912 100644 --- a/docs/mfc/how-to-create-a-message-map-for-a-template-class.md +++ b/docs/mfc/how-to-create-a-message-map-for-a-template-class.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Create a Message Map for a Template Clas title: "How to: Create a Message Map for a Template Class" ms.date: "11/04/2016" helpviewer_keywords: ["template classes [MFC], creating message maps", "message maps [MFC], template classes"] -ms.assetid: 4e7e24f8-06df-4b46-82aa-7435c8650de3 --- # How to: Create a Message Map for a Template Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Message mapping in MFC provides an efficient way to direct Windows messages to an appropriate C++ object instance. Examples of MFC message map targets include application classes, document and view classes, control classes, and so on. Traditional MFC message maps are declared using the [BEGIN_MESSAGE_MAP](reference/message-map-macros-mfc.md#begin_message_map) macro to declare the start of the message map, a macro entry for each message-handler class method, and finally the [END_MESSAGE_MAP](reference/message-map-macros-mfc.md#end_message_map) macro to declare the end of the message map. diff --git a/docs/mfc/how-to-customize-the-application-button.md b/docs/mfc/how-to-customize-the-application-button.md index 8a9c8abbdae..9685a0d1b5b 100644 --- a/docs/mfc/how-to-customize-the-application-button.md +++ b/docs/mfc/how-to-customize-the-application-button.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Customize the Application Button" title: "How to: Customize the Application Button" ms.date: "09/07/2019" helpviewer_keywords: ["application button [MFC], customizing"] -ms.assetid: ebb11180-ab20-43df-a234-801feca9eb38 --- # How to: Customize the Application Button +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you click the Application button, a menu of commands is displayed. Typically, the menu contains file-related commands such as **Open**, **Save**, **Print**, and **Exit**. ![MFC Ribbon Application Button.](../mfc/media/application_button.png "MFC Ribbon Application Button") diff --git a/docs/mfc/how-to-customize-the-quick-access-toolbar.md b/docs/mfc/how-to-customize-the-quick-access-toolbar.md index fd1992a269c..432b7813070 100644 --- a/docs/mfc/how-to-customize-the-quick-access-toolbar.md +++ b/docs/mfc/how-to-customize-the-quick-access-toolbar.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Customize the Quick Access Toolbar" title: "How to: Customize the Quick Access Toolbar" ms.date: "09/07/2019" helpviewer_keywords: ["quick access toolbar [MFC], customization"] -ms.assetid: 2554099b-0c89-4605-9249-31bf9cbcefe0 --- # How to: Customize the Quick Access Toolbar +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Quick Access Toolbar (QAT) is a customizable toolbar that contains a set of commands that are either displayed next to the Application button or under the category tabs. The following illustration shows a typical Quick Access Toolbar. ![MFC Ribbon Quick Access Toolbar.](../mfc/media/quick_access_toolbar.png "MFC Ribbon Quick Access Toolbar") diff --git a/docs/mfc/how-to-display-command-information-in-the-status-bar.md b/docs/mfc/how-to-display-command-information-in-the-status-bar.md index 88c1169ad69..04bda0d0edd 100644 --- a/docs/mfc/how-to-display-command-information-in-the-status-bar.md +++ b/docs/mfc/how-to-display-command-information-in-the-status-bar.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Display Command Information in the Statu title: "How to: Display Command Information in the Status Bar" ms.date: "11/04/2016" helpviewer_keywords: ["prompts [MFC]", "displaying command status [MFC]", "status bars [MFC], message area", "status bars [MFC], displaying command information"] -ms.assetid: de895cbe-61ee-46bf-9787-76b247527d6d --- # How to: Display Command Information in the Status Bar +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you run the Application Wizard to create the skeleton of your application, you can support a toolbar and a status bar. Just one option in the Application Wizard supports both. When a status bar is present, the application automatically provides helpful feedback as the user moves the pointer over items on the menus. The application automatically displays a prompt string in the status bar when the menu item is highlighted. For example, when the user moves the pointer over the **Cut** command on the **Edit** menu, the status bar might display "Cuts the selection and puts it on the Clipboard" in the message area of the status bar. The prompt helps the user understand the purpose of the menu item. This also works when the user clicks a toolbar button. You can add to this status-bar help by defining prompt strings for menu items that you add to the program. To do this, provide the prompt strings when you edit the properties of the menu item in the menu editor. The strings you define are stored in the application resource file; they have the same IDs as the commands they explain. diff --git a/docs/mfc/how-to-implement-tracking-in-your-code.md b/docs/mfc/how-to-implement-tracking-in-your-code.md index 7d46e6634e7..b007c680d57 100644 --- a/docs/mfc/how-to-implement-tracking-in-your-code.md +++ b/docs/mfc/how-to-implement-tracking-in-your-code.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Implement Tracking in Your Code" title: "How to: Implement Tracking in Your Code" ms.date: "11/04/2016" helpviewer_keywords: ["CRectTracker class [MFC], implementing trackers"] -ms.assetid: baaeca2c-5114-485f-bf58-8807db1bc973 --- # How to: Implement Tracking in Your Code +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To track an OLE item, you must handle certain events related to the item, such as clicking the item or updating the view of the document. In all cases, it is sufficient to declare a temporary [CRectTracker](reference/crecttracker-class.md) object and manipulate the item by means of this object. When a user selects an item or inserts an object with a menu command, you must initialize the tracker with the proper styles to represent the state of the OLE item. The following table outlines the conventions used by the OCLIENT sample. For more information on these styles, see `CRectTracker`. diff --git a/docs/mfc/how-to-load-a-ribbon-resource-from-an-mfc-application.md b/docs/mfc/how-to-load-a-ribbon-resource-from-an-mfc-application.md index f86fcec8eeb..10204cff33c 100644 --- a/docs/mfc/how-to-load-a-ribbon-resource-from-an-mfc-application.md +++ b/docs/mfc/how-to-load-a-ribbon-resource-from-an-mfc-application.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Load a Ribbon Resource from an MFC Appli title: "How to: Load a Ribbon Resource from an MFC Application" ms.date: "11/04/2016" helpviewer_keywords: ["ribbon resource [MFC], loading"] -ms.assetid: 1c76bb8f-6345-414a-9f3f-128815ceadc5 --- # How to: Load a Ribbon Resource from an MFC Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To use the ribbon resource in your application, modify the application to load the ribbon resource. ### To load a ribbon resource diff --git a/docs/mfc/how-to-make-a-type-safe-collection.md b/docs/mfc/how-to-make-a-type-safe-collection.md index 3b507e6d543..c1c4dac4865 100644 --- a/docs/mfc/how-to-make-a-type-safe-collection.md +++ b/docs/mfc/how-to-make-a-type-safe-collection.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Make a Type-Safe Collection" title: "How to: Make a Type-Safe Collection" ms.date: "11/04/2016" helpviewer_keywords: ["type-safe collections [MFC]", "serializing collection-class elements [MFC]", "collection classes [MFC], type safety", "SerializeElements function [MFC]", "collection classes [MFC], template-based", "serialization [MFC], collection classes", "collection classes [MFC], deriving from nontemplate"] -ms.assetid: 7230b2db-4283-4083-b098-eb231bf5b89e --- # How to: Make a Type-Safe Collection +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to make type-safe collections for your own data types. Topics include: - [Using template-based classes for type safety](#_core_using_template.2d.based_classes_for_type_safety) diff --git a/docs/mfc/how-to-update-user-interface-objects.md b/docs/mfc/how-to-update-user-interface-objects.md index 2b5fa11a2d1..0a9e902847d 100644 --- a/docs/mfc/how-to-update-user-interface-objects.md +++ b/docs/mfc/how-to-update-user-interface-objects.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Update User-Interface Objects" title: "How to: Update User-Interface Objects" ms.date: "11/04/2016" helpviewer_keywords: ["menus [MFC], updating as context changes", "user interface objects [MFC], updating", "user interface objects [MFC]", "update handlers [MFC]", "enabling UI elements [MFC]", "disabling menus [MFC]", "updating user-interface objects [MFC]", "disabling UI elements [MFC]", "commands [MFC], updating UI", "enabling menus [MFC]"] -ms.assetid: 82f09773-c978-427b-b321-05a6143b7369 --- # How to: Update User-Interface Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Typically, menu items and toolbar buttons have more than one state. For example, a menu item is grayed (dimmed) if it is unavailable in the present context. Menu items can also be checked or unchecked. A toolbar button can also be disabled if unavailable, or it can be checked. Who updates the state of these items as program conditions change Logically, if a menu item generates a command that is handled by, say, a document, it makes sense to have the document update the menu item. The document probably contains the information on which the update is based. diff --git a/docs/mfc/how-wininet-makes-it-easier-to-create-internet-client-applications.md b/docs/mfc/how-wininet-makes-it-easier-to-create-internet-client-applications.md index 4b8cec07283..ac1c59f2b1d 100644 --- a/docs/mfc/how-wininet-makes-it-easier-to-create-internet-client-applications.md +++ b/docs/mfc/how-wininet-makes-it-easier-to-create-internet-client-applications.md @@ -3,10 +3,12 @@ description: "Learn more about: How WinInet Makes It Easier to Create Internet C title: "How WinInet Makes It Easier to Create Internet Client Applications" ms.date: "11/04/2016" helpviewer_keywords: ["Windows Sockets [MFC], vs. WinInet", "WinInet classes [MFC], vs. WinSock", "WinInet classes [MFC], Internet client applications"] -ms.assetid: dc0f9f47-3184-4e7a-8074-2c63e0359885 --- # How WinInet Makes It Easier to Create Internet Client Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Win32 Internet Extensions, or WinInet, provide access to common Internet protocols, including gopher, FTP, and HTTP. Using WinInet, you can write Internet client applications at a higher level of programming, without having to deal with WinSock, TCP/IP, or the details of specific Internet protocols. WinInet provides a consistent set of functions for all three protocols, with a familiar Win32 API interface. This consistency minimizes code changes you need to make if the underlying protocol changes (for example, from FTP to HTTP). Visual C++ provides two ways for you to use WinInet. You can call the Win32 Internet functions directly (see the OLE documentation in the Windows SDK for more information) or you can use WinInet through the [MFC WinInet classes](mfc-classes-for-creating-internet-client-applications.md). diff --git a/docs/mfc/html-basics.md b/docs/mfc/html-basics.md index 88e3e02b5ad..52a2ba0cd3c 100644 --- a/docs/mfc/html-basics.md +++ b/docs/mfc/html-basics.md @@ -3,10 +3,12 @@ description: "Learn more about: HTML Basics" title: "HTML Basics" ms.date: "11/04/2016" helpviewer_keywords: ["HTML [MFC], about HTML"] -ms.assetid: aab8ea9f-12d4-4bdd-a585-ac3124081a2a --- # HTML Basics +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Most browsers have the capability of examining the HTML source of the pages you browse. When you view the source you will see a number of HTML (Hypertext markup language) tags, surrounded by angle brackets(<>), interspersed with text. The steps below use HTML tags to build a simple Web page. In these steps, you'll type plain text into a file in Notepad, make a few changes, save the file, and reload your page in the browser to see your changes. diff --git a/docs/mfc/html-help-context-sensitive-help-for-your-programs.md b/docs/mfc/html-help-context-sensitive-help-for-your-programs.md index ecadee9898f..592b23b3a8d 100644 --- a/docs/mfc/html-help-context-sensitive-help-for-your-programs.md +++ b/docs/mfc/html-help-context-sensitive-help-for-your-programs.md @@ -3,10 +3,12 @@ description: "Learn more about: HTML Help: Context-Sensitive Help for Your Progr title: "HTML Help: Context-Sensitive Help for Your Programs" ms.date: "11/04/2016" helpviewer_keywords: ["context-sensitive Help [MFC], HTML Help", "HTML Help [MFC], context-sensitive"] -ms.assetid: f2eabbbb-0796-43f3-a483-5f7cf00f2e7c --- # HTML Help: Context-Sensitive Help for Your Programs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!IMPORTANT] > HTML Help is not supported in this version of MFC. diff --git a/docs/mfc/idle-loop-processing.md b/docs/mfc/idle-loop-processing.md index 33d16f0956d..abf173d9f42 100644 --- a/docs/mfc/idle-loop-processing.md +++ b/docs/mfc/idle-loop-processing.md @@ -3,10 +3,12 @@ description: "Learn more about: Idle Loop Processing" title: "Idle Loop Processing" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, background processing", "PeekMessage method [MFC], elsewhere than message loop", "PeekMessage method [MFC]", "MFC, messages", "messages [MFC], loops", "OnIdle method [MFC]", "processing [MFC], background", "idle loop processing [MFC]", "idle processing [MFC]", "threading [MFC], alternatives to multithreading", "processing, during idle loop", "processing [MFC]", "background processing [MFC]"] -ms.assetid: 5c7c46c1-6107-4304-895f-480983bb1e44 --- # Idle Loop Processing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Many applications perform lengthy processing "in the background." Sometimes performance considerations dictate using multithreading for such work. Threads involve extra development overhead, so they are not recommended for simple tasks like the idle-time work that MFC does in the [OnIdle](reference/cwinthread-class.md#onidle) function. This article focuses on idle processing. For more information about multithreading, see [Multithreading Topics](../parallel/multithreading-support-for-older-code-visual-cpp.md). Some kinds of background processing are appropriately done during intervals that the user is not otherwise interacting with the application. In an application developed for the Microsoft Windows operating system, an application can perform idle-time processing by splitting a lengthy process into many small fragments. After processing each fragment, the application yields execution control to Windows using a [PeekMessage](/windows/win32/api/winuser/nf-winuser-peekmessagew) loop. @@ -32,7 +34,7 @@ Another method for performing idle processing in an application involves embeddi [!code-cpp[NVC_MFCDocView#8](codesnippet/cpp/idle-loop-processing_1.cpp)] -This code, embedded in a function, loops as long as there is idle processing to do. Within that loop, a nested loop repeatedly calls `PeekMessage`. As long as that call returns a nonzero value, the loop calls `CWinThread::PumpMessage` to perform normal message translation and dispatching. Although `PumpMessage` is undocumented, you can examine its source code in the ThrdCore.Cpp file in the \atlmfc\src\mfc directory of your Visual C++ installation. +This code, embedded in a function, loops as long as there is idle processing to do. Within that loop, a nested loop repeatedly calls `PeekMessage`. As long as that call returns a nonzero value, the loop calls `CWinThread::PumpMessage` to perform normal message translation and dispatching. Although `PumpMessage` is undocumented, you can examine its source code in the ThrdCore.Cpp file in the \atlmfc\src\mfc directory of your Visual Studio installation. Once the inner loop ends, the outer loop performs idle processing with one or more calls to `OnIdle`. The first call is for MFC's purposes. You can make additional calls to `OnIdle` to do your own background work. diff --git a/docs/mfc/image-information-in-image-lists.md b/docs/mfc/image-information-in-image-lists.md index 85fb338f183..11ca2a4de11 100644 --- a/docs/mfc/image-information-in-image-lists.md +++ b/docs/mfc/image-information-in-image-lists.md @@ -3,10 +3,12 @@ description: "Learn more about: Image Information in Image Lists" title: "Image Information in Image Lists" ms.date: "11/04/2016" helpviewer_keywords: ["CImageList class [MFC], image information in", "image lists [MFC], image information in"] -ms.assetid: 73c41543-fa91-405d-b15b-0feffa6a72c1 --- # Image Information in Image Lists +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [CImageList](reference/cimagelist-class.md) includes a number of functions that retrieve information from an image list. The [GetImageInfo](reference/cimagelist-class.md#getimageinfo) member function fills an `IMAGEINFO` structure with information about a single image, including the handles of the image and mask bitmaps, the number of color planes and bits per pixel, and the bounding rectangle of the image within the image bitmap. You can use this information to directly manipulate the bitmaps for the image. The [GetImageCount](reference/cimagelist-class.md#getimagecount) member function retrieves the number of images in an image list. diff --git a/docs/mfc/image-overlays-in-image-lists.md b/docs/mfc/image-overlays-in-image-lists.md index 808d498a425..1822b3e0149 100644 --- a/docs/mfc/image-overlays-in-image-lists.md +++ b/docs/mfc/image-overlays-in-image-lists.md @@ -3,10 +3,12 @@ description: "Learn more about: Image Overlays in Image Lists" title: "Image Overlays in Image Lists" ms.date: "11/04/2016" helpviewer_keywords: ["overlays [MFC]", "image lists [MFC], image overlays in", "CImageList class [MFC], image overlays in"] -ms.assetid: aaf4e1c4-cd12-42c8-9af4-1bb458889b4e --- # Image Overlays in Image Lists +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Every image list ([CImageList](reference/cimagelist-class.md)) includes a list of images to use as overlay masks. An "overlay mask" is an image drawn transparently over another image. Any image can be used as an overlay mask. You can specify up to four overlay masks per image list. You add the index of an image to the list of overlay masks by using the [SetOverlayImage](reference/cimagelist-class.md#setoverlayimage) member function, the index of an image, and the index of an overlay mask. Note that the indices for the overlay masks are one-based rather than zero-based. diff --git a/docs/mfc/implementing-working-areas-in-list-controls.md b/docs/mfc/implementing-working-areas-in-list-controls.md index 9649cfcd2b5..5379ff13fea 100644 --- a/docs/mfc/implementing-working-areas-in-list-controls.md +++ b/docs/mfc/implementing-working-areas-in-list-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Implementing Working Areas in List Controls" title: "Implementing Working Areas in List Controls" ms.date: "11/04/2016" helpviewer_keywords: ["list controls [MFC], working areas", "working areas in list control [MFC]"] -ms.assetid: fbbb356b-3359-4348-8603-f1cb114cadde +ms.topic: concept-article --- # Implementing Working Areas in List Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By default, a list control arranges all items in a standard grid fashion. However, another method is supported, working areas, that arranges the list items into rectangular groups. For an image of a list control that implements working areas, see Using List-View Controls in the Windows SDK. > [!NOTE] diff --git a/docs/mfc/initializing-and-cleaning-up-documents-and-views.md b/docs/mfc/initializing-and-cleaning-up-documents-and-views.md index 4462b237bf1..a5475344903 100644 --- a/docs/mfc/initializing-and-cleaning-up-documents-and-views.md +++ b/docs/mfc/initializing-and-cleaning-up-documents-and-views.md @@ -3,10 +3,13 @@ description: "Learn more about: Initializing and Cleaning Up Documents and Views title: "Initializing and Cleaning Up Documents and Views" ms.date: "11/04/2016" helpviewer_keywords: ["initializing documents [MFC]", "views [MFC], cleaning up", "documents [MFC], initializing", "documents [MFC], cleaning up", "views [MFC], initializing", "initializing objects [MFC], document objects", "document objects [MFC], life cycle of", "initializing views [MFC]"] -ms.assetid: 95d6f09b-a047-4079-856a-ae7d0548e9d2 +ms.topic: how-to --- # Initializing and Cleaning Up Documents and Views +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use the following guidelines for initializing and cleaning up after your documents and views: - The MFC framework initializes documents and views; you initialize any data you add to them. diff --git a/docs/mfc/initializing-documents-and-views.md b/docs/mfc/initializing-documents-and-views.md index 326411c8763..9df47617166 100644 --- a/docs/mfc/initializing-documents-and-views.md +++ b/docs/mfc/initializing-documents-and-views.md @@ -3,10 +3,13 @@ description: "Learn more about: Initializing Documents and Views" title: "Initializing Documents and Views" ms.date: "11/04/2016" helpviewer_keywords: ["initializing documents [MFC]", "documents [MFC], initializing", "views [MFC], initializing", "initializing objects [MFC], document objects", "initializing views [MFC]"] -ms.assetid: 33cb8643-8a16-478c-bc26-eccc734e3661 +ms.topic: concept-article --- # Initializing Documents and Views +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Documents are created in two different ways, so your document class must support both ways. First, the user can create a new, empty document with the File New command. In that case, initialize the document in your override of the [OnNewDocument](reference/cdocument-class.md#onnewdocument) member function of class [CDocument](reference/cdocument-class.md). Second, the user can use the Open command on the File menu to create a new document whose contents are read from a file. In that case, initialize the document in your override of the [OnOpenDocument](reference/cdocument-class.md#onopendocument) member function of class `CDocument`. If both initializations are the same, you can call a common member function from both overrides, or `OnOpenDocument` can call `OnNewDocument` to initialize a clean document and then finish the open operation. Views are created after their documents are created. The best time to initialize a view is after the framework has finished creating the document, frame window, and view. You can initialize your view by overriding the [OnInitialUpdate](reference/cview-class.md#oninitialupdate) member function of [CView](reference/cview-class.md). If you need to reinitialize or adjust anything each time the document changes, you can override [OnUpdate](reference/cview-class.md#onupdate). diff --git a/docs/mfc/initializing-the-dialog-box.md b/docs/mfc/initializing-the-dialog-box.md index f3fa2fa7af0..a023246ae63 100644 --- a/docs/mfc/initializing-the-dialog-box.md +++ b/docs/mfc/initializing-the-dialog-box.md @@ -3,10 +3,13 @@ description: "Learn more about: Initializing the Dialog Box" title: "Initializing the Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["initializing dialog boxes [MFC]", "OnInitDialog method [MFC]", "modal dialog boxes [MFC], initializing", "modeless dialog boxes [MFC], initializing", "MFC dialog boxes [MFC], initializing"] -ms.assetid: 968142f5-19f9-4b34-a1d4-8e6412d4379b +ms.topic: concept-article --- # Initializing the Dialog Box +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + After the dialog box and all of its controls are created but just before the dialog box (of either type) appears on the screen, the dialog object's [OnInitDialog](reference/cdialog-class.md#oninitdialog) member function is called. For a modal dialog box, this occurs during the `DoModal` call. For a modeless dialog box, `OnInitDialog` is called when `Create` is called. You typically override `OnInitDialog` to initialize the dialog box's controls, such as setting the initial text of an edit box. You must call the `OnInitDialog` member function of the base class, `CDialog`, from your `OnInitDialog` override. If you want to set your dialog box's background color (and that of all other dialog boxes in your application), see [Setting the Dialog Box's Background Color](setting-the-dialog-boxs-background-color.md). diff --git a/docs/mfc/initializing-the-parts-of-a-cstatusbarctrl-object.md b/docs/mfc/initializing-the-parts-of-a-cstatusbarctrl-object.md index c47acf19ddd..fb6a19352f3 100644 --- a/docs/mfc/initializing-the-parts-of-a-cstatusbarctrl-object.md +++ b/docs/mfc/initializing-the-parts-of-a-cstatusbarctrl-object.md @@ -3,10 +3,13 @@ description: "Learn more about: Initializing the Parts of a CStatusBarCtrl Objec title: "Initializing the Parts of a CStatusBarCtrl Object" ms.date: "11/04/2016" helpviewer_keywords: ["CStatusBarCtrl class [MFC], simple mode", "status bars [MFC], declaring parts of", "simple status bars [MFC]", "status bars [MFC], icons", "status bars [MFC], simple mode", "icons, using in status bars", "CStatusBarCtrl class [MFC], declaring parts of"] -ms.assetid: 60e8f285-d2d8-424a-a6ea-2fc548370303 +ms.topic: concept-article --- # Initializing the Parts of a CStatusBarCtrl Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By default, a status bar displays status information using separate panes. These panes (also referred to as parts) can contain either a text string, an icon, or both. Use [SetParts](reference/cstatusbarctrl-class.md#setparts) to define how many parts, and the length, the status bar will have. After you have created the parts of the status bar, make calls to [SetText](reference/cstatusbarctrl-class.md#settext) and [SetIcon](reference/cstatusbarctrl-class.md#seticon) to set the text or icon for a specific part of the status bar. Once the part has been successfully set, the control is automatically redrawn. diff --git a/docs/mfc/initinstance-member-function.md b/docs/mfc/initinstance-member-function.md index adea53e37d0..a9b498541b8 100644 --- a/docs/mfc/initinstance-member-function.md +++ b/docs/mfc/initinstance-member-function.md @@ -4,10 +4,12 @@ title: "InitInstance Member Function" ms.date: "11/04/2016" f1_keywords: ["InitInstance"] helpviewer_keywords: ["InitInstance method [MFC]", "applications [MFC], initializing", "MFC, initializing", "initializing MFC applications"] -ms.assetid: 4ef09267-ff7f-4c39-91a0-57454a264f83 --- # InitInstance Member Function +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Windows operating system allows you to run more than one copy, or "instance," of the same application. `WinMain` calls [InitInstance](reference/cwinapp-class.md#initinstance) every time a new instance of the application starts. The standard `InitInstance` implementation created by the MFC Application Wizard performs the following tasks: diff --git a/docs/mfc/inserting-a-control-into-a-control-container-application.md b/docs/mfc/inserting-a-control-into-a-control-container-application.md index dd5b98f83e8..d53eaffac01 100644 --- a/docs/mfc/inserting-a-control-into-a-control-container-application.md +++ b/docs/mfc/inserting-a-control-into-a-control-container-application.md @@ -3,10 +3,12 @@ description: "Learn more about: ActiveX Control Containers: Inserting a Control title: "ActiveX Control Containers: Inserting a Control into a Control Container Application" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX control containers [MFC], inserting controls", "ActiveX controls [MFC], adding to projects"] -ms.assetid: bbb617ff-872f-43d8-b4d6-c49adb16b148 --- # ActiveX Control Containers: Inserting a Control into a Control Container Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Before you can access an ActiveX control from an ActiveX control container application, you must add the ActiveX control to the container application using the [Insert ActiveX Control](../windows/adding-editing-or-deleting-controls.md) dialog box. To add an ActiveX control to the ActiveX control container project, see [Viewing and Adding ActiveX Controls to a Dialog Box](../windows/adding-editing-or-deleting-controls.md). diff --git a/docs/mfc/inserting-a-form-into-a-project.md b/docs/mfc/inserting-a-form-into-a-project.md index 51e916c60c4..657302adc43 100644 --- a/docs/mfc/inserting-a-form-into-a-project.md +++ b/docs/mfc/inserting-a-form-into-a-project.md @@ -3,10 +3,13 @@ description: "Learn more about: Inserting a Form into a Project" title: "Inserting a Form into a Project" ms.date: "11/04/2016" helpviewer_keywords: ["inserting forms [MFC]", "Insert New dialog box [MFC]", "forms, adding to projects"] -ms.assetid: f3bd2998-3ce2-496d-ac5c-57ca70eec7cb +ms.topic: how-to --- # Inserting a Form into a Project +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Forms provide a convenient container for controls. You can easily insert an MFC-based form into your application as long as the application supports the MFC libraries. ### To insert a form into your project @@ -21,7 +24,7 @@ Forms provide a convenient container for controls. You can easily insert an MFC- 1. Using the MFC Class Wizard, make the new class derive from [CFormView](reference/cformview-class.md). -Visual C++ adds the form to your application, opening it inside the Dialog editor so that you can begin adding controls and working on its overall design. +Visual Studio adds the form to your application, opening it inside the Dialog editor so that you can begin adding controls and working on its overall design. You may want to perform the following additional steps (not applicable for dialog-based applications): diff --git a/docs/mfc/interface-elements.md b/docs/mfc/interface-elements.md index 28c6b293ffe..04cd91cdafe 100644 --- a/docs/mfc/interface-elements.md +++ b/docs/mfc/interface-elements.md @@ -3,10 +3,12 @@ description: "Learn more about: Interface Elements" title: "Interface Elements" ms.date: "11/19/2018" helpviewer_keywords: ["architecture [MFC], MFC Feature Pack", "MFC Feature Pack, architecture"] -ms.assetid: eead6827-9602-40a3-8038-8986e8207385 --- # Interface Elements +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This document describes interface elements that were introduced in Visual Studio 2008 SP1, and also describes differences with the earlier version of the library. The following illustration shows an application that was built by using the new interface elements. diff --git a/docs/mfc/internet-and-networking-classes.md b/docs/mfc/internet-and-networking-classes.md index 4832f616532..a7f0d4040c6 100644 --- a/docs/mfc/internet-and-networking-classes.md +++ b/docs/mfc/internet-and-networking-classes.md @@ -4,10 +4,12 @@ title: "Internet and Networking Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.net"] helpviewer_keywords: ["Internet classes [MFC]", "networking classes [MFC]"] -ms.assetid: 1acf793d-ebf2-4fac-97be-703d62e3897e --- # Internet and Networking Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes allow you to exchange information with another computer using a Windows Socket or Win32 Internet (WinInet). There are also a set of classes for manipulating Windows Sockets. The following categories of classes support connectivity. diff --git a/docs/mfc/internet-information-by-task.md b/docs/mfc/internet-information-by-task.md index 7493ce32c50..246ca26a540 100644 --- a/docs/mfc/internet-information-by-task.md +++ b/docs/mfc/internet-information-by-task.md @@ -3,10 +3,12 @@ description: "Learn more about: Internet Information by Task" title: "Internet Information by Task" ms.date: "09/12/2018" helpviewer_keywords: ["MFC, Internet applications"] -ms.assetid: da078bf5-53c3-4167-b1ef-509b5a544ad9 --- # Internet Information by Task +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The tasks listed in this topic are sorted based on the task you want to accomplish. >[!IMPORTANT] diff --git a/docs/mfc/internet-information-by-topic.md b/docs/mfc/internet-information-by-topic.md index c23fba8b600..a8b769f525f 100644 --- a/docs/mfc/internet-information-by-topic.md +++ b/docs/mfc/internet-information-by-topic.md @@ -3,10 +3,12 @@ description: "Learn more about: Internet Information by Topic" title: "Internet Information by Topic" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, Internet applications"] -ms.assetid: 93a8b6c9-d274-492a-90b3-cf43a77edb1d --- # Internet Information by Topic +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For information on programming with a specific Internet technology, see: ## WinInet diff --git a/docs/mfc/internet-related-mfc-classes.md b/docs/mfc/internet-related-mfc-classes.md index 25f83f8c5cc..9dbcbb7a9ca 100644 --- a/docs/mfc/internet-related-mfc-classes.md +++ b/docs/mfc/internet-related-mfc-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Internet-Related MFC Classes" title: "Internet-Related MFC Classes" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, Internet classes"] -ms.assetid: e50c6b39-4b65-4b8a-8101-8934d0780723 --- # Internet-Related MFC Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For information about Internet-related classes and functions, see: ## Global functions diff --git a/docs/mfc/internet-security-cpp.md b/docs/mfc/internet-security-cpp.md index c66886c7db5..8aed9355989 100644 --- a/docs/mfc/internet-security-cpp.md +++ b/docs/mfc/internet-security-cpp.md @@ -3,10 +3,12 @@ description: "Learn more about: Internet Security (C++)" title: "Internet Security (C++)" ms.date: "11/04/2016" helpviewer_keywords: ["code signing [MFC], Internet security", "sandboxing [MFC]", "digital signatures [MFC], Internet security", "code signing [MFC]", "Web application security [MFC]", "code access security [MFC], Internet security considerations", "security [MFC]", "security [MFC], Internet", "Internet applications [MFC], security", "Web application security [MFC], Internet security approaches"] -ms.assetid: bf0da697-81bc-41f0-83fa-d7f82ed83df8 --- # Internet Security (C++) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Code safety is a major issue for developers and for users of Internet applications. There are risks: malicious code, code that has been tampered with, and code from unknown sites or authors. There are two basic approaches to security when developing for the Internet. The first is called "sandboxing." In this approach, an application is restricted to a particular set of APIs, and excluded from potentially dangerous ones such as file I/O where a program could destroy data on a user's computer. The second is implemented using digital signatures. This approach is referred to as "shrinkwrap" for the Internet. Code is verified and signed using private key/public key technology. Before the code is run, its digital signature is verified to ensure that the code is from a known authenticated source, and that the code has not been altered since it has been signed. diff --git a/docs/mfc/interpreting-user-input-through-a-view.md b/docs/mfc/interpreting-user-input-through-a-view.md index 4a71432b222..190fcef5aef 100644 --- a/docs/mfc/interpreting-user-input-through-a-view.md +++ b/docs/mfc/interpreting-user-input-through-a-view.md @@ -3,10 +3,13 @@ description: "Learn more about: Interpreting User Input Through a View" title: "Interpreting User Input Through a View" ms.date: "11/04/2016" helpviewer_keywords: ["interpreting user input through views [MFC]", "views [MFC], user interface and input", "input [MFC], view class [MFC]", "CView class [MFC], interpreting user input", "user input [MFC], interpreting through view class [MFC]"] -ms.assetid: f0302a70-661f-4781-8fe7-78f082bef2a5 +ms.topic: concept-article --- # Interpreting User Input Through a View +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Other member functions of the view handle and interpret all user input. You will usually define message-handler member functions in your view class to process: - Windows [messages](messages.md) generated by mouse and keyboard actions. diff --git a/docs/mfc/isolation-of-the-mfc-common-controls-library.md b/docs/mfc/isolation-of-the-mfc-common-controls-library.md index 9f038e52807..7fac241cdb5 100644 --- a/docs/mfc/isolation-of-the-mfc-common-controls-library.md +++ b/docs/mfc/isolation-of-the-mfc-common-controls-library.md @@ -3,10 +3,12 @@ description: "Learn more about: Isolation of the MFC Common Controls Library" title: "Isolation of the MFC Common Controls Library" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, Common Controls library"] -ms.assetid: 7471e6f0-49b0-47f7-86e7-8d6bc3541694 --- # Isolation of the MFC Common Controls Library +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Common Controls library is now isolated within MFC, allowing different modules (such as user DLLs) to use different versions of the Common Controls library by specifying the version in their manifests. An MFC application (or user code called by MFC) makes calls to Common Controls library APIs through wrapper functions named `Afx`*FunctionName*, where *FunctionName* is the name of a Common Controls API. Those wrapper functions are defined in afxcomctl32.h and afxcomctl32.inl. diff --git a/docs/mfc/keyboard-and-mouse-customization.md b/docs/mfc/keyboard-and-mouse-customization.md index 9e1e28242fb..749fbb102eb 100644 --- a/docs/mfc/keyboard-and-mouse-customization.md +++ b/docs/mfc/keyboard-and-mouse-customization.md @@ -3,10 +3,12 @@ description: "Learn more about: Keyboard and Mouse Customization" title: "Keyboard and Mouse Customization" ms.date: "11/19/2018" helpviewer_keywords: ["customizations [MFC], keyboard and mouse (MFC Extensions)", "keyboard and mouse customizations (MFC Extensions)"] -ms.assetid: 1f789f1b-5f2e-4b11-b974-e3e2a2e49d82 --- # Keyboard and Mouse Customization +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC allows the user of your application to customize how it handles keyboard and mouse input. The user can customize keyboard input by assigning keyboard shortcuts to commands. The user can also customize the mouse input by selecting the command that should be executed when the user double-clicks inside specific windows of the application. This topic explains how to customize the input for your application. In the **Customization** dialog box, the user can change the custom controls for the mouse and the keyboard. To display this dialog box, the user points to **Customize** on the **View** menu and then clicks **Toolbars and Docking**. In the dialog box, the user clicks either the **Keyboard** tab or the **Mouse** tab. diff --git a/docs/mfc/life-cycle-of-a-dialog-box.md b/docs/mfc/life-cycle-of-a-dialog-box.md index 1375df3e61d..38d347f2d30 100644 --- a/docs/mfc/life-cycle-of-a-dialog-box.md +++ b/docs/mfc/life-cycle-of-a-dialog-box.md @@ -3,10 +3,13 @@ description: "Learn more about: Working with Dialog Boxes in MFC" title: "Working with Dialog Boxes in MFC" ms.date: "09/27/2019" helpviewer_keywords: ["dialog boxes [MFC], life cycle", "modal dialog boxes [MFC], life cycle", "modeless dialog boxes [MFC], life cycle", "MFC dialog boxes [MFC], life cycle", "life cycle of dialog boxes [MFC]"] -ms.assetid: e16fd78e-238d-4f31-8c9d-8564f3953bd9 +ms.topic: concept-article --- # Working with Dialog Boxes in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + During the life cycle of a dialog box, the user invokes the dialog box, typically inside a command handler that creates and initializes the dialog object, the user interacts with the dialog box, then dialog box closes. For modal dialog boxes, your handler gathers any data the user entered once the dialog box closes. Since the dialog object exists after its dialog window has closed, you can simply use the member variables of your dialog class to extract the data. diff --git a/docs/mfc/list-control-and-list-view.md b/docs/mfc/list-control-and-list-view.md index 80c769cd219..20e0d4b2792 100644 --- a/docs/mfc/list-control-and-list-view.md +++ b/docs/mfc/list-control-and-list-view.md @@ -3,10 +3,12 @@ description: "Learn more about: List Control and List View" title: "List Control and List View" ms.date: "11/04/2016" helpviewer_keywords: ["CListView class [MFC], and CListCtrl", "views [MFC], list and list control", "CListCtrl class [MFC], and CListView", "list views [MFC]", "list controls [MFC], List view"] -ms.assetid: 7aee1c48-b158-4399-be0b-be366993665e --- # List Control and List View +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For convenience, MFC encapsulates the list control in two ways. You can use list controls: - Directly, by embedding a [CListCtrl](reference/clistctrl-class.md) object in a dialog class. diff --git a/docs/mfc/list-items-and-image-lists.md b/docs/mfc/list-items-and-image-lists.md index 27c772c67c3..9c6bf25f89a 100644 --- a/docs/mfc/list-items-and-image-lists.md +++ b/docs/mfc/list-items-and-image-lists.md @@ -3,10 +3,12 @@ description: "Learn more about: List Items and Image Lists" title: "List Items and Image Lists" ms.date: "11/04/2016" helpviewer_keywords: ["CImageList class [MFC], and list items", "image lists [MFC], list items", "CListCtrl class [MFC], image lists", "list items [MFC], image lists"] -ms.assetid: 317d095f-f978-47da-acb6-7bfe7dd3bc69 --- # List Items and Image Lists +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An "item" in a list control ([CListCtrl](reference/clistctrl-class.md)) consists of an icon, a label, and possibly other information (in "subitems"). The icons for list control items are contained in image lists. One image list contains full-sized icons used in icon view. A second, optional, image list contains smaller versions of the same icons for use in other views of the control. A third optional list contains "state" images, such as check boxes, for display in front of the small icons in certain views. A fourth optional list contains images that are displayed in individual header items of the list control. diff --git a/docs/mfc/making-and-using-controls.md b/docs/mfc/making-and-using-controls.md index 92fd5c28a69..e09293f71d9 100644 --- a/docs/mfc/making-and-using-controls.md +++ b/docs/mfc/making-and-using-controls.md @@ -3,11 +3,14 @@ description: "Learn more about: Making and Using Controls" title: "Making and Using Controls" ms.date: "11/04/2016" helpviewer_keywords: ["controls [MFC], creating for dialog boxes", "Windows common controls [MFC], about common controls", "common controls [MFC], about common controls"] -ms.assetid: a252acad-3cc0-440e-bbc6-43eaaf8cb7bb +ms.topic: concept-article --- # Making and Using Controls -You make most controls for dialog boxes in the Visual C++ [dialog editor](../windows/dialog-editor.md). But you can also create controls in any dialog box or window. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +You make most controls for dialog boxes in the Visual Studio [dialog editor](../windows/dialog-editor.md). But you can also create controls in any dialog box or window. ## What do you want to know more about diff --git a/docs/mfc/making-owner-drawn-header-controls.md b/docs/mfc/making-owner-drawn-header-controls.md index 121655e7e4e..e57f2484f92 100644 --- a/docs/mfc/making-owner-drawn-header-controls.md +++ b/docs/mfc/making-owner-drawn-header-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Making Owner-Drawn Header Controls" title: "Making Owner-Drawn Header Controls" ms.date: "11/04/2016" helpviewer_keywords: ["header controls [MFC], owner-drawn", "drawing [MFC], header controls", "CHeaderCtrl class [MFC], making owner-drawn", "controls [MFC], header", "owner-drawn header controls [MFC]"] -ms.assetid: 455c113b-e8d0-400c-8690-dbb92cba0d05 +ms.topic: concept-article --- # Making Owner-Drawn Header Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can define individual items of a header control ([CHeaderCtrl](reference/cheaderctrl-class.md)) to be owner-drawn items. For more information, see [Owner-Drawn Header Controls](/windows/win32/Controls/header-controls) in the Windows SDK. ## See also diff --git a/docs/mfc/making-owner-drawn-tabs.md b/docs/mfc/making-owner-drawn-tabs.md index f27d45d88ba..31d9bdfbc57 100644 --- a/docs/mfc/making-owner-drawn-tabs.md +++ b/docs/mfc/making-owner-drawn-tabs.md @@ -3,10 +3,13 @@ description: "Learn more about: Making Owner-Drawn Tabs" title: "Making Owner-Drawn Tabs" ms.date: "11/04/2016" helpviewer_keywords: ["owner-drawn tabs [MFC]", "tabs [MFC], owner-drawn", "CTabCtrl class [MFC], owner-drawn tabs", "drawing [MFC], tabs"] -ms.assetid: 11af2926-41d7-47e3-9eec-c595283f6371 +ms.topic: concept-article --- # Making Owner-Drawn Tabs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can define individual items of a tab control ([CTabCtrl](reference/ctabctrl-class.md)) to be owner-drawn items. For more information, see [Owner-Drawn Tabs](/windows/win32/Controls/tab-controls) in the Windows SDK. ## See also diff --git a/docs/mfc/managing-data-with-document-data-variables.md b/docs/mfc/managing-data-with-document-data-variables.md index 1d6951c2b7a..0375973e8be 100644 --- a/docs/mfc/managing-data-with-document-data-variables.md +++ b/docs/mfc/managing-data-with-document-data-variables.md @@ -3,10 +3,13 @@ description: "Learn more about: Managing Data with Document Data Variables" title: "Managing Data with Document Data Variables" ms.date: "11/04/2016" helpviewer_keywords: ["documents [MFC], data storage", "friend classes [MFC]", "classes [MFC], friend", "data [MFC]", "data [MFC], documents", "collection classes [MFC], used by document object", "document data [MFC]", "member variables [MFC], document class [MFC]"] -ms.assetid: e70b87f4-8c30-49e5-8986-521c2ff91704 +ms.topic: concept-article --- # Managing Data with Document Data Variables +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implement your document's data as member variables of your document class. For example, the Scribble program declares a data member of type `CObList` — a linked list that stores pointers to `CObject` objects. This list is used to store arrays of points that make up a freehand line drawing. How you implement your document's member data depends on the nature of your application. To help you out, MFC supplies a group of "collection classes" — arrays, lists, and maps (dictionaries), including collections based on C++ templates — along with classes that encapsulate a variety of common data types such as `CString`, `CRect`, `CPoint`, `CSize`, and `CTime`. For more information about these classes, see the [Class Library Overview](class-library-overview.md) in the *MFC Reference*. diff --git a/docs/mfc/managing-mdi-child-windows.md b/docs/mfc/managing-mdi-child-windows.md index 378345309ed..f0426cace5d 100644 --- a/docs/mfc/managing-mdi-child-windows.md +++ b/docs/mfc/managing-mdi-child-windows.md @@ -4,10 +4,13 @@ title: "Managing MDI Child Windows" ms.date: "11/19/2018" f1_keywords: ["MDICLIENT"] helpviewer_keywords: ["MDI [MFC], child windows", "child windows [MFC], and MDICLIENT window", "MDICLIENT window [MFC]", "windows [MFC], MDI", "frame windows [MFC], MDI child windows", "child windows [MFC]", "MDI [MFC], frame windows"] -ms.assetid: 1828d96e-a561-48ae-a661-ba9701de6bee +ms.topic: concept-article --- # Managing MDI Child Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MDI main frame windows (one per application) contain a special child window called the MDICLIENT window. The MDICLIENT window manages the client area of the main frame window, and itself has child windows: the document windows, derived from `CMDIChildWnd`. Because the document windows are frame windows themselves (MDI child windows), they can also have their own children. In all of these cases, the parent window manages its child windows and forwards some commands to them. In an MDI frame window, the frame window manages the MDICLIENT window, repositioning it in conjunction with control bars. The MDICLIENT window, in turn, manages all MDI child frame windows. The following figure shows the relationship between an MDI frame window, its MDICLIENT window, and its child document frame windows. diff --git a/docs/mfc/managing-menus-control-bars-and-accelerators.md b/docs/mfc/managing-menus-control-bars-and-accelerators.md index bdd164b2c96..4830ec1e010 100644 --- a/docs/mfc/managing-menus-control-bars-and-accelerators.md +++ b/docs/mfc/managing-menus-control-bars-and-accelerators.md @@ -3,10 +3,13 @@ description: "Learn more about: Managing Menus, Control Bars, and Accelerators" title: "Managing Menus, Control Bars, and Accelerators" ms.date: "11/04/2016" helpviewer_keywords: ["MDI [MFC], frame windows", "control bars [MFC], updating in frame windows", "menus [MFC], updating as context changes", "user interface objects [MFC], updating", "accelerator tables [MFC]", "sharing menus [MFC]", "updating user-interface objects [MFC]", "frame windows [MFC], updating", "status bars [MFC], updating"] -ms.assetid: 97ca1997-06df-4373-b023-4f7ecd81047b +ms.topic: concept-article --- # Managing Menus, Control Bars, and Accelerators +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The frame window manages updating user-interface objects, including menus, toolbar buttons, the status bar, and accelerators. It also manages sharing the menu bar in MDI applications. ## Managing Menus diff --git a/docs/mfc/managing-the-current-view.md b/docs/mfc/managing-the-current-view.md index 9a14f7cccde..59c278a4d13 100644 --- a/docs/mfc/managing-the-current-view.md +++ b/docs/mfc/managing-the-current-view.md @@ -3,10 +3,13 @@ description: "Learn more about: Managing the Current View" title: "Managing the Current View" ms.date: "11/04/2016" helpviewer_keywords: ["views [MFC], and OnActivateView method [MFC]", "views [MFC], deactivating", "views [MFC], activating", "frame windows [MFC], current view", "OnActivateView method [MFC]", "views [MFC], current", "deactivating views [MFC]", "current view in frame window [MFC]"] -ms.assetid: 0a1cc22d-d646-4536-9ad2-3cb6d7092e4a +ms.topic: concept-article --- # Managing the Current View +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As part of the default implementation of frame windows, a frame window keeps track of a currently active view. If the frame window contains more than one view, as for example in a splitter window, the current view is the most recent view in use. The active view is independent of the active window in Windows or the current input focus. When the active view changes, the framework notifies the current view by calling its [OnActivateView](reference/cview-class.md#onactivateview) member function. You can tell whether the view is being activated or deactivated by examining `OnActivateView`'s *bActivate* parameter. By default, `OnActivateView` sets the focus to the current view on activation. You can override `OnActivateView` to perform any special processing when the view is deactivated or reactivated. For example, you might want to provide special visual cues to distinguish the active view from other, inactive views. diff --git a/docs/mfc/managing-the-state-data-of-mfc-modules.md b/docs/mfc/managing-the-state-data-of-mfc-modules.md index f40ff4f6b76..31871e32640 100644 --- a/docs/mfc/managing-the-state-data-of-mfc-modules.md +++ b/docs/mfc/managing-the-state-data-of-mfc-modules.md @@ -3,10 +3,13 @@ description: "Learn more about: Managing the State Data of MFC Modules" title: "Managing the State Data of MFC Modules" ms.date: "11/19/2018" helpviewer_keywords: ["global state [MFC]", "data management [MFC], MFC modules", "window procedure entry points [MFC]", "exported interfaces and global state [MFC]", "module states [MFC], saving and restoring", "data management [MFC]", "MFC, managing state data", "multiple modules [MFC]", "module state restored [MFC]"] -ms.assetid: 81889c11-0101-4a66-ab3c-f81cf199e1bb +ms.topic: concept-article --- # Managing the State Data of MFC Modules +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses the state data of MFC modules and how this state is updated when the flow of execution (the path code takes through an application when executing) enters and leaves a module. Switching module states with the AFX_MANAGE_STATE and METHOD_PROLOGUE macros is also discussed. > [!NOTE] diff --git a/docs/mfc/manipulating-image-lists.md b/docs/mfc/manipulating-image-lists.md index 7b782d16ed5..2f2e7a0d6a3 100644 --- a/docs/mfc/manipulating-image-lists.md +++ b/docs/mfc/manipulating-image-lists.md @@ -3,10 +3,13 @@ description: "Learn more about: Manipulating Image Lists" title: "Manipulating Image Lists" ms.date: "11/04/2016" helpviewer_keywords: ["image lists [MFC], manipulating", "lists [MFC], image", "CImageList class [MFC], manipulating"] -ms.assetid: 043418f8-077e-4dce-b8bb-2b7b0d7b5156 +ms.topic: concept-article --- # Manipulating Image Lists +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [Replace](reference/cimagelist-class.md#replace) member function replaces an image in an image list ([CImageList](reference/cimagelist-class.md)) with a new image. This function is also useful if you need to dynamically increase the number of images in an image list object. The [SetImageCount](reference/cimagelist-class.md#setimagecount) function dynamically changes the number of images stored in the image list. If you increase the size of the image list, call `Replace` to add images to the new image slots. If you decrease the size of the image list, the images beyond the new size are freed. The [Remove](reference/cimagelist-class.md#remove) member function removes an image from an image list. The [Copy](reference/cimagelist-class.md#copy) member function can copy or swap images within an image list. This function allows you to indicate whether the source image should be copied to the destination index or the source and destination images should be swapped. diff --git a/docs/mfc/manipulating-menus-during-program-execution.md b/docs/mfc/manipulating-menus-during-program-execution.md index 27ce44d928d..272a383e298 100644 --- a/docs/mfc/manipulating-menus-during-program-execution.md +++ b/docs/mfc/manipulating-menus-during-program-execution.md @@ -3,10 +3,13 @@ description: "Learn more about: Manipulating Menus During Program Execution" title: "Manipulating Menus During Program Execution" ms.date: "11/04/2016" helpviewer_keywords: ["menus [MFC], editing during execution", "menus during execution [MFC], deleting", "CMenu class [MFC], manipulating menus during execution", "menus [MFC], manipulating during execution", "menus during execution"] -ms.assetid: 722c7c00-4be2-4967-877d-f96aaa604396 +ms.topic: concept-article --- # Manipulating Menus During Program Execution +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use class `CMenu` to manipulate menus and menu items on the fly. `CMenu` encapsulates a Windows HMENU handle and supplies member functions for working with menus. See the overview for class [CMenu](reference/cmenu-class.md) for details. diff --git a/docs/mfc/manipulating-the-progress-control.md b/docs/mfc/manipulating-the-progress-control.md index 69a85df1a21..ab103759dc1 100644 --- a/docs/mfc/manipulating-the-progress-control.md +++ b/docs/mfc/manipulating-the-progress-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Manipulating the Progress Control" title: "Manipulating the Progress Control" ms.date: "11/04/2016" helpviewer_keywords: ["CProgressCtrl class [MFC], working with", "progress controls [MFC], manipulating", "CProgressCtrl class [MFC], manipulating", "controlling progress controls [MFC]", "CProgressCtrl class [MFC], using"] -ms.assetid: 9af561d1-980b-4003-a6da-ff79be15bf23 +ms.topic: how-to --- # Manipulating the Progress Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are three ways to change the current position of a progress control ([CProgressCtrl](reference/cprogressctrl-class.md)). - The position can be changed by a preset increment amount. diff --git a/docs/mfc/manipulating-the-tool-tip-control.md b/docs/mfc/manipulating-the-tool-tip-control.md index 0663d49d969..ea50fc35323 100644 --- a/docs/mfc/manipulating-the-tool-tip-control.md +++ b/docs/mfc/manipulating-the-tool-tip-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Manipulating the Tool Tip Control" title: "Manipulating the Tool Tip Control" ms.date: "11/04/2016" helpviewer_keywords: ["CToolTipCtrl class [MFC], manipulating tool tip attributes", "tool tips [MFC], attributes"] -ms.assetid: 3600afe5-712a-4b56-8456-96e85fe879af +ms.topic: concept-article --- # Manipulating the Tool Tip Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Class `CToolTipCtrl` provides a group of member functions that control the various attributes of the `CToolTipCtrl` object and the tool tip window. The initial, pop-up, and reshow durations for the tool tip windows can be set and retrieved with calls to [GetDelayTime](reference/ctooltipctrl-class.md#getdelaytime) and [SetDelayTime](reference/ctooltipctrl-class.md#setdelaytime). diff --git a/docs/mfc/mapi-samples.md b/docs/mfc/mapi-samples.md index cf952047442..87c7684e026 100644 --- a/docs/mfc/mapi-samples.md +++ b/docs/mfc/mapi-samples.md @@ -3,10 +3,12 @@ description: "Learn more about: MAPI Samples" title: "MAPI Samples" ms.date: "11/04/2016" helpviewer_keywords: ["MAPI, MFC", "sample applications [MFC], MAPI"] -ms.assetid: 3af3085c-8c8f-47c9-a966-b82311a20bf6 --- # MAPI Samples +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + See the following sample programs that illustrate Microsoft Messaging Application Programming Interface (MAPI) functionality: - [NPP](../overview/visual-cpp-samples.md) diff --git a/docs/mfc/mapi-support-in-mfc.md b/docs/mfc/mapi-support-in-mfc.md index cdb9d8b6388..b241e223917 100644 --- a/docs/mfc/mapi-support-in-mfc.md +++ b/docs/mfc/mapi-support-in-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: MAPI Support in MFC" title: "MAPI Support in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, MAPI support", "MAPI support in MFC", "CDocument class [MFC], and MAPI", "OnUpdateFileSendMail method [MFC]", "MAPI, MFC", "OnFileSendMail method [MFC]"] -ms.assetid: cafbecb1-0427-4077-b4b8-159bae5b49b8 --- # MAPI Support in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC supplies support for a subset of the Microsoft Messaging Application Program Interface (MAPI) in class `CDocument`. Specifically, `CDocument` has member functions that determine whether mail support is present on the end-user's machine and, if so, enable a Send Mail command whose standard command ID is ID_FILE_SEND_MAIL. The MFC handler function for this command allows the user to send a document through electronic mail. > [!TIP] @@ -21,7 +23,7 @@ MAPI needs to read the file to send the attachment. If the application keeps its #### To implement a Send Mail command with MFC -1. Use the Visual C++ menu editor to add a menu item whose command ID is ID_FILE_SEND_MAIL. +1. Use the Visual Studio menu editor to add a menu item whose command ID is ID_FILE_SEND_MAIL. This command ID is provided by the framework in AFXRES.H. The command can be added to any menu, but it is usually added to the **File** menu. diff --git a/docs/mfc/mapi.md b/docs/mfc/mapi.md index 70bc8612b7c..55667986b9f 100644 --- a/docs/mfc/mapi.md +++ b/docs/mfc/mapi.md @@ -3,10 +3,12 @@ description: "Learn more about: MAPI" title: "MAPI" ms.date: "11/04/2016" helpviewer_keywords: ["messaging [MFC], client applications", "enabling applications for MAPI [MFC]", "MAPI support in MFC", "e-mail [MFC], enabling", "mail [MFC], enabling your application", "MAPI, MFC", "enabling applications for mail [MFC]"] -ms.assetid: 193449f7-b131-4ab0-9301-8d4f6cd1e7c4 --- # MAPI +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the Microsoft Messaging Application Programming Interface (MAPI) for client message application developers. MFC supplies support for a subset of MAPI in class `CDocument` but does not encapsulate the entire API. For more information, see [MAPI Support in MFC](mapi-support-in-mfc.md). MAPI is a set of functions that mail-enabled and mail-aware applications use to create, manipulate, transfer, and store mail messages. It gives application developers the tools to define the purpose and content of mail messages and gives them flexibility in their management of stored mail messages. MAPI also provides a common interface that application developers can use to create mail-enabled and mail-aware applications independent of the underlying messaging system. diff --git a/docs/mfc/mapping-messages.md b/docs/mfc/mapping-messages.md index 58e53eb5f24..ebd242a4c18 100644 --- a/docs/mfc/mapping-messages.md +++ b/docs/mfc/mapping-messages.md @@ -3,10 +3,13 @@ description: "Learn more about: Mapping Messages" title: "Mapping Messages" ms.date: "11/04/2016" helpviewer_keywords: ["message maps [MFC], about message maps", "mappings [MFC], commands", "commands [MFC], mapping", "command mapping [MFC]", "message handling [MFC], connecting to handler functions", "commands [MFC], connecting to handler functions", "mappings [MFC], messages", "messages [MFC], mapping"] -ms.assetid: 996f0652-0698-4b8c-b893-cdaa836d9d0f +ms.topic: concept-article --- # Mapping Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Each framework class that can receive messages or commands has its own "message map." The framework uses message maps to connect messages and commands to their handler functions. Any class derived from class `CCmdTarget` can have a message map. Other articles explain message maps in detail and describe how to use them. In spite of the name "message map," message maps handle both messages and commands — all three categories of messages listed in [Message Categories](message-categories.md). diff --git a/docs/mfc/mapping-windows-messages-to-your-class.md b/docs/mfc/mapping-windows-messages-to-your-class.md index f8a7a8751e2..115e49cc2d1 100644 --- a/docs/mfc/mapping-windows-messages-to-your-class.md +++ b/docs/mfc/mapping-windows-messages-to-your-class.md @@ -3,10 +3,13 @@ description: "Learn more about: Mapping Windows Messages to Your Class" title: "Mapping Windows Messages to Your Class" ms.date: "09/06/2019" helpviewer_keywords: ["MFC dialog boxes [MFC], Windows messages", "message maps [MFC], in dialog class", "Windows messages [MFC], mapping in dialog classes", "messages to dialog class [MFC]", "mappings [MFC], messages to dialog class [MFC]", "message maps [MFC], mapping Windows messages to classes", "messages to dialog class [MFC], mapping", "Class Wizard [MFC]"] -ms.assetid: a4c6fd1f-1d33-47c9-baa0-001755746d6d +ms.topic: concept-article --- # Mapping Windows Messages to Your Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you need your dialog box to handle Windows messages, override the appropriate handler functions. To do so, choose the **Class View** tab in **Solution Explorer**, right click on the class that represents the dialog box, and choose [Class Wizard](reference/mfc-class-wizard.md). Use the wizard to [map the messages](reference/mapping-messages-to-functions.md) to the dialog class. This writes a message-map entry for each message and adds the message-handler member functions to the class. Use the code editor to write code in the message handlers. You can also override member functions of [CDialog](reference/cdialog-class.md) and its base classes, especially [CWnd](reference/cwnd-class.md). diff --git a/docs/mfc/mdi-tabbed-groups.md b/docs/mfc/mdi-tabbed-groups.md index c4b435c6ecf..ad7e811bbfb 100644 --- a/docs/mfc/mdi-tabbed-groups.md +++ b/docs/mfc/mdi-tabbed-groups.md @@ -3,10 +3,12 @@ description: "Learn more about: MDI Tabbed Groups" title: "MDI Tabbed Groups" ms.date: "11/04/2016" helpviewer_keywords: ["mdi [MFC], tabbed groups", "tabbed grous [MFC]"] -ms.assetid: 0a464f36-39b7-4e68-8b67-ec175de28377 --- # MDI Tabbed Groups +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The multiple document interface (MDI) tabbed groups feature enables multiple document interface (MDI) applications to display one or more tabbed windows (or groups of tabbed windows, known as *tabbed groups*) in the MDI client area. The tabbed windows can be aligned vertically or horizontally. If an application hosts more than one MDI tabbed group, the groups are separated by splitters. ## Features diff --git a/docs/mfc/memory-management-examples.md b/docs/mfc/memory-management-examples.md index c76643dce83..398fc193af1 100644 --- a/docs/mfc/memory-management-examples.md +++ b/docs/mfc/memory-management-examples.md @@ -3,10 +3,12 @@ description: "Learn more about: Memory Management: Examples" title: "Memory Management: Examples" ms.date: "11/04/2016" helpviewer_keywords: ["objects [MFC], memory allocation", "data structures [MFC]", "arrays [MFC], allocating resources", "objects [MFC], allocating memory", "data structures [MFC], allocating memory", "examples [MFC], memory allocation", "heap allocation [MFC], examples", "memory allocation [MFC], arrays", "MFC, memory management", "struct memory allocation [MFC]", "types [MFC], memory allocation", "memory allocation [MFC], objects", "memory allocation [MFC], examples", "arrays [MFC], memory management", "frame allocation [MFC]", "memory allocation [MFC], data structures"] -ms.assetid: f10240f8-b698-4c83-9288-97a54318930b --- # Memory Management: Examples +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes how MFC performs frame allocations and heap allocations for each of the three typical kinds of memory allocations: - [An array of bytes](#_core_allocation_of_an_array_of_bytes) diff --git a/docs/mfc/memory-management-frame-allocation.md b/docs/mfc/memory-management-frame-allocation.md index dc3cfa5d7a0..0bb639b12c0 100644 --- a/docs/mfc/memory-management-frame-allocation.md +++ b/docs/mfc/memory-management-frame-allocation.md @@ -3,10 +3,12 @@ description: "Learn more about: Memory Management: Frame Allocation" title: "Memory Management: Frame Allocation" ms.date: "11/04/2016" helpviewer_keywords: ["memory leaks [MFC], frame allocation", "memory [MFC], detecting leaks", "memory [MFC], reclaiming", "memory allocation [MFC], frames", "frame variables [MFC], automatic deletion of", "scope [MFC], frame variables", "heap allocation [MFC], vs. frame allocation", "variables [MFC], frame variables", "memory leaks [MFC], detecting", "memory, releasing [MFC]", "stack frames [MFC]", "memory leaks [MFC], allocating objects on the frame", "detecting memory leaks [MFC]", "frame allocation [MFC]", "frame variables [MFC]"] -ms.assetid: 945a211a-6f4f-4679-bb6a-b0f2a0d4a6c1 --- # Memory Management: Frame Allocation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allocation on the frame takes its name from the "stack frame" that is set up whenever a function is called. The stack frame is an area of memory that temporarily holds the arguments to the function as well as any variables that are defined local to the function. Frame variables are often called "automatic" variables because the compiler automatically allocates the space for them. There are two key characteristics of frame allocations. First, when you define a local variable, enough space is allocated on the stack frame to hold the entire variable, even if it is a large array or data structure. Second, frame variables are automatically deleted when they go out of scope: diff --git a/docs/mfc/memory-management-heap-allocation.md b/docs/mfc/memory-management-heap-allocation.md index 4d0992fab1f..d9fe3cec85e 100644 --- a/docs/mfc/memory-management-heap-allocation.md +++ b/docs/mfc/memory-management-heap-allocation.md @@ -3,10 +3,12 @@ description: "Learn more about: Memory Management: Heap Allocation" title: "Memory Management: Heap Allocation" ms.date: "11/04/2016" helpviewer_keywords: ["memory [MFC], detecting leaks", "delete operator [MFC], using with debug MFC", "heap allocation [MFC], described", "memory allocation [MFC], heap memory", "memory leaks [MFC], detecting", "new operator [MFC], using with debug MFC", "heap allocation [MFC]", "detecting memory leaks [MFC]"] -ms.assetid: a5d949c6-1b79-476e-9c66-513a558203d9 --- # Memory Management: Heap Allocation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The heap is reserved for the memory allocation needs of the program. It is an area apart from the program code and the stack. Typical C programs use the functions **malloc** and **free** to allocate and deallocate heap memory. The Debug version of MFC provides modified versions of the C++ built-in operators **`new`** and **`delete`** to allocate and deallocate objects in heap memory. When you use **`new`** and **`delete`** instead of **malloc** and **free**, you are able to take advantage of the class library's memory-management debugging enhancements, which can be useful in detecting memory leaks. When you build your program with the Release version of MFC, the standard versions of the **`new`** and **`delete`** operators provide an efficient way to allocate and deallocate memory (the Release version of MFC does not provide modified versions of these operators). diff --git a/docs/mfc/memory-management-resizable-memory-blocks.md b/docs/mfc/memory-management-resizable-memory-blocks.md index 7223f4180ad..6ac07cbf65b 100644 --- a/docs/mfc/memory-management-resizable-memory-blocks.md +++ b/docs/mfc/memory-management-resizable-memory-blocks.md @@ -3,10 +3,12 @@ description: "Learn more about: Memory Management: Resizable Memory Blocks" title: "Memory Management: Resizable Memory Blocks" ms.date: "11/04/2016" helpviewer_keywords: ["memory blocks [MFC], resizable", "memory [MFC], corruption", "memory allocation [MFC], memory block size", "memory blocks [MFC], allocating", "blocks [MFC], memory allocation", "resizable memory blocks [MFC]"] -ms.assetid: f0efe6f4-a3ed-4541-9195-51ec1291967a --- # Memory Management: Resizable Memory Blocks +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The **`new`** and **`delete`** operators, described in the article [Memory Management: Examples](memory-management-examples.md), are good for allocating and deallocating fixed-size memory blocks and objects. Occasionally, your application may need resizable memory blocks. You must use the standard C run-time library functions [malloc](../c-runtime-library/reference/malloc.md), [realloc](../c-runtime-library/reference/realloc.md), and [free](../c-runtime-library/reference/free.md) to manage resizable memory blocks on the heap. > [!IMPORTANT] diff --git a/docs/mfc/memory-management.md b/docs/mfc/memory-management.md index 89b67110a51..7e8e4f29121 100644 --- a/docs/mfc/memory-management.md +++ b/docs/mfc/memory-management.md @@ -3,10 +3,12 @@ description: "Learn more about: Memory Management" title: "Memory Management" ms.date: "11/04/2016" helpviewer_keywords: ["memory [MFC]", "MFC, memory management", "memory allocation [MFC]", "memory [MFC], managing", "memory allocation [MFC], MFC"] -ms.assetid: 934ac81b-d630-4232-88e5-ea74f7187987 --- # Memory Management +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This group of articles describes how to take advantage of the general-purpose services of the Microsoft Foundation Class Library (MFC) related to memory management. Memory allocation can be divided into two main categories: frame allocations and heap allocations. One main difference between the two allocation techniques is that with frame allocation you typically work with the actual memory block itself, while with heap allocation you are always given a pointer to the memory block. Another major difference between the two schemes is that frame objects are automatically deleted, while heap objects must be explicitly deleted by the programmer. diff --git a/docs/mfc/menu-sample-list.md b/docs/mfc/menu-sample-list.md index 5c9810c792f..5cccff447db 100644 --- a/docs/mfc/menu-sample-list.md +++ b/docs/mfc/menu-sample-list.md @@ -3,10 +3,12 @@ description: "Learn more about: Menu Sample List" title: "Menu Sample List" ms.date: "11/04/2016" helpviewer_keywords: ["sample applications [MFC], menus"] -ms.assetid: 6d89c723-03d6-474e-8ca5-e98f93bd41cc --- # Menu Sample List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + See the following sample programs that illustrate creating, editing, and updating menus: *MDI Sample: Enable and Disable Menu Items* diff --git a/docs/mfc/menus-and-resources-container-additions.md b/docs/mfc/menus-and-resources-container-additions.md index 7ece3400513..09b822aea90 100644 --- a/docs/mfc/menus-and-resources-container-additions.md +++ b/docs/mfc/menus-and-resources-container-additions.md @@ -4,10 +4,12 @@ title: "Menus and Resources: Container Additions" ms.date: "11/04/2016" f1_keywords: ["IDP_OLE_INIT_FAILED", "IDP_FAILED_TO_CREATE", "VK_ESCAPE"] helpviewer_keywords: ["application accelerator table [MFC]", "VK_ESCAPE key [MFC]", "IDP_FAILED_TO_CREATE macro [MFC]", "visual editing, application menus and resources", "OLE containers [MFC], menus and resources", "accelerator tables [MFC], container applications", "IDP_OLE_INIT_FAILED macro [MFC]", "CONTAIN tutorial [MFC]", "Links menu item [MFC]"] -ms.assetid: 425448be-8ca0-412e-909a-a3a9ce845288 --- # Menus and Resources: Container Additions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the changes that need to be made to the menus and other resources in a visual editing container application. In container applications, two types of changes need to be made: modifications to existing resources to support OLE visual editing and addition of new resources used for in-place activation. If you use the application wizard to create your container application, these steps will be done for you, but they may require some customization. diff --git a/docs/mfc/menus-and-resources-menu-merging.md b/docs/mfc/menus-and-resources-menu-merging.md index b418a729ab0..523cbbb818e 100644 --- a/docs/mfc/menus-and-resources-menu-merging.md +++ b/docs/mfc/menus-and-resources-menu-merging.md @@ -3,10 +3,12 @@ description: "Learn more about: Menus and Resources: Menu Merging" title: "Menus and Resources: Menu Merging" ms.date: "11/04/2016" helpviewer_keywords: ["status bars [MFC], OLE document applications", "visual editing [MFC], application menus and resources", "coordinating menu layouts [MFC]", "OLE containers [MFC], menus and resources", "toolbars [MFC], OLE document applications", "merging toolbar and status bar [MFC]", "menus [MFC], OLE document applications"] -ms.assetid: 80b6bb17-d830-4122-83f0-651fc112d4d1 --- # Menus and Resources: Menu Merging +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article details the steps necessary for OLE document applications to handle visual editing and in-place activation properly. In-place activation poses a challenge for both container and server (component) applications. The user remains in the same frame window (within the context of the container document) but is actually running another application (the server). This requires coordination between the resources of the container and server applications. Topics covered in this article include: diff --git a/docs/mfc/menus-and-resources-ole.md b/docs/mfc/menus-and-resources-ole.md index 8cc71f8bc8a..577625c40ba 100644 --- a/docs/mfc/menus-and-resources-ole.md +++ b/docs/mfc/menus-and-resources-ole.md @@ -3,10 +3,12 @@ description: "Learn more about: Menus and Resources (OLE)" title: "Menus and Resources (OLE)" ms.date: "11/04/2016" helpviewer_keywords: ["OLE visual editing servers [MFC]", "status bars [MFC], OLE document applications", "visual editing [MFC], application menus and resources", "string tables [MFC], visual editing applications", "OLE containers [MFC], menus and resources", "OLE applications [MFC], menus and resources", "OLE server applications [MFC], menus and resources", "toolbars [MFC], OLE document applications", "string editing [MFC], visual editing applications", "server applications [MFC], OLE menus and resources", "applications [OLE], menus and resources", "menus [MFC], OLE document applications", "in-place activation [MFC], OLE menus and resources", "containers [MFC], OLE container applications", "OLE menus and resources [MFC]"] -ms.assetid: 52bfa086-7d3d-466f-94c7-c7061f3bdb3a --- # Menus and Resources (OLE) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This group of articles explains the use of menus and resources in MFC OLE document applications. OLE visual editing places additional requirements on the menu and other resources provided by OLE document applications because there are a number of modes in which both container and server (component) applications can be started and used. For example, a full-server application can run in any of these three modes: diff --git a/docs/mfc/menus-and-resources-server-additions.md b/docs/mfc/menus-and-resources-server-additions.md index dda5aca9ad4..0bdebe03ea2 100644 --- a/docs/mfc/menus-and-resources-server-additions.md +++ b/docs/mfc/menus-and-resources-server-additions.md @@ -3,10 +3,12 @@ description: "Learn more about: Menus and Resources: Server Additions" title: "Menus and Resources: Server Additions" ms.date: "11/04/2016" helpviewer_keywords: ["OLE visual editing servers [MFC]", "accelerator tables [MFC], server applications", "visual editing [MFC], application menus and resources", "server applications [MFC], accelerator table", "string tables [MFC], visual editing applications", "servers [MFC], menu additions", "resources [MFC], server applications", "OLE server applications [MFC], menus and resources", "string editing [MFC], visual editing applications", "IDP_OLE_INIT_FAILED macro [MFC]", "server applications [MFC], OLE menus and resources", "OLE initialization failure [MFC]"] -ms.assetid: 56ce9e8d-8f41-4db8-8dee-e8b0702d057c --- # Menus and Resources: Server Additions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the changes that need to be made to the menus and other resources in a visual editing server (component) application. A server application requires many additions to the menu structure and other resources because it can be started in one of three modes: stand alone, embedded, or in place. As described in the [Menus and Resources (OLE)](menus-and-resources-ole.md) article, there are a maximum of four sets of menus. All four are used for an MDI full-server application, while only three are used for a miniserver. The application wizard will create the menu layout necessary for the type of server you want. Some customization may be necessary. If you do not use the application wizard, you may want to look at HIERSVR.RC, the resource script for the MFC sample application [HIERSVR](../overview/visual-cpp-samples.md), to see how these changes are implemented. diff --git a/docs/mfc/menus-mfc.md b/docs/mfc/menus-mfc.md index 5cbfe9db0ff..c1abbae69f7 100644 --- a/docs/mfc/menus-mfc.md +++ b/docs/mfc/menus-mfc.md @@ -3,17 +3,19 @@ description: "Learn more about: Menus (MFC)" title: "Menus (MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["menus [MFC], updating as context changes", "menus [MFC], MFC resources for working with", "menus [MFC], manipulating during execution", "menus [MFC]"] -ms.assetid: 6a181495-47a9-4356-83fc-b89152d6cb4c --- # Menus (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC supplies two elements to help you work with menus: - Class [CMenu](reference/cmenu-class.md) for manipulating your program's menus at run time. Use the documentation for `CMenu` and the sample to learn how to use `CMenu` effectively. - A mechanism for updating menus and toolbar buttons: enabling or disabling them on the fly to suit current program conditions. -Visual C++ also provides a [menu editor](../windows/menu-editor.md) for creating and editing your program's menu resources. +Visual Studio also provides a [menu editor](../windows/menu-editor.md) for creating and editing your program's menu resources. ## What do you want to know more about diff --git a/docs/mfc/message-categories.md b/docs/mfc/message-categories.md index 5bc141928a7..ad100f126fb 100644 --- a/docs/mfc/message-categories.md +++ b/docs/mfc/message-categories.md @@ -3,10 +3,13 @@ description: "Learn more about: Message Categories" title: "Message Categories" ms.date: "11/04/2016" helpviewer_keywords: ["messages [MFC], categories", "control-notification messages [MFC]", "Windows messages [MFC], categories", "controls [MFC], notifications", "command messages [MFC]", "messages [MFC], Windows", "message handling [MFC], message types"] -ms.assetid: 68e1db75-9da6-4a4d-b2c2-dc4d59f8d87b +ms.topic: how-to --- # Message Categories +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + What kinds of messages do you write handlers for There are three main categories: 1. Windows messages diff --git a/docs/mfc/message-handlers.md b/docs/mfc/message-handlers.md index 80bf4659c7d..60944d82359 100644 --- a/docs/mfc/message-handlers.md +++ b/docs/mfc/message-handlers.md @@ -3,17 +3,19 @@ description: "Learn more about: Message Handlers" title: "Message Handlers" ms.date: "11/04/2016" helpviewer_keywords: ["message handlers [MFC]", "command handling [MFC], message handlers", "handlers [MFC]", "message handling [MFC], message handler functions", "handlers [MFC], command", "handlers [MFC], message"] -ms.assetid: 51bc4e76-dbe3-4cc2-b026-3199d56b2fa9 --- # Message Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In MFC, a dedicated *handler* function processes each separate message. Message-handler functions are member functions of a class. This documentation uses the terms *message-handler member function*, *message-handler function*, *message handler*, and *handler* interchangeably. Some kinds of message handlers are also called "command handlers." Writing message handlers accounts for a large proportion of your work in writing a framework application. This article family describes how the message-processing mechanism works. What does the handler for a message do It does whatever you want done in response to that message. You can create the handlers by using the [Class Wizard](reference/mfc-class-wizard.md) of the class, and then fill in the handler's code using the source code editor. -You can use all of the facilities of Microsoft Visual C++ and MFC to write your handlers. For a list of all classes, see [Class Library Overview](class-library-overview.md) in the *MFC Reference*. +You can use all of the facilities of Visual Studio and MFC to write your handlers. For a list of all classes, see [Class Library Overview](class-library-overview.md) in the *MFC Reference*. ## See also diff --git a/docs/mfc/message-handling-and-command-targets.md b/docs/mfc/message-handling-and-command-targets.md index b6f6fe862a7..f53661b8363 100644 --- a/docs/mfc/message-handling-and-command-targets.md +++ b/docs/mfc/message-handling-and-command-targets.md @@ -4,10 +4,12 @@ title: "Message Handling and Command Targets" ms.date: "11/04/2016" f1_keywords: ["IOleCommandTarget"] helpviewer_keywords: ["command targets [MFC]", "message handling [MFC], active documents", "IOleCommandTarget interface [MFC]", "command routing [MFC], command targets"] -ms.assetid: e45ce14c-e6b6-4262-8f3b-4e891e0ec2a3 --- # Message Handling and Command Targets +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The command dispatch interface `IOleCommandTarget` defines a simple and extensible mechanism to query and execute commands. This mechanism is simpler than Automation's `IDispatch` because it relies entirely on a standard set of commands; commands rarely have arguments, and no type information is involved (type safety is diminished for command arguments as well). In the command dispatch interface design, each command belongs to a "command group" which is itself identified with a **GUID**. Therefore, anyone can define a new group and define all the commands within that group without any need to coordinate with Microsoft or any other vendor. (This is essentially the same means of definition as a **dispinterface** plus **dispIDs** in Automation. There is overlap here, although this command routing mechanism is only for command routing and not for scripting/programmability on a large scale as Automation handles.) diff --git a/docs/mfc/message-handling-and-mapping.md b/docs/mfc/message-handling-and-mapping.md index bbbbaee3203..ee575c92be8 100644 --- a/docs/mfc/message-handling-and-mapping.md +++ b/docs/mfc/message-handling-and-mapping.md @@ -3,10 +3,12 @@ description: "Learn more about: Message Handling and Mapping" title: "Message Handling and Mapping" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, messages", "message handling [MFC]", "message maps [MFC]"] -ms.assetid: 62fe2a1b-944c-449d-a0f0-63c11ee0a3cb --- # Message Handling and Mapping +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article family describes how messages and commands are processed by the MFC framework and how you connect them to their handler functions. In traditional programs for Windows, Windows messages are handled in a large switch statement in a window procedure. MFC instead uses [message maps](message-categories.md) to map direct messages to distinct class member functions. Message maps are more efficient than virtual functions for this purpose, and they allow messages to be handled by the most appropriate C++ object — application, document, view, and so on. You can map a single message or a range of messages, command IDs, or control IDs. diff --git a/docs/mfc/message-sending-and-receiving.md b/docs/mfc/message-sending-and-receiving.md index 0aa04b4cd8e..95b7873283f 100644 --- a/docs/mfc/message-sending-and-receiving.md +++ b/docs/mfc/message-sending-and-receiving.md @@ -3,10 +3,12 @@ description: "Learn more about: Message Sending and Receiving" title: "Message Sending and Receiving" ms.date: "11/04/2016" helpviewer_keywords: ["Windows messages [MFC], handling in MFC", "control-notification messages [MFC]", "messages [MFC], receiving", "messages [MFC], MFC", "MFC, messages", "messages [MFC], sending"] -ms.assetid: 9ce189cb-b259-4c3b-b6f2-9cfbed18b98b --- # Message Sending and Receiving +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Consider the sending part of the process and how the framework responds. Most messages result from user interaction with the program. Commands are generated by mouse clicks in menu items or toolbar buttons or by accelerator keystrokes. The user also generates Windows messages by, for example, moving or resizing a window. Other Windows messages are sent when events such as program startup or termination occur, as windows get or lose the focus, and so on. Control-notification messages are generated by mouse clicks or other user interactions with a control, such as a button or list-box control in a dialog box. diff --git a/docs/mfc/messages-and-commands-in-the-framework.md b/docs/mfc/messages-and-commands-in-the-framework.md index 9cb53a25e9f..023b2947a2e 100644 --- a/docs/mfc/messages-and-commands-in-the-framework.md +++ b/docs/mfc/messages-and-commands-in-the-framework.md @@ -3,10 +3,12 @@ description: "Learn more about: Messages and Commands in the Framework" title: "Messages and Commands in the Framework" ms.date: "11/04/2016" helpviewer_keywords: ["events [MFC], command routing in MFC", "event-driven programming [MFC]", "events [MFC], event-driven programming", "message-driven programming [MFC]"] -ms.assetid: d799ed8c-6a9f-4f05-be5d-29cb5bc6d185 --- # Messages and Commands in the Framework +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Applications written for Microsoft Windows are "message driven." In response to events such as mouse clicks, keystrokes, window movements, and so on, Windows sends messages to the proper window. Framework applications process Windows messages like any other application for Windows. But the framework also provides some enhancements that make processing messages easier, more maintainable, and better encapsulated. The following topics introduce the key terms used in the rest of the article family to discuss messages and commands: diff --git a/docs/mfc/messages.md b/docs/mfc/messages.md index 2d0f33dd300..13d244746fa 100644 --- a/docs/mfc/messages.md +++ b/docs/mfc/messages.md @@ -3,10 +3,12 @@ description: "Learn more about: Messages" title: "Messages" ms.date: "11/04/2016" helpviewer_keywords: ["messages, MFC", "messages [MFC]"] -ms.assetid: b1476310-a135-42ca-817c-444fb3675491 --- # Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The message loop in the `Run` member function of class `CWinApp` retrieves queued messages generated by various events. For example, when the user clicks the mouse, Windows sends several mouse-related messages, such as WM_LBUTTONDOWN when the left mouse button is pressed and WM_LBUTTONUP when the left mouse button is released. The framework's implementation of the application message loop dispatches the message to the appropriate window. The important categories of messages are described in [Message Categories](message-categories.md). diff --git a/docs/mfc/methods-of-creating-a-status-bar.md b/docs/mfc/methods-of-creating-a-status-bar.md index 7d4e9bc4cf0..0eaad577a3f 100644 --- a/docs/mfc/methods-of-creating-a-status-bar.md +++ b/docs/mfc/methods-of-creating-a-status-bar.md @@ -3,10 +3,12 @@ description: "Learn more about: Methods of Creating a Status Bar" title: "Methods of Creating a Status Bar" ms.date: "11/04/2016" helpviewer_keywords: ["CStatusBar class [MFC], vs. CStatusBarCtrl", "methods [MFC], creating status bars", "CStatusBarCtrl class [MFC], vs. CStatusBar", "CStatusBarCtrl class [MFC], creating", "methods [MFC]", "status bars [MFC], creating"] -ms.assetid: 9aeaf290-7099-4762-a5ba-9c26705333c9 --- # Methods of Creating a Status Bar +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC provides two classes to create status bars: [CStatusBar](reference/cstatusbar-class.md) and [CStatusBarCtrl](reference/cstatusbarctrl-class.md) (which wraps the Windows common control API). `CStatusBar` provides all of the functionality of the status bar common control, it automatically interacts with menus and toolbars, and it handles many of the required common control settings and structures for you; however, your resulting executable usually will be larger than that created by using `CStatusBarCtrl`. `CStatusBarCtrl` usually results in a smaller executable, and you may prefer to use `CStatusBarCtrl` if you do not intend to integrate the status bar into the MFC architecture. If you plan to use `CStatusBarCtrl` and integrate the status bar into the MFC architecture, you must take additional care to communicate status bar control manipulations to MFC. This communication is not difficult; however, it is additional work that is unneeded when you use `CStatusBar`. diff --git a/docs/mfc/methods-of-creating-a-toolbar.md b/docs/mfc/methods-of-creating-a-toolbar.md index aca7ea41dc3..b3c940a3ae1 100644 --- a/docs/mfc/methods-of-creating-a-toolbar.md +++ b/docs/mfc/methods-of-creating-a-toolbar.md @@ -3,10 +3,12 @@ description: "Learn more about: Methods of Creating a Toolbar" title: "Methods of Creating a Toolbar" ms.date: "11/04/2016" helpviewer_keywords: ["CToolBarCtrl class [MFC], and CToolBar class [MFC]", "CToolBar class [MFC], creating toolbars", "MFC toolbars", "toolbar controls [MFC]", "toolbar controls [MFC], creating", "CToolBarCtrl class [MFC], creating toolbars"] -ms.assetid: f19d8d65-d49f-445c-abe8-d47d3e4101c8 --- # Methods of Creating a Toolbar +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC provides two classes to create toolbars: [CToolBar](reference/ctoolbar-class.md) and [CToolBarCtrl](reference/ctoolbarctrl-class.md) (which wraps the Windows common control API). `CToolBar` provides all of the functionality of the toolbar common control, and it handles many of the required common control settings and structures for you; however, your resulting executable usually will be larger than that created by using `CToolBarCtrl`. `CToolBarCtrl` usually results in a smaller executable, and you may prefer to use `CToolBarCtrl` if you do not intend to integrate the toolbar into the MFC architecture. If you plan to use `CToolBarCtrl` and integrate the toolbar into the MFC architecture, you must take additional care to communicate toolbar control manipulations to MFC. This communication is not difficult; however, it is additional work that is unneeded when you use `CToolBar`. diff --git a/docs/mfc/methods-of-creating-tool-tips.md b/docs/mfc/methods-of-creating-tool-tips.md index a51f80a85ad..7d3de35c5cd 100644 --- a/docs/mfc/methods-of-creating-tool-tips.md +++ b/docs/mfc/methods-of-creating-tool-tips.md @@ -3,10 +3,12 @@ description: "Learn more about: Methods of Creating Tool Tips" title: "Methods of Creating Tool Tips" ms.date: "11/04/2016" helpviewer_keywords: ["CToolTipCtrl class [MFC], creating tool tips", "tool tips [MFC], tool tip controls", "tool tips [MFC], creating"] -ms.assetid: b015e9f4-ddfb-49a4-a5a6-fa2d45e4d328 --- # Methods of Creating Tool Tips +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC provides three classes to create and manage the tool tip control: [CWnd](reference/cwnd-class.md), [CToolBarCtrl](reference/ctoolbarctrl-class.md), [CToolTipCtrl](reference/ctooltipctrl-class.md) and [CMFCToolTipCtrl](reference/cmfctooltipctrl-class.md). The tool tip member functions in these classes wrap the Windows common control API. Class `CToolBarCtrl` and class `CToolTipCtrl` are derived from class `CWnd`. `CWnd` provides four member functions to create and manage tool tips: [EnableToolTips](reference/cwnd-class.md#enabletooltips), [CancelToolTips](reference/cwnd-class.md#canceltooltips), [FilterToolTipMessage](reference/cwnd-class.md#filtertooltipmessage), and [OnToolHitTest](reference/cwnd-class.md#ontoolhittest). See these individual member functions for more information about how they implement tool tips. diff --git a/docs/mfc/mfc-activex-controls-accessing-ambient-properties.md b/docs/mfc/mfc-activex-controls-accessing-ambient-properties.md index 1d6babaf05f..613eacca7a6 100644 --- a/docs/mfc/mfc-activex-controls-accessing-ambient-properties.md +++ b/docs/mfc/mfc-activex-controls-accessing-ambient-properties.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Accessing Ambient Properti title: "MFC ActiveX Controls: Accessing Ambient Properties" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], accessing ambient properties", "properties [MFC], accessing ambient"] -ms.assetid: fdc9db29-e6b0-45d2-a879-8bd60e2058a7 --- # MFC ActiveX Controls: Accessing Ambient Properties +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses how an ActiveX control can access the ambient properties of its control container. A control can obtain information about its container by accessing the container's ambient properties. These properties expose visual characteristics, such as the container's background color, the current font used by the container, and operational characteristics, such as whether the container is currently in user mode or designer mode. A control can use ambient properties to tailor its appearance and behavior to the particular container in which it is embedded. However, a control should never assume that its container will support any particular ambient property. In fact, some containers may not support any ambient properties at all. In the absence of an ambient property, a control should assume a reasonable default value. diff --git a/docs/mfc/mfc-activex-controls-adding-another-custom-property-page.md b/docs/mfc/mfc-activex-controls-adding-another-custom-property-page.md index 7cac0772199..1cc40a9fbaf 100644 --- a/docs/mfc/mfc-activex-controls-adding-another-custom-property-page.md +++ b/docs/mfc/mfc-activex-controls-adding-another-custom-property-page.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Adding Another Custom Prop title: "MFC ActiveX Controls: Adding Another Custom Property Page" ms.date: "11/04/2016" helpviewer_keywords: ["property pages [MFC], MFC ActiveX controls", "custom property pages [MFC]", "ActiveX controls [MFC], property pages", "MFC ActiveX controls [MFC], property pages"] -ms.assetid: fcf7e119-9f29-41a9-908d-e9b1607e08af --- # MFC ActiveX Controls: Adding Another Custom Property Page +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Occasionally, an ActiveX control will have more properties than can reasonably fit on one property page. In this case, you can add property pages to the ActiveX control to display these properties. This article discusses adding new property pages to an ActiveX control that already has at least one property page. For more information on adding stock property pages (font, picture, or color), see the article [MFC ActiveX Controls: Using Stock Property Pages](mfc-activex-controls-using-stock-property-pages.md). diff --git a/docs/mfc/mfc-activex-controls-adding-custom-events.md b/docs/mfc/mfc-activex-controls-adding-custom-events.md index c89a3bcb620..034ada14256 100644 --- a/docs/mfc/mfc-activex-controls-adding-custom-events.md +++ b/docs/mfc/mfc-activex-controls-adding-custom-events.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Adding Custom Events" title: "MFC ActiveX Controls: Adding Custom Events" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], events [MFC]", "EVENT_CUSTOM prefix [MFC]", "custom events [MFC], adding to ActiveX controls", "EVENT_CUSTOM macro [MFC]", "InCircle method [MFC]", "ClickIn event", "FireClickIn event", "COleControl class [MFC], custom events [MFC]", "Click event, custom events [MFC]", "events [MFC], ActiveX controls", "custom events [MFC]", "FireEvent method, adding custom events"] -ms.assetid: c584d053-1e34-47aa-958e-37d3e9b85892 --- # MFC ActiveX Controls: Adding Custom Events +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Custom events differ from stock events in that they are not automatically fired by class `COleControl`. A custom event recognizes a certain action, determined by the control developer, as an event. The event map entries for custom events are represented by the EVENT_CUSTOM macro. The following section implements a custom event for an ActiveX control project that was created using the ActiveX Control Wizard. ## Adding a Custom Event with the Add Event Wizard diff --git a/docs/mfc/mfc-activex-controls-adding-custom-methods.md b/docs/mfc/mfc-activex-controls-adding-custom-methods.md index 3886e34488c..a1b2c458c84 100644 --- a/docs/mfc/mfc-activex-controls-adding-custom-methods.md +++ b/docs/mfc/mfc-activex-controls-adding-custom-methods.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Adding Custom Methods" title: "MFC ActiveX Controls: Adding Custom Methods" ms.date: "09/12/2018" helpviewer_keywords: ["MFC ActiveX controls [MFC], methods", "PtInCircle custom method [MFC]"] -ms.assetid: 8f8dc344-44a0-4021-8db5-4cdd3d700e18 --- # MFC ActiveX Controls: Adding Custom Methods +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Custom methods differ from stock methods in that they are not already implemented by `COleControl`. You must supply the implementation for each custom method you add to your control. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-adding-custom-properties.md b/docs/mfc/mfc-activex-controls-adding-custom-properties.md index a14b72ef64c..f6f15299fde 100644 --- a/docs/mfc/mfc-activex-controls-adding-custom-properties.md +++ b/docs/mfc/mfc-activex-controls-adding-custom-properties.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Adding Custom Properties" title: "MFC ActiveX Controls: Adding Custom Properties" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], properties", "properties [MFC], custom"] -ms.assetid: 85af5167-74c7-427b-b8f3-e0d7b73942e5 --- # MFC ActiveX Controls: Adding Custom Properties +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Custom properties differ from stock properties in that custom properties are not already implemented by the `COleControl` class. A custom property is used to expose a certain state or appearance of an ActiveX control to a programmer using the control. This article describes how to add a custom property to the ActiveX control using the Add Property Wizard and explains the resulting code modifications. Topics include: diff --git a/docs/mfc/mfc-activex-controls-adding-stock-events-to-an-activex-control.md b/docs/mfc/mfc-activex-controls-adding-stock-events-to-an-activex-control.md index 6199bcbffa9..ee97fd6f354 100644 --- a/docs/mfc/mfc-activex-controls-adding-stock-events-to-an-activex-control.md +++ b/docs/mfc/mfc-activex-controls-adding-stock-events-to-an-activex-control.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Adding Stock Events to an ActiveX Control" ms.date: "11/04/2016" f1_keywords: ["EVENT__STOCK_ERROR", "EVENT__STOCK_READYSTATECHANGE", "ReadyStateChange", "EVENT__STOCK_MOUSEMOVE", "EVENT__STOCK_MOUSEUP", "EVENT__STOCK_DBLCLICK", "KeyPress", "EVENT__STOCK_KEYDOWN", "EVENT__STOCK", "EVENT__STOCK_MOUSEDOWN", "EVENT__STOCK_KEYPRESS", "EVENT__STOCK_CLICK", "EVENT__STOCK_KEYUP"] helpviewer_keywords: ["MFC ActiveX controls [MFC], events", "KeyPress event", "FireDblClick event", "FireMouseDown event", "events [MFC], stock", "FireKeyPress event", "EVENT_STOCK_MOUSEMOVE event", "EVENT_STOCK_CLICK event", "FireClick event", "FireKeyUp event", "FireMouseUp event", "EVENT_STOCK_ERROREVENT event", "EVENT_STOCK_KEYDOWN event", "EVENT_STOCK_MOUSEDOWN event", "EVENT_STOCK_KEYPRESS macro [MFC]", "EVENT_STOCK_KEYUP event", "EVENT_STOCK_DBLCLICK event", "FireError event", "FireKeyDown event", "ReadyStateChange event", "EVENT_STOCK_MOUSEUP event", "FireMouseMove event", "EVENT_STOCK prefix", "EVENT_STOCK_READYSTATECHANGE event", "EVENT_STOCK_KEYPRESS event"] -ms.assetid: 3eeadc67-4b3d-4444-8caa-53054073988a --- # MFC ActiveX Controls: Adding Stock Events to an ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Stock events differ from custom events in that they are automatically fired by class [COleControl](reference/colecontrol-class.md). `COleControl` contains predefined member functions that fire events resulting from common actions. Some common actions implemented by `COleControl` include single- and double-clicks on the control, keyboard events, and changes in the state of the mouse buttons. Event map entries for stock events are always preceded by the EVENT_STOCK prefix. ## Stock Events Supported by the Add Event Wizard diff --git a/docs/mfc/mfc-activex-controls-adding-stock-methods.md b/docs/mfc/mfc-activex-controls-adding-stock-methods.md index 7764a1a974e..408b9945866 100644 --- a/docs/mfc/mfc-activex-controls-adding-stock-methods.md +++ b/docs/mfc/mfc-activex-controls-adding-stock-methods.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Adding Stock Methods" title: "MFC ActiveX Controls: Adding Stock Methods" ms.date: "09/12/2018" helpviewer_keywords: ["MFC ActiveX controls [MFC], stock methods", "MFC ActiveX controls [MFC], methods", "DoClick method [MFC]"] -ms.assetid: bc4fad78-cabd-4cc0-a798-464b1a682f0b --- # MFC ActiveX Controls: Adding Stock Methods +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A stock method differs from a custom method in that it is already implemented by class [COleControl](reference/colecontrol-class.md). For example, `COleControl` contains a predefined member function that supports the Refresh method for your control. The dispatch map entry for this stock method is DISP_STOCKFUNC_REFRESH. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-adding-stock-properties.md b/docs/mfc/mfc-activex-controls-adding-stock-properties.md index 8d70bbf4929..574cf734613 100644 --- a/docs/mfc/mfc-activex-controls-adding-stock-properties.md +++ b/docs/mfc/mfc-activex-controls-adding-stock-properties.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Adding Stock Properties" title: "MFC ActiveX Controls: Adding Stock Properties" ms.date: "11/04/2016" helpviewer_keywords: ["BackColor property [MFC]", "properties [MFC], adding stock", "ForeColor property [MFC]", "MFC ActiveX controls [MFC], properties", "foreground colors, ActiveX controls", "foreground colors [MFC]"] -ms.assetid: 8b98c8c5-5b69-4366-87bf-0e61e6668ecb --- # MFC ActiveX Controls: Adding Stock Properties +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Stock properties differ from custom properties in that they are already implemented by the class `COleControl`. `COleControl` contains predefined member functions that support common properties for the control. Some common properties include the control's caption and the foreground and background colors. For information on other stock properties, see [Stock Properties Supported by the Add Property Wizard](#_core_stock_properties_supported_by_classwizard) later in this article. The dispatch map entries for stock properties are always prefixed by DISP_STOCKPROP. This article describes how to add a stock property (in this case, Caption) to an ActiveX control using the Add Property Wizard and explains the resulting code modifications. Topics include: diff --git a/docs/mfc/mfc-activex-controls-advanced-property-implementation.md b/docs/mfc/mfc-activex-controls-advanced-property-implementation.md index 03227889216..d9fd955fb6f 100644 --- a/docs/mfc/mfc-activex-controls-advanced-property-implementation.md +++ b/docs/mfc/mfc-activex-controls-advanced-property-implementation.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Advanced Property Implemen title: "MFC ActiveX Controls: Advanced Property Implementation" ms.date: "09/12/2018" helpviewer_keywords: ["MFC ActiveX controls [MFC], error codes", "properties [MFC], ActiveX controls", "MFC ActiveX controls [MFC], properties"] -ms.assetid: ec2e6759-5a8e-41d8-a275-99af8ff6f32e --- # MFC ActiveX Controls: Advanced Property Implementation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes topics related to implementing advanced properties in an ActiveX control. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-advanced-topics.md b/docs/mfc/mfc-activex-controls-advanced-topics.md index 12416853047..4cf57c98d20 100644 --- a/docs/mfc/mfc-activex-controls-advanced-topics.md +++ b/docs/mfc/mfc-activex-controls-advanced-topics.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Advanced Topics" title: "MFC ActiveX Controls: Advanced Topics" ms.date: "09/12/2018" helpviewer_keywords: ["MFC ActiveX controls [MFC], error codes", "MFC ActiveX controls [MFC], accessing invisible dialog controls", "MFC ActiveX controls [MFC], advanced topics", "FireError method [MFC]", "MFC ActiveX controls [MFC], database classes", "MFC ActiveX controls [MFC], special keys", "PreTranslateMessage method [MFC]", "MFC ActiveX controls [MFC], parameterized property", "ThrowError method [MFC]"] -ms.assetid: e9e34abb-8e2d-461e-bb9c-a1aec5dcecbd --- # MFC ActiveX Controls: Advanced Topics +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article covers advanced topics related to developing ActiveX controls. These include: - [Using Database Classes in ActiveX Controls](#_core_using_database_classes_in_activex_controls) @@ -29,7 +31,7 @@ Because the ActiveX control classes are part of the class library, you can apply For a general overview of the MFC database classes, see [MFC Database Classes (DAO and ODBC)](../data/mfc-database-classes-odbc-and-dao.md). The article introduces both the MFC ODBC classes and the MFC DAO classes and directs you to more details on either. > [!NOTE] -> DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual C++ environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-programming.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. +> DAO is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual Studio environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-programming.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. ## Implementing a Parameterized Property diff --git a/docs/mfc/mfc-activex-controls-creating-an-automation-server.md b/docs/mfc/mfc-activex-controls-creating-an-automation-server.md index 732f948b9d1..a3a405fd699 100644 --- a/docs/mfc/mfc-activex-controls-creating-an-automation-server.md +++ b/docs/mfc/mfc-activex-controls-creating-an-automation-server.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Creating an Automation Ser title: "MFC ActiveX Controls: Creating an Automation Server" ms.date: "11/04/2016" helpviewer_keywords: ["Automation servers [MFC], MFC ActiveX controls", "ActiveX controls [MFC], Automation server", "MFC ActiveX controls [MFC], Automation server"] -ms.assetid: e0c24ed2-d61c-49ad-a4fa-4e1098d1d39b --- # MFC ActiveX Controls: Creating an Automation Server +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can develop an MFC ActiveX control as an Automation server for the purpose of programmatically embedding that control in another application and calling methods in the control from the application. Such a control would still be available to be hosted in an ActiveX control container. ### To create a control as an Automation server diff --git a/docs/mfc/mfc-activex-controls-distributing-activex-controls.md b/docs/mfc/mfc-activex-controls-distributing-activex-controls.md index a82f3d13a4c..e1a83f2a393 100644 --- a/docs/mfc/mfc-activex-controls-distributing-activex-controls.md +++ b/docs/mfc/mfc-activex-controls-distributing-activex-controls.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Distributing ActiveX Controls" ms.date: "09/12/2018" f1_keywords: ["GetWindowsDirectory", "GetSystemDirectory"] helpviewer_keywords: ["MFC ActiveX controls [MFC], ANSI or Unicode versions", "RegSvr32.exe", "MFC ActiveX controls [MFC], distributing", "distributing MFC ActiveX controls", "redistributable files, MFC ActiveX controls", "GetSystemDirectory method [MFC]", "registering ActiveX controls", "MSVCRT40.dll", "registry [MFC], registering controls", "LoadLibrary method, registering ActiveX controls", "MFC40U.DLL", "MFC40.DLL", "GetWindowsDirectory method [MFC]", "installing ActiveX controls", "GetProcAddress method, registering ActiveX controls", "MFC ActiveX controls [MFC], installing", "MFC ActiveX controls [MFC], registering", "registering controls", "OLEPRO32.DLL"] -ms.assetid: cd70ac9b-f613-4879-9e81-6381fdfda2a1 --- # MFC ActiveX Controls: Distributing ActiveX Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses several issues related to redistributing ActiveX controls: - [ANSI or Unicode Control Versions](#_core_ansi_or_unicode_control_versions) diff --git a/docs/mfc/mfc-activex-controls-events.md b/docs/mfc/mfc-activex-controls-events.md index 6a6162a9272..0861f1f6ae8 100644 --- a/docs/mfc/mfc-activex-controls-events.md +++ b/docs/mfc/mfc-activex-controls-events.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Events" title: "MFC ActiveX Controls: Events" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], events", "notifications [MFC], notifying containers of events", "custom events [MFC], adding to ActiveX controls", "events [MFC], mapping", "COleControl class [MFC], handling of events", "mappings [MFC], events", "stock events [MFC]", "container events [MFC]", "events [MFC], ActiveX controls", "OLE events [MFC]"] -ms.assetid: e1e57e0c-206b-4923-a0b5-682c26564f74 --- # MFC ActiveX Controls: Events +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + ActiveX controls use events to notify a container that something has happened to the control. Common examples of events include clicks on the control, data entered using the keyboard, and changes in the control's state. When these actions occur, the control fires an event to alert the container. Events are also called messages. diff --git a/docs/mfc/mfc-activex-controls-licensing-an-activex-control.md b/docs/mfc/mfc-activex-controls-licensing-an-activex-control.md index 45eb20a4fa8..c2241ffecc3 100644 --- a/docs/mfc/mfc-activex-controls-licensing-an-activex-control.md +++ b/docs/mfc/mfc-activex-controls-licensing-an-activex-control.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Licensing an ActiveX Contr title: "MFC ActiveX Controls: Licensing an ActiveX Control" ms.date: "11/19/2018" helpviewer_keywords: ["COleObjectFactory class [MFC], licensing controls", "MFC ActiveX controls [MFC], licensing", "VerifyLicenseKey method [MFC]", "VerifyUserLicense method [MFC]", "GetLicenseKey method [MFC]", "licensing ActiveX controls"] -ms.assetid: cacd9e45-701a-4a1f-8f1f-b0b39f6ac303 --- # MFC ActiveX Controls: Licensing an ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Licensing support, an optional feature of ActiveX controls, allows you to control who is able to use or distribute the control. (For additional discussion of licensing issues, see Licensing Issues in [Upgrading an Existing ActiveX Control](upgrading-an-existing-activex-control.md).) > [!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-localizing-an-activex-control.md b/docs/mfc/mfc-activex-controls-localizing-an-activex-control.md index 7e25d900478..b226aba58f7 100644 --- a/docs/mfc/mfc-activex-controls-localizing-an-activex-control.md +++ b/docs/mfc/mfc-activex-controls-localizing-an-activex-control.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Localizing an ActiveX Control" ms.date: "09/12/2018" f1_keywords: ["LocaleID", "AfxOleRegisterTypeLib"] helpviewer_keywords: ["localization, ActiveX controls", "MFC ActiveX controls [MFC], localizing", "LocaleID ambient property [MFC]", "LOCALIZE sample [MFC]"] -ms.assetid: a44b839a-c652-4ec5-b824-04392708a5f9 --- # MFC ActiveX Controls: Localizing an ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses procedures for localizing ActiveX control interfaces. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-methods.md b/docs/mfc/mfc-activex-controls-methods.md index a4719418053..6c38e501a25 100644 --- a/docs/mfc/mfc-activex-controls-methods.md +++ b/docs/mfc/mfc-activex-controls-methods.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Methods" title: "MFC ActiveX Controls: Methods" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], methods"] -ms.assetid: e20271de-6ffa-4ba0-848b-bafe6c9e510c --- # MFC ActiveX Controls: Methods +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An ActiveX control fires events to communicate between itself and its control container. A container can also communicate with a control by means of methods and properties. Methods are also called functions. Methods and properties provide an exported interface for use by other applications, such as Automation clients and ActiveX control containers. For more information on ActiveX control properties, see the article [MFC ActiveX Controls: Properties](mfc-activex-controls-properties.md). diff --git a/docs/mfc/mfc-activex-controls-optimization.md b/docs/mfc/mfc-activex-controls-optimization.md index a93fa67f5ef..eae4188a105 100644 --- a/docs/mfc/mfc-activex-controls-optimization.md +++ b/docs/mfc/mfc-activex-controls-optimization.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Optimization" title: "MFC ActiveX Controls: Optimization" ms.date: "09/12/2018" helpviewer_keywords: ["MFC ActiveX controls [MFC], windowless", "flicker-free ActiveX controls", "MFC ActiveX controls [MFC], mouse interaction", "device contexts, unclipped for MFC ActiveX controls", "MFC ActiveX controls [MFC], optimizing", "performance, ActiveX controls", "optimization, ActiveX controls", "MFC ActiveX controls [MFC], flicker-free", "windowless MFC ActiveX controls", "MFC ActiveX controls [MFC], active/inactive state", "optimizing performance, ActiveX controls"] -ms.assetid: 8b11f26a-190d-469b-b594-5336094a0109 --- # MFC ActiveX Controls: Optimization +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains techniques you can use to optimize your ActiveX controls for better performance. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-painting-an-activex-control.md b/docs/mfc/mfc-activex-controls-painting-an-activex-control.md index 6a5ae990337..2e850615b59 100644 --- a/docs/mfc/mfc-activex-controls-painting-an-activex-control.md +++ b/docs/mfc/mfc-activex-controls-painting-an-activex-control.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Painting an ActiveX Contro title: "MFC ActiveX Controls: Painting an ActiveX Control" ms.date: "09/12/2018" helpviewer_keywords: ["MFC ActiveX controls [MFC], painting", "MFC ActiveX controls [MFC], optimizing"] -ms.assetid: 25fff9c0-4dab-4704-aaae-8dfb1065dee3 --- # MFC ActiveX Controls: Painting an ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the ActiveX control painting process and how you can alter paint code to optimize the process. (See [Optimizing Control Drawing](optimizing-control-drawing.md) for techniques on how to optimize drawing by not having controls individually restore previously selected GDI objects. After all of the controls have been drawn, the container can automatically restore the original objects.) >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-properties.md b/docs/mfc/mfc-activex-controls-properties.md index 6779f249c19..839b34e745b 100644 --- a/docs/mfc/mfc-activex-controls-properties.md +++ b/docs/mfc/mfc-activex-controls-properties.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Properties" title: "MFC ActiveX Controls: Properties" ms.date: "11/04/2016" helpviewer_keywords: ["properties [MFC], ActiveX controls", "MFC ActiveX controls [MFC], properties", "properties [MFC]"] -ms.assetid: b678a53c-0d9e-476f-8aa0-23b80baaba46 --- # MFC ActiveX Controls: Properties +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An ActiveX control fires events to communicate with its control container. The container, in return, uses methods and properties to communicate with the control. Methods and properties are similar in use and purpose, respectively, to member functions and member variables of a C++ class. Properties are data members of the ActiveX control that are exposed to any container. Properties provide an interface for applications that contain ActiveX controls, such as Automation clients and ActiveX control containers. Properties are also called attributes. diff --git a/docs/mfc/mfc-activex-controls-property-pages.md b/docs/mfc/mfc-activex-controls-property-pages.md index 3fcbd9e8f72..e1514eb2968 100644 --- a/docs/mfc/mfc-activex-controls-property-pages.md +++ b/docs/mfc/mfc-activex-controls-property-pages.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ActiveX Controls: Property Pages" title: "MFC ActiveX Controls: Property Pages" ms.date: "11/19/2018" helpviewer_keywords: ["DDP_ functions [MFC]", "MFC ActiveX controls [MFC], properties", "property pages [MFC], MFC ActiveX controls", "DoDataExchange method [MFC]", "OLEIVERB_PROPERTIES", "CPropertyPageDialog class [MFC]", "MFC ActiveX controls [MFC], property pages"] -ms.assetid: 1506f87a-9fd6-4505-8380-0dbc9636230e --- # MFC ActiveX Controls: Property Pages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Property pages allow an ActiveX control user to view and change ActiveX control properties. These properties are accessed by invoking a control properties dialog box, which contains one or more property pages that provide a customized, graphical interface for viewing and editing the control properties. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-returning-error-codes-from-a-method.md b/docs/mfc/mfc-activex-controls-returning-error-codes-from-a-method.md index aff377276ae..7aa30785a26 100644 --- a/docs/mfc/mfc-activex-controls-returning-error-codes-from-a-method.md +++ b/docs/mfc/mfc-activex-controls-returning-error-codes-from-a-method.md @@ -3,10 +3,13 @@ description: "Learn more about: MFC ActiveX Controls: Returning Error Codes From title: "MFC ActiveX Controls: Returning Error Codes From a Method" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], error codes", "SetNotSupported method, using", "errors [MFC], ActiveX control error codes", "GetNotSupported method [MFC]", "FireError method [MFC]", "SCODE, MFC ActiveX controls", "ThrowError method [MFC]"] -ms.assetid: 771fb9c9-2413-4dcc-b386-7bc4c4adeafd +ms.topic: troubleshooting-error-codes --- # MFC ActiveX Controls: Returning Error Codes From a Method +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes how to return error codes from an ActiveX control method. To indicate that an error has occurred within a method, you should use the [COleControl::ThrowError](reference/colecontrol-class.md#throwerror) member function, which takes an SCODE (status code) as a parameter. You can use a predefined SCODE or define one of your own. diff --git a/docs/mfc/mfc-activex-controls-serializing.md b/docs/mfc/mfc-activex-controls-serializing.md index 95877d684b8..3cc9f82efc1 100644 --- a/docs/mfc/mfc-activex-controls-serializing.md +++ b/docs/mfc/mfc-activex-controls-serializing.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Serializing" ms.date: "09/12/2018" f1_keywords: ["_wVerMinor", "DoPropExchange", "_wVerMajor"] helpviewer_keywords: ["MFC ActiveX controls [MFC], version support", "wVerMinor global constant [MFC]", "GetVersion method [MFC]", "ExchangeVersion method [MFC]", "MFC ActiveX controls [MFC], serializing", "DoPropExchange method [MFC]", "versioning ActiveX controls", "wVerMajor global constant"] -ms.assetid: 9d57c290-dd8c-4853-b552-6f17f15ebedd --- # MFC ActiveX Controls: Serializing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses how to serialize an ActiveX control. Serialization is the process of reading from or writing to a persistent storage medium, such as a disk file. The Microsoft Foundation Class (MFC) Library provides built-in support for serialization in class `CObject`. `COleControl` extends this support to ActiveX controls through the use of a property exchange mechanism. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-subclassing-a-windows-control.md b/docs/mfc/mfc-activex-controls-subclassing-a-windows-control.md index 8a871b2d5f9..04ee60c3058 100644 --- a/docs/mfc/mfc-activex-controls-subclassing-a-windows-control.md +++ b/docs/mfc/mfc-activex-controls-subclassing-a-windows-control.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Subclassing a Windows Control" ms.date: "09/12/2018" f1_keywords: ["precreatewindow", "IsSubclassed"] helpviewer_keywords: ["OnDraw method, MFC ActiveX controls", "subclassing", "DoSuperclassPaint method [MFC]", "subclassing Windows controls", "subclassing, Windows controls", "reflected messages, in ActiveX controls", "PreCreateWindow method, overriding", "MFC ActiveX controls [MFC], subclassed controls", "MFC ActiveX controls [MFC], creating", "IsSubclassed method [MFC]"] -ms.assetid: 3236d4de-401f-49b7-918d-c84559ecc426 --- # MFC ActiveX Controls: Subclassing a Windows Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the process for subclassing a common Windows control to create an ActiveX control. Subclassing an existing Windows control is a quick way to develop an ActiveX control. The new control will have the abilities of the subclassed Windows control, such as painting and responding to mouse clicks. The MFC ActiveX controls sample [BUTTON](../overview/visual-cpp-samples.md) is an example of subclassing a Windows control. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-using-data-binding-in-an-activex-control.md b/docs/mfc/mfc-activex-controls-using-data-binding-in-an-activex-control.md index b979bc1a9a8..95155d02712 100644 --- a/docs/mfc/mfc-activex-controls-using-data-binding-in-an-activex-control.md +++ b/docs/mfc/mfc-activex-controls-using-data-binding-in-an-activex-control.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Using Data Binding in an ActiveX Control" ms.date: "11/19/2018" f1_keywords: ["bindable", "requestedit", "defaultbind", "displaybind", "dispid"] helpviewer_keywords: ["MFC ActiveX controls [MFC], data binding", "data binding [MFC], MFC ActiveX controls", "data-bound controls [MFC], MFC ActiveX controls", "controls [MFC], data binding", "bound controls [MFC], MFC ActiveX"] -ms.assetid: 476b590a-bf2a-498a-81b7-dd476bd346f1 --- # MFC ActiveX Controls: Using Data Binding in an ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + One of the more powerful uses of ActiveX controls is data binding, which allows a property of the control to bind with a specific field in a database. When a user modifies data in this bound property, the control notifies the database and requests that the record field be updated. The database then notifies the control of the success or failure of the request. >[!IMPORTANT] diff --git a/docs/mfc/mfc-activex-controls-using-fonts.md b/docs/mfc/mfc-activex-controls-using-fonts.md index d1db67fe5c4..1848b68f49d 100644 --- a/docs/mfc/mfc-activex-controls-using-fonts.md +++ b/docs/mfc/mfc-activex-controls-using-fonts.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If your ActiveX control displays text, you can allow the control user to change the text appearance by changing a font property. Font properties are implemented as font objects and can be one of two types: stock or custom. Stock Font properties are preimplemented font properties that you can add using the Add Property Wizard. Custom Font properties are not preimplemented and the control developer determines the property's behavior and usage. This article covers the following topics: @@ -112,7 +114,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 +217,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/mfc-activex-controls-using-pictures-in-an-activex-control.md b/docs/mfc/mfc-activex-controls-using-pictures-in-an-activex-control.md index 6703e6d5431..6f3f143caa9 100644 --- a/docs/mfc/mfc-activex-controls-using-pictures-in-an-activex-control.md +++ b/docs/mfc/mfc-activex-controls-using-pictures-in-an-activex-control.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Using Pictures in an ActiveX Control" ms.date: "11/04/2016" f1_keywords: ["LPPICTUREDISP"] helpviewer_keywords: ["OnDraw method, MFC ActiveX controls", "MFC ActiveX controls [MFC], pictures", "OnDraw method [MFC]", "OnResetState method [MFC]", "CLSID_CPicturePropPage [MFC]"] -ms.assetid: 2e49735c-21b9-4442-bb3d-c82ef258eec9 --- # MFC ActiveX Controls: Using Pictures in an ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the common Picture type and how to implement it in your ActiveX control. Topics include: - [Overview of Custom Picture Properties](#_core_overview_of_custom_picture_properties) diff --git a/docs/mfc/mfc-activex-controls-using-stock-property-pages.md b/docs/mfc/mfc-activex-controls-using-stock-property-pages.md index e9553c4cef5..0ce6947ce86 100644 --- a/docs/mfc/mfc-activex-controls-using-stock-property-pages.md +++ b/docs/mfc/mfc-activex-controls-using-stock-property-pages.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls: Using Stock Property Pages" ms.date: "09/12/2018" f1_keywords: ["CLSID_CPicturePropPage", "CLSID_CColorPropPage", "CLSID_CFontPropPage"] helpviewer_keywords: ["picture stock property pages [MFC]", "CLSID_CFontPropPage [MFC]", "color stock property pages [MFC]", "CLSID_CColorPropPage [MFC]", "fonts [MFC], ActiveX controls", "stock properties [MFC], stock property pages", "CLSID_CPicturePropPage [MFC]", "MFC ActiveX controls [MFC], property pages"] -ms.assetid: 22638d86-ff3e-4124-933e-54b7c2a25968 --- # MFC ActiveX Controls: Using Stock Property Pages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article discusses the stock property pages available for ActiveX controls and how to use them. >[!IMPORTANT] @@ -30,7 +32,7 @@ Note that the count of property pages, in the BEGIN_PROPPAGEIDS macro, is 4. Thi After these modifications have been made, rebuild your project. Your control now has property pages for the font, picture, and color properties. > [!NOTE] -> If the control stock property pages cannot be accessed, it may be because the MFC DLL (MFCxx.DLL) has not been properly registered with the current operating system. This usually results from installing Visual C++ under an operating system different from the one currently running. +> If the control stock property pages cannot be accessed, it may be because the MFC DLL (MFCxx.DLL) has not been properly registered with the current operating system. This usually results from installing Visual Studio under an operating system different from the one currently running. > [!TIP] > If your stock property pages are not visible (see previous Note), register the DLL by running RegSvr32.exe from the command line with the full path name to the DLL. diff --git a/docs/mfc/mfc-activex-controls.md b/docs/mfc/mfc-activex-controls.md index fb744cd66d4..f08cd1629c3 100644 --- a/docs/mfc/mfc-activex-controls.md +++ b/docs/mfc/mfc-activex-controls.md @@ -4,10 +4,12 @@ title: "MFC ActiveX Controls" ms.date: "11/19/2018" f1_keywords: ["MFC ActiveX Controls (MFC)"] helpviewer_keywords: ["COleControl class [MFC], MFC ActiveX controls", "ActiveX controls [MFC], MFC", "containers [MFC], MFC ActiveX controls", "MFC ActiveX controls [MFC], serializing", "MFC ActiveX controls [MFC], containers", "serialization [MFC], MFC ActiveX controls", "dispatch maps [MFC], for MFC ActiveX controls", "MFC ActiveX controls [MFC], active/inactive state", "events [MFC], ActiveX controls", "MFC ActiveX controls [MFC]"] -ms.assetid: c911fb74-3afc-4bf3-a0f5-7922b14d9a1b --- # MFC ActiveX Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An ActiveX control is a reusable software component based on the Component Object Model (COM) that supports a wide variety of OLE functionality and can be customized to fit many software needs. >[!IMPORTANT] @@ -80,7 +82,7 @@ Note that a control is not responsible for obtaining access to the storage mediu ## Installing ActiveX Control Classes and Tools -When you install Visual C++, the MFC ActiveX control classes and retail and debug ActiveX control run-time DLLs are automatically installed if ActiveX controls are selected in Setup (they are selected by default). +When you install Visual Studio, the MFC ActiveX control classes and retail and debug ActiveX control run-time DLLs are automatically installed if ActiveX controls are selected in Setup (they are selected by default). By default, the ActiveX control classes and tools are installed in the following subdirectories under \Program Files\Microsoft Visual Studio .NET: diff --git a/docs/mfc/mfc-and-atl.md b/docs/mfc/mfc-and-atl.md index d9e499ac1bd..424ca2dd106 100644 --- a/docs/mfc/mfc-and-atl.md +++ b/docs/mfc/mfc-and-atl.md @@ -2,15 +2,17 @@ description: "Learn more about: MFC and ATL" title: "MFC and ATL" ms.date: "01/24/2018" -ms.assetid: 31b1a3a8-4154-4c4a-af10-fafc23ecdc5c ms.topic: "overview" ms.custom: intro-overview --- # MFC and ATL +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library and Active Template Library (ATL) continue to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Classes (MFC) provide a C++ object-oriented wrapper over Win32 for rapid development of native desktop applications. The Active Template Library (ATL) is a wrapper library that simplifies COM development and is used extensively for creating ActiveX controls. -You can create MFC or ATL programs with Visual Studio Community Edition or higher. The Express editions do not support MFC or ATL. +You can create MFC or ATL programs with Visual Studio Community Edition or higher. The Express editions don't support MFC or ATL. In Visual Studio 2015, Visual C++ is an optional component, and MFC and ATL components are optional sub-components under Visual C++. If you do not select these components when you first install Visual Studio, you will be prompted to install them the first time you attempt to create or open an MFC or ATL project. diff --git a/docs/mfc/mfc-application-architecture-classes.md b/docs/mfc/mfc-application-architecture-classes.md index 6ec1f95b61a..197201a873d 100644 --- a/docs/mfc/mfc-application-architecture-classes.md +++ b/docs/mfc/mfc-application-architecture-classes.md @@ -6,6 +6,9 @@ helpviewer_keywords: ["MFC, classes", "MFC, application development", "classes [ --- # MFC application architecture classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class library (MFC) classes in this category contribute to the architecture of an MFC application. They supply functionality common to most applications. You fill in the framework to add application-specific functionality. Typically, you do so by deriving new classes from the architecture classes, and then adding new members or overriding existing member functions. [Application wizards](reference/mfc-application-wizard.md) generate several types of applications, all of which use the application framework in differing ways. SDI (single document interface) and MDI (multiple document interface) applications make full use of the document/view part of the framework. Other types of applications, such as dialog-based applications, form-based applications, and DLLs, use only some of document/view architecture features. diff --git a/docs/mfc/mfc-classes-for-creating-internet-client-applications.md b/docs/mfc/mfc-classes-for-creating-internet-client-applications.md index f3a6c837e05..d4d0530b4fa 100644 --- a/docs/mfc/mfc-classes-for-creating-internet-client-applications.md +++ b/docs/mfc/mfc-classes-for-creating-internet-client-applications.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC Classes for Creating Internet Client Applica title: "MFC Classes for Creating Internet Client Applications" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, WinInet classes", "WinInet classes [MFC], classes", "classes [MFC], MFC", "Internet client applications [MFC], MFC", "Internet applications [MFC], MFC"] -ms.assetid: 67d34117-9839-4f4b-8bb8-0e4a9471c606 --- # MFC Classes for Creating Internet Client Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC provides the following classes and global functions for writing Internet client applications. Indentation indicates a class is derived from the unindented class above it. `CGopherFile` and `CHttpFile` derive from `CInternetFile`, for example. These classes and global functions are declared in AFXINET.H, except `CFileFind`, which is declared in AFX.H. ## Classes diff --git a/docs/mfc/mfc-com.md b/docs/mfc/mfc-com.md index eb5282b585c..4737b866ce6 100644 --- a/docs/mfc/mfc-com.md +++ b/docs/mfc/mfc-com.md @@ -1,16 +1,18 @@ --- -description: "Learn more about: MFC COM" title: "MFC COM" -ms.date: "09/12/2018" +description: "Learn more about: MFC COM" +ms.date: 09/12/2018 f1_keywords: ["MFC COM (MFC)"] helpviewer_keywords: ["MFC, COM support", "MFC ActiveX controls [MFC], COM support in MFC", "MFC COM [MFC]", "ActiveX controls [MFC], COM object model", "Active technology [MFC]", "COM [MFC], MFC support"] -ms.assetid: 7646bdcb-3a06-4ed5-9386-9b00f3979dcb --- # MFC COM +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A subset of MFC is designed to support COM, while most of the Active Template Library (ATL) is designed for COM programming. This section of topics describes MFC's support for COM. -Active technologies (such as ActiveX controls, Active document containment, OLE, and so on) use the Component Object Model (COM) to enable software components to interact with one another in a networked environment, regardless of the language with which they were created. Active technologies can be used to create applications that run on the desktop or the Internet. For more information see [Introduction to COM](../atl/introduction-to-com.md) or [The Component Object Model](/windows/win32/com/the-component-object-model). +Active technologies (such as ActiveX controls, Active document containment, OLE, and so on) use the Component Object Model (COM) to enable software components to interact with one another in a networked environment, regardless of the language with which they were created. Active technologies can be used to create applications that run on the desktop or the Internet. For more information, see [Introduction to COM](../atl/introduction-to-com.md) or [The Component Object Model](/windows/win32/com/the-component-object-model). Active technologies include both client and server technologies, including the following: diff --git a/docs/mfc/mfc-concepts.md b/docs/mfc/mfc-concepts.md index 3ff73e4812e..3de9b5e8e42 100644 --- a/docs/mfc/mfc-concepts.md +++ b/docs/mfc/mfc-concepts.md @@ -3,9 +3,13 @@ description: "Learn more about: MFC Concepts" title: "MFC Concepts" ms.date: "01/09/2018" f1_keywords: ["Concepts"] +ms.topic: concept-article --- # MFC Concepts +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This section provides conceptual and task-based topics to help you program using the Microsoft Foundation Class (MFC) Library. ## In This Section diff --git a/docs/mfc/mfc-desktop-applications.md b/docs/mfc/mfc-desktop-applications.md index d1876d18607..73e8b385257 100644 --- a/docs/mfc/mfc-desktop-applications.md +++ b/docs/mfc/mfc-desktop-applications.md @@ -4,10 +4,12 @@ title: "MFC Desktop Applications" ms.date: "07/28/2019" f1_keywords: ["MFC"] helpviewer_keywords: ["libraries, MFC", "class libraries, MFC", "MFC, about MFC"] -ms.assetid: 7101cb18-a681-495c-8f2b-069ad20c72f7 --- # MFC Desktop Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class (MFC) Library provides an object-oriented wrapper over much of the Win32 and COM APIs. Although it can be used to create very simple desktop applications, it is most useful when you need to develop more complex user interfaces with multiple controls. You can use MFC to create applications with Office-style user interfaces. For documentation on the Windows platform itself, see [Windows documentation](/windows/index). For information on building Windows applications in C++ without MFC, see [Build desktop Windows apps using the Win32 API](/windows/win32/index). The MFC Reference covers the classes, global functions, global variables, and macros that make up the Microsoft Foundation Class Library. @@ -72,8 +74,8 @@ Provides links to classes that are shared between MFC and ATL. [MFC Samples](../overview/visual-cpp-samples.md#mfc-samples)
Provides links to samples that demonstrate how to use MFC. -[Visual C++ Libraries Reference](../standard-library/cpp-standard-library-reference.md)
-Provides links to the various libraries provided with Visual C++, including ATL, MFC, OLE DB Templates, the C run-time library, and the C++ Standard Library. +[C++ Libraries Reference](../standard-library/cpp-standard-library-reference.md)
+Provides links to the various libraries provided with Visual Studio, including ATL, MFC, OLE DB Templates, the C run-time library, and the C++ Standard Library. [Debugging in Visual Studio](/visualstudio/debugger/debugging-in-visual-studio)
Provides links to using the Visual Studio debugger to correct logic errors in your application or stored procedures. diff --git a/docs/mfc/mfc-internet-programming-basics.md b/docs/mfc/mfc-internet-programming-basics.md index 60d8a09587a..c5619509e17 100644 --- a/docs/mfc/mfc-internet-programming-basics.md +++ b/docs/mfc/mfc-internet-programming-basics.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC Internet Programming Basics" title: "MFC Internet Programming Basics" ms.date: "11/19/2018" helpviewer_keywords: ["ISAPI extensions, programming with ISAPI", "Internet applications [MFC]", "ISAPI", "ActiveX controls [MFC], Internet", "programming [MFC], Internet", "Web applications [MFC], MFC classes", "ISAPI filters [MFC], programming with ISAPI", "Internet applications [MFC], ActiveX controls", "Internet applications [MFC], writing", "Internet applications [MFC], Active technology", "Active technology [MFC]", "Internet content [MFC]", "WinInet classes [MFC]"] -ms.assetid: 6df2dfd0-6e3f-4587-9d01-2a32f00f8a6f --- # MFC Internet Programming Basics +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Microsoft provides many APIs for programming both client and server applications. Many new applications are being written for the Internet, and as technologies, browser capabilities, and security options change, new types of applications will be written. Browsers run on client computers, providing access to the World Wide Web and displaying HTML pages that contain text, graphics, ActiveX controls, and documents. Servers provide FTP, HTTP, and gopher services, and run server extension applications using CGI. Your custom application can retrieve information and provide data on the Internet. >[!IMPORTANT] diff --git a/docs/mfc/mfc-internet-programming-tasks.md b/docs/mfc/mfc-internet-programming-tasks.md index 7498fd45c93..3685e6ac8db 100644 --- a/docs/mfc/mfc-internet-programming-tasks.md +++ b/docs/mfc/mfc-internet-programming-tasks.md @@ -3,13 +3,15 @@ description: "Learn more about: MFC Internet Programming Tasks" title: "MFC Internet Programming Tasks" ms.date: "09/12/2018" helpviewer_keywords: ["Internet applications [MFC], getting started", "Internet applications [MFC], first steps"] -ms.assetid: 6377e9b8-07c4-4380-b63b-05f5a9061313 --- # MFC Internet Programming Tasks +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This section contains detailed steps for adding Internet support to your applications. Topics include how to use the MFC classes to Internet-enable your existing applications, and how to add Active document support to your existing COM component. Do you want to create a document with up-to-the-minute stock quotes, Pittsburgh's football scores, and the latest temperature in Antarctica Microsoft provides a number of technologies to help you do that over the Internet. -Active technologies include ActiveX controls (formerly OLE controls) and Active documents; WinInet for easily retrieving and saving files across the Internet; and asynchronous monikers for efficient data downloading. Visual C++ provides wizards to help you get started quickly with a starter application. For an introduction to these technologies, see [MFC Internet Programming Basics](mfc-internet-programming-basics.md) and [MFC COM](mfc-com.md). +Active technologies include ActiveX controls (formerly OLE controls) and Active documents; WinInet for easily retrieving and saving files across the Internet; and asynchronous monikers for efficient data downloading. Visual Studio provides wizards to help you get started quickly with a starter application. For an introduction to these technologies, see [MFC Internet Programming Basics](mfc-internet-programming-basics.md) and [MFC COM](mfc-com.md). Have you always wanted to FTP a file but haven't learned WinSock and network programming protocols WinInet classes encapsulate these protocols, providing you with a simple set of functions you can use to write a client application on the Internet to download files using HTTP, FTP, and gopher. You can use WinInet to search directories on your hard drive or around the world. You can transparently collect data of several different types, and present it to the user in an integrated interface. diff --git a/docs/mfc/mfc-library-versions.md b/docs/mfc/mfc-library-versions.md index bafc3f49141..e266541499b 100644 --- a/docs/mfc/mfc-library-versions.md +++ b/docs/mfc/mfc-library-versions.md @@ -6,6 +6,9 @@ helpviewer_keywords: ["class libraries [MFC], building versions", "version infor --- # MFC Library Versions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The MFC Library is available in versions that support ANSI single-byte and multibyte character set (MBCS) code, as well as versions that support Unicode (encoded as UTF-16LE, the Windows-native character set). Each MFC version is available as a static library or as a shared DLL. There is also a smaller MFC static library version that leaves out MFC controls for dialogs, for applications that are very sensitive to size and don't need those controls. The MFC libraries are available in both debug and release versions for supported architectures that include x86, x64, and ARM processors. You can create both applications (.exe files) and DLLs with any version of the MFC libraries. There is also a set of MFC libraries compiled for interfacing with managed code. The MFC shared DLLs include a version number to indicate library binary compatibility. ## Automatic linking of MFC library versions @@ -100,7 +103,7 @@ Debugger files that have the same base name and a .pdb extension are also availa The MFC shared DLLs also follow a structured naming convention. This makes it easier to know which DLL or library you should be using for which purpose. -The MFC DLLs have *version* numbers that indicate binary compatibility. Use MFC DLLs that have the same version as your other libraries and compiler toolset to guarantee compatibility within a project. +The MFC DLLs have *version* numbers that indicate binary compatibility. Use MFC DLLs that have the same version as your other libraries and compiler build tools to guarantee compatibility within a project. |DLL|Description| |---------|-----------------| diff --git a/docs/mfc/mfc-mbcs-dll-add-on.md b/docs/mfc/mfc-mbcs-dll-add-on.md index 154e05d42f4..9a8b5621b3c 100644 --- a/docs/mfc/mfc-mbcs-dll-add-on.md +++ b/docs/mfc/mfc-mbcs-dll-add-on.md @@ -6,11 +6,14 @@ helpviewer_keywords: ["MBCS", "MFC"] --- # MFC MBCS DLL Add-on +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Support for MFC and its multibyte character set (MBCS) libraries requires an additional step during Visual Studio installation in Visual Studio 2013 and later. **Visual Studio 2013**: By default, the MFC libraries installed in Visual Studio 2013 only support Unicode development. You need the MBCS DLLs in order to build an MFC project in Visual Studio 2013 that has the **Character Set** property set to **Use Multi-Byte Character Set** or **Not Set**. Download the DLL at [Multibyte MFC Library for Visual Studio 2013](https://www.microsoft.com/download/details.aspx?id=40770). -**Visual Studio 2015**: Both Unicode and MBCS MFC DLLs are included in the Visual C++ setup components, but support for MFC is not installed by default. Visual C++ and MFC are optional install configurations in Visual Studio setup. To make sure that MFC is installed, choose **Custom** in setup, and under **Programming Languages**, make sure that **Visual C++** and **Microsoft Foundation Classes for C++** are selected. If you have already installed Visual Studio, you will be prompted to install Visual C++ and/or MFC when you attempt to create an MFC project. +**Visual Studio 2015**: Both Unicode and MBCS MFC DLLs are included in the Visual C++ setup components, but support for MFC is not installed by default. Visual C++ and MFC are optional install configurations in Visual Studio setup. To make sure that MFC is installed, choose **Custom** in setup, and under **Programming Languages**, make sure that **Visual C++** and ****Microsoft Foundation Classes for C++** are selected. If you have already installed Visual Studio, you will be prompted to install Visual C++ and/or MFC when you attempt to create an MFC project. **Visual Studio 2017 and later**: The Unicode and MBCS MFC DLLs are installed with the **Desktop development with C++** workload when you select **MFC and ATL support** from the **Optional Components** pane in the Visual Studio Installer program. If your installation does not include these components, navigate to the **File | New Projects** dialog and click the **Open Visual Studio Installer** link. For more information, see [Install Visual Studio](/visualstudio/install/install-visual-studio). diff --git a/docs/mfc/mfc-technical-notes.md b/docs/mfc/mfc-technical-notes.md index f11bc35414a..57d42e99c87 100644 --- a/docs/mfc/mfc-technical-notes.md +++ b/docs/mfc/mfc-technical-notes.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC Technical Notes" title: "MFC Technical Notes" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, technical notes", "technical notes, MFC", "technical notes [MFC]"] -ms.assetid: 8aa01d66-0b07-4d0a-a080-4bb00c7baaac --- # MFC Technical Notes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A technical note is a document written for programmers by programmers. Each technical note describes a problem or feature that is beyond the scope of the rest of the MFC documentation. The technical notes supplied reflect requests for information from users, as well as specialized information that the MFC developers anticipate advanced users will want. diff --git a/docs/mfc/mfc-toolbar-implementation.md b/docs/mfc/mfc-toolbar-implementation.md index 696dfdd3cd3..a97b5840b3c 100644 --- a/docs/mfc/mfc-toolbar-implementation.md +++ b/docs/mfc/mfc-toolbar-implementation.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC Toolbar Implementation" title: "MFC Toolbar Implementation" ms.date: "11/04/2016" helpviewer_keywords: ["toolbars [MFC], creating", "buttons [MFC], MFC toolbars", "toolbars [MFC], docking", "CToolBar class [MFC], creating toolbars", "MFC toolbars", "floating toolbars [MFC]", "toolbars [MFC], floating", "docking toolbars [MFC]", "bitmaps [MFC], toolbar", "toolbar controls [MFC]", "CToolBarCtrl class [MFC], implementing toolbars", "tool tips [MFC], enabling", "toolbars [MFC]", "toolbars [MFC], implementing MFC toolbars"] -ms.assetid: af3319ad-c430-4f90-8361-e6a2c06fd084 --- # MFC Toolbar Implementation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar is a [control bar](control-bars.md) that contains the bitmap images of controls. These images can behave like pushbuttons, check boxes, or radio buttons. MFC supplies class [CToolbar](reference/ctoolbar-class.md) to manage toolbars. If you enable it, users of MFC toolbars can dock them to the edge of a window or "float" them anywhere within the application window. MFC doesn't support customizable toolbars like those in the development environment. @@ -69,7 +71,7 @@ Also see the MFC General sample [DOCKTOOL](../overview/visual-cpp-samples.md). ## The Toolbar Bitmap -Once constructed, a `CToolBar` object creates the toolbar image by loading a single bitmap that contains one image for each button. The Application Wizard creates a standard toolbar bitmap that you can customize with the Visual C++ [toolbar editor](../windows/toolbar-editor.md). +Once constructed, a `CToolBar` object creates the toolbar image by loading a single bitmap that contains one image for each button. The Application Wizard creates a standard toolbar bitmap that you can customize with the Visual Studio [toolbar editor](../windows/toolbar-editor.md). ### What do you want to know more about diff --git a/docs/mfc/modal-and-modeless-dialog-boxes.md b/docs/mfc/modal-and-modeless-dialog-boxes.md index 018ff95a740..c939871ca9d 100644 --- a/docs/mfc/modal-and-modeless-dialog-boxes.md +++ b/docs/mfc/modal-and-modeless-dialog-boxes.md @@ -3,10 +3,12 @@ description: "Learn more about: Modal and Modeless Dialog Boxes" title: "Modal and Modeless Dialog Boxes" ms.date: "11/04/2016" helpviewer_keywords: ["MFC dialog boxes [MFC], modeless", "modeless dialog boxes [MFC]", "MFC dialog boxes [MFC], modal", "modal dialog boxes [MFC]"] -ms.assetid: e83df336-5994-4b8f-8233-7942f997315b --- # Modal and Modeless Dialog Boxes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use class [CDialog](reference/cdialog-class.md) to manage two kinds of dialog boxes: - *Modal dialog boxes*, which require the user to respond before continuing the program diff --git a/docs/mfc/month-calendar-control-examples.md b/docs/mfc/month-calendar-control-examples.md index 3881ae480f1..8085cecad97 100644 --- a/docs/mfc/month-calendar-control-examples.md +++ b/docs/mfc/month-calendar-control-examples.md @@ -3,10 +3,12 @@ description: "Learn more about: Month Calendar Control Examples" title: "Month Calendar Control Examples" ms.date: "11/04/2016" helpviewer_keywords: ["month calendar controls [MFC], examples", "CMonthCalCtrl class [MFC], examples"] -ms.assetid: 1af7fb59-d6fd-46e0-aaa5-b0394a0a3ed5 --- # Month Calendar Control Examples +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CMNCTRL1](../overview/visual-cpp-samples.md) sample application demonstrates the various attributes of the `CMonthCalCtrl` class. The control, found on a separate tab in the sample, demonstrates basic functionality and allows the user to dynamically modify certain attributes. ## See also diff --git a/docs/mfc/multipage-documents.md b/docs/mfc/multipage-documents.md index 664450ef076..4953a61ee3a 100644 --- a/docs/mfc/multipage-documents.md +++ b/docs/mfc/multipage-documents.md @@ -3,10 +3,12 @@ description: "Learn more about: Multipage Documents" title: "Multipage Documents" ms.date: "11/19/2018" helpviewer_keywords: ["pagination [MFC]", "overriding [MFC], View class functions for printing", "OnPrepareDC method [MFC]", "CPrintInfo structure [MFC], multipage documents", "OnEndPrinting method [MFC]", "protocols [MFC], printing protocol", "document pages vs. printer pages [MFC]", "printer mode [MFC]", "printing [MFC], multipage documents", "printers [MFC], printer mode", "documents [MFC], printing", "OnPreparePrinting method [MFC]", "OnPrint method [MFC]", "DoPreparePrinting method and pagination [MFC]", "OnDraw method [MFC], printing", "pagination [MFC], printing multipage documents", "printing [MFC], protocol", "pages [MFC], printing", "OnBeginPrinting method [MFC]", "multipage documents [MFC]", "printing [MFC], pagination", "documents [MFC], paginating"] -ms.assetid: 69626b86-73ac-4b74-b126-9955034835ef --- # Multipage Documents +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the Windows printing protocol and explains how to print documents that contain more than one page. The article covers the following topics: - [Printing protocol](#_core_the_printing_protocol) diff --git a/docs/mfc/multiple-document-types-views-and-frame-windows.md b/docs/mfc/multiple-document-types-views-and-frame-windows.md index f24bb3620a6..cb992a563d4 100644 --- a/docs/mfc/multiple-document-types-views-and-frame-windows.md +++ b/docs/mfc/multiple-document-types-views-and-frame-windows.md @@ -3,10 +3,12 @@ description: "Learn more about: Multiple Document Types, Views, and Frame Window title: "Multiple Document Types, Views, and Frame Windows" ms.date: "11/19/2018" helpviewer_keywords: ["static splitter windows [MFC]", "multiple views [MFC]", "multiple document types [MFC]", "multiple views [MFC], frame windows", "document classes [MFC], multiple", "documents [MFC], multiple types of", "splitter windows [MFC], dynamic", "dynamic splitter windows [MFC]", "windows [MFC], dynamic splitter", "windows [MFC], static splitter", "multiple frame windows [MFC]", "splitter windows [MFC], static"] -ms.assetid: c6b9e4e0-7c9c-45f1-a804-aeac39c9a128 --- # Multiple Document Types, Views, and Frame Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The standard relationship among a document, its view, and its frame window is described in [Document/View Creation](document-view-creation.md). Many applications support a single document type (but possibly multiple open documents of that type) with a single view on the document and only one frame window per document. But some applications may need to alter one or more of those defaults. ## What do you want to know more about @@ -64,7 +66,7 @@ In a splitter window, the window is, or can be, split into two or more scrollabl Dynamic splitter windows, with views of the same class, allow the user to split a window into multiple panes at will and then scroll different panes to see different parts of the document. The user can also unsplit the window to remove the additional views. The splitter windows added to the [Scribble sample](../overview/visual-cpp-samples.md) are an example. That topic describes the technique for creating dynamic splitter windows. A dynamic splitter window is shown in part b of the figure Multiple-View User Interfaces. -Static splitter windows, with views of different classes, start with the window split into multiple panes, each with a different purpose. For example, in the Visual C++ bitmap editor, the image window shows two panes side by side. The left-hand pane displays a life-sized image of the bitmap. The right-hand pane displays a zoomed or magnified image of the same bitmap. The panes are separated by a "splitter bar" that the user can drag to change the relative sizes of the panes. A static splitter window is shown in part c of the figure Multiple-View User Interfaces. +Static splitter windows, with views of different classes, start with the window split into multiple panes, each with a different purpose. For example, in the Visual Studio bitmap editor, the image window shows two panes side by side. The left-hand pane displays a life-sized image of the bitmap. The right-hand pane displays a zoomed or magnified image of the same bitmap. The panes are separated by a "splitter bar" that the user can drag to change the relative sizes of the panes. A static splitter window is shown in part c of the figure Multiple-View User Interfaces. For more information, see class [CSplitterWnd](reference/csplitterwnd-class.md) in the *MFC Reference* and [MFC Samples](../overview/visual-cpp-samples.md#mfc-samples). diff --git a/docs/mfc/notifications-from-a-rich-edit-control.md b/docs/mfc/notifications-from-a-rich-edit-control.md index a7478300fc8..f5278d8e970 100644 --- a/docs/mfc/notifications-from-a-rich-edit-control.md +++ b/docs/mfc/notifications-from-a-rich-edit-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Notifications from a Rich Edit Control" title: "Notifications from a Rich Edit Control" ms.date: "11/04/2016" helpviewer_keywords: ["messages [MFC], notification [MFC]", "CRichEditCtrl class [MFC], notifications", "rich edit controls [MFC], notifications", "notifications [MFC], from CRichEditCtrl"] -ms.assetid: eb5304fe-f4f3-4557-9ebf-3095dea383c4 --- # Notifications from a Rich Edit Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Notification messages report events affecting a rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)). They can be processed by the parent window or, using message reflection, by the rich edit control itself. Rich edit controls support all of the notification messages used with edit controls as well as several additional ones. You can determine which notification messages a rich edit control sends its parent window by setting its "event mask." To set the event mask for a rich edit control, use the [SetEventMask](reference/cricheditctrl-class.md#seteventmask) member function. You can retrieve the current event mask for a rich edit control by using the [GetEventMask](reference/cricheditctrl-class.md#geteventmask) member function. diff --git a/docs/mfc/notifications-sent-by-animation-controls.md b/docs/mfc/notifications-sent-by-animation-controls.md index a6881465bd3..e900b18a8d9 100644 --- a/docs/mfc/notifications-sent-by-animation-controls.md +++ b/docs/mfc/notifications-sent-by-animation-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Notifications Sent by Animation Controls" title: "Notifications Sent by Animation Controls" ms.date: "11/04/2016" helpviewer_keywords: ["notifications [MFC], animation controls", "CAnimateCtrl class [MFC], notifications", "controls [MFC], animation", "animation controls [MFC], notifications"] -ms.assetid: 584f5824-446b-4a1a-85f7-ef61842c8186 --- # Notifications Sent by Animation Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An animation control ([CAnimateCtrl](reference/canimatectrl-class.md)) sends two different types of notification messages. The notifications are sent in the form of [WM_COMMAND](/windows/win32/menurc/wm-command) messages. The [ACN_START](/windows/win32/Controls/acn-start) message is sent when the animation control has started playing a clip. The [ACN_STOP](/windows/win32/Controls/acn-stop) message is sent when the animation control has finished or stopped playing a clip. diff --git a/docs/mfc/odbc-classes.md b/docs/mfc/odbc-classes.md index c2df2b212e5..d0a77096e4a 100644 --- a/docs/mfc/odbc-classes.md +++ b/docs/mfc/odbc-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: ODBC Classes" title: "ODBC Classes" ms.date: "11/04/2016" helpviewer_keywords: ["database classes [MFC], ODBC", "ODBC classes [MFC]"] -ms.assetid: 6c40fca8-3033-4873-9abe-7f51725de0e0 --- # ODBC Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes work with the other application framework classes to give easy access to a wide variety of databases for which Open Database Connectivity (ODBC) drivers are available. Programs that use ODBC databases will have at least a `CDatabase` object and a `CRecordset` object. diff --git a/docs/mfc/ole-automation-classes.md b/docs/mfc/ole-automation-classes.md index 7422cd998f9..e2d74d8d030 100644 --- a/docs/mfc/ole-automation-classes.md +++ b/docs/mfc/ole-automation-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Automation Classes" title: "OLE Automation Classes" ms.date: "11/04/2016" helpviewer_keywords: ["Automation, classes", "Automation classes [MFC], OLE classes", "OLE Automation [MFC], classes", "Automation classes [MFC]", "OLE Automation [MFC]"] -ms.assetid: 96e5372b-ff8a-4da1-933b-4d9bbf4dceb3 --- # OLE Automation Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes support automation clients (applications that control other applications). Automation servers (applications that can be controlled by other applications) are supported through [dispatch maps](reference/dispatch-maps.md). [COleDispatchDriver](reference/coledispatchdriver-class.md)
diff --git a/docs/mfc/ole-background-containers-and-servers.md b/docs/mfc/ole-background-containers-and-servers.md index 298221f6c60..b9cc3c392e8 100644 --- a/docs/mfc/ole-background-containers-and-servers.md +++ b/docs/mfc/ole-background-containers-and-servers.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Background: Containers and Servers" title: "OLE Background: Containers and Servers" ms.date: "11/04/2016" helpviewer_keywords: ["OLE full-server applications [MFC]", "server applications [MFC], communication with containers", "full-server [MFC]", "server applications [MFC], requirements", "server applications [MFC], defined", "OLE server applications [MFC], about server applications", "server applications [MFC], full-server vs. mini-server", "OLE server applications [MFC], mini-server applications", "OLE containers [MFC], container applications", "containers [MFC], OLE container applications", "server applications [MFC]"] -ms.assetid: dafbb31d-096c-4654-b774-12900d832919 --- # OLE Background: Containers and Servers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A container application is an application that can incorporate embedded or linked items into its own documents. The documents managed by a container application must be able to store and display OLE document components as well as the data created by the application itself. A container application must also allow users to insert new items or edit existing items by activating server applications when necessary. The user-interface requirements of a container application are listed in the article [Containers: User-Interface Issues](containers-user-interface-issues.md). A server application or component application is an application that can create OLE document components for use by container applications. Server applications usually support drag and drop or copying their data to the Clipboard so that a container application can insert the data as an embedded or linked item. An application can be both a container and a server. diff --git a/docs/mfc/ole-background-implementation-strategies.md b/docs/mfc/ole-background-implementation-strategies.md index e23b0f862da..57fe6adffab 100644 --- a/docs/mfc/ole-background-implementation-strategies.md +++ b/docs/mfc/ole-background-implementation-strategies.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Background: Implementation Strategies" title: "OLE Background: Implementation Strategies" ms.date: "11/04/2016" helpviewer_keywords: ["OLE [MFC], development strategy", "OLE applications [MFC], implementing OLE", "applications [OLE], implementing OLE"] -ms.assetid: 0875ddae-99df-488c-82c6-164074a81058 --- # OLE Background: Implementation Strategies +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Depending on your application, there are four possible implementation strategies for adding OLE support: - You are writing a new application. diff --git a/docs/mfc/ole-background-linking-and-embedding.md b/docs/mfc/ole-background-linking-and-embedding.md index 78b8429ce8e..d39790a77ee 100644 --- a/docs/mfc/ole-background-linking-and-embedding.md +++ b/docs/mfc/ole-background-linking-and-embedding.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Background: Linking and Embedding" title: "OLE Background: Linking and Embedding" ms.date: "11/04/2016" helpviewer_keywords: ["OLE embedded items [MFC]", "item types [MFC], defined", "item types [MFC]", "OLE [MFC], linked items", "linked items (OLE) [MFC]", "embedded objects [MFC]", "OLE items [MFC], types"] -ms.assetid: 11107711-eb96-4099-8f5c-7910bb3ecb75 --- # OLE Background: Linking and Embedding +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Using the Paste command in a container application can create an embedded component, or embedded item. The source data for an embedded item is stored as part of the OLE document that contains it. In this way, a document file for a word processor document can contain text and also can contain bitmaps, graphs, formulas, or any other type of data. OLE provides another way to incorporate data from another application: creating a linked component, or linked item, or a link. The steps for creating a linked item are similar to those for creating an embedded item, except that you use the Paste Link command instead of the Paste command. Unlike an embedded component, a linked component stores a path to the original data, which is often in a separate file. diff --git a/docs/mfc/ole-background-mfc-implementation.md b/docs/mfc/ole-background-mfc-implementation.md index 0076752ca40..5f1bce62a1e 100644 --- a/docs/mfc/ole-background-mfc-implementation.md +++ b/docs/mfc/ole-background-mfc-implementation.md @@ -4,10 +4,12 @@ title: "OLE Background: MFC Implementation" ms.date: "11/04/2016" f1_keywords: ["IMarshall", "IMoniker"] helpviewer_keywords: ["MFC libraries, implementing", "OLE MFC library implementation", "OLE IMarshal interface", "IMoniker interface, MFC", "IMarshall class [MFC]", "OLE, compound files", "OLE IMoniker interface", "OLE IUnknown"] -ms.assetid: 2b67016a-d78e-4d60-925f-c28ec8fb6180 --- # OLE Background: MFC Implementation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Because of the size and complexity of the raw OLE API, calling it directly to write OLE applications can be very time consuming. The goal of the Microsoft Foundation Class Library implementation of OLE is to reduce the amount of work you have to do to write full-featured, OLE-capable applications. This article explains the parts of the OLE API that have not been implemented inside MFC. The discussion also explains how what is implemented maps to the OLE section of the Windows SDK. diff --git a/docs/mfc/ole-background.md b/docs/mfc/ole-background.md index 859cbbf19a2..86be5ffa153 100644 --- a/docs/mfc/ole-background.md +++ b/docs/mfc/ole-background.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Background" title: "OLE Background" ms.date: "11/04/2016" helpviewer_keywords: ["OLE, about OLE"] -ms.assetid: 5f654eb5-66b1-40c9-9215-bb85356a67f8 --- # OLE Background +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + OLE is a mechanism that allows users to create and edit documents containing items or "objects" created by multiple applications. > [!NOTE] @@ -61,7 +63,7 @@ Some of the more important OLE topics are covered in the following articles: - [OLE Background: MFC Implementation](ole-background-mfc-implementation.md) -For general OLE information not found in the above articles, [search for OLE](/search/?terms=ole) in Microsoft Docs. +For general OLE information not found in the articles listed, [search for OLE](/search/?terms=ole) . ## See also diff --git a/docs/mfc/ole-classes.md b/docs/mfc/ole-classes.md index 78d380ba5cc..77233aff1ca 100644 --- a/docs/mfc/ole-classes.md +++ b/docs/mfc/ole-classes.md @@ -4,10 +4,12 @@ title: "OLE Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.ole"] helpviewer_keywords: ["ActiveX classes [MFC]", "classes [MFC], OLE", "OLE classes [MFC]", "OLE [MFC], classes"] -ms.assetid: 4c2b2bca-fafb-4d2d-8498-9ed1e04011d2 --- # OLE Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The OLE classes work with the other application framework classes to provide easy access to the ActiveX API, giving your programs an easy way to provide the power of ActiveX to your users. Using ActiveX, you can: - Create compound documents, which allow users to create and edit documents containing data created by multiple applications, including text, graphics, spreadsheets, sound, or other types of data. diff --git a/docs/mfc/ole-common-dialog-classes.md b/docs/mfc/ole-common-dialog-classes.md index 3c51dfb89b5..da438438f5b 100644 --- a/docs/mfc/ole-common-dialog-classes.md +++ b/docs/mfc/ole-common-dialog-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Common Dialog Classes" title: "OLE Common Dialog Classes" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX classes [MFC]", "dialog classes [MFC], OLE", "OLE common dialog classes [MFC]", "common dialog classes [MFC]"] -ms.assetid: 706526ae-f94f-4909-a0f8-6b5fe954fd97 --- # OLE Common Dialog Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes handle common OLE tasks by implementing a number of standard OLE dialog boxes. They also provide a consistent user interface for OLE functionality. [COleDialog](reference/coledialog-class.md)
diff --git a/docs/mfc/ole-container-classes.md b/docs/mfc/ole-container-classes.md index 7a9ad84150c..f5186d11cf6 100644 --- a/docs/mfc/ole-container-classes.md +++ b/docs/mfc/ole-container-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Container Classes" title: "OLE Container Classes" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX classes [MFC]", "container classes [MFC]", "OLE classes [MFC]", "visual editing [MFC], classes", "OLE [MFC], classes", "containers [MFC], OLE container applications"] -ms.assetid: 1e27e1ab-4c22-41eb-8547-6915c72668ae --- # OLE Container Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes are used by container applications. Both `COleLinkingDoc` and `COleDocument` manage collections of `COleClientItem` objects. Rather than deriving your document class from `CDocument`, you'll derive it from `COleLinkingDoc` or `COleDocument`, depending on whether you want support for links to objects embedded in your document. Use a `COleClientItem` object to represent each OLE item in your document that is embedded from another document or is a link to another document. diff --git a/docs/mfc/ole-control-classes.md b/docs/mfc/ole-control-classes.md index 3d29bc98e80..a527fc6d11b 100644 --- a/docs/mfc/ole-control-classes.md +++ b/docs/mfc/ole-control-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Control Classes" title: "OLE Control Classes" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX classes [MFC]", "custom controls [MFC], classes", "ActiveX controls [MFC], OLE control classes", "ActiveX control classes [MFC]", "OLE controls [MFC], classes", "OLE control classes [MFC]", "reusable component classes [MFC]"] -ms.assetid: 96495ec3-319e-4163-b839-1af0428ed9dd --- # OLE Control Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These are the primary classes you use when writing OLE controls. The `COleControlModule` class in an OLE control module is like the [CWinApp](reference/cwinapp-class.md) class in an application. Each module implements one or more OLE controls; these controls are represented by `COleControl` objects. These controls communicate with their containers using `CConnectionPoint` objects. The `CPictureHolder` and `CFontHolder` classes encapsulate COM interfaces for pictures and fonts, while the `COlePropertyPage` and `CPropExchange` classes help you implement property pages and property persistence for your control. diff --git a/docs/mfc/ole-db-classes.md b/docs/mfc/ole-db-classes.md index 64191ae0fc7..03b1ec49670 100644 --- a/docs/mfc/ole-db-classes.md +++ b/docs/mfc/ole-db-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE DB Classes" title: "OLE DB Classes" ms.date: "11/04/2016" helpviewer_keywords: ["OLE DB consumers, support", "COleDBRecordView class [MFC]"] -ms.assetid: 65245d26-8743-4efd-9a72-90e19aef3c3a --- # OLE DB Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The OLE DB support in MFC currently consists of the class [COLEDBRecordView](reference/coledbrecordview-class.md). `COleDBRecordView` displays database records in controls, through a form view directly connected to a [CRowset](../data/oledb/crowset-class.md) object. For more information about the OLE DB consumer templates, see [List of OLE DB Consumer Templates](../data/oledb/ole-db-consumer-templates-reference.md). ## See also diff --git a/docs/mfc/ole-drag-and-drop-and-data-transfer-classes.md b/docs/mfc/ole-drag-and-drop-and-data-transfer-classes.md index ae1305da27a..ef61be8434f 100644 --- a/docs/mfc/ole-drag-and-drop-and-data-transfer-classes.md +++ b/docs/mfc/ole-drag-and-drop-and-data-transfer-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Drag-and-Drop and Data Transfer Classes" title: "OLE Drag-and-Drop and Data Transfer Classes" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX classes [MFC]", "OLE drag and drop [MFC], and data transfer classes", "drag and drop [MFC], classes", "data transfer [MFC], OLE", "data transfer classes [MFC]"] -ms.assetid: c8ab2825-ed69-4b88-8ae6-f368b94726b8 --- # OLE Drag-and-Drop and Data Transfer Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes are used in OLE data transfers. They allow data to be transferred between applications by using the Clipboard or through drag and drop. [COleDropSource](reference/coledropsource-class.md)
diff --git a/docs/mfc/ole-in-mfc.md b/docs/mfc/ole-in-mfc.md index 537e4c14f83..d347fe7617b 100644 --- a/docs/mfc/ole-in-mfc.md +++ b/docs/mfc/ole-in-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE in MFC" title: "OLE in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, OLE and", "OLE items", "OLE applications [MFC], about OLE", "OLE [MFC]", "OLE containers [MFC], about OLE", "applications [OLE], about OLE", "OLE component object model (COM)"] -ms.assetid: 5193479d-1239-4697-aea4-e82f92c707ab --- # OLE in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These articles explain the fundamentals of OLE programming using MFC. MFC provides the easiest way to write programs that use OLE: - To use OLE visual editing (in-place activation). diff --git a/docs/mfc/ole-mfc.md b/docs/mfc/ole-mfc.md index 263a4d2b59e..1eaa373f3dc 100644 --- a/docs/mfc/ole-mfc.md +++ b/docs/mfc/ole-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE (MFC)" title: "OLE (MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["OLE [MFC], user-interface topics", "OLE applications [MFC], user interface", "user interfaces, OLE", "applications [OLE], user interface"] -ms.assetid: 61cb5d3e-1108-4e9b-b301-a8d8fcc586cb --- # OLE (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implementing OLE functionality in your program affects your user interface in several ways: - Visual editing (in-place activation) displays the user interface of another program in your program's windows and modifies your program's menus with items from the other program. diff --git a/docs/mfc/ole-related-classes.md b/docs/mfc/ole-related-classes.md index d8b67b66a5e..e2cd7c17f1c 100644 --- a/docs/mfc/ole-related-classes.md +++ b/docs/mfc/ole-related-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE-Related Classes" title: "OLE-Related Classes" ms.date: "11/04/2016" helpviewer_keywords: ["ActiveX classes [MFC]", "OLE classes [MFC]", "OLE [MFC], classes"] -ms.assetid: 2135cf54-1d9d-4e0e-91b4-943b3440effa --- # OLE-Related Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes provide a number of different services, ranging from exceptions to file input and output. [COleObjectFactory](reference/coleobjectfactory-class.md)
diff --git a/docs/mfc/ole-server-classes.md b/docs/mfc/ole-server-classes.md index bb867adb855..01e1a9e5862 100644 --- a/docs/mfc/ole-server-classes.md +++ b/docs/mfc/ole-server-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: OLE Server Classes" title: "OLE Server Classes" ms.date: "11/04/2016" helpviewer_keywords: ["OLE server applications [MFC], server classes", "OLE server documents", "COM components, classes [MFC]", "component classes [MFC]"] -ms.assetid: 8e9b67a2-c0ff-479c-a8d6-19b36c5e6fc6 --- # OLE Server Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes are used by server applications. Server documents are derived from `COleServerDoc` rather than from `CDocument`. Note that because `COleServerDoc` is derived from `COleLinkingDoc`, server documents can also be containers that support linking. The `COleServerItem` class represents a document or portion of a document that can be embedded in another document or linked to. diff --git a/docs/mfc/on-update-command-ui-macro.md b/docs/mfc/on-update-command-ui-macro.md index b5eb0ecd791..0bc1fcfc69f 100644 --- a/docs/mfc/on-update-command-ui-macro.md +++ b/docs/mfc/on-update-command-ui-macro.md @@ -4,10 +4,13 @@ title: "ON_UPDATE_COMMAND_UI Macro" ms.date: "09/06/2019" f1_keywords: ["ON_UPDATE_COMMAND_UI"] helpviewer_keywords: ["ON_UPDATE_COMMAND_UI macro [MFC]", "update handlers [MFC]", "command-handler macros", "updating user-interface objects [MFC]"] -ms.assetid: 3e72b50f-4119-4c82-81cf-6e09b132de05 +ms.topic: reference --- # ON_UPDATE_COMMAND_UI Macro +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To connect a user-interface object to a command-update handler in a command-target object, open **Class View**, then right-click on the class to which the handler will be added, and choose **Class Wizard**. Find the user-interface object's ID in the list on the left, then choose **UPDATE_COMMAND_UI** in the right pane and click **Add Handler**. This creates a handler function in the class and adds the appropriate entry in the message map. See [Mapping Messages to Functions](reference/mapping-messages-to-functions.md) for more information. You can specify additional messages to handle in the **Messages** pane. For example, to update a Clear All command in your program's Edit menu, use the **Class Wizard** to add a message-map entry in the selected class, a function declaration for a command-update handler called `OnUpdateEditClearAll` in the class declaration, and an empty function template in the class's implementation file. The function prototype looks like this: diff --git a/docs/mfc/oncmdmsg-handler.md b/docs/mfc/oncmdmsg-handler.md index 86b362ec27e..b40687263d1 100644 --- a/docs/mfc/oncmdmsg-handler.md +++ b/docs/mfc/oncmdmsg-handler.md @@ -4,10 +4,12 @@ title: "OnCmdMsg Handler" ms.date: "11/04/2016" f1_keywords: ["OnCmdMsg"] helpviewer_keywords: ["messages, routing", "handlers [MFC]", "command routing [MFC], OnCmdMsg handler", "handlers, OnCmdMessage [MFC]", "OnCmdMessage method [MFC]"] -ms.assetid: 8df07024-506f-47e7-bba9-1c3bc5ad8ab6 --- # OnCmdMsg Handler +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To accomplish the routing of commands, each command target calls the `OnCmdMsg` member function of the next command target in the sequence. Command targets use `OnCmdMsg` to determine whether they can handle a command and to route it to another command target if they cannot handle it. Each command-target class may override the `OnCmdMsg` member function. The overrides let each class route commands to a particular next target. A frame window, for example, always routes commands to its current child window or view, as shown in the table [Standard Command Route](command-routing.md). diff --git a/docs/mfc/one-stage-and-two-stage-construction-of-objects.md b/docs/mfc/one-stage-and-two-stage-construction-of-objects.md index 7afd60556d4..b1b0ad5b6dd 100644 --- a/docs/mfc/one-stage-and-two-stage-construction-of-objects.md +++ b/docs/mfc/one-stage-and-two-stage-construction-of-objects.md @@ -3,10 +3,12 @@ description: "Learn more about: One-Stage and Two-Stage Construction of Objects" title: "One-Stage and Two-Stage Construction of Objects" ms.date: "11/04/2016" helpviewer_keywords: ["objects [MFC], creating graphic objects", "object creation [MFC], graphic objects", "objects [MFC], graphic objects", "one-stage and two-stage construction of objects [MFC]"] -ms.assetid: 5a1c410c-4a4b-4dd9-a2ec-ced831aa7f21 --- # One-Stage and Two-Stage Construction of Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You have a choice between two techniques for creating graphic objects, such as pens and brushes: - *One-stage construction*: Construct and initialize the object in one stage, all with the constructor. diff --git a/docs/mfc/onidle-member-function.md b/docs/mfc/onidle-member-function.md index 2c69006b57c..8f81ef6c73a 100644 --- a/docs/mfc/onidle-member-function.md +++ b/docs/mfc/onidle-member-function.md @@ -4,10 +4,12 @@ title: "OnIdle Member Function" ms.date: "11/19/2018" f1_keywords: ["OnIdle"] helpviewer_keywords: ["processing messages [MFC]", "OnIdle method [MFC]", "idle loop processing [MFC]", "CWinApp class [MFC], OnIdle method [MFC]", "message handling [MFC], OnIdle method [MFC]"] -ms.assetid: 51adc874-0075-4f76-be1c-79283f46c10b --- # OnIdle Member Function +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When no Windows messages are being processed, the framework calls the [CWinApp](reference/cwinapp-class.md) member function [OnIdle](reference/cwinapp-class.md#onidle) (described in the MFC Library Reference). Override `OnIdle` to perform background tasks. The default version updates the state of user-interface objects such as toolbar buttons and performs cleanup of temporary objects created by the framework in the course of its operations. The following figure illustrates how the message loop calls `OnIdle` when there are no messages in the queue. diff --git a/docs/mfc/opening-files.md b/docs/mfc/opening-files.md index c758c1bb9c6..364e80e69c4 100644 --- a/docs/mfc/opening-files.md +++ b/docs/mfc/opening-files.md @@ -3,10 +3,13 @@ description: "Learn more about: Opening Files" title: "Opening Files" ms.date: "11/04/2016" helpviewer_keywords: ["Open member functions [MFC]", "CFile class [MFC], variable", "opening files, in MFC", "Open calls [MFC]", "Open method, CFile class [MFC]", "examples [MFC], opening files", "opening files, handling exceptions", "exception handling [MFC], when opening files", "files [MFC], opening", "file objects [MFC]", "MFC, file operations", "opening files [MFC]", "exception handling [MFC], opening files"] -ms.assetid: a991b8ec-b04a-4766-b47e-7485b5dd0b01 +ms.topic: how-to --- # Opening Files +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In MFC, the most common way to open a file is a two-stage process. #### To open a file diff --git a/docs/mfc/optimizing-control-drawing.md b/docs/mfc/optimizing-control-drawing.md index 389d769e750..0ed7b644291 100644 --- a/docs/mfc/optimizing-control-drawing.md +++ b/docs/mfc/optimizing-control-drawing.md @@ -3,10 +3,13 @@ description: "Learn more about: Optimizing Control Drawing" title: "Optimizing Control Drawing" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], optimizing"] -ms.assetid: 29ff985d-9bf5-4678-b62d-aad12def75fb +ms.topic: concept-article --- # Optimizing Control Drawing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When a control is instructed to draw itself into a container-supplied device context, it typically selects GDI objects (such as pens, brushes, and fonts) into the device context, performs its drawing operations, and restores the previous GDI objects. If the container has multiple controls that are to be drawn into the same device context, and each control selects the GDI objects it requires, time can be saved if the controls do not individually restore previously selected objects. After all the controls have been drawn, the container can automatically restore the original objects. To detect whether a container supports this technique, a control can call the [COleControl::IsOptimizedDraw](reference/colecontrol-class.md#isoptimizeddraw) member function. If this function returns **TRUE**, the control can skip the normal step of restoring the previously selected objects. diff --git a/docs/mfc/optimizing-persistence-and-initialization.md b/docs/mfc/optimizing-persistence-and-initialization.md index 51e8befc886..88bfbbbf03a 100644 --- a/docs/mfc/optimizing-persistence-and-initialization.md +++ b/docs/mfc/optimizing-persistence-and-initialization.md @@ -3,10 +3,13 @@ description: "Learn more about: Optimizing Persistence and Initialization" title: "Optimizing Persistence and Initialization" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], optimizing", "performance, ActiveX controls", "optimization, ActiveX controls", "optimizing performance, ActiveX controls"] -ms.assetid: e821e19e-b9eb-49ab-b719-0743420ba80b +ms.topic: concept-article --- # Optimizing Persistence and Initialization +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By default, persistence and initialization in a control are handled by the `DoPropExchange` member function. In a typical control, this function contains calls to several **PX_** functions (`PX_Color`, `PX_Font`, and so on), one for each property. This approach has the advantage that a single `DoPropExchange` implementation can be used for initialization, for persistence in binary format, and for persistence in the so-called "property-bag" format used by some containers. This one function provides all information about the properties and their default values in one convenient place. diff --git a/docs/mfc/orchestrating-other-window-actions.md b/docs/mfc/orchestrating-other-window-actions.md index 41b8115884e..0f909d0693e 100644 --- a/docs/mfc/orchestrating-other-window-actions.md +++ b/docs/mfc/orchestrating-other-window-actions.md @@ -3,10 +3,13 @@ description: "Learn more about: Orchestrating Other Window Actions" title: "Orchestrating Other Window Actions" ms.date: "11/04/2016" helpviewer_keywords: ["frame windows [MFC], print preview", "context-sensitive Help [MFC], frame windows", "print preview [MFC], and frame windows", "frame windows [MFC], context-sensitive Help", "frame windows [MFC], semimodal states", "context-sensitive Help [MFC]"] -ms.assetid: 5f34eea8-2bf8-4479-95c7-45e8f443db8f +ms.topic: concept-article --- # Orchestrating Other Window Actions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The frame window orchestrates semimodal states such as context-sensitive help and print preview. For a description of the frame window's role in print preview, see [Printing and Print Preview](printing-and-print-preview.md). ## See also diff --git a/docs/mfc/ordering-items-in-the-header-control.md b/docs/mfc/ordering-items-in-the-header-control.md index 5dfc66ea144..e17ef17634e 100644 --- a/docs/mfc/ordering-items-in-the-header-control.md +++ b/docs/mfc/ordering-items-in-the-header-control.md @@ -4,10 +4,13 @@ title: "Ordering Items in the Header Control" ms.date: "11/04/2016" f1_keywords: ["DS_DRAGDROP"] helpviewer_keywords: ["sequence [MFC]", "sequence [MFC], header control items", "OrderToIndex method [MFC]", "DS_DRAGDROP notification [MFC]", "GetOrderArray method [MFC]", "SetOrderArray method [MFC]", "header controls [MFC], ordering items"] -ms.assetid: 5aaef872-75b5-49c5-8fed-6f9a81fca812 +ms.topic: concept-article --- # Ordering Items in the Header Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Once you've [added items to a header control](adding-items-to-the-header-control.md), you can manipulate or get information about their order with the following functions: - [CHeaderCtrl::GetOrderArray](reference/cheaderctrl-class.md#getorderarray) and [CHeaderCtrl::SetOrderArray](reference/cheaderctrl-class.md#setorderarray) diff --git a/docs/mfc/output-device-context-classes.md b/docs/mfc/output-device-context-classes.md index cdfed637a81..78ed227889d 100644 --- a/docs/mfc/output-device-context-classes.md +++ b/docs/mfc/output-device-context-classes.md @@ -4,10 +4,12 @@ title: "Output (Device Context) Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.output"] helpviewer_keywords: ["device contexts [MFC], classes", "screen output classes [MFC]", "printing classes [MFC]", "window drawing classes [MFC]", "painting classes [MFC]", "output classes [MFC]"] -ms.assetid: 35fd6435-a38e-42c6-a3fa-cd6f39370fc3 --- # Output (Device Context) Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These classes encapsulate the different types of device contexts available in Windows. Most of the following classes encapsulate a handle to a Windows device context. A device context is a Windows object that contains information about the drawing attributes of a device such as a display or a printer. All drawing calls are made through a device-context object. Additional classes derived from `CDC` encapsulate specialized device-context functionality, including support for Windows metafiles. diff --git a/docs/mfc/overridable-cwinapp-member-functions.md b/docs/mfc/overridable-cwinapp-member-functions.md index 9036701c9f0..fd923a07aac 100644 --- a/docs/mfc/overridable-cwinapp-member-functions.md +++ b/docs/mfc/overridable-cwinapp-member-functions.md @@ -3,10 +3,12 @@ description: "Learn more about: Overridable CWinApp Member Functions" title: "Overridable CWinApp Member Functions" ms.date: "11/04/2016" helpviewer_keywords: ["overriding [MFC], overridable functions in CWinApp", "application class [MFC]", "CWinApp class [MFC], overridables"] -ms.assetid: 07183d5e-734b-45d9-a8b6-9dde4adac0b4 --- # Overridable CWinApp Member Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [CWinApp](reference/cwinapp-class.md) provides several key overridable member functions (`CWinApp` overrides these members from class [CWinThread](reference/cwinthread-class.md), from which `CWinApp` derives): - [InitInstance](initinstance-member-function.md) diff --git a/docs/mfc/overriding-the-standard-command-routing.md b/docs/mfc/overriding-the-standard-command-routing.md index df1c2ddbd3c..f813b8218cc 100644 --- a/docs/mfc/overriding-the-standard-command-routing.md +++ b/docs/mfc/overriding-the-standard-command-routing.md @@ -3,10 +3,13 @@ description: "Learn more about: Overriding the Standard Command Routing" title: "Overriding the Standard Command Routing" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, command routing", "command routing [MFC], overriding", "command handling [MFC], routing commands", "overriding, standard command routing"] -ms.assetid: 872b698a-7432-40c4-9008-68721e8effa5 +ms.topic: concept-article --- # Overriding the Standard Command Routing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In rare cases when you must implement some variation of the standard framework routing, you can override it. The idea is to change the routing in one or more classes by overriding `OnCmdMsg` in those classes. Do so: - In the class that breaks the order to pass to a nondefault object. diff --git a/docs/mfc/overview-of-the-rich-edit-control.md b/docs/mfc/overview-of-the-rich-edit-control.md index e14a976fb89..dd13c02671d 100644 --- a/docs/mfc/overview-of-the-rich-edit-control.md +++ b/docs/mfc/overview-of-the-rich-edit-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Overview of the Rich Edit Control" title: "Overview of the Rich Edit Control" ms.date: "11/04/2016" helpviewer_keywords: ["rich edit controls [MFC]"] -ms.assetid: ad589b9f-a3fd-4820-bf1f-6b1965997e68 +ms.topic: concept-article --- # Overview of the Rich Edit Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!IMPORTANT] > If you are using a rich edit control in a dialog box (regardless of whether your application is SDI, MDI, or dialog-based), you must call [AfxInitRichEdit](reference/application-information-and-management.md#afxinitrichedit) once before the dialog box is displayed. A typical place to call this function is in your program's `InitInstance` member function. You do not need to call it for each time you display the dialog box, only the first time. You do not have to call `AfxInitRichEdit` if you are working with `CRichEditView`. diff --git a/docs/mfc/paragraph-formatting-in-rich-edit-controls.md b/docs/mfc/paragraph-formatting-in-rich-edit-controls.md index bf891d8c81d..6d186474a34 100644 --- a/docs/mfc/paragraph-formatting-in-rich-edit-controls.md +++ b/docs/mfc/paragraph-formatting-in-rich-edit-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Paragraph Formatting in Rich Edit Controls" title: "Paragraph Formatting in Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["rich edit controls [MFC], paragraph formatting in", "paragraph formatting in CRichEditCtrl [MFC]", "CRichEditCtrl class [MFC], paragraph formatting in", "formatting [MFC], paragraphs"] -ms.assetid: 0df2e4c9-2074-4e41-b913-87cb8c1b4d43 --- # Paragraph Formatting in Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use member functions of the rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)) to format paragraphs and to retrieve formatting information. Paragraph formatting attributes include alignment, tabs, indents, and numbering. You can apply paragraph formatting by using the [SetParaFormat](reference/cricheditctrl-class.md#setparaformat) member function. To determine the current paragraph formatting for the selected text, use the [GetParaFormat](reference/cricheditctrl-class.md#getparaformat) member function. The [PARAFORMAT](/windows/win32/api/richedit/ns-richedit-paraformat) structure is used with these member functions to specify paragraph attributes. One of the important members of **PARAFORMAT** is *dwMask*. In `SetParaFormat`, *dwMask* specifies which paragraph attributes will be set by this function call. `GetParaFormat` reports the attributes of the first paragraph in the selection; *dwMask* specifies the attributes that are consistent throughout the selection. diff --git a/docs/mfc/prerequisites-for-internet-client-classes.md b/docs/mfc/prerequisites-for-internet-client-classes.md index 3cc4b6bc083..2f7a948b5b5 100644 --- a/docs/mfc/prerequisites-for-internet-client-classes.md +++ b/docs/mfc/prerequisites-for-internet-client-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Prerequisites for Internet Client Classes" title: "Prerequisites for Internet Client Classes" ms.date: "11/04/2016" helpviewer_keywords: ["Internet files [MFC], writing to", "Internet [MFC], connections", "FTP (File Transfer Protocol), MFC classes", "Gopher prerequisites [MFC]", "files [MFC], writing to", "classes [MFC], connections", "HTTP [MFC], prerequisites for Internet clients", "connections [MFC], classes for", "Internet client class prerequisites [MFC]", "files [MFC], reading", "URLs [MFC], Internet client applications", "prerequisites, Internet client classes [MFC]", "Gopher client applications [MFC]"] -ms.assetid: c51d1dfe-260c-4228-8100-e4efd90e9599 --- # Prerequisites for Internet Client Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Some actions taken by an Internet client (reading a file, for example) have prerequisite actions (in this case, establishing an Internet connection). The following tables list the prerequisites for some client actions. ### General Internet URL (FTP, Gopher, or HTTP) diff --git a/docs/mfc/print-preview-architecture.md b/docs/mfc/print-preview-architecture.md index 4ec11761f33..a47454457b8 100644 --- a/docs/mfc/print-preview-architecture.md +++ b/docs/mfc/print-preview-architecture.md @@ -3,10 +3,12 @@ description: "Learn more about: Print Preview Architecture" title: "Print Preview Architecture" ms.date: "11/04/2016" helpviewer_keywords: ["print preview [MFC], process", "previewing printing", "print preview [MFC], architecture", "printing [MFC], print preview", "print preview [MFC], modifications to MFC"] -ms.assetid: 0efc87e6-ff8d-43c5-9d72-9b729a169115 --- # Print Preview Architecture +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how the MFC framework implements print preview functionality. Topics covered include: - [Print preview process](#_core_the_print_preview_process) diff --git a/docs/mfc/printing-and-print-preview.md b/docs/mfc/printing-and-print-preview.md index 5ad4329b9a7..fab2bc436e3 100644 --- a/docs/mfc/printing-and-print-preview.md +++ b/docs/mfc/printing-and-print-preview.md @@ -3,10 +3,13 @@ description: "Learn more about: Printing and Print Preview" title: "Printing and Print Preview" ms.date: "11/04/2016" helpviewer_keywords: ["printing [MFC]", "previewing printing", "printing [MFC]", "print preview", "printing [MFC], print preview"] -ms.assetid: d15059cd-32de-4450-95f7-e73aece238f6 +ms.topic: concept-article --- # Printing and Print Preview +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC supports printing and print preview for your program's documents via class [CView](reference/cview-class.md). For basic printing and print preview, simply override your view class's [OnDraw](reference/cview-class.md#ondraw) member function, which you must do anyway. That function can draw to the view on the screen, to a printer device context for an actual printer, or to a device context that simulates your printer on the screen. You can also add code to manage multipage document printing and preview, to paginate your printed documents, and to add headers and footers to them. diff --git a/docs/mfc/printing-in-rich-edit-controls.md b/docs/mfc/printing-in-rich-edit-controls.md index 21c9af612a1..f75b3796583 100644 --- a/docs/mfc/printing-in-rich-edit-controls.md +++ b/docs/mfc/printing-in-rich-edit-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Printing in Rich Edit Controls" title: "Printing in Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["printing [MFC], CRichEditCtrl", "rich edit controls [MFC], printing", "CRichEditCtrl class [MFC], printing"] -ms.assetid: dbda0e40-018f-424e-b5d8-7b489aaf27af +ms.topic: concept-article --- # Printing in Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can tell a rich edit control ([CRichEditCtrl](reference/cricheditctrl-class.md)) to render its output for a specified device, such as a printer. You can also specify the output device for which a rich edit control formats its text. To format part of the contents of a rich edit control for a specific device, you can use the [FormatRange](reference/cricheditctrl-class.md#formatrange) member function. The [FORMATRANGE](/windows/win32/api/richedit/ns-richedit-formatrange) structure used with this function specifies the range of text to format as well as the device context (DC) for the target device. diff --git a/docs/mfc/printing.md b/docs/mfc/printing.md index 2e4c83c98ff..9bb80b5f90e 100644 --- a/docs/mfc/printing.md +++ b/docs/mfc/printing.md @@ -3,10 +3,13 @@ description: "Learn more about: Printing" title: "Printing" ms.date: "11/04/2016" helpviewer_keywords: ["view classes [MFC], print operations", "documents [MFC], printing", "printing [MFC], from framework", "printing [MFC]"] -ms.assetid: be465e8d-b0c9-4fc5-9fa8-d10486064f76 +ms.topic: concept-article --- # Printing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Microsoft Windows implements device-independent display. In MFC, this means that the same drawing calls, in the `OnDraw` member function of your view class, are responsible for drawing on the display and on other devices, such as printers. For print preview, the target device is a simulated printer output to the display. ## Your Role in Printing vs. the Framework's Role diff --git a/docs/mfc/processing-header-control-notifications.md b/docs/mfc/processing-header-control-notifications.md index 5e4ec0c1a28..8fef663e015 100644 --- a/docs/mfc/processing-header-control-notifications.md +++ b/docs/mfc/processing-header-control-notifications.md @@ -3,10 +3,13 @@ description: "Learn more about: Processing Header-Control Notifications" title: "Processing Header-Control Notifications" ms.date: "11/04/2016" helpviewer_keywords: ["CHeaderCtrl class [MFC], processing notifications", "controls [MFC], header", "notifications [MFC], processing for CHeaderCtrl", "header controls [MFC], processing notifications", "header control notifications"] -ms.assetid: e6c6af7c-d458-4d33-85aa-48014ccde5f6 +ms.topic: concept-article --- # Processing Header-Control Notifications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In your view or dialog class, use the [Class Wizard](reference/mfc-class-wizard.md) to create an [OnChildNotify](reference/cwnd-class.md#onchildnotify) handler function with a switch statement for any header-control ([CHeaderCtrl](reference/cheaderctrl-class.md)) notification messages you want to handle (see [Mapping Messages to Functions](reference/mapping-messages-to-functions.md)). Notifications are sent to the parent window when the user clicks or double-clicks a header item, drags a divider between items, and so on. The notification messages associated with a header control are listed in [Header Control Reference](/windows/win32/controls/header-control-reference) in the Windows SDK. diff --git a/docs/mfc/processing-notification-messages-in-a-rebar-control.md b/docs/mfc/processing-notification-messages-in-a-rebar-control.md index 4a606ad68ea..cd4bf9f3832 100644 --- a/docs/mfc/processing-notification-messages-in-a-rebar-control.md +++ b/docs/mfc/processing-notification-messages-in-a-rebar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Processing Notification Messages in a Rebar Cont title: "Processing Notification Messages in a Rebar Control" ms.date: "11/04/2016" helpviewer_keywords: ["RBN_ notification messages, description of", "CReBarCtrl class [MFC], notification messages sent by", "RBN_ notification messages [MFC]", "notifications [MFC], CReBarCtrl"] -ms.assetid: 40f43a60-0c18-4d8d-8fab-213a095624f9 +ms.topic: concept-article --- # Processing Notification Messages in a Rebar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In the parent class of the rebar control, create an `OnChildNotify` handler function with a switch statement for any rebar-control (`CReBarCtrl`) notification messages you want to handle. Notifications are sent to the parent window when the user drags objects over the rebar control, changes the layout of the rebar bands, deletes bands from the rebar control, and so on. The following notification messages can be sent by the rebar control object: diff --git a/docs/mfc/processing-notification-messages-in-date-and-time-picker-controls.md b/docs/mfc/processing-notification-messages-in-date-and-time-picker-controls.md index 40487fce818..52eadf5e783 100644 --- a/docs/mfc/processing-notification-messages-in-date-and-time-picker-controls.md +++ b/docs/mfc/processing-notification-messages-in-date-and-time-picker-controls.md @@ -4,10 +4,13 @@ title: "Processing Notification Messages in Date and Time Picker Controls" ms.date: "11/04/2016" f1_keywords: ["DTN_CLOSEUP", "DTN_DATETIMECHANGE", "DTN_DROPDOWN"] helpviewer_keywords: ["DTN_DROPDOWN notification [MFC]", "DTN_DATETIMECHANGE notification [MFC]", "DTN_CLOSEUP notification [MFC]", "DateTimePicker control [MFC], handling notifications", "CDateTimeCtrl class [MFC], handling notifications", "DTN_FORMAT notification [MFC]", "DateTimePicker control [MFC]"] -ms.assetid: ffbe29ab-ff80-4609-89f7-260b404439c4 +ms.topic: concept-article --- # Processing Notification Messages in Date and Time Picker Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As users interact with the date and time picker control, the control (`CDateTimeCtrl`) sends notification messages to its parent window, usually a view or dialog object. Handle these messages if you want to do something in response. For example, when the user opens the date and time picker to display the embedded month calendar control, the DTN_DROPDOWN notification is sent. Use the [Class Wizard](reference/mfc-class-wizard.md) to add notification handlers to the parent class for those messages you want to implement. diff --git a/docs/mfc/processing-notification-messages-in-extended-combo-box-controls.md b/docs/mfc/processing-notification-messages-in-extended-combo-box-controls.md index f6f17343c9d..6f0782a1f0f 100644 --- a/docs/mfc/processing-notification-messages-in-extended-combo-box-controls.md +++ b/docs/mfc/processing-notification-messages-in-extended-combo-box-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Processing Notification Messages in Extended Com title: "Processing Notification Messages in Extended Combo Box Controls" ms.date: "11/04/2016" helpviewer_keywords: ["extended combo boxes [MFC], notifications", "notifications [MFC], extended combo box controls"] -ms.assetid: 4e442758-d054-4746-bb1a-6ff84accb127 +ms.topic: concept-article --- # Processing Notification Messages in Extended Combo Box Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As users interact with the extended combo box, the control (`CComboBoxEx`) sends notification messages to its parent window, usually a view or dialog object. Handle these messages if you want to do something in response. For example, when the user activates the drop-down list or clicks in the control's edit box, the CBEN_BEGINEDIT notification is sent. Use the [Class Wizard](reference/mfc-class-wizard.md) to add notification handlers to the parent class for those messages you want to implement. diff --git a/docs/mfc/processing-notification-messages-in-list-controls.md b/docs/mfc/processing-notification-messages-in-list-controls.md index 2f76695521d..5b96ff8b84d 100644 --- a/docs/mfc/processing-notification-messages-in-list-controls.md +++ b/docs/mfc/processing-notification-messages-in-list-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Processing Notification Messages in List Control title: "Processing Notification Messages in List Controls" ms.date: "11/04/2016" helpviewer_keywords: ["processing notifications [MFC]", "CListCtrl class [MFC], processing notifications"] -ms.assetid: 1f0e296e-d2a3-48fc-ae38-51d7fb096f51 +ms.topic: concept-article --- # Processing Notification Messages in List Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As users click column headers, drag icons, edit labels, and so on, the list control ([CListCtrl](../mfc/reference/clistctrl-class.md)) sends notification messages to its parent window. Handle these messages if you want to do something in response. For example, when the user clicks a column header, you might want to sort the items based on the contents of the clicked column, as in Microsoft Outlook. Process WM_NOTIFY messages from the list control in your view or dialog class. Use the [Class Wizard](reference/mfc-class-wizard.md) to create an [OnChildNotify](../mfc/reference/cwnd-class.md#onchildnotify) handler function with a switch statement based on which notification message is being handled. diff --git a/docs/mfc/processing-notification-messages-in-month-calendar-controls.md b/docs/mfc/processing-notification-messages-in-month-calendar-controls.md index 2effdb45f93..56632401488 100644 --- a/docs/mfc/processing-notification-messages-in-month-calendar-controls.md +++ b/docs/mfc/processing-notification-messages-in-month-calendar-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Processing Notification Messages in Month Calend title: "Processing Notification Messages in Month Calendar Controls" ms.date: "11/04/2016" helpviewer_keywords: ["CMonthCalCtrl class [MFC], notifications", "CMonthCalCtrl class [MFC], day states", "month calendar controls [MFC], notification messages", "notifications [MFC], for CMonthCalCtrl", "notifications [MFC], month calendar control"] -ms.assetid: 607c3e90-0756-493b-9503-ce835a50c7ab +ms.topic: concept-article --- # Processing Notification Messages in Month Calendar Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As users interact with the month calendar control (selecting dates and/or viewing a different month), the control (`CMonthCalCtrl`) sends notification messages to its parent window, usually a view or dialog object. Handle these messages if you want to do something in response. For example, when the user selects a new month to view, you could provide a set of dates that should be emphasized. Use the [Class Wizard](reference/mfc-class-wizard.md) to add notification handlers to the parent class for those messages you want to implement. diff --git a/docs/mfc/processing-tab-control-notification-messages.md b/docs/mfc/processing-tab-control-notification-messages.md index a0abab7d8aa..55e2b15e573 100644 --- a/docs/mfc/processing-tab-control-notification-messages.md +++ b/docs/mfc/processing-tab-control-notification-messages.md @@ -3,10 +3,13 @@ description: "Learn more about: Processing Tab Control Notification Messages" title: "Processing Tab Control Notification Messages" ms.date: "11/04/2016" helpviewer_keywords: ["notifications [MFC], tab controls", "CTabCtrl class [MFC], processing notifications", "notifications [MFC], processing in CTabCtrl", "processing notifications [MFC]", "tab controls [MFC], processing notifications"] -ms.assetid: 758ccb7a-9e73-48f8-9073-23f7cb09918c +ms.topic: concept-article --- # Processing Tab Control Notification Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As users click tabs or buttons, the tab control ([CTabCtrl](../mfc/reference/ctabctrl-class.md)) sends notification messages to its parent window. Handle these messages if you want to do something in response. For example, when the user clicks a tab, you may want to preset control data on the page prior to displaying it. Process WM_NOTIFY messages from the tab control in your view or dialog class. Use the [Class Wizard](reference/mfc-class-wizard.md) to create an [OnChildNotify](../mfc/reference/cwnd-class.md#onchildnotify) handler function with a switch statement based on which notification message is being handled. For a list of the notifications a tab control can send to its parent window, see the **Notifications** section of [Tab Control Reference](/windows/win32/controls/tab-control-reference) in the Windows SDK. diff --git a/docs/mfc/programmatic-printing.md b/docs/mfc/programmatic-printing.md index 079ccaf4b9f..913dff44ca3 100644 --- a/docs/mfc/programmatic-printing.md +++ b/docs/mfc/programmatic-printing.md @@ -3,10 +3,12 @@ description: "Learn more about: Programmatic Printing" title: "Programmatic Printing" ms.date: "11/04/2016" helpviewer_keywords: ["printing [MFC], active documents", "active documents [MFC], printing", "printing [MFC], programmatic", "IPrint interface", "printing [MFC]"] -ms.assetid: 3db0945b-5e13-4be4-86a0-6aecdae565bd --- # Programmatic Printing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + OLE provided the means to uniquely identify persistent documents (`GetClassFile`) and load them into their associated code (`CoCreateInstance`, `QueryInterface(IID_IPersistFile)`, `QueryInterface(IID_IPersistStorage)`, `IPersistFile::Load`, and `IPersistStorage::Load`). To further enable printing documents, active document containment (using an existing OLE design not shipped with OLE 2.0 originally) introduces a base-standard printing interface, `IPrint`, generally available through any object that can load the persistent state of the document type. Each view of an active document can optionally support the `IPrint` interface to provide these capabilities. The `IPrint` interface is defined as follows: diff --git a/docs/mfc/programming-activex-controls-in-a-activex-control-container.md b/docs/mfc/programming-activex-controls-in-a-activex-control-container.md index 43334e14538..327d058bc67 100644 --- a/docs/mfc/programming-activex-controls-in-a-activex-control-container.md +++ b/docs/mfc/programming-activex-controls-in-a-activex-control-container.md @@ -3,10 +3,12 @@ description: "Learn more about: ActiveX Control Containers: Programming ActiveX title: "ActiveX Control Containers: Programming ActiveX Controls in an ActiveX Control Container" ms.date: "09/12/2018" helpviewer_keywords: ["ActiveX control containers [MFC], accessing ActiveX controls", "Confirm Classes dialog box", "wrapper classes [MFC], ActiveX controls", "ActiveX control containers [MFC], wrapper classes", "ActiveX controls [MFC], accessing", "MFC ActiveX controls [MFC], accessing in containers", "header files [MFC], for ActiveX control wrapper class", "wrapper classes [MFC], using", "ActiveX controls [MFC], wrapper classes"] -ms.assetid: ef9b2480-92d6-4191-b16e-8055c4fd7b73 --- # ActiveX Control Containers: Programming ActiveX Controls in an ActiveX Control Container +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the process for accessing the exposed [methods](../mfc/mfc-activex-controls-methods.md) and [properties](../mfc/mfc-activex-controls-properties.md) of embedded ActiveX controls. >[!IMPORTANT] @@ -44,7 +46,7 @@ Once the Circ control is inserted into the project (step 1), insert an instance ## Modifications to the Project -To enable the Container application to access the Circ control, Visual C++ automatically adds the wrapper class (`CCirc`) implementation file (.CPP) to the Container project and the wrapper class header (.H) file to the dialog box header file: +To enable the Container application to access the Circ control, Visual Studio automatically adds the wrapper class (`CCirc`) implementation file (.CPP) to the Container project and the wrapper class header (.H) file to the dialog box header file: [!code-cpp[NVC_MFC_AxCont#1](../mfc/codesnippet/cpp/programming-activex-controls-in-a-activex-control-container_1.h)] @@ -59,7 +61,7 @@ These functions can then be called from other of the application's procedures us ## Member Variable Modifications to the Project -Once the ActiveX control has been added to the project and embedded in a dialog box container, it can be accessed by other parts of the project. The easiest way to access the control is to [create a member variable](../mfc/activex-control-containers-connecting-an-activex-control-to-a-member-variable.md) of the dialog class, `CContainerDlg` (step 2), that is of the same type as the wrapper class added to the project by Visual C++. You can then use the member variable to access the embedded control at any time. +Once the ActiveX control has been added to the project and embedded in a dialog box container, it can be accessed by other parts of the project. The easiest way to access the control is to [create a member variable](../mfc/activex-control-containers-connecting-an-activex-control-to-a-member-variable.md) of the dialog class, `CContainerDlg` (step 2), that is of the same type as the wrapper class added to the project by Visual Studio. You can then use the member variable to access the embedded control at any time. When the **Add Member Variable** dialog box adds the *m_circctl* member variable to the project, it also adds the following lines to the header file (.H) of the `CContainerDlg` class: diff --git a/docs/mfc/property-sheets-and-property-pages-in-mfc.md b/docs/mfc/property-sheets-and-property-pages-in-mfc.md index d1ff2461a9e..26ba5d7997f 100644 --- a/docs/mfc/property-sheets-and-property-pages-in-mfc.md +++ b/docs/mfc/property-sheets-and-property-pages-in-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Property Sheets and Property Pages in MFC" title: "Property Sheets and Property Pages in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["property pages [MFC], MFC", "controls [MFC], property sheets", "property sheets, MFC", "tab dialog boxes"] -ms.assetid: e1bede2b-0285-4b88-a052-0f8a372807a2 --- # Property Sheets and Property Pages in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A property sheet, also known as a tab dialog box, is a dialog box that contains property pages. Each property page is based on a dialog template resource and contains controls. It is enclosed on a page with a tab on top. The tab names the page and indicates its purpose. Users click a tab in the property sheet to select a set of controls. Use pages to group the controls in the property sheet into meaningful sets. The contained property sheet typically has several controls of its own. These apply to all pages. diff --git a/docs/mfc/property-sheets-and-property-pages-mfc.md b/docs/mfc/property-sheets-and-property-pages-mfc.md index 66e1363c041..d2ab2c06422 100644 --- a/docs/mfc/property-sheets-and-property-pages-mfc.md +++ b/docs/mfc/property-sheets-and-property-pages-mfc.md @@ -2,12 +2,14 @@ description: "Learn more about: Property Sheets and Property Pages (MFC)" title: "Property Sheets and Property Pages (MFC)" ms.date: "11/04/2016" -helpviewer_keywords: ["MFC dialog boxes [MFC], tabs", "property pages [MFC], property sheets", "CPropertyPage class [MFC], property sheets and pages", "CPropertySheet class [MFC], property sheets and pages", "property sheets, propert pages"] -ms.assetid: de8fea12-6c35-4cef-8625-b8073a379446 +helpviewer_keywords: ["MFC dialog boxes [MFC], tabs", "property pages [MFC], property sheets", "CPropertyPage class [MFC], property sheets and pages", "CPropertySheet class [MFC], property sheets and pages", "property sheets, property pages"] --- # Property Sheets and Property Pages (MFC) -An MFC [dialog box](../mfc/dialog-boxes.md) can take on a "tab dialog" look by incorporating property sheets and property pages. Called a "property sheet" in MFC, this kind of dialog box, similar to many dialog boxes in Microsoft Word, Excel, and Visual C++, appears to contain a stack of tabbed sheets, much like a stack of file folders seen from front to back, or a group of cascaded windows. Controls on the front tab are visible; only the labeled tab is visible on the rear tabs. Property sheets are particularly useful for managing large numbers of properties or settings that fall fairly neatly into several groups. Typically, one property sheet can simplify a user interface by replacing several separate dialog boxes. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +An MFC [dialog box](../mfc/dialog-boxes.md) can take on a "tab dialog" look by incorporating property sheets and property pages. Called a "property sheet" in MFC, this kind of dialog box, similar to many dialog boxes in Microsoft Word, Excel, and Visual Studio, appears to contain a stack of tabbed sheets, much like a stack of file folders seen from front to back, or a group of cascaded windows. Controls on the front tab are visible; only the labeled tab is visible on the rear tabs. Property sheets are particularly useful for managing large numbers of properties or settings that fall fairly neatly into several groups. Typically, one property sheet can simplify a user interface by replacing several separate dialog boxes. As of MFC version 4.0, property sheets and property pages are implemented using the common controls that come with Windows 95 and Windows NT version 3.51 and later. diff --git a/docs/mfc/property-sheets-as-wizards.md b/docs/mfc/property-sheets-as-wizards.md index 30372a26477..028073f571a 100644 --- a/docs/mfc/property-sheets-as-wizards.md +++ b/docs/mfc/property-sheets-as-wizards.md @@ -3,10 +3,12 @@ description: "Learn more about: Property Sheets as Wizards" title: "Property Sheets as Wizards" ms.date: "11/04/2016" helpviewer_keywords: ["property sheets, as wizards"] -ms.assetid: 1ea66ecb-23b0-484a-838d-58671a2999b5 --- # Property Sheets as Wizards +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A key characteristic of a wizard property sheet is that navigation is provided with Next or Finish, Back, and Cancel buttons instead of tabs. You need to call [CPropertySheet::SetWizardMode](../mfc/reference/cpropertysheet-class.md#setwizardmode) before calling [CPropertySheet::DoModal](../mfc/reference/cpropertysheet-class.md#domodal) on the property sheet object to take advantage of this feature. The user receives the same [CPropertyPage::OnSetActive](../mfc/reference/cpropertypage-class.md#onsetactive) and [CPropertyPage::OnKillActive](../mfc/reference/cpropertypage-class.md#onkillactive) notifications while moving from one page to another page. Next and Finish buttons are mutually exclusive controls; that is, only one of them will be shown at a time. On the first page, the Next button should be enabled. If the user is on the last page, the Finish button should be enabled. This is not done automatically by the framework. You have to call [CPropertySheet::SetWizardButton](../mfc/reference/cpropertysheet-class.md#setwizardbuttons) on the last page to achieve this. diff --git a/docs/mfc/property-sheets-mfc.md b/docs/mfc/property-sheets-mfc.md index aaf53b3bab6..e387244b3fb 100644 --- a/docs/mfc/property-sheets-mfc.md +++ b/docs/mfc/property-sheets-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Property Sheets (MFC)" title: "Property Sheets (MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["dialog boxes [MFC], tabs", "property sheets", "dialog boxes [MFC], property sheets", "tab dialog boxes"] -ms.assetid: 09439f65-921d-45a2-b3cc-e13884a087b1 --- # Property Sheets (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This family of articles explains how to implement support for property sheets in MFC applications. A property sheet, also known as a tab dialog box, provides a way to manage large numbers of controls in a dialog box. The property sheet contains property pages, each based on a separate dialog template resource. You can divide your dialog box's controls into logical groups and put each group on its own property page. ## What do you want to know more about diff --git a/docs/mfc/providing-drag-and-drop-support-for-header-items.md b/docs/mfc/providing-drag-and-drop-support-for-header-items.md index e3c3b78cab3..283f10cc348 100644 --- a/docs/mfc/providing-drag-and-drop-support-for-header-items.md +++ b/docs/mfc/providing-drag-and-drop-support-for-header-items.md @@ -3,10 +3,13 @@ description: "Learn more about: Providing Drag-and-Drop Support for Header Items title: "Providing Drag-and-Drop Support for Header Items" ms.date: "11/04/2016" helpviewer_keywords: ["HDS_DRAGDROP style", "header items in header controls", "CHeaderCtrl class [MFC], drag and drop support", "HDN_ notifications [MFC]"] -ms.assetid: 93a152ec-804f-488f-b260-b3a438d0dc0f +ms.topic: concept-article --- # Providing Drag-and-Drop Support for Header Items +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To provide drag-and-drop support for header items, specify the HDS_DRAGDROP style. Drag-and-drop support for header items gives the user the ability to reorder the header items of a header control. The default behavior provides a semitransparent drag image of the header item being dragged and a visual indicator of the new position, if the header item is dropped. As with common drag-and-drop functionality, you can extend the default drag-and-drop behavior by handling the HDN_BEGINDRAG and HDN_ENDDRAG notifications. You can also customize the appearance of the drag image by overriding the [CHeaderCtrl::CreateDragImage](../mfc/reference/cheaderctrl-class.md#createdragimage) member function. diff --git a/docs/mfc/providing-flicker-free-activation.md b/docs/mfc/providing-flicker-free-activation.md index e4f3a54191d..edd2defede6 100644 --- a/docs/mfc/providing-flicker-free-activation.md +++ b/docs/mfc/providing-flicker-free-activation.md @@ -3,10 +3,13 @@ description: "Learn more about: Providing Flicker-Free Activation" title: "Providing Flicker-Free Activation" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], flicker-free", "flicker, MFC ActiveX controls", "activation [MFC], flicker-free"] -ms.assetid: bcb24b77-31d8-44a0-8c58-2ea6213b4c43 +ms.topic: concept-article --- # Providing Flicker-Free Activation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If your control draws itself identically in the inactive and active states (and does not use windowless activation), you can eliminate the drawing operations and the accompanying visual flicker that normally occur when making the transition between the inactive and active states. To do this, include the **noFlickerActivate** flag in the set of flags returned by [COleControl::GetControlFlags](../mfc/reference/colecontrol-class.md#getcontrolflags). For example: [!code-cpp[NVC_MFC_AxOpt#5](../mfc/codesnippet/cpp/providing-flicker-free-activation_1.cpp)] diff --git a/docs/mfc/providing-mouse-interaction-while-inactive.md b/docs/mfc/providing-mouse-interaction-while-inactive.md index 0cc692d9e05..446aa4c6892 100644 --- a/docs/mfc/providing-mouse-interaction-while-inactive.md +++ b/docs/mfc/providing-mouse-interaction-while-inactive.md @@ -3,10 +3,13 @@ description: "Learn more about: Providing Mouse Interaction While Inactive" title: "Providing Mouse Interaction While Inactive" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], mouse interaction"] -ms.assetid: b09106bf-44c7-4b9b-a6d9-0d624f16f5b3 +ms.topic: concept-article --- # Providing Mouse Interaction While Inactive +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If your control is not immediately activated, you may still want it to process WM_SETCURSOR and WM_MOUSEMOVE messages, even though the control has no window of its own. This can be accomplished by enabling `COleControl`'s implementation of the `IPointerInactive` interface, which is disabled by default. (See the *ActiveX SDK* for a description of this interface.) To enable it, include the pointerInactive flag in the set of flags returned by [COleControl::GetControlFlags](../mfc/reference/colecontrol-class.md#getcontrolflags): [!code-cpp[NVC_MFC_AxOpt#5](../mfc/codesnippet/cpp/providing-mouse-interaction-while-inactive_1.cpp)] diff --git a/docs/mfc/providing-windowless-activation.md b/docs/mfc/providing-windowless-activation.md index b78c0e19c41..d30b308b309 100644 --- a/docs/mfc/providing-windowless-activation.md +++ b/docs/mfc/providing-windowless-activation.md @@ -3,10 +3,13 @@ description: "Learn more about: Providing Windowless Activation" title: "Providing Windowless Activation" ms.date: "11/04/2016" helpviewer_keywords: ["windowless activation of MFC ActiveX controls", "activation [MFC], MFC ActiveX controls", "MFC ActiveX controls [MFC], activate options", "activation [MFC], windowless"] -ms.assetid: 094903b5-c344-42fa-96ff-ce01e16891c5 +ms.topic: concept-article --- # Providing Windowless Activation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Window creation code (that is, everything that happens when you call `CreateWindow`) is costly to execute. A control that maintains an on-screen window has to manage messages for the window. Windowless controls are therefore faster than controls with windows. A further advantage of windowless controls is that, unlike windowed controls, windowless controls support transparent painting and nonrectangular screen regions. A common example of a transparent control is a text control with a transparent background. The controls paints the text but not the background, so whatever is under the text shows through. Newer forms often make use of nonrectangular controls, such as arrows and round buttons. diff --git a/docs/mfc/reading-and-writing-files.md b/docs/mfc/reading-and-writing-files.md index 0ef0ecd046b..1a536cdadb6 100644 --- a/docs/mfc/reading-and-writing-files.md +++ b/docs/mfc/reading-and-writing-files.md @@ -3,10 +3,13 @@ description: "Learn more about: Reading and Writing Files" title: "Reading and Writing Files" ms.date: "11/04/2016" helpviewer_keywords: ["CFile class [MFC], objects", "examples [MFC], reading files", "files [MFC], writing to", "examples [MFC], writing to files", "files [MFC], reading", "MFC, file operations", "CFile class [MFC], reading and writing CFile objects", "reading files", "writing to files [MFC]"] -ms.assetid: cac0c826-ba56-495f-99b3-ce6336f65763 +ms.topic: how-to --- # Reading and Writing Files +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you've used the C run-time library file-handling functions, MFC reading and writing operations will appear familiar. This article describes reading directly from and writing directly to a `CFile` object. You can also do buffered file I/O with the [CArchive](../mfc/reference/carchive-class.md) class. #### To read from and write to the file diff --git a/docs/mfc/ready-to-use-array-classes.md b/docs/mfc/ready-to-use-array-classes.md index 16f2460eccf..f63012d0816 100644 --- a/docs/mfc/ready-to-use-array-classes.md +++ b/docs/mfc/ready-to-use-array-classes.md @@ -4,10 +4,12 @@ title: "Ready-to-Use Array Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.array"] helpviewer_keywords: ["arrays [MFC], classes", "collection classes [MFC], arrays", "classes [MFC], array"] -ms.assetid: fdeabf95-2fe7-43a8-8f88-d954133caf52 --- # Ready-to-Use Array Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following classes are ready-to-use array classes. [CByteArray](../mfc/reference/cbytearray-class.md)
diff --git a/docs/mfc/ready-to-use-list-classes.md b/docs/mfc/ready-to-use-list-classes.md index 7e242c1ad12..50647fdfc75 100644 --- a/docs/mfc/ready-to-use-list-classes.md +++ b/docs/mfc/ready-to-use-list-classes.md @@ -4,10 +4,12 @@ title: "Ready-to-Use List Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.list"] helpviewer_keywords: ["classes [MFC], list", "list classes [MFC]", "collection classes [MFC], lists"] -ms.assetid: aed8e9bd-edb7-4620-84a2-77c20322abd7 --- # Ready-to-Use List Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following classes are ready-to-use list classes. [CObList](../mfc/reference/coblist-class.md)
diff --git a/docs/mfc/ready-to-use-map-classes.md b/docs/mfc/ready-to-use-map-classes.md index 2c2b8674f79..002957165bd 100644 --- a/docs/mfc/ready-to-use-map-classes.md +++ b/docs/mfc/ready-to-use-map-classes.md @@ -4,10 +4,12 @@ title: "Ready-to-Use Map Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.map"] helpviewer_keywords: ["collection classes [MFC], maps", "classes [MFC], map", "map classes [MFC]"] -ms.assetid: 3f0b1c05-2243-4d4d-98d4-429fc3310c9f --- # Ready-to-Use Map Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following classes are ready-to-use map classes. [CMapPtrToPtr](../mfc/reference/cmapptrtoptr-class.md)
diff --git a/docs/mfc/rebar-controls-and-bands.md b/docs/mfc/rebar-controls-and-bands.md index 4efeb0795a6..0b14f9dbb4a 100644 --- a/docs/mfc/rebar-controls-and-bands.md +++ b/docs/mfc/rebar-controls-and-bands.md @@ -3,10 +3,12 @@ description: "Learn more about: Rebar Controls and Bands" title: "Rebar Controls and Bands" ms.date: "11/04/2016" helpviewer_keywords: ["rebar controls [MFC], working with bands in", "bands, in rebar controls"] -ms.assetid: b647e7a5-9ea7-48b1-8e5f-096d104748f0 --- # Rebar Controls and Bands +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The main purpose of a rebar control is to act as a container for child windows, common dialog controls, menus, toolbars, and so on. This containment is supported by the concept of a "band." Each rebar band can contain any combination of a gripper bar, a bitmap, a text label, and a child window. Class `CReBarCtrl` has many member functions that you can use to retrieve, and manipulate, information for a specific rebar band: diff --git a/docs/mfc/receiving-notification-from-common-controls.md b/docs/mfc/receiving-notification-from-common-controls.md index ee2aadff48d..435756b0ced 100644 --- a/docs/mfc/receiving-notification-from-common-controls.md +++ b/docs/mfc/receiving-notification-from-common-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Receiving Notification from Common Controls" title: "Receiving Notification from Common Controls" ms.date: "11/04/2016" helpviewer_keywords: ["OnNotify method [MFC]", "common controls [MFC], notifications", "ON_NOTIFY macro [MFC]", "controls [MFC], notifications", "receiving notifications from common controls", "notifications [MFC], common controls", "Windows common controls [MFC], notifications", "WM_NOTIFY message"] -ms.assetid: 50194592-d60d-44d0-8ab3-338a2a2c63e7 +ms.topic: concept-article --- # Receiving Notification from Common Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Common controls are child windows that send notification messages to the parent window when events, such as input from the user, occur in the control. The application relies on these notification messages to determine what action the user wants it to take. Most common controls send notification messages as WM_NOTIFY messages. Windows controls send most notification messages as WM_COMMAND messages. [CWnd::OnNotify](../mfc/reference/cwnd-class.md#onnotify) is the handler for the WM_NOTIFY message. As with `CWnd::OnCommand`, the implementation of `OnNotify` dispatches the notification message to `OnCmdMsg` for handling in message maps. The message-map entry for handling notifications is ON_NOTIFY. For more information, see [Technical Note 61: ON_NOTIFY and WM_NOTIFY Messages](../mfc/tn061-on-notify-and-wm-notify-messages.md). diff --git a/docs/mfc/recommendations-for-choosing-a-collection-class.md b/docs/mfc/recommendations-for-choosing-a-collection-class.md index aaf0201877d..081935d01d7 100644 --- a/docs/mfc/recommendations-for-choosing-a-collection-class.md +++ b/docs/mfc/recommendations-for-choosing-a-collection-class.md @@ -3,10 +3,12 @@ description: "Learn more about: Recommendations for Choosing a Collection Class" title: "Recommendations for Choosing a Collection Class" ms.date: "11/04/2016" helpviewer_keywords: ["type safety of collection classes [MFC]", "collection classes [MFC], serialization", "collection classes [MFC], speed", "collection classes [MFC], type safety", "collection classes [MFC], choosing", "collection classes [MFC], functionality", "shapes, collection", "collection classes [MFC], template-based", "MFC collection classes [MFC], characteristics", "collection classes [MFC], about collection classes [MFC]", "serialization [MFC], collection classes", "collection classes [MFC], duplicates allowed", "collection classes [MFC], shapes"] -ms.assetid: a82188cd-443f-40d8-a244-edf292a53db4 --- # Recommendations for Choosing a Collection Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article contains detailed information designed to help you choose a collection class for your particular application needs. Your choice of a collection class depends on a number of factors, including: diff --git a/docs/mfc/recommendations-for-handling-input-output.md b/docs/mfc/recommendations-for-handling-input-output.md index 891b0028419..151b6e1c4a6 100644 --- a/docs/mfc/recommendations-for-handling-input-output.md +++ b/docs/mfc/recommendations-for-handling-input-output.md @@ -3,10 +3,12 @@ description: "Learn more about: Recommendations for Handling Input/Output" title: "Recommendations for Handling Input-Output" ms.date: "11/04/2016" helpviewer_keywords: ["I/O [MFC], about I/O", "file-based I/O options", "I/O [MFC]", "I/O [MFC], options", "I/O [MFC], file-based options"] -ms.assetid: d664b175-3b4a-40c3-b14b-39de6b12e419 --- # Recommendations for Handling Input/Output +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Whether you use file-based I/O or not depends on how you respond to the questions in the following decision tree: **Does the primary data in your application reside in a disk file** diff --git a/docs/mfc/reference/add-class-from-typelib-wizard.md b/docs/mfc/reference/add-class-from-typelib-wizard.md index 1f45b4a023c..378a883f19a 100644 --- a/docs/mfc/reference/add-class-from-typelib-wizard.md +++ b/docs/mfc/reference/add-class-from-typelib-wizard.md @@ -3,11 +3,13 @@ description: "Learn more about: Add Class from Typelib Wizard" title: "Add Class from Typelib Wizard" ms.date: "03/10/2022" helpviewer_keywords: ["COM interfaces, adding classes"] -ms.assetid: 96152afd-9374-4649-a6ab-b0fa2a5592a3 ms.custom: devdivchpfy22 --- # Add Class from Typelib Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + ::: moniker range=">=msvc-160" The wizard creates a class for each interface you add from the selected type library. diff --git a/docs/mfc/reference/add-idl-mfc-method-wizard.md b/docs/mfc/reference/add-idl-mfc-method-wizard.md index 4a8592c7e2c..f93f1ee4b80 100644 --- a/docs/mfc/reference/add-idl-mfc-method-wizard.md +++ b/docs/mfc/reference/add-idl-mfc-method-wizard.md @@ -9,6 +9,9 @@ ms.custom: devdivchpfy22 # Add an IDL MFC method +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The **Add IDL MFC Method** wizard adds a method to an Interface Definition Library (IDL) interface defined in your Microsoft Framework Class (MFC) project. If the project contains a class associated with the interface, the wizard also adds the method to the class. To use this wizard, you must be in an MFC Project, ActiveX project, or an ATL project that supports MFC. For example, if you have a Microsoft ActiveX control project, you can use the following procedure to add a method to an IDL interface in the solution. diff --git a/docs/mfc/reference/add-interface-definition-library-mfc-property-wizard.md b/docs/mfc/reference/add-interface-definition-library-mfc-property-wizard.md index 5ac27990ea7..6ecb599ae65 100644 --- a/docs/mfc/reference/add-interface-definition-library-mfc-property-wizard.md +++ b/docs/mfc/reference/add-interface-definition-library-mfc-property-wizard.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: Use the Microsoft Visual Studio Add IDL MFC property wizard to add a property to an IDL interface in your MFC or ATL project" title: "Add an IDL MFC property" -ms.date: "04/14/2022" +description: "Learn more about: Use the Microsoft Visual Studio Add IDL MFC property wizard to add a property to an IDL interface in your MFC or ATL project" +ms.date: 04/14/2022 f1_keywords: ["vc.codewiz.prop.overview"] helpviewer_keywords: ["interfaces, adding properties", "properties [C++], adding to interfaces", "names, add property wizard", "add property wizard", "stock properties, about stock properties", "stock properties"] ms.custom: devdivchpfy22 @@ -9,6 +9,9 @@ ms.custom: devdivchpfy22 # Add an IDL MFC property +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The **Add IDL MFC Property** wizard adds a property to an Interface Definition Library (IDL) interface defined in your Microsoft Framework Class (MFC) project. To use this wizard, you must be in an MFC Project, ActiveX project, or an ATL project that supports MFC. For example, if you have a Microsoft ActiveX control project, you can use the following procedure to add a property to an IDL interface in the solution. @@ -167,7 +170,7 @@ If you're adding a property to an MFC dispinterface, you can choose one of the f |`ReadyState`|Returns or sets the control's `ReadyState` property.
A control can be uninitialized, initialized, loading, interactive, or complete.
For more information, see [READYSTATE](/previous-versions/aa768362\(v=vs.85\)) in the *Internet SDK*.| |`Text`|Returns or sets the text contained in a control.
Has no **Member variable** implementation type.| -## See Also +## See also [Add Property](../../ide/adding-a-property-visual-cpp.md) diff --git a/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md b/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md index db0802eea7c..533a9746542 100644 --- a/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md +++ b/docs/mfc/reference/adding-an-mfc-class-from-a-type-library.md @@ -7,6 +7,9 @@ ms.custom: devdivchpfy22 --- # Add an MFC class from a type library +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use this wizard to create an MFC class from an interface in a type library. You can add an MFC class to an [MFC application](../../mfc/reference/creating-an-mfc-application.md), an [MFC DLL](../../mfc/reference/creating-an-mfc-dll-project.md), or an [MFC ActiveX control](../../mfc/reference/creating-an-mfc-activex-control.md). > [!NOTE] diff --git a/docs/mfc/reference/adding-an-mfc-class.md b/docs/mfc/reference/adding-an-mfc-class.md index aa1ef1c78f2..45dea891a56 100644 --- a/docs/mfc/reference/adding-an-mfc-class.md +++ b/docs/mfc/reference/adding-an-mfc-class.md @@ -4,10 +4,12 @@ title: "Adding an MFC Class" ms.date: "09/06/2019" f1_keywords: ["vc.codewiz.classes.adding.mfc"] helpviewer_keywords: ["classes [MFC], adding MFC", "MFC, adding classes"] -ms.assetid: 9a96b67f-40bf-43d4-8872-2f8dfc5404f1 --- # Adding an MFC Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To add classes derived from Microsoft Foundation Class (MFC) library classes to your project, use the **Add Class** button in [Class Wizard](mfc-class-wizard.md). Specify the name of the new class, select the base class, and select the ID of the dialog box with which it is associated (if any). The wizard creates a header file and an implementation file and adds them to your project. > [!NOTE] diff --git a/docs/mfc/reference/adding-an-mfc-message-handler.md b/docs/mfc/reference/adding-an-mfc-message-handler.md index 3bfd45427da..6d413d2139e 100644 --- a/docs/mfc/reference/adding-an-mfc-message-handler.md +++ b/docs/mfc/reference/adding-an-mfc-message-handler.md @@ -4,10 +4,12 @@ title: "Adding an MFC Message Handler" ms.date: "09/06/2019" f1_keywords: ["vc.codewiz.adding.mfc.msghandler"] helpviewer_keywords: ["message handling [MFC], adding handlers"] -ms.assetid: 4251cfce-76ca-443d-bd2f-6303afa6d942 --- # Adding an MFC Message Handler +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use the [Class Wizard](mfc-class-wizard.md) or the **Properties** window in **CLass View** to add a message handler (a member function that handles Windows messages) to a class and map Windows messages to the message handler. You can also add [an event handler for any dialog box control](../../windows/adding-editing-or-deleting-controls.md). By using the **Class Wizard** or **Properties** window (in **Class View**) to define message- and event-handling functions, you can automatically update the message-dispatch table (or message map) and your class header file. diff --git a/docs/mfc/reference/adding-an-mfc-odbc-consumer.md b/docs/mfc/reference/adding-an-mfc-odbc-consumer.md index 887931326d3..44a5ce4943a 100644 --- a/docs/mfc/reference/adding-an-mfc-odbc-consumer.md +++ b/docs/mfc/reference/adding-an-mfc-odbc-consumer.md @@ -3,10 +3,12 @@ description: "Learn more about: Adding an MFC ODBC Consumer" title: "Adding an MFC ODBC Consumer" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ODBC consumers"] -ms.assetid: 2dc97909-1f7e-43ee-9d47-99e612727058 --- # Adding an MFC ODBC Consumer +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An MFC ODBC consumer consists of an ODBC recordset class and data bindings necessary to access a data source. ### To add an MFC ODBC consumer diff --git a/docs/mfc/reference/adding-atl-support-to-your-mfc-project.md b/docs/mfc/reference/adding-atl-support-to-your-mfc-project.md index b994dd50d59..0648dcb7ea1 100644 --- a/docs/mfc/reference/adding-atl-support-to-your-mfc-project.md +++ b/docs/mfc/reference/adding-atl-support-to-your-mfc-project.md @@ -4,14 +4,14 @@ title: "Adding ATL Support to Your MFC Project" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.adding.atl.mfc"] helpviewer_keywords: ["MFC, ATL support", "ATL, MFC projects"] -ms.assetid: b5fe15d6-7752-4818-b9f9-62482ad35c95 --- # Adding ATL Support to Your MFC Project -If you have already created an MFC-based application, then you can add support for the Active Template Library (ATL) easily by using the IDE. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library and Active Template Library (ATL) continue to be supported. However, we're no longer adding features or updating the documentation. +> ATL support applies only to simple COM objects added to an MFC executable or DLL project. You can add other COM objects (including ActiveX controls) to MFC projects, but the objects might not operate as expected. -> [!NOTE] -> This support applies only to simple COM objects added to an MFC executable or DLL project. You can add other COM objects (including ActiveX controls) to MFC projects, but the objects might not operate as expected. +If you have already created an MFC-based application, then you can add support for the Active Template Library (ATL) easily by using the IDE. ::: moniker range=">=msvc-160" diff --git a/docs/mfc/reference/advanced-features-mfc-application-wizard.md b/docs/mfc/reference/advanced-features-mfc-application-wizard.md index 7a7c5bbdfe2..aa7ae813506 100644 --- a/docs/mfc/reference/advanced-features-mfc-application-wizard.md +++ b/docs/mfc/reference/advanced-features-mfc-application-wizard.md @@ -4,10 +4,12 @@ title: "Advanced Features, MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.advanced"] helpviewer_keywords: ["MFC Application Wizard, advanced features"] -ms.assetid: 8a6681c5-6576-4b12-841a-6862beee76fa --- # Advanced Features, MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists options for additional features for your application, such as Help, printing support, and so on. In each section, specify additional support for these advanced features. - **Context-sensitive help (HTML)** diff --git a/docs/mfc/reference/afx-extension-module-structure.md b/docs/mfc/reference/afx-extension-module-structure.md index e64cd1da160..925e38e46c1 100644 --- a/docs/mfc/reference/afx-extension-module-structure.md +++ b/docs/mfc/reference/afx-extension-module-structure.md @@ -4,10 +4,12 @@ title: "AFX_EXTENSION_MODULE Structure" ms.date: "11/04/2016" f1_keywords: ["AFX_EXTENSION_MODULE"] helpviewer_keywords: ["AFX_EXTENSION_MODULE structure [MFC]"] -ms.assetid: b85a989c-d0c5-4b28-b53c-dad45b75704e --- # AFX_EXTENSION_MODULE Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `AFX_EXTENSION_MODULE` is used during initialization of MFC extension DLLs to hold the state of MFC extension DLL module. ## Syntax diff --git a/docs/mfc/reference/afx-global-data-structure.md b/docs/mfc/reference/afx-global-data-structure.md index 22f9fd769ea..1abc9996801 100644 --- a/docs/mfc/reference/afx-global-data-structure.md +++ b/docs/mfc/reference/afx-global-data-structure.md @@ -4,10 +4,12 @@ title: "AFX_GLOBAL_DATA Structure" ms.date: "11/04/2016" f1_keywords: ["AFX_GLOBAL_DATA", "AFXGLOBALS/AFX_GLOBAL_DATA::AFX_GLOBAL_DATA", "AFXGLOBALS/AFX_GLOBAL_DATA::~AFX_GLOBAL_DATA", "AFXGLOBALS/AFX_GLOBAL_DATA::CleanUp", "AFXGLOBALS/AFX_GLOBAL_DATA::D2D1MakeRotateMatrix", "AFXGLOBALS/AFX_GLOBAL_DATA::DrawParentBackground", "AFXGLOBALS/AFX_GLOBAL_DATA::DrawTextOnGlass", "AFXGLOBALS/AFX_GLOBAL_DATA::ExcludeTag", "AFXGLOBALS/AFX_GLOBAL_DATA::GetColor", "AFXGLOBALS/AFX_GLOBAL_DATA::GetDirect2dFactory", "AFXGLOBALS/AFX_GLOBAL_DATA::GetHandCursor", "AFXGLOBALS/AFX_GLOBAL_DATA::GetITaskbarList", "AFXGLOBALS/AFX_GLOBAL_DATA::GetITaskbarList3", "AFXGLOBALS/AFX_GLOBAL_DATA::GetNonClientMetrics", "AFXGLOBALS/AFX_GLOBAL_DATA::GetShellAutohideBars", "AFXGLOBALS/AFX_GLOBAL_DATA::GetTextHeight", "AFXGLOBALS/AFX_GLOBAL_DATA::GetWICFactory", "AFXGLOBALS/AFX_GLOBAL_DATA::GetWriteFactory", "AFXGLOBALS/AFX_GLOBAL_DATA::InitD2D", "AFXGLOBALS/AFX_GLOBAL_DATA::Is32BitIcons", "AFXGLOBALS/AFX_GLOBAL_DATA::IsD2DInitialized", "AFXGLOBALS/AFX_GLOBAL_DATA::IsDwmCompositionEnabled", "AFXGLOBALS/AFX_GLOBAL_DATA::IsHighContrastMode", "AFXGLOBALS/AFX_GLOBAL_DATA::OnSettingChange", "AFXGLOBALS/AFX_GLOBAL_DATA::RegisterWindowClass", "AFXGLOBALS/AFX_GLOBAL_DATA::ReleaseTaskBarRefs", "AFXGLOBALS/AFX_GLOBAL_DATA::Resume", "AFXGLOBALS/AFX_GLOBAL_DATA::SetLayeredAttrib", "AFXGLOBALS/AFX_GLOBAL_DATA::SetMenuFont", "AFXGLOBALS/AFX_GLOBAL_DATA::ShellCreateItemFromParsingName", "AFXGLOBALS/AFX_GLOBAL_DATA::UpdateFonts", "AFXGLOBALS/AFX_GLOBAL_DATA::UpdateSysColors", "AFXGLOBALS/AFX_GLOBAL_DATA::EnableAccessibilitySupport", "AFXGLOBALS/AFX_GLOBAL_DATA::IsAccessibilitySupport", "AFXGLOBALS/AFX_GLOBAL_DATA::IsWindowsLayerSupportAvailable", "AFXGLOBALS/AFX_GLOBAL_DATA::bIsOSAlphaBlendingSupport", "AFXGLOBALS/AFX_GLOBAL_DATA::bIsWindows7", "AFXGLOBALS/AFX_GLOBAL_DATA::clrActiveCaptionGradient", "AFXGLOBALS/AFX_GLOBAL_DATA::clrInactiveCaptionGradient", "AFXGLOBALS/AFX_GLOBAL_DATA::m_bUseBuiltIn32BitIcons", "AFXGLOBALS/AFX_GLOBAL_DATA::m_bUseSystemFont", "AFXGLOBALS/AFX_GLOBAL_DATA::m_hcurHand", "AFXGLOBALS/AFX_GLOBAL_DATA::m_hcurStretch", "AFXGLOBALS/AFX_GLOBAL_DATA::m_hcurStretchVert", "AFXGLOBALS/AFX_GLOBAL_DATA::m_hiconTool", "AFXGLOBALS/AFX_GLOBAL_DATA::m_nAutoHideToolBarMargin", "AFXGLOBALS/AFX_GLOBAL_DATA::m_nAutoHideToolBarSpacing", "AFXGLOBALS/AFX_GLOBAL_DATA::m_nDragFrameThicknessDock", "AFXGLOBALS/AFX_GLOBAL_DATA::m_nDragFrameThicknessFloat"] helpviewer_keywords: ["AFX_GLOBAL_DATA structure [MFC]", "AFX_GLOBAL_DATA constructor"] -ms.assetid: c7abf2fb-ad5e-4336-a01d-260c29ed53a2 --- # AFX_GLOBAL_DATA Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `AFX_GLOBAL_DATA` structure contains fields and methods that are used to manage the framework or customize the appearance and behavior of your application. ## Syntax diff --git a/docs/mfc/reference/afx-messages.md b/docs/mfc/reference/afx-messages.md index 8651a84d6d5..afb7cd8d516 100644 --- a/docs/mfc/reference/afx-messages.md +++ b/docs/mfc/reference/afx-messages.md @@ -4,10 +4,12 @@ title: "AFX Messages" ms.date: "11/04/2016" f1_keywords: ["SB_LINELEFT", "SB_THUMBTRACK", "AFX_TOOLTIP_TYPE_EDIT", "AFX_WM_ON_HSCROLL", "SB_PAGERIGHT", "AFX_WM_RESETPROMPT", "AFX_WM_CHANGE_RIBBON_CATEGORY", "AFX_TOOLTIP_TYPE_MINIFRAME", "AFX_WM_CUSTOMIZETOOLBAR", "AFX_WM_CHANGE_ACTIVE_TAB", "AFX_WM_ACCGETOBJECT", "AFX_WM_TOOLBARMENU", "AFX_TOOLTIP_TYPE_DOCKBAR", "AFX_WM_CUSTOMIZEHELP", "AFX_WM_ON_GET_TAB_TOOLTIP", "AFX_WM_ON_RIBBON_CUSTOMIZE", "AFX_WM_ON_DRAGCOMPLETE", "AFX_WM_RESETTOOLBAR", "AFX_WM_ON_MOVETOTABGROUP", "AFX_WM_CHECKEMPTYMINIFRAME", "AFX_WM_GETDOCUMENTCOLORS", "SB_RIGHT", "AFX_WM_ON_BEFORE_SHOW_RIBBON_ITEM_MENU", "AFX_WM_ACCGETSTATE", "SB_PAGELEFT", "SB_ENDSCROLL", "AFX_WM_ON_CANCELTABMOVE", "AFX_TOOLTIP_TYPE_TAB", "AFX_WM_WINDOW_HELP", "AFX_WM_HIGHLIGHT_RIBBON_LIST_ITEM", "AFX_WM_SHOWREGULARMENU", "AFX_TOOLTIP_TYPE_TOOLBAR", "AFX_WM_CHANGE_CURRENT_FOLDER", "AFX_WM_UPDATETOOLTIPS", "AFX_WM_ON_MOVE_TAB", "AFX_WM_CHANGING_ACTIVE_TAB", "AFX_WM_RESETMENU", "AFX_WM_GETDRAGBOUNDS", "AFX_WM_RESETCONTEXTMENU", "AFX_TOOLTIP_TYPE_BUTTON", "AFX_WM_ON_CLOSEPOPUPWINDOW", "AFX_TOOLTIP_TYPE_TOOLBOX", "AFX_WM_CHANGEVISUALMANAGER", "SB_LINERIGHT", "AFX_WM_ON_RENAME_TAB", "AFX_TOOLTIP_TYPE_DEFAULT", "AFX_WM_ON_TABGROUPMOUSEMOVE", "SB_LEFT", "AFX_WM_DELETETOOLBAR", "AFX_WM_PROPERTY_CHANGED", "AFX_TOOLTIP_TYPE_ALL", "AFX_WM_ACCHITTEST", "AFX_WM_ON_AFTER_SHELL_COMMAND", "AFX_WM_ON_PRESS_CLOSE_BUTTON", "AFX_WM_RESETKEYBOARD", "AFX_WM_ON_MOVETABCOMPLETE", "AFX_WM_CREATETOOLBAR", "SB_THUMBPOSITION", "AFX_WM_POSTSETPREVIEWFRAME"] helpviewer_keywords: ["AFX messages [MFC]"] -ms.assetid: 3d601f3c-af6d-47d3-8553-34f1318fa74f --- # AFX Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These messages are used in MFC. ## Messages diff --git a/docs/mfc/reference/application-control.md b/docs/mfc/reference/application-control.md index b858a4d41b7..94e130be1d1 100644 --- a/docs/mfc/reference/application-control.md +++ b/docs/mfc/reference/application-control.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + OLE requires substantial control over applications and their objects. The OLE system DLLs must be able to launch and release applications automatically, coordinate their production and modification of objects, and so on. The functions in this topic meet those requirements. In addition to being called by the OLE system DLLs, these functions must sometimes be called by applications as well. ### Application Control @@ -67,7 +69,7 @@ Call this function to access the current `COleMessageFilter`-derived object, jus ### Example [!code-cpp[NVC_MFCAutomation#3](../../mfc/codesnippet/cpp/application-control_2.cpp)] - +  [!code-cpp[NVC_MFCAutomation#4](../../mfc/codesnippet/cpp/application-control_3.cpp)] ### Requirements @@ -258,7 +260,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/application-information-and-management.md b/docs/mfc/reference/application-information-and-management.md index cffc7c4c52f..1abddac4368 100644 --- a/docs/mfc/reference/application-information-and-management.md +++ b/docs/mfc/reference/application-information-and-management.md @@ -1,12 +1,14 @@ --- title: "Application Information and Management" description: "Reference to the Microsoft Foundation Class library (MFC) application information and management functions." -ms.date: "01/27/2020" +ms.date: 01/27/2020 helpviewer_keywords: ["applications [MFC], managing"] -ms.assetid: b72f4154-24db-4e75-bca3-6873e2459c15 --- # Application Information and Management +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you write an application, you create a single [`CWinApp`](../../mfc/reference/cwinapp-class.md)-derived object. At times, you may want to get information about this object from outside the `CWinApp`-derived object. Or you may need access to other global "manager" objects. The Microsoft Foundation Class Library provides the following global functions to help you accomplish these tasks: @@ -173,6 +175,7 @@ HINSTANCE AFXAPI AfxFindResourceHandle( LPCTSTR lpszName, LPCTSTR lpszType ); *`lpszName`*\ A pointer to a string containing the resource ID. + *`lpszType`*\ A pointer to the type of resource. For a list of resource types, see [`FindResource`](/windows/win32/api/winbase/nf-winbase-findresourcea) in the Windows SDK. @@ -414,7 +417,7 @@ This function is provided for backward compatibility. New applications should us `AfxInitRichEdit` loads `RICHED32.DLL` to initialize version 1.0 of the rich edit control. To use version 2.0 and 3.0 of the rich edit control, `RICHED20.DLL` needs to be loaded. It's loaded by making a call to [`AfxInitRichEdit2`](#afxinitrichedit2). -To update rich edit controls in existing Visual C++ applications to version 2.0, open the .RC file as text, change the class name of each rich edit control from "`RICHEDIT`" to "`RichEdit20a`". Then replace the call to `AfxInitRichEdit` with `AfxInitRichEdit2`. +To update rich edit controls in existing Visual Studio applications to version 2.0, open the .RC file as text, change the class name of each rich edit control from "`RICHEDIT`" to "`RichEdit20a`". Then replace the call to `AfxInitRichEdit` with `AfxInitRichEdit2`. This function also initializes the common controls library, if the library hasn't already been initialized for the process. If you use the rich edit control directly from your MFC application, call this function to assure that MFC has properly initialized the rich edit control runtime. If you call the `Create` method of [`CRichEditCtrl`](../../mfc/reference/cricheditctrl-class.md), [`CRichEditView`](../../mfc/reference/cricheditview-class.md), or [`CRichEditDoc`](../../mfc/reference/cricheditdoc-class.md), you typically don't need to call this function, but in some cases it might be necessary. diff --git a/docs/mfc/reference/application-settings-mfc-activex-control-wizard.md b/docs/mfc/reference/application-settings-mfc-activex-control-wizard.md index 47132045c6e..c4319681860 100644 --- a/docs/mfc/reference/application-settings-mfc-activex-control-wizard.md +++ b/docs/mfc/reference/application-settings-mfc-activex-control-wizard.md @@ -4,10 +4,12 @@ title: "Application Settings, MFC ActiveX Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.ctl.appset"] helpviewer_keywords: ["MFC ActiveX Control Wizard, application settings"] -ms.assetid: 48475194-cc63-467f-8499-f142269a4c1c --- # Application Settings, MFC ActiveX Control Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use this page of the MFC ActiveX Control Wizard to design and add basic features to a new MFC ActiveX project. These settings apply to the application itself and not to any specific feature or element of the control. - **Run-time license** diff --git a/docs/mfc/reference/application-settings-mfc-dll-wizard.md b/docs/mfc/reference/application-settings-mfc-dll-wizard.md index b954d26d00d..867e12a7058 100644 --- a/docs/mfc/reference/application-settings-mfc-dll-wizard.md +++ b/docs/mfc/reference/application-settings-mfc-dll-wizard.md @@ -4,10 +4,12 @@ title: "Application Settings, MFC DLL Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.dll.appset"] helpviewer_keywords: ["MFC DLL Wizard, application settings"] -ms.assetid: 0a96b94f-ae36-4975-951b-c9ffb3def21c --- # Application Settings, MFC DLL Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use this page of the MFC DLL wizard to design and add basic features to a new MFC DLL project. ## DLL type diff --git a/docs/mfc/reference/application-type-mfc-application-wizard.md b/docs/mfc/reference/application-type-mfc-application-wizard.md index ba1c3c9b273..4619680538f 100644 --- a/docs/mfc/reference/application-type-mfc-application-wizard.md +++ b/docs/mfc/reference/application-type-mfc-application-wizard.md @@ -4,10 +4,12 @@ title: "Application Type, MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.apptype"] helpviewer_keywords: ["static libraries, MFC"] -ms.assetid: c3f62b0e-3f13-42c5-9859-d3890d0c3e1d --- # Application Type, MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use this page of the [MFC Application Wizard](../../mfc/reference/mfc-application-wizard.md) to design and add basic features to a new MFC application. - **Application type** diff --git a/docs/mfc/reference/buffercommand-enumeration.md b/docs/mfc/reference/buffercommand-enumeration.md index 347d457d898..755a0916ae5 100644 --- a/docs/mfc/reference/buffercommand-enumeration.md +++ b/docs/mfc/reference/buffercommand-enumeration.md @@ -7,11 +7,14 @@ helpviewer_keywords: ["buffercommand enumeration [MFC]"] --- # BufferCommand enumeration +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used by [CMemFile::GetBufferPtr](cmemfile-class.md#getbufferptr) to determine what action to take on the file-backed memory buffer. ## Syntax -``` cpp +```cpp public enum BufferCommand { bufferRead, diff --git a/docs/mfc/reference/cacceleratedeceleratetransition-class.md b/docs/mfc/reference/cacceleratedeceleratetransition-class.md index 2a1805bcab4..59271982e96 100644 --- a/docs/mfc/reference/cacceleratedeceleratetransition-class.md +++ b/docs/mfc/reference/cacceleratedeceleratetransition-class.md @@ -4,10 +4,12 @@ title: "CAccelerateDecelerateTransition Class" ms.date: "11/04/2016" f1_keywords: ["CAccelerateDecelerateTransition", "afxanimationcontroller/CAccelerateDecelerateTransition"] helpviewer_keywords: ["CAccelerateDecelerateTransition class [MFC]"] -ms.assetid: b1f31ee8-bb11-4ccc-b124-365fb02b025c --- # CAccelerateDecelerateTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements an accelerate-decelerate transition. ## Syntax diff --git a/docs/mfc/reference/callback-functions-used-by-mfc.md b/docs/mfc/reference/callback-functions-used-by-mfc.md index 48c2ebd5c79..5beda34b607 100644 --- a/docs/mfc/reference/callback-functions-used-by-mfc.md +++ b/docs/mfc/reference/callback-functions-used-by-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Callback Functions Used by MFC" title: "Callback Functions Used by MFC" ms.date: "11/04/2016" helpviewer_keywords: ["callback functions [MFC], MFC", "MFC, callback functions", "functions [MFC], callback", "callback functions [MFC]"] -ms.assetid: b2a6857c-fdd3-45ec-8fd8-2e71fac77582 --- # Callback Functions Used by MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Three callback functions appear in the Microsoft Foundation Class Library. These callback functions are passed to [CDC::EnumObjects](../../mfc/reference/cdc-class.md#enumobjects), [CDC::GrayString](../../mfc/reference/cdc-class.md#graystring), and [CDC::SetAbortProc](../../mfc/reference/cdc-class.md#setabortproc). Note that all callback functions must trap MFC 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). [Callback Function for CDC::EnumObjects](#enum_objects)\ diff --git a/docs/mfc/reference/canimatectrl-class.md b/docs/mfc/reference/canimatectrl-class.md index 15e0d9893a9..5fa507210c2 100644 --- a/docs/mfc/reference/canimatectrl-class.md +++ b/docs/mfc/reference/canimatectrl-class.md @@ -4,10 +4,12 @@ title: "CAnimateCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CAnimateCtrl", "AFXCMN/CAnimateCtrl", "AFXCMN/CAnimateCtrl::CAnimateCtrl", "AFXCMN/CAnimateCtrl::Close", "AFXCMN/CAnimateCtrl::Create", "AFXCMN/CAnimateCtrl::CreateEx", "AFXCMN/CAnimateCtrl::IsPlaying", "AFXCMN/CAnimateCtrl::Open", "AFXCMN/CAnimateCtrl::Play", "AFXCMN/CAnimateCtrl::Seek", "AFXCMN/CAnimateCtrl::Stop"] helpviewer_keywords: ["CAnimateCtrl [MFC], CAnimateCtrl", "CAnimateCtrl [MFC], Close", "CAnimateCtrl [MFC], Create", "CAnimateCtrl [MFC], CreateEx", "CAnimateCtrl [MFC], IsPlaying", "CAnimateCtrl [MFC], Open", "CAnimateCtrl [MFC], Play", "CAnimateCtrl [MFC], Seek", "CAnimateCtrl [MFC], Stop"] -ms.assetid: 5e8eb1bd-96b7-47b8-8de2-6bcbb3cc299b --- # CAnimateCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common animation control. ## Syntax diff --git a/docs/mfc/reference/canimationbaseobject-class.md b/docs/mfc/reference/canimationbaseobject-class.md index cd986f2657d..7177f63f464 100644 --- a/docs/mfc/reference/canimationbaseobject-class.md +++ b/docs/mfc/reference/canimationbaseobject-class.md @@ -4,10 +4,12 @@ title: "CAnimationBaseObject Class" ms.date: "03/27/2019" f1_keywords: ["CAnimationBaseObject", "AFXANIMATIONCONTROLLER/CAnimationBaseObject", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::CAnimationBaseObject", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::ApplyTransitions", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::ClearTransitions", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::ContainsVariable", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::CreateTransitions", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::DetachFromController", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::EnableIntegerValueChangedEvent", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::EnableValueChangedEvent", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::GetAutodestroyTransitions", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::GetGroupID", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::GetObjectID", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::GetUserData", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::SetAutodestroyTransitions", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::SetID", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::SetUserData", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::GetAnimationVariableList", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::SetParentAnimationObjects", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::m_bAutodestroyTransitions", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::m_dwUserData", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::m_nGroupID", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::m_nObjectID", "AFXANIMATIONCONTROLLER/CAnimationBaseObject::m_pParentController"] helpviewer_keywords: ["CAnimationBaseObject [MFC], CAnimationBaseObject", "CAnimationBaseObject [MFC], ApplyTransitions", "CAnimationBaseObject [MFC], ClearTransitions", "CAnimationBaseObject [MFC], ContainsVariable", "CAnimationBaseObject [MFC], CreateTransitions", "CAnimationBaseObject [MFC], DetachFromController", "CAnimationBaseObject [MFC], EnableIntegerValueChangedEvent", "CAnimationBaseObject [MFC], EnableValueChangedEvent", "CAnimationBaseObject [MFC], GetAutodestroyTransitions", "CAnimationBaseObject [MFC], GetGroupID", "CAnimationBaseObject [MFC], GetObjectID", "CAnimationBaseObject [MFC], GetUserData", "CAnimationBaseObject [MFC], SetAutodestroyTransitions", "CAnimationBaseObject [MFC], SetID", "CAnimationBaseObject [MFC], SetUserData", "CAnimationBaseObject [MFC], GetAnimationVariableList", "CAnimationBaseObject [MFC], SetParentAnimationObjects", "CAnimationBaseObject [MFC], m_bAutodestroyTransitions", "CAnimationBaseObject [MFC], m_dwUserData", "CAnimationBaseObject [MFC], m_nGroupID", "CAnimationBaseObject [MFC], m_nObjectID", "CAnimationBaseObject [MFC], m_pParentController"] -ms.assetid: 76b25917-940e-4eba-940f-31d270702603 --- # CAnimationBaseObject Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for all animation objects. ## Syntax diff --git a/docs/mfc/reference/canimationcolor-class.md b/docs/mfc/reference/canimationcolor-class.md index 776a4f94c5a..95cd12e9f5c 100644 --- a/docs/mfc/reference/canimationcolor-class.md +++ b/docs/mfc/reference/canimationcolor-class.md @@ -4,10 +4,12 @@ title: "CAnimationColor Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationColor", "AFXANIMATIONCONTROLLER/CAnimationColor", "AFXANIMATIONCONTROLLER/CAnimationColor::CAnimationColor", "AFXANIMATIONCONTROLLER/CAnimationColor::AddTransition", "AFXANIMATIONCONTROLLER/CAnimationColor::GetB", "AFXANIMATIONCONTROLLER/CAnimationColor::GetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationColor::GetG", "AFXANIMATIONCONTROLLER/CAnimationColor::GetR", "AFXANIMATIONCONTROLLER/CAnimationColor::GetValue", "AFXANIMATIONCONTROLLER/CAnimationColor::SetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationColor::GetAnimationVariableList", "AFXANIMATIONCONTROLLER/CAnimationColor::m_bValue", "AFXANIMATIONCONTROLLER/CAnimationColor::m_gValue", "AFXANIMATIONCONTROLLER/CAnimationColor::m_rValue"] helpviewer_keywords: ["CAnimationColor [MFC], CAnimationColor", "CAnimationColor [MFC], AddTransition", "CAnimationColor [MFC], GetB", "CAnimationColor [MFC], GetDefaultValue", "CAnimationColor [MFC], GetG", "CAnimationColor [MFC], GetR", "CAnimationColor [MFC], GetValue", "CAnimationColor [MFC], SetDefaultValue", "CAnimationColor [MFC], GetAnimationVariableList", "CAnimationColor [MFC], m_bValue", "CAnimationColor [MFC], m_gValue", "CAnimationColor [MFC], m_rValue"] -ms.assetid: 88bfabd4-efeb-4652-87e8-304253d8e48c --- # CAnimationColor Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the functionality of a color whose red, green, and blue components can be animated. ## Syntax diff --git a/docs/mfc/reference/canimationcontroller-class.md b/docs/mfc/reference/canimationcontroller-class.md index efbcb21ccb4..e2fb90bb856 100644 --- a/docs/mfc/reference/canimationcontroller-class.md +++ b/docs/mfc/reference/canimationcontroller-class.md @@ -4,10 +4,12 @@ title: "CAnimationController Class" ms.date: "03/27/2019" f1_keywords: ["CAnimationController", "AFXANIMATIONCONTROLLER/CAnimationController", "AFXANIMATIONCONTROLLER/CAnimationController::CAnimationController", "AFXANIMATIONCONTROLLER/CAnimationController::AddAnimationObject", "AFXANIMATIONCONTROLLER/CAnimationController::AddKeyframeToGroup", "AFXANIMATIONCONTROLLER/CAnimationController::AnimateGroup", "AFXANIMATIONCONTROLLER/CAnimationController::CleanUpGroup", "AFXANIMATIONCONTROLLER/CAnimationController::CreateKeyframe", "AFXANIMATIONCONTROLLER/CAnimationController::EnableAnimationManagerEvent", "AFXANIMATIONCONTROLLER/CAnimationController::EnableAnimationTimerEventHandler", "AFXANIMATIONCONTROLLER/CAnimationController::EnablePriorityComparisonHandler", "AFXANIMATIONCONTROLLER/CAnimationController::EnableStoryboardEventHandler", "AFXANIMATIONCONTROLLER/CAnimationController::FindAnimationGroup", "AFXANIMATIONCONTROLLER/CAnimationController::FindAnimationObject", "AFXANIMATIONCONTROLLER/CAnimationController::GetKeyframeStoryboardStart", "AFXANIMATIONCONTROLLER/CAnimationController::GetUIAnimationManager", "AFXANIMATIONCONTROLLER/CAnimationController::GetUIAnimationTimer", "AFXANIMATIONCONTROLLER/CAnimationController::GetUITransitionFactory", "AFXANIMATIONCONTROLLER/CAnimationController::GetUITransitionLibrary", "AFXANIMATIONCONTROLLER/CAnimationController::IsAnimationInProgress", "AFXANIMATIONCONTROLLER/CAnimationController::IsValid", "AFXANIMATIONCONTROLLER/CAnimationController::OnAnimationIntegerValueChanged", "AFXANIMATIONCONTROLLER/CAnimationController::OnAnimationManagerStatusChanged", "AFXANIMATIONCONTROLLER/CAnimationController::OnAnimationTimerPostUpdate", "AFXANIMATIONCONTROLLER/CAnimationController::OnAnimationTimerPreUpdate", "AFXANIMATIONCONTROLLER/CAnimationController::OnAnimationTimerRenderingTooSlow", "AFXANIMATIONCONTROLLER/CAnimationController::OnAnimationValueChanged", "AFXANIMATIONCONTROLLER/CAnimationController::OnBeforeAnimationStart", "AFXANIMATIONCONTROLLER/CAnimationController::OnHasPriorityCancel", "AFXANIMATIONCONTROLLER/CAnimationController::OnHasPriorityCompress", "AFXANIMATIONCONTROLLER/CAnimationController::OnHasPriorityConclude", "AFXANIMATIONCONTROLLER/CAnimationController::OnHasPriorityTrim", "AFXANIMATIONCONTROLLER/CAnimationController::OnStoryboardStatusChanged", "AFXANIMATIONCONTROLLER/CAnimationController::OnStoryboardUpdated", "AFXANIMATIONCONTROLLER/CAnimationController::RemoveAllAnimationGroups", "AFXANIMATIONCONTROLLER/CAnimationController::RemoveAnimationGroup", "AFXANIMATIONCONTROLLER/CAnimationController::RemoveAnimationObject", "AFXANIMATIONCONTROLLER/CAnimationController::RemoveTransitions", "AFXANIMATIONCONTROLLER/CAnimationController::ScheduleGroup", "AFXANIMATIONCONTROLLER/CAnimationController::SetRelatedWnd", "AFXANIMATIONCONTROLLER/CAnimationController::UpdateAnimationManager", "AFXANIMATIONCONTROLLER/CAnimationController::OnAfterSchedule", "AFXANIMATIONCONTROLLER/CAnimationController::gkeyframeStoryboardStart", "AFXANIMATIONCONTROLLER/CAnimationController::m_bIsValid", "AFXANIMATIONCONTROLLER/CAnimationController::m_lstAnimationGroups", "AFXANIMATIONCONTROLLER/CAnimationController::m_pAnimationManager", "AFXANIMATIONCONTROLLER/CAnimationController::m_pAnimationTimer", "AFXANIMATIONCONTROLLER/CAnimationController::m_pRelatedWnd", "AFXANIMATIONCONTROLLER/CAnimationController::m_pTransitionFactory", "AFXANIMATIONCONTROLLER/CAnimationController::m_pTransitionLibrary"] helpviewer_keywords: ["CAnimationController [MFC], CAnimationController", "CAnimationController [MFC], AddAnimationObject", "CAnimationController [MFC], AddKeyframeToGroup", "CAnimationController [MFC], AnimateGroup", "CAnimationController [MFC], CleanUpGroup", "CAnimationController [MFC], CreateKeyframe", "CAnimationController [MFC], EnableAnimationManagerEvent", "CAnimationController [MFC], EnableAnimationTimerEventHandler", "CAnimationController [MFC], EnablePriorityComparisonHandler", "CAnimationController [MFC], EnableStoryboardEventHandler", "CAnimationController [MFC], FindAnimationGroup", "CAnimationController [MFC], FindAnimationObject", "CAnimationController [MFC], GetKeyframeStoryboardStart", "CAnimationController [MFC], GetUIAnimationManager", "CAnimationController [MFC], GetUIAnimationTimer", "CAnimationController [MFC], GetUITransitionFactory", "CAnimationController [MFC], GetUITransitionLibrary", "CAnimationController [MFC], IsAnimationInProgress", "CAnimationController [MFC], IsValid", "CAnimationController [MFC], OnAnimationIntegerValueChanged", "CAnimationController [MFC], OnAnimationManagerStatusChanged", "CAnimationController [MFC], OnAnimationTimerPostUpdate", "CAnimationController [MFC], OnAnimationTimerPreUpdate", "CAnimationController [MFC], OnAnimationTimerRenderingTooSlow", "CAnimationController [MFC], OnAnimationValueChanged", "CAnimationController [MFC], OnBeforeAnimationStart", "CAnimationController [MFC], OnHasPriorityCancel", "CAnimationController [MFC], OnHasPriorityCompress", "CAnimationController [MFC], OnHasPriorityConclude", "CAnimationController [MFC], OnHasPriorityTrim", "CAnimationController [MFC], OnStoryboardStatusChanged", "CAnimationController [MFC], OnStoryboardUpdated", "CAnimationController [MFC], RemoveAllAnimationGroups", "CAnimationController [MFC], RemoveAnimationGroup", "CAnimationController [MFC], RemoveAnimationObject", "CAnimationController [MFC], RemoveTransitions", "CAnimationController [MFC], ScheduleGroup", "CAnimationController [MFC], SetRelatedWnd", "CAnimationController [MFC], UpdateAnimationManager", "CAnimationController [MFC], CleanUpGroup", "CAnimationController [MFC], OnAfterSchedule", "CAnimationController [MFC], gkeyframeStoryboardStart", "CAnimationController [MFC], m_bIsValid", "CAnimationController [MFC], m_lstAnimationGroups", "CAnimationController [MFC], m_pAnimationManager", "CAnimationController [MFC], m_pAnimationTimer", "CAnimationController [MFC], m_pRelatedWnd", "CAnimationController [MFC], m_pTransitionFactory", "CAnimationController [MFC], m_pTransitionLibrary"] -ms.assetid: ed294c98-695e-40a6-b940-33ef1d40aa6b --- # CAnimationController Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the animation controller, which provides a central interface for creating and managing animations. ## Syntax diff --git a/docs/mfc/reference/canimationgroup-class.md b/docs/mfc/reference/canimationgroup-class.md index ec55261113d..e0465936f07 100644 --- a/docs/mfc/reference/canimationgroup-class.md +++ b/docs/mfc/reference/canimationgroup-class.md @@ -4,10 +4,12 @@ title: "CAnimationGroup Class" ms.date: "03/27/2019" f1_keywords: ["CAnimationGroup", "AFXANIMATIONCONTROLLER/CAnimationGroup", "AFXANIMATIONCONTROLLER/CAnimationGroup::CAnimationGroup", "AFXANIMATIONCONTROLLER/CAnimationGroup::Animate", "AFXANIMATIONCONTROLLER/CAnimationGroup::ApplyTransitions", "AFXANIMATIONCONTROLLER/CAnimationGroup::FindAnimationObject", "AFXANIMATIONCONTROLLER/CAnimationGroup::GetGroupID", "AFXANIMATIONCONTROLLER/CAnimationGroup::RemoveKeyframes", "AFXANIMATIONCONTROLLER/CAnimationGroup::RemoveTransitions", "AFXANIMATIONCONTROLLER/CAnimationGroup::Schedule", "AFXANIMATIONCONTROLLER/CAnimationGroup::SetAutodestroyTransitions", "AFXANIMATIONCONTROLLER/CAnimationGroup::AddKeyframes", "AFXANIMATIONCONTROLLER/CAnimationGroup::AddTransitions", "AFXANIMATIONCONTROLLER/CAnimationGroup::CreateTransitions", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_bAutoclearTransitions", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_bAutodestroyAnimationObjects", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_bAutodestroyKeyframes", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_lstAnimationObjects", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_lstKeyFrames", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_pStoryboard", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_nGroupID", "AFXANIMATIONCONTROLLER/CAnimationGroup::m_pParentController"] helpviewer_keywords: ["CAnimationGroup [MFC], CAnimationGroup", "CAnimationGroup [MFC], Animate", "CAnimationGroup [MFC], ApplyTransitions", "CAnimationGroup [MFC], FindAnimationObject", "CAnimationGroup [MFC], GetGroupID", "CAnimationGroup [MFC], RemoveKeyframes", "CAnimationGroup [MFC], RemoveTransitions", "CAnimationGroup [MFC], Schedule", "CAnimationGroup [MFC], SetAutodestroyTransitions", "CAnimationGroup [MFC], AddKeyframes", "CAnimationGroup [MFC], AddTransitions", "CAnimationGroup [MFC], CreateTransitions", "CAnimationGroup [MFC], m_bAutoclearTransitions", "CAnimationGroup [MFC], m_bAutodestroyAnimationObjects", "CAnimationGroup [MFC], m_bAutodestroyKeyframes", "CAnimationGroup [MFC], m_lstAnimationObjects", "CAnimationGroup [MFC], m_lstKeyFrames", "CAnimationGroup [MFC], m_pStoryboard", "CAnimationGroup [MFC], m_nGroupID", "CAnimationGroup [MFC], m_pParentController"] -ms.assetid: 8bc18ceb-33a2-41d0-9731-71811adacab7 --- # CAnimationGroup Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements an animation group, which combines an animation storyboard, animation objects, and transitions to define an animation. ## Syntax diff --git a/docs/mfc/reference/canimationmanagereventhandler-class.md b/docs/mfc/reference/canimationmanagereventhandler-class.md index 098d5153445..0f734d57cb7 100644 --- a/docs/mfc/reference/canimationmanagereventhandler-class.md +++ b/docs/mfc/reference/canimationmanagereventhandler-class.md @@ -4,10 +4,12 @@ title: "CAnimationManagerEventHandler Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationManagerEventHandler", "AFXANIMATIONCONTROLLER/CAnimationManagerEventHandler", "AFXANIMATIONCONTROLLER/CAnimationManagerEventHandler::CAnimationManagerEventHandler", "AFXANIMATIONCONTROLLER/CAnimationManagerEventHandler::CreateInstance", "AFXANIMATIONCONTROLLER/CAnimationManagerEventHandler::OnManagerStatusChanged", "AFXANIMATIONCONTROLLER/CAnimationManagerEventHandler::SetAnimationController"] helpviewer_keywords: ["CAnimationManagerEventHandler [MFC], CAnimationManagerEventHandler", "CAnimationManagerEventHandler [MFC], CreateInstance", "CAnimationManagerEventHandler [MFC], OnManagerStatusChanged", "CAnimationManagerEventHandler [MFC], SetAnimationController"] -ms.assetid: 6089ec07-e661-4805-b227-823b4652aade --- # CAnimationManagerEventHandler Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a callback, which is called by the Animation API when a status of an animation manager is changed. ## Syntax diff --git a/docs/mfc/reference/canimationpoint-class.md b/docs/mfc/reference/canimationpoint-class.md index 164e739941d..cf1d3ae8466 100644 --- a/docs/mfc/reference/canimationpoint-class.md +++ b/docs/mfc/reference/canimationpoint-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CAnimationPoint [MFC], CAnimationPoint", "CAnimationPoint --- # `CAnimationPoint` class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the functionality of a point whose coordinates can be animated. ## Syntax diff --git a/docs/mfc/reference/canimationrect-class.md b/docs/mfc/reference/canimationrect-class.md index 6d9e450cc35..b2a605299d6 100644 --- a/docs/mfc/reference/canimationrect-class.md +++ b/docs/mfc/reference/canimationrect-class.md @@ -4,10 +4,12 @@ title: "CAnimationRect Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationRect", "AFXANIMATIONCONTROLLER/CAnimationRect", "AFXANIMATIONCONTROLLER/CAnimationRect::CAnimationRect", "AFXANIMATIONCONTROLLER/CAnimationRect::AddTransition", "AFXANIMATIONCONTROLLER/CAnimationRect::GetBottom", "AFXANIMATIONCONTROLLER/CAnimationRect::GetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationRect::GetLeft", "AFXANIMATIONCONTROLLER/CAnimationRect::GetRight", "AFXANIMATIONCONTROLLER/CAnimationRect::GetTop", "AFXANIMATIONCONTROLLER/CAnimationRect::GetValue", "AFXANIMATIONCONTROLLER/CAnimationRect::SetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationRect::GetAnimationVariableList", "AFXANIMATIONCONTROLLER/CAnimationRect::m_bFixedSize", "AFXANIMATIONCONTROLLER/CAnimationRect::m_bottomValue", "AFXANIMATIONCONTROLLER/CAnimationRect::m_leftValue", "AFXANIMATIONCONTROLLER/CAnimationRect::m_rightValue", "AFXANIMATIONCONTROLLER/CAnimationRect::m_szInitial", "AFXANIMATIONCONTROLLER/CAnimationRect::m_topValue"] helpviewer_keywords: ["CAnimationRect [MFC], CAnimationRect", "CAnimationRect [MFC], AddTransition", "CAnimationRect [MFC], GetBottom", "CAnimationRect [MFC], GetDefaultValue", "CAnimationRect [MFC], GetLeft", "CAnimationRect [MFC], GetRight", "CAnimationRect [MFC], GetTop", "CAnimationRect [MFC], GetValue", "CAnimationRect [MFC], SetDefaultValue", "CAnimationRect [MFC], GetAnimationVariableList", "CAnimationRect [MFC], m_bFixedSize", "CAnimationRect [MFC], m_bottomValue", "CAnimationRect [MFC], m_leftValue", "CAnimationRect [MFC], m_rightValue", "CAnimationRect [MFC], m_szInitial", "CAnimationRect [MFC], m_topValue"] -ms.assetid: 0294156d-241e-4a57-92b2-31234fe557d6 --- # CAnimationRect Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the functionality of a rectangle whose sides can be animated. ## Syntax diff --git a/docs/mfc/reference/canimationsize-class.md b/docs/mfc/reference/canimationsize-class.md index e918efbaef0..898c45342db 100644 --- a/docs/mfc/reference/canimationsize-class.md +++ b/docs/mfc/reference/canimationsize-class.md @@ -4,10 +4,12 @@ title: "CAnimationSize Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationSize", "AFXANIMATIONCONTROLLER/CAnimationSize", "AFXANIMATIONCONTROLLER/CAnimationSize::CAnimationSize", "AFXANIMATIONCONTROLLER/CAnimationSize::AddTransition", "AFXANIMATIONCONTROLLER/CAnimationSize::GetCX", "AFXANIMATIONCONTROLLER/CAnimationSize::GetCY", "AFXANIMATIONCONTROLLER/CAnimationSize::GetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationSize::GetValue", "AFXANIMATIONCONTROLLER/CAnimationSize::SetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationSize::GetAnimationVariableList", "AFXANIMATIONCONTROLLER/CAnimationSize::m_cxValue", "AFXANIMATIONCONTROLLER/CAnimationSize::m_cyValue"] helpviewer_keywords: ["CAnimationSize [MFC], CAnimationSize", "CAnimationSize [MFC], AddTransition", "CAnimationSize [MFC], GetCX", "CAnimationSize [MFC], GetCY", "CAnimationSize [MFC], GetDefaultValue", "CAnimationSize [MFC], GetValue", "CAnimationSize [MFC], SetDefaultValue", "CAnimationSize [MFC], GetAnimationVariableList", "CAnimationSize [MFC], m_cxValue", "CAnimationSize [MFC], m_cyValue"] -ms.assetid: ea06d1b5-502c-44a3-82ca-8bd6ba6a9364 --- # CAnimationSize Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the functionality of a size object whose dimensions can be animated. ## Syntax diff --git a/docs/mfc/reference/canimationstoryboardeventhandler-class.md b/docs/mfc/reference/canimationstoryboardeventhandler-class.md index 24d9635f462..e7d70c17056 100644 --- a/docs/mfc/reference/canimationstoryboardeventhandler-class.md +++ b/docs/mfc/reference/canimationstoryboardeventhandler-class.md @@ -4,10 +4,12 @@ title: "CAnimationStoryboardEventHandler Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationStoryboardEventHandler", "AFXANIMATIONCONTROLLER/CAnimationStoryboardEventHandler", "AFXANIMATIONCONTROLLER/CAnimationStoryboardEventHandler::CAnimationStoryboardEventHandler", "AFXANIMATIONCONTROLLER/CAnimationStoryboardEventHandler::CreateInstance", "AFXANIMATIONCONTROLLER/CAnimationStoryboardEventHandler::OnStoryboardStatusChanged", "AFXANIMATIONCONTROLLER/CAnimationStoryboardEventHandler::OnStoryboardUpdated", "AFXANIMATIONCONTROLLER/CAnimationStoryboardEventHandler::SetAnimationController"] helpviewer_keywords: ["CAnimationStoryboardEventHandler [MFC], CAnimationStoryboardEventHandler", "CAnimationStoryboardEventHandler [MFC], CreateInstance", "CAnimationStoryboardEventHandler [MFC], OnStoryboardStatusChanged", "CAnimationStoryboardEventHandler [MFC], OnStoryboardUpdated", "CAnimationStoryboardEventHandler [MFC], SetAnimationController"] -ms.assetid: 10a7e86b-c02d-4124-9a2e-61ecf8ac62fc --- # CAnimationStoryboardEventHandler Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a callback, which is called by the Animation API when the status of a storyboard is changed or a storyboard is updated. ## Syntax diff --git a/docs/mfc/reference/canimationtimereventhandler-class.md b/docs/mfc/reference/canimationtimereventhandler-class.md index ba43bc2b92c..c81fac2c402 100644 --- a/docs/mfc/reference/canimationtimereventhandler-class.md +++ b/docs/mfc/reference/canimationtimereventhandler-class.md @@ -4,10 +4,12 @@ title: "CAnimationTimerEventHandler Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationTimerEventHandler", "AFXANIMATIONCONTROLLER/CAnimationTimerEventHandler", "AFXANIMATIONCONTROLLER/CAnimationTimerEventHandler::CreateInstance", "AFXANIMATIONCONTROLLER/CAnimationTimerEventHandler::OnPostUpdate", "AFXANIMATIONCONTROLLER/CAnimationTimerEventHandler::OnPreUpdate", "AFXANIMATIONCONTROLLER/CAnimationTimerEventHandler::OnRenderingTooSlow", "AFXANIMATIONCONTROLLER/CAnimationTimerEventHandler::SetAnimationController"] helpviewer_keywords: ["CAnimationTimerEventHandler [MFC], CreateInstance", "CAnimationTimerEventHandler [MFC], OnPostUpdate", "CAnimationTimerEventHandler [MFC], OnPreUpdate", "CAnimationTimerEventHandler [MFC], OnRenderingTooSlow", "CAnimationTimerEventHandler [MFC], SetAnimationController"] -ms.assetid: 188dea3b-4b5e-4f6b-8df9-09d993a21619 --- # CAnimationTimerEventHandler Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a callback, which is called by the Animation API when timing events occur. ## Syntax diff --git a/docs/mfc/reference/canimationvalue-class.md b/docs/mfc/reference/canimationvalue-class.md index 30fc884931c..e18d055b2e6 100644 --- a/docs/mfc/reference/canimationvalue-class.md +++ b/docs/mfc/reference/canimationvalue-class.md @@ -4,10 +4,12 @@ title: "CAnimationValue Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationValue", "AFXANIMATIONCONTROLLER/CAnimationValue", "AFXANIMATIONCONTROLLER/CAnimationValue::CAnimationValue", "AFXANIMATIONCONTROLLER/CAnimationValue::AddTransition", "AFXANIMATIONCONTROLLER/CAnimationValue::GetValue", "AFXANIMATIONCONTROLLER/CAnimationValue::GetVariable", "AFXANIMATIONCONTROLLER/CAnimationValue::SetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationValue::GetAnimationVariableList", "AFXANIMATIONCONTROLLER/CAnimationValue::m_value"] helpviewer_keywords: ["CAnimationValue [MFC], CAnimationValue", "CAnimationValue [MFC], AddTransition", "CAnimationValue [MFC], GetValue", "CAnimationValue [MFC], GetVariable", "CAnimationValue [MFC], SetDefaultValue", "CAnimationValue [MFC], GetAnimationVariableList", "CAnimationValue [MFC], m_value"] -ms.assetid: 78c5ae19-ede5-4f20-bfbe-68b467b603c2 --- # CAnimationValue Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the functionality of animation object that has one value. ## Syntax diff --git a/docs/mfc/reference/canimationvariable-class.md b/docs/mfc/reference/canimationvariable-class.md index 2e6c644481f..cc9ff75a44b 100644 --- a/docs/mfc/reference/canimationvariable-class.md +++ b/docs/mfc/reference/canimationvariable-class.md @@ -4,10 +4,12 @@ title: "CAnimationVariable Class" ms.date: "03/27/2019" f1_keywords: ["CAnimationVariable", "AFXANIMATIONCONTROLLER/CAnimationVariable", "AFXANIMATIONCONTROLLER/CAnimationVariable::CAnimationVariable", "AFXANIMATIONCONTROLLER/CAnimationVariable::AddTransition", "AFXANIMATIONCONTROLLER/CAnimationVariable::ApplyTransitions", "AFXANIMATIONCONTROLLER/CAnimationVariable::ClearTransitions", "AFXANIMATIONCONTROLLER/CAnimationVariable::Create", "AFXANIMATIONCONTROLLER/CAnimationVariable::CreateTransitions", "AFXANIMATIONCONTROLLER/CAnimationVariable::EnableIntegerValueChangedEvent", "AFXANIMATIONCONTROLLER/CAnimationVariable::EnableValueChangedEvent", "AFXANIMATIONCONTROLLER/CAnimationVariable::GetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationVariable::GetParentAnimationObject", "AFXANIMATIONCONTROLLER/CAnimationVariable::GetValue", "AFXANIMATIONCONTROLLER/CAnimationVariable::GetVariable", "AFXANIMATIONCONTROLLER/CAnimationVariable::SetDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationVariable::SetParentAnimationObject", "AFXANIMATIONCONTROLLER/CAnimationVariable::m_bAutodestroyTransitions", "AFXANIMATIONCONTROLLER/CAnimationVariable::m_dblDefaultValue", "AFXANIMATIONCONTROLLER/CAnimationVariable::m_lstTransitions", "AFXANIMATIONCONTROLLER/CAnimationVariable::m_pParentObject", "AFXANIMATIONCONTROLLER/CAnimationVariable::m_variable"] helpviewer_keywords: ["CAnimationVariable [MFC], CAnimationVariable", "CAnimationVariable [MFC], AddTransition", "CAnimationVariable [MFC], ApplyTransitions", "CAnimationVariable [MFC], ClearTransitions", "CAnimationVariable [MFC], Create", "CAnimationVariable [MFC], CreateTransitions", "CAnimationVariable [MFC], EnableIntegerValueChangedEvent", "CAnimationVariable [MFC], EnableValueChangedEvent", "CAnimationVariable [MFC], GetDefaultValue", "CAnimationVariable [MFC], GetParentAnimationObject", "CAnimationVariable [MFC], GetValue", "CAnimationVariable [MFC], GetVariable", "CAnimationVariable [MFC], SetDefaultValue", "CAnimationVariable [MFC], SetParentAnimationObject", "CAnimationVariable [MFC], m_bAutodestroyTransitions", "CAnimationVariable [MFC], m_dblDefaultValue", "CAnimationVariable [MFC], m_lstTransitions", "CAnimationVariable [MFC], m_pParentObject", "CAnimationVariable [MFC], m_variable"] -ms.assetid: 506e697e-31a8-4033-a27e-292f4d7b42d9 --- # CAnimationVariable Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an animation variable. ## Syntax diff --git a/docs/mfc/reference/canimationvariablechangehandler-class.md b/docs/mfc/reference/canimationvariablechangehandler-class.md index 1ddcd351281..8b5b4aca7d5 100644 --- a/docs/mfc/reference/canimationvariablechangehandler-class.md +++ b/docs/mfc/reference/canimationvariablechangehandler-class.md @@ -4,10 +4,12 @@ title: "CAnimationVariableChangeHandler Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationVariableChangeHandler", "AFXANIMATIONCONTROLLER/CAnimationVariableChangeHandler", "AFXANIMATIONCONTROLLER/CAnimationVariableChangeHandler::OnValueChanged", "AFXANIMATIONCONTROLLER/CAnimationVariableChangeHandler::SetAnimationController"] helpviewer_keywords: ["CAnimationVariableChangeHandler [MFC], OnValueChanged", "CAnimationVariableChangeHandler [MFC], SetAnimationController"] -ms.assetid: 2ea4996d-5c04-4dfc-be79-d42d55050795 --- # CAnimationVariableChangeHandler Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a callback, which is called by the Animation API when the value of an animation variable changes. ## Syntax diff --git a/docs/mfc/reference/canimationvariableintegerchangehandler-class.md b/docs/mfc/reference/canimationvariableintegerchangehandler-class.md index 4dfd846fcaa..bfda12cf2d4 100644 --- a/docs/mfc/reference/canimationvariableintegerchangehandler-class.md +++ b/docs/mfc/reference/canimationvariableintegerchangehandler-class.md @@ -4,10 +4,12 @@ title: "CAnimationVariableIntegerChangeHandler Class" ms.date: "11/04/2016" f1_keywords: ["CAnimationVariableIntegerChangeHandler", "AFXANIMATIONCONTROLLER/CAnimationVariableIntegerChangeHandler", "AFXANIMATIONCONTROLLER/CAnimationVariableIntegerChangeHandler::CAnimationVariableIntegerChangeHandler", "AFXANIMATIONCONTROLLER/CAnimationVariableIntegerChangeHandler::CreateInstance", "AFXANIMATIONCONTROLLER/CAnimationVariableIntegerChangeHandler::OnIntegerValueChanged", "AFXANIMATIONCONTROLLER/CAnimationVariableIntegerChangeHandler::SetAnimationController"] helpviewer_keywords: ["CAnimationVariableIntegerChangeHandler [MFC], CAnimationVariableIntegerChangeHandler", "CAnimationVariableIntegerChangeHandler [MFC], CreateInstance", "CAnimationVariableIntegerChangeHandler [MFC], OnIntegerValueChanged", "CAnimationVariableIntegerChangeHandler [MFC], SetAnimationController"] -ms.assetid: 6ac8e91b-e514-4ff6-babd-33f77c4b2b61 --- # CAnimationVariableIntegerChangeHandler Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a callback, which is called by the Animation API when the value of an animation variable changes. ## Syntax diff --git a/docs/mfc/reference/carchive-class.md b/docs/mfc/reference/carchive-class.md index 637d0a6d484..26b7fbc409d 100644 --- a/docs/mfc/reference/carchive-class.md +++ b/docs/mfc/reference/carchive-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CArchive` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows you to save a complex network of objects in a permanent binary form (usually disk storage) that persists after those objects are deleted. ## Syntax @@ -74,7 +77,7 @@ You must create a [`CFile`](../../mfc/reference/cfile-class.md) object before yo When you construct a `CArchive` object, you attach it to an object of class `CFile` (or a derived class) that represents an open file. You also specify whether the archive will be used for loading or storing. A `CArchive` object can process not only primitive types but also objects of [`CObject`](../../mfc/reference/cobject-class.md)-derived classes designed for serialization. A serializable class usually has a `Serialize` member function, and it usually uses the [`DECLARE_SERIAL`](../../mfc/reference/run-time-object-model-services.md#declare_serial) and [`IMPLEMENT_SERIAL`](../../mfc/reference/run-time-object-model-services.md#implement_serial) macros, as described under class `CObject`. -The overloaded extraction ( `>>`) and insertion ( `<<`) operators are convenient archive programming interfaces that support both primitive types and `CObject`-derived classes. +The overloaded extraction (`>>`) and insertion (`<<`) operators are convenient archive programming interfaces that support both primitive types and `CObject`-derived classes. `CArchive` also supports programming with the MFC Windows Sockets classes [`CSocket`](../../mfc/reference/csocket-class.md) and [`CSocketFile`](../../mfc/reference/csocketfile-class.md). The [`IsBufferEmpty`](#isbufferempty) member function supports that usage. @@ -310,11 +313,11 @@ You can call `MapObject` when you store to and load from the `CArchive` object. ### Example [!code-cpp[NVC_MFCSerialization#18](../../mfc/codesnippet/cpp/carchive-class_7.h)] - +  [!code-cpp[NVC_MFCSerialization#19](../../mfc/codesnippet/cpp/carchive-class_8.cpp)] - +  [!code-cpp[NVC_MFCSerialization#20](../../mfc/codesnippet/cpp/carchive-class_9.h)] - +  [!code-cpp[NVC_MFCSerialization#21](../../mfc/codesnippet/cpp/carchive-class_10.cpp)] ## `CArchive::m_pDocument` @@ -570,7 +573,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 +784,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/carchiveexception-class.md b/docs/mfc/reference/carchiveexception-class.md index dca7aacee89..f16ea647f26 100644 --- a/docs/mfc/reference/carchiveexception-class.md +++ b/docs/mfc/reference/carchiveexception-class.md @@ -4,10 +4,12 @@ title: "CArchiveException Class" ms.date: "11/04/2016" f1_keywords: ["CArchiveException", "AFX/CArchiveException", "AFX/CArchiveException::CArchiveException", "AFX/CArchiveException::m_cause", "AFX/CArchiveException::m_strFileName"] helpviewer_keywords: ["CArchiveException [MFC], CArchiveException", "CArchiveException [MFC], m_cause", "CArchiveException [MFC], m_strFileName"] -ms.assetid: da31a127-e86c-41d1-b0b6-bed0865b1b49 --- # CArchiveException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a serialization exception condition ## Syntax diff --git a/docs/mfc/reference/carray-class.md b/docs/mfc/reference/carray-class.md index 20596963732..0ebc44e38fc 100644 --- a/docs/mfc/reference/carray-class.md +++ b/docs/mfc/reference/carray-class.md @@ -4,10 +4,12 @@ title: "CArray Class" ms.date: "11/04/2016" f1_keywords: ["CArray", "AFXTEMPL/CArray", "AFXTEMPL/CArray::CArray", "AFXTEMPL/CArray::Add", "AFXTEMPL/CArray::Append", "AFXTEMPL/CArray::Copy", "AFXTEMPL/CArray::ElementAt", "AFXTEMPL/CArray::FreeExtra", "AFXTEMPL/CArray::GetAt", "AFXTEMPL/CArray::GetCount", "AFXTEMPL/CArray::GetData", "AFXTEMPL/CArray::GetSize", "AFXTEMPL/CArray::GetUpperBound", "AFXTEMPL/CArray::InsertAt", "AFXTEMPL/CArray::IsEmpty", "AFXTEMPL/CArray::RemoveAll", "AFXTEMPL/CArray::RemoveAt", "AFXTEMPL/CArray::SetAt", "AFXTEMPL/CArray::SetAtGrow", "AFXTEMPL/CArray::SetSize"] helpviewer_keywords: ["CArray [MFC], CArray", "CArray [MFC], Add", "CArray [MFC], Append", "CArray [MFC], Copy", "CArray [MFC], ElementAt", "CArray [MFC], FreeExtra", "CArray [MFC], GetAt", "CArray [MFC], GetCount", "CArray [MFC], GetData", "CArray [MFC], GetSize", "CArray [MFC], GetUpperBound", "CArray [MFC], InsertAt", "CArray [MFC], IsEmpty", "CArray [MFC], RemoveAll", "CArray [MFC], RemoveAt", "CArray [MFC], SetAt", "CArray [MFC], SetAtGrow", "CArray [MFC], SetSize"] -ms.assetid: fead8b00-4cfd-4625-ad0e-251df62ba92f --- # `CArray` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports arrays that are like C arrays, but can dynamically reduce and grow as necessary. ## Syntax diff --git a/docs/mfc/reference/casyncmonikerfile-class.md b/docs/mfc/reference/casyncmonikerfile-class.md index 609962a7759..e5ea9ddca36 100644 --- a/docs/mfc/reference/casyncmonikerfile-class.md +++ b/docs/mfc/reference/casyncmonikerfile-class.md @@ -4,10 +4,12 @@ title: "CAsyncMonikerFile Class" ms.date: "11/04/2016" f1_keywords: ["CAsyncMonikerFile", "AFXOLE/CAsyncMonikerFile", "AFXOLE/CAsyncMonikerFile::CAsyncMonikerFile", "AFXOLE/CAsyncMonikerFile::Close", "AFXOLE/CAsyncMonikerFile::GetBinding", "AFXOLE/CAsyncMonikerFile::GetFormatEtc", "AFXOLE/CAsyncMonikerFile::Open", "AFXOLE/CAsyncMonikerFile::CreateBindStatusCallback", "AFXOLE/CAsyncMonikerFile::GetBindInfo", "AFXOLE/CAsyncMonikerFile::GetPriority", "AFXOLE/CAsyncMonikerFile::OnDataAvailable", "AFXOLE/CAsyncMonikerFile::OnLowResource", "AFXOLE/CAsyncMonikerFile::OnProgress", "AFXOLE/CAsyncMonikerFile::OnStartBinding", "AFXOLE/CAsyncMonikerFile::OnStopBinding"] helpviewer_keywords: ["CAsyncMonikerFile [MFC], CAsyncMonikerFile", "CAsyncMonikerFile [MFC], Close", "CAsyncMonikerFile [MFC], GetBinding", "CAsyncMonikerFile [MFC], GetFormatEtc", "CAsyncMonikerFile [MFC], Open", "CAsyncMonikerFile [MFC], CreateBindStatusCallback", "CAsyncMonikerFile [MFC], GetBindInfo", "CAsyncMonikerFile [MFC], GetPriority", "CAsyncMonikerFile [MFC], OnDataAvailable", "CAsyncMonikerFile [MFC], OnLowResource", "CAsyncMonikerFile [MFC], OnProgress", "CAsyncMonikerFile [MFC], OnStartBinding", "CAsyncMonikerFile [MFC], OnStopBinding"] -ms.assetid: 17378b66-a49a-4b67-88e3-7756ad26a2fc --- # CAsyncMonikerFile Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides functionality for the use of asynchronous monikers in ActiveX controls (formerly OLE controls). ## Syntax diff --git a/docs/mfc/reference/casyncsocket-class.md b/docs/mfc/reference/casyncsocket-class.md index d68ce7630fd..a88cc1ed46a 100644 --- a/docs/mfc/reference/casyncsocket-class.md +++ b/docs/mfc/reference/casyncsocket-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a Windows Socket — an endpoint of network communication. ## Syntax @@ -844,7 +846,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/cautohidedocksite-class.md b/docs/mfc/reference/cautohidedocksite-class.md index 9b588d7bbf0..87b68fc1d17 100644 --- a/docs/mfc/reference/cautohidedocksite-class.md +++ b/docs/mfc/reference/cautohidedocksite-class.md @@ -4,10 +4,12 @@ title: "CAutoHideDockSite Class" ms.date: "11/04/2016" f1_keywords: ["CAutoHideDockSite", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::CanAcceptPane", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::DockPane", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::GetAlignRect", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::RepositionPanes", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::SetOffsetLeft", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::SetOffsetRight", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::UnSetAutoHideMode", "AFXAUTOHIDEDOCKSITE/CAutoHideDockSite::m_nExtraSpace"] helpviewer_keywords: ["CAutoHideDockSite [MFC], CanAcceptPane", "CAutoHideDockSite [MFC], DockPane", "CAutoHideDockSite [MFC], GetAlignRect", "CAutoHideDockSite [MFC], RepositionPanes", "CAutoHideDockSite [MFC], SetOffsetLeft", "CAutoHideDockSite [MFC], SetOffsetRight", "CAutoHideDockSite [MFC], UnSetAutoHideMode", "CAutoHideDockSite [MFC], m_nExtraSpace"] -ms.assetid: 2a0f6bec-c369-4ab7-977d-564e7946ebad --- # CAutoHideDockSite Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CAutoHideDockSite` extends the [CDockSite Class](../../mfc/reference/cdocksite-class.md) to implement auto-hide dock panes. ## Syntax diff --git a/docs/mfc/reference/cbasekeyframe-class.md b/docs/mfc/reference/cbasekeyframe-class.md index 03a3f495639..db616828987 100644 --- a/docs/mfc/reference/cbasekeyframe-class.md +++ b/docs/mfc/reference/cbasekeyframe-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the basic functionality of a keyframe. ## Syntax @@ -115,7 +117,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 b2c88c5ae6d..0f46768977e 100644 --- a/docs/mfc/reference/cbasepane-class.md +++ b/docs/mfc/reference/cbasepane-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Base class for all panes in MFC. ## Syntax @@ -80,7 +82,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.| @@ -566,8 +568,8 @@ The library adds several new styles for panes. The following table describes the |AFX_CBRS_RESIZE|The pane can be resized. **Important:** This style is not implemented.| |AFX_CBRS_CLOSE|The pane can be closed.| |AFX_CBRS_AUTO_ROLLUP|The pane can be rolled up when it floats.| -|AFX_CBRS_REGULAR_TABS|When one pane docks to another pane that has this style, a regular tabbed window is created. (For more information, see [CTabbedPane Class](../../mfc/reference/ctabbedpane-class.md).)| -|AFX_CBRS_OUTLOOK_TABS|When one pane docks to another pane that has this style, an Outlook-style tabbed window is created. (For more information, see [CMFCOutlookBar Class](../../mfc/reference/cmfcoutlookbar-class.md).)| +|AFX_CBRS_REGULAR_TABS|When one pane docks to another pane that has this style, a regular tabbed window is created. For more information, see [CTabbedPane Class](../../mfc/reference/ctabbedpane-class.md).| +|AFX_CBRS_OUTLOOK_TABS|When one pane docks to another pane that has this style, an Outlook-style tabbed window is created. For more information, see [CMFCOutlookBar Class](../../mfc/reference/cmfcoutlookbar-class.md).| To use the new styles, specify them in *dwControlBarStyle*. @@ -892,7 +894,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 +969,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/cbasetabbedpane-class.md b/docs/mfc/reference/cbasetabbedpane-class.md index 22e01b013fc..ce0f9df952f 100644 --- a/docs/mfc/reference/cbasetabbedpane-class.md +++ b/docs/mfc/reference/cbasetabbedpane-class.md @@ -4,10 +4,12 @@ title: "CBaseTabbedPane Class" ms.date: "11/04/2016" f1_keywords: ["CBaseTabbedPane", "AFXBASETABBEDPANE/CBaseTabbedPane", "AFXBASETABBEDPANE/CBaseTabbedPane::AddTab", "AFXBASETABBEDPANE/CBaseTabbedPane::AllowDestroyEmptyTabbedPane", "AFXBASETABBEDPANE/CBaseTabbedPane::ApplyRestoredTabInfo", "AFXBASETABBEDPANE/CBaseTabbedPane::CanFloat", "AFXBASETABBEDPANE/CBaseTabbedPane::CanSetCaptionTextToTabName", "AFXBASETABBEDPANE/CBaseTabbedPane::ConvertToTabbedDocument", "AFXBASETABBEDPANE/CBaseTabbedPane::DetachPane", "AFXBASETABBEDPANE/CBaseTabbedPane::EnableSetCaptionTextToTabName", "AFXBASETABBEDPANE/CBaseTabbedPane::FillDefaultTabsOrderArray", "AFXBASETABBEDPANE/CBaseTabbedPane::FindBarByTabNumber", "AFXBASETABBEDPANE/CBaseTabbedPane::FindPaneByID", "AFXBASETABBEDPANE/CBaseTabbedPane::FloatTab", "AFXBASETABBEDPANE/CBaseTabbedPane::GetDefaultTabsOrder", "AFXBASETABBEDPANE/CBaseTabbedPane::GetFirstVisibleTab", "AFXBASETABBEDPANE/CBaseTabbedPane::GetMinSize", "AFXBASETABBEDPANE/CBaseTabbedPane::GetPaneIcon", "AFXBASETABBEDPANE/CBaseTabbedPane::GetPaneList", "AFXBASETABBEDPANE/CBaseTabbedPane::GetTabArea", "AFXBASETABBEDPANE/CBaseTabbedPane::GetTabsNum", "AFXBASETABBEDPANE/CBaseTabbedPane::GetUnderlyingWindow", "AFXBASETABBEDPANE/CBaseTabbedPane::GetVisibleTabsNum", "AFXBASETABBEDPANE/CBaseTabbedPane::HasAutoHideMode", "AFXBASETABBEDPANE/CBaseTabbedPane::IsHideSingleTab", "AFXBASETABBEDPANE/CBaseTabbedPane::RecalcLayout", "AFXBASETABBEDPANE/CBaseTabbedPane::RemovePane", "AFXBASETABBEDPANE/CBaseTabbedPane::SetAutoDestroy", "AFXBASETABBEDPANE/CBaseTabbedPane::SetAutoHideMode", "AFXBASETABBEDPANE/CBaseTabbedPane::ShowTab"] helpviewer_keywords: ["CBaseTabbedPane [MFC], AddTab", "CBaseTabbedPane [MFC], AllowDestroyEmptyTabbedPane", "CBaseTabbedPane [MFC], ApplyRestoredTabInfo", "CBaseTabbedPane [MFC], CanFloat", "CBaseTabbedPane [MFC], CanSetCaptionTextToTabName", "CBaseTabbedPane [MFC], ConvertToTabbedDocument", "CBaseTabbedPane [MFC], DetachPane", "CBaseTabbedPane [MFC], EnableSetCaptionTextToTabName", "CBaseTabbedPane [MFC], FillDefaultTabsOrderArray", "CBaseTabbedPane [MFC], FindBarByTabNumber", "CBaseTabbedPane [MFC], FindPaneByID", "CBaseTabbedPane [MFC], FloatTab", "CBaseTabbedPane [MFC], GetDefaultTabsOrder", "CBaseTabbedPane [MFC], GetFirstVisibleTab", "CBaseTabbedPane [MFC], GetMinSize", "CBaseTabbedPane [MFC], GetPaneIcon", "CBaseTabbedPane [MFC], GetPaneList", "CBaseTabbedPane [MFC], GetTabArea", "CBaseTabbedPane [MFC], GetTabsNum", "CBaseTabbedPane [MFC], GetUnderlyingWindow", "CBaseTabbedPane [MFC], GetVisibleTabsNum", "CBaseTabbedPane [MFC], HasAutoHideMode", "CBaseTabbedPane [MFC], IsHideSingleTab", "CBaseTabbedPane [MFC], RecalcLayout", "CBaseTabbedPane [MFC], RemovePane", "CBaseTabbedPane [MFC], SetAutoDestroy", "CBaseTabbedPane [MFC], SetAutoHideMode", "CBaseTabbedPane [MFC], ShowTab"] -ms.assetid: f22c0080-5b29-4a0a-8f74-8f0a4cd2dbcf --- # CBaseTabbedPane Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Extends the functionality of the [CDockablePane Class](../../mfc/reference/cdockablepane-class.md) to support the creation of tabbed windows. ## Syntax diff --git a/docs/mfc/reference/cbasetransition-class.md b/docs/mfc/reference/cbasetransition-class.md index 83787986692..1fcad2c2626 100644 --- a/docs/mfc/reference/cbasetransition-class.md +++ b/docs/mfc/reference/cbasetransition-class.md @@ -4,10 +4,12 @@ title: "CBaseTransition Class" ms.date: "03/27/2019" f1_keywords: ["CBaseTransition", "AFXANIMATIONCONTROLLER/CBaseTransition", "AFXANIMATIONCONTROLLER/CBaseTransition::CBaseTransition", "AFXANIMATIONCONTROLLER/CBaseTransition::AddToStoryboard", "AFXANIMATIONCONTROLLER/CBaseTransition::AddToStoryboardAtKeyframes", "AFXANIMATIONCONTROLLER/CBaseTransition::Clear", "AFXANIMATIONCONTROLLER/CBaseTransition::Create", "AFXANIMATIONCONTROLLER/CBaseTransition::GetEndKeyframe", "AFXANIMATIONCONTROLLER/CBaseTransition::GetRelatedVariable", "AFXANIMATIONCONTROLLER/CBaseTransition::GetStartKeyframe", "AFXANIMATIONCONTROLLER/CBaseTransition::GetTransition", "AFXANIMATIONCONTROLLER/CBaseTransition::GetType", "AFXANIMATIONCONTROLLER/CBaseTransition::IsAdded", "AFXANIMATIONCONTROLLER/CBaseTransition::SetKeyframes", "AFXANIMATIONCONTROLLER/CBaseTransition::SetRelatedVariable", "AFXANIMATIONCONTROLLER/CBaseTransition::m_bAdded", "AFXANIMATIONCONTROLLER/CBaseTransition::m_pEndKeyframe", "AFXANIMATIONCONTROLLER/CBaseTransition::m_pRelatedVariable", "AFXANIMATIONCONTROLLER/CBaseTransition::m_pStartKeyframe", "AFXANIMATIONCONTROLLER/CBaseTransition::m_transition", "AFXANIMATIONCONTROLLER/CBaseTransition::m_type"] helpviewer_keywords: ["CBaseTransition [MFC], CBaseTransition", "CBaseTransition [MFC], AddToStoryboard", "CBaseTransition [MFC], AddToStoryboardAtKeyframes", "CBaseTransition [MFC], Clear", "CBaseTransition [MFC], Create", "CBaseTransition [MFC], GetEndKeyframe", "CBaseTransition [MFC], GetRelatedVariable", "CBaseTransition [MFC], GetStartKeyframe", "CBaseTransition [MFC], GetTransition", "CBaseTransition [MFC], GetType", "CBaseTransition [MFC], IsAdded", "CBaseTransition [MFC], SetKeyframes", "CBaseTransition [MFC], SetRelatedVariable", "CBaseTransition [MFC], m_bAdded", "CBaseTransition [MFC], m_pEndKeyframe", "CBaseTransition [MFC], m_pRelatedVariable", "CBaseTransition [MFC], m_pStartKeyframe", "CBaseTransition [MFC], m_transition", "CBaseTransition [MFC], m_type"] -ms.assetid: dfe84007-bbc5-43b7-b5b8-fae9145573bf --- # CBaseTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a basic transition. ## Syntax diff --git a/docs/mfc/reference/cbitmap-class.md b/docs/mfc/reference/cbitmap-class.md index 41642f129b5..c914aa52a4b 100644 --- a/docs/mfc/reference/cbitmap-class.md +++ b/docs/mfc/reference/cbitmap-class.md @@ -4,10 +4,12 @@ title: "CBitmap Class" ms.date: "11/04/2016" f1_keywords: ["CBitmap", "AFXWIN/CBitmap", "AFXWIN/CBitmap::CBitmap", "AFXWIN/CBitmap::CreateBitmap", "AFXWIN/CBitmap::CreateBitmapIndirect", "AFXWIN/CBitmap::CreateCompatibleBitmap", "AFXWIN/CBitmap::CreateDiscardableBitmap", "AFXWIN/CBitmap::FromHandle", "AFXWIN/CBitmap::GetBitmap", "AFXWIN/CBitmap::GetBitmapBits", "AFXWIN/CBitmap::GetBitmapDimension", "AFXWIN/CBitmap::LoadBitmap", "AFXWIN/CBitmap::LoadMappedBitmap", "AFXWIN/CBitmap::LoadOEMBitmap", "AFXWIN/CBitmap::SetBitmapBits", "AFXWIN/CBitmap::SetBitmapDimension"] helpviewer_keywords: ["CBitmap [MFC], CBitmap", "CBitmap [MFC], CreateBitmap", "CBitmap [MFC], CreateBitmapIndirect", "CBitmap [MFC], CreateCompatibleBitmap", "CBitmap [MFC], CreateDiscardableBitmap", "CBitmap [MFC], FromHandle", "CBitmap [MFC], GetBitmap", "CBitmap [MFC], GetBitmapBits", "CBitmap [MFC], GetBitmapDimension", "CBitmap [MFC], LoadBitmap", "CBitmap [MFC], LoadMappedBitmap", "CBitmap [MFC], LoadOEMBitmap", "CBitmap [MFC], SetBitmapBits", "CBitmap [MFC], SetBitmapDimension"] -ms.assetid: 3980616a-c59d-495a-86e6-62bd3889c84c --- # `CBitmap` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a Windows graphics device interface (GDI) bitmap and provides member functions to manipulate the bitmap. ## Syntax diff --git a/docs/mfc/reference/cbitmapbutton-class.md b/docs/mfc/reference/cbitmapbutton-class.md index 40777e6f653..74b93c9d90c 100644 --- a/docs/mfc/reference/cbitmapbutton-class.md +++ b/docs/mfc/reference/cbitmapbutton-class.md @@ -4,10 +4,12 @@ title: "CBitmapButton Class" ms.date: "11/04/2016" f1_keywords: ["CBitmapButton", "AFXEXT/CBitmapButton", "AFXEXT/CBitmapButton::CBitmapButton", "AFXEXT/CBitmapButton::AutoLoad", "AFXEXT/CBitmapButton::LoadBitmaps", "AFXEXT/CBitmapButton::SizeToContent"] helpviewer_keywords: ["CBitmapButton [MFC], CBitmapButton", "CBitmapButton [MFC], AutoLoad", "CBitmapButton [MFC], LoadBitmaps", "CBitmapButton [MFC], SizeToContent"] -ms.assetid: 9ad6cb45-c3c4-4fb1-96d3-1fe3df7bbcfc --- # CBitmapButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Creates pushbutton controls labeled with bitmapped images instead of text. ## Syntax diff --git a/docs/mfc/reference/cbitmaprendertarget-class.md b/docs/mfc/reference/cbitmaprendertarget-class.md index 39e0ba6e5b0..c0469597461 100644 --- a/docs/mfc/reference/cbitmaprendertarget-class.md +++ b/docs/mfc/reference/cbitmaprendertarget-class.md @@ -4,10 +4,12 @@ title: "CBitmapRenderTarget Class" ms.date: "11/04/2016" f1_keywords: ["CBitmapRenderTarget", "AFXRENDERTARGET/CBitmapRenderTarget", "AFXRENDERTARGET/CBitmapRenderTarget::CBitmapRenderTarget", "AFXRENDERTARGET/CBitmapRenderTarget::Attach", "AFXRENDERTARGET/CBitmapRenderTarget::Detach", "AFXRENDERTARGET/CBitmapRenderTarget::GetBitmap", "AFXRENDERTARGET/CBitmapRenderTarget::GetBitmapRenderTarget", "AFXRENDERTARGET/CBitmapRenderTarget::m_pBitmapRenderTarget"] helpviewer_keywords: ["CBitmapRenderTarget [MFC], CBitmapRenderTarget", "CBitmapRenderTarget [MFC], Attach", "CBitmapRenderTarget [MFC], Detach", "CBitmapRenderTarget [MFC], GetBitmap", "CBitmapRenderTarget [MFC], GetBitmapRenderTarget", "CBitmapRenderTarget [MFC], m_pBitmapRenderTarget"] -ms.assetid: c89a4437-812e-4943-acb2-b429a04cc4d2 --- # CBitmapRenderTarget Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1BitmapRenderTarget. ## Syntax diff --git a/docs/mfc/reference/cbrush-class.md b/docs/mfc/reference/cbrush-class.md index e9173b9a1b9..274a3dac48a 100644 --- a/docs/mfc/reference/cbrush-class.md +++ b/docs/mfc/reference/cbrush-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CBrush [MFC], CBrush", "CBrush [MFC], CreateBrushIndirect --- # `CBrush` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a Windows graphics device interface (GDI) brush. ## Syntax diff --git a/docs/mfc/reference/cbutton-class.md b/docs/mfc/reference/cbutton-class.md index 3d19e7ff585..607dd0251aa 100644 --- a/docs/mfc/reference/cbutton-class.md +++ b/docs/mfc/reference/cbutton-class.md @@ -4,10 +4,12 @@ title: "CButton Class" ms.date: "11/04/2016" f1_keywords: ["CButton", "AFXWIN/CButton", "AFXWIN/CButton::CButton", "AFXWIN/CButton::Create", "AFXWIN/CButton::DrawItem", "AFXWIN/CButton::GetBitmap", "AFXWIN/CButton::GetButtonStyle", "AFXWIN/CButton::GetCheck", "AFXWIN/CButton::GetCursor", "AFXWIN/CButton::GetIcon", "AFXWIN/CButton::GetIdealSize", "AFXWIN/CButton::GetImageList", "AFXWIN/CButton::GetNote", "AFXWIN/CButton::GetNoteLength", "AFXWIN/CButton::GetSplitGlyph", "AFXWIN/CButton::GetSplitImageList", "AFXWIN/CButton::GetSplitInfo", "AFXWIN/CButton::GetSplitSize", "AFXWIN/CButton::GetSplitStyle", "AFXWIN/CButton::GetState", "AFXWIN/CButton::GetTextMargin", "AFXWIN/CButton::SetBitmap", "AFXWIN/CButton::SetButtonStyle", "AFXWIN/CButton::SetCheck", "AFXWIN/CButton::SetCursor", "AFXWIN/CButton::SetDropDownState", "AFXWIN/CButton::SetIcon", "AFXWIN/CButton::SetImageList", "AFXWIN/CButton::SetNote", "AFXWIN/CButton::SetSplitGlyph", "AFXWIN/CButton::SetSplitImageList", "AFXWIN/CButton::SetSplitInfo", "AFXWIN/CButton::SetSplitSize", "AFXWIN/CButton::SetSplitStyle", "AFXWIN/CButton::SetState", "AFXWIN/CButton::SetTextMargin"] helpviewer_keywords: ["CButton [MFC], CButton", "CButton [MFC], Create", "CButton [MFC], DrawItem", "CButton [MFC], GetBitmap", "CButton [MFC], GetButtonStyle", "CButton [MFC], GetCheck", "CButton [MFC], GetCursor", "CButton [MFC], GetIcon", "CButton [MFC], GetIdealSize", "CButton [MFC], GetImageList", "CButton [MFC], GetNote", "CButton [MFC], GetNoteLength", "CButton [MFC], GetSplitGlyph", "CButton [MFC], GetSplitImageList", "CButton [MFC], GetSplitInfo", "CButton [MFC], GetSplitSize", "CButton [MFC], GetSplitStyle", "CButton [MFC], GetState", "CButton [MFC], GetTextMargin", "CButton [MFC], SetBitmap", "CButton [MFC], SetButtonStyle", "CButton [MFC], SetCheck", "CButton [MFC], SetCursor", "CButton [MFC], SetDropDownState", "CButton [MFC], SetIcon", "CButton [MFC], SetImageList", "CButton [MFC], SetNote", "CButton [MFC], SetSplitGlyph", "CButton [MFC], SetSplitImageList", "CButton [MFC], SetSplitInfo", "CButton [MFC], SetSplitSize", "CButton [MFC], SetSplitStyle", "CButton [MFC], SetState", "CButton [MFC], SetTextMargin"] -ms.assetid: cdc76d5b-31da-43c5-bc43-fde4cb39de5b --- # CButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of Windows button controls. ## Syntax diff --git a/docs/mfc/reference/cbytearray-class.md b/docs/mfc/reference/cbytearray-class.md index 9010e7b881a..42df04444be 100644 --- a/docs/mfc/reference/cbytearray-class.md +++ b/docs/mfc/reference/cbytearray-class.md @@ -4,10 +4,12 @@ title: "CByteArray Class" ms.date: "11/04/2016" f1_keywords: ["CByteArray", "AFXCOLL/CByteArray", "AFXCOLL/CByteArray::CByteArray", "AFXCOLL/CByteArray::Add", "AFXCOLL/CByteArray::Append", "AFXCOLL/CByteArray::Copy", "AFXCOLL/CByteArray::ElementAt", "AFXCOLL/CByteArray::FreeExtra", "AFXCOLL/CByteArray::GetAt", "AFXCOLL/CByteArray::GetCount", "AFXCOLL/CByteArray::GetData", "AFXCOLL/CByteArray::GetSize", "AFXCOLL/CByteArray::GetUpperBound", "AFXCOLL/CByteArray::InsertAt", "AFXCOLL/CByteArray::IsEmpty", "AFXCOLL/CByteArray::RemoveAll", "AFXCOLL/CByteArray::RemoveAt", "AFXCOLL/CByteArray::SetAt", "AFXCOLL/CByteArray::SetAtGrow", "AFXCOLL/CByteArray::SetSize"] helpviewer_keywords: ["CByteArray [MFC], CByteArray", "CByteArray [MFC], Add", "CByteArray [MFC], Append", "CByteArray [MFC], Copy", "CByteArray [MFC], ElementAt", "CByteArray [MFC], FreeExtra", "CByteArray [MFC], GetAt", "CByteArray [MFC], GetCount", "CByteArray [MFC], GetData", "CByteArray [MFC], GetSize", "CByteArray [MFC], GetUpperBound", "CByteArray [MFC], InsertAt", "CByteArray [MFC], IsEmpty", "CByteArray [MFC], RemoveAll", "CByteArray [MFC], RemoveAt", "CByteArray [MFC], SetAt", "CByteArray [MFC], SetAtGrow", "CByteArray [MFC], SetSize"] -ms.assetid: 53d4a512-657c-4187-9609-e3f5339a78e0 --- # CByteArray Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports dynamic arrays of bytes. ## Syntax diff --git a/docs/mfc/reference/ccacheddatapathproperty-class.md b/docs/mfc/reference/ccacheddatapathproperty-class.md index bbbdeb2971a..e437ac08a70 100644 --- a/docs/mfc/reference/ccacheddatapathproperty-class.md +++ b/docs/mfc/reference/ccacheddatapathproperty-class.md @@ -4,10 +4,12 @@ title: "CCachedDataPathProperty Class" ms.date: "11/04/2016" f1_keywords: ["CCachedDataPathProperty", "AFXCTL/CCachedDataPathProperty", "AFXCTL/CCachedDataPathProperty::CCachedDataPathProperty", "AFXCTL/CCachedDataPathProperty::m_Cache"] helpviewer_keywords: ["CCachedDataPathProperty [MFC], CCachedDataPathProperty", "CCachedDataPathProperty [MFC], m_Cache"] -ms.assetid: 0d81356b-4fe5-43f6-aed2-2eb5a5485706 --- # CCachedDataPathProperty Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements an OLE control property transferred asynchronously and cached in a memory file. ## Syntax diff --git a/docs/mfc/reference/cchecklistbox-class.md b/docs/mfc/reference/cchecklistbox-class.md index 1ef8922947c..ab55aaf58ec 100644 --- a/docs/mfc/reference/cchecklistbox-class.md +++ b/docs/mfc/reference/cchecklistbox-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CCheckListBox [MFC], CCheckListBox", "CCheckListBox [MFC] --- # `CCheckListBox` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows checklist box. ## Syntax diff --git a/docs/mfc/reference/cclientdc-class.md b/docs/mfc/reference/cclientdc-class.md index 02091a39e28..1321c52ab06 100644 --- a/docs/mfc/reference/cclientdc-class.md +++ b/docs/mfc/reference/cclientdc-class.md @@ -4,10 +4,12 @@ title: "CClientDC Class" ms.date: "11/04/2016" f1_keywords: ["CClientDC", "AFXWIN/CClientDC", "AFXWIN/CClientDC::CClientDC", "AFXWIN/CClientDC::m_hWnd"] helpviewer_keywords: ["CClientDC [MFC], CClientDC", "CClientDC [MFC], m_hWnd"] -ms.assetid: 8a871d6b-06f8-496e-9fa3-9a5780848369 --- # CClientDC Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Takes care of calling 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. ## Syntax diff --git a/docs/mfc/reference/ccmdtarget-class.md b/docs/mfc/reference/ccmdtarget-class.md index 6da05a3a24a..e089d2093e5 100644 --- a/docs/mfc/reference/ccmdtarget-class.md +++ b/docs/mfc/reference/ccmdtarget-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CCmdTarget` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for the Microsoft Foundation Class Library message-map architecture. ## Syntax @@ -299,7 +302,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. @@ -447,7 +450,7 @@ If you override `OnCmdMsg`, you must supply the appropriate value for *`nCode`*, ### Example [!code-cpp[NVC_MFCDocView#44](../../mfc/codesnippet/cpp/ccmdtarget-class_2.cpp)] - +  [!code-cpp[NVC_MFCDocView#45](../../mfc/codesnippet/cpp/ccmdtarget-class_3.cpp)] ## `CCmdTarget::OnFinalRelease` diff --git a/docs/mfc/reference/ccmdui-class.md b/docs/mfc/reference/ccmdui-class.md index 0d90c19e9b7..52a40e07db6 100644 --- a/docs/mfc/reference/ccmdui-class.md +++ b/docs/mfc/reference/ccmdui-class.md @@ -4,10 +4,12 @@ title: "CCmdUI Class" ms.date: "09/06/2019" f1_keywords: ["CCmdUI", "AFXWIN/CCmdUI", "AFXWIN/CCmdUI::ContinueRouting", "AFXWIN/CCmdUI::Enable", "AFXWIN/CCmdUI::SetCheck", "AFXWIN/CCmdUI::SetRadio", "AFXWIN/CCmdUI::SetText", "AFXWIN/CCmdUI::m_nID", "AFXWIN/CCmdUI::m_nIndex", "AFXWIN/CCmdUI::m_pMenu", "AFXWIN/CCmdUI::m_pOther", "AFXWIN/CCmdUI::m_pSubMenu"] helpviewer_keywords: ["CCmdUI [MFC], ContinueRouting", "CCmdUI [MFC], Enable", "CCmdUI [MFC], SetCheck", "CCmdUI [MFC], SetRadio", "CCmdUI [MFC], SetText", "CCmdUI [MFC], m_nID", "CCmdUI [MFC], m_nIndex", "CCmdUI [MFC], m_pMenu", "CCmdUI [MFC], m_pOther", "CCmdUI [MFC], m_pSubMenu"] -ms.assetid: 04eaaaf5-f510-48ab-b425-94665ba24766 --- # CCmdUI Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Is used only within an `ON_UPDATE_COMMAND_UI` handler in a `CCmdTarget`-derived class. ## Syntax @@ -96,7 +98,7 @@ TRUE to enable the item, FALSE to disable it. ### Example [!code-cpp[NVC_MFCDocView#46](../../mfc/codesnippet/cpp/ccmdui-class_1.cpp)] - +  [!code-cpp[NVC_MFCDocView#47](../../mfc/codesnippet/cpp/ccmdui-class_2.cpp)] ## CCmdUI::m_nID diff --git a/docs/mfc/reference/ccolordialog-class.md b/docs/mfc/reference/ccolordialog-class.md index 3ef9b0282c5..d860dfcfc00 100644 --- a/docs/mfc/reference/ccolordialog-class.md +++ b/docs/mfc/reference/ccolordialog-class.md @@ -4,10 +4,12 @@ title: "CColorDialog Class" ms.date: "11/04/2016" f1_keywords: ["CColorDialog", "AFXDLGS/CColorDialog", "AFXDLGS/CColorDialog::CColorDialog", "AFXDLGS/CColorDialog::DoModal", "AFXDLGS/CColorDialog::GetColor", "AFXDLGS/CColorDialog::GetSavedCustomColors", "AFXDLGS/CColorDialog::SetCurrentColor", "AFXDLGS/CColorDialog::OnColorOK", "AFXDLGS/CColorDialog::m_cc"] helpviewer_keywords: ["CColorDialog [MFC], CColorDialog", "CColorDialog [MFC], DoModal", "CColorDialog [MFC], GetColor", "CColorDialog [MFC], GetSavedCustomColors", "CColorDialog [MFC], SetCurrentColor", "CColorDialog [MFC], OnColorOK", "CColorDialog [MFC], m_cc"] -ms.assetid: d013dc25-9290-4b5d-a97e-95ad7208e13b --- # CColorDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows you to incorporate a color-selection dialog box into your application. ## Syntax diff --git a/docs/mfc/reference/ccombobox-class.md b/docs/mfc/reference/ccombobox-class.md index 02046d4a906..fb99b69cc46 100644 --- a/docs/mfc/reference/ccombobox-class.md +++ b/docs/mfc/reference/ccombobox-class.md @@ -1,13 +1,15 @@ --- title: "CComboBox Class" description: "API reference for the MFC Windows combo box class CComboBox" -ms.date: "08/27/2020" +ms.date: 08/27/2020 f1_keywords: ["CComboBox", "AFXWIN/CComboBox", "AFXWIN/CComboBox::CComboBox", "AFXWIN/CComboBox::AddString", "AFXWIN/CComboBox::Clear", "AFXWIN/CComboBox::CompareItem", "AFXWIN/CComboBox::Copy", "AFXWIN/CComboBox::Create", "AFXWIN/CComboBox::Cut", "AFXWIN/CComboBox::DeleteItem", "AFXWIN/CComboBox::DeleteString", "AFXWIN/CComboBox::Dir", "AFXWIN/CComboBox::DrawItem", "AFXWIN/CComboBox::FindString", "AFXWIN/CComboBox::FindStringExact", "AFXWIN/CComboBox::GetComboBoxInfo", "AFXWIN/CComboBox::GetCount", "AFXWIN/CComboBox::GetCueBanner", "AFXWIN/CComboBox::GetCurSel", "AFXWIN/CComboBox::GetDroppedControlRect", "AFXWIN/CComboBox::GetDroppedState", "AFXWIN/CComboBox::GetDroppedWidth", "AFXWIN/CComboBox::GetEditSel", "AFXWIN/CComboBox::GetExtendedUI", "AFXWIN/CComboBox::GetHorizontalExtent", "AFXWIN/CComboBox::GetItemData", "AFXWIN/CComboBox::GetItemDataPtr", "AFXWIN/CComboBox::GetItemHeight", "AFXWIN/CComboBox::GetLBText", "AFXWIN/CComboBox::GetLBTextLen", "AFXWIN/CComboBox::GetLocale", "AFXWIN/CComboBox::GetMinVisible", "AFXWIN/CComboBox::GetTopIndex", "AFXWIN/CComboBox::InitStorage", "AFXWIN/CComboBox::InsertString", "AFXWIN/CComboBox::LimitText", "AFXWIN/CComboBox::MeasureItem", "AFXWIN/CComboBox::Paste", "AFXWIN/CComboBox::ResetContent", "AFXWIN/CComboBox::SelectString", "AFXWIN/CComboBox::SetCueBanner", "AFXWIN/CComboBox::SetCurSel", "AFXWIN/CComboBox::SetDroppedWidth", "AFXWIN/CComboBox::SetEditSel", "AFXWIN/CComboBox::SetExtendedUI", "AFXWIN/CComboBox::SetHorizontalExtent", "AFXWIN/CComboBox::SetItemData", "AFXWIN/CComboBox::SetItemDataPtr", "AFXWIN/CComboBox::SetItemHeight", "AFXWIN/CComboBox::SetLocale", "AFXWIN/CComboBox::SetMinVisibleItems", "AFXWIN/CComboBox::SetTopIndex", "AFXWIN/CComboBox::ShowDropDown"] helpviewer_keywords: ["CComboBox [MFC], CComboBox", "CComboBox [MFC], AddString", "CComboBox [MFC], Clear", "CComboBox [MFC], CompareItem", "CComboBox [MFC], Copy", "CComboBox [MFC], Create", "CComboBox [MFC], Cut", "CComboBox [MFC], DeleteItem", "CComboBox [MFC], DeleteString", "CComboBox [MFC], Dir", "CComboBox [MFC], DrawItem", "CComboBox [MFC], FindString", "CComboBox [MFC], FindStringExact", "CComboBox [MFC], GetComboBoxInfo", "CComboBox [MFC], GetCount", "CComboBox [MFC], GetCueBanner", "CComboBox [MFC], GetCurSel", "CComboBox [MFC], GetDroppedControlRect", "CComboBox [MFC], GetDroppedState", "CComboBox [MFC], GetDroppedWidth", "CComboBox [MFC], GetEditSel", "CComboBox [MFC], GetExtendedUI", "CComboBox [MFC], GetHorizontalExtent", "CComboBox [MFC], GetItemData", "CComboBox [MFC], GetItemDataPtr", "CComboBox [MFC], GetItemHeight", "CComboBox [MFC], GetLBText", "CComboBox [MFC], GetLBTextLen", "CComboBox [MFC], GetLocale", "CComboBox [MFC], GetMinVisible", "CComboBox [MFC], GetTopIndex", "CComboBox [MFC], InitStorage", "CComboBox [MFC], InsertString", "CComboBox [MFC], LimitText", "CComboBox [MFC], MeasureItem", "CComboBox [MFC], Paste", "CComboBox [MFC], ResetContent", "CComboBox [MFC], SelectString", "CComboBox [MFC], SetCueBanner", "CComboBox [MFC], SetCurSel", "CComboBox [MFC], SetDroppedWidth", "CComboBox [MFC], SetEditSel", "CComboBox [MFC], SetExtendedUI", "CComboBox [MFC], SetHorizontalExtent", "CComboBox [MFC], SetItemData", "CComboBox [MFC], SetItemDataPtr", "CComboBox [MFC], SetItemHeight", "CComboBox [MFC], SetLocale", "CComboBox [MFC], SetMinVisibleItems", "CComboBox [MFC], SetTopIndex", "CComboBox [MFC], ShowDropDown"] -ms.assetid: 4e73b5df-0d2e-4658-9706-38133fb10513 --- # `CComboBox` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows combo box. ## Syntax @@ -515,7 +517,7 @@ BOOL GetComboBoxInfo(PCOMBOBOXINFO pcbi) const; ### Parameters -*`pcbi*
+*`pcbi`*
A pointer to the [`COMBOBOXINFO`](/windows/win32/api/winuser/ns-winuser-comboboxinfo) structure. ### Return Value diff --git a/docs/mfc/reference/ccomboboxex-class.md b/docs/mfc/reference/ccomboboxex-class.md index 5038d39997d..51257fd7d41 100644 --- a/docs/mfc/reference/ccomboboxex-class.md +++ b/docs/mfc/reference/ccomboboxex-class.md @@ -4,10 +4,12 @@ title: "CComboBoxEx Class" ms.date: "11/04/2016" f1_keywords: ["CComboBoxEx", "AFXCMN/CComboBoxEx", "AFXCMN/CComboBoxEx::CComboBoxEx", "AFXCMN/CComboBoxEx::Create", "AFXCMN/CComboBoxEx::CreateEx", "AFXCMN/CComboBoxEx::DeleteItem", "AFXCMN/CComboBoxEx::GetComboBoxCtrl", "AFXCMN/CComboBoxEx::GetEditCtrl", "AFXCMN/CComboBoxEx::GetExtendedStyle", "AFXCMN/CComboBoxEx::GetImageList", "AFXCMN/CComboBoxEx::GetItem", "AFXCMN/CComboBoxEx::HasEditChanged", "AFXCMN/CComboBoxEx::InsertItem", "AFXCMN/CComboBoxEx::SetExtendedStyle", "AFXCMN/CComboBoxEx::SetImageList", "AFXCMN/CComboBoxEx::SetItem", "AFXCMN/CComboBoxEx::SetWindowTheme"] helpviewer_keywords: ["CComboBoxEx [MFC], CComboBoxEx", "CComboBoxEx [MFC], Create", "CComboBoxEx [MFC], CreateEx", "CComboBoxEx [MFC], DeleteItem", "CComboBoxEx [MFC], GetComboBoxCtrl", "CComboBoxEx [MFC], GetEditCtrl", "CComboBoxEx [MFC], GetExtendedStyle", "CComboBoxEx [MFC], GetImageList", "CComboBoxEx [MFC], GetItem", "CComboBoxEx [MFC], HasEditChanged", "CComboBoxEx [MFC], InsertItem", "CComboBoxEx [MFC], SetExtendedStyle", "CComboBoxEx [MFC], SetImageList", "CComboBoxEx [MFC], SetItem", "CComboBoxEx [MFC], SetWindowTheme"] -ms.assetid: 33ca960a-2409-478c-84a4-a2ee8ecfe8f7 --- # CComboBoxEx Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Extends the combo box control by providing support for image lists. ## Syntax diff --git a/docs/mfc/reference/ccommandlineinfo-class.md b/docs/mfc/reference/ccommandlineinfo-class.md index 944fb85dd15..3f165999fdd 100644 --- a/docs/mfc/reference/ccommandlineinfo-class.md +++ b/docs/mfc/reference/ccommandlineinfo-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CCommandLineInfo` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Aids in parsing the command line at application startup. ## Syntax @@ -83,7 +86,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/ccommondialog-class.md b/docs/mfc/reference/ccommondialog-class.md index bb92ea0e98a..80866aebe99 100644 --- a/docs/mfc/reference/ccommondialog-class.md +++ b/docs/mfc/reference/ccommondialog-class.md @@ -4,10 +4,12 @@ title: "CCommonDialog Class" ms.date: "11/04/2016" f1_keywords: ["CCommonDialog", "AFXDLGS/CCommonDialog", "AFXDLGS/CCommonDialog::CCommonDialog"] helpviewer_keywords: ["CCommonDialog [MFC], CCommonDialog"] -ms.assetid: 1f68d65f-a0fd-4778-be22-ebbe51a95f95 --- # CCommonDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for classes that encapsulate functionality of the Windows common dialogs. ## Syntax diff --git a/docs/mfc/reference/cconnectionpoint-class.md b/docs/mfc/reference/cconnectionpoint-class.md index 97925d83f01..8ee400a356d 100644 --- a/docs/mfc/reference/cconnectionpoint-class.md +++ b/docs/mfc/reference/cconnectionpoint-class.md @@ -4,10 +4,12 @@ title: "CConnectionPoint Class" ms.date: "11/04/2016" f1_keywords: ["CConnectionPoint", "AFXDISP/CConnectionPoint", "AFXDISP/CConnectionPoint::CConnectionPoint", "AFXDISP/CConnectionPoint::GetConnections", "AFXDISP/CConnectionPoint::GetContainer", "AFXDISP/CConnectionPoint::GetIID", "AFXDISP/CConnectionPoint::GetMaxConnections", "AFXDISP/CConnectionPoint::GetNextConnection", "AFXDISP/CConnectionPoint::GetStartPosition", "AFXDISP/CConnectionPoint::OnAdvise", "AFXDISP/CConnectionPoint::QuerySinkInterface"] helpviewer_keywords: ["CConnectionPoint [MFC], CConnectionPoint", "CConnectionPoint [MFC], GetConnections", "CConnectionPoint [MFC], GetContainer", "CConnectionPoint [MFC], GetIID", "CConnectionPoint [MFC], GetMaxConnections", "CConnectionPoint [MFC], GetNextConnection", "CConnectionPoint [MFC], GetStartPosition", "CConnectionPoint [MFC], OnAdvise", "CConnectionPoint [MFC], QuerySinkInterface"] -ms.assetid: f0f23a1e-5e8c-41a9-aa6c-1a4793b28e8f --- # CConnectionPoint Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Defines a special type of interface used to communicate with other OLE objects, called a "connection point." ## Syntax diff --git a/docs/mfc/reference/cconstanttransition-class.md b/docs/mfc/reference/cconstanttransition-class.md index 16a55675bc6..717319d3441 100644 --- a/docs/mfc/reference/cconstanttransition-class.md +++ b/docs/mfc/reference/cconstanttransition-class.md @@ -4,10 +4,12 @@ title: "CConstantTransition Class" ms.date: "11/04/2016" f1_keywords: ["CConstantTransition", "AFXANIMATIONCONTROLLER/CConstantTransition", "AFXANIMATIONCONTROLLER/CConstantTransition::CConstantTransition", "AFXANIMATIONCONTROLLER/CConstantTransition::Create", "AFXANIMATIONCONTROLLER/CConstantTransition::m_duration"] helpviewer_keywords: ["CConstantTransition [MFC], CConstantTransition", "CConstantTransition [MFC], Create", "CConstantTransition [MFC], m_duration"] -ms.assetid: f6fa4780-a71b-4cd6-80aa-d4792ace36c2 --- # CConstantTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a constant transition. ## Syntax diff --git a/docs/mfc/reference/ccontextmenumanager-class.md b/docs/mfc/reference/ccontextmenumanager-class.md index 5c6539ddf36..f2800b39bcb 100644 --- a/docs/mfc/reference/ccontextmenumanager-class.md +++ b/docs/mfc/reference/ccontextmenumanager-class.md @@ -4,10 +4,12 @@ title: "CContextMenuManager Class" ms.date: "11/04/2016" f1_keywords: ["CContextMenuManager", "AFXCONTEXTMENUMANAGER/CContextMenuManager", "AFXCONTEXTMENUMANAGER/CContextMenuManager::CContextMenuManager", "AFXCONTEXTMENUMANAGER/CContextMenuManager::AddMenu", "AFXCONTEXTMENUMANAGER/CContextMenuManager::GetMenuById", "AFXCONTEXTMENUMANAGER/CContextMenuManager::GetMenuByName", "AFXCONTEXTMENUMANAGER/CContextMenuManager::GetMenuNames", "AFXCONTEXTMENUMANAGER/CContextMenuManager::LoadState", "AFXCONTEXTMENUMANAGER/CContextMenuManager::ResetState", "AFXCONTEXTMENUMANAGER/CContextMenuManager::SaveState", "AFXCONTEXTMENUMANAGER/CContextMenuManager::SetDontCloseActiveMenu", "AFXCONTEXTMENUMANAGER/CContextMenuManager::ShowPopupMenu", "AFXCONTEXTMENUMANAGER/CContextMenuManager::TrackPopupMenu"] helpviewer_keywords: ["CContextMenuManager [MFC], CContextMenuManager", "CContextMenuManager [MFC], AddMenu", "CContextMenuManager [MFC], GetMenuById", "CContextMenuManager [MFC], GetMenuByName", "CContextMenuManager [MFC], GetMenuNames", "CContextMenuManager [MFC], LoadState", "CContextMenuManager [MFC], ResetState", "CContextMenuManager [MFC], SaveState", "CContextMenuManager [MFC], SetDontCloseActiveMenu", "CContextMenuManager [MFC], ShowPopupMenu", "CContextMenuManager [MFC], TrackPopupMenu"] -ms.assetid: 1de20640-243c-47e1-85de-1baa4153bc83 --- # CContextMenuManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CContextMenuManager` object manages shortcut menus, also known as context menus. ## Syntax diff --git a/docs/mfc/reference/ccontrolbar-class.md b/docs/mfc/reference/ccontrolbar-class.md index d8ab52bf13f..3216a4f4a83 100644 --- a/docs/mfc/reference/ccontrolbar-class.md +++ b/docs/mfc/reference/ccontrolbar-class.md @@ -4,10 +4,12 @@ title: "CControlBar Class" ms.date: "11/04/2016" f1_keywords: ["CControlBar", "AFXEXT/CControlBar", "AFXEXT/CControlBar::CControlBar", "AFXEXT/CControlBar::CalcDynamicLayout", "AFXEXT/CControlBar::CalcFixedLayout", "AFXEXT/CControlBar::CalcInsideRect", "AFXEXT/CControlBar::DoPaint", "AFXEXT/CControlBar::DrawBorders", "AFXEXT/CControlBar::DrawGripper", "AFXEXT/CControlBar::EnableDocking", "AFXEXT/CControlBar::GetBarStyle", "AFXEXT/CControlBar::GetBorders", "AFXEXT/CControlBar::GetCount", "AFXEXT/CControlBar::GetDockingFrame", "AFXEXT/CControlBar::IsFloating", "AFXEXT/CControlBar::OnUpdateCmdUI", "AFXEXT/CControlBar::SetBarStyle", "AFXEXT/CControlBar::SetBorders", "AFXEXT/CControlBar::SetInPlaceOwner", "AFXEXT/CControlBar::m_bAutoDelete", "AFXEXT/CControlBar::m_pInPlaceOwner"] helpviewer_keywords: ["CControlBar [MFC], CControlBar", "CControlBar [MFC], CalcDynamicLayout", "CControlBar [MFC], CalcFixedLayout", "CControlBar [MFC], CalcInsideRect", "CControlBar [MFC], DoPaint", "CControlBar [MFC], DrawBorders", "CControlBar [MFC], DrawGripper", "CControlBar [MFC], EnableDocking", "CControlBar [MFC], GetBarStyle", "CControlBar [MFC], GetBorders", "CControlBar [MFC], GetCount", "CControlBar [MFC], GetDockingFrame", "CControlBar [MFC], IsFloating", "CControlBar [MFC], OnUpdateCmdUI", "CControlBar [MFC], SetBarStyle", "CControlBar [MFC], SetBorders", "CControlBar [MFC], SetInPlaceOwner", "CControlBar [MFC], m_bAutoDelete", "CControlBar [MFC], m_pInPlaceOwner"] -ms.assetid: 4d668c55-9b42-4838-97ac-cf2b3000b82c --- # CControlBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for the control-bar classes [CStatusBar](../../mfc/reference/cstatusbar-class.md), [CToolBar](../../mfc/reference/ctoolbar-class.md), [CDialogBar](../../mfc/reference/cdialogbar-class.md), [CReBar](../../mfc/reference/crebar-class.md), and [COleResizeBar](../../mfc/reference/coleresizebar-class.md). ## Syntax diff --git a/docs/mfc/reference/ccreatecontext-structure.md b/docs/mfc/reference/ccreatecontext-structure.md index 5e388a6ea2c..f51446f4efe 100644 --- a/docs/mfc/reference/ccreatecontext-structure.md +++ b/docs/mfc/reference/ccreatecontext-structure.md @@ -4,10 +4,12 @@ title: "CCreateContext Structure" ms.date: "11/04/2016" f1_keywords: ["CCreateContext"] helpviewer_keywords: ["CCreateContext structure [MFC]"] -ms.assetid: 337a0e44-d910-49a8-afc0-c7207666a9dc --- # CCreateContext Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The framework uses the `CCreateContext` structure when it creates the frame windows and views that are associated with a document. ## Syntax diff --git a/docs/mfc/reference/ccriticalsection-class.md b/docs/mfc/reference/ccriticalsection-class.md index 5f747387318..d8d4e783423 100644 --- a/docs/mfc/reference/ccriticalsection-class.md +++ b/docs/mfc/reference/ccriticalsection-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CCriticalSection [MFC], CCriticalSection", "CCriticalSect --- # `CCriticalSection` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a "critical section" — a synchronization object that allows one thread at a time to access a resource or section of code. ## Syntax diff --git a/docs/mfc/reference/cctrlview-class.md b/docs/mfc/reference/cctrlview-class.md index c2d7a5d4315..818994d888b 100644 --- a/docs/mfc/reference/cctrlview-class.md +++ b/docs/mfc/reference/cctrlview-class.md @@ -4,10 +4,12 @@ title: "CCtrlView Class" ms.date: "11/04/2016" f1_keywords: ["CCtrlView", "AFXWIN/CCtrlView", "AFXWIN/CCtrlView::CCtrlView", "AFXWIN/CCtrlView::OnDraw", "AFXWIN/CCtrlView::PreCreateWindow", "AFXWIN/CCtrlView::m_dwDefaultStyle", "AFXWIN/CCtrlView::m_strClass"] helpviewer_keywords: ["CCtrlView [MFC], CCtrlView", "CCtrlView [MFC], OnDraw", "CCtrlView [MFC], PreCreateWindow", "CCtrlView [MFC], m_dwDefaultStyle", "CCtrlView [MFC], m_strClass"] -ms.assetid: ff488596-1e71-451f-8fec-b0831a7b44e0 --- # CCtrlView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Adapts the document-view architecture to the common controls supported by Windows 98 and Windows NT versions 3.51 and later. ## Syntax diff --git a/docs/mfc/reference/ccubictransition-class.md b/docs/mfc/reference/ccubictransition-class.md index 17ba50a9a7c..093c1ed04d9 100644 --- a/docs/mfc/reference/ccubictransition-class.md +++ b/docs/mfc/reference/ccubictransition-class.md @@ -4,10 +4,12 @@ title: "CCubicTransition Class" ms.date: "11/04/2016" f1_keywords: ["CCubicTransition", "AFXANIMATIONCONTROLLER/CCubicTransition", "AFXANIMATIONCONTROLLER/CCubicTransition::CCubicTransition", "AFXANIMATIONCONTROLLER/CCubicTransition::Create", "AFXANIMATIONCONTROLLER/CCubicTransition::m_dblFinalValue", "AFXANIMATIONCONTROLLER/CCubicTransition::m_dblFinalVelocity", "AFXANIMATIONCONTROLLER/CCubicTransition::m_duration"] helpviewer_keywords: ["CCubicTransition [MFC], CCubicTransition", "CCubicTransition [MFC], Create", "CCubicTransition [MFC], m_dblFinalValue", "CCubicTransition [MFC], m_dblFinalVelocity", "CCubicTransition [MFC], m_duration"] -ms.assetid: 4fc30e9c-160c-45e1-bdbe-51adf8fee9c5 --- # CCubicTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a cubic transition. ## Syntax diff --git a/docs/mfc/reference/ccustominterpolator-class.md b/docs/mfc/reference/ccustominterpolator-class.md index e1ab9c85536..270871b36a5 100644 --- a/docs/mfc/reference/ccustominterpolator-class.md +++ b/docs/mfc/reference/ccustominterpolator-class.md @@ -4,10 +4,12 @@ title: "CCustomInterpolator Class" ms.date: "11/04/2016" f1_keywords: ["CCustomInterpolator", "AFXANIMATIONCONTROLLER/CCustomInterpolator", "AFXANIMATIONCONTROLLER/CCustomInterpolator::CCustomInterpolator", "AFXANIMATIONCONTROLLER/CCustomInterpolator::GetDependencies", "AFXANIMATIONCONTROLLER/CCustomInterpolator::GetDuration", "AFXANIMATIONCONTROLLER/CCustomInterpolator::GetFinalValue", "AFXANIMATIONCONTROLLER/CCustomInterpolator::Init", "AFXANIMATIONCONTROLLER/CCustomInterpolator::InterpolateValue", "AFXANIMATIONCONTROLLER/CCustomInterpolator::InterpolateVelocity", "AFXANIMATIONCONTROLLER/CCustomInterpolator::SetDuration", "AFXANIMATIONCONTROLLER/CCustomInterpolator::SetInitialValueAndVelocity", "AFXANIMATIONCONTROLLER/CCustomInterpolator::m_currentValue", "AFXANIMATIONCONTROLLER/CCustomInterpolator::m_currentVelocity", "AFXANIMATIONCONTROLLER/CCustomInterpolator::m_duration", "AFXANIMATIONCONTROLLER/CCustomInterpolator::m_finalValue", "AFXANIMATIONCONTROLLER/CCustomInterpolator::m_initialValue", "AFXANIMATIONCONTROLLER/CCustomInterpolator::m_initialVelocity"] helpviewer_keywords: ["CCustomInterpolator [MFC], CCustomInterpolator", "CCustomInterpolator [MFC], GetDependencies", "CCustomInterpolator [MFC], GetDuration", "CCustomInterpolator [MFC], GetFinalValue", "CCustomInterpolator [MFC], Init", "CCustomInterpolator [MFC], InterpolateValue", "CCustomInterpolator [MFC], InterpolateVelocity", "CCustomInterpolator [MFC], SetDuration", "CCustomInterpolator [MFC], SetInitialValueAndVelocity", "CCustomInterpolator [MFC], m_currentValue", "CCustomInterpolator [MFC], m_currentVelocity", "CCustomInterpolator [MFC], m_duration", "CCustomInterpolator [MFC], m_finalValue", "CCustomInterpolator [MFC], m_initialValue", "CCustomInterpolator [MFC], m_initialVelocity"] -ms.assetid: 28d85595-989a-40a3-b003-e0e38437a94d --- # CCustomInterpolator Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a basic interpolator. ## Syntax diff --git a/docs/mfc/reference/ccustomtransition-class.md b/docs/mfc/reference/ccustomtransition-class.md index 36e2810e347..73ffb6d571d 100644 --- a/docs/mfc/reference/ccustomtransition-class.md +++ b/docs/mfc/reference/ccustomtransition-class.md @@ -4,10 +4,12 @@ title: "CCustomTransition Class" ms.date: "11/04/2016" f1_keywords: ["CCustomTransition", "AFXANIMATIONCONTROLLER/CCustomTransition", "AFXANIMATIONCONTROLLER/CCustomTransition::CCustomTransition", "AFXANIMATIONCONTROLLER/CCustomTransition::Create", "AFXANIMATIONCONTROLLER/CCustomTransition::SetInitialValue", "AFXANIMATIONCONTROLLER/CCustomTransition::SetInitialVelocity", "AFXANIMATIONCONTROLLER/CCustomTransition::m_bInitialValueSpecified", "AFXANIMATIONCONTROLLER/CCustomTransition::m_bInitialVelocitySpecified", "AFXANIMATIONCONTROLLER/CCustomTransition::m_initialValue", "AFXANIMATIONCONTROLLER/CCustomTransition::m_initialVelocity", "AFXANIMATIONCONTROLLER/CCustomTransition::m_pInterpolator"] helpviewer_keywords: ["CCustomTransition [MFC], CCustomTransition", "CCustomTransition [MFC], Create", "CCustomTransition [MFC], SetInitialValue", "CCustomTransition [MFC], SetInitialVelocity", "CCustomTransition [MFC], m_bInitialValueSpecified", "CCustomTransition [MFC], m_bInitialVelocitySpecified", "CCustomTransition [MFC], m_initialValue", "CCustomTransition [MFC], m_initialVelocity", "CCustomTransition [MFC], m_pInterpolator"] -ms.assetid: 5bd3f492-940f-4290-a38b-fa68eb8f8401 --- # CCustomTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a custom transition. ## Syntax diff --git a/docs/mfc/reference/cd2dbitmap-class.md b/docs/mfc/reference/cd2dbitmap-class.md index 576532f3178..b763abcc8b7 100644 --- a/docs/mfc/reference/cd2dbitmap-class.md +++ b/docs/mfc/reference/cd2dbitmap-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1Bitmap. ## Syntax @@ -70,7 +72,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 +329,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/cd2dbitmapbrush-class.md b/docs/mfc/reference/cd2dbitmapbrush-class.md index 7387755e260..cd4aa8f6312 100644 --- a/docs/mfc/reference/cd2dbitmapbrush-class.md +++ b/docs/mfc/reference/cd2dbitmapbrush-class.md @@ -4,10 +4,12 @@ title: "CD2DBitmapBrush Class" ms.date: "11/04/2016" f1_keywords: ["CD2DBitmapBrush", "AFXRENDERTARGET/CD2DBitmapBrush", "AFXRENDERTARGET/CD2DBitmapBrush::CD2DBitmapBrush", "AFXRENDERTARGET/CD2DBitmapBrush::Attach", "AFXRENDERTARGET/CD2DBitmapBrush::Create", "AFXRENDERTARGET/CD2DBitmapBrush::Destroy", "AFXRENDERTARGET/CD2DBitmapBrush::Detach", "AFXRENDERTARGET/CD2DBitmapBrush::Get", "AFXRENDERTARGET/CD2DBitmapBrush::GetBitmap", "AFXRENDERTARGET/CD2DBitmapBrush::GetExtendModeX", "AFXRENDERTARGET/CD2DBitmapBrush::GetExtendModeY", "AFXRENDERTARGET/CD2DBitmapBrush::GetInterpolationMode", "AFXRENDERTARGET/CD2DBitmapBrush::SetBitmap", "AFXRENDERTARGET/CD2DBitmapBrush::SetExtendModeX", "AFXRENDERTARGET/CD2DBitmapBrush::SetExtendModeY", "AFXRENDERTARGET/CD2DBitmapBrush::SetInterpolationMode", "AFXRENDERTARGET/CD2DBitmapBrush::CommonInit", "AFXRENDERTARGET/CD2DBitmapBrush::m_pBitmap", "AFXRENDERTARGET/CD2DBitmapBrush::m_pBitmapBrush", "AFXRENDERTARGET/CD2DBitmapBrush::m_pBitmapBrushProperties"] helpviewer_keywords: ["CD2DBitmapBrush [MFC], CD2DBitmapBrush", "CD2DBitmapBrush [MFC], Attach", "CD2DBitmapBrush [MFC], Create", "CD2DBitmapBrush [MFC], Destroy", "CD2DBitmapBrush [MFC], Detach", "CD2DBitmapBrush [MFC], Get", "CD2DBitmapBrush [MFC], GetBitmap", "CD2DBitmapBrush [MFC], GetExtendModeX", "CD2DBitmapBrush [MFC], GetExtendModeY", "CD2DBitmapBrush [MFC], GetInterpolationMode", "CD2DBitmapBrush [MFC], SetBitmap", "CD2DBitmapBrush [MFC], SetExtendModeX", "CD2DBitmapBrush [MFC], SetExtendModeY", "CD2DBitmapBrush [MFC], SetInterpolationMode", "CD2DBitmapBrush [MFC], CommonInit", "CD2DBitmapBrush [MFC], m_pBitmap", "CD2DBitmapBrush [MFC], m_pBitmapBrush", "CD2DBitmapBrush [MFC], m_pBitmapBrushProperties"] -ms.assetid: 46ebbe34-66e0-44c8-af1d-d129e851de5e --- # CD2DBitmapBrush Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1BitmapBrush. ## Syntax diff --git a/docs/mfc/reference/cd2dbrush-class.md b/docs/mfc/reference/cd2dbrush-class.md index 1e7dc1032f6..cc583fd9207 100644 --- a/docs/mfc/reference/cd2dbrush-class.md +++ b/docs/mfc/reference/cd2dbrush-class.md @@ -4,11 +4,13 @@ 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +A wrapper for `ID2D1Brush`. ## Syntax @@ -22,57 +24,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 +84,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 +100,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 +129,9 @@ ID2D1Brush* Detach(); Pointer to detached resource interface. -## CD2DBrush::Get +## `CD2DBrush::Get` -Returns ID2D1Brush interface +Returns `ID2D1Brush` interface ``` ID2D1Brush* Get(); @@ -137,9 +139,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 +151,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 +163,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 +176,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 +194,9 @@ Brush properties. CD2DBrushProperties* m_pBrushProperties; ``` -## CD2DBrush::operator ID2D1Brush* +## `CD2DBrush::operator ID2D1Brush*` -Returns ID2D1Brush interface +Returns `ID2D1Brush` interface ``` operator ID2D1Brush*(); @@ -202,9 +204,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 +216,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 +229,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/cd2dbrushproperties-class.md b/docs/mfc/reference/cd2dbrushproperties-class.md index c28b4ec6722..527c0480618 100644 --- a/docs/mfc/reference/cd2dbrushproperties-class.md +++ b/docs/mfc/reference/cd2dbrushproperties-class.md @@ -4,10 +4,12 @@ title: "CD2DBrushProperties Class" ms.date: "11/04/2016" f1_keywords: ["CD2DBrushProperties", "AFXRENDERTARGET/CD2DBrushProperties", "AFXRENDERTARGET/CD2DBrushProperties::CD2DBrushProperties", "AFXRENDERTARGET/CD2DBrushProperties::CommonInit"] helpviewer_keywords: ["CD2DBrushProperties [MFC], CD2DBrushProperties", "CD2DBrushProperties [MFC], CommonInit"] -ms.assetid: c77d717f-0a16-4d74-b2ce-0ae1766ed6f9 --- # CD2DBrushProperties Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for `D2D1_BRUSH_PROPERTIES`. ## Syntax diff --git a/docs/mfc/reference/cd2dellipse-class.md b/docs/mfc/reference/cd2dellipse-class.md index dbe03207497..29caf8cb670 100644 --- a/docs/mfc/reference/cd2dellipse-class.md +++ b/docs/mfc/reference/cd2dellipse-class.md @@ -4,10 +4,12 @@ title: "CD2DEllipse Class" ms.date: "08/29/2019" f1_keywords: ["CD2DEllipse", "AFXRENDERTARGET/CD2DEllipse", "AFXRENDERTARGET/CD2DEllipse::CD2DEllipse"] helpviewer_keywords: ["CD2DEllipse [MFC], CD2DEllipse"] -ms.assetid: e9f02f54-acf2-427e-b349-db50cd9a77df --- # CD2DEllipse Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for `D2D1_ELLIPSE`. ## Syntax diff --git a/docs/mfc/reference/cd2dgeometry-class.md b/docs/mfc/reference/cd2dgeometry-class.md index 1c6a4178da5..30b66e593e1 100644 --- a/docs/mfc/reference/cd2dgeometry-class.md +++ b/docs/mfc/reference/cd2dgeometry-class.md @@ -4,10 +4,12 @@ title: "CD2DGeometry Class" ms.date: "11/04/2016" f1_keywords: ["CD2DGeometry", "AFXRENDERTARGET/CD2DGeometry", "AFXRENDERTARGET/CD2DGeometry::CD2DGeometry", "AFXRENDERTARGET/CD2DGeometry::Attach", "AFXRENDERTARGET/CD2DGeometry::CombineWithGeometry", "AFXRENDERTARGET/CD2DGeometry::CompareWithGeometry", "AFXRENDERTARGET/CD2DGeometry::ComputeArea", "AFXRENDERTARGET/CD2DGeometry::ComputeLength", "AFXRENDERTARGET/CD2DGeometry::ComputePointAtLength", "AFXRENDERTARGET/CD2DGeometry::Destroy", "AFXRENDERTARGET/CD2DGeometry::Detach", "AFXRENDERTARGET/CD2DGeometry::FillContainsPoint", "AFXRENDERTARGET/CD2DGeometry::Get", "AFXRENDERTARGET/CD2DGeometry::GetBounds", "AFXRENDERTARGET/CD2DGeometry::GetWidenedBounds", "AFXRENDERTARGET/CD2DGeometry::IsValid", "AFXRENDERTARGET/CD2DGeometry::Outline", "AFXRENDERTARGET/CD2DGeometry::Simplify", "AFXRENDERTARGET/CD2DGeometry::StrokeContainsPoint", "AFXRENDERTARGET/CD2DGeometry::Tessellate", "AFXRENDERTARGET/CD2DGeometry::Widen", "AFXRENDERTARGET/CD2DGeometry::m_pGeometry"] helpviewer_keywords: ["CD2DGeometry [MFC], CD2DGeometry", "CD2DGeometry [MFC], Attach", "CD2DGeometry [MFC], CombineWithGeometry", "CD2DGeometry [MFC], CompareWithGeometry", "CD2DGeometry [MFC], ComputeArea", "CD2DGeometry [MFC], ComputeLength", "CD2DGeometry [MFC], ComputePointAtLength", "CD2DGeometry [MFC], Destroy", "CD2DGeometry [MFC], Detach", "CD2DGeometry [MFC], FillContainsPoint", "CD2DGeometry [MFC], Get", "CD2DGeometry [MFC], GetBounds", "CD2DGeometry [MFC], GetWidenedBounds", "CD2DGeometry [MFC], IsValid", "CD2DGeometry [MFC], Outline", "CD2DGeometry [MFC], Simplify", "CD2DGeometry [MFC], StrokeContainsPoint", "CD2DGeometry [MFC], Tessellate", "CD2DGeometry [MFC], Widen", "CD2DGeometry [MFC], m_pGeometry"] -ms.assetid: 3f95054b-fdb8-4e87-87f2-9fc3df7279ec --- # CD2DGeometry Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1Geometry. ## Syntax @@ -239,7 +241,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/cd2dgeometrysink-class.md b/docs/mfc/reference/cd2dgeometrysink-class.md index ca50d6fef2a..f48b0a0569e 100644 --- a/docs/mfc/reference/cd2dgeometrysink-class.md +++ b/docs/mfc/reference/cd2dgeometrysink-class.md @@ -4,10 +4,12 @@ title: "CD2DGeometrySink Class" ms.date: "11/04/2016" f1_keywords: ["CD2DGeometrySink", "AFXRENDERTARGET/CD2DGeometrySink", "AFXRENDERTARGET/CD2DGeometrySink::CD2DGeometrySink", "AFXRENDERTARGET/CD2DGeometrySink::AddArc", "AFXRENDERTARGET/CD2DGeometrySink::AddBezier", "AFXRENDERTARGET/CD2DGeometrySink::AddBeziers", "AFXRENDERTARGET/CD2DGeometrySink::AddLine", "AFXRENDERTARGET/CD2DGeometrySink::AddLines", "AFXRENDERTARGET/CD2DGeometrySink::AddQuadraticBezier", "AFXRENDERTARGET/CD2DGeometrySink::AddQuadraticBeziers", "AFXRENDERTARGET/CD2DGeometrySink::BeginFigure", "AFXRENDERTARGET/CD2DGeometrySink::Close", "AFXRENDERTARGET/CD2DGeometrySink::EndFigure", "AFXRENDERTARGET/CD2DGeometrySink::Get", "AFXRENDERTARGET/CD2DGeometrySink::IsValid", "AFXRENDERTARGET/CD2DGeometrySink::SetFillMode", "AFXRENDERTARGET/CD2DGeometrySink::SetSegmentFlags", "AFXRENDERTARGET/CD2DGeometrySink::m_pSink"] helpviewer_keywords: ["CD2DGeometrySink [MFC], CD2DGeometrySink", "CD2DGeometrySink [MFC], AddArc", "CD2DGeometrySink [MFC], AddBezier", "CD2DGeometrySink [MFC], AddBeziers", "CD2DGeometrySink [MFC], AddLine", "CD2DGeometrySink [MFC], AddLines", "CD2DGeometrySink [MFC], AddQuadraticBezier", "CD2DGeometrySink [MFC], AddQuadraticBeziers", "CD2DGeometrySink [MFC], BeginFigure", "CD2DGeometrySink [MFC], Close", "CD2DGeometrySink [MFC], EndFigure", "CD2DGeometrySink [MFC], Get", "CD2DGeometrySink [MFC], IsValid", "CD2DGeometrySink [MFC], SetFillMode", "CD2DGeometrySink [MFC], SetSegmentFlags", "CD2DGeometrySink [MFC], m_pSink"] -ms.assetid: e5e07f41-0343-4ab1-9d6b-8c62ed33c04a --- # CD2DGeometrySink Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1GeometrySink. ## Syntax diff --git a/docs/mfc/reference/cd2dgradientbrush-class.md b/docs/mfc/reference/cd2dgradientbrush-class.md index f6611d222e0..b5c69b59e7e 100644 --- a/docs/mfc/reference/cd2dgradientbrush-class.md +++ b/docs/mfc/reference/cd2dgradientbrush-class.md @@ -4,10 +4,12 @@ title: "CD2DGradientBrush Class" ms.date: "03/27/2019" f1_keywords: ["CD2DGradientBrush", "AFXRENDERTARGET/CD2DGradientBrush", "AFXRENDERTARGET/CD2DGradientBrush::CD2DGradientBrush", "AFXRENDERTARGET/CD2DGradientBrush::Destroy", "AFXRENDERTARGET/CD2DGradientBrush::m_arGradientStops", "AFXRENDERTARGET/CD2DGradientBrush::m_colorInterpolationGamma", "AFXRENDERTARGET/CD2DGradientBrush::m_extendMode", "AFXRENDERTARGET/CD2DGradientBrush::m_pGradientStops"] helpviewer_keywords: ["CD2DGradientBrush [MFC], CD2DGradientBrush", "CD2DGradientBrush [MFC], Destroy", "CD2DGradientBrush [MFC], m_arGradientStops", "CD2DGradientBrush [MFC], m_colorInterpolationGamma", "CD2DGradientBrush [MFC], m_extendMode", "CD2DGradientBrush [MFC], m_pGradientStops"] -ms.assetid: 5bf133e6-16b7-4e3a-845d-0ce63fafe5ec --- # CD2DGradientBrush Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class of the CD2DLinearGradientBrush and the CD2DRadialGradientBrush classes. ## Syntax diff --git a/docs/mfc/reference/cd2dlayer-class.md b/docs/mfc/reference/cd2dlayer-class.md index 71d22b6df07..504d7151232 100644 --- a/docs/mfc/reference/cd2dlayer-class.md +++ b/docs/mfc/reference/cd2dlayer-class.md @@ -4,10 +4,12 @@ title: "CD2DLayer Class" ms.date: "11/04/2016" f1_keywords: ["CD2DLayer", "AFXRENDERTARGET/CD2DLayer", "AFXRENDERTARGET/CD2DLayer::CD2DLayer", "AFXRENDERTARGET/CD2DLayer::Attach", "AFXRENDERTARGET/CD2DLayer::Create", "AFXRENDERTARGET/CD2DLayer::Destroy", "AFXRENDERTARGET/CD2DLayer::Detach", "AFXRENDERTARGET/CD2DLayer::Get", "AFXRENDERTARGET/CD2DLayer::GetSize", "AFXRENDERTARGET/CD2DLayer::IsValid", "AFXRENDERTARGET/CD2DLayer::m_pLayer"] helpviewer_keywords: ["CD2DLayer [MFC], CD2DLayer", "CD2DLayer [MFC], Attach", "CD2DLayer [MFC], Create", "CD2DLayer [MFC], Destroy", "CD2DLayer [MFC], Detach", "CD2DLayer [MFC], Get", "CD2DLayer [MFC], GetSize", "CD2DLayer [MFC], IsValid", "CD2DLayer [MFC], m_pLayer"] -ms.assetid: 2f96378e-66bb-40d1-9661-6afe324de3c1 --- # CD2DLayer Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1Layer. ## Syntax diff --git a/docs/mfc/reference/cd2dlineargradientbrush-class.md b/docs/mfc/reference/cd2dlineargradientbrush-class.md index 70c1ca78877..dc008c90e2c 100644 --- a/docs/mfc/reference/cd2dlineargradientbrush-class.md +++ b/docs/mfc/reference/cd2dlineargradientbrush-class.md @@ -4,10 +4,12 @@ title: "CD2DLinearGradientBrush Class" ms.date: "11/04/2016" f1_keywords: ["CD2DLinearGradientBrush", "AFXRENDERTARGET/CD2DLinearGradientBrush", "AFXRENDERTARGET/CD2DLinearGradientBrush::CD2DLinearGradientBrush", "AFXRENDERTARGET/CD2DLinearGradientBrush::Attach", "AFXRENDERTARGET/CD2DLinearGradientBrush::Create", "AFXRENDERTARGET/CD2DLinearGradientBrush::Destroy", "AFXRENDERTARGET/CD2DLinearGradientBrush::Detach", "AFXRENDERTARGET/CD2DLinearGradientBrush::Get", "AFXRENDERTARGET/CD2DLinearGradientBrush::GetEndPoint", "AFXRENDERTARGET/CD2DLinearGradientBrush::GetStartPoint", "AFXRENDERTARGET/CD2DLinearGradientBrush::SetEndPoint", "AFXRENDERTARGET/CD2DLinearGradientBrush::SetStartPoint", "AFXRENDERTARGET/CD2DLinearGradientBrush::m_LinearGradientBrushProperties", "AFXRENDERTARGET/CD2DLinearGradientBrush::m_pLinearGradientBrush"] helpviewer_keywords: ["CD2DLinearGradientBrush [MFC], CD2DLinearGradientBrush", "CD2DLinearGradientBrush [MFC], Attach", "CD2DLinearGradientBrush [MFC], Create", "CD2DLinearGradientBrush [MFC], Destroy", "CD2DLinearGradientBrush [MFC], Detach", "CD2DLinearGradientBrush [MFC], Get", "CD2DLinearGradientBrush [MFC], GetEndPoint", "CD2DLinearGradientBrush [MFC], GetStartPoint", "CD2DLinearGradientBrush [MFC], SetEndPoint", "CD2DLinearGradientBrush [MFC], SetStartPoint", "CD2DLinearGradientBrush [MFC], m_LinearGradientBrushProperties", "CD2DLinearGradientBrush [MFC], m_pLinearGradientBrush"] -ms.assetid: d4be9ff9-0ea8-45e6-9b8d-f3bc5673cbac --- # CD2DLinearGradientBrush Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1LinearGradientBrush. ## Syntax diff --git a/docs/mfc/reference/cd2dmesh-class.md b/docs/mfc/reference/cd2dmesh-class.md index 1c00d6b8ab2..7b769ec7df4 100644 --- a/docs/mfc/reference/cd2dmesh-class.md +++ b/docs/mfc/reference/cd2dmesh-class.md @@ -4,10 +4,12 @@ title: "CD2DMesh Class" ms.date: "11/04/2016" f1_keywords: ["CD2DMesh", "AFXRENDERTARGET/CD2DMesh", "AFXRENDERTARGET/CD2DMesh::CD2DMesh", "AFXRENDERTARGET/CD2DMesh::Attach", "AFXRENDERTARGET/CD2DMesh::Create", "AFXRENDERTARGET/CD2DMesh::Destroy", "AFXRENDERTARGET/CD2DMesh::Detach", "AFXRENDERTARGET/CD2DMesh::Get", "AFXRENDERTARGET/CD2DMesh::IsValid", "AFXRENDERTARGET/CD2DMesh::Open", "AFXRENDERTARGET/CD2DMesh::m_pMesh"] helpviewer_keywords: ["CD2DMesh [MFC], CD2DMesh", "CD2DMesh [MFC], Attach", "CD2DMesh [MFC], Create", "CD2DMesh [MFC], Destroy", "CD2DMesh [MFC], Detach", "CD2DMesh [MFC], Get", "CD2DMesh [MFC], IsValid", "CD2DMesh [MFC], Open", "CD2DMesh [MFC], m_pMesh"] -ms.assetid: 11a2c78a-1367-40e8-a34f-44aa0509a4c9 --- # CD2DMesh Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1Mesh. ## Syntax diff --git a/docs/mfc/reference/cd2dpathgeometry-class.md b/docs/mfc/reference/cd2dpathgeometry-class.md index 26d66a55e56..5b7fd0c32a3 100644 --- a/docs/mfc/reference/cd2dpathgeometry-class.md +++ b/docs/mfc/reference/cd2dpathgeometry-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1PathGeometry. ## Syntax @@ -32,7 +34,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 +129,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/cd2dpointf-class.md b/docs/mfc/reference/cd2dpointf-class.md index da1e32fae53..be72cbd1f06 100644 --- a/docs/mfc/reference/cd2dpointf-class.md +++ b/docs/mfc/reference/cd2dpointf-class.md @@ -4,10 +4,12 @@ title: "CD2DPointF Class" ms.date: "11/04/2016" f1_keywords: ["CD2DPointF", "AFXRENDERTARGET/CD2DPointF", "AFXRENDERTARGET/CD2DPointF::CD2DPointF"] helpviewer_keywords: ["CD2DPointF [MFC], CD2DPointF"] -ms.assetid: 30f72083-1c8a-4f50-adb2-72dbbe3522d4 --- # CD2DPointF Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for `D2D1_POINT_2F`. ## Syntax diff --git a/docs/mfc/reference/cd2dpointu-class.md b/docs/mfc/reference/cd2dpointu-class.md index a7496417187..40d1d16f15e 100644 --- a/docs/mfc/reference/cd2dpointu-class.md +++ b/docs/mfc/reference/cd2dpointu-class.md @@ -4,10 +4,12 @@ title: "CD2DPointU Class" ms.date: "08/29/2019" f1_keywords: ["CD2DPointU", "AFXRENDERTARGET/CD2DPointU", "AFXRENDERTARGET/CD2DPointU::CD2DPointU"] helpviewer_keywords: ["CD2DPointU [MFC], CD2DPointU"] -ms.assetid: 04733f96-b6de-4a89-82e3-caad1e8087a9 --- # CD2DPointU Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for `D2D1_POINT_2U`. ## Syntax diff --git a/docs/mfc/reference/cd2dradialgradientbrush-class.md b/docs/mfc/reference/cd2dradialgradientbrush-class.md index 6bedb70852f..3cd841c1f05 100644 --- a/docs/mfc/reference/cd2dradialgradientbrush-class.md +++ b/docs/mfc/reference/cd2dradialgradientbrush-class.md @@ -4,10 +4,12 @@ title: "CD2DRadialGradientBrush Class" ms.date: "11/04/2016" f1_keywords: ["CD2DRadialGradientBrush", "AFXRENDERTARGET/CD2DRadialGradientBrush", "AFXRENDERTARGET/CD2DRadialGradientBrush::CD2DRadialGradientBrush", "AFXRENDERTARGET/CD2DRadialGradientBrush::Attach", "AFXRENDERTARGET/CD2DRadialGradientBrush::Create", "AFXRENDERTARGET/CD2DRadialGradientBrush::Destroy", "AFXRENDERTARGET/CD2DRadialGradientBrush::Detach", "AFXRENDERTARGET/CD2DRadialGradientBrush::Get", "AFXRENDERTARGET/CD2DRadialGradientBrush::GetCenter", "AFXRENDERTARGET/CD2DRadialGradientBrush::GetGradientOriginOffset", "AFXRENDERTARGET/CD2DRadialGradientBrush::GetRadiusX", "AFXRENDERTARGET/CD2DRadialGradientBrush::GetRadiusY", "AFXRENDERTARGET/CD2DRadialGradientBrush::SetCenter", "AFXRENDERTARGET/CD2DRadialGradientBrush::SetGradientOriginOffset", "AFXRENDERTARGET/CD2DRadialGradientBrush::SetRadiusX", "AFXRENDERTARGET/CD2DRadialGradientBrush::SetRadiusY", "AFXRENDERTARGET/CD2DRadialGradientBrush::m_pRadialGradientBrush", "AFXRENDERTARGET/CD2DRadialGradientBrush::m_RadialGradientBrushProperties"] helpviewer_keywords: ["CD2DRadialGradientBrush [MFC], CD2DRadialGradientBrush", "CD2DRadialGradientBrush [MFC], Attach", "CD2DRadialGradientBrush [MFC], Create", "CD2DRadialGradientBrush [MFC], Destroy", "CD2DRadialGradientBrush [MFC], Detach", "CD2DRadialGradientBrush [MFC], Get", "CD2DRadialGradientBrush [MFC], GetCenter", "CD2DRadialGradientBrush [MFC], GetGradientOriginOffset", "CD2DRadialGradientBrush [MFC], GetRadiusX", "CD2DRadialGradientBrush [MFC], GetRadiusY", "CD2DRadialGradientBrush [MFC], SetCenter", "CD2DRadialGradientBrush [MFC], SetGradientOriginOffset", "CD2DRadialGradientBrush [MFC], SetRadiusX", "CD2DRadialGradientBrush [MFC], SetRadiusY", "CD2DRadialGradientBrush [MFC], m_pRadialGradientBrush", "CD2DRadialGradientBrush [MFC], m_RadialGradientBrushProperties"] -ms.assetid: 6c76d84a-d831-4ee2-96f1-82c1f5b0d6a9 --- # CD2DRadialGradientBrush Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1RadialGradientBrush. ## Syntax diff --git a/docs/mfc/reference/cd2drectf-class.md b/docs/mfc/reference/cd2drectf-class.md index 967b8fb9227..9f04d36e4ed 100644 --- a/docs/mfc/reference/cd2drectf-class.md +++ b/docs/mfc/reference/cd2drectf-class.md @@ -4,10 +4,12 @@ title: "CD2DRectF Class" ms.date: "11/04/2016" f1_keywords: ["CD2DRectF", "AFXRENDERTARGET/CD2DRectF", "AFXRENDERTARGET/CD2DRectF::CD2DRectF", "AFXRENDERTARGET/CD2DRectF::IsNull"] helpviewer_keywords: ["CD2DRectF [MFC], CD2DRectF", "CD2DRectF [MFC], IsNull"] -ms.assetid: 87c12d87-9d18-4a19-ba14-0f51d6b6835a --- # CD2DRectF Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for `D2D1_RECT_F`. ## Syntax diff --git a/docs/mfc/reference/cd2drectu-class.md b/docs/mfc/reference/cd2drectu-class.md index 2e49d1489ae..a88732c9fb7 100644 --- a/docs/mfc/reference/cd2drectu-class.md +++ b/docs/mfc/reference/cd2drectu-class.md @@ -4,10 +4,12 @@ title: "CD2DRectU Class" ms.date: "11/04/2016" f1_keywords: ["CD2DRectU", "AFXRENDERTARGET/CD2DRectU", "AFXRENDERTARGET/CD2DRectU::CD2DRectU", "AFXRENDERTARGET/CD2DRectU::IsNull"] helpviewer_keywords: ["CD2DRectU [MFC], CD2DRectU", "CD2DRectU [MFC], IsNull"] -ms.assetid: a62f17d1-011d-4867-8f51-fd7e7c00561d --- # CD2DRectU Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for `D2D1_RECT_U`. ## Syntax diff --git a/docs/mfc/reference/cd2dresource-class.md b/docs/mfc/reference/cd2dresource-class.md index fa6c42d756a..d4e355f07f3 100644 --- a/docs/mfc/reference/cd2dresource-class.md +++ b/docs/mfc/reference/cd2dresource-class.md @@ -4,10 +4,12 @@ title: "CD2DResource Class" ms.date: "03/27/2019" f1_keywords: ["CD2DResource", "AFXRENDERTARGET/CD2DResource", "AFXRENDERTARGET/CD2DResource::CD2DResource", "AFXRENDERTARGET/CD2DResource::Create", "AFXRENDERTARGET/CD2DResource::Destroy", "AFXRENDERTARGET/CD2DResource::IsValid", "AFXRENDERTARGET/CD2DResource::IsAutoDestroy", "AFXRENDERTARGET/CD2DResource::ReCreate", "AFXRENDERTARGET/CD2DResource::m_bIsAutoDestroy", "AFXRENDERTARGET/CD2DResource::m_pParentTarget"] helpviewer_keywords: ["CD2DResource [MFC], CD2DResource", "CD2DResource [MFC], Create", "CD2DResource [MFC], Destroy", "CD2DResource [MFC], IsValid", "CD2DResource [MFC], IsAutoDestroy", "CD2DResource [MFC], ReCreate", "CD2DResource [MFC], m_bIsAutoDestroy", "CD2DResource [MFC], m_pParentTarget"] -ms.assetid: 34e3ee18-aab6-4c39-9294-de869e1f7820 --- # CD2DResource Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An abstract class that provides an interface for creating and managing D2D resources such as brushes, layers, and texts. ## Syntax diff --git a/docs/mfc/reference/cd2droundedrect-class.md b/docs/mfc/reference/cd2droundedrect-class.md index fc3e784f5ef..e93423f089c 100644 --- a/docs/mfc/reference/cd2droundedrect-class.md +++ b/docs/mfc/reference/cd2droundedrect-class.md @@ -4,10 +4,12 @@ title: "CD2DRoundedRect Class" ms.date: "11/04/2016" f1_keywords: ["CD2DRoundedRect", "AFXRENDERTARGET/CD2DRoundedRect", "AFXRENDERTARGET/CD2DRoundedRect::CD2DRoundedRect"] helpviewer_keywords: ["CD2DRoundedRect [MFC], CD2DRoundedRect"] -ms.assetid: 06207fb5-e92b-41c0-bceb-b45d8f466531 --- # CD2DRoundedRect Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for `D2D1_ROUNDED_RECT`. ## Syntax diff --git a/docs/mfc/reference/cd2dsizef-class.md b/docs/mfc/reference/cd2dsizef-class.md index 5b1d39d894a..a4458cedd76 100644 --- a/docs/mfc/reference/cd2dsizef-class.md +++ b/docs/mfc/reference/cd2dsizef-class.md @@ -4,10 +4,12 @@ title: "CD2DSizeF Class" ms.date: "08/29/2019" f1_keywords: ["CD2DSizeF", "AFXRENDERTARGET/CD2DSizeF", "AFXRENDERTARGET/CD2DSizeF::CD2DSizeF", "AFXRENDERTARGET/CD2DSizeF::IsNull"] helpviewer_keywords: ["CD2DSizeF [MFC], CD2DSizeF", "CD2DSizeF [MFC], IsNull"] -ms.assetid: f486a1e1-997d-4286-8cb9-26369dc82055 --- # CD2DSizeF Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for D2D1_SIZE_F. ## Syntax diff --git a/docs/mfc/reference/cd2dsizeu-class.md b/docs/mfc/reference/cd2dsizeu-class.md index 464d7d1b622..819e251ae7b 100644 --- a/docs/mfc/reference/cd2dsizeu-class.md +++ b/docs/mfc/reference/cd2dsizeu-class.md @@ -4,10 +4,12 @@ title: "CD2DSizeU Class" ms.date: "08/29/2019" f1_keywords: ["CD2DSizeU", "AFXRENDERTARGET/CD2DSizeU", "AFXRENDERTARGET/CD2DSizeU::CD2DSizeU", "AFXRENDERTARGET/CD2DSizeU::IsNull"] helpviewer_keywords: ["CD2DSizeU [MFC], CD2DSizeU", "CD2DSizeU [MFC], IsNull"] -ms.assetid: 6e679ba8-2112-43c3-8275-70b660856f02 --- # CD2DSizeU Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for D2D1_SIZE_U. ## Syntax diff --git a/docs/mfc/reference/cd2dsolidcolorbrush-class.md b/docs/mfc/reference/cd2dsolidcolorbrush-class.md index 177c2fc3fef..c343346e6a8 100644 --- a/docs/mfc/reference/cd2dsolidcolorbrush-class.md +++ b/docs/mfc/reference/cd2dsolidcolorbrush-class.md @@ -4,10 +4,12 @@ title: "CD2DSolidColorBrush Class" ms.date: "03/27/2019" f1_keywords: ["CD2DSolidColorBrush", "AFXRENDERTARGET/CD2DSolidColorBrush", "AFXRENDERTARGET/CD2DSolidColorBrush::CD2DSolidColorBrush", "AFXRENDERTARGET/CD2DSolidColorBrush::Attach", "AFXRENDERTARGET/CD2DSolidColorBrush::Create", "AFXRENDERTARGET/CD2DSolidColorBrush::Destroy", "AFXRENDERTARGET/CD2DSolidColorBrush::Detach", "AFXRENDERTARGET/CD2DSolidColorBrush::Get", "AFXRENDERTARGET/CD2DSolidColorBrush::GetColor", "AFXRENDERTARGET/CD2DSolidColorBrush::SetColor", "AFXRENDERTARGET/CD2DSolidColorBrush::m_colorSolid", "AFXRENDERTARGET/CD2DSolidColorBrush::m_pSolidColorBrush"] helpviewer_keywords: ["CD2DSolidColorBrush [MFC], CD2DSolidColorBrush", "CD2DSolidColorBrush [MFC], Attach", "CD2DSolidColorBrush [MFC], Create", "CD2DSolidColorBrush [MFC], Destroy", "CD2DSolidColorBrush [MFC], Detach", "CD2DSolidColorBrush [MFC], Get", "CD2DSolidColorBrush [MFC], GetColor", "CD2DSolidColorBrush [MFC], SetColor", "CD2DSolidColorBrush [MFC], m_colorSolid", "CD2DSolidColorBrush [MFC], m_pSolidColorBrush"] -ms.assetid: d4506637-acce-4f74-8a9b-f0a45571a735 --- # CD2DSolidColorBrush Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1SolidColorBrush. ## Syntax diff --git a/docs/mfc/reference/cd2dtextformat-class.md b/docs/mfc/reference/cd2dtextformat-class.md index 258818a08a6..94bffc9c182 100644 --- a/docs/mfc/reference/cd2dtextformat-class.md +++ b/docs/mfc/reference/cd2dtextformat-class.md @@ -4,10 +4,12 @@ title: "CD2DTextFormat Class" ms.date: "03/27/2019" f1_keywords: ["CD2DTextFormat", "AFXRENDERTARGET/CD2DTextFormat", "AFXRENDERTARGET/CD2DTextFormat::CD2DTextFormat", "AFXRENDERTARGET/CD2DTextFormat::Create", "AFXRENDERTARGET/CD2DTextFormat::Destroy", "AFXRENDERTARGET/CD2DTextFormat::Get", "AFXRENDERTARGET/CD2DTextFormat::GetFontFamilyName", "AFXRENDERTARGET/CD2DTextFormat::GetLocaleName", "AFXRENDERTARGET/CD2DTextFormat::IsValid", "AFXRENDERTARGET/CD2DTextFormat::ReCreate", "AFXRENDERTARGET/CD2DTextFormat::m_pTextFormat"] helpviewer_keywords: ["CD2DTextFormat [MFC], CD2DTextFormat", "CD2DTextFormat [MFC], Create", "CD2DTextFormat [MFC], Destroy", "CD2DTextFormat [MFC], Get", "CD2DTextFormat [MFC], GetFontFamilyName", "CD2DTextFormat [MFC], GetLocaleName", "CD2DTextFormat [MFC], IsValid", "CD2DTextFormat [MFC], ReCreate", "CD2DTextFormat [MFC], m_pTextFormat"] -ms.assetid: db194cec-9dae-4644-ab84-7c43b7164117 --- # CD2DTextFormat Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for IDWriteTextFormat. ## Syntax diff --git a/docs/mfc/reference/cd2dtextlayout-class.md b/docs/mfc/reference/cd2dtextlayout-class.md index 02fe965fb31..574552a8d41 100644 --- a/docs/mfc/reference/cd2dtextlayout-class.md +++ b/docs/mfc/reference/cd2dtextlayout-class.md @@ -4,10 +4,12 @@ title: "CD2DTextLayout Class" ms.date: "03/27/2019" f1_keywords: ["CD2DTextLayout", "AFXRENDERTARGET/CD2DTextLayout", "AFXRENDERTARGET/CD2DTextLayout::CD2DTextLayout", "AFXRENDERTARGET/CD2DTextLayout::Create", "AFXRENDERTARGET/CD2DTextLayout::Destroy", "AFXRENDERTARGET/CD2DTextLayout::Get", "AFXRENDERTARGET/CD2DTextLayout::GetFontFamilyName", "AFXRENDERTARGET/CD2DTextLayout::GetLocaleName", "AFXRENDERTARGET/CD2DTextLayout::IsValid", "AFXRENDERTARGET/CD2DTextLayout::ReCreate", "AFXRENDERTARGET/CD2DTextLayout::SetFontFamilyName", "AFXRENDERTARGET/CD2DTextLayout::SetLocaleName", "AFXRENDERTARGET/CD2DTextLayout::m_pTextLayout"] helpviewer_keywords: ["CD2DTextLayout [MFC], CD2DTextLayout", "CD2DTextLayout [MFC], Create", "CD2DTextLayout [MFC], Destroy", "CD2DTextLayout [MFC], Get", "CD2DTextLayout [MFC], GetFontFamilyName", "CD2DTextLayout [MFC], GetLocaleName", "CD2DTextLayout [MFC], IsValid", "CD2DTextLayout [MFC], ReCreate", "CD2DTextLayout [MFC], SetFontFamilyName", "CD2DTextLayout [MFC], SetLocaleName", "CD2DTextLayout [MFC], m_pTextLayout"] -ms.assetid: 724bd13c-f2ef-4e55-a775-8cb04b7b7908 --- # CD2DTextLayout Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for IDWriteTextLayout. ## Syntax diff --git a/docs/mfc/reference/cdaodatabase-class.md b/docs/mfc/reference/cdaodatabase-class.md index 81d9b3cb0d7..817e7f6ea26 100644 --- a/docs/mfc/reference/cdaodatabase-class.md +++ b/docs/mfc/reference/cdaodatabase-class.md @@ -4,11 +4,17 @@ 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 +ms.custom: sfi-ropc-nochange --- # 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +47,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 +56,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 +81,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 +100,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 +174,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 +198,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 +249,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 +280,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 +313,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 +323,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 +399,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 +418,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 +449,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 +558,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 +578,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 +752,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 +769,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 +777,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 +789,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 +804,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 +831,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 0c65d02f3cf..e01c08c24f7 100644 --- a/docs/mfc/reference/cdaodatabaseinfo-structure.md +++ b/docs/mfc/reference/cdaodatabaseinfo-structure.md @@ -4,11 +4,16 @@ 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +99,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 686a487153e..4e34fad326c 100644 --- a/docs/mfc/reference/cdaoerrorinfo-structure.md +++ b/docs/mfc/reference/cdaoerrorinfo-structure.md @@ -4,11 +4,16 @@ 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +55,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 10e48df0626..d0d03730f6b 100644 --- a/docs/mfc/reference/cdaoexception-class.md +++ b/docs/mfc/reference/cdaoexception-class.md @@ -4,15 +4,20 @@ 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +53,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 +61,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 +83,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 +115,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 +161,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 +193,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 44eab5cdfe4..af11986eaa1 100644 --- a/docs/mfc/reference/cdaofieldexchange-class.md +++ b/docs/mfc/reference/cdaofieldexchange-class.md @@ -1,16 +1,19 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +47,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 +63,7 @@ The [IsValidOperation](#isvalidoperation) member function is provided for writin ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoFieldExchange::IsValidOperation @@ -89,7 +92,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 b816e163d4e..6db2749e23d 100644 --- a/docs/mfc/reference/cdaofieldinfo-structure.md +++ b/docs/mfc/reference/cdaofieldinfo-structure.md @@ -4,13 +4,16 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +149,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 160831669cb..b7b20cca2d7 100644 --- a/docs/mfc/reference/cdaoindexfieldinfo-structure.md +++ b/docs/mfc/reference/cdaoindexfieldinfo-structure.md @@ -4,13 +4,16 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +43,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 390978f486f..be9ddb6cda6 100644 --- a/docs/mfc/reference/cdaoindexinfo-structure.md +++ b/docs/mfc/reference/cdaoindexinfo-structure.md @@ -4,12 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +103,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 50b0f3407d8..4fcf70aef04 100644 --- a/docs/mfc/reference/cdaoparameterinfo-structure.md +++ b/docs/mfc/reference/cdaoparameterinfo-structure.md @@ -4,11 +4,16 @@ 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +41,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 +52,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 a1613f393f8..a9a1a58c780 100644 --- a/docs/mfc/reference/cdaoquerydef-class.md +++ b/docs/mfc/reference/cdaoquerydef-class.md @@ -4,15 +4,20 @@ 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 + +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. 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 +44,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 +70,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 +85,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 +102,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 +127,7 @@ For related information, see the topics "QueryDef Object", "QueryDefs Collection ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoQueryDef::Append @@ -140,7 +145,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 +153,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 +186,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 +202,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 +217,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 +251,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 +264,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 +285,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 +314,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 +322,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 +342,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 +378,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 +433,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 +455,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 +504,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 +516,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 +552,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 +592,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 +613,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 +621,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 +629,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 +642,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 +663,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 +674,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 +704,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 +735,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 +775,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 c42b9f33333..189ccc92e46 100644 --- a/docs/mfc/reference/cdaoquerydefinfo-structure.md +++ b/docs/mfc/reference/cdaoquerydefinfo-structure.md @@ -4,12 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +38,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 +86,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 1e04df6fb4c..5e2e7a99aaa 100644 --- a/docs/mfc/reference/cdaorecordset-class.md +++ b/docs/mfc/reference/cdaorecordset-class.md @@ -1,15 +1,21 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +75,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 +113,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 +127,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 +152,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 +166,7 @@ For related information, see the topic "Recordset Object" in DAO Help. ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## CDaoRecordset::AddNew @@ -172,7 +178,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 +187,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 +195,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 +218,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 +238,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 +252,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 +275,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 +344,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 +353,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 +365,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 +385,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 +411,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 +434,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 +457,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 +481,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 +532,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 +559,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 +574,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 +613,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 +655,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 +697,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 +732,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 +758,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 +779,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 +802,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 +1021,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 +1043,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 +1105,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 +1125,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 +1194,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 +1212,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 +1281,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 +1301,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 +1333,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 +1344,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 +1374,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 +1406,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 +1417,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 +1449,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 +1472,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 +1480,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 +1501,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 +1513,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 +1540,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 +1575,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 +1585,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 +1599,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 +1626,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 +1647,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 +1657,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 +1685,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 +1703,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 +1713,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 +1729,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 +1739,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 +1797,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 +1813,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 +1824,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 +1859,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 +1884,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 +1938,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 +1948,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 +1986,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 +2013,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 +2028,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 +2057,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 +2080,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 +2101,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 +2121,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 +2144,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 +2153,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 +2168,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 +2210,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 +2233,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 +2252,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 +2291,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 +2312,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 +2334,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 +2357,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 616077e525d..ac74d10bda4 100644 --- a/docs/mfc/reference/cdaorecordview-class.md +++ b/docs/mfc/reference/cdaorecordview-class.md @@ -4,12 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +75,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 f77f5502ff7..fca6e68a814 100644 --- a/docs/mfc/reference/cdaorelationfieldinfo-structure.md +++ b/docs/mfc/reference/cdaorelationfieldinfo-structure.md @@ -4,12 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +35,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 5152258fe06..23b62170c85 100644 --- a/docs/mfc/reference/cdaorelationinfo-structure.md +++ b/docs/mfc/reference/cdaorelationinfo-structure.md @@ -4,11 +4,16 @@ 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +76,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 2078bc7bb02..2c76e899c5f 100644 --- a/docs/mfc/reference/cdaotabledef-class.md +++ b/docs/mfc/reference/cdaotabledef-class.md @@ -4,12 +4,18 @@ 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 +ms.custom: sfi-ropc-nochange --- # CDaoTableDef Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +120,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 +426,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 eef34d4ef36..d554bc069f5 100644 --- a/docs/mfc/reference/cdaotabledefinfo-structure.md +++ b/docs/mfc/reference/cdaotabledefinfo-structure.md @@ -4,12 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +87,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 0b0f9fb5915..b482e263b68 100644 --- a/docs/mfc/reference/cdaoworkspace-class.md +++ b/docs/mfc/reference/cdaoworkspace-class.md @@ -4,15 +4,21 @@ 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 +ms.custom: sfi-ropc-nochange --- # 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +54,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 +69,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 +88,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 +96,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 +116,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 +128,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 +146,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 +207,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 +224,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 +256,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 +295,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 +309,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 +358,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 +428,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 +450,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 +472,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 +486,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 +504,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 +522,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 +544,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 +601,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 +653,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 +698,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 +718,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 +740,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 +769,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 +803,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 +820,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 +841,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 790e286f321..b35ed93deab 100644 --- a/docs/mfc/reference/cdaoworkspaceinfo-structure.md +++ b/docs/mfc/reference/cdaoworkspaceinfo-structure.md @@ -4,12 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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 +45,7 @@ Information retrieved by the [CDaoWorkspace::GetWorkspaceInfo](../../mfc/referen ## Requirements -**Header:** afxdao.h +**Header:** `afxdao.h` ## See also diff --git a/docs/mfc/reference/cdatabase-class.md b/docs/mfc/reference/cdatabase-class.md index aa96521cb0a..b6b22b72799 100644 --- a/docs/mfc/reference/cdatabase-class.md +++ b/docs/mfc/reference/cdatabase-class.md @@ -4,9 +4,13 @@ title: "CDatabase Class" ms.date: "11/04/2016" f1_keywords: ["CDatabase", "AFXDB/CDatabase", "AFXDB/CDatabase::CDatabase", "AFXDB/CDatabase::BeginTrans", "AFXDB/CDatabase::BindParameters", "AFXDB/CDatabase::Cancel", "AFXDB/CDatabase::CanTransact", "AFXDB/CDatabase::CanUpdate", "AFXDB/CDatabase::Close", "AFXDB/CDatabase::CommitTrans", "AFXDB/CDatabase::ExecuteSQL", "AFXDB/CDatabase::GetBookmarkPersistence", "AFXDB/CDatabase::GetConnect", "AFXDB/CDatabase::GetCursorCommitBehavior", "AFXDB/CDatabase::GetCursorRollbackBehavior", "AFXDB/CDatabase::GetDatabaseName", "AFXDB/CDatabase::IsOpen", "AFXDB/CDatabase::OnSetOptions", "AFXDB/CDatabase::Open", "AFXDB/CDatabase::OpenEx", "AFXDB/CDatabase::Rollback", "AFXDB/CDatabase::SetLoginTimeout", "AFXDB/CDatabase::SetQueryTimeout", "AFXDB/CDatabase::m_hdbc"] helpviewer_keywords: ["CDatabase [MFC], CDatabase", "CDatabase [MFC], BeginTrans", "CDatabase [MFC], BindParameters", "CDatabase [MFC], Cancel", "CDatabase [MFC], CanTransact", "CDatabase [MFC], CanUpdate", "CDatabase [MFC], Close", "CDatabase [MFC], CommitTrans", "CDatabase [MFC], ExecuteSQL", "CDatabase [MFC], GetBookmarkPersistence", "CDatabase [MFC], GetConnect", "CDatabase [MFC], GetCursorCommitBehavior", "CDatabase [MFC], GetCursorRollbackBehavior", "CDatabase [MFC], GetDatabaseName", "CDatabase [MFC], IsOpen", "CDatabase [MFC], OnSetOptions", "CDatabase [MFC], Open", "CDatabase [MFC], OpenEx", "CDatabase [MFC], Rollback", "CDatabase [MFC], SetLoginTimeout", "CDatabase [MFC], SetQueryTimeout", "CDatabase [MFC], m_hdbc"] +ms.custom: sfi-ropc-nochange --- # `CDatabase` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a connection to a data source, through which you can operate on the data source. ## Syntax @@ -193,7 +197,7 @@ You may find it convenient to embed the `CDatabase` object in your document clas This example illustrates using `CDatabase` in a `CDocument`-derived class. [!code-cpp[NVC_MFCDatabase#9](../../mfc/codesnippet/cpp/cdatabase-class_1.h)] - +  [!code-cpp[NVC_MFCDatabase#10](../../mfc/codesnippet/cpp/cdatabase-class_2.cpp)] ## `CDatabase::Close` diff --git a/docs/mfc/reference/cdataexchange-class.md b/docs/mfc/reference/cdataexchange-class.md index 36773b0d836..c8db1f00f28 100644 --- a/docs/mfc/reference/cdataexchange-class.md +++ b/docs/mfc/reference/cdataexchange-class.md @@ -4,10 +4,12 @@ title: "CDataExchange Class" ms.date: "11/04/2016" f1_keywords: ["CDataExchange", "AFXWIN/CDataExchange", "AFXWIN/CDataExchange::CDataExchange", "AFXWIN/CDataExchange::Fail", "AFXWIN/CDataExchange::PrepareCtrl", "AFXWIN/CDataExchange::PrepareEditCtrl", "AFXWIN/CDataExchange::PrepareOleCtrl", "AFXWIN/CDataExchange::m_bSaveAndValidate", "AFXWIN/CDataExchange::m_pDlgWnd"] helpviewer_keywords: ["CDataExchange [MFC], CDataExchange", "CDataExchange [MFC], Fail", "CDataExchange [MFC], PrepareCtrl", "CDataExchange [MFC], PrepareEditCtrl", "CDataExchange [MFC], PrepareOleCtrl", "CDataExchange [MFC], m_bSaveAndValidate", "CDataExchange [MFC], m_pDlgWnd"] -ms.assetid: 84ed6113-325d-493e-a75d-223f03a992b8 --- # CDataExchange Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports the dialog data exchange (DDX) and dialog data validation (DDV) routines used by the Microsoft Foundation classes. ## Syntax diff --git a/docs/mfc/reference/cdatapathproperty-class.md b/docs/mfc/reference/cdatapathproperty-class.md index 46de01c0c6b..d98aad1fe22 100644 --- a/docs/mfc/reference/cdatapathproperty-class.md +++ b/docs/mfc/reference/cdatapathproperty-class.md @@ -4,10 +4,12 @@ title: "CDataPathProperty Class" ms.date: "11/04/2016" f1_keywords: ["CDataPathProperty", "AFXCTL/CDataPathProperty", "AFXCTL/CDataPathProperty::CDataPathProperty", "AFXCTL/CDataPathProperty::GetControl", "AFXCTL/CDataPathProperty::GetPath", "AFXCTL/CDataPathProperty::Open", "AFXCTL/CDataPathProperty::ResetData", "AFXCTL/CDataPathProperty::SetControl", "AFXCTL/CDataPathProperty::SetPath"] helpviewer_keywords: ["CDataPathProperty [MFC], CDataPathProperty", "CDataPathProperty [MFC], GetControl", "CDataPathProperty [MFC], GetPath", "CDataPathProperty [MFC], Open", "CDataPathProperty [MFC], ResetData", "CDataPathProperty [MFC], SetControl", "CDataPathProperty [MFC], SetPath"] -ms.assetid: 1f96efdb-54e4-460b-862c-eba5d4103488 --- # CDataPathProperty Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements an OLE control property that can be loaded asynchronously. ## Syntax diff --git a/docs/mfc/reference/cdatarecoveryhandler-class.md b/docs/mfc/reference/cdatarecoveryhandler-class.md index e66f75c9646..8c5793cbe90 100644 --- a/docs/mfc/reference/cdatarecoveryhandler-class.md +++ b/docs/mfc/reference/cdatarecoveryhandler-class.md @@ -4,10 +4,12 @@ title: "CDataRecoveryHandler Class" ms.date: "03/27/2019" f1_keywords: ["CDataRecoveryHandler", "AFXDATARECOVERY/CDataRecoveryHandler", "AFXDATARECOVERY/CDataRecoveryHandler::CDataRecoveryHandler", "AFXDATARECOVERY/CDataRecoveryHandler::AutosaveAllDocumentInfo", "AFXDATARECOVERY/CDataRecoveryHandler::AutosaveDocumentInfo", "AFXDATARECOVERY/CDataRecoveryHandler::CreateDocumentInfo", "AFXDATARECOVERY/CDataRecoveryHandler::DeleteAllAutosavedFiles", "AFXDATARECOVERY/CDataRecoveryHandler::DeleteAutosavedFile", "AFXDATARECOVERY/CDataRecoveryHandler::GenerateAutosaveFileName", "AFXDATARECOVERY/CDataRecoveryHandler::GetAutosaveInterval", "AFXDATARECOVERY/CDataRecoveryHandler::GetAutosavePath", "AFXDATARECOVERY/CDataRecoveryHandler::GetDocumentListName", "AFXDATARECOVERY/CDataRecoveryHandler::GetNormalDocumentTitle", "AFXDATARECOVERY/CDataRecoveryHandler::GetRecoveredDocumentTitle", "AFXDATARECOVERY/CDataRecoveryHandler::GetRestartIdentifier", "AFXDATARECOVERY/CDataRecoveryHandler::GetSaveDocumentInfoOnIdle", "AFXDATARECOVERY/CDataRecoveryHandler::GetShutdownByRestartManager", "AFXDATARECOVERY/CDataRecoveryHandler::Initialize", "AFXDATARECOVERY/CDataRecoveryHandler::QueryRestoreAutosavedDocuments", "AFXDATARECOVERY/CDataRecoveryHandler::ReadOpenDocumentList", "AFXDATARECOVERY/CDataRecoveryHandler::RemoveDocumentInfo", "AFXDATARECOVERY/CDataRecoveryHandler::ReopenPreviousDocuments", "AFXDATARECOVERY/CDataRecoveryHandler::RestoreAutosavedDocuments", "AFXDATARECOVERY/CDataRecoveryHandler::SaveOpenDocumentList", "AFXDATARECOVERY/CDataRecoveryHandler::SetAutosaveInterval", "AFXDATARECOVERY/CDataRecoveryHandler::SetAutosavePath", "AFXDATARECOVERY/CDataRecoveryHandler::SetRestartIdentifier", "AFXDATARECOVERY/CDataRecoveryHandler::SetSaveDocumentInfoOnIdle", "AFXDATARECOVERY/CDataRecoveryHandler::SetShutdownByRestartManager", "AFXDATARECOVERY/CDataRecoveryHandler::UpdateDocumentInfo"] helpviewer_keywords: ["CDataRecoveryHandler [MFC], CDataRecoveryHandler", "CDataRecoveryHandler [MFC], AutosaveAllDocumentInfo", "CDataRecoveryHandler [MFC], AutosaveDocumentInfo", "CDataRecoveryHandler [MFC], CreateDocumentInfo", "CDataRecoveryHandler [MFC], DeleteAllAutosavedFiles", "CDataRecoveryHandler [MFC], DeleteAutosavedFile", "CDataRecoveryHandler [MFC], GenerateAutosaveFileName", "CDataRecoveryHandler [MFC], GetAutosaveInterval", "CDataRecoveryHandler [MFC], GetAutosavePath", "CDataRecoveryHandler [MFC], GetDocumentListName", "CDataRecoveryHandler [MFC], GetNormalDocumentTitle", "CDataRecoveryHandler [MFC], GetRecoveredDocumentTitle", "CDataRecoveryHandler [MFC], GetRestartIdentifier", "CDataRecoveryHandler [MFC], GetSaveDocumentInfoOnIdle", "CDataRecoveryHandler [MFC], GetShutdownByRestartManager", "CDataRecoveryHandler [MFC], Initialize", "CDataRecoveryHandler [MFC], QueryRestoreAutosavedDocuments", "CDataRecoveryHandler [MFC], ReadOpenDocumentList", "CDataRecoveryHandler [MFC], RemoveDocumentInfo", "CDataRecoveryHandler [MFC], ReopenPreviousDocuments", "CDataRecoveryHandler [MFC], RestoreAutosavedDocuments", "CDataRecoveryHandler [MFC], SaveOpenDocumentList", "CDataRecoveryHandler [MFC], SetAutosaveInterval", "CDataRecoveryHandler [MFC], SetAutosavePath", "CDataRecoveryHandler [MFC], SetRestartIdentifier", "CDataRecoveryHandler [MFC], SetSaveDocumentInfoOnIdle", "CDataRecoveryHandler [MFC], SetShutdownByRestartManager", "CDataRecoveryHandler [MFC], UpdateDocumentInfo"] -ms.assetid: 7794802c-e583-4eba-90b9-2fed1a161f9c --- # CDataRecoveryHandler Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CDataRecoveryHandler` autosaves documents and restores them if an application unexpectedly exits. ## Syntax diff --git a/docs/mfc/reference/cdatetimectrl-class.md b/docs/mfc/reference/cdatetimectrl-class.md index 095b88b9642..92549d32217 100644 --- a/docs/mfc/reference/cdatetimectrl-class.md +++ b/docs/mfc/reference/cdatetimectrl-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CDateTimeCtrl [MFC], CDateTimeCtrl", "CDateTimeCtrl [MFC] --- # `CDateTimeCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the functionality of a date and time picker control. ## Syntax diff --git a/docs/mfc/reference/cdbexception-class.md b/docs/mfc/reference/cdbexception-class.md index 741ced39720..0c142000f01 100644 --- a/docs/mfc/reference/cdbexception-class.md +++ b/docs/mfc/reference/cdbexception-class.md @@ -4,10 +4,12 @@ title: "CDBException Class" ms.date: "11/04/2016" f1_keywords: ["CDBException", "AFXDB/CDBException", "AFXDB/CDBException::m_nRetCode", "AFXDB/CDBException::m_strError", "AFXDB/CDBException::m_strStateNativeOrigin"] helpviewer_keywords: ["CDBException [MFC], m_nRetCode", "CDBException [MFC], m_strError", "CDBException [MFC], m_strStateNativeOrigin"] -ms.assetid: eb9e1119-89f5-49a7-b9d4-b91cee1ccc82 --- # CDBException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an exception condition arising from the database classes. ## Syntax diff --git a/docs/mfc/reference/cdbvariant-class.md b/docs/mfc/reference/cdbvariant-class.md index f752d848dae..585531dc9ab 100644 --- a/docs/mfc/reference/cdbvariant-class.md +++ b/docs/mfc/reference/cdbvariant-class.md @@ -4,10 +4,12 @@ title: "CDBVariant Class" ms.date: "11/04/2016" f1_keywords: ["CDBVariant", "AFXDB/CDBVariant", "AFXDB/CDBVariant::CDBVariant", "AFXDB/CDBVariant::Clear", "AFXDB/CDBVariant::m_dwType", "AFXDB/CDBVariant::m_boolVal", "AFXDB/CDBVariant::m_chVal", "AFXDB/CDBVariant::m_dblVal", "AFXDB/CDBVariant::m_fltVal", "AFXDB/CDBVariant::m_iVal", "AFXDB/CDBVariant::m_lVal", "AFXDB/CDBVariant::m_pbinary", "AFXDB/CDBVariant::m_pdate", "AFXDB/CDBVariant::m_pstring", "AFXDB/CDBVariant::m_pstringA", "AFXDB/CDBVariant::m_pstringW"] helpviewer_keywords: ["CDBVariant [MFC], CDBVariant", "CDBVariant [MFC], Clear", "CDBVariant [MFC], m_dwType", "CDBVariant [MFC], m_boolVal", "CDBVariant [MFC], m_chVal", "CDBVariant [MFC], m_dblVal", "CDBVariant [MFC], m_fltVal", "CDBVariant [MFC], m_iVal", "CDBVariant [MFC], m_lVal", "CDBVariant [MFC], m_pbinary", "CDBVariant [MFC], m_pdate", "CDBVariant [MFC], m_pstring", "CDBVariant [MFC], m_pstringA", "CDBVariant [MFC], m_pstringW"] -ms.assetid: de23609c-c560-4b24-bd6b-9d8903fd5b49 --- # CDBVariant Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a variant data type for the MFC ODBC classes. ## Syntax diff --git a/docs/mfc/reference/cdc-class.md b/docs/mfc/reference/cdc-class.md index 01cc0d83559..0ab4a2f4054 100644 --- a/docs/mfc/reference/cdc-class.md +++ b/docs/mfc/reference/cdc-class.md @@ -1,18 +1,20 @@ --- -description: "Learn more about: CDC Class" title: "CDC Class" -ms.date: "11/19/2018" +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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Defines a class of device-context objects. ## Syntax -``` +```cpp class CDC : public CObject ``` @@ -49,21 +51,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 +78,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 +159,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 +202,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 +241,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 +252,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 +305,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 +313,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 +333,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 +347,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 +359,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 +381,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 +434,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 +459,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 +484,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 +525,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 +554,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 @@ -591,9 +593,9 @@ Nonzero if the function is successful; otherwise 0. ### Remarks -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. +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 +607,7 @@ BOOL Attach(HDC hDC); ### Parameters -*`hDC`*
+*`hDC`*\ A Windows device context. ### Return Value @@ -656,28 +658,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 +692,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 +737,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 +778,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 +798,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 +812,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 +845,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 +881,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 +905,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 +917,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 +931,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 +959,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 +981,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 +1018,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 +1063,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 +1100,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 +1115,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 +1126,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 +1153,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 +1161,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 +1176,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 +1264,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 +1363,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 +1408,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 +1425,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 +1451,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 +1482,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 +1525,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 +1548,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 +1570,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 +1629,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 +1646,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 Visual Studio 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 +1683,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 +1741,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 +1761,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 +1802,7 @@ int ExcludeUpdateRgn(CWnd* pWnd); ### Parameters -*`pWnd`*
+*`pWnd`*\ Points to the window object whose window is being updated. ### Return Value @@ -1829,16 +1831,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 +1849,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 +1886,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 +1922,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 +1952,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 +1980,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 +2017,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 +2066,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 +2099,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 +2127,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 +2157,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 +2240,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 +2254,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 +2270,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 +2313,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 +2359,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 +2403,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 +2441,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 +2463,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 +2479,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 +2509,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 +2518,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 +2538,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 +2687,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 +2712,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 +2734,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 +2770,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 +2781,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 +2839,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 +2857,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 +2928,7 @@ COLORREF GetNearestColor(COLORREF crColor) const; ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the color to be matched. ### Return Value @@ -2947,13 +2951,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 +2966,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 +2981,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,9 +3000,9 @@ 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` +## `CDC::GetOutputTabbedTextExtent` Call this member function to compute the width and height of a character string using [`m_hDC`](#m_hdc), the output device context. @@ -3017,19 +3021,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 +3044,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 +3064,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 +3079,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 +3093,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 +3113,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 +3131,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 +3148,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 +3160,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 +3266,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 +3289,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 +3315,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 +3325,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 +3387,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 +3406,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 +3426,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 +3465,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 +3496,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 +3523,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 +3604,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 +3634,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 +3678,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 +3710,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 +3730,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 +3747,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 +3772,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 +3793,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 +3813,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 +3836,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 +3873,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 +3909,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 +3937,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 +3991,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 +4030,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 +4048,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 +4080,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 +4111,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 +4126,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 +4148,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 +4170,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 +4206,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 +4228,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 +4286,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 +4327,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 +4349,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 +4391,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 +4428,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 +4450,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 +4464,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 +4478,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 +4490,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 +4509,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 +4521,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 +4529,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 +4538,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 +4556,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 +4588,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 +4600,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 +4616,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 +4628,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 +4643,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 +4660,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 +4679,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 +4694,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 +4710,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 +4733,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 +4771,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 +4794,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 +4810,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 +4827,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 +4851,7 @@ BOOL ResetDC(const DEVMODE* lpDevMode); ### Parameters -*`lpDevMode`*
+*`lpDevMode`*\ A pointer to a Windows `DEVMODE` structure. ### Return Value @@ -4874,7 +4878,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 +4889,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 +4911,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 +4943,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 +4959,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 +4981,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 +5021,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 +5063,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 +5087,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 +5101,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 +5136,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 +5162,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 +5191,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 +5227,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 +5243,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 +5269,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 +5300,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 +5320,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 +5337,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 Visual Studio 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 +5349,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 +5361,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 +5392,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 +5409,7 @@ virtual COLORREF SetBkColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the new background color. ### Return Value @@ -5428,12 +5432,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 +5445,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 +5463,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 +5479,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 +5503,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 +5520,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 +5532,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 +5553,7 @@ COLORREF SetDCBrushColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the new brush color. ### Return Value @@ -5572,7 +5576,7 @@ COLORREF SetDCPenColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the new pen color. ### Return Value @@ -5593,7 +5597,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 +5620,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 +5637,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 +5655,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 +5682,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 +5701,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 +5712,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 +5726,7 @@ BOOL SetMiterLimit(float fMiterLimit); ### Parameters -*`fMiterLimit`*
+*`fMiterLimit`*\ Specifies the new miter limit for the device context. ### Return Value @@ -5743,12 +5747,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 +5771,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 +5810,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 +5828,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 +5840,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 +5863,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 +5908,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 +5920,7 @@ int SetStretchBltMode(int nStretchMode); ### Parameters -*`nStretchMode`*
+*`nStretchMode`*\ Specifies the stretching mode. It can be any of the following values: |Value|Description| @@ -5941,9 +5945,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 +5959,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 +5978,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 +6000,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 +6021,7 @@ virtual COLORREF SetTextColor(COLORREF crColor); ### Parameters -*`crColor`*
+*`crColor`*\ Specifies the color of the text as an RGB color value. ### Return Value @@ -6026,7 +6030,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 +6050,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 +6088,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 +6132,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 +6169,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 +6220,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 +6249,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 +6275,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 +6289,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 +6345,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 +6417,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 +6439,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 +6482,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 +6516,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 +6537,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 +6558,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 +6586,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 +6660,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/cdcrendertarget-class.md b/docs/mfc/reference/cdcrendertarget-class.md index 6a191229ba9..43ae0089a83 100644 --- a/docs/mfc/reference/cdcrendertarget-class.md +++ b/docs/mfc/reference/cdcrendertarget-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CDCRenderTarget [MFC], CDCRenderTarget", "CDCRenderTarget --- # `CDCRenderTarget` class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for [`ID2D1DCRenderTarget`](/windows/win32/api/d2d1/nn-d2d1-id2d1dcrendertarget). ## Syntax diff --git a/docs/mfc/reference/cdhtmldialog-class.md b/docs/mfc/reference/cdhtmldialog-class.md index 82562ba5ad2..afad32ba58d 100644 --- a/docs/mfc/reference/cdhtmldialog-class.md +++ b/docs/mfc/reference/cdhtmldialog-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CDHtmlDialog [MFC], CDHtmlDialog", "CDHtmlDialog [MFC], C --- # `CDHtmlDialog` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Is used to create dialog boxes that use HTML rather than dialog resources to implement their user interface. ## Syntax diff --git a/docs/mfc/reference/cdialog-class.md b/docs/mfc/reference/cdialog-class.md index 0f2eb95f528..dfd80214b40 100644 --- a/docs/mfc/reference/cdialog-class.md +++ b/docs/mfc/reference/cdialog-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class used for displaying dialog boxes on the screen. ## Syntax @@ -274,7 +276,7 @@ You can call `EndDialog` at any time, even in [OnInitDialog](#oninitdialog), in ### Example [!code-cpp[NVC_MFCControlLadenDialog#64](../../mfc/codesnippet/cpp/cdialog-class_3.cpp)] - +  [!code-cpp[NVC_MFCControlLadenDialog#65](../../mfc/codesnippet/cpp/cdialog-class_4.cpp)] ## CDialog::GetDefID @@ -287,7 +289,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/cdialogbar-class.md b/docs/mfc/reference/cdialogbar-class.md index 8d8c5acd272..1bd4ddb3413 100644 --- a/docs/mfc/reference/cdialogbar-class.md +++ b/docs/mfc/reference/cdialogbar-class.md @@ -4,10 +4,12 @@ title: "CDialogBar Class" ms.date: "11/04/2016" f1_keywords: ["CDialogBar", "AFXEXT/CDialogBar", "AFXEXT/CDialogBar::CDialogBar", "AFXEXT/CDialogBar::Create"] helpviewer_keywords: ["CDialogBar [MFC], CDialogBar", "CDialogBar [MFC], Create"] -ms.assetid: da2f7a30-970c-44e3-87f0-6094bd002cab --- # CDialogBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows modeless dialog box in a control bar. ## Syntax @@ -39,7 +41,7 @@ Creating and using a dialog bar is similar to creating and using a `CFormView` o For more information on `CDialogBar`, see the article [Dialog Bars](../../mfc/dialog-bars.md) and [Technical Note 31](../../mfc/tn031-control-bars.md), Control Bars. > [!NOTE] -> In the current release, a `CDialogBar` object cannot host Windows Forms controls. For more information about Windows Forms controls in Visual C++, see [Using a Windows Form User Control in MFC](../../dotnet/using-a-windows-form-user-control-in-mfc.md). +> In the current release, a `CDialogBar` object cannot host Windows Forms controls. For more information about Windows Forms controls in Visual Studio, see [Using a Windows Form User Control in MFC](../../dotnet/using-a-windows-form-user-control-in-mfc.md). ## Inheritance Hierarchy diff --git a/docs/mfc/reference/cdialogex-class.md b/docs/mfc/reference/cdialogex-class.md index f2b25ce85ee..06f3d5289ca 100644 --- a/docs/mfc/reference/cdialogex-class.md +++ b/docs/mfc/reference/cdialogex-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CDialogEx [MFC], CDialogEx", "CDialogEx [MFC], SetBackgro --- # `CDialogEx` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CDialogEx` class specifies the background color and background image of a dialog box. ## Syntax diff --git a/docs/mfc/reference/cdiscretetransition-class.md b/docs/mfc/reference/cdiscretetransition-class.md index 19fc03b66bb..252551cbaed 100644 --- a/docs/mfc/reference/cdiscretetransition-class.md +++ b/docs/mfc/reference/cdiscretetransition-class.md @@ -4,10 +4,12 @@ title: "CDiscreteTransition Class" ms.date: "11/04/2016" f1_keywords: ["CDiscreteTransition", "AFXANIMATIONCONTROLLER/CDiscreteTransition", "AFXANIMATIONCONTROLLER/CDiscreteTransition::CDiscreteTransition", "AFXANIMATIONCONTROLLER/CDiscreteTransition::Create", "AFXANIMATIONCONTROLLER/CDiscreteTransition::m_dblFinalValue", "AFXANIMATIONCONTROLLER/CDiscreteTransition::m_delay", "AFXANIMATIONCONTROLLER/CDiscreteTransition::m_hold"] helpviewer_keywords: ["CDiscreteTransition [MFC], CDiscreteTransition", "CDiscreteTransition [MFC], Create", "CDiscreteTransition [MFC], m_dblFinalValue", "CDiscreteTransition [MFC], m_delay", "CDiscreteTransition [MFC], m_hold"] -ms.assetid: b4d84fb3-ccaa-451c-a69b-6b50dcb9b9c8 --- # CDiscreteTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a discrete transition. ## Syntax diff --git a/docs/mfc/reference/cdocitem-class.md b/docs/mfc/reference/cdocitem-class.md index 7c8ae289b39..b0bb4ca4108 100644 --- a/docs/mfc/reference/cdocitem-class.md +++ b/docs/mfc/reference/cdocitem-class.md @@ -4,10 +4,12 @@ title: "CDocItem Class" ms.date: "11/04/2016" f1_keywords: ["CDocItem", "AFXOLE/CDocItem", "AFXOLE/CDocItem::GetDocument", "AFXOLE/CDocItem::IsBlank"] helpviewer_keywords: ["CDocItem [MFC], GetDocument", "CDocItem [MFC], IsBlank"] -ms.assetid: 84fb8610-a4c8-4211-adc0-e70e8d002c11 --- # CDocItem Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for document items, which are components of a document's data. ## Syntax diff --git a/docs/mfc/reference/cdockablepane-class.md b/docs/mfc/reference/cdockablepane-class.md index 832300d209d..a52ecfb1a54 100644 --- a/docs/mfc/reference/cdockablepane-class.md +++ b/docs/mfc/reference/cdockablepane-class.md @@ -1,12 +1,15 @@ --- -description: "Learn more about: CDockablePane Class" title: "CDockablePane Class" -ms.date: "07/02/2019" +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"] --- # `CDockablePane` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a pane that can either be docked in a dock site or included in a tabbed pane. ## Syntax @@ -207,7 +210,7 @@ virtual CDockablePane* AttachToTabWnd( ### Return Value -A pointer to the current pane, if it isn't a tabbed pane; otherwise a pointer to the tabbed pane that results from the attach operation. The return value is `NULL` if the current pane can’t be attached, or if an error occurs. +A pointer to the current pane, if it isn't a tabbed pane; otherwise a pointer to the tabbed pane that results from the attach operation. The return value is `NULL` if the current pane can't be attached, or if an error occurs. ### Remarks @@ -874,7 +877,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). @@ -1090,7 +1093,7 @@ virtual BOOL IsResizable() const; By default, dockable panes are resizable. To prevent resizing, override this method in a derived class and return `FALSE`. Note that a `FALSE` value leads to a failed **`ASSERT`** in [`CPane::DockPane`](../../mfc/reference/cpane-class.md#dockpane). Use [`CDockingManager::AddPane`](../../mfc/reference/cdockingmanager-class.md#addpane) instead to dock a pane within a parent frame. -Panes that can’t be resized can neither float nor enter auto-hide mode and are always located at the outer edge of the parent frame. +Panes that can't be resized can neither float nor enter auto-hide mode and are always located at the outer edge of the parent frame. ## `CDockablePane::IsTabLocationBottom` @@ -1142,7 +1145,7 @@ If the dockable pane is in autohide mode and `IsHideInAutoHideMode` returns `TRU If the dockable pane isn't in autohide mode, the visibility state is determined by the [`CBasePane::IsVisible`](../../mfc/reference/cbasepane-class.md#isvisible) method. -## ## `CDockablePane::LoadState` +## `CDockablePane::LoadState` For internal use only. For more detail, see the source code located in the `mfc` folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. @@ -1201,7 +1204,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 962eeab2d04..a9f0e5685b9 100644 --- a/docs/mfc/reference/cdockablepaneadapter-class.md +++ b/docs/mfc/reference/cdockablepaneadapter-class.md @@ -4,10 +4,12 @@ title: "CDockablePaneAdapter Class" ms.date: "11/04/2016" f1_keywords: ["CDockablePaneAdapter", "AFXDOCKABLEPANEADAPTER/CDockablePaneAdapter", "AFXDOCKABLEPANEADAPTER/CDockablePaneAdapter::GetWrappedWnd", "AFXDOCKABLEPANEADAPTER/CDockablePaneAdapter::LoadState", "AFXDOCKABLEPANEADAPTER/CDockablePaneAdapter::SaveState", "AFXDOCKABLEPANEADAPTER/CDockablePaneAdapter::SetWrappedWnd"] helpviewer_keywords: ["CDockablePaneAdapter [MFC], GetWrappedWnd", "CDockablePaneAdapter [MFC], LoadState", "CDockablePaneAdapter [MFC], SaveState", "CDockablePaneAdapter [MFC], SetWrappedWnd"] -ms.assetid: 6ed6cf82-f39c-4d0c-bf7c-8641495cf8f3 --- # CDockablePaneAdapter Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides docking support for `CWnd`-derived panes. ## Syntax @@ -37,11 +39,11 @@ If you want to customize the `CDockablePaneAdapter` behavior, just derive a new [CObject](../../mfc/reference/cobject-class.md)\ └ [CCmdTarget](../../mfc/reference/ccmdtarget-class.md)\ -    └ [CWnd](../../mfc/reference/cwnd-class.md)\ -        └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ -            └ [CPane](../../mfc/reference/cpane-class.md)\ -                └ [CDockablePane](../../mfc/reference/cdockablepane-class.md)\ -                    └ [CDockablePaneAdapter](../../mfc/reference/cdockablepaneadapter-class.md) + └ [CWnd](../../mfc/reference/cwnd-class.md)\ +  └ [CBasePane](../../mfc/reference/cbasepane-class.md)\ +   └ [CPane](../../mfc/reference/cpane-class.md)\ +    └ [CDockablePane](../../mfc/reference/cdockablepane-class.md)\ +     └ [CDockablePaneAdapter](../../mfc/reference/cdockablepaneadapter-class.md) ## Requirements diff --git a/docs/mfc/reference/cdockingmanager-class.md b/docs/mfc/reference/cdockingmanager-class.md index fb2b4cc0e04..972e77d344e 100644 --- a/docs/mfc/reference/cdockingmanager-class.md +++ b/docs/mfc/reference/cdockingmanager-class.md @@ -4,10 +4,12 @@ title: "CDockingManager Class" ms.date: "11/04/2016" f1_keywords: ["CDockingManager", "AFXDOCKINGMANAGER/CDockingManager", "AFXDOCKINGMANAGER/CDockingManager::AddDockSite", "AFXDOCKINGMANAGER/CDockingManager::AddHiddenMDITabbedBar", "AFXDOCKINGMANAGER/CDockingManager::AddMiniFrame", "AFXDOCKINGMANAGER/CDockingManager::AddPane", "AFXDOCKINGMANAGER/CDockingManager::AdjustDockingLayout", "AFXDOCKINGMANAGER/CDockingManager::AdjustPaneFrames", "AFXDOCKINGMANAGER/CDockingManager::AdjustRectToClientArea", "AFXDOCKINGMANAGER/CDockingManager::AlignAutoHidePane", "AFXDOCKINGMANAGER/CDockingManager::AutoHidePane", "AFXDOCKINGMANAGER/CDockingManager::BringBarsToTop", "AFXDOCKINGMANAGER/CDockingManager::BuildPanesMenu", "AFXDOCKINGMANAGER/CDockingManager::CalcExpectedDockedRect", "AFXDOCKINGMANAGER/CDockingManager::Create", "AFXDOCKINGMANAGER/CDockingManager::DeterminePaneAndStatus", "AFXDOCKINGMANAGER/CDockingManager::DisableRestoreDockState", "AFXDOCKINGMANAGER/CDockingManager::DockPane", "AFXDOCKINGMANAGER/CDockingManager::DockPaneLeftOf", "AFXDOCKINGMANAGER/CDockingManager::EnableAutoHidePanes", "AFXDOCKINGMANAGER/CDockingManager::EnableDocking", "AFXDOCKINGMANAGER/CDockingManager::EnableDockSiteMenu", "AFXDOCKINGMANAGER/CDockingManager::EnablePaneContextMenu", "AFXDOCKINGMANAGER/CDockingManager::FindDockSite", "AFXDOCKINGMANAGER/CDockingManager::FindDockSiteByPane", "AFXDOCKINGMANAGER/CDockingManager::FindPaneByID", "AFXDOCKINGMANAGER/CDockingManager::FixupVirtualRects", "AFXDOCKINGMANAGER/CDockingManager::FrameFromPoint", "AFXDOCKINGMANAGER/CDockingManager::GetClientAreaBounds", "AFXDOCKINGMANAGER/CDockingManager::GetDockingMode", "AFXDOCKINGMANAGER/CDockingManager::GetDockSiteFrameWnd", "AFXDOCKINGMANAGER/CDockingManager::GetEnabledAutoHideAlignment", "AFXDOCKINGMANAGER/CDockingManager::GetMiniFrames", "AFXDOCKINGMANAGER/CDockingManager::GetOuterEdgeBounds", "AFXDOCKINGMANAGER/CDockingManager::GetPaneList", "AFXDOCKINGMANAGER/CDockingManager::GetSmartDockingManager", "AFXDOCKINGMANAGER/CDockingManager::GetSmartDockingManagerPermanent", "AFXDOCKINGMANAGER/CDockingManager::GetSmartDockingParams", "AFXDOCKINGMANAGER/CDockingManager::GetSmartDockingTheme", "AFXDOCKINGMANAGER/CDockingManager::HideAutoHidePanes", "AFXDOCKINGMANAGER/CDockingManager::InsertDockSite", "AFXDOCKINGMANAGER/CDockingManager::InsertPane", "AFXDOCKINGMANAGER/CDockingManager::IsDockSiteMenu", "AFXDOCKINGMANAGER/CDockingManager::IsInAdjustLayout", "AFXDOCKINGMANAGER/CDockingManager::IsOLEContainerMode", "AFXDOCKINGMANAGER/CDockingManager::IsPointNearDockSite", "AFXDOCKINGMANAGER/CDockingManager::IsPrintPreviewValid", "AFXDOCKINGMANAGER/CDockingManager::LoadState", "AFXDOCKINGMANAGER/CDockingManager::LockUpdate", "AFXDOCKINGMANAGER/CDockingManager::OnActivateFrame", "AFXDOCKINGMANAGER/CDockingManager::OnClosePopupMenu", "AFXDOCKINGMANAGER/CDockingManager::OnMoveMiniFrame", "AFXDOCKINGMANAGER/CDockingManager::OnPaneContextMenu", "AFXDOCKINGMANAGER/CDockingManager::PaneFromPoint", "AFXDOCKINGMANAGER/CDockingManager::ProcessPaneContextMenuCommand", "AFXDOCKINGMANAGER/CDockingManager::RecalcLayout", "AFXDOCKINGMANAGER/CDockingManager::ReleaseEmptyPaneContainers", "AFXDOCKINGMANAGER/CDockingManager::RemoveHiddenMDITabbedBar", "AFXDOCKINGMANAGER/CDockingManager::RemoveMiniFrame", "AFXDOCKINGMANAGER/CDockingManager::RemovePaneFromDockManager", "AFXDOCKINGMANAGER/CDockingManager::ReplacePane", "AFXDOCKINGMANAGER/CDockingManager::ResortMiniFramesForZOrder", "AFXDOCKINGMANAGER/CDockingManager::SaveState", "AFXDOCKINGMANAGER/CDockingManager::SendMessageToMiniFrames", "AFXDOCKINGMANAGER/CDockingManager::Serialize", "AFXDOCKINGMANAGER/CDockingManager::SetAutohideZOrder", "AFXDOCKINGMANAGER/CDockingManager::SetDockingMode", "AFXDOCKINGMANAGER/CDockingManager::SetDockState", "AFXDOCKINGMANAGER/CDockingManager::SetPrintPreviewMode", "AFXDOCKINGMANAGER/CDockingManager::SetSmartDockingParams", "AFXDOCKINGMANAGER/CDockingManager::ShowDelayShowMiniFrames", "AFXDOCKINGMANAGER/CDockingManager::ShowPanes", "AFXDOCKINGMANAGER/CDockingManager::StartSDocking", "AFXDOCKINGMANAGER/CDockingManager::StopSDocking", "AFXDOCKINGMANAGER/CDockingManager::m_bHideDockingBarsInContainerMode", "AFXDOCKINGMANAGER/CDockingManager::m_dockModeGlobal", "AFXDOCKINGMANAGER/CDockingManager::m_nDockSensitivity", "AFXDOCKINGMANAGER/CDockingManager::m_nTimeOutBeforeDockingBarDock", "AFXDOCKINGMANAGER/CDockingManager::m_nTimeOutBeforeToolBarDock"] helpviewer_keywords: ["CDockingManager [MFC], AddDockSite", "CDockingManager [MFC], AddHiddenMDITabbedBar", "CDockingManager [MFC], AddMiniFrame", "CDockingManager [MFC], AddPane", "CDockingManager [MFC], AdjustDockingLayout", "CDockingManager [MFC], AdjustPaneFrames", "CDockingManager [MFC], AdjustRectToClientArea", "CDockingManager [MFC], AlignAutoHidePane", "CDockingManager [MFC], AutoHidePane", "CDockingManager [MFC], BringBarsToTop", "CDockingManager [MFC], BuildPanesMenu", "CDockingManager [MFC], CalcExpectedDockedRect", "CDockingManager [MFC], Create", "CDockingManager [MFC], DeterminePaneAndStatus", "CDockingManager [MFC], DisableRestoreDockState", "CDockingManager [MFC], DockPane", "CDockingManager [MFC], DockPaneLeftOf", "CDockingManager [MFC], EnableAutoHidePanes", "CDockingManager [MFC], EnableDocking", "CDockingManager [MFC], EnableDockSiteMenu", "CDockingManager [MFC], EnablePaneContextMenu", "CDockingManager [MFC], FindDockSite", "CDockingManager [MFC], FindDockSiteByPane", "CDockingManager [MFC], FindPaneByID", "CDockingManager [MFC], FixupVirtualRects", "CDockingManager [MFC], FrameFromPoint", "CDockingManager [MFC], GetClientAreaBounds", "CDockingManager [MFC], GetDockingMode", "CDockingManager [MFC], GetDockSiteFrameWnd", "CDockingManager [MFC], GetEnabledAutoHideAlignment", "CDockingManager [MFC], GetMiniFrames", "CDockingManager [MFC], GetOuterEdgeBounds", "CDockingManager [MFC], GetPaneList", "CDockingManager [MFC], GetSmartDockingManager", "CDockingManager [MFC], GetSmartDockingManagerPermanent", "CDockingManager [MFC], GetSmartDockingParams", "CDockingManager [MFC], GetSmartDockingTheme", "CDockingManager [MFC], HideAutoHidePanes", "CDockingManager [MFC], InsertDockSite", "CDockingManager [MFC], InsertPane", "CDockingManager [MFC], IsDockSiteMenu", "CDockingManager [MFC], IsInAdjustLayout", "CDockingManager [MFC], IsOLEContainerMode", "CDockingManager [MFC], IsPointNearDockSite", "CDockingManager [MFC], IsPrintPreviewValid", "CDockingManager [MFC], LoadState", "CDockingManager [MFC], LockUpdate", "CDockingManager [MFC], OnActivateFrame", "CDockingManager [MFC], OnClosePopupMenu", "CDockingManager [MFC], OnMoveMiniFrame", "CDockingManager [MFC], OnPaneContextMenu", "CDockingManager [MFC], PaneFromPoint", "CDockingManager [MFC], ProcessPaneContextMenuCommand", "CDockingManager [MFC], RecalcLayout", "CDockingManager [MFC], ReleaseEmptyPaneContainers", "CDockingManager [MFC], RemoveHiddenMDITabbedBar", "CDockingManager [MFC], RemoveMiniFrame", "CDockingManager [MFC], RemovePaneFromDockManager", "CDockingManager [MFC], ReplacePane", "CDockingManager [MFC], ResortMiniFramesForZOrder", "CDockingManager [MFC], SaveState", "CDockingManager [MFC], SendMessageToMiniFrames", "CDockingManager [MFC], Serialize", "CDockingManager [MFC], SetAutohideZOrder", "CDockingManager [MFC], SetDockingMode", "CDockingManager [MFC], SetDockState", "CDockingManager [MFC], SetPrintPreviewMode", "CDockingManager [MFC], SetSmartDockingParams", "CDockingManager [MFC], ShowDelayShowMiniFrames", "CDockingManager [MFC], ShowPanes", "CDockingManager [MFC], StartSDocking", "CDockingManager [MFC], StopSDocking", "CDockingManager [MFC], m_bHideDockingBarsInContainerMode", "CDockingManager [MFC], m_dockModeGlobal", "CDockingManager [MFC], m_nDockSensitivity", "CDockingManager [MFC], m_nTimeOutBeforeDockingBarDock", "CDockingManager [MFC], m_nTimeOutBeforeToolBarDock"] -ms.assetid: 98e69c43-55d8-4f43-b861-4fda80ec1e32 --- # CDockingManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the core functionality that controls docking layout in a main frame window. ## Syntax @@ -29,7 +31,7 @@ class CDockingManager : public CObject |[CDockingManager::AdjustDockingLayout](#adjustdockinglayout)|Recalculates and adjusts the layout of all panes in a frame window.| |[CDockingManager::AdjustPaneFrames](#adjustpaneframes)|Causes the WM_NCCALCSIZE message to be sent to all panes and `CPaneFrameWnd` windows.| |[CDockingManager::AdjustRectToClientArea](#adjustrecttoclientarea)|Adjusts the alignment of a rectangle.| -|[CDockingManager::AlignAutoHidePane](#alignautohidepane)|Resizes a docking pane in autohide mode so that it takes the full width or height of the frame’s client area surrounded by dock sites.| +|[CDockingManager::AlignAutoHidePane](#alignautohidepane)|Resizes a docking pane in autohide mode so that it takes the full width or height of the frame's client area surrounded by dock sites.| |[CDockingManager::AutoHidePane](#autohidepane)|Creates an autohide toolbar.| |[CDockingManager::BringBarsToTop](#bringbarstotop)|Brings the docked bars that have the specified alignment to the top.| |[CDockingManager::BuildPanesMenu](#buildpanesmenu)|Adds names of docking panes and toolbars to a menu.| @@ -292,7 +294,7 @@ The *dwAlignment* parameter can have one of the following values: ## CDockingManager::AlignAutoHidePane -Resizes a docking pane in autohide mode so that it takes the full width or height of the frame’s client area surrounded by dock sites. +Resizes a docking pane in autohide mode so that it takes the full width or height of the frame's client area surrounded by dock sites. ```cpp void AlignAutoHidePane( diff --git a/docs/mfc/reference/cdockingpanesrow-class.md b/docs/mfc/reference/cdockingpanesrow-class.md index ed86e50a70f..be4e8f4a307 100644 --- a/docs/mfc/reference/cdockingpanesrow-class.md +++ b/docs/mfc/reference/cdockingpanesrow-class.md @@ -4,10 +4,12 @@ title: "CDockingPanesRow Class" ms.date: "10/18/2018" f1_keywords: ["CDockingPanesRow", "AFXDOCKINGPANESROW/CDockingPanesRow", "AFXDOCKINGPANESROW/CDockingPanesRow::AddPane", "AFXDOCKINGPANESROW/CDockingPanesRow::AddPaneFromRow", "AFXDOCKINGPANESROW/CDockingPanesRow::ArrangePanes", "AFXDOCKINGPANESROW/CDockingPanesRow::CalcFixedLayout", "AFXDOCKINGPANESROW/CDockingPanesRow::Create", "AFXDOCKINGPANESROW/CDockingPanesRow::ExpandStretchedPanes", "AFXDOCKINGPANESROW/CDockingPanesRow::ExpandStretchedPanesRect", "AFXDOCKINGPANESROW/CDockingPanesRow::FixupVirtualRects", "AFXDOCKINGPANESROW/CDockingPanesRow::GetAvailableLength", "AFXDOCKINGPANESROW/CDockingPanesRow::GetAvailableSpace", "AFXDOCKINGPANESROW/CDockingPanesRow::GetClientRect", "AFXDOCKINGPANESROW/CDockingPanesRow::GetDockSite", "AFXDOCKINGPANESROW/CDockingPanesRow::GetExtraSpace", "AFXDOCKINGPANESROW/CDockingPanesRow::GetGroupFromPane", "AFXDOCKINGPANESROW/CDockingPanesRow::GetID", "AFXDOCKINGPANESROW/CDockingPanesRow::GetMaxPaneSize", "AFXDOCKINGPANESROW/CDockingPanesRow::GetPaneCount", "AFXDOCKINGPANESROW/CDockingPanesRow::GetPaneList", "AFXDOCKINGPANESROW/CDockingPanesRow::GetRowAlignment", "AFXDOCKINGPANESROW/CDockingPanesRow::GetRowHeight", "AFXDOCKINGPANESROW/CDockingPanesRow::GetRowOffset", "AFXDOCKINGPANESROW/CDockingPanesRow::GetVisibleCount", "AFXDOCKINGPANESROW/CDockingPanesRow::GetWindowRect", "AFXDOCKINGPANESROW/CDockingPanesRow::HasPane", "AFXDOCKINGPANESROW/CDockingPanesRow::IsEmpty", "AFXDOCKINGPANESROW/CDockingPanesRow::IsExclusiveRow", "AFXDOCKINGPANESROW/CDockingPanesRow::IsHorizontal", "AFXDOCKINGPANESROW/CDockingPanesRow::IsVisible", "AFXDOCKINGPANESROW/CDockingPanesRow::Move", "AFXDOCKINGPANESROW/CDockingPanesRow::MovePane", "AFXDOCKINGPANESROW/CDockingPanesRow::OnResizePane", "AFXDOCKINGPANESROW/CDockingPanesRow::RedrawAll", "AFXDOCKINGPANESROW/CDockingPanesRow::RemovePane", "AFXDOCKINGPANESROW/CDockingPanesRow::ReplacePane", "AFXDOCKINGPANESROW/CDockingPanesRow::RepositionPanes", "AFXDOCKINGPANESROW/CDockingPanesRow::Resize", "AFXDOCKINGPANESROW/CDockingPanesRow::ResizeByPaneDivider", "AFXDOCKINGPANESROW/CDockingPanesRow::ScreenToClient", "AFXDOCKINGPANESROW/CDockingPanesRow::SetExtra", "AFXDOCKINGPANESROW/CDockingPanesRow::ShowDockSiteRow", "AFXDOCKINGPANESROW/CDockingPanesRow::ShowPane", "AFXDOCKINGPANESROW/CDockingPanesRow::UpdateVisibleState"] helpviewer_keywords: ["CDockingPanesRow [MFC], AddPane", "CDockingPanesRow [MFC], AddPaneFromRow", "CDockingPanesRow [MFC], ArrangePanes", "CDockingPanesRow [MFC], CalcFixedLayout", "CDockingPanesRow [MFC], Create", "CDockingPanesRow [MFC], ExpandStretchedPanes", "CDockingPanesRow [MFC], ExpandStretchedPanesRect", "CDockingPanesRow [MFC], FixupVirtualRects", "CDockingPanesRow [MFC], GetAvailableLength", "CDockingPanesRow [MFC], GetAvailableSpace", "CDockingPanesRow [MFC], GetClientRect", "CDockingPanesRow [MFC], GetDockSite", "CDockingPanesRow [MFC], GetExtraSpace", "CDockingPanesRow [MFC], GetGroupFromPane", "CDockingPanesRow [MFC], GetID", "CDockingPanesRow [MFC], GetMaxPaneSize", "CDockingPanesRow [MFC], GetPaneCount", "CDockingPanesRow [MFC], GetPaneList", "CDockingPanesRow [MFC], GetRowAlignment", "CDockingPanesRow [MFC], GetRowHeight", "CDockingPanesRow [MFC], GetRowOffset", "CDockingPanesRow [MFC], GetVisibleCount", "CDockingPanesRow [MFC], GetWindowRect", "CDockingPanesRow [MFC], HasPane", "CDockingPanesRow [MFC], IsEmpty", "CDockingPanesRow [MFC], IsExclusiveRow", "CDockingPanesRow [MFC], IsHorizontal", "CDockingPanesRow [MFC], IsVisible", "CDockingPanesRow [MFC], Move", "CDockingPanesRow [MFC], MovePane", "CDockingPanesRow [MFC], OnResizePane", "CDockingPanesRow [MFC], RedrawAll", "CDockingPanesRow [MFC], RemovePane", "CDockingPanesRow [MFC], ReplacePane", "CDockingPanesRow [MFC], RepositionPanes", "CDockingPanesRow [MFC], Resize", "CDockingPanesRow [MFC], ResizeByPaneDivider", "CDockingPanesRow [MFC], ScreenToClient", "CDockingPanesRow [MFC], SetExtra", "CDockingPanesRow [MFC], ShowDockSiteRow", "CDockingPanesRow [MFC], ShowPane", "CDockingPanesRow [MFC], UpdateVisibleState"] -ms.assetid: e7a17832-0ebb-4bce-b799-cec9b60f76fe --- # CDockingPanesRow Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages a list of panes that are located in the same horizontal or vertical row (column) of a dock site. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cdocksite-class.md b/docs/mfc/reference/cdocksite-class.md index 49d36e675c8..810d4522d7b 100644 --- a/docs/mfc/reference/cdocksite-class.md +++ b/docs/mfc/reference/cdocksite-class.md @@ -4,10 +4,12 @@ title: "CDockSite Class" ms.date: "10/18/2018" f1_keywords: ["CDockSite", "AFXDOCKSITE/CDockSite", "AFXDOCKSITE/CDockSite::AddRow", "AFXDOCKSITE/CDockSite::AdjustDockingLayout", "AFXDOCKSITE/CDockSite::AdjustLayout", "AFXDOCKSITE/CDockSite::AlignDockSite", "AFXDOCKSITE/CDockSite::CalcFixedLayout", "AFXDOCKSITE/CDockSite::CanAcceptPane", "AFXDOCKSITE/CDockSite::CreateEx", "AFXDOCKSITE/CDockSite::CreateRow", "AFXDOCKSITE/CDockSite::DockPane", "AFXDOCKSITE/CDockSite::DoesAllowDynInsertBefore", "AFXDOCKSITE/CDockSite::FindRowIndex", "AFXDOCKSITE/CDockSite::FixupVirtualRects", "AFXDOCKSITE/CDockSite::GetDockSiteID", "AFXDOCKSITE/CDockSite::GetDockSiteRowsList", "AFXDOCKSITE/CDockSite::IsAccessibilityCompatible", "AFXDOCKSITE/CDockSite::IsDragMode", "AFXDOCKSITE/CDockSite::IsLastRow", "AFXDOCKSITE/CDockSite::IsRectWithinDockSite", "AFXDOCKSITE/CDockSite::IsResizable", "AFXDOCKSITE/CDockSite::MovePane", "AFXDOCKSITE/CDockSite::OnInsertRow", "AFXDOCKSITE/CDockSite::OnRemoveRow", "AFXDOCKSITE/CDockSite::OnResizeRow", "AFXDOCKSITE/CDockSite::OnSetWindowPos", "AFXDOCKSITE/CDockSite::OnShowRow", "AFXDOCKSITE/CDockSite::OnSizeParent", "AFXDOCKSITE/CDockSite::PaneFromPoint", "AFXDOCKSITE/CDockSite::DockPaneLeftOf", "AFXDOCKSITE/CDockSite::FindPaneByID", "AFXDOCKSITE/CDockSite::GetPaneList", "AFXDOCKSITE/CDockSite::RectSideFromPoint", "AFXDOCKSITE/CDockSite::RemovePane", "AFXDOCKSITE/CDockSite::RemoveRow", "AFXDOCKSITE/CDockSite::ReplacePane", "AFXDOCKSITE/CDockSite::RepositionPanes", "AFXDOCKSITE/CDockSite::ResizeDockSite", "AFXDOCKSITE/CDockSite::ResizeRow", "AFXDOCKSITE/CDockSite::ShowPane", "AFXDOCKSITE/CDockSite::ShowRow", "AFXDOCKSITE/CDockSite::SwapRows"] helpviewer_keywords: ["CDockSite [MFC], AddRow", "CDockSite [MFC], AdjustDockingLayout", "CDockSite [MFC], AdjustLayout", "CDockSite [MFC], AlignDockSite", "CDockSite [MFC], CalcFixedLayout", "CDockSite [MFC], CanAcceptPane", "CDockSite [MFC], CreateEx", "CDockSite [MFC], CreateRow", "CDockSite [MFC], DockPane", "CDockSite [MFC], DoesAllowDynInsertBefore", "CDockSite [MFC], FindRowIndex", "CDockSite [MFC], FixupVirtualRects", "CDockSite [MFC], GetDockSiteID", "CDockSite [MFC], GetDockSiteRowsList", "CDockSite [MFC], IsAccessibilityCompatible", "CDockSite [MFC], IsDragMode", "CDockSite [MFC], IsLastRow", "CDockSite [MFC], IsRectWithinDockSite", "CDockSite [MFC], IsResizable", "CDockSite [MFC], MovePane", "CDockSite [MFC], OnInsertRow", "CDockSite [MFC], OnRemoveRow", "CDockSite [MFC], OnResizeRow", "CDockSite [MFC], OnSetWindowPos", "CDockSite [MFC], OnShowRow", "CDockSite [MFC], OnSizeParent", "CDockSite [MFC], PaneFromPoint", "CDockSite [MFC], DockPaneLeftOf", "CDockSite [MFC], FindPaneByID", "CDockSite [MFC], GetPaneList", "CDockSite [MFC], RectSideFromPoint", "CDockSite [MFC], RemovePane", "CDockSite [MFC], RemoveRow", "CDockSite [MFC], ReplacePane", "CDockSite [MFC], RepositionPanes", "CDockSite [MFC], ResizeDockSite", "CDockSite [MFC], ResizeRow", "CDockSite [MFC], ShowPane", "CDockSite [MFC], ShowRow", "CDockSite [MFC], SwapRows"] -ms.assetid: 0fcfff79-5f50-4281-b2de-a55653bbea40 --- # CDockSite Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. Provides functionality for arranging panes that are derived from the [CPane Class](../../mfc/reference/cpane-class.md) into sets of rows. @@ -81,9 +83,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 93d04a208a1..2cf9a40a24d 100644 --- a/docs/mfc/reference/cdockstate-class.md +++ b/docs/mfc/reference/cdockstate-class.md @@ -4,10 +4,12 @@ title: "CDockState Class" ms.date: "11/04/2016" f1_keywords: ["CDockState", "AFXADV/CDockState", "AFXADV/CDockState::Clear", "AFXADV/CDockState::GetVersion", "AFXADV/CDockState::LoadState", "AFXADV/CDockState::SaveState", "AFXADV/CDockState::m_arrBarInfo"] helpviewer_keywords: ["CDockState [MFC], Clear", "CDockState [MFC], GetVersion", "CDockState [MFC], LoadState", "CDockState [MFC], SaveState", "CDockState [MFC], m_arrBarInfo"] -ms.assetid: 09e7c10b-3abd-4cb2-ad36-42420fe6bc36 --- # CDockState Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A serialized `CObject` class that loads, unloads, or clears the state of one or more docking control bars in persistent memory (a file). ## Syntax @@ -92,7 +94,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 70f2fed0871..706cee08863 100644 --- a/docs/mfc/reference/cdocobjectserver-class.md +++ b/docs/mfc/reference/cdocobjectserver-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the additional OLE interfaces needed to make a normal `COleDocument` server into a full DocObject server: `IOleDocument`, `IOleDocumentView`, `IOleCommandTarget`, and `IPrint`. ## Syntax @@ -94,7 +96,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/cdocobjectserveritem-class.md b/docs/mfc/reference/cdocobjectserveritem-class.md index 04f07c5cba0..373797418d1 100644 --- a/docs/mfc/reference/cdocobjectserveritem-class.md +++ b/docs/mfc/reference/cdocobjectserveritem-class.md @@ -4,10 +4,12 @@ title: "CDocObjectServerItem Class" ms.date: "03/27/2019" f1_keywords: ["CDocObjectServerItem", "AFXDOCOB/CDocObjectServerItem", "AFXDOCOB/CDocObjectServerItem::CDocObjectServerItem", "AFXDOCOB/CDocObjectServerItem::GetDocument", "AFXDOCOB/CDocObjectServerItem::OnDoVerb", "AFXDOCOB/CDocObjectServerItem::OnHide", "AFXDOCOB/CDocObjectServerItem::OnShow"] helpviewer_keywords: ["CDocObjectServerItem [MFC], CDocObjectServerItem", "CDocObjectServerItem [MFC], GetDocument", "CDocObjectServerItem [MFC], OnDoVerb", "CDocObjectServerItem [MFC], OnHide", "CDocObjectServerItem [MFC], OnShow"] -ms.assetid: 530f7156-50c8-4806-9328-602c9133f622 --- # CDocObjectServerItem Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements OLE server verbs specifically for DocObject servers. ## Syntax diff --git a/docs/mfc/reference/cdoctemplate-class.md b/docs/mfc/reference/cdoctemplate-class.md index 455c0dabdaa..37cdf1a2d6d 100644 --- a/docs/mfc/reference/cdoctemplate-class.md +++ b/docs/mfc/reference/cdoctemplate-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CDocTemplate [MFC], CDocTemplate", "CDocTemplate [MFC], A --- # `CDocTemplate` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An abstract base class that defines the basic functionality for document templates. ## Syntax @@ -65,7 +68,7 @@ The document template contains the ID of the resources used with the document ty If your application is an OLE container and/or server, the document template also defines the ID of the menu used during in-place activation. If your application is an OLE server, the document template defines the ID of the toolbar and menu used during in-place activation. You specify these additional OLE resources by calling `SetContainerInfo` and `SetServerInfo`. -Because `CDocTemplate` is an abstract class, you can’t use the class directly. A typical application uses one of the two `CDocTemplate`-derived classes provided by the Microsoft Foundation Class Library: `CSingleDocTemplate`, which implements SDI, and `CMultiDocTemplate`, which implements MDI. See those classes for more information on using document templates. +Because `CDocTemplate` is an abstract class, you can't use the class directly. A typical application uses one of the two `CDocTemplate`-derived classes provided by the Microsoft Foundation Class Library: `CSingleDocTemplate`, which implements SDI, and `CMultiDocTemplate`, which implements MDI. See those classes for more information on using document templates. If your application requires a user-interface paradigm that is fundamentally different from SDI or MDI, you can derive your own class from `CDocTemplate`. @@ -259,7 +262,7 @@ An index of the substring being retrieved from the string that describes the doc - `CDocTemplate::filterExt` Extension for documents of this type (for example, ".xls"). If not specified, the document type is inaccessible using the **File Open** command. -- `CDocTemplate::regFileTypeId` Identifier for the document type to be stored in the registration database maintained by Windows. This string is for internal use only (for example, "ExcelWorksheet"). If not specified, the document type can’t be registered with the Windows File Manager. +- `CDocTemplate::regFileTypeId` Identifier for the document type to be stored in the registration database maintained by Windows. This string is for internal use only (for example, "ExcelWorksheet"). If not specified, the document type can't be registered with the Windows File Manager. - `CDocTemplate::regFileTypeName` Name of the document type to be stored in the registration database. This string may be displayed in dialog boxes of applications that access the registration database (for example, "Microsoft Excel Worksheet"). diff --git a/docs/mfc/reference/cdocument-class.md b/docs/mfc/reference/cdocument-class.md index 5ab35556df6..8fe635eee58 100644 --- a/docs/mfc/reference/cdocument-class.md +++ b/docs/mfc/reference/cdocument-class.md @@ -4,10 +4,12 @@ title: "CDocument Class" ms.date: "11/04/2016" f1_keywords: ["CDocument", "AFXWIN/CDocument", "AFXWIN/CDocument::CDocument", "AFXWIN/CDocument::AddView", "AFXWIN/CDocument::BeginReadChunks", "AFXWIN/CDocument::CanCloseFrame", "AFXWIN/CDocument::ClearChunkList", "AFXWIN/CDocument::ClearPathName", "AFXWIN/CDocument::DeleteContents", "AFXWIN/CDocument::FindChunk", "AFXWIN/CDocument::GetAdapter", "AFXWIN/CDocument::GetDocTemplate", "AFXWIN/CDocument::GetFile", "AFXWIN/CDocument::GetFirstViewPosition", "AFXWIN/CDocument::GetNextView", "AFXWIN/CDocument::GetPathName", "AFXWIN/CDocument::GetThumbnail", "AFXWIN/CDocument::GetTitle", "AFXWIN/CDocument::InitializeSearchContent", "AFXWIN/CDocument::IsModified", "AFXWIN/CDocument::IsSearchAndOrganizeHandler", "AFXWIN/CDocument::LoadDocumentFromStream", "AFXWIN/CDocument::OnBeforeRichPreviewFontChanged", "AFXWIN/CDocument::OnChangedViewList", "AFXWIN/CDocument::OnCloseDocument", "AFXWIN/CDocument::OnCreatePreviewFrame", "AFXWIN/CDocument::OnDocumentEvent", "AFXWIN/CDocument::OnDrawThumbnail", "AFXWIN/CDocument::OnLoadDocumentFromStream", "AFXWIN/CDocument::OnNewDocument", "AFXWIN/CDocument::OnOpenDocument", "AFXWIN/CDocument::OnPreviewHandlerQueryFocus", "AFXWIN/CDocument::OnPreviewHandlerTranslateAccelerator", "AFXWIN/CDocument::OnRichPreviewBackColorChanged", "AFXWIN/CDocument::OnRichPreviewFontChanged", "AFXWIN/CDocument::OnRichPreviewSiteChanged", "AFXWIN/CDocument::OnRichPreviewTextColorChanged", "AFXWIN/CDocument::OnSaveDocument", "AFXWIN/CDocument::OnUnloadHandler", "AFXWIN/CDocument::PreCloseFrame", "AFXWIN/CDocument::ReadNextChunkValue", "AFXWIN/CDocument::ReleaseFile", "AFXWIN/CDocument::RemoveChunk", "AFXWIN/CDocument::RemoveView", "AFXWIN/CDocument::ReportSaveLoadException", "AFXWIN/CDocument::SaveModified", "AFXWIN/CDocument::SetChunkValue", "AFXWIN/CDocument::SetModifiedFlag", "AFXWIN/CDocument::SetPathName", "AFXWIN/CDocument::SetTitle", "AFXWIN/CDocument::UpdateAllViews", "AFXWIN/CDocument::OnFileSendMail", "AFXWIN/CDocument::OnUpdateFileSendMail", "AFXWIN/CDocument::m_bGetThumbnailMode", "AFXWIN/CDocument::m_bPreviewHandlerMode", "AFXWIN/CDocument::m_bSearchMode", "AFXWIN/CDocument::m_clrRichPreviewBackColor", "AFXWIN/CDocument::m_clrRichPreviewTextColor", "AFXWIN/CDocument::m_lfRichPreviewFont"] helpviewer_keywords: ["CDocument [MFC], CDocument", "CDocument [MFC], AddView", "CDocument [MFC], BeginReadChunks", "CDocument [MFC], CanCloseFrame", "CDocument [MFC], ClearChunkList", "CDocument [MFC], ClearPathName", "CDocument [MFC], DeleteContents", "CDocument [MFC], FindChunk", "CDocument [MFC], GetAdapter", "CDocument [MFC], GetDocTemplate", "CDocument [MFC], GetFile", "CDocument [MFC], GetFirstViewPosition", "CDocument [MFC], GetNextView", "CDocument [MFC], GetPathName", "CDocument [MFC], GetThumbnail", "CDocument [MFC], GetTitle", "CDocument [MFC], InitializeSearchContent", "CDocument [MFC], IsModified", "CDocument [MFC], IsSearchAndOrganizeHandler", "CDocument [MFC], LoadDocumentFromStream", "CDocument [MFC], OnBeforeRichPreviewFontChanged", "CDocument [MFC], OnChangedViewList", "CDocument [MFC], OnCloseDocument", "CDocument [MFC], OnCreatePreviewFrame", "CDocument [MFC], OnDocumentEvent", "CDocument [MFC], OnDrawThumbnail", "CDocument [MFC], OnLoadDocumentFromStream", "CDocument [MFC], OnNewDocument", "CDocument [MFC], OnOpenDocument", "CDocument [MFC], OnPreviewHandlerQueryFocus", "CDocument [MFC], OnPreviewHandlerTranslateAccelerator", "CDocument [MFC], OnRichPreviewBackColorChanged", "CDocument [MFC], OnRichPreviewFontChanged", "CDocument [MFC], OnRichPreviewSiteChanged", "CDocument [MFC], OnRichPreviewTextColorChanged", "CDocument [MFC], OnSaveDocument", "CDocument [MFC], OnUnloadHandler", "CDocument [MFC], PreCloseFrame", "CDocument [MFC], ReadNextChunkValue", "CDocument [MFC], ReleaseFile", "CDocument [MFC], RemoveChunk", "CDocument [MFC], RemoveView", "CDocument [MFC], ReportSaveLoadException", "CDocument [MFC], SaveModified", "CDocument [MFC], SetChunkValue", "CDocument [MFC], SetModifiedFlag", "CDocument [MFC], SetPathName", "CDocument [MFC], SetTitle", "CDocument [MFC], UpdateAllViews", "CDocument [MFC], OnFileSendMail", "CDocument [MFC], OnUpdateFileSendMail", "CDocument [MFC], m_bGetThumbnailMode", "CDocument [MFC], m_bPreviewHandlerMode", "CDocument [MFC], m_bSearchMode", "CDocument [MFC], m_clrRichPreviewBackColor", "CDocument [MFC], m_clrRichPreviewTextColor", "CDocument [MFC], m_lfRichPreviewFont"] -ms.assetid: e5a2891d-e1e1-4599-8c7e-afa9b4945446 --- # `CDocument` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the basic functionality for user-defined document classes. ## Syntax @@ -705,9 +707,9 @@ Note that there are cases where `OnNewDocument` is called twice. This occurs whe The following examples illustrate alternative methods of initializing a document object. [!code-cpp[NVC_MFCDocView#60](../../mfc/codesnippet/cpp/cdocument-class_5.cpp)] - +  [!code-cpp[NVC_MFCDocView#61](../../mfc/codesnippet/cpp/cdocument-class_6.cpp)] - +  [!code-cpp[NVC_MFCDocView#62](../../mfc/codesnippet/cpp/cdocument-class_7.cpp)] ## `CDocument::OnOpenDocument` @@ -738,11 +740,11 @@ If the user chooses the File Open command in an SDI application, the framework u The following examples illustrate alternative methods of initializing a document object. [!code-cpp[NVC_MFCDocView#60](../../mfc/codesnippet/cpp/cdocument-class_5.cpp)] - +  [!code-cpp[NVC_MFCDocView#61](../../mfc/codesnippet/cpp/cdocument-class_6.cpp)] - +  [!code-cpp[NVC_MFCDocView#62](../../mfc/codesnippet/cpp/cdocument-class_7.cpp)] - +  [!code-cpp[NVC_MFCDocView#63](../../mfc/codesnippet/cpp/cdocument-class_8.cpp)] ## `CDocument::OnPreviewHandlerQueryFocus` diff --git a/docs/mfc/reference/cdraglistbox-class.md b/docs/mfc/reference/cdraglistbox-class.md index 3f606afec5c..0a6c49b750a 100644 --- a/docs/mfc/reference/cdraglistbox-class.md +++ b/docs/mfc/reference/cdraglistbox-class.md @@ -4,10 +4,12 @@ title: "CDragListBox Class" ms.date: "11/04/2016" f1_keywords: ["CDragListBox", "AFXCMN/CDragListBox", "AFXCMN/CDragListBox::CDragListBox", "AFXCMN/CDragListBox::BeginDrag", "AFXCMN/CDragListBox::CancelDrag", "AFXCMN/CDragListBox::Dragging", "AFXCMN/CDragListBox::DrawInsert", "AFXCMN/CDragListBox::Dropped", "AFXCMN/CDragListBox::ItemFromPt"] helpviewer_keywords: ["CDragListBox [MFC], CDragListBox", "CDragListBox [MFC], BeginDrag", "CDragListBox [MFC], CancelDrag", "CDragListBox [MFC], Dragging", "CDragListBox [MFC], DrawInsert", "CDragListBox [MFC], Dropped", "CDragListBox [MFC], ItemFromPt"] -ms.assetid: fee20b42-60ae-4aa9-83f9-5a3d9b96e33b --- # CDragListBox Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In addition to providing the functionality of a Windows list box, the `CDragListBox` class allows the user to move list box items, such as filenames, within the list box. ## Syntax diff --git a/docs/mfc/reference/cdrawingmanager-class.md b/docs/mfc/reference/cdrawingmanager-class.md index 0ac81cd52f4..0b13d57074e 100644 --- a/docs/mfc/reference/cdrawingmanager-class.md +++ b/docs/mfc/reference/cdrawingmanager-class.md @@ -4,10 +4,12 @@ title: "CDrawingManager Class" ms.date: "11/04/2016" f1_keywords: ["CDrawingManager", "AFXDRAWMANAGER/CDrawingManager", "AFXDRAWMANAGER/CDrawingManager::CDrawingManager", "AFXDRAWMANAGER/CDrawingManager::CreateBitmap_32", "AFXDRAWMANAGER/CDrawingManager::DrawAlpha", "AFXDRAWMANAGER/CDrawingManager::DrawRotated", "AFXDRAWMANAGER/CDrawingManager::DrawEllipse", "AFXDRAWMANAGER/CDrawingManager::DrawGradientRing", "AFXDRAWMANAGER/CDrawingManager::DrawRect", "AFXDRAWMANAGER/CDrawingManager::DrawShadow", "AFXDRAWMANAGER/CDrawingManager::Fill4ColorsGradient", "AFXDRAWMANAGER/CDrawingManager::FillGradient", "AFXDRAWMANAGER/CDrawingManager::FillGradient2", "AFXDRAWMANAGER/CDrawingManager::GrayRect", "AFXDRAWMANAGER/CDrawingManager::HighlightRect", "AFXDRAWMANAGER/CDrawingManager::HLStoRGB_ONE", "AFXDRAWMANAGER/CDrawingManager::HLStoRGB_TWO", "AFXDRAWMANAGER/CDrawingManager::HSVtoRGB", "AFXDRAWMANAGER/CDrawingManager::HuetoRGB", "AFXDRAWMANAGER/CDrawingManager::MirrorRect", "AFXDRAWMANAGER/CDrawingManager::PixelAlpha", "AFXDRAWMANAGER/CDrawingManager::PrepareShadowMask", "AFXDRAWMANAGER/CDrawingManager::RGBtoHSL", "AFXDRAWMANAGER/CDrawingManager::RGBtoHSV", "AFXDRAWMANAGER/CDrawingManager::SetAlphaPixel", "AFXDRAWMANAGER/CDrawingManager::SetPixel", "AFXDRAWMANAGER/CDrawingManager::SmartMixColors"] helpviewer_keywords: ["CDrawingManager [MFC], CDrawingManager", "CDrawingManager [MFC], CreateBitmap_32", "CDrawingManager [MFC], DrawAlpha", "CDrawingManager [MFC], DrawRotated", "CDrawingManager [MFC], DrawEllipse", "CDrawingManager [MFC], DrawGradientRing", "CDrawingManager [MFC], DrawRect", "CDrawingManager [MFC], DrawShadow", "CDrawingManager [MFC], Fill4ColorsGradient", "CDrawingManager [MFC], FillGradient", "CDrawingManager [MFC], FillGradient2", "CDrawingManager [MFC], GrayRect", "CDrawingManager [MFC], HighlightRect", "CDrawingManager [MFC], HLStoRGB_ONE", "CDrawingManager [MFC], HLStoRGB_TWO", "CDrawingManager [MFC], HSVtoRGB", "CDrawingManager [MFC], HuetoRGB", "CDrawingManager [MFC], MirrorRect", "CDrawingManager [MFC], PixelAlpha", "CDrawingManager [MFC], PrepareShadowMask", "CDrawingManager [MFC], RGBtoHSL", "CDrawingManager [MFC], RGBtoHSV", "CDrawingManager [MFC], SetAlphaPixel", "CDrawingManager [MFC], SetPixel", "CDrawingManager [MFC], SmartMixColors"] -ms.assetid: 9e4775ca-101b-4aa9-a85a-4d047c701215 --- # CDrawingManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CDrawingManager` class implements complex drawing algorithms. ## Syntax diff --git a/docs/mfc/reference/cdumpcontext-class.md b/docs/mfc/reference/cdumpcontext-class.md index 62761573c65..7ea003f58f8 100644 --- a/docs/mfc/reference/cdumpcontext-class.md +++ b/docs/mfc/reference/cdumpcontext-class.md @@ -4,10 +4,12 @@ title: "CDumpContext Class" ms.date: "11/04/2016" f1_keywords: ["CDumpContext", "AFX/CDumpContext", "AFX/CDumpContext::CDumpContext", "AFX/CDumpContext::DumpAsHex", "AFX/CDumpContext::Flush", "AFX/CDumpContext::GetDepth", "AFX/CDumpContext::HexDump", "AFX/CDumpContext::SetDepth"] helpviewer_keywords: ["CDumpContext [MFC], CDumpContext", "CDumpContext [MFC], DumpAsHex", "CDumpContext [MFC], Flush", "CDumpContext [MFC], GetDepth", "CDumpContext [MFC], HexDump", "CDumpContext [MFC], SetDepth"] -ms.assetid: 98c52b2d-14b5-48ed-b423-479a4d1c60fa --- # CDumpContext Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports stream-oriented diagnostic output in the form of human-readable text. ## Syntax diff --git a/docs/mfc/reference/cdwordarray-class.md b/docs/mfc/reference/cdwordarray-class.md index 6e9d5f38710..25eaea47f31 100644 --- a/docs/mfc/reference/cdwordarray-class.md +++ b/docs/mfc/reference/cdwordarray-class.md @@ -4,10 +4,12 @@ title: "CDWordArray Class" ms.date: "11/04/2016" f1_keywords: ["CDWordArray", "AFXCOLL/CDWordArray", "AFXCOLL/CDWordArray::CDWordArray", "AFXCOLL/CDWordArray::Add", "AFXCOLL/CDWordArray::Append", "AFXCOLL/CDWordArray::Copy", "AFXCOLL/CDWordArray::ElementAt", "AFXCOLL/CDWordArray::FreeExtra", "AFXCOLL/CDWordArray::GetAt", "AFXCOLL/CDWordArray::GetCount", "AFXCOLL/CDWordArray::GetData", "AFXCOLL/CDWordArray::GetSize", "AFXCOLL/CDWordArray::GetUpperBound", "AFXCOLL/CDWordArray::InsertAt", "AFXCOLL/CDWordArray::IsEmpty", "AFXCOLL/CDWordArray::RemoveAll", "AFXCOLL/CDWordArray::RemoveAt", "AFXCOLL/CDWordArray::SetAt", "AFXCOLL/CDWordArray::SetAtGrow", "AFXCOLL/CDWordArray::SetSize"] helpviewer_keywords: ["CDWordArray [MFC], CDWordArray", "CDWordArray [MFC], Add", "CDWordArray [MFC], Append", "CDWordArray [MFC], Copy", "CDWordArray [MFC], ElementAt", "CDWordArray [MFC], FreeExtra", "CDWordArray [MFC], GetAt", "CDWordArray [MFC], GetCount", "CDWordArray [MFC], GetData", "CDWordArray [MFC], GetSize", "CDWordArray [MFC], GetUpperBound", "CDWordArray [MFC], InsertAt", "CDWordArray [MFC], IsEmpty", "CDWordArray [MFC], RemoveAll", "CDWordArray [MFC], RemoveAt", "CDWordArray [MFC], SetAt", "CDWordArray [MFC], SetAtGrow", "CDWordArray [MFC], SetSize"] -ms.assetid: 581be11e-ced6-47d1-8679-e0b8e7d99494 --- # CDWordArray Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports arrays of 32-bit doublewords. ## Syntax diff --git a/docs/mfc/reference/cedit-class.md b/docs/mfc/reference/cedit-class.md index 3843aec8703..1bbce9a88f9 100644 --- a/docs/mfc/reference/cedit-class.md +++ b/docs/mfc/reference/cedit-class.md @@ -4,10 +4,12 @@ title: "CEdit Class" ms.date: "09/12/2018" f1_keywords: ["CEdit", "AFXWIN/CEdit", "AFXWIN/CEdit::CEdit", "AFXWIN/CEdit::CanUndo", "AFXWIN/CEdit::CharFromPos", "AFXWIN/CEdit::Clear", "AFXWIN/CEdit::Copy", "AFXWIN/CEdit::Create", "AFXWIN/CEdit::Cut", "AFXWIN/CEdit::EmptyUndoBuffer", "AFXWIN/CEdit::FmtLines", "AFXWIN/CEdit::GetCueBanner", "AFXWIN/CEdit::GetFirstVisibleLine", "AFXWIN/CEdit::GetHandle", "AFXWIN/CEdit::GetHighlight", "AFXWIN/CEdit::GetLimitText", "AFXWIN/CEdit::GetLine", "AFXWIN/CEdit::GetLineCount", "AFXWIN/CEdit::GetMargins", "AFXWIN/CEdit::GetModify", "AFXWIN/CEdit::GetPasswordChar", "AFXWIN/CEdit::GetRect", "AFXWIN/CEdit::GetSel", "AFXWIN/CEdit::HideBalloonTip", "AFXWIN/CEdit::LimitText", "AFXWIN/CEdit::LineFromChar", "AFXWIN/CEdit::LineIndex", "AFXWIN/CEdit::LineLength", "AFXWIN/CEdit::LineScroll", "AFXWIN/CEdit::Paste", "AFXWIN/CEdit::PosFromChar", "AFXWIN/CEdit::ReplaceSel", "AFXWIN/CEdit::SetCueBanner", "AFXWIN/CEdit::SetHandle", "AFXWIN/CEdit::SetHighlight", "AFXWIN/CEdit::SetLimitText", "AFXWIN/CEdit::SetMargins", "AFXWIN/CEdit::SetModify", "AFXWIN/CEdit::SetPasswordChar", "AFXWIN/CEdit::SetReadOnly", "AFXWIN/CEdit::SetRect", "AFXWIN/CEdit::SetRectNP", "AFXWIN/CEdit::SetSel", "AFXWIN/CEdit::SetTabStops", "AFXWIN/CEdit::ShowBalloonTip", "AFXWIN/CEdit::Undo"] helpviewer_keywords: ["CEdit [MFC], CEdit", "CEdit [MFC], CanUndo", "CEdit [MFC], CharFromPos", "CEdit [MFC], Clear", "CEdit [MFC], Copy", "CEdit [MFC], Create", "CEdit [MFC], Cut", "CEdit [MFC], EmptyUndoBuffer", "CEdit [MFC], FmtLines", "CEdit [MFC], GetCueBanner", "CEdit [MFC], GetFirstVisibleLine", "CEdit [MFC], GetHandle", "CEdit [MFC], GetHighlight", "CEdit [MFC], GetLimitText", "CEdit [MFC], GetLine", "CEdit [MFC], GetLineCount", "CEdit [MFC], GetMargins", "CEdit [MFC], GetModify", "CEdit [MFC], GetPasswordChar", "CEdit [MFC], GetRect", "CEdit [MFC], GetSel", "CEdit [MFC], HideBalloonTip", "CEdit [MFC], LimitText", "CEdit [MFC], LineFromChar", "CEdit [MFC], LineIndex", "CEdit [MFC], LineLength", "CEdit [MFC], LineScroll", "CEdit [MFC], Paste", "CEdit [MFC], PosFromChar", "CEdit [MFC], ReplaceSel", "CEdit [MFC], SetCueBanner", "CEdit [MFC], SetHandle", "CEdit [MFC], SetHighlight", "CEdit [MFC], SetLimitText", "CEdit [MFC], SetMargins", "CEdit [MFC], SetModify", "CEdit [MFC], SetPasswordChar", "CEdit [MFC], SetReadOnly", "CEdit [MFC], SetRect", "CEdit [MFC], SetRectNP", "CEdit [MFC], SetSel", "CEdit [MFC], SetTabStops", "CEdit [MFC], ShowBalloonTip", "CEdit [MFC], Undo"] -ms.assetid: b1533c30-7f10-4663-88d3-8b7f2c9f7024 --- # CEdit Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows edit control. ## Syntax diff --git a/docs/mfc/reference/ceditview-class.md b/docs/mfc/reference/ceditview-class.md index 618fca8547c..d2a418035b5 100644 --- a/docs/mfc/reference/ceditview-class.md +++ b/docs/mfc/reference/ceditview-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A type of view class that provides the functionality of a Windows edit control and can be used to implement simple text-editor functionality. ## Syntax @@ -427,7 +429,7 @@ Width of each tab stop, in dialog units. ### Remarks -Only a single tab-stop width is supported. ( `CEdit` objects support multiple tab widths.) Widths are in dialog units, which equal one-fourth of the average character width (based on uppercase and lowercase alphabetic characters only) of the font used at the time of printing or displaying. You should not use `CEdit::SetTabStops` because `CEditView` must cache the tab-stop value. +Only a single tab-stop width is supported. (`CEdit` objects support multiple tab widths.) Widths are in dialog units, which equal one-fourth of the average character width (based on uppercase and lowercase alphabetic characters only) of the font used at the time of printing or displaying. You should not use `CEdit::SetTabStops` because `CEditView` must cache the tab-stop value. This function modifies only the tabs of the object for which it is called. To change the tab stops for each `CEditView` object in your application, call each object's `SetTabStops` function. diff --git a/docs/mfc/reference/cevent-class.md b/docs/mfc/reference/cevent-class.md index d9d30ffa385..0389a61a321 100644 --- a/docs/mfc/reference/cevent-class.md +++ b/docs/mfc/reference/cevent-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CEvent [MFC], CEvent", "CEvent [MFC], PulseEvent", "CEven --- # `CEvent` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an event, which is a synchronization object that enables one thread to notify another that an event has occurred. ## Syntax @@ -53,7 +56,7 @@ For more information about how to use `CEvent` objects, see [Multithreading: How ## Example [!code-cpp[NVC_MFC_Utilities#45](../../mfc/codesnippet/cpp/cevent-class_1.cpp)] - +  [!code-cpp[NVC_MFC_Utilities#46](../../mfc/codesnippet/cpp/cevent-class_2.cpp)] ## Inheritance Hierarchy diff --git a/docs/mfc/reference/cexception-class.md b/docs/mfc/reference/cexception-class.md index 93c2dbab31a..8bc8d5f40da 100644 --- a/docs/mfc/reference/cexception-class.md +++ b/docs/mfc/reference/cexception-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CException [MFC], CException", "CException [MFC], Delete" --- # `CException` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for all exceptions in the Microsoft Foundation Class Library. ## Syntax @@ -32,7 +35,7 @@ class AFX_NOVTABLE CException : public CObject ## Remarks -Because `CException` is an abstract base class you can’t create `CException` objects directly; you must create objects of derived classes. If you need to create your own `CException`-style class, use one of the derived classes listed above as a model. Make sure that your derived class also uses `IMPLEMENT_DYNAMIC`. +Because `CException` is an abstract base class you can't create `CException` objects directly; you must create objects of derived classes. If you need to create your own `CException`-style class, use one of the derived classes listed above as a model. Make sure that your derived class also uses `IMPLEMENT_DYNAMIC`. The derived classes and their descriptions are listed below: @@ -143,7 +146,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/cfieldexchange-class.md b/docs/mfc/reference/cfieldexchange-class.md index 02902f9e1c8..f1a099f9bc7 100644 --- a/docs/mfc/reference/cfieldexchange-class.md +++ b/docs/mfc/reference/cfieldexchange-class.md @@ -4,10 +4,12 @@ title: "CFieldExchange Class" ms.date: "11/04/2016" f1_keywords: ["CFieldExchange", "AFXDB/CFieldExchange", "AFXDB/CFieldExchange::IsFieldType", "AFXDB/CFieldExchange::SetFieldType"] helpviewer_keywords: ["CFieldExchange [MFC], IsFieldType", "CFieldExchange [MFC], SetFieldType"] -ms.assetid: 24c5c0b3-06a6-430e-9b6f-005a2c65e29f --- # CFieldExchange Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports the record field exchange (RFX) and bulk record field exchange (Bulk RFX) routines used by the database classes. ## Syntax diff --git a/docs/mfc/reference/cfile-class.md b/docs/mfc/reference/cfile-class.md index de431233f28..5c12dc2db75 100644 --- a/docs/mfc/reference/cfile-class.md +++ b/docs/mfc/reference/cfile-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for Microsoft Foundation Class file classes. ## Syntax @@ -277,7 +279,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 @@ -547,7 +549,7 @@ The following table describes the possible results of `Open`. ### Example [!code-cpp[NVC_MFCFiles#13](../../atl-mfc-shared/reference/codesnippet/cpp/cfile-class_9.cpp)] - +  [!code-cpp[NVC_MFCFiles#14](../../atl-mfc-shared/reference/codesnippet/cpp/cfile-class_10.cpp)] ## CFile::operator HANDLE diff --git a/docs/mfc/reference/cfiledialog-class.md b/docs/mfc/reference/cfiledialog-class.md index 0f65edabaf2..3d84f293e8b 100644 --- a/docs/mfc/reference/cfiledialog-class.md +++ b/docs/mfc/reference/cfiledialog-class.md @@ -4,10 +4,12 @@ title: "CFileDialog Class" ms.date: "11/04/2016" f1_keywords: ["CFileDialog", "AFXDLGS/CFileDialog", "AFXDLGS/CFileDialog::CFileDialog", "AFXDLGS/CFileDialog::AddCheckButton", "AFXDLGS/CFileDialog::AddComboBox", "AFXDLGS/CFileDialog::AddControlItem", "AFXDLGS/CFileDialog::AddEditBox", "AFXDLGS/CFileDialog::AddMenu", "AFXDLGS/CFileDialog::AddPlace", "AFXDLGS/CFileDialog::AddPushButton", "AFXDLGS/CFileDialog::AddRadioButtonList", "AFXDLGS/CFileDialog::AddSeparator", "AFXDLGS/CFileDialog::AddText", "AFXDLGS/CFileDialog::ApplyOFNToShellDialog", "AFXDLGS/CFileDialog::DoModal", "AFXDLGS/CFileDialog::EnableOpenDropDown", "AFXDLGS/CFileDialog::EndVisualGroup", "AFXDLGS/CFileDialog::GetCheckButtonState", "AFXDLGS/CFileDialog::GetControlItemState", "AFXDLGS/CFileDialog::GetControlState", "AFXDLGS/CFileDialog::GetEditBoxText", "AFXDLGS/CFileDialog::GetFileExt", "AFXDLGS/CFileDialog::GetFileName", "AFXDLGS/CFileDialog::GetFileTitle", "AFXDLGS/CFileDialog::GetFolderPath", "AFXDLGS/CFileDialog::GetIFileDialogCustomize", "AFXDLGS/CFileDialog::GetIFileOpenDialog", "AFXDLGS/CFileDialog::GetIFileSaveDialog", "AFXDLGS/CFileDialog::GetNextPathName", "AFXDLGS/CFileDialog::GetOFN", "AFXDLGS/CFileDialog::GetPathName", "AFXDLGS/CFileDialog::GetReadOnlyPref", "AFXDLGS/CFileDialog::GetResult", "AFXDLGS/CFileDialog::GetResults", "AFXDLGS/CFileDialog::GetSelectedControlItem", "AFXDLGS/CFileDialog::GetStartPosition", "AFXDLGS/CFileDialog::HideControl", "AFXDLGS/CFileDialog::IsPickFoldersMode", "AFXDLGS/CFileDialog::MakeProminent", "AFXDLGS/CFileDialog::RemoveControlItem", "AFXDLGS/CFileDialog::SetCheckButtonState", "AFXDLGS/CFileDialog::SetControlItemState", "AFXDLGS/CFileDialog::SetControlItemText", "AFXDLGS/CFileDialog::SetControlLabel", "AFXDLGS/CFileDialog::SetControlState", "AFXDLGS/CFileDialog::SetControlText", "AFXDLGS/CFileDialog::SetDefExt", "AFXDLGS/CFileDialog::SetEditBoxText", "AFXDLGS/CFileDialog::SetProperties", "AFXDLGS/CFileDialog::SetSelectedControlItem", "AFXDLGS/CFileDialog::SetTemplate", "AFXDLGS/CFileDialog::StartVisualGroup", "AFXDLGS/CFileDialog::UpdateOFNFromShellDialog", "AFXDLGS/CFileDialog::OnButtonClicked", "AFXDLGS/CFileDialog::OnCheckButtonToggled", "AFXDLGS/CFileDialog::OnControlActivating", "AFXDLGS/CFileDialog::OnFileNameChange", "AFXDLGS/CFileDialog::OnFileNameOK", "AFXDLGS/CFileDialog::OnFolderChange", "AFXDLGS/CFileDialog::OnInitDone", "AFXDLGS/CFileDialog::OnItemSelected", "AFXDLGS/CFileDialog::OnLBSelChangedNotify", "AFXDLGS/CFileDialog::OnShareViolation", "AFXDLGS/CFileDialog::OnTypeChange", "AFXDLGS/CFileDialog::m_ofn"] helpviewer_keywords: ["CFileDialog [MFC], CFileDialog", "CFileDialog [MFC], AddCheckButton", "CFileDialog [MFC], AddComboBox", "CFileDialog [MFC], AddControlItem", "CFileDialog [MFC], AddEditBox", "CFileDialog [MFC], AddMenu", "CFileDialog [MFC], AddPlace", "CFileDialog [MFC], AddPushButton", "CFileDialog [MFC], AddRadioButtonList", "CFileDialog [MFC], AddSeparator", "CFileDialog [MFC], AddText", "CFileDialog [MFC], ApplyOFNToShellDialog", "CFileDialog [MFC], DoModal", "CFileDialog [MFC], EnableOpenDropDown", "CFileDialog [MFC], EndVisualGroup", "CFileDialog [MFC], GetCheckButtonState", "CFileDialog [MFC], GetControlItemState", "CFileDialog [MFC], GetControlState", "CFileDialog [MFC], GetEditBoxText", "CFileDialog [MFC], GetFileExt", "CFileDialog [MFC], GetFileName", "CFileDialog [MFC], GetFileTitle", "CFileDialog [MFC], GetFolderPath", "CFileDialog [MFC], GetIFileDialogCustomize", "CFileDialog [MFC], GetIFileOpenDialog", "CFileDialog [MFC], GetIFileSaveDialog", "CFileDialog [MFC], GetNextPathName", "CFileDialog [MFC], GetOFN", "CFileDialog [MFC], GetPathName", "CFileDialog [MFC], GetReadOnlyPref", "CFileDialog [MFC], GetResult", "CFileDialog [MFC], GetResults", "CFileDialog [MFC], GetSelectedControlItem", "CFileDialog [MFC], GetStartPosition", "CFileDialog [MFC], HideControl", "CFileDialog [MFC], IsPickFoldersMode", "CFileDialog [MFC], MakeProminent", "CFileDialog [MFC], RemoveControlItem", "CFileDialog [MFC], SetCheckButtonState", "CFileDialog [MFC], SetControlItemState", "CFileDialog [MFC], SetControlItemText", "CFileDialog [MFC], SetControlLabel", "CFileDialog [MFC], SetControlState", "CFileDialog [MFC], SetControlText", "CFileDialog [MFC], SetDefExt", "CFileDialog [MFC], SetEditBoxText", "CFileDialog [MFC], SetProperties", "CFileDialog [MFC], SetSelectedControlItem", "CFileDialog [MFC], SetTemplate", "CFileDialog [MFC], StartVisualGroup", "CFileDialog [MFC], UpdateOFNFromShellDialog", "CFileDialog [MFC], OnButtonClicked", "CFileDialog [MFC], OnCheckButtonToggled", "CFileDialog [MFC], OnControlActivating", "CFileDialog [MFC], OnFileNameChange", "CFileDialog [MFC], OnFileNameOK", "CFileDialog [MFC], OnFolderChange", "CFileDialog [MFC], OnInitDone", "CFileDialog [MFC], OnItemSelected", "CFileDialog [MFC], OnLBSelChangedNotify", "CFileDialog [MFC], OnShareViolation", "CFileDialog [MFC], OnTypeChange", "CFileDialog [MFC], m_ofn"] -ms.assetid: fda4fd3c-08b8-4ce0-8e9d-7bab23f8c6c0 --- # CFileDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the common dialog box that is used for file open or file save operations. ## Syntax @@ -411,7 +413,7 @@ explicit CFileDialog( [in] The parameter that specifies what type of dialog box to create. Set it to TRUE to construct a **File Open** dialog box. Set it to FALSE to construct a **File Save As** dialog box. *lpszDefExt*
-[in] The default file name extension. If the user does not include a known extension (one that has an association on the user’s computer) in the Filename box, the extension specified by *lpszDefExt* is automatically appended to the file name. If this parameter is NULL, no extension is appended. +[in] The default file name extension. If the user does not include a known extension (one that has an association on the user's computer) in the Filename box, the extension specified by *lpszDefExt* is automatically appended to the file name. If this parameter is NULL, no extension is appended. *lpszFileName*
[in] The initial file name that appears in the Filename box. If NULL, no initial file name appears. @@ -437,7 +439,7 @@ The parameter that specifies the style of the file dialog. Set it to TRUE to use Either a **File Open** or **File Save As** dialog box is constructed, depending on the value of *bOpenFileDialog*. -Specifying a default extension using *lpszDefExt* may not produce the behavior that you expect, because it is seldom predictable what extensions have file associations on the user’s computer. If you need more control over the appending of a default extension, you can derive your own class from `CFileDialog`, and override the `CFileDialog::OnFileNameOK` method to perform your own extension handling. +Specifying a default extension using *lpszDefExt* may not produce the behavior that you expect, because it is seldom predictable what extensions have file associations on the user's computer. If you need more control over the appending of a default extension, you can derive your own class from `CFileDialog`, and override the `CFileDialog::OnFileNameOK` method to perform your own extension handling. To enable the user to select multiple files, set the OFN_ALLOWMULTISELECT flag before you call [DoModal](#domodal). You must supply your own file name buffer to store the returned list of multiple file names. Do this by replacing `m_ofn.lpstrFile` with a pointer to a buffer you have allocated, after you construct the [CFileDialog](../../mfc/reference/cfiledialog-class.md), but before you call `DoModal`. Additionally, you must set `m_ofn.nMaxFile` with the number of characters in the buffer pointed to by `m_ofn.lpstrFile`. If you set the maximum number of files to be selected to *n*, the necessary buffer size is `n`*(_MAX_PATH + 1) + 1. For example: diff --git a/docs/mfc/reference/cfileexception-class.md b/docs/mfc/reference/cfileexception-class.md index 5b9dda753a6..a69119c7834 100644 --- a/docs/mfc/reference/cfileexception-class.md +++ b/docs/mfc/reference/cfileexception-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CFileException [MFC], CFileException", "CFileException [M --- # `CFileException` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a file-related exception condition. ## Syntax @@ -170,7 +173,7 @@ This data member is a public variable of type **`int`**. The enumerators and the | `CFileException::tooManyOpenFiles` | 4: The permitted number of open files was exceeded. | | `CFileException::accessDenied` | 5: The file couldn't be accessed. | | `CFileException::invalidFile` | 6: There was an attempt to use an invalid file handle. | -| `CFileException::removeCurrentDir` | 7: The current working directory can’t be removed. | +| `CFileException::removeCurrentDir` | 7: The current working directory can't be removed. | | `CFileException::directoryFull` | 8: There are no more directory entries. | | `CFileException::badSeek` | 9: There was an error trying to set the file pointer. | | `CFileException::hardIO` | 10: There was a hardware error. | diff --git a/docs/mfc/reference/cfilefind-class.md b/docs/mfc/reference/cfilefind-class.md index aabf078c761..01edcb95523 100644 --- a/docs/mfc/reference/cfilefind-class.md +++ b/docs/mfc/reference/cfilefind-class.md @@ -4,10 +4,12 @@ title: "CFileFind Class" ms.date: "11/04/2016" f1_keywords: ["CFileFind", "AFX/CFileFind", "AFX/CFileFind::CFileFind", "AFX/CFileFind::Close", "AFX/CFileFind::FindFile", "AFX/CFileFind::FindNextFile", "AFX/CFileFind::GetCreationTime", "AFX/CFileFind::GetFileName", "AFX/CFileFind::GetFilePath", "AFX/CFileFind::GetFileTitle", "AFX/CFileFind::GetFileURL", "AFX/CFileFind::GetLastAccessTime", "AFX/CFileFind::GetLastWriteTime", "AFX/CFileFind::GetLength", "AFX/CFileFind::GetRoot", "AFX/CFileFind::IsArchived", "AFX/CFileFind::IsCompressed", "AFX/CFileFind::IsDirectory", "AFX/CFileFind::IsDots", "AFX/CFileFind::IsHidden", "AFX/CFileFind::IsNormal", "AFX/CFileFind::IsReadOnly", "AFX/CFileFind::IsSystem", "AFX/CFileFind::IsTemporary", "AFX/CFileFind::MatchesMask", "AFX/CFileFind::CloseContext", "AFX/CFileFind::m_pTM"] helpviewer_keywords: ["CFileFind [MFC], CFileFind", "CFileFind [MFC], Close", "CFileFind [MFC], FindFile", "CFileFind [MFC], FindNextFile", "CFileFind [MFC], GetCreationTime", "CFileFind [MFC], GetFileName", "CFileFind [MFC], GetFilePath", "CFileFind [MFC], GetFileTitle", "CFileFind [MFC], GetFileURL", "CFileFind [MFC], GetLastAccessTime", "CFileFind [MFC], GetLastWriteTime", "CFileFind [MFC], GetLength", "CFileFind [MFC], GetRoot", "CFileFind [MFC], IsArchived", "CFileFind [MFC], IsCompressed", "CFileFind [MFC], IsDirectory", "CFileFind [MFC], IsDots", "CFileFind [MFC], IsHidden", "CFileFind [MFC], IsNormal", "CFileFind [MFC], IsReadOnly", "CFileFind [MFC], IsSystem", "CFileFind [MFC], IsTemporary", "CFileFind [MFC], MatchesMask", "CFileFind [MFC], CloseContext", "CFileFind [MFC], m_pTM"] -ms.assetid: 9990068c-b023-4114-9580-a50182d15240 --- # `CFileFind` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Performs local file searches and is the base class for [`CGopherFileFind`](../../mfc/reference/cgopherfilefind-class.md) and [`CFtpFileFind`](../../mfc/reference/cftpfilefind-class.md), which perform Internet file searches. ## Syntax diff --git a/docs/mfc/reference/cfindreplacedialog-class.md b/docs/mfc/reference/cfindreplacedialog-class.md index 4f4ac279860..bb106ba948c 100644 --- a/docs/mfc/reference/cfindreplacedialog-class.md +++ b/docs/mfc/reference/cfindreplacedialog-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows you to implement standard string Find/Replace dialog boxes in your application. ## Syntax @@ -142,12 +144,12 @@ Nonzero if the dialog box object was successfully created; otherwise 0. ### Remarks -In order for the parent window to be notified of find/replace requests, you must use the Windows [RegisterWindowMessage](/windows/win32/api/winuser/nf-winuser-registerwindowmessagew) function whose return value is a message number unique to the application's instance. Your frame window should have a message map entry that declares the callback function ( `OnFindReplace` in the example that follows) that handles this registered message. The following code fragment is an example of how to do this for a frame window class named `CMyRichEditView`: +In order for the parent window to be notified of find/replace requests, you must use the Windows [RegisterWindowMessage](/windows/win32/api/winuser/nf-winuser-registerwindowmessagew) function whose return value is a message number unique to the application's instance. Your frame window should have a message map entry that declares the callback function (`OnFindReplace` in the example that follows) that handles this registered message. The following code fragment is an example of how to do this for a frame window class named `CMyRichEditView`: [!code-cpp[NVC_MFCDocView#171](../../mfc/codesnippet/cpp/cfindreplacedialog-class_2.h)] - +  [!code-cpp[NVC_MFCDocView#172](../../mfc/codesnippet/cpp/cfindreplacedialog-class_3.cpp)] - +  [!code-cpp[NVC_MFCDocView#173](../../mfc/codesnippet/cpp/cfindreplacedialog-class_4.cpp)] Within your `OnFindReplace` function, you interpret the intentions of the user by using the [CFindReplaceDialog::FindNext](#findnext) and [CFindReplaceDialog::IsTerminating](#isterminating) methods and you create the code for the find/replace operations. diff --git a/docs/mfc/reference/cfolderpickerdialog-class.md b/docs/mfc/reference/cfolderpickerdialog-class.md index de4f2750fa3..3e416178867 100644 --- a/docs/mfc/reference/cfolderpickerdialog-class.md +++ b/docs/mfc/reference/cfolderpickerdialog-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CFolderPickerDialog [MFC], CFolderPickerDialog"] --- # `CFolderPickerDialog` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CFolderPickerDialog` class implements `CFileDialog` in the folder picker mode. ## Syntax diff --git a/docs/mfc/reference/cfont-class.md b/docs/mfc/reference/cfont-class.md index 768ca7bd6af..c16e20c74d1 100644 --- a/docs/mfc/reference/cfont-class.md +++ b/docs/mfc/reference/cfont-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a Windows graphics device interface (GDI) font and provides member functions for manipulating the font. ## Syntax @@ -102,7 +104,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. @@ -142,7 +144,7 @@ Specifies the desired clipping precision. The clipping precision defines how to To use an embedded read-only font, an application must specify `CLIP_ENCAPSULATE`. -To achieve consistent rotation of device, TrueType, and vector fonts, an application can use the bitwise OR operator (`|`) to combine the `CLIP_LH_ANGLES` value with any of the other *`nClipPrecision`* values. If the `CLIP_LH_ANGLES` bit is set, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed. (For more information about the orientation of coordinate systems, see the description of the *`nOrientation`* parameter.) If `CLIP_LH_ANGLES` is not set, device fonts always rotate counterclockwise, but the rotation of other fonts is dependent on the orientation of the coordinate system. +To achieve consistent rotation of device, TrueType, and vector fonts, an application can use the bitwise OR operator (`|`) to combine the `CLIP_LH_ANGLES` value with any of the other *`nClipPrecision`* values. If the `CLIP_LH_ANGLES` bit is set, the rotation for all fonts depends on whether the orientation of the coordinate system is left-handed or right-handed. For more information about the orientation of coordinate systems, see the description of the *`nOrientation`* parameter. If `CLIP_LH_ANGLES` is not set, device fonts always rotate counterclockwise, but the rotation of other fonts is dependent on the orientation of the coordinate system. *`nQuality`*
Specifies the font's output quality, which defines how carefully the GDI must attempt to match the logical-font attributes to those of an actual physical font. See the `lfQuality` member in the `LOGFONT` structure in the Windows SDK for a list of values. @@ -173,7 +175,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/cfontdialog-class.md b/docs/mfc/reference/cfontdialog-class.md index 175c1d1978c..277855afb50 100644 --- a/docs/mfc/reference/cfontdialog-class.md +++ b/docs/mfc/reference/cfontdialog-class.md @@ -4,10 +4,12 @@ title: "CFontDialog Class" ms.date: "11/04/2016" f1_keywords: ["CFontDialog", "AFXDLGS/CFontDialog", "AFXDLGS/CFontDialog::CFontDialog", "AFXDLGS/CFontDialog::DoModal", "AFXDLGS/CFontDialog::GetCharFormat", "AFXDLGS/CFontDialog::GetColor", "AFXDLGS/CFontDialog::GetCurrentFont", "AFXDLGS/CFontDialog::GetFaceName", "AFXDLGS/CFontDialog::GetSize", "AFXDLGS/CFontDialog::GetStyleName", "AFXDLGS/CFontDialog::GetWeight", "AFXDLGS/CFontDialog::IsBold", "AFXDLGS/CFontDialog::IsItalic", "AFXDLGS/CFontDialog::IsStrikeOut", "AFXDLGS/CFontDialog::IsUnderline", "AFXDLGS/CFontDialog::m_cf"] helpviewer_keywords: ["CFontDialog [MFC], CFontDialog", "CFontDialog [MFC], DoModal", "CFontDialog [MFC], GetCharFormat", "CFontDialog [MFC], GetColor", "CFontDialog [MFC], GetCurrentFont", "CFontDialog [MFC], GetFaceName", "CFontDialog [MFC], GetSize", "CFontDialog [MFC], GetStyleName", "CFontDialog [MFC], GetWeight", "CFontDialog [MFC], IsBold", "CFontDialog [MFC], IsItalic", "CFontDialog [MFC], IsStrikeOut", "CFontDialog [MFC], IsUnderline", "CFontDialog [MFC], m_cf"] -ms.assetid: 6228d500-ed0f-4156-81e5-ab0d57d1dcf4 --- # CFontDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows you to incorporate a font-selection dialog box into your application. ## Syntax diff --git a/docs/mfc/reference/cfontholder-class.md b/docs/mfc/reference/cfontholder-class.md index 793af5a5496..22a1b18a28f 100644 --- a/docs/mfc/reference/cfontholder-class.md +++ b/docs/mfc/reference/cfontholder-class.md @@ -4,10 +4,12 @@ title: "CFontHolder Class" ms.date: "11/04/2016" f1_keywords: ["CFontHolder", "AFXCTL/CFontHolder", "AFXCTL/CFontHolder::CFontHolder", "AFXCTL/CFontHolder::GetDisplayString", "AFXCTL/CFontHolder::GetFontDispatch", "AFXCTL/CFontHolder::GetFontHandle", "AFXCTL/CFontHolder::InitializeFont", "AFXCTL/CFontHolder::QueryTextMetrics", "AFXCTL/CFontHolder::ReleaseFont", "AFXCTL/CFontHolder::Select", "AFXCTL/CFontHolder::SetFont", "AFXCTL/CFontHolder::m_pFont"] helpviewer_keywords: ["CFontHolder [MFC], CFontHolder", "CFontHolder [MFC], GetDisplayString", "CFontHolder [MFC], GetFontDispatch", "CFontHolder [MFC], GetFontHandle", "CFontHolder [MFC], InitializeFont", "CFontHolder [MFC], QueryTextMetrics", "CFontHolder [MFC], ReleaseFont", "CFontHolder [MFC], Select", "CFontHolder [MFC], SetFont", "CFontHolder [MFC], m_pFont"] -ms.assetid: 728ab472-0c97-440d-889f-1324c6e1b6b8 --- # CFontHolder Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the stock Font property and encapsulates the functionality of a Windows font object and the `IFont` interface. ## Syntax diff --git a/docs/mfc/reference/cformview-class.md b/docs/mfc/reference/cformview-class.md index de28089798d..97aeaa9ffc6 100644 --- a/docs/mfc/reference/cformview-class.md +++ b/docs/mfc/reference/cformview-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CFormView [MFC], CFormView", "CFormView [MFC], IsInitDlgC --- # `CFormView` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class used for form views. ## Syntax @@ -35,7 +38,7 @@ A form view is essentially a view that contains controls. These controls are lai When you're [Creating a Forms-Based Application](../../mfc/reference/creating-a-forms-based-mfc-application.md), you can base its view class on `CFormView`, making it a forms-based application. -You can also insert new [Form Topics](../../mfc/form-views-mfc.md) into document-view-based applications. Even if your application didn't initially support forms, Visual C++ will add this support when you insert a new form. +You can also insert new [Form Topics](../../mfc/form-views-mfc.md) into document-view-based applications. Even if your application didn't initially support forms, Visual Studio will add this support when you insert a new form. The MFC Application Wizard and the Add Class command are the preferred methods for creating forms-based applications. If you need to create a forms-based application without using these methods, see [Creating a Forms-Based Application](../../mfc/reference/creating-a-forms-based-mfc-application.md). @@ -86,7 +89,7 @@ The form-view window and child controls aren't created until `CWnd::Create` is c ### Example [!code-cpp[NVC_MFCDocView#90](../../mfc/codesnippet/cpp/cformview-class_1.h)] - +  [!code-cpp[NVC_MFCDocView#91](../../mfc/codesnippet/cpp/cformview-class_2.cpp)] ## `CFormView::IsInitDlgCompleted` diff --git a/docs/mfc/reference/cframewnd-class.md b/docs/mfc/reference/cframewnd-class.md index 969f96a322e..633733e9f7b 100644 --- a/docs/mfc/reference/cframewnd-class.md +++ b/docs/mfc/reference/cframewnd-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows single document interface (SDI) overlapped or pop-up frame window, along with members for managing the window. ## Syntax @@ -420,7 +422,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 +434,7 @@ A pointer to the current [`CView`](../../mfc/reference/cview-class.md). If there ### Remarks -This function returns `NULL` when called for an MDI main frame window ( `CMDIFrameWnd`). In an MDI application, the MDI main frame window does not have a view associated with it. Instead, each individual child window ( `CMDIChildWnd`) has one or more associated views. The active view in an MDI application can be obtained by first finding the active MDI child window and then finding the active view for that child window. The active MDI child window can be found by calling the function `MDIGetActive` or `GetActiveFrame` as demonstrated in the following: +This function returns `NULL` when called for an MDI main frame window (`CMDIFrameWnd`). In an MDI application, the MDI main frame window does not have a view associated with it. Instead, each individual child window (`CMDIChildWnd`) has one or more associated views. The active view in an MDI application can be obtained by first finding the active MDI child window and then finding the active view for that child window. The active MDI child window can be found by calling the function `MDIGetActive` or `GetActiveFrame` as demonstrated in the following: [!code-cpp[NVC_MFCWindowing#2](../../mfc/reference/codesnippet/cpp/cframewnd-class_2.cpp)] @@ -512,7 +514,7 @@ This method returns one of the following values: - `AFX_MBV_DISPLAYONFOCUS` (0x02) - The menu is hidden by default. If the menu is hidden, press the ALT key to display the menu and give it the focus. If the menu is displayed, press the ALT or ESC key to hide it. -- `AFX_MBV_ DISPLAYONFOCUS | AFX_MBV_DISPLAYONF10` (0x06) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it. +- `AFX_MBV_DISPLAYONFOCUS | AFX_MBV_DISPLAYONF10` (0x06) - The menu is hidden by default. If the menu is hidden, press the F10 key to display the menu and give it the focus. If the menu is displayed, press the F10 key to toggle the focus on or off the menu. The menu is displayed until you press the ALT or ESC key to hide it. ### Remarks diff --git a/docs/mfc/reference/cframewndex-class.md b/docs/mfc/reference/cframewndex-class.md index e81e7b78581..8447320700c 100644 --- a/docs/mfc/reference/cframewndex-class.md +++ b/docs/mfc/reference/cframewndex-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CFrameWndEx` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the functionality of a Windows single document interface (SDI) overlapped or popup frame window, and provides members for managing the window. It extends the [`CFrameWnd`](../../mfc/reference/cframewnd-class.md) class. ## Syntax @@ -107,7 +110,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 @@ -1436,7 +1439,7 @@ This method always returns `TRUE`. ### Remarks -The quick customize menu is a pop-up menu that appears when you click the toolbar’s customize button +The quick customize menu is a pop-up menu that appears when you click the toolbar's customize button ## `CFrameWndEx::OnShowPanes` diff --git a/docs/mfc/reference/cftpconnection-class.md b/docs/mfc/reference/cftpconnection-class.md index 5fd943b04eb..6f1606040cb 100644 --- a/docs/mfc/reference/cftpconnection-class.md +++ b/docs/mfc/reference/cftpconnection-class.md @@ -4,10 +4,12 @@ title: "CFtpConnection Class" ms.date: "08/29/2019" f1_keywords: ["CFtpConnection", "AFXINET/CFtpConnection", "AFXINET/CFtpConnection::CFtpConnection", "AFXINET/CFtpConnection::Command", "AFXINET/CFtpConnection::CreateDirectory", "AFXINET/CFtpConnection::GetCurrentDirectory", "AFXINET/CFtpConnection::GetCurrentDirectoryAsURL", "AFXINET/CFtpConnection::GetFile", "AFXINET/CFtpConnection::OpenFile", "AFXINET/CFtpConnection::PutFile", "AFXINET/CFtpConnection::Remove", "AFXINET/CFtpConnection::RemoveDirectory", "AFXINET/CFtpConnection::Rename", "AFXINET/CFtpConnection::SetCurrentDirectory"] helpviewer_keywords: ["CFtpConnection [MFC], CFtpConnection", "CFtpConnection [MFC], Command", "CFtpConnection [MFC], CreateDirectory", "CFtpConnection [MFC], GetCurrentDirectory", "CFtpConnection [MFC], GetCurrentDirectoryAsURL", "CFtpConnection [MFC], GetFile", "CFtpConnection [MFC], OpenFile", "CFtpConnection [MFC], PutFile", "CFtpConnection [MFC], Remove", "CFtpConnection [MFC], RemoveDirectory", "CFtpConnection [MFC], Rename", "CFtpConnection [MFC], SetCurrentDirectory"] -ms.assetid: 5e3a0501-8893-49cf-a3d5-0628d8d6b936 --- # CFtpConnection Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages your FTP connection to an Internet server and allows direct manipulation of directories and files on that server. ## Syntax @@ -369,7 +371,7 @@ A pointer to a [CInternetFile](../../mfc/reference/cinternetfile-class.md) objec - An application needs a fine level of control over a file transfer. For example, the application may want to display a progress control indicate the progress of the file transfer status while downloading a file. -After calling `OpenFile` and until calling `CInternetConnection::Close`, the application can only call [CInternetFile::Read](../../mfc/reference/cinternetfile-class.md#read), [CInternetFile::Write](../../mfc/reference/cinternetfile-class.md#write), `CInternetConnection::Close`, or [CFtpFileFind::FindFile](../../mfc/reference/cftpfilefind-class.md#findfile). Calls to other FTP functions for the same FTP session will fail and set the error code to FTP_ETRANSFER_IN_PROGRESS. +After calling `OpenFile` and until calling `CInternetFile::Close`, the application can only call [CInternetFile::Read](../../mfc/reference/cinternetfile-class.md#read), [CInternetFile::Write](../../mfc/reference/cinternetfile-class.md#write), `CInternetConnection::Close`, or [CFtpFileFind::FindFile](../../mfc/reference/cftpfilefind-class.md#findfile). Calls to other FTP functions for the same FTP session will fail and set the error code to FTP_ETRANSFER_IN_PROGRESS. The *pstrFileName* parameter can be either a partially qualified filename relative to the current directory or fully qualified. A backslash (\\) or forward slash (/) can be used as the directory separator for either name. `OpenFile` translates the directory name separators to the appropriate characters before using it. diff --git a/docs/mfc/reference/cftpfilefind-class.md b/docs/mfc/reference/cftpfilefind-class.md index f43026aff12..33966e135c9 100644 --- a/docs/mfc/reference/cftpfilefind-class.md +++ b/docs/mfc/reference/cftpfilefind-class.md @@ -4,10 +4,12 @@ title: "CFtpFileFind Class" ms.date: "05/28/2020" f1_keywords: ["CFtpFileFind", "AFXINET/CFtpFileFind", "AFXINET/CFtpFileFind::CFtpFileFind", "AFXINET/CFtpFileFind::FindFile", "AFXINET/CFtpFileFind::FindNextFile", "AFXINET/CFtpFileFind::GetFileURL"] helpviewer_keywords: ["CFtpFileFind [MFC], CFtpFileFind", "CFtpFileFind [MFC], FindFile", "CFtpFileFind [MFC], FindNextFile", "CFtpFileFind [MFC], GetFileURL"] -ms.assetid: 9667cf01-657f-4b11-b9db-f11e5a7b4e4c --- # CFtpFileFind Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Aids in Internet file searches of FTP servers. ## Syntax diff --git a/docs/mfc/reference/cgdiobject-class.md b/docs/mfc/reference/cgdiobject-class.md index ff6dde45220..ab134f376d1 100644 --- a/docs/mfc/reference/cgdiobject-class.md +++ b/docs/mfc/reference/cgdiobject-class.md @@ -4,10 +4,12 @@ title: "CGdiObject Class" ms.date: "11/04/2016" f1_keywords: ["CGdiObject", "AFXWIN/CGdiObject", "AFXWIN/CGdiObject::CGdiObject", "AFXWIN/CGdiObject::Attach", "AFXWIN/CGdiObject::CreateStockObject", "AFXWIN/CGdiObject::DeleteObject", "AFXWIN/CGdiObject::DeleteTempMap", "AFXWIN/CGdiObject::Detach", "AFXWIN/CGdiObject::FromHandle", "AFXWIN/CGdiObject::GetObject", "AFXWIN/CGdiObject::GetObjectType", "AFXWIN/CGdiObject::GetSafeHandle", "AFXWIN/CGdiObject::UnrealizeObject", "AFXWIN/CGdiObject::m_hObject"] helpviewer_keywords: ["CGdiObject [MFC], CGdiObject", "CGdiObject [MFC], Attach", "CGdiObject [MFC], CreateStockObject", "CGdiObject [MFC], DeleteObject", "CGdiObject [MFC], DeleteTempMap", "CGdiObject [MFC], Detach", "CGdiObject [MFC], FromHandle", "CGdiObject [MFC], GetObject", "CGdiObject [MFC], GetObjectType", "CGdiObject [MFC], GetSafeHandle", "CGdiObject [MFC], UnrealizeObject", "CGdiObject [MFC], m_hObject"] -ms.assetid: 1cba3ba5-3d49-4e43-8293-209299f2f6f4 --- # CGdiObject Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides a base class for various kinds of Windows graphics device interface (GDI) objects such as bitmaps, regions, brushes, pens, palettes, and fonts. ## Syntax diff --git a/docs/mfc/reference/cglobalutils-class.md b/docs/mfc/reference/cglobalutils-class.md index 55f11e6089d..ddfb73146e3 100644 --- a/docs/mfc/reference/cglobalutils-class.md +++ b/docs/mfc/reference/cglobalutils-class.md @@ -4,10 +4,12 @@ title: "CGlobalUtils Class" ms.date: "10/18/2018" f1_keywords: ["CGlobalUtils", "AFXGLOBALUTILS/CGlobalUtils", "AFXGLOBALUTILS/CGlobalUtils::AdjustRectToWorkArea", "AFXGLOBALUTILS/CGlobalUtils::CalcExpectedDockedRect", "AFXGLOBALUTILS/CGlobalUtils::CanBeAttached", "AFXGLOBALUTILS/CGlobalUtils::CanPaneBeInFloatingMultiPaneFrameWnd", "AFXGLOBALUTILS/CGlobalUtils::CheckAlignment", "AFXGLOBALUTILS/CGlobalUtils::CyFromString", "AFXGLOBALUTILS/CGlobalUtils::DecimalFromString", "AFXGLOBALUTILS/CGlobalUtils::FlipRect", "AFXGLOBALUTILS/CGlobalUtils::ForceAdjustLayout", "AFXGLOBALUTILS/CGlobalUtils::GetDockingManager", "AFXGLOBALUTILS/CGlobalUtils::GetOppositeAlignment", "AFXGLOBALUTILS/CGlobalUtils::GetPaneAndAlignFromPoint", "AFXGLOBALUTILS/CGlobalUtils::GetWndIcon", "AFXGLOBALUTILS/CGlobalUtils::SetNewParent", "AFXGLOBALUTILS/CGlobalUtils::StringFromCy", "AFXGLOBALUTILS/CGlobalUtils::StringFromDecimal"] helpviewer_keywords: ["CGlobalUtils [MFC], AdjustRectToWorkArea", "CGlobalUtils [MFC], CalcExpectedDockedRect", "CGlobalUtils [MFC], CanBeAttached", "CGlobalUtils [MFC], CanPaneBeInFloatingMultiPaneFrameWnd", "CGlobalUtils [MFC], CheckAlignment", "CGlobalUtils [MFC], CyFromString", "CGlobalUtils [MFC], DecimalFromString", "CGlobalUtils [MFC], FlipRect", "CGlobalUtils [MFC], ForceAdjustLayout", "CGlobalUtils [MFC], GetDockingManager", "CGlobalUtils [MFC], GetOppositeAlignment", "CGlobalUtils [MFC], GetPaneAndAlignFromPoint", "CGlobalUtils [MFC], GetWndIcon", "CGlobalUtils [MFC], SetNewParent", "CGlobalUtils [MFC], StringFromCy", "CGlobalUtils [MFC], StringFromDecimal"] -ms.assetid: 2c5bd1a6-f80c-4e79-a476-b4ceebabfb2f --- # CGlobalUtils Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. ## Syntax diff --git a/docs/mfc/reference/cgopherconnection-class.md b/docs/mfc/reference/cgopherconnection-class.md index 585855bbfe9..d6c587237d0 100644 --- a/docs/mfc/reference/cgopherconnection-class.md +++ b/docs/mfc/reference/cgopherconnection-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages your connection to a gopher Internet server. > [!NOTE] @@ -167,8 +169,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 +225,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/cgopherfile-class.md b/docs/mfc/reference/cgopherfile-class.md index 8d384db4c31..23dd44f2693 100644 --- a/docs/mfc/reference/cgopherfile-class.md +++ b/docs/mfc/reference/cgopherfile-class.md @@ -4,10 +4,12 @@ title: "CGopherFile Class" ms.date: "11/04/2016" f1_keywords: ["CGopherFile", "AFXINET/CGopherFile", "AFXINET/CGopherFile::CGopherFile"] helpviewer_keywords: ["CGopherFile [MFC], CGopherFile"] -ms.assetid: 3ca9898f-8cdb-4495-bbde-46d40100feda --- # CGopherFile Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality to find and read files on a gopher server. > [!NOTE] diff --git a/docs/mfc/reference/cgopherfilefind-class.md b/docs/mfc/reference/cgopherfilefind-class.md index ef0ffada189..47ad8e86a51 100644 --- a/docs/mfc/reference/cgopherfilefind-class.md +++ b/docs/mfc/reference/cgopherfilefind-class.md @@ -4,10 +4,12 @@ title: "CGopherFileFind Class" ms.date: "11/04/2016" f1_keywords: ["CGopherFileFind", "AFXINET/CGopherFileFind", "AFXINET/CGopherFileFind::CGopherFileFind", "AFXINET/CGopherFileFind::FindFile", "AFXINET/CGopherFileFind::FindNextFile", "AFXINET/CGopherFileFind::GetCreationTime", "AFXINET/CGopherFileFind::GetLastAccessTime", "AFXINET/CGopherFileFind::GetLastWriteTime", "AFXINET/CGopherFileFind::GetLength", "AFXINET/CGopherFileFind::GetLocator", "AFXINET/CGopherFileFind::GetScreenName", "AFXINET/CGopherFileFind::IsDots"] helpviewer_keywords: ["CGopherFileFind [MFC], CGopherFileFind", "CGopherFileFind [MFC], FindFile", "CGopherFileFind [MFC], FindNextFile", "CGopherFileFind [MFC], GetCreationTime", "CGopherFileFind [MFC], GetLastAccessTime", "CGopherFileFind [MFC], GetLastWriteTime", "CGopherFileFind [MFC], GetLength", "CGopherFileFind [MFC], GetLocator", "CGopherFileFind [MFC], GetScreenName", "CGopherFileFind [MFC], IsDots"] -ms.assetid: 8465a979-6323-496d-ab4b-e81383fb999d --- # CGopherFileFind Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Aids in Internet file searches of gopher servers. > [!NOTE] diff --git a/docs/mfc/reference/cgopherlocator-class.md b/docs/mfc/reference/cgopherlocator-class.md index e7d981dba71..aa39d685fbd 100644 --- a/docs/mfc/reference/cgopherlocator-class.md +++ b/docs/mfc/reference/cgopherlocator-class.md @@ -4,10 +4,12 @@ title: "CGopherLocator Class" ms.date: "11/04/2016" f1_keywords: ["CGopherLocator", "AFXINET/CGopherLocator", "AFXINET/CGopherLocator::CGopherLocator", "AFXINET/CGopherLocator::GetLocatorType"] helpviewer_keywords: ["CGopherLocator [MFC], CGopherLocator", "CGopherLocator [MFC], GetLocatorType"] -ms.assetid: 6fcc015f-5ae6-4959-b936-858634c71019 --- # CGopherLocator Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Gets a gopher "locator" from a gopher server, determines the locator's type, and makes the locator available to [CGopherFileFind](../../mfc/reference/cgopherfilefind-class.md). > [!NOTE] diff --git a/docs/mfc/reference/cheaderctrl-class.md b/docs/mfc/reference/cheaderctrl-class.md index 3287d1ab18a..8ded47a365a 100644 --- a/docs/mfc/reference/cheaderctrl-class.md +++ b/docs/mfc/reference/cheaderctrl-class.md @@ -4,10 +4,12 @@ title: "CHeaderCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CHeaderCtrl", "AFXCMN/CHeaderCtrl", "AFXCMN/CHeaderCtrl::CHeaderCtrl", "AFXCMN/CHeaderCtrl::ClearAllFilters", "AFXCMN/CHeaderCtrl::ClearFilter", "AFXCMN/CHeaderCtrl::Create", "AFXCMN/CHeaderCtrl::CreateDragImage", "AFXCMN/CHeaderCtrl::CreateEx", "AFXCMN/CHeaderCtrl::DeleteItem", "AFXCMN/CHeaderCtrl::DrawItem", "AFXCMN/CHeaderCtrl::EditFilter", "AFXCMN/CHeaderCtrl::GetBitmapMargin", "AFXCMN/CHeaderCtrl::GetFocusedItem", "AFXCMN/CHeaderCtrl::GetImageList", "AFXCMN/CHeaderCtrl::GetItem", "AFXCMN/CHeaderCtrl::GetItemCount", "AFXCMN/CHeaderCtrl::GetItemDropDownRect", "AFXCMN/CHeaderCtrl::GetItemRect", "AFXCMN/CHeaderCtrl::GetOrderArray", "AFXCMN/CHeaderCtrl::GetOverflowRect", "AFXCMN/CHeaderCtrl::HitTest", "AFXCMN/CHeaderCtrl::InsertItem", "AFXCMN/CHeaderCtrl::Layout", "AFXCMN/CHeaderCtrl::OrderToIndex", "AFXCMN/CHeaderCtrl::SetBitmapMargin", "AFXCMN/CHeaderCtrl::SetFilterChangeTimeout", "AFXCMN/CHeaderCtrl::SetFocusedItem", "AFXCMN/CHeaderCtrl::SetHotDivider", "AFXCMN/CHeaderCtrl::SetImageList", "AFXCMN/CHeaderCtrl::SetItem", "AFXCMN/CHeaderCtrl::SetOrderArray"] helpviewer_keywords: ["CHeaderCtrl [MFC], CHeaderCtrl", "CHeaderCtrl [MFC], ClearAllFilters", "CHeaderCtrl [MFC], ClearFilter", "CHeaderCtrl [MFC], Create", "CHeaderCtrl [MFC], CreateDragImage", "CHeaderCtrl [MFC], CreateEx", "CHeaderCtrl [MFC], DeleteItem", "CHeaderCtrl [MFC], DrawItem", "CHeaderCtrl [MFC], EditFilter", "CHeaderCtrl [MFC], GetBitmapMargin", "CHeaderCtrl [MFC], GetFocusedItem", "CHeaderCtrl [MFC], GetImageList", "CHeaderCtrl [MFC], GetItem", "CHeaderCtrl [MFC], GetItemCount", "CHeaderCtrl [MFC], GetItemDropDownRect", "CHeaderCtrl [MFC], GetItemRect", "CHeaderCtrl [MFC], GetOrderArray", "CHeaderCtrl [MFC], GetOverflowRect", "CHeaderCtrl [MFC], HitTest", "CHeaderCtrl [MFC], InsertItem", "CHeaderCtrl [MFC], Layout", "CHeaderCtrl [MFC], OrderToIndex", "CHeaderCtrl [MFC], SetBitmapMargin", "CHeaderCtrl [MFC], SetFilterChangeTimeout", "CHeaderCtrl [MFC], SetFocusedItem", "CHeaderCtrl [MFC], SetHotDivider", "CHeaderCtrl [MFC], SetImageList", "CHeaderCtrl [MFC], SetItem", "CHeaderCtrl [MFC], SetOrderArray"] -ms.assetid: b847ac90-5fae-4a87-88e0-ca45f77b8b3b --- # CHeaderCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common header control. ## Syntax diff --git a/docs/mfc/reference/child-window-notification-message-handlers.md b/docs/mfc/reference/child-window-notification-message-handlers.md index 46654fcf608..318b2f6e6ae 100644 --- a/docs/mfc/reference/child-window-notification-message-handlers.md +++ b/docs/mfc/reference/child-window-notification-message-handlers.md @@ -4,10 +4,12 @@ title: "Child Window Notification Message Handlers" ms.date: "11/04/2016" f1_keywords: ["ChildWindow"] helpviewer_keywords: ["message handlers [MFC]", "message handling [MFC], child window message handlers", "notifications [MFC], child window messages", "windows [MFC], message handlers", "child windows [MFC], messages"] -ms.assetid: fddfdd08-8ecf-4f84-8b45-5a84616aaa8d --- # Child Window Notification Message Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are five categories of child window notification messages: |Category|Description| diff --git a/docs/mfc/reference/chotkeyctrl-class.md b/docs/mfc/reference/chotkeyctrl-class.md index a442cd26c68..8b855d2303d 100644 --- a/docs/mfc/reference/chotkeyctrl-class.md +++ b/docs/mfc/reference/chotkeyctrl-class.md @@ -4,10 +4,12 @@ title: "CHotKeyCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CHotKeyCtrl", "AFXCMN/CHotKeyCtrl", "AFXCMN/CHotKeyCtrl::CHotKeyCtrl", "AFXCMN/CHotKeyCtrl::Create", "AFXCMN/CHotKeyCtrl::CreateEx", "AFXCMN/CHotKeyCtrl::GetHotKey", "AFXCMN/CHotKeyCtrl::GetHotKeyName", "AFXCMN/CHotKeyCtrl::GetKeyName", "AFXCMN/CHotKeyCtrl::SetHotKey", "AFXCMN/CHotKeyCtrl::SetRules"] helpviewer_keywords: ["CHotKeyCtrl [MFC], CHotKeyCtrl", "CHotKeyCtrl [MFC], Create", "CHotKeyCtrl [MFC], CreateEx", "CHotKeyCtrl [MFC], GetHotKey", "CHotKeyCtrl [MFC], GetHotKeyName", "CHotKeyCtrl [MFC], GetKeyName", "CHotKeyCtrl [MFC], SetHotKey", "CHotKeyCtrl [MFC], SetRules"] -ms.assetid: 896f9766-0718-4f58-aab2-20325e118ca6 --- # CHotKeyCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common hot key control. ## Syntax diff --git a/docs/mfc/reference/chtmleditctrl-class.md b/docs/mfc/reference/chtmleditctrl-class.md index 6a7e7c8c2a4..547bf0c9771 100644 --- a/docs/mfc/reference/chtmleditctrl-class.md +++ b/docs/mfc/reference/chtmleditctrl-class.md @@ -4,10 +4,12 @@ title: "CHtmlEditCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CHtmlEditCtrl", "AFXHTML/CHtmlEditCtrl", "AFXHTML/CHtmlEditCtrl::CHtmlEditCtrl", "AFXHTML/CHtmlEditCtrl::Create", "AFXHTML/CHtmlEditCtrl::GetDHtmlDocument", "AFXHTML/CHtmlEditCtrl::GetStartDocument"] helpviewer_keywords: ["CHtmlEditCtrl [MFC], CHtmlEditCtrl", "CHtmlEditCtrl [MFC], Create", "CHtmlEditCtrl [MFC], GetDHtmlDocument", "CHtmlEditCtrl [MFC], GetStartDocument"] -ms.assetid: 0fc4a238-b05f-4874-9edc-6a6701f064d9 --- # CHtmlEditCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the WebBrowser ActiveX control in an MFC window. ## Syntax diff --git a/docs/mfc/reference/chtmleditctrlbase-class.md b/docs/mfc/reference/chtmleditctrlbase-class.md index 084f3f0bed7..e092aa41d3f 100644 --- a/docs/mfc/reference/chtmleditctrlbase-class.md +++ b/docs/mfc/reference/chtmleditctrlbase-class.md @@ -4,10 +4,12 @@ title: "CHtmlEditCtrlBase Class" ms.date: "11/04/2016" f1_keywords: ["CHtmlEditCtrlBase", "AFXHTML/CHtmlEditCtrlBase", "AFXHTML/CHtmlEditCtrlBase::AddToGlyphTable", "AFXHTML/CHtmlEditCtrlBase::Bold", "AFXHTML/CHtmlEditCtrlBase::Button", "AFXHTML/CHtmlEditCtrlBase::CheckBox", "AFXHTML/CHtmlEditCtrlBase::ClearSelection", "AFXHTML/CHtmlEditCtrlBase::Copy", "AFXHTML/CHtmlEditCtrlBase::Cut", "AFXHTML/CHtmlEditCtrlBase::Delete", "AFXHTML/CHtmlEditCtrlBase::DropDownBox", "AFXHTML/CHtmlEditCtrlBase::EmptyGlyphTable", "AFXHTML/CHtmlEditCtrlBase::ExecCommand", "AFXHTML/CHtmlEditCtrlBase::Font", "AFXHTML/CHtmlEditCtrlBase::GetAbsolutePosition", "AFXHTML/CHtmlEditCtrlBase::GetBackColor", "AFXHTML/CHtmlEditCtrlBase::GetBlockFormat", "AFXHTML/CHtmlEditCtrlBase::GetBlockFormatNames", "AFXHTML/CHtmlEditCtrlBase::GetBookMark", "AFXHTML/CHtmlEditCtrlBase::GetDocument", "AFXHTML/CHtmlEditCtrlBase::GetDocumentHTML", "AFXHTML/CHtmlEditCtrlBase::GetDocumentTitle", "AFXHTML/CHtmlEditCtrlBase::GetEvent", "AFXHTML/CHtmlEditCtrlBase::GetEventSrcElement", "AFXHTML/CHtmlEditCtrlBase::GetFontFace", "AFXHTML/CHtmlEditCtrlBase::GetFontSize", "AFXHTML/CHtmlEditCtrlBase::GetForeColor", "AFXHTML/CHtmlEditCtrlBase::GetFrameZone", "AFXHTML/CHtmlEditCtrlBase::GetIsDirty", "AFXHTML/CHtmlEditCtrlBase::GetShowAlignedSiteTags", "AFXHTML/CHtmlEditCtrlBase::GetShowAllTags", "AFXHTML/CHtmlEditCtrlBase::GetShowAreaTags", "AFXHTML/CHtmlEditCtrlBase::GetShowBRTags", "AFXHTML/CHtmlEditCtrlBase::GetShowCommentTags", "AFXHTML/CHtmlEditCtrlBase::GetShowMiscTags", "AFXHTML/CHtmlEditCtrlBase::GetShowScriptTags", "AFXHTML/CHtmlEditCtrlBase::GetShowStyleTags", "AFXHTML/CHtmlEditCtrlBase::GetShowUnknownTags", "AFXHTML/CHtmlEditCtrlBase::HorizontalLine", "AFXHTML/CHtmlEditCtrlBase::HyperLink", "AFXHTML/CHtmlEditCtrlBase::IE50Paste", "AFXHTML/CHtmlEditCtrlBase::Iframe", "AFXHTML/CHtmlEditCtrlBase::Image", "AFXHTML/CHtmlEditCtrlBase::Indent", "AFXHTML/CHtmlEditCtrlBase::InsFieldSet", "AFXHTML/CHtmlEditCtrlBase::InsInputButton", "AFXHTML/CHtmlEditCtrlBase::InsInputHidden", "AFXHTML/CHtmlEditCtrlBase::InsInputImage", "AFXHTML/CHtmlEditCtrlBase::InsInputPassword", "AFXHTML/CHtmlEditCtrlBase::InsInputReset", "AFXHTML/CHtmlEditCtrlBase::InsInputSubmit", "AFXHTML/CHtmlEditCtrlBase::InsInputUpload", "AFXHTML/CHtmlEditCtrlBase::Is1DElement", "AFXHTML/CHtmlEditCtrlBase::Is2DElement", "AFXHTML/CHtmlEditCtrlBase::Italic", "AFXHTML/CHtmlEditCtrlBase::JustifyCenter", "AFXHTML/CHtmlEditCtrlBase::JustifyLeft", "AFXHTML/CHtmlEditCtrlBase::JustifyRight", "AFXHTML/CHtmlEditCtrlBase::ListBox", "AFXHTML/CHtmlEditCtrlBase::Marquee", "AFXHTML/CHtmlEditCtrlBase::NewDocument", "AFXHTML/CHtmlEditCtrlBase::OrderList", "AFXHTML/CHtmlEditCtrlBase::Outdent", "AFXHTML/CHtmlEditCtrlBase::Paragraph", "AFXHTML/CHtmlEditCtrlBase::Paste", "AFXHTML/CHtmlEditCtrlBase::PrintDocument", "AFXHTML/CHtmlEditCtrlBase::PrintPreview", "AFXHTML/CHtmlEditCtrlBase::QueryStatus", "AFXHTML/CHtmlEditCtrlBase::RadioButton", "AFXHTML/CHtmlEditCtrlBase::RefreshDocument", "AFXHTML/CHtmlEditCtrlBase::RemoveFormat", "AFXHTML/CHtmlEditCtrlBase::SaveAs", "AFXHTML/CHtmlEditCtrlBase::SelectAll", "AFXHTML/CHtmlEditCtrlBase::Set2DPosition", "AFXHTML/CHtmlEditCtrlBase::SetAbsolutePosition", "AFXHTML/CHtmlEditCtrlBase::SetAtomicSelection", "AFXHTML/CHtmlEditCtrlBase::SetAutoURLDetectMode", "AFXHTML/CHtmlEditCtrlBase::SetBackColor", "AFXHTML/CHtmlEditCtrlBase::SetBlockFormat", "AFXHTML/CHtmlEditCtrlBase::SetBookMark", "AFXHTML/CHtmlEditCtrlBase::SetCSSEditingLevel", "AFXHTML/CHtmlEditCtrlBase::SetDefaultComposeSettings", "AFXHTML/CHtmlEditCtrlBase::SetDesignMode", "AFXHTML/CHtmlEditCtrlBase::SetDisableEditFocusUI", "AFXHTML/CHtmlEditCtrlBase::SetDocumentHTML", "AFXHTML/CHtmlEditCtrlBase::SetFontFace", "AFXHTML/CHtmlEditCtrlBase::SetFontSize", "AFXHTML/CHtmlEditCtrlBase::SetForeColor", "AFXHTML/CHtmlEditCtrlBase::SetIE5PasteMode", "AFXHTML/CHtmlEditCtrlBase::SetLiveResize", "AFXHTML/CHtmlEditCtrlBase::SetMultiSelect", "AFXHTML/CHtmlEditCtrlBase::SetOverrideCursor", "AFXHTML/CHtmlEditCtrlBase::SetMode", "AFXHTML/CHtmlEditCtrlBase::SetRespectVisInDesign", "AFXHTML/CHtmlEditCtrlBase::SetShowAlignedSiteTags", "AFXHTML/CHtmlEditCtrlBase::SetShowAllTags", "AFXHTML/CHtmlEditCtrlBase::SetShowAreaTags", "AFXHTML/CHtmlEditCtrlBase::SetShowBRTags", "AFXHTML/CHtmlEditCtrlBase::SetShowCommentTags", "AFXHTML/CHtmlEditCtrlBase::SetShowMiscTags", "AFXHTML/CHtmlEditCtrlBase::SetShowScriptTags", "AFXHTML/CHtmlEditCtrlBase::SetShowStyleTags", "AFXHTML/CHtmlEditCtrlBase::SetShowUnknownTags", "AFXHTML/CHtmlEditCtrlBase::TextArea", "AFXHTML/CHtmlEditCtrlBase::TextBox", "AFXHTML/CHtmlEditCtrlBase::UnBookmark", "AFXHTML/CHtmlEditCtrlBase::Underline", "AFXHTML/CHtmlEditCtrlBase::Unlink", "AFXHTML/CHtmlEditCtrlBase::UnorderList"] helpviewer_keywords: ["CHtmlEditCtrlBase [MFC], AddToGlyphTable", "CHtmlEditCtrlBase [MFC], Bold", "CHtmlEditCtrlBase [MFC], Button", "CHtmlEditCtrlBase [MFC], CheckBox", "CHtmlEditCtrlBase [MFC], ClearSelection", "CHtmlEditCtrlBase [MFC], Copy", "CHtmlEditCtrlBase [MFC], Cut", "CHtmlEditCtrlBase [MFC], Delete", "CHtmlEditCtrlBase [MFC], DropDownBox", "CHtmlEditCtrlBase [MFC], EmptyGlyphTable", "CHtmlEditCtrlBase [MFC], ExecCommand", "CHtmlEditCtrlBase [MFC], Font", "CHtmlEditCtrlBase [MFC], GetAbsolutePosition", "CHtmlEditCtrlBase [MFC], GetBackColor", "CHtmlEditCtrlBase [MFC], GetBlockFormat", "CHtmlEditCtrlBase [MFC], GetBlockFormatNames", "CHtmlEditCtrlBase [MFC], GetBookMark", "CHtmlEditCtrlBase [MFC], GetDocument", "CHtmlEditCtrlBase [MFC], GetDocumentHTML", "CHtmlEditCtrlBase [MFC], GetDocumentTitle", "CHtmlEditCtrlBase [MFC], GetEvent", "CHtmlEditCtrlBase [MFC], GetEventSrcElement", "CHtmlEditCtrlBase [MFC], GetFontFace", "CHtmlEditCtrlBase [MFC], GetFontSize", "CHtmlEditCtrlBase [MFC], GetForeColor", "CHtmlEditCtrlBase [MFC], GetFrameZone", "CHtmlEditCtrlBase [MFC], GetIsDirty", "CHtmlEditCtrlBase [MFC], GetShowAlignedSiteTags", "CHtmlEditCtrlBase [MFC], GetShowAllTags", "CHtmlEditCtrlBase [MFC], GetShowAreaTags", "CHtmlEditCtrlBase [MFC], GetShowBRTags", "CHtmlEditCtrlBase [MFC], GetShowCommentTags", "CHtmlEditCtrlBase [MFC], GetShowMiscTags", "CHtmlEditCtrlBase [MFC], GetShowScriptTags", "CHtmlEditCtrlBase [MFC], GetShowStyleTags", "CHtmlEditCtrlBase [MFC], GetShowUnknownTags", "CHtmlEditCtrlBase [MFC], HorizontalLine", "CHtmlEditCtrlBase [MFC], HyperLink", "CHtmlEditCtrlBase [MFC], IE50Paste", "CHtmlEditCtrlBase [MFC], Iframe", "CHtmlEditCtrlBase [MFC], Image", "CHtmlEditCtrlBase [MFC], Indent", "CHtmlEditCtrlBase [MFC], InsFieldSet", "CHtmlEditCtrlBase [MFC], InsInputButton", "CHtmlEditCtrlBase [MFC], InsInputHidden", "CHtmlEditCtrlBase [MFC], InsInputImage", "CHtmlEditCtrlBase [MFC], InsInputPassword", "CHtmlEditCtrlBase [MFC], InsInputReset", "CHtmlEditCtrlBase [MFC], InsInputSubmit", "CHtmlEditCtrlBase [MFC], InsInputUpload", "CHtmlEditCtrlBase [MFC], Is1DElement", "CHtmlEditCtrlBase [MFC], Is2DElement", "CHtmlEditCtrlBase [MFC], Italic", "CHtmlEditCtrlBase [MFC], JustifyCenter", "CHtmlEditCtrlBase [MFC], JustifyLeft", "CHtmlEditCtrlBase [MFC], JustifyRight", "CHtmlEditCtrlBase [MFC], ListBox", "CHtmlEditCtrlBase [MFC], Marquee", "CHtmlEditCtrlBase [MFC], NewDocument", "CHtmlEditCtrlBase [MFC], OrderList", "CHtmlEditCtrlBase [MFC], Outdent", "CHtmlEditCtrlBase [MFC], Paragraph", "CHtmlEditCtrlBase [MFC], Paste", "CHtmlEditCtrlBase [MFC], PrintDocument", "CHtmlEditCtrlBase [MFC], PrintPreview", "CHtmlEditCtrlBase [MFC], QueryStatus", "CHtmlEditCtrlBase [MFC], RadioButton", "CHtmlEditCtrlBase [MFC], RefreshDocument", "CHtmlEditCtrlBase [MFC], RemoveFormat", "CHtmlEditCtrlBase [MFC], SaveAs", "CHtmlEditCtrlBase [MFC], SelectAll", "CHtmlEditCtrlBase [MFC], Set2DPosition", "CHtmlEditCtrlBase [MFC], SetAbsolutePosition", "CHtmlEditCtrlBase [MFC], SetAtomicSelection", "CHtmlEditCtrlBase [MFC], SetAutoURLDetectMode", "CHtmlEditCtrlBase [MFC], SetBackColor", "CHtmlEditCtrlBase [MFC], SetBlockFormat", "CHtmlEditCtrlBase [MFC], SetBookMark", "CHtmlEditCtrlBase [MFC], SetCSSEditingLevel", "CHtmlEditCtrlBase [MFC], SetDefaultComposeSettings", "CHtmlEditCtrlBase [MFC], SetDesignMode", "CHtmlEditCtrlBase [MFC], SetDisableEditFocusUI", "CHtmlEditCtrlBase [MFC], SetDocumentHTML", "CHtmlEditCtrlBase [MFC], SetFontFace", "CHtmlEditCtrlBase [MFC], SetFontSize", "CHtmlEditCtrlBase [MFC], SetForeColor", "CHtmlEditCtrlBase [MFC], SetIE5PasteMode", "CHtmlEditCtrlBase [MFC], SetLiveResize", "CHtmlEditCtrlBase [MFC], SetMultiSelect", "CHtmlEditCtrlBase [MFC], SetOverrideCursor", "CHtmlEditCtrlBase [MFC], SetOverwriteMode", "CHtmlEditCtrlBase [MFC], SetRespectVisInDesign", "CHtmlEditCtrlBase [MFC], SetShowAlignedSiteTags", "CHtmlEditCtrlBase [MFC], SetShowAllTags", "CHtmlEditCtrlBase [MFC], SetShowAreaTags", "CHtmlEditCtrlBase [MFC], SetShowBRTags", "CHtmlEditCtrlBase [MFC], SetShowCommentTags", "CHtmlEditCtrlBase [MFC], SetShowMiscTags", "CHtmlEditCtrlBase [MFC], SetShowScriptTags", "CHtmlEditCtrlBase [MFC], SetShowStyleTags", "CHtmlEditCtrlBase [MFC], SetShowUnknownTags", "CHtmlEditCtrlBase [MFC], TextArea", "CHtmlEditCtrlBase [MFC], TextBox", "CHtmlEditCtrlBase [MFC], UnBookmark", "CHtmlEditCtrlBase [MFC], Underline", "CHtmlEditCtrlBase [MFC], Unlink", "CHtmlEditCtrlBase [MFC], UnorderList"] -ms.assetid: e0cc74b4-8320-4570-b673-16c03d2ae266 --- # CHtmlEditCtrlBase Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an HTML editing component. ## Syntax diff --git a/docs/mfc/reference/chtmleditdoc-class.md b/docs/mfc/reference/chtmleditdoc-class.md index 0e5251f0434..309a4e8901a 100644 --- a/docs/mfc/reference/chtmleditdoc-class.md +++ b/docs/mfc/reference/chtmleditdoc-class.md @@ -4,10 +4,12 @@ title: "CHtmlEditDoc Class" ms.date: "11/04/2016" f1_keywords: ["CHtmlEditDoc", "AFXHTML/CHtmlEditDoc", "AFXHTML/CHtmlEditDoc::CHtmlEditDoc", "AFXHTML/CHtmlEditDoc::GetView", "AFXHTML/CHtmlEditDoc::IsModified", "AFXHTML/CHtmlEditDoc::OpenURL"] helpviewer_keywords: ["CHtmlEditDoc [MFC], CHtmlEditDoc", "CHtmlEditDoc [MFC], GetView", "CHtmlEditDoc [MFC], IsModified", "CHtmlEditDoc [MFC], OpenURL"] -ms.assetid: b2cca61f-e5d6-4099-b0d1-46bf85f0bd64 --- # CHtmlEditDoc Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + With [CHtmlEditView](../../mfc/reference/chtmleditview-class.md), provides the functionality of the WebBrowser editing platform within the context of the MFC document-view architecture. ## Syntax diff --git a/docs/mfc/reference/chtmleditview-class.md b/docs/mfc/reference/chtmleditview-class.md index f636ef74ab1..0813a65f6bb 100644 --- a/docs/mfc/reference/chtmleditview-class.md +++ b/docs/mfc/reference/chtmleditview-class.md @@ -4,10 +4,12 @@ title: "CHtmlEditView Class" ms.date: "11/04/2016" f1_keywords: ["CHtmlEditView", "AFXHTML/CHtmlEditView", "AFXHTML/CHtmlEditView::CHtmlEditView", "AFXHTML/CHtmlEditView::Create", "AFXHTML/CHtmlEditView::GetDHtmlDocument", "AFXHTML/CHtmlEditView::GetStartDocument"] helpviewer_keywords: ["CHtmlEditView [MFC], CHtmlEditView", "CHtmlEditView [MFC], Create", "CHtmlEditView [MFC], GetDHtmlDocument", "CHtmlEditView [MFC], GetStartDocument"] -ms.assetid: 166c8ba8-3fb5-4dd7-a9ea-5bca662d00f6 --- # CHtmlEditView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the WebBrowser editing platform within the context of MFC's document/view architecture. ## Syntax diff --git a/docs/mfc/reference/chtmlview-class.md b/docs/mfc/reference/chtmlview-class.md index 28ae4d50120..1a173311fc6 100644 --- a/docs/mfc/reference/chtmlview-class.md +++ b/docs/mfc/reference/chtmlview-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CHtmlView [MFC], Create", "CHtmlView [MFC], CreateControl --- # `CHtmlView` class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the WebBrowser control within the context of MFC's document/view architecture. ## Syntax @@ -599,7 +602,7 @@ BOOL GetSilent() const; ### Return Value -Nonzero if dialog boxes can’t be displayed from the WebBrowser control; otherwise zero. +Nonzero if dialog boxes can't be displayed from the WebBrowser control; otherwise zero. ### Remarks diff --git a/docs/mfc/reference/chttpconnection-class.md b/docs/mfc/reference/chttpconnection-class.md index 04a22df5849..f8d4f1d7f87 100644 --- a/docs/mfc/reference/chttpconnection-class.md +++ b/docs/mfc/reference/chttpconnection-class.md @@ -4,10 +4,12 @@ title: "CHttpConnection Class" ms.date: "03/27/2019" f1_keywords: ["CHttpConnection", "AFXINET/CHttpConnection", "AFXINET/CHttpConnection::CHttpConnection", "AFXINET/CHttpConnection::OpenRequest"] helpviewer_keywords: ["CHttpConnection [MFC], CHttpConnection", "CHttpConnection [MFC], OpenRequest"] -ms.assetid: a402b662-c445-4988-800d-c8278551babe --- # CHttpConnection Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages your connection to an HTTP server. ## Syntax diff --git a/docs/mfc/reference/chttpfile-class.md b/docs/mfc/reference/chttpfile-class.md index 63ab4b55b7b..e6fac4c2b68 100644 --- a/docs/mfc/reference/chttpfile-class.md +++ b/docs/mfc/reference/chttpfile-class.md @@ -4,10 +4,12 @@ title: "CHttpFile Class" ms.date: "11/04/2016" f1_keywords: ["CHttpFile", "AFXINET/CHttpFile", "AFXINET/CHttpFile::CHttpFile", "AFXINET/CHttpFile::AddRequestHeaders", "AFXINET/CHttpFile::EndRequest", "AFXINET/CHttpFile::GetFileURL", "AFXINET/CHttpFile::GetObject", "AFXINET/CHttpFile::GetVerb", "AFXINET/CHttpFile::QueryInfo", "AFXINET/CHttpFile::QueryInfoStatusCode", "AFXINET/CHttpFile::SendRequest", "AFXINET/CHttpFile::SendRequestEx"] helpviewer_keywords: ["CHttpFile [MFC], CHttpFile", "CHttpFile [MFC], AddRequestHeaders", "CHttpFile [MFC], EndRequest", "CHttpFile [MFC], GetFileURL", "CHttpFile [MFC], GetObject", "CHttpFile [MFC], GetVerb", "CHttpFile [MFC], QueryInfo", "CHttpFile [MFC], QueryInfoStatusCode", "CHttpFile [MFC], SendRequest", "CHttpFile [MFC], SendRequestEx"] -ms.assetid: 399e7c68-bbce-4374-8c55-206e9c7baac6 --- # CHttpFile Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality to request and read files on an HTTP server. ## Syntax diff --git a/docs/mfc/reference/chwndrendertarget-class.md b/docs/mfc/reference/chwndrendertarget-class.md index 540b28ca338..a55070e729a 100644 --- a/docs/mfc/reference/chwndrendertarget-class.md +++ b/docs/mfc/reference/chwndrendertarget-class.md @@ -4,10 +4,12 @@ title: "CHwndRenderTarget Class" ms.date: "11/04/2016" f1_keywords: ["CHwndRenderTarget", "AFXRENDERTARGET/CHwndRenderTarget", "AFXRENDERTARGET/CHwndRenderTarget::CHwndRenderTarget", "AFXRENDERTARGET/CHwndRenderTarget::Attach", "AFXRENDERTARGET/CHwndRenderTarget::CheckWindowState", "AFXRENDERTARGET/CHwndRenderTarget::Create", "AFXRENDERTARGET/CHwndRenderTarget::Detach", "AFXRENDERTARGET/CHwndRenderTarget::GetHwnd", "AFXRENDERTARGET/CHwndRenderTarget::GetHwndRenderTarget", "AFXRENDERTARGET/CHwndRenderTarget::ReCreate", "AFXRENDERTARGET/CHwndRenderTarget::Resize", "AFXRENDERTARGET/CHwndRenderTarget::m_pHwndRenderTarget"] helpviewer_keywords: ["CHwndRenderTarget [MFC], CHwndRenderTarget", "CHwndRenderTarget [MFC], Attach", "CHwndRenderTarget [MFC], CheckWindowState", "CHwndRenderTarget [MFC], Create", "CHwndRenderTarget [MFC], Detach", "CHwndRenderTarget [MFC], GetHwnd", "CHwndRenderTarget [MFC], GetHwndRenderTarget", "CHwndRenderTarget [MFC], ReCreate", "CHwndRenderTarget [MFC], Resize", "CHwndRenderTarget [MFC], m_pHwndRenderTarget"] -ms.assetid: aa65b69f-7202-46ea-af81-ef325da0b840 --- # CHwndRenderTarget Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1HwndRenderTarget. ## Syntax diff --git a/docs/mfc/reference/cimagelist-class.md b/docs/mfc/reference/cimagelist-class.md index 184a95db737..74324b18e4a 100644 --- a/docs/mfc/reference/cimagelist-class.md +++ b/docs/mfc/reference/cimagelist-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common image list control. ## Syntax @@ -359,7 +361,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/cinstantaneoustransition-class.md b/docs/mfc/reference/cinstantaneoustransition-class.md index 3ae206b69ab..052761c2868 100644 --- a/docs/mfc/reference/cinstantaneoustransition-class.md +++ b/docs/mfc/reference/cinstantaneoustransition-class.md @@ -4,10 +4,12 @@ title: "CInstantaneousTransition Class" ms.date: "11/04/2016" f1_keywords: ["CInstantaneousTransition", "AFXANIMATIONCONTROLLER/CInstantaneousTransition", "AFXANIMATIONCONTROLLER/CInstantaneousTransition::CInstantaneousTransition", "AFXANIMATIONCONTROLLER/CInstantaneousTransition::Create", "AFXANIMATIONCONTROLLER/CInstantaneousTransition::m_dblFinalValue"] helpviewer_keywords: ["CInstantaneousTransition [MFC], CInstantaneousTransition", "CInstantaneousTransition [MFC], Create", "CInstantaneousTransition [MFC], m_dblFinalValue"] -ms.assetid: c3d5121f-2c6b-4221-9e57-10e082a31120 --- # CInstantaneousTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates an instantaneous transition. ## Syntax diff --git a/docs/mfc/reference/cinternetconnection-class.md b/docs/mfc/reference/cinternetconnection-class.md index 0673cfd4de8..bc22af6454b 100644 --- a/docs/mfc/reference/cinternetconnection-class.md +++ b/docs/mfc/reference/cinternetconnection-class.md @@ -4,10 +4,12 @@ title: "CInternetConnection Class" ms.date: "11/04/2016" f1_keywords: ["CInternetConnection", "AFXINET/CInternetConnection", "AFXINET/CInternetConnection::CInternetConnection", "AFXINET/CInternetConnection::GetContext", "AFXINET/CInternetConnection::GetServerName", "AFXINET/CInternetConnection::GetSession"] helpviewer_keywords: ["CInternetConnection [MFC], CInternetConnection", "CInternetConnection [MFC], GetContext", "CInternetConnection [MFC], GetServerName", "CInternetConnection [MFC], GetSession"] -ms.assetid: 62a5d1c3-8471-4e36-a064-48831829b2a7 --- # CInternetConnection Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages your connection to an Internet server. ## Syntax diff --git a/docs/mfc/reference/cinternetexception-class.md b/docs/mfc/reference/cinternetexception-class.md index 9d9ccae4624..8b6ea3e8409 100644 --- a/docs/mfc/reference/cinternetexception-class.md +++ b/docs/mfc/reference/cinternetexception-class.md @@ -4,10 +4,12 @@ title: "CInternetException Class" ms.date: "11/04/2016" f1_keywords: ["CInternetException", "AFXINET/CInternetException", "AFXINET/CInternetException::CInternetException", "AFXINET/CInternetException::m_dwContext", "AFXINET/CInternetException::m_dwError"] helpviewer_keywords: ["CInternetException [MFC], CInternetException", "CInternetException [MFC], m_dwContext", "CInternetException [MFC], m_dwError"] -ms.assetid: 44fb3cbe-523e-4754-8843-a77909990b14 --- # CInternetException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an exception condition related to an Internet operation. ## Syntax @@ -90,7 +92,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/cinternetfile-class.md b/docs/mfc/reference/cinternetfile-class.md index 6e30d78c6bc..b8dc86a17a3 100644 --- a/docs/mfc/reference/cinternetfile-class.md +++ b/docs/mfc/reference/cinternetfile-class.md @@ -4,10 +4,12 @@ title: "CInternetFile Class" ms.date: "11/04/2016" f1_keywords: ["CInternetFile", "AFXINET/CInternetFile", "AFXINET/CInternetFile::CInternetFile", "AFXINET/CInternetFile::Abort", "AFXINET/CInternetFile::Close", "AFXINET/CInternetFile::Flush", "AFXINET/CInternetFile::GetLength", "AFXINET/CInternetFile::Read", "AFXINET/CInternetFile::ReadString", "AFXINET/CInternetFile::Seek", "AFXINET/CInternetFile::SetReadBufferSize", "AFXINET/CInternetFile::SetWriteBufferSize", "AFXINET/CInternetFile::Write", "AFXINET/CInternetFile::WriteString", "AFXINET/CInternetFile::m_hFile"] helpviewer_keywords: ["CInternetFile [MFC], CInternetFile", "CInternetFile [MFC], Abort", "CInternetFile [MFC], Close", "CInternetFile [MFC], Flush", "CInternetFile [MFC], GetLength", "CInternetFile [MFC], Read", "CInternetFile [MFC], ReadString", "CInternetFile [MFC], Seek", "CInternetFile [MFC], SetReadBufferSize", "CInternetFile [MFC], SetWriteBufferSize", "CInternetFile [MFC], Write", "CInternetFile [MFC], WriteString", "CInternetFile [MFC], m_hFile"] -ms.assetid: 96935681-ee71-4a8d-9783-5abc7b3e6f10 --- # CInternetFile Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows access to files on remote systems that use Internet protocols. ## Syntax diff --git a/docs/mfc/reference/cinternetsession-class.md b/docs/mfc/reference/cinternetsession-class.md index c45d10ff9c3..4ed84687949 100644 --- a/docs/mfc/reference/cinternetsession-class.md +++ b/docs/mfc/reference/cinternetsession-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CInternetSession` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Creates and initializes a single or several simultaneous Internet sessions and, if necessary, describes your connection to a proxy server. ## Syntax @@ -72,7 +75,7 @@ For more information about basic Internet programming tasks, see the article [In ## Inheritance Hierarchy [`CObject`](../../mfc/reference/cobject-class.md)\ -    `CInternetSession` + `CInternetSession` ## Requirements @@ -169,7 +172,7 @@ When handling status callback, you can provide status about the progress of the Because callbacks occur during the request's processing, the application should spend as little time as possible in the callback to prevent degradation of data throughput to the network. For example, putting up a dialog box in a callback may be such a lengthy operation that the server terminates the request. -The status callback can’t be removed as long as any callbacks are pending. +The status callback can't be removed as long as any callbacks are pending. To handle any operations asynchronously, you must either create your own thread or use the WinInet functions without MFC. @@ -540,7 +543,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/cinterpolatorbase-class.md b/docs/mfc/reference/cinterpolatorbase-class.md index 3d8cced609b..93648302073 100644 --- a/docs/mfc/reference/cinterpolatorbase-class.md +++ b/docs/mfc/reference/cinterpolatorbase-class.md @@ -4,10 +4,12 @@ title: "CInterpolatorBase Class" ms.date: "11/04/2016" f1_keywords: ["CInterpolatorBase", "AFXANIMATIONCONTROLLER/CInterpolatorBase", "AFXANIMATIONCONTROLLER/CInterpolatorBase::CInterpolatorBase", "AFXANIMATIONCONTROLLER/CInterpolatorBase::CreateInstance", "AFXANIMATIONCONTROLLER/CInterpolatorBase::GetDependencies", "AFXANIMATIONCONTROLLER/CInterpolatorBase::GetDuration", "AFXANIMATIONCONTROLLER/CInterpolatorBase::GetFinalValue", "AFXANIMATIONCONTROLLER/CInterpolatorBase::InterpolateValue", "AFXANIMATIONCONTROLLER/CInterpolatorBase::InterpolateVelocity", "AFXANIMATIONCONTROLLER/CInterpolatorBase::SetCustomInterpolator", "AFXANIMATIONCONTROLLER/CInterpolatorBase::SetDuration", "AFXANIMATIONCONTROLLER/CInterpolatorBase::SetInitialValueAndVelocity"] helpviewer_keywords: ["CInterpolatorBase [MFC], CInterpolatorBase", "CInterpolatorBase [MFC], CreateInstance", "CInterpolatorBase [MFC], GetDependencies", "CInterpolatorBase [MFC], GetDuration", "CInterpolatorBase [MFC], GetFinalValue", "CInterpolatorBase [MFC], InterpolateValue", "CInterpolatorBase [MFC], InterpolateVelocity", "CInterpolatorBase [MFC], SetCustomInterpolator", "CInterpolatorBase [MFC], SetDuration", "CInterpolatorBase [MFC], SetInitialValueAndVelocity"] -ms.assetid: bbc3dce7-8398-47f9-b97e-e4fd2d737232 --- # CInterpolatorBase Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a callback, which is called by the Animation API when it has to calculate a new value of an animation variable. ## Syntax diff --git a/docs/mfc/reference/cinvalidargexception-class.md b/docs/mfc/reference/cinvalidargexception-class.md index 938e2630fbe..3efef73e2d8 100644 --- a/docs/mfc/reference/cinvalidargexception-class.md +++ b/docs/mfc/reference/cinvalidargexception-class.md @@ -4,10 +4,12 @@ title: "CInvalidArgException Class" ms.date: "11/04/2016" f1_keywords: ["CInvalidArgException", "AFX/CInvalidArgException", "AFX/CInvalidArgException::CInvalidArgException"] helpviewer_keywords: ["CInvalidArgException [MFC], CInvalidArgException"] -ms.assetid: e43d7c67-1157-47f8-817a-804083e8186e --- # CInvalidArgException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This class represents an invalid argument exception condition. ## Syntax diff --git a/docs/mfc/reference/cipaddressctrl-class.md b/docs/mfc/reference/cipaddressctrl-class.md index 859832b3e2e..6e0287d3989 100644 --- a/docs/mfc/reference/cipaddressctrl-class.md +++ b/docs/mfc/reference/cipaddressctrl-class.md @@ -4,10 +4,12 @@ title: "CIPAddressCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CIPAddressCtrl", "AFXCMN/CIPAddressCtrl", "AFXCMN/CIPAddressCtrl::CIPAddressCtrl", "AFXCMN/CIPAddressCtrl::ClearAddress", "AFXCMN/CIPAddressCtrl::Create", "AFXCMN/CIPAddressCtrl::CreateEx", "AFXCMN/CIPAddressCtrl::GetAddress", "AFXCMN/CIPAddressCtrl::IsBlank", "AFXCMN/CIPAddressCtrl::SetAddress", "AFXCMN/CIPAddressCtrl::SetFieldFocus", "AFXCMN/CIPAddressCtrl::SetFieldRange"] helpviewer_keywords: ["CIPAddressCtrl [MFC], CIPAddressCtrl", "CIPAddressCtrl [MFC], ClearAddress", "CIPAddressCtrl [MFC], Create", "CIPAddressCtrl [MFC], CreateEx", "CIPAddressCtrl [MFC], GetAddress", "CIPAddressCtrl [MFC], IsBlank", "CIPAddressCtrl [MFC], SetAddress", "CIPAddressCtrl [MFC], SetFieldFocus", "CIPAddressCtrl [MFC], SetFieldRange"] -ms.assetid: 9764d2f4-cb14-4ba8-b799-7f57a55a47c6 --- # CIPAddressCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common IP Address control. ## Syntax diff --git a/docs/mfc/reference/cjumplist-class.md b/docs/mfc/reference/cjumplist-class.md index e924d7a4a7c..140ef4a93e0 100644 --- a/docs/mfc/reference/cjumplist-class.md +++ b/docs/mfc/reference/cjumplist-class.md @@ -4,10 +4,12 @@ title: "CJumpList Class" ms.date: "03/27/2019" f1_keywords: ["CJumpList", "AFXADV/CJumpList", "AFXADV/CJumpList::CJumpList", "AFXADV/CJumpList::AbortList", "AFXADV/CJumpList::AddDestination", "AFXADV/CJumpList::AddKnownCategory", "AFXADV/CJumpList::AddTask", "AFXADV/CJumpList::AddTasks", "AFXADV/CJumpList::AddTaskSeparator", "AFXADV/CJumpList::ClearAll", "AFXADV/CJumpList::ClearAllDestinations", "AFXADV/CJumpList::CommitList", "AFXADV/CJumpList::GetDestinationList", "AFXADV/CJumpList::GetMaxSlots", "AFXADV/CJumpList::GetRemovedItems", "AFXADV/CJumpList::InitializeList", "AFXADV/CJumpList::SetAppID"] helpviewer_keywords: ["CJumpList [MFC], CJumpList", "CJumpList [MFC], AbortList", "CJumpList [MFC], AddDestination", "CJumpList [MFC], AddKnownCategory", "CJumpList [MFC], AddTask", "CJumpList [MFC], AddTasks", "CJumpList [MFC], AddTaskSeparator", "CJumpList [MFC], ClearAll", "CJumpList [MFC], ClearAllDestinations", "CJumpList [MFC], CommitList", "CJumpList [MFC], GetDestinationList", "CJumpList [MFC], GetMaxSlots", "CJumpList [MFC], GetRemovedItems", "CJumpList [MFC], InitializeList", "CJumpList [MFC], SetAppID"] -ms.assetid: d364d27e-f512-4b12-9872-c2a17c78ab1f --- # CJumpList Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A `CJumpList` is the list of shortcuts revealed when you right-click on an icon in the task bar. ## Syntax diff --git a/docs/mfc/reference/ckeyboardmanager-class.md b/docs/mfc/reference/ckeyboardmanager-class.md index 028992b0d67..19cfdf860e3 100644 --- a/docs/mfc/reference/ckeyboardmanager-class.md +++ b/docs/mfc/reference/ckeyboardmanager-class.md @@ -4,10 +4,12 @@ title: "CKeyboardManager Class" ms.date: "11/04/2016" f1_keywords: ["CKeyboardManager", "AFXKEYBOARDMANAGER/CKeyboardManager", "AFXKEYBOARDMANAGER/CKeyboardManager::CKeyboardManager", "AFXKEYBOARDMANAGER/CKeyboardManager::CleanUp", "AFXKEYBOARDMANAGER/CKeyboardManager::FindDefaultAccelerator", "AFXKEYBOARDMANAGER/CKeyboardManager::IsKeyHandled", "AFXKEYBOARDMANAGER/CKeyboardManager::IsKeyPrintable", "AFXKEYBOARDMANAGER/CKeyboardManager::IsShowAllAccelerators", "AFXKEYBOARDMANAGER/CKeyboardManager::LoadState", "AFXKEYBOARDMANAGER/CKeyboardManager::ResetAll", "AFXKEYBOARDMANAGER/CKeyboardManager::SaveState", "AFXKEYBOARDMANAGER/CKeyboardManager::ShowAllAccelerators", "AFXKEYBOARDMANAGER/CKeyboardManager::TranslateCharToUpper", "AFXKEYBOARDMANAGER/CKeyboardManager::UpdateAccelTable"] helpviewer_keywords: ["CKeyboardManager [MFC], CKeyboardManager", "CKeyboardManager [MFC], CleanUp", "CKeyboardManager [MFC], FindDefaultAccelerator", "CKeyboardManager [MFC], IsKeyHandled", "CKeyboardManager [MFC], IsKeyPrintable", "CKeyboardManager [MFC], IsShowAllAccelerators", "CKeyboardManager [MFC], LoadState", "CKeyboardManager [MFC], ResetAll", "CKeyboardManager [MFC], SaveState", "CKeyboardManager [MFC], ShowAllAccelerators", "CKeyboardManager [MFC], TranslateCharToUpper", "CKeyboardManager [MFC], UpdateAccelTable"] -ms.assetid: 4809ece6-89df-4479-8b53-9bf476ee107b --- # CKeyboardManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages shortcut key tables for the main frame window and child frame windows. ## Syntax diff --git a/docs/mfc/reference/ckeyframe-class.md b/docs/mfc/reference/ckeyframe-class.md index 295550b2edc..fab2e6461a0 100644 --- a/docs/mfc/reference/ckeyframe-class.md +++ b/docs/mfc/reference/ckeyframe-class.md @@ -4,10 +4,12 @@ title: "CKeyFrame Class" ms.date: "11/04/2016" f1_keywords: ["CKeyFrame", "AFXANIMATIONCONTROLLER/CKeyFrame", "AFXANIMATIONCONTROLLER/CKeyFrame::CKeyFrame", "AFXANIMATIONCONTROLLER/CKeyFrame::AddToStoryboard", "AFXANIMATIONCONTROLLER/CKeyFrame::AddToStoryboardAfterTransition", "AFXANIMATIONCONTROLLER/CKeyFrame::AddToStoryboardAtOffset", "AFXANIMATIONCONTROLLER/CKeyFrame::GetExistingKeyframe", "AFXANIMATIONCONTROLLER/CKeyFrame::GetOffset", "AFXANIMATIONCONTROLLER/CKeyFrame::GetTransition", "AFXANIMATIONCONTROLLER/CKeyFrame::m_offset", "AFXANIMATIONCONTROLLER/CKeyFrame::m_pExistingKeyFrame", "AFXANIMATIONCONTROLLER/CKeyFrame::m_pTransition"] helpviewer_keywords: ["CKeyFrame [MFC], CKeyFrame", "CKeyFrame [MFC], AddToStoryboard", "CKeyFrame [MFC], AddToStoryboardAfterTransition", "CKeyFrame [MFC], AddToStoryboardAtOffset", "CKeyFrame [MFC], GetExistingKeyframe", "CKeyFrame [MFC], GetOffset", "CKeyFrame [MFC], GetTransition", "CKeyFrame [MFC], m_offset", "CKeyFrame [MFC], m_pExistingKeyFrame", "CKeyFrame [MFC], m_pTransition"] -ms.assetid: d050a562-20f6-4c65-8ce5-ccb3aef1a20e --- # CKeyFrame Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an animation keyframe. ## Syntax diff --git a/docs/mfc/reference/class-factories-and-licensing.md b/docs/mfc/reference/class-factories-and-licensing.md index fb570c46f96..eb2f2f98254 100644 --- a/docs/mfc/reference/class-factories-and-licensing.md +++ b/docs/mfc/reference/class-factories-and-licensing.md @@ -3,10 +3,12 @@ description: "Learn more about: Class Factories and Licensing" title: "Class Factories and Licensing" ms.date: "11/04/2016" helpviewer_keywords: ["class factories [MFC], and licensing"] -ms.assetid: 53c4856a-4062-46db-9f69-dd4339f746b3 --- # Class Factories and Licensing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To create an instance of your OLE control, a container application calls a member function of the control's class factory. Because your control is an actual OLE object, the class factory is responsible for creating instances of your control. Every OLE control class must have a class factory. Another important feature of OLE controls is their ability to enforce a license. ControlWizard allows you to incorporate licensing during the creation of your control project. For more information on control licensing, see the article [ActiveX Controls: Licensing An ActiveX Control](../../mfc/mfc-activex-controls-licensing-an-activex-control.md). diff --git a/docs/mfc/reference/classes-and-functions-generated-by-the-mfc-dll-wizard.md b/docs/mfc/reference/classes-and-functions-generated-by-the-mfc-dll-wizard.md index 8a8852ea8bd..c0db5403493 100644 --- a/docs/mfc/reference/classes-and-functions-generated-by-the-mfc-dll-wizard.md +++ b/docs/mfc/reference/classes-and-functions-generated-by-the-mfc-dll-wizard.md @@ -3,10 +3,12 @@ description: "Learn more about: Classes and Functions Generated by the MFC DLL W title: "Classes and Functions Generated by the MFC DLL Wizard" ms.date: "11/04/2016" helpviewer_keywords: ["functions [MFC]", "functions [MFC], DLLs", "MFC DLL Wizard", "DLLs [MFC], wizard classes and functions", "classes [MFC], generated by MFC DLL wizard", "code [MFC], generated by MFC DLL wizard"] -ms.assetid: e69e62fe-4953-42bf-a2fc-50bbf9bdaeaf --- # Classes and Functions Generated by the MFC DLL Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The code that the MFC DLL Wizard generates depends on the kind of DLL you are creating and the options you have selected. The MFC DLL Wizard generates the same code for both forms of regular MFC DLLs. |Kind of DLL|Option|Classes|Functions| diff --git a/docs/mfc/reference/clineartransition-class.md b/docs/mfc/reference/clineartransition-class.md index db00d95751a..4fc9741cd95 100644 --- a/docs/mfc/reference/clineartransition-class.md +++ b/docs/mfc/reference/clineartransition-class.md @@ -4,10 +4,12 @@ title: "CLinearTransition Class" ms.date: "11/04/2016" f1_keywords: ["CLinearTransition", "AFXANIMATIONCONTROLLER/CLinearTransition", "AFXANIMATIONCONTROLLER/CLinearTransition::CLinearTransition", "AFXANIMATIONCONTROLLER/CLinearTransition::Create", "AFXANIMATIONCONTROLLER/CLinearTransition::m_dblFinalValue", "AFXANIMATIONCONTROLLER/CLinearTransition::m_duration"] helpviewer_keywords: ["CLinearTransition [MFC], CLinearTransition", "CLinearTransition [MFC], Create", "CLinearTransition [MFC], m_dblFinalValue", "CLinearTransition [MFC], m_duration"] -ms.assetid: 7fcb2dba-beb8-4933-9f5d-3b7fb1585ef0 --- # CLinearTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a linear transition. ## Syntax diff --git a/docs/mfc/reference/clineartransitionfromspeed-class.md b/docs/mfc/reference/clineartransitionfromspeed-class.md index 543e8eb4232..7054525da73 100644 --- a/docs/mfc/reference/clineartransitionfromspeed-class.md +++ b/docs/mfc/reference/clineartransitionfromspeed-class.md @@ -4,10 +4,12 @@ title: "CLinearTransitionFromSpeed Class" ms.date: "11/04/2016" f1_keywords: ["CLinearTransitionFromSpeed", "AFXANIMATIONCONTROLLER/CLinearTransitionFromSpeed", "AFXANIMATIONCONTROLLER/CLinearTransitionFromSpeed::CLinearTransitionFromSpeed", "AFXANIMATIONCONTROLLER/CLinearTransitionFromSpeed::Create", "AFXANIMATIONCONTROLLER/CLinearTransitionFromSpeed::m_dblFinalValue", "AFXANIMATIONCONTROLLER/CLinearTransitionFromSpeed::m_dblSpeed"] helpviewer_keywords: ["CLinearTransitionFromSpeed [MFC], CLinearTransitionFromSpeed", "CLinearTransitionFromSpeed [MFC], Create", "CLinearTransitionFromSpeed [MFC], m_dblFinalValue", "CLinearTransitionFromSpeed [MFC], m_dblSpeed"] -ms.assetid: 8f159a1c-8893-4017-951e-09e5758aba7d --- # CLinearTransitionFromSpeed Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a linear-speed transition. ## Syntax diff --git a/docs/mfc/reference/clinkctrl-class.md b/docs/mfc/reference/clinkctrl-class.md index 11601a0c130..0b0c0f80cc6 100644 --- a/docs/mfc/reference/clinkctrl-class.md +++ b/docs/mfc/reference/clinkctrl-class.md @@ -4,10 +4,12 @@ title: "CLinkCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CLinkCtrl", "AFXCMN/CLinkCtrl", "AFXCMN/CLinkCtrl::CLinkCtrl", "AFXCMN/CLinkCtrl::Create", "AFXCMN/CLinkCtrl::CreateEx", "AFXCMN/CLinkCtrl::GetIdealHeight", "AFXCMN/CLinkCtrl::GetIdealSize", "AFXCMN/CLinkCtrl::GetItem", "AFXCMN/CLinkCtrl::GetItemID", "AFXCMN/CLinkCtrl::GetItemState", "AFXCMN/CLinkCtrl::GetItemUrl", "AFXCMN/CLinkCtrl::HitTest", "AFXCMN/CLinkCtrl::SetItem", "AFXCMN/CLinkCtrl::SetItemID", "AFXCMN/CLinkCtrl::SetItemState", "AFXCMN/CLinkCtrl::SetItemUrl"] helpviewer_keywords: ["CLinkCtrl [MFC], CLinkCtrl", "CLinkCtrl [MFC], Create", "CLinkCtrl [MFC], CreateEx", "CLinkCtrl [MFC], GetIdealHeight", "CLinkCtrl [MFC], GetIdealSize", "CLinkCtrl [MFC], GetItem", "CLinkCtrl [MFC], GetItemID", "CLinkCtrl [MFC], GetItemState", "CLinkCtrl [MFC], GetItemUrl", "CLinkCtrl [MFC], HitTest", "CLinkCtrl [MFC], SetItem", "CLinkCtrl [MFC], SetItemID", "CLinkCtrl [MFC], SetItemState", "CLinkCtrl [MFC], SetItemUrl"] -ms.assetid: d1cd876a-ecca-42db-8ac4-9cd327df0cd4 --- # CLinkCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common SysLink control. ## Syntax diff --git a/docs/mfc/reference/clist-class.md b/docs/mfc/reference/clist-class.md index 083376f4fcf..536e937582b 100644 --- a/docs/mfc/reference/clist-class.md +++ b/docs/mfc/reference/clist-class.md @@ -4,10 +4,12 @@ title: "CList Class" ms.date: "11/04/2016" f1_keywords: ["CList", "AFXTEMPL/CList", "AFXTEMPL/CList::CList", "AFXTEMPL/CList::AddHead", "AFXTEMPL/CList::AddTail", "AFXTEMPL/CList::Find", "AFXTEMPL/CList::FindIndex", "AFXTEMPL/CList::GetAt", "AFXTEMPL/CList::GetCount", "AFXTEMPL/CList::GetHead", "AFXTEMPL/CList::GetHeadPosition", "AFXTEMPL/CList::GetNext", "AFXTEMPL/CList::GetPrev", "AFXTEMPL/CList::GetSize", "AFXTEMPL/CList::GetTail", "AFXTEMPL/CList::GetTailPosition", "AFXTEMPL/CList::InsertAfter", "AFXTEMPL/CList::InsertBefore", "AFXTEMPL/CList::IsEmpty", "AFXTEMPL/CList::RemoveAll", "AFXTEMPL/CList::RemoveAt", "AFXTEMPL/CList::RemoveHead", "AFXTEMPL/CList::RemoveTail", "AFXTEMPL/CList::SetAt"] helpviewer_keywords: ["CList [MFC], CList", "CList [MFC], AddHead", "CList [MFC], AddTail", "CList [MFC], Find", "CList [MFC], FindIndex", "CList [MFC], GetAt", "CList [MFC], GetCount", "CList [MFC], GetHead", "CList [MFC], GetHeadPosition", "CList [MFC], GetNext", "CList [MFC], GetPrev", "CList [MFC], GetSize", "CList [MFC], GetTail", "CList [MFC], GetTailPosition", "CList [MFC], InsertAfter", "CList [MFC], InsertBefore", "CList [MFC], IsEmpty", "CList [MFC], RemoveAll", "CList [MFC], RemoveAt", "CList [MFC], RemoveHead", "CList [MFC], RemoveTail", "CList [MFC], SetAt"] -ms.assetid: 6f6273c3-c8f6-47f5-ac2a-0a950379ae5d --- # `CList` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports ordered lists of nonunique objects accessible sequentially or by value. ## Syntax diff --git a/docs/mfc/reference/clistbox-class.md b/docs/mfc/reference/clistbox-class.md index 93f4efc5532..2c82cd368f2 100644 --- a/docs/mfc/reference/clistbox-class.md +++ b/docs/mfc/reference/clistbox-class.md @@ -4,10 +4,12 @@ description: "A description of the MFC CListBox class and its member functions." ms.date: "01/22/2020" f1_keywords: ["CListBox", "AFXWIN/CListBox", "AFXWIN/CListBox::CListBox", "AFXWIN/CListBox::AddString", "AFXWIN/CListBox::CharToItem", "AFXWIN/CListBox::CompareItem", "AFXWIN/CListBox::Create", "AFXWIN/CListBox::DeleteItem", "AFXWIN/CListBox::DeleteString", "AFXWIN/CListBox::Dir", "AFXWIN/CListBox::DrawItem", "AFXWIN/CListBox::FindString", "AFXWIN/CListBox::FindStringExact", "AFXWIN/CListBox::GetAnchorIndex", "AFXWIN/CListBox::GetCaretIndex", "AFXWIN/CListBox::GetCount", "AFXWIN/CListBox::GetCurSel", "AFXWIN/CListBox::GetHorizontalExtent", "AFXWIN/CListBox::GetItemData", "AFXWIN/CListBox::GetItemDataPtr", "AFXWIN/CListBox::GetItemHeight", "AFXWIN/CListBox::GetItemRect", "AFXWIN/CListBox::GetListBoxInfo", "AFXWIN/CListBox::GetLocale", "AFXWIN/CListBox::GetSel", "AFXWIN/CListBox::GetSelCount", "AFXWIN/CListBox::GetSelItems", "AFXWIN/CListBox::GetText", "AFXWIN/CListBox::GetTextLen", "AFXWIN/CListBox::GetTopIndex", "AFXWIN/CListBox::InitStorage", "AFXWIN/CListBox::InsertString", "AFXWIN/CListBox::ItemFromPoint", "AFXWIN/CListBox::MeasureItem", "AFXWIN/CListBox::ResetContent", "AFXWIN/CListBox::SelectString", "AFXWIN/CListBox::SelItemRange", "AFXWIN/CListBox::SetAnchorIndex", "AFXWIN/CListBox::SetCaretIndex", "AFXWIN/CListBox::SetColumnWidth", "AFXWIN/CListBox::SetCurSel", "AFXWIN/CListBox::SetHorizontalExtent", "AFXWIN/CListBox::SetItemData", "AFXWIN/CListBox::SetItemDataPtr", "AFXWIN/CListBox::SetItemHeight", "AFXWIN/CListBox::SetLocale", "AFXWIN/CListBox::SetSel", "AFXWIN/CListBox::SetTabStops", "AFXWIN/CListBox::SetTopIndex", "AFXWIN/CListBox::VKeyToItem"] helpviewer_keywords: ["CListBox [MFC], CListBox", "CListBox [MFC], AddString", "CListBox [MFC], CharToItem", "CListBox [MFC], CompareItem", "CListBox [MFC], Create", "CListBox [MFC], DeleteItem", "CListBox [MFC], DeleteString", "CListBox [MFC], Dir", "CListBox [MFC], DrawItem", "CListBox [MFC], FindString", "CListBox [MFC], FindStringExact", "CListBox [MFC], GetAnchorIndex", "CListBox [MFC], GetCaretIndex", "CListBox [MFC], GetCount", "CListBox [MFC], GetCurSel", "CListBox [MFC], GetHorizontalExtent", "CListBox [MFC], GetItemData", "CListBox [MFC], GetItemDataPtr", "CListBox [MFC], GetItemHeight", "CListBox [MFC], GetItemRect", "CListBox [MFC], GetListBoxInfo", "CListBox [MFC], GetLocale", "CListBox [MFC], GetSel", "CListBox [MFC], GetSelCount", "CListBox [MFC], GetSelItems", "CListBox [MFC], GetText", "CListBox [MFC], GetTextLen", "CListBox [MFC], GetTopIndex", "CListBox [MFC], InitStorage", "CListBox [MFC], InsertString", "CListBox [MFC], ItemFromPoint", "CListBox [MFC], MeasureItem", "CListBox [MFC], ResetContent", "CListBox [MFC], SelectString", "CListBox [MFC], SelItemRange", "CListBox [MFC], SetAnchorIndex", "CListBox [MFC], SetCaretIndex", "CListBox [MFC], SetColumnWidth", "CListBox [MFC], SetCurSel", "CListBox [MFC], SetHorizontalExtent", "CListBox [MFC], SetItemData", "CListBox [MFC], SetItemDataPtr", "CListBox [MFC], SetItemHeight", "CListBox [MFC], SetLocale", "CListBox [MFC], SetSel", "CListBox [MFC], SetTabStops", "CListBox [MFC], SetTopIndex", "CListBox [MFC], VKeyToItem"] -ms.assetid: 7ba3c699-c286-4cd9-9066-532c41ec05d1 --- # `CListBox` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows list box. ## Syntax @@ -873,10 +875,10 @@ int InitStorage( ### Parameters *`nItems`*
-Specifies the number of items to add. +Specifies the number of items to for which to reserve space. *`nBytes`*
-Specifies the amount of memory, in bytes, to allocate for item strings. +Specifies the amount of additional memory, in bytes, to allocate for item strings. ### Return Value @@ -884,9 +886,11 @@ If successful, the maximum number of items that the list box can store before a ### Remarks -Call this function before adding a large number of items to a `CListBox`. +You can call this function before adding a large number of items to a `CListBox`. + +This function helps speed up the initialization of list boxes that have a large number of items (more than 100). It preallocates the specified amount of memory so that subsequent [`AddString`](#addstring), [`InsertString`](#insertstring), and [`Dir`](#dir) functions are more efficient. You can use estimates for the parameters. If you overestimate, the extra memory remains allocated; if you underestimate, the list box will allocate additional memory as necessary. -This function helps speed up the initialization of list boxes that have a large number of items (more than 100). It preallocates the specified amount of memory so that subsequent [`AddString`](#addstring), [`InsertString`](#insertstring), and [`Dir`](#dir) functions take the shortest possible time. You can use estimates for the parameters. If you overestimate, some extra memory is allocated; if you underestimate, the normal allocation is used for items that exceed the preallocated amount. +The memory required to store a string includes the null terminator. Therefore, if you plan to add 100 strings, each with a length of 10 characters, you would pass a *wParam* of 100 and an *lParam* of 100 × (10 + 1) × sizeof(TCHAR). Windows 95/98 only: The *`nItems`* parameter is limited to 16-bit values. This means list boxes cannot contain more than 32,767 items. Although the number of items is restricted, the total size of the items in a list box is limited only by available memory. diff --git a/docs/mfc/reference/clistctrl-class.md b/docs/mfc/reference/clistctrl-class.md index 8ddf3770801..489c3ee07dc 100644 --- a/docs/mfc/reference/clistctrl-class.md +++ b/docs/mfc/reference/clistctrl-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CListCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax @@ -427,7 +430,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/clistview-class.md b/docs/mfc/reference/clistview-class.md index 111656d0800..5536fc76f68 100644 --- a/docs/mfc/reference/clistview-class.md +++ b/docs/mfc/reference/clistview-class.md @@ -4,10 +4,12 @@ title: "CListView Class" ms.date: "11/04/2016" f1_keywords: ["CListView", "AFXCVIEW/CListView", "AFXCVIEW/CListView::CListView", "AFXCVIEW/CListView::GetListCtrl", "AFXCVIEW/CListView::RemoveImageList"] helpviewer_keywords: ["CListView [MFC], CListView", "CListView [MFC], GetListCtrl", "CListView [MFC], RemoveImageList"] -ms.assetid: 7626bdb2-a1b8-4eab-b631-6743710a8432 --- # CListView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Simplifies use of the list control and of [CListCtrl](../../mfc/reference/clistctrl-class.md), the class that encapsulates list-control functionality, with MFC's document-view architecture. ## Syntax diff --git a/docs/mfc/reference/clongbinary-class.md b/docs/mfc/reference/clongbinary-class.md index 7ba265343e8..268db8c9c57 100644 --- a/docs/mfc/reference/clongbinary-class.md +++ b/docs/mfc/reference/clongbinary-class.md @@ -4,10 +4,12 @@ title: "CLongBinary Class" ms.date: "11/04/2016" f1_keywords: ["CLongBinary", "AFXDB_/CLongBinary", "AFXDB_/CLongBinary::CLongBinary", "AFXDB_/CLongBinary::m_dwDataLength", "AFXDB_/CLongBinary::m_hData"] helpviewer_keywords: ["CLongBinary class [MFC]"] -ms.assetid: f4320059-aeb4-4ee5-bc2b-25f19d898ef5 --- # CLongBinary Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Simplifies working with very large binary data objects (often called BLOBs, or "binary large objects") in a database. ## Syntax diff --git a/docs/mfc/reference/cmap-class.md b/docs/mfc/reference/cmap-class.md index d985acc0408..ab87ec202a2 100644 --- a/docs/mfc/reference/cmap-class.md +++ b/docs/mfc/reference/cmap-class.md @@ -4,10 +4,12 @@ title: "CMap Class" ms.date: "11/04/2016" f1_keywords: ["CMap", "AFXTEMPL/CMap", "AFXTEMPL/CMap::CPair", "AFXTEMPL/CMap::CMap", "AFXTEMPL/CMap::GetCount", "AFXTEMPL/CMap::GetHashTableSize", "AFXTEMPL/CMap::GetNextAssoc", "AFXTEMPL/CMap::GetSize", "AFXTEMPL/CMap::GetStartPosition", "AFXTEMPL/CMap::InitHashTable", "AFXTEMPL/CMap::IsEmpty", "AFXTEMPL/CMap::Lookup", "AFXTEMPL/CMap::PGetFirstAssoc", "AFXTEMPL/CMap::PGetNextAssoc", "AFXTEMPL/CMap::PLookup", "AFXTEMPL/CMap::RemoveAll", "AFXTEMPL/CMap::RemoveKey", "AFXTEMPL/CMap::SetAt"] helpviewer_keywords: ["CMap [MFC], CPair", "CMap [MFC], CMap", "CMap [MFC], GetCount", "CMap [MFC], GetHashTableSize", "CMap [MFC], GetNextAssoc", "CMap [MFC], GetSize", "CMap [MFC], GetStartPosition", "CMap [MFC], InitHashTable", "CMap [MFC], IsEmpty", "CMap [MFC], Lookup", "CMap [MFC], PGetFirstAssoc", "CMap [MFC], PGetNextAssoc", "CMap [MFC], PLookup", "CMap [MFC], RemoveAll", "CMap [MFC], RemoveKey", "CMap [MFC], SetAt"] -ms.assetid: 640a45ab-0993-4def-97ec-42cc78eb10b9 --- # `CMap` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A dictionary collection class that maps unique keys to values. ## Syntax diff --git a/docs/mfc/reference/cmapptrtoptr-class.md b/docs/mfc/reference/cmapptrtoptr-class.md index 10277c43259..e30a3b31515 100644 --- a/docs/mfc/reference/cmapptrtoptr-class.md +++ b/docs/mfc/reference/cmapptrtoptr-class.md @@ -4,10 +4,12 @@ title: "CMapPtrToPtr Class" ms.date: "11/04/2016" f1_keywords: ["CMapPtrToPtr", "AFXCOLL/CMapPtrToPtr", "AFXCOLL/CMapPtrToPtr::CMapPtrToPtr", "AFXCOLL/CMapPtrToPtr::GetCount", "AFXCOLL/CMapPtrToPtr::GetHashTableSize", "AFXCOLL/CMapPtrToPtr::GetNextAssoc", "AFXCOLL/CMapPtrToPtr::GetSize", "AFXCOLL/CMapPtrToPtr::GetStartPosition", "AFXCOLL/CMapPtrToPtr::HashKey", "AFXCOLL/CMapPtrToPtr::InitHashTable", "AFXCOLL/CMapPtrToPtr::IsEmpty", "AFXCOLL/CMapPtrToPtr::Lookup", "AFXCOLL/CMapPtrToPtr::LookupKey", "AFXCOLL/CMapPtrToPtr::RemoveAll", "AFXCOLL/CMapPtrToPtr::RemoveKey", "AFXCOLL/CMapPtrToPtr::SetAt"] helpviewer_keywords: ["CMapPtrToPtr [MFC], CMapPtrToPtr", "CMapPtrToPtr [MFC], GetCount", "CMapPtrToPtr [MFC], GetHashTableSize", "CMapPtrToPtr [MFC], GetNextAssoc", "CMapPtrToPtr [MFC], GetSize", "CMapPtrToPtr [MFC], GetStartPosition", "CMapPtrToPtr [MFC], HashKey", "CMapPtrToPtr [MFC], InitHashTable", "CMapPtrToPtr [MFC], IsEmpty", "CMapPtrToPtr [MFC], Lookup", "CMapPtrToPtr [MFC], LookupKey", "CMapPtrToPtr [MFC], RemoveAll", "CMapPtrToPtr [MFC], RemoveKey", "CMapPtrToPtr [MFC], SetAt"] -ms.assetid: 23cbbaec-9d64-48f2-92ae-5e24fa64b926 --- # CMapPtrToPtr Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports maps of void pointers keyed by void pointers. ## Syntax diff --git a/docs/mfc/reference/cmapptrtoword-class.md b/docs/mfc/reference/cmapptrtoword-class.md index 1810b0d5fd7..6793004b32b 100644 --- a/docs/mfc/reference/cmapptrtoword-class.md +++ b/docs/mfc/reference/cmapptrtoword-class.md @@ -4,10 +4,12 @@ title: "CMapPtrToWord Class" ms.date: "11/04/2016" f1_keywords: ["CMapPtrToWord", "AFXCOLL/CMapPtrToWord", "AFXCOLL/CMapPtrToWord::CMapPtrToWord", "AFXCOLL/CMapPtrToWord::GetCount", "AFXCOLL/CMapPtrToWord::GetHashTableSize", "AFXCOLL/CMapPtrToWord::GetNextAssoc", "AFXCOLL/CMapPtrToWord::GetSize", "AFXCOLL/CMapPtrToWord::GetStartPosition", "AFXCOLL/CMapPtrToWord::HashKey", "AFXCOLL/CMapPtrToWord::InitHashTable", "AFXCOLL/CMapPtrToWord::IsEmpty", "AFXCOLL/CMapPtrToWord::Lookup", "AFXCOLL/CMapPtrToWord::LookupKey", "AFXCOLL/CMapPtrToWord::RemoveAll", "AFXCOLL/CMapPtrToWord::RemoveKey", "AFXCOLL/CMapPtrToWord::SetAt"] helpviewer_keywords: ["CMapPtrToWord [MFC], CMapPtrToWord", "CMapPtrToWord [MFC], GetCount", "CMapPtrToWord [MFC], GetHashTableSize", "CMapPtrToWord [MFC], GetNextAssoc", "CMapPtrToWord [MFC], GetSize", "CMapPtrToWord [MFC], GetStartPosition", "CMapPtrToWord [MFC], HashKey", "CMapPtrToWord [MFC], InitHashTable", "CMapPtrToWord [MFC], IsEmpty", "CMapPtrToWord [MFC], Lookup", "CMapPtrToWord [MFC], LookupKey", "CMapPtrToWord [MFC], RemoveAll", "CMapPtrToWord [MFC], RemoveKey", "CMapPtrToWord [MFC], SetAt"] -ms.assetid: 4631c6b6-d49f-49d9-adc0-1e0491e32d7b --- # CMapPtrToWord Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports maps of 16-bit words keyed by void pointers. ## Syntax diff --git a/docs/mfc/reference/cmapstringtoob-class.md b/docs/mfc/reference/cmapstringtoob-class.md index f48bf10173a..a5de929c1c7 100644 --- a/docs/mfc/reference/cmapstringtoob-class.md +++ b/docs/mfc/reference/cmapstringtoob-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CMapStringToOb` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A dictionary collection class that maps unique `CString` objects to `CObject` pointers. ## Syntax @@ -399,7 +402,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/cmapstringtoptr-class.md b/docs/mfc/reference/cmapstringtoptr-class.md index 4a4ac641f44..a89fe7b5c4f 100644 --- a/docs/mfc/reference/cmapstringtoptr-class.md +++ b/docs/mfc/reference/cmapstringtoptr-class.md @@ -4,10 +4,12 @@ title: "CMapStringToPtr Class" ms.date: "11/04/2016" f1_keywords: ["CMapStringToPtr", "AFXCOLL/CMapStringToPtr", "AFXCOLL/CMapStringToPtr::CMapStringToPtr", "AFXCOLL/CMapStringToPtr::GetCount", "AFXCOLL/CMapStringToPtr::GetHashTableSize", "AFXCOLL/CMapStringToPtr::GetNextAssoc", "AFXCOLL/CMapStringToPtr::GetSize", "AFXCOLL/CMapStringToPtr::GetStartPosition", "AFXCOLL/CMapStringToPtr::HashKey", "AFXCOLL/CMapStringToPtr::InitHashTable", "AFXCOLL/CMapStringToPtr::IsEmpty", "AFXCOLL/CMapStringToPtr::Lookup", "AFXCOLL/CMapStringToPtr::LookupKey", "AFXCOLL/CMapStringToPtr::RemoveAll", "AFXCOLL/CMapStringToPtr::RemoveKey", "AFXCOLL/CMapStringToPtr::SetAt"] helpviewer_keywords: ["CMapStringToPtr [MFC], CMapStringToPtr", "CMapStringToPtr [MFC], GetCount", "CMapStringToPtr [MFC], GetHashTableSize", "CMapStringToPtr [MFC], GetNextAssoc", "CMapStringToPtr [MFC], GetSize", "CMapStringToPtr [MFC], GetStartPosition", "CMapStringToPtr [MFC], HashKey", "CMapStringToPtr [MFC], InitHashTable", "CMapStringToPtr [MFC], IsEmpty", "CMapStringToPtr [MFC], Lookup", "CMapStringToPtr [MFC], LookupKey", "CMapStringToPtr [MFC], RemoveAll", "CMapStringToPtr [MFC], RemoveKey", "CMapStringToPtr [MFC], SetAt"] -ms.assetid: 1ac11143-eb0a-4511-a662-2df0d1d9005b --- # CMapStringToPtr Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports maps of void pointers keyed by `CString` objects. ## Syntax diff --git a/docs/mfc/reference/cmapstringtostring-class.md b/docs/mfc/reference/cmapstringtostring-class.md index 1899172a7ed..a7f970445e6 100644 --- a/docs/mfc/reference/cmapstringtostring-class.md +++ b/docs/mfc/reference/cmapstringtostring-class.md @@ -4,10 +4,12 @@ title: "CMapStringToString Class" ms.date: "11/04/2016" f1_keywords: ["CMapStringToString", "AFXCOLL/CMapStringToString", "AFXCOLL/CMapStringToString::CPair", "AFXCOLL/CMapStringToString::CMapStringToString", "AFXCOLL/CMapStringToString::GetCount", "AFXCOLL/CMapStringToString::GetHashTableSize", "AFXCOLL/CMapStringToString::GetNextAssoc", "AFXCOLL/CMapStringToString::GetSize", "AFXCOLL/CMapStringToString::GetStartPosition", "AFXCOLL/CMapStringToString::HashKey", "AFXCOLL/CMapStringToString::InitHashTable", "AFXCOLL/CMapStringToString::IsEmpty", "AFXCOLL/CMapStringToString::Lookup", "AFXCOLL/CMapStringToString::LookupKey", "AFXCOLL/CMapStringToString::PGetFirstAssoc", "AFXCOLL/CMapStringToString::PGetNextAssoc", "AFXCOLL/CMapStringToString::PLookup", "AFXCOLL/CMapStringToString::RemoveAll", "AFXCOLL/CMapStringToString::RemoveKey", "AFXCOLL/CMapStringToString::SetAt"] helpviewer_keywords: ["CMapStringToString [MFC], CPair", "CMapStringToString [MFC], CMapStringToString", "CMapStringToString [MFC], GetCount", "CMapStringToString [MFC], GetHashTableSize", "CMapStringToString [MFC], GetNextAssoc", "CMapStringToString [MFC], GetSize", "CMapStringToString [MFC], GetStartPosition", "CMapStringToString [MFC], HashKey", "CMapStringToString [MFC], InitHashTable", "CMapStringToString [MFC], IsEmpty", "CMapStringToString [MFC], Lookup", "CMapStringToString [MFC], LookupKey", "CMapStringToString [MFC], PGetFirstAssoc", "CMapStringToString [MFC], PGetNextAssoc", "CMapStringToString [MFC], PLookup", "CMapStringToString [MFC], RemoveAll", "CMapStringToString [MFC], RemoveKey", "CMapStringToString [MFC], SetAt"] -ms.assetid: b45794c2-fe6b-4edb-a8ca-faa03b57b4a8 --- # CMapStringToString Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports maps of `CString` objects keyed by `CString` objects. ## Syntax diff --git a/docs/mfc/reference/cmapwordtoob-class.md b/docs/mfc/reference/cmapwordtoob-class.md index 395f405e314..8b3c3c428d7 100644 --- a/docs/mfc/reference/cmapwordtoob-class.md +++ b/docs/mfc/reference/cmapwordtoob-class.md @@ -4,10 +4,12 @@ title: "CMapWordToOb Class" ms.date: "11/04/2016" f1_keywords: ["CMapWordToOb", "AFXCOLL/CMapWordToOb", "AFXCOLL/CMapWordToOb::CMapWordToOb", "AFXCOLL/CMapWordToOb::GetCount", "AFXCOLL/CMapWordToOb::GetHashTableSize", "AFXCOLL/CMapWordToOb::GetNextAssoc", "AFXCOLL/CMapWordToOb::GetSize", "AFXCOLL/CMapWordToOb::GetStartPosition", "AFXCOLL/CMapWordToOb::HashKey", "AFXCOLL/CMapWordToOb::InitHashTable", "AFXCOLL/CMapWordToOb::IsEmpty", "AFXCOLL/CMapWordToOb::Lookup", "AFXCOLL/CMapWordToOb::LookupKey", "AFXCOLL/CMapWordToOb::RemoveAll", "AFXCOLL/CMapWordToOb::RemoveKey", "AFXCOLL/CMapWordToOb::SetAt"] helpviewer_keywords: ["CMapWordToOb [MFC], CMapWordToOb", "CMapWordToOb [MFC], GetCount", "CMapWordToOb [MFC], GetHashTableSize", "CMapWordToOb [MFC], GetNextAssoc", "CMapWordToOb [MFC], GetSize", "CMapWordToOb [MFC], GetStartPosition", "CMapWordToOb [MFC], HashKey", "CMapWordToOb [MFC], InitHashTable", "CMapWordToOb [MFC], IsEmpty", "CMapWordToOb [MFC], Lookup", "CMapWordToOb [MFC], LookupKey", "CMapWordToOb [MFC], RemoveAll", "CMapWordToOb [MFC], RemoveKey", "CMapWordToOb [MFC], SetAt"] -ms.assetid: 9c9bcd76-456f-4cf9-b03c-dd28b49d5e4f --- # CMapWordToOb Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports maps of `CObject` pointers keyed by 16-bit words. ## Syntax diff --git a/docs/mfc/reference/cmapwordtoptr-class.md b/docs/mfc/reference/cmapwordtoptr-class.md index 474a9292c20..90d850b0f18 100644 --- a/docs/mfc/reference/cmapwordtoptr-class.md +++ b/docs/mfc/reference/cmapwordtoptr-class.md @@ -4,10 +4,12 @@ title: "CMapWordToPtr Class" ms.date: "11/04/2016" f1_keywords: ["CMapWordToPtr", "AFXCOLL/CMapWordToPtr", "AFXCOLL/CMapWordToPtr::CMapWordToPtr", "AFXCOLL/CMapWordToPtr::GetCount", "AFXCOLL/CMapWordToPtr::GetHashTableSize", "AFXCOLL/CMapWordToPtr::GetNextAssoc", "AFXCOLL/CMapWordToPtr::GetSize", "AFXCOLL/CMapWordToPtr::GetStartPosition", "AFXCOLL/CMapWordToPtr::HashKey", "AFXCOLL/CMapWordToPtr::InitHashTable", "AFXCOLL/CMapWordToPtr::IsEmpty", "AFXCOLL/CMapWordToPtr::Lookup", "AFXCOLL/CMapWordToPtr::LookupKey", "AFXCOLL/CMapWordToPtr::RemoveAll", "AFXCOLL/CMapWordToPtr::RemoveKey", "AFXCOLL/CMapWordToPtr::SetAt"] helpviewer_keywords: ["CMapWordToPtr [MFC], CMapWordToPtr", "CMapWordToPtr [MFC], GetCount", "CMapWordToPtr [MFC], GetHashTableSize", "CMapWordToPtr [MFC], GetNextAssoc", "CMapWordToPtr [MFC], GetSize", "CMapWordToPtr [MFC], GetStartPosition", "CMapWordToPtr [MFC], HashKey", "CMapWordToPtr [MFC], InitHashTable", "CMapWordToPtr [MFC], IsEmpty", "CMapWordToPtr [MFC], Lookup", "CMapWordToPtr [MFC], LookupKey", "CMapWordToPtr [MFC], RemoveAll", "CMapWordToPtr [MFC], RemoveKey", "CMapWordToPtr [MFC], SetAt"] -ms.assetid: b204d87f-6427-43e1-93e3-a4b1bb41099f --- # CMapWordToPtr Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports maps of void pointers keyed by 16-bit words. ## Syntax diff --git a/docs/mfc/reference/cmdichildwnd-class.md b/docs/mfc/reference/cmdichildwnd-class.md index a199284190a..acace68a0f5 100644 --- a/docs/mfc/reference/cmdichildwnd-class.md +++ b/docs/mfc/reference/cmdichildwnd-class.md @@ -4,10 +4,12 @@ title: "CMDIChildWnd Class" ms.date: "11/04/2016" f1_keywords: ["CMDIChildWnd", "AFXWIN/CMDIChildWnd", "AFXWIN/CMDIChildWnd::CMDIChildWnd", "AFXWIN/CMDIChildWnd::Create", "AFXWIN/CMDIChildWnd::GetMDIFrame", "AFXWIN/CMDIChildWnd::MDIActivate", "AFXWIN/CMDIChildWnd::MDIDestroy", "AFXWIN/CMDIChildWnd::MDIMaximize", "AFXWIN/CMDIChildWnd::MDIRestore", "AFXWIN/CMDIChildWnd::SetHandles"] helpviewer_keywords: ["CMDIChildWnd [MFC], CMDIChildWnd", "CMDIChildWnd [MFC], Create", "CMDIChildWnd [MFC], GetMDIFrame", "CMDIChildWnd [MFC], MDIActivate", "CMDIChildWnd [MFC], MDIDestroy", "CMDIChildWnd [MFC], MDIMaximize", "CMDIChildWnd [MFC], MDIRestore", "CMDIChildWnd [MFC], SetHandles"] -ms.assetid: 6d07f5d4-9a3e-4723-9fa5-e65bb669fdd5 --- # CMDIChildWnd Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows multiple document interface (MDI) child window, along with members for managing the window. ## Syntax diff --git a/docs/mfc/reference/cmdichildwndex-class.md b/docs/mfc/reference/cmdichildwndex-class.md index b0b6eed2b5c..a689a0849b7 100644 --- a/docs/mfc/reference/cmdichildwndex-class.md +++ b/docs/mfc/reference/cmdichildwndex-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMDIChildWndEx` class 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. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -62,7 +64,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 +955,7 @@ BOOL IsTaskbarTabsSupportEnabled(); ### Return Value -TRUE if the MDI child can appear on Windows 7 taskbar tabs; FALSE if the MDI child can not appear on Windows 7 taskbar tabs. +TRUE if the MDI child can appear on Windows 7 taskbar tabs; FALSE if the MDI child cannot appear on Windows 7 taskbar tabs. ### Remarks diff --git a/docs/mfc/reference/cmdiframewnd-class.md b/docs/mfc/reference/cmdiframewnd-class.md index 4a000c3fe84..f757ad62da0 100644 --- a/docs/mfc/reference/cmdiframewnd-class.md +++ b/docs/mfc/reference/cmdiframewnd-class.md @@ -4,10 +4,12 @@ title: "CMDIFrameWnd Class" ms.date: "11/04/2016" f1_keywords: ["CMDIFrameWnd", "AFXWIN/CMDIFrameWnd", "AFXWIN/CMDIFrameWnd::CMDIFrameWnd", "AFXWIN/CMDIFrameWnd::CreateClient", "AFXWIN/CMDIFrameWnd::CreateNewChild", "AFXWIN/CMDIFrameWnd::GetWindowMenuPopup", "AFXWIN/CMDIFrameWnd::MDIActivate", "AFXWIN/CMDIFrameWnd::MDICascade", "AFXWIN/CMDIFrameWnd::MDIGetActive", "AFXWIN/CMDIFrameWnd::MDIIconArrange", "AFXWIN/CMDIFrameWnd::MDIMaximize", "AFXWIN/CMDIFrameWnd::MDINext", "AFXWIN/CMDIFrameWnd::MDIPrev", "AFXWIN/CMDIFrameWnd::MDIRestore", "AFXWIN/CMDIFrameWnd::MDISetMenu", "AFXWIN/CMDIFrameWnd::MDITile"] helpviewer_keywords: ["CMDIFrameWnd [MFC], CMDIFrameWnd", "CMDIFrameWnd [MFC], CreateClient", "CMDIFrameWnd [MFC], CreateNewChild", "CMDIFrameWnd [MFC], GetWindowMenuPopup", "CMDIFrameWnd [MFC], MDIActivate", "CMDIFrameWnd [MFC], MDICascade", "CMDIFrameWnd [MFC], MDIGetActive", "CMDIFrameWnd [MFC], MDIIconArrange", "CMDIFrameWnd [MFC], MDIMaximize", "CMDIFrameWnd [MFC], MDINext", "CMDIFrameWnd [MFC], MDIPrev", "CMDIFrameWnd [MFC], MDIRestore", "CMDIFrameWnd [MFC], MDISetMenu", "CMDIFrameWnd [MFC], MDITile"] -ms.assetid: fa8736e6-511b-4c51-8b4d-eba78378aeb9 --- # CMDIFrameWnd Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows multiple document interface (MDI) frame window, along with members for managing the window. ## Syntax @@ -391,7 +393,7 @@ Do not call this member function if you use the framework to manage your MDI chi ### Example [!code-cpp[NVC_MFCWindowing#19](../../mfc/reference/codesnippet/cpp/cmdiframewnd-class_7.cpp)] - +  [!code-cpp[NVC_MFCWindowing#20](../../mfc/reference/codesnippet/cpp/cmdiframewnd-class_8.cpp)] ## CMDIFrameWnd::MDITile diff --git a/docs/mfc/reference/cmdiframewndex-class.md b/docs/mfc/reference/cmdiframewndex-class.md index b7b8d1f72ba..47ee4e152ce 100644 --- a/docs/mfc/reference/cmdiframewndex-class.md +++ b/docs/mfc/reference/cmdiframewndex-class.md @@ -1,17 +1,20 @@ --- -description: "Learn more about: CMDIFrameWndEx Class" title: "CMDIFrameWndEx Class" -ms.date: "11/04/2016" -f1_keywords: ["CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ActiveItemRecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AddPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustClientArea", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustDockingLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AreMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CanCovertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ControlBarToTabbedDocument", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateDocumentWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateNewWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPaneLeftOf", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableAutoHidePanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableDocking", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMainMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableLoadDockState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabbedGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabsLastActiveActivation", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnablePaneMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetActivePopup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetDefaultResId", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMenuBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetRibbonBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetTearOffBars", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetToolbarButtonToolTipText", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::InsertPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMDITabbedGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMemberOfMDITabGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMenuBarAvailable", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPointNearDockSite", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPrintPreview", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabMoveToNextGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabNewGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::NegotiateBorderSpace", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseDockingPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnClosePopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCmdMsg", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuImage", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuLogo", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnEraseMDIClientBackground", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMenuButtonToolHitTest", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMoveMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSetPreviewMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowCustomizePane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowMDITabContextMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSizeMDIClient", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnTearOffMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnUpdateFrameMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::PaneFromPoint", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RemovePaneFromDockManager", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SaveMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetPrintPreviewFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetupToolbarMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::TabbedDocumentToControlBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateCaption", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateMDITabbedBarsIcons", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::WinHelp", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bDisableSetRedraw"] -helpviewer_keywords: ["CMDIFrameWndEx [MFC], ActiveItemRecalcLayout", "CMDIFrameWndEx [MFC], AddPane", "CMDIFrameWndEx [MFC], AdjustClientArea", "CMDIFrameWndEx [MFC], AdjustDockingLayout", "CMDIFrameWndEx [MFC], AreMDITabs", "CMDIFrameWndEx [MFC], CanCovertControlBarToMDIChild", "CMDIFrameWndEx [MFC], ControlBarToTabbedDocument", "CMDIFrameWndEx [MFC], CreateDocumentWindow", "CMDIFrameWndEx [MFC], CreateNewWindow", "CMDIFrameWndEx [MFC], DockPane", "CMDIFrameWndEx [MFC], DockPaneLeftOf", "CMDIFrameWndEx [MFC], EnableAutoHidePanes", "CMDIFrameWndEx [MFC], EnableDocking", "CMDIFrameWndEx [MFC], EnableFullScreenMainMenu", "CMDIFrameWndEx [MFC], EnableFullScreenMode", "CMDIFrameWndEx [MFC], EnableLoadDockState", "CMDIFrameWndEx [MFC], EnableMDITabbedGroups", "CMDIFrameWndEx [MFC], EnableMDITabs", "CMDIFrameWndEx [MFC], EnableMDITabsLastActiveActivation", "CMDIFrameWndEx [MFC], EnablePaneMenu", "CMDIFrameWndEx [MFC], EnableWindowsDialog", "CMDIFrameWndEx [MFC], GetActivePopup", "CMDIFrameWndEx [MFC], GetPane", "CMDIFrameWndEx [MFC], GetDefaultResId", "CMDIFrameWndEx [MFC], GetMDITabGroups", "CMDIFrameWndEx [MFC], GetMDITabs", "CMDIFrameWndEx [MFC], GetMDITabsContextMenuAllowedItems", "CMDIFrameWndEx [MFC], GetMenuBar", "CMDIFrameWndEx [MFC], GetRibbonBar", "CMDIFrameWndEx [MFC], GetTearOffBars", "CMDIFrameWndEx [MFC], GetToolbarButtonToolTipText", "CMDIFrameWndEx [MFC], InsertPane", "CMDIFrameWndEx [MFC], IsFullScreen", "CMDIFrameWndEx [MFC], IsMDITabbedGroup", "CMDIFrameWndEx [MFC], IsMemberOfMDITabGroup", "CMDIFrameWndEx [MFC], IsMenuBarAvailable", "CMDIFrameWndEx [MFC], IsPointNearDockSite", "CMDIFrameWndEx [MFC], IsPrintPreview", "CMDIFrameWndEx [MFC], LoadFrame", "CMDIFrameWndEx [MFC], LoadMDIState", "CMDIFrameWndEx [MFC], MDITabMoveToNextGroup", "CMDIFrameWndEx [MFC], MDITabNewGroup", "CMDIFrameWndEx [MFC], NegotiateBorderSpace", "CMDIFrameWndEx [MFC], OnCloseDockingPane", "CMDIFrameWndEx [MFC], OnCloseMiniFrame", "CMDIFrameWndEx [MFC], OnClosePopupMenu", "CMDIFrameWndEx [MFC], OnCmdMsg", "CMDIFrameWndEx [MFC], OnDrawMenuImage", "CMDIFrameWndEx [MFC], OnDrawMenuLogo", "CMDIFrameWndEx [MFC], OnEraseMDIClientBackground", "CMDIFrameWndEx [MFC], OnMenuButtonToolHitTest", "CMDIFrameWndEx [MFC], OnMoveMiniFrame", "CMDIFrameWndEx [MFC], OnSetPreviewMode", "CMDIFrameWndEx [MFC], OnShowCustomizePane", "CMDIFrameWndEx [MFC], OnShowMDITabContextMenu", "CMDIFrameWndEx [MFC], OnShowPanes", "CMDIFrameWndEx [MFC], OnShowPopupMenu", "CMDIFrameWndEx [MFC], OnSizeMDIClient", "CMDIFrameWndEx [MFC], OnTearOffMenu", "CMDIFrameWndEx [MFC], OnUpdateFrameMenu", "CMDIFrameWndEx [MFC], PaneFromPoint", "CMDIFrameWndEx [MFC], RecalcLayout", "CMDIFrameWndEx [MFC], RemovePaneFromDockManager", "CMDIFrameWndEx [MFC], SaveMDIState", "CMDIFrameWndEx [MFC], SetPrintPreviewFrame", "CMDIFrameWndEx [MFC], SetupToolbarMenu", "CMDIFrameWndEx [MFC], ShowFullScreen", "CMDIFrameWndEx [MFC], ShowPane", "CMDIFrameWndEx [MFC], ShowWindowsDialog", "CMDIFrameWndEx [MFC], TabbedDocumentToControlBar", "CMDIFrameWndEx [MFC], UpdateCaption", "CMDIFrameWndEx [MFC], UpdateMDITabbedBarsIcons", "CMDIFrameWndEx [MFC], WinHelp", "CMDIFrameWndEx [MFC], m_bCanCovertControlBarToMDIChild", "CMDIFrameWndEx [MFC], m_bDisableSetRedraw"] +description: "Learn more about: CMDIFrameWndEx class" +ms.date: 08/16/2022 +f1_keywords: ["CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ActiveItemRecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AddPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustClientArea", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AdjustDockingLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::AreMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CanConvertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ControlBarToTabbedDocument", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateDocumentWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::CreateNewWindow", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::DockPaneLeftOf", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableAutoHidePanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableDocking", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMainMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableFullScreenMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableLoadDockState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabbedGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableMDITabsLastActiveActivation", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnablePaneMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::EnableWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetActivePopup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetDefaultResId", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabGroups", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabs", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMDITabsContextMenuAllowedItems", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetMenuBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetRibbonBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetTearOffBars", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::GetToolbarButtonToolTipText", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::InsertPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMDITabbedGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMemberOfMDITabGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsMenuBarAvailable", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPointNearDockSite", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::IsPrintPreview", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::LoadMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabMoveToNextGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::MDITabNewGroup", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::NegotiateBorderSpace", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseDockingPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCloseMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnClosePopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnCmdMsg", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuImage", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnDrawMenuLogo", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnEraseMDIClientBackground", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMenuButtonToolHitTest", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnMoveMiniFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSetPreviewMode", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowCustomizePane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowMDITabContextMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPanes", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnShowPopupMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnSizeMDIClient", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnTearOffMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::OnUpdateFrameMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::PaneFromPoint", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RecalcLayout", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::RemovePaneFromDockManager", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SaveMDIState", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetPrintPreviewFrame", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::SetupToolbarMenu", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowFullScreen", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowPane", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::ShowWindowsDialog", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::TabbedDocumentToControlBar", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateCaption", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::UpdateMDITabbedBarsIcons", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::WinHelp", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild", "AFXMDIFRAMEWNDEX/CMDIFrameWndEx::m_bDisableSetRedraw"] +helpviewer_keywords: ["CMDIFrameWndEx [MFC], ActiveItemRecalcLayout", "CMDIFrameWndEx [MFC], AddPane", "CMDIFrameWndEx [MFC], AdjustClientArea", "CMDIFrameWndEx [MFC], AdjustDockingLayout", "CMDIFrameWndEx [MFC], AreMDITabs", "CMDIFrameWndEx [MFC], CanConvertControlBarToMDIChild", "CMDIFrameWndEx [MFC], ControlBarToTabbedDocument", "CMDIFrameWndEx [MFC], CreateDocumentWindow", "CMDIFrameWndEx [MFC], CreateNewWindow", "CMDIFrameWndEx [MFC], DockPane", "CMDIFrameWndEx [MFC], DockPaneLeftOf", "CMDIFrameWndEx [MFC], EnableAutoHidePanes", "CMDIFrameWndEx [MFC], EnableDocking", "CMDIFrameWndEx [MFC], EnableFullScreenMainMenu", "CMDIFrameWndEx [MFC], EnableFullScreenMode", "CMDIFrameWndEx [MFC], EnableLoadDockState", "CMDIFrameWndEx [MFC], EnableMDITabbedGroups", "CMDIFrameWndEx [MFC], EnableMDITabs", "CMDIFrameWndEx [MFC], EnableMDITabsLastActiveActivation", "CMDIFrameWndEx [MFC], EnablePaneMenu", "CMDIFrameWndEx [MFC], EnableWindowsDialog", "CMDIFrameWndEx [MFC], GetActivePopup", "CMDIFrameWndEx [MFC], GetPane", "CMDIFrameWndEx [MFC], GetDefaultResId", "CMDIFrameWndEx [MFC], GetMDITabGroups", "CMDIFrameWndEx [MFC], GetMDITabs", "CMDIFrameWndEx [MFC], GetMDITabsContextMenuAllowedItems", "CMDIFrameWndEx [MFC], GetMenuBar", "CMDIFrameWndEx [MFC], GetRibbonBar", "CMDIFrameWndEx [MFC], GetTearOffBars", "CMDIFrameWndEx [MFC], GetToolbarButtonToolTipText", "CMDIFrameWndEx [MFC], InsertPane", "CMDIFrameWndEx [MFC], IsFullScreen", "CMDIFrameWndEx [MFC], IsMDITabbedGroup", "CMDIFrameWndEx [MFC], IsMemberOfMDITabGroup", "CMDIFrameWndEx [MFC], IsMenuBarAvailable", "CMDIFrameWndEx [MFC], IsPointNearDockSite", "CMDIFrameWndEx [MFC], IsPrintPreview", "CMDIFrameWndEx [MFC], LoadFrame", "CMDIFrameWndEx [MFC], LoadMDIState", "CMDIFrameWndEx [MFC], MDITabMoveToNextGroup", "CMDIFrameWndEx [MFC], MDITabNewGroup", "CMDIFrameWndEx [MFC], NegotiateBorderSpace", "CMDIFrameWndEx [MFC], OnCloseDockingPane", "CMDIFrameWndEx [MFC], OnCloseMiniFrame", "CMDIFrameWndEx [MFC], OnClosePopupMenu", "CMDIFrameWndEx [MFC], OnCmdMsg", "CMDIFrameWndEx [MFC], OnDrawMenuImage", "CMDIFrameWndEx [MFC], OnDrawMenuLogo", "CMDIFrameWndEx [MFC], OnEraseMDIClientBackground", "CMDIFrameWndEx [MFC], OnMenuButtonToolHitTest", "CMDIFrameWndEx [MFC], OnMoveMiniFrame", "CMDIFrameWndEx [MFC], OnSetPreviewMode", "CMDIFrameWndEx [MFC], OnShowCustomizePane", "CMDIFrameWndEx [MFC], OnShowMDITabContextMenu", "CMDIFrameWndEx [MFC], OnShowPanes", "CMDIFrameWndEx [MFC], OnShowPopupMenu", "CMDIFrameWndEx [MFC], OnSizeMDIClient", "CMDIFrameWndEx [MFC], OnTearOffMenu", "CMDIFrameWndEx [MFC], OnUpdateFrameMenu", "CMDIFrameWndEx [MFC], PaneFromPoint", "CMDIFrameWndEx [MFC], RecalcLayout", "CMDIFrameWndEx [MFC], RemovePaneFromDockManager", "CMDIFrameWndEx [MFC], SaveMDIState", "CMDIFrameWndEx [MFC], SetPrintPreviewFrame", "CMDIFrameWndEx [MFC], SetupToolbarMenu", "CMDIFrameWndEx [MFC], ShowFullScreen", "CMDIFrameWndEx [MFC], ShowPane", "CMDIFrameWndEx [MFC], ShowWindowsDialog", "CMDIFrameWndEx [MFC], TabbedDocumentToControlBar", "CMDIFrameWndEx [MFC], UpdateCaption", "CMDIFrameWndEx [MFC], UpdateMDITabbedBarsIcons", "CMDIFrameWndEx [MFC], WinHelp", "CMDIFrameWndEx [MFC], m_bCanConvertControlBarToMDIChild", "CMDIFrameWndEx [MFC], m_bDisableSetRedraw"] --- -# `CMDIFrameWndEx` Class +# `CMDIFrameWndEx` class + +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. Extends the functionality of [`CMDIFrameWnd`](../../mfc/reference/cframewnd-class.md), a Windows Multiple Document Interface (MDI) frame window. ## Syntax -``` +```cpp class CMDIFrameWndEx : public CMDIFrameWnd ``` @@ -27,7 +30,7 @@ class CMDIFrameWndEx : public CMDIFrameWnd |[`CMDIFrameWndEx::AdjustClientArea`](#adjustclientarea)|Reduces the client area to allow for a border.| |[`CMDIFrameWndEx::AdjustDockingLayout`](#adjustdockinglayout)|Recalculates the layout of all docked panes.| |[`CMDIFrameWndEx::AreMDITabs`](#aremditabs)|Determines whether the MDI Tabs feature or the MDI Tabbed Groups feature is enabled.| -|[`CMDIFrameWndEx::CanCovertControlBarToMDIChild`](#cancovertcontrolbartomdichild)|Called by the framework to determine whether the frame window can convert docking panes to tabbed documents.| +|[`CMDIFrameWndEx::CanConvertControlBarToMDIChild`](#canConvertcontrolbartomdichild)|Called by the framework to determine whether the frame window can convert docking panes to tabbed documents.| |[`CMDIFrameWndEx::ControlBarToTabbedDocument`](#controlbartotabbeddocument)|Converts the specified docking pane to a tabbed document.| |[`CMDIFrameWndEx::CreateDocumentWindow`](#createdocumentwindow)|Creates a child document window.| |[`CMDIFrameWndEx::CreateNewWindow`](#createnewwindow)|Called by the framework to create a new window.| @@ -72,9 +75,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.| @@ -99,11 +102,11 @@ class CMDIFrameWndEx : public CMDIFrameWnd |[`CMDIFrameWndEx::UpdateMDITabbedBarsIcons`](#updatemditabbedbarsicons)|Sets the icon for each MDI tabbed pane.| |[`CMDIFrameWndEx::WinHelp`](#winhelp)|Called by the framework to initiate the WinHelp application or context help. (Overrides [`CWnd::WinHelp`](../../mfc/reference/cwnd-class.md#winhelp).)| -### Data Members +### Data members |Name|Description| |----------|-----------------| -|[`CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild`](#m_bcancovertcontrolbartomdichild)|Determines whether docking panes can be converted to MDI child windows.| +|[`CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild`](#m_bcanConvertcontrolbartomdichild)|Determines whether docking panes can be converted to MDI child windows.| |[`CMDIFrameWndEx::m_bDisableSetRedraw`](#m_bdisablesetredraw)|Enables or disables redraw optimization for MDI child windows.| ## Remarks @@ -146,7 +149,7 @@ void ActiveItemRecalcLayout(); Registers a pane with the docking manager. -``` +```cpp BOOL AddPane( CBasePane* pControlBar, BOOL bTail=TRUE); @@ -160,19 +163,19 @@ BOOL AddPane( *`bTail`*\ [in] Specifies whether to add this pane to the end of the list. -### Return Value +### Return value Returns a non-zero value if the pane is registered successfully. Returns 0 if the pane is already registered with the docking manager. ### Remarks -Each pane must be registered with the [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md) before it can take a part in the docking layout. Use this method to notify the docking manager that you want to dock a specific pane. Once that pane is registered, the docking manager aligns it based on its alignment setting and position in the list of panes maintained by the docking manager. +Each pane must be registered with the [`CDockingManager` class](../../mfc/reference/cdockingmanager-class.md) before it can take a part in the docking layout. Use this method to notify the docking manager that you want to dock a specific pane. Once that pane is registered, the docking manager aligns it based on its alignment setting and position in the list of panes maintained by the docking manager. ## `CMDIFrameWndEx::AdjustClientArea` Reduces the client area to allow for a border. -``` +```cpp virtual void AdjustClientArea(); ``` @@ -180,7 +183,7 @@ virtual void AdjustClientArea(); Recalculates the layout of all docked panes. -``` +```cpp virtual void AdjustDockingLayout(HDWP hdwp=NULL); ``` @@ -197,7 +200,7 @@ Call this member function to recalculate the layout of all panes docked to the f Determines whether the MDI tabs feature or the MDI tabbed groups feature is enabled. -``` +```cpp BOOL AreMDITabs(int* pnMDITabsType=NULL) const; ``` @@ -207,16 +210,14 @@ BOOL AreMDITabs(int* pnMDITabsType=NULL) const; [out] A pointer to an integer variable that indicates which features are enabled: - 0: All features are disabled. - - 1: MDI tabs is enabled. - - 2: MDI tabbed groups is enabled. -### Return Value +### Return value Returns `TRUE` if MDI tabs or MDI tabbed groups is enabled. -Returns `FALSE` if none of the above features is enabled. +Returns `FALSE` if none of the above features are enabled. ### Remarks @@ -224,12 +225,12 @@ Use this function to determine whether MDI tabs or MDI tabbed groups is enabled Use [`CMDIFrameWndEx::EnableMDITabbedGroups`](#enablemditabbedgroups) to enable or disable the MDI tabbed groups feature. -## `CMDIFrameWndEx::CanCovertControlBarToMDIChild` +## `CMDIFrameWndEx::CanConvertControlBarToMDIChild` Called by the framework to determine whether the frame window can convert docking panes to tabbed documents -``` -virtual BOOL CanCovertControlBarToMDIChild(); +```cpp +virtual BOOL CanConvertControlBarToMDIChild(); ``` ### Return Value @@ -238,13 +239,13 @@ Returns `TRUE` if the frame window can convert docking panes to tabbed documents ### Remarks -Override this method in a derived class and return `TRUE` to enable the conversion of docking panes to tabbed documents. Alternatively, you can set [`CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild`](#m_bcancovertcontrolbartomdichild) to `TRUE`. +Override this method in a derived class and return `TRUE` to enable the conversion of docking panes to tabbed documents. Alternatively, you can set [`CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild`](#m_bcanConvertcontrolbartomdichild) to `TRUE`. ## `CMDIFrameWndEx::ControlBarToTabbedDocument` Converts the specified docking pane to a tabbed document. -``` +```cpp virtual CMDIChildWndEx* ControlBarToTabbedDocument(CDockablePane* pBar); ``` @@ -259,13 +260,13 @@ Returns a pointer to the new MDI child window that contains the docking pane. ### Remarks -This method converts a docking pane to a tabbed document. When you call this method, the framework creates a [`CMDIChildWndEx` Class](../../mfc/reference/cmdichildwndex-class.md) object, removes the docking pane from the docking manager, and adds the docking pane to the new MDI child window. The MDI child window resizes the docking pane to cover the entire client area +This method converts a docking pane to a tabbed document. When you call this method, the framework creates a [`CMDIChildWndEx` class](../../mfc/reference/cmdichildwndex-class.md) object, removes the docking pane from the docking manager, and adds the docking pane to the new MDI child window. The MDI child window resizes the docking pane to cover the entire client area ## `CMDIFrameWndEx::CreateDocumentWindow` Creates a child document window. -``` +```cpp virtual CMDIChildWndEx* CreateDocumentWindow( LPCTSTR lpcszDocName, CObject* pObj); @@ -279,7 +280,7 @@ virtual CMDIChildWndEx* CreateDocumentWindow( *`pObj`*\ [in] A pointer to a user-defined object. For example, a developer can create an application-specific data structure describing the document and telling how the document should be initialized at startup. -### Return Value +### Return value A pointer to `CMDIChildWndEx`. @@ -293,7 +294,7 @@ Override this method in order to create documents when they're being loaded from The following example shows how `CreateDocumentWindow` is used in the [VisualStudioDemo Sample: MFC Visual Studio Application](../../overview/visual-cpp-samples.md). -In this example, `g_strStartViewName` could be the name of a "virtual document" (for example, "Start Page") that isn't actually loaded from a disk file. Therefore we need special processing to handle that case. +In this example, `g_strStartViewName` could be the name of a "virtual document" (for example, "Start Page") that isn't loaded from a disk file. Therefore we need special processing to handle that case. [!code-cpp[NVC_MFC_VisualStudioDemo#13](../../mfc/codesnippet/cpp/cmdiframewndex-class_2.cpp)] @@ -301,7 +302,7 @@ In this example, `g_strStartViewName` could be the name of a "virtual document" Called by the framework to create a new window. -``` +```cpp virtual CMDIChildWndEx* CreateNewWindow( LPCTSTR lpcszDocName, CObject* pObj); @@ -315,7 +316,7 @@ virtual CMDIChildWndEx* CreateNewWindow( *`pObj`*\ [in] Reserved for future use. -### Return Value +### Return value A pointer to the new window. @@ -343,7 +344,7 @@ void DockPane( ### Remarks -This method docks the specified the pane to one of the sides of the frame window that was specified when [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking) and [`CMDIFrameWndEx::EnableDocking`](#enabledocking) were called. +This method docks the specified pane to one of the sides of the frame window that was specified when [`CBasePane::EnableDocking`](../../mfc/reference/cbasepane-class.md#enabledocking) and [`CMDIFrameWndEx::EnableDocking`](#enabledocking) were called. ### Example @@ -355,7 +356,7 @@ The following example demonstrates the use of the `DockPane` method. This code s Docks one pane to the left of another pane. -``` +```cpp BOOL DockPaneLeftOf( CPane* pBar, CPane* pLeftOf); @@ -369,7 +370,7 @@ BOOL DockPaneLeftOf( *`pLeftOf`*\ [in] A pointer to the pane that serves as the dock site. -### Return Value +### Return value Returns `TRUE` if the operation is successful. Otherwise returns `FALSE`. @@ -387,7 +388,7 @@ The following example shows how the `DockPaneLeftOf` method is used in the [Visu Enables auto-hide mode for panes when they're docked at the specified sides of the main frame window. -``` +```cpp BOOL EnableAutoHidePanes(DWORD dwDockStyle); ``` @@ -397,14 +398,11 @@ BOOL EnableAutoHidePanes(DWORD dwDockStyle); [in] Specifies the sides of the main frame window that will be enabled. Use one or more of the following flags. - `CBRS_ALIGN_LEFT` - - `CBRS_ALIGN_RIGHT` - - `CBRS_ALIGN_TOP` - - `CBRS_ALIGN_BOTTOM` -### Return Value +### Return value Call this function to enable auto-hide mode for panes when they're docked at the specified sides of the main frame window. @@ -420,7 +418,7 @@ The following example shows how the `EnableAutoHidePanes` method is used in the Enables docking of the panes that belong to the MDI frame window. -``` +```cpp BOOL EnableDocking(DWORD dwDockStyle); ``` @@ -429,7 +427,7 @@ BOOL EnableDocking(DWORD dwDockStyle); *`dwDockStyle`*\ [in] Specifies the docking style that you want to apply. -### Return Value +### Return value ### Remarks @@ -471,7 +469,7 @@ void EnableFullScreenMode(UINT uiFullScreenCmd); ### Remarks -In full-screen mode, all docking control bars, toolbars and menus are hidden and the active view is resized to occupy the full-screen.When you enable full-screen mode, you must specify an ID of the command that enables or disables it. You can call `EnableFullScreenMode` from the main frame's `OnCreate` function. When a frame window is being switched to full-screen mode, the framework creates a floating toolbar with one button that has the specified command ID. If you want to keep the main menu on the screen, call [`CMDIFrameWndEx::EnableFullScreenMainMenu`](#enablefullscreenmainmenu). +In full-screen mode, all docking control bars, toolbars and menus are hidden and the active view is resized to occupy the full-screen. When you enable full-screen mode, you must specify an ID of the command that enables or disables it. You can call `EnableFullScreenMode` from the main frame's `OnCreate` function. When a frame window is being switched to full-screen mode, the framework creates a floating toolbar with one button that has the specified command ID. If you want to keep the main menu on the screen, call [`CMDIFrameWndEx::EnableFullScreenMainMenu`](#enablefullscreenmainmenu). ## `CMDIFrameWndEx::EnableLoadDockState` @@ -510,14 +508,11 @@ void EnableMDITabbedGroups( Use this method to enable or disable the MDI tabbed groups feature. This feature enables MDI applications to display child windows as tabbed windows that are aligned vertically or horizontally within the MDI client area. Groups of tabbed windows are separated by splitters. The user can resize tabbed groups by using a splitter. -- The user can: +The user can: - Drag individual tabs between groups. - - Drag individual tabs to the edge of the window to create new groups. - - Move tabs or create new groups by using a shortcut menu. - - Your application can save the current layout of tabbed windows and the list of currently opened documents. If you call this method with *`bEnable`* set to `FALSE`, *`params`* is ignored. @@ -602,7 +597,6 @@ void EnableMDITabsLastActiveActivation(BOOL bLastActiveTab=TRUE); There are two ways to open a tab when the active tab is closed: - Activate the next tab. - - Activate the previously active tab. The default implementation uses the first way. @@ -687,7 +681,7 @@ void EnableWindowsDialog( ### Remarks -Use this method to insert a menu item whose command calls a MDI child window management dialog box ( [`CMFCWindowsManagerDialog` Class](../../mfc/reference/cmfcwindowsmanagerdialog-class.md)). The new item is inserted into the menu specified by *`uiMenuId`*. Call `EnableWindowsDialog` when you process the `WM_CREATE` message. +Use this method to insert a menu item whose command calls an MDI child window management dialog box ( [`CMFCWindowsManagerDialog` class](../../mfc/reference/cmfcwindowsmanagerdialog-class.md)). The new item is inserted into the menu specified by *`uiMenuId`*. Call `EnableWindowsDialog` when you process the `WM_CREATE` message. ### Example @@ -699,27 +693,27 @@ The following example shows how `EnableWindowsDialog` is used in the [VisualStud Returns a pointer to the currently displayed popup menu. -``` +```cpp CMFCPopupMenu* GetActivePopup() const; ``` -### Return Value +### Return value A pointer to the active popup menu; `NULL` if no popup menu is active. ### Remarks -Use this function to obtain a pointer to the [`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md) object that is currently displayed. +Use this function to obtain a pointer to the [`CMFCPopupMenu` class](../../mfc/reference/cmfcpopupmenu-class.md) object that is currently displayed. ## `CMDIFrameWndEx::GetDefaultResId` Returns the ID of shared resources of the MDI frame window. -``` +```cpp UINT GetDefaultResId() const; ``` -### Return Value +### Return value A resource ID value. 0 if the frame window has no menu bar. @@ -731,13 +725,13 @@ This method returns the resource ID that was specified when the MDI frame window Returns a list of MDI tabbed windows. -``` +```cpp const CObList& GetMDITabGroups() const; ``` -### Return Value +### Return value -A reference to a [`CObList` Class](../../mfc/reference/coblist-class.md) object that contains a list of tabbed windows. Don't store or modify the list. +A reference to a [`CObList` class](../../mfc/reference/coblist-class.md) object that contains a list of tabbed windows. Don't store or modify the list. ### Remarks @@ -747,11 +741,11 @@ Use this method to access the list of tabbed windows. It can be helpful if you w Returns a reference to the underlined tabbed window. -``` +```cpp CMFCTabCtrl& GetMDITabs(); ``` -### Return Value +### Return value A reference to the underlined tabbed window. @@ -759,20 +753,17 @@ A reference to the underlined tabbed window. Returns a combination of flags that determines what operations are valid when the MDI Tabbed Groups feature is enabled. -``` +```cpp DWORD GetMDITabsContextMenuAllowedItems(); ``` -### Return Value +### Return value A bitwise "or" (`|`) combination of the following flags: - `AFX_MDI_CREATE_VERT_GROUP` - can create a vertical tab group. - - `AFX_MDI_CREATE_HORZ_GROUP` - can create a horizontal tab group. - - `AFX_MDI_CAN_MOVE_PREV` - can move a tab to the previous tab group. - - `AFX_MDI_CAN_MOVE_NEXT` - can move a tab to the next tab group. ### Remarks @@ -791,11 +782,11 @@ You can move a tab to the next group only if there's more than one tab in a tabb Returns a pointer to a menu bar object attached to the frame window. -``` +```cpp const CMFCMenuBar* GetMenuBar() const; ``` -### Return Value +### Return value A pointer to a menu bar object. @@ -803,7 +794,7 @@ A pointer to a menu bar object. Returns a pointer to the pane that has the specified control ID. -``` +```cpp CBasePane* GetPane(UINT nID); ``` @@ -812,7 +803,7 @@ CBasePane* GetPane(UINT nID); *`nID`*\ [in] The control ID. -### Return Value +### Return value A pointer to the pane that has the specified control ID, if it exists. Otherwise, `NULL`. @@ -820,13 +811,13 @@ A pointer to the pane that has the specified control ID, if it exists. Otherwise Retrieves the ribbon bar control for the frame. -``` +```cpp CMFCRibbonBar* GetRibbonBar(); ``` -### Return Value +### Return value -Pointer to the [`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.md) for the frame. +Pointer to the [`CMFCRibbonBar` class](../../mfc/reference/cmfcribbonbar-class.md) for the frame. ### Remarks @@ -834,13 +825,13 @@ Pointer to the [`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.m Returns a list of tear-off menus. -``` +```cpp const CObList& GetTearOffBars() const; ``` -### Return Value +### Return value -A reference to a [`CObList` Class](../../mfc/reference/coblist-class.md) object that contains a collection of pointers to `CPane`-derived objects that are in a tear-off state. +A reference to a [`CObList` class](../../mfc/reference/coblist-class.md) object that contains a collection of pointers to `CPane`-derived objects that are in a tear-off state. ### Remarks @@ -850,7 +841,7 @@ A reference to a [`CObList` Class](../../mfc/reference/coblist-class.md) object Called by the framework when the application displays the tooltip for a toolbar button. -``` +```cpp virtual BOOL GetToolbarButtonToolTipText( CMFCToolBarButton* pButton, CString& strTTText); @@ -864,7 +855,7 @@ virtual BOOL GetToolbarButtonToolTipText( *`strTTText`*\ [in] The tooltip text to display for the button. -### Return Value +### Return value `TRUE` if the tooltip has been displayed. `FALSE` otherwise. @@ -874,7 +865,7 @@ virtual BOOL GetToolbarButtonToolTipText( Registers the specified pane with the docking manager. -``` +```cpp BOOL InsertPane( CBasePane* pControlBar, CBasePane* pTarget, @@ -892,7 +883,7 @@ BOOL InsertPane( *`bAfter`*\ [in] If `TRUE`, *`pControlBar`* is inserted after *`pTarget`*. If `FALSE`, *`pControlBar`* is inserted before *`pTarget`*. -### Return Value +### Return value `TRUE` if the method successfully registers the pane, `FALSE` if the pane was already registered with the docking manager. @@ -904,11 +895,11 @@ Use this method to tell the docking manager about a pane specified by *`pControl Determines whether the frame window is in full-screen mode. -``` +```cpp BOOL IsFullScreen() const; ``` -### Return Value +### Return value `TRUE` if the frame window is in full screen mode; otherwise `FALSE`. @@ -920,11 +911,11 @@ You can set the full screen mode by calling the [`CMDIFrameWndEx::EnableFullScre Specifies whether the MDI Tabbed Groups feature is enabled. -``` +```cpp BOOL IsMDITabbedGroup() const; ``` -### Return Value +### Return value `TRUE` if the MDI Tabbed Groups feature is enabled; otherwise `FALSE`. @@ -936,7 +927,7 @@ To determine whether regular MDI tabs or the MDI Tabbed Groups feature is enable Determines whether the specified tabbed window is in the list of windows that are in MDI Tabbed Groups. -``` +```cpp BOOL IsMemberOfMDITabGroup(CWnd* pWnd); ``` @@ -945,7 +936,7 @@ BOOL IsMemberOfMDITabGroup(CWnd* pWnd); *`pWnd`*\ [in] A pointer to tabbed window. -### Return Value +### Return value `TRUE` if the specified tabbed window is in the list of tabbed windows that form MDI Tabbed Groups. Otherwise `FALSE`. @@ -953,11 +944,11 @@ BOOL IsMemberOfMDITabGroup(CWnd* pWnd); Determines whether the frame window has a menu bar. -``` +```cpp BOOL IsMenuBarAvailable() const; ``` -### Return Value +### Return value `TRUE` if the pointer to the menu bar object isn't `NULL`; otherwise `FALSE`. @@ -965,7 +956,7 @@ BOOL IsMenuBarAvailable() const; Determines whether a specified point is near the dock site. -``` +```cpp BOOL IsPointNearDockSite( CPoint point, DWORD& dwBarAlignment, @@ -983,7 +974,7 @@ BOOL IsPointNearDockSite( *`bOuterEdge`*\ [in] `TRUE` if the point is near the outer border of the dock site; `FALSE` otherwise. -### Return Value +### Return value `TRUE` if the point is near the dock site; otherwise `FALSE`. @@ -995,11 +986,11 @@ The point is near the dock site when it is within the sensitivity set in the doc Determines whether the frame window is in print-preview mode. -``` +```cpp BOOL IsPrintPreview(); ``` -### Return Value +### Return value `TRUE` if the frame window is in print-preview mode; otherwise, `FALSE`. @@ -1009,7 +1000,7 @@ BOOL IsPrintPreview(); Creates a frame window from resource information. -``` +```cpp virtual BOOL LoadFrame( UINT nIDResource, DWORD dwDefaultStyle = WS_OVERLAPPEDWINDOW | FWS_ADDTOTITLE, @@ -1031,7 +1022,7 @@ virtual BOOL LoadFrame( *`pContext`*\ [in] A pointer to a [`CCreateContext` Structure](../../mfc/reference/ccreatecontext-structure.md). This parameter can be `NULL`. -### Return Value +### Return value `TRUE` if the method succeeds, otherwise `FALSE`. @@ -1039,7 +1030,7 @@ virtual BOOL LoadFrame( Loads the specified layout of MDI Tabbed Groups and the list of previously opened documents. -``` +```cpp virtual BOOL LoadMDIState(LPCTSTR lpszProfileName); ``` @@ -1048,7 +1039,7 @@ virtual BOOL LoadMDIState(LPCTSTR lpszProfileName); *`lpszProfileName`*\ [in] Specifies the profile name. -### Return Value +### Return value `TRUE` if the load succeeded; `FALSE` if the load failed or there's no data to load. @@ -1057,11 +1048,8 @@ virtual BOOL LoadMDIState(LPCTSTR lpszProfileName); To load or save the state of MDI tabs and groups and the list of opened documents, do the following: - Call [`CMDIFrameWndEx::SaveMDIState`](#savemdistate) when the main frame is being closed - -- Call [`CMDIFrameWndEx::LoadMDIState`](#loadmdistate) when the main frame is being created. The recommended place for this call is before the main frame is displayed for the first time. Add `CWinAppEx::EnableLoadWindowPlacement` `(FALSE);` before `pMainFrame->LoadFrame (IDR_MAINFRAME);.` Add `CWinAppEx::ReloadWindowPlacement` `(pMainFrame);` after the call to `LoadMDIState` to display the main frame at the position that was stored in the registry. - +- Call [`CMDIFrameWndEx::LoadMDIState`](#loadmdistate) when the main frame is being created. The recommended place for this call is before the main frame is displayed for the first time. Add `CWinAppEx::EnableLoadWindowPlacement` `(FALSE);` before `pMainFrame->LoadFrame (IDR_MAINFRAME);`. Add `CWinAppEx::ReloadWindowPlacement` `(pMainFrame);` after the call to `LoadMDIState` to display the main frame at the position that was stored in the registry. - Override `GetDocumentName` in the `CMDIChildWndEx`- derived class if your application displays documents that aren't stored as files. The returned string will be saved in the registry as the document identifier. The base implementation of [`CMDIChildWndEx::GetDocumentName`](../../mfc/reference/cmdichildwndex-class.md#getdocumentname) returns a value obtained from [`CDocument::GetPathName`](../../mfc/reference/cdocument-class.md#getpathname). - - Override [`CMDIFrameWndEx::CreateDocumentWindow`](#createdocumentwindow) to correctly create documents when they're being loaded from the registry. The first parameter is the string that `GetDocumentName` returned. ### Example @@ -1106,23 +1094,23 @@ The following example shows how `MDITabNewGroup` is used in the [VisualStudioDem [!code-cpp[NVC_MFC_VisualStudioDemo#12](../../mfc/codesnippet/cpp/cmdiframewndex-class_12.cpp)] -## `CMDIFrameWndEx::m_bCanCovertControlBarToMDIChild` +## `CMDIFrameWndEx::m_bCanConvertControlBarToMDIChild` Specifies whether docking panes can be converted to MDI child windows. -``` -BOOL m_bCanCovertControlBarToMDIChild; +```cpp +BOOL m_bCanConvertControlBarToMDIChild; ``` ### Remarks -Indicates whether docking control bars can be converted to MDI child windows. If this flag is `TRUE`, the framework handles the conversion automatically when the user selects the **Tabbed Document** command. The flag is protected and you must explicitly enable this option either by setting `m_bCanCovertControlBarToMDIChild` in a constructor of a `CMDIFrameWndEx`-derived class, or by overriding `CanConvertControlBarToMDIChild`. +Indicates whether docking control bars can be converted to MDI child windows. If this flag is `TRUE`, the framework handles the conversion automatically when the user selects the **Tabbed Document** command. The flag is protected and you must explicitly enable this option either by setting `m_bCanConvertControlBarToMDIChild` in a constructor of a `CMDIFrameWndEx`-derived class, or by overriding `CanConvertControlBarToMDIChild`. The default value is `FALSE`. ### Example -The following example shows how `m_bCanCovertControlBarToMDIChild` is used in the [VisualStudioDemo Sample: MFC Visual Studio Application](../../overview/visual-cpp-samples.md). +The following example shows how `m_bCanConvertControlBarToMDIChild` is used in the [VisualStudioDemo Sample: MFC Visual Studio Application](../../overview/visual-cpp-samples.md). [!code-cpp[NVC_MFC_VisualStudioDemo#13](../../mfc/codesnippet/cpp/cmdiframewndex-class_2.cpp)] @@ -1130,7 +1118,7 @@ The following example shows how `m_bCanCovertControlBarToMDIChild` is used in th Enables or disables redraw optimization for MDI child windows. -``` +```cpp AFX_IMPORT_DATA static BOOL m_bDisableSetRedraw; ``` @@ -1138,7 +1126,7 @@ AFX_IMPORT_DATA static BOOL m_bDisableSetRedraw; The default value is `TRUE`. -Set this flag to `FALSE` if you want to optimize redrawing of MDI children. In this case the framework will call `SetRedraw (FALSE)` for the main frame when the application is changing the active tab. +Set this flag to `FALSE` if you want to optimize redrawing of MDI children. In this case, the framework will call `SetRedraw (FALSE)` for the main frame when the application is changing the active tab. This flag can cause unwanted effects (such as background applications that become visible). Therefore we recommend that you change the default only if you experience noticeable flickering during MDI tab activation. @@ -1146,7 +1134,7 @@ This flag can cause unwanted effects (such as background applications that becom Negotiates border space in a frame window during OLE in-place activation. -``` +```cpp virtual BOOL NegotiateBorderSpace( UINT nBorderCmd, LPRECT lpRectBorder); @@ -1158,15 +1146,13 @@ virtual BOOL NegotiateBorderSpace( [in] Contains one of the following values from the enum `CFrameWnd::BorderCmd`: - `borderGet` = 1 - - `borderRequest` = 2 - - `borderSet` = 3 *`lpRectBorder`*\ -[in, out] Pointer to a [`RECT` Structure](/windows/win32/api/windef/ns-windef-rect) or a [`CRect` Class](../../atl-mfc-shared/reference/crect-class.md) object that specifies the coordinates of the border. +[in, out] Pointer to a [`RECT` structure](/windows/win32/api/windef/ns-windef-rect) or a [`CRect` class](../../atl-mfc-shared/reference/crect-class.md) object that specifies the coordinates of the border. -### Return Value +### Return value Nonzero if the method was successful; otherwise 0. @@ -1178,7 +1164,7 @@ This method is an implementation of OLE border space negotiation. Called by the framework when the user clicks the **Close** button on a dockable pane. -``` +```cpp virtual BOOL OnCloseDockingPane(CDockablePane* pWnd); ``` @@ -1187,7 +1173,7 @@ virtual BOOL OnCloseDockingPane(CDockablePane* pWnd); *`pWnd`*\ [in] Pointer to the pane being closed. -### Return Value +### Return value `TRUE` if the docking pane can be closed. Otherwise, `FALSE`. @@ -1201,7 +1187,7 @@ The default implementation does nothing and returns `TRUE`. Called by the framework when the user clicks the **Close** button on a floating mini-frame window. -``` +```cpp virtual BOOL OnCloseMiniFrame(CPaneFrameWnd*); ``` @@ -1210,7 +1196,7 @@ virtual BOOL OnCloseMiniFrame(CPaneFrameWnd*); *`pWnd`*\ [in] Pointer to the mini-frame window being closed. -### Return Value +### Return value `TRUE` if the floating mini-frame window can be closed. Otherwise, `FALSE`. @@ -1224,7 +1210,7 @@ The default implementation does nothing and returns `TRUE`. Called by the framework when an active pop-up menu processes a `WM_DESTROY` message. -``` +```cpp virtual void OnClosePopupMenu(CMFCPopupMenu* pMenuPopup); ``` @@ -1235,13 +1221,13 @@ virtual void OnClosePopupMenu(CMFCPopupMenu* pMenuPopup); ### Remarks -Override this method if you want to process notifications from [`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md) objects that belong to the MDI frame window when those objects process `WM_DESTROY` messages. +Override this method if you want to process notifications from [`CMFCPopupMenu` class](../../mfc/reference/cmfcpopupmenu-class.md) objects that belong to the MDI frame window when those objects process `WM_DESTROY` messages. ## `CMDIFrameWndEx::OnCmdMsg` Called by the framework to route and dispatch command messages and to update command user-interface objects. -``` +```cpp virtual BOOL OnCmdMsg( UINT nID, int nCode, @@ -1255,15 +1241,15 @@ virtual BOOL OnCmdMsg( [in] The command ID. *`nCode`*\ -[in] Identifies the command notification code. See [`CCmdTarget::OnCmdMsg`](../../mfc/reference/ccmdtarget-class.md#oncmdmsg) for more information about values for *`nCode`*. +[in] Identifies the command notification code. For more information about values for *`nCode`*, see [`CCmdTarget::OnCmdMsg`](../../mfc/reference/ccmdtarget-class.md#oncmdmsg). *`pExtra`*\ -[in] Used according to the value of *`nCode`*. See [`CCmdTarget::OnCmdMsg`](../../mfc/reference/ccmdtarget-class.md#oncmdmsg) for more information about *`pExtra`*. +[in] Used according to the value of *`nCode`*. For more information about *`pExtra`*, see [`CCmdTarget::OnCmdMsg`](../../mfc/reference/ccmdtarget-class.md#oncmdmsg). *`pHandlerInfo`*\ -[in, out] Typically, this parameter should be `NULL`.If not `NULL`, `OnCmdMsg` fills in the `pTarget` and `pmf` members of the *`pHandlerInfo`* structure instead of dispatching the command. +[in, out] Typically, this parameter should be `NULL`. If not `NULL`, `OnCmdMsg` fills in the `pTarget` and `pmf` members of the *`pHandlerInfo`* structure instead of dispatching the command. -### Return Value +### Return value Nonzero if the message is handled; otherwise 0. @@ -1271,7 +1257,7 @@ Nonzero if the message is handled; otherwise 0. Called by the framework when the image associated with a menu item is drawn. -``` +```cpp virtual BOOL OnDrawMenuImage( CDC* pDC, const CMFCToolBarMenuButton* pMenuButton, @@ -1289,7 +1275,7 @@ virtual BOOL OnDrawMenuImage( *`rectImage`*\ [in] Bounding rectangle of the image. -### Return Value +### Return value `TRUE` if the method draws the image. The default implementation returns `FALSE`. @@ -1299,9 +1285,9 @@ 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( CDC*, CMFCPopupMenu*, @@ -1316,11 +1302,11 @@ Override this function to display a logo on the pop-up menu that belongs to the Called by the framework when the MDI frame window processes a `WM_ERASEBKGND` message. -``` +```cpp virtual BOOL OnEraseMDIClientBackground(CDC*); ``` -### Return Value +### Return value `TRUE` if the application processes the message and erases the background. @@ -1330,9 +1316,9 @@ 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( CMFCToolBarButton* pButton, TOOLINFO* pTI); @@ -1346,7 +1332,7 @@ virtual BOOL OnMenuButtonToolHitTest( *`pTI`*\ [out] Pointer to a [`TOOLINFO`](/windows/win32/api/commctrl/ns-commctrl-tttoolinfoa) structure. -### Return Value +### Return value `TRUE` if the application fills the *`pTI`* parameter. The default implementation returns `FALSE`. @@ -1358,7 +1344,7 @@ Override this method if you want to provide information about specific menu item Called by the framework to move a mini-frame window. -``` +```cpp virtual BOOL OnMoveMiniFrame(CWnd* pFrame); ``` @@ -1367,7 +1353,7 @@ virtual BOOL OnMoveMiniFrame(CWnd* pFrame); *`pFrame`*\ [in] A pointer to a mini-frame window. -### Return Value +### Return value `TRUE` if the method succeeds, otherwise `FALSE`. @@ -1375,7 +1361,7 @@ virtual BOOL OnMoveMiniFrame(CWnd* pFrame); Sets the application's main frame window print-preview mode. -``` +```cpp virtual void OnSetPreviewMode( BOOL bPreview, CPrintPreviewState* pState); @@ -1397,7 +1383,7 @@ This method overrides [`CFrameWnd::OnSetPreviewMode`](../../mfc/reference/cframe Called by the framework when a Quick Customize pane is activated. -``` +```cpp virtual BOOL OnShowCustomizePane( CMFCPopupMenu* pMenuPane, UINT uiToolbarID); @@ -1411,7 +1397,7 @@ virtual BOOL OnShowCustomizePane( *`uiToolbarID`*\ [in] Control ID of the toolbar to customize. -### Return Value +### Return value This method always returns `TRUE`. @@ -1425,7 +1411,7 @@ Override this method in a derived class to make changes in the Quick Customize p Called by the framework before a shortcut menu is displayed on one of the tabs. Valid for MDI Tabbed Groups only. -``` +```cpp virtual BOOL OnShowMDITabContextMenu( CPoint point, DWORD dwAllowedItems, @@ -1441,19 +1427,15 @@ virtual BOOL OnShowMDITabContextMenu( [in] A bitwise "or" (`|`) combination of flags that indicates what actions are allowed for the current tab: - `AFX_MDI_CREATE_VERT_GROUP` - can create a vertical tab group. - - `AFX_MDI_CREATE_HORZ_GROUP` - can create a horizontal tab group. - - `AFX_MDI_CAN_MOVE_PREV` - can move a tab to the previous tab group. - - `AFX_MDI_CAN_MOVE_NEXT` - can move a tab to the next tab group. - - `AFX_MDI_CAN_BE_DOCKED` - switch a tabbed document to docked state (relevant for tabbed documents only). *`bTabDrop`*\ [in] `TRUE` to display the menu as a result of dragging the tab onto another tabbed group. `FALSE` to display the menu as a shortcut menu on the currently active tab. -### Return Value +### Return value Override this method in a [`CMDIFrameWndEx`](../../mfc/reference/cmdiframewndex-class.md)-derived class. @@ -1471,7 +1453,7 @@ The following example shows how `OnShowMDITabContextMenu` is used in the [Visual Called by the framework to show or hide panes. -``` +```cpp virtual BOOL OnShowPanes(BOOL bShow); ``` @@ -1480,9 +1462,9 @@ virtual BOOL OnShowPanes(BOOL bShow); *`bShow`*\ [in] `TRUE` to show panes, `FALSE` to hide panes. -### Return Value +### Return value -`TRUE` if the state of the panes changes as a result of calling this method, `FALSE` if the panes are already in the state specified by *`bShow`*. For example, if the panes are hidden and *`bShow`* is `FALSE`, the return value is `FALSE`. +`TRUE` if the state of the panes changes as a result of calling this method, `FALSE` if the panes are already in the state specified by *`bShow`*. For example, if the panes are hidden and *`bShow`* is `FALSE`, the Return value is `FALSE`. ### Remarks @@ -1494,11 +1476,11 @@ If [`CDockingManager::m_bHideDockingBarsInContainerMode`](../../mfc/reference/cd Called by the framework when it opens a pop-up menu. -``` +```cpp virtual BOOL OnShowPopupMenu(CMFCPopupMenu*); ``` -### Return Value +### Return value `TRUE` if the pop-up menu is to be displayed. Otherwise, `FALSE`. The default implementation returns `TRUE`. @@ -1512,7 +1494,7 @@ The default implementation does nothing. Called by the framework when the size of the client MDI window is changing. -``` +```cpp virtual void OnSizeMDIClient( const CRect& rectOld, const CRect& rectNew); @@ -1532,7 +1514,7 @@ virtual void OnSizeMDIClient( Called by the framework when a menu that has a tear-off bar is activated. -``` +```cpp virtual BOOL OnTearOffMenu( CMFCPopupMenu* pMenuPopup, CPane* pBar); @@ -1546,7 +1528,7 @@ virtual BOOL OnTearOffMenu( *`pBar`*\ [in] A pointer to the tear-off bar. -### Return Value +### Return value `TRUE` to allow the pop-up menu with the tear-off bar to be made activate; otherwise `FALSE`. The default is `TRUE`. @@ -1558,7 +1540,7 @@ Override this function when you want to implement a special setup for the tear-o Called by the framework to update the frame menu. -``` +```cpp virtual void OnUpdateFrameMenu(HMENU hMenuAlt); ``` @@ -1571,7 +1553,7 @@ virtual void OnUpdateFrameMenu(HMENU hMenuAlt); Returns the docking pane that contains the specified point. -``` +```cpp CBasePane* PaneFromPoint( CPoint point, int nSensitivity, @@ -1602,19 +1584,19 @@ CBasePane* PaneFromPoint( *`dwAlignment`*\ [out] If a pane is found, this parameter will specify which side of the pane is closest to the specified point. -### Return Value +### Return value A pointer to a docking pane, or `NULL` if no control contains the point specified by *`point`*. ### Remarks -The call is redirected to the [`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md). See [`CDockingManager::ControlBarFromPoint`](../../mfc/reference/cdockingmanager-class.md#panefrompoint) for more information. +The call is redirected to the [`CDockingManager` class](../../mfc/reference/cdockingmanager-class.md). For more information, see [`CDockingManager::ControlBarFromPoint`](../../mfc/reference/cdockingmanager-class.md#panefrompoint). ## `CMDIFrameWndEx::RecalcLayout` Called by the framework to recalculate the layout of the frame window. -``` +```cpp virtual void RecalcLayout(BOOL bNotify = TRUE); ``` @@ -1667,7 +1649,7 @@ Use this method when a pane is no longer a part of the docking layout of the fra Saves the current layout of MDI Tabbed Groups and the list of previously opened documents. -``` +```cpp virtual BOOL SaveMDIState(LPCTSTR lpszProfileName); ``` @@ -1676,7 +1658,7 @@ virtual BOOL SaveMDIState(LPCTSTR lpszProfileName); *`lpszProfileName`*\ [in] Specifies the profile name. -### Return Value +### Return value `TRUE` if the save succeeded; `FALSE` if the save failed. @@ -1685,15 +1667,10 @@ virtual BOOL SaveMDIState(LPCTSTR lpszProfileName); To load or save the state of MDI tabs and groups and the list of opened documents, do the following: - Call `SaveMDIState` when the main frame is being closed - - Call [`CMDIFrameWndEx::LoadMDIState`](#loadmdistate) when the main frame is being created. The recommended location for this call is before the main frame is displayed for the first time. - - Call `CWinAppEx::EnableLoadWindowPlacement(FALSE);` before `pMainFrame->LoadFrame (IDR_MAINFRAME);` - - Call `CWinAppEx::ReloadWindowPlacement(pMainFrame)` after `LoadMDIState` to display the main frame at the position that was stored in the registry. - - Override `GetDocumentName` in the `CMDIChildWndEx`- derived class if your application displays documents that aren't stored as files. The returned string will be saved in the registry as a document identifier. For more information, see [`CMDIChildWndEx::GetDocumentName`](../../mfc/reference/cmdichildwndex-class.md#getdocumentname). - - Override [`CMDIFrameWndEx::CreateDocumentWindow`](#createdocumentwindow) to correctly create documents when they're loaded from the registry. The parameter to `CreateDocumentWindow` is the string that `GetDocumentName` returned earlier. ### Example @@ -1731,7 +1708,7 @@ void SetupToolbarMenu( ### Parameters *`menu`*\ -[in] A reference to a [`CMenu` Class](../../mfc/reference/cmenu-class.md) object to be modified. +[in] A reference to a [`CMenu` class](../../mfc/reference/cmenu-class.md) object to be modified. *`uiViewUserToolbarCmdFirst`*\ [in] Specifies the first user-defined command. @@ -1773,7 +1750,7 @@ void ShowPane( [in] `TRUE` to delay the recalculation of the docking layout. `FALSE` to recalculate the docking layout immediately. *`bActivate`*\ -[in] `TRUE` to show the pane should as active. `FALSE` to show the pane as inactive. +[in] `TRUE` to show the pane as active. `FALSE` to show the pane as inactive. ### Remarks @@ -1803,7 +1780,7 @@ The following example shows how `ShowWindowsDialog` is used in the [VisualStudio Converts the specified tabbed document to a docking pane. -``` +```cpp virtual BOOL TabbedDocumentToControlBar(CMDIChildWndEx* pMDIChildWnd); ``` @@ -1812,7 +1789,7 @@ virtual BOOL TabbedDocumentToControlBar(CMDIChildWndEx* pMDIChildWnd); *`pMDIChildWnd`*\ A pointer to MDI child window that contains a docking pane. -### Return Value +### Return value `TRUE` if the method was successful, `FALSE` on failure. @@ -1848,7 +1825,7 @@ void UpdateMDITabbedBarsIcons(); Called by the framework to initiate the WinHelp application or context help. -``` +```cpp virtual void WinHelp( DWORD dwData, UINT nCmd = HELP_CONTEXT); @@ -1860,7 +1837,7 @@ virtual void WinHelp( [in] Specifies data as required for the type of help specified by *`nCmd`*. *`nCmd`*\ -[in] Specifies the type of help requested. For a list of possible values and how they affect the *`dwData`* parameter, see the [WinHelp Function](/windows/win32/api/winuser/nf-winuser-winhelpw) in the Windows SDK. +[in] Specifies the type of help requested. For more information about the possible values and how they affect the *`dwData`* parameter, see [`WinHelp`](/windows/win32/api/winuser/nf-winuser-winhelpw). ### Remarks @@ -1870,5 +1847,5 @@ This method overrides [`CWnd::WinHelp`](../../mfc/reference/cwnd-class.md#winhel [Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [Classes](../../mfc/reference/mfc-classes.md)\ -[`CMDIFrameWnd`](../../mfc/reference/cframewnd-class.md)\ -[`CMDIChildWndEx` Class](../../mfc/reference/cmdichildwndex-class.md) +[`CMDIFrameWnd` class](../../mfc/reference/cframewnd-class.md)\ +[`CMDIChildWndEx` class](../../mfc/reference/cmdichildwndex-class.md) diff --git a/docs/mfc/reference/cmditabinfo-class.md b/docs/mfc/reference/cmditabinfo-class.md index 1f9cfbb1760..d2ef90ec29b 100644 --- a/docs/mfc/reference/cmditabinfo-class.md +++ b/docs/mfc/reference/cmditabinfo-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CMDITabInfo Class" title: "CMDITabInfo Class" -ms.date: "11/04/2016" +description: "Learn more about: CMDITabInfo Class" +ms.date: 11/04/2016 f1_keywords: ["CMDITabInfo", "AFXMDICLIENTAREAWND/CMDITabInfo", "AFXMDICLIENTAREAWND/CMDITabInfo::Serialize", "AFXMDICLIENTAREAWND/CMDITabInfo::m_bAutoColor", "AFXMDICLIENTAREAWND/CMDITabInfo::m_bDocumentMenu", "AFXMDICLIENTAREAWND/CMDITabInfo::m_bEnableTabSwap", "AFXMDICLIENTAREAWND/CMDITabInfo::m_bFlatFrame", "AFXMDICLIENTAREAWND/CMDITabInfo::m_bTabCloseButton", "AFXMDICLIENTAREAWND/CMDITabInfo::m_bTabCustomTooltips", "AFXMDICLIENTAREAWND/CMDITabInfo::m_bTabIcons", "AFXMDICLIENTAREAWND/CMDITabInfo::m_nTabBorderSize", "AFXMDICLIENTAREAWND/CMDITabInfo::m_style", "AFXMDICLIENTAREAWND/CMDITabInfo::m_tabLocation"] helpviewer_keywords: ["CMDITabInfo [MFC], Serialize", "CMDITabInfo [MFC], m_bAutoColor", "CMDITabInfo [MFC], m_bDocumentMenu", "CMDITabInfo [MFC], m_bEnableTabSwap", "CMDITabInfo [MFC], m_bFlatFrame", "CMDITabInfo [MFC], m_bTabCloseButton", "CMDITabInfo [MFC], m_bTabCustomTooltips", "CMDITabInfo [MFC], m_bTabIcons", "CMDITabInfo [MFC], m_nTabBorderSize", "CMDITabInfo [MFC], m_style", "CMDITabInfo [MFC], m_tabLocation"] -ms.assetid: 988ae1b7-4f7f-4239-b88f-7e28b3291c5e --- # CMDITabInfo Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMDITabInfo` class is 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. ## Syntax @@ -64,7 +66,7 @@ The following example demonstrates how to set the values of the various member v **Header:** afxmdiclientareawnd.h -## CMDITabInfo::m_bActiveTabCloseButton; +## CMDITabInfo::m_bActiveTabCloseButton Specifies whether a **Close** button is displayed on the label of the active tab. diff --git a/docs/mfc/reference/cmemfile-class.md b/docs/mfc/reference/cmemfile-class.md index cef271bf9c3..4fdaeeddc42 100644 --- a/docs/mfc/reference/cmemfile-class.md +++ b/docs/mfc/reference/cmemfile-class.md @@ -1,13 +1,15 @@ --- 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" -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"] +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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CFile](../../mfc/reference/cfile-class.md)-derived class that supports memory files. ## Syntax @@ -86,7 +88,7 @@ virtual BYTE* Alloc(SIZE_T nBytes); ### Parameters -*nBytes*
+*nBytes*\ Number of bytes of memory to be allocated. ### Return Value @@ -112,13 +114,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 +129,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 +148,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 +181,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 +193,7 @@ virtual void Free(BYTE* lpMem); ### Parameters -*lpMem*
+*lpMem*\ Pointer to the memory to be deallocated. ### Remarks @@ -213,16 +215,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 +254,7 @@ virtual void GrowFile(SIZE_T dwNewLen); ### Parameters -*dwNewLen*
+*dwNewLen*\ New size of the memory file. ### Remarks @@ -272,13 +274,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 +303,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 +319,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/cmemoryexception-class.md b/docs/mfc/reference/cmemoryexception-class.md index d7afee5e522..42c37ca9bcc 100644 --- a/docs/mfc/reference/cmemoryexception-class.md +++ b/docs/mfc/reference/cmemoryexception-class.md @@ -4,10 +4,12 @@ title: "CMemoryException Class" ms.date: "11/04/2016" f1_keywords: ["CMemoryException", "AFX/CMemoryException", "AFX/CMemoryException::CMemoryException"] helpviewer_keywords: ["CMemoryException [MFC], CMemoryException"] -ms.assetid: 9af0ed57-d12a-45ca-82b5-c910a60f7edf --- # CMemoryException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an out-of-memory exception condition. ## Syntax diff --git a/docs/mfc/reference/cmemorystate-structure.md b/docs/mfc/reference/cmemorystate-structure.md index a81816fc534..9f6a7f3f41f 100644 --- a/docs/mfc/reference/cmemorystate-structure.md +++ b/docs/mfc/reference/cmemorystate-structure.md @@ -4,10 +4,12 @@ title: "CMemoryState Structure" ms.date: "11/04/2016" f1_keywords: ["CMemoryState"] helpviewer_keywords: ["CMemoryState structure [MFC]", "memory leaks [MFC], detecting", "detecting memory leaks [MFC]"] -ms.assetid: 229d9de7-a6f3-4cc6-805b-5a9d9b1bfe1d --- # CMemoryState Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides a convenient way to detect memory leaks in your program. ## Syntax diff --git a/docs/mfc/reference/cmenu-class.md b/docs/mfc/reference/cmenu-class.md index 2b144ffb589..7cf5c9589a0 100644 --- a/docs/mfc/reference/cmenu-class.md +++ b/docs/mfc/reference/cmenu-class.md @@ -4,10 +4,12 @@ title: "CMenu Class" ms.date: "11/04/2016" f1_keywords: ["CMenu", "AFXWIN/CMenu", "AFXWIN/CMenu::CMenu", "AFXWIN/CMenu::AppendMenu", "AFXWIN/CMenu::Attach", "AFXWIN/CMenu::CheckMenuItem", "AFXWIN/CMenu::CheckMenuRadioItem", "AFXWIN/CMenu::CreateMenu", "AFXWIN/CMenu::CreatePopupMenu", "AFXWIN/CMenu::DeleteMenu", "AFXWIN/CMenu::DeleteTempMap", "AFXWIN/CMenu::DestroyMenu", "AFXWIN/CMenu::Detach", "AFXWIN/CMenu::DrawItem", "AFXWIN/CMenu::EnableMenuItem", "AFXWIN/CMenu::FromHandle", "AFXWIN/CMenu::GetDefaultItem", "AFXWIN/CMenu::GetMenuContextHelpId", "AFXWIN/CMenu::GetMenuInfo", "AFXWIN/CMenu::GetMenuItemCount", "AFXWIN/CMenu::GetMenuItemID", "AFXWIN/CMenu::GetMenuItemInfo", "AFXWIN/CMenu::GetMenuState", "AFXWIN/CMenu::GetMenuString", "AFXWIN/CMenu::GetSafeHmenu", "AFXWIN/CMenu::GetSubMenu", "AFXWIN/CMenu::InsertMenu", "AFXWIN/CMenu::InsertMenuItem", "AFXWIN/CMenu::LoadMenu", "AFXWIN/CMenu::LoadMenuIndirect", "AFXWIN/CMenu::MeasureItem", "AFXWIN/CMenu::ModifyMenu", "AFXWIN/CMenu::RemoveMenu", "AFXWIN/CMenu::SetDefaultItem", "AFXWIN/CMenu::SetMenuContextHelpId", "AFXWIN/CMenu::SetMenuInfo", "AFXWIN/CMenu::SetMenuItemBitmaps", "AFXWIN/CMenu::SetMenuItemInfo", "AFXWIN/CMenu::TrackPopupMenu", "AFXWIN/CMenu::TrackPopupMenuEx", "AFXWIN/CMenu::m_hMenu"] helpviewer_keywords: ["CMenu [MFC], CMenu", "CMenu [MFC], AppendMenu", "CMenu [MFC], Attach", "CMenu [MFC], CheckMenuItem", "CMenu [MFC], CheckMenuRadioItem", "CMenu [MFC], CreateMenu", "CMenu [MFC], CreatePopupMenu", "CMenu [MFC], DeleteMenu", "CMenu [MFC], DeleteTempMap", "CMenu [MFC], DestroyMenu", "CMenu [MFC], Detach", "CMenu [MFC], DrawItem", "CMenu [MFC], EnableMenuItem", "CMenu [MFC], FromHandle", "CMenu [MFC], GetDefaultItem", "CMenu [MFC], GetMenuContextHelpId", "CMenu [MFC], GetMenuInfo", "CMenu [MFC], GetMenuItemCount", "CMenu [MFC], GetMenuItemID", "CMenu [MFC], GetMenuItemInfo", "CMenu [MFC], GetMenuState", "CMenu [MFC], GetMenuString", "CMenu [MFC], GetSafeHmenu", "CMenu [MFC], GetSubMenu", "CMenu [MFC], InsertMenu", "CMenu [MFC], InsertMenuItem", "CMenu [MFC], LoadMenu", "CMenu [MFC], LoadMenuIndirect", "CMenu [MFC], MeasureItem", "CMenu [MFC], ModifyMenu", "CMenu [MFC], RemoveMenu", "CMenu [MFC], SetDefaultItem", "CMenu [MFC], SetMenuContextHelpId", "CMenu [MFC], SetMenuInfo", "CMenu [MFC], SetMenuItemBitmaps", "CMenu [MFC], SetMenuItemInfo", "CMenu [MFC], TrackPopupMenu", "CMenu [MFC], TrackPopupMenuEx", "CMenu [MFC], m_hMenu"] -ms.assetid: 40cacfdc-d45c-4ec7-bf28-991c72812499 --- # `CMenu` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An encapsulation of the Windows `HMENU`. ## Syntax @@ -1286,7 +1288,7 @@ The Windows `GetMenuCheckMarkDimensions` function retrieves the dimensions of th ### Example [!code-cpp[NVC_MFCWindowing#32](../../mfc/reference/codesnippet/cpp/cmenu-class_12.cpp)] - +  [!code-cpp[NVC_MFCWindowing#33](../../mfc/reference/codesnippet/cpp/cmenu-class_13.cpp)] ## `CMenu::SetMenuItemInfo` diff --git a/docs/mfc/reference/cmenutearoffmanager-class.md b/docs/mfc/reference/cmenutearoffmanager-class.md index 3aeb8d41a0b..d4fea412a20 100644 --- a/docs/mfc/reference/cmenutearoffmanager-class.md +++ b/docs/mfc/reference/cmenutearoffmanager-class.md @@ -4,10 +4,12 @@ title: "CMenuTearOffManager Class" ms.date: "10/18/2018" f1_keywords: ["CMenuTearOffManager", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::CMenuTearOffManager", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::Build", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::GetRegPath", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::Initialize", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::IsDynamicID", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::Parse", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::Reset", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::SetInUse", "AFXMENUTEAROFFMANAGER/CMenuTearOffManager::SetupTearOffMenus"] helpviewer_keywords: ["CMenuTearOffManager [MFC], CMenuTearOffManager", "CMenuTearOffManager [MFC], Build", "CMenuTearOffManager [MFC], GetRegPath", "CMenuTearOffManager [MFC], Initialize", "CMenuTearOffManager [MFC], IsDynamicID", "CMenuTearOffManager [MFC], Parse", "CMenuTearOffManager [MFC], Reset", "CMenuTearOffManager [MFC], SetInUse", "CMenuTearOffManager [MFC], SetupTearOffMenus"] -ms.assetid: ab7ca272-ce42-4678-95f7-6ad75038f5a0 --- # CMenuTearOffManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmetafiledc-class.md b/docs/mfc/reference/cmetafiledc-class.md index 247113ce933..cbbca361521 100644 --- a/docs/mfc/reference/cmetafiledc-class.md +++ b/docs/mfc/reference/cmetafiledc-class.md @@ -4,10 +4,12 @@ title: "CMetaFileDC Class" ms.date: "11/04/2016" f1_keywords: ["CMetaFileDC", "AFXEXT/CMetaFileDC", "AFXEXT/CMetaFileDC::CMetaFileDC", "AFXEXT/CMetaFileDC::Close", "AFXEXT/CMetaFileDC::CloseEnhanced", "AFXEXT/CMetaFileDC::Create", "AFXEXT/CMetaFileDC::CreateEnhanced"] helpviewer_keywords: ["CMetaFileDC [MFC], CMetaFileDC", "CMetaFileDC [MFC], Close", "CMetaFileDC [MFC], CloseEnhanced", "CMetaFileDC [MFC], Create", "CMetaFileDC [MFC], CreateEnhanced"] -ms.assetid: ffce60fa-4181-4d46-9832-25e46fad4db4 --- # CMetaFileDC Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax diff --git a/docs/mfc/reference/cmfcacceleratorkey-class.md b/docs/mfc/reference/cmfcacceleratorkey-class.md index cea5e0154c5..ceef60ee03b 100644 --- a/docs/mfc/reference/cmfcacceleratorkey-class.md +++ b/docs/mfc/reference/cmfcacceleratorkey-class.md @@ -4,10 +4,12 @@ title: "CMFCAcceleratorKey Class" ms.date: "11/04/2016" f1_keywords: ["CMFCAcceleratorKey", "AFXACCELERATORKEY/CMFCAcceleratorKey", "AFXACCELERATORKEY/CMFCAcceleratorKey::CMFCAcceleratorKey", "AFXACCELERATORKEY/CMFCAcceleratorKey::Format", "AFXACCELERATORKEY/CMFCAcceleratorKey::SetAccelerator"] helpviewer_keywords: ["CMFCAcceleratorKey [MFC], CMFCAcceleratorKey", "CMFCAcceleratorKey [MFC], Format", "CMFCAcceleratorKey [MFC], SetAccelerator"] -ms.assetid: d140fbf7-23db-45ea-a63e-414a5ec7b3d5 --- # CMFCAcceleratorKey Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A helper class that implements virtual key mapping and formatting. ## Syntax diff --git a/docs/mfc/reference/cmfcacceleratorkeyassignctrl-class.md b/docs/mfc/reference/cmfcacceleratorkeyassignctrl-class.md index 24c02779510..dadb4244270 100644 --- a/docs/mfc/reference/cmfcacceleratorkeyassignctrl-class.md +++ b/docs/mfc/reference/cmfcacceleratorkeyassignctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCAcceleratorKeyAssignCtrl Class" ms.date: "10/18/2018" f1_keywords: ["CMFCAcceleratorKeyAssignCtrl", "AFXACCELERATORKEYASSIGNCTRL/CMFCAcceleratorKeyAssignCtrl", "AFXACCELERATORKEYASSIGNCTRL/CMFCAcceleratorKeyAssignCtrl::CMFCAcceleratorKeyAssignCtrl", "AFXACCELERATORKEYASSIGNCTRL/CMFCAcceleratorKeyAssignCtrl::GetAccel", "AFXACCELERATORKEYASSIGNCTRL/CMFCAcceleratorKeyAssignCtrl::IsFocused", "AFXACCELERATORKEYASSIGNCTRL/CMFCAcceleratorKeyAssignCtrl::IsKeyDefined", "AFXACCELERATORKEYASSIGNCTRL/CMFCAcceleratorKeyAssignCtrl::PreTranslateMessage", "AFXACCELERATORKEYASSIGNCTRL/CMFCAcceleratorKeyAssignCtrl::ResetKey"] helpviewer_keywords: ["CMFCAcceleratorKeyAssignCtrl [MFC], CMFCAcceleratorKeyAssignCtrl", "CMFCAcceleratorKeyAssignCtrl [MFC], GetAccel", "CMFCAcceleratorKeyAssignCtrl [MFC], IsFocused", "CMFCAcceleratorKeyAssignCtrl [MFC], IsKeyDefined", "CMFCAcceleratorKeyAssignCtrl [MFC], PreTranslateMessage", "CMFCAcceleratorKeyAssignCtrl [MFC], ResetKey"] -ms.assetid: 89fb8e62-596e-4e71-8c9a-32740347aaab --- # CMFCAcceleratorKeyAssignCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCAcceleratorKeyAssignCtrl` class extends the [CEdit Class](../../mfc/reference/cedit-class.md) to support extra system buttons such as ALT, CONTROL, and SHIFT. ## Syntax diff --git a/docs/mfc/reference/cmfcautohidebar-class.md b/docs/mfc/reference/cmfcautohidebar-class.md index 120b1d8303a..20ad6d6369f 100644 --- a/docs/mfc/reference/cmfcautohidebar-class.md +++ b/docs/mfc/reference/cmfcautohidebar-class.md @@ -4,10 +4,12 @@ title: "CMFCAutoHideBar Class" ms.date: "10/18/2018" f1_keywords: ["CMFCAutoHideBar", "AFXAUTOHIDEBAR/CMFCAutoHideBar", "AFXAUTOHIDEBAR/CMFCAutoHideBar::CMFCAutoHideBar", "AFXAUTOHIDEBAR/CMFCAutoHideBar::AddAutoHideWindow", "AFXAUTOHIDEBAR/CMFCAutoHideBar::AllowShowOnPaneMenu", "AFXAUTOHIDEBAR/CMFCAutoHideBar::CalcFixedLayout", "AFXAUTOHIDEBAR/CMFCAutoHideBar::Create", "AFXAUTOHIDEBAR/CMFCAutoHideBar::GetFirstAHWindow", "AFXAUTOHIDEBAR/CMFCAutoHideBar::GetVisibleCount", "AFXAUTOHIDEBAR/CMFCAutoHideBar::OnShowControlBarMenu", "AFXAUTOHIDEBAR/CMFCAutoHideBar::RemoveAutoHideWindow", "AFXAUTOHIDEBAR/CMFCAutoHideBar::SetActiveInGroup", "AFXAUTOHIDEBAR/CMFCAutoHideBar::SetRecentVisibleState", "AFXAUTOHIDEBAR/CMFCAutoHideBar::ShowAutoHideWindow", "AFXAUTOHIDEBAR/CMFCAutoHideBar::StretchPane", "AFXAUTOHIDEBAR/CMFCAutoHideBar::UnSetAutoHideMode", "AFXAUTOHIDEBAR/CMFCAutoHideBar::UpdateVisibleState", "AFXAUTOHIDEBAR/CMFCAutoHideBar::m_nShowAHWndDelay"] helpviewer_keywords: ["CMFCAutoHideBar [MFC], CMFCAutoHideBar", "CMFCAutoHideBar [MFC], AddAutoHideWindow", "CMFCAutoHideBar [MFC], AllowShowOnPaneMenu", "CMFCAutoHideBar [MFC], CalcFixedLayout", "CMFCAutoHideBar [MFC], Create", "CMFCAutoHideBar [MFC], GetFirstAHWindow", "CMFCAutoHideBar [MFC], GetVisibleCount", "CMFCAutoHideBar [MFC], OnShowControlBarMenu", "CMFCAutoHideBar [MFC], RemoveAutoHideWindow", "CMFCAutoHideBar [MFC], SetActiveInGroup", "CMFCAutoHideBar [MFC], SetRecentVisibleState", "CMFCAutoHideBar [MFC], ShowAutoHideWindow", "CMFCAutoHideBar [MFC], StretchPane", "CMFCAutoHideBar [MFC], UnSetAutoHideMode", "CMFCAutoHideBar [MFC], UpdateVisibleState", "CMFCAutoHideBar [MFC], m_nShowAHWndDelay"] -ms.assetid: 54c8d84f-de64-4efd-8a47-3ea0ade40a70 --- # CMFCAutoHideBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCAutoHideBar` class is a special toolbar class that implements the auto-hide feature. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcautohidebutton-class.md b/docs/mfc/reference/cmfcautohidebutton-class.md index a1b6dfaa421..1b1561fd267 100644 --- a/docs/mfc/reference/cmfcautohidebutton-class.md +++ b/docs/mfc/reference/cmfcautohidebutton-class.md @@ -4,10 +4,12 @@ title: "CMFCAutoHideButton Class" ms.date: "10/18/2018" f1_keywords: ["CMFCAutoHideButton", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::BringToTop", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::Create", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::GetAlignment", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::GetAutoHideWindow", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::GetParentToolBar", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::GetRect", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::GetSize", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::GetTextSize", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::HighlightButton", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::IsActive", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::IsHighlighted", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::IsHorizontal", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::IsTop", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::IsVisible", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::Move", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::OnDraw", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::OnDrawBorder", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::OnFillBackground", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::ReplacePane", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::ShowAttachedWindow", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::ShowButton", "AFXAUTOHIDEBUTTON/CMFCAutoHideButton::UnSetAutoHideMode"] helpviewer_keywords: ["CMFCAutoHideButton [MFC], BringToTop", "CMFCAutoHideButton [MFC], Create", "CMFCAutoHideButton [MFC], GetAlignment", "CMFCAutoHideButton [MFC], GetAutoHideWindow", "CMFCAutoHideButton [MFC], GetParentToolBar", "CMFCAutoHideButton [MFC], GetRect", "CMFCAutoHideButton [MFC], GetSize", "CMFCAutoHideButton [MFC], GetTextSize", "CMFCAutoHideButton [MFC], HighlightButton", "CMFCAutoHideButton [MFC], IsActive", "CMFCAutoHideButton [MFC], IsHighlighted", "CMFCAutoHideButton [MFC], IsHorizontal", "CMFCAutoHideButton [MFC], IsTop", "CMFCAutoHideButton [MFC], IsVisible", "CMFCAutoHideButton [MFC], Move", "CMFCAutoHideButton [MFC], OnDraw", "CMFCAutoHideButton [MFC], OnDrawBorder", "CMFCAutoHideButton [MFC], OnFillBackground", "CMFCAutoHideButton [MFC], ReplacePane", "CMFCAutoHideButton [MFC], ShowAttachedWindow", "CMFCAutoHideButton [MFC], ShowButton", "CMFCAutoHideButton [MFC], UnSetAutoHideMode"] -ms.assetid: c80e6b8b-25ca-4d12-9d27-457731028ab0 --- # CMFCAutoHideButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A button that displays or hides a [CDockablePane Class](../../mfc/reference/cdockablepane-class.md) that is configured to hide. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcbasetabctrl-class.md b/docs/mfc/reference/cmfcbasetabctrl-class.md index b20f815af9d..519bcbeb027 100644 --- a/docs/mfc/reference/cmfcbasetabctrl-class.md +++ b/docs/mfc/reference/cmfcbasetabctrl-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the base functionality for tabbed windows. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -210,7 +212,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 +319,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 +1759,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 +2140,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/cmfcbasetoolbar-class.md b/docs/mfc/reference/cmfcbasetoolbar-class.md index 39389c20bd7..d9a2eb12cae 100644 --- a/docs/mfc/reference/cmfcbasetoolbar-class.md +++ b/docs/mfc/reference/cmfcbasetoolbar-class.md @@ -4,10 +4,12 @@ title: "CMFCBaseToolBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCBaseToolBar", "AFXBASETOOLBAR/CMFCBaseToolBar", "AFXBASETOOLBAR/CMFCBaseToolBar::GetDockingMode", "AFXBASETOOLBAR/CMFCBaseToolBar::GetMinSize", "AFXBASETOOLBAR/CMFCBaseToolBar::OnAfterChangeParent"] helpviewer_keywords: ["CMFCBaseToolBar [MFC], GetDockingMode", "CMFCBaseToolBar [MFC], GetMinSize", "CMFCBaseToolBar [MFC], OnAfterChangeParent"] -ms.assetid: 5d79206d-55e4-46f8-b1b8-042e34d7f9da --- # CMFCBaseToolBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Base class for toolbars. ## Syntax diff --git a/docs/mfc/reference/cmfcbasevisualmanager-class.md b/docs/mfc/reference/cmfcbasevisualmanager-class.md index c6e2eacfb4a..e092d50743a 100644 --- a/docs/mfc/reference/cmfcbasevisualmanager-class.md +++ b/docs/mfc/reference/cmfcbasevisualmanager-class.md @@ -4,10 +4,12 @@ title: "CMFCBaseVisualManager Class" ms.date: "11/04/2016" f1_keywords: ["CMFCBaseVisualManager", "AFXVISUALMANAGER/CMFCBaseVisualManager", "AFXVISUALMANAGER/CMFCBaseVisualManager::CMFCBaseVisualManager", "AFXVISUALMANAGER/CMFCBaseVisualManager::DrawCheckBox", "AFXVISUALMANAGER/CMFCBaseVisualManager::DrawComboBorder", "AFXVISUALMANAGER/CMFCBaseVisualManager::DrawComboDropButton", "AFXVISUALMANAGER/CMFCBaseVisualManager::DrawPushButton", "AFXVISUALMANAGER/CMFCBaseVisualManager::DrawRadioButton", "AFXVISUALMANAGER/CMFCBaseVisualManager::DrawStatusBarProgress", "AFXVISUALMANAGER/CMFCBaseVisualManager::FillReBarPane", "AFXVISUALMANAGER/CMFCBaseVisualManager::GetStandardWindowsTheme", "AFXVISUALMANAGER/CMFCBaseVisualManager::CleanUpThemes", "AFXVISUALMANAGER/CMFCBaseVisualManager::UpdateSystemColors"] helpviewer_keywords: ["CMFCBaseVisualManager [MFC], CMFCBaseVisualManager", "CMFCBaseVisualManager [MFC], DrawCheckBox", "CMFCBaseVisualManager [MFC], DrawComboBorder", "CMFCBaseVisualManager [MFC], DrawComboDropButton", "CMFCBaseVisualManager [MFC], DrawPushButton", "CMFCBaseVisualManager [MFC], DrawRadioButton", "CMFCBaseVisualManager [MFC], DrawStatusBarProgress", "CMFCBaseVisualManager [MFC], FillReBarPane", "CMFCBaseVisualManager [MFC], GetStandardWindowsTheme", "CMFCBaseVisualManager [MFC], CleanUpThemes", "CMFCBaseVisualManager [MFC], UpdateSystemColors"] -ms.assetid: d56f3afc-cdea-4de1-825a-a08999c571e0 --- # CMFCBaseVisualManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A layer between derived visual managers and the Windows Theme API. `CMFCBaseVisualManager` loads UxTheme.dll, if available, and manages access to Windows Theme API methods. diff --git a/docs/mfc/reference/cmfcbutton-class.md b/docs/mfc/reference/cmfcbutton-class.md index 5cf031c6e96..def437d5ce1 100644 --- a/docs/mfc/reference/cmfcbutton-class.md +++ b/docs/mfc/reference/cmfcbutton-class.md @@ -1,18 +1,20 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCButton` class adds functionality to the [`CButton`](../../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. ## Syntax -``` +```cpp class CMFCButton : public CButton ``` @@ -46,7 +48,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 +81,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 +128,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 +142,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 +157,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 +171,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 +188,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 +196,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 +208,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 +228,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 +236,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 +256,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 +272,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 +280,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 +292,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 +304,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 +316,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 +328,7 @@ BOOL m_bDontUseWinXPTheme; Indicates whether to draw a focus rectangle around a button. -``` +```cpp BOOL m_bDrawFocus; ``` @@ -354,7 +342,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 +350,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 +362,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 +370,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 +390,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 +402,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 +418,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 +430,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 +458,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 +467,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 +484,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 +493,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 +510,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 +518,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 +532,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 +543,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 +566,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 +574,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 +588,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 +611,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 +645,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 +693,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 +730,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 +783,7 @@ void SetMouseCursor(HCURSOR hcursor); ### Parameters -*`hcursor`*
+*`hcursor`*\ [in] The handle of a cursor. ### Remarks @@ -840,16 +822,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 +841,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 +854,9 @@ void SetTextHotColor(COLORREF clrTextHot); ### Parameters -*`clrTextHot`*
+*`clrTextHot`*\ [in] An RGB color value. -### Remarks - ## `CMFCButton::SetTooltip` Associates a tooltip with a button. @@ -891,22 +867,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 +893,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/cmfccaptionbar-class.md b/docs/mfc/reference/cmfccaptionbar-class.md index b6faf964bb5..c42a67c0d28 100644 --- a/docs/mfc/reference/cmfccaptionbar-class.md +++ b/docs/mfc/reference/cmfccaptionbar-class.md @@ -4,10 +4,12 @@ title: "CMFCCaptionBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCCaptionBar", "AFXCAPTIONBAR/CMFCCaptionBar", "AFXCAPTIONBAR/CMFCCaptionBar::Create", "AFXCAPTIONBAR/CMFCCaptionBar::DoesAllowDynInsertBefore", "AFXCAPTIONBAR/CMFCCaptionBar::EnableButton", "AFXCAPTIONBAR/CMFCCaptionBar::GetAlignment", "AFXCAPTIONBAR/CMFCCaptionBar::GetBorderSize", "AFXCAPTIONBAR/CMFCCaptionBar::GetButtonRect", "AFXCAPTIONBAR/CMFCCaptionBar::GetMargin", "AFXCAPTIONBAR/CMFCCaptionBar::IsMessageBarMode", "AFXCAPTIONBAR/CMFCCaptionBar::RemoveBitmap", "AFXCAPTIONBAR/CMFCCaptionBar::RemoveButton", "AFXCAPTIONBAR/CMFCCaptionBar::RemoveIcon", "AFXCAPTIONBAR/CMFCCaptionBar::RemoveText", "AFXCAPTIONBAR/CMFCCaptionBar::SetBitmap", "AFXCAPTIONBAR/CMFCCaptionBar::SetBorderSize", "AFXCAPTIONBAR/CMFCCaptionBar::SetButton", "AFXCAPTIONBAR/CMFCCaptionBar::SetButtonPressed", "AFXCAPTIONBAR/CMFCCaptionBar::SetButtonToolTip", "AFXCAPTIONBAR/CMFCCaptionBar::SetFlatBorder", "AFXCAPTIONBAR/CMFCCaptionBar::SetIcon", "AFXCAPTIONBAR/CMFCCaptionBar::SetImageToolTip", "AFXCAPTIONBAR/CMFCCaptionBar::SetMargin", "AFXCAPTIONBAR/CMFCCaptionBar::SetText", "AFXCAPTIONBAR/CMFCCaptionBar::OnDrawBackground", "AFXCAPTIONBAR/CMFCCaptionBar::OnDrawBorder", "AFXCAPTIONBAR/CMFCCaptionBar::OnDrawButton", "AFXCAPTIONBAR/CMFCCaptionBar::OnDrawImage", "AFXCAPTIONBAR/CMFCCaptionBar::OnDrawText", "AFXCAPTIONBAR/CMFCCaptionBar::m_clrBarBackground", "AFXCAPTIONBAR/CMFCCaptionBar::m_clrBarBorder", "AFXCAPTIONBAR/CMFCCaptionBar::m_clrBarText"] helpviewer_keywords: ["CMFCCaptionBar [MFC], Create", "CMFCCaptionBar [MFC], DoesAllowDynInsertBefore", "CMFCCaptionBar [MFC], EnableButton", "CMFCCaptionBar [MFC], GetAlignment", "CMFCCaptionBar [MFC], GetBorderSize", "CMFCCaptionBar [MFC], GetButtonRect", "CMFCCaptionBar [MFC], GetMargin", "CMFCCaptionBar [MFC], IsMessageBarMode", "CMFCCaptionBar [MFC], RemoveBitmap", "CMFCCaptionBar [MFC], RemoveButton", "CMFCCaptionBar [MFC], RemoveIcon", "CMFCCaptionBar [MFC], RemoveText", "CMFCCaptionBar [MFC], SetBitmap", "CMFCCaptionBar [MFC], SetBorderSize", "CMFCCaptionBar [MFC], SetButton", "CMFCCaptionBar [MFC], SetButtonPressed", "CMFCCaptionBar [MFC], SetButtonToolTip", "CMFCCaptionBar [MFC], SetFlatBorder", "CMFCCaptionBar [MFC], SetIcon", "CMFCCaptionBar [MFC], SetImageToolTip", "CMFCCaptionBar [MFC], SetMargin", "CMFCCaptionBar [MFC], SetText", "CMFCCaptionBar [MFC], OnDrawBackground", "CMFCCaptionBar [MFC], OnDrawBorder", "CMFCCaptionBar [MFC], OnDrawButton", "CMFCCaptionBar [MFC], OnDrawImage", "CMFCCaptionBar [MFC], OnDrawText", "CMFCCaptionBar [MFC], m_clrBarBackground", "CMFCCaptionBar [MFC], m_clrBarBorder", "CMFCCaptionBar [MFC], m_clrBarText"] -ms.assetid: acb54d5f-14ff-4c96-aeb3-7717cf566d9a --- # CMFCCaptionBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A `CMFCCaptionBar` object is a 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. ## Syntax diff --git a/docs/mfc/reference/cmfccaptionbutton-class.md b/docs/mfc/reference/cmfccaptionbutton-class.md index 645ae95d272..3c1b580936c 100644 --- a/docs/mfc/reference/cmfccaptionbutton-class.md +++ b/docs/mfc/reference/cmfccaptionbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCCaptionButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCCaptionButton", "AFXCAPTIONBUTTON/CMFCCaptionButton", "AFXCAPTIONBUTTON/CMFCCaptionButton::CMFCCaptionButton", "AFXCAPTIONBUTTON/CMFCCaptionButton::GetHit", "AFXCAPTIONBUTTON/CMFCCaptionButton::GetIconID", "AFXCAPTIONBUTTON/CMFCCaptionButton::GetRect", "AFXCAPTIONBUTTON/CMFCCaptionButton::GetSize", "AFXCAPTIONBUTTON/CMFCCaptionButton::IsMiniFrameButton", "AFXCAPTIONBUTTON/CMFCCaptionButton::Move", "AFXCAPTIONBUTTON/CMFCCaptionButton::OnDraw", "AFXCAPTIONBUTTON/CMFCCaptionButton::SetMiniFrameButton"] helpviewer_keywords: ["CMFCCaptionButton [MFC], CMFCCaptionButton", "CMFCCaptionButton [MFC], GetHit", "CMFCCaptionButton [MFC], GetIconID", "CMFCCaptionButton [MFC], GetRect", "CMFCCaptionButton [MFC], GetSize", "CMFCCaptionButton [MFC], IsMiniFrameButton", "CMFCCaptionButton [MFC], Move", "CMFCCaptionButton [MFC], OnDraw", "CMFCCaptionButton [MFC], SetMiniFrameButton"] -ms.assetid: c5774b38-c0dd-414a-9ede-3b2f78f233ec --- # CMFCCaptionButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCCaptionButton` class 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. ## Syntax diff --git a/docs/mfc/reference/cmfccmdusagecount-class.md b/docs/mfc/reference/cmfccmdusagecount-class.md index 72347cb1a62..db6d04fbc03 100644 --- a/docs/mfc/reference/cmfccmdusagecount-class.md +++ b/docs/mfc/reference/cmfccmdusagecount-class.md @@ -4,10 +4,12 @@ title: "CMFCCmdUsageCount Class" ms.date: "11/04/2016" f1_keywords: ["CMFCCmdUsageCount", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount::AddCmd", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount::GetCount", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount::HasEnoughInformation", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount::IsFreqeuntlyUsedCmd", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount::Reset", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount::Serialize", "AFXCMDUSAGECOUNT/CMFCCmdUsageCount::SetOptions"] helpviewer_keywords: ["CMFCCmdUsageCount [MFC], AddCmd", "CMFCCmdUsageCount [MFC], GetCount", "CMFCCmdUsageCount [MFC], HasEnoughInformation", "CMFCCmdUsageCount [MFC], IsFreqeuntlyUsedCmd", "CMFCCmdUsageCount [MFC], Reset", "CMFCCmdUsageCount [MFC], Serialize", "CMFCCmdUsageCount [MFC], SetOptions"] -ms.assetid: 9c33b783-37c0-43ea-9f31-3c75e246c841 --- # CMFCCmdUsageCount Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Tracks the usage count of Windows messages, such as when the user selects an item from a menu. ## Syntax diff --git a/docs/mfc/reference/cmfccolorbar-class.md b/docs/mfc/reference/cmfccolorbar-class.md index 56ffd39bac4..d423c2cacf5 100644 --- a/docs/mfc/reference/cmfccolorbar-class.md +++ b/docs/mfc/reference/cmfccolorbar-class.md @@ -4,10 +4,12 @@ title: "CMFCColorBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCColorBar", "AFXCOLORBAR/CMFCColorBar", "AFXCOLORBAR/CMFCColorBar::CMFCColorBar", "AFXCOLORBAR/CMFCColorBar::ContextToSize", "AFXCOLORBAR/CMFCColorBar::CreateControl", "AFXCOLORBAR/CMFCColorBar::Create", "AFXCOLORBAR/CMFCColorBar::EnableAutomaticButton", "AFXCOLORBAR/CMFCColorBar::EnableOtherButton", "AFXCOLORBAR/CMFCColorBar::GetColor", "AFXCOLORBAR/CMFCColorBar::GetCommandID", "AFXCOLORBAR/CMFCColorBar::GetHighlightedColor", "AFXCOLORBAR/CMFCColorBar::GetHorzMargin", "AFXCOLORBAR/CMFCColorBar::GetVertMargin", "AFXCOLORBAR/CMFCColorBar::IsTearOff", "AFXCOLORBAR/CMFCColorBar::SetColor", "AFXCOLORBAR/CMFCColorBar::SetColorName", "AFXCOLORBAR/CMFCColorBar::SetCommandID", "AFXCOLORBAR/CMFCColorBar::SetDocumentColors", "AFXCOLORBAR/CMFCColorBar::SetHorzMargin", "AFXCOLORBAR/CMFCColorBar::SetVertMargin", "AFXCOLORBAR/CMFCColorBar::AdjustLocations", "AFXCOLORBAR/CMFCColorBar::AllowChangeTextLabels", "AFXCOLORBAR/CMFCColorBar::AllowShowOnList", "AFXCOLORBAR/CMFCColorBar::CalcSize", "AFXCOLORBAR/CMFCColorBar::CreatePalette", "AFXCOLORBAR/CMFCColorBar::GetColorGridSize", "AFXCOLORBAR/CMFCColorBar::GetExtraHeight", "AFXCOLORBAR/CMFCColorBar::InitColors", "AFXCOLORBAR/CMFCColorBar::OnKey", "AFXCOLORBAR/CMFCColorBar::OnSendCommand", "AFXCOLORBAR/CMFCColorBar::OnUpdateCmdUI", "AFXCOLORBAR/CMFCColorBar::OpenColorDialog", "AFXCOLORBAR/CMFCColorBar::Rebuild", "AFXCOLORBAR/CMFCColorBar::SelectPalette", "AFXCOLORBAR/CMFCColorBar::SetPropList", "AFXCOLORBAR/CMFCColorBar::ShowCommandMessageString"] helpviewer_keywords: ["CMFCColorBar [MFC], CMFCColorBar", "CMFCColorBar [MFC], ContextToSize", "CMFCColorBar [MFC], CreateControl", "CMFCColorBar [MFC], Create", "CMFCColorBar [MFC], EnableAutomaticButton", "CMFCColorBar [MFC], EnableOtherButton", "CMFCColorBar [MFC], GetColor", "CMFCColorBar [MFC], GetCommandID", "CMFCColorBar [MFC], GetHighlightedColor", "CMFCColorBar [MFC], GetHorzMargin", "CMFCColorBar [MFC], GetVertMargin", "CMFCColorBar [MFC], IsTearOff", "CMFCColorBar [MFC], SetColor", "CMFCColorBar [MFC], SetColorName", "CMFCColorBar [MFC], SetCommandID", "CMFCColorBar [MFC], SetDocumentColors", "CMFCColorBar [MFC], SetHorzMargin", "CMFCColorBar [MFC], SetVertMargin", "CMFCColorBar [MFC], AdjustLocations", "CMFCColorBar [MFC], AllowChangeTextLabels", "CMFCColorBar [MFC], AllowShowOnList", "CMFCColorBar [MFC], CalcSize", "CMFCColorBar [MFC], CreatePalette", "CMFCColorBar [MFC], GetColorGridSize", "CMFCColorBar [MFC], GetExtraHeight", "CMFCColorBar [MFC], InitColors", "CMFCColorBar [MFC], OnKey", "CMFCColorBar [MFC], OnSendCommand", "CMFCColorBar [MFC], OnUpdateCmdUI", "CMFCColorBar [MFC], OpenColorDialog", "CMFCColorBar [MFC], Rebuild", "CMFCColorBar [MFC], SelectPalette", "CMFCColorBar [MFC], SetPropList", "CMFCColorBar [MFC], ShowCommandMessageString"] -ms.assetid: 4756ee40-25a5-4cee-af7f-acab7993d1c7 --- # CMFCColorBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCColorBar` class represents a docking control bar that can select colors in a document or application. ## Syntax @@ -78,7 +80,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/cmfccolorbutton-class.md b/docs/mfc/reference/cmfccolorbutton-class.md index dca58ef49eb..1c99ada333c 100644 --- a/docs/mfc/reference/cmfccolorbutton-class.md +++ b/docs/mfc/reference/cmfccolorbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCColorButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCColorButton", "AFXCOLORBUTTON/CMFCColorButton", "AFXCOLORBUTTON/CMFCColorButton::CMFCColorButton", "AFXCOLORBUTTON/CMFCColorButton::EnableAutomaticButton", "AFXCOLORBUTTON/CMFCColorButton::EnableOtherButton", "AFXCOLORBUTTON/CMFCColorButton::GetAutomaticColor", "AFXCOLORBUTTON/CMFCColorButton::GetColor", "AFXCOLORBUTTON/CMFCColorButton::SetColor", "AFXCOLORBUTTON/CMFCColorButton::SetColorName", "AFXCOLORBUTTON/CMFCColorButton::SetColumnsNumber", "AFXCOLORBUTTON/CMFCColorButton::SetDocumentColors", "AFXCOLORBUTTON/CMFCColorButton::SetPalette", "AFXCOLORBUTTON/CMFCColorButton::SizeToContent", "AFXCOLORBUTTON/CMFCColorButton::IsDrawXPTheme", "AFXCOLORBUTTON/CMFCColorButton::OnDraw", "AFXCOLORBUTTON/CMFCColorButton::OnDrawBorder", "AFXCOLORBUTTON/CMFCColorButton::OnDrawFocusRect", "AFXCOLORBUTTON/CMFCColorButton::OnShowColorPopup", "AFXCOLORBUTTON/CMFCColorButton::RebuildPalette", "AFXCOLORBUTTON/CMFCColorButton::UpdateColor", "AFXCOLORBUTTON/CMFCColorButton::m_bEnabledInCustomizeMode"] helpviewer_keywords: ["CMFCColorButton [MFC], CMFCColorButton", "CMFCColorButton [MFC], EnableAutomaticButton", "CMFCColorButton [MFC], EnableOtherButton", "CMFCColorButton [MFC], GetAutomaticColor", "CMFCColorButton [MFC], GetColor", "CMFCColorButton [MFC], SetColor", "CMFCColorButton [MFC], SetColorName", "CMFCColorButton [MFC], SetColumnsNumber", "CMFCColorButton [MFC], SetDocumentColors", "CMFCColorButton [MFC], SetPalette", "CMFCColorButton [MFC], SizeToContent", "CMFCColorButton [MFC], IsDrawXPTheme", "CMFCColorButton [MFC], OnDraw", "CMFCColorButton [MFC], OnDrawBorder", "CMFCColorButton [MFC], OnDrawFocusRect", "CMFCColorButton [MFC], OnShowColorPopup", "CMFCColorButton [MFC], RebuildPalette", "CMFCColorButton [MFC], UpdateColor", "CMFCColorButton [MFC], m_bEnabledInCustomizeMode"] -ms.assetid: 9fdf34ae-4cc5-4c5e-9d89-1c50e8a73699 --- # CMFCColorButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCColorButton` and [CMFCColorBar Class](../../mfc/reference/cmfccolorbar-class.md) classes are used together to implement a color picker control. ## Syntax diff --git a/docs/mfc/reference/cmfccolordialog-class.md b/docs/mfc/reference/cmfccolordialog-class.md index db781111fc2..2eac941f55d 100644 --- a/docs/mfc/reference/cmfccolordialog-class.md +++ b/docs/mfc/reference/cmfccolordialog-class.md @@ -4,10 +4,12 @@ title: "CMFCColorDialog Class" ms.date: "11/04/2016" f1_keywords: ["CMFCColorDialog", "AFXCOLORDIALOG/CMFCColorDialog", "AFXCOLORDIALOG/CMFCColorDialog::CMFCColorDialog", "AFXCOLORDIALOG/CMFCColorDialog::GetColor", "AFXCOLORDIALOG/CMFCColorDialog::GetPalette", "AFXCOLORDIALOG/CMFCColorDialog::RebuildPalette", "AFXCOLORDIALOG/CMFCColorDialog::SetCurrentColor", "AFXCOLORDIALOG/CMFCColorDialog::SetNewColor", "AFXCOLORDIALOG/CMFCColorDialog::SetPageOne", "AFXCOLORDIALOG/CMFCColorDialog::SetPageTwo"] helpviewer_keywords: ["CMFCColorDialog [MFC], CMFCColorDialog", "CMFCColorDialog [MFC], GetColor", "CMFCColorDialog [MFC], GetPalette", "CMFCColorDialog [MFC], RebuildPalette", "CMFCColorDialog [MFC], SetCurrentColor", "CMFCColorDialog [MFC], SetNewColor", "CMFCColorDialog [MFC], SetPageOne", "CMFCColorDialog [MFC], SetPageTwo"] -ms.assetid: 235bbbbc-a3b1-46e0-801b-fb55093ec579 --- # CMFCColorDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCColorDialog` class represents a color selection dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfccolormenubutton-class.md b/docs/mfc/reference/cmfccolormenubutton-class.md index e234a849f45..8298e45f61f 100644 --- a/docs/mfc/reference/cmfccolormenubutton-class.md +++ b/docs/mfc/reference/cmfccolormenubutton-class.md @@ -4,10 +4,12 @@ title: "CMFCColorMenuButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCColorMenuButton", "AFXCOLORMENUBUTTON/CMFCColorMenuButton", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::CMFCColorMenuButton", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::EnableAutomaticButton", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::EnableDocumentColors", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::EnableOtherButton", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::EnableTearOff", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::GetAutomaticColor", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::GetColor", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::GetColorByCmdID", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::OnChangeParentWnd", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::OpenColorDialog", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::SetColor", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::SetColorByCmdID", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::SetColorName", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::SetColumnsNumber", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::CopyFrom", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::CreatePopupMenu", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::IsEmptyMenuAllowed", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::OnDraw", "AFXCOLORMENUBUTTON/CMFCColorMenuButton::OnDrawOnCustomizeList"] helpviewer_keywords: ["CMFCColorMenuButton [MFC], CMFCColorMenuButton", "CMFCColorMenuButton [MFC], EnableAutomaticButton", "CMFCColorMenuButton [MFC], EnableDocumentColors", "CMFCColorMenuButton [MFC], EnableOtherButton", "CMFCColorMenuButton [MFC], EnableTearOff", "CMFCColorMenuButton [MFC], GetAutomaticColor", "CMFCColorMenuButton [MFC], GetColor", "CMFCColorMenuButton [MFC], GetColorByCmdID", "CMFCColorMenuButton [MFC], OnChangeParentWnd", "CMFCColorMenuButton [MFC], OpenColorDialog", "CMFCColorMenuButton [MFC], SetColor", "CMFCColorMenuButton [MFC], SetColorByCmdID", "CMFCColorMenuButton [MFC], SetColorName", "CMFCColorMenuButton [MFC], SetColumnsNumber", "CMFCColorMenuButton [MFC], CopyFrom", "CMFCColorMenuButton [MFC], CreatePopupMenu", "CMFCColorMenuButton [MFC], IsEmptyMenuAllowed", "CMFCColorMenuButton [MFC], OnDraw", "CMFCColorMenuButton [MFC], OnDrawOnCustomizeList"] -ms.assetid: 42685704-e994-4f7b-9553-62283c27b754 --- # CMFCColorMenuButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCColorMenuButton` class supports a menu command or a toolbar button that starts a color picker dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfccolorpickerctrl-class.md b/docs/mfc/reference/cmfccolorpickerctrl-class.md index a00150e5a1d..4ccef18c4df 100644 --- a/docs/mfc/reference/cmfccolorpickerctrl-class.md +++ b/docs/mfc/reference/cmfccolorpickerctrl-class.md @@ -4,15 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCColorPickerCtrl` class provides functionality for a control that is used to select colors. ## Syntax -``` +```cpp class CMFCColorPickerCtrl : public CButton ``` @@ -22,43 +24,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 +70,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 +94,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 +106,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 +130,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 +143,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 +168,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 +182,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 +196,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 +213,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 +238,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 +248,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 +267,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 +291,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 +306,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 +321,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 +338,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 +355,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 +372,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 +387,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 +398,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/cmfccolorpopupmenu-class.md b/docs/mfc/reference/cmfccolorpopupmenu-class.md index e67a537f494..0b6d3554b4c 100644 --- a/docs/mfc/reference/cmfccolorpopupmenu-class.md +++ b/docs/mfc/reference/cmfccolorpopupmenu-class.md @@ -4,10 +4,12 @@ title: "CMFCColorPopupMenu Class" ms.date: "11/04/2016" f1_keywords: ["CMFCColorPopupMenu", "AFXCOLORPOPUPMENU/CMFCColorPopupMenu", "AFXCOLORPOPUPMENU/CMFCColorPopupMenu::CMFCColorPopupMenu", "AFXCOLORPOPUPMENU/CMFCColorPopupMenu::CreateTearOffBar", "AFXCOLORPOPUPMENU/CMFCColorPopupMenu::GetMenuBar", "AFXCOLORPOPUPMENU/CMFCColorPopupMenu::SetPropList"] helpviewer_keywords: ["CMFCColorPopupMenu [MFC], CMFCColorPopupMenu", "CMFCColorPopupMenu [MFC], CreateTearOffBar", "CMFCColorPopupMenu [MFC], GetMenuBar", "CMFCColorPopupMenu [MFC], SetPropList"] -ms.assetid: 0bf9efe8-aed5-4ab7-b23b-eb284b4668be --- # CMFCColorPopupMenu Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a pop-up menu that users use to select colors in a document or application. ## Syntax diff --git a/docs/mfc/reference/cmfccustomcolorspropertypage-class.md b/docs/mfc/reference/cmfccustomcolorspropertypage-class.md index 215b8deb8d2..1c1005ea7a5 100644 --- a/docs/mfc/reference/cmfccustomcolorspropertypage-class.md +++ b/docs/mfc/reference/cmfccustomcolorspropertypage-class.md @@ -4,10 +4,12 @@ title: "CMFCCustomColorsPropertyPage Class" ms.date: "11/04/2016" f1_keywords: ["CMFCCustomColorsPropertyPage", "AFXCUSTOMCOLORSPROPERTYPAGE/CMFCCustomColorsPropertyPage", "AFXCUSTOMCOLORSPROPERTYPAGE/CMFCCustomColorsPropertyPage::Setup"] helpviewer_keywords: ["CMFCCustomColorsPropertyPage [MFC], Setup"] -ms.assetid: 46a45ba2-1fda-440d-8018-d4dcd44f5816 --- # CMFCCustomColorsPropertyPage Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a property page that can select custom colors in a color dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcdesktopalertdialog-class.md b/docs/mfc/reference/cmfcdesktopalertdialog-class.md index 8807b8902f3..0e7912e917e 100644 --- a/docs/mfc/reference/cmfcdesktopalertdialog-class.md +++ b/docs/mfc/reference/cmfcdesktopalertdialog-class.md @@ -4,10 +4,12 @@ title: "CMFCDesktopAlertDialog Class" ms.date: "10/18/2018" f1_keywords: ["CMFCDesktopAlertDialog", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertDialog", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertDialog::CreateFromParams", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertDialog::GetDlgSize", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertDialog::HasFocus", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertDialog::PreTranslateMessage"] helpviewer_keywords: ["CMFCDesktopAlertDialog [MFC], CreateFromParams", "CMFCDesktopAlertDialog [MFC], GetDlgSize", "CMFCDesktopAlertDialog [MFC], HasFocus", "CMFCDesktopAlertDialog [MFC], PreTranslateMessage"] -ms.assetid: a53c60aa-9607-485b-b826-ec64962075f6 --- # CMFCDesktopAlertDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCDesktopAlertDialog` class is used together with the [CMFCDesktopAlertWnd Class](../../mfc/reference/cmfcdesktopalertwnd-class.md) to display a custom dialog in a popup window. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcdesktopalertwnd-class.md b/docs/mfc/reference/cmfcdesktopalertwnd-class.md index d473b05c588..5179e51c5f5 100644 --- a/docs/mfc/reference/cmfcdesktopalertwnd-class.md +++ b/docs/mfc/reference/cmfcdesktopalertwnd-class.md @@ -4,10 +4,12 @@ title: "CMFCDesktopAlertWnd Class" ms.date: "10/18/2018" f1_keywords: ["CMFCDesktopAlertWnd", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::Create", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::GetAnimationSpeed", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::GetAnimationType", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::GetAutoCloseTime", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::GetCaptionHeight", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::GetDialogSize", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::GetLastPos", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::GetTransparency", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::HasSmallCaption", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::OnBeforeShow", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::OnClickLinkButton", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::OnCommand", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::OnDraw", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::ProcessCommand", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::SetAnimationSpeed", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::SetAnimationType", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::SetAutoCloseTime", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::SetSmallCaption", "AFXDESKTOPALERTWND/CMFCDesktopAlertWnd::SetTransparency"] helpviewer_keywords: ["CMFCDesktopAlertWnd [MFC], Create", "CMFCDesktopAlertWnd [MFC], GetAnimationSpeed", "CMFCDesktopAlertWnd [MFC], GetAnimationType", "CMFCDesktopAlertWnd [MFC], GetAutoCloseTime", "CMFCDesktopAlertWnd [MFC], GetCaptionHeight", "CMFCDesktopAlertWnd [MFC], GetDialogSize", "CMFCDesktopAlertWnd [MFC], GetLastPos", "CMFCDesktopAlertWnd [MFC], GetTransparency", "CMFCDesktopAlertWnd [MFC], HasSmallCaption", "CMFCDesktopAlertWnd [MFC], OnBeforeShow", "CMFCDesktopAlertWnd [MFC], OnClickLinkButton", "CMFCDesktopAlertWnd [MFC], OnCommand", "CMFCDesktopAlertWnd [MFC], OnDraw", "CMFCDesktopAlertWnd [MFC], ProcessCommand", "CMFCDesktopAlertWnd [MFC], SetAnimationSpeed", "CMFCDesktopAlertWnd [MFC], SetAnimationType", "CMFCDesktopAlertWnd [MFC], SetAutoCloseTime", "CMFCDesktopAlertWnd [MFC], SetSmallCaption", "CMFCDesktopAlertWnd [MFC], SetTransparency"] -ms.assetid: 73a2dd7b-ea84-4ae2-9830-7cf6e8dd2425 --- # CMFCDesktopAlertWnd Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCDesktopAlertWnd` class implements the functionality of a modeless dialog box which appears on the screen to inform the user about an event. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcdesktopalertwndbutton-class.md b/docs/mfc/reference/cmfcdesktopalertwndbutton-class.md index 65e46a6c1ec..f216316ca09 100644 --- a/docs/mfc/reference/cmfcdesktopalertwndbutton-class.md +++ b/docs/mfc/reference/cmfcdesktopalertwndbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCDesktopAlertWndButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCDesktopAlertWndButton", "AFXDESKTOPALERTWND/CMFCDesktopAlertWndButton", "AFXDESKTOPALERTWND/CMFCDesktopAlertWndButton::IsCaptionButton", "AFXDESKTOPALERTWND/CMFCDesktopAlertWndButton::IsCloseButton"] helpviewer_keywords: ["CMFCDesktopAlertWndButton [MFC], IsCaptionButton", "CMFCDesktopAlertWndButton [MFC], IsCloseButton"] -ms.assetid: df39a0c8-0c39-4ab0-8c64-78c5b2c4ecaf --- # CMFCDesktopAlertWndButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows buttons to be added to a desktop alert dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcdesktopalertwndinfo-class.md b/docs/mfc/reference/cmfcdesktopalertwndinfo-class.md index fcf410dddb8..1591b9e0164 100644 --- a/docs/mfc/reference/cmfcdesktopalertwndinfo-class.md +++ b/docs/mfc/reference/cmfcdesktopalertwndinfo-class.md @@ -4,10 +4,12 @@ title: "CMFCDesktopAlertWndInfo Class" ms.date: "10/18/2018" f1_keywords: ["CMFCDesktopAlertWndInfo", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertWndInfo", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertWndInfo::m_hIcon", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertWndInfo::m_nURLCmdID", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertWndInfo::m_strText", "AFXDESKTOPALERTDIALOG/CMFCDesktopAlertWndInfo::m_strURL"] helpviewer_keywords: ["CMFCDesktopAlertWndInfo [MFC], m_hIcon", "CMFCDesktopAlertWndInfo [MFC], m_nURLCmdID", "CMFCDesktopAlertWndInfo [MFC], m_strText", "CMFCDesktopAlertWndInfo [MFC], m_strURL"] -ms.assetid: 5c9bb84e-6c96-4748-8e74-6951b6ae8e84 --- # CMFCDesktopAlertWndInfo Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCDesktopAlertWndInfo` class is used with the [CMFCDesktopAlertWnd Class](../../mfc/reference/cmfcdesktopalertwnd-class.md). It specifies the controls that are displayed if the desktop alert window pops up. ## Syntax diff --git a/docs/mfc/reference/cmfcdisablemenuanimation-class.md b/docs/mfc/reference/cmfcdisablemenuanimation-class.md index 5dc689897be..e4bd79b0ee9 100644 --- a/docs/mfc/reference/cmfcdisablemenuanimation-class.md +++ b/docs/mfc/reference/cmfcdisablemenuanimation-class.md @@ -4,10 +4,12 @@ title: "CMFCDisableMenuAnimation Class" ms.date: "11/04/2016" f1_keywords: ["CMFCDisableMenuAnimation", "AFXPOPUPMENU/CMFCDisableMenuAnimation", "AFXPOPUPMENU/CMFCDisableMenuAnimation::Restore"] helpviewer_keywords: ["CMFCDisableMenuAnimation [MFC], Restore"] -ms.assetid: c6eb07da-c382-43d6-8028-007f2320e50e --- # CMFCDisableMenuAnimation Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Disables pop-up menu animation. ## Syntax diff --git a/docs/mfc/reference/cmfcdragframeimpl-class.md b/docs/mfc/reference/cmfcdragframeimpl-class.md index 0305fe19091..6f1eca2b4cd 100644 --- a/docs/mfc/reference/cmfcdragframeimpl-class.md +++ b/docs/mfc/reference/cmfcdragframeimpl-class.md @@ -4,10 +4,12 @@ title: "CMFCDragFrameImpl Class" ms.date: "10/18/2018" f1_keywords: ["CMFCDragFrameImpl"] helpviewer_keywords: ["CMFCDragFrameImpl class [MFC]"] -ms.assetid: 500cd824-8188-43c2-8754-b7bb46b5648a --- # CMFCDragFrameImpl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCDragFrameImpl` class draws the drag rectangle that appears when the user drags a pane in the standard dock mode. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcdropdownframe-class.md b/docs/mfc/reference/cmfcdropdownframe-class.md index dc2193522d5..d82e9660902 100644 --- a/docs/mfc/reference/cmfcdropdownframe-class.md +++ b/docs/mfc/reference/cmfcdropdownframe-class.md @@ -4,10 +4,12 @@ title: "CMFCDropDownFrame Class" ms.date: "11/04/2016" f1_keywords: ["CMFCDropDownFrame", "AFXDROPDOWNTOOLBAR/CMFCDropDownFrame", "AFXDROPDOWNTOOLBAR/CMFCDropDownFrame::Create", "AFXDROPDOWNTOOLBAR/CMFCDropDownFrame::GetParentMenuBar", "AFXDROPDOWNTOOLBAR/CMFCDropDownFrame::GetParentPopupMenu", "AFXDROPDOWNTOOLBAR/CMFCDropDownFrame::RecalcLayout", "AFXDROPDOWNTOOLBAR/CMFCDropDownFrame::SetAutoDestroy"] helpviewer_keywords: ["CMFCDropDownFrame [MFC], Create", "CMFCDropDownFrame [MFC], GetParentMenuBar", "CMFCDropDownFrame [MFC], GetParentPopupMenu", "CMFCDropDownFrame [MFC], RecalcLayout", "CMFCDropDownFrame [MFC], SetAutoDestroy"] -ms.assetid: 09ff81a9-de00-43ec-9df9-b626f7728c4b --- # CMFCDropDownFrame Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides drop-down frame window functionality to drop-down toolbars and drop-down toolbar buttons. ## Syntax diff --git a/docs/mfc/reference/cmfcdropdowntoolbar-class.md b/docs/mfc/reference/cmfcdropdowntoolbar-class.md index 9fbdc25a7b8..ef021c74955 100644 --- a/docs/mfc/reference/cmfcdropdowntoolbar-class.md +++ b/docs/mfc/reference/cmfcdropdowntoolbar-class.md @@ -4,10 +4,12 @@ title: "CMFCDropDownToolBar Class" ms.date: "11/19/2018" f1_keywords: ["CMFCDropDownToolBar", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar::AllowShowOnPaneMenu", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar::LoadBitmap", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar::LoadToolBar", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar::OnLButtonUp", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar::OnMouseMove", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar::OnSendCommand", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolBar::OnUpdateCmdUI"] helpviewer_keywords: ["CMFCDropDownToolBar [MFC], AllowShowOnPaneMenu", "CMFCDropDownToolBar [MFC], LoadBitmap", "CMFCDropDownToolBar [MFC], LoadToolBar", "CMFCDropDownToolBar [MFC], OnLButtonUp", "CMFCDropDownToolBar [MFC], OnMouseMove", "CMFCDropDownToolBar [MFC], OnSendCommand", "CMFCDropDownToolBar [MFC], OnUpdateCmdUI"] -ms.assetid: 78818ec5-83ce-42fa-a0d4-2d9d5ecc8770 --- # CMFCDropDownToolBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar that appears when the user presses and holds a top-level toolbar button. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcdropdowntoolbarbutton-class.md b/docs/mfc/reference/cmfcdropdowntoolbarbutton-class.md index dd68698320f..4b264833d8e 100644 --- a/docs/mfc/reference/cmfcdropdowntoolbarbutton-class.md +++ b/docs/mfc/reference/cmfcdropdowntoolbarbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCDropDownToolbarButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCDropDownToolbarButton", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::CMFCDropDownToolbarButton", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::CopyFrom", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::DropDownToolbar", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::ExportToMenuButton", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::GetDropDownToolBar", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::IsDropDown", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::IsExtraSize", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnCalculateSize", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnChangeParentWnd", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnClick", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnClickUp", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnContextHelp", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnCustomizeMenu", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnDraw", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::OnDrawOnCustomizeList", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::Serialize", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::SetDefaultCommand", "AFXDROPDOWNTOOLBAR/CMFCDropDownToolbarButton::m_uiShowBarDelay"] helpviewer_keywords: ["CMFCDropDownToolbarButton [MFC], CMFCDropDownToolbarButton", "CMFCDropDownToolbarButton [MFC], CopyFrom", "CMFCDropDownToolbarButton [MFC], DropDownToolbar", "CMFCDropDownToolbarButton [MFC], ExportToMenuButton", "CMFCDropDownToolbarButton [MFC], GetDropDownToolBar", "CMFCDropDownToolbarButton [MFC], IsDropDown", "CMFCDropDownToolbarButton [MFC], IsExtraSize", "CMFCDropDownToolbarButton [MFC], OnCalculateSize", "CMFCDropDownToolbarButton [MFC], OnChangeParentWnd", "CMFCDropDownToolbarButton [MFC], OnClick", "CMFCDropDownToolbarButton [MFC], OnClickUp", "CMFCDropDownToolbarButton [MFC], OnContextHelp", "CMFCDropDownToolbarButton [MFC], OnCustomizeMenu", "CMFCDropDownToolbarButton [MFC], OnDraw", "CMFCDropDownToolbarButton [MFC], OnDrawOnCustomizeList", "CMFCDropDownToolbarButton [MFC], Serialize", "CMFCDropDownToolbarButton [MFC], SetDefaultCommand", "CMFCDropDownToolbarButton [MFC], m_uiShowBarDelay"] -ms.assetid: bc9d69e6-bd3e-4c15-9368-e80a504a0ba7 --- # CMFCDropDownToolbarButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax diff --git a/docs/mfc/reference/cmfcdynamiclayout-class.md b/docs/mfc/reference/cmfcdynamiclayout-class.md index 0c8f47f3f09..09cb98df6b4 100644 --- a/docs/mfc/reference/cmfcdynamiclayout-class.md +++ b/docs/mfc/reference/cmfcdynamiclayout-class.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Specifies how controls in a window are moved and resized as the user resizes the window. ## Syntax @@ -170,7 +172,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 +505,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 4026be004c5..331e901377c 100644 --- a/docs/mfc/reference/cmfceditbrowsectrl-class.md +++ b/docs/mfc/reference/cmfceditbrowsectrl-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCEditBrowseCtrl` class 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. ## Syntax @@ -69,7 +71,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 +308,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/cmfcfilterchunkvalueimpl-class.md b/docs/mfc/reference/cmfcfilterchunkvalueimpl-class.md index 7bd629455bd..8b8400cd514 100644 --- a/docs/mfc/reference/cmfcfilterchunkvalueimpl-class.md +++ b/docs/mfc/reference/cmfcfilterchunkvalueimpl-class.md @@ -4,10 +4,12 @@ title: "CMFCFilterChunkValueImpl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCFilterChunkValueImpl", "AFXWIN/CMFCFilterChunkValueImpl", "AFXWIN/CMFCFilterChunkValueImpl::CMFCFilterChunkValueImpl", "AFXWIN/CMFCFilterChunkValueImpl::Clear", "AFXWIN/CMFCFilterChunkValueImpl::CopyChunk", "AFXWIN/CMFCFilterChunkValueImpl::CopyFrom", "AFXWIN/CMFCFilterChunkValueImpl::GetChunkGUID", "AFXWIN/CMFCFilterChunkValueImpl::GetChunkPID", "AFXWIN/CMFCFilterChunkValueImpl::GetChunkType", "AFXWIN/CMFCFilterChunkValueImpl::GetString", "AFXWIN/CMFCFilterChunkValueImpl::GetValue", "AFXWIN/CMFCFilterChunkValueImpl::GetValueNoAlloc", "AFXWIN/CMFCFilterChunkValueImpl::IsValid", "AFXWIN/CMFCFilterChunkValueImpl::SetBoolValue", "AFXWIN/CMFCFilterChunkValueImpl::SetDwordValue", "AFXWIN/CMFCFilterChunkValueImpl::SetFileTimeValue", "AFXWIN/CMFCFilterChunkValueImpl::SetInt64Value", "AFXWIN/CMFCFilterChunkValueImpl::SetIntValue", "AFXWIN/CMFCFilterChunkValueImpl::SetLongValue", "AFXWIN/CMFCFilterChunkValueImpl::SetSystemTimeValue", "AFXWIN/CMFCFilterChunkValueImpl::SetTextValue", "AFXWIN/CMFCFilterChunkValueImpl::SetChunk"] helpviewer_keywords: ["CMFCFilterChunkValueImpl [MFC], CMFCFilterChunkValueImpl", "CMFCFilterChunkValueImpl [MFC], Clear", "CMFCFilterChunkValueImpl [MFC], CopyChunk", "CMFCFilterChunkValueImpl [MFC], CopyFrom", "CMFCFilterChunkValueImpl [MFC], GetChunkGUID", "CMFCFilterChunkValueImpl [MFC], GetChunkPID", "CMFCFilterChunkValueImpl [MFC], GetChunkType", "CMFCFilterChunkValueImpl [MFC], GetString", "CMFCFilterChunkValueImpl [MFC], GetValue", "CMFCFilterChunkValueImpl [MFC], GetValueNoAlloc", "CMFCFilterChunkValueImpl [MFC], IsValid", "CMFCFilterChunkValueImpl [MFC], SetBoolValue", "CMFCFilterChunkValueImpl [MFC], SetDwordValue", "CMFCFilterChunkValueImpl [MFC], SetFileTimeValue", "CMFCFilterChunkValueImpl [MFC], SetInt64Value", "CMFCFilterChunkValueImpl [MFC], SetIntValue", "CMFCFilterChunkValueImpl [MFC], SetLongValue", "CMFCFilterChunkValueImpl [MFC], SetSystemTimeValue", "CMFCFilterChunkValueImpl [MFC], SetTextValue", "CMFCFilterChunkValueImpl [MFC], SetChunk"] -ms.assetid: 3c833f23-5b88-4d08-9e09-ca6a8aec88bf --- # CMFCFilterChunkValueImpl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This is a class which simplifies both chunk and property value pair logic. ## Syntax diff --git a/docs/mfc/reference/cmfcfontcombobox-class.md b/docs/mfc/reference/cmfcfontcombobox-class.md index 23d4f981449..bebc44a37c0 100644 --- a/docs/mfc/reference/cmfcfontcombobox-class.md +++ b/docs/mfc/reference/cmfcfontcombobox-class.md @@ -4,10 +4,12 @@ title: "CMFCFontComboBox Class" ms.date: "11/04/2016" f1_keywords: ["CMFCFontComboBox", "AFXFONTCOMBOBOX/CMFCFontComboBox", "AFXFONTCOMBOBOX/CMFCFontComboBox::CMFCFontComboBox", "AFXFONTCOMBOBOX/CMFCFontComboBox::GetSelFont", "AFXFONTCOMBOBOX/CMFCFontComboBox::SelectFont", "AFXFONTCOMBOBOX/CMFCFontComboBox::Setup", "AFXFONTCOMBOBOX/CMFCFontComboBox::m_bDrawUsingFont"] helpviewer_keywords: ["CMFCFontComboBox [MFC], CMFCFontComboBox", "CMFCFontComboBox [MFC], GetSelFont", "CMFCFontComboBox [MFC], SelectFont", "CMFCFontComboBox [MFC], Setup", "CMFCFontComboBox [MFC], m_bDrawUsingFont"] -ms.assetid: 9a53fb0c-7b45-486d-8187-2a4c723d9fbb --- # CMFCFontComboBox Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCFontComboBox` class creates a combo box control that contains a list of fonts. ## Syntax diff --git a/docs/mfc/reference/cmfcfontinfo-class.md b/docs/mfc/reference/cmfcfontinfo-class.md index f44dd4e20b1..cf82482be39 100644 --- a/docs/mfc/reference/cmfcfontinfo-class.md +++ b/docs/mfc/reference/cmfcfontinfo-class.md @@ -4,10 +4,12 @@ title: "CMFCFontInfo Class" ms.date: "11/04/2016" f1_keywords: ["CMFCFontInfo", "AFXTOOLBARFONTCOMBOBOX/CMFCFontInfo", "AFXTOOLBARFONTCOMBOBOX/CMFCFontInfo::GetFullName", "AFXTOOLBARFONTCOMBOBOX/CMFCFontInfo::m_nCharSet", "AFXTOOLBARFONTCOMBOBOX/CMFCFontInfo::m_nPitchAndFamily", "AFXTOOLBARFONTCOMBOBOX/CMFCFontInfo::m_nType", "AFXTOOLBARFONTCOMBOBOX/CMFCFontInfo::m_strName", "AFXTOOLBARFONTCOMBOBOX/CMFCFontInfo::m_strScript"] helpviewer_keywords: ["CMFCFontInfo [MFC], GetFullName", "CMFCFontInfo [MFC], m_nCharSet", "CMFCFontInfo [MFC], m_nPitchAndFamily", "CMFCFontInfo [MFC], m_nType", "CMFCFontInfo [MFC], m_strName", "CMFCFontInfo [MFC], m_strScript"] -ms.assetid: f88329b2-d74e-4921-9441-a3bb6536a049 --- # CMFCFontInfo Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCFontInfo` class describes the name and other attributes of a font. ## Syntax diff --git a/docs/mfc/reference/cmfcheaderctrl-class.md b/docs/mfc/reference/cmfcheaderctrl-class.md index c736bcd0e22..fb24bc1b33b 100644 --- a/docs/mfc/reference/cmfcheaderctrl-class.md +++ b/docs/mfc/reference/cmfcheaderctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCHeaderCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCHeaderCtrl", "AFXHEADERCTRL/CMFCHeaderCtrl", "AFXHEADERCTRL/CMFCHeaderCtrl::CMFCHeaderCtrl", "AFXHEADERCTRL/CMFCHeaderCtrl::EnableMultipleSort", "AFXHEADERCTRL/CMFCHeaderCtrl::GetColumnState", "AFXHEADERCTRL/CMFCHeaderCtrl::GetSortColumn", "AFXHEADERCTRL/CMFCHeaderCtrl::IsAscending", "AFXHEADERCTRL/CMFCHeaderCtrl::IsDialogControl", "AFXHEADERCTRL/CMFCHeaderCtrl::IsMultipleSort", "AFXHEADERCTRL/CMFCHeaderCtrl::RemoveSortColumn", "AFXHEADERCTRL/CMFCHeaderCtrl::SetSortColumn", "AFXHEADERCTRL/CMFCHeaderCtrl::OnDrawItem", "AFXHEADERCTRL/CMFCHeaderCtrl::OnDrawSortArrow", "AFXHEADERCTRL/CMFCHeaderCtrl::OnFillBackground"] helpviewer_keywords: ["CMFCHeaderCtrl [MFC], CMFCHeaderCtrl", "CMFCHeaderCtrl [MFC], EnableMultipleSort", "CMFCHeaderCtrl [MFC], GetColumnState", "CMFCHeaderCtrl [MFC], GetSortColumn", "CMFCHeaderCtrl [MFC], IsAscending", "CMFCHeaderCtrl [MFC], IsDialogControl", "CMFCHeaderCtrl [MFC], IsMultipleSort", "CMFCHeaderCtrl [MFC], RemoveSortColumn", "CMFCHeaderCtrl [MFC], SetSortColumn", "CMFCHeaderCtrl [MFC], OnDrawItem", "CMFCHeaderCtrl [MFC], OnDrawSortArrow", "CMFCHeaderCtrl [MFC], OnFillBackground"] -ms.assetid: 2f5fbf7b-5c75-42db-9216-640b1628f777 --- # CMFCHeaderCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCHeaderCtrl` class supports sorting multiple columns in a header control. ## Syntax diff --git a/docs/mfc/reference/cmfcimageeditordialog-class.md b/docs/mfc/reference/cmfcimageeditordialog-class.md index fb12f266bfe..46b2338e662 100644 --- a/docs/mfc/reference/cmfcimageeditordialog-class.md +++ b/docs/mfc/reference/cmfcimageeditordialog-class.md @@ -4,10 +4,12 @@ title: "CMFCImageEditorDialog Class" ms.date: "11/19/2018" f1_keywords: ["CMFCImageEditorDialog", "AFXIMAGEEDITORDIALOG/CMFCImageEditorDialog", "AFXIMAGEEDITORDIALOG/CMFCImageEditorDialog::CMFCImageEditorDialog"] helpviewer_keywords: ["CMFCImageEditorDialog [MFC], CMFCImageEditorDialog"] -ms.assetid: 6a7d08f3-1ec2-4062-9b79-a0c2776b58d1 --- # CMFCImageEditorDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCImageEditorDialog` class supports an image editor dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcimageeditorpalettebar-class.md b/docs/mfc/reference/cmfcimageeditorpalettebar-class.md index 3e967fd6efe..28e32d6f7e3 100644 --- a/docs/mfc/reference/cmfcimageeditorpalettebar-class.md +++ b/docs/mfc/reference/cmfcimageeditorpalettebar-class.md @@ -4,10 +4,12 @@ title: "CMFCImageEditorPaletteBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCImageEditorPaletteBar", "AFXIMAGEEDITORDIALOG/CMFCImageEditorPaletteBar", "AFXIMAGEEDITORDIALOG/CMFCImageEditorPaletteBar::GetRowHeight", "AFXIMAGEEDITORDIALOG/CMFCImageEditorPaletteBar::IsButtonExtraSizeAvailable"] helpviewer_keywords: ["CMFCImageEditorPaletteBar [MFC], GetRowHeight", "CMFCImageEditorPaletteBar [MFC], IsButtonExtraSizeAvailable"] -ms.assetid: 3fb7ba8e-f254-4d56-b913-9941b4ed8138 --- # CMFCImageEditorPaletteBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides palette bar functionality to an image editor dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcimagepaintarea-class.md b/docs/mfc/reference/cmfcimagepaintarea-class.md index b9b12f31673..2c8bd7c1b13 100644 --- a/docs/mfc/reference/cmfcimagepaintarea-class.md +++ b/docs/mfc/reference/cmfcimagepaintarea-class.md @@ -4,10 +4,12 @@ title: "CMFCImagePaintArea Class" ms.date: "11/04/2016" f1_keywords: ["CMFCImagePaintArea", "AFXIMAGEPAINTAREA/CMFCImagePaintArea", "AFXIMAGEPAINTAREA/CMFCImagePaintArea::CMFCImagePaintArea", "AFXIMAGEPAINTAREA/CMFCImagePaintArea::GetMode", "AFXIMAGEPAINTAREA/CMFCImagePaintArea::SetBitmap", "AFXIMAGEPAINTAREA/CMFCImagePaintArea::SetColor", "AFXIMAGEPAINTAREA/CMFCImagePaintArea::SetMode"] helpviewer_keywords: ["CMFCImagePaintArea [MFC], CMFCImagePaintArea", "CMFCImagePaintArea [MFC], GetMode", "CMFCImagePaintArea [MFC], SetBitmap", "CMFCImagePaintArea [MFC], SetColor", "CMFCImagePaintArea [MFC], SetMode"] -ms.assetid: c59eec22-f15a-4e58-8c4d-4a18a41f4452 --- # CMFCImagePaintArea Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the picture area that you use to modify an image in an image editor dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcimagepaintarea-image-edit-mode-enumeration.md b/docs/mfc/reference/cmfcimagepaintarea-image-edit-mode-enumeration.md index ea4942119f2..3ca70390145 100644 --- a/docs/mfc/reference/cmfcimagepaintarea-image-edit-mode-enumeration.md +++ b/docs/mfc/reference/cmfcimagepaintarea-image-edit-mode-enumeration.md @@ -4,10 +4,12 @@ title: "CMFCImagePaintArea::IMAGE_EDIT_MODE Enumeration" ms.date: "11/04/2016" f1_keywords: ["IMAGE_EDIT_MODE Enumeration"] helpviewer_keywords: ["IMAGE_EDIT_MODE Enumeration method [MFC]"] -ms.assetid: e51db66a-fa1c-4766-9dac-a25b595f871a --- # CMFCImagePaintArea::IMAGE_EDIT_MODE Enumeration +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Specifies a drawing mode that you use to modify an image in an image editor dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfckeymapdialog-class.md b/docs/mfc/reference/cmfckeymapdialog-class.md index 43c94443db1..80c2426815c 100644 --- a/docs/mfc/reference/cmfckeymapdialog-class.md +++ b/docs/mfc/reference/cmfckeymapdialog-class.md @@ -4,10 +4,12 @@ title: "CMFCKeyMapDialog Class" ms.date: "11/04/2016" f1_keywords: ["CMFCKeyMapDialog", "AFXKEYMAPDIALOG/CMFCKeyMapDialog", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::CMFCKeyMapDialog", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::DoModal", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::FormatItem", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::GetCommandKeys", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::OnInsertItem", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::OnPrintHeader", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::OnPrintItem", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::OnSetColumns", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::PrintKeyMap", "AFXKEYMAPDIALOG/CMFCKeyMapDialog::SetColumnsWidth"] helpviewer_keywords: ["CMFCKeyMapDialog [MFC], CMFCKeyMapDialog", "CMFCKeyMapDialog [MFC], DoModal", "CMFCKeyMapDialog [MFC], FormatItem", "CMFCKeyMapDialog [MFC], GetCommandKeys", "CMFCKeyMapDialog [MFC], OnInsertItem", "CMFCKeyMapDialog [MFC], OnPrintHeader", "CMFCKeyMapDialog [MFC], OnPrintItem", "CMFCKeyMapDialog [MFC], OnSetColumns", "CMFCKeyMapDialog [MFC], PrintKeyMap", "CMFCKeyMapDialog [MFC], SetColumnsWidth"] -ms.assetid: 5feb4942-d636-462d-a162-0104dd320f4e --- # CMFCKeyMapDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCKeyMapDialog` class supports a control that maps commands to keys on the keyboard. ## Syntax diff --git a/docs/mfc/reference/cmfclinkctrl-class.md b/docs/mfc/reference/cmfclinkctrl-class.md index 9fee3460bae..0e008d64bfd 100644 --- a/docs/mfc/reference/cmfclinkctrl-class.md +++ b/docs/mfc/reference/cmfclinkctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCLinkCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCLinkCtrl", "AFXLINKCTRL/CMFCLinkCtrl", "AFXLINKCTRL/CMFCLinkCtrl::SetURL", "AFXLINKCTRL/CMFCLinkCtrl::SetURLPrefix", "AFXLINKCTRL/CMFCLinkCtrl::SizeToContent", "AFXLINKCTRL/CMFCLinkCtrl::OnDrawFocusRect"] helpviewer_keywords: ["CMFCLinkCtrl [MFC], SetURL", "CMFCLinkCtrl [MFC], SetURLPrefix", "CMFCLinkCtrl [MFC], SizeToContent", "CMFCLinkCtrl [MFC], OnDrawFocusRect"] -ms.assetid: 80f3874d-7cc8-410e-9ff1-62a225f5034b --- # CMFCLinkCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCLinkCtrl` class displays a button as a hyperlink and invokes the link's target when the button is clicked. ## Syntax diff --git a/docs/mfc/reference/cmfclistctrl-class.md b/docs/mfc/reference/cmfclistctrl-class.md index 2ac870b8469..9f7534a3fdf 100644 --- a/docs/mfc/reference/cmfclistctrl-class.md +++ b/docs/mfc/reference/cmfclistctrl-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CMFCListCtrl [MFC], EnableMarkSortedColumn", "CMFCListCtr --- # `CMFCListCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCListCtrl` class extends the functionality of [`CListCtrl` Class](../../mfc/reference/clistctrl-class.md) class by supporting the advanced header control functionality of the [`CMFCHeaderCtrl` Class](../../mfc/reference/cmfcheaderctrl-class.md). ## Syntax diff --git a/docs/mfc/reference/cmfcmaskededit-class.md b/docs/mfc/reference/cmfcmaskededit-class.md index 7b846c8641d..71ee2f137b4 100644 --- a/docs/mfc/reference/cmfcmaskededit-class.md +++ b/docs/mfc/reference/cmfcmaskededit-class.md @@ -4,10 +4,12 @@ title: "CMFCMaskedEdit Class" ms.date: "11/04/2016" f1_keywords: ["CMFCMaskedEdit", "AFXMASKEDEDIT/CMFCMaskedEdit", "AFXMASKEDEDIT/CMFCMaskedEdit::DisableMask", "AFXMASKEDEDIT/CMFCMaskedEdit::EnableGetMaskedCharsOnly", "AFXMASKEDEDIT/CMFCMaskedEdit::EnableMask", "AFXMASKEDEDIT/CMFCMaskedEdit::EnableSelectByGroup", "AFXMASKEDEDIT/CMFCMaskedEdit::EnableSetMaskedCharsOnly", "AFXMASKEDEDIT/CMFCMaskedEdit::GetWindowText", "AFXMASKEDEDIT/CMFCMaskedEdit::SetValidChars", "AFXMASKEDEDIT/CMFCMaskedEdit::SetWindowText", "AFXMASKEDEDIT/CMFCMaskedEdit::IsMaskedChar"] helpviewer_keywords: ["CMFCMaskedEdit [MFC], DisableMask", "CMFCMaskedEdit [MFC], EnableGetMaskedCharsOnly", "CMFCMaskedEdit [MFC], EnableMask", "CMFCMaskedEdit [MFC], EnableSelectByGroup", "CMFCMaskedEdit [MFC], EnableSetMaskedCharsOnly", "CMFCMaskedEdit [MFC], GetWindowText", "CMFCMaskedEdit [MFC], SetValidChars", "CMFCMaskedEdit [MFC], SetWindowText", "CMFCMaskedEdit [MFC], IsMaskedChar"] -ms.assetid: 13b1a645-2d5d-4c37-8599-16d5003f23a5 --- # CMFCMaskedEdit Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCMaskedEdit` class supports a masked edit control, which validates user input against a mask and displays the validated results according to a template. ## Syntax diff --git a/docs/mfc/reference/cmfcmenubar-class.md b/docs/mfc/reference/cmfcmenubar-class.md index b541ec3c640..5dfec5efea7 100644 --- a/docs/mfc/reference/cmfcmenubar-class.md +++ b/docs/mfc/reference/cmfcmenubar-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A menu bar that implements docking. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -663,7 +665,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 +979,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/cmfcmenubutton-class.md b/docs/mfc/reference/cmfcmenubutton-class.md index 380fdad1eed..a7a14369f28 100644 --- a/docs/mfc/reference/cmfcmenubutton-class.md +++ b/docs/mfc/reference/cmfcmenubutton-class.md @@ -4,10 +4,12 @@ title: "CMFCMenuButton Class" ms.date: "07/15/2019" f1_keywords: ["CMFCMenuButton", "AFXMENUBUTTON/CMFCMenuButton", "AFXMENUBUTTON/CMFCMenuButton::CMFCMenuButton", "AFXMENUBUTTON/CMFCMenuButton::PreTranslateMessage", "AFXMENUBUTTON/CMFCMenuButton::SizeToContent", "AFXMENUBUTTON/CMFCMenuButton::m_bOSMenu", "AFXMENUBUTTON/CMFCMenuButton::m_bRightArrow", "AFXMENUBUTTON/CMFCMenuButton::m_bStayPressed", "AFXMENUBUTTON/CMFCMenuButton::m_hMenu", "AFXMENUBUTTON/CMFCMenuButton::m_nMenuResult", "AFXMENUBUTTON/CMFCMenuButton::m_bDefaultClick"] helpviewer_keywords: ["CMFCMenuButton [MFC], CMFCMenuButton", "CMFCMenuButton [MFC], PreTranslateMessage", "CMFCMenuButton [MFC], SizeToContent", "CMFCMenuButton [MFC], m_bOSMenu", "CMFCMenuButton [MFC], m_bRightArrow", "CMFCMenuButton [MFC], m_bStayPressed", "CMFCMenuButton [MFC], m_hMenu", "CMFCMenuButton [MFC], m_nMenuResult", "CMFCMenuButton [MFC], m_bDefaultClick"] -ms.assetid: 53d3d459-1e5a-47c5-8b7f-2e61f6af5187 --- # CMFCMenuButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A button that displays a pop-up menu and reports on the user's menu selections. ## Syntax diff --git a/docs/mfc/reference/cmfcoutlookbar-class.md b/docs/mfc/reference/cmfcoutlookbar-class.md index 86aa09e2f8d..e4b228d5fac 100644 --- a/docs/mfc/reference/cmfcoutlookbar-class.md +++ b/docs/mfc/reference/cmfcoutlookbar-class.md @@ -4,10 +4,12 @@ title: "CMFCOutlookBar Class" ms.date: "06/25/2018" f1_keywords: ["CMFCOutlookBar", "AFXOUTLOOKBAR/CMFCOutlookBar", "AFXOUTLOOKBAR/CMFCOutlookBar::AllowDestroyEmptyTabbedPane", "AFXOUTLOOKBAR/CMFCOutlookBar::CanAcceptPane", "AFXOUTLOOKBAR/CMFCOutlookBar::CanSetCaptionTextToTabName", "AFXOUTLOOKBAR/CMFCOutlookBar::Create", "AFXOUTLOOKBAR/CMFCOutlookBar::CreateCustomPage", "AFXOUTLOOKBAR/CMFCOutlookBar::DoesAllowDynInsertBefore", "AFXOUTLOOKBAR/CMFCOutlookBar::FloatTab", "AFXOUTLOOKBAR/CMFCOutlookBar::GetButtonsFont", "AFXOUTLOOKBAR/CMFCOutlookBar::GetTabArea", "AFXOUTLOOKBAR/CMFCOutlookBar::IsMode2003", "AFXOUTLOOKBAR/CMFCOutlookBar::OnAfterAnimation", "AFXOUTLOOKBAR/CMFCOutlookBar::OnBeforeAnimation", "AFXOUTLOOKBAR/CMFCOutlookBar::OnScroll", "AFXOUTLOOKBAR/CMFCOutlookBar::RemoveCustomPage", "AFXOUTLOOKBAR/CMFCOutlookBar::SetButtonsFont", "AFXOUTLOOKBAR/CMFCOutlookBar::SetMode2003"] helpviewer_keywords: ["CMFCOutlookBar [MFC], AllowDestroyEmptyTabbedPane", "CMFCOutlookBar [MFC], CanAcceptPane", "CMFCOutlookBar [MFC], CanSetCaptionTextToTabName", "CMFCOutlookBar [MFC], Create", "CMFCOutlookBar [MFC], CreateCustomPage", "CMFCOutlookBar [MFC], DoesAllowDynInsertBefore", "CMFCOutlookBar [MFC], FloatTab", "CMFCOutlookBar [MFC], GetButtonsFont", "CMFCOutlookBar [MFC], GetTabArea", "CMFCOutlookBar [MFC], IsMode2003", "CMFCOutlookBar [MFC], OnAfterAnimation", "CMFCOutlookBar [MFC], OnBeforeAnimation", "CMFCOutlookBar [MFC], OnScroll", "CMFCOutlookBar [MFC], RemoveCustomPage", "CMFCOutlookBar [MFC], SetButtonsFont", "CMFCOutlookBar [MFC], SetMode2003"] -ms.assetid: 2b335f71-ce99-4efd-b103-e65ba43ffc36 --- # CMFCOutlookBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax diff --git a/docs/mfc/reference/cmfcoutlookbarpane-class.md b/docs/mfc/reference/cmfcoutlookbarpane-class.md index 04527f6dd39..37a1f9e4ad7 100644 --- a/docs/mfc/reference/cmfcoutlookbarpane-class.md +++ b/docs/mfc/reference/cmfcoutlookbarpane-class.md @@ -4,10 +4,12 @@ title: "CMFCOutlookBarPane Class" ms.date: "11/04/2016" f1_keywords: ["CMFCOutlookBarPane", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::AddButton", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::CanBeAttached", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::ClearAll", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::Create", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::EnablePageScrollMode", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::GetRegularColor", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::IsBackgroundTexture", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::IsDrawShadedHighlight", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::RemoveButton", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::SetBackColor", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::SetBackImage", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::SetDefaultState", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::SetExtraSpace", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::SetTextColor", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::SetTransparentColor", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::EnableContextMenuItems", "AFXOUTLOOKBARPANE/CMFCOutlookBarPane::RemoveAllButtons"] helpviewer_keywords: ["CMFCOutlookBarPane [MFC], AddButton", "CMFCOutlookBarPane [MFC], CanBeAttached", "CMFCOutlookBarPane [MFC], ClearAll", "CMFCOutlookBarPane [MFC], Create", "CMFCOutlookBarPane [MFC], EnablePageScrollMode", "CMFCOutlookBarPane [MFC], GetRegularColor", "CMFCOutlookBarPane [MFC], IsBackgroundTexture", "CMFCOutlookBarPane [MFC], IsDrawShadedHighlight", "CMFCOutlookBarPane [MFC], RemoveButton", "CMFCOutlookBarPane [MFC], SetBackColor", "CMFCOutlookBarPane [MFC], SetBackImage", "CMFCOutlookBarPane [MFC], SetDefaultState", "CMFCOutlookBarPane [MFC], SetExtraSpace", "CMFCOutlookBarPane [MFC], SetTextColor", "CMFCOutlookBarPane [MFC], SetTransparentColor", "CMFCOutlookBarPane [MFC], EnableContextMenuItems", "CMFCOutlookBarPane [MFC], RemoveAllButtons"] -ms.assetid: 094e2ef3-a118-487e-a4cc-27626108fe08 --- # CMFCOutlookBarPane Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. 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. diff --git a/docs/mfc/reference/cmfcoutlookbartabctrl-class.md b/docs/mfc/reference/cmfcoutlookbartabctrl-class.md index 0ea3e6a49b0..7af29c03428 100644 --- a/docs/mfc/reference/cmfcoutlookbartabctrl-class.md +++ b/docs/mfc/reference/cmfcoutlookbartabctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCOutlookBarTabCtrl Class" ms.date: "10/18/2018" f1_keywords: ["CMFCOutlookBarTabCtrl", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::AddControl", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::CanShowFewerPageButtons", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::CanShowMorePageButtons", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::Create", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::EnableAnimation", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::EnableInPlaceEdit", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::EnableScrollButtons", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::GetBorderSize", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::GetVisiblePageButtons", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::IsAnimation", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::IsMode2003", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::OnShowFewerPageButtons", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::OnShowMorePageButtons", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::OnShowOptions", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::SetActiveTab", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::SetBorderSize", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::SetPageButtonTextAlign", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::SetToolbarImageList", "AFXOUTLOOKBARTABCTRL/CMFCOutlookBarTabCtrl::SetVisiblePageButtons"] helpviewer_keywords: ["CMFCOutlookBarTabCtrl [MFC], AddControl", "CMFCOutlookBarTabCtrl [MFC], CanShowFewerPageButtons", "CMFCOutlookBarTabCtrl [MFC], CanShowMorePageButtons", "CMFCOutlookBarTabCtrl [MFC], Create", "CMFCOutlookBarTabCtrl [MFC], EnableAnimation", "CMFCOutlookBarTabCtrl [MFC], EnableInPlaceEdit", "CMFCOutlookBarTabCtrl [MFC], EnableScrollButtons", "CMFCOutlookBarTabCtrl [MFC], GetBorderSize", "CMFCOutlookBarTabCtrl [MFC], GetVisiblePageButtons", "CMFCOutlookBarTabCtrl [MFC], IsAnimation", "CMFCOutlookBarTabCtrl [MFC], IsMode2003", "CMFCOutlookBarTabCtrl [MFC], OnShowFewerPageButtons", "CMFCOutlookBarTabCtrl [MFC], OnShowMorePageButtons", "CMFCOutlookBarTabCtrl [MFC], OnShowOptions", "CMFCOutlookBarTabCtrl [MFC], SetActiveTab", "CMFCOutlookBarTabCtrl [MFC], SetBorderSize", "CMFCOutlookBarTabCtrl [MFC], SetPageButtonTextAlign", "CMFCOutlookBarTabCtrl [MFC], SetToolbarImageList", "CMFCOutlookBarTabCtrl [MFC], SetVisiblePageButtons"] -ms.assetid: b1f2b3f7-cc59-49a3-99d8-7ff9b37c044b --- # CMFCOutlookBarTabCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A tab control that has the visual appearance of the **Navigation Pane** in Microsoft Outlook. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcpopupmenu-class.md b/docs/mfc/reference/cmfcpopupmenu-class.md index ab702034109..a56effeb9f5 100644 --- a/docs/mfc/reference/cmfcpopupmenu-class.md +++ b/docs/mfc/reference/cmfcpopupmenu-class.md @@ -4,10 +4,12 @@ title: "CMFCPopupMenu Class" ms.date: "10/18/2018" f1_keywords: ["CMFCPopupMenu", "AFXPOPUPMENU/CMFCPopupMenu", "AFXPOPUPMENU/CMFCPopupMenu::CMFCPopupMenu", "AFXPOPUPMENU/CMFCPopupMenu::ActivatePopupMenu", "AFXPOPUPMENU/CMFCPopupMenu::AlwaysShowEmptyToolsEntry", "AFXPOPUPMENU/CMFCPopupMenu::AreAllCommandsShown", "AFXPOPUPMENU/CMFCPopupMenu::CheckArea", "AFXPOPUPMENU/CMFCPopupMenu::CloseMenu", "AFXPOPUPMENU/CMFCPopupMenu::Create", "AFXPOPUPMENU/CMFCPopupMenu::DefaultMouseClickOnClose", "AFXPOPUPMENU/CMFCPopupMenu::EnableMenuLogo", "AFXPOPUPMENU/CMFCPopupMenu::EnableMenuSound", "AFXPOPUPMENU/CMFCPopupMenu::EnableResize", "AFXPOPUPMENU/CMFCPopupMenu::EnableScrolling", "AFXPOPUPMENU/CMFCPopupMenu::EnableVertResize", "AFXPOPUPMENU/CMFCPopupMenu::FindSubItemByCommand", "AFXPOPUPMENU/CMFCPopupMenu::GetActiveMenu", "AFXPOPUPMENU/CMFCPopupMenu::GetAnimationSpeed", "AFXPOPUPMENU/CMFCPopupMenu::GetAnimationType", "AFXPOPUPMENU/CMFCPopupMenu::GetDropDirection", "AFXPOPUPMENU/CMFCPopupMenu::GetForceMenuFocus", "AFXPOPUPMENU/CMFCPopupMenu::GetForceShadow", "AFXPOPUPMENU/CMFCPopupMenu::GetHMenu", "AFXPOPUPMENU/CMFCPopupMenu::GetMenuBar", "AFXPOPUPMENU/CMFCPopupMenu::GetMenuItem", "AFXPOPUPMENU/CMFCPopupMenu::GetMenuItemCount", "AFXPOPUPMENU/CMFCPopupMenu::GetMessageWnd", "AFXPOPUPMENU/CMFCPopupMenu::GetParentArea", "AFXPOPUPMENU/CMFCPopupMenu::GetParentButton", "AFXPOPUPMENU/CMFCPopupMenu::GetParentPopupMenu", "AFXPOPUPMENU/CMFCPopupMenu::GetParentRibbonElement", "AFXPOPUPMENU/CMFCPopupMenu::GetParentToolBar", "AFXPOPUPMENU/CMFCPopupMenu::GetQuickCustomizeType", "AFXPOPUPMENU/CMFCPopupMenu::GetSelItem", "AFXPOPUPMENU/CMFCPopupMenu::HasBeenResized", "AFXPOPUPMENU/CMFCPopupMenu::HideRarelyUsedCommands", "AFXPOPUPMENU/CMFCPopupMenu::InCommand", "AFXPOPUPMENU/CMFCPopupMenu::InsertItem", "AFXPOPUPMENU/CMFCPopupMenu::InsertSeparator", "AFXPOPUPMENU/CMFCPopupMenu::IsAlwaysClose", "AFXPOPUPMENU/CMFCPopupMenu::IsAlwaysShowEmptyToolsEntry", "AFXPOPUPMENU/CMFCPopupMenu::IsCustomizePane", "AFXPOPUPMENU/CMFCPopupMenu::IsEscClose", "AFXPOPUPMENU/CMFCPopupMenu::IsIdle", "AFXPOPUPMENU/CMFCPopupMenu::IsMenuSound", "AFXPOPUPMENU/CMFCPopupMenu::IsQuickCustomize", "AFXPOPUPMENU/CMFCPopupMenu::IsResizeble", "AFXPOPUPMENU/CMFCPopupMenu::IsRightAlign", "AFXPOPUPMENU/CMFCPopupMenu::IsScrollable", "AFXPOPUPMENU/CMFCPopupMenu::IsSendMenuSelectMsg", "AFXPOPUPMENU/CMFCPopupMenu::IsShown", "AFXPOPUPMENU/CMFCPopupMenu::MoveTo", "AFXPOPUPMENU/CMFCPopupMenu::OnCmdMsg", "AFXPOPUPMENU/CMFCPopupMenu::PostCommand", "AFXPOPUPMENU/CMFCPopupMenu::PreTranslateMessage", "AFXPOPUPMENU/CMFCPopupMenu::RecalcLayout", "AFXPOPUPMENU/CMFCPopupMenu::RemoveAllItems", "AFXPOPUPMENU/CMFCPopupMenu::RemoveItem", "AFXPOPUPMENU/CMFCPopupMenu::SaveState", "AFXPOPUPMENU/CMFCPopupMenu::SetAnimationSpeed", "AFXPOPUPMENU/CMFCPopupMenu::SetAnimationType", "AFXPOPUPMENU/CMFCPopupMenu::SetAutoDestroy", "AFXPOPUPMENU/CMFCPopupMenu::SetDefaultItem", "AFXPOPUPMENU/CMFCPopupMenu::SetForceMenuFocus", "AFXPOPUPMENU/CMFCPopupMenu::SetForceShadow", "AFXPOPUPMENU/CMFCPopupMenu::SetMaxWidth", "AFXPOPUPMENU/CMFCPopupMenu::SetMessageWnd", "AFXPOPUPMENU/CMFCPopupMenu::SetParentRibbonElement", "AFXPOPUPMENU/CMFCPopupMenu::SetQuickCustomizeType", "AFXPOPUPMENU/CMFCPopupMenu::SetQuickMode", "AFXPOPUPMENU/CMFCPopupMenu::SetRightAlign", "AFXPOPUPMENU/CMFCPopupMenu::SetSendMenuSelectMsg", "AFXPOPUPMENU/CMFCPopupMenu::ShowAllCommands", "AFXPOPUPMENU/CMFCPopupMenu::TriggerResize", "AFXPOPUPMENU/CMFCPopupMenu::UpdateAllShadows", "AFXPOPUPMENU/CMFCPopupMenu::UpdateShadow", "AFXPOPUPMENU/CMFCPopupMenu::CreateTearOffBar", "AFXPOPUPMENU/CMFCPopupMenu::OnChangeHot", "AFXPOPUPMENU/CMFCPopupMenu::OnChooseItem"] helpviewer_keywords: ["CMFCPopupMenu [MFC], CMFCPopupMenu", "CMFCPopupMenu [MFC], ActivatePopupMenu", "CMFCPopupMenu [MFC], AlwaysShowEmptyToolsEntry", "CMFCPopupMenu [MFC], AreAllCommandsShown", "CMFCPopupMenu [MFC], CheckArea", "CMFCPopupMenu [MFC], CloseMenu", "CMFCPopupMenu [MFC], Create", "CMFCPopupMenu [MFC], DefaultMouseClickOnClose", "CMFCPopupMenu [MFC], EnableMenuLogo", "CMFCPopupMenu [MFC], EnableMenuSound", "CMFCPopupMenu [MFC], EnableResize", "CMFCPopupMenu [MFC], EnableScrolling", "CMFCPopupMenu [MFC], EnableVertResize", "CMFCPopupMenu [MFC], FindSubItemByCommand", "CMFCPopupMenu [MFC], GetActiveMenu", "CMFCPopupMenu [MFC], GetAnimationSpeed", "CMFCPopupMenu [MFC], GetAnimationType", "CMFCPopupMenu [MFC], GetDropDirection", "CMFCPopupMenu [MFC], GetForceMenuFocus", "CMFCPopupMenu [MFC], GetForceShadow", "CMFCPopupMenu [MFC], GetHMenu", "CMFCPopupMenu [MFC], GetMenuBar", "CMFCPopupMenu [MFC], GetMenuItem", "CMFCPopupMenu [MFC], GetMenuItemCount", "CMFCPopupMenu [MFC], GetMessageWnd", "CMFCPopupMenu [MFC], GetParentArea", "CMFCPopupMenu [MFC], GetParentButton", "CMFCPopupMenu [MFC], GetParentPopupMenu", "CMFCPopupMenu [MFC], GetParentRibbonElement", "CMFCPopupMenu [MFC], GetParentToolBar", "CMFCPopupMenu [MFC], GetQuickCustomizeType", "CMFCPopupMenu [MFC], GetSelItem", "CMFCPopupMenu [MFC], HasBeenResized", "CMFCPopupMenu [MFC], HideRarelyUsedCommands", "CMFCPopupMenu [MFC], InCommand", "CMFCPopupMenu [MFC], InsertItem", "CMFCPopupMenu [MFC], InsertSeparator", "CMFCPopupMenu [MFC], IsAlwaysClose", "CMFCPopupMenu [MFC], IsAlwaysShowEmptyToolsEntry", "CMFCPopupMenu [MFC], IsCustomizePane", "CMFCPopupMenu [MFC], IsEscClose", "CMFCPopupMenu [MFC], IsIdle", "CMFCPopupMenu [MFC], IsMenuSound", "CMFCPopupMenu [MFC], IsQuickCustomize", "CMFCPopupMenu [MFC], IsResizeble", "CMFCPopupMenu [MFC], IsRightAlign", "CMFCPopupMenu [MFC], IsScrollable", "CMFCPopupMenu [MFC], IsSendMenuSelectMsg", "CMFCPopupMenu [MFC], IsShown", "CMFCPopupMenu [MFC], MoveTo", "CMFCPopupMenu [MFC], OnCmdMsg", "CMFCPopupMenu [MFC], PostCommand", "CMFCPopupMenu [MFC], PreTranslateMessage", "CMFCPopupMenu [MFC], RecalcLayout", "CMFCPopupMenu [MFC], RemoveAllItems", "CMFCPopupMenu [MFC], RemoveItem", "CMFCPopupMenu [MFC], SaveState", "CMFCPopupMenu [MFC], SetAnimationSpeed", "CMFCPopupMenu [MFC], SetAnimationType", "CMFCPopupMenu [MFC], SetAutoDestroy", "CMFCPopupMenu [MFC], SetDefaultItem", "CMFCPopupMenu [MFC], SetForceMenuFocus", "CMFCPopupMenu [MFC], SetForceShadow", "CMFCPopupMenu [MFC], SetMaxWidth", "CMFCPopupMenu [MFC], SetMessageWnd", "CMFCPopupMenu [MFC], SetParentRibbonElement", "CMFCPopupMenu [MFC], SetQuickCustomizeType", "CMFCPopupMenu [MFC], SetQuickMode", "CMFCPopupMenu [MFC], SetRightAlign", "CMFCPopupMenu [MFC], SetSendMenuSelectMsg", "CMFCPopupMenu [MFC], ShowAllCommands", "CMFCPopupMenu [MFC], TriggerResize", "CMFCPopupMenu [MFC], UpdateAllShadows", "CMFCPopupMenu [MFC], UpdateShadow", "CMFCPopupMenu [MFC], CreateTearOffBar", "CMFCPopupMenu [MFC], OnChangeHot", "CMFCPopupMenu [MFC], OnChooseItem"] -ms.assetid: 9555dca1-8c9c-44c9-af72-0659ddad128e --- # CMFCPopupMenu Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements Windows pop-up menu functionality and extends it by adding features such as tear-off menus and tooltips. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcpopupmenubar-class.md b/docs/mfc/reference/cmfcpopupmenubar-class.md index c3b797becac..b80cec2199f 100644 --- a/docs/mfc/reference/cmfcpopupmenubar-class.md +++ b/docs/mfc/reference/cmfcpopupmenubar-class.md @@ -4,10 +4,12 @@ title: "CMFCPopupMenuBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCPopupMenuBar", "AFXPOPUPMENUBAR/CMFCPopupMenuBar", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::AdjustSizeImmediate", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::BuildOrigItems", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::CloseDelayedSubMenu", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::ExportToMenu", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::FindDestintationToolBar", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::GetCurrentMenuImageSize", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::GetDefaultMenuId", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::GetLastCommandIndex", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::GetOffset", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::ImportFromMenu", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::IsDropDownListMode", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::IsPaletteMode", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::IsRibbonPanel", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::IsRibbonPanelInRegularMode", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::LoadFromHash", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::RestoreDelayedSubMenu", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::SetButtonStyle", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::SetOffset", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::StartPopupMenuTimer", "AFXPOPUPMENUBAR/CMFCPopupMenuBar::m_bDisableSideBarInXPMode"] helpviewer_keywords: ["CMFCPopupMenuBar [MFC], AdjustSizeImmediate", "CMFCPopupMenuBar [MFC], BuildOrigItems", "CMFCPopupMenuBar [MFC], CloseDelayedSubMenu", "CMFCPopupMenuBar [MFC], ExportToMenu", "CMFCPopupMenuBar [MFC], FindDestintationToolBar", "CMFCPopupMenuBar [MFC], GetCurrentMenuImageSize", "CMFCPopupMenuBar [MFC], GetDefaultMenuId", "CMFCPopupMenuBar [MFC], GetLastCommandIndex", "CMFCPopupMenuBar [MFC], GetOffset", "CMFCPopupMenuBar [MFC], ImportFromMenu", "CMFCPopupMenuBar [MFC], IsDropDownListMode", "CMFCPopupMenuBar [MFC], IsPaletteMode", "CMFCPopupMenuBar [MFC], IsRibbonPanel", "CMFCPopupMenuBar [MFC], IsRibbonPanelInRegularMode", "CMFCPopupMenuBar [MFC], LoadFromHash", "CMFCPopupMenuBar [MFC], RestoreDelayedSubMenu", "CMFCPopupMenuBar [MFC], SetButtonStyle", "CMFCPopupMenuBar [MFC], SetOffset", "CMFCPopupMenuBar [MFC], StartPopupMenuTimer", "CMFCPopupMenuBar [MFC], m_bDisableSideBarInXPMode"] -ms.assetid: 4c93c459-7f70-4240-8c63-280bb811e374 --- # CMFCPopupMenuBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A menu bar embedded into a pop-up menu. ## Syntax diff --git a/docs/mfc/reference/cmfcpreviewctrlimpl-class.md b/docs/mfc/reference/cmfcpreviewctrlimpl-class.md index 22d3cb15833..00f4b24cce3 100644 --- a/docs/mfc/reference/cmfcpreviewctrlimpl-class.md +++ b/docs/mfc/reference/cmfcpreviewctrlimpl-class.md @@ -1,18 +1,20 @@ --- -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 + +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. 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 +24,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 +62,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 +164,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 +222,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/cmfcprintpreviewtoolbar-class.md b/docs/mfc/reference/cmfcprintpreviewtoolbar-class.md index d4afc3ce036..12c1fad00ce 100644 --- a/docs/mfc/reference/cmfcprintpreviewtoolbar-class.md +++ b/docs/mfc/reference/cmfcprintpreviewtoolbar-class.md @@ -3,10 +3,12 @@ description: "Learn more about: CMFCPrintPreviewToolBar Class" title: "CMFCPrintPreviewToolBar Class" ms.date: "11/04/2016" helpviewer_keywords: ["CMFCPrintPreviewToolBar class [MFC]", "CMFCPrintPreviewToolBar class [MFC], destructor"] -ms.assetid: 7b9f641b-d402-4339-8815-e5247237e7e5 --- # CMFCPrintPreviewToolBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The toolbar on the print preview. ## Syntax diff --git a/docs/mfc/reference/cmfcpropertygridcolorproperty-class.md b/docs/mfc/reference/cmfcpropertygridcolorproperty-class.md index 75794a5d3ce..2f8314b97fa 100644 --- a/docs/mfc/reference/cmfcpropertygridcolorproperty-class.md +++ b/docs/mfc/reference/cmfcpropertygridcolorproperty-class.md @@ -4,10 +4,12 @@ title: "CMFCPropertyGridColorProperty Class" ms.date: "11/04/2016" f1_keywords: ["CMFCPropertyGridColorProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty::CMFCPropertyGridColorProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty::EnableAutomaticButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty::EnableOtherButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty::GetColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty::SetColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty::SetColumnsNumber", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridColorProperty::SetOriginalValue"] helpviewer_keywords: ["CMFCPropertyGridColorProperty [MFC], CMFCPropertyGridColorProperty", "CMFCPropertyGridColorProperty [MFC], EnableAutomaticButton", "CMFCPropertyGridColorProperty [MFC], EnableOtherButton", "CMFCPropertyGridColorProperty [MFC], GetColor", "CMFCPropertyGridColorProperty [MFC], SetColor", "CMFCPropertyGridColorProperty [MFC], SetColumnsNumber", "CMFCPropertyGridColorProperty [MFC], SetOriginalValue"] -ms.assetid: af37be93-a91e-40a2-9a65-0f3412c6f0f8 --- # CMFCPropertyGridColorProperty Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCPropertyGridColorProperty` class supports a property list control item that opens a color selection dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcpropertygridctrl-class.md b/docs/mfc/reference/cmfcpropertygridctrl-class.md index 319ba89f9d9..bddf570d91a 100644 --- a/docs/mfc/reference/cmfcpropertygridctrl-class.md +++ b/docs/mfc/reference/cmfcpropertygridctrl-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more detail see the source code located in the **`mfc`** folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. Supports an editable property grid control that can display properties in alphabetical or hierarchical order. @@ -179,7 +181,7 @@ virtual HRESULT accSelect( ### Parameters [in] *`flagsSelect`*\ -[in] *`varChild`*\ +[in] *`varChild`* ### Return Value @@ -235,7 +237,7 @@ void AlwaysShowUserToolTip(BOOL bShow = TRUE); ### Parameters -[in] *`bShow`*\ +[in] *`bShow`* ### Remarks @@ -524,7 +526,7 @@ virtual HRESULT get_accChildCount(long* pcountChildren); ### Parameters -[in] *`pcountChildren`*\ +[in] *`pcountChildren`* ### Return Value @@ -538,7 +540,7 @@ virtual HRESULT get_accFocus(VARIANT* pvarChild); ### Parameters -[in] *`pvarChild`*\ +[in] *`pvarChild`* ### Return Value @@ -555,7 +557,7 @@ virtual HRESULT get_accHelp( ### Parameters [in] *`varChild`*\ -[in] *`pszHelp`*\ +[in] *`pszHelp`* ### Return Value @@ -574,7 +576,7 @@ virtual HRESULT get_accHelpTopic( [in] *`pszHelpFile`*\ [in] *`varChild`*\ -[in] *`pidTopic`*\ +[in] *`pidTopic`* ### Return Value @@ -591,7 +593,7 @@ virtual HRESULT get_accKeyboardShortcut( ### Parameters [in] *`varChild`*\ -[in] *`pszKeyboardShortcut`*\ +[in] *`pszKeyboardShortcut`* ### Return Value @@ -605,7 +607,7 @@ virtual HRESULT get_accSelection(VARIANT* pvarChildren); ### Parameters -[in] *`pvarChildren`*\ +[in] *`pvarChildren`* ### Return Value @@ -781,7 +783,7 @@ CRect GetListRect() const; ### Return Value -The bounding rectangle of the property grid control. This rectange doesn't include the description area and header. +The bounding rectangle of the property grid control. This rectangle doesn't include the description area and header. ### Remarks diff --git a/docs/mfc/reference/cmfcpropertygridfileproperty-class.md b/docs/mfc/reference/cmfcpropertygridfileproperty-class.md index 7d7c329867d..00f5bffd1f0 100644 --- a/docs/mfc/reference/cmfcpropertygridfileproperty-class.md +++ b/docs/mfc/reference/cmfcpropertygridfileproperty-class.md @@ -4,10 +4,12 @@ title: "CMFCPropertyGridFileProperty Class" ms.date: "11/04/2016" f1_keywords: ["CMFCPropertyGridFileProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridFileProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridFileProperty::CMFCPropertyGridFileProperty"] helpviewer_keywords: ["CMFCPropertyGridFileProperty [MFC], CMFCPropertyGridFileProperty"] -ms.assetid: 2bb8b8b4-47fc-4798-bd5e-dc8ea0b4cd9d --- # CMFCPropertyGridFileProperty Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCPropertyGridFileProperty` class supports a property list control item that opens a file selection dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcpropertygridfontproperty-class.md b/docs/mfc/reference/cmfcpropertygridfontproperty-class.md index 9dc77057151..84b77c97caa 100644 --- a/docs/mfc/reference/cmfcpropertygridfontproperty-class.md +++ b/docs/mfc/reference/cmfcpropertygridfontproperty-class.md @@ -4,10 +4,12 @@ title: "CMFCPropertyGridFontProperty Class" ms.date: "11/04/2016" f1_keywords: ["CMFCPropertyGridFontProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridFontProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridFontProperty::CMFCPropertyGridFontProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridFontProperty::GetColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridFontProperty::GetLogFont"] helpviewer_keywords: ["CMFCPropertyGridFontProperty [MFC], CMFCPropertyGridFontProperty", "CMFCPropertyGridFontProperty [MFC], GetColor", "CMFCPropertyGridFontProperty [MFC], GetLogFont"] -ms.assetid: 83693f33-bbd3-4fcb-a9ad-fa79fcf2ca24 --- # CMFCPropertyGridFontProperty Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCPropertyGridFileProperty` class supports a property list control item that opens a font selection dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcpropertygridproperty-class.md b/docs/mfc/reference/cmfcpropertygridproperty-class.md index e00757b1415..e9a54f4ffc6 100644 --- a/docs/mfc/reference/cmfcpropertygridproperty-class.md +++ b/docs/mfc/reference/cmfcpropertygridproperty-class.md @@ -1,19 +1,22 @@ --- -description: "Learn more about: CMFCPropertyGridProperty Class" -title: "CMFCPropertyGridProperty Class" -ms.date: "11/04/2016" +title: "CMFCPropertyGridProperty class" +description: "Learn more about: CMFCPropertyGridProperty class" +ms.date: 10/12/2022 f1_keywords: ["CMFCPropertyGridProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CMFCPropertyGridProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AddOption", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AddSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AdjustButtonRect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AdjustInPlaceEditRect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::AllowEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CreateInPlaceEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CreateSpinControl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Enable", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::EnableSpinControl", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Expand", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::FormatProperty", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetData", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetDescription", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetExpandedSubItems", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetHierarchyLevel", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetNameTooltip", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetOption", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetOptionCount", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetOriginalValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetParent", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetRect", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetSubItemsCount", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::GetValueTooltip", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::HitTest", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsAllowEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsEnabled", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsExpanded", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsGroup", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsInPlaceEditing", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsModified", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsParentExpanded", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsSelected", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsVisible", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnClickButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnClickName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnClickValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnCloseCombo", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDblClk", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawDescription", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawExpandBox", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDrawValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnEndEdit", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnKillSelection", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnPosSizeChanged", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnRClickName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnRClickValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnSelectCombo", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnSetCursor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnSetSelection", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnUpdateValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::PushChar", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Redraw", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::RemoveAllOptions", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::RemoveSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::ResetOriginalValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetData", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetDescription", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetName", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetOriginalValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::SetValue", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Show", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::CreateCombo", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::HasButton", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::Init", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsSubItem", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::IsValueChanged", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnCtlColor", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnDestroyWindow", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::OnKillFocus", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatDouble", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatFloat", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatLong", "AFXPROPERTYGRIDCTRL/CMFCPropertyGridProperty::m_strFormatShort"] helpviewer_keywords: ["CMFCPropertyGridProperty [MFC], CMFCPropertyGridProperty", "CMFCPropertyGridProperty [MFC], AddOption", "CMFCPropertyGridProperty [MFC], AddSubItem", "CMFCPropertyGridProperty [MFC], AdjustButtonRect", "CMFCPropertyGridProperty [MFC], AdjustInPlaceEditRect", "CMFCPropertyGridProperty [MFC], AllowEdit", "CMFCPropertyGridProperty [MFC], CreateInPlaceEdit", "CMFCPropertyGridProperty [MFC], CreateSpinControl", "CMFCPropertyGridProperty [MFC], Enable", "CMFCPropertyGridProperty [MFC], EnableSpinControl", "CMFCPropertyGridProperty [MFC], Expand", "CMFCPropertyGridProperty [MFC], FormatProperty", "CMFCPropertyGridProperty [MFC], GetData", "CMFCPropertyGridProperty [MFC], GetDescription", "CMFCPropertyGridProperty [MFC], GetExpandedSubItems", "CMFCPropertyGridProperty [MFC], GetHierarchyLevel", "CMFCPropertyGridProperty [MFC], GetName", "CMFCPropertyGridProperty [MFC], GetNameTooltip", "CMFCPropertyGridProperty [MFC], GetOption", "CMFCPropertyGridProperty [MFC], GetOptionCount", "CMFCPropertyGridProperty [MFC], GetOriginalValue", "CMFCPropertyGridProperty [MFC], GetParent", "CMFCPropertyGridProperty [MFC], GetRect", "CMFCPropertyGridProperty [MFC], GetSubItem", "CMFCPropertyGridProperty [MFC], GetSubItemsCount", "CMFCPropertyGridProperty [MFC], GetValue", "CMFCPropertyGridProperty [MFC], GetValueTooltip", "CMFCPropertyGridProperty [MFC], HitTest", "CMFCPropertyGridProperty [MFC], IsAllowEdit", "CMFCPropertyGridProperty [MFC], IsEnabled", "CMFCPropertyGridProperty [MFC], IsExpanded", "CMFCPropertyGridProperty [MFC], IsGroup", "CMFCPropertyGridProperty [MFC], IsInPlaceEditing", "CMFCPropertyGridProperty [MFC], IsModified", "CMFCPropertyGridProperty [MFC], IsParentExpanded", "CMFCPropertyGridProperty [MFC], IsSelected", "CMFCPropertyGridProperty [MFC], IsVisible", "CMFCPropertyGridProperty [MFC], OnClickButton", "CMFCPropertyGridProperty [MFC], OnClickName", "CMFCPropertyGridProperty [MFC], OnClickValue", "CMFCPropertyGridProperty [MFC], OnCloseCombo", "CMFCPropertyGridProperty [MFC], OnDblClk", "CMFCPropertyGridProperty [MFC], OnDrawButton", "CMFCPropertyGridProperty [MFC], OnDrawDescription", "CMFCPropertyGridProperty [MFC], OnDrawExpandBox", "CMFCPropertyGridProperty [MFC], OnDrawName", "CMFCPropertyGridProperty [MFC], OnDrawValue", "CMFCPropertyGridProperty [MFC], OnEdit", "CMFCPropertyGridProperty [MFC], OnEndEdit", "CMFCPropertyGridProperty [MFC], OnKillSelection", "CMFCPropertyGridProperty [MFC], OnPosSizeChanged", "CMFCPropertyGridProperty [MFC], OnRClickName", "CMFCPropertyGridProperty [MFC], OnRClickValue", "CMFCPropertyGridProperty [MFC], OnSelectCombo", "CMFCPropertyGridProperty [MFC], OnSetCursor", "CMFCPropertyGridProperty [MFC], OnSetSelection", "CMFCPropertyGridProperty [MFC], OnUpdateValue", "CMFCPropertyGridProperty [MFC], PushChar", "CMFCPropertyGridProperty [MFC], Redraw", "CMFCPropertyGridProperty [MFC], RemoveAllOptions", "CMFCPropertyGridProperty [MFC], RemoveSubItem", "CMFCPropertyGridProperty [MFC], ResetOriginalValue", "CMFCPropertyGridProperty [MFC], SetData", "CMFCPropertyGridProperty [MFC], SetDescription", "CMFCPropertyGridProperty [MFC], SetName", "CMFCPropertyGridProperty [MFC], SetOriginalValue", "CMFCPropertyGridProperty [MFC], SetValue", "CMFCPropertyGridProperty [MFC], Show", "CMFCPropertyGridProperty [MFC], CreateCombo", "CMFCPropertyGridProperty [MFC], HasButton", "CMFCPropertyGridProperty [MFC], Init", "CMFCPropertyGridProperty [MFC], IsSubItem", "CMFCPropertyGridProperty [MFC], IsValueChanged", "CMFCPropertyGridProperty [MFC], OnCtlColor", "CMFCPropertyGridProperty [MFC], OnDestroyWindow", "CMFCPropertyGridProperty [MFC], OnKillFocus", "CMFCPropertyGridProperty [MFC], m_strFormatDouble", "CMFCPropertyGridProperty [MFC], m_strFormatFloat", "CMFCPropertyGridProperty [MFC], m_strFormatLong", "CMFCPropertyGridProperty [MFC], m_strFormatShort"] --- -# `CMFCPropertyGridProperty` Class +# `CMFCPropertyGridProperty` class + +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. A `CMFCPropertyGridProperty` object represents a list item in a property list control. - For more detail see the source code located in the **`mfc`** folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. + For more detail, see the source code located in the **`mfc`** folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. ## Syntax -``` +```cpp class CMFCPropertyGridProperty : public CObject ``` @@ -39,11 +42,11 @@ class CMFCPropertyGridProperty : public CObject |[`CMFCPropertyGridProperty::CreateSpinControl`](#createspincontrol)|Called by the framework to create an editable spin button control.| |[`CMFCPropertyGridProperty::Enable`](#enable)|Enables or disables a property.| |[`CMFCPropertyGridProperty::EnableSpinControl`](#enablespincontrol)|Enables or disables a spin button control that is used to modify a property value.| -|[`CMFCPropertyGridProperty::Expand`](#expand)|Expands or collapses a property that contains sub-properties.| +|[`CMFCPropertyGridProperty::Expand`](#expand)|Expands or collapses a property that contains subproperties.| |[`CMFCPropertyGridProperty::FormatProperty`](#formatproperty)|Formats the text representation of a property value.| |[`CMFCPropertyGridProperty::GetData`](#getdata)|Retrieves a DWORD value that is associated with a property.| |[`CMFCPropertyGridProperty::GetDescription`](#getdescription)|Retrieves a property description.| -|[`CMFCPropertyGridProperty::GetExpandedSubItems`](#getexpandedsubitems)|Retrieves the number of expanded sub-items.| +|[`CMFCPropertyGridProperty::GetExpandedSubItems`](#getexpandedsubitems)|Retrieves the number of expanded subitems.| |[`CMFCPropertyGridProperty::GetHierarchyLevel`](#gethierarchylevel)|Retrieves the zero-based index of the property's hierarchy level.| |[`CMFCPropertyGridProperty::GetName`](#getname)|Retrieves the name of the property.| |[`CMFCPropertyGridProperty::GetNameTooltip`](#getnametooltip)|Called by the framework to display the name of the property in a tooltip.| @@ -52,8 +55,8 @@ class CMFCPropertyGridProperty : public CObject |[`CMFCPropertyGridProperty::GetOriginalValue`](#getoriginalvalue)|Retrieves the initial value of the current property.| |[`CMFCPropertyGridProperty::GetParent`](#getparent)|Retrieves a pointer to a parent property.| |[`CMFCPropertyGridProperty::GetRect`](#getrect)|Retrieves the bounding rectangle of a property.| -|[`CMFCPropertyGridProperty::GetSubItem`](#getsubitem)|Retrieves a sub-property identified by a zero-based index.| -|[`CMFCPropertyGridProperty::GetSubItemsCount`](#getsubitemscount)|Retrieves the number of sub-items.| +|[`CMFCPropertyGridProperty::GetSubItem`](#getsubitem)|Retrieves a subproperty identified by a zero-based index.| +|[`CMFCPropertyGridProperty::GetSubItemsCount`](#getsubitemscount)|Retrieves the number of subitems.| |`CMFCPropertyGridProperty::GetThisClass`|Used by the framework to obtain a pointer to the [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) object that is associated with this class type.| |[`CMFCPropertyGridProperty::GetValue`](#getvalue)|Retrieves a property value.| |[`CMFCPropertyGridProperty::GetValueTooltip`](#getvaluetooltip)|Called by the framework to retrieve the text representation of the property value that is then displayed in a tooltip.| @@ -74,7 +77,7 @@ class CMFCPropertyGridProperty : public CObject |[`CMFCPropertyGridProperty::OnDblClk`](#ondblclk)|Called by the framework when the user double clicks a property.| |[`CMFCPropertyGridProperty::OnDrawButton`](#ondrawbutton)|Called by the framework to draw a button that is contained in a property.| |[`CMFCPropertyGridProperty::OnDrawDescription`](#ondrawdescription)|Called by the framework to display the property description.| -|[`CMFCPropertyGridProperty::OnDrawExpandBox`](#ondrawexpandbox)|Called by the framework to draw an expand box control near a property that contains sub-properties.| +|[`CMFCPropertyGridProperty::OnDrawExpandBox`](#ondrawexpandbox)|Called by the framework to draw an expand box control near a property that contains subproperties.| |[`CMFCPropertyGridProperty::OnDrawName`](#ondrawname)|Called by the framework to display the property name.| |[`CMFCPropertyGridProperty::OnDrawValue`](#ondrawvalue)|Called by the framework to display the property value.| |[`CMFCPropertyGridProperty::OnEdit`](#onedit)|Called by the framework when the user is about to modify a property value.| @@ -90,7 +93,7 @@ class CMFCPropertyGridProperty : public CObject |[`CMFCPropertyGridProperty::PushChar`](#pushchar)|Called from the property list control when the property is selected and the user enters a new character.| |[`CMFCPropertyGridProperty::Redraw`](#redraw)|Redraws the property.| |[`CMFCPropertyGridProperty::RemoveAllOptions`](#removealloptions)|Removes all options (items) from a property.| -|[`CMFCPropertyGridProperty::RemoveSubItem`](#removesubitem)|Removes the specified sub-item.| +|[`CMFCPropertyGridProperty::RemoveSubItem`](#removesubitem)|Removes the specified subitem.| |[`CMFCPropertyGridProperty::ResetOriginalValue`](#resetoriginalvalue)|Restores the original value of an edited property.| |[`CMFCPropertyGridProperty::SetData`](#setdata)|Associates a DWORD value with a property.| |[`CMFCPropertyGridProperty::SetDescription`](#setdescription)|Specifies the text that describes the current property.| @@ -106,7 +109,7 @@ class CMFCPropertyGridProperty : public CObject |[`CMFCPropertyGridProperty::CreateCombo`](#createcombo)|Called by the framework to add a combo box to a property.| |[`CMFCPropertyGridProperty::HasButton`](#hasbutton)|Indicates whether a property contains a button.| |[`CMFCPropertyGridProperty::Init`](#init)|Called by the framework to initialize a property object.| -|[`CMFCPropertyGridProperty::IsSubItem`](#issubitem)|Indicates whether the specified property is a sub-item of the current property.| +|[`CMFCPropertyGridProperty::IsSubItem`](#issubitem)|Indicates whether the specified property is a subitem of the current property.| |[`CMFCPropertyGridProperty::IsValueChanged`](#isvaluechanged)|Indicates whether the value of the current property has changed.| |[`CMFCPropertyGridProperty::OnCtlColor`](#onctlcolor)|Called by the framework when it must retrieve a brush to fill the background color of a property.| |[`CMFCPropertyGridProperty::OnDestroyWindow`](#ondestroywindow)|Called by the framework when a property is destroyed or when editing is finished.| @@ -129,7 +132,7 @@ A property object can represent data types such as strings, dates, and Boolean o ## Example -The following example demonstrates how to construct a `CMFCPropertyGridProperty` object. The example also demonstrates how to use various methods in the `CMFCPropertyGridProperty` class to add an option, add a sub-item, enable a property, and show a property. This example is part of the [New Controls sample](../../overview/visual-cpp-samples.md). +The following example demonstrates how to construct a `CMFCPropertyGridProperty` object. The example also demonstrates how to use various methods in the `CMFCPropertyGridProperty` class to add an option, add a subitem, enable a property, and show a property. This example is part of the [New Controls sample](../../overview/visual-cpp-samples.md). [!code-cpp[NVC_MFC_NewControls#27](../../mfc/reference/codesnippet/cpp/cmfcpropertygridproperty-class_1.cpp)] @@ -147,7 +150,7 @@ The following example demonstrates how to construct a `CMFCPropertyGridProperty` Adds a new list item to a property list control. -``` +```cpp BOOL AddOption( LPCTSTR lpszOption, BOOL bInsertUnique=TRUE); @@ -165,13 +168,11 @@ BOOL AddOption( `TRUE`, which means that the list item is added. Otherwise, `FALSE`, which means that the list item isn't added because the *`bInsertUnique`* parameter is `TRUE` and the list item specified by the *`lpszOption`* parameter already exists. -### Remarks - ## `CMFCPropertyGridProperty::AddSubItem` Adds a child item to a property. -``` +```cpp BOOL AddSubItem(CMFCPropertyGridProperty* pProp); ``` @@ -192,7 +193,7 @@ Use this method to create a hierarchical list of parent and child properties. Af Called by the parent property list control to tell a property to resize the bounding rectangle of an embedded button. -``` +```cpp virtual void AdjustButtonRect(); ``` @@ -200,17 +201,15 @@ virtual void AdjustButtonRect(); By default, this method: -- Adjusts the width of the button equal to the height of the button plus 3 pixels. - +- Adjusts the width of the button equal to the height of the button plus three pixels. - Moves the bounding rectangle of the button to the right edge of the property. - - Shifts the button 1 pixel below the top edge of the property. ## `CMFCPropertyGridProperty::AdjustInPlaceEditRect` Retrieves the boundaries of the text box and optional spin button control that are used to set a property value. -``` +```cpp virtual void AdjustInPlaceEditRect( CRect& rectEdit, CRect& rectSpin); @@ -241,13 +240,11 @@ void AllowEdit(BOOL bAllow=TRUE); *`bAllow`*\ [in] `TRUE` to make the property editable; `FALSE` to make the property read-only. The default value is `TRUE`. -### Remarks - ## `CMFCPropertyGridProperty::CMFCPropertyGridProperty` Constructs a `CMFCPropertyGridProperty` object. -``` +```cpp CMFCPropertyGridProperty( const CString& strGroupName, DWORD_PTR dwData=0, @@ -292,13 +289,11 @@ CMFCPropertyGridProperty( *`bIsValueList`*\ [in] `TRUE` if the property represents a list of values; `FALSE` if the property represents a single value. The default value is `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::CreateCombo` Called by the framework to add a combo box to a property. -``` +```cpp virtual CComboBox* CreateCombo( CWnd* pWndParent, CRect rect); @@ -316,13 +311,11 @@ virtual CComboBox* CreateCombo( Pointer to a new [`CComboBox`](../../mfc/reference/ccombobox-class.md) object. -### Remarks - ## `CMFCPropertyGridProperty::CreateInPlaceEdit` Called by the framework to create an editable control for a property. -``` +```cpp virtual CWnd* CreateInPlaceEdit( CRect rectEdit, BOOL& bDefaultFormat); @@ -350,7 +343,7 @@ This method creates a [`CMFCMaskedEdit`](../../mfc/reference/cmfcmaskededit-clas Called by the framework to create an editable spin button control. -``` +```cpp virtual CSpinButtonCtrl* CreateSpinControl(CRect rectSpin); ``` @@ -380,8 +373,6 @@ void Enable(BOOL bEnable=TRUE); *`bEnable`*\ [in] `TRUE` to enable the property; `FALSE` to disable the property. Disabled properties don't respond to mouse or keyboard input. The default value is `TRUE`. -### Remarks - ## `CMFCPropertyGridProperty::EnableSpinControl` Enables or disables a spin button control that is used to modify a property value. @@ -412,7 +403,7 @@ The property type, which is specified by the *`varValue`* parameter of the [`CMF ## `CMFCPropertyGridProperty::Expand` -Expands or collapses a property that contains sub-properties. +Expands or collapses a property that contains subproperties. ```cpp void Expand(BOOL bExpand=TRUE); @@ -423,13 +414,11 @@ void Expand(BOOL bExpand=TRUE); *`bExpand`*\ [in] `TRUE` to expand the property; `FALSE` to collapse the property. The default value is `TRUE`. -### Remarks - ## `CMFCPropertyGridProperty::FormatProperty` Formats the text representation of a property value. -``` +```cpp virtual CString FormatProperty(); ``` @@ -445,7 +434,7 @@ This method is called by the framework before the property value is displayed. Retrieves a `DWORD` value that is associated with a property. -``` +```cpp DWORD_PTR GetData() const; ``` @@ -461,7 +450,7 @@ The data that is returned is an application-specific value, such as a number or Retrieves a property description. -``` +```cpp const CString& GetDescription() const; ``` @@ -475,28 +464,26 @@ Property list control also uses this method to display the description of the pr ## `CMFCPropertyGridProperty::GetExpandedSubItems` -Retrieves the number of expanded sub-items. +Retrieves the number of expanded subitems. -``` +```cpp int GetExpandedSubItems(BOOL bIncludeHidden=TRUE) const; ``` ### Parameters *`bIncludeHidden`*\ -[in] `TRUE` to include the hidden sub-items in the count; otherwise, `FALSE`. The default value is `TRUE`. +[in] `TRUE` to include the hidden subitems in the count; otherwise, `FALSE`. The default value is `TRUE`. ### Return Value -The number of expanded sub-items. - -### Remarks +The number of expanded subitems. ## `CMFCPropertyGridProperty::GetHierarchyLevel` Retrieves the zero-based index of the property's hierarchy level. -``` +```cpp int GetHierarchyLevel() const; ``` @@ -504,13 +491,11 @@ int GetHierarchyLevel() const; The property's hierarchical level. -### Remarks - ## `CMFCPropertyGridProperty::GetName` Retrieves the name of the property. -``` +```cpp LPCTSTR GetName() const; ``` @@ -518,13 +503,11 @@ LPCTSTR GetName() const; Pointer to a string that contains the name of the property. -### Remarks - ## `CMFCPropertyGridProperty::GetNameTooltip` Called by the framework to display the name of the property in a tooltip. -``` +```cpp virtual CString GetNameTooltip(); ``` @@ -532,13 +515,11 @@ virtual CString GetNameTooltip(); A string that contains the property name. By default, the return value is the empty string. -### Remarks - ## `CMFCPropertyGridProperty::GetOption` Retrieves the text of the option that is specified by an index. -``` +```cpp LPCTSTR GetOption(int nIndex) const; ``` @@ -551,13 +532,11 @@ The zero-based index of the property list item (option) to retrieve. Pointer to a string that contains the option text. -### Remarks - ## `CMFCPropertyGridProperty::GetOptionCount` Retrieves the number of options that belong to a property. -``` +```cpp int GetOptionCount() const; ``` @@ -573,7 +552,7 @@ Call the [`CMFCPropertyGridProperty::AddOption`](#addoption) method to add items Retrieves the initial value of the current property. -``` +```cpp const COleVariant& GetOriginalValue() const; ``` @@ -591,7 +570,7 @@ The original value of the current property is set by the [`CMFCPropertyGridPrope Retrieves a pointer to a parent property. -``` +```cpp CMFCPropertyGridProperty* GetParent() const; ``` @@ -599,13 +578,11 @@ CMFCPropertyGridProperty* GetParent() const; A pointer to a parent property object, or `NULL` for the top-level property. -### Remarks - ## `CMFCPropertyGridProperty::GetRect` Retrieves the bounding rectangle of a property. -``` +```cpp CRect GetRect() const; ``` @@ -613,20 +590,18 @@ CRect GetRect() const; A [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object that describes the bounding rectangle. -### Remarks - ## `CMFCPropertyGridProperty::GetSubItem` -Retrieves a sub-property identified by a zero-based index. +Retrieves a subproperty identified by a zero-based index. -``` +```cpp CMFCPropertyGridProperty* GetSubItem(int nIndex) const; ``` ### Parameters *`nIndex`*\ -[in] The zero-based index of the property to retrieve. This parameter is invalid if it's less than zero or greater than or equal to the number of sub-properties. +[in] The zero-based index of the property to retrieve. This parameter is invalid if it's less than zero or greater than or equal to the number of subproperties. ### Return Value @@ -636,13 +611,11 @@ A pointer to a property object that is a child item of this property. In retail mode, `NULL` if the *`nIndex`* parameter is invalid. In debug mode, this method asserts. -### Remarks - ## `CMFCPropertyGridProperty::GetSubItemsCount` -Retrieves the number of sub-items. +Retrieves the number of subitems. -``` +```cpp int GetSubItemsCount() const; ``` @@ -650,13 +623,11 @@ int GetSubItemsCount() const; The number of child items. -### Remarks - ## `CMFCPropertyGridProperty::GetValue` Retrieves a property value. -``` +```cpp virtual const _variant_t& GetValue() const; ``` @@ -664,13 +635,11 @@ virtual const _variant_t& GetValue() const; A variant that contains the property value. -### Remarks - ## `CMFCPropertyGridProperty::GetValueTooltip` Called by the framework to retrieve the text representation of the property value that is then displayed in a tooltip. -``` +```cpp virtual CString GetValueTooltip(); ``` @@ -678,13 +647,11 @@ virtual CString GetValueTooltip(); A `CString` object containing the textual representation of the property value. By default, this value is the empty string. -### Remarks - ## `CMFCPropertyGridProperty::HasButton` Indicates whether a property contains a button. -``` +```cpp virtual BOOL HasButton() const; ``` @@ -692,13 +659,11 @@ virtual BOOL HasButton() const; `TRUE` if a property contains a button (or property list); otherwise, `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::HitTest` Points to the property object that corresponds to the property list item that corresponds to a point. -``` +```cpp CMFCPropertyGridProperty* HitTest( CPoint point, CMFCPropertyGridProperty::ClickArea* pnArea=NULL); @@ -729,7 +694,7 @@ A pointer to a property object or `NULL`. ### Remarks -By default, this method tests property sub-items if the specified point isn't found within any of the property items. +By default, this method tests property subitems if the specified point isn't found within any of the property items. The following table lists the values that can be returned to the *`pnArea`* parameter. @@ -747,13 +712,11 @@ Called by the framework to initialize a property object. void Init(); ``` -### Remarks - ## `CMFCPropertyGridProperty::IsAllowEdit` Indicates whether a property is editable. -``` +```cpp BOOL IsAllowEdit() const; ``` @@ -761,13 +724,11 @@ BOOL IsAllowEdit() const; `TRUE` if the property is editable; otherwise `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::IsEnabled` Indicates whether a property is enabled or disabled. -``` +```cpp BOOL IsEnabled() const; ``` @@ -783,7 +744,7 @@ Tells whether a property is enabled or disabled. Indicates whether a property is expanded or collapsed. -``` +```cpp BOOL IsExpanded() const; ``` @@ -791,13 +752,11 @@ BOOL IsExpanded() const; `TRUE` if the property is expanded; `FALSE` if the property is collapsed. -### Remarks - ## `CMFCPropertyGridProperty::IsGroup` Indicates whether the current property represents a group. -``` +```cpp BOOL IsGroup() const; ``` @@ -813,7 +772,7 @@ A *group* is a collection of related properties in a property grid control. If t Indicates whether the current property is editable. -``` +```cpp BOOL IsInPlaceEditing() const; ``` @@ -821,13 +780,11 @@ BOOL IsInPlaceEditing() const; `TRUE` if the current property is editable; otherwise, `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::IsModified` Indicates whether the current property is modified. -``` +```cpp BOOL IsModified() const; ``` @@ -835,13 +792,11 @@ BOOL IsModified() const; `TRUE` if the property is modified; otherwise, `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::IsParentExpanded` Indicates whether the parents of the current property are expanded. -``` +```cpp BOOL IsParentExpanded() const; ``` @@ -849,13 +804,11 @@ BOOL IsParentExpanded() const; `TRUE` if all parents of the current property are expanded; `FALSE` if the parent properties are collapsed. -### Remarks - ## `CMFCPropertyGridProperty::IsSelected` Indicates whether the current property is selected. -``` +```cpp virtual BOOL IsSelected() const; ``` @@ -863,13 +816,11 @@ virtual BOOL IsSelected() const; `TRUE` if the current property is selected; otherwise, `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::IsSubItem` -Indicates whether the specified property is a sub-item of the current property. +Indicates whether the specified property is a subitem of the current property. -``` +```cpp BOOL IsSubItem(CMFCPropertyGridProperty* pProp) const; ``` @@ -880,13 +831,13 @@ BOOL IsSubItem(CMFCPropertyGridProperty* pProp) const; ### Return Value -`TRUE` if the specified property is a sub-item of the current property; otherwise, `FALSE`. +`TRUE` if the specified property is a subitem of the current property; otherwise, `FALSE`. ## `CMFCPropertyGridProperty::IsValueChanged` Indicates whether the value of the current property has changed. -``` +```cpp virtual BOOL IsValueChanged() const; ``` @@ -894,13 +845,11 @@ virtual BOOL IsValueChanged() const; `TRUE` if the value of the current property has changed; otherwise, `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::IsVisible` Indicates whether the current property is visible. -``` +```cpp BOOL IsVisible() const; ``` @@ -908,53 +857,43 @@ BOOL IsVisible() const; `TRUE` if the current property is visible; otherwise; `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::m_strFormatDouble` Holds a format string for a value of type double. -``` +```cpp static CString m_strFormatDouble; ``` -### Remarks - ## `CMFCPropertyGridProperty::m_strFormatFloat` Holds a format string for a value of type float. -``` +```cpp static CString m_strFormatFloat; ``` -### Remarks - ## `CMFCPropertyGridProperty::m_strFormatLong` Holds a format string for a value of type long. -``` +```cpp static CString m_strFormatLong; ``` -### Remarks - ## `CMFCPropertyGridProperty::m_strFormatShort` Holds a format string for a value of type short. -``` +```cpp static CString m_strFormatShort; ``` -### Remarks - ## `CMFCPropertyGridProperty::OnClickButton` Called by the framework when the user selects a button that is contained in a property. -``` +```cpp virtual void OnClickButton(CPoint point); ``` @@ -971,7 +910,7 @@ By default, this method does nothing. Called by a parent property list control when a user selects the name field of a property. -``` +```cpp virtual void OnClickName(CPoint C); ``` @@ -988,7 +927,7 @@ By default, this method does nothing. Called by a parent property list control when a user selects the value field of a property. -``` +```cpp virtual BOOL OnClickValue( UINT uiMsg, CPoint point); @@ -1014,17 +953,15 @@ By default, this method returns `FALSE` if the current property isn't editable. Called by the framework when a combo box that is contained in a property is closed. -``` +```cpp virtual void OnCloseCombo(); ``` -### Remarks - ## `CMFCPropertyGridProperty::OnCtlColor` Called by the framework when it must retrieve a brush to fill the background color of a property. -``` +```cpp virtual HBRUSH OnCtlColor( CDC* pDC, UINT nCtlColor); @@ -1042,13 +979,11 @@ virtual HBRUSH OnCtlColor( The handle to a brush if this method is successful; otherwise, `NULL`. -### Remarks - ## `CMFCPropertyGridProperty::OnDblClk` Called by the framework when the user double clicks a property. -``` +```cpp virtual BOOL OnDblClk(CPoint point); ``` @@ -1069,17 +1004,15 @@ By default, this method selects the next property item in the property list cont Called by the framework when a property is destroyed or when editing is finished. -``` +```cpp virtual void OnDestroyWindow(); ``` -### Remarks - ## `CMFCPropertyGridProperty::OnDrawButton` Called by the framework to draw a button that is contained in a property. -``` +```cpp virtual void OnDrawButton( CDC* pDC, CRect rectButton); @@ -1093,13 +1026,11 @@ virtual void OnDrawButton( *`rectButton`*\ [in] A bounding rectangle that specifies where to draw a button. -### Remarks - ## `CMFCPropertyGridProperty::OnDrawDescription` Called by the framework to draw the property description. -``` +```cpp virtual void OnDrawDescription( CDC* pDC, CRect rect); @@ -1119,9 +1050,9 @@ By default, this method draws the property name and description in the font used ## `CMFCPropertyGridProperty::OnDrawExpandBox` -Called by the framework to draw an expand box control near a property that contains sub-properties. +Called by the framework to draw an expand box control near a property that contains subproperties. -``` +```cpp virtual void OnDrawExpandBox( CDC* pDC, CRect rectExpand); @@ -1137,13 +1068,13 @@ virtual void OnDrawExpandBox( ### Remarks -Select the expand box control to expand or collapse a list of sub-properties. The expand box control is designated by a square that contains a plus (**+**) or minus (**-**) sign. A plus sign indicates that the property can be expanded to show a list of sub-properties. A minus sign indicates that the list can be collapsed to show only the property. +Select the expand box control to expand or collapse a list of subproperties. The expand box control is designated by a square that contains a plus (**+**) or minus (**-**) sign. A plus sign indicates that the property can be expanded to show a list of subproperties. A minus sign indicates that the list can be collapsed to show only the property. ## `CMFCPropertyGridProperty::OnDrawName` Called by the framework to display the property name. -``` +```cpp virtual void OnDrawName( CDC* pDC, CRect rect); @@ -1157,13 +1088,11 @@ virtual void OnDrawName( *`rect`*\ [in] A bounding rectangle that specifies where to draw the property name. -### Remarks - ## `CMFCPropertyGridProperty::OnDrawValue` Called by the framework to display the property value. -``` +```cpp virtual void OnDrawValue( CDC* pDC, CRect rect); @@ -1177,13 +1106,11 @@ virtual void OnDrawValue( *`rect`*\ [in] A bounding rectangle that specifies where to draw the property value. -### Remarks - ## `CMFCPropertyGridProperty::OnEdit` Called by the framework when the user is about to modify a property value. -``` +```cpp virtual BOOL OnEdit(LPPOINT lptClick); ``` @@ -1204,7 +1131,7 @@ This function is called by the framework when the user is about to modify a prop Called by the framework when the user is finished modifying a property value. -``` +```cpp virtual BOOL OnEndEdit(); ``` @@ -1220,7 +1147,7 @@ By default, this method destroys the current editing control and then returns `T Called by the framework when the property loses the input focus. -``` +```cpp virtual BOOL OnKillFocus(CWnd*); ``` @@ -1239,13 +1166,13 @@ By default, this method does nothing and then returns `TRUE`. If you override th ## `CMFCPropertyGridProperty::OnKillSelection` -``` +```cpp virtual void OnKillSelection(CMFCPropertyGridProperty*); ``` ### Parameters -[in] *`CMFCPropertyGridProperty*`*\ +[in] *`CMFCPropertyGridProperty*`* ### Remarks @@ -1253,13 +1180,13 @@ By default, this method does nothing. ## `CMFCPropertyGridProperty::OnPosSizeChanged` -``` +```cpp virtual void OnPosSizeChanged(CRect); ``` ### Parameters -[in] *`CRect`*\ +[in] *`CRect`* ### Remarks @@ -1269,7 +1196,7 @@ By default, this method does nothing. Called by the framework when the user selects the right mouse button in the property name area. -``` +```cpp virtual void OnRClickName(CPoint C); ``` @@ -1286,7 +1213,7 @@ By default, this method does nothing. Called by the framework when the user selects the right mouse button in the property value area. -``` +```cpp virtual void OnRClickValue( CPoint C, BOOL B); @@ -1308,7 +1235,7 @@ By default, this method does nothing and the *`B`* parameter has no predefined p Called by the framework when the user selects an item from the editable combo box. -``` +```cpp virtual void OnSelectCombo(); ``` @@ -1320,7 +1247,7 @@ By default, this method uses the text of the selected item to update the propert Called by the framework when the mouse pointer moves to a property item. -``` +```cpp virtual BOOL OnSetCursor() const; ``` @@ -1334,13 +1261,13 @@ This method supports the following variant types: `VT_INT`, `VT_I2`, `VT_I4`, `V ## `CMFCPropertyGridProperty::OnSetSelection` -``` -virtual void OnSetSelection CMFCPropertyGridProperty*); +```cpp +virtual void OnSetSelection(CMFCPropertyGridProperty*); ``` ### Parameters -[in] *`CMFCPropertyGridProperty*`*\ +[in] *`CMFCPropertyGridProperty*`* ### Remarks @@ -1350,7 +1277,7 @@ By default, this method does nothing. Called by the framework when the value of an editable property has changed. -``` +```cpp virtual BOOL OnUpdateValue(); ``` @@ -1358,13 +1285,11 @@ virtual BOOL OnUpdateValue(); `TRUE` if this method is successful; otherwise, `FALSE`. -### Remarks - ## `CMFCPropertyGridProperty::PushChar` Called from the property list control when the property is selected and the user enters a new character. -``` +```cpp virtual BOOL PushChar(UINT nChar); ``` @@ -1389,8 +1314,6 @@ Redraws the property. void Redraw(); ``` -### Remarks - ## `CMFCPropertyGridProperty::RemoveAllOptions` Removes all options (items) from a property. @@ -1405,9 +1328,9 @@ Options are also known as the list items of a property list control. ## `CMFCPropertyGridProperty::RemoveSubItem` -Removes the specified sub-item. +Removes the specified subitem. -``` +```cpp BOOL RemoveSubItem( CMFCPropertyGridProperty*& pProp, BOOL bDelete=TRUE); @@ -1416,7 +1339,7 @@ BOOL RemoveSubItem( ### Parameters *`pProp`*\ -[in] Pointer to a property sub-item. +[in] Pointer to a property subitem. *`bDelete`*\ [in] `TRUE` to delete the property object that is specified by the *`pProp`* parameter; otherwise, `FALSE`. The default value is `TRUE`. @@ -1425,18 +1348,16 @@ BOOL RemoveSubItem( ### Remarks -Specify `FALSE` for the *`bDelete`* parameter if you intend to move the specified sub-item; that is, remove the sub-item and then add it elsewhere. +Specify `FALSE` for the *`bDelete`* parameter if you intend to move the specified subitem; that is, remove the subitem and then add it elsewhere. ## `CMFCPropertyGridProperty::ResetOriginalValue` Restores the original value of an edited property. -``` +```cpp virtual void ResetOriginalValue(); ``` -### Remarks - ## `CMFCPropertyGridProperty::SetData` Associates a `DWORD` value with a property. @@ -1467,8 +1388,6 @@ void SetDescription(const CString& strDescr); *`strDescr`*\ [in] Text that describes the current property. -### Remarks - ## `CMFCPropertyGridProperty::SetName` Sets the name of a property. @@ -1487,13 +1406,11 @@ void SetName( *`bRedraw`*\ [in] `TRUE` to redraw the property immediately; otherwise, `FALSE`. The default value is `TRUE`. -### Remarks - ## `CMFCPropertyGridProperty::SetOriginalValue` Sets the original value of an editable property. -``` +```cpp virtual void SetOriginalValue(const COleVariant& varValue); ``` @@ -1510,16 +1427,27 @@ Use the [`CMFCPropertyGridProperty::ResetOriginalValue`](#resetoriginalvalue) me Sets the value of a property grid property. -``` +```cpp virtual void SetValue(const _variant_t& varValue); ``` ### Parameters *`varValue`*\ -[in] A reference to a value. +[in] A reference to the value to set the property to. -### Remarks +### Example: `SetValue` + +```cpp +void SetPropBarValue(UINT propId, const DWORD& barPropDwordValue) +{ + auto property = propertiesGridCtrlList.FindItemByData(propId); + if (property != nullptr) + { + property->SetValue(static_cast<_variant_t >(barPropDwordValue == 1)); // set value to true or false depending on dword value + } +} +``` ## `CMFCPropertyGridProperty::Show` @@ -1534,7 +1462,7 @@ void Show( ### Parameters *`bShow`*\ -[in] `TRUE` to display the current property and its sub-items; `FALSE` to hide the current property and its sub-items. The default value is `TRUE`. +[in] `TRUE` to display the current property and its subitems; `FALSE` to hide the current property and its subitems. The default value is `TRUE`. *`bAdjustLayout`*\ [in] `TRUE` to recalculate how to draw the label and value of a property and then draw the property; `FALSE` to use existing calculations to draw the property. The default value is `TRUE`. @@ -1543,4 +1471,4 @@ void Show( [Hierarchy Chart](../../mfc/hierarchy-chart.md)\ [Classes](../../mfc/reference/mfc-classes.md)\ -[`CMFCPropertyGridCtrl` Class](../../mfc/reference/cmfcpropertygridctrl-class.md) +[`CMFCPropertyGridCtrl` class](../../mfc/reference/cmfcpropertygridctrl-class.md) diff --git a/docs/mfc/reference/cmfcpropertygridtooltipctrl-class.md b/docs/mfc/reference/cmfcpropertygridtooltipctrl-class.md index 84ef4b26a9a..47484ecb7db 100644 --- a/docs/mfc/reference/cmfcpropertygridtooltipctrl-class.md +++ b/docs/mfc/reference/cmfcpropertygridtooltipctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCPropertyGridToolTipCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCPropertyGridToolTipCtrl", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl::CMFCPropertyGridToolTipCtrl", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl::Create", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl::Deactivate", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl::GetLastRect", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl::Hide", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl::SetTextMargin", "AFXPROPERTYGRIDTOOLTIPCTRL/CMFCPropertyGridToolTipCtrl::Track"] helpviewer_keywords: ["CMFCPropertyGridToolTipCtrl [MFC], CMFCPropertyGridToolTipCtrl", "CMFCPropertyGridToolTipCtrl [MFC], Create", "CMFCPropertyGridToolTipCtrl [MFC], Deactivate", "CMFCPropertyGridToolTipCtrl [MFC], GetLastRect", "CMFCPropertyGridToolTipCtrl [MFC], Hide", "CMFCPropertyGridToolTipCtrl [MFC], SetTextMargin", "CMFCPropertyGridToolTipCtrl [MFC], Track"] -ms.assetid: 84b436e5-6695-4da0-9569-1a875e087711 --- # CMFCPropertyGridToolTipCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a tooltip control that the [CMFCPropertyGridCtrl Class](../../mfc/reference/cmfcpropertygridctrl-class.md) uses to display tooltips. ## Syntax diff --git a/docs/mfc/reference/cmfcpropertypage-class.md b/docs/mfc/reference/cmfcpropertypage-class.md index a8448d4c043..7ad58c0a49a 100644 --- a/docs/mfc/reference/cmfcpropertypage-class.md +++ b/docs/mfc/reference/cmfcpropertypage-class.md @@ -4,10 +4,12 @@ title: "CMFCPropertyPage Class" ms.date: "11/04/2016" f1_keywords: ["CMFCPropertyPage", "AFXPROPERTYPAGE/CMFCPropertyPage", "AFXPROPERTYPAGE/CMFCPropertyPage::CMFCPropertyPage"] helpviewer_keywords: ["CMFCPropertyPage [MFC], CMFCPropertyPage"] -ms.assetid: d279d7f2-2d81-418d-9f23-6147d6e8df09 --- # CMFCPropertyPage Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCPropertyPage` class supports the display of pop-up menus on a property page. ## Syntax diff --git a/docs/mfc/reference/cmfcpropertysheet-class.md b/docs/mfc/reference/cmfcpropertysheet-class.md index b7f34be9f44..3526eeb6a54 100644 --- a/docs/mfc/reference/cmfcpropertysheet-class.md +++ b/docs/mfc/reference/cmfcpropertysheet-class.md @@ -4,10 +4,12 @@ title: "CMFCPropertySheet Class" ms.date: "11/19/2018" f1_keywords: ["CMFCPropertySheet", "AFXPROPERTYSHEET/CMFCPropertySheet", "AFXPROPERTYSHEET/CMFCPropertySheet::CMFCPropertySheet", "AFXPROPERTYSHEET/CMFCPropertySheet::AddPage", "AFXPROPERTYSHEET/CMFCPropertySheet::AddPageToTree", "AFXPROPERTYSHEET/CMFCPropertySheet::AddTreeCategory", "AFXPROPERTYSHEET/CMFCPropertySheet::EnablePageHeader", "AFXPROPERTYSHEET/CMFCPropertySheet::GetHeaderHeight", "AFXPROPERTYSHEET/CMFCPropertySheet::GetLook", "AFXPROPERTYSHEET/CMFCPropertySheet::GetNavBarWidth", "AFXPROPERTYSHEET/CMFCPropertySheet::GetTab", "AFXPROPERTYSHEET/CMFCPropertySheet::InitNavigationControl", "AFXPROPERTYSHEET/CMFCPropertySheet::OnActivatePage", "AFXPROPERTYSHEET/CMFCPropertySheet::OnDrawPageHeader", "AFXPROPERTYSHEET/CMFCPropertySheet::OnRemoveTreePage", "AFXPROPERTYSHEET/CMFCPropertySheet::RemoveCategory", "AFXPROPERTYSHEET/CMFCPropertySheet::RemovePage", "AFXPROPERTYSHEET/CMFCPropertySheet::SetIconsList", "AFXPROPERTYSHEET/CMFCPropertySheet::SetLook"] helpviewer_keywords: ["CMFCPropertySheet [MFC], CMFCPropertySheet", "CMFCPropertySheet [MFC], AddPage", "CMFCPropertySheet [MFC], AddPageToTree", "CMFCPropertySheet [MFC], AddTreeCategory", "CMFCPropertySheet [MFC], EnablePageHeader", "CMFCPropertySheet [MFC], GetHeaderHeight", "CMFCPropertySheet [MFC], GetLook", "CMFCPropertySheet [MFC], GetNavBarWidth", "CMFCPropertySheet [MFC], GetTab", "CMFCPropertySheet [MFC], InitNavigationControl", "CMFCPropertySheet [MFC], OnActivatePage", "CMFCPropertySheet [MFC], OnDrawPageHeader", "CMFCPropertySheet [MFC], OnRemoveTreePage", "CMFCPropertySheet [MFC], RemoveCategory", "CMFCPropertySheet [MFC], RemovePage", "CMFCPropertySheet [MFC], SetIconsList", "CMFCPropertySheet [MFC], SetLook"] -ms.assetid: 01d93573-9698-440f-a6a4-5bebbee879dc --- # CMFCPropertySheet Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCPropertySheet` class 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. ## Syntax diff --git a/docs/mfc/reference/cmfcrebar-class.md b/docs/mfc/reference/cmfcrebar-class.md index edf17e6c6ec..babf161b4c7 100644 --- a/docs/mfc/reference/cmfcrebar-class.md +++ b/docs/mfc/reference/cmfcrebar-class.md @@ -4,10 +4,12 @@ title: "CMFCReBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCReBar", "AFXREBAR/CMFCReBar", "AFXREBAR/CMFCReBar::AddBar", "AFXREBAR/CMFCReBar::CalcFixedLayout", "AFXREBAR/CMFCReBar::CanFloat", "AFXREBAR/CMFCReBar::Create", "AFXREBAR/CMFCReBar::EnableDocking", "AFXREBAR/CMFCReBar::GetReBarBandInfoSize", "AFXREBAR/CMFCReBar::GetReBarCtrl", "AFXREBAR/CMFCReBar::OnShowControlBarMenu", "AFXREBAR/CMFCReBar::OnToolHitTest", "AFXREBAR/CMFCReBar::OnUpdateCmdUI", "AFXREBAR/CMFCReBar::SetPaneAlignment"] helpviewer_keywords: ["CMFCReBar [MFC], AddBar", "CMFCReBar [MFC], CalcFixedLayout", "CMFCReBar [MFC], CanFloat", "CMFCReBar [MFC], Create", "CMFCReBar [MFC], EnableDocking", "CMFCReBar [MFC], GetReBarBandInfoSize", "CMFCReBar [MFC], GetReBarCtrl", "CMFCReBar [MFC], OnShowControlBarMenu", "CMFCReBar [MFC], OnToolHitTest", "CMFCReBar [MFC], OnUpdateCmdUI", "CMFCReBar [MFC], SetPaneAlignment"] -ms.assetid: 02a60e29-6224-49c1-9e74-e0a7d9f8d023 --- # CMFCReBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A `CMFCReBar` object is a control bar that provides layout, persistence, and state information for rebar controls. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -52,10 +54,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/cmfcribbonapplicationbutton-class.md b/docs/mfc/reference/cmfcribbonapplicationbutton-class.md index 5309f14c60f..50d4c58b4ff 100644 --- a/docs/mfc/reference/cmfcribbonapplicationbutton-class.md +++ b/docs/mfc/reference/cmfcribbonapplicationbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonApplicationButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonApplicationButton", "AFXRIBBONBAR/CMFCRibbonApplicationButton", "AFXRIBBONBAR/CMFCRibbonApplicationButton::CMFCRibbonApplicationButton", "AFXRIBBONBAR/CMFCRibbonApplicationButton::SetImage"] helpviewer_keywords: ["CMFCRibbonApplicationButton [MFC], CMFCRibbonApplicationButton", "CMFCRibbonApplicationButton [MFC], SetImage"] -ms.assetid: beb81757-fabd-4641-9130-876ba8505b78 --- # CMFCRibbonApplicationButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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**. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonbar-class.md b/docs/mfc/reference/cmfcribbonbar-class.md index 9b4b33d3846..0dc8d3faf6c 100644 --- a/docs/mfc/reference/cmfcribbonbar-class.md +++ b/docs/mfc/reference/cmfcribbonbar-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CMFCRibbonBar Class" title: "CMFCRibbonBar Class" +description: "Learn more about: CMFCRibbonBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonBar", "AFXRIBBONBAR/CMFCRibbonBar", "AFXRIBBONBAR/CMFCRibbonBar::ActivateContextCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddContextCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddMainCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddPrintPreviewCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddQATOnlyCategory", "AFXRIBBONBAR/CMFCRibbonBar::AddToTabs", "AFXRIBBONBAR/CMFCRibbonBar::CreateEx", "AFXRIBBONBAR/CMFCRibbonBar::Create", "AFXRIBBONBAR/CMFCRibbonBar::DeactivateKeyboardFocus", "AFXRIBBONBAR/CMFCRibbonBar::DrawMenuImage", "AFXRIBBONBAR/CMFCRibbonBar::DWMCompositionChanged", "AFXRIBBONBAR/CMFCRibbonBar::EnableKeyTips", "AFXRIBBONBAR/CMFCRibbonBar::EnablePrintPreview", "AFXRIBBONBAR/CMFCRibbonBar::EnableToolTips", "AFXRIBBONBAR/CMFCRibbonBar::FindByData", "AFXRIBBONBAR/CMFCRibbonBar::FindByID", "AFXRIBBONBAR/CMFCRibbonBar::FindCategoryIndexByData", "AFXRIBBONBAR/CMFCRibbonBar::ForceRecalcLayout", "AFXRIBBONBAR/CMFCRibbonBar::GetActiveCategory", "AFXRIBBONBAR/CMFCRibbonBar::GetCaptionHeight", "AFXRIBBONBAR/CMFCRibbonBar::GetCategory", "AFXRIBBONBAR/CMFCRibbonBar::GetCategoryCount", "AFXRIBBONBAR/CMFCRibbonBar::GetCategoryHeight", "AFXRIBBONBAR/CMFCRibbonBar::GetCategoryIndex", "AFXRIBBONBAR/CMFCRibbonBar::GetContextName", "AFXRIBBONBAR/CMFCRibbonBar::GetDroppedDown", "AFXRIBBONBAR/CMFCRibbonBar::GetElementsByID", "AFXRIBBONBAR/CMFCRibbonBar::GetApplicationButton", "AFXRIBBONBAR/CMFCRibbonBar::GetFocused", "AFXRIBBONBAR/CMFCRibbonBar::GetHideFlags", "AFXRIBBONBAR/CMFCRibbonBar::GetItemIDsList", "AFXRIBBONBAR/CMFCRibbonBar::GetKeyboardNavigationLevel", "AFXRIBBONBAR/CMFCRibbonBar::GetKeyboardNavLevelCurrent", "AFXRIBBONBAR/CMFCRibbonBar::GetKeyboardNavLevelParent", "AFXRIBBONBAR/CMFCRibbonBar::GetMainCategory", "AFXRIBBONBAR/CMFCRibbonBar::GetQATCommandsLocation", "AFXRIBBONBAR/CMFCRibbonBar::GetQATDroppedDown", "AFXRIBBONBAR/CMFCRibbonBar::GetQuickAccessCommands", "AFXRIBBONBAR/CMFCRibbonBar::GetQuickAccessToolbarLocation", "AFXRIBBONBAR/CMFCRibbonBar::GetTabTrancateRatio", "AFXRIBBONBAR/CMFCRibbonBar::GetTooltipFixedWidthLargeImage", "AFXRIBBONBAR/CMFCRibbonBar::GetTooltipFixedWidthRegular", "AFXRIBBONBAR/CMFCRibbonBar::GetVisibleCategoryCount", "AFXRIBBONBAR/CMFCRibbonBar::HideAllContextCategories", "AFXRIBBONBAR/CMFCRibbonBar::HideKeyTips", "AFXRIBBONBAR/CMFCRibbonBar::HitTest", "AFXRIBBONBAR/CMFCRibbonBar::IsKeyTipEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsMainRibbonBar", "AFXRIBBONBAR/CMFCRibbonBar::IsPrintPreviewEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsQATEmpty", "AFXRIBBONBAR/CMFCRibbonBar::IsQuickAccessToolbarOnTop", "AFXRIBBONBAR/CMFCRibbonBar::IsReplaceFrameCaption", "AFXRIBBONBAR/CMFCRibbonBar::IsShowGroupBorder", "AFXRIBBONBAR/CMFCRibbonBar::IsToolTipDescrEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsToolTipEnabled", "AFXRIBBONBAR/CMFCRibbonBar::IsTransparentCaption", "AFXRIBBONBAR/CMFCRibbonBar::IsWindows7Look", "AFXRIBBONBAR/CMFCRibbonBar::LoadFromResource", "AFXRIBBONBAR/CMFCRibbonBar::OnClickButton", "AFXRIBBONBAR/CMFCRibbonBar::OnEditContextMenu", "AFXRIBBONBAR/CMFCRibbonBar::OnRTLChanged", "AFXRIBBONBAR/CMFCRibbonBar::OnSetAccData", "AFXRIBBONBAR/CMFCRibbonBar::OnShowRibbonContextMenu", "AFXRIBBONBAR/CMFCRibbonBar::OnShowRibbonQATMenu", "AFXRIBBONBAR/CMFCRibbonBar::OnSysKeyDown", "AFXRIBBONBAR/CMFCRibbonBar::OnSysKeyUp", "AFXRIBBONBAR/CMFCRibbonBar::PopTooltip", "AFXRIBBONBAR/CMFCRibbonBar::PreTranslateMessage", "AFXRIBBONBAR/CMFCRibbonBar::RecalcLayout", "AFXRIBBONBAR/CMFCRibbonBar::RemoveAllCategories", "AFXRIBBONBAR/CMFCRibbonBar::RemoveAllFromTabs", "AFXRIBBONBAR/CMFCRibbonBar::RemoveCategory", "AFXRIBBONBAR/CMFCRibbonBar::SaveToXMLBuffer", "AFXRIBBONBAR/CMFCRibbonBar::SaveToXMLFile", "AFXRIBBONBAR/CMFCRibbonBar::SetActiveCategory", "AFXRIBBONBAR/CMFCRibbonBar::SetActiveMDIChild", "AFXRIBBONBAR/CMFCRibbonBar::SetElementKeys", "AFXRIBBONBAR/CMFCRibbonBar::SetApplicationButton", "AFXRIBBONBAR/CMFCRibbonBar::SetKeyboardNavigationLevel", "AFXRIBBONBAR/CMFCRibbonBar::SetMaximizeMode", "AFXRIBBONBAR/CMFCRibbonBar::SetQuickAccessCommands", "AFXRIBBONBAR/CMFCRibbonBar::SetQuickAccessDefaultState", "AFXRIBBONBAR/CMFCRibbonBar::SetQuickAccessToolbarOnTop", "AFXRIBBONBAR/CMFCRibbonBar::SetTooltipFixedWidth", "AFXRIBBONBAR/CMFCRibbonBar::SetWindows7Look", "AFXRIBBONBAR/CMFCRibbonBar::ShowCategory", "AFXRIBBONBAR/CMFCRibbonBar::ShowContextCategories", "AFXRIBBONBAR/CMFCRibbonBar::ShowKeyTips", "AFXRIBBONBAR/CMFCRibbonBar::ToggleMimimizeState", "AFXRIBBONBAR/CMFCRibbonBar::TranslateChar"] helpviewer_keywords: ["CMFCRibbonBar [MFC], ActivateContextCategory", "CMFCRibbonBar [MFC], AddCategory", "CMFCRibbonBar [MFC], AddContextCategory", "CMFCRibbonBar [MFC], AddMainCategory", "CMFCRibbonBar [MFC], AddPrintPreviewCategory", "CMFCRibbonBar [MFC], AddQATOnlyCategory", "CMFCRibbonBar [MFC], AddToTabs", "CMFCRibbonBar [MFC], CreateEx", "CMFCRibbonBar [MFC], Create", "CMFCRibbonBar [MFC], DeactivateKeyboardFocus", "CMFCRibbonBar [MFC], DrawMenuImage", "CMFCRibbonBar [MFC], DWMCompositionChanged", "CMFCRibbonBar [MFC], EnableKeyTips", "CMFCRibbonBar [MFC], EnablePrintPreview", "CMFCRibbonBar [MFC], EnableToolTips", "CMFCRibbonBar [MFC], FindByData", "CMFCRibbonBar [MFC], FindByID", "CMFCRibbonBar [MFC], FindCategoryIndexByData", "CMFCRibbonBar [MFC], ForceRecalcLayout", "CMFCRibbonBar [MFC], GetActiveCategory", "CMFCRibbonBar [MFC], GetCaptionHeight", "CMFCRibbonBar [MFC], GetCategory", "CMFCRibbonBar [MFC], GetCategoryCount", "CMFCRibbonBar [MFC], GetCategoryHeight", "CMFCRibbonBar [MFC], GetCategoryIndex", "CMFCRibbonBar [MFC], GetContextName", "CMFCRibbonBar [MFC], GetDroppedDown", "CMFCRibbonBar [MFC], GetElementsByID", "CMFCRibbonBar [MFC], GetApplicationButton", "CMFCRibbonBar [MFC], GetFocused", "CMFCRibbonBar [MFC], GetHideFlags", "CMFCRibbonBar [MFC], GetItemIDsList", "CMFCRibbonBar [MFC], GetKeyboardNavigationLevel", "CMFCRibbonBar [MFC], GetKeyboardNavLevelCurrent", "CMFCRibbonBar [MFC], GetKeyboardNavLevelParent", "CMFCRibbonBar [MFC], GetMainCategory", "CMFCRibbonBar [MFC], GetQATCommandsLocation", "CMFCRibbonBar [MFC], GetQATDroppedDown", "CMFCRibbonBar [MFC], GetQuickAccessCommands", "CMFCRibbonBar [MFC], GetQuickAccessToolbarLocation", "CMFCRibbonBar [MFC], GetTabTrancateRatio", "CMFCRibbonBar [MFC], GetTooltipFixedWidthLargeImage", "CMFCRibbonBar [MFC], GetTooltipFixedWidthRegular", "CMFCRibbonBar [MFC], GetVisibleCategoryCount", "CMFCRibbonBar [MFC], HideAllContextCategories", "CMFCRibbonBar [MFC], HideKeyTips", "CMFCRibbonBar [MFC], HitTest", "CMFCRibbonBar [MFC], IsKeyTipEnabled", "CMFCRibbonBar [MFC], IsMainRibbonBar", "CMFCRibbonBar [MFC], IsPrintPreviewEnabled", "CMFCRibbonBar [MFC], IsQATEmpty", "CMFCRibbonBar [MFC], IsQuickAccessToolbarOnTop", "CMFCRibbonBar [MFC], IsReplaceFrameCaption", "CMFCRibbonBar [MFC], IsShowGroupBorder", "CMFCRibbonBar [MFC], IsToolTipDescrEnabled", "CMFCRibbonBar [MFC], IsToolTipEnabled", "CMFCRibbonBar [MFC], IsTransparentCaption", "CMFCRibbonBar [MFC], IsWindows7Look", "CMFCRibbonBar [MFC], LoadFromResource", "CMFCRibbonBar [MFC], OnClickButton", "CMFCRibbonBar [MFC], OnEditContextMenu", "CMFCRibbonBar [MFC], OnRTLChanged", "CMFCRibbonBar [MFC], OnSetAccData", "CMFCRibbonBar [MFC], OnShowRibbonContextMenu", "CMFCRibbonBar [MFC], OnShowRibbonQATMenu", "CMFCRibbonBar [MFC], OnSysKeyDown", "CMFCRibbonBar [MFC], OnSysKeyUp", "CMFCRibbonBar [MFC], PopTooltip", "CMFCRibbonBar [MFC], PreTranslateMessage", "CMFCRibbonBar [MFC], RecalcLayout", "CMFCRibbonBar [MFC], RemoveAllCategories", "CMFCRibbonBar [MFC], RemoveAllFromTabs", "CMFCRibbonBar [MFC], RemoveCategory", "CMFCRibbonBar [MFC], SaveToXMLBuffer", "CMFCRibbonBar [MFC], SaveToXMLFile", "CMFCRibbonBar [MFC], SetActiveCategory", "CMFCRibbonBar [MFC], SetActiveMDIChild", "CMFCRibbonBar [MFC], SetElementKeys", "CMFCRibbonBar [MFC], SetApplicationButton", "CMFCRibbonBar [MFC], SetKeyboardNavigationLevel", "CMFCRibbonBar [MFC], SetMaximizeMode", "CMFCRibbonBar [MFC], SetQuickAccessCommands", "CMFCRibbonBar [MFC], SetQuickAccessDefaultState", "CMFCRibbonBar [MFC], SetQuickAccessToolbarOnTop", "CMFCRibbonBar [MFC], SetTooltipFixedWidth", "CMFCRibbonBar [MFC], SetWindows7Look", "CMFCRibbonBar [MFC], ShowCategory", "CMFCRibbonBar [MFC], ShowContextCategories", "CMFCRibbonBar [MFC], ShowKeyTips", "CMFCRibbonBar [MFC], ToggleMimimizeState", "CMFCRibbonBar [MFC], TranslateChar"] -ms.assetid: a65d06fa-1a28-4cc0-8971-bc9d7c9198fe --- # `CMFCRibbonBar` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonBar` class implements a ribbon bar similar to that used in Office 2007. For more detail, see the source code located in the `mfc` folder of your Visual Studio installation. For example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. @@ -119,7 +121,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 @@ -271,7 +273,7 @@ CMFCRibbonCategory* AddContextCategory( ### Return Value -A pointer to the newly created category, or `NULL` if the `CreateObject` method of *`pRTI`* can’t create the specified category. +A pointer to the newly created category, or `NULL` if the `CreateObject` method of *`pRTI`* can't create the specified category. ### Remarks @@ -698,7 +700,7 @@ A pointer to the active ribbon category; or `NULL` if no category is active. A category is active if it has the focus. By default, the active category is the first category on the left side of the ribbon bar. -The main category is displayed when the user presses the application button and it can’t be the active category. +The main category is displayed when the user presses the application button and it can't be the active category. ## `CMFCRibbonBar::GetApplicationButton` @@ -1305,7 +1307,7 @@ virtual void OnEditContextMenu( ### Parameters [in] *`pEdit`*\ -[in] *`point`*\ +[in] *`point`* ### Remarks @@ -1360,7 +1362,7 @@ virtual BOOL OnShowRibbonContextMenu( [in] *`pWnd`*\ [in] *`x`*\ [in] *`y`*\ -[in] *`pHit`*\ +[in] *`pHit`* ### Return Value @@ -1381,7 +1383,7 @@ virtual BOOL OnShowRibbonQATMenu( [in] *`pWnd`*\ [in] *`x`*\ [in] *`y`*\ -[in] *`pHit`*\ +[in] *`pHit`* ### Return Value @@ -1553,9 +1555,9 @@ BOOL SetActiveCategory( ### Remarks -The main ribbon category can’t be the active category. +The main ribbon category can't be the active category. -If the category specified by *`pCategory`* isn't displayed, it can’t be set as the active category. +If the category specified by *`pCategory`* isn't displayed, it can't be set as the active category. ## `CMFCRibbonBar::SetActiveMDIChild` diff --git a/docs/mfc/reference/cmfcribbonbaseelement-class.md b/docs/mfc/reference/cmfcribbonbaseelement-class.md index 27c7ee698a3..d67fb97cd16 100644 --- a/docs/mfc/reference/cmfcribbonbaseelement-class.md +++ b/docs/mfc/reference/cmfcribbonbaseelement-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonBaseElement` class is the base class for all elements that you can add to a [ribbon bar](../../mfc/reference/cmfcribbonbar-class.md). Examples of ribbon elements are ribbon buttons, ribbon check boxes, and ribbon combo boxes. ## Syntax @@ -131,7 +133,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 +2044,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/cmfcribbonbutton-class.md b/docs/mfc/reference/cmfcribbonbutton-class.md index 38845bda11c..fec84f00b6a 100644 --- a/docs/mfc/reference/cmfcribbonbutton-class.md +++ b/docs/mfc/reference/cmfcribbonbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonButton", "AFXRIBBONBUTTON/CMFCRibbonButton", "AFXRIBBONBUTTON/CMFCRibbonButton::CMFCRibbonButton", "AFXRIBBONBUTTON/CMFCRibbonButton::AddSubItem", "AFXRIBBONBUTTON/CMFCRibbonButton::CanBeStretched", "AFXRIBBONBUTTON/CMFCRibbonButton::CleanUpSizes", "AFXRIBBONBUTTON/CMFCRibbonButton::ClosePopupMenu", "AFXRIBBONBUTTON/CMFCRibbonButton::DrawBottomText", "AFXRIBBONBUTTON/CMFCRibbonButton::DrawImage", "AFXRIBBONBUTTON/CMFCRibbonButton::DrawRibbonText", "AFXRIBBONBUTTON/CMFCRibbonButton::FindSubItemIndexByID", "AFXRIBBONBUTTON/CMFCRibbonButton::GetCommandRect", "AFXRIBBONBUTTON/CMFCRibbonButton::GetCompactSize", "AFXRIBBONBUTTON/CMFCRibbonButton::GetIcon", "AFXRIBBONBUTTON/CMFCRibbonButton::GetImageIndex", "AFXRIBBONBUTTON/CMFCRibbonButton::GetImageSize", "AFXRIBBONBUTTON/CMFCRibbonButton::GetIntermediateSize", "AFXRIBBONBUTTON/CMFCRibbonButton::GetMenu", "AFXRIBBONBUTTON/CMFCRibbonButton::GetMenuRect", "AFXRIBBONBUTTON/CMFCRibbonButton::GetRegularSize", "AFXRIBBONBUTTON/CMFCRibbonButton::GetSubItems", "AFXRIBBONBUTTON/CMFCRibbonButton::GetTextRowHeight", "AFXRIBBONBUTTON/CMFCRibbonButton::GetToolTipText", "AFXRIBBONBUTTON/CMFCRibbonButton::HasCompactMode", "AFXRIBBONBUTTON/CMFCRibbonButton::HasIntermediateMode", "AFXRIBBONBUTTON/CMFCRibbonButton::HasLargeMode", "AFXRIBBONBUTTON/CMFCRibbonButton::HasMenu", "AFXRIBBONBUTTON/CMFCRibbonButton::IsAlwaysDrawBorder", "AFXRIBBONBUTTON/CMFCRibbonButton::IsAlwaysLargeImage", "AFXRIBBONBUTTON/CMFCRibbonButton::IsApplicationButton", "AFXRIBBONBUTTON/CMFCRibbonButton::IsCommandAreaHighlighted", "AFXRIBBONBUTTON/CMFCRibbonButton::IsDefaultCommand", "AFXRIBBONBUTTON/CMFCRibbonButton::IsDefaultPanelButton", "AFXRIBBONBUTTON/CMFCRibbonButton::IsDrawTooltipImage", "AFXRIBBONBUTTON/CMFCRibbonButton::IsLargeImage", "AFXRIBBONBUTTON/CMFCRibbonButton::IsMenuAreaHighlighted", "AFXRIBBONBUTTON/CMFCRibbonButton::IsMenuOnBottom", "AFXRIBBONBUTTON/CMFCRibbonButton::IsPopupDefaultMenuLook", "AFXRIBBONBUTTON/CMFCRibbonButton::IsRightAlignMenu", "AFXRIBBONBUTTON/CMFCRibbonButton::IsSingleLineText", "AFXRIBBONBUTTON/CMFCRibbonButton::OnCalcTextSize", "AFXRIBBONBUTTON/CMFCRibbonButton::OnDrawBorder", "AFXRIBBONBUTTON/CMFCRibbonButton::OnDraw", "AFXRIBBONBUTTON/CMFCRibbonButton::OnFillBackground", "AFXRIBBONBUTTON/CMFCRibbonButton::RemoveAllSubItems", "AFXRIBBONBUTTON/CMFCRibbonButton::RemoveSubItem", "AFXRIBBONBUTTON/CMFCRibbonButton::SetACCData", "AFXRIBBONBUTTON/CMFCRibbonButton::SetAlwaysLargeImage", "AFXRIBBONBUTTON/CMFCRibbonButton::SetDefaultCommand", "AFXRIBBONBUTTON/CMFCRibbonButton::SetDescription", "AFXRIBBONBUTTON/CMFCRibbonButton::SetImageIndex", "AFXRIBBONBUTTON/CMFCRibbonButton::SetMenu", "AFXRIBBONBUTTON/CMFCRibbonButton::SetParentCategory", "AFXRIBBONBUTTON/CMFCRibbonButton::SetRightAlignMenu", "AFXRIBBONBUTTON/CMFCRibbonButton::SetText", "AFXRIBBONBUTTON/CMFCRibbonButton::OnClick"] helpviewer_keywords: ["CMFCRibbonButton [MFC], CMFCRibbonButton", "CMFCRibbonButton [MFC], AddSubItem", "CMFCRibbonButton [MFC], CanBeStretched", "CMFCRibbonButton [MFC], CleanUpSizes", "CMFCRibbonButton [MFC], ClosePopupMenu", "CMFCRibbonButton [MFC], DrawBottomText", "CMFCRibbonButton [MFC], DrawImage", "CMFCRibbonButton [MFC], DrawRibbonText", "CMFCRibbonButton [MFC], FindSubItemIndexByID", "CMFCRibbonButton [MFC], GetCommandRect", "CMFCRibbonButton [MFC], GetCompactSize", "CMFCRibbonButton [MFC], GetIcon", "CMFCRibbonButton [MFC], GetImageIndex", "CMFCRibbonButton [MFC], GetImageSize", "CMFCRibbonButton [MFC], GetIntermediateSize", "CMFCRibbonButton [MFC], GetMenu", "CMFCRibbonButton [MFC], GetMenuRect", "CMFCRibbonButton [MFC], GetRegularSize", "CMFCRibbonButton [MFC], GetSubItems", "CMFCRibbonButton [MFC], GetTextRowHeight", "CMFCRibbonButton [MFC], GetToolTipText", "CMFCRibbonButton [MFC], HasCompactMode", "CMFCRibbonButton [MFC], HasIntermediateMode", "CMFCRibbonButton [MFC], HasLargeMode", "CMFCRibbonButton [MFC], HasMenu", "CMFCRibbonButton [MFC], IsAlwaysDrawBorder", "CMFCRibbonButton [MFC], IsAlwaysLargeImage", "CMFCRibbonButton [MFC], IsApplicationButton", "CMFCRibbonButton [MFC], IsCommandAreaHighlighted", "CMFCRibbonButton [MFC], IsDefaultCommand", "CMFCRibbonButton [MFC], IsDefaultPanelButton", "CMFCRibbonButton [MFC], IsDrawTooltipImage", "CMFCRibbonButton [MFC], IsLargeImage", "CMFCRibbonButton [MFC], IsMenuAreaHighlighted", "CMFCRibbonButton [MFC], IsMenuOnBottom", "CMFCRibbonButton [MFC], IsPopupDefaultMenuLook", "CMFCRibbonButton [MFC], IsRightAlignMenu", "CMFCRibbonButton [MFC], IsSingleLineText", "CMFCRibbonButton [MFC], OnCalcTextSize", "CMFCRibbonButton [MFC], OnDrawBorder", "CMFCRibbonButton [MFC], OnDraw", "CMFCRibbonButton [MFC], OnFillBackground", "CMFCRibbonButton [MFC], RemoveAllSubItems", "CMFCRibbonButton [MFC], RemoveSubItem", "CMFCRibbonButton [MFC], SetACCData", "CMFCRibbonButton [MFC], SetAlwaysLargeImage", "CMFCRibbonButton [MFC], SetDefaultCommand", "CMFCRibbonButton [MFC], SetDescription", "CMFCRibbonButton [MFC], SetImageIndex", "CMFCRibbonButton [MFC], SetMenu", "CMFCRibbonButton [MFC], SetParentCategory", "CMFCRibbonButton [MFC], SetRightAlignMenu", "CMFCRibbonButton [MFC], SetText", "CMFCRibbonButton [MFC], OnClick"] -ms.assetid: 732e941c-9504-4b83-a691-d18075965d53 --- # CMFCRibbonButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonButton` class implements buttons that you can position on ribbon bar elements such as panels, Quick Access Toolbars, and pop-up menus. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcribbonbuttonsgroup-class.md b/docs/mfc/reference/cmfcribbonbuttonsgroup-class.md index 943d046aca0..969db73abad 100644 --- a/docs/mfc/reference/cmfcribbonbuttonsgroup-class.md +++ b/docs/mfc/reference/cmfcribbonbuttonsgroup-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonButtonsGroup Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonButtonsGroup", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::CMFCRibbonButtonsGroup", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::AddButton", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::AddButtons", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::GetButton", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::GetCount", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::GetImageSize", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::GetRegularSize", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::HasImages", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::OnDrawImage", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::RemoveAll", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::SetImages", "AFXRIBBONBUTTONSGROUP/CMFCRibbonButtonsGroup::SetParentCategory"] helpviewer_keywords: ["CMFCRibbonButtonsGroup [MFC], CMFCRibbonButtonsGroup", "CMFCRibbonButtonsGroup [MFC], AddButton", "CMFCRibbonButtonsGroup [MFC], AddButtons", "CMFCRibbonButtonsGroup [MFC], GetButton", "CMFCRibbonButtonsGroup [MFC], GetCount", "CMFCRibbonButtonsGroup [MFC], GetImageSize", "CMFCRibbonButtonsGroup [MFC], GetRegularSize", "CMFCRibbonButtonsGroup [MFC], HasImages", "CMFCRibbonButtonsGroup [MFC], OnDrawImage", "CMFCRibbonButtonsGroup [MFC], RemoveAll", "CMFCRibbonButtonsGroup [MFC], SetImages", "CMFCRibbonButtonsGroup [MFC], SetParentCategory"] -ms.assetid: b993d93e-fc1a-472f-a87f-1d7b7b499845 --- # CMFCRibbonButtonsGroup Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonButtonsGroup` class allows you to 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. ## Syntax diff --git a/docs/mfc/reference/cmfcribboncategory-class.md b/docs/mfc/reference/cmfcribboncategory-class.md index 242d0f8fb99..4cfdf0d8b3e 100644 --- a/docs/mfc/reference/cmfcribboncategory-class.md +++ b/docs/mfc/reference/cmfcribboncategory-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CMFCRibbonCategory Class" title: "CMFCRibbonCategory Class" -ms.date: "11/19/2018" +description: "Learn more about: CMFCRibbonCategory Class" +ms.date: 11/19/2018 f1_keywords: ["CMFCRibbonCategory", "AFXRIBBONCATEGORY/CMFCRibbonCategory", "AFXRIBBONCATEGORY/CMFCRibbonCategory::CMFCRibbonCategory", "AFXRIBBONCATEGORY/CMFCRibbonCategory::AddHidden", "AFXRIBBONCATEGORY/CMFCRibbonCategory::AddPanel", "AFXRIBBONCATEGORY/CMFCRibbonCategory::CopyFrom", "AFXRIBBONCATEGORY/CMFCRibbonCategory::FindByData", "AFXRIBBONCATEGORY/CMFCRibbonCategory::FindByID", "AFXRIBBONCATEGORY/CMFCRibbonCategory::FindPanelWithElem", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetContextID", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetData", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetDroppedDown", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetElements", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetElementsByID", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetFirstVisibleElement", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetFocused", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetHighlighted", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetImageCount", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetImageSize", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetItemIDsList", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetLastVisibleElement", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetLargeImages", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetMaxHeight", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetName", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetPanel", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetPanelCount", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetPanelFromPoint", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetPanelIndex", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetParentButton", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetParentMenuBar", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetParentRibbonBar", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetRect", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetSmallImages", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetTabColor", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetTabRect", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetTextTopLine", "AFXRIBBONCATEGORY/CMFCRibbonCategory::GetVisibleElements", "AFXRIBBONCATEGORY/CMFCRibbonCategory::HighlightPanel", "AFXRIBBONCATEGORY/CMFCRibbonCategory::HitTest", "AFXRIBBONCATEGORY/CMFCRibbonCategory::HitTestEx", "AFXRIBBONCATEGORY/CMFCRibbonCategory::HitTestScrollButtons", "AFXRIBBONCATEGORY/CMFCRibbonCategory::IsActive", "AFXRIBBONCATEGORY/CMFCRibbonCategory::IsVisible", "AFXRIBBONCATEGORY/CMFCRibbonCategory::IsWindows7Look", "AFXRIBBONCATEGORY/CMFCRibbonCategory::NotifyControlCommand", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnCancelMode", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnDraw", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnDrawImage", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnDrawMenuBorder", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnKey", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnLButtonDown", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnLButtonUp", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnMouseMove", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnRTLChanged", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnScrollHorz", "AFXRIBBONCATEGORY/CMFCRibbonCategory::OnUpdateCmdUI", "AFXRIBBONCATEGORY/CMFCRibbonCategory::RecalcLayout", "AFXRIBBONCATEGORY/CMFCRibbonCategory::RemovePanel", "AFXRIBBONCATEGORY/CMFCRibbonCategory::ReposPanels", "AFXRIBBONCATEGORY/CMFCRibbonCategory::SetCollapseOrder", "AFXRIBBONCATEGORY/CMFCRibbonCategory::SetData", "AFXRIBBONCATEGORY/CMFCRibbonCategory::SetKeys", "AFXRIBBONCATEGORY/CMFCRibbonCategory::SetName", "AFXRIBBONCATEGORY/CMFCRibbonCategory::SetTabColor"] helpviewer_keywords: ["CMFCRibbonCategory [MFC], CMFCRibbonCategory", "CMFCRibbonCategory [MFC], AddHidden", "CMFCRibbonCategory [MFC], AddPanel", "CMFCRibbonCategory [MFC], CopyFrom", "CMFCRibbonCategory [MFC], FindByData", "CMFCRibbonCategory [MFC], FindByID", "CMFCRibbonCategory [MFC], FindPanelWithElem", "CMFCRibbonCategory [MFC], GetContextID", "CMFCRibbonCategory [MFC], GetData", "CMFCRibbonCategory [MFC], GetDroppedDown", "CMFCRibbonCategory [MFC], GetElements", "CMFCRibbonCategory [MFC], GetElementsByID", "CMFCRibbonCategory [MFC], GetFirstVisibleElement", "CMFCRibbonCategory [MFC], GetFocused", "CMFCRibbonCategory [MFC], GetHighlighted", "CMFCRibbonCategory [MFC], GetImageCount", "CMFCRibbonCategory [MFC], GetImageSize", "CMFCRibbonCategory [MFC], GetItemIDsList", "CMFCRibbonCategory [MFC], GetLastVisibleElement", "CMFCRibbonCategory [MFC], GetLargeImages", "CMFCRibbonCategory [MFC], GetMaxHeight", "CMFCRibbonCategory [MFC], GetName", "CMFCRibbonCategory [MFC], GetPanel", "CMFCRibbonCategory [MFC], GetPanelCount", "CMFCRibbonCategory [MFC], GetPanelFromPoint", "CMFCRibbonCategory [MFC], GetPanelIndex", "CMFCRibbonCategory [MFC], GetParentButton", "CMFCRibbonCategory [MFC], GetParentMenuBar", "CMFCRibbonCategory [MFC], GetParentRibbonBar", "CMFCRibbonCategory [MFC], GetRect", "CMFCRibbonCategory [MFC], GetSmallImages", "CMFCRibbonCategory [MFC], GetTabColor", "CMFCRibbonCategory [MFC], GetTabRect", "CMFCRibbonCategory [MFC], GetTextTopLine", "CMFCRibbonCategory [MFC], GetVisibleElements", "CMFCRibbonCategory [MFC], HighlightPanel", "CMFCRibbonCategory [MFC], HitTest", "CMFCRibbonCategory [MFC], HitTestEx", "CMFCRibbonCategory [MFC], HitTestScrollButtons", "CMFCRibbonCategory [MFC], IsActive", "CMFCRibbonCategory [MFC], IsVisible", "CMFCRibbonCategory [MFC], IsWindows7Look", "CMFCRibbonCategory [MFC], NotifyControlCommand", "CMFCRibbonCategory [MFC], OnCancelMode", "CMFCRibbonCategory [MFC], OnDraw", "CMFCRibbonCategory [MFC], OnDrawImage", "CMFCRibbonCategory [MFC], OnDrawMenuBorder", "CMFCRibbonCategory [MFC], OnKey", "CMFCRibbonCategory [MFC], OnLButtonDown", "CMFCRibbonCategory [MFC], OnLButtonUp", "CMFCRibbonCategory [MFC], OnMouseMove", "CMFCRibbonCategory [MFC], OnRTLChanged", "CMFCRibbonCategory [MFC], OnScrollHorz", "CMFCRibbonCategory [MFC], OnUpdateCmdUI", "CMFCRibbonCategory [MFC], RecalcLayout", "CMFCRibbonCategory [MFC], RemovePanel", "CMFCRibbonCategory [MFC], ReposPanels", "CMFCRibbonCategory [MFC], SetCollapseOrder", "CMFCRibbonCategory [MFC], SetData", "CMFCRibbonCategory [MFC], SetKeys", "CMFCRibbonCategory [MFC], SetName", "CMFCRibbonCategory [MFC], SetTabColor"] -ms.assetid: 99ba25b6-d060-4fdd-bfab-3c46c22981bb --- # CMFCRibbonCategory Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonCategory` class implements a ribbon tab that contains a group of [ribbon panels](../../mfc/reference/cmfcribbonpanel-class.md). ## Syntax @@ -99,7 +101,7 @@ The `CMFCRibbonTab` class draws ribbon categories. It is derived from [CMFCRibbo This following example demonstrates how to create a ribbon category and add a panel to it. ```cpp -// Create a new ribbon category and get a pointer to it` +// Create a new ribbon category and get a pointer to it CMFCRibbonCategory* pCategory = m_wndRibbonBar.AddCategory (_T("&Write"), // Category name IDB_WRITE, // Category small images (16 x 16) @@ -838,7 +840,7 @@ Only ribbon elements that are contained in the ribbon category are tested. ## CMFCRibbonCategory::HitTestScrollButtons -If a point falls within a ribbon category’s left or right scroll button, returns a pointer to that button. +If a point falls within a ribbon category's left or right scroll button, returns a pointer to that button. ``` CMFCRibbonBaseElement* HitTestScrollButtons(CPoint point) const; diff --git a/docs/mfc/reference/cmfcribboncheckbox-class.md b/docs/mfc/reference/cmfcribboncheckbox-class.md index 57ce564c554..33cb715bbba 100644 --- a/docs/mfc/reference/cmfcribboncheckbox-class.md +++ b/docs/mfc/reference/cmfcribboncheckbox-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonCheckBox` class implements a check box that you can add to a ribbon panel, Quick Access Toolbar, or popup menu. ## Syntax @@ -131,7 +133,7 @@ A `CSize` object containing the intermediate size of the check box. ### Remarks -If not overridden, calculates the intermediate size as the default check box size ( `AFX_CHECK_BOX_DEFAULT_SIZE`) plus the text size, plus margins. +If not overridden, calculates the intermediate size as the default check box size (`AFX_CHECK_BOX_DEFAULT_SIZE`) plus the text size, plus margins. ## CMFCRibbonCheckBox::GetRegularSize diff --git a/docs/mfc/reference/cmfcribboncolorbutton-class.md b/docs/mfc/reference/cmfcribboncolorbutton-class.md index 3ad6148fb52..a450dd22d7e 100644 --- a/docs/mfc/reference/cmfcribboncolorbutton-class.md +++ b/docs/mfc/reference/cmfcribboncolorbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonColorButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonColorButton", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::CMFCRibbonColorButton", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::AddColorsGroup", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::EnableAutomaticButton", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::EnableOtherButton", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::GetAutomaticColor", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::GetColor", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::GetColorBoxSize", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::GetColumns", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::GetHighlightedColor", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::RemoveAllColorGroups", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::SetColor", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::SetColorBoxSize", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::SetColorName", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::SetColumns", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::SetDocumentColors", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::SetPalette", "AFXRIBBONCOLORBUTTON/CMFCRibbonColorButton::UpdateColor"] helpviewer_keywords: ["CMFCRibbonColorButton [MFC], CMFCRibbonColorButton", "CMFCRibbonColorButton [MFC], AddColorsGroup", "CMFCRibbonColorButton [MFC], EnableAutomaticButton", "CMFCRibbonColorButton [MFC], EnableOtherButton", "CMFCRibbonColorButton [MFC], GetAutomaticColor", "CMFCRibbonColorButton [MFC], GetColor", "CMFCRibbonColorButton [MFC], GetColorBoxSize", "CMFCRibbonColorButton [MFC], GetColumns", "CMFCRibbonColorButton [MFC], GetHighlightedColor", "CMFCRibbonColorButton [MFC], RemoveAllColorGroups", "CMFCRibbonColorButton [MFC], SetColor", "CMFCRibbonColorButton [MFC], SetColorBoxSize", "CMFCRibbonColorButton [MFC], SetColorName", "CMFCRibbonColorButton [MFC], SetColumns", "CMFCRibbonColorButton [MFC], SetDocumentColors", "CMFCRibbonColorButton [MFC], SetPalette", "CMFCRibbonColorButton [MFC], UpdateColor"] -ms.assetid: 6b4b4ee3-8cc0-41b4-a4eb-93e8847008e1 --- # CMFCRibbonColorButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonColorButton` class 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. ## Syntax @@ -241,7 +243,7 @@ The size of the color buttons in the drop-down color palette. ## CMFCRibbonColorButton::GetColumns -Gets the number of items in a row of the ribbon color button’s gallery display. +Gets the number of items in a row of the ribbon color button's gallery display. ``` int GetColumns() const; diff --git a/docs/mfc/reference/cmfcribboncombobox-class.md b/docs/mfc/reference/cmfcribboncombobox-class.md index 91d6fe19fa7..39b79bd3263 100644 --- a/docs/mfc/reference/cmfcribboncombobox-class.md +++ b/docs/mfc/reference/cmfcribboncombobox-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CMFCRibbonComboBox Class" title: "CMFCRibbonComboBox Class" -ms.date: "11/04/2016" +description: "Learn more about: CMFCRibbonComboBox Class" +ms.date: 11/04/2016 f1_keywords: ["CMFCRibbonComboBox", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::CMFCRibbonComboBox", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::AddItem", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::DeleteItem", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::EnableDropDownListResize", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::FindItem", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::GetCount", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::GetCurSel", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::GetDropDownHeight", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::GetIntermediateSize", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::GetItem", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::GetItemData", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::HasEditBox", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::IsResizeDropDownList", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::OnSelectItem", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::RemoveAllItems", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::SelectItem", "AFXRIBBONCOMBOBOX/CMFCRibbonComboBox::SetDropDownHeight"] helpviewer_keywords: ["CMFCRibbonComboBox [MFC], CMFCRibbonComboBox", "CMFCRibbonComboBox [MFC], AddItem", "CMFCRibbonComboBox [MFC], DeleteItem", "CMFCRibbonComboBox [MFC], EnableDropDownListResize", "CMFCRibbonComboBox [MFC], FindItem", "CMFCRibbonComboBox [MFC], GetCount", "CMFCRibbonComboBox [MFC], GetCurSel", "CMFCRibbonComboBox [MFC], GetDropDownHeight", "CMFCRibbonComboBox [MFC], GetIntermediateSize", "CMFCRibbonComboBox [MFC], GetItem", "CMFCRibbonComboBox [MFC], GetItemData", "CMFCRibbonComboBox [MFC], HasEditBox", "CMFCRibbonComboBox [MFC], IsResizeDropDownList", "CMFCRibbonComboBox [MFC], OnSelectItem", "CMFCRibbonComboBox [MFC], RemoveAllItems", "CMFCRibbonComboBox [MFC], SelectItem", "CMFCRibbonComboBox [MFC], SetDropDownHeight"] -ms.assetid: 9b29a6a4-cf17-4152-9b13-0bf90784b30d --- # CMFCRibbonComboBox Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonComboBox` class implements a combo box control that you can add to a ribbon bar, a ribbon panel, or a ribbon popup menu. ## Syntax @@ -102,9 +104,9 @@ public: CMFCRibbonComboBox( UINT nID, BOOL bHasEditBox=TRUE, - Int nWidth=-1, + int nWidth=-1, LPCTSTR lpszLabel=NULL, - Int nImage=-1); + int nImage=-1); protected: CMFCRibbonComboBox(); diff --git a/docs/mfc/reference/cmfcribboncontextcaption-class.md b/docs/mfc/reference/cmfcribboncontextcaption-class.md index 0cbbbcd3aaf..a066c0981fd 100644 --- a/docs/mfc/reference/cmfcribboncontextcaption-class.md +++ b/docs/mfc/reference/cmfcribboncontextcaption-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonContextCaption Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonContextCaption", "AFXRIBBONBAR/CMFCRibbonContextCaption", "AFXRIBBONBAR/CMFCRibbonContextCaption::GetColor", "AFXRIBBONBAR/CMFCRibbonContextCaption::GetRightTabX"] helpviewer_keywords: ["CMFCRibbonContextCaption [MFC], GetColor", "CMFCRibbonContextCaption [MFC], GetRightTabX"] -ms.assetid: cce2c0a2-8370-4266-997e-f8d0eeb3d616 --- # CMFCRibbonContextCaption Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a colored caption that appears at the top of a ribbon category or a context category. ## Syntax @@ -81,7 +83,7 @@ The color of the caption can be set by calling [CMFCRibbonCategory::SetTabColor] ## CMFCRibbonContextCaption::GetRightTabX -Retrieves the position of the right-hand edge of the category’s ribbon tab. +Retrieves the position of the right-hand edge of the category's ribbon tab. ``` int GetRightTabX() const; @@ -89,7 +91,7 @@ int GetRightTabX() const; ### Return Value -Returns the right-hand X-value of the enclosing rectangle of the `CMFCRibbonCategory` object’s ribbon tab, or a value of -1 if the tab is truncated. +Returns the right-hand X-value of the enclosing rectangle of the `CMFCRibbonCategory` object's ribbon tab, or a value of -1 if the tab is truncated. ### Remarks diff --git a/docs/mfc/reference/cmfcribboncustomizedialog-class.md b/docs/mfc/reference/cmfcribboncustomizedialog-class.md index f465c917d41..dde0bf3da9d 100644 --- a/docs/mfc/reference/cmfcribboncustomizedialog-class.md +++ b/docs/mfc/reference/cmfcribboncustomizedialog-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonCustomizeDialog Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonCustomizeDialog", "AFXRIBBONCUSTOMIZEDIALOG/CMFCRibbonCustomizeDialog", "AFXRIBBONCUSTOMIZEDIALOG/CMFCRibbonCustomizeDialog::CMFCRibbonCustomizeDialog"] helpviewer_keywords: ["CMFCRibbonCustomizeDialog [MFC], CMFCRibbonCustomizeDialog"] -ms.assetid: ce67de7f-5eaa-4c75-9b94-f290f36df073 --- # CMFCRibbonCustomizeDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Displays the ribbon **Customize** page. ## Syntax diff --git a/docs/mfc/reference/cmfcribboncustomizepropertypage-class.md b/docs/mfc/reference/cmfcribboncustomizepropertypage-class.md index 1580c5a1aa3..47791413a83 100644 --- a/docs/mfc/reference/cmfcribboncustomizepropertypage-class.md +++ b/docs/mfc/reference/cmfcribboncustomizepropertypage-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonCustomizePropertyPage Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonCustomizePropertyPage", "AFXRIBBONCUSTOMIZEDIALOG/CMFCRibbonCustomizePropertyPage", "AFXRIBBONCUSTOMIZEDIALOG/CMFCRibbonCustomizePropertyPage::CMFCRibbonCustomizePropertyPage", "AFXRIBBONCUSTOMIZEDIALOG/CMFCRibbonCustomizePropertyPage::AddCustomCategory", "AFXRIBBONCUSTOMIZEDIALOG/CMFCRibbonCustomizePropertyPage::OnOK"] helpviewer_keywords: ["CMFCRibbonCustomizePropertyPage [MFC], CMFCRibbonCustomizePropertyPage", "CMFCRibbonCustomizePropertyPage [MFC], AddCustomCategory", "CMFCRibbonCustomizePropertyPage [MFC], OnOK"] -ms.assetid: ea32a99a-dfbe-401e-8975-aa191552532f --- # CMFCRibbonCustomizePropertyPage Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a custom page for the **Customize** dialog box in Ribbon-based applications. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonedit-class.md b/docs/mfc/reference/cmfcribbonedit-class.md index d27304b45d2..6e6bd2a3279 100644 --- a/docs/mfc/reference/cmfcribbonedit-class.md +++ b/docs/mfc/reference/cmfcribbonedit-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonEdit Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonEdit", "AFXRIBBONEDIT/CMFCRibbonEdit", "AFXRIBBONEDIT/CMFCRibbonEdit::CMFCRibbonEdit", "AFXRIBBONEDIT/CMFCRibbonEdit::CanBeStretched", "AFXRIBBONEDIT/CMFCRibbonEdit::CopyFrom", "AFXRIBBONEDIT/CMFCRibbonEdit::CreateEdit", "AFXRIBBONEDIT/CMFCRibbonEdit::DestroyCtrl", "AFXRIBBONEDIT/CMFCRibbonEdit::DropDownList", "AFXRIBBONEDIT/CMFCRibbonEdit::EnableSpinButtons", "AFXRIBBONEDIT/CMFCRibbonEdit::GetCompactSize", "AFXRIBBONEDIT/CMFCRibbonEdit::GetEditText", "AFXRIBBONEDIT/CMFCRibbonEdit::GetIntermediateSize", "AFXRIBBONEDIT/CMFCRibbonEdit::GetTextAlign", "AFXRIBBONEDIT/CMFCRibbonEdit::GetWidth", "AFXRIBBONEDIT/CMFCRibbonEdit::HasCompactMode", "AFXRIBBONEDIT/CMFCRibbonEdit::HasFocus", "AFXRIBBONEDIT/CMFCRibbonEdit::HasLargeMode", "AFXRIBBONEDIT/CMFCRibbonEdit::HasSpinButtons", "AFXRIBBONEDIT/CMFCRibbonEdit::IsHighlighted", "AFXRIBBONEDIT/CMFCRibbonEdit::OnAfterChangeRect", "AFXRIBBONEDIT/CMFCRibbonEdit::OnDraw", "AFXRIBBONEDIT/CMFCRibbonEdit::OnDrawLabelAndImage", "AFXRIBBONEDIT/CMFCRibbonEdit::OnDrawOnList", "AFXRIBBONEDIT/CMFCRibbonEdit::OnEnable", "AFXRIBBONEDIT/CMFCRibbonEdit::OnHighlight", "AFXRIBBONEDIT/CMFCRibbonEdit::OnKey", "AFXRIBBONEDIT/CMFCRibbonEdit::OnLButtonDown", "AFXRIBBONEDIT/CMFCRibbonEdit::OnLButtonUp", "AFXRIBBONEDIT/CMFCRibbonEdit::OnRTLChanged", "AFXRIBBONEDIT/CMFCRibbonEdit::OnShow", "AFXRIBBONEDIT/CMFCRibbonEdit::Redraw", "AFXRIBBONEDIT/CMFCRibbonEdit::SetACCData", "AFXRIBBONEDIT/CMFCRibbonEdit::SetEditText", "AFXRIBBONEDIT/CMFCRibbonEdit::SetTextAlign", "AFXRIBBONEDIT/CMFCRibbonEdit::SetWidth"] helpviewer_keywords: ["CMFCRibbonEdit [MFC], CMFCRibbonEdit", "CMFCRibbonEdit [MFC], CanBeStretched", "CMFCRibbonEdit [MFC], CMFCRibbonEdit", "CMFCRibbonEdit [MFC], CopyFrom", "CMFCRibbonEdit [MFC], CreateEdit", "CMFCRibbonEdit [MFC], DestroyCtrl", "CMFCRibbonEdit [MFC], DropDownList", "CMFCRibbonEdit [MFC], EnableSpinButtons", "CMFCRibbonEdit [MFC], GetCompactSize", "CMFCRibbonEdit [MFC], GetEditText", "CMFCRibbonEdit [MFC], GetIntermediateSize", "CMFCRibbonEdit [MFC], GetTextAlign", "CMFCRibbonEdit [MFC], GetWidth", "CMFCRibbonEdit [MFC], HasCompactMode", "CMFCRibbonEdit [MFC], HasFocus", "CMFCRibbonEdit [MFC], HasLargeMode", "CMFCRibbonEdit [MFC], HasSpinButtons", "CMFCRibbonEdit [MFC], IsHighlighted", "CMFCRibbonEdit [MFC], OnAfterChangeRect", "CMFCRibbonEdit [MFC], OnDraw", "CMFCRibbonEdit [MFC], OnDrawLabelAndImage", "CMFCRibbonEdit [MFC], OnDrawOnList", "CMFCRibbonEdit [MFC], OnEnable", "CMFCRibbonEdit [MFC], OnHighlight", "CMFCRibbonEdit [MFC], OnKey", "CMFCRibbonEdit [MFC], OnLButtonDown", "CMFCRibbonEdit [MFC], OnLButtonUp", "CMFCRibbonEdit [MFC], OnRTLChanged", "CMFCRibbonEdit [MFC], OnShow", "CMFCRibbonEdit [MFC], Redraw", "CMFCRibbonEdit [MFC], SetACCData", "CMFCRibbonEdit [MFC], SetEditText", "CMFCRibbonEdit [MFC], SetTextAlign", "CMFCRibbonEdit [MFC], SetWidth"] -ms.assetid: 9b85f1f2-446b-454e-9af9-104fdad8a897 --- # CMFCRibbonEdit Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements an edit control that is located on a ribbon bar. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonfontcombobox-class.md b/docs/mfc/reference/cmfcribbonfontcombobox-class.md index 3582dbb7f95..ac472185acb 100644 --- a/docs/mfc/reference/cmfcribbonfontcombobox-class.md +++ b/docs/mfc/reference/cmfcribbonfontcombobox-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a combo box that contains a list of fonts. You place the combo box on a ribbon panel. ## Syntax @@ -110,7 +112,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 +226,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 b86fd74dc26..097256031c0 100644 --- a/docs/mfc/reference/cmfcribbongallery-class.md +++ b/docs/mfc/reference/cmfcribbongallery-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonGallery Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonGallery", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::CMFCRibbonGallery", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::AddGroup", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::AddSubItem", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::Clear", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::EnableMenuResize", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::EnableMenuSideBar", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetCompactSize", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetDroppedDown", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetGroupName", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetGroupOffset", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetIconsInRow", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetItemToolTip", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetLastSelectedItem", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetPaletteID", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetRegularSize", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::GetSelectedItem", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::HasMenu", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::IsButtonMode", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::IsMenuResizeEnabled", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::IsMenuResizeVertical", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::IsMenuSideBar", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::OnAfterChangeRect", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::OnDraw", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::OnEnable", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::OnRTLChanged", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::RedrawIcons", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::RemoveItemToolTips", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SelectItem", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SetACCData", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SetButtonMode", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SetGroupName", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SetIconsInRow", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SetItemToolTip", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SetPalette", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::SetPaletteID", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGallery::OnDrawPaletteIcon"] helpviewer_keywords: ["CMFCRibbonGallery [MFC], CMFCRibbonGallery", "CMFCRibbonGallery [MFC], AddGroup", "CMFCRibbonGallery [MFC], AddSubItem", "CMFCRibbonGallery [MFC], Clear", "CMFCRibbonGallery [MFC], EnableMenuResize", "CMFCRibbonGallery [MFC], EnableMenuSideBar", "CMFCRibbonGallery [MFC], GetCompactSize", "CMFCRibbonGallery [MFC], GetDroppedDown", "CMFCRibbonGallery [MFC], GetGroupName", "CMFCRibbonGallery [MFC], GetGroupOffset", "CMFCRibbonGallery [MFC], GetIconsInRow", "CMFCRibbonGallery [MFC], GetItemToolTip", "CMFCRibbonGallery [MFC], GetLastSelectedItem", "CMFCRibbonGallery [MFC], GetPaletteID", "CMFCRibbonGallery [MFC], GetRegularSize", "CMFCRibbonGallery [MFC], GetSelectedItem", "CMFCRibbonGallery [MFC], HasMenu", "CMFCRibbonGallery [MFC], IsButtonMode", "CMFCRibbonGallery [MFC], IsMenuResizeEnabled", "CMFCRibbonGallery [MFC], IsMenuResizeVertical", "CMFCRibbonGallery [MFC], IsMenuSideBar", "CMFCRibbonGallery [MFC], OnAfterChangeRect", "CMFCRibbonGallery [MFC], OnDraw", "CMFCRibbonGallery [MFC], OnEnable", "CMFCRibbonGallery [MFC], OnRTLChanged", "CMFCRibbonGallery [MFC], RedrawIcons", "CMFCRibbonGallery [MFC], RemoveItemToolTips", "CMFCRibbonGallery [MFC], SelectItem", "CMFCRibbonGallery [MFC], SetACCData", "CMFCRibbonGallery [MFC], SetButtonMode", "CMFCRibbonGallery [MFC], SetGroupName", "CMFCRibbonGallery [MFC], SetIconsInRow", "CMFCRibbonGallery [MFC], SetItemToolTip", "CMFCRibbonGallery [MFC], SetPalette", "CMFCRibbonGallery [MFC], SetPaletteID", "CMFCRibbonGallery [MFC], OnDrawPaletteIcon"] -ms.assetid: 9734c9c9-981c-4b3f-8c59-264fd41811b4 --- # CMFCRibbonGallery Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements Office 2007-style ribbon galleries. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -84,8 +86,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 dfc162862f5..34d3bb3d3a3 100644 --- a/docs/mfc/reference/cmfcribbongallerymenubutton-class.md +++ b/docs/mfc/reference/cmfcribbongallerymenubutton-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonGalleryMenuButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonGalleryMenuButton", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGalleryMenuButton", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGalleryMenuButton::CMFCRibbonGalleryMenuButton", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGalleryMenuButton::CopyFrom", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGalleryMenuButton::CreatePopupMenu", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGalleryMenuButton::GetPalette", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGalleryMenuButton::HasButton", "AFXRIBBONPALETTEGALLERY/CMFCRibbonGalleryMenuButton::IsEmptyMenuAllowed"] helpviewer_keywords: ["CMFCRibbonGalleryMenuButton [MFC], CMFCRibbonGalleryMenuButton", "CMFCRibbonGalleryMenuButton [MFC], CopyFrom", "CMFCRibbonGalleryMenuButton [MFC], CreatePopupMenu", "CMFCRibbonGalleryMenuButton [MFC], GetPalette", "CMFCRibbonGalleryMenuButton [MFC], HasButton", "CMFCRibbonGalleryMenuButton [MFC], IsEmptyMenuAllowed"] -ms.assetid: 4d459d9b-8b1a-4371-92f6-dc4ce6cc42c8 --- # CMFCRibbonGalleryMenuButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a ribbon menu button that contains ribbon galleries. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -71,8 +73,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/cmfcribbonlabel-class.md b/docs/mfc/reference/cmfcribbonlabel-class.md index 9b505588b3d..da97ff30008 100644 --- a/docs/mfc/reference/cmfcribbonlabel-class.md +++ b/docs/mfc/reference/cmfcribbonlabel-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonLabel Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonLabel", "AFXRIBBONLABEL/CMFCRibbonLabel", "AFXRIBBONLABEL/CMFCRibbonLabel::CMFCRibbonLabel", "AFXRIBBONLABEL/CMFCRibbonLabel::SetACCData"] helpviewer_keywords: ["CMFCRibbonLabel [MFC], CMFCRibbonLabel", "CMFCRibbonLabel [MFC], SetACCData"] -ms.assetid: 0346c891-83bf-4f20-b8a1-c84cf2aadced --- # CMFCRibbonLabel Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a non-clickable text label for a ribbon. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonlinkctrl-class.md b/docs/mfc/reference/cmfcribbonlinkctrl-class.md index 14e3be9f0b1..6ac99272c06 100644 --- a/docs/mfc/reference/cmfcribbonlinkctrl-class.md +++ b/docs/mfc/reference/cmfcribbonlinkctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonLinkCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonLinkCtrl", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::CMFCRibbonLinkCtrl", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::CopyFrom", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::GetCompactSize", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::GetLink", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::GetRegularSize", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::GetToolTipText", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::IsDrawTooltipImage", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::OnDraw", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::OnDrawMenuImage", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::OnMouseMove", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::OnSetIcon", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::OpenLink", "AFXRIBBONLINKCTRL/CMFCRibbonLinkCtrl::SetLink"] helpviewer_keywords: ["CMFCRibbonLinkCtrl [MFC], CMFCRibbonLinkCtrl", "CMFCRibbonLinkCtrl [MFC], CopyFrom", "CMFCRibbonLinkCtrl [MFC], GetCompactSize", "CMFCRibbonLinkCtrl [MFC], GetLink", "CMFCRibbonLinkCtrl [MFC], GetRegularSize", "CMFCRibbonLinkCtrl [MFC], GetToolTipText", "CMFCRibbonLinkCtrl [MFC], IsDrawTooltipImage", "CMFCRibbonLinkCtrl [MFC], OnDraw", "CMFCRibbonLinkCtrl [MFC], OnDrawMenuImage", "CMFCRibbonLinkCtrl [MFC], OnMouseMove", "CMFCRibbonLinkCtrl [MFC], OnSetIcon", "CMFCRibbonLinkCtrl [MFC], OpenLink", "CMFCRibbonLinkCtrl [MFC], SetLink"] -ms.assetid: 77ae1941-e0ab-4a9d-911e-1752d34c079b --- # CMFCRibbonLinkCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a hyperlink that is positioned on a ribbon. The hyperlink opens a Web page when you click it. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -50,8 +52,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/cmfcribbonmainpanel-class.md b/docs/mfc/reference/cmfcribbonmainpanel-class.md index 622b1ecf24f..c97388bfaff 100644 --- a/docs/mfc/reference/cmfcribbonmainpanel-class.md +++ b/docs/mfc/reference/cmfcribbonmainpanel-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonMainPanel Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonMainPanel", "AFXRIBBONMAINPANEL/CMFCRibbonMainPanel", "AFXRIBBONMAINPANEL/CMFCRibbonMainPanel::Add", "AFXRIBBONMAINPANEL/CMFCRibbonMainPanel::AddRecentFilesList", "AFXRIBBONMAINPANEL/CMFCRibbonMainPanel::AddToBottom", "AFXRIBBONMAINPANEL/CMFCRibbonMainPanel::AddToRight", "AFXRIBBONMAINPANEL/CMFCRibbonMainPanel::GetCommandsFrame"] helpviewer_keywords: ["CMFCRibbonMainPanel [MFC], Add", "CMFCRibbonMainPanel [MFC], AddRecentFilesList", "CMFCRibbonMainPanel [MFC], AddToBottom", "CMFCRibbonMainPanel [MFC], AddToRight", "CMFCRibbonMainPanel [MFC], GetCommandsFrame"] -ms.assetid: 1af78798-5e75-4365-9c81-a54aa5679602 --- # CMFCRibbonMainPanel Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a ribbon panel that displays when you click the [CMFCRibbonApplicationButton](../../mfc/reference/cmfcribbonapplicationbutton-class.md). ## Syntax diff --git a/docs/mfc/reference/cmfcribbonminitoolbar-class.md b/docs/mfc/reference/cmfcribbonminitoolbar-class.md index 2cde2d313e5..07b6def8703 100644 --- a/docs/mfc/reference/cmfcribbonminitoolbar-class.md +++ b/docs/mfc/reference/cmfcribbonminitoolbar-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonMiniToolBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonMiniToolBar", "AFXRIBBONMINITOOLBAR/CMFCRibbonMiniToolBar", "AFXRIBBONMINITOOLBAR/CMFCRibbonMiniToolBar::IsContextMenuMode", "AFXRIBBONMINITOOLBAR/CMFCRibbonMiniToolBar::IsRibbonMiniToolBar", "AFXRIBBONMINITOOLBAR/CMFCRibbonMiniToolBar::SetCommands", "AFXRIBBONMINITOOLBAR/CMFCRibbonMiniToolBar::Show", "AFXRIBBONMINITOOLBAR/CMFCRibbonMiniToolBar::ShowWithContextMenu"] helpviewer_keywords: ["CMFCRibbonMiniToolBar [MFC], IsContextMenuMode", "CMFCRibbonMiniToolBar [MFC], IsRibbonMiniToolBar", "CMFCRibbonMiniToolBar [MFC], SetCommands", "CMFCRibbonMiniToolBar [MFC], Show", "CMFCRibbonMiniToolBar [MFC], ShowWithContextMenu"] -ms.assetid: 7017e963-aeaf-4fe9-b540-e15a7ed41e94 --- # CMFCRibbonMiniToolBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a contextual popup toolbar. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonpanel-class.md b/docs/mfc/reference/cmfcribbonpanel-class.md index ae0c4cf2d40..bbacccf348a 100644 --- a/docs/mfc/reference/cmfcribbonpanel-class.md +++ b/docs/mfc/reference/cmfcribbonpanel-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonPanel Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonPanel", "AFXRIBBONPANEL/CMFCRibbonPanel", "AFXRIBBONPANEL/CMFCRibbonPanel::CMFCRibbonPanel", "AFXRIBBONPANEL/CMFCRibbonPanel::Add", "AFXRIBBONPANEL/CMFCRibbonPanel::AddSeparator", "AFXRIBBONPANEL/CMFCRibbonPanel::AddToolBar", "AFXRIBBONPANEL/CMFCRibbonPanel::FindByData", "AFXRIBBONPANEL/CMFCRibbonPanel::FindByID", "AFXRIBBONPANEL/CMFCRibbonPanel::GetCaptionHeight", "AFXRIBBONPANEL/CMFCRibbonPanel::GetCount", "AFXRIBBONPANEL/CMFCRibbonPanel::GetData", "AFXRIBBONPANEL/CMFCRibbonPanel::GetDefaultButton", "AFXRIBBONPANEL/CMFCRibbonPanel::GetDroppedDown", "AFXRIBBONPANEL/CMFCRibbonPanel::GetElement", "AFXRIBBONPANEL/CMFCRibbonPanel::GetElements", "AFXRIBBONPANEL/CMFCRibbonPanel::GetElementsByID", "AFXRIBBONPANEL/CMFCRibbonPanel::GetFocused", "AFXRIBBONPANEL/CMFCRibbonPanel::GetGalleryRect", "AFXRIBBONPANEL/CMFCRibbonPanel::GetHighlighted", "AFXRIBBONPANEL/CMFCRibbonPanel::GetIndex", "AFXRIBBONPANEL/CMFCRibbonPanel::GetItemIDsList", "AFXRIBBONPANEL/CMFCRibbonPanel::GetName", "AFXRIBBONPANEL/CMFCRibbonPanel::GetParentButton", "AFXRIBBONPANEL/CMFCRibbonPanel::GetParentCategory", "AFXRIBBONPANEL/CMFCRibbonPanel::GetParentMenuBar", "AFXRIBBONPANEL/CMFCRibbonPanel::GetPreferedMenuLocation", "AFXRIBBONPANEL/CMFCRibbonPanel::GetPressed", "AFXRIBBONPANEL/CMFCRibbonPanel::GetRect", "AFXRIBBONPANEL/CMFCRibbonPanel::GetVisibleElements", "AFXRIBBONPANEL/CMFCRibbonPanel::HasElement", "AFXRIBBONPANEL/CMFCRibbonPanel::HitTest", "AFXRIBBONPANEL/CMFCRibbonPanel::HitTestEx", "AFXRIBBONPANEL/CMFCRibbonPanel::Insert", "AFXRIBBONPANEL/CMFCRibbonPanel::InsertSeparator", "AFXRIBBONPANEL/CMFCRibbonPanel::IsCenterColumnVert", "AFXRIBBONPANEL/CMFCRibbonPanel::IsCollapsed", "AFXRIBBONPANEL/CMFCRibbonPanel::IsHighlighted", "AFXRIBBONPANEL/CMFCRibbonPanel::IsJustifyColumns", "AFXRIBBONPANEL/CMFCRibbonPanel::IsMainPanel", "AFXRIBBONPANEL/CMFCRibbonPanel::IsMenuMode", "AFXRIBBONPANEL/CMFCRibbonPanel::MakeGalleryItemVisible", "AFXRIBBONPANEL/CMFCRibbonPanel::OnKey", "AFXRIBBONPANEL/CMFCRibbonPanel::RecalcWidths", "AFXRIBBONPANEL/CMFCRibbonPanel::Remove", "AFXRIBBONPANEL/CMFCRibbonPanel::RemoveAll", "AFXRIBBONPANEL/CMFCRibbonPanel::Replace", "AFXRIBBONPANEL/CMFCRibbonPanel::ReplaceByID", "AFXRIBBONPANEL/CMFCRibbonPanel::SetCenterColumnVert", "AFXRIBBONPANEL/CMFCRibbonPanel::SetData", "AFXRIBBONPANEL/CMFCRibbonPanel::SetElementMenu", "AFXRIBBONPANEL/CMFCRibbonPanel::SetElementRTC", "AFXRIBBONPANEL/CMFCRibbonPanel::SetElementRTCByID", "AFXRIBBONPANEL/CMFCRibbonPanel::SetFocused", "AFXRIBBONPANEL/CMFCRibbonPanel::SetJustifyColumns", "AFXRIBBONPANEL/CMFCRibbonPanel::SetKeys", "AFXRIBBONPANEL/CMFCRibbonPanel::ShowPopup"] helpviewer_keywords: ["CMFCRibbonPanel [MFC], CMFCRibbonPanel", "CMFCRibbonPanel [MFC], Add", "CMFCRibbonPanel [MFC], AddSeparator", "CMFCRibbonPanel [MFC], AddToolBar", "CMFCRibbonPanel [MFC], FindByData", "CMFCRibbonPanel [MFC], FindByID", "CMFCRibbonPanel [MFC], GetCaptionHeight", "CMFCRibbonPanel [MFC], GetCount", "CMFCRibbonPanel [MFC], GetData", "CMFCRibbonPanel [MFC], GetDefaultButton", "CMFCRibbonPanel [MFC], GetDroppedDown", "CMFCRibbonPanel [MFC], GetElement", "CMFCRibbonPanel [MFC], GetElements", "CMFCRibbonPanel [MFC], GetElementsByID", "CMFCRibbonPanel [MFC], GetFocused", "CMFCRibbonPanel [MFC], GetGalleryRect", "CMFCRibbonPanel [MFC], GetHighlighted", "CMFCRibbonPanel [MFC], GetIndex", "CMFCRibbonPanel [MFC], GetItemIDsList", "CMFCRibbonPanel [MFC], GetName", "CMFCRibbonPanel [MFC], GetParentButton", "CMFCRibbonPanel [MFC], GetParentCategory", "CMFCRibbonPanel [MFC], GetParentMenuBar", "CMFCRibbonPanel [MFC], GetPreferedMenuLocation", "CMFCRibbonPanel [MFC], GetPressed", "CMFCRibbonPanel [MFC], GetRect", "CMFCRibbonPanel [MFC], GetVisibleElements", "CMFCRibbonPanel [MFC], HasElement", "CMFCRibbonPanel [MFC], HitTest", "CMFCRibbonPanel [MFC], HitTestEx", "CMFCRibbonPanel [MFC], Insert", "CMFCRibbonPanel [MFC], InsertSeparator", "CMFCRibbonPanel [MFC], IsCenterColumnVert", "CMFCRibbonPanel [MFC], IsCollapsed", "CMFCRibbonPanel [MFC], IsHighlighted", "CMFCRibbonPanel [MFC], IsJustifyColumns", "CMFCRibbonPanel [MFC], IsMainPanel", "CMFCRibbonPanel [MFC], IsMenuMode", "CMFCRibbonPanel [MFC], MakeGalleryItemVisible", "CMFCRibbonPanel [MFC], OnKey", "CMFCRibbonPanel [MFC], RecalcWidths", "CMFCRibbonPanel [MFC], Remove", "CMFCRibbonPanel [MFC], RemoveAll", "CMFCRibbonPanel [MFC], Replace", "CMFCRibbonPanel [MFC], ReplaceByID", "CMFCRibbonPanel [MFC], SetCenterColumnVert", "CMFCRibbonPanel [MFC], SetData", "CMFCRibbonPanel [MFC], SetElementMenu", "CMFCRibbonPanel [MFC], SetElementRTC", "CMFCRibbonPanel [MFC], SetElementRTCByID", "CMFCRibbonPanel [MFC], SetFocused", "CMFCRibbonPanel [MFC], SetJustifyColumns", "CMFCRibbonPanel [MFC], SetKeys", "CMFCRibbonPanel [MFC], ShowPopup"] -ms.assetid: 51d70749-1140-4386-b103-f14082049ba6 --- # CMFCRibbonPanel Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -968,7 +970,6 @@ If you want to add a custom element (for example, a color button) to the ribbon The following example shows how to use the `SetElementRTCByID` method: ``` - // Load and add toolbar with standard buttons. This toolbar // should display a custom color button with id ID_CHAR_COLOR: diff --git a/docs/mfc/reference/cmfcribbonprogressbar-class.md b/docs/mfc/reference/cmfcribbonprogressbar-class.md index 5155a822f97..67c5ff15ff7 100644 --- a/docs/mfc/reference/cmfcribbonprogressbar-class.md +++ b/docs/mfc/reference/cmfcribbonprogressbar-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonProgressBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonProgressBar", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::CMFCRibbonProgressBar", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::GetPos", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::GetRangeMax", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::GetRangeMin", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::GetRegularSize", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::IsInfiniteMode", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::OnDraw", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::SetInfiniteMode", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::SetPos", "AFXRIBBONPROGRESSBAR/CMFCRibbonProgressBar::SetRange"] helpviewer_keywords: ["CMFCRibbonProgressBar [MFC], CMFCRibbonProgressBar", "CMFCRibbonProgressBar [MFC], GetPos", "CMFCRibbonProgressBar [MFC], GetRangeMax", "CMFCRibbonProgressBar [MFC], GetRangeMin", "CMFCRibbonProgressBar [MFC], GetRegularSize", "CMFCRibbonProgressBar [MFC], IsInfiniteMode", "CMFCRibbonProgressBar [MFC], OnDraw", "CMFCRibbonProgressBar [MFC], SetInfiniteMode", "CMFCRibbonProgressBar [MFC], SetPos", "CMFCRibbonProgressBar [MFC], SetRange"] -ms.assetid: de3d9f2e-ed59-480e-aa7d-08a33ab36c67 --- # CMFCRibbonProgressBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a control that visually indicates the progress of a lengthy operation. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md b/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md index 7065867788b..0357f3a8f14 100644 --- a/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md +++ b/docs/mfc/reference/cmfcribbonquickaccesstoolbardefaultstate-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonQuickAccessToolBarDefaultState Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonQuickAccessToolBarDefaultState", "AFXRIBBONQUICKACCESSTOOLBAR/CMFCRibbonQuickAccessToolBarDefaultState", "AFXRIBBONQUICKACCESSTOOLBAR/CMFCRibbonQuickAccessToolBarDefaultState::CMFCRibbonQuickAccessToolBarDefaultState", "AFXRIBBONQUICKACCESSTOOLBAR/CMFCRibbonQuickAccessToolBarDefaultState::AddCommand", "AFXRIBBONQUICKACCESSTOOLBAR/CMFCRibbonQuickAccessToolBarDefaultState::CopyFrom", "AFXRIBBONQUICKACCESSTOOLBAR/CMFCRibbonQuickAccessToolBarDefaultState::RemoveAll"] helpviewer_keywords: ["CMFCRibbonQuickAccessToolBarDefaultState [MFC], CMFCRibbonQuickAccessToolBarDefaultState", "CMFCRibbonQuickAccessToolBarDefaultState [MFC], AddCommand", "CMFCRibbonQuickAccessToolBarDefaultState [MFC], CopyFrom", "CMFCRibbonQuickAccessToolBarDefaultState [MFC], RemoveAll"] -ms.assetid: eca99200-b87b-47ba-b2e8-2f3f2444b176 --- # `CMFCRibbonQuickAccessToolBarDefaultState` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A helper class that manages default state for the Quick Access Toolbar that is positioned on the ribbon bar ([`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.md)). ## Syntax diff --git a/docs/mfc/reference/cmfcribbonseparator-class.md b/docs/mfc/reference/cmfcribbonseparator-class.md index 83e9ba528dc..e4839b50c9d 100644 --- a/docs/mfc/reference/cmfcribbonseparator-class.md +++ b/docs/mfc/reference/cmfcribbonseparator-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonSeparator Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonSeparator", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::CMFCRibbonSeparator", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::AddToListBox", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::CopyFrom", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::GetRegularSize", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::IsSeparator", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::IsTabStop", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::OnDraw", "AFXBASERIBBONELEMENT/CMFCRibbonSeparator::OnDrawOnList"] helpviewer_keywords: ["CMFCRibbonSeparator [MFC], CMFCRibbonSeparator", "CMFCRibbonSeparator [MFC], AddToListBox", "CMFCRibbonSeparator [MFC], CopyFrom", "CMFCRibbonSeparator [MFC], GetRegularSize", "CMFCRibbonSeparator [MFC], IsSeparator", "CMFCRibbonSeparator [MFC], IsTabStop", "CMFCRibbonSeparator [MFC], OnDraw", "CMFCRibbonSeparator [MFC], OnDrawOnList"] -ms.assetid: bedb1a53-cb07-4c3c-be12-698c5409e7cf --- # CMFCRibbonSeparator Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the ribbon separator. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonslider-class.md b/docs/mfc/reference/cmfcribbonslider-class.md index d0930642854..52069775539 100644 --- a/docs/mfc/reference/cmfcribbonslider-class.md +++ b/docs/mfc/reference/cmfcribbonslider-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonSlider Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonSlider", "AFXRIBBONSLIDER/CMFCRibbonSlider", "AFXRIBBONSLIDER/CMFCRibbonSlider::CMFCRibbonSlider", "AFXRIBBONSLIDER/CMFCRibbonSlider::GetPos", "AFXRIBBONSLIDER/CMFCRibbonSlider::GetRangeMax", "AFXRIBBONSLIDER/CMFCRibbonSlider::GetRangeMin", "AFXRIBBONSLIDER/CMFCRibbonSlider::GetRegularSize", "AFXRIBBONSLIDER/CMFCRibbonSlider::GetZoomIncrement", "AFXRIBBONSLIDER/CMFCRibbonSlider::HasZoomButtons", "AFXRIBBONSLIDER/CMFCRibbonSlider::OnDraw", "AFXRIBBONSLIDER/CMFCRibbonSlider::SetPos", "AFXRIBBONSLIDER/CMFCRibbonSlider::SetRange", "AFXRIBBONSLIDER/CMFCRibbonSlider::SetZoomButtons", "AFXRIBBONSLIDER/CMFCRibbonSlider::SetZoomIncrement"] helpviewer_keywords: ["CMFCRibbonSlider [MFC], CMFCRibbonSlider", "CMFCRibbonSlider [MFC], GetPos", "CMFCRibbonSlider [MFC], GetRangeMax", "CMFCRibbonSlider [MFC], GetRangeMin", "CMFCRibbonSlider [MFC], GetRegularSize", "CMFCRibbonSlider [MFC], GetZoomIncrement", "CMFCRibbonSlider [MFC], HasZoomButtons", "CMFCRibbonSlider [MFC], OnDraw", "CMFCRibbonSlider [MFC], SetPos", "CMFCRibbonSlider [MFC], SetRange", "CMFCRibbonSlider [MFC], SetZoomButtons", "CMFCRibbonSlider [MFC], SetZoomIncrement"] -ms.assetid: 9351ac34-f234-4e42-91e2-763f1989c8ff --- # CMFCRibbonSlider Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonSlider` class 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. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonstatusbar-class.md b/docs/mfc/reference/cmfcribbonstatusbar-class.md index 1b142bb2694..0326624c77c 100644 --- a/docs/mfc/reference/cmfcribbonstatusbar-class.md +++ b/docs/mfc/reference/cmfcribbonstatusbar-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonStatusBar Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonStatusBar", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::AddDynamicElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::AddElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::AddExtendedElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::AddSeparator", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::Create", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::CreateEx", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::FindByID", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::FindElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::GetCount", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::GetElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::GetExCount", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::GetExElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::GetExtendedArea", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::GetSpace", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::IsBottomFrame", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::IsExtendedElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::IsInformationMode", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::RecalcLayout", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::RemoveAll", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::RemoveElement", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::SetInformation", "AFXRIBBONSTATUSBAR/CMFCRibbonStatusBar::OnDrawInformation"] helpviewer_keywords: ["CMFCRibbonStatusBar [MFC], AddDynamicElement", "CMFCRibbonStatusBar [MFC], AddElement", "CMFCRibbonStatusBar [MFC], AddExtendedElement", "CMFCRibbonStatusBar [MFC], AddSeparator", "CMFCRibbonStatusBar [MFC], Create", "CMFCRibbonStatusBar [MFC], CreateEx", "CMFCRibbonStatusBar [MFC], FindByID", "CMFCRibbonStatusBar [MFC], FindElement", "CMFCRibbonStatusBar [MFC], GetCount", "CMFCRibbonStatusBar [MFC], GetElement", "CMFCRibbonStatusBar [MFC], GetExCount", "CMFCRibbonStatusBar [MFC], GetExElement", "CMFCRibbonStatusBar [MFC], GetExtendedArea", "CMFCRibbonStatusBar [MFC], GetSpace", "CMFCRibbonStatusBar [MFC], IsBottomFrame", "CMFCRibbonStatusBar [MFC], IsExtendedElement", "CMFCRibbonStatusBar [MFC], IsInformationMode", "CMFCRibbonStatusBar [MFC], RecalcLayout", "CMFCRibbonStatusBar [MFC], RemoveAll", "CMFCRibbonStatusBar [MFC], RemoveElement", "CMFCRibbonStatusBar [MFC], SetInformation", "CMFCRibbonStatusBar [MFC], OnDrawInformation"] -ms.assetid: 921eb57f-3b40-49fa-a38c-3f2fb6dc2893 --- # CMFCRibbonStatusBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonStatusBar` class implements a status bar control that can display ribbon elements. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonstatusbarpane-class.md b/docs/mfc/reference/cmfcribbonstatusbarpane-class.md index 8893c2f2649..7c7da6cf122 100644 --- a/docs/mfc/reference/cmfcribbonstatusbarpane-class.md +++ b/docs/mfc/reference/cmfcribbonstatusbarpane-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonStatusBarPane Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonStatusBarPane", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::CMFCRibbonStatusBarPane", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::GetAlmostLargeText", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::GetTextAlign", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::IsAnimation", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::IsExtended", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::OnDrawBorder", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::OnFillBackground", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::SetAlmostLargeText", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::SetAnimationList", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::SetTextAlign", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::StartAnimation", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::StopAnimation", "AFXRIBBONSTATUSBARPANE/CMFCRibbonStatusBarPane::OnFinishAnimation"] helpviewer_keywords: ["CMFCRibbonStatusBarPane [MFC], CMFCRibbonStatusBarPane", "CMFCRibbonStatusBarPane [MFC], GetAlmostLargeText", "CMFCRibbonStatusBarPane [MFC], GetTextAlign", "CMFCRibbonStatusBarPane [MFC], IsAnimation", "CMFCRibbonStatusBarPane [MFC], IsExtended", "CMFCRibbonStatusBarPane [MFC], OnDrawBorder", "CMFCRibbonStatusBarPane [MFC], OnFillBackground", "CMFCRibbonStatusBarPane [MFC], SetAlmostLargeText", "CMFCRibbonStatusBarPane [MFC], SetAnimationList", "CMFCRibbonStatusBarPane [MFC], SetTextAlign", "CMFCRibbonStatusBarPane [MFC], StartAnimation", "CMFCRibbonStatusBarPane [MFC], StopAnimation", "CMFCRibbonStatusBarPane [MFC], OnFinishAnimation"] -ms.assetid: 5d034c3c-ecca-4267-b88c-0f55a2884dd0 --- # CMFCRibbonStatusBarPane Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonStatusBarPane` class implements a ribbon element that you can add to a ribbon status bar. ## Syntax diff --git a/docs/mfc/reference/cmfcribbonundobutton-class.md b/docs/mfc/reference/cmfcribbonundobutton-class.md index 2cc70cab6a8..19f612a1c0a 100644 --- a/docs/mfc/reference/cmfcribbonundobutton-class.md +++ b/docs/mfc/reference/cmfcribbonundobutton-class.md @@ -4,10 +4,12 @@ title: "CMFCRibbonUndoButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCRibbonUndoButton", "AFXRIBBONUNDOBUTTON/CMFCRibbonUndoButton", "AFXRIBBONUNDOBUTTON/CMFCRibbonUndoButton::CMFCRibbonUndoButton", "AFXRIBBONUNDOBUTTON/CMFCRibbonUndoButton::AddUndoAction", "AFXRIBBONUNDOBUTTON/CMFCRibbonUndoButton::CleanUpUndoList", "AFXRIBBONUNDOBUTTON/CMFCRibbonUndoButton::GetActionNumber", "AFXRIBBONUNDOBUTTON/CMFCRibbonUndoButton::HasMenu"] helpviewer_keywords: ["CMFCRibbonUndoButton [MFC], CMFCRibbonUndoButton", "CMFCRibbonUndoButton [MFC], AddUndoAction", "CMFCRibbonUndoButton [MFC], CleanUpUndoList", "CMFCRibbonUndoButton [MFC], GetActionNumber", "CMFCRibbonUndoButton [MFC], HasMenu"] -ms.assetid: 5c42adf7-871d-4239-901e-47ae7fb816fc --- # CMFCRibbonUndoButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCRibbonUndoButton` class implements a drop-down list button that contains the most recent user commands. Users can select one or more of the most recent commands from the drop-down list to either redo or undo them. ## Syntax diff --git a/docs/mfc/reference/cmfcshelllistctrl-class.md b/docs/mfc/reference/cmfcshelllistctrl-class.md index a912243d295..40bda8b608f 100644 --- a/docs/mfc/reference/cmfcshelllistctrl-class.md +++ b/docs/mfc/reference/cmfcshelllistctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCShellListCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCShellListCtrl", "AFXSHELLLISTCTRL/CMFCShellListCtrl", "AFXSHELLLISTCTRL/CMFCShellListCtrl::DisplayFolder", "AFXSHELLLISTCTRL/CMFCShellListCtrl::DisplayParentFolder", "AFXSHELLLISTCTRL/CMFCShellListCtrl::EnableShellContextMenu", "AFXSHELLLISTCTRL/CMFCShellListCtrl::GetCurrentFolder", "AFXSHELLLISTCTRL/CMFCShellListCtrl::GetCurrentFolderName", "AFXSHELLLISTCTRL/CMFCShellListCtrl::GetCurrentItemIdList", "AFXSHELLLISTCTRL/CMFCShellListCtrl::GetCurrentShellFolder", "AFXSHELLLISTCTRL/CMFCShellListCtrl::GetItemPath", "AFXSHELLLISTCTRL/CMFCShellListCtrl::GetItemTypes", "AFXSHELLLISTCTRL/CMFCShellListCtrl::IsDesktop", "AFXSHELLLISTCTRL/CMFCShellListCtrl::OnCompareItems", "AFXSHELLLISTCTRL/CMFCShellListCtrl::OnFormatFileDate", "AFXSHELLLISTCTRL/CMFCShellListCtrl::OnFormatFileSize", "AFXSHELLLISTCTRL/CMFCShellListCtrl::OnGetItemIcon", "AFXSHELLLISTCTRL/CMFCShellListCtrl::OnGetItemText", "AFXSHELLLISTCTRL/CMFCShellListCtrl::OnSetColumns", "AFXSHELLLISTCTRL/CMFCShellListCtrl::Refresh", "AFXSHELLLISTCTRL/CMFCShellListCtrl::SetItemTypes"] helpviewer_keywords: ["CMFCShellListCtrl [MFC], DisplayFolder", "CMFCShellListCtrl [MFC], DisplayParentFolder", "CMFCShellListCtrl [MFC], EnableShellContextMenu", "CMFCShellListCtrl [MFC], GetCurrentFolder", "CMFCShellListCtrl [MFC], GetCurrentFolderName", "CMFCShellListCtrl [MFC], GetCurrentItemIdList", "CMFCShellListCtrl [MFC], GetCurrentShellFolder", "CMFCShellListCtrl [MFC], GetItemPath", "CMFCShellListCtrl [MFC], GetItemTypes", "CMFCShellListCtrl [MFC], IsDesktop", "CMFCShellListCtrl [MFC], OnCompareItems", "CMFCShellListCtrl [MFC], OnFormatFileDate", "CMFCShellListCtrl [MFC], OnFormatFileSize", "CMFCShellListCtrl [MFC], OnGetItemIcon", "CMFCShellListCtrl [MFC], OnGetItemText", "CMFCShellListCtrl [MFC], OnSetColumns", "CMFCShellListCtrl [MFC], Refresh", "CMFCShellListCtrl [MFC], SetItemTypes"] -ms.assetid: ad472958-5586-4c50-aadf-1844c30bf6e7 --- # CMFCShellListCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCShellListCtrl` class provides Windows list control functionality and expands it by including the ability to display a list of shell items. ## Syntax diff --git a/docs/mfc/reference/cmfcshelltreectrl-class.md b/docs/mfc/reference/cmfcshelltreectrl-class.md index 7dfa16e3951..1389dd1c38b 100644 --- a/docs/mfc/reference/cmfcshelltreectrl-class.md +++ b/docs/mfc/reference/cmfcshelltreectrl-class.md @@ -4,10 +4,12 @@ title: "CMFCShellTreeCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCShellTreeCtrl", "AFXSHELLTREECTRL/CMFCShellTreeCtrl", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::EnableShellContextMenu", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::GetFlags", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::GetItemPath", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::GetRelatedList", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::OnChildNotify", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::OnGetItemIcon", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::OnGetItemText", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::Refresh", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::SelectPath", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::SetFlags", "AFXSHELLTREECTRL/CMFCShellTreeCtrl::SetRelatedList"] helpviewer_keywords: ["CMFCShellTreeCtrl [MFC], EnableShellContextMenu", "CMFCShellTreeCtrl [MFC], GetFlags", "CMFCShellTreeCtrl [MFC], GetItemPath", "CMFCShellTreeCtrl [MFC], GetRelatedList", "CMFCShellTreeCtrl [MFC], OnChildNotify", "CMFCShellTreeCtrl [MFC], OnGetItemIcon", "CMFCShellTreeCtrl [MFC], OnGetItemText", "CMFCShellTreeCtrl [MFC], Refresh", "CMFCShellTreeCtrl [MFC], SelectPath", "CMFCShellTreeCtrl [MFC], SetFlags", "CMFCShellTreeCtrl [MFC], SetRelatedList"] -ms.assetid: 3d1da715-9554-4ed7-968c-055c48146267 --- # CMFCShellTreeCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCShellTreeCtrl` class extends [CTreeCtrl Class](../../mfc/reference/ctreectrl-class.md) functionality by displaying a hierarchy of Shell items. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcspinbuttonctrl-class.md b/docs/mfc/reference/cmfcspinbuttonctrl-class.md index 4c0be4a5be5..ba101a0b26f 100644 --- a/docs/mfc/reference/cmfcspinbuttonctrl-class.md +++ b/docs/mfc/reference/cmfcspinbuttonctrl-class.md @@ -4,10 +4,12 @@ title: "CMFCSpinButtonCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCSpinButtonCtrl", "AFXSPINBUTTONCTRL/CMFCSpinButtonCtrl", "AFXSPINBUTTONCTRL/CMFCSpinButtonCtrl::OnDraw"] helpviewer_keywords: ["CMFCSpinButtonCtrl [MFC], OnDraw"] -ms.assetid: 8773f259-4d3f-4bca-a71c-09e0c71bc843 --- # CMFCSpinButtonCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCSpinButtonCtrl` class supports a visual manager that draws a spin button control. ## Syntax diff --git a/docs/mfc/reference/cmfcstandardcolorspropertypage-class.md b/docs/mfc/reference/cmfcstandardcolorspropertypage-class.md index bfa687e415c..74a8259dd78 100644 --- a/docs/mfc/reference/cmfcstandardcolorspropertypage-class.md +++ b/docs/mfc/reference/cmfcstandardcolorspropertypage-class.md @@ -3,10 +3,12 @@ description: "Learn more about: CMFCStandardColorsPropertyPage Class" title: "CMFCStandardColorsPropertyPage Class" ms.date: "11/04/2016" helpviewer_keywords: ["CMFCStandardColorsPropertyPage class [MFC]"] -ms.assetid: b84b7cfb-bb24-4c65-804a-5b642cb64400 --- # CMFCStandardColorsPropertyPage Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a property page that users use to select standard colors in a color dialog box. ## Syntax diff --git a/docs/mfc/reference/cmfcstatusbar-class.md b/docs/mfc/reference/cmfcstatusbar-class.md index 066130cf342..0f7754ee2fb 100644 --- a/docs/mfc/reference/cmfcstatusbar-class.md +++ b/docs/mfc/reference/cmfcstatusbar-class.md @@ -4,10 +4,12 @@ title: "CMFCStatusBar Class" ms.date: "11/19/2018" f1_keywords: ["CMFCStatusBar", "AFXSTATUSBAR/CMFCStatusBar", "AFXSTATUSBAR/CMFCStatusBar::CalcFixedLayout", "AFXSTATUSBAR/CMFCStatusBar::CommandToIndex", "AFXSTATUSBAR/CMFCStatusBar::Create", "AFXSTATUSBAR/CMFCStatusBar::CreateEx", "AFXSTATUSBAR/CMFCStatusBar::DoesAllowDynInsertBefore", "AFXSTATUSBAR/CMFCStatusBar::EnablePaneDoubleClick", "AFXSTATUSBAR/CMFCStatusBar::EnablePaneProgressBar", "AFXSTATUSBAR/CMFCStatusBar::GetCount", "AFXSTATUSBAR/CMFCStatusBar::GetDrawExtendedArea", "AFXSTATUSBAR/CMFCStatusBar::GetExtendedArea", "AFXSTATUSBAR/CMFCStatusBar::GetItemID", "AFXSTATUSBAR/CMFCStatusBar::GetItemRect", "AFXSTATUSBAR/CMFCStatusBar::GetPaneInfo", "AFXSTATUSBAR/CMFCStatusBar::GetPaneProgress", "AFXSTATUSBAR/CMFCStatusBar::GetPaneStyle", "AFXSTATUSBAR/CMFCStatusBar::GetPaneText", "AFXSTATUSBAR/CMFCStatusBar::GetPaneWidth", "AFXSTATUSBAR/CMFCStatusBar::GetTipText", "AFXSTATUSBAR/CMFCStatusBar::InvalidatePaneContent", "AFXSTATUSBAR/CMFCStatusBar::PreCreateWindow", "AFXSTATUSBAR/CMFCStatusBar::SetDrawExtendedArea", "AFXSTATUSBAR/CMFCStatusBar::SetIndicators", "AFXSTATUSBAR/CMFCStatusBar::SetPaneAnimation", "AFXSTATUSBAR/CMFCStatusBar::SetPaneBackgroundColor", "AFXSTATUSBAR/CMFCStatusBar::SetPaneIcon", "AFXSTATUSBAR/CMFCStatusBar::SetPaneInfo", "AFXSTATUSBAR/CMFCStatusBar::SetPaneProgress", "AFXSTATUSBAR/CMFCStatusBar::SetPaneStyle", "AFXSTATUSBAR/CMFCStatusBar::SetPaneText", "AFXSTATUSBAR/CMFCStatusBar::SetPaneTextColor", "AFXSTATUSBAR/CMFCStatusBar::SetPaneWidth", "AFXSTATUSBAR/CMFCStatusBar::SetTipText", "AFXSTATUSBAR/CMFCStatusBar::OnDrawPane"] helpviewer_keywords: ["CMFCStatusBar [MFC], CalcFixedLayout", "CMFCStatusBar [MFC], CommandToIndex", "CMFCStatusBar [MFC], Create", "CMFCStatusBar [MFC], CreateEx", "CMFCStatusBar [MFC], DoesAllowDynInsertBefore", "CMFCStatusBar [MFC], EnablePaneDoubleClick", "CMFCStatusBar [MFC], EnablePaneProgressBar", "CMFCStatusBar [MFC], GetCount", "CMFCStatusBar [MFC], GetDrawExtendedArea", "CMFCStatusBar [MFC], GetExtendedArea", "CMFCStatusBar [MFC], GetItemID", "CMFCStatusBar [MFC], GetItemRect", "CMFCStatusBar [MFC], GetPaneInfo", "CMFCStatusBar [MFC], GetPaneProgress", "CMFCStatusBar [MFC], GetPaneStyle", "CMFCStatusBar [MFC], GetPaneText", "CMFCStatusBar [MFC], GetPaneWidth", "CMFCStatusBar [MFC], GetTipText", "CMFCStatusBar [MFC], InvalidatePaneContent", "CMFCStatusBar [MFC], PreCreateWindow", "CMFCStatusBar [MFC], SetDrawExtendedArea", "CMFCStatusBar [MFC], SetIndicators", "CMFCStatusBar [MFC], SetPaneAnimation", "CMFCStatusBar [MFC], SetPaneBackgroundColor", "CMFCStatusBar [MFC], SetPaneIcon", "CMFCStatusBar [MFC], SetPaneInfo", "CMFCStatusBar [MFC], SetPaneProgress", "CMFCStatusBar [MFC], SetPaneStyle", "CMFCStatusBar [MFC], SetPaneText", "CMFCStatusBar [MFC], SetPaneTextColor", "CMFCStatusBar [MFC], SetPaneWidth", "CMFCStatusBar [MFC], SetTipText", "CMFCStatusBar [MFC], OnDrawPane"] -ms.assetid: f2960d1d-f4ed-41e8-bd99-0382b2f8d88e --- # CMFCStatusBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCStatusBar` class 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. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfctabctrl-class.md b/docs/mfc/reference/cmfctabctrl-class.md index 1a75a0bb84f..1cc67d8362b 100644 --- a/docs/mfc/reference/cmfctabctrl-class.md +++ b/docs/mfc/reference/cmfctabctrl-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CMFCTabCtrl [MFC], ActivateMDITab", "CMFCTabCtrl [MFC], A --- # `CMFCTabCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCTabCtrl` class provides functionality for a tab control. The tab control displays a dockable window with flat or three-dimensional tabs at its top or bottom. The tabs can display text and an image and can change color when active. ## Syntax @@ -775,7 +778,7 @@ virtual DROPEFFECT OnDragEnter( ### Return Value -Always `DROPEFFECT_NONE`, which means that the drop target can’t accept the data. +Always `DROPEFFECT_NONE`, which means that the drop target can't accept the data. ### Remarks @@ -947,7 +950,7 @@ virtual BOOL SetImageList(HIMAGELIST hImageList); ### Return Value -`TRUE` if this method is successful. `FALSE` if the tab control is created by using a flat style or if the first method overload can’t load the bitmap that is specified by the *`uiID`* parameter. +`TRUE` if this method is successful. `FALSE` if the tab control is created by using a flat style or if the first method overload can't load the bitmap that is specified by the *`uiID`* parameter. ### Remarks @@ -974,7 +977,7 @@ The *resizeMode* parameter can be one of the following `ResizeMode` enumeration |Name|Description| |----------|-----------------| -|`RESIZE_NO`|The tab control can’t be resized.| +|`RESIZE_NO`|The tab control can't be resized.| |`RESIZE_VERT`|The tab control can be resized vertically but not horizontally.| |`RESIZE_HORIZ`|The tab control can be resized horizontally but not vertically.| diff --git a/docs/mfc/reference/cmfctabdroptarget-class.md b/docs/mfc/reference/cmfctabdroptarget-class.md index 5d89adc8afd..23d80ad1a80 100644 --- a/docs/mfc/reference/cmfctabdroptarget-class.md +++ b/docs/mfc/reference/cmfctabdroptarget-class.md @@ -4,10 +4,12 @@ title: "CMFCTabDropTarget Class" ms.date: "11/04/2016" f1_keywords: ["CMFCTabDropTarget", "AFXBASETABCTRL/CMFCTabDropTarget", "AFXBASETABCTRL/CMFCTabDropTarget::OnDragEnter", "AFXBASETABCTRL/CMFCTabDropTarget::OnDragLeave", "AFXBASETABCTRL/CMFCTabDropTarget::OnDragOver", "AFXBASETABCTRL/CMFCTabDropTarget::OnDropEx", "AFXBASETABCTRL/CMFCTabDropTarget::Register"] helpviewer_keywords: ["CMFCTabDropTarget [MFC], OnDragEnter", "CMFCTabDropTarget [MFC], OnDragLeave", "CMFCTabDropTarget [MFC], OnDragOver", "CMFCTabDropTarget [MFC], OnDropEx", "CMFCTabDropTarget [MFC], Register"] -ms.assetid: 9777b7b6-10da-4c4b-b1d1-7ea795b0f1cb --- # CMFCTabDropTarget Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the communication mechanism between a tab control and the OLE libraries. ## Syntax diff --git a/docs/mfc/reference/cmfctabtooltipinfo-structure.md b/docs/mfc/reference/cmfctabtooltipinfo-structure.md index af9d6c82a9c..b83387bc247 100644 --- a/docs/mfc/reference/cmfctabtooltipinfo-structure.md +++ b/docs/mfc/reference/cmfctabtooltipinfo-structure.md @@ -4,10 +4,12 @@ title: "CMFCTabToolTipInfo Structure" ms.date: "11/04/2016" f1_keywords: ["CMFCTabToolTipInfo"] helpviewer_keywords: ["CMFCTabToolTipInfo struct"] -ms.assetid: 9c3b3fb9-1497-4d59-932b-0da9348dd5e2 --- # CMFCTabToolTipInfo Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This structure provides information about the MDI tab that the user is hovering over. ## Syntax diff --git a/docs/mfc/reference/cmfctaskspane-class.md b/docs/mfc/reference/cmfctaskspane-class.md index 8644aab7a74..c45aa476a0f 100644 --- a/docs/mfc/reference/cmfctaskspane-class.md +++ b/docs/mfc/reference/cmfctaskspane-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. The `CMFCTasksPane` class implements a list of clickable items (tasks). @@ -171,11 +173,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 +1463,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/cmfctaskspanetask-class.md b/docs/mfc/reference/cmfctaskspanetask-class.md index 215e27bed25..f11dfddd682 100644 --- a/docs/mfc/reference/cmfctaskspanetask-class.md +++ b/docs/mfc/reference/cmfctaskspanetask-class.md @@ -4,10 +4,12 @@ title: "CMFCTasksPaneTask Class" ms.date: "11/19/2018" f1_keywords: ["CMFCTasksPaneTask", "AFXTASKSPANE/CMFCTasksPaneTask", "AFXTASKSPANE/CMFCTasksPaneTask::CMFCTasksPaneTask", "AFXTASKSPANE/CMFCTasksPaneTask::SetACCData", "AFXTASKSPANE/CMFCTasksPaneTask::m_bAutoDestroyWindow", "AFXTASKSPANE/CMFCTasksPaneTask::m_bIsBold", "AFXTASKSPANE/CMFCTasksPaneTask::m_dwUserData", "AFXTASKSPANE/CMFCTasksPaneTask::m_hwndTask", "AFXTASKSPANE/CMFCTasksPaneTask::m_nIcon", "AFXTASKSPANE/CMFCTasksPaneTask::m_nWindowHeight", "AFXTASKSPANE/CMFCTasksPaneTask::m_pGroup", "AFXTASKSPANE/CMFCTasksPaneTask::m_rect", "AFXTASKSPANE/CMFCTasksPaneTask::m_strName", "AFXTASKSPANE/CMFCTasksPaneTask::m_uiCommandID"] helpviewer_keywords: ["CMFCTasksPaneTask [MFC], CMFCTasksPaneTask", "CMFCTasksPaneTask [MFC], SetACCData", "CMFCTasksPaneTask [MFC], m_bAutoDestroyWindow", "CMFCTasksPaneTask [MFC], m_bIsBold", "CMFCTasksPaneTask [MFC], m_dwUserData", "CMFCTasksPaneTask [MFC], m_hwndTask", "CMFCTasksPaneTask [MFC], m_nIcon", "CMFCTasksPaneTask [MFC], m_nWindowHeight", "CMFCTasksPaneTask [MFC], m_pGroup", "CMFCTasksPaneTask [MFC], m_rect", "CMFCTasksPaneTask [MFC], m_strName", "CMFCTasksPaneTask [MFC], m_uiCommandID"] -ms.assetid: c5a7513b-cd8f-4e2e-b16f-650e1fe30954 --- # CMFCTasksPaneTask Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCTasksPaneTask` class is a helper class that represents tasks for the task pane control ( [CMFCTasksPane](../../mfc/reference/cmfctaskspane-class.md)). The task object represents an item in the task group ( [CMFCTasksPaneTaskGroup](../../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. ## Syntax diff --git a/docs/mfc/reference/cmfctaskspanetaskgroup-class.md b/docs/mfc/reference/cmfctaskspanetaskgroup-class.md index c7f575c20a3..4db39770b60 100644 --- a/docs/mfc/reference/cmfctaskspanetaskgroup-class.md +++ b/docs/mfc/reference/cmfctaskspanetaskgroup-class.md @@ -4,10 +4,12 @@ title: "CMFCTasksPaneTaskGroup Class" ms.date: "11/19/2018" f1_keywords: ["CMFCTasksPaneTaskGroup", "AFXTASKSPANE/CMFCTasksPaneTaskGroup", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::CMFCTasksPaneTaskGroup", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::SetACCData", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::m_bIsBottom", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::m_bIsCollapsed", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::m_bIsSpecial", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::m_lstTasks", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::m_rect", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::m_rectGroup", "AFXTASKSPANE/CMFCTasksPaneTaskGroup::m_strName"] helpviewer_keywords: ["CMFCTasksPaneTaskGroup [MFC], CMFCTasksPaneTaskGroup", "CMFCTasksPaneTaskGroup [MFC], SetACCData", "CMFCTasksPaneTaskGroup [MFC], m_bIsBottom", "CMFCTasksPaneTaskGroup [MFC], m_bIsCollapsed", "CMFCTasksPaneTaskGroup [MFC], m_bIsSpecial", "CMFCTasksPaneTaskGroup [MFC], m_lstTasks", "CMFCTasksPaneTaskGroup [MFC], m_rect", "CMFCTasksPaneTaskGroup [MFC], m_rectGroup", "CMFCTasksPaneTaskGroup [MFC], m_strName"] -ms.assetid: 2111640b-a46e-4b27-b033-29e88632b86a --- # CMFCTasksPaneTaskGroup Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCTasksPaneTaskGroup` class is a helper class used by the [CMFCTasksPane](../../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. ## Syntax diff --git a/docs/mfc/reference/cmfctoolbar-class.md b/docs/mfc/reference/cmfctoolbar-class.md index 236254137a2..a921bc1033d 100644 --- a/docs/mfc/reference/cmfctoolbar-class.md +++ b/docs/mfc/reference/cmfctoolbar-class.md @@ -1,12 +1,15 @@ --- -description: "Learn more about: CMFCToolBar Class" title: "CMFCToolBar Class" -ms.date: "11/04/2016" +description: "Learn more about: CMFCToolBar Class" +ms.date: 11/04/2016 f1_keywords: ["CMFCToolBar", "AFXTOOLBAR/CMFCToolBar", "AFXTOOLBAR/CMFCToolBar::AddBasicCommand", "AFXTOOLBAR/CMFCToolBar::AddCommandUsage", "AFXTOOLBAR/CMFCToolBar::AddToolBarForImageCollection", "AFXTOOLBAR/CMFCToolBar::AdjustLayout", "AFXTOOLBAR/CMFCToolBar::AdjustSize", "AFXTOOLBAR/CMFCToolBar::AllowChangeTextLabels", "AFXTOOLBAR/CMFCToolBar::AreTextLabels", "AFXTOOLBAR/CMFCToolBar::AutoGrayInactiveImages", "AFXTOOLBAR/CMFCToolBar::ButtonToIndex", "AFXTOOLBAR/CMFCToolBar::CalcFixedLayout", "AFXTOOLBAR/CMFCToolBar::CalcSize", "AFXTOOLBAR/CMFCToolBar::CanHandleSiblings", "AFXTOOLBAR/CMFCToolBar::CleanUpImages", "AFXTOOLBAR/CMFCToolBar::CleanUpLockedImages", "AFXTOOLBAR/CMFCToolBar::CanBeClosed", "AFXTOOLBAR/CMFCToolBar::CanBeRestored", "AFXTOOLBAR/CMFCToolBar::CanFocus", "AFXTOOLBAR/CMFCToolBar::CommandToIndex", "AFXTOOLBAR/CMFCToolBar::Create", "AFXTOOLBAR/CMFCToolBar::CreateEx", "AFXTOOLBAR/CMFCToolBar::Deactivate", "AFXTOOLBAR/CMFCToolBar::EnableCustomizeButton", "AFXTOOLBAR/CMFCToolBar::EnableDocking", "AFXTOOLBAR/CMFCToolBar::EnableLargeIcons", "AFXTOOLBAR/CMFCToolBar::EnableQuickCustomization", "AFXTOOLBAR/CMFCToolBar::EnableReflections", "AFXTOOLBAR/CMFCToolBar::EnableTextLabels", "AFXTOOLBAR/CMFCToolBar::FromHandlePermanent", "AFXTOOLBAR/CMFCToolBar::GetAllButtons", "AFXTOOLBAR/CMFCToolBar::GetAllToolbars", "AFXTOOLBAR/CMFCToolBar::GetBasicCommands", "AFXTOOLBAR/CMFCToolBar::GetButton", "AFXTOOLBAR/CMFCToolBar::GetButtonInfo", "AFXTOOLBAR/CMFCToolBar::GetButtonSize", "AFXTOOLBAR/CMFCToolBar::GetButtonStyle", "AFXTOOLBAR/CMFCToolBar::GetButtonText", "AFXTOOLBAR/CMFCToolBar::GetColdImages", "AFXTOOLBAR/CMFCToolBar::GetColumnWidth", "AFXTOOLBAR/CMFCToolBar::GetCommandButtons", "AFXTOOLBAR/CMFCToolBar::GetCount", "AFXTOOLBAR/CMFCToolBar::GetCustomizeButton", "AFXTOOLBAR/CMFCToolBar::GetDefaultImage", "AFXTOOLBAR/CMFCToolBar::GetDisabledImages", "AFXTOOLBAR/CMFCToolBar::GetDisabledMenuImages", "AFXTOOLBAR/CMFCToolBar::GetDroppedDownMenu", "AFXTOOLBAR/CMFCToolBar::GetGrayDisabledButtons", "AFXTOOLBAR/CMFCToolBar::GetHighlightedButton", "AFXTOOLBAR/CMFCToolBar::GetHotBorder", "AFXTOOLBAR/CMFCToolBar::GetHotTextColor", "AFXTOOLBAR/CMFCToolBar::GetHwndLastFocus", "AFXTOOLBAR/CMFCToolBar::GetOVERWRITESetText", "AFXTOOLBAR/CMFCToolBar::GetImageSize", "AFXTOOLBAR/CMFCToolBar::GetImages", "AFXTOOLBAR/CMFCToolBar::GetImagesOffset", "AFXTOOLBAR/CMFCToolBar::GetInvalidateItemRect", "AFXTOOLBAR/CMFCToolBar::GetItemID", "AFXTOOLBAR/CMFCToolBar::GetItemRect", "AFXTOOLBAR/CMFCToolBar::GetLargeColdImages", "AFXTOOLBAR/CMFCToolBar::GetLargeDisabledImages", "AFXTOOLBAR/CMFCToolBar::GetLargeImages", "AFXTOOLBAR/CMFCToolBar::GetLockedColdImages", "AFXTOOLBAR/CMFCToolBar::GetLockedDisabledImages", "AFXTOOLBAR/CMFCToolBar::GetLockedImages", "AFXTOOLBAR/CMFCToolBar::GetLockedImageSize", "AFXTOOLBAR/CMFCToolBar::GetLockedMenuImages", "AFXTOOLBAR/CMFCToolBar::GetMenuButtonSize", "AFXTOOLBAR/CMFCToolBar::GetMenuImageSize", "AFXTOOLBAR/CMFCToolBar::GetMenuImages", "AFXTOOLBAR/CMFCToolBar::GetOrigButtons", "AFXTOOLBAR/CMFCToolBar::GetOrigResetButtons", "AFXTOOLBAR/CMFCToolBar::GetResourceID", "AFXTOOLBAR/CMFCToolBar::GetRouteCommandsViaFrame", "AFXTOOLBAR/CMFCToolBar::GetRowHeight", "AFXTOOLBAR/CMFCToolBar::GetShowTooltips", "AFXTOOLBAR/CMFCToolBar::GetSiblingToolBar", "AFXTOOLBAR/CMFCToolBar::GetUserImages", "AFXTOOLBAR/CMFCToolBar::HitTest", "AFXTOOLBAR/CMFCToolBar::InsertButton", "AFXTOOLBAR/CMFCToolBar::InsertSeparator", "AFXTOOLBAR/CMFCToolBar::InvalidateButton", "AFXTOOLBAR/CMFCToolBar::IsAddRemoveQuickCustomize", "AFXTOOLBAR/CMFCToolBar::IsAltCustomizeMode", "AFXTOOLBAR/CMFCToolBar::IsAutoGrayInactiveImages", "AFXTOOLBAR/CMFCToolBar::IsBasicCommand", "AFXTOOLBAR/CMFCToolBar::IsButtonExtraSizeAvailable", "AFXTOOLBAR/CMFCToolBar::IsButtonHighlighted", "AFXTOOLBAR/CMFCToolBar::IsCommandPermitted", "AFXTOOLBAR/CMFCToolBar::IsCommandRarelyUsed", "AFXTOOLBAR/CMFCToolBar::IsCustomizeMode", "AFXTOOLBAR/CMFCToolBar::IsDragButton", "AFXTOOLBAR/CMFCToolBar::IsExistCustomizeButton", "AFXTOOLBAR/CMFCToolBar::IsFloating", "AFXTOOLBAR/CMFCToolBar::IsLargeIcons", "AFXTOOLBAR/CMFCToolBar::IsLastCommandFromButton", "AFXTOOLBAR/CMFCToolBar::IsLocked", "AFXTOOLBAR/CMFCToolBar::IsOneRowWithSibling", "AFXTOOLBAR/CMFCToolBar::IsUserDefined", "AFXTOOLBAR/CMFCToolBar::LoadBitmap", "AFXTOOLBAR/CMFCToolBar::LoadBitmapEx", "AFXTOOLBAR/CMFCToolBar::LoadParameters", "AFXTOOLBAR/CMFCToolBar::LoadState", "AFXTOOLBAR/CMFCToolBar::LoadToolBar", "AFXTOOLBAR/CMFCToolBar::LoadToolBarEx", "AFXTOOLBAR/CMFCToolBar::OnChangeHot", "AFXTOOLBAR/CMFCToolBar::OnFillBackground", "AFXTOOLBAR/CMFCToolBar::OnReset", "AFXTOOLBAR/CMFCToolBar::OnSetAccData", "AFXTOOLBAR/CMFCToolBar::OnSetDefaultButtonText", "AFXTOOLBAR/CMFCToolBar::RemoveAllButtons", "AFXTOOLBAR/CMFCToolBar::RemoveButton", "AFXTOOLBAR/CMFCToolBar::RemoveStateFromRegistry", "AFXTOOLBAR/CMFCToolBar::ReplaceButton", "AFXTOOLBAR/CMFCToolBar::ResetAll", "AFXTOOLBAR/CMFCToolBar::ResetAllImages", "AFXTOOLBAR/CMFCToolBar::RestoreOriginalState", "AFXTOOLBAR/CMFCToolBar::SaveState", "AFXTOOLBAR/CMFCToolBar::SetBasicCommands", "AFXTOOLBAR/CMFCToolBar::SetButtonInfo", "AFXTOOLBAR/CMFCToolBar::SetButtonStyle", "AFXTOOLBAR/CMFCToolBar::SetButtonText", "AFXTOOLBAR/CMFCToolBar::SetButtons", "AFXTOOLBAR/CMFCToolBar::SetCommandUsageOptions", "AFXTOOLBAR/CMFCToolBar::SetCustomizeMode", "AFXTOOLBAR/CMFCToolBar::SetGrayDisabledButtons", "AFXTOOLBAR/CMFCToolBar::SetHeight", "AFXTOOLBAR/CMFCToolBar::SetHotBorder", "AFXTOOLBAR/CMFCToolBar::SetHotTextColor", "AFXTOOLBAR/CMFCToolBar::SetLargeIcons", "AFXTOOLBAR/CMFCToolBar::SetLockedSizes", "AFXTOOLBAR/CMFCToolBar::SetMenuSizes", "AFXTOOLBAR/CMFCToolBar::SetNonPermittedCommands", "AFXTOOLBAR/CMFCToolBar::SetOneRowWithSibling", "AFXTOOLBAR/CMFCToolBar::SetPermament", "AFXTOOLBAR/CMFCToolBar::SetRouteCommandsViaFrame", "AFXTOOLBAR/CMFCToolBar::SetShowTooltips", "AFXTOOLBAR/CMFCToolBar::SetSiblingToolBar", "AFXTOOLBAR/CMFCToolBar::SetSizes", "AFXTOOLBAR/CMFCToolBar::SetToolBarBtnText", "AFXTOOLBAR/CMFCToolBar::SetTwoRowsWithSibling", "AFXTOOLBAR/CMFCToolBar::SetUserImages", "AFXTOOLBAR/CMFCToolBar::StretchPane", "AFXTOOLBAR/CMFCToolBar::TranslateChar", "AFXTOOLBAR/CMFCToolBar::UpdateButton", "AFXTOOLBAR/CMFCToolBar::WrapToolBar", "AFXTOOLBAR/CMFCToolBar::AllowShowOnList", "AFXTOOLBAR/CMFCToolBar::CalcMaxButtonHeight", "AFXTOOLBAR/CMFCToolBar::DoPaint", "AFXTOOLBAR/CMFCToolBar::DrawButton", "AFXTOOLBAR/CMFCToolBar::DrawSeparator", "AFXTOOLBAR/CMFCToolBar::OnUserToolTip", "AFXTOOLBAR/CMFCToolBar::m_bDontScaleImages", "AFXTOOLBAR/CMFCToolBar::m_dblLargeImageRatio"] helpviewer_keywords: ["CMFCToolBar [MFC], AddBasicCommand", "CMFCToolBar [MFC], AddCommandUsage", "CMFCToolBar [MFC], AddToolBarForImageCollection", "CMFCToolBar [MFC], AdjustLayout", "CMFCToolBar [MFC], AdjustSize", "CMFCToolBar [MFC], AllowChangeTextLabels", "CMFCToolBar [MFC], AreTextLabels", "CMFCToolBar [MFC], AutoGrayInactiveImages", "CMFCToolBar [MFC], ButtonToIndex", "CMFCToolBar [MFC], CalcFixedLayout", "CMFCToolBar [MFC], CalcSize", "CMFCToolBar [MFC], CanHandleSiblings", "CMFCToolBar [MFC], CleanUpImages", "CMFCToolBar [MFC], CleanUpLockedImages", "CMFCToolBar [MFC], CanBeClosed", "CMFCToolBar [MFC], CanBeRestored", "CMFCToolBar [MFC], CanFocus", "CMFCToolBar [MFC], CanHandleSiblings", "CMFCToolBar [MFC], CommandToIndex", "CMFCToolBar [MFC], Create", "CMFCToolBar [MFC], CreateEx", "CMFCToolBar [MFC], Deactivate", "CMFCToolBar [MFC], EnableCustomizeButton", "CMFCToolBar [MFC], EnableDocking", "CMFCToolBar [MFC], EnableLargeIcons", "CMFCToolBar [MFC], EnableQuickCustomization", "CMFCToolBar [MFC], EnableReflections", "CMFCToolBar [MFC], EnableTextLabels", "CMFCToolBar [MFC], FromHandlePermanent", "CMFCToolBar [MFC], GetAllButtons", "CMFCToolBar [MFC], GetAllToolbars", "CMFCToolBar [MFC], GetBasicCommands", "CMFCToolBar [MFC], GetButton", "CMFCToolBar [MFC], GetButtonInfo", "CMFCToolBar [MFC], GetButtonSize", "CMFCToolBar [MFC], GetButtonStyle", "CMFCToolBar [MFC], GetButtonText", "CMFCToolBar [MFC], GetColdImages", "CMFCToolBar [MFC], GetColumnWidth", "CMFCToolBar [MFC], GetCommandButtons", "CMFCToolBar [MFC], GetCount", "CMFCToolBar [MFC], GetCustomizeButton", "CMFCToolBar [MFC], GetDefaultImage", "CMFCToolBar [MFC], GetDisabledImages", "CMFCToolBar [MFC], GetDisabledMenuImages", "CMFCToolBar [MFC], GetDroppedDownMenu", "CMFCToolBar [MFC], GetGrayDisabledButtons", "CMFCToolBar [MFC], GetHighlightedButton", "CMFCToolBar [MFC], GetHotBorder", "CMFCToolBar [MFC], GetHotTextColor", "CMFCToolBar [MFC], GetHwndLastFocus", "CMFCToolBar [MFC], GetIgnoreSetText", "CMFCToolBar [MFC], GetImageSize", "CMFCToolBar [MFC], GetImages", "CMFCToolBar [MFC], GetImagesOffset", "CMFCToolBar [MFC], GetInvalidateItemRect", "CMFCToolBar [MFC], GetItemID", "CMFCToolBar [MFC], GetItemRect", "CMFCToolBar [MFC], GetLargeColdImages", "CMFCToolBar [MFC], GetLargeDisabledImages", "CMFCToolBar [MFC], GetLargeImages", "CMFCToolBar [MFC], GetLockedColdImages", "CMFCToolBar [MFC], GetLockedDisabledImages", "CMFCToolBar [MFC], GetLockedImages", "CMFCToolBar [MFC], GetLockedImageSize", "CMFCToolBar [MFC], GetLockedMenuImages", "CMFCToolBar [MFC], GetMenuButtonSize", "CMFCToolBar [MFC], GetMenuImageSize", "CMFCToolBar [MFC], GetMenuImages", "CMFCToolBar [MFC], GetOrigButtons", "CMFCToolBar [MFC], GetOrigResetButtons", "CMFCToolBar [MFC], GetResourceID", "CMFCToolBar [MFC], GetRouteCommandsViaFrame", "CMFCToolBar [MFC], GetRowHeight", "CMFCToolBar [MFC], GetShowTooltips", "CMFCToolBar [MFC], GetSiblingToolBar", "CMFCToolBar [MFC], GetUserImages", "CMFCToolBar [MFC], HitTest", "CMFCToolBar [MFC], InsertButton", "CMFCToolBar [MFC], InsertSeparator", "CMFCToolBar [MFC], InvalidateButton", "CMFCToolBar [MFC], IsAddRemoveQuickCustomize", "CMFCToolBar [MFC], IsAltCustomizeMode", "CMFCToolBar [MFC], IsAutoGrayInactiveImages", "CMFCToolBar [MFC], IsBasicCommand", "CMFCToolBar [MFC], IsButtonExtraSizeAvailable", "CMFCToolBar [MFC], IsButtonHighlighted", "CMFCToolBar [MFC], IsCommandPermitted", "CMFCToolBar [MFC], IsCommandRarelyUsed", "CMFCToolBar [MFC], IsCustomizeMode", "CMFCToolBar [MFC], IsDragButton", "CMFCToolBar [MFC], IsExistCustomizeButton", "CMFCToolBar [MFC], IsFloating", "CMFCToolBar [MFC], IsLargeIcons", "CMFCToolBar [MFC], IsLastCommandFromButton", "CMFCToolBar [MFC], IsLocked", "CMFCToolBar [MFC], IsOneRowWithSibling", "CMFCToolBar [MFC], IsUserDefined", "CMFCToolBar [MFC], LoadBitmap", "CMFCToolBar [MFC], LoadBitmapEx", "CMFCToolBar [MFC], LoadParameters", "CMFCToolBar [MFC], LoadState", "CMFCToolBar [MFC], LoadToolBar", "CMFCToolBar [MFC], LoadToolBarEx", "CMFCToolBar [MFC], OnChangeHot", "CMFCToolBar [MFC], OnFillBackground", "CMFCToolBar [MFC], OnReset", "CMFCToolBar [MFC], OnSetAccData", "CMFCToolBar [MFC], OnSetDefaultButtonText", "CMFCToolBar [MFC], RemoveAllButtons", "CMFCToolBar [MFC], RemoveButton", "CMFCToolBar [MFC], RemoveStateFromRegistry", "CMFCToolBar [MFC], ReplaceButton", "CMFCToolBar [MFC], ResetAll", "CMFCToolBar [MFC], ResetAllImages", "CMFCToolBar [MFC], RestoreOriginalState", "CMFCToolBar [MFC], SaveState", "CMFCToolBar [MFC], SetBasicCommands", "CMFCToolBar [MFC], SetButtonInfo", "CMFCToolBar [MFC], SetButtonStyle", "CMFCToolBar [MFC], SetButtonText", "CMFCToolBar [MFC], SetButtons", "CMFCToolBar [MFC], SetCommandUsageOptions", "CMFCToolBar [MFC], SetCustomizeMode", "CMFCToolBar [MFC], SetGrayDisabledButtons", "CMFCToolBar [MFC], SetHeight", "CMFCToolBar [MFC], SetHotBorder", "CMFCToolBar [MFC], SetHotTextColor", "CMFCToolBar [MFC], SetLargeIcons", "CMFCToolBar [MFC], SetLockedSizes", "CMFCToolBar [MFC], SetMenuSizes", "CMFCToolBar [MFC], SetNonPermittedCommands", "CMFCToolBar [MFC], SetOneRowWithSibling", "CMFCToolBar [MFC], SetPermament", "CMFCToolBar [MFC], SetRouteCommandsViaFrame", "CMFCToolBar [MFC], SetShowTooltips", "CMFCToolBar [MFC], SetSiblingToolBar", "CMFCToolBar [MFC], SetSizes", "CMFCToolBar [MFC], SetToolBarBtnText", "CMFCToolBar [MFC], SetTwoRowsWithSibling", "CMFCToolBar [MFC], SetUserImages", "CMFCToolBar [MFC], StretchPane", "CMFCToolBar [MFC], TranslateChar", "CMFCToolBar [MFC], UpdateButton", "CMFCToolBar [MFC], WrapToolBar", "CMFCToolBar [MFC], AllowShowOnList", "CMFCToolBar [MFC], CalcMaxButtonHeight", "CMFCToolBar [MFC], DoPaint", "CMFCToolBar [MFC], DrawButton", "CMFCToolBar [MFC], DrawSeparator", "CMFCToolBar [MFC], OnUserToolTip", "CMFCToolBar [MFC], m_bDontScaleImages", "CMFCToolBar [MFC], m_dblLargeImageRatio"] --- # `CMFCToolBar` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCToolBar` class resembles [`CToolBar` Class](../../mfc/reference/ctoolbar-class.md), but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The `CMFCToolBar` class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons. For more detail, see the source code located in your Visual Studio installation, for example, `%ProgramFiles(x86)%\Microsoft Visual Studio\2019\Enterprise\VC\Tools\MSVC\14.29.30133\atlmfc\src\mfc`. @@ -47,7 +50,6 @@ class CMFCToolBar : public CMFCBaseToolBar |[`CMFCToolBar::CanBeClosed`](#canbeclosed)|Specifies whether a user can close the toolbar. (Overrides [`CBasePane::CanBeClosed`](../../mfc/reference/cbasepane-class.md#canbeclosed).)| |[`CMFCToolBar::CanBeRestored`](#canberestored)|Determines whether the system can restore a toolbar to its original state after customization.| |[`CMFCToolBar::CanFocus`](#canfocus)|Specifies whether the pane can receive focus. (Overrides [`CBasePane::CanFocus`](../../mfc/reference/cbasepane-class.md#canfocus).)| -|[`CMFCToolBar::CanHandleSiblings`](#canhandlesiblings)|Determines whether the toolbar and its sibling are positioned on the same pane.| |[`CMFCToolBar::CommandToIndex`](#commandtoindex)|Returns the index of the button in the toolbar with a specified command ID.| |[`CMFCToolBar::Create`](#create)|Creates a `CMFCToolBar` object.| |[`CMFCToolBar::CreateEx`](#createex)|Creates a `CMFCToolBar` object that uses additional style options, such as large icons.| @@ -2303,7 +2305,7 @@ virtual BOOL LoadBitmapEx( ### Parameters [in] *`params`*\ -[in] *`bLocked`*\ +[in] *`bLocked`* ### Return Value @@ -2317,7 +2319,7 @@ static BOOL __stdcall LoadLargeIconsState(LPCTSTR lpszProfileName = NULL); ### Parameters -[in] *`lpszProfileName`*\ +[in] *`lpszProfileName`* ### Return Value @@ -2577,7 +2579,7 @@ virtual BOOL OnSetAccData(long lVal); ### Parameters -[in] *`lVal`*\ +[in] *`lVal`* ### Return Value @@ -2837,7 +2839,7 @@ static BOOL __stdcall SaveParameters(LPCTSTR lpszProfileName = NULL); ### Parameters -[in] *`lpszProfileName`*\ +[in] *`lpszProfileName`* ### Return Value @@ -3099,7 +3101,7 @@ static void __stdcall SetHelpMode(BOOL bOn = TRUE); ### Parameters -[in] *`bOn`*\ +[in] *`bOn`* ### Remarks @@ -3111,7 +3113,7 @@ BOOL SetHot(CMFCToolBarButton* pMenuButton); ### Parameters -[in] *`pMenuButton`*\ +[in] *`pMenuButton`* ### Return Value @@ -3161,7 +3163,7 @@ void SetIgnoreSetText(BOOL bValue); ### Parameters -[in] *`bValue`*\ +[in] *`bValue`* ### Remarks @@ -3222,7 +3224,7 @@ void SetMaskMode(BOOL bMasked); ### Parameters -[in] *`bMasked`*\ +[in] *`bMasked`* ### Remarks @@ -3295,7 +3297,7 @@ void SetOrigButtons(const CObList& lstOrigButtons); ### Parameters -[in] *`lstOrigButtons`*\ +[in] *`lstOrigButtons`* ### Remarks @@ -3472,7 +3474,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/cmfctoolbarbutton-class.md b/docs/mfc/reference/cmfctoolbarbutton-class.md index dd3933b89bc..7c6d4005c6c 100644 --- a/docs/mfc/reference/cmfctoolbarbutton-class.md +++ b/docs/mfc/reference/cmfctoolbarbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarButton", "AFXTOOLBARBUTTON/CMFCToolBarButton", "AFXTOOLBARBUTTON/CMFCToolBarButton::CMFCToolBarButton", "AFXTOOLBARBUTTON/CMFCToolBarButton::CanBeDropped", "AFXTOOLBARBUTTON/CMFCToolBarButton::CanBeStored", "AFXTOOLBARBUTTON/CMFCToolBarButton::CanBeStretched", "AFXTOOLBARBUTTON/CMFCToolBarButton::CompareWith", "AFXTOOLBARBUTTON/CMFCToolBarButton::CopyFrom", "AFXTOOLBARBUTTON/CMFCToolBarButton::CreateFromOleData", "AFXTOOLBARBUTTON/CMFCToolBarButton::EnableWindow", "AFXTOOLBARBUTTON/CMFCToolBarButton::ExportToMenuButton", "AFXTOOLBARBUTTON/CMFCToolBarButton::GetClipboardFormat", "AFXTOOLBARBUTTON/CMFCToolBarButton::GetHwnd", "AFXTOOLBARBUTTON/CMFCToolBarButton::GetImage", "AFXTOOLBARBUTTON/CMFCToolBarButton::GetInvalidateRect", "AFXTOOLBARBUTTON/CMFCToolBarButton::GetParentWnd", "AFXTOOLBARBUTTON/CMFCToolBarButton::GetProtectedCommands", "AFXTOOLBARBUTTON/CMFCToolBarButton::GetTextSize", "AFXTOOLBARBUTTON/CMFCToolBarButton::HasFocus", "AFXTOOLBARBUTTON/CMFCToolBarButton::HaveHotBorder", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsDrawImage", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsDrawText", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsDroppedDown", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsEditable", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsExtraSize", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsFirstInGroup", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsHidden", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsHorizontal", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsLastInGroup", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsLocked", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsOwnerOf", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsVisible", "AFXTOOLBARBUTTON/CMFCToolBarButton::IsWindowVisible", "AFXTOOLBARBUTTON/CMFCToolBarButton::NotifyCommand", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnAddToCustomizePage", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnBeforeDrag", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnBeforeDrop", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnCalculateSize", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnCancelMode", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnChangeParentWnd", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnClick", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnClickUp", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnContextHelp", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnCtlColor", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnCustomizeMenu", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnDblClk", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnDraw", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnDrawOnCustomizeList", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnGetCustomToolTipText", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnGlobalFontsChanged", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnMove", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnShow", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnSize", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnToolHitTest", "AFXTOOLBARBUTTON/CMFCToolBarButton::OnUpdateToolTip", "AFXTOOLBARBUTTON/CMFCToolBarButton::PrepareDrag", "AFXTOOLBARBUTTON/CMFCToolBarButton::Rect", "AFXTOOLBARBUTTON/CMFCToolBarButton::ResetImageToDefault", "AFXTOOLBARBUTTON/CMFCToolBarButton::SaveBarState", "AFXTOOLBARBUTTON/CMFCToolBarButton::Serialize", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetACCData", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetClipboardFormatName", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetImage", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetProtectedCommands", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetRadio", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetRect", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetStyle", "AFXTOOLBARBUTTON/CMFCToolBarButton::SetVisible", "AFXTOOLBARBUTTON/CMFCToolBarButton::Show", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_bImage", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_bText", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_bTextBelow", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_bUserButton", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_bWholeText", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_bWrap", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_bWrapText", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_nID", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_nStyle", "AFXTOOLBARBUTTON/CMFCToolBarButton::m_strText"] helpviewer_keywords: ["CMFCToolBarButton [MFC], CMFCToolBarButton", "CMFCToolBarButton [MFC], CanBeDropped", "CMFCToolBarButton [MFC], CanBeStored", "CMFCToolBarButton [MFC], CanBeStretched", "CMFCToolBarButton [MFC], CompareWith", "CMFCToolBarButton [MFC], CopyFrom", "CMFCToolBarButton [MFC], CreateFromOleData", "CMFCToolBarButton [MFC], EnableWindow", "CMFCToolBarButton [MFC], ExportToMenuButton", "CMFCToolBarButton [MFC], GetClipboardFormat", "CMFCToolBarButton [MFC], GetHwnd", "CMFCToolBarButton [MFC], GetImage", "CMFCToolBarButton [MFC], GetInvalidateRect", "CMFCToolBarButton [MFC], GetParentWnd", "CMFCToolBarButton [MFC], GetProtectedCommands", "CMFCToolBarButton [MFC], GetTextSize", "CMFCToolBarButton [MFC], HasFocus", "CMFCToolBarButton [MFC], HaveHotBorder", "CMFCToolBarButton [MFC], IsDrawImage", "CMFCToolBarButton [MFC], IsDrawText", "CMFCToolBarButton [MFC], IsDroppedDown", "CMFCToolBarButton [MFC], IsEditable", "CMFCToolBarButton [MFC], IsExtraSize", "CMFCToolBarButton [MFC], IsFirstInGroup", "CMFCToolBarButton [MFC], IsHidden", "CMFCToolBarButton [MFC], IsHorizontal", "CMFCToolBarButton [MFC], IsLastInGroup", "CMFCToolBarButton [MFC], IsLocked", "CMFCToolBarButton [MFC], IsOwnerOf", "CMFCToolBarButton [MFC], IsVisible", "CMFCToolBarButton [MFC], IsWindowVisible", "CMFCToolBarButton [MFC], NotifyCommand", "CMFCToolBarButton [MFC], OnAddToCustomizePage", "CMFCToolBarButton [MFC], OnBeforeDrag", "CMFCToolBarButton [MFC], OnBeforeDrop", "CMFCToolBarButton [MFC], OnCalculateSize", "CMFCToolBarButton [MFC], OnCancelMode", "CMFCToolBarButton [MFC], OnChangeParentWnd", "CMFCToolBarButton [MFC], OnClick", "CMFCToolBarButton [MFC], OnClickUp", "CMFCToolBarButton [MFC], OnContextHelp", "CMFCToolBarButton [MFC], OnCtlColor", "CMFCToolBarButton [MFC], OnCustomizeMenu", "CMFCToolBarButton [MFC], OnDblClk", "CMFCToolBarButton [MFC], OnDraw", "CMFCToolBarButton [MFC], OnDrawOnCustomizeList", "CMFCToolBarButton [MFC], OnGetCustomToolTipText", "CMFCToolBarButton [MFC], OnGlobalFontsChanged", "CMFCToolBarButton [MFC], OnMove", "CMFCToolBarButton [MFC], OnShow", "CMFCToolBarButton [MFC], OnSize", "CMFCToolBarButton [MFC], OnToolHitTest", "CMFCToolBarButton [MFC], OnUpdateToolTip", "CMFCToolBarButton [MFC], PrepareDrag", "CMFCToolBarButton [MFC], Rect", "CMFCToolBarButton [MFC], ResetImageToDefault", "CMFCToolBarButton [MFC], SaveBarState", "CMFCToolBarButton [MFC], Serialize", "CMFCToolBarButton [MFC], SetACCData", "CMFCToolBarButton [MFC], SetClipboardFormatName", "CMFCToolBarButton [MFC], SetImage", "CMFCToolBarButton [MFC], SetProtectedCommands", "CMFCToolBarButton [MFC], SetRadio", "CMFCToolBarButton [MFC], SetRect", "CMFCToolBarButton [MFC], SetStyle", "CMFCToolBarButton [MFC], SetVisible", "CMFCToolBarButton [MFC], Show", "CMFCToolBarButton [MFC], m_bImage", "CMFCToolBarButton [MFC], m_bText", "CMFCToolBarButton [MFC], m_bTextBelow", "CMFCToolBarButton [MFC], m_bUserButton", "CMFCToolBarButton [MFC], m_bWholeText", "CMFCToolBarButton [MFC], m_bWrap", "CMFCToolBarButton [MFC], m_bWrapText", "CMFCToolBarButton [MFC], m_nID", "CMFCToolBarButton [MFC], m_nStyle", "CMFCToolBarButton [MFC], m_strText"] -ms.assetid: 8a6ecffb-86b0-4f5c-8211-a9146b463efd --- # CMFCToolBarButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides button functionality to toolbars. ## Syntax diff --git a/docs/mfc/reference/cmfctoolbarcomboboxbutton-class.md b/docs/mfc/reference/cmfctoolbarcomboboxbutton-class.md index 33ad04efef8..90ef5256171 100644 --- a/docs/mfc/reference/cmfctoolbarcomboboxbutton-class.md +++ b/docs/mfc/reference/cmfctoolbarcomboboxbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarComboBoxButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarComboBoxButton", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::CMFCToolBarComboBoxButton", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::AddItem", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::AddSortedItem", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::Compare", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::CreateEdit", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::DeleteItem", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::FindItem", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetByCmd", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetComboBox", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetCount", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetCountAll", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetCurSel", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetCurSelAll", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetEditCtrl", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetItem", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetItemAll", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetItemData", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetItemDataAll", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetItemDataPtrAll", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetText", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::GetTextAll", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::IsCenterVert", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::IsFlatMode", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::RemoveAllItems", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::SelectItem", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::SelectItemAll", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::SetCenterVert", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::SetDropDownHeight", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxButton::SetFlatMode"] helpviewer_keywords: ["CMFCToolBarComboBoxButton [MFC], CMFCToolBarComboBoxButton", "CMFCToolBarComboBoxButton [MFC], AddItem", "CMFCToolBarComboBoxButton [MFC], AddSortedItem", "CMFCToolBarComboBoxButton [MFC], Compare", "CMFCToolBarComboBoxButton [MFC], CreateEdit", "CMFCToolBarComboBoxButton [MFC], DeleteItem", "CMFCToolBarComboBoxButton [MFC], FindItem", "CMFCToolBarComboBoxButton [MFC], GetByCmd", "CMFCToolBarComboBoxButton [MFC], GetComboBox", "CMFCToolBarComboBoxButton [MFC], GetCount", "CMFCToolBarComboBoxButton [MFC], GetCountAll", "CMFCToolBarComboBoxButton [MFC], GetCurSel", "CMFCToolBarComboBoxButton [MFC], GetCurSelAll", "CMFCToolBarComboBoxButton [MFC], GetEditCtrl", "CMFCToolBarComboBoxButton [MFC], GetItem", "CMFCToolBarComboBoxButton [MFC], GetItemAll", "CMFCToolBarComboBoxButton [MFC], GetItemData", "CMFCToolBarComboBoxButton [MFC], GetItemDataAll", "CMFCToolBarComboBoxButton [MFC], GetItemDataPtrAll", "CMFCToolBarComboBoxButton [MFC], GetText", "CMFCToolBarComboBoxButton [MFC], GetTextAll", "CMFCToolBarComboBoxButton [MFC], IsCenterVert", "CMFCToolBarComboBoxButton [MFC], IsFlatMode", "CMFCToolBarComboBoxButton [MFC], RemoveAllItems", "CMFCToolBarComboBoxButton [MFC], SelectItem", "CMFCToolBarComboBoxButton [MFC], SelectItemAll", "CMFCToolBarComboBoxButton [MFC], SetCenterVert", "CMFCToolBarComboBoxButton [MFC], SetDropDownHeight", "CMFCToolBarComboBoxButton [MFC], SetFlatMode"] -ms.assetid: 32fa39f7-8e4e-4f0a-a31d-7b540d969a6c --- # CMFCToolBarComboBoxButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar button that contains a combo box control ( [CComboBox Class](../../mfc/reference/ccombobox-class.md)). ## Syntax diff --git a/docs/mfc/reference/cmfctoolbarcomboboxedit-class.md b/docs/mfc/reference/cmfctoolbarcomboboxedit-class.md index d3268930335..e967144ef94 100644 --- a/docs/mfc/reference/cmfctoolbarcomboboxedit-class.md +++ b/docs/mfc/reference/cmfctoolbarcomboboxedit-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarComboBoxEdit Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarComboBoxEdit", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxEdit", "AFXTOOLBARCOMBOBOXBUTTON/CMFCToolBarComboBoxEdit::CMFCToolBarComboBoxEdit"] helpviewer_keywords: ["CMFCToolBarComboBoxEdit [MFC], CMFCToolBarComboBoxEdit"] -ms.assetid: 4789c34a-ce58-48ba-a26f-38748b601352 --- # CMFCToolBarComboBoxEdit Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The framework uses the `CMFCToolBarComboBoxEdit` class to create a toolbar button that behaves like an editable combo box control. ## Syntax diff --git a/docs/mfc/reference/cmfctoolbardatetimectrl-class.md b/docs/mfc/reference/cmfctoolbardatetimectrl-class.md index 367cba596e9..8e6ff7c4dea 100644 --- a/docs/mfc/reference/cmfctoolbardatetimectrl-class.md +++ b/docs/mfc/reference/cmfctoolbardatetimectrl-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarDateTimeCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarDateTimeCtrl", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::CMFCToolBarDateTimeCtrl", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::CanBeStretched", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::CopyFrom", "AFXTOOLBARDATETIMECTRL/CMFCToolBarButton::ExportToMenuButton", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::GetByCmd", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::GetDateTimeCtrl", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::GetHwnd", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::GetTime", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::GetTimeAll", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::HaveHotBorder", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::NotifyCommand", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnAddToCustomizePage", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnChangeParentWnd", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnClick", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnCtlColor", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnGlobalFontsChanged", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnMove", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnShow", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::OnUpdateToolTip", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::SetTime", "AFXTOOLBARDATETIMECTRL/CMFCToolBarDateTimeCtrl::SetTimeAll"] helpviewer_keywords: ["CMFCToolBarDateTimeCtrl [MFC], CMFCToolBarDateTimeCtrl", "CMFCToolBarDateTimeCtrl [MFC], CanBeStretched", "CMFCToolBarDateTimeCtrl [MFC], CopyFrom", "CMFCToolBarButton [MFC], ExportToMenuButton", "CMFCToolBarDateTimeCtrl [MFC], GetByCmd", "CMFCToolBarDateTimeCtrl [MFC], GetDateTimeCtrl", "CMFCToolBarDateTimeCtrl [MFC], GetHwnd", "CMFCToolBarDateTimeCtrl [MFC], GetTime", "CMFCToolBarDateTimeCtrl [MFC], GetTimeAll", "CMFCToolBarDateTimeCtrl [MFC], HaveHotBorder", "CMFCToolBarDateTimeCtrl [MFC], NotifyCommand", "CMFCToolBarDateTimeCtrl [MFC], OnAddToCustomizePage", "CMFCToolBarDateTimeCtrl [MFC], OnChangeParentWnd", "CMFCToolBarDateTimeCtrl [MFC], OnClick", "CMFCToolBarDateTimeCtrl [MFC], OnCtlColor", "CMFCToolBarDateTimeCtrl [MFC], OnGlobalFontsChanged", "CMFCToolBarDateTimeCtrl [MFC], OnMove", "CMFCToolBarDateTimeCtrl [MFC], OnShow", "CMFCToolBarDateTimeCtrl [MFC], OnUpdateToolTip", "CMFCToolBarDateTimeCtrl [MFC], SetTime", "CMFCToolBarDateTimeCtrl [MFC], SetTimeAll"] -ms.assetid: a3853cb9-8ebc-444f-a1e4-9cf905e24c18 --- # CMFCToolBarDateTimeCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar button that contains a date and time picker control. ## Syntax diff --git a/docs/mfc/reference/cmfctoolbareditboxbutton-class.md b/docs/mfc/reference/cmfctoolbareditboxbutton-class.md index bd00650204d..3d2790f18f1 100644 --- a/docs/mfc/reference/cmfctoolbareditboxbutton-class.md +++ b/docs/mfc/reference/cmfctoolbareditboxbutton-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarEditBoxButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarEditBoxButton", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::CMFCToolBarEditBoxButton", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::CanBeStretched", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::CopyFrom", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::GetByCmd", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::GetContentsAll", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::GetContextMenuID", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::GetEditBorder", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::GetHwnd", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::GetInvalidateRect", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::HaveHotBorder", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::IsFlatMode", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::NotifyCommand", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnAddToCustomizePage", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnChangeParentWnd", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnClick", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnCtlColor", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnGlobalFontsChanged", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnMove", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnShow", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnSize", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::OnUpdateToolTip", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::SetContextMenuID", "AFXTOOLBAREDITBOXBUTTON/CMFCToolBarEditBoxButton::SetFlatMode"] helpviewer_keywords: ["CMFCToolBarEditBoxButton [MFC], CMFCToolBarEditBoxButton", "CMFCToolBarEditBoxButton [MFC], CanBeStretched", "CMFCToolBarEditBoxButton [MFC], CopyFrom", "CMFCToolBarEditBoxButton [MFC], GetByCmd", "CMFCToolBarEditBoxButton [MFC], GetContentsAll", "CMFCToolBarEditBoxButton [MFC], GetContextMenuID", "CMFCToolBarEditBoxButton [MFC], GetEditBorder", "CMFCToolBarEditBoxButton [MFC], GetHwnd", "CMFCToolBarEditBoxButton [MFC], GetInvalidateRect", "CMFCToolBarEditBoxButton [MFC], HaveHotBorder", "CMFCToolBarEditBoxButton [MFC], IsFlatMode", "CMFCToolBarEditBoxButton [MFC], NotifyCommand", "CMFCToolBarEditBoxButton [MFC], OnAddToCustomizePage", "CMFCToolBarEditBoxButton [MFC], OnChangeParentWnd", "CMFCToolBarEditBoxButton [MFC], OnClick", "CMFCToolBarEditBoxButton [MFC], OnCtlColor", "CMFCToolBarEditBoxButton [MFC], OnGlobalFontsChanged", "CMFCToolBarEditBoxButton [MFC], OnMove", "CMFCToolBarEditBoxButton [MFC], OnShow", "CMFCToolBarEditBoxButton [MFC], OnSize", "CMFCToolBarEditBoxButton [MFC], OnUpdateToolTip", "CMFCToolBarEditBoxButton [MFC], SetContextMenuID", "CMFCToolBarEditBoxButton [MFC], SetFlatMode"] -ms.assetid: b21d9b67-6bf7-4ca9-bd62-b237756e0ab3 --- # CMFCToolBarEditBoxButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar button that contains an edit control ( [CEdit Class](../../mfc/reference/cedit-class.md)). ## Syntax diff --git a/docs/mfc/reference/cmfctoolbarfontcombobox-class.md b/docs/mfc/reference/cmfctoolbarfontcombobox-class.md index 4c8e05d3ad6..965f04c370b 100644 --- a/docs/mfc/reference/cmfctoolbarfontcombobox-class.md +++ b/docs/mfc/reference/cmfctoolbarfontcombobox-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarFontComboBox Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarFontComboBox", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontComboBox", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontComboBox::CMFCToolBarFontComboBox", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontComboBox::GetFontDesc", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontComboBox::SetFont"] helpviewer_keywords: ["CMFCToolBarFontComboBox [MFC], CMFCToolBarFontComboBox", "CMFCToolBarFontComboBox [MFC], GetFontDesc", "CMFCToolBarFontComboBox [MFC], SetFont"] -ms.assetid: 25f8e08c-aadd-4cb5-9581-a99d49d444b1 --- # CMFCToolBarFontComboBox Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar button that contains a combo box control that enables the user to select a font from a list of system fonts. ## Syntax diff --git a/docs/mfc/reference/cmfctoolbarfontsizecombobox-class.md b/docs/mfc/reference/cmfctoolbarfontsizecombobox-class.md index 8bb1581813f..7314ab35ff8 100644 --- a/docs/mfc/reference/cmfctoolbarfontsizecombobox-class.md +++ b/docs/mfc/reference/cmfctoolbarfontsizecombobox-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarFontSizeComboBox Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarFontSizeComboBox", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontSizeComboBox", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontSizeComboBox::CMFCToolBarFontSizeComboBox", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontSizeComboBox::GetTwipSize", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontSizeComboBox::RebuildFontSizes", "AFXTOOLBARFONTCOMBOBOX/CMFCToolBarFontSizeComboBox::SetTwipSize"] helpviewer_keywords: ["CMFCToolBarFontSizeComboBox [MFC], CMFCToolBarFontSizeComboBox", "CMFCToolBarFontSizeComboBox [MFC], GetTwipSize", "CMFCToolBarFontSizeComboBox [MFC], RebuildFontSizes", "CMFCToolBarFontSizeComboBox [MFC], SetTwipSize"] -ms.assetid: 72e0c44c-6a0e-4194-a71f-ab64e3afb9b5 --- # CMFCToolBarFontSizeComboBox Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar button that contains a combo box control that enables the user to select a font size. ## Syntax diff --git a/docs/mfc/reference/cmfctoolbarimages-class.md b/docs/mfc/reference/cmfctoolbarimages-class.md index 3fe00a3e0af..6a04928ba74 100644 --- a/docs/mfc/reference/cmfctoolbarimages-class.md +++ b/docs/mfc/reference/cmfctoolbarimages-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarImages Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarImages", "AFXTOOLBARIMAGES/CMFCToolBarImages", "AFXTOOLBARIMAGES/CMFCToolBarImages::CMFCToolBarImages", "AFXTOOLBARIMAGES/CMFCToolBarImages::AdaptColors", "AFXTOOLBARIMAGES/CMFCToolBarImages::AddIcon", "AFXTOOLBARIMAGES/CMFCToolBarImages::AddImage", "AFXTOOLBARIMAGES/CMFCToolBarImages::CleanUp", "AFXTOOLBARIMAGES/CMFCToolBarImages::Clear", "AFXTOOLBARIMAGES/CMFCToolBarImages::ConvertTo32Bits", "AFXTOOLBARIMAGES/CMFCToolBarImages::CopyImageToClipboard", "AFXTOOLBARIMAGES/CMFCToolBarImages::CopyTo", "AFXTOOLBARIMAGES/CMFCToolBarImages::CreateFromImageList", "AFXTOOLBARIMAGES/CMFCToolBarImages::CreateRegionFromImage", "AFXTOOLBARIMAGES/CMFCToolBarImages::DeleteImage", "AFXTOOLBARIMAGES/CMFCToolBarImages::Draw", "AFXTOOLBARIMAGES/CMFCToolBarImages::DrawEx", "AFXTOOLBARIMAGES/CMFCToolBarImages::EnableRTL", "AFXTOOLBARIMAGES/CMFCToolBarImages::EndDrawImage", "AFXTOOLBARIMAGES/CMFCToolBarImages::ExtractIcon", "AFXTOOLBARIMAGES/CMFCToolBarImages::FillDitheredRect", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetAlwaysLight", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetBitsPerPixel", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetCount", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetDisabledImageAlpha", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetFadedImageAlpha", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetImageSize", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetImageWell", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetImageWellLight", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetLastImageRect", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetLightPercentage", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetMapTo3DColors", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetMask", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetResourceOffset", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetScale", "AFXTOOLBARIMAGES/CMFCToolBarImages::GetTransparentColor", "AFXTOOLBARIMAGES/CMFCToolBarImages::GrayImages", "AFXTOOLBARIMAGES/CMFCToolBarImages::Is32BitTransparencySupported", "AFXTOOLBARIMAGES/CMFCToolBarImages::IsPreMultiplyAutoCheck", "AFXTOOLBARIMAGES/CMFCToolBarImages::IsRTL", "AFXTOOLBARIMAGES/CMFCToolBarImages::IsReadOnly", "AFXTOOLBARIMAGES/CMFCToolBarImages::IsScaled", "AFXTOOLBARIMAGES/CMFCToolBarImages::IsUserImagesList", "AFXTOOLBARIMAGES/CMFCToolBarImages::IsValid", "AFXTOOLBARIMAGES/CMFCToolBarImages::Load", "AFXTOOLBARIMAGES/CMFCToolBarImages::LoadStr", "AFXTOOLBARIMAGES/CMFCToolBarImages::MapFromSysColor", "AFXTOOLBARIMAGES/CMFCToolBarImages::MapTo3dColors", "AFXTOOLBARIMAGES/CMFCToolBarImages::MapToSysColor", "AFXTOOLBARIMAGES/CMFCToolBarImages::MapToSysColorAlpha", "AFXTOOLBARIMAGES/CMFCToolBarImages::Mirror", "AFXTOOLBARIMAGES/CMFCToolBarImages::MirrorBitmap", "AFXTOOLBARIMAGES/CMFCToolBarImages::MirrorBitmapVert", "AFXTOOLBARIMAGES/CMFCToolBarImages::MirrorVert", "AFXTOOLBARIMAGES/CMFCToolBarImages::OnSysColorChange", "AFXTOOLBARIMAGES/CMFCToolBarImages::PrepareDrawImage", "AFXTOOLBARIMAGES/CMFCToolBarImages::Save", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetAlwaysLight", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetDisabledImageAlpha", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetFadedImageAlpha", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetImageSize", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetLightPercentage", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetMapTo3DColors", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetPreMultiplyAutoCheck", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetSingleImage", "AFXTOOLBARIMAGES/CMFCToolBarImages::SetTransparentColor", "AFXTOOLBARIMAGES/CMFCToolBarImages::SmoothResize", "AFXTOOLBARIMAGES/CMFCToolBarImages::UpdateImage", "AFXTOOLBARIMAGES/CMFCToolBarImages::PreMultiplyAlpha", "AFXTOOLBARIMAGES/CMFCToolBarImages::m_bDisableTrueColorAlpha"] helpviewer_keywords: ["CMFCToolBarImages [MFC], CMFCToolBarImages", "CMFCToolBarImages [MFC], AdaptColors", "CMFCToolBarImages [MFC], AddIcon", "CMFCToolBarImages [MFC], AddImage", "CMFCToolBarImages [MFC], CleanUp", "CMFCToolBarImages [MFC], Clear", "CMFCToolBarImages [MFC], ConvertTo32Bits", "CMFCToolBarImages [MFC], CopyImageToClipboard", "CMFCToolBarImages [MFC], CopyTo", "CMFCToolBarImages [MFC], CreateFromImageList", "CMFCToolBarImages [MFC], CreateRegionFromImage", "CMFCToolBarImages [MFC], DeleteImage", "CMFCToolBarImages [MFC], Draw", "CMFCToolBarImages [MFC], DrawEx", "CMFCToolBarImages [MFC], EnableRTL", "CMFCToolBarImages [MFC], EndDrawImage", "CMFCToolBarImages [MFC], ExtractIcon", "CMFCToolBarImages [MFC], FillDitheredRect", "CMFCToolBarImages [MFC], GetAlwaysLight", "CMFCToolBarImages [MFC], GetBitsPerPixel", "CMFCToolBarImages [MFC], GetCount", "CMFCToolBarImages [MFC], GetDisabledImageAlpha", "CMFCToolBarImages [MFC], GetFadedImageAlpha", "CMFCToolBarImages [MFC], GetImageSize", "CMFCToolBarImages [MFC], GetImageWell", "CMFCToolBarImages [MFC], GetImageWellLight", "CMFCToolBarImages [MFC], GetLastImageRect", "CMFCToolBarImages [MFC], GetLightPercentage", "CMFCToolBarImages [MFC], GetMapTo3DColors", "CMFCToolBarImages [MFC], GetMask", "CMFCToolBarImages [MFC], GetResourceOffset", "CMFCToolBarImages [MFC], GetScale", "CMFCToolBarImages [MFC], GetTransparentColor", "CMFCToolBarImages [MFC], GrayImages", "CMFCToolBarImages [MFC], Is32BitTransparencySupported", "CMFCToolBarImages [MFC], IsPreMultiplyAutoCheck", "CMFCToolBarImages [MFC], IsRTL", "CMFCToolBarImages [MFC], IsReadOnly", "CMFCToolBarImages [MFC], IsScaled", "CMFCToolBarImages [MFC], IsUserImagesList", "CMFCToolBarImages [MFC], IsValid", "CMFCToolBarImages [MFC], Load", "CMFCToolBarImages [MFC], LoadStr", "CMFCToolBarImages [MFC], MapFromSysColor", "CMFCToolBarImages [MFC], MapTo3dColors", "CMFCToolBarImages [MFC], MapToSysColor", "CMFCToolBarImages [MFC], MapToSysColorAlpha", "CMFCToolBarImages [MFC], Mirror", "CMFCToolBarImages [MFC], MirrorBitmap", "CMFCToolBarImages [MFC], MirrorBitmapVert", "CMFCToolBarImages [MFC], MirrorVert", "CMFCToolBarImages [MFC], OnSysColorChange", "CMFCToolBarImages [MFC], PrepareDrawImage", "CMFCToolBarImages [MFC], Save", "CMFCToolBarImages [MFC], SetAlwaysLight", "CMFCToolBarImages [MFC], SetDisabledImageAlpha", "CMFCToolBarImages [MFC], SetFadedImageAlpha", "CMFCToolBarImages [MFC], SetImageSize", "CMFCToolBarImages [MFC], SetLightPercentage", "CMFCToolBarImages [MFC], SetMapTo3DColors", "CMFCToolBarImages [MFC], SetPreMultiplyAutoCheck", "CMFCToolBarImages [MFC], SetSingleImage", "CMFCToolBarImages [MFC], SetTransparentColor", "CMFCToolBarImages [MFC], SmoothResize", "CMFCToolBarImages [MFC], UpdateImage", "CMFCToolBarImages [MFC], PreMultiplyAlpha", "CMFCToolBarImages [MFC], m_bDisableTrueColorAlpha"] -ms.assetid: d4e50518-9ffc-406f-9996-f79e5cd38155 --- # CMFCToolBarImages Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The images on a toolbar. The `CMFCToolBarImages` class manages toolbar images loaded from application resources or from files. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfctoolbarinfo-class.md b/docs/mfc/reference/cmfctoolbarinfo-class.md index efec0c3afac..43a753a5169 100644 --- a/docs/mfc/reference/cmfctoolbarinfo-class.md +++ b/docs/mfc/reference/cmfctoolbarinfo-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarInfo Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarInfo", "AFXTOOLBAR/CMFCToolBarInfo", "AFXTOOLBAR/CMFCToolBarInfo::m_uiColdResID", "AFXTOOLBAR/CMFCToolBarInfo::m_uiDisabledResID", "AFXTOOLBAR/CMFCToolBarInfo::m_uiHotResID", "AFXTOOLBAR/CMFCToolBarInfo::m_uiLargeColdResID", "AFXTOOLBAR/CMFCToolBarInfo::m_uiLargeDisabledResID", "AFXTOOLBAR/CMFCToolBarInfo::m_uiLargeHotResID", "AFXTOOLBAR/CMFCToolBarInfo::m_uiMenuDisabledResID", "AFXTOOLBAR/CMFCToolBarInfo::m_uiMenuResID"] helpviewer_keywords: ["CMFCToolBarInfo [MFC], m_uiColdResID", "CMFCToolBarInfo [MFC], m_uiDisabledResID", "CMFCToolBarInfo [MFC], m_uiHotResID", "CMFCToolBarInfo [MFC], m_uiLargeColdResID", "CMFCToolBarInfo [MFC], m_uiLargeDisabledResID", "CMFCToolBarInfo [MFC], m_uiLargeHotResID", "CMFCToolBarInfo [MFC], m_uiMenuDisabledResID", "CMFCToolBarInfo [MFC], m_uiMenuResID"] -ms.assetid: 6dc84482-eaaa-491f-aa5d-dd7a57886b46 --- # CMFCToolBarInfo Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax diff --git a/docs/mfc/reference/cmfctoolbarmenubutton-class.md b/docs/mfc/reference/cmfctoolbarmenubutton-class.md index 62f67ca32f7..aa9fbb43a60 100644 --- a/docs/mfc/reference/cmfctoolbarmenubutton-class.md +++ b/docs/mfc/reference/cmfctoolbarmenubutton-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarMenuButton Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarMenuButton", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::CMFCToolBarMenuButton", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::CompareWith", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::CopyFrom", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::CreateFromMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::CreateMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::CreatePopupMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::EnableQuickCustomize", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::GetCommands", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::GetImageRect", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::GetPaletteRows", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::GetPopupMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::HasButton", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::HaveHotBorder", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsBorder", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsClickedOnMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsDroppedDown", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsEmptyMenuAllowed", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsExclusive", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsMenuPaletteMode", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsQuickMode", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::IsTearOffMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnAfterCreatePopupMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnBeforeDrag", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnCalculateSize", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnCancelMode", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnChangeParentWnd", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnClick", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnClickMenuItem", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnContextHelp", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnDraw", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OnDrawOnCustomizeList", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::OpenPopupMenu", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::ResetImageToDefault", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::SaveBarState", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::Serialize", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::SetACCData", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::SetMenuOnly", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::SetMenuPaletteMode", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::SetMessageWnd", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::SetRadio", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::SetTearOff", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::DrawDocumentIcon", "AFXTOOLBARMENUBUTTON/CMFCToolBarMenuButton::m_bAlwaysCallOwnerDraw"] helpviewer_keywords: ["CMFCToolBarMenuButton [MFC], CMFCToolBarMenuButton", "CMFCToolBarMenuButton [MFC], CompareWith", "CMFCToolBarMenuButton [MFC], CopyFrom", "CMFCToolBarMenuButton [MFC], CreateFromMenu", "CMFCToolBarMenuButton [MFC], CreateMenu", "CMFCToolBarMenuButton [MFC], CreatePopupMenu", "CMFCToolBarMenuButton [MFC], EnableQuickCustomize", "CMFCToolBarMenuButton [MFC], GetCommands", "CMFCToolBarMenuButton [MFC], GetImageRect", "CMFCToolBarMenuButton [MFC], GetPaletteRows", "CMFCToolBarMenuButton [MFC], GetPopupMenu", "CMFCToolBarMenuButton [MFC], HasButton", "CMFCToolBarMenuButton [MFC], HaveHotBorder", "CMFCToolBarMenuButton [MFC], IsBorder", "CMFCToolBarMenuButton [MFC], IsClickedOnMenu", "CMFCToolBarMenuButton [MFC], IsDroppedDown", "CMFCToolBarMenuButton [MFC], IsEmptyMenuAllowed", "CMFCToolBarMenuButton [MFC], IsExclusive", "CMFCToolBarMenuButton [MFC], IsMenuPaletteMode", "CMFCToolBarMenuButton [MFC], IsQuickMode", "CMFCToolBarMenuButton [MFC], IsTearOffMenu", "CMFCToolBarMenuButton [MFC], OnAfterCreatePopupMenu", "CMFCToolBarMenuButton [MFC], OnBeforeDrag", "CMFCToolBarMenuButton [MFC], OnCalculateSize", "CMFCToolBarMenuButton [MFC], OnCancelMode", "CMFCToolBarMenuButton [MFC], OnChangeParentWnd", "CMFCToolBarMenuButton [MFC], OnClick", "CMFCToolBarMenuButton [MFC], OnClickMenuItem", "CMFCToolBarMenuButton [MFC], OnContextHelp", "CMFCToolBarMenuButton [MFC], OnDraw", "CMFCToolBarMenuButton [MFC], OnDrawOnCustomizeList", "CMFCToolBarMenuButton [MFC], OpenPopupMenu", "CMFCToolBarMenuButton [MFC], ResetImageToDefault", "CMFCToolBarMenuButton [MFC], SaveBarState", "CMFCToolBarMenuButton [MFC], Serialize", "CMFCToolBarMenuButton [MFC], SetACCData", "CMFCToolBarMenuButton [MFC], SetMenuOnly", "CMFCToolBarMenuButton [MFC], SetMenuPaletteMode", "CMFCToolBarMenuButton [MFC], SetMessageWnd", "CMFCToolBarMenuButton [MFC], SetRadio", "CMFCToolBarMenuButton [MFC], SetTearOff", "CMFCToolBarMenuButton [MFC], DrawDocumentIcon", "CMFCToolBarMenuButton [MFC], m_bAlwaysCallOwnerDraw"] -ms.assetid: cfa50176-7e4b-4527-9904-86a1b48fc1bc --- # CMFCToolBarMenuButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A toolbar button that contains a pop-up menu. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md b/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md index 788354e40da..ab98d47944b 100644 --- a/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md +++ b/docs/mfc/reference/cmfctoolbarscustomizedialog-class.md @@ -4,10 +4,12 @@ title: "CMFCToolBarsCustomizeDialog Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolBarsCustomizeDialog", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::CMFCToolBarsCustomizeDialog", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::FillAllCommandsList", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::FillCategoriesComboBox", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::FillCategoriesListBox", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::GetCommandName", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::GetCountInCategory", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::GetFlags", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::OnInitDialog", "AFXTOOLBARSCUSTOMIZEDIALOG/CMFCToolBarsCustomizeDialog::PostNcDestroy"] helpviewer_keywords: ["CMFCToolBarsCustomizeDialog [MFC], CMFCToolBarsCustomizeDialog", "CMFCToolBarsCustomizeDialog [MFC], FillAllCommandsList", "CMFCToolBarsCustomizeDialog [MFC], FillCategoriesComboBox", "CMFCToolBarsCustomizeDialog [MFC], FillCategoriesListBox", "CMFCToolBarsCustomizeDialog [MFC], GetCommandName", "CMFCToolBarsCustomizeDialog [MFC], GetCountInCategory", "CMFCToolBarsCustomizeDialog [MFC], GetFlags", "CMFCToolBarsCustomizeDialog [MFC], OnInitDialog", "CMFCToolBarsCustomizeDialog [MFC], PostNcDestroy"] -ms.assetid: 78e2cddd-4f13-4097-afc3-1ad646a113f1 --- # CMFCToolBarsCustomizeDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. The **Customize** dialog box has six tabs: **Commands**, **Toolbars**, **Tools**, **Keyboard**, **Menu**, and **Options**. @@ -518,7 +520,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 5c4d7f2204b..9cf0b9adff4 100644 --- a/docs/mfc/reference/cmfctooltipctrl-class.md +++ b/docs/mfc/reference/cmfctooltipctrl-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -149,7 +151,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 +393,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/cmfctooltipinfo-class.md b/docs/mfc/reference/cmfctooltipinfo-class.md index cefde9ab39f..4f9385a7fd7 100644 --- a/docs/mfc/reference/cmfctooltipinfo-class.md +++ b/docs/mfc/reference/cmfctooltipinfo-class.md @@ -4,10 +4,12 @@ title: "CMFCToolTipInfo Class" ms.date: "11/04/2016" f1_keywords: ["CMFCToolTipInfo", "AFXTOOLTIPCTRL/CMFCToolTipInfo", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_bBalloonTooltip", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_bBoldLabel", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_bDrawDescription", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_bDrawIcon", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_bDrawSeparator", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_bRoundedCorners", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_bVislManagerTheme", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_clrBorder", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_clrFill", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_clrFillGradient", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_clrText", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_nGradientAngle", "AFXTOOLTIPCTRL/CMFCToolTipInfo::m_nMaxDescrWidth"] helpviewer_keywords: ["CMFCToolTipInfo [MFC], m_bBalloonTooltip", "CMFCToolTipInfo [MFC], m_bBoldLabel", "CMFCToolTipInfo [MFC], m_bDrawDescription", "CMFCToolTipInfo [MFC], m_bDrawIcon", "CMFCToolTipInfo [MFC], m_bDrawSeparator", "CMFCToolTipInfo [MFC], m_bRoundedCorners", "CMFCToolTipInfo [MFC], m_bVislManagerTheme", "CMFCToolTipInfo [MFC], m_clrBorder", "CMFCToolTipInfo [MFC], m_clrFill", "CMFCToolTipInfo [MFC], m_clrFillGradient", "CMFCToolTipInfo [MFC], m_clrText", "CMFCToolTipInfo [MFC], m_nGradientAngle", "CMFCToolTipInfo [MFC], m_nMaxDescrWidth"] -ms.assetid: f9d3d7f8-1f08-4342-a7b2-683860e5d2a5 --- # CMFCToolTipInfo Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Stores information about the visual appearance of tooltips. ## Syntax diff --git a/docs/mfc/reference/cmfcvisualmanager-class.md b/docs/mfc/reference/cmfcvisualmanager-class.md index 30656dd9234..fbcf36dd516 100644 --- a/docs/mfc/reference/cmfcvisualmanager-class.md +++ b/docs/mfc/reference/cmfcvisualmanager-class.md @@ -4,10 +4,12 @@ title: "CMFCVisualManager Class" ms.date: "11/04/2016" f1_keywords: ["CMFCVisualManager", "AFXVISUALMANAGER/CMFCVisualManager", "AFXVISUALMANAGER/CMFCVisualManager::AdjustFrames", "AFXVISUALMANAGER/CMFCVisualManager::AdjustToolbars", "AFXVISUALMANAGER/CMFCVisualManager::AlwaysHighlight3DTabs", "AFXVISUALMANAGER/CMFCVisualManager::DestroyInstance", "AFXVISUALMANAGER/CMFCVisualManager::DoDrawHeaderSortArrow", "AFXVISUALMANAGER/CMFCVisualManager::DrawComboDropButtonWinXP", "AFXVISUALMANAGER/CMFCVisualManager::DrawPushButtonWinXP", "AFXVISUALMANAGER/CMFCVisualManager::DrawTextOnGlass", "AFXVISUALMANAGER/CMFCVisualManager::GetAutoHideButtonTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetButtonExtraBorder", "AFXVISUALMANAGER/CMFCVisualManager::GetCaptionBarTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetDockingTabsBordersSize", "AFXVISUALMANAGER/CMFCVisualManager::GetHighlightedMenuItemTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetInstance", "AFXVISUALMANAGER/CMFCVisualManager::GetMDITabsBordersSize", "AFXVISUALMANAGER/CMFCVisualManager::GetMenuItemTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetMenuShadowDepth", "AFXVISUALMANAGER/CMFCVisualManager::GetNcBtnSize", "AFXVISUALMANAGER/CMFCVisualManager::GetPopupMenuBorderSize", "AFXVISUALMANAGER/CMFCVisualManager::GetPropertyGridGroupColor", "AFXVISUALMANAGER/CMFCVisualManager::GetPropertyGridGroupTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetRibbonHyperlinkTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetRibbonPopupBorderSize", "AFXVISUALMANAGER/CMFCVisualManager::GetRibbonQuickAccessToolBarTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetRibbonSliderColors", "AFXVISUALMANAGER/CMFCVisualManager::GetShowAllMenuItemsHeight", "AFXVISUALMANAGER/CMFCVisualManager::GetSmartDockingBaseGuideColors", "AFXVISUALMANAGER/CMFCVisualManager::GetSmartDockingHighlightToneColor", "AFXVISUALMANAGER/CMFCVisualManager::GetSmartDockingTheme", "AFXVISUALMANAGER/CMFCVisualManager::GetStatusBarPaneTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetTabFrameColors", "AFXVISUALMANAGER/CMFCVisualManager::GetTabTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetToolbarButtonTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetToolbarDisabledTextColor", "AFXVISUALMANAGER/CMFCVisualManager::GetToolbarHighlightColor", "AFXVISUALMANAGER/CMFCVisualManager::GetToolTipInfo", "AFXVISUALMANAGER/CMFCVisualManager::HasOverlappedAutoHideButtons", "AFXVISUALMANAGER/CMFCVisualManager::IsDockingTabHasBorder", "AFXVISUALMANAGER/CMFCVisualManager::IsEmbossDisabledImage", "AFXVISUALMANAGER/CMFCVisualManager::IsFadeInactiveImage", "AFXVISUALMANAGER/CMFCVisualManager::IsMenuFlatLook", "AFXVISUALMANAGER/CMFCVisualManager::IsOfficeXPStyleMenus", "AFXVISUALMANAGER/CMFCVisualManager::IsOwnerDrawCaption", "AFXVISUALMANAGER/CMFCVisualManager::IsShadowHighlightedImage", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawAutoHideButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawBarGripper", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawBrowseButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawButtonSeparator", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawCaptionBarBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawCaptionBarButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawCaptionBarInfoArea", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawCaptionButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawCheckBox", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawCheckBoxEx", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawComboBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawComboDropButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawControlBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawDefaultRibbonImage", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawEditBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawExpandingBox", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawFloatingToolbarBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawHeaderCtrlBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawHeaderCtrlSortArrow", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuArrowOnCustomizeList", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuCheck", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuItemButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuLabel", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuResizeBar", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuScrollButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuShadow", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMenuSystemButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawMiniFrameBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawOutlookBarSplitter", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawOutlookPageButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawPaneBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawPaneCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawPaneDivider", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawPopupWindowBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawPopupWindowButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawPopupWindowCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonApplicationButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonButtonsGroup", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonCaptionButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonCategory", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonCategoryCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonCategoryScroll", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonCategoryTab", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonCheckBoxOnList", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonColorPaletteBox", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonDefaultPaneButtonContext", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonDefaultPaneButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonDefaultPaneButtonIndicator", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonGalleryBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonGalleryButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonKeyTip", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonLabel", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonMainPanelButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonMainPanelFrame", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonMenuCheckFrame", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonPanel", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonPanelCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonProgressBar", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonQuickAccessToolBarSeparator", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonRecentFilesFrame", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonSliderChannel", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonSliderThumb", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonSliderZoomButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonStatusBarPane", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawRibbonTabsFrame", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawScrollButtons", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawSeparator", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawShowAllMenuItems", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawSpinButtons", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawSplitterBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawSplitterBox", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawStatusBarPaneBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawStatusBarProgress", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawStatusBarSizeBox", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTab", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTabCloseButton", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTabContent", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTabsButtonBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTask", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTasksGroupAreaBorder", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTasksGroupCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTasksGroupIcon", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawTearOffCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnDrawToolBoxFrame", "AFXVISUALMANAGER/CMFCVisualManager::OnEraseMDIClientArea", "AFXVISUALMANAGER/CMFCVisualManager::OnErasePopupWindowButton", "AFXVISUALMANAGER/CMFCVisualManager::OnEraseTabsArea", "AFXVISUALMANAGER/CMFCVisualManager::OnEraseTabsButton", "AFXVISUALMANAGER/CMFCVisualManager::OnEraseTabsFrame", "AFXVISUALMANAGER/CMFCVisualManager::OnFillAutoHideButtonBackground", "AFXVISUALMANAGER/CMFCVisualManager::OnFillBarBackground", "AFXVISUALMANAGER/CMFCVisualManager::OnFillButtonInterior", "AFXVISUALMANAGER/CMFCVisualManager::OnFillCaptionBarButton", "AFXVISUALMANAGER/CMFCVisualManager::OnFillCommandsListBackground", "AFXVISUALMANAGER/CMFCVisualManager::OnFillHeaderCtrlBackground", "AFXVISUALMANAGER/CMFCVisualManager::OnFillMiniFrameCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnFillOutlookBarCaption", "AFXVISUALMANAGER/CMFCVisualManager::OnFillOutlookPageButton", "AFXVISUALMANAGER/CMFCVisualManager::OnFillPopupWindowBackground", "AFXVISUALMANAGER/CMFCVisualManager::OnFillRibbonButton", "AFXVISUALMANAGER/CMFCVisualManager::OnFillRibbonEdit", "AFXVISUALMANAGER/CMFCVisualManager::OnFillRibbonMainPanelButton", "AFXVISUALMANAGER/CMFCVisualManager::OnFillRibbonMenuFrame", "AFXVISUALMANAGER/CMFCVisualManager::OnFillRibbonQuickAccessToolBarPopup", "AFXVISUALMANAGER/CMFCVisualManager::OnFillSplitterBackground", "AFXVISUALMANAGER/CMFCVisualManager::OnFillTab", "AFXVISUALMANAGER/CMFCVisualManager::OnFillTasksGroupInterior", "AFXVISUALMANAGER/CMFCVisualManager::OnFillTasksPaneBackground", "AFXVISUALMANAGER/CMFCVisualManager::OnHighlightMenuItem", "AFXVISUALMANAGER/CMFCVisualManager::OnHighlightRarelyUsedMenuItems", "AFXVISUALMANAGER/CMFCVisualManager::OnNcPaint", "AFXVISUALMANAGER/CMFCVisualManager::OnSetWindowRegion", "AFXVISUALMANAGER/CMFCVisualManager::OnUpdateSystemColors", "AFXVISUALMANAGER/CMFCVisualManager::RedrawAll", "AFXVISUALMANAGER/CMFCVisualManager::RibbonCategoryColorToRGB", "AFXVISUALMANAGER/CMFCVisualManager::SetDefaultManager", "AFXVISUALMANAGER/CMFCVisualManager::SetEmbossDisabledImage", "AFXVISUALMANAGER/CMFCVisualManager::SetFadeInactiveImage", "AFXVISUALMANAGER/CMFCVisualManager::SetMenuFlatLook", "AFXVISUALMANAGER/CMFCVisualManager::SetMenuShadowDepth", "AFXVISUALMANAGER/CMFCVisualManager::SetShadowHighlightedImage"] helpviewer_keywords: ["CMFCVisualManager [MFC], AdjustFrames", "CMFCVisualManager [MFC], AdjustToolbars", "CMFCVisualManager [MFC], AlwaysHighlight3DTabs", "CMFCVisualManager [MFC], DestroyInstance", "CMFCVisualManager [MFC], DoDrawHeaderSortArrow", "CMFCVisualManager [MFC], DrawComboDropButtonWinXP", "CMFCVisualManager [MFC], DrawPushButtonWinXP", "CMFCVisualManager [MFC], DrawTextOnGlass", "CMFCVisualManager [MFC], GetAutoHideButtonTextColor", "CMFCVisualManager [MFC], GetButtonExtraBorder", "CMFCVisualManager [MFC], GetCaptionBarTextColor", "CMFCVisualManager [MFC], GetDockingTabsBordersSize", "CMFCVisualManager [MFC], GetHighlightedMenuItemTextColor", "CMFCVisualManager [MFC], GetInstance", "CMFCVisualManager [MFC], GetMDITabsBordersSize", "CMFCVisualManager [MFC], GetMenuItemTextColor", "CMFCVisualManager [MFC], GetMenuShadowDepth", "CMFCVisualManager [MFC], GetNcBtnSize", "CMFCVisualManager [MFC], GetPopupMenuBorderSize", "CMFCVisualManager [MFC], GetPropertyGridGroupColor", "CMFCVisualManager [MFC], GetPropertyGridGroupTextColor", "CMFCVisualManager [MFC], GetRibbonHyperlinkTextColor", "CMFCVisualManager [MFC], GetRibbonPopupBorderSize", "CMFCVisualManager [MFC], GetRibbonQuickAccessToolBarTextColor", "CMFCVisualManager [MFC], GetRibbonSliderColors", "CMFCVisualManager [MFC], GetShowAllMenuItemsHeight", "CMFCVisualManager [MFC], GetSmartDockingBaseGuideColors", "CMFCVisualManager [MFC], GetSmartDockingHighlightToneColor", "CMFCVisualManager [MFC], GetSmartDockingTheme", "CMFCVisualManager [MFC], GetStatusBarPaneTextColor", "CMFCVisualManager [MFC], GetTabFrameColors", "CMFCVisualManager [MFC], GetTabTextColor", "CMFCVisualManager [MFC], GetToolbarButtonTextColor", "CMFCVisualManager [MFC], GetToolbarDisabledTextColor", "CMFCVisualManager [MFC], GetToolbarHighlightColor", "CMFCVisualManager [MFC], GetToolTipInfo", "CMFCVisualManager [MFC], HasOverlappedAutoHideButtons", "CMFCVisualManager [MFC], IsDockingTabHasBorder", "CMFCVisualManager [MFC], IsEmbossDisabledImage", "CMFCVisualManager [MFC], IsFadeInactiveImage", "CMFCVisualManager [MFC], IsMenuFlatLook", "CMFCVisualManager [MFC], IsOfficeXPStyleMenus", "CMFCVisualManager [MFC], IsOwnerDrawCaption", "CMFCVisualManager [MFC], IsShadowHighlightedImage", "CMFCVisualManager [MFC], OnDrawAutoHideButtonBorder", "CMFCVisualManager [MFC], OnDrawBarGripper", "CMFCVisualManager [MFC], OnDrawBrowseButton", "CMFCVisualManager [MFC], OnDrawButtonBorder", "CMFCVisualManager [MFC], OnDrawButtonSeparator", "CMFCVisualManager [MFC], OnDrawCaptionBarBorder", "CMFCVisualManager [MFC], OnDrawCaptionBarButtonBorder", "CMFCVisualManager [MFC], OnDrawCaptionBarInfoArea", "CMFCVisualManager [MFC], OnDrawCaptionButton", "CMFCVisualManager [MFC], OnDrawCheckBox", "CMFCVisualManager [MFC], OnDrawCheckBoxEx", "CMFCVisualManager [MFC], OnDrawComboBorder", "CMFCVisualManager [MFC], OnDrawComboDropButton", "CMFCVisualManager [MFC], OnDrawControlBorder", "CMFCVisualManager [MFC], OnDrawDefaultRibbonImage", "CMFCVisualManager [MFC], OnDrawEditBorder", "CMFCVisualManager [MFC], OnDrawExpandingBox", "CMFCVisualManager [MFC], OnDrawFloatingToolbarBorder", "CMFCVisualManager [MFC], OnDrawHeaderCtrlBorder", "CMFCVisualManager [MFC], OnDrawHeaderCtrlSortArrow", "CMFCVisualManager [MFC], OnDrawMenuArrowOnCustomizeList", "CMFCVisualManager [MFC], OnDrawMenuBorder", "CMFCVisualManager [MFC], OnDrawMenuCheck", "CMFCVisualManager [MFC], OnDrawMenuItemButton", "CMFCVisualManager [MFC], OnDrawMenuLabel", "CMFCVisualManager [MFC], OnDrawMenuResizeBar", "CMFCVisualManager [MFC], OnDrawMenuScrollButton", "CMFCVisualManager [MFC], OnDrawMenuShadow", "CMFCVisualManager [MFC], OnDrawMenuSystemButton", "CMFCVisualManager [MFC], OnDrawMiniFrameBorder", "CMFCVisualManager [MFC], OnDrawOutlookBarSplitter", "CMFCVisualManager [MFC], OnDrawOutlookPageButtonBorder", "CMFCVisualManager [MFC], OnDrawPaneBorder", "CMFCVisualManager [MFC], OnDrawPaneCaption", "CMFCVisualManager [MFC], OnDrawPaneDivider", "CMFCVisualManager [MFC], OnDrawPopupWindowBorder", "CMFCVisualManager [MFC], OnDrawPopupWindowButtonBorder", "CMFCVisualManager [MFC], OnDrawPopupWindowCaption", "CMFCVisualManager [MFC], OnDrawRibbonApplicationButton", "CMFCVisualManager [MFC], OnDrawRibbonButtonBorder", "CMFCVisualManager [MFC], OnDrawRibbonButtonsGroup", "CMFCVisualManager [MFC], OnDrawRibbonCaption", "CMFCVisualManager [MFC], OnDrawRibbonCaptionButton", "CMFCVisualManager [MFC], OnDrawRibbonCategory", "CMFCVisualManager [MFC], OnDrawRibbonCategoryCaption", "CMFCVisualManager [MFC], OnDrawRibbonCategoryScroll", "CMFCVisualManager [MFC], OnDrawRibbonCategoryTab", "CMFCVisualManager [MFC], OnDrawRibbonCheckBoxOnList", "CMFCVisualManager [MFC], OnDrawRibbonColorPaletteBox", "CMFCVisualManager [MFC], OnDrawRibbonDefaultPaneButtonContext", "CMFCVisualManager [MFC], OnDrawRibbonDefaultPaneButton", "CMFCVisualManager [MFC], OnDrawRibbonDefaultPaneButtonIndicator", "CMFCVisualManager [MFC], OnDrawRibbonGalleryBorder", "CMFCVisualManager [MFC], OnDrawRibbonGalleryButton", "CMFCVisualManager [MFC], OnDrawRibbonKeyTip", "CMFCVisualManager [MFC], OnDrawRibbonLabel", "CMFCVisualManager [MFC], OnDrawRibbonMainPanelButtonBorder", "CMFCVisualManager [MFC], OnDrawRibbonMainPanelFrame", "CMFCVisualManager [MFC], OnDrawRibbonMenuCheckFrame", "CMFCVisualManager [MFC], OnDrawRibbonPanel", "CMFCVisualManager [MFC], OnDrawRibbonPanelCaption", "CMFCVisualManager [MFC], OnDrawRibbonProgressBar", "CMFCVisualManager [MFC], OnDrawRibbonQuickAccessToolBarSeparator", "CMFCVisualManager [MFC], OnDrawRibbonRecentFilesFrame", "CMFCVisualManager [MFC], OnDrawRibbonSliderChannel", "CMFCVisualManager [MFC], OnDrawRibbonSliderThumb", "CMFCVisualManager [MFC], OnDrawRibbonSliderZoomButton", "CMFCVisualManager [MFC], OnDrawRibbonStatusBarPane", "CMFCVisualManager [MFC], OnDrawRibbonTabsFrame", "CMFCVisualManager [MFC], OnDrawScrollButtons", "CMFCVisualManager [MFC], OnDrawSeparator", "CMFCVisualManager [MFC], OnDrawShowAllMenuItems", "CMFCVisualManager [MFC], OnDrawSpinButtons", "CMFCVisualManager [MFC], OnDrawSplitterBorder", "CMFCVisualManager [MFC], OnDrawSplitterBox", "CMFCVisualManager [MFC], OnDrawStatusBarPaneBorder", "CMFCVisualManager [MFC], OnDrawStatusBarProgress", "CMFCVisualManager [MFC], OnDrawStatusBarSizeBox", "CMFCVisualManager [MFC], OnDrawTab", "CMFCVisualManager [MFC], OnDrawTabCloseButton", "CMFCVisualManager [MFC], OnDrawTabContent", "CMFCVisualManager [MFC], OnDrawTabsButtonBorder", "CMFCVisualManager [MFC], OnDrawTask", "CMFCVisualManager [MFC], OnDrawTasksGroupAreaBorder", "CMFCVisualManager [MFC], OnDrawTasksGroupCaption", "CMFCVisualManager [MFC], OnDrawTasksGroupIcon", "CMFCVisualManager [MFC], OnDrawTearOffCaption", "CMFCVisualManager [MFC], OnDrawToolBoxFrame", "CMFCVisualManager [MFC], OnEraseMDIClientArea", "CMFCVisualManager [MFC], OnErasePopupWindowButton", "CMFCVisualManager [MFC], OnEraseTabsArea", "CMFCVisualManager [MFC], OnEraseTabsButton", "CMFCVisualManager [MFC], OnEraseTabsFrame", "CMFCVisualManager [MFC], OnFillAutoHideButtonBackground", "CMFCVisualManager [MFC], OnFillBarBackground", "CMFCVisualManager [MFC], OnFillButtonInterior", "CMFCVisualManager [MFC], OnFillCaptionBarButton", "CMFCVisualManager [MFC], OnFillCommandsListBackground", "CMFCVisualManager [MFC], OnFillHeaderCtrlBackground", "CMFCVisualManager [MFC], OnFillMiniFrameCaption", "CMFCVisualManager [MFC], OnFillOutlookBarCaption", "CMFCVisualManager [MFC], OnFillOutlookPageButton", "CMFCVisualManager [MFC], OnFillPopupWindowBackground", "CMFCVisualManager [MFC], OnFillRibbonButton", "CMFCVisualManager [MFC], OnFillRibbonEdit", "CMFCVisualManager [MFC], OnFillRibbonMainPanelButton", "CMFCVisualManager [MFC], OnFillRibbonMenuFrame", "CMFCVisualManager [MFC], OnFillRibbonQuickAccessToolBarPopup", "CMFCVisualManager [MFC], OnFillSplitterBackground", "CMFCVisualManager [MFC], OnFillTab", "CMFCVisualManager [MFC], OnFillTasksGroupInterior", "CMFCVisualManager [MFC], OnFillTasksPaneBackground", "CMFCVisualManager [MFC], OnHighlightMenuItem", "CMFCVisualManager [MFC], OnHighlightRarelyUsedMenuItems", "CMFCVisualManager [MFC], OnNcPaint", "CMFCVisualManager [MFC], OnSetWindowRegion", "CMFCVisualManager [MFC], OnUpdateSystemColors", "CMFCVisualManager [MFC], RedrawAll", "CMFCVisualManager [MFC], RibbonCategoryColorToRGB", "CMFCVisualManager [MFC], SetDefaultManager", "CMFCVisualManager [MFC], SetEmbossDisabledImage", "CMFCVisualManager [MFC], SetFadeInactiveImage", "CMFCVisualManager [MFC], SetMenuFlatLook", "CMFCVisualManager [MFC], SetMenuShadowDepth", "CMFCVisualManager [MFC], SetShadowHighlightedImage"] -ms.assetid: beed80f7-36a2-4d64-9f09-e807cfefc3fe --- # CMFCVisualManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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`. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. @@ -556,7 +558,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 a2ca2ffc89e..3ae383f3c4c 100644 --- a/docs/mfc/reference/cmfcvisualmanageroffice2003-class.md +++ b/docs/mfc/reference/cmfcvisualmanageroffice2003-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CMFCVisualManagerOffice2003` gives an application a Microsoft Office 2003 appearance. ## Syntax @@ -1265,7 +1267,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/cmfcvisualmanageroffice2007-class.md b/docs/mfc/reference/cmfcvisualmanageroffice2007-class.md index b0620fe6b8f..ee13a6682b2 100644 --- a/docs/mfc/reference/cmfcvisualmanageroffice2007-class.md +++ b/docs/mfc/reference/cmfcvisualmanageroffice2007-class.md @@ -4,10 +4,12 @@ title: "CMFCVisualManagerOffice2007 Class" ms.date: "11/04/2016" f1_keywords: ["CMFCVisualManagerOffice2007", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::AlwaysHighlight3DTabs", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::CleanStyle", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetCaptionBarTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetHighlightedMenuItemTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetMenuItemTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetNcBtnSize", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetRibbonBar", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetRibbonHyperlinkTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetRibbonPopupBorderSize", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetRibbonQuickAccessToolBarChevronOffset", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetRibbonQuickAccessToolBarRightMargin", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetRibbonQuickAccessToolBarTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetRibbonStatusBarTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetShowAllMenuItemsHeight", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetStatusBarPaneTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetTabFrameColors", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetTabHorzMargin", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetTabTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetToolbarButtonTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetToolbarDisabledTextColor", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::GetToolTipInfo", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::IsHighlightWholeMenuItem", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::IsLayeredRibbonKeyTip", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::IsOwnerDrawCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::IsOwnerDrawMenuCheck", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::IsRibbonPresent", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawBarGripper", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawButtonBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawButtonSeparator", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawCaptionBarInfoArea", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawCheckBoxEx", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawComboBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawComboDropButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawDefaultRibbonImage", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawEditBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawFloatingToolbarBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawHeaderCtrlBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMenuBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMenuCheck", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMenuItemButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMenuLabel", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMenuResizeBar", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMenuScrollButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMenuSystemButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawMiniFrameBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawOutlookBarSplitter", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawOutlookPageButtonBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawPaneCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawPopupWindowCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawPropertySheetListItem", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonApplicationButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonButtonBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonButtonsGroup", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonCaptionButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonCategory", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonCategoryCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonCategoryScroll", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonCategoryTab", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonCheckBoxOnList", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonDefaultPaneButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonDefaultPaneButtonIndicator", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonGalleryBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonGalleryButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonKeyTip", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonMainPanelButtonBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonMainPanelFrame", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonMenuCheckFrame", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonPanel", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonPanelCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonProgressBar", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonRecentFilesFrame", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonSliderChannel", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonSliderThumb", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonSliderZoomButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonStatusBarPane", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawRibbonTabsFrame", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawScrollButtons", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawSeparator", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawShowAllMenuItems", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawStatusBarPaneBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawStatusBarSizeBox", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawTab", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawTabsButtonBorder", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawTask", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawTasksGroupCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnDrawTearOffCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnEraseMDIClientArea", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnEraseTabsArea", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnEraseTabsButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnEraseTabsFrame", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillBarBackground", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillButtonInterior", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillCaptionBarButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillHighlightedArea", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillMiniFrameCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillOutlookBarCaption", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillOutlookPageButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillPopupWindowBackground", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillRibbonButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillRibbonEdit", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillRibbonMainPanelButton", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillRibbonMenuFrame", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillRibbonQuickAccessToolBarPopup", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnFillTab", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnHighlightMenuItem", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnHighlightRarelyUsedMenuItems", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnNcActivate", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnNcPaint", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnSetWindowRegion", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::OnUpdateSystemColors", "AFXVISUALMANAGEROFFICE2007/CMFCVisualManagerOffice2007::SetResourceHandle"] helpviewer_keywords: ["CMFCVisualManagerOffice2007 [MFC], AlwaysHighlight3DTabs", "CMFCVisualManagerOffice2007 [MFC], CleanStyle", "CMFCVisualManagerOffice2007 [MFC], GetCaptionBarTextColor", "CMFCVisualManagerOffice2007 [MFC], GetHighlightedMenuItemTextColor", "CMFCVisualManagerOffice2007 [MFC], GetMenuItemTextColor", "CMFCVisualManagerOffice2007 [MFC], GetNcBtnSize", "CMFCVisualManagerOffice2007 [MFC], GetRibbonBar", "CMFCVisualManagerOffice2007 [MFC], GetRibbonHyperlinkTextColor", "CMFCVisualManagerOffice2007 [MFC], GetRibbonPopupBorderSize", "CMFCVisualManagerOffice2007 [MFC], GetRibbonQuickAccessToolBarChevronOffset", "CMFCVisualManagerOffice2007 [MFC], GetRibbonQuickAccessToolBarRightMargin", "CMFCVisualManagerOffice2007 [MFC], GetRibbonQuickAccessToolBarTextColor", "CMFCVisualManagerOffice2007 [MFC], GetRibbonStatusBarTextColor", "CMFCVisualManagerOffice2007 [MFC], GetShowAllMenuItemsHeight", "CMFCVisualManagerOffice2007 [MFC], GetStatusBarPaneTextColor", "CMFCVisualManagerOffice2007 [MFC], GetTabFrameColors", "CMFCVisualManagerOffice2007 [MFC], GetTabHorzMargin", "CMFCVisualManagerOffice2007 [MFC], GetTabTextColor", "CMFCVisualManagerOffice2007 [MFC], GetToolbarButtonTextColor", "CMFCVisualManagerOffice2007 [MFC], GetToolbarDisabledTextColor", "CMFCVisualManagerOffice2007 [MFC], GetToolTipInfo", "CMFCVisualManagerOffice2007 [MFC], IsHighlightWholeMenuItem", "CMFCVisualManagerOffice2007 [MFC], IsLayeredRibbonKeyTip", "CMFCVisualManagerOffice2007 [MFC], IsOwnerDrawCaption", "CMFCVisualManagerOffice2007 [MFC], IsOwnerDrawMenuCheck", "CMFCVisualManagerOffice2007 [MFC], IsRibbonPresent", "CMFCVisualManagerOffice2007 [MFC], OnDrawBarGripper", "CMFCVisualManagerOffice2007 [MFC], OnDrawButtonBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawButtonSeparator", "CMFCVisualManagerOffice2007 [MFC], OnDrawCaptionBarInfoArea", "CMFCVisualManagerOffice2007 [MFC], OnDrawCheckBoxEx", "CMFCVisualManagerOffice2007 [MFC], OnDrawComboBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawComboDropButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawDefaultRibbonImage", "CMFCVisualManagerOffice2007 [MFC], OnDrawEditBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawFloatingToolbarBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawHeaderCtrlBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawMenuBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawMenuCheck", "CMFCVisualManagerOffice2007 [MFC], OnDrawMenuItemButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawMenuLabel", "CMFCVisualManagerOffice2007 [MFC], OnDrawMenuResizeBar", "CMFCVisualManagerOffice2007 [MFC], OnDrawMenuScrollButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawMenuSystemButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawMiniFrameBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawOutlookBarSplitter", "CMFCVisualManagerOffice2007 [MFC], OnDrawOutlookPageButtonBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawPaneCaption", "CMFCVisualManagerOffice2007 [MFC], OnDrawPopupWindowCaption", "CMFCVisualManagerOffice2007 [MFC], OnDrawPropertySheetListItem", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonApplicationButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonButtonBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonButtonsGroup", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonCaption", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonCaptionButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonCategory", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonCategoryCaption", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonCategoryScroll", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonCategoryTab", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonCheckBoxOnList", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonDefaultPaneButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonDefaultPaneButtonIndicator", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonGalleryBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonGalleryButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonKeyTip", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonMainPanelButtonBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonMainPanelFrame", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonMenuCheckFrame", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonPanel", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonPanelCaption", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonProgressBar", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonRecentFilesFrame", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonSliderChannel", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonSliderThumb", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonSliderZoomButton", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonStatusBarPane", "CMFCVisualManagerOffice2007 [MFC], OnDrawRibbonTabsFrame", "CMFCVisualManagerOffice2007 [MFC], OnDrawScrollButtons", "CMFCVisualManagerOffice2007 [MFC], OnDrawSeparator", "CMFCVisualManagerOffice2007 [MFC], OnDrawShowAllMenuItems", "CMFCVisualManagerOffice2007 [MFC], OnDrawStatusBarPaneBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawStatusBarSizeBox", "CMFCVisualManagerOffice2007 [MFC], OnDrawTab", "CMFCVisualManagerOffice2007 [MFC], OnDrawTabsButtonBorder", "CMFCVisualManagerOffice2007 [MFC], OnDrawTask", "CMFCVisualManagerOffice2007 [MFC], OnDrawTasksGroupCaption", "CMFCVisualManagerOffice2007 [MFC], OnDrawTearOffCaption", "CMFCVisualManagerOffice2007 [MFC], OnEraseMDIClientArea", "CMFCVisualManagerOffice2007 [MFC], OnEraseTabsArea", "CMFCVisualManagerOffice2007 [MFC], OnEraseTabsButton", "CMFCVisualManagerOffice2007 [MFC], OnEraseTabsFrame", "CMFCVisualManagerOffice2007 [MFC], OnFillBarBackground", "CMFCVisualManagerOffice2007 [MFC], OnFillButtonInterior", "CMFCVisualManagerOffice2007 [MFC], OnFillCaptionBarButton", "CMFCVisualManagerOffice2007 [MFC], OnFillHighlightedArea", "CMFCVisualManagerOffice2007 [MFC], OnFillMiniFrameCaption", "CMFCVisualManagerOffice2007 [MFC], OnFillOutlookBarCaption", "CMFCVisualManagerOffice2007 [MFC], OnFillOutlookPageButton", "CMFCVisualManagerOffice2007 [MFC], OnFillPopupWindowBackground", "CMFCVisualManagerOffice2007 [MFC], OnFillRibbonButton", "CMFCVisualManagerOffice2007 [MFC], OnFillRibbonEdit", "CMFCVisualManagerOffice2007 [MFC], OnFillRibbonMainPanelButton", "CMFCVisualManagerOffice2007 [MFC], OnFillRibbonMenuFrame", "CMFCVisualManagerOffice2007 [MFC], OnFillRibbonQuickAccessToolBarPopup", "CMFCVisualManagerOffice2007 [MFC], OnFillTab", "CMFCVisualManagerOffice2007 [MFC], OnHighlightMenuItem", "CMFCVisualManagerOffice2007 [MFC], OnHighlightRarelyUsedMenuItems", "CMFCVisualManagerOffice2007 [MFC], OnNcActivate", "CMFCVisualManagerOffice2007 [MFC], OnNcPaint", "CMFCVisualManagerOffice2007 [MFC], OnSetWindowRegion", "CMFCVisualManagerOffice2007 [MFC], OnUpdateSystemColors", "CMFCVisualManagerOffice2007 [MFC], SetResourceHandle"] -ms.assetid: fb687c74-6d08-4c72-8acf-27f75dda6d6b --- # CMFCVisualManagerOffice2007 Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CMFCVisualManagerOffice2007` gives an application a Microsoft Office 2007 appearance. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcvisualmanagerofficexp-class.md b/docs/mfc/reference/cmfcvisualmanagerofficexp-class.md index ed358d6d4d4..4639abf5286 100644 --- a/docs/mfc/reference/cmfcvisualmanagerofficexp-class.md +++ b/docs/mfc/reference/cmfcvisualmanagerofficexp-class.md @@ -4,10 +4,12 @@ title: "CMFCVisualManagerOfficeXP Class" ms.date: "11/04/2016" f1_keywords: ["CMFCVisualManagerOfficeXP"] helpviewer_keywords: ["CMFCVisualManagerOfficeXP class [MFC]"] -ms.assetid: 46b6f854-37c2-4836-8f56-5cb6ff63c9af --- # CMFCVisualManagerOfficeXP Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCVisualManagerOfficeXP` gives an application a Microsoft Office XP appearance. ## Syntax diff --git a/docs/mfc/reference/cmfcvisualmanagervs2005-class.md b/docs/mfc/reference/cmfcvisualmanagervs2005-class.md index fc636e47285..0fd63adf20a 100644 --- a/docs/mfc/reference/cmfcvisualmanagervs2005-class.md +++ b/docs/mfc/reference/cmfcvisualmanagervs2005-class.md @@ -4,10 +4,12 @@ title: "CMFCVisualManagerVS2005 Class" ms.date: "11/04/2016" f1_keywords: ["CMFCVisualManagerVS2005", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::GetDockingTabsBordersSize", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::GetMDITabsBordersSize", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::GetPropertyGridGroupColor", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::GetTabFrameColors", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::HasOverlappedAutoHideButtons", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnDrawAutoHideButtonBorder", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnDrawCaptionButton", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnDrawPaneCaption", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnDrawSeparator", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnDrawTab", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnDrawToolBoxFrame", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnEraseTabsArea", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnFillAutoHideButtonBackground", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnFillHighlightedArea", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnFillMiniFrameCaption", "AFXVISUALMANAGERVS2005/CMFCVisualManagerVS2005::OnUpdateSystemColors"] helpviewer_keywords: ["CMFCVisualManagerVS2005 [MFC], GetDockingTabsBordersSize", "CMFCVisualManagerVS2005 [MFC], GetMDITabsBordersSize", "CMFCVisualManagerVS2005 [MFC], GetPropertyGridGroupColor", "CMFCVisualManagerVS2005 [MFC], GetTabFrameColors", "CMFCVisualManagerVS2005 [MFC], HasOverlappedAutoHideButtons", "CMFCVisualManagerVS2005 [MFC], OnDrawAutoHideButtonBorder", "CMFCVisualManagerVS2005 [MFC], OnDrawCaptionButton", "CMFCVisualManagerVS2005 [MFC], OnDrawPaneCaption", "CMFCVisualManagerVS2005 [MFC], OnDrawSeparator", "CMFCVisualManagerVS2005 [MFC], OnDrawTab", "CMFCVisualManagerVS2005 [MFC], OnDrawToolBoxFrame", "CMFCVisualManagerVS2005 [MFC], OnEraseTabsArea", "CMFCVisualManagerVS2005 [MFC], OnFillAutoHideButtonBackground", "CMFCVisualManagerVS2005 [MFC], OnFillHighlightedArea", "CMFCVisualManagerVS2005 [MFC], OnFillMiniFrameCaption", "CMFCVisualManagerVS2005 [MFC], OnUpdateSystemColors"] -ms.assetid: ea39b9ae-327e-4a51-bce7-dc84c78f005b --- # CMFCVisualManagerVS2005 Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CMFCVisualManagerVS2005` gives an application a Microsoft Visual Studio 2005 appearance. ## Syntax @@ -23,7 +25,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/cmfcvisualmanagerwindows-class.md b/docs/mfc/reference/cmfcvisualmanagerwindows-class.md index 6579ed1aba2..0149e9a9721 100644 --- a/docs/mfc/reference/cmfcvisualmanagerwindows-class.md +++ b/docs/mfc/reference/cmfcvisualmanagerwindows-class.md @@ -4,10 +4,12 @@ title: "CMFCVisualManagerWindows Class" ms.date: "11/04/2016" f1_keywords: ["CMFCVisualManagerWindows", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::AlwaysHighlight3DTabs", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::DrawComboBorderWinXP", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::DrawComboDropButtonWinXP", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::DrawPushButtonWinXP", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::GetButtonExtraBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::GetCaptionButtonExtraBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::GetDockingPaneCaptionExtraHeight", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::GetHighlightedMenuItemTextColor", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::GetPopupMenuGap", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::GetToolbarButtonTextColor", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::IsDefaultWinXPPopupButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::IsHighlightWholeMenuItem", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::IsOfficeStyleMenus", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::IsOfficeXPStyleMenus", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::IsWindowsThemingSupported", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::IsWinXPThemeAvailable", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawBarGripper", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawBrowseButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawButtonBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawButtonSeparator", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawCaptionButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawCaptionButtonIcon", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawCheckBoxEx", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawComboBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawComboDropButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawControlBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawEditBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawExpandingBox", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawFloatingToolbarBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawHeaderCtrlBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawHeaderCtrlSortArrow", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawMenuBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawMenuSystemButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawMiniFrameBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawOutlookPageButtonBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawPaneBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawPaneCaption", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawPopupWindowButtonBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawScrollButtons", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawSeparator", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawSpinButtons", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawStatusBarPaneBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawStatusBarProgress", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawStatusBarSizeBox", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawTab", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawTabCloseButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawTabsButtonBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawTask", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawTasksGroupAreaBorder", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawTasksGroupCaption", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnDrawTearOffCaption", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnErasePopupWindowButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnEraseTabsArea", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnEraseTabsButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnEraseTabsFrame", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnFillBarBackground", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnFillButtonInterior", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnFillCommandsListBackground", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnFillMiniFrameCaption", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnFillOutlookPageButton", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnFillTasksGroupInterior", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnFillTasksPaneBackground", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnHighlightMenuItem", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnHighlightRarelyUsedMenuItems", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::OnUpdateSystemColors", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::SetOfficeStyleMenus", "AFXVISUALMANAGERWINDOWS/CMFCVisualManagerWindows::m_b3DTabsXPTheme"] helpviewer_keywords: ["CMFCVisualManagerWindows [MFC], AlwaysHighlight3DTabs", "CMFCVisualManagerWindows [MFC], DrawComboBorderWinXP", "CMFCVisualManagerWindows [MFC], DrawComboDropButtonWinXP", "CMFCVisualManagerWindows [MFC], DrawPushButtonWinXP", "CMFCVisualManagerWindows [MFC], GetButtonExtraBorder", "CMFCVisualManagerWindows [MFC], GetCaptionButtonExtraBorder", "CMFCVisualManagerWindows [MFC], GetDockingPaneCaptionExtraHeight", "CMFCVisualManagerWindows [MFC], GetHighlightedMenuItemTextColor", "CMFCVisualManagerWindows [MFC], GetPopupMenuGap", "CMFCVisualManagerWindows [MFC], GetToolbarButtonTextColor", "CMFCVisualManagerWindows [MFC], IsDefaultWinXPPopupButton", "CMFCVisualManagerWindows [MFC], IsHighlightWholeMenuItem", "CMFCVisualManagerWindows [MFC], IsOfficeStyleMenus", "CMFCVisualManagerWindows [MFC], IsOfficeXPStyleMenus", "CMFCVisualManagerWindows [MFC], IsWindowsThemingSupported", "CMFCVisualManagerWindows [MFC], IsWinXPThemeAvailable", "CMFCVisualManagerWindows [MFC], OnDrawBarGripper", "CMFCVisualManagerWindows [MFC], OnDrawBrowseButton", "CMFCVisualManagerWindows [MFC], OnDrawButtonBorder", "CMFCVisualManagerWindows [MFC], OnDrawButtonSeparator", "CMFCVisualManagerWindows [MFC], OnDrawCaptionButton", "CMFCVisualManagerWindows [MFC], OnDrawCaptionButtonIcon", "CMFCVisualManagerWindows [MFC], OnDrawCheckBoxEx", "CMFCVisualManagerWindows [MFC], OnDrawComboBorder", "CMFCVisualManagerWindows [MFC], OnDrawComboDropButton", "CMFCVisualManagerWindows [MFC], OnDrawControlBorder", "CMFCVisualManagerWindows [MFC], OnDrawEditBorder", "CMFCVisualManagerWindows [MFC], OnDrawExpandingBox", "CMFCVisualManagerWindows [MFC], OnDrawFloatingToolbarBorder", "CMFCVisualManagerWindows [MFC], OnDrawHeaderCtrlBorder", "CMFCVisualManagerWindows [MFC], OnDrawHeaderCtrlSortArrow", "CMFCVisualManagerWindows [MFC], OnDrawMenuBorder", "CMFCVisualManagerWindows [MFC], OnDrawMenuSystemButton", "CMFCVisualManagerWindows [MFC], OnDrawMiniFrameBorder", "CMFCVisualManagerWindows [MFC], OnDrawOutlookPageButtonBorder", "CMFCVisualManagerWindows [MFC], OnDrawPaneBorder", "CMFCVisualManagerWindows [MFC], OnDrawPaneCaption", "CMFCVisualManagerWindows [MFC], OnDrawPopupWindowButtonBorder", "CMFCVisualManagerWindows [MFC], OnDrawScrollButtons", "CMFCVisualManagerWindows [MFC], OnDrawSeparator", "CMFCVisualManagerWindows [MFC], OnDrawSpinButtons", "CMFCVisualManagerWindows [MFC], OnDrawStatusBarPaneBorder", "CMFCVisualManagerWindows [MFC], OnDrawStatusBarProgress", "CMFCVisualManagerWindows [MFC], OnDrawStatusBarSizeBox", "CMFCVisualManagerWindows [MFC], OnDrawTab", "CMFCVisualManagerWindows [MFC], OnDrawTabCloseButton", "CMFCVisualManagerWindows [MFC], OnDrawTabsButtonBorder", "CMFCVisualManagerWindows [MFC], OnDrawTask", "CMFCVisualManagerWindows [MFC], OnDrawTasksGroupAreaBorder", "CMFCVisualManagerWindows [MFC], OnDrawTasksGroupCaption", "CMFCVisualManagerWindows [MFC], OnDrawTearOffCaption", "CMFCVisualManagerWindows [MFC], OnErasePopupWindowButton", "CMFCVisualManagerWindows [MFC], OnEraseTabsArea", "CMFCVisualManagerWindows [MFC], OnEraseTabsButton", "CMFCVisualManagerWindows [MFC], OnEraseTabsFrame", "CMFCVisualManagerWindows [MFC], OnFillBarBackground", "CMFCVisualManagerWindows [MFC], OnFillButtonInterior", "CMFCVisualManagerWindows [MFC], OnFillCommandsListBackground", "CMFCVisualManagerWindows [MFC], OnFillMiniFrameCaption", "CMFCVisualManagerWindows [MFC], OnFillOutlookPageButton", "CMFCVisualManagerWindows [MFC], OnFillTasksGroupInterior", "CMFCVisualManagerWindows [MFC], OnFillTasksPaneBackground", "CMFCVisualManagerWindows [MFC], OnHighlightMenuItem", "CMFCVisualManagerWindows [MFC], OnHighlightRarelyUsedMenuItems", "CMFCVisualManagerWindows [MFC], OnUpdateSystemColors", "CMFCVisualManagerWindows [MFC], SetOfficeStyleMenus", "CMFCVisualManagerWindows [MFC], m_b3DTabsXPTheme"] -ms.assetid: 568b6e9e-8e67-4477-9a3d-2981cbd09861 --- # CMFCVisualManagerWindows Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CMFCVisualManagerWindows` mimics the appearance of Microsoft Windows XP or Microsoft Vista when the user selects a Windows XP or Vista theme. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmfcvisualmanagerwindows7-class.md b/docs/mfc/reference/cmfcvisualmanagerwindows7-class.md index d354cd2cc54..d2e9935e2e3 100644 --- a/docs/mfc/reference/cmfcvisualmanagerwindows7-class.md +++ b/docs/mfc/reference/cmfcvisualmanagerwindows7-class.md @@ -4,10 +4,12 @@ title: "CMFCVisualManagerWindows7 Class" ms.date: "03/27/2019" f1_keywords: ["CMFCVisualManagerWindows7", "AFXVISUALMANAGERWINDOWS7/CMFCVisualManagerWindows7", "AFXVISUALMANAGERWINDOWS7/CMFCVisualManagerWindows7::CMFCVisualManagerWindows7", "AFXVISUALMANAGERWINDOWS7/CMFCVisualManagerWindows7::GetRibbonEditBackgroundColor", "AFXVISUALMANAGERWINDOWS7/CMFCVisualManagerWindows7::OnFillMenuImageRect"] helpviewer_keywords: ["CMFCVisualManagerWindows7 Class [MFC]"] -ms.assetid: e8d87df1-0c09-4b58-8ade-4e911f796e42 --- # CMFCVisualManagerWindows7 Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCVisualManagerWindows7` gives an application the appearance of a Windows 7 application. ## Syntax diff --git a/docs/mfc/reference/cmfcwindowsmanagerdialog-class.md b/docs/mfc/reference/cmfcwindowsmanagerdialog-class.md index 3e82d4901f0..6e5f503419b 100644 --- a/docs/mfc/reference/cmfcwindowsmanagerdialog-class.md +++ b/docs/mfc/reference/cmfcwindowsmanagerdialog-class.md @@ -4,10 +4,12 @@ title: "CMFCWindowsManagerDialog Class" ms.date: "11/04/2016" f1_keywords: ["CMFCWindowsManagerDialog", "AFXWINDOWSMANAGERDIALOG/CMFCWindowsManagerDialog", "AFXWINDOWSMANAGERDIALOG/CMFCWindowsManagerDialog::CMFCWindowsManagerDialog"] helpviewer_keywords: ["CMFCWindowsManagerDialog [MFC], CMFCWindowsManagerDialog"] -ms.assetid: 35b4b0db-33c4-4b22-94d8-5e3396341340 --- # CMFCWindowsManagerDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMFCWindowsManagerDialog` object enables a user to manage MDI child windows in a MDI application. ## Syntax diff --git a/docs/mfc/reference/cminiframewnd-class.md b/docs/mfc/reference/cminiframewnd-class.md index c62e43effd8..ba3f3abbdb4 100644 --- a/docs/mfc/reference/cminiframewnd-class.md +++ b/docs/mfc/reference/cminiframewnd-class.md @@ -4,10 +4,12 @@ title: "CMiniFrameWnd Class" ms.date: "11/04/2016" f1_keywords: ["CMiniFrameWnd", "AFXWIN/CMiniFrameWnd", "AFXWIN/CMiniFrameWnd::CMiniFrameWnd", "AFXWIN/CMiniFrameWnd::Create", "AFXWIN/CMiniFrameWnd::CreateEx"] helpviewer_keywords: ["CMiniFrameWnd [MFC], CMiniFrameWnd", "CMiniFrameWnd [MFC], Create", "CMiniFrameWnd [MFC], CreateEx"] -ms.assetid: b8f534ed-0532-4d8e-9657-5595cf677749 --- # CMiniFrameWnd Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a half-height frame window typically seen around floating toolbars. ## Syntax diff --git a/docs/mfc/reference/cmonikerfile-class.md b/docs/mfc/reference/cmonikerfile-class.md index 56e7b9dac14..74ff22caf0c 100644 --- a/docs/mfc/reference/cmonikerfile-class.md +++ b/docs/mfc/reference/cmonikerfile-class.md @@ -4,10 +4,12 @@ title: "CMonikerFile Class" ms.date: "11/04/2016" f1_keywords: ["CMonikerFile", "AFXOLE/CMonikerFile", "AFXOLE/CMonikerFile::CMonikerFile", "AFXOLE/CMonikerFile::Close", "AFXOLE/CMonikerFile::Detach", "AFXOLE/CMonikerFile::GetMoniker", "AFXOLE/CMonikerFile::Open", "AFXOLE/CMonikerFile::CreateBindContext"] helpviewer_keywords: ["CMonikerFile [MFC], CMonikerFile", "CMonikerFile [MFC], Close", "CMonikerFile [MFC], Detach", "CMonikerFile [MFC], GetMoniker", "CMonikerFile [MFC], Open", "CMonikerFile [MFC], CreateBindContext"] -ms.assetid: 87be5966-f4f7-4235-bce2-1fa39e9417de --- # CMonikerFile Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a stream of data ( [IStream](/windows/win32/api/objidl/nn-objidl-istream)) named by an [IMoniker](/windows/win32/api/objidl/nn-objidl-imoniker). ## Syntax diff --git a/docs/mfc/reference/cmonthcalctrl-class.md b/docs/mfc/reference/cmonthcalctrl-class.md index 75cfdbbb96e..033259412cf 100644 --- a/docs/mfc/reference/cmonthcalctrl-class.md +++ b/docs/mfc/reference/cmonthcalctrl-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the functionality of a month calendar control. ## Syntax @@ -305,7 +307,8 @@ The next code example reports which view the month calendar control currently di Retrieves the system time as indicated by the currently-selected date. ``` -BOOL GetCurSel(COleDateTime& refDateTime) const; BOOL GetCurSel(CTime& refDateTime) const; +BOOL GetCurSel(COleDateTime& refDateTime) const; +BOOL GetCurSel(CTime& refDateTime) const; BOOL GetCurSel(LPSYSTEMTIME pDateTime) const; ``` @@ -320,7 +323,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 @@ -596,7 +599,8 @@ In MFC's implementation of `GetSelRange`, you can specify `COleDateTime` usage, Retrieves the date information for the date specified as "today" for a month calendar control. ``` -BOOL GetToday(COleDateTime& refDateTime) const; BOOL GetToday(COleDateTime& refDateTime) const; +BOOL GetToday(COleDateTime& refDateTime) const; +BOOL GetToday(COleDateTime& refDateTime) const; BOOL GetToday(LPSYSTEMTIME pDateTime) const; ``` diff --git a/docs/mfc/reference/cmousemanager-class.md b/docs/mfc/reference/cmousemanager-class.md index 10ca342ab29..1f133903fae 100644 --- a/docs/mfc/reference/cmousemanager-class.md +++ b/docs/mfc/reference/cmousemanager-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows a user to associate different commands with a particular [CView](../../mfc/reference/cview-class.md) object when the user double-clicks inside that view. ## Syntax @@ -33,7 +35,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 +248,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/cmultidoctemplate-class.md b/docs/mfc/reference/cmultidoctemplate-class.md index c103e3e9a82..532ac98e884 100644 --- a/docs/mfc/reference/cmultidoctemplate-class.md +++ b/docs/mfc/reference/cmultidoctemplate-class.md @@ -4,10 +4,12 @@ title: "CMultiDocTemplate Class" ms.date: "11/04/2016" f1_keywords: ["CMultiDocTemplate", "AFXWIN/CMultiDocTemplate", "AFXWIN/CMultiDocTemplate::CMultiDocTemplate"] helpviewer_keywords: ["CMultiDocTemplate [MFC], CMultiDocTemplate"] -ms.assetid: 5b8aa328-e461-41d0-b388-00594535e119 --- # CMultiDocTemplate Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Defines a document template that implements the multiple document interface (MDI). ## Syntax diff --git a/docs/mfc/reference/cmultilock-class.md b/docs/mfc/reference/cmultilock-class.md index c59e02672be..f04a88f1b54 100644 --- a/docs/mfc/reference/cmultilock-class.md +++ b/docs/mfc/reference/cmultilock-class.md @@ -4,10 +4,12 @@ title: "CMultiLock Class" ms.date: "11/04/2016" f1_keywords: ["CMultiLock", "AFXMT/CMultiLock", "AFXMT/CMultiLock::CMultiLock", "AFXMT/CMultiLock::IsLocked", "AFXMT/CMultiLock::Lock", "AFXMT/CMultiLock::Unlock"] helpviewer_keywords: ["CMultiLock [MFC], CMultiLock", "CMultiLock [MFC], IsLocked", "CMultiLock [MFC], Lock", "CMultiLock [MFC], Unlock"] -ms.assetid: c5b7c78b-1f81-4387-b7dd-2c813c5b6b61 --- # CMultiLock Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents the access-control mechanism used in controlling access to resources in a multithreaded program. ## Syntax diff --git a/docs/mfc/reference/cmultipagedhtmldialog-class.md b/docs/mfc/reference/cmultipagedhtmldialog-class.md index b47ead03872..328f588d532 100644 --- a/docs/mfc/reference/cmultipagedhtmldialog-class.md +++ b/docs/mfc/reference/cmultipagedhtmldialog-class.md @@ -4,10 +4,12 @@ title: "CMultiPageDHtmlDialog Class" ms.date: "03/27/2019" f1_keywords: ["CMultiPageDHtmlDialog", "AFXDHTML/CMultiPageDHtmlDialog", "AFXDHTML/CMultiPageDHtmlDialog::CMultiPageDHtmlDialog"] helpviewer_keywords: ["CMultiPageDHtmlDialog [MFC], CMultiPageDHtmlDialog"] -ms.assetid: 971accc1-824d-4df4-b4c1-b1a20e0f7e4f --- # CMultiPageDHtmlDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A multipage dialog displays multiple HTML pages sequentially and handles the events from each page. ## Syntax diff --git a/docs/mfc/reference/cmultipaneframewnd-class.md b/docs/mfc/reference/cmultipaneframewnd-class.md index 67427e554bf..f19fe3809ba 100644 --- a/docs/mfc/reference/cmultipaneframewnd-class.md +++ b/docs/mfc/reference/cmultipaneframewnd-class.md @@ -4,10 +4,12 @@ title: "CMultiPaneFrameWnd Class" ms.date: "11/04/2016" f1_keywords: ["CMultiPaneFrameWnd", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::AddPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::AddRecentPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::AdjustLayout", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::AdjustPaneFrames", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::CalcExpectedDockedRect", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::CanBeAttached", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::CanBeDockedToPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::CheckGripperVisibility", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::CloseMiniFrame", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::ConvertToTabbedDocument", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::DockFrame", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::DockPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::DockRecentPaneToMainFrame", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::GetCaptionText", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::GetPaneContainerManager", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::GetFirstVisiblePane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::GetPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::GetPaneCount", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::GetVisiblePaneCount", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::InsertPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::LoadState", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::OnDockToRecentPos", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::OnKillRollUpTimer", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::OnPaneRecalcLayout", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::OnSetRollUpTimer", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::OnShowPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::PaneFromPoint", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::RemoveNonValidPanes", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::RemovePane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::ReplacePane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::SaveState", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::Serialize", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::SetDockState", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::SetLastFocusedPane", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::SetPreDockState", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::StoreRecentDockSiteInfo", "AFXMULTIPANEFRAMEWND/CMultiPaneFrameWnd::StoreRecentTabRelatedInfo"] helpviewer_keywords: ["CMultiPaneFrameWnd [MFC], AddPane", "CMultiPaneFrameWnd [MFC], AddRecentPane", "CMultiPaneFrameWnd [MFC], AdjustLayout", "CMultiPaneFrameWnd [MFC], AdjustPaneFrames", "CMultiPaneFrameWnd [MFC], CalcExpectedDockedRect", "CMultiPaneFrameWnd [MFC], CanBeAttached", "CMultiPaneFrameWnd [MFC], CanBeDockedToPane", "CMultiPaneFrameWnd [MFC], CheckGripperVisibility", "CMultiPaneFrameWnd [MFC], CloseMiniFrame", "CMultiPaneFrameWnd [MFC], ConvertToTabbedDocument", "CMultiPaneFrameWnd [MFC], DockFrame", "CMultiPaneFrameWnd [MFC], DockPane", "CMultiPaneFrameWnd [MFC], DockRecentPaneToMainFrame", "CMultiPaneFrameWnd [MFC], GetCaptionText", "CMultiPaneFrameWnd [MFC], GetPaneContainerManager", "CMultiPaneFrameWnd [MFC], GetFirstVisiblePane", "CMultiPaneFrameWnd [MFC], GetPane", "CMultiPaneFrameWnd [MFC], GetPaneCount", "CMultiPaneFrameWnd [MFC], GetVisiblePaneCount", "CMultiPaneFrameWnd [MFC], InsertPane", "CMultiPaneFrameWnd [MFC], LoadState", "CMultiPaneFrameWnd [MFC], OnDockToRecentPos", "CMultiPaneFrameWnd [MFC], OnKillRollUpTimer", "CMultiPaneFrameWnd [MFC], OnPaneRecalcLayout", "CMultiPaneFrameWnd [MFC], OnSetRollUpTimer", "CMultiPaneFrameWnd [MFC], OnShowPane", "CMultiPaneFrameWnd [MFC], PaneFromPoint", "CMultiPaneFrameWnd [MFC], RemoveNonValidPanes", "CMultiPaneFrameWnd [MFC], RemovePane", "CMultiPaneFrameWnd [MFC], ReplacePane", "CMultiPaneFrameWnd [MFC], SaveState", "CMultiPaneFrameWnd [MFC], Serialize", "CMultiPaneFrameWnd [MFC], SetDockState", "CMultiPaneFrameWnd [MFC], SetLastFocusedPane", "CMultiPaneFrameWnd [MFC], SetPreDockState", "CMultiPaneFrameWnd [MFC], StoreRecentDockSiteInfo", "CMultiPaneFrameWnd [MFC], StoreRecentTabRelatedInfo"] -ms.assetid: 989a548e-0d70-46b7-a513-8cf740e1be3e --- # CMultiPaneFrameWnd Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CMultiPaneFrameWnd` class 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. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cmutex-class.md b/docs/mfc/reference/cmutex-class.md index a7267ffb085..e7a025cf985 100644 --- a/docs/mfc/reference/cmutex-class.md +++ b/docs/mfc/reference/cmutex-class.md @@ -4,10 +4,12 @@ title: "CMutex Class" ms.date: "11/04/2016" f1_keywords: ["CMutex", "AFXMT/CMutex", "AFXMT/CMutex::CMutex"] helpviewer_keywords: ["CMutex [MFC], CMutex"] -ms.assetid: 6330c050-4f01-4195-a099-2029b92f8cf1 --- # CMutex Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a "mutex" — a synchronization object that allows one thread mutually exclusive access to a resource. ## Syntax diff --git a/docs/mfc/reference/cnetaddressctrl-class.md b/docs/mfc/reference/cnetaddressctrl-class.md index 961b95a3943..97655606205 100644 --- a/docs/mfc/reference/cnetaddressctrl-class.md +++ b/docs/mfc/reference/cnetaddressctrl-class.md @@ -4,10 +4,12 @@ title: "CNetAddressCtrl Class" ms.date: "11/19/2018" f1_keywords: ["CNetAddressCtrl", "AFXCMN/CNetAddressCtrl", "AFXCMN/CNetAddressCtrl::CNetAddressCtrl", "AFXCMN/CNetAddressCtrl::Create", "AFXCMN/CNetAddressCtrl::CreateEx", "AFXCMN/CNetAddressCtrl::DisplayErrorTip", "AFXCMN/CNetAddressCtrl::GetAddress", "AFXCMN/CNetAddressCtrl::GetAllowType", "AFXCMN/CNetAddressCtrl::SetAllowType"] helpviewer_keywords: ["CNetAddressCtrl [MFC], CNetAddressCtrl", "CNetAddressCtrl [MFC], Create", "CNetAddressCtrl [MFC], CreateEx", "CNetAddressCtrl [MFC], DisplayErrorTip", "CNetAddressCtrl [MFC], GetAddress", "CNetAddressCtrl [MFC], GetAllowType", "CNetAddressCtrl [MFC], SetAllowType"] -ms.assetid: cb4c6aca-3f49-4b52-b76c-65f57096155b --- # CNetAddressCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax diff --git a/docs/mfc/reference/cnotsupportedexception-class.md b/docs/mfc/reference/cnotsupportedexception-class.md index 91c32de3a13..4cb7a08ce51 100644 --- a/docs/mfc/reference/cnotsupportedexception-class.md +++ b/docs/mfc/reference/cnotsupportedexception-class.md @@ -4,10 +4,12 @@ title: "CNotSupportedException Class" ms.date: "11/04/2016" f1_keywords: ["CNotSupportedException", "AFX/CNotSupportedException", "AFX/CNotSupportedException::CNotSupportedException"] helpviewer_keywords: ["CNotSupportedException [MFC], CNotSupportedException"] -ms.assetid: e517391b-eb94-4c39-ae32-87b45bf7d624 --- # CNotSupportedException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an exception that is the result of a request for an unsupported feature. ## Syntax diff --git a/docs/mfc/reference/cobarray-class.md b/docs/mfc/reference/cobarray-class.md index 2f8d493a340..71356304785 100644 --- a/docs/mfc/reference/cobarray-class.md +++ b/docs/mfc/reference/cobarray-class.md @@ -1,13 +1,15 @@ --- title: "CObArray Class" -description: "API reference for the `CObArray` `MFC` class which stores `CObject` pointers in an array." -ms.date: "08/27/2020" +description: "API reference for the `CObArray` MFC class which stores `CObject` pointers in an array." +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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports arrays of `CObject` pointers. ## Syntax @@ -294,7 +296,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 +327,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/cobject-class.md b/docs/mfc/reference/cobject-class.md index 1f712952c98..0eb328cc399 100644 --- a/docs/mfc/reference/cobject-class.md +++ b/docs/mfc/reference/cobject-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CObject [MFC], CObject", "CObject [MFC], AssertValid", "C --- # `CObject` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The principal base class for the Microsoft Foundation Class Library. ## Syntax diff --git a/docs/mfc/reference/coblist-class.md b/docs/mfc/reference/coblist-class.md index e7e91149f98..0e7810fc3d7 100644 --- a/docs/mfc/reference/coblist-class.md +++ b/docs/mfc/reference/coblist-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CObList [MFC], CObList", "CObList [MFC], AddHead", "CObLi --- # `CObList` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports ordered lists of nonunique `CObject` pointers accessible sequentially or by pointer value. ## Syntax @@ -33,12 +36,12 @@ class CObList : public CObject |[`CObList::FindIndex`](#findindex)|Gets the position of an element specified by a zero-based index.| |[`CObList::GetAt`](#getat)|Gets the element at a given position.| |[`CObList::GetCount`](#getcount)|Returns the number of elements in this list.| -|[`CObList::GetHead`](#gethead)|Returns the head element of the list (can’t be empty).| +|[`CObList::GetHead`](#gethead)|Returns the head element of the list (can't be empty).| |[`CObList::GetHeadPosition`](#getheadposition)|Returns the position of the head element of the list.| |[`CObList::GetNext`](#getnext)|Gets the next element for iterating.| |[`CObList::GetPrev`](#getprev)|Gets the previous element for iterating.| |[`CObList::GetSize`](#getsize)|Returns the number of elements in this list.| -|[`CObList::GetTail`](#gettail)|Returns the tail element of the list (can’t be empty).| +|[`CObList::GetTail`](#gettail)|Returns the tail element of the list (can't be empty).| |[`CObList::GetTailPosition`](#gettailposition)|Returns the position of the tail element of the list.| |[`CObList::InsertAfter`](#insertafter)|Inserts a new element after a given position.| |[`CObList::InsertBefore`](#insertbefore)|Inserts a new element before a given position.| @@ -299,7 +302,7 @@ See the return value description for [`GetHead`](#gethead). ### Remarks -It isn't the same as an index, and you can’t operate on a `POSITION` value yourself. `GetAt` retrieves the `CObject` pointer associated with a given position. +It isn't the same as an index, and you can't operate on a `POSITION` value yourself. `GetAt` retrieves the `CObject` pointer associated with a given position. You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. @@ -840,7 +843,7 @@ The `CObject` pointer to be written to the list. ### Remarks -A variable of type `POSITION` is a key for the list. It isn't the same as an index, and you can’t operate on a `POSITION` value yourself. `SetAt` writes the `CObject` pointer to the specified position in the list. +A variable of type `POSITION` is a key for the list. It isn't the same as an index, and you can't operate on a `POSITION` value yourself. `SetAt` writes the `CObject` pointer to the specified position in the list. You must ensure that your `POSITION` value represents a valid position in the list. If it's invalid, then the Debug version of the Microsoft Foundation Class Library asserts. diff --git a/docs/mfc/reference/coccmanager-class.md b/docs/mfc/reference/coccmanager-class.md index 8660c985c55..18a35b36a4a 100644 --- a/docs/mfc/reference/coccmanager-class.md +++ b/docs/mfc/reference/coccmanager-class.md @@ -4,10 +4,12 @@ title: "COccManager Class" ms.date: "11/04/2016" f1_keywords: ["COccManager", "AFXOCC/COccManager", "AFXOCC/COccManager::CreateContainer", "AFXOCC/COccManager::CreateDlgControls", "AFXOCC/COccManager::CreateSite", "AFXOCC/COccManager::GetDefBtnCode", "AFXOCC/COccManager::IsDialogMessage", "AFXOCC/COccManager::IsLabelControl", "AFXOCC/COccManager::IsMatchingMnemonic", "AFXOCC/COccManager::OnEvent", "AFXOCC/COccManager::PostCreateDialog", "AFXOCC/COccManager::PreCreateDialog", "AFXOCC/COccManager::SetDefaultButton", "AFXOCC/COccManager::SplitDialogTemplate"] helpviewer_keywords: ["COccManager [MFC], CreateContainer", "COccManager [MFC], CreateDlgControls", "COccManager [MFC], CreateSite", "COccManager [MFC], GetDefBtnCode", "COccManager [MFC], IsDialogMessage", "COccManager [MFC], IsLabelControl", "COccManager [MFC], IsMatchingMnemonic", "COccManager [MFC], OnEvent", "COccManager [MFC], PostCreateDialog", "COccManager [MFC], PreCreateDialog", "COccManager [MFC], SetDefaultButton", "COccManager [MFC], SplitDialogTemplate"] -ms.assetid: 7d47aeed-d1ab-48e3-b4cf-d429718e370a --- # COccManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages various custom control sites; implemented by `COleControlContainer` and `COleControlSite` objects. ## Syntax diff --git a/docs/mfc/reference/codbcfieldinfo-structure.md b/docs/mfc/reference/codbcfieldinfo-structure.md index 03a4573f045..ea89688707e 100644 --- a/docs/mfc/reference/codbcfieldinfo-structure.md +++ b/docs/mfc/reference/codbcfieldinfo-structure.md @@ -4,10 +4,12 @@ title: "CODBCFieldInfo Structure" ms.date: "11/04/2016" f1_keywords: ["CODBCFieldInfo"] helpviewer_keywords: ["ODBC [MFC], data source information", "CODBCFieldInfo structure [MFC]"] -ms.assetid: 92598b4f-facc-4108-b282-63a179ff79ab --- # CODBCFieldInfo Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CODBCFieldInfo` structure contains information about the fields in an ODBC data source. ## Syntax diff --git a/docs/mfc/reference/codesnippet/CPP/cbutton-class_10.h b/docs/mfc/reference/codesnippet/CPP/cbutton-class_10.h index e34c0f5e239..c428acdc935 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/cmfcrebar-class_2.cpp b/docs/mfc/reference/codesnippet/CPP/cmfcrebar-class_2.cpp index bd1a7ee4322..8827522e7ca 100644 --- a/docs/mfc/reference/codesnippet/CPP/cmfcrebar-class_2.cpp +++ b/docs/mfc/reference/codesnippet/CPP/cmfcrebar-class_2.cpp @@ -1,4 +1,4 @@ -// Each rebar pane will ocupy its own row: +// Each rebar pane will occupy its own row: DWORD dwStyle = RBBS_GRIPPERALWAYS | RBBS_FIXEDBMP | RBBS_BREAK; // CMFCMenuBar m_wndMenuBar // CMFCToolBar m_wndToolBar diff --git a/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_2.cpp b/docs/mfc/reference/codesnippet/CPP/cmfctoolbarscustomizedialog-class_2.cpp index b6138fdf944..170c9fff5ed 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 bed3f475417..88446128e81 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 78fa084d092..e01076e8ae9 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 8d26f622010..faf40bf8581 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/colebusydialog-class.md b/docs/mfc/reference/colebusydialog-class.md index d9d615fe4e1..8a448182cce 100644 --- a/docs/mfc/reference/colebusydialog-class.md +++ b/docs/mfc/reference/colebusydialog-class.md @@ -4,10 +4,12 @@ title: "COleBusyDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleBusyDialog", "AFXODLGS/COleBusyDialog", "AFXODLGS/COleBusyDialog::COleBusyDialog", "AFXODLGS/COleBusyDialog::DoModal", "AFXODLGS/COleBusyDialog::GetSelectionType", "AFXODLGS/COleBusyDialog::m_bz"] helpviewer_keywords: ["COleBusyDialog [MFC], COleBusyDialog", "COleBusyDialog [MFC], DoModal", "COleBusyDialog [MFC], GetSelectionType", "COleBusyDialog [MFC], m_bz"] -ms.assetid: c881a532-9672-4c41-b51b-5ce4a7246a6b --- # COleBusyDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used for the OLE Server Not Responding or Server Busy dialog boxes. ## Syntax diff --git a/docs/mfc/reference/colechangeicondialog-class.md b/docs/mfc/reference/colechangeicondialog-class.md index 4aa41b2f9b8..f3215747770 100644 --- a/docs/mfc/reference/colechangeicondialog-class.md +++ b/docs/mfc/reference/colechangeicondialog-class.md @@ -4,10 +4,12 @@ title: "COleChangeIconDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleChangeIconDialog", "AFXODLGS/COleChangeIconDialog", "AFXODLGS/COleChangeIconDialog::COleChangeIconDialog", "AFXODLGS/COleChangeIconDialog::DoChangeIcon", "AFXODLGS/COleChangeIconDialog::DoModal", "AFXODLGS/COleChangeIconDialog::GetIconicMetafile", "AFXODLGS/COleChangeIconDialog::m_ci"] helpviewer_keywords: ["COleChangeIconDialog [MFC], COleChangeIconDialog", "COleChangeIconDialog [MFC], DoChangeIcon", "COleChangeIconDialog [MFC], DoModal", "COleChangeIconDialog [MFC], GetIconicMetafile", "COleChangeIconDialog [MFC], m_ci"] -ms.assetid: 8d6e131b-ddbb-4dff-a432-f239efda8e3d --- # COleChangeIconDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used for the OLE Change Icon dialog box. ## Syntax diff --git a/docs/mfc/reference/colechangesourcedialog-class.md b/docs/mfc/reference/colechangesourcedialog-class.md index dde0eeca7c4..9b66d040ee1 100644 --- a/docs/mfc/reference/colechangesourcedialog-class.md +++ b/docs/mfc/reference/colechangesourcedialog-class.md @@ -4,10 +4,12 @@ title: "COleChangeSourceDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleChangeSourceDialog", "AFXODLGS/COleChangeSourceDialog", "AFXODLGS/COleChangeSourceDialog::COleChangeSourceDialog", "AFXODLGS/COleChangeSourceDialog::DoModal", "AFXODLGS/COleChangeSourceDialog::GetDisplayName", "AFXODLGS/COleChangeSourceDialog::GetFileName", "AFXODLGS/COleChangeSourceDialog::GetFromPrefix", "AFXODLGS/COleChangeSourceDialog::GetItemName", "AFXODLGS/COleChangeSourceDialog::GetToPrefix", "AFXODLGS/COleChangeSourceDialog::IsValidSource", "AFXODLGS/COleChangeSourceDialog::m_cs"] helpviewer_keywords: ["COleChangeSourceDialog [MFC], COleChangeSourceDialog", "COleChangeSourceDialog [MFC], DoModal", "COleChangeSourceDialog [MFC], GetDisplayName", "COleChangeSourceDialog [MFC], GetFileName", "COleChangeSourceDialog [MFC], GetFromPrefix", "COleChangeSourceDialog [MFC], GetItemName", "COleChangeSourceDialog [MFC], GetToPrefix", "COleChangeSourceDialog [MFC], IsValidSource", "COleChangeSourceDialog [MFC], m_cs"] -ms.assetid: d0e08be7-21ef-45e1-97af-fe27d99e3bac --- # COleChangeSourceDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used for the OLE Change Source dialog box. ## Syntax diff --git a/docs/mfc/reference/coleclientitem-class.md b/docs/mfc/reference/coleclientitem-class.md index 6bbc2c72fcb..6d13579bde0 100644 --- a/docs/mfc/reference/coleclientitem-class.md +++ b/docs/mfc/reference/coleclientitem-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Defines the container interface to OLE items. ## Syntax @@ -1434,7 +1436,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 954ba6ac620..04cb24cec92 100644 --- a/docs/mfc/reference/colecmdui-class.md +++ b/docs/mfc/reference/colecmdui-class.md @@ -4,10 +4,12 @@ title: "COleCmdUI Class" ms.date: 07/24/2020 f1_keywords: ["COleCmdUI", "AFXDOCOBJ/COleCmdUI", "AFXDOCOBJ/COleCmdUI::COleCmdUI", "AFXDOCOBJ/COleCmdUI::Enable", "AFXDOCOBJ/COleCmdUI::SetCheck", "AFXDOCOBJ/COleCmdUI::SetText"] helpviewer_keywords: ["COleCmdUI [MFC], COleCmdUI", "COleCmdUI [MFC], Enable", "COleCmdUI [MFC], SetCheck", "COleCmdUI [MFC], SetText"] -ms.assetid: a2d5ce08-6657-45d3-8673-2a9f32d50eec --- # COleCmdUI Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a method for MFC to update the state of user-interface objects related to the `IOleCommandTarget`-driven features of your application. ## Syntax @@ -34,7 +36,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/colecontrol-class.md b/docs/mfc/reference/colecontrol-class.md index 4fd5fcaaa04..c30561fbf89 100644 --- a/docs/mfc/reference/colecontrol-class.md +++ b/docs/mfc/reference/colecontrol-class.md @@ -4,10 +4,12 @@ title: "COleControl Class" ms.date: "08/27/2018" f1_keywords: ["COleControl", "AFXCTL/COleControl", "AFXCTL/COleControl::COleControl", "AFXCTL/COleControl::AmbientAppearance", "AFXCTL/COleControl::AmbientBackColor", "AFXCTL/COleControl::AmbientDisplayName", "AFXCTL/COleControl::AmbientFont", "AFXCTL/COleControl::AmbientForeColor", "AFXCTL/COleControl::AmbientLocaleID", "AFXCTL/COleControl::AmbientScaleUnits", "AFXCTL/COleControl::AmbientShowGrabHandles", "AFXCTL/COleControl::AmbientShowHatching", "AFXCTL/COleControl::AmbientTextAlign", "AFXCTL/COleControl::AmbientUIDead", "AFXCTL/COleControl::AmbientUserMode", "AFXCTL/COleControl::BoundPropertyChanged", "AFXCTL/COleControl::BoundPropertyRequestEdit", "AFXCTL/COleControl::ClientToParent", "AFXCTL/COleControl::ClipCaretRect", "AFXCTL/COleControl::ControlInfoChanged", "AFXCTL/COleControl::DisplayError", "AFXCTL/COleControl::DoClick", "AFXCTL/COleControl::DoPropExchange", "AFXCTL/COleControl::DoSuperclassPaint", "AFXCTL/COleControl::EnableSimpleFrame", "AFXCTL/COleControl::ExchangeExtent", "AFXCTL/COleControl::ExchangeStockProps", "AFXCTL/COleControl::ExchangeVersion", "AFXCTL/COleControl::FireClick", "AFXCTL/COleControl::FireDblClick", "AFXCTL/COleControl::FireError", "AFXCTL/COleControl::FireEvent", "AFXCTL/COleControl::FireKeyDown", "AFXCTL/COleControl::FireKeyPress", "AFXCTL/COleControl::FireKeyUp", "AFXCTL/COleControl::FireMouseDown", "AFXCTL/COleControl::FireMouseMove", "AFXCTL/COleControl::FireMouseUp", "AFXCTL/COleControl::FireReadyStateChange", "AFXCTL/COleControl::GetActivationPolicy", "AFXCTL/COleControl::GetAmbientProperty", "AFXCTL/COleControl::GetAppearance", "AFXCTL/COleControl::GetBackColor", "AFXCTL/COleControl::GetBorderStyle", "AFXCTL/COleControl::GetCapture", "AFXCTL/COleControl::GetClassID", "AFXCTL/COleControl::GetClientOffset", "AFXCTL/COleControl::GetClientRect", "AFXCTL/COleControl::GetClientSite", "AFXCTL/COleControl::GetControlFlags", "AFXCTL/COleControl::GetControlSize", "AFXCTL/COleControl::GetDC", "AFXCTL/COleControl::GetEnabled", "AFXCTL/COleControl::GetExtendedControl", "AFXCTL/COleControl::GetFocus", "AFXCTL/COleControl::GetFont", "AFXCTL/COleControl::GetFontTextMetrics", "AFXCTL/COleControl::GetForeColor", "AFXCTL/COleControl::GetHwnd", "AFXCTL/COleControl::GetMessageString", "AFXCTL/COleControl::GetNotSupported", "AFXCTL/COleControl::GetReadyState", "AFXCTL/COleControl::GetRectInContainer", "AFXCTL/COleControl::GetStockTextMetrics", "AFXCTL/COleControl::GetText", "AFXCTL/COleControl::GetWindowlessDropTarget", "AFXCTL/COleControl::InitializeIIDs", "AFXCTL/COleControl::InternalGetFont", "AFXCTL/COleControl::InternalGetText", "AFXCTL/COleControl::InternalSetReadyState", "AFXCTL/COleControl::InvalidateControl", "AFXCTL/COleControl::InvalidateRgn", "AFXCTL/COleControl::IsConvertingVBX", "AFXCTL/COleControl::IsModified", "AFXCTL/COleControl::IsOptimizedDraw", "AFXCTL/COleControl::IsSubclassedControl", "AFXCTL/COleControl::Load", "AFXCTL/COleControl::LockInPlaceActive", "AFXCTL/COleControl::OnAmbientPropertyChange", "AFXCTL/COleControl::OnAppearanceChanged", "AFXCTL/COleControl::OnBackColorChanged", "AFXCTL/COleControl::OnBorderStyleChanged", "AFXCTL/COleControl::OnClick", "AFXCTL/COleControl::OnClose", "AFXCTL/COleControl::OnDoVerb", "AFXCTL/COleControl::OnDraw", "AFXCTL/COleControl::OnDrawMetafile", "AFXCTL/COleControl::OnEdit", "AFXCTL/COleControl::OnEnabledChanged", "AFXCTL/COleControl::OnEnumVerbs", "AFXCTL/COleControl::OnEventAdvise", "AFXCTL/COleControl::OnFontChanged", "AFXCTL/COleControl::OnForeColorChanged", "AFXCTL/COleControl::OnFreezeEvents", "AFXCTL/COleControl::OnGetColorSet", "AFXCTL/COleControl::OnGetControlInfo", "AFXCTL/COleControl::OnGetDisplayString", "AFXCTL/COleControl::OnGetInPlaceMenu", "AFXCTL/COleControl::OnGetNaturalExtent", "AFXCTL/COleControl::OnGetPredefinedStrings", "AFXCTL/COleControl::OnGetPredefinedValue", "AFXCTL/COleControl::OnGetViewExtent", "AFXCTL/COleControl::OnGetViewRect", "AFXCTL/COleControl::OnGetViewStatus", "AFXCTL/COleControl::OnHideToolBars", "AFXCTL/COleControl::OnInactiveMouseMove", "AFXCTL/COleControl::OnInactiveSetCursor", "AFXCTL/COleControl::OnKeyDownEvent", "AFXCTL/COleControl::OnKeyPressEvent", "AFXCTL/COleControl::OnKeyUpEvent", "AFXCTL/COleControl::OnMapPropertyToPage", "AFXCTL/COleControl::OnMnemonic", "AFXCTL/COleControl::OnProperties", "AFXCTL/COleControl::OnQueryHitPoint", "AFXCTL/COleControl::OnQueryHitRect", "AFXCTL/COleControl::OnRenderData", "AFXCTL/COleControl::OnRenderFileData", "AFXCTL/COleControl::OnRenderGlobalData", "AFXCTL/COleControl::OnResetState", "AFXCTL/COleControl::OnSetClientSite", "AFXCTL/COleControl::OnSetData", "AFXCTL/COleControl::OnSetExtent", "AFXCTL/COleControl::OnSetObjectRects", "AFXCTL/COleControl::OnShowToolBars", "AFXCTL/COleControl::OnTextChanged", "AFXCTL/COleControl::OnWindowlessMessage", "AFXCTL/COleControl::ParentToClient", "AFXCTL/COleControl::PostModalDialog", "AFXCTL/COleControl::PreModalDialog", "AFXCTL/COleControl::RecreateControlWindow", "AFXCTL/COleControl::Refresh", "AFXCTL/COleControl::ReleaseCapture", "AFXCTL/COleControl::ReleaseDC", "AFXCTL/COleControl::ReparentControlWindow", "AFXCTL/COleControl::ResetStockProps", "AFXCTL/COleControl::ResetVersion", "AFXCTL/COleControl::ScrollWindow", "AFXCTL/COleControl::SelectFontObject", "AFXCTL/COleControl::SelectStockFont", "AFXCTL/COleControl::SerializeExtent", "AFXCTL/COleControl::SerializeStockProps", "AFXCTL/COleControl::SerializeVersion", "AFXCTL/COleControl::SetAppearance", "AFXCTL/COleControl::SetBackColor", "AFXCTL/COleControl::SetBorderStyle", "AFXCTL/COleControl::SetCapture", "AFXCTL/COleControl::SetControlSize", "AFXCTL/COleControl::SetEnabled", "AFXCTL/COleControl::SetFocus", "AFXCTL/COleControl::SetFont", "AFXCTL/COleControl::SetForeColor", "AFXCTL/COleControl::SetInitialSize", "AFXCTL/COleControl::SetModifiedFlag", "AFXCTL/COleControl::SetNotPermitted", "AFXCTL/COleControl::SetNotSupported", "AFXCTL/COleControl::SetRectInContainer", "AFXCTL/COleControl::SetText", "AFXCTL/COleControl::ThrowError", "AFXCTL/COleControl::TransformCoords", "AFXCTL/COleControl::TranslateColor", "AFXCTL/COleControl::WillAmbientsBeValidDuringLoad", "AFXCTL/COleControl::WindowProc", "AFXCTL/COleControl::DrawContent", "AFXCTL/COleControl::DrawMetafile", "AFXCTL/COleControl::IsInvokeAllowed", "AFXCTL/COleControl::SetInitialDataFormats"] helpviewer_keywords: ["COleControl [MFC], COleControl", "COleControl [MFC], AmbientAppearance", "COleControl [MFC], AmbientBackColor", "COleControl [MFC], AmbientDisplayName", "COleControl [MFC], AmbientFont", "COleControl [MFC], AmbientForeColor", "COleControl [MFC], AmbientLocaleID", "COleControl [MFC], AmbientScaleUnits", "COleControl [MFC], AmbientShowGrabHandles", "COleControl [MFC], AmbientShowHatching", "COleControl [MFC], AmbientTextAlign", "COleControl [MFC], AmbientUIDead", "COleControl [MFC], AmbientUserMode", "COleControl [MFC], BoundPropertyChanged", "COleControl [MFC], BoundPropertyRequestEdit", "COleControl [MFC], ClientToParent", "COleControl [MFC], ClipCaretRect", "COleControl [MFC], ControlInfoChanged", "COleControl [MFC], DisplayError", "COleControl [MFC], DoClick", "COleControl [MFC], DoPropExchange", "COleControl [MFC], DoSuperclassPaint", "COleControl [MFC], EnableSimpleFrame", "COleControl [MFC], ExchangeExtent", "COleControl [MFC], ExchangeStockProps", "COleControl [MFC], ExchangeVersion", "COleControl [MFC], FireClick", "COleControl [MFC], FireDblClick", "COleControl [MFC], FireError", "COleControl [MFC], FireEvent", "COleControl [MFC], FireKeyDown", "COleControl [MFC], FireKeyPress", "COleControl [MFC], FireKeyUp", "COleControl [MFC], FireMouseDown", "COleControl [MFC], FireMouseMove", "COleControl [MFC], FireMouseUp", "COleControl [MFC], FireReadyStateChange", "COleControl [MFC], GetActivationPolicy", "COleControl [MFC], GetAmbientProperty", "COleControl [MFC], GetAppearance", "COleControl [MFC], GetBackColor", "COleControl [MFC], GetBorderStyle", "COleControl [MFC], GetCapture", "COleControl [MFC], GetClassID", "COleControl [MFC], GetClientOffset", "COleControl [MFC], GetClientRect", "COleControl [MFC], GetClientSite", "COleControl [MFC], GetControlFlags", "COleControl [MFC], GetControlSize", "COleControl [MFC], GetDC", "COleControl [MFC], GetEnabled", "COleControl [MFC], GetExtendedControl", "COleControl [MFC], GetFocus", "COleControl [MFC], GetFont", "COleControl [MFC], GetFontTextMetrics", "COleControl [MFC], GetForeColor", "COleControl [MFC], GetHwnd", "COleControl [MFC], GetMessageString", "COleControl [MFC], GetNotSupported", "COleControl [MFC], GetReadyState", "COleControl [MFC], GetRectInContainer", "COleControl [MFC], GetStockTextMetrics", "COleControl [MFC], GetText", "COleControl [MFC], GetWindowlessDropTarget", "COleControl [MFC], InitializeIIDs", "COleControl [MFC], InternalGetFont", "COleControl [MFC], InternalGetText", "COleControl [MFC], InternalSetReadyState", "COleControl [MFC], InvalidateControl", "COleControl [MFC], InvalidateRgn", "COleControl [MFC], IsConvertingVBX", "COleControl [MFC], IsModified", "COleControl [MFC], IsOptimizedDraw", "COleControl [MFC], IsSubclassedControl", "COleControl [MFC], Load", "COleControl [MFC], LockInPlaceActive", "COleControl [MFC], OnAmbientPropertyChange", "COleControl [MFC], OnAppearanceChanged", "COleControl [MFC], OnBackColorChanged", "COleControl [MFC], OnBorderStyleChanged", "COleControl [MFC], OnClick", "COleControl [MFC], OnClose", "COleControl [MFC], OnDoVerb", "COleControl [MFC], OnDraw", "COleControl [MFC], OnDrawMetafile", "COleControl [MFC], OnEdit", "COleControl [MFC], OnEnabledChanged", "COleControl [MFC], OnEnumVerbs", "COleControl [MFC], OnEventAdvise", "COleControl [MFC], OnFontChanged", "COleControl [MFC], OnForeColorChanged", "COleControl [MFC], OnFreezeEvents", "COleControl [MFC], OnGetColorSet", "COleControl [MFC], OnGetControlInfo", "COleControl [MFC], OnGetDisplayString", "COleControl [MFC], OnGetInPlaceMenu", "COleControl [MFC], OnGetNaturalExtent", "COleControl [MFC], OnGetPredefinedStrings", "COleControl [MFC], OnGetPredefinedValue", "COleControl [MFC], OnGetViewExtent", "COleControl [MFC], OnGetViewRect", "COleControl [MFC], OnGetViewStatus", "COleControl [MFC], OnHideToolBars", "COleControl [MFC], OnInactiveMouseMove", "COleControl [MFC], OnInactiveSetCursor", "COleControl [MFC], OnKeyDownEvent", "COleControl [MFC], OnKeyPressEvent", "COleControl [MFC], OnKeyUpEvent", "COleControl [MFC], OnMapPropertyToPage", "COleControl [MFC], OnMnemonic", "COleControl [MFC], OnProperties", "COleControl [MFC], OnQueryHitPoint", "COleControl [MFC], OnQueryHitRect", "COleControl [MFC], OnRenderData", "COleControl [MFC], OnRenderFileData", "COleControl [MFC], OnRenderGlobalData", "COleControl [MFC], OnResetState", "COleControl [MFC], OnSetClientSite", "COleControl [MFC], OnSetData", "COleControl [MFC], OnSetExtent", "COleControl [MFC], OnSetObjectRects", "COleControl [MFC], OnShowToolBars", "COleControl [MFC], OnTextChanged", "COleControl [MFC], OnWindowlessMessage", "COleControl [MFC], ParentToClient", "COleControl [MFC], PostModalDialog", "COleControl [MFC], PreModalDialog", "COleControl [MFC], RecreateControlWindow", "COleControl [MFC], Refresh", "COleControl [MFC], ReleaseCapture", "COleControl [MFC], ReleaseDC", "COleControl [MFC], ReparentControlWindow", "COleControl [MFC], ResetStockProps", "COleControl [MFC], ResetVersion", "COleControl [MFC], ScrollWindow", "COleControl [MFC], SelectFontObject", "COleControl [MFC], SelectStockFont", "COleControl [MFC], SerializeExtent", "COleControl [MFC], SerializeStockProps", "COleControl [MFC], SerializeVersion", "COleControl [MFC], SetAppearance", "COleControl [MFC], SetBackColor", "COleControl [MFC], SetBorderStyle", "COleControl [MFC], SetCapture", "COleControl [MFC], SetControlSize", "COleControl [MFC], SetEnabled", "COleControl [MFC], SetFocus", "COleControl [MFC], SetFont", "COleControl [MFC], SetForeColor", "COleControl [MFC], SetInitialSize", "COleControl [MFC], SetModifiedFlag", "COleControl [MFC], SetNotPermitted", "COleControl [MFC], SetNotSupported", "COleControl [MFC], SetRectInContainer", "COleControl [MFC], SetText", "COleControl [MFC], ThrowError", "COleControl [MFC], TransformCoords", "COleControl [MFC], TranslateColor", "COleControl [MFC], WillAmbientsBeValidDuringLoad", "COleControl [MFC], WindowProc", "COleControl [MFC], DrawContent", "COleControl [MFC], DrawMetafile", "COleControl [MFC], IsInvokeAllowed", "COleControl [MFC], SetInitialDataFormats"] -ms.assetid: 53e95299-38e8-447b-9c5f-a381d27f5123 --- # COleControl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A powerful base class for developing OLE controls. ## Syntax diff --git a/docs/mfc/reference/colecontrolcontainer-class.md b/docs/mfc/reference/colecontrolcontainer-class.md index 5187c2d745f..ff21a7c3de1 100644 --- a/docs/mfc/reference/colecontrolcontainer-class.md +++ b/docs/mfc/reference/colecontrolcontainer-class.md @@ -4,10 +4,12 @@ title: "COleControlContainer Class" ms.date: "11/04/2016" f1_keywords: ["COleControlContainer", "AFXOCC/COleControlContainer", "AFXOCC/COleControlContainer::COleControlContainer", "AFXOCC/COleControlContainer::AttachControlSite", "AFXOCC/COleControlContainer::BroadcastAmbientPropertyChange", "AFXOCC/COleControlContainer::CheckDlgButton", "AFXOCC/COleControlContainer::CheckRadioButton", "AFXOCC/COleControlContainer::CreateControl", "AFXOCC/COleControlContainer::CreateOleFont", "AFXOCC/COleControlContainer::FindItem", "AFXOCC/COleControlContainer::FreezeAllEvents", "AFXOCC/COleControlContainer::GetAmbientProp", "AFXOCC/COleControlContainer::GetDlgItem", "AFXOCC/COleControlContainer::GetDlgItemInt", "AFXOCC/COleControlContainer::GetDlgItemText", "AFXOCC/COleControlContainer::HandleSetFocus", "AFXOCC/COleControlContainer::HandleWindowlessMessage", "AFXOCC/COleControlContainer::IsDlgButtonChecked", "AFXOCC/COleControlContainer::OnPaint", "AFXOCC/COleControlContainer::OnUIActivate", "AFXOCC/COleControlContainer::OnUIDeactivate", "AFXOCC/COleControlContainer::ScrollChildren", "AFXOCC/COleControlContainer::SendDlgItemMessage", "AFXOCC/COleControlContainer::SetDlgItemInt", "AFXOCC/COleControlContainer::SetDlgItemText", "AFXOCC/COleControlContainer::m_crBack", "AFXOCC/COleControlContainer::m_crFore", "AFXOCC/COleControlContainer::m_listSitesOrWnds", "AFXOCC/COleControlContainer::m_nWindowlessControls", "AFXOCC/COleControlContainer::m_pOleFont", "AFXOCC/COleControlContainer::m_pSiteCapture", "AFXOCC/COleControlContainer::m_pSiteFocus", "AFXOCC/COleControlContainer::m_pSiteUIActive", "AFXOCC/COleControlContainer::m_pWnd", "AFXOCC/COleControlContainer::m_siteMap"] helpviewer_keywords: ["COleControlContainer [MFC], COleControlContainer", "COleControlContainer [MFC], AttachControlSite", "COleControlContainer [MFC], BroadcastAmbientPropertyChange", "COleControlContainer [MFC], CheckDlgButton", "COleControlContainer [MFC], CheckRadioButton", "COleControlContainer [MFC], CreateControl", "COleControlContainer [MFC], CreateOleFont", "COleControlContainer [MFC], FindItem", "COleControlContainer [MFC], FreezeAllEvents", "COleControlContainer [MFC], GetAmbientProp", "COleControlContainer [MFC], GetDlgItem", "COleControlContainer [MFC], GetDlgItemInt", "COleControlContainer [MFC], GetDlgItemText", "COleControlContainer [MFC], HandleSetFocus", "COleControlContainer [MFC], HandleWindowlessMessage", "COleControlContainer [MFC], IsDlgButtonChecked", "COleControlContainer [MFC], OnPaint", "COleControlContainer [MFC], OnUIActivate", "COleControlContainer [MFC], OnUIDeactivate", "COleControlContainer [MFC], ScrollChildren", "COleControlContainer [MFC], SendDlgItemMessage", "COleControlContainer [MFC], SetDlgItemInt", "COleControlContainer [MFC], SetDlgItemText", "COleControlContainer [MFC], m_crBack", "COleControlContainer [MFC], m_crFore", "COleControlContainer [MFC], m_listSitesOrWnds", "COleControlContainer [MFC], m_nWindowlessControls", "COleControlContainer [MFC], m_pOleFont", "COleControlContainer [MFC], m_pSiteCapture", "COleControlContainer [MFC], m_pSiteFocus", "COleControlContainer [MFC], m_pSiteUIActive", "COleControlContainer [MFC], m_pWnd", "COleControlContainer [MFC], m_siteMap"] -ms.assetid: f7ce9246-0fb7-4f07-a83a-6c2390d0fdf8 --- # COleControlContainer Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Acts as a control container for ActiveX controls. ## Syntax diff --git a/docs/mfc/reference/colecontrolmodule-class.md b/docs/mfc/reference/colecontrolmodule-class.md index 27758f5eae1..6a03e9ed1c9 100644 --- a/docs/mfc/reference/colecontrolmodule-class.md +++ b/docs/mfc/reference/colecontrolmodule-class.md @@ -4,10 +4,12 @@ title: "COleControlModule Class" ms.date: "11/04/2016" f1_keywords: ["OleControlModule"] helpviewer_keywords: ["OLE control modules [MFC]", "MFC ActiveX controls [MFC], OLE control modules", "COleControlModule class [MFC]", "control modules [MFC]"] -ms.assetid: 0721724d-d4af-4eda-ad34-5a2b27810dd4 --- # COleControlModule Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class from which you derive an OLE control module object. ## Syntax diff --git a/docs/mfc/reference/colecontrolsite-class.md b/docs/mfc/reference/colecontrolsite-class.md index 06932c8dffc..e5b30a331c1 100644 --- a/docs/mfc/reference/colecontrolsite-class.md +++ b/docs/mfc/reference/colecontrolsite-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides support for custom client-side control interfaces. ## Syntax @@ -358,7 +360,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 +648,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 +724,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 +1014,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/coleconvertdialog-class.md b/docs/mfc/reference/coleconvertdialog-class.md index eda026d9681..4d73297fdc0 100644 --- a/docs/mfc/reference/coleconvertdialog-class.md +++ b/docs/mfc/reference/coleconvertdialog-class.md @@ -4,10 +4,12 @@ title: "COleConvertDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleConvertDialog", "AFXODLGS/COleConvertDialog", "AFXODLGS/COleConvertDialog::COleConvertDialog", "AFXODLGS/COleConvertDialog::DoConvert", "AFXODLGS/COleConvertDialog::DoModal", "AFXODLGS/COleConvertDialog::GetClassID", "AFXODLGS/COleConvertDialog::GetDrawAspect", "AFXODLGS/COleConvertDialog::GetIconicMetafile", "AFXODLGS/COleConvertDialog::GetSelectionType", "AFXODLGS/COleConvertDialog::m_cv"] helpviewer_keywords: ["COleConvertDialog [MFC], COleConvertDialog", "COleConvertDialog [MFC], DoConvert", "COleConvertDialog [MFC], DoModal", "COleConvertDialog [MFC], GetClassID", "COleConvertDialog [MFC], GetDrawAspect", "COleConvertDialog [MFC], GetIconicMetafile", "COleConvertDialog [MFC], GetSelectionType", "COleConvertDialog [MFC], m_cv"] -ms.assetid: a7c57714-31e8-4b78-834d-8ddd1b856a1c --- # COleConvertDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more information, see the [OLEUICONVERT](/windows/win32/api/oledlg/ns-oledlg-oleuiconvertw) structure in the Windows SDK. ## Syntax diff --git a/docs/mfc/reference/colecurrency-class.md b/docs/mfc/reference/colecurrency-class.md index d208b9739da..b440966b509 100644 --- a/docs/mfc/reference/colecurrency-class.md +++ b/docs/mfc/reference/colecurrency-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the `CURRENCY` data type of OLE automation. ## Syntax @@ -290,7 +292,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 +488,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 c56df1d52c0..db59686d70a 100644 --- a/docs/mfc/reference/coledataobject-class.md +++ b/docs/mfc/reference/coledataobject-class.md @@ -4,10 +4,12 @@ title: "COleDataObject Class" ms.date: "11/04/2016" f1_keywords: ["COleDataObject", "AFXOLE/COleDataObject", "AFXOLE/COleDataObject::COleDataObject", "AFXOLE/COleDataObject::Attach", "AFXOLE/COleDataObject::AttachClipboard", "AFXOLE/COleDataObject::BeginEnumFormats", "AFXOLE/COleDataObject::Detach", "AFXOLE/COleDataObject::GetData", "AFXOLE/COleDataObject::GetFileData", "AFXOLE/COleDataObject::GetGlobalData", "AFXOLE/COleDataObject::GetNextFormat", "AFXOLE/COleDataObject::IsDataAvailable", "AFXOLE/COleDataObject::Release"] helpviewer_keywords: ["COleDataObject [MFC], COleDataObject", "COleDataObject [MFC], Attach", "COleDataObject [MFC], AttachClipboard", "COleDataObject [MFC], BeginEnumFormats", "COleDataObject [MFC], Detach", "COleDataObject [MFC], GetData", "COleDataObject [MFC], GetFileData", "COleDataObject [MFC], GetGlobalData", "COleDataObject [MFC], GetNextFormat", "COleDataObject [MFC], IsDataAvailable", "COleDataObject [MFC], Release"] -ms.assetid: d1cc84be-2e1c-4bb3-a8a0-565eb08aaa34 --- # COleDataObject Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used in data transfers for retrieving data in various formats from the Clipboard, through drag and drop, or from an embedded OLE item. ## Syntax @@ -96,7 +98,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 5cb2cc3bd9b..b107af62451 100644 --- a/docs/mfc/reference/coledatasource-class.md +++ b/docs/mfc/reference/coledatasource-class.md @@ -4,10 +4,12 @@ title: "COleDataSource Class" ms.date: "11/04/2016" f1_keywords: ["COleDataSource", "AFXOLE/COleDataSource", "AFXOLE/COleDataSource::COleDataSource", "AFXOLE/COleDataSource::CacheData", "AFXOLE/COleDataSource::CacheGlobalData", "AFXOLE/COleDataSource::DelayRenderData", "AFXOLE/COleDataSource::DelayRenderFileData", "AFXOLE/COleDataSource::DelaySetData", "AFXOLE/COleDataSource::DoDragDrop", "AFXOLE/COleDataSource::Empty", "AFXOLE/COleDataSource::FlushClipboard", "AFXOLE/COleDataSource::GetClipboardOwner", "AFXOLE/COleDataSource::OnRenderData", "AFXOLE/COleDataSource::OnRenderFileData", "AFXOLE/COleDataSource::OnRenderGlobalData", "AFXOLE/COleDataSource::OnSetData", "AFXOLE/COleDataSource::SetClipboard"] helpviewer_keywords: ["COleDataSource [MFC], COleDataSource", "COleDataSource [MFC], CacheData", "COleDataSource [MFC], CacheGlobalData", "COleDataSource [MFC], DelayRenderData", "COleDataSource [MFC], DelayRenderFileData", "COleDataSource [MFC], DelaySetData", "COleDataSource [MFC], DoDragDrop", "COleDataSource [MFC], Empty", "COleDataSource [MFC], FlushClipboard", "COleDataSource [MFC], GetClipboardOwner", "COleDataSource [MFC], OnRenderData", "COleDataSource [MFC], OnRenderFileData", "COleDataSource [MFC], OnRenderGlobalData", "COleDataSource [MFC], OnSetData", "COleDataSource [MFC], SetClipboard"] -ms.assetid: 02c8ee7d-8e10-4463-8613-bb2a0305ca69 --- # COleDataSource Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax @@ -227,7 +229,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/coledbrecordview-class.md b/docs/mfc/reference/coledbrecordview-class.md index b8ab8c78076..dda014b94d5 100644 --- a/docs/mfc/reference/coledbrecordview-class.md +++ b/docs/mfc/reference/coledbrecordview-class.md @@ -4,10 +4,12 @@ title: "COleDBRecordView Class" ms.date: "11/04/2016" f1_keywords: ["COleDBRecordView", "AFXOLEDB/COleDBRecordView", "AFXOLEDB/COleDBRecordView::COleDBRecordView", "AFXOLEDB/COleDBRecordView::OnGetRowset", "AFXOLEDB/COleDBRecordView::OnMove"] helpviewer_keywords: ["COleDBRecordView [MFC], COleDBRecordView", "COleDBRecordView [MFC], OnGetRowset", "COleDBRecordView [MFC], OnMove"] -ms.assetid: 98612427-c4c9-4760-b7e1-85b17448add9 --- # COleDBRecordView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A view that displays database records in controls. ## Syntax diff --git a/docs/mfc/reference/coledialog-class.md b/docs/mfc/reference/coledialog-class.md index bc4e1f0d908..cc997aaebd4 100644 --- a/docs/mfc/reference/coledialog-class.md +++ b/docs/mfc/reference/coledialog-class.md @@ -4,10 +4,12 @@ title: "COleDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleDialog", "AFXODLGS/COleDialog", "AFXODLGS/COleDialog::GetLastError"] helpviewer_keywords: ["COleDialog [MFC], GetLastError"] -ms.assetid: b1ed0aca-3914-4b00-af34-4a4fb491aec7 --- # COleDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides functionality common to dialog boxes for OLE. ## Syntax diff --git a/docs/mfc/reference/coledispatchdriver-class.md b/docs/mfc/reference/coledispatchdriver-class.md index 5984ecda38f..5a08820a954 100644 --- a/docs/mfc/reference/coledispatchdriver-class.md +++ b/docs/mfc/reference/coledispatchdriver-class.md @@ -4,10 +4,12 @@ title: "COleDispatchDriver Class" ms.date: "11/04/2016" f1_keywords: ["COleDispatchDriver", "AFXDISP/COleDispatchDriver", "AFXDISP/COleDispatchDriver::COleDispatchDriver", "AFXDISP/COleDispatchDriver::AttachDispatch", "AFXDISP/COleDispatchDriver::CreateDispatch", "AFXDISP/COleDispatchDriver::DetachDispatch", "AFXDISP/COleDispatchDriver::GetProperty", "AFXDISP/COleDispatchDriver::InvokeHelper", "AFXDISP/COleDispatchDriver::ReleaseDispatch", "AFXDISP/COleDispatchDriver::SetProperty", "AFXDISP/COleDispatchDriver::m_bAutoRelease", "AFXDISP/COleDispatchDriver::m_lpDispatch"] helpviewer_keywords: ["COleDispatchDriver [MFC], COleDispatchDriver", "COleDispatchDriver [MFC], AttachDispatch", "COleDispatchDriver [MFC], CreateDispatch", "COleDispatchDriver [MFC], DetachDispatch", "COleDispatchDriver [MFC], GetProperty", "COleDispatchDriver [MFC], InvokeHelper", "COleDispatchDriver [MFC], ReleaseDispatch", "COleDispatchDriver [MFC], SetProperty", "COleDispatchDriver [MFC], m_bAutoRelease", "COleDispatchDriver [MFC], m_lpDispatch"] -ms.assetid: 3ed98daf-cdc7-4374-8a0c-cf695a8d3657 --- # COleDispatchDriver Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the client side of OLE automation. ## Syntax diff --git a/docs/mfc/reference/coledispatchexception-class.md b/docs/mfc/reference/coledispatchexception-class.md index a37125f8492..c95af10037c 100644 --- a/docs/mfc/reference/coledispatchexception-class.md +++ b/docs/mfc/reference/coledispatchexception-class.md @@ -4,10 +4,12 @@ title: "COleDispatchException Class" ms.date: "11/04/2016" f1_keywords: ["COleDispatchException", "AFXDISP/COleDispatchException", "AFXDISP/COleDispatchException::m_dwHelpContext", "AFXDISP/COleDispatchException::m_strDescription", "AFXDISP/COleDispatchException::m_strHelpFile", "AFXDISP/COleDispatchException::m_strSource", "AFXDISP/COleDispatchException::m_wCode"] helpviewer_keywords: ["COleDispatchException [MFC], m_dwHelpContext", "COleDispatchException [MFC], m_strDescription", "COleDispatchException [MFC], m_strHelpFile", "COleDispatchException [MFC], m_strSource", "COleDispatchException [MFC], m_wCode"] -ms.assetid: 0e95c8be-e21a-490c-99ec-181c6a9a26d0 --- # COleDispatchException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Handles exceptions specific to the OLE `IDispatch` interface, which is a key part of OLE automation. ## Syntax diff --git a/docs/mfc/reference/coledocobjectitem-class.md b/docs/mfc/reference/coledocobjectitem-class.md index 91854ce6bb8..5bf120dd054 100644 --- a/docs/mfc/reference/coledocobjectitem-class.md +++ b/docs/mfc/reference/coledocobjectitem-class.md @@ -4,10 +4,12 @@ title: "COleDocObjectItem Class" ms.date: "11/04/2016" f1_keywords: ["COleDocObjectItem", "AFXOLE/COleDocObjectItem", "AFXOLE/COleDocObjectItem::COleDocObjectItem", "AFXOLE/COleDocObjectItem::DoDefaultPrinting", "AFXOLE/COleDocObjectItem::ExecCommand", "AFXOLE/COleDocObjectItem::GetActiveView", "AFXOLE/COleDocObjectItem::GetPageCount", "AFXOLE/COleDocObjectItem::OnPreparePrinting", "AFXOLE/COleDocObjectItem::OnPrint", "AFXOLE/COleDocObjectItem::QueryCommand", "AFXOLE/COleDocObjectItem::Release"] helpviewer_keywords: ["COleDocObjectItem [MFC], COleDocObjectItem", "COleDocObjectItem [MFC], DoDefaultPrinting", "COleDocObjectItem [MFC], ExecCommand", "COleDocObjectItem [MFC], GetActiveView", "COleDocObjectItem [MFC], GetPageCount", "COleDocObjectItem [MFC], OnPreparePrinting", "COleDocObjectItem [MFC], OnPrint", "COleDocObjectItem [MFC], QueryCommand", "COleDocObjectItem [MFC], Release"] -ms.assetid: d150d306-8fd3-4831-b06d-afbe71d8fc9b --- # COleDocObjectItem Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements Active document containment. ## Syntax diff --git a/docs/mfc/reference/coledocument-class.md b/docs/mfc/reference/coledocument-class.md index c8ad83bdfbe..9c792ffd574 100644 --- a/docs/mfc/reference/coledocument-class.md +++ b/docs/mfc/reference/coledocument-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for OLE documents that support visual editing. ## Syntax @@ -64,9 +66,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 +155,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 +358,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 +493,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/coledropsource-class.md b/docs/mfc/reference/coledropsource-class.md index 1681ecaa0d2..e00dc920b0b 100644 --- a/docs/mfc/reference/coledropsource-class.md +++ b/docs/mfc/reference/coledropsource-class.md @@ -4,10 +4,12 @@ title: "COleDropSource Class" ms.date: "11/04/2016" f1_keywords: ["COleDropSource", "AFXOLE/COleDropSource", "AFXOLE/COleDropSource::COleDropSource", "AFXOLE/COleDropSource::GiveFeedback", "AFXOLE/COleDropSource::OnBeginDrag", "AFXOLE/COleDropSource::QueryContinueDrag"] helpviewer_keywords: ["COleDropSource [MFC], COleDropSource", "COleDropSource [MFC], GiveFeedback", "COleDropSource [MFC], OnBeginDrag", "COleDropSource [MFC], QueryContinueDrag"] -ms.assetid: d3eecc5f-a70b-4a01-b705-7d2c098ebe17 --- # COleDropSource Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows data to be dragged to a drop target. ## Syntax diff --git a/docs/mfc/reference/coledroptarget-class.md b/docs/mfc/reference/coledroptarget-class.md index 302ff8d19da..e9bd9141c53 100644 --- a/docs/mfc/reference/coledroptarget-class.md +++ b/docs/mfc/reference/coledroptarget-class.md @@ -4,10 +4,12 @@ title: "COleDropTarget Class" ms.date: "11/04/2016" f1_keywords: ["COleDropTarget", "AFXOLE/COleDropTarget", "AFXOLE/COleDropTarget::COleDropTarget", "AFXOLE/COleDropTarget::OnDragEnter", "AFXOLE/COleDropTarget::OnDragLeave", "AFXOLE/COleDropTarget::OnDragOver", "AFXOLE/COleDropTarget::OnDragScroll", "AFXOLE/COleDropTarget::OnDrop", "AFXOLE/COleDropTarget::OnDropEx", "AFXOLE/COleDropTarget::Register", "AFXOLE/COleDropTarget::Revoke"] helpviewer_keywords: ["COleDropTarget [MFC], COleDropTarget", "COleDropTarget [MFC], OnDragEnter", "COleDropTarget [MFC], OnDragLeave", "COleDropTarget [MFC], OnDragOver", "COleDropTarget [MFC], OnDragScroll", "COleDropTarget [MFC], OnDrop", "COleDropTarget [MFC], OnDropEx", "COleDropTarget [MFC], Register", "COleDropTarget [MFC], Revoke"] -ms.assetid: a58c9a48-6a93-4357-b078-4594df258311 --- # COleDropTarget Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the communication mechanism between a window and the OLE libraries. ## Syntax diff --git a/docs/mfc/reference/coleexception-class.md b/docs/mfc/reference/coleexception-class.md index c9c34fbd723..f78ec5f29fb 100644 --- a/docs/mfc/reference/coleexception-class.md +++ b/docs/mfc/reference/coleexception-class.md @@ -4,10 +4,12 @@ title: "COleException Class" ms.date: "11/04/2016" f1_keywords: ["COleException", "AFXDISP/COleException", "AFXDISP/COleException::Process", "AFXDISP/COleException::m_sc"] helpviewer_keywords: ["COleException [MFC], Process", "COleException [MFC], m_sc"] -ms.assetid: 2571e9fe-26cc-42f0-9ad9-8ad5b4311ec1 --- # COleException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents an exception condition related to an OLE operation. ## Syntax diff --git a/docs/mfc/reference/coleinsertdialog-class.md b/docs/mfc/reference/coleinsertdialog-class.md index 976c1cfaacb..229f2ae0ac3 100644 --- a/docs/mfc/reference/coleinsertdialog-class.md +++ b/docs/mfc/reference/coleinsertdialog-class.md @@ -4,10 +4,12 @@ title: "COleInsertDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleInsertDialog", "AFXODLGS/COleInsertDialog", "AFXODLGS/COleInsertDialog::COleInsertDialog", "AFXODLGS/COleInsertDialog::CreateItem", "AFXODLGS/COleInsertDialog::DoModal", "AFXODLGS/COleInsertDialog::GetClassID", "AFXODLGS/COleInsertDialog::GetDrawAspect", "AFXODLGS/COleInsertDialog::GetIconicMetafile", "AFXODLGS/COleInsertDialog::GetPathName", "AFXODLGS/COleInsertDialog::GetSelectionType", "AFXODLGS/COleInsertDialog::m_io"] helpviewer_keywords: ["COleInsertDialog [MFC], COleInsertDialog", "COleInsertDialog [MFC], CreateItem", "COleInsertDialog [MFC], DoModal", "COleInsertDialog [MFC], GetClassID", "COleInsertDialog [MFC], GetDrawAspect", "COleInsertDialog [MFC], GetIconicMetafile", "COleInsertDialog [MFC], GetPathName", "COleInsertDialog [MFC], GetSelectionType", "COleInsertDialog [MFC], m_io"] -ms.assetid: a9ec610b-abde-431e-bd01-c40159a66dbb --- # COleInsertDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used for the OLE Insert Object dialog box. ## Syntax diff --git a/docs/mfc/reference/coleipframewnd-class.md b/docs/mfc/reference/coleipframewnd-class.md index 268e34a20cd..01d3333f30c 100644 --- a/docs/mfc/reference/coleipframewnd-class.md +++ b/docs/mfc/reference/coleipframewnd-class.md @@ -4,10 +4,12 @@ title: "COleIPFrameWnd Class" ms.date: "11/04/2016" f1_keywords: ["COleIPFrameWnd", "AFXOLE/COleIPFrameWnd", "AFXOLE/COleIPFrameWnd::COleIPFrameWnd", "AFXOLE/COleIPFrameWnd::OnCreateControlBars", "AFXOLE/COleIPFrameWnd::RepositionFrame"] helpviewer_keywords: ["COleIPFrameWnd [MFC], COleIPFrameWnd", "COleIPFrameWnd [MFC], OnCreateControlBars", "COleIPFrameWnd [MFC], RepositionFrame"] -ms.assetid: 24abb2cb-826c-4dda-a287-d8a8900a5763 --- # COleIPFrameWnd Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base for your application's in-place editing window. ## Syntax diff --git a/docs/mfc/reference/coleipframewndex-class.md b/docs/mfc/reference/coleipframewndex-class.md index 69d2da9c479..e309d938cf8 100644 --- a/docs/mfc/reference/coleipframewndex-class.md +++ b/docs/mfc/reference/coleipframewndex-class.md @@ -1,14 +1,16 @@ --- -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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +52,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 +573,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 +599,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 a0e41b51281..e81abbb02b1 100644 --- a/docs/mfc/reference/colelinkingdoc-class.md +++ b/docs/mfc/reference/colelinkingdoc-class.md @@ -4,10 +4,12 @@ title: "COleLinkingDoc Class" ms.date: "11/04/2016" f1_keywords: ["COleLinkingDoc", "AFXOLE/COleLinkingDoc", "AFXOLE/COleLinkingDoc::COleLinkingDoc", "AFXOLE/COleLinkingDoc::Register", "AFXOLE/COleLinkingDoc::Revoke", "AFXOLE/COleLinkingDoc::OnFindEmbeddedItem", "AFXOLE/COleLinkingDoc::OnGetLinkedItem"] helpviewer_keywords: ["COleLinkingDoc [MFC], COleLinkingDoc", "COleLinkingDoc [MFC], Register", "COleLinkingDoc [MFC], Revoke", "COleLinkingDoc [MFC], OnFindEmbeddedItem", "COleLinkingDoc [MFC], OnGetLinkedItem"] -ms.assetid: 9f547f35-2f95-427f-b9c0-85c31940198b --- # COleLinkingDoc Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for OLE container documents that support linking to the embedded items they contain. ## Syntax @@ -130,7 +132,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/colelinksdialog-class.md b/docs/mfc/reference/colelinksdialog-class.md index 9f58c147848..af1f098034d 100644 --- a/docs/mfc/reference/colelinksdialog-class.md +++ b/docs/mfc/reference/colelinksdialog-class.md @@ -4,10 +4,12 @@ title: "COleLinksDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleLinksDialog", "AFXODLGS/COleLinksDialog", "AFXODLGS/COleLinksDialog::COleLinksDialog", "AFXODLGS/COleLinksDialog::DoModal", "AFXODLGS/COleLinksDialog::m_el"] helpviewer_keywords: ["COleLinksDialog [MFC], COleLinksDialog", "COleLinksDialog [MFC], DoModal", "COleLinksDialog [MFC], m_el"] -ms.assetid: fb2eb638-2809-46db-ac74-392a732affc7 --- # COleLinksDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used for the OLE Edit Links dialog box. ## Syntax diff --git a/docs/mfc/reference/colemessagefilter-class.md b/docs/mfc/reference/colemessagefilter-class.md index 4fe6409199c..51294d30e72 100644 --- a/docs/mfc/reference/colemessagefilter-class.md +++ b/docs/mfc/reference/colemessagefilter-class.md @@ -4,10 +4,12 @@ title: "COleMessageFilter Class" ms.date: "11/04/2016" f1_keywords: ["COleMessageFilter", "AFXOLE/COleMessageFilter", "AFXOLE/COleMessageFilter::COleMessageFilter", "AFXOLE/COleMessageFilter::BeginBusyState", "AFXOLE/COleMessageFilter::EnableBusyDialog", "AFXOLE/COleMessageFilter::EnableNotRespondingDialog", "AFXOLE/COleMessageFilter::EndBusyState", "AFXOLE/COleMessageFilter::OnMessagePending", "AFXOLE/COleMessageFilter::Register", "AFXOLE/COleMessageFilter::Revoke", "AFXOLE/COleMessageFilter::SetBusyReply", "AFXOLE/COleMessageFilter::SetMessagePendingDelay", "AFXOLE/COleMessageFilter::SetRetryReply"] helpviewer_keywords: ["COleMessageFilter [MFC], COleMessageFilter", "COleMessageFilter [MFC], BeginBusyState", "COleMessageFilter [MFC], EnableBusyDialog", "COleMessageFilter [MFC], EnableNotRespondingDialog", "COleMessageFilter [MFC], EndBusyState", "COleMessageFilter [MFC], OnMessagePending", "COleMessageFilter [MFC], Register", "COleMessageFilter [MFC], Revoke", "COleMessageFilter [MFC], SetBusyReply", "COleMessageFilter [MFC], SetMessagePendingDelay", "COleMessageFilter [MFC], SetRetryReply"] -ms.assetid: b1fd1639-fac4-4fd0-bf17-15172deba13c --- # COleMessageFilter Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages the concurrency required by the interaction of OLE applications. ## Syntax diff --git a/docs/mfc/reference/coleobjectfactory-class.md b/docs/mfc/reference/coleobjectfactory-class.md index 72f3cce4fcf..08a19604d79 100644 --- a/docs/mfc/reference/coleobjectfactory-class.md +++ b/docs/mfc/reference/coleobjectfactory-class.md @@ -4,10 +4,12 @@ title: "COleObjectFactory Class" ms.date: "11/04/2016" f1_keywords: ["COleObjectFactory", "AFXDISP/COleObjectFactory", "AFXDISP/COleObjectFactory::COleObjectFactory", "AFXDISP/COleObjectFactory::GetClassID", "AFXDISP/COleObjectFactory::IsLicenseValid", "AFXDISP/COleObjectFactory::IsRegistered", "AFXDISP/COleObjectFactory::Register", "AFXDISP/COleObjectFactory::RegisterAll", "AFXDISP/COleObjectFactory::Revoke", "AFXDISP/COleObjectFactory::RevokeAll", "AFXDISP/COleObjectFactory::UnregisterAll", "AFXDISP/COleObjectFactory::UpdateRegistry", "AFXDISP/COleObjectFactory::UpdateRegistryAll", "AFXDISP/COleObjectFactory::GetLicenseKey", "AFXDISP/COleObjectFactory::OnCreateObject", "AFXDISP/COleObjectFactory::VerifyLicenseKey", "AFXDISP/COleObjectFactory::VerifyUserLicense"] helpviewer_keywords: ["COleObjectFactory [MFC], COleObjectFactory", "COleObjectFactory [MFC], GetClassID", "COleObjectFactory [MFC], IsLicenseValid", "COleObjectFactory [MFC], IsRegistered", "COleObjectFactory [MFC], Register", "COleObjectFactory [MFC], RegisterAll", "COleObjectFactory [MFC], Revoke", "COleObjectFactory [MFC], RevokeAll", "COleObjectFactory [MFC], UnregisterAll", "COleObjectFactory [MFC], UpdateRegistry", "COleObjectFactory [MFC], UpdateRegistryAll", "COleObjectFactory [MFC], GetLicenseKey", "COleObjectFactory [MFC], OnCreateObject", "COleObjectFactory [MFC], VerifyLicenseKey", "COleObjectFactory [MFC], VerifyUserLicense"] -ms.assetid: ab179c1e-4af2-44aa-a576-37c48149b427 --- # COleObjectFactory Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the OLE class factory, which creates OLE objects such as servers, automation objects, and documents. ## Syntax @@ -178,7 +180,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 ba39324f30c..26e5fd4a445 100644 --- a/docs/mfc/reference/colepastespecialdialog-class.md +++ b/docs/mfc/reference/colepastespecialdialog-class.md @@ -4,10 +4,12 @@ title: "COlePasteSpecialDialog Class" ms.date: "11/04/2016" f1_keywords: ["COlePasteSpecialDialog", "AFXODLGS/COlePasteSpecialDialog", "AFXODLGS/COlePasteSpecialDialog::COlePasteSpecialDialog", "AFXODLGS/COlePasteSpecialDialog::AddFormat", "AFXODLGS/COlePasteSpecialDialog::AddLinkEntry", "AFXODLGS/COlePasteSpecialDialog::AddStandardFormats", "AFXODLGS/COlePasteSpecialDialog::CreateItem", "AFXODLGS/COlePasteSpecialDialog::DoModal", "AFXODLGS/COlePasteSpecialDialog::GetDrawAspect", "AFXODLGS/COlePasteSpecialDialog::GetIconicMetafile", "AFXODLGS/COlePasteSpecialDialog::GetPasteIndex", "AFXODLGS/COlePasteSpecialDialog::GetSelectionType", "AFXODLGS/COlePasteSpecialDialog::m_ps"] helpviewer_keywords: ["COlePasteSpecialDialog [MFC], COlePasteSpecialDialog", "COlePasteSpecialDialog [MFC], AddFormat", "COlePasteSpecialDialog [MFC], AddLinkEntry", "COlePasteSpecialDialog [MFC], AddStandardFormats", "COlePasteSpecialDialog [MFC], CreateItem", "COlePasteSpecialDialog [MFC], DoModal", "COlePasteSpecialDialog [MFC], GetDrawAspect", "COlePasteSpecialDialog [MFC], GetIconicMetafile", "COlePasteSpecialDialog [MFC], GetPasteIndex", "COlePasteSpecialDialog [MFC], GetSelectionType", "COlePasteSpecialDialog [MFC], m_ps"] -ms.assetid: 0e82ef9a-9bbe-457e-8240-42c86a0534f7 --- # COlePasteSpecialDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used for the OLE Paste Special dialog box. ## Syntax @@ -328,7 +330,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/colepropertiesdialog-class.md b/docs/mfc/reference/colepropertiesdialog-class.md index 55ad58f8271..c35ab0d70ec 100644 --- a/docs/mfc/reference/colepropertiesdialog-class.md +++ b/docs/mfc/reference/colepropertiesdialog-class.md @@ -4,10 +4,12 @@ title: "COlePropertiesDialog Class" ms.date: "11/04/2016" f1_keywords: ["COlePropertiesDialog", "AFXODLGS/COlePropertiesDialog", "AFXODLGS/COlePropertiesDialog::COlePropertiesDialog", "AFXODLGS/COlePropertiesDialog::DoModal", "AFXODLGS/COlePropertiesDialog::OnApplyScale", "AFXODLGS/COlePropertiesDialog::m_gp", "AFXODLGS/COlePropertiesDialog::m_lp", "AFXODLGS/COlePropertiesDialog::m_op", "AFXODLGS/COlePropertiesDialog::m_psh", "AFXODLGS/COlePropertiesDialog::m_vp"] helpviewer_keywords: ["COlePropertiesDialog [MFC], COlePropertiesDialog", "COlePropertiesDialog [MFC], DoModal", "COlePropertiesDialog [MFC], OnApplyScale", "COlePropertiesDialog [MFC], m_gp", "COlePropertiesDialog [MFC], m_lp", "COlePropertiesDialog [MFC], m_op", "COlePropertiesDialog [MFC], m_psh", "COlePropertiesDialog [MFC], m_vp"] -ms.assetid: a54dbc89-1447-4329-bd01-00e98ec9e935 --- # COlePropertiesDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the Windows common OLE Object Properties dialog box. ## Syntax diff --git a/docs/mfc/reference/colepropertypage-class.md b/docs/mfc/reference/colepropertypage-class.md index bc1c760b238..e9d69c786df 100644 --- a/docs/mfc/reference/colepropertypage-class.md +++ b/docs/mfc/reference/colepropertypage-class.md @@ -4,10 +4,12 @@ title: "COlePropertyPage Class" ms.date: "11/04/2016" f1_keywords: ["COlePropertyPage", "AFXCTL/COlePropertyPage", "AFXCTL/COlePropertyPage::COlePropertyPage", "AFXCTL/COlePropertyPage::GetControlStatus", "AFXCTL/COlePropertyPage::GetObjectArray", "AFXCTL/COlePropertyPage::GetPageSite", "AFXCTL/COlePropertyPage::OVERWRITEApply", "AFXCTL/COlePropertyPage::IsModified", "AFXCTL/COlePropertyPage::OnEditProperty", "AFXCTL/COlePropertyPage::OnHelp", "AFXCTL/COlePropertyPage::OnInitDialog", "AFXCTL/COlePropertyPage::OnObjectsChanged", "AFXCTL/COlePropertyPage::OnSetPageSite", "AFXCTL/COlePropertyPage::SetControlStatus", "AFXCTL/COlePropertyPage::SetDialogResource", "AFXCTL/COlePropertyPage::SetHelpInfo", "AFXCTL/COlePropertyPage::SetModifiedFlag", "AFXCTL/COlePropertyPage::SetPageName"] helpviewer_keywords: ["COlePropertyPage [MFC], COlePropertyPage", "COlePropertyPage [MFC], GetControlStatus", "COlePropertyPage [MFC], GetObjectArray", "COlePropertyPage [MFC], GetPageSite", "COlePropertyPage [MFC], IgnoreApply", "COlePropertyPage [MFC], IsModified", "COlePropertyPage [MFC], OnEditProperty", "COlePropertyPage [MFC], OnHelp", "COlePropertyPage [MFC], OnInitDialog", "COlePropertyPage [MFC], OnObjectsChanged", "COlePropertyPage [MFC], OnSetPageSite", "COlePropertyPage [MFC], SetControlStatus", "COlePropertyPage [MFC], SetDialogResource", "COlePropertyPage [MFC], SetHelpInfo", "COlePropertyPage [MFC], SetModifiedFlag", "COlePropertyPage [MFC], SetPageName"] -ms.assetid: e9972872-8e6b-4550-905e-d36a274d64dc --- # COlePropertyPage Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used to display the properties of a custom control in a graphical interface, similar to a dialog box. ## Syntax diff --git a/docs/mfc/reference/coleresizebar-class.md b/docs/mfc/reference/coleresizebar-class.md index 1066e554e7a..5909bb78628 100644 --- a/docs/mfc/reference/coleresizebar-class.md +++ b/docs/mfc/reference/coleresizebar-class.md @@ -4,10 +4,12 @@ title: "COleResizeBar Class" ms.date: "11/04/2016" f1_keywords: ["COleResizeBar", "AFXOLE/COleResizeBar", "AFXOLE/COleResizeBar::COleResizeBar", "AFXOLE/COleResizeBar::Create"] helpviewer_keywords: ["COleResizeBar [MFC], COleResizeBar", "COleResizeBar [MFC], Create"] -ms.assetid: 56a708d9-28c5-4eb0-9404-77b688d91c63 --- # COleResizeBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A type of control bar that supports resizing of in-place OLE items. ## Syntax diff --git a/docs/mfc/reference/colesafearray-class.md b/docs/mfc/reference/colesafearray-class.md index 1efbd04b7f8..322140c97cd 100644 --- a/docs/mfc/reference/colesafearray-class.md +++ b/docs/mfc/reference/colesafearray-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: COleSafeArray Class" title: "COleSafeArray Class" -ms.date: "08/29/2019" +description: "Learn more about: COleSafeArray Class" +ms.date: 08/29/2019 f1_keywords: ["COleSafeArray", "AFXDISP/COleSafeArray", "AFXDISP/COleSafeArray::COleSafeArray", "AFXDISP/COleSafeArray::AccessData", "AFXDISP/COleSafeArray::AllocData", "AFXDISP/COleSafeArray::AllocDescriptor", "AFXDISP/COleSafeArray::Attach", "AFXDISP/COleSafeArray::Clear", "AFXDISP/COleSafeArray::Copy", "AFXDISP/COleSafeArray::Create", "AFXDISP/COleSafeArray::CreateOneDim", "AFXDISP/COleSafeArray::Destroy", "AFXDISP/COleSafeArray::DestroyData", "AFXDISP/COleSafeArray::DestroyDescriptor", "AFXDISP/COleSafeArray::Detach", "AFXDISP/COleSafeArray::GetByteArray", "AFXDISP/COleSafeArray::GetDim", "AFXDISP/COleSafeArray::GetElement", "AFXDISP/COleSafeArray::GetElemSize", "AFXDISP/COleSafeArray::GetLBound", "AFXDISP/COleSafeArray::GetOneDimSize", "AFXDISP/COleSafeArray::GetUBound", "AFXDISP/COleSafeArray::Lock", "AFXDISP/COleSafeArray::PtrOfIndex", "AFXDISP/COleSafeArray::PutElement", "AFXDISP/COleSafeArray::Redim", "AFXDISP/COleSafeArray::ResizeOneDim", "AFXDISP/COleSafeArray::UnaccessData", "AFXDISP/COleSafeArray::Unlock"] helpviewer_keywords: ["COleSafeArray [MFC], COleSafeArray", "COleSafeArray [MFC], AccessData", "COleSafeArray [MFC], AllocData", "COleSafeArray [MFC], AllocDescriptor", "COleSafeArray [MFC], Attach", "COleSafeArray [MFC], Clear", "COleSafeArray [MFC], Copy", "COleSafeArray [MFC], Create", "COleSafeArray [MFC], CreateOneDim", "COleSafeArray [MFC], Destroy", "COleSafeArray [MFC], DestroyData", "COleSafeArray [MFC], DestroyDescriptor", "COleSafeArray [MFC], Detach", "COleSafeArray [MFC], GetByteArray", "COleSafeArray [MFC], GetDim", "COleSafeArray [MFC], GetElement", "COleSafeArray [MFC], GetElemSize", "COleSafeArray [MFC], GetLBound", "COleSafeArray [MFC], GetOneDimSize", "COleSafeArray [MFC], GetUBound", "COleSafeArray [MFC], Lock", "COleSafeArray [MFC], PtrOfIndex", "COleSafeArray [MFC], PutElement", "COleSafeArray [MFC], Redim", "COleSafeArray [MFC], ResizeOneDim", "COleSafeArray [MFC], UnaccessData", "COleSafeArray [MFC], Unlock"] -ms.assetid: f45a5224-5f48-40ec-9ddd-287ef9740150 --- # COleSafeArray Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A class for working with arrays of arbitrary type and dimension. ## Syntax @@ -554,11 +556,14 @@ A brief description of each operator follows: This operator compares two arrays (`SAFEARRAY`, `VARIANT`, `COleVariant`, or `COleSafeArray` arrays) and returns nonzero if they are equal; otherwise 0. ``` -BOOL operator==(const SAFEARRAY& saSrc) const; BOOL operator==(LPCSAFEARRAY pSrc) const; +BOOL operator==(const SAFEARRAY& saSrc) const; +BOOL operator==(LPCSAFEARRAY pSrc) const; -BOOL operator==(const COleSafeArray& saSrc) const; BOOL operator==(const VARIANT& varSrc) const; +BOOL operator==(const COleSafeArray& saSrc) const; +BOOL operator==(const VARIANT& varSrc) const; -BOOL operator==(LPCVARIANT pSrc) const; BOOL operator==(const COleVariant& varSrc) const; +BOOL operator==(LPCVARIANT pSrc) const; +BOOL operator==(const COleVariant& varSrc) const; ``` ### Remarks diff --git a/docs/mfc/reference/coleserverdoc-class.md b/docs/mfc/reference/coleserverdoc-class.md index 59f7a9c34b2..c9c350b8214 100644 --- a/docs/mfc/reference/coleserverdoc-class.md +++ b/docs/mfc/reference/coleserverdoc-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class for OLE server documents. ## Syntax @@ -477,7 +479,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 +517,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 +601,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 +862,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/coleserveritem-class.md b/docs/mfc/reference/coleserveritem-class.md index 44a7e5a498a..61718ed04e1 100644 --- a/docs/mfc/reference/coleserveritem-class.md +++ b/docs/mfc/reference/coleserveritem-class.md @@ -4,10 +4,12 @@ title: "COleServerItem Class" ms.date: "11/04/2016" f1_keywords: ["COleServerItem", "AFXOLE/COleServerItem", "AFXOLE/COleServerItem::COleServerItem", "AFXOLE/COleServerItem::AddOtherClipboardData", "AFXOLE/COleServerItem::CopyToClipboard", "AFXOLE/COleServerItem::DoDragDrop", "AFXOLE/COleServerItem::GetClipboardData", "AFXOLE/COleServerItem::GetDocument", "AFXOLE/COleServerItem::GetEmbedSourceData", "AFXOLE/COleServerItem::GetItemName", "AFXOLE/COleServerItem::GetLinkSourceData", "AFXOLE/COleServerItem::GetObjectDescriptorData", "AFXOLE/COleServerItem::IsConnected", "AFXOLE/COleServerItem::IsLinkedItem", "AFXOLE/COleServerItem::NotifyChanged", "AFXOLE/COleServerItem::OnDoVerb", "AFXOLE/COleServerItem::OnDraw", "AFXOLE/COleServerItem::OnDrawEx", "AFXOLE/COleServerItem::OnGetClipboardData", "AFXOLE/COleServerItem::OnGetExtent", "AFXOLE/COleServerItem::OnInitFromData", "AFXOLE/COleServerItem::OnQueryUpdateItems", "AFXOLE/COleServerItem::OnRenderData", "AFXOLE/COleServerItem::OnRenderFileData", "AFXOLE/COleServerItem::OnRenderGlobalData", "AFXOLE/COleServerItem::OnSetColorScheme", "AFXOLE/COleServerItem::OnSetData", "AFXOLE/COleServerItem::OnSetExtent", "AFXOLE/COleServerItem::OnUpdate", "AFXOLE/COleServerItem::OnUpdateItems", "AFXOLE/COleServerItem::SetItemName", "AFXOLE/COleServerItem::GetDataSource", "AFXOLE/COleServerItem::OnHide", "AFXOLE/COleServerItem::OnOpen", "AFXOLE/COleServerItem::OnShow", "AFXOLE/COleServerItem::m_sizeExtent"] helpviewer_keywords: ["COleServerItem [MFC], COleServerItem", "COleServerItem [MFC], AddOtherClipboardData", "COleServerItem [MFC], CopyToClipboard", "COleServerItem [MFC], DoDragDrop", "COleServerItem [MFC], GetClipboardData", "COleServerItem [MFC], GetDocument", "COleServerItem [MFC], GetEmbedSourceData", "COleServerItem [MFC], GetItemName", "COleServerItem [MFC], GetLinkSourceData", "COleServerItem [MFC], GetObjectDescriptorData", "COleServerItem [MFC], IsConnected", "COleServerItem [MFC], IsLinkedItem", "COleServerItem [MFC], NotifyChanged", "COleServerItem [MFC], OnDoVerb", "COleServerItem [MFC], OnDraw", "COleServerItem [MFC], OnDrawEx", "COleServerItem [MFC], OnGetClipboardData", "COleServerItem [MFC], OnGetExtent", "COleServerItem [MFC], OnInitFromData", "COleServerItem [MFC], OnQueryUpdateItems", "COleServerItem [MFC], OnRenderData", "COleServerItem [MFC], OnRenderFileData", "COleServerItem [MFC], OnRenderGlobalData", "COleServerItem [MFC], OnSetColorScheme", "COleServerItem [MFC], OnSetData", "COleServerItem [MFC], OnSetExtent", "COleServerItem [MFC], OnUpdate", "COleServerItem [MFC], OnUpdateItems", "COleServerItem [MFC], SetItemName", "COleServerItem [MFC], GetDataSource", "COleServerItem [MFC], OnHide", "COleServerItem [MFC], OnOpen", "COleServerItem [MFC], OnShow", "COleServerItem [MFC], m_sizeExtent"] -ms.assetid: 80256df6-3888-4256-944b-787d4b2e6b0d --- # COleServerItem Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the server interface to OLE items. ## Syntax diff --git a/docs/mfc/reference/colestreamfile-class.md b/docs/mfc/reference/colestreamfile-class.md index 053820436c5..62128112f58 100644 --- a/docs/mfc/reference/colestreamfile-class.md +++ b/docs/mfc/reference/colestreamfile-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a stream of data (`IStream`) in a compound file as part of OLE Structured Storage. ## Syntax @@ -41,7 +43,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 +224,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/coletemplateserver-class.md b/docs/mfc/reference/coletemplateserver-class.md index e497aa5a489..2c2175eb464 100644 --- a/docs/mfc/reference/coletemplateserver-class.md +++ b/docs/mfc/reference/coletemplateserver-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: COleTemplateServer Class" title: "COleTemplateServer Class" -ms.date: "11/04/2016" +description: "Learn more about: COleTemplateServer Class" +ms.date: 11/04/2016 f1_keywords: ["COleTemplateServer", "AFXDISP/COleTemplateServer", "AFXDISP/COleTemplateServer::COleTemplateServer", "AFXDISP/COleTemplateServer::ConnectTemplate", "AFXDISP/COleTemplateServer::Unregister", "AFXDISP/COleTemplateServer::UpdateRegistry"] helpviewer_keywords: ["COleTemplateServer [MFC], COleTemplateServer", "COleTemplateServer [MFC], ConnectTemplate", "COleTemplateServer [MFC], Unregister", "COleTemplateServer [MFC], UpdateRegistry"] -ms.assetid: 47a2887d-8162-4993-a842-a784177c7f5c --- # COleTemplateServer Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Used for OLE visual editing servers, automation servers, and link containers (applications that support links to embeddings). ## Syntax @@ -104,10 +106,6 @@ BOOL Unregister(); TRUE if successful; otherwise FALSE. -### Remarks - -EnterRemarks - ## COleTemplateServer::UpdateRegistry Loads file-type information from the document-template string and places that information in the OLE system registry. diff --git a/docs/mfc/reference/coleupdatedialog-class.md b/docs/mfc/reference/coleupdatedialog-class.md index 326d47c4ada..fecc99693b3 100644 --- a/docs/mfc/reference/coleupdatedialog-class.md +++ b/docs/mfc/reference/coleupdatedialog-class.md @@ -4,10 +4,12 @@ title: "COleUpdateDialog Class" ms.date: "11/04/2016" f1_keywords: ["COleUpdateDialog", "AFXODLGS/COleUpdateDialog", "AFXODLGS/COleUpdateDialog::COleUpdateDialog", "AFXODLGS/COleUpdateDialog::DoModal"] helpviewer_keywords: ["COleUpdateDialog [MFC], COleUpdateDialog", "COleUpdateDialog [MFC], DoModal"] -ms.assetid: 699ca980-52b1-4cf8-9ab1-ac6767ad5b0e --- # COleUpdateDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax diff --git a/docs/mfc/reference/colevariant-class.md b/docs/mfc/reference/colevariant-class.md index 7879d57253a..2bea4e14753 100644 --- a/docs/mfc/reference/colevariant-class.md +++ b/docs/mfc/reference/colevariant-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the [VARIANT](/windows/win32/api/oaidl/ns-oaidl-variant) data type. ## Syntax @@ -52,7 +54,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 +152,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 4db46796895..b89b18ac671 100644 --- a/docs/mfc/reference/collection-class-helpers.md +++ b/docs/mfc/reference/collection-class-helpers.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The collection classes `CMap`, `CList`, and `CArray` use templated global helper functions for such purposes as comparing, copying, and serializing elements. As part of your implementation of classes based on `CMap`, `CList`, and `CArray`, you must override these functions as necessary with versions tailored to the type of data stored in your map, list, or array. For information on overriding helper functions such as `SerializeElements`, see the article [Collections: How to Make a Type-Safe Collection](../../mfc/how-to-make-a-type-safe-collection.md). Note that `ConstructElements` and `DestructElements` have been deprecated. The Microsoft Foundation Class Library provides the following global functions in afxtempl.h to help you customize your collection classes: @@ -57,7 +59,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/combo-box-handlers.md b/docs/mfc/reference/combo-box-handlers.md index 46257dcaf02..f95c442ef4c 100644 --- a/docs/mfc/reference/combo-box-handlers.md +++ b/docs/mfc/reference/combo-box-handlers.md @@ -4,10 +4,12 @@ title: "Combo Box Handlers" ms.date: "11/04/2016" f1_keywords: ["ON_CBN_KILLFOCUS", "ON_CBN_ERRSPACE", "ON_CBN_EDITCHANGE", "ON_CBN_CLOSEUP", "ON_CBN_DBLCLK", "ON_CBN_EDITUPDATE", "ON_CBN_DROPDOWN", "ON_CBN_SELENDOK", "ON_CBN_SELCHANGE", "ON_CBN_SETFOCUS", "ON_CBN_SELENDCANCEL"] helpviewer_keywords: ["ON_CBN_CLOSEUP", "ON_CBN_SETFOCUS", "ON_CBN_DBLCLK", "ON_CBN_SELENDCANCEL", "ON_CBN_DROPDOWN", "ON_CBN_EDITUPDATE", "ON_CBN_KILLFOCUS", "combo boxes [MFC], handlers", "ON_CBN_EDITCHANGE", "ON_CBN_ERRSPACE", "ON_CBN_SELENDOK", "ON_CBN_SELCHANGE"] -ms.assetid: 7f092412-01b7-4242-95ec-41ba506b9d71 --- # Combo Box Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries correspond to the function prototypes. |Map entry|Function prototype| diff --git a/docs/mfc/reference/compound-document-support-mfc-application-wizard.md b/docs/mfc/reference/compound-document-support-mfc-application-wizard.md index cf2cac48dfd..6ad2ec8f2f1 100644 --- a/docs/mfc/reference/compound-document-support-mfc-application-wizard.md +++ b/docs/mfc/reference/compound-document-support-mfc-application-wizard.md @@ -3,10 +3,12 @@ description: "Learn more about: Compound Document Support, MFC Application Wizar title: "Compound Document Support, MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.compdoc"] -ms.assetid: 42e1af83-12c4-438d-92eb-13835afdb148 --- # Compound Document Support, MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In this page of the MFC Application Wizard, indicate to what level your application provides compound and active document support. Your application must support the document/view architecture to support compound documents and document templates. By default, the application contains no compound document support. If you accept this default, your application cannot support active documents or compound files. diff --git a/docs/mfc/reference/connection-maps.md b/docs/mfc/reference/connection-maps.md index dda5d5f1d10..db3d8ce0988 100644 --- a/docs/mfc/reference/connection-maps.md +++ b/docs/mfc/reference/connection-maps.md @@ -1,174 +1,177 @@ --- -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 + +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. 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 +180,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 +201,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 +230,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 +247,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 +276,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/control-names-mfc-activex-control-wizard.md b/docs/mfc/reference/control-names-mfc-activex-control-wizard.md index 9d6baedbd15..1ee01d5de06 100644 --- a/docs/mfc/reference/control-names-mfc-activex-control-wizard.md +++ b/docs/mfc/reference/control-names-mfc-activex-control-wizard.md @@ -4,10 +4,12 @@ title: "Control Names, MFC ActiveX Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.ctl.names"] helpviewer_keywords: ["MFC ActiveX Control Wizard, control names"] -ms.assetid: 9b8b81d2-36df-48ed-b58a-a771a0e269ee --- # Control Names, MFC ActiveX Control Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Specify the names for the control class and property page class, the type names, and type identifiers for your control. With the exception of **Short name**, all other fields can be edited independently. If you change the text for **Short name**, the change is reflected in the names of all other fields in this page. This naming behavior is designed to make all the names easily identifiable for you as you develop your control. - **Short name** diff --git a/docs/mfc/reference/control-settings-mfc-activex-control-wizard.md b/docs/mfc/reference/control-settings-mfc-activex-control-wizard.md index 6fe38cbe3b5..6c7a98c6210 100644 --- a/docs/mfc/reference/control-settings-mfc-activex-control-wizard.md +++ b/docs/mfc/reference/control-settings-mfc-activex-control-wizard.md @@ -4,10 +4,12 @@ title: "Control Settings, MFC ActiveX Control Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.ctl.settings"] helpviewer_keywords: ["MFC ActiveX Control Wizard, control settings"] -ms.assetid: 2ccaa4fc-0d52-413e-afa3-ecd474c3f6f0 --- # Control Settings, MFC ActiveX Control Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use this page of the wizard to specify how you want the control to behave. For example, you can base the control on standard Windows control types, optimize its behavior and appearance, or indicate that the control can act as a container for other controls. For more information about how to select options on this page to maximize the efficiency of the control, see [MFC ActiveX Controls: Optimization](../../mfc/mfc-activex-controls-optimization.md). diff --git a/docs/mfc/reference/cpagerctrl-class.md b/docs/mfc/reference/cpagerctrl-class.md index 78da74a2235..e04ec30cc21 100644 --- a/docs/mfc/reference/cpagerctrl-class.md +++ b/docs/mfc/reference/cpagerctrl-class.md @@ -4,10 +4,12 @@ title: "CPagerCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CPagerCtrl", "AFXCMN/CPagerCtrl", "AFXCMN/CPagerCtrl::CPagerCtrl", "AFXCMN/CPagerCtrl::Create", "AFXCMN/CPagerCtrl::CreateEx", "AFXCMN/CPagerCtrl::ForwardMouse", "AFXCMN/CPagerCtrl::GetBkColor", "AFXCMN/CPagerCtrl::GetBorder", "AFXCMN/CPagerCtrl::GetButtonSize", "AFXCMN/CPagerCtrl::GetButtonState", "AFXCMN/CPagerCtrl::GetDropTarget", "AFXCMN/CPagerCtrl::GetScrollPos", "AFXCMN/CPagerCtrl::IsButtonDepressed", "AFXCMN/CPagerCtrl::IsButtonGrayed", "AFXCMN/CPagerCtrl::IsButtonHot", "AFXCMN/CPagerCtrl::IsButtonInvisible", "AFXCMN/CPagerCtrl::IsButtonNormal", "AFXCMN/CPagerCtrl::RecalcSize", "AFXCMN/CPagerCtrl::SetBkColor", "AFXCMN/CPagerCtrl::SetBorder", "AFXCMN/CPagerCtrl::SetButtonSize", "AFXCMN/CPagerCtrl::SetChild", "AFXCMN/CPagerCtrl::SetScrollPos"] helpviewer_keywords: ["CPagerCtrl [MFC], CPagerCtrl", "CPagerCtrl [MFC], Create", "CPagerCtrl [MFC], CreateEx", "CPagerCtrl [MFC], ForwardMouse", "CPagerCtrl [MFC], GetBkColor", "CPagerCtrl [MFC], GetBorder", "CPagerCtrl [MFC], GetButtonSize", "CPagerCtrl [MFC], GetButtonState", "CPagerCtrl [MFC], GetDropTarget", "CPagerCtrl [MFC], GetScrollPos", "CPagerCtrl [MFC], IsButtonDepressed", "CPagerCtrl [MFC], IsButtonGrayed", "CPagerCtrl [MFC], IsButtonHot", "CPagerCtrl [MFC], IsButtonInvisible", "CPagerCtrl [MFC], IsButtonNormal", "CPagerCtrl [MFC], RecalcSize", "CPagerCtrl [MFC], SetBkColor", "CPagerCtrl [MFC], SetBorder", "CPagerCtrl [MFC], SetButtonSize", "CPagerCtrl [MFC], SetChild", "CPagerCtrl [MFC], SetScrollPos"] -ms.assetid: 65ac58dd-4f5e-4b7e-b15c-e0d435a7e884 --- # CPagerCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CPagerCtrl` class wraps the Windows pager control, which can scroll into view a contained window that does not fit the containing window. ## Syntax diff --git a/docs/mfc/reference/cpagesetupdialog-class.md b/docs/mfc/reference/cpagesetupdialog-class.md index bf629aa89cc..296f1412590 100644 --- a/docs/mfc/reference/cpagesetupdialog-class.md +++ b/docs/mfc/reference/cpagesetupdialog-class.md @@ -4,10 +4,12 @@ title: "CPageSetupDialog Class" ms.date: "11/04/2016" f1_keywords: ["CPageSetupDialog", "AFXDLGS/CPageSetupDialog", "AFXDLGS/CPageSetupDialog::CPageSetupDialog", "AFXDLGS/CPageSetupDialog::CreatePrinterDC", "AFXDLGS/CPageSetupDialog::DoModal", "AFXDLGS/CPageSetupDialog::GetDeviceName", "AFXDLGS/CPageSetupDialog::GetDevMode", "AFXDLGS/CPageSetupDialog::GetDriverName", "AFXDLGS/CPageSetupDialog::GetMargins", "AFXDLGS/CPageSetupDialog::GetPaperSize", "AFXDLGS/CPageSetupDialog::GetPortName", "AFXDLGS/CPageSetupDialog::OnDrawPage", "AFXDLGS/CPageSetupDialog::PreDrawPage", "AFXDLGS/CPageSetupDialog::m_psd"] helpviewer_keywords: ["CPageSetupDialog [MFC], CPageSetupDialog", "CPageSetupDialog [MFC], CreatePrinterDC", "CPageSetupDialog [MFC], DoModal", "CPageSetupDialog [MFC], GetDeviceName", "CPageSetupDialog [MFC], GetDevMode", "CPageSetupDialog [MFC], GetDriverName", "CPageSetupDialog [MFC], GetMargins", "CPageSetupDialog [MFC], GetPaperSize", "CPageSetupDialog [MFC], GetPortName", "CPageSetupDialog [MFC], OnDrawPage", "CPageSetupDialog [MFC], PreDrawPage", "CPageSetupDialog [MFC], m_psd"] -ms.assetid: 049c0ac8-f254-4854-9414-7a8271d1447a --- # CPageSetupDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the services provided by the Windows common OLE Page Setup dialog box with additional support for setting and modifying print margins. ## Syntax diff --git a/docs/mfc/reference/cpaintdc-class.md b/docs/mfc/reference/cpaintdc-class.md index dc01823c28e..9f5268f8d58 100644 --- a/docs/mfc/reference/cpaintdc-class.md +++ b/docs/mfc/reference/cpaintdc-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CPaintDC [MFC], CPaintDC", "CPaintDC [MFC], m_ps", "CPain --- # `CPaintDC` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A device-context class derived from [`CDC`](../../mfc/reference/cdc-class.md). ## Syntax diff --git a/docs/mfc/reference/cpalette-class.md b/docs/mfc/reference/cpalette-class.md index c07f7e48beb..7c40fbda689 100644 --- a/docs/mfc/reference/cpalette-class.md +++ b/docs/mfc/reference/cpalette-class.md @@ -4,10 +4,12 @@ title: "CPalette Class" ms.date: "11/04/2016" f1_keywords: ["CPalette", "AFXWIN/CPalette", "AFXWIN/CPalette::CPalette", "AFXWIN/CPalette::AnimatePalette", "AFXWIN/CPalette::CreateHalftonePalette", "AFXWIN/CPalette::CreatePalette", "AFXWIN/CPalette::FromHandle", "AFXWIN/CPalette::GetEntryCount", "AFXWIN/CPalette::GetNearestPaletteIndex", "AFXWIN/CPalette::GetPaletteEntries", "AFXWIN/CPalette::ResizePalette", "AFXWIN/CPalette::SetPaletteEntries"] helpviewer_keywords: ["CPalette [MFC], CPalette", "CPalette [MFC], AnimatePalette", "CPalette [MFC], CreateHalftonePalette", "CPalette [MFC], CreatePalette", "CPalette [MFC], FromHandle", "CPalette [MFC], GetEntryCount", "CPalette [MFC], GetNearestPaletteIndex", "CPalette [MFC], GetPaletteEntries", "CPalette [MFC], ResizePalette", "CPalette [MFC], SetPaletteEntries"] -ms.assetid: 8cd95498-53ed-4852-85e1-70e522541114 --- # CPalette Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a Windows color palette. ## Syntax diff --git a/docs/mfc/reference/cpane-class.md b/docs/mfc/reference/cpane-class.md index 9611f4835af..b80f5cbffa5 100644 --- a/docs/mfc/reference/cpane-class.md +++ b/docs/mfc/reference/cpane-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CPane Class" title: "CPane Class" -ms.date: "11/04/2016" +description: "Learn more about: CPane Class" +ms.date: 11/04/2016 f1_keywords: ["CPane", "AFXPANE/CPane", "AFXPANE/CPane::AdjustSizeImmediate", "AFXPANE/CPane::AllocElements", "AFXPANE/CPane::AllowShowOnPaneMenu", "AFXPANE/CPane::CalcAvailableSize", "AFXPANE/CPane::CalcInsideRect", "AFXPANE/CPane::CalcRecentDockedRect", "AFXPANE/CPane::CalcSize", "AFXPANE/CPane::CanBeDocked", "AFXPANE/CPane::CanBeTabbedDocument", "AFXPANE/CPane::ConvertToTabbedDocument", "AFXPANE/CPane::CopyState", "AFXPANE/CPane::Create", "AFXPANE/CPane::CreateDefaultMiniframe", "AFXPANE/CPane::CreateEx", "AFXPANE/CPane::DockByMouse", "AFXPANE/CPane::DockPane", "AFXPANE/CPane::DockPaneStandard", "AFXPANE/CPane::DockToFrameWindow", "AFXPANE/CPane::DoesAllowSiblingBars", "AFXPANE/CPane::FloatPane", "AFXPANE/CPane::GetAvailableExpandSize", "AFXPANE/CPane::GetAvailableStretchSize", "AFXPANE/CPane::GetBorders", "AFXPANE/CPane::GetClientHotSpot", "AFXPANE/CPane::GetDockSiteRow", "AFXPANE/CPane::GetExclusiveRowMode", "AFXPANE/CPane::GetHotSpot", "AFXPANE/CPane::GetMinSize", "AFXPANE/CPane::GetPaneName", "AFXPANE/CPane::GetVirtualRect", "AFXPANE/CPane::IsChangeState", "AFXPANE/CPane::IsDragMode", "AFXPANE/CPane::IsInFloatingMultiPaneFrameWnd", "AFXPANE/CPane::IsLeftOf", "AFXPANE/CPane::IsResizable", "AFXPANE/CPane::IsTabbed", "AFXPANE/CPane::LoadState", "AFXPANE/CPane::MoveByAlignment", "AFXPANE/CPane::MovePane", "AFXPANE/CPane::OnAfterChangeParent", "AFXPANE/CPane::OnBeforeChangeParent", "AFXPANE/CPane::OnPressCloseButton", "AFXPANE/CPane::OnShowControlBarMenu", "AFXPANE/CPane::RecalcLayout", "AFXPANE/CPane::SaveState", "AFXPANE/CPane::SetActiveInGroup", "AFXPANE/CPane::SetBorders", "AFXPANE/CPane::SetClientHotSpot", "AFXPANE/CPane::SetDockState", "AFXPANE/CPane::SetExclusiveRowMode", "AFXPANE/CPane::SetMiniFrameRTC", "AFXPANE/CPane::SetMinSize", "AFXPANE/CPane::SetVirtualRect", "AFXPANE/CPane::StretchPaneDeferWndPos", "AFXPANE/CPane::ToggleAutoHide", "AFXPANE/CPane::UndockPane", "AFXPANE/CPane::UpdateVirtualRect", "AFXPANE/CPane::OnAfterDock", "AFXPANE/CPane::OnAfterFloat", "AFXPANE/CPane::OnBeforeDock", "AFXPANE/CPane::OnBeforeFloat", "AFXPANE/CPane::m_bHandleMinSize", "AFXPANE/CPane::m_recentDockInfo"] helpviewer_keywords: ["CPane [MFC], AdjustSizeImmediate", "CPane [MFC], AllocElements", "CPane [MFC], AllowShowOnPaneMenu", "CPane [MFC], CalcAvailableSize", "CPane [MFC], CalcInsideRect", "CPane [MFC], CalcRecentDockedRect", "CPane [MFC], CalcSize", "CPane [MFC], CanBeDocked", "CPane [MFC], CanBeTabbedDocument", "CPane [MFC], ConvertToTabbedDocument", "CPane [MFC], CopyState", "CPane [MFC], Create", "CPane [MFC], CreateDefaultMiniframe", "CPane [MFC], CreateEx", "CPane [MFC], DockByMouse", "CPane [MFC], DockPane", "CPane [MFC], DockPaneStandard", "CPane [MFC], DockToFrameWindow", "CPane [MFC], DoesAllowSiblingBars", "CPane [MFC], FloatPane", "CPane [MFC], GetAvailableExpandSize", "CPane [MFC], GetAvailableStretchSize", "CPane [MFC], GetBorders", "CPane [MFC], GetClientHotSpot", "CPane [MFC], GetDockSiteRow", "CPane [MFC], GetExclusiveRowMode", "CPane [MFC], GetHotSpot", "CPane [MFC], GetMinSize", "CPane [MFC], GetPaneName", "CPane [MFC], GetVirtualRect", "CPane [MFC], IsChangeState", "CPane [MFC], IsDragMode", "CPane [MFC], IsInFloatingMultiPaneFrameWnd", "CPane [MFC], IsLeftOf", "CPane [MFC], IsResizable", "CPane [MFC], IsTabbed", "CPane [MFC], LoadState", "CPane [MFC], MoveByAlignment", "CPane [MFC], MovePane", "CPane [MFC], OnAfterChangeParent", "CPane [MFC], OnBeforeChangeParent", "CPane [MFC], OnPressCloseButton", "CPane [MFC], OnShowControlBarMenu", "CPane [MFC], OnShowControlBarMenu", "CPane [MFC], RecalcLayout", "CPane [MFC], SaveState", "CPane [MFC], SetActiveInGroup", "CPane [MFC], SetBorders", "CPane [MFC], SetClientHotSpot", "CPane [MFC], SetDockState", "CPane [MFC], SetExclusiveRowMode", "CPane [MFC], SetMiniFrameRTC", "CPane [MFC], SetMinSize", "CPane [MFC], SetVirtualRect", "CPane [MFC], StretchPaneDeferWndPos", "CPane [MFC], ToggleAutoHide", "CPane [MFC], UndockPane", "CPane [MFC], UpdateVirtualRect", "CPane [MFC], OnAfterDock", "CPane [MFC], OnAfterFloat", "CPane [MFC], OnBeforeDock", "CPane [MFC], OnBeforeFloat", "CPane [MFC], m_bHandleMinSize", "CPane [MFC], m_recentDockInfo"] -ms.assetid: 5c651a64-3c79-4d94-9676-45f6402a6bc5 --- # CPane Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CPane` class is an enhancement of the [CControlBar Class](../../mfc/reference/ccontrolbar-class.md). If you are upgrading an existing MFC project, replace all occurrences of `CControlBar` with `CPane`. ## Syntax @@ -75,7 +77,6 @@ class CPane : public CBasePane |[CPane::OnPressCloseButton](#onpressclosebutton)|Called by the framework when the user chooses the Close button on the caption for the pane.| |`CPane::OnProcessDblClk`|Used internally.| |[CPane::OnShowControlBarMenu](#onshowcontrolbarmenu)|Called by the framework when a special pane menu is about to be displayed.| -|[CPane::OnShowControlBarMenu](#onshowcontrolbarmenu)|Called by the framework when a special pane menu is about to be displayed.| |`CPane::PrepareToDock`|Used internally.| |[CPane::RecalcLayout](#recalclayout)|Recalculates layout information for the pane. (Overrides [CBasePane::RecalcLayout](../../mfc/reference/cbasepane-class.md#recalclayout).)| |[CPane::SaveState](#savestate)|Saves the state of the pane to the registry. (Overrides [CBasePane::SaveState](../../mfc/reference/cbasepane-class.md#savestate).)| diff --git a/docs/mfc/reference/cpanecontainer-class.md b/docs/mfc/reference/cpanecontainer-class.md index b259352e618..3dfdcf4bdca 100644 --- a/docs/mfc/reference/cpanecontainer-class.md +++ b/docs/mfc/reference/cpanecontainer-class.md @@ -1,14 +1,16 @@ --- -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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +845,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/cpanecontainermanager-class.md b/docs/mfc/reference/cpanecontainermanager-class.md index 0adabe6f729..65836da7866 100644 --- a/docs/mfc/reference/cpanecontainermanager-class.md +++ b/docs/mfc/reference/cpanecontainermanager-class.md @@ -4,10 +4,12 @@ title: "CPaneContainerManager Class" ms.date: "11/04/2016" f1_keywords: ["CPaneContainerManager", "AFXPANECONTAINERMANAGER/CPaneContainerManager", "AFXPANECONTAINERMANAGER/CPaneContainerManager::AddPane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::AddPaneContainerManager", "AFXPANECONTAINERMANAGER/CPaneContainerManager::AddPaneContainerManagerToDockablePane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::AddPanesToList", "AFXPANECONTAINERMANAGER/CPaneContainerManager::AddPaneToList", "AFXPANECONTAINERMANAGER/CPaneContainerManager::AddPaneToRecentPaneContainer", "AFXPANECONTAINERMANAGER/CPaneContainerManager::CalcRects", "AFXPANECONTAINERMANAGER/CPaneContainerManager::CanBeAttached", "AFXPANECONTAINERMANAGER/CPaneContainerManager::CheckAndRemoveNonValidPane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::CheckForMiniFrameAndCaption", "AFXPANECONTAINERMANAGER/CPaneContainerManager::Create", "AFXPANECONTAINERMANAGER/CPaneContainerManager::DoesAllowDynInsertBefore", "AFXPANECONTAINERMANAGER/CPaneContainerManager::DoesContainFloatingPane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::EnableGrippers", "AFXPANECONTAINERMANAGER/CPaneContainerManager::FindPaneContainer", "AFXPANECONTAINERMANAGER/CPaneContainerManager::FindTabbedPane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetAvailableSpace", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetDefaultPaneDivider", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetDockSiteFrameWnd", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetFirstPane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetFirstVisiblePane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetMinMaxOffset", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetMinSize", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetNodeCount", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetPaneContainerRTC", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetPaneCount", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetTotalRefCount", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetVisiblePaneCount", "AFXPANECONTAINERMANAGER/CPaneContainerManager::GetWindowRect", "AFXPANECONTAINERMANAGER/CPaneContainerManager::HideAll", "AFXPANECONTAINERMANAGER/CPaneContainerManager::InsertPane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::IsAutoHideMode", "AFXPANECONTAINERMANAGER/CPaneContainerManager::IsEmpty", "AFXPANECONTAINERMANAGER/CPaneContainerManager::IsRootPaneContainerVisible", "AFXPANECONTAINERMANAGER/CPaneContainerManager::NotifyPaneDivider", "AFXPANECONTAINERMANAGER/CPaneContainerManager::OnPaneDividerMove", "AFXPANECONTAINERMANAGER/CPaneContainerManager::OnShowPane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::PaneFromPoint", "AFXPANECONTAINERMANAGER/CPaneContainerManager::ReleaseEmptyPaneContainers", "AFXPANECONTAINERMANAGER/CPaneContainerManager::RemoveAllPanesAndPaneDividers", "AFXPANECONTAINERMANAGER/CPaneContainerManager::RemoveNonValidPanes", "AFXPANECONTAINERMANAGER/CPaneContainerManager::RemovePaneDivider", "AFXPANECONTAINERMANAGER/CPaneContainerManager::RemovePaneFromPaneContainer", "AFXPANECONTAINERMANAGER/CPaneContainerManager::ReplacePane", "AFXPANECONTAINERMANAGER/CPaneContainerManager::ResizePaneContainers", "AFXPANECONTAINERMANAGER/CPaneContainerManager::Serialize", "AFXPANECONTAINERMANAGER/CPaneContainerManager::SetDefaultPaneDividerForPanes", "AFXPANECONTAINERMANAGER/CPaneContainerManager::SetPaneContainerRTC", "AFXPANECONTAINERMANAGER/CPaneContainerManager::SetResizeMode", "AFXPANECONTAINERMANAGER/CPaneContainerManager::StoreRecentDockSiteInfo"] helpviewer_keywords: ["CPaneContainerManager [MFC], AddPane", "CPaneContainerManager [MFC], AddPaneContainerManager", "CPaneContainerManager [MFC], AddPaneContainerManagerToDockablePane", "CPaneContainerManager [MFC], AddPanesToList", "CPaneContainerManager [MFC], AddPaneToList", "CPaneContainerManager [MFC], AddPaneToRecentPaneContainer", "CPaneContainerManager [MFC], CalcRects", "CPaneContainerManager [MFC], CanBeAttached", "CPaneContainerManager [MFC], CheckAndRemoveNonValidPane", "CPaneContainerManager [MFC], CheckForMiniFrameAndCaption", "CPaneContainerManager [MFC], Create", "CPaneContainerManager [MFC], DoesAllowDynInsertBefore", "CPaneContainerManager [MFC], DoesContainFloatingPane", "CPaneContainerManager [MFC], EnableGrippers", "CPaneContainerManager [MFC], FindPaneContainer", "CPaneContainerManager [MFC], FindTabbedPane", "CPaneContainerManager [MFC], GetAvailableSpace", "CPaneContainerManager [MFC], GetDefaultPaneDivider", "CPaneContainerManager [MFC], GetDockSiteFrameWnd", "CPaneContainerManager [MFC], GetFirstPane", "CPaneContainerManager [MFC], GetFirstVisiblePane", "CPaneContainerManager [MFC], GetMinMaxOffset", "CPaneContainerManager [MFC], GetMinSize", "CPaneContainerManager [MFC], GetNodeCount", "CPaneContainerManager [MFC], GetPaneContainerRTC", "CPaneContainerManager [MFC], GetPaneCount", "CPaneContainerManager [MFC], GetTotalRefCount", "CPaneContainerManager [MFC], GetVisiblePaneCount", "CPaneContainerManager [MFC], GetWindowRect", "CPaneContainerManager [MFC], HideAll", "CPaneContainerManager [MFC], InsertPane", "CPaneContainerManager [MFC], IsAutoHideMode", "CPaneContainerManager [MFC], IsEmpty", "CPaneContainerManager [MFC], IsRootPaneContainerVisible", "CPaneContainerManager [MFC], NotifyPaneDivider", "CPaneContainerManager [MFC], OnPaneDividerMove", "CPaneContainerManager [MFC], OnShowPane", "CPaneContainerManager [MFC], PaneFromPoint", "CPaneContainerManager [MFC], ReleaseEmptyPaneContainers", "CPaneContainerManager [MFC], RemoveAllPanesAndPaneDividers", "CPaneContainerManager [MFC], RemoveNonValidPanes", "CPaneContainerManager [MFC], RemovePaneDivider", "CPaneContainerManager [MFC], RemovePaneFromPaneContainer", "CPaneContainerManager [MFC], ReplacePane", "CPaneContainerManager [MFC], ResizePaneContainers", "CPaneContainerManager [MFC], Serialize", "CPaneContainerManager [MFC], SetDefaultPaneDividerForPanes", "CPaneContainerManager [MFC], SetPaneContainerRTC", "CPaneContainerManager [MFC], SetResizeMode", "CPaneContainerManager [MFC], StoreRecentDockSiteInfo"] -ms.assetid: 3d974c15-a62f-4648-bb5b-cc31ab7950af --- # CPaneContainerManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CPaneContainerManager` class manages the storage and display of the current docking layout. For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/cpanedialog-class.md b/docs/mfc/reference/cpanedialog-class.md index 71d8ba02273..43078a07946 100644 --- a/docs/mfc/reference/cpanedialog-class.md +++ b/docs/mfc/reference/cpanedialog-class.md @@ -4,10 +4,12 @@ title: "CPaneDialog Class" ms.date: "11/04/2016" f1_keywords: ["CPaneDialog", "AFXPANEDIALOG/CPaneDialog", "AFXPANEDIALOG/CPaneDialog::Create", "AFXPANEDIALOG/CPaneDialog::HandleInitDialog", "AFXPANEDIALOG/CPaneDialog::SetOccDialogInfo"] helpviewer_keywords: ["CPaneDialog [MFC], Create", "CPaneDialog [MFC], HandleInitDialog", "CPaneDialog [MFC], SetOccDialogInfo"] -ms.assetid: 48a6bb91-4b92-40f5-8907-b3270b146cf6 --- # CPaneDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CPaneDialog` class supports a modeless, dockable dialog box. ## Syntax diff --git a/docs/mfc/reference/cpanedivider-class.md b/docs/mfc/reference/cpanedivider-class.md index 30585e316bf..49f3d48bc3d 100644 --- a/docs/mfc/reference/cpanedivider-class.md +++ b/docs/mfc/reference/cpanedivider-class.md @@ -4,10 +4,12 @@ title: "CPaneDivider Class" ms.date: "11/04/2016" f1_keywords: ["CPaneDivider", "AFXPANEDIVIDER/CPaneDivider", "AFXPANEDIVIDER/CPaneDivider::CPaneDivider", "AFXPANEDIVIDER/CPaneDivider::AddPaneContainer", "AFXPANEDIVIDER/CPaneDivider::AddPane", "AFXPANEDIVIDER/CPaneDivider::AddRecentPane", "AFXPANEDIVIDER/CPaneDivider::CalcExpectedDockedRect", "AFXPANEDIVIDER/CPaneDivider::CalcFixedLayout", "AFXPANEDIVIDER/CPaneDivider::CheckVisibility", "AFXPANEDIVIDER/CPaneDivider::CreateEx", "AFXPANEDIVIDER/CPaneDivider::DoesAllowDynInsertBefore", "AFXPANEDIVIDER/CPaneDivider::DoesContainFloatingPane", "AFXPANEDIVIDER/CPaneDivider::FindPaneContainer", "AFXPANEDIVIDER/CPaneDivider::FindTabbedPane", "AFXPANEDIVIDER/CPaneDivider::GetDefaultWidth", "AFXPANEDIVIDER/CPaneDivider::GetFirstPane", "AFXPANEDIVIDER/CPaneDivider::GetPaneDividerStyle", "AFXPANEDIVIDER/CPaneDivider::GetRootContainerRect", "AFXPANEDIVIDER/CPaneDivider::GetWidth", "AFXPANEDIVIDER/CPaneDivider::Init", "AFXPANEDIVIDER/CPaneDivider::InsertPane", "AFXPANEDIVIDER/CPaneDivider::IsAutoHideMode", "AFXPANEDIVIDER/CPaneDivider::IsDefault", "AFXPANEDIVIDER/CPaneDivider::IsHorizontal", "AFXPANEDIVIDER/CPaneDivider::Move", "AFXPANEDIVIDER/CPaneDivider::NotifyAboutRelease", "AFXPANEDIVIDER/CPaneDivider::OnShowPane", "AFXPANEDIVIDER/CPaneDivider::ReleaseEmptyPaneContainers", "AFXPANEDIVIDER/CPaneDivider::RemovePane", "AFXPANEDIVIDER/CPaneDivider::ReplacePane", "AFXPANEDIVIDER/CPaneDivider::RepositionPanes", "AFXPANEDIVIDER/CPaneDivider::Serialize", "AFXPANEDIVIDER/CPaneDivider::SetAutoHideMode", "AFXPANEDIVIDER/CPaneDivider::SetPaneContainerManager", "AFXPANEDIVIDER/CPaneDivider::ShowWindow", "AFXPANEDIVIDER/CPaneDivider::StoreRecentDockSiteInfo", "AFXPANEDIVIDER/CPaneDivider::StoreRecentTabRelatedInfo", "AFXPANEDIVIDER/CPaneDivider::GetPanes", "AFXPANEDIVIDER/CPaneDivider::GetPaneDividers", "AFXPANEDIVIDER/CPaneDivider::m_nDefaultWidth", "AFXPANEDIVIDER/CPaneDivider::m_pSliderRTC"] helpviewer_keywords: ["CPaneDivider [MFC], CPaneDivider", "CPaneDivider [MFC], AddPaneContainer", "CPaneDivider [MFC], AddPane", "CPaneDivider [MFC], AddRecentPane", "CPaneDivider [MFC], CalcExpectedDockedRect", "CPaneDivider [MFC], CalcFixedLayout", "CPaneDivider [MFC], CheckVisibility", "CPaneDivider [MFC], CreateEx", "CPaneDivider [MFC], DoesAllowDynInsertBefore", "CPaneDivider [MFC], DoesContainFloatingPane", "CPaneDivider [MFC], FindPaneContainer", "CPaneDivider [MFC], FindTabbedPane", "CPaneDivider [MFC], GetDefaultWidth", "CPaneDivider [MFC], GetFirstPane", "CPaneDivider [MFC], GetPaneDividerStyle", "CPaneDivider [MFC], GetRootContainerRect", "CPaneDivider [MFC], GetWidth", "CPaneDivider [MFC], Init", "CPaneDivider [MFC], InsertPane", "CPaneDivider [MFC], IsAutoHideMode", "CPaneDivider [MFC], IsDefault", "CPaneDivider [MFC], IsHorizontal", "CPaneDivider [MFC], Move", "CPaneDivider [MFC], NotifyAboutRelease", "CPaneDivider [MFC], OnShowPane", "CPaneDivider [MFC], ReleaseEmptyPaneContainers", "CPaneDivider [MFC], RemovePane", "CPaneDivider [MFC], ReplacePane", "CPaneDivider [MFC], RepositionPanes", "CPaneDivider [MFC], Serialize", "CPaneDivider [MFC], SetAutoHideMode", "CPaneDivider [MFC], SetPaneContainerManager", "CPaneDivider [MFC], ShowWindow", "CPaneDivider [MFC], StoreRecentDockSiteInfo", "CPaneDivider [MFC], StoreRecentTabRelatedInfo", "CPaneDivider [MFC], GetPanes", "CPaneDivider [MFC], GetPaneDividers", "CPaneDivider [MFC], m_nDefaultWidth", "CPaneDivider [MFC], m_pSliderRTC"] -ms.assetid: 8e828a5d-232f-4127-b8e3-7fa45a7a476e --- # CPaneDivider Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. The `CPaneDivider` class divides two panes, divides two groups of panes, or separates a group of panes from the client area of the main frame window. @@ -92,9 +94,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/cpaneframewnd-class.md b/docs/mfc/reference/cpaneframewnd-class.md index 3c281c3f41c..5c73ad4d607 100644 --- a/docs/mfc/reference/cpaneframewnd-class.md +++ b/docs/mfc/reference/cpaneframewnd-class.md @@ -4,10 +4,12 @@ title: "CPaneFrameWnd Class" ms.date: "11/04/2016" f1_keywords: ["CPaneFrameWnd", "AFXPANEFRAMEWND/CPaneFrameWnd", "AFXPANEFRAMEWND/CPaneFrameWnd::AddPane", "AFXPANEFRAMEWND/CPaneFrameWnd::AddRemovePaneFromGlobalList", "AFXPANEFRAMEWND/CPaneFrameWnd::AdjustLayout", "AFXPANEFRAMEWND/CPaneFrameWnd::AdjustPaneFrames", "AFXPANEFRAMEWND/CPaneFrameWnd::CalcBorderSize", "AFXPANEFRAMEWND/CPaneFrameWnd::CalcExpectedDockedRect", "AFXPANEFRAMEWND/CPaneFrameWnd::CanBeAttached", "AFXPANEFRAMEWND/CPaneFrameWnd::CanBeDockedToPane", "AFXPANEFRAMEWND/CPaneFrameWnd::CheckGripperVisibility", "AFXPANEFRAMEWND/CPaneFrameWnd::ConvertToTabbedDocument", "AFXPANEFRAMEWND/CPaneFrameWnd::Create", "AFXPANEFRAMEWND/CPaneFrameWnd::CreateEx", "AFXPANEFRAMEWND/CPaneFrameWnd::DockPane", "AFXPANEFRAMEWND/CPaneFrameWnd::FindFloatingPaneByID", "AFXPANEFRAMEWND/CPaneFrameWnd::FrameFromPoint", "AFXPANEFRAMEWND/CPaneFrameWnd::GetCaptionHeight", "AFXPANEFRAMEWND/CPaneFrameWnd::GetCaptionRect", "AFXPANEFRAMEWND/CPaneFrameWnd::GetCaptionText", "AFXPANEFRAMEWND/CPaneFrameWnd::GetDockingManager", "AFXPANEFRAMEWND/CPaneFrameWnd::GetDockingMode", "AFXPANEFRAMEWND/CPaneFrameWnd::GetFirstVisiblePane", "AFXPANEFRAMEWND/CPaneFrameWnd::GetHotPoint", "AFXPANEFRAMEWND/CPaneFrameWnd::GetPane", "AFXPANEFRAMEWND/CPaneFrameWnd::GetPaneCount", "AFXPANEFRAMEWND/CPaneFrameWnd::GetParent", "AFXPANEFRAMEWND/CPaneFrameWnd::GetPinState", "AFXPANEFRAMEWND/CPaneFrameWnd::GetRecentFloatingRect", "AFXPANEFRAMEWND/CPaneFrameWnd::GetVisiblePaneCount", "AFXPANEFRAMEWND/CPaneFrameWnd::HitTest", "AFXPANEFRAMEWND/CPaneFrameWnd::IsCaptured", "AFXPANEFRAMEWND/CPaneFrameWnd::IsDelayShow", "AFXPANEFRAMEWND/CPaneFrameWnd::IsRollDown", "AFXPANEFRAMEWND/CPaneFrameWnd::IsRollUp", "AFXPANEFRAMEWND/CPaneFrameWnd::KillDockingTimer", "AFXPANEFRAMEWND/CPaneFrameWnd::LoadState", "AFXPANEFRAMEWND/CPaneFrameWnd::OnBeforeDock", "AFXPANEFRAMEWND/CPaneFrameWnd::OnDockToRecentPos", "AFXPANEFRAMEWND/CPaneFrameWnd::OnKillRollUpTimer", "AFXPANEFRAMEWND/CPaneFrameWnd::OnMovePane", "AFXPANEFRAMEWND/CPaneFrameWnd::OnPaneRecalcLayout", "AFXPANEFRAMEWND/CPaneFrameWnd::OnSetRollUpTimer", "AFXPANEFRAMEWND/CPaneFrameWnd::OnShowPane", "AFXPANEFRAMEWND/CPaneFrameWnd::PaneFromPoint", "AFXPANEFRAMEWND/CPaneFrameWnd::Pin", "AFXPANEFRAMEWND/CPaneFrameWnd::RedrawAll", "AFXPANEFRAMEWND/CPaneFrameWnd::RemoveNonValidPanes", "AFXPANEFRAMEWND/CPaneFrameWnd::RemovePane", "AFXPANEFRAMEWND/CPaneFrameWnd::ReplacePane", "AFXPANEFRAMEWND/CPaneFrameWnd::SaveState", "AFXPANEFRAMEWND/CPaneFrameWnd::SetCaptionButtons", "AFXPANEFRAMEWND/CPaneFrameWnd::SetDelayShow", "AFXPANEFRAMEWND/CPaneFrameWnd::SetDockingManager", "AFXPANEFRAMEWND/CPaneFrameWnd::SetDockingTimer", "AFXPANEFRAMEWND/CPaneFrameWnd::SetDockState", "AFXPANEFRAMEWND/CPaneFrameWnd::SetHotPoint", "AFXPANEFRAMEWND/CPaneFrameWnd::SetPreDockState", "AFXPANEFRAMEWND/CPaneFrameWnd::SizeToContent", "AFXPANEFRAMEWND/CPaneFrameWnd::StartTearOff", "AFXPANEFRAMEWND/CPaneFrameWnd::StoreRecentDockSiteInfo", "AFXPANEFRAMEWND/CPaneFrameWnd::StoreRecentTabRelatedInfo", "AFXPANEFRAMEWND/CPaneFrameWnd::OnCheckRollState", "AFXPANEFRAMEWND/CPaneFrameWnd::OnDrawBorder", "AFXPANEFRAMEWND/CPaneFrameWnd::m_bUseSaveBits"] helpviewer_keywords: ["CPaneFrameWnd [MFC], AddPane", "CPaneFrameWnd [MFC], AddRemovePaneFromGlobalList", "CPaneFrameWnd [MFC], AdjustLayout", "CPaneFrameWnd [MFC], AdjustPaneFrames", "CPaneFrameWnd [MFC], CalcBorderSize", "CPaneFrameWnd [MFC], CalcExpectedDockedRect", "CPaneFrameWnd [MFC], CanBeAttached", "CPaneFrameWnd [MFC], CanBeDockedToPane", "CPaneFrameWnd [MFC], CheckGripperVisibility", "CPaneFrameWnd [MFC], ConvertToTabbedDocument", "CPaneFrameWnd [MFC], Create", "CPaneFrameWnd [MFC], CreateEx", "CPaneFrameWnd [MFC], DockPane", "CPaneFrameWnd [MFC], FindFloatingPaneByID", "CPaneFrameWnd [MFC], FrameFromPoint", "CPaneFrameWnd [MFC], GetCaptionHeight", "CPaneFrameWnd [MFC], GetCaptionRect", "CPaneFrameWnd [MFC], GetCaptionText", "CPaneFrameWnd [MFC], GetDockingManager", "CPaneFrameWnd [MFC], GetDockingMode", "CPaneFrameWnd [MFC], GetFirstVisiblePane", "CPaneFrameWnd [MFC], GetHotPoint", "CPaneFrameWnd [MFC], GetPane", "CPaneFrameWnd [MFC], GetPaneCount", "CPaneFrameWnd [MFC], GetParent", "CPaneFrameWnd [MFC], GetPinState", "CPaneFrameWnd [MFC], GetRecentFloatingRect", "CPaneFrameWnd [MFC], GetVisiblePaneCount", "CPaneFrameWnd [MFC], HitTest", "CPaneFrameWnd [MFC], IsCaptured", "CPaneFrameWnd [MFC], IsDelayShow", "CPaneFrameWnd [MFC], IsRollDown", "CPaneFrameWnd [MFC], IsRollUp", "CPaneFrameWnd [MFC], KillDockingTimer", "CPaneFrameWnd [MFC], LoadState", "CPaneFrameWnd [MFC], OnBeforeDock", "CPaneFrameWnd [MFC], OnDockToRecentPos", "CPaneFrameWnd [MFC], OnKillRollUpTimer", "CPaneFrameWnd [MFC], OnMovePane", "CPaneFrameWnd [MFC], OnPaneRecalcLayout", "CPaneFrameWnd [MFC], OnSetRollUpTimer", "CPaneFrameWnd [MFC], OnShowPane", "CPaneFrameWnd [MFC], PaneFromPoint", "CPaneFrameWnd [MFC], Pin", "CPaneFrameWnd [MFC], RedrawAll", "CPaneFrameWnd [MFC], RemoveNonValidPanes", "CPaneFrameWnd [MFC], RemovePane", "CPaneFrameWnd [MFC], ReplacePane", "CPaneFrameWnd [MFC], SaveState", "CPaneFrameWnd [MFC], SetCaptionButtons", "CPaneFrameWnd [MFC], SetDelayShow", "CPaneFrameWnd [MFC], SetDockingManager", "CPaneFrameWnd [MFC], SetDockingTimer", "CPaneFrameWnd [MFC], SetDockState", "CPaneFrameWnd [MFC], SetHotPoint", "CPaneFrameWnd [MFC], SetPreDockState", "CPaneFrameWnd [MFC], SizeToContent", "CPaneFrameWnd [MFC], StartTearOff", "CPaneFrameWnd [MFC], StoreRecentDockSiteInfo", "CPaneFrameWnd [MFC], StoreRecentTabRelatedInfo", "CPaneFrameWnd [MFC], OnCheckRollState", "CPaneFrameWnd [MFC], OnDrawBorder", "CPaneFrameWnd [MFC], m_bUseSaveBits"] -ms.assetid: ea3423a3-2763-482e-b763-817036ded10d --- # CPaneFrameWnd Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. Implements a mini-frame window that contains one pane. The pane fills the client area of the window. diff --git a/docs/mfc/reference/cparabolictransitionfromacceleration-class.md b/docs/mfc/reference/cparabolictransitionfromacceleration-class.md index ec6569ac474..669010b4e3d 100644 --- a/docs/mfc/reference/cparabolictransitionfromacceleration-class.md +++ b/docs/mfc/reference/cparabolictransitionfromacceleration-class.md @@ -4,10 +4,12 @@ title: "CParabolicTransitionFromAcceleration Class" ms.date: "11/04/2016" f1_keywords: ["CParabolicTransitionFromAcceleration", "AFXANIMATIONCONTROLLER/CParabolicTransitionFromAcceleration", "AFXANIMATIONCONTROLLER/CParabolicTransitionFromAcceleration::CParabolicTransitionFromAcceleration", "AFXANIMATIONCONTROLLER/CParabolicTransitionFromAcceleration::Create", "AFXANIMATIONCONTROLLER/CParabolicTransitionFromAcceleration::m_dblAcceleration", "AFXANIMATIONCONTROLLER/CParabolicTransitionFromAcceleration::m_dblFinalValue", "AFXANIMATIONCONTROLLER/CParabolicTransitionFromAcceleration::m_dblFinalVelocity"] helpviewer_keywords: ["CParabolicTransitionFromAcceleration [MFC], CParabolicTransitionFromAcceleration", "CParabolicTransitionFromAcceleration [MFC], Create", "CParabolicTransitionFromAcceleration [MFC], m_dblAcceleration", "CParabolicTransitionFromAcceleration [MFC], m_dblFinalValue", "CParabolicTransitionFromAcceleration [MFC], m_dblFinalVelocity"] -ms.assetid: 1e59b86f-358b-4da0-a4fd-8eaf5e85e00f --- # CParabolicTransitionFromAcceleration Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a parabolic-acceleration transition. ## Syntax diff --git a/docs/mfc/reference/cpen-class.md b/docs/mfc/reference/cpen-class.md index 1eb6778ffdf..3dfc6ed53ac 100644 --- a/docs/mfc/reference/cpen-class.md +++ b/docs/mfc/reference/cpen-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CPen [MFC], CPen", "CPen [MFC], CreatePen", "CPen [MFC], --- # `CPen` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a Windows graphics device interface (GDI) pen. ## Syntax @@ -125,7 +128,7 @@ The second version of the `CPen` constructor specifies a combination of type, st *`nWidth`*\ Specifies the width of the pen. -- For the first version of the constructor, if this value is 0, the width in device units is always 1 pixel, regardless of the mapping mode. +- For the first version of the constructor, a value of 0 will be treated similarly to a value of 1, except that the width will not be affected by scale-transform operations that are in effect for the Graphics object that the pen is used for; the width will always be 1 pixel. - For the second version of the constructor, if *`nPenStyle`* is `PS_GEOMETRIC`, the width is given in logical units. If *`nPenStyle`* is `PS_COSMETIC`, the width must be set to 1. @@ -177,7 +180,7 @@ Specifies the style for the pen. For a list of possible values, see the *`nPenSt *`nWidth`*\ Specifies the width of the pen. -- For the first version of `CreatePen`, if this value is 0, the width in device units is always 1 pixel, regardless of the mapping mode. +- For the first version of `CreatePen`, a value of 0 will be treated similarly to a value of 1, except that the width will not be affected by scale-transform operations that are in effect for the Graphics object that the pen is used for; the width will always be 1 pixel. - For the second version of `CreatePen`, if *`nPenStyle`* is `PS_GEOMETRIC`, the width is given in logical units. If *`nPenStyle`* is `PS_COSMETIC`, the width must be set to 1. @@ -203,7 +206,7 @@ The first version of `CreatePen` initializes a pen with the specified style, wid Pens that have a width greater than 1 pixel should always have either the `PS_NULL`, `PS_SOLID`, or `PS_INSIDEFRAME` style. -If a pen has the `PS_INSIDEFRAME` style and a color that doesn't match a color in the logical color table, the pen is drawn with a dithered color. The `PS_SOLID` pen style can’t be used to create a pen with a dithered color. The style `PS_INSIDEFRAME` is identical to `PS_SOLID` if the pen width is less than or equal to 1. +If a pen has the `PS_INSIDEFRAME` style and a color that doesn't match a color in the logical color table, the pen is drawn with a dithered color. The `PS_SOLID` pen style can't be used to create a pen with a dithered color. The style `PS_INSIDEFRAME` is identical to `PS_SOLID` if the pen width is less than or equal to 1. The second version of `CreatePen` initializes a logical cosmetic or geometric pen that has the specified style, width, and brush attributes. The width of a cosmetic pen is always 1; the width of a geometric pen is always specified in world units. After an application creates a logical pen, it can select that pen into a device context by calling the [`CDC::SelectObject`](../../mfc/reference/cdc-class.md#selectobject) function. After a pen is selected into a device context, it can be used to draw lines and curves. diff --git a/docs/mfc/reference/cpictureholder-class.md b/docs/mfc/reference/cpictureholder-class.md index 27354c1940f..98e8a242e74 100644 --- a/docs/mfc/reference/cpictureholder-class.md +++ b/docs/mfc/reference/cpictureholder-class.md @@ -4,10 +4,12 @@ title: "CPictureHolder Class" ms.date: "11/04/2016" f1_keywords: ["CPictureHolder", "AFXCTL/CPictureHolder", "AFXCTL/CPictureHolder::CPictureHolder", "AFXCTL/CPictureHolder::CreateEmpty", "AFXCTL/CPictureHolder::CreateFromBitmap", "AFXCTL/CPictureHolder::CreateFromIcon", "AFXCTL/CPictureHolder::CreateFromMetafile", "AFXCTL/CPictureHolder::GetDisplayString", "AFXCTL/CPictureHolder::GetPictureDispatch", "AFXCTL/CPictureHolder::GetType", "AFXCTL/CPictureHolder::Render", "AFXCTL/CPictureHolder::SetPictureDispatch", "AFXCTL/CPictureHolder::m_pPict"] helpviewer_keywords: ["CPictureHolder [MFC], CPictureHolder", "CPictureHolder [MFC], CreateEmpty", "CPictureHolder [MFC], CreateFromBitmap", "CPictureHolder [MFC], CreateFromIcon", "CPictureHolder [MFC], CreateFromMetafile", "CPictureHolder [MFC], GetDisplayString", "CPictureHolder [MFC], GetPictureDispatch", "CPictureHolder [MFC], GetType", "CPictureHolder [MFC], Render", "CPictureHolder [MFC], SetPictureDispatch", "CPictureHolder [MFC], m_pPict"] -ms.assetid: a4f59775-704a-41dd-b5bd-2e531c95127a --- # CPictureHolder Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements a Picture property, which allows the user to display a picture in your control. ## Syntax diff --git a/docs/mfc/reference/cprintdialog-class.md b/docs/mfc/reference/cprintdialog-class.md index d4c03521ce6..093f0f5844a 100644 --- a/docs/mfc/reference/cprintdialog-class.md +++ b/docs/mfc/reference/cprintdialog-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CPrintDialog [MFC], CPrintDialog", "CPrintDialog [MFC], C --- # `CPrintDialog` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the services provided by the Windows common dialog box for printing. ## Syntax diff --git a/docs/mfc/reference/cprintdialogex-class.md b/docs/mfc/reference/cprintdialogex-class.md index 1a6cb91c882..dced4c2fffb 100644 --- a/docs/mfc/reference/cprintdialogex-class.md +++ b/docs/mfc/reference/cprintdialogex-class.md @@ -4,10 +4,12 @@ title: "CPrintDialogEx Class" ms.date: "11/04/2016" f1_keywords: ["CPrintDialogEx", "AFXDLGS/CPrintDialogEx", "AFXDLGS/CPrintDialogEx::CPrintDialogEx", "AFXDLGS/CPrintDialogEx::CreatePrinterDC", "AFXDLGS/CPrintDialogEx::DoModal", "AFXDLGS/CPrintDialogEx::GetCopies", "AFXDLGS/CPrintDialogEx::GetDefaults", "AFXDLGS/CPrintDialogEx::GetDeviceName", "AFXDLGS/CPrintDialogEx::GetDevMode", "AFXDLGS/CPrintDialogEx::GetDriverName", "AFXDLGS/CPrintDialogEx::GetPortName", "AFXDLGS/CPrintDialogEx::GetPrinterDC", "AFXDLGS/CPrintDialogEx::PrintAll", "AFXDLGS/CPrintDialogEx::PrintCollate", "AFXDLGS/CPrintDialogEx::PrintCurrentPage", "AFXDLGS/CPrintDialogEx::PrintRange", "AFXDLGS/CPrintDialogEx::PrintSelection", "AFXDLGS/CPrintDialogEx::m_pdex"] helpviewer_keywords: ["CPrintDialogEx [MFC], CPrintDialogEx", "CPrintDialogEx [MFC], CreatePrinterDC", "CPrintDialogEx [MFC], DoModal", "CPrintDialogEx [MFC], GetCopies", "CPrintDialogEx [MFC], GetDefaults", "CPrintDialogEx [MFC], GetDeviceName", "CPrintDialogEx [MFC], GetDevMode", "CPrintDialogEx [MFC], GetDriverName", "CPrintDialogEx [MFC], GetPortName", "CPrintDialogEx [MFC], GetPrinterDC", "CPrintDialogEx [MFC], PrintAll", "CPrintDialogEx [MFC], PrintCollate", "CPrintDialogEx [MFC], PrintCurrentPage", "CPrintDialogEx [MFC], PrintRange", "CPrintDialogEx [MFC], PrintSelection", "CPrintDialogEx [MFC], m_pdex"] -ms.assetid: 1d506703-ee1c-44cc-b4ce-4e778fec26b8 --- # CPrintDialogEx Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the services provided by the Windows Print property sheet. ## Syntax diff --git a/docs/mfc/reference/cprintinfo-structure.md b/docs/mfc/reference/cprintinfo-structure.md index 45508f935e3..988a7d8cb56 100644 --- a/docs/mfc/reference/cprintinfo-structure.md +++ b/docs/mfc/reference/cprintinfo-structure.md @@ -4,10 +4,12 @@ title: "CPrintInfo Structure" ms.date: "11/04/2016" f1_keywords: ["CPrintInfo"] helpviewer_keywords: ["CPrintInfo structure [MFC]"] -ms.assetid: 0b3de849-d050-4386-9a14-f4c1a25684f7 --- # CPrintInfo Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Stores information about a print or print-preview job. ## Syntax diff --git a/docs/mfc/reference/cprogressctrl-class.md b/docs/mfc/reference/cprogressctrl-class.md index d6eaee52925..7ae4d353fc7 100644 --- a/docs/mfc/reference/cprogressctrl-class.md +++ b/docs/mfc/reference/cprogressctrl-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CProgressCtrl [MFC], CProgressCtrl", "CProgressCtrl [MFC] --- # `CProgressCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common progress bar control. ## Syntax diff --git a/docs/mfc/reference/cpropertypage-class.md b/docs/mfc/reference/cpropertypage-class.md index 8b2c9507064..178080adc1f 100644 --- a/docs/mfc/reference/cpropertypage-class.md +++ b/docs/mfc/reference/cpropertypage-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CPropertyPage [MFC], CPropertyPage", "CPropertyPage [MFC] --- # `CPropertyPage` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents individual pages of a property sheet, otherwise known as a tab dialog box. ## Syntax @@ -83,7 +86,7 @@ void CancelToClose(); ### Remarks -This function will change the **OK** button to **Close** and disable the **Cancel** button. This change alerts the user that a change is permanent and the modifications can’t be canceled. +This function will change the **OK** button to **Close** and disable the **Cancel** button. This change alerts the user that a change is permanent and the modifications can't be canceled. The `CancelToClose` member function does nothing in a modeless property sheet, because a modeless property sheet doesn't have a **Cancel** button by default. @@ -194,7 +197,7 @@ ID of the name to be placed in the tab for this page. If 0, the name will be tak *`dwSize`*\ *`lpszTemplateName`* -Points to a string containing the name of the template for this page. Can’t be `NULL`. +Points to a string containing the name of the template for this page. Can't be `NULL`. *`nIDHeaderTitle`*\ ID of the name to be placed in the title location of the property page header. @@ -447,11 +450,11 @@ For more information on how to make a wizard-type property sheet, see [`CPropert ### Example [!code-cpp[NVC_MFCDocView#119](../../mfc/codesnippet/cpp/cpropertypage-class_9.cpp)] - +  [!code-cpp[NVC_MFCDocView#120](../../mfc/codesnippet/cpp/cpropertypage-class_10.cpp)] - +  [!code-cpp[NVC_MFCDocView#121](../../mfc/codesnippet/cpp/cpropertypage-class_11.cpp)] - +  [!code-cpp[NVC_MFCDocView#122](../../mfc/codesnippet/cpp/cpropertypage-class_12.cpp)] ## `CPropertyPage::OnWizardNext` @@ -505,9 +508,9 @@ If a page returns a nonzero value, the property sheet doesn't send the message t ### Example [!code-cpp[NVC_MFCDocView#124](../../mfc/codesnippet/cpp/cpropertypage-class_14.cpp)] - +  [!code-cpp[NVC_MFCDocView#125](../../mfc/codesnippet/cpp/cpropertypage-class_15.cpp)] - +  [!code-cpp[NVC_MFCDocView#126](../../mfc/codesnippet/cpp/cpropertypage-class_16.cpp)] ## `CPropertyPage::SetModified` diff --git a/docs/mfc/reference/cpropertysheet-class.md b/docs/mfc/reference/cpropertysheet-class.md index 0ab6b76fe9d..e383f0c4105 100644 --- a/docs/mfc/reference/cpropertysheet-class.md +++ b/docs/mfc/reference/cpropertysheet-class.md @@ -4,10 +4,12 @@ title: "CPropertySheet Class" ms.date: "11/04/2016" f1_keywords: ["CPropertySheet", "AFXDLGS/CPropertySheet", "AFXDLGS/CPropertySheet::CPropertySheet", "AFXDLGS/CPropertySheet::AddPage", "AFXDLGS/CPropertySheet::Construct", "AFXDLGS/CPropertySheet::Create", "AFXDLGS/CPropertySheet::DoModal", "AFXDLGS/CPropertySheet::EnableStackedTabs", "AFXDLGS/CPropertySheet::EndDialog", "AFXDLGS/CPropertySheet::GetActiveIndex", "AFXDLGS/CPropertySheet::GetActivePage", "AFXDLGS/CPropertySheet::GetPage", "AFXDLGS/CPropertySheet::GetPageCount", "AFXDLGS/CPropertySheet::GetPageIndex", "AFXDLGS/CPropertySheet::GetTabControl", "AFXDLGS/CPropertySheet::MapDialogRect", "AFXDLGS/CPropertySheet::OnInitDialog", "AFXDLGS/CPropertySheet::PressButton", "AFXDLGS/CPropertySheet::RemovePage", "AFXDLGS/CPropertySheet::SetActivePage", "AFXDLGS/CPropertySheet::SetFinishText", "AFXDLGS/CPropertySheet::SetTitle", "AFXDLGS/CPropertySheet::SetWizardButtons", "AFXDLGS/CPropertySheet::SetWizardMode", "AFXDLGS/CPropertySheet::m_psh"] helpviewer_keywords: ["CPropertySheet [MFC], CPropertySheet", "CPropertySheet [MFC], AddPage", "CPropertySheet [MFC], Construct", "CPropertySheet [MFC], Create", "CPropertySheet [MFC], DoModal", "CPropertySheet [MFC], EnableStackedTabs", "CPropertySheet [MFC], EndDialog", "CPropertySheet [MFC], GetActiveIndex", "CPropertySheet [MFC], GetActivePage", "CPropertySheet [MFC], GetPage", "CPropertySheet [MFC], GetPageCount", "CPropertySheet [MFC], GetPageIndex", "CPropertySheet [MFC], GetTabControl", "CPropertySheet [MFC], MapDialogRect", "CPropertySheet [MFC], OnInitDialog", "CPropertySheet [MFC], PressButton", "CPropertySheet [MFC], RemovePage", "CPropertySheet [MFC], SetActivePage", "CPropertySheet [MFC], SetFinishText", "CPropertySheet [MFC], SetTitle", "CPropertySheet [MFC], SetWizardButtons", "CPropertySheet [MFC], SetWizardMode", "CPropertySheet [MFC], m_psh"] -ms.assetid: 8461ccff-d14f-46e0-a746-42ad642ef94e --- # `CPropertySheet` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents property sheets, also known as tab dialog boxes. ## Syntax @@ -315,7 +317,7 @@ To display a modal property sheet, call [`DoModal`](#domodal) instead. ### Example [!code-cpp[NVC_MFCDocView#132](../../mfc/codesnippet/cpp/cpropertysheet-class_4.cpp)] - +  [!code-cpp[NVC_MFCDocView#133](../../mfc/codesnippet/cpp/cpropertysheet-class_5.cpp)] ## `CPropertySheet::DoModal` @@ -750,9 +752,9 @@ If you want to change the text on the Finish button or hide the Next and Back bu A `CPropertySheet` has three wizard property pages: `CStylePage`, `CColorPage`, and `CShapePage`. The code fragment below shows how to enable and disable the **Back** and **Next** buttons on the wizard property page. [!code-cpp[NVC_MFCDocView#140](../../mfc/codesnippet/cpp/cpropertysheet-class_13.cpp)] - +  [!code-cpp[NVC_MFCDocView#141](../../mfc/codesnippet/cpp/cpropertysheet-class_14.cpp)] - +  [!code-cpp[NVC_MFCDocView#138](../../mfc/codesnippet/cpp/cpropertysheet-class_11.cpp)] ## `CPropertySheet::SetWizardMode` diff --git a/docs/mfc/reference/cpropexchange-class.md b/docs/mfc/reference/cpropexchange-class.md index 4292d4b07dd..6af0cb17262 100644 --- a/docs/mfc/reference/cpropexchange-class.md +++ b/docs/mfc/reference/cpropexchange-class.md @@ -4,10 +4,12 @@ title: "CPropExchange Class" ms.date: "11/04/2016" f1_keywords: ["CPropExchange", "AFXCTL/CPropExchange", "AFXCTL/CPropExchange::ExchangeBlobProp", "AFXCTL/CPropExchange::ExchangeFontProp", "AFXCTL/CPropExchange::ExchangePersistentProp", "AFXCTL/CPropExchange::ExchangeProp", "AFXCTL/CPropExchange::ExchangeVersion", "AFXCTL/CPropExchange::GetVersion", "AFXCTL/CPropExchange::IsAsynchronous", "AFXCTL/CPropExchange::IsLoading"] helpviewer_keywords: ["CPropExchange [MFC], ExchangeBlobProp", "CPropExchange [MFC], ExchangeFontProp", "CPropExchange [MFC], ExchangePersistentProp", "CPropExchange [MFC], ExchangeProp", "CPropExchange [MFC], ExchangeVersion", "CPropExchange [MFC], GetVersion", "CPropExchange [MFC], IsAsynchronous", "CPropExchange [MFC], IsLoading"] -ms.assetid: ed872180-e770-4942-892a-92139d501fab --- # CPropExchange Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports the implementation of persistence for your OLE controls. ## Syntax diff --git a/docs/mfc/reference/cptrarray-class.md b/docs/mfc/reference/cptrarray-class.md index 74865d07bc0..d96c8b72602 100644 --- a/docs/mfc/reference/cptrarray-class.md +++ b/docs/mfc/reference/cptrarray-class.md @@ -4,10 +4,12 @@ title: "CPtrArray Class" ms.date: "11/04/2016" f1_keywords: ["CPtrArray", "AFXCOLL/CPtrArray", "AFXCOLL/CPtrArray::CPtrArray", "AFXCOLL/CPtrArray::Add", "AFXCOLL/CPtrArray::Append", "AFXCOLL/CPtrArray::Copy", "AFXCOLL/CPtrArray::ElementAt", "AFXCOLL/CPtrArray::FreeExtra", "AFXCOLL/CPtrArray::GetAt", "AFXCOLL/CPtrArray::GetCount", "AFXCOLL/CPtrArray::GetData", "AFXCOLL/CPtrArray::GetSize", "AFXCOLL/CPtrArray::GetUpperBound", "AFXCOLL/CPtrArray::InsertAt", "AFXCOLL/CPtrArray::IsEmpty", "AFXCOLL/CPtrArray::RemoveAll", "AFXCOLL/CPtrArray::RemoveAt", "AFXCOLL/CPtrArray::SetAt", "AFXCOLL/CPtrArray::SetAtGrow", "AFXCOLL/CPtrArray::SetSize"] helpviewer_keywords: ["CPtrArray [MFC], CPtrArray", "CPtrArray [MFC], Add", "CPtrArray [MFC], Append", "CPtrArray [MFC], Copy", "CPtrArray [MFC], ElementAt", "CPtrArray [MFC], FreeExtra", "CPtrArray [MFC], GetAt", "CPtrArray [MFC], GetCount", "CPtrArray [MFC], GetData", "CPtrArray [MFC], GetSize", "CPtrArray [MFC], GetUpperBound", "CPtrArray [MFC], InsertAt", "CPtrArray [MFC], IsEmpty", "CPtrArray [MFC], RemoveAll", "CPtrArray [MFC], RemoveAt", "CPtrArray [MFC], SetAt", "CPtrArray [MFC], SetAtGrow", "CPtrArray [MFC], SetSize"] -ms.assetid: c23b87a3-bf84-49d6-a66b-61e999d0938a --- # CPtrArray Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports arrays of void pointers. ## Syntax diff --git a/docs/mfc/reference/cptrlist-class.md b/docs/mfc/reference/cptrlist-class.md index 452efb1d46e..46437ca882e 100644 --- a/docs/mfc/reference/cptrlist-class.md +++ b/docs/mfc/reference/cptrlist-class.md @@ -4,10 +4,12 @@ title: "CPtrList Class" ms.date: "11/04/2016" f1_keywords: ["CPtrList"] helpviewer_keywords: ["lists, generic", "CPtrList class [MFC]", "generic lists"] -ms.assetid: 4139a09c-4338-4f42-9eea-51336120b43c --- # CPtrList Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports lists of void pointers. ## Syntax diff --git a/docs/mfc/reference/creating-a-file-explorer-style-mfc-application.md b/docs/mfc/reference/creating-a-file-explorer-style-mfc-application.md index 896201ac5fc..14dba910556 100644 --- a/docs/mfc/reference/creating-a-file-explorer-style-mfc-application.md +++ b/docs/mfc/reference/creating-a-file-explorer-style-mfc-application.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["browsers [MFC], Explorer-style applications", "MFC applic --- # Creating a File Explorer-Style MFC Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Many Windows system applications use the user interface (UI) for File Explorer. When you start File Explorer, for example, you see an application with a vertical splitter bar dividing the client area. The left side of the client area provides navigation and browsing features, and the right side of the client area shows details pertinent to the selection in the left pane. When a user clicks an item in the left pane, the application repopulates the right pane. In an MDI application, you can use commands on the **View** menu to change the amount of detail shown in the right pane. (In an SDI or multiple top-level document application, you can change the detail using the toolbar buttons only.) The contents of the panes depend on the application. In a file-system browser, the left pane shows a hierarchical view of directories or machines, or machine groups, while the right pane displays folders, individual files, or machines, and details about them. The contents don't necessarily have to be files. They could be e-mail messages, error reports, or other items in a database. diff --git a/docs/mfc/reference/creating-a-forms-based-mfc-application.md b/docs/mfc/reference/creating-a-forms-based-mfc-application.md index 9ef2409ba6b..0c5b3bef019 100644 --- a/docs/mfc/reference/creating-a-forms-based-mfc-application.md +++ b/docs/mfc/reference/creating-a-forms-based-mfc-application.md @@ -4,10 +4,12 @@ title: "Creating a Forms-Based MFC Application" ms.date: "09/09/2019" f1_keywords: ["vc.appwiz.mfcforms.project"] helpviewer_keywords: ["applications [MFC], forms-based", "forms-based applications [MFC]"] -ms.assetid: 048d2f7d-b60d-4386-ad8e-71d49af9c05e --- # Creating a Forms-Based MFC Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A form is a dialog box with controls that let a user access and possibly change data. You may want to develop an application in which the user selects from a selection of forms. Commonly, a forms-based application lets the user access forms by click **New** from the **File** menu. A dialog-based application, which does not give users access to a **New** option in the **File** menu, is also considered a forms-based application. A single document interface (SDI), forms-based application allows only one instance of a particular form to run at a time. It is possible to run different forms at the same time from an SDI forms-based application by selecting a new form from the **New** option in the **File** menu. @@ -24,7 +26,7 @@ The base class for form-based applications is [`CFormView`](cformview-class.md). Even if you use a base class such as [`CView`](cview-class.md), you can later make your applications forms-based by [adding an MFC class](adding-an-mfc-class.md) derived from `CFormView`. -Once you finish with the wizard, your project opens, and if you selected `CFormView` (or a class that inherits from `CFormView`) as your base class or if you created a dialog-based application, Visual C++ opens the dialog editor. At this point, you are ready to design your first form. +Once you finish with the wizard, your project opens, and if you selected `CFormView` (or a class that inherits from `CFormView`) as your base class or if you created a dialog-based application, Visual Studio opens the dialog editor. At this point, you are ready to design your first form. ### To begin creating a forms-based MFC executable diff --git a/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md b/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md index 40010ce0635..b955619f604 100644 --- a/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md +++ b/docs/mfc/reference/creating-a-web-browser-style-mfc-application.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["MFC, Web applications", "Web browsers, creating from MFC --- # Creating a Web Browser-Style MFC Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A Web browser-style application can access information from the Internet (such as HTML or active documents) or an intranet, as well as folders in the local file system and on a network. By deriving the application's view class from [`CHtmlView`](../../mfc/reference/chtmlview-class.md), effectively you make the application a Web browser by providing the view with the WebBrowser control. ## To create a Web browser application based on the MFC document/view architecture @@ -28,7 +31,7 @@ The WebBrowser control supports Web browsing through hyperlinks and Uniform Reso Because `CHtmlView` simply implements the Microsoft Web browser control, its support for printing isn't like other [`CView`](../../mfc/reference/cview-class.md)-derived classes. Rather, the WebBrowser control implements the printer user interface and printing. As a result, `CHtmlView` doesn't support print preview, and the framework doesn't provide for other printing support functions: for example, [`CView::OnPreparePrinting`](../../mfc/reference/cview-class.md#onprepareprinting), [`CView::OnBeginPrinting`](../../mfc/reference/cview-class.md#onbeginprinting), and [`CView::OnEndPrinting`](../../mfc/reference/cview-class.md#onendprinting), which are available in other MFC applications. -`CHtmlView` acts as a wrapper for the Web browser control, which gives your application a view onto a Web or an HTML page. The wizard creates an override to the [`OnInitialUpdate`](../../mfc/reference/cview-class.md#oninitialupdate) function in the view class, providing a navigational link to the Microsoft Visual C++ Web site: +`CHtmlView` acts as a wrapper for the Web browser control, which gives your application a view onto a Web or an HTML page. The wizard creates an override to the [`OnInitialUpdate`](../../mfc/reference/cview-class.md#oninitialupdate) function in the view class, providing a navigational link to the Visual Studio Web site: ```cpp void CWebView::OnInitialUpdate() @@ -37,7 +40,7 @@ void CWebView::OnInitialUpdate() // TODO: This code navigates to a popular spot on the web. // Change the code to go where you'd like. - Navigate2(_T("http://www.docs.microsoft.com/"), + Navigate2(_T("https://learn.microsoft.com/"), NULL, NULL); } diff --git a/docs/mfc/reference/creating-an-mfc-activex-control-container.md b/docs/mfc/reference/creating-an-mfc-activex-control-container.md index bf2998f393f..09e8ca13391 100644 --- a/docs/mfc/reference/creating-an-mfc-activex-control-container.md +++ b/docs/mfc/reference/creating-an-mfc-activex-control-container.md @@ -4,10 +4,12 @@ title: "Creating an MFC ActiveX Control Container" ms.date: "09/12/2018" f1_keywords: ["vc.appwiz.activex.container"] helpviewer_keywords: ["MFC ActiveX controls [MFC], containers", "ActiveX control containers [MFC], creating", "containers [MFC], creating", "OLE controls [MFC], containers"] -ms.assetid: ec70e137-7c14-4940-bd0e-fd4edcc63ea5 --- # Creating an MFC ActiveX Control Container +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An ActiveX control container is a parent program that supplies the environment for an ActiveX (formerly OLE) control to run. You can create an application capable of containing ActiveX controls with or without MFC, but it is much easier to do with MFC. >[!IMPORTANT] diff --git a/docs/mfc/reference/creating-an-mfc-activex-control.md b/docs/mfc/reference/creating-an-mfc-activex-control.md index af40e85640b..699fd44cc35 100644 --- a/docs/mfc/reference/creating-an-mfc-activex-control.md +++ b/docs/mfc/reference/creating-an-mfc-activex-control.md @@ -4,10 +4,12 @@ title: "Creating an MFC ActiveX Control" ms.date: "08/19/2019" f1_keywords: ["vc.appwiz.activex.project"] helpviewer_keywords: ["MFC ActiveX controls [MFC], creating", "ActiveX controls [MFC], creating"] -ms.assetid: 8bd5a93c-d04d-414e-bb28-163fdc1c0dd5 --- # Creating an MFC ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + ActiveX control programs are modular programs designed to give a specific type of functionality to a parent application. For example, you can create a control such as a button for use in a dialog, or toolbar for use in a Web page. >[!IMPORTANT] diff --git a/docs/mfc/reference/creating-an-mfc-application.md b/docs/mfc/reference/creating-an-mfc-application.md index eebadcf9497..5a7719ffafc 100644 --- a/docs/mfc/reference/creating-an-mfc-application.md +++ b/docs/mfc/reference/creating-an-mfc-application.md @@ -1,12 +1,14 @@ --- 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An MFC application is an executable application for Windows that is based on the Microsoft Foundation Class (MFC) Library. MFC executables generally fall into five types: standard Windows applications, dialog boxes, forms-based applications, Explorer-style applications, and Web browser-style applications. For more information, see: - [Using the Classes to Write Windows Applications](../../mfc/using-the-classes-to-write-applications-for-windows.md) @@ -32,35 +34,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 **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 +75,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 +96,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 +116,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/creating-an-mfc-dll-project.md b/docs/mfc/reference/creating-an-mfc-dll-project.md index 783d8204a23..0db9eb054b6 100644 --- a/docs/mfc/reference/creating-an-mfc-dll-project.md +++ b/docs/mfc/reference/creating-an-mfc-dll-project.md @@ -4,10 +4,12 @@ title: "Creating an MFC DLL Project" ms.date: "08/19/2019" f1_keywords: ["vc.appwiz.mfcdll.project"] helpviewer_keywords: ["MFC DLLs [MFC], creating projects", "DLLs [MFC], MFC", "projects [MFC], creating", "DLLs [MFC], creating"] -ms.assetid: 05540b93-4781-4a90-aadf-55158313f5b2 --- # Creating an MFC DLL Project +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An MFC DLL is a binary file that acts as a shared library of functions that can be used simultaneously by multiple applications. The easiest way to create an MFC DLL project is to use the MFC DLL Wizard. > [!NOTE] diff --git a/docs/mfc/reference/crebar-class.md b/docs/mfc/reference/crebar-class.md index 52ee6e4ec94..16cc85e331b 100644 --- a/docs/mfc/reference/crebar-class.md +++ b/docs/mfc/reference/crebar-class.md @@ -4,10 +4,12 @@ title: "CReBar Class" ms.date: "11/19/2018" f1_keywords: ["CReBar", "AFXEXT/CReBar", "AFXEXT/CReBar::AddBar", "AFXEXT/CReBar::Create", "AFXEXT/CReBar::GetReBarCtrl"] helpviewer_keywords: ["CReBar [MFC], AddBar", "CReBar [MFC], Create", "CReBar [MFC], GetReBarCtrl"] -ms.assetid: c1ad2720-1d33-4106-8e4e-80aa84f93559 --- # CReBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A control bar that provides layout, persistence, and state information for rebar controls. ## Syntax diff --git a/docs/mfc/reference/crebarctrl-class.md b/docs/mfc/reference/crebarctrl-class.md index 5dc690832f0..970ef6e7e42 100644 --- a/docs/mfc/reference/crebarctrl-class.md +++ b/docs/mfc/reference/crebarctrl-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the functionality of a rebar control, which is a container for a child window. ## Syntax @@ -337,7 +339,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/crecentdocksiteinfo-class.md b/docs/mfc/reference/crecentdocksiteinfo-class.md index 88bf440c502..2c9a20d7337 100644 --- a/docs/mfc/reference/crecentdocksiteinfo-class.md +++ b/docs/mfc/reference/crecentdocksiteinfo-class.md @@ -4,10 +4,12 @@ title: "CRecentDockSiteInfo Class" ms.date: "11/04/2016" f1_keywords: ["CRecentDockSiteInfo", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::CleanUp", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::GetRecentDefaultPaneDivider", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::GetRecentDockedPercent", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::GetRecentDockedRect", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::GetRecentListOfPanes", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::GetRecentPaneContainer", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::GetRecentTabContainer", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::Init", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::IsRecentLeftPane", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::SaveListOfRecentPanes", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::SetInfo", "AFXRECENTDOCKSITEINFO/CRecentDockSiteInfo::StoreDockInfo"] helpviewer_keywords: ["CRecentDockSiteInfo [MFC], CleanUp", "CRecentDockSiteInfo [MFC], GetRecentDefaultPaneDivider", "CRecentDockSiteInfo [MFC], GetRecentDockedPercent", "CRecentDockSiteInfo [MFC], GetRecentDockedRect", "CRecentDockSiteInfo [MFC], GetRecentListOfPanes", "CRecentDockSiteInfo [MFC], GetRecentPaneContainer", "CRecentDockSiteInfo [MFC], GetRecentTabContainer", "CRecentDockSiteInfo [MFC], Init", "CRecentDockSiteInfo [MFC], IsRecentLeftPane", "CRecentDockSiteInfo [MFC], SaveListOfRecentPanes", "CRecentDockSiteInfo [MFC], SetInfo", "CRecentDockSiteInfo [MFC], StoreDockInfo"] -ms.assetid: 2dd14f95-d5a2-4461-a7a5-2c6c36a3a165 --- # CRecentDockSiteInfo Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CRecentDockSiteInfo` class is a helper class that stores recent state information for the [CPane Class](../../mfc/reference/cpane-class.md). ## Syntax diff --git a/docs/mfc/reference/crecentfilelist-class.md b/docs/mfc/reference/crecentfilelist-class.md index d1254290dfa..01ada3f09c3 100644 --- a/docs/mfc/reference/crecentfilelist-class.md +++ b/docs/mfc/reference/crecentfilelist-class.md @@ -4,10 +4,12 @@ title: "CRecentFileList Class" ms.date: "11/04/2016" f1_keywords: ["CRecentFileList", "AFXADV/CRecentFileList", "AFXADV/CRecentFileList::CRecentFileList", "AFXADV/CRecentFileList::Add", "AFXADV/CRecentFileList::GetDisplayName", "AFXADV/CRecentFileList::GetSize", "AFXADV/CRecentFileList::ReadList", "AFXADV/CRecentFileList::Remove", "AFXADV/CRecentFileList::UpdateMenu", "AFXADV/CRecentFileList::WriteList"] helpviewer_keywords: ["CRecentFileList [MFC], CRecentFileList", "CRecentFileList [MFC], Add", "CRecentFileList [MFC], GetDisplayName", "CRecentFileList [MFC], GetSize", "CRecentFileList [MFC], ReadList", "CRecentFileList [MFC], Remove", "CRecentFileList [MFC], UpdateMenu", "CRecentFileList [MFC], WriteList"] -ms.assetid: a77f0524-7584-4582-849a-7e97b76d186e --- # CRecentFileList Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports control of the most recently used (MRU) file list. ## Syntax diff --git a/docs/mfc/reference/crecordset-class.md b/docs/mfc/reference/crecordset-class.md index 9265ac72794..4e04679a569 100644 --- a/docs/mfc/reference/crecordset-class.md +++ b/docs/mfc/reference/crecordset-class.md @@ -1,12 +1,15 @@ --- -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"] --- # `CRecordset` class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a set of records selected from a data source. ## Syntax @@ -205,7 +208,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` @@ -504,7 +507,7 @@ Your stored procedure needs to have bound fields if you want to call `FlushResul The following code assumes that `COutParamRecordset` is a `CRecordset`-derived object based on a predefined query with an input parameter and an output parameter, and having multiple result sets. Note the structure of the [`DoFieldExchange`](#dofieldexchange) override. [!code-cpp[NVC_MFCDatabase#21](../../mfc/codesnippet/cpp/crecordset-class_5.cpp)] - +  [!code-cpp[NVC_MFCDatabase#22](../../mfc/codesnippet/cpp/crecordset-class_6.cpp)] ## `CRecordset::GetBookmark` @@ -728,7 +731,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` @@ -1403,7 +1406,7 @@ Accept the default value, `AFX_DB_USE_DEFAULT_TYPE`, or use one of the following - `CRecordset::forwardOnly` A read-only recordset with only forward scrolling. - For `CRecordset`, the default value is `CRecordset::snapshot`. The default-value mechanism allows the Visual C++ wizards to interact with both ODBC `CRecordset` and DAO `CDaoRecordset`, which have different defaults. + For `CRecordset`, the default value is `CRecordset::snapshot`. The default-value mechanism allows the Visual Studio wizards to interact with both ODBC `CRecordset` and DAO `CDaoRecordset`, which have different defaults. For more information about these recordset types, see [Recordset (ODBC)](../../data/odbc/recordset-odbc.md). For related information, see "Using Block and Scrollable Cursors" in the Windows SDK. @@ -1474,7 +1477,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 +1627,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/crecordview-class.md b/docs/mfc/reference/crecordview-class.md index f4e471911b4..6fd8701e014 100644 --- a/docs/mfc/reference/crecordview-class.md +++ b/docs/mfc/reference/crecordview-class.md @@ -4,10 +4,12 @@ title: "CRecordView Class" ms.date: "11/04/2016" f1_keywords: ["CRecordView", "AFXDB/CRecordView", "AFXDB/CRecordView::CRecordView", "AFXDB/CRecordView::IsOnFirstRecord", "AFXDB/CRecordView::IsOnLastRecord", "AFXDB/CRecordView::OnGetRecordset", "AFXDB/CRecordView::OnMove"] helpviewer_keywords: ["CRecordView [MFC], CRecordView", "CRecordView [MFC], IsOnFirstRecord", "CRecordView [MFC], IsOnLastRecord", "CRecordView [MFC], OnGetRecordset", "CRecordView [MFC], OnMove", "CRecordView [MFC], OnMove"] -ms.assetid: 9b4b0897-bd50-4d48-a0b4-f3323f5ccc55 --- # CRecordView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A view that displays database records in controls. ## Syntax diff --git a/docs/mfc/reference/crecttracker-class.md b/docs/mfc/reference/crecttracker-class.md index 19a028ee9c3..5fe0fff5ac8 100644 --- a/docs/mfc/reference/crecttracker-class.md +++ b/docs/mfc/reference/crecttracker-class.md @@ -4,10 +4,12 @@ title: "CRectTracker Class" ms.date: "11/19/2018" f1_keywords: ["CRectTracker", "AFXEXT/CRectTracker", "AFXEXT/CRectTracker::CRectTracker", "AFXEXT/CRectTracker::AdjustRect", "AFXEXT/CRectTracker::Draw", "AFXEXT/CRectTracker::DrawTrackerRect", "AFXEXT/CRectTracker::GetHandleMask", "AFXEXT/CRectTracker::GetTrueRect", "AFXEXT/CRectTracker::HitTest", "AFXEXT/CRectTracker::NormalizeHit", "AFXEXT/CRectTracker::OnChangedRect", "AFXEXT/CRectTracker::SetCursor", "AFXEXT/CRectTracker::Track", "AFXEXT/CRectTracker::TrackRubberBand", "AFXEXT/CRectTracker::m_nHandleSize", "AFXEXT/CRectTracker::m_nStyle", "AFXEXT/CRectTracker::m_rect", "AFXEXT/CRectTracker::m_sizeMin"] helpviewer_keywords: ["CRectTracker [MFC], CRectTracker", "CRectTracker [MFC], AdjustRect", "CRectTracker [MFC], Draw", "CRectTracker [MFC], DrawTrackerRect", "CRectTracker [MFC], GetHandleMask", "CRectTracker [MFC], GetTrueRect", "CRectTracker [MFC], HitTest", "CRectTracker [MFC], NormalizeHit", "CRectTracker [MFC], OnChangedRect", "CRectTracker [MFC], SetCursor", "CRectTracker [MFC], Track", "CRectTracker [MFC], TrackRubberBand", "CRectTracker [MFC], m_nHandleSize", "CRectTracker [MFC], m_nStyle", "CRectTracker [MFC], m_rect", "CRectTracker [MFC], m_sizeMin"] -ms.assetid: 99caa7f2-3c0d-4a42-bbee-e5d1d342d4ee --- # CRectTracker Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Allows an item to be displayed, moved, and resized in different fashions. ## Syntax diff --git a/docs/mfc/reference/crendertarget-class.md b/docs/mfc/reference/crendertarget-class.md index 3c031ef53a6..c03c1adaece 100644 --- a/docs/mfc/reference/crendertarget-class.md +++ b/docs/mfc/reference/crendertarget-class.md @@ -4,10 +4,12 @@ title: "CRenderTarget Class" ms.date: "03/27/2019" f1_keywords: ["CRenderTarget", "AFXRENDERTARGET/CRenderTarget", "AFXRENDERTARGET/CRenderTarget::CRenderTarget", "AFXRENDERTARGET/CRenderTarget::Attach", "AFXRENDERTARGET/CRenderTarget::BeginDraw", "AFXRENDERTARGET/CRenderTarget::Clear", "AFXRENDERTARGET/CRenderTarget::COLORREF_TO_D2DCOLOR", "AFXRENDERTARGET/CRenderTarget::CreateCompatibleRenderTarget", "AFXRENDERTARGET/CRenderTarget::Destroy", "AFXRENDERTARGET/CRenderTarget::Detach", "AFXRENDERTARGET/CRenderTarget::DrawBitmap", "AFXRENDERTARGET/CRenderTarget::DrawEllipse", "AFXRENDERTARGET/CRenderTarget::DrawGeometry", "AFXRENDERTARGET/CRenderTarget::DrawGlyphRun", "AFXRENDERTARGET/CRenderTarget::DrawLine", "AFXRENDERTARGET/CRenderTarget::DrawRectangle", "AFXRENDERTARGET/CRenderTarget::DrawRoundedRectangle", "AFXRENDERTARGET/CRenderTarget::DrawText", "AFXRENDERTARGET/CRenderTarget::DrawTextLayout", "AFXRENDERTARGET/CRenderTarget::EndDraw", "AFXRENDERTARGET/CRenderTarget::FillEllipse", "AFXRENDERTARGET/CRenderTarget::FillGeometry", "AFXRENDERTARGET/CRenderTarget::FillMesh", "AFXRENDERTARGET/CRenderTarget::FillOpacityMask", "AFXRENDERTARGET/CRenderTarget::FillRectangle", "AFXRENDERTARGET/CRenderTarget::FillRoundedRectangle", "AFXRENDERTARGET/CRenderTarget::Flush", "AFXRENDERTARGET/CRenderTarget::GetAntialiasMode", "AFXRENDERTARGET/CRenderTarget::GetDpi", "AFXRENDERTARGET/CRenderTarget::GetMaximumBitmapSize", "AFXRENDERTARGET/CRenderTarget::GetPixelFormat", "AFXRENDERTARGET/CRenderTarget::GetPixelSize", "AFXRENDERTARGET/CRenderTarget::GetRenderTarget", "AFXRENDERTARGET/CRenderTarget::GetSize", "AFXRENDERTARGET/CRenderTarget::GetTags", "AFXRENDERTARGET/CRenderTarget::GetTextAntialiasMode", "AFXRENDERTARGET/CRenderTarget::GetTextRenderingParams", "AFXRENDERTARGET/CRenderTarget::GetTransform", "AFXRENDERTARGET/CRenderTarget::IsSupported", "AFXRENDERTARGET/CRenderTarget::IsValid", "AFXRENDERTARGET/CRenderTarget::PopAxisAlignedClip", "AFXRENDERTARGET/CRenderTarget::PopLayer", "AFXRENDERTARGET/CRenderTarget::PushAxisAlignedClip", "AFXRENDERTARGET/CRenderTarget::PushLayer", "AFXRENDERTARGET/CRenderTarget::RestoreDrawingState", "AFXRENDERTARGET/CRenderTarget::SaveDrawingState", "AFXRENDERTARGET/CRenderTarget::SetAntialiasMode", "AFXRENDERTARGET/CRenderTarget::SetDpi", "AFXRENDERTARGET/CRenderTarget::SetTags", "AFXRENDERTARGET/CRenderTarget::SetTextAntialiasMode", "AFXRENDERTARGET/CRenderTarget::SetTextRenderingParams", "AFXRENDERTARGET/CRenderTarget::SetTransform", "AFXRENDERTARGET/CRenderTarget::VerifyResource", "AFXRENDERTARGET/CRenderTarget::m_lstResources", "AFXRENDERTARGET/CRenderTarget::m_pRenderTarget", "AFXRENDERTARGET/CRenderTarget::m_pTextFormatDefault"] helpviewer_keywords: ["CRenderTarget [MFC], CRenderTarget", "CRenderTarget [MFC], Attach", "CRenderTarget [MFC], BeginDraw", "CRenderTarget [MFC], Clear", "CRenderTarget [MFC], COLORREF_TO_D2DCOLOR", "CRenderTarget [MFC], CreateCompatibleRenderTarget", "CRenderTarget [MFC], Destroy", "CRenderTarget [MFC], Detach", "CRenderTarget [MFC], DrawBitmap", "CRenderTarget [MFC], DrawEllipse", "CRenderTarget [MFC], DrawGeometry", "CRenderTarget [MFC], DrawGlyphRun", "CRenderTarget [MFC], DrawLine", "CRenderTarget [MFC], DrawRectangle", "CRenderTarget [MFC], DrawRoundedRectangle", "CRenderTarget [MFC], DrawText", "CRenderTarget [MFC], DrawTextLayout", "CRenderTarget [MFC], EndDraw", "CRenderTarget [MFC], FillEllipse", "CRenderTarget [MFC], FillGeometry", "CRenderTarget [MFC], FillMesh", "CRenderTarget [MFC], FillOpacityMask", "CRenderTarget [MFC], FillRectangle", "CRenderTarget [MFC], FillRoundedRectangle", "CRenderTarget [MFC], Flush", "CRenderTarget [MFC], GetAntialiasMode", "CRenderTarget [MFC], GetDpi", "CRenderTarget [MFC], GetMaximumBitmapSize", "CRenderTarget [MFC], GetPixelFormat", "CRenderTarget [MFC], GetPixelSize", "CRenderTarget [MFC], GetRenderTarget", "CRenderTarget [MFC], GetSize", "CRenderTarget [MFC], GetTags", "CRenderTarget [MFC], GetTextAntialiasMode", "CRenderTarget [MFC], GetTextRenderingParams", "CRenderTarget [MFC], GetTransform", "CRenderTarget [MFC], IsSupported", "CRenderTarget [MFC], IsValid", "CRenderTarget [MFC], PopAxisAlignedClip", "CRenderTarget [MFC], PopLayer", "CRenderTarget [MFC], PushAxisAlignedClip", "CRenderTarget [MFC], PushLayer", "CRenderTarget [MFC], RestoreDrawingState", "CRenderTarget [MFC], SaveDrawingState", "CRenderTarget [MFC], SetAntialiasMode", "CRenderTarget [MFC], SetDpi", "CRenderTarget [MFC], SetTags", "CRenderTarget [MFC], SetTextAntialiasMode", "CRenderTarget [MFC], SetTextRenderingParams", "CRenderTarget [MFC], SetTransform", "CRenderTarget [MFC], VerifyResource", "CRenderTarget [MFC], m_lstResources", "CRenderTarget [MFC], m_pRenderTarget", "CRenderTarget [MFC], m_pTextFormatDefault"] -ms.assetid: 30d1607d-68d3-4d14-ac36-fdbd0ef903a1 --- # CRenderTarget Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for ID2D1RenderTarget. ## Syntax diff --git a/docs/mfc/reference/cresourceexception-class.md b/docs/mfc/reference/cresourceexception-class.md index 2fb51f30a9f..7092e28d4cf 100644 --- a/docs/mfc/reference/cresourceexception-class.md +++ b/docs/mfc/reference/cresourceexception-class.md @@ -4,10 +4,12 @@ title: "CResourceException Class" ms.date: "11/04/2016" f1_keywords: ["CResourceException", "AFXWIN/CResourceException", "AFXWIN/CResourceException::CResourceException"] helpviewer_keywords: ["CResourceException [MFC], CResourceException"] -ms.assetid: af6ae043-d124-4bfd-b35e-7bb0db67d289 --- # CResourceException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Generated when Windows cannot find or allocate a requested resource. ## Syntax diff --git a/docs/mfc/reference/creversaltransition-class.md b/docs/mfc/reference/creversaltransition-class.md index ce0eea97765..a5d5fd66648 100644 --- a/docs/mfc/reference/creversaltransition-class.md +++ b/docs/mfc/reference/creversaltransition-class.md @@ -4,10 +4,12 @@ title: "CReversalTransition Class" ms.date: "11/04/2016" f1_keywords: ["CReversalTransition", "AFXANIMATIONCONTROLLER/CReversalTransition", "AFXANIMATIONCONTROLLER/CReversalTransition::CReversalTransition", "AFXANIMATIONCONTROLLER/CReversalTransition::Create", "AFXANIMATIONCONTROLLER/CReversalTransition::m_duration"] helpviewer_keywords: ["CReversalTransition [MFC], CReversalTransition", "CReversalTransition [MFC], Create", "CReversalTransition [MFC], m_duration"] -ms.assetid: e89516be-2d07-4885-95a8-fc278f46e3ad --- # CReversalTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a reversal transition. ## Syntax diff --git a/docs/mfc/reference/crgn-class.md b/docs/mfc/reference/crgn-class.md index 3e1cf67d0b7..3f188fbc505 100644 --- a/docs/mfc/reference/crgn-class.md +++ b/docs/mfc/reference/crgn-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a Windows graphics device interface (GDI) region. ## Syntax @@ -37,7 +39,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 +252,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*. @@ -610,17 +612,14 @@ int GetRgnBox(LPRECT lpRect) const; *lpRect*
Points to a `RECT` structure or `CRect` object to receive the coordinates of the bounding rectangle. The `RECT` structure has the following form: -`typedef struct tagRECT {` - -`int left;` - -`int top;` - -`int right;` - -`int bottom;` - -`} RECT;` +```cpp +typedef struct tagRECT { + int left; + int top; + int right; + int bottom; +} RECT; +``` ### Return Value diff --git a/docs/mfc/reference/cricheditcntritem-class.md b/docs/mfc/reference/cricheditcntritem-class.md index 54de9aee098..98ad504bdb2 100644 --- a/docs/mfc/reference/cricheditcntritem-class.md +++ b/docs/mfc/reference/cricheditcntritem-class.md @@ -4,10 +4,12 @@ title: "CRichEditCntrItem Class" ms.date: "11/04/2016" f1_keywords: ["CRichEditCntrItem", "AFXRICH/CRichEditCntrItem", "AFXRICH/CRichEditCntrItem::CRichEditCntrItem", "AFXRICH/CRichEditCntrItem::SyncToRichEditObject"] helpviewer_keywords: ["CRichEditCntrItem [MFC], CRichEditCntrItem", "CRichEditCntrItem [MFC], SyncToRichEditObject"] -ms.assetid: 6c0b4efe-0fb8-4621-b5e1-fdcb8ec48c3b --- # CRichEditCntrItem Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + With [CRichEditView](../../mfc/reference/cricheditview-class.md) and [CRichEditDoc](../../mfc/reference/cricheditdoc-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. ## Syntax diff --git a/docs/mfc/reference/cricheditctrl-class.md b/docs/mfc/reference/cricheditctrl-class.md index 21cda42093f..9a34e6cb057 100644 --- a/docs/mfc/reference/cricheditctrl-class.md +++ b/docs/mfc/reference/cricheditctrl-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CRichEditCtrl Class" title: "CRichEditCtrl Class" -ms.date: "11/04/2016" +description: "Learn more about: CRichEditCtrl Class" +ms.date: 11/04/2016 f1_keywords: ["CRichEditCtrl", "AFXCMN/CRichEditCtrl", "AFXCMN/CRichEditCtrl::CRichEditCtrl", "AFXCMN/CRichEditCtrl::CanPaste", "AFXCMN/CRichEditCtrl::CanRedo", "AFXCMN/CRichEditCtrl::CanUndo", "AFXCMN/CRichEditCtrl::CharFromPos", "AFXCMN/CRichEditCtrl::Clear", "AFXCMN/CRichEditCtrl::Copy", "AFXCMN/CRichEditCtrl::Create", "AFXCMN/CRichEditCtrl::CreateEx", "AFXCMN/CRichEditCtrl::Cut", "AFXCMN/CRichEditCtrl::DisplayBand", "AFXCMN/CRichEditCtrl::EmptyUndoBuffer", "AFXCMN/CRichEditCtrl::FindText", "AFXCMN/CRichEditCtrl::FindWordBreak", "AFXCMN/CRichEditCtrl::FormatRange", "AFXCMN/CRichEditCtrl::GetCharPos", "AFXCMN/CRichEditCtrl::GetDefaultCharFormat", "AFXCMN/CRichEditCtrl::GetEventMask", "AFXCMN/CRichEditCtrl::GetFirstVisibleLine", "AFXCMN/CRichEditCtrl::GetIRichEditOle", "AFXCMN/CRichEditCtrl::GetLimitText", "AFXCMN/CRichEditCtrl::GetLine", "AFXCMN/CRichEditCtrl::GetLineCount", "AFXCMN/CRichEditCtrl::GetModify", "AFXCMN/CRichEditCtrl::GetOptions", "AFXCMN/CRichEditCtrl::GetParaFormat", "AFXCMN/CRichEditCtrl::GetPunctuation", "AFXCMN/CRichEditCtrl::GetRect", "AFXCMN/CRichEditCtrl::GetRedoName", "AFXCMN/CRichEditCtrl::GetSel", "AFXCMN/CRichEditCtrl::GetSelectionCharFormat", "AFXCMN/CRichEditCtrl::GetSelectionType", "AFXCMN/CRichEditCtrl::GetSelText", "AFXCMN/CRichEditCtrl::GetTextLength", "AFXCMN/CRichEditCtrl::GetTextLengthEx", "AFXCMN/CRichEditCtrl::GetTextMode", "AFXCMN/CRichEditCtrl::GetTextRange", "AFXCMN/CRichEditCtrl::GetUndoName", "AFXCMN/CRichEditCtrl::GetWordWrapMode", "AFXCMN/CRichEditCtrl::HideSelection", "AFXCMN/CRichEditCtrl::LimitText", "AFXCMN/CRichEditCtrl::LineFromChar", "AFXCMN/CRichEditCtrl::LineIndex", "AFXCMN/CRichEditCtrl::LineLength", "AFXCMN/CRichEditCtrl::LineScroll", "AFXCMN/CRichEditCtrl::Paste", "AFXCMN/CRichEditCtrl::PasteSpecial", "AFXCMN/CRichEditCtrl::PosFromChar", "AFXCMN/CRichEditCtrl::Redo", "AFXCMN/CRichEditCtrl::ReplaceSel", "AFXCMN/CRichEditCtrl::RequestResize", "AFXCMN/CRichEditCtrl::SetAutoURLDetect", "AFXCMN/CRichEditCtrl::SetBackgroundColor", "AFXCMN/CRichEditCtrl::SetDefaultCharFormat", "AFXCMN/CRichEditCtrl::SetEventMask", "AFXCMN/CRichEditCtrl::SetModify", "AFXCMN/CRichEditCtrl::SetOLECallback", "AFXCMN/CRichEditCtrl::SetOptions", "AFXCMN/CRichEditCtrl::SetParaFormat", "AFXCMN/CRichEditCtrl::SetPunctuation", "AFXCMN/CRichEditCtrl::SetReadOnly", "AFXCMN/CRichEditCtrl::SetRect", "AFXCMN/CRichEditCtrl::SetSel", "AFXCMN/CRichEditCtrl::SetSelectionCharFormat", "AFXCMN/CRichEditCtrl::SetTargetDevice", "AFXCMN/CRichEditCtrl::SetTextMode", "AFXCMN/CRichEditCtrl::SetUndoLimit", "AFXCMN/CRichEditCtrl::SetWordCharFormat", "AFXCMN/CRichEditCtrl::SetWordWrapMode", "AFXCMN/CRichEditCtrl::StopGroupTyping", "AFXCMN/CRichEditCtrl::StreamIn", "AFXCMN/CRichEditCtrl::StreamOut", "AFXCMN/CRichEditCtrl::Undo"] helpviewer_keywords: ["CRichEditCtrl [MFC], CRichEditCtrl", "CRichEditCtrl [MFC], CanPaste", "CRichEditCtrl [MFC], CanRedo", "CRichEditCtrl [MFC], CanUndo", "CRichEditCtrl [MFC], CharFromPos", "CRichEditCtrl [MFC], Clear", "CRichEditCtrl [MFC], Copy", "CRichEditCtrl [MFC], Create", "CRichEditCtrl [MFC], CreateEx", "CRichEditCtrl [MFC], Cut", "CRichEditCtrl [MFC], DisplayBand", "CRichEditCtrl [MFC], EmptyUndoBuffer", "CRichEditCtrl [MFC], FindText", "CRichEditCtrl [MFC], FindWordBreak", "CRichEditCtrl [MFC], FormatRange", "CRichEditCtrl [MFC], GetCharPos", "CRichEditCtrl [MFC], GetDefaultCharFormat", "CRichEditCtrl [MFC], GetEventMask", "CRichEditCtrl [MFC], GetFirstVisibleLine", "CRichEditCtrl [MFC], GetIRichEditOle", "CRichEditCtrl [MFC], GetLimitText", "CRichEditCtrl [MFC], GetLine", "CRichEditCtrl [MFC], GetLineCount", "CRichEditCtrl [MFC], GetModify", "CRichEditCtrl [MFC], GetOptions", "CRichEditCtrl [MFC], GetParaFormat", "CRichEditCtrl [MFC], GetPunctuation", "CRichEditCtrl [MFC], GetRect", "CRichEditCtrl [MFC], GetRedoName", "CRichEditCtrl [MFC], GetSel", "CRichEditCtrl [MFC], GetSelectionCharFormat", "CRichEditCtrl [MFC], GetSelectionType", "CRichEditCtrl [MFC], GetSelText", "CRichEditCtrl [MFC], GetTextLength", "CRichEditCtrl [MFC], GetTextLengthEx", "CRichEditCtrl [MFC], GetTextMode", "CRichEditCtrl [MFC], GetTextRange", "CRichEditCtrl [MFC], GetUndoName", "CRichEditCtrl [MFC], GetWordWrapMode", "CRichEditCtrl [MFC], HideSelection", "CRichEditCtrl [MFC], LimitText", "CRichEditCtrl [MFC], LineFromChar", "CRichEditCtrl [MFC], LineIndex", "CRichEditCtrl [MFC], LineLength", "CRichEditCtrl [MFC], LineScroll", "CRichEditCtrl [MFC], Paste", "CRichEditCtrl [MFC], PasteSpecial", "CRichEditCtrl [MFC], PosFromChar", "CRichEditCtrl [MFC], Redo", "CRichEditCtrl [MFC], ReplaceSel", "CRichEditCtrl [MFC], RequestResize", "CRichEditCtrl [MFC], SetAutoURLDetect", "CRichEditCtrl [MFC], SetBackgroundColor", "CRichEditCtrl [MFC], SetDefaultCharFormat", "CRichEditCtrl [MFC], SetEventMask", "CRichEditCtrl [MFC], SetModify", "CRichEditCtrl [MFC], SetOLECallback", "CRichEditCtrl [MFC], SetOptions", "CRichEditCtrl [MFC], SetParaFormat", "CRichEditCtrl [MFC], SetPunctuation", "CRichEditCtrl [MFC], SetReadOnly", "CRichEditCtrl [MFC], SetRect", "CRichEditCtrl [MFC], SetSel", "CRichEditCtrl [MFC], SetSelectionCharFormat", "CRichEditCtrl [MFC], SetTargetDevice", "CRichEditCtrl [MFC], SetTextMode", "CRichEditCtrl [MFC], SetUndoLimit", "CRichEditCtrl [MFC], SetWordCharFormat", "CRichEditCtrl [MFC], SetWordWrapMode", "CRichEditCtrl [MFC], StopGroupTyping", "CRichEditCtrl [MFC], StreamIn", "CRichEditCtrl [MFC], StreamOut", "CRichEditCtrl [MFC], Undo"] -ms.assetid: 2be52788-822c-4c27-aafd-2471231e74eb --- # `CRichEditCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the rich edit control. ## Syntax @@ -553,7 +555,8 @@ For more information, see [`EM_POSFROMCHAR`](/windows/win32/Controls/em-posfromc Gets the default character formatting attributes of this `CRichEditCtrl` object. ``` -DWORD GetDefaultCharFormat(CHARFORMAT& cf) const; DWORD GetDefaultCharFormat(CHARFORMAT2& cf) const; +DWORD GetDefaultCharFormat(CHARFORMAT& cf) const; +DWORD GetDefaultCharFormat(CHARFORMAT2& cf) const; ``` ### Parameters @@ -759,7 +762,8 @@ A combination of the current option flag values. For a list of these values, see Gets the paragraph formatting attributes of the current selection. ``` -DWORD GetParaFormat(PARAFORMAT& pf) const; DWORD GetParaFormat(PARAFORMAT2& pf) const; +DWORD GetParaFormat(PARAFORMAT& pf) const; +DWORD GetParaFormat(PARAFORMAT2& pf) const; ``` ### Parameters @@ -892,7 +896,8 @@ For more information, see [`EM_EXGETSEL`](/windows/win32/Controls/em-exgetsel) m Gets the character formatting attributes of the current selection. ``` -DWORD GetSelectionCharFormat(CHARFORMAT& cf) const; DWORD GetSelectionCharFormat(CHARFORMAT2& cf) const; +DWORD GetSelectionCharFormat(CHARFORMAT& cf) const; +DWORD GetSelectionCharFormat(CHARFORMAT2& cf) const; ``` ### Parameters @@ -951,7 +956,8 @@ For more information, see [`EM_SELECTIONTYPE`](/windows/win32/Controls/em-select Retrieves the text from the current selection in this `CRichEditCtrl` object. ``` -long GetSelText(LPSTR lpBuf) const; CString GetSelText() const; +long GetSelText(LPSTR lpBuf) const; +CString GetSelText() const; ``` ### Parameters @@ -1195,7 +1201,7 @@ Contains the index value for the desired line in the text of the edit control, o ### Return Value -The character index of the line specified in *`nLine`* or -1 if the specified line number is greater then the number of lines in the edit control. +The character index of the line specified in *`nLine`* or -1 if the specified line number is greater than the number of lines in the edit control. ### Remarks @@ -1972,7 +1978,7 @@ For more information, see [`EM_STREAMIN`](/windows/win32/Controls/em-streamin) m ### Example [!code-cpp[NVC_MFC_CRichEditCtrl#34](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_34.cpp)] - +  [!code-cpp[NVC_MFC_CRichEditCtrl#35](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_35.cpp)] ## `CRichEditCtrl::StreamOut` @@ -2018,7 +2024,7 @@ For more information, see [`EM_STREAMOUT`](/windows/win32/Controls/em-streamout) ### Example [!code-cpp[NVC_MFC_CRichEditCtrl#36](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_36.cpp)] - +  [!code-cpp[NVC_MFC_CRichEditCtrl#37](../../mfc/reference/codesnippet/cpp/cricheditctrl-class_37.cpp)] ## `CRichEditCtrl::Undo` diff --git a/docs/mfc/reference/cricheditdoc-class.md b/docs/mfc/reference/cricheditdoc-class.md index 700f0691962..5dfa99a29a0 100644 --- a/docs/mfc/reference/cricheditdoc-class.md +++ b/docs/mfc/reference/cricheditdoc-class.md @@ -4,10 +4,12 @@ title: "CRichEditDoc Class" ms.date: "11/04/2016" f1_keywords: ["CRichEditDoc", "AFXRICH/CRichEditDoc", "AFXRICH/CRichEditDoc::CreateClientItem", "AFXRICH/CRichEditDoc::GetStreamFormat", "AFXRICH/CRichEditDoc::GetView", "AFXRICH/CRichEditDoc::m_bRTF"] helpviewer_keywords: ["CRichEditDoc [MFC], CreateClientItem", "CRichEditDoc [MFC], GetStreamFormat", "CRichEditDoc [MFC], GetView", "CRichEditDoc [MFC], m_bRTF"] -ms.assetid: c936ec18-d516-49d4-b7fb-c9aa0229eddc --- # CRichEditDoc Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + With [CRichEditView](../../mfc/reference/cricheditview-class.md) and [CRichEditCntrItem](../../mfc/reference/cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. ## Syntax @@ -24,7 +26,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/cricheditview-class.md b/docs/mfc/reference/cricheditview-class.md index 7cab1642800..23d301f4091 100644 --- a/docs/mfc/reference/cricheditview-class.md +++ b/docs/mfc/reference/cricheditview-class.md @@ -4,10 +4,12 @@ title: "CRichEditView Class" ms.date: "11/04/2016" f1_keywords: ["CRichEditView", "AFXRICH/CRichEditView", "AFXRICH/CRichEditView::CRichEditView", "AFXRICH/CRichEditView::AdjustDialogPosition", "AFXRICH/CRichEditView::CanPaste", "AFXRICH/CRichEditView::DoPaste", "AFXRICH/CRichEditView::FindText", "AFXRICH/CRichEditView::FindTextSimple", "AFXRICH/CRichEditView::GetCharFormatSelection", "AFXRICH/CRichEditView::GetDocument", "AFXRICH/CRichEditView::GetInPlaceActiveItem", "AFXRICH/CRichEditView::GetMargins", "AFXRICH/CRichEditView::GetPageRect", "AFXRICH/CRichEditView::GetPaperSize", "AFXRICH/CRichEditView::GetParaFormatSelection", "AFXRICH/CRichEditView::GetPrintRect", "AFXRICH/CRichEditView::GetPrintWidth", "AFXRICH/CRichEditView::GetRichEditCtrl", "AFXRICH/CRichEditView::GetSelectedItem", "AFXRICH/CRichEditView::GetTextLength", "AFXRICH/CRichEditView::GetTextLengthEx", "AFXRICH/CRichEditView::InsertFileAsObject", "AFXRICH/CRichEditView::InsertItem", "AFXRICH/CRichEditView::IsRichEditFormat", "AFXRICH/CRichEditView::OnCharEffect", "AFXRICH/CRichEditView::OnParaAlign", "AFXRICH/CRichEditView::OnUpdateCharEffect", "AFXRICH/CRichEditView::OnUpdateParaAlign", "AFXRICH/CRichEditView::PrintInsideRect", "AFXRICH/CRichEditView::PrintPage", "AFXRICH/CRichEditView::SetCharFormat", "AFXRICH/CRichEditView::SetMargins", "AFXRICH/CRichEditView::SetPaperSize", "AFXRICH/CRichEditView::SetParaFormat", "AFXRICH/CRichEditView::TextNotFound", "AFXRICH/CRichEditView::GetClipboardData", "AFXRICH/CRichEditView::GetContextMenu", "AFXRICH/CRichEditView::IsSelected", "AFXRICH/CRichEditView::OnFindNext", "AFXRICH/CRichEditView::OnInitialUpdate", "AFXRICH/CRichEditView::OnPasteNativeObject", "AFXRICH/CRichEditView::OnPrinterChanged", "AFXRICH/CRichEditView::OnReplaceAll", "AFXRICH/CRichEditView::OnReplaceSel", "AFXRICH/CRichEditView::OnTextNotFound", "AFXRICH/CRichEditView::QueryAcceptData", "AFXRICH/CRichEditView::WrapChanged", "AFXRICH/CRichEditView::m_nBulletIndent", "AFXRICH/CRichEditView::m_nWordWrap"] helpviewer_keywords: ["CRichEditView [MFC], CRichEditView", "CRichEditView [MFC], AdjustDialogPosition", "CRichEditView [MFC], CanPaste", "CRichEditView [MFC], DoPaste", "CRichEditView [MFC], FindText", "CRichEditView [MFC], FindTextSimple", "CRichEditView [MFC], GetCharFormatSelection", "CRichEditView [MFC], GetDocument", "CRichEditView [MFC], GetInPlaceActiveItem", "CRichEditView [MFC], GetMargins", "CRichEditView [MFC], GetPageRect", "CRichEditView [MFC], GetPaperSize", "CRichEditView [MFC], GetParaFormatSelection", "CRichEditView [MFC], GetPrintRect", "CRichEditView [MFC], GetPrintWidth", "CRichEditView [MFC], GetRichEditCtrl", "CRichEditView [MFC], GetSelectedItem", "CRichEditView [MFC], GetTextLength", "CRichEditView [MFC], GetTextLengthEx", "CRichEditView [MFC], InsertFileAsObject", "CRichEditView [MFC], InsertItem", "CRichEditView [MFC], IsRichEditFormat", "CRichEditView [MFC], OnCharEffect", "CRichEditView [MFC], OnParaAlign", "CRichEditView [MFC], OnUpdateCharEffect", "CRichEditView [MFC], OnUpdateParaAlign", "CRichEditView [MFC], PrintInsideRect", "CRichEditView [MFC], PrintPage", "CRichEditView [MFC], SetCharFormat", "CRichEditView [MFC], SetMargins", "CRichEditView [MFC], SetPaperSize", "CRichEditView [MFC], SetParaFormat", "CRichEditView [MFC], TextNotFound", "CRichEditView [MFC], GetClipboardData", "CRichEditView [MFC], GetContextMenu", "CRichEditView [MFC], IsSelected", "CRichEditView [MFC], OnFindNext", "CRichEditView [MFC], OnInitialUpdate", "CRichEditView [MFC], OnPasteNativeObject", "CRichEditView [MFC], OnPrinterChanged", "CRichEditView [MFC], OnReplaceAll", "CRichEditView [MFC], OnReplaceSel", "CRichEditView [MFC], OnTextNotFound", "CRichEditView [MFC], QueryAcceptData", "CRichEditView [MFC], WrapChanged", "CRichEditView [MFC], m_nBulletIndent", "CRichEditView [MFC], m_nWordWrap"] -ms.assetid: bd576b10-4cc0-4050-8f76-e1a0548411e4 --- # CRichEditView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + With [CRichEditDoc](../../mfc/reference/cricheditdoc-class.md) and [CRichEditCntrItem](../../mfc/reference/cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. ## Syntax diff --git a/docs/mfc/reference/cruntimeclass-structure.md b/docs/mfc/reference/cruntimeclass-structure.md index 6f396b5818b..c6772976abc 100644 --- a/docs/mfc/reference/cruntimeclass-structure.md +++ b/docs/mfc/reference/cruntimeclass-structure.md @@ -4,10 +4,12 @@ title: "CRuntimeClass Structure" ms.date: "11/04/2016" f1_keywords: ["CRuntimeClass"] helpviewer_keywords: ["CRuntimeClass structure [MFC]", "dynamic class information [MFC]", "runtime [MFC], class information", "run-time class [MFC], CRuntimeClass structure"] -ms.assetid: de62b6ef-90d4-420f-8c70-f58b36976a2b --- # CRuntimeClass Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Each class derived from `CObject` is associated with a `CRuntimeClass` structure that you can use to obtain information about an object or its base class at run time. ## Syntax diff --git a/docs/mfc/reference/cscrollbar-class.md b/docs/mfc/reference/cscrollbar-class.md index b5e379b5299..b489841cf9e 100644 --- a/docs/mfc/reference/cscrollbar-class.md +++ b/docs/mfc/reference/cscrollbar-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CScrollBar [MFC], CScrollBar", "CScrollBar [MFC], Create" --- # `CScrollBar` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows scroll-bar control. ## Syntax diff --git a/docs/mfc/reference/cscrollview-class.md b/docs/mfc/reference/cscrollview-class.md index 3cca28a8061..9103f4b0a7c 100644 --- a/docs/mfc/reference/cscrollview-class.md +++ b/docs/mfc/reference/cscrollview-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CScrollView [MFC], CScrollView", "CScrollView [MFC], Chec --- # `CScrollView` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A [`CView`](../../mfc/reference/cview-class.md) with scrolling capabilities. ## Syntax @@ -341,7 +344,7 @@ You must set the mapping mode to any of the Windows mapping modes except `MM_ISO ### Example [!code-cpp[NVC_MFCDocView#168](../../mfc/codesnippet/cpp/cscrollview-class_5.cpp)] - +  [!code-cpp[NVC_MFCDocView#169](../../mfc/codesnippet/cpp/cscrollview-class_6.cpp)] ## See also diff --git a/docs/mfc/reference/csemaphore-class.md b/docs/mfc/reference/csemaphore-class.md index fce78fae489..e2d61659cf4 100644 --- a/docs/mfc/reference/csemaphore-class.md +++ b/docs/mfc/reference/csemaphore-class.md @@ -4,15 +4,17 @@ 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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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 +24,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 +56,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 +66,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/csettingsstore-class.md b/docs/mfc/reference/csettingsstore-class.md index d54d021a525..cb4f6c83294 100644 --- a/docs/mfc/reference/csettingsstore-class.md +++ b/docs/mfc/reference/csettingsstore-class.md @@ -4,10 +4,12 @@ title: "CSettingsStore Class" ms.date: "11/04/2016" f1_keywords: ["CSettingsStore", "AFXSETTINGSSTORE/CSettingsStore", "AFXSETTINGSSTORE/CSettingsStore::CSettingsStore", "AFXSETTINGSSTORE/CSettingsStore::Close", "AFXSETTINGSSTORE/CSettingsStore::CreateKey", "AFXSETTINGSSTORE/CSettingsStore::DeleteKey", "AFXSETTINGSSTORE/CSettingsStore::DeleteValue", "AFXSETTINGSSTORE/CSettingsStore::Open", "AFXSETTINGSSTORE/CSettingsStore::Read", "AFXSETTINGSSTORE/CSettingsStore::Write"] helpviewer_keywords: ["CSettingsStore [MFC], CSettingsStore", "CSettingsStore [MFC], Close", "CSettingsStore [MFC], CreateKey", "CSettingsStore [MFC], DeleteKey", "CSettingsStore [MFC], DeleteValue", "CSettingsStore [MFC], Open", "CSettingsStore [MFC], Read", "CSettingsStore [MFC], Write"] -ms.assetid: 0ea181de-a13e-4b29-b560-7c43838223ff --- # CSettingsStore Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Wraps Windows API functions, providing an object-oriented interface that you use to access the registry. ## Syntax diff --git a/docs/mfc/reference/csettingsstoresp-class.md b/docs/mfc/reference/csettingsstoresp-class.md index 460f1d63a96..aeede5a5af0 100644 --- a/docs/mfc/reference/csettingsstoresp-class.md +++ b/docs/mfc/reference/csettingsstoresp-class.md @@ -4,10 +4,12 @@ title: "CSettingsStoreSP Class" ms.date: "11/04/2016" f1_keywords: ["CSettingsStoreSP", "AFXSETTINGSSTORE/CSettingsStoreSP", "AFXSETTINGSSTORE/CSettingsStoreSP::CSettingsStoreSP", "AFXSETTINGSSTORE/CSettingsStoreSP::Create", "AFXSETTINGSSTORE/CSettingsStoreSP::SetRuntimeClass"] helpviewer_keywords: ["CSettingsStoreSP [MFC], CSettingsStoreSP", "CSettingsStoreSP [MFC], Create", "CSettingsStoreSP [MFC], SetRuntimeClass"] -ms.assetid: bcd37f40-cfd4-4d17-a5ce-3bfabe995dcc --- # CSettingsStoreSP Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CSettingsStoreSP` class is a helper class that you can use to create instances of the [CSettingsStore Class](../../mfc/reference/csettingsstore-class.md). ## Syntax diff --git a/docs/mfc/reference/csharedfile-class.md b/docs/mfc/reference/csharedfile-class.md index 9b41513705b..f337246813d 100644 --- a/docs/mfc/reference/csharedfile-class.md +++ b/docs/mfc/reference/csharedfile-class.md @@ -4,10 +4,12 @@ title: "CSharedFile Class" ms.date: "11/04/2016" f1_keywords: ["CSharedFile", "AFXADV/CSharedFile", "AFXADV/CSharedFile::CSharedFile", "AFXADV/CSharedFile::Detach", "AFXADV/CSharedFile::SetHandle"] helpviewer_keywords: ["CSharedFile [MFC], CSharedFile", "CSharedFile [MFC], Detach", "CSharedFile [MFC], SetHandle"] -ms.assetid: 5d000422-9ede-4318-a8c9-f7412b674f39 --- # CSharedFile Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CMemFile](../../mfc/reference/cmemfile-class.md)-derived class that supports shared memory files. ## Syntax diff --git a/docs/mfc/reference/cshellmanager-class.md b/docs/mfc/reference/cshellmanager-class.md index 83bc1cbf6f1..3a4b20fb72a 100644 --- a/docs/mfc/reference/cshellmanager-class.md +++ b/docs/mfc/reference/cshellmanager-class.md @@ -4,10 +4,12 @@ title: "CShellManager Class" ms.date: "11/04/2016" f1_keywords: ["CShellManager", "AFXSHELLMANAGER/CShellManager", "AFXSHELLMANAGER/CShellManager::CShellManager", "AFXSHELLMANAGER/CShellManager::BrowseForFolder", "AFXSHELLMANAGER/CShellManager::ConcatenateItem", "AFXSHELLMANAGER/CShellManager::CopyItem", "AFXSHELLMANAGER/CShellManager::CreateItem", "AFXSHELLMANAGER/CShellManager::FreeItem", "AFXSHELLMANAGER/CShellManager::GetItemCount", "AFXSHELLMANAGER/CShellManager::GetItemSize", "AFXSHELLMANAGER/CShellManager::GetNextItem", "AFXSHELLMANAGER/CShellManager::GetParentItem", "AFXSHELLMANAGER/CShellManager::ItemFromPath"] helpviewer_keywords: ["CShellManager [MFC], CShellManager", "CShellManager [MFC], BrowseForFolder", "CShellManager [MFC], ConcatenateItem", "CShellManager [MFC], CopyItem", "CShellManager [MFC], CreateItem", "CShellManager [MFC], FreeItem", "CShellManager [MFC], GetItemCount", "CShellManager [MFC], GetItemSize", "CShellManager [MFC], GetNextItem", "CShellManager [MFC], GetParentItem", "CShellManager [MFC], ItemFromPath"] -ms.assetid: f15c4c1a-6fae-487d-9913-9b7369b33da0 --- # CShellManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements several methods that enable you to work with pointers to identifier lists (PIDLs). ## Syntax diff --git a/docs/mfc/reference/csimpleexception-class.md b/docs/mfc/reference/csimpleexception-class.md index 177145f514b..3e53ac0ac49 100644 --- a/docs/mfc/reference/csimpleexception-class.md +++ b/docs/mfc/reference/csimpleexception-class.md @@ -4,10 +4,12 @@ title: "CSimpleException Class" ms.date: "11/04/2016" f1_keywords: ["CSimpleException", "AFX/CSimpleException", "AFX/CSimpleException::CSimpleException", "AFX/CSimpleException::GetErrorMessage"] helpviewer_keywords: ["CSimpleException [MFC], CSimpleException", "CSimpleException [MFC], GetErrorMessage"] -ms.assetid: be0eb8ef-e5b9-47d6-b0fb-efaff2d1e666 --- # CSimpleException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This class is a base class for resource-critical MFC exceptions. ## Syntax diff --git a/docs/mfc/reference/csingledoctemplate-class.md b/docs/mfc/reference/csingledoctemplate-class.md index a8ad3922e2c..91c62bd2ca8 100644 --- a/docs/mfc/reference/csingledoctemplate-class.md +++ b/docs/mfc/reference/csingledoctemplate-class.md @@ -4,10 +4,12 @@ title: "CSingleDocTemplate Class" ms.date: "11/04/2016" f1_keywords: ["CSingleDocTemplate", "AFXWIN/CSingleDocTemplate", "AFXWIN/CSingleDocTemplate::CSingleDocTemplate"] helpviewer_keywords: ["CSingleDocTemplate [MFC], CSingleDocTemplate"] -ms.assetid: 4f3a8212-81ee-48a0-ad22-e0ed7c36a391 --- # CSingleDocTemplate Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Defines a document template that implements the single document interface (SDI). ## Syntax @@ -103,7 +105,7 @@ Dynamically allocate a `CSingleDocTemplate` object and pass it to `CWinApp::AddD ### Example [!code-cpp[NVC_MFCDocViewSDI#13](../../mfc/codesnippet/cpp/csingledoctemplate-class_1.cpp)] - +  [!code-cpp[NVC_MFCDocViewSDI#14](../../mfc/codesnippet/cpp/csingledoctemplate-class_2.cpp)] ## See also diff --git a/docs/mfc/reference/csinglelock-class.md b/docs/mfc/reference/csinglelock-class.md index fd33502e814..514ffb67131 100644 --- a/docs/mfc/reference/csinglelock-class.md +++ b/docs/mfc/reference/csinglelock-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CSingleLock [MFC], CSingleLock", "CSingleLock [MFC], IsLo --- # `CSingleLock` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents the access-control mechanism used in controlling access to a resource in a multithreaded program. ## Syntax @@ -62,7 +65,7 @@ explicit CSingleLock( ### Parameters *`pObject`*\ -Points to the synchronization object to be accessed. Can’t be `NULL`. +Points to the synchronization object to be accessed. Can't be `NULL`. *`bInitialLock`*\ Specifies whether to initially attempt to access the supplied object. diff --git a/docs/mfc/reference/csinusoidaltransitionfromrange-class.md b/docs/mfc/reference/csinusoidaltransitionfromrange-class.md index 71e765f9e7a..0781edb9065 100644 --- a/docs/mfc/reference/csinusoidaltransitionfromrange-class.md +++ b/docs/mfc/reference/csinusoidaltransitionfromrange-class.md @@ -4,10 +4,12 @@ title: "CSinusoidalTransitionFromRange Class" ms.date: "11/04/2016" f1_keywords: ["CSinusoidalTransitionFromRange", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange::CSinusoidalTransitionFromRange", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange::Create", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange::m_dblMaximumValue", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange::m_dblMinimumValue", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange::m_duration", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange::m_period", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromRange::m_slope"] helpviewer_keywords: ["CSinusoidalTransitionFromRange [MFC], CSinusoidalTransitionFromRange", "CSinusoidalTransitionFromRange [MFC], Create", "CSinusoidalTransitionFromRange [MFC], m_dblMaximumValue", "CSinusoidalTransitionFromRange [MFC], m_dblMinimumValue", "CSinusoidalTransitionFromRange [MFC], m_duration", "CSinusoidalTransitionFromRange [MFC], m_period", "CSinusoidalTransitionFromRange [MFC], m_slope"] -ms.assetid: 8b66a729-5f10-431a-b055-e3600d0065da --- # CSinusoidalTransitionFromRange Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a sinusoidal-range transition that has a given range of oscillation. ## Syntax diff --git a/docs/mfc/reference/csinusoidaltransitionfromvelocity-class.md b/docs/mfc/reference/csinusoidaltransitionfromvelocity-class.md index 5340dcf776b..035fcb9bc5f 100644 --- a/docs/mfc/reference/csinusoidaltransitionfromvelocity-class.md +++ b/docs/mfc/reference/csinusoidaltransitionfromvelocity-class.md @@ -4,10 +4,12 @@ title: "CSinusoidalTransitionFromVelocity Class" ms.date: "11/04/2016" f1_keywords: ["CSinusoidalTransitionFromVelocity", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromVelocity", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromVelocity::CSinusoidalTransitionFromVelocity", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromVelocity::Create", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromVelocity::m_duration", "AFXANIMATIONCONTROLLER/CSinusoidalTransitionFromVelocity::m_period"] helpviewer_keywords: ["CSinusoidalTransitionFromVelocity [MFC], CSinusoidalTransitionFromVelocity", "CSinusoidalTransitionFromVelocity [MFC], Create", "CSinusoidalTransitionFromVelocity [MFC], m_duration", "CSinusoidalTransitionFromVelocity [MFC], m_period"] -ms.assetid: cc885f17-b84b-45ee-8f1f-36a8bbb7adad --- # CSinusoidalTransitionFromVelocity Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a sinusoidal-velocity transition that has an amplitude that is determined by the initial velocity of the animation variable. ## Syntax diff --git a/docs/mfc/reference/csliderctrl-class.md b/docs/mfc/reference/csliderctrl-class.md index 28afb9140de..2618ebf579c 100644 --- a/docs/mfc/reference/csliderctrl-class.md +++ b/docs/mfc/reference/csliderctrl-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CSliderCtrl [MFC], CSliderCtrl", "CSliderCtrl [MFC], Clea --- # `CSliderCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common slider control. ## Syntax diff --git a/docs/mfc/reference/csmartdockinginfo-class.md b/docs/mfc/reference/csmartdockinginfo-class.md index d7944553b9c..eb889a8c47a 100644 --- a/docs/mfc/reference/csmartdockinginfo-class.md +++ b/docs/mfc/reference/csmartdockinginfo-class.md @@ -4,10 +4,12 @@ title: "CSmartDockingInfo Class" ms.date: "11/19/2018" f1_keywords: ["CSmartDockingInfo", "AFXDOCKINGMANAGER/CSmartDockingInfo", "AFXDOCKINGMANAGER/CSmartDockingInfo::CopyTo", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_bUseThemeColorInShading", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_clrBaseBackground", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_clrToneDest", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_clrToneSrc", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_clrTransparent", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_nCentralGroupOffset", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_sizeTotal", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_uiMarkerBmpResID", "AFXDOCKINGMANAGER/CSmartDockingInfo::m_uiMarkerLightBmpResID"] helpviewer_keywords: ["CSmartDockingInfo [MFC], CopyTo", "CSmartDockingInfo [MFC], m_bUseThemeColorInShading", "CSmartDockingInfo [MFC], m_clrBaseBackground", "CSmartDockingInfo [MFC], m_clrToneDest", "CSmartDockingInfo [MFC], m_clrToneSrc", "CSmartDockingInfo [MFC], m_clrTransparent", "CSmartDockingInfo [MFC], m_nCentralGroupOffset", "CSmartDockingInfo [MFC], m_sizeTotal", "CSmartDockingInfo [MFC], m_uiMarkerBmpResID", "CSmartDockingInfo [MFC], m_uiMarkerLightBmpResID"] -ms.assetid: cab04f38-4bc1-4378-9337-c56fc87fbd68 --- # CSmartDockingInfo Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Defines the appearance of smart docking markers. ## Syntax diff --git a/docs/mfc/reference/csmoothstoptransition-class.md b/docs/mfc/reference/csmoothstoptransition-class.md index 039271bcb5e..9d7b0d6b78f 100644 --- a/docs/mfc/reference/csmoothstoptransition-class.md +++ b/docs/mfc/reference/csmoothstoptransition-class.md @@ -4,10 +4,12 @@ title: "CSmoothStopTransition Class" ms.date: "11/04/2016" f1_keywords: ["CSmoothStopTransition", "AFXANIMATIONCONTROLLER/CSmoothStopTransition", "AFXANIMATIONCONTROLLER/CSmoothStopTransition::CSmoothStopTransition", "AFXANIMATIONCONTROLLER/CSmoothStopTransition::Create", "AFXANIMATIONCONTROLLER/CSmoothStopTransition::m_dblFinalValue", "AFXANIMATIONCONTROLLER/CSmoothStopTransition::m_maximumDuration"] helpviewer_keywords: ["CSmoothStopTransition [MFC], CSmoothStopTransition", "CSmoothStopTransition [MFC], Create", "CSmoothStopTransition [MFC], m_dblFinalValue", "CSmoothStopTransition [MFC], m_maximumDuration"] -ms.assetid: e1a4b476-6f96-43dd-90db-870a64406b85 --- # CSmoothStopTransition Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates a smooth-stop transition. ## Syntax diff --git a/docs/mfc/reference/csocket-class.md b/docs/mfc/reference/csocket-class.md index 437001deb40..d317b7cced5 100644 --- a/docs/mfc/reference/csocket-class.md +++ b/docs/mfc/reference/csocket-class.md @@ -4,10 +4,12 @@ title: "CSocket Class" ms.date: "11/04/2016" f1_keywords: ["CSocket", "AFXSOCK/CSocket", "AFXSOCK/CSocket::CSocket", "AFXSOCK/CSocket::Attach", "AFXSOCK/CSocket::CancelBlockingCall", "AFXSOCK/CSocket::Create", "AFXSOCK/CSocket::FromHandle", "AFXSOCK/CSocket::IsBlocking", "AFXSOCK/CSocket::OnMessagePending"] helpviewer_keywords: ["CSocket [MFC], CSocket", "CSocket [MFC], Attach", "CSocket [MFC], CancelBlockingCall", "CSocket [MFC], Create", "CSocket [MFC], FromHandle", "CSocket [MFC], IsBlocking", "CSocket [MFC], OnMessagePending"] -ms.assetid: 7f23c081-d24d-42e3-b511-8053ca53d729 --- # `CSocket` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Derives from `CAsyncSocket`, inherits its encapsulation of the Windows Sockets API, and represents a higher level of abstraction than that of a `CAsyncSocket` object. ## Syntax @@ -99,9 +101,9 @@ For more information, see [Windows Sockets: Using Sockets with Archives](../../m ### Example [!code-cpp[NVC_MFCSocketThread#1](../../mfc/reference/codesnippet/cpp/csocket-class_2.h)] - +  [!code-cpp[NVC_MFCSocketThread#2](../../mfc/reference/codesnippet/cpp/csocket-class_3.cpp)] - +  [!code-cpp[NVC_MFCSocketThread#3](../../mfc/reference/codesnippet/cpp/csocket-class_4.cpp)] ## `CSocket::CancelBlockingCall` diff --git a/docs/mfc/reference/csocketfile-class.md b/docs/mfc/reference/csocketfile-class.md index 5a6596fbcf7..77c50de870a 100644 --- a/docs/mfc/reference/csocketfile-class.md +++ b/docs/mfc/reference/csocketfile-class.md @@ -4,10 +4,12 @@ title: "CSocketFile Class" ms.date: "11/04/2016" f1_keywords: ["CSocketFile", "AFXSOCK/CSocketFile", "AFXSOCK/CSocketFile::CSocketFile"] helpviewer_keywords: ["CSocketFile [MFC], CSocketFile"] -ms.assetid: 7924c098-5f72-40d6-989d-42800a47958f --- # CSocketFile Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A `CFile` object used for sending and receiving data across a network via Windows Sockets. ## Syntax diff --git a/docs/mfc/reference/cspinbuttonctrl-class.md b/docs/mfc/reference/cspinbuttonctrl-class.md index b9e1628b644..35a334b4672 100644 --- a/docs/mfc/reference/cspinbuttonctrl-class.md +++ b/docs/mfc/reference/cspinbuttonctrl-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CSpinButtonCtrl Class" title: "CSpinButtonCtrl Class" -ms.date: "11/04/2016" +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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common spin button control. ## Syntax @@ -71,7 +73,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( @@ -202,7 +204,8 @@ A pointer to the current buddy window. Retrieves the current position of a spin button control. ``` -int GetPos() const; int GetPos32(LPBOOL lpbError = NULL) const; +int GetPos() const; +int GetPos32(LPBOOL lpbError = NULL) const; ``` ### Parameters @@ -366,7 +369,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/csplitbutton-class.md b/docs/mfc/reference/csplitbutton-class.md index 1e57c08c497..e946d578adf 100644 --- a/docs/mfc/reference/csplitbutton-class.md +++ b/docs/mfc/reference/csplitbutton-class.md @@ -4,10 +4,12 @@ title: "CSplitButton Class" ms.date: "11/19/2018" f1_keywords: ["CSplitButton", "AFXCMN/CSplitButton", "AFXCMN/CSplitButton::CSplitButton", "AFXCMN/CSplitButton::Create", "AFXCMN/CSplitButton::SetDropDownMenu", "AFXCMN/CSplitButton::OnDropDown"] helpviewer_keywords: ["CSplitButton [MFC], CSplitButton", "CSplitButton [MFC], Create", "CSplitButton [MFC], SetDropDownMenu", "CSplitButton [MFC], OnDropDown"] -ms.assetid: 6844d0a9-6408-4e44-9b5f-57628ed8bad6 --- # CSplitButton Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CSplitButton` class 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. ## Syntax diff --git a/docs/mfc/reference/csplitterwnd-class.md b/docs/mfc/reference/csplitterwnd-class.md index da72f6e13bb..f84ab903751 100644 --- a/docs/mfc/reference/csplitterwnd-class.md +++ b/docs/mfc/reference/csplitterwnd-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CSplitterWnd [MFC], CSplitterWnd", "CSplitterWnd [MFC], A --- # `CSplitterWnd` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a splitter window, which is a window that contains multiple panes. ## Syntax diff --git a/docs/mfc/reference/csplitterwndex-class.md b/docs/mfc/reference/csplitterwndex-class.md index 58ba5c4a4b3..187fb96b481 100644 --- a/docs/mfc/reference/csplitterwndex-class.md +++ b/docs/mfc/reference/csplitterwndex-class.md @@ -4,10 +4,12 @@ title: "CSplitterWndEx Class" ms.date: "11/04/2016" f1_keywords: ["CSplitterWndEx", "AFXSPLITTERWNDEX/CSplitterWndEx", "AFXSPLITTERWNDEX/CSplitterWndEx::OnDrawSplitter"] helpviewer_keywords: ["CSplitterWndEx [MFC], OnDrawSplitter"] -ms.assetid: 33e5eef3-05e1-4a07-a968-bf9207ce8598 --- # CSplitterWndEx Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a customized splitter window. ## Syntax diff --git a/docs/mfc/reference/cstatic-class.md b/docs/mfc/reference/cstatic-class.md index bce8cd9cc13..00eb9afd387 100644 --- a/docs/mfc/reference/cstatic-class.md +++ b/docs/mfc/reference/cstatic-class.md @@ -4,10 +4,12 @@ title: "CStatic Class" ms.date: "11/04/2016" f1_keywords: ["CStatic", "AFXWIN/CStatic", "AFXWIN/CStatic::CStatic", "AFXWIN/CStatic::Create", "AFXWIN/CStatic::DrawItem", "AFXWIN/CStatic::GetBitmap", "AFXWIN/CStatic::GetCursor", "AFXWIN/CStatic::GetEnhMetaFile", "AFXWIN/CStatic::GetIcon", "AFXWIN/CStatic::SetBitmap", "AFXWIN/CStatic::SetCursor", "AFXWIN/CStatic::SetEnhMetaFile", "AFXWIN/CStatic::SetIcon"] helpviewer_keywords: ["CStatic [MFC], CStatic", "CStatic [MFC], Create", "CStatic [MFC], DrawItem", "CStatic [MFC], GetBitmap", "CStatic [MFC], GetCursor", "CStatic [MFC], GetEnhMetaFile", "CStatic [MFC], GetIcon", "CStatic [MFC], SetBitmap", "CStatic [MFC], SetCursor", "CStatic [MFC], SetEnhMetaFile", "CStatic [MFC], SetIcon"] -ms.assetid: e7c94cd9-5ebd-428a-aa30-b3e51f8efb95 --- # `CStatic` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of a Windows static control. ## Syntax diff --git a/docs/mfc/reference/cstatusbar-class.md b/docs/mfc/reference/cstatusbar-class.md index 3a7b614c75c..c6c9f11a58f 100644 --- a/docs/mfc/reference/cstatusbar-class.md +++ b/docs/mfc/reference/cstatusbar-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CStatusBar Class" title: "CStatusBar Class" -ms.date: "11/04/2016" +description: "Learn more about: CStatusBar Class" +ms.date: 11/04/2016 f1_keywords: ["CStatusBar", "AFXEXT/CStatusBar", "AFXEXT/CStatusBar::CStatusBar", "AFXEXT/CStatusBar::CommandToIndex", "AFXEXT/CStatusBar::Create", "AFXEXT/CStatusBar::CreateEx", "AFXEXT/CStatusBar::DrawItem", "AFXEXT/CStatusBar::GetItemID", "AFXEXT/CStatusBar::GetItemRect", "AFXEXT/CStatusBar::GetPaneInfo", "AFXEXT/CStatusBar::GetPaneStyle", "AFXEXT/CStatusBar::GetPaneText", "AFXEXT/CStatusBar::GetStatusBarCtrl", "AFXEXT/CStatusBar::SetIndicators", "AFXEXT/CStatusBar::SetPaneInfo", "AFXEXT/CStatusBar::SetPaneStyle", "AFXEXT/CStatusBar::SetPaneText"] helpviewer_keywords: ["CStatusBar [MFC], CStatusBar", "CStatusBar [MFC], CommandToIndex", "CStatusBar [MFC], Create", "CStatusBar [MFC], CreateEx", "CStatusBar [MFC], DrawItem", "CStatusBar [MFC], GetItemID", "CStatusBar [MFC], GetItemRect", "CStatusBar [MFC], GetPaneInfo", "CStatusBar [MFC], GetPaneStyle", "CStatusBar [MFC], GetPaneText", "CStatusBar [MFC], GetStatusBarCtrl", "CStatusBar [MFC], SetIndicators", "CStatusBar [MFC], SetPaneInfo", "CStatusBar [MFC], SetPaneStyle", "CStatusBar [MFC], SetPaneText"] -ms.assetid: a3bde3db-e71c-4881-a3ca-1d5481c345ba --- # CStatusBar Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A control bar with a row of text output panes, or "indicators." ## Syntax @@ -306,7 +308,8 @@ For a list of styles available for status bars, see [Create](#create). Call this member function to retrieve the text that appears in a status-bar pane. ``` -CString GetPaneText(int nIndex) const; void GetPaneText(int nIndex, CString& rString) const; +CString GetPaneText(int nIndex) const; +void GetPaneText(int nIndex, CString& rString) const; ``` ### Parameters @@ -462,9 +465,9 @@ After you call `SetPaneText`, you must add a UI update handler to display the ne ### Example [!code-cpp[NVC_MFCDocView#176](../../mfc/codesnippet/cpp/cstatusbar-class_1.cpp)] - +  [!code-cpp[NVC_MFCDocView#177](../../mfc/codesnippet/cpp/cstatusbar-class_2.cpp)] - +  [!code-cpp[NVC_MFCDocView#178](../../mfc/codesnippet/cpp/cstatusbar-class_3.cpp)] ## See also diff --git a/docs/mfc/reference/cstatusbarctrl-class.md b/docs/mfc/reference/cstatusbarctrl-class.md index a8e884c9e38..aed31b1090e 100644 --- a/docs/mfc/reference/cstatusbarctrl-class.md +++ b/docs/mfc/reference/cstatusbarctrl-class.md @@ -4,10 +4,12 @@ title: "CStatusBarCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CStatusBarCtrl", "AFXCMN/CStatusBarCtrl", "AFXCMN/CStatusBarCtrl::CStatusBarCtrl", "AFXCMN/CStatusBarCtrl::Create", "AFXCMN/CStatusBarCtrl::CreateEx", "AFXCMN/CStatusBarCtrl::DrawItem", "AFXCMN/CStatusBarCtrl::GetBorders", "AFXCMN/CStatusBarCtrl::GetIcon", "AFXCMN/CStatusBarCtrl::GetParts", "AFXCMN/CStatusBarCtrl::GetRect", "AFXCMN/CStatusBarCtrl::GetText", "AFXCMN/CStatusBarCtrl::GetTextLength", "AFXCMN/CStatusBarCtrl::GetTipText", "AFXCMN/CStatusBarCtrl::IsSimple", "AFXCMN/CStatusBarCtrl::SetBkColor", "AFXCMN/CStatusBarCtrl::SetIcon", "AFXCMN/CStatusBarCtrl::SetMinHeight", "AFXCMN/CStatusBarCtrl::SetParts", "AFXCMN/CStatusBarCtrl::SetSimple", "AFXCMN/CStatusBarCtrl::SetText", "AFXCMN/CStatusBarCtrl::SetTipText"] helpviewer_keywords: ["CStatusBarCtrl [MFC], CStatusBarCtrl", "CStatusBarCtrl [MFC], Create", "CStatusBarCtrl [MFC], CreateEx", "CStatusBarCtrl [MFC], DrawItem", "CStatusBarCtrl [MFC], GetBorders", "CStatusBarCtrl [MFC], GetIcon", "CStatusBarCtrl [MFC], GetParts", "CStatusBarCtrl [MFC], GetRect", "CStatusBarCtrl [MFC], GetText", "CStatusBarCtrl [MFC], GetTextLength", "CStatusBarCtrl [MFC], GetTipText", "CStatusBarCtrl [MFC], IsSimple", "CStatusBarCtrl [MFC], SetBkColor", "CStatusBarCtrl [MFC], SetIcon", "CStatusBarCtrl [MFC], SetMinHeight", "CStatusBarCtrl [MFC], SetParts", "CStatusBarCtrl [MFC], SetSimple", "CStatusBarCtrl [MFC], SetText", "CStatusBarCtrl [MFC], SetTipText"] -ms.assetid: 8504ad38-7b91-4746-aede-ac98886eb47b --- # CStatusBarCtrl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common status bar control. ## Syntax diff --git a/docs/mfc/reference/cstdiofile-class.md b/docs/mfc/reference/cstdiofile-class.md index 9c318985f75..5cc9c21d9d5 100644 --- a/docs/mfc/reference/cstdiofile-class.md +++ b/docs/mfc/reference/cstdiofile-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a C run-time stream file as opened by the run-time function [`fopen`](../../c-runtime-library/reference/fopen-wfopen.md). ## Syntax @@ -181,7 +183,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 +262,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/cstring-formatting-and-message-box-display.md b/docs/mfc/reference/cstring-formatting-and-message-box-display.md index 51932cc807a..9a02bc6164b 100644 --- a/docs/mfc/reference/cstring-formatting-and-message-box-display.md +++ b/docs/mfc/reference/cstring-formatting-and-message-box-display.md @@ -3,10 +3,12 @@ description: "Learn more about: CString Formatting and Message-Box Display" title: "CString Formatting and Message-Box Display" ms.date: "11/04/2016" helpviewer_keywords: ["CString objects [MFC], formatting and message boxes"] -ms.assetid: d1068cf4-9cc5-4952-b9e7-d612c53cbc28 --- # `CString` Formatting and Message-Box Display +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A number of functions are provided to format and parse `CString` objects. You can use these functions whenever you have to manipulate `CString` objects, but they are particularly useful for formatting strings that will appear in message-box text. This group of functions also includes a global routine for displaying a message box. diff --git a/docs/mfc/reference/cstringarray-class.md b/docs/mfc/reference/cstringarray-class.md index 34af72a6b3d..89df9c7e97b 100644 --- a/docs/mfc/reference/cstringarray-class.md +++ b/docs/mfc/reference/cstringarray-class.md @@ -4,15 +4,17 @@ 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports arrays of [`CString`](../../atl-mfc-shared/using-cstring.md) objects. ## Syntax -``` +```cpp class CStringArray : public CObject ``` @@ -24,7 +26,7 @@ The member functions of `CStringArray` are similar to the member functions of cl for example, translates to -`CString CStringArray::GetAt( int ) const;` +`const CString& CStringArray::GetAt( int ) const;` and diff --git a/docs/mfc/reference/cstringlist-class.md b/docs/mfc/reference/cstringlist-class.md index f24299b44b2..323ca43963e 100644 --- a/docs/mfc/reference/cstringlist-class.md +++ b/docs/mfc/reference/cstringlist-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CStringList [MFC], CStringList", "CStringList [MFC], AddH --- # `CStringList` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports lists of `CString` objects. ## Syntax @@ -49,12 +52,12 @@ translates to |[`CStringList::FindIndex`](../../mfc/reference/coblist-class.md#findindex)|Gets the position of an element specified by a zero-based index.| |[`CStringList::GetAt`](../../mfc/reference/coblist-class.md#getat)|Gets the element at a given position.| |[`CStringList::GetCount`](../../mfc/reference/coblist-class.md#getcount)|Returns the number of elements in this list.| -|[`CStringList::GetHead`](../../mfc/reference/coblist-class.md#gethead)|Returns the head element of the list (can’t be empty).| +|[`CStringList::GetHead`](../../mfc/reference/coblist-class.md#gethead)|Returns the head element of the list (can't be empty).| |[`CStringList::GetHeadPosition`](../../mfc/reference/coblist-class.md#getheadposition)|Returns the position of the head element of the list.| |[`CStringList::GetNext`](../../mfc/reference/coblist-class.md#getnext)|Gets the next element for iterating.| |[`CStringList::GetPrev`](../../mfc/reference/coblist-class.md#getprev)|Gets the previous element for iterating.| |[`CStringList::GetSize`](../../mfc/reference/coblist-class.md#getsize)|Returns the number of elements in this list.| -|[`CStringList::GetTail`](../../mfc/reference/coblist-class.md#gettail)|Returns the tail element of the list (can’t be empty).| +|[`CStringList::GetTail`](../../mfc/reference/coblist-class.md#gettail)|Returns the tail element of the list (can't be empty).| |[`CStringList::GetTailPosition`](../../mfc/reference/coblist-class.md#gettailposition)|Returns the position of the tail element of the list.| |[`CStringList::InsertAfter`](../../mfc/reference/coblist-class.md#insertafter)|Inserts a new element after a given position.| |[`CStringList::InsertBefore`](../../mfc/reference/coblist-class.md#insertbefore)|Inserts a new element before a given position.| diff --git a/docs/mfc/reference/csyncobject-class.md b/docs/mfc/reference/csyncobject-class.md index 535d9aaaa81..3ba190fb667 100644 --- a/docs/mfc/reference/csyncobject-class.md +++ b/docs/mfc/reference/csyncobject-class.md @@ -4,10 +4,12 @@ title: "CSyncObject Class" ms.date: "11/04/2016" f1_keywords: ["CSyncObject", "AFXMT/CSyncObject", "AFXMT/CSyncObject::CSyncObject", "AFXMT/CSyncObject::Lock", "AFXMT/CSyncObject::Unlock", "AFXMT/CSyncObject::m_hObject"] helpviewer_keywords: ["CSyncObject [MFC], CSyncObject", "CSyncObject [MFC], Lock", "CSyncObject [MFC], Unlock", "CSyncObject [MFC], m_hObject"] -ms.assetid: c62ea6eb-a17b-4e01-aed4-321fc435a5f4 --- # CSyncObject Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A pure virtual class that provides functionality common to the synchronization objects in Win32. ## Syntax diff --git a/docs/mfc/reference/ctabbedpane-class.md b/docs/mfc/reference/ctabbedpane-class.md index f6b051754f6..939efc4a2c1 100644 --- a/docs/mfc/reference/ctabbedpane-class.md +++ b/docs/mfc/reference/ctabbedpane-class.md @@ -4,10 +4,12 @@ title: "CTabbedPane Class" ms.date: "11/04/2016" f1_keywords: ["CTabbedPane", "AFXTABBEDPANE/CTabbedPane", "AFXTABBEDPANE/CTabbedPane::DetachPane", "AFXTABBEDPANE/CTabbedPane::EnableTabAutoColor", "AFXTABBEDPANE/CTabbedPane::FloatTab", "AFXTABBEDPANE/CTabbedPane::GetTabArea", "AFXTABBEDPANE/CTabbedPane::GetTabWnd", "AFXTABBEDPANE/CTabbedPane::HasAutoHideMode", "AFXTABBEDPANE/CTabbedPane::IsTabLocationBottom", "AFXTABBEDPANE/CTabbedPane::ResetTabs", "AFXTABBEDPANE/CTabbedPane::SetTabAutoColors", "AFXTABBEDPANE/CTabbedPane::m_bTabsAlwaysTop", "AFXTABBEDPANE/CTabbedPane::m_pTabWndRTC"] helpviewer_keywords: ["CTabbedPane [MFC], DetachPane", "CTabbedPane [MFC], EnableTabAutoColor", "CTabbedPane [MFC], FloatTab", "CTabbedPane [MFC], GetTabArea", "CTabbedPane [MFC], GetTabWnd", "CTabbedPane [MFC], HasAutoHideMode", "CTabbedPane [MFC], IsTabLocationBottom", "CTabbedPane [MFC], ResetTabs", "CTabbedPane [MFC], SetTabAutoColors", "CTabbedPane [MFC], m_bTabsAlwaysTop", "CTabbedPane [MFC], m_pTabWndRTC"] -ms.assetid: f4dc5215-b789-4f2d-8c62-477aceda3578 --- # CTabbedPane Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements the functionality of a pane with detachable tabs. or more detail see the source code located in the **VC\\atlmfc\\src\\mfc** folder of your Visual Studio installation. diff --git a/docs/mfc/reference/ctabctrl-class.md b/docs/mfc/reference/ctabctrl-class.md index 8416886a1de..8e2ee485435 100644 --- a/docs/mfc/reference/ctabctrl-class.md +++ b/docs/mfc/reference/ctabctrl-class.md @@ -1,12 +1,15 @@ --- 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"] --- # `CTabCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common tab control. ## Syntax @@ -80,7 +83,7 @@ For more information about `CTabCtrl`, see [Controls](../../mfc/controls-mfc.md) **Header:** `afxcmn.h` -## `CTabCtrl::AdjustRect` +## `CTabCtrl::AdjustRect` Calculates a tab control's display area given a window rectangle, or calculates the window rectangle that would correspond to a given display area. @@ -366,7 +369,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/ctabview-class.md b/docs/mfc/reference/ctabview-class.md index b084e0afbd3..2a38b3edd1b 100644 --- a/docs/mfc/reference/ctabview-class.md +++ b/docs/mfc/reference/ctabview-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CTabView Class" title: "CTabView Class" -ms.date: "11/04/2016" +description: "Learn more about: CTabView Class" +ms.date: 11/04/2016 f1_keywords: ["CTabView", "AFXTABVIEW/CTabView", "AFXTABVIEW/CTabView::AddView", "AFXTABVIEW/CTabView::FindTab", "AFXTABVIEW/CTabView::GetActiveView", "AFXTABVIEW/CTabView::GetTabControl", "AFXTABVIEW/CTabView::RemoveView", "AFXTABVIEW/CTabView::SetActiveView", "AFXTABVIEW/CTabView::IsScrollBar", "AFXTABVIEW/CTabView::OnActivateView"] helpviewer_keywords: ["CTabView [MFC], AddView", "CTabView [MFC], FindTab", "CTabView [MFC], GetActiveView", "CTabView [MFC], GetTabControl", "CTabView [MFC], RemoveView", "CTabView [MFC], SetActiveView", "CTabView [MFC], IsScrollBar", "CTabView [MFC], OnActivateView"] -ms.assetid: 8e6ecd9d-d28d-432b-8ec8-0446f0204d52 --- # CTabView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CTabView` class simplifies the use of the tab control class ( [CMFCTabCtrl](../../mfc/reference/ctabview-class.md)) in applications that use MFC's document/view architecture. ## Syntax @@ -208,7 +210,7 @@ TRUE if the specified view was made active, FALSE if the view's index is invalid ### Remarks -For more information see [CMFCTabCtrl::SetActiveTab](../../mfc/reference/cmfctabctrl-class.md#setactivetab). +For more information, see [CMFCTabCtrl::SetActiveTab](../../mfc/reference/cmfctabctrl-class.md#setactivetab). ## See also diff --git a/docs/mfc/reference/ctaskdialog-class.md b/docs/mfc/reference/ctaskdialog-class.md index 9c685c35608..c7d5d84e1a4 100644 --- a/docs/mfc/reference/ctaskdialog-class.md +++ b/docs/mfc/reference/ctaskdialog-class.md @@ -4,10 +4,12 @@ title: "CTaskDialog Class" ms.date: "11/19/2018" f1_keywords: ["CTaskDialog", "AFXTASKDIALOG/CTaskDialog", "AFXTASKDIALOG/CTaskDialog::CTaskDialog", "AFXTASKDIALOG/CTaskDialog::AddCommandControl", "AFXTASKDIALOG/CTaskDialog::AddRadioButton", "AFXTASKDIALOG/CTaskDialog::ClickCommandControl", "AFXTASKDIALOG/CTaskDialog::ClickRadioButton", "AFXTASKDIALOG/CTaskDialog::DoModal", "AFXTASKDIALOG/CTaskDialog::GetCommonButtonCount", "AFXTASKDIALOG/CTaskDialog::GetCommonButtonFlag", "AFXTASKDIALOG/CTaskDialog::GetCommonButtonId", "AFXTASKDIALOG/CTaskDialog::GetOptions", "AFXTASKDIALOG/CTaskDialog::GetSelectedCommandControlID", "AFXTASKDIALOG/CTaskDialog::GetSelectedRadioButtonID", "AFXTASKDIALOG/CTaskDialog::GetVerificationCheckboxState", "AFXTASKDIALOG/CTaskDialog::IsCommandControlEnabled", "AFXTASKDIALOG/CTaskDialog::IsRadioButtonEnabled", "AFXTASKDIALOG/CTaskDialog::IsSupported", "AFXTASKDIALOG/CTaskDialog::LoadCommandControls", "AFXTASKDIALOG/CTaskDialog::LoadRadioButtons", "AFXTASKDIALOG/CTaskDialog::NavigateTo", "AFXTASKDIALOG/CTaskDialog::OnCommandControlClick", "AFXTASKDIALOG/CTaskDialog::OnCreate", "AFXTASKDIALOG/CTaskDialog::OnDestroy", "AFXTASKDIALOG/CTaskDialog::OnExpandButtonClick", "AFXTASKDIALOG/CTaskDialog::OnHelp", "AFXTASKDIALOG/CTaskDialog::OnHyperlinkClick", "AFXTASKDIALOG/CTaskDialog::OnInit", "AFXTASKDIALOG/CTaskDialog::OnNavigatePage", "AFXTASKDIALOG/CTaskDialog::OnRadioButtonClick", "AFXTASKDIALOG/CTaskDialog::OnTimer", "AFXTASKDIALOG/CTaskDialog::OnVerificationCheckboxClick", "AFXTASKDIALOG/CTaskDialog::RemoveAllCommandControls", "AFXTASKDIALOG/CTaskDialog::RemoveAllRadioButtons", "AFXTASKDIALOG/CTaskDialog::SetCommandControlOptions", "AFXTASKDIALOG/CTaskDialog::SetCommonButtonOptions", "AFXTASKDIALOG/CTaskDialog::SetCommonButtons", "AFXTASKDIALOG/CTaskDialog::SetContent", "AFXTASKDIALOG/CTaskDialog::SetDefaultCommandControl", "AFXTASKDIALOG/CTaskDialog::SetDefaultRadioButton", "AFXTASKDIALOG/CTaskDialog::SetDialogWidth", "AFXTASKDIALOG/CTaskDialog::SetExpansionArea", "AFXTASKDIALOG/CTaskDialog::SetFooterIcon", "AFXTASKDIALOG/CTaskDialog::SetFooterText", "AFXTASKDIALOG/CTaskDialog::SetMainIcon", "AFXTASKDIALOG/CTaskDialog::SetMainInstruction", "AFXTASKDIALOG/CTaskDialog::SetOptions", "AFXTASKDIALOG/CTaskDialog::SetProgressBarMarquee", "AFXTASKDIALOG/CTaskDialog::SetProgressBarPosition", "AFXTASKDIALOG/CTaskDialog::SetProgressBarRange", "AFXTASKDIALOG/CTaskDialog::SetProgressBarState", "AFXTASKDIALOG/CTaskDialog::SetRadioButtonOptions", "AFXTASKDIALOG/CTaskDialog::SetVerificationCheckbox", "AFXTASKDIALOG/CTaskDialog::SetVerificationCheckboxText", "AFXTASKDIALOG/CTaskDialog::SetWindowTitle", "AFXTASKDIALOG/CTaskDialog::ShowDialog", "AFXTASKDIALOG/CTaskDialog::TaskDialogCallback"] helpviewer_keywords: ["CTaskDialog [MFC], CTaskDialog", "CTaskDialog [MFC], AddCommandControl", "CTaskDialog [MFC], AddRadioButton", "CTaskDialog [MFC], ClickCommandControl", "CTaskDialog [MFC], ClickRadioButton", "CTaskDialog [MFC], DoModal", "CTaskDialog [MFC], GetCommonButtonCount", "CTaskDialog [MFC], GetCommonButtonFlag", "CTaskDialog [MFC], GetCommonButtonId", "CTaskDialog [MFC], GetOptions", "CTaskDialog [MFC], GetSelectedCommandControlID", "CTaskDialog [MFC], GetSelectedRadioButtonID", "CTaskDialog [MFC], GetVerificationCheckboxState", "CTaskDialog [MFC], IsCommandControlEnabled", "CTaskDialog [MFC], IsRadioButtonEnabled", "CTaskDialog [MFC], IsSupported", "CTaskDialog [MFC], LoadCommandControls", "CTaskDialog [MFC], LoadRadioButtons", "CTaskDialog [MFC], NavigateTo", "CTaskDialog [MFC], OnCommandControlClick", "CTaskDialog [MFC], OnCreate", "CTaskDialog [MFC], OnDestroy", "CTaskDialog [MFC], OnExpandButtonClick", "CTaskDialog [MFC], OnHelp", "CTaskDialog [MFC], OnHyperlinkClick", "CTaskDialog [MFC], OnInit", "CTaskDialog [MFC], OnNavigatePage", "CTaskDialog [MFC], OnRadioButtonClick", "CTaskDialog [MFC], OnTimer", "CTaskDialog [MFC], OnVerificationCheckboxClick", "CTaskDialog [MFC], RemoveAllCommandControls", "CTaskDialog [MFC], RemoveAllRadioButtons", "CTaskDialog [MFC], SetCommandControlOptions", "CTaskDialog [MFC], SetCommonButtonOptions", "CTaskDialog [MFC], SetCommonButtons", "CTaskDialog [MFC], SetContent", "CTaskDialog [MFC], SetDefaultCommandControl", "CTaskDialog [MFC], SetDefaultRadioButton", "CTaskDialog [MFC], SetDialogWidth", "CTaskDialog [MFC], SetExpansionArea", "CTaskDialog [MFC], SetFooterIcon", "CTaskDialog [MFC], SetFooterText", "CTaskDialog [MFC], SetMainIcon", "CTaskDialog [MFC], SetMainInstruction", "CTaskDialog [MFC], SetOptions", "CTaskDialog [MFC], SetProgressBarMarquee", "CTaskDialog [MFC], SetProgressBarPosition", "CTaskDialog [MFC], SetProgressBarRange", "CTaskDialog [MFC], SetProgressBarState", "CTaskDialog [MFC], SetRadioButtonOptions", "CTaskDialog [MFC], SetVerificationCheckbox", "CTaskDialog [MFC], SetVerificationCheckboxText", "CTaskDialog [MFC], SetWindowTitle", "CTaskDialog [MFC], ShowDialog", "CTaskDialog [MFC], TaskDialogCallback"] -ms.assetid: 1991ec98-ae56-4483-958b-233809c8c559 --- # CTaskDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax @@ -685,7 +687,7 @@ virtual HRESULT OnHelp(); ### Return Value -The default implementation returns S_OK. +The default implementation returns S_FALSE. ### Remarks diff --git a/docs/mfc/reference/ctoolbar-class.md b/docs/mfc/reference/ctoolbar-class.md index 983d20748bc..0374063757d 100644 --- a/docs/mfc/reference/ctoolbar-class.md +++ b/docs/mfc/reference/ctoolbar-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CToolBar [MFC], CToolBar", "CToolBar [MFC], CommandToInde --- # `CToolBar` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Control bars that have a row of bitmapped buttons and optional separators. ## Syntax @@ -52,7 +55,7 @@ The buttons can act like pushbuttons, check-box buttons, or radio buttons. `CToo [`CToolBar::GetToolBarCtrl`](#gettoolbarctrl), a member function new to MFC 4.0, allows you to take advantage of the Windows common control's support for toolbar customization and additional functionality. `CToolBar` member functions give you most of the functionality of the Windows common controls; however, when you call `GetToolBarCtrl`, you can give your toolbars even more of the characteristics of Windows 95/98 toolbars. When you call `GetToolBarCtrl`, it will return a reference to a `CToolBarCtrl` object. See [`CToolBarCtrl`](../../mfc/reference/ctoolbarctrl-class.md) for more information about designing toolbars using Windows common controls. For more general information about common controls, see [Common Controls](/windows/win32/Controls/common-controls-intro) in the Windows SDK. -Visual C++ provides you with two methods to create a toolbar. To create a toolbar resource using the Resource Editor, follow these steps: +Visual Studio provides you with two methods to create a toolbar. To create a toolbar resource using the Resource Editor, follow these steps: 1. Create a toolbar resource. diff --git a/docs/mfc/reference/ctoolbarctrl-class.md b/docs/mfc/reference/ctoolbarctrl-class.md index 558c744f429..b4ff4996576 100644 --- a/docs/mfc/reference/ctoolbarctrl-class.md +++ b/docs/mfc/reference/ctoolbarctrl-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CToolBarCtrl [MFC], CToolBarCtrl", "CToolBarCtrl [MFC], A --- # `CToolBarCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows toolbar common control. ## Syntax @@ -121,7 +124,7 @@ This control (and therefore the `CToolBarCtrl` class) is available only to progr A Windows toolbar common control is a rectangular child window that contains one or more buttons. These buttons can display a bitmap image, a string, or both. When the user chooses a button, it sends a command message to the toolbar's owner window. Typically, the buttons in a toolbar correspond to items in the application's menu; they provide a more direct way for the user to access an application's commands. -`CToolBarCtrl` objects contain several important internal data structures: a list of button image bitmaps or an image list, a list of button label strings, and a list of `TBBUTTON` structures that associate an image and/or string with the position, style, state, and command ID of the button. Each of the elements of these data structures is referred to by a zero-based index. Before you can use a `CToolBarCtrl` object, you must set up these data structures. The list of strings can only be used for button labels; you can’t retrieve strings from the toolbar. +`CToolBarCtrl` objects contain several important internal data structures: a list of button image bitmaps or an image list, a list of button label strings, and a list of `TBBUTTON` structures that associate an image and/or string with the position, style, state, and command ID of the button. Each of the elements of these data structures is referred to by a zero-based index. Before you can use a `CToolBarCtrl` object, you must set up these data structures. The list of strings can only be used for button labels; you can't retrieve strings from the toolbar. To use a `CToolBarCtrl` object, you'll typically follow these steps: @@ -257,7 +260,7 @@ The members are as follows: - `TBSTATE_ENABLED` The button accepts user input. A button that doesn't have this state doesn't accept user input and is grayed. - - `TBSTATE_HIDDEN` The button isn't visible and can’t receive user input. + - `TBSTATE_HIDDEN` The button isn't visible and can't receive user input. - `TBSTATE_INDETERMINATE` The button is grayed. @@ -2108,18 +2111,18 @@ void SetRows( Requested number of rows. *`bLarger`*\ -Tells whether to use more rows or fewer rows if the toolbar can’t be resized to the requested number of rows. +Tells whether to use more rows or fewer rows if the toolbar can't be resized to the requested number of rows. *`lpRect`*\ Points to the [`CRect`](../../atl-mfc-shared/reference/crect-class.md) object or [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure that will receive the new bounding rectangle of the toolbar. ### Remarks -If the toolbar can’t resize itself to the requested number or rows, it will resize itself to either the next larger or next smaller valid size, depending on the value of *`bLarger`*. If *`bLarger`* is `TRUE`, the new number of rows will be larger than the number requested. If *`bLarger`* is `FALSE`, the new number of rows will be smaller than the number requested. +If the toolbar can't resize itself to the requested number or rows, it will resize itself to either the next larger or next smaller valid size, depending on the value of *`bLarger`*. If *`bLarger`* is `TRUE`, the new number of rows will be larger than the number requested. If *`bLarger`* is `FALSE`, the new number of rows will be smaller than the number requested. A given number of rows is valid for the toolbar if the buttons can be arranged such that all of the rows have the same number of buttons (except perhaps the last row). For example, a toolbar that contains four buttons couldn't be sized to three rows because the last two rows would have to be shorter. If you attempted to size it to three rows, you would get four rows if *`bLarger`* was `TRUE` and two rows if *`bLarger`* was `FALSE`. -If there are separators in the toolbar, the rules for when a given number of rows is valid are more complicated. The layout is computed such that button groups (buttons with a separator before the first and the last button in the group) are never broken up on several rows unless the group can’t fit on one row. +If there are separators in the toolbar, the rules for when a given number of rows is valid are more complicated. The layout is computed such that button groups (buttons with a separator before the first and the last button in the group) are never broken up on several rows unless the group can't fit on one row. If a group doesn't fit on one row, the next group will start on the next row even if it would fit on the row where the large group ended. The purpose of this rule is to make the separation between large groups more noticeable. The resulting vertical separators are counted as rows. diff --git a/docs/mfc/reference/ctooltipctrl-class.md b/docs/mfc/reference/ctooltipctrl-class.md index ceaf49a6f03..258feb52633 100644 --- a/docs/mfc/reference/ctooltipctrl-class.md +++ b/docs/mfc/reference/ctooltipctrl-class.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["CToolTipCtrl [MFC], CToolTipCtrl", "CToolTipCtrl [MFC], A --- # `CToolTipCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Encapsulates the functionality of a "tooltip control," a small pop-up window that displays a single line of text describing the purpose of a tool in an application. ## Syntax diff --git a/docs/mfc/reference/ctooltipmanager-class.md b/docs/mfc/reference/ctooltipmanager-class.md index 4a495081f92..a8ed2b9ada1 100644 --- a/docs/mfc/reference/ctooltipmanager-class.md +++ b/docs/mfc/reference/ctooltipmanager-class.md @@ -4,10 +4,12 @@ title: "CTooltipManager Class" ms.date: "11/04/2016" f1_keywords: ["CTooltipManager", "AFXTOOLTIPMANAGER/CTooltipManager", "AFXTOOLTIPMANAGER/CTooltipManager::CreateToolTip", "AFXTOOLTIPMANAGER/CTooltipManager::DeleteToolTip", "AFXTOOLTIPMANAGER/CTooltipManager::SetTooltipParams", "AFXTOOLTIPMANAGER/CTooltipManager::SetTooltipText", "AFXTOOLTIPMANAGER/CTooltipManager::UpdateTooltips"] helpviewer_keywords: ["CTooltipManager [MFC], CreateToolTip", "CTooltipManager [MFC], DeleteToolTip", "CTooltipManager [MFC], SetTooltipParams", "CTooltipManager [MFC], SetTooltipText", "CTooltipManager [MFC], UpdateTooltips"] -ms.assetid: c71779d7-8b6e-47ef-8500-d4552731fe86 --- # CTooltipManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Maintains runtime information about tooltips. The `CTooltipManager` class is instantiated one time per application. ## Syntax diff --git a/docs/mfc/reference/ctreectrl-class.md b/docs/mfc/reference/ctreectrl-class.md index 83e6a7fccb0..f3679f9e9bc 100644 --- a/docs/mfc/reference/ctreectrl-class.md +++ b/docs/mfc/reference/ctreectrl-class.md @@ -4,10 +4,12 @@ title: "CTreeCtrl Class" ms.date: "11/04/2016" f1_keywords: ["CTreeCtrl", "AFXCMN/CTreeCtrl", "AFXCMN/CTreeCtrl::CTreeCtrl", "AFXCMN/CTreeCtrl::Create", "AFXCMN/CTreeCtrl::CreateDragImage", "AFXCMN/CTreeCtrl::CreateEx", "AFXCMN/CTreeCtrl::DeleteAllItems", "AFXCMN/CTreeCtrl::DeleteItem", "AFXCMN/CTreeCtrl::EditLabel", "AFXCMN/CTreeCtrl::EndEditLabelNow", "AFXCMN/CTreeCtrl::EnsureVisible", "AFXCMN/CTreeCtrl::Expand", "AFXCMN/CTreeCtrl::GetBkColor", "AFXCMN/CTreeCtrl::GetCheck", "AFXCMN/CTreeCtrl::GetChildItem", "AFXCMN/CTreeCtrl::GetCount", "AFXCMN/CTreeCtrl::GetDropHilightItem", "AFXCMN/CTreeCtrl::GetEditControl", "AFXCMN/CTreeCtrl::GetExtendedStyle", "AFXCMN/CTreeCtrl::GetFirstVisibleItem", "AFXCMN/CTreeCtrl::GetImageList", "AFXCMN/CTreeCtrl::GetIndent", "AFXCMN/CTreeCtrl::GetInsertMarkColor", "AFXCMN/CTreeCtrl::GetItem", "AFXCMN/CTreeCtrl::GetItemData", "AFXCMN/CTreeCtrl::GetItemExpandedImageIndex", "AFXCMN/CTreeCtrl::GetItemHeight", "AFXCMN/CTreeCtrl::GetItemImage", "AFXCMN/CTreeCtrl::GetItemPartRect", "AFXCMN/CTreeCtrl::GetItemRect", "AFXCMN/CTreeCtrl::GetItemState", "AFXCMN/CTreeCtrl::GetItemStateEx", "AFXCMN/CTreeCtrl::GetItemText", "AFXCMN/CTreeCtrl::GetLastVisibleItem", "AFXCMN/CTreeCtrl::GetLineColor", "AFXCMN/CTreeCtrl::GetNextItem", "AFXCMN/CTreeCtrl::GetNextSiblingItem", "AFXCMN/CTreeCtrl::GetNextVisibleItem", "AFXCMN/CTreeCtrl::GetParentItem", "AFXCMN/CTreeCtrl::GetPrevSiblingItem", "AFXCMN/CTreeCtrl::GetPrevVisibleItem", "AFXCMN/CTreeCtrl::GetRootItem", "AFXCMN/CTreeCtrl::GetScrollTime", "AFXCMN/CTreeCtrl::GetSelectedCount", "AFXCMN/CTreeCtrl::GetSelectedItem", "AFXCMN/CTreeCtrl::GetTextColor", "AFXCMN/CTreeCtrl::GetToolTips", "AFXCMN/CTreeCtrl::GetVisibleCount", "AFXCMN/CTreeCtrl::HitTest", "AFXCMN/CTreeCtrl::InsertItem", "AFXCMN/CTreeCtrl::ItemHasChildren", "AFXCMN/CTreeCtrl::MapAccIdToItem", "AFXCMN/CTreeCtrl::MapItemToAccID", "AFXCMN/CTreeCtrl::Select", "AFXCMN/CTreeCtrl::SelectDropTarget", "AFXCMN/CTreeCtrl::SelectItem", "AFXCMN/CTreeCtrl::SelectSetFirstVisible", "AFXCMN/CTreeCtrl::SetAutoscrollInfo", "AFXCMN/CTreeCtrl::SetBkColor", "AFXCMN/CTreeCtrl::SetCheck", "AFXCMN/CTreeCtrl::SetExtendedStyle", "AFXCMN/CTreeCtrl::SetImageList", "AFXCMN/CTreeCtrl::SetIndent", "AFXCMN/CTreeCtrl::SetInsertMark", "AFXCMN/CTreeCtrl::SetInsertMarkColor", "AFXCMN/CTreeCtrl::SetItem", "AFXCMN/CTreeCtrl::SetItemData", "AFXCMN/CTreeCtrl::SetItemExpandedImageIndex", "AFXCMN/CTreeCtrl::SetItemHeight", "AFXCMN/CTreeCtrl::SetItemImage", "AFXCMN/CTreeCtrl::SetItemState", "AFXCMN/CTreeCtrl::SetItemStateEx", "AFXCMN/CTreeCtrl::SetItemText", "AFXCMN/CTreeCtrl::SetLineColor", "AFXCMN/CTreeCtrl::SetScrollTime", "AFXCMN/CTreeCtrl::SetTextColor", "AFXCMN/CTreeCtrl::SetToolTips", "AFXCMN/CTreeCtrl::ShowInfoTip", "AFXCMN/CTreeCtrl::SortChildren", "AFXCMN/CTreeCtrl::SortChildrenCB"] helpviewer_keywords: ["CTreeCtrl [MFC], CTreeCtrl", "CTreeCtrl [MFC], Create", "CTreeCtrl [MFC], CreateDragImage", "CTreeCtrl [MFC], CreateEx", "CTreeCtrl [MFC], DeleteAllItems", "CTreeCtrl [MFC], DeleteItem", "CTreeCtrl [MFC], EditLabel", "CTreeCtrl [MFC], EndEditLabelNow", "CTreeCtrl [MFC], EnsureVisible", "CTreeCtrl [MFC], Expand", "CTreeCtrl [MFC], GetBkColor", "CTreeCtrl [MFC], GetCheck", "CTreeCtrl [MFC], GetChildItem", "CTreeCtrl [MFC], GetCount", "CTreeCtrl [MFC], GetDropHilightItem", "CTreeCtrl [MFC], GetEditControl", "CTreeCtrl [MFC], GetExtendedStyle", "CTreeCtrl [MFC], GetFirstVisibleItem", "CTreeCtrl [MFC], GetImageList", "CTreeCtrl [MFC], GetIndent", "CTreeCtrl [MFC], GetInsertMarkColor", "CTreeCtrl [MFC], GetItem", "CTreeCtrl [MFC], GetItemData", "CTreeCtrl [MFC], GetItemExpandedImageIndex", "CTreeCtrl [MFC], GetItemHeight", "CTreeCtrl [MFC], GetItemImage", "CTreeCtrl [MFC], GetItemPartRect", "CTreeCtrl [MFC], GetItemRect", "CTreeCtrl [MFC], GetItemState", "CTreeCtrl [MFC], GetItemStateEx", "CTreeCtrl [MFC], GetItemText", "CTreeCtrl [MFC], GetLastVisibleItem", "CTreeCtrl [MFC], GetLineColor", "CTreeCtrl [MFC], GetNextItem", "CTreeCtrl [MFC], GetNextSiblingItem", "CTreeCtrl [MFC], GetNextVisibleItem", "CTreeCtrl [MFC], GetParentItem", "CTreeCtrl [MFC], GetPrevSiblingItem", "CTreeCtrl [MFC], GetPrevVisibleItem", "CTreeCtrl [MFC], GetRootItem", "CTreeCtrl [MFC], GetScrollTime", "CTreeCtrl [MFC], GetSelectedCount", "CTreeCtrl [MFC], GetSelectedItem", "CTreeCtrl [MFC], GetTextColor", "CTreeCtrl [MFC], GetToolTips", "CTreeCtrl [MFC], GetVisibleCount", "CTreeCtrl [MFC], HitTest", "CTreeCtrl [MFC], InsertItem", "CTreeCtrl [MFC], ItemHasChildren", "CTreeCtrl [MFC], MapAccIdToItem", "CTreeCtrl [MFC], MapItemToAccID", "CTreeCtrl [MFC], Select", "CTreeCtrl [MFC], SelectDropTarget", "CTreeCtrl [MFC], SelectItem", "CTreeCtrl [MFC], SelectSetFirstVisible", "CTreeCtrl [MFC], SetAutoscrollInfo", "CTreeCtrl [MFC], SetBkColor", "CTreeCtrl [MFC], SetCheck", "CTreeCtrl [MFC], SetExtendedStyle", "CTreeCtrl [MFC], SetImageList", "CTreeCtrl [MFC], SetIndent", "CTreeCtrl [MFC], SetInsertMark", "CTreeCtrl [MFC], SetInsertMarkColor", "CTreeCtrl [MFC], SetItem", "CTreeCtrl [MFC], SetItemData", "CTreeCtrl [MFC], SetItemExpandedImageIndex", "CTreeCtrl [MFC], SetItemHeight", "CTreeCtrl [MFC], SetItemImage", "CTreeCtrl [MFC], SetItemState", "CTreeCtrl [MFC], SetItemStateEx", "CTreeCtrl [MFC], SetItemText", "CTreeCtrl [MFC], SetLineColor", "CTreeCtrl [MFC], SetScrollTime", "CTreeCtrl [MFC], SetTextColor", "CTreeCtrl [MFC], SetToolTips", "CTreeCtrl [MFC], ShowInfoTip", "CTreeCtrl [MFC], SortChildren", "CTreeCtrl [MFC], SortChildrenCB"] -ms.assetid: 96e20031-6161-4143-8c12-8d1816c66d90 --- # `CTreeCtrl` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the functionality of the Windows common tree view control. ## Syntax @@ -2154,7 +2156,7 @@ The *`lParam1`* and *`lParam2`* parameters correspond to the `lParam` member of ### Example [!code-cpp[NVC_MFC_CTreeCtrl#38](../../mfc/reference/codesnippet/cpp/ctreectrl-class_46.cpp)] - +  [!code-cpp[NVC_MFC_CTreeCtrl#39](../../mfc/reference/codesnippet/cpp/ctreectrl-class_47.cpp)] ## See also diff --git a/docs/mfc/reference/ctreeview-class.md b/docs/mfc/reference/ctreeview-class.md index 7511efdd06c..4419e23af0a 100644 --- a/docs/mfc/reference/ctreeview-class.md +++ b/docs/mfc/reference/ctreeview-class.md @@ -4,10 +4,12 @@ title: "CTreeView Class" ms.date: "11/04/2016" f1_keywords: ["CTreeView", "AFXCVIEW/CTreeView", "AFXCVIEW/CTreeView::CTreeView", "AFXCVIEW/CTreeView::GetTreeCtrl"] helpviewer_keywords: ["CTreeView [MFC], CTreeView", "CTreeView [MFC], GetTreeCtrl"] -ms.assetid: 5df583a6-d69f-42ca-9d8d-57e04558afff --- # CTreeView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Simplifies use of the tree control and of [CTreeCtrl](../../mfc/reference/ctreectrl-class.md), the class that encapsulates tree-control functionality, with MFC's document-view architecture. ## Syntax diff --git a/docs/mfc/reference/ctypedptrarray-class.md b/docs/mfc/reference/ctypedptrarray-class.md index 5bdf3ccd14c..0ece714e621 100644 --- a/docs/mfc/reference/ctypedptrarray-class.md +++ b/docs/mfc/reference/ctypedptrarray-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides a type-safe "wrapper" for objects of class `CPtrArray` or `CObArray`. ## Syntax @@ -20,7 +22,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 9eefb3d44ac..0ffa8e30f0f 100644 --- a/docs/mfc/reference/ctypedptrlist-class.md +++ b/docs/mfc/reference/ctypedptrlist-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides a type-safe "wrapper" for objects of class `CPtrList`. ## Syntax @@ -20,7 +22,7 @@ class CTypedPtrList : public BASE_CLASS #### Parameters *BASE_CLASS*
-Base class of the typed pointer list class; must be a pointer list class ( `CObList` or `CPtrList`). +Base class of the typed pointer list class; must be a pointer list class (`CObList` or `CPtrList`). *TYPE*
Type of the elements stored in the base-class list. @@ -61,7 +63,7 @@ For more information on using `CTypedPtrList`, see the articles [Collections](.. This example creates an instance of `CTypedPtrList`, adds one object, serializes the list to disk, and then deletes the object: [!code-cpp[NVC_MFCCollections#110](../../mfc/codesnippet/cpp/ctypedptrlist-class_1.cpp)] - +  [!code-cpp[NVC_MFCCollections#111](../../mfc/codesnippet/cpp/ctypedptrlist-class_2.cpp)] ## Inheritance Hierarchy diff --git a/docs/mfc/reference/ctypedptrmap-class.md b/docs/mfc/reference/ctypedptrmap-class.md index 03721557f82..7b430d55ba8 100644 --- a/docs/mfc/reference/ctypedptrmap-class.md +++ b/docs/mfc/reference/ctypedptrmap-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides a type-safe "wrapper" for objects of the pointer-map classes `CMapPtrToPtr`, `CMapPtrToWord`, `CMapWordToPtr`, and `CMapStringToPtr`. ## Syntax @@ -20,7 +22,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/cuintarray-class.md b/docs/mfc/reference/cuintarray-class.md index 6f73ded501d..fb9f1b1c845 100644 --- a/docs/mfc/reference/cuintarray-class.md +++ b/docs/mfc/reference/cuintarray-class.md @@ -4,10 +4,12 @@ title: "CUIntArray Class" ms.date: "11/04/2016" f1_keywords: ["CUIntArray", "AFXCOLL/CUIntArray", "AFXCOLL/CUIntArray::CUIntArray", "AFXCOLL/CUIntArray::Add", "AFXCOLL/CUIntArray::Append", "AFXCOLL/CUIntArray::Copy", "AFXCOLL/CUIntArray::ElementAt", "AFXCOLL/CUIntArray::FreeExtra", "AFXCOLL/CUIntArray::GetAt", "AFXCOLL/CUIntArray::GetCount", "AFXCOLL/CUIntArray::GetData", "AFXCOLL/CUIntArray::GetSize", "AFXCOLL/CUIntArray::GetUpperBound", "AFXCOLL/CUIntArray::InsertAt", "AFXCOLL/CUIntArray::IsEmpty", "AFXCOLL/CUIntArray::RemoveAll", "AFXCOLL/CUIntArray::RemoveAt", "AFXCOLL/CUIntArray::SetAt", "AFXCOLL/CUIntArray::SetAtGrow", "AFXCOLL/CUIntArray::SetSize"] helpviewer_keywords: ["CUIntArray [MFC], CUIntArray", "CUIntArray [MFC], Add", "CUIntArray [MFC], Append", "CUIntArray [MFC], Copy", "CUIntArray [MFC], ElementAt", "CUIntArray [MFC], FreeExtra", "CUIntArray [MFC], GetAt", "CUIntArray [MFC], GetCount", "CUIntArray [MFC], GetData", "CUIntArray [MFC], GetSize", "CUIntArray [MFC], GetUpperBound", "CUIntArray [MFC], InsertAt", "CUIntArray [MFC], IsEmpty", "CUIntArray [MFC], RemoveAll", "CUIntArray [MFC], RemoveAt", "CUIntArray [MFC], SetAt", "CUIntArray [MFC], SetAtGrow", "CUIntArray [MFC], SetSize"] -ms.assetid: d71f3d8f-ef9f-4e48-9b69-7782c0e2ddf7 --- # CUIntArray Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports arrays of unsigned integers. ## Syntax diff --git a/docs/mfc/reference/cuserexception-class.md b/docs/mfc/reference/cuserexception-class.md index b3dc67f0608..26387721c0a 100644 --- a/docs/mfc/reference/cuserexception-class.md +++ b/docs/mfc/reference/cuserexception-class.md @@ -4,10 +4,12 @@ title: "CUserException Class" ms.date: "11/04/2016" f1_keywords: ["CUserException"] helpviewer_keywords: ["operations [MFC], stopping", "exceptions [MFC], throwing", "CUserException class [MFC]", "errors [MFC], trapping", "operations [MFC]", "throwing exceptions [MFC], stopping user operations"] -ms.assetid: 2156ba6d-2cce-415a-9000-6f02c26fcd7d --- # CUserException Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Thrown to stop an end-user operation. ## Syntax diff --git a/docs/mfc/reference/cusertool-class.md b/docs/mfc/reference/cusertool-class.md index f664e322f8b..7701be54440 100644 --- a/docs/mfc/reference/cusertool-class.md +++ b/docs/mfc/reference/cusertool-class.md @@ -4,10 +4,12 @@ title: "CUserTool Class" ms.date: "11/04/2016" f1_keywords: ["CUserTool", "AFXUSERTOOL/CUserTool", "AFXUSERTOOL/CUserTool::CopyIconToClipboard", "AFXUSERTOOL/CUserTool::DrawToolIcon", "AFXUSERTOOL/CUserTool::GetCommand", "AFXUSERTOOL/CUserTool::GetCommandId", "AFXUSERTOOL/CUserTool::Invoke", "AFXUSERTOOL/CUserTool::Serialize", "AFXUSERTOOL/CUserTool::SetCommand", "AFXUSERTOOL/CUserTool::SetToolIcon", "AFXUSERTOOL/CUserTool::LoadDefaultIcon", "AFXUSERTOOL/CUserTool::m_strArguments", "AFXUSERTOOL/CUserTool::m_strInitialDirectory", "AFXUSERTOOL/CUserTool::m_strLabel"] helpviewer_keywords: ["CUserTool [MFC], CopyIconToClipboard", "CUserTool [MFC], DrawToolIcon", "CUserTool [MFC], GetCommand", "CUserTool [MFC], GetCommandId", "CUserTool [MFC], Invoke", "CUserTool [MFC], Serialize", "CUserTool [MFC], SetCommand", "CUserTool [MFC], SetToolIcon", "CUserTool [MFC], LoadDefaultIcon", "CUserTool [MFC], m_strArguments", "CUserTool [MFC], m_strInitialDirectory", "CUserTool [MFC], m_strLabel"] -ms.assetid: 7c287d3e-d012-488d-b4e1-aa0f83f294bb --- # CUserTool Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A user tool is a 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. ## Syntax diff --git a/docs/mfc/reference/cusertoolsmanager-class.md b/docs/mfc/reference/cusertoolsmanager-class.md index a0b94f5dc84..eaa6e767e20 100644 --- a/docs/mfc/reference/cusertoolsmanager-class.md +++ b/docs/mfc/reference/cusertoolsmanager-class.md @@ -4,10 +4,12 @@ title: "CUserToolsManager Class" ms.date: "11/04/2016" f1_keywords: ["CUserToolsManager", "AFXUSERTOOLSMANAGER/CUserToolsManager", "AFXUSERTOOLSMANAGER/CUserToolsManager::CUserToolsManager", "AFXUSERTOOLSMANAGER/CUserToolsManager::CreateNewTool", "AFXUSERTOOLSMANAGER/CUserToolsManager::FindTool", "AFXUSERTOOLSMANAGER/CUserToolsManager::GetArgumentsMenuID", "AFXUSERTOOLSMANAGER/CUserToolsManager::GetDefExt", "AFXUSERTOOLSMANAGER/CUserToolsManager::GetFilter", "AFXUSERTOOLSMANAGER/CUserToolsManager::GetInitialDirMenuID", "AFXUSERTOOLSMANAGER/CUserToolsManager::GetMaxTools", "AFXUSERTOOLSMANAGER/CUserToolsManager::GetToolsEntryCmd", "AFXUSERTOOLSMANAGER/CUserToolsManager::GetUserTools", "AFXUSERTOOLSMANAGER/CUserToolsManager::InvokeTool", "AFXUSERTOOLSMANAGER/CUserToolsManager::IsUserToolCmd", "AFXUSERTOOLSMANAGER/CUserToolsManager::LoadState", "AFXUSERTOOLSMANAGER/CUserToolsManager::MoveToolDown", "AFXUSERTOOLSMANAGER/CUserToolsManager::MoveToolUp", "AFXUSERTOOLSMANAGER/CUserToolsManager::RemoveTool", "AFXUSERTOOLSMANAGER/CUserToolsManager::SaveState", "AFXUSERTOOLSMANAGER/CUserToolsManager::SetDefExt", "AFXUSERTOOLSMANAGER/CUserToolsManager::SetFilter"] helpviewer_keywords: ["CUserToolsManager [MFC], CUserToolsManager", "CUserToolsManager [MFC], CreateNewTool", "CUserToolsManager [MFC], FindTool", "CUserToolsManager [MFC], GetArgumentsMenuID", "CUserToolsManager [MFC], GetDefExt", "CUserToolsManager [MFC], GetFilter", "CUserToolsManager [MFC], GetInitialDirMenuID", "CUserToolsManager [MFC], GetMaxTools", "CUserToolsManager [MFC], GetToolsEntryCmd", "CUserToolsManager [MFC], GetUserTools", "CUserToolsManager [MFC], InvokeTool", "CUserToolsManager [MFC], IsUserToolCmd", "CUserToolsManager [MFC], LoadState", "CUserToolsManager [MFC], MoveToolDown", "CUserToolsManager [MFC], MoveToolUp", "CUserToolsManager [MFC], RemoveTool", "CUserToolsManager [MFC], SaveState", "CUserToolsManager [MFC], SetDefExt", "CUserToolsManager [MFC], SetFilter"] -ms.assetid: bdfa37ae-efca-4616-abb5-9d0dcd2d335b --- # CUserToolsManager Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + 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. ## Syntax diff --git a/docs/mfc/reference/cview-class.md b/docs/mfc/reference/cview-class.md index 28e7c3215b8..e9a3113ea03 100644 --- a/docs/mfc/reference/cview-class.md +++ b/docs/mfc/reference/cview-class.md @@ -4,10 +4,12 @@ title: "CView Class" ms.date: "11/04/2016" f1_keywords: ["CView", "AFXWIN/CView", "AFXWIN/CView::CView", "AFXWIN/CView::DoPreparePrinting", "AFXWIN/CView::GetDocument", "AFXWIN/CView::IsSelected", "AFXWIN/CView::OnDragEnter", "AFXWIN/CView::OnDragLeave", "AFXWIN/CView::OnDragOver", "AFXWIN/CView::OnDragScroll", "AFXWIN/CView::OnDrop", "AFXWIN/CView::OnDropEx", "AFXWIN/CView::OnInitialUpdate", "AFXWIN/CView::OnPrepareDC", "AFXWIN/CView::OnScroll", "AFXWIN/CView::OnScrollBy", "AFXWIN/CView::OnActivateFrame", "AFXWIN/CView::OnActivateView", "AFXWIN/CView::OnBeginPrinting", "AFXWIN/CView::OnDraw", "AFXWIN/CView::OnEndPrinting", "AFXWIN/CView::OnEndPrintPreview", "AFXWIN/CView::OnPreparePrinting", "AFXWIN/CView::OnPrint", "AFXWIN/CView::OnUpdate"] helpviewer_keywords: ["CView [MFC], CView", "CView [MFC], DoPreparePrinting", "CView [MFC], GetDocument", "CView [MFC], IsSelected", "CView [MFC], OnDragEnter", "CView [MFC], OnDragLeave", "CView [MFC], OnDragOver", "CView [MFC], OnDragScroll", "CView [MFC], OnDrop", "CView [MFC], OnDropEx", "CView [MFC], OnInitialUpdate", "CView [MFC], OnPrepareDC", "CView [MFC], OnScroll", "CView [MFC], OnScrollBy", "CView [MFC], OnActivateFrame", "CView [MFC], OnActivateView", "CView [MFC], OnBeginPrinting", "CView [MFC], OnDraw", "CView [MFC], OnEndPrinting", "CView [MFC], OnEndPrintPreview", "CView [MFC], OnPreparePrinting", "CView [MFC], OnPrint", "CView [MFC], OnUpdate"] -ms.assetid: 9cff3c56-7564-416b-b9a4-71a9254ed755 --- # `CView` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the basic functionality for user-defined view classes. ## Syntax @@ -494,7 +496,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/cvslistbox-class.md b/docs/mfc/reference/cvslistbox-class.md index 45cbc0e8068..68cf0b67cc9 100644 --- a/docs/mfc/reference/cvslistbox-class.md +++ b/docs/mfc/reference/cvslistbox-class.md @@ -4,10 +4,12 @@ title: "CVSListBox Class" ms.date: "11/19/2018" f1_keywords: ["CVSListBox", "AFXVSLISTBOX/CVSListBox", "AFXVSLISTBOX/CVSListBox::CVSListBox", "AFXVSLISTBOX/CVSListBox::AddItem", "AFXVSLISTBOX/CVSListBox::EditItem", "AFXVSLISTBOX/CVSListBox::GetCount", "AFXVSLISTBOX/CVSListBox::GetItemData", "AFXVSLISTBOX/CVSListBox::GetItemText", "AFXVSLISTBOX/CVSListBox::GetSelItem", "AFXVSLISTBOX/CVSListBox::RemoveItem", "AFXVSLISTBOX/CVSListBox::SelectItem", "AFXVSLISTBOX/CVSListBox::SetItemData", "AFXVSLISTBOX/CVSListBox::GetListHwnd"] helpviewer_keywords: ["CVSListBox [MFC], CVSListBox", "CVSListBox [MFC], AddItem", "CVSListBox [MFC], EditItem", "CVSListBox [MFC], GetCount", "CVSListBox [MFC], GetItemData", "CVSListBox [MFC], GetItemText", "CVSListBox [MFC], GetSelItem", "CVSListBox [MFC], RemoveItem", "CVSListBox [MFC], SelectItem", "CVSListBox [MFC], SetItemData", "CVSListBox [MFC], GetListHwnd"] -ms.assetid: c79be7b4-46ed-4af8-a41e-68962782d8ef --- # CVSListBox Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `CVSListBox` class supports an editable list control. ## Syntax diff --git a/docs/mfc/reference/cwaitcursor-class.md b/docs/mfc/reference/cwaitcursor-class.md index 7a62508db91..36fd2f3f99d 100644 --- a/docs/mfc/reference/cwaitcursor-class.md +++ b/docs/mfc/reference/cwaitcursor-class.md @@ -4,10 +4,12 @@ title: "CWaitCursor Class" ms.date: "11/04/2016" f1_keywords: ["CWaitCursor", "AFXWIN/CWaitCursor", "AFXWIN/CWaitCursor::CWaitCursor", "AFXWIN/CWaitCursor::Restore"] helpviewer_keywords: ["CWaitCursor [MFC], CWaitCursor", "CWaitCursor [MFC], Restore"] -ms.assetid: 5dfae2ff-d7b6-4383-b0ad-91e0868c67b3 --- # CWaitCursor Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides a one-line way to show a wait cursor, which is usually displayed as an hourglass, while you're doing a lengthy operation. ## Syntax diff --git a/docs/mfc/reference/cwinapp-class.md b/docs/mfc/reference/cwinapp-class.md index 21cdc641e93..977fe4b8cc9 100644 --- a/docs/mfc/reference/cwinapp-class.md +++ b/docs/mfc/reference/cwinapp-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The base class from which you derive a Windows application object. ## Syntax @@ -897,7 +899,8 @@ Taskbar interaction means that MDI application displays the content of MDI child Loads the cursor resource named by *lpszResourceName* or specified by *nIDResource* from the current executable file. ``` -HCURSOR LoadCursor(LPCTSTR lpszResourceName) const; HCURSOR LoadCursor(UINT nIDResource) const; +HCURSOR LoadCursor(LPCTSTR lpszResourceName) const; +HCURSOR LoadCursor(UINT nIDResource) const; ``` ### Parameters @@ -927,7 +930,8 @@ Use the [LoadStandardCursor](#loadstandardcursor) or [LoadOEMCursor](#loadoemcur Loads the icon resource named by *lpszResourceName* or specified by *nIDResource* from the executable file. ``` -HICON LoadIcon(LPCTSTR lpszResourceName) const; HICON LoadIcon(UINT nIDResource) const; +HICON LoadIcon(LPCTSTR lpszResourceName) const; +HICON LoadIcon(UINT nIDResource) const; ``` ### Parameters @@ -962,7 +966,7 @@ HCURSOR LoadOEMCursor(UINT nIDCursor) const; ### Parameters *nIDCursor*
-An **OCR_** manifest constant identifier that specifies a predefined Windows cursor. You must have `#define OEMRESOURCE` before `#include \` to gain access to the **OCR_** constants in WINDOWS.H. +An **OCR_** manifest constant identifier that specifies a predefined Windows cursor. You must have `#define OEMRESOURCE` before `#include ` to gain access to the **OCR_** constants in WINDOWS.H. ### Return Value @@ -975,7 +979,7 @@ Use the `LoadOEMCursor` or [LoadStandardCursor](#loadstandardcursor) member func ### Example [!code-cpp[NVC_MFCWindowing#45](../../mfc/reference/codesnippet/cpp/cwinapp-class_12.h)] - +  [!code-cpp[NVC_MFCWindowing#46](../../mfc/reference/codesnippet/cpp/cwinapp-class_13.cpp)] ## CWinApp::LoadOEMIcon @@ -989,7 +993,7 @@ HICON LoadOEMIcon(UINT nIDIcon) const; ### Parameters *nIDIcon*
-An **OIC_** manifest constant identifier that specifies a predefined Windows icon. You must have `#define OEMRESOURCE` before `#include \` to access the **OIC_** constants in WINDOWS.H. +An **OIC_** manifest constant identifier that specifies a predefined Windows icon. You must have `#define OEMRESOURCE` before `#include ` to access the **OIC_** constants in WINDOWS.H. ### Return Value @@ -1386,7 +1390,7 @@ See [Technical Note 22](../../mfc/tn022-standard-commands-implementation.md) for ### Example [!code-cpp[NVC_MFCWindowing#49](../../mfc/reference/codesnippet/cpp/cwinapp-class_25.cpp)] - +  [!code-cpp[NVC_MFCWindowing#50](../../mfc/reference/codesnippet/cpp/cwinapp-class_26.cpp)] ## CWinApp::OnFileOpen @@ -1406,7 +1410,7 @@ For information on default behavior and guidance on how to override this member ### Example [!code-cpp[NVC_MFCWindowing#49](../../mfc/reference/codesnippet/cpp/cwinapp-class_25.cpp)] - +  [!code-cpp[NVC_MFCWindowing#50](../../mfc/reference/codesnippet/cpp/cwinapp-class_26.cpp)] ## CWinApp::OnFilePrintSetup @@ -1426,7 +1430,7 @@ For information on default behavior and guidance on how to override this member ### Example [!code-cpp[NVC_MFCWindowing#49](../../mfc/reference/codesnippet/cpp/cwinapp-class_25.cpp)] - +  [!code-cpp[NVC_MFCWindowing#50](../../mfc/reference/codesnippet/cpp/cwinapp-class_26.cpp)] ## CWinApp::OnHelp @@ -1535,7 +1539,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 +1625,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 +1696,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 +1940,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 42271b822ef..6ddbfc30372 100644 --- a/docs/mfc/reference/cwinappex-class.md +++ b/docs/mfc/reference/cwinappex-class.md @@ -1,11 +1,14 @@ --- -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 + +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. `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 +16,7 @@ For more detail, see the source code located in the `mfc` folder of your Visual ## Syntax -``` +```cpp class CWinAppEx : public CWinApp ``` @@ -402,7 +405,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 +973,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 19f890b5cef..c47bff917d7 100644 --- a/docs/mfc/reference/cwindowdc-class.md +++ b/docs/mfc/reference/cwindowdc-class.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Derived from `CDC`. ## Syntax @@ -32,7 +34,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/cwinformscontrol-class.md b/docs/mfc/reference/cwinformscontrol-class.md index 78663935bdc..1d3e5e58e4a 100644 --- a/docs/mfc/reference/cwinformscontrol-class.md +++ b/docs/mfc/reference/cwinformscontrol-class.md @@ -4,10 +4,12 @@ title: "CWinFormsControl Class" ms.date: "11/04/2016" f1_keywords: ["CWinFormsControl", "AFXWINFORMS/CWinFormsControl", "AFXWINFORMS/CWinFormsControl::CWinFormsControl", "AFXWINFORMS/CWinFormsControl::CreateManagedControl", "AFXWINFORMS/CWinFormsControl::GetControl", "AFXWINFORMS/CWinFormsControl::GetControlHandle"] helpviewer_keywords: ["CWinFormsControl [MFC], CWinFormsControl", "CWinFormsControl [MFC], CreateManagedControl", "CWinFormsControl [MFC], GetControl", "CWinFormsControl [MFC], GetControlHandle"] -ms.assetid: 6406dd7b-fb89-4a18-ac3a-c010d6b6289a --- # CWinFormsControl Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the basic functionality for hosting of a Windows Forms control. ## Syntax diff --git a/docs/mfc/reference/cwinformsdialog-class.md b/docs/mfc/reference/cwinformsdialog-class.md index 89e9ab38315..f24797163f1 100644 --- a/docs/mfc/reference/cwinformsdialog-class.md +++ b/docs/mfc/reference/cwinformsdialog-class.md @@ -4,10 +4,12 @@ title: "CWinFormsDialog Class" ms.date: "03/27/2019" f1_keywords: ["CWinFormsDialog", "AFXWINFORMS/CWinFormsDialog", "AFXWINFORMS/CWinFormsDialog::CWinFormsDialog", "AFXWINFORMS/CWinFormsDialog::GetControl", "AFXWINFORMS/CWinFormsDialog::GetControlHandle", "AFXWINFORMS/CWinFormsDialog::OnInitDialog"] helpviewer_keywords: ["CWinFormsDialog [MFC], CWinFormsDialog", "CWinFormsDialog [MFC], GetControl", "CWinFormsDialog [MFC], GetControlHandle", "CWinFormsDialog [MFC], OnInitDialog"] -ms.assetid: e3cec000-a578-448e-b06a-8af256312f61 --- # CWinFormsDialog Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A wrapper for an MFC dialog class that hosts a Windows Forms user control. ## Syntax diff --git a/docs/mfc/reference/cwinformsview-class.md b/docs/mfc/reference/cwinformsview-class.md index b681ae885ad..549c6236de3 100644 --- a/docs/mfc/reference/cwinformsview-class.md +++ b/docs/mfc/reference/cwinformsview-class.md @@ -4,10 +4,12 @@ title: "CWinFormsView Class" ms.date: "11/04/2016" f1_keywords: ["CWinFormsView", "AFXWINFORMS/CWinFormsView", "AFXWINFORMS/CWinFormsView::CWinFormsView", "AFXWINFORMS/CWinFormsView::GetControl"] helpviewer_keywords: ["CWinFormsView [MFC], CWinFormsView", "CWinFormsView [MFC], GetControl"] -ms.assetid: d597e397-6529-469b-88f5-7f65a6b9e895 --- # CWinFormsView Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides generic functionality for hosting of a Windows Forms control as an MFC view. ## Syntax @@ -70,7 +72,7 @@ A pointer to the data type of the Windows Forms user control. In the following example, the `CUserView` class inherits from `CWinFormsView` and passes the type of `UserControl1` to the `CWinFormsView` constructor. `UserControl1` is a custom-built control in ControlLibrary1.dll. [!code-cpp[NVC_MFC_Managed#1](../../mfc/reference/codesnippet/cpp/cwinformsview-class_1.h)] - +  [!code-cpp[NVC_MFC_Managed#2](../../mfc/reference/codesnippet/cpp/cwinformsview-class_2.cpp)] ## CWinFormsView::GetControl diff --git a/docs/mfc/reference/cwinthread-class.md b/docs/mfc/reference/cwinthread-class.md index 02e9bfbfa88..4cc52e29c7b 100644 --- a/docs/mfc/reference/cwinthread-class.md +++ b/docs/mfc/reference/cwinthread-class.md @@ -4,10 +4,12 @@ title: "CWinThread Class" ms.date: "11/04/2016" f1_keywords: ["CWinThread", "AFXWIN/CWinThread", "AFXWIN/CWinThread::CWinThread", "AFXWIN/CWinThread::CreateThread", "AFXWIN/CWinThread::ExitInstance", "AFXWIN/CWinThread::GetMainWnd", "AFXWIN/CWinThread::GetThreadPriority", "AFXWIN/CWinThread::InitInstance", "AFXWIN/CWinThread::IsIdleMessage", "AFXWIN/CWinThread::OnIdle", "AFXWIN/CWinThread::PostThreadMessage", "AFXWIN/CWinThread::PreTranslateMessage", "AFXWIN/CWinThread::ProcessMessageFilter", "AFXWIN/CWinThread::ProcessWndProcException", "AFXWIN/CWinThread::PumpMessage", "AFXWIN/CWinThread::ResumeThread", "AFXWIN/CWinThread::Run", "AFXWIN/CWinThread::SetThreadPriority", "AFXWIN/CWinThread::SuspendThread", "AFXWIN/CWinThread::m_bAutoDelete", "AFXWIN/CWinThread::m_hThread", "AFXWIN/CWinThread::m_nThreadID", "AFXWIN/CWinThread::m_pActiveWnd", "AFXWIN/CWinThread::m_pMainWnd"] helpviewer_keywords: ["CWinThread [MFC], CWinThread", "CWinThread [MFC], CreateThread", "CWinThread [MFC], ExitInstance", "CWinThread [MFC], GetMainWnd", "CWinThread [MFC], GetThreadPriority", "CWinThread [MFC], InitInstance", "CWinThread [MFC], IsIdleMessage", "CWinThread [MFC], OnIdle", "CWinThread [MFC], PostThreadMessage", "CWinThread [MFC], PreTranslateMessage", "CWinThread [MFC], ProcessMessageFilter", "CWinThread [MFC], ProcessWndProcException", "CWinThread [MFC], PumpMessage", "CWinThread [MFC], ResumeThread", "CWinThread [MFC], Run", "CWinThread [MFC], SetThreadPriority", "CWinThread [MFC], SuspendThread", "CWinThread [MFC], m_bAutoDelete", "CWinThread [MFC], m_hThread", "CWinThread [MFC], m_nThreadID", "CWinThread [MFC], m_pActiveWnd", "CWinThread [MFC], m_pMainWnd"] -ms.assetid: 10cdc294-4057-4e76-ac7c-a8967a89af0b --- # `CWinThread` Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Represents a thread of execution within an application. ## Syntax diff --git a/docs/mfc/reference/cwnd-class.md b/docs/mfc/reference/cwnd-class.md index c419c24c6b4..40d6e732502 100644 --- a/docs/mfc/reference/cwnd-class.md +++ b/docs/mfc/reference/cwnd-class.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: CWnd Class" title: "CWnd Class" -ms.date: "8/25/2021" +description: "Learn more about: 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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides the base functionality of all window classes in the Microsoft Foundation Class Library. ## Syntax @@ -711,9 +713,9 @@ Nonzero if successful; otherwise 0. This example shows how to use `Attach` and `Detach` to map to the MDI client window. [!code-cpp[NVC_MFCWindowing#67](../../mfc/reference/codesnippet/cpp/cwnd-class_2.h)] - +  [!code-cpp[NVC_MFCWindowing#68](../../mfc/reference/codesnippet/cpp/cwnd-class_3.cpp)] - +  [!code-cpp[NVC_MFCWindowing#69](../../mfc/reference/codesnippet/cpp/cwnd-class_4.cpp)] ## `CWnd::BeginModalState` @@ -1025,7 +1027,8 @@ The `CWnd`* that is returned may be temporary and shouldn't be stored for later Converts the client coordinates of a given point or rectangle on the display to screen coordinates. ```cpp -void ClientToScreen(LPPOINT lpPoint) const; void ClientToScreen(LPRECT lpRect) const; +void ClientToScreen(LPPOINT lpPoint) const; +void ClientToScreen(LPRECT lpRect) const; ``` ### Parameters @@ -1246,7 +1249,7 @@ Points to a [`POINT` structure](/windows/win32/api/windef/ns-windef-point) or `C *`pSize`*
Points to a [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure or `CSize` object that contains the control's size -*`pParentWnd*`
+*`pParentWnd`*
Specifies the control's parent window. It must not be `NULL`. *`nID`*
@@ -2059,7 +2062,7 @@ The default tool tips provided for your windows by `EnableToolTips` do not have ### Example [!code-cpp[NVC_MFCWindowing#91](../../mfc/reference/codesnippet/cpp/cwnd-class_30.cpp)] - +  [!code-cpp[NVC_MFCWindowing#92](../../mfc/reference/codesnippet/cpp/cwnd-class_31.cpp)] ## `CWnd::EnableTrackingToolTips` @@ -2320,7 +2323,7 @@ BOOL FlashWindowEx( ### Parameters -*`dwFlags*`
+*`dwFlags`*
Specifies the flash status. For a complete list of values, see the [`FLASHWINFO`](/windows/win32/api/winuser/ns-winuser-flashwinfo) structure. *`uCount`*
@@ -4108,7 +4111,7 @@ CWnd* GetWindow(UINT nCmd) const; ### Parameters -*`nCmd*`
+*`nCmd`*
Specifies the relationship between `CWnd` and the returned window. It can take one of the following values: - `GW_CHILD` Identifies the `CWnd` first child window. @@ -4863,10 +4866,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 @@ -10175,7 +10178,8 @@ By default, `ContinueModal` returns `FALSE` after `EndModalLoop` is called. Retu Converts the screen coordinates of a given point or rectangle on the display to client coordinates. ```cpp -void ScreenToClient(LPPOINT lpPoint) const; void ScreenToClient(LPRECT lpRect) const; +void ScreenToClient(LPPOINT lpPoint) const; +void ScreenToClient(LPRECT lpRect) const; ``` ### Parameters diff --git a/docs/mfc/reference/cwordarray-class.md b/docs/mfc/reference/cwordarray-class.md index 76e6c6e25ab..52941cdfd84 100644 --- a/docs/mfc/reference/cwordarray-class.md +++ b/docs/mfc/reference/cwordarray-class.md @@ -4,10 +4,12 @@ title: "CWordArray Class" ms.date: "09/07/2019" f1_keywords: ["CWordArray", "AFXCOLL/CWordArray", "AFXCOLL/CWordArray::CWordArray", "AFXCOLL/CWordArray::Add", "AFXCOLL/CWordArray::Append", "AFXCOLL/CWordArray::Copy", "AFXCOLL/CWordArray::ElementAt", "AFXCOLL/CWordArray::FreeExtra", "AFXCOLL/CWordArray::GetAt", "AFXCOLL/CWordArray::GetCount", "AFXCOLL/CWordArray::GetData", "AFXCOLL/CWordArray::GetSize", "AFXCOLL/CWordArray::GetUpperBound", "AFXCOLL/CWordArray::InsertAt", "AFXCOLL/CWordArray::IsEmpty", "AFXCOLL/CWordArray::RemoveAll", "AFXCOLL/CWordArray::RemoveAt", "AFXCOLL/CWordArray::SetAt", "AFXCOLL/CWordArray::SetAtGrow", "AFXCOLL/CWordArray::SetSize"] helpviewer_keywords: ["CWordArray [MFC], CWordArray", "CWordArray [MFC], Add", "CWordArray [MFC], Append", "CWordArray [MFC], Copy", "CWordArray [MFC], ElementAt", "CWordArray [MFC], FreeExtra", "CWordArray [MFC], GetAt", "CWordArray [MFC], GetCount", "CWordArray [MFC], GetData", "CWordArray [MFC], GetSize", "CWordArray [MFC], GetUpperBound", "CWordArray [MFC], InsertAt", "CWordArray [MFC], IsEmpty", "CWordArray [MFC], RemoveAll", "CWordArray [MFC], RemoveAt", "CWordArray [MFC], SetAt", "CWordArray [MFC], SetAtGrow", "CWordArray [MFC], SetSize"] -ms.assetid: 2ba2c194-2c6c-40ff-9db4-e9dbe57e1f57 --- # CWordArray Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Supports arrays of 16-bit words. ## Syntax diff --git a/docs/mfc/reference/dao-database-engine-initialization-and-termination.md b/docs/mfc/reference/dao-database-engine-initialization-and-termination.md index ab7e957bd30..937431e7009 100644 --- a/docs/mfc/reference/dao-database-engine-initialization-and-termination.md +++ b/docs/mfc/reference/dao-database-engine-initialization-and-termination.md @@ -3,10 +3,12 @@ description: "Learn more about: DAO Database Engine Initialization and Terminati title: "DAO Database Engine Initialization and Termination" ms.date: "09/17/2019" helpviewer_keywords: ["DAO (Data Access Objects), termination", "DAO (Data Access Objects), initialization"] -ms.assetid: a7edf31c-e7c2-4f3e-aada-63c3e48781da --- # DAO Database Engine Initialization and Termination +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. When using MFC DAO objects, the DAO database engine must first be initialized and then terminated before your application or DLL quits. Two functions, `AfxDaoInit` and `AfxDaoTerm`, perform these tasks. ### DAO Database Engine Initialization and Termination @@ -21,7 +23,6 @@ DAO is used with Access databases and is supported through Office 2013. DAO 3.6 This function initializes the DAO database engine. ``` - void AfxDaoInit(); throw(CDaoException*); @@ -42,7 +43,6 @@ For related information, and for an example of calling `AfxDaoInit`, see [Techni This function terminates the DAO database engine. ``` - void AfxDaoTerm(); ``` diff --git a/docs/mfc/reference/data-types-mfc.md b/docs/mfc/reference/data-types-mfc.md index d1790212f18..d8c7488a1cb 100644 --- a/docs/mfc/reference/data-types-mfc.md +++ b/docs/mfc/reference/data-types-mfc.md @@ -1,24 +1,25 @@ --- -description: "Learn more about: Data Types (MFC)" title: "Data Types (MFC)" -ms.date: "11/04/2016" +description: "Learn more about: Data Types (MFC)" +ms.date: 11/04/2016 f1_keywords: ["LPCRECT", "POSITION"] helpviewer_keywords: ["LPCRECT data type [MFC]", "WPARAM data type [MFC]", "data types [MFC], MFC", "LRESULT [MFC]", "POSITION data type [MFC]", "UINT [MFC]", "LPVOID data type [MFC]", "COLORREF [MFC]", "LPCTSTR [MFC]", "LPSTR [MFC]", "DWORD operator [MFC]", "WORD data type [MFC]", "LPTSTR [MFC]", "BYTE data type (Windows)", "Long data type [MFC], Windows types", "Boolean data type [MFC], supported data types", "LPARAM data type [MFC]", "LPCSTR [MFC]"] -ms.assetid: 8954848b-2c01-4a4f-abf5-ee55f6a05eeb --- # Data Types (MFC) -This topic lists the data types most commonly used in the Microsoft Foundation Class Library. Most of the data types are the same as those in the Platform Software Development Kit (SDK), while others are unique to MFC. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. -For information about the data types used in both the Windows SDK and MFC, see [Windows Data Types](/windows/win32/WinProg/windows-data-types). +This topic lists the data types most commonly used in the Microsoft Foundation Class (MFC) Library. Most of the data types are the same as those in the Platform Software Development Kit (SDK), while others are unique to MFC. -Data types unique to the Microsoft Foundation Class Library include the following: +For information about the data types used in both the Windows SDK and MFC, see [Windows Data Types](/windows/win32/WinProg/windows-data-types). -- POSITION A value used to denote the position of an element in a collection; used by MFC collection classes. +Data types unique to MFC include the following: -- LPCRECT A 32-bit pointer to a constant (nonmodifiable) `RECT` structure. +- `POSITION` - A value used to denote the position of an element in a collection; used by MFC collection classes. +- `LPCRECT` - A 32-bit pointer to a constant (nonmodifiable) [`RECT`](/windows/win32/api/windef/ns-windef-rect) structure. ## See also -[Class Overview](../../mfc/class-library-overview.md)
-[Macros and Globals](../../mfc/reference/mfc-macros-and-globals.md) +[Class Overview](../class-library-overview.md)\ +[Macros and Globals](mfc-macros-and-globals.md) diff --git a/docs/mfc/reference/database-macros-and-globals.md b/docs/mfc/reference/database-macros-and-globals.md index 0a51a55db66..b210e2a8037 100644 --- a/docs/mfc/reference/database-macros-and-globals.md +++ b/docs/mfc/reference/database-macros-and-globals.md @@ -4,10 +4,12 @@ title: "Database Macros and Globals" ms.date: "11/04/2016" f1_keywords: ["AFXDB/AFX_ODBC_CALL", "AFXDB/AFX_SQL_ASYNC", "AFXDB/AFX_SQL_SYNC", "AFXDB/AfxGetHENV"] helpviewer_keywords: ["global database functions [MFC]", "database macros [MFC]", "database globals [MFC]", "global functions [MFC], database functions", "macros [MFC], MFC database"] -ms.assetid: 5b9b9e61-1cf9-4345-9f29-3807dd466488 --- # Database Macros and Globals +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The macros and globals listed below apply to ODBC-based database applications. They are not used with DAO-based applications. Before MFC 4.2, the macros `AFX_SQL_ASYNC` and `AFX_SQL_SYNC` gave asynchronous operations an opportunity to yield time to other processes. Beginning with MFC 4.2, the implementation of these macros changed because the MFC ODBC classes used only synchronous operations. The macro `AFX_ODBC_CALL` was new to MFC 4.2. diff --git a/docs/mfc/reference/database-support-mfc-application-wizard.md b/docs/mfc/reference/database-support-mfc-application-wizard.md index 8430be65389..317ec1832c8 100644 --- a/docs/mfc/reference/database-support-mfc-application-wizard.md +++ b/docs/mfc/reference/database-support-mfc-application-wizard.md @@ -4,10 +4,12 @@ title: "Database Support, MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.database"] helpviewer_keywords: ["MFC Application Wizard, database support"] -ms.assetid: 9ddf4558-fd41-4ac7-8d9b-c93d9c68ab59 --- # Database Support, MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This page provides options that allow you to specify the level of database support (plus a data source, if necessary) for your project. - **Database support** diff --git a/docs/mfc/reference/ddx-dhtml-helper-macros.md b/docs/mfc/reference/ddx-dhtml-helper-macros.md index cc1d4e7bebf..597dbbc19ab 100644 --- a/docs/mfc/reference/ddx-dhtml-helper-macros.md +++ b/docs/mfc/reference/ddx-dhtml-helper-macros.md @@ -4,10 +4,12 @@ title: "DDX_DHtml Helper Macros" ms.date: "11/04/2016" f1_keywords: ["AFXDHTML/DDX_DHtml_ElementValue", "AFXDHTML/DDX_DHtml_ElementInnerText", "AFXDHTML/DDX_DHtml_ElementInnerHtml", "AFXDHTML/DDX_DHtml_Anchor_Href", "AFXDHTML/DDX_DHtml_Anchor_Target", "AFXDHTML/DDX_DHtml_Img_Src", "AFXDHTML/DDX_DHtml_Frame_Src", "AFXDHTML/DDX_DHtml_IFrame_Src"] helpviewer_keywords: ["macros [MFC], exchanging data with HMTL pages", "DDX macros [MFC]", "HTML pages [MFC], helper macros", "DDX (dialog data exchange), DHtml helper macros", "macros [MFC], DDX_DHtml helpers"] -ms.assetid: c46302d2-ea43-4fea-bfc2-6f590d99f267 --- # DDX_DHtml Helper Macros +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The DDX_DHtml helper macros allow easy access to the commonly used properties of controls on an HTML page. ### Data Exchange Macros diff --git a/docs/mfc/reference/declaring-a-variable-based-on-your-new-control-class.md b/docs/mfc/reference/declaring-a-variable-based-on-your-new-control-class.md index d911fb2a338..9d0cd90dd1f 100644 --- a/docs/mfc/reference/declaring-a-variable-based-on-your-new-control-class.md +++ b/docs/mfc/reference/declaring-a-variable-based-on-your-new-control-class.md @@ -4,10 +4,12 @@ title: "Declaring a Variable Based on Your New Control Class" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.classes.control.variable"] helpviewer_keywords: ["variables [MFC], control classes", "control classes [MFC], variables", "classes [MFC], declaring variables based on"] -ms.assetid: 5722dc38-c0eb-40bd-93da-67a808140d03 --- # Declaring a Variable Based on Your New Control Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Once you have created an MFC control class, you can declare a variable based on it. To provide a context for the new variable, you must open the dialog editor and edit the dialog box in which you want to use your reusable control. Also, the dialog box must already have a class associated with it. For information on using the dialog editor, see [Dialog Editor](../../windows/dialog-editor.md). ### To declare a variable based on your reusable class diff --git a/docs/mfc/reference/defining-a-message-handler-for-a-reflected-message.md b/docs/mfc/reference/defining-a-message-handler-for-a-reflected-message.md index 7e3b2efc820..cc57d41b8b6 100644 --- a/docs/mfc/reference/defining-a-message-handler-for-a-reflected-message.md +++ b/docs/mfc/reference/defining-a-message-handler-for-a-reflected-message.md @@ -4,10 +4,12 @@ title: "Defining a Message Handler for a Reflected Message" ms.date: "09/07/2019" f1_keywords: ["vc.codewiz.defining.msg.msghandler"] helpviewer_keywords: ["messages [MFC], reflected", "message handling [MFC], reflected messages"] -ms.assetid: 5a403528-58c5-46e7-90d5-4a77f0ab9b9c --- # Defining a Message Handler for a Reflected Message +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Once you have created a new MFC control class, you can define message handlers for it. Reflected message handlers allow your control class to handle its own messages before the message is received by the parent. You can use the MFC [CWnd::SendMessage](../../mfc/reference/cwnd-class.md#sendmessage) function to send messages from your control to a parent window. With this functionality you could, for example, create a list box that will redraw itself rather than relying on the parent window to do so (owner drawn). For more information on reflected messages, see [Handling Reflected Messages](../../mfc/handling-reflected-messages.md). diff --git a/docs/mfc/reference/delegate-and-interface-maps.md b/docs/mfc/reference/delegate-and-interface-maps.md index f190e37f4ee..2aa03516318 100644 --- a/docs/mfc/reference/delegate-and-interface-maps.md +++ b/docs/mfc/reference/delegate-and-interface-maps.md @@ -1,12 +1,14 @@ --- -description: "Learn more about: Delegate and interface map macros" title: "Delegate and Interface Map Macros (MFC)" -ms.date: "03/30/2017" +description: "Learn more about: Delegate and interface map macros" +ms.date: 03/30/2017 helpviewer_keywords: ["delegate map macros [MFC]", "event map macros [MFC]", "interface map macros [MFC]"] -ms.assetid: 3840e642-ff7d-4bdc-998b-c7d8fc50890e --- # Delegate and interface map macros +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC supports these macros for delegate and interface maps: |Name|Description| @@ -215,8 +217,10 @@ INTERFACE_PART( theClass, iid, localClass) *theClass*
The name of the class that contains the interface map. + *iid*
The IID that is to be mapped to the embedded class. + *localClass*
The name of the local class. diff --git a/docs/mfc/reference/details-of-atl-support-added-by-the-atl-wizard.md b/docs/mfc/reference/details-of-atl-support-added-by-the-atl-wizard.md index 75372cba8f4..938589b2b95 100644 --- a/docs/mfc/reference/details-of-atl-support-added-by-the-atl-wizard.md +++ b/docs/mfc/reference/details-of-atl-support-added-by-the-atl-wizard.md @@ -4,13 +4,16 @@ title: "Details of ATL Support Added by the ATL Wizard" ms.date: "08/20/2019" f1_keywords: ["vc.codewiz.atl.support"] helpviewer_keywords: ["MFC, ATL support", "ATL, MFC projects"] -ms.assetid: aa66bad0-008f-4886-94c1-2a0a0d04bce4 --- + # Details of ATL Support Added by the ATL Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library and Active Template Library (ATL) continue to be supported. However, we're no longer adding features or updating the documentation. + ::: moniker range=">=msvc-160" -When you [add ATL support to an existing MFC executable or DLL](../../mfc/reference/adding-atl-support-to-your-mfc-project.md), Visual Studio adds a header file called *framework.h* by default, which contains `#include` and `#define` preprocessor directives to enable the use of ATL in your project. No additional files or classes are added, as was done in previous versions of Visual Studio. +When you [add ATL support to an existing MFC executable or DLL](../../mfc/reference/adding-atl-support-to-your-mfc-project.md), Visual Studio adds a header file called `framework.h` by default, which contains `#include` and `#define` preprocessor directives to enable the use of ATL in your project. No additional files or classes are added, as was done in previous versions of Visual Studio. ::: moniker-end diff --git a/docs/mfc/reference/dhtml-editing-command-maps.md b/docs/mfc/reference/dhtml-editing-command-maps.md index 817b045cfc7..eb8672332d6 100644 --- a/docs/mfc/reference/dhtml-editing-command-maps.md +++ b/docs/mfc/reference/dhtml-editing-command-maps.md @@ -2,10 +2,12 @@ description: "Learn more about: DHTML Editing Command Maps" title: "DHTML Editing Command Maps" ms.date: "11/04/2016" -ms.assetid: c1b49876-039e-4a26-bb24-ea98ccf254a1 --- # DHTML Editing Command Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following macros can be used to map DHTML editing commands in [CHtmlEditView](../../mfc/reference/chtmleditview-class.md)-derived classes. For an example of their use, see [HTMLEdit Sample](../../overview/visual-cpp-samples.md). ### DHTML Editing Command Map Macros diff --git a/docs/mfc/reference/dhtml-event-maps.md b/docs/mfc/reference/dhtml-event-maps.md index b613eca890f..edc049eefaa 100644 --- a/docs/mfc/reference/dhtml-event-maps.md +++ b/docs/mfc/reference/dhtml-event-maps.md @@ -4,10 +4,12 @@ title: "DHTML Event Maps" ms.date: "11/04/2016" f1_keywords: ["vc.macros.shared"] helpviewer_keywords: ["event map macros [MFC]", "DHTML [MFC], event map macros", "macros [MFC], DHTML event map", "DHTML events [MFC], event map", "DHTML events [MFC]"] -ms.assetid: 9a2c8ae7-7216-4a5e-bc60-6b98695be0c6 --- # DHTML Event Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following macros can be used to handle DHTML events. ## DHTML Event Map Macros diff --git a/docs/mfc/reference/dhtmlurleventmapentry-structure.md b/docs/mfc/reference/dhtmlurleventmapentry-structure.md index 2664dadb6f2..d1b3181f822 100644 --- a/docs/mfc/reference/dhtmlurleventmapentry-structure.md +++ b/docs/mfc/reference/dhtmlurleventmapentry-structure.md @@ -4,10 +4,12 @@ title: "DHtmlUrlEventMapEntry Structure" ms.date: "11/04/2016" f1_keywords: ["DHtmlUrlEventMapEntry"] helpviewer_keywords: ["DHtmlUrlEventMapEntry structure [MFC]"] -ms.assetid: 43117c1f-1a51-406c-aa2f-fea647080049 --- # DHtmlUrlEventMapEntry Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The `DHtmlUrlEventMapEntry` structure provides multi-URL event map support. ## Syntax diff --git a/docs/mfc/reference/diagnostic-services.md b/docs/mfc/reference/diagnostic-services.md index 7b1856d5835..afc822dd261 100644 --- a/docs/mfc/reference/diagnostic-services.md +++ b/docs/mfc/reference/diagnostic-services.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class Library supplies many diagnostic services that make debugging your programs easier. These diagnostic services include macros and global functions that allow you to track your program's memory allocations, dump the contents of objects during run time, and print debugging messages during run time. The macros and global functions for diagnostic services are grouped into the following categories: - General diagnostic macros @@ -77,7 +79,7 @@ Suppresses compiler warnings for the use of deprecated MFC functions. ### Syntax -``` +```cpp _AFX_SECURE_NO_WARNINGS ``` @@ -105,7 +107,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 +122,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 +158,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 +180,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 +193,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 +225,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 +252,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 +276,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 +308,7 @@ Expands to the name of the file that is being compiled. ### Syntax -``` +```cpp THIS_FILE ``` @@ -334,9 +336,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 +357,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,15 +390,15 @@ 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 `afxDump` is a predefined [CDumpContext](../../mfc/reference/cdumpcontext-class.md) object that allows you to send `CDumpContext` information to the debugger output window or to a debug terminal. Typically, you supply `afxDump` as a parameter to `CObject::Dump`. -Under Windows NT and all versions of Windows, `afxDump` output is sent to the Output-Debug window of Visual C++ when you debug your application. +Under Windows NT and all versions of Windows, `afxDump` output is sent to the Output-Debug window of Visual Studio when you debug your application. This variable is defined only in the Debug version of MFC. For more information on `afxDump`, see [Debugging MFC Applications](/visualstudio/debugger/mfc-debugging-techniques). @@ -420,7 +422,7 @@ void AfxDump(const CObject* pOb); ### Parameters -*pOb*
+*pOb*\ A pointer to an object of a class derived from `CObject`. ### Remarks @@ -437,8 +439,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 +492,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 +535,7 @@ void AfxDump(const CObject* pOb); ### Parameters -*pOb*
+*pOb*\ A pointer to an object of a class derived from `CObject`. ### Remarks @@ -556,7 +558,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 +628,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 +658,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 +692,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 +701,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 +730,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 +739,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 +770,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 +802,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 +821,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 +849,10 @@ AFXAPI AfxDoForAllClasses( ### Parameters -*pfn*
+*pfn*\ Points to an iteration function to be called for each class. The function arguments are a pointer to a `CRuntimeClass` object and a void pointer to extra data that the caller supplies to the function. -*pContext*
+*pContext*\ Points to optional data that the caller can supply to the iteration function. This pointer can be NULL. ### Remarks @@ -863,7 +865,7 @@ Serializable `CObject`-derived classes are classes derived using the DECLARE_SER ### Example [!code-cpp[NVC_MFCCollections#113](../../mfc/codesnippet/cpp/diagnostic-services_16.cpp)] - +  [!code-cpp[NVC_MFCCollections#114](../../mfc/codesnippet/cpp/diagnostic-services_17.cpp)] ### Requirements @@ -882,10 +884,10 @@ void AfxDoForAllObjects( ### Parameters -*pfn*
+*pfn*\ Points to an iteration function to execute for each object. The function arguments are a pointer to a `CObject` and a void pointer to extra data that the caller supplies to the function. -*pContext*
+*pContext*\ Points to optional data that the caller can supply to the iteration function. This pointer can be NULL. ### Remarks @@ -898,10 +900,10 @@ Stack, global, or embedded objects are not enumerated. The pointer passed to `Af ### Example [!code-cpp[NVC_MFCCollections#115](../../mfc/codesnippet/cpp/diagnostic-services_18.cpp)] - +  [!code-cpp[NVC_MFCCollections#116](../../mfc/codesnippet/cpp/diagnostic-services_19.cpp)] ## See also -[Macros and Globals](mfc-macros-and-globals.md)
+[Macros and Globals](mfc-macros-and-globals.md)\ [CObject::Dump](cobject-class.md#dump) diff --git a/docs/mfc/reference/dialog-data-exchange-functions-for-crecordview-and-cdaorecordview.md b/docs/mfc/reference/dialog-data-exchange-functions-for-crecordview-and-cdaorecordview.md index 06e79c9647e..c9544270702 100644 --- a/docs/mfc/reference/dialog-data-exchange-functions-for-crecordview-and-cdaorecordview.md +++ b/docs/mfc/reference/dialog-data-exchange-functions-for-crecordview-and-cdaorecordview.md @@ -4,10 +4,12 @@ title: "Dialog Data Exchange Functions for CRecordView and CDaoRecordView" ms.date: "09/17/2019" f1_keywords: ["AFXDAO/DDX_FieldCBIndex", "AFXDAO/DDX_FieldCBString", "AFXDAO/DDX_FieldCBStringExact", "AFXDAO/DDX_FieldCheck", "AFXDAO/DDX_FieldLBIndex", "AFXDAO/DDX_FieldLBString", "AFXDAO/DDX_FieldLBStringExact", "AFXDAO/DDX_FieldRadio", "AFXDAO/DDX_FieldScroll", "AFXDAO/DDX_FieldText"] helpviewer_keywords: ["DDX_Field functions [MFC]", "ODBC [MFC], dialog data exchange (DDX) support", "DDX (dialog data exchange) [MFC], database support", "DDX (dialog data exchange) [MFC], functions", "databases [MFC], dialog data exchange (DDX) support", "DAO [MFC], dialog data exchange (DDX) support"] -ms.assetid: 0d8cde38-3a2c-4100-9589-ac80a7b1ce91 --- # Dialog Data Exchange Functions for CRecordView and CDaoRecordView +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists the DDX_Field functions used to exchange data between a [CRecordset](../../mfc/reference/crecordset-class.md) and a [CRecordView](../../mfc/reference/crecordview-class.md) form or a [CDaoRecordset](../../mfc/reference/cdaorecordset-class.md) and a [CDaoRecordView](../../mfc/reference/cdaorecordview-class.md) form. DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. > [!NOTE] 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 37cc40288ab..35eba789e94 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 @@ -4,10 +4,12 @@ title: "Dialog Data Exchange Functions for OLE Controls" ms.date: "11/04/2016" f1_keywords: ["AFXDISP/DDX_OCBool", "AFXDISP/DDX_OCBoolRO", "AFXDISP/DDX_OCColor", "AFXDISP/DDX_OCColorRO", "AFXDISP/DDX_OCFloat", "AFXDISP/DDX_OCFloatRO", "AFXDISP/DDX_OCInt", "AFXDISP/DDX_OCIntRO", "AFXDISP/DDX_OCShort", "AFXDISP/DDX_OCShortRO", "AFXDISP/DDX_OCText", "AFXDISP/DDX_OCTextRO"] helpviewer_keywords: ["OLE controls [MFC], DDX functions", "DDX (dialog data exchange), OLE support"] -ms.assetid: 7ef1f288-ff65-40d4-aad2-5497bc00bb27 --- # Dialog Data Exchange Functions for OLE Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists the DDX_OC functions used to exchange data between a property of an OLE control in a dialog box, form view, or control view object and a data member of the dialog box, form view, or control view object. ### DDX_OC Functions @@ -245,7 +247,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/dispatch-maps.md b/docs/mfc/reference/dispatch-maps.md index 571218e9715..9d7c82dd749 100644 --- a/docs/mfc/reference/dispatch-maps.md +++ b/docs/mfc/reference/dispatch-maps.md @@ -3,10 +3,12 @@ description: "Learn more about: Dispatch Maps" title: "Dispatch Maps" ms.date: "06/20/2018" helpviewer_keywords: ["dispatch maps [MFC], macros", "dispatch maps [MFC]", "dispatch map macros [MFC]"] -ms.assetid: bef9d08b-ad35-4c3a-99d8-04150c7c04e2 --- # Dispatch Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + OLE Automation provides ways to call methods and to access properties across applications. The mechanism supplied by the Microsoft Foundation Class Library for dispatching these requests is the "dispatch map," which designates the internal and external names of object functions and properties, as well as the data types of the properties themselves and of function arguments. |Dispatch map macro|Description| diff --git a/docs/mfc/reference/document-template-strings-mfc-application-wizard.md b/docs/mfc/reference/document-template-strings-mfc-application-wizard.md index 29c42ee91a8..6cb67bac734 100644 --- a/docs/mfc/reference/document-template-strings-mfc-application-wizard.md +++ b/docs/mfc/reference/document-template-strings-mfc-application-wizard.md @@ -4,10 +4,12 @@ title: "Document Template Strings, MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.doctemp"] helpviewer_keywords: ["MFC Application Wizard, document template strings"] -ms.assetid: 8109f662-3182-4682-977a-2503321c678a --- # Document Template Strings, MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In this page of the MFC Application Wizard, provide or refine the following options to help with document management and localization. Document template strings are available for applications that include **Document/view architecture support** in the [Application Type](../../mfc/reference/application-type-mfc-application-wizard.md). They are not available for dialog boxes. Because most document template strings are visible and used by the application's users, they are localized into the **Resource language** indicated in the **Application Type** page of the wizard. - **Nonlocalized strings** diff --git a/docs/mfc/reference/edit-control-handlers.md b/docs/mfc/reference/edit-control-handlers.md index 4fc2ee2591c..4b33390e216 100644 --- a/docs/mfc/reference/edit-control-handlers.md +++ b/docs/mfc/reference/edit-control-handlers.md @@ -4,10 +4,12 @@ title: "Edit Control Handlers" ms.date: "11/04/2016" f1_keywords: ["ON_EN_ERRSPACE", "ON_EN_UPDATE", "ON_EN_VSCROLL", "ON_EN_HSCROLL", "ON_EN_KILLFOCUS", "ON_EN_MAXTEXT", "ON_EN_SETFOCUS", "ON_EN_CHANGE"] helpviewer_keywords: ["ON_EN_ERRSPACE macro [MFC]", "ON_EN_SETFOCUS macro [MFC]", "ON_EN_UPDATE macro [MFC]", "ON_EN_MAXTEXT macro [MFC]", "ON_EN_CHANGE macro [MFC]", "ON_EN_HSCROLL macro [MFC]", "ON_EN_VSCROLL macro [MFC]", "ON_EN_KILLFOCUS macro [MFC]", "edit controls [MFC], edit control handlers"] -ms.assetid: 55b88b5e-12b5-4422-b03e-c8c2f27d095c --- # Edit Control Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries correspond to the function prototype. |Map entry|Function prototype| diff --git a/docs/mfc/reference/editing-a-message-handler.md b/docs/mfc/reference/editing-a-message-handler.md index 17f1783f009..e54b6e9322e 100644 --- a/docs/mfc/reference/editing-a-message-handler.md +++ b/docs/mfc/reference/editing-a-message-handler.md @@ -4,10 +4,12 @@ title: "Editing a Message Handler" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.editing.msghandler"] helpviewer_keywords: ["message handlers [MFC]", "message handling [MFC], editing handlers"] -ms.assetid: 7babb496-1f14-43b1-a14d-2e54402a92e2 --- # Editing a Message Handler +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Once you have defined a message handler, you can go to the member function's definition to add or modify code. To jump to a member function definition from the [dialog editor](../../windows/dialog-editor.md), double-click a control for which a handler is already defined. This navigates you to the file in which the selected control's message handler is defined. diff --git a/docs/mfc/reference/event-maps.md b/docs/mfc/reference/event-maps.md index 2766a3a56a5..b6392f23e83 100644 --- a/docs/mfc/reference/event-maps.md +++ b/docs/mfc/reference/event-maps.md @@ -3,10 +3,12 @@ description: "Learn more about: Event Maps" title: "Event Maps" ms.date: "09/07/2019" helpviewer_keywords: ["event maps [MFC]"] -ms.assetid: 1ed53aee-bc53-43cd-834a-6fb935c0d29b --- # Event Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Whenever a control wishes to notify its container that some action (determined by the control developer) has happened (such as a keystroke, mouse click, or a change to the control's state) it calls an event-firing function. This function notifies the control container that some important action has occurred by firing the related event. The Microsoft Foundation Class Library offers a programming model optimized for firing events. In this model, "event maps" are used to designate which functions fire which events for a particular control. Event maps contain one macro for each event. For example, an event map that fires a stock Click event might look like this: diff --git a/docs/mfc/reference/event-sink-maps.md b/docs/mfc/reference/event-sink-maps.md index e8d550c045a..d4dad8707fc 100644 --- a/docs/mfc/reference/event-sink-maps.md +++ b/docs/mfc/reference/event-sink-maps.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When an embedded OLE control fires an event, the control's container receives the event using a mechanism, called an "event sink map," supplied by MFC. This event sink map designates handler functions for each specific event, as well as parameters of those events. For more information on event sink maps, see the article [ActiveX Control Containers](../../mfc/activex-control-containers.md). ### Event Sink Maps @@ -158,7 +160,7 @@ For a list of the **VTS_** constants, see [EVENT_CUSTOM](event-maps.md#event_cus ### Example -The following example demonstrates an event handler, for the MouseDown event, implemented for three controls ( IDC_MYCTRL1 through IDC_MYCTRL3). The event handler function, `OnRangeMouseDown`, is declared in the header file of the dialog class ( `CMyDlg`) as: +The following example demonstrates an event handler, for the MouseDown event, implemented for three controls ( IDC_MYCTRL1 through IDC_MYCTRL3). The event handler function, `OnRangeMouseDown`, is declared in the header file of the dialog class (`CMyDlg`) as: [!code-cpp[NVC_MFCAutomation#12](../../mfc/codesnippet/cpp/event-sink-maps_2.h)] @@ -248,7 +250,6 @@ For a list of the **VTS_** constants, see [EVENT_CUSTOM](event-maps.md#event_cus Use the ON_PROPNOTIFY_RANGE macro to define an event sink map entry for handling property notifications from any OLE control having a control ID within a contiguous range of IDs. ``` - ON_PROPNOTIFY_RANGE(theClass, idFirst, idLast, dispid, pfnRequest, pfnChanged) ``` @@ -281,7 +282,6 @@ Pointer to a member function that handles the `OnChanged` notification for this The ON_PROPNOTIFY_REFLECT macro, when used in the event sink map of an OLE control's wrapper class, receives property notifications sent by the control before they are handled by the control's container. ``` - ON_PROPNOTIFY_REFLECT(theClass, dispid, pfnRequest, pfnChanged) ``` diff --git a/docs/mfc/reference/exception-processing.md b/docs/mfc/reference/exception-processing.md index cd5e64b1d63..687a470c9c4 100644 --- a/docs/mfc/reference/exception-processing.md +++ b/docs/mfc/reference/exception-processing.md @@ -3,10 +3,12 @@ description: "Learn more about: Exception Processing" title: "Exception Processing" ms.date: "11/04/2016" helpviewer_keywords: ["macros [MFC], exception handling", "DAO (Data Access Objects), exceptions [MFC]", "OLE exceptions [MFC], MFC functions", "exceptions [MFC], processing", "exception macros [MFC]", "termination functions, MFC", "MFC, exceptions", "exceptions [MFC], MFC throwing functions"] -ms.assetid: 26d4457c-8350-48f5-916e-78f919787c30 --- # Exception Processing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When a program executes, a number of abnormal conditions and errors called "exceptions" can occur. These may include running out of memory, resource allocation errors, and failure to find files. The Microsoft Foundation Class Library uses an exception-handling scheme that is modeled closely after the one proposed by the ANSI standards committee for C++. An exception handler must be set up before calling a function that may encounter an abnormal situation. If the function encounters an abnormal condition, it throws an exception and control is passed to the exception handler. diff --git a/docs/mfc/reference/extension-dll-macros.md b/docs/mfc/reference/extension-dll-macros.md index f7dc3c4d10f..548496d62fa 100644 --- a/docs/mfc/reference/extension-dll-macros.md +++ b/docs/mfc/reference/extension-dll-macros.md @@ -6,6 +6,9 @@ helpviewer_keywords: ["module macros in MFC"] --- # Macros and functions for managing DLLs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + | Name | Description | |--|--| | [`AFX_EXT_CLASS`](#afx_ext_class)] | Exports classes. | @@ -79,7 +82,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 +332,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/generated-classes-mfc-application-wizard.md b/docs/mfc/reference/generated-classes-mfc-application-wizard.md index 7bdcfd54455..de59480ba26 100644 --- a/docs/mfc/reference/generated-classes-mfc-application-wizard.md +++ b/docs/mfc/reference/generated-classes-mfc-application-wizard.md @@ -4,10 +4,12 @@ title: "Generated Classes, MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.classes"] helpviewer_keywords: ["MFC Application Wizard, generated classes"] -ms.assetid: 5f33209c-7f01-4f72-8c1c-6f02f507ba9f --- # Generated Classes, MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists the names of base classes and files that your project generates. By default, the names are based on the project name that you specified in the **New Project Dialog Box**. You can change most of these names, as described here: - **Generated classes** diff --git a/docs/mfc/reference/generic-control-handler.md b/docs/mfc/reference/generic-control-handler.md index 7006c0d77b3..37f27818fa9 100644 --- a/docs/mfc/reference/generic-control-handler.md +++ b/docs/mfc/reference/generic-control-handler.md @@ -3,10 +3,12 @@ description: "Learn more about: Generic Control Handler" title: "Generic Control Handler" ms.date: "11/04/2016" helpviewer_keywords: ["handlers [MFC], ON_CONTROL", "handlers [MFC]", "GenericControl Handler [MFC]", "ON_CONTROL macro [MFC]"] -ms.assetid: 1e25e583-5d5a-4363-8904-839991a8570d --- # Generic Control Handler +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entry corresponds to the function prototype. |Map entry|Function prototype| diff --git a/docs/mfc/reference/gray-and-dithered-bitmap-functions.md b/docs/mfc/reference/gray-and-dithered-bitmap-functions.md index d2d80261f07..4d33b4f498a 100644 --- a/docs/mfc/reference/gray-and-dithered-bitmap-functions.md +++ b/docs/mfc/reference/gray-and-dithered-bitmap-functions.md @@ -4,10 +4,12 @@ title: "Gray and Dithered Bitmap Functions" ms.date: "11/19/2018" f1_keywords: ["AFXWIN/AfxDrawGrayBitmap", "AFXWIN/AfxGetGrayBitmap", "AFXWIN/AfxDrawDitheredBitmap", "AFXWIN/AfxGetDitheredBitmap"] helpviewer_keywords: ["gray and dithered bitmap functions [MFC]"] -ms.assetid: cb139a77-b85e-4504-9d93-24156ad77a41 --- # Gray and Dithered Bitmap Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + **Gray Bitmap Functions** MFC provides two functions for giving a bitmap the appearance of a disabled control. diff --git a/docs/mfc/reference/handlers-for-wm-messages.md b/docs/mfc/reference/handlers-for-wm-messages.md index eb656fb8f76..a562529cbd9 100644 --- a/docs/mfc/reference/handlers-for-wm-messages.md +++ b/docs/mfc/reference/handlers-for-wm-messages.md @@ -3,10 +3,12 @@ description: "Learn more about: Handlers for WM_ Messages" title: "Handlers for WM_ Messages" ms.date: "11/04/2016" helpviewer_keywords: ["WM_ messages [MFC]"] -ms.assetid: cad81690-90bf-4f77-943f-a435e7563bdd --- # Handlers for WM_ Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following topics correspond to the map entries. |Topic|Map entries| diff --git a/docs/mfc/reference/how-to-use-the-message-map-cross-reference.md b/docs/mfc/reference/how-to-use-the-message-map-cross-reference.md index 8141dd49521..b93284c67e1 100644 --- a/docs/mfc/reference/how-to-use-the-message-map-cross-reference.md +++ b/docs/mfc/reference/how-to-use-the-message-map-cross-reference.md @@ -3,10 +3,12 @@ description: "Learn more about: How to: Use the Message-Map Cross-Reference" title: "How to: Use the Message-Map Cross-Reference" ms.date: "11/04/2016" helpviewer_keywords: ["windows [MFC], message maps"] -ms.assetid: 2e863d23-9e58-45ba-b5e4-a8ceefccd0c8 --- # How to: Use the Message-Map Cross-Reference +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In entries labeled \, write your own member function for a derived [CWnd](../../mfc/reference/cwnd-class.md) class. Give your function any name you like. Other functions, such as `OnActivate`, are member functions of class `CWnd`. If called, they pass the message to the `DefWindowProc` Windows function. To process Windows notification messages, override the corresponding `CWnd` function in your derived class. Your function should call the overridden function in your base class to let the base class and Windows respond to the message. In all cases, put the function prototype in the `CWnd`-derived class header, and code the message map entry as shown. diff --git a/docs/mfc/reference/hse-version-info-structure.md b/docs/mfc/reference/hse-version-info-structure.md index 3917f359172..30cb155cdac 100644 --- a/docs/mfc/reference/hse-version-info-structure.md +++ b/docs/mfc/reference/hse-version-info-structure.md @@ -4,10 +4,12 @@ title: "HSE_VERSION_INFO Structure" ms.date: "11/04/2016" f1_keywords: ["HSE_VERSION_INFO"] helpviewer_keywords: ["HSE_VERSION_INFO structure [MFC]"] -ms.assetid: 4837312d-68c8-4d05-9afa-1934d7d49b20 --- # HSE_VERSION_INFO Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This structure is pointed to by the *pVer* parameter in the `CHttpServer::GetExtensionVersion` member function. It provides the ISA version number and a text description of the ISA. ## Syntax diff --git a/docs/mfc/reference/icommandsource-interface.md b/docs/mfc/reference/icommandsource-interface.md index b75c703c395..b5499c10a48 100644 --- a/docs/mfc/reference/icommandsource-interface.md +++ b/docs/mfc/reference/icommandsource-interface.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: ICommandSource Interface" title: "ICommandSource Interface" -ms.date: "03/27/2019" +description: "Learn more about: ICommandSource Interface" +ms.date: 03/27/2019 f1_keywords: ["ICommandSource", "AFXWINFORMS/ICommandSource", "AFXWINFORMS/ICommandSource::AddCommandHandler", "AFXWINFORMS/ICommandSource::AddCommandRangeHandler", "AFXWINFORMS/ICommandSource::AddCommandRangeUIHandler", "AFXWINFORMS/ICommandSource::AddCommandUIHandler", "AFXWINFORMS/ICommandSource::PostCommand", "AFXWINFORMS/ICommandSource::RemoveCommandHandler", "AFXWINFORMS/ICommandSource::RemoveCommandRangeHandler", "AFXWINFORMS/ICommandSource::RemoveCommandRangeUIHandler", "AFXWINFORMS/ICommandSource::RemoveCommandUIHandler", "AFXWINFORMS/ICommandSource::SendCommand"] helpviewer_keywords: ["ICommandSource interface [MFC]"] -ms.assetid: a4b1f698-c09f-4ba8-9b13-0e74a0a4967e --- # ICommandSource Interface +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages commands sent from a command source object to a user control. ## Syntax @@ -59,6 +61,7 @@ void AddCommandHandler( *cmdID*
The command ID. + *cmdHandler*
A handle to the command handler method. @@ -82,8 +85,10 @@ void AddCommandRangeHandler( *cmdIDMin*
The beginning index of the command ID range. + *cmdIDMax*
The ending index of the command ID range. + *cmdHandler*
A handle to the message handler method to which the commands are mapped. @@ -106,8 +111,10 @@ void AddCommandRangeUIHandler( *cmdIDMin*
The beginning index of the command ID range. + *cmdIDMax*
The ending index of the command ID range. + *cmdHandler*
A handle to the message handler method to which the commands are mapped. @@ -129,6 +136,7 @@ void AddCommandUIHandler( *cmdID*
The command ID. + *cmdUIHandler*
A handle to the user interface command message handler method. @@ -184,6 +192,7 @@ void RemoveCommandRangeUIHandler( *cmdIDMin*
The beginning index of the command ID range. + *cmdIDMax*
The ending index of the command ID range. @@ -205,6 +214,7 @@ void RemoveCommandRangeUIHandler( *cmdIDMin*
The beginning index of the command ID range. + *cmdIDMax*
The ending index of the command ID range. diff --git a/docs/mfc/reference/icommandtarget-interface.md b/docs/mfc/reference/icommandtarget-interface.md index 95e3b7d45b8..5d5d07a167a 100644 --- a/docs/mfc/reference/icommandtarget-interface.md +++ b/docs/mfc/reference/icommandtarget-interface.md @@ -4,10 +4,12 @@ title: "ICommandTarget Interface" ms.date: "11/04/2016" f1_keywords: ["ICommandTarget", "AFXWINFORMS/ICommandTarget", "AFXWINFORMS/ICommandTarget::Initialize"] helpviewer_keywords: ["ICommandTarget interface [MFC]"] -ms.assetid: dd9927f6-3479-4e7c-8ef9-13206cf901f3 --- # ICommandTarget Interface +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Provides a user control with an interface to receive commands from a command source object. ## Syntax diff --git a/docs/mfc/reference/icommandui-interface.md b/docs/mfc/reference/icommandui-interface.md index 8e4e7726a6b..c2bc8e659ea 100644 --- a/docs/mfc/reference/icommandui-interface.md +++ b/docs/mfc/reference/icommandui-interface.md @@ -4,10 +4,12 @@ title: "ICommandUI Interface" ms.date: "09/07/2019" f1_keywords: ["ICommandUI", "AFXWINFORMS/ICommandUI", "AFXWINFORMS/icommandui__Check", "AFXWINFORMS/ICommandUI::ContinueRouting", "AFXWINFORMS/ICommandUI::Enabled", "AFXWINFORMS/ICommandUI::ID", "AFXWINFORMS/ICommandUI::Index", "AFXWINFORMS/ICommandUI::Radio", "AFXWINFORMS/ICommandUI::Text"] helpviewer_keywords: ["ICommandUI interface [MFC]"] -ms.assetid: 134afe8d-dcdf-47ca-857a-a166a6b665dd --- # ICommandUI Interface +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Manages user interface commands. ## Syntax diff --git a/docs/mfc/reference/internal-classes.md b/docs/mfc/reference/internal-classes.md index 09282b431ff..ceb3619df8e 100644 --- a/docs/mfc/reference/internal-classes.md +++ b/docs/mfc/reference/internal-classes.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["UpdateTabs method [MFC]", "Start method [MFC]", "IsLast m --- # Internal Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following classes are used internally in MFC. For completeness, this section describes these internal classes, but they aren't intended to be used directly in your code. ## In This Section diff --git a/docs/mfc/reference/internet-url-parsing-globals.md b/docs/mfc/reference/internet-url-parsing-globals.md index d87c5d1798e..053844d9984 100644 --- a/docs/mfc/reference/internet-url-parsing-globals.md +++ b/docs/mfc/reference/internet-url-parsing-globals.md @@ -3,10 +3,12 @@ description: "Learn more about: Internet URL Parsing Globals and Helpers" title: "Internet URL Parsing Globals and Helpers" ms.date: "04/03/2017" helpviewer_keywords: ["parsing, URLs", "URLs, parsing"] -ms.assetid: 46c6384f-e4a6-4dbd-9196-219c19040ec5 --- # Internet URL Parsing Globals and Helpers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When a client sends a query to the Internet server, you can use one of the URL parsing globals to extract information about the client. The helper functions provide other internet functionality. ## Internet URL Parsing Globals diff --git a/docs/mfc/reference/iview-interface.md b/docs/mfc/reference/iview-interface.md index 0cd40802b71..af902350ca1 100644 --- a/docs/mfc/reference/iview-interface.md +++ b/docs/mfc/reference/iview-interface.md @@ -4,10 +4,12 @@ title: "IView Interface" ms.date: "11/04/2016" f1_keywords: ["IView", "AFXWINFORMS/IView", "AFXWINFORMS/IView::OnActivateView", "AFXWINFORMS/IView::OnInitialUpdate", "AFXWINFORMS/IView::OnUpdate"] helpviewer_keywords: ["views [MFC]", "IView class [MFC]", "views [MFC], classes"] -ms.assetid: 9321f299-486e-4551-bee9-d2c4a7b91548 --- # IView Interface +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Implements several methods that [CWinFormsView](../../mfc/reference/cwinformsview-class.md) uses to send view notifications to a managed control. ## Syntax diff --git a/docs/mfc/reference/list-box-handlers.md b/docs/mfc/reference/list-box-handlers.md index 6563a51a716..f331b682812 100644 --- a/docs/mfc/reference/list-box-handlers.md +++ b/docs/mfc/reference/list-box-handlers.md @@ -4,10 +4,12 @@ title: "List Box Handlers" ms.date: "11/04/2016" f1_keywords: ["ON_LBN_DBLCLK", "ON_LBN_ERRSPACE", "ON_LBN_SETFOCUS", "ON_LBN_SELCHANGE", "ON_LBN_KILLFOCUS"] helpviewer_keywords: ["list boxes [MFC], list box handlers", "ON_LBN_KILLFOCUS", "ON_LBN_ERRSPACE", "ON_LBN_SELCHANGE", "ON_LBN_SETFOCUS", "ON_LBN_DBLCLK"] -ms.assetid: e4e54412-2167-436a-883b-5dcad01820b8 --- # List Box Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries have the corresponding function prototype. |Map entry|Function prototype| diff --git a/docs/mfc/reference/mapping-messages-to-functions.md b/docs/mfc/reference/mapping-messages-to-functions.md index 6121a62bd33..5331cb8cc67 100644 --- a/docs/mfc/reference/mapping-messages-to-functions.md +++ b/docs/mfc/reference/mapping-messages-to-functions.md @@ -4,10 +4,12 @@ title: "Mapping Messages to Functions" ms.date: "09/06/2019" f1_keywords: ["vc.codewiz.mapping.msg.function"] helpviewer_keywords: ["Windows messages [MFC], adding message handlers", "message maps [MFC], mapping messages to functions"] -ms.assetid: a7727a62-f638-4b20-b7f5-131f47200d6a --- # Mapping Messages to Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [Class Wizard](mfc-class-wizard.md) enables you to bind message handlers (member functions of MFC user-interface classes) to the messages generated by your application's resources. They use [MFC message maps](../../mfc/messages-and-commands-in-the-framework.md) to create the binding. When you use Class View to create a new class derived from one of the framework classes, it automatically places a complete and functional class in the header (.h) and implementation (.cpp) files that you specify. diff --git a/docs/mfc/reference/media/mfc-app-wizard.png b/docs/mfc/reference/media/mfc-app-wizard.png index df573840244..20680712235 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 07a43109d69..00000000000 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 21fae3a3a49..832196599dc 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/message-map-macros-mfc.md b/docs/mfc/reference/message-map-macros-mfc.md index f2739a164d2..8b21fa4fa91 100644 --- a/docs/mfc/reference/message-map-macros-mfc.md +++ b/docs/mfc/reference/message-map-macros-mfc.md @@ -4,10 +4,12 @@ title: "Message Map Macros (MFC)" ms.date: "03/27/2019" f1_keywords: ["AFXWIN/DECLARE_MESSAGE_MAP", "AFXWIN/BEGIN_MESSAGE_MAP", "AFXWIN/BEGIN_TEMPLATE_MESSAGE_MAP", "AFXWIN/END_MESSAGE_MAP", "AFXWIN/ON_COMMAND", "AFXWIN/ON_COMMAND_EX", "AFXWIN/ON_CONTROL", "AFXWIN/ON_MESSAGE", "AFXWIN/ON_OLECMD", "AFXWIN/ON_REGISTERED_MESSAGE", "AFXWIN/ON_REGISTERED_THREAD_MESSAGE", "AFXWIN/ON_THREAD_MESSAGE", "AFXWIN/ON_UPDATE_COMMAND_UI", "AFXWIN/ON_COMMAND_RANGE", "AFXWIN/ON_UPDATE_COMMAND_UI_RANGE", "AFXWIN/ON_CONTROL_RANGE"] helpviewer_keywords: ["message map macros", "Windows messages [MFC], declaration", "demarcating Windows messages", "message maps [MFC], macros", "message maps [MFC], declaration and demarcation", "message mapping macros", "ranges, message map", "message map ranges"] -ms.assetid: 531b15ce-32b5-4ca0-a849-bb519616c731 --- # Message Map Macros (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To support message maps, MFC supplies the following macros: ### Message-Map Declaration and Demarcation Macros diff --git a/docs/mfc/reference/message-maps-mfc.md b/docs/mfc/reference/message-maps-mfc.md index fcce99b97e6..2de3e965971 100644 --- a/docs/mfc/reference/message-maps-mfc.md +++ b/docs/mfc/reference/message-maps-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Message Maps (MFC)" title: "Message Maps (MFC)" ms.date: "09/07/2019" helpviewer_keywords: ["message maps [MFC], MFC", "Windows messages [MFC], message maps", "messages [MFC], Windows", "MFC, messages"] -ms.assetid: 3f9855e4-9d7d-4b64-8f3f-a19ea3cf79ba --- # Message Maps (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This section of the reference lists all [message mapping macros](../../mfc/reference/message-map-macros-mfc.md) and all [`CWnd`](../../mfc/reference/cwnd-class.md) message-map entries along with the corresponding member function prototypes: |Category|Description| diff --git a/docs/mfc/reference/message-types-associated-with-user-interface-objects.md b/docs/mfc/reference/message-types-associated-with-user-interface-objects.md index 61472bf5ac0..b9183f9ee34 100644 --- a/docs/mfc/reference/message-types-associated-with-user-interface-objects.md +++ b/docs/mfc/reference/message-types-associated-with-user-interface-objects.md @@ -4,10 +4,12 @@ title: "Message Types Associated with User-Interface Objects" ms.date: "11/04/2016" f1_keywords: ["vc.codewiz.uiobject.msgs"] helpviewer_keywords: ["message types and user interface objects [MFC]"] -ms.assetid: 681ee1a7-f6e6-4ea0-9fc6-1fb53a35516e --- # Message Types Associated with User-Interface Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows the types of objects with which you work, and the types of messages associated with them. ### User Interface Objects and Associated Messages diff --git a/docs/mfc/reference/mfc-activex-control-wizard.md b/docs/mfc/reference/mfc-activex-control-wizard.md index e949d307fa7..b3eadd27b35 100644 --- a/docs/mfc/reference/mfc-activex-control-wizard.md +++ b/docs/mfc/reference/mfc-activex-control-wizard.md @@ -4,11 +4,13 @@ title: "MFC ActiveX Control Wizard" ms.date: "03/04/2022" f1_keywords: ["vc.appwiz.mfc.ctl.overview"] helpviewer_keywords: ["ActiveX controls [MFC], MFC", "MFC ActiveX controls [MFC], wizards", "OLE controls [MFC], creating", "MFC ActiveX Control Wizard", "OLE controls [MFC]"] -ms.assetid: f19d698c-bdc3-4c74-af97-3d6ccb441b75 ms.custom: devdivchpfy22 --- # MFC ActiveX Control Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An ActiveX control is a specific type of [automation server](../../mfc/automation-servers.md); it's a reusable component. The application hosting the ActiveX control is the [automation client](../../mfc/automation-clients.md) of that control. If your goal is to create such a reusable component, then use this wizard to create your control. For more information, see [MFC ActiveX Controls](../../mfc/mfc-activex-controls.md). >[!IMPORTANT] diff --git a/docs/mfc/reference/mfc-add-class-wizard.md b/docs/mfc/reference/mfc-add-class-wizard.md index ce799af37fc..fe1567f8266 100644 --- a/docs/mfc/reference/mfc-add-class-wizard.md +++ b/docs/mfc/reference/mfc-add-class-wizard.md @@ -4,10 +4,12 @@ title: "MFC Add Class Wizard" ms.date: "09/06/2019" f1_keywords: ["vc.codewiz.class.mfc.simple.overview"] helpviewer_keywords: ["MFC Add Class Wizard", "wizards [MFC]"] -ms.assetid: ad3b0989-d307-43b2-9417-3f9a78889024 --- # MFC Add Class Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use this code wizard to add a class to an existing MFC project, or to add a class to an ATL project that supports MFC. You can also add MFC classes to Win32 projects that have MFC support. The features you specified when you created your project determine the options available in this dialog box. To access the wizard, click on **Add Class** in [Class Wizard](mfc-class-wizard.md). ![Add MFC Class Wizard.](media/add-mfc-class-wizard.png "Add MFC Class Wizard") diff --git a/docs/mfc/reference/mfc-application-wizard.md b/docs/mfc/reference/mfc-application-wizard.md index 50199dd5162..960a05d3ce5 100644 --- a/docs/mfc/reference/mfc-application-wizard.md +++ b/docs/mfc/reference/mfc-application-wizard.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["MFC Application Wizard", "executable files, creating"] --- # MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The MFC Application Wizard generates an application that, when compiled, implements the basic features of a Windows executable (.exe) application. The MFC starter application includes C++ source (.cpp) files, resource (.rc) files, header (.h) files, and a project (.vcxproj) file. The code that is generated in these starter files is based on MFC. > [!NOTE] @@ -14,7 +17,7 @@ The MFC Application Wizard generates an application that, when compiled, impleme ## Overview -This wizard page describes the current application settings for the MFC application that you’re creating. By default, the wizard creates a project as follows: +This wizard page describes the current application settings for the MFC application that you're creating. By default, the wizard creates a project as follows: - [Application Type, MFC Application Wizard](../../mfc/reference/application-type-mfc-application-wizard.md) @@ -68,7 +71,7 @@ This wizard page describes the current application settings for the MFC applicat To change these default settings, select the appropriate tab title in the left column of the wizard and make the changes on the page that appears. -After you create an MFC application project, you can add objects or controls to your project using Visual C++ [code wizards](../../ide/adding-functionality-with-code-wizards-cpp.md). +After you create an MFC application project, you can add objects or controls to your project using Visual Studio [code wizards](../../ide/adding-functionality-with-code-wizards-cpp.md). ## See also diff --git a/docs/mfc/reference/mfc-class-wizard.md b/docs/mfc/reference/mfc-class-wizard.md index ea0eb4c71b2..3af17c09036 100644 --- a/docs/mfc/reference/mfc-class-wizard.md +++ b/docs/mfc/reference/mfc-class-wizard.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["MFC Class Wizard"] --- # MFC Class Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use the **Class Wizard** to create new MFC classes, or add messages and message handlers to existing classes in your project. There are three ways to open the **Class Wizard**: diff --git a/docs/mfc/reference/mfc-classes.md b/docs/mfc/reference/mfc-classes.md index 1b2c709b60b..99ecdc84b58 100644 --- a/docs/mfc/reference/mfc-classes.md +++ b/docs/mfc/reference/mfc-classes.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The classes in the following list are included in the Microsoft Foundation Class (MFC) Library. > [!TIP] @@ -17,1285 +19,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)
-Supports arrays that resemble` C arrays, but can dynamically reduce and grow as necessary. +[`CArray` Class](carray-class.md)\ +Supports arrays that resemble C arrays, but can dynamically reduce and grow as necessary. -[`CAsyncMonikerFile` Class](../../mfc/reference/casyncmonikerfile-class.md)
+[`CAsyncMonikerFile` Class](casyncmonikerfile-class.md)\ Provides functionality for the use of asynchronous monikers in ActiveX controls (formerly OLE controls). -[`CAsyncSocket` Class](../../mfc/reference/casyncsocket-class.md)
+[`CAsyncSocket` Class](casyncsocket-class.md)\ Represents a Windows Socket, which is an endpoint of network communication. -[`CAutoHideDockSite` Class](../../mfc/reference/cautohidedocksite-class.md)
-Extends the [`CDockSite` Class](../../mfc/reference/cdocksite-class.md) to implement auto-hide dock panes. +[`CAutoHideDockSite` Class](cautohidedocksite-class.md)\ +Extends the [`CDockSite` Class](cdocksite-class.md) to implement auto-hide dock panes. -[`CBaseKeyFrame` Class](../../mfc/reference/cbasekeyframe-class.md)
+[`CBaseKeyFrame` Class](cbasekeyframe-class.md)\ Implements the basic functionality of a keyframe. -[`CBasePane` Class](../../mfc/reference/cbasepane-class.md)
+[`CBasePane` Class](cbasepane-class.md)\ Base class for all panes. -[`CBaseTabbedPane` Class](../../mfc/reference/cbasetabbedpane-class.md)
-Extends the functionality of the [`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md) to support the creation of tabbed windows. +[`CBaseTabbedPane` Class](cbasetabbedpane-class.md)\ +Extends the functionality of the [`CDockablePane` Class](cdockablepane-class.md) to support the creation of tabbed windows. -[`CBaseTransition` Class](../../mfc/reference/cbasetransition-class.md)
+[`CBaseTransition` Class](cbasetransition-class.md)\ Represents a basic transition. -[`CBitmap` Class](../../mfc/reference/cbitmap-class.md)
+[`CBitmap` Class](cbitmap-class.md)\ Encapsulates a Windows graphics device interface (GDI) bitmap and provides member functions to manipulate the bitmap. -[`CBitmapButton` Class](../../mfc/reference/cbitmapbutton-class.md)
+[`CBitmapButton` Class](cbitmapbutton-class.md)\ Creates pushbutton controls labeled with bitmapped images instead of text. -[`CBitmapRenderTarget` Class](../../mfc/reference/cbitmaprendertarget-class.md)
+[`CBitmapRenderTarget` Class](cbitmaprendertarget-class.md)\ A wrapper for `ID2D1BitmapRenderTarget`. -[`CBrush` Class](../../mfc/reference/cbrush-class.md)
+[`CBrush` Class](cbrush-class.md)\ Encapsulates a Windows graphics device interface (GDI) brush. -[`CButton` Class](../../mfc/reference/cbutton-class.md)
+[`CButton` Class](cbutton-class.md)\ Provides the functionality of Windows button controls. -[`CByteArray` Class](../../mfc/reference/cbytearray-class.md)
+[`CByteArray` Class](cbytearray-class.md)\ Supports dynamic arrays of bytes. -[`CCachedDataPathProperty` Class](../../mfc/reference/ccacheddatapathproperty-class.md)
+[`CCachedDataPathProperty` Class](ccacheddatapathproperty-class.md)\ Implements an OLE control property transferred asynchronously and cached in a memory file. -[`CCheckListBox` Class](../../mfc/reference/cchecklistbox-class.md)
+[`CCheckListBox` Class](cchecklistbox-class.md)\ Provides the functionality of a Windows checklist box. -[`CClientDC` Class](../../mfc/reference/cclientdc-class.md)
+[`CClientDC` Class](cclientdc-class.md)\ Handles the calling of the Windows functions [`GetDC`](/windows/win32/api/winuser/nf-winuser-getdc) at construction time and [`ReleaseDC`](/windows/win32/api/winuser/nf-winuser-releasedc) at destruction time. -[`CCmdTarget` Class](../../mfc/reference/ccmdtarget-class.md)
+[`CCmdTarget` Class](ccmdtarget-class.md)\ Base class for the Microsoft Foundation Class Library message-map architecture. -[`CCmdUI` Class](../../mfc/reference/ccmdui-class.md)
+[`CCmdUI` Class](ccmdui-class.md)\ Used only within an `ON_UPDATE_COMMAND_UI` handler in a `CCmdTarget`-derived class. -[`CColorDialog` Class](../../mfc/reference/ccolordialog-class.md)
+[`CColorDialog` Class](ccolordialog-class.md)\ Lets you incorporate a color-selection dialog box into your application. -[`CComboBox` Class](../../mfc/reference/ccombobox-class.md)
+[`CComboBox` Class](ccombobox-class.md)\ Provides the functionality of a Windows combo box. -[`CComboBoxEx` Class](../../mfc/reference/ccomboboxex-class.md)
+[`CComboBoxEx` Class](ccomboboxex-class.md)\ Extends the combo box control by providing support for image lists. -[`CCommandLineInfo` Class](../../mfc/reference/ccommandlineinfo-class.md)
+[`CCommandLineInfo` Class](ccommandlineinfo-class.md)\ Aids in parsing the command line at application startup. -[`CCommonDialog` Class](../../mfc/reference/ccommondialog-class.md)
+[`CCommonDialog` Class](ccommondialog-class.md)\ The base class for classes that encapsulate functionality of the Windows common dialogs. -[`CConnectionPoint` Class](../../mfc/reference/cconnectionpoint-class.md)
+[`CConnectionPoint` Class](cconnectionpoint-class.md)\ Defines a special type of interface used to communicate with other OLE objects, called a "connection point." -[`CConstantTransition` Class](../../mfc/reference/cconstanttransition-class.md)
+[`CConstantTransition` Class](cconstanttransition-class.md)\ Encapsulates a constant transition. -[`CContextMenuManager` Class](../../mfc/reference/ccontextmenumanager-class.md)
+[`CContextMenuManager` Class](ccontextmenumanager-class.md)\ Manages shortcut menus, also known as context menus. -[`CControlBar` Class](../../mfc/reference/ccontrolbar-class.md)
-Base class for the control-bar classes [`CStatusBar` Class](../../mfc/reference/cstatusbar-class.md), [`CToolBar` Class](../../mfc/reference/ctoolbar-class.md), [`CDialogBar` Class](../../mfc/reference/cdialogbar-class.md), [`CReBar` Class](../../mfc/reference/crebar-class.md), and [`COleResizeBar` Class](../../mfc/reference/coleresizebar-class.md). +[`CControlBar` Class](ccontrolbar-class.md)\ +Base class for the control-bar classes [`CStatusBar` Class](cstatusbar-class.md), [`CToolBar` Class](ctoolbar-class.md), [`CDialogBar` Class](cdialogbar-class.md), [`CReBar` Class](crebar-class.md), and [`COleResizeBar` Class](coleresizebar-class.md). -[`CCriticalSection` Class](../../mfc/reference/ccriticalsection-class.md)
+[`CCriticalSection` Class](ccriticalsection-class.md)\ Represents a "critical section", which is a synchronization object that enables one thread at a time to access a resource or section of code. -[`CCtrlView` Class](../../mfc/reference/cctrlview-class.md)
+[`CCtrlView` Class](cctrlview-class.md)\ Adapts the document-view architecture to the common controls supported by Windows 98 and Windows NT versions 3.51 and later. -[`CCubicTransition` Class](../../mfc/reference/ccubictransition-class.md)
+[`CCubicTransition` Class](ccubictransition-class.md)\ Encapsulates a cubic transition. -[`CCustomInterpolator` Class](../../mfc/reference/ccustominterpolator-class.md)
+[`CCustomInterpolator` Class](ccustominterpolator-class.md)\ Implements a basic interpolator. -[`CCustomTransition` Class](../../mfc/reference/ccustomtransition-class.md)
+[`CCustomTransition` Class](ccustomtransition-class.md)\ Implements a custom transition. -[`CD2DBitmap` Class](../../mfc/reference/cd2dbitmap-class.md)
+[`CD2DBitmap` Class](cd2dbitmap-class.md)\ A wrapper for `ID2D1Bitmap`. -[`CD2DBitmapBrush` Class](../../mfc/reference/cd2dbitmapbrush-class.md)
+[`CD2DBitmapBrush` Class](cd2dbitmapbrush-class.md)\ A wrapper for `ID2D1BitmapBrush`. -[`CD2DBrush` Class](../../mfc/reference/cd2dbrush-class.md)
+[`CD2DBrush` Class](cd2dbrush-class.md)\ A wrapper for `ID2D1Brush`. -[`CD2DBrushProperties` Class](../../mfc/reference/cd2dbrushproperties-class.md)
+[`CD2DBrushProperties` Class](cd2dbrushproperties-class.md)\ A wrapper for `D2D1_BRUSH_PROPERTIES`. -[`CD2DEllipse` Class](../../mfc/reference/cd2dellipse-class.md)
+[`CD2DEllipse` Class](cd2dellipse-class.md)\ A wrapper for `D2D1_BRUSH_PROPERTIES`. -[`CD2DGeometry` Class](../../mfc/reference/cd2dgeometry-class.md)
+[`CD2DGeometry` Class](cd2dgeometry-class.md)\ A wrapper for `ID2D1Geometry`. -[`CD2DGeometrySink` Class](../../mfc/reference/cd2dgeometrysink-class.md)
+[`CD2DGeometrySink` Class](cd2dgeometrysink-class.md)\ A wrapper for `ID2D1GeometrySink`. -[`CD2DGradientBrush` Class](../../mfc/reference/cd2dgradientbrush-class.md)
+[`CD2DGradientBrush` Class](cd2dgradientbrush-class.md)\ The base class of the `CD2DLinearGradientBrush` and the `CD2DRadialGradientBrush` classes. -[`CD2DLayer` Class](../../mfc/reference/cd2dlayer-class.md)
+[`CD2DLayer` Class](cd2dlayer-class.md)\ A wrapper for `ID2D1Layer`. -[`CD2DLinearGradientBrush` Class](../../mfc/reference/cd2dlineargradientbrush-class.md)
+[`CD2DLinearGradientBrush` Class](cd2dlineargradientbrush-class.md)\ A wrapper for `ID2D1LinearGradientBrush`. -[`CD2DMesh` Class](../../mfc/reference/cd2dmesh-class.md)
+[`CD2DMesh` Class](cd2dmesh-class.md)\ A wrapper for `ID2D1Mesh`. -[`CD2DPathGeometry` Class](../../mfc/reference/cd2dpathgeometry-class.md)
+[`CD2DPathGeometry` Class](cd2dpathgeometry-class.md)\ A wrapper for `ID2D1PathGeometry`. -[`CD2DPointF` Class](../../mfc/reference/cd2dpointf-class.md)
+[`CD2DPointF` Class](cd2dpointf-class.md)\ A wrapper for `D2D1_POINT_2F`. -[`CD2DPointU` Class](../../mfc/reference/cd2dpointu-class.md)
+[`CD2DPointU` Class](cd2dpointu-class.md)\ A wrapper for `D2D1_POINT_2U`. -[`CD2DRadialGradientBrush` Class](../../mfc/reference/cd2dradialgradientbrush-class.md)
+[`CD2DRadialGradientBrush` Class](cd2dradialgradientbrush-class.md)\ A wrapper for `ID2D1RadialGradientBrush`. -[`CD2DRectF` Class](../../mfc/reference/cd2drectf-class.md)
+[`CD2DRectF` Class](cd2drectf-class.md)\ A wrapper for `D2D1_RECT_F`. -[`CD2DRectU` Class](../../mfc/reference/cd2drectu-class.md)
+[`CD2DRectU` Class](cd2drectu-class.md)\ A wrapper for `D2D1_RECT_U`. -[`CD2DResource` Class](../../mfc/reference/cd2dresource-class.md)
-An abstract class that provides a interface for creating and managing `D2D` resources such as brushes, layers, and texts. +[`CD2DResource` Class](cd2dresource-class.md)\ +An abstract class that provides an interface for creating and managing `D2D` resources such as brushes, layers, and texts. -[`CD2DRoundedRect` Class](../../mfc/reference/cd2droundedrect-class.md)
+[`CD2DRoundedRect` Class](cd2droundedrect-class.md)\ A wrapper for `D2D1_ROUNDED_RECT`. -[`CD2DSizeF` Class](../../mfc/reference/cd2dsizef-class.md)
+[`CD2DSizeF` Class](cd2dsizef-class.md)\ A wrapper for `D2D1_SIZE_F`. -[`CD2DSizeU` Class](../../mfc/reference/cd2dsizeu-class.md)
+[`CD2DSizeU` Class](cd2dsizeu-class.md)\ A wrapper for `D2D1_SIZE_U`. -[`CD2DSolidColorBrush` Class](../../mfc/reference/cd2dsolidcolorbrush-class.md)
+[`CD2DSolidColorBrush` Class](cd2dsolidcolorbrush-class.md)\ A wrapper for `ID2D1SolidColorBrush`. -[`CD2DTextFormat` Class](../../mfc/reference/cd2dtextformat-class.md)
+[`CD2DTextFormat` Class](cd2dtextformat-class.md)\ A wrapper for `IDWriteTextFormat`. -[`CD2DTextLayout` Class](../../mfc/reference/cd2dtextlayout-class.md)
+[`CD2DTextLayout` Class](cd2dtextlayout-class.md)\ A wrapper for `IDWriteTextLayout`. -[`CDaoDatabase` Class](../../mfc/reference/cdaodatabase-class.md)
+[`CDaoDatabase` Class](cdaodatabase-class.md)\ Represents a connection to a database through which you can operate on the data. -[`CDaoException` Class](../../mfc/reference/cdaoexception-class.md)
+[`CDaoException` Class](cdaoexception-class.md)\ Represents an exception condition arising from the MFC database classes based on data access objects (DAO). -[`CDaoFieldExchange` Class](../../mfc/reference/cdaofieldexchange-class.md)
+[`CDaoFieldExchange` Class](cdaofieldexchange-class.md)\ Supports the DAO record field exchange (DFX) routines used by the DAO database classes. -[`CDaoQueryDef` Class](../../mfc/reference/cdaoquerydef-class.md)
+[`CDaoQueryDef` Class](cdaoquerydef-class.md)\ Represents a query definition, or "querydef," usually one saved in a database. -[`CDaoRecordset` Class](../../mfc/reference/cdaorecordset-class.md)
+[`CDaoRecordset` Class](cdaorecordset-class.md)\ Represents a set of records selected from a data source. -[`CDaoRecordView` Class](../../mfc/reference/cdaorecordview-class.md)
+[`CDaoRecordView` Class](cdaorecordview-class.md)\ A view that displays database records in controls. -[`CDaoTableDef` Class](../../mfc/reference/cdaotabledef-class.md)
+[`CDaoTableDef` Class](cdaotabledef-class.md)\ Represents the stored definition of a base table or an attached table. -[`CDaoWorkspace` Class](../../mfc/reference/cdaoworkspace-class.md)
+[`CDaoWorkspace` Class](cdaoworkspace-class.md)\ Manages a named, password-protected database session from login to logoff, by a single user. -[`CDatabase` Class](../../mfc/reference/cdatabase-class.md)
+[`CDatabase` Class](cdatabase-class.md)\ Represents a connection to a data source, through which you can operate on the data source. -[`CDataExchange` Class](../../mfc/reference/cdataexchange-class.md)
+[`CDataExchange` Class](cdataexchange-class.md)\ Supports the dialog data exchange (DDX) and dialog data validation (DDV) routines used by the Microsoft Foundation classes. -[`CDataPathProperty` Class](../../mfc/reference/cdatapathproperty-class.md)
+[`CDataPathProperty` Class](cdatapathproperty-class.md)\ Implements an OLE control property that can be loaded asynchronously. -[`CDataRecoveryHandler` Class](../../mfc/reference/cdatarecoveryhandler-class.md)
+[`CDataRecoveryHandler` Class](cdatarecoveryhandler-class.md)\ Autosaves documents and restores them if an application unexpectedly exits. -[`CDateTimeCtrl` Class](../../mfc/reference/cdatetimectrl-class.md)
+[`CDateTimeCtrl` Class](cdatetimectrl-class.md)\ Encapsulates the functionality of a date and time picker control. -[`CDBException` Class](../../mfc/reference/cdbexception-class.md)
+[`CDBException` Class](cdbexception-class.md)\ Represents an exception condition arising from the database classes. -[`CDBVariant` Class](../../mfc/reference/cdbvariant-class.md)
+[`CDBVariant` Class](cdbvariant-class.md)\ Represents a variant data type for the MFC ODBC classes. -[`CDC` Class](../../mfc/reference/cdc-class.md)
+[`CDC` Class](cdc-class.md)\ Defines a class of device-context objects. -[`CDCRenderTarget` Class](../../mfc/reference/cdcrendertarget-class.md)
+[`CDCRenderTarget` Class](cdcrendertarget-class.md)\ A wrapper for `ID2D1DCRenderTarget`. -[`CDHtmlDialog` Class](../../mfc/reference/cdhtmldialog-class.md)
+[`CDHtmlDialog` Class](cdhtmldialog-class.md)\ Used to create dialog boxes that use HTML rather than dialog resources to implement their user interface. -[`CDialog` Class](../../mfc/reference/cdialog-class.md)
+[`CDialog` Class](cdialog-class.md)\ Base class used for displaying dialog boxes on the screen. -[`CDialogBar` Class](../../mfc/reference/cdialogbar-class.md)
+[`CDialogBar` Class](cdialogbar-class.md)\ Provides the functionality of a Windows modeless dialog box in a control bar. -[`CDialogEx` Class](../../mfc/reference/cdialogex-class.md)
+[`CDialogEx` Class](cdialogex-class.md)\ Specifies the background color and background image of a dialog box. -[`CDiscreteTransition` Class](../../mfc/reference/cdiscretetransition-class.md)
+[`CDiscreteTransition` Class](cdiscretetransition-class.md)\ Encapsulates a discrete transition. -[`CDocItem` Class](../../mfc/reference/cdocitem-class.md)
+[`CDocItem` Class](cdocitem-class.md)\ The base class for document items, which are components of a document's data. -[`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md)
+[`CDockablePane` Class](cdockablepane-class.md)\ Implements a pane that can either be docked in a dock site or included in a tabbed pane. -[`CDockablePaneAdapter` Class](../../mfc/reference/cdockablepaneadapter-class.md)
+[`CDockablePaneAdapter` Class](cdockablepaneadapter-class.md)\ Provides docking support for `CWnd`-derived panes. -[`CDockingManager` Class](../../mfc/reference/cdockingmanager-class.md)
+[`CDockingManager` Class](cdockingmanager-class.md)\ Implements the core functionality that controls docking layout in a main frame window. -[`CDockingPanesRow` Class](../../mfc/reference/cdockingpanesrow-class.md)
+[`CDockingPanesRow` Class](cdockingpanesrow-class.md)\ Manages a list of panes that are located in the same horizontal or vertical row (column) of a dock site. -[`CDockSite` Class](../../mfc/reference/cdocksite-class.md)
-Provides functionality for arranging panes that are derived from the [`CPane` Class](../../mfc/reference/cpane-class.md) into sets of rows. +[`CDockSite` Class](cdocksite-class.md)\ +Provides functionality for arranging panes that are derived from the [`CPane` Class](cpane-class.md) into sets of rows. -[`CDockState` Class](../../mfc/reference/cdockstate-class.md)
+[`CDockState` Class](cdockstate-class.md)\ A serialized `CObject` class that loads, unloads, or clears the state of one or more docking control bars in persistent memory (a file). -[`CDocObjectServer` Class](../../mfc/reference/cdocobjectserver-class.md)
+[`CDocObjectServer` Class](cdocobjectserver-class.md)\ Implements the additional OLE interfaces needed to make a normal `COleDocument` server into a full DocObject server: `IOleDocument`, `IOleDocumentView`, `IOleCommandTarget`, and `IPrint`. -[`CDocObjectServerItem` Class](../../mfc/reference/cdocobjectserveritem-class.md)
+[`CDocObjectServerItem` Class](cdocobjectserveritem-class.md)\ Implements OLE server verbs specifically for DocObject servers. -[`CDocTemplate` Class](../../mfc/reference/cdoctemplate-class.md)
+[`CDocTemplate` Class](cdoctemplate-class.md)\ An abstract base class that defines the basic functionality for document templates. -[`CDocument` Class](../../mfc/reference/cdocument-class.md)
+[`CDocument` Class](cdocument-class.md)\ Provides the basic functionality for user-defined document classes. -[`CDragListBox` Class](../../mfc/reference/cdraglistbox-class.md)
+[`CDragListBox` Class](cdraglistbox-class.md)\ In addition to providing the functionality of a Windows list box, the `CDragListBox` class lets the user move list box items, such as filenames, within the list box. -[`CDrawingManager` Class](../../mfc/reference/cdrawingmanager-class.md)
+[`CDrawingManager` Class](cdrawingmanager-class.md)\ Implements complex drawing algorithms. -[`CDumpContext` Class](../../mfc/reference/cdumpcontext-class.md)
+[`CDumpContext` Class](cdumpcontext-class.md)\ Supports stream-oriented diagnostic output in the form of human-readable text. -[`CDWordArray` Class](../../mfc/reference/cdwordarray-class.md)
+[`CDWordArray` Class](cdwordarray-class.md)\ Supports arrays of 32-bit doublewords. -[`CEdit` Class](../../mfc/reference/cedit-class.md)
+[`CEdit` Class](cedit-class.md)\ Provides the functionality of a Windows edit control. -[`CEditView` Class](../../mfc/reference/ceditview-class.md)
+[`CEditView` Class](ceditview-class.md)\ A type of view class that provides the functionality of a Windows edit control and can be used to implement simple text-editor functionality. -[`CEvent` Class](../../mfc/reference/cevent-class.md)
+[`CEvent` Class](cevent-class.md)\ Represents an "event", which is a synchronization object that enables one thread to notify another that an event has occurred. -[`CException` Class](../../mfc/reference/cexception-class.md)
+[`CException` Class](cexception-class.md)\ The base class for all exceptions in the Microsoft Foundation Class Library. -[`CFieldExchange` Class](../../mfc/reference/cfieldexchange-class.md)
+[`CFieldExchange` Class](cfieldexchange-class.md)\ Supports the record field exchange (RFX) and bulk record field exchange (Bulk RFX) routines used by the database classes. -[`CFile` Class](../../mfc/reference/cfile-class.md)
+[`CFile` Class](cfile-class.md)\ The base class for Microsoft Foundation Class file classes. -[`CFileDialog` Class](../../mfc/reference/cfiledialog-class.md)
+[`CFileDialog` Class](cfiledialog-class.md)\ Encapsulates the common file dialog box for Windows. -[`CFileException` Class](../../mfc/reference/cfileexception-class.md)
+[`CFileException` Class](cfileexception-class.md)\ Represents a file-related exception condition. -[`CFileFind` Class](../../mfc/reference/cfilefind-class.md)
-Performs local file searches and is the base class for [`CGopherFileFind` Class](../../mfc/reference/cgopherfilefind-class.md) and [`CFtpFileFind` Class](../../mfc/reference/cftpfilefind-class.md), which perform Internet file searches. +[`CFileFind` Class](cfilefind-class.md)\ +Performs local file searches and is the base class for [`CGopherFileFind` Class](cgopherfilefind-class.md) and [`CFtpFileFind` Class](cftpfilefind-class.md), which perform Internet file searches. -[`CFindReplaceDialog` Class](../../mfc/reference/cfindreplacedialog-class.md)
+[`CFindReplaceDialog` Class](cfindreplacedialog-class.md)\ Lets you implement standard string Find/Replace dialog boxes in your application. -[`CFolderPickerDialog` Class](../../mfc/reference/cfolderpickerdialog-class.md)
+[`CFolderPickerDialog` Class](cfolderpickerdialog-class.md)\ Implements `CFileDialog` in the folder picker mode. -[`CFont` Class](../../mfc/reference/cfont-class.md)
+[`CFont` Class](cfont-class.md)\ Encapsulates a Windows graphics device interface (GDI) font and provides member functions for manipulating the font. -[`CFontDialog` Class](../../mfc/reference/cfontdialog-class.md)
+[`CFontDialog` Class](cfontdialog-class.md)\ Lets you incorporate a font-selection dialog box into your application. -[`CFontHolder` Class](../../mfc/reference/cfontholder-class.md)
+[`CFontHolder` Class](cfontholder-class.md)\ Implements the stock Font property and encapsulates the functionality of a Windows font object and the `IFont` interface. -[`CFormView` Class](../../mfc/reference/cformview-class.md)
+[`CFormView` Class](cformview-class.md)\ The base class used for form views. -[`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md)
+[`CFrameWnd` Class](cframewnd-class.md)\ Provides the functionality of a Windows single document interface (SDI) overlapped or pop-up frame window, along with members for managing the window. -[`CFrameWndEx` Class](../../mfc/reference/cframewndex-class.md)
-Implements the functionality of a Windows single document interface (SDI) overlapped or popup frame window, and provides members for managing the window. It extends the [`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md) class. +[`CFrameWndEx` Class](cframewndex-class.md)\ +Implements the functionality of a Windows single document interface (SDI) overlapped or popup frame window, and provides members for managing the window. It extends the [`CFrameWnd` Class](cframewnd-class.md) class. -[`CFtpConnection` Class](../../mfc/reference/cftpconnection-class.md)
+[`CFtpConnection` Class](cftpconnection-class.md)\ Manages your FTP connection to an Internet server and enables direct manipulation of directories and files on that server. -[`CFtpFileFind` Class](../../mfc/reference/cftpfilefind-class.md)
+[`CFtpFileFind` Class](cftpfilefind-class.md)\ Aids in Internet file searches of FTP servers. -[`CGdiObject` Class](../../mfc/reference/cgdiobject-class.md)
+[`CGdiObject` Class](cgdiobject-class.md)\ Provides a base class for various kinds of Windows graphics device interface (GDI) objects such as bitmaps, regions, brushes, pens, palettes, and fonts. -[`CGopherConnection` Class](../../mfc/reference/cgopherconnection-class.md)
+[`CGopherConnection` Class](cgopherconnection-class.md)\ Manages your connection to a gopher Internet server. -[`CGopherFile` Class](../../mfc/reference/cgopherfile-class.md)
+[`CGopherFile` Class](cgopherfile-class.md)\ Provides the functionality to find and read files on a gopher server. -[`CGopherFileFind` Class](../../mfc/reference/cgopherfilefind-class.md)
+[`CGopherFileFind` Class](cgopherfilefind-class.md)\ Aids in Internet file searches of gopher servers. -[`CGopherLocator` Class](../../mfc/reference/cgopherlocator-class.md)
-Gets a gopher "locator" from a gopher server, determines the locator's type, and makes the locator available to [`CGopherFileFind` Class](../../mfc/reference/cgopherfilefind-class.md). +[`CGopherLocator` Class](cgopherlocator-class.md)\ +Gets a gopher "locator" from a gopher server, determines the locator's type, and makes the locator available to [`CGopherFileFind` Class](cgopherfilefind-class.md). -[`CHeaderCtrl` Class](../../mfc/reference/cheaderctrl-class.md)
+[`CHeaderCtrl` Class](cheaderctrl-class.md)\ Provides the functionality of the Windows common header control. -[`CHotKeyCtrl` Class](../../mfc/reference/chotkeyctrl-class.md)
+[`CHotKeyCtrl` Class](chotkeyctrl-class.md)\ Provides the functionality of the Windows common hot key control. -[`CHtmlEditCtrl` Class](../../mfc/reference/chtmleditctrl-class.md)
+[`CHtmlEditCtrl` Class](chtmleditctrl-class.md)\ Provides the functionality of the `WebBrowser` ActiveX control in an MFC window. -[`CHtmlEditCtrlBase` Class](../../mfc/reference/chtmleditctrlbase-class.md)
+[`CHtmlEditCtrlBase` Class](chtmleditctrlbase-class.md)\ Represents an HTML editing component. -[`CHtmlEditDoc` Class](../../mfc/reference/chtmleditdoc-class.md)
-With [`CHtmlEditView` Class](../../mfc/reference/chtmleditview-class.md), provides the functionality of the WebBrowser editing platform within the context of the MFC document-view architecture. +[`CHtmlEditDoc` Class](chtmleditdoc-class.md)\ +With [`CHtmlEditView` Class](chtmleditview-class.md), provides the functionality of the WebBrowser editing platform within the context of the MFC document-view architecture. -[`CHtmlEditView` Class](../../mfc/reference/chtmleditview-class.md)
+[`CHtmlEditView` Class](chtmleditview-class.md)\ Provides the functionality of the WebBrowser editing platform within the context of MFC's document/view architecture. -[`CHtmlView` Class](../../mfc/reference/chtmlview-class.md)
+[`CHtmlView` Class](chtmlview-class.md)\ Provides the functionality of the WebBrowser control within the context of MFC's document/view architecture. -[`CHttpConnection` Class](../../mfc/reference/chttpconnection-class.md)
+[`CHttpConnection` Class](chttpconnection-class.md)\ Manages your connection to an HTTP server. -[`CHttpFile` Class](../../mfc/reference/chttpfile-class.md)
+[`CHttpFile` Class](chttpfile-class.md)\ Provides the functionality to request and read files on an HTTP server. -[`CHwndRenderTarget` Class](../../mfc/reference/chwndrendertarget-class.md)
+[`CHwndRenderTarget` Class](chwndrendertarget-class.md)\ A wrapper for `ID2D1HwndRenderTarget`. -[`CImageList` Class](../../mfc/reference/cimagelist-class.md)
+[`CImageList` Class](cimagelist-class.md)\ Provides the functionality of the Windows common image list control. -[`CInstantaneousTransition` Class](../../mfc/reference/cinstantaneoustransition-class.md)
+[`CInstantaneousTransition` Class](cinstantaneoustransition-class.md)\ Encapsulates an instantaneous transition. -[`CInternetConnection` Class](../../mfc/reference/cinternetconnection-class.md)
+[`CInternetConnection` Class](cinternetconnection-class.md)\ Manages your connection to an Internet server. -[`CInternetException` Class](../../mfc/reference/cinternetexception-class.md)
+[`CInternetException` Class](cinternetexception-class.md)\ Represents an exception condition related to an Internet operation. -[`CInternetFile` Class](../../mfc/reference/cinternetfile-class.md)
+[`CInternetFile` Class](cinternetfile-class.md)\ Enables access to files on remote systems that use Internet protocols. -[`CInternetSession` Class](../../mfc/reference/cinternetsession-class.md)
+[`CInternetSession` Class](cinternetsession-class.md)\ Creates and initializes a single or several simultaneous Internet sessions and, if necessary, describes your connection to a proxy server. -[`CInterpolatorBase` Class](../../mfc/reference/cinterpolatorbase-class.md)
+[`CInterpolatorBase` Class](cinterpolatorbase-class.md)\ Implements a callback, which is called by the Animation API when it has to calculate a new value of an animation variable. -[`CInvalidArgException` Class](../../mfc/reference/cinvalidargexception-class.md)
+[`CInvalidArgException` Class](cinvalidargexception-class.md)\ This class represents an invalid argument exception condition. -[`CIPAddressCtrl` Class](../../mfc/reference/cipaddressctrl-class.md)
+[`CIPAddressCtrl` Class](cipaddressctrl-class.md)\ Provides the functionality of the Windows common IP Address control. -[`CJumpList` Class](../../mfc/reference/cjumplist-class.md)
+[`CJumpList` Class](cjumplist-class.md)\ The list of shortcuts revealed when you right click on an icon in the task bar. -[`CKeyboardManager` Class](../../mfc/reference/ckeyboardmanager-class.md)
+[`CKeyboardManager` Class](ckeyboardmanager-class.md)\ Manages shortcut key tables for the main frame window and child frame windows. -[`CKeyFrame` Class](../../mfc/reference/ckeyframe-class.md)
+[`CKeyFrame` Class](ckeyframe-class.md)\ Represents an animation keyframe. -[`CLinearTransition` Class](../../mfc/reference/clineartransition-class.md)
+[`CLinearTransition` Class](clineartransition-class.md)\ Encapsulates a linear transition. -[`CLinearTransitionFromSpeed` Class](../../mfc/reference/clineartransitionfromspeed-class.md)
+[`CLinearTransitionFromSpeed` Class](clineartransitionfromspeed-class.md)\ Encapsulates a linear-speed transition. -[`CLinkCtrl` Class](../../mfc/reference/clinkctrl-class.md)
+[`CLinkCtrl` Class](clinkctrl-class.md)\ Provides the functionality of the Windows common SysLink control. -[`CList` Class](../../mfc/reference/clist-class.md)
+[`CList` Class](clist-class.md)\ Supports ordered lists of nonunique objects accessible sequentially or by value. -[`CListBox` Class](../../mfc/reference/clistbox-class.md)
+[`CListBox` Class](clistbox-class.md)\ Provides the functionality of a Windows list box. -[`CListCtrl` Class](../../mfc/reference/clistctrl-class.md)
+[`CListCtrl` Class](clistctrl-class.md)\ Encapsulates the functionality of a "list view control," which displays a collection of items each consisting of an icon (from an image list) and a label. -[`CListView` Class](../../mfc/reference/clistview-class.md)
-Simplifies use of the list control and of [`CListCtrl` Class](../../mfc/reference/clistctrl-class.md), the class that encapsulates list-control functionality, with MFC's document-view architecture. +[`CListView` Class](clistview-class.md)\ +Simplifies use of the list control and of [`CListCtrl` Class](clistctrl-class.md), the class that encapsulates list-control functionality, with MFC's document-view architecture. -[`CLongBinary` Class](../../mfc/reference/clongbinary-class.md)
+[`CLongBinary` Class](clongbinary-class.md)\ Simplifies working with very large binary data objects (often called BLOBs, or "binary large objects") in a database. -[`CMap` Class](../../mfc/reference/cmap-class.md)
+[`CMap` Class](cmap-class.md)\ A dictionary collection class that maps unique keys to values. -[`CMapPtrToPtr` Class](../../mfc/reference/cmapptrtoptr-class.md)
+[`CMapPtrToPtr` Class](cmapptrtoptr-class.md)\ Supports maps of void pointers keyed by void pointers. -[`CMapPtrToWord` Class](../../mfc/reference/cmapptrtoword-class.md)
+[`CMapPtrToWord` Class](cmapptrtoword-class.md)\ Supports maps of 16-bit words keyed by void pointers. -[`CMapStringToOb` Class](../../mfc/reference/cmapstringtoob-class.md)
+[`CMapStringToOb` Class](cmapstringtoob-class.md)\ A dictionary collection class that maps unique `CString` objects to `CObject` pointers. -[`CMapStringToPtr` Class](../../mfc/reference/cmapstringtoptr-class.md)
+[`CMapStringToPtr` Class](cmapstringtoptr-class.md)\ Supports maps of void pointers keyed by `CString` objects. -[`CMapStringToString` Class](../../mfc/reference/cmapstringtostring-class.md)
+[`CMapStringToString` Class](cmapstringtostring-class.md)\ Supports maps of `CString` objects keyed by `CString` objects. -[`CMapWordToOb` Class](../../mfc/reference/cmapwordtoob-class.md)
+[`CMapWordToOb` Class](cmapwordtoob-class.md)\ Supports maps of `CObject` pointers keyed by 16-bit words. -[`CMapWordToPtr` Class](../../mfc/reference/cmapwordtoptr-class.md)
+[`CMapWordToPtr` Class](cmapwordtoptr-class.md)\ Supports maps of void pointers keyed by 16-bit words. -[`CMDIChildWnd` Class](../../mfc/reference/cmdichildwnd-class.md)
+[`CMDIChildWnd` Class](cmdichildwnd-class.md)\ Provides the functionality of a Windows multiple document interface (MDI) child window, along with members for managing the window. -[`CMDIChildWndEx` Class](../../mfc/reference/cmdichildwndex-class.md)
-Provides the functionality of a Windows multiple document interface (MDI) child window. It extends the functionality of [`CMDIChildWnd` Class](../../mfc/reference/cmdichildwnd-class.md). The framework requires this class when an MDI application uses certain MFC classes. +[`CMDIChildWndEx` Class](cmdichildwndex-class.md)\ +Provides the functionality of a Windows multiple document interface (MDI) child window. It extends the functionality of [`CMDIChildWnd` Class](cmdichildwnd-class.md). The framework requires this class when an MDI application uses certain MFC classes. -[`CMDIFrameWnd` Class](../../mfc/reference/cmdiframewnd-class.md)
+[`CMDIFrameWnd` Class](cmdiframewnd-class.md)\ Provides the functionality of a Windows multiple document interface (MDI) frame window, along with members for managing the window. -[`CMDIFrameWndEx` Class](../../mfc/reference/cmdiframewndex-class.md)
-Extends the functionality of [`CFrameWnd` Class](../../mfc/reference/cframewnd-class.md), a Windows Multiple Document Interface (MDI) frame window. +[`CMDIFrameWndEx` Class](cmdiframewndex-class.md)\ +Extends the functionality of [`CFrameWnd` Class](cframewnd-class.md), a Windows Multiple Document Interface (MDI) frame window. -[`CMDITabInfo` Class](../../mfc/reference/cmditabinfo-class.md)
-Used to pass parameters to [`CMDIFrameWndEx::EnableMDITabbedGroups`](../../mfc/reference/cmdiframewndex-class.md#enablemditabbedgroups) method. Set members of this class to control the behavior of MDI tabbed groups. +[`CMDITabInfo` Class](cmditabinfo-class.md)\ +Used to pass parameters to [`CMDIFrameWndEx::EnableMDITabbedGroups`](cmdiframewndex-class.md#enablemditabbedgroups) method. Set members of this class to control the behavior of MDI tabbed groups. -[`CMemFile` Class](../../mfc/reference/cmemfile-class.md)
-The [`CFile` Class](../../mfc/reference/cfile-class.md)-derived class that supports memory files. +[`CMemFile` Class](cmemfile-class.md)\ +The [`CFile` Class](cfile-class.md)-derived class that supports memory files. -[`CMemoryException` Class](../../mfc/reference/cmemoryexception-class.md)
+[`CMemoryException` Class](cmemoryexception-class.md)\ Represents an out-of-memory exception condition. -[`CMenu` Class](../../mfc/reference/cmenu-class.md)
+[`CMenu` Class](cmenu-class.md)\ An encapsulation of the Windows `HMENU`. -[`CMenuTearOffManager` Class](../../mfc/reference/cmenutearoffmanager-class.md)
+[`CMenuTearOffManager` Class](cmenutearoffmanager-class.md)\ Manages tear-off menus. A tear-off menu is a menu on the menu bar. The user can remove a tear-off menu from the menu bar, causing the tear-off menu to float. -[`CMetaFileDC` Class](../../mfc/reference/cmetafiledc-class.md)
+[`CMetaFileDC` Class](cmetafiledc-class.md)\ Implements a Windows metafile, which contains a sequence of graphics device interface (GDI) commands that you can replay to create a desired image or text. -[`CMFCAcceleratorKey` Class](../../mfc/reference/cmfcacceleratorkey-class.md)
+[`CMFCAcceleratorKey` Class](cmfcacceleratorkey-class.md)\ Helper class that implements virtual key mapping and formatting. -[`CMFCAcceleratorKeyAssignCtrl` Class](../../mfc/reference/cmfcacceleratorkeyassignctrl-class.md)
-Extends the [`CEdit` Class](../../mfc/reference/cedit-class.md) to support extra system buttons such as ALT, CONTROL, and SHIFT. +[`CMFCAcceleratorKeyAssignCtrl` Class](cmfcacceleratorkeyassignctrl-class.md)\ +Extends the [`CEdit` Class](cedit-class.md) to support extra system buttons such as ALT, CONTROL, and SHIFT. -[`CMFCAutoHideButton` Class](../../mfc/reference/cmfcautohidebutton-class.md)
-A button that displays or hides a [`CDockablePane` Class](../../mfc/reference/cdockablepane-class.md) that is configured to hide. +[`CMFCAutoHideButton` Class](cmfcautohidebutton-class.md)\ +A button that displays or hides a [`CDockablePane` Class](cdockablepane-class.md) that is configured to hide. -[`CMFCBaseTabCtrl` Class](../../mfc/reference/cmfcbasetabctrl-class.md)
+[`CMFCBaseTabCtrl` Class](cmfcbasetabctrl-class.md)\ Implements the base functionality for tabbed windows. -[`CMFCButton` Class](../../mfc/reference/cmfcbutton-class.md)
-Adds functionality to the [`CButton` Class](../../mfc/reference/cbutton-class.md) class such as aligning button text, combining button text and an image, selecting a cursor, and specifying a tool tip. +[`CMFCButton` Class](cmfcbutton-class.md)\ +Adds functionality to the [`CButton` Class](cbutton-class.md) class such as aligning button text, combining button text and an image, selecting a cursor, and specifying a tool tip. -[`CMFCCaptionBar` Class](../../mfc/reference/cmfccaptionbar-class.md)
+[`CMFCCaptionBar` Class](cmfccaptionbar-class.md)\ Control bar that can display three elements: a button, a text label, and a bitmap. It can only display one element of each type at a time. You can align each element to the left or right edges of the control or to the center. You can also apply a flat or 3D style to the top and bottom borders of the caption bar. -[`CMFCCaptionButton` Class](../../mfc/reference/cmfccaptionbutton-class.md)
+[`CMFCCaptionButton` Class](cmfccaptionbutton-class.md)\ Implements a button that is displayed on the caption bar for a docking pane or a mini-frame window. Typically, the framework creates caption buttons automatically. -[`CMFCColorBar` Class](../../mfc/reference/cmfccolorbar-class.md)
+[`CMFCColorBar` Class](cmfccolorbar-class.md)\ Represents a docking control bar that can select colors in a document or application. -[`CMFCColorButton` Class](../../mfc/reference/cmfccolorbutton-class.md)
-The `CMFCColorButton` and [`CMFCColorBar` Class](../../mfc/reference/cmfccolorbar-class.md) classes are used together to implement a color picker control. +[`CMFCColorButton` Class](cmfccolorbutton-class.md)\ +The `CMFCColorButton` and [`CMFCColorBar` Class](cmfccolorbar-class.md) classes are used together to implement a color picker control. -[`CMFCColorDialog` Class](../../mfc/reference/cmfccolordialog-class.md)
+[`CMFCColorDialog` Class](cmfccolordialog-class.md)\ Represents a color selection dialog box. -[`CMFCColorMenuButton` Class](../../mfc/reference/cmfccolormenubutton-class.md)
+[`CMFCColorMenuButton` Class](cmfccolormenubutton-class.md)\ Supports a menu command or a toolbar button that starts a color picker dialog box. -[`CMFCColorPickerCtrl` Class](../../mfc/reference/cmfccolorpickerctrl-class.md)
+[`CMFCColorPickerCtrl` Class](cmfccolorpickerctrl-class.md)\ Provides functionality for a control that is used to select colors. -[`CMFCDesktopAlertDialog` Class](../../mfc/reference/cmfcdesktopalertdialog-class.md)
-Used together with the [`CMFCDesktopAlertWnd` Class](../../mfc/reference/cmfcdesktopalertwnd-class.md) to display a custom dialog in a popup window. +[`CMFCDesktopAlertDialog` Class](cmfcdesktopalertdialog-class.md)\ +Used together with the [`CMFCDesktopAlertWnd` Class](cmfcdesktopalertwnd-class.md) to display a custom dialog in a popup window. -[`CMFCDesktopAlertWnd` Class](../../mfc/reference/cmfcdesktopalertwnd-class.md)
+[`CMFCDesktopAlertWnd` Class](cmfcdesktopalertwnd-class.md)\ Implements the functionality of a modeless dialog box which appears on the screen to inform the user about an event. -[`CMFCDesktopAlertWndInfo` Class](../../mfc/reference/cmfcdesktopalertwndinfo-class.md)
-Used with the [`CMFCDesktopAlertWnd` Class](../../mfc/reference/cmfcdesktopalertwnd-class.md). It specifies the controls that are displayed if the desktop alert window pops up. +[`CMFCDesktopAlertWndInfo` Class](cmfcdesktopalertwndinfo-class.md)\ +Used with the [`CMFCDesktopAlertWnd` Class](cmfcdesktopalertwnd-class.md). It specifies the controls that are displayed if the desktop alert window pops up. -[`CMFCDragFrameImpl` Class](../../mfc/reference/cmfcdragframeimpl-class.md)
+[`CMFCDragFrameImpl` Class](cmfcdragframeimpl-class.md)\ Draws the drag rectangle that appears when the user drags a pane in the standard dock mode. -[`CMFCDropDownToolBar` Class](../../mfc/reference/cmfcdropdowntoolbar-class.md)
+[`CMFCDropDownToolBar` Class](cmfcdropdowntoolbar-class.md)\ A toolbar that appears when the user presses and holds a top-level toolbar button. -[`CMFCDropDownToolbarButton` Class](../../mfc/reference/cmfcdropdowntoolbarbutton-class.md)
-A type of toolbar button that behaves like a regular button when it is clicked. However, it opens a drop-down toolbar ([`CMFCDropDownToolBar` Class](../../mfc/reference/cmfcdropdowntoolbar-class.md) if the user presses and holds the toolbar button down. +[`CMFCDropDownToolbarButton` Class](cmfcdropdowntoolbarbutton-class.md)\ +A type of toolbar button that behaves like a regular button when it is clicked. However, it opens a drop-down toolbar ([`CMFCDropDownToolBar` Class](cmfcdropdowntoolbar-class.md)) if the user presses and holds the toolbar button down. -[`CMFCDynamicLayout` Class](../../mfc/reference/cmfcdynamiclayout-class.md)
+[`CMFCDynamicLayout` Class](cmfcdynamiclayout-class.md)\ Specifies how controls in a window are moved and resized as the user resizes the window. -[`CMFCEditBrowseCtrl` Class](../../mfc/reference/cmfceditbrowsectrl-class.md)
+[`CMFCEditBrowseCtrl` Class](cmfceditbrowsectrl-class.md)\ Supports the edit browse control, which is an editable text box that optionally contains a browse button. When the user clicks the browse button, the control performs a custom action or displays a standard dialog box that contains a file browser or a folder browser. -[`CMFCFilterChunkValueImpl` Class](../../mfc/reference/cmfcfilterchunkvalueimpl-class.md)
+[`CMFCFilterChunkValueImpl` Class](cmfcfilterchunkvalueimpl-class.md)\ Simplifies both chunk and property value pair logic. -[`CMFCFontComboBox` Class](../../mfc/reference/cmfcfontcombobox-class.md)
+[`CMFCFontComboBox` Class](cmfcfontcombobox-class.md)\ Creates a combo box control that contains a list of fonts. -[`CMFCFontInfo` Class](../../mfc/reference/cmfcfontinfo-class.md)
+[`CMFCFontInfo` Class](cmfcfontinfo-class.md)\ Describes the name and other attributes of a font. -[`CMFCHeaderCtrl` Class](../../mfc/reference/cmfcheaderctrl-class.md)
+[`CMFCHeaderCtrl` Class](cmfcheaderctrl-class.md)\ Supports sorting multiple columns in a header control. -[`CMFCImageEditorDialog` Class](../../mfc/reference/cmfcimageeditordialog-class.md)
+[`CMFCImageEditorDialog` Class](cmfcimageeditordialog-class.md)\ Supports an image editor dialog box. -[`CMFCKeyMapDialog` Class](../../mfc/reference/cmfckeymapdialog-class.md)
+[`CMFCKeyMapDialog` Class](cmfckeymapdialog-class.md)\ Supports a control that maps commands to keys on the keyboard. -[`CMFCLinkCtrl` Class](../../mfc/reference/cmfclinkctrl-class.md)
+[`CMFCLinkCtrl` Class](cmfclinkctrl-class.md)\ Displays a button as a hyperlink and invokes the link's target when the button is clicked. -[`CMFCListCtrl` Class](../../mfc/reference/cmfclistctrl-class.md)
-Extends the functionality of [`CListCtrl` Class](../../mfc/reference/clistctrl-class.md) class by supporting the advanced header control functionality of the [`CMFCHeaderCtrl` Class](../../mfc/reference/cmfcheaderctrl-class.md). +[`CMFCListCtrl` Class](cmfclistctrl-class.md)\ +Extends the functionality of [`CListCtrl` Class](clistctrl-class.md) class by supporting the advanced header control functionality of the [`CMFCHeaderCtrl` Class](cmfcheaderctrl-class.md). -[`CMFCMaskedEdit` Class](../../mfc/reference/cmfcmaskededit-class.md)
+[`CMFCMaskedEdit` Class](cmfcmaskededit-class.md)\ Supports a masked edit control, which validates user input against a mask and displays the validated results according to a template. -[`CMFCMenuBar` Class](../../mfc/reference/cmfcmenubar-class.md)
+[`CMFCMenuBar` Class](cmfcmenubar-class.md)\ A menu bar that implements docking. -[`CMFCMenuButton` Class](../../mfc/reference/cmfcmenubutton-class.md)
+[`CMFCMenuButton` Class](cmfcmenubutton-class.md)\ A button that displays a pop-up menu and reports on the user's menu selections. -[`CMFCOutlookBar` Class](../../mfc/reference/cmfcoutlookbar-class.md)
-A tabbed pane with the visual appearance of the **Navigation Pane** in Microsoft Outlook 2000 or Outlook 2003. The `CMFCOutlookBar` object contains a [`CMFCOutlookBarTabCtrl` Class](../../mfc/reference/cmfcoutlookbartabctrl-class.md) object and a series of tabs. The tabs can be either [`CMFCOutlookBarPane` Class](../../mfc/reference/cmfcoutlookbarpane-class.md) objects or `CWnd`-derived objects. To the user, the Outlook bar appears as a series of buttons and a display area. When the user clicks a button, the corresponding control or button pane is displayed. +[`CMFCOutlookBar` Class](cmfcoutlookbar-class.md)\ +A tabbed pane with the visual appearance of the **Navigation Pane** in Microsoft Outlook 2000 or Outlook 2003. The `CMFCOutlookBar` object contains a [`CMFCOutlookBarTabCtrl` Class](cmfcoutlookbartabctrl-class.md) object and a series of tabs. The tabs can be either [`CMFCOutlookBarPane` Class](cmfcoutlookbarpane-class.md) objects or `CWnd`-derived objects. To the user, the Outlook bar appears as a series of buttons and a display area. When the user clicks a button, the corresponding control or button pane is displayed. -[`CMFCOutlookBarPane` Class](../../mfc/reference/cmfcoutlookbarpane-class.md)
-A control derived from [`CMFCToolBar` Class](../../mfc/reference/cmfctoolbar-class.md) that can be inserted into an Outlook bar ([`CMFCOutlookBar` Class](../../mfc/reference/cmfcoutlookbar-class.md)). The Outlook bar pane contains a column of large buttons. The user can scroll up and down the list of buttons if it is larger than the pane. When the user detaches an Outlook bar pane from the Outlook bar, it can float or dock in the main frame window. +[`CMFCOutlookBarPane` Class](cmfcoutlookbarpane-class.md)\ +A control derived from [`CMFCToolBar` Class](cmfctoolbar-class.md) that can be inserted into an Outlook bar ([`CMFCOutlookBar` Class](cmfcoutlookbar-class.md)). The Outlook bar pane contains a column of large buttons. The user can scroll up and down the list of buttons if it is larger than the pane. When the user detaches an Outlook bar pane from the Outlook bar, it can float or dock in the main frame window. -[`CMFCOutlookBarTabCtrl` Class](../../mfc/reference/cmfcoutlookbartabctrl-class.md)
+[`CMFCOutlookBarTabCtrl` Class](cmfcoutlookbartabctrl-class.md)\ A tab control that has the visual appearance of the **Navigation Pane** in Microsoft Outlook. -[`CMFCPopupMenu` Class](../../mfc/reference/cmfcpopupmenu-class.md)
+[`CMFCPopupMenu` Class](cmfcpopupmenu-class.md)\ Implements Windows pop-up menu functionality and extends it by adding features such as tear-off menus and tooltips. -[`CMFCPopupMenuBar` Class](../../mfc/reference/cmfcpopupmenubar-class.md)
+[`CMFCPopupMenuBar` Class](cmfcpopupmenubar-class.md)\ A menu bar embedded into a pop-up menu. -[`CMFCPreviewCtrlImpl` Class](../../mfc/reference/cmfcpreviewctrlimpl-class.md)
+[`CMFCPreviewCtrlImpl` Class](cmfcpreviewctrlimpl-class.md)\ Implements a window that is placed on a host window provided by the Shell for Rich Preview. -[`CMFCPropertyGridColorProperty` Class](../../mfc/reference/cmfcpropertygridcolorproperty-class.md)
+[`CMFCPropertyGridColorProperty` Class](cmfcpropertygridcolorproperty-class.md)\ Supports a property list control item that opens a color selection dialog box. -[`CMFCPropertyGridCtrl` Class](../../mfc/reference/cmfcpropertygridctrl-class.md)
+[`CMFCPropertyGridCtrl` Class](cmfcpropertygridctrl-class.md)\ Supports an editable property grid control that can display properties in alphabetical or hierarchical order. -[`CMFCPropertyGridFileProperty` Class](../../mfc/reference/cmfcpropertygridfileproperty-class.md)
+[`CMFCPropertyGridFileProperty` Class](cmfcpropertygridfileproperty-class.md)\ Supports a property list control item that opens a file selection dialog box. -[`CMFCPropertyGridFontProperty` Class](../../mfc/reference/cmfcpropertygridfontproperty-class.md)
+[`CMFCPropertyGridFontProperty` Class](cmfcpropertygridfontproperty-class.md)\ Supports a property list control item that opens a font selection dialog box. -[`CMFCPropertyGridProperty` Class](../../mfc/reference/cmfcpropertygridproperty-class.md)
+[`CMFCPropertyGridProperty` Class](cmfcpropertygridproperty-class.md)\ Represents a list item in a property list control. -[`CMFCPropertyPage` Class](../../mfc/reference/cmfcpropertypage-class.md)
+[`CMFCPropertyPage` Class](cmfcpropertypage-class.md)\ Supports the display of pop-up menus on a property page. -[`CMFCPropertySheet` Class](../../mfc/reference/cmfcpropertysheet-class.md)
+[`CMFCPropertySheet` Class](cmfcpropertysheet-class.md)\ Supports a property sheet where each property page is denoted by a page tab, a toolbar button, a tree control node, or a list item. -[`CMFCReBar` Class](../../mfc/reference/cmfcrebar-class.md)
+[`CMFCReBar` Class](cmfcrebar-class.md)\ Control bar that provides layout, persistence, and state information for rebar controls. -[`CMFCRibbonApplicationButton` Class](../../mfc/reference/cmfcribbonapplicationbutton-class.md)
+[`CMFCRibbonApplicationButton` Class](cmfcribbonapplicationbutton-class.md)\ Implements a special button located in the top-left corner of the application window. When clicked, the button opens a menu that usually contains common **File** commands like **Open**, **Save**, and **Exit**. -[`CMFCRibbonBaseElement` Class](../../mfc/reference/cmfcribbonbaseelement-class.md)
-Base class for all elements that you can add to a [`CMFCRibbonBar` Class](../../mfc/reference/cmfcribbonbar-class.md). Examples of ribbon elements are ribbon buttons, ribbon check boxes, and ribbon combo boxes. +[`CMFCRibbonBaseElement` Class](cmfcribbonbaseelement-class.md)\ +Base class for all elements that you can add to a [`CMFCRibbonBar` Class](cmfcribbonbar-class.md). Examples of ribbon elements are ribbon buttons, ribbon check boxes, and ribbon combo boxes. -[`CMFCRibbonButton` Class](../../mfc/reference/cmfcribbonbutton-class.md)
+[`CMFCRibbonButton` Class](cmfcribbonbutton-class.md)\ Implements buttons that you can position on ribbon bar elements such as panels, Quick Access Toolbars, and pop-up menus. -[`CMFCRibbonButtonsGroup` Class](../../mfc/reference/cmfcribbonbuttonsgroup-class.md)
+[`CMFCRibbonButtonsGroup` Class](cmfcribbonbuttonsgroup-class.md)\ Lets you organize a set of ribbon buttons into a group. All buttons in the group are directly adjacent to each other horizontally and enclosed in a border. -[`CMFCRibbonCategory` Class](../../mfc/reference/cmfcribboncategory-class.md)
-Implements a ribbon tab that contains a group of [`CMFCRibbonPanel` Class](../../mfc/reference/cmfcribbonpanel-class.md). +[`CMFCRibbonCategory` Class](cmfcribboncategory-class.md)\ +Implements a ribbon tab that contains a group of [`CMFCRibbonPanel` Class](cmfcribbonpanel-class.md). -[`CMFCRibbonCheckBox` Class](../../mfc/reference/cmfcribboncheckbox-class.md)
+[`CMFCRibbonCheckBox` Class](cmfcribboncheckbox-class.md)\ Implements a check box that you can add to a ribbon panel, Quick Access Toolbar, or popup menu. -[`CMFCRibbonColorButton` Class](../../mfc/reference/cmfcribboncolorbutton-class.md)
+[`CMFCRibbonColorButton` Class](cmfcribboncolorbutton-class.md)\ Implements a color button that you can add to a ribbon bar. The ribbon color button displays a drop-down menu that contains one or more color palettes. -[`CMFCRibbonComboBox` Class](../../mfc/reference/cmfcribboncombobox-class.md)
+[`CMFCRibbonComboBox` Class](cmfcribboncombobox-class.md)\ Implements a combo box control that you can add to a ribbon bar, a ribbon panel, or a ribbon popup menu. -[`CMFCRibbonContextCaption` Class](../../mfc/reference/cmfcribboncontextcaption-class.md)
+[`CMFCRibbonContextCaption` Class](cmfcribboncontextcaption-class.md)\ Implements a colored caption that appears at the top of a ribbon category or a context category. -[`CMFCRibbonEdit` Class](../../mfc/reference/cmfcribbonedit-class.md)
+[`CMFCRibbonEdit` Class](cmfcribbonedit-class.md)\ Implements an edit control that is positioned on a ribbon. -[`CMFCRibbonFontComboBox` Class](../../mfc/reference/cmfcribbonfontcombobox-class.md)
+[`CMFCRibbonFontComboBox` Class](cmfcribbonfontcombobox-class.md)\ Implements a combo box that contains a list of fonts. You place the combo box on a ribbon panel. -[`CMFCRibbonGallery` Class](../../mfc/reference/cmfcribbongallery-class.md)
+[`CMFCRibbonGallery` Class](cmfcribbongallery-class.md)\ Implements Office 2007-style ribbon galleries. -[`CMFCRibbonGalleryMenuButton` Class](../../mfc/reference/cmfcribbongallerymenubutton-class.md)
+[`CMFCRibbonGalleryMenuButton` Class](cmfcribbongallerymenubutton-class.md)\ Implements a ribbon menu button that contains ribbon galleries. -[`CMFCRibbonLabel` Class](../../mfc/reference/cmfcribbonlabel-class.md)
+[`CMFCRibbonLabel` Class](cmfcribbonlabel-class.md)\ Implements a non-clickable text label for a ribbon. -[`CMFCRibbonLinkCtrl` Class](../../mfc/reference/cmfcribbonlinkctrl-class.md)
+[`CMFCRibbonLinkCtrl` Class](cmfcribbonlinkctrl-class.md)\ Implements a hyperlink that is positioned on a ribbon. The hyperlink opens a Web page when you click it. -[`CMFCRibbonMainPanel` Class](../../mfc/reference/cmfcribbonmainpanel-class.md)
-Implements a ribbon panel that displays when you click the [`CMFCRibbonApplicationButton` Class](../../mfc/reference/cmfcribbonapplicationbutton-class.md). +[`CMFCRibbonMainPanel` Class](cmfcribbonmainpanel-class.md)\ +Implements a ribbon panel that displays when you click the [`CMFCRibbonApplicationButton` Class](cmfcribbonapplicationbutton-class.md). -[`CMFCRibbonMiniToolBar` Class](../../mfc/reference/cmfcribbonminitoolbar-class.md)
+[`CMFCRibbonMiniToolBar` Class](cmfcribbonminitoolbar-class.md)\ Implements a contextual popup toolbar. -[`CMFCRibbonPanel` Class](../../mfc/reference/cmfcribbonpanel-class.md)
+[`CMFCRibbonPanel` Class](cmfcribbonpanel-class.md)\ Implements a panel that contains a set of ribbon elements. When the panel is drawn, it displays as many elements as possible, given the size of the panel. -[`CMFCRibbonProgressBar` Class](../../mfc/reference/cmfcribbonprogressbar-class.md)
+[`CMFCRibbonProgressBar` Class](cmfcribbonprogressbar-class.md)\ Implements a control that visually indicates the progress of a lengthy operation. -[`CMFCRibbonSlider` Class](../../mfc/reference/cmfcribbonslider-class.md)
+[`CMFCRibbonSlider` Class](cmfcribbonslider-class.md)\ Implements a slider control that you can add to a ribbon bar or ribbon status bar. The ribbon slider control resembles the zoom sliders that appear in Office 2007 applications. -[`CMFCRibbonStatusBar` Class](../../mfc/reference/cmfcribbonstatusbar-class.md)
+[`CMFCRibbonStatusBar` Class](cmfcribbonstatusbar-class.md)\ Implements a status bar control that can display ribbon elements. -[`CMFCRibbonStatusBarPane` Class](../../mfc/reference/cmfcribbonstatusbarpane-class.md)
+[`CMFCRibbonStatusBarPane` Class](cmfcribbonstatusbarpane-class.md)\ Implements a ribbon element that you can add to a ribbon status bar. -[`CMFCRibbonUndoButton` Class](../../mfc/reference/cmfcribbonundobutton-class.md)
+[`CMFCRibbonUndoButton` Class](cmfcribbonundobutton-class.md)\ Implements a split button, a small button with a downward pointing triangle on the rightmost part of the main button. Users can click the triangle to display a drop-down list of their most recently performed actions. Users can then select one or more actions from the drop-down list. However, if the user clicks the button, only the last (the most recently added) action on the drop-down list is undone. You should populate the list with actions as the user performs them. -[`CMFCShellListCtrl` Class](../../mfc/reference/cmfcshelllistctrl-class.md)
+[`CMFCShellListCtrl` Class](cmfcshelllistctrl-class.md)\ Provides Windows list control functionality and expands it by including the ability to display a list of shell items. -[`CMFCShellTreeCtrl` Class](../../mfc/reference/cmfcshelltreectrl-class.md)
-Extends [`CTreeCtrl` Class](../../mfc/reference/ctreectrl-class.md) functionality by displaying a hierarchy of Shell items. +[`CMFCShellTreeCtrl` Class](cmfcshelltreectrl-class.md)\ +Extends [`CTreeCtrl` Class](ctreectrl-class.md) functionality by displaying a hierarchy of Shell items. -[`CMFCSpinButtonCtrl` Class](../../mfc/reference/cmfcspinbuttonctrl-class.md)
+[`CMFCSpinButtonCtrl` Class](cmfcspinbuttonctrl-class.md)\ Supports a visual manager that draws a spin button control. -[`CMFCStatusBar` Class](../../mfc/reference/cmfcstatusbar-class.md)
+[`CMFCStatusBar` Class](cmfcstatusbar-class.md)\ Implements a status bar similar to the `CStatusBar` class. However, the `CMFCStatusBar` class has features not offered by the `CStatusBar` class, such as the ability to display images, animations, and progress bars; and the ability to respond to mouse double-clicks. -[`CMFCTabCtrl` Class](../../mfc/reference/cmfctabctrl-class.md)
+[`CMFCTabCtrl` Class](cmfctabctrl-class.md)\ Provides functionality for a tab control. The tab control displays a dockable window with flat or three-dimensional tabs at its top or bottom. The tabs can display text and an image and can change color when active. -[`CMFCTabToolTipInfo Structure](../../mfc/reference/cmfctabtooltipinfo-structure.md)
+[`CMFCTabToolTipInfo` Structure](cmfctabtooltipinfo-structure.md)\ Provides information about the MDI tab that the user is hovering over. -[`CMFCTasksPane` Class](../../mfc/reference/cmfctaskspane-class.md)
+[`CMFCTasksPane` Class](cmfctaskspane-class.md)\ Implements a list of clickable items (tasks). -[`CMFCTasksPaneTask` Class](../../mfc/reference/cmfctaskspanetask-class.md)
-Helper class that represents tasks for the task pane control ([`CMFCTasksPane` Class](../../mfc/reference/cmfctaskspane-class.md)). The task object represents an item in the task group ([`CMFCTasksPaneTaskGroup` Class](../../mfc/reference/cmfctaskspanetaskgroup-class.md)). Each task can have a command that the framework executes when a user clicks on the task and an icon that appears to the left of the task name. +[`CMFCTasksPaneTask` Class](cmfctaskspanetask-class.md)\ +Helper class that represents tasks for the task pane control ([`CMFCTasksPane` Class](cmfctaskspane-class.md)). The task object represents an item in the task group ([`CMFCTasksPaneTaskGroup` Class](cmfctaskspanetaskgroup-class.md)). Each task can have a command that the framework executes when a user clicks on the task and an icon that appears to the left of the task name. -[`CMFCTasksPaneTaskGroup` Class](../../mfc/reference/cmfctaskspanetaskgroup-class.md)
-Helper class used by the [`CMFCTasksPane` Class](../../mfc/reference/cmfctaskspane-class.md) control. Objects of type `CMFCTasksPaneTaskGroup` represent a *task group*. The task group is a list of items that the framework displays in a separate box that has a collapse button. The box can have an optional caption (group name). If a group is collapsed, the list of tasks is not visible. +[`CMFCTasksPaneTaskGroup` Class](cmfctaskspanetaskgroup-class.md)\ +Helper class used by the [`CMFCTasksPane` Class](cmfctaskspane-class.md) control. Objects of type `CMFCTasksPaneTaskGroup` represent a *task group*. The task group is a list of items that the framework displays in a separate box that has a collapse button. The box can have an optional caption (group name). If a group is collapsed, the list of tasks is not visible. -[`CMFCToolBar` Class](../../mfc/reference/cmfctoolbar-class.md)
-Resembles [`CToolBar` Class](../../mfc/reference/ctoolbar-class.md), but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The `CMFCToolBar` class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons. +[`CMFCToolBar` Class](cmfctoolbar-class.md)\ +Resembles [`CToolBar` Class](ctoolbar-class.md), but provides additional support for user interface features. These include flat toolbars, toolbars with hot images, large icons, pager buttons, locked toolbars, rebar controls, text under images, background images, and tabbed toolbars. The `CMFCToolBar` class also contains built-in support for user customization of toolbars and menus, drag-and-drop between toolbars and menus, combo box buttons, edit box buttons, color pickers, and roll-up buttons. -[`CMFCToolBarImages` Class](../../mfc/reference/cmfctoolbarimages-class.md)
+[`CMFCToolBarImages` Class](cmfctoolbarimages-class.md)\ Manages toolbar images loaded from application resources or from files. -[`CMFCToolBarInfo` Class](../../mfc/reference/cmfctoolbarinfo-class.md)
-Contains the resource IDs of toolbar images in various states. `CMFCToolBarInfo` is a helper class that is used as a parameter of the [`CMFCToolBar::LoadToolBarEx`](../../mfc/reference/cmfctoolbar-class.md#loadtoolbarex) method. +[`CMFCToolBarInfo` Class](cmfctoolbarinfo-class.md)\ +Contains the resource IDs of toolbar images in various states. `CMFCToolBarInfo` is a helper class that is used as a parameter of the [`CMFCToolBar::LoadToolBarEx`](cmfctoolbar-class.md#loadtoolbarex) method. -[`CMFCToolBarMenuButton` Class](../../mfc/reference/cmfctoolbarmenubutton-class.md)
+[`CMFCToolBarMenuButton` Class](cmfctoolbarmenubutton-class.md)\ A toolbar button that contains a pop-up menu. -[`CMFCToolBarsCustomizeDialog` Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md)
-A modeless tab dialog box ([`CPropertySheet` Class](../../mfc/reference/cpropertysheet-class.md)) that enables the user to customize the toolbars, menus, keyboard shortcuts, user-defined tools, and visual style in an application. Typically, the user accesses this dialog box by selecting **Customize** from the **Tools** menu. +[`CMFCToolBarsCustomizeDialog` Class](cmfctoolbarscustomizedialog-class.md)\ +A modeless tab dialog box ([`CPropertySheet` Class](cpropertysheet-class.md)) that enables the user to customize the toolbars, menus, keyboard shortcuts, user-defined tools, and visual style in an application. Typically, the user accesses this dialog box by selecting **Customize** from the **Tools** menu. -[`CMFCToolTipCtrl` Class](../../mfc/reference/cmfctooltipctrl-class.md)
-An extended tooltip implementation based on the [`CToolTipCtrl` Class](../../mfc/reference/ctooltipctrl-class.md). A tooltip based on the `CMFCToolTipCtrl` class can display an icon, a label, and a description. You can customize its visual appearance by using a gradient fill, custom text and border colors, bold text, rounded corners, or a balloon style. +[`CMFCToolTipCtrl` Class](cmfctooltipctrl-class.md)\ +An extended tooltip implementation based on the [`CToolTipCtrl` Class](ctooltipctrl-class.md). A tooltip based on the `CMFCToolTipCtrl` class can display an icon, a label, and a description. You can customize its visual appearance by using a gradient fill, custom text and border colors, bold text, rounded corners, or a balloon style. -[`CMFCToolTipInfo` Class](../../mfc/reference/cmfctooltipinfo-class.md)
+[`CMFCToolTipInfo` Class](cmfctooltipinfo-class.md)\ Stores information about the visual appearance of tooltips. -[`CMFCVisualManager` Class](../../mfc/reference/cmfcvisualmanager-class.md)
+[`CMFCVisualManager` Class](cmfcvisualmanager-class.md)\ Provides support for changing the appearance of your application at a global level. The `CMFCVisualManager` class works together with a class that provides instructions to draw the GUI controls of your application using a consistent style. These other classes are referred to as visual managers and they inherit from `CMFCBaseVisualManager`. -[`CMFCVisualManagerOffice2003` Class](../../mfc/reference/cmfcvisualmanageroffice2003-class.md)
+[`CMFCVisualManagerOffice2003` Class](cmfcvisualmanageroffice2003-class.md)\ Gives an application a Microsoft Office 2003 appearance. -[`CMFCVisualManagerOffice2007` Class](../../mfc/reference/cmfcvisualmanageroffice2007-class.md)
+[`CMFCVisualManagerOffice2007` Class](cmfcvisualmanageroffice2007-class.md)\ Gives an application a Microsoft Office 2007 appearance. -[`CMFCVisualManagerVS2005` Class](../../mfc/reference/cmfcvisualmanagervs2005-class.md)
+[`CMFCVisualManagerVS2005` Class](cmfcvisualmanagervs2005-class.md)\ Gives an application a Microsoft Visual Studio 2005 appearance. -[`CMFCVisualManagerWindows` Class](../../mfc/reference/cmfcvisualmanagerwindows-class.md)
+[`CMFCVisualManagerWindows` Class](cmfcvisualmanagerwindows-class.md)\ Mimics the appearance of Microsoft Windows XP or Microsoft Vista when the user selects a Windows XP or Vista theme. -[`CMFCVisualManagerWindows7` Class](../../mfc/reference/cmfcvisualmanagerwindows7-class.md)
+[`CMFCVisualManagerWindows7` Class](cmfcvisualmanagerwindows7-class.md)\ Gives an application the appearance of a Windows 7 application. -[`CMFCWindowsManagerDialog` Class](../../mfc/reference/cmfcwindowsmanagerdialog-class.md)
-Enables a user to manage MDI child windows in a MDI application. +[`CMFCWindowsManagerDialog` Class](cmfcwindowsmanagerdialog-class.md)\ +Enables a user to manage MDI child windows in an MDI application. -[`CMiniFrameWnd` Class](../../mfc/reference/cminiframewnd-class.md)
+[`CMiniFrameWnd` Class](cminiframewnd-class.md)\ Represents a half-height frame window typically seen around floating toolbars. -[`CMonikerFile` Class](../../mfc/reference/cmonikerfile-class.md)
+[`CMonikerFile` Class](cmonikerfile-class.md)\ Represents a stream of data ([`IStream`](/windows/win32/api/objidl/nn-objidl-istream)) named by an [`IMoniker`](/windows/win32/api/objidl/nn-objidl-imoniker). -[`CMonthCalCtrl` Class](../../mfc/reference/cmonthcalctrl-class.md)
+[`CMonthCalCtrl` Class](cmonthcalctrl-class.md)\ Encapsulates the functionality of a month calendar control. -[`CMouseManager` Class](../../mfc/reference/cmousemanager-class.md)
-Lets a user associate different commands with a particular [`CView` Class](../../mfc/reference/cview-class.md) object when the user double-clicks inside that view. +[`CMouseManager` Class](cmousemanager-class.md)\ +Lets a user associate different commands with a particular [`CView` Class](cview-class.md) object when the user double-clicks inside that view. -[`CMultiDocTemplate` Class](../../mfc/reference/cmultidoctemplate-class.md)
+[`CMultiDocTemplate` Class](cmultidoctemplate-class.md)\ Defines a document template that implements the multiple document interface (MDI). -[`CMultiLock` Class](../../mfc/reference/cmultilock-class.md)
+[`CMultiLock` Class](cmultilock-class.md)\ Represents the access-control mechanism used in controlling access to resources in a multithreaded program. -[`CMultiPageDHtmlDialog` Class](../../mfc/reference/cmultipagedhtmldialog-class.md)
+[`CMultiPageDHtmlDialog` Class](cmultipagedhtmldialog-class.md)\ A multipage dialog displays multiple HTML pages sequentially and handles the events from each page. -[`CMultiPaneFrameWnd` Class](../../mfc/reference/cmultipaneframewnd-class.md)
-Extends [`CPaneFrameWnd` Class](../../mfc/reference/cpaneframewnd-class.md). It can support multiple panes. Instead of a single embedded handle to a control bar, `CMultiPaneFrameWnd` contains a [`CPaneContainerManager` Class](../../mfc/reference/cpanecontainermanager-class.md) object that enables the user to dock one `CMultiPaneFrameWnd` to another and dynamically create multiple floating, tabbed windows. +[`CMultiPaneFrameWnd` Class](cmultipaneframewnd-class.md)\ +Extends [`CPaneFrameWnd` Class](cpaneframewnd-class.md). It can support multiple panes. Instead of a single embedded handle to a control bar, `CMultiPaneFrameWnd` contains a [`CPaneContainerManager` Class](cpanecontainermanager-class.md) object that enables the user to dock one `CMultiPaneFrameWnd` to another and dynamically create multiple floating, tabbed windows. -[`CMutex` Class](../../mfc/reference/cmutex-class.md)
+[`CMutex` Class](cmutex-class.md)\ Represents a mutex, which is a synchronization object that allows one thread mutually exclusive access to a resource. -[`CNetAddressCtrl` Class](../../mfc/reference/cnetaddressctrl-class.md)
+[`CNetAddressCtrl` Class](cnetaddressctrl-class.md)\ The `CNetAddressCtrl` class represents the network address control, which you can use to input and validate the format of IPv4, IPv6, and named DNS addresses. -[`CNotSupportedException` Class](../../mfc/reference/cnotsupportedexception-class.md)
+[`CNotSupportedException` Class](cnotsupportedexception-class.md)\ Represents an exception that is the result of a request for an unsupported feature. -[`CObArray` Class](../../mfc/reference/cobarray-class.md)
+[`CObArray` Class](cobarray-class.md)\ Supports arrays of `CObject` pointers. -[`CObject` Class](../../mfc/reference/cobject-class.md)
+[`CObject` Class](cobject-class.md)\ The principal base class for the Microsoft Foundation Class Library. -[`CObList` Class](../../mfc/reference/coblist-class.md)
+[`CObList` Class](coblist-class.md)\ Supports ordered lists of non-unique `CObject` pointers accessible sequentially or by pointer value. -[`COccManager` Class](../../mfc/reference/coccmanager-class.md)
+[`COccManager` Class](coccmanager-class.md)\ Manages various custom control sites; implemented by `COleControlContainer` and `COleControlSite` objects. -[`COleBusyDialog` Class](../../mfc/reference/colebusydialog-class.md)
+[`COleBusyDialog` Class](colebusydialog-class.md)\ Used for the OLE Server Not Responding or Server Busy dialog boxes. -[`COleChangeIconDialog` Class](../../mfc/reference/colechangeicondialog-class.md)
+[`COleChangeIconDialog` Class](colechangeicondialog-class.md)\ Used for the OLE Change Icon dialog box. -[`COleChangeSourceDialog` Class](../../mfc/reference/colechangesourcedialog-class.md)
+[`COleChangeSourceDialog` Class](colechangesourcedialog-class.md)\ Used for the OLE Change Source dialog box. -[`COleClientItem` Class](../../mfc/reference/coleclientitem-class.md)
+[`COleClientItem` Class](coleclientitem-class.md)\ Defines the container interface to OLE items. -[`COleCmdUI` Class](../../mfc/reference/colecmdui-class.md)
+[`COleCmdUI` Class](colecmdui-class.md)\ Implements a method for MFC to update the state of user-interface objects related to the `IOleCommandTarget`-driven features of your application. -[`COleControl` Class](../../mfc/reference/colecontrol-class.md)
+[`COleControl` Class](colecontrol-class.md)\ A powerful base class for developing OLE controls. -[`COleControlContainer` Class](../../mfc/reference/colecontrolcontainer-class.md)
+[`COleControlContainer` Class](colecontrolcontainer-class.md)\ Acts as a control container for ActiveX controls. -[`COleControlModule` Class](../../mfc/reference/colecontrolmodule-class.md)
+[`COleControlModule` Class](colecontrolmodule-class.md)\ The base class from which you derive an OLE control module object. -[`COleControlSite` Class](../../mfc/reference/colecontrolsite-class.md)
+[`COleControlSite` Class](colecontrolsite-class.md)\ Provides support for custom client-side control interfaces. -[`COleConvertDialog` Class](../../mfc/reference/coleconvertdialog-class.md)
+[`COleConvertDialog` Class](coleconvertdialog-class.md)\ For more information, see the [`OLEUICONVERT`](/windows/win32/api/oledlg/ns-oledlg-oleuiconvertw) structure in the Windows SDK. -[`COleCurrency` Class](../../mfc/reference/colecurrency-class.md)
+[`COleCurrency` Class](colecurrency-class.md)\ Encapsulates the `CURRENCY` data type of OLE automation. -[`COleDataObject` Class](../../mfc/reference/coledataobject-class.md)
+[`COleDataObject` Class](coledataobject-class.md)\ Used in data transfers for retrieving data in various formats from the Clipboard, through drag and drop, or from an embedded OLE item. -[`COleDataSource` Class](../../mfc/reference/coledatasource-class.md)
+[`COleDataSource` Class](coledatasource-class.md)\ Acts as a cache into which an application places the data that it will offer during data transfer operations, such as Clipboard or drag-and-drop operations. -[`COleDBRecordView` Class](../../mfc/reference/coledbrecordview-class.md)
+[`COleDBRecordView` Class](coledbrecordview-class.md)\ A view that displays database records in controls. -[`COleDialog` Class](../../mfc/reference/coledialog-class.md)
+[`COleDialog` Class](coledialog-class.md)\ Provides functionality common to dialog boxes for OLE. -[`COleDispatchDriver` Class](../../mfc/reference/coledispatchdriver-class.md)
+[`COleDispatchDriver` Class](coledispatchdriver-class.md)\ Implements the client side of OLE automation. -[`COleDispatchException` Class](../../mfc/reference/coledispatchexception-class.md)
+[`COleDispatchException` Class](coledispatchexception-class.md)\ Handles exceptions specific to the OLE `IDispatch` interface, which is a key part of OLE automation. -[`COleDocObjectItem` Class](../../mfc/reference/coledocobjectitem-class.md)
+[`COleDocObjectItem` Class](coledocobjectitem-class.md)\ Implements Active document containment. -[`COleDocument` Class](../../mfc/reference/coledocument-class.md)
+[`COleDocument` Class](coledocument-class.md)\ The base class for OLE documents that support visual editing. -[`COleDropSource` Class](../../mfc/reference/coledropsource-class.md)
+[`COleDropSource` Class](coledropsource-class.md)\ Enables data to be dragged to a drop target. -[`COleDropTarget` Class](../../mfc/reference/coledroptarget-class.md)
+[`COleDropTarget` Class](coledroptarget-class.md)\ Provides the communication mechanism between a window and the OLE libraries. -[`COleException` Class](../../mfc/reference/coleexception-class.md)
+[`COleException` Class](coleexception-class.md)\ Represents an exception condition related to an OLE operation. -[`COleInsertDialog` Class](../../mfc/reference/coleinsertdialog-class.md)
+[`COleInsertDialog` Class](coleinsertdialog-class.md)\ Used for the OLE Insert Object dialog box. -[`COleIPFrameWnd` Class](../../mfc/reference/coleipframewnd-class.md)
+[`COleIPFrameWnd` Class](coleipframewnd-class.md)\ The base for your application's in-place editing window. -[`COleIPFrameWndEx` Class](../../mfc/reference/coleipframewndex-class.md)
-Implements an OLE container that supports MFC. You must derive the in-place frame window class for your application from the `COleIPFrameWndEx` class, instead of deriving it from the [`COleIPFrameWnd`](../../mfc/reference/coleipframewnd-class.md) class. +[`COleIPFrameWndEx` Class](coleipframewndex-class.md)\ +Implements an OLE container that supports MFC. You must derive the in-place frame window class for your application from the `COleIPFrameWndEx` class, instead of deriving it from the [`COleIPFrameWnd`](coleipframewnd-class.md) class. -[`COleLinkingDoc` Class](../../mfc/reference/colelinkingdoc-class.md)
+[`COleLinkingDoc` Class](colelinkingdoc-class.md)\ The base class for OLE container documents that support linking to the embedded items they contain. -[`COleLinksDialog` Class](../../mfc/reference/colelinksdialog-class.md)
+[`COleLinksDialog` Class](colelinksdialog-class.md)\ Used for the OLE Edit Links dialog box. -[`COleMessageFilter` Class](../../mfc/reference/colemessagefilter-class.md)
+[`COleMessageFilter` Class](colemessagefilter-class.md)\ Manages the concurrency required by the interaction of OLE applications. -[`COleObjectFactory` Class](../../mfc/reference/coleobjectfactory-class.md)
+[`COleObjectFactory` Class](coleobjectfactory-class.md)\ Implements the OLE class factory, which creates OLE objects such as servers, automation objects, and documents. -[`COlePasteSpecialDialog` Class](../../mfc/reference/colepastespecialdialog-class.md)
+[`COlePasteSpecialDialog` Class](colepastespecialdialog-class.md)\ Used for the OLE Paste Special dialog box. -[`COlePropertiesDialog` Class](../../mfc/reference/colepropertiesdialog-class.md)
+[`COlePropertiesDialog` Class](colepropertiesdialog-class.md)\ Encapsulates the Windows common OLE Object Properties dialog box. -[`COlePropertyPage` Class](../../mfc/reference/colepropertypage-class.md)
+[`COlePropertyPage` Class](colepropertypage-class.md)\ Used to display the properties of a custom control in a graphical interface, similar to a dialog box. -[`COleResizeBar` Class](../../mfc/reference/coleresizebar-class.md)
+[`COleResizeBar` Class](coleresizebar-class.md)\ A type of control bar that supports resizing of in-place OLE items. -[`COleSafeArray` Class](../../mfc/reference/colesafearray-class.md)
+[`COleSafeArray` Class](colesafearray-class.md)\ A class for working with arrays of arbitrary type and dimension. -[`COleServerDoc` Class](../../mfc/reference/coleserverdoc-class.md)
+[`COleServerDoc` Class](coleserverdoc-class.md)\ The base class for OLE server documents. -[`COleServerItem` Class](../../mfc/reference/coleserveritem-class.md)
+[`COleServerItem` Class](coleserveritem-class.md)\ Provides the server interface to OLE items. -[`COleStreamFile` Class](../../mfc/reference/colestreamfile-class.md)
+[`COleStreamFile` Class](colestreamfile-class.md)\ Represents a stream of data (`IStream`) in a compound file as part of OLE Structured Storage. -[`COleTemplateServer` Class](../../mfc/reference/coletemplateserver-class.md)
+[`COleTemplateServer` Class](coletemplateserver-class.md)\ Used for OLE visual editing servers, automation servers, and link containers (applications that support links to embeddings). -[`COleUpdateDialog` Class](../../mfc/reference/coleupdatedialog-class.md)
+[`COleUpdateDialog` Class](coleupdatedialog-class.md)\ Used for a special case of the OLE Edit Links dialog box, which should be used when you need to update only existing linked or embedded objects in a document. -[`COleVariant` Class](../../mfc/reference/colevariant-class.md)
+[`COleVariant` Class](colevariant-class.md)\ Encapsulates the [`VARIANT`](/windows/win32/api/oaidl/ns-oaidl-variant) data type. -[`CPagerCtrl` Class](../../mfc/reference/cpagerctrl-class.md)
+[`CPagerCtrl` Class](cpagerctrl-class.md)\ The `CPagerCtrl` class wraps the Windows pager control, which can scroll into view a contained window that does not fit the containing window. -[`CPageSetupDialog` Class](../../mfc/reference/cpagesetupdialog-class.md)
+[`CPageSetupDialog` Class](cpagesetupdialog-class.md)\ Encapsulates the services provided by the Windows common OLE Page Setup dialog box with additional support for setting and modifying print margins. -[`CPaintDC` Class](../../mfc/reference/cpaintdc-class.md)
-A device-context class derived from [`CDC` Class](../../mfc/reference/cdc-class.md). +[`CPaintDC` Class](cpaintdc-class.md)\ +A device-context class derived from [`CDC` Class](cdc-class.md). -[`CPalette` Class](../../mfc/reference/cpalette-class.md)
+[`CPalette` Class](cpalette-class.md)\ Encapsulates a Windows color palette. -[`CPane` Class](../../mfc/reference/cpane-class.md)
-Enhancement of the [`CControlBar` Class](../../mfc/reference/ccontrolbar-class.md). If you are upgrading an existing MFC project, you need to replace all occurrences of `CControlBar` with `CPane`. +[`CPane` Class](cpane-class.md)\ +Enhancement of the [`CControlBar` Class](ccontrolbar-class.md). If you are upgrading an existing MFC project, you need to replace all occurrences of `CControlBar` with `CPane`. -[`CPaneContainer` Class](../../mfc/reference/cpanecontainer-class.md)
-Basic component of the docking model implemented by MFC. An object of this class stores pointers to two docking panes or to two instances of `CPaneContainer`. It also stores a pointer to the divider that separates the panes (or the containers). By nesting containers inside containers, the framework can build a binary tree that represents complex docking layouts. The root of the binary tree is stored in a [`CPaneContainerManager` Class](../../mfc/reference/cpanecontainermanager-class.md) object. +[`CPaneContainer` Class](cpanecontainer-class.md)\ +Basic component of the docking model implemented by MFC. An object of this class stores pointers to two docking panes or to two instances of `CPaneContainer`. It also stores a pointer to the divider that separates the panes (or the containers). By nesting containers inside containers, the framework can build a binary tree that represents complex docking layouts. The root of the binary tree is stored in a [`CPaneContainerManager` Class](cpanecontainermanager-class.md) object. -[`CPaneContainerManager` Class](../../mfc/reference/cpanecontainermanager-class.md)
+[`CPaneContainerManager` Class](cpanecontainermanager-class.md)\ Manages the storage and display of the current docking layout. -[`CPaneDialog` Class](../../mfc/reference/cpanedialog-class.md)
+[`CPaneDialog` Class](cpanedialog-class.md)\ Supports a modeless, dockable dialog box. -[`CPaneDivider` Class](../../mfc/reference/cpanedivider-class.md)
+[`CPaneDivider` Class](cpanedivider-class.md)\ Divides two panes, divides two groups of panes, or separates a group of panes from the client area of the main frame window. -[`CPaneFrameWnd` Class](../../mfc/reference/cpaneframewnd-class.md)
+[`CPaneFrameWnd` Class](cpaneframewnd-class.md)\ Implements a mini-frame window that contains one pane. The pane fills the client area of the window. -[`CParabolicTransitionFromAcceleration` Class](../../mfc/reference/cparabolictransitionfromacceleration-class.md)
+[`CParabolicTransitionFromAcceleration` Class](cparabolictransitionfromacceleration-class.md)\ Encapsulates a parabolic-acceleration transition. -[`CPen` Class](../../mfc/reference/cpen-class.md)
+[`CPen` Class](cpen-class.md)\ Encapsulates a Windows graphics device interface (GDI) pen. -[`CPictureHolder` Class](../../mfc/reference/cpictureholder-class.md)
+[`CPictureHolder` Class](cpictureholder-class.md)\ Implements a Picture property, which lets the user display a picture in your control. -[`CPoint` Class](../../atl-mfc-shared/reference/cpoint-class.md)
+[`CPoint` Class](../../atl-mfc-shared/reference/cpoint-class.md)\ Similar to the Windows `POINT` structure. -[`CPrintDialog` Class](../../mfc/reference/cprintdialog-class.md)
+[`CPrintDialog` Class](cprintdialog-class.md)\ Encapsulates the services provided by the Windows common dialog box for printing. -[`CPrintDialogEx` Class](../../mfc/reference/cprintdialogex-class.md)
+[`CPrintDialogEx` Class](cprintdialogex-class.md)\ Encapsulates the services provided by the Windows Print property sheet. -[`CProgressCtrl` Class](../../mfc/reference/cprogressctrl-class.md)
+[`CProgressCtrl` Class](cprogressctrl-class.md)\ Provides the functionality of the Windows common progress bar control. -[`CPropertyPage` Class](../../mfc/reference/cpropertypage-class.md)
+[`CPropertyPage` Class](cpropertypage-class.md)\ Represents individual pages of a property sheet, otherwise known as a tab dialog box. -[`CPropertySheet` Class](../../mfc/reference/cpropertysheet-class.md)
+[`CPropertySheet` Class](cpropertysheet-class.md)\ Represents property sheets, also known as tab dialog boxes. -[`CPropExchange` Class](../../mfc/reference/cpropexchange-class.md)
+[`CPropExchange` Class](cpropexchange-class.md)\ Supports the implementation of persistence for your OLE controls. -[`CPtrArray` Class](../../mfc/reference/cptrarray-class.md)
+[`CPtrArray` Class](cptrarray-class.md)\ Supports arrays of void pointers. -[`CPtrList` Class](../../mfc/reference/cptrlist-class.md)
+[`CPtrList` Class](cptrlist-class.md)\ Supports lists of void pointers. -[`CReBar` Class](../../mfc/reference/crebar-class.md)
+[`CReBar` Class](crebar-class.md)\ A control bar that provides layout, persistence, and state information for rebar controls. -[`CReBarCtrl` Class](../../mfc/reference/crebarctrl-class.md)
+[`CReBarCtrl` Class](crebarctrl-class.md)\ Encapsulates the functionality of a rebar control, which is a container for a child window. -[`CRecentDockSiteInfo` Class](../../mfc/reference/crecentdocksiteinfo-class.md)
-Helper class that stores recent state information for the [`CPane` Class](../../mfc/reference/cpane-class.md). +[`CRecentDockSiteInfo` Class](crecentdocksiteinfo-class.md)\ +Helper class that stores recent state information for the [`CPane` Class](cpane-class.md). -[`CRecentFileList` Class](../../mfc/reference/crecentfilelist-class.md)
+[`CRecentFileList` Class](crecentfilelist-class.md)\ Supports control of the most recently used (MRU) file list. -[`CRecordset` Class](../../mfc/reference/crecordset-class.md)
+[`CRecordset` Class](crecordset-class.md)\ Represents a set of records selected from a data source. -[`CRecordView` Class](../../mfc/reference/crecordview-class.md)
+[`CRecordView` Class](crecordview-class.md)\ A view that displays database records in controls. -[`CRect` Class](../../atl-mfc-shared/reference/crect-class.md)
+[`CRect` Class](../../atl-mfc-shared/reference/crect-class.md)\ Similar to a Windows [`RECT` structure](/windows/win32/api/windef/ns-windef-rect). -[`CRectTracker` Class](../../mfc/reference/crecttracker-class.md)
+[`CRectTracker` Class](crecttracker-class.md)\ Enables an item to be displayed, moved, and resized in different fashions. -[`CRenderTarget` Class](../../mfc/reference/crendertarget-class.md)
+[`CRenderTarget` Class](crendertarget-class.md)\ A wrapper for `ID2D1RenderTarget`. -[`CResourceException` Class](../../mfc/reference/cresourceexception-class.md)
+[`CResourceException` Class](cresourceexception-class.md)\ Generated when Windows cannot find or allocate a requested resource. -[`CReversalTransition` Class](../../mfc/reference/creversaltransition-class.md)
+[`CReversalTransition` Class](creversaltransition-class.md)\ Encapsulates a reversal transition. -[`CRgn` Class](../../mfc/reference/crgn-class.md)
+[`CRgn` Class](crgn-class.md)\ Encapsulates a Windows graphics device interface (GDI) region. -[`CRichEditCntrItem` Class](../../mfc/reference/cricheditcntritem-class.md)
-With [`CRichEditView` Class](../../mfc/reference/cricheditview-class.md) and [`CRichEditDoc` Class](../../mfc/reference/cricheditdoc-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. +[`CRichEditCntrItem` Class](cricheditcntritem-class.md)\ +With [`CRichEditView` Class](cricheditview-class.md) and [`CRichEditDoc` Class](cricheditdoc-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. -[`CRichEditCtrl` Class](../../mfc/reference/cricheditctrl-class.md)
+[`CRichEditCtrl` Class](cricheditctrl-class.md)\ Provides the functionality of the rich edit control. -[`CRichEditDoc` Class](../../mfc/reference/cricheditdoc-class.md)
-With [`CRichEditView` Class](../../mfc/reference/cricheditview-class.md) and [`CRichEditCntrItem` Class](../../mfc/reference/cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. +[`CRichEditDoc` Class](cricheditdoc-class.md)\ +With [`CRichEditView` Class](cricheditview-class.md) and [`CRichEditCntrItem` Class](cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. -[`CRichEditView` Class](../../mfc/reference/cricheditview-class.md)
-With [`CRichEditDoc` Class](../../mfc/reference/cricheditdoc-class.md) and [`CRichEditCntrItem` Class](../../mfc/reference/cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. +[`CRichEditView` Class](cricheditview-class.md)\ +With [`CRichEditDoc` Class](cricheditdoc-class.md) and [`CRichEditCntrItem` Class](cricheditcntritem-class.md), provides the functionality of the rich edit control within the context of MFC's document view architecture. -[`CScrollBar` Class](../../mfc/reference/cscrollbar-class.md)
+[`CScrollBar` Class](cscrollbar-class.md)\ Provides the functionality of a Windows scroll-bar control. -[`CScrollView` Class](../../mfc/reference/cscrollview-class.md)
-A [`CView` Class](../../mfc/reference/cview-class.md) with scrolling capabilities. +[`CScrollView` Class](cscrollview-class.md)\ +A [`CView` Class](cview-class.md) with scrolling capabilities. -[`CSemaphore` Class](../../mfc/reference/csemaphore-class.md)
+[`CSemaphore` Class](csemaphore-class.md)\ Represents a "semaphore", which is a synchronization object that allows a limited number of threads in one or more processes to access aMaintains a count of the number of threads currently accessing a specified resource. -[`CSettingsStore` Class](../../mfc/reference/csettingsstore-class.md)
+[`CSettingsStore` Class](csettingsstore-class.md)\ Wraps Windows API functions, providing an object-oriented interface that you use to access the registry. -[`CSettingsStoreSP` Class](../../mfc/reference/csettingsstoresp-class.md)
-Helper class that you can use to create instances of the [`CSettingsStore` Class](../../mfc/reference/csettingsstore-class.md). +[`CSettingsStoreSP` Class](csettingsstoresp-class.md)\ +Helper class that you can use to create instances of the [`CSettingsStore` Class](csettingsstore-class.md). -[`CSharedFile` Class](../../mfc/reference/csharedfile-class.md)
-The [`CMemFile` Class](../../mfc/reference/cmemfile-class.md)-derived class that supports shared memory files. +[`CSharedFile` Class](csharedfile-class.md)\ +The [`CMemFile` Class](cmemfile-class.md)-derived class that supports shared memory files. -[`CShellManager` Class](../../mfc/reference/cshellmanager-class.md)
+[`CShellManager` Class](cshellmanager-class.md)\ Implements several methods that enable you to work with pointers to identifier lists (PIDLs). -[`CSimpleException` Class](../../mfc/reference/csimpleexception-class.md)
+[`CSimpleException` Class](csimpleexception-class.md)\ This class is a base class for resource-critical MFC exceptions. -[`CSingleDocTemplate` Class](../../mfc/reference/csingledoctemplate-class.md)
+[`CSingleDocTemplate` Class](csingledoctemplate-class.md)\ Defines a document template that implements the single document interface (SDI). -[`CSingleLock` Class](../../mfc/reference/csinglelock-class.md)
+[`CSingleLock` Class](csinglelock-class.md)\ Represents the access-control mechanism used in controlling access to a resource in a multithreaded program. -[`CSinusoidalTransitionFromRange` Class](../../mfc/reference/csinusoidaltransitionfromrange-class.md)
+[`CSinusoidalTransitionFromRange` Class](csinusoidaltransitionfromrange-class.md)\ Encapsulates a sinusoidal-range transition that has a given range of oscillation. -[`CSinusoidalTransitionFromVelocity` Class](../../mfc/reference/csinusoidaltransitionfromvelocity-class.md)
+[`CSinusoidalTransitionFromVelocity` Class](csinusoidaltransitionfromvelocity-class.md)\ Encapsulates a sinusoidal-velocity transition that has an amplitude that is determined by the initial velocity of the animation variable. -[`CSize` Class](../../atl-mfc-shared/reference/csize-class.md)
+[`CSize` Class](../../atl-mfc-shared/reference/csize-class.md)\ Similar to the Windows [`SIZE`](/windows/win32/api/windef/ns-windef-size) structure, which implements a relative coordinate or position. -[`CSliderCtrl` Class](../../mfc/reference/csliderctrl-class.md)
+[`CSliderCtrl` Class](csliderctrl-class.md)\ Provides the functionality of the Windows common slider control. -[`CSmartDockingInfo` Class](../../mfc/reference/csmartdockinginfo-class.md)
+[`CSmartDockingInfo` Class](csmartdockinginfo-class.md)\ Defines the appearance of smart docking markers. -[`CSmoothStopTransition` Class](../../mfc/reference/csmoothstoptransition-class.md)
+[`CSmoothStopTransition` Class](csmoothstoptransition-class.md)\ Encapsulates a smooth-stop transition. -[`CSocket` Class](../../mfc/reference/csocket-class.md)
+[`CSocket` Class](csocket-class.md)\ Derives from `CAsyncSocket`, and represents a higher level of abstraction of the Windows Sockets API. -[`CSocketFile` Class](../../mfc/reference/csocketfile-class.md)
+[`CSocketFile` Class](csocketfile-class.md)\ A `CFile` object used for sending and receiving data across a network via Windows Sockets. -[`CSpinButtonCtrl` Class](../../mfc/reference/cspinbuttonctrl-class.md)
+[`CSpinButtonCtrl` Class](cspinbuttonctrl-class.md)\ Provides the functionality of the Windows common spin button control. -[`CSplitButton` Class](../../mfc/reference/csplitbutton-class.md)
+[`CSplitButton` Class](csplitbutton-class.md)\ Represents a split button control. The split button control performs a default behavior when a user clicks the main part of the button, and displays a drop-down menu when a user clicks the drop-down arrow of the button. -[`CSplitterWnd` Class](../../mfc/reference/csplitterwnd-class.md)
+[`CSplitterWnd` Class](csplitterwnd-class.md)\ Provides the functionality of a splitter window, which is a window that contains multiple panes. -[`CSplitterWndEx` Class](csplitterwndex-class.md)
+[`CSplitterWndEx` Class](csplitterwndex-class.md)\ Represents a customized splitter window. -[`CStatic` Class](../../mfc/reference/cstatic-class.md)
+[`CStatic` Class](cstatic-class.md)\ Provides the functionality of a Windows static control. -[`CStatusBar` Class](../../mfc/reference/cstatusbar-class.md)
+[`CStatusBar` Class](cstatusbar-class.md)\ A control bar with a row of text output panes, or "indicators". -[`CStatusBarCtrl` Class](../../mfc/reference/cstatusbarctrl-class.md)
+[`CStatusBarCtrl` Class](cstatusbarctrl-class.md)\ Provides the functionality of the Windows common status bar control. -[`CStdioFile` Class](../../mfc/reference/cstdiofile-class.md)
+[`CStdioFile` Class](cstdiofile-class.md)\ Represents a C run-time stream file as opened by the run-time function [`fopen`, `_wfopen`](../../c-runtime-library/reference/fopen-wfopen.md). -[`CStringArray` Class](../../mfc/reference/cstringarray-class.md)
+[`CStringArray` Class](cstringarray-class.md)\ Supports arrays of `CString` objects. -[`CStringList` Class](../../mfc/reference/cstringlist-class.md)
+[`CStringList` Class](cstringlist-class.md)\ Supports lists of `CString` objects. -[`CSyncObject` Class](../../mfc/reference/csyncobject-class.md)
+[`CSyncObject` Class](csyncobject-class.md)\ A pure virtual class that provides functionality common to the synchronization objects in Win32. -[`CTabbedPane` Class](../../mfc/reference/ctabbedpane-class.md)
+[`CTabbedPane` Class](ctabbedpane-class.md)\ Implements the functionality of a pane with detachable tabs. -[`CTabCtrl` Class](../../mfc/reference/ctabctrl-class.md)
+[`CTabCtrl` Class](ctabctrl-class.md)\ Provides the functionality of the Windows common tab control. -[`CTabView` Class](../../mfc/reference/ctabview-class.md)
-Simplifies the use of the tab control class ([`CTabView` Class](../../mfc/reference/ctabview-class.md)) in applications that use MFC's document/view architecture. +[`CTabView` Class](ctabview-class.md)\ +Simplifies the use of the tab control class ([`CTabView` Class](ctabview-class.md)) in applications that use MFC's document/view architecture. -[`CTaskDialog` Class](../../mfc/reference/ctaskdialog-class.md)
+[`CTaskDialog` Class](ctaskdialog-class.md)\ A pop-up dialog box that functions like a message box but can display additional information to the user. The `CTaskDialog` also includes functionality for gathering information from the user. -[`CToolBar` Class](../../mfc/reference/ctoolbar-class.md)
+[`CToolBar` Class](ctoolbar-class.md)\ Control bars that have a row of bitmapped buttons and optional separators. -[`CToolBarCtrl` Class](../../mfc/reference/ctoolbarctrl-class.md)
+[`CToolBarCtrl` Class](ctoolbarctrl-class.md)\ Provides the functionality of the Windows toolbar common control. -[`CToolTipCtrl` Class](../../mfc/reference/ctooltipctrl-class.md)
+[`CToolTipCtrl` Class](ctooltipctrl-class.md)\ Encapsulates the functionality of a "tool tip control", a small pop-up window that displays a single line of text describing the purpose of a tool in an application. -[`CTooltipManager` Class](../../mfc/reference/ctooltipmanager-class.md)
+[`CTooltipManager` Class](ctooltipmanager-class.md)\ Maintains runtime information about tooltips. The `CTooltipManager` class is instantiated one time per application. -[`CTreeCtrl` Class](../../mfc/reference/ctreectrl-class.md)
+[`CTreeCtrl` Class](ctreectrl-class.md)\ Provides the functionality of the Windows common tree view control. -[`CTreeView` Class](../../mfc/reference/ctreeview-class.md)
-Simplifies use of the tree control and of [`CTreeCtrl` Class](../../mfc/reference/ctreectrl-class.md), the class that encapsulates tree-control functionality, with MFC's document-view architecture. +[`CTreeView` Class](ctreeview-class.md)\ +Simplifies use of the tree control and of [`CTreeCtrl` Class](ctreectrl-class.md), the class that encapsulates tree-control functionality, with MFC's document-view architecture. -[`CTypedPtrArray` Class](../../mfc/reference/ctypedptrarray-class.md)
+[`CTypedPtrArray` Class](ctypedptrarray-class.md)\ Provides a type-safe "wrapper" for objects of class `CPtrArray` or `CObArray`. -[`CTypedPtrList` Class](../../mfc/reference/ctypedptrlist-class.md)
+[`CTypedPtrList` Class](ctypedptrlist-class.md)\ Provides a type-safe "wrapper" for objects of class `CPtrList`. -[`CTypedPtrMap` Class](../../mfc/reference/ctypedptrmap-class.md)
+[`CTypedPtrMap` Class](ctypedptrmap-class.md)\ Provides a type-safe "wrapper" for objects of the pointer-map classes `CMapPtrToPtr`, `CMapPtrToWord`, `CMapWordToPtr`, and `CMapStringToPtr`. -[`CUIntArray` Class](../../mfc/reference/cuintarray-class.md)
+[`CUIntArray` Class](cuintarray-class.md)\ Supports arrays of unsigned integers. -[`CUserException` Class](../../mfc/reference/cuserexception-class.md)
+[`CUserException` Class](cuserexception-class.md)\ Thrown to stop an end-user operation. -[`CUserTool` Class](../../mfc/reference/cusertool-class.md)
-Menu item that runs an external application. The **Tools** tab of the **Customize** dialog box ([`CMFCToolBarsCustomizeDialog` Class](../../mfc/reference/cmfctoolbarscustomizedialog-class.md)) enables the user to add user tools, and to specify the name, command, arguments, and initial directory for each user tool. +[`CUserTool` Class](cusertool-class.md)\ +Menu item that runs an external application. The **Tools** tab of the **Customize** dialog box ([`CMFCToolBarsCustomizeDialog` Class](cmfctoolbarscustomizedialog-class.md)) enables the user to add user tools, and to specify the name, command, arguments, and initial directory for each user tool. -[`CUserToolsManager` Class](../../mfc/reference/cusertoolsmanager-class.md)
-Maintains the collection of [`CUserTool` Class](../../mfc/reference/cusertool-class.md) objects in an application. A user tool is a menu item that runs an external application. The `CUserToolsManager` object enables the user or developer to add new user tools to the application. It supports the execution of the commands associated with user tools, and it also saves information about user tools in the Windows registry. +[`CUserToolsManager` Class](cusertoolsmanager-class.md)\ +Maintains the collection of [`CUserTool` Class](cusertool-class.md) objects in an application. A user tool is a menu item that runs an external application. The `CUserToolsManager` object enables the user or developer to add new user tools to the application. It supports the execution of the commands associated with user tools, and it also saves information about user tools in the Windows registry. -[`CView` Class](../../mfc/reference/cview-class.md)
+[`CView` Class](cview-class.md)\ Provides the basic functionality for user-defined view classes. -[`CVSListBox` Class](../../mfc/reference/cvslistbox-class.md)
+[`CVSListBox` Class](cvslistbox-class.md)\ Supports an editable list control. -[`CWaitCursor` Class](../../mfc/reference/cwaitcursor-class.md)
+[`CWaitCursor` Class](cwaitcursor-class.md)\ Provides a one-line way to show a wait cursor, which is usually displayed as an hourglass, while you're doing a lengthy operation. -[`CWinApp` Class](../../mfc/reference/cwinapp-class.md)
+[`CWinApp` Class](cwinapp-class.md)\ The base class from which you derive a Windows application object. -[`CWinAppEx` Class](../../mfc/reference/cwinappex-class.md)
+[`CWinAppEx` Class](cwinappex-class.md)\ Handles the application state, saves the state to the registry, loads the state from the registry, initializes application managers, and provides links to those same application managers. -[`CWindowDC` Class](../../mfc/reference/cwindowdc-class.md)
+[`CWindowDC` Class](cwindowdc-class.md)\ Derived from `CDC`. -[`CWinFormsControl` Class](../../mfc/reference/cwinformscontrol-class.md)
+[`CWinFormsControl` Class](cwinformscontrol-class.md)\ Provides the basic functionality for hosting of a Windows Forms control. -[`CWinFormsDialog` Class](../../mfc/reference/cwinformsdialog-class.md)
+[`CWinFormsDialog` Class](cwinformsdialog-class.md)\ A wrapper for an MFC dialog class that hosts a Windows Forms user control. -[`CWinFormsView` Class](../../mfc/reference/cwinformsview-class.md)
+[`CWinFormsView` Class](cwinformsview-class.md)\ Provides generic functionality for hosting of a Windows Forms control as an MFC view. -[`CWinThread` Class](../../mfc/reference/cwinthread-class.md)
+[`CWinThread` Class](cwinthread-class.md)\ Represents a thread of execution within an application. -[`CWnd` Class](../../mfc/reference/cwnd-class.md)
+[`CWnd` Class](cwnd-class.md)\ Provides the base functionality of all window classes in the Microsoft Foundation Class Library. -[`CWordArray` Class](../../mfc/reference/cwordarray-class.md)
+[`CWordArray` Class](cwordarray-class.md)\ Supports arrays of 16-bit words. ## Related Sections -[MFC Desktop Applications](../../mfc/mfc-desktop-applications.md)
+[MFC Desktop Applications](../mfc-desktop-applications.md)\ Contains links to topics about the classes, global functions, global variables, and macros that make up the MFC Library. diff --git a/docs/mfc/reference/mfc-dll-wizard.md b/docs/mfc/reference/mfc-dll-wizard.md index 9f7433d1c1c..6d06403db33 100644 --- a/docs/mfc/reference/mfc-dll-wizard.md +++ b/docs/mfc/reference/mfc-dll-wizard.md @@ -4,10 +4,12 @@ title: "MFC DLL Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.dll.overview"] helpviewer_keywords: ["MFC DLLs [MFC], creating", "MFC DLL Wizard", "DLLs [MFC], MFC", "DLL wizard [MFC]", "MFC DLLs [MFC]", "DLLs [MFC], creating"] -ms.assetid: 4e936031-7e39-4f40-a295-42a09c5ff264 --- # MFC DLL Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you use the MFC DLL wizard to create an MFC DLL project, you get a working starter application with built-in functionality that, when compiled, will implement the basic features of a [DLL](../../build/dlls-in-visual-cpp.md). The MFC starter program includes C++ source (.cpp) files, resource (.rc) files, and a project (.vcxproj) file. The code generated in these starter files is based on MFC. For more detailed information, see the file details in Readme.txt that is generated for your project in Visual Studio, and [Classes and Functions Generated by the MFC DLL Wizard](../../mfc/reference/classes-and-functions-generated-by-the-mfc-dll-wizard.md) ## Overview @@ -16,7 +18,7 @@ This wizard page describes the current [application settings for the MFC DLL pro To change these defaults, click **Application Settings** in the left column of the wizard and make changes in that page of the MFC DLL Wizard. -After you create an MFC DLL project, you can add objects or controls to your project using Visual C++ [code wizards](../../ide/adding-functionality-with-code-wizards-cpp.md). +After you create an MFC DLL project, you can add objects or controls to your project using Visual Studio [code wizards](../../ide/adding-functionality-with-code-wizards-cpp.md). You can perform the following tasks and types of enhancements to a basic MFC DLL project: diff --git a/docs/mfc/reference/mfc-macros-and-globals.md b/docs/mfc/reference/mfc-macros-and-globals.md index 7055e4a7c74..10468fe5bbe 100644 --- a/docs/mfc/reference/mfc-macros-and-globals.md +++ b/docs/mfc/reference/mfc-macros-and-globals.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC Macros and Globals" title: "MFC Macros and Globals" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, global functions and variables", "MFC, macros", "global functions, MFC", "macros, MFC", "global functions [MFC]", "global variables, MFC", "Afx naming convention", "macros"] -ms.assetid: add4e33f-0e62-4d27-be14-896cb8675d22 --- # MFC Macros and Globals +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class Library can be divided into two major sections: (1) the MFC classes and (2) macros and globals. If a function or variable is not a member of a class, it is a global function or variable. The MFC library and the Active Template Library (ATL) share string conversion macros. For more information, see [String Conversion Macros](../../atl/reference/string-conversion-macros.md) in the ATL documentation. diff --git a/docs/mfc/reference/mfc-odbc-consumer-wizard.md b/docs/mfc/reference/mfc-odbc-consumer-wizard.md index 4b3754189d2..f63ea871767 100644 --- a/docs/mfc/reference/mfc-odbc-consumer-wizard.md +++ b/docs/mfc/reference/mfc-odbc-consumer-wizard.md @@ -3,10 +3,12 @@ description: "Learn more about: MFC ODBC Consumer Wizard" title: "MFC ODBC Consumer Wizard" ms.date: "08/29/2019" helpviewer_keywords: ["wizards [MFC]"] -ms.assetid: f64a890b-a252-4887-88a1-782a7cd4ff3d --- # MFC ODBC Consumer Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + ::: moniker range=">=msvc-160" This wizard is not available in Visual Studio 2019 and later. diff --git a/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md b/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md index 6a99fce2ecd..1ca91580e76 100644 --- a/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md +++ b/docs/mfc/reference/mfc-wizards-and-dialog-boxes.md @@ -2,10 +2,12 @@ description: "Learn more about: MFC Wizards and Dialog Boxes" title: "MFC Wizards and Dialog Boxes" ms.date: "11/04/2016" -ms.assetid: 2fae0a2c-d147-4468-a547-f7b85df767a1 --- # MFC Wizards and Dialog Boxes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class (MFC) wizards generate boilerplate code for various kinds of components and objects. You can run the wizards by opening the shortcut menu for a project in **Solution Explorer** and choosing **Add**, **Class**. ## Related Articles diff --git a/docs/mfc/reference/ole-initialization.md b/docs/mfc/reference/ole-initialization.md index 9e2eb402775..739a71c9abf 100644 --- a/docs/mfc/reference/ole-initialization.md +++ b/docs/mfc/reference/ole-initialization.md @@ -4,10 +4,12 @@ title: "OLE Initialization" ms.date: "11/04/2016" f1_keywords: ["afxdisp/AfxOleInit", "afxdisp/AfxEnableControlContainer"] helpviewer_keywords: ["OLE initialization"] -ms.assetid: aa8a54a7-24c3-4344-b2c6-dbcf6084fa31 --- # OLE Initialization +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Before an application can use OLE system services, it must initialize the OLE system DLLs and verify that the DLLs are the correct version. The `AfxOleInit` function initializes the OLE system DLLs. ### OLE Initialization diff --git a/docs/mfc/reference/persistence-of-ole-controls.md b/docs/mfc/reference/persistence-of-ole-controls.md index f01c148c590..85a6f6459e5 100644 --- a/docs/mfc/reference/persistence-of-ole-controls.md +++ b/docs/mfc/reference/persistence-of-ole-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Persistence of OLE Controls" title: "Persistence of OLE Controls" ms.date: "11/04/2016" helpviewer_keywords: ["OLE controls [MFC], persistence", "persistence, OLE controls"] -ms.assetid: 64f8dc80-f110-41af-b3ea-14948f6bfdf7 --- # Persistence of OLE Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + One capability of OLE controls is property persistence (or serialization), which allows the OLE control to read or write property values to and from a file or stream. A container application can use serialization to store a control's property values even after the application has destroyed the control. The property values of the OLE control can then be read from the file or stream when a new instance of the control is created at a later time. ### Persistence of OLE Controls diff --git a/docs/mfc/reference/property-pages-mfc.md b/docs/mfc/reference/property-pages-mfc.md index 68a4e94fa5d..f46e45774dd 100644 --- a/docs/mfc/reference/property-pages-mfc.md +++ b/docs/mfc/reference/property-pages-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Property Pages (MFC)" title: "Property Pages (MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["property page data transfer functions in MFC", "property pages [MFC], global MFC functions"] -ms.assetid: 734f88bc-c776-4136-9b0e-f45c761a45c1 --- # Property Pages (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Property pages display the current values of specific OLE control properties in a customizable, graphical interface for viewing and editing by supporting a data-mapping mechanism based on dialog data exchange (DDX). This data-mapping mechanism maps property page controls to the individual properties of the OLE control. The value of the control property reflects the status or content of the property page control. The mapping between property page controls and properties is specified by **DDP_** function calls in the property page's `DoDataExchange` member function. The following is a list of **DDP_** functions that exchange data entered using the property page of your control: diff --git a/docs/mfc/reference/record-field-exchange-functions.md b/docs/mfc/reference/record-field-exchange-functions.md index 477e1ec39a3..30388eac0ad 100644 --- a/docs/mfc/reference/record-field-exchange-functions.md +++ b/docs/mfc/reference/record-field-exchange-functions.md @@ -4,10 +4,12 @@ title: "Record Field Exchange Functions" ms.date: "09/17/2019" f1_keywords: ["AFXDB/RFX_Binary", "AFXDB/RFX_Bool", "AFXDB/RFX_Byte", "AFXDB/RFX_Date", "AFXDB/RFX_Double", "AFXDB/RFX_Int", "AFXDB/RFX_Long", "AFXDB/RFX_LongBinary", "AFXDB/RFX_Single", "AFXDB/RFX_Text", "AFXDB/RFX_Binary_Bulk", "AFXDB/RFX_Bool_Bulk", "AFXDB/RFX_Byte_Bulk", "AFXDB/RFX_Date_Bulk", "AFXDB/RFX_Double_Bulk", "AFXDB/RFX_Int_Bulk", "AFXDB/RFX_Long_Bulk", "AFXDB/RFX_Single_Bulk", "AFXDB/RFX_Text_Bulk", "AFXDB/DFX_Binary", "AFXDB/DFX_Bool", "AFXDB/DFX_Byte", "AFXDB/DFX_Currency", "AFXDB/DFX_DateTime", "AFXDB/DFX_Double", "AFXDB/DFX_Long", "AFXDB/DFX_LongBinary", "AFXDB/DFX_Short", "AFXDB/DFX_Single", "AFXDB/DFX_Text"] helpviewer_keywords: ["DAO (Data Access Objects), record field exchange (DFX)", "ODBC, bulk RFX data exchange functions [MFC]", "RFX (record field exchange), ODBC classes", "DFX (DAO record field exchange), data exchange functions [MFC]", "DFX functions [MFC]", "bulk RFX functions [MFC]", "DFX (DAO record field exchange)", "RFX (record field exchange), DAO classes", "ODBC, RFX", "RFX (record field exchange), data exchange functions [MFC]", "RFX (record field exchange)"] -ms.assetid: 6e4c5c1c-acb7-4c18-bf51-bf7959a696cd --- # Record Field Exchange Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists the Record Field Exchange (RFX, Bulk RFX, and DFX) functions used to automate the transfer of data between a recordset object and its data source and to perform other operations on the data. If you are using the ODBC-based classes and you have implemented bulk row fetching, you must manually override the `DoBulkFieldExchange` member function of `CRecordset` by calling the Bulk RFX functions for each data member corresponding to a data source column. diff --git a/docs/mfc/reference/registering-ole-controls.md b/docs/mfc/reference/registering-ole-controls.md index 8de8baa13dc..474f755e5d7 100644 --- a/docs/mfc/reference/registering-ole-controls.md +++ b/docs/mfc/reference/registering-ole-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Registering OLE Controls" title: "Registering OLE Controls" ms.date: "11/04/2016" helpviewer_keywords: ["registering OLE controls", "OLE controls [MFC], registering"] -ms.assetid: 73c45b7f-7dbc-43f5-bd17-dd77c6acec72 --- # Registering OLE Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + OLE controls, like other OLE server objects, can be accessed by other OLE-aware applications. This is achieved by registering the control's type library and class. The following functions allow you to add and remove the control's class, property pages, and type library in the Windows registration database: @@ -224,7 +226,7 @@ This function updates the registry with the type library name and its location o ### Example [!code-cpp[NVC_MFCAutomation#7](../../mfc/codesnippet/cpp/registering-ole-controls_3.cpp)] - +  [!code-cpp[NVC_MFCAutomation#8](../../mfc/codesnippet/cpp/registering-ole-controls_4.cpp)] ### Requirements diff --git a/docs/mfc/reference/run-time-object-model-services.md b/docs/mfc/reference/run-time-object-model-services.md index c0a9d10f0bf..b2554a26265 100644 --- a/docs/mfc/reference/run-time-object-model-services.md +++ b/docs/mfc/reference/run-time-object-model-services.md @@ -6,6 +6,9 @@ helpviewer_keywords: ["run-time object model services macros"] --- # Run-Time Object Model Services +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The classes [`CObject`](../../mfc/reference/cobject-class.md) and [`CRuntimeClass`](../../mfc/reference/cruntimeclass-structure.md) encapsulate several object services, including access to run-time class information, serialization, and dynamic object creation. All classes derived from `CObject` inherit this functionality. Access to run-time class information enables you to determine information about an object's class at run time. The ability to determine the class of an object at run time is useful when you need extra type-checking of function arguments and when you must write special-purpose code based on the class of an object. Run-time class information isn't supported directly by the C++ language. @@ -268,7 +271,7 @@ For more information, see [`CObject` Class Topics](../../mfc/using-cobject.md). ### Example [!code-cpp[NVC_MFCCObjectSample#2](../../mfc/codesnippet/cpp/run-time-object-model-services_3.h)] - +  [!code-cpp[NVC_MFCCObjectSample#3](../../mfc/codesnippet/cpp/run-time-object-model-services_4.cpp)] ### Requirements @@ -304,7 +307,7 @@ Note that this macro definition will invoke the default constructor for your cla ### Example [!code-cpp[NVC_MFCCObjectSample#22](../../mfc/codesnippet/cpp/run-time-object-model-services_5.h)] - +  [!code-cpp[NVC_MFCCObjectSample#23](../../mfc/codesnippet/cpp/run-time-object-model-services_6.cpp)] ### Requirements diff --git a/docs/mfc/reference/standard-command-and-window-ids.md b/docs/mfc/reference/standard-command-and-window-ids.md index bd4e60b03d2..d856dbfd439 100644 --- a/docs/mfc/reference/standard-command-and-window-ids.md +++ b/docs/mfc/reference/standard-command-and-window-ids.md @@ -3,10 +3,12 @@ description: "Learn more about: Standard Command and Window IDs" title: "Standard Command and Window IDs" ms.date: "11/04/2016" helpviewer_keywords: ["standard command and Window IDs"] -ms.assetid: 0424805c-fff8-4531-8f0c-15cfb13aa612 --- # Standard Command and Window IDs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class Library defines a number of standard command and window IDs in Afxres.h. These IDs are most commonly used within the resource editors and the [Class Wizard](mfc-class-wizard.md) to map messages to your handler functions. All standard commands have an **ID_** prefix. For example, when you use the menu editor, you normally bind the File Open menu item to the standard ID_FILE_OPEN command ID. For most standard commands, application code does not need to refer to the command ID, because the framework itself handles the commands through message maps in its primary framework classes (`CWinThread`, `CWinApp`, `CView`, `CDocument`, and so on). diff --git a/docs/mfc/reference/standard-dialog-data-exchange-routines.md b/docs/mfc/reference/standard-dialog-data-exchange-routines.md index fd89641996b..75d3a07d319 100644 --- a/docs/mfc/reference/standard-dialog-data-exchange-routines.md +++ b/docs/mfc/reference/standard-dialog-data-exchange-routines.md @@ -6,6 +6,9 @@ helpviewer_keywords: ["standard dialog, data exchange routines"] --- # Standard Dialog Data Exchange Routines +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists the standard dialog data exchange (DDX) routines used for common MFC dialog controls. > [!NOTE] @@ -34,7 +37,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/standard-dialog-data-validation-routines.md b/docs/mfc/reference/standard-dialog-data-validation-routines.md index 43e9cb3e105..80d776f309b 100644 --- a/docs/mfc/reference/standard-dialog-data-validation-routines.md +++ b/docs/mfc/reference/standard-dialog-data-validation-routines.md @@ -3,10 +3,12 @@ description: "Learn more about: Standard Dialog Data Validation Routines" title: "Standard Dialog Data Validation Routines" ms.date: "11/04/2016" helpviewer_keywords: ["standard dialog, data validation routines"] -ms.assetid: 44dbc222-a897-4949-925e-7660e8964ccd --- # Standard Dialog Data Validation Routines +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists the standard dialog data validation (DDV) routines used for common MFC dialog controls. > [!NOTE] diff --git a/docs/mfc/reference/structures-styles-callbacks-and-message-maps.md b/docs/mfc/reference/structures-styles-callbacks-and-message-maps.md index f7b7d59f652..759dcd5d559 100644 --- a/docs/mfc/reference/structures-styles-callbacks-and-message-maps.md +++ b/docs/mfc/reference/structures-styles-callbacks-and-message-maps.md @@ -3,10 +3,12 @@ description: "Learn more about: Structures, Styles, Callbacks, and Message Maps" title: "Structures, Styles, Callbacks, and Message Maps" ms.date: "11/04/2016" helpviewer_keywords: ["callback functions, MFC", "styles, MFC", "message classes [MFC], MFC", "structures, MFC"] -ms.assetid: 27566602-7d84-4089-880c-8e90fb04fa56 --- # Structures, Styles, Callbacks, and Message Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This section documents the structures, styles, and callback functions used by the Microsoft Foundation Class Library and the MFC message maps. ## In This Section diff --git a/docs/mfc/reference/structures-used-by-mfc.md b/docs/mfc/reference/structures-used-by-mfc.md index 4e4f0a60c98..f01d1b7ccbb 100644 --- a/docs/mfc/reference/structures-used-by-mfc.md +++ b/docs/mfc/reference/structures-used-by-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Structures Used by MFC" title: "Structures Used by MFC" ms.date: "12/03/2018" helpviewer_keywords: ["structures", "structures, MFC"] -ms.assetid: 2168fcc6-e800-4814-aabf-0bca86ff790d --- # Structures Used by MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table lists structures that are called from various member functions. For further information on individual structure usage, refer to the classes and member functions noted in the See Also list for each structure. :::row::: diff --git a/docs/mfc/reference/styles-used-by-mfc.md b/docs/mfc/reference/styles-used-by-mfc.md index 3afec125dba..57a0bfaa6b2 100644 --- a/docs/mfc/reference/styles-used-by-mfc.md +++ b/docs/mfc/reference/styles-used-by-mfc.md @@ -1,17 +1,19 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use the following style flags to specify window or control appearance and behavior when you create the corresponding MFC object. In most cases, these styles are set in the *`dwStyle`* parameter of the class `Create` function. ## 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 +26,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 +102,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 +123,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 +156,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 +198,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 +215,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 +249,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 +283,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 +312,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/toolbar-control-styles.md b/docs/mfc/reference/toolbar-control-styles.md index 77597a53dab..f5b7a9d6002 100644 --- a/docs/mfc/reference/toolbar-control-styles.md +++ b/docs/mfc/reference/toolbar-control-styles.md @@ -3,10 +3,12 @@ description: "Learn more about: ToolBar Control Styles" title: "ToolBar Control Styles" ms.date: "11/04/2016" helpviewer_keywords: ["ToolBar control styles [MFC]"] -ms.assetid: 0f717eb9-fa32-4263-b852-809238863feb --- # ToolBar Control Styles +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [CMFCToolBarButton Class](../../mfc/reference/cmfctoolbarbutton-class.md) has a set of style flags that determine the appearance and behavior of the button. You can set a combination of these flags by calling [CMFCToolBarButton::SetStyle](../../mfc/reference/cmfctoolbarbutton-class.md#setstyle). This topic lists the style flag values and their meanings. ## Property Values diff --git a/docs/mfc/reference/type-casting-of-mfc-class-objects.md b/docs/mfc/reference/type-casting-of-mfc-class-objects.md index ee081937069..233e7ad3cb8 100644 --- a/docs/mfc/reference/type-casting-of-mfc-class-objects.md +++ b/docs/mfc/reference/type-casting-of-mfc-class-objects.md @@ -3,10 +3,12 @@ description: "Learn more about: Type Casting of MFC Class Objects" title: "Type Casting of MFC Class Objects" ms.date: "11/04/2016" helpviewer_keywords: ["macros [MFC], type casting", "pointers [MFC], type casting", "type casts [MFC]", "casting types [MFC]", "macros [MFC], casting pointers"] -ms.assetid: e138465e-c35f-4e84-b788-bd200ccf2f0e --- # Type Casting of MFC Class Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Type casting macros provide a way to cast a given pointer to a pointer that points to an object of specific class, with or without checking that the cast is legal. The following table lists the MFC type casting macros. diff --git a/docs/mfc/reference/type-library-access.md b/docs/mfc/reference/type-library-access.md index 6ef3220a64b..b0b56f09b88 100644 --- a/docs/mfc/reference/type-library-access.md +++ b/docs/mfc/reference/type-library-access.md @@ -3,10 +3,12 @@ description: "Learn more about: Type Library Access" title: "Type Library Access" ms.date: "11/04/2016" helpviewer_keywords: ["type libraries [MFC], accessing"] -ms.assetid: a03fa7f0-86c2-4119-bf81-202916fb74b3 --- # Type Library Access +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Type libraries expose the interfaces of an OLE control to other OLE-aware applications. Each OLE control must have a type library if one or more interfaces are to be exposed. The following macros allow an OLE control to provide access to its own type library: diff --git a/docs/mfc/reference/uicheckstate-enumeration.md b/docs/mfc/reference/uicheckstate-enumeration.md index 71cd897d5a1..8224123d07a 100644 --- a/docs/mfc/reference/uicheckstate-enumeration.md +++ b/docs/mfc/reference/uicheckstate-enumeration.md @@ -4,10 +4,12 @@ title: "UICheckState Enumeration" ms.date: "04/03/2017" f1_keywords: ["afxwinforms/uicheckstate"] helpviewer_keywords: ["uicheckstate enumeration [MFC]"] -ms.assetid: 2ac0098c-20e7-410c-9685-5ead5cb02b63 --- # UICheckState Enumeration +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Describes the check state of a user interface item for the command. ### Syntax diff --git a/docs/mfc/reference/user-button-handlers.md b/docs/mfc/reference/user-button-handlers.md index 60722f09cc4..8d81f6329ef 100644 --- a/docs/mfc/reference/user-button-handlers.md +++ b/docs/mfc/reference/user-button-handlers.md @@ -4,10 +4,12 @@ title: "User Button Handlers" ms.date: "11/04/2016" f1_keywords: ["ON_BN_HILITE", "ON_BN_DOUBLECLICKED", "ON_BN_CLICKED", "ON_BN_PAINT", "ON_BN_DISABLE", "ON_BN_UNHILITE"] helpviewer_keywords: ["ON_BN_PAINT", "user buttons [MFC]", "ON_BN_DOUBLECLICKED [MFC]", "ON_BN_DISABLE [MFC]", "ON_BN_UNHILITE [MFC]", "ON_BN_HILITE [MFC]", "ON_BN_CLICKED [MFC]"] -ms.assetid: 410ea968-478f-4806-b7b8-5d7c8dc2bf42 --- # User Button Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries correspond to the function prototypes. |Map entry|Function prototype| diff --git a/docs/mfc/reference/user-defined-handlers.md b/docs/mfc/reference/user-defined-handlers.md index e975f7b8127..f7774849951 100644 --- a/docs/mfc/reference/user-defined-handlers.md +++ b/docs/mfc/reference/user-defined-handlers.md @@ -3,10 +3,12 @@ description: "Learn more about: User-Defined Handlers" title: "User-Defined Handlers" ms.date: "11/04/2016" helpviewer_keywords: ["ON_REGISTERED_MESSAGE macro [MFC]", "ON_MESSAGE macro [MFC]", "user-defined handlers [MFC]"] -ms.assetid: 99478294-bef0-4ba7-a369-25a6abdcdb62 --- # User-Defined Handlers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries correspond to the function prototypes. |Map entry|Function prototype| diff --git a/docs/mfc/reference/user-interface-features-mfc-application-wizard.md b/docs/mfc/reference/user-interface-features-mfc-application-wizard.md index 68ccfa97e30..3dee4ab90ac 100644 --- a/docs/mfc/reference/user-interface-features-mfc-application-wizard.md +++ b/docs/mfc/reference/user-interface-features-mfc-application-wizard.md @@ -4,10 +4,12 @@ title: "User Interface Features, MFC Application Wizard" ms.date: "11/04/2016" f1_keywords: ["vc.appwiz.mfc.exe.ui"] helpviewer_keywords: ["MFC Application Wizard, user interface features"] -ms.assetid: 59e7b829-a665-42eb-be23-3f2a36eb2dad --- # User Interface Features, MFC Application Wizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic explains the options that you can use to specify the look of your application. The user interface features available for your project depend on the type of application you specified in the [Application Type, MFC Application Wizard](../../mfc/reference/application-type-mfc-application-wizard.md) page of the MFC Application Wizard. For example, if you create a single document interface application, you cannot add child frame styles. - **Main frame styles** diff --git a/docs/mfc/reference/variant-parameter-type-constants.md b/docs/mfc/reference/variant-parameter-type-constants.md index e71f99e6d80..2a6d1aadeee 100644 --- a/docs/mfc/reference/variant-parameter-type-constants.md +++ b/docs/mfc/reference/variant-parameter-type-constants.md @@ -4,17 +4,19 @@ title: "Variant Parameter Type Constants" ms.date: "11/04/2016" f1_keywords: ["VTS_YPOS_HIMETRIC", "VTS_PICTURE", "VTS_FONT", "VTS_XPOS_HIMETRIC", "VTS_XPOS_PIXELS", "VTS_XSIZE_HIMETRIC", "VTS_YPOS_PIXELS", "VTS_TRISTATE", "VTS_HANDLE", "VTS_YSIZE_HIMETRIC", "VTS_COLOR", "VTS_OPTEXCLUSIVE", "VTS_YSIZE_PIXELS", "VTS_XSIZE_PIXELS"] helpviewer_keywords: ["VTS_XPOS_HIMETRIC constant [MFC]", "VTS_FONT constant [MFC]", "VTS_XPOS_PIXELS constant [MFC]", "VTS_COLOR constant [MFC]", "Variants [MFC]", "VTS_YPOS_PIXELS constant [MFC]", "VTS_YSIZE_HIMETRIC constant [MFC]", "VTS_YPOS_HIMETRIC constant [MFC]", "Variants, parameter type constants", "Variant data constants [MFC]", "VTS_PICTURE constant [MFC]", "VTS_TRISTATE constant [MFC]", "VTS_XSIZE_HIMETRIC constant [MFC]", "VTS_HANDLE constant [MFC]", "VTS_XSIZE_PIXELS constant [MFC]", "VTS_OPTEXCLUSIVE constant [MFC]", "VTS_YSIZE_PIXELS constant [MFC]"] -ms.assetid: de99c7a9-7aae-4dc4-b723-40c6380543ab --- # Variant Parameter Type Constants +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic lists new constants that indicate variant parameter types designed for use with the OLE control classes of the Microsoft Foundation Class Library. The following is a list of class constants: ## Variant Data Constants -- VTS_COLOR A 32-bit integer used to represent a RGB color value. +- VTS_COLOR A 32-bit integer used to represent an RGB color value. - VTS_FONT A pointer to the `IFontDisp` interface of an OLE font object. diff --git a/docs/mfc/reference/wm-message-handlers-a-c.md b/docs/mfc/reference/wm-message-handlers-a-c.md index e6e35de0fcc..8301bf57d3d 100644 --- a/docs/mfc/reference/wm-message-handlers-a-c.md +++ b/docs/mfc/reference/wm-message-handlers-a-c.md @@ -7,6 +7,9 @@ helpviewer_keywords: ["ON_WM_COMPACTING [MFC]", "ON_WM_COMPAREITEM [MFC]", "ON_W --- # `WM_` Message Handlers: A - C +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries on the left correspond to the function prototypes on the right: |Map entry|Function prototype| diff --git a/docs/mfc/reference/wm-message-handlers-d-e.md b/docs/mfc/reference/wm-message-handlers-d-e.md index 3e6cded86cc..0f1932a34bd 100644 --- a/docs/mfc/reference/wm-message-handlers-d-e.md +++ b/docs/mfc/reference/wm-message-handlers-d-e.md @@ -4,10 +4,12 @@ title: "WM_ Message Handlers: D - E" ms.date: "11/04/2016" f1_keywords: ["ON_WM_ERASEBKGND", "ON_WM_DEVICECHANGE", "ON_WM_ENTERIDLE", "ON_WM_DESTROYCLIPBOARD", "ON_WM_DESTROY", "ON_WM_DEADCHAR", "ON_WM_DELETEITEM", "ON_WM_DROPFILES", "ON_WM_DEVMODECHANGE", "ON_WM_ENDSESSION", "ON_WM_ENABLE", "ON_WM_DRAWITEM", "ON_WM_DRAWCLIPBOARD"] helpviewer_keywords: ["ON_WM_ENTERIDLE [MFC]", "ON_WM_DESTROYCLIPBOARD [MFC]", "ON_WM_DEADCHAR [MFC]", "ON_WM_DEVMODECHANGE [MFC]", "ON_WM_ERASEBKGND [MFC]", "ON_WM_DESTROY [MFC]", "ON_WM_DRAWCLIPBOARD [MFC]", "ON_WM_ENDSESSION [MFC]", "ON_WM_DRAWITEM [MFC]", "ON_WM_ENABLE [MFC]", "ON_WM_DROPFILES [MFC]", "ON_WM_DELETEITEM [MFC]", "ON_WM_DEVICECHANGE [MFC]", "WM_ messages [MFC]"] -ms.assetid: 56fb89c8-68a8-4adf-883e-a9f63bf677e9 --- # WM_ Message Handlers: D - E +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries on the left correspond to the function prototypes on the right: |Map entry|Function prototype| diff --git a/docs/mfc/reference/wm-message-handlers-f-k.md b/docs/mfc/reference/wm-message-handlers-f-k.md index e696a99370d..d5fdf788d64 100644 --- a/docs/mfc/reference/wm-message-handlers-f-k.md +++ b/docs/mfc/reference/wm-message-handlers-f-k.md @@ -4,10 +4,12 @@ title: "WM_ Message Handlers: F - K" ms.date: "11/27/2018" f1_keywords: ["ON_WM_FONTCHANGE", "ON_WM_ICONERASEBKGND", "ON_WM_KEYDOWN", "ON_WM_GETMINMAXINFO", "ON_WM_KEYUP", "ON_WM_HSCROLL", "ON_WM_KILLFOCUS", "ON_WM_HSCROLLCLIPBOARD", "ON_WM_GETDLGCODE", "ON_WM_HELPINFO", "ON_WM_INITMENUPOPUP", "ON_WM_INITMENU"] helpviewer_keywords: ["ON_WM_HELPINFO [MFC]", "ON_WM_KILLFOCUS [MFC]", "ON_WM_GETMINMAXINFO [MFC]", "ON_WM_KEYUP [MFC]", "ON_WM_HSCROLL [MFC]", "ON_WM_INITMENUPOPUP [MFC]", "ON_WM_FONTCHANGE [MFC]", "ON_WM_ICONERASEBKGND [MFC]", "ON_WM_GETDLGCODE [MFC]", "ON_WM_HSCROLLCLIPBOARD [MFC]", "ON_WM_INITMENU [MFC]", "WM_ messages [MFC]", "ON_WM_KEYDOWN [MFC]"] -ms.assetid: 0e7de191-1499-499f-859c-62742797808e --- # WM_ Message Handlers: F - K +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries on the left correspond to the function prototypes on the right: |Map entry|Function prototype| diff --git a/docs/mfc/reference/wm-message-handlers-l-m.md b/docs/mfc/reference/wm-message-handlers-l-m.md index 264bc859502..6b128ee4e41 100644 --- a/docs/mfc/reference/wm-message-handlers-l-m.md +++ b/docs/mfc/reference/wm-message-handlers-l-m.md @@ -4,10 +4,12 @@ title: "WM_ Message Handlers: L - M" ms.date: "11/04/2016" f1_keywords: ["ON_WM_MENUSELECT", "ON_WM_MBUTTONDBLCLK", "ON_WM_MOUSEACTIVATE", "ON_WM_MOUSEMOVE", "ON_WM_MOVING", "ON_WM_LBUTTONUP", "ON_WM_LBUTTONDBLCLK", "ON_WM_MEASUREITEM", "ON_WM_MDIACTIVATE", "ON_WM_MOVE", "ON_WM_LBUTTONDOWN", "ON_WM_MBUTTONDOWN", "ON_WM_MENUCHAR", "ON_WM_MBUTTONUP"] helpviewer_keywords: ["ON_WM_MENUSELECT [MFC]", "ON_WM_MBUTTONDBLCLK [MFC]", "ON_WM_MOVE [MFC]", "ON_WM_MOUSEACTIVATE [MFC]", "ON_WM_MBUTTONUP [MFC]", "ON_WM_MOUSEMOVE [MFC]", "ON_WM_MENUCHAR [MFC]", "ON_WM_MBUTTONDOWN [MFC]", "ON_WM_MEASUREITEM [MFC]", "ON_WM_MOVING [MFC]", "ON_WM_LBUTTONDOWN [MFC]", "ON_WM_MDIACTIVATE [MFC]", "ON_WM_LBUTTONDBLCLK [MFC]", "ON_WM_LBUTTONUP [MFC]", "WM_ messages"] -ms.assetid: 96ecaaf1-6d13-4e12-a454-535635967489 --- # WM_ Message Handlers: L - M +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries on the left correspond to the function prototypes on the right: |Map entry|Function prototype| diff --git a/docs/mfc/reference/wm-message-handlers-n-o.md b/docs/mfc/reference/wm-message-handlers-n-o.md index 51f2cc151fc..7d21b6da435 100644 --- a/docs/mfc/reference/wm-message-handlers-n-o.md +++ b/docs/mfc/reference/wm-message-handlers-n-o.md @@ -4,10 +4,12 @@ title: "WM_ Message Handlers: N - O" ms.date: "11/04/2016" f1_keywords: ["ON_WM_NCHITTEST", "ON_WM_NCLBUTTONDOWN", "ON_WM_NCCALCSIZE", "ON_WM_NCLBUTTONUP", "ON_WM_NCPAINT", "ON_WM_NCMBUTTONUP", "ON_WM_NCCREATE", "ON_WM_NCACTIVATE", "ON_WM_NCMOUSEMOVE", "ON_WM_NCRBUTTONDBLCLK", "ON_WM_NCLBUTTONDBLCLK", "ON_WM_NCDESTROY", "ON_WM_NCMBUTTONDBLCLK", "ON_WM_NCRBUTTONDOWN", "ON_WM_NCRBUTTONUP", "ON_WM_NCMBUTTONDOWN"] helpviewer_keywords: ["ON_WM_NCCALCSIZE [MFC]", "ON_WM_NCMBUTTONDOWN [MFC]", "ON_WM_NCRBUTTONDBLCLK [MFC]", "ON_WM_NCMBUTTONDBLCLK [MFC]", "ON_WM_NCLBUTTONDBLCLK [MFC]", "ON_WM_NCDESTROY [MFC]", "ON_WM_NCRBUTTONDOWN [MFC]", "ON_WM_NCLBUTTONDOWN [MFC]", "ON_WM_NCCREATE [MFC]", "ON_WM_NCRBUTTONUP [MFC]", "ON_WM_NCLBUTTONUP [MFC]", "ON_WM_NCPAINT [MFC]", "ON_WM_NCACTIVATE [MFC]", "ON_WM_NCHITTEST [MFC]", "ON_WM_NCMOUSEMOVE [MFC]", "ON_WM_NCMBUTTONUP [MFC]", "WM_ messages"] -ms.assetid: 4efd1cda-b642-4e8b-89e8-73255fa70d77 --- # WM_ Message Handlers: N - O +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries on the left correspond to the function prototypes on the right: |Map entry|Function prototype| diff --git a/docs/mfc/reference/wm-messages-p-r.md b/docs/mfc/reference/wm-messages-p-r.md index 257f831f491..11aef99dbbf 100644 --- a/docs/mfc/reference/wm-messages-p-r.md +++ b/docs/mfc/reference/wm-messages-p-r.md @@ -4,10 +4,12 @@ title: "WM_ Messages: P - R" ms.date: "11/04/2016" f1_keywords: ["ON_WM_RBUTTONUP", "ON_WM_PALETTECHANGED", "ON_WM_RBUTTONDBLCLK", "ON_WM_QUERYENDSESSION", "ON_WM_PARENTNOTIFY", "ON_WM_PALETTEISCHANGING", "ON_WM_QUERYOPEN", "ON_WM_PAINT", "ON_WM_QUERYNEWPALETTE", "ON_WM_RBUTTONDOWN", "ON_WM_RENDERALLFORMATS", "ON_WM_PAINTCLIPBOARD", "ON_WM_RENDERFORMAT", "ON_WM_QUERYDRAGICON"] helpviewer_keywords: ["ON_WM_RENDERFORMAT [MFC]", "ON_WM_QUERYOPEN [MFC]", "ON_WM_RBUTTONDOWN [MFC]", "ON_WM_PAINTCLIPBOARD [MFC]", "ON_WM_QUERYNEWPALETTE [MFC]", "ON_WM_RBUTTONUP [MFC]", "ON_WM_PARENTNOTIFY [MFC]", "ON_WM_RBUTTONDBLCLK [MFC]", "ON_WM_PALETTECHANGED [MFC]", "ON_WM_PALETTEISCHANGING [MFC]", "ON_WM_QUERYDRAGICON [MFC]", "ON_WM_PAINT [MFC]", "ON_WM_RENDERALLFORMATS [MFC]", "ON_WM_QUERYENDSESSION [MFC]", "WM_ messages"] -ms.assetid: f46962e5-8329-4f1f-9b4d-fdad2a5ce1f8 --- # WM_ Messages: P - R +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries correspond to the function prototypes: |Map entry|Function prototype| diff --git a/docs/mfc/reference/wm-messages-s.md b/docs/mfc/reference/wm-messages-s.md index 78fee76db60..70fb5ac333d 100644 --- a/docs/mfc/reference/wm-messages-s.md +++ b/docs/mfc/reference/wm-messages-s.md @@ -4,10 +4,12 @@ title: "WM_ Messages: S" ms.date: "11/04/2016" f1_keywords: ["ON_WM_SYSDEADCHAR", "ON_WM_SYSKEYDOWN", "ON_WM_STYLECHANGING", "ON_WM_STYLECHANGED", "ON_WM_SPOOLERSTATUS", "ON_WM_SYSCHAR", "ON_WM_SETFOCUS", "ON_WM_SIZE", "ON_WM_SIZING", "ON_WM_SETCURSOR", "ON_WM_SYSCOMMAND", "ON_WM_SETTINGCHANGE", "ON_WM_SHOWWINDOW", "ON_WM_SYSKEYUP", "ON_WM_SIZECLIPBOARD", "ON_WM_SYSCOLORCHANGE"] helpviewer_keywords: ["ON_WM_SIZE [MFC]", "ON_WM_SETFOCUS [MFC]", "ON_WM_SIZING [MFC]", "ON_WM_SYSCHAR [MFC]", "ON_WM_SETTINGCHANGE [MFC]", "ON_WM_SYSDEADCHAR [MFC]", "ON_WM_SHOWWINDOW [MFC]", "ON_WM_STYLECHANGING [MFC]", "ON_WM_SYSCOMMAND [MFC]", "ON_WM_STYLECHANGED [MFC]", "ON_WM_SPOOLERSTATUS [MFC]", "ON_WM_SYSCOLORCHANGE [MFC]", "ON_WM_SETCURSOR [MFC]", "ON_WM_SIZECLIPBOARD [MFC]", "ON_WM_SYSKEYUP [MFC]", "ON_WM_SYSKEYDOWN [MFC]", "WM_ messages"] -ms.assetid: 4b9aec79-a98f-4aa0-a3d9-110941b6dcbc --- # WM_ Messages: S +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries correspond to the function prototypes. |Map entry|Function prototype| diff --git a/docs/mfc/reference/wm-messages-t-z.md b/docs/mfc/reference/wm-messages-t-z.md index b60436e68dc..4c65130ce0f 100644 --- a/docs/mfc/reference/wm-messages-t-z.md +++ b/docs/mfc/reference/wm-messages-t-z.md @@ -4,10 +4,12 @@ title: "WM_ Messages: T - Z" ms.date: "11/04/2016" f1_keywords: ["ON_WM_TCARD", "ON_WM_WININICHANGE", "ON_WM_VSCROLLCLIPBOARD", "ON_WM_VSCROLL", "ON_WM_WINDOWPOSCHANGED", "ON_WM_TIMECHANGE", "ON_WM_TIMER", "ON_WM_VKEYTOITEM", "ON_WM_WINDOWPOSCHANGING"] helpviewer_keywords: ["ON_WM_VSCROLLCLIPBOARD [MFC]", "ON_WM_WININICHANGE [MFC]", "ON_WM_WINDOWPOSCHANGED [MFC]", "ON_WM_TCARD [MFC]", "ON_WM_TIMECHANGE [MFC]", "ON_WM_TIMER [MFC]", "WM_ messages [MFC]", "ON_WM_WINDOWPOSCHANGING [MFC]", "ON_WM_VKEYTOITEM [MFC]", "ON_WM_VSCROLL"] -ms.assetid: c528bb2e-ddb5-4da6-b652-432a387408b8 --- # WM_ Messages: T - Z +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following map entries correspond to the function prototypes: |Map entry|Function prototype| diff --git a/docs/mfc/reflected-window-message-ids.md b/docs/mfc/reflected-window-message-ids.md index 45071edf6dd..aec1d557a2b 100644 --- a/docs/mfc/reflected-window-message-ids.md +++ b/docs/mfc/reflected-window-message-ids.md @@ -4,10 +4,12 @@ title: "Reflected Window Message IDs" ms.date: "11/04/2016" f1_keywords: ["OCM_CTLCOLORBTN", "OCM_PARENTNOTIFY", "OCM_VKEYTOITEM", "OCM_CTLCOLORSTATIC", "OCM_HSCROLL", "OCM_CHARTOITEM", "OCM_DRAWITEM", "OCM_MEASUREITEM", "OCM_COMPAREITEM", "OCM_COMMAND", "OCM_NOTIFY", "OCM_CTLCOLORMSGBOX", "OCM_DELETEITEM", "OCM_CTLCOLORLISTBOX", "OCM_CTLCOLORDLG", "OCM_CTLCOLOREDIT", "OCM_CTLCOLORSCROLLBAR", "OCM_VSCROLL", "OCM_CTLCOLOR"] helpviewer_keywords: ["OCM_HSCROLL message [MFC]", "OCM_PARENTNOTIFY message [MFC]", "messages, reflected", "reflected messages, window message Ids", "OCM_CTLCOLORDLG message [MFC]", "OCM_COMMAND message [MFC]", "OCM_CTLCOLORMSGBOX message [MFC]", "OCM_COMPAREITEM message [MFC]", "OCM_DRAWITEM message [MFC]", "OCM_VSCROLL message [MFC]", "OCM_CTLCOLOREDIT message [MFC]", "OCM_VKEYTOITEM message [MFC]", "OCM_CHARTOITEM message [MFC]", "OCM_CTLCOLORBTN message [MFC]", "OCM_CTLCOLORSTATIC message [MFC]", "OCM_MEASUREITEM message [MFC]", "OCM_CTLCOLOR message [MFC]", "OCM_CTLCOLORSCROLLBAR message [MFC]", "OCM_ messages", "OCM_DELETEITEM message [MFC]", "OCM_CTLCOLORLISTBOX message [MFC]", "OCM_NOTIFY message [MFC]", "reflected messages"] -ms.assetid: 3417ff51-ff9f-458c-bff4-17c200f00d96 --- # Reflected Window Message IDs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A quick way to create an ActiveX control, or other specialized control, is to subclass a window. For more information, see [MFC ActiveX Controls: Subclassing a Windows Control](../mfc/mfc-activex-controls-subclassing-a-windows-control.md). To prevent the control's container from receiving the window messages sent by a subclassed Windows control, [COleControl](../mfc/reference/colecontrol-class.md) creates a "reflector" window to intercept certain window messages and send them back to the control. The control, in its window procedure, can then process these reflected messages by taking actions appropriate for an ActiveX control. diff --git a/docs/mfc/registering-window-classes.md b/docs/mfc/registering-window-classes.md index 2d37bda3fb5..be9840fb0a4 100644 --- a/docs/mfc/registering-window-classes.md +++ b/docs/mfc/registering-window-classes.md @@ -4,10 +4,13 @@ title: "Registering Window Classes" ms.date: "11/04/2016" f1_keywords: ["WndProc"] helpviewer_keywords: ["window classes [MFC], registering", "registry [MFC], registering classes", "AfxRegisterWndClass method [MFC]", "MFC, windows", "WinMain method [MFC], and registering window classes", "WndProc method [MFC]", "classes [MFC], registering window classes", "WinMain method [MFC]", "registering window classes [MFC]"] -ms.assetid: 30994bc4-a362-43da-bcc5-1bf67a3fc929 +ms.topic: concept-article --- # Registering Window Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Window "classes" in traditional programming for Windows define the characteristics of a "class" (not a C++ class) from which any number of windows can be created. This kind of class is a template or model for creating windows. ## Window Class Registration in Traditional Programs for Windows diff --git a/docs/mfc/registration.md b/docs/mfc/registration.md index 93dd93f87f5..33ac6b7fa0b 100644 --- a/docs/mfc/registration.md +++ b/docs/mfc/registration.md @@ -3,10 +3,12 @@ description: "Learn more about: Registration" title: "Registration" ms.date: "11/04/2016" helpviewer_keywords: ["servers [MFC], initializing", "initializing servers [MFC]", "OLE, registration", "installing servers [MFC]", "registry [MFC], OLE item database", "registration databases [MFC]", "servers [MFC], installing", "OLE server applications [MFC], registering servers"] -ms.assetid: 991d5684-72c1-4f9e-a09a-9184ed12bbb9 --- # Registration +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When a user wants to insert an OLE item into an application, OLE presents a list of object types to choose from. OLE gets this list from the system registration database, which contains information provided by all server applications. When a server registers itself, the entries it puts into the system registration database (the Registry) describe each type of object it supplies, file extensions, and the path to itself, among other information. The framework and the OLE system dynamic-link libraries (DLL) use this registry to determine what types of OLE items are available on the system. The OLE system DLLs also use this registry to determine how to launch a server application when a linked or embedded object is activated. diff --git a/docs/mfc/relationship-between-a-cpp-window-object-and-an-hwnd.md b/docs/mfc/relationship-between-a-cpp-window-object-and-an-hwnd.md index 91522b05d2d..0ce79cf6314 100644 --- a/docs/mfc/relationship-between-a-cpp-window-object-and-an-hwnd.md +++ b/docs/mfc/relationship-between-a-cpp-window-object-and-an-hwnd.md @@ -4,10 +4,12 @@ title: "Relationship Between a C++ Window Object and an HWND" ms.date: "11/19/2018" f1_keywords: ["HWND"] helpviewer_keywords: ["Windows window [MFC]", "window objects [MFC], HWND and", "HWND [MFC]", "CWnd class [MFC], HWND", "HWND, window objects [MFC]"] -ms.assetid: f2e76340-6691-4ee6-9424-0345634a9469 --- # Relationship Between a C++ Window Object and an HWND +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The window *object* is an object of the C++ `CWnd` class (or a derived class) that your program creates directly. It comes and goes in response to your program's constructor and destructor calls. The Windows *window*, on the other hand, is an opaque handle to an internal Windows data structure that corresponds to a window and consumes system resources when present. A Windows window is identified by a "window handle" (`HWND`) and is created after the `CWnd` object is created by a call to the `Create` member function of class `CWnd`. The window may be destroyed either by a program call or by a user's action. The window handle is stored in the window object's *m_hWnd* member variable. The following figure shows the relationship between the C++ window object and the Windows window. Creating windows is discussed in [Creating Windows](../mfc/creating-windows.md). Destroying windows is discussed in [Destroying Window Objects](../mfc/destroying-window-objects.md). ![CWnd window object and resulting window.](../mfc/media/vc37fj1.gif "CWnd window object and resulting window")
diff --git a/docs/mfc/relationship-to-the-c-language-api.md b/docs/mfc/relationship-to-the-c-language-api.md index b055335b658..5fe382a89a6 100644 --- a/docs/mfc/relationship-to-the-c-language-api.md +++ b/docs/mfc/relationship-to-the-c-language-api.md @@ -3,13 +3,15 @@ description: "Learn more about: Relationship to the C-Language API" title: "Relationship to the C-Language API" ms.date: "11/04/2016" helpviewer_keywords: ["books [MFC], about MFC and Windows SDK", "books [MFC]", "MFC, Windows API", "Visual C, Windows API calls", "Windows API [MFC], and MFC"] -ms.assetid: 334e8efc-f3cc-4018-bc2e-02908b2a39fe --- # Relationship to the C-Language API +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The single characteristic that sets the Microsoft Foundation Class (MFC) Library apart from other class libraries for Windows is the very close mapping to the Windows API written in the C language. Further, you can generally mix calls to the class library freely with direct calls to the Windows API. This direct access does not, however, imply that the classes are a complete replacement for that API. Developers must still occasionally make direct calls to some Windows functions, such as [SetCursor](/windows/win32/api/winuser/nf-winuser-setcursor) and [GetSystemMetrics](/windows/win32/api/winuser/nf-winuser-getsystemmetrics), for example. A Windows function is wrapped by a class member function only when there is a clear advantage to doing so. -Because you sometimes need to make native Windows function calls, you should have access to the C-language Windows API documentation. This documentation is included with Microsoft Visual C++. +Because you sometimes need to make native Windows function calls, you should have access to the C-language Windows API documentation. This documentation is included with Visual Studio. > [!NOTE] > For an overview of how the MFC Library framework operates, see [Using the Classes to Write Applications for Windows](../mfc/using-the-classes-to-write-applications-for-windows.md). diff --git a/docs/mfc/relationships-among-mfc-objects.md b/docs/mfc/relationships-among-mfc-objects.md index 81cdad19204..a81651518ab 100644 --- a/docs/mfc/relationships-among-mfc-objects.md +++ b/docs/mfc/relationships-among-mfc-objects.md @@ -3,10 +3,12 @@ description: "Learn more about: Relationships Among MFC Objects" title: "Relationships Among MFC Objects" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, relationships between key objects", "objects [MFC], relationships", "relationships, MFC objects", "MFC object relationships"] -ms.assetid: 6e8f3b51-e80f-4d88-94c8-4c1e4ee163ad --- # Relationships Among MFC Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To help put the document/view creation process in perspective, consider a running program: a document, the frame window used to contain the view, and the view associated with the document. - A document keeps a list of the views of that document and a pointer to the document template that created the document. diff --git a/docs/mfc/responding-to-dynamic-data-exchange-dde.md b/docs/mfc/responding-to-dynamic-data-exchange-dde.md index 9ec13c9df44..c34e3e3c131 100644 --- a/docs/mfc/responding-to-dynamic-data-exchange-dde.md +++ b/docs/mfc/responding-to-dynamic-data-exchange-dde.md @@ -3,10 +3,13 @@ description: "Learn more about: Responding to Dynamic Data Exchange (DDE)" title: "Responding to Dynamic Data Exchange (DDE)" ms.date: "11/04/2016" helpviewer_keywords: ["registry [MFC], most recently used files", "frame windows [MFC], dynamic data exchange (DDE)", "DDE (Dynamic Data Exchange), frame windows", "registration [MFC], shell", "Shell [MFC], registering file types", "windows [MFC], and dynamic data exchange", "responding to dynamic data exchange (DDE)", "frame windows [MFC], shell registration"] -ms.assetid: 4db838d5-62cf-4123-915a-66e514155c0c +ms.topic: concept-article --- # Responding to Dynamic Data Exchange (DDE) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The frame window can respond to dynamic data exchange (DDE) requests to open files from the File Manager (if the file extension is registered or associated with the application). See [Shell Registration](../mfc/special-cwinapp-services.md). ## See also diff --git a/docs/mfc/retrieving-data-from-the-dialog-object.md b/docs/mfc/retrieving-data-from-the-dialog-object.md index 7c870f78077..cd3e39f36e0 100644 --- a/docs/mfc/retrieving-data-from-the-dialog-object.md +++ b/docs/mfc/retrieving-data-from-the-dialog-object.md @@ -3,10 +3,13 @@ description: "Learn more about: Retrieving Data from the Dialog Object" title: "Retrieving Data from the Dialog Object" ms.date: "11/04/2016" helpviewer_keywords: ["dialog boxes [MFC], retrieving user data", "dialog box data [MFC]", "data [MFC], retrieving", "GetDlgItemText method [MFC]", "SetDlgItemText method [MFC]", "SetWindowText method [MFC]", "dialog box data [MFC], retrieving", "retrieving data [MFC]", "user input [MFC], retrieving from MFC dialog boxes", "capturing user input [MFC]", "dialog box controls [MFC], initializing values", "DDX (dialog data exchange) [MFC]", "MFC dialog boxes [MFC], retrieving user input", "data retrieval [MFC], dialog boxes", "data [MFC], dialog boxes", "DDX (dialog data exchange) [MFC], about DDX", "DDX (dialog data exchange) [MFC], retrieving data from Dialog object", "GetWindowText method [MFC]"] -ms.assetid: bdca2b61-6b53-4c2e-b426-8712c7a38ec0 +ms.topic: concept-article --- # Retrieving Data from the Dialog Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The framework provides an easy way to initialize the values of controls in a dialog box and to retrieve values from the controls. The more laborious manual approach is to call functions such as the `SetDlgItemText` and `GetDlgItemText` member functions of class `CWnd`, which apply to control windows. With these functions, you access each control individually to set or get its value, calling functions such as `SetWindowText` and `GetWindowText`. The framework's approach automates both initialization and retrieval. Dialog data exchange (DDX) lets you exchange data between the controls in the dialog box and member variables in the dialog object more easily. This exchange works both ways. To initialize the controls in the dialog box, you can set the values of data members in the dialog object, and the framework will transfer the values to the controls before the dialog box is displayed. Then you can at any time update the dialog data members with data entered by the user. At that point, you can use the data by referring to the data member variables. diff --git a/docs/mfc/ribbon-designer-mfc.md b/docs/mfc/ribbon-designer-mfc.md index d642ff01095..92a66a7e4ec 100644 --- a/docs/mfc/ribbon-designer-mfc.md +++ b/docs/mfc/ribbon-designer-mfc.md @@ -4,10 +4,12 @@ title: "Ribbon Designer (MFC)" ms.date: "11/19/2018" f1_keywords: ["vc.editors.ribbon.F1"] helpviewer_keywords: ["Ribbon Designer (MFC)", "MFC Ribbon Designer"] -ms.assetid: 0806dfd6-7d11-471a-99e1-4072852231f9 --- # Ribbon Designer (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Ribbon Designer lets you create and customize ribbons in MFC applications. A ribbon is a user interface (UI) element that organizes commands into logical groups. These groups appear on separate tabs in a strip across the top of the window. The ribbon replaces the menu bar and toolbars. A ribbon can significantly improve application usability. For more information, see [Ribbons](/windows/win32/uxguide/cmd-ribbons). The following illustration shows a ribbon. ![MFC Ribbon Resource Control.](../mfc/media/ribbon_no_callouts.png "MFC Ribbon Resource Control") diff --git a/docs/mfc/rich-edit-control-examples.md b/docs/mfc/rich-edit-control-examples.md index 8a37dc61eb9..f5b095f2dc4 100644 --- a/docs/mfc/rich-edit-control-examples.md +++ b/docs/mfc/rich-edit-control-examples.md @@ -2,10 +2,12 @@ description: "Learn more about: Rich Edit Control Examples" title: "Rich Edit Control Examples" ms.date: "02/06/2019" -ms.assetid: ac98bf45-ca74-459c-9b3e-df278a67a00f --- # Rich Edit Control Examples +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The MFC OLE sample [WORDPAD](https://github.com/Microsoft/VCSamples/tree/da802c2aa92a730b3da33c5957186f128709c398/VC2010Samples/MFC/Visual%20C%2B%2B%202008%20Feature%20Pack/WordPad) uses the `CRichEditView`, `CRichEditDoc`, and `CRichEditCntrItem` classes. By extension, it uses the [CRichEditCtrl](../mfc/reference/cricheditctrl-class.md). For a quick description of these three classes, see [Classes Related to Rich Edit Controls](../mfc/classes-related-to-rich-edit-controls.md). ## See also diff --git a/docs/mfc/role-of-the-view-in-printing.md b/docs/mfc/role-of-the-view-in-printing.md index d6d0724eeaa..5900d5ab150 100644 --- a/docs/mfc/role-of-the-view-in-printing.md +++ b/docs/mfc/role-of-the-view-in-printing.md @@ -3,10 +3,12 @@ description: "Learn more about: Role of the View in Printing" title: "Role of the View in Printing" ms.date: "11/04/2016" helpviewer_keywords: ["views [MFC], printing", "OnDraw method [MFC], and printing", "printing [MFC], OnDraw method [MFC]", "printing [MFC], views", "CView class [MFC], role in printing", "printing views [MFC]"] -ms.assetid: 8d4a3c8e-1fce-4edc-b608-94cb5f3e487e --- # Role of the View in Printing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your view also plays two important roles in printing its associated document. The view: diff --git a/docs/mfc/root-class-cobject.md b/docs/mfc/root-class-cobject.md index 3f59550cd10..faaf0b9e8cb 100644 --- a/docs/mfc/root-class-cobject.md +++ b/docs/mfc/root-class-cobject.md @@ -3,10 +3,12 @@ description: "Learn more about: Root Class: CObject" title: "Root Class: CObject" ms.date: "11/04/2016" helpviewer_keywords: ["base classes [MFC], MFC objects", "classes [MFC], MFC base class [MFC]", "root class [MFC]", "MFC, base class"] -ms.assetid: 593706f3-e9e5-435f-815d-e7b5176b2a61 --- # Root Class: CObject +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Most of the classes in the Microsoft Foundation Class (MFC) Library are derived from a single base class at the root of the class hierarchy. `CObject` provides a number of useful capabilities to all classes derived from it, with very low overhead. For more information about `CObject` and its capabilities, see [Using CObject](../mfc/using-cobject.md). [CObject](../mfc/reference/cobject-class.md)
diff --git a/docs/mfc/rubber-banding-and-trackers.md b/docs/mfc/rubber-banding-and-trackers.md index 4fb1ae81c9b..0e3385f5383 100644 --- a/docs/mfc/rubber-banding-and-trackers.md +++ b/docs/mfc/rubber-banding-and-trackers.md @@ -3,10 +3,13 @@ description: "Learn more about: Rubber-Banding and Trackers" title: "Rubber-Banding and Trackers" ms.date: "11/04/2016" helpviewer_keywords: ["trackers [MFC]", "CRectTracker class [MFC], implementing trackers", "OLE objects [MFC], selecting", "rubber banding [MFC]", "WM_LBUTTONDOWN [MFC]"] -ms.assetid: 0d0fa64c-6418-4baf-ab7f-2d16ca039230 +ms.topic: concept-article --- # Rubber-Banding and Trackers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Another feature supplied with trackers is the "rubber-band" selection, which allows a user to select multiple OLE items by dragging a sizing rectangle around the items to be selected. When the user releases the left mouse button, items within the region selected by the user are selected and can be manipulated by the user. For instance, the user might drag the selection into another container application. Implementing this feature requires some additional code in your application's WM_LBUTTONDOWN handler function. diff --git a/docs/mfc/run-member-function.md b/docs/mfc/run-member-function.md index d9524c34a85..6c22de662c5 100644 --- a/docs/mfc/run-member-function.md +++ b/docs/mfc/run-member-function.md @@ -3,10 +3,12 @@ description: "Learn more about: Run Member Function" title: "Run Member Function" ms.date: "11/04/2016" helpviewer_keywords: ["WinMain method [MFC]"] -ms.assetid: 24ab7597-2354-495b-9a20-2c8ccc7385b3 --- # Run Member Function +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A framework application spends most of its time in the [Run](../mfc/reference/cwinapp-class.md#run) member function of class [CWinApp](../mfc/reference/cwinapp-class.md). After initialization, `WinMain` calls `Run` to process the message loop. `Run` cycles through a message loop, checking the message queue for available messages. If a message is available, `Run` dispatches it for action. If no messages are available, which is often true, `Run` calls `OnIdle` to do any idle-time processing that you or the framework may need done. If there are no messages and no idle processing to do, the application waits until something happens. When the application terminates, `Run` calls `ExitInstance`. The figure in [OnIdle Member Function](../mfc/onidle-member-function.md) shows the sequence of actions in the message loop. diff --git a/docs/mfc/scrolling-and-scaling-views.md b/docs/mfc/scrolling-and-scaling-views.md index 997ef315f89..ab7a05dacbb 100644 --- a/docs/mfc/scrolling-and-scaling-views.md +++ b/docs/mfc/scrolling-and-scaling-views.md @@ -3,10 +3,13 @@ description: "Learn more about: Scrolling and Scaling Views" title: "Scrolling and Scaling Views" ms.date: "11/04/2016" helpviewer_keywords: ["message handlers [MFC]", "scaling views [MFC]", "message handling [MFC], scroll bars in view class [MFC]", "scroll bars [MFC], messages", "scrolling views [MFC]"] -ms.assetid: f98a3421-c336-407e-97ee-dbb2ffd76fbd +ms.topic: concept-article --- # Scrolling and Scaling Views +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC supports views that scroll and views that are automatically scaled to the size of the frame window that displays them. Class `CScrollView` supports both kinds of views. For more information about scrolling and scaling, see class [CScrollView](../mfc/reference/cscrollview-class.md) in the *MFC Reference*. For a scrolling example, see the [Scribble sample](../overview/visual-cpp-samples.md). diff --git a/docs/mfc/scrolling-arranging-sorting-and-finding-in-list-controls.md b/docs/mfc/scrolling-arranging-sorting-and-finding-in-list-controls.md index 118697bf2bf..d2f6e704ec7 100644 --- a/docs/mfc/scrolling-arranging-sorting-and-finding-in-list-controls.md +++ b/docs/mfc/scrolling-arranging-sorting-and-finding-in-list-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Scrolling, Arranging, Sorting, and Finding in Li title: "Scrolling, Arranging, Sorting, and Finding in List Controls" ms.date: "06/03/2019" helpviewer_keywords: ["image lists [MFC], sorting", "image lists [MFC], arranging", "image lists [MFC], scrolling", "CListCtrl class [MFC], finding items in", "image lists [MFC], finding items", "CListCtrl class [MFC], scrolling", "CListCtrl class [MFC], sorting", "CListCtrl class [MFC], arranging the list"] -ms.assetid: dcc51e4c-0ca8-4319-bec5-6994cc8ac9e5 --- # Scrolling, Arranging, Sorting, and Finding in List Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + List controls ([CListCtrl](../mfc/reference/clistctrl-class.md)) are scrollable by default. For more information, see [Scroll Position](/windows/win32/Controls/using-list-view-controls) in the Windows SDK and the [Scroll](../mfc/reference/clistctrl-class.md#scroll) member function. You can call `CListCtrl` member functions to arrange list items in the control, sort items, and find particular items. For more information, see [Using ListView Controls](/windows/win32/Controls/using-list-view-controls) in the Windows SDK and the [CListCtrl](../mfc/reference/clistctrl-class.md) members [Arrange](../mfc/reference/clistctrl-class.md#arrange), [SortItems](../mfc/reference/clistctrl-class.md#sortitems), and [FindItem](../mfc/reference/clistctrl-class.md#finditem). diff --git a/docs/mfc/sdi-and-mdi.md b/docs/mfc/sdi-and-mdi.md index 9eb07bb3531..0d8faf95203 100644 --- a/docs/mfc/sdi-and-mdi.md +++ b/docs/mfc/sdi-and-mdi.md @@ -3,10 +3,12 @@ description: "Learn more about: SDI and MDI" title: "SDI and MDI" ms.date: "11/04/2016" helpviewer_keywords: ["frame windows [MFC], SDI applications", "frame windows [MFC], MDI applications", "MFC, windows", "single document interface (SDI) [MFC], applications", "MDI [MFC], vs. SDI"] -ms.assetid: bb7239d9-4759-4f63-bfff-44a04b48c067 --- # SDI and MDI +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC makes it easy to work with both single-document interface (SDI) and multiple-document interface (MDI) applications. SDI applications allow only one open document frame window at a time. MDI applications allow multiple document frame windows to be open in the same instance of an application. An MDI application has a window within which multiple MDI child windows, which are frame windows themselves, can be opened, each containing a separate document. In some applications, the child windows can be of different types, such as chart windows and spreadsheet windows. In that case, the menu bar can change as MDI child windows of different types are activated. diff --git a/docs/mfc/security-implications-of-customization.md b/docs/mfc/security-implications-of-customization.md index e5a33963ddb..ba8a5191d15 100644 --- a/docs/mfc/security-implications-of-customization.md +++ b/docs/mfc/security-implications-of-customization.md @@ -3,10 +3,12 @@ description: "Learn more about: Security Implications of Customization" title: "Security Implications of Customization" ms.date: "11/04/2016" helpviewer_keywords: ["security, MFC Feature Pack", "MFC Feature Pack, security"] -ms.assetid: 9be96b12-be38-43bd-a133-5d671265f7a1 --- # Security Implications of Customization +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic discusses a potential security weakness in MFC. ## Potential Security Weakness diff --git a/docs/mfc/selecting-a-graphic-object-into-a-device-context.md b/docs/mfc/selecting-a-graphic-object-into-a-device-context.md index 711b5ca8758..a1946b710d9 100644 --- a/docs/mfc/selecting-a-graphic-object-into-a-device-context.md +++ b/docs/mfc/selecting-a-graphic-object-into-a-device-context.md @@ -3,10 +3,13 @@ description: "Learn more about: Selecting a Graphic Object into a Device Context title: "Selecting a Graphic Object into a Device Context" ms.date: "11/04/2016" helpviewer_keywords: ["graphic objects [MFC], selecting into device context", "SelectObject method [MFC]", "GDI objects [MFC], device contexts", "lifetime, graphic objects [MFC]", "device contexts, selecting graphic objects into", "device contexts, graphic objects [MFC]"] -ms.assetid: cf54a330-63ef-421f-83eb-90ec7bd82eef +ms.topic: concept-article --- # Selecting a Graphic Object into a Device Context +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This topic applies to using graphic objects in a window's device context. After you [create a drawing object](../mfc/one-stage-and-two-stage-construction-of-objects.md), you must select it into the device context in place of the default object stored there: [!code-cpp[NVC_MFCDocViewSDI#7](../mfc/codesnippet/cpp/selecting-a-graphic-object-into-a-device-context_1.cpp)] diff --git a/docs/mfc/sequence-of-operations-for-building-mfc-applications.md b/docs/mfc/sequence-of-operations-for-building-mfc-applications.md index 3c77d334150..a19042a0516 100644 --- a/docs/mfc/sequence-of-operations-for-building-mfc-applications.md +++ b/docs/mfc/sequence-of-operations-for-building-mfc-applications.md @@ -3,10 +3,12 @@ description: "Learn more about: Sequence of Operations for Building MFC Applicat title: "Sequence of Operations for Building MFC Applications" ms.date: "09/09/2019" helpviewer_keywords: ["applications [MFC], developing"] -ms.assetid: 6973c714-fe20-48c6-926b-de88356b3a3d --- # Sequence of Operations for Building MFC Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table explains the general sequence you might typically follow as you develop your MFC application. ### Sequence for Building an Application with the Framework @@ -14,8 +16,8 @@ The following table explains the general sequence you might typically follow as |Task|You do|The framework does| |----------|------------|------------------------| |Create a skeleton application.|Run the [MFC Application Wizard](../mfc/reference/mfc-application-wizard.md). Specify the options you want in the options pages. Options include making the application a COM component, container, or both; adding Automation; and making the application database-aware.|The MFC Application Wizard creates the files for a skeleton application, including source files for your application, document, view, and frame windows; a resource file; a project file; and others, all tailored to your specifications.| -|See what the framework and the MFC Application Wizard offer without adding a line of your own code.|Build the skeleton application and run it in Visual C++.|The running skeleton application derives many standard **File**, **Edit**, **View**, and **Help** menu commands from the framework. For MDI applications, you also get a fully functional Windows menu, and the framework manages creation, arrangement, and destruction of MDI child windows.| -|Construct your application's user interface.|Use the Visual C++ [resource editors](../windows/resource-editors.md) to visually edit the application's user interface:

- Create menus.
- Define accelerators.
- Create dialog boxes.
- Create and edit bitmaps, icons, and cursors.
- Edit the toolbar created for you by the MFC Application Wizard.
- Create and edit other resources.

You can also test the dialog boxes in the dialog editor.|The default resource file created by the MFC Application Wizard supplies many of the resources you need. Visual C++ lets you edit existing resources and add new resources easily and visually.| +|See what the framework and the MFC Application Wizard offer without adding a line of your own code.|Build the skeleton application and run it in Visual Studio.|The running skeleton application derives many standard **File**, **Edit**, **View**, and **Help** menu commands from the framework. For MDI applications, you also get a fully functional Windows menu, and the framework manages creation, arrangement, and destruction of MDI child windows.| +|Construct your application's user interface.|Use the Visual Studio [resource editors](../windows/resource-editors.md) to visually edit the application's user interface:

- Create menus.
- Define accelerators.
- Create dialog boxes.
- Create and edit bitmaps, icons, and cursors.
- Edit the toolbar created for you by the MFC Application Wizard.
- Create and edit other resources.

You can also test the dialog boxes in the dialog editor.|The default resource file created by the MFC Application Wizard supplies many of the resources you need. Visual Studio lets you edit existing resources and add new resources easily and visually.| |Map menus to handler functions.|Use the **Events** button in the [**Properties** window](/visualstudio/ide/reference/properties-window) in **Class View** (or the **Commands** tab in [Class Wizard](reference/mfc-class-wizard.md)) to connect menus and accelerators to handler functions in your code.|These tools insert message-map entries and empty function templates into the source files you specify and manages many manual coding tasks.| |Write your handler code.|Use Class View to jump directly to the code in the source code editor. Fill in the code for your handler functions. For more information on using Class View and about wizards that add code to a project, see [Adding Functionality with Code Wizards](../ide/adding-functionality-with-code-wizards-cpp.md).|Class View opens the editor, scrolls to the empty function template and positions the cursor for you.| |Map toolbar buttons to commands.|Map each button on your toolbar to a menu or accelerator command by assigning the button the appropriate command ID.|The framework controls the drawing, enabling, disabling, checking, and other visual aspects of the toolbar buttons.| @@ -33,7 +35,7 @@ The following table explains the general sequence you might typically follow as |Create database forms.|If you want a form-based data-access application, derive your view class from [CRecordView](../mfc/reference/crecordview-class.md) (for ODBC programming).|The view works like a form view, but its controls are connected to the fields of a [CRecordset](../mfc/reference/crecordset-class.md) object representing a database table. MFC moves data between the controls and the recordset for you.| |Create a simple text editor.|If you want your view to be a simple text editor, derive your view class or classes from [CEditView](../mfc/reference/ceditview-class.md) or [CRichEditView](../mfc/reference/cricheditview-class.md).|The view provides editing functions, Clipboard support, and file input/output. `CRichEditView` provides styled text.| |Add splitter windows.|If you want to support window splitting, add a [CSplitterWnd](../mfc/reference/csplitterwnd-class.md) object to your SDI frame window or MDI child window and hook it up in the window's [OnCreateClient](../mfc/reference/cframewnd-class.md#oncreateclient) member function.|The framework supplies splitter-box controls next to the scroll bars and manages splitting your view into multiple panes. If the user splits a window, the framework creates and attaches additional view objects to the document.| -|Build, test, and debug your application.|Use the facilities of Visual C++ to build, test, and debug your application.|Visual C++ lets you adjust compile, link, and other options. It also lets you browse your source code and class structure.| +|Build, test, and debug your application.|Use the facilities of Visual Studio to build, test, and debug your application.|Visual Studio lets you adjust compile, link, and other options. It also lets you browse your source code and class structure.| ## See also diff --git a/docs/mfc/sequence-of-operations-for-creating-activex-controls.md b/docs/mfc/sequence-of-operations-for-creating-activex-controls.md index 1b1dc9884d5..ac9ef6254a2 100644 --- a/docs/mfc/sequence-of-operations-for-creating-activex-controls.md +++ b/docs/mfc/sequence-of-operations-for-creating-activex-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Sequence of Operations for Creating ActiveX Cont title: "Sequence of Operations for Creating ActiveX Controls" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], creating", "ActiveX controls [MFC], creating", "sequence [MFC], for creating ActiveX controls", "OLE controls [MFC], MFC", "sequence [MFC]"] -ms.assetid: 7d868c53-a0af-4ef6-a89c-e1c03c583a53 --- # Sequence of Operations for Creating ActiveX Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows your role and the framework's role in creating ActiveX controls (formerly known as OLE controls). ### Creating ActiveX Controls @@ -16,7 +18,7 @@ The following table shows your role and the framework's role in creating ActiveX |Create an ActiveX control framework.|Run the MFC ActiveX Control Wizard to create your control. Specify the options you want in the options pages. Options include the type and name of the control in the project, licensing, subclassing, and an About Box method.|The MFC ActiveX Control Wizard creates the files for an ActiveX control with basic functionality, including source files for your application, control, and property page or pages; a resource file; a project file; and others, all tailored to your specifications.| |See what the control and the ActiveX Control Wizard offer without adding a line of your own code.|Build the ActiveX control and test it with Internet Explorer or the [TSTCON sample](../overview/visual-cpp-samples.md).|The running control has the ability to be resized and moved. It also has an **About Box** method (if chosen) that can be invoked.| |Implement the control's methods and properties.|Implement your control-specific methods and properties by adding member functions to provide an exposed interface to the control's data. Add member variables to hold data structures and use event handlers to fire events when you determine.|The framework has already defined a map to support the control's events, properties, and methods, leaving you to focus on how the properties and methods are implemented. The default property page is viewable and a default About Box method is supplied.| -|Construct the control's property page or pages.|Use the Visual C++ resource editors to visually edit the control's property page interface:

- Create additional property pages.
- Create and edit bitmaps, icons, and cursors.

You can also test the property page(s) in the dialog editor.|The default resource file created by the MFC Application Wizard supplies many of the resources you need. Visual C++ lets you edit existing resources and add new resources easily and visually.| +|Construct the control's property page or pages.|Use the Visual Studio resource editors to visually edit the control's property page interface:

- Create additional property pages.
- Create and edit bitmaps, icons, and cursors.

You can also test the property page(s) in the dialog editor.|The default resource file created by the MFC Application Wizard supplies many of the resources you need. Visual Studio lets you edit existing resources and add new resources easily and visually.| |Test the control's events, methods, and properties.|Rebuild the control and use Test Container to test that your handlers work correctly.|You can invoke the control's methods and manipulate its properties through the property page interface or through Test Container. In addition, use Test Container to track events fired from the control and notifications received by the control's container.| ## See also diff --git a/docs/mfc/sequence-of-operations-for-creating-database-applications.md b/docs/mfc/sequence-of-operations-for-creating-database-applications.md index 2f39ff70f31..ea35c960ae0 100644 --- a/docs/mfc/sequence-of-operations-for-creating-database-applications.md +++ b/docs/mfc/sequence-of-operations-for-creating-database-applications.md @@ -3,14 +3,16 @@ description: "Learn more about: Sequence of Operations for Creating Database App title: "Sequence of Operations for Creating Database Applications" ms.date: "11/04/2016" helpviewer_keywords: ["applications [MFC], database", "database applications [MFC]", "database applications [MFC], creating", "MFC, database applications"] -ms.assetid: 9371da59-8536-43cd-8314-706ad320e2ec --- # Sequence of Operations for Creating Database Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows your role and the framework's role in writing database applications. > [!NOTE] -> The Visual C++ environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use ODBC for new MFC projects. You should only use DAO in maintaining existing applications. +> The Visual Studio environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use ODBC for new MFC projects. You should only use DAO in maintaining existing applications. ### Creating Database Applications @@ -18,7 +20,7 @@ The following table shows your role and the framework's role in writing database |----------|------------|------------------------| |Decide whether to use the MFC ODBC or DAO classes.|Use ODBC for new MFC projects. Use DAO only to maintain existing applications. For general information, see the article [Data Access Programming](../data/data-access-programming-mfc-atl.md).|The framework supplies classes that support database access.| |Create your skeleton application with database options.|Run the MFC Application Wizard. Select options on the Database Support page. If you choose an option that creates a record view, also specify:

- Data source and table name or names
- Query name or names.|The MFC Application Wizard creates files and specifies the necessary includes. Depending on the options you specify, the files can include a recordset class.| -|Design your database form or forms.|Use the Visual C++ dialog editor to place controls on the dialog template resources for your record view classes.|The MFC Application Wizard creates an empty dialog template resource for you to fill in.| +|Design your database form or forms.|Use the Visual Studio dialog editor to place controls on the dialog template resources for your record view classes.|The MFC Application Wizard creates an empty dialog template resource for you to fill in.| |Create additional record view and recordset classes as needed.|Use Class View to create the classes and the dialog editor to design the views.|Class View creates additional files for your new classes.| |Create recordset objects as needed in your code. Use each recordset to manipulate records...|Your recordsets are based on the classes derived from [CRecordset](../mfc/reference/crecordset-class.md) with the wizards.|ODBC uses record field exchange (RFX) to exchange data between the database and your recordset's field data members. If you are using a record view, dialog data exchange (DDX) exchanges data between the recordset and the controls on the record view.| |...or create an explicit [CDatabase](../mfc/reference/cdatabase-class.md) in your code for each database you want to open.|Base your recordset objects on the database objects.|The database object provides an interface to the data source.| diff --git a/docs/mfc/sequence-of-operations-for-creating-ole-applications.md b/docs/mfc/sequence-of-operations-for-creating-ole-applications.md index 067edaef529..3ea89654f37 100644 --- a/docs/mfc/sequence-of-operations-for-creating-ole-applications.md +++ b/docs/mfc/sequence-of-operations-for-creating-ole-applications.md @@ -3,10 +3,12 @@ description: "Learn more about: Sequence of Operations for Creating OLE Applicat title: "Sequence of Operations for Creating OLE Applications" ms.date: "11/04/2016" helpviewer_keywords: ["OLE applications [MFC], creating", "OLE applications [MFC]", "applications [OLE], creating", "applications [OLE]"] -ms.assetid: 84b0f606-36c1-4253-9cea-44427f0074b9 --- # Sequence of Operations for Creating OLE Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows your role and the framework's role in creating OLE linking and embedding applications. These represent options available rather than a sequence of steps to perform. ### Creating OLE Applications diff --git a/docs/mfc/serialization-in-mfc.md b/docs/mfc/serialization-in-mfc.md index e864816e8ab..36fb257c7f9 100644 --- a/docs/mfc/serialization-in-mfc.md +++ b/docs/mfc/serialization-in-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Serialization in MFC" title: "Serialization in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["collection classes [MFC], serialization", "bypassing serialization [MFC]", "MFC, serialization", "serialization [MFC], MFC", "serialization [MFC], bypassing"] -ms.assetid: fb596a18-4522-47e0-96e0-192732d24c12 --- # Serialization in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the serialization mechanism provided in the Microsoft Foundation Class Library (MFC) to allow objects to persist between runs of your program. Serialization is the process of writing or reading an object to or from a persistent storage medium such as a disk file. Serialization is ideal for situations where it is desired to maintain the state of structured data (such as C++ classes or structures) during or after execution of a program. Using the serialization objects provided by MFC allows this to occur in a standard and consistent manner, relieving the user from the need to perform file operations by hand. diff --git a/docs/mfc/serialization-making-a-serializable-class.md b/docs/mfc/serialization-making-a-serializable-class.md index 1f99e1741f4..c5108c24f65 100644 --- a/docs/mfc/serialization-making-a-serializable-class.md +++ b/docs/mfc/serialization-making-a-serializable-class.md @@ -3,10 +3,12 @@ description: "Learn more about: Serialization: Making a Serializable Class" title: "Serialization: Making a Serializable Class" ms.date: "11/04/2016" helpviewer_keywords: ["serializable class [MFC]", "DECLARE_SERIAL macro [MFC]", "default constructor [MFC]", "VERSIONABLE_SCHEMA macro [MFC]", "classes [MFC], derived", "IMPLEMENT_SERIAL macro [MFC]", "no-arguments constructor [MFC]", "Serialize method, overriding", "defaults [MFC], constructor", "CObject class [MFC], deriving serializable classes", "constructors [MFC], defining with no arguments", "serialization [MFC], serializable classes", "no default constructor"] -ms.assetid: 59a14d32-1cc8-4275-9829-99639beee27c --- # Serialization: Making a Serializable Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Five main steps are required to make a class serializable. They are listed below and explained in the following sections: 1. [Deriving your class from CObject](#_core_deriving_your_class_from_cobject) (or from some class derived from `CObject`). diff --git a/docs/mfc/serialization-serialization-vs-database-input-output.md b/docs/mfc/serialization-serialization-vs-database-input-output.md index e1aca76ea6c..52e8a9d75a6 100644 --- a/docs/mfc/serialization-serialization-vs-database-input-output.md +++ b/docs/mfc/serialization-serialization-vs-database-input-output.md @@ -3,10 +3,12 @@ description: "Learn more about: Serialization: Serialization vs. Database Input/ title: "Serialization: Serialization vs. Database Input-Output" ms.date: "11/04/2016" helpviewer_keywords: ["database applications [MFC], file I/O vs. serialization", "serialization [MFC], vs. database I/O", "I/O [MFC], vs. serialization", "databases [MFC], input/output handling"] -ms.assetid: f1d23d77-4761-4a52-a7ea-54fc92d347ea --- # Serialization: Serialization vs. Database Input/Output +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains when to use document objects and serialization for file-based input/output (I/O) and when other I/O techniques are appropriate — because the application reads and writes data on a per-transaction basis, as in database applications. If you don't use serialization, you also won't need the File Open, Save, and Save As commands. Topics covered include: - [Recommendations for handling input/output](../mfc/recommendations-for-handling-input-output.md) diff --git a/docs/mfc/serialization-serializing-an-object.md b/docs/mfc/serialization-serializing-an-object.md index 232074c244b..cadb13d0f3f 100644 --- a/docs/mfc/serialization-serializing-an-object.md +++ b/docs/mfc/serialization-serializing-an-object.md @@ -3,10 +3,12 @@ description: "Learn more about: Serialization: Serializing an Object" title: "Serialization: Serializing an Object" ms.date: "11/04/2016" helpviewer_keywords: ["serializing objects [MFC]", "serialization [MFC], objects", "objects [MFC], serializing"] -ms.assetid: 1db772b1-ad55-4fcf-b133-126cca082510 --- # Serialization: Serializing an Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The article [Serialization: Making a Serializable Class](../mfc/serialization-making-a-serializable-class.md) shows how to make a class serializable. Once you have a serializable class, you can serialize objects of that class to and from a file via a [CArchive](../mfc/reference/carchive-class.md) object. This article explains: - [What a CArchive object is](../mfc/what-is-a-carchive-object.md). diff --git a/docs/mfc/serializing-data-to-and-from-files.md b/docs/mfc/serializing-data-to-and-from-files.md index 9fac8aba10d..f261f8b8832 100644 --- a/docs/mfc/serializing-data-to-and-from-files.md +++ b/docs/mfc/serializing-data-to-and-from-files.md @@ -3,10 +3,13 @@ description: "Learn more about: Serializing Data to and from Files" title: "Serializing Data to and from Files" ms.date: "11/04/2016" helpviewer_keywords: ["documents [MFC], serialization", "documents [MFC], saving", "saving documents", "deserialization [MFC]", "serialization [MFC], role of document", "serialization [MFC], role of data", "data [MFC]", "data [MFC], serializing", "document data [MFC]"] -ms.assetid: b42a0c68-4bc4-4012-9938-5433a26d2c24 +ms.topic: concept-article --- # Serializing Data to and from Files +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The basic idea of persistence is that an object should be able to write its current state, indicated by the values of its member variables, to persistent storage. Later, the object can be re-created by reading, or "deserializing," the object's state from persistent storage. A key point here is that the object itself is responsible for reading and writing its own state. Thus, for a class to be persistent, it must implement the basic serialization operations. The framework provides a default implementation for saving documents to disk files in response to the Save and Save As commands on the File menu and for loading documents from disk files in response to the Open command. With very little work, you can implement a document's ability to write and read its data to and from a file. The main thing you must do is override the [Serialize](../mfc/reference/cobject-class.md#serialize) member function in your document class. diff --git a/docs/mfc/servers-implementing-a-server.md b/docs/mfc/servers-implementing-a-server.md index c7b9e42a749..d7e904aaf38 100644 --- a/docs/mfc/servers-implementing-a-server.md +++ b/docs/mfc/servers-implementing-a-server.md @@ -3,10 +3,12 @@ description: "Learn more about: Servers: Implementing a Server" title: "Servers: Implementing a Server" ms.date: "11/04/2016" helpviewer_keywords: ["servers, implementing", "OLE server applications [MFC], implementing OLE servers"] -ms.assetid: 5bd57e8e-3b23-4f23-9597-496fac2d24b5 --- # Servers: Implementing a Server +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the code the MFC Application Wizard creates for a visual editing server application. If you are not using the application wizard, this article lists the areas where you must write code to implement a server application. If you are using the application wizard to create a new server application, it provides a significant amount of server-specific code for you. If you are adding visual editing server functionality to an existing application, you must duplicate the code that the application wizard would have provided before adding the rest of the necessary server code. diff --git a/docs/mfc/servers-implementing-in-place-frame-windows.md b/docs/mfc/servers-implementing-in-place-frame-windows.md index 3349e0c1357..8df12137b90 100644 --- a/docs/mfc/servers-implementing-in-place-frame-windows.md +++ b/docs/mfc/servers-implementing-in-place-frame-windows.md @@ -3,11 +3,13 @@ description: "Learn more about: Servers: Implementing In-Place Frame Windows" title: "Servers: Implementing In-Place Frame Windows" ms.date: "09/09/2019" helpviewer_keywords: ["frame windows [MFC], implementing", "OLE server applications [MFC], frame windows", "servers, in-place frame windows", "frame windows [MFC], in-place", "in-place frame windows"] -ms.assetid: 09bde4d8-15e2-4fba-8d14-9b954d926b92 --- # Servers: Implementing In-Place Frame Windows -This article explains what you must do to implement in-place frame windows in your visual editing server application if you do not use the application wizard to create your server application. In place of following the procedure outlined in this article, you could use an existing in-place frame-window class from either an application wizard-generated application or a sample provided with Visual C++. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +This article explains what you must do to implement in-place frame windows in your visual editing server application if you do not use the application wizard to create your server application. In place of following the procedure outlined in this article, you could use an existing in-place frame-window class from either an application wizard-generated application or a sample provided with Visual Studio. #### To declare an in-place frame-window class diff --git a/docs/mfc/servers-implementing-server-documents.md b/docs/mfc/servers-implementing-server-documents.md index 63a6bb9c0bb..05049ed51a8 100644 --- a/docs/mfc/servers-implementing-server-documents.md +++ b/docs/mfc/servers-implementing-server-documents.md @@ -3,10 +3,12 @@ description: "Learn more about: Servers: Implementing Server Documents" title: "Servers: Implementing Server Documents" ms.date: "11/04/2016" helpviewer_keywords: ["OLE server applications [MFC], managing server documents", "OLE server applications [MFC], implementing OLE servers", "servers, server documents", "server documents [MFC], implementing"] -ms.assetid: cca1451a-ad09-47ed-b56e-bccd78fc86d1 --- # Servers: Implementing Server Documents +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the steps you must take to successfully implement a server document if you did not specify the OLE Server option in the application wizard. #### To define a server document class diff --git a/docs/mfc/servers-server-items.md b/docs/mfc/servers-server-items.md index 86bcb8eb760..8ede0e366d0 100644 --- a/docs/mfc/servers-server-items.md +++ b/docs/mfc/servers-server-items.md @@ -3,10 +3,12 @@ description: "Learn more about: Servers: Server Items" title: "Servers: Server Items" ms.date: "11/04/2016" helpviewer_keywords: ["server items, implementing", "servers [MFC], server items", "architecture [MFC], server-item", "server items", "OLE server applications [MFC], server items"] -ms.assetid: 28ba81a1-726a-4728-a52d-68bc7efd5a3c --- # Servers: Server Items +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When a container launches a server so that a user can edit an embedded or linked OLE item, the server application creates a "server item." The server item, which is an object of a class derived from `COleServerItem`, provides an interface between the server document and the container application. The `COleServerItem` class defines several overridable member functions that are called by OLE, usually in response to requests from the container. Server items can represent part of the server document or the entire document. When an OLE item is embedded in the container document, the server item represents the entire server document. When the OLE item is linked, the server item can represent a part of the server document or the whole document, depending on whether the link is to a part or to the whole. diff --git a/docs/mfc/servers-user-interface-issues.md b/docs/mfc/servers-user-interface-issues.md index d0dd6bf54da..5c53ea2e53b 100644 --- a/docs/mfc/servers-user-interface-issues.md +++ b/docs/mfc/servers-user-interface-issues.md @@ -3,10 +3,12 @@ description: "Learn more about: Servers: User-Interface Issues" title: "Servers: User-Interface Issues" ms.date: "11/04/2016" helpviewer_keywords: ["OLE server applications [MFC], user interface", "servers, user-interface issues", "user interface issues"] -ms.assetid: 7ef55702-b439-43fa-8ced-c69b96239a89 --- # Servers: User-Interface Issues +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A server application has a number of features that must be added to the user interface to supply OLE items to container applications. For further information on the menus and additional resources that need to be added to a server application, see [Menus and Resources: Server Additions](../mfc/menus-and-resources-server-additions.md). ## See also diff --git a/docs/mfc/servers.md b/docs/mfc/servers.md index 79e33d42863..f4ad231f490 100644 --- a/docs/mfc/servers.md +++ b/docs/mfc/servers.md @@ -3,10 +3,12 @@ description: "Learn more about: Servers" title: "Servers" ms.date: "11/04/2016" helpviewer_keywords: ["OLE server applications [MFC]", "OLE server applications [MFC], activation", "full-server", "servers", "mini-server", "OLE server applications [MFC], server types", "server applications [MFC]"] -ms.assetid: e45172e8-eae3-400a-8139-0fa009a42fdc --- # Servers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A server application (or component application) creates OLE items (or components) for use by container applications. A visual editing server application also supports visual editing or in-place activation. Another form of OLE server is an [automation server](../mfc/automation-servers.md). Some server applications support only the creation of embedded items; others support the creation of both embedded and linked items. Some support linking only, although this is rare. All server applications must support activation by container applications when the user wants to edit an item. An application can be both a container and a server. In other words, it can both incorporate data into its documents, and create data that can be incorporated as items into other applications' documents. A miniserver is a special type of server application that can only be launched by a container. Microsoft Draw and Microsoft Graph are examples of miniservers. A miniserver does not store documents as files on disk. Instead, it reads its documents from and writes them to items in documents belonging to containers. As a result, a miniserver supports embedding only, not linking. diff --git a/docs/mfc/setting-a-hot-key.md b/docs/mfc/setting-a-hot-key.md index 75e08246041..902a72d9a00 100644 --- a/docs/mfc/setting-a-hot-key.md +++ b/docs/mfc/setting-a-hot-key.md @@ -3,10 +3,13 @@ description: "Learn more about: Setting a Hot Key" title: "Setting a Hot Key" ms.date: "11/04/2016" helpviewer_keywords: ["keyboard shortcuts [MFC], hot keys", "access keys [MFC], hot keys", "CHotKeyCtrl class [MFC], setting hot key"] -ms.assetid: 6f3bc141-e346-4dce-9ca7-3e6b2c453f3f +ms.topic: concept-article --- # Setting a Hot Key +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Your application can use the information provided by a hot key ([CHotKeyCtrl](../mfc/reference/chotkeyctrl-class.md)) control in one of two ways: - Set up a global hot key for activating a nonchild window by sending a [WM_SETHOTKEY](/windows/win32/inputdev/wm-sethotkey) message to the window to be activated. diff --git a/docs/mfc/setting-the-day-state-of-a-month-calendar-control.md b/docs/mfc/setting-the-day-state-of-a-month-calendar-control.md index 1ab946d3d7d..8e99333c363 100644 --- a/docs/mfc/setting-the-day-state-of-a-month-calendar-control.md +++ b/docs/mfc/setting-the-day-state-of-a-month-calendar-control.md @@ -4,10 +4,13 @@ title: "Setting the Day State of a Month Calendar Control" ms.date: "11/04/2016" f1_keywords: ["MCN_GETDAYSTATE"] helpviewer_keywords: ["CMonthCalCtrl class [MFC], setting day state info", "MCN_GETDAYSTATE notification [MFC]", "month calendar controls [MFC], day state info"] -ms.assetid: 435d1b11-ec0e-4121-9e25-aaa6af812a3c +ms.topic: how-to --- # Setting the Day State of a Month Calendar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + One of the attributes of a month calendar control is the ability to store information, referred to as the day state of the control, for each day of the month. This information is used to emphasize certain dates for the month currently displayed. > [!NOTE] diff --git a/docs/mfc/setting-the-dialog-boxs-background-color.md b/docs/mfc/setting-the-dialog-boxs-background-color.md index 76b102465c5..5adc2f37f3c 100644 --- a/docs/mfc/setting-the-dialog-boxs-background-color.md +++ b/docs/mfc/setting-the-dialog-boxs-background-color.md @@ -1,17 +1,37 @@ --- -description: "Learn more about: Setting the Dialog Box’s Background Color" -title: "Setting the Dialog Box’s Background Color" -ms.date: "07/12/2018" +description: "Learn more about: Setting the Dialog Box's Background Color" +title: "Setting the Dialog Box's Background Color" +ms.date: 11/17/2023 helpviewer_keywords: ["CSS, background attributes in styles [MFC]", "HTML element formatting, background attributes", "colors, dialog box", "dialog boxes [MFC], colors", "background colors, dialog boxes", "MFC dialog boxes [MFC], colors"] -ms.assetid: 05ee28a4-f3ae-4203-84ac-022f266ff2ab +ms.topic: concept-article --- -# Setting the Dialog Box’s Background Color +# Setting the Dialog Box's Background Color -You can set the background color of your dialog boxes by handling WM_CTLCOLOR messages for the dialog box window. The color you set is used for only the specified dialog box. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. -See [codexpert blog](https://codexpert.ro/blog/2013/03/13/painting-the-dialog-backround/) for an example. +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. + +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/setting-the-images-for-an-individual-item.md b/docs/mfc/setting-the-images-for-an-individual-item.md index 88a9906b6d2..e871b56a334 100644 --- a/docs/mfc/setting-the-images-for-an-individual-item.md +++ b/docs/mfc/setting-the-images-for-an-individual-item.md @@ -3,10 +3,13 @@ description: "Learn more about: Setting the Images for an Individual Item" title: "Setting the Images for an Individual Item" ms.date: "11/04/2016" helpviewer_keywords: ["extended combo boxes [MFC], images", "images [MFC], combo box items"] -ms.assetid: bde83db8-23a7-4e35-837a-c86447d2c0af +ms.topic: how-to --- # Setting the Images for an Individual Item +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The different types of images used by the extended combo box item are determined by the values in the *iImage*, *iSelectedImage*, and *iOverlay* members of the [COMBOBOXEXITEM](/windows/win32/api/commctrl/ns-commctrl-comboboxexitemw) structure. Each value is the index of an image in the associated image list of the control. By default, these members are set to 0, causing the control to display no image for the item. If you want to use images for a specific item, you can modify the structure accordingly, either when inserting the combo box item or by modifying an existing combo box item. ## Setting the Image for a New Item diff --git a/docs/mfc/setting-the-mode-of-a-cstatusbarctrl-object.md b/docs/mfc/setting-the-mode-of-a-cstatusbarctrl-object.md index bdfd84d65d0..cbf9cb32b0f 100644 --- a/docs/mfc/setting-the-mode-of-a-cstatusbarctrl-object.md +++ b/docs/mfc/setting-the-mode-of-a-cstatusbarctrl-object.md @@ -3,10 +3,13 @@ description: "Learn more about: Setting the Mode of a CStatusBarCtrl Object" title: "Setting the Mode of a CStatusBarCtrl Object" ms.date: "11/04/2016" helpviewer_keywords: ["simple mode and status bar controls", "IsSimple method, using", "SetSimple method [MFC]", "status bar controls [MFC], simple and nonsimple modes", "non-simple mode and status bar controls", "CStatusBarCtrl class [MFC], simple and nonsimple modes"] -ms.assetid: ca6076e5-1501-4e33-8d35-9308941e46c0 +ms.topic: concept-article --- # Setting the Mode of a CStatusBarCtrl Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are two modes for a `CStatusBarCtrl` object: simple and nonsimple. In the majority of cases, your status bar control will have one or more parts, along with text and perhaps an icon or icons. This is called the nonsimple mode. For more information on this mode, see [Initializing the Parts of a CStatusBarCtrl Object](../mfc/initializing-the-parts-of-a-cstatusbarctrl-object.md). However, there are cases where you only need to display a single line of text. In this case, the simple mode is sufficient for your needs. To change the mode of the `CStatusBarCtrl` object to simple, make a call to the [SetSimple](../mfc/reference/cstatusbarctrl-class.md#setsimple) member function. Once the status bar control is in simple mode, set the text by calling the `SetText` member function, passing 255 as the value for the *nPane* parameter. diff --git a/docs/mfc/settings-for-the-cstatusbarctrl.md b/docs/mfc/settings-for-the-cstatusbarctrl.md index a8ec8d51a93..332b48a0464 100644 --- a/docs/mfc/settings-for-the-cstatusbarctrl.md +++ b/docs/mfc/settings-for-the-cstatusbarctrl.md @@ -3,10 +3,12 @@ description: "Learn more about: Settings for the CStatusBarCtrl" title: "Settings for the CStatusBarCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["status bar controls [MFC], settings", "CStatusBarCtrl class [MFC], settings"] -ms.assetid: adeba0c3-17f3-435c-b140-a57845e9ce49 --- # Settings for the CStatusBarCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The default position of a [CStatusBarCtrl](../mfc/reference/cstatusbarctrl-class.md) status window is along the bottom of the parent window, but you can specify the CCS_TOP style to have it appear at the top of the parent window's client area. You can specify the SBARS_SIZEGRIP style to include a sizing grip at the right end of the `CStatusBarCtrl` status window. A sizing grip is similar to a sizing border; it is a rectangular area that the user can click and drag to resize the parent window. diff --git a/docs/mfc/settings-for-the-progress-control.md b/docs/mfc/settings-for-the-progress-control.md index 982abdb535b..778150af132 100644 --- a/docs/mfc/settings-for-the-progress-control.md +++ b/docs/mfc/settings-for-the-progress-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Settings for the Progress Control" title: "Settings for the Progress Control" ms.date: "11/04/2016" helpviewer_keywords: ["CProgressCtrl class [MFC], settings", "progress controls [MFC], settings"] -ms.assetid: f4616e91-74fa-4000-ba0d-d3ddc0ee075b --- # Settings for the Progress Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The basic settings for the progress control ([CProgressCtrl](../mfc/reference/cprogressctrl-class.md)) are the range and current position. The range represents the entire duration of the operation. The current position represents the progress that your application has made toward completing the operation. Any changes to the range or position cause the progress control to redraw itself. By default, the range is set to 0 - 100, and the initial position is set to 0. To retrieve the current range settings for the progress control, use the [GetRange](../mfc/reference/cprogressctrl-class.md#getrange) member function. To change the range, use the [SetRange](../mfc/reference/cprogressctrl-class.md#setrange) member function. diff --git a/docs/mfc/settings-for-the-tool-tip-control.md b/docs/mfc/settings-for-the-tool-tip-control.md index 05c07197ab0..adde2501854 100644 --- a/docs/mfc/settings-for-the-tool-tip-control.md +++ b/docs/mfc/settings-for-the-tool-tip-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Settings for the Tool Tip Control" title: "Settings for the Tool Tip Control" ms.date: "11/04/2016" helpviewer_keywords: ["tool tips [MFC], activating", "CToolTipCtrl class [MFC], settings"] -ms.assetid: ff8c5c46-2047-403a-bd98-ffec3d21ee3a --- # Settings for the Tool Tip Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can set the tool tip control ([CToolTipCtrl](../mfc/reference/ctooltipctrl-class.md)) to be either active or inactive. When you set it to be active, the tool tip control appears when the cursor is on a tool. When you set it to be inactive, the tool tip control does not appear, even if the cursor is on a tool. Call [Activate](../mfc/reference/ctooltipctrl-class.md#activate) to activate or deactivate a tool tip control. You can set an active tool tip to display the tool tip when the cursor is on a tool, whether or not the tool tip control's owner window is active or inactive, by using the TTS_ALWAYSTIP style. If you do not use this style, the tool tip control appears when the tool's owner window is active, but not when it is inactive. diff --git a/docs/mfc/settings-for-the-toolbar-control.md b/docs/mfc/settings-for-the-toolbar-control.md index 5649440229c..91e4a115f28 100644 --- a/docs/mfc/settings-for-the-toolbar-control.md +++ b/docs/mfc/settings-for-the-toolbar-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Settings for the Toolbar Control" title: "Settings for the Toolbar Control" ms.date: "11/04/2016" helpviewer_keywords: ["toolbar controls [MFC], about toolbar controls", "CToolBarCtrl class [MFC], settings"] -ms.assetid: 025ba920-b3ee-4d82-9367-e652cd7875b9 --- # Settings for the Toolbar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The buttons on a toolbar can display a bitmap, a string, or both. By default, the image size is set to the dimensions of 16 by 15 pixels. All buttons are the same width, by default 24 by 22 pixels. A toolbar's height is determined by the height of the buttons, and a toolbar's width is the same as the width of the parent window's client area, also by default. A toolbar can have built-in customization features, including a system-defined customization dialog box, that allow the user to insert, delete, or rearrange toolbar buttons. An application determines whether the customization features are available to the user and controls the extent to which the user can customize the toolbar. For more information about customizing the toolbar, see class [CToolBarCtrl](../mfc/reference/ctoolbarctrl-class.md) in the *MFC Reference*. diff --git a/docs/mfc/simple-data-type-classes.md b/docs/mfc/simple-data-type-classes.md index 4e332b84f9c..d5dbfc4d22f 100644 --- a/docs/mfc/simple-data-type-classes.md +++ b/docs/mfc/simple-data-type-classes.md @@ -4,10 +4,12 @@ title: "Simple Data Type Classes" ms.date: "11/04/2016" f1_keywords: ["vc.classes.data"] helpviewer_keywords: ["scalar classes [MFC]", "data classes [MFC]", "simple data type classes [MFC]"] -ms.assetid: 0d591d68-0a33-49e9-8a6d-90c90de5c16a --- # Simple Data Type Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following classes encapsulate drawing coordinates, character strings, and time and date information, allowing convenient use of C++ syntax. These objects are used widely as parameters to the member functions of Windows classes in the class library. Because `CPoint`, `CSize`, and `CRect` correspond to the **POINT**, **SIZE**, and **RECT** structures, respectively, in the Windows SDK, you can use objects of these C++ classes wherever you can use these C-language structures. The classes provide useful interfaces through their member functions. `CStringT` provides very flexible dynamic character strings. `CTime`, `COleDateTime`, `CTimeSpan`, and `COleTimeSpan` represent time and date values. For more information about these classes, see the article [Date and Time](../atl-mfc-shared/date-and-time.md). The classes that begin with "`COle`" are encapsulations of data types provided by OLE. These data types can be used in Windows programs regardless of whether other OLE features are used. diff --git a/docs/mfc/slider-control-member-functions.md b/docs/mfc/slider-control-member-functions.md index 10e1c674727..3bd37f94b77 100644 --- a/docs/mfc/slider-control-member-functions.md +++ b/docs/mfc/slider-control-member-functions.md @@ -3,13 +3,15 @@ description: "Learn more about: Slider Control Member Functions" title: "Slider Control Member Functions" ms.date: "11/04/2016" helpviewer_keywords: ["CSliderCtrl class [MFC], methods", "slider controls [MFC], member functions"] -ms.assetid: dbde49ee-7306-4d14-a6ce-d09aa198178f --- # Slider Control Member Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An application can call the slider control's member functions to retrieve information about the slider control ([CSliderCtrl](../mfc/reference/csliderctrl-class.md)) and to change its characteristics. -To retrieve the position of the slider (that is, the value the user has chosen), use the [GetPos](../mfc/reference/csliderctrl-class.md#getpos) member function. To set the position of the slider, use the [SetPos](../mfc/reference/csliderctrl-class.md#setpos) member function. At any time you can use the `VerifyPos` member function to make sure that the slider is between the minimum and maximum values. +To retrieve the position of the slider (that is, the value the user has chosen), use the [GetPos](../mfc/reference/csliderctrl-class.md#getpos) member function. To set the position of the slider, use the [SetPos](../mfc/reference/csliderctrl-class.md#setpos) member function. The range of a slider control is the set of contiguous values that the slider control can represent. Most applications use the [SetRange](../mfc/reference/csliderctrl-class.md#setrange) member function to set the range of a slider control when it is first created. Applications can dynamically alter the range after the slider control has been created by using the [SetRangeMax](../mfc/reference/csliderctrl-class.md#setrangemax) and [SetRangeMin](../mfc/reference/csliderctrl-class.md#setrangemin) member functions. An application that allows the range to be changed dynamically typically retrieves the final range settings when the user has finished working with the slider control. To retrieve these settings, use the [GetRange](../mfc/reference/csliderctrl-class.md#getrange), [GetRangeMax](../mfc/reference/csliderctrl-class.md#getrangemax), and [GetRangeMin](../mfc/reference/csliderctrl-class.md#getrangemin) member functions. diff --git a/docs/mfc/slider-control-styles.md b/docs/mfc/slider-control-styles.md index b84fb69f468..b779c005ee2 100644 --- a/docs/mfc/slider-control-styles.md +++ b/docs/mfc/slider-control-styles.md @@ -3,10 +3,12 @@ description: "Learn more about: Slider Control Styles" title: "Slider Control Styles" ms.date: "11/04/2016" helpviewer_keywords: ["slider controls [MFC], styles", "CSliderCtrl class [MFC], styles", "styles [MFC], CSliderCtrl", "styles [MFC], slider controls"] -ms.assetid: 64c491fc-5af1-4f97-ae30-854071b3dc02 --- # Slider Control Styles +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Slider controls ([CSliderCtrl](../mfc/reference/csliderctrl-class.md)) can have either a vertical or horizontal orientation. They can have tick marks on either side, both sides, or neither. They can also be used to specify a range of consecutive values. These properties are controlled by using slider control styles, which you specify when you create the slider control. The TBS_HORZ and TBS_VERT styles determine the orientation of the slider control. If you do not specify an orientation, the slider control is oriented horizontally. diff --git a/docs/mfc/slider-notification-messages.md b/docs/mfc/slider-notification-messages.md index 3e750d22cde..da9382e3626 100644 --- a/docs/mfc/slider-notification-messages.md +++ b/docs/mfc/slider-notification-messages.md @@ -3,10 +3,12 @@ description: "Learn more about: Slider Notification Messages" title: "Slider Notification Messages" ms.date: "11/04/2016" helpviewer_keywords: ["CSliderCtrl class [MFC], notifications", "slider controls [MFC], notification messages", "messages, notification", "notifications [MFC], CSliderCtrl"] -ms.assetid: b9121104-3889-4a10-92bf-f3723f1af9d0 --- # Slider Notification Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A slider control notifies its parent window of user actions by sending the parent WM_HSCROLL or WM_VSCROLL messages, depending on the orientation of the slider control. To handle these messages, add handlers for the WM_HSCROLL and WM_VSCROLL messages to the parent window. The [OnHScroll](../mfc/reference/cwnd-class.md#onhscroll) and [OnVScroll](../mfc/reference/cwnd-class.md#onvscroll) member functions will be passed a notification code, the position of the slider, and a pointer to the [CSliderCtrl](../mfc/reference/csliderctrl-class.md) object. Note that the pointer is of type `CScrollBar *` even though it points to a `CSliderCtrl` object. You may need to typecast this pointer if you need to manipulate the slider control. Rather than using the scroll bar notification codes, slider controls send a different set of notification codes. A slider control sends the TB_BOTTOM, TB_LINEDOWN, TB_LINEUP, and TB_TOP notification codes only when the user interacts with a slider control by using the keyboard. The TB_THUMBPOSITION and TB_THUMBTRACK notification messages are only sent when the user is using the mouse. The TB_ENDTRACK, TB_PAGEDOWN, and TB_PAGEUP notification codes are sent in both cases. diff --git a/docs/mfc/special-cwinapp-services.md b/docs/mfc/special-cwinapp-services.md index ee7285fee54..e0f956d3860 100644 --- a/docs/mfc/special-cwinapp-services.md +++ b/docs/mfc/special-cwinapp-services.md @@ -4,10 +4,12 @@ title: "Special CWinApp Services" ms.date: "11/04/2016" f1_keywords: ["LoadStdProfileSettings", "EnableShellOpen"] helpviewer_keywords: ["files [MFC], most recently used", "DragAcceptFiles method [MFC]", "MRU lists", "GDI+, initializing for MFC", "GDI+, suppressing background thread [MFC]", "CWinApp class [MFC], shell registration", "application objects [MFC], services", "CWinApp class [MFC], initializing GDI+", "MFC, shell registration", "CWinApp class [MFC], File Manager drag and drop", "LoadStdProfileSettings method [MFC]", "MFC, most-recently-used file list", "RegisterShellFileTypes method [MFC]", "drag and drop [MFC], files", "registering file types", "Shell, registering file types", "services, provided by CWinApp", "CWinApp class [MFC], recently used documents", "CWinApp class [MFC], services", "files [MFC], drag and drop", "EnableShellOpen method [MFC]", "registry [MFC], most recently used files", "MFC, file operations", "registration [MFC], shell"] -ms.assetid: 0480cd01-f629-4249-b221-93432d95b431 --- # Special CWinApp Services +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Besides running the message loop and giving you an opportunity to initialize the application and clean up after it, [CWinApp](../mfc/reference/cwinapp-class.md) provides several other services. ## Shell Registration diff --git a/docs/mfc/specifying-levels-of-functionality.md b/docs/mfc/specifying-levels-of-functionality.md index 66ae19f7f99..5c5b2617a16 100644 --- a/docs/mfc/specifying-levels-of-functionality.md +++ b/docs/mfc/specifying-levels-of-functionality.md @@ -3,10 +3,13 @@ description: "Learn more about: Specifying Levels of Functionality" title: "Specifying Levels of Functionality" ms.date: "11/06/2018" helpviewer_keywords: ["CObject class [MFC], adding functionality to derived classes", "runtime [MFC], class information", "serialization [MFC], Cobject", "dynamic creation support", "levels [MFC], functionality in CObject", "run-time class [MFC], information support", "levels [MFC]"] -ms.assetid: 562669ba-c858-4f66-b5f1-b3beeea4f486 +ms.topic: how-to --- # Specifying Levels of Functionality +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes how to add the following levels of functionality to your [CObject](../mfc/reference/cobject-class.md)-derived class: - Run-time class information diff --git a/docs/mfc/spin-button-member-functions.md b/docs/mfc/spin-button-member-functions.md index 9c2b9529356..5346069e91c 100644 --- a/docs/mfc/spin-button-member-functions.md +++ b/docs/mfc/spin-button-member-functions.md @@ -3,10 +3,12 @@ description: "Learn more about: Spin Button Member Functions" title: "Spin Button Member Functions" ms.date: "11/04/2016" helpviewer_keywords: ["spin button control, methods", "CSpinButtonCtrl class [MFC], methods"] -ms.assetid: a08a26fd-b803-4cbe-a509-395fa357d057 --- # Spin Button Member Functions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are several member functions available for the spin control ([CSpinButtonCtrl](../mfc/reference/cspinbuttonctrl-class.md)). Use these functions to change the following attributes of the spin button. - **Acceleration** You can adjust the rate at which the position changes when the user holds down the arrow button. To work with acceleration, use the [SetAccel](../mfc/reference/cspinbuttonctrl-class.md#setaccel) and [GetAccel](../mfc/reference/cspinbuttonctrl-class.md#getaccel) member functions. diff --git a/docs/mfc/spin-button-styles.md b/docs/mfc/spin-button-styles.md index aaa73fe9d2f..4abc91b2123 100644 --- a/docs/mfc/spin-button-styles.md +++ b/docs/mfc/spin-button-styles.md @@ -3,10 +3,12 @@ description: "Learn more about: Spin Button Styles" title: "Spin Button Styles" ms.date: "09/09/2019" helpviewer_keywords: ["styles [MFC], CSpinButtonCtrl", "CSpinButtonCtrl class [MFC], styles", "styles [MFC], spin button control", "spin button control, styles"] -ms.assetid: fb4a7f6f-9182-47be-bccf-0728fdc5332f --- # Spin Button Styles +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Many of the settings for a spin button ([CSpinButtonCtrl](../mfc/reference/cspinbuttonctrl-class.md)) are controlled by styles. You can set the following styles using the [Class Wizard](reference/mfc-class-wizard.md). - **Orientation** Either Vertical or Horizontal. Controls the orientation of the arrow buttons. Associated with the UDS_HORZ style. diff --git a/docs/mfc/standard-commands.md b/docs/mfc/standard-commands.md index 116be5bb811..6c1c07c796f 100644 --- a/docs/mfc/standard-commands.md +++ b/docs/mfc/standard-commands.md @@ -3,10 +3,12 @@ description: "Learn more about: Standard Commands" title: "Standard Commands" ms.date: "11/04/2016" helpviewer_keywords: ["File menu", "identifiers [MFC], command IDs", "command IDs, standard commands", "OLE commands", "commands [MFC], standard", "standard command IDs", "Window menu commands", "standard commands", "View menu commands", "Edit menu standard commands", "Help [MFC], menus", "programmer-defined IDs [MFC]"] -ms.assetid: 88cf3ab4-79b3-4ac6-9365-8ac561036fbf --- # Standard commands +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The framework defines many standard command messages. The IDs for these commands typically take the form **`ID__`**, where `` is usually a menu name and `` is a menu item. For example, the command ID for the **New** command on the **File** menu is `ID_FILE_NEW`. Standard command IDs are shown in bold type in the documentation. Programmer-defined IDs are shown in a font that's different from the surrounding text. The following list shows some of the most important commands supported: diff --git a/docs/mfc/status-bar-implementation-in-mfc.md b/docs/mfc/status-bar-implementation-in-mfc.md index 6ddeb263c87..343121838b1 100644 --- a/docs/mfc/status-bar-implementation-in-mfc.md +++ b/docs/mfc/status-bar-implementation-in-mfc.md @@ -4,10 +4,12 @@ title: "Status Bar Implementation in MFC" ms.date: "11/19/2018" f1_keywords: ["COldStatusBar"] helpviewer_keywords: ["status bars [MFC], implementing in MFC", "CStatusBarCtrl class [MFC], and MFC status bars", "CStatusBar class [MFC], and CStatusBarCtrl class [MFC]", "CStatusBarCtrl class [MFC], and CStatusBar class [MFC]", "status bars [MFC], backward compatibility", "status bars [MFC], old with COldStatusBar class [MFC]", "COldStatusBar class [MFC]", "status bars [MFC], and CStatusBarCtrl class", "CStatusBar class [MFC], and MFC status bars", "status indicators", "status bars [MFC], Windows 95 implementation"] -ms.assetid: be5cd876-38e3-4d5c-b8cb-16d57a16a142 --- # Status Bar Implementation in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A [CStatusBar](../mfc/reference/cstatusbar-class.md) object is a control bar with a row of text output panes. The output panes are commonly used as message lines and as status indicators. Examples include the menu help-message lines that briefly explain the selected menu command and the indicators that show the status of the SCROLL LOCK, NUM LOCK, and other keys. As of MFC version 4.0, status bars are implemented using class [CStatusBarCtrl](../mfc/reference/cstatusbarctrl-class.md), which encapsulates a status bar common control. For backward compatibility, MFC retains the older status bar implementation in class `COldStatusBar`. The documentation for earlier versions of MFC describes `COldStatusBar` under `CStatusBar`. diff --git a/docs/mfc/status-bars.md b/docs/mfc/status-bars.md index d780d9410ee..29ff0152e63 100644 --- a/docs/mfc/status-bars.md +++ b/docs/mfc/status-bars.md @@ -3,10 +3,12 @@ description: "Learn more about: Status Bars" title: "Status Bars" ms.date: "11/04/2016" helpviewer_keywords: ["status bars", "control bars [MFC], status bar"] -ms.assetid: fcbc5029-1aab-4e14-adf7-419038a4935e --- # Status Bars +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Status bars give your application a place to display messages and useful information to the user without interrupting the user's work. Typically displayed at the bottom of a window, status bars have "panes," which include "indicators" and a "message line." The indicators give the status of such things as SCROLL LOCK, whether macro recording is turned on, and so on. The message line on the status bar can display information about program status or about a toolbar button or menu item that the user is pointing to with the mouse. Create a status bar in your program by selecting the **Initial Status Bar** option in the MFC Application Wizard. diff --git a/docs/mfc/steps-in-a-typical-ftp-client-application-to-delete-a-file.md b/docs/mfc/steps-in-a-typical-ftp-client-application-to-delete-a-file.md index 258b8a4d22f..e6f3ca36d29 100644 --- a/docs/mfc/steps-in-a-typical-ftp-client-application-to-delete-a-file.md +++ b/docs/mfc/steps-in-a-typical-ftp-client-application-to-delete-a-file.md @@ -3,10 +3,13 @@ description: "Learn more about: Steps in a Typical FTP Client Application to Del title: "Steps in a Typical FTP Client Application to Delete a File" ms.date: "11/04/2016" helpviewer_keywords: ["Internet client applications [MFC], FTP delete", "WinInet classes [MFC], FTP", "FTP (File Transfer Protocol) [MFC], client applications", "Internet applications [MFC], FTP client applications"] -ms.assetid: 2c347a96-c0a4-4827-98fe-668406e552bc +ms.topic: how-to --- # Steps in a Typical FTP Client Application to Delete a File +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows the steps you might perform in a typical FTP client application that deletes a file. |Your goal|Actions you take|Effects| diff --git a/docs/mfc/steps-in-a-typical-ftp-client-application.md b/docs/mfc/steps-in-a-typical-ftp-client-application.md index d84e6990dc8..b1b865a3ea1 100644 --- a/docs/mfc/steps-in-a-typical-ftp-client-application.md +++ b/docs/mfc/steps-in-a-typical-ftp-client-application.md @@ -3,10 +3,13 @@ description: "Learn more about: Steps in a Typical FTP Client Application" title: "Steps in a Typical FTP Client Application" ms.date: "11/04/2016" helpviewer_keywords: ["Internet client applications [MFC], FTP table", "FTP (File Transfer Protocol)", "WinInet classes [MFC], FTP", "FTP (File Transfer Protocol) [MFC], client applications", "Internet applications [MFC], FTP client applications"] -ms.assetid: 70bed7b5-6040-40d1-bc77-702e63a698f2 +ms.topic: how-to --- # Steps in a Typical FTP Client Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A typical FTP client application creates a [CInternetSession](../mfc/reference/cinternetsession-class.md) and a [CFtpConnection](../mfc/reference/cftpconnection-class.md) object. Note that these MFC WinInet classes do not actually control the proxy type settings; IIS does. The following table shows the steps you might perform in a typical FTP client application. diff --git a/docs/mfc/steps-in-a-typical-gopher-client-application.md b/docs/mfc/steps-in-a-typical-gopher-client-application.md index 6b00efb5591..8e6d6c44703 100644 --- a/docs/mfc/steps-in-a-typical-gopher-client-application.md +++ b/docs/mfc/steps-in-a-typical-gopher-client-application.md @@ -3,10 +3,13 @@ description: "Learn more about: Steps in a Typical Gopher Client Application" title: "Steps in a Typical Gopher Client Application" ms.date: "11/04/2016" helpviewer_keywords: ["WinInet classes [MFC], gopher", "Internet applications [MFC], gopher client applications", "Gopher client applications [MFC]", "Internet client applications [MFC], gopher table"] -ms.assetid: 3e4e1869-5da0-453d-8ba9-b648c894bb90 +ms.topic: how-to --- # Steps in a Typical Gopher Client Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows the steps you might perform in a typical gopher client application. |Your goal|Actions you take|Effects| diff --git a/docs/mfc/steps-in-a-typical-http-client-application.md b/docs/mfc/steps-in-a-typical-http-client-application.md index 96b6b19fee6..59dd59a7cb3 100644 --- a/docs/mfc/steps-in-a-typical-http-client-application.md +++ b/docs/mfc/steps-in-a-typical-http-client-application.md @@ -3,10 +3,13 @@ description: "Learn more about: Steps in a Typical HTTP Client Application" title: "Steps in a Typical HTTP Client Application" ms.date: "11/04/2016" helpviewer_keywords: ["HTTP client applications [MFC]", "client applications [MFC], HTTP", "Internet applications [MFC], HTTP client applications", "applications [MFC], HTTP client", "Internet client applications [MFC], HTTP table", "WinInet classes [MFC], HTTP"] -ms.assetid: f86552e8-8acd-4b23-bdc5-0c3a247ebd74 +ms.topic: how-to --- # Steps in a Typical HTTP Client Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows the steps you might perform in a typical HTTP client application: |Your goal|Actions you take|Effects| diff --git a/docs/mfc/steps-in-a-typical-internet-client-application.md b/docs/mfc/steps-in-a-typical-internet-client-application.md index 927d514d1e1..4f1851ddc27 100644 --- a/docs/mfc/steps-in-a-typical-internet-client-application.md +++ b/docs/mfc/steps-in-a-typical-internet-client-application.md @@ -3,10 +3,13 @@ description: "Learn more about: Steps in a Typical Internet Client Application" title: "Steps in a Typical Internet Client Application" ms.date: "11/04/2016" helpviewer_keywords: ["Internet client applications [MFC], general table", "WinInet classes [MFC], programming", "Internet applications [MFC], client applications"] -ms.assetid: 7aba135c-7c15-4e2f-8c34-bbaf792c89a6 +ms.topic: how-to --- # Steps in a Typical Internet Client Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The following table shows the steps you might perform in a typical Internet client application. |Your goal|Actions you take|Effects| diff --git a/docs/mfc/storing-and-loading-cobjects-via-an-archive.md b/docs/mfc/storing-and-loading-cobjects-via-an-archive.md index 174a0a762ee..145b8d1f840 100644 --- a/docs/mfc/storing-and-loading-cobjects-via-an-archive.md +++ b/docs/mfc/storing-and-loading-cobjects-via-an-archive.md @@ -3,10 +3,13 @@ description: "Learn more about: Storing and Loading CObjects via an Archive" title: "Storing and Loading CObjects via an Archive" ms.date: "11/04/2016" helpviewer_keywords: ["CObjects [MFC], loading through archives", "CArchive class [MFC], storing and loading objects", "Serialize method, vs. CArchive operators", "CObject class [MFC], CArchive objects", "CObjects [MFC]"] -ms.assetid: a829b6dd-bc31-47e0-8108-fbb946722db9 +ms.topic: concept-article --- # Storing and Loading CObjects via an Archive +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Storing and loading `CObject`s via an archive requires extra consideration. In certain cases, you should call the `Serialize` function of the object, where the `CArchive` object is a parameter of the `Serialize` call, as opposed to using the **<\<** or **>>** operator of the `CArchive`. The important fact to keep in mind is that the `CArchive` **>>** operator constructs the `CObject` in memory based on `CRuntimeClass` information previously written to the file by the storing archive. Therefore, whether you use the `CArchive` **<\<** and **>>** operators, versus calling `Serialize`, depends on whether you *need* the loading archive to dynamically reconstruct the object based on previously stored `CRuntimeClass` information. Use the `Serialize` function in the following cases: @@ -21,7 +24,7 @@ Therefore, whether you use the `CArchive` **<\<** and **>>** operators, versus c The following example illustrates the cases: [!code-cpp[NVC_MFCSerialization#36](../mfc/codesnippet/cpp/storing-and-loading-cobjects-via-an-archive_1.h)] - +  [!code-cpp[NVC_MFCSerialization#37](../mfc/codesnippet/cpp/storing-and-loading-cobjects-via-an-archive_2.cpp)] In summary, if your serializable class defines an embedded `CObject` as a member, you should *not* use the `CArchive` **<\<** and **>>** operators for that object, but should call the `Serialize` function instead. Also, if your serializable class defines a pointer to a `CObject` (or an object derived from `CObject`) as a member, but constructs this other object in its own constructor, you should also call `Serialize`. diff --git a/docs/mfc/stream-operations-in-rich-edit-controls.md b/docs/mfc/stream-operations-in-rich-edit-controls.md index 81ae2c76cec..04f1e5d277c 100644 --- a/docs/mfc/stream-operations-in-rich-edit-controls.md +++ b/docs/mfc/stream-operations-in-rich-edit-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Stream Operations in Rich Edit Controls" title: "Stream Operations in Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["CRichEditCtrl class [MFC], stream operations", "CRichEditCtrl class [MFC], stream storage", "rich edit controls [MFC], stream operations", "storage, stream in CRichEditCtrl", "stream operations in CRichEditCtrl", "stream storage and CRichEditCtrl"] -ms.assetid: 110b4684-1e76-4ca6-9ef0-5bc8b2d93c78 --- # Stream Operations in Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use streams to transfer data into or out of a rich edit control ([CRichEditCtrl](../mfc/reference/cricheditctrl-class.md)). A stream is defined by an [EDITSTREAM](/windows/win32/api/richedit/ns-richedit-editstream) structure, which specifies a buffer and an application-defined callback function. To read data into a rich edit control (that is, stream the data in), use the [StreamIn](../mfc/reference/cricheditctrl-class.md#streamin) member function. The control repeatedly calls the application-defined callback function, which transfers a portion of the data into the buffer each time. diff --git a/docs/mfc/styles-for-the-progress-control.md b/docs/mfc/styles-for-the-progress-control.md index 2fe586be746..9a43e2cb16d 100644 --- a/docs/mfc/styles-for-the-progress-control.md +++ b/docs/mfc/styles-for-the-progress-control.md @@ -3,10 +3,12 @@ description: "Learn more about: Styles for the Progress Control" title: "Styles for the Progress Control" ms.date: "11/19/2018" helpviewer_keywords: ["PBS_SMOOTH style", "progress controls [MFC], styles", "PBS_VERTICAL style", "CProgressCtrl class [MFC], styles"] -ms.assetid: 39eb8081-bc20-4552-91b9-e7cdd1b7d8ae --- # Styles for the Progress Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you initially create the progress control ([CProgressCtrl::Create](../mfc/reference/cprogressctrl-class.md#create)), use the *dwStyle* parameter to specify the desired window styles for your progress control. The following list details the applicable window styles. The control ignores any window style other than the ones listed here. You should always create the control as a child window, usually of a dialog box parent. |Window style|Effect| diff --git a/docs/mfc/support-for-activation-contexts-in-the-mfc-module-state.md b/docs/mfc/support-for-activation-contexts-in-the-mfc-module-state.md index 38bebdec767..b4a07738a52 100644 --- a/docs/mfc/support-for-activation-contexts-in-the-mfc-module-state.md +++ b/docs/mfc/support-for-activation-contexts-in-the-mfc-module-state.md @@ -3,10 +3,12 @@ description: "Learn more about: Support for Activation Contexts in the MFC Modul title: "Support for Activation Contexts in the MFC Module State" ms.date: "11/04/2016" helpviewer_keywords: ["activation contexts [MFC]", "activation contexts [MFC], MFC support"] -ms.assetid: 1e49eea9-3620-46dd-bc5f-d664749567c7 --- # Support for Activation Contexts in the MFC Module State +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC creates an activation context using a manifest resource provided by the user module. For more information on how activation contexts are created, see the following topics: - [Activation Contexts](/windows/win32/SbsCs/activation-contexts) diff --git a/docs/mfc/tab-controls-and-property-sheets.md b/docs/mfc/tab-controls-and-property-sheets.md index 594015025ce..adcb8c11d50 100644 --- a/docs/mfc/tab-controls-and-property-sheets.md +++ b/docs/mfc/tab-controls-and-property-sheets.md @@ -3,10 +3,12 @@ description: "Learn more about: Tab Controls and Property Sheets" title: "Tab Controls and Property Sheets" ms.date: "11/04/2016" helpviewer_keywords: ["property sheets, tab controls", "tab controls [MFC], and property sheets", "CTabCtrl class [MFC], and property sheets"] -ms.assetid: f3b87bea-9ad9-41e6-a7ff-a9285308267e --- # Tab Controls and Property Sheets +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Property sheets are multiple-page dialogs or "tab dialogs" that can display up to 24 dialog template resources to the user. For examples of property sheets, see the Windows Display Properties dialog box or the following MFC sample application: [CMNCTRL1: Demonstrates Common Control Classes, Part 1](../overview/visual-cpp-samples.md) diff --git a/docs/mfc/tabs-and-tab-control-attributes.md b/docs/mfc/tabs-and-tab-control-attributes.md index 61dcc0d87b4..02ea18ccdc2 100644 --- a/docs/mfc/tabs-and-tab-control-attributes.md +++ b/docs/mfc/tabs-and-tab-control-attributes.md @@ -3,10 +3,12 @@ description: "Learn more about: Tabs and Tab Control Attributes" title: "Tabs and Tab Control Attributes" ms.date: "11/04/2016" helpviewer_keywords: ["attributes [MFC], reference topics", "tab controls [MFC], attributes", "tabs [MFC]", "tabs [MFC], attributes", "CTabCtrl class [MFC], tab control attributes"] -ms.assetid: ecf190cb-f323-4751-bfdb-766dbe6bb553 --- # Tabs and Tab Control Attributes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You have considerable control over the appearance and behavior of tabs that make up a tab control ([CTabCtrl](../mfc/reference/ctabctrl-class.md)). Each tab can have a label, an icon, an item state, and an application-defined 32-bit value associated with it. For each tab, you can display the icon, the label, or both. In addition, each tab item can have three possible states: pressed, unpressed, or highlighted. This state can only be set by modifying an existing tab item. To modify an existing tab item, retrieve it with a call to [GetItem](../mfc/reference/ctabctrl-class.md#getitem), modify the `TCITEM` structure (specifically the *dwState* and *dwStateMask* data members), and then return the modified `TCITEM` structure with a call to [SetItem](../mfc/reference/ctabctrl-class.md#setitem). If you need to clear the item states of all the tab items in a `CTabCtrl` object, make a call to [DeselectAll](../mfc/reference/ctabctrl-class.md#deselectall). This function resets the state of all tab items or all items except the one currently selected. diff --git a/docs/mfc/technical-notes-by-category.md b/docs/mfc/technical-notes-by-category.md index 288094ac3af..7128376cfaa 100644 --- a/docs/mfc/technical-notes-by-category.md +++ b/docs/mfc/technical-notes-by-category.md @@ -2,10 +2,12 @@ description: "Learn more about: Technical Notes by Category" title: "Technical Notes by Category" ms.date: "11/04/2016" -ms.assetid: b9f1c953-233d-4d64-9e8e-ca69b79460b8 --- # Technical Notes by Category +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Technical notes are divided into the following categories. For a numerical listing of the technical notes, see [Technical Notes by Number](../mfc/technical-notes-by-number.md). ### MFC and Windows diff --git a/docs/mfc/technical-notes-by-number.md b/docs/mfc/technical-notes-by-number.md index d07d4b3b3bd..ce0f9032bba 100644 --- a/docs/mfc/technical-notes-by-number.md +++ b/docs/mfc/technical-notes-by-number.md @@ -3,10 +3,12 @@ description: "Learn more about: Technical Notes by Number" title: "Technical Notes by Number" ms.date: "11/04/2016" f1_keywords: ["vc.tables.mfc.technotes"] -ms.assetid: aaa449be-9167-4510-a490-af872c4f60a2 --- # Technical Notes by Number +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The technical notes below are listed numerically, with the most recently written technical note first. For a listing by category, see [Technical Notes by Category](../mfc/technical-notes-by-category.md). |Number|Title| diff --git a/docs/mfc/template-based-classes.md b/docs/mfc/template-based-classes.md index b60a54b82a6..c15c730b488 100644 --- a/docs/mfc/template-based-classes.md +++ b/docs/mfc/template-based-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Template-Based Classes" title: "Template-Based Classes" ms.date: "11/04/2016" helpviewer_keywords: ["type-safe collections", "CTypedPtrList class [MFC], template-based classes", "arrays [MFC], classes", "arrays [MFC], pointers", "typed pointers, collections of", "arrays [MFC], template-based", "CArray class [MFC], template-based classes", "simple template-based collections", "simple array collection classes [MFC]", "typed pointers", "collections, typed-pointer", "CList class [MFC], template-based classes", "collection classes [MFC], template-based", "CTypedPtrMap class [MFC], template-based classes", "pointers, collections of typed", "CTypedPtrArray class [MFC], template-based classes", "MFC collection classes [MFC], template-based", "template-based collection classes [MFC]", "simple list collection classes [MFC]"] -ms.assetid: c69fc95b-c8f6-4a99-abed-517c9898ef0c --- # Template-Based Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the type-safe template-based collection classes in MFC version 3.0 and later. Using these templates to create type-safe collections is more convenient and helps provide type safety more effectively than using the collection classes not based on templates. MFC predefines two categories of template-based collections: diff --git a/docs/mfc/template-classes-for-arrays-lists-and-maps.md b/docs/mfc/template-classes-for-arrays-lists-and-maps.md index adf320b1c3e..f76f823414c 100644 --- a/docs/mfc/template-classes-for-arrays-lists-and-maps.md +++ b/docs/mfc/template-classes-for-arrays-lists-and-maps.md @@ -4,10 +4,12 @@ title: "Template Classes for Arrays, Lists, and Maps" ms.date: "11/04/2016" f1_keywords: ["vc.classes.template"] helpviewer_keywords: ["arrays [MFC], classes", "template classes [MFC], for arrays/lists and maps", "list classes [MFC]", "map classes [MFC]", "template classes [MFC]"] -ms.assetid: a8331c4b-068a-48f8-a629-b8449601e121 --- # Template Classes for Arrays, Lists, and Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + These collection classes are templates whose parameters determine the types of the objects stored in the aggregates. The `CArray`, `CMap`, and `CList` classes use global helper functions that must usually be customized. For more information about these helper functions, see [Collection Class Helpers](../mfc/reference/collection-class-helpers.md). The typed pointer classes are wrappers for other classes in the class library. By using these wrappers, you enlist the compiler's type-checking to help you avoid errors. For more information on using these classes, see [Collections](../mfc/collections.md). These classes provide templates you can use to create arrays, lists, and maps using any type you like. diff --git a/docs/mfc/testing-internet-applications.md b/docs/mfc/testing-internet-applications.md index 17cd363f1b3..cee0b483a39 100644 --- a/docs/mfc/testing-internet-applications.md +++ b/docs/mfc/testing-internet-applications.md @@ -3,10 +3,13 @@ description: "Learn more about: Testing Internet Applications" title: "Testing Internet Applications" ms.date: "11/04/2016" helpviewer_keywords: ["Web applications [MFC], testing", "debugging Web applications [MFC], testing applications", "testing [MFC], Internet applications", "debugging [MFC], Web applications", "Internet debugging and testing"] -ms.assetid: ac4c74e3-d4ad-4e19-8f6c-e270de067f01 +ms.topic: concept-article --- # Testing Internet Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are some unique testing challenges on the Internet, especially for applications running on a Web server. Your initial testing will probably be done using a single-user client connecting to a test server. This will be useful for debugging your code. You will also want to test under real conditions: with multiple clients connected over high-speed connections as well as low-speed serial lines, including modem connections. It can be difficult to simulate real conditions, but it is certainly worth spending time designing possible scenarios and executing them. If possible, you will also want to use tools to do capacity and stress testing. Certain classes of bugs, such as timing bugs, are difficult to find and to reproduce. diff --git a/docs/mfc/testing-properties-and-events-with-test-container.md b/docs/mfc/testing-properties-and-events-with-test-container.md index fd24b36eca9..e6d18116671 100644 --- a/docs/mfc/testing-properties-and-events-with-test-container.md +++ b/docs/mfc/testing-properties-and-events-with-test-container.md @@ -1,12 +1,15 @@ --- -description: "Learn more about: Testing Properties and Events with Test Container" title: "Testing Properties and Events with Test Container" -ms.date: "11/04/2016" +description: "Learn more about: Testing Properties and Events with Test Container" +ms.date: 11/04/2016 helpviewer_keywords: ["testing, test containers", "tstcon32.exe", "debugging ActiveX controls", "test container", "ActiveX Control Test Container", "ActiveX controls [MFC], testing", "properties [MFC], testing"] -ms.assetid: 626867cf-fe53-4c30-8973-55bb93ef3917 +ms.topic: how-to --- # Testing Properties and Events with Test Container +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Test Container application, shipped in Visual C++, is an ActiveX control container for testing and debugging ActiveX controls. Test Container allows the control developer to test the control's functionality by changing its properties, invoking its methods, and firing its events. Test Container can display logs of data-binding notifications and also provides facilities for testing an ActiveX control's persistence functionality: you can save properties to a stream or to substorage, reload them, and examine the stored stream data. This section describes how to use the basic features of Test Container. For additional information, select the **Help** menu while running Test Container. ### To access the ActiveX Control Test Container @@ -36,7 +39,7 @@ At this point you can test your control's properties or events. The property now contains the new value. -#### To test events and specify the destination of event information. +#### To test events and specify the destination of event information 1. On the **Options** menu, click **Logging**. diff --git a/docs/mfc/the-ccmdui-class.md b/docs/mfc/the-ccmdui-class.md index 7b932b51d26..4769f532e4c 100644 --- a/docs/mfc/the-ccmdui-class.md +++ b/docs/mfc/the-ccmdui-class.md @@ -3,10 +3,12 @@ description: "Learn more about: The CCmdUI Class" title: "The CCmdUI Class" ms.date: "11/04/2016" helpviewer_keywords: ["updating user interface objects [MFC]", "user interface objects [MFC], updating", "CCmdUI class [MFC], menu updating", "update handlers [MFC]", "toolbars [MFC], updating"] -ms.assetid: 2f2bae62-8c29-45a4-bbce-490eb01907d5 --- # The CCmdUI Class +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When it routes an update command to its handler, the framework passes the handler a pointer to a `CCmdUI` object (or to an object of a `CCmdUI`-derived class). This object represents the menu item or toolbar button or other user-interface object that generated the command. The update handler calls member functions of the `CCmdUI` structure through the pointer to update the user-interface object. For example, here is an update handler for the Clear All menu item: [!code-cpp[NVC_MFCDocView#3](../mfc/codesnippet/cpp/the-ccmdui-class_1.cpp)] diff --git a/docs/mfc/thread-specific-hot-keys.md b/docs/mfc/thread-specific-hot-keys.md index cf9bd0c9221..bb3eddc5a5c 100644 --- a/docs/mfc/thread-specific-hot-keys.md +++ b/docs/mfc/thread-specific-hot-keys.md @@ -3,10 +3,12 @@ description: "Learn more about: Thread-Specific Hot Keys" title: "Thread-Specific Hot Keys" ms.date: "11/04/2016" helpviewer_keywords: ["CHotKeyCtrl class [MFC], thread-specific hot keys", "keyboard shortcuts [MFC], hot keys", "threading [MFC], hot keys in CHotKeyCtrl", "access keys [MFC], hot keys"] -ms.assetid: b6021274-1498-483f-bcbf-ba5723547cc8 --- # Thread-Specific Hot Keys +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An application sets a thread-specific hot key ([CHotKeyCtrl](../mfc/reference/chotkeyctrl-class.md)) by using the Windows `RegisterHotKey` function. When the user presses a thread-specific hot key, Windows posts a [WM_HOTKEY](/windows/win32/inputdev/wm-hotkey) message to the beginning of a particular thread's message queue. The WM_HOTKEY message contains the virtual key code, shift state, and user-defined ID of the specific hot key that was pressed. For a list of standard virtual key codes, see Winuser.h. For more information on this method, see [RegisterHotKey](/windows/win32/api/winuser/nf-winuser-registerhotkey). Note that the shift state flags used in the call to `RegisterHotKey` are not the same as those returned by the [GetHotKey](../mfc/reference/chotkeyctrl-class.md#gethotkey) member function; you'll have to translate these flags before calling `RegisterHotKey`. diff --git a/docs/mfc/tn001-window-class-registration.md b/docs/mfc/tn001-window-class-registration.md index 9a528229abf..df44ee16549 100644 --- a/docs/mfc/tn001-window-class-registration.md +++ b/docs/mfc/tn001-window-class-registration.md @@ -4,10 +4,12 @@ title: "TN001: Window Class Registration" ms.date: "11/04/2016" f1_keywords: ["vc.registration"] helpviewer_keywords: ["TN001", "WNDCLASS [MFC]", "AfxRegisterClass function"] -ms.assetid: 1abf678e-f220-4606-85e0-03df32f64c54 --- # TN001: Window Class Registration +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the MFC routines that register the special [WNDCLASS](/windows/win32/api/winuser/ns-winuser-wndclassw)es needed by Microsoft Windows. Specific `WNDCLASS` attributes used by MFC and Windows are discussed. ## The Problem diff --git a/docs/mfc/tn002-persistent-object-data-format.md b/docs/mfc/tn002-persistent-object-data-format.md index da977b57ee5..710322980dc 100644 --- a/docs/mfc/tn002-persistent-object-data-format.md +++ b/docs/mfc/tn002-persistent-object-data-format.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the MFC routines that support persistent C++ objects and the format of the object data when it is stored in a file. This applies only to classes with 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. ## The Problem @@ -56,7 +58,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/tn003-mapping-of-windows-handles-to-objects.md b/docs/mfc/tn003-mapping-of-windows-handles-to-objects.md index aae3e6e82cb..b7b4f207886 100644 --- a/docs/mfc/tn003-mapping-of-windows-handles-to-objects.md +++ b/docs/mfc/tn003-mapping-of-windows-handles-to-objects.md @@ -4,10 +4,12 @@ title: "TN003: Mapping of Windows Handles to Objects" ms.date: "11/04/2016" f1_keywords: ["vc.mapping"] helpviewer_keywords: ["TN003", "handle maps", "Windows handles to objects [MFC]", "mappings [MFC], Windows handles to objects"] -ms.assetid: fbea9f38-992c-4091-8dbc-f29e288617d6 --- # TN003: Mapping of Windows Handles to Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the MFC routines that support mapping Windows object handles to C++ objects. ## The Problem diff --git a/docs/mfc/tn006-message-maps.md b/docs/mfc/tn006-message-maps.md index 91f8aec4a38..41ac839b2e1 100644 --- a/docs/mfc/tn006-message-maps.md +++ b/docs/mfc/tn006-message-maps.md @@ -4,10 +4,12 @@ title: "TN006: Message Maps" ms.date: "06/25/2018" f1_keywords: ["vc.messages.maps"] helpviewer_keywords: ["ON_UPDATE_COMMAND_UI macro [MFC]", "ON_NOTIFY_RANGE macro [MFC]", "ON_COMMAND macro [MFC]", "ON_CONTROL_RANGE macro [MFC]", "ON_REGISTERED_MESSAGE macro [MFC]", "ON_NOTIFY message [MFC]", "ON_COMMAND_RANGE_EX macro [MFC]", "ON_MESSAGE macro [MFC]", "Windows messages [MFC], message maps", "ON_COMMAND_RANGE macro [MFC]", "TN006", "ON_CONTROL macro [MFC]", "ON_COMMAND_EX macro [MFC]", "message maps [MFC], Windows messaging"] -ms.assetid: af4b6794-4b40-4f1e-ad41-603c3b7409bb --- # TN006: Message Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the MFC message map facility. ## The Problem @@ -97,7 +99,7 @@ pWnd->SendMessage(WM_MYMESSAGE); The range of user-defined messages that use this approach must be in the range WM_USER to 0x7fff. > [!NOTE] -> ClassWizard does not support entering ON_MESSAGE handler routines from the ClassWizard user interface. You must manually enter them from the Visual C++ editor. ClassWizard will parse these entries and let you browse them just like any other message-map entries. +> ClassWizard does not support entering ON_MESSAGE handler routines from the ClassWizard user interface. You must manually enter them from the Visual Studio editor. ClassWizard will parse these entries and let you browse them just like any other message-map entries. ## Registered Windows Messages @@ -150,7 +152,7 @@ Advanced users can use the ON_COMMAND_EX macro, which is an extended form of com Examples of these forms: -- Inside Resource.h (usually generated by Visual C++) +- Inside Resource.h (usually generated by Visual Studio) ```cpp #define ID_MYCMD 100 diff --git a/docs/mfc/tn011-using-mfc-as-part-of-a-dll.md b/docs/mfc/tn011-using-mfc-as-part-of-a-dll.md index 6036c016123..bc0600b0c0b 100644 --- a/docs/mfc/tn011-using-mfc-as-part-of-a-dll.md +++ b/docs/mfc/tn011-using-mfc-as-part-of-a-dll.md @@ -3,10 +3,12 @@ description: "Learn more about: TN011: Using MFC as Part of a DLL" title: "TN011: Using MFC as Part of a DLL" ms.date: "11/04/2016" helpviewer_keywords: ["_USRDLL symbol", "USRDLLs, compiler switches", "TN011", "DLLs [MFC], linking", "MFC DLLs [MFC], linking regular MFC DLLs to MFC"] -ms.assetid: 76753e9c-59dc-40f6-b6a7-f6bb9a7c4190 --- # TN011: Using MFC as Part of a DLL +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes regular MFC DLLs, which allow you to use the MFC library as part of a Windows dynamic-link library (DLL). It assumes that you are familiar with Windows DLLs and how to build them. For information about MFC extension DLLs, with which you can create extensions to the MFC library, see [DLL Version of MFC](../mfc/tn033-dll-version-of-mfc.md). ## DLL Interfaces @@ -17,7 +19,7 @@ If both a DLL and an application want to use MFC, both have a choice to either u regular MFC DLLs have several advantages: -- The application that uses the DLL does not have to use MFC and does not have to be a Visual C++ application. +- The application that uses the DLL does not have to use MFC and does not have to be a Visual Studio application. - With regular MFC DLLs that statically link to MFC, the size of the DLL depends only on the MFC and C runtime routines that are used and linked. @@ -63,7 +65,7 @@ The `DllMain` function that MFC provides will call the [CWinApp::ExitInstance](. ## Linking Your DLL -With regular MFC DLLs that statically link to MFC, you must link your DLL with Nafxcwd.lib or Nafxcw.lib and with the version of the C runtimes named Libcmt.lib. These libraries are pre-built and may be installed by specifying them when you run Visual C++ setup. +With regular MFC DLLs that statically link to MFC, you must link your DLL with Nafxcwd.lib or Nafxcw.lib and with the version of the C runtimes named Libcmt.lib. These libraries are pre-built and may be installed by specifying them when you run Visual Studio setup. ## Sample Code diff --git a/docs/mfc/tn014-custom-controls.md b/docs/mfc/tn014-custom-controls.md index 6cfdbcff967..f1562fa20f3 100644 --- a/docs/mfc/tn014-custom-controls.md +++ b/docs/mfc/tn014-custom-controls.md @@ -1,13 +1,15 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the MFC Support for custom and self-drawing controls. It also describes dynamic subclassing, and describes the relationship between [CWnd](../mfc/reference/cwnd-class.md) objects and `HWND`s. The MFC sample application CTRLTEST illustrates how to use many custom controls. See the source code for the MFC General sample [CTRLTEST](../overview/visual-cpp-samples.md) and online help. @@ -39,44 +41,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 +120,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 +128,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/tn016-using-cpp-multiple-inheritance-with-mfc.md b/docs/mfc/tn016-using-cpp-multiple-inheritance-with-mfc.md index cf44c6bf0ea..fec8f1aa64e 100644 --- a/docs/mfc/tn016-using-cpp-multiple-inheritance-with-mfc.md +++ b/docs/mfc/tn016-using-cpp-multiple-inheritance-with-mfc.md @@ -4,10 +4,12 @@ title: "TN016: Using C++ Multiple Inheritance with MFC" ms.date: "06/28/2018" f1_keywords: ["vc.inheritance"] helpviewer_keywords: ["TN016", "MI (Multiple Inheritance)", "multiple inheritance, MFC support for"] -ms.assetid: 4ee27ae1-1410-43a5-b111-b6af9b84535d --- # TN016: Using C++ Multiple Inheritance with MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes how to use multiple inheritance (MI) with the Microsoft Foundation Classes. The use of MI is not required with MFC. MI is not used in any MFC classes and is not required to write a class library. The following subtopics describe how MI affects the use of common MFC idioms as well as covering some of the restrictions of MI. Some of these restrictions are general C++ restrictions. Others are imposed by the MFC architecture. diff --git a/docs/mfc/tn017-destroying-window-objects.md b/docs/mfc/tn017-destroying-window-objects.md index f50a0b32b71..960374a2479 100644 --- a/docs/mfc/tn017-destroying-window-objects.md +++ b/docs/mfc/tn017-destroying-window-objects.md @@ -4,10 +4,12 @@ title: "TN017: Destroying window objects" ms.date: 06/03/2022 f1_keywords: ["vc.objects"] helpviewer_keywords: ["destroying windows", "TN017", "PostNcDestroy method [MFC]"] -ms.assetid: 5bf208a5-5683-439b-92a1-547c5ded26cd --- # TN017: Destroying window objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the use of the [`CWnd::PostNcDestroy`](../mfc/reference/cwnd-class.md#postncdestroy) method. Use this method if you want to do customized allocation of `CWnd`-derived objects. This note also explains why you should use [`CWnd::DestroyWindow`](../mfc/reference/cwnd-class.md#destroywindow) to destroy a C++ Windows object instead of the **`delete`** operator. If you follow the guidelines in this article, you'll have few cleanup problems. These problems can result from issues such as forgetting to delete/free C++ memory, forgetting to free system resources like `HWND`s, or freeing objects too many times. diff --git a/docs/mfc/tn020-id-naming-and-numbering-conventions.md b/docs/mfc/tn020-id-naming-and-numbering-conventions.md index 753afb306c8..39b718d2625 100644 --- a/docs/mfc/tn020-id-naming-and-numbering-conventions.md +++ b/docs/mfc/tn020-id-naming-and-numbering-conventions.md @@ -4,21 +4,23 @@ title: "TN020: ID Naming and Numbering Conventions" ms.date: "11/04/2016" f1_keywords: ["vc.id"] helpviewer_keywords: ["TN020", "resource identifiers, naming and numbering", "resource identifiers"] -ms.assetid: aecbd2cf-68b3-47f6-ae21-b1f507917245 --- # TN020: ID Naming and Numbering Conventions +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the ID naming and numbering conventions that MFC 2.0 uses for resources, commands, strings, controls, and child windows. The MFC ID naming and numbering conventions are intended to meet the following requirements: -- Provide a consistent ID-naming standard used across the MFC library and MFC applications that are supported by the Visual C++ resource editor. This makes it easier for the programmer to interpret the type and origin of a resource from its ID. +- Provide a consistent ID-naming standard used across the MFC library and MFC applications that are supported by the Visual Studio resource editor. This makes it easier for the programmer to interpret the type and origin of a resource from its ID. - Emphasize the strong 1-to-1 relationship between certain types of IDs. - Conform to already widely used standards for naming IDs in Windows. -- Partition the ID-numbering space. ID numbers can be assigned by the programmer, MFC, Windows, and Visual C++-edited resources. Appropriate partitioning will help avoid duplication of ID numbers. +- Partition the ID-numbering space. ID numbers can be assigned by the programmer, MFC, Windows, and Visual Studio-edited resources. Appropriate partitioning will help avoid duplication of ID numbers. ## The ID Prefix Naming Convention diff --git a/docs/mfc/tn021-command-and-message-routing.md b/docs/mfc/tn021-command-and-message-routing.md index 597613bdc7b..1ad354a62dd 100644 --- a/docs/mfc/tn021-command-and-message-routing.md +++ b/docs/mfc/tn021-command-and-message-routing.md @@ -4,16 +4,18 @@ title: "TN021: Command and Message Routing" ms.date: "06/28/2018" f1_keywords: ["vc.routing"] helpviewer_keywords: ["TN021", "command routing [MFC], technical note TN021", "Windows messages [MFC], routing"] -ms.assetid: b5952c8b-123e-406c-a36d-a6ac7c6df307 --- # TN021: Command and Message Routing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. This note describes the command routing and dispatch architecture as well as advanced topics in general window message routing. -Please refer to Visual C++ for general details on the architectures described here, especially the distinction between Windows messages, control notifications, and commands. This note assumes you are very familiar with the issues described in the printed documentation and only addresses very advanced topics. +Please refer to Visual Studio for general details on the architectures described here, especially the distinction between Windows messages, control notifications, and commands. This note assumes you are very familiar with the issues described in the printed documentation and only addresses very advanced topics. ## Command Routing and Dispatch MFC 1.0 Functionality Evolves to MFC 2.0 Architecture @@ -29,7 +31,7 @@ This functionality has been generalized and extended in MFC 2.0 to allow command ## Command IDs -See Visual C++ for an explanation of the command routing and binding process. [Technical Note 20](../mfc/tn020-id-naming-and-numbering-conventions.md) contains information on ID naming. +See Visual Studio for an explanation of the command routing and binding process. [Technical Note 20](../mfc/tn020-id-naming-and-numbering-conventions.md) contains information on ID naming. We use the generic prefix "ID_" for command IDs. Command IDs are >= 0x8000. The message line or status bar will show the command description string if there is a STRINGTABLE resource with the same IDs as the command ID. @@ -71,7 +73,7 @@ Maintaining the enabled/checked state of all a program's menu items all the time `CFrameWnd` also handles the WM_ENTERIDLE message to describe the current menu item selected on the status bar (also known as the message line). -An application's menu structure, edited by Visual C++, is used to represent the potential commands available at WM_INITMENUPOPUP time. ON_UPDATE_COMMAND_UI handlers can modify the state or text of a menu, or for advanced uses (like the File MRU list or the OLE Verbs pop-up menu), actually modify the menu structure before the menu is drawn. +An application's menu structure, edited by Visual Studio, is used to represent the potential commands available at WM_INITMENUPOPUP time. ON_UPDATE_COMMAND_UI handlers can modify the state or text of a menu, or for advanced uses (like the File MRU list or the OLE Verbs pop-up menu), actually modify the menu structure before the menu is drawn. The same sort of ON_UPDATE_COMMAND_UI processing is done for toolbars (and other control bars) when the application enters its idle loop. See the *Class Library Reference* and [Technical Note 31](../mfc/tn031-control-bars.md) for more information on control bars. diff --git a/docs/mfc/tn022-standard-commands-implementation.md b/docs/mfc/tn022-standard-commands-implementation.md index 87a928b8c48..a12033ebd64 100644 --- a/docs/mfc/tn022-standard-commands-implementation.md +++ b/docs/mfc/tn022-standard-commands-implementation.md @@ -4,16 +4,18 @@ title: "TN022: Standard Commands Implementation" ms.date: "11/04/2016" f1_keywords: ["vc.commands"] helpviewer_keywords: ["ID_PREV_PANE command [MFC]", "ID_APP_EXIT command [MFC]", "ID_NEXT_PANE command [MFC]", "ID_INDICATOR_REC command [MFC]", "ID_WINDOW_SPLIT command [MFC]", "ID_FILE_PRINT_PREVIEW command [MFC]", "ID_WINDOW_CASCADE command [MFC]", "ID_FILE_CLOSE command [MFC]", "ID_FILE_SAVE_COPY_AS command [MFC]", "ID_WINDOW_ARRANGE command [MFC]", "ID_EDIT_FIND command [MFC]", "ID_FILE_OPEN command [MFC]", "ID_FILE_PAGE_SETUP command [MFC]", "ID_OLE_VERB_FIRST command [MFC]", "ID_EDIT_UNDO command [MFC]", "ID_EDIT_CLEAR command [MFC]", "ID_INDICATOR_CAPS command [MFC]", "ID_HELP_INDEX command [MFC]", "commands [MFC], standard", "ID_FILE_PRINT_SETUP command [MFC]", "ID_DEFAULT_HELP command [MFC]", "ID_INDICATOR_SCRL command [MFC]", "ID_FILE_PRINT command [MFC]", "ID_INDICATOR_OVR command [MFC]", "ID_INDICATOR_KANA command [MFC]", "ID_EDIT_COPY command [MFC]", "ID_EDIT_REDO command [MFC]", "ID_EDIT_PASTE command [MFC]", "ID_OLE_INSERT_NEW command [MFC]", "ID_OLE_EDIT_LINKS command [MFC]", "ID_EDIT_PASTE_SPECIAL command [MFC]", "ID_INDICATOR_EXT command [MFC]", "ID_HELP_USING command [MFC]", "standard commands", "ID_VIEW_STATUS_BAR command [MFC]", "ID_FILE_SAVE_AS command [MFC]", "ID_EDIT_CLEAR_ALL command [MFC]", "ID_WINDOW_NEW command [MFC]", "ID_CONTEXT_HELP command [MFC]", "ID_EDIT_REPLACE command [MFC]", "ID_WINDOW_TILE_HORZ command [MFC]", "ID_APP_ABOUT command [MFC]", "TN022", "ID_VIEW_TOOLBAR command [MFC]", "ID_HELP command [MFC]", "ID_WINDOW_TILE_VERT command [MFC]", "ID_EDIT_CUT command [MFC]", "ID_FILE_UPDATE command [MFC]", "ID_EDIT_REPEAT command [MFC]", "ID_FILE_SAVE command [MFC]", "ID_EDIT_PASTE_LINK command [MFC]", "ID_EDIT_SELECT_ALL command [MFC]", "ID_FILE_NEW command [MFC]", "ID_INDICATOR_NUM command"] -ms.assetid: a7883b46-23f7-4870-ac3a-804aed9258b5 --- # TN022: Standard Commands Implementation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. This note describes the standard command implementations provided by MFC 2.0. Read [Technical Note 21](../mfc/tn021-command-and-message-routing.md) first because it describes the mechanisms used to implement many of the standard commands. -This description assumes knowledge of the MFC architectures, APIs, and common programming practice. Documented as well as undocumented "implementation only" APIs are described. This is not a place to start learning about the features of or how to program in MFC. Refer to Visual C++ for more general information and for details of documented APIs. +This description assumes knowledge of the MFC architectures, APIs, and common programming practice. Documented as well as undocumented "implementation only" APIs are described. This is not a place to start learning about the features of or how to program in MFC. Refer to Visual Studio for more general information and for details of documented APIs. ## The Problem diff --git a/docs/mfc/tn023-standard-mfc-resources.md b/docs/mfc/tn023-standard-mfc-resources.md index d7e50ae3190..913e6b22d01 100644 --- a/docs/mfc/tn023-standard-mfc-resources.md +++ b/docs/mfc/tn023-standard-mfc-resources.md @@ -3,10 +3,12 @@ description: "Learn more about: TN023: Standard MFC Resources" title: "TN023: Standard MFC Resources" ms.date: "11/04/2016" helpviewer_keywords: ["resources [MFC]", "TN023", "standard resources"] -ms.assetid: 60af8415-c576-4c2f-a711-ca5da0b9a1f2 --- # TN023: Standard MFC Resources +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the standard resources provided with and needed by the MFC library. ## Standard Resources @@ -29,7 +31,7 @@ Clip-art resources are additional resources that the framework does not depend o - Prompts.rc: Contains menu-prompt string resources for each predefined command, such as "Create a new document" for ID_FILE_NEW. -- Commdlg.rc: A Visual C++ compatible .rc file that contains the standard COMMDLG dialog templates. +- Commdlg.rc: A Visual Studio compatible .rc file that contains the standard COMMDLG dialog templates. Standard framework resources are resources with AFX-defined IDs that the framework depends on for internal implementations. You will rarely need to change these AFX-defined resources. If you do, you should follow the procedure outlined later in this topic. @@ -47,7 +49,7 @@ The following framework resources are contained in the MFC\INCLUDE directory: #### To use a clip-art binary resource -1. Open your application's resource file in Visual C++. +1. Open your application's resource file in Visual Studio. 1. Open Common.rc. This file contains all the binary clip-art resources. This may take some time because the Common.rc file is compiled. @@ -72,11 +74,11 @@ Standard framework resources are usually included in an application by using the The most common case of customizing standard framework resources is adding or removing additional includes for printing, OLE Client, and OLE Server support. -In some rare cases you might want to customize the contents of the standard framework resources for your particular application, not just add and remove the entire file. The followings steps show how you can limit the resources that are included: +In some rare cases you might want to customize the contents of the standard framework resources for your particular application, not just add and remove the entire file. The following steps show how you can limit the resources that are included: ##### To customize the contents of a standard resource file -1. Open the resource file in Visual C++. +1. Open the resource file in Visual Studio. 1. Using the Resource Set Includes command, remove the `#include` for the standard .rc file that you want to customize. For example, to customize the print-preview toolbar, remove the `#include "afxprint.rc"` line. diff --git a/docs/mfc/tn024-mfc-defined-messages-and-resources.md b/docs/mfc/tn024-mfc-defined-messages-and-resources.md index b510b909b79..6a18d57ef98 100644 --- a/docs/mfc/tn024-mfc-defined-messages-and-resources.md +++ b/docs/mfc/tn024-mfc-defined-messages-and-resources.md @@ -3,10 +3,12 @@ description: "Learn more about: TN024: MFC-Defined Messages and Resources" title: "TN024: MFC-Defined Messages and Resources" ms.date: "11/04/2016" helpviewer_keywords: ["resources [MFC]", "Windows messages [MFC], MFC-defined", "messages [MFC], MFC", "TN024"] -ms.assetid: c65353ce-8096-454b-ad22-1a7a1dd9a788 --- # TN024: MFC-Defined Messages and Resources +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. @@ -159,9 +161,9 @@ The default toolbar supplied by AppWizard is based on an RT_TOOLBAR custom resou ## RT_DLGINIT Resource Format -One MFC private resource format is used to store extra dialog initialization information. This includes the initial strings stored in a combo box. The format of this resource is not designed to be manually edited, but is handled by Visual C++. +One MFC private resource format is used to store extra dialog initialization information. This includes the initial strings stored in a combo box. The format of this resource is not designed to be manually edited, but is handled by Visual Studio. -Visual C++ and this RT_DLGINIT resource are not required to use the related features of MFC since there are API alternative to using the information in the resource. Using Visual C++ makes it much easier to write, maintain, and translate your application in the long run. +Visual Studio and this RT_DLGINIT resource are not required to use the related features of MFC since there are API alternative to using the information in the resource. Using Visual Studio makes it much easier to write, maintain, and translate your application in the long run. The basic structure of a RT_DLGINIT resource is as follows: @@ -186,7 +188,7 @@ A repeated section contains the control ID to send the message to, the Message # SendDlgItemMessage(, , 0, &); ``` -This is a very general format, allowing any Windows messages and data content. The Visual C++ resource editor and MFC only support a limited subset of Windows messages: CB_ADDSTRING for the initial list-choices for combo boxes (the data is a text string). +This is a very general format, allowing any Windows messages and data content. The Visual Studio resource editor and MFC only support a limited subset of Windows messages: CB_ADDSTRING for the initial list-choices for combo boxes (the data is a text string). ## See also diff --git a/docs/mfc/tn025-document-view-and-frame-creation.md b/docs/mfc/tn025-document-view-and-frame-creation.md index a914375e71e..425c5552a97 100644 --- a/docs/mfc/tn025-document-view-and-frame-creation.md +++ b/docs/mfc/tn025-document-view-and-frame-creation.md @@ -4,10 +4,12 @@ title: "TN025: Document, View, and Frame Creation" ms.date: "11/04/2016" f1_keywords: ["vc.creation"] helpviewer_keywords: ["documents [MFC], view and frame creation", "TN025"] -ms.assetid: 09254d72-6e1d-43db-80e9-693887dbeda2 --- # TN025: Document, View, and Frame Creation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn026-ddx-and-ddv-routines.md b/docs/mfc/tn026-ddx-and-ddv-routines.md index 8cfde655e61..0d6e4eb4176 100644 --- a/docs/mfc/tn026-ddx-and-ddv-routines.md +++ b/docs/mfc/tn026-ddx-and-ddv-routines.md @@ -4,10 +4,12 @@ title: "TN026: DDX and DDV Routines" ms.date: "06/28/2018" f1_keywords: ["DDX", "DDV"] helpviewer_keywords: ["DDX (dialog data exchange), procedures", "TN026", "DDV (dialog data validation), procedures"] -ms.assetid: c2eba87a-4b47-4083-b28b-e2fa77dfb4c4 --- # TN026: DDX and DDV Routines +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn028-context-sensitive-help-support.md b/docs/mfc/tn028-context-sensitive-help-support.md index 1a5ff078b5a..b6ae1421563 100644 --- a/docs/mfc/tn028-context-sensitive-help-support.md +++ b/docs/mfc/tn028-context-sensitive-help-support.md @@ -4,11 +4,13 @@ title: "TN028: Context-Sensitive Help Support" ms.date: "11/04/2016" f1_keywords: ["vc.help"] helpviewer_keywords: ["context-sensitive Help [MFC], MFC applications", "TN028", "resource identifiers, context-sensitive Help"] -ms.assetid: 884f1c55-fa27-4d4c-984f-30907d477484 --- # TN028: Context-Sensitive Help Support -This note describes the rules for assigning Help contexts IDs and other help issues in MFC. Context-sensitive help support requires the help compiler that is available in Visual C++. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +This note describes the rules for assigning Help contexts IDs and other help issues in MFC. Context-sensitive help support requires the help compiler that is available in Visual Studio. > [!NOTE] > In addition to implementing context-sensitive help using WinHelp, MFC also supports using HTML Help. For more information on this support and programming with HTML Help, see [HTML Help: Context-Sensitive Help for Your Programs](../mfc/html-help-context-sensitive-help-for-your-programs.md). @@ -74,7 +76,6 @@ To override this functionality and the way that a Help context is determined, yo ## WM_COMMANDHELP ``` - afx_msg LRESULT CWnd::OnCommandHelp(WPARAM wParam, LPARAM lParam) ``` @@ -103,7 +104,6 @@ If the user chooses a command from the menu, it is handled as help on that comma ## WM_HELPHITTEST ``` - afx_msg LRESULT CWnd::OnHelpHitTest( WPARAM, LPARAM lParam) ``` diff --git a/docs/mfc/tn029-splitter-windows.md b/docs/mfc/tn029-splitter-windows.md index 44ff393dd03..4a8d2d983dd 100644 --- a/docs/mfc/tn029-splitter-windows.md +++ b/docs/mfc/tn029-splitter-windows.md @@ -4,17 +4,19 @@ title: "TN029: Splitter Windows" ms.date: "11/04/2016" f1_keywords: ["vc.windows.splitter"] helpviewer_keywords: ["TN029", "splitter windows [MFC], about splitter windows"] -ms.assetid: 2c57ce99-2a3c-4eff-9cea-baccb13af075 --- # TN029: Splitter Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes the MFC [CSplitterWnd Class](../mfc/reference/csplitterwnd-class.md), which provides window splits and manages the resizing of other pane windows. ## Splitter Styles A `CSplitterWnd` supports two different styles of splitting windows. -In "static splitters," the splitter window creates the panes when it is created. The order and number of panes never change. Splitter bars are used to resize the different panes. You can use this style to display a different view class in each pane. The Visual C++ graphics editor and the Windows File Manager are examples of programs that use this splitter style. This style of splitter window does not use splitter boxes. +In "static splitters," the splitter window creates the panes when it is created. The order and number of panes never change. Splitter bars are used to resize the different panes. You can use this style to display a different view class in each pane. The Visual Studio graphics editor and the Windows File Manager are examples of programs that use this splitter style. This style of splitter window does not use splitter boxes. In "dynamic splitters," additional panes are created and destroyed as the user splits and un-splits new views. This splitter starts out with a single view and provides splitter boxes for the user to initiate splitting. The splitter window dynamically creates a new view object when the view is split in one direction. This new view object represents the new pane. If the view is split in two directions by using the keyboard interface, the splitter window creates three new view objects for the three new panes. While the split is active, Windows displays the splitter box as a splitter bar between the panes. Windows destroys additional view objects when the user removes a split, but the original view remains until the splitter window itself is destroyed. Microsoft Excel and Microsoft Word are examples of applications that use the dynamic splitter style. diff --git a/docs/mfc/tn030-customizing-printing-and-print-preview.md b/docs/mfc/tn030-customizing-printing-and-print-preview.md index 851f9d6ad6d..859df12533e 100644 --- a/docs/mfc/tn030-customizing-printing-and-print-preview.md +++ b/docs/mfc/tn030-customizing-printing-and-print-preview.md @@ -4,10 +4,12 @@ title: "TN030: Customizing Printing and Print Preview" ms.date: "06/28/2018" f1_keywords: ["vc.print"] helpviewer_keywords: ["TN030", "customizing printing and print preview", "printing [MFC], views", "printing views [MFC]", "print preview [MFC], customizing"] -ms.assetid: 32744697-c91c-41b6-9a12-b8ec01e0d438 --- # TN030: Customizing Printing and Print Preview +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn031-control-bars.md b/docs/mfc/tn031-control-bars.md index cdd945cff4a..f186f5a4dc3 100644 --- a/docs/mfc/tn031-control-bars.md +++ b/docs/mfc/tn031-control-bars.md @@ -4,10 +4,12 @@ title: "TN031: Control Bars" ms.date: "11/04/2016" f1_keywords: ["vc.controls.bars"] helpviewer_keywords: ["control bars [MFC], styles", "CStatusBar class [MFC], Tech Note 31 usage", "CControlBar class [MFC], Tech Note 31 usage", "CControlBar class [MFC], deriving from", "control bars [MFC], classes [MFC]", "CDialogBar class [MFC], Tech Note 31 usage", "CToolBar class [MFC], Tech Note 31 usage", "TN031", "styles [MFC], control bars"] -ms.assetid: 8cb895c0-40ea-40ef-90ee-1dd29f34cfd1 --- # TN031: Control Bars +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn032-mfc-exception-mechanism.md b/docs/mfc/tn032-mfc-exception-mechanism.md index 37d0ecc454e..37358762f81 100644 --- a/docs/mfc/tn032-mfc-exception-mechanism.md +++ b/docs/mfc/tn032-mfc-exception-mechanism.md @@ -3,10 +3,12 @@ description: "Learn more about: TN032: MFC Exception Mechanism" title: "TN032: MFC Exception Mechanism" ms.date: "11/04/2016" helpviewer_keywords: ["TN032", "MFC, exceptions", "CException class [MFC], using"] -ms.assetid: 0271f0aa-82cb-47a2-b7ea-e88126fc7e43 --- # TN032: MFC Exception Mechanism +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Previous versions of Visual C++ did not support the standard C++ exception mechanism, and MFC provided macros **TRY/CATCH/THROW** that were used instead. This version of Visual C++ fully supports C++ exceptions. This note covered some of the advanced implementation details of the previous macros including how to automatically cleanup stack based objects. Because C++ exceptions support stack unwinding by default, this technical note is no longer necessary. Refer to [Exceptions: Using MFC Macros and C++ Exceptions](../mfc/exceptions-using-mfc-macros-and-cpp-exceptions.md) for more information on the differences between the MFC macros and the new C++ keywords. diff --git a/docs/mfc/tn033-dll-version-of-mfc.md b/docs/mfc/tn033-dll-version-of-mfc.md index 0e5df9d531b..3db6c4930e0 100644 --- a/docs/mfc/tn033-dll-version-of-mfc.md +++ b/docs/mfc/tn033-dll-version-of-mfc.md @@ -6,6 +6,9 @@ helpviewer_keywords: ["MFC DLLs [MFC], writing MFC extension DLLS", "AFXDLL libr --- # TN033: DLL Version of MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note describes how you can use the *`MFCxx.DLL`* and *`MFCxxD.DLL`* (where *xx* is the MFC version number) shared dynamic link libraries with MFC applications and MFC extension DLLs. For more information about regular MFC DLLs, see [Using MFC as Part of a DLL](../mfc/tn011-using-mfc-as-part-of-a-dll.md). This technical note covers three aspects of DLLs. The last two are for the more advanced users: @@ -416,9 +419,9 @@ A full rebuild is required after these changes are made. ### Building the Samples -Most of the MFC sample programs can be built from Visual C++ or from a shared NMAKE-compatible MAKEFILE from the command line. +Most of the MFC sample programs can be built from Visual Studio or from a shared NMAKE-compatible MAKEFILE from the command line. -To convert any of these samples to use *`MFCxx.DLL`*, you can load the MAK file into the Visual C++ and set the Project options as described above. If you're using the NMAKE build, you can specify `AFXDLL=1` on the NMAKE command line and that will build the sample using the shared MFC libraries. +To convert any of these samples to use *`MFCxx.DLL`*, you can load the MAK file into the Visual Studio and set the Project options as described above. If you're using the NMAKE build, you can specify `AFXDLL=1` on the NMAKE command line and that will build the sample using the shared MFC libraries. The MFC Advanced Concepts sample [DLLHUSK](../overview/visual-cpp-samples.md) is built with the DLL version of MFC. This sample not only illustrates how to build an application linked with *`MFCxx.DLL`*, but it also illustrates other features of the MFC DLL packaging option such as MFC extension DLLs described later in this technical note. @@ -426,7 +429,7 @@ The MFC Advanced Concepts sample [DLLHUSK](../overview/visual-cpp-samples.md) is The release versions of the DLLs (*`MFCxx.DLL`* and *`MFCxxU.DLL`*) are freely redistributable. The debug versions of the DLLs are not freely redistributable and should be used only during the development of your application. -The debug DLLs are provided with debugging information. By using the Visual C++ debugger, you can trace execution of both your application and the DLL. The Release DLLs (*`MFCxx.DLL`* and *`MFCxxU.DLL`*) don't contain debugging information. +The debug DLLs are provided with debugging information. By using the Visual Studio debugger, you can trace execution of both your application and the DLL. The Release DLLs (*`MFCxx.DLL`* and *`MFCxxU.DLL`*) don't contain debugging information. If you customize or rebuild the DLLs, then you should call them something other than "MFCxx". The MFC SRC file *`MFCDLL.MAK`* describes build options and contains the logic for renaming the DLL. Renaming the files is necessary, since these DLLs are potentially shared by many MFC applications. Having your custom version of the MFC DLLs replace the ones installed on the system may break another MFC application using the shared MFC DLLs. diff --git a/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md b/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md index e0ab4fbfd9e..21c577de734 100644 --- a/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md +++ b/docs/mfc/tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md @@ -1,71 +1,80 @@ --- -description: "Learn more about: TN035: Using Multiple Resource Files and Header Files with Visual C++" -title: "TN035: Using Multiple Resource Files and Header Files with Visual C++" +description: "Learn more about: TN035: Using multiple resource files and header files with Visual Studio" +title: "TN035: Using multiple resource files and header files with Visual Studio" ms.date: "11/04/2016" f1_keywords: ["vc.resources"] helpviewer_keywords: ["resource files, multiple", "TN035"] -ms.assetid: 1f08ce5e-a912-44cc-ac56-7dd93ad73fb6 --- -# TN035: Using Multiple Resource Files and Header Files with Visual C++ +# TN035: Using multiple resource files and header files with Visual Studio + +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. -This note describes how the Visual C++ resource editor supports multiple resource files and header files shared in a single project or shared across multiple projects and how you can take advantage of that support. This note answers these questions: +This note describes how the Visual Studio resource editor supports multiple resource files and header files shared in a single project or shared across multiple projects and how you can take advantage of that support. This note answers these questions: - When might you want to split a project into multiple resource files and/or header files, and how you do it -- How do you share a common header .H file between two .RC files +- How do you share a common header `.H` file between two `.RC` files -- How do you divide project resources into multiple .RC files +- How do you divide project resources into multiple `.RC` files -- How do you (and the tools) manage build dependencies between .RC, .CPP, and .H files +- How do you (and the tools) manage build dependencies between `.RC`, `.CPP`, and `.H` files -You should be aware that if you add an additional resource file to your project, ClassWizard will not recognize the resources in the added file. +You should be aware that if you add an additional resource file to your project, ClassWizard won't recognize the resources in the added file. This note is structured to answer the above questions as follows: -- **Overview of How Visual C++ Manages Resource Files and Header Files** provides an overview of how the Resource Set Includes command in Visual C++ lets you use multiple resource files and header files in the same project. +- **Overview of how Visual Studio manages resource files and header files** provides an overview of how the Resource Set Includes command in Visual Studio lets you use multiple resource files and header files in the same project. -- **Analysis of AppWizard-created .RC and .H Files** looks at the multiple resource and header files that are used by an AppWizard-created application. These files serve as a good model for additional resource files and header files you might want to add to your project. +- **Analysis of AppWizard-created `.RC` and `.H` Files** looks at the multiple resource and header files that are used by an AppWizard-created application. These files serve as a good model for additional resource files and header files you might want to add to your project. -- **Including Additional Header Files** describes where you might want to include multiple header files, and provides details how to do so. +- **Including additional header files** describes where you might want to include multiple header files, and provides details how to do so. -- **Sharing a Header File Between Two .RC Files** shows how you can share one header file between multiple .RC files in different projects, or perhaps in the same project. +- **Sharing a header file between two `.RC` files** shows how you can share one header file between multiple `.RC` files in different projects, or perhaps in the same project. -- **Using Multiple Resource Files in the Same Project** describes where you might want to break up your project into multiple .RC files, and provides details how to do so. +- **Using multiple resource files in the same project** describes where you might want to break up your project into multiple `.RC` files, and provides details how to do so. -- **Enforcement of Non-Editable Visual C++ Files** describes how you can make sure Visual C++ does not edit and unintentionally reformat a custom resource. +- **Enforcement of non-editable Visual Studio files** describes how you can make sure Visual Studio doesn't edit and unintentionally reformat a custom resource. -- **Managing Symbols Shared by Multiple Visual C++-Edited .RC Files** describes how to share the same symbols across multiple .RC files and how to avoid assigning duplicate ID numeric values. +- **Managing symbols shared by multiple Visual Studio-edited `.RC` files** describes how to share the same symbols across multiple `.RC` files and how to avoid assigning duplicate ID numeric values. -- **Managing Dependencies Between .RC, .CPP, and .H Files** describes how Visual C++ avoids unnecessary recompiling .CPP files that are dependent on resource symbol files. +- **Managing dependencies between `.RC`, `.CPP`, and `.H` files** describes how Visual Studio avoids unnecessary recompiling `.CPP` files that are dependent on resource symbol files. -- **How Visual C++ Manages Set Includes Information** provides technical details about how Visual C++ keeps track of multiple (nested) .RC files and multiple header files that are #include'd by an .RC file. +- **How Visual Studio manages Set Includes information** provides technical details about how Visual Studio keeps track of multiple (nested) `.RC` files and multiple header files that are included by an `.RC` file. -## Overview of How Visual C++ Manages Resource Files and Header Files +## Overview of how Visual Studio manages resource files and header files -Visual C++ manages a single .RC resource file and a corresponding .H header file as a tightly coupled pair of files. When you edit and save resources in an .RC file, you indirectly edit and save symbols in the corresponding .H file. Although you can open and edit multiple .RC files at a time (using Visual C++'s MDI user interface) for any given .RC file you indirectly edit exactly one corresponding header file. +Visual Studio manages a single `.RC` resource file and a corresponding `.H` header file as a tightly coupled pair of files. When you edit and save resources in an `.RC` file, you indirectly edit and save symbols in the corresponding `.H` file. Although you can open and edit multiple `.RC` files at a time (using Visual Studio's MDI user interface), for any given `.RC` file you indirectly edit exactly one corresponding header file. -### Symbol Header File +### Resource View's Resource Includes dialog -By default, Visual C++ always names the corresponding header file RESOURCE.H, regardless of the name of the resource file (e.g., MYAPP.RC). Using the **Resource Includes** command from the **View** menu in Visual C++, you can change the name of this header file by updating the Symbol Header File file in the **Set Includes** dialog box. +To access the **Resource Includes**, open the **Resource View** then right-click the `.RC` file and select **Resource Includes**. -### Read-Only Symbol Directives +#### Symbol Header File -Although Visual C++ only edits one header file for any given .RC file, Visual C++ supports references to symbols defined in additional read-only header files. Using the **Resource Includes** command from the **View** menu in Visual C++, you can specify any number of additional read-only header files as Read-Only Symbol Directives. The "read-only" restriction means that when you add a new resource in the .RC file, you can use a symbol defined in the read-only header file; but if you delete the resource, the symbol still remains defined in the read-only header file. You cannot change the numeric value assigned to a read-only symbol. +By default, Visual Studio always names the corresponding header file `RESOURCE.H`, regardless of the name of the resource file (for example, `MYAPP.RC`). The **Symbol Header File:** section in the **Resource Includes** dialog in Visual Studio, lets you change the name of this header file. Enter a new file name in the section's edit box. -### Compile-Time Directives +> [!NOTE] +> resource files not located in the same directory as the `.RC` file must prepend a relative path with escaped-'\\' to be read properly. + +#### Read-Only Symbol Directives + +Although Visual Studio only edits one header file for any given `.RC` file, Visual Studio supports references to symbols defined in additional read-only header files. The **Read-Only Symbol Directives:** section in the **Resource Includes** dialog lets you specify any number of additional read-only header files as Read-Only Symbol Directives. The "read-only" restriction means that when you add a new resource in the `.RC` file, you can use a symbol defined in the read-only header file. However, if you delete the resource, the symbol still remains defined in the read-only header file. You can't change the numeric value assigned to a read-only symbol. + +#### Compile-Time Directives -Visual C++ also supports nesting of resource files, where one .RC file is #include'd within another. When you edit a given .RC file using Visual C++, any resources in the #include'd files are not visible. But when you compile the .RC file, the #include'd files are also compiled. Using the **Resource Includes** command from the **View** menu in Visual C++, you can specify any number of #include'd .RC files as Compile-Time Directives. +Visual Studio also supports nesting of resource files, where one `.RC` file is included within another by using a `#include` directive. When you edit a given `.RC` file using Visual Studio, any resources in the included files aren't visible. But when you compile the `.RC` file, the included files are also compiled. The **Compile-Time Directives:** section in the **Resources Includes** dialog lets you specify any number of `.RC` files to include as Compile-Time Directives. -Note what happens if you read into Visual C++ an .RC file that #include's another .RC file that is *not* specified as a Compile-Time Directive. This situation might arise when you bring to Visual C++ an .RC file that you had been previously maintaining manually with a text editor. When Visual C++ reads the #include'd .RC file, it merges the #include'd resources into the parent .RC file. When you save the parent .RC file, the #include statement, in effect, will be replaced by the #include'd resources. If you do not want this merge to happen, you should remove the #include statement from the parent .RC file *prior* to reading it into Visual C++; then using Visual C++, add back the same #include statement as a Compile-Time Directive. +Note what happens if you read into Visual Studio an `.RC` file that includes another `.RC` file that isn't* specified as a Compile-Time Directive. This situation might arise when you bring to Visual Studio an `.RC` file that you had been previously maintaining manually with a text editor. When Visual Studio reads the included `.RC` file, it merges the included resources into the parent `.RC` file. When you save the parent `.RC` file, the `#include` statement, in effect, will be replaced by the included resources. If you don't want this merge to happen, you should remove the `#include` statement from the parent `.RC` file *prior* to reading it into Visual Studio; then using Visual Studio, add back the same `#include` statement as a Compile-Time Directive. -Visual C++ saves in an .RC file the three kinds of above Set Includes information (Symbol Header File, Read-Only Symbol Directives, and Compile-Time Directives) in #include directives *and* in TEXTINCLUDE resources. The TEXTINCLUDE resources, an implementation detail that you do not normally need to deal with, are explained in [How Visual C++ Manages Set Includes Information](#_mfcnotes_tn035_set_includes). +Visual Studio saves in an `.RC` file the three kinds of above Set Includes information (Symbol Header File, Read-Only Symbol Directives, and Compile-Time Directives) in `#include` directives *and* in `TEXTINCLUDE` resources. The `TEXTINCLUDE` resources, an implementation detail that you don't normally need to deal with, are explained in [How Visual Studio manages set includes information](#_mfcnotes_tn035_set_includes). -## Analysis of AppWizard-Created .RC and .H Files +## Analysis of AppWizard-created `.RC` and `.H` files -Examining the application code produced by AppWizard provides insight into how Visual C++ manages multiple resource files and header files. The code excerpts examined below are from a MYAPP application produced by AppWizard using the default options. +Examining the application code produced by AppWizard provides insight into how Visual Studio manages multiple resource files and header files. The code excerpts examined below are from a `MYAPP` application produced by AppWizard using the default options. An AppWizard-created application uses multiple resource files and multiple header files, as summarized in the diagram below: @@ -81,12 +90,12 @@ An AppWizard-created application uses multiple resource files and multiple heade AFXPRINT.RC ``` -You can view these multiple file relationships using the Visual C++ File/Set Includes command. +You can view these multiple file relationships using the Visual Studio File/Set Includes command. -MYAPP.RC\ -The application resource file that you edit using Visual C++. +`MYAPP.RC`\ +The application resource file that you edit using Visual Studio. -RESOURCE.H is the application-specific header file. It is always named RESOURCE.H by AppWizard, consistent with Visual C++'s default naming of the header file. The #include for this header file is the first statement in the resource file (MYAPP.RC): +`RESOURCE.H` is the application-specific header file. It's always named `RESOURCE.H` by AppWizard, consistent with Visual Studio's default naming of the header file. The `#include` for this header file is the first statement in the resource file (`MYAPP.RC`): ```rc //Microsoft Visual C++ generated resource script @@ -94,22 +103,22 @@ RESOURCE.H is the application-specific header file. It is always named RESOURCE. #include "resource.h" ``` -RES\MYAPP.RC2\ -Contains resources that will not be edited by Visual C++ but will be included in the final compiled .EXE file. AppWizard creates no such resources by default, since Visual C++ can edit all of the standard resources, including the version resource (a new feature in this release). An empty file is generated by AppWizard in case you wish to add your own custom formatted resources to this file. +`RES\MYAPP.RC2`\ +Contains resources that won't be edited by Visual Studio but will be included in the final compiled `.EXE` file. AppWizard creates no such resources by default, since Visual Studio can edit all of the standard resources, including the version resource (a new feature in this release). An empty file is generated by AppWizard in case you wish to add your own custom formatted resources to this file. -If you use custom formatted resources, you can add them to RES\MYAPP.RC2 and edit them using the Visual C++ text editor. +If you use custom formatted resources, you can add them to `RES\MYAPP.RC2` and edit them using the Visual Studio text editor. -AFXRES.RC and AFXPRINT.RC contain standard resources required by certain features of the framework. Like RES\MYAPP.RC2, these two framework-provided resource files are #include'd at the end of MYAPP.RC, and they are specified in the Compile-Time Directives of the Set Includes dialog box. Thus, you do not directly view or edit these framework resources while you edit MYAPP.RC in Visual C++, but they are compiled into the application's binary .RES file and final .EXE file. For more information on the standard framework resources, including procedures for modifying them, see [Technical Note 23](../mfc/tn023-standard-mfc-resources.md). +`AFXRES.RC` and `AFXPRINT.RC` contain standard resources required by certain features of the framework. Like `RES\MYAPP.RC2`, these two framework-provided resource files are included at the end of `MYAPP.RC`, and they're specified in the Compile-Time Directives of the Set Includes dialog box. Thus, you don't directly view or edit these framework resources while you edit `MYAPP.RC` in Visual Studio, but they're compiled into the application's binary `.RES` file and final `.EXE` file. For more information on the standard framework resources, including procedures for modifying them, see [Technical Note 23](../mfc/tn023-standard-mfc-resources.md). -AFXRES.H defines standard symbols, such as `ID_FILE_NEW`, used by the framework and specifically used in AFXRES.RC. AFXRES.H also #include's WINRES.H, which contains a subset of WINDOWS.H that are needed by Visual C++ generated .RC files as well as AFXRES.RC. The symbols defined in AFXRES.H are available as you edit the application resource file (MYAPP.RC). For example, `ID_FILE_NEW` is used for the File New menu item in MYAPP.RC's menu resource. You cannot change or delete these framework-defined symbols. +`AFXRES.H` defines standard symbols, such as `ID_FILE_NEW`, used by the framework and specifically used in `AFXRES.RC`. `AFXRES.H` also uses `#include` to include `WINRES.H`, which contains a subset of `WINDOWS.H` that's needed by Visual Studio generated `.RC` files and `AFXRES.RC`. The symbols defined in `AFXRES.H` are available as you edit the application resource file (`MYAPP.RC`). For example, `ID_FILE_NEW` is used for the `File` `New` menu item in the `MYAPP.RC` file's menu resource. You can't change or delete these framework-defined symbols. -## Including Additional Header Files +## Including additional header files -The AppWizard-created application includes only two header files: RESOURCE.H and AFXRES.H. Only RESOURCE.H is application-specific. You may need to include additional read-only header files in the following cases: +The AppWizard-created application includes only two header files: `RESOURCE.H` and `AFXRES.H`. Only `RESOURCE.H` is application-specific. You may need to include additional read-only header files in the following cases: The header file is provided by an external source, or you want to share the header file among multiple projects or multiple parts of the same project. -The header file has formatting and comments that you do not want Visual C++ to change or filter out when it saves the file. For example, maybe you want to preserve #define's that use symbolic arithmetic such as: +The header file has formatting and comments that you don't want Visual Studio to change or filter out when it saves the file. For example, maybe you want to preserve #define's that use symbolic arithmetic such as: ```h #define RED 0 @@ -121,7 +130,7 @@ The header file has formatting and comments that you do not want Visual C++ to c #define ID_GREEN_BUTTON (ID_COLOR_BUTTON + GREEN) ``` -You can include additional read-only header files by using the **Resource Includes** command to specify the #include statement as a second Read-Only Symbol Directive, as in: +You can include additional read-only header files by using the **Resource Includes** command to specify the `#include` statement as a second Read-Only Symbol Directive, as in: ```rc #include "afxres.h" @@ -143,9 +152,9 @@ The new file relationship diagram now looks like this: AFXPRINT.RC ``` -## Sharing a Header File Between Two .RC Files +## Sharing a header file between two `.RC` files -You may want to share a header file between two .RC files that are in different projects, or possibly the same project. To do so, simply apply the Read-Only Directives technique described above to both .RC files. In the case where the two .RC files are for different applications (different projects), the result is illustrated in the following diagram: +You may want to share a header file between two `.RC` files that are in different projects, or possibly the same project. To do so, apply the Read-Only Directives technique described above to both `.RC` files. In the case where the two `.RC` files are for different applications (different projects), the result is illustrated in the following diagram: ```Diagram RESOURCE.H AFXRES.H RESOURCE.H @@ -159,26 +168,26 @@ RES\MYAPP1.RC2 AFXRES.RC RES\MYAPP2.RC2 AFXPRINT.RC ``` -The case where the second header file is shared by two .RC files in the same application (project) is discussed below. +The case where the second header file is shared by two `.RC` files in the same application (project) is discussed below. -## Using Multiple Resource Files in the Same Project +## Using multiple resource files in the same project -Visual C++ and the Resource Compiler support multiple .RC files in the same project through #include's of one .RC file within another. Multiple nesting is allowed. There are various reasons to split your project's resources into multiple .RC files: +Visual Studio and the Resource Compiler support multiple `.RC` files in the same project through `#include` directives that include one `.RC` file within another. Multiple nesting is allowed. There are various reasons to split your project's resources into multiple `.RC` files: -- It is easier to manage a large number of resources among multiple project team members if you split the resources into multiple .RC files. If you use a source control management package for checking out files and checking in changes, splitting the resources into multiple .RC files will give you finer control over managing changes to resources. +- It's easier to manage a large number of resources among multiple project team members if you split the resources into multiple `.RC` files. If you use a source control management package for checking out files and checking in changes, splitting the resources into multiple `.RC` files will give you finer control over managing changes to resources. -- If you want to use preprocessor directives, such as #ifdef, #endif, and #define, for portions of your resources, you must isolate them in read-only resources that will be compiled by the Resource Compiler. +- If you want to use preprocessor directives, such as `#ifdef`, `#endif`, and `#define`, for portions of your resources, you must isolate them in read-only resources that will be compiled by the Resource Compiler. -- Component .RC files will load and save faster in Visual C++ than one composite .RC file. +- Component `.RC` files will load and save faster in Visual Studio than one composite `.RC` file. -- If you want to maintain a resource with a text editor in a human-readable form, you should keep it in a .RC file separate from the one Visual C++ edits. +- If you want to maintain a resource with a text editor in a human-readable form, you should keep it in a `.RC` file separate from the one Visual Studio edits. -- If you need to keep a user-defined resource in a binary or text form that is interpretable by another specialized data editor, then you should keep it in a separate .RC file so Visual C++ does not change the format to hexadecimal data. The .WAV (sound) file resources in the MFC Advanced Concepts sample [SPEAKN](../overview/visual-cpp-samples.md) are a good example. +- If you need to keep a user-defined resource in a binary or text form that is interpretable by another specialized data editor, then you should keep it in a separate `.RC` file so Visual Studio doesn't change the format to hexadecimal data. The `.WAV` (sound) file resources in the MFC Advanced Concepts sample [SPEAKN](../overview/visual-cpp-samples.md) are a good example. -You can #include a SECOND.RC in the Compile-Time Directives in the Set Includes dialog box: +You can include `SECOND.RC` in the Compile-Time Directives in the Set Includes dialog box: ```h -#include "res\myapp.rc2" // non-Visual C++ edited resources +#include "res\myapp.rc2" // non-Visual Studio edited resources #include "second.rc" // THE SECOND .RC FILE #include "afxres.rc" // Standard components @@ -200,29 +209,29 @@ The result is illustrated in the following diagram: AFXPRINT.RC ``` -Using Compile-Time Directives, you can organize your Visual C++-editable and non-editable resources into multiple .RC files, where the "master" MYAPP.RC does nothing but #include the other .RC files. If you are using a Visual Studio C++ project .MAK file, then you should include the "master" .RC file in the project so that all the #include'd resources are compiled with your application. +Using Compile-Time Directives, you can organize your Visual Studio-editable and non-editable resources into multiple `.RC` files, where the main `MYAPP.RC` does nothing but `#include` the other `.RC` files. If you're using a Visual Studio C++ project `.MAK` file, then you should include the main `.RC` file in the project so that all the included resources are compiled with your application. -## Enforcement of Noneditable Visual C++ Files +## Enforcement of non-editable Visual Studio files -The AppWizard-created RES\MYAPP.RC2 file is an example of a file that contains resources that you do *not* want to accidentally read into Visual C++ and then write it back out with loss of formatting information. To protect against this, place the following lines in the beginning of the RES\MYAPP.RC2 file: +The AppWizard-created `RES\MYAPP.RC2` file is an example of a file that contains resources that you don't want to accidentally read into Visual Studio and then write back out with loss of formatting information. To protect against this problem, place the following lines in the beginning of the `RES\MYAPP.RC2` file: ```rc2 #ifdef APSTUDIO_INVOKED - #error this file is not editable by Visual C++ + #error this file is not editable by Visual Studio #endif //APSTUDIO_INVOKED ``` -When Visual C++ compiles the .RC file, it defines `APSTUDIO_INVOKED` as well as `RC_INVOKED`. If the AppWizard-created file structure is corrupted and Visual C++ reads the #error line above, it reports a fatal error and abort the reading of the .RC file. +When Visual Studio compiles the `.RC` file, it defines both `APSTUDIO_INVOKED` and `RC_INVOKED`. If the AppWizard-created file structure is corrupted and Visual Studio reads the #error line above, it reports a fatal error and aborts the reading of the `.RC` file. -## Managing Symbols Shared by Multiple Visual C++-Edited .RC Files +## Managing symbols shared by multiple Visual Studio-edited `.RC` files -Two issues arise when you split up your resources into multiple .RC files that you want to edit separately in Visual C++: +Two issues arise when you split up your resources into multiple `.RC` files that you want to edit separately in Visual Studio: -- You might want to share the same symbols across multiple .RC files. +- You might want to share the same symbols across multiple `.RC` files. -- You need to help Visual C++ avoid assigning the same ID numeric values to distinct resources (symbols). +- You need to help Visual Studio avoid assigning the same ID numeric values to distinct resources (symbols). -The following diagram illustrates an organization of .RC and .H files that deals with the first issue: +The following diagram illustrates an organization of `.RC` and `.H` files that deals with the first issue: ```Diagram MYAPP.RC @@ -234,13 +243,13 @@ MYSTRS.H / MYSHARED.H \ MYMENUS.H MYSTRS.RC MYMENUS.RC ``` -In this example, string resources are kept in one resource file, MYSTRS.RC, and menus are kept in another, MYMENUS.RC. Some symbols, such as for commands, may need to be shared between the two files. For example, a ID_TOOLS_SPELL may be the menu command ID for the Spell item in a Tools menu; and it may also be the string ID of the command prompt displayed by the framework in the application's main window status bar. +In this example, string resources are kept in one resource file, `MYSTRS.RC`, and menus are kept in another, `MYMENUS.RC`. Some symbols, such as for commands, may need to be shared between the two files. For example, a `ID_TOOLS_SPELL` may be the menu command ID for the Spell item in a Tools menu; and it may also be the string ID of the command prompt displayed by the framework in the application's main window status bar. -The ID_TOOLS_SPELL symbol is kept in the shared header file, MYSHARED.H. You maintain this shared header file manually with a text editor; Visual C++ does not directly edit it. In the two resource files MYSTRS.RC and MYMENUS.RC, you specify #include MYSHARED.H in the Read-Only Directives for MYAPP.RC, using the **Resource Includes** command, as described earlier. +The `ID_TOOLS_SPELL` symbol is kept in the shared header file, `MYSHARED.H`. You maintain this shared header file manually with a text editor; Visual Studio doesn't directly edit it. In the two resource files `MYSTRS.RC` and `MYMENUS.RC`, you specify `#include "MYSHARED.H"` in the Read-Only Directives for `MYAPP.RC`, using the **Resource Includes** command, as described earlier. -It is most convenient to anticipate a symbol you will share before you attempt to use it to identify any resource. Add the symbol to the shared header file and, if you have not already #include'd the shared header file in the Read-Only Directives for the .RC file, do so before using the symbol. If you did not anticipate sharing the symbol in this way, then you will have to manually (using a text editor) move the #define statement for the symbol from, say, MYMENUS.H to MYSHARED.H before using it in MYSTRS.RC. +It's most convenient to anticipate a symbol you'll share before you attempt to use it to identify any resource. Add the symbol to the shared header file and, if you haven't already included the shared header file in the Read-Only Directives for the `.RC` file, do so before using the symbol. If you didn't anticipate sharing the symbol in this way, then you'll have to manually (using a text editor) move the #define statement for the symbol from, say, `MYMENUS.H` to `MYSHARED.H` before using it in `MYSTRS.RC`. -When you manage symbols in multiple .RC files, you also must help Visual C++ avoid assigning the same ID numeric values to distinct resources (symbols). For any given .RC file, Visual C++ incrementally assigns IDs in each of four ID domains. Between editing sessions, Visual C++ keeps track of the last ID it assigned in each of the domains in the symbol header file for the .RC file. Here is what the APS_NEXT values are for an empty (new) .RC file: +When you manage symbols in multiple `.RC` files, you also must help Visual Studio avoid assigning the same ID numeric values to distinct resources (symbols). For any given `.RC` file, Visual Studio incrementally assigns IDs in each of four ID domains. Between editing sessions, Visual Studio keeps track of the last ID it assigned in each of the domains in the Symbol Header File for the `.RC` file. Here's what the `APS_NEXT` values are for an empty (new) `.RC` file: ```rc #define _APS_NEXT_RESOURCE_VALUE 101 @@ -257,11 +266,11 @@ When you manage symbols in multiple .RC files, you also must help Visual C++ avo `_APS_NEXT_SYMED_VALUE` is the next symbol value that will be issued when you manually assign a symbol value using the New command in the Symbol Browser. -Visual C++ starts with slightly higher values that the lowest legal value when creating a new .RC file. AppWizard will also initialize these values to something more appropriate for MFC applications. For more information about ID value ranges, see [Technical Note 20](../mfc/tn020-id-naming-and-numbering-conventions.md). +Visual Studio starts with slightly higher values that the lowest legal value when creating a new `.RC` file. AppWizard will also initialize these values to something more appropriate for MFC applications. For more information about ID value ranges, see [Technical Note 20](../mfc/tn020-id-naming-and-numbering-conventions.md). -Now every time you create a new resource file, even in the same project, Visual C++ defines the same `_APS_NEXT_` values. This means that if you add, say, multiple dialogs in two different .RC files, it is highly likely that the same #define value will be assigned to different dialogs. For example, IDD_MY_DLG1 in the first .RC file might be assigned the same number, 101, as IDD_MY_DLG2 in a second .RC file. +Now every time you create a new resource file, even in the same project, Visual Studio defines the same `_APS_NEXT_` values. It means that if you add, say, multiple dialogs in two different `.RC` files, it's highly likely that the same #define value will be assigned to different dialogs. For example, `IDD_MY_DLG1` in the first `.RC` file might be assigned the same number, 101, as `IDD_MY_DLG2` in a second `.RC` file. -To avoid this, you should reserve a separate numeric range for each of the four domains of IDs in the respective .RC files. Do this by manually updating the `_APS_NEXT` values in each of the .RC files **before** you start adding resources. For example, if the first .RC file uses the default `_APS_NEXT` values, then you might want to assign the following `_APS_NEXT` values to the second .RC file: +To avoid this issue, you should reserve a separate numeric range for each of the four domains of IDs in the respective `.RC` files. Set the ranges by manually updating the `_APS_NEXT` values in each of the `.RC` files **before** you start adding resources. For example, if the first `.RC` file uses the default `_APS_NEXT` values, then you might want to assign the following `_APS_NEXT` values to the second `.RC` file: ```rc #define _APS_NEXT_RESOURCE_VALUE 2000 @@ -270,23 +279,23 @@ To avoid this, you should reserve a separate numeric range for each of the four #define _APS_NEXT_SYMED_VALUE 2000 ``` -Of course, it is still possible that Visual C++ will assign so many IDs in the first .RC file that the numeric values start to overlap those reserved for the second .RC file. You should reserve sufficiently large ranges so that this does not happen. +Of course, it's still possible that Visual Studio will assign so many IDs in the first `.RC` file that the numeric values start to overlap the ones reserved for the second `.RC` file. You should reserve sufficiently large ranges so that this collision doesn't happen. -## Managing Dependencies Between .RC, .CPP, and .H Files +## Managing dependencies between `.RC`, `.CPP`, and `.H` files -When Visual C++ saves an .RC file, it also saves symbol changes to the corresponding RESOURCE.H file. Any of your .CPP files that refer to resources in the .RC file must #include the RESOURCE.H file, usually from within your project's master header file. This leads to an undesirable side-effect because of the development environment's internal project management which scans source files for header dependencies. Every time you add a new symbol in Visual C++, all the .CPP files that #include RESOURCE.H would need to be recompiled. +When Visual Studio saves an `.RC` file, it also saves symbol changes to the corresponding `RESOURCE.H` file. Any of your `.CPP` files that refer to resources in the `.RC` file must use `#include` to include the `RESOURCE.H` file, usually from within your project's main header file. This inclusion leads to an undesirable side-effect because of the development environment's internal project management, which scans source files for header dependencies. Every time you add a new symbol in Visual Studio, all the `.CPP` files that have `#include "RESOURCE.H"` directives would need to be recompiled. -Visual C++, circumvents the dependency on RESOURCE.H by including the following comment as the first line of the RESOURCE.H file: +Visual Studio, circumvents the dependency on `RESOURCE.H` by including the following comment as the first line of the `RESOURCE.H` file: ```h //{{NO_DEPENDENCIES}} ``` -The development environment interprets this comment by ignoring the changes to RESOURCE.H so that dependent .CPP files will not need to be recompiled. +The development environment interprets this comment by ignoring the changes to `RESOURCE.H` so that dependent `.CPP` files won't need to be recompiled. -Visual C++ always adds the //{{NO_DEPENDENCIES}} comment line to a .RC file when it saves the file. In some cases, circumventing of the build dependency on RESOURCE.H may lead to run-time errors undetected at link time. For example, if you use the Symbol Browser to change the numeric value assigned to a symbol for a resource, the resource will not be correctly found and loaded at application run-time if the .CPP file referring to the resource is not recompiled. In such cases, you should explicitly recompile any .CPP files that you know are affected by the symbol changes in RESOURCE.H or select **Rebuild All**. If you have the need to frequently change symbol values for a certain group of resources, you will probably find it more convenient and safer to break out these symbols into a separate read-only header file, as described in the above section [Including Additional Header Files](#_mfcnotes_tn035_including). +Visual Studio always adds the `//{{NO_DEPENDENCIES}}` comment line to a `.RC` file when it saves the file. In some cases, circumventing of the build dependency on `RESOURCE.H` may lead to run-time errors undetected at link time. For example, if you use the Symbol Browser to change the numeric value assigned to a symbol for a resource, the resource won't be correctly found and loaded at application run-time if the `.CPP` file referring to the resource isn't recompiled. In such cases, you should explicitly recompile any `.CPP` files that you know are affected by the symbol changes in `RESOURCE.H` or select **Rebuild All**. If you have the need to frequently change symbol values for a certain group of resources, you'll probably find it more convenient and safer to break out these symbols into a separate read-only header file, as described in the above section [Including Additional Header Files](#_mfcnotes_tn035_including). -## How Visual C++ Manages Set Includes Information +## How Visual Studio manages Set Includes information As discussed above, the File menu Set Includes command lets you specify three types of information: @@ -296,29 +305,29 @@ As discussed above, the File menu Set Includes command lets you specify three ty - Compile-Time Directives -The following describes how Visual C++ maintains this information in a .RC file. You do not need this information to use Visual C++, but it may enhance your understanding so that you can more confidently use the Set Includes feature. +The following table describes how Visual Studio maintains this information in a `.RC` file. You don't need this information to use Visual Studio, but it may enhance your understanding so that you can more confidently use the Set Includes feature. -Each of the above three types of Set Includes information is stored in the .RC file in two forms: (1) as #include or other directives interpretable by the Resource Compiler, and (2) as special TEXTINCLUDE resources interpretable only by Visual C++. +Each of the above three types of Set Includes information is stored in the `.RC` file in two forms: (1) as `#include` or other directives interpretable by the Resource Compiler, and (2) as special `TEXTINCLUDE` resources interpretable only by Visual Studio. -The purpose of the TEXTINCLUDE resource is to safely store Set Include information in a form that is readily presentable in Visual C++'s **Set Includes** dialog box. TEXTINCLUDE is a *resource type* defined by Visual C++. Visual C++ recognizes three specific TEXTINCLUDE resources that have the resource identification numbers 1, 2 and 3: +The purpose of the `TEXTINCLUDE` resource is to safely store Set Include information in a form that is readily presentable in Visual Studio's **Set Includes** dialog box. `TEXTINCLUDE` is a *resource type* defined by Visual Studio. Visual Studio recognizes three specific `TEXTINCLUDE` resources that have the resource identification numbers 1, 2 and 3: -|TEXTINCLUDE resource ID|Type of Set Includes information| +|`TEXTINCLUDE` resource ID|Type of Set Includes information| |-----------------------------|--------------------------------------| |1|Symbol Header File| |2|Read-Only Symbol Directives| |3|Compile-Time Directives| -Each of the three types of Set Includes information is illustrated by the default MYAPP.RC and RESOURCE.H files created by AppWizard, as described below. The extra \0 and "" tokens between BEGIN and END blocks are required by the RC syntax to specify zero terminated strings and the double quote character respectively. +Each of the three types of Set Includes information is illustrated by the default `MYAPP.RC` and `RESOURCE.H` files created by AppWizard, as described below. The extra `\0` and `""` tokens between `BEGIN` and `END` blocks are required by the RC syntax to specify zero terminated strings and the double quote character respectively. ### Symbol Header File -The form of the Symbol Header File information interpreted by the Resource Compiler is simply a #include statement: +The form of the Symbol Header File information interpreted by the Resource Compiler is simply a `#include` statement: ```rc #include "resource.h" ``` -The corresponding TEXTINCLUDE resource is: +The corresponding `TEXTINCLUDE` resource is: ```rc 1 TEXTINCLUDE DISCARDABLE @@ -329,13 +338,13 @@ END ### Read-Only Symbol Directives -Read-Only Symbol Directives are included at the top of MYAPP.RC in the following form interpretable by the Resource Compiler: +Read-Only Symbol Directives are included at the top of `MYAPP.RC` in the following form interpretable by the Resource Compiler: ```rc #include "afxres.h" ``` -The corresponding TEXTINCLUDE resource is: +The corresponding `TEXTINCLUDE` resource is: ```rc 2 TEXTINCLUDE DISCARDABLE @@ -347,7 +356,7 @@ END ### Compile-Time Directives -Compile-Time Directives are included at the end of MYAPP.RC in the following form interpretable by the Resource Compiler: +Compile-Time Directives are included at the end of `MYAPP.RC` in the following form interpretable by the Resource Compiler: ```rc #ifndef APSTUDIO_INVOKED @@ -355,21 +364,21 @@ Compile-Time Directives are included at the end of MYAPP.RC in the following for // // From TEXTINCLUDE 3 // -#include "res\myapp.rc2" // non-Visual C++ edited resources +#include "res\myapp.rc2" // non-Visual Studio edited resources #include "afxres.rc" // Standard components #include "afxprint.rc" // printing/print preview resources #endif // not APSTUDIO_INVOKED ``` -The #ifndef APSTUDIO_INVOKED directive instructs Visual C++ to skip over Compile-Time Directives. +The `#ifndef APSTUDIO_INVOKED` directive instructs Visual Studio to skip over Compile-Time Directives. -The corresponding TEXTINCLUDE resource is: +The corresponding `TEXTINCLUDE` resource is: ```rc 3 TEXTINCLUDE DISCARDABLE BEGIN -"#include ""res\myapp.rc2"" // non-Visual C++ edited resources\r\n" +"#include ""res\myapp.rc2"" // non-Visual Studio edited resources\r\n" "\r\n" "#include ""afxres.rc"" // Standard components\r\n" "#include ""afxprint.rc"" // printing/print preview resources\r\n" diff --git a/docs/mfc/tn036-using-cformview-with-appwizard-and-classwizard.md b/docs/mfc/tn036-using-cformview-with-appwizard-and-classwizard.md index 4d3569e13ae..9e8261d1fbe 100644 --- a/docs/mfc/tn036-using-cformview-with-appwizard-and-classwizard.md +++ b/docs/mfc/tn036-using-cformview-with-appwizard-and-classwizard.md @@ -3,10 +3,12 @@ description: "Learn more about: TN036: Using CFormView with AppWizard and ClassW title: "TN036: Using CFormView with AppWizard and ClassWizard" ms.date: "11/04/2016" helpviewer_keywords: ["TN036"] -ms.assetid: dd54053f-ae80-4d23-9180-c7d07ddf2290 --- # TN036: Using CFormView with AppWizard and ClassWizard +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This technical note described how to modify an AppWizard generated application so that it used a `CFormView` instead of the default `CView` as its main view class. This is supported directly with this version of Visual C++. ## See also diff --git a/docs/mfc/tn037-multithreaded-mfc-2-1-applications.md b/docs/mfc/tn037-multithreaded-mfc-2-1-applications.md index 8b1d54b02af..ac6bb8c4a7e 100644 --- a/docs/mfc/tn037-multithreaded-mfc-2-1-applications.md +++ b/docs/mfc/tn037-multithreaded-mfc-2-1-applications.md @@ -3,10 +3,12 @@ description: "Learn more about: TN037: Multithreaded MFC 2.1 Applications" title: "TN037: Multithreaded MFC 2.1 Applications" ms.date: "11/04/2016" helpviewer_keywords: ["TN037"] -ms.assetid: 05ee204c-700a-4c40-957c-dc2d0db1249d --- # TN037: Multithreaded MFC 2.1 Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This technical note originally described the limitations of multithreaded programs with MFC 2.1, originally provided with Visual C++ 1.0 for Windows NT. MFC 3.0 supports multithreading directly and is documented. See that reference for more information. ## See also diff --git a/docs/mfc/tn038-mfc-ole-iunknown-implementation.md b/docs/mfc/tn038-mfc-ole-iunknown-implementation.md index a7e7375d137..5389681a074 100644 --- a/docs/mfc/tn038-mfc-ole-iunknown-implementation.md +++ b/docs/mfc/tn038-mfc-ole-iunknown-implementation.md @@ -1,12 +1,14 @@ --- -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 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. @@ -518,7 +520,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/tn039-mfc-ole-automation-implementation.md b/docs/mfc/tn039-mfc-ole-automation-implementation.md index f0293d78dae..07218539d2f 100644 --- a/docs/mfc/tn039-mfc-ole-automation-implementation.md +++ b/docs/mfc/tn039-mfc-ole-automation-implementation.md @@ -3,10 +3,12 @@ description: "Learn more about: TN039: MFC/OLE Automation Implementation" title: "TN039: MFC-OLE Automation Implementation" ms.date: "06/28/2018" helpviewer_keywords: ["MFC, COM support", "IDispatch interface", "MFC, OLE DB and", "TN039", "Automation, MFC COM interface entry points"] -ms.assetid: 765fa3e9-dd54-4f08-9ad2-26e0546ff8b6 --- # TN039: MFC/OLE Automation Implementation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. @@ -85,7 +87,7 @@ The Z property is given a **DISPID** with a zero **HIWORD** since it is defined ## Advanced MFC Dispatch Map Features -There are a number of additional features that ClassWizard does not support with this release of Visual C++. ClassWizard supports `DISP_FUNCTION`, `DISP_PROPERTY`, and `DISP_PROPERTY_EX` which define a method, member variable property, and get/set member function property, respectively. These capabilities are usually all that is needed to create most automation servers. +There are a number of additional features that ClassWizard does not support with this release of Visual Studio. ClassWizard supports `DISP_FUNCTION`, `DISP_PROPERTY`, and `DISP_PROPERTY_EX` which define a method, member variable property, and get/set member function property, respectively. These capabilities are usually all that is needed to create most automation servers. The following additional macros can be used when the ClassWizard supported macros are not adequate: `DISP_PROPERTY_NOTIFY`, and `DISP_PROPERTY_PARAM`. diff --git a/docs/mfc/tn040-mfc-ole-in-place-resizing-and-zooming.md b/docs/mfc/tn040-mfc-ole-in-place-resizing-and-zooming.md index 4feead7b1e8..48d421019bc 100644 --- a/docs/mfc/tn040-mfc-ole-in-place-resizing-and-zooming.md +++ b/docs/mfc/tn040-mfc-ole-in-place-resizing-and-zooming.md @@ -3,10 +3,12 @@ description: "Learn more about: TN040: MFC/OLE In-Place Resizing and Zooming" title: "TN040: MFC-OLE In-Place Resizing and Zooming" ms.date: "11/04/2016" helpviewer_keywords: ["resizing in-place", "TN040", "zooming and in-place activation", "in-place activation, zooming and resizing"] -ms.assetid: 4d7859bd-0b2e-4254-be62-2735cecf02c6 --- # TN040: MFC/OLE In-Place Resizing and Zooming +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md b/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md index 9838cef62ca..bb8cdf822ee 100644 --- a/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md +++ b/docs/mfc/tn041-mfc-ole1-migration-to-mfc-ole-2.md @@ -3,10 +3,12 @@ description: "Learn more about: TN041: MFC/OLE1 Migration to MFC/OLE 2" title: "TN041: MFC-OLE1 Migration to MFC-OLE 2" ms.date: "10/18/2018" helpviewer_keywords: ["OLE1 [MFC]", "migrating OLE1 to OLE2", "migration [MFC], OLE1 to OLE2", "OLE2 [MFC]", "porting OLE1 to OLE2", "converting OLE1 to OLE2", "upgrading Visual C++ applications [MFC], OLE1 to OLE2", "TN041"] -ms.assetid: 67f55552-4b04-4ddf-af0b-4d9eaf5da957 --- # TN041: MFC/OLE1 Migration to MFC/OLE 2 +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. @@ -276,7 +278,7 @@ At this point, OCLIENT is a functional OLE container application. It is possible One of the most interesting features of OLE is in-place activation (or "Visual Editing"). This feature allows the server application to take over portions of the container's user interface to provided a more seamless editing interface for the user. To implement in-place activation to OCLIENT, some special resources need to be added, as well as some additional code. These resources and the code are normally provided by AppWizard — in fact, much of the code here was borrowed directly from a fresh AppWizard application with "Container" support. -First of all, it is necessary to add a menu resource to be used when there is an item which is in-place active. You can create this extra menu resource in Visual C++ by copying the IDR_OCLITYPE resource and removing all but the File and Window pop-ups. Two separator bars are inserted between the File and Window pop-ups to indicate the separation of groups (it should look like: `File || Window`). For more information on what these separators mean and how the server and container menus are merged see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). +First of all, it is necessary to add a menu resource to be used when there is an item which is in-place active. You can create this extra menu resource in Visual Studio by copying the IDR_OCLITYPE resource and removing all but the File and Window pop-ups. Two separator bars are inserted between the File and Window pop-ups to indicate the separation of groups (it should look like: `File || Window`). For more information on what these separators mean and how the server and container menus are merged see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). Once you have these menus created, you need to let the framework know about them. This is done by calling `CDocTemplate::SetContainerInfo` for the document template before you add it to the document template list in your InitInstance. The new code to register the document template looks like this: @@ -292,7 +294,7 @@ pTemplate->SetContainerInfo(IDR_OLECLITYPE_INPLACE); AddDocTemplate(pTemplate); ``` -The IDR_OLECLITYPE_INPLACE resource is the special in-place resource created in Visual C++. +The IDR_OLECLITYPE_INPLACE resource is the special in-place resource created in Visual Studio. To enable in-place activation, there are some things that need to change in both the `CView` (CMainView) derived class as well as the `COleClientItem` derived class (CRectItem). All of these overrides are provided by AppWizard and most of the implementation will come directly from a default AppWizard application. @@ -338,7 +340,7 @@ BOOL CRectItem::OnChangeItemPosition(const CRect& rectPos) At this point, there is enough code to allow an item to be in-place activated and to deal with sizing and moving the item when it is active, but no code will allow the user to exit the editing session. Although some servers will provide this functionality themselves by handling the escape key, it is suggested that containers provide two ways to deactivate an item: (1) by clicking outside the item, and (2) by pressing the ESCAPE key. -For the ESCAPE key, add an accelerator with Visual C++ that maps the VK_ESCAPE key to a command, ID_CANCEL_EDIT is added to the resources. The handler for this command follows: +For the ESCAPE key, add an accelerator with Visual Studio that maps the VK_ESCAPE key to a command, ID_CANCEL_EDIT is added to the resources. The handler for this command follows: ```cpp // The following command handler provides the standard @@ -512,7 +514,7 @@ BOOL COLEServerApp::InitInstance() You will notice that the code above refers to a new resource ID, IDR_HIERSVRTYPE_SRVR_EMB. This is the menu resource to be used when a document that is embedded in another container is edited. In MFC/OLE1 the menu items specific to editing an embedded item were modified on the fly. Using an entirely different menu structure when editing an embedded item instead of editing a file-based document makes it much easier to provide different user interfaces for these two separate modes. As you'll see later, an entirely separate menu resource is used when editing an embedded object in-place. -To create this resource, load the resource script into Visual C++ and copy the existing IDR_HIERSVRTYPE menu resource. Rename the new resource to IDR_HIERSVRTYPE_SRVR_EMB (this is the same naming convention that AppWizard uses). Next change "File Save" to "File Update"; give it command ID ID_FILE_UPDATE. Also change "File Save As" to "File Save Copy As"; give it command ID ID_FILE_SAVE_COPY_AS. The framework provides the implementation of both of these commands. +To create this resource, load the resource script into Visual Studio and copy the existing IDR_HIERSVRTYPE menu resource. Rename the new resource to IDR_HIERSVRTYPE_SRVR_EMB (this is the same naming convention that AppWizard uses). Next change "File Save" to "File Update"; give it command ID ID_FILE_UPDATE. Also change "File Save As" to "File Save Copy As"; give it command ID ID_FILE_SAVE_COPY_AS. The framework provides the implementation of both of these commands. ```Output \hiersvr\svritem.h(60) : error C2433: 'OLESTATUS' : 'virtual' not permitted on data declarations @@ -629,9 +631,9 @@ To add "Visual Editing" (or in-place activation) to this server application, the - You need to tell the framework about these special resources and classes. -The menu resource is easy to create. Run Visual C++, copy the menu resource IDR_HIERSVRTYPE to a menu resource called IDR_HIERSVRTYPE_SRVR_IP. Modify the menu so that only the Edit and Help menu popups are left. Add two separators to the menu in between the Edit and Help menus (it should look like: `Edit || Help`). For more information on what these separators mean and how the server and container menus are merged, see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). +The menu resource is easy to create. Run Visual Studio, copy the menu resource IDR_HIERSVRTYPE to a menu resource called IDR_HIERSVRTYPE_SRVR_IP. Modify the menu so that only the Edit and Help menu popups are left. Add two separators to the menu in between the Edit and Help menus (it should look like: `Edit || Help`). For more information on what these separators mean and how the server and container menus are merged, see [Menus and Resources: Menu Merging](../mfc/menus-and-resources-menu-merging.md). -The bitmap for the subset toolbar can be easily created by copying the one from a fresh AppWizard generated application with a "Server" option checked. This bitmap can then be imported into Visual C++. Be sure to give the bitmap an ID of IDR_HIERSVRTYPE_SRVR_IP. +The bitmap for the subset toolbar can be easily created by copying the one from a fresh AppWizard generated application with a "Server" option checked. This bitmap can then be imported into Visual Studio. Be sure to give the bitmap an ID of IDR_HIERSVRTYPE_SRVR_IP. The class derived from `COleIPFrameWnd` can be copied from an AppWizard generated application with server support as well. Copy both files, IPFRAME.CPP and IPFRAME.H and add them to the project. Make sure that the `LoadBitmap` call refers to IDR_HIERSVRTYPE_SRVR_IP, the bitmap created in the previous step. diff --git a/docs/mfc/tn042-odbc-driver-developer-recommendations.md b/docs/mfc/tn042-odbc-driver-developer-recommendations.md index 67507a46417..50e12f2ed4f 100644 --- a/docs/mfc/tn042-odbc-driver-developer-recommendations.md +++ b/docs/mfc/tn042-odbc-driver-developer-recommendations.md @@ -4,10 +4,12 @@ title: "TN042: ODBC Driver Developer Recommendations" ms.date: "11/04/2016" f1_keywords: ["vc.odbc"] helpviewer_keywords: ["ODBC drivers [MFC], writing", "databases [MFC], ODBC", "TN042"] -ms.assetid: ecc6b5d9-f480-4582-9e22-8309fe561dad --- # TN042: ODBC Driver Developer Recommendations +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn043-rfx-routines.md b/docs/mfc/tn043-rfx-routines.md index 9c22c0478d5..9ce9eb78ffb 100644 --- a/docs/mfc/tn043-rfx-routines.md +++ b/docs/mfc/tn043-rfx-routines.md @@ -4,10 +4,12 @@ title: "TN043: RFX Routines" ms.date: "06/28/2018" f1_keywords: ["RFX"] helpviewer_keywords: ["RFX (record field exchange), architecture", "TN043", "RFX (record field exchange)"] -ms.assetid: f552d0c1-2c83-4389-b472-42c9940aa713 --- # TN043: RFX Routines +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn044-mfc-support-for-dbcs.md b/docs/mfc/tn044-mfc-support-for-dbcs.md index d20373e0d56..a49ca84591f 100644 --- a/docs/mfc/tn044-mfc-support-for-dbcs.md +++ b/docs/mfc/tn044-mfc-support-for-dbcs.md @@ -3,10 +3,12 @@ description: "Learn more about: TN044: MFC Support for DBCS" title: "TN044: MFC Support for DBCS" ms.date: "11/04/2016" helpviewer_keywords: ["TN044"] -ms.assetid: 8160bb2a-012d-4c5a-b05c-91ee6d4ca4cb --- # TN044: MFC Support for DBCS +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This technical note described the support in MFC for "double-byte character sets" or DBCS. This information as well as information on MFC's support for UNICODE is now available in the *Class Library Reference*. ## See also diff --git a/docs/mfc/tn045-mfc-database-support-for-long-varchar-varbinary.md b/docs/mfc/tn045-mfc-database-support-for-long-varchar-varbinary.md index 871ed060118..ae8ac6acc8c 100644 --- a/docs/mfc/tn045-mfc-database-support-for-long-varchar-varbinary.md +++ b/docs/mfc/tn045-mfc-database-support-for-long-varchar-varbinary.md @@ -3,10 +3,12 @@ description: "Learn more about: TN045: MFC/Database Support for Long Varchar/Var title: "TN045: MFC-Database Support for Long Varchar-Varbinary" ms.date: "11/04/2016" helpviewer_keywords: ["TN045", "Varbinary data type", "Varchar data type"] -ms.assetid: cf572c35-5275-45b5-83df-5f0e36114f40 --- # TN045: MFC/Database Support for Long Varchar/Varbinary +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn046-commenting-conventions-for-the-mfc-classes.md b/docs/mfc/tn046-commenting-conventions-for-the-mfc-classes.md index 26c2dc119d1..bec24e62f25 100644 --- a/docs/mfc/tn046-commenting-conventions-for-the-mfc-classes.md +++ b/docs/mfc/tn046-commenting-conventions-for-the-mfc-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: TN046: Commenting Conventions for the MFC Classe title: "TN046: Commenting Conventions for the MFC Classes" ms.date: "11/04/2016" helpviewer_keywords: ["TN046"] -ms.assetid: 0d6ff3c9-4a5d-44df-b121-be4b0a649947 --- # TN046: Commenting Conventions for the MFC Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This technical note originally described the conventions used to comment the MFC classes. This information is now covered in [MFC: Using the MFC Source Files](../mfc/using-the-mfc-source-files.md). ## See also diff --git a/docs/mfc/tn047-relaxing-database-transaction-requirements.md b/docs/mfc/tn047-relaxing-database-transaction-requirements.md index 43e0e700c54..51f54a2b31b 100644 --- a/docs/mfc/tn047-relaxing-database-transaction-requirements.md +++ b/docs/mfc/tn047-relaxing-database-transaction-requirements.md @@ -4,10 +4,12 @@ title: "TN047: Relaxing Database Transaction Requirements" ms.date: "11/04/2016" f1_keywords: ["vc.data"] helpviewer_keywords: ["TN047"] -ms.assetid: f93c51cf-a8c0-43d0-aa47-7bcb8333d693 --- # TN047: Relaxing Database Transaction Requirements +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This tech note, which discussed the transaction requirements of the MFC ODBC database classes, is now obsolete. Before MFC 4.2, the database classes required that cursors be preserved on recordsets after a **CommitTrans** or **Rollback** operation. If the ODBC driver and DBMS did not support this level of cursor preservation, then the database classes did not enable transactions. Beginning with MFC 4.2, the database classes have relaxed the restriction of requiring cursor preservation. Transactions will be enabled if the driver supports them. However, you must now check the effect of a **CommitTrans** or **Rollback** operation on open recordsets. See the member functions [CDatabase::GetCursorCommitBehavior](../mfc/reference/cdatabase-class.md#getcursorcommitbehavior) and [CDatabase::GetCursorRollbackBehavior](../mfc/reference/cdatabase-class.md#getcursorrollbackbehavior) for more information. diff --git a/docs/mfc/tn048-writing-odbc-setup-and-administration-programs.md b/docs/mfc/tn048-writing-odbc-setup-and-administration-programs.md index 5c3c307246d..af7fe25e2bf 100644 --- a/docs/mfc/tn048-writing-odbc-setup-and-administration-programs.md +++ b/docs/mfc/tn048-writing-odbc-setup-and-administration-programs.md @@ -3,10 +3,13 @@ description: "Learn more about: TN048: Writing ODBC Setup and Administration Pro title: "TN048: Writing ODBC Setup and Administration Programs for MFC Database Applications" ms.date: "11/04/2016" helpviewer_keywords: ["installing ODBC", "ODBC, installing", "setup, ODBC setup programs", "TN048", "ODBC, and MFC", "MFC, database applications"] -ms.assetid: d456cdd4-0513-4a51-80c0-9132b66115ce +ms.topic: install-set-up-deploy --- # TN048: Writing ODBC Setup and Administration Programs for MFC Database Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn049-mfc-ole-mbcs-to-unicode-translation-layer-mfcans32.md b/docs/mfc/tn049-mfc-ole-mbcs-to-unicode-translation-layer-mfcans32.md index 85033aff5c3..b5125053a59 100644 --- a/docs/mfc/tn049-mfc-ole-mbcs-to-unicode-translation-layer-mfcans32.md +++ b/docs/mfc/tn049-mfc-ole-mbcs-to-unicode-translation-layer-mfcans32.md @@ -3,10 +3,12 @@ description: "Learn more about: TN049: MFC/OLE MBCS to Unicode Translation Layer title: "TN049: MFC-OLE MBCS to Unicode Translation Layer (MFCANS32)" ms.date: "11/04/2016" helpviewer_keywords: ["MFCANS32.DLL", "TN049"] -ms.assetid: c027e30d-8a51-4e28-b215-13fc49b40431 --- # TN049: MFC/OLE MBCS to Unicode Translation Layer (MFCANS32) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note originally described how MFCANS32.DLL provides ANSI interfaces in the primarily Unicode world of 32-bit OLE. This DLL is no longer used by MFC. ## See also diff --git a/docs/mfc/tn050-mfc-ole-common-dialogs-mfcuix32.md b/docs/mfc/tn050-mfc-ole-common-dialogs-mfcuix32.md index 622181cfa4f..e1aefa45288 100644 --- a/docs/mfc/tn050-mfc-ole-common-dialogs-mfcuix32.md +++ b/docs/mfc/tn050-mfc-ole-common-dialogs-mfcuix32.md @@ -3,10 +3,12 @@ description: "Learn more about: TN050: MFC/OLE Common Dialogs (MFCUIx32)" title: "TN050: MFC-OLE Common Dialogs (MFCUIx32)" ms.date: "11/04/2016" helpviewer_keywords: ["MFCUIx32", "TN050"] -ms.assetid: 397c92f7-e7c8-49fb-97bc-f5602ec744b8 --- # TN050: MFC/OLE Common Dialogs (MFCUIx32) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This note originally covered some issues and the future of the OLE common dialogs provided and used by MFC. The OLE common dialogs are now provided as a component built-in to the system (OLEDLG.DLL) and are fully documented in the product documentation. ## See also diff --git a/docs/mfc/tn051-using-ctl3d-now-and-in-the-future.md b/docs/mfc/tn051-using-ctl3d-now-and-in-the-future.md index 2507945e66f..7ce559319cf 100644 --- a/docs/mfc/tn051-using-ctl3d-now-and-in-the-future.md +++ b/docs/mfc/tn051-using-ctl3d-now-and-in-the-future.md @@ -3,10 +3,12 @@ description: "Learn more about: TN051: Using CTL3D Now and in the Future" title: "TN051: Using CTL3D Now and in the Future" ms.date: "11/04/2016" helpviewer_keywords: ["TN051", "CTL3D.DLL", "3D effect"] -ms.assetid: ab517a13-a137-4a60-8039-be92a632b76b --- # TN051: Using CTL3D Now and in the Future +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This technical note, which previously discussed CTL3D and MFC, is now obsolete. The 3D effect for controls is automatically implemented by MFC. ## See also diff --git a/docs/mfc/tn053-custom-dfx-routines-for-dao-database-classes.md b/docs/mfc/tn053-custom-dfx-routines-for-dao-database-classes.md index 5902135a9a4..68d83d09180 100644 --- a/docs/mfc/tn053-custom-dfx-routines-for-dao-database-classes.md +++ b/docs/mfc/tn053-custom-dfx-routines-for-dao-database-classes.md @@ -3,12 +3,14 @@ description: "Learn more about: TN053: Custom DFX Routines for DAO Database Clas title: "TN053: Custom DFX Routines for DAO Database Classes" ms.date: "09/17/2019" helpviewer_keywords: ["MFC, DAO and", "database classes [MFC], DAO", "DAO [MFC], MFC", "DFX (DAO record field exchange) [MFC], custom routines", "TN053", "DAO [MFC], classes", "DFX (DAO record field exchange) [MFC]", "custom DFX routines [MFC]"] -ms.assetid: fdcf3c51-4fa8-4517-9222-58aaa4f25cac --- # TN053: Custom DFX Routines for DAO Database Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] -> DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual C++ environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-templates.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. +> DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual Studio environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-templates.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. This technical note describes the DAO record field exchange (DFX) mechanism. To help understand what is happening in the DFX routines, the `DFX_Text` function will be explained in detail as an example. As an additional source of information to this technical note, you can examine the code for the other the individual DFX functions. You probably will not need a custom DFX routine as often as you might need a custom RFX routine (used with ODBC database classes). diff --git a/docs/mfc/tn054-calling-dao-directly-while-using-mfc-dao-classes.md b/docs/mfc/tn054-calling-dao-directly-while-using-mfc-dao-classes.md index 02a2e7b5061..c39376ef8a7 100644 --- a/docs/mfc/tn054-calling-dao-directly-while-using-mfc-dao-classes.md +++ b/docs/mfc/tn054-calling-dao-directly-while-using-mfc-dao-classes.md @@ -3,12 +3,15 @@ description: "Learn more about: TN054: Calling DAO Directly While Using MFC DAO title: "TN054: Calling DAO Directly While Using MFC DAO Classes" ms.date: "09/17/2019" helpviewer_keywords: ["MFC, DAO and", "passwords [MFC], calling DAO", "security [MFC], DAO", "DAO (Data Access Objects), calling directly", "DAO (Data Access Objects), security", "security [MFC]", "TN054", "DAO (Data Access Objects), and MFC"] -ms.assetid: f7de7d85-8d6c-4426-aa05-2e617c0da957 +ms.custom: sfi-ropc-nochange --- # TN054: Calling DAO Directly While Using MFC DAO Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] -> DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual C++ environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-templates.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. +> DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual Studio environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-templates.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. When using the MFC DAO database classes, there may be situations where it is necessary to use DAO directly. Usually, this will not be the case, but MFC has provided some helper mechanisms to facilitate making direct DAO calls simple when combining the use of the MFC classes with direct DAO calls. Making direct DAO calls to the methods of an MFC-managed DAO object should require only a few lines of code. If you need to create and use DAO objects that are *not* managed by MFC, you will have to do a little more work by actually calling `Release` on the object. This technical note explains when you might want to call DAO directly, what the MFC helpers can do to help you, and how to use the DAO OLE interfaces. Finally, this note provides some sample functions showing how to call DAO directly for DAO security features. diff --git a/docs/mfc/tn055-migrating-mfc-odbc-database-class-applications-to-mfc-dao-classes.md b/docs/mfc/tn055-migrating-mfc-odbc-database-class-applications-to-mfc-dao-classes.md index 4f563326304..8b669381a6b 100644 --- a/docs/mfc/tn055-migrating-mfc-odbc-database-class-applications-to-mfc-dao-classes.md +++ b/docs/mfc/tn055-migrating-mfc-odbc-database-class-applications-to-mfc-dao-classes.md @@ -3,12 +3,14 @@ description: "Learn more about: TN055: Migrating MFC ODBC Database Class Applica title: "TN055: Migrating MFC ODBC Database Class Applications to MFC DAO Classes" ms.date: "09/17/2019" helpviewer_keywords: ["DAO [MFC], migration", "TN055", "migration [MFC], ODBC database applications", "ODBC classes [MFC], DAO classes", "migrating ODBC database applications [MFC]", "porting database applications to DAO", "ODBC [MFC], DAO", "porting ODBC database applications to DAO", "migrating database applications [MFC]"] -ms.assetid: 0f858bd1-e168-4e2e-bcd1-8debd82856e4 --- # TN055: Migrating MFC ODBC Database Class Applications to MFC DAO Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] -> DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual C++ environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-templates.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. +> DAO is used with Access databases and is supported through Office 2013. DAO 3.6 is the final version, and it is considered obsolete. The Visual Studio environment and wizards do not support DAO (although the DAO classes are included and you can still use them). Microsoft recommends that you use [OLE DB Templates](../data/oledb/ole-db-templates.md) or [ODBC and MFC](../data/odbc/odbc-and-mfc.md) for new projects. You should only use DAO in maintaining existing applications. ## Overview diff --git a/docs/mfc/tn056-installation-of-localized-mfc-components.md b/docs/mfc/tn056-installation-of-localized-mfc-components.md index c3257be73fd..48848e726d2 100644 --- a/docs/mfc/tn056-installation-of-localized-mfc-components.md +++ b/docs/mfc/tn056-installation-of-localized-mfc-components.md @@ -3,10 +3,12 @@ description: "Learn more about: TN056: Installation of Localized MFC Components" title: "TN056: Installation of Localized MFC Components" ms.date: "11/04/2016" helpviewer_keywords: ["components [MFC]", "TN056", "resources [MFC], localization", "localization [MFC], MFC resources", "MFC70LOC.DLL", "MFC DLLs [MFC], localizing", "components [MFC], installing", "DLLs [MFC], localizing MFC", "CTL3D32.DLL", "localization [MFC], resources", "installing MFC components"] -ms.assetid: 0b582615-3bb1-4fc0-b569-d127d6deccd3 --- # TN056: Installation of Localized MFC Components +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This tech note, which discussed the installation of localized MFC components, is now obsolete. **See** [TechNote 57](../mfc/tn057-localization-of-mfc-components.md) for more information on localizing MFC applications. diff --git a/docs/mfc/tn057-localization-of-mfc-components.md b/docs/mfc/tn057-localization-of-mfc-components.md index bb920458129..fe12fc41a47 100644 --- a/docs/mfc/tn057-localization-of-mfc-components.md +++ b/docs/mfc/tn057-localization-of-mfc-components.md @@ -3,10 +3,12 @@ description: "Learn more about: TN057: Localization of MFC Components" title: "TN057: Localization of MFC Components" ms.date: "06/28/2018" helpviewer_keywords: ["components [MFC], localizing", "TN057", "resources [MFC], localization", "localization [MFC], MFC resources", "localization [MFC], MFC components", "MFC DLLs [MFC], localizing", "DLLs [MFC], localizing MFC", "localization [MFC], resources"] -ms.assetid: 5376d329-bd45-41bd-97f5-3d895a9a0af5 --- # TN057: Localization of MFC Components +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn058-mfc-module-state-implementation.md b/docs/mfc/tn058-mfc-module-state-implementation.md index 29a3777b22a..b2ca4bf12b7 100644 --- a/docs/mfc/tn058-mfc-module-state-implementation.md +++ b/docs/mfc/tn058-mfc-module-state-implementation.md @@ -3,10 +3,12 @@ description: "Learn more about: TN058: MFC Module State Implementation" title: "TN058: MFC Module State Implementation" ms.date: "06/28/2018" helpviewer_keywords: ["thread state [MFC]", "module states [MFC], managing state data", "TN058", "MFC, managing state data", "module states [MFC], switching", "DLLs [MFC], module states", "process state [MFC]"] -ms.assetid: 72f5b36f-b3da-4009-a144-24258dcd2b2f --- # TN058: MFC Module State Implementation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn059-using-mfc-mbcs-unicode-conversion-macros.md b/docs/mfc/tn059-using-mfc-mbcs-unicode-conversion-macros.md index ad8aba48e47..b4bae8e9fe9 100644 --- a/docs/mfc/tn059-using-mfc-mbcs-unicode-conversion-macros.md +++ b/docs/mfc/tn059-using-mfc-mbcs-unicode-conversion-macros.md @@ -3,10 +3,12 @@ description: "Learn more about: TN059: Using MFC MBCS/Unicode Conversion Macros" title: "TN059: Using MFC MBCS-Unicode Conversion Macros" ms.date: "11/04/2016" helpviewer_keywords: ["MFCANS32.DLL", "Unicode [MFC], conversion macros", "Unicode [MFC], OLE interfaces", "conversion macros [MFC]", "converting Unicode", "MBCS [MFC], conversion macros", "macros [MFC], MBCS conversion macros", "TN059"] -ms.assetid: a2aab748-94d0-4e2f-8447-3bd07112a705 --- # TN059: Using MFC MBCS/Unicode Conversion Macros +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn060-the-new-windows-common-controls.md b/docs/mfc/tn060-the-new-windows-common-controls.md index 587bb4c4336..2fc9ddc17bd 100644 --- a/docs/mfc/tn060-the-new-windows-common-controls.md +++ b/docs/mfc/tn060-the-new-windows-common-controls.md @@ -4,10 +4,12 @@ title: "TN060: The New Windows Common Controls" ms.date: "11/04/2016" f1_keywords: ["vc.controls.common"] helpviewer_keywords: ["TN060"] -ms.assetid: 1a8eea6c-283a-4043-a7dc-a036e37e508e --- # TN060: The New Windows Common Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Technical Note 60, describing the new Windows common controls and how to use them, has been incorporated into [Controls](../mfc/controls-mfc.md). ## See also diff --git a/docs/mfc/tn061-on-notify-and-wm-notify-messages.md b/docs/mfc/tn061-on-notify-and-wm-notify-messages.md index b035d0e6d44..8575d247f07 100644 --- a/docs/mfc/tn061-on-notify-and-wm-notify-messages.md +++ b/docs/mfc/tn061-on-notify-and-wm-notify-messages.md @@ -3,10 +3,13 @@ description: "Learn more about: TN061: ON_NOTIFY and WM_NOTIFY Messages" title: "TN061: ON_NOTIFY and WM_NOTIFY Messages" ms.date: "06/28/2018" helpviewer_keywords: ["ON_NOTIFY_EX message [MFC]", "TN061", "ON_NOTIFY message [MFC]", "ON_NOTIFY_EX_RANGE message [MFC]", "ON_NOTIFY_RANGE message [MFC]", "notification messages", "WM_NOTIFY message"] -ms.assetid: 04a96dde-7049-41df-9954-ad7bb5587caf +ms.topic: reference --- # TN061: ON_NOTIFY and WM_NOTIFY Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn062-message-reflection-for-windows-controls.md b/docs/mfc/tn062-message-reflection-for-windows-controls.md index 9f4d1c7ffe5..dda93b386df 100644 --- a/docs/mfc/tn062-message-reflection-for-windows-controls.md +++ b/docs/mfc/tn062-message-reflection-for-windows-controls.md @@ -4,10 +4,12 @@ title: "TN062: Message Reflection for Windows Controls" ms.date: "06/28/2018" f1_keywords: ["vc.controls.messages"] helpviewer_keywords: ["ON_WM_VKEYTOITEM_REFLECT macro [MFC]", "ON_WM_DRAWITEM_REFLECT macro [MFC]", "ON_WM_VSCROLL_REFLECT macro [MFC]", "ON_NOTIFY_REFLECT message [MFC]", "ON_CONTROL_REFLECT_EX macro [MFC]", "ON_UPDATE_COMMAND_UI_REFLECT macro [MFC]", "ON_NOTIFY_REFLECT_EX message [MFC]", "ON_WM_HSCROLL_REFLECT macro [MFC]", "message reflection [MFC]", "ON_WM_COMPAREITEM_REFLECT macro [MFC]", "ON_WM_MEASUREITEM_REFLECT macro [MFC]", "ON_NOTIFY message [MFC]", "WM_COMMAND [MFC]", "WM_CTLCOLOR message [MFC]", "TN062 [MFC]", "ON_WM_CHARTOITEM_REFLECT macro [MFC]", "ON_WM_CTLCOLOR_REFLECT macro [MFC]", "ON_WM_DELETEITEM_REFLECT macro [MFC]", "notification messages [MFC]", "ON_WM_PARENTNOTIFY_REFLECT macro [MFC]", "WM_NOTIFY message [MFC]", "ON_CONTROL_REFLECT macro"] -ms.assetid: 53efb0ba-fcda-4fa0-a3c7-14e0b78fb494 --- # TN062: Message Reflection for Windows Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. @@ -90,7 +92,7 @@ This simple example creates a reusable control called `CYellowEdit`. The control You must have an application in which to develop the reusable control. If you don't have an existing application to use, create a dialog-based application using AppWizard. -2. With your project loaded into Visual C++, use ClassWizard to create a new class called `CYellowEdit` based on `CEdit`. +2. With your project loaded into Visual Studio, use ClassWizard to create a new class called `CYellowEdit` based on `CEdit`. 3. Add three member variables to your `CYellowEdit` class. The first two will be *COLORREF* variables to hold the text color and the background color. The third will be a `CBrush` object that will hold the brush for painting the background. The `CBrush` object allows you to create the brush once, merely referencing it after that, and to destroy the brush automatically when the `CYellowEdit` control is destroyed. diff --git a/docs/mfc/tn063-debugging-internet-extension-dlls.md b/docs/mfc/tn063-debugging-internet-extension-dlls.md index 221dc62282f..cbc729feaf3 100644 --- a/docs/mfc/tn063-debugging-internet-extension-dlls.md +++ b/docs/mfc/tn063-debugging-internet-extension-dlls.md @@ -4,10 +4,12 @@ title: "TN063: Debugging Internet MFC extension DLLs" ms.date: "11/04/2016" f1_keywords: ["vs.debug.dlls"] helpviewer_keywords: ["IIS [MFC], debugging DLLs", "TN063 [MFC]", "DLLs [MFC], Internet extension"] -ms.assetid: 7012d592-9d2f-491a-b417-48e5c2a7680f --- # TN063: Debugging Internet MFC extension DLLs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This information is obsolete and has been removed. ## See also diff --git a/docs/mfc/tn064-apartment-model-threading-in-activex-controls.md b/docs/mfc/tn064-apartment-model-threading-in-activex-controls.md index 0d71b56986e..126989be356 100644 --- a/docs/mfc/tn064-apartment-model-threading-in-activex-controls.md +++ b/docs/mfc/tn064-apartment-model-threading-in-activex-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: TN064: Apartment-Model Threading in ActiveX Cont title: "TN064: Apartment-Model Threading in ActiveX Controls" ms.date: "11/04/2016" helpviewer_keywords: ["OLE controls [MFC], container support", "containers [MFC], multithreaded", "TN064 [MFC]", "multithread container [MFC]", "apartment model threading [MFC]"] -ms.assetid: b2ab4c88-6954-48e2-9a74-01d4a60df073 --- # TN064: Apartment-Model Threading in ActiveX Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn065-dual-interface-support-for-ole-automation-servers.md b/docs/mfc/tn065-dual-interface-support-for-ole-automation-servers.md index 295169fce62..956ba9e677a 100644 --- a/docs/mfc/tn065-dual-interface-support-for-ole-automation-servers.md +++ b/docs/mfc/tn065-dual-interface-support-for-ole-automation-servers.md @@ -4,10 +4,12 @@ title: "TN065: Dual-Interface Support for OLE Automation Servers" ms.date: "06/28/2018" f1_keywords: ["vc.ole"] helpviewer_keywords: ["dual interfaces [MFC], OLE Automation", "TN065 [MFC]", "ACDUAL sample [MFC]", "Automation servers [MFC], dual-interface support"] -ms.assetid: b5c8ed09-2f7f-483c-80fc-2a47ad896063 --- # TN065: Dual-Interface Support for OLE Automation Servers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. @@ -31,7 +33,7 @@ Although OLE Automation allows you to implement an `IDispatch` interface, a VTBL A dual interface is really just a custom interface derived from `IDispatch`. The most straightforward way to implement dual-interface support in a `CCmdTarget`-based class is to first implement the normal dispatch interface on your class using MFC and ClassWizard, then add the custom interface later. For the most part, your custom interface implementation will simply delegate back to the MFC `IDispatch` implementation. -First, modify the ODL file for your server to define dual interfaces for your objects. To define a dual interface, you must use an interface statement, instead of the `DISPINTERFACE` statement that the Visual C++ wizards generate. Rather than removing the existing `DISPINTERFACE` statement, add a new interface statement. By retaining the `DISPINTERFACE` form, you can continue to use ClassWizard to add properties and methods to your object, but you must add the equivalent properties and methods to your interface statement. +First, modify the ODL file for your server to define dual interfaces for your objects. To define a dual interface, you must use an interface statement, instead of the `DISPINTERFACE` statement that the Visual Studio wizards generate. Rather than removing the existing `DISPINTERFACE` statement, add a new interface statement. By retaining the `DISPINTERFACE` form, you can continue to use ClassWizard to add properties and methods to your object, but you must add the equivalent properties and methods to your interface statement. An interface statement for a dual interface must have the *OLEAUTOMATION* and *DUAL* attributes, and the interface must be derived from `IDispatch`. You can use the [GUIDGEN](../overview/visual-cpp-samples.md) sample to create a **IID** for the dual interface: @@ -275,7 +277,7 @@ To add the **UUID** definitions from the MkTypLib-generated header file to your ## Specifying the Correct Object Class Name in the Type Library -The wizards shipped with Visual C++ incorrectly use the implementation class name to specify the coclass in the server's ODL file for OLE-creatable classes. While this will work, the implementation class name is probably not the class name you want users of your object to use. To specify the correct name, open the ODL file, locate each coclass statement, and replace the implementation class name with the correct external name. +The wizards shipped with Visual Studio incorrectly use the implementation class name to specify the coclass in the server's ODL file for OLE-creatable classes. While this will work, the implementation class name is probably not the class name you want users of your object to use. To specify the correct name, open the ODL file, locate each coclass statement, and replace the implementation class name with the correct external name. Note that when the coclass statement is changed, the variable names of **CLSID**s in the MkTypLib-generated header file will change accordingly. You will need to update your code to use the new variable names. diff --git a/docs/mfc/tn066-common-mfc-3-x-to-4-0-porting-issues.md b/docs/mfc/tn066-common-mfc-3-x-to-4-0-porting-issues.md index ecfa6eef124..6b374174140 100644 --- a/docs/mfc/tn066-common-mfc-3-x-to-4-0-porting-issues.md +++ b/docs/mfc/tn066-common-mfc-3-x-to-4-0-porting-issues.md @@ -3,10 +3,12 @@ description: "Learn more about: TN066: Common MFC 3.x to 4.0 Porting Issues" title: "TN066: Common MFC 3.x to 4.0 Porting Issues" ms.date: "11/04/2016" helpviewer_keywords: ["porting MFC, 3.x to 4.0", "TN066 [MFC]", "porting MFC"] -ms.assetid: 88308897-8da8-496d-bdef-d34ab77cdd79 --- # TN066: Common MFC 3.x to 4.0 Porting Issues +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This technical note described the most common problems that can occur when attempting to port an application written with MFC 3.x (the MFC included with Visual C++ 2.x) to MFC 4.0. ## See also diff --git a/docs/mfc/tn068-performing-transactions-with-the-microsoft-access-7-odbc-driver.md b/docs/mfc/tn068-performing-transactions-with-the-microsoft-access-7-odbc-driver.md index 41fbc200c66..64b92977edd 100644 --- a/docs/mfc/tn068-performing-transactions-with-the-microsoft-access-7-odbc-driver.md +++ b/docs/mfc/tn068-performing-transactions-with-the-microsoft-access-7-odbc-driver.md @@ -4,10 +4,12 @@ title: "TN068: Performing Transactions with the Microsoft Access 7 ODBC Driver" ms.date: "06/28/2018" f1_keywords: ["vc.data.odbc"] helpviewer_keywords: ["TN068 [MFC]", "transactions [MFC], calling BeginTrans", "transactions [MFC], Microsoft Access"] -ms.assetid: d3f8f5d9-b118-4194-be36-a1aefb630c45 --- # TN068: Performing Transactions with the Microsoft Access 7 ODBC Driver +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn070-mfc-window-class-names.md b/docs/mfc/tn070-mfc-window-class-names.md index f72a9dadf3f..f3d9fe97e47 100644 --- a/docs/mfc/tn070-mfc-window-class-names.md +++ b/docs/mfc/tn070-mfc-window-class-names.md @@ -3,10 +3,12 @@ description: "Learn more about: TN070: MFC Window Class Names" title: "TN070: MFC Window Class Names" ms.date: "11/04/2016" helpviewer_keywords: ["window class names [MFC]", "TN070 [MFC]"] -ms.assetid: 90617912-dd58-4a7c-9082-ced71736d7cd --- # TN070: MFC Window Class Names +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/tn071-mfc-iolecommandtarget-implementation.md b/docs/mfc/tn071-mfc-iolecommandtarget-implementation.md index 293dda09b60..33a2073e56b 100644 --- a/docs/mfc/tn071-mfc-iolecommandtarget-implementation.md +++ b/docs/mfc/tn071-mfc-iolecommandtarget-implementation.md @@ -3,10 +3,12 @@ description: "Learn more about: TN071: MFC IOleCommandTarget Implementation" title: "TN071: MFC IOleCommandTarget Implementation" ms.date: "06/28/2018" helpviewer_keywords: ["TN071 [MFC]", "IOleCommandTarget interface [MFC]"] -ms.assetid: 3eef571e-6357-444d-adbb-6f734a0c3161 --- # TN071: MFC IOleCommandTarget Implementation +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > The following technical note has not been updated since it was first included in the online documentation. As a result, some procedures and topics might be out of date or incorrect. For the latest information, it is recommended that you search for the topic of interest in the online documentation index. diff --git a/docs/mfc/toc.yml b/docs/mfc/toc.yml index 5003fb328d6..fcc45274295 100644 --- a/docs/mfc/toc.yml +++ b/docs/mfc/toc.yml @@ -1025,7 +1025,7 @@ items: href: creating-modeless-dialog-boxes.md - name: Using a dialog template in memory href: using-a-dialog-template-in-memory.md - - name: Setting the dialog box’s background color + - name: Setting the dialog box's background color href: setting-the-dialog-boxs-background-color.md - name: Initializing the dialog box href: initializing-the-dialog-box.md @@ -1493,7 +1493,7 @@ items: href: tn032-mfc-exception-mechanism.md - name: "TN033: DLL version of MFC" href: tn033-dll-version-of-mfc.md - - name: "TN035: Using multiple resource files and header files with Visual C++" + - name: "TN035: Using multiple resource files and header files with Visual Studio" href: tn035-using-multiple-resource-files-and-header-files-with-visual-cpp.md - name: "TN036: Using CFormView with AppWizard and ClassWizard" href: tn036-using-cformview-with-appwizard-and-classwizard.md @@ -2919,6 +2919,6 @@ items: - name: Add a method to an IDL interface in a MFC project href: reference/add-idl-mfc-method-wizard.md - name: Add a property to an IDL interface in a MFC project - href: reference/add-interface-definition-library-mfc-property-wizard.md + href: reference/add-interface-definition-library-mfc-property-wizard.md - name: MFC class wizard - href: reference/mfc-class-wizard.md \ No newline at end of file + href: reference/mfc-class-wizard.md \ No newline at end of file diff --git a/docs/mfc/tool-tips-in-windows-not-derived-from-cframewnd.md b/docs/mfc/tool-tips-in-windows-not-derived-from-cframewnd.md index ae8986fef63..8d3d3ee6772 100644 --- a/docs/mfc/tool-tips-in-windows-not-derived-from-cframewnd.md +++ b/docs/mfc/tool-tips-in-windows-not-derived-from-cframewnd.md @@ -3,10 +3,12 @@ description: "Learn more about: Tool Tips in Windows Not Derived from CFrameWnd" title: "Tool Tips in Windows Not Derived from CFrameWnd" ms.date: "11/04/2016" helpviewer_keywords: ["enabling tool tips [MFC]", "TOOLTIPTEXT structure [MFC]", "Help [MFC], tool tips for controls", "TTN_NEEDTEXT message [MFC]", "controls [MFC], tool tips", "handler functions [MFC], tool tips"] -ms.assetid: cad5ef0f-02e3-4151-ad0d-3d42e6932b0e --- # Tool Tips in Windows Not Derived from CFrameWnd +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article family covers enabling tool tips for controls contained in a window that is not derived from [CFrameWnd](../mfc/reference/cframewnd-class.md). The article [Toolbars Tool Tips](../mfc/toolbar-tool-tips.md) provides information about tool tips for controls in a `CFrameWnd`. Topics covered in this article family include: diff --git a/docs/mfc/tool-tips.md b/docs/mfc/tool-tips.md index 33ac9aa93ef..84f1e235f9b 100644 --- a/docs/mfc/tool-tips.md +++ b/docs/mfc/tool-tips.md @@ -3,10 +3,12 @@ description: "Learn more about: Tool Tips" title: "Tool Tips" ms.date: "11/04/2016" helpviewer_keywords: ["CFrameWnd class [MFC], tool tips", "Help [MFC], tool tips for controls", "tool tips [MFC], CFrameWnd", "controls [MFC], tool tips", "buttons [MFC], tool tips"] -ms.assetid: 7f0bba86-7c55-4bf6-8455-687a4dcb2be8 --- # Tool Tips +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The procedures are distinct for adding tool tips to controls contained in windows derived from MFC class [CFrameWnd](../mfc/reference/cframewnd-class.md) and windows not derived from `CFrameWnd`. ## What do you want to know more about diff --git a/docs/mfc/toolbar-fundamentals.md b/docs/mfc/toolbar-fundamentals.md index 283156c66ef..92532ae95e8 100644 --- a/docs/mfc/toolbar-fundamentals.md +++ b/docs/mfc/toolbar-fundamentals.md @@ -4,10 +4,12 @@ title: "Toolbar Fundamentals" ms.date: "11/04/2016" f1_keywords: ["RT_TOOLBAR"] helpviewer_keywords: ["embedding toolbar in frame window class [MFC]", "application wizards [MFC], installing default application toolbars", "toolbars [MFC], creating", "resources [MFC], toolbar", "toolbar controls [MFC], toolbars created using Application Wizard", "toolbar controls [MFC], command ID", "RT_TOOLBAR resource [MFC]", "toolbars [MFC], adding default using Application Wizard", "LoadBitmap method [MFC], toolbars", "Toolbar editor [MFC], Application Wizard", "command IDs [MFC], toolbar buttons", "SetButtons method [MFC]", "CToolBar class [MFC], default toolbars in Application Wizard", "frame window classes [MFC], toolbar embedded in", "LoadToolBar method [MFC]"] -ms.assetid: cc00aaff-8a56-433b-b0c0-b857d76b4ffd --- # Toolbar Fundamentals +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the fundamental MFC implementation that lets you add a default toolbar to your application by selecting an option in the Application Wizard. Topics covered include: - [The Application Wizard toolbar option](#_core_the_appwizard_toolbar_option) @@ -47,7 +49,7 @@ The docking, floating, and tool tips calls are optional. You can remove those li ## Editing the Toolbar Resource -The default toolbar you get with the Application Wizard is based on an **RT_TOOLBAR** custom resource, introduced in MFC version 4.0. You can edit this resource with the [toolbar editor](../windows/toolbar-editor.md). The editor lets you easily add, delete, and rearrange buttons. It contains a graphical editor for the buttons that is very similar to the general graphics editor in Visual C++. If you edited toolbars in previous versions of Visual C++, you'll find the task much easier now. +The default toolbar you get with the Application Wizard is based on an **RT_TOOLBAR** custom resource, introduced in MFC version 4.0. You can edit this resource with the [toolbar editor](../windows/toolbar-editor.md). The editor lets you easily add, delete, and rearrange buttons. It contains a graphical editor for the buttons that is very similar to the general graphics editor in Visual Studio. If you edited toolbars in previous versions of Visual Studio, you'll find the task much easier now. To connect a toolbar button to a command, you give the button a command ID, such as `ID_MYCOMMAND`. Specify the command ID in the button's property page in the toolbar editor. Then create a handler function for the command (see [Mapping Messages to Functions](../mfc/reference/mapping-messages-to-functions.md) for more information). diff --git a/docs/mfc/toolbar-sample-list.md b/docs/mfc/toolbar-sample-list.md index f7ec47b1bec..a47fdf7ea6c 100644 --- a/docs/mfc/toolbar-sample-list.md +++ b/docs/mfc/toolbar-sample-list.md @@ -3,10 +3,12 @@ description: "Learn more about: Toolbar Sample List" title: "Toolbar Sample List" ms.date: "11/04/2016" helpviewer_keywords: ["sample applications [MFC], toolbars"] -ms.assetid: 61310e4e-3df7-47c2-8b10-7c6cb45c5d1b --- # Toolbar Sample List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + See the following sample programs that illustrate using MFC's toolbars: - [SCRIBBLE](../overview/visual-cpp-samples.md) diff --git a/docs/mfc/toolbar-tool-tips.md b/docs/mfc/toolbar-tool-tips.md index d7914d8884d..b0ea2b0d9a7 100644 --- a/docs/mfc/toolbar-tool-tips.md +++ b/docs/mfc/toolbar-tool-tips.md @@ -3,10 +3,12 @@ description: "Learn more about: Toolbar Tool Tips" title: "Toolbar Tool Tips" ms.date: "11/04/2016" helpviewer_keywords: ["tool tips [MFC], activating", "CBRS_TOOLTIPS constant [MFC]", "tool tips [MFC], adding text", "updates [MFC]", "CBRS_FLYBY constant [MFC]", "tool tips [MFC]", "updating status bar messages", "updates, status bar messages", "status bars [MFC], tool tips", "flyby status bar updates"] -ms.assetid: d1696305-b604-4fad-9f09-638878371412 --- # Toolbar Tool Tips +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Tool tips are the tiny popup windows that present short descriptions of a toolbar button's purpose when you position the mouse over a button for a period of time. When you create an application with the Application Wizard that has a toolbar, tool tip support is provided for you. This article explains both the tool tip support created by the Application Wizard and how to add tool tip support to your application. This article covers: diff --git a/docs/mfc/toolbars.md b/docs/mfc/toolbars.md index 7ad24693784..cca3d41db3b 100644 --- a/docs/mfc/toolbars.md +++ b/docs/mfc/toolbars.md @@ -3,10 +3,12 @@ description: "Learn more about: Toolbars" title: "Toolbars" ms.date: "11/04/2016" helpviewer_keywords: ["toolbars [MFC]", "command bars [MFC], MFC toolbars"] -ms.assetid: c22ecc5b-a84c-4979-8d1a-8e3e71d5ce33 --- # Toolbars +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The toolbar family of articles describes MFC toolbars and how to create and use them. ## What do you want to know more about diff --git a/docs/mfc/tooltiptext-structure.md b/docs/mfc/tooltiptext-structure.md index 2fb1e28f541..ebb33d4f484 100644 --- a/docs/mfc/tooltiptext-structure.md +++ b/docs/mfc/tooltiptext-structure.md @@ -4,10 +4,12 @@ title: "TOOLTIPTEXT Structure" ms.date: "11/04/2016" f1_keywords: ["TOOLTIPTEXT"] helpviewer_keywords: ["TOOLTIPTEXT structure [MFC]", "tool tips [MFC], notifications"] -ms.assetid: 547591bf-80f5-400e-a2a7-0708cfffbb5d --- # TOOLTIPTEXT Structure +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In writing your [tool tip notification handler](../mfc/handling-ttn-needtext-notification-for-tool-tips.md), you need to use the **TOOLTIPTEXT** structure. The members of the **TOOLTIPTEXT** structure are: ```cpp diff --git a/docs/mfc/trackers-implementing-trackers-in-your-ole-application.md b/docs/mfc/trackers-implementing-trackers-in-your-ole-application.md index d5718ffda1d..208656401f8 100644 --- a/docs/mfc/trackers-implementing-trackers-in-your-ole-application.md +++ b/docs/mfc/trackers-implementing-trackers-in-your-ole-application.md @@ -3,10 +3,12 @@ description: "Learn more about: Trackers: Implementing Trackers in Your OLE Appl title: "Trackers: Implementing Trackers in Your OLE Application" ms.date: "11/04/2016" helpviewer_keywords: ["trackers [MFC]", "OLE applications [MFC], trackers", "applications [OLE], trackers", "tracking OLE items [MFC]", "OLE containers [MFC], trackers", "CRectTracker class [MFC], implementing trackers"] -ms.assetid: 5103a517-65bd-441a-8a53-02915ff3ef08 --- # Trackers: Implementing Trackers in Your OLE Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Trackers provide a graphical interface to enable users to interact with OLE client items. By using different tracker styles, OLE client items can be displayed with hatched borders, resize handles, or a variety of other visual effects. This article describes: - [How to Implement Tracking in Your Code](../mfc/how-to-implement-tracking-in-your-code.md). diff --git a/docs/mfc/trackers.md b/docs/mfc/trackers.md index 284e9585651..c3f2d1dec11 100644 --- a/docs/mfc/trackers.md +++ b/docs/mfc/trackers.md @@ -3,10 +3,12 @@ description: "Learn more about: Trackers" title: "Trackers" ms.date: "11/04/2016" helpviewer_keywords: ["trackers [MFC]", "OLE applications [MFC], trackers", "applications [OLE], trackers", "tracking OLE items [MFC]", "OLE containers [MFC], trackers", "CDC class [MFC], trackers", "CRectTracker class [MFC], implementing trackers", "OLE server applications [MFC], trackers"] -ms.assetid: dcd09399-6637-4621-80e5-d12670429787 --- # Trackers +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CRectTracker](../mfc/reference/crecttracker-class.md) class provides a user interface between rectangular items in your application and your user by providing a variety of display styles. These styles include solid, hatched, or dashed borders; a hatched pattern that covers the item; and resize handles that can be located on the outside or inside of a border. Trackers are often used in conjunction with OLE items, that is, objects derived from `COleClientItem`. The tracker rectangles give visual cues on the current status of the item. The MFC OLE sample [OCLIENT](../overview/visual-cpp-samples.md) demonstrates a common interface using trackers and OLE client items from the viewpoint of a container application. For a demonstration of the different styles and abilities of a tracker object, see the MFC general sample [TRACKER](../overview/visual-cpp-samples.md). diff --git a/docs/mfc/tree-control-drag-and-drop-operations.md b/docs/mfc/tree-control-drag-and-drop-operations.md index 32bfd434cb4..bd72d567335 100644 --- a/docs/mfc/tree-control-drag-and-drop-operations.md +++ b/docs/mfc/tree-control-drag-and-drop-operations.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Drag-and-Drop Operations" title: "Tree Control Drag-and-Drop Operations" ms.date: "11/04/2016" helpviewer_keywords: ["CTreeCtrl class [MFC], drag and drop operations", "drag and drop [MFC], CTreeCtrl", "tree controls [MFC], drag and drop operations"] -ms.assetid: 3cf78b4c-4579-4fe1-9bc9-c5ab876e4af1 --- # Tree Control Drag-and-Drop Operations +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) sends a notification when the user starts to drag an item. The control sends a [TVN_BEGINDRAG](/windows/win32/Controls/tvn-begindrag) notification message when the user begins dragging an item with the left mouse button and a [TVN_BEGINRDRAG](/windows/win32/Controls/tvn-beginrdrag) notification message when the user begins dragging with the right button. You can prevent a tree control from sending these notifications by giving the tree control the TVS_DISABLEDRAGDROP style. You obtain an image to display during a drag operation by calling the [CreateDragImage](../mfc/reference/ctreectrl-class.md#createdragimage) member function. The tree control creates a dragging bitmap based on the label of the item being dragged. Then the tree control creates an image list, adds the bitmap to it, and returns a pointer to the [CImageList](../mfc/reference/cimagelist-class.md) object. diff --git a/docs/mfc/tree-control-image-lists.md b/docs/mfc/tree-control-image-lists.md index d8525bec05f..93787bb896f 100644 --- a/docs/mfc/tree-control-image-lists.md +++ b/docs/mfc/tree-control-image-lists.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Image Lists" title: "Tree Control Image Lists" ms.date: "11/04/2016" helpviewer_keywords: ["images [MFC], lists in tree controls", "tree controls [MFC], image lists", "CTreeCtrl class [MFC], image lists"] -ms.assetid: f560c4f2-20d2-4d28-ac33-4017e65fb0a6 --- # Tree Control Image Lists +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Each item in a tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) can have a pair of bitmapped images associated with it. The images appear on the left side of an item's label. One image is displayed when the item is selected, and the other is displayed when the item is not selected. For example, an item might display an open folder when it is selected and a closed folder when it is not selected. To use item images, you must create an image list by constructing a [CImageList](../mfc/reference/cimagelist-class.md) object and using the [CImageList::Create](../mfc/reference/cimagelist-class.md#create) function to create the associated image list. Then add the desired bitmaps to the list, and associate the list with the tree control by using the [SetImageList](../mfc/reference/ctreectrl-class.md#setimagelist) member function. By default, all items display the first image in the image list for both the selected and nonselected states. You can change the default behavior for a particular item by specifying the indexes of the selected and nonselected images when adding the item to the tree control using the [InsertItem](../mfc/reference/ctreectrl-class.md#insertitem) member function. You can change the indexes after adding an item by using the [SetItemImage](../mfc/reference/ctreectrl-class.md#setitemimage) member function. diff --git a/docs/mfc/tree-control-item-information.md b/docs/mfc/tree-control-item-information.md index acf7eb6b7d9..bc49370f2b1 100644 --- a/docs/mfc/tree-control-item-information.md +++ b/docs/mfc/tree-control-item-information.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Item Information" title: "Tree Control Item Information" ms.date: "11/04/2016" helpviewer_keywords: ["tree controls [MFC], item information", "CTreeCtrl class [MFC], item information"] -ms.assetid: 8dcab855-27de-49e9-95d8-f78ba963ea71 --- # Tree Control Item Information +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Tree controls ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) have a number of member functions that retrieve information about items in the control. The [GetItem](../mfc/reference/ctreectrl-class.md#getitem) member function retrieves some or all of the data associated with an item. This data could include the item's text, state, images, count of child items, and an application-defined 32-bit data value. There is also a [SetItem](../mfc/reference/ctreectrl-class.md#setitem) function that can set some or all of the data associated with an item. The [GetItemState](../mfc/reference/ctreectrl-class.md#getitemstate), [GetItemText](../mfc/reference/ctreectrl-class.md#getitemtext), [GetItemData](../mfc/reference/ctreectrl-class.md#getitemdata), and [GetItemImage](../mfc/reference/ctreectrl-class.md#getitemimage) member functions retrieve individual attributes of an item. Each of these functions has a corresponding Set function for setting the attributes of an item. diff --git a/docs/mfc/tree-control-item-labels.md b/docs/mfc/tree-control-item-labels.md index aea13c5e902..42490361966 100644 --- a/docs/mfc/tree-control-item-labels.md +++ b/docs/mfc/tree-control-item-labels.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Item Labels" title: "Tree Control Item Labels" ms.date: "11/04/2016" helpviewer_keywords: ["tree controls [MFC], item labels", "labels, CTreeCtrl items", "CTreeCtrl class [MFC], item labels", "item labels, tree controls", "item labels"] -ms.assetid: fe834107-1a25-4280-aced-774c11565805 --- # Tree Control Item Labels +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You typically specify the text of an item's label when adding the item to the tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)). The `InsertItem` member function can pass a [TVITEM](/windows/win32/api/commctrl/ns-commctrl-tvitemw) structure that defines the item's properties, including a string containing the text of the label. `InsertItem` has several overloads that can be called with various combinations of parameters. A tree control allocates memory for storing each item; the text of the item labels takes up a significant portion of this memory. If your application maintains a copy of the strings in the tree control, you can decrease the memory requirements of the control by specifying the **LPSTR_TEXTCALLBACK** value in the *pszText* member of `TV_ITEM` or the *lpszItem* parameter instead of passing actual strings to the tree control. Using **LPSTR_TEXTCALLBACK** causes the tree control to retrieve the text of an item's label from the application whenever the item needs to be redrawn. To retrieve the text, the tree control sends a [TVN_GETDISPINFO](/windows/win32/Controls/tvn-getdispinfo) notification message, which includes the address of a [NMTVDISPINFO](/windows/win32/api/commctrl/ns-commctrl-nmtvdispinfow) structure. You must respond by setting the appropriate members of the included structure. diff --git a/docs/mfc/tree-control-item-position.md b/docs/mfc/tree-control-item-position.md index f6a855c2018..11544293a93 100644 --- a/docs/mfc/tree-control-item-position.md +++ b/docs/mfc/tree-control-item-position.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Item Position" title: "Tree Control Item Position" ms.date: "11/04/2016" helpviewer_keywords: ["CTreeCtrl class [MFC], item position", "item position in tree controls", "tree controls [MFC], item position", "position, CTreeCtrl items"] -ms.assetid: cd264344-2cf9-4d90-9ea8-c6900b6f60e7 --- # Tree Control Item Position +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An item's initial position is set when the item is added to the tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) by using the `InsertItem` member function. The member function call specifies the handle of the parent item and the handle of the item after which the new item is to be inserted. The second handle must identify either a child item of the given parent or one of these values: `TVI_FIRST`, `TVI_LAST`, or `TVI_SORT`. When `TVI_FIRST` or `TVI_LAST` is specified, the tree control places the new item at the beginning or end of the given parent item's list of child items. When `TVI_SORT` is specified, the tree control inserts the new item into the list of child items in alphabetical order based on the text of the item labels. diff --git a/docs/mfc/tree-control-item-selection.md b/docs/mfc/tree-control-item-selection.md index e48ff060f2c..411f20dbc4f 100644 --- a/docs/mfc/tree-control-item-selection.md +++ b/docs/mfc/tree-control-item-selection.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Item Selection" title: "Tree Control Item Selection" ms.date: "11/04/2016" helpviewer_keywords: ["tree controls [MFC], item selection", "controls [MFC], selecting items in", "CTreeCtrl class [MFC], item selection", "item selection in tree controls"] -ms.assetid: 7bcb3b16-b9c8-4c06-9350-7bc3c1c5009b --- # Tree Control Item Selection +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When the selection changes from one item to another, a tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) sends [TVN_SELCHANGING](/windows/win32/Controls/tvn-selchanging) and [TVN_SELCHANGED](/windows/win32/Controls/tvn-selchanged) notification messages. Both notifications include a value that specifies whether the change is the result of a mouse click or a keystroke. The notifications also include information about the item that is gaining the selection and the item that is losing the selection. You can use this information to set item attributes that depend on the selection state of the item. Returning **TRUE** in response to `TVN_SELCHANGING` prevents the selection from changing; returning **FALSE** allows the change. An application can change the selection by calling the [SelectItem](../mfc/reference/ctreectrl-class.md#selectitem) member function. diff --git a/docs/mfc/tree-control-item-states-overview.md b/docs/mfc/tree-control-item-states-overview.md index 73e7e0f6327..856d9a7e72d 100644 --- a/docs/mfc/tree-control-item-states-overview.md +++ b/docs/mfc/tree-control-item-states-overview.md @@ -3,10 +3,13 @@ description: "Learn more about: Tree Control Item States Overview" title: "Tree Control Item States Overview" ms.date: "11/04/2016" helpviewer_keywords: ["states, CTreeCtrl items", "tree controls [MFC], item states overview", "CTreeCtrl class [MFC], item states"] -ms.assetid: 2db11ae0-0d87-499d-8c1f-5e0dbe9e94c8 +ms.topic: concept-article --- # Tree Control Item States Overview +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Each item in a tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) has a current state. For example, an item can be selected, disabled, expanded, and so on. For the most part, the tree control automatically sets an item's state to reflect user actions, such as selection of an item. However, you can also set an item's state by using the [SetItemState](../mfc/reference/ctreectrl-class.md#setitemstate) member function and retrieve the current state of an item by using the [GetItemState](../mfc/reference/ctreectrl-class.md#getitemstate) member function. For a complete list of item states, see [Tree-View Control Constants](/windows/win32/Controls/tree-view-control-item-states) in the Windows SDK. An item's current state is specified by the *nState* parameter. A tree control might change an item's state to reflect a user action, such as selecting the item or setting the focus to the item. In addition, an application might change an item's state to disable or hide the item or to specify an overlay image or state image. diff --git a/docs/mfc/tree-control-label-editing.md b/docs/mfc/tree-control-label-editing.md index ec3bd79edfb..fbef5efff63 100644 --- a/docs/mfc/tree-control-label-editing.md +++ b/docs/mfc/tree-control-label-editing.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Label Editing" title: "Tree Control Label Editing" ms.date: "11/04/2016" helpviewer_keywords: ["editing tree control labels", "CTreeCtrl class [MFC], editing labels", "label editing in CTreeCtrl class [MFC]", "tree controls [MFC], label editing"] -ms.assetid: 6cde2ac3-43ee-468f-bac2-cf1a228ad32d --- # Tree Control Label Editing +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The user can directly edit the labels of items in a tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) that has the **TVS_EDITLABELS** style. The user begins editing by clicking the label of the item that has the focus. An application begins editing by using the [EditLabel](../mfc/reference/ctreectrl-class.md#editlabel) member function. The tree control sends the notification when editing begins and when it is canceled or completed. When editing is completed, you are responsible for updating the item's label, if appropriate. When label editing begins, a tree control sends a [TVN_BEGINLABELEDIT](/windows/win32/Controls/tvn-beginlabeledit) notification message. By processing this notification, you can allow editing of some labels and prevent editing of others. Returning 0 allows editing, and returning nonzero prevents it. diff --git a/docs/mfc/tree-control-notification-messages.md b/docs/mfc/tree-control-notification-messages.md index d17b69afe5d..15a91e6e4fb 100644 --- a/docs/mfc/tree-control-notification-messages.md +++ b/docs/mfc/tree-control-notification-messages.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Notification Messages" title: "Tree Control Notification Messages" ms.date: "11/04/2016" helpviewer_keywords: ["notifications [MFC], tree controls", "messages [MFC], notification", "CTreeCtrl class [MFC], notifications", "notifications [MFC], CTreeCtrl", "tree controls [MFC], notification messages"] -ms.assetid: ac7013b4-91dd-4668-bd75-439ca0680ef9 --- # Tree Control Notification Messages +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) sends the following notification messages as WM_NOTIFY messages: |Notification message|Description| diff --git a/docs/mfc/tree-control-parent-and-child-items.md b/docs/mfc/tree-control-parent-and-child-items.md index 27d07a900eb..ddc959d65e6 100644 --- a/docs/mfc/tree-control-parent-and-child-items.md +++ b/docs/mfc/tree-control-parent-and-child-items.md @@ -3,10 +3,12 @@ description: "Learn more about: Tree Control Parent and Child Items" title: "Tree Control Parent and Child Items" ms.date: "11/04/2016" helpviewer_keywords: ["parent items in CTreeCtrl [MFC]", "child items in tree control [MFC]", "CTreeCtrl class [MFC], parent and child items", "tree controls [MFC], parent and child items"] -ms.assetid: abcea1e4-fe9b-40d9-86dc-1db235f8f103 --- # Tree Control Parent and Child Items +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Any item in a tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) can have a list of subitems, which are called child items, associated with it. An item that has one or more child items is called a parent item. A child item is displayed below its parent item and is indented to indicate it is subordinate to the parent. An item that has no parent is at the top of the hierarchy and is called a root item. At any given time, the state of a parent item's list of child items can be either expanded or collapsed. When the state is expanded, the child items are displayed below the parent item. When it is collapsed, the child items are not displayed. The list automatically toggles between the expanded and collapsed states when the user double-clicks the parent item or, if the parent has the **TVS_HASBUTTONS** style, when the user clicks the button associated with the parent item. An application can expand or collapse the child items by using the [Expand](../mfc/reference/ctreectrl-class.md#expand) member function. diff --git a/docs/mfc/tree-control-styles.md b/docs/mfc/tree-control-styles.md index bde048b5f4f..b801000df1d 100644 --- a/docs/mfc/tree-control-styles.md +++ b/docs/mfc/tree-control-styles.md @@ -4,10 +4,12 @@ title: "Tree Control Styles" ms.date: "11/04/2016" f1_keywords: ["TVS_SINGLEEXPAND", "TVS_LINESATROOT", "TVS_HASBUTTONS", "TVS_NOTOOLTIPS", "TVS_HASLINES"] helpviewer_keywords: ["TVS_LINESATROOT [MFC]", "styles [MFC], CTreeCtrl", "styles [MFC], tree control", "TVS_HASLINES", "TVS_SINGLEEXPAND", "CTreeCtrl class [MFC], styles", "TVS_EDITLABELS [MFC]", "TVS_NOTOOLTIPS [MFC]", "TVS_HASBUTTONS [MFC]", "tree controls [MFC], styles"] -ms.assetid: f43faebd-a355-479e-888a-bf0673d5e1b4 --- # Tree Control Styles +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) styles govern aspects of a tree control's appearance. You set the initial styles when you create the tree control. You can retrieve and change the styles after creating the tree control by using the [GetWindowLong](/windows/win32/api/winuser/nf-winuser-getwindowlongw) and [SetWindowLong](/windows/win32/api/winuser/nf-winuser-setwindowlongw) Windows functions, specifying **GWL_STYLE** for the *nIndex* parameter. For a complete list of styles, see [Tree View Control Window Styles](/windows/win32/Controls/tree-view-control-window-styles) in the Windows SDK. The **TVS_HASLINES** style enhances the graphic representation of a tree control's hierarchy by drawing lines that link child items to their corresponding parent item. This style does not link items at the root of the hierarchy. To do so, you need to combine the **TVS_HASLINES** and **TVS_LINESATROOT** styles. diff --git a/docs/mfc/turning-off-the-activate-when-visible-option.md b/docs/mfc/turning-off-the-activate-when-visible-option.md index 837eb26f2f8..530d54f0526 100644 --- a/docs/mfc/turning-off-the-activate-when-visible-option.md +++ b/docs/mfc/turning-off-the-activate-when-visible-option.md @@ -3,10 +3,13 @@ description: "Learn more about: Turning off the Activate When Visible Option" title: "Turning off the Activate When Visible Option" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], activate options", "Activate When Visible option [MFC]"] -ms.assetid: 8f7ddc5a-a7a6-4da8-bcb9-1b569f0ecb48 +ms.topic: concept-article --- # Turning off the Activate When Visible Option +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A control has two basic states: active and inactive. Traditionally, these states were distinguished by whether the control had a window. An active control had a window; an inactive control did not. With the introduction of windowless activation, this distinction is no longer universal, but still applies to many controls. Compared with the rest of the initialization typically performed by an ActiveX control, the creation of a window is an extremely expensive operation. Ideally, a control would defer creating its window until absolutely necessary. diff --git a/docs/mfc/two-ways-to-create-a-carchive-object.md b/docs/mfc/two-ways-to-create-a-carchive-object.md index 9347fd20f75..b63004007b1 100644 --- a/docs/mfc/two-ways-to-create-a-carchive-object.md +++ b/docs/mfc/two-ways-to-create-a-carchive-object.md @@ -3,10 +3,12 @@ description: "Learn more about: Two Ways to Create a CArchive Object" title: "Two Ways to Create a CArchive Object" ms.date: "11/04/2016" helpviewer_keywords: ["CArchive class [MFC], closing CArchive objects", "CArchive objects [MFC], closing", "I/O [MFC], creating CArchive objects", "serialization [MFC], CArchive class", "CArchive objects [MFC]", "storage [MFC], CArchive class [MFC]", "data storage [MFC], CArchive class", "CArchive class [MFC], constructor"] -ms.assetid: aefa28ce-b55c-40dc-9e42-5f038030985d --- # Two Ways to Create a CArchive Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are two ways to create a `CArchive` object: - [Implicit creation of a CArchive object via the framework](#_core_implicit_creation_of_a_carchive_object_via_the_framework) diff --git a/docs/mfc/type-safe-access-to-controls-in-a-dialog-box.md b/docs/mfc/type-safe-access-to-controls-in-a-dialog-box.md index 0e628e5526b..1154f42ac06 100644 --- a/docs/mfc/type-safe-access-to-controls-in-a-dialog-box.md +++ b/docs/mfc/type-safe-access-to-controls-in-a-dialog-box.md @@ -3,10 +3,12 @@ description: "Learn more about: Type-Safe Access to Controls in a Dialog Box" title: "Type-Safe Access to Controls in a Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["common controls [MFC], in dialog boxes", "Windows common controls [MFC], in dialog boxes", "safe access to dialog box controls", "dialog boxes [MFC], type-safe access to controls", "controls [MFC], accessing in dialog boxes", "type-safe access to dialog box controls", "MFC dialog boxes [MFC], type-safe access to controls"] -ms.assetid: 67021025-dd93-4d6a-8bed-a1348fe50685 --- # Type-Safe Access to Controls in a Dialog Box +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The controls in a dialog box can use the interfaces of MFC control classes such as `CListBox` and `CEdit`. You can create a control object and attach it to a dialog control. Then you can access the control through its class interface, calling member functions to operate on the control. The methods described here are designed to give you type-safe access to a control. This is especially useful for controls such as edit boxes and list boxes. There are two approaches to making a connection between a control in a dialog box and a C++ control member variable in a `CDialog`-derived class: diff --git a/docs/mfc/type-safe-access-to-controls-with-code-wizards.md b/docs/mfc/type-safe-access-to-controls-with-code-wizards.md index 0ac28da3350..56892af1285 100644 --- a/docs/mfc/type-safe-access-to-controls-with-code-wizards.md +++ b/docs/mfc/type-safe-access-to-controls-with-code-wizards.md @@ -3,10 +3,12 @@ description: "Learn more about: Type-Safe Access to Controls With Code Wizards" title: "Type-Safe Access to Controls With Code Wizards" ms.date: "11/04/2016" helpviewer_keywords: ["DDX (dialog data exchange), access to controls", "code wizards", "dialog boxes [MFC], access to controls", "dialog box controls [MFC], accessing"] -ms.assetid: b8874393-ee48-4124-8d78-e3648a7e29b9 --- # Type-Safe Access to Controls With Code Wizards +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you are familiar with DDX features, you can use the Control property in the [Add Member Variable Wizard](../ide/adding-a-member-variable-visual-cpp.md#add-member-variable-wizard) to create type-safe access. This approach is easier than creating controls without code wizards. If you simply want access to a control's value, DDX provides it. If you want to do more than access a control's value, use the Add Member Variable Wizard to add a member variable of the appropriate class to your dialog class. Attach this member variable to the Control property. diff --git a/docs/mfc/type-safe-access-to-controls-without-code-wizards.md b/docs/mfc/type-safe-access-to-controls-without-code-wizards.md index 6783fcc6296..613307d7c10 100644 --- a/docs/mfc/type-safe-access-to-controls-without-code-wizards.md +++ b/docs/mfc/type-safe-access-to-controls-without-code-wizards.md @@ -3,10 +3,12 @@ description: "Learn more about: Type-Safe Access to Controls Without Code Wizard title: "Type-Safe Access to Controls Without Code Wizards" ms.date: "11/04/2016" helpviewer_keywords: ["dialog boxes [MFC], accessing controls", "dialog box controls [MFC], accessing"] -ms.assetid: 325b4927-d49b-42b4-8e0b-fc84f31fb059 --- # Type-Safe Access to Controls Without Code Wizards +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The first approach to creating type-safe access to controls uses an inline member function to cast the return type of class `CWnd`'s `GetDlgItem` member function to the appropriate C++ control type, as in this example: [!code-cpp[NVC_MFCControlLadenDialog#50](../mfc/codesnippet/cpp/type-safe-access-to-controls-without-code-wizards_1.cpp)] diff --git a/docs/mfc/types-of-image-lists.md b/docs/mfc/types-of-image-lists.md index 3ed02c1d59a..d93ce25d1c3 100644 --- a/docs/mfc/types-of-image-lists.md +++ b/docs/mfc/types-of-image-lists.md @@ -3,10 +3,12 @@ description: "Learn more about: Types of Image Lists" title: "Types of Image Lists" ms.date: "11/04/2016" helpviewer_keywords: ["lists [MFC], image", "image lists [MFC], types of", "CImageList class [MFC], types"] -ms.assetid: bee5e7c3-78f5-4037-a136-9c50d67cdee5 --- # Types of Image Lists +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + There are two types of image lists ([CImageList](../mfc/reference/cimagelist-class.md)): nonmasked and masked. A "nonmasked image list" consists of a color bitmap that contains one or more images. A "masked image list" consists of two bitmaps of equal size. The first is a color bitmap that contains the images, and the second is a monochrome bitmap that contains a series of masks — one for each image in the first bitmap. One of the overloads of the `Create` member function takes a flag to indicate whether or not the image list is masked. (The other overloads create masked image lists.) diff --git a/docs/mfc/updating-the-text-of-a-status-bar-pane.md b/docs/mfc/updating-the-text-of-a-status-bar-pane.md index 389cc228367..e77e2921ab3 100644 --- a/docs/mfc/updating-the-text-of-a-status-bar-pane.md +++ b/docs/mfc/updating-the-text-of-a-status-bar-pane.md @@ -3,10 +3,13 @@ description: "Learn more about: Updating the Text of a Status-Bar Pane" title: "Updating the Text of a Status-Bar Pane" ms.date: "11/04/2016" helpviewer_keywords: ["updating user interface objects [MFC]", "ON_UPDATE_COMMAND_UI macro [MFC]", "user interface objects [MFC], updating", "text, status bar", "CStatusBar class [MFC], updating", "SetText method [MFC]", "panes, status bar", "status bars [MFC], updating"] -ms.assetid: 4984a3f4-9905-4d8c-a927-dca19781053b +ms.topic: how-to --- # Updating the Text of a Status-Bar Pane +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how to change the text that appears in an MFC status bar pane. A status bar — a window object of class [CStatusBar](../mfc/reference/cstatusbar-class.md) — contains several "panes." Each pane is a rectangular area of the status bar that you can use to display information. For example, many applications display the status of the CAPS LOCK, NUM LOCK, and other keys in the rightmost panes. Applications also often display informative text in the leftmost pane (pane 0), sometimes called the "message pane." For example, the default MFC status bar uses the message pane to display a string explaining the currently selected menu item or toolbar button. The figure in [Status Bars](../mfc/status-bar-implementation-in-mfc.md) shows a status bar from an Application Wizard-created MFC application. By default, MFC does not enable a `CStatusBar` pane when it creates the pane. To activate a pane, you must use the ON_UPDATE_COMMAND_UI macro for each pane on the status bar and update the panes. Because panes do not send WM_COMMAND messages (they aren't like toolbar buttons), you must type the code manually. diff --git a/docs/mfc/upgrading-an-existing-activex-control.md b/docs/mfc/upgrading-an-existing-activex-control.md index e2b88e3db99..5af223c224e 100644 --- a/docs/mfc/upgrading-an-existing-activex-control.md +++ b/docs/mfc/upgrading-an-existing-activex-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Upgrading an Existing ActiveX Control" title: "Upgrading an Existing ActiveX Control" ms.date: 11/03/2021 helpviewer_keywords: ["ActiveX controls [MFC], Internet", "LPK files for Internet controls", "safe for scripting and initialization (controls)", "OLE controls [MFC], upgrading to ActiveX", "CAB files, for ActiveX controls", "Internet applications [MFC], ActiveX controls", "Internet applications [MFC], packaging code for download", "upgrading ActiveX controls", "licensing ActiveX controls"] -ms.assetid: 4d12ddfa-b491-4f9f-a0b7-b51458e05651 +ms.topic: how-to --- # Upgrading an Existing ActiveX Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Existing ActiveX controls (formerly OLE controls) can be used on the Internet without modification. However, you may want to modify controls to improve their performance. > [!IMPORTANT] @@ -47,7 +50,7 @@ CODEBASE="http://example.contoso.com/mycontrol.ocx#version=4, 1086" ``` -This solution downloads only the control's .ocx file, and requires any supporting DLLs to already be installed on the client machine. This will work for Internet Explorer and MFC ActiveX controls built with Visual C++, because Internet Explorer ships with the supporting DLLs for Visual C++ controls. If another Internet browser that is ActiveX control-capable is used to view this control, this solution will not work. +This solution downloads only the control's .ocx file, and requires any supporting DLLs to already be installed on the client machine. This will work for Internet Explorer and MFC ActiveX controls built with Visual Studio, because Internet Explorer ships with the supporting DLLs for Visual Studio controls. If another Internet browser that is ActiveX control-capable is used to view this control, this solution will not work. ### Using the CODEBASE Tag with an INF File @@ -157,7 +160,7 @@ HKEY_CLASSES_ROOT\CLSID\{06889605-B8D0-101A-91F1-00608CEAD5B3}\Implemented Categ If you want to use a licensed control on a Web page, you must verify that the license agreement allows its use on the Internet and create a license package file (LPK) for it. -A licensed ActiveX control will not load properly in an HTML page if the computer running Internet Explorer is not licensed to use the control. For example, if a licensed control was built using Visual C++, the HTML page using the control will load properly on the computer where the control was built, but it will not load on a different computer unless licensing information is included. +A licensed ActiveX control will not load properly in an HTML page if the computer running Internet Explorer is not licensed to use the control. For example, if a licensed control was built using Visual Studio, the HTML page using the control will load properly on the computer where the control was built, but it will not load on a different computer unless licensing information is included. To use a licensed ActiveX control in Internet Explorer, you must check the vendor's license agreement to verify that the license for the control permits: diff --git a/docs/mfc/user-defined-tools.md b/docs/mfc/user-defined-tools.md index 9f477181081..e29719954c4 100644 --- a/docs/mfc/user-defined-tools.md +++ b/docs/mfc/user-defined-tools.md @@ -3,10 +3,12 @@ description: "Learn more about: User-defined Tools" title: "User-defined Tools" ms.date: "11/19/2018" helpviewer_keywords: ["user-defined tools (MFC Extensions)"] -ms.assetid: cb887421-78ce-4652-bc67-96a53984ccaa --- # User-defined Tools +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC supports user-defined tools. A user-defined tool is a special command that executes an external, user-specified program. You can use the customization process to manage user-defined tools. However, you cannot use this process if your application object is not derived from [CWinAppEx Class](../mfc/reference/cwinappex-class.md). For more information about customization, see [Customization for MFC](../mfc/customization-for-mfc.md). If you enabled user-defined tools support, the customization dialog box automatically includes the **Tools** tab. The following illustration shows the **Tools** page. diff --git a/docs/mfc/user-interface-elements-mfc.md b/docs/mfc/user-interface-elements-mfc.md index a4c20c415e1..fb716052e9a 100644 --- a/docs/mfc/user-interface-elements-mfc.md +++ b/docs/mfc/user-interface-elements-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: User Interface Elements (MFC)" title: "User Interface Elements (MFC)" ms.date: "11/04/2016" helpviewer_keywords: ["MFC, user interface", "user interfaces, creating", "user interfaces"] -ms.assetid: f5daf2c1-bc08-4b71-9b03-da2c0aab5764 --- # User Interface Elements (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + For information about how to create the user interface for your application by using the Microsoft Foundation Class (MFC) Library, see the following topics. ## In This Section diff --git a/docs/mfc/user-interface-objects-and-command-ids.md b/docs/mfc/user-interface-objects-and-command-ids.md index 25183aea048..ec45364b2e3 100644 --- a/docs/mfc/user-interface-objects-and-command-ids.md +++ b/docs/mfc/user-interface-objects-and-command-ids.md @@ -3,10 +3,12 @@ description: "Learn more about: User-Interface Objects and Command IDs" title: "User-Interface Objects and Command IDs" ms.date: "11/19/2018" helpviewer_keywords: ["keyboard shortcuts, associating with IDs", "MFC, command routing", "toolbar controls [MFC], command ID", "menu items, associating with IDs", "user interface objects [MFC], associating with IDs", "command IDs, user interface objects", "command routing [MFC], MFC", "command handling [MFC], user-interface objects"] -ms.assetid: 4ea19e9b-ed1e-452e-bd33-7f509107a45b --- # User-Interface Objects and Command IDs +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Menu items, toolbar buttons, and accelerator keys are "user-interface objects" capable of generating commands. Each such user-interface object has an ID. You associate a user-interface object with a command by assigning the same ID to the object and the command. As explained in [Messages](../mfc/messages.md), commands are implemented as special messages. The figure "Commands in the Framework" below shows how the framework manages commands. When a user-interface object generates a command, such as `ID_EDIT_CLEAR_ALL`, one of the objects in your application handles the command — in the figure below, the document object's `OnEditClearAll` function is called via the document's message map. ![Commands in the Framework.](../mfc/media/vc385p1.gif "Commands in the Framework")
diff --git a/docs/mfc/using-a-common-control-as-a-child-window.md b/docs/mfc/using-a-common-control-as-a-child-window.md index b51b02f859c..8e0cd9bb980 100644 --- a/docs/mfc/using-a-common-control-as-a-child-window.md +++ b/docs/mfc/using-a-common-control-as-a-child-window.md @@ -3,10 +3,13 @@ description: "Learn more about: Using a Common Control as a Child Window" title: "Using a Common Control as a Child Window" ms.date: "11/04/2016" helpviewer_keywords: ["controls [MFC], using as child windows", "windows [MFC], common controls as", "child windows [MFC], common controls as", "common controls [MFC], child windows", "Windows common controls [MFC], child windows"] -ms.assetid: 608f7d47-7854-4fce-bde9-856c51e76753 +ms.topic: how-to --- # Using a Common Control as a Child Window +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Any of the Windows common controls can be used as a child window of any other window. The following procedure describes how to create a common control dynamically and then work with it. ### To use a common control as a child window diff --git a/docs/mfc/using-a-dialog-bar-with-a-rebar-control.md b/docs/mfc/using-a-dialog-bar-with-a-rebar-control.md index ca097e6d626..d96d2431b8b 100644 --- a/docs/mfc/using-a-dialog-bar-with-a-rebar-control.md +++ b/docs/mfc/using-a-dialog-bar-with-a-rebar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Using a Dialog Bar with a Rebar Control" title: "Using a Dialog Bar with a Rebar Control" ms.date: "11/04/2016" helpviewer_keywords: ["WS_EX_TRANSPARENT style", "rebar controls [MFC], dialog bars", "dialog bars [MFC], using with rebar bands"] -ms.assetid: e528cea0-6b81-4bdf-9643-7c03b6176590 +ms.topic: how-to --- # Using a Dialog Bar with a Rebar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + As mentioned in [Rebar Controls and Bands](../mfc/rebar-controls-and-bands.md), each band can contain only one child window (or control). This might be a limitation if you want to have more than one child window per band. A convenient workaround is to create a dialog bar resource with multiple controls and then add a rebar band (containing the dialog bar) to the rebar control. Normally, if you wanted the dialog bar band to appear transparent, you would set the WS_EX_TRANSPARENT extended style for the dialog bar object. However, because WS_EX_TRANSPARENT has some issues with properly painting the background of a dialog bar, you will need to do a little extra work to achieve the desired effect. diff --git a/docs/mfc/using-a-dialog-template-in-memory.md b/docs/mfc/using-a-dialog-template-in-memory.md index 944130b91b0..5be7e52e6a5 100644 --- a/docs/mfc/using-a-dialog-template-in-memory.md +++ b/docs/mfc/using-a-dialog-template-in-memory.md @@ -3,10 +3,13 @@ description: "Learn more about: Using a Dialog Template in Memory" title: "Using a Dialog Template in Memory" ms.date: "11/04/2016" helpviewer_keywords: ["templates [MFC], for dialog boxes", "dialog templates [MFC]", "dialog templates [MFC], in memory", "MFC dialog boxes [MFC], dialog templates"] -ms.assetid: edb443bb-e614-4f77-8a3b-74d93871e9bd +ms.topic: concept-article --- # Using a Dialog Template in Memory +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Instead of using the methods given in the [Dialog Creation table](../mfc/creating-a-dialog-class-with-code-wizards.md), you can create either kind of dialog box indirectly from a dialog template in memory. For more information, see class [CDialog](../mfc/reference/cdialog-class.md) in the *MFC Reference*. ## See also diff --git a/docs/mfc/using-a-hot-key-control.md b/docs/mfc/using-a-hot-key-control.md index 64a2fe30c91..2ecb69d51f2 100644 --- a/docs/mfc/using-a-hot-key-control.md +++ b/docs/mfc/using-a-hot-key-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Using a Hot Key Control" title: "Using a Hot Key Control" ms.date: "11/04/2016" helpviewer_keywords: ["CHotKeyCtrl class [MFC], using", "hot key controls"] -ms.assetid: cdd6524b-cc43-447f-b151-164273559685 +ms.topic: concept-article --- # Using a Hot Key Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Typical usage of a hot key control follows the pattern below: - The control is created. If the control is specified in a dialog box template, creation is automatic when the dialog box is created. (You should have a [CHotKeyCtrl](../mfc/reference/chotkeyctrl-class.md) member in your dialog class that corresponds to the hot key control.) Alternatively, you can use the [Create](../mfc/reference/chotkeyctrl-class.md#create) member function to create the control as a child window of any window. diff --git a/docs/mfc/using-an-animation-control.md b/docs/mfc/using-an-animation-control.md index cbf09f8efee..39919ad405b 100644 --- a/docs/mfc/using-an-animation-control.md +++ b/docs/mfc/using-an-animation-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Using an Animation Control" title: "Using an Animation Control" ms.date: "11/04/2016" helpviewer_keywords: ["controls [MFC], animation", "CAnimateCtrl class [MFC], animation controls", "animation controls [MFC]"] -ms.assetid: a009a464-e12d-4112-bf52-04a09b28dd88 +ms.topic: concept-article --- # Using an Animation Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Typical usage of an animation control follows the pattern below: - The control is created. If the control is specified in a dialog box template, creation is automatic when the dialog box is created. (You should have a [CAnimateCtrl](../mfc/reference/canimatectrl-class.md) member in your dialog class that corresponds to the animation control.) Alternatively, you can use the [Create](../mfc/reference/canimatectrl-class.md#create) member function to create the control as a child window of any window. diff --git a/docs/mfc/using-an-image-list-with-a-rebar-control.md b/docs/mfc/using-an-image-list-with-a-rebar-control.md index 2c8d693dc63..9e60de4bb38 100644 --- a/docs/mfc/using-an-image-list-with-a-rebar-control.md +++ b/docs/mfc/using-an-image-list-with-a-rebar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Using an Image List with a Rebar Control" title: "Using an Image List with a Rebar Control" ms.date: "11/04/2016" helpviewer_keywords: ["image lists [MFC], rebar controls", "rebar controls [MFC], image lists"] -ms.assetid: 1a5836ac-019a-46aa-8741-b35c3376b839 +ms.topic: how-to --- # Using an Image List with a Rebar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Each rebar band can contain, among other things, an image from an associated image list. The following procedure details the necessary steps for displaying an image in a rebar band. ### To display images in a rebar band diff --git a/docs/mfc/using-an-image-list.md b/docs/mfc/using-an-image-list.md index 4796e5b6fbb..5eac2d45cf2 100644 --- a/docs/mfc/using-an-image-list.md +++ b/docs/mfc/using-an-image-list.md @@ -3,10 +3,13 @@ description: "Learn more about: Using an Image List" title: "Using an Image List" ms.date: "11/04/2016" helpviewer_keywords: ["lists [MFC], image", "CImageList class [MFC], using", "image lists [MFC]"] -ms.assetid: e0aed188-a1e6-400e-9f51-033d61c5541f +ms.topic: concept-article --- # Using an Image List +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Typical usage of an image list follows the pattern below: - Construct a [CImageList](../mfc/reference/cimagelist-class.md) object and call one of the overloads of its [Create](../mfc/reference/cimagelist-class.md#create) function to create an image list and attach it to the `CImageList` object. diff --git a/docs/mfc/using-an-unclipped-device-context.md b/docs/mfc/using-an-unclipped-device-context.md index 9b81ba4268a..6e2d218703e 100644 --- a/docs/mfc/using-an-unclipped-device-context.md +++ b/docs/mfc/using-an-unclipped-device-context.md @@ -3,10 +3,13 @@ description: "Learn more about: Using an Unclipped Device Context" title: "Using an Unclipped Device Context" ms.date: "11/04/2016" helpviewer_keywords: ["MFC ActiveX controls [MFC], unclipped device context"] -ms.assetid: 9c020063-73da-4803-bf7b-2e1fd950c9ed +ms.topic: concept-article --- # Using an Unclipped Device Context +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + If you are absolutely certain that your control does not paint outside its client rectangle, you can realize a small but detectable speed gain by disabling the call to `IntersectClipRect` that is made by `COleControl`. To do this, remove the *clipPaintDC* flag from the set of flags returned by [COleControl::GetControlFlags](../mfc/reference/colecontrol-class.md#getcontrolflags). For example: [!code-cpp[NVC_MFC_AxOpt#5](../mfc/codesnippet/cpp/using-an-unclipped-device-context_1.cpp)] diff --git a/docs/mfc/using-callback-fields-in-a-date-and-time-picker-control.md b/docs/mfc/using-callback-fields-in-a-date-and-time-picker-control.md index 1b2bf9f7f1d..bc01e6ebe10 100644 --- a/docs/mfc/using-callback-fields-in-a-date-and-time-picker-control.md +++ b/docs/mfc/using-callback-fields-in-a-date-and-time-picker-control.md @@ -4,10 +4,13 @@ title: "Using Callback Fields in a Date and Time Picker Control" ms.date: "11/04/2016" f1_keywords: ["DTN_FORMATQUERY", "DTN_FORMAT"] helpviewer_keywords: ["DateTimePicker control [MFC], callback fields", "callback fields in CDateTimeCtrl class [MFC]", "CDateTimeCtrl class [MFC], callback fields", "CDateTimeCtrl class [MFC], handling DTN_FORMAT and DTN_FORMATQ", "DTN_FORMATQUERY notification [MFC]", "DTN_FORMAT notification [MFC]", "DateTimePicker control [MFC]"] -ms.assetid: 404f4ba9-cba7-4718-9faa-bc6b274a723f +ms.topic: concept-article --- # Using Callback Fields in a Date and Time Picker Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In addition to the standard format characters that define date and time picker fields, you can customize your output by specifying certain parts of a custom format string as callback fields. To declare a callback field, include one or more "X" characters (ASCII Code 88) anywhere in the body of the format string. For example, the following string "'Today is: 'yy'/'MM'/'dd' (Day 'X')'"causes the date and time picker control to display the current value as the year followed by the month, date, and finally the day of the year. > [!NOTE] diff --git a/docs/mfc/using-canimatectrl.md b/docs/mfc/using-canimatectrl.md index 7c02d4b52bf..f22e7a7519b 100644 --- a/docs/mfc/using-canimatectrl.md +++ b/docs/mfc/using-canimatectrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CAnimateCtrl" title: "Using CAnimateCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["animation controls [MFC], CAnimateCtrl class", "controls [MFC], animation", "CAnimateCtrl class [MFC], about CAnimateCtrl class [MFC]"] -ms.assetid: 696c0805-bef0-4e2e-a9e7-b37b9215b7f0 +ms.topic: concept-article --- # Using CAnimateCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An animation control, represented by the class [CAnimateCtrl](../mfc/reference/canimatectrl-class.md), is a window that displays a clip in Audio Video Interleaved (AVI) format — the standard Windows video/audio format. An AVI clip is a series of bitmap frames, like a movie. Since your thread continues executing while the AVI clip is displayed, one common use for an animation control is to indicate system activity during a lengthy operation. For example, the Windows Find dialog box displays a moving magnifying glass as the system searches for a file. diff --git a/docs/mfc/using-ccomboboxex.md b/docs/mfc/using-ccomboboxex.md index a0ccb2ebc22..bed47613510 100644 --- a/docs/mfc/using-ccomboboxex.md +++ b/docs/mfc/using-ccomboboxex.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CComboBoxEx" title: "Using CComboBoxEx" ms.date: "11/04/2016" helpviewer_keywords: ["combo boxes [MFC], extended", "extended combo boxes [MFC], about extended combo boxes", "combo boxes [MFC], CComboBoxEx class", "CComboBox class [MFC], extended"] -ms.assetid: c23cbfe8-75d2-4f98-a753-c942416eda52 +ms.topic: concept-article --- # Using CComboBoxEx +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The extended combo box control is an extension of the standard combo box control that provides native support for item images. These images can be used to indicate the status of individual items in the combo box, such as the currently selected and unselected items. To make item images easily accessible, the control provides image list support. Use this control to provide the functionality of a combo box without having to manually draw item graphics. diff --git a/docs/mfc/using-cdatetimectrl.md b/docs/mfc/using-cdatetimectrl.md index 1dc32ef93b9..de67e342135 100644 --- a/docs/mfc/using-cdatetimectrl.md +++ b/docs/mfc/using-cdatetimectrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CDateTimeCtrl" title: "Using CDateTimeCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["DateTimePicker control [MFC], CDateTimeCtrl class"] -ms.assetid: cb2a8720-43f1-4c33-a3a4-def9a1622e00 +ms.topic: concept-article --- # Using CDateTimeCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The date and time picker control ([CDateTimeCtrl](../mfc/reference/cdatetimectrl-class.md)) implements an intuitive and recognizable method of entering or selecting a specific date. The main interface of the control is similar in functionality to a combo box. However, if the user expands the control, a month calendar control appears (by default), allowing the user to specify a particular date. When a date is chosen, the month calendar control automatically disappears. > [!NOTE] diff --git a/docs/mfc/using-cheaderctrl.md b/docs/mfc/using-cheaderctrl.md index f5d2df5c64a..f2b2ef3eb29 100644 --- a/docs/mfc/using-cheaderctrl.md +++ b/docs/mfc/using-cheaderctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CHeaderCtrl" title: "Using CHeaderCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["header controls [MFC], using", "CHeaderCtrl class [MFC]"] -ms.assetid: fb3e512b-9539-43c4-a7e7-3fafd6d0706e +ms.topic: concept-article --- # Using CHeaderCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use a header control, represented by class [CHeaderCtrl](../mfc/reference/cheaderctrl-class.md), to display column headers for a columnar list. For example, a header control would be useful for implementing column controls in a spreadsheet. The header control is usually divided into parts, called "header items," each bearing a title for the associated column of text or numbers. Depending on the styles you set, you can provide a number of direct ways for users to manipulate the header items. diff --git a/docs/mfc/using-chotkeyctrl.md b/docs/mfc/using-chotkeyctrl.md index 051b6ffdb9d..f3f757de784 100644 --- a/docs/mfc/using-chotkeyctrl.md +++ b/docs/mfc/using-chotkeyctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CHotKeyCtrl" title: "Using CHotKeyCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["keys, hot and CHotKeyCtrl", "CHotKeyCtrl class [MFC], using", "hot key controls"] -ms.assetid: 9b207117-d848-4224-8888-c3d197bb0c95 +ms.topic: concept-article --- # Using CHotKeyCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A hot key control, represented by class [CHotKeyCtrl](../mfc/reference/chotkeyctrl-class.md), is a window that displays a text representation of the key combination the user types into it, such as CTRL+SHIFT+Q. It also maintains an internal representation of this key in the form of a virtual key code and a set of flags that represent the shift state. The hot key control does not actually set the hot key — doing that is up to your program. (For a list of standard virtual key codes, see Winuser.h.) Use a hot key control to get a user's input for which hot key to associate with a window or thread. Hot key controls are often used in dialog boxes, such as you might display when asking the user to assign a hot key. It is your program's responsibility to retrieve the values describing the hot key from the hot key control and to call the appropriate functions to associate the hot key with a window or thread. diff --git a/docs/mfc/using-cimagelist.md b/docs/mfc/using-cimagelist.md index 45fcf927268..e9042469157 100644 --- a/docs/mfc/using-cimagelist.md +++ b/docs/mfc/using-cimagelist.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CImageList" title: "Using CImageList" ms.date: "11/04/2016" helpviewer_keywords: ["image list control", "CImageList class [MFC], using"] -ms.assetid: 3d2a909e-d641-46b7-aada-81cab1a29b41 +ms.topic: concept-article --- # Using CImageList +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An image list, represented by class [CImageList](../mfc/reference/cimagelist-class.md), is a collection of same-sized images, each of which can be referred to by its index. Image lists are used to efficiently manage large sets of icons or bitmaps. Image lists are not themselves controls since they are not windows; however, they are used with several different types of controls, including list controls ([CListCtrl](../mfc/reference/clistctrl-class.md)), tree controls ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)), and tab controls ([CTabCtrl](../mfc/reference/ctabctrl-class.md)). All images in an image list are contained in a single, wide bitmap in screen-device format. An image list may also include a monochrome bitmap that contains masks used to draw images transparently (icon style). `CImageList` provides member functions that enable you to draw images, create and destroy image lists, add and remove images, replace images, merge images, and drag images. diff --git a/docs/mfc/using-clistctrl.md b/docs/mfc/using-clistctrl.md index ea7188aea4f..afb3b2c7928 100644 --- a/docs/mfc/using-clistctrl.md +++ b/docs/mfc/using-clistctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CListCtrl" title: "Using CListCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CListCtrl class [MFC], using"] -ms.assetid: 20d6a5d6-8f07-4ddf-975f-ea2dfebcc835 +ms.topic: concept-article --- # Using CListCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Use a list control to display any arrangement of icons with labels, as in File Explorer, or columnar lists of text, with or without icons. For a description of the four possible "views" (not to be confused with MFC views) you can have in a list control — icon view, small icon view, list view, and report view — see Views in the [CListCtrl](../mfc/reference/clistctrl-class.md) class overview. In some views, users can drag icons to different positions or edit icon labels. For example, see the right-hand pane in File Explorer, which uses a list control in a nondialog window. You can experiment with the available views in Explorer's View menu. diff --git a/docs/mfc/using-cmonthcalctrl.md b/docs/mfc/using-cmonthcalctrl.md index 77869ba574a..b61d0562f7e 100644 --- a/docs/mfc/using-cmonthcalctrl.md +++ b/docs/mfc/using-cmonthcalctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CMonthCalCtrl" title: "Using CMonthCalCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CMonthCalCtrl class [MFC], about CMonthCalCtrl class"] -ms.assetid: 2be0e8c2-ed03-4853-aea1-4461eba18611 +ms.topic: concept-article --- # Using CMonthCalCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The month calendar control ([CMonthCalCtrl](../mfc/reference/cmonthcalctrl-class.md)) implements a calendar-like user interface. This provides the user with a very intuitive and recognizable method of entering or selecting a date. The control also provides the application with the means to obtain and set the date information in the control using existing data types. By default, the month calendar control displays the current day and month. However, the user is able to scroll to the previous and next months and select a specific month and/or year. > [!NOTE] diff --git a/docs/mfc/using-cobject.md b/docs/mfc/using-cobject.md index af6529ea21d..0b1071f2035 100644 --- a/docs/mfc/using-cobject.md +++ b/docs/mfc/using-cobject.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CObject" title: "Using CObject" ms.date: "11/04/2016" helpviewer_keywords: ["examples [MFC], CObject", "root base class for MFC", "derived classes [MFC], from CObject", "MFC, base class", "CObject class [MFC]"] -ms.assetid: d0cd19bb-2856-4b41-abbc-620fd64cb223 +ms.topic: concept-article --- # Using CObject +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [CObject](../mfc/reference/cobject-class.md) is the root base class for most of the Microsoft Foundation Class Library (MFC). The `CObject` class contains many useful features that you may want to incorporate into your own program objects, including serialization support, run-time class information, and object diagnostic output. If you derive your class from `CObject`, your class can exploit these `CObject` features. ## What do you want to do diff --git a/docs/mfc/using-common-controls-in-a-dialog-box.md b/docs/mfc/using-common-controls-in-a-dialog-box.md index 6caadbbe11b..e4d84c57642 100644 --- a/docs/mfc/using-common-controls-in-a-dialog-box.md +++ b/docs/mfc/using-common-controls-in-a-dialog-box.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Common Controls in a Dialog Box" title: "Using Common Controls in a Dialog Box" ms.date: "11/04/2016" helpviewer_keywords: ["common controls [MFC], in dialog boxes", "dialog box controls [MFC], common controls", "Windows common controls [MFC], in dialog boxes"] -ms.assetid: 17713caf-09f8-484a-bf54-5f48bf09cce9 +ms.topic: how-to --- # Using Common Controls in a Dialog Box +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Windows common controls can be used in [dialog boxes](../mfc/dialog-boxes.md), form views, record views, and any other window based on a dialog template. The following procedure, with minor changes, will work for forms as well. ## Procedures diff --git a/docs/mfc/using-cprogressctrl.md b/docs/mfc/using-cprogressctrl.md index 884b121ca0a..db9747fac63 100644 --- a/docs/mfc/using-cprogressctrl.md +++ b/docs/mfc/using-cprogressctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CProgressCtrl" title: "Using CProgressCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["progress controls [MFC]", "CProgressCtrl class [MFC], using", "progress controls [MFC], CProgressCtrl", "progress controls [MFC], using"] -ms.assetid: 61473270-196b-41ab-bf2b-467f46673539 +ms.topic: concept-article --- # Using CProgressCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use the progress control to indicate the progress of a lengthy operation. It is a rectangle that is gradually filled with the system highlight color as the operation progresses. The progress control is represented in MFC by class [CProgressCtrl](../mfc/reference/cprogressctrl-class.md). diff --git a/docs/mfc/using-crebarctrl.md b/docs/mfc/using-crebarctrl.md index c77177533ab..4100cc50206 100644 --- a/docs/mfc/using-crebarctrl.md +++ b/docs/mfc/using-crebarctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CReBarCtrl" title: "Using CReBarCtrl" ms.date: "11/19/2018" helpviewer_keywords: ["child windows [MFC], rebar controls", "combo boxes [MFC], in rebar controls", "rebar controls"] -ms.assetid: 2c0aeec2-ffc3-44b8-97b5-0f56e116a338 +ms.topic: concept-article --- # Using CReBarCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A rebar control acts as a container for child windows. These child windows, often other controls, are assigned to a rebar control band. A rebar control can contain one or more bands, with each band having any combination of a gripper bar, a bitmap, a text label, and a child window. However, bands cannot contain more than one child window. The following illustration shows a rebar control that has two bands. One contains a gripper bar, a text label ("Address"), and a combo box child window. The other band contains a gripper bar, a text label, and a flat toolbar (implemented with a child window). diff --git a/docs/mfc/using-cricheditctrl.md b/docs/mfc/using-cricheditctrl.md index 5d14b8c84bb..e53c1400f84 100644 --- a/docs/mfc/using-cricheditctrl.md +++ b/docs/mfc/using-cricheditctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CRichEditCtrl" title: "Using CRichEditCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["rich edit controls [MFC], using", "CRichEditCtrl class [MFC], using"] -ms.assetid: e400c6ed-563e-4d4c-ab3b-a3f0aa20273b +ms.topic: concept-article --- # Using CRichEditCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A rich edit control is a window in which the user can enter and edit text. The text can be assigned character and paragraph formatting, and can include embedded OLE objects. The rich edit control is represented in MFC by the [CRichEditCtrl](../mfc/reference/cricheditctrl-class.md) class. ## What do you want to know more about diff --git a/docs/mfc/using-csliderctrl.md b/docs/mfc/using-csliderctrl.md index 0b1b04c8216..0bcaefe6cb7 100644 --- a/docs/mfc/using-csliderctrl.md +++ b/docs/mfc/using-csliderctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CSliderCtrl" title: "Using CSliderCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CSliderCtrl class [MFC], using", "slider controls [MFC], using"] -ms.assetid: 242c7bcd-126e-4b9b-8f76-8082ad06fe73 +ms.topic: concept-article --- # Using CSliderCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CSliderCtrl](../mfc/reference/csliderctrl-class.md) class represents a slider control, which is also called a trackbar. A "slider control" is a window that contains a slider and optional tick marks. When the user moves the slider, using either the mouse or the arrow keys, the slider control sends notification messages to indicate the change. Slider controls are useful when you want the user to select a discrete value or a set of consecutive values in a range. For example, you might use a slider control to allow the user to set the repeat rate of the keyboard by moving the slider to a given tick mark. diff --git a/docs/mfc/using-cspinbuttonctrl.md b/docs/mfc/using-cspinbuttonctrl.md index 7e1f5c444c9..a34cbab66da 100644 --- a/docs/mfc/using-cspinbuttonctrl.md +++ b/docs/mfc/using-cspinbuttonctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CSpinButtonCtrl" title: "Using CSpinButtonCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["up-down controls [MFC], spin button control", "up-down controls", "spin button control", "CSpinButtonCtrl class [MFC], using"] -ms.assetid: a91db36b-e11e-42ef-8e89-51915cc486d2 +ms.topic: concept-article --- # Using CSpinButtonCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The *spin button* control (also known as an *up-down* control) provides a pair of arrows that a user can click to adjust a value. This value is known as the *current position*. The position stays within the range of the spin button. When the user clicks the up arrow, the position moves toward the maximum; and when the user clicks the down arrow, the position moves toward the minimum. The spin button control is represented in MFC by the [CSpinButtonCtrl](../mfc/reference/cspinbuttonctrl-class.md) class. diff --git a/docs/mfc/using-cstatusbarctrl-to-create-a-cstatusbarctrl-object.md b/docs/mfc/using-cstatusbarctrl-to-create-a-cstatusbarctrl-object.md index c332a42a3e1..e1a227e63c5 100644 --- a/docs/mfc/using-cstatusbarctrl-to-create-a-cstatusbarctrl-object.md +++ b/docs/mfc/using-cstatusbarctrl-to-create-a-cstatusbarctrl-object.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CStatusBarCtrl to Create a CStatusBarCtrl title: "Using CStatusBarCtrl to Create a CStatusBarCtrl Object" ms.date: "11/04/2016" helpviewer_keywords: ["status bar controls [MFC], creating", "CStatusBarCtrl class [MFC], creating"] -ms.assetid: 365c2b65-12de-49e6-9a2e-416c6ee10d60 +ms.topic: how-to --- # Using CStatusBarCtrl to Create a CStatusBarCtrl Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Here is an example of a typical use of [CStatusBarCtrl](../mfc/reference/cstatusbarctrl-class.md): ### To use a status bar control with parts diff --git a/docs/mfc/using-cstatusbarctrl.md b/docs/mfc/using-cstatusbarctrl.md index b7805b4eb79..3f547a0312b 100644 --- a/docs/mfc/using-cstatusbarctrl.md +++ b/docs/mfc/using-cstatusbarctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CStatusBarCtrl" title: "Using CStatusBarCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CStatusBarCtrl class [MFC], using", "status bar controls [MFC], about status bar controls"] -ms.assetid: 08b39f83-580d-439a-b93e-7ef9e2a5702a +ms.topic: concept-article --- # Using CStatusBarCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use the status bar control ([CStatusBarCtrl](../mfc/reference/cstatusbarctrl-class.md)) to create a control window that reflects various kinds of status information about the application. The status window can be divided into parts that display more than one type of information. ## What do you want to know more about diff --git a/docs/mfc/using-ctabctrl.md b/docs/mfc/using-ctabctrl.md index 75006f68eb2..ce3200242ed 100644 --- a/docs/mfc/using-ctabctrl.md +++ b/docs/mfc/using-ctabctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CTabCtrl" title: "Using CTabCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CTabCtrl class [MFC], using", "tab controls [MFC], using"] -ms.assetid: 6bda6798-0085-4c09-a5ea-fe0e97af5c95 +ms.topic: concept-article --- # Using CTabCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A "tab control" is analogous to the dividers in a notebook or the labeled folders in a file cabinet. Use the tab control, represented by class [CTabCtrl](../mfc/reference/ctabctrl-class.md), to show multiple pages of information or controls to a user, one at a time, in a format that suggests a peer or logical relationship between each page. For more information on tab controls, see [Tab Controls](/windows/win32/Controls/tab-controls) in the Windows SDK. diff --git a/docs/mfc/using-ctoolbarctrl.md b/docs/mfc/using-ctoolbarctrl.md index 13abfe7b9e4..0322ea45f27 100644 --- a/docs/mfc/using-ctoolbarctrl.md +++ b/docs/mfc/using-ctoolbarctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CToolBarCtrl" title: "Using CToolBarCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CToolBarCtrl class [MFC]", "toolbar controls [MFC], creating"] -ms.assetid: 13cf3753-135b-4a3e-a850-ed30177fcf9d +ms.topic: concept-article --- # Using CToolBarCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use the toolbar control ([CToolBarCtrl](../mfc/reference/ctoolbarctrl-class.md)) to create a control window containing buttons and optional spaces. Each button in the toolbar control window sends a command message to the parent window as the user chooses it. Typically, the buttons in a toolbar correspond to items in the application's menu, providing an additional and more direct way for the user to access an application's commands. ## What do you want to know more about diff --git a/docs/mfc/using-ctooltipctrl-to-create-and-manipulate-a-ctooltipctrl-object.md b/docs/mfc/using-ctooltipctrl-to-create-and-manipulate-a-ctooltipctrl-object.md index 14c85737f80..8dc58397f7d 100644 --- a/docs/mfc/using-ctooltipctrl-to-create-and-manipulate-a-ctooltipctrl-object.md +++ b/docs/mfc/using-ctooltipctrl-to-create-and-manipulate-a-ctooltipctrl-object.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CToolTipCtrl to Create and Manipulate a CT title: "Using CToolTipCtrl to Create and Manipulate a CToolTipCtrl Object" ms.date: "11/04/2016" helpviewer_keywords: ["tool tips [MFC], creating", "CToolTipCtrl class [MFC], using"] -ms.assetid: 0a34583f-f66d-46a1-a239-31b80ea395ad +ms.topic: how-to --- # Using CToolTipCtrl to Create and Manipulate a CToolTipCtrl Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Here is an example of [CToolTipCtrl](../mfc/reference/ctooltipctrl-class.md) usage: ### To create and manipulate a CToolTipCtrl diff --git a/docs/mfc/using-ctooltipctrl.md b/docs/mfc/using-ctooltipctrl.md index edcd85851ea..bacc499c4bd 100644 --- a/docs/mfc/using-ctooltipctrl.md +++ b/docs/mfc/using-ctooltipctrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CToolTipCtrl" title: "Using CToolTipCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CToolTipCtrl class [MFC], creating tool tips", "CToolTipCtrl class"] -ms.assetid: 8fc58a04-4792-4223-a092-d349d11344da +ms.topic: concept-article --- # Using CToolTipCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The [CToolTipCtrl](../mfc/reference/ctooltipctrl-class.md) class encapsulates the functionality of a tool tip control, a small pop-up window that displays a single line of text describing the purpose of a tool in an application. A tool tip is hidden most of the time, appearing only when the user puts the cursor on a tool and leaves it there for approximately one-half second. The tool tip appears near the cursor and disappears when the user clicks a mouse button or moves the cursor off of the tool. ## What do you want to know more about diff --git a/docs/mfc/using-ctreectrl.md b/docs/mfc/using-ctreectrl.md index f7412fec528..8d379b429ba 100644 --- a/docs/mfc/using-ctreectrl.md +++ b/docs/mfc/using-ctreectrl.md @@ -3,10 +3,13 @@ description: "Learn more about: Using CTreeCtrl" title: "Using CTreeCtrl" ms.date: "11/04/2016" helpviewer_keywords: ["CTreeCtrl class [MFC], about CTreeCtrl", "tree controls [MFC], using"] -ms.assetid: 6a262f2c-3540-43e5-b03f-e4b6f9cb0325 +ms.topic: concept-article --- # Using CTreeCtrl +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A tree control, represented by the class [CTreeCtrl](../mfc/reference/ctreectrl-class.md), is a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and an optional bitmapped image, and each item can have a list of subitems associated with it. By clicking an item, the user can expand and collapse the associated list of subitems. The directory tree in the left-hand pane of File Explorer is an example of a tree control. ## What do you want to know more about diff --git a/docs/mfc/using-custom-format-strings-in-a-date-and-time-picker-control.md b/docs/mfc/using-custom-format-strings-in-a-date-and-time-picker-control.md index eae626975e7..1c22a9078aa 100644 --- a/docs/mfc/using-custom-format-strings-in-a-date-and-time-picker-control.md +++ b/docs/mfc/using-custom-format-strings-in-a-date-and-time-picker-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Custom Format Strings in a Date and Time P title: "Using Custom Format Strings in a Date and Time Picker Control" ms.date: "11/04/2016" helpviewer_keywords: ["CDateTimeCtrl class [MFC], display styles", "DateTimePicker control [MFC], display styles", "DateTimePicker control [MFC]"] -ms.assetid: 7d577f03-6ca0-4597-9093-50b78f304719 +ms.topic: concept-article --- # Using Custom Format Strings in a Date and Time Picker Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By default, date and time picker controls provide three format types (each format corresponding to a unique style) for displaying the current date or time: - **DTS_LONGDATEFORMAT** Displays the date in long format, producing output like "Wednesday, January 3, 2000". diff --git a/docs/mfc/using-documents.md b/docs/mfc/using-documents.md index aec24f4d756..f975b3b9f94 100644 --- a/docs/mfc/using-documents.md +++ b/docs/mfc/using-documents.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Documents" title: "Using Documents" ms.date: "11/04/2016" helpviewer_keywords: ["documents [MFC], C++ applications", "data [MFC], reading", "documents [MFC]", "files [MFC], writing to", "data [MFC], documents", "files [MFC]", "views [MFC], C++ applications", "document/view architecture [MFC], documents", "reading data [MFC], documents and views", "printing [MFC], documents", "writing to files [MFC]"] -ms.assetid: f390d6d8-d0e1-4497-9b6a-435f7ce0776c +ms.topic: concept-article --- # Using Documents +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Working together, documents and views: - Contain, manage, and display your application-specific [data](../mfc/managing-data-with-document-data-variables.md). diff --git a/docs/mfc/using-drop-down-buttons-in-a-toolbar-control.md b/docs/mfc/using-drop-down-buttons-in-a-toolbar-control.md index 818fa7efcfe..10ebb0f4aa4 100644 --- a/docs/mfc/using-drop-down-buttons-in-a-toolbar-control.md +++ b/docs/mfc/using-drop-down-buttons-in-a-toolbar-control.md @@ -4,10 +4,13 @@ title: "Using Drop-Down Buttons in a Toolbar Control" ms.date: "11/04/2016" f1_keywords: ["TBN_DROPDOWN", "TBSTYLE_EX_DRAWDDARROWS"] helpviewer_keywords: ["CToolBarCtrl class [MFC], drop-down buttons", "toolbars [MFC], drop-down buttons", "drop-down buttons in toolbars", "TBSTYLE_EX_DRAWDDARROWS", "TBN_DROPDOWN notification [MFC]"] -ms.assetid: b859f758-d2f6-40d9-9c26-0ff61993b9b2 +ms.topic: how-to --- # Using Drop-Down Buttons in a Toolbar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In addition to standard push buttons, a toolbar can also have drop-down buttons. A drop-down button is usually indicated by the presence of an attached down arrow. > [!NOTE] diff --git a/docs/mfc/using-frame-windows.md b/docs/mfc/using-frame-windows.md index e6d18fe0760..dc593d3783f 100644 --- a/docs/mfc/using-frame-windows.md +++ b/docs/mfc/using-frame-windows.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Frame Windows" title: "Using Frame Windows" ms.date: "11/04/2016" helpviewer_keywords: ["windows [MFC], frame windows", "frame windows [MFC], using", "MFC, frame windows"] -ms.assetid: 4d773238-11f6-4ccf-8114-57310c5aaa2d +ms.topic: concept-article --- # Using Frame Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The MFC framework creates document frame windows — and their views and documents — as part of its implementation of the New and Open commands on the File menu. Because the framework does most of the frame-window work for you, you play only a small role in creating, using, and destroying those windows. You can, however, explicitly create your own frame windows and child windows for special purposes. ## What do you want to know more about diff --git a/docs/mfc/using-image-lists-in-a-toolbar-control.md b/docs/mfc/using-image-lists-in-a-toolbar-control.md index efa816d9951..c8dd09a333f 100644 --- a/docs/mfc/using-image-lists-in-a-toolbar-control.md +++ b/docs/mfc/using-image-lists-in-a-toolbar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Image Lists in a Toolbar Control" title: "Using Image Lists in a Toolbar Control" ms.date: "11/04/2016" helpviewer_keywords: ["toolbar controls [MFC], image", "image lists [MFC], toolbar controls", "CToolBarCtrl class [MFC], image lists"] -ms.assetid: ccbe8df4-4ed9-4b54-bb93-9a1dcb3b97eb +ms.topic: concept-article --- # Using Image Lists in a Toolbar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + By default, the images used by the buttons in a toolbar control are stored as a single bitmap. However, you can also store button images in a set of image lists. The toolbar control object can use up to three separate image lists: - Enabled image list Contains images for toolbar buttons that are currently enabled. diff --git a/docs/mfc/using-image-lists-in-an-extended-combo-box-control.md b/docs/mfc/using-image-lists-in-an-extended-combo-box-control.md index 60f03d8ba45..4c3c8a928e5 100644 --- a/docs/mfc/using-image-lists-in-an-extended-combo-box-control.md +++ b/docs/mfc/using-image-lists-in-an-extended-combo-box-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Image Lists in an Extended Combo Box Contr title: "Using Image Lists in an Extended Combo Box Control" ms.date: "11/04/2016" helpviewer_keywords: ["image lists [MFC], combo boxes", "extended combo boxes [MFC], images", "images [MFC], combo box items"] -ms.assetid: dfff25fe-af70-47a2-8032-3901d1e6842d +ms.topic: how-to --- # Using Image Lists in an Extended Combo Box Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The main feature of extended combo box controls is the ability to associate images from an image list with individual items in a combo box control. Each item is able to display three different images: one for its selected state, one for its nonselected state, and a third for an overlay image. The following procedure associates an image list with an extended combo box control: diff --git a/docs/mfc/using-image-lists-with-header-controls.md b/docs/mfc/using-image-lists-with-header-controls.md index 346cef44bd1..76ea9410dc0 100644 --- a/docs/mfc/using-image-lists-with-header-controls.md +++ b/docs/mfc/using-image-lists-with-header-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Image Lists with Header Controls" title: "Using Image Lists with Header Controls" ms.date: "11/04/2016" helpviewer_keywords: ["header controls [MFC], image lists", "CHeaderCtrl class [MFC], image lists", "image lists [MFC], header controls"] -ms.assetid: d5e9b310-6278-406c-909c-eefa09549a47 +ms.topic: how-to --- # Using Image Lists with Header Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Header items have the ability to display an image within a header item. This image, stored in an associated image list, is 16 x 16 pixels and has the same characteristics as the icon images used in a list view control. In order to implement this behavior successfully, you must first create and initialize the image list, associate the list with the header control, and then modify the attributes of the header item that will display the image. The following procedure illustrates the details, using a pointer to a header control (`m_pHdrCtrl`) and a pointer to an image list (`m_pHdrImages`). diff --git a/docs/mfc/using-property-sheets-in-your-application.md b/docs/mfc/using-property-sheets-in-your-application.md index 618786b7ce7..dd89bad3850 100644 --- a/docs/mfc/using-property-sheets-in-your-application.md +++ b/docs/mfc/using-property-sheets-in-your-application.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Property Sheets in Your Application" title: "Using Property Sheets in Your Application" ms.date: "11/04/2016" helpviewer_keywords: ["dialog templates [MFC], property sheets", "dialog resources", "property pages [MFC], property sheets", "DoModal method property sheets", "AddPage method [MFC]", "property sheets, about property sheets", "Create method [MFC], property sheets", "CPropertyPage class [MFC], styles"] -ms.assetid: 240654d4-152b-4e3f-af7b-44234339206e +ms.topic: how-to --- # Using Property Sheets in Your Application +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To use a property sheet in your application, complete the following steps: 1. Create a dialog template resource for each property page. Keep in mind that the user may be switching from one page to another, so lay out each page as consistently as possible. diff --git a/docs/mfc/using-slider-controls.md b/docs/mfc/using-slider-controls.md index ce6fe778aae..52555ecbd5d 100644 --- a/docs/mfc/using-slider-controls.md +++ b/docs/mfc/using-slider-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Slider Controls" title: "Using Slider Controls" ms.date: "11/04/2016" helpviewer_keywords: ["CSliderCtrl class [MFC], using", "slider controls", "slider controls [MFC], using"] -ms.assetid: 2b1a8ac8-2b17-41e1-aa24-83c1fd737049 +ms.topic: concept-article --- # Using Slider Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Typical usage of an slider control follows the pattern below: - The control is created. If the control is specified in a dialog box template, creation is automatic when the dialog box is created. (You should have a [CSliderCtrl](../mfc/reference/csliderctrl-class.md) member in your dialog class that corresponds to the slider control.) Alternatively, you can use the [Create](../mfc/reference/csliderctrl-class.md#create) member function to create the control as a child window of any window. diff --git a/docs/mfc/using-the-carchive-output-and-input-operators.md b/docs/mfc/using-the-carchive-output-and-input-operators.md index 3562deb0f97..1f57ddc404c 100644 --- a/docs/mfc/using-the-carchive-output-and-input-operators.md +++ b/docs/mfc/using-the-carchive-output-and-input-operators.md @@ -3,10 +3,13 @@ description: "Learn more about: Using the CArchive << and >> Operators" title: "Using the CArchive << and >> Operators" ms.date: "11/04/2016" helpviewer_keywords: ["objects [MFC], loading from previously stored values", "CArchive class [MFC], storing and loading objects", "CArchive class [MFC], operators"] -ms.assetid: 56aef326-02dc-4992-8282-f0a4b78a064e +ms.topic: how-to --- # Using the CArchive `<<` and `>>` Operators +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CArchive` provides <\< and >> operators for writing and reading simple data types as well as `CObject`s to and from a file. #### To store an object in a file via an archive diff --git a/docs/mfc/using-the-classes-to-write-applications-for-windows.md b/docs/mfc/using-the-classes-to-write-applications-for-windows.md index 6b89b84fc1d..27b9d14cf40 100644 --- a/docs/mfc/using-the-classes-to-write-applications-for-windows.md +++ b/docs/mfc/using-the-classes-to-write-applications-for-windows.md @@ -3,11 +3,14 @@ description: "Learn more about: Using the Classes to Write Applications for Wind title: "Using the Classes to Write Applications for Windows" ms.date: "11/04/2016" helpviewer_keywords: ["Windows applications [MFC], MFC application framework", "MFC, application development", "applications [OLE], MFC application framework", "MFC ActiveX controls [MFC], creating", "OLE applications [MFC], MFC application framework", "database applications [MFC], creating"] -ms.assetid: 73f63470-857d-43dd-9a54-b38b7be0f1b7 +ms.topic: concept-article --- # Using the Classes to Write Applications for Windows -Taken together, the classes in the Microsoft Foundation Class (MFC) Library make up an "application framework," on which you build an application for the Windows operating system. At a very general level, the framework defines the skeleton of an application and supplies standard user-interface implementations that can be placed onto the skeleton. Your job as programmer is to fill in the rest of the skeleton, which are those things that are specific to your application. You can get a head start by using the MFC Application Wizard to create the files for a very thorough starter application. You use the Microsoft Visual C++ resource editors to design your user-interface elements visually, Class View commands to connect those elements to code, and the class library to implement your application-specific logic. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +Taken together, the classes in the Microsoft Foundation Class (MFC) Library make up an "application framework," on which you build an application for the Windows operating system. At a very general level, the framework defines the skeleton of an application and supplies standard user-interface implementations that can be placed onto the skeleton. Your job as programmer is to fill in the rest of the skeleton, which are those things that are specific to your application. You can get a head start by using the MFC Application Wizard to create the files for a very thorough starter application. You use the Visual Studio resource editors to design your user-interface elements visually, Class View commands to connect those elements to code, and the class library to implement your application-specific logic. Version 3.0 and later of the MFC framework supports programming for Win32 platforms, including Microsoft Windows 95 and later, and Windows NT versions 3.51 and later. MFC Win32 support includes multithreading. Use version 1.5*x* if you need to do 16-bit programming. diff --git a/docs/mfc/using-the-dialog-editor-to-add-controls.md b/docs/mfc/using-the-dialog-editor-to-add-controls.md index fa78c746bd5..713ea777a5d 100644 --- a/docs/mfc/using-the-dialog-editor-to-add-controls.md +++ b/docs/mfc/using-the-dialog-editor-to-add-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Using the Dialog Editor to Add Controls" title: "Using the Dialog Editor to Add Controls" ms.date: "11/04/2016" helpviewer_keywords: ["Windows common controls [MFC], adding", "dialog box controls [MFC], adding to dialog boxes", "controls [MFC], adding to dialog boxes", "Dialog editor, creating controls", "common controls [MFC], adding"] -ms.assetid: d3f9f994-7e54-4656-a545-42c204557c36 +ms.topic: concept-article --- # Using the Dialog Editor to Add Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you create your dialog-template resource with the [dialog editor](../windows/dialog-editor.md), you drag controls from a controls palette and drop them into the dialog box. This adds the specifications for that control type to the dialog-template resource. When you construct a dialog object and call its `Create` or `DoModal` member function, the framework creates a Windows control and places it in the dialog window on screen. You can instead [create controls by hand](../mfc/adding-controls-by-hand.md) if you want. This is more work. diff --git a/docs/mfc/using-the-mfc-source-files.md b/docs/mfc/using-the-mfc-source-files.md index 77141ce95cd..ab89891084c 100644 --- a/docs/mfc/using-the-mfc-source-files.md +++ b/docs/mfc/using-the-mfc-source-files.md @@ -3,10 +3,13 @@ description: "Learn more about: Using the MFC source files" title: "Using the MFC source files" ms.date: "08/19/2019" helpviewer_keywords: ["public members", "source files", "MFC, source files", "MFC source files", "comments, MFC", "private member access", "protected member access", "source files, MFC"] -ms.assetid: 3230e8fb-3b69-4ddf-9538-365ac7ea5e72 +ms.topic: concept-article --- # Using the MFC source files +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class (MFC) Library supplies full source code. Header files (.h) are in the *\atlmfc\include* directory. Implementation files (.cpp) are in the *\atlmfc\src\mfc* directory. This article explains the conventions that MFC uses to comment the various parts of each class, what these comments mean, and what you should expect to find in each section. The Visual Studio wizards use similar conventions for the classes that they create for you, and you'll probably find these conventions useful for your own code. diff --git a/docs/mfc/using-tooltips-in-a-cstatusbarctrl-object.md b/docs/mfc/using-tooltips-in-a-cstatusbarctrl-object.md index f98699e4cdb..acc70168491 100644 --- a/docs/mfc/using-tooltips-in-a-cstatusbarctrl-object.md +++ b/docs/mfc/using-tooltips-in-a-cstatusbarctrl-object.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Tooltips in a CStatusBarCtrl Object" title: "Using Tooltips in a CStatusBarCtrl Object" ms.date: "11/04/2016" helpviewer_keywords: ["tool tips [MFC], using in status bars", "status bars [MFC], tool tips", "CStatusBarCtrl class [MFC], tool tips"] -ms.assetid: a77597a7-43ef-4b8f-87bc-a8ea1dc63dc3 +ms.topic: how-to --- # Using Tooltips in a CStatusBarCtrl Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To enable tooltips for a status bar control, create the `CStatusBarCtrl` object with the SBT_TOOLTIPS style. > [!NOTE] diff --git a/docs/mfc/using-tree-controls.md b/docs/mfc/using-tree-controls.md index a0b87f8f551..e444398c798 100644 --- a/docs/mfc/using-tree-controls.md +++ b/docs/mfc/using-tree-controls.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Tree Controls" title: "Using Tree Controls" ms.date: "11/04/2016" helpviewer_keywords: ["CTreeCtrl class [MFC], using", "tree controls [MFC], about tree controls"] -ms.assetid: 4e92941a-e477-4fb1-b1ce-4abeafbef1c1 +ms.topic: concept-article --- # Using Tree Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Typical usage of a tree control ([CTreeCtrl](../mfc/reference/ctreectrl-class.md)) follows the pattern below: - The control is created. If the control is specified in a dialog box template or if you're using `CTreeView`, creation is automatic when the dialog box or view is created. If you want to create the tree control as a child window of some other window, use the [Create](../mfc/reference/ctreectrl-class.md#create) member function. diff --git a/docs/mfc/using-views.md b/docs/mfc/using-views.md index be0abb6f982..e83e30e8e11 100644 --- a/docs/mfc/using-views.md +++ b/docs/mfc/using-views.md @@ -3,10 +3,13 @@ description: "Learn more about: Using Views" title: "Using Views" ms.date: "11/04/2016" helpviewer_keywords: ["interacting with users and role of view class [MFC]", "drawing [MFC], data", "rendering data", "view classes [MFC], role in managing user interaction", "CView class [MFC], view architecture", "MFC, views", "views [MFC], using", "painting data", "user input [MFC], interpreting through view class [MFC]", "view classes [MFC], role in displaying application data"] -ms.assetid: dc3de6ad-5c64-4317-8f10-8bdcc38cdbd5 +ms.topic: concept-article --- # Using Views +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The view's responsibilities are to display the document's data graphically to the user and to accept and interpret user input as operations on the document. Your tasks in writing your view class are to: - Write your view class's [OnDraw](../mfc/reference/cview-class.md#ondraw) member function, which renders the document's data. diff --git a/docs/mfc/using-your-old-toolbars.md b/docs/mfc/using-your-old-toolbars.md index 737b5f6d214..8433410e874 100644 --- a/docs/mfc/using-your-old-toolbars.md +++ b/docs/mfc/using-your-old-toolbars.md @@ -4,11 +4,14 @@ title: "Using Your Old Toolbars" ms.date: "11/04/2016" f1_keywords: ["COldToolBar"] helpviewer_keywords: ["toolbars [MFC], backward compatibility", "COldToolBar class [MFC]"] -ms.assetid: 3543257c-8547-43f0-a66a-ee641dc1cf89 +ms.topic: concept-article --- # Using Your Old Toolbars -If you have used previous versions of Visual C++ to create customized toolbars, the new implementation of class [CToolBar](../mfc/reference/ctoolbar-class.md) could cause you problems. So that you don't have to give up your old toolbars to use the new functionality, the old implementation is still supported. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +If you have used previous versions of Visual Studio to create customized toolbars, the new implementation of class [CToolBar](../mfc/reference/ctoolbar-class.md) could cause you problems. So that you don't have to give up your old toolbars to use the new functionality, the old implementation is still supported. The DOCKTOOL sample does not use the old-style toolbars, only the new-style toolbars. diff --git a/docs/mfc/view-classes-architecture.md b/docs/mfc/view-classes-architecture.md index b49cc3c4ec7..3e5e53eedb3 100644 --- a/docs/mfc/view-classes-architecture.md +++ b/docs/mfc/view-classes-architecture.md @@ -3,10 +3,12 @@ description: "Learn more about: View Classes (Architecture)" title: "View Classes (Architecture)" ms.date: "09/17/2019" helpviewer_keywords: ["form and record views [MFC]", "view classes [MFC]", "control views [MFC]", "view classes [MFC], architecture"] -ms.assetid: 8894579a-1436-441e-b985-83711061e495 --- # View Classes (Architecture) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CView` and its derived classes are child windows that represent the client area of a frame window. Views show data and accept input for a document. A view class is associated with a document class and a frame window class using a document-template object. diff --git a/docs/mfc/view-classes-windows.md b/docs/mfc/view-classes-windows.md index 763e0ca629a..ebd9220138c 100644 --- a/docs/mfc/view-classes-windows.md +++ b/docs/mfc/view-classes-windows.md @@ -4,10 +4,12 @@ title: "View Classes (Windows)" ms.date: "09/17/2019" f1_keywords: ["vc.classes.view"] helpviewer_keywords: ["form and record views [MFC]", "splitter window classes [MFC]", "view classes [MFC], Windows"] -ms.assetid: b11683fb-9f43-4de3-9499-2b55775f9870 --- # View Classes (Windows) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + `CView` and its derived classes are child windows that represent the client area of a frame window. Views show data and accept input for a document. A view class is associated with a document class and a frame window class using a document-template object. diff --git a/docs/mfc/virtual-list-controls.md b/docs/mfc/virtual-list-controls.md index f2e9003efd4..311cac31958 100644 --- a/docs/mfc/virtual-list-controls.md +++ b/docs/mfc/virtual-list-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Virtual List Controls" title: "Virtual List Controls" ms.date: "11/04/2016" helpviewer_keywords: ["cache, virtual list control item data", "list controls [MFC], virtual", "list controls [MFC], List view", "virtual list controls"] -ms.assetid: 319f841f-e426-423a-8276-d93f965b0b45 --- # Virtual List Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A virtual list control is a list view control that has the LVS_OWNERDATA style. This style enables the control to support an item count up to a **DWORD** (the default item count only extends to an **`int`**). However, the biggest advantage provided by this style is the ability to only have a subset of data items in memory at any one time. This allows the virtual list view control to lend itself for use with large databases of information, where specific methods of accessing data are already in place. > [!NOTE] diff --git a/docs/mfc/visualization-manager.md b/docs/mfc/visualization-manager.md index b02e2a7bb43..3325a8136a0 100644 --- a/docs/mfc/visualization-manager.md +++ b/docs/mfc/visualization-manager.md @@ -3,10 +3,12 @@ description: "Learn more about: Visualization Manager" title: "Visualization Manager" ms.date: "11/19/2018" helpviewer_keywords: ["Visualization Manager"] -ms.assetid: c9dd1365-27ac-42e5-8caa-1004525b4129 --- # Visualization Manager +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The visual manager is an object that controls the appearance of a whole application. It acts as a single class where you can put all the drawing code for your application. The MFC Library includes several visual managers. You can also create your own visual manager if you want to create a custom view for your application. The following images show the same application when different visual managers are enabled: ![MyApp as rendered by CMFCVisualManagerWindows.](../mfc/media/vmwindows.png "MyApp as rendered by CMFCVisualManagerWindows")
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 6a21fdfad1d..22a01a8430a 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,20 @@ --- -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. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. -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. +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 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 +23,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. +## Replace the Windows message box with a CTaskDialog -### To Replace a 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 +54,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 - -1. Navigate to the **Resource View**. If you can't see the **Resource View**, you can open it from the **View** menu. - -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**. +## Add functionality to the CTaskDialog -1. Navigate back to MyProject.cpp. +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. 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 +77,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 +133,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/walkthrough-adding-a-d2d-object-to-an-mfc-project.md b/docs/mfc/walkthrough-adding-a-d2d-object-to-an-mfc-project.md index a1bcbd4b77d..f947e363ef4 100644 --- a/docs/mfc/walkthrough-adding-a-d2d-object-to-an-mfc-project.md +++ b/docs/mfc/walkthrough-adding-a-d2d-object-to-an-mfc-project.md @@ -3,11 +3,13 @@ description: "Learn more about: Walkthrough: Adding a D2D Object to an MFC Proje title: "Walkthrough: Adding a D2D Object to an MFC Project" ms.date: "04/25/2019" helpviewer_keywords: ["MFC, D2D", "D2D [MFC]"] -ms.assetid: dda36c33-c231-4da6-a62f-72d69a12b6dd --- # Walkthrough: Adding a D2D Object to an MFC Project -This walkthrough teaches how to add a basic Direct2D (D2D) object to a Visual C++, Microsoft Foundation Class Library (MFC) project, and then build the project into an application that prints "Hello, World!" on a gradient background. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +This walkthrough teaches how to add a basic Direct2D (D2D) object to a Visual Studio, Microsoft Foundation Class Library (MFC) project, and then build the project into an application that prints "Hello, World!" on a gradient background. The walkthrough shows how to accomplish these tasks: @@ -25,7 +27,7 @@ The walkthrough shows how to accomplish these tasks: ## Prerequisites -To complete this walkthrough, you must have Visual Studio installed with the **Desktop development with C++** workload and the optional **Visual C++ MFC for x86 and x64** component. +To complete this walkthrough, you must have Visual Studio installed with the **Desktop development with C++** workload and the optional **C++ MFC for x64/x86** component. ## To create an MFC application diff --git a/docs/mfc/walkthrough-adding-animation-to-an-mfc-project.md b/docs/mfc/walkthrough-adding-animation-to-an-mfc-project.md index 2ab962abddd..8c7a5e4ed3c 100644 --- a/docs/mfc/walkthrough-adding-animation-to-an-mfc-project.md +++ b/docs/mfc/walkthrough-adding-animation-to-an-mfc-project.md @@ -3,11 +3,13 @@ description: "Learn more about: Walkthrough: Adding Animation to an MFC Project" title: "Walkthrough: Adding Animation to an MFC Project" ms.date: "04/25/2019" helpviewer_keywords: ["animation [MFC]", "MFC, animation"] -ms.assetid: 004f832c-9fd5-4f88-9ca9-ae65dececdc2 --- # Walkthrough: Adding Animation to an MFC Project -This walkthrough teaches how to add a basic animated object to a Visual C++, Microsoft Foundation Class Library (MFC) project. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +This walkthrough teaches how to add a basic animated object to a Visual Studio, Microsoft Foundation Class Library (MFC) project. The walkthrough shows how to accomplish these tasks: diff --git a/docs/mfc/walkthrough-creating-a-ribbon-application-by-using-mfc.md b/docs/mfc/walkthrough-creating-a-ribbon-application-by-using-mfc.md index 6421813b892..68f02ff75c1 100644 --- a/docs/mfc/walkthrough-creating-a-ribbon-application-by-using-mfc.md +++ b/docs/mfc/walkthrough-creating-a-ribbon-application-by-using-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Walkthrough: Creating a Ribbon Application By Us title: "Walkthrough: Creating a Ribbon Application By Using MFC" ms.date: "09/09/2019" helpviewer_keywords: ["ribbon application, creating (MFC)", "creating a ribbon application (MFC)"] -ms.assetid: e61393e2-1d6b-4594-a7ce-157d3d1b0d9f --- # Walkthrough: Creating a Ribbon Application By Using MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This walkthrough shows how to use the **MFC Application Wizard** to create an application that has a ribbon by default. You can then expand the ribbon by adding a **Custom** ribbon category that has a **Favorites** ribbon panel, and then adding some frequently used commands to the panel. ## Prerequisites diff --git a/docs/mfc/walkthrough-putting-controls-on-toolbars.md b/docs/mfc/walkthrough-putting-controls-on-toolbars.md index ca7b06348c4..9688e8d6d59 100644 --- a/docs/mfc/walkthrough-putting-controls-on-toolbars.md +++ b/docs/mfc/walkthrough-putting-controls-on-toolbars.md @@ -1,13 +1,15 @@ --- -description: "Learn more about: Walkthrough: Putting Controls On Toolbars" title: "Walkthrough: Putting Controls On Toolbars" -ms.date: "04/25/2019" +description: "Learn more about: Walkthrough: Putting Controls On Toolbars" +ms.date: 04/25/2019 helpviewer_keywords: ["Customize dialog box, adding controls", "toolbars [MFC], adding controls"] -ms.assetid: 8fc94bdf-0da7-45d9-8bc4-52b7b1edf205 --- # Walkthrough: Putting Controls On Toolbars -This article describes how to add a toolbar button that contains a Windows control to a toolbar. In MFC, a toolbar button must be a [CMFCToolBarButton Class](../mfc/reference/cmfctoolbarbutton-class.md)-derived class, for example [CMFCToolBarComboBoxButton Class](../mfc/reference/cmfctoolbarcomboboxbutton-class.md), [CMFCToolBarEditBoxButton Class](../mfc/reference/cmfctoolbareditboxbutton-class.md), [CMFCDropDownToolbarButton Class](../mfc/reference/cmfcdropdowntoolbarbutton-class.md), or [CMFCToolBarMenuButton Class](../mfc/reference/cmfctoolbarmenubutton-class.md). +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +This article describes how to add a toolbar button that contains a Windows control to a toolbar. In MFC, a toolbar button must be a [`CMFCToolBarButton` Class](reference/cmfctoolbarbutton-class.md)-derived class, for example [`CMFCToolBarComboBoxButton` Class](reference/cmfctoolbarcomboboxbutton-class.md), [`CMFCToolBarEditBoxButton` Class](reference/cmfctoolbareditboxbutton-class.md), [`CMFCDropDownToolbarButton` Class](reference/cmfcdropdowntoolbarbutton-class.md), or [`CMFCToolBarMenuButton` Class](reference/cmfctoolbarmenubutton-class.md). ## Adding Controls to Toolbars @@ -21,7 +23,7 @@ To add a control to a toolbar, follow these steps: 1. Construct the button control by using a `CMFCToolbarButton`-derived class. - 1. Replace the dummy button with the new control by using [CMFCToolBar::ReplaceButton](../mfc/reference/cmfctoolbar-class.md#replacebutton). You can construct the button object on the stack, because `ReplaceButton` copies the button object and maintains the copy. + 1. Replace the dummy button with the new control by using [`CMFCToolBar::ReplaceButton`](reference/cmfctoolbar-class.md#replacebutton). You can construct the button object on the stack, because `ReplaceButton` copies the button object and maintains the copy. > [!NOTE] > If you enabled customization in your application, you may have to reset the toolbar by using the **Reset** button on the **Toolbars** tab of the **Customize** dialog box to see the updated control in your application after recompiling. The toolbar state is saved in the Windows registry, and the registry information is loaded and applied after the `ReplaceButton` method is executed during application startup. @@ -30,11 +32,11 @@ To add a control to a toolbar, follow these steps: The **Commands** tab of the **Customize** dialog box contains a list of commands that are available in the application. By default, the **Customize** dialog box processes the application menus and builds a list of standard toolbar buttons in each menu category. To keep the extended functionality that the toolbar controls provide, you must replace the standard toolbar button with the custom control in the **Customize** dialog box. -When you enable customization, you create the **Customize** dialog box in the customization handler `OnViewCustomize` by using the [CMFCToolBarsCustomizeDialog Class](../mfc/reference/cmfctoolbarscustomizedialog-class.md) class. Before you display the **Customize** dialog box by calling [CMFCToolBarsCustomizeDialog::Create](../mfc/reference/cmfctoolbarscustomizedialog-class.md#create), call [CMFCToolBarsCustomizeDialog::ReplaceButton](../mfc/reference/cmfctoolbarscustomizedialog-class.md#replacebutton) to replace the standard button with the new control. +When you enable customization, you create the **Customize** dialog box in the customization handler `OnViewCustomize` by using the [`CMFCToolBarsCustomizeDialog` Class](reference/cmfctoolbarscustomizedialog-class.md) class. Before you display the **Customize** dialog box by calling [`CMFCToolBarsCustomizeDialog::Create`](reference/cmfctoolbarscustomizedialog-class.md#create), call [`CMFCToolBarsCustomizeDialog::ReplaceButton`](reference/cmfctoolbarscustomizedialog-class.md#replacebutton) to replace the standard button with the new control. ## Example: Creating a Find Combo Box -This section describes how to create a **Find** combo box control that appears on a toolbar and contains recent-used search strings. The user can type a string in the control and then press the enter key to search a document, or press the escape key to return the focus to the main frame. This example assumes that the document is displayed in a [CEditView Class](../mfc/reference/ceditview-class.md)-derived view. +This section describes how to create a **Find** combo box control that appears on a toolbar and contains recent-used search strings. The user can type a string in the control and then press the enter key to search a document, or press the escape key to return the focus to the main frame. This example assumes that the document is displayed in a [`CEditView` Class](reference/ceditview-class.md)-derived view. ### Creating the Find Control @@ -46,32 +48,32 @@ First, create the **Find** combo box control: 1. Create a new menu item with the `ID_EDIT_FIND` command ID. - 1. Add a new string "Find the text\nFind" to the string table and assign it an `ID_EDIT_FIND_COMBO` command ID. This ID will be used as the command ID of the **Find** combo box button. + 1. Add a new string `"Find the text\nFind"` to the string table and assign it an `ID_EDIT_FIND_COMBO` command ID. This ID will be used as the command ID of the **Find** combo box button. > [!NOTE] - > Because `ID_EDIT_FIND` is a standard command that is processed by `CEditView`, you are not required to implement a special handler for this command. However, you must implement a handler for the new command `ID_EDIT_FIND_COMBO`. + > Because `ID_EDIT_FIND` is a standard command that is processed by `CEditView`, you are not required to implement a special handler for this command. However, you must implement a handler for the new command `ID_EDIT_FIND_COMBO`. -1. Create a new class, `CFindComboBox`, derived from [CComboBox Class](../mfc/reference/ccombobox-class.md). +1. Create a new class, `CFindComboBox`, derived from [`CComboBox` Class](reference/ccombobox-class.md). -1. In the `CFindComboBox` class, override the `PreTranslateMessage` virtual method. This method will enable the combo box to process the [WM_KEYDOWN](/windows/win32/inputdev/wm-keydown) message. If the user hits the escape key (`VK_ESCAPE`), return the focus to the main frame window. If the user hits the Enter key (`VK_ENTER`), post to the main frame window a `WM_COMMAND` message that contains the `ID_EDIT_FIND_COMBO` command ID. +1. In the `CFindComboBox` class, override the `PreTranslateMessage` virtual method. This method will enable the combo box to process the [`WM_KEYDOWN`](/windows/win32/inputdev/wm-keydown) message. If the user hits the escape key (`VK_ESCAPE`), return the focus to the main frame window. If the user hits the Enter key (`VK_ENTER`), post to the main frame window a `WM_COMMAND` message that contains the `ID_EDIT_FIND_COMBO` command ID. -1. Create a class for the **Find** combo box button, derived from [CMFCToolBarComboBoxButton Class](../mfc/reference/cmfctoolbarcomboboxbutton-class.md). In this example, it's named `CFindComboButton`. +1. Create a class for the **Find** combo box button, derived from [`CMFCToolBarComboBoxButton` Class](reference/cmfctoolbarcomboboxbutton-class.md). In this example, it's named `CFindComboButton`. 1. The constructor of `CMFCToolbarComboBoxButton` takes three parameters: the command ID of the button, the button image index, and the style of the combo box. Set these parameters as follows: 1. Pass the `ID_EDIT_FIND_COMBO` as the command ID. - 1. Use [CCommandManager::GetCmdImage](reference/internal-classes.md) with `ID_EDIT_FIND` to get the image index. + 1. Use [`CCommandManager::GetCmdImage`](reference/internal-classes.md) with `ID_EDIT_FIND` to get the image index. - 1. For a list of available combo box styles, see [Combo-Box Styles](../mfc/reference/styles-used-by-mfc.md#combo-box-styles). + 1. For a list of available combo box styles, see [Combo-Box Styles](reference/styles-used-by-mfc.md#combo-box-styles). 1. In the `CFindComboButton` class, override the `CMFCToolbarComboBoxButton::CreateCombo` method. Here you should create the `CFindComboButton` object and return a pointer to it. -1. Use the [IMPLEMENT_SERIAL](../mfc/reference/run-time-object-model-services.md#implement_serial) macro to make the combo button persistent. The workspace manager automatically loads and saves the button's state in the Windows registry. +1. Use the [`IMPLEMENT_SERIAL`](reference/run-time-object-model-services.md#implement_serial) macro to make the combo button persistent. The workspace manager automatically loads and saves the button's state in the Windows registry. -1. Implement the `ID_EDIT_FIND_COMBO` handler in your document view. Use [CMFCToolBar::GetCommandButtons](../mfc/reference/cmfctoolbar-class.md#getcommandbuttons) with `ID_EDIT_FIND_COMBO` to retrieve all **Find** combo box buttons. There can be several copies of a button with the same command ID because of customization. +1. Implement the `ID_EDIT_FIND_COMBO` handler in your document view. Use [`CMFCToolBar::GetCommandButtons`](reference/cmfctoolbar-class.md#getcommandbuttons) with `ID_EDIT_FIND_COMBO` to retrieve all **Find** combo box buttons. There can be several copies of a button with the same command ID because of customization. -1. In the `ID_EDIT_FIND` message handler `OnFind`, use [CMFCToolBar::IsLastCommandFromButton](../mfc/reference/cmfctoolbar-class.md#islastcommandfrombutton) to determine whether the find command was sent from the **Find** combo box button. If so, find the text and add the search string to the combo box. +1. In the `ID_EDIT_FIND` message handler `OnFind`, use [`CMFCToolBar::IsLastCommandFromButton`](reference/cmfctoolbar-class.md#islastcommandfrombutton) to determine whether the find command was sent from the **Find** combo box button. If so, find the text and add the search string to the combo box. ### Adding the Find Control to the Main Toolbar @@ -82,20 +84,20 @@ To add the combo box button to the toolbar, follow these steps: > [!NOTE] > The framework sends this message to the main frame window when a toolbar is initialized during application startup, or when a toolbar is reset during customization. In either case, you must replace the standard toolbar button with the custom **Find** combo box button. -1. In the `AFX_WM_RESETTOOLBAR` handler, examine the toolbar ID, that is, the *WPARAM* of the AFX_WM_RESETTOOLBAR message. If the toolbar ID is equal to that of the toolbar that contains the **Find** combo box button, call [CMFCToolBar::ReplaceButton](../mfc/reference/cmfctoolbar-class.md#replacebutton) to replace the **Find** button (that is, the button with the command ID `ID_EDIT_FIND)` with a `CFindComboButton` object. +1. In the `AFX_WM_RESETTOOLBAR` handler, examine the toolbar ID, that is, the *`WPARAM`* of the `AFX_WM_RESETTOOLBAR` message. If the toolbar ID is equal to that of the toolbar that contains the **Find** combo box button, call [`CMFCToolBar::ReplaceButton`](reference/cmfctoolbar-class.md#replacebutton) to replace the **Find** button (that is, the button with the command ID `ID_EDIT_FIND`) with a `CFindComboButton` object. > [!NOTE] > You can construct a `CFindComboBox` object on the stack, because `ReplaceButton` copies the button object and maintains the copy. ### Adding the Find Control to the Customize Dialog Box -In the customization handler `OnViewCustomize`, call [CMFCToolBarsCustomizeDialog::ReplaceButton](../mfc/reference/cmfctoolbarscustomizedialog-class.md#replacebutton) to replace the **Find** button (that is, the button with the command ID `ID_EDIT_FIND`) with a `CFindComboButton` object. +In the customization handler `OnViewCustomize`, call [`CMFCToolBarsCustomizeDialog::ReplaceButton`](reference/cmfctoolbarscustomizedialog-class.md#replacebutton) to replace the **Find** button (that is, the button with the command ID `ID_EDIT_FIND`) with a `CFindComboButton` object. ## See also -[Hierarchy Chart](../mfc/hierarchy-chart.md)
-[Classes](../mfc/reference/mfc-classes.md)
-[CMFCToolBar Class](../mfc/reference/cmfctoolbar-class.md)
-[CMFCToolBarButton Class](../mfc/reference/cmfctoolbarbutton-class.md)
-[CMFCToolBarComboBoxButton Class](../mfc/reference/cmfctoolbarcomboboxbutton-class.md)
-[CMFCToolBarsCustomizeDialog Class](../mfc/reference/cmfctoolbarscustomizedialog-class.md) +[Hierarchy Chart](hierarchy-chart.md)\ +[Classes](reference/mfc-classes.md)\ +[`CMFCToolBar` Class](reference/cmfctoolbar-class.md)\ +[`CMFCToolBarButton` Class](reference/cmfctoolbarbutton-class.md)\ +[`CMFCToolBarComboBoxButton` Class](reference/cmfctoolbarcomboboxbutton-class.md)\ +[`CMFCToolBarsCustomizeDialog` Class](reference/cmfctoolbarscustomizedialog-class.md) diff --git a/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-1.md b/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-1.md index 6a37a8bff6a..0df6ca00842 100644 --- a/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-1.md +++ b/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-1.md @@ -3,10 +3,12 @@ description: "Learn more about: Walkthrough: Updating the MFC Scribble Applicati title: "Walkthrough: Updating the MFC Scribble Application (Part 1)" ms.date: "09/09/2019" helpviewer_keywords: ["examples [MFC], update existing application", "ribbon UI, porting to", "Office Fluent UI, porting to", "samples [MFC], update existing application", "MFC Feature Pack, update existing application", "walkthroughs [MFC], update existing application"] -ms.assetid: aa6330d3-6cfc-4c79-8fcb-0282263025f7 --- # Walkthrough: Updating the MFC Scribble Application (Part 1) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This walkthrough demonstrates how to modify an existing MFC application to use the Ribbon user interface. Visual Studio supports both the Office 2007 Ribbon and the Windows 7 Scenic Ribbon. For more information about the Ribbon user interface, see [Ribbons](/windows/win32/uxguide/cmd-ribbons). This walkthrough modifies the classic Scribble 1.0 MFC sample that lets you use the mouse to create line drawings. This part of the walkthrough shows how to modify the Scribble sample so that it displays a ribbon bar. [Part 2](../mfc/walkthrough-updating-the-mfc-scribble-application-part-2.md) adds more buttons to the ribbon bar. diff --git a/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-2.md b/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-2.md index 19b88357d9d..81cb6c4023a 100644 --- a/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-2.md +++ b/docs/mfc/walkthrough-updating-the-mfc-scribble-application-part-2.md @@ -3,10 +3,12 @@ description: "Learn more about: Walkthrough: Updating the MFC Scribble Applicati title: "Walkthrough: Updating the MFC Scribble Application (Part 2)" ms.date: "04/25/2019" helpviewer_keywords: ["walkthroughs [MFC]"] -ms.assetid: 602df5c2-17d4-4cd9-8cf6-dff652c4cae5 --- # Walkthrough: Updating the MFC Scribble Application (Part 2) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + [Part 1](../mfc/walkthrough-updating-the-mfc-scribble-application-part-1.md) of this walkthrough showed how to add an Office Fluent Ribbon to the classic Scribble application. This part shows how to add ribbon panels and controls that users can use instead of menus and commands. ## Prerequisites diff --git a/docs/mfc/walkthrough-using-the-new-mfc-shell-controls.md b/docs/mfc/walkthrough-using-the-new-mfc-shell-controls.md index 35d503d1884..7b82b7990a9 100644 --- a/docs/mfc/walkthrough-using-the-new-mfc-shell-controls.md +++ b/docs/mfc/walkthrough-using-the-new-mfc-shell-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Walkthrough: Using the New MFC Shell Controls" title: "Walkthrough: Using the New MFC Shell Controls" ms.date: 10/27/2021 helpviewer_keywords: ["shell controls (MFC)"] -ms.assetid: f0015caa-199d-4aaf-9501-5a239fce9095 --- # Walkthrough: Using the New MFC Shell Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In this walkthrough, you'll create an application that resembles File Explorer. You'll create a window that has two panes. The left pane will hold a [CMFCShellTreeCtrl](../mfc/reference/cmfcshelltreectrl-class.md) object that displays your Desktop in a hierarchical view. The right pane will hold a [CMFCShellListCtrl](../mfc/reference/cmfcshelllistctrl-class.md) that shows the files in the folder that is selected in the left pane. ## Prerequisites diff --git a/docs/mfc/walkthroughs-mfc.md b/docs/mfc/walkthroughs-mfc.md index a286a742aec..d5c6bf20893 100644 --- a/docs/mfc/walkthroughs-mfc.md +++ b/docs/mfc/walkthroughs-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Walkthroughs (MFC)" title: "Walkthroughs (MFC)" ms.date: "09/20/2018" helpviewer_keywords: ["MFC Feature Pack, walkthroughs"] -ms.assetid: 20d5756f-ad58-46f4-8b6c-c7a1020b72eb --- # Walkthroughs (MFC) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This section contains articles that walk you through various tasks associated with new MFC library features. ## In This Section diff --git a/docs/mfc/what-does-it-cost-me-to-derive-a-class-from-cobject-q.md b/docs/mfc/what-does-it-cost-me-to-derive-a-class-from-cobject-q.md index 5aedcbf9840..6f32909aa5b 100644 --- a/docs/mfc/what-does-it-cost-me-to-derive-a-class-from-cobject-q.md +++ b/docs/mfc/what-does-it-cost-me-to-derive-a-class-from-cobject-q.md @@ -3,10 +3,12 @@ description: "Learn more about: What Does it Cost me to Derive a Class from CObj title: "What Does it Cost me to Derive a Class from CObject?" ms.date: "11/04/2016" helpviewer_keywords: ["CObject class [MFC], overhead of derived classes [MFC]"] -ms.assetid: 9b92c98b-b3dd-48a7-9d24-c3b8554edf90 --- # What Does it Cost me to Derive a Class from CObject? +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The overhead in deriving from class [CObject](../mfc/reference/cobject-class.md) is minimal. Your derived class inherits only four virtual functions and a single [CRuntimeClass](../mfc/reference/cruntimeclass-structure.md) object. ## See also diff --git a/docs/mfc/what-frame-windows-do.md b/docs/mfc/what-frame-windows-do.md index 4949a47ade0..bb4c94ccf7a 100644 --- a/docs/mfc/what-frame-windows-do.md +++ b/docs/mfc/what-frame-windows-do.md @@ -3,10 +3,12 @@ description: "Learn more about: What Frame Windows Do" title: "What Frame Windows Do" ms.date: "11/04/2016" helpviewer_keywords: ["frame windows [MFC], about frame windows", "frame windows [MFC], tasks", "MFC, frame windows"] -ms.assetid: 1148a952-6786-4622-b5a8-68a2d7eae584 --- # What Frame Windows Do +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Besides simply framing a view, frame windows are responsible for numerous tasks involved in coordinating the frame with its view and with the application. [CMDIFrameWnd](../mfc/reference/cmdiframewnd-class.md) and [CMDIChildWnd](../mfc/reference/cmdichildwnd-class.md) inherit from [CFrameWnd](../mfc/reference/cframewnd-class.md), so they have `CFrameWnd` capabilities as well as new capabilities that they add. Examples of child windows include views, controls such as buttons and list boxes, and control bars, including toolbars, status bars, and dialog bars. The frame window is responsible for managing the layout of its child windows. In the MFC framework, a frame window positions any control bars, views, and other child windows inside its client area. diff --git a/docs/mfc/what-is-a-carchive-object.md b/docs/mfc/what-is-a-carchive-object.md index 299602c9df4..07598d35a70 100644 --- a/docs/mfc/what-is-a-carchive-object.md +++ b/docs/mfc/what-is-a-carchive-object.md @@ -3,11 +3,14 @@ description: "Learn more about: What Is a CArchive Object" title: "What Is a CArchive Object" ms.date: "11/04/2016" helpviewer_keywords: ["archive objects [MFC]", "archives [MFC], for serialization", "buffers, serializable objects", "CArchive class [MFC], about CArchive class [MFC]", "buffering, serializable objects"] -ms.assetid: 843f1825-288d-4d89-a1fa-70e1f92d9b8b ms.custom: intro-overview +ms.topic: concept-article --- # What Is a CArchive Object +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A `CArchive` object provides a type-safe buffering mechanism for writing or reading serializable objects to or from a `CFile` object. Usually the `CFile` object represents a disk file; however, it can also be a memory file (`CSharedFile` object), perhaps representing the Clipboard. A given `CArchive` object either stores (writes, serializes) data or loads (reads, deserializes) data, but never both. The life of a `CArchive` object is limited to one pass through writing objects to a file or reading objects from a file. Thus, two successively created `CArchive` objects are required to serialize data to a file and then deserialize it back from the file. diff --git a/docs/mfc/when-to-initialize-cwnd-objects.md b/docs/mfc/when-to-initialize-cwnd-objects.md index 4097208b0f6..88b6408936f 100644 --- a/docs/mfc/when-to-initialize-cwnd-objects.md +++ b/docs/mfc/when-to-initialize-cwnd-objects.md @@ -3,10 +3,12 @@ description: "Learn more about: When to Initialize CWnd Objects" title: "When to Initialize CWnd Objects" ms.date: "11/04/2016" helpviewer_keywords: ["window objects [MFC], when to initialize CWnd", "initializing CWnd objects [MFC]", "initializing objects [MFC], CWnd", "CWnd objects [MFC], when HWND is attached", "HWND, when attached to CWnd object", "CWnd objects [MFC], when to initialize"] -ms.assetid: 4d31bcb1-73db-4f2f-b71c-89b087569a10 --- # When to Initialize CWnd Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You cannot create your own child windows or call any Windows API functions in the constructor of a `CWnd`-derived object. This is because the `HWND` for the `CWnd` object has not been created yet. Most Windows-specific initialization, such as adding child windows, must be done in an [OnCreate](../mfc/reference/cwnd-class.md#oncreate) message handler. ## What do you want to know more about diff --git a/docs/mfc/when-update-handlers-are-called.md b/docs/mfc/when-update-handlers-are-called.md index 63558a68e37..ad527d5e48d 100644 --- a/docs/mfc/when-update-handlers-are-called.md +++ b/docs/mfc/when-update-handlers-are-called.md @@ -3,10 +3,12 @@ description: "Learn more about: When Update Handlers Are Called" title: "When Update Handlers Are Called" ms.date: "11/04/2016" helpviewer_keywords: ["updating user interface objects [MFC]", "command routing [MFC], update commands", "toolbar buttons [MFC], enabling", "disabling toolbar buttons", "menus [MFC], initializing", "update handlers [MFC]", "disabling menu items", "toolbars [MFC], updating", "menus [MFC], updating as context changes", "toolbar controls [MFC], updated during OnIdle method [MFC]", "menu items, enabling", "command routing [MFC], update handlers", "update handlers, calling"] -ms.assetid: 7359f6b1-4669-477d-bd99-690affed08d9 --- # When Update Handlers Are Called +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Suppose the user clicks the mouse in the File menu, which generates a WM_INITMENUPOPUP message. The framework's update mechanism collectively updates all items on the File menu before the menu drops down so the user can see it. To do this, the framework routes update commands for all menu items in the pop-up menu along the standard command routing. Command targets on the routing have an opportunity to update any menu items by matching the update command with an appropriate message-map entry (of the form `ON_UPDATE_COMMAND_UI`) and calling an "update handler" function. Thus, for a menu with six menu items, six update commands are sent out. If an update handler exists for the command ID of the menu item, it is called to do the updating. If not, the framework checks for the existence of a handler for that command ID and enables or disables the menu item as appropriate. diff --git a/docs/mfc/where-to-find-message-maps.md b/docs/mfc/where-to-find-message-maps.md index 2d4a1403aa2..5db17291298 100644 --- a/docs/mfc/where-to-find-message-maps.md +++ b/docs/mfc/where-to-find-message-maps.md @@ -3,10 +3,12 @@ description: "Learn more about: Where to Find Message Maps" title: "Where to Find Message Maps" ms.date: "11/04/2016" helpviewer_keywords: ["macros, message map", "locating message maps", "message classes [MFC], finding", "message-map macros"] -ms.assetid: bf59fbc8-b222-42d3-b5d3-0a79aa3cb923 --- # Where to Find Message Maps +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + When you create a new skeleton application with the Application Wizard, the Application Wizard writes a message map for each command-target class it creates for you. This includes your derived application, document, view, and frame-window classes. Some of these message maps already have the entries supplied by the Application Wizard for certain messages and predefined commands, and some are just placeholders for handlers that you will add. A class's message map is located in the .CPP file for the class. Working with the basic message maps that the Application Wizard creates, you use the [Class Wizard](reference/mfc-class-wizard.md) to add entries for the messages and commands that each class will handle. A typical message map might look like the following after you add some entries: diff --git a/docs/mfc/win32-internet-classes.md b/docs/mfc/win32-internet-classes.md index 218920d5438..f30bb06f4b3 100644 --- a/docs/mfc/win32-internet-classes.md +++ b/docs/mfc/win32-internet-classes.md @@ -4,10 +4,12 @@ title: "Win32 Internet Classes" ms.date: "09/12/2018" f1_keywords: ["vc.classes.win32"] helpviewer_keywords: ["Internet classes [MFC]", "WinInet classes [MFC], classes", "Win32 [MFC], Internet classes", "Windows API [MFC], Internet classes"] -ms.assetid: b49601d5-3025-4068-9408-316b54ee4375 --- # Win32 Internet Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC wraps the Win32 Internet (WinInet) and ActiveX technology to make Internet programming easier. >[!IMPORTANT] diff --git a/docs/mfc/win32-internet-extensions-wininet.md b/docs/mfc/win32-internet-extensions-wininet.md index 801fcbb1aca..63a5cba7c3f 100644 --- a/docs/mfc/win32-internet-extensions-wininet.md +++ b/docs/mfc/win32-internet-extensions-wininet.md @@ -3,10 +3,12 @@ description: "Learn more about: Win32 Internet Extensions (WinInet)" title: "Win32 Internet Extensions (WinInet)" ms.date: "11/04/2016" helpviewer_keywords: ["Internet applications [MFC], Win32 Internet Extensions", "Internet client applications [MFC], about Internet client applications", "client applications [MFC], Win32 Internet", "WinInet classes [MFC], about WinInet classes"] -ms.assetid: f8c80f0b-ce14-4f0d-a3cf-4f7d8c5cca59 --- # Win32 Internet Extensions (WinInet) +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + An Internet client application is a program that accesses information from a network data source (server) using Internet protocols such as gopher, FTP, or HTTP. An Internet client application might access a server to retrieve data such as weather maps, stock prices, or newspaper headlines, for example. The Internet client can access the server through an external network (the Internet) or an internal network (sometimes called an intranet). MFC includes the Win32 Internet Extensions, or WinInet, for creating an Internet client application. MFC encapsulates these Internet extensions in a set of standard, easy-to-use classes. You can write a WinInet client application by calling the Win32 functions directly or by using the MFC WinInet classes. diff --git a/docs/mfc/window-destruction-sequence.md b/docs/mfc/window-destruction-sequence.md index 7cc74192df7..24af36131b3 100644 --- a/docs/mfc/window-destruction-sequence.md +++ b/docs/mfc/window-destruction-sequence.md @@ -3,10 +3,12 @@ description: "Learn more about: Window Destruction Sequence" title: "Window Destruction Sequence" ms.date: "11/04/2016" helpviewer_keywords: ["destruction, windows", "destroying windows", "sequence [MFC], window destruction", "CWnd objects [MFC], destruction sequence", "sequence [MFC]", "windows [MFC], destroying"] -ms.assetid: 2d819196-6240-415f-a308-db43745e616c --- # Window Destruction Sequence +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + In the MFC framework, when the user closes the frame window, the window's default [OnClose](../mfc/reference/cwnd-class.md#onclose) handler calls [DestroyWindow](../mfc/reference/cwnd-class.md#destroywindow). The last member function called when the Windows window is destroyed is [OnNcDestroy](../mfc/reference/cwnd-class.md#onncdestroy), which does some cleanup, calls the [Default](../mfc/reference/cwnd-class.md#default) member function to perform Windows cleanup, and lastly calls the virtual member function [PostNcDestroy](../mfc/reference/cwnd-class.md#postncdestroy). The [CFrameWnd](../mfc/reference/cframewnd-class.md) implementation of `PostNcDestroy` deletes the C++ window object. ## What do you want to know more about diff --git a/docs/mfc/window-dialog-and-control-classes.md b/docs/mfc/window-dialog-and-control-classes.md index 9beece06877..730a6baea47 100644 --- a/docs/mfc/window-dialog-and-control-classes.md +++ b/docs/mfc/window-dialog-and-control-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Window, Dialog, and Control Classes" title: "Window, Dialog, and Control Classes" ms.date: "11/04/2016" helpviewer_keywords: ["windows [MFC], dialog and control classes"] -ms.assetid: b3610da6-9644-49b7-adbf-0e04f0d6d2b5 --- # Window, Dialog, and Control Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Class `CWnd` and its derived classes encapsulate an `HWND`, a handle to a Windows window. `CWnd` can be used by itself or as a base for deriving new classes. The derived classes supplied by the class library represent various kinds of windows. [CWnd](../mfc/reference/cwnd-class.md)
diff --git a/docs/mfc/window-objects.md b/docs/mfc/window-objects.md index a4f2924d5be..fc1929cb147 100644 --- a/docs/mfc/window-objects.md +++ b/docs/mfc/window-objects.md @@ -3,10 +3,12 @@ description: "Learn more about: Window Objects" title: "Window Objects" ms.date: "11/04/2016" helpviewer_keywords: ["objects [MFC], window", "Windows window [MFC]", "MFC, windows", "frame windows [MFC], C++ window objects", "window objects [MFC]", "windows [MFC], C++ window objects", "window messages [MFC]", "HWND", "messages [MFC], Windows", "Visual C++, window objects [MFC]", "HWND, window objects [MFC]"] -ms.assetid: 28b33ce2-af05-4617-9d03-1cb9a02be687 --- # Window Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + MFC supplies class [CWnd](../mfc/reference/cwnd-class.md) to encapsulate the `HWND` handle of a window. The `CWnd` object is a C++ window object, distinct from the `HWND` that represents a Windows window but containing it. Use `CWnd` to derive your own child window classes, or use one of the many MFC classes derived from `CWnd`. Class `CWnd` is the base class for all windows, including frame windows, dialog boxes, child windows, controls, and control bars such as toolbars. A good understanding of [the relationship between a C++ window object and an HWND](../mfc/relationship-between-a-cpp-window-object-and-an-hwnd.md) is crucial for effective programming with MFC. MFC provides some default functionality and management of windows, but you can derive your own class from `CWnd` and use its member functions to customize the provided functionality. You can create child windows by constructing a `CWnd` object and calling its [Create](../mfc/reference/cwnd-class.md#create) member function, then customize the child windows using `CWnd` member functions. You can embed objects derived from [CView](../mfc/reference/cview-class.md), such as form views or tree views, in a frame window. And you can support multiple views of your documents via splitter panes, supplied by class [CSplitterWnd](../mfc/reference/csplitterwnd-class.md). diff --git a/docs/mfc/window-procedure-entry-points.md b/docs/mfc/window-procedure-entry-points.md index 2655dd259f0..a56476482dd 100644 --- a/docs/mfc/window-procedure-entry-points.md +++ b/docs/mfc/window-procedure-entry-points.md @@ -3,10 +3,12 @@ description: "Learn more about: Window Procedure Entry Points" title: "Window Procedure Entry Points" ms.date: "11/04/2016" helpviewer_keywords: ["state management, window procedures", "MFC, managing state data", "window procedure entry points", "entry points, window procedures"] -ms.assetid: a6b46a7f-6e42-45f2-9ae6-82e19fc57148 --- # Window Procedure Entry Points +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + To protect MFC window procedures, a module static links with a special window procedure implementation. The linkage occurs automatically when the module is linked with MFC. This window procedure uses the AFX_MANAGE_STATE macro to properly set the effective module state, then it calls `AfxWndProc`, which in turn delegates to the `WindowProc` member function of the appropriate `CWnd`-derived object. ## See also diff --git a/docs/mfc/windows-sockets-background.md b/docs/mfc/windows-sockets-background.md index 8bb853e4102..26d496907f5 100644 --- a/docs/mfc/windows-sockets-background.md +++ b/docs/mfc/windows-sockets-background.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Background" title: "Windows Sockets: Background" ms.date: "11/04/2016" helpviewer_keywords: ["record-oriented data [MFC]", "e-mail [MFC]", "Internet Protocol Suite", "mail [MFC]", "communications [MFC], domain", "Windows Sockets [MFC], stream sockets", "mail [MFC], programming for", "sockets [MFC], stream sockets", "datagram sockets [MFC]", "SOCKET handle", "data types [MFC], socket", "e-mail [MFC], programming for", "X Window servers", "sequenced data flow", "stream sockets [MFC]"] -ms.assetid: f60d4ed2-bf23-4a0e-98d2-fee77e8473dd --- # Windows Sockets: Background +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the nature and purpose of Windows Sockets. The article also: - [Defines the term "socket"](#_core_definition_of_a_socket). diff --git a/docs/mfc/windows-sockets-blocking.md b/docs/mfc/windows-sockets-blocking.md index f0e50a171df..2c2d61ed2d6 100644 --- a/docs/mfc/windows-sockets-blocking.md +++ b/docs/mfc/windows-sockets-blocking.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Blocking" title: "Windows Sockets: Blocking" ms.date: "11/04/2016" helpviewer_keywords: ["sockets [MFC], blocking mode", "Windows Sockets [MFC], Windows platforms", "Windows Sockets [MFC], blocking mode", "sockets [MFC], behavior on different Windows platforms", "blocking mode sockets"] -ms.assetid: 10aca9b1-bfba-41a8-9c55-ea8082181e63 --- # Windows Sockets: Blocking +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article and two companion articles explain several issues in Windows Sockets programming. This article covers blocking. The other issues are covered in the articles: [Windows Sockets: Byte Ordering](../mfc/windows-sockets-byte-ordering.md) and [Windows Sockets: Converting Strings](../mfc/windows-sockets-converting-strings.md). If you use or derive from class [CAsyncSocket](../mfc/reference/casyncsocket-class.md), you will need to manage these issues yourself. If you use or derive from class [CSocket](../mfc/reference/csocket-class.md), MFC manages them for you. diff --git a/docs/mfc/windows-sockets-byte-ordering.md b/docs/mfc/windows-sockets-byte-ordering.md index fde1d2eed8e..d8b3e1a50ae 100644 --- a/docs/mfc/windows-sockets-byte-ordering.md +++ b/docs/mfc/windows-sockets-byte-ordering.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Byte Ordering" title: "Windows Sockets: Byte Ordering" ms.date: "11/04/2016" helpviewer_keywords: ["byte order issues in sockets programming", "sockets [MFC], byte order issues", "Windows Sockets [MFC], byte order issues"] -ms.assetid: 8a787a65-f9f4-4002-a02f-ac25a5dace5d --- # Windows Sockets: Byte Ordering +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article and two companion articles explain several issues in Windows Sockets programming. This article covers byte ordering. The other issues are covered in the articles: [Windows Sockets: Blocking](../mfc/windows-sockets-blocking.md) and [Windows Sockets: Converting Strings](../mfc/windows-sockets-converting-strings.md). If you use or derive from class [CAsyncSocket](../mfc/reference/casyncsocket-class.md), you will need to manage these issues yourself. If you use or derive from class [CSocket](../mfc/reference/csocket-class.md), MFC manages them for you. diff --git a/docs/mfc/windows-sockets-classes.md b/docs/mfc/windows-sockets-classes.md index c80ea097acb..0c0b8f257ec 100644 --- a/docs/mfc/windows-sockets-classes.md +++ b/docs/mfc/windows-sockets-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets Classes" title: "Windows Sockets Classes" ms.date: "11/04/2016" helpviewer_keywords: ["sockets classes [MFC]", "Windows Sockets [MFC], classes"] -ms.assetid: 58b9ab8d-9e44-4db3-8265-e04e713d2e9a --- # Windows Sockets Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Windows Sockets provide a network protocol-independent way to communicate between two computers. These sockets can be synchronous (your program waits until the communication is done) or asynchronous (your program continues running while the communication is going on). [CAsyncSocket](../mfc/reference/casyncsocket-class.md)
diff --git a/docs/mfc/windows-sockets-converting-strings.md b/docs/mfc/windows-sockets-converting-strings.md index 6afd8d49102..d7a439eb926 100644 --- a/docs/mfc/windows-sockets-converting-strings.md +++ b/docs/mfc/windows-sockets-converting-strings.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Converting Strings" title: "Windows Sockets: Converting Strings" ms.date: "11/04/2016" helpviewer_keywords: ["Windows Sockets [MFC], multibyte character string conversion", "sockets [MFC], multibyte character string conversion issues", "string conversion, multibyte character strings"] -ms.assetid: 9df522b5-6b23-41e0-bb96-e4e623baf141 --- # Windows Sockets: Converting Strings +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article and two companion articles explain several issues in Windows Sockets programming. This article covers converting strings. The other issues are covered in [Windows Sockets: Blocking](../mfc/windows-sockets-blocking.md) and [Windows Sockets: Byte Ordering](../mfc/windows-sockets-byte-ordering.md). If you use or derive from class [CAsyncSocket](../mfc/reference/casyncsocket-class.md), you will need to manage these issues yourself. If you use or derive from class [CSocket](../mfc/reference/csocket-class.md), MFC manages them for you. diff --git a/docs/mfc/windows-sockets-datagram-sockets.md b/docs/mfc/windows-sockets-datagram-sockets.md index b751ab84485..6382445c37f 100644 --- a/docs/mfc/windows-sockets-datagram-sockets.md +++ b/docs/mfc/windows-sockets-datagram-sockets.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Datagram Sockets" title: "Windows Sockets: Datagram Sockets" ms.date: "11/04/2016" helpviewer_keywords: ["sockets [MFC], datagram", "Windows Sockets [MFC], bi-directional data flow", "datagram sockets [MFC]", "Windows Sockets [MFC], datagram", "sockets [MFC], bi-directional data flow"] -ms.assetid: bec16a1c-74c0-4ff9-8c18-c2d87897d264 --- # Windows Sockets: Datagram Sockets +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes datagram sockets, one of the two Windows Socket types available. (The other type is the [stream socket](../mfc/windows-sockets-stream-sockets.md).) Datagram sockets support a bidirectional data flow that is not guaranteed to be sequenced or unduplicated. Datagrams also are not guaranteed to be reliable; they can fail to arrive. Datagram data may arrive out of order and possibly duplicated, but record boundaries in the data are preserved, as long as the records are smaller than the receiver's internal size limit. You are responsible for managing sequencing and reliability. (Reliability tends to be good on local-area networks [LAN] but less so on wide-area networks [WAN], such as the Internet.) diff --git a/docs/mfc/windows-sockets-deriving-from-socket-classes.md b/docs/mfc/windows-sockets-deriving-from-socket-classes.md index 3915149c498..42d1d881cb8 100644 --- a/docs/mfc/windows-sockets-deriving-from-socket-classes.md +++ b/docs/mfc/windows-sockets-deriving-from-socket-classes.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Deriving from Socket Classes" title: "Windows Sockets: Deriving from Socket Classes" ms.date: "11/04/2016" helpviewer_keywords: ["derived classes [MFC], from socket classes", "Windows Sockets [MFC], deriving from socket classes", "sockets [MFC], deriving from socket classes"] -ms.assetid: 3a26e67a-e323-433b-9b05-eca018799801 --- # Windows Sockets: Deriving from Socket Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes some of the functionality you can gain by deriving your own class from one of the socket classes. You can derive your own socket classes from either [CAsyncSocket](../mfc/reference/casyncsocket-class.md) or [CSocket](../mfc/reference/csocket-class.md) to add your own functionality. In particular, these classes supply a number of virtual member functions that you can override. These functions include [OnReceive](../mfc/reference/casyncsocket-class.md#onreceive), [OnSend](../mfc/reference/casyncsocket-class.md#onsend), [OnAccept](../mfc/reference/casyncsocket-class.md#onaccept), [OnConnect](../mfc/reference/casyncsocket-class.md#onconnect), and [OnClose](../mfc/reference/casyncsocket-class.md#onclose). You can override the functions in your derived socket class to take advantage of the notifications they provide when network events occur. The framework calls these notification callback functions to notify you of important socket events, such as the receipt of data that you can begin reading. For more information about notification functions, see [Windows Sockets: Socket Notifications](../mfc/windows-sockets-socket-notifications.md). diff --git a/docs/mfc/windows-sockets-example-of-sockets-using-archives.md b/docs/mfc/windows-sockets-example-of-sockets-using-archives.md index bd76e3b6f35..92d56b0acb9 100644 --- a/docs/mfc/windows-sockets-example-of-sockets-using-archives.md +++ b/docs/mfc/windows-sockets-example-of-sockets-using-archives.md @@ -1,12 +1,14 @@ --- -description: "Learn more about: Windows Sockets: Example of Sockets Using Archives" title: "Windows Sockets: Example of Sockets Using Archives" -ms.date: "11/04/2016" +description: "Learn more about: Windows Sockets: Example of Sockets Using Archives" +ms.date: 11/04/2016 helpviewer_keywords: ["sockets [MFC], with archives", "examples [MFC], Windows Sockets", "Windows Sockets [MFC], with archives"] -ms.assetid: 2e3c9bb2-7e7b-4f28-8dc5-6cb7a484edac --- # Windows Sockets: Example of Sockets Using Archives +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article presents an example of using class [CSocket](../mfc/reference/csocket-class.md). The example employs `CArchive` objects to serialize data through a socket. Note that this is not document serialization to or from a file. The following example illustrates how you use the archive to send and receive data through `CSocket` objects. The example is designed so that two instances of the application (on the same machine or on different machines on the network) exchange data. One instance sends data, which the other instance receives and acknowledges. Either application can initiate an exchange, and either can act as server or as client to the other application. The following function is defined in the application's view class: @@ -50,6 +52,6 @@ For more information, see Windows Sockets Specification: **htonl**, **htons**, * [Windows Sockets in MFC](../mfc/windows-sockets-in-mfc.md)
[CArchive::IsStoring](../mfc/reference/carchive-class.md#isstoring)
[CArchive::operator <<](../mfc/reference/carchive-class.md#operator_lt_lt)
-[CArchive::operator >>](../mfc/reference/carchive-class.md#operator_lt_lt)
+[CArchive::operator >>](../mfc/reference/carchive-class.md#operator_gt_gt)
[CArchive::Flush](../mfc/reference/carchive-class.md#flush)
[CObject::Serialize](../mfc/reference/cobject-class.md#serialize) diff --git a/docs/mfc/windows-sockets-how-sockets-with-archives-work.md b/docs/mfc/windows-sockets-how-sockets-with-archives-work.md index 6532e6b427a..d09962908a2 100644 --- a/docs/mfc/windows-sockets-how-sockets-with-archives-work.md +++ b/docs/mfc/windows-sockets-how-sockets-with-archives-work.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: How Sockets with Archives Work" title: "Windows Sockets: How Sockets with Archives Work" ms.date: "11/19/2018" helpviewer_keywords: ["Windows Sockets [MFC], synchronous", "sockets [MFC], synchronous operation", "sockets [MFC], with archives", "synchronous state socket", "Windows Sockets [MFC], with archives", "two-state socket object"] -ms.assetid: d8ae4039-391d-44f0-a19b-558817affcbb --- # Windows Sockets: How Sockets with Archives Work +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how a [CSocket](../mfc/reference/csocket-class.md) object, a [CSocketFile](../mfc/reference/csocketfile-class.md) object, and a [CArchive](../mfc/reference/carchive-class.md) object are combined to simplify sending and receiving data through a Windows Socket. The article [Windows Sockets: Example of Sockets Using Archives](../mfc/windows-sockets-example-of-sockets-using-archives.md) presents the `PacketSerialize` function. The archive object in the `PacketSerialize` example works much like an archive object passed to an MFC [Serialize](../mfc/reference/cobject-class.md#serialize) function. The essential difference is that for sockets, the archive is attached not to a standard [CFile](../mfc/reference/cfile-class.md) object (typically associated with a disk file) but to a `CSocketFile` object. Rather than connecting to a disk file, the `CSocketFile` object connects to a `CSocket` object. diff --git a/docs/mfc/windows-sockets-in-mfc.md b/docs/mfc/windows-sockets-in-mfc.md index c75929505b3..d63008126b5 100644 --- a/docs/mfc/windows-sockets-in-mfc.md +++ b/docs/mfc/windows-sockets-in-mfc.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets in MFC" title: "Windows Sockets in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["WINSOCK.DLL", "sockets [MFC], programming models", "MFC, Windows Sockets", "Windows Sockets [MFC], MFC support", "Windows Sockets [MFC], programming models", "WSOCK32.DLL", "sockets [MFC], MFC"] -ms.assetid: 1f3c476a-9c68-49fe-9a25-d22971a334d0 --- # Windows Sockets in MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + > [!NOTE] > MFC supports Windows Sockets 1 but does not support [Windows Sockets 2](/windows/win32/WinSock/windows-sockets-start-page-2). Windows Sockets 2 first shipped with Windows 98 and is the version included with Windows 2000. @@ -30,7 +32,7 @@ Creating and using `CSocket` and `CAsyncSocket` objects is described in [Windows ## Windows Sockets DLLs -The Microsoft Windows operating systems supply the Windows Sockets dynamic-link libraries (DLL). Visual C++ supplies the appropriate header files and libraries and the Windows Sockets specification. +The Microsoft Windows operating systems supply the Windows Sockets dynamic-link libraries (DLL). Visual Studio supplies the appropriate header files and libraries and the Windows Sockets specification. For more information about Windows Sockets, see: diff --git a/docs/mfc/windows-sockets-ports-and-socket-addresses.md b/docs/mfc/windows-sockets-ports-and-socket-addresses.md index d4026d95f32..a8de0f7603f 100644 --- a/docs/mfc/windows-sockets-ports-and-socket-addresses.md +++ b/docs/mfc/windows-sockets-ports-and-socket-addresses.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Ports and Socket Addresses" title: "Windows Sockets: Ports and Socket Addresses" ms.date: "11/04/2016" helpviewer_keywords: ["ports [MFC], definition", "Windows Sockets [MFC], ports", "Windows Sockets [MFC], addresses", "ports [MFC]", "addresses [MFC], socket", "sockets [MFC], addresses", "sockets [MFC], ports"] -ms.assetid: e050261a-9285-4f31-a1c5-6c8033af5b4a --- # Windows Sockets: Ports and Socket Addresses +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the terms "port" and "address" as used with Windows Sockets. ## Port diff --git a/docs/mfc/windows-sockets-sequence-of-operations.md b/docs/mfc/windows-sockets-sequence-of-operations.md index cf5c241e016..82a4873c610 100644 --- a/docs/mfc/windows-sockets-sequence-of-operations.md +++ b/docs/mfc/windows-sockets-sequence-of-operations.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Sequence of Operations" title: "Windows Sockets: Sequence of Operations" ms.date: "11/04/2016" helpviewer_keywords: ["Windows Sockets [MFC], operations", "Windows Sockets [MFC], stream sockets", "sockets [MFC], stream sockets", "sockets [MFC], operations", "stream sockets [MFC]"] -ms.assetid: 43ce76f5-aad3-4247-b8a6-16cc7d012796 --- # Windows Sockets: Sequence of Operations +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article illustrates, side by side, the sequence of operations for a server socket and a client socket. Because the sockets use `CArchive` objects, they are necessarily [stream sockets](../mfc/windows-sockets-stream-sockets.md). ## Sequence of Operations for a Stream Socket Communication diff --git a/docs/mfc/windows-sockets-socket-notifications.md b/docs/mfc/windows-sockets-socket-notifications.md index b0119e77c9b..2716daf8e39 100644 --- a/docs/mfc/windows-sockets-socket-notifications.md +++ b/docs/mfc/windows-sockets-socket-notifications.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Socket Notifications" title: "Windows Sockets: Socket Notifications" ms.date: "11/04/2016" helpviewer_keywords: ["Windows Sockets [MFC], notifications", "notifications [MFC], socket", "sockets [MFC], notifications"] -ms.assetid: 87d5bf70-6e77-49a9-9a64-aaadee2ad018 --- # Windows Sockets: Socket Notifications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the notification functions in the socket classes. These member functions are callback functions that the framework calls to notify your socket object of important events. The notification functions are: - [OnReceive](../mfc/reference/casyncsocket-class.md#onreceive): Notifies this socket that there is data in the buffer for it to retrieve by calling [Receive](../mfc/reference/casyncsocket-class.md#receive). diff --git a/docs/mfc/windows-sockets-stream-sockets.md b/docs/mfc/windows-sockets-stream-sockets.md index e87a2ee37f2..30bff346e13 100644 --- a/docs/mfc/windows-sockets-stream-sockets.md +++ b/docs/mfc/windows-sockets-stream-sockets.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Stream Sockets" title: "Windows Sockets: Stream Sockets" ms.date: "11/04/2016" helpviewer_keywords: ["Windows Sockets [MFC], stream sockets", "sockets [MFC], stream sockets", "stream sockets [MFC]"] -ms.assetid: 31faaa34-a995-493f-a30b-b8115293d619 --- # Windows Sockets: Stream Sockets +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes stream sockets, one of the two Windows Socket types available. (The other type is the [datagram socket](../mfc/windows-sockets-datagram-sockets.md).) Stream sockets provide for a data flow without record boundaries: a stream of bytes that can be bidirectional (the application is full duplex: it can both transmit and receive through the socket). Streams can be relied upon to deliver sequenced, unduplicated data. ("Sequenced" means that packets are delivered in the order sent. "Unduplicated" means that you get a particular packet only once.) Receipt of stream messages is guaranteed, and streams are well suited to handling large amounts of data. diff --git a/docs/mfc/windows-sockets-using-class-casyncsocket.md b/docs/mfc/windows-sockets-using-class-casyncsocket.md index b0a56716364..e4628d00c61 100644 --- a/docs/mfc/windows-sockets-using-class-casyncsocket.md +++ b/docs/mfc/windows-sockets-using-class-casyncsocket.md @@ -1,16 +1,19 @@ --- -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`. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +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`. +`CAsyncSocket` is documented in the *MFC Reference*. Visual Studio also supplies the Windows Sockets specification, located in the Windows SDK. The details are left to you. Visual Studio 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 +25,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 +51,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 +86,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/mfc/windows-sockets-using-sockets-with-archives.md b/docs/mfc/windows-sockets-using-sockets-with-archives.md index cd35be2b053..139a4bfd6be 100644 --- a/docs/mfc/windows-sockets-using-sockets-with-archives.md +++ b/docs/mfc/windows-sockets-using-sockets-with-archives.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets: Using Sockets with Archives" title: "Windows Sockets: Using Sockets with Archives" ms.date: "11/04/2016" helpviewer_keywords: ["Windows Sockets [MFC], archives", "sockets [MFC], with archives", "archives [MFC], and Windows Sockets", "CSocket class [MFC], programming model"] -ms.assetid: 17e71a99-a09e-4e1a-9fda-13d62805c824 --- # Windows Sockets: Using Sockets with Archives +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article describes the [CSocket programming model](#_core_the_csocket_programming_model). Class [CSocket](../mfc/reference/csocket-class.md) supplies socket support at a higher level of abstraction than does class [CAsyncSocket](../mfc/reference/casyncsocket-class.md). `CSocket` uses a version of the MFC serialization protocol to pass data to and from a socket object through an MFC [CArchive](../mfc/reference/carchive-class.md) object. `CSocket` provides blocking (while managing background processing of Windows messages) and gives you access to `CArchive`, which manages many aspects of the communication that you would have to do yourself using either the raw API or class `CAsyncSocket`. > [!TIP] diff --git a/docs/mfc/windows-sockets.md b/docs/mfc/windows-sockets.md index 5459fe65933..04568103ca6 100644 --- a/docs/mfc/windows-sockets.md +++ b/docs/mfc/windows-sockets.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows Sockets" title: "Windows Sockets" ms.date: "11/04/2016" helpviewer_keywords: ["sockets [MFC], Windows sockets", "networks [MFC], Windows Sockets", "programming [MFC], network", "sockets [MFC]", "Windows Sockets [MFC]"] -ms.assetid: c077ec53-540d-4bfb-a1e0-bd6482ab9e19 --- # Windows Sockets +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This family of articles covers the MFC implementation of Windows Sockets. MFC supplies two classes to support programming network applications with the Windows Sockets API. Class [CAsyncSocket](../mfc/reference/casyncsocket-class.md) encapsulates the Windows Sockets API one for one, giving advanced network programmers the most power and flexibility. Class [CSocket](../mfc/reference/csocket-class.md) provides a simplified interface for serializing data to and from a [CArchive](../mfc/reference/carchive-class.md) object. ## In This Section diff --git a/docs/mfc/windows.md b/docs/mfc/windows.md index b8c0f5aee20..92c62e35331 100644 --- a/docs/mfc/windows.md +++ b/docs/mfc/windows.md @@ -3,10 +3,12 @@ description: "Learn more about: Windows" title: "Windows" ms.date: "11/04/2016" helpviewer_keywords: ["objects [MFC], window", "windows [MFC]", "MFC, windows", "window objects [MFC], MFC Framework"] -ms.assetid: dd92bf34-842e-40fe-8aea-3028b55314d5 --- # Windows +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This family of articles covers window objects in the MFC framework. All MFC windows derive from class [CWnd](../mfc/reference/cwnd-class.md), including frame windows, views, dialog boxes, and controls. The first group of articles describes [window objects](../mfc/window-objects.md) in general. Refer to this group for general information about C++ window objects, how they encapsulate an `HWND`, and how you use them when creating your own windows, such as child windows. diff --git a/docs/mfc/wininet-basics.md b/docs/mfc/wininet-basics.md index 8dc432382e0..57b100acb73 100644 --- a/docs/mfc/wininet-basics.md +++ b/docs/mfc/wininet-basics.md @@ -3,10 +3,12 @@ description: "Learn more about: WinInet Basics" title: "WinInet Basics" ms.date: "11/04/2016" helpviewer_keywords: ["OnStatusCallback method [MFC]", "WinInet classes [MFC], displaying progress", "WinInet classes [MFC], about WinInet classes"] -ms.assetid: 665de5ac-e80d-427d-8d91-2ae466885940 --- # WinInet Basics +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + You can use WinInet to add FTP support to download and upload files from within your application. You can override [OnStatusCallback](../mfc/reference/cinternetsession-class.md#onstatuscallback) and use the *dwContext* parameter to provide progress information to users as you search for and download files. This article contains the following topics: diff --git a/docs/mfc/wizards-and-the-resource-editors.md b/docs/mfc/wizards-and-the-resource-editors.md index daf62848239..d7b409d03e4 100644 --- a/docs/mfc/wizards-and-the-resource-editors.md +++ b/docs/mfc/wizards-and-the-resource-editors.md @@ -3,15 +3,17 @@ description: "Learn more about: Wizards and the Resource Editors" title: "Wizards and the Resource Editors" ms.date: "11/04/2016" helpviewer_keywords: ["application wizards [MFC], and MFC", "MFC, resource editors", "resource editors, MFC", "MFC Application Wizard", "editors [MFC], resource", "wizards [MFC]", "wizards [MFC], MFC programming", "MFC, wizards", "Class View tool, managing Windows messages"] -ms.assetid: f5dd4d13-9dc1-4a49-b6bf-5b3cb45fa8ba --- # Wizards and the Resource Editors -Visual C++ includes several wizards for use in MFC programming, along with many integrated resource editors. For ActiveX controls programming, the [ActiveX Control Wizard](../mfc/reference/mfc-activex-control-wizard.md) serves a purpose much like that of the MFC Application Wizard. While you can write MFC applications without most of these tools, the tools greatly simplify and speed your work. +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + +Visual Studio includes several wizards for use in MFC programming, along with many integrated resource editors. For ActiveX controls programming, the [ActiveX Control Wizard](../mfc/reference/mfc-activex-control-wizard.md) serves a purpose much like that of the MFC Application Wizard. While you can write MFC applications without most of these tools, the tools greatly simplify and speed your work. ## Use the MFC Application Wizard to Create an MFC Application -Use the [MFC Application Wizard](../mfc/reference/mfc-application-wizard.md) to create an MFC project in Visual C++, which can include OLE and database support. Files in the project contain your application, document, view, and frame-window classes; standard resources, including menus and an optional toolbar; other required Windows files; and optional .rtf files containing standard Windows Help topics that you can revise and augment to create your program's help file. +Use the [MFC Application Wizard](../mfc/reference/mfc-application-wizard.md) to create an MFC project in Visual Studio, which can include OLE and database support. Files in the project contain your application, document, view, and frame-window classes; standard resources, including menus and an optional toolbar; other required Windows files; and optional .rtf files containing standard Windows Help topics that you can revise and augment to create your program's help file. ## Use Class View to Manage Classes and Windows Messages @@ -30,11 +32,11 @@ The [Class Wizard](reference/mfc-class-wizard.md) will create empty message-hand ## Use the Resource Editors to Create and Edit Resources -Use the Visual C++ [resource editors](../windows/resource-editors.md) to create and edit menus, dialog boxes, custom controls, accelerator keys, bitmaps, icons, cursors, strings, and version resources. As of Visual C++ version 4.0, a toolbar editor makes creating toolbars much easier. +Use the Visual Studio [resource editors](../windows/resource-editors.md) to create and edit menus, dialog boxes, custom controls, accelerator keys, bitmaps, icons, cursors, strings, and version resources. As of Visual Studio version 4.0, a toolbar editor makes creating toolbars much easier. To help you even more, the Microsoft Foundation Class Library provides a file called COMMON.RES, which contains "clip art" resources that you can copy from COMMON.RES and paste into your own resource file. COMMON.RES includes toolbar buttons, common cursors, icons, and more. You can use, modify, and redistribute these resources in your application. For more information about COMMON.RES, see the [Clipart sample](../overview/visual-cpp-samples.md). -The MFC Application Wizard, the Visual C++ wizards, resource editors, and the MFC framework do a lot of work for you and make managing your code much easier. The bulk of your application-specific code is in your document and view classes. +The MFC Application Wizard, the Visual Studio wizards, resource editors, and the MFC framework do a lot of work for you and make managing your code much easier. The bulk of your application-specific code is in your document and view classes. ## See also diff --git a/docs/mfc/word-breaks-in-rich-edit-controls.md b/docs/mfc/word-breaks-in-rich-edit-controls.md index c4bd94e11bb..860a8188dac 100644 --- a/docs/mfc/word-breaks-in-rich-edit-controls.md +++ b/docs/mfc/word-breaks-in-rich-edit-controls.md @@ -3,10 +3,12 @@ description: "Learn more about: Word Breaks in Rich Edit Controls" title: "Word Breaks in Rich Edit Controls" ms.date: "11/04/2016" helpviewer_keywords: ["CRichEditCtrl class [MFC], word breaks in", "word breaks", "breaking words in CRichEditCtrl", "rich edit controls [MFC], word breaks in"] -ms.assetid: 641dcf9e-7b40-4dc0-85f7-575a8c142f73 --- # Word Breaks in Rich Edit Controls +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + A rich edit control ([CRichEditCtrl](../mfc/reference/cricheditctrl-class.md)) calls a function called a "word break procedure" to find breaks between words and to determine where it can break lines. The control uses this information when performing word-wrap operations and when processing the CTRL+LEFT and CTRL+RIGHT key combinations. An application can send messages to a rich edit control to replace the default word-break procedure, to retrieve word-break information, and to determine what line a given character falls on. ## See also diff --git a/docs/mfc/working-with-a-header-control.md b/docs/mfc/working-with-a-header-control.md index 920a1c5ff09..d08784122db 100644 --- a/docs/mfc/working-with-a-header-control.md +++ b/docs/mfc/working-with-a-header-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Working with a Header Control" title: "Working with a Header Control" ms.date: "11/04/2016" helpviewer_keywords: ["header controls [MFC], working with", "header controls"] -ms.assetid: af3afb5c-bf97-451b-8fee-3adcb8257210 +ms.topic: concept-article --- # Working with a Header Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The easy way to use a header control ([CHeaderCtrl](../mfc/reference/cheaderctrl-class.md)) is in conjunction with a list control; see [Using CListCtrl](../mfc/using-clistctrl.md) later in this topic family. You can also use a header control by itself. MFC calls `InitCommonControls` for you. The key tasks are as follows: - [Creating the header control](../mfc/creating-the-header-control.md) diff --git a/docs/mfc/working-with-a-tab-control.md b/docs/mfc/working-with-a-tab-control.md index 6894322f677..6e7adf73b88 100644 --- a/docs/mfc/working-with-a-tab-control.md +++ b/docs/mfc/working-with-a-tab-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Working with a Tab Control" title: "Working with a Tab Control" ms.date: "11/04/2016" helpviewer_keywords: ["CTabCtrl class [MFC], using", "tab controls [MFC], working with", "tab controls [MFC], using"] -ms.assetid: 819488e3-4944-44b7-9483-195edb8e0aed +ms.topic: concept-article --- # Working with a Tab Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The easiest way to use a tab control ([CTabCtrl](../mfc/reference/ctabctrl-class.md)) is by adding it to a dialog template resource with the dialog editor. You can also use a tab control by itself. MFC calls `InitCommonControls` for you. The key tasks are as follows: - [Creating the tab control](../mfc/creating-the-tab-control.md) diff --git a/docs/mfc/working-with-the-toolbar-control.md b/docs/mfc/working-with-the-toolbar-control.md index f0660e38d6d..ed5fe057c34 100644 --- a/docs/mfc/working-with-the-toolbar-control.md +++ b/docs/mfc/working-with-the-toolbar-control.md @@ -3,10 +3,13 @@ description: "Learn more about: Working with the Toolbar Control" title: "Working with the Toolbar Control" ms.date: "11/04/2016" helpviewer_keywords: ["GetToolBarCtrl method [MFC]", "toolbars [MFC], accessing common control", "CToolBarCtrl class [MFC], accessing toolbar", "toolbar controls [MFC], accessing"] -ms.assetid: b19409d5-3831-42c7-80ae-195c49dc9085 +ms.topic: how-to --- # Working with the Toolbar Control +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains how you can access the [CToolBarCtrl](../mfc/reference/ctoolbarctrl-class.md) object underlying a [CToolBar](../mfc/reference/ctoolbar-class.md) for greater control over your toolbars. This is an advanced topic. ## Procedures diff --git a/docs/mfc/working-with-window-objects.md b/docs/mfc/working-with-window-objects.md index 3624187334e..2630a6af645 100644 --- a/docs/mfc/working-with-window-objects.md +++ b/docs/mfc/working-with-window-objects.md @@ -3,10 +3,13 @@ description: "Learn more about: Working with Window Objects" title: "Working with Window Objects" ms.date: "11/04/2016" helpviewer_keywords: ["child windows [MFC], working with", "window objects [MFC], working with"] -ms.assetid: f73aa254-90e3-46a9-8e9b-d78b7054a331 +ms.topic: concept-article --- # Working with Window Objects +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + Working with windows calls for two kinds of activity: - Handling Windows messages diff --git a/docs/mfc/writing-an-internet-client-application-using-mfc-wininet-classes.md b/docs/mfc/writing-an-internet-client-application-using-mfc-wininet-classes.md index ce28434c991..339dc335a7b 100644 --- a/docs/mfc/writing-an-internet-client-application-using-mfc-wininet-classes.md +++ b/docs/mfc/writing-an-internet-client-application-using-mfc-wininet-classes.md @@ -3,10 +3,13 @@ description: "Learn more about: Writing an Internet Client Application Using MFC title: "Writing an Internet Client Application Using MFC WinInet Classes" ms.date: "11/04/2016" helpviewer_keywords: ["Internet client applications [MFC]", "WinInet classes [MFC], programming", "Internet client applications [MFC], writing", "Internet applications [MFC], WinInet", "Internet applications [MFC], client applications", "MFC, Internet applications"] -ms.assetid: a2c4a40c-a94e-4b3e-9dbf-f8a8dc8e5428 +ms.topic: concept-article --- # Writing an Internet Client Application Using MFC WinInet Classes +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The basis of every Internet client application is the Internet session. MFC implements Internet sessions as objects of class [CInternetSession](../mfc/reference/cinternetsession-class.md). Using this class, you can create one Internet session or several simultaneous sessions. To communicate with a server, you need a [CInternetConnection](../mfc/reference/cinternetconnection-class.md) object as well as a `CInternetSession`. You can create a `CInternetConnection` by using [CInternetSession::GetFtpConnection](../mfc/reference/cinternetsession-class.md#getftpconnection), [CInternetSession::GetHttpConnection](../mfc/reference/cinternetsession-class.md#gethttpconnection), or [CInternetSession::GetGopherConnection](../mfc/reference/cinternetsession-class.md#getgopherconnection). Each of these calls is specific to the protocol type. These calls do not open a file on the server for reading or writing. If you intend to read or write data, you must open the file as a separate step. diff --git a/docs/mfc/writing-mfc-applications.md b/docs/mfc/writing-mfc-applications.md index 8858085fae1..b42cbf62a52 100644 --- a/docs/mfc/writing-mfc-applications.md +++ b/docs/mfc/writing-mfc-applications.md @@ -3,10 +3,13 @@ description: "Learn more about: Writing MFC Applications" title: "Writing MFC Applications" ms.date: "09/12/2018" helpviewer_keywords: ["Internet applications [MFC], MFC", "MFC, Internet applications", "application wizards [MFC], Internet applications", "MFC, application development"] -ms.assetid: 6a8d8a03-abfa-4976-86c2-c5773a4b7179 +ms.topic: concept-article --- # Writing MFC Applications +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + This article explains the initial steps you take to develop your application. First, you must decide what kind of application you are writing. Several of the choices were discussed in [Application Design Choices](../mfc/application-design-choices.md). Will your application be: - Running on the Internet or an intranet diff --git a/docs/overview/compiler-versions.md b/docs/overview/compiler-versions.md new file mode 100644 index 00000000000..a51e9795b8e --- /dev/null +++ b/docs/overview/compiler-versions.md @@ -0,0 +1,193 @@ +--- +description: "Learn more about Microsoft C++ compiler versioning." +title: "Microsoft C++ (MSVC) compiler versioning" +ms.date: 05/12/2026 +ms.service: "visual-cpp" +ms.subservice: "tools" +helpviewer_keywords: ["Visual C++, platforms supported", "platforms [C++]"] +--- +# Microsoft C++ (MSVC) compiler versioning + +The Microsoft C++ (MSVC) 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 versions 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 versions 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). + +## Visual Studio channels + +All MSVC Build Tools are available through the Visual Studio Installer. + +The [Visual Studio Stable Channel](https://visualstudio.microsoft.com) gets monthly updates and includes the latest supported MSVC Build Tools. The [Visual Studio Insiders Channel](https://visualstudio.microsoft.com/insiders) updates more often, so you can try upcoming MSVC changes sooner. For more information about the release cadence, see [Visual Studio 2026 release rhythm](/visualstudio/releases/2026/release-rhythm) and [Visual Studio Insiders release notes](/visualstudio/releases/2026/release-notes-insiders). + +Each Visual Studio update receives updates to all of the MSVC build toolsets: +- The **preview** toolset receives new features and fixes that the development team completed since the previous update. +- The **default** and **older in-support** toolsets receive only targeted bug fixes. + +Visual Studio Insiders users get early access to MSVC releases: +- On the Insiders Channel, preview toolsets update approximately weekly. +- On the Insiders Channel, new toolsets are available as release candidates about a month before they reach the Stable Channel, giving Insiders users time to validate the toolset and report issues. + +### Install specific MSVC toolsets + +- To install only the default MSVC toolset, install the `Desktop development with C++` workload. +- To install the preview toolset, run the Visual Studio Installer and select **MSVC Build Tools for <arch> (Preview)**. For more information, see [MSVC Build Tools Preview](https://aka.ms/msvc/preview). +- To install an older in-support 14.5x toolset, run the Visual Studio Installer, open the **Individual Components** tab, and select the specific 14.5x toolset. +- To restore a previously installed toolset after an upgrade—for example, when 14.50 is replaced by 14.51—add the older toolset back from the **Individual Components** tab. +- To install only the Build Tools without the full Visual Studio IDE, use the [Visual Studio Stable Build Tools SKU](https://aka.ms/vs/stable/vs_BuildTools.exe). +- Some out-of-support toolsets (labeled **(Out of support)**) may also be available in the Visual Studio Installer. These toolsets don't receive any updates and may be removed in the future. We strongly recommend moving to a supported version. + +## 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 versions 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 revision version of the compiler. It has the form: R. Use it to distinguish between compiler revisions. + +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 version 17.1 to Visual Studio 2022 version 17.2. In that case, `_MSC_VER` changed from 1931 to 1932. + +The following table lists the Visual Studio version that corresponds to each MSVC compiler (`_MSC_VER`) and MSVC Build Tools release, together with support status. EOL means end of life. + +| Visual Studio version | `_MSC_VER` | MSVC Build Tools version | Support | More info | +|--|--|--|--|--| +| Visual Studio 6.0 | 1200 | 6.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio .NET 2002 (7.0) | 1300 | 7.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio .NET 2003 (7.1) | 1310 | 7.1 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio 2005 (8.0) | 1400 | 8.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio 2008 (9.0) | 1500 | 9.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio 2010 (10.0) | 1600 | 10.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio 2012 (11.0) | 1700 | 11.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio 2013 (12.0) | 1800 | 12.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio 2015 (14.0) | 1900 | 14.0 | EOL | [Visual Studio lifecycle policy](/visualstudio/releases/2026/servicing-vs#support-for-older-versions) | +| Visual Studio 2017 RTW (15.0) | 1910 | 14.10 | EOL | [Visual Studio 2017 lifecycle](/lifecycle/products/visual-studio-2017) | +| Visual Studio 2017 version 15.3 | 1911 | 14.11 | EOL | [Visual Studio 2017 lifecycle](/lifecycle/products/visual-studio-2017) | +| Visual Studio 2017 version 15.5 | 1912 | 14.12 | EOL | [Visual Studio 2017 lifecycle](/lifecycle/products/visual-studio-2017) | +| Visual Studio 2017 version 15.6 | 1913 | 14.13 | EOL | [Visual Studio 2017 lifecycle](/lifecycle/products/visual-studio-2017) | +| Visual Studio 2017 version 15.7 | 1914 | 14.14 | EOL | [Visual Studio 2017 lifecycle](/lifecycle/products/visual-studio-2017) | +| Visual Studio 2017 version 15.8 | 1915 | 14.15 | EOL | [Visual Studio 2017 lifecycle](/lifecycle/products/visual-studio-2017) | +| Visual Studio 2017 version 15.9 | 1916 | 14.16 | Apr 13, 2027 | [Visual Studio 2017 lifecycle](/lifecycle/products/visual-studio-2017) | +| Visual Studio 2019 RTW (16.0) | 1920 | 14.20 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.1 | 1921 | 14.21 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.2 | 1922 | 14.22 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.3 | 1923 | 14.23 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.4 | 1924 | 14.24 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.5 | 1925 | 14.25 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.6 | 1926 | 14.26 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.7 | 1927 | 14.27 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.8, 16.9 a | 1928 | 14.28 | EOL | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2019 version 16.10, 16.11 b | 1929 | 14.29 | Apr 10, 2029 | [Visual Studio 2019 lifecycle](/lifecycle/products/visual-studio-2019) | +| Visual Studio 2022 RTW 17.0 | 1930 | 14.30 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.1 | 1931 | 14.31 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.2 | 1932 | 14.32 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.3 | 1933 | 14.33 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.4 | 1934 | 14.34 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.5 | 1935 | 14.35 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.6 | 1936 | 14.36 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.7 | 1937 | 14.37 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.8 | 1938 | 14.38 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.9 | 1939 | 14.39 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.10 | 1940 | 14.40 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.11 | 1941 | 14.41 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.12 | 1942 | 14.42 | Jul 14, 2026 | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.13 | 1943 | 14.43 | EOL | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | +| Visual Studio 2022 version 17.14 | 1944 | 14.44 | Jan 13, 2032 | [Visual Studio 2022 lifecycle](/lifecycle/products/visual-studio-2022) | + +The following table lists MSVC Build Tools versions for Visual Studio 2026 and later. Starting with Visual Studio 2026, MSVC versioning is decoupled from Visual Studio versioning. EOL (end of life) dates are defined by the [MSVC lifecycle policy](https://aka.ms/msvc/lifecycle). + +| MSVC Build Tools version | `_MSC_VER` | Support | EOL date | More info | +|--|--|--|--|--| +| 14.50 | 1950 | Long-term | Nov 2028 | [What's New for C++ developers in Visual Studio 2026 version 18.0](https://devblogs.microsoft.com/cppblog/whats-new-for-cpp-developers-in-visual-studio-2026-version-18-0/) | +| 14.51 | 1951 | Standard | Feb 2027 | [MSVC lifecycle policy](https://aka.ms/msvc/lifecycle) | +| 14.52 | 1952 | Standard | Previewc | [MSVC lifecycle policy](https://aka.ms/msvc/lifecycle) | + +a Visual Studio 2019 versions 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 version 16.8 is 192829333. The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 version 16.9 is 192829910. + +b Visual Studio 2019 versions 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 version 16.10 is 192929917. The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 version 16.11 is 192930129. + +c MSVC Build Tools version 14.52 is in preview. The EOL date will be established upon general availability. + +## A brief history of Microsoft 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 to Visual Studio 2022 + +- 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. + +### Visual Studio 2026 and later + +The MSVC build tools that ship with Visual Studio 2026 and later start at version 14.50, and `_MSC_VER` starts at 1950. A new MSVC version—14.51/1951, 14.52/1952, and so on, ships every six months. Support follows the [MSVC lifecycle policy](https://aka.ms/msvc/lifecycle). + +This versioning system differs from earlier Visual Studio releases because MSVC versioning is now separate from Visual Studio versioning. That means the compiler minor version can stay the same across multiple Visual Studio updates. + +At any given time, the Visual Studio Installer can offer several MSVC versions: + +- A preview toolset with the newest changes +- The current default toolset +- Earlier toolsets that are still in support + +For example, as of May 2026: + +- **14.52** is the preview toolset and gets regular feature and fix updates. +- **14.51** is the default toolset released in May 2026, with 9 months of support. +- **14.50** is the toolset released in November 2025, with 3 years of support. + +By November 2026, we expect **14.53** to become the new preview toolset, **14.52** to become the default toolset, and **14.51** and **14.50** to remain in support under the [MSVC lifecycle policy](https://aka.ms/msvc/lifecycle). + +Microsoft changed to this model for three reasons: +- It shortens the time between MSVC feature development and preview availability from months to a week or so. +- It keeps the MSVC release cadence aligned with Visual Studio and long-term servicing releases aligned with .NET Long Term Support (LTS) releases. +- It reduces the complexity of servicing older compilers. + +### Service releases starting with Visual Studio 2017 + +Use `_MSC_FULL_VER` to distinguish servicing releases. The build field (the BBBBB in the MMNNBBBBB version number) typically increases by 1. + +For example, `_MSC_FULL_VER` is useful to distinguish Visual Studio 2019 version 16.8 from 16.9, and Visual Studio 2019 version 16.10 from 16.11. Those versions share the same major and minor versions, so they 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 version 16.8 is 192829333.\ +The minimum value of `_MSC_FULL_VER` for Visual Studio 2019 version 16.9 is 192829910. + +## 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 663bf576e8d..72c38c1e4ae 100644 --- a/docs/overview/cpp-conformance-improvements-2017.md +++ b/docs/overview/cpp-conformance-improvements-2017.md @@ -2,11 +2,12 @@ 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 -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 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 improvements by major release, then by version. To jump directly to the changes for a specific version, use the list below **In this article**. This document lists the changes in Visual Studio 2017. For a guide to the changes in Visual Studio 2022, see [C++ conformance improvements in Visual Studio 2022](cpp-conformance-improvements.md). For a guide to the changes in Visual Studio 2019, see [C++ conformance improvements in Visual Studio 2019](cpp-conformance-improvements-2019.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). @@ -69,7 +70,7 @@ const A& a2{ 1 }; In Visual Studio 2015, the compiler erroneously treated copy-list-initialization in the same way as regular copy-initialization: it considered only converting constructors for overload resolution. In the following example, Visual Studio 2015 chooses `MyInt(23)`. Visual Studio 2017 correctly raises the error. ```cpp -// From http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_closed.html#1228 +// From https://www.open-std.org/jtc1/sc22/wg21/docs/cwg_closed.html#1228 struct MyStore { explicit MyStore(int initialCapacity); }; @@ -464,7 +465,7 @@ int main() // understand C++ and uses BitBlt, which results in a double-free later. f(A()); // C4606 'A': passing argument by value across native and managed // boundary requires valid copy constructor. Otherwise, the runtime - // behavior is undefined.` + // behavior is undefined. } ``` @@ -610,7 +611,7 @@ To fix the warning, put `extern "C"` first: extern "C" __declspec(noinline) HRESULT __stdcall ``` -This warning is off by default in Visual Studio 2017 version 15.3, and only impacts code compiled with **`/Wall`** **`/WX`**. Starting in Visual Studio 2017 version 15.5, it's enabled by default as a level 3 warning. +This warning is off by default in Visual Studio 2017 version 15.3, and only impacts code compiled with **`/Wall`** **`/WX`**. Starting in Visual Studio 2017 version 15.5, it's enabled by default as a level 3 warning. ### `decltype` and calls to deleted destructors @@ -804,7 +805,7 @@ In earlier versions of Visual Studio, the compiler always gave a **`constexpr`** ### Removing allocator support in `std::function` -[P0302R1](https://wg21.link/p0302r1) Prior to C++17, the class template `std::function` had several constructors that took an allocator argument. However, the use of allocators in this context was problematic, and the semantics were unclear. The problem contructors have been removed. +[P0302R1](https://wg21.link/p0302r1) Prior to C++17, the class template `std::function` had several constructors that took an allocator argument. However, the use of allocators in this context was problematic, and the semantics were unclear. The problematic constructors have been removed. ### Fixes for `not_fn()` @@ -1021,7 +1022,7 @@ To fix the error, remove the unused variable. ### Single-line comments -In Visual Studio 2017 version 15.5, warnings C4001 and C4179 are no longer emitted by the C compiler. Previously, they were only emitted under the **`/Za`** compiler switch. The warnings are no longer needed because single-line comments have been part of the C standard since C99. +In Visual Studio 2017 version 15.5, warnings C4001 and C4179 are no longer emitted by the C compiler. Previously, they were only emitted under the **`/Za`** compiler switch. The warnings are no longer needed because single-line comments have been part of the C standard since C99. ```cpp /* C only */ @@ -1050,7 +1051,7 @@ When the code doesn't need to be backwards compatible, avoid the warning by remo ### `__declspec` attributes with `extern "C"` linkage -In earlier versions of Visual Studio, the compiler ignored `__declspec(...)` attributes when `__declspec(...)` was applied before the `extern "C"` linkage specification. This behavior caused code to be generated that user didn't intend, with possible runtime implications. The [C4768](../error-messages/compiler-warnings/c4768.md) warning was added in Visual Studio version 15.3, but was off by default. In Visual Studio 2017 version 15.5, the warning is enabled by default. +In earlier versions of Visual Studio, the compiler ignored `__declspec(...)` attributes when `__declspec(...)` was applied before the `extern "C"` linkage specification. This behavior caused code to be generated that the user didn't intend, with possible runtime implications. The [C4768](../error-messages/compiler-warnings/c4768.md) warning was added in Visual Studio version 15.3, but was off by default. In Visual Studio 2017 version 15.5, the warning is enabled by default. ```cpp __declspec(noinline) extern "C" HRESULT __stdcall // C4768 @@ -1115,7 +1116,7 @@ error C2027: use of undefined type 'S' ### `std::is_convertible` target type -`std::is_convertible` requires the target type to be a valid return type. In earlier versions of Visual Studio, the compiler incorrectly allowed abstract types, which might lead to incorrect overload resolution and unintended runtime behavior. The following code now correctly raises C2338: +`std::is_convertible` requires the target type to be a valid return type. In earlier versions of Visual Studio, the compiler incorrectly allowed abstract types, which might lead to incorrect overload resolution and unintended runtime behavior. The following code now correctly raises C2338: ```cpp #include @@ -1192,7 +1193,7 @@ The warning was added in Visual Studio 2017 version 15.3, but was off by default ### Defaulted functions and `__declspec(nothrow)` -The compiler previously allowed defaulted functions to be declared with `__declspec(nothrow)` when the corresponding base/member functions permitted exceptions. This behavior is contrary to the C++ standard and can cause undefined behavior at runtime. The standard requires such functions to be defined as deleted if there's an exception specification mismatch. Under **`/std:c++17`**, the following code raises C2280: +The compiler previously allowed defaulted functions to be declared with `__declspec(nothrow)` when the corresponding base/member functions permitted exceptions. This behavior is contrary to the C++ standard and can cause undefined behavior at runtime. The standard requires such functions to be defined as deleted if there's an exception specification mismatch. Under **`/std:c++17`**, the following code raises C2280: ```cpp struct A { @@ -1440,7 +1441,7 @@ void sample(A<0> *p) ### C++20: Avoiding unnecessary decay (partial) -[P0777R1](https://wg21.link/p0777r1) Adds differentiation between the concept of "decay" and that of simply removing const or reference qualifiers. New type trait `remove_reference_t` replaces `decay_t` in some contexts. Support for `remove_cvref_t` is implemented in Visual Studio 2019. +[P0777R1](https://wg21.link/p0777r1) Adds differentiation between the concept of "decay" and that of simply removing const or reference qualifiers. New type trait `remove_reference_t` replaces `decay_t` in some contexts. Support for `remove_cvref_t` is implemented in Visual Studio 2019. ### C++17: Parallel algorithms @@ -1456,7 +1457,7 @@ void sample(A<0> *p) ### C++17: Mathematical special functions -[P0226R1](https://wg21.link/p0220r1) Adopts previous technical specifications for Mathematical Special Functions into the standard *``* header. +[P0226R1](https://wg21.link/p0226r1) Adopts previous technical specifications for Mathematical Special Functions into the standard *``* header. ### C++17: Deduction guides for the standard library @@ -1612,7 +1613,7 @@ In [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode ```cpp template -using X = typename T; // C7511: 'T': 'typename' keyword must be +using X = typename T; // C7511: 'T': 'typename' keyword must be // followed by a qualified name ``` @@ -1628,10 +1629,10 @@ The standard C++ attribute [`[[deprecated]]`](../cpp/attributes.md) may be used template using X = __declspec(deprecated("msg")) T; // C2760: syntax error: // unexpected token '__declspec', - // expected 'type specifier'` + // expected 'type specifier' ``` -To fix the error, change to code to the following (with the attribute placed before the '=' of the alias definition): +To fix the error, change the code to the following (with the attribute placed before the '=' of the alias definition): ```cpp template @@ -1677,7 +1678,7 @@ The following code now raises C4643: namespace std { template class vector; // C4643: Forward declaring 'vector' // in namespace std is not permitted - // by the C++ Standard` + // by the C++ Standard } ``` diff --git a/docs/overview/cpp-conformance-improvements-2019.md b/docs/overview/cpp-conformance-improvements-2019.md index 1ca2fe0e0ce..c69a47b06b0 100644 --- a/docs/overview/cpp-conformance-improvements-2019.md +++ b/docs/overview/cpp-conformance-improvements-2019.md @@ -2,11 +2,12 @@ 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 -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++ (MSVC) Build Tools in Visual Studio 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**. This document lists the changes in Visual Studio 2019. For a guide to the changes in Visual Studio 2022, see [C++ conformance improvements in Visual Studio 2022](cpp-conformance-improvements.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). @@ -66,7 +67,16 @@ To avoid the errors, insert a space in the offending line before the final angle ### References to types with mismatched cv-qualifiers -Previously, MSVC allowed direct binding of a reference from a type with mismatched cv-qualifiers below the top level. This binding could allow modification of supposedly const data referred to by the reference. The compiler now creates a temporary, as required by the standard. In Visual Studio 2017, the following code compiles without warnings. In Visual Studio 2019, the compiler raises warning C4172: +> [!NOTE] +> This change only affects Visual Studio 2019 versions 16.0 through 16.8. It was reverted starting in Visual Studio 2019 version 16.9. + +Previously, MSVC allowed direct binding of a reference from a type with mismatched cv-qualifiers below the top level. This binding could allow modification of supposedly const data referred to by the reference. + +The compiler for Visual Studio 2019 versions 16.0 through 16.8 instead creates a temporary, as was required by the standard at that time. Later, the standard retroactively changed making the previous behavior of Visual Studio 2017 and earlier correct, and the behavior of Visual Studio 2019 version 16.0 through 16.8 wrong. Consequently, this change was reverted starting in Visual Studio 2019 version 16.9. + +See [Similar types and reference binding](#similar-types-and-reference-binding) for a related change. + +As an example, in Visual Studio 2017, the following code compiles without warnings. In Visual Studio 2019 versions 16.0 through 16.8, the compiler raises warning C4172. Starting with Visual Studio 2019 version 16.9, the code once again compiles without warnings: ```cpp struct X @@ -435,7 +445,7 @@ The unordered container `reserve` function now actually reserves for N elements, - Added the overloads for container merge and extract member functions that accept rvalue containers. For more information, see [P0083 "Splicing Maps And Sets"](https://wg21.link/p0083r3) -### `std::basic_istream::read` processing of `\r\n`` =>`\n` +### `std::basic_istream::read` processing of `\r\n` => `\n` `std::basic_istream::read` was fixed to not write into parts of the supplied buffer temporarily as part of `\r\n` to `\n` processing. This change gives up some of the performance advantage that was gained in Visual Studio 2017 15.8 for reads larger than 4K in size. However, efficiency improvements from avoiding three virtual calls per character are still present. @@ -445,7 +455,7 @@ The `std::bitset` constructor no longer reads the ones and zeroes in reverse ord ### `std::pair::operator=` regression -We fixed a regression in the `std::pair` assignment operator introduced when implementing [LWG 2729 "Missing SFINAE on `std::pair::operator=`";](https://cplusplus.github.io/LWG/issue2729). It now correctly accepts types convertible to `std::pair` again. +We fixed a regression in the `std::pair` assignment operator introduced when implementing [LWG 2729 "Missing SFINAE on `std::pair::operator=`"](https://cplusplus.github.io/LWG/issue2729). It now correctly accepts types convertible to `std::pair` again. ### Non-deduced contexts for `add_const_t` @@ -455,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 @@ -569,8 +579,8 @@ int main() // The conversion from 'E' to the fixed underlying type 'unsigned char' is better than the // conversion from 'E' to the promoted type 'unsigned int'. f(e); - - // Error C2666. This call is ambiguous, but previously called f(unsigned int, const B&). + + // Error C2666. This call is ambiguous, but previously called f(unsigned int, const B&). f(e, B{}); } ``` @@ -684,7 +694,7 @@ std::equal(std::begin(a), std::end(a), std::begin(b), std::end(b)); ### Effect of defining spaceship operator on `==` and `!=` -A definition of the spaceship operator (**`<=>`**) alone will no longer rewrite expressions involving **`==`** or **`!=`** unless the spaceship operator is marked as **`= default`** ([P1185R2](https://wg21.link/p1185r2)). The following example compiles in Visual Studio 2019 RTW and version 16.1, but produces C2678 in Visual Studio 2019 version 16.2: +A definition of the spaceship operator (**`<=>`**) alone will no longer rewrite expressions involving **`==`** or **`!=`** unless the spaceship operator is marked as **`= default`** ([P1185R2](https://wg21.link/p1185r2)). The following example compiles in Visual Studio 2019 RTW and version 16.1, but produces C2676 in Visual Studio 2019 version 16.2: ```cpp #include @@ -779,7 +789,6 @@ struct Comparer { return a.a < b.a; } }; - ``` ## Conformance improvements in Visual Studio 2019 version 16.3 @@ -876,7 +885,7 @@ The non-standard headers \ and \ have been removed. Code Two-phase name lookup requires that non-dependent names used in template bodies must be visible to the template at definition time. Previously, such names may have been found when the template is instantiated. This change makes it easier to write portable and conforming code in MSVC under the [`/permissive-`](../build/reference/permissive-standards-conformance.md) flag. -In Visual Studio 2019 version 16.4 with the **`/permissive-`** flag set, the following example produces an error, because `N::f` isn't visible when the `f` template is defined: +In Visual Studio 2019 version 16.4 with the **`/permissive-`** flag set, the following example produces an error, because `N::f` isn't visible when the `f` template is defined: ```cpp template @@ -1240,7 +1249,7 @@ void f() { Previously, thread-local variables in DLLs weren't correctly initialized. Other than on the thread that loaded the DLL, they weren't initialized before first use on threads that existed before the DLL was loaded. This defect has now been corrected. Thread-local variables in such a DLL get initialized immediately before their first use on such threads. -This new behavior of testing for initialization on uses of thread-local variables may be disabled by using the **`/Zc:tlsGuards-`** compiler option. Or, by adding the `[[msvc:no_tls_guard]]` attribute to particular thread local variables. +This new behavior of testing for initialization on uses of thread-local variables may be disabled by using the **`/Zc:tlsGuards-`** compiler option. Or, by adding the `[[msvc::no_tls_guard]]` attribute to particular thread local variables. ### Better diagnosis of call to deleted functions @@ -1415,7 +1424,7 @@ In Visual Studio 2019 version 16.6 and later, the behavior of **`typedef`** decl The same restrictions are applied recursively to each nested class. The restriction is meant to ensure the simplicity of structs that have **`typedef`** names for linkage purposes. They must be simple enough that no linkage calculations are necessary before the compiler gets to the **`typedef`** name for linkage. -This change affects all standards modes of the compiler. In default (**`/std:c++14`**) and **`/std:c++17`** modes, the compiler emits warning C5208 for non-conforming code. If **`/permissive-`** is specified, the compiler emits warning C5208 as an error under **`/std:c++14`** and emits error C7626 under **`/std:c++17`**. The compiler emits error C7626 for non-conforming code when **`/std:c++20`** or **`/std:c++latest`** is specified. +This change affects all standards modes of the compiler. In default (**`/std:c++14`**) and **`/std:c++17`** modes, the compiler emits warning C5208 for non-conforming code. If **`/permissive-`** is specified, the compiler emits warning C5208 as an error under **`/std:c++14`** and emits error C7626 under **`/std:c++17`**. The compiler emits error C7626 for non-conforming code when **`/std:c++20`** or **`/std:c++latest`** is specified. The following sample shows the constructs that are no longer allowed in unnamed structs. Depending on the standards mode specified, C5208 or C7626 errors or warnings are emitted: @@ -1925,14 +1934,14 @@ C++20 doesn't support coroutines with a return type that includes a placeholder auto my_generator() { ... co_yield next; -}; +} // /std:c++latest #include std::experimental::generator my_generator() { ... co_yield next; -}; +} ``` #### Return type of `return_value` @@ -2068,10 +2077,14 @@ With this change, a destructor is also potentially throwing if it has a virtual ### Similar types and reference binding -Core Working Group issue [CWG 2352](https://wg21.link/cwg2352) deals with an inconsistency between the reference binding rules and changes to type similarity. The inconsistency was introduced in earlier Defect Reports (such as [CWG 330](https://wg21.link/cwg330)). With this change, code that previously bound a reference to a temporary may now bind directly when the types involved differ only by cv-qualifiers. +Core Working Group issue [CWG 2352](https://wg21.link/cwg2352) deals with an inconsistency between the reference binding rules and changes to type similarity. The inconsistency was introduced in earlier Defect Reports (such as [CWG 330](https://wg21.link/cwg330)). This affected Visual Studio 2019 versions 16.0 through 16.8. + +With this change, starting in Visual Studio 2019 version 16.9, code that previously bound a reference to a temporary in Visual Studio 2019 version 16.0 through 16.8 may now bind directly when the types involved differ only by cv-qualifiers. Visual Studio 2019 version 16.9 implements the changed behavior in all **`/std`** compiler modes. It's potentially a source breaking change. +See [References to types with mismatched cv-qualifiers](#references-to-types-with-mismatched-cv-qualifiers) for a related change. + This sample shows the changed behavior: ```cpp @@ -2088,7 +2101,7 @@ The update may change program behavior that relied on an introduced temporary: int func() { int i1 = 13; int i2 = 23; - + int* iptr = &i1; int const * const& iptrcref = iptr; @@ -2097,7 +2110,7 @@ int func() { { return 1; } - + // Now change what iptr points to. // Prior to CWG 2352 iptrcref should be bound to a temporary and still points to the value 13. @@ -2138,7 +2151,7 @@ class B { template B::~B() { /* ... */ } // Before: no diagnostic. -// Now diagnoses a definition mismatch. To fix, define the implementation by +// Now diagnoses a definition mismatch. To fix, define the implementation by // using the same noexcept-specifier. For example, // B::~B() noexcept { /* ... */ } ``` @@ -2241,7 +2254,7 @@ Earlier versions of the compiler would incorrectly convert the argument of `f` f This change can also correct the chosen overload in some other situations: ```cpp -struct Base +struct Base { operator char *(); }; diff --git a/docs/overview/cpp-conformance-improvements.md b/docs/overview/cpp-conformance-improvements.md index 329ab8ea619..2249e10efaa 100644 --- a/docs/overview/cpp-conformance-improvements.md +++ b/docs/overview/cpp-conformance-improvements.md @@ -1,18 +1,713 @@ --- title: "C++ conformance improvements in Visual Studio 2022" description: "Microsoft C++ in Visual Studio is improving standards conformance and fixing bugs regularly." -ms.date: 05/05/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 + +Visual Studio 2022 version 17.4 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### Underlying types of unscoped `enum` with no fixed type + +In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ compiler didn't correctly determine the underlying type of an unscoped enumeration with no fixed base type. Under [`/Zc:enumTypes`](../build/reference/zc-enumtypes.md), we now correctly implement the standard behavior. + +The C++ Standard requires the underlying type of an **`enum`** to be large enough to hold all enumerators in that **`enum`**. Sufficiently large enumerators can set the underlying type of the **`enum`** to **`unsigned int`**, **`long long`**, or **`unsigned long long`**. Previously, such **`enum`** types always had an underlying type of **`int`** in the Microsoft compiler, regardless of enumerator values. + +When enabled, the **`/Zc:enumTypes`** option is a potential source and binary breaking change. It's off by default, and not enabled by **`/permissive-`**, because the fix might affect binary compatibility. Some enumeration types change size when the conformant fix is enabled. Certain Windows SDK headers include such enumeration definitions. + +#### Example + +```cpp +enum Unsigned +{ + A = 0xFFFFFFFF // Value 'A' does not fit in 'int'. +}; + +// Previously, failed this static_assert. Now passes with /Zc:enumTypes. +static_assert(std::is_same_v, unsigned int>); + +template +void f(T x) +{ +} + +int main() +{ + // Previously called f, now calls f. + f(+A); +} + +// Previously this enum would have an underlying type of `int`, but Standard C++ requires this to have +// a 64-bit underlying type. Using /Zc:enumTypes changes the size of this enum from 4 to 8, which could +// impact binary compatibility with code compiled with an earlier compiler version or without the switch. +enum Changed +{ + X = -1, + Y = 0xFFFFFFFF +}; +``` + +### Types of enumerators within an `enum` definition with no fixed underlying type + +In versions of Visual Studio before Visual Studio 2022 version 17.4, the C++ compiler didn't correctly model the types of enumerators. It could assume an incorrect type in enumerations without a fixed underlying type before the closing brace of the enumeration. Under [`/Zc:enumTypes`](../build/reference/zc-enumtypes.md), the compiler now correctly implements the standard behavior. + +The C++ Standard specifies that within an enumeration definition of no fixed underlying type, initializers determine the types of enumerators. Or, for the enumerators with no initializer, by the type of the previous enumerator (accounting for overflow). Previously, such enumerators were always given the deduced type of the enumeration, with a placeholder for the underlying type (typically **`int`**). + +When enabled, the **`/Zc:enumTypes`** option is a potential source and binary breaking change. It's off by default, and not enabled by **`/permissive-`**, because the fix might affect binary compatibility. Some enumeration types change size when the conformant fix is enabled. Certain Windows SDK headers include such enumeration definitions. + +#### Example + +```cpp +enum Enum { + A = 'A', + B = sizeof(A) +}; + +static_assert(B == 1); // previously failed, now succeeds under /Zc:enumTypes +``` + +In this example the enumerator `A` should have type **`char`** before the closing brace of the enumeration, so `B` should be initialized using `sizeof(char)`. Before the **`/Zc:enumTypes`** fix, `A` had enumeration type `Enum` with a deduced underlying type **`int`**, and `B` was initialized using `sizeof(Enum)`, or 4. + +## Conformance improvements in Visual Studio 2022 version 17.3 + +Visual Studio 2022 version 17.3 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. + +### C: Improved modifier compatibility checking between pointers + +The C compiler didn't properly compare modifiers between pointers, especially `void*`. This defect could result in an improper diagnosis of incompatibility between `const int**` and `void*` and compatibility between `int* volatile*` and `void*`. + +#### Example + +```c +void fn(void* pv) { (pv); } + +int main() +{ + int t = 42; + int* pt = &t; + int* volatile * i = &pt; + fn(i); // Now raises C4090 + const int** j = &pt; + fn(j); // No longer raises C4090 +} +``` ## Conformance improvements in Visual Studio 2022 version 17.2 -Visual Studio 2022 version 17.2 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C++ compiler. +Visual Studio 2022 version 17.2 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. ### Unterminated bidirectional character warnings @@ -46,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 @@ -91,9 +786,9 @@ This rounded DOWN. ### `/Zc:__STDC__` makes `__STDC__` available for C -The C standard requires that a conforming C implementation defines `__STDC__` as `1`. Due to the behavior of the UCRT, which doesn't expose POSIX functions when `__STDC__` is `1`, it isn't possible to define this macro for C by default without introducing breaking changes to the stable language versions. Visual Studio 2022 version 17.2 and later add a conformance option, `/Zc:__STDC__`, 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. +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 @@ -161,24 +856,24 @@ void f() ## Conformance improvements in Visual Studio 2022 version 17.1 -Visual Studio 2022 version 17.1 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C++ compiler. +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 C++ 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`**. #### Example -In Visual C++ 2022 version 17.1 this code now emits an error: +In Visual Studio 2022 version 17.1 this code now emits an error: ```cpp #pragma warning(error:5253) auto incr = [=](int value) { return value + 1; }; -// capture_default.cpp(3,14): error C5253: a 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; }; // ^ ``` @@ -212,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 **`/Zc: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 @@ -247,7 +942,7 @@ With this change, the compiler only emits an error if the function template `f` ## Conformance improvements in Visual Studio 2022 version 17.0 -Visual Studio 2022 version 17.0 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C++ compiler. +Visual Studio 2022 version 17.0 contains the following conformance improvements, bug fixes, and behavior changes in the Microsoft C/C++ compiler. ### Warning on bitfield width for enumeration type @@ -286,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 82b3daf9fd2..579d8db1796 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 @@ -1,20 +1,21 @@ --- -title: "How to report a problem with the Microsoft C++ toolset" +title: "How to report a problem with the Microsoft C++ Build Tools" 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: "cpp-lang" +author: "tylermsft" +ms.author: "twhitney" --- -# How to report a problem with the Microsoft C++ toolset or documentation +# How to report a problem with the Microsoft C++ Build Tools or documentation If you find problems in the Microsoft C++ compiler (MSVC), the linker, or other tools and libraries, we want to know about them. When the issue is in our documentation, we want to know about that, too. ## 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 @@ -310,6 +311,20 @@ After you've generated the preprocessed files, it's a good idea to make sure the Finally, attach the preprocessed repro files (*filename*.i and *modulename*.i) along with the .ifc output to your report. +#### To generate a module trace file + +When issues involve C++ modules, provide a module trace file along with the preprocessed repro improves diagnostic quality to reduce turnaround time. A module trace file records detailed information about module operations during compilation. + +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. Using **/MP** or multi-source invocations can cause the trace to represent only the last compiled file or be incomplete. 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). + +1. Open the **Developer Command Prompt** that matches the Visual Studio version and configuration architecture used to build your project. +1. Enter the command `cl /d1module:enableLogging`*trace.json* [*other-args*] *filename.cpp*. For *trace.json*, specify the desired output file name for the module trace. There can't be a space between `/d1module:enableLogging` and the output file name. For [*other-args*], include any additional compilation arguments. For *filename.cpp*, specify the source file that reproduces the problem. +1. If multiple translation units are involved in the problem, run separate single-file invocations to collect a trace for the specific file that reproduces the problem. You can collect traces for additional relevant files if needed. + +Finally, attach the generated *trace.json* file along with the preprocessed repro to your report. + ### Link repros A *link repro* is the linker-generated contents of a directory, specified either by the **link\_repro** environment variable, or as an argument to the [/LINKREPRO](../build/reference/linkrepro.md) linker option. It contains build artifacts that collectively demonstrate a problem that occurs at link time. Examples include a backend crash involving Link-Time Code Generation (LTCG), or a linker crash. These build artifacts are the ones needed as linker input so the problem can be reproduced. A link repro can be created easily by using this environment variable. It enables the linker's built-in repro generation capability. @@ -328,7 +343,7 @@ A *link repro* is the linker-generated contents of a directory, specified either 1. To build the repro project in Visual Studio, in the developer command prompt console window, enter the command **devenv**. It ensures that the value of the **link\_repro** environment variable is visible to Visual Studio. To build the project at the command line, use the command-line arguments captured above to duplicate the repro build. -1. Build your repro project, and confirm that the expected problem has occurred. +1. Build your repro project, and confirm that the expected problem occurred. 1. Close Visual Studio, if you used it to do the build. @@ -356,29 +371,32 @@ Create your repro as a minimal IDE project, then package it by compressing the e ## Ways to send your report -You have a couple of good ways to get your report to us. You can use Visual Studio's built-in [Report a Problem Tool](/visualstudio/ide/how-to-report-a-problem-with-visual-studio), or the [Visual Studio Developer Community]( https://aka.ms/feedback/report?space=62) page. There's also a **Product feedback** button at the bottom of this page. The choice depends on whether you want to use the built-in tools in the IDE to capture screenshots and organize your report. If you prefer not to, you can use the Developer Community website directly. +You have a couple of good ways to get your report to us. You can use Visual Studio's built-in [problem reporting tool](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) or the [Visual Studio Developer Community](https://aka.ms/feedback/report?space=62) page. There's also a **Product feedback** button at the bottom of this page. The choice depends on whether you want to use the built-in tools in the IDE to capture screenshots and organize your report. If you prefer not to, you can use the Developer Community website directly. > [!NOTE] > Regardless of how you submit your report, Microsoft respects your privacy. Microsoft is committed to compliance with all data privacy laws and regulations. For information about how we treat the data that you send us, see the [Microsoft Privacy Statement](https://privacy.microsoft.com/privacystatement). ### Use the Report a Problem tool -The **Report a Problem** tool in Visual Studio is a way for Visual Studio users to report problems with just a few clicks. It pops up a simple form to send detailed information about the problem you've found. You can then submit your report without ever leaving the IDE. +The **Report a Problem** tool in Visual Studio is a way for Visual Studio users to report problems with just a few clicks. It pops up a simple form to send detailed information about the problem you found. You can then submit your report without ever leaving the IDE. Reporting your problem through the **Report a Problem** tool is easy and convenient from the IDE. You can access it from the title bar by choosing the **Send Feedback** icon next to the **Quick Launch** search box. Or, you can find it on the menu bar in **Help** > **Send Feedback** > **Report a Problem**. -When you choose to report a problem, first search the Developer Community for similar problems. In case your problem has been reported before, upvote the report and add comments with additional specifics. If you don't see a similar problem, choose the **Report new problem** button at the bottom of the Visual Studio Feedback dialog and follow the steps to report your problem. +When you choose to report a problem, first search the Developer Community for similar problems. In case your problem has been reported before, upvote the report and add comments with more specifics. If you don't see a similar problem, choose the **Report new problem** button at the bottom of the Visual Studio Feedback dialog and follow the steps to report your problem. ### Use the Visual Studio Developer Community pages The Visual Studio Developer Community pages are another convenient way to report problems and find solutions for Visual Studio and the C++ compiler, tools, and libraries. There are specific Developer Community pages for [Visual Studio](https://aka.ms/feedback/report?space=8), [Visual Studio for Mac](https://aka.ms/feedback/report?space=41), [.NET](https://aka.ms/feedback/report?space=61), [C++](https://aka.ms/feedback/report?space=62), [Azure DevOps](https://aka.ms/feedback/report?space=21), and [Azure DevOps Server](https://aka.ms/feedback/report?space=22). -Beneath the community tabs, near the top of each page, is a search box. You can use it to find posts that report problems similar to yours. You may find a solution or other useful information related to your problem is already available. If someone has reported the same problem before, then upvote and comment on that report, rather than create a new problem report. To comment, vote, or report a new problem, you may be asked to sign in to your Visual Studio account. The first time you sign in, you'll have to agree to give the Developer Community app access to your profile. +Beneath the community tabs, near the top of each page, is a search box. You can use it to find posts that report problems similar to yours. You may find a solution or other useful information related to your problem is already available. If someone has reported the same problem before, then upvote and comment on that report, rather than create a new problem report. To comment, vote, or report a new problem, you may be asked to sign in to your Visual Studio account. The first time you sign in, you have to agree to give the Developer Community app access to your profile. -For issues with the C++ compiler, linker, and other tools and libraries, first search the [C++ Developer Community](https://aka.ms/vsfeedback/browsecpp) page. If you search for your problem, and it 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. +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. + +> [!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 Microsoft C++ Build Tools (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 +422,6 @@ To maintain your privacy and keep your sensitive information out of public view, ## How to report a C++ documentation issue -We use GitHub issues to track problems reported in our documentation. You can now create GitHub issues directly from a content page, which enables you interact in a much richer way with writers and product teams. If you see an issue with a document, a bad code sample, a confusing explanation, a critical omission, or even just a typo, you can easily let us know. Scroll to the bottom of the page and select **Sign in to give documentation feedback**. You'll need to create a GitHub account if you don't have one already. When you have a GitHub account, you can see all of our documentation issues and their status. You also get notifications when changes are made for the issue you reported. For more information, see [A New Feedback System Is Coming to docs.microsoft.com](/teamblog/a-new-feedback-system-is-coming-to-docs). +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 by using the feedback buttons on the page. Since 2024, we no longer use GitHub issues to track problems reported. For more information, see [Announcing a new way to give feedback on Microsoft Learn](https://techcommunity.microsoft.com/blog/skills-hub-blog/announcing-a-new-way-to-give-feedback-on-microsoft-learn/4027635). -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. +[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 b02dc239e2f..8618404b3e1 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 92e9640c763..9dcb18514d7 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 00000000000..4a2f9020811 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 00000000000..1a5c0f85564 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 00000000000..3b33e677bc3 Binary files /dev/null and b/docs/overview/media/build-insights-view-explanations.png differ diff --git a/docs/overview/media/clang-tidy-improvements.png b/docs/overview/media/clang-tidy-improvements.png new file mode 100644 index 00000000000..fe999aa5360 Binary files /dev/null and b/docs/overview/media/clang-tidy-improvements.png differ diff --git a/docs/overview/media/cmake-intellisense.png b/docs/overview/media/cmake-intellisense.png new file mode 100644 index 00000000000..7f55a9ca39b 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 00000000000..0d66cfc4df8 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 00000000000..9f38ed0e6f4 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 00000000000..6f9ffb6cbc4 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 00000000000..480b05db75f 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 00000000000..7919d0d70ab 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 00000000000..6d39d04e0d5 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 00000000000..8680b640682 Binary files /dev/null and b/docs/overview/media/copilot-smart-variable-inspection.png differ diff --git a/docs/overview/media/cpp-preprocess-menu-entry.png b/docs/overview/media/cpp-preprocess-menu-entry.png new file mode 100644 index 00000000000..59f45d3bc6a Binary files /dev/null and b/docs/overview/media/cpp-preprocess-menu-entry.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 00000000000..531ede1c600 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 00000000000..5a56492bbe4 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 00000000000..8e0c2102398 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 00000000000..7210c4ce6be 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 00000000000..c01f573bbb7 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 00000000000..a293f13ab40 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 00000000000..326070a28e2 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 00000000000..cfab83b0cf8 Binary files /dev/null and b/docs/overview/media/include-diagnostics.png differ diff --git a/docs/overview/media/inline-post-return-value.png b/docs/overview/media/inline-post-return-value.png new file mode 100644 index 00000000000..cace675c49f Binary files /dev/null and b/docs/overview/media/inline-post-return-value.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 00000000000..31e237e4c80 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 00000000000..287be12cea6 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 00000000000..1d112b98f9b 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 00000000000..523959124d4 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 00000000000..4d154f0bd08 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 00000000000..d4a5e14951c 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 00000000000..b42accbd5fd Binary files /dev/null and b/docs/overview/media/vs2022-copilot-git-changes-review.png differ diff --git a/docs/overview/msvc-conformance-improvements.md b/docs/overview/msvc-conformance-improvements.md new file mode 100644 index 00000000000..71c66d185d9 --- /dev/null +++ b/docs/overview/msvc-conformance-improvements.md @@ -0,0 +1,314 @@ +--- +title: "/C++ Conformance improvements, behavior changes, and bug fixes in Microsoft C++ (MSVC) Build Tools" +description: "Summary of conformance improvements in Microsoft C/C++ (MSVC)" +ms.date: 05/12/2026 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" +--- +# C/C++ Conformance improvements, behavior changes, and bug fixes in Microsoft C++ (MSVC) Build Tools + +We make conformance improvements and bug fixes in every release of Microsoft C++ (MSVC) Build Tools. Starting with Visual Studio 2026 version 18.0, we organize major improvements by MSVC Build Tools version number. Use the **In this article** links at the top of this article to jump directly to the changes for a specific version. + +For changes in earlier versions of Visual Studio: + +| Version | Conformance improvements link | +|---|---| +| 2022 | [C++ conformance improvements in Visual Studio 2022](cpp-conformance-improvements.md) | +| 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) | + +## C++ conformance improvements, behavior changes, and bug fixes in MSVC Build Tools v14.51 + +MSVC Build Tools v14.51 continues the progress toward C++23 conformance with several key language feature implementations and numerous Core Working Group (CWG) issue resolutions. This release focuses on compile-time evaluation improvements, Unicode support enhancements, and refined `consteval` handling. + +This version shipped first with Visual Studio 2026 version 18.6 and includes version 19.51 of the MSVC compiler. + +Key highlights of this release include: +- Static `constexpr` variables in `constexpr` functions (P2647R1) +- Relaxed `constexpr` restrictions (P2448R2) +- Unicode support improvements (P2029R4, P2071R2, P2314R4) +- Improved `consteval` function handling with default-enabled experimental features +- New standard library headers `` and `` + +For more information about library features and other updates, see [C++23 Support in MSVC Build Tools 14.51](https://devblogs.microsoft.com/cppblog/c23-support-in-msvc-build-tools-14-51) and [STL Changelog](https://github.com/microsoft/STL/wiki/Changelog). + +### P2647R1: Static constexpr variables in constexpr functions + +[P2647R1](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2647r1.html) allows static local variables to be declared `constexpr` within `constexpr` functions, reducing friction when marking existing functions as `constexpr`. + +```cpp +constexpr char xdigit(int n) +{ + static constexpr char digits[] = "0123456789abcdef"; + return digits[n]; +} +``` + +This feature improves both compile-time evaluation and run-time optimization. Previously, static local variables couldn't be marked `constexpr`, which made it difficult to declare lookup tables inside `constexpr` functions. Now the compiler can evaluate these functions at compile time when possible, while also generating optimized run-time code that accesses the static storage directly. + +### Other C++23 features + +Other C++23 features implemented in this release include Unicode support improvements, labels at the end of compound statements for C compatibility, Class Template Argument Deduction (CTAD) from inherited constructors, and meaningful exports for modules. For more information and related Core Working Group (CWG) issue resolutions, see the [C++23 Support in MSVC Build Tools 14.51](https://devblogs.microsoft.com/cppblog/c23-support-in-msvc-build-tools-14-51). + +### Standard Library + +MSVC Build Tools v14.51 adds new standard library features including: +- `` and `` headers +- Type traits for detecting references binding to temporaries ([P2255R2](https://wg21.link/p2255r2)) +- Explicit lifetime management ([P2590R2](https://wg21.link/p2590r2)), and `is_implicit_lifetime` ([P2674R1](https://wg21.link/P2674R1)). +- Major `` overhaul, SIMD-vectorized STL algorithms using NEON for ARM64/ARM64EC, and 18 Library Working Group (LWG) issue resolutions. +For the complete list, see the [STL Changelog](https://github.com/microsoft/STL/wiki/Changelog). + +## C++ conformance improvements, behavior changes, and bug fixes in MSVC Build Tools v14.50 + +MSVC Build Tools v14.50 introduces improvements to the MSVC compiler and standard library including better C++23 standards conformance, enhanced reliability, and improved correctness. This release also includes numerous bug fixes and updates that benefit large-scale C++ development. + +This version shipped first with Visual Studio 2026 version 18.0 and includes version 19.50 of the MSVC compiler. + +Key highlights of this release include: +- Advanced C++23 feature support including `auto(x)` decay-copy and `#warning` directive. +- Comprehensive `constexpr` improvements, particularly for virtual functions. +- Major stability improvements for C++ modules. +- Extensive reliability fixes reducing internal compiler errors. +- Enhanced C++/CLI support for managed code scenarios. +- The Microsoft C++ standard library (MSVC STL) no longer supports targeting Windows 7/Server 2008 R2, Windows 8/Server 2012, or Windows 8.1/Server 2012 R2. +- Windows 10/Server 2016 are the minimum supported operating systems. + +For more information about performance improvements, bug fixes, and conformance updates in the standard library, see [STL Changelog](https://github.com/microsoft/STL/wiki/Changelog), which is updated regularly. + +## C++23 features + +MSVC Build Tools v14.50 adds support for several C++23 features, bringing the compiler closer to full C++23 conformance. + +### P0849R8: auto(x) - decay-copy in the language + +[P0849R8](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p0849r8.html) introduces the `auto(x)` syntax for decay-copy operations directly in the language, providing a more concise way to express decay-copy semantics. + +Before P0849R8, you needed to explicitly perform decay operations: + +```cpp +// Before P0849R8: +void pop_front_alike(auto& x) +{ + using T = std::decay_t; + std::erase(x, T(x.front())); +} +``` + +After P0849R8, you can use the simpler `auto(x)` syntax: + +```cpp +// After P0849R8: +void pop_front_alike(auto& x) +{ + std::erase(x, auto(x.front())); +} +``` + +This feature provides a standardized way to perform decay-copy operations, making code more readable and reducing the need for verbose template metaprogramming. + +### P2437R1: C++23 `#warning` directive + +[P2437R1](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2437r1.pdf) implements the C++23 `#warning` preprocessor directive, providing a standard way to emit warnings during compilation. + +```cpp +// Valid before C++23. +#error bad configuration... + +// Valid after C++23. +#warning configuration deprecated... +``` + +The `#warning` directive allows you to emit diagnostic messages without stopping compilation, making it useful for deprecation notices and configuration warnings. For more information, see [#warning directive (C/C++)](/cpp/preprocessor/hash-warning-directive-c-cpp). + +### CWG Issue 2586: Explicit object parameter for assignment and comparison + +[CWG Issue 2586](https://cplusplus.github.io/CWG/issues/2586) allows explicit object parameters in assignment and comparison operators, enabling more flexible operator definitions. + +```cpp +struct S +{ + S& operator=(this S&, const S&) = default; // Valid after CWG2586. + auto operator<=>(this const S&, const S&) = default; // Valid after CWG2586. +}; +``` + +This change allows you to use the explicit object parameter syntax (deducing `this`) in assignment and comparison operators, providing more consistent syntax across different types of member functions. + +### P2266R1 : Simpler implicit move + +The introduction of [P2266R1](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2266r1.html) may cause code that was previously treated as an lvalue to be treated as an xvalue or a prvalue. For example: + +```cpp +#include + +template +T& f(T&& t) +{ + return t; +} + +struct S { }; + +void g() +{ + S s1{ }; + S& s2 = f(std::move(s1)); +} +``` + +In C++20, and earlier, this code compiled because even though the type of `t` is `S&&` the use of `t` in `return t` is treated as a glvalue and so it can bind to the return type.\ +With C++23, `t` is treated as an xvalue and so it can't bind to an lvalue reference.\ +One fix is to change to the return type of the function from `T&` to `T&&` but this may affect code that calls this function. An alternative is to use the feature test macro that is associated with this change. For example: + +```cpp +#include + +template +T& f(T&& t) +{ +#if defined(__cpp_implicit_move) + return static_cast&>(t); +#else + return t; +#endif +} +``` + +Adding the cast means that the value-category of the return expression is now an lvalue and so it can bind to the return type. + +### P2280R4: References to unknown values during constant evaluation + +[P2280R4](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2280r4.html) allows references to unknown values during constant evaluation, relaxing restrictions on `constexpr` evaluation. + +```cpp +template +constexpr size_t array_size(T (&)[N]) +{ + return N; +} + +void check(int const (¶m)[3]) +{ + constexpr auto s2 = array_size(param); // Previously ill-formed, now accepted as a constant expression after P2280R4. +} +``` + +This improvement allows more code to be evaluated at compile time, particularly when dealing with function parameters in template contexts. + +## Conformance enhancements + +Improved adherence to C++ standards includes better handling of attributes, templates, and C++20/C++23 features. + +### Attribute support + +- Added support for [`[[maybe_unused]]` on labels](https://developercommunity.visualstudio.com/t/unreferenced-label-when-ref-hidden-by-if/102076). +- Fixed warning C4102 (unreferenced label) when the only reference was from a discarded `if constexpr` branch. + +### Template and specialization fixes + +- [Diagnosed ill-formed friend explicit specializations](https://developercommunity.visualstudio.com/t/Defining-explicit-function-template-spec/10933841) that were incorrectly accepted in C++20 or later. +- Added `/Zc:enumEncoding` switch to [correctly encode enum nontype template parameters](https://developercommunity.visualstudio.com/t/Overload-resolution-fails-for-enum-non-t/10398088). +- Fixed issues with [missing 'template' keyword diagnostics](https://developercommunity.visualstudio.com/t/No-diagnostic-for-missing-template-in-d/10501221) + +### C++20 and C++23 Features + +- Enhanced [multidimensional `operator[]` support](https://developercommunity.visualstudio.com/t/Multidimensional-operator-with-Wall-r/10876026) +- Improved [concept and constraint evaluation](https://developercommunity.visualstudio.com/t/VS-1714-if-constexpr-requires--does/10905731) + +### Smaller conformance updates + +MSVC Build Tools v14.50 includes numerous smaller conformance improvements that enhance C++ standard compliance: + +- [CWG2635](https://cplusplus.github.io/CWG/issues/2635): Constrained structured bindings support +- [CWG2465](https://cplusplus.github.io/CWG/issues/2465): Coroutine parameters passed to promise constructor improvements +- [CWG2496](https://cplusplus.github.io/CWG/issues/2496): Ref-qualifiers and virtual overriding corrections +- [CWG2506](https://cplusplus.github.io/CWG/issues/2506): Structured bindings and array cv-qualifiers fixes +- [CWG2507](https://cplusplus.github.io/CWG/issues/2507): Default arguments for `operator[]` support +- [CWG2585](https://cplusplus.github.io/CWG/issues/2585): Behavior alignment with standard requirements +- [CWG2521](https://cplusplus.github.io/CWG/issues/2521): Deprecation of 'operator string-literal identifier' +- [CWG2528](https://cplusplus.github.io/CWG/issues/2528): Relaxed conversion rules for the spaceship operator +- [P2360R0](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p2360r0.html): Extended init-statement definition to allow alias-declarations +- [P2290R3](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2290r3.pdf): C++23 hexadecimal/octal delimited escape sequence support in string literals +- [P2797R0](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2797r0.html): Resolution for CWG2692 regarding static and explicit object member functions with the same parameter-type-lists +- [P2266R3](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2022/p2266r3.html): Simpler implicit move semantics + +## Bug fixes + +Bug fixes for C++ Modules, `constexpr`, and other fixes were made in MSVC Build Tools v14.50. + +For a detailed list of bug fixes, see [Compiler Improvements in v14.50](https://devblogs.microsoft.com/cppblog/c-language-updates-in-msvc-build-tools-v14-50/#compiler-improvements-in-v14.50). + +**Encoding of certain nontype template arguments corrected** + +Affects `/std:c++20` or later. + +Certain nontype pointer type template arguments involving subobjects could lead to linking issues or in some cases silent bad code generation where what should be distinct specializations collide. + +```cpp +struct A +{ + int x; +}; + +struct B +{ + int y; +}; + +template void f(); + +int main() +{ + static A a; + static B b; + constexpr auto px = &a.x; + constexpr auto py = &b.y; + f(); // incorrect encoding of argument 'px' + f(); // incorrect encoding of argument 'py', collided with 'px'. +} +``` + +With this fix, the two calls to `f` get distinct encodings, as required. + +## Migrating to MSVC Build Tools v14.50 + +When upgrading to MSVC Build Tools v14.50, consider the following potential breaking changes and migration guidance: + +### C++23 feature adoption +- Update code to take advantage of new `auto(x)` decay-copy syntax for cleaner template code +- Consider using `#warning` directives for deprecation notices instead of error-prone conditional compilation +- Review explicit object parameter usage in operators for improved consistency + +### `constexpr` improvements +- Existing `constexpr` code may now compile that previously failed, particularly with virtual functions +- Review constant evaluation code for potential new optimization opportunities +- Update CRTP patterns that may now work correctly with static constexpr members + +### Modules migration +- Projects using C++20 modules should see improved stability and compatibility +- Header units now work more reliably with large codebases like Unreal Engine 5 +- Consider migrating from traditional headers to modules for better compilation performance + +### Compiler diagnostics +- New warnings may appear for previously undiagnosed issues +- Review enum type usage if using `/Zc:enumTypes` +- Update code that relies on implicit conversions that may now be flagged + +### C code updates +- C23 features are available with `/std:clatest` +- `typeof` behavior changes may affect existing code +- Review preprocessor usage for new `__VA_OPT__` availability + +## Provide feedback + +For the latest updates and to provide feedback, visit the [Visual Studio Developer Community](https://developercommunity.visualstudio.com/) or contact the team at [visualcpp@microsoft.com](mailto:visualcpp@microsoft.com). Follow us on X [@visualc](https://x.com/visualc) or BlueSky [@msftcpp.bsky.social](https://bsky.app/profile/msftcpp.bsky.social). + +If you encounter problems with MSVC in Visual Studio 2026, please let us know via the [Report a Problem](how-to-report-a-problem-with-the-visual-cpp-toolset.md) option, either from the installer or the Visual Studio IDE itself. + +## See also + +[Microsoft C/C++ language conformance](visual-cpp-language-conformance.md)\ +[What's new for C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md)\ +[C++ conformance improvements in Visual Studio 2022](cpp-conformance-improvements.md) \ No newline at end of file diff --git a/docs/overview/overview-of-cpp-development.md b/docs/overview/overview-of-cpp-development.md index a151bf22deb..ac46ec8f83c 100644 --- a/docs/overview/overview-of-cpp-development.md +++ b/docs/overview/overview-of-cpp-development.md @@ -1,10 +1,10 @@ --- 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" +description: "The Visual Studio IDE supports C++ development on Windows and Linux 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 @@ -44,13 +44,13 @@ Source control enables you to coordinate work among multiple developers, isolate ::: moniker range=">=msvc-160" -![Screenshot of the Team Explorer window in Visual Studio 2019.](media/vs2019-team-explorer.png ) +![Screenshot of the Team Explorer window in Visual Studio 2019.](media/vs2019-team-explorer.png) ::: moniker-end ::: moniker range="<=msvc-150" -![Screenshot of the Team Explorer window in Visual Studio 2017.](media/vs2017-team-explorer.png ) +![Screenshot of the Team Explorer window in Visual Studio 2017.](media/vs2017-team-explorer.png) ::: moniker-end @@ -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 @@ -110,7 +110,7 @@ For more information, see [Verifying Code by Using Unit Tests](/visualstudio/tes ## Analyze -Visual Studio includes static code analysis tools that can detect potential problems in your source code. These tools include an implementation of the [C++ Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md) rules checkers. For more information, see [Code analysis for C/C++ overview](../code-quality/code-analysis-for-c-cpp-overview.md). +Visual Studio includes static code analysis tools that can detect potential problems in your source code. These tools include an implementation of the [C++ Core Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) rules checkers. For more information, see [Code analysis for C/C++ overview](../code-quality/code-analysis-for-c-cpp-overview.md). ## Deploy completed applications diff --git a/docs/overview/supported-platforms-visual-cpp.md b/docs/overview/supported-platforms-visual-cpp.md index 422178f56d4..afcfd94885f 100644 --- a/docs/overview/supported-platforms-visual-cpp.md +++ b/docs/overview/supported-platforms-visual-cpp.md @@ -1,46 +1,56 @@ --- -description: "Learn more about: Supported Platforms (Visual C++)" -title: "Supported Platforms (Visual C++)" -ms.date: 11/09/2021 -ms.technology: "cpp-tools" +description: "Learn more about: Supported Platforms (Microsoft C++)" +title: "Supported Platforms (Microsoft C++)" +ms.date: 10/22/2025 +ms.service: "visual-cpp" +ms.subservice: "tools" helpviewer_keywords: ["Visual C++, platforms supported", "platforms [C++]"] --- -# Supported platforms (Visual C++) +# Supported platforms (Microsoft C++) Apps built by using Visual Studio can be targeted to various platforms. +Support for targeting 32-bit ARM was permanently removed in VS 2026 18.0. + ## Visual Studio target OS and architecture support -| Operating System | x86 | x64 | ARM | ARM64a | -|--|--|--|--|--| -| Windows XP b | X | X | | | -| Windows Vista | X | X | | | -| Windows 7 | X | X | | | -| Windows 8 | X | X | X | | -| Windows 8.1 | X | X | X | | -| Windows 10 | X | X | X | X | -| Windows 11 | X | X | X | X | -| Windows Server 2003 b | X | X | | | -| Windows Server 2008 R2 | X | X | | | -| Windows Server 2012 R2 | X | X | | | -| Windows Server 2016 | X | X | | | -| Windows Server 2019 | X | X | | | -| Windows Server 2022 | X | X | | | -| Android c | X | X | X | X | -| iOS c | X | X | X | X | -| Linux d | X | X | X | X | +| Operating System | x86 | x64 | ARM64a | +|--|--|--|--| +| Windows XP b | X | X | | +| Windows Vistac | X | X | | +| Windows 7d | X | X | | +| Windows 8d | X | X | | +| Windows 8.1d | X | X | | +| Windows 10 | X | X | X | +| Windows 11 | X | X | X | +| Windows Server 2003 b | X | X | | +| Windows Server 2008d | X | X | | +| Windows Server 2008 R2d | X | X | | +| Windows Server 2012d | X | X | | +| Windows Server 2012 R2d | X | X | | +| Windows Server 2016 | X | X | | +| Windows Server 2019 | X | X | | +| Windows Server 2022 | X | X | | +| Windows Server 2025 | X | X | | +| Android e | X | X | X | +| iOS e | | | X | +| Linux f | X | X | X | a ARM64 support is available in Visual Studio 2017 and later. -b You can use the Windows XP platform toolsets included in Visual Studio 2017, Visual Studio 2015, Visual Studio 2013, and Visual Studio 2012 Update 1 to build Windows XP and Windows Server 2003 projects. For information on how to use these platform toolsets, see [Configuring Programs for Windows XP](../build/configuring-programs-for-windows-xp.md). For more information on changing the platform toolset, see [How to: Modify the Target Framework and Platform Toolset](../build/how-to-modify-the-target-framework-and-platform-toolset.md). +b Visual Studio no longer supports targeting Windows XP. Use the Windows XP platform toolsets included in Visual Studio 2017, Visual Studio 2015, Visual Studio 2013, and Visual Studio 2012 Update 1 to build Windows XP and Windows Server 2003 projects. + +c Visual Studio 2022 17.0 and later no longer support targeting Windows Vista or Windows Server 2008. + +d Visual Studio 2026 18.0 and later no longer support targeting Windows 7/8/8.1 or Windows Server 2008 R2/2012/2012 R2. Visual Studio 2026 and later target Windows 10 or later and Windows Server 2016 or later. -c You can install the **Mobile development with C++** workload in the installer for Visual Studio 2017 and later. In Visual Studio 2015 setup, choose the optional **Visual C++ for Cross Platform Mobile Development** component to target iOS or Android platforms. For instructions, see [Install Visual C++ for Cross-Platform Mobile Development](/visualstudio/cross-platform/install-visual-cpp-for-cross-platform-mobile-development). To build iOS code, you must have a Mac computer and meet other requirements. For a list of prerequisites and installation instructions, see [Install And Configure Tools to Build using iOS](/visualstudio/cross-platform/install-and-configure-tools-to-build-using-ios). You can build x86 or ARM code to match the target hardware. Use x86 configurations to build for some Android devices. Use ARM configurations to build for iOS devices and most Android devices. +e You can install the **Mobile development with C++** workload in the installer for Visual Studio 2017 and later. In Visual Studio 2015 setup, choose the optional **Visual C++ for Cross Platform Mobile Development** component to target iOS or Android platforms. For instructions, see [Install Visual C++ for Cross-Platform Mobile Development](/visualstudio/cross-platform/install-visual-cpp-for-cross-platform-mobile-development). To build iOS code, you must have a Mac computer and meet other requirements. For a list of prerequisites and installation instructions, see [Install And Configure Tools to Build using iOS](/visualstudio/cross-platform/install-and-configure-tools-to-build-using-ios). You can build x86 or ARM code to match the target hardware. Use x86 configurations to build for some Android devices. Use ARM configurations to build for iOS devices and most Android devices. **IMPORTANT**: Starting with Visual Studio 2026 (version 18.0), the **Mobile development with C++** workload for iOS and Android targeting in the Visual Studio installer and the **Embedded and IoT tools**--including RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import--are no longer supported and will be removed in a future update. However, the Android NDKs listed in the Mobile development with C++ workload continue to be supported. -d You can install the **Linux development with C++** workload in the installer for Visual Studio 2017 and later to target Linux platforms. For instructions, see [Download, install, and setup the Linux Workload](../linux/download-install-and-setup-the-linux-development-workload.md). This toolset compiles your executable on the target machine, so you can build for any supported architecture. +f You can install the **Linux development with C++** workload in the installer for Visual Studio 2017 and later to target Linux platforms. For instructions, see [Download, install, and setup the Linux Workload](../linux/download-install-and-setup-the-linux-development-workload.md). This toolset compiles your executable on the target machine, so you can build for any supported architecture. -For information about how to set the target platform configuration, see [How to: Configure Visual C++ projects to target 64-bit, x64 platforms](../build/how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md). +For information about how to set the target platform configuration, see [How to: Configure Microsoft C++ projects to target 64-bit, x64 platforms](../build/how-to-configure-visual-cpp-projects-to-target-64-bit-platforms.md). ## See also -[Visual C++ tools and features in Visual Studio editions](visual-cpp-tools-and-features-in-visual-studio-editions.md)\ +[Microsoft C++ tools and features in Visual Studio editions](visual-cpp-tools-and-features-in-visual-studio-editions.md)\ [Getting Started](/visualstudio/ide/getting-started-with-cpp-in-visual-studio) diff --git a/docs/overview/toc.yml b/docs/overview/toc.yml index 6835b304bd4..39072bdc2eb 100644 --- a/docs/overview/toc.yml +++ b/docs/overview/toc.yml @@ -2,18 +2,20 @@ 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 + - name: What's new for MSVC Build Tools + href: ../overview/what-s-new-for-msvc.md - name: What's new for C++ in Visual Studio 2022 href: ../overview/what-s-new-for-visual-cpp-in-visual-studio.md - name: What's new for C++ in Visual Studio 2019 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/C++ conformance improvements in Microsoft C++ (MSVC) Build Tools + href: ../overview/msvc-conformance-improvements.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 +26,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 @@ -32,7 +36,7 @@ items: href: ../overview/visual-cpp-samples.md - name: Help and community href: ../overview/visual-cpp-help-and-community.md - - name: How to report a problem with the Visual C++ toolset + - name: How to report a problem with the Microsoft C++ Build Tools href: ../overview/how-to-report-a-problem-with-the-visual-cpp-toolset.md - name: Visual Studio C++ Tutorials expanded: false diff --git a/docs/overview/visual-cpp-help-and-community.md b/docs/overview/visual-cpp-help-and-community.md index 284b13123b0..3cd59d14be4 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 @@ -24,7 +25,7 @@ You can view Microsoft developer content online. This content is updated regular You can also download and view the content locally in the offline Help Viewer. The offline documentation is organized by books of related content, which are also updated periodically. You can download the books you're interested in as they become available. For more information, see [Microsoft Help Viewer](/visualstudio/ide/microsoft-help-viewer). -Many sections of the documentation are also available in PDF form. These sections have a **Download PDF** link below the table of contents on docs.microsoft.com. +Many sections of the documentation are also available in PDF form. These sections have a **Download PDF** link below the table of contents on Microsoft Learn. ## Related sites @@ -34,6 +35,6 @@ Many sections of the documentation are also available in PDF form. These section - [Visual Studio website](https://visualstudio.microsoft.com/): Contains articles and news about Visual Studio and related development tools. This site also hosts Visual Studio downloads and Redistributable files. -- [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html): Official Microsoft forums where you can post questions about C++ and Visual Studio and get answers from Microsoft and from experts in the community. +- [Microsoft Learn Q&A](/answers/topics/c%2B%2B.html): Official Microsoft forums where you can post questions about C++ and Visual Studio and get answers from Microsoft and from experts in the community. - [Visual Studio C++ Developer Community](https://aka.ms/vsfeedback/browsecpp): Forums for reporting problems in the C++ compiler and tools or the IDE, or for making product suggestions. You can vote for your favorite ideas or bug reports, or add a new one. This site is monitored by the development team. diff --git a/docs/overview/visual-cpp-in-visual-studio.md b/docs/overview/visual-cpp-in-visual-studio.md index 12a0c14023e..111b4036a69 100644 --- a/docs/overview/visual-cpp-in-visual-studio.md +++ b/docs/overview/visual-cpp-in-visual-studio.md @@ -1,8 +1,9 @@ --- title: "C and C++ in Visual Studio" description: "Learn how to use the Microsoft C/C++ compiler and related tools to develop C++ and assembly programs for Windows, Linux, Android, and iOS." -ms.date: 04/20/2022 -ms.technology: "cpp-ide" +ms.date: 09/29/2022 +ms.service: "visual-cpp" +ms.subservice: "ide" helpviewer_keywords: ["Visual C++, home page"] --- # C and C++ in Visual Studio @@ -43,14 +44,20 @@ helpviewer_keywords: ["Visual C++, home page"] :::moniker-end -Microsoft Visual C++ (MSVC) refers to the C++, C, and assembly language development tools and libraries available as part of Visual Studio on Windows. These tools and libraries let you create Universal Windows Platform (UWP) apps, native Windows desktop and server applications, cross-platform libraries and apps that run on Windows, Linux, Android, and iOS, as well as managed apps and libraries that use the .NET Framework. You can use MSVC to write anything from simple console apps to the most sophisticated and complex apps for Windows desktop, from device drivers and operating system components to cross-platform games for mobile devices, and from the smallest IoT devices to multi-server high performance computing in the Azure cloud. +Microsoft C++ (MSVC) refers to the C++, C, and assembly language development tools and libraries available as part of Visual Studio on Windows. These tools and libraries let you create native Windows desktop and server applications, Universal Windows Platform (UWP) apps, or managed apps and libraries that use the .NET Framework. Create cross-platform libraries and apps that run on Windows, Linux, Android, and iOS. You can use MSVC to write anything from simple console apps to the most sophisticated and complex apps for Windows desktop. Write device drivers and operating system components or cross-platform games for mobile devices. Target anything from the smallest IoT devices to multi-server high performance computing in the Azure cloud. -Visual Studio 2015, 2017, 2019, and 2022 can be installed side-by-side. You can use Visual Studio 2019 (compiler toolset v142) or Visual Studio 2017 (v141) to edit and build programs using the toolset from Visual Studio 2017 (v141) and Visual Studio 2015 (v140). +You can install Visual Studio 2015 and later side-by-side. For example, you can use Visual Studio 2019 (compiler toolset v142) or Visual Studio 2017 (v141) to edit and build programs using the toolset from Visual Studio 2017 (v141) and Visual Studio 2015 (v140). ## What's new for C++ in Visual Studio -[What's New for C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md)\ -Find out what's new in Visual Studio. +[What's New for C++ in Visual Studio 2022](what-s-new-for-visual-cpp-in-visual-studio.md)\ +Find out what's new in Visual Studio 2022. + +[What's New for C++ in Visual Studio 2019](./what-s-new-for-cpp-2019.md)\ +Find out what's new in Visual Studio 2019. + +[What's New for C++ in Visual Studio 2017](./what-s-new-for-cpp-2017.md)\ +Find out what's new in Visual Studio 2017. [What's New for C++ in Visual Studio 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md)\ Find out what was new in C++ for each version of Visual Studio from 2003 through 2015. @@ -67,10 +74,10 @@ Learn about the breaking changes in previous versions. ## Install Visual Studio C++ and upgrade from earlier versions [Install C++ support in Visual Studio](../build/vscpp-step-0-installation.md)\ -Download Visual Studio and install the Microsoft C/C++ toolset. +Download Visual Studio and install the Microsoft C++ Build Tools. [Microsoft C++ porting and upgrading guide](../porting/visual-cpp-porting-and-upgrading-guide.md)\ -Guidance for porting code and upgrading projects to Visual Studio 2015 or later to take advantage of greater compiler conformance to the C++ standard as well as greatly improved compilation times and security features such as Spectre mitigation. +Guidance for porting code and upgrading projects to Visual Studio 2015 or later. Take advantage of greater compiler conformance to the C++ standard, greatly improved compilation times, and security features such as Spectre mitigation. [C++ tools and features in Visual Studio editions](visual-cpp-tools-and-features-in-visual-studio-editions.md)\ Find out about different Visual Studio editions. @@ -114,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)\ @@ -127,7 +134,7 @@ Find guides and reference content on the Windows Developer Center. For informati Use the Visual Studio IDE to code and deploy to a remote Linux machine for compilation with GCC. [Create C/C++ DLLs in Visual Studio](../build/dlls-in-visual-cpp.md)\ -Find out how to use Win32, ATL, and MFC to create Windows desktop DLLs, and provides information about how to compile and register your DLL. +Find out how to use Win32, ATL, and MFC to create Windows desktop DLLs. Provides information about how to compile and register your DLL. [Parallel programming](../parallel/parallel-programming-in-visual-cpp.md)\ Learn how to use the Parallel Patterns Library, C++ AMP, OpenMP, and other features that are related to multithreading on Windows. @@ -155,7 +162,7 @@ The reference guide to the Microsoft implementation of the C programming languag [C/C++ preprocessor reference](../preprocessor/c-cpp-preprocessor-reference.md)\ A common reference to the shared C and C++ language preprocessor. -[C++/CX language reference](/cpp/cppcx/visual-c-language-reference-c-cx)\ +[C++/CX language reference](../cppcx/visual-c-language-reference-c-cx.md)\ The reference guide to the Microsoft extensions to the C++ language for creating C++ Universal Windows Platform apps, C++ Windows runtime components that can be consumed by JavaScript-based Windows apps, and Windows DirectX games and graphics-intensive apps. [C++/CLI language reference](https://www.ecma-international.org/wp-content/uploads/ECMA-372_1st_edition_december_2005.pdf)\ @@ -194,12 +201,12 @@ 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 -[Microsoft Docs Q&A](/answers/topics/c%2B%2B.html)\ -Microsoft Docs hosts searchable forums for questions and answers. Add a `C++` tag to your post for community assistance on C++-related issues. +[Microsoft Learn Q&A](/answers/topics/c%2B%2B.html)\ +Microsoft Learn hosts searchable forums for questions and answers. Add a `C++` tag to your post for community assistance on C++-related issues. [How to report a problem with the Microsoft C/C++ toolset](how-to-report-a-problem-with-the-visual-cpp-toolset.md)\ Learn how to create effective error reports against the Microsoft C/C++ toolset (compiler, linker, and other tools), and ways to submit your report. diff --git a/docs/overview/visual-cpp-language-conformance.md b/docs/overview/visual-cpp-language-conformance.md index ee6ecf2d34c..698a03e2b9f 100644 --- a/docs/overview/visual-cpp-language-conformance.md +++ b/docs/overview/visual-cpp-language-conformance.md @@ -1,14 +1,15 @@ --- title: "Microsoft C/C++ language conformance" description: "Microsoft C and C++ conformance updates by Visual Studio version." -ms.date: 11/08/2021 -ms.technology: "cpp-language" +ms.date: 03/10/2026 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- # Microsoft C/C++ language conformance by Visual Studio version Standards conformance for the Microsoft C/C++ compiler in Visual Studio (MSVC) is a work in progress. Here's a summary of ISO Standard C and C++ language and library conformance by Visual Studio version. Each C++ compiler and standard library feature name has a link to the ISO Standard C++ proposal paper that describes the feature, when one is available at publication time. The **Supported** column lists the Visual Studio version in which support for the feature first appeared. -For details on conformance improvements, see [C++ conformance improvements in Visual Studio](cpp-conformance-improvements.md). For a list of other changes, see [What's New for Visual C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md). For conformance changes in earlier versions, see [Visual C++ change history](../porting/visual-cpp-change-history-2003-2015.md) and [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). For current news from the C++ team, visit the [C++ team blog](https://devblogs.microsoft.com/cppblog/). +For details on conformance improvements, see [C++ conformance improvements in Visual Studio](cpp-conformance-improvements.md). For a list of other changes, see [What's New for Microsoft C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md). For conformance changes in earlier versions, see [Visual C++ change history](../porting/visual-cpp-change-history-2003-2015.md) and [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). For current news from the C++ team, visit the [C++ team blog](https://devblogs.microsoft.com/cppblog/). > [!NOTE] > There are no binary breaking changes between Visual Studio 2015, 2017, 2019, and 2022. For more information, see [C++ binary compatibility between Visual Studio versions](../porting/binary-compat-2015-2017.md) @@ -20,6 +21,7 @@ For details on conformance improvements, see [C++ conformance improvements in Vi | **C++03/11 Core language features** | **Supported** | |  Everything else | VS 2015 [A](#note_A) | |  Two-phase name lookup | VS 2017 15.7 [B](#note_B) | +|  [`CWG 1213 Value category of arrays and subscripts`](https://cplusplus.github.io/CWG/issues/1213.html) | VS 2022 17.14 | |  [`N2634 Expression SFINAE`](https://wg21.link/N2634) | VS 2017 15.7 | |  [`N1653 C99 preprocessor`](https://wg21.link/N1653) | VS 2019 16.6 [C](#note_C) | | **C++03/11 Core language features (Defect reports)** | **Supported** | @@ -86,7 +88,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 +117,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) | @@ -173,13 +175,61 @@ For details on conformance improvements, see [C++ conformance improvements in Vi |  [`P1073R3 Immediate functions`](https://wg21.link/P1073R3) | VS 2019 16.10 [20](#note_20) | |  [`P1143R2 constinit`](https://wg21.link/P1143R2) | VS 2019 16.10 [20](#note_20) | |  [`P1353R0 Missing feature-test macros`](https://wg21.link/P1353R0) | VS 2019 16.10 [20](#note_20) | -|  [`P0735R1 Interaction of memory_order_consume with release sequences`](https://wg21.link/P0735R1) | N/A | -|  [`P1236R1 Signed integers are two's complement`](https://wg21.link/P1236R1) | N/A | +|  [`P0735R1 Interaction of memory_order_consume with release sequences`](https://wg21.link/P0735R1) | VS 2022 v17.14 | +|  [`P1236R1 Signed integers are two's complement`](https://wg21.link/P1236R1) | VS 2022 v17.14 | +| **C++23 Core language features** | **Supported** | +|  [`P0330R8 Literal Suffix for (signed) size_t`](https://wg21.link/p0330r8) | VS 2022 17.13 [23](#note_23) | +|  [`P0847R7 Deducing this`](https://wg21.link/p0847r7) | VS 2022 17.13 [23](#note_23) | +|  [`P0849R8 auto(x): decay-copy in the language`](https://wg21.link/p0849r8) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P1102R2 Down with ()!`](https://wg21.link/p1102r2) | VS 2022 17.14 [23](#note_23) | +|  [`P1169R4 static operator()`](https://wg21.link/p1169r4) | VS 2022 17.14 [23](#note_23) | +|  [`P1401R5 Narrowing contextual conversions to bool`](https://wg21.link/p1401r5) | VS 2022 17.14 [23](#note_23) | +|  [`P1467R9 Extended floating-point types and standard names`](https://wg21.link/p1467r9) | No [U](#note_U) | +|  [`P1774R8 Portable assumptions`](https://wg21.link/p1774r8) | no | +|  [`P1787R6 Declarations and where to find them`](https://wg21.link/p1787r6) | No change required | +|  [`P1847R4 Make declaration order layout mandated`](https://wg21.link/p1847r4) | VS 2022 17.0 [23](#note_23) | +|  [`P1938R3 if consteval`](https://wg21.link/p1938r3) | VS 2022 17.14 [23](#note_23) | +|  [`P1949R7 C++ Identifier Syntax using Unicode Standard Annex 31`](https://wg21.link/p1949r7) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2029R4 Proposed resolution for core issues 411, 1656, and 2333; numeric and universal character escapes in character and string literals`](https://wg21.link/p2029r4) | no | +|  [`P2036R3 Change scope of lambda trailing-return-type`](https://wg21.link/p2036r3) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2071R2 Named universal character escapes`](https://wg21.link/p2071r2) | no | +|  [`P2128R6 Multidimensional subscript operator`](https://wg21.link/p2128r6) | VS 2022 17.12 [23](#note_23) | +|  [`P2156R1 Allow Duplicate Attributes`](https://wg21.link/p2156r1) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2173R1 Attributes on Lambda-Expressions`](https://wg21.link/p2173r1) | VS 2022 17.14 [23](#note_23) | +|  [`P2186R2 Remove Garbage Collection Support`](https://wg21.link/p2186r2) | VS 2022 17.0 [23](#note_23) | +|  [`P2201R1 Mixed string literal concatenation`](https://wg21.link/p2201r1) | VS 2022 17.14 | +|  [`P2223R2 Trimming whitespaces before line splicing`](https://wg21.link/p2223r2) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2242R3 Non-literal variables (and labels and gotos) in constexpr functions`](https://wg21.link/p2242r3) | VS 2022 17.14 [23](#note_23) | +|  [`P2246R1 Character encoding of diagnostic text`](https://wg21.link/p2246r1) | VS 2022 17.0 [23](#note_23) | +|  [`P2266R3 Simpler implicit move`](https://wg21.link/p2266r3) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2280R4 Using unknown pointers and references in constant expressions`](https://wg21.link/p2280r4) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2290R3 Delimited escape sequences`](https://wg21.link/p2290r3) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2295R6 Support for UTF-8 as a portable source file encoding`](https://wg21.link/p2295r6) | [V](#note_V) | +|  [`P2314R4 Character sets and encodings`](https://wg21.link/p2314r4) | no | +|  [`P2316R2 Consistent character literal encoding`](https://wg21.link/p2316r2) | VS 2022 17.0 [23](#note_23) | +|  [`P2324R2 Labels at the end of compound statements (C compatibility)`](https://wg21.link/p2324r2) | no | +|  [`P2327R1 De-deprecating volatile compound operations`](https://wg21.link/p2327r1) | VS 2022 v17.14 | +|  [`P2334R1 preprocessing directives elifdef and elifndef`](https://wg21.link/p2334r1) | VS 2022 17.10 [23](#note_23) | +|  [`P2360R0 Extend init-statement to allow alias-declaration`](https://wg21.link/p2360r0) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2362R3 Remove non-encodable wide character literals and multicharacter wide character literals`](https://wg21.link/p2362r3) | no | +|  [`P2437R1 Support for #warning`](https://wg21.link/p2437r1) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2448R2 Relaxing some constexpr restrictions`](https://wg21.link/p2448r2) | no | +|  [`P2460R2 Relax requirements on wchar_t to match existing practices`](https://wg21.link/p2460r2) | VS 2022 v17.14 | +|  [`P2468R2 The Equality Operator You Are Looking For`](https://wg21.link/p2468r2) | VS 2022 17.6 [23](#note_23) | +|  [`P2493R0 Missing feature test macros for C++20 core papers`](https://wg21.link/p2493r0) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`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) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2582R1 Wording for class template argument deduction from inherited constructors`](https://wg21.link/p2582r1) | no | +|  [`P2589R1 static operator[]`](https://wg21.link/p2589r1) | VS 2022 17.14 [23](#note_23) | ## C++ Standard library features A more detailed listing of Standard Library features and bug fixes by product version is available on the [GitHub Microsoft STL wiki Changelog](https://github.com/microsoft/STL/wiki/Changelog) page. +For the latest information about ongoing conformance work, see: +- [STL C++23 Features](https://github.com/orgs/microsoft/projects/1142/views/2). +- [STL C++26 Features](https://github.com/orgs/microsoft/projects/1143/views/2). + | Feature | Supported | |--|--| | **C++14 Standard library features** | **Supported** | @@ -290,7 +340,7 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`P0607R0 Inline Variables for the Standard Library`](https://wg21.link/p0607r0) | VS 2017 15.5 [17](#note_17) | |  [`P0618R0 Deprecating `](https://wg21.link/p0618r0) | VS 2017 15.5 [17](#note_17) | | **C++17 Standard library features (Defect reports)** | **Supported** | -|  [`P0682R1 Repairing Elementary String Conversions`](https://wg21.link/P0682R1) | VS 2015 15.7 [17](#note_17) | +|  [`P0682R1 Repairing Elementary String Conversions`](https://wg21.link/P0682R1) | VS 2017 15.7 [17](#note_17) | |  [`P1164R1 Making create_directory() Intuitive`](https://wg21.link/P1164R1) | VS 2019 16.0 [14](#note_14) | | **C++20 Standard library features** | **Supported** | |  [`P0809R0 Comparing Unordered Containers`](https://wg21.link/p0809r0) | VS 2010 [14](#note_14) | @@ -356,7 +406,7 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`P1023R0 constexpr For std::array Comparisons`](https://wg21.link/P1023R0) | VS 2019 16.7 [20](#note_20) | |  [`P1115R3 erase()/erase_if() Return size_type`](https://wg21.link/P1115R3) | VS 2019 16.7 [20](#note_20) | |  [`P1831R1 Deprecating volatile in the standard library`](https://wg21.link/P1831R1) | VS 2019 16.7 [20](#note_20) | -|  [`P1871R1 Concept traits should be named after concepts`](https://wg21.link/P1831R1) | VS 2019 16.7 [20](#note_20) | +|  [`P1871R1 Concept traits should be named after concepts`](https://wg21.link/P1871R1) | VS 2019 16.7 [20](#note_20) | |  [`P1956R1 has_single_bit(), bit_ceil(), bit_floor(), bit_width()`](https://wg21.link/P1956R1) | VS 2019 16.7 [20](#note_20) | |  [`P1964R2 Replacing boolean With boolean-testable`](https://wg21.link/P1964R2) | VS 2019 16.7 [20](#note_20) | |  [`P1976R2 Fixed-size span construction from dynamic range`](https://wg21.link/P1976R2) | VS 2019 16.7 [20](#note_20) | @@ -394,25 +444,73 @@ A more detailed listing of Standard Library features and bug fixes by product ve |  [`P1208R6 `](https://wg21.link/P1208R6) | VS 2019 16.10 [20](#note_20) | |  [`P1502R1 Standard Library Header Units`](https://wg21.link/P1502R1) | VS 2019 16.10 [20](#note_20) | |  [`P1614R2 Adding Spaceship <=> To The Library`](https://wg21.link/P1614R2) | VS 2019 16.10 [20](#note_20) | -|  [`P1285R0 Improving Completeness Requirements For Type Traits`](https://wg21.link/P1285R0) | N/A | +|  [`P1285R0 Improving Completeness Requirements For Type Traits`](https://wg21.link/P1285R0) | VS 2022 v17.14 | | **C++20 Standard library features (Defect reports)** | **Supported** | |  [`P2325R3 Views Should Not Be Required To Be Default Constructible`](https://wg21.link/P2325r3) | VS 2022 17.0 [20abi](#note_20abi) | |  [`P2328R1 join_view should join all views of ranges`](https://wg21.link/P2328R1) | VS 2022 17.0 [20abi](#note_20abi) | |  [`P2367R0 Remove misuses of list-initialization from clause 24 ranges`](https://wg21.link/P2367R0) | VS 2022 17.0 [20abi](#note_20abi) | |  [`P2259R1 Partial LWG issue resolution: repairing Input Range Adaptors and counted_iterator`](https://wg21.link/P2259R1) | VS 2022 17.0 [23](#note_23) | | **C++23 Standard library features** | **Supported** | -|  [`P0401R6 Providing size feedback in the allocator interface`](https://wg21.link/P0401R6) | VS 2022 17.0 [23](#note_23) | -|  [`P0881R7 `](https://wg21.link/p0881r7) | No | -|  [`P0943R6 Supporting C Atomics In C++`](https://wg21.link/P0943R6) | VS 2022 17.0 [T](#note_T) | -|  [`P1048R1 is_scoped_enum`](https://wg21.link/P1048R1) | VS 2022 17.0 [23](#note_23) | -|  [`P1132R7 out_ptr(), inout_ptr()`](https://wg21.link/P1132R7) | VS 2022 17.0 [23](#note_23) | -|  [`P1679R3 contains() for basic_string/basic_string_view`](https://wg21.link/P1679R3) | VS 2022 17.0 [23](#note_23) | -|  [`P1682R3 to_underlying() for enumerations`](https://wg21.link/P1682R3) | VS 2022 17.0 [23](#note_23) | -|  [`P1951R1 Default template arguments for pair's forwarding constructor`](https://wg21.link/P1951R1) | VS 2022 17.0 [23](#note_23) | -|  [`P1989R2 Range Constructor For string_view`](https://wg21.link/P1989R2) | VS 2022 17.0 [23](#note_23) | +|  [`P0288R9 move_only_function`](https://wg21.link/p0288r9) | VS 2022 17.2 [23](#note_23) | +|  [`P0323R12 `](https://wg21.link/p0323r12) | VS 2022 17.3 [23](#note_23) | +|  [`P0401R6 Providing Size Feedback In The Allocator Interface`](https://wg21.link/p0401r6) | VS 2022 17.0 [23](#note_23) | +|  [`P0448R4 `](https://wg21.link/p0448r4) | VS 2022 17.1 [23](#note_23) | +|  [`P0627R6 unreachable()`](https://wg21.link/p0627r6) | VS 2022 17.2 [23](#note_23) | +|  [`P0798R8 Monadic Operations For optional`](https://wg21.link/p0798r8) | VS 2022 17.2 [23](#note_23) | +|  [`P0849R8 auto(x): decay-copy In The Language`](https://wg21.link/p0849r8) | VS 2022 17.4 [23](#note_23) | +|  [`P0881R7 `](https://wg21.link/p0881r7) | VS 2022 17.4 [23](#note_23) | +|  [`P0943R6 Supporting C Atomics In C++`](https://wg21.link/p0943r6) | VS 2022 17.1 [23](#note_23) | +|  [`P1048R1 is_scoped_enum`](https://wg21.link/p1048r1) | VS 2022 17.0 [23](#note_23) | +|  [`P1072R10 basic_string::resize_and_overwrite`](https://wg21.link/p1072r10) | VS 2022 17.1 [23](#note_23) | +|  [`P1132R7 out_ptr(), inout_ptr()`](https://wg21.link/p1132r7) | VS 2022 17.0 [23](#note_23) | +|  [`P1147R1 Printing volatile Pointers`](https://wg21.link/p1147r1) | VS 2022 17.1 [23](#note_23) | +|  [`P1206R7 Conversions From Ranges To Containers`](https://wg21.link/p1206r7) | VS 2022 17.4 [23](#note_23) | +|  [`P1272R4 byteswap()`](https://wg21.link/p1272r4) | VS 2022 17.1 [23](#note_23) | +|  [`P1328R1 constexpr type_info::operator==()`](https://wg21.link/p1328r1) | VS 2022 17.4 [23](#note_23) | +|  [`P1413R3 Deprecate aligned_storage And aligned_union`](https://wg21.link/p1413r3) | VS 2022 17.3 [23](#note_23) | +|  [`P1425R4 Iterator Pair Constructors For stack And queue`](https://wg21.link/p1425r4) | VS 2022 17.1 [23](#note_23) | +|  [`P1518R2 Stop Overconstraining Allocators In Container Deduction Guides`](https://wg21.link/p1518r2) | VS 2022 17.1 [23](#note_23) | +|  [`P1659R3 ranges::starts_with, ranges::ends_with`](https://wg21.link/p1659r3) | VS 2022 17.1 [23](#note_23) | +|  [`P1679R3 contains() For basic_string/basic_string_view`](https://wg21.link/p1679r3) | VS 2022 17.0 [23](#note_23) | +|  [`P1682R3 to_underlying() For Enumerations`](https://wg21.link/p1682r3) | VS 2022 17.0 [23](#note_23) | +|  [`P1899R3 views::stride`](https://wg21.link/p1899r3) | VS 2022 17.4 [23](#note_23) | +|  [`P1951R1 Default Template Arguments For pair's Forwarding Constructor`](https://wg21.link/p1951r1) | VS 2022 17.0 [23](#note_23) | +|  [`P1989R2 Range Constructor For string_view`](https://wg21.link/p1989r2) | VS 2022 17.0 [23](#note_23) | +|  [`P2077R3 Heterogeneous Erasure Overloads For Associative Containers`](https://wg21.link/p2077r3) | VS 2022 17.2 [23](#note_23) | +|  [`P2136R3 invoke_r()`](https://wg21.link/p2136r3) | VS 2022 17.1 [23](#note_23) | |  [`P2162R2 Inheriting from std::variant`](https://wg21.link/P2162R2) | VS 2022 17.0 [17](#note_17) | |  [`P2166R1 Prohibit basic_string and basic_string_view from being constructed from nullptr`](https://wg21.link/P2166R1) | VS 2022 17.0 [23](#note_23), [R](#note_R) | |  [`P2186R2 Removed garbage collection support`](https://wg21.link/P2186R2) | VS 2022 17.0 [23](#note_23), [Q](#note_Q) | +|  [`P2251R1 Require span And basic_string_view To Be Trivially Copyable`](https://wg21.link/p2251r1) | VS 2022 17.1 [23](#note_23) | +|  [`P2273R3 constexpr unique_ptr`](https://wg21.link/p2273r3) | VS 2022 17.3 [23](#note_23) | +|  [`P2280R4 Using unknown pointers and references in constant expressions`](https://wg21.link/p2280r4) | MSVC Build Tools version 14.5 [24](#note_24) | +|  [`P2290R3 Delimited escape sequences`](https://wg21.link/p2290r3) | MSVC Build Tools version 14.5 [24](#note_24) | +|  [`P2291R3 constexpr Integral `](https://wg21.link/p2291r3) | VS 2022 17.4 [23](#note_23) | +|  [`P2302R4 ranges::contains, ranges::contains_subrange`](https://wg21.link/p2302r4) | VS 2022 17.4 [23](#note_23) | +|  [`P2321R2 std::zip`](https://wg21.link/p2321r2) | partial in VS 2022 17.5 [23](#note_23) | +|  [`P2322R6 ranges::fold_left, ranges::fold_right, etc.`](https://wg21.link/p2322r6) | VS 2022 17.5 [23](#note_23) | +|  [`P2360R0 Extend init-statement to allow alias-declaration`](https://wg21.link/p2360r0) | MSVC Build Tools version 14.5 [24](#note_24) | +|  [`P2387R3 Pipe Support For User-Defined Range Adaptors`](https://wg21.link/p2387r3) | VS 2022 17.4 [23](#note_23) | +|  [`P2393R1 Cleaning Up Integer-Class Types`](https://wg21.link/p2393r1) | VS 2022 17.2 [23](#note_23) | +|  [`P2401R0 Conditional noexcept For exchange()`](https://wg21.link/p2401r0) | VS 2022 17.1 [23](#note_23) | +|  [`P2408R5 Ranges Iterators As Inputs To Non-Ranges Algorithms`](https://wg21.link/p2408r5) | VS 2022 17.4 [23](#note_23) | +|  [`P2417R2 More constexpr bitset`](https://wg21.link/p2417r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2419R2 Clarify Handling Of Encodings In Localized Formatting Of chrono Types`](https://wg21.link/p2419r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2437R1 Support for #warning`](https://wg21.link/p2437r1) | MSVC Build Tools version 14.50 [24](#note_24) | +|  [`P2438R2 string::substr() &&`](https://wg21.link/p2438r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2440R1 ranges::iota, ranges::shift_left, ranges::shift_right`](https://wg21.link/p2440r1) | VS 2022 17.4 [23](#note_23) | +|  [`P2441R2 views::join_with`](https://wg21.link/p2441r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2442R1 Windowing Range Adaptors: views::chunk, views::slide`](https://wg21.link/p2442r1) | VS 2022 17.3 [23](#note_23) | +|  [`P2443R1 views::chunk_by`](https://wg21.link/p2443r1) | VS 2022 17.3 [23](#note_23) | +|  [`P2445R1 forward_like()`](https://wg21.link/p2445r1) | VS 2022 17.4 [23](#note_23) | +|  [`P2446R2 views::as_rvalue`](https://wg21.link/p2446r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2465R3 Standard Library Modules std And std.compat`](https://wg21.link/p2465r3) | no | +|  [`P2494R2 Relaxing Range Adaptors To Allow Move-Only Types`](https://wg21.link/p2494r2) | VS 2022 17.4 [23](#note_23) | +|  [`P2499R0 string_view Range Constructor Should Be explicit`](https://wg21.link/p2499r0) | VS 2022 17.4 [23](#note_23) | +|  [`P2508R1 basic_format_string, format_string, wformat_string`](https://wg21.link/p2508r1) | VS 2022 17.5 [23](#note_23) | +|  [`P2517R1 Conditional noexcept For apply()`](https://wg21.link/p2517r1) | VS 2022 17.4 [23](#note_23) | +|  [`P2520R0 move_iterator Should Be A Random-Access Iterator`](https://wg21.link/p2520r0) | VS 2022 17.4 [23](#note_23) | +|  [`P2549R1 unexpected::error()`](https://wg21.link/p2549r1) | VS 2022 17.3 [23](#note_23) | A group of papers listed together indicates a Standard feature along with one or more approved improvements or expansions. These features are implemented together. @@ -441,17 +539,18 @@ 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) | |  Bounds-checking interfaces (`*_s` APIs) | Partial in VS 2015 [C11](#note_C11), [O](#note_O) | |  `fopen` `"x"` option | VS 2019 16.8 [C11](#note_C11) | -|  Static assertions | VS 2019 16.8 [C11](#note_C11), [2104](#note_2104) | +|  Static assertions | VS 2019 16.8 [C11](#note_C11), [2104](#note_2104) | |  `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 @@ -476,13 +575,19 @@ A group of papers listed together indicates a Standard feature along with one or **VS 2019 16.8** Supported in Visual Studio 2019 version 16.8.\ **VS 2019 16.9** Supported in Visual Studio 2019 version 16.9.\ **VS 2019 16.10** Supported in Visual Studio 2019 version 16.10.\ -**VS 2022 17.0** Supported in Visual Studio 2022 version 17.0. +**VS 2022 17.0** Supported in Visual Studio 2022 version 17.0.\ +**VS 2022 17.1** Supported in Visual Studio 2022 version 17.1.\ +**VS 2022 17.2** Supported in Visual Studio 2022 version 17.2.\ +**VS 2022 17.3** Supported in Visual Studio 2022 version 17.3.\ +**VS 2022 17.4** Supported in Visual Studio 2022 version 17.4.\ +**VS 2022 17.5** Supported in Visual Studio 2022 version 17.5.\ +**MSVC Build Tools version 14.50** Supported in Visual Studio 2026 18.0 (MSVC compiler version 19.50) and up. ### 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. + **A** In [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) mode, the compiler leaves dynamic exception specifications unimplemented, and treats `throw()` as a synonym for `__declspec(nothrow)`. In C++17, P0003R5 removed most dynamic exception specifications, except for one vestige: the standard deprecated `throw()` and requires it 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/). @@ -494,7 +599,7 @@ The compiler option [`/Zc:noexceptTypes`](../build/reference/zc-noexcepttypes.md **F** Features removed when the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later compiler option is specified. To re-enable these features (to ease the transition to newer language modes), use these macros: `_HAS_AUTO_PTR_ETC`, `_HAS_FUNCTION_ALLOCATOR_SUPPORT`, `_HAS_OLD_IOSTREAMS_MEMBERS`, and `_HAS_UNEXPECTED`. - **G** C++17's parallel algorithms library is complete. Complete doesn't mean that every algorithm is parallelized in every case. The most important algorithms have been parallelized. Execution policy signatures are provided even where the implementation doesn't parallelize algorithms. The central internal header, ``, contains the following "Parallel Algorithms Notes": C++ allows an implementation to implement parallel algorithms as calls to the serial algorithms. This implementation parallelizes several common algorithm calls, but not all. + **G** C++17's parallel algorithms library is complete. Complete doesn't mean that every algorithm is parallelized in every case. The most important algorithms are parallelized. Execution policy signatures are provided even where the implementation doesn't parallelize algorithms. The central internal header, ``, contains the following "Parallel Algorithms Notes": C++ allows an implementation to implement parallel algorithms as calls to the serial algorithms. This implementation parallelizes several common algorithm calls, but not all. The following algorithms are parallelized: @@ -508,7 +613,7 @@ These algorithms aren't presently parallelized: - `generate`, `generate_n` - Effective parallelism of these algorithms might be infeasible: - `partial_sort`, `partial_sort_copy` -- These algorithms haven't been evaluated yet. The library might implement parallelism in a future release: +- These algorithms aren't evaluated yet. The library might implement parallelism in a future release: - `copy_if`, `includes`, `inplace_merge`, `lexicographical_compare`, `max_element`, `merge`, `min_element`, `minmax_element`, `nth_element`, `partition_copy`, `remove_copy`, `remove_copy_if`, `replace_copy`, `replace_copy_if`, `set_symmetric_difference`, `set_union`, `stable_partition`, `unique`, `unique_copy` **H** This is a wholly new implementation, incompatible with the previous `std::experimental` version, made necessary by symlink support, bug fixes, and changes in standard-required behavior. Currently, `` provides both the new `std::filesystem` and the previous `std::experimental::filesystem`. The `` header provides only the old experimental implementation. Expect removal of the experimental implementation in the next ABI-breaking release of the libraries. @@ -519,7 +624,7 @@ These algorithms aren't presently parallelized: **K** MSVC doesn't support the `_Complex` keyword or native complex types. The Universal CRT `` uses implementation-specific macros to achieve the same effect. For more information, see [C complex math support](../c-runtime-library/complex-math-support.md). - **L** The Universal CRT doesn't implement the `strftime` `E` and `O` alternative conversion modifiers. These modifiers are ignored (for example, `%Oe` behaves the same as `%e`). The modifiers aren't supported by the underlying locale APIs. + **L** The Universal CRT doesn't implement the `strftime` `E` and `O` alternative conversion modifiers. These modifiers are ignored (for example, `%Oe` behaves the same as `%e`). The underlying locale APIs don’t support the modifiers. **M** The Universal CRT doesn't implement C11 `aligned_alloc`, but does provide [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md) and [`_aligned_free`](../c-runtime-library/reference/aligned-free.md). Because the Windows operating system doesn't support aligned allocations, this function is unlikely to be implemented. @@ -537,6 +642,10 @@ These algorithms aren't presently parallelized: **T** `` is currently supported when compiled as C++ (`/std:c++latest`). It isn't yet supported when compiled as C (`/std:c11` and `/std:c17`) + **U** Extended floating-point types are an optional C++23 feature. This feature won't be implemented until C++23 standardization is finalized. + + **V** Use the compiler options `/source-charset:utf-8` and `/we4828` to treat source files as UTF-8 encoded. + **14** These C++17 and C++20 features are always enabled, even when [`/std:c++14`](../build/reference/std-specify-language-standard-version.md) (the default) is specified. The reason is either because the feature was implemented before the introduction of the **`/std`** options, or because conditional implementation was undesirably complex. **17** These features are enabled by the [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later compiler option. @@ -547,6 +656,8 @@ These algorithms aren't presently parallelized: **23** In Visual Studio 2022 version 17.0 and up, these features are enabled by the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. + **24** In MSVC Build Tools version 14.50 and up (first shipped with Visual Studio 2026 version 18.0), these features are enabled by the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. + **C11** Compiler support for C11 and C17 requires Visual Studio 2019 version 16.8 or higher. Except as noted, C11 and C17 library support requires Windows SDK build 10.0.20211.0 or higher. For more information on how to install support for C11 and C17, see [Install C11 and C17 support in Visual Studio](./install-c17-support.md). **DR** These features are enabled in all C++ [`/std`](../build/reference/std-specify-language-standard-version.md) compiler option modes. The C++ Standard committee adopted this change as a retroactive Defect Report to C++11 and all later versions. @@ -558,7 +669,7 @@ These algorithms aren't presently parallelized: [C++ Language Reference](../cpp/cpp-language-reference.md)\ [C++ Standard Library](../standard-library/cpp-standard-library-reference.md)\ [C++ conformance improvements in Visual Studio](cpp-conformance-improvements.md)\ -[What's New for Visual C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md)\ +[What's New for Microsoft C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md)\ [Visual C++ change history 2003 through 2015](../porting/visual-cpp-change-history-2003-2015.md)\ [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md)\ [C++ team blog](https://devblogs.microsoft.com/cppblog/) diff --git a/docs/overview/visual-cpp-samples.md b/docs/overview/visual-cpp-samples.md index 433f20e8965..e3371885a18 100644 --- a/docs/overview/visual-cpp-samples.md +++ b/docs/overview/visual-cpp-samples.md @@ -1,15 +1,15 @@ --- title: "Visual Studio C++ Samples" -description: "Summary descriptions of the samples available in the archived Visual Studio C++ samples repository on GitHub." -ms.date: "03/23/2020" -ms.technology: "cpp-language" -ms.assetid: 76798022-5886-48e7-a7f2-f99352b15cbf +description: "Learn about the samples available in the archived Visual Studio C++ samples repository on GitHub." +ms.date: 03/25/2025 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" --- -# Visual Studio C++ Samples +# Visual Studio C++ samples Samples for Visual Studio C++ are available on the web. Microsoft has produced many C++ samples that demonstrate different functionalities across multiple technologies. Here are a few of the places to find additional samples: -- [Microsoft Docs samples - C++](/samples/browse/?term=c%2B%2B) +- [C++ code samples](/samples/browse/?term=c%2B%2B) - [Windows samples on GitHub](https://microsoft.github.io/windows/) @@ -21,7 +21,24 @@ Samples for Visual Studio C++ are available on the web. Microsoft has produced m ## Archived C++ samples on GitHub -Visual Studio included C++ sample code in previous versions. The sample code was either installed with Visual Studio, or was available as a separate download. Many articles in our documentation refer to these samples. They don't get installed by Visual Studio anymore. Instead, a repository is available on GitHub. The tables below have descriptions for each sample, and links to the sample's directory in the repository. +Previous versions of Visual Studio included C++ sample code. The sample code was either installed with Visual Studio, or was available as a separate download. Many articles in our documentation refer to these samples. They don't get installed by Visual Studio anymore. Instead, a repository is available on GitHub. The following tables have descriptions for each sample, and links to the sample's directory in the repository. + +- [ATL samples](#atl-samples) +- [CLR and language samples](#clr-and-language-samples---windows-forms) +- [COM events samples](#com-events-samples) +- [ComTypeLibfor7 samples](#comtypelibfor7-samples) +- [Compiler samples](#compiler-samples) +- [CRT samples](#crt-samples) +- [Debugging samples](#debugging-samples) +- [Fusion samples](#fusion-samples) +- [Hilo sample](#hilo-sample) +- [International samples](#international-samples) +- [Language samples](#language-samples---general) +- [MFC samples](#mfc-samples) +- [ODBC samples](#odbc-samples) +- [OS samples](#os-samples) +- [Unix samples](#unix-samples) +- [Windows 8 samples](#windows-8-samples) [!INCLUDE[note_security_samplecode](includes/note_security_samplecode_md.md)] @@ -34,10 +51,10 @@ Visual Studio included C++ sample code in previous versions. The sample code was | [ActiveDoc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates how to implement an Active Document Server. | | [Async](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Downloads data asynchronously from a URL. | | [ATLButton](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Creates a button that displays itself with three different bitmaps depending on its state. | -| [ATLDuck](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates using connection points with ATL controls. | +| [ATLDuck](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates how to use connection points with ATL controls. | | [ATLSecurity](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Shows how to use the ATL security classes to examine security settings. | | [ATLTraceTool](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Displays the output generated by the `ATLTRACE2` macro. | -| [Connect](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Illustrates the implementation and use of connection points (the IConnectionPointContainer and IConnectionPoint interfaces) in a multithreaded environment. | +| [Connect](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Illustrates the implementation and use of connection points (the `IConnectionPointContainer` and `IConnectionPoint` interfaces) in a multithreaded environment. | | [CThreadPool](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Shows how to use a thread pool in an application and how implementing a thread pool can improve the application's performance. | | [DCOM](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Demonstrates how to call a COM object (implemented in a Windows service) from multiple clients, running on different machines. | | [MFCATL](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/Advanced) | Illustrates how ATL COM objects can be used in an MFC server EXE. | @@ -72,7 +89,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was |--|--| | [CatDB](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Displays the schema information, such as tables and columns, of OLE DB providers. | | [DBViewer](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Demonstrates a mid-level application that relies on the `CManualAccessor` class to take full control of data bindings for your applications. | -| [DynamicConsumer](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Demonstrates using dynamic accessor and schema rowset classes to read metadata from a database. | +| [DynamicConsumer](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Demonstrates how to use dynamic accessor and schema rowset classes to read metadata from a database. | | [MultiRead](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ATL/OLEDB/Consumer) | Reads through a table in a database using multiple threads. | ### ATL samples - OLEDB - Provider @@ -88,7 +105,6 @@ Visual Studio included C++ sample code in previous versions. The sample code was |--|--| | [BirthdayPicker](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Language/Windows%20Forms) | Shows how the .NET Framework resource mechanism can be used in C++ applications. It also demonstrates some common Window Forms components. | | [Calculator](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Language/Windows%20Forms) | Implements a simple pocket calculator using C++ and the .NET Framework Windows Forms classes. | -| Scribble (using MFC) | An MFC implementation of the Scribble sample, updated and extended to include new .NET functionality. | | [Scribble (Windows Forms)](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Language/General) | A Windows Forms implementation of the Scribble sample, updated and extended to include new .NET functionality. | | [STLCLR](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/CLR/stlclr/StlClr%20Sample) | Demonstrates some of the capabilities available when using the STL/CLR Library. | @@ -109,9 +125,9 @@ Visual Studio included C++ sample code in previous versions. The sample code was | [Connect](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Illustrates the use and implementation of connection points (the `IConnectionPointContainer` and `IConnectionPoint` interfaces) in a multithreaded environment. | | [DCOM](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates how to call a COM object (implemented in a Windows service) from multiple clients, running on different computers. | | [FreeThrd](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates a multithreaded client and free-threaded server with compiler COM support. | -| [InProc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an in-process Automation server application with compiler COM support. | +| [InProc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an in-process automation server application with compiler COM support. | | [Labrador](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Implements an EXE server that doesn't have any user interface. | -| [MFCCalc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an Automation server application with compiler COM support. | +| [MFCCalc](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/ComTypeLibfor7) | Demonstrates an automation server application with compiler COM support. | ## Compiler samples @@ -119,7 +135,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was | Sample name | Description | |--|--| -| [ccWrapper](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Compiler) | Demonstrates how to map C/C++ compiler flags from other compilers to the Visual C++ compiler (cl.exe). | +| [ccWrapper](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/Compiler) | Demonstrates how to map C/C++ compiler flags from other compilers to the Visual C++ compiler (`cl.exe`). | ### Compiler samples - MASM @@ -137,10 +153,10 @@ Visual Studio included C++ sample code in previous versions. The sample code was |--|--| | [CPUID](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Determines the capabilities of the CPU being run. | | [CRT_Dbg1](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Illustrates the basic debugging features of the C run-time libraries. | -| [CRT_Dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the C run-time debugging hook functions. | +| [CRT_Dbg2](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the C runtime debugging hook functions. | | [DFACObjs](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Shows how to use the _CrtDoForAllClientObjects C run-time function to iterate through a linked list of client objects. | -| [Report](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Illustrates the C run-time debugging report functions. | -| [RTC](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the run-time error checks feature. | +| [Report](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Illustrates the C runtime debugging report functions. | +| [RTC](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | Demonstrates the runtime error checks feature. | | [SecureCRT](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/crt) | This sample demonstrates how to upgrade code that used deprecated CRT functions to increase code security. | ## Debugging samples @@ -159,7 +175,7 @@ Visual Studio included C++ sample code in previous versions. The sample code was | Sample name | Description | |--|--| -| [Hilo](https://github.com/Microsoft/VCSamples/tree/master/VC2013Samples/Hilo) | Hilo is a series of articles and sample applications. They demonstrate the power of Windows 7, Visual Studio and C++ to build high performance, responsive client applications. Hilo provides both source code and guidance that will help you design and develop compelling, touch-enabled Windows applications of your own.

This sample has been updated for Visual Studio 2013. It includes a hot fix to the *AsyncLoaderMemoryManager.cpp* file (in lines 36 and 37), which addresses a common crash issue. | +| [Hilo](https://github.com/Microsoft/VCSamples/tree/master/VC2013Samples/Hilo) | Hilo is a series of articles and sample applications. They demonstrate the power of Windows 7, Visual Studio and C++ to build high performance, responsive client applications. Hilo provides both source code and guidance that help you design and develop compelling, touch-enabled Windows applications of your own. | ## International samples @@ -201,13 +217,13 @@ Visual Studio included C++ sample code in previous versions. The sample code was | Sample name | Description | |--|--| | [Button](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates use of an in-place active menu, a stock property page, and the About box control option. | -| [Circ](https://github.com/Microsoft/VCSamples/tree/master/VC2010Samples/MFC/controls) | Demonstrates ActiveX control basics. These include control painting, stock and custom properties, stock and custom events, use of colors and fonts, the stock Font property page, the default property page, and versioning. | -| [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`). | +| [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 Windows Vista: 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/visual-cpp-tools-and-features-in-visual-studio-editions.md b/docs/overview/visual-cpp-tools-and-features-in-visual-studio-editions.md index 8f68bdd1c4a..05aadb31dd0 100644 --- a/docs/overview/visual-cpp-tools-and-features-in-visual-studio-editions.md +++ b/docs/overview/visual-cpp-tools-and-features-in-visual-studio-editions.md @@ -3,7 +3,6 @@ description: "Learn more about: C++ Tools and Features in Visual Studio Editions title: "C++ Tools and Features in Visual Studio Editions" ms.date: 10/27/2021 helpviewer_keywords: ["tools and platforms [C++]"] -ms.assetid: 3d88607b-9cc4-490a-8d4c-31ee7610a26f --- # C++ Tools and Features in Visual Studio Editions @@ -15,7 +14,7 @@ The following C++ features are available in Visual Studio. Unless stated otherwi ::: moniker range="<=msvc-150" -The following tables show Visual C++ features that are available in Visual Studio 2017. An X in a cell indicates that the feature is available; an empty cell indicates that the feature is not available. Notes in parentheses indicate that a feature is available, but restricted. +The following tables show C++ features that are available in Visual Studio 2017. An X in a cell indicates that the feature is available; an empty cell indicates that the feature is not available. Notes in parentheses indicate that a feature is available, but restricted. ::: moniker-end @@ -29,6 +28,9 @@ The following tables show Visual C++ features that are available in Visual Studi - Android - iOS +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + ::: moniker-end ::: moniker range="<=msvc-150" @@ -257,6 +259,9 @@ Optional Components: ### Mobile development with C++ +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + Included: - C++ core features diff --git a/docs/overview/what-s-new-for-cpp-2017.md b/docs/overview/what-s-new-for-cpp-2017.md index 0e0670a9b01..d30dc9febd5 100644 --- a/docs/overview/what-s-new-for-cpp-2017.md +++ b/docs/overview/what-s-new-for-cpp-2017.md @@ -2,14 +2,15 @@ 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 Visual Studio 2017 brings many updates and fixes to the C++ environment. We've fixed over 250 bugs and reported issues in the compiler and tools. Many were submitted by customers through the [Report a Problem and Provide a Suggestion](/visualstudio/ide/how-to-report-a-problem-with-visual-studio?view=vs-2017&preserve-view=true) options under **Send Feedback**. Thank you for reporting bugs! -For more information on what's new in all of Visual Studio, see [What's new in Visual Studio 2017](/visualstudio/ide/whats-new-visual-studio-2017?view=vs-2017&preserve-view=true). 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-visual-cpp-in-visual-studio.md?preserve-view=true&view=msvc-160). For information on what's new for C++ in Visual Studio 2015 and earlier versions, see [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). For information about what's new in the C++ docs, see [Microsoft C++ docs: What's new](whats-new-cpp-docs.md). +For more information on what's new in all of Visual Studio, see [What's new in Visual Studio 2017](/visualstudio/ide/whats-new-visual-studio-2017?view=vs-2017&preserve-view=true). 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-visual-cpp-in-visual-studio.md?preserve-view=true&view=msvc-160). For information on what's new for C++ in Visual Studio 2015 and earlier versions, see [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). ## Visual Studio 2017 C++ compiler @@ -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 18df33e3145..341347e69cd 100644 --- a/docs/overview/what-s-new-for-cpp-2019.md +++ b/docs/overview/what-s-new-for-cpp-2019.md @@ -2,14 +2,15 @@ title: "What's new for C++ in Visual Studio 2019" description: "The new features and fixes in the Microsoft C/C++ compiler and tools in Visual Studio 2019." ms.date: 10/22/2021 -ms.technology: "cpp-ide" +ms.service: "visual-cpp" +ms.subservice: "ide" ms.custom: intro-whats-new --- # What's new for C++ in Visual Studio 2019 Visual Studio 2019 brings many updates and fixes to the Microsoft C++ environment. We've fixed many bugs and issues in the compiler and tools. Many of these issues were submitted by customers through the [Report a Problem](/visualstudio/ide/how-to-report-a-problem-with-visual-studio?view=vs-2019&preserve-view=true) and [Provide a Suggestion](https://aka.ms/feedback/suggest?space=62) options under **Send Feedback**. Thank you for reporting bugs! -For more information on what's new in all of Visual Studio, visit [What's new in Visual Studio 2019](/visualstudio/ide/whats-new-visual-studio-2019). For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017](what-s-new-for-cpp-2017.md). For information on what's new for C++ in Visual Studio 2015 and earlier versions, see [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). For information about what's new in the C++ docs, see [Microsoft C++ docs: What's new](whats-new-cpp-docs.md). +For more information on what's new in all of Visual Studio, visit [What's new in Visual Studio 2019](/visualstudio/ide/whats-new-visual-studio-2019). For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017](what-s-new-for-cpp-2017.md). For information on what's new for C++ in Visual Studio 2015 and earlier versions, see [Visual C++ What's New 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). ## What's new for C++ in Visual Studio version 16.11 @@ -25,7 +26,7 @@ For a summary of new features and bug fixes in Visual Studio version 16.11, see For a summary of new features and bug fixes in Visual Studio version 16.10, see [What's New in Visual Studio 2019 version 16.10](/visualstudio/releases/2019/release-notes-v16.10). -- All C++20 features are now available under [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md). While MSVC’s implementation of the C++20 standards (as currently published by ISO) is feature complete, some key C++20 library features are expected to be amended by upcoming Defect Reports (ISO C++20 bug fixes) that may change them in an ABI-incompatible way. Please see [Microsoft/STL Issue #1814](https://github.com/microsoft/STL/issues/1814) for more details. +- All C++20 features are now available under [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md). While MSVC's implementation of the C++20 standards (as currently published by ISO) is feature complete, some key C++20 library features are expected to be amended by upcoming Defect Reports (ISO C++20 bug fixes) that may change them in an ABI-incompatible way. Please see [Microsoft/STL Issue #1814](https://github.com/microsoft/STL/issues/1814) for more details. - C++20 immediate functions & constinit support added in 16.10 - The final pieces of ``: new clocks, leap seconds, time zones, and parsing @@ -133,7 +134,7 @@ For a summary of new features and bug fixes in Visual Studio version 16.8, see [ - Support for ARM64 projects using clang-cl. -- [Intel AMX intrinsics](https://software.intel.com/content/www/us/en/develop/documentation/cpp-compiler-developer-guide-and-reference/top/compiler-reference/intrinsics/intrinsics-for-intel-advanced-matrix-extensions-intel-amx-instructions.html) support. +- [Intel AMX intrinsics](https://www.intel.com/content/www/us/en/developer/articles/code-sample/advanced-matrix-extensions-intrinsics-functions.html) support. ## What's new for C++ in Visual Studio version 16.7 @@ -309,7 +310,7 @@ The new IntelliCode features (Custom Models, C++ support, and EditorConfig infer #### Quick Info improvements -- The Quick Info tooltip now respects the semantic colorization of your editor. It also has a new **Search Online** link that will search for online docs to learn more about the hovered code construct. The link provided by Quick Info for red-squiggled code will search for the error online. That way you don't need to retype the message into your browser. For more information, see [Quick Info Improvements in Visual Studio 2019: Colorization and Search Online](https://devblogs.microsoft.com/cppblog/quick-info-improvements-in-visual-studio-2019-colorization-and-search-online/). +- The Quick Info tooltip now respects the semantic colorization of your editor. It also has a new **Search Online** link that will search online documentation for information about the hovered code construct. The link provided by Quick Info for red-squiggled code will search for the error online. That way you don't need to retype the message into your browser. For more information, see [Quick Info Improvements in Visual Studio 2019: Colorization and Search Online](https://devblogs.microsoft.com/cppblog/quick-info-improvements-in-visual-studio-2019-colorization-and-search-online/). #### General improvements @@ -504,7 +505,7 @@ IncrediBuild is included as an optional component in the **Desktop development w - MFC class from ActiveX control - MFC class from Type Lib. - Sample code for these technologies is archived at Microsoft Docs and the VCSamples GitHub repository. + Sample code for these technologies is archived in Microsoft Learn and the VCSamples GitHub repository. - The Windows 8.1 Software Development Kit (SDK) is no longer available in the Visual Studio installer. We recommend you upgrade your C++ projects to the latest Windows SDK. If you have a hard dependency on 8.1, you can download it from the Windows SDK archive. diff --git a/docs/overview/what-s-new-for-msvc.md b/docs/overview/what-s-new-for-msvc.md new file mode 100644 index 00000000000..31aabe88305 --- /dev/null +++ b/docs/overview/what-s-new-for-msvc.md @@ -0,0 +1,173 @@ +--- +title: "What's new for MSVC Build Tools" +description: "The new features and fixes in the Microsoft C/C++ compiler and tools (MSVC)." +ms.date: 05/15/2026 +ms.service: "visual-cpp" +ms.subservice: "cpp-lang" +ms.custom: intro-whats-new +--- + +# What's new for MSVC Build Tools + +Version 14.51 brings many updates and fixes to the Microsoft C++ compiler and other build tools. + +- For more information about what's new in all of Visual Studio, see [Visual Studio 2026 release notes](/visualstudio/releases/2026/release-notes). + +## What's new for MSVC Build Tools version 14.51 + +* Introduced in Visual Studio 2026 version 18.6 released May 2026. + +Visual Studio 2026 version 18.6 ships with the v145 platform toolset for MSBuild C++ projects and Microsoft C++ (MSVC) Build Tools version 14.51. To access all the new language features, build with `/std:c++latest`. Or, if you want to be restricted to features up to C++23, use `/std:c++23preview`. + +MSVC Build Tools version 14.51 preserves binary compatibility with code built with MSVC tools shipped in Visual Studio 2015 or later. For more information about binary compatibility, see [C++ binary compatibility between Visual Studio versions](/cpp/porting/binary-compat-2015-2017). + +| For detailed information about | See | +|---|---| +| What's new for C++ developers | [MSVC Build Tools version 14.51 Release Candidate Now Available](https://devblogs.microsoft.com/cppblog/msvc-build-tools-version-14-51-release-candidate-now-available/) | +| Standard Library (STL) improvements | [STL Changelog MSVC Build Tools 14.51](https://github.com/microsoft/STL/wiki/Changelog#msvc-build-tools-1451) | +| C++ language conformance improvements | [C/C++ Conformance improvements, behavior changes, and bug fixes in Microsoft C++ (MSVC) Build Tools](msvc-conformance-improvements.md) | + +Here's a quick highlight of some of the new features in MSVC Build Tools version 14.51: + +### C++ language enhancements + +- More C++23 and C++20 features and conformance issue fixes. For full C++23 details, see [C++23 Support in MSVC Build Tools 14.51](https://devblogs.microsoft.com/cppblog/c23-support-in-msvc-build-tools-14-51). +- Multiple fixes to `consteval` function handling, including support for constexpr `new`/`delete` in modules. The `/experimental:constevalVfuncVtable` behavior is now enabled by default. +- Added support for C language features: `_Atomic` qualifier and `__typeof__` for function types. +- Fixed incorrect diagnostics for C99 flexible array members. +- MSVC now generates IFC files according to [version 0.44](https://github.com/microsoft/ifc-spec/releases/tag/0.44) of the [IFC specification](https://github.com/microsoft/ifc-spec). +- Improved parser error recovery. + +## C language enhancements + +Added `_Atomic` qualifier support and added `__typeof__` support for function types. +Fixed [C4319](/cpp/error-messages/compiler-warnings/compiler-warning-level-1-c4319) not being emitted when compiling C code. + +### Standard Library enhancements + +- Added new C++23 headers: `` ([P0429R9](https://wg21.link/P0429R9)) and `` ([P1222R4](https://wg21.link/P1222R4)). +- **Massive `` overhaul:** Fixed long-standing correctness and performance problems. The implementation includes significant performance improvements. +- **ARM64 NEON vectorization:** First release shipping NEON-vectorized STL algorithms for ARM64/ARM64EC. Previously, only x64/x86 received SIMD optimizations with SSE4.2 and AVX2. Vectorized implementations are now available for algorithms including `swap_ranges()`, `rotate()`, `reverse()`, `min_element()`, `max_element()`, `find()`, `count()`, and more. +- Implemented 18 Library Working Group (LWG) issue resolutions, including fixes for duration conversion overflow, `construct_at` array support, and `optional` const overloads. +- Optimized integer-to-string conversions by printing digits in pairs. The Standard Template Library is now optimized for speed instead of size. +- Added type traits to detect references binding to temporaries ([P2255R2](https://wg21.link/P2255R2)). +- Added explicit lifetime management support ([P2590R2](https://wg21.link/P2590R2)). +- Enhanced debugger visualizations, including a `c_str()` intrinsic function for `basic_string` that enables conditional breakpoints. + +### Build enhancements + +- **Arm SVE support:** First Arm Scalable Vector Extension (SVE) support in MSVC, including frontend type support, intrinsic lowering, callee-saved register unwinding, and DIA SDK support. +- **Sample-based PGO:** Preview support for sample-based profile guided optimizations. For more information, see [Use Sample Profile Guided Optimization (SPGO) to improve C++ performance](../build/sample-profile-guided-optimization.md). +- The C++ backend optimizer improves code generation, including better inlining, loop optimizations, and pattern matching. +- **Experimental support for x64 Unwind Version 3 MASM directives**. For more information, see [Unwind Version 3 directives (experimental)](../assembler/masm/directives-reference.md#x64-unwind-version-3-experimental) +- **Intel APX preview:** Preview support for Intel Advanced Performance Extensions. For more information, see [/feature (x64)](../build/reference/feature-x64.md), [`[[msvc::enable(feature:APX)]]`](../cpp/attributes.md#msvcenablefeatureapx), and [`[[msvc::disable(feature:APX)]]`](../cpp/attributes.md#msvcdisablefeatureapx). +- Enabled debug info pruning to reduce PDB sizes. + +### Deprecations + +- The following experimental coroutine headers are now deprecated: ``, ``, and ``. Transition to standard C++20 coroutines using the `` header. + +### Removed features + +The following long-deprecated non-Standard features have been removed: + +- **TR1** including the `std::tr1` namespace, old `array::assign()`, and old `` engines and distributions. Deprecated since VS 2017 15.5 (December 2017). +- **`_ALLOW_RTCc_IN_STL`** macro removed. The Standard Template Library doesn't support the `/RTCc` compiler option, but `/RTCs` and `/RTCu`/`/RTC1` remain supported. +- **`` and ``**. Deprecated since VS 2015 (July 2015). +- **``**. Deprecated since VS 2019 16.3 (September 2019). +- **`stdext::checked_array_iterator` and `stdext::unchecked_array_iterator`**. Deprecated since VS 2022 17.8 (November 2023) for C++17 and later. +- **`basic_istream::ipfx()`/`isfx()` and `basic_ostream::opfx()`/`osfx()`**. Deprecated since VS 2022 17.9 (February 2024) for C++17 and later. +- **`locale::empty()`**. Deprecated since VS 2022 17.14 (May 2025). + +## What's new for MSVC Build Tools version 14.50 + +* Introduced in Visual Studio 2026 version 18.0 released November 2025. + +Visual Studio 2026 version 18.0 ships with the v145 platform toolset for MSBuild C++ projects and Microsoft C++ (MSVC) Build Tools version 14.50, which offers the best conformance, build performance, and runtime performance story yet. To access all the new language features, build with `/std:c++latest`. Or, if you want to be restricted to features up to C++23, use `/std:c++23preview`. + +MSVC Build Tools version 14.50 preserves binary compatibility with code built with MSVC tools shipped in Visual Studio 2015 or later. For more information about binary compatibility, see [C++ binary compatibility between Visual Studio versions](/cpp/porting/binary-compat-2015-2017). + +| For detailed information about | See | +|---|---| +| What's new for C++ developers | [What’s New for C++ Developers in Visual Studio 2026 version 18.0](https://devblogs.microsoft.com/cppblog/whats-new-for-cpp-developers-in-visual-studio-2026-version-18-0) | +| C++ Standard Library (STL) improvements | [STL Changelog MSVC Build Tools 14.50](https://github.com/microsoft/STL/wiki/Changelog#msvc-build-tools-1450) | +| C++ language updates | [C++ Language Updates in MSVC Build Tools v14.50](https://devblogs.microsoft.com/cppblog/c-language-updates-in-msvc-build-tools-v14-50/) | +| C++ language conformance improvements | [C/C++ Conformance improvements, behavior changes, and bug fixes in Microsoft C++ (MSVC) Build Tools](msvc-conformance-improvements.md) | + +Here's a quick highlight of some of the new features in MSVC Build Tools version 14.50 and Visual Studio 2026 version 18.0: + +### C++ language enhancements + +- C++20 is the default for new Console App, Windows Desktop Application, Dynamic-Link Library, and Static Library C++ projects. +- C++23 preprocessing directive `#warning` allows you to generate a diagnostic message without stopping translation as `#error` does. For more information, see [`#warning` directive](/cpp/preprocessor/hash-warning-directive-c-cpp). +- Easily set debugger command-line arguments for any C++ project using the toolbar for `.vcxproj`, CMake, and Unreal Engine projects. This feature is no longer tied to the Game Development with C++ workload, and is available to all C++ developers without installing any other workloads or components. For more information, see [Pass command-line arguments](/visualstudio/debugger/getting-started-with-the-debugger-cpp?view=visualstudio&preserve-view=true). + +### Standard Library enhancements + +- Enhanced `` reliability and speed. [LWG-2503](https://cplusplus.github.io/LWG/issue2503) added a multiline option to `syntax_option_type`. This is a `regex` behavioral change. By default, `_REGEX_LEGACY_MULTILINE_MODE` is 0, which requests Standard behavior. Set `_REGEX_LEGACY_MULTILINE_MODE` to 1 to request legacy behavior. For more information, see [STL Changelog](https://github.com/microsoft/STL/wiki/Changelog#msvc-build-tools-1450). +- Added and improved vectorized implementations of many types and functions. + +### GitHub Copilot enhancements + +- Copilot Chat allows you to use natural language to get answers to questions (Ask mode) or even implement changes for you automatically (Agent Mode). +- Copilot Chat is smarter with improved context for everyday tasks. Expect better results when searching your codebase and referencing specific lines in your code. +- A **Copilot Actions** option was added to the right-click context menu in the Visual Studio editor. Use it to quickly bring a specific file or lines of code you select to the attention of Copilot Chat. You can then ask Copilot to explain what the code does, make optimizations, generate comments, generate unit tests, and more. +- Better AI code completions for C++. GitHub Copilot uses context from relevant files to improve inline autocomplete for C++. GitHub Copilot includes other relevant files as context, which reduces hallucinations while offering more relevant and accurate suggestions. +- For more information, see [New GitHub Copilot capabilities for C++ developers: Upgrade MSVC, improve build performance, and refactor C++ code](https://devblogs.microsoft.com/cppblog/new-github-copilot-capabilities-for-c-developers-upgrade-msvc-improve-build-performance-and-refactor-c-code/). + +### Build enhancements + +- Visual Studio 2026 now includes CMake 4.1.1 by default. CMake also includes a Visual Studio 2026 generator and supports modern SLNX projects, so you can build Visual Studio C++ projects directly from CMake. +- Includes the latest version of the IncrediBuild engine and an updated extension that works with Visual Studio 2026 version 18.0. +- Compiler backend runtime performance improvements. Compared to Visual Studio version 17.14, there's up to a 6% improvement on Unreal Engine's City Sample RenderThread and up to +3% improvements on Unreal Engine's City Sample GameThread benchmark. For more information, see [Why you should upgrade your C++ build tools](https://devblogs.microsoft.com/cppblog/upgrading-c-projects-to-visual-studio-2026/#why-you-should-upgrade-your-c++-build-tools). +- The Visual Studio setup assistant can help you retarget your projects to build with the latest MSVC Build Tools. For more information, see [Retarget your projects with the setup assistant](https://devblogs.microsoft.com/cppblog/upgrading-c-projects-to-visual-studio-2026/#retarget-your-projects-with-the-setup-assistant). + +### Code analysis enhancements + +- Clang-Tidy code analysis improvements provide enhanced configuration options for faster builds and custom workflows: + - Code analysis has new configuration options. You can now allocate more processors to run code analysis as part of your build, speeding up your development workflow. + - You can add custom arguments to the command line used to invoke `clang-tidy`, giving you complete control over your analysis setup. + - Access the new options from **Project Properties** > **Code Analysis** > **Clang-Tidy**: + +![Screenshot of Project Properties dialog showing clang-tidy configuration options including processor allocation and custom command line arguments](./media/clang-tidy-improvements.png) +- AddressSanitizer support for ARM64 Builds (Preview): For some time, the MSVC Build Tools supported building projects that target x64 and x86 with [AddressSanitizer](/cpp/sanitizers/asan), which allows you to identify hard-to-find memory safety issues with zero false positives at runtime and increase memory safety. Now you can use AddressSanitizer to target ARM64. This feature is in preview. + +### Productivity enhancements + +- Generate preprocessed output for a C++ file. In Visual Studio, right-click a C++ file to instantly generate its preprocessed output, making it easy to debug macros and includes, and see errors immediately: ![Screenshot showing the right-click context menu for a C++ file with the Preprocess option highlighted.](./media/cpp-preprocess-menu-entry.png) +- The Visual Studio debugger now shows the return values of functions inline. This provides real-time visibility into function behavior without stepping into code or setting up watches, making it faster to catch logic issues or unexpected results: ![Screenshot showing inline post-return values displayed in the debugger next to function call."](./media/inline-post-return-value.png) + +### Other changes + +- In the Visual Studio installer, the *C++ Linux* workload is renamed *Linux, Mac, and embedded development with C++*. + +### Deprecations + +- The minimum supported target operating systems for the MSVC Build Tools version 14.50 are Windows 10 or Windows Server 2016. +- MSVC Build Tools version 14.50 no longer targets: + + - Windows 7 / Windows Server 2008 R2 + - Windows 8 / Windows Server 2012 + - Windows 8.1 / Windows Server 2012 R2 + + These changes allow for better performance, enhanced security, and alignment with the most recent Windows platform capabilities. + +The MSVC compiler switch [`/await`](/cpp/build/reference/await-enable-coroutine-support) is deprecated and will be removed in a future release. This switch enabled an early draft implementation of C++ coroutines using the `` header. Developers should transition to standard C++ coroutines by using the `` header available in C++20 and later. For C++14/17 projects, use `/await:strict` (which isn't being deprecated) to access the standard `` header without enabling other C++20 features. + +The Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. This impacts tooling support for iOS and Android development, including new projects, building, and debugging. + +### Removed features + +- C++AMP +- ARM32 toolchain: if you still need to build for ARM32, use an older version of the MSVC Build Tools. For more information, see [Side-by-side Minor Version MSVC Toolsets in Visual Studio 2019](https://devblogs.microsoft.com/cppblog/side-by-side-minor-version-msvc-toolsets-in-visual-studio-2019/). +- `/DEBUG:FASTLINK` linker switch. Use [`/DEBUG:FULL`](/cpp/build/reference/debug-generate-debug-info) for improved debugging support. + +## Feedback and suggestions + +We'd love to hear from you! You can [Report a Problem or Suggest a Feature](/visualstudio/ide/how-to-report-a-problem-with-visual-studio) by using the Send Feedback icon in the upper right-hand corner of either the installer or the Visual Studio IDE, or from **Help** > **Send Feedback**. You can track your issues by using [Visual Studio Developer Community](https://developercommunity.visualstudio.com/), where you add comments or find solutions. You can also get free installation help through our [Live Chat support](https://visualstudio.microsoft.com/vs/support/#talktous). + +## Blogs + +Stay up to date on all new releases by taking advantage of the insights and recommendations available in at [Microsoft Developer Blogs](https://devblogs.microsoft.com/). 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/what-s-new-for-visual-cpp-in-visual-studio.md b/docs/overview/what-s-new-for-visual-cpp-in-visual-studio.md index 10169c5fb1f..491f55e9093 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,63 +1,575 @@ --- 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: 05/24/2022 -ms.technology: "cpp-ide" +ms.date: 11/04/2025 +ms.service: "visual-cpp" +ms.subservice: "ide" ms.custom: intro-whats-new +ai-usage: ai-assisted --- -# What's new for C++ in Visual Studio 2022 -Visual Studio 2022 brings many updates and fixes to the Microsoft C++ environment. We've added features and fixed many bugs and issues in the compiler and tools. The Visual Studio IDE also offers significant improvements in performance and productivity, and now runs natively as a 64-bit application. For more information on what's new in all of Visual Studio, visit [What's new in Visual Studio 2022](/visualstudio/ide/whats-new-visual-studio-2022?view=vs-2022&preserve-view=true). For information about what's new in the C++ docs, see [Microsoft C++ docs: What's new](whats-new-cpp-docs.md). +# What's new for C++ in Visual Studio + +Microsoft C++ Build Tools (MSVC Build Tools) versioning is no longer synchronized with Visual Studio versioning starting with Visual Studio 2026 version 18.0 and Microsoft C++ Build Tools version 14.50. For the latest updates to MSVC going forward, see [What's new for MSVC](what-s-new-for-msvc.md). + +## What's new for C++ in Visual Studio 2022 + +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-v17.13) | +| 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 coroutines. 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(rng), 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-v17.12) | +| 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/VS-2022-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-v17.11) | +| 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/VS-2022-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-v17.10) | +| 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 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, the number of ForceInlines, and the impact of header files on build time. For more information, see [Tutorial: Troubleshoot function inlining on build time](../build-insights/tutorials/build-insights-function-view.md) and [Tutorial: Troubleshoot header file impact on build time](../build-insights/tutorials/build-insights-included-files-view.md). +- Remote Linux unit test support now lets you run your CTest and GTest tests on your remote Linux machines from Visual Studio's Test Explorer, just like your local tests. + +## What's new for C++ in Visual Studio version 17.7 + +*Released Aug 2023* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's new for C++ Developers in Visual Studio 2022 17.7](https://devblogs.microsoft.com/cppblog/whats-new-for-c-developers-in-visual-studio-2022-17-7/) | +| New C++ features specific to game development | [Unleashing the Power of Visual Studio 2022 for C++ Game Development](https://devblogs.microsoft.com/visualstudio/unleashing-the-power-of-visual-studio-2022-for-c-game-development/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.7](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-177) | +| New features in the Visual Studio 17.7 IDE |[Visual Studio 2022 version 17.7 Release Notes](/visualstudio/releases/2022/release-notes-v17.7) | +| C++ language conformance improvements in Visual Studio 2022 17.7 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_177) | + +A partial list of new features: + +* Faster debugging sessions and faster project load times +* Step-by-step visualization of macro expansion +* One-click download for Windows Subsystem for Linux (WSL) +* Improved support for Doxygen comments +* C++ Build Insights for game development +* Added [`/std:clatest`](../build/reference/std-specify-language-standard-version.md) for the C compiler. +* Unreal Engine project improvements such as faster IntelliSense and syntax colorization, the ability to find all Unreal Engine Blueprint references, and more. + +## What's new for C++ in Visual Studio version 17.6 + +*Released May 2023* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.6](https://devblogs.microsoft.com/cppblog/visual-studio-17-6-for-cpp-devs/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.6](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-176) | +| New features in the Visual Studio 17.6 IDE | [Visual Studio 2022 version 17.6 Release Notes](/visualstudio/releases/2022/release-notes-v17.6) | +| C++ language conformance improvements in Visual Studio 2022 17.6 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_176) | + +A partial list of new features includes: +- CMake script debugging +- Built-in support for High Level Shading Language (HLSL) +- Unreal Engine Log viewer +- VCPKG is now added by default +- Initial support for C++20 in C++/CLI projects and some C++23 standard library features for ranges. + +## What's new for C++ in Visual Studio version 17.5 + +*Released Feb 2023* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.5](https://devblogs.microsoft.com/cppblog/visual-studio-17-5-for-cpp-devs/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.5](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-175) | +| New features in the Visual Studio 17.5 IDE | [Visual Studio 2022 version 17.5 Release Notes](/visualstudio/releases/2022/release-notes-v17.5) | + +A partial list of new features includes: + +- `std::move`, `std::forward`, `std::move_if_noexcept`, and `std::forward_like` now don't produce function calls in generated code, even in debug mode. This change avoids named casts causing unnecessary overhead in debug builds. `/permissive-` (or an option that implies it, such as `/std:c++20` or `/std:c++latest`) is required. +- Added [`[[msvc::intrinsic]]`](../cpp/attributes.md#msvcintrinsic). You can apply this attribute to nonrecursive functions consisting of a single cast, which take only one parameter. +- Added support for Linux Console in the Integrated Terminal, which allows for terminal I/O. +- Added initial experimental support for C11 atomic primitives (``). You can enable this experimental feature with the `/experimental:c11atomics` option in `/std:c11` mode or later. +- Added a new set of experimental high-confidence checks to the Lifetime Checker for reduced noise. +- A new preview feature, Remote File Explorer, lets you view the file directory on your remote machines within VS, and upload and download files to it. +- Changed versioning of CMake executables shipped with Visual Studio to match Kitware versions. +- Added support for Hot Reload to the CMake Project template. +- Go To Definition for C++ now uses a more subtle indicator of the operation taking more time, replacing the modal dialog from previous versions. +- Started rollout of an experiment providing more smart results in the C++ autocompletion and member list. This functionality was previously known as Predictive IntelliSense but now uses a new presentation method. +- We now ship a native Arm64 Clang toolset with our LLVM workload, allowing native compilation on Arm64 machines. +- Added localization to the [Image Watch Extension](https://marketplace.visualstudio.com/items?itemName=VisualCPPTeam.ImageWatchForVisualStudio2022) (This extension is available in the Marketplace, and isn't bundled through the Visual Studio Installer). +- Added support for opening a Terminal window into the currently running Developer Container. +- Made several improvements to IntelliSense macro expansion. Notably, we enabled recursive expansion in more contexts, and we added options to the pop up to copy the expansion to the clipboard or expand the macro inline. +- Concurrent monitoring is now supported in the Serial Monitor. Concurrent monitoring allows you to monitor multiple ports at the same time side by side. Press the plus button to open another Serial Monitor and get started. +- You can now view properties from base classes modified in an Unreal Blueprint asset without leaving Visual Studio. Double-click in a Blueprint reference for a C++ class or property to open the UE Asset Inspector in Visual Studio. +- Enabled running DevContainers on a remote Linux machine. +- Enabled selection of multiple targets to build in the CMake Targets view. +- Added support for CMakePresets.json version 5. See the [CMake documentation](https://cmake.org/cmake/help/v3.24/manual/cmake-presets.7.html) for information of new features. +- Enabled Test Explorer to build and test multiple CMake targets in parallel. +- Added "Open container in terminal" option to Dev Containers. +- Implemented standard library features: + + - [P2508R1](https://wg21.link/P2508R1) `basic_format_string`, `format_string`, `wformat_string` + - [P2322R6](https://wg21.link/P2322R6) `ranges::fold_left`, `ranges::fold_right`, and so on. + - [P2321R2](https://wg21.link/P2321R2) `views::zip` (doesn't include `zip_transform`, `adjacent`, and `adjacent_transform`) + +## What's new for C++ in Visual Studio version 17.4 + +*Released Nov 2022* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [What's New for C++ Developers in Visual Studio 2022 17.4](https://devblogs.microsoft.com/cppblog/whats-new-for-cpp-developers-in-visual-studio-2022-17-4/) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.4](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-174) | +| New features in the Visual Studio 17.4 IDE | [Visual Studio 2022 version 17.4 Release Notes](/visualstudio/releases/2022/release-notes-v17.4) | +| C++ language conformance improvements in Visual Studio 2022 17.4 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_174) | + +A partial list of new features in 17.4: + +- Improved compiler error messages to provide more correct and useful information, especially for concepts. +- Added experimental MSVC option [`/experimental:log`](../build/reference/experimental-log.md) to output [structured SARIF diagnostics](../build/reference/sarif-output.md) to the specified directory. +- Added support for C23 attributes to IntelliSense and continued progress in C++20 modules support. +- Improved indexing performance when opening a new solution. Large projects could see a 20-35% improvement from 17.3. +- Improved Named Return Value Optimization (NRVO): + - NRVO is enabled for cases that involve exception handling or loops. + - NRVO is enabled even under **`/Od`** if the user passes the **`/Zc:nrvo`** option, or **`/std:c++20`** or later, or **`/permissive-`**. + - You can now disable NRVO with the **`/Zc:nrvo-`** option. +- Upgraded the version of LLVM shipped with Visual Studio to 15.0.1. For more information on what is available, see the [LLVM](https://releases.llvm.org/15.0.0/docs/ReleaseNotes.html) and [Clang](https://releases.llvm.org/15.0.0/tools/clang/docs/ReleaseNotes.html) release notes. +- Added support to Visual Studio for vcpkg artifacts with CMake projects. For projects that include a vcpkg manifest, the environment is activated automatically on project open. Learn more about this feature in the [vcpkg environment activation in Visual Studio](https://aka.ms/vsvcpkgenv) blog post. +- You can now use Dev Containers for your C++ projects. Learn more about this feature in our [Dev Containers for C++](https://aka.ms/vscppdevcontainer) blog post. +- IntelliSense now respects the order of preincluded headers when one of them is a PCH. Previously, when a PCH was used via **`/Yu`** and force-included via **`/FI`**, IntelliSense would always process it first, before any other headers included via **`/FI`**. This behavior didn't match the build behavior. With this change, **`/FI`** headers are processed in the order they're specified. +- Removed internal prefixes from CTest names in Test Explorer. +- Updated the version of CMake shipped with Visual Studio to version 3.24.1. For details of what is available, see the [CMake release notes](https://cmake.org/cmake/help/v3.24/release/3.24.html). +- Android SDK update: + - Ant scripts were removed, so users no longer see Ant-based templates in the New Project dialog. For help migrating from Ant templates to Gradle templates, see [Migrating Builds From Apache Ant](https://docs.gradle.org/current/userguide/migrating_from_ant.html) + - Added support for building with NDK 23 and 24 + - Updated NDK component to the LTS version 23 +- Added vectorized implementations of `ranges::min_element()`, `ranges::max_element()`, and `ranges::minmax_element()` +- We continue to track the latest developments in C++ standardization. Support for these C++23 features is available by including [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) in your compiler options: + - [P2302R4](https://wg21.link/p2302r4) `ranges::contains`, `ranges::contains_subrange` + - [P2499R0](https://wg21.link/p2499r0) `string_view` Range Constructor Should Be `explicit` + - [P0849R8](https://wg21.link/p0849r8) `auto(x)`: decay-copy In The Language + + (The compiler part isn't implemented yet. The library part was implemented in C++20 mode when Ranges support was initially implemented.) + - [P0881R7](https://wg21.link/p0881r7) `` + - [P2301R1](https://wg21.link/p2301r1) Add a `pmr` alias for `std::stacktrace` + - [P1328R1](https://wg21.link/p1328r1) `constexpr type_info::operator==()` + - [P2440R1](https://wg21.link/p2440r1) `ranges::iota`, `ranges::shift_left`, `ranges::shift_right` + - [P2441R2](https://wg21.link/p2441r2) `views::join_with` + +- Added an option "Navigation after Create Declaration/Definition" to allow you to choose the navigation behavior of the Create Declaration/Definition feature. You can select between peeking (the default) or opening the document, or no navigation. +- Arm64 builds of Visual Studio now bundle Arm64 versions of CMake and Ninja. +- Added support for CMake Presets version 4. For details of what is available, see the [CMake release notes](https://cmake.org/cmake/help/v3.23/release/3.23.html#id6). +- Remote system connections using the [Connection Manager](../linux/connect-to-your-remote-linux-computer.md) now support SSH ProxyJump. ProxyJump is used to access an SSH host via another SSH host (for example, to access a host behind a firewall). + +## What's new for C++ in Visual Studio version 17.3 + +*Released Aug 2022* + +| For more information about | See | +|---|---| +| What's new for C++ developers | [C++ improvements in 17.3](https://devblogs.microsoft.com/visualstudio/visual-studio-2022-17-3-is-now-available/#c++-improvements) | +| Standard Library (STL) merged C++23 features, Language Working Group (LWG) issue resolutions, performance improvements, enhanced behavior, and fixed bugs | [STL Changelog 17.3](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-173) | +| New features in the Visual Studio 17.3 IDE | [Visual Studio 2022 version 17.3 Release Notes](/visualstudio/releases/2022/release-notes-v17.3) | +| C++ language conformance improvements in Visual Studio 2022 17.3 | [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](cpp-conformance-improvements.md#improvements_173) | + +A partial list of new features in 17.3: + +- The Arm64EC toolchain is no longer marked as experimental and is ready for production use. +- The Visual Studio Terminal can now be used as an SSH client with your stored SSH connections. With the C++ for Linux Tools installed, open the Terminal tool window. The Terminal dropdown is populated with your stored connections. When you select a connection, a new Terminal window opens inside Visual Studio that shows a pseudo-terminal on your remote system. Control characters, colors, and cursor positional awareness are all supported. +- Visual Studio can now add Unreal Engine class templates for your UE projects. To try this feature, ensure **IDE support for Unreal Engine** is selected in the **Game development with C++** workload in the Visual Studio Installer. When you're working on a UE project, right-click in the project or a folder/filter and select **Add** > **UE Class**. +- **Go to Definition** now remembers the prior signature and navigates accordingly when a better match isn't available (for example, after you manually change the signature of one of the pair). +The responsiveness of **Go To All** is improved. Previously, results appeared after you stopped typing. In the new experience, results show as you type. +- In contexts requiring `enum` type completion (for example, assignments to `enum` variables, case labels, returning `enum` type, and so on), the autocompletion list is now filtered to just the matching enumerators and related constructs. +- Added NuGet PackageReference support for C++/CLI MSBuild projects targeting .NET Core. This change was made to unblock mixed codebases from being able to adopt .NET Core. This support doesn't work for other C++ project types or any C++ project types targeting .NET Framework. There are no plans to extend PackageReference support to other C++ scenarios. The team is working on separate experiences involving vcpkg for non-MSBuild scenarios and to add greater functionality. +- Added a Serial Monitor window for embedded development, available through **Debug** > **Windows** > **Serial Monitor**. +- Improved C++ indexing by ~66% compared to 17.2. +- Updated the version of CMake shipped with Visual Studio to version 3.23. See the [CMake 3.23 release notes](https://cmake.org/cmake/help/v3.23/release/3.23.html) for details of what is available. +- Upgraded the versions of LLVM tools shipped with Visual Studio to v14. For details of what is available, see the [LLVM](https://releases.llvm.org/14.0.0/docs/ReleaseNotes.html) and [Clang](https://releases.llvm.org/14.0.0/tools/clang/docs/ReleaseNotes.html) release notes. +- Updated the side-by-side Dev 16.11 C++ Toolset to version 14.29.30145.00. The latest version of the Dev 16.11 C++ Toolset contains important bug fixes, including fixing all remaining C++20 defect reports. For more information about bug fixes, including C++20 defect reports in Dev 16.11, see [Visual Studio 2019 version 16.11.14 release notes](/visualstudio/releases/2019/release-notes#16.11.14). +- Made various improvements to the in-editor experience of C++ modules. We're continuously working on improving the quality of the experience but encourage you to try them in 17.3. Report remaining issues through [Developer Community](https://aka.ms/vsfeedback/browsecpp). ## What's new for C++ in Visual Studio version 17.2 -For a summary of new features and bug fixes in Visual Studio, see [What's New in Visual Studio 2022 version 17.2](/visualstudio/releases/2022/release-notes). +*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`](https://wg21.link/p1938). - Added inline parameter name and type hint support, toggled by pressing **Alt+F1** or double-tapping **Ctrl**. This behavior can be customized under **Tools > Options > Text Editors > C/C++ > IntelliSense**. - - Added experimental support for C++20 modules in CMake projects. This support is currently only available with the Visual Studio (MSBuild) generator. - - In 17.1, we introduced peripheral register and RTOS views for embedded developers. We continue to improve the capabilities of those views with usability improvements in 17.2: - The RTOS tool window is now hidden by default. It prevents showing a tool window with error messages that aren't relevant when you're not using an RTOS. - - When you double click on 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. - - 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. - + - 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 to the top of the Peripheral View. +- Added implementations of the remaining C++20 defect reports (also known as *backports*). All C++20 features are now available under the **`/std:c++20`** option. For more information about the implemented backports, see the [VS 2022 Changelog](https://github.com/microsoft/STL/wiki/VS-2022-Changelog#vs-2022-172) in the Microsoft/STL GitHub repository and the [MSVC's STL Completes `/std:c++20`](https://devblogs.microsoft.com/cppblog/msvcs-stl-completes-stdc20/) blog post. - We added various C++23 Library features, available under the **`/std:c++latest`** option. For more information about the new features, see the [STL Repo changelog](https://github.com/microsoft/STL/wiki/Changelog). - - Improved performance of the initial C++ indexing by up to 20%, depending on the depth of the include graph. ## What's new for C++ in Visual Studio version 17.1 -For a summary of new features and bug fixes in Visual Studio, see [What's New in Visual Studio 2022 version 17.1](/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. +| 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) | -- You can now debug core dumps on a remote macOS system from Visual Studio with LLDB or GDB. +A partial list of new features in 17.1: -- 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 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/). -- 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. +## What's new for C++ in Visual Studio version 17.0 -- Added a new register visualization window for embedded targets, available through **Debug** > **Windows** > **Embedded Registers**. +*Released Nov 2021* -- Added a new thread view for RTOS projects, available through **Debug** > **Windows** > **RTOS Objects**. +| 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/VS-2022-Changelog#vs-2022-170) | +| 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) | -## What's new for C++ in Visual Studio version 17.0 - -For a summary of new features and bug fixes in Visual Studio, see [What's New in Visual Studio 2022 version 17.0](/visualstudio/releases/2022/release-notes-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++ @@ -74,26 +586,22 @@ In Visual Studio 2022, when you start your app in the debugger, you can use the ### Improved CMake support -- We've upgraded the version of CMake shipped with Visual Studio to version 3.21. For more information on what's available in this version, see the [CMake 3.21 release notes](https://cmake.org/cmake/help/latest/release/3.21.html). - -- CMake Overview Pages have been updated to support *`CMakePresets.json`*. +- Upgraded the version of CMake shipped with Visual Studio to version 3.21. For more information on what's available in this version, see the [CMake 3.21 release notes](https://cmake.org/cmake/help/latest/release/3.21.html). +- CMake Overview Pages are updated to support *`CMakePresets.json`*. - You can now configure and build your CMake projects with CMake 3.21 and *`CMakePresets.json`* v3. - - Visual Studio now supports the `buildPresets.targets` option in *`CMakePresets.json`*. This option allows you to build a subset of targets in your CMake project. - -- The Project menu in CMake projects has been streamlined and exposes options to "Delete Cache and Reconfigure" and "View Cache". - -- Implemented the **`/scanDependencies`** compiler option to list C++20 module dependencies for CMake projects, as described in [P1689R4](https://wg21.link/P1689r4). It's a step towards support for building modules-based projects with CMake and we're working on completing this support in later releases. +- The Project menu in CMake projects is streamlined and exposes options to "Delete Cache and Reconfigure" and "View Cache." +- Implemented the **`/scanDependencies`** compiler option to list C++20 module dependencies for CMake projects, as described in [P1689R5](https://wg21.link/P1689r5). It's a step towards support for building modules-based projects with CMake and we're working on completing this support in later releases. ### Standard Library improvements -Select Standard Library (STL) improvements are highlighted here. For a comprehensive list of new functionality, changes, bug fixes, and performance improvements, see the STL team's [Changelog](https://github.com/microsoft/STL/wiki/Changelog#vs-2022). +Select Standard Library (STL) improvements are highlighted here. For a comprehensive list of new functionality, changes, bug fixes, and performance improvements, see the STL team's [Changelog](https://github.com/microsoft/STL/wiki/Changelog). - Added debugging visualizers to improve how the following types are displayed: `source_location`, `bind_front()`, `u8string` (and its iterators), `default_sentinel_t`, `unreachable_sentinel_t`, `ranges::empty_view`, `ranges::single_view`, `ranges::iota_view` (and its iterator/sentinel), `ranges::ref_view`, `thread`, `thread::id`, `jthread`, and `filesystem::path` - Added `[[nodiscard]]` to the `stoi()` family of functions in `` and to various functions in `` such as the `collate` member functions, `has_facet()`, and the `isalnum()` and `tolower()` families. -- [P0980R1](https://wg21.link/P0980R1) Made `std::string` `constexpr` in VS 2019 16.10. Now it's also supported for Clang. -- [P1004R2](https://wg21.link/P1004R2) Made `std::vector` `constexpr`in VS 2019 16.10. Now it's also supported for Clang. +- [P0980R1](https://wg21.link/P0980R1) Made `std::string` `constexpr` in VS 2019 16.10. Now supported for Clang. +- [P1004R2](https://wg21.link/P1004R2) Made `std::vector` `constexpr` in VS 2019 16.10. Now supported for Clang. **Highlighted C++23 features** @@ -102,7 +610,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** @@ -114,45 +622,41 @@ 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 -- C++ AMP headers are now deprecated. Including `` in a C++ project generates build errors. To silence the errors, define `_SILENCE_AMP_DEPRECATION_WARNINGS`. For more information, see [our AMP Deprecation links](/cpp/parallel/amp/cpp-amp-overview). +- C++ AMP headers are now deprecated. Including `` in a C++ project generates build errors. To silence the errors, define `_SILENCE_AMP_DEPRECATION_WARNINGS`. For more information, see [our AMP Deprecation links](../parallel/amp/cpp-amp-overview.md). ### IntelliSense improvements - We made improvements in C++ IntelliSense when providing navigation and syntax highlighting for types from imported Modules and Header Units. IntelliSense is an active area of investment for us. Help us improve: Share your feedback on Developer Community by using **Help** > **Send Feedback**. - - We improved C++ IntelliSense performance by optimizing cached header usage and symbol database access, providing improved load times to get into your code. - - The IntelliSense Code Linter for C++ is now on by default, providing instant as-you-type suggestions and fix suggestions for common code defects. - - C++ IntelliSense for CMake projects now works when using a preset with a display name. ### C++ Workload updates - Updated to NDK r21 LTS in the **C++ Mobile Development** workload. - -- The **Game development with C++** workload now installs the latest Unreal Engine with support with for Visual Studio 2022. +- The **Game development with C++** workload now installs the latest Unreal Engine with support for Visual Studio 2022. ### Code analysis improvements - Code analysis now enforces that return values of functions annotated with `_Check_return_` or `_Must_inspect_result_` must be checked. - -- We've improved null pointer dereference detection in our code analysis tooling. - +- Null pointer dereference detection is improved in our code analysis tooling. - Added support for `gsl::not_null` to code analysis. - - Support for Libfuzzer under the **`/fsanitize=fuzzer`** compiler option. ## Release notes for older versions -Release notes for older C++ versions are also available. For information on what's new for C++ in Visual Studio 2019, see [What's new for C++ in Visual Studio 2019.](what-s-new-for-cpp-2019.md) For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017.](what-s-new-for-cpp-2017.md) For information on what's new in earlier versions, see [Visual C++ What's New 2003 through 2015.](../porting/visual-cpp-what-s-new-2003-through-2015.md) +Release notes for older C++ versions are also available: + +- For information on what's new for C++ in Visual Studio 2019, see [What's new for C++ in Visual Studio 2019](what-s-new-for-cpp-2019.md). +- For information on what's new for C++ in Visual Studio 2017, see [What's new for C++ in Visual Studio 2017](what-s-new-for-cpp-2017.md). +- For information on what's new in earlier versions, see [Visual C++ What's new 2003 through 2015](../porting/visual-cpp-what-s-new-2003-through-2015.md). ## Known issues @@ -168,4 +672,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 b3150802ac8..00000000000 --- a/docs/overview/whats-new-cpp-docs.md +++ /dev/null @@ -1,580 +0,0 @@ ---- -title: "What's new for the C++ docs" -ms.date: "11/5/2021" -description: "The new docs and doc updates for the Microsoft C/C++ compiler, ATL/MFC, C runtime, and standard library docs." -ms.custom: intro-whats-new ---- - -# Microsoft C++ docs: What's new for October 2021 - -This article lists major changes to the Microsoft C++ docs July 2021 through October 2021. - -- For what was new in the docs in previous months, see [What's new history](#whats-new-history). -- For what's new related to C++ in Visual Studio, see [What's new for C++ in Visual Studio](what-s-new-for-visual-cpp-in-visual-studio.md). -- For the latest C and C++ conformance with ISO standards status, see [C++ conformance improvements in Visual Studio](cpp-conformance-improvements.md). - -## Active Template Library (ATL), Microsoft Foundation Classes (MFC) - -### Updated articles - -- [`CSimpleStringT` Class](../atl-mfc-shared/reference/csimplestringt-class.md) - updated code examples and added code example output -- [MFC class hierarchy chart](../mfc/hierarchy-chart.md) - Update MFC hierarchy chart - -## C language - -### New articles - -- [Generic selection (C11)](../c-language/generic-selection.md) - -### Updated articles - -- [`register` storage-class specifier](../c-language/register-storage-class-specifier.md) - Add C5033 warning -- [C Pragmas](../c-language/c-pragmas.md) - Add system_header pragma documentation -- [C Bit Fields](../c-language/c-bit-fields.md) - Clarify int main(void) example & document MSVC doesn't straddle bit-fields - -## C runtime library - -### Updated articles - -- [CRT Initialization](../c-runtime-library/crt-initialization.md) - Add 16.11 Compiler warnings C5247 and C5248 -- [`rand`](../c-runtime-library/reference/rand.md) - Update code example -- [`wcstombs_s`, `_wcstombs_s_l`](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md) - Update code example -- [_get_errno](../c-runtime-library/reference/get-errno.md) - Update code example - -## C/C++ compiler and tools errors and warnings - -### New articles - -- [Command-line error D8049](../error-messages/tool-errors/command-line-error-d8049.md) -- [Compiler Warning C5243](../error-messages/compiler-warnings/c5243.md) -- [Compiler Warning C5247](../error-messages/compiler-warnings/c5247.md) -- [Compiler Warning C5248](../error-messages/compiler-warnings/c5248.md) -- [Compiler Warning (level 1) C5033](../error-messages/compiler-warnings/c5033.md) - -### Updated articles - -- [Command-line errors and warnings](../error-messages/tool-errors/command-line-errors-d8000-through-d9999.md) - new error messages -- [Compiler Warning (level 4) C4710](../error-messages/compiler-warnings/compiler-warning-level-4-c4710.md) - Add C5033 warning -- [Compiler Warnings C4800 through C5999](../error-messages/compiler-warnings/compiler-warnings-c4800-through-c4999.md) - Add compiler warning C5033, C5243, C5249, C5250, C5247, and C5248. -- [Compiler Error C2666](../error-messages/compiler-errors-2/compiler-error-c2666.md) - Update 16.1 conformance -- [Compiler Warning (level 4) C4702](../error-messages/compiler-warnings/compiler-warning-level-4-c4702.md) - Update warning C4702 -- [Compiler Error C2440](../error-messages/compiler-errors-1/compiler-error-c2440.md) - Add `/Zc:char8_t` compiler option -- [Compiler Error C2760](../error-messages/compiler-errors-2/compiler-error-c2760.md) - New `/Zc:lambda` info -- [Compiler Error C2259](../error-messages/compiler-errors-1/compiler-error-c2259.md) - Update code example - -## C/C++ compiler intrinsics and assembly language - -### New articles - -- [MASM instruction format](../assembler/masm/instruction-format.md) -- [OPTION AVXENCODING](../assembler/masm/option-avxencoding-masm.md) -- [OPTION LANGUAGE](../assembler/masm/option-language-masm.md) - -### Updated articles - -- [MASM for x64 (ml64.exe)](../assembler/masm/masm-for-x64-ml64-exe.md) - Document MASM instruction format including prefixes and option avxencoding -- [Microsoft Macro Assembler reference](../assembler/masm/microsoft-macro-assembler-reference.md) - Document MASM instruction format including prefixes and option avxencoding -- [`OPTION`](../assembler/masm/option-masm.md) - Document MASM instruction format including prefixes and option avxencoding -- [_InterlockedCompareExchange intrinsic functions](../intrinsics/interlockedcompareexchange-intrinsic-functions.md) - Adding missing interlocked intrinsic and fixing another interlock intrinsic return type - -## C/C++ in Visual Studio overview - -### New articles - -- [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2019](../overview/cpp-conformance-improvements-2019.md) -- [What's new for C++ in Visual Studio 2019](../overview/what-s-new-for-cpp-2019.md) - -### Updated articles - -- [Overview of C++ development in Visual Studio](../overview/overview-of-cpp-development.md) - Visual Studio 2022 related updates. -- [Install C11 and C17 support in Visual Studio](../overview/install-c17-support.md) - Visual Studio 2022 related updates, C17 updates -- [C++ Tools and Features in Visual Studio Editions](../overview/visual-cpp-tools-and-features-in-visual-studio-editions.md) - Visual Studio 2022 related updates, C17 updates -- [C++ Conformance improvements, behavior changes, and bug fixes in Visual Studio 2022](../overview/cpp-conformance-improvements.md) - Visual Studio 2022 and 16.1 conformance updates -- [Microsoft C/C++ language conformance by Visual Studio version](../overview/visual-cpp-language-conformance.md) - Visual Studio 2022 related updates -- [C and C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md) - Add missing redist content - -## C/C++ preprocessor reference - -### New articles - -- [`system_header` pragma](../preprocessor/system-header-pragma.md) - -### Updated articles - -- [`fenv_access` pragma](../preprocessor/fenv-access.md) - Add floating-point *contractions* info -- [`float_control` pragma](../preprocessor/float-control.md) - Add floating-point *contractions* info -- [`fp_contract` pragma](../preprocessor/fp-contract.md) - Add floating-point *contractions* info -- [Predefined macros](../preprocessor/predefined-macros.md) - Add `__SANITIZE_ADDRESS__` and `_M_FP_CONTRACT` -- [Compiler warnings that are off by default](../preprocessor/compiler-warnings-that-are-off-by-default.md) - Add compiler warning C5243, C5249, C5250, C5247, and C5248 - -## C/C++ projects and build systems - -### New articles - -- [`/Zc:char8_t` (Enable C++20 char8_t type)](../build/reference/zc-char8-t.md) -- [`/Zc:lambda` (Enable updated lambda processor)](../build/reference/zc-lambda.md) -- [`/fsanitize-coverage` (Configure sanitizer coverage)](../build/reference/fsanitize-coverage.md) -- [`abspath` NMAKE function](../build/reference/nmake-function-abspath.md) -- [`basename` NMAKE function](../build/reference/nmake-function-basename.md) -- [`filter`, `filteri` NMAKE functions](../build/reference/nmake-function-filter.md) -- [`filterout`, `filterouti` NMAKE functions](../build/reference/nmake-function-filterout.md) -- [`findstring`, `findstringi` NMAKE functions](../build/reference/nmake-function-findstring.md) -- [`patsubst`, `patsubsti` NMAKE functions](../build/reference/nmake-function-patsubst.md) -- [`strip` NMAKE function](../build/reference/nmake-function-strip.md) -- [`subst`, `substi` NMAKE functions](../build/reference/nmake-function-subst.md) -- [Walkthrough: Build and debug C++ with WSL 2 and Visual Studio 2022](../build/walkthrough-build-debug-wsl2.md) - -### Updated articles - -- [Configure and build with CMake Presets in Visual Studio](../build/cmake-presets-vs.md) - Fix inconsistencies and add documentation about the "unspecified" architecture feature -- [Clang/LLVM support in Visual Studio CMake projects](../build/clang-support-cmake.md) - Clarified version-specific installation -- [CMake projects in Visual Studio](../build/cmake-projects-in-visual-studio.md) - Fix inconsistencies in CMake docs and add docs on using existing cache without cmake-server -- [/fp (Specify floating-point behavior)](../build/reference/fp-specify-floating-point-behavior.md) - Fix `/fp` sample code -- [`/Og` (Global Optimizations)](../build/reference/og-global-optimizations.md) - Clarify when the **`register`** keyword is ignored -- [`/PROFILE` (Performance Tools Profiler)](../build/reference/profile-performance-tools-profiler.md) - Address `/profile` issues -- [Use the Microsoft C++ toolset from the command line](../build/building-on-the-command-line.md) - Fix MSBuild recommendation & update C/C++ workload name -- [Use an NMAKE macro](../build/reference/using-an-nmake-macro.md) - Add documentation for the new NMAKE functions -- [Commands in a makefile](../build/reference/commands-in-a-makefile.md) - Combine and update NMAKE docs -- [NMAKE makefile contents and features](../build/reference/contents-of-a-makefile.md) - Combine and update NMAKE docs -- [Create a C++ makefile project](../build/reference/creating-a-makefile-project.md) - Combine and update NMAKE docs -- [Define an NMAKE macro](../build/reference/defining-an-nmake-macro.md) - Combine and update NMAKE docs -- [Dot directives](../build/reference/dot-directives.md) - Combine and update NMAKE docs -- [Inference rules](../build/reference/inference-rules.md) - Combine and update NMAKE docs -- [Inline files in a makefile](../build/reference/inline-files-in-a-makefile.md) - Combine and update NMAKE docs -- [Makefile Preprocessing](../build/reference/makefile-preprocessing.md) - Combine and update NMAKE docs -- [NMAKE Reference](../build/reference/nmake-reference.md) - Combine and update NMAKE docs -- [Running NMAKE](../build/reference/running-nmake.md) - Combine and update NMAKE docs -- [Sample Makefile](../build/reference/sample-makefile.md) - Combine and update NMAKE docs -- [Special NMAKE macros](../build/reference/special-nmake-macros.md) - Combine and update NMAKE docs -- [Configuring Programs for Windows XP](../build/configuring-programs-for-windows-xp.md) - Link updates for new redist article -- [`/Zc` (Conformance)](../build/reference/zc-conformance.md) - New `/Zc:lambda` information -- [`/Zc:__cplusplus` (Enable updated `__cplusplus` macro)](../build/reference/zc-cplusplus.md) - New `/Zc:lambda` information -- [CMake predefined build configurations](../build/cmake-predefined-configuration-reference.md) - Fix inconsistencies in CMake docs -- [`CMakePresets.json` and `CMakeUserPresets.json` Microsoft vendor maps](../build/cmake-presets-json-reference.md) - Fix inconsistencies in CMake docs -- [Tutorial: Debug a CMake project on a remote Windows machine](../build/cmake-remote-debugging.md) - Fix inconsistencies in CMake docs -- [`CMakeSettings.json` schema reference](../build/cmakesettings-reference.md) - Fix inconsistencies in CMake docs -- [`launch.vs.json` schema reference (C++)](../build/launch-vs-schema-reference-cpp.md) - add debugInfo macro definitions -- [`/external` (External headers diagnostics)](../build/reference/external-external-headers-diagnostics.md) - Add `system_header` pragma doc -- [DUMPBIN Reference](../build/reference/dumpbin-reference.md) - Setting `PATH` allows `DUMPBIN` to be executed from the command prompt -- [/Qspectre](../build/reference/qspectre.md) - Clarified `/Qspectre` Required Libraries section - -## C++ in Visual Studio - -### Updated articles - -- [Storage classes](../cpp/storage-classes-cpp.md) - Add C5033 warning -- [void (C++)](../cpp/void-cpp.md) - Clarify overall article -- [Labeled statements](../cpp/labeled-statements.md) - Correct labeled statements -- [Brace initialization](../cpp/initializing-classes-and-structs-without-constructors-cpp.md) - Address sanitizer comment location -- [Member Access Control (C++)](../cpp/member-access-control-cpp.md) - Update static member access in example -- [String and character literals (C++)](../cpp/string-and-character-literals-cpp.md) - Updates for C++20 portable **`char8_t`**. -- [Declarations and definitions (C++)](../cpp/declarations-and-definitions-cpp.md) - fix code sample -- [Template Specialization (C++)](../cpp/template-specialization-cpp.md) - update code example - -## C++ in Visual Studio tutorials - -### Updated articles - -- [Create a console calculator in C++](../get-started/tutorial-console-cpp.md) - add Git source control info to the tutorial - -## C++ porting and upgrade guide - -### Updated articles - -- [C++ binary compatibility between Visual Studio versions](../porting/binary-compat-2015-2017.md) - Update version info - -## C++ Standard Library (STL) - -### New articles - -- [`ambiguous_local_time` class](../standard-library/ambiguous-local-time.md) -- [`choose` enum](../standard-library/choose-enum.md) -- [`clock_time_conversion` struct](../standard-library/clock-time-conversion-struct.md) -- [`file_clock` class](../standard-library/file-clock-class.md) -- [`gps_clock` class](../standard-library/gps-clock-class.md) -- [`is_clock` structure](../standard-library/is-clock-struct.md) -- [`last_spec` struct](../standard-library/last-spec-struct.md) -- [`local_info` struct](../standard-library/local-info-struct.md) -- [`local_t` struct](../standard-library/local_t.md) -- [`nonexistent_local_time` class](../standard-library/nonexistent-local-time.md) -- [`sys_info` struct](../standard-library/sys-info-struct.md) -- [`tai_clock` class](../standard-library/tai-clock-class.md) -- [`time_zone_link` class](../standard-library/time-zone-link-class.md) -- [`tzdb_list` class](../standard-library/tzdb-list-class.md) -- [`tzdb` struct](../standard-library/tzdb-struct.md) -- [`utc_clock` class](../standard-library/utc-clock-class.md) -- [`zoned_time` class](../standard-library/zoned-time-class.md) -- [`zoned_traits` struct](../standard-library/zoned-traits-struct.md) - -### Updated articles - -- [`` functions](../standard-library/chrono-functions.md) - added new `` functions -- [``](../standard-library/chrono.md) - added new `` types -- [`duration` class](../standard-library/duration-class.md) - overall article update and linking to related non-member functions -- [Using Insertion Operators and Controlling Format](../standard-library/using-insertion-operators-and-controlling-format.md) - fix `setw` code example -- [`` operators](../standard-library/chrono-operators.md) - Added new C++20 chrono operators -- [`local_info` struct](../standard-library/local-info-struct.md) - updated descriptions for errors -- [`time_zone` class](../standard-library/time-zone-class.md) - article clarifications -- [`any` class](../standard-library/any-class.md) - Added requirements section -- [`` functions](../standard-library/any-functions.md) - Added requirements section -- [`bad_any_cast` class](../standard-library/bad-any-cast-class.md) - Added requirements section -- [domain_error Class](../standard-library/domain-error-class.md) - Improve `` documentation and examples -- [invalid_argument Class](../standard-library/invalid-argument-class.md) - Improve `` documentation and examples -- [length_error Class](../standard-library/length-error-class.md) - Improve `` documentation and examples -- [logic_error Class](../standard-library/logic-error-class.md) - Improve `` documentation and examples -- [out_of_range Class](../standard-library/out-of-range-class.md) - Improve `` documentation and examples -- [overflow_error Class](../standard-library/overflow-error-class.md) - Improve `` documentation and examples -- [range_error Class](../standard-library/range-error-class.md) - Improve `` documentation and examples -- [runtime_error Class](../standard-library/runtime-error-class.md) - Improve `` documentation and examples -- [underflow_error Class](../standard-library/underflow-error-class.md) - Improve `` documentation and examples -- [`filesystem`](../standard-library/filesystem.md) - `` no longer includes `` -- [Output File Stream Member Functions](../standard-library/output-file-stream-member-functions.md) - fixed code example -- [`` functions](../standard-library/bit-functions.md) - Fixed code example -- [``](../standard-library/execution.md) - Mention limits of concurrency -- [`` functions](../standard-library/future-functions.md) - Mention limits of concurrency -- [`thread` Class](../standard-library/thread-class.md) - Mention limits of concurrency - -## Overview of Windows programming in C++ - -### New articles - -- [Microsoft Visual C++ Redistributable Latest Supported Downloads](../windows/latest-supported-vc-redist.md) - -### Updated articles - -- [Walkthrough: Create a traditional Windows Desktop application (C++)](../windows/walkthrough-creating-windows-desktop-applications-cpp.md) - updated examples - -## Read and write code using C++ in Visual Studio - -### New articles - -- [IntelliSense code linter for C++ overview](../ide/cpp-linter-overview.md) -- [`lnt-assignment-equality`](../ide/lnt-assignment-equality.md) -- [`lnt-integer-float-division`](../ide/lnt-integer-float-division.md) -- [`lnt-accidental-copy`](../ide/lnt-accidental-copy.md) -- [`lnt-arithmetic-overflow`](../ide/lnt-arithmetic-overflow.md) -- [`lnt-logical-bitwise-mismatch`](../ide/lnt-logical-bitwise-mismatch.md) -- [`lnt-uninitialized-local`](../ide/lnt-uninitialized-local.md) - -### Updated articles - -- [`lnt-integer-float-division`](../ide/lnt-integer-float-division.md) - Add Visual Studio 2022 specific config information - -## STL/CLR library reference - -### Updated articles - -- [.NET programming with C++/CLI](../dotnet/dotnet-programming-with-cpp-cli-visual-cpp.md) - updated instructions for Visual Studio version UI differences - -## Community contributors - -The following people contributed to the C++, C, and Assembler docs during this period. Thank you! See [Microsoft Docs contributor guide overview](/contribute/) if you'd like to learn how to contribute. - -- [mohammad-ghasemi-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 [Microsoft Docs contributor guide overview](/contribute/) if you'd like to learn how to contribute. - -- [0xbadfca11](https://github.com/0xbadfca11) (1) -- [bclehmann](https://github.com/bclehmann) - Benjamin Lehmann (1) -- [Brian-Taylor8](https://github.com/Brian-Taylor8) (1) -- [cartwrightluke](https://github.com/cartwrightluke) (2) -- [ccawley2011](https://github.com/ccawley2011) - Cameron Cawley (1) -- [EddieBreeveld](https://github.com/EddieBreeveld) - Edward Breeveld (1) -- [FrankAtHexagon](https://github.com/FrankAtHexagon) - Frank Edwards (1) -- [fsb4000](https://github.com/fsb4000) - Igor Zhukov (1) -- [Jaiganeshkumaran](https://github.com/Jaiganeshkumaran) - Jaiganesh Kumaran (2) -- [jayvient](https://github.com/jayvient) - Jayvien (1) -- [KishkinJ10](https://github.com/KishkinJ10) (1) -- [kokosxD](https://github.com/kokosxD) - kokos (1) -- [langemol](https://github.com/langemol) - Jacco Mol (1) -- [MUzairS15](https://github.com/MUzairS15) (1) -- [nadavsu](https://github.com/nadavsu) - Nadav (1) -- [NegiAkash890](https://github.com/NegiAkash890) - Akash Negi (1) -- [pjessesco](https://github.com/pjessesco) - Jino Park (1) -- [pramodkirchki](https://github.com/pramodkirchki) (1) -- [Radfordhound](https://github.com/Radfordhound) - Graham Scott (1) -- [sapant-msft](https://github.com/sapant-msft) (1) -- [sebgod](https://github.com/sebgod) - Sebastian Godelet (1) -- [seedkar1](https://github.com/seedkar1) (1) -- [ShamanCoder](https://github.com/ShamanCoder) (1) -- [sheila-stewart](https://github.com/sheila-stewart) (1) -- [softmac](https://github.com/softmac) (1) -- [Thieum](https://github.com/Thieum) - Matthieu Penant (2) -- [tjs137](https://github.com/tjs137) (1) -- [urmyfaith](https://github.com/urmyfaith) - zx (1) -- [ValZapod](https://github.com/ValZapod) - Valerii Zapodovnikov (1) -- [westinn](https://github.com/westinn) - Nicolas Westin (1) diff --git a/docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md b/docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md deleted file mode 100644 index 10d5f9f5a2e..00000000000 --- a/docs/parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md +++ /dev/null @@ -1,35 +0,0 @@ ---- -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. - -## Related Topics - -|Title|Description| -|-----------|-----------------| -|[C++ AMP Overview](../../parallel/amp/cpp-amp-overview.md)|Describes the key features of C++ AMP and the mathematical library.| -|[Using Lambdas, Function Objects, and Restricted Functions](../../parallel/amp/using-lambdas-function-objects-and-restricted-functions.md)|Describes how to use lambda expressions, function objects, and restricted functions in calls to the [parallel_for_each](reference/concurrency-namespace-functions-amp.md#parallel_for_each) method.| -|[Using Tiles](../../parallel/amp/using-tiles.md)|Describes how to use tiles to accelerate your C++ AMP code.| -|[Using accelerator and accelerator_view Objects](../../parallel/amp/using-accelerator-and-accelerator-view-objects.md)|Describes how to use accelerators to customize execution of your code on the GPU.| -|[Using C++ AMP in UWP Apps](../../parallel/amp/using-cpp-amp-in-windows-store-apps.md)|Describes how to use C++ AMP in Universal Windows Platform (UWP) apps that use Windows Runtime types.| -|[Graphics (C++ AMP)](../../parallel/amp/graphics-cpp-amp.md)|Describes how to use the C++ AMP graphics library.| -|[Walkthrough: Matrix Multiplication](../../parallel/amp/walkthrough-matrix-multiplication.md)|Demonstrates matrix multiplication using C++ AMP code and tiling.| -|[Walkthrough: Debugging a C++ AMP Application](../../parallel/amp/walkthrough-debugging-a-cpp-amp-application.md)|Explains how to create and debug an application that uses parallel reduction to sum up a large array of integers.| - -## Reference - -[Reference (C++ AMP)](../../parallel/amp/reference/reference-cpp-amp.md)
-[tile_static Keyword](../../cpp/tile-static-keyword.md)
-[restrict (C++ AMP)](../../cpp/restrict-cpp-amp.md) - -## Other Resources - -[Parallel Programming in Native Code Blog](/archive/blogs/nativeconcurrency/)
-[C++ AMP sample projects for download](/archive/blogs/nativeconcurrency/c-amp-sample-projects-for-download)
-[Analyzing C++ AMP Code with the Concurrency Visualizer](/archive/blogs/nativeconcurrency/analyzing-c-amp-code-with-the-concurrency-visualizer) diff --git a/docs/parallel/amp/cpp-amp-overview.md b/docs/parallel/amp/cpp-amp-overview.md deleted file mode 100644 index 0591dea93e9..00000000000 --- a/docs/parallel/amp/cpp-amp-overview.md +++ /dev/null @@ -1,505 +0,0 @@ ---- -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. -> 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. - -## System Requirements - -- Windows 7 or later - -- Windows Server 2008 R2 or later - -- DirectX 11 Feature Level 11.0 or later hardware - -- For debugging on the software emulator, Windows 8 or Windows Server 2012 is required. For debugging on the hardware, you must install the drivers for your graphics card. For more information, see [Debugging GPU Code](/visualstudio/debugger/debugging-gpu-code). - -- Note: AMP is currently not supported on ARM64. - -## Introduction - -The following two examples illustrate the primary components of C++ AMP. Assume that you want to add the corresponding elements of two one-dimensional arrays. For example, you might want to add `{1, 2, 3, 4, 5}` and `{6, 7, 8, 9, 10}` to obtain `{7, 9, 11, 13, 15}`. Without using C++ AMP, you might write the following code to add the numbers and display the results. - -```cpp -#include - -void StandardMethod() { - - int aCPP[] = {1, 2, 3, 4, 5}; - int bCPP[] = {6, 7, 8, 9, 10}; - int sumCPP[5]; - - for (int idx = 0; idx < 5; idx++) - { - sumCPP[idx] = aCPP[idx] + bCPP[idx]; - } - - for (int idx = 0; idx < 5; idx++) - { - std::cout << sumCPP[idx] << "\n"; - } -} -``` - -The important parts of the code are as follows: - -- Data: The data consists of three arrays. All have the same rank (one) and length (five). - -- Iteration: The first **`for`** loop provides a mechanism for iterating through the elements in the arrays. The code that you want to execute to compute the sums is contained in the first **`for`** block. - -- Index: The `idx` variable accesses the individual elements of the arrays. - -Using C++ AMP, you might write the following code instead. - -```cpp -#include -#include -using namespace concurrency; - -const int size = 5; - -void CppAmpMethod() { - int aCPP[] = {1, 2, 3, 4, 5}; - int bCPP[] = {6, 7, 8, 9, 10}; - int sumCPP[size]; - - // Create C++ AMP objects. - array_view a(size, aCPP); - array_view b(size, bCPP); - array_view sum(size, sumCPP); - sum.discard_data(); - - parallel_for_each( - // Define the compute domain, which is the set of threads that are created. - sum.extent, - // Define the code to run on each thread on the accelerator. - [=](index<1> idx) restrict(amp) { - sum[idx] = a[idx] + b[idx]; - } - ); - - // Print the results. The expected output is "7, 9, 11, 13, 15". - for (int i = 0; i < size; i++) { - std::cout << sum[i] << "\n"; - } -} -``` - -The same basic elements are present, but C++ AMP constructs are used: - -- Data: You use C++ arrays to construct three C++ AMP [array_view](../../parallel/amp/reference/array-view-class.md) objects. You supply four values to construct an `array_view` object: the data values, the rank, the element type, and the length of the `array_view` object in each dimension. The rank and type are passed as type parameters. The data and length are passed as constructor parameters. In this example, the C++ array that is passed to the constructor is one-dimensional. The rank and length are used to construct the rectangular shape of the data in the `array_view` object, and the data values are used to fill the array. The runtime library also includes the [array Class](../../parallel/amp/reference/array-class.md), which has an interface that resembles the `array_view` class and is discussed later in this article. - -- Iteration: The [parallel_for_each Function (C++ AMP)](reference/concurrency-namespace-functions-amp.md#parallel_for_each) provides a mechanism for iterating through the data elements, or *compute domain*. In this example, the compute domain is specified by `sum.extent`. The code that you want to execute is contained in a lambda expression, or *kernel function*. The `restrict(amp)` indicates that only the subset of the C++ language that C++ AMP can accelerate is used. - -- Index: The [index Class](../../parallel/amp/reference/index-class.md) variable, `idx`, is declared with a rank of one to match the rank of the `array_view` object. By using the index, you can access the individual elements of the `array_view` objects. - -## Shaping and Indexing Data: index and extent - -You must define the data values and declare the shape of the data before you can run the kernel code. All data is defined to be an array (rectangular), and you can define the array to have any rank (number of dimensions). The data can be any size in any of the dimensions. - -### index Class - -The [index Class](../../parallel/amp/reference/index-class.md) specifies a location in the `array` or `array_view` object by encapsulating the offset from the origin in each dimension into one object. When you access a location in the array, you pass an `index` object to the indexing operator, `[]`, instead of a list of integer indexes. You can access the elements in each dimension by using the [array::operator() Operator](reference/array-class.md#operator_call) or the [array_view::operator() Operator](reference/array-view-class.md#operator_call). - -The following example creates a one-dimensional index that specifies the third element in a one-dimensional `array_view` object. The index is used to print the third element in the `array_view` object. The output is 3. - -```cpp -int aCPP[] = {1, 2, 3, 4, 5}; -array_view a(5, aCPP); - -index<1> idx(2); - -std::cout << a[idx] << "\n"; -// Output: 3 -``` - -The following example creates a two-dimensional index that specifies the element where the row = 1 and the column = 2 in a two-dimensional `array_view` object. The first parameter in the `index` constructor is the row component, and the second parameter is the column component. The output is 6. - -```cpp -int aCPP[] = {1, 2, 3, 4, 5, 6}; -array_view a(2, 3, aCPP); - -index<2> idx(1, 2); - -std::cout < a(2, 3, 4, aCPP); - -// Specifies the element at 3, 1, 0. -index<3> idx(0, 1, 3); - -std::cout << a[idx] << "\n"; -// Output: 8 -``` - -### extent Class - -The [extent Class](../../parallel/amp/reference/extent-class.md) specifies the length of the data in each dimension of the `array` or `array_view` object. You can create an extent and use it to create an `array` or `array_view` object. You can also retrieve the extent of an existing `array` or `array_view` object. The following example prints the length of the extent in each dimension of an `array_view` object. - -```cpp -int aCPP[] = { - 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, - 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12}; -// There are 3 rows and 4 columns, and the depth is two. -array_view a(2, 3, 4, aCPP); - -std::cout << "The number of columns is " << a.extent[2] << "\n"; -std::cout << "The number of rows is " << a.extent[1] << "\n"; -std::cout << "The depth is " << a.extent[0] << "\n"; -std::cout << "Length in most significant dimension is " << a.extent[0] << "\n"; -``` - -The following example creates an `array_view` object that has the same dimensions as the object in the previous example, but this example uses an `extent` object instead of using explicit parameters in the `array_view` constructor. - -```cpp -int aCPP[] = {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24}; -extent<3> e(2, 3, 4); - -array_view a(e, aCPP); - -std::cout << "The number of columns is " << a.extent[2] << "\n"; -std::cout << "The number of rows is " << a.extent[1] << "\n"; -std::cout << "The depth is " << a.extent[0] << "\n"; -``` - -## Moving Data to the Accelerator: array and array_view - -Two data containers used to move data to the accelerator are defined in the runtime library. They are the [array Class](../../parallel/amp/reference/array-class.md) and the [array_view Class](../../parallel/amp/reference/array-view-class.md). The `array` class is a container class that creates a deep copy of the data when the object is constructed. The `array_view` class is a wrapper class that copies the data when the kernel function accesses the data. When the data is needed on the source device the data is copied back. - -### array Class - -When an `array` object is constructed, a deep copy of the data is created on the accelerator if you use a constructor that includes a pointer to the data set. The kernel function modifies the copy on the accelerator. When the execution of the kernel function is finished, you must copy the data back to the source data structure. The following example multiplies each element in a vector by 10. After the kernel function is finished, the `vector conversion operator` is used to copy the data back into the vector object. - -```cpp -std::vector data(5); - -for (int count = 0; count <5; count++) -{ - data[count] = count; -} - -array a(5, data.begin(), data.end()); - -parallel_for_each( - a.extent, - [=, &a](index<1> idx) restrict(amp) { - a[idx] = a[idx]* 10; - }); - -data = a; -for (int i = 0; i < 5; i++) -{ - std::cout << data[i] << "\n"; -} -``` - -### array_view Class - -The `array_view` has nearly the same members as the `array` class, but the underlying behavior is not the same. Data passed to the `array_view` constructor is not replicated on the GPU as it is with an `array` constructor. Instead, the data is copied to the accelerator when the kernel function is executed. Therefore, if you create two `array_view` objects that use the same data, both `array_view` objects refer to the same memory space. When you do this, you have to synchronize any multithreaded access. The main advantage of using the `array_view` class is that data is moved only if it is necessary. - -### Comparison of array and array_view - -The following table summarizes the similarities and differences between the `array` and `array_view` classes. - -|Description|array class|array_view class| -|-----------------|-----------------|-----------------------| -|When rank is determined|At compile time.|At compile time.| -|When extent is determined|At run time.|At run time.| -|Shape|Rectangular.|Rectangular.| -|Data storage|Is a data container.|Is a data wrapper.| -|Copy|Explicit and deep copy at definition.|Implicit copy when it is accessed by the kernel function.| -|Data retrieval|By copying the array data back to an object on the CPU thread.|By direct access of the `array_view` object or by calling the [array_view::synchronize Method](reference/array-view-class.md#synchronize) to continue accessing the data on the original container.| - -### Shared memory with array and array_view - -Shared memory is memory that can be accessed by both the CPU and the accelerator. The use of shared memory eliminates or significantly reduces the overhead of copying data between the CPU and the accelerator. Although the memory is shared, it cannot be accessed concurrently by both the CPU and the accelerator, and doing so causes undefined behavior. - -`array` objects can be used to specify fine-grained control over the use of shared memory if the associated accelerator supports it. Whether an accelerator supports shared memory is determined by the accelerator’s [supports_cpu_shared_memory](reference/accelerator-class.md#supports_cpu_shared_memory) property, which returns **`true`** when shared memory is supported. If shared memory is supported, the default [access_type Enumeration](reference/concurrency-namespace-enums-amp.md#access_type) for memory allocations on the accelerator is determined by the `default_cpu_access_type` property. By default, `array` and `array_view` objects take on the same `access_type` as the primary associated `accelerator`. - -By setting the [array::cpu_access_type Data Member](reference/array-class.md#cpu_access_type) property of an `array` explicitly, you can exercise fine-grained control over how shared memory is used, so that you can optimize the app for the hardware’s performance characteristics, based on the memory access patterns of its computation kernels. An `array_view` reflects the same `cpu_access_type` as the `array` that it’s associated with; or, if the array_view is constructed without a data source, its `access_type` reflects the environment that first causes it to allocate storage. That is, if it’s first accessed by the host (CPU), then it behaves as if it were created over a CPU data source and shares the `access_type` of the `accelerator_view` associated by capture; however, if it's first accessed by an `accelerator_view`, then it behaves as if it were created over an `array` created on that `accelerator_view` and shares the `array`’s `access_type`. - -The following code example shows how to determine whether the default accelerator supports shared memory, and then creates several arrays that have different cpu_access_type configurations. - -```cpp -#include -#include - -using namespace Concurrency; - -int main() -{ - accelerator acc = accelerator(accelerator::default_accelerator); - - // Early out if the default accelerator doesn’t support shared memory. - if (!acc.supports_cpu_shared_memory) - { - std::cout << "The default accelerator does not support shared memory" << std::endl; - return 1; - } - - // Override the default CPU access type. - acc.default_cpu_access_type = access_type_read_write - - // Create an accelerator_view from the default accelerator. The - // accelerator_view inherits its default_cpu_access_type from acc. - accelerator_view acc_v = acc.default_view; - - // Create an extent object to size the arrays. - extent<1> ex(10); - - // Input array that can be written on the CPU. - array arr_w(ex, acc_v, access_type_write); - - // Output array that can be read on the CPU. - array arr_r(ex, acc_v, access_type_read); - - // Read-write array that can be both written to and read from on the CPU. - array arr_rw(ex, acc_v, access_type_read_write); -} -``` - -## Executing Code over Data: parallel_for_each - -The [parallel_for_each](reference/concurrency-namespace-functions-amp.md#parallel_for_each) function defines the code that you want to run on the accelerator against the data in the `array` or `array_view` object. Consider the following code from the introduction of this topic. - -```cpp -#include -#include -using namespace concurrency; - -void AddArrays() { - int aCPP[] = {1, 2, 3, 4, 5}; - int bCPP[] = {6, 7, 8, 9, 10}; - int sumCPP[5] = {0, 0, 0, 0, 0}; - - array_view a(5, aCPP); - array_view b(5, bCPP); - array_view sum(5, sumCPP); - - parallel_for_each( - sum.extent, - [=](index<1> idx) restrict(amp) - { - sum[idx] = a[idx] + b[idx]; - } - ); - - for (int i = 0; i < 5; i++) { - std::cout << sum[i] << "\n"; - } -} -``` - -The `parallel_for_each` method takes two arguments, a compute domain and a lambda expression. - -The *compute domain* is an `extent` object or a `tiled_extent` object that defines the set of threads to create for parallel execution. One thread is generated for each element in the compute domain. In this case, the `extent` object is one-dimensional and has five elements. Therefore, five threads are started. - -The *lambda expression* defines the code to run on each thread. The capture clause, `[=]`, specifies that the body of the lambda expression accesses all captured variables by value, which in this case are `a`, `b`, and `sum`. In this example, the parameter list creates a one-dimensional `index` variable named `idx`. The value of the `idx[0]` is 0 in the first thread and increases by one in each subsequent thread. The `restrict(amp)` indicates that only the subset of the C++ language that C++ AMP can accelerate is used. The limitations on functions that have the restrict modifier are described in [restrict (C++ AMP)](../../cpp/restrict-cpp-amp.md). For more information, see, [Lambda Expression Syntax](../../cpp/lambda-expression-syntax.md). - -The lambda expression can include the code to execute or it can call a separate kernel function. The kernel function must include the `restrict(amp)` modifier. The following example is equivalent to the previous example, but it calls a separate kernel function. - -```cpp -#include -#include -using namespace concurrency; - -void AddElements( - index<1> idx, - array_view sum, - array_view a, - array_view b) restrict(amp) { - sum[idx] = a[idx] + b[idx]; -} - -void AddArraysWithFunction() { - - int aCPP[] = {1, 2, 3, 4, 5}; - int bCPP[] = {6, 7, 8, 9, 10}; - int sumCPP[5] = {0, 0, 0, 0, 0}; - - array_view a(5, aCPP); - array_view b(5, bCPP); - array_view sum(5, sumCPP); - - parallel_for_each( - sum.extent, - [=](index<1> idx) restrict(amp) { - AddElements(idx, sum, a, b); - } - ); - - for (int i = 0; i < 5; i++) { - std::cout << sum[i] << "\n"; - } -} -``` - -## Accelerating Code: Tiles and Barriers - -You can gain additional acceleration by using tiling. Tiling divides the threads into equal rectangular subsets or *tiles*. You determine the appropriate tile size based on your data set and the algorithm that you are coding. For each thread, you have access to the *global* location of a data element relative to the whole `array` or `array_view` and access to the *local* location relative to the tile. Using the local index value simplifies your code because you don't have to write the code to translate index values from global to local. To use tiling, call the [extent::tile Method](reference/extent-class.md#tile) on the compute domain in the `parallel_for_each` method, and use a [tiled_index](../../parallel/amp/reference/tiled-index-class.md) object in the lambda expression. - -In typical applications, the elements in a tile are related in some way, and the code has to access and keep track of values across the tile. Use the [tile_static Keyword](../../cpp/tile-static-keyword.md) keyword and the [tile_barrier::wait Method](reference/tile-barrier-class.md#wait) to accomplish this. A variable that has the **tile_static** keyword has a scope across an entire tile, and an instance of the variable is created for each tile. You must handle synchronization of tile-thread access to the variable. The [tile_barrier::wait Method](reference/tile-barrier-class.md#wait) stops execution of the current thread until all the threads in the tile have reached the call to `tile_barrier::wait`. So you can accumulate values across the tile by using **tile_static** variables. Then you can finish any computations that require access to all the values. - -The following diagram represents a two-dimensional array of sampling data that is arranged in tiles. - -![Index values in a tiled extent.](../../parallel/amp/media/camptiledgridexample.png "Index values in a tiled extent") - -The following code example uses the sampling data from the previous diagram. The code replaces each value in the tile by the average of the values in the tile. - -```cpp -// Sample data: -int sampledata[] = { - 2, 2, 9, 7, 1, 4, - 4, 4, 8, 8, 3, 4, - 1, 5, 1, 2, 5, 2, - 6, 8, 3, 2, 7, 2}; - -// The tiles: -// 2 2 9 7 1 4 -// 4 4 8 8 3 4 -// -// 1 5 1 2 5 2 -// 6 8 3 2 7 2 - -// Averages: -int averagedata[] = { - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, - 0, 0, 0, 0, 0, 0, -}; - -array_view sample(4, 6, sampledata); - -array_view average(4, 6, averagedata); - -parallel_for_each( - // Create threads for sample.extent and divide the extent into 2 x 2 tiles. - sample.extent.tile<2,2>(), - [=](tiled_index<2,2> idx) restrict(amp) { - // Create a 2 x 2 array to hold the values in this tile. - tile_static int nums[2][2]; - - // Copy the values for the tile into the 2 x 2 array. - nums[idx.local[1]][idx.local[0]] = sample[idx.global]; - - // When all the threads have executed and the 2 x 2 array is complete, find the average. - idx.barrier.wait(); - int sum = nums[0][0] + nums[0][1] + nums[1][0] + nums[1][1]; - - // Copy the average into the array_view. - average[idx.global] = sum / 4; - }); - -for (int i = 0; i <4; i++) { - for (int j = 0; j <6; j++) { - std::cout << average(i,j) << " "; - } - std::cout << "\n"; -} - -// Output: -// 3 3 8 8 3 3 -// 3 3 8 8 3 3 -// 5 5 2 2 4 4 -// 5 5 2 2 4 4 -``` - -## Math Libraries - -C++ AMP includes two math libraries. The double-precision library in the [Concurrency::precise_math Namespace](../../parallel/amp/reference/concurrency-precise-math-namespace.md) provides support for double-precision functions. It also provides support for single-precision functions, although double-precision support on the hardware is still required. It conforms to the [C99 Specification (ISO/IEC 9899)](https://go.microsoft.com/fwlink/p/?linkid=225887). The accelerator must support full double precision. You can determine whether it does by checking the value of the [accelerator::supports_double_precision Data Member](reference/accelerator-class.md#supports_double_precision). The fast math library, in the [Concurrency::fast_math Namespace](../../parallel/amp/reference/concurrency-fast-math-namespace.md), contains another set of math functions. These functions, which support only **`float`** operands, execute more quickly but aren’t as precise as those in the double-precision math library. The functions are contained in the \ header file and all are declared with `restrict(amp)`. The functions in the \ header file are imported into both the `fast_math` and `precise_math` namespaces. The **`restrict`** keyword is used to distinguish the \ version and the C++ AMP version. The following code calculates the base-10 logarithm, using the fast method, of each value that is in the compute domain. - -```cpp -#include -#include -#include -using namespace concurrency; - -void MathExample() { - - double numbers[] = { 1.0, 10.0, 60.0, 100.0, 600.0, 1000.0 }; - array_view logs(6, numbers); - - parallel_for_each( - logs.extent, - [=] (index<1> idx) restrict(amp) { - logs[idx] = concurrency::fast_math::log10(numbers[idx]); - } - ); - - for (int i = 0; i < 6; i++) { - std::cout << logs[i] << "\n"; - } -} -``` - -## Graphics Library - -C++ AMP includes a graphics library that is designed for accelerated graphics programming. This library is used only on devices that support native graphics functionality. The methods are in the [Concurrency::graphics Namespace](../../parallel/amp/reference/concurrency-graphics-namespace.md) and are contained in the \ header file. The key components of the graphics library are: - -- [texture Class](../../parallel/amp/reference/texture-class.md): You can use the texture class to create textures from memory or from a file. Textures resemble arrays because they contain data, and they resemble containers in the C++ Standard Library with respect to assignment and copy construction. For more information, see [C++ Standard Library Containers](../../standard-library/stl-containers.md). The template parameters for the `texture` class are the element type and the rank. The rank can be 1, 2, or 3. The element type can be one of the short vector types that are described later in this article. - -- [writeonly_texture_view Class](../../parallel/amp/reference/writeonly-texture-view-class.md): Provides write-only access to any texture. - -- Short Vector Library: Defines a set of short vector types of length 2, 3, and 4 that are based on **`int`**, `uint`, **`float`**, **`double`**, [norm](../../parallel/amp/reference/norm-class.md), or [unorm](../../parallel/amp/reference/unorm-class.md). - -## Universal Windows Platform (UWP) Apps - -Like other C++ libraries, you can use C++ AMP in your UWP apps. These articles describe how to include C++ AMP code in apps that is created by using C++, C#, Visual Basic, or JavaScript: - -- [Using C++ AMP in UWP Apps](../../parallel/amp/using-cpp-amp-in-windows-store-apps.md) - -- [Walkthrough: Creating a basic Windows Runtime component in C++ and calling it from JavaScript](/previous-versions/windows/apps/hh755833(v=vs.140)) - -- [Bing Maps Trip Optimizer, a Window Store app in JavaScript and C++](/previous-versions/windows/apps/hh699893(v=vs.140)) - -- [How to use C++ AMP from C# using the Windows Runtime](https://devblogs.microsoft.com/pfxteam/how-to-use-c-amp-from-c-using-winrt/) - -- [How to use C++ AMP from C#](https://devblogs.microsoft.com/pfxteam/how-to-use-c-amp-from-c/) - -- [Calling Native Functions from Managed Code](../../dotnet/calling-native-functions-from-managed-code.md) - -## C++ AMP and Concurrency Visualizer - -The Concurrency Visualizer includes support for analyzing performance of C++ AMP code. These articles describe these features: - -- [GPU Activity Graph](/visualstudio/profiling/gpu-activity-graph) - -- [GPU Activity (Paging)](/visualstudio/profiling/gpu-activity-paging) - -- [GPU Activity (This Process)](/visualstudio/profiling/gpu-activity-this-process) - -- [GPU Activity (Other Processes)](/visualstudio/profiling/gpu-activity-other-processes) - -- [Channels (Threads View)](/visualstudio/profiling/channels-threads-view) - -- [Analyzing C++ AMP Code with the Concurrency Visualizer](/archive/blogs/nativeconcurrency/analyzing-c-amp-code-with-the-concurrency-visualizer) - -## Performance Recommendations - -Modulus and division of unsigned integers have significantly better performance than modulus and division of signed integers. We recommend that you use unsigned integers when possible. - -## See also - -[C++ AMP (C++ Accelerated Massive Parallelism)](../../parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md)
-[Lambda Expression Syntax](../../cpp/lambda-expression-syntax.md)
-[Reference (C++ AMP)](../../parallel/amp/reference/reference-cpp-amp.md)
-[Parallel Programming in Native Code Blog](/archive/blogs/nativeconcurrency/) diff --git a/docs/parallel/amp/graphics-cpp-amp.md b/docs/parallel/amp/graphics-cpp-amp.md deleted file mode 100644 index 1361e754631..00000000000 --- a/docs/parallel/amp/graphics-cpp-amp.md +++ /dev/null @@ -1,425 +0,0 @@ ---- -description: "Learn more about: Graphics (C++ AMP)" -title: "Graphics (C++ AMP)" -ms.date: "11/04/2016" -ms.assetid: 190a98a4-5f7d-442e-866b-b374ca74c16f ---- -# 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: - -- 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. - -## 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. - -## Short Vector Library - -The Short Vector Library provides some of the functionality of the [Vector Type](/windows/win32/direct3dhlsl/dx-graphics-hlsl-vector) that's defined in HLSL and is typically used to define texels. A short vector is a data structure that holds one to four values of the same type. The supported types are **`double`**, **`float`**, **`int`**, `norm`, `uint`, and `unorm`. The type names are shown in the following table. For each type, there is also a corresponding **`typedef`** that doesn't have an underscore in the name. The types that have the underscores are in the [Concurrency::graphics Namespace](../../parallel/amp/reference/concurrency-graphics-namespace.md). The types that don't have the underscores are in the [Concurrency::graphics::direct3d Namespace](../../parallel/amp/reference/concurrency-graphics-direct3d-namespace.md) so that they are clearly separated from the similarly-named fundamental types such as **`__int8`** and **`__int16`**. - -|Type|Length 2|Length 3|Length 4| -|-|--------------|--------------|--------------| -|double|double_2

double2|double_3

double3|double_4

double4| -|float|float_2

float2|float_3

float3|float_4

float4| -|int|int_2

int2|int_3

int3|int_4

int4| -|norm|norm_2

norm2|norm_3

norm3|norm_4

norm4| -|uint|uint_2

uint2|uint_3

uint3|uint_4

uint4| -|unorm|unorm_2

unorm2|unorm_3

unorm3|unorm_4

unorm4| - -### Operators - -If an operator is defined between two short vectors, then it is also defined between a short vector and a scalar. Also, one of these must be true: - -- The scalar's type must be the same as the short vector's element type. - -- The scalar's type can be implicitly converted to the vector's element type by using only one user-defined conversion. - -The operation is carried component-wise between each component of the short vector and the scalar. Here are the valid operators: - -|Operator type|Valid types| -|-------------------|-----------------| -|Binary operators|Valid on all types: `+`, `-`, `*`, `/`,

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

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

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

Both prefix and postfix are valid.| -|Bitwise NOT operator (`~`)|Valid on integer types.| -|Unary `-` operator|Valid on all types except `unorm` and `uint`.| - -### Swizzling Expressions - -The Short Vector Library supports the `vector_type.identifier` accessor construct to access the components of a short vector. The `identifier`, which is known as a *swizzling expression*, specifies the components of the vector. The expression can be an l-value or an r-value. Individual characters in the identifier may be: x, y, z, and w; or r, g, b, and a. "x" and "r" mean the zero-th component, "y" and "g" mean the first component, and so on. (Notice that "x" and "r" cannot be used in the same identifier.) Therefore, "rgba" and "xyzw" return the same result. Single-component accessors such as "x" and "y" are scalar value types. Multi-component accessors are short vector types. For example, if you construct an `int_4` vector that's named `fourInts` and has the values 2, 4, 6, and 8, then `fourInts.y` returns the integer 4 and `fourInts.rg` returns an `int_2` object that has the values 2 and 4. - -## 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: - -- An **`int`**, `uint`, **`float`**, **`double`**, `norm`, or `unorm` scalar. - -- A short vector that has two or four components. The only exception is `double_4`, which is not allowed. - -The `texture` object can have a rank of 1, 2, or 3. The `texture` object can be captured only by reference in the lambda of a call to `parallel_for_each`. The texture is stored on the GPU as Direct3D texture objects. For more information about textures and texels in Direct3D, see [Introduction to Textures in Direct3D 11](/windows/win32/direct3d11/overviews-direct3d-11-resources-textures-intro). - -The texel type you use might be one of the many texture formats that are used in graphics programming. For example, an RGBA format could use 32 bits, with 8 bits each for the R, G, B, and A scalar elements. The texture hardware of a graphics card can access the individual elements based on the format. For example, if you are using the RGBA format, the texture hardware can extract each 8-bit element into a 32-bit form. In C++ AMP, you can set the bits per scalar element of your texel so that you can automatically access the individual scalar elements in the code without using bit-shifting. - -### Instantiating Texture Objects - -You can declare a texture object without initialization. The following code example declares several texture objects. - -```cpp -#include -#include -using namespace concurrency; -using namespace concurrency::graphics; - -void declareTextures() { - // Create a 16-texel texture of int. - texture intTexture1(16); - texture intTexture2(extent<1>(16)); - - // Create a 16 x 32 texture of float_2. - texture floatTexture1(16, 32); - texture floatTexture2(extent<2>(16, 32)); - - // Create a 2 x 4 x 8 texture of uint_4. - texture uintTexture1(2, 4, 8); - texture uintTexture2(extent<3>(2, 4, 8)); -} -``` - -You can also use a constructor to declare and initialize a `texture` object. The following code example instantiates a `texture` object from a vector of `float_4` objects. The bits per scalar element is set to the default. You cannot use this constructor with `norm`, `unorm`, or the short vectors of `norm` and `unorm`, because they do not have a default bits per scalar element. - -```cpp -#include -#include -#include -using namespace concurrency; -using namespace concurrency::graphics; - -void initializeTexture() { - std::vector texels; - for (int i = 0; i < 768 * 1024; i++) { - int_4 i4(i, i, i, i); - texels.push_back(i4); - } - - texture aTexture(768, 1024, texels.begin(), texels.end()); -} -``` - -You can also declare and initialize a `texture` object by using a constructor overload that takes a pointer to the source data, the size of source data in bytes, and the bits per scalar element. - -```cpp -void createTextureWithBPC() { // Create the source data. - float source[1024* 2]; - for (int i = 0; i <1024* 2; i++) { - source[i] = (float)i; - } - // Initialize the texture by using the size of source in bytes // and bits per scalar element. - texture floatTexture(1024, source, (unsigned int)sizeof(source), 32U); -} -``` - -The textures in these examples are created on the default view of the default accelerator. You can use other overloads of the constructor if you want to specify an `accelerator_view` object. You cannot create a texture object on a CPU accelerator. - -There are limits on the size of each dimension of the `texture` object, as shown in the following table. A run-time error is generated if you exceed the limits. - -|Texture|Size limitation per dimension| -|-------------|---------------------| -|texture\|16384| -|texture\|16384| -|texture\|2048| - -### 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\[\]`. - -```cpp -void readTexture() { - std::vector src; - for (int i = 0; i <16 *32; i++) { - int_2 i2(i, i); - - src.push_back(i2); - } - - std::vector dst(16* 32); - - array_view arr(16, 32, dst); - - arr.discard_data(); - - const texture tex9(16, 32, src.begin(), src.end()); - - parallel_for_each(tex9.extent, [=, &tex9] (index<2> idx) restrict(amp) { // Use the subscript operator. - arr[idx].x += tex9[idx].x; // Use the function () operator. - arr[idx].x += tex9(idx).x; // Use the get method. - arr[idx].y += tex9.get(idx).y; // Use the function () operator. - arr[idx].y += tex9(idx[0], idx[1]).y; - }); - - arr.synchronize(); -} -``` - -The following code example demonstrates how to store texture channels in a short vector, and then access the individual scalar elements as properties of the short vector. - -```cpp -void UseBitsPerScalarElement() { // Create the image data. // Each unsigned int (32-bit) represents four 8-bit scalar elements(r,g,b,a values). - const int image_height = 16; - const int image_width = 16; - std::vector image(image_height* image_width); - - extent<2> image_extent(image_height, image_width); - - // By using uint_4 and 8 bits per channel, each 8-bit channel in the data source is // stored in one 32-bit component of a uint_4. - texture image_texture(image_extent, image.data(), image_extent.size()* 4U, 8U); - - // Use can access the RGBA values of the source data by using swizzling expressions of the uint_4. - parallel_for_each(image_extent, - [&image_texture](index<2> idx) restrict(amp) - { // 4 bytes are automatically extracted when reading. - uint_4 color = image_texture[idx]; - unsigned int r = color.r; - unsigned int g = color.g; - unsigned int b = color.b; - unsigned int a = color.a; - }); -} -``` - -The following table lists the valid bits per channel for each sort vector type. - -|Texture data type|Valid bits per scalar element| -|-----------------------|-----------------------------------| -|int, int_2, int_4

uint, uint_2, uint_4|8, 16, 32| -|int_3, uint_3|32| -|float, float_2, float_4|16, 32| -|float_3|32| -|double, double_2|64| -|norm, norm_2, norm_4

unorm, unorm_2, unorm, 4|8, 16| - -### Writing to Texture Objects - -Use the [texture::set](reference/texture-class.md#set) method to write to `texture` objects. A texture object can be readonly or read/write. For a texture object to be readable and writeable, the following conditions must be true: - -- T has only one scalar component. (Short vectors are not allowed.) - -- T is not **`double`**, `norm`, or `unorm`. - -- The `texture::bits_per_scalar_element` property is 32. - -If all three are not true, then the `texture` object is readonly. The first two conditions are checked during compilation. A compilation error is generated if you have code that tries to write to a `readonly` texture object. The condition for `texture::bits_per_scalar_element` is detected at run time, and the runtime generates the [unsupported_feature](../../parallel/amp/reference/unsupported-feature-class.md) exception if you try to write to a readonly `texture` object. - -The following code example writes values to a texture object. - -```cpp -void writeTexture() { - texture tex1(16); - - parallel_for_each(tex1.extent, [&tex1] (index<1> idx) restrict(amp) { - tex1.set(idx, 0); - }); -} -``` - -### Copying Texture Objects - -You can copy between texture objects by using the [copy](reference/concurrency-namespace-functions-amp.md#copy) function or the [copy_async](reference/concurrency-namespace-functions-amp.md#copy_async) function, as shown in the following code example. - -```cpp -void copyHostArrayToTexture() { // Copy from source array to texture object by using the copy function. - float floatSource[1024* 2]; - for (int i = 0; i <1024* 2; i++) { - floatSource[i] = (float)i; - } - texture floatTexture(1024); - - copy(floatSource, (unsigned int)sizeof(floatSource), floatTexture); - - // Copy from source array to texture object by using the copy function. - char charSource[16* 16]; - for (int i = 0; i <16* 16; i++) { - charSource[i] = (char)i; - } - texture charTexture(16, 16, 8U); - - copy(charSource, (unsigned int)sizeof(charSource), charTexture); - // Copy from texture object to source array by using the copy function. - copy(charTexture, charSource, (unsigned int)sizeof(charSource)); -} -``` - -You can also copy from one texture to another by using the [texture::copy_to](reference/texture-class.md#copy_to) method. The two textures can be on different accelerator_views. When you copy to a `writeonly_texture_view` object, the data is copied to the underlying `texture` object. The bits per scalar element and the extent must be the same on the source and destination `texture` objects. If those requirements are not met, the runtime throws an exception. - -## Texture View Classes - -C++ AMP introduces the [texture_view Class](../../parallel/amp/reference/texture-view-class.md) in Visual Studio 2013. Texture views support the same texel types and ranks as the [texture Class](../../parallel/amp/reference/texture-class.md), but unlike textures, they provide access to additional hardware features such as texture sampling and mipmaps. Texture views support read-only, write-only, and read-write access to the underlying texture data. - -- Read-only access is provided by the `texture_view` template specialization, which supports elements that have 1, 2, or 4 components, texture sampling, and dynamic access to a range of mipmap levels that are determined when the view is instantiated. - -- Write-only access is provided by the non-specialized template class `texture_view`, which supports elements that have either 2 or 4 components and can access one mipmap level that's determined when the view is instantiated. It does not support sampling. - -- Read-write access is provided by the non-specialized template class `texture_view`, which, like textures, supports elements that have only one component; the view can access one mipmap level that's determined when it is instantiated. It does not support sampling. - -Texture views are analogous to array views, but do not provide the automatic data management and movement functionality that the [array_view Class](../../parallel/amp/reference/array-view-class.md) provides over the [array class](../../parallel/amp/reference/array-class.md). A `texture_view` can only be accessed on the accelerator view where the underlying texture data resides. - -### writeonly_texture_view Deprecated - -For Visual Studio 2013, C++ AMP introduces better support for hardware texture features such as sampling and mipmaps, which could not be supported by the [writeonly_texture_view Class](../../parallel/amp/reference/writeonly-texture-view-class.md). The newly introduced `texture_view` class supports a superset of the functionality in `writeonly_texture_view`; as a result, `writeonly_texture_view` is deprecated. - -We recommend—at least for new code—that you use `texture_view` to access functionality that was formerly provided by `writeonly_texture_view`. Compare the following two code examples that write to a texture object that has two components (int_2). Notice that in both cases, the view, `wo_tv4`, must be captured by value in the lambda expression. Here is the example that uses the new `texture_view` class: - -```cpp -void write2ComponentTexture() { - texture tex4(16); - - texture_view wo_tv4(tex4); - - parallel_for_each(extent<1>(16), [=] (index<1> idx) restrict(amp) { - wo_tv4.set(idx, int_2(1, 1)); - }); -} -``` - -And here is the deprecated `writeonly_texture_view` class: - -```cpp -void write2ComponentTexture() { - texture tex4(16); - - writeonly_texture_view wo_tv4(tex4); - - parallel_for_each(extent<1>(16), [=] (index<1> idx) restrict(amp) { - wo_tv4.set(idx, int_2(1, 1)); - }); -} -``` - -As you can see, the two code examples are nearly identical when all you are doing is writing to the primary mipmap level. If you used `writeonly_texture_view` in existing code and you're not planning to enhance that code, you don't have to change it. However, if you're thinking about bringing that code forward, we suggest that you rewrite it to use `texture_view` because the enhancements in it support new hardware texture features. Read on for more information about these new capabilities. - -For more information about the deprecation of `writeonly_texture_view`, see [Overview of the Texture View Design in C++ AMP](/archive/blogs/nativeconcurrency/overview-of-the-texture-view-design-in-c-amp) on the Parallel Programming in Native Code blog. - -### Instantiating Texture View Objects - -Declaring a `texture_view` is similar to declaring an `array_view` that's associated with an **array**. The following code example declares several `texture` objects and `texture_view` objects that are associated with them. - -```cpp -#include -#include -using namespace concurrency; -using namespace concurrency::graphics; - -void declareTextureViews() -{ - // Create a 16-texel texture of int, with associated texture_views. - texture intTexture(16); - texture_view intTextureViewRO(intTexture); // read-only - texture_view intTextureViewRW(intTexture); // read-write - - // Create a 16 x 32 texture of float_2, with associated texture_views. - texture floatTexture(16, 32); - texture_view floatTextureViewRO(floatTexture); // read-only - texture_view floatTextureViewRO(floatTexture); // write-only - - // Create a 2 x 4 x 8 texture of uint_4, with associated texture_views. - texture uintTexture(2, 4, 8); - texture_view uintTextureViewRO(uintTexture); // read-only - texture_view uintTextureViewWO(uintTexture); // write-only -} -``` - -Notice how a texture view whose element type is non-const and has one component is read-write, but a texture view whose element type is non-const but has more than one componenent are write-only. Texture views of const element types are always read-only, but if the element type is non-const, then the number of components in the element determines whether it is read-write (1 component) or write-only (multiple components). - -The element type of a `texture_view`—its const-ness and also the number of components it has—also plays a role in determining whether the view supports texture sampling, and how mipmap levels can be accessed: - -|Type|Components|Read|Write|Sampling|Mipmap access| -|----------|----------------|----------|-----------|--------------|-------------------| -|texture_view\|1, 2, 4|Yes|No (1)|Yes|Yes, indexable. Range is determined at instantiation.| -|Texture_view\|1

2, 4|Yes

No (2)|Yes

Yes|No (1)

No (1)|Yes, one level. Level is determined at instantiation.

Yes, one level. Level is determined at instantiation.| - -From this table, you can see that read-only texture views fully support the new capabilities in exchange for not being able to write to the view. Writable texture views are limited in that they can only access one mipmap level. Read-write texture views are even more specialized than writable ones, because they add the requirement that the element type of the texture view has only one component. Notice that sampling is not supported for writable texture views because it's a read-oriented operation. - -### Reading from Texture View Objects - -Reading unsampled texture data through a texture view is just like reading it from the texture itself, except that textures are captured by reference, whereas texture views are captured by value. The following two code examples demonstrate; first, by using `texture` only: - -```cpp -void write2ComponentTexture() { - texture text_data(16); - - parallel_for_each(extent<1>(16), [&] (index<1> idx) restrict(amp) { - tex_data.set(idx, int_2(1, 1)); - }); -} -``` - -And here is the same example, except it now uses the `texture_view` class: - -```cpp -void write2ComponentTexture() { - texture tex_data(16); - - texture_view tex_view(tex_data); - - parallel_for_each(extent<1>(16), [=] (index<1> idx) restrict(amp) { - tex_view.set(idx, int_2(1, 1)); - }); -} -``` - -Texture views whose elements are based on floating-point types—for example, float, float_2, or float_4—can also be read by using texture sampling to take advantage of hardware support for various filtering modes and addressing modes. C++ AMP supports the two filtering modes that are most common in compute scenarios—point-filtering (nearest-neighbor) and linear-filtering (weighted average)—and four addressing modes—wrapped, mirrored, clamped, and border. For more information about addressing modes, see [address_mode Enumeration](reference/concurrency-graphics-namespace-enums.md#address_mode). - -In addition to modes that C++ AMP supports directly, you can access other filtering modes and addressing modes of the underlying platform by using the interop APIs to adopt a texture sampler that was created by using the platform APIs directly. For example, Direct3D supports other filtering modes such as anisotropic filtering, and can apply a different addressing mode to each dimension of a texture. You could create a texture sampler whose coordinates are wrapped vertically, mirrored horizontally, and sampled with anisotropic filtering by using the Direct3D APIs, and then leverage the sampler in your C++ AMP code by using the `make_sampler` interop API. For more information see [Texture Sampling in C++ AMP](/archive/blogs/nativeconcurrency/texture-sampling-in-c-amp) on the Parallel Programming in Native Code blog. - -Texture views also support the reading of mipmaps. Read-only texture views (those that have a const element type) offer the most flexibility because a range of mip-levels that is determined at instantiation can be dynamically sampled, and because elements that have 1, 2, or 4 components are supported. Read-write texture views that have elements that have one component also support mipmaps, but only of a level that's determined at instantiation. For more information, see [Texture with Mipmaps](/archive/blogs/nativeconcurrency/texture-with-mipmaps) on the Parallel Programming in Native Code blog. - -### Writing to Texture View Objects - -Use the [texture_view::get Method](reference/texture-view-class.md#get) to write to the underlying `texture` through the `texture_view` object. A texture view can be read-only, read-write, or write-only. For a texture view to be writable it must have an element type that is non-const; for a texture view to be readable and writable, its element type must also have only one component. Otherwise, the texture view is read-only. You can only access one mipmap level of a texture at a time through a texture view, and the level is specified when the view is instantiated. - -This example shows how to write to the second-most detailed mipmap level of a texture that has 4 mipmap levels. The most detailed mipmap level is level 0. - -```cpp -// Create a texture that has 4 mipmap levels : 16x16, 8x8, 4x4, 2x2 -texture tex(extent<2>(16, 16), 16U, 4); - -// Create a writable texture view to the second mipmap level :4x4 -texture_view w_view(tex, 1); - -parallel_for_each(w_view.extent, [=](index<2> idx) restrict(amp) -{ - w_view.set(idx, 123); -}); -``` - -## Interoperability - -The C++ AMP runtime supports interoperability between `texture` and the [ID3D11Texture1D interface](/windows/win32/api/d3d11/nn-d3d11-id3d11texture1d), between `texture` and the [ID3D11Texture2D interface](/windows/win32/api/d3d11/nn-d3d11-id3d11texture2d), and between `texture` and the [ID3D11Texture3D interface](/windows/win32/api/d3d11/nn-d3d11-id3d11texture3d). The [get_texture](reference/concurrency-graphics-direct3d-namespace-functions.md#get_texture) method takes a `texture` object and returns an `IUnknown` interface. The [make_texture](reference/concurrency-graphics-direct3d-namespace-functions.md#make_texture) method takes an `IUnknown` interface and an `accelerator_view` object and returns a `texture` object. - -## See also - -[double_2 Class](../../parallel/amp/reference/double-2-class.md)
-[double_3 Class](../../parallel/amp/reference/double-3-class.md)
-[double_4 Class](../../parallel/amp/reference/double-4-class.md)
-[float_2 Class](../../parallel/amp/reference/float-2-class.md)
-[float_3 Class](../../parallel/amp/reference/float-3-class.md)
-[float_4 Class](../../parallel/amp/reference/float-4-class.md)
-[int_2 Class](../../parallel/amp/reference/int-2-class.md)
-[int_3 Class](../../parallel/amp/reference/int-3-class.md)
-[int_4 Class](../../parallel/amp/reference/int-4-class.md)
-[norm_2 Class](../../parallel/amp/reference/norm-2-class.md)
-[norm_3 Class](../../parallel/amp/reference/norm-3-class.md)
-[norm_4 Class](../../parallel/amp/reference/norm-4-class.md)
-[short_vector Structure](../../parallel/amp/reference/short-vector-structure.md)
-[short_vector_traits Structure](../../parallel/amp/reference/short-vector-traits-structure.md)
-[uint_2 Class](../../parallel/amp/reference/uint-2-class.md)
-[uint_3 Class](../../parallel/amp/reference/uint-3-class.md)
-[uint_4 Class](../../parallel/amp/reference/uint-4-class.md)
-[unorm_2 Class](../../parallel/amp/reference/unorm-2-class.md)
-[unorm_3 Class](../../parallel/amp/reference/unorm-3-class.md)
-[unorm_4 Class](../../parallel/amp/reference/unorm-4-class.md) diff --git a/docs/parallel/amp/media/campc.PNG b/docs/parallel/amp/media/campc.PNG deleted file mode 100644 index adbcadddb1a..00000000000 Binary files a/docs/parallel/amp/media/campc.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campcpubreakpoints.png b/docs/parallel/amp/media/campcpubreakpoints.png deleted file mode 100644 index 44d1da5977a..00000000000 Binary files a/docs/parallel/amp/media/campcpubreakpoints.png and /dev/null differ diff --git a/docs/parallel/amp/media/campd.png b/docs/parallel/amp/media/campd.png deleted file mode 100644 index 2ea0f0cd8a9..00000000000 Binary files a/docs/parallel/amp/media/campd.png and /dev/null differ diff --git a/docs/parallel/amp/media/campe.png b/docs/parallel/amp/media/campe.png deleted file mode 100644 index 681bd4cc9ee..00000000000 Binary files a/docs/parallel/amp/media/campe.png and /dev/null differ diff --git a/docs/parallel/amp/media/campf.PNG b/docs/parallel/amp/media/campf.PNG deleted file mode 100644 index 627b78deb1d..00000000000 Binary files a/docs/parallel/amp/media/campf.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campg.PNG b/docs/parallel/amp/media/campg.PNG deleted file mode 100644 index 181d786a7b7..00000000000 Binary files a/docs/parallel/amp/media/campg.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campgpubreakpoints.png b/docs/parallel/amp/media/campgpubreakpoints.png deleted file mode 100644 index c3195246a9d..00000000000 Binary files a/docs/parallel/amp/media/campgpubreakpoints.png and /dev/null differ diff --git a/docs/parallel/amp/media/camph.png b/docs/parallel/amp/media/camph.png deleted file mode 100644 index 2688ccc2267..00000000000 Binary files a/docs/parallel/amp/media/camph.png and /dev/null differ diff --git a/docs/parallel/amp/media/campk.PNG b/docs/parallel/amp/media/campk.PNG deleted file mode 100644 index c4d12b983fd..00000000000 Binary files a/docs/parallel/amp/media/campk.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campl.PNG b/docs/parallel/amp/media/campl.PNG deleted file mode 100644 index aa55a8b92d1..00000000000 Binary files a/docs/parallel/amp/media/campl.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixanontiled.PNG b/docs/parallel/amp/media/campmatrixanontiled.PNG deleted file mode 100644 index 9d614e60639..00000000000 Binary files a/docs/parallel/amp/media/campmatrixanontiled.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixapartitioned.PNG b/docs/parallel/amp/media/campmatrixapartitioned.PNG deleted file mode 100644 index c7ea08435eb..00000000000 Binary files a/docs/parallel/amp/media/campmatrixapartitioned.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixatiled.PNG b/docs/parallel/amp/media/campmatrixatiled.PNG deleted file mode 100644 index 7e0e1fc8896..00000000000 Binary files a/docs/parallel/amp/media/campmatrixatiled.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixbnontiled.PNG b/docs/parallel/amp/media/campmatrixbnontiled.PNG deleted file mode 100644 index 2c7633e1787..00000000000 Binary files a/docs/parallel/amp/media/campmatrixbnontiled.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixbpartitioned.PNG b/docs/parallel/amp/media/campmatrixbpartitioned.PNG deleted file mode 100644 index 9e345d153e2..00000000000 Binary files a/docs/parallel/amp/media/campmatrixbpartitioned.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixbtiled.PNG b/docs/parallel/amp/media/campmatrixbtiled.PNG deleted file mode 100644 index a9a12d72da1..00000000000 Binary files a/docs/parallel/amp/media/campmatrixbtiled.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixproductnontiled.PNG b/docs/parallel/amp/media/campmatrixproductnontiled.PNG deleted file mode 100644 index 8632cfec780..00000000000 Binary files a/docs/parallel/amp/media/campmatrixproductnontiled.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixproductpartitioned.PNG b/docs/parallel/amp/media/campmatrixproductpartitioned.PNG deleted file mode 100644 index 82b5f65cba4..00000000000 Binary files a/docs/parallel/amp/media/campmatrixproductpartitioned.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/campmatrixproducttiled.PNG b/docs/parallel/amp/media/campmatrixproducttiled.PNG deleted file mode 100644 index 4339e6523f4..00000000000 Binary files a/docs/parallel/amp/media/campmatrixproducttiled.PNG and /dev/null differ diff --git a/docs/parallel/amp/media/camptiledgridexample.png b/docs/parallel/amp/media/camptiledgridexample.png deleted file mode 100644 index 8a82b2c08f9..00000000000 Binary files a/docs/parallel/amp/media/camptiledgridexample.png and /dev/null differ diff --git a/docs/parallel/amp/media/usingtilesmatrix.PNG b/docs/parallel/amp/media/usingtilesmatrix.PNG deleted file mode 100644 index 0175a433a18..00000000000 Binary files a/docs/parallel/amp/media/usingtilesmatrix.PNG and /dev/null differ diff --git a/docs/parallel/amp/reference/accelerator-class.md b/docs/parallel/amp/reference/accelerator-class.md deleted file mode 100644 index 02b879fba94..00000000000 --- a/docs/parallel/amp/reference/accelerator-class.md +++ /dev/null @@ -1,525 +0,0 @@ ---- -description: "Learn more about: accelerator Class" -title: "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 - -An accelerator is a hardware capability that is optimized for data-parallel computing. An accelerator may be a device attached to a PCIe bus (such as a GPU), or it might be an extended instruction set on the main CPU. - -## Syntax - -```cpp -class accelerator; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[accelerator Constructor](#ctor)|Initializes a new instance of the `accelerator` class.| -|[~accelerator Destructor](#ctor)|Destroys the `accelerator` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[create_view](#create_view)|Creates and returns an `accelerator_view` object on this accelerator.| -|[get_all](#get_all)|Returns a vector of `accelerator` objects that represent all the available accelerators.| -|[get_auto_selection_view](#get_auto_selection_view)|Returns the auto-selection `accelerator_view`.| -|[get_dedicated_memory](#get_dedicated_memory)|Returns the dedicated memory for the `accelerator`, in kilobytes.| -|[get_default_cpu_access_type](#get_default_cpu_access_type)|Returns the default [access_type](concurrency-namespace-enums-amp.md#access_type) for buffers created on this accelerator.| -|[get_default_view](#get_default_view)|Returns the default `accelerator_view` object that is associated with the `accelerator`.| -|[get_description](#get_description)|Returns a short description of the `accelerator` device.| -|[get_device_path](#get_device_path)|Returns the path of the device.| -|[get_has_display](#get_has_display)|Determines whether the `accelerator` is attached to a display.| -|[get_is_debug](#get_is_debug)|Determines whether the `accelerator` has the DEBUG layer enabled for extensive error reporting.| -|[get_is_emulated](#get_is_emulated)|Determines whether the `accelerator` is emulated.| -|[get_supports_cpu_shared_memory](#get_supports_cpu_shared_memory)|Determines whether the `accelerator` supports shared memory| -|[get_supports_double_precision](#get_supports_double_precision)|Determines whether the `accelerator` is attached to a display.| -|[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`.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator!=](#operator_neq)|Compares this `accelerator` object with another and returns **`false`** if they are the same; otherwise, returns **`true`**.| -|[operator=](#operator_eq)|Copies the contents of the specified `accelerator` object to this one.| -|[operator==](#operator_eq_eq)|Compares this `accelerator` object with another and returns **`true`** if they are the same; otherwise, returns **`false`**.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[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_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.| -|[direct3d_ref](#direct3d_ref)|Gets a string constant for a Direct3D reference `accelerator`.| -|[direct3d_warp](#direct3d_warp)|Gets the string constant for an `accelerator` object that you can use for executing C++ AMP code on multi-core CPUs that use Streaming SIMD Extensions (SSE).| -|[has_display](#has_display)|Gets a Boolean value that indicates whether the `accelerator` is attached to a display.| -|[is_debug](#is_debug)|Indicates whether the `accelerator` has the DEBUG layer enabled for extensive error reporting.| -|[is_emulated](#is_emulated)|Indicates whether the `accelerator` is emulated.| -|[supports_cpu_shared_memory](#supports_cpu_shared_memory)|Indicates whether the `accelerator` supports shared memory.| -|[supports_double_precision](#supports_double_precision)|Indicates whether the accelerator supports double-precision math.| -|[supports_limited_double_precision](#supports_limited_double_precision)|Indicates whether the accelerator has limited support for double-precision math.| -|[version](#version)|Gets the version of the `accelerator`.| - -## Inheritance Hierarchy - -`accelerator` - -## Remarks - -An accelerator is a hardware capability that is optimized for data-parallel computing. An accelerator is often a discrete GPU, but it can also be a virtual host-side entity such as a DirectX REF device, a WARP (a CPU-side device that is accelerated by means of SSE instructions), or the CPU itself. - -You can construct an `accelerator` object by enumerating the available devices, or by getting the default device, the reference device, or the WARP device. - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## ~accelerator - -Destroys the `accelerator` object. - -```cpp -~accelerator(); -``` - -### Return Value - -## accelerator - -Initializes a new instance of the [accelerator class](accelerator-class.md). - -```cpp -accelerator(); - -explicit accelerator(const std::wstring& _Device_path); - -accelerator(const accelerator& _Other); -``` - -### Parameters - -*_Device_path*
-The path of the physical device. - -*_Other*
-The accelerator to copy. - -## cpu_accelerator - -Gets a string constant for the CPU accelerator. - -```cpp -static const wchar_t cpu_accelerator[]; -``` - -## create_view - -Creates and returns an `accelerator_view` object on this accelerator, using the specified queuing mode. When the queuing mode is not specified, the new `accelerator_view` uses the [queuing_mode::immediate](concurrency-namespace-enums-amp.md#queuing_mode) queuing mode. - -```cpp -accelerator_view create_view(queuing_mode qmode = queuing_mode_automatic); -``` - -### Parameters - -*qmode*
-The queuing mode. - -### Return Value - -A new `accelerator_view` object on this accelerator, using the specified queuing mode. - -## dedicated_memory - -Gets the dedicated memory for the `accelerator`, in kilobytes. - -```cpp -__declspec(property(get= get_dedicated_memory)) size_t dedicated_memory; -``` - -## default_accelerator - -Gets a string constant for the default `accelerator`. - -```cpp -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`. - -```cpp -__declspec(property(get= get_default_cpu_access_type)) access_type default_cpu_access_type; -``` - -## default_view - -Gets the default accelerator view that is associated with the `accelerator`. - -```cpp -__declspec(property(get= get_default_view)) accelerator_view default_view; -``` - -## description - -Gets a short description of the `accelerator` device. - -```cpp -__declspec(property(get= get_description)) std::wstring description; -``` - -## device_path - -Gets the path of the accelerator. The path is unique on the system. - -```cpp -__declspec(property(get= get_device_path)) std::wstring device_path; -``` - -## direct3d_ref - -Gets a string constant for a Direct3D reference accelerator. - -```cpp -static const wchar_t direct3d_ref[]; -``` - -## direct3d_warp - -Gets the string constant for an `accelerator` object that you can use for executing your C++ AMP code on multi-core CPUs using Streaming SIMD Extensions (SSE). - -```cpp -static const wchar_t direct3d_warp[]; -``` - -## get_all - -Returns a vector of `accelerator` objects that represent all the available accelerators. - -```cpp -static inline std::vector get_all(); -``` - -### Return Value - -The vector of available accelerators - -## get_auto_selection_view - -Returns the auto selection accelerator_view, which when specified as the parallel_for_each target results in the target accelerator_view for executing the parallel_for_each kernel to be automatically selected by the runtime. For all other purposes, the accelerator_view returned by this method is the same as the default accelerator_view of the default accelerator - -```cpp -static accelerator_view __cdecl get_auto_selection_view(); -``` - -### Return Value - -The auto selection accelerator_view. - -## get_dedicated_memory - -Returns the dedicated memory for the `accelerator`, in kilobytes. - -```cpp -size_t get_dedicated_memory() const; -``` - -### Return Value - -The dedicated memory for the `accelerator`, in kilobytes. - -## get_default_cpu_access_type - -Gets the default cpu access_type for buffers created on this accelerator - -```cpp -access_type get_default_cpu_access_type() const; -``` - -### Return Value - -The default cpu access_type for buffers created on this accelerator. - -## get_default_view - -Returns the default `accelerator_view` object that is associated with the `accelerator`. - -```cpp -accelerator_view get_default_view() const; -``` - -### Return Value - -The default `accelerator_view` object that is associated with the `accelerator`. - -## get_description - -Returns a short description of the `accelerator` device. - -```cpp -std::wstring get_description() const; -``` - -### Return Value - -A short description of the `accelerator` device. - -## get_device_path - -Returns the path of the accelerator. The path is unique on the system. - -```cpp -std::wstring get_device_path() const; -``` - -### Return Value - -The system-wide unique device instance path. - -## get_has_display - -Returns a Boolean value that indicates whether the `accelerator` can output to a display. - -```cpp -bool get_has_display() const; -``` - -### Return Value - -**`true`** if the `accelerator` can output to a display; otherwise, **`false`**. - -## get_is_debug - -Determines whether the `accelerator` has the DEBUG layer enabled for extensive error reporting. - -```cpp -bool get_is_debug() const; -``` - -### Return Value - -**`true`** if the `accelerator` has the DEBUG layer enabled for extensive error reporting. Otherwise, **`false`**. - -## get_is_emulated - -Determines whether the `accelerator` is emulated. - -```cpp -bool get_is_emulated() const; -``` - -### Return Value - -**`true`** if the `accelerator` is emulated. Otherwise, **`false`**. - -## get_supports_cpu_shared_memory - -Returns a boolean value indicating whether the accelerator supports memory accessible both by the accelerator and the CPU. - -```cpp -bool get_supports_cpu_shared_memory() const; -``` - -### Return Value - -**`true`** if the accelerator supports CPU shared memory; otherwise, **`false`**. - -## get_supports_double_precision - -Returns a Boolean value that indicates whether the accelerator supports double precision math, including fused multiply add (FMA), division, reciprocal, and casting between **`int`** and **`double`** - -```cpp -bool get_supports_double_precision() const; -``` - -### Return Value - -**`true`** if the accelerator supports double precision math; otherwise, **`false`**. - -## get_supports_limited_double_precision - -Returns a Boolean value that indicates whether the accelerator has limited support for double precision math. If the accelerator has only limited support, then fused multiply add (FMA), division, reciprocal, and casting between **`int`** and **`double`** are not supported. - -```cpp -bool get_supports_limited_double_precision() const; -``` - -### Return Value - -**`true`** if the accelerator has limited support for double precision math; otherwise, **`false`**. - -## get_version - -Returns the version of the `accelerator`. - -```cpp -unsigned int get_version() const; -``` - -### Return Value - -The version of the `accelerator`. - -## has_display - -Gets a Boolean value that indicates whether the `accelerator` can output to a display. - -```cpp -__declspec(property(get= get_has_display)) bool has_display; -``` - -## is_debug - -Gets a Boolean value that indicates whether the `accelerator` has the DEBUG layer enabled for extensive error reporting. - -```cpp -__declspec(property(get= get_is_debug)) bool is_debug; -``` - -## is_emulated - -Gets a Boolean value that indicates whether the `accelerator` is emulated. - -```cpp -__declspec(property(get= get_is_emulated)) bool is_emulated; -``` - -## operator!= - -Compares this `accelerator` object with another and returns **`false`** if they are the same; otherwise, returns **`true`**. - -```cpp -bool operator!= (const accelerator& _Other) const; -``` - -### Parameters - -*_Other*
-The `accelerator` object to compare with this one. - -### Return Value - -**`false`** if the two `accelerator` objects are the same; otherwise, **`true`**. - -## operator= - -Copies the contents of the specified `accelerator` object to this one. - -```cpp -accelerator& operator= (const accelerator& _Other); -``` - -### Parameters - -*_Other*
-The `accelerator` object to copy from. - -### Return Value - -A reference to this `accelerator` object. - -## operator== - -Compares this `accelerator` object with another and returns **`true`** if they are the same; otherwise, returns **`false`**. - -```cpp -bool operator== (const accelerator& _Other) const; -``` - -### Parameters - -*_Other*
-The `accelerator` object to compare with this one. - -### Return Value - -**`true`** if the other `accelerator` object is same as this `accelerator` object; otherwise, **`false`**. - -## set_default - -Sets the default accelerator to be used for any operation that implicitly uses the default accelerator. This method only succeeds if the runtime selected default accelerator has not already been used in an operation that implicitly uses the default accelerator - -```cpp -static inline bool set_default(std::wstring _Path); -``` - -### Parameters - -*_Path*
-The path to the accelerator. - -### Return Value - -**`true`** if the call succeeds at setting the default accelerator. Otherwise, **`false`**. - -## set_default_cpu_access_type - -Set the default cpu access_type for arrays created on this accelerator or for implicit memory allocations as part of array_views accessed on this accelerator. This method only succeeds if the default_cpu_access_type for the accelerator has not already been overridden by a previous call to this method and the runtime selected default_cpu_access_type for this accelerator has not yet been used for allocating an array or for an implicit memory allocation backing an array_view accessed on this accelerator. - -```cpp -bool set_default_cpu_access_type(access_type _Default_cpu_access_type); -``` - -### Parameters - -*_Default_cpu_access_type*
-The default cpu access_type to be used for array/array_view memory allocations on this accelerator. - -### Return Value - -A boolean value indicating if the default cpu access_type for the accelerator was successfully set. - -## supports_cpu_shared_memory - -Gets a Boolean value indicating whether the `accelerator` supports shared memory. - -```cpp -__declspec(property(get= get_supports_cpu_shared_memory)) bool supports_cpu_shared_memory; -``` - -## supports_double_precision - -Gets a Boolean value that indicates whether the accelerator supports double precision math. - -```cpp -__declspec(property(get= get_supports_double_precision)) bool supports_double_precision; -``` - -## supports_limited_double_precision - -Gets a Boolean value that indicates whether the accelerator has limited support for double precision math. If the accelerator has only limited support, then fused multiply add (FMA), division, reciprocal, and casting between **`int`** and **`double`** are not supported. - -```cpp -__declspec(property(get= get_supports_limited_double_precision)) bool supports_limited_double_precision; -``` - -## version - -Gets the version of the `accelerator`. - -```cpp -__declspec(property(get= get_version)) unsigned int version; -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/accelerator-view-class.md b/docs/parallel/amp/reference/accelerator-view-class.md deleted file mode 100644 index 53208aae6bf..00000000000 --- a/docs/parallel/amp/reference/accelerator-view-class.md +++ /dev/null @@ -1,327 +0,0 @@ ---- -description: "Learn more about: accelerator_view Class" -title: "accelerator_view Class" -ms.date: "03/27/2019" -f1_keywords: ["accelerator_view", "AMPRT/accelerator_view", "AMPRT/Concurrency::accelerator_view::accelerator_view", "AMPRT/Concurrency::accelerator_view::create_marker", "AMPRT/Concurrency::accelerator_view::flush", "AMPRT/Concurrency::accelerator_view::get_accelerator", "AMPRT/Concurrency::accelerator_view::get_is_auto_selection", "AMPRT/Concurrency::accelerator_view::get_is_debug", "AMPRT/Concurrency::accelerator_view::get_queuing_mode", "AMPRT/Concurrency::accelerator_view::get_version", "AMPRT/Concurrency::accelerator_view::wait", "AMPRT/Concurrency::accelerator_view::accelerator", "AMPRT/Concurrency::accelerator_view::is_auto_selection", "AMPRT/Concurrency::accelerator_view::is_debug", "AMPRT/Concurrency::accelerator_view::queuing_mode", "AMPRT/Concurrency::accelerator_view::version"] -helpviewer_keywords: ["accelerator_view class"] -ms.assetid: 9f298c21-bf62-46e0-88b8-01c5c78ef144 ---- -# accelerator_view Class - -Represents a virtual device abstraction on a C++ AMP data-parallel accelerator. - -## Syntax - -```cpp -class accelerator_view; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[accelerator_view Constructor](#ctor)|Initializes a new instance of the `accelerator_view` class.| -|[~accelerator_view Destructor](#dtor)|Destroys the `accelerator_view` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[create_marker](#create_marker)|Returns a future to track the completion of all commands submitted so far to this `accelerator_view` object.| -|[flush](#flush)|Submits all pending commands queued to the `accelerator_view` object to the accelerator for execution.| -|[get_accelerator](#get_accelerator)|Returns the `accelerator` object for the `accelerator_view` object.| -|[get_is_auto_selection](#get_is_auto_selection)|Returns a Boolean value that indicates whether the runtime will automatically select an appropriate accelerator when the `accelerator_view` object is passed to a [parallel_for_each](concurrency-namespace-functions-amp.md#parallel_for_each).| -|[get_is_debug](#get_is_debug)|Returns a Boolean value that indicates whether the `accelerator_view` object has the DEBUG layer enabled for extensive error reporting.| -|[get_queuing_mode](#get_queuing_mode)|Returns the queuing mode for the `accelerator_view` object.| -|[get_version](#get_version)|Returns the version of the `accelerator_view`.| -|[wait](#wait)|Waits for all commands submitted to the `accelerator_view` object to finish.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator!=](#operator_neq)|Compares this `accelerator_view` object with another and returns **`false`** if they are the same; otherwise, returns **`true`**.| -|[operator=](#operator_eq)|Copies the contents of the specified `accelerator_view` object into this one.| -|[operator==](#operator_eq_eq)|Compares this `accelerator_view` object with another and returns **`true`** if they are the same; otherwise, returns **`false`**.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[accelerator](#accelerator)|Gets the `accelerator` object for the `accelerator_view` object.| -|[is_auto_selection](#is_auto_selection)|Gets a Boolean value that indicates whether the runtime will automatically select an appropriate accelerator when the `accelerator_view` object is passed to a [parallel_for_each](concurrency-namespace-functions-amp.md#parallel_for_each).| -|[is_debug](#is_debug)|Gets a Boolean value that indicates whether the `accelerator_view` object has the DEBUG layer enabled for extensive error reporting.| -|[queuing_mode](#queuing_mode)|Gets the queuing mode for the `accelerator_view` object.| -|[version](#version)|Gets the version of the accelerator.| - -## Inheritance Hierarchy - -`accelerator_view` - -### Remarks - -An `accelerator_view` object represents a logical, isolated view of an accelerator. A single physical compute device can have many logical, isolated `accelerator_view` objects. Each accelerator has a default `accelerator_view` object. Additional `accelerator_view` objects can be created. - -Physical devices can be shared among many client threads. Client threads can cooperatively use the same `accelerator_view` object of an accelerator, or each client can communicate with a compute device via an independent `accelerator_view` object for isolation from other client threads. - -An `accelerator_view` object can have one of two [queuing_mode Enumeration](concurrency-namespace-enums-amp.md#queuing_mode) states. If the queuing mode is `immediate`, commands like `copy` and `parallel_for_each` are sent to the corresponding accelerator device as soon as they return to the caller. If the queuing mode is `deferred`, such commands are queued up on a command queue that corresponds to the `accelerator_view` object. Commands are not actually sent to the device until `flush()` is called. - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## accelerator - -Gets the accelerator object for the accelerator_view object. - -### Syntax - -```cpp -__declspec(property(get= get_accelerator)) Concurrency::accelerator accelerator; -``` - -## accelerator_view - -Initializes a new instance of the accelerator_view class by copying an existing `accelerator_view` object. - -### Syntax - -```cpp -accelerator_view( const accelerator_view & other ); -``` - -### Parameters - -*other*
-The `accelerator_view` object to copy. - -## create_marker - -Returns a future to track the completion of all commands submitted so far to this `accelerator_view` object. - -### Syntax - -```cpp -concurrency::completion_future create_marker(); -``` - -### Return Value - -A future to track the completion of all commands submitted so far to this `accelerator_view` object. - -## flush - -Submits all pending commands queued to the accelerator_view object to the accelerator for execution. - -### Syntax - -```cpp -void flush(); -``` - -### Return Value - -Returns **`void`**. - -## get_accelerator - -Returns the accelerator object for the accelerator_view object. - -### Syntax - -```cpp -accelerator get_accelerator() const; -``` - -### Return Value - -The accelerator object for the accelerator_view object. - -## get_is_auto_selection - -Returns a Boolean value that indicates whether the runtime will automatically select an appropriate accelerator when the accelerator_view is passed to a [parallel_for_each](concurrency-namespace-functions-amp.md#parallel_for_each). - -### Syntax - -```cpp -bool get_is_auto_selection() const; -``` - -### Return Value - -**`true`** if the runtime will automatically select an appropriate accelerator; otherwise, **`false`**. - -## get_is_debug - -Returns a Boolean value that indicates whether the accelerator_view object has the DEBUG layer enabled for extensive error reporting. - -### Syntax - -```cpp -bool get_is_debug() const; -``` - -### Return Value - -A Boolean value that indicates whether the `accelerator_view` object has the DEBUG layer enabled for extensive error reporting. - -## get_queuing_mode - -Returns the queuing mode for the accelerator_view object. - -### Syntax - -```cpp -queuing_mode get_queuing_mode() const; -``` - -### Return Value - -The queuing mode for the `accelerator_view` object. - -## get_version - -Returns the version of the accelerator_view. - -### Syntax - -```cpp -unsigned int get_version() const; -``` - -### Return Value - -The version of the `accelerator_view`. - -## is_auto_selection - -Gets a Boolean value that indicates whether the runtime will automatically select an appropriate accelerator when the accelerator_view is passed to a [parallel_for_each](concurrency-namespace-functions-amp.md#parallel_for_each). - -### Syntax - -```cpp -__declspec(property(get= get_is_auto_selection)) bool is_auto_selection; -``` - -## is_debug - -Gets a Boolean value that indicates whether the accelerator_view object has the DEBUG layer enabled for extensive error reporting. - -### Syntax - -```cpp -__declspec(property(get= get_is_debug)) bool is_debug; -``` - -## operator!= - -Compares this accelerator_view object with another and returns **`false`** if they are the same; otherwise, returns **`true`**. - -### Syntax - -```cpp -bool operator!= ( const accelerator_view & other ) const; -``` - -### Parameters - -*other*
-The `accelerator_view` object to compare with this one. - -### Return Value - -**`false`** if the two objects are the same; otherwise, **`true`**. - -## operator= - -Copies the contents of the specified accelerator_view object into this one. - -### Syntax - -```cpp -accelerator_view & operator= ( const accelerator_view & other ); -``` - -### Parameters - -*other*
-The `accelerator_view` object to copy from. - -### Return Value - -A reference to the modified `accelerator_view` object. - -## operator== - -Compares this accelerator_view object with another and returns **`true`** if they are the same; otherwise, returns **`false`**. - -### Syntax - -```cpp -bool operator== ( const accelerator_view & other ) const; -``` - -### Parameters - -*other*
-The `accelerator_view` object to compare with this one. - -### Return Value - -**`true`** if the two objects are the same; otherwise, **`false`**. - -## queuing_mode - -Gets the queuing mode for the accelerator_view object. - -### Syntax - -```cpp -__declspec(property(get= get_queuing_mode)) Concurrency::queuing_mode queuing_mode; -``` - -## version - -Gets the version of the accelerator_view. - -### Syntax - -```cpp -__declspec(property(get= get_version)) unsigned int version; -``` - -## wait - -Waits for all commands submitted to the accelerator_view object to finish. - -### Syntax - -```cpp -void wait(); -``` - -### Return Value - -Returns **`void`**. - -### Remarks - -If the [queuing_mode](concurrency-namespace-enums-amp.md#queuing_mode) is `immediate`, this method returns immediately without blocking. - -## ~accelerator_view - -Destroys the accelerator_view object. - -### Syntax - -```cpp -~accelerator_view(); -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/accelerator-view-removed-class.md b/docs/parallel/amp/reference/accelerator-view-removed-class.md deleted file mode 100644 index f5487950ff2..00000000000 --- a/docs/parallel/amp/reference/accelerator-view-removed-class.md +++ /dev/null @@ -1,86 +0,0 @@ ---- -description: "Learn more about: accelerator_view_removed Class" -title: "accelerator_view_removed Class" -ms.date: "03/27/2019" -f1_keywords: ["accelerator_view_removed", "AMPRT/accelerator_view_removed", "AMPRT/Concurrency::accelerator_view_removed::accelerator_view_removed", "AMPRT/Concurrency::accelerator_view_removed::get_view_removed_reason"] -helpviewer_keywords: ["AMPRT/Concurrency::accelerator_view_removed::accelerator_view_removed Class"] -ms.assetid: 262446de-311c-454e-a5ed-e2aaced0d88a ---- -# accelerator_view_removed Class - -The exception that is thrown when an underlying DirectX call fails due to the Windows timeout detection and recovery mechanism. - -## Syntax - -```cpp -class accelerator_view_removed : public runtime_exception; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[accelerator_view_removed Constructor](#ctor)|Initializes a new instance of the `accelerator_view_removed` class.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[get_view_removed_reason](#get_view_removed_reason)|Returns an HRESULT error code indicating the cause of the `accelerator_view` object's removal.| - -## Inheritance Hierarchy - -`exception` - -`runtime_exception` - -`out_of_memory` - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## accelerator_view_removed - -Initializes a new instance of the [accelerator_view_removed](accelerator-view-removed-class.md) class. - -### Syntax - -```cpp -explicit accelerator_view_removed( - const char * message, - HRESULT view_removed_reason ) throw(); - -explicit accelerator_view_removed( - HRESULT view_removed_reason ) throw(); -``` - -### Parameters - -*message*
-A description of the error. - -*view_removed_reason*
-An HRESULT error code indicating the cause of removal of the `accelerator_view` object. - -### Return Value - -A new instance of the `accelerator_view_removed` class. - -## get_view_removed_reason - -Returns an HRESULT error code indicating the cause of the `accelerator_view` object's removal. - -### Syntax - -```cpp -HRESULT get_view_removed_reason() const throw(); -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md b/docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md deleted file mode 100644 index 9c6baf74c4d..00000000000 --- a/docs/parallel/amp/reference/adopt-d3d-access-lock-t-structure.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -description: "Learn more about: adopt_d3d_access_lock_t Structure" -title: "adopt_d3d_access_lock_t Structure" -ms.date: "11/04/2016" -f1_keywords: ["amprt/concurrency::direct3d::adopt_d3d_access_lock_t"] -ms.assetid: ef10bb06-88d6-420b-bb81-35895b2e02e6 ---- -# adopt_d3d_access_lock_t Structure - -Tag type to indicate the D3D access lock should be adopted rather than acquired. - -## Syntax - -```cpp -struct adopt_d3d_access_lock_t; -``` - -## Members - -## Inheritance Hierarchy - -`adopt_d3d_access_lock_t` - -## Requirements - -**Header:** amprt.h - -**Namespace:** concurrency::direct3d - -## See also - -[Concurrency::direct3d Namespace](concurrency-direct3d-namespace.md) diff --git a/docs/parallel/amp/reference/array-class.md b/docs/parallel/amp/reference/array-class.md deleted file mode 100644 index ce31e23b618..00000000000 --- a/docs/parallel/amp/reference/array-class.md +++ /dev/null @@ -1,817 +0,0 @@ ---- -description: "Learn more about: array Class" -title: "array Class" -ms.date: "11/04/2016" -f1_keywords: ["array", "AMP/array", "AMP/Concurrency::array::array", "AMP/Concurrency::array::copy_to", "AMP/Concurrency::array::data", "AMP/Concurrency::array::get_accelerator_view", "AMP/Concurrency::array::get_associated_accelerator_view", "AMP/Concurrency::array::get_cpu_access_type", "AMP/Concurrency::array::get_extent", "AMP/Concurrency::array::reinterpret_as", "AMP/Concurrency::array::section", "AMP/Concurrency::array::view_as", "AMP/Concurrency::array::rank", "AMP/Concurrency::array::accelerator_view", "AMP/Concurrency::array::associated_accelerator_view", "AMP/Concurrency::array::cpu_access_type", "AMP/Concurrency::array::extent"] -helpviewer_keywords: ["array class"] -ms.assetid: 0832b6c1-40f0-421d-9104-6b1baa0c63a7 ---- -# array Class - -Represents a data container used to move data to an accelerator. - -## Syntax - -```cpp -template -friend class array; -``` - -### Parameters - -*value_type*
-The element type of the data. - -*_Rank*
-The rank of the array. - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[array Constructor](#ctor)|Initializes a new instance of the `array` class.| -|[~array Destructor](#dtor)|Destroys the `array` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[copy_to](#copy_to)|Copies the contents of the array to another array.| -|[data](#data)|Returns a pointer to the raw data of the array.| -|[get_accelerator_view](#get_accelerator_view)|Returns the [accelerator_view](accelerator-view-class.md) object that represents the location where the array is allocated. This property can be accessed only on the CPU.| -|[get_associated_accelerator_view](#get_associated_accelerator_view)|Gets the second [accelerator_view](accelerator-view-class.md) object that is passed as a parameter when a staging constructor is called to instantiate the `array` object.| -|[get_cpu_access_type](#get_cpu_access_type)|Returns the [access_type](concurrency-namespace-enums-amp.md#access_type) of the array. This method can be accessed only on the CPU.| -|[get_extent](#get_extent)|Returns the [extent](extent-class.md) object of the array.| -|[reinterpret_as](#reinterpret_as)|Returns a one-dimensional array that contains all the elements in the `array` object.| -|[section](#section)|Returns a subsection of the `array` object that is at the specified origin and, optionally, that has the specified extent.| -|[view_as](#view_as)|Returns an [array_view](array-view-class.md) object that is constructed from the `array` object.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[`operator std::vector`](#operator_vec)|Uses `copy(*this, vector)` to implicitly convert the array to a std::[vector](../../../standard-library/vector-class.md) object.| -|[operator()](#operator_call)|Returns the element value that is specified by the parameters.| -|[operator\[\]](#operator_at)|Returns the element that is at the specified index.| -|[operator=](#operator_eq)|Copies the contents of the specified `array` object into this one.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[rank Constant](#rank)|Stores the rank of the array.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[accelerator_view](#accelerator_view)|Gets the [accelerator_view](accelerator-view-class.md) object that represents the location where the array is allocated. This property can be accessed only on the CPU.| -|[associated_accelerator_view](#associated_accelerator_view)|Gets the second [accelerator_view](accelerator-view-class.md) object that is passed as a parameter when a staging constructor is called to instantiate the `array` object.| -|[cpu_access_type](#cpu_access_type)|Gets the [access_type](concurrency-namespace-enums-amp.md#access_type) that represents how the CPU can access the storage of the array.| -|[extent](#extent)|Gets the extent that defines the shape of the array.| - -## Remarks - -The type `array` represents a dense and regular (not jagged) *N*-dimensional array that is located in a specific location, such as an accelerator or the CPU. The data type of the elements in the array is `T`, which must be of a type that is compatible with the target accelerator. Although the rank, `N`, (of the array is determined statically and is part of the type, the extent of the array is determined by the runtime and is expressed by using class `extent`. - -An array can have any number of dimensions, although some functionality is specialized for `array` objects with rank one, two, and three. If you omit the dimension argument, the default is 1. - -Array data is laid out contiguously in memory. Elements that differ by one in the least significant dimension are adjacent in memory. - -Arrays are logically considered to be value types, because when an array is copied to another array, a deep copy is performed. Two arrays never point to the same data. - -The `array` type is used in several scenarios: - -- As a data container that can be used in computations on an accelerator. - -- As a data container to hold memory on the host CPU (that can be used to copy to and from other arrays). - -- As a staging object to act as a fast intermediary in host-to-device copies. - -## Inheritance Hierarchy - -`array` - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## ~array - -Destroys the `array` object. - -```cpp -~array() restrict(cpu); -``` - -## accelerator_view - -Gets the [accelerator_view](accelerator-view-class.md) object that represents the location where the array is allocated. This property can be accessed only on the CPU. - -```cpp -__declspec(property(get= get_accelerator_view)) Concurrency::accelerator_view accelerator_view; -``` - -## array - -Initializes a new instance of the [array class](array-class.md). There is no default constructor for `array`. All constructors are run on the CPU only. They cannot be executed on a Direct3D target. - -```cpp -explicit array( - const Concurrency::extent<_Rank>& _Extent) restrict(cpu); - -explicit array( - int _E0) restrict(cpu); - -explicit array( - int _E0, - int _E1) restrict(cpu); - -explicit array( - int _E0, - int _E1, - int _E2) restrict(cpu); - -array( - const Concurrency::extent<_Rank>& _Extent, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -array( - int _E0, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -array( - int _E0, - int _E1, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -array( - int _E0, - int _E1, - int _E2, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -array( - const Concurrency::extent<_Rank>& _Extent, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -array( - int _E0, - accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -array( - int _E0, - int _E1, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -array( - int _E0, - int _E1, - int _E2, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - const Concurrency::extent<_Rank>& _Extent, - _InputIterator _Src_first, - _InputIterator _Src_last) restrict(cpu); - -template -array( - const Concurrency::extent<_Rank>& _Extent, - _InputIterator _Src_first) restrict(cpu); - -template -array( - int _E0, - _InputIterator _Src_first, - _InputIterator _Src_last) restrict(cpu); - -template -array( - int _E0, - _InputIterator _Src_first) restrict(cpu); - -template -array( - int _E0, - int _E1, - _InputIterator _Src_first, - _InputIterator _Src_last) restrict(cpu); - -template -array( - int _E0, - int _E1, - _InputIterator _Src_first) restrict(cpu); - -template -array( - int _E0, - int _E1, - int _E2, - _InputIterator _Src_first, - _InputIterator _Src_last) restrict(cpu); - -template -array( - int _E0, - int _E1, - int _E2, - _InputIterator _Src_first) restrict(cpu); - -template -array( - const Concurrency::extent<_Rank>& _Extent, - _InputIterator _Src_first, - _InputIterator _Src_last, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - const Concurrency::extent<_Rank>& _Extent, - _InputIterator _Src_first, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - int _E0, - _InputIterator _Src_first, - _InputIterator _Src_last, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - int _E0, - _InputIterator _Src_first, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - int _E0, - int _E1, - _InputIterator _Src_first, - _InputIterator _Src_last, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - int _E0, - int _E1, - _InputIterator _Src_first, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - int _E0, - int _E1, - int _E2, - _InputIterator _Src_first, - _InputIterator _Src_last, - Concurrency::accelerator_view _Av, - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - int _E0, - int _E1, - int _E2, - _InputIterator _Src_first, - Concurrency::accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -template -array( - const Concurrency::extent<_Rank>& _Extent, - _InputIterator _Src_first, - _InputIterator _Src_last, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - const Concurrency::extent<_Rank>& _Extent, - _InputIterator _Src_first, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - int _E0, - _InputIterator _Src_first, - _InputIterator _Src_last, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - int _E0, _InputIterator _Src_first, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - int _E0, - int _E1, _InputIterator _Src_first, _InputIterator _Src_last, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - int _E0, - int _E1, _InputIterator _Src_first, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - int _E0, - int _E1, - int _E2, _InputIterator _Src_first, _InputIterator _Src_last, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -template -array( - int _E0, - int _E1, - int _E2, _InputIterator _Src_first, - Concurrency::accelerator_view _Av, - Concurrency::accelerator_view _Associated_Av) restrict(cpu); - -explicit array( - const array_view& _Src) restrict(cpu); - -array( - const array_view& _Src, - accelerator_view _Av - access_type _Cpu_access_type = access_type_auto) restrict(cpu); - -array( - const array_view& _Src, - accelerator_view _Av, - accelerator_view _Associated_Av) restrict(cpu); - -array(const array& _Other) restrict(cpu); - -array(array&& _Other) restrict(cpu); -``` - -### Parameters - -*_Associated_Av*
-An accelerator_view which specifies the preferred target location of the array. - -*_Av*
-An [accelerator_view](accelerator-view-class.md) object that specifies the location of the array. - -*_Cpu_access_type*
-The desired [access_type](concurrency-namespace-enums-amp.md#access_type) for the array on the CPU. This parameter has a default value of `access_type_auto` leaving the CPU `access_type` determination to the runtime. The actual CPU `access_type` for the array can be queried using the `get_cpu_access_type` method. - -*_Extent*
-The extent in each dimension of the array. - -*_E0*
-The most significant component of the extent of this section. - -*_E1*
-The next-to-most-significant component of the extent of this section. - -*_E2*
-The least significant component of the extent of this section. - -*_InputIterator*
-The type of the input iterator. - -*_Src*
-To object to copy. - -*_Src_first*
-A beginning iterator into the source container. - -*_Src_last*
-An ending iterator into the source container. - -*_Other*
-Other data source. - -*_Rank*
-The rank of the section. - -*value_type*
-The data type of the elements that are copied. - -## associated_accelerator_view - -Gets the second [accelerator_view](accelerator-view-class.md) object that is passed as a parameter when a staging constructor is called to instantiate the `array` object. - -```cpp -__declspec(property(get= get_associated_accelerator_view)) Concurrency::accelerator_view associated_accelerator_view; -``` - -## copy_to - -Copies the contents of the `array` to another `array`. - -```cpp -void copy_to( - array& _Dest) const ; - -void copy_to( - array_view& _Dest) const ; -``` - -### Parameters - -*_Dest*
-The [array_view](array-view-class.md) object to copy to. - -## cpu_access_type - -Gets the CPU access_type allowed for this array. - -```cpp -__declspec(property(get= get_cpu_access_type)) access_type cpu_access_type; -``` - -## data - -Returns a pointer to the raw data of the `array`. - -```cpp -value_type* data() restrict(amp, cpu); - -const value_type* data() const restrict(amp, cpu); -``` - -### Return Value - -A pointer to the raw data of the array. - -## extent - -Gets the [extent](extent-class.md) object that defines the shape of the `array`. - -```cpp -__declspec(property(get= get_extent)) Concurrency::extent<_Rank> extent; -``` - -## get_accelerator_view - -Returns the [accelerator_view](accelerator-view-class.md) object that represents the location where the `array` object is allocated. This property can be accessed only on the CPU. - -```cpp -Concurrency::accelerator_view get_accelerator_view() const; -``` - -### Return Value - -The `accelerator_view` object that represents the location where the `array` object is allocated. - -## get_associated_accelerator_view - -Gets the second [accelerator_view](accelerator-view-class.md) object that is passed as a parameter when a staging constructor is called to instantiate the `array` object. - -```cpp -Concurrency::accelerator_view get_associated_accelerator_view() const ; -``` - -### Return Value - -The second [accelerator_view](accelerator-view-class.md) object passed to the staging constructor. - -## get_cpu_access_type - -Returns the CPU access_type that's allowed for this array. - -```cpp -access_type get_cpu_access_type() const restrict(cpu); -``` - -### Return Value - -## get_extent - -Returns the [extent](extent-class.md) object of the `array`. - -```cpp -Concurrency::extent<_Rank> get_extent() const restrict(amp,cpu); -``` - -### Return Value - -The `extent` object of the `array`. - -## `operator std::vector` - -Uses `copy(*this, vector)` to implicitly convert the array to a std::vector object. - -```cpp -operator std::vector() const restrict(cpu); -``` - -### Parameters - -*value_type*
-The data type of the elements of the vector. - -### Return Value - -An object of type `vector` that contains a copy of the data that is contained in the array. - -## operator() - -Returns the element value that is specified by the parameters. - -```cpp -value_type& operator() (const index<_Rank>& _Index) restrict(amp,cpu); - -const value_type& operator() (const index<_Rank>& _Index) cons t restrict(amp,cpu); - -value_type& operator() (int _I0, int _I1) restrict(amp,cpu); - -const value_type& operator() (int _I0, int _I1) const restrict(amp,cpu) ; - -value_type& operator() (int _I0, int _I1, int _I2) restrict(amp,cpu); - -const value_type& operator() (int _I0, int _I1, int _I2) const restrict(amp,cpu); - -typename details::_Projection_result_type::_Result_type operator()(int _I) restrict(amp,cpu); - -typename details::_Projection_result_type::_Const_result_type operator()(int _I) const restrict(amp,cpu); -``` - -### Parameters - -*_Index*
-The location of the element. - -*_I0*
-The most significant component of the origin of this section. - -*_I1*
-The next-to-most-significant component of the origin of this section. - -*_I2*
-The least significant component of the origin of this section. - -*_I*
-The location of the element. - -### Return Value - -The element value specified by the parameters. - -## operator[] - -Returns the element that is at the specified index. - -```cpp -value_type& operator[](const index<_Rank>& _Index) restrict(amp,cpu); - -const value_type& operator[] - (const index<_Rank>& _Index) const restrict(amp,cpu); - -typename details::_Projection_result_type::_Result_type operator[](int _i) restrict(amp,cpu); - -typename details::_Projection_result_type::_Const_result_type operator[](int _i) const restrict(amp,cpu); -``` - -### Parameters - -*_Index*
-The index. - -*_I*
-The index. - -### Return Value - -The element that is at the specified index. - -## operator= - -Copies the contents of the specified `array` object. - -```cpp -array& operator= (const array& _Other) restrict(cpu); - -array& operator= (array&& _Other) restrict(cpu); - -array& operator= ( - const array_view& _Src) restrict(cpu); -``` - -### Parameters - -*_Other*
-The `array` object to copy from. - -*_Src*
-The `array` object to copy from. - -### Return Value - -A reference to this `array` object. - -## rank - -Stores the rank of the `array`. - -```cpp -static const int rank = _Rank; -``` - -## reinterpret_as - -Reinterprets the array through a one-dimensional array_view, which optionally may have a different value type than the source array. - -### Syntax - -```cpp -template -array_view<_Value_type2,1> reinterpret_as() restrict(amp,cpu); - -template -array_view reinterpret_as() const restrict(amp,cpu); -``` - -### Parameters - -*_Value_type2*
-The data type of the returned data. - -### Return Value - -An array_view or const array_view object that is based on the array, with the element type reinterpreted from T to ElementType and the rank reduced from N to 1. - -### Remarks - -Sometimes it is convenient to view a multi-dimensional array as if it is a linear, one-dimensional array, possibly with a different value type than the source array. You can use this method to achieve this. -**Caution** Reinterpreting an array object by using a different value type is a potentially unsafe operation. We recommend that you use this functionality carefully. - -The following code provides an example. - -```cpp -struct RGB { float r; float g; float b; }; - -array a = ...; -array_view v = a.reinterpret_as(); - -assert(v.extent == 3*a.extent); -``` - -## section - -Returns a subsection of the `array` object that is at the specified origin and, optionally, that has the specified extent. - -```cpp -array_view section( - const Concurrency::index<_Rank>& _Section_origin, - const Concurrency::extent<_Rank>& _Section_extent) restrict(amp,cpu); - -array_view section( - const Concurrency::index<_Rank>& _Section_origin, - const Concurrency::extent<_Rank>& _Section_extent) const restrict(amp,cpu); - -array_view section( - const Concurrency::extent<_Rank>& _Ext) restrict(amp,cpu); - -array_view section( - const Concurrency::extent<_Rank>& _Ext) const restrict(amp,cpu); - -array_view section( - const index<_Rank>& _Idx) restrict(amp,cpu); - -array_view section( - const index<_Rank>& _Idx) const restrict(amp,cpu); - -array_view section( - int _I0, - int _E0) restrict(amp,cpu); - -array_view section( - int _I0, - int _E0) const restrict(amp,cpu); - -array_view section( - int _I0, - int _I1, - int _E0, - int _E1) restrict(amp,cpu); - -array_view section( - int _I0, - int _I1, - int _E0, - int _E1) const restrict(amp,cpu); - -array_view section( - int _I0, - int _I1, - int _I2, - int _E0, - int _E1, - int _E2) restrict(amp,cpu); - -array_view section( - int _I0, - int _I1, - int _I2, - int _E0, - int _E1, - int _E2) const restrict(amp,cpu); -``` - -### Parameters - -*_E0*
-The most significant component of the extent of this section. - -*_E1*
-The next-to-most-significant component of the extent of this section. - -*_E2*
-The least significant component of the extent of this section. - -*_Ext*
-The [extent](extent-class.md) object that specifies the extent of the section. The origin is 0. - -*_Idx*
-The [index](index-class.md) object that specifies the location of the origin. The subsection is the rest of the extent. - -*_I0*
-The most significant component of the origin of this section. - -*_I1*
-The next-to-most-significant component of the origin of this section. - -*_I2*
-The least significant component of the origin of this section. - -*_Rank*
-The rank of the section. - -*_Section_extent*
-The [extent](extent-class.md) object that specifies the extent of the section. - -*_Section_origin*
-The [index](index-class.md) object that specifies the location of the origin. - -*value_type*
-The data type of the elements that are copied. - -### Return Value - -Returns a subsection of the `array` object that is at the specified origin and, optionally, that has the specified extent. When only the `index` object is specified, the subsection contains all elements in the associated grid that have indexes that are larger than the indexes of the elements in the `index` object. - -## view_as - -Reinterprets this array as an [array_view](array-view-class.md) of a different rank. - -```cpp -template -array_view view_as( - const Concurrency::extent<_New_rank>& _View_extent) restrict(amp,cpu); - -template -array_view view_as( - const Concurrency::extent<_New_rank>& _View_extent) const restrict(amp,cpu); -``` - -### Parameters - -*_New_rank*
-The rank of the `extent` object passed as a parameter. - -*_View_extent*
-The extent that is used to construct the new [array_view](array-view-class.md) object. - -*value_type*
-The data type of the elements in both the original `array` object and the returned `array_view` object. - -### Return Value - -The [array_view](array-view-class.md) object that is constructed. - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/array-view-class.md b/docs/parallel/amp/reference/array-view-class.md deleted file mode 100644 index 212c17cdeaf..00000000000 --- a/docs/parallel/amp/reference/array-view-class.md +++ /dev/null @@ -1,773 +0,0 @@ ---- -description: "Learn more about: array_view Class" -title: "array_view Class" -ms.date: "11/04/2016" -f1_keywords: ["array_view", "AMP/array_view", "AMP/Concurrency::array_view::array_view", "AMP/Concurrency::array_view::copy_to", "AMP/Concurrency::array_view::data", "AMP/Concurrency::array_view::discard_data", "AMP/Concurrency::array_view::get_extent", "AMP/Concurrency::array_view::get_ref", "AMP/Concurrency::array_view::get_source_accelerator_view", "AMP/Concurrency::array_view::refresh", "AMP/Concurrency::array_view::reinterpret_as", "AMP/Concurrency::array_view::section", "AMP/Concurrency::array_view::synchronize", "AMP/Concurrency::array_view::synchronize_async", "AMP/Concurrency::array_view::synchronize_to", "AMP/Concurrency::array_view::synchronize_to_async", "AMP/Concurrency::array_view::view_as", "AMP/Concurrency::array_view::rank", "AMP/Concurrency::array_view::extent", "AMP/Concurrency::array_view::source_accelerator_view", "AMP/Concurrency::array_view::value_type"] -helpviewer_keywords: ["array_view class"] -ms.assetid: 7e7ec9bc-05a2-4372-b05d-752b50006c5a ---- -# array_view Class - -Represents an N-dimensional view over the data held in another container. - -## Syntax - -```cpp -template < - typename value_type, - int _Rank = 1 -> -class array_view : public _Array_view_base<_Rank, sizeof(value_type)/sizeof(int)>; - -template < - typename value_type, - int _Rank -> -class array_view : public _Array_view_base<_Rank, sizeof(value_type)/sizeof(int)>; -``` - -### Parameters - -*value_type*
-The data type of the elements in the `array_view` object. - -*_Rank*
-The rank of the `array_view` object. - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[array_view Constructor](#ctor)|Initializes a new instance of the `array_view` class. There is no default constructor for `array`. All constructors are restricted to run on the CPU only and cannot be executed on a Direct3D target.| -|[~array_view Destructor](#ctor)|Destroys the `array_view` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[copy_to](#copy_to)|Copies the contents of the `array_view` object to the specified destination by calling `copy(*this, dest)`.| -|[data](#data)|Returns a pointer to the raw data of the `array_view`.| -|[discard_data](#discard_data)|Discards the current data underlying this view.| -|[get_extent](#get_extent)|Returns the extent object of the array_view object.| -|[get_ref](#get_ref)|Returns a reference to the indexed element.| -|[get_source_accelerator_view](#get_source_accelerator_view)|Returns the [accelerator_view](accelerator-view-class.md) where the data source of the `array_view` is located.| -|[refresh](#refresh)|Notifies the `array_view` object that its bound memory has been modified outside the `array_view` interface. A call to this method renders all cached information stale.| -|[reinterpret_as](#reinterpret_as)|Returns a one-dimensional array that contains all the elements in the `array_view` object.| -|[section](#section)|Returns a subsection of the `array_view` object that's at the specified origin and, optionally, that has the specified extent.| -|[synchronize](#synchronize)|Synchronizes any modifications made to the `array_view` object back to its source data.| -|[synchronize_async](#synchronize_async)|Asynchronously synchronizes any modifications made to the `array_view` object back to its source data.| -|[synchronize_to](#synchronize_to)|Synchronizes any modifications made to the `array_view` object to the specified [accelerator_view](accelerator-view-class.md).| -|[synchronize_to_async](#synchronize_to_async)|Asynchronously synchronizes any modifications made to the `array_view` object to the specified [accelerator_view](accelerator-view-class.md).| -|[view_as](#view_as)|Produces an `array_view` object of a different rank using this `array_view` object’s data.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator()](#operator_call)|Returns the value of the element that is specified by the parameter or parameters.| -|[operator\[\]](#operator_at)|Returns the element that is specified by the parameters.| -|[operator=](#operator_eq)|Copies the contents of the specified `array_view` object into this one.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[rank Constant](#rank)|Stores the rank of the `array_view` object.| - -### Data Members - -|Name|Description| -|----------|-----------------| -|[extent](#extent)|Gets the `extent` object that defines the shape of the `array_view` object.| -|[source_accelerator_view](#source_accelerator_view)|Gets the [accelerator_view](accelerator-view-class.md) where the data source of the `array_view` is located| -|[value_type](#value_type)|The value type of the `array_view` and the bound array.| - -## Remarks - -The `array_view` class represents a view into the data that is contained in an [array](array-class.md) object or a subsection of an `array` object. - -You can access the `array_view` object where the source data is located (locally) or on a different accelerator or a coherence domain (remotely). When you access the object remotely, views are copied and cached as necessary. Except for the effects of automatic caching, `array_view` objects have a performance profile similar to that of `array` objects. There is a small performance penalty when you access the data through views. - -There are three remote usage scenarios: - -- A view to a system memory pointer is passed by means of a [parallel_for_each](../../../parallel/concrt/reference/concurrency-namespace-functions.md#parallel_for_each) call to an accelerator and accessed on the accelerator. - -- A view to an array located on an accelerator is passed by means of a `parallel_for_each` call to another accelerator and is accessed there. - -- A view to an array located on an accelerator is accessed on the CPU. - -In any one of these scenarios, the referenced views are copied by the runtime to the remote location and, if modified by the calls to the `array_view` object, are copied back to the local location. The runtime might optimize the process of copying changes back, might copy only changed elements, or might copy unchanged portions also. Overlapping `array_view` objects on one data source are not guaranteed to maintain referential integrity in a remote location. - -You must synchronize any multithreaded access to the same data source. - -The runtime makes the following guarantees regarding the caching of data in `array_view` objects: - -- All well-synchronized accesses to an `array` object and an `array_view` object on it in program order obey a serial happens-before relationship. - -- All well-synchronized accesses to overlapping `array_view` objects on the same accelerator on a single `array` object are aliased through the `array` object. They induce a total occurs-before relationship which obeys program order. There is no caching. If the `array_view` objects are executing on different accelerators, the order of access is undefined, creating a race condition. - -When you create an `array_view` object using a pointer in system memory, you must change the view `array_view` object only through the `array_view` pointer. Alternatively, you must call `refresh()` on one of the `array_view` objects that are attached to the system pointer, if the underlying native memory is changed directly, instead of through the `array_view` object. - -Either action notifies the `array_view` object that the underlying native memory is changed and that any copies that are located on an accelerator are outdated. If you follow these guidelines, the pointer-based views are identical to those provided to views of data-parallel arrays. - -## Inheritance Hierarchy - -`_Array_view_shape` - -`_Array_view_base` - -`array_view` - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## ~array_view - -Destroys the `array_view` object. - -```cpp -~array_view()restrict(amp,cpu); -``` - -## array_view - -Initializes a new instance of the `array_view` class. - -```cpp -array_view( - array& _Src)restrict(amp,cpu); - -array_view( - const array_view& _Other)restrict(amp,cpu); - -explicit array_view( - const Concurrency::extent<_Rank>& _Extent) restrict(cpu); - -template < - typename _Container -> -array_view( - const Concurrency::extent<_Rank>& _Extent, - _Container& _Src) restrict(cpu); - -array_view( - const Concurrency::extent<_Rank>& _Extent, - value_type* _Src)restrict(amp,cpu); - -explicit array_view( - int _E0) restrict(cpu); - -template < - typename _Container -> -explicit array_view( - _Container& _Src, - typename std::enable_if::type::value, void **>::type = 0) restrict(cpu); - -template < - typename _Container -> -explicit array_view( - int _E0, - _Container& _Src) restrict(cpu); - -explicit array_view( - int _E0, - int _E1) __CPU_ONLY; - -template < - typename _Container -> -explicit array_view( - int _E0, - int _E1, - _Container& _Src) restrict(cpu); - -explicit array_view( - int _E0, - int _E1, - int _E2) __CPU_ONLY; - -template < - typename _Container -> -explicit array_view( - int _E0, - int _E1, - int _E2, - _Container& _Src); - -explicit array_view( - int _E0, - _In_ value_type* _Src)restrict(amp,cpu); - -template < - typename _Arr_type, - int _Size -> -explicit array_view( - _In_ _Arr_type (& _Src) [_Size]) restrict(amp,cpu); - -explicit array_view( - int _E0, - int _E1, - _In_ value_type* _Src)restrict(amp,cpu); - -explicit array_view( - int _E0, - int _E1, - int _E2, - _In_ value_type* _Src)restrict(amp,cpu); - -array_view( - const array& _Src)restrict(amp,cpu); - -array_view( - const array_view& _Src)restrict(amp,cpu); - -array_view( - const array_view& _Src)restrict(amp,cpu); - -template < - typename _Container -> -array_view( - const Concurrency::extent<_Rank>& _Extent, - const _Container& _Src) restrict(cpu); - -template < - typename _Container -> -explicit array_view( - const _Container& _Src, - typename std::enable_if::type::value, void **>::type = 0) restrict(cpu); - -array_view( - const Concurrency::extent<_Rank>& _Extent, - const value_type* _Src)restrict(amp,cpu); - -template < - typename _Arr_type, - int _Size -> -explicit array_view( - const _In_ _Arr_type (& _Src) [_Size]) restrict(amp,cpu); - -template < - typename _Container -> -array_view( - int _E0, - const _Container& _Src); - -template < - typename _Container -> -array_view( - int _E0, - int _E1, - const _Container& _Src); - -template < - typename _Container -> -array_view( - int _E0, - int _E1, - int _E2, - const _Container& _Src); - -array_view( - int _E0, - const value_type* _Src)restrict(amp,cpu); - -array_view( - int _E0, - int _E1, - const value_type* _Src) restrict(amp,cpu); - -array_view( - int _E0, - int _E1, - int _E2, - const value_type* _Src) restrict(amp,cpu); -``` - -### Parameters - -*_Arr_type*
-The element type of a C-style array from which data is supplied. - -*_Container*
-A template argument that must specify a linear container that supports `data()` and `size()` members. - -*_E0*
-The most significant component of the extent of this section. - -*_E1*
-The next-to-most-significant component of the extent of this section. - -*_E2*
-The least significant component of the extent of this section. - -*_Extent*
-The extent in each dimension of this `array_view`. - -*_Other*
-An object of type `array_view` from which to initialize the new `array_view`. - -*_Size*
-The size of a C-style array from which data is supplied. - -*_Src*
-A pointer to the source data that will be copied into the new array. - -## copy_to - -Copies the contents of the `array_view` object to the specified destination object by calling `copy(*this, dest)`. - -```cpp -void copy_to( - array& _Dest) const; - -void copy_to( - array_view& _Dest) const; -``` - -### Parameters - -*_Dest*
-The object to copy to. - -## data - -Returns a pointer to the raw data of the `array_view`. - -```cpp -value_type* data() const restrict(amp, - cpu); - -const value_type* data() const restrict(amp, - cpu); -``` - -### Return Value - -A pointer to the raw data of the `array_view`. - -## discard_data - -Discards the current data underlying this view. This is an optimization hint to the runtime used to avoid copying the current contents of the view to a target `accelerator_view` that it is accessed on, and its use is recommended if the existing content is not needed. This method is a no-op when used in a restrict(amp) context - -```cpp -void discard_data() const restrict(cpu); -``` - -## extent - -Gets the `extent` object that defines the shape of the `array_view` object. - -```cpp -__declspec(property(get= get_extent)) Concurrency::extent<_Rank> extent; -``` - -## get_extent - -Returns the [extent](extent-class.md) object of the `array_view` object. - -```cpp -Concurrency::extent<_Rank> get_extent() const restrict(cpu, amp); -``` - -### Return Value - -The `extent` object of the `array_view` object - -## get_ref - -Get a reference to the element indexed by _Index. Unlike the other indexing operators for accessing the array_view on the CPU, this method does not implicitly synchronize this array_view's contents to the CPU. After accessing the array_view on a remote location or performing a copy operation involving this array_view users are responsible to explicitly synchronize the array_view to the CPU before calling this method. Failure to do so results in undefined behavior. - -```cpp -value_type& get_ref( - const index<_Rank>& _Index) const restrict(amp, cpu); -``` - -### Parameters - -*_Index*
-The index. - -### Return Value - -Reference to the element indexed by _Index - -## get_source_accelerator_view - -Returns the accelerator_view where the data source of the array_view is located. If the array_view does not have a data source, this API throws a runtime_exception - -```cpp -accelerator_view get_source_accelerator_view() const; -``` - -### Return Value - -## operator() - -Returns the value of the element that is specified by the parameter or parameters. - -```cpp -value_type& operator() ( - const index<_Rank>& _Index) const restrict(amp,cpu); - -typename details::_Projection_result_type::_Result_type operator() ( - int _I) const restrict(amp,cpu); - -value_type& operator() ( - int _I0, - int _I1) const restrict(amp,cpu); - -value_type& operator() ( - int _I0, - int _I1, - int _I2) const restrict(amp,cpu); - -typename details::_Projection_result_type::_Const_result_type operator() ( - int _I) const restrict(amp,cpu); -``` - -### Parameters - -*_Index*
-The location of the element. - -*_I0*
-The index in the first dimension. - -*_I1*
-The index in the second dimension. - -*_I2*
-The index in the third dimension. - -*_I*
-The location of the element. - -### Return Value - -The value of the element that is specified by the parameter or parameters. - -## operator[] - -Returns the element that is specified by the parameters. - -```cpp -typename details::_Projection_result_type::_Const_result_type operator[] ( - int _I) const restrict(amp,cpu); - -value_type& operator[] ( - const index<_Rank>& _Index) const restrict(amp,cpu); -``` - -### Parameters - -*_Index*
-The index. - -*_I*
-The index. - -### Return Value - -The value of the element at the index, or an `array_view` projected on the most-significant dimension. - -## operator= - -Copies the contents of the specified `array_view` object to this one. - -```cpp -array_view& operator= ( - const array_view& _Other) restrict(amp,cpu); - -array_view& operator= ( - const array_view& _Other) restrict(amp,cpu); -``` - -### Parameters - -*_Other*
-The `array_view` object to copy from. - -### Return Value - -A reference to this `array_view` object. - -## rank - -Stores the rank of the `array_view` object. - -```cpp -static const int rank = _Rank; -``` - -## refresh - -Notifies the `array_view` object that its bound memory has been modified outside the `array_view` interface. A call to this method renders all cached information stale. - -```cpp -void refresh() const restrict(cpu); -``` - -## reinterpret_as - -Reinterprets the array_view through a one-dimensional array_view, which as an option can have a different value type than the source array_view. - -### Syntax - -```cpp -template < - typename _Value_type2 -> -array_view< _Value_type2, _Rank> reinterpret_as() const restrict(amp,cpu); - -template < - typename _Value_type2 -> -array_view reinterpret_as() const restrict(amp,cpu); -``` - -### Parameters - -*_Value_type2*
-The data type of the new `array_view` object. - -### Return Value - -An `array_view` object or a const `array_view` object that is based on this `array_view`, with the element type converted from `T` to `_Value_type2`, and the rank reduced from *N* to 1. - -### Remarks - -Sometimes it is convenient to view a multi-dimensional array as a linear, one-dimensional array, which may have a different value type than the source array. You can achieve this on an `array_view` by using this method. - -**Warning** Reinterpreting an array_view object by using a different value type is a potentially unsafe operation. This functionality should be used with care. - -Here's an example: - -```cpp -struct RGB { float r; float g; float b; }; - -array a = ...; -array_view v = a.reinterpret_as(); - -assert(v.extent == 3*a.extent); -``` - -## section - -Returns a subsection of the `array_view` object that's at the specified origin and, optionally, that has the specified extent. - -```cpp -array_view section( - const Concurrency::index<_Rank>& _Section_origin, - const Concurrency::extent<_Rank>& _Section_extent) const restrict(amp,cpu); - -array_view section( - const Concurrency::index<_Rank>& _Idx) const restrict(amp,cpu); - -array_view section( - const Concurrency::extent<_Rank>& _Ext) const restrict(amp,cpu); - -array_view section( - int _I0, - int _E0) const restrict(amp,cpu); - -array_view section( - int _I0, - int _I1, - int _E0, - int _E1) const restrict(amp,cpu); - -array_view section( - int _I0, - int _I1, - int _I2, - int _E0, - int _E1, - int _E2) const restrict(amp,cpu); -``` - -### Parameters - -*_E0*
-The most significant component of the extent of this section. - -*_E1*
-The next-to-most-significant component of the extent of this section. - -*_E2*
-The least significant component of the extent of this section. - -*_Ext*
-The [extent](extent-class.md) object that specifies the extent of the section. The origin is 0. - -*_Idx*
-The [index](index-class.md) object that specifies the location of the origin. The subsection is the rest of the extent. - -*_I0*
-The most significant component of the origin of this section. - -*_I1*
-The next-to-most-significant component of the origin of this section. - -*_I2*
-The least significant component of the origin of this section. - -*_Rank*
-The rank of the section. - -*_Section_extent*
-The [extent](extent-class.md) object that specifies the extent of the section. - -*_Section_origin*
-The [index](index-class.md) object that specifies the location of the origin. - -### Return Value - -A subsection of the `array_view` object that's at the specified origin and, optionally, that has the specified extent. When only the `index` object is specified, the subsection contains all elements in the associated extent that have indexes that are larger than the indexes of the elements in the `index` object. - -## source_accelerator_view - -Gets the source accelerator_view that this array_view is associated with. - -```cpp -__declspec(property(get= get_source_accelerator_view)) accelerator_view source_accelerator_view; -``` - -## synchronize - -Synchronizes any modifications made to the `array_view` object back to its source data. - -```cpp -void synchronize(access_type _Access_type = access_type_read) const restrict(cpu); - -void synchronize() const restrict(cpu); -``` - -### Parameters - -*_Access_type*
-The intended [access_type](concurrency-namespace-enums-amp.md#access_type) on the target [accelerator_view](accelerator-view-class.md). This parameter has a default value of `access_type_read`. - -## synchronize_async - -Asynchronously synchronizes any modifications made to the `array_view` object back to its source data. - -```cpp -concurrency::completion_future synchronize_async(access_type _Access_type = access_type_read) const restrict(cpu); - -concurrency::completion_future synchronize_async() const restrict(cpu); -``` - -### Parameters - -*_Access_type*
-The intended [access_type](concurrency-namespace-enums-amp.md#access_type) on the target [accelerator_view](accelerator-view-class.md). This parameter has a default value of `access_type_read`. - -### Return Value - -A future upon which to wait for the operation to complete. - -## synchronize_to - -Synchronizes any modifications made to this array_view to the specified accelerator_view. - -```cpp -void synchronize_to( - const accelerator_view& _Accl_view, - access_type _Access_type = access_type_read) const restrict(cpu); - -void synchronize_to( - const accelerator_view& _Accl_view) const restrict(cpu); -``` - -### Parameters - -*_Accl_view*
-The target accelerator_view to synchronize to. - -*_Access_type*
-The desired access_type on the target accelerator_view. This parameter has a default value of access_type_read. - -## synchronize_to_async - -Asynchronously synchronizes any modifications made to this array_view to the specified accelerator_view. - -```cpp -concurrency::completion_future synchronize_to_async( - const accelerator_view& _Accl_view, - access_type _Access_type = access_type_read) const restrict(cpu); - -concurrency::completion_future synchronize_to_async( - const accelerator_view& _Accl_view) const restrict(cpu); -``` - -### Parameters - -*_Accl_view*
-The target accelerator_view to synchronize to. - -*_Access_type*
-The desired access_type on the target accelerator_view. This parameter has a default value of access_type_read. - -### Return Value - -A future upon which to wait for the operation to complete. - -## value_type - -The value type of the array_view and the bound array. - -```cpp -typedef typenamevalue_type value_type; -``` - -## view_as - -Reinterprets this `array_view` as an `array_view` of a different rank. - -```cpp -template < - int _New_rank -> -array_view view_as( - const Concurrency::extent<_New_rank>& _View_extent) const restrict(amp,cpu); - -template < - int _New_rank -> -array_view view_as( - const Concurrency::extent<_New_rank> _View_extent) const restrict(amp,cpu); -``` - -### Parameters - -*_New_rank*
-The rank of the new `array_view` object. - -*_View_extent*
-The reshaping `extent`. - -*value_type*
-The data type of the elements in both the original [array](array-class.md) object and the returned `array_view` object. - -### Return Value - -The `array_view` object that is constructed. - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/completion-future-class.md b/docs/parallel/amp/reference/completion-future-class.md deleted file mode 100644 index e1f8fc6879f..00000000000 --- a/docs/parallel/amp/reference/completion-future-class.md +++ /dev/null @@ -1,277 +0,0 @@ ---- -description: "Learn more about: completion_future Class" -title: "completion_future Class" -ms.date: "11/04/2016" -f1_keywords: ["completion_future", "AMPRT/completion_future", "AMPRT/Concurrency::completion_future::completion_future", "AMPRT/Concurrency::completion_future::get", "AMPRT/Concurrency::completion_future::then", "AMPRT/Concurrency::completion_future::to_task", "AMPRT/Concurrency::completion_future::valid", "AMPRT/Concurrency::completion_future::wait", "AMPRT/Concurrency::completion_future::wait_for", "AMPRT/Concurrency::completion_future::wait_until"] -ms.assetid: 1303c62e-546d-4b02-a578-251ed3fc0b6b ---- -# completion_future Class - -Represents a future corresponding to a C++ AMP asynchronous operation. - -## Syntax - -```cpp -class completion_future; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[completion_future Constructor](#ctor)|Initializes a new instance of the `completion_future` class.| -|[~completion_future Destructor](#dtor)|Destroys the `completion_future` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[get](#get)|Waits until the associated asynchronous operation completes.| -|[then](#then)|Chains a callback function object to the `completion_future` object to be executed when the associated asynchronous operation finishes execution.| -|[to_task](#to_task)|Returns a `task` object corresponding to the associated asynchronous operation.| -|[valid](#valid)|Gets a Boolean value that indicates whether the object is associated with an asynchronous operation.| -|[wait](#wait)|Blocks until the associated asynchronous operation completes.| -|[wait_for](#wait_for)|Blocks until the associated asynchronous operation completes or the time specified by `_Rel_time` has elapsed.| -|[wait_until](#wait_until)|Blocks until the associated asynchronous operation completes or until the current time exceeds the value specified by `_Abs_time`.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator std::shared_future\](#operator_shared_future)|Implicitly converts the `completion_future` object to an `std::shared_future` object.| -|[operator=](#operator_eq)|Copies the contents of the specified `completion_future` object into this one.| - -## Inheritance Hierarchy - -`completion_future` - -## Requirements - -**Header:** amprt.h - -**Namespace:** concurrency - -## completion_future - -Initializes a new instance of the `completion_future` class. - -### Syntax - -```cpp -completion_future(); - -completion_future( - const completion_future& _Other ); - -completion_future( - completion_future&& _Other ); -``` - -### Parameters - -*_Other*
-The `completion_future` object to copy or move. - -### Overloads List - -|Name|Description| -|----------|-----------------| -|`completion_future();`|Initializes a new instance of the `completion_future` Class| -|`completion_future(const completion_future& _Other);`|Initializes a new instance of the `completion_future` class by copying a constructor.| -|`completion_future(completion_future&& _Other);`|Initializes a new instance of the `completion_future` class by moving a constructor.| - -## get - -Waits until the associated asynchronous operation completes. Throws the stored exception if one was encountered during the asynchronous operation. - -### Syntax - -```cpp -void get() const; -``` - -## operator std::shared_future\ - -Implicitly converts the `completion_future` object to an `std::shared_future` object. - -### Syntax - -```cpp -operator std::shared_future() const; -``` - -### Return Value - -An `std::shared_future` object. - -## operator= - -Copies the contents of the specified `completion_future` object into this one. - -### Syntax - -```cpp -completion_future& operator= (const completion_future& _Other ); -completion_future& operator= (completion_future&& _Other ); -``` - -### Parameters - -*_Other*
-The object to copy from. - -### Return Value - -A reference to this `completion_future` object. - -## Overloads List - -|Name|Description| -|----------|-----------------| -|`completion_future& operator=(const completion_future& _Other);`|Copies the contents of the specified `completion_future` object into this one, using a deep copy.| -|`completion_future& operator=(completion_future&& _Other);`|Copies the contents of the specified `completion_future` object into this one, using a move assignment.| - -## then - -Chains a callback function object to the `completion_future` object to be executed when the associated asynchronous operation finishes execution. - -### Syntax - -```cpp -template -void then(const _Functor & _Func ) const; -``` - -### Parameters - -*_Functor*
-The callback functor. - -*_Func*
-The callback function object. - -## to_task - -Returns a `task` object corresponding to the associated asynchronous operation. - -### Syntax - -```cpp -concurrency::task to_task() const; -``` - -### Return Value - -A `task` object corresponding to the associated asynchronous operation. - -## valid - -Gets a Boolean value that indicates whether the object is associated with an asynchronous operation. - -### Syntax - -```cpp -bool valid() const; -``` - -### Return Value - -**`true`** if the object is associated with an asynchronous operation; otherwise, **`false`**. - -## wait - -Blocks until the associated asynchronous operation completes. - -### Syntax - -```cpp -void wait() const; -``` - -## wait_for - -Blocks until the associated asynchronous operation completes or the time that's specified by `_Rel_time` has elapsed. - -### Syntax - -```cpp -template < - class _Rep, - class _Period -> -std::future_status::future_status wait_for( - const std::chrono::duration< _Rep, _Period>& _Rel_time ) const; -``` - -### Parameters - -*_Rep*
-An arithmetic type that represents the number of ticks. - -*_Period*
-A std::ratio that represents the number of seconds that elapse per tick. - -*_Rel_time*
-The maximum amount of time to wait for the operation to complete. - -### Return Value - -Returns: - -- `std::future_status::deferred` if the associated asynchronous operation is not running. - -- `std::future_status::ready` if the associated asynchronous operation is finished. - -- `std::future_status::timeout` if the specified time period has elapsed. - -## wait_until - -Blocks until the associated asynchronous operation completes or until the current time exceeds the value specified by `_Abs_time`. - -### Syntax - -```cpp -template < - class _Clock, - class _Duration -> -std::future_status::future_status wait_until( - const std::chrono::time_point< _Clock, _Duration>& _Abs_time ) const; -``` - -### Parameters - -*_Clock*
-The clock on which this time point is measured. - -*_Duration*
-The time interval since the start of `_Clock`’s epoch, after which the function will time out. - -*_Abs_time*
-The point in time after which the function will time out. - -### Return Value - -Returns: - -1. `std::future_status::deferred` if the associated asynchronous operation is not running. - -1. `std::future_status::ready` if the associated asynchronous operation is finished. - -1. `std::future_status::timeout` if the time period specified has elapsed. - -## ~completion_future - -Destroys the `completion_future` object. - -### Syntax - -```cpp -~completion_future(); -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md b/docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md deleted file mode 100644 index b524d406b84..00000000000 --- a/docs/parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md +++ /dev/null @@ -1,618 +0,0 @@ ---- -description: "Learn more about: Concurrency::direct3d namespace functions (AMP)" -title: "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) - -:::row::: - :::column span=""::: - [abs](#abs)\ - [clamp](#clamp)\ - [countbits](#countbits)\ - [create_accelerator_view](#create_accelerator_view)\ - [d3d_access_lock](#d3d_access_lock)\ - [d3d_access_try_lock](#d3d_access_try_lock)\ - [d3d_access_unlock](#d3d_access_unlock) - :::column-end::: - :::column span=""::: - [firstbithigh](#firstbithigh)\ - [firstbitlow](#firstbitlow)\ - [get_buffer](#get_buffer)\ - [get_device](#get_device)\ - [imax](#imax)\ - [imin](#imin)\ - [is_timeout_disabled](#is_timeout_disabled) - :::column-end::: - :::column span=""::: - [mad](#mad)\ - [make_array](#make_array)\ - [noise](#noise)\ - [radians](#radians)\ - [rcp](#rcp)\ - [reversebits](#reversebits) - :::column-end::: - :::column span=""::: - [saturate](#saturate)\ - [sign](#sign)\ - [smoothstep](#smoothstep)\ - [step](#step)\ - [umax](#umax)\ - [umin](#umin) - :::column-end::: -:::row-end::: - -## Requirements - -**Header:** amp.h -**Namespace:** Concurrency - -## abs - -Returns the absolute value of the argument - -```cpp -inline int abs(int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -### Return Value - -Returns the absolute value of the argument. - -## clamp - -Computes the value of the first specified argument clamped to a range defined by the second and third specified arguments. - -```cpp -inline float clamp( - float _X, - float _Min, - float _Max) restrict(amp); - -inline int clamp( - int _X, - int _Min, - int _Max) restrict(amp); -``` - -### Parameters - -*_X*
-The value to be clamped - -*_Min*
-The lower bound of the clamping range. - -*_Max*
-The upper bound of the clamping range. - -### Return Value - -The clamped value of `_X`. - -## countbits - -Counts the number of set bits in _X - -```cpp -inline unsigned int countbits(unsigned int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Unsigned integer value - -### Return Value - -Returns the number of set bits in _X - -## create_accelerator_view - -Creates an [accelerator_view](accelerator-view-class.md) object from a pointer to a Direct3D device interface. - -## Syntax - -```cpp -accelerator_view create_accelerator_view( - IUnknown * _D3D_device - queuing_mode _Qmode = queuing_mode_automatic); - -accelerator_view create_accelerator_view( - accelerator& _Accelerator, - bool _Disable_timeout - queuing_mode _Qmode = queuing_mode_automatic); -``` - -### Parameters - -*_Accelerator*
-The accelerator on which the new accelerator_view is to be created. - -*_D3D_device*
-The pointer to the Direct3D device interface. - -*_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*
-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 - -The `accelerator_view` object created from the passed Direct3D device interface. - -## Remarks - -This function creates a new `accelerator_view` object from an existing pointer to a Direct3D device interface. If the function call succeeds, the reference count of the parameter is incremented by means of an `AddRef` call to the interface. You can safely release the object when it is no longer required in your DirectX code. If the method call fails, a [runtime_exception](runtime-exception-class.md) is thrown. - -The `accelerator_view` object that you create by using this function is thread safe. You must synchronize concurrent use of the `accelerator_view` object. Unsynchronized concurrent usage of the `accelerator_view` object and the raw ID3D11Device interface causes undefined behavior. - -The C++ AMP runtime provides detailed error information in debug mode by using the D3D Debug layer if you use the `D3D11_CREATE_DEVICE_DEBUG` flag. - -## d3d_access_lock - -Acquire a lock on an accelerator_view for the purpose of safely performing D3D operations on resources shared with the accelerator_view. The accelerator_view and all C++ AMP resources associated with this accelerator_view internally take this lock when performing operations and will block while another thread holds the D3D access lock. This lock is non-recursive: It is undefined behavior to call this function from a thread that already holds the lock. It is undefined behavior to perform operations on the accelerator_view or any data container associated with the accelerator_view from the thread that holds the D3D access lock. See also scoped_d3d_access_lock, a RAII-style class for a scope-based D3D access lock. - -```cpp -void __cdecl d3d_access_lock(accelerator_view& _Av); -``` - -### Parameters - -*_Av*
-The accelerator_view to lock. - -## d3d_access_try_lock - -Attempt to acquire the D3D access lock on an accelerator_view without blocking. - -```cpp -bool __cdecl d3d_access_try_lock(accelerator_view& _Av); -``` - -### Parameters - -*_Av*
-The accelerator_view to lock. - -### Return Value - -true if the lock was acquired, or false if it is currently held by another thread. - -## d3d_access_unlock - -Release the D3D access lock on the given accelerator_view. If the calling thread does not hold the lock on the accelerator_view the results are undefined. - -```cpp -void __cdecl d3d_access_unlock(accelerator_view& _Av); -``` - -### Parameters - -*_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. - -```cpp -inline int firstbithigh(int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -### Return Value - -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. - -```cpp -inline int firstbitlow(int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -### Return Value - -Returns The location of the first set bit - -## get_buffer - -Get the Direct3D buffer interface underlying the specified array. - -```cpp -template< - typename value_type, - int _Rank -> -IUnknown *get_buffer( - const array& _Array) ; -``` - -### Parameters - -*value_type*
-The type of elements in the array. - -*_Rank*
-The rank of the 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 the D3D device interface underlying a accelerator_view. - -```cpp -IUnknown* get_device(const accelerator_view Av); -``` - -### Parameters - -*Av*
-The D3D accelerator_view for which the underlying D3D device interface is returned. - -### Return value - -The `IUnknown` interface pointer of the D3D device underlying the accelerator_view. - -## imax - -Determine the maximum numeric value of the arguments - -```cpp -inline int imax( - int _X, - int _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -*_Y*
-Integer value - -### Return Value - -Return the maximum numeric value of the arguments - -## imin - -Determine the minimum numeric value of the arguments - -```cpp -inline int imin( - int _X, - int _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -*_Y*
-Integer value - -### Return Value - -Return the minimum numeric value of the arguments - -## is_timeout_disabled - -Returns a boolean flag indicating if timeout is disabled for the specified accelerator_view. This corresponds to the D3D11_CREATE_DEVICE_DISABLE_GPU_TIMEOUT flag for Direct3D device creation. - -```cpp -bool __cdecl is_timeout_disabled(const accelerator_view& _Accelerator_view); -``` - -### Parameters - -*_Accelerator_view*
-The accelerator_view for which the timeout disabled setting is to be queried. - -### Return Value - -A boolean flag indicating if timeout is disabled for the specified accelerator_view. - -## mad - -Computes the product of the first and second specified argument, then adds the third specified argument. - -```cpp -inline float mad( - float _X, - float _Y, - float _Z) restrict(amp); - -inline double mad( - double _X, - double _Y, - double _Z) restrict(amp); - -inline int mad( - int _X, - int _Y, - int _Z) restrict(amp); - -inline unsigned int mad( - unsigned int _X, - unsigned int _Y, - unsigned int _Z) restrict(amp); -``` - -### Parameters - -*_X*
-The first specified argument. - -*_Y*
-The second specified argument. - -*_Z*
-The third specified argument. - -### Return Value - -The result of `_X` \* `_Y` + `_Z`. - -## make_array - -Create an array from a Direct3D buffer interface pointer. - -```cpp -template< - typename value_type, - int _Rank -> -array make_array( - const extent<_Rank>& _Extent, - const Concurrency::accelerator_view& _Rv, - IUnknown* _D3D_buffer) ; -``` - -### Parameters - -*value_type*
-The element type of the array to be created. - -*_Rank*
-The rank of the array to be created. - -*_Extent*
-An extent that describes the shape of the array aggregate. - -*_Rv*
-A D3D accelerator view on which the array is to be created. - -*_D3D_buffer*
-IUnknown interface pointer of the D3D buffer to create the array from. - -### Return Value - -An array created using the provided Direct3D buffer. - -## noise - -Generates a random value using the Perlin noise algorithm - -```cpp -inline float noise(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value from which to generate Perlin noise - -### Return Value - -Returns The Perlin noise value within a range between -1 and 1 - -## radians - -Converts _X from degrees to radians - -```cpp -inline float radians(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns _X converted from degrees to radians - -## rcp - -Computes the reciprocal of the specified argument by using a fast approximation. - -```cpp -inline float rcp(float _X) restrict(amp); - -inline double rcp(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-The value for which to compute the reciprocal. - -### Return Value - -The reciprocal of the specified argument. - -## reversebits - -Reverses the order of the bits in _X - -```cpp -inline unsigned int reversebits(unsigned int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Unsigned integer value - -### Return Value - -Returns the value with the bit order reversed in _X - -## saturate - -Clamps _X within the range of 0 to 1 - -```cpp -inline float saturate(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns _X clamped within the range of 0 to 1 - -## sign - -Determines the sign of the specified argument. - -```cpp -inline int sign(int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -### Return Value - -The sign of the argument. - -## smoothstep - -Returns a smooth Hermite interpolation between 0 and 1, if _X is in the range [_Min, _Max]. - -```cpp -inline float smoothstep( - float _Min, - float _Max, - float _X) restrict(amp); -``` - -### Parameters - -*_Min*
-Floating-point value - -*_Max*
-Floating-point value - -*_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] - -## step - -Compares two values, returning 0 or 1 based on which value is greater - -```cpp -inline float step( - float _Y, - float _X) restrict(amp); -``` - -### Parameters - -*_Y*
-Floating-point value - -*_X*
-Floating-point value - -### Return Value - -Returns 1 if the _X is greater than or equal to _Y; otherwise, 0 - -## umax - -Determine the maximum numeric value of the arguments - -```cpp -inline unsigned int umax( - unsigned int _X, - unsigned int _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -*_Y*
-Integer value - -### Return Value - -Return the maximum numeric value of the arguments - -## umin - -Determine the minimum numeric value of the arguments - -```cpp -inline unsigned int umin( - unsigned int _X, - unsigned int _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -*_Y*
-Integer value - -### Return Value - -Return the minimum numeric value of the arguments - -## See also - -[Concurrency::direct3d Namespace](concurrency-direct3d-namespace.md) diff --git a/docs/parallel/amp/reference/concurrency-direct3d-namespace.md b/docs/parallel/amp/reference/concurrency-direct3d-namespace.md deleted file mode 100644 index 3c371c751ec..00000000000 --- a/docs/parallel/amp/reference/concurrency-direct3d-namespace.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -description: "Learn more about: Concurrency::direct3d Namespace" -title: "Concurrency::direct3d Namespace" -ms.date: "11/04/2016" -f1_keywords: ["amp/Concurrency::direct3d", "amprt/Concurrency::direct3d", "amp_short_vectors/Concurrency::direct3d", "amp_graphics/Concurrency::direct3d", "amp_math/Concurrency::direct3d"] -helpviewer_keywords: ["direct3d namespace"] -ms.assetid: 9566a2f1-4d5f-43e4-a3ac-676643d38420 ---- -# Concurrency::direct3d Namespace - -The `direct3d` namespace provides functions that support D3D interoperability. It lets you use D3D resources for compute in AMP code. It also allows use of resources created in AMP in D3D code, without creating redundant intermediate copies. You can incrementally accelerate the compute intensive sections of your DirectX applications by using C++ AMP, and use the D3D API on data produced from AMP computations. - -## Syntax - -```cpp -namespace direct3d; -``` - -## Members - -### Classes - -|Name|Description| -|----------|-----------------| -|[scoped_d3d_access_lock Class](scoped-d3d-access-lock-class.md)|An RAII wrapper for a D3D access lock on an `accelerator_view` object.| - -### Structures - -|Name|Description| -|----------|-----------------| -|[adopt_d3d_access_lock_t Structure](adopt-d3d-access-lock-t-structure.md)|Tag type to indicate the D3D access lock should be adopted rather than acquired.| - -### Functions - -|Name|Description| -|----------|-----------------| -|[abs](concurrency-direct3d-namespace-functions-amp.md#abs)|Returns the absolute value of the argument| -|[clamp](concurrency-direct3d-namespace-functions-amp.md#clamp)|Overloaded. Clamps _X to the specified _Min and _Max range| -|[countbits](concurrency-direct3d-namespace-functions-amp.md#countbits)|Counts the number of set bits in _X| -|[create_accelerator_view](concurrency-direct3d-namespace-functions-amp.md#create_accelerator_view)|Creates an [accelerator_view Class](accelerator-view-class.md) from a pointer to a Direct3D device interface| -|[d3d_access_lock](concurrency-direct3d-namespace-functions-amp.md#d3d_access_lock)|Acquires a lock on an accelerator_view to safely perform D3D operations on resources shared with the accelerator_view| -|[d3d_access_try_lock](concurrency-direct3d-namespace-functions-amp.md#d3d_access_try_lock)|Attempt to acquire the D3D access lock on an accelerator_view without blocking.| -|[d3d_access_unlock](concurrency-direct3d-namespace-functions-amp.md#d3d_access_unlock)|Release the D3D access lock on the given accelerator_view.| -|[firstbithigh](concurrency-direct3d-namespace-functions-amp.md#firstbithigh)|Gets the location of the first set bit in _X, starting from the highest order bit and working downward| -|[firstbitlow](concurrency-direct3d-namespace-functions-amp.md#firstbitlow)|Gets the location of the first set bit in _X, starting from the lowest order bit and working upward| -|[get_buffer](concurrency-direct3d-namespace-functions-amp.md#get_buffer)|Get the D3D buffer interface underlying an array.| -|[imax](concurrency-direct3d-namespace-functions-amp.md#imax)|Compares two values, returning the value that's greater.| -|[imin](concurrency-direct3d-namespace-functions-amp.md#imin)|Compares two values, returning the value that's smaller.| -|[is_timeout_disabled](concurrency-direct3d-namespace-functions-amp.md#is_timeout_disabled)|Returns a boolean flag indicating if timeout is disabled for the specified accelerator_view.| -|[mad](concurrency-direct3d-namespace-functions-amp.md#mad)|Overloaded. Performs an arithmetic multiply/add operation on three arguments: _X \* _Y + _Z| -|[make_array](concurrency-direct3d-namespace-functions-amp.md#make_array)|Create an array from a D3D buffer interface pointer.| -|[noise](concurrency-direct3d-namespace-functions-amp.md#noise)|Generates a random value by using the Perlin noise algorithm| -|[radians](concurrency-direct3d-namespace-functions-amp.md#radians)|Converts _X from degrees to radians| -|[rcp](concurrency-direct3d-namespace-functions-amp.md#rcp)|Calculates a fast, approximate reciprocal of the argument| -|[reversebits](concurrency-direct3d-namespace-functions-amp.md#reversebits)|Reverses the order of the bits in _X| -|[saturate](concurrency-direct3d-namespace-functions-amp.md#saturate)|Clamps _X within the range of 0 to 1| -|[sign](concurrency-direct3d-namespace-functions-amp.md#sign)|Overloaded. Returns the sign of the argument| -|[smoothstep](concurrency-direct3d-namespace-functions-amp.md#smoothstep)|Returns a smooth Hermite interpolation between 0 and 1, if _X is in the range [_Min, _Max].| -|[step](concurrency-direct3d-namespace-functions-amp.md#step)|Compares two values, returning 0 or 1 based on which value is greater| -|[umax](concurrency-direct3d-namespace-functions-amp.md#umax)|Compares two unsigned values, returning the value that's greater.| -|[umin](concurrency-direct3d-namespace-functions-amp.md#umin)|Compares two unsigned values, returning the value that's smaller.| - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md b/docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md deleted file mode 100644 index dea78f5cd4d..00000000000 --- a/docs/parallel/amp/reference/concurrency-fast-math-namespace-functions.md +++ /dev/null @@ -1,1286 +0,0 @@ ---- -description: "Learn more about: Concurrency::fast_math namespace functions" -title: "Concurrency::fast_math namespace functions" -ms.date: "11/04/2016" -f1_keywords: ["amp_math/Concurrency::fast_math::acos", "amp_math/Concurrency::fast_math::asin", "amp_math/Concurrency::fast_math::asinf", "amp_math/Concurrency::fast_math::atan2", "amp_math/Concurrency::fast_math::atan2f", "amp_math/Concurrency::fast_math::ceil", "amp_math/Concurrency::fast_math::ceilf", "amp_math/Concurrency::fast_math::cosf", "amp_math/Concurrency::fast_math::cosh", "amp_math/Concurrency::fast_math::exp", "amp_math/Concurrency::fast_math::exp2", "amp_math/Concurrency::fast_math::expf", "amp_math/Concurrency::fast_math::fabs", "amp_math/Concurrency::fast_math::floor", "amp_math/Concurrency::fast_math::floorf", "amp_math/Concurrency::fast_math::fmaxf", "amp_math/Concurrency::fast_math::fmin", "amp_math/Concurrency::fast_math::fmod", "amp_math/Concurrency::fast_math::fmodf", "amp_math/Concurrency::fast_math::frexpf", "amp_math/Concurrency::fast_math::isfinite", "amp_math/Concurrency::fast_math::isnan", "amp_math/Concurrency::fast_math::ldexp", "amp_math/Concurrency::fast_math::log", "amp_math/Concurrency::fast_math::log10", "amp_math/Concurrency::fast_math::log2", "amp_math/Concurrency::fast_math::log2f", "amp_math/Concurrency::fast_math::modf", "amp_math/Concurrency::fast_math::modff", "amp_math/Concurrency::fast_math::powf", "amp_math/Concurrency::fast_math::round", "amp_math/Concurrency::fast_math::rsqrt", "amp_math/Concurrency::fast_math::rsqrtf", "amp_math/Concurrency::fast_math::signbitf", "amp_math/Concurrency::fast_math::sin", "amp_math/Concurrency::fast_math::sincosf", "amp_math/Concurrency::fast_math::sinf", "amp_math/Concurrency::fast_math::sinhf", "amp_math/Concurrency::fast_math::sqrt", "amp_math/Concurrency::fast_math::tan", "amp_math/Concurrency::fast_math::tanf", "amp_math/Concurrency::fast_math::tanhf", "amp_math/Concurrency::fast_math::trunc"] -ms.assetid: f5763d62-795b-4de6-a7a5-c7115f158708 ---- -# Concurrency::fast_math namespace functions - -:::row::: - :::column span=""::: - [`acos`](#acos)\ - [`acosf`](#acosf)\ - [`asin`](#asin)\ - [`asinf`](#asinf)\ - [`atan`](#atan)\ - [`atan2`](#atan2)\ - [`atan2f`](#atan2f)\ - [`atanf`](#atanf)\ - [`ceil`](#ceil)\ - [`ceilf`](#ceilf)\ - [`cos`](#cos)\ - [`cosf`](#cosf)\ - [`cosh`](#cosh)\ - [`coshf`](#coshf)\ - [`exp`](#exp)\ - [`exp2`](#exp2)\ - [`exp2f`](#exp2f) - :::column-end::: - :::column span=""::: - [`expf`](#expf)\ - [`fabs`](#fabs)\ - [`fabsf`](#fabsf)\ - [`floor`](#floor)\ - [`floorf`](#floorf)\ - [`fmax`](#fmax)\ - [`fmaxf`](#fmaxf)\ - [`fmin`](#fmin)\ - [`fminf`](#fminf)\ - [`fmod`](#fmod)\ - [`fmodf`](#fmodf)\ - [`frexp`](#frexp)\ - [`frexpf`](#frexpf)\ - [`isfinite`](#isfinite)\ - [`isinf`](#isinf)\ - [`isnan`](#isnan) - :::column-end::: - :::column span=""::: - [`ldexp`](#ldexp)\ - [`ldexpf`](#ldexpf)\ - [`log`](#log)\ - [`log10`](#log10)\ - [`log10f`](#log10f)\ - [`log2`](#log2)\ - [`log2f`](#log2f)\ - [`logf`](#logf)\ - [`modf`](#modf)\ - [`modff`](#modff)\ - [`pow`](#pow)\ - [`powf`](#powf)\ - [`round`](#round)\ - [`roundf`](#roundf)\ - [`rsqrt`](#rsqrt)\ - [`rsqrtf`](#rsqrtf) - :::column-end::: - :::column span=""::: - [`signbit`](#signbit)\ - [`signbitf`](#signbitf)\ - [`sin`](#sin)\ - [`sincos`](#sincos)\ - [`sincosf`](#sincosf)\ - [`sinf`](#sinf)\ - [`sinh`](#sinh)\ - [`sinhf`](#sinhf)\ - [`sqrt`](#sqrt)\ - [`sqrtf`](#sqrtf)\ - [`tan`](#tan)\ - [`tanf`](#tanf)\ - [`tanh`](#tanh)\ - [`tanhf`](#tanhf)\ - [`trunc`](#trunc)\ - [`truncf`](#truncf) - :::column-end::: -:::row-end::: - -## acos - -Calculates the arccosine of the argument - -```cpp -inline float acos(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arccosine value of the argument - -## acosf - -Calculates the arccosine of the argument - -```cpp -inline float acosf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arccosine value of the argument - -## asin - -Calculates the arcsine of the argument - -```cpp -inline float asin(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arcsine value of the argument - -## asinf - -Calculates the arcsine of the argument - -```cpp -inline float asinf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arcsine value of the argument - -## atan - -Calculates the arctangent of the argument - -```cpp -inline float atan(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of the argument - -## atan2 - -Calculates the arctangent of _Y/_X - -```cpp -inline float atan2( - float _Y, - float _X) restrict(amp); -``` - -### Parameters - -*_Y*
-Floating-point value - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of _Y/_X - -## atan2f - -Calculates the arctangent of _Y/_X - -```cpp -inline float atan2f( - float _Y, - float _X) restrict(amp); -``` - -### Parameters - -*_Y*
-Floating-point value - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of _Y/_X - -## atanf - -Calculates the arctangent of the argument - -```cpp -inline float atanf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of the argument - -## ceil - -Calculates the ceiling of the argument - -```cpp -inline float ceil(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the ceiling of the argument - -## ceilf - -Calculates the ceiling of the argument - -```cpp -inline float ceilf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the ceiling of the argument - -## cosf - -Calculates the cosine of the argument - -```cpp -inline float cosf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cosine value of the argument - -## coshf - -Calculates the hyperbolic cosine value of the argument - -```cpp -inline float coshf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic cosine value of the argument - -## cos - -Calculates the cosine of the argument - -```cpp -inline float cos(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cosine value of the argument - -## cosh - -Calculates the hyperbolic cosine value of the argument - -```cpp -inline float cosh(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic cosine value of the argument - -## exp - -Calculates the base-e exponential of the argument - -```cpp -inline float exp(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e exponential of the argument - -## exp2 - -Calculates the base-2 exponential of the argument - -```cpp -inline float exp2(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-2 exponential of the argument - -## exp2f - -Calculates the base-2 exponential of the argument - -```cpp -inline float exp2f(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-2 exponential of the argument - -## expf - -Calculates the base-e exponential of the argument - -```cpp -inline float expf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e exponential of the argument - -## fabs - -Returns the absolute value of the argument - -```cpp -inline float fabs(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -### Return Value - -Returns the absolute value of the argument - -## fabsf - -Returns the absolute value of the argument - -```cpp -inline float fabsf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the absolute value of the argument - -## floor - -Calculates the floor of the argument - -```cpp -inline float floor(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the floor of the argument - -## floorf - -Calculates the floor of the argument - -```cpp -inline float floorf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the floor of the argument - -## fmax - -Determine the maximum numeric value of the arguments - -```cpp -inline float max( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -*_Y*
-Integer value - -### Return Value - -Return the maximum numeric value of the arguments - -## fmaxf - -Determine the maximum numeric value of the arguments - -```cpp -inline float fmaxf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Return the maximum numeric value of the arguments - -## fmin - -Determine the minimum numeric value of the arguments - -```cpp -inline float min( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -*_Y*
-Integer value - -### Return Value - -Return the minimum numeric value of the arguments - -## fminf - -Determine the minimum numeric value of the arguments - -```cpp -inline float fminf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Return the minimum numeric value of the arguments - -## fmod - -Calculates the floating-point remainder of _X/_Y - -```cpp -inline float fmod( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns the floating-point remainder of _X/_Y - -## fmodf - -Calculates the floating-point remainder of _X/_Y. - -```cpp -inline float fmodf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns the floating-point remainder of _X/_Y - -## frexp - -Gets the mantissa and exponent of _X - -```cpp -inline float frexp( - float _X, - _Out_ int* _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Exp*
-Returns the integer exponent of _X in floating-point value - -### Return Value - -Returns the mantissa _X - -## frexpf - -Gets the mantissa and exponent of _X - -```cpp -inline float frexpf( - float _X, - _Out_ int* _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Exp*
-Returns the integer exponent of _X in floating-point value - -### Return Value - -Returns the mantissa _X - -## isfinite - -Determines whether the argument has a finite value - -```cpp -inline int isfinite(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the argument has a finite value - -## isinf - -Determines whether the argument is an infinity - -```cpp -inline int isinf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the argument has an infinite value - -## isnan - -Determines whether the argument is a NaN - -```cpp -inline int isnan(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the argument has a NaN value - -## ldexp - -Computes a real number from the mantissa and exponent - -```cpp -inline float ldexp( - float _X, - int _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, mentissa - -*_Exp*
-Integer exponent - -### Return Value - -Returns _X \* 2^_Exp - -## ldexpf - -Computes a real number from the mantissa and exponent - -```cpp -inline float ldexpf( - float _X, - int _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, mentissa - -*_Exp*
-Integer exponent - -### Return Value - -Returns _X \* 2^_Exp - -## log - -Calculates the base-e logarithm of the argument - -```cpp -inline float log(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e logarithm of the argument - -## log10 - -Calculates the base-10 logarithm of the argument - -```cpp -inline float log10(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 logarithm of the argument - -## log10f - -Calculates the base-10 logarithm of the argument - -```cpp -inline float log10f(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 logarithm of the argument - -## log2 - -Calculates the base-2 logarithm of the argument - -```cpp -inline float log2(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-2 logarithm of the argument - -## log2f - -Calculates the base-2 logarithm of the argument - -```cpp -inline float log2f(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 logarithm of the argument - -## logf - -Calculates the base-e logarithm of the argument - -```cpp -inline float logf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e logarithm of the argument - -## modf - -Splits _X into fractional and integer parts. - -```cpp -inline float modf( - float _X, - float* _Ip) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Ip*
-Receives integer part of the value - -### Return Value - -Returns the signed fractional portion of _X - -## modff - -Splits _X into fractional and integer parts. - -```cpp -inline float modff( - float _X, - float* _Ip) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Ip*
-Receives integer part of the value - -### Return Value - -Returns the signed fractional portion of _X - -## pow - -Calculates _X raised to the power of _Y - -```cpp -inline float pow( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, base - -*_Y*
-Floating-point value, exponent - -### Return Value - -Returns the value of _X raised to the power of _Y - -## powf - -Calculates _X raised to the power of _Y - -```cpp -inline float powf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, base - -*_Y*
-Floating-point value, exponent - -### Return Value - -## round - -Rounds _X to the nearest integer - -```cpp -inline float round(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the nearest integer of _X - -## roundf - -Rounds _X to the nearest integer - -```cpp -inline float roundf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the nearest integer of _X - -## rsqrt - -Returns the reciprocal of the square root of the argument - -```cpp -inline float rsqrt(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the reciprocal of the square root of the argument - -## rsqrtf - -Returns the reciprocal of the square root of the argument - -```cpp -inline float rsqrtf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the reciprocal of the square root of the argument - -## signbit - -Determines whether the sign of _X is negative - -```cpp -inline int signbit(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the sign of _X is negative - -## signbitf - -Determines whether the sign of _X is negative - -```cpp -inline int signbitf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the sign of _X is negative - -## sin - -Calculates the sine value of the argument - -```cpp -inline float sin(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the sine value of the argument - -## sinf - -Calculates the sine value of the argument - -```cpp -inline float sinf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the sine value of the argument - -## sincos - -Calculates sine and cosine value of _X - -```cpp -inline void sincos( - float _X, - float* _S, - float* _C) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_S*
-Returns the sine value of _X - -*_C*
-Returns the cosine value of _X - -## sincosf - -Calculates sine and cosine value of _X - -```cpp -inline void sincosf( - float _X, - float* _S, - float* _C) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_S*
-Returns the sine value of _X - -*_C*
-Returns the cosine value of _X - -## sinh - -Calculates the hyperbolic sine value of the argument - -```cpp -inline float sinh(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic sine value of the argument - -## sinhf - -Calculates the hyperbolic sine value of the argument - -```cpp -inline float sinhf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic sine value of the argument - -## sqrt - -Calculates the squre root of the argument - -```cpp -inline float sqrt(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the squre root of the argument - -## sqrtf - -Calculates the squre root of the argument - -```cpp -inline float sqrtf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the squre root of the argument - -## tan - -Calculates the tangent value of the argument - -```cpp -inline float tan(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the tangent value of the argument - -## tanf - -Calculates the tangent value of the argument - -```cpp -inline float tanf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the tangent value of the argument - -## tanh - -Calculates the hyperbolic tangent value of the argument - -```cpp -inline float tanh(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic tangent value of the argument - -## tanhf - -Calculates the hyperbolic tangent value of the argument - -```cpp -inline float tanhf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic tangent value of the argument - -## trunc - -Truncates the argument to the integer component - -```cpp -inline float trunc(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the integer component of the argument - -## truncf - -Truncates the argument to the integer component - -```cpp -inline float truncf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the integer component of the argument - -## Requirements - -**Header:** amp_math.h -**Namespace:** Concurrency::fast_math - -## See also - -[Concurrency::fast_math Namespace](concurrency-fast-math-namespace.md) diff --git a/docs/parallel/amp/reference/concurrency-fast-math-namespace.md b/docs/parallel/amp/reference/concurrency-fast-math-namespace.md deleted file mode 100644 index 38e9403d86e..00000000000 --- a/docs/parallel/amp/reference/concurrency-fast-math-namespace.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -description: "Learn more about: Concurrency::fast_math Namespace" -title: "Concurrency::fast_math Namespace" -ms.date: "11/04/2016" -f1_keywords: ["amp_math/Concurrency::fast_math"] -ms.assetid: 54fed939-9902-49db-9f29-e98fd9821508 ---- -# Concurrency::fast_math Namespace - -Functions in the `fast_math` namespace have lower accuracy, support only single-precision (**`float`**), and call the DirectX intrinsics. There are two versions of each function, for example `cos` and `cosf`. Both versions take and return a **`float`**, but each calls the same DirectX intrinsic. - -## Syntax - -```cpp -namespace fast_math; -``` - -## Members - -### Functions - -|Name|Description| -|----------|-----------------| -|[cos](concurrency-fast-math-namespace-functions.md#cos)|Calculates the arccosine of the argument| -|[cosf](concurrency-fast-math-namespace-functions.md#cosf)|Calculates the arccosine of the argument| -|[asin](concurrency-fast-math-namespace-functions.md#asin)|Calculates the arcsine of the argument| -|[asinf](concurrency-fast-math-namespace-functions.md#asinf)|Calculates the arcsine of the argument| -|[atan](concurrency-fast-math-namespace-functions.md#atan)|Calculates the arctangent of the argument| -|[atan2](concurrency-fast-math-namespace-functions.md#atan2)|Calculates the arctangent of _Y/_X| -|[atan2f](concurrency-fast-math-namespace-functions.md#atan2f)|Calculates the arctangent of _Y/_X| -|[atanf](concurrency-fast-math-namespace-functions.md#atanf)|Calculates the arctangent of the argument| -|[ceil](concurrency-fast-math-namespace-functions.md#ceil)|Calculates the ceiling of the argument| -|[ceilf](concurrency-fast-math-namespace-functions.md#ceilf)|Calculates the ceiling of the argument| -|[cos](concurrency-fast-math-namespace-functions.md#cos)|Calculates the cosine of the argument| -|[cosf](concurrency-fast-math-namespace-functions.md#cosf)|Calculates the cosine of the argument| -|[cosh](concurrency-fast-math-namespace-functions.md#cosh)|Calculates the hyperbolic cosine value of the argument| -|[coshf](concurrency-fast-math-namespace-functions.md#coshf)|Calculates the hyperbolic cosine value of the argument| -|[exp](concurrency-fast-math-namespace-functions.md#exp)|Calculates the base-e exponential of the argument| -|[exp2](concurrency-fast-math-namespace-functions.md#exp2)|Calculates the base-2 exponential of the argument| -|[exp2f](concurrency-fast-math-namespace-functions.md#exp2f)|Calculates the base-2 exponential of the argument| -|[expf](concurrency-fast-math-namespace-functions.md#expf)|Calculates the base-e exponential of the argument| -|[fabs](concurrency-fast-math-namespace-functions.md#fabs)|Returns the absolute value of the argument| -|[fabsf](concurrency-fast-math-namespace-functions.md#fabsf)|Returns the absolute value of the argument| -|[floor](concurrency-fast-math-namespace-functions.md#floor)|Calculates the floor of the argument| -|[floorf](concurrency-fast-math-namespace-functions.md#floorf)|Calculates the floor of the argument| -|[fmax](concurrency-fast-math-namespace-functions.md#fmax)|Determine the maximum numeric value of the arguments| -|[fmaxf](concurrency-fast-math-namespace-functions.md#fmaxf)|Determine the maximum numeric value of the arguments| -|[fmin](concurrency-fast-math-namespace-functions.md#fmin)|Determine the minimum numeric value of the arguments| -|[fminf](concurrency-fast-math-namespace-functions.md#fminf)|Determine the minimum numeric value of the arguments| -|[fmod](concurrency-fast-math-namespace-functions.md#fmod)|Calculates the floating-point remainder of _X/_Y| -|[fmodf](concurrency-fast-math-namespace-functions.md#fmodf)|Calculates the floating-point remainder of _X/_Y| -|[frexp](concurrency-fast-math-namespace-functions.md#frexp)|Gets the mantissa and exponent of _X| -|[frexpf](concurrency-fast-math-namespace-functions.md#frexpf)|Gets the mantissa and exponent of _X| -|[isfinite](concurrency-fast-math-namespace-functions.md#isfinite)|Determines whether the argument has a finite value| -|[isinf](concurrency-fast-math-namespace-functions.md#isinf)|Determines whether the argument is an infinity| -|[isnan](concurrency-fast-math-namespace-functions.md#isnan)|Determines whether the argument is a NaN| -|[ldexp](concurrency-fast-math-namespace-functions.md#ldexp)|Computes a real number from the mantissa and exponent| -|[ldexpf](concurrency-fast-math-namespace-functions.md#ldexpf)|Computes a real number from the mantissa and exponent| -|[log](concurrency-fast-math-namespace-functions.md#log)|Calculates the base-e logarithm of the argument| -|[log10](concurrency-fast-math-namespace-functions.md#log10)|Calculates the base-10 logarithm of the argument| -|[log10f](concurrency-fast-math-namespace-functions.md#log10f)|Calculates the base-10 logarithm of the argument| -|[log2](concurrency-fast-math-namespace-functions.md#log2)|Calculates the base-2 logarithm of the argument| -|[log2f](concurrency-fast-math-namespace-functions.md#log2f)|Calculates the base-2 logarithm of the argument| -|[logf](concurrency-fast-math-namespace-functions.md#logf)|Calculates the base-e logarithm of the argument| -|[modf](concurrency-fast-math-namespace-functions.md#modf)|Splits _X into fractional and integer parts.| -|[modff](concurrency-fast-math-namespace-functions.md#modff)|Splits _X into fractional and integer parts.| -|[pow](concurrency-fast-math-namespace-functions.md#pow)|Calculates _X raised to the power of _Y| -|[powf](concurrency-fast-math-namespace-functions.md#powf)|Calculates _X raised to the power of _Y| -|[round](concurrency-fast-math-namespace-functions.md#round)|Rounds _X to the nearest integer| -|[roundf](concurrency-fast-math-namespace-functions.md#roundf)|Rounds _X to the nearest integer| -|[rsqrt](concurrency-fast-math-namespace-functions.md#rsqrt)|Returns the reciprocal of the square root of the argument| -|[rsqrtf](concurrency-fast-math-namespace-functions.md#rsqrtf)|Returns the reciprocal of the square root of the argument| -|[signbit](concurrency-fast-math-namespace-functions.md#signbit)|Returns the sign of the argument| -|[signbitf](concurrency-fast-math-namespace-functions.md#signbitf)|Returns the sign of the argument| -|[sin](concurrency-fast-math-namespace-functions.md#sin)|Calculates the sine value of the argument| -|[sincos](concurrency-fast-math-namespace-functions.md#sincos)|Calculates sine and cosine value of _X| -|[sincosf](concurrency-fast-math-namespace-functions.md#sincosf)|Calculates sine and cosine value of _X| -|[sinf](concurrency-fast-math-namespace-functions.md#sinf)|Calculates the sine value of the argument| -|[sinh](concurrency-fast-math-namespace-functions.md#sinh)|Calculates the hyperbolic sine value of the argument| -|[sinhf](concurrency-fast-math-namespace-functions.md#sinhf)|Calculates the hyperbolic sine value of the argument| -|[sqrt](concurrency-fast-math-namespace-functions.md#sqrt)|Calculates the square root of the argument| -|[sqrtf](concurrency-fast-math-namespace-functions.md#sqrtf)|Calculates the square root of the argument| -|[tan](concurrency-fast-math-namespace-functions.md#tan)|Calculates the tangent value of the argument| -|[tanf](concurrency-fast-math-namespace-functions.md#tanf)|Calculates the tangent value of the argument| -|[tanh](concurrency-fast-math-namespace-functions.md#tanh)|Calculates the hyperbolic tangent value of the argument| -|[tanhf](concurrency-fast-math-namespace-functions.md#tanhf)|Calculates the hyperbolic tangent value of the argument| -|[trunc](concurrency-fast-math-namespace-functions.md#trunc)|Truncates the argument to the integer component| -|[truncf](concurrency-fast-math-namespace-functions.md#truncf)|Truncates the argument to the integer component| - -## Requirements - -**Header:** amp_math.h - -**Namespace:** Concurrency::fast_math - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md b/docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md deleted file mode 100644 index 946f6478c8f..00000000000 --- a/docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md +++ /dev/null @@ -1,177 +0,0 @@ ---- -description: "Learn more about: Concurrency::graphics::direct3d namespace functions" -title: "Concurrency::graphics::direct3d namespace functions" -ms.date: "11/04/2016" -f1_keywords: ["amp_graphics/Concurrency::graphics::direct3d::get_sampler", "amp_graphics/Concurrency::graphics::direct3d::make_sampler", "amp_graphics/Concurrency::graphics::direct3d::make_texture"] -ms.assetid: 11ee1d42-333e-4ae9-95ac-4cf68c06d13d ---- -# Concurrency::graphics::direct3d namespace functions - -:::row::: - :::column span=""::: - [`get_sampler`](#get_sampler)\ - [`get_texture`](#get_texture) - :::column-end::: - :::column span=""::: - [`make_sampler`](#make_sampler) - :::column-end::: - :::column span=""::: - [`make_texture`](#make_texture) - :::column-end::: - :::column span=""::: - [`msad4`](#msad4) - :::column-end::: -:::row-end::: - -## get_sampler - -Get the D3D sampler state interface on the given accelerator view that represents the specified sampler object. - -```cpp -IUnknown* get_sampler( - const Concurrency::accelerator_view& _Av, - const sampler& _Sampler) restrict(amp); -``` - -### Parameters - -*_Av*
-A D3D accelerator view on which the D3D sampler state is to be created. - -*_Sampler*
-A sampler object for which the underlying D3D sampler state interface is created. - -### Return Value - -The IUnknown interface pointer corresponding to the D3D sampler state that represents the given sampler. - -## get_texture - -Gets the Direct3D texture interface underlying the specified [texture](texture-class.md) object. - -```cpp -template< - typename value_type, - int _Rank -> -_Ret_ IUnknown *get_texture( - const texture& _Texture) restrict(cpu); - -template< - typename value_type, - int _Rank -> -_Ret_ IUnknown *get_texture( - const writeonly_texture_view& _Texture) restrict(cpu); - -template< - typename value_type, - int _Rank -> -_Ret_ IUnknown *get_texture( - const texture_view& _Texture) restrict(cpu); -``` - -### Parameters - -*value_type*
-The element type of the texture. - -*_Rank*
-The rank of the texture. - -*_Texture*
-A texture or texture view associated with the accelerator_view for which the underlying Direct3D texture interface is returned. - -### Return Value - -The IUnknown interface pointer corresponding to the Direct3D texture underlying the texture. - -## make_sampler - -Create a sampler from a D3D sampler state interface pointer. - -```cpp -sampler make_sampler(_In_ IUnknown* _D3D_sampler) restrict(amp); -``` - -### Parameters - -*_D3D_sampler*
-IUnknown interface pointer of the D3D sampler state to create the sampler from. - -### Return Value - -A sampler represents the provided D3D sampler state. - -## make_texture - -Creates a [texture](texture-class.md) object by using the specified parameters. - -```cpp -template< - typename value_type, - int _Rank -> -texture make_texture( - const Concurrency::accelerator_view& _Av, - _In_ IUnknown* _D3D_texture, - DXGI_FORMAT _View_format = DXGI_FORMAT_UNKNOWN) restrict(cpu); -``` - -### Parameters - -*value_type*
-The type of the elements in the texture. - -*_Rank*
-The rank of the texture. - -*_Av*
-A D3D accelerator view on which the texture is to be created. - -*_D3D_texture*
-IUnknown interface pointer of the D3D texture to create the texture from. - -*_View_format*
-The DXGI format to use for views created from this texture. Pass DXGI_FORMAT_UNKNOWN (the default) to derive the format from the underlying format of _D3D_texture and the value_type of this template. The provided format must be compatible with the underlying format of _D3D_texture. - -### Return Value - -A texture using the provided D3D texture. - -## msad4 - -Compares a 4-byte reference value and an 8-byte source value and accumulates a vector of 4 sums. Each sum corresponds to the masked sum of absolute differences of different byte alignments between the reference value and the source value. - -```cpp -inline uint4 msad4( - uint _Reference, - uint2 _Source, - uint4 _Accum) restrict(amp); -``` - -### Parameters - -*_Reference*
-The reference array of 4 bytes in one uint value - -*_Source*
-The source array of 8 bytes in a vector of two uint values. - -*_Accum*
-A vector of 4 values to be added to the masked sum of absolute differences of the different byte alignments between the reference value and the source value. - -### Return Value - -Returns a vector of 4 sums. Each sum corresponds to the masked sum of absolute differences of different byte alignments between the reference value and the source value. - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** Concurrency::graphics::direct3d - -## See also - -[Concurrency::graphics::direct3d Namespace](concurrency-graphics-direct3d-namespace.md) diff --git a/docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md b/docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md deleted file mode 100644 index ff00042ac40..00000000000 --- a/docs/parallel/amp/reference/concurrency-graphics-direct3d-namespace.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -description: "Learn more about: Concurrency::graphics::direct3d Namespace" -title: "Concurrency::graphics::direct3d Namespace" -ms.date: "11/04/2016" -f1_keywords: ["amp_graphics/Concurrency::graphics::direct3d", "amp_short_vectors/Concurrency::graphics::direct3d"] -ms.assetid: be283331-07cf-46e4-91a1-e8aa85d4ec8e ---- -# Concurrency::graphics::direct3d Namespace - -Provides the [get_texture](concurrency-graphics-direct3d-namespace-functions.md#get_texture) and [make_texture](concurrency-graphics-direct3d-namespace-functions.md#make_texture) methods. - -## Syntax - -```cpp -namespace direct3d; -``` - -## Members - -### Functions - -|Name

Description| -|--------------------------| -|[get_sampler](concurrency-graphics-direct3d-namespace-functions.md#get_sampler)

Get the Direct3D sampler state interface on the given accelerator view that represents the specified sampler object.| -|[get_texture](concurrency-graphics-direct3d-namespace-functions.md#get_texture)

Gets the Direct3D texture interface underlying the specified [texture](texture-class.md) object.| -|[make_sampler](concurrency-graphics-direct3d-namespace-functions.md#make_sampler)

Create a sampler from a Direct3D sampler state interface pointer.| -|[make_texture](concurrency-graphics-direct3d-namespace-functions.md#make_texture)

Creates a [texture](texture-class.md) object by using the specified parameters.| -|[msad4](concurrency-graphics-direct3d-namespace-functions.md#msad4)

Compares a 4-byte reference value and an 8-byte source value and accumulates a vector of 4 sums.| - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** Concurrency::graphics - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md b/docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md deleted file mode 100644 index 212776f47b4..00000000000 --- a/docs/parallel/amp/reference/concurrency-graphics-namespace-enums.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -description: "Learn more about: Concurrency::graphics namespace enums" -title: "Concurrency::graphics namespace enums" -ms.date: "11/04/2016" -f1_keywords: ["amp_graphics/concurrency::graphics::address_mode", "amp_graphics/concurrency::graphics::filter_mode"] -ms.assetid: 1d2e1859-a3d7-4d3d-8e03-1a877a86b3e0 ---- -# Concurrency::graphics namespace enums - -|Name|Description| -|-|-| -|[_mode Enumeration](#address_mode)|[filter_mode Enumeration](#filter_mode)| - -## address_mode Enumeration - -Enumeration type use to denote address modes supported for texture sampling. - -```cpp -enum address_mode; -``` - -## filter_mode Enumeration - -Enumeration type use to denote filter modes supported for texture sampling. - -```cpp -enum filter_mode; -``` - -## Requirements - -**Header:** amp_graphics.h -**Namespace:** Concurrency::graphics - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md b/docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md deleted file mode 100644 index ac0f29d6764..00000000000 --- a/docs/parallel/amp/reference/concurrency-graphics-namespace-functions.md +++ /dev/null @@ -1,295 +0,0 @@ ---- -description: "Learn more about: Concurrency::graphics namespace functions" -title: "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) - -## copy Function (Concurrency::graphics Namespace) - -Copies a source texture into a destination buffer, or copies a source buffer into a destination buffer. The general form of this function is `copy(src, dest)`. - -```cpp -template < - typename _Src_type, - typename = typename std::enable_if::is_texture, void>::type> -> -void copy ( - const _Src_type& _Src, - _Out_ void* _Dst, - unsigned int _Dst_byte_size); - -template < - typename _Src_type, - typename = typename std::enable_if::is_texture, void>::type -> -void copy( - const _Src_type& _Src, - const index<_Src_type::rank>& _Src_offset, - const extent<_Src_type::rank>& _Copy_extent, - _Out_ void* _Dst, - unsigned int _Dst_byte_size); - -template < - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type -> -void copy( - const void* _Src, - unsigned int _Src_byte_size, _Dst_type& _Dst); - -template < - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type -> -void copy( - const void* _Src, - unsigned int _Src_byte_size, - _Dst_type& _Dst, - const index<_Dst_type::rank>& _Dst_offset, - const extent<_Dst_type::rank>& _Copy_extent); - -template < - typename InputIterator, - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type -> -void copy(InputIterator first, InputIterator last, _Dst_type& _Dst); - -template < - typename InputIterator, - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type ->void copy(InputIterator first, InputIterator last, _Dst_type& _Dst, - const index<_Dst_type::rank>& _Dst_offset, - const extent<_Dst_type::rank>& _Copy_extent); - -template < - typename _Src_type, - typename OutputIterator, - typename = typename std::enable_if::is_texture&& !details::texture_traits::is_texture, void>::type -> -void copy( - const _Src_type& _Src, OutputIterator _Dst); - -template < - typename _Src_type, - typename OutputIterator, - typename = typename std::enable_if::is_texture&& !details::texture_traits::is_texture, void>::type -> -void copy ( - const _Src_type& _Src, - const index<_Src_type::rank>& _Src_offset, - const extent<_Src_type::rank>& _Copy_extent, OutputIterator _Dst); - -template < - typename _Src_type, - typename _Dst_type, - typename = typename std::enable_if::is_texture&& details::texture_traits<_Dst_type>::is_texture, void>::type -> -void copy ( - const _Src_type& _Src, _Dst_type& _Dst); - -template < - typename _Src_type, - typename _Dst_type, - typename = typename std::enable_if::is_texture&& details::texture_traits<_Dst_type>::is_texture, - void>::type -> -void copy ( - const _Src_type& _Src, - const index<_Src_type::rank>& _Src_offset, _Dst_type& _Dst, - const index<_Dst_type::rank>& _Dst_offset, - const extent<_Src_type::rank>& _Copy_extent); -``` - -### Parameters - -*_Copy_extent*
-The extent of the texture section to be copied. - -*_Dst*
-The object to copy to. - -*_Dst_byte_size*
-The number of bytes in the destination. - -*_Dst_type*
-The type of the destination object. - -*_Dst_offset*
-The offset into the destination at which to begin copying. - -*InputIterator*
-The type of the input iterator. - -*OutputIterator*
-The type of the output iterator. - -*_Src*
-To object to copy. - -*_Src_byte_size*
-The number of bytes in the source. - -*_Src_type*
-The type of the source object. - -*_Src_offset*
-The offset into the source from which to begin copying. - -*first*
-A beginning iterator into the source container. - -*last*
-An ending iterator into the source container. - -## copy_async Function (Concurrency::graphics Namespace) - -Asynchronously copies a source texture into a destination buffer, or copies a source buffer into a destination buffer, and then returns a [completion_future](completion-future-class.md) object that can be waited on. Data can't be copied when code is running on an accelerator. The general form of this function is `copy(src, dest)`. - -```cpp -template< - typename _Src_type, - typename = typename std::enable_if::is_texture, void>::type -> -concurrency::completion_future copy_async( - const _Src_type& _Src, - _Out_ void* _Dst, - unsigned int _Dst_byte_size); - -template< - typename _Src_type, - typename = typename std::enable_if::is_texture, void>::type -> -concurrency::completion_future copy_async( - const _Src_type& _Src, - const index<_Src_type::rank>& _Src_offset, - const extent<_Src_type::rank>& _Copy_extent, - _Out_ void* _Dst, - unsigned int _Dst_byte_size); - -template < - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type -> -concurrency::completion_future copy_async( - const void* _Src, - unsigned int _Src_byte_size, _Dst_type& _Dst); - -template < - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type -> -concurrency::completion_future copy_async( - const void* _Src, - unsigned int _Src_byte_size, _Dst_type& _Dst, - const index<_Dst_type::rank>& _Dst_offset, - const extent<_Dst_type::rank>& _Copy_extent); - -template < - typename InputIterator, - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type -> -concurrency::completion_future copy_async(InputIterator first, InputIterator last, _Dst_type& _Dst); - -template < - typename InputIterator, - typename _Dst_type, - typename = typename std::enable_if::is_texture, void>::type -> -concurrency::completion_future copy_async(InputIterator first, InputIterator last, _Dst_type& _Dst, - const index<_Dst_type::rank>& _Dst_offset, - const extent<_Dst_type::rank>& _Copy_extent); - -template < - typename _Src_type, - typename OutputIterator, - typename = typename std::enable_if::is_texture&& !details::texture_traits::is_texture, void>::type -> -concurrency::completion_future copy_async(_Src_type& _Src, OutputIterator _Dst); - -template < - typename _Src_type, - typename OutputIterator, - typename = typename std::enable_if::is_texture&& !details::texture_traits::is_texture, void>::type -> -concurrency::completion_future copy_async(_Src_type& _Src, - const index<_Src_type::rank>& _Src_offset, - const extent<_Src_type::rank>& _Copy_extent, - OutputIterator _Dst); - -template < - typename _Src_type, - typename _Dst_type, - typename = typename std::enable_if::is_texture&& details::texture_traits<_Dst_type>::is_texture, void>::type -> -concurrency::completion_future copy_async(_Src_type& _Src, _Dst_type& _Dst); - -template < - typename _Src_type, - typename _Dst_type, - typename = typename std::enable_if::is_texture&& details::texture_traits<_Dst_type>::is_texture, void>::type -> -concurrency::completion_future copy_async(_Src_type& _Src, - const index<_Src_type::rank>& _Src_offset, _Dst_type &_Dst, - const index<_Dst_type::rank>& _Dst_offset, - const extent<_Src_type::rank>& _Copy_extent); -``` - -### Parameters - -*_Copy_extent*
-The extent of the texture section to be copied. - -*_Dst*
-The object to copy to. - -*_Dst_byte_size*
-The number of bytes in the destination. - -*_Dst_type*
-The type of the destination object. - -*_Dst_offset*
-The offset into the destination at which to begin copying. - -*InputIterator*
-The type of the input iterator. - -*OutputIterator*
-The type of the output iterator. - -*_Src*
-To object to copy. - -*_Src_byte_size*
-The number of bytes in the source. - -*_Src_type*
-The type of the source object. - -*_Src_offset*
-The offset into the source from which to begin copying. - -*first*
-A beginning iterator into the source container. - -*last*
-An ending iterator into the source container. - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** Concurrency::graphics - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/concurrency-graphics-namespace.md b/docs/parallel/amp/reference/concurrency-graphics-namespace.md deleted file mode 100644 index cf1517f385d..00000000000 --- a/docs/parallel/amp/reference/concurrency-graphics-namespace.md +++ /dev/null @@ -1,83 +0,0 @@ ---- -description: "Learn more about: Concurrency::graphics Namespace" -title: "Concurrency::graphics Namespace" -ms.date: "11/04/2016" -f1_keywords: ["AMP_GRAPHICS/Concurrency"] -ms.assetid: 4529d3b1-d7da-4ffb-82bf-080915e0f23e ---- -# Concurrency::graphics Namespace - -The graphics namespace provides types and functions that are designed for graphics programming. - -## Syntax - -```cpp -namespace graphics; -``` - -## Members - -### Namespaces - -|Name|Description| -|----------|-----------------| -|[Concurrency::graphics::direct3d Namespace](concurrency-graphics-direct3d-namespace.md)|Provides functions for Direct3D interop.| - -### Typedefs - -|Name|Description| -|----------|-----------------| -|`uint`|The element type for [uint_2 Class](uint-2-class.md), [uint_3 Class](uint-3-class.md), and [uint_4 Class](uint-4-class.md). Defined as `typedef unsigned int uint;`.| - -### Enumerations - -|Name|Description| -|----------|-----------------| -|[address_mode Enumeration](concurrency-graphics-namespace-enums.md#address_mode).|Specifies address modes supported for texture sampling.| -|[filter_mode Enumeration](concurrency-graphics-namespace-enums.md#filter_mode)|Specifies filter modes supported for texture sampling.| - -### Classes - -|Name|Description| -|----------|-----------------| -|[texture Class](texture-class.md)|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), or scalar type norm, or unorm (defined in concurrency::graphics), or eligible short vector types defined in concurrency::graphics.| -|[writeonly_texture_view Class](writeonly-texture-view-class.md)|A writeonly_texture_view provides writeonly access to a texture.| -|[double_2 Class](double-2-class.md)|Represents a short vector of 2 **`double`** values.| -|[double_3 Class](double-3-class.md)|Represents a short vector of 3 **`double`** values.| -|[double_4 Class](double-4-class.md)|Represents a short vector of 4 **`double`** values.| -|[float_2 Class](float-2-class.md)|Represents a short vector of 2 **`float`** values.| -|[float_3 Class](float-3-class.md)|Represents a short vector of 3 **`float`** values.| -|[float_4 Class](float-4-class.md)|Represents a short vector of 4 **`float`** values.| -|[int_2 Class](int-2-class.md)|Represents a short vector of 2 **`int`** values.| -|[int_3 Class](int-3-class.md)|Represents a short vector of 3 **`int`** values.| -|[int_4 Class](int-4-class.md)|Represents a short vector of 4 **`int`** values.| -|[norm_2 Class](norm-2-class.md)|Represents a short vector of 2 `norm` values.| -|[norm_3 Class](norm-3-class.md)|Represents a short vector of 3 `norm` values.| -|[norm_4 Class](norm-4-class.md)|Represents a short vector of 4 `norm` values.| -|[uint_2 Class](uint-2-class.md)|Represents a short vector of 2 `uint` values.| -|[uint_3 Class](uint-3-class.md)|Represents a short vector of 3 `uint` values.| -|[uint_4 Class](uint-4-class.md)|Represents a short vector of 4 `uint` values.| -|[unorm_2 Class](unorm-2-class.md)|Represents a short vector of 2 `unorm` values.| -|[unorm_3 Class](unorm-3-class.md)|Represents a short vector of 3 `unorm` values.| -|[unorm_4 Class](unorm-4-class.md)|Represents a short vector of 4 `unorm` values.| -|[sampler Class](sampler-class.md)|Represents the sampler configuration used for texture sampling.| -|[short_vector Structure](short-vector-structure.md)|Provides a basic implementation of a short vector of values.| -|[short_vector_traits Structure](short-vector-traits-structure.md)|Provides for retrieval of the length and type of a short vector.| -|[texture_view Class](texture-view-class.md)|Provides read access and write access to a texture.| - -### Functions - -|Name|Description| -|----------|-----------------| -|[copy](concurrency-graphics-namespace-functions.md#copy)|Overloaded. Copies the contents of the source texture into the destination host buffer.| -|[copy_async](concurrency-graphics-namespace-functions.md#copy_async)|Overloaded. Asynchronously copies the contents of the source texture into the destination host buffer.| - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** Concurrency - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-namespace-constants-amp.md b/docs/parallel/amp/reference/concurrency-namespace-constants-amp.md deleted file mode 100644 index b3e6db41fd9..00000000000 --- a/docs/parallel/amp/reference/concurrency-namespace-constants-amp.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: "Learn more about: Concurrency namespace constants (AMP)" -title: "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) - -## HLSL_MAX_NUM_BUFFERS Constant - -The maximum number of buffers allowed by DirectX. - -```cpp -static const UINT HLSL_MAX_NUM_BUFFERS = 64 + 128; -``` - -## MODULENAME_MAX_LENGTH Constant - -Stores the maximum length of the module name. This value must be the same on the compiler and runtime. - -```cpp -static const UINT MODULENAME_MAX_LENGTH = 1024; -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md b/docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md deleted file mode 100644 index df6d09b52f2..00000000000 --- a/docs/parallel/amp/reference/concurrency-namespace-cpp-amp.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -description: "Learn more about: Concurrency Namespace (C++ AMP)" -title: "Concurrency Namespace (C++ AMP)" -ms.date: "11/04/2016" -f1_keywords: ["AMP/Concurrency"] -helpviewer_keywords: ["Concurrency namespace"] -ms.assetid: b5aab265-3bac-42c5-8ead-f92ce05ef267 ---- -# Concurrency Namespace (C++ AMP) - -Provides classes and functions that accelerate the execution of C++ code on data-parallel hardware. For more information, see [C++ AMP Overview](../cpp-amp-overview.md) - -## Syntax - -```cpp -namespace Concurrency; -``` - -## Members - -### Namespaces - -|Name|Description| -|----------|-----------------| -|[Concurrency::direct3d Namespace](concurrency-direct3d-namespace.md)|Provides functions that support D3D interoperability. Enables seamless use of D3D resources for compute in AMP code and the use of resources created in AMP in D3D code, without creating redundant intermediate copies. You can use C++ AMP to incrementally accelerate the compute-intensive sections of your DirectX applications and use the D3D API on data produced from AMP computations.| -|[Concurrency::fast_math Namespace](concurrency-fast-math-namespace.md)|Functions in the `fast_math` namespace are not C99-conformant. Only single-precision versions of each function are provided. These functions use the DirectX intrinsic functions, which are faster than the corresponding functions in the `precise_math` namespace and do not require extended double-precision support on the accelerator, but they are less accurate. There are two versions of each function for source-level compatibility with C99 code; both versions take and return single-precision values.| -|[Concurrency::graphics Namespace](concurrency-graphics-namespace.md)|Provides types and functions that are designed for graphics programming.| -|[Concurrency::precise_math Namespace](concurrency-precise-math-namespace.md)|Functions in the `precise_math` namespace are C99 conformant. Both single-precision and double-precision versions of each function are included. These functions—this includes the single-precision functions—require extended double-precision support on the accelerator.| - -### Classes - -|Name|Description| -|----------|-----------------| -|[accelerator Class](accelerator-class.md)|Represents an abstraction of a physical DP-optimized compute node.| -|[accelerator_view Class](accelerator-view-class.md)|Represents a virtual device abstraction on a C++ AMP data-parallel accelerator.| -|[accelerator_view_removed Class](accelerator-view-removed-class.md)|The exception that is thrown when an underlying DirectX call fails due to the Windows timeout-detection-and-recovery mechanism.| -|[array Class](array-class.md)|A data aggregate on an `accelerator_view` in the grid domain. It is a collection of variables, one for each element in a grid domain. Each variable holds a value that corresponds to some C++ type.| -|[array_view Class](array-view-class.md)|Represents a view into the data in an array\.| -|[completion_future Class](completion-future-class.md)|Represents a future that corresponds to a C++ AMP asynchronous operation.| -|[extent Class](extent-class.md)|Represents a vector of N integer values that specify the bounds of an N-dimensional space that has an origin of 0. The values in the coordinate vector are ordered from most significant to least significant. For example, in Cartesian 3-dimensional space, the extent vector (7,5,3) represents a space in which the z coordinate ranges from 0 to 7, the y coordinate ranges from 0 to 5, and the x coordinate ranges from 0 to 3.| -|[index Class](index-class.md)|Defines an N-dimensional index point.| -|[invalid_compute_domain Class](invalid-compute-domain-class.md)|The exception that's thrown when the runtime can't start a kernel by using the compute domain specified at the `parallel_for_each` call site.| -|[out_of_memory Class](out-of-memory-class.md)|The exception that is thrown when a method fails because of a lack of system or device memory.| -|[runtime_exception Class](runtime-exception-class.md)|The base type for exceptions in the C++ AMP library.| -|[tile_barrier Class](tile-barrier-class.md)|A capability class that is only creatable by the system and is passed to a tiled `parallel_for_each` lambda as part of the `tiled_index` parameter. It provides one method, `wait()`, whose purpose is to synchronize execution of threads that are running in the thread group (tile).| -|[tiled_extent Class](tiled-extent-class.md)|A `tiled_extent` object is an `extent` object of one to three dimensions that subdivides the extent space into one-dimensional, two-dimensional, or three-dimensional tiles.| -|[tiled_index Class](tiled-index-class.md)|Provides an index into a `tiled_grid` object. This class has properties to access element relative to the local tile origin and relative to the global origin.| -|[uninitialized_object Class](uninitialized-object-class.md)|The exception that is thrown when an uninitialized object is used.| -|[unsupported_feature Class](unsupported-feature-class.md)|The exception that is thrown when an unsupported feature is used.| - -### Enumerations - -|Name|Description| -|----------|-----------------| -|[access_type Enumeration](concurrency-namespace-enums-amp.md#access_type)|Specifies the data access type.| -|[queuing_mode Enumeration](concurrency-namespace-enums-amp.md#queuing_mode)|Specifies the queuing modes that are supported on the accelerator.| - -### Operators - -|Operator|Description| -|--------------|-----------------| -|[operator== Operator (C++ AMP)](concurrency-namespace-operators-amp.md#operator_eq_eq)|Determines whether the specified data structures are equal.| -|[operator!= Operator (C++ AMP)](concurrency-namespace-operators-amp.md#operator_neq)|Determines whether the specified data structures are unequal.| -|[operator+ Operator (C++ AMP)](concurrency-namespace-operators-amp.md#operator_add)|Computes the component-wise sum of the specified arguments.| -|[operator- Operator (C++ AMP)](concurrency-namespace-operators-amp.md#operator-)|Computes the component-wise difference between the specified arguments.| -|[operator* Operator (C++ AMP)](concurrency-namespace-operators-amp.md#operator_star)|Computes the component-wise product of the specified arguments.| -|[operator/ Operator (C++ AMP)](concurrency-namespace-operators-amp.md#operator_div)|Computes the component-wise quotient of the specified arguments.| -|[operator% Operator (C++ AMP)](concurrency-namespace-operators-amp.md#operator_mod)|Computes the modulus of the first specified argument by the second specified argument.| - -### Functions - -|Name|Description| -|----------|-----------------| -|[all_memory_fence](concurrency-namespace-functions-amp.md#all_memory_fence)|Blocks execution of all threads in a tile until all memory accesses have been completed.| -|[amp_uninitialize](concurrency-namespace-functions-amp.md#amp_uninitialize)|Uninitializes the C++ AMP runtime.| -|[atomic_compare_exchange](concurrency-namespace-functions-amp.md#atomic_compare_exchange)|Overloaded. If the value stored at the specified location compares equal to the first specified value, then the second specified value is stored in the same location as an atomic operation.| -|[atomic_exchange](concurrency-namespace-functions-amp.md#atomic_exchange)|Overloaded. Sets the value stored at the specified location to the specified value as an atomic operation.| -|[atomic_fetch_add](concurrency-namespace-functions-amp.md#atomic_fetch_add)|Overloaded. Sets the value stored at the specified location to the sum of that value and a specified value as an atomic operation.| -|[atomic_fetch_and](concurrency-namespace-functions-amp.md#atomic_fetch_and)|Overloaded. Sets the value stored at the specified location to the bitwise `and` of that value and a specified value as an atomic operation.| -|[atomic_fetch_dec](concurrency-namespace-functions-amp.md#atomic_fetch_dec)|Overloaded. Decrements the value stored at the specified location and stores the result in the same location as an atomic operation.| -|[atomic_fetch_inc](concurrency-namespace-functions-amp.md#atomic_fetch_inc)|Overloaded. Increments the value stored at the specified location and stores the result in the same location as an atomic operation.| -|[atomic_fetch_max](concurrency-namespace-functions-amp.md#atomic_fetch_max)|Overloaded. Sets the value stored at the specified location to the larger of that value and a specified value as an atomic operation.| -|[atomic_fetch_min](concurrency-namespace-functions-amp.md#atomic_fetch_min)|Overloaded. Sets the value stored at the specified location to the smaller of that value and a specified value as an atomic operation.| -|[atomic_fetch_or](concurrency-namespace-functions-amp.md#atomic_fetch_or)|Overloaded. Sets the value stored at the specified location to the bitwise `or` of that value and a specified value as an atomic operation.| -|[atomic_fetch_sub](concurrency-namespace-functions-amp.md#atomic_fetch_sub)|Overloaded. Sets the value stored at the specified location to the difference of that value and a specified value as an atomic operation.| -|[atomic_fetch_xor](concurrency-namespace-functions-amp.md#atomic_fetch_xor)|Overloaded. Sets the value stored at the specified location to the bitwise `xor` of that value and a specified value as an atomic operation.| -|[copy](concurrency-namespace-functions-amp.md#copy)|Copies a C++ AMP object. All synchronous data transfer requirements are met. Data can't be copied when code is running code on an accelerator. The general form of this function is `copy(src, dest)`.| -|[copy_async](concurrency-namespace-functions-amp.md#copy_async)|Copies a C++ AMP object and returns [completion_future](completion-future-class.md) that can be waited on. Data can't be copied when code is running on an accelerator. The general form of this function is `copy(src, dest)`.| -|[direct3d_abort](concurrency-namespace-functions-amp.md#direct3d_abort)|Aborts the execution of a function that has the `restrict(amp)` restriction clause.| -|[direct3d_errorf](concurrency-namespace-functions-amp.md#direct3d_errorf)|Prints a formatted string to the Visual Studio **Output** window and raises a [runtime_exception](runtime-exception-class.md) exception that has the same formatting string.| -|[direct3d_printf](concurrency-namespace-functions-amp.md#direct3d_printf)|Prints a formatted string to the Visual Studio **Output** window. It is called from a function that has the `restrict(amp)` restriction clause.| -|[global_memory_fence](concurrency-namespace-functions-amp.md#global_memory_fence)|Blocks execution of all threads in a tile until all global memory accesses have been completed.| -|[parallel_for_each Function (C++ AMP)](concurrency-namespace-functions-amp.md#parallel_for_each)|Runs a function across the compute domain.| -|[tile_static_memory_fence](concurrency-namespace-functions-amp.md#tile_static_memory_fence)|Blocks execution of all threads in a tile until `tile_static` memory accesses have been completed.| - -## Constants - -|Name|Description| -|----------|-----------------| -|[HLSL_MAX_NUM_BUFFERS Constant](concurrency-namespace-constants-amp.md#hlsl_max_num_buffers)|The maximum number of buffers allowed by DirectX.| -|[MODULENAME_MAX_LENGTH Constant](concurrency-namespace-constants-amp.md#modulename_max_length)|Stores the maximum length of the module name. This value must be the same on the compiler and the runtime.| - -## Requirements - -**Header:** amp.h - -## See also - -[Reference (C++ AMP)](reference-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-namespace-enums-amp.md b/docs/parallel/amp/reference/concurrency-namespace-enums-amp.md deleted file mode 100644 index 55a34e9c713..00000000000 --- a/docs/parallel/amp/reference/concurrency-namespace-enums-amp.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -description: "Learn more about: Concurrency namespace enums (AMP)" -title: "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) - -## access_type Enumeration - -Enumeration type used to denote the various types of access to data. - -```cpp -enum access_type; -``` - -### Values - -|Name|Description| -|----------|-----------------| -|`access_type_auto`|Automatically choose the best `access_type` for the accelerator.| -|`access_type_none`|Dedicated. The allocation is only accessible on the accelerator and not on the CPU.| -|`access_type_read`|Shared. The allocation is accessible on the accelerator and is readable on the CPU.| -|`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 - -Specifies the queuing modes that are supported on the accelerator. - -```cpp -enum queuing_mode; -``` - -### Values - -|Name|Description| -|----------|-----------------| -|`queuing_mode_immediate`|A queuing mode that specifies that any commands, for example, [parallel_for_each Function (C++ AMP)](concurrency-namespace-functions-amp.md#parallel_for_each), are sent to the corresponding accelerator device as soon as they return to the caller.| -|`queuing_mode_automatic`|A queuing mode that specifies that commands be queued up on a command queue that corresponds to the [accelerator_view](accelerator-view-class.md) object. Commands are sent to the device when [accelerator_view::flush](accelerator-view-class.md#flush) is called.| - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-namespace-functions-amp.md b/docs/parallel/amp/reference/concurrency-namespace-functions-amp.md deleted file mode 100644 index 5020d2c580b..00000000000 --- a/docs/parallel/amp/reference/concurrency-namespace-functions-amp.md +++ /dev/null @@ -1,686 +0,0 @@ ---- -description: "Learn more about: Concurrency namespace functions (AMP)" -title: "Concurrency namespace functions (AMP)" -ms.date: "11/04/2016" -f1_keywords: ["amp/Concurrency::all_memory_fence", "amp/Concurrency::atomic_compare_exchange", "amp/Concurrency::atomic_fetch_dec", "amp/Concurrency::atomic_fetch_max", "amp/Concurrency::atomic_fetch_min", "amp/Concurrency::copy", "amp/Concurrency::direct3d_abort", "amp/Concurrency::direct3d_printf", "amp/Concurrency::global_memory_fence", "amp/Concurrency::tile_static_memory_fence"] -ms.assetid: 2bef0985-cb90-4ece-90b9-66529aec73c9 ---- -# Concurrency namespace functions (AMP) - -:::row::: - :::column span=""::: - [`all_memory_fence`](#all_memory_fence)\ - [`amp_uninitialize`](#amp_uninitialize)\ - [`atomic_compare_exchange`](#atomic_compare_exchange)\ - [`atomic_exchange`](#atomic_exchange)\ - [`atomic_fetch_add`](#atomic_fetch_add)\ - [`atomic_fetch_and`](#atomic_fetch_and) - :::column-end::: - :::column span=""::: - [`atomic_fetch_dec`](#atomic_fetch_dec)\ - [`atomic_fetch_inc`](#atomic_fetch_inc)\ - [`atomic_fetch_max`](#atomic_fetch_max)\ - [`atomic_fetch_min`](#atomic_fetch_min)\ - [`atomic_fetch_or`](#atomic_fetch_or) - :::column-end::: - :::column span=""::: - [`atomic_fetch_sub`](#atomic_fetch_sub)\ - [`atomic_fetch_xor`](#atomic_fetch_xor)\ - [`copy`](#copy)\ - [`copy_async`](#copy_async)\ - [`direct3d_abort`](#direct3d_abort) - :::column-end::: - :::column span=""::: - [`direct3d_errorf`](#direct3d_errorf)\ - [`direct3d_printf`](#direct3d_printf)\ - [`global_memory_fence`](#global_memory_fence)\ - [`parallel_for_each`](#parallel_for_each)\ - [`tile_static_memory_fence`](#tile_static_memory_fence) - :::column-end::: -:::row-end::: - -## all_memory_fence - -Blocks execution of all threads in a tile until all memory accesses have been completed. This ensures that all memory accesses are visible to other threads in the thread tile, and are executed in program order. - -```cpp -inline void all_memory_fence(const tile_barrier& _Barrier) restrict(amp); -``` - -### Parameters - -*_Barrier*
-A `tile_barrier` object. - -## amp_uninitialize - -Uninitializes the C++ AMP runtime. It is legal to call this function multiple times during an applications lifetime. Calling any C++ AMP API after calling this function will reinitialize the C++ AMP runtime. Note that it is illegal to use C++ AMP objects across calls to this function and doing so will result in undefined behavior. Also, concurrently calling this function and any other AMP APIs is illegal and would result in undefined behavior. - -```cpp -void __cdecl amp_uninitialize(); -``` - -## atomic_compare_exchange - -Atomically compares the value stored at a memory location specified in the first argument for equality with the value of the second specified argument, and if the values are the same, the value at the memory location is changed to that of the third specified argument. - -```cpp -inline bool atomic_compare_exchange( - _Inout_ int* _Dest, - _Inout_ int* _Expected_value, - int value - ) restrict(amp) - -inline bool atomic_compare_exchange( - _Inout_ unsigned int* _Dest, - _Inout_ unsigned int* _Expected_value, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-The location from which one of the values to be compared is read, and to which the new value, if any, is to be stored. - -*_Expected_value*
-The location from which the second value to be compared is read. - -*value*
-The value to be stored to the memory location specified in by `_Dest` if `_Dest` is equal to `_Expected_value`. - -### Return Value - -**`true`** if the operation is successful; otherwise, **`false`**. - -## atomic_exchange Function (C++ AMP) - -Sets the value of destination location as an atomic operation. - -```cpp -inline int atomic_exchange( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_exchange( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) - -inline float atomic_exchange( - _Inout_ float* _Dest, - float value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-Pointer to the destination location. - -*value*
-The new value. - -### Return Value - -The original value of the destination location. - -## atomic_fetch_add Function (C++ AMP) - -Atomically add a value to the value of a memory location. - -```cpp -inline int atomic_fetch_add( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_fetch_add( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-Pointer to the memory location. - -*value*
-The value to be added. - -### Return Value - -The original value of the memory location. - -## atomic_fetch_and Function (C++ AMP) - -Atomically performs a bitwise AND operation of a value and the value of a memory location. - -```cpp -inline int atomic_fetch_and( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_fetch_and( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-Pointer to the memory location. - -*value*
-The value to use in the bitwise AND calculation. - -### Return Value - -The original value of the memory location. - -## atomic_fetch_dec - -Atomically decrements the value stored at the specified memory location. - -```cpp -inline int atomic_fetch_dec(_Inout_ int* _Dest - ) restrict(amp) - -inline unsigned int atomic_fetch_dec(_Inout_ unsigned int* _Dest) restrict(amp); -``` - -### Parameters - -*_Dest*
-The location in memory of the value to be decremented. - -### Return Value - -The original value stored at the memory location. - -## atomic_fetch_inc - -Atomically increments the value stored at the specified memory location. - -```cpp -inline int atomic_fetch_inc(_Inout_ int* _Dest) restrict(amp); - -inline unsigned int atomic_fetch_inc(_Inout_ unsigned int* _Dest) restrict(amp); -``` - -### Parameters - -*_Dest*
-The location in memory of the value to be incremented. - -### Return Value - -The original value stored at the memory location. - -## atomic_fetch_max - -Atomically computes the maximum value between the value stored at the memory location specified in the first argument and the value specified in the second argument, and stores it at the same memory location. - -```cpp -inline int atomic_fetch_max( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_fetch_max( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-The location from which one of the values to be compared is read, and to which the maximum of the two values is to be stored. - -*value*
-The value to be compared to the value at the specified location. - -### Return Value - -The original value stored at the specified location location. - -## atomic_fetch_min - -Atomically computes the minimum value between the value stored at the memory location specified in the first argument and the value specified in the second argument, and stores it at the same memory location. - -```cpp -inline int atomic_fetch_min( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_fetch_min( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-The location from which one of the values to be compared is read, and to which the minimum of the two values is to be stored. - -*value*
-The value to be compared to the value at the specified location. - -### Return Value - -The original value stored at the specified location location. - -## atomic_fetch_or Function (C++ AMP) - -Atomically performs a bitwise OR operation with a value and the value of a memory location. - -```cpp -inline int atomic_fetch_or( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_fetch_or( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-Pointer to the memory location. - -*value*
-The value to use in the bitwise OR calculation. - -### Return Value - -The original value of the memory location. - -## atomic_fetch_sub Function (C++ AMP) - -Atomically subtracts a value from a memory location. - -```cpp -inline int atomic_fetch_sub( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_fetch_sub( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-Pointer to the destination location. - -*value*
-The value to be subtracted. - -### Return Value - -The original value of the memory location. - -## atomic_fetch_xor Function (C++ AMP) - -Atomically performs an bitwise XOR operation of a value and a memory location. - -```cpp -inline int atomic_fetch_xor( - _Inout_ int* _Dest, - int value - ) restrict(amp) - -inline unsigned int atomic_fetch_xor( - _Inout_ unsigned int* _Dest, - unsigned int value - ) restrict(amp) -``` - -### Parameters - -*_Dest*
-Pointer to the memory location. - -*value*
-The value to use in the XOR calculation. - -### Return Value - -The original value of the memory location. - -## copy - -Copies a C++ AMP object. All synchronous data transfer requirements are met. You can't copy data when running code on an accelerator. The general form of this function is `copy(src, dest)`. - -```cpp -template -void copy( - const array& _Src, - array& _Dest); - -template -void copy( - InputIterator _SrcFirst, - InputIterator _SrcLast, - array& _Dest); - -template -void copy( - InputIterator _SrcFirst, - array& _Dest); - -template -void copy( - const array& _Src, - OutputIterator _DestIter); - -template -void copy( - const array& _Src, - array_view& _Dest); - -template -void copy( - const array_view& _Src, - array& _Dest); - -template -void copy( - const array_view& _Src, - array& _Dest); - -template -void copy( - const array_view& _Src, - array_view& _Dest); - -template -void copy( - const array_view& _Src, - array_view& _Dest); - -template -void copy( - InputIterator _SrcFirst, - InputIterator _SrcLast, - array_view& _Dest); - -template -void copy( - InputIterator _SrcFirst, - array_view& _Dest); - -template -void copy( - const array_view& _Src, - OutputIterator _DestIter); -``` - -### Parameters - -*_Dest*
-The object to copy to. - -*_DestIter*
-An output iterator to the beginning position at destination. - -*InputIterator*
-The type of the input iterator. - -*OutputIterator*
-The type of the output iterator. - -*_Rank*
-The rank of the object to copy from or the object to copy to. - -*_Src*
-To object to copy. - -*_SrcFirst*
-A beginning iterator into the source container. - -*_SrcLast*
-An ending iterator into the source container. - -*value_type*
-The data type of the elements that are copied. - -## copy_async - -Copies a C++ AMP object and returns a [completion_future](completion-future-class.md) object that can be waited on. You can't copy data when running code on an accelerator. The general form of this function is `copy(src, dest)`. - -```cpp -template -concurrency::completion_future copy_async( - const array& _Src, - array& _Dest); - -template -concurrency::completion_future copy_async(InputIterator _SrcFirst, InputIterator _SrcLast, - array& _Dest); - -template -concurrency::completion_future copy_async(InputIterator _SrcFirst, - array& _Dest); - -template -concurrency::completion_future copy_async( - const array& _Src, OutputIterator _DestIter); - -template -concurrency::completion_future copy_async( - const array& _Src, - array_view& _Dest); - -template -concurrency::completion_future copy_async( - const array_view& _Src, - array& _Dest); - -template -concurrency::completion_future copy_async( - const array_view& _Src, - array& _Dest); - -template -concurrency::completion_future copy_async( - const array_view& _Src, - array_view& _Dest); - -template -concurrency::completion_future copy_async( - const array_view& _Src, - array_view& _Dest); - -template -concurrency::completion_future copy_async(InputIterator _SrcFirst, InputIterator _SrcLast, - array_view& _Dest); - -template -concurrency::completion_future copy_async(InputIterator _SrcFirst, - array_view& _Dest); - -template -concurrency::completion_future copy_async( - const array_view& _Src, OutputIterator _DestIter); -``` - -### Parameters - -*_Dest*
-The object to copy to. - -*_DestIter*
-An output iterator to the beginning position at destination. - -*InputIterator*
-The type of the input iterator. - -*OutputIterator*
-The type of the output iterator. - -*_Rank*
-The rank of the object to copy from or the object to copy to. - -*_Src*
-To object to copy. - -*_SrcFirst*
-A beginning iterator into the source container. - -*_SrcLast*
-An ending iterator into the source container. - -*value_type*
-The data type of the elements that are copied. - -### Return Value - -A `future` that can be waited on. - -## direct3d_abort - -Aborts the execution of a function with the `restrict(amp)` restriction clause. When the AMP runtime detects the call, it raises a [runtime_exception](runtime-exception-class.md) exception with the error message "Reference Rasterizer: Shader abort instruction hit". - -```cpp -void direct3d_abort() restrict(amp); -``` - -## direct3d_errorf - -Prints a formatted string to the Visual Studio output window. It is called from a function with the `restrict(amp)` restriction clause. When the AMP runtime detects the call, it raises a [runtime_exception](runtime-exception-class.md) exception with the same formatting string. - -```cpp -void direct3d_errorf( - const char *, -...) restrict(amp); -``` - -## direct3d_printf - -Prints a formatted string to the Visual Studio output window. It is called from a function with the `restrict(amp)` restriction clause. - -```cpp -void direct3d_printf( - const char *, -...) restrict(amp); -``` - -## global_memory_fence - -Blocks execution of all threads in a tile until all global memory accesses have been completed. This ensures that global memory accesses are visible to other threads in the thread tile, and are executed in program order. - -```cpp -inline void global_memory_fence(const tile_barrier& _Barrier) restrict(amp); -``` - -### Parameters - -*_Barrier*
-A tile_barrier object - -## parallel_for_each Function (C++ AMP) - -Runs a function across the compute domain. For more information, see [C++ AMP Overview](../../../parallel/amp/cpp-amp-overview.md). - -```cpp -template -void parallel_for_each( - const extent<_Rank>& _Compute_domain, - const _Kernel_type& _Kernel); - -template -void parallel_for_each( - const tiled_extent<_Dim0, _Dim1, _Dim2>& _Compute_domain, - const _Kernel_type& _Kernel); - -template -void parallel_for_each( - const tiled_extent<_Dim0, _Dim1>& _Compute_domain, - const _Kernel_type& _Kernel); - -template -void parallel_for_each( - const tiled_extent<_Dim0>& _Compute_domain, - const _Kernel_type& _Kernel); - -template -void parallel_for_each( - const accelerator_view& _Accl_view, - const extent<_Rank>& _Compute_domain, - const _Kernel_type& _Kernel); - -template -void parallel_for_each( - const accelerator_view& _Accl_view, - const tiled_extent<_Dim0, _Dim1, _Dim2>& _Compute_domain, - const _Kernel_type& _Kernel); - -template -void parallel_for_each( - const accelerator_view& _Accl_view, - const tiled_extent<_Dim0, _Dim1>& _Compute_domain, - const _Kernel_type& _Kernel); - -template -void parallel_for_each( - const accelerator_view& _Accl_view, - const tiled_extent<_Dim0>& _Compute_domain, - const _Kernel_type& _Kernel); -``` - -### Parameters - -*_Accl_view*
-The `accelerator_view` object to run the parallel computation on. - -*_Compute_domain*
-An `extent` object that contains the data for the computation. - -*_Dim0*
-The dimension of the `tiled_extent` object. - -*_Dim1*
-The dimension of the `tiled_extent` object. - -*_Dim2*
-The dimension of the `tiled_extent` object. - -*_Kernel*
-A lambda or function object that takes an argument of type "index\<_Rank>" and performs the parallel computation. - -*_Kernel_type*
-A lambda or functor. - -*_Rank*
-The rank of the extent. - -## tile_static_memory_fence - -Blocks execution of all threads in a tile until all outstanding `tile_static` memory accesses have been completed. This ensures that `tile_static` memory accesses are visible to other threads in the thread tile, and that accesses are executed in program order. - -```cpp -inline void tile_static_memory_fence(const tile_barrier& _Barrier) restrict(amp); -``` - -### Parameters - -*_Barrier*
-A tile_barrier object. - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-namespace-operators-amp.md b/docs/parallel/amp/reference/concurrency-namespace-operators-amp.md deleted file mode 100644 index 3275296c1f8..00000000000 --- a/docs/parallel/amp/reference/concurrency-namespace-operators-amp.md +++ /dev/null @@ -1,288 +0,0 @@ ---- -description: "Learn more about: Concurrency namespace operators (AMP)" -title: "Concurrency namespace operators (AMP)" -ms.date: "11/04/2016" -ms.assetid: 77f1ae17-1eb2-480d-8fe5-66d4c24bb91e ---- -# Concurrency namespace operators (AMP) - -:::row::: - :::column span=""::: - [`operator==`](#operator_eq_eq)\ - [`operator!=`](#operator_neq) - :::column-end::: - :::column span=""::: - [`operator+`](#operator_add)\ - [`operator-`](#operator-) - :::column-end::: - :::column span=""::: - [`operator*`](#operator_star)\ - [`operator/`](#operator_div) - :::column-end::: - :::column span=""::: - [`operator%`](#operator_mod) - :::column-end::: -:::row-end::: - -## operator== - -Determines whether the specified arguments are equal. - -```cpp -template < - int _Rank, - template class _Tuple_type -> -bool operator== ( - const _Tuple_type<_Rank>& _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp); -``` - -### Parameters - -*_Rank*
-The rank of the tuple arguments. - -*_Lhs*
-One of the tuples to compare. - -*_Rhs*
-One of the tuples to compare. - -### Return Value - -**`true`** if the tuples are equal; otherwise, **`false`**. - -## operator!= - -Determines whether the specified arguments are not equal. - -```cpp -template < - int _Rank, - template class _Tuple_type -> -bool operator!= ( - const _Tuple_type<_Rank>& _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp); -``` - -### Parameters - -*_Rank*
-The rank of the tuple arguments. - -*_Lhs*
-One of the tuples to compare. - -*_Rhs*
-One of the tuples to compare. - -### Return Value - -**`true`** if the tuples are not equal; otherwise, **`false`**. - -## operator+ - -Computes the component-wise sum of the specified arguments. - -```cpp -template < - int _Rank, - template class _Tuple_type -> -class _Tuple_type> _Tuple_type<_Rank> operator+( - const _Tuple_type<_Rank>& _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp,cpu); - -template < - int _Rank, - template class _Tuple_type -> -class _Tuple_type> _Tuple_type<_Rank> operator+( - const _Tuple_type<_Rank>& _Lhs, - typename _Tuple_type<_Rank>::value_type _Rhs) restrict(amp,cpu); - -template < - int _Rank, - template class _Tuple_type -> -class _Tuple_type> _Tuple_type<_Rank> operator+( - typename _Tuple_type<_Rank>::value_type _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rank*
-The rank of the tuple arguments. - -*_Lhs*
-One of the arguments to add. - -*_Rhs*
-One of the arguments to add. - -### Return Value - -The component-wise sum of the specified arguments. - -## operator- - -Computes the component-wise difference between the specified arguments. - -```cpp -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator-( - const _Tuple_type<_Rank>& _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp,cpu); - -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator-( - const _Tuple_type<_Rank>& _Lhs, - typename _Tuple_type<_Rank>::value_type _Rhs) restrict(amp,cpu); - -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator-( - typename _Tuple_type<_Rank>::value_type _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rank*
-The rank of the tuple arguments. - -*_Lhs*
-The argument to be subtracted from. - -*_Rhs*
-The argument to subtract. - -### Return Value - -The component-wise difference between the specified arguments. - -## operator* - -Computes the component-wise product of the specified arguments. - -```cpp -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator*( - const _Tuple_type<_Rank>& _Lhs, - typename _Tuple_type<_Rank>::value_type _Rhs) restrict(amp,cpu); - -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator*( - typename _Tuple_type<_Rank>::value_type _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp, cpu); -``` - -### Parameters - -*_Rank*
-The rank of the tuple arguments. - -*_Lhs*
-One of the tuples to multiply. - -*_Rhs*
-One of the tuples to multiply. - -### Return Value - -The component-wise product of the specified arguments. - -## operator/ - -Computes the component-wise quotient of the specified arguments. - -```cpp -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator/( - const _Tuple_type<_Rank>& _Lhs, - typename _Tuple_type<_Rank>::value_type _Rhs) restrict(amp,cpu); - -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator/( - typename _Tuple_type<_Rank>::value_type _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rank*
-The rank of the tuple arguments. - -*_Lhs*
-The tuple to be divided. - -*_Rhs*
-The tuple to divide by. - -### Return Value - -The component-wise quotient of the specified arguments. - -## operator% - -Computes the modulus of the first specified argument by the second specified argument. - -```cpp -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator%( - const _Tuple_type<_Rank>& _Lhs, - typename _Tuple_type<_Rank>::value_type _Rhs) restrict(amp,cpu); - -template < - int _Rank, - template class _Tuple_type -> -_Tuple_type<_Rank> operator%( - typename _Tuple_type<_Rank>::value_type _Lhs, - const _Tuple_type<_Rank>& _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rank*
-The rank of the tuple arguments. - -*_Lhs*
-The tuple from which the modulo is calculated. - -*_Rhs*
-The tuple to modulo by. - -### Return Value - -The result of the first specified argument modulus the second specified argument. - -## See also - -[Concurrency Namespace](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md b/docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md deleted file mode 100644 index 0df3345b355..00000000000 --- a/docs/parallel/amp/reference/concurrency-precise-math-namespace-functions.md +++ /dev/null @@ -1,2757 +0,0 @@ ---- -description: "Learn more about: Concurrency::precise_math namespace functions" -title: "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 - -:::row::: - :::column span=""::: - [`acos`](#acos)\ - [`acosf`](#acosf)\ - [`acosh`](#acosh)\ - [`acoshf`](#acoshf)\ - [`asin`](#asin)\ - [`asinf`](#asinf)\ - [`asinh`](#asinh)\ - [`asinhf`](#asinhf)\ - [`atan`](#atan)\ - [`atan2`](#atan2)\ - [`atan2f`](#atan2f)\ - [`atanf`](#atanf)\ - [`atanh`](#atanh)\ - [`atanhf`](#atanhf)\ - [`cbrt`](#cbrt)\ - [`cbrtf`](#cbrtf)\ - [`ceil`](#ceil)\ - [`ceilf`](#ceilf)\ - [`copysign`](#copysign)\ - [`copysignf`](#copysignf)\ - [`cos`](#cos)\ - [`cosf`](#cosf)\ - [`cosh`](#cosh)\ - [`coshf`](#coshf)\ - [`cospi`](#cospi)\ - [`cospif`](#cospif)\ - [`erf`](#erf)\ - [`erfc`](#erfc)\ - [`erfcf`](#erfcf)\ - [`erfcinv`](#erfcinv)\ - [`erfcinvf`](#erfcinvf)\ - [`erff`](#erff)\ - [`erfinv`](#erfinv) - :::column-end::: - :::column span=""::: - [`erfinvf`](#erfinvf)\ - [`exp`](#exp)\ - [`exp10`](#exp10)\ - [`exp10f`](#exp10f)\ - [`exp2`](#exp2)\ - [`exp2f`](#exp2f)\ - [`expf`](#expf)\ - [`expm1`](#expm1)\ - [`expm1f`](#expm1f)\ - [`fabs`](#fabs)\ - [`fabsf`](#fabsf)\ - [`floor`](#floor)\ - [`fdim`](#fdim)\ - [`fdimf`](#fdimf)|\ - [`floorf`](#floorf)\ - [`fma`](#fma)\ - [`fmaf`](#fmaf)\ - [`fmax`](#fmax)\ - [`fmaxf`](#fmaxf)\ - [`fmin`](#fmin)\ - [`fminf`](#fminf)\ - [`fmod`](#fmod)\ - [`fmodf`](#fmodf)\ - [`fpclassify`](#fpclassify)\ - [`frexp`](#frexp)\ - [`frexpf`](#frexpf)\ - [`hypot`](#hypot)\ - [`hypotf`](#hypotf)\ - [`ilogb`](#ilogb)\ - [`ilogbf`](#ilogbf)\ - [`isfinite`](#isfinite)\ - [`isinf`](#isinf)\ - [`isnan`](#isnan) - :::column-end::: - :::column span=""::: - [`isnormal`](#isnormal)\ - [`ldexp`](#ldexp)\ - [`ldexpf`](#ldexpf)\ - [`lgamma`](#lgamma)\ - [`lgammaf`](#lgammaf)\ - [`log`](#log)\ - [`log10`](#log10)\ - [`log10f`](#log10f)\ - [`log1p`](#log1p)\ - [`log1pf`](#log1pf)\ - [`log2`](#log2)\ - [`log2f`](#log2f)\ - [`logb`](#logb)\ - [`logbf`](#logbf)\ - [`logf`](#logf)\ - [`modf`](#modf)\ - [`modff`](#modff)\ - [`nan`](#nan)\ - [`nanf`](#nanf)\ - [`nearbyint`](#nearbyint)\ - [`nearbyintf`](#nearbyintf)\ - [`nextafter`](#nextafter)\ - [`nextafterf`](#nextafterf)\ - [`phi`](#phi)\ - [`phif`](#phif)\ - [`pow`](#pow)\ - [`powf`](#powf)\ - [`probit`](#probit)\ - [`probitf`](#probitf)\ - [`rcbrt`](#rcbrt)\ - [`rcbrtf`](#rcbrtf)\ - [`remainder`](#remainder)\ - [`remainderf`](#remainderf) - :::column-end::: - :::column span=""::: - [`remquo`](#remquo)\ - [`remquof`](#remquof)\ - [`round`](#round)\ - [`roundf`](#roundf)\ - [`rsqrt`](#rsqrt)\ - [`rsqrtf`](#rsqrtf)\ - [`scalb`](#scalb)\ - [`scalbf`](#scalbf)\ - [`scalbn`](#scalbn)\ - [`scalbnf`](#scalbnf)\ - [`signbit`](#signbit)\ - [`signbitf`](#signbitf)\ - [`sin`](#sin)\ - [`sincos`](#sincos)\ - [`sincosf`](#sincosf)\ - [`sinf`](#sinf)\ - [`sinh`](#sinh)\ - [`sinhf`](#sinhf)\ - [`sinpi`](#sinpi)\ - [`sinpif`](#sinpif)\ - [`sqrt`](#sqrt)\ - [`sqrtf`](#sqrtf)\ - [`tan`](#tan)\ - [`tanf`](#tanf)\ - [`tanh`](#tanh)\ - [`tanhf`](#tanhf)\ - [`tanpi`](#tanpi)\ - [`tanpif`](#tanpif)\ - [`tgamma`](#tgamma)\ - [`tgammaf`](#tgammaf)\ - [`trunc`](#trunc)\ - [`truncf`](#truncf) - :::column-end::: -:::row-end::: - -## acos - -Calculates the arccosine of the argument - -```cpp -inline float acos(float _X) restrict(amp); - -inline double acos(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arccosine value of the argument - -## acosf - -Calculates the arccosine of the argument - -```cpp -inline float acosf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arccosine value of the argument - -## acosh - -Calculates the inverse hyperbolic cosine of the argument - -```cpp -inline float acosh(float _X) restrict(amp); - -inline double acosh(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse hyperbolic cosine value of the argument - -## acoshf - -Calculates the inverse hyperbolic cosine of the argument - -```cpp -inline float acoshf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse hyperbolic cosine value of the argument - -## asin - -Calculates the arcsine of the argument - -```cpp -inline float asin(float _X) restrict(amp); - -inline double asin(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arcsine value of the argument - -## asinf - -Calculates the arcsine of the argument - -```cpp -inline float asinf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arcsine value of the argument - -## asinh - -Calculates the inverse hyperbolic sine of the argument - -```cpp -inline float asinh(float _X) restrict(amp); - -inline double asinh(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse hyperbolic sine value of the argument - -## asinhf - -Calculates the inverse hyperbolic sine of the argument - -```cpp -inline float asinhf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse hyperbolic sine value of the argument - -## atan - -Calculates the arctangent of the argument - -```cpp -inline float atan(float _X) restrict(amp); - -inline double atan(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of the argument - -## atan2 - -Calculates the arctangent of _Y/_X - -```cpp -inline float atan2( - float _Y, - float _X) restrict(amp); - -inline double atan2( - double _Y, - double _X) restrict(amp); -``` - -### Parameters - -*_Y*
-Floating-point value - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of _Y/_X - -## atan2f - -Calculates the arctangent of _Y/_X - -```cpp -inline float atan2f( - float _Y, - float _X) restrict(amp); -``` - -### Parameters - -*_Y*
-Floating-point value - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of _Y/_X - -## atanf - -Calculates the arctangent of the argument - -```cpp -inline float atanf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the arctangent value of the argument - -## atanh - -Calculates the inverse hyperbolic tangent of the argument - -```cpp -inline float atanh(float _X) restrict(amp); - -inline double atanh(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse hyperbolic tangent value of the argument - -## atanhf - -Calculates the inverse hyperbolic tangent of the argument - -```cpp -inline float atanhf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse hyperbolic tangent value of the argument - -## cbrt - -Computes the real cube root of the argument - -```cpp -inline float cbrt(float _X) restrict(amp); - -inline double cbrt(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the real cube root of the argument - -## cbrtf - -Computes the real cube root of the argument - -```cpp -inline float cbrtf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the real cube root of the argument - -## ceil - -Calculates the ceiling of the argument - -```cpp -inline float ceil(float _X) restrict(amp); - -inline double ceil(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the ceiling of the argument - -## ceilf - -Calculates the ceiling of the argument - -```cpp -inline float ceilf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the ceiling of the argument - -## copysign - -Produces a value with the magnitude of _X and the sign of _Y - -```cpp -inline float copysign( - float _X, - float _Y) restrict(amp); - -inline double copysign( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns a value with the magnitude of _X and the sign of _Y - -## copysignf - -Produces a value with the magnitude of _X and the sign of _Y - -```cpp -inline float copysignf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns a value with the magnitude of _X and the sign of _Y - -## cos - -Calculates the cosine of the argument - -```cpp -inline float cos(float _X) restrict(amp); - -inline double cos(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cosine value of the argument - -## cosf - -Calculates the cosine of the argument - -```cpp -inline float cosf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cosine value of the argument - -## cosh - -Calculates the hyperbolic cosine value of the argument - -```cpp -inline float cosh(float _X) restrict(amp); - -inline double cosh(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic cosine value of the argument - -## coshf - -Calculates the hyperbolic cosine value of the argument - -```cpp -inline float coshf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic cosine value of the argument - -## cospi - -Calculates the cosine value of pi \* _X - -```cpp -inline float cospi(float _X) restrict(amp); - -inline double cospi(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cosine value of pi \* _X - -## cospif - -Calculates the cosine value of pi \* _X - -```cpp -inline float cospif(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cosine value of pi \* _X - -## erf - -Computes the error function of _X - -```cpp -inline float erf(float _X) restrict(amp); - -inline double erf(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the error function of _X - -## erfc - -Computes the complementary error function of _X - -```cpp -inline float erfc(float _X) restrict(amp); - -inline double erfc(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the complementary error function of _X - -## erfcf - -Computes the complementary error function of _X - -```cpp -inline float erfcf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the complementary error function of _X - -## erfcinv - -Computes the inverse complementary error function of _X - -```cpp -inline float erfcinv(float _X) restrict(amp); - -inline double erfcinv(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse complementary error function of _X - -## erfcinvf - -Computes the inverse complementary error function of _X - -```cpp -inline float erfcinvf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse complementary error function of _X - -## erff - -Computes the error function of _X - -```cpp -inline float erff(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the error function of _X - -## erfinv - -Computes the inverse error function of _X - -```cpp -inline float erfinv(float _X) restrict(amp); - -inline double erfinv(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse error function of _X - -## erfinvf - -Computes the inverse error function of _X - -```cpp -inline float erfinvf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse error function of _X - -## exp10 - -Calculates the base-10 exponential of the argument - -```cpp -inline float exp10(float _X) restrict(amp); - -inline double exp10(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 exponential of the argument - -## exp10f - -Calculates the base-10 exponential of the argument - -```cpp -inline float exp10f(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 exponential of the argument - -## expm1 - -Calculates the base-e exponential of the argument, minus 1 - -```cpp -inline float expm1(float exponent) restrict(amp); - -inline double expm1(double exponent) restrict(amp); -``` - -### Parameters - -*exponent*
-The exponential term *n* of the mathematical expression `e`n, where `e` is the base of the natural logarithm. - -### Return Value - -Returns the base-e exponential of the argument, minus 1 - -## expm1f - -Calculates the base-e exponential of the argument, minus 1 - -```cpp -inline float expm1f(float exponent) restrict(amp); -``` - -### Parameters - -*exponent*
-The exponential term *n* of the mathematical expression `e`n, where `e` is the base of the natural logarithm. - -### Return Value - -Returns the base-e exponential of the argument, minus 1 - -## exp - -Calculates the base-e exponential of the argument - -```cpp -inline float exp(float _X) restrict(amp); - -inline double exp(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e exponential of the argument - -## expf - -Calculates the base-e exponential of the argument - -```cpp -inline float expf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e exponential of the argument - -## exp2 - -Calculates the base-2 exponential of the argument - -```cpp -inline float exp2(float _X) restrict(amp); - -inline double exp2(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-2 exponential of the argument - -## exp2f - -Calculates the base-2 exponential of the argument - -```cpp -inline float exp2f(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-2 exponential of the argument - -## fabs - -Returns the absolute value of the argument - -```cpp -inline float fabs(float _X) restrict(amp); - -inline double fabs(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the absolute value of the argument - -## fabsf - -Returns the absolute value of the argument - -```cpp -inline float fabsf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the absolute value of the argument - -## fdim - -Computes the positive difference between the arguments. - -```cpp -inline float fdim( - float _X, - float _Y -) restrict(amp); -inline double fdim( - double _X, - double _Y -) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value -*_Y*
-Floating-point value - -### Return Value - -The difference between _X and _Y if _X is greater than _Y; otherwise, +0. - -## fdimf - -Computes the positive difference between the arguments. - -```cpp -inline float fdimf( - float _X, - float _Y -) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value -*_Y*
-Floating-point value - -### Return Value - -The difference between _X and _Y if _X is greater than _Y; otherwise, +0. - -## floor - -Calculates the floor of the argument - -```cpp -inline float floor(float _X) restrict(amp); - -inline double floor(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the floor of the argument - -## floorf - -Calculates the floor of the argument - -```cpp -inline float floorf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the floor of the argument - -## 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. - -```cpp -inline float fma( - float _X, - float _Y, - float _Z -) restrict(amp); - -inline double fma( - double _X, - double _Y, - double _Z -) restrict(amp); -``` - -### Parameters - -*_X*
-The first floating-point argument. -*_Y*
-The second floating-point argument. -*_Z*
-The third floating-point argument. - -### Return Value - -The result of the expression (_X \* _Y) + _Z. The entire computation is performed as a single operation; that is, the sub-expressions are calculated to infinite precision, and only the final result is rounded. - -## fmaf - -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. - -```cpp -inline float fmaf( - float _X, - float _Y, - float _Z -) restrict(amp); -``` - -### Parameters - -*_X*
-The first floating-point argument. -*_Y*
-The second floating-point argument. -*_Z*
-The third floating-point argument. - -### Return Value - -The result of the expression (_X \* _Y) + _Z. The entire computation is performed as a single operation; that is, the sub-expressions are calculated to infinite precision, and only the final result is rounded. - -## fmax - -Determine the maximum numeric value of the arguments - -```cpp -inline float fmax( - float _X, - float _Y) restrict(amp); - -inline double fmax( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Return the maximum numeric value of the arguments - -## fmaxf - -Determine the maximum numeric value of the arguments - -```cpp -inline float fmaxf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Return the maximum numeric value of the arguments - -## fmin - -Determine the minimum numeric value of the arguments - -```cpp -inline float fmin( - float _X, - float _Y) restrict(amp); - -inline double fmin( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Return the minimum numeric value of the arguments - -## fminf - -Determine the minimum numeric value of the arguments - -```cpp -inline float fminf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Return the minimum numeric value of the arguments - -## fmod Function (C++ AMP) - -Computes the remainder of the first specified argument divided by the second specified argument. - -```cpp -inline float fmod( - float _X, - float _Y) restrict(amp); - -inline double fmod( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-The first floating-point argument. - -*_Y*
-The second floating-point argument. - -### Return Value - -The remainder of `_X` divided by `_Y`; that is, the value of `_X` - `_Y`*n*, where *n* is a whole integer such that the magnitude of `_X` - `_Y`*n* is less than the magnitude of `_Y`. - -## fmodf - -Computes the remainder of the first specified argument divided by the second specified argument. - -```cpp -inline float fmodf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-The first floating-point argument. - -*_Y*
-The second floating-point argument. - -### Return Value - -The remainder of `_X` divided by `_Y`; that is, the value of `_X` - `_Y`*n*, where *n* is a whole integer such that the magnitude of `_X` - `_Y`*n* is less than the magnitude of `_Y`. - -## fpclassify - -Classifies the argument value as NaN, infinite, normal, subnormal, zero - -```cpp -inline int fpclassify(float _X) restrict(amp); - -inline int fpclassify(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the value of the number classification macro appropriate to the value of the argument. - -## frexp - -Gets the mantissa and exponent of _X - -```cpp -inline float frexp( - float _X, - _Out_ int* _Exp) restrict(amp); - -inline double frexp( - double _X, - _Out_ int* _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Exp*
-Returns the integer exponent of _X in floating-point value - -### Return Value - -Returns the mantissa _X - -## frexpf - -Gets the mantissa and exponent of _X - -```cpp -inline float frexpf( - float _X, - _Out_ int* _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Exp*
-Returns the integer exponent of _X in floating-point value - -### Return Value - -Returns the mantissa _X - -## hypot - -Computes the square root of the sum of the squares of _X and _Y - -```cpp -inline float hypot( - float _X, - float _Y) restrict(amp); - -inline double hypot( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns the square root of the sum of the squares of _X and _Y - -## hypotf - -Computes the square root of the sum of the squares of _X and _Y - -```cpp -inline float hypotf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns the square root of the sum of the squares of _X and _Y - -## ilogb - -Extract the exponent of _X as a signed int value - -```cpp -inline int ilogb(float _X) restrict(amp); - -inline int ilogb(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the exponent of _X as a signed int value - -## ilogbf - -Extract the exponent of _X as a signed int value - -```cpp -inline int ilogbf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the exponent of _X as a signed int value - -## isfinite - -Determines whether the argument has a finite value - -```cpp -inline int isfinite(float _X) restrict(amp); - -inline int isfinite(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the argument has a finite value - -## isinf - -Determines whether the argument is an infinity - -```cpp -inline int isinf(float _X) restrict(amp); - -inline int isinf(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the argument has an infinite value - -## isnan - -Determines whether the argument is a NaN - -```cpp -inline int isnan(float _X) restrict(amp); - -inline int isnan(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the argument has a NaN value - -## isnormal - -Determines whether the argument is a normal - -```cpp -inline int isnormal(float _X) restrict(amp); - -inline int isnormal(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the argument has a normal value - -## ldexp - -Computes a real number from the specified mantissa and exponent. - -```cpp -inline float ldexp( - float _X, - int _Exp) restrict(amp); - -inline double ldexp( - double _X, - double _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, mantissa - -*_Exp*
-Integer value, exponent - -### Return Value - -Returns _X \* 2^_Exp - -## ldexpf - -Computes a real number from the specified mantissa and exponent. - -```cpp -inline float ldexpf( - float _X, - int _Exp) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, mantissa - -*_Exp*
-Integer value, exponent - -### Return Value - -Returns _X \* 2^_Exp - -## lgamma - -Computes the natural logarithm of the absolute value of gamma of the argument - -```cpp -inline float lgamma( - float _X, - _Out_ int* _Sign) restrict(amp); - -inline double lgamma( - double _X, - _Out_ int* _Sign) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Sign*
-Returns the sign - -### Return Value - -Returns the natural logarithm of the absolute value of gamma of the argument - -## lgammaf - -Computes the natural logarithm of the absolute value of gamma of the argument - -```cpp -inline float lgammaf( - float _X, - _Out_ int* _Sign) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Sign*
-Returns the sign - -### Return Value - -Returns the natural logarithm of the absolute value of gamma of the argument - -## log - -Calculates the base-e logarithm of the argument - -```cpp -inline float log(float _X) restrict(amp); - -inline double log(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e logarithm of the argument - -## log10 - -Calculates the base-10 logarithm of the argument - -```cpp -inline float log10(float _X) restrict(amp); - -inline double log10(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 logarithm of the argument - -## log10f - -Calculates the base-10 logarithm of the argument - -```cpp -inline float log10f(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 logarithm of the argument - -## log1p - -Calculates the base-e logarithm of 1 plus the argument - -```cpp -inline float log1p(float _X) restrict(amp); - -inline double log1p(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e logarithm of 1 plus the argument - -## log1pf - -Calculates the base-e logarithm of 1 plus the argument - -```cpp -inline float log1pf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e logarithm of 1 plus the argument - -## log2 - -Calculates the base-2 logarithm of the argument - -```cpp -inline float log2(float _X) restrict(amp); - -inline double log2(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 logarithm of the argument - -## log2f - -Calculates the base-2 logarithm of the argument - -```cpp -inline float log2f(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-10 logarithm of the argument - -## logb - -Extracts the exponent of _X, as a signed integer value in floating-point format - -```cpp -inline float logb(float _X) restrict(amp); - -inline double logb(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the signed exponent of _X - -## logbf - -Extracts the exponent of _X, as a signed integer value in floating-point format - -```cpp -inline float logbf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the signed exponent of _X - -## logf - -Calculates the base-e logarithm of the argument - -```cpp -inline float logf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the base-e logarithm of the argument - -## modf - -Splits the specified argument into fractional and integer parts. - -```cpp -inline float modf( - float _X, - _Out_ float* _Iptr) restrict(amp); - -inline double modf( - double _X, - _Out_ double* _Iptr) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Iptr*
-[out] The integer portion of `_X`, as a floating-point value. - -### Return Value - -The signed fractional portion of `_X`. - -## modff - -Splits the specified argument into fractional and integer parts. - -```cpp -inline float modff( - float _X, - _Out_ float* _Iptr) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Iptr*
-The integer portion of `_X`, as a floating-point value. - -### Return Value - -Returns the signed fractional portion of `_X`. - -## nan - -Returns a quiet NaN - -```cpp -inline double nan(int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -### Return Value - -Returns a quiet NaN, if available, with the content indicated in _X - -## nanf - -Returns a quiet NaN - -```cpp -inline float nanf(int _X) restrict(amp); -``` - -### Parameters - -*_X*
-Integer value - -### Return Value - -Returns a quiet NaN, if available, with the content indicated in _X - -## nearbyint - -Rounds the argument to an integer value in floating-point format, using the current rounding direction. - -```cpp -inline float nearbyint(float _X) restrict(amp); - -inline double nearbyint(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the rounded integer value. - -## nearbyintf - -Rounds the argument to an integer value in floating-point format, using the current rounding direction. - -```cpp -inline float nearbyintf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the rounded integer value. - -## nextafter - -Determine the next representable value, in the type of the function, after _X in the direction of _Y - -```cpp -inline float nextafter( - float _X, - float _Y) restrict(amp); - -inline double nextafter( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns the next representable value, in the type of the function, after _X in the direction of _Y - -## nextafterf - -Determine the next representable value, in the type of the function, after _X in the direction of _Y - -```cpp -inline float nextafterf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns the next representable value, in the type of the function, after _X in the direction of _Y - -## phi - -Returns the cumulative distribution function of the argument - -```cpp -inline float phi(float _X) restrict(amp); - -inline double phi(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cumulative distribution function of the argument - -## phif - -Returns the cumulative distribution function of the argument - -```cpp -inline float phif(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the cumulative distribution function of the argument - -## pow - -Calculates _X raised to the power of _Y - -```cpp -inline float pow( - float _X, - float _Y) restrict(amp); - -inline double pow( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, base - -*_Y*
-Floating-point value, exponent - -### Return Value - -## powf - -Calculates _X raised to the power of _Y - -```cpp -inline float powf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value, base - -*_Y*
-Floating-point value, exponent - -### Return Value - -## probit - -Returns the inverse cumulative distribution function of the argument - -```cpp -inline float probit(float _X) restrict(amp); - -inline double probit(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse cumulative distribution function of the argument - -## probitf - -Returns the inverse cumulative distribution function of the argument - -```cpp -inline float probitf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the inverse cumulative distribution function of the argument - -## rcbrt - -Returns the reciprocal of the cube root of the argument - -```cpp -inline float rcbrt(float _X) restrict(amp); - -inline double rcbrt(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the reciprocal of the cube root of the argument - -## rcbrtf - -Returns the reciprocal of the cube root of the argument - -```cpp -inline float rcbrtf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the reciprocal of the cube root of the argument - -## remainder - -Computes the remainder: _X REM _Y - -```cpp -inline float remainder( - float _X, - float _Y) restrict(amp); - -inline double remainder( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns _X REM _Y - -## remainderf - -Computes the remainder: _X REM _Y - -```cpp -inline float remainderf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns _X REM _Y - -## remquo - -Computes the remainder of the first specified argument divided by the second specified argument. Also computes the quotient of the significand of the first specified argument divided by the significand of the second specified argument, and returns the quotient using the location specified in the third argument. - -```cpp -inline float remquo( - float _X, - float _Y, - _Out_ int* _Quo) restrict(amp); - -inline double remquo( - double _X, - double _Y, - _Out_ int* _Quo) restrict(amp); -``` - -### Parameters - -*_X*
-The first floating-point argument. - -*_Y*
-The second floating-point argument. - -*_Quo*
-[out] The address of an integer that’s used to return the quotient of the fractional bits of `_X` divided by the fractional bits of `_Y`. - -### Return Value - -Returns the remainder of `_X` divided by `_Y`. - -## remquof - -Computes the remainder of the first specified argument divided by the second specified argument. Also computes the quotient of the significand of the first specified argument divided by the significand of the second specified argument, and returns the quotient using the location specified in the third argument. - -```cpp -inline float remquof( - float _X, - float _Y, - _Out_ int* _Quo) restrict(amp); -``` - -### Parameters - -*_X*
-The first floating-point argument. - -*_Y*
-The second floating-point argument. - -*_Quo*
-[out] The address of an integer that’s used to return the quotient of the fractional bits of `_X` divided by the fractional bits of `_Y`. - -### Return Value - -Returns the remainder of `_X` divided by `_Y`. - -## round - -Rounds _X to the nearest integer - -```cpp -inline float round(float _X) restrict(amp); - -inline double round(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the nearest integer of _X - -## roundf - -Rounds _X to the nearest integer - -```cpp -inline float roundf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the nearest integer of _X - -## rsqrt - -Returns the reciprocal of the square root of the argument - -```cpp -inline float rsqrt(float _X) restrict(amp); - -inline double rsqrt(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the reciprocal of the square root of the argument - -## rsqrtf - -Returns the reciprocal of the square root of the argument - -```cpp -inline float rsqrtf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the reciprocal of the square root of the argument - -## scalb - -Multiplies _X by FLT_RADIX to the power _Y - -```cpp -inline float scalb( - float _X, - float _Y) restrict(amp); - -inline double scalb( - double _X, - double _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns _X \* (FLT_RADIX ^ _Y) - -## scalbf - -Multiplies _X by FLT_RADIX to the power _Y - -```cpp -inline float scalbf( - float _X, - float _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Floating-point value - -### Return Value - -Returns _X \* (FLT_RADIX ^ _Y) - -## scalbn - -Multiplies _X by FLT_RADIX to the power _Y - -```cpp -inline float scalbn( - float _X, - int _Y) restrict(amp); - -inline double scalbn( - double _X, - int _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Integer value - -### Return Value - -Returns _X \* (FLT_RADIX ^ _Y) - -## scalbnf - -Multiplies _X by FLT_RADIX to the power _Y - -```cpp -inline float scalbnf( - float _X, - int _Y) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_Y*
-Integer value - -### Return Value - -Returns _X \* (FLT_RADIX ^ _Y) - -## signbit - -Determines whether the sign of _X is negative - -```cpp -inline int signbit(float _X) restrict(amp); - -inline int signbit(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the sign of _X is negative - -## signbitf - -Determines whether the sign of _X is negative - -```cpp -inline int signbitf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns a nonzero value if and only if the sign of _X is negative - -## sin - -Calculates the sine value of the argument - -```cpp -inline float sin(float _X) restrict(amp); - -inline double sin(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the sine value of the argument - -## sinf - -Calculates the sine value of the argument - -```cpp -inline float sinf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the sine value of the argument - -## sincos - -Calculates sine and cosine value of _X - -```cpp -inline void sincos( - float _X, - _Out_ float* _S, - _Out_ float* _C) restrict(amp); - -inline void sincos( - double _X, - _Out_ double* _S, - _Out_ double* _C) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_S*
-Returns the sine value of _X - -*_C*
-Returns the cosine value of _X - -## sincosf - -Calculates sine and cosine value of _X - -```cpp -inline void sincosf( - float _X, - _Out_ float* _S, - _Out_ float* _C) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -*_S*
-Returns the sine value of _X - -*_C*
-Returns the cosine value of _X - -## sinh - -Calculates the hyperbolic sine value of the argument - -```cpp -inline float sinh(float _X) restrict(amp); - -inline double sinh(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic sine value of the argument - -## sinhf - -Calculates the hyperbolic sine value of the argument - -```cpp -inline float sinhf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic sine value of the argument - -## sinpi - -Calculates the sine value of pi \* _X - -```cpp -inline float sinpi(float _X) restrict(amp); - -inline double sinpi(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the sine value of pi \* _X - -## sinpif - -Calculates the sine value of pi \* _X - -```cpp -inline float sinpif(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the sine value of pi \* _X - -## sqrt - -Calculates the squre root of the argument - -```cpp -inline float sqrt(float _X) restrict(amp); - -inline double sqrt(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the squre root of the argument - -## sqrtf - -Calculates the squre root of the argument - -```cpp -inline float sqrtf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the squre root of the argument - -## tan - -Calculates the tangent value of the argument - -```cpp -inline float tan(float _X) restrict(amp); - -inline double tan(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the tangent value of the argument - -## tanf - -Calculates the tangent value of the argument - -```cpp -inline float tanf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the tangent value of the argument - -## tanh - -Calculates the hyperbolic tangent value of the argument - -```cpp -inline float tanh(float _X) restrict(amp); - -inline double tanh(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic tangent value of the argument - -## tanhf - -Calculates the hyperbolic tangent value of the argument - -```cpp -inline float tanhf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the hyperbolic tangent value of the argument - -## tanpi - -Calculates the tangent value of pi \* _X - -```cpp -inline float tanpi(float _X) restrict(amp); - -inline double tanpi(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the tangent value of pi \* _X - -## tanpif - -Calculates the tangent value of pi \* _X - -```cpp -inline float tanpif(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the tangent value of pi \* _X - -## tgamma - -Computes the gamma function of _X - -```cpp -inline float tgamma(float _X) restrict(amp); - -inline double tgamma(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the result of gamma function of _X - -## tgammaf - -Computes the gamma function of _X - -```cpp -inline float tgammaf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the result of gamma function of _X - -## trunc - -Truncates the argument to the integer component - -```cpp -inline float trunc(float _X) restrict(amp); - -inline double trunc(double _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the integer component of the argument - -## truncf - -Truncates the argument to the integer component - -```cpp -inline float truncf(float _X) restrict(amp); -``` - -### Parameters - -*_X*
-Floating-point value - -### Return Value - -Returns the integer component of the argument - -## See also - -[Concurrency::precise_math Namespace](concurrency-precise-math-namespace.md) diff --git a/docs/parallel/amp/reference/concurrency-precise-math-namespace.md b/docs/parallel/amp/reference/concurrency-precise-math-namespace.md deleted file mode 100644 index ade1b8c16cc..00000000000 --- a/docs/parallel/amp/reference/concurrency-precise-math-namespace.md +++ /dev/null @@ -1,166 +0,0 @@ ---- -description: "Learn more about: Concurrency::precise_math Namespace" -title: "Concurrency::precise_math Namespace" -ms.date: "11/04/2016" -f1_keywords: ["AMP_MATH/Concurrency::acos", "AMP_MATH/Concurrency::acosf", "AMP_MATH/Concurrency::acosh", "AMP_MATH/Concurrency::acoshf", "AMP_MATH/Concurrency::asin", "AMP_MATH/Concurrency::asinf", "AMP_MATH/Concurrency::asinh", "AMP_MATH/Concurrency::asinhf", "AMP_MATH/Concurrency::atan", "AMP_MATH/Concurrency::atan2", "AMP_MATH/Concurrency::atan2f", "AMP_MATH/Concurrency::atanf", "AMP_MATH/Concurrency::atanh", "AMP_MATH/Concurrency::atanhf", "AMP_MATH/Concurrency::cbrt", "AMP_MATH/Concurrency::cbrtf", "AMP_MATH/Concurrency::ceil", "AMP_MATH/Concurrency::ceilf", "AMP_MATH/Concurrency::copysign", "AMP_MATH/Concurrency::copysignf", "AMP_MATH/Concurrency::cos", "AMP_MATH/Concurrency::cosf", "AMP_MATH/Concurrency::cosh", "AMP_MATH/Concurrency::coshf", "AMP_MATH/Concurrency::cospi", "AMP_MATH/Concurrency::cospif", "AMP_MATH/Concurrency::erf", "AMP_MATH/Concurrency::erfc", "AMP_MATH/Concurrency::erfcf", "AMP_MATH/Concurrency::erfcinv", "AMP_MATH/Concurrency::erfcinvf", "AMP_MATH/Concurrency::erff", "AMP_MATH/Concurrency::erfinv", "AMP_MATH/Concurrency::erfinvf", "AMP_MATH/Concurrency::exp", "AMP_MATH/Concurrency::exp10", "AMP_MATH/Concurrency::exp10f", "AMP_MATH/Concurrency::exp2", "AMP_MATH/Concurrency::exp2f", "AMP_MATH/Concurrency::expf", "AMP_MATH/Concurrency::expm1", "AMP_MATH/Concurrency::expm1f", "AMP_MATH/Concurrency::fabs", "AMP_MATH/Concurrency::fabsf", "AMP_MATH/Concurrency::fdim", "AMP_MATH/Concurrency::fdimf", "AMP_MATH/Concurrency::floor", "AMP_MATH/Concurrency::floorf", "AMP_MATH/Concurrency::fma", "AMP_MATH/Concurrency::fmaf", "AMP_MATH/Concurrency::fmax", "AMP_MATH/Concurrency::fmaxf", "AMP_MATH/Concurrency::fmin", "AMP_MATH/Concurrency::fminf", "AMP_MATH/Concurrency::fmodf", "AMP_MATH/Concurrency::fpclassify", "AMP_MATH/Concurrency::frexp", "AMP_MATH/Concurrency::frexpf", "AMP_MATH/Concurrency::hypot", "AMP_MATH/Concurrency::hypotf", "AMP_MATH/Concurrency::ilogb", "AMP_MATH/Concurrency::ilogbf", "AMP_MATH/Concurrency::isfinite", "AMP_MATH/Concurrency::isinf", "AMP_MATH/Concurrency::isnan", "AMP_MATH/Concurrency::isnormal", "AMP_MATH/Concurrency::ldexp", "AMP_MATH/Concurrency::ldexpf", "AMP_MATH/Concurrency::lgamma", "AMP_MATH/Concurrency::lgammaf", "AMP_MATH/Concurrency::log", "AMP_MATH/Concurrency::log10", "AMP_MATH/Concurrency::log10f", "AMP_MATH/Concurrency::log1p", "AMP_MATH/Concurrency::log1pf", "AMP_MATH/Concurrency::log2", "AMP_MATH/Concurrency::log2f", "AMP_MATH/Concurrency::logb", "AMP_MATH/Concurrency::logbf", "AMP_MATH/Concurrency::logf", "AMP_MATH/Concurrency::modf", "AMP_MATH/Concurrency::modff", "AMP_MATH/Concurrency::nan", "AMP_MATH/Concurrency::nanf", "AMP_MATH/Concurrency::nearbyint", "AMP_MATH/Concurrency::nearbyintf", "AMP_MATH/Concurrency::nextafter", "AMP_MATH/Concurrency::nextafterf", "AMP_MATH/Concurrency::phi", "AMP_MATH/Concurrency::phif", "AMP_MATH/Concurrency::pow", "AMP_MATH/Concurrency::powf", "AMP_MATH/Concurrency::probit", "AMP_MATH/Concurrency::probitf", "AMP_MATH/Concurrency::rcbrt", "AMP_MATH/Concurrency::rcbrtf", "AMP_MATH/Concurrency::remainder", "AMP_MATH/Concurrency::remainderf", "AMP_MATH/Concurrency::remquo", "AMP_MATH/Concurrency::remquof", "AMP_MATH/Concurrency::round", "AMP_MATH/Concurrency::roundf", "AMP_MATH/Concurrency::rsqrt", "AMP_MATH/Concurrency::rsqrtf", "AMP_MATH/Concurrency::scalb", "AMP_MATH/Concurrency::scalbf", "AMP_MATH/Concurrency::scalbn", "AMP_MATH/Concurrency::scalbnf", "AMP_MATH/Concurrency::signbit", "AMP_MATH/Concurrency::signbitf", "AMP_MATH/Concurrency::sin", "AMP_MATH/Concurrency::sincos", "AMP_MATH/Concurrency::sincosf", "AMP_MATH/Concurrency::sinf", "AMP_MATH/Concurrency::sinh", "AMP_MATH/Concurrency::sinhf", "AMP_MATH/Concurrency::sinpi", "AMP_MATH/Concurrency::sinpif", "AMP_MATH/Concurrency::sqrt", "AMP_MATH/Concurrency::sqrtf", "AMP_MATH/Concurrency::tan", "AMP_MATH/Concurrency::tanf", "AMP_MATH/Concurrency::tanh", "AMP_MATH/Concurrency::tanhf", "AMP_MATH/Concurrency::tanpi", "AMP_MATH/Concurrency::tanpif", "AMP_MATH/Concurrency::tgamma", "AMP_MATH/Concurrency::tgammaf", "AMP_MATH/Concurrency::trunc", "AMP_MATH/Concurrency::truncf"] -ms.assetid: ba653308-dc28-4384-b2fd-6cd718a72f91 ---- -# Concurrency::precise_math Namespace - -Functions in the `precise_math` namespace are C99 conformant. Both single precision and double precision versions of each function are included. For example, `acos` is the double-precision version and `acosf` is the single-precision version. These functions, including the single-precision functions, require extended double-precision support on the accelerator. You can use the [accelerator::supports_double_precision](accelerator-class.md#supports_double_precision) to determine if you can run these functions on a specific accelerator. - -## Syntax - -```cpp -namespace precise_math; -``` - -### Parameters - -## Members - -### Functions - -|Name|Description| -|----------|-----------------| -|[acos](concurrency-precise-math-namespace-functions.md#acos)|Overloaded. Calculates the arccosine of the argument| -|[acosf](concurrency-precise-math-namespace-functions.md#acosf)|Calculates the arccosine of the argument| -|[acosh](concurrency-precise-math-namespace-functions.md#acosh)|Overloaded. Calculates the inverse hyperbolic cosine of the argument| -|[acoshf](concurrency-precise-math-namespace-functions.md#acoshf)|Calculates the inverse hyperbolic cosine of the argument| -|[asin](concurrency-precise-math-namespace-functions.md#asin)|Overloaded. Calculates the arcsine of the argument| -|[asinf](concurrency-precise-math-namespace-functions.md#asinf)|Calculates the arcsine of the argument| -|[asinh](concurrency-precise-math-namespace-functions.md#asinh)|Overloaded. Calculates the inverse hyperbolic sine of the argument| -|[asinhf](concurrency-precise-math-namespace-functions.md#asinhf)|Calculates the inverse hyperbolic sine of the argument| -|[atan](concurrency-precise-math-namespace-functions.md#atan)|Overloaded. Calculates the arctangent of the argument| -|[atan2](concurrency-precise-math-namespace-functions.md#atan2)|Overloaded. Calculates the arctangent of _Y/_X| -|[atan2f](concurrency-precise-math-namespace-functions.md#atan2f)|Calculates the arctangent of _Y/_X| -|[atanf](concurrency-precise-math-namespace-functions.md#atanf)|Calculates the arctangent of the argument| -|[atanh](concurrency-precise-math-namespace-functions.md#atanh)|Overloaded. Calculates the inverse hyperbolic tangent of the argument| -|[atanhf](concurrency-precise-math-namespace-functions.md#atanhf)|Calculates the inverse hyperbolic tangent of the argument| -|[cbrt](concurrency-precise-math-namespace-functions.md#cbrt)|Overloaded. Computes the real cube root of the argument| -|[cbrtf](concurrency-precise-math-namespace-functions.md#cbrtf)|Computes the real cube root of the argument| -|[ceil](concurrency-precise-math-namespace-functions.md#ceil)|Overloaded. Calculates the ceiling of the argument| -|[ceilf](concurrency-precise-math-namespace-functions.md#ceilf)|Calculates the ceiling of the argument| -|[copysign](concurrency-precise-math-namespace-functions.md#copysign)|Overloaded. Produces a value with the magnitude of _X and the sign of _Y| -|[copysignf](concurrency-precise-math-namespace-functions.md#copysignf)|Produces a value with the magnitude of _X and the sign of _Y| -|[cos](concurrency-precise-math-namespace-functions.md#cos)|Overloaded. Calculates the cosine of the argument| -|[cosf](concurrency-precise-math-namespace-functions.md#cosf)|Calculates the cosine of the argument| -|[cosh](concurrency-precise-math-namespace-functions.md#cosh)|Overloaded. Calculates the hyperbolic cosine value of the argument| -|[coshf](concurrency-precise-math-namespace-functions.md#coshf)|Calculates the hyperbolic cosine value of the argument| -|[cospi](concurrency-precise-math-namespace-functions.md#cospi)|Overloaded. Calculates the cosine value of pi \* _X| -|[cospif](concurrency-precise-math-namespace-functions.md#cospif)|Calculates the cosine value of pi \* _X| -|[erf](concurrency-precise-math-namespace-functions.md#erf)|Overloaded. Computes the error function of _X| -|[erfc](concurrency-precise-math-namespace-functions.md#erfc)|Overloaded. Computes the complementary error function of _X| -|[erfcf](concurrency-precise-math-namespace-functions.md#erfcf)|Computes the complementary error function of _X| -|[erfcinv](concurrency-precise-math-namespace-functions.md#erfcinv)|Overloaded. Computes the inverse complementary error function of _X| -|[erfcinvf](concurrency-precise-math-namespace-functions.md#erfcinvf)|Computes the inverse complementary error function of _X| -|[erff](concurrency-precise-math-namespace-functions.md#erff)|Computes the error function of _X| -|[erfinv](concurrency-precise-math-namespace-functions.md#erfinv)|Overloaded. Computes the inverse error function of _X| -|[erfinvf](concurrency-precise-math-namespace-functions.md#erfinvf)|Computes the inverse error function of _X| -|[exp](concurrency-precise-math-namespace-functions.md#exp)|Overloaded. Calculates the base-e exponential of the argument| -|[exp10](concurrency-precise-math-namespace-functions.md#exp10)|Overloaded. Calculates the base-10 exponential of the argument| -|[exp10f](concurrency-precise-math-namespace-functions.md#exp10f)|Calculates the base-10 exponential of the argument| -|[exp2](concurrency-precise-math-namespace-functions.md#exp2)|Overloaded. Calculates the base-2 exponential of the argument| -|[exp2f](concurrency-precise-math-namespace-functions.md#exp2f)|Calculates the base-2 exponential of the argument| -|[expf](concurrency-precise-math-namespace-functions.md#expf)|Calculates the base-e exponential of the argument| -|[expm1](concurrency-precise-math-namespace-functions.md#expm1)|Overloaded. Calculates the base-e exponential of the argument, minus 1| -|[expm1f](concurrency-precise-math-namespace-functions.md#expm1f)|Calculates the base-e exponential of the argument, minus 1| -|[fabs](concurrency-precise-math-namespace-functions.md#fabs)|Overloaded. Returns the absolute value of the argument| -|[fabsf](concurrency-precise-math-namespace-functions.md#fabsf)|Returns the absolute value of the argument| -|[fdim](concurrency-precise-math-namespace-functions.md#fdim)|Overloaded. Determines the positive difference between the arguments| -|[fdimf](concurrency-precise-math-namespace-functions.md#fdimf)|Determines the positive difference between the arguments| -|[floor](concurrency-precise-math-namespace-functions.md#floor)|Overloaded. Calculates the floor of the argument| -|[floorf](concurrency-precise-math-namespace-functions.md#floorf)|Calculates the floor of the argument| -|[fma](concurrency-precise-math-namespace-functions.md#fma)|Overloaded. Compute (_X \* _Y) + _Z, rounded as one ternary operation| -|[fmaf](concurrency-precise-math-namespace-functions.md#fmaf)|Compute (_X \* _Y) + _Z, rounded as one ternary operation| -|[fmax](concurrency-precise-math-namespace-functions.md#fmax)|Overloaded. Determine the maximum numeric value of the arguments| -|[fmaxf](concurrency-precise-math-namespace-functions.md#fmaxf)|Determine the maximum numeric value of the arguments| -|[fmin](concurrency-precise-math-namespace-functions.md#fmin)|Overloaded. Determine the minimum numeric value of the arguments| -|[fminf](concurrency-precise-math-namespace-functions.md#fminf)|Determine the minimum numeric value of the arguments| -|[fmod Function (C++ AMP)](concurrency-precise-math-namespace-functions.md#fmod)|Overloaded. Calculates the floating-point remainder of _X/_Y| -|[fmodf](concurrency-precise-math-namespace-functions.md#fmodf)|Calculates the floating-point remainder of _X/_Y| -|[fpclassify](concurrency-precise-math-namespace-functions.md#fpclassify)|Overloaded. Classifies the argument value as NaN, infinite, normal, subnormal, zero| -|[frexp](concurrency-precise-math-namespace-functions.md#frexp)|Overloaded. Gets the mantissa and exponent of _X| -|[frexpf](concurrency-precise-math-namespace-functions.md#frexpf)|Gets the mantissa and exponent of _X| -|[hypot](concurrency-precise-math-namespace-functions.md#hypot)|Overloaded. Computes the square root of the sum of the squares of _X and _Y| -|[hypotf](concurrency-precise-math-namespace-functions.md#hypotf)|Computes the square root of the sum of the squares of _X and _Y| -|[ilogb](concurrency-precise-math-namespace-functions.md#ilogb)|Overloaded. Extract the exponent of _X as a signed int value| -|[ilogbf](concurrency-precise-math-namespace-functions.md#ilogbf)|Extract the exponent of _X as a signed int value| -|[isfinite](concurrency-precise-math-namespace-functions.md#isfinite)|Overloaded. Determines whether the argument has a finite value| -|[isinf](concurrency-precise-math-namespace-functions.md#isinf)|Overloaded. Determines whether the argument is an infinity| -|[isnan](concurrency-precise-math-namespace-functions.md#isnan)|Overloaded. Determines whether the argument is a NaN| -|[isnormal](concurrency-precise-math-namespace-functions.md#isnormal)|Overloaded. Determines whether the argument is a normal| -|[ldexp](concurrency-precise-math-namespace-functions.md#ldexp)|Overloaded. Computes a real number from the mantissa and exponent| -|[ldexpf](concurrency-precise-math-namespace-functions.md#ldexpf)|Computes a real number from the mantissa and exponent| -|[lgamma](concurrency-precise-math-namespace-functions.md#lgamma)|Overloaded. Computes the natural logarithm of the absolute value of gamma of the argument| -|[lgammaf](concurrency-precise-math-namespace-functions.md#lgammaf)|Computes the natural logarithm of the absolute value of gamma of the argument| -|[log](concurrency-precise-math-namespace-functions.md#log)|Overloaded. Calculates the base-e logarithm of the argument| -|[log10](concurrency-precise-math-namespace-functions.md#log10)|Overloaded. Calculates the base-10 logarithm of the argument| -|[log10f](concurrency-precise-math-namespace-functions.md#log10f)|Calculates the base-10 logarithm of the argument| -|[log1p](concurrency-precise-math-namespace-functions.md#log1p)|Overloaded. Calculates the base-e logarithm of 1 plus the argument| -|[log1pf](concurrency-precise-math-namespace-functions.md#log1pf)|Calculates the base-e logarithm of 1 plus the argument| -|[log2](concurrency-precise-math-namespace-functions.md#log2)|Overloaded. Calculates the base-2 logarithm of the argument| -|[log2f](concurrency-precise-math-namespace-functions.md#log2f)|Calculates the base-2 logarithm of the argument| -|[logb](concurrency-precise-math-namespace-functions.md#logb)|Overloaded. Extracts the exponent of _X, as a signed integer value in floating-point format| -|[logbf](concurrency-precise-math-namespace-functions.md#logbf)|Extracts the exponent of _X, as a signed integer value in floating-point format| -|[logf](concurrency-precise-math-namespace-functions.md#logf)|Calculates the base-e logarithm of the argument| -|[modf](concurrency-precise-math-namespace-functions.md#modf)|Overloaded. Splits _X into fractional and integer parts.| -|[modff](concurrency-precise-math-namespace-functions.md#modff)|Splits _X into fractional and integer parts.| -|[nan](concurrency-precise-math-namespace-functions.md#nan)|Returns a quiet NaN| -|[nanf](concurrency-precise-math-namespace-functions.md#nanf)|Returns a quiet NaN| -|[nearbyint](concurrency-precise-math-namespace-functions.md#nearbyint)|Overloaded. Rounds the argument to an integer value in floating-point format, using the current rounding direction.| -|[nearbyintf](concurrency-precise-math-namespace-functions.md#nearbyintf)|Rounds the argument to an integer value in floating-point format, using the current rounding direction.| -|[nextafter](concurrency-precise-math-namespace-functions.md#nextafter)|Overloaded. Determine the next representable value, in the type of the function, after _X in the direction of _Y| -|[nextafterf](concurrency-precise-math-namespace-functions.md#nextafterf)|Determine the next representable value, in the type of the function, after _X in the direction of _Y| -|[phi](concurrency-precise-math-namespace-functions.md#phi)|Overloaded. Returns the cumulative distribution function of the argument| -|[phif](concurrency-precise-math-namespace-functions.md#phif)|Returns the cumulative distribution function of the argument| -|[pow](concurrency-precise-math-namespace-functions.md#pow)|Overloaded. Calculates _X raised to the power of _Y| -|[powf](concurrency-precise-math-namespace-functions.md#powf)|Calculates _X raised to the power of _Y| -|[probit](concurrency-precise-math-namespace-functions.md#probit)|Overloaded. Returns the inverse cumulative distribution function of the argument| -|[probitf](concurrency-precise-math-namespace-functions.md#probitf)|Returns the inverse cumulative distribution function of the argument| -|[rcbrt](concurrency-precise-math-namespace-functions.md#rcbrt)|Overloaded. Returns the reciprocal of the cube root of the argument| -|[rcbrtf](concurrency-precise-math-namespace-functions.md#rcbrtf)|Returns the reciprocal of the cube root of the argument| -|[remainder](concurrency-precise-math-namespace-functions.md#remainder)|Overloaded. Computes the remainder: _X REM _Y| -|[remainderf](concurrency-precise-math-namespace-functions.md#remainderf)|Computes the remainder: _X REM _Y| -|[remquo](concurrency-precise-math-namespace-functions.md#remquo)|Overloaded. Computes the same remainder as _X REM _Y. Also calculates the lower 23 bits of the integral quotient _X/_Y, and gives that value the same sign as _X/_Y. It stores this signed value in the integer pointed to by _Quo.| -|[remquof](concurrency-precise-math-namespace-functions.md#remquof)|Computes the same remainder as _X REM _Y. Also calculates the lower 23 bits of the integral quotient _X/_Y, and gives that value the same sign as _X/_Y. It stores this signed value in the integer pointed to by _Quo.| -|[round](concurrency-precise-math-namespace-functions.md#round)|Overloaded. Rounds _X to the nearest integer| -|[roundf](concurrency-precise-math-namespace-functions.md#roundf)|Rounds _X to the nearest integer| -|[rsqrt](concurrency-precise-math-namespace-functions.md#rsqrt)|Overloaded. Returns the reciprocal of the square root of the argument| -|[rsqrtf](concurrency-precise-math-namespace-functions.md#rsqrtf)|Returns the reciprocal of the square root of the argument| -|[scalb](concurrency-precise-math-namespace-functions.md#scalb)|Overloaded. Multiplies _X by FLT_RADIX to the power _Y| -|[scalbf](concurrency-precise-math-namespace-functions.md#scalbf)|Multiplies _X by FLT_RADIX to the power _Y| -|[scalbn](concurrency-precise-math-namespace-functions.md#scalbn)|Overloaded. Multiplies _X by FLT_RADIX to the power _Y| -|[scalbnf](concurrency-precise-math-namespace-functions.md#scalbnf)|Multiplies _X by FLT_RADIX to the power _Y| -|[signbit](concurrency-precise-math-namespace-functions.md#signbit)|Overloaded. Determines whether the sign of _X is negative| -|[signbitf](concurrency-precise-math-namespace-functions.md#signbitf)|Determines whether the sign of _X is negative| -|[sin](concurrency-precise-math-namespace-functions.md#sin)|Overloaded. Calculates the sine value of the argument| -|[sincos](concurrency-precise-math-namespace-functions.md#sincos)|Overloaded. Calculates sine and cosine value of _X| -|[sincosf](concurrency-precise-math-namespace-functions.md#sincosf)|Calculates sine and cosine value of _X| -|[sinf](concurrency-precise-math-namespace-functions.md#sinf)|Calculates the sine value of the argument| -|[sinh](concurrency-precise-math-namespace-functions.md#sinh)|Overloaded. Calculates the hyperbolic sine value of the argument| -|[sinhf](concurrency-precise-math-namespace-functions.md#sinhf)|Calculates the hyperbolic sine value of the argument| -|[sinpi](concurrency-precise-math-namespace-functions.md#sinpi)|Overloaded. Calculates the sine value of pi \* _X| -|[sinpif](concurrency-precise-math-namespace-functions.md#sinpif)|Calculates the sine value of pi \* _X| -|[sqrt](concurrency-precise-math-namespace-functions.md#sqrt)|Overloaded. Calculates the squre root of the argument| -|[sqrtf](concurrency-precise-math-namespace-functions.md#sqrtf)|Calculates the squre root of the argument| -|[tan](concurrency-precise-math-namespace-functions.md#tan)|Overloaded. Calculates the tangent value of the argument| -|[tanf](concurrency-precise-math-namespace-functions.md#tanf)|Calculates the tangent value of the argument| -|[tanh](concurrency-precise-math-namespace-functions.md#tanh)|Overloaded. Calculates the hyperbolic tangent value of the argument| -|[tanhf](concurrency-precise-math-namespace-functions.md#tanhf)|Calculates the hyperbolic tangent value of the argument| -|[tanpi](concurrency-precise-math-namespace-functions.md#tanpi)|Overloaded. Calculates the tangent value of pi \* _X| -|[tanpif](concurrency-precise-math-namespace-functions.md#tanpif)|Calculates the tangent value of pi \* _X| -|[tgamma](concurrency-precise-math-namespace-functions.md#tgamma)|Overloaded. Computes the gamma function of _X| -|[tgammaf](concurrency-precise-math-namespace-functions.md#tgammaf)|Computes the gamma function of _X| -|[trunc](concurrency-precise-math-namespace-functions.md#trunc)|Overloaded. Truncates the argument to the integer component| -|[truncf](concurrency-precise-math-namespace-functions.md#truncf)|Truncates the argument to the integer component| - -## Requirements - -**Header:** amp_math.h - -**Namespace:** Concurrency - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/double-2-class.md b/docs/parallel/amp/reference/double-2-class.md deleted file mode 100644 index 59d983be77d..00000000000 --- a/docs/parallel/amp/reference/double-2-class.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -description: "Learn more about: double_2 Class" -title: "double_2 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::double_2::set_x", "amp_short_vectors/Concurrency::graphics::double_2::operator+=", "amp_short_vectors/Concurrency::graphics::double_2::operator=", "amp_short_vectors/Concurrency::graphics::double_2::operator/=", "amp_short_vectors/Concurrency::graphics::double_2::operator*=", "amp_short_vectors/Concurrency::graphics::double_2::yx", "amp_short_vectors/Concurrency::graphics::double_2::y", "amp_short_vectors/Concurrency::graphics::double_2::xy", "amp_short_vectors/Concurrency::graphics::double_2::set_xy", "amp_short_vectors/Concurrency::graphics::double_2::get_yx", "amp_short_vectors/Concurrency::graphics::double_2::set_yx", "amp_short_vectors/Concurrency::graphics::double_2::get_xy", "amp_short_vectors/Concurrency::graphics::double_2::operator++", "amp_short_vectors/Concurrency::graphics::double_2::get_x", "amp_short_vectors/Concurrency::graphics::double_2::operator-=", "amp_short_vectors/Concurrency::graphics::double_2::rg", "amp_short_vectors/Concurrency::graphics::double_2::gr", "amp_short_vectors/Concurrency::graphics::double_2::get_y", "amp_short_vectors/Concurrency::graphics::double_2::x", "amp_short_vectors/Concurrency::graphics::double_2::r", "amp_short_vectors/Concurrency::graphics::double_2::operator--", "amp_short_vectors/Concurrency::graphics::double_2", "amp_short_vectors/Concurrency::graphics::double_2::operator-", "amp_short_vectors/Concurrency::graphics::double_2::g", "amp_short_vectors/Concurrency::graphics::double_2::set_y"] -ms.assetid: c19c2d21-3cbf-4ce5-b460-3b8253688f82 ---- -# double_2 Class - -Represent a short vector of 2 double's. - -## Syntax - -```cpp -class double_2; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[double_2 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|double_2::get_x|| -|double_2::get_xy|| -|double_2::get_y|| -|double_2::get_yx|| -|double_2::ref_g|| -|double_2::ref_r|| -|double_2::ref_x|| -|double_2::ref_y|| -|double_2::set_x|| -|double_2::set_xy|| -|double_2::set_y|| -|double_2::set_yx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|double_2::operator-|| -|double_2::operator--|| -|double_2::operator*=|| -|double_2::operator/=|| -|double_2::operator++|| -|double_2::operator+=|| -|double_2::operator=|| -|double_2::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|double_2::size Constant|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|double_2::g|| -|double_2::gr|| -|double_2::r|| -|double_2::rg|| -|double_2::x|| -|double_2::xy|| -|double_2::y|| -|double_2::yx|| - -## Inheritance Hierarchy - -`double_2` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## double_2 - -Default constructor, initializes all elements with 0. - -```cpp -double_2() restrict(amp, - cpu); - -double_2( - double _V0, - double _V1) restrict(amp, - cpu); - -double_2( - double _V) restrict(amp, - cpu); - -double_2( - const double_2& _Other) restrict(amp, - cpu); - -explicit inline double_2( - const uint_2& _Other) restrict(amp, - cpu); - -explicit inline double_2( - const int_2& _Other) restrict(amp, - cpu); - -explicit inline double_2( - const float_2& _Other) restrict(amp, - cpu); - -explicit inline double_2( - const unorm_2& _Other) restrict(amp, - cpu); - -explicit inline double_2( - const norm_2& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 2; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/double-3-class.md b/docs/parallel/amp/reference/double-3-class.md deleted file mode 100644 index 67dd97384bb..00000000000 --- a/docs/parallel/amp/reference/double-3-class.md +++ /dev/null @@ -1,205 +0,0 @@ ---- -description: "Learn more about: double_3 Class" -title: "double_3 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::double_3::get_xzy", "amp_short_vectors/Concurrency::graphics::double_3", "amp_short_vectors/Concurrency::graphics::double_3::set_yz", "amp_short_vectors/Concurrency::graphics::double_3::bgr", "amp_short_vectors/Concurrency::graphics::double_3::get_zyx", "amp_short_vectors/Concurrency::graphics::double_3::r", "amp_short_vectors/Concurrency::graphics::double_3::g", "amp_short_vectors/Concurrency::graphics::double_3::gr", "amp_short_vectors/Concurrency::graphics::double_3::yz", "amp_short_vectors/Concurrency::graphics::double_3::gbr", "amp_short_vectors/Concurrency::graphics::double_3::xyz", "amp_short_vectors/Concurrency::graphics::double_3::grb", "amp_short_vectors/Concurrency::graphics::double_3::get_z", "amp_short_vectors/Concurrency::graphics::double_3::get_xyz", "amp_short_vectors/Concurrency::graphics::double_3::set_yxz", "amp_short_vectors/Concurrency::graphics::double_3::z", "amp_short_vectors/Concurrency::graphics::double_3::zx", "amp_short_vectors/Concurrency::graphics::double_3::operator+=", "amp_short_vectors/Concurrency::graphics::double_3::rg", "amp_short_vectors/Concurrency::graphics::double_3::get_x", "amp_short_vectors/Concurrency::graphics::double_3::x", "amp_short_vectors/Concurrency::graphics::double_3::set_y", "amp_short_vectors/Concurrency::graphics::double_3::set_yx", "amp_short_vectors/Concurrency::graphics::double_3::operator-=", "amp_short_vectors/Concurrency::graphics::double_3::operator/=", "amp_short_vectors/Concurrency::graphics::double_3::get_y", "amp_short_vectors/Concurrency::graphics::double_3::zy", "amp_short_vectors/Concurrency::graphics::double_3::xy", "amp_short_vectors/Concurrency::graphics::double_3::operator-", "amp_short_vectors/Concurrency::graphics::double_3::bg", "amp_short_vectors/Concurrency::graphics::double_3::get_xz", "amp_short_vectors/Concurrency::graphics::double_3::zxy", "amp_short_vectors/Concurrency::graphics::double_3::set_xzy", "amp_short_vectors/Concurrency::graphics::double_3::set_zx", "amp_short_vectors/Concurrency::graphics::double_3::xzy", "amp_short_vectors/Concurrency::graphics::double_3::get_yzx", "amp_short_vectors/Concurrency::graphics::double_3::br", "amp_short_vectors/Concurrency::graphics::double_3::set_zxy", "amp_short_vectors/Concurrency::graphics::double_3::zyx", "amp_short_vectors/Concurrency::graphics::double_3::get_zx", "amp_short_vectors/Concurrency::graphics::double_3::operator--", "amp_short_vectors/Concurrency::graphics::double_3::b", "amp_short_vectors/Concurrency::graphics::double_3::set_xy", "amp_short_vectors/Concurrency::graphics::double_3::set_x", "amp_short_vectors/Concurrency::graphics::double_3::rb", "amp_short_vectors/Concurrency::graphics::double_3::y", "amp_short_vectors/Concurrency::graphics::double_3::set_xyz", "amp_short_vectors/Concurrency::graphics::double_3::get_xy", "amp_short_vectors/Concurrency::graphics::double_3::operator++", "amp_short_vectors/Concurrency::graphics::double_3::set_z", "amp_short_vectors/Concurrency::graphics::double_3::yx", "amp_short_vectors/Concurrency::graphics::double_3::operator*=", "amp_short_vectors/Concurrency::graphics::double_3::set_zy", "amp_short_vectors/Concurrency::graphics::double_3::rgb", "amp_short_vectors/Concurrency::graphics::double_3::set_zyx", "amp_short_vectors/Concurrency::graphics::double_3::gb", "amp_short_vectors/Concurrency::graphics::double_3::get_zy", "amp_short_vectors/Concurrency::graphics::double_3::get_yz", "amp_short_vectors/Concurrency::graphics::double_3::operator=", "amp_short_vectors/Concurrency::graphics::double_3::yxz", "amp_short_vectors/Concurrency::graphics::double_3::xz", "amp_short_vectors/Concurrency::graphics::double_3::get_zxy", "amp_short_vectors/Concurrency::graphics::double_3::set_yzx", "amp_short_vectors/Concurrency::graphics::double_3::yzx", "amp_short_vectors/Concurrency::graphics::double_3::brg", "amp_short_vectors/Concurrency::graphics::double_3::set_xz", "amp_short_vectors/Concurrency::graphics::double_3::get_yx", "amp_short_vectors/Concurrency::graphics::double_3::rbg", "amp_short_vectors/Concurrency::graphics::double_3::get_yxz"] -ms.assetid: baeb3ff0-2862-4c81-857e-b1a4c085be25 ---- -# double_3 Class - -Represents a short vector of three doubles. - -## Syntax - -```cpp -class double_3; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|value_type|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[double_3 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|double_3::get_x|| -|double_3::get_xy|| -|double_3::get_xyz|| -|double_3::get_xz|| -|double_3::get_xzy|| -|double_3::get_y|| -|double_3::get_yx|| -|double_3::get_yxz|| -|double_3::get_yz|| -|double_3::get_yzx|| -|double_3::get_z|| -|double_3::get_zx|| -|double_3::get_zxy|| -|double_3::get_zy|| -|double_3::get_zyx|| -|double_3::ref_b|| -|double_3::ref_g|| -|double_3::ref_r|| -|double_3::ref_x|| -|double_3::ref_y|| -|double_3::ref_z|| -|double_3::set_x|| -|double_3::set_xy|| -|double_3::set_xyz|| -|double_3::set_xz|| -|double_3::set_xzy|| -|double_3::set_y|| -|double_3::set_yx|| -|double_3::set_yxz|| -|double_3::set_yz|| -|double_3::set_yzx|| -|double_3::set_z|| -|double_3::set_zx|| -|double_3::set_zxy|| -|double_3::set_zy|| -|double_3::set_zyx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|double_3::operator-|| -|double_3::operator--|| -|double_3::operator*=|| -|double_3::operator/=|| -|double_3::operator++|| -|double_3::operator+=|| -|double_3::operator=|| -|double_3::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#double_3__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|double_3::b|| -|double_3::bg|| -|double_3::bgr|| -|double_3::br|| -|double_3::brg|| -|double_3::g|| -|double_3::gb|| -|double_3::gbr|| -|double_3::gr|| -|double_3::grb|| -|double_3::r|| -|double_3::rb|| -|double_3::rbg|| -|double_3::rg|| -|double_3::rgb|| -|double_3::x|| -|double_3::xy|| -|double_3::xyz|| -|double_3::xz|| -|double_3::xzy|| -|double_3::y|| -|double_3::yx|| -|double_3::yxz|| -|double_3::yz|| -|double_3::yzx|| -|double_3::z|| -|double_3::zx|| -|double_3::zxy|| -|double_3::zy|| -|double_3::zyx|| - -## Inheritance Hierarchy - -`double_3` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## double_3 - -Default constructor, initializes all elements with 0. - -```cpp -double_3() restrict(amp, - cpu); - -double_3( - double _V0, - double _V1, - double _V2) restrict(amp, - cpu); - -double_3( - double _V) restrict(amp, - cpu); - -double_3( - const double_3& _Other) restrict(amp, - cpu); - -explicit inline double_3( - const uint_3& _Other) restrict(amp, - cpu); - -explicit inline double_3( - const int_3& _Other) restrict(amp, - cpu); - -explicit inline double_3( - const float_3& _Other) restrict(amp, - cpu); - -explicit inline double_3( - const unorm_3& _Other) restrict(amp, - cpu); - -explicit inline double_3( - const norm_3& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 3; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/double-4-class.md b/docs/parallel/amp/reference/double-4-class.md deleted file mode 100644 index ef7b6325492..00000000000 --- a/docs/parallel/amp/reference/double-4-class.md +++ /dev/null @@ -1,407 +0,0 @@ ---- -description: "Learn more about: double_4 Class" -title: "double_4 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::double_4::get_xw", "amp_short_vectors/Concurrency::graphics::double_4::wxz", "amp_short_vectors/Concurrency::graphics::double_4::rag", "amp_short_vectors/Concurrency::graphics::double_4::wzx", "amp_short_vectors/Concurrency::graphics::double_4::get_yzxw", "amp_short_vectors/Concurrency::graphics::double_4::zxw", "amp_short_vectors/Concurrency::graphics::double_4::set_zwx", "amp_short_vectors/Concurrency::graphics::double_4::get_yxwz", "amp_short_vectors/Concurrency::graphics::double_4::get_wy", "amp_short_vectors/Concurrency::graphics::double_4::set_yx", "amp_short_vectors/Concurrency::graphics::double_4::rbag", "amp_short_vectors/Concurrency::graphics::double_4::ab", "amp_short_vectors/Concurrency::graphics::double_4::ywx", "amp_short_vectors/Concurrency::graphics::double_4::set_xwzy", "amp_short_vectors/Concurrency::graphics::double_4::set_wxyz", "amp_short_vectors/Concurrency::graphics::double_4::xw", "amp_short_vectors/Concurrency::graphics::double_4::set_wxz", "amp_short_vectors/Concurrency::graphics::double_4::ga", "amp_short_vectors/Concurrency::graphics::double_4::yxz", "amp_short_vectors/Concurrency::graphics::double_4::wyx", "amp_short_vectors/Concurrency::graphics::double_4::get_yz", "amp_short_vectors/Concurrency::graphics::double_4::rgba", "amp_short_vectors/Concurrency::graphics::double_4::yzwx", "amp_short_vectors/Concurrency::graphics::double_4::rgb", "amp_short_vectors/Concurrency::graphics::double_4::ywz", "amp_short_vectors/Concurrency::graphics::double_4::set_yw", "amp_short_vectors/Concurrency::graphics::double_4::get_yw", "amp_short_vectors/Concurrency::graphics::double_4::get_xy", "amp_short_vectors/Concurrency::graphics::double_4::set_zwxy", "amp_short_vectors/Concurrency::graphics::double_4::arb", "amp_short_vectors/Concurrency::graphics::double_4::abgr", "amp_short_vectors/Concurrency::graphics::double_4::xwyz", "amp_short_vectors/Concurrency::graphics::double_4::get_wxy", "amp_short_vectors/Concurrency::graphics::double_4::wzyx", "amp_short_vectors/Concurrency::graphics::double_4::zwx", "amp_short_vectors/Concurrency::graphics::double_4::wyz", "amp_short_vectors/Concurrency::graphics::double_4::xwz", "amp_short_vectors/Concurrency::graphics::double_4::set_wy", "amp_short_vectors/Concurrency::graphics::double_4::g", "amp_short_vectors/Concurrency::graphics::double_4::set_zxwy", "amp_short_vectors/Concurrency::graphics::double_4::abg", "amp_short_vectors/Concurrency::graphics::double_4::xzyw", "amp_short_vectors/Concurrency::graphics::double_4::operator++", "amp_short_vectors/Concurrency::graphics::double_4::get_yzx", "amp_short_vectors/Concurrency::graphics::double_4::set_wzx", "amp_short_vectors/Concurrency::graphics::double_4::arg", "amp_short_vectors/Concurrency::graphics::double_4::rab", "amp_short_vectors/Concurrency::graphics::double_4::set_zwyx", "amp_short_vectors/Concurrency::graphics::double_4::ba", "amp_short_vectors/Concurrency::graphics::double_4::w", "amp_short_vectors/Concurrency::graphics::double_4::set_yxwz", "amp_short_vectors/Concurrency::graphics::double_4::ywxz", "amp_short_vectors/Concurrency::graphics::double_4::bar", "amp_short_vectors/Concurrency::graphics::double_4::set_xz", "amp_short_vectors/Concurrency::graphics::double_4::yxzw", "amp_short_vectors/Concurrency::graphics::double_4::get_xzyw", "amp_short_vectors/Concurrency::graphics::double_4::get_wxzy", "amp_short_vectors/Concurrency::graphics::double_4::garb", "amp_short_vectors/Concurrency::graphics::double_4::zwyx", "amp_short_vectors/Concurrency::graphics::double_4::set_yxz", "amp_short_vectors/Concurrency::graphics::double_4::get_xzw", "amp_short_vectors/Concurrency::graphics::double_4::wzy", "amp_short_vectors/Concurrency::graphics::double_4::get_xz", "amp_short_vectors/Concurrency::graphics::double_4::barg", "amp_short_vectors/Concurrency::graphics::double_4::get_zwyx", "amp_short_vectors/Concurrency::graphics::double_4::operator-=", "amp_short_vectors/Concurrency::graphics::double_4::set_yzwx", "amp_short_vectors/Concurrency::graphics::double_4::get_wxz", "amp_short_vectors/Concurrency::graphics::double_4::gabr", "amp_short_vectors/Concurrency::graphics::double_4::set_wxzy", "amp_short_vectors/Concurrency::graphics::double_4::operator/=", "amp_short_vectors/Concurrency::graphics::double_4::zxy", "amp_short_vectors/Concurrency::graphics::double_4::set_zx", "amp_short_vectors/Concurrency::graphics::double_4::get_ywzx", "amp_short_vectors/Concurrency::graphics::double_4::grab", "amp_short_vectors/Concurrency::graphics::double_4::set_ywzx", "amp_short_vectors/Concurrency::graphics::double_4::get_zy", "amp_short_vectors/Concurrency::graphics::double_4::wxzy", "amp_short_vectors/Concurrency::graphics::double_4::yzx", "amp_short_vectors/Concurrency::graphics::double_4::brag", "amp_short_vectors/Concurrency::graphics::double_4::get_wyz", "amp_short_vectors/Concurrency::graphics::double_4::set_yxw", "amp_short_vectors/Concurrency::graphics::double_4::set_xzw", "amp_short_vectors/Concurrency::graphics::double_4::get_zx", "amp_short_vectors/Concurrency::graphics::double_4::get_zxyw", "amp_short_vectors/Concurrency::graphics::double_4::get_zyxw", "amp_short_vectors/Concurrency::graphics::double_4::set_xzwy", "amp_short_vectors/Concurrency::graphics::double_4::get_xyzw", "amp_short_vectors/Concurrency::graphics::double_4::get_xywz", "amp_short_vectors/Concurrency::graphics::double_4::operator-", "amp_short_vectors/Concurrency::graphics::double_4::bga", "amp_short_vectors/Concurrency::graphics::double_4::bgra", "amp_short_vectors/Concurrency::graphics::double_4::set_yzxw", "amp_short_vectors/Concurrency::graphics::double_4::abr", "amp_short_vectors/Concurrency::graphics::double_4::brga", "amp_short_vectors/Concurrency::graphics::double_4::rga", "amp_short_vectors/Concurrency::graphics::double_4::yxw", "amp_short_vectors/Concurrency::graphics::double_4::abrg", "amp_short_vectors/Concurrency::graphics::double_4::gbr", "amp_short_vectors/Concurrency::graphics::double_4::set_wzyx", "amp_short_vectors/Concurrency::graphics::double_4::set_zyxw", "amp_short_vectors/Concurrency::graphics::double_4::xz", "amp_short_vectors/Concurrency::graphics::double_4::get_zxy", "amp_short_vectors/Concurrency::graphics::double_4::set_zw", "amp_short_vectors/Concurrency::graphics::double_4::wy", "amp_short_vectors/Concurrency::graphics::double_4::zx", "amp_short_vectors/Concurrency::graphics::double_4::set_xy", "amp_short_vectors/Concurrency::graphics::double_4::rabg", "amp_short_vectors/Concurrency::graphics::double_4::set_zwy", "amp_short_vectors/Concurrency::graphics::double_4::xzwy", "amp_short_vectors/Concurrency::graphics::double_4::bgar", "amp_short_vectors/Concurrency::graphics::double_4::operator+=", "amp_short_vectors/Concurrency::graphics::double_4::get_xwz", "amp_short_vectors/Concurrency::graphics::double_4::operator*=", "amp_short_vectors/Concurrency::graphics::double_4::get_yxw", "amp_short_vectors/Concurrency::graphics::double_4::y", "amp_short_vectors/Concurrency::graphics::double_4::set_zy", "amp_short_vectors/Concurrency::graphics::double_4::wzxy", "amp_short_vectors/Concurrency::graphics::double_4::get_xwy", "amp_short_vectors/Concurrency::graphics::double_4::xzy", "amp_short_vectors/Concurrency::graphics::double_4::set_zywx", "amp_short_vectors/Concurrency::graphics::double_4::yxwz", "amp_short_vectors/Concurrency::graphics::double_4::ragb", "amp_short_vectors/Concurrency::graphics::double_4::get_zyx", "amp_short_vectors/Concurrency::graphics::double_4::agb", "amp_short_vectors/Concurrency::graphics::double_4::gar", "amp_short_vectors/Concurrency::graphics::double_4::get_wyxz", "amp_short_vectors/Concurrency::graphics::double_4::a", "amp_short_vectors/Concurrency::graphics::double_4::set_wyx", "amp_short_vectors/Concurrency::graphics::double_4::rg", "amp_short_vectors/Concurrency::graphics::double_4::set_xzyw", "amp_short_vectors/Concurrency::graphics::double_4::get_ywx", "amp_short_vectors/Concurrency::graphics::double_4::yx", "amp_short_vectors/Concurrency::graphics::double_4::get_wyzx", "amp_short_vectors/Concurrency::graphics::double_4::set_w", "amp_short_vectors/Concurrency::graphics::double_4::set_zyx", "amp_short_vectors/Concurrency::graphics::double_4::set_wyz", "amp_short_vectors/Concurrency::graphics::double_4::set_wzxy", "amp_short_vectors/Concurrency::graphics::double_4::wyzx", "amp_short_vectors/Concurrency::graphics::double_4::gbar", "amp_short_vectors/Concurrency::graphics::double_4::operator=", "amp_short_vectors/Concurrency::graphics::double_4::x", "amp_short_vectors/Concurrency::graphics::double_4::get_y", "amp_short_vectors/Concurrency::graphics::double_4::set_wx", "amp_short_vectors/Concurrency::graphics::double_4::get_zyw", "amp_short_vectors/Concurrency::graphics::double_4::set_xywz", "amp_short_vectors/Concurrency::graphics::double_4::zyxw", "amp_short_vectors/Concurrency::graphics::double_4::get_zywx", "amp_short_vectors/Concurrency::graphics::double_4::yzw", "amp_short_vectors/Concurrency::graphics::double_4::xyw", "amp_short_vectors/Concurrency::graphics::double_4::bra", "amp_short_vectors/Concurrency::graphics::double_4::agr", "amp_short_vectors/Concurrency::graphics::double_4::zw", "amp_short_vectors/Concurrency::graphics::double_4::get_xwyz", "amp_short_vectors/Concurrency::graphics::double_4::gbra", "amp_short_vectors/Concurrency::graphics::double_4::get_wz", "amp_short_vectors/Concurrency::graphics::double_4::brg", "amp_short_vectors/Concurrency::graphics::double_4::xyz", "amp_short_vectors/Concurrency::graphics::double_4::set_y", "amp_short_vectors/Concurrency::graphics::double_4::set_wyxz", "amp_short_vectors/Concurrency::graphics::double_4::set_z", "amp_short_vectors/Concurrency::graphics::double_4::zwxy", "amp_short_vectors/Concurrency::graphics::double_4::get_ywxz", "amp_short_vectors/Concurrency::graphics::double_4::set_xwy", "amp_short_vectors/Concurrency::graphics::double_4::xyzw", "amp_short_vectors/Concurrency::graphics::double_4::get_x", "amp_short_vectors/Concurrency::graphics::double_4::get_zw", "amp_short_vectors/Concurrency::graphics::double_4::rbga", "amp_short_vectors/Concurrency::graphics::double_4::gr", "amp_short_vectors/Concurrency::graphics::double_4::set_xyzw", "amp_short_vectors/Concurrency::graphics::double_4::get_xzwy", "amp_short_vectors/Concurrency::graphics::double_4::gb", "amp_short_vectors/Concurrency::graphics::double_4::zxyw", "amp_short_vectors/Concurrency::graphics::double_4::set_zxw", "amp_short_vectors/Concurrency::graphics::double_4::gab", "amp_short_vectors/Concurrency::graphics::double_4::xwy", "amp_short_vectors/Concurrency::graphics::double_4::wxyz", "amp_short_vectors/Concurrency::graphics::double_4::wx", "amp_short_vectors/Concurrency::graphics::double_4::gra", "amp_short_vectors/Concurrency::graphics::double_4::xwzy", "amp_short_vectors/Concurrency::graphics::double_4::wxy", "amp_short_vectors/Concurrency::graphics::double_4::set_ywz", "amp_short_vectors/Concurrency::graphics::double_4::set_xw", "amp_short_vectors/Concurrency::graphics::double_4::set_yxzw", "amp_short_vectors/Concurrency::graphics::double_4::set_zyw", "amp_short_vectors/Concurrency::graphics::double_4::get_zwy", "amp_short_vectors/Concurrency::graphics::double_4::agrb", "amp_short_vectors/Concurrency::graphics::double_4::get_yxzw", "amp_short_vectors/Concurrency::graphics::double_4::grb", "amp_short_vectors/Concurrency::graphics::double_4::get_yx", "amp_short_vectors/Concurrency::graphics::double_4::gba", "amp_short_vectors/Concurrency::graphics::double_4::set_ywxz", "amp_short_vectors/Concurrency::graphics::double_4::ywzx", "amp_short_vectors/Concurrency::graphics::double_4::yzxw", "amp_short_vectors/Concurrency::graphics::double_4::zyx", "amp_short_vectors/Concurrency::graphics::double_4::get_yxz", "amp_short_vectors/Concurrency::graphics::double_4::set_yzw", "amp_short_vectors/Concurrency::graphics::double_4::xzw", "amp_short_vectors/Concurrency::graphics::double_4::wz", "amp_short_vectors/Concurrency::graphics::double_4::yw", "amp_short_vectors/Concurrency::graphics::double_4::set_zxyw", "amp_short_vectors/Concurrency::graphics::double_4::get_yzw", "amp_short_vectors/Concurrency::graphics::double_4::get_xyw", "amp_short_vectors/Concurrency::graphics::double_4::get_wzx", "amp_short_vectors/Concurrency::graphics::double_4::argb", "amp_short_vectors/Concurrency::graphics::double_4::set_ywx", "amp_short_vectors/Concurrency::graphics::double_4::get_zwx", "amp_short_vectors/Concurrency::graphics::double_4::set_xyw", "amp_short_vectors/Concurrency::graphics::double_4::r", "amp_short_vectors/Concurrency::graphics::double_4::set_yzx", "amp_short_vectors/Concurrency::graphics::double_4::agbr", "amp_short_vectors/Concurrency::graphics::double_4::set_wzy", "amp_short_vectors/Concurrency::graphics::double_4::xywz", "amp_short_vectors/Concurrency::graphics::double_4::set_wyzx", "amp_short_vectors/Concurrency::graphics::double_4::grba", "amp_short_vectors/Concurrency::graphics::double_4::bg", "amp_short_vectors/Concurrency::graphics::double_4::get_zwxy", "amp_short_vectors/Concurrency::graphics::double_4::get_wyx", "amp_short_vectors/Concurrency::graphics::double_4::get_zxwy", "amp_short_vectors/Concurrency::graphics::double_4::set_zxy", "amp_short_vectors/Concurrency::graphics::double_4::get_w", "amp_short_vectors/Concurrency::graphics::double_4", "amp_short_vectors/Concurrency::graphics::double_4::set_x", "amp_short_vectors/Concurrency::graphics::double_4::bgr", "amp_short_vectors/Concurrency::graphics::double_4::xy", "amp_short_vectors/Concurrency::graphics::double_4::yz", "amp_short_vectors/Concurrency::graphics::double_4::get_wzxy", "amp_short_vectors/Concurrency::graphics::double_4::rbg", "amp_short_vectors/Concurrency::graphics::double_4::get_xzy", "amp_short_vectors/Concurrency::graphics::double_4::operator--", "amp_short_vectors/Concurrency::graphics::double_4::z", "amp_short_vectors/Concurrency::graphics::double_4::b", "amp_short_vectors/Concurrency::graphics::double_4::set_wz", "amp_short_vectors/Concurrency::graphics::double_4::arbg", "amp_short_vectors/Concurrency::graphics::double_4::rba", "amp_short_vectors/Concurrency::graphics::double_4::get_zxw", "amp_short_vectors/Concurrency::graphics::double_4::get_wxyz", "amp_short_vectors/Concurrency::graphics::double_4::ag", "amp_short_vectors/Concurrency::graphics::double_4::zxwy", "amp_short_vectors/Concurrency::graphics::double_4::get_ywz", "amp_short_vectors/Concurrency::graphics::double_4::get_xyz", "amp_short_vectors/Concurrency::graphics::double_4::get_wzy", "amp_short_vectors/Concurrency::graphics::double_4::zy", "amp_short_vectors/Concurrency::graphics::double_4::set_xyz", "amp_short_vectors/Concurrency::graphics::double_4::set_wxy", "amp_short_vectors/Concurrency::graphics::double_4::get_wx", "amp_short_vectors/Concurrency::graphics::double_4::rb", "amp_short_vectors/Concurrency::graphics::double_4::get_wzyx", "amp_short_vectors/Concurrency::graphics::double_4::get_yzwx", "amp_short_vectors/Concurrency::graphics::double_4::rgab", "amp_short_vectors/Concurrency::graphics::double_4::set_xwz", "amp_short_vectors/Concurrency::graphics::double_4::get_z", "amp_short_vectors/Concurrency::graphics::double_4::br", "amp_short_vectors/Concurrency::graphics::double_4::bagr", "amp_short_vectors/Concurrency::graphics::double_4::zywx", "amp_short_vectors/Concurrency::graphics::double_4::set_xzy", "amp_short_vectors/Concurrency::graphics::double_4::set_yz", "amp_short_vectors/Concurrency::graphics::double_4::zyw", "amp_short_vectors/Concurrency::graphics::double_4::ar", "amp_short_vectors/Concurrency::graphics::double_4::wyxz", "amp_short_vectors/Concurrency::graphics::double_4::get_xwzy", "amp_short_vectors/Concurrency::graphics::double_4::ra", "amp_short_vectors/Concurrency::graphics::double_4::set_xwyz", "amp_short_vectors/Concurrency::graphics::double_4::bag", "amp_short_vectors/Concurrency::graphics::double_4::zwy"] -ms.assetid: a81c1595-24c6-4b3f-9574-d5942275e5e8 ---- -# double_4 Class - -Represents a short vector of four doubles. - -## Syntax - -```cpp -class double_4; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[double_4 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|double_4::get_w|| -|double_4::get_wx|| -|double_4::get_wxy|| -|double_4::get_wxyz|| -|double_4::get_wxz|| -|double_4::get_wxzy|| -|double_4::get_wy|| -|double_4::get_wyx|| -|double_4::get_wyxz|| -|double_4::get_wyz|| -|double_4::get_wyzx|| -|double_4::get_wz|| -|double_4::get_wzx|| -|double_4::get_wzxy|| -|double_4::get_wzy|| -|double_4::get_wzyx|| -|double_4::get_x|| -|double_4::get_xw|| -|double_4::get_xwy|| -|double_4::get_xwyz|| -|double_4::get_xwz|| -|double_4::get_xwzy|| -|double_4::get_xy|| -|double_4::get_xyw|| -|double_4::get_xywz|| -|double_4::get_xyz|| -|double_4::get_xyzw|| -|double_4::get_xz|| -|double_4::get_xzw|| -|double_4::get_xzwy|| -|double_4::get_xzy|| -|double_4::get_xzyw|| -|double_4::get_y|| -|double_4::get_yw|| -|double_4::get_ywx|| -|double_4::get_ywxz|| -|double_4::get_ywz|| -|double_4::get_ywzx|| -|double_4::get_yx|| -|double_4::get_yxw|| -|double_4::get_yxwz|| -|double_4::get_yxz|| -|double_4::get_yxzw|| -|double_4::get_yz|| -|double_4::get_yzw|| -|double_4::get_yzwx|| -|double_4::get_yzx|| -|double_4::get_yzxw|| -|double_4::get_z|| -|double_4::get_zw|| -|double_4::get_zwx|| -|double_4::get_zwxy|| -|double_4::get_zwy|| -|double_4::get_zwyx|| -|double_4::get_zx|| -|double_4::get_zxw|| -|double_4::get_zxwy|| -|double_4::get_zxy|| -|double_4::get_zxyw|| -|double_4::get_zy|| -|double_4::get_zyw|| -|double_4::get_zywx|| -|double_4::get_zyx|| -|double_4::get_zyxw|| -|double_4::ref_a|| -|double_4::ref_b|| -|double_4::ref_g|| -|double_4::ref_r|| -|double_4::ref_w|| -|double_4::ref_x|| -|double_4::ref_y|| -|double_4::ref_z|| -|double_4::set_w|| -|double_4::set_wx|| -|double_4::set_wxy|| -|double_4::set_wxyz|| -|double_4::set_wxz|| -|double_4::set_wxzy|| -|double_4::set_wy|| -|double_4::set_wyx|| -|double_4::set_wyxz|| -|double_4::set_wyz|| -|double_4::set_wyzx|| -|double_4::set_wz|| -|double_4::set_wzx|| -|double_4::set_wzxy|| -|double_4::set_wzy|| -|double_4::set_wzyx|| -|double_4::set_x|| -|double_4::set_xw|| -|double_4::set_xwy|| -|double_4::set_xwyz|| -|double_4::set_xwz|| -|double_4::set_xwzy|| -|double_4::set_xy|| -|double_4::set_xyw|| -|double_4::set_xywz|| -|double_4::set_xyz|| -|double_4::set_xyzw|| -|double_4::set_xz|| -|double_4::set_xzw|| -|double_4::set_xzwy|| -|double_4::set_xzy|| -|double_4::set_xzyw|| -|double_4::set_y|| -|double_4::set_yw|| -|double_4::set_ywx|| -|double_4::set_ywxz|| -|double_4::set_ywz|| -|double_4::set_ywzx|| -|double_4::set_yx|| -|double_4::set_yxw|| -|double_4::set_yxwz|| -|double_4::set_yxz|| -|double_4::set_yxzw|| -|double_4::set_yz|| -|double_4::set_yzw|| -|double_4::set_yzwx|| -|double_4::set_yzx|| -|double_4::set_yzxw|| -|double_4::set_z|| -|double_4::set_zw|| -|double_4::set_zwx|| -|double_4::set_zwxy|| -|double_4::set_zwy|| -|double_4::set_zwyx|| -|double_4::set_zx|| -|double_4::set_zxw|| -|double_4::set_zxwy|| -|double_4::set_zxy|| -|double_4::set_zxyw|| -|double_4::set_zy|| -|double_4::set_zyw|| -|double_4::set_zywx|| -|double_4::set_zyx|| -|double_4::set_zyxw|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|double_4::operator-|| -|double_4::operator--|| -|double_4::operator*=|| -|double_4::operator/=|| -|double_4::operator++|| -|double_4::operator+=|| -|double_4::operator=|| -|double_4::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#double_4__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|double_4::a|| -|double_4::ab|| -|double_4::abg|| -|double_4::abgr|| -|double_4::abr|| -|double_4::abrg|| -|double_4::ag|| -|double_4::agb|| -|double_4::agbr|| -|double_4::agr|| -|double_4::agrb|| -|double_4::ar|| -|double_4::arb|| -|double_4::arbg|| -|double_4::arg|| -|double_4::argb|| -|double_4::b|| -|double_4::ba|| -|double_4::bag|| -|double_4::bagr|| -|double_4::bar|| -|double_4::barg|| -|double_4::bg|| -|double_4::bga|| -|double_4::bgar|| -|double_4::bgr|| -|double_4::bgra|| -|double_4::br|| -|double_4::bra|| -|double_4::brag|| -|double_4::brg|| -|double_4::brga|| -|double_4::g|| -|double_4::ga|| -|double_4::gab|| -|double_4::gabr|| -|double_4::gar|| -|double_4::garb|| -|double_4::gb|| -|double_4::gba|| -|double_4::gbar|| -|double_4::gbr|| -|double_4::gbra|| -|double_4::gr|| -|double_4::gra|| -|double_4::grab|| -|double_4::grb|| -|double_4::grba|| -|double_4::r|| -|double_4::ra|| -|double_4::rab|| -|double_4::rabg|| -|double_4::rag|| -|double_4::ragb|| -|double_4::rb|| -|double_4::rba|| -|double_4::rbag|| -|double_4::rbg|| -|double_4::rbga|| -|double_4::rg|| -|double_4::rga|| -|double_4::rgab|| -|double_4::rgb|| -|double_4::rgba|| -|double_4::w|| -|double_4::wx|| -|double_4::wxy|| -|double_4::wxyz|| -|double_4::wxz|| -|double_4::wxzy|| -|double_4::wy|| -|double_4::wyx|| -|double_4::wyxz|| -|double_4::wyz|| -|double_4::wyzx|| -|double_4::wz|| -|double_4::wzx|| -|double_4::wzxy|| -|double_4::wzy|| -|double_4::wzyx|| -|double_4::x|| -|double_4::xw|| -|double_4::xwy|| -|double_4::xwyz|| -|double_4::xwz|| -|double_4::xwzy|| -|double_4::xy|| -|double_4::xyw|| -|double_4::xywz|| -|double_4::xyz|| -|double_4::xyzw|| -|double_4::xz|| -|double_4::xzw|| -|double_4::xzwy|| -|double_4::xzy|| -|double_4::xzyw|| -|double_4::y|| -|double_4::yw|| -|double_4::ywx|| -|double_4::ywxz|| -|double_4::ywz|| -|double_4::ywzx|| -|double_4::yx|| -|double_4::yxw|| -|double_4::yxwz|| -|double_4::yxz|| -|double_4::yxzw|| -|double_4::yz|| -|double_4::yzw|| -|double_4::yzwx|| -|double_4::yzx|| -|double_4::yzxw|| -|double_4::z|| -|double_4::zw|| -|double_4::zwx|| -|double_4::zwxy|| -|double_4::zwy|| -|double_4::zwyx|| -|double_4::zx|| -|double_4::zxw|| -|double_4::zxwy|| -|double_4::zxy|| -|double_4::zxyw|| -|double_4::zy|| -|double_4::zyw|| -|double_4::zywx|| -|double_4::zyx|| -|double_4::zyxw|| - -## Inheritance Hierarchy - -`double_4` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## double_4 - -Default constructor, initializes all elements with 0. - -```cpp -double_4() restrict(amp, - cpu); - -double_4( - double _V0, - double _V1, - double _V2, - double _V3) restrict(amp, - cpu); - -double_4( - double _V) restrict(amp, - cpu); - -double_4( - const double_4& _Other) restrict(amp, - cpu); - -explicit inline double_4( - const uint_4& _Other) restrict(amp, - cpu); - -explicit inline double_4( - const int_4& _Other) restrict(amp, - cpu); - -explicit inline double_4( - const float_4& _Other) restrict(amp, - cpu); - -explicit inline double_4( - const unorm_4& _Other) restrict(amp, - cpu); - -explicit inline double_4( - const norm_4& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V3*
-The value to initialize element 3. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 4; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/extent-class.md b/docs/parallel/amp/reference/extent-class.md deleted file mode 100644 index d14304486f9..00000000000 --- a/docs/parallel/amp/reference/extent-class.md +++ /dev/null @@ -1,385 +0,0 @@ ---- -description: "Learn more about: extent Class (C++ AMP)" -title: "extent Class (C++ AMP)" -ms.date: "03/27/2019" -f1_keywords: ["extent", "AMP/extent", "AMP/Concurrency::extent::extent", "AMP/Concurrency::extent::contains", "AMP/Concurrency::extent::size", "AMP/Concurrency::extent::tile", "AMP/Concurrency::extent::rank Constant"] -helpviewer_keywords: ["extent structure"] -ms.assetid: edb5de3d-3935-4dbb-8365-4cc6c4fb0269 ---- -# extent Class (C++ AMP) - -Represents a vector of *N* integer values that specify the bounds of an *N*-dimensional space that has an origin of 0. The values in the vector are ordered from most significant to least significant. - -## Syntax - -```cpp -template -class extent; -``` - -### Parameters - -*_Rank*
-The rank of the `extent` object. - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[extent Constructor](#ctor)|Initializes a new instance of the `extent` class.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[contains](#contains)|Verifies that the specified `extent` object has the specified rank.| -|[size](#size)|Returns the total linear size of the extent (in units of elements).| -|[tile](#tile)|Produces a `tiled_extent` object with the tile extents given by specified dimensions.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator-](#operator_min)|Returns a new `extent` object that's created by subtracting the `index` elements from the corresponding `extent` elements.| -|[operator--](#operator_min_min)|Decrements each element of the `extent` object.| -|[operator%=](#operator_mod_eq)|Calculates the modulus (remainder) of each element in the `extent` object when that element is divided by a number.| -|[operator*=](#operator_star_eq)|Multiplies each element of the `extent` object by a number.| -|[operator/=](#operator_min_eq)|Divides each element of the `extent` object by a number.| -|[extent::operator\[\]](#operator_at)|Returns the element that's at the specified index.| -|[operator+](#operator_add)|Returns a new `extent` object that's created by adding the corresponding `index` and `extent` elements.| -|[operator++](#operator_add_add)|Increments each element of the `extent` object.| -|[operator+=](#operator_add_eq)|Adds the specified number to each element of the `extent` object.| -|[operator=](#operator_eq)|Copies the contents of another `extent` object into this one.| -|[operator-=](#operator_min_eq)|Subtracts the specified number from each element of the `extent` object.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[rank Constant](#rank_constant)|Gets the rank of the `extent` object.| - -## Inheritance Hierarchy - -`extent` - -## contains - -Indicates whether the specified [index](index-class.md) value is contained within the `extent` object. - -### Syntax - -```cpp -bool contains(const index& _Index) const restrict(amp,cpu); -``` - -### Parameters - -*_Index*
-The `index` value to test. - -### Return Value - -**`true`** if the specified *index* value is contained in the `extent` object; otherwise, **`false`**. - -## extent - -Initializes a new instance of the `extent` class. - -### Syntax - -```cpp -extent() restrict(amp,cpu); -extent(const extent<_Rank>& _Other) restrict(amp,cpu); -explicit extent(int _I) restrict(amp,cpu); -extent(int _I0, int _I1) restrict(amp,cpu); -extent(int _I0, int _I1, int _I2) restrict(amp,cpu); -explicit extent(const int _Array[_Rank])restrict(amp,cpu); -``` - -### Parameters - -*_Array*
-An array of `_Rank` integers that is used to create the new `extent` object. - -*_I*
-The length of the extent. - -*_I0*
-The length of the most significant dimension. - -*_I1*
-The length of the next-to-most-significant dimension. - -*_I2*
-The length of the least significant dimension. - -*_Other*
-An `extent` object on which the new `extent` object is based. - -## Remarks - -The default constructor initializes an `extent` object that has a rank of three. - -If an array is used to construct an `extent` object, the length of the array must match the rank of the `extent` object. - -## operator%= - -Calculates the modulus (remainder) of each element in the `extent` when that element is divided by a number. - -### Syntax - -```cpp -extent<_Rank>& operator%=(int _Rhs) restrict(cpu, direct3d); -``` - -### Parameters - -*_Rhs*
-The number to find the modulus of. - -### Return Value - -The `extent` object. - -## operator*= - -Multiplies each element in the `extent` object by the specified number. - -### Syntax - -```cpp -extent<_Rank>& operator*=(int _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number to multiply. - -### Return Value - -The `extent` object. - -## operator+ - -Returns a new `extent` object created by adding the corresponding `index` and `extent` elements. - -### Syntax - -```cpp -extent<_Rank> operator+(const index<_Rank>& _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The `index` object that contains the elements to add. - -### Return Value - -The new `extent` object. - -## operator++ - -Increments each element of the `extent` object. - -### Syntax - -```cpp -extent<_Rank>& operator++() restrict(amp,cpu); -extent<_Rank> operator++(int)restrict(amp,cpu); -``` - -### Return Value - -For the prefix operator, the `extent` object (**`*this`**). For the suffix operator, a new `extent` object. - -## operator+= - -Adds the specified number to each element of the `extent` object. - -### Syntax - -```cpp -extent<_Rank>& operator+=(const extent<_Rank>& _Rhs) restrict(amp,cpu); -extent<_Rank>& operator+=(const index<_Rank>& _Rhs) restrict(amp,cpu); -extent<_Rank>& operator+=(int _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number, index, or extent to add. - -### Return Value - -The resulting `extent` object. - -## operator- - -Creates a new `extent` object by subtracting each element in the specified `index` object from the corresponding element in this `extent` object. - -### Syntax - -```cpp -extent<_Rank> operator-(const index<_Rank>& _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The `index` object that contains the elements to subtract. - -### Return Value - -The new `extent` object. - -## operator-- - -Decrements each element in the `extent` object. - -### Syntax - -```cpp -extent<_Rank>& operator--() restrict(amp,cpu); -extent<_Rank> operator--(int)restrict(amp,cpu); -``` - -### Return Value - -For the prefix operator, the `extent` object (**`*this`**). For the suffix operator, a new `extent` object. - -## operator/= - -Divides each element in the `extent` object by the specified number. - -### Syntax - -```cpp -extent<_Rank>& operator/=(int _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number to divide by. - -### Return Value - -The `extent` object. - -## operator-= - -Subtracts the specified number from each element of the `extent` object. - -### Syntax - -```cpp -extent<_Rank>& operator-=(const extent<_Rank>& _Rhs) restrict(amp,cpu); -extent<_Rank>& operator-=(const index<_Rank>& _Rhs) restrict(amp,cpu); -extent<_Rank>& operator-=(int _Rhs) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number to subtract. - -### Return Value - -The resulting `extent` object. - -## operator= - -Copies the contents of another `extent` object into this one. - -### Syntax - -```cpp -extent<_Rank>& operator=(const extent<_Rank>& _Other) restrict(amp,cpu); -``` - -### Parameters - -*_Other*
-The `extent` object to copy from. - -### Return Value - -A reference to this `extent` object. - -## extent::operator \[\] - -Returns the element that's at the specified index. - -### Syntax - -```cpp -int operator[](unsigned int _Index) const restrict(amp,cpu); -int& operator[](unsigned int _Index) restrict(amp,cpu); -``` - -### Parameters - -*_Index*
-An integer from 0 through the rank minus 1. - -### Return Value - -The element that's at the specified index. - -## rank - -Stores the rank of the `extent` object. - -### Syntax - -```cpp -static const int rank = _Rank; -``` - -## size - -Returns the total linear size of the `extent` object (in units of elements). - -### Syntax - -```cpp -unsigned int size() const restrict(amp,cpu); -``` - -## tile - -Produces a tiled_extent object with the specified tile dimensions. - -```cpp -template -tiled_extent<_Dim0> tile() const ; - -template -tiled_extent<_Dim0, _Dim1> tile() const ; - -template -tiled_extent<_Dim0, _Dim1, _Dim2> tile() const ; -``` - -### Parameters - -*_Dim0*
-The most significant component of the tiled extent. -*_Dim1*
-The next-to-most-significant component of the tiled extent. -*_Dim2*
-The least significant component of the tiled extent. - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/float-2-class.md b/docs/parallel/amp/reference/float-2-class.md deleted file mode 100644 index 4f6befc7b98..00000000000 --- a/docs/parallel/amp/reference/float-2-class.md +++ /dev/null @@ -1,155 +0,0 @@ ---- -description: "Learn more about: float_2 Class" -title: "float_2 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::float_2::yx", "amp_short_vectors/Concurrency::graphics::float_2::operator-=", "amp_short_vectors/Concurrency::graphics::float_2::operator++", "amp_short_vectors/Concurrency::graphics::float_2::operator-", "amp_short_vectors/Concurrency::graphics::float_2::r", "amp_short_vectors/Concurrency::graphics::float_2::get_yx", "amp_short_vectors/Concurrency::graphics::float_2::get_xy", "amp_short_vectors/Concurrency::graphics::float_2::operator/=", "amp_short_vectors/Concurrency::graphics::float_2::set_yx", "amp_short_vectors/Concurrency::graphics::float_2::x", "amp_short_vectors/Concurrency::graphics::float_2::get_y", "amp_short_vectors/Concurrency::graphics::float_2::operator+=", "amp_short_vectors/Concurrency::graphics::float_2::gr", "amp_short_vectors/Concurrency::graphics::float_2::operator=", "amp_short_vectors/Concurrency::graphics::float_2::set_x", "amp_short_vectors/Concurrency::graphics::float_2::operator--", "amp_short_vectors/Concurrency::graphics::float_2::get_x", "amp_short_vectors/Concurrency::graphics::float_2::operator*=", "amp_short_vectors/Concurrency::graphics::float_2::rg", "amp_short_vectors/Concurrency::graphics::float_2::set_xy", "amp_short_vectors/Concurrency::graphics::float_2::xy", "amp_short_vectors/Concurrency::graphics::float_2", "amp_short_vectors/Concurrency::graphics::float_2::set_y", "amp_short_vectors/Concurrency::graphics::float_2::y", "amp_short_vectors/Concurrency::graphics::float_2::g"] -ms.assetid: b3ebd48e-f8c8-4f00-a640-357f702f0cae ---- -# float_2 Class - -Represents a short vector of two floats. - -## Syntax - -```cpp -class float_2; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[float_2 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|float_2::get_x|| -|float_2::get_xy|| -|float_2::get_y|| -|float_2::get_yx|| -|float_2::ref_g|| -|float_2::ref_r|| -|float_2::ref_x|| -|float_2::ref_y|| -|float_2::set_x|| -|float_2::set_xy|| -|float_2::set_y|| -|float_2::set_yx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|float_2::operator-|| -|float_2::operator--|| -|float_2::operator*=|| -|float_2::operator/=|| -|float_2::operator++|| -|float_2::operator+=|| -|float_2::operator=|| -|float_2::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#float_2__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|float_2::g|| -|float_2::gr|| -|float_2::r|| -|float_2::rg|| -|float_2::x|| -|float_2::xy|| -|float_2::y|| -|float_2::yx|| - -## Inheritance Hierarchy - -`float_2` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## float_2 - -Default constructor, initializes all elements with 0. - -```cpp -float_2() restrict(amp, - cpu); - -float_2( - float _V0, - float _V1) restrict(amp, - cpu); - -float_2( - float _V) restrict(amp, - cpu); - -float_2( - const float_2& _Other) restrict(amp, - cpu); - -explicit inline float_2( - const uint_2& _Other) restrict(amp, - cpu); - -explicit inline float_2( - const int_2& _Other) restrict(amp, - cpu); - -explicit inline float_2( - const unorm_2& _Other) restrict(amp, - cpu); - -explicit inline float_2( - const norm_2& _Other) restrict(amp, - cpu); - -explicit inline float_2( - const double_2& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 2; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/float-3-class.md b/docs/parallel/amp/reference/float-3-class.md deleted file mode 100644 index 0a4ac77c7da..00000000000 --- a/docs/parallel/amp/reference/float-3-class.md +++ /dev/null @@ -1,206 +0,0 @@ ---- -description: "Learn more about: float_3 Class" -title: "float_3 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::float_3::get_zyx", "amp_short_vectors/Concurrency::graphics::float_3::set_y", "amp_short_vectors/Concurrency::graphics::float_3::b", "amp_short_vectors/Concurrency::graphics::float_3::operator-=", "amp_short_vectors/Concurrency::graphics::float_3::get_y", "amp_short_vectors/Concurrency::graphics::float_3::set_zy", "amp_short_vectors/Concurrency::graphics::float_3::get_yzx", "amp_short_vectors/Concurrency::graphics::float_3::xz", "amp_short_vectors/Concurrency::graphics::float_3::xyz", "amp_short_vectors/Concurrency::graphics::float_3::operator+=", "amp_short_vectors/Concurrency::graphics::float_3::brg", "amp_short_vectors/Concurrency::graphics::float_3::get_x", "amp_short_vectors/Concurrency::graphics::float_3::get_zx", "amp_short_vectors/Concurrency::graphics::float_3::y", "amp_short_vectors/Concurrency::graphics::float_3::rbg", "amp_short_vectors/Concurrency::graphics::float_3::operator-", "amp_short_vectors/Concurrency::graphics::float_3::get_yz", "amp_short_vectors/Concurrency::graphics::float_3::set_xz", "amp_short_vectors/Concurrency::graphics::float_3::operator/=", "amp_short_vectors/Concurrency::graphics::float_3::zxy", "amp_short_vectors/Concurrency::graphics::float_3::yx", "amp_short_vectors/Concurrency::graphics::float_3::g", "amp_short_vectors/Concurrency::graphics::float_3::r", "amp_short_vectors/Concurrency::graphics::float_3::zy", "amp_short_vectors/Concurrency::graphics::float_3::set_zxy", "amp_short_vectors/Concurrency::graphics::float_3::set_zyx", "amp_short_vectors/Concurrency::graphics::float_3::get_yx", "amp_short_vectors/Concurrency::graphics::float_3", "amp_short_vectors/Concurrency::graphics::float_3::get_xz", "amp_short_vectors/Concurrency::graphics::float_3::get_yxz", "amp_short_vectors/Concurrency::graphics::float_3::set_xy", "amp_short_vectors/Concurrency::graphics::float_3::get_xzy", "amp_short_vectors/Concurrency::graphics::float_3::bgr", "amp_short_vectors/Concurrency::graphics::float_3::zx", "amp_short_vectors/Concurrency::graphics::float_3::gr", "amp_short_vectors/Concurrency::graphics::float_3::set_z", "amp_short_vectors/Concurrency::graphics::float_3::get_zy", "amp_short_vectors/Concurrency::graphics::float_3::gb", "amp_short_vectors/Concurrency::graphics::float_3::set_xzy", "amp_short_vectors/Concurrency::graphics::float_3::set_zx", "amp_short_vectors/Concurrency::graphics::float_3::set_yzx", "amp_short_vectors/Concurrency::graphics::float_3::operator=", "amp_short_vectors/Concurrency::graphics::float_3::x", "amp_short_vectors/Concurrency::graphics::float_3::grb", "amp_short_vectors/Concurrency::graphics::float_3::zyx", "amp_short_vectors/Concurrency::graphics::float_3::set_yxz", "amp_short_vectors/Concurrency::graphics::float_3::get_zxy", "amp_short_vectors/Concurrency::graphics::float_3::set_yz", "amp_short_vectors/Concurrency::graphics::float_3::operator--", "amp_short_vectors/Concurrency::graphics::float_3::set_xyz", "amp_short_vectors/Concurrency::graphics::float_3::operator++", "amp_short_vectors/Concurrency::graphics::float_3::z", "amp_short_vectors/Concurrency::graphics::float_3::xy", "amp_short_vectors/Concurrency::graphics::float_3::rgb", "amp_short_vectors/Concurrency::graphics::float_3::rg", "amp_short_vectors/Concurrency::graphics::float_3::yzx", "amp_short_vectors/Concurrency::graphics::float_3::set_yx", "amp_short_vectors/Concurrency::graphics::float_3::xzy", "amp_short_vectors/Concurrency::graphics::float_3::rb", "amp_short_vectors/Concurrency::graphics::float_3::get_z", "amp_short_vectors/Concurrency::graphics::float_3::br", "amp_short_vectors/Concurrency::graphics::float_3::bg", "amp_short_vectors/Concurrency::graphics::float_3::get_xyz", "amp_short_vectors/Concurrency::graphics::float_3::set_x", "amp_short_vectors/Concurrency::graphics::float_3::yxz", "amp_short_vectors/Concurrency::graphics::float_3::yz", "amp_short_vectors/Concurrency::graphics::float_3::gbr", "amp_short_vectors/Concurrency::graphics::float_3::operator*=", "amp_short_vectors/Concurrency::graphics::float_3::get_xy"] -helpviewer_keywords: ["amp_short_vectors/Concurrency::graphics::float_3"] -ms.assetid: 209df7a5-08d7-48b4-8ba5-77603642cdd8 ---- -# float_3 Class - -Represents a short vector of three floats. - -## Syntax - -```cpp -class float_3; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[float_3 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|float_3::get_x|| -|float_3::get_xy|| -|float_3::get_xyz|| -|float_3::get_xz|| -|float_3::get_xzy|| -|float_3::get_y|| -|float_3::get_yx|| -|float_3::get_yxz|| -|float_3::get_yz|| -|float_3::get_yzx|| -|float_3::get_z|| -|float_3::get_zx|| -|float_3::get_zxy|| -|float_3::get_zy|| -|float_3::get_zyx|| -|float_3::ref_b|| -|float_3::ref_g|| -|float_3::ref_r|| -|float_3::ref_x|| -|float_3::ref_y|| -|float_3::ref_z|| -|float_3::set_x|| -|float_3::set_xy|| -|float_3::set_xyz|| -|float_3::set_xz|| -|float_3::set_xzy|| -|float_3::set_y|| -|float_3::set_yx|| -|float_3::set_yxz|| -|float_3::set_yz|| -|float_3::set_yzx|| -|float_3::set_z|| -|float_3::set_zx|| -|float_3::set_zxy|| -|float_3::set_zy|| -|float_3::set_zyx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|float_3::operator-|| -|float_3::operator--|| -|float_3::operator*=|| -|float_3::operator/=|| -|float_3::operator++|| -|float_3::operator+=|| -|float_3::operator=|| -|float_3::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#float_3__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|float_3::b|| -|float_3::bg|| -|float_3::bgr|| -|float_3::br|| -|float_3::brg|| -|float_3::g|| -|float_3::gb|| -|float_3::gbr|| -|float_3::gr|| -|float_3::grb|| -|float_3::r|| -|float_3::rb|| -|float_3::rbg|| -|float_3::rg|| -|float_3::rgb|| -|float_3::x|| -|float_3::xy|| -|float_3::xyz|| -|float_3::xz|| -|float_3::xzy|| -|float_3::y|| -|float_3::yx|| -|float_3::yxz|| -|float_3::yz|| -|float_3::yzx|| -|float_3::z|| -|float_3::zx|| -|float_3::zxy|| -|float_3::zy|| -|float_3::zyx|| - -## Inheritance Hierarchy - -`float_3` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## float_3 - -Default constructor, initializes all elements with 0. - -```cpp -float_3() restrict(amp, - cpu); - -float_3( - float _V0, - float _V1, - float _V2) restrict(amp, - cpu); - -float_3( - float _V) restrict(amp, - cpu); - -float_3( - const float_3& _Other) restrict(amp, - cpu); - -explicit inline float_3( - const uint_3& _Other) restrict(amp, - cpu); - -explicit inline float_3( - const int_3& _Other) restrict(amp, - cpu); - -explicit inline float_3( - const unorm_3& _Other) restrict(amp, - cpu); - -explicit inline float_3( - const norm_3& _Other) restrict(amp, - cpu); - -explicit inline float_3( - const double_3& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 3; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/float-4-class.md b/docs/parallel/amp/reference/float-4-class.md deleted file mode 100644 index 386b6fa124a..00000000000 --- a/docs/parallel/amp/reference/float-4-class.md +++ /dev/null @@ -1,407 +0,0 @@ ---- -description: "Learn more about: float_4 Class" -title: "float_4 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::float_4::get_wyxz", "amp_short_vectors/Concurrency::graphics::float_4::zxw", "amp_short_vectors/Concurrency::graphics::float_4::bgra", "amp_short_vectors/Concurrency::graphics::float_4::get_xz", "amp_short_vectors/Concurrency::graphics::float_4::get_yxw", "amp_short_vectors/Concurrency::graphics::float_4::r", "amp_short_vectors/Concurrency::graphics::float_4::set_wzx", "amp_short_vectors/Concurrency::graphics::float_4::brga", "amp_short_vectors/Concurrency::graphics::float_4::get_xyw", "amp_short_vectors/Concurrency::graphics::float_4::gr", "amp_short_vectors/Concurrency::graphics::float_4::operator/=", "amp_short_vectors/Concurrency::graphics::float_4::agrb", "amp_short_vectors/Concurrency::graphics::float_4::set_wxz", "amp_short_vectors/Concurrency::graphics::float_4::get_wzy", "amp_short_vectors/Concurrency::graphics::float_4::rag", "amp_short_vectors/Concurrency::graphics::float_4::yzx", "amp_short_vectors/Concurrency::graphics::float_4::gbr", "amp_short_vectors/Concurrency::graphics::float_4::set_zxwy", "amp_short_vectors/Concurrency::graphics::float_4::wx", "amp_short_vectors/Concurrency::graphics::float_4::zwx", "amp_short_vectors/Concurrency::graphics::float_4::zwyx", "amp_short_vectors/Concurrency::graphics::float_4::wxy", "amp_short_vectors/Concurrency::graphics::float_4::set_wyx", "amp_short_vectors/Concurrency::graphics::float_4::set_zyx", "amp_short_vectors/Concurrency::graphics::float_4::set_yz", "amp_short_vectors/Concurrency::graphics::float_4::rbag", "amp_short_vectors/Concurrency::graphics::float_4::rb", "amp_short_vectors/Concurrency::graphics::float_4::get_zxyw", "amp_short_vectors/Concurrency::graphics::float_4::xz", "amp_short_vectors/Concurrency::graphics::float_4::get_zy", "amp_short_vectors/Concurrency::graphics::float_4::abrg", "amp_short_vectors/Concurrency::graphics::float_4::bg", "amp_short_vectors/Concurrency::graphics::float_4::xwy", "amp_short_vectors/Concurrency::graphics::float_4::get_xwz", "amp_short_vectors/Concurrency::graphics::float_4::ragb", "amp_short_vectors/Concurrency::graphics::float_4::wzx", "amp_short_vectors/Concurrency::graphics::float_4::rgba", "amp_short_vectors/Concurrency::graphics::float_4::set_zyw", "amp_short_vectors/Concurrency::graphics::float_4::get_zw", "amp_short_vectors/Concurrency::graphics::float_4::zywx", "amp_short_vectors/Concurrency::graphics::float_4::set_zwxy", "amp_short_vectors/Concurrency::graphics::float_4::set_wyzx", "amp_short_vectors/Concurrency::graphics::float_4::zyxw", "amp_short_vectors/Concurrency::graphics::float_4::yw", "amp_short_vectors/Concurrency::graphics::float_4::set_xw", "amp_short_vectors/Concurrency::graphics::float_4::gar", "amp_short_vectors/Concurrency::graphics::float_4::get_yzx", "amp_short_vectors/Concurrency::graphics::float_4::get_w", "amp_short_vectors/Concurrency::graphics::float_4::wzy", "amp_short_vectors/Concurrency::graphics::float_4::ywx", "amp_short_vectors/Concurrency::graphics::float_4::get_zx", "amp_short_vectors/Concurrency::graphics::float_4::operator=", "amp_short_vectors/Concurrency::graphics::float_4::set_wx", "amp_short_vectors/Concurrency::graphics::float_4::get_zyx", "amp_short_vectors/Concurrency::graphics::float_4::ra", "amp_short_vectors/Concurrency::graphics::float_4::zy", "amp_short_vectors/Concurrency::graphics::float_4::grab", "amp_short_vectors/Concurrency::graphics::float_4::get_xwy", "amp_short_vectors/Concurrency::graphics::float_4::get_yw", "amp_short_vectors/Concurrency::graphics::float_4::set_xyz", "amp_short_vectors/Concurrency::graphics::float_4::get_zywx", "amp_short_vectors/Concurrency::graphics::float_4::w", "amp_short_vectors/Concurrency::graphics::float_4::get_ywxz", "amp_short_vectors/Concurrency::graphics::float_4::xy", "amp_short_vectors/Concurrency::graphics::float_4::yzwx", "amp_short_vectors/Concurrency::graphics::float_4::rabg", "amp_short_vectors/Concurrency::graphics::float_4::get_ywx", "amp_short_vectors/Concurrency::graphics::float_4::get_zwyx", "amp_short_vectors/Concurrency::graphics::float_4::rbg", "amp_short_vectors/Concurrency::graphics::float_4::get_yxzw", "amp_short_vectors/Concurrency::graphics::float_4::a", "amp_short_vectors/Concurrency::graphics::float_4::ba", "amp_short_vectors/Concurrency::graphics::float_4::operator+=", "amp_short_vectors/Concurrency::graphics::float_4::brag", "amp_short_vectors/Concurrency::graphics::float_4::yxz", "amp_short_vectors/Concurrency::graphics::float_4::get_yzxw", "amp_short_vectors/Concurrency::graphics::float_4::set_xyw", "amp_short_vectors/Concurrency::graphics::float_4::set_yxwz", "amp_short_vectors/Concurrency::graphics::float_4::ab", "amp_short_vectors/Concurrency::graphics::float_4", "amp_short_vectors/Concurrency::graphics::float_4::set_wz", "amp_short_vectors/Concurrency::graphics::float_4::gabr", "amp_short_vectors/Concurrency::graphics::float_4::operator-", "amp_short_vectors/Concurrency::graphics::float_4::set_zwyx", "amp_short_vectors/Concurrency::graphics::float_4::set_zxy", "amp_short_vectors/Concurrency::graphics::float_4::set_x", "amp_short_vectors/Concurrency::graphics::float_4::get_wzxy", "amp_short_vectors/Concurrency::graphics::float_4::gbar", "amp_short_vectors/Concurrency::graphics::float_4::gb", "amp_short_vectors/Concurrency::graphics::float_4::zxwy", "amp_short_vectors/Concurrency::graphics::float_4::yxzw", "amp_short_vectors/Concurrency::graphics::float_4::get_wxz", "amp_short_vectors/Concurrency::graphics::float_4::zyx", "amp_short_vectors/Concurrency::graphics::float_4::xzyw", "amp_short_vectors/Concurrency::graphics::float_4::operator*=", "amp_short_vectors/Concurrency::graphics::float_4::yxwz", "amp_short_vectors/Concurrency::graphics::float_4::xywz", "amp_short_vectors/Concurrency::graphics::float_4::arb", "amp_short_vectors/Concurrency::graphics::float_4::get_yzw", "amp_short_vectors/Concurrency::graphics::float_4::wyxz", "amp_short_vectors/Concurrency::graphics::float_4::get_yzwx", "amp_short_vectors/Concurrency::graphics::float_4::wy", "amp_short_vectors/Concurrency::graphics::float_4::zwxy", "amp_short_vectors/Concurrency::graphics::float_4::set_wyz", "amp_short_vectors/Concurrency::graphics::float_4::set_wyxz", "amp_short_vectors/Concurrency::graphics::float_4::gab", "amp_short_vectors/Concurrency::graphics::float_4::get_xyzw", "amp_short_vectors/Concurrency::graphics::float_4::get_wyz", "amp_short_vectors/Concurrency::graphics::float_4::rbga", "amp_short_vectors/Concurrency::graphics::float_4::bagr", "amp_short_vectors/Concurrency::graphics::float_4::xyz", "amp_short_vectors/Concurrency::graphics::float_4::set_wzxy", "amp_short_vectors/Concurrency::graphics::float_4::agb", "amp_short_vectors/Concurrency::graphics::float_4::brg", "amp_short_vectors/Concurrency::graphics::float_4::zxyw", "amp_short_vectors/Concurrency::graphics::float_4::arg", "amp_short_vectors/Concurrency::graphics::float_4::g", "amp_short_vectors/Concurrency::graphics::float_4::get_zxy", "amp_short_vectors/Concurrency::graphics::float_4::set_yzxw", "amp_short_vectors/Concurrency::graphics::float_4::set_yzx", "amp_short_vectors/Concurrency::graphics::float_4::gba", "amp_short_vectors/Concurrency::graphics::float_4::ywzx", "amp_short_vectors/Concurrency::graphics::float_4::get_wx", "amp_short_vectors/Concurrency::graphics::float_4::set_z", "amp_short_vectors/Concurrency::graphics::float_4::set_xwyz", "amp_short_vectors/Concurrency::graphics::float_4::grba", "amp_short_vectors/Concurrency::graphics::float_4::yxw", "amp_short_vectors/Concurrency::graphics::float_4::set_zw", "amp_short_vectors/Concurrency::graphics::float_4::get_yx", "amp_short_vectors/Concurrency::graphics::float_4::get_zwxy", "amp_short_vectors/Concurrency::graphics::float_4::get_wz", "amp_short_vectors/Concurrency::graphics::float_4::garb", "amp_short_vectors/Concurrency::graphics::float_4::set_yxw", "amp_short_vectors/Concurrency::graphics::float_4::rba", "amp_short_vectors/Concurrency::graphics::float_4::xzwy", "amp_short_vectors/Concurrency::graphics::float_4::get_zxwy", "amp_short_vectors/Concurrency::graphics::float_4::zw", "amp_short_vectors/Concurrency::graphics::float_4::abgr", "amp_short_vectors/Concurrency::graphics::float_4::set_wxzy", "amp_short_vectors/Concurrency::graphics::float_4::wz", "amp_short_vectors/Concurrency::graphics::float_4::agbr", "amp_short_vectors/Concurrency::graphics::float_4::ar", "amp_short_vectors/Concurrency::graphics::float_4::bra", "amp_short_vectors/Concurrency::graphics::float_4::zxy", "amp_short_vectors/Concurrency::graphics::float_4::set_wy", "amp_short_vectors/Concurrency::graphics::float_4::argb", "amp_short_vectors/Concurrency::graphics::float_4::abr", "amp_short_vectors/Concurrency::graphics::float_4::get_wyzx", "amp_short_vectors/Concurrency::graphics::float_4::set_xywz", "amp_short_vectors/Concurrency::graphics::float_4::get_xwzy", "amp_short_vectors/Concurrency::graphics::float_4::b", "amp_short_vectors/Concurrency::graphics::float_4::ywz", "amp_short_vectors/Concurrency::graphics::float_4::wxz", "amp_short_vectors/Concurrency::graphics::float_4::rga", "amp_short_vectors/Concurrency::graphics::float_4::set_zx", "amp_short_vectors/Concurrency::graphics::float_4::ga", "amp_short_vectors/Concurrency::graphics::float_4::get_y", "amp_short_vectors/Concurrency::graphics::float_4::agr", "amp_short_vectors/Concurrency::graphics::float_4::wzxy", "amp_short_vectors/Concurrency::graphics::float_4::set_xzy", "amp_short_vectors/Concurrency::graphics::float_4::arbg", "amp_short_vectors/Concurrency::graphics::float_4::gbra", "amp_short_vectors/Concurrency::graphics::float_4::set_xy", "amp_short_vectors/Concurrency::graphics::float_4::yx", "amp_short_vectors/Concurrency::graphics::float_4::set_yxz", "amp_short_vectors/Concurrency::graphics::float_4::wxzy", "amp_short_vectors/Concurrency::graphics::float_4::bgr", "amp_short_vectors/Concurrency::graphics::float_4::get_wxyz", "amp_short_vectors/Concurrency::graphics::float_4::xyw", "amp_short_vectors/Concurrency::graphics::float_4::set_ywx", "amp_short_vectors/Concurrency::graphics::float_4::get_wzyx", "amp_short_vectors/Concurrency::graphics::float_4::wyx", "amp_short_vectors/Concurrency::graphics::float_4::get_xzyw", "amp_short_vectors/Concurrency::graphics::float_4::get_zwy", "amp_short_vectors/Concurrency::graphics::float_4::get_wzx", "amp_short_vectors/Concurrency::graphics::float_4::barg", "amp_short_vectors/Concurrency::graphics::float_4::get_ywzx", "amp_short_vectors/Concurrency::graphics::float_4::set_wxyz", "amp_short_vectors/Concurrency::graphics::float_4::get_wxy", "amp_short_vectors/Concurrency::graphics::float_4::set_zyxw", "amp_short_vectors/Concurrency::graphics::float_4::set_zywx", "amp_short_vectors/Concurrency::graphics::float_4::operator-=", "amp_short_vectors/Concurrency::graphics::float_4::set_y", "amp_short_vectors/Concurrency::graphics::float_4::wyzx", "amp_short_vectors/Concurrency::graphics::float_4::bgar", "amp_short_vectors/Concurrency::graphics::float_4::set_yx", "amp_short_vectors/Concurrency::graphics::float_4::set_xzyw", "amp_short_vectors/Concurrency::graphics::float_4::set_yxzw", "amp_short_vectors/Concurrency::graphics::float_4::xyzw", "amp_short_vectors/Concurrency::graphics::float_4::abg", "amp_short_vectors/Concurrency::graphics::float_4::x", "amp_short_vectors/Concurrency::graphics::float_4::gra", "amp_short_vectors/Concurrency::graphics::float_4::get_zyw", "amp_short_vectors/Concurrency::graphics::float_4::set_xz", "amp_short_vectors/Concurrency::graphics::float_4::get_xw", "amp_short_vectors/Concurrency::graphics::float_4::bag", "amp_short_vectors/Concurrency::graphics::float_4::xwz", "amp_short_vectors/Concurrency::graphics::float_4::get_xwyz", "amp_short_vectors/Concurrency::graphics::float_4::get_zxw", "amp_short_vectors/Concurrency::graphics::float_4::set_xwzy", "amp_short_vectors/Concurrency::graphics::float_4::get_wxzy", "amp_short_vectors/Concurrency::graphics::float_4::get_xzwy", "amp_short_vectors/Concurrency::graphics::float_4::get_xzw", "amp_short_vectors/Concurrency::graphics::float_4::get_xzy", "amp_short_vectors/Concurrency::graphics::float_4::set_yzw", "amp_short_vectors/Concurrency::graphics::float_4::zwy", "amp_short_vectors/Concurrency::graphics::float_4::operator--", "amp_short_vectors/Concurrency::graphics::float_4::set_xzw", "amp_short_vectors/Concurrency::graphics::float_4::get_wy", "amp_short_vectors/Concurrency::graphics::float_4::xzy", "amp_short_vectors/Concurrency::graphics::float_4::set_zy", "amp_short_vectors/Concurrency::graphics::float_4::set_xwz", "amp_short_vectors/Concurrency::graphics::float_4::set_zwx", "amp_short_vectors/Concurrency::graphics::float_4::bar", "amp_short_vectors/Concurrency::graphics::float_4::set_wzy", "amp_short_vectors/Concurrency::graphics::float_4::set_zxyw", "amp_short_vectors/Concurrency::graphics::float_4::set_wzyx", "amp_short_vectors/Concurrency::graphics::float_4::set_w", "amp_short_vectors/Concurrency::graphics::float_4::get_yxz", "amp_short_vectors/Concurrency::graphics::float_4::get_ywz", "amp_short_vectors/Concurrency::graphics::float_4::set_ywzx", "amp_short_vectors/Concurrency::graphics::float_4::get_zwx", "amp_short_vectors/Concurrency::graphics::float_4::set_zwy", "amp_short_vectors/Concurrency::graphics::float_4::set_yzwx", "amp_short_vectors/Concurrency::graphics::float_4::wyz", "amp_short_vectors/Concurrency::graphics::float_4::yzxw", "amp_short_vectors/Concurrency::graphics::float_4::yz", "amp_short_vectors/Concurrency::graphics::float_4::xw", "amp_short_vectors/Concurrency::graphics::float_4::bga", "amp_short_vectors/Concurrency::graphics::float_4::ywxz", "amp_short_vectors/Concurrency::graphics::float_4::set_wxy", "amp_short_vectors/Concurrency::graphics::float_4::get_wyx", "amp_short_vectors/Concurrency::graphics::float_4::yzw", "amp_short_vectors/Concurrency::graphics::float_4::grb", "amp_short_vectors/Concurrency::graphics::float_4::operator++", "amp_short_vectors/Concurrency::graphics::float_4::xwyz", "amp_short_vectors/Concurrency::graphics::float_4::br", "amp_short_vectors/Concurrency::graphics::float_4::set_zxw", "amp_short_vectors/Concurrency::graphics::float_4::rgab", "amp_short_vectors/Concurrency::graphics::float_4::get_xy", "amp_short_vectors/Concurrency::graphics::float_4::xzw", "amp_short_vectors/Concurrency::graphics::float_4::zyw", "amp_short_vectors/Concurrency::graphics::float_4::set_ywz", "amp_short_vectors/Concurrency::graphics::float_4::zx", "amp_short_vectors/Concurrency::graphics::float_4::wxyz", "amp_short_vectors/Concurrency::graphics::float_4::set_xzwy", "amp_short_vectors/Concurrency::graphics::float_4::rab", "amp_short_vectors/Concurrency::graphics::float_4::ag", "amp_short_vectors/Concurrency::graphics::float_4::set_xwy", "amp_short_vectors/Concurrency::graphics::float_4::get_xywz", "amp_short_vectors/Concurrency::graphics::float_4::get_xyz", "amp_short_vectors/Concurrency::graphics::float_4::y", "amp_short_vectors/Concurrency::graphics::float_4::rg", "amp_short_vectors/Concurrency::graphics::float_4::wzyx", "amp_short_vectors/Concurrency::graphics::float_4::z", "amp_short_vectors/Concurrency::graphics::float_4::set_ywxz", "amp_short_vectors/Concurrency::graphics::float_4::get_yxwz", "amp_short_vectors/Concurrency::graphics::float_4::rgb", "amp_short_vectors/Concurrency::graphics::float_4::get_zyxw", "amp_short_vectors/Concurrency::graphics::float_4::get_yz", "amp_short_vectors/Concurrency::graphics::float_4::set_yw", "amp_short_vectors/Concurrency::graphics::float_4::xwzy", "amp_short_vectors/Concurrency::graphics::float_4::get_x", "amp_short_vectors/Concurrency::graphics::float_4::get_z", "amp_short_vectors/Concurrency::graphics::float_4::set_xyzw"] -ms.assetid: 10f92170-e58c-4afc-8198-fc5778d56038 ---- -# float_4 Class - -Represents a short vector of four floats. - -## Syntax - -```cpp -class float_4; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[float_4 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|float_4::get_w|| -|float_4::get_wx|| -|float_4::get_wxy|| -|float_4::get_wxyz|| -|float_4::get_wxz|| -|float_4::get_wxzy|| -|float_4::get_wy|| -|float_4::get_wyx|| -|float_4::get_wyxz|| -|float_4::get_wyz|| -|float_4::get_wyzx|| -|float_4::get_wz|| -|float_4::get_wzx|| -|float_4::get_wzxy|| -|float_4::get_wzy|| -|float_4::get_wzyx|| -|float_4::get_x|| -|float_4::get_xw|| -|float_4::get_xwy|| -|float_4::get_xwyz|| -|float_4::get_xwz|| -|float_4::get_xwzy|| -|float_4::get_xy|| -|float_4::get_xyw|| -|float_4::get_xywz|| -|float_4::get_xyz|| -|float_4::get_xyzw|| -|float_4::get_xz|| -|float_4::get_xzw|| -|float_4::get_xzwy|| -|float_4::get_xzy|| -|float_4::get_xzyw|| -|float_4::get_y|| -|float_4::get_yw|| -|float_4::get_ywx|| -|float_4::get_ywxz|| -|float_4::get_ywz|| -|float_4::get_ywzx|| -|float_4::get_yx|| -|float_4::get_yxw|| -|float_4::get_yxwz|| -|float_4::get_yxz|| -|float_4::get_yxzw|| -|float_4::get_yz|| -|float_4::get_yzw|| -|float_4::get_yzwx|| -|float_4::get_yzx|| -|float_4::get_yzxw|| -|float_4::get_z|| -|float_4::get_zw|| -|float_4::get_zwx|| -|float_4::get_zwxy|| -|float_4::get_zwy|| -|float_4::get_zwyx|| -|float_4::get_zx|| -|float_4::get_zxw|| -|float_4::get_zxwy|| -|float_4::get_zxy|| -|float_4::get_zxyw|| -|float_4::get_zy|| -|float_4::get_zyw|| -|float_4::get_zywx|| -|float_4::get_zyx|| -|float_4::get_zyxw|| -|float_4::ref_a|| -|float_4::ref_b|| -|float_4::ref_g|| -|float_4::ref_r|| -|float_4::ref_w|| -|float_4::ref_x|| -|float_4::ref_y|| -|float_4::ref_z|| -|float_4::set_w|| -|float_4::set_wx|| -|float_4::set_wxy|| -|float_4::set_wxyz|| -|float_4::set_wxz|| -|float_4::set_wxzy|| -|float_4::set_wy|| -|float_4::set_wyx|| -|float_4::set_wyxz|| -|float_4::set_wyz|| -|float_4::set_wyzx|| -|float_4::set_wz|| -|float_4::set_wzx|| -|float_4::set_wzxy|| -|float_4::set_wzy|| -|float_4::set_wzyx|| -|float_4::set_x|| -|float_4::set_xw|| -|float_4::set_xwy|| -|float_4::set_xwyz|| -|float_4::set_xwz|| -|float_4::set_xwzy|| -|float_4::set_xy|| -|float_4::set_xyw|| -|float_4::set_xywz|| -|float_4::set_xyz|| -|float_4::set_xyzw|| -|float_4::set_xz|| -|float_4::set_xzw|| -|float_4::set_xzwy|| -|float_4::set_xzy|| -|float_4::set_xzyw|| -|float_4::set_y|| -|float_4::set_yw|| -|float_4::set_ywx|| -|float_4::set_ywxz|| -|float_4::set_ywz|| -|float_4::set_ywzx|| -|float_4::set_yx|| -|float_4::set_yxw|| -|float_4::set_yxwz|| -|float_4::set_yxz|| -|float_4::set_yxzw|| -|float_4::set_yz|| -|float_4::set_yzw|| -|float_4::set_yzwx|| -|float_4::set_yzx|| -|float_4::set_yzxw|| -|float_4::set_z|| -|float_4::set_zw|| -|float_4::set_zwx|| -|float_4::set_zwxy|| -|float_4::set_zwy|| -|float_4::set_zwyx|| -|float_4::set_zx|| -|float_4::set_zxw|| -|float_4::set_zxwy|| -|float_4::set_zxy|| -|float_4::set_zxyw|| -|float_4::set_zy|| -|float_4::set_zyw|| -|float_4::set_zywx|| -|float_4::set_zyx|| -|float_4::set_zyxw|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|float_4::operator-|| -|float_4::operator--|| -|float_4::operator*=|| -|float_4::operator/=|| -|float_4::operator++|| -|float_4::operator+=|| -|float_4::operator=|| -|float_4::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#float_4__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|float_4::a|| -|float_4::ab|| -|float_4::abg|| -|float_4::abgr|| -|float_4::abr|| -|float_4::abrg|| -|float_4::ag|| -|float_4::agb|| -|float_4::agbr|| -|float_4::agr|| -|float_4::agrb|| -|float_4::ar|| -|float_4::arb|| -|float_4::arbg|| -|float_4::arg|| -|float_4::argb|| -|float_4::b|| -|float_4::ba|| -|float_4::bag|| -|float_4::bagr|| -|float_4::bar|| -|float_4::barg|| -|float_4::bg|| -|float_4::bga|| -|float_4::bgar|| -|float_4::bgr|| -|float_4::bgra|| -|float_4::br|| -|float_4::bra|| -|float_4::brag|| -|float_4::brg|| -|float_4::brga|| -|float_4::g|| -|float_4::ga|| -|float_4::gab|| -|float_4::gabr|| -|float_4::gar|| -|float_4::garb|| -|float_4::gb|| -|float_4::gba|| -|float_4::gbar|| -|float_4::gbr|| -|float_4::gbra|| -|float_4::gr|| -|float_4::gra|| -|float_4::grab|| -|float_4::grb|| -|float_4::grba|| -|float_4::r|| -|float_4::ra|| -|float_4::rab|| -|float_4::rabg|| -|float_4::rag|| -|float_4::ragb|| -|float_4::rb|| -|float_4::rba|| -|float_4::rbag|| -|float_4::rbg|| -|float_4::rbga|| -|float_4::rg|| -|float_4::rga|| -|float_4::rgab|| -|float_4::rgb|| -|float_4::rgba|| -|float_4::w|| -|float_4::wx|| -|float_4::wxy|| -|float_4::wxyz|| -|float_4::wxz|| -|float_4::wxzy|| -|float_4::wy|| -|float_4::wyx|| -|float_4::wyxz|| -|float_4::wyz|| -|float_4::wyzx|| -|float_4::wz|| -|float_4::wzx|| -|float_4::wzxy|| -|float_4::wzy|| -|float_4::wzyx|| -|float_4::x|| -|float_4::xw|| -|float_4::xwy|| -|float_4::xwyz|| -|float_4::xwz|| -|float_4::xwzy|| -|float_4::xy|| -|float_4::xyw|| -|float_4::xywz|| -|float_4::xyz|| -|float_4::xyzw|| -|float_4::xz|| -|float_4::xzw|| -|float_4::xzwy|| -|float_4::xzy|| -|float_4::xzyw|| -|float_4::y|| -|float_4::yw|| -|float_4::ywx|| -|float_4::ywxz|| -|float_4::ywz|| -|float_4::ywzx|| -|float_4::yx|| -|float_4::yxw|| -|float_4::yxwz|| -|float_4::yxz|| -|float_4::yxzw|| -|float_4::yz|| -|float_4::yzw|| -|float_4::yzwx|| -|float_4::yzx|| -|float_4::yzxw|| -|float_4::z|| -|float_4::zw|| -|float_4::zwx|| -|float_4::zwxy|| -|float_4::zwy|| -|float_4::zwyx|| -|float_4::zx|| -|float_4::zxw|| -|float_4::zxwy|| -|float_4::zxy|| -|float_4::zxyw|| -|float_4::zy|| -|float_4::zyw|| -|float_4::zywx|| -|float_4::zyx|| -|float_4::zyxw|| - -## Inheritance Hierarchy - -`float_4` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## float_4 - -Default constructor, initializes all elements with 0. - -```cpp -float_4() restrict(amp, - cpu); - -float_4( - float _V0, - float _V1, - float _V2, - float _V3) restrict(amp, - cpu); - -float_4( - float _V) restrict(amp, - cpu); - -float_4( - const float_4& _Other) restrict(amp, - cpu); - -explicit inline float_4( - const uint_4& _Other) restrict(amp, - cpu); - -explicit inline float_4( - const int_4& _Other) restrict(amp, - cpu); - -explicit inline float_4( - const unorm_4& _Other) restrict(amp, - cpu); - -explicit inline float_4( - const norm_4& _Other) restrict(amp, - cpu); - -explicit inline float_4( - const double_4& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V3*
-The value to initialize element 3. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 4; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/index-class.md b/docs/parallel/amp/reference/index-class.md deleted file mode 100644 index 7e4fe7573d1..00000000000 --- a/docs/parallel/amp/reference/index-class.md +++ /dev/null @@ -1,311 +0,0 @@ ---- -description: "Learn more about: index Class" -title: "index Class" -ms.date: 06/21/2022 -f1_keywords: ["AMP/index", "AMP/Concurrency::index::index", "AMP/Concurrency::index::rank"] -helpviewer_keywords: ["index structure"] -ms.assetid: cbe79b08-0ba7-474c-9828-f1a71da39eb3 -ms.custom: devdivchpfy22 ---- - -# index Class - -Defines an *N*-dimensional index vector. - -## Syntax - -```cpp -template -class index; -``` - -### Parameters - -*_Rank*
-The rank, or number of dimensions. - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[index Constructor](#index_ctor)|Initializes a new instance of the `index` class.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator--](#operator--)|Decrements each element of the `index` object.| -|[operator%=](#operator_mod_eq)|Calculates the modulus (remainder) of each element in the `index` object when that element is divided by a number.| -|[operator*=](#operator_star_eq)|Multiplies each element of the `index` object by a number.| -|[operator/=](#operator_div_eq)|Divides each element of the `index` object by a number.| -|[index::operator\[\]](#operator_at)|Returns the element that's at the specified index.| -|[operator++](#operator_add_add)|Increments each element of the `index` object.| -|[operator+=](#operator_add_eq)|Adds the specified number to each element of the `index` object.| -|[operator=](#operator_eq)|Copies the contents of the specified `index` object into this one.| -|[operator-=](#operator_-_eq)|Subtracts the specified number from each element of the `index` object.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[rank Constant](#rank)|Stores the rank of the `index` object.| - -## Inheritance Hierarchy - -`index` - -## Remarks - -The `index` structure represents a coordinate vector of *N* integers that specifies a unique position in an *N*-dimensional space. The values in the vector are ordered from most significant to least significant. You can retrieve the values of the components using [operator=](#operator_eq). - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## index Constructor - -Initializes a new instance of the index class. - -```cpp -index() restrict(amp,cpu); - -index( - const index<_Rank>& _Other -) restrict(amp,cpu); - -explicit index( - int _I -) restrict(amp,cpu); - -index( - int _I0, - int _I1 -) restrict(amp,cpu); - -index( - int _I0, - int _I1, - int _I2 -) restrict(amp,cpu); - -explicit index( - const int _Array[_Rank] -) restrict(amp,cpu); -``` - -### Parameters - -*_Array*
-A one-dimensional array with the rank values. - -*_I*
-The index location in a one-dimensional index. - -*_I0*
-The length of the most significant dimension. - -*_I1*
-The length of the next-to-most-significant dimension. - -*_I2*
-The length of the least significant dimension. - -*_Other*
-An index object on which the new index object is based. - -## operator-- - -Decrements each element of the index object. - -```cpp -index<_Rank>& operator--() restrict(amp,cpu); - -index operator--( - int -) restrict(amp,cpu); -``` - -### Return values - -For the prefix operator, the index object (`*this`). For the suffix operator, a new index object. - -## operator%= - -Calculates the modulus (remainder) of each element in the index object when that element is divided by the specified number. - -```cpp -index<_Rank>& operator%=( - int _Rhs -) restrict(cpu, amp); -``` - -### Parameters - -*_Rhs*
-The number to divide by to find the modulus. - -## Return Value - -The index object. - -## operator*= - -Multiplies each element in the index object by the specified number. - -```cpp -index<_Rank>& operator*=( - int _Rhs -) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number to multiply. - -## operator/= - -Divides each element in the index object by the specified number. - -```cpp -index<_Rank>& operator/=( - int _Rhs -) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number to divide by. - -## operator\[\] - -Returns the component of the index at the specified location. - -```cpp -int operator[] ( - unsigned _Index -) const restrict(amp,cpu); - -int& operator[] ( - unsigned _Index -) restrict(amp,cpu); -``` - -### Parameters - -*_Index*
-An integer from 0 through the rank minus 1. - -### Return Value - -The element that's at the specified index. - -### Remarks - -This following example displays the component values of the index. - -```cpp -// Prints 1 2 3. -concurrency::index<3> idx(1, 2, 3); -std::cout << idx[0] << "\n"; -std::cout << idx[1] << "\n"; -std::cout << idx[2] << "\n"; -``` - -## operator++ - -Increments each element of the index object. - -```cpp -index<_Rank>& operator++() restrict(amp,cpu); - -index<_Rank> operator++( - int -) restrict(amp,cpu); -``` - -### Return Value - -For the prefix operator, the index object (`*this`). For the suffix operator, a new index object. - -## operator+= - -Adds the specified number to each element of the index object. - -```cpp -index<_Rank>& operator+=( - const index<_Rank>& _Rhs -) restrict(amp,cpu); - -index<_Rank>& operator+=( - int _Rhs -) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number to add. - -### Return Value - -The index object. - -## operator= - -Copies the contents of the specified index object into this one. - -```cpp -index<_Rank>& operator=( - const index<_Rank>& _Other -) restrict(amp,cpu); -``` - -### Parameters - -*_Other*
-The index object to copy from. - -### Return Value - -A reference to this index object. - -## operator-= - -Subtracts the specified number from each element of the index object. - -```cpp -index<_Rank>& operator-=( - const index<_Rank>& _Rhs -) restrict(amp,cpu); - -index<_Rank>& operator-=( - int _Rhs -) restrict(amp,cpu); -``` - -### Parameters - -*_Rhs*
-The number to subtract. - -### Return Value - -The index object. - -## Rank - -Gets the rank of the index object. - -```cpp -static const int rank = _Rank; -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/int-2-class.md b/docs/parallel/amp/reference/int-2-class.md deleted file mode 100644 index 6b5e99b2225..00000000000 --- a/docs/parallel/amp/reference/int-2-class.md +++ /dev/null @@ -1,162 +0,0 @@ ---- -description: "Learn more about: int_2 Class" -title: "int_2 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::int_2::y", "amp_short_vectors/Concurrency::graphics::int_2::set_x", "amp_short_vectors/Concurrency::graphics::int_2::set_y", "amp_short_vectors/Concurrency::graphics::int_2::get_yx", "amp_short_vectors/Concurrency::graphics::int_2::operator++", "amp_short_vectors/Concurrency::graphics::int_2::x", "amp_short_vectors/Concurrency::graphics::int_2::set_yx", "amp_short_vectors/Concurrency::graphics::int_2::operator/=", "amp_short_vectors/Concurrency::graphics::int_2::get_y", "amp_short_vectors/Concurrency::graphics::int_2::gr", "amp_short_vectors/Concurrency::graphics::int_2::operator*=", "amp_short_vectors/Concurrency::graphics::int_2::r", "amp_short_vectors/Concurrency::graphics::int_2::get_xy", "amp_short_vectors/Concurrency::graphics::int_2::operator=", "amp_short_vectors/Concurrency::graphics::int_2::g", "amp_short_vectors/Concurrency::graphics::int_2::rg", "amp_short_vectors/Concurrency::graphics::int_2::xy", "amp_short_vectors/Concurrency::graphics::int_2::operator-=", "amp_short_vectors/Concurrency::graphics::int_2::get_x", "amp_short_vectors/Concurrency::graphics::int_2::yx", "amp_short_vectors/Concurrency::graphics::int_2", "amp_short_vectors/Concurrency::graphics::int_2::operator-", "amp_short_vectors/Concurrency::graphics::int_2::set_xy", "amp_short_vectors/Concurrency::graphics::int_2::operator+=", "amp_short_vectors/Concurrency::graphics::int_2::operator--"] -ms.assetid: 258b02e9-f1ee-46c2-8edd-dc9f69184846 ---- -# int_2 Class - -Represents a short vector of two integers. - -## Syntax - -```cpp -class int_2; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[int_2 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|int_2::get_x|| -|int_2::get_xy|| -|int_2::get_y|| -|int_2::get_yx|| -|int_2::ref_g|| -|int_2::ref_r|| -|int_2::ref_x|| -|int_2::ref_y|| -|int_2::set_x|| -|int_2::set_xy|| -|int_2::set_y|| -|int_2::set_yx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|int_2::operator-|| -|int_2::operator--|| -|int_2::operator%=|| -|int_2::operator&=|| -|int_2::operator*=|| -|int_2::operator/=|| -|int_2::operator^=|| -|int_2::operator\|=|| -|int_2::operator~|| -|int_2::operator++|| -|int_2::operator+=|| -|int_2::operator<\<=|| -|int_2::operator=|| -|int_2::operator-=|| -|int_2::operator>>=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#int_2__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|int_2::g|| -|int_2::gr|| -|int_2::r|| -|int_2::rg|| -|int_2::x|| -|int_2::xy|| -|int_2::y|| -|int_2::yx|| - -## Inheritance Hierarchy - -`int_2` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## int_2 - -Default constructor, initializes all elements with 0. - -```cpp -int_2() restrict(amp, - cpu); - -int_2( - int _V0, - int _V1) restrict(amp, - cpu); - -int_2( - int _V) restrict(amp, - cpu); - -int_2( - const int_2& _Other) restrict(amp, - cpu); - -explicit inline int_2( - const uint_2& _Other) restrict(amp, - cpu); - -explicit inline int_2( - const float_2& _Other) restrict(amp, - cpu); - -explicit inline int_2( - const unorm_2& _Other) restrict(amp, - cpu); - -explicit inline int_2( - const norm_2& _Other) restrict(amp, - cpu); - -explicit inline int_2( - const double_2& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 2; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/int-3-class.md b/docs/parallel/amp/reference/int-3-class.md deleted file mode 100644 index 460a6983ff9..00000000000 --- a/docs/parallel/amp/reference/int-3-class.md +++ /dev/null @@ -1,207 +0,0 @@ ---- -description: "Learn more about: int_3 Class" -title: "int_3 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::int_3::get_x", "amp_short_vectors/Concurrency::graphics::int_3::operator-=", "amp_short_vectors/Concurrency::graphics::int_3::get_y", "amp_short_vectors/Concurrency::graphics::int_3::operator=", "amp_short_vectors/Concurrency::graphics::int_3::operator++", "amp_short_vectors/Concurrency::graphics::int_3::zyx", "amp_short_vectors/Concurrency::graphics::int_3::get_z", "amp_short_vectors/Concurrency::graphics::int_3::operator*=", "amp_short_vectors/Concurrency::graphics::int_3::grb", "amp_short_vectors/Concurrency::graphics::int_3::get_xz", "amp_short_vectors/Concurrency::graphics::int_3::br", "amp_short_vectors/Concurrency::graphics::int_3::operator--", "amp_short_vectors/Concurrency::graphics::int_3", "amp_short_vectors/Concurrency::graphics::int_3::set_yx", "amp_short_vectors/Concurrency::graphics::int_3::x", "amp_short_vectors/Concurrency::graphics::int_3::yxz", "amp_short_vectors/Concurrency::graphics::int_3::set_y", "amp_short_vectors/Concurrency::graphics::int_3::zy", "amp_short_vectors/Concurrency::graphics::int_3::z", "amp_short_vectors/Concurrency::graphics::int_3::get_zx", "amp_short_vectors/Concurrency::graphics::int_3::rb", "amp_short_vectors/Concurrency::graphics::int_3::yzx", "amp_short_vectors/Concurrency::graphics::int_3::gb", "amp_short_vectors/Concurrency::graphics::int_3::set_zxy", "amp_short_vectors/Concurrency::graphics::int_3::xy", "amp_short_vectors/Concurrency::graphics::int_3::set_zx", "amp_short_vectors/Concurrency::graphics::int_3::g", "amp_short_vectors/Concurrency::graphics::int_3::operator/=", "amp_short_vectors/Concurrency::graphics::int_3::get_zy", "amp_short_vectors/Concurrency::graphics::int_3::yx", "amp_short_vectors/Concurrency::graphics::int_3::xzy", "amp_short_vectors/Concurrency::graphics::int_3::set_x", "amp_short_vectors/Concurrency::graphics::int_3::set_xz", "amp_short_vectors/Concurrency::graphics::int_3::get_yzx", "amp_short_vectors/Concurrency::graphics::int_3::b", "amp_short_vectors/Concurrency::graphics::int_3::gbr", "amp_short_vectors/Concurrency::graphics::int_3::operator+=", "amp_short_vectors/Concurrency::graphics::int_3::gr", "amp_short_vectors/Concurrency::graphics::int_3::brg", "amp_short_vectors/Concurrency::graphics::int_3::bg", "amp_short_vectors/Concurrency::graphics::int_3::zx", "amp_short_vectors/Concurrency::graphics::int_3::get_xyz", "amp_short_vectors/Concurrency::graphics::int_3::set_zyx", "amp_short_vectors/Concurrency::graphics::int_3::set_yzx", "amp_short_vectors/Concurrency::graphics::int_3::y", "amp_short_vectors/Concurrency::graphics::int_3::set_z", "amp_short_vectors/Concurrency::graphics::int_3::r", "amp_short_vectors/Concurrency::graphics::int_3::set_xzy", "amp_short_vectors/Concurrency::graphics::int_3::rg", "amp_short_vectors/Concurrency::graphics::int_3::xyz", "amp_short_vectors/Concurrency::graphics::int_3::get_yz", "amp_short_vectors/Concurrency::graphics::int_3::operator-", "amp_short_vectors/Concurrency::graphics::int_3::set_xy", "amp_short_vectors/Concurrency::graphics::int_3::zxy", "amp_short_vectors/Concurrency::graphics::int_3::yz", "amp_short_vectors/Concurrency::graphics::int_3::set_zy", "amp_short_vectors/Concurrency::graphics::int_3::bgr", "amp_short_vectors/Concurrency::graphics::int_3::get_xzy", "amp_short_vectors/Concurrency::graphics::int_3::get_yx", "amp_short_vectors/Concurrency::graphics::int_3::rbg", "amp_short_vectors/Concurrency::graphics::int_3::get_zxy", "amp_short_vectors/Concurrency::graphics::int_3::set_yxz", "amp_short_vectors/Concurrency::graphics::int_3::rgb", "amp_short_vectors/Concurrency::graphics::int_3::get_xy", "amp_short_vectors/Concurrency::graphics::int_3::set_xyz", "amp_short_vectors/Concurrency::graphics::int_3::get_yxz", "amp_short_vectors/Concurrency::graphics::int_3::get_zyx", "amp_short_vectors/Concurrency::graphics::int_3::xz", "amp_short_vectors/Concurrency::graphics::int_3::set_yz"] -ms.assetid: d4af182f-30f1-455c-b16d-aa99cd314038 ---- -# int_3 Class - -Represents a short vector of three integers. - -## Syntax - -```cpp -class int_3; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[int_3 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|int_3::get_x|| -|int_3::get_xy|| -|int_3::get_xyz|| -|int_3::get_xz|| -|int_3::get_xzy|| -|int_3::get_y|| -|int_3::get_yx|| -|int_3::get_yxz|| -|int_3::get_yz|| -|int_3::get_yzx|| -|int_3::get_z|| -|int_3::get_zx|| -|int_3::get_zxy|| -|int_3::get_zy|| -|int_3::get_zyx|| -|int_3::ref_b|| -|int_3::ref_g|| -|int_3::ref_r|| -|int_3::ref_x|| -|int_3::ref_y|| -|int_3::ref_z|| -|int_3::set_x|| -|int_3::set_xy|| -|int_3::set_xyz|| -|int_3::set_xz|| -|int_3::set_xzy|| -|int_3::set_y|| -|int_3::set_yx|| -|int_3::set_yxz|| -|int_3::set_yz|| -|int_3::set_yzx|| -|int_3::set_z|| -|int_3::set_zx|| -|int_3::set_zxy|| -|int_3::set_zy|| -|int_3::set_zyx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|int_3::operator-|| -|int_3::operator--|| -|int_3::operator%=|| -|int_3::operator&=|| -|int_3::operator*=|| -|int_3::operator/=|| -|int_3::operator^=|| -|int_3::operator\|=|| -|int_3::operator~|| -|int_3::operator++|| -|int_3::operator+=|| -|int_3::operator<\<=|| -|int_3::operator=|| -|int_3::operator-=|| -|int_3::operator>>=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|int_3::b|| -|int_3::bg|| -|int_3::bgr|| -|int_3::br|| -|int_3::brg|| -|int_3::g|| -|int_3::gb|| -|int_3::gbr|| -|int_3::gr|| -|int_3::grb|| -|int_3::r|| -|int_3::rb|| -|int_3::rbg|| -|int_3::rg|| -|int_3::rgb|| -|int_3::x|| -|int_3::xy|| -|int_3::xyz|| -|int_3::xz|| -|int_3::xzy|| -|int_3::y|| -|int_3::yx|| -|int_3::yxz|| -|int_3::yz|| -|int_3::yzx|| -|int_3::z|| -|int_3::zx|| -|int_3::zxy|| -|int_3::zy|| -|int_3::zyx|| - -## Inheritance Hierarchy - -`int_3` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## int_3 - -Default constructor, initializes all elements with 0. - -### Syntax - -```cpp -int_3() restrict(amp,cpu); -int_3( - int _V0, - int _V1, - int _V2 -) restrict(amp,cpu); -int_3( - int _V -) restrict(amp,cpu); -int_3( - const int_3& _Other -) restrict(amp,cpu); -explicit inline int_3( - const uint_3& _Other -) restrict(amp,cpu); -explicit inline int_3( - const float_3& _Other -) restrict(amp,cpu); -explicit inline int_3( - const unorm_3& _Other -) restrict(amp,cpu); -explicit inline int_3( - const norm_3& _Other -) restrict(amp,cpu); -explicit inline int_3( - const double_3& _Other -) restrict(amp,cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -### Syntax - -```cpp -static const int size = 3; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/int-4-class.md b/docs/parallel/amp/reference/int-4-class.md deleted file mode 100644 index ad9e159065f..00000000000 --- a/docs/parallel/amp/reference/int-4-class.md +++ /dev/null @@ -1,414 +0,0 @@ ---- -description: "Learn more about: int_4 Class" -title: "int_4 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::int_4::get_ywxz", "amp_short_vectors/Concurrency::graphics::int_4::xzyw", "amp_short_vectors/Concurrency::graphics::int_4::get_x", "amp_short_vectors/Concurrency::graphics::int_4::agr", "amp_short_vectors/Concurrency::graphics::int_4::set_ywxz", "amp_short_vectors/Concurrency::graphics::int_4::set_yzxw", "amp_short_vectors/Concurrency::graphics::int_4::get_zyw", "amp_short_vectors/Concurrency::graphics::int_4::set_zwyx", "amp_short_vectors/Concurrency::graphics::int_4::abgr", "amp_short_vectors/Concurrency::graphics::int_4::get_wzxy", "amp_short_vectors/Concurrency::graphics::int_4::get_wyxz", "amp_short_vectors/Concurrency::graphics::int_4::zyxw", "amp_short_vectors/Concurrency::graphics::int_4::rgb", "amp_short_vectors/Concurrency::graphics::int_4::wyxz", "amp_short_vectors/Concurrency::graphics::int_4::get_xwz", "amp_short_vectors/Concurrency::graphics::int_4::set_wyz", "amp_short_vectors/Concurrency::graphics::int_4::set_xz", "amp_short_vectors/Concurrency::graphics::int_4::gabr", "amp_short_vectors/Concurrency::graphics::int_4::gbr", "amp_short_vectors/Concurrency::graphics::int_4::set_wx", "amp_short_vectors/Concurrency::graphics::int_4::yxw", "amp_short_vectors/Concurrency::graphics::int_4::get_ywx", "amp_short_vectors/Concurrency::graphics::int_4::set_wxzy", "amp_short_vectors/Concurrency::graphics::int_4::get_yzx", "amp_short_vectors/Concurrency::graphics::int_4::yz", "amp_short_vectors/Concurrency::graphics::int_4::rg", "amp_short_vectors/Concurrency::graphics::int_4::rba", "amp_short_vectors/Concurrency::graphics::int_4::operator/=", "amp_short_vectors/Concurrency::graphics::int_4::get_wxy", "amp_short_vectors/Concurrency::graphics::int_4::set_yx", "amp_short_vectors/Concurrency::graphics::int_4::get_ywz", "amp_short_vectors/Concurrency::graphics::int_4::abg", "amp_short_vectors/Concurrency::graphics::int_4::get_y", "amp_short_vectors/Concurrency::graphics::int_4::ra", "amp_short_vectors/Concurrency::graphics::int_4::wxzy", "amp_short_vectors/Concurrency::graphics::int_4::rabg", "amp_short_vectors/Concurrency::graphics::int_4::ag", "amp_short_vectors/Concurrency::graphics::int_4::xwyz", "amp_short_vectors/Concurrency::graphics::int_4::zxy", "amp_short_vectors/Concurrency::graphics::int_4::x", "amp_short_vectors/Concurrency::graphics::int_4::bag", "amp_short_vectors/Concurrency::graphics::int_4::grb", "amp_short_vectors/Concurrency::graphics::int_4::xwz", "amp_short_vectors/Concurrency::graphics::int_4::get_wzx", "amp_short_vectors/Concurrency::graphics::int_4::operator*=", "amp_short_vectors/Concurrency::graphics::int_4::r", "amp_short_vectors/Concurrency::graphics::int_4::get_xzwy", "amp_short_vectors/Concurrency::graphics::int_4::bgra", "amp_short_vectors/Concurrency::graphics::int_4::xyzw", "amp_short_vectors/Concurrency::graphics::int_4::ab", "amp_short_vectors/Concurrency::graphics::int_4::set_xwyz", "amp_short_vectors/Concurrency::graphics::int_4::brg", "amp_short_vectors/Concurrency::graphics::int_4::garb", "amp_short_vectors/Concurrency::graphics::int_4::set_xzw", "amp_short_vectors/Concurrency::graphics::int_4::set_ywz", "amp_short_vectors/Concurrency::graphics::int_4::xywz", "amp_short_vectors/Concurrency::graphics::int_4::get_w", "amp_short_vectors/Concurrency::graphics::int_4::wzy", "amp_short_vectors/Concurrency::graphics::int_4::zwy", "amp_short_vectors/Concurrency::graphics::int_4::arb", "amp_short_vectors/Concurrency::graphics::int_4::agbr", "amp_short_vectors/Concurrency::graphics::int_4::get_yw", "amp_short_vectors/Concurrency::graphics::int_4::gra", "amp_short_vectors/Concurrency::graphics::int_4::get_yx", "amp_short_vectors/Concurrency::graphics::int_4::get_zyx", "amp_short_vectors/Concurrency::graphics::int_4::rag", "amp_short_vectors/Concurrency::graphics::int_4::b", "amp_short_vectors/Concurrency::graphics::int_4::rbag", "amp_short_vectors/Concurrency::graphics::int_4::set_zyw", "amp_short_vectors/Concurrency::graphics::int_4::grab", "amp_short_vectors/Concurrency::graphics::int_4::xzy", "amp_short_vectors/Concurrency::graphics::int_4::get_xwzy", "amp_short_vectors/Concurrency::graphics::int_4::wxy", "amp_short_vectors/Concurrency::graphics::int_4::abr", "amp_short_vectors/Concurrency::graphics::int_4::yw", "amp_short_vectors/Concurrency::graphics::int_4::set_zxyw", "amp_short_vectors/Concurrency::graphics::int_4::get_xyzw", "amp_short_vectors/Concurrency::graphics::int_4::set_wxz", "amp_short_vectors/Concurrency::graphics::int_4::get_yxwz", "amp_short_vectors/Concurrency::graphics::int_4::bar", "amp_short_vectors/Concurrency::graphics::int_4::zwxy", "amp_short_vectors/Concurrency::graphics::int_4::operator+=", "amp_short_vectors/Concurrency::graphics::int_4::get_zwy", "amp_short_vectors/Concurrency::graphics::int_4::get_xwyz", "amp_short_vectors/Concurrency::graphics::int_4::zxwy", "amp_short_vectors/Concurrency::graphics::int_4::barg", "amp_short_vectors/Concurrency::graphics::int_4::set_yxwz", "amp_short_vectors/Concurrency::graphics::int_4::operator=", "amp_short_vectors/Concurrency::graphics::int_4::get_xz", "amp_short_vectors/Concurrency::graphics::int_4::wz", "amp_short_vectors/Concurrency::graphics::int_4::w", "amp_short_vectors/Concurrency::graphics::int_4::set_zwy", "amp_short_vectors/Concurrency::graphics::int_4::yzx", "amp_short_vectors/Concurrency::graphics::int_4::set_xwzy", "amp_short_vectors/Concurrency::graphics::int_4::set_wzxy", "amp_short_vectors/Concurrency::graphics::int_4::get_yxz", "amp_short_vectors/Concurrency::graphics::int_4::set_ywx", "amp_short_vectors/Concurrency::graphics::int_4::get_zyxw", "amp_short_vectors/Concurrency::graphics::int_4::ragb", "amp_short_vectors/Concurrency::graphics::int_4::xzwy", "amp_short_vectors/Concurrency::graphics::int_4::get_wx", "amp_short_vectors/Concurrency::graphics::int_4::arbg", "amp_short_vectors/Concurrency::graphics::int_4::set_zxw", "amp_short_vectors/Concurrency::graphics::int_4::get_wyx", "amp_short_vectors/Concurrency::graphics::int_4::gab", "amp_short_vectors/Concurrency::graphics::int_4::agrb", "amp_short_vectors/Concurrency::graphics::int_4::bagr", "amp_short_vectors/Concurrency::graphics::int_4::get_wzyx", "amp_short_vectors/Concurrency::graphics::int_4::operator-=", "amp_short_vectors/Concurrency::graphics::int_4::get_wxz", "amp_short_vectors/Concurrency::graphics::int_4::get_xzw", "amp_short_vectors/Concurrency::graphics::int_4::gar", "amp_short_vectors/Concurrency::graphics::int_4::zw", "amp_short_vectors/Concurrency::graphics::int_4::yxzw", "amp_short_vectors/Concurrency::graphics::int_4::get_yxw", "amp_short_vectors/Concurrency::graphics::int_4::get_yxzw", "amp_short_vectors/Concurrency::graphics::int_4::operator++", "amp_short_vectors/Concurrency::graphics::int_4::xzw", "amp_short_vectors/Concurrency::graphics::int_4::arg", "amp_short_vectors/Concurrency::graphics::int_4::get_zwyx", "amp_short_vectors/Concurrency::graphics::int_4::g", "amp_short_vectors/Concurrency::graphics::int_4::set_zywx", "amp_short_vectors/Concurrency::graphics::int_4::z", "amp_short_vectors/Concurrency::graphics::int_4::get_z", "amp_short_vectors/Concurrency::graphics::int_4::get_zwxy", "amp_short_vectors/Concurrency::graphics::int_4::set_zyx", "amp_short_vectors/Concurrency::graphics::int_4", "amp_short_vectors/Concurrency::graphics::int_4::set_wy", "amp_short_vectors/Concurrency::graphics::int_4::bgr", "amp_short_vectors/Concurrency::graphics::int_4::xwy", "amp_short_vectors/Concurrency::graphics::int_4::xz", "amp_short_vectors/Concurrency::graphics::int_4::get_zwx", "amp_short_vectors/Concurrency::graphics::int_4::set_z", "amp_short_vectors/Concurrency::graphics::int_4::ywz", "amp_short_vectors/Concurrency::graphics::int_4::set_yz", "amp_short_vectors/Concurrency::graphics::int_4::wyx", "amp_short_vectors/Concurrency::graphics::int_4::get_yzwx", "amp_short_vectors/Concurrency::graphics::int_4::grba", "amp_short_vectors/Concurrency::graphics::int_4::bra", "amp_short_vectors/Concurrency::graphics::int_4::set_zxy", "amp_short_vectors/Concurrency::graphics::int_4::set_xzyw", "amp_short_vectors/Concurrency::graphics::int_4::get_zx", "amp_short_vectors/Concurrency::graphics::int_4::xyz", "amp_short_vectors/Concurrency::graphics::int_4::operator--", "amp_short_vectors/Concurrency::graphics::int_4::y", "amp_short_vectors/Concurrency::graphics::int_4::yzwx", "amp_short_vectors/Concurrency::graphics::int_4::agb", "amp_short_vectors/Concurrency::graphics::int_4::set_wyxz", "amp_short_vectors/Concurrency::graphics::int_4::set_xyzw", "amp_short_vectors/Concurrency::graphics::int_4::wzyx", "amp_short_vectors/Concurrency::graphics::int_4::rgab", "amp_short_vectors/Concurrency::graphics::int_4::set_wzy", "amp_short_vectors/Concurrency::graphics::int_4::set_wxyz", "amp_short_vectors/Concurrency::graphics::int_4::set_wyzx", "amp_short_vectors/Concurrency::graphics::int_4::wyzx", "amp_short_vectors/Concurrency::graphics::int_4::set_ywzx", "amp_short_vectors/Concurrency::graphics::int_4::zyw", "amp_short_vectors/Concurrency::graphics::int_4::get_xyw", "amp_short_vectors/Concurrency::graphics::int_4::ywxz", "amp_short_vectors/Concurrency::graphics::int_4::brag", "amp_short_vectors/Concurrency::graphics::int_4::get_yzw", "amp_short_vectors/Concurrency::graphics::int_4::get_xzy", "amp_short_vectors/Concurrency::graphics::int_4::get_xw", "amp_short_vectors/Concurrency::graphics::int_4::xw", "amp_short_vectors/Concurrency::graphics::int_4::gbra", "amp_short_vectors/Concurrency::graphics::int_4::set_wxy", "amp_short_vectors/Concurrency::graphics::int_4::get_xyz", "amp_short_vectors/Concurrency::graphics::int_4::get_zxyw", "amp_short_vectors/Concurrency::graphics::int_4::zwx", "amp_short_vectors/Concurrency::graphics::int_4::get_xzyw", "amp_short_vectors/Concurrency::graphics::int_4::set_xzwy", "amp_short_vectors/Concurrency::graphics::int_4::set_yxw", "amp_short_vectors/Concurrency::graphics::int_4::get_xy", "amp_short_vectors/Concurrency::graphics::int_4::get_wz", "amp_short_vectors/Concurrency::graphics::int_4::set_yw", "amp_short_vectors/Concurrency::graphics::int_4::rbga", "amp_short_vectors/Concurrency::graphics::int_4::ywzx", "amp_short_vectors/Concurrency::graphics::int_4::get_wxyz", "amp_short_vectors/Concurrency::graphics::int_4::ba", "amp_short_vectors/Concurrency::graphics::int_4::gba", "amp_short_vectors/Concurrency::graphics::int_4::set_zw", "amp_short_vectors/Concurrency::graphics::int_4::set_x", "amp_short_vectors/Concurrency::graphics::int_4::set_xwy", "amp_short_vectors/Concurrency::graphics::int_4::get_zxy", "amp_short_vectors/Concurrency::graphics::int_4::set_xwz", "amp_short_vectors/Concurrency::graphics::int_4::wyz", "amp_short_vectors/Concurrency::graphics::int_4::set_y", "amp_short_vectors/Concurrency::graphics::int_4::get_wyzx", "amp_short_vectors/Concurrency::graphics::int_4::set_zyxw", "amp_short_vectors/Concurrency::graphics::int_4::rgba", "amp_short_vectors/Concurrency::graphics::int_4::gr", "amp_short_vectors/Concurrency::graphics::int_4::set_yzx", "amp_short_vectors/Concurrency::graphics::int_4::set_xyz", "amp_short_vectors/Concurrency::graphics::int_4::get_xwy", "amp_short_vectors/Concurrency::graphics::int_4::get_wxzy", "amp_short_vectors/Concurrency::graphics::int_4::set_xzy", "amp_short_vectors/Concurrency::graphics::int_4::set_xy", "amp_short_vectors/Concurrency::graphics::int_4::rbg", "amp_short_vectors/Concurrency::graphics::int_4::br", "amp_short_vectors/Concurrency::graphics::int_4::get_yzxw", "amp_short_vectors/Concurrency::graphics::int_4::rab", "amp_short_vectors/Concurrency::graphics::int_4::set_xw", "amp_short_vectors/Concurrency::graphics::int_4::ga", "amp_short_vectors/Concurrency::graphics::int_4::wxyz", "amp_short_vectors/Concurrency::graphics::int_4::set_wzyx", "amp_short_vectors/Concurrency::graphics::int_4::zywx", "amp_short_vectors/Concurrency::graphics::int_4::xyw", "amp_short_vectors/Concurrency::graphics::int_4::bgar", "amp_short_vectors/Concurrency::graphics::int_4::xy", "amp_short_vectors/Concurrency::graphics::int_4::zxw", "amp_short_vectors/Concurrency::graphics::int_4::get_xywz", "amp_short_vectors/Concurrency::graphics::int_4::wy", "amp_short_vectors/Concurrency::graphics::int_4::zyx", "amp_short_vectors/Concurrency::graphics::int_4::get_zw", "amp_short_vectors/Concurrency::graphics::int_4::bga", "amp_short_vectors/Concurrency::graphics::int_4::set_zx", "amp_short_vectors/Concurrency::graphics::int_4::get_zywx", "amp_short_vectors/Concurrency::graphics::int_4::yzw", "amp_short_vectors/Concurrency::graphics::int_4::set_yzw", "amp_short_vectors/Concurrency::graphics::int_4::rb", "amp_short_vectors/Concurrency::graphics::int_4::set_w", "amp_short_vectors/Concurrency::graphics::int_4::get_wy", "amp_short_vectors/Concurrency::graphics::int_4::yzxw", "amp_short_vectors/Concurrency::graphics::int_4::wzx", "amp_short_vectors/Concurrency::graphics::int_4::zxyw", "amp_short_vectors/Concurrency::graphics::int_4::set_zwxy", "amp_short_vectors/Concurrency::graphics::int_4::get_wzy", "amp_short_vectors/Concurrency::graphics::int_4::zwyx", "amp_short_vectors/Concurrency::graphics::int_4::set_xywz", "amp_short_vectors/Concurrency::graphics::int_4::set_zxwy", "amp_short_vectors/Concurrency::graphics::int_4::set_zy", "amp_short_vectors/Concurrency::graphics::int_4::yx", "amp_short_vectors/Concurrency::graphics::int_4::set_yxzw", "amp_short_vectors/Concurrency::graphics::int_4::ar", "amp_short_vectors/Concurrency::graphics::int_4::yxwz", "amp_short_vectors/Concurrency::graphics::int_4::get_zxwy", "amp_short_vectors/Concurrency::graphics::int_4::rga", "amp_short_vectors/Concurrency::graphics::int_4::zy", "amp_short_vectors/Concurrency::graphics::int_4::operator-", "amp_short_vectors/Concurrency::graphics::int_4::xwzy", "amp_short_vectors/Concurrency::graphics::int_4::wxz", "amp_short_vectors/Concurrency::graphics::int_4::set_wzx", "amp_short_vectors/Concurrency::graphics::int_4::gb", "amp_short_vectors/Concurrency::graphics::int_4::get_yz", "amp_short_vectors/Concurrency::graphics::int_4::set_yzwx", "amp_short_vectors/Concurrency::graphics::int_4::get_wyz", "amp_short_vectors/Concurrency::graphics::int_4::set_wyx", "amp_short_vectors/Concurrency::graphics::int_4::get_zy", "amp_short_vectors/Concurrency::graphics::int_4::zx", "amp_short_vectors/Concurrency::graphics::int_4::set_xyw", "amp_short_vectors/Concurrency::graphics::int_4::wx", "amp_short_vectors/Concurrency::graphics::int_4::get_zxw", "amp_short_vectors/Concurrency::graphics::int_4::brga", "amp_short_vectors/Concurrency::graphics::int_4::set_zwx", "amp_short_vectors/Concurrency::graphics::int_4::a", "amp_short_vectors/Concurrency::graphics::int_4::ywx", "amp_short_vectors/Concurrency::graphics::int_4::wzxy", "amp_short_vectors/Concurrency::graphics::int_4::argb", "amp_short_vectors/Concurrency::graphics::int_4::set_wz", "amp_short_vectors/Concurrency::graphics::int_4::gbar", "amp_short_vectors/Concurrency::graphics::int_4::set_yxz", "amp_short_vectors/Concurrency::graphics::int_4::get_ywzx", "amp_short_vectors/Concurrency::graphics::int_4::abrg", "amp_short_vectors/Concurrency::graphics::int_4::bg", "amp_short_vectors/Concurrency::graphics::int_4::yxz"] -ms.assetid: 01768c28-23a8-4965-8267-96834864f4eb ---- -# int_4 Class - -Represents a short vector of four integers. - -## Syntax - -```cpp -class int_4; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[int_4 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|int_4::get_w|| -|int_4::get_wx|| -|int_4::get_wxy|| -|int_4::get_wxyz|| -|int_4::get_wxz|| -|int_4::get_wxzy|| -|int_4::get_wy|| -|int_4::get_wyx|| -|int_4::get_wyxz|| -|int_4::get_wyz|| -|int_4::get_wyzx|| -|int_4::get_wz|| -|int_4::get_wzx|| -|int_4::get_wzxy|| -|int_4::get_wzy|| -|int_4::get_wzyx|| -|int_4::get_x|| -|int_4::get_xw|| -|int_4::get_xwy|| -|int_4::get_xwyz|| -|int_4::get_xwz|| -|int_4::get_xwzy|| -|int_4::get_xy|| -|int_4::get_xyw|| -|int_4::get_xywz|| -|int_4::get_xyz|| -|int_4::get_xyzw|| -|int_4::get_xz|| -|int_4::get_xzw|| -|int_4::get_xzwy|| -|int_4::get_xzy|| -|int_4::get_xzyw|| -|int_4::get_y|| -|int_4::get_yw|| -|int_4::get_ywx|| -|int_4::get_ywxz|| -|int_4::get_ywz|| -|int_4::get_ywzx|| -|int_4::get_yx|| -|int_4::get_yxw|| -|int_4::get_yxwz|| -|int_4::get_yxz|| -|int_4::get_yxzw|| -|int_4::get_yz|| -|int_4::get_yzw|| -|int_4::get_yzwx|| -|int_4::get_yzx|| -|int_4::get_yzxw|| -|int_4::get_z|| -|int_4::get_zw|| -|int_4::get_zwx|| -|int_4::get_zwxy|| -|int_4::get_zwy|| -|int_4::get_zwyx|| -|int_4::get_zx|| -|int_4::get_zxw|| -|int_4::get_zxwy|| -|int_4::get_zxy|| -|int_4::get_zxyw|| -|int_4::get_zy|| -|int_4::get_zyw|| -|int_4::get_zywx|| -|int_4::get_zyx|| -|int_4::get_zyxw|| -|int_4::ref_a|| -|int_4::ref_b|| -|int_4::ref_g|| -|int_4::ref_r|| -|int_4::ref_w|| -|int_4::ref_x|| -|int_4::ref_y|| -|int_4::ref_z|| -|int_4::set_w|| -|int_4::set_wx|| -|int_4::set_wxy|| -|int_4::set_wxyz|| -|int_4::set_wxz|| -|int_4::set_wxzy|| -|int_4::set_wy|| -|int_4::set_wyx|| -|int_4::set_wyxz|| -|int_4::set_wyz|| -|int_4::set_wyzx|| -|int_4::set_wz|| -|int_4::set_wzx|| -|int_4::set_wzxy|| -|int_4::set_wzy|| -|int_4::set_wzyx|| -|int_4::set_x|| -|int_4::set_xw|| -|int_4::set_xwy|| -|int_4::set_xwyz|| -|int_4::set_xwz|| -|int_4::set_xwzy|| -|int_4::set_xy|| -|int_4::set_xyw|| -|int_4::set_xywz|| -|int_4::set_xyz|| -|int_4::set_xyzw|| -|int_4::set_xz|| -|int_4::set_xzw|| -|int_4::set_xzwy|| -|int_4::set_xzy|| -|int_4::set_xzyw|| -|int_4::set_y|| -|int_4::set_yw|| -|int_4::set_ywx|| -|int_4::set_ywxz|| -|int_4::set_ywz|| -|int_4::set_ywzx|| -|int_4::set_yx|| -|int_4::set_yxw|| -|int_4::set_yxwz|| -|int_4::set_yxz|| -|int_4::set_yxzw|| -|int_4::set_yz|| -|int_4::set_yzw|| -|int_4::set_yzwx|| -|int_4::set_yzx|| -|int_4::set_yzxw|| -|int_4::set_z|| -|int_4::set_zw|| -|int_4::set_zwx|| -|int_4::set_zwxy|| -|int_4::set_zwy|| -|int_4::set_zwyx|| -|int_4::set_zx|| -|int_4::set_zxw|| -|int_4::set_zxwy|| -|int_4::set_zxy|| -|int_4::set_zxyw|| -|int_4::set_zy|| -|int_4::set_zyw|| -|int_4::set_zywx|| -|int_4::set_zyx|| -|int_4::set_zyxw|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|int_4::operator-|| -|int_4::operator--|| -|int_4::operator%=|| -|int_4::operator&=|| -|int_4::operator*=|| -|int_4::operator/=|| -|int_4::operator^=|| -|int_4::operator\|=|| -|int_4::operator~|| -|int_4::operator++|| -|int_4::operator+=|| -|int_4::operator<\<=|| -|int_4::operator=|| -|int_4::operator-=|| -|int_4::operator>>=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#int_4__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|int_4::a|| -|int_4::ab|| -|int_4::abg|| -|int_4::abgr|| -|int_4::abr|| -|int_4::abrg|| -|int_4::ag|| -|int_4::agb|| -|int_4::agbr|| -|int_4::agr|| -|int_4::agrb|| -|int_4::ar|| -|int_4::arb|| -|int_4::arbg|| -|int_4::arg|| -|int_4::argb|| -|int_4::b|| -|int_4::ba|| -|int_4::bag|| -|int_4::bagr|| -|int_4::bar|| -|int_4::barg|| -|int_4::bg|| -|int_4::bga|| -|int_4::bgar|| -|int_4::bgr|| -|int_4::bgra|| -|int_4::br|| -|int_4::bra|| -|int_4::brag|| -|int_4::brg|| -|int_4::brga|| -|int_4::g|| -|int_4::ga|| -|int_4::gab|| -|int_4::gabr|| -|int_4::gar|| -|int_4::garb|| -|int_4::gb|| -|int_4::gba|| -|int_4::gbar|| -|int_4::gbr|| -|int_4::gbra|| -|int_4::gr|| -|int_4::gra|| -|int_4::grab|| -|int_4::grb|| -|int_4::grba|| -|int_4::r|| -|int_4::ra|| -|int_4::rab|| -|int_4::rabg|| -|int_4::rag|| -|int_4::ragb|| -|int_4::rb|| -|int_4::rba|| -|int_4::rbag|| -|int_4::rbg|| -|int_4::rbga|| -|int_4::rg|| -|int_4::rga|| -|int_4::rgab|| -|int_4::rgb|| -|int_4::rgba|| -|int_4::w|| -|int_4::wx|| -|int_4::wxy|| -|int_4::wxyz|| -|int_4::wxz|| -|int_4::wxzy|| -|int_4::wy|| -|int_4::wyx|| -|int_4::wyxz|| -|int_4::wyz|| -|int_4::wyzx|| -|int_4::wz|| -|int_4::wzx|| -|int_4::wzxy|| -|int_4::wzy|| -|int_4::wzyx|| -|int_4::x|| -|int_4::xw|| -|int_4::xwy|| -|int_4::xwyz|| -|int_4::xwz|| -|int_4::xwzy|| -|int_4::xy|| -|int_4::xyw|| -|int_4::xywz|| -|int_4::xyz|| -|int_4::xyzw|| -|int_4::xz|| -|int_4::xzw|| -|int_4::xzwy|| -|int_4::xzy|| -|int_4::xzyw|| -|int_4::y|| -|int_4::yw|| -|int_4::ywx|| -|int_4::ywxz|| -|int_4::ywz|| -|int_4::ywzx|| -|int_4::yx|| -|int_4::yxw|| -|int_4::yxwz|| -|int_4::yxz|| -|int_4::yxzw|| -|int_4::yz|| -|int_4::yzw|| -|int_4::yzwx|| -|int_4::yzx|| -|int_4::yzxw|| -|int_4::z|| -|int_4::zw|| -|int_4::zwx|| -|int_4::zwxy|| -|int_4::zwy|| -|int_4::zwyx|| -|int_4::zx|| -|int_4::zxw|| -|int_4::zxwy|| -|int_4::zxy|| -|int_4::zxyw|| -|int_4::zy|| -|int_4::zyw|| -|int_4::zywx|| -|int_4::zyx|| -|int_4::zyxw|| - -## Inheritance Hierarchy - -`int_4` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## int_4 - -Default constructor, initializes all elements with 0. - -```cpp -int_4() restrict(amp, - cpu); - -int_4( - int _V0, - int _V1, - int _V2, - int _V3) restrict(amp, - cpu); - -int_4( - int _V) restrict(amp, - cpu); - -int_4( - const int_4& _Other) restrict(amp, - cpu); - -explicit inline int_4( - const uint_4& _Other) restrict(amp, - cpu); - -explicit inline int_4( - const float_4& _Other) restrict(amp, - cpu); - -explicit inline int_4( - const unorm_4& _Other) restrict(amp, - cpu); - -explicit inline int_4( - const norm_4& _Other) restrict(amp, - cpu); - -explicit inline int_4( - const double_4& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V3*
-The value to initialize element 3. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 4; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/invalid-compute-domain-class.md b/docs/parallel/amp/reference/invalid-compute-domain-class.md deleted file mode 100644 index 333ee60fc80..00000000000 --- a/docs/parallel/amp/reference/invalid-compute-domain-class.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: "Learn more about: invalid_compute_domain Class" -title: "invalid_compute_domain Class" -ms.date: "11/04/2016" -f1_keywords: ["invalid_compute_domain", "AMPRT/invalid_compute_domain", "AMPRT/Concurrency::invalid_compute_domain::invalid_compute_domain"] -helpviewer_keywords: ["invalid_compute_domain class"] -ms.assetid: ac7a7166-8bdb-4db1-8caf-ea129ab5117e ---- -# invalid_compute_domain Class - -The exception that's thrown when the runtime can't start a kernel by using the compute domain specified at the [parallel_for_each](concurrency-namespace-functions-amp.md#parallel_for_each) call site. - -## Syntax - -```cpp -class invalid_compute_domain : public runtime_exception; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[invalid_compute_domain Constructor](#ctor)|Initializes a new instance of the `invalid_compute_domain` class.| - -## Inheritance Hierarchy - -`exception` - -`runtime_exception` - -`invalid_compute_domain` - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## invalid_compute_domain - -Initializes a new instance of the class. - -### Syntax - -```cpp -explicit invalid_compute_domain( - const char * _Message ) throw(); - -invalid_compute_domain() throw(); -``` - -### Parameters - -*_Message*
-A description of the error. - -### Return Value - -An instance of the `invalid_compute_domain` class - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/norm-2-class.md b/docs/parallel/amp/reference/norm-2-class.md deleted file mode 100644 index 4a244b33204..00000000000 --- a/docs/parallel/amp/reference/norm-2-class.md +++ /dev/null @@ -1,169 +0,0 @@ ---- -description: "Learn more about: norm_2 Class" -title: "norm_2 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::norm_2::set_x", "amp_short_vectors/Concurrency::graphics::norm_2::set_xy", "amp_short_vectors/Concurrency::graphics::norm_2::g", "amp_short_vectors/Concurrency::graphics::norm_2::get_yx", "amp_short_vectors/Concurrency::graphics::norm_2::set_yx", "amp_short_vectors/Concurrency::graphics::norm_2::operator-=", "amp_short_vectors/Concurrency::graphics::norm_2::operator/=", "amp_short_vectors/Concurrency::graphics::norm_2::operator*=", "amp_short_vectors/Concurrency::graphics::norm_2::yx", "amp_short_vectors/Concurrency::graphics::norm_2::y", "amp_short_vectors/Concurrency::graphics::norm_2::xy", "amp_short_vectors/Concurrency::graphics::norm_2::operator++", "amp_short_vectors/Concurrency::graphics::norm_2::operator-", "amp_short_vectors/Concurrency::graphics::norm_2::rg", "amp_short_vectors/Concurrency::graphics::norm_2::operator=", "amp_short_vectors/Concurrency::graphics::norm_2::get_y", "amp_short_vectors/Concurrency::graphics::norm_2::r", "amp_short_vectors/Concurrency::graphics::norm_2::get_x", "amp_short_vectors/Concurrency::graphics::norm_2::get_xy", "amp_short_vectors/Concurrency::graphics::norm_2::gr", "amp_short_vectors/Concurrency::graphics::norm_2::set_y", "amp_short_vectors/Concurrency::graphics::norm_2::x", "amp_short_vectors/Concurrency::graphics::norm_2::operator+=", "amp_short_vectors/Concurrency::graphics::norm_2", "amp_short_vectors/Concurrency::graphics::norm_2::operator--"] -ms.assetid: 80703f9b-61f4-414a-93fd-bc774f7d3393 ---- -# norm_2 Class - -Represents a short vector of two normal numbers. - -## Syntax - -```cpp -class norm_2; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[norm_2 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|norm_2::get_x|| -|norm_2::get_xy|| -|norm_2::get_y|| -|norm_2::get_yx|| -|norm_2::ref_g|| -|norm_2::ref_r|| -|norm_2::ref_x|| -|norm_2::ref_y|| -|norm_2::set_x|| -|norm_2::set_xy|| -|norm_2::set_y|| -|norm_2::set_yx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|norm_2::operator-|| -|norm_2::operator--|| -|norm_2::operator*=|| -|norm_2::operator/=|| -|norm_2::operator++|| -|norm_2::operator+=|| -|norm_2::operator=|| -|norm_2::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#norm_2__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|norm_2::g|| -|norm_2::gr|| -|norm_2::r|| -|norm_2::rg|| -|norm_2::x|| -|norm_2::xy|| -|norm_2::y|| -|norm_2::yx|| - -## Inheritance Hierarchy - -`norm_2` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## norm_2 - -Default constructor, initializes all elements with 0. - -```cpp -norm_2() restrict(amp, - cpu); - -norm_2( - norm _V0, - norm _V1) restrict(amp, - cpu); - -norm_2( - float _V0, - float _V1) restrict(amp, - cpu); - -norm_2( - unorm _V0, - unorm _V1) restrict(amp, - cpu); - -norm_2( - norm _V) restrict(amp, - cpu); - -explicit norm_2( - float _V) restrict(amp, - cpu); - -norm_2( - const norm_2& _Other) restrict(amp, - cpu); - -explicit inline norm_2( - const uint_2& _Other) restrict(amp, - cpu); - -explicit inline norm_2( - const int_2& _Other) restrict(amp, - cpu); - -explicit inline norm_2( - const float_2& _Other) restrict(amp, - cpu); - -explicit inline norm_2( - const unorm_2& _Other) restrict(amp, - cpu); - -explicit inline norm_2( - const double_2& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 2; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/norm-3-class.md b/docs/parallel/amp/reference/norm-3-class.md deleted file mode 100644 index 336f4b5e089..00000000000 --- a/docs/parallel/amp/reference/norm-3-class.md +++ /dev/null @@ -1,213 +0,0 @@ ---- -description: "Learn more about: norm_3 Class" -title: "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 - -Represents a short vector of three normal numbers. - -## Syntax - -```cpp -class norm_3; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[norm_3 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|norm_3::get_x|| -|norm_3::get_xy|| -|norm_3::get_xyz|| -|norm_3::get_xz|| -|norm_3::get_xzy|| -|norm_3::get_y|| -|norm_3::get_yx|| -|norm_3::get_yxz|| -|norm_3::get_yz|| -|norm_3::get_yzx|| -|norm_3::get_z|| -|norm_3::get_zx|| -|norm_3::get_zxy|| -|norm_3::get_zy|| -|norm_3::get_zyx|| -|norm_3::ref_b|| -|norm_3::ref_g|| -|norm_3::ref_r|| -|norm_3::ref_x|| -|norm_3::ref_y|| -|norm_3::ref_z|| -|norm_3::set_x|| -|norm_3::set_xy|| -|norm_3::set_xyz|| -|norm_3::set_xz|| -|norm_3::set_xzy|| -|norm_3::set_y|| -|norm_3::set_yx|| -|norm_3::set_yxz|| -|norm_3::set_yz|| -|norm_3::set_yzx|| -|norm_3::set_z|| -|norm_3::set_zx|| -|norm_3::set_zxy|| -|norm_3::set_zy|| -|norm_3::set_zyx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|norm_3::operator-|| -|norm_3::operator--|| -|norm_3::operator*=|| -|norm_3::operator/=|| -|norm_3::operator++|| -|norm_3::operator+=|| -|norm_3::operator=|| -|norm_3::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|norm_3::b|| -|norm_3::bg|| -|norm_3::bgr|| -|norm_3::br|| -|norm_3::brg|| -|norm_3::g|| -|norm_3::gb|| -|norm_3::gbr|| -|norm_3::gr|| -|norm_3::grb|| -|norm_3::r|| -|norm_3::rb|| -|norm_3::rbg|| -|norm_3::rg|| -|norm_3::rgb|| -|norm_3::x|| -|norm_3::xy|| -|norm_3::xyz|| -|norm_3::xz|| -|norm_3::xzy|| -|norm_3::y|| -|norm_3::yx|| -|norm_3::yxz|| -|norm_3::yz|| -|norm_3::yzx|| -|norm_3::z|| -|norm_3::zx|| -|norm_3::zxy|| -|norm_3::zy|| -|norm_3::zyx|| - -## Inheritance Hierarchy - -`norm_3` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## norm_3 Constructor - -Default constructor, initializes all elements with 0. - -### Syntax - -```cpp -norm_3() restrict(amp,cpu); -norm_3( - norm _V0, - norm _V1, - norm _V2 -) restrict(amp,cpu); -norm_3( - float _V0, - float _V1, - float _V2 -) restrict(amp,cpu); -norm_3( - unorm _V0, - unorm _V1, - unorm _V2 -) restrict(amp,cpu); -norm_3( - norm _V -) restrict(amp,cpu); -explicit norm_3( - float _V -) restrict(amp,cpu); -norm_3( - const norm_3& _Other -) restrict(amp,cpu); -explicit inline norm_3( - const uint_3& _Other -) restrict(amp,cpu); -explicit inline norm_3( - const int_3& _Other -) restrict(amp,cpu); -explicit inline norm_3( - const float_3& _Other -) restrict(amp,cpu); -explicit inline norm_3( - const unorm_3& _Other -) restrict(amp,cpu); -explicit inline norm_3( - const double_3& _Other -) restrict(amp,cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size Constant - -### Syntax - -```cpp -static const int size = 3; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/norm-4-class.md b/docs/parallel/amp/reference/norm-4-class.md deleted file mode 100644 index 0b0262d23a5..00000000000 --- a/docs/parallel/amp/reference/norm-4-class.md +++ /dev/null @@ -1,425 +0,0 @@ ---- -description: "Learn more about: norm_4 Class" -title: "norm_4 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::norm_4::grab", "amp_short_vectors/Concurrency::graphics::norm_4::agrb", "amp_short_vectors/Concurrency::graphics::norm_4::bg", "amp_short_vectors/Concurrency::graphics::norm_4::get_wx", "amp_short_vectors/Concurrency::graphics::norm_4::rabg", "amp_short_vectors/Concurrency::graphics::norm_4::get_wxz", "amp_short_vectors/Concurrency::graphics::norm_4::get_zxyw", "amp_short_vectors/Concurrency::graphics::norm_4::get_ywxz", "amp_short_vectors/Concurrency::graphics::norm_4::zwyx", "amp_short_vectors/Concurrency::graphics::norm_4::set_yxzw", "amp_short_vectors/Concurrency::graphics::norm_4::rag", "amp_short_vectors/Concurrency::graphics::norm_4::operator--", "amp_short_vectors/Concurrency::graphics::norm_4::agbr", "amp_short_vectors/Concurrency::graphics::norm_4::set_zyw", "amp_short_vectors/Concurrency::graphics::norm_4::y", "amp_short_vectors/Concurrency::graphics::norm_4::get_xzy", "amp_short_vectors/Concurrency::graphics::norm_4::get_wxy", "amp_short_vectors/Concurrency::graphics::norm_4::get_ywzx", "amp_short_vectors/Concurrency::graphics::norm_4::grba", "amp_short_vectors/Concurrency::graphics::norm_4::get_xwz", "amp_short_vectors/Concurrency::graphics::norm_4::xzy", "amp_short_vectors/Concurrency::graphics::norm_4::get_xywz", "amp_short_vectors/Concurrency::graphics::norm_4::get_ywx", "amp_short_vectors/Concurrency::graphics::norm_4::abgr", "amp_short_vectors/Concurrency::graphics::norm_4::get_xyzw", "amp_short_vectors/Concurrency::graphics::norm_4::ywx", "amp_short_vectors/Concurrency::graphics::norm_4::argb", "amp_short_vectors/Concurrency::graphics::norm_4::set_ywx", "amp_short_vectors/Concurrency::graphics::norm_4::set_yzx", "amp_short_vectors/Concurrency::graphics::norm_4::b", "amp_short_vectors/Concurrency::graphics::norm_4::arb", "amp_short_vectors/Concurrency::graphics::norm_4::rab", "amp_short_vectors/Concurrency::graphics::norm_4::gb", "amp_short_vectors/Concurrency::graphics::norm_4::yzxw", "amp_short_vectors/Concurrency::graphics::norm_4::bagr", "amp_short_vectors/Concurrency::graphics::norm_4::wyzx", "amp_short_vectors/Concurrency::graphics::norm_4::gba", "amp_short_vectors/Concurrency::graphics::norm_4::wz", "amp_short_vectors/Concurrency::graphics::norm_4::get_yz", "amp_short_vectors/Concurrency::graphics::norm_4::rgab", "amp_short_vectors/Concurrency::graphics::norm_4::get_wxzy", "amp_short_vectors/Concurrency::graphics::norm_4::set_wzyx", "amp_short_vectors/Concurrency::graphics::norm_4::set_yzxw", "amp_short_vectors/Concurrency::graphics::norm_4::xzw", "amp_short_vectors/Concurrency::graphics::norm_4::zwxy", "amp_short_vectors/Concurrency::graphics::norm_4::yzw", "amp_short_vectors/Concurrency::graphics::norm_4::set_zxw", "amp_short_vectors/Concurrency::graphics::norm_4::ywxz", "amp_short_vectors/Concurrency::graphics::norm_4::yxz", "amp_short_vectors/Concurrency::graphics::norm_4::rbg", "amp_short_vectors/Concurrency::graphics::norm_4::get_wyz", "amp_short_vectors/Concurrency::graphics::norm_4::get_zwyx", "amp_short_vectors/Concurrency::graphics::norm_4::set_zxwy", "amp_short_vectors/Concurrency::graphics::norm_4::set_xzwy", "amp_short_vectors/Concurrency::graphics::norm_4::set_zxyw", "amp_short_vectors/Concurrency::graphics::norm_4::get_wzyx", "amp_short_vectors/Concurrency::graphics::norm_4::barg", "amp_short_vectors/Concurrency::graphics::norm_4::set_zywx", "amp_short_vectors/Concurrency::graphics::norm_4::set_wx", "amp_short_vectors/Concurrency::graphics::norm_4::bar", "amp_short_vectors/Concurrency::graphics::norm_4::a", "amp_short_vectors/Concurrency::graphics::norm_4::set_xyz", "amp_short_vectors/Concurrency::graphics::norm_4::gab", "amp_short_vectors/Concurrency::graphics::norm_4::gbra", "amp_short_vectors/Concurrency::graphics::norm_4::agr", "amp_short_vectors/Concurrency::graphics::norm_4::xzyw", "amp_short_vectors/Concurrency::graphics::norm_4::rg", "amp_short_vectors/Concurrency::graphics::norm_4::get_wzxy", "amp_short_vectors/Concurrency::graphics::norm_4::operator=", "amp_short_vectors/Concurrency::graphics::norm_4::wxzy", "amp_short_vectors/Concurrency::graphics::norm_4::get_x", "amp_short_vectors/Concurrency::graphics::norm_4::bra", "amp_short_vectors/Concurrency::graphics::norm_4::get_xwzy", "amp_short_vectors/Concurrency::graphics::norm_4::yzwx", "amp_short_vectors/Concurrency::graphics::norm_4::wzyx", "amp_short_vectors/Concurrency::graphics::norm_4::gbar", "amp_short_vectors/Concurrency::graphics::norm_4::set_wyzx", "amp_short_vectors/Concurrency::graphics::norm_4::set_yxz", "amp_short_vectors/Concurrency::graphics::norm_4::wzxy", "amp_short_vectors/Concurrency::graphics::norm_4::garb", "amp_short_vectors/Concurrency::graphics::norm_4::bgar", "amp_short_vectors/Concurrency::graphics::norm_4::set_zx", "amp_short_vectors/Concurrency::graphics::norm_4::bgr", "amp_short_vectors/Concurrency::graphics::norm_4::ga", "amp_short_vectors/Concurrency::graphics::norm_4::set_wzy", "amp_short_vectors/Concurrency::graphics::norm_4::zxw", "amp_short_vectors/Concurrency::graphics::norm_4::get_xwyz", "amp_short_vectors/Concurrency::graphics::norm_4::yzx", "amp_short_vectors/Concurrency::graphics::norm_4::get_wy", "amp_short_vectors/Concurrency::graphics::norm_4::get_xwy", "amp_short_vectors/Concurrency::graphics::norm_4::set_xw", "amp_short_vectors/Concurrency::graphics::norm_4::yz", "amp_short_vectors/Concurrency::graphics::norm_4::w", "amp_short_vectors/Concurrency::graphics::norm_4::wxyz", "amp_short_vectors/Concurrency::graphics::norm_4::set_w", "amp_short_vectors/Concurrency::graphics::norm_4::gar", "amp_short_vectors/Concurrency::graphics::norm_4::get_yzx", "amp_short_vectors/Concurrency::graphics::norm_4::set_zwx", "amp_short_vectors/Concurrency::graphics::norm_4::set_wxzy", "amp_short_vectors/Concurrency::graphics::norm_4::xyz", "amp_short_vectors/Concurrency::graphics::norm_4::set_wz", "amp_short_vectors/Concurrency::graphics::norm_4::get_xz", "amp_short_vectors/Concurrency::graphics::norm_4::set_zwxy", "amp_short_vectors/Concurrency::graphics::norm_4::get_w", "amp_short_vectors/Concurrency::graphics::norm_4::set_yzw", "amp_short_vectors/Concurrency::graphics::norm_4::set_yx", "amp_short_vectors/Concurrency::graphics::norm_4::rga", "amp_short_vectors/Concurrency::graphics::norm_4::xwy", "amp_short_vectors/Concurrency::graphics::norm_4::wzy", "amp_short_vectors/Concurrency::graphics::norm_4::wzx", "amp_short_vectors/Concurrency::graphics::norm_4::xz", "amp_short_vectors/Concurrency::graphics::norm_4::brga", "amp_short_vectors/Concurrency::graphics::norm_4::brag", "amp_short_vectors/Concurrency::graphics::norm_4::set_wyz", "amp_short_vectors/Concurrency::graphics::norm_4::ra", "amp_short_vectors/Concurrency::graphics::norm_4::get_xzwy", "amp_short_vectors/Concurrency::graphics::norm_4::zyx", "amp_short_vectors/Concurrency::graphics::norm_4::yw", "amp_short_vectors/Concurrency::graphics::norm_4::set_yzwx", "amp_short_vectors/Concurrency::graphics::norm_4::get_yxz", "amp_short_vectors/Concurrency::graphics::norm_4::xwzy", "amp_short_vectors/Concurrency::graphics::norm_4::get_zyw", "amp_short_vectors/Concurrency::graphics::norm_4::gbr", "amp_short_vectors/Concurrency::graphics::norm_4::zxyw", "amp_short_vectors/Concurrency::graphics::norm_4::wyx", "amp_short_vectors/Concurrency::graphics::norm_4::get_zyxw", "amp_short_vectors/Concurrency::graphics::norm_4::get_zwy", "amp_short_vectors/Concurrency::graphics::norm_4::set_zxy", "amp_short_vectors/Concurrency::graphics::norm_4::ywz", "amp_short_vectors/Concurrency::graphics::norm_4::xy", "amp_short_vectors/Concurrency::graphics::norm_4", "amp_short_vectors/Concurrency::graphics::norm_4::set_wxyz", "amp_short_vectors/Concurrency::graphics::norm_4::r", "amp_short_vectors/Concurrency::graphics::norm_4::get_zwx", "amp_short_vectors/Concurrency::graphics::norm_4::get_xw", "amp_short_vectors/Concurrency::graphics::norm_4::xyw", "amp_short_vectors/Concurrency::graphics::norm_4::wxy", "amp_short_vectors/Concurrency::graphics::norm_4::set_wxz", "amp_short_vectors/Concurrency::graphics::norm_4::agb", "amp_short_vectors/Concurrency::graphics::norm_4::bga", "amp_short_vectors/Concurrency::graphics::norm_4::gr", "amp_short_vectors/Concurrency::graphics::norm_4::arg", "amp_short_vectors/Concurrency::graphics::norm_4::rgba", "amp_short_vectors/Concurrency::graphics::norm_4::arbg", "amp_short_vectors/Concurrency::graphics::norm_4::yx", "amp_short_vectors/Concurrency::graphics::norm_4::set_yz", "amp_short_vectors/Concurrency::graphics::norm_4::set_yxwz", "amp_short_vectors/Concurrency::graphics::norm_4::get_wyzx", "amp_short_vectors/Concurrency::graphics::norm_4::get_yzw", "amp_short_vectors/Concurrency::graphics::norm_4::set_yw", "amp_short_vectors/Concurrency::graphics::norm_4::brg", "amp_short_vectors/Concurrency::graphics::norm_4::zxy", "amp_short_vectors/Concurrency::graphics::norm_4::operator-", "amp_short_vectors/Concurrency::graphics::norm_4::yxzw", "amp_short_vectors/Concurrency::graphics::norm_4::rbga", "amp_short_vectors/Concurrency::graphics::norm_4::set_zyxw", "amp_short_vectors/Concurrency::graphics::norm_4::zwy", "amp_short_vectors/Concurrency::graphics::norm_4::abr", "amp_short_vectors/Concurrency::graphics::norm_4::get_zwxy", "amp_short_vectors/Concurrency::graphics::norm_4::br", "amp_short_vectors/Concurrency::graphics::norm_4::set_xzy", "amp_short_vectors/Concurrency::graphics::norm_4::get_zx", "amp_short_vectors/Concurrency::graphics::norm_4::rgb", "amp_short_vectors/Concurrency::graphics::norm_4::get_zy", "amp_short_vectors/Concurrency::graphics::norm_4::zw", "amp_short_vectors/Concurrency::graphics::norm_4::set_ywzx", "amp_short_vectors/Concurrency::graphics::norm_4::set_xy", "amp_short_vectors/Concurrency::graphics::norm_4::get_xzw", "amp_short_vectors/Concurrency::graphics::norm_4::rba", "amp_short_vectors/Concurrency::graphics::norm_4::get_wyx", "amp_short_vectors/Concurrency::graphics::norm_4::operator+=", "amp_short_vectors/Concurrency::graphics::norm_4::set_xwz", "amp_short_vectors/Concurrency::graphics::norm_4::set_zwy", "amp_short_vectors/Concurrency::graphics::norm_4::abg", "amp_short_vectors/Concurrency::graphics::norm_4::xywz", "amp_short_vectors/Concurrency::graphics::norm_4::ar", "amp_short_vectors/Concurrency::graphics::norm_4::set_y", "amp_short_vectors/Concurrency::graphics::norm_4::get_xzyw", "amp_short_vectors/Concurrency::graphics::norm_4::set_yxw", "amp_short_vectors/Concurrency::graphics::norm_4::set_ywxz", "amp_short_vectors/Concurrency::graphics::norm_4::yxw", "amp_short_vectors/Concurrency::graphics::norm_4::get_z", "amp_short_vectors/Concurrency::graphics::norm_4::get_zxy", "amp_short_vectors/Concurrency::graphics::norm_4::ag", "amp_short_vectors/Concurrency::graphics::norm_4::operator/=", "amp_short_vectors/Concurrency::graphics::norm_4::gra", "amp_short_vectors/Concurrency::graphics::norm_4::ragb", "amp_short_vectors/Concurrency::graphics::norm_4::get_yxwz", "amp_short_vectors/Concurrency::graphics::norm_4::get_wyxz", "amp_short_vectors/Concurrency::graphics::norm_4::xyzw", "amp_short_vectors/Concurrency::graphics::norm_4::zyw", "amp_short_vectors/Concurrency::graphics::norm_4::set_wzxy", "amp_short_vectors/Concurrency::graphics::norm_4::set_x", "amp_short_vectors/Concurrency::graphics::norm_4::set_xwyz", "amp_short_vectors/Concurrency::graphics::norm_4::wyz", "amp_short_vectors/Concurrency::graphics::norm_4::zwx", "amp_short_vectors/Concurrency::graphics::norm_4::set_zw", "amp_short_vectors/Concurrency::graphics::norm_4::zy", "amp_short_vectors/Concurrency::graphics::norm_4::set_zwyx", "amp_short_vectors/Concurrency::graphics::norm_4::set_xwzy", "amp_short_vectors/Concurrency::graphics::norm_4::get_yzxw", "amp_short_vectors/Concurrency::graphics::norm_4::get_yzwx", "amp_short_vectors/Concurrency::graphics::norm_4::z", "amp_short_vectors/Concurrency::graphics::norm_4::g", "amp_short_vectors/Concurrency::graphics::norm_4::get_xyz", "amp_short_vectors/Concurrency::graphics::norm_4::xwyz", "amp_short_vectors/Concurrency::graphics::norm_4::get_wxyz", "amp_short_vectors/Concurrency::graphics::norm_4::zywx", "amp_short_vectors/Concurrency::graphics::norm_4::operator++", "amp_short_vectors/Concurrency::graphics::norm_4::operator-=", "amp_short_vectors/Concurrency::graphics::norm_4::set_wyx", "amp_short_vectors/Concurrency::graphics::norm_4::wxz", "amp_short_vectors/Concurrency::graphics::norm_4::set_xyw", "amp_short_vectors/Concurrency::graphics::norm_4::set_ywz", "amp_short_vectors/Concurrency::graphics::norm_4::operator*=", "amp_short_vectors/Concurrency::graphics::norm_4::wx", "amp_short_vectors/Concurrency::graphics::norm_4::x", "amp_short_vectors/Concurrency::graphics::norm_4::get_y", "amp_short_vectors/Concurrency::graphics::norm_4::set_xzyw", "amp_short_vectors/Concurrency::graphics::norm_4::bag", "amp_short_vectors/Concurrency::graphics::norm_4::get_zw", "amp_short_vectors/Concurrency::graphics::norm_4::abrg", "amp_short_vectors/Concurrency::graphics::norm_4::get_xy", "amp_short_vectors/Concurrency::graphics::norm_4::set_wyxz", "amp_short_vectors/Concurrency::graphics::norm_4::ywzx", "amp_short_vectors/Concurrency::graphics::norm_4::set_xwy", "amp_short_vectors/Concurrency::graphics::norm_4::set_wxy", "amp_short_vectors/Concurrency::graphics::norm_4::set_xyzw", "amp_short_vectors/Concurrency::graphics::norm_4::wyxz", "amp_short_vectors/Concurrency::graphics::norm_4::ba", "amp_short_vectors/Concurrency::graphics::norm_4::xwz", "amp_short_vectors/Concurrency::graphics::norm_4::zxwy", "amp_short_vectors/Concurrency::graphics::norm_4::gabr", "amp_short_vectors/Concurrency::graphics::norm_4::set_wzx", "amp_short_vectors/Concurrency::graphics::norm_4::get_xyw", "amp_short_vectors/Concurrency::graphics::norm_4::grb", "amp_short_vectors/Concurrency::graphics::norm_4::get_zxw", "amp_short_vectors/Concurrency::graphics::norm_4::get_yw", "amp_short_vectors/Concurrency::graphics::norm_4::set_xzw", "amp_short_vectors/Concurrency::graphics::norm_4::set_wy", "amp_short_vectors/Concurrency::graphics::norm_4::get_yxw", "amp_short_vectors/Concurrency::graphics::norm_4::get_ywz", "amp_short_vectors/Concurrency::graphics::norm_4::get_wz", "amp_short_vectors/Concurrency::graphics::norm_4::yxwz", "amp_short_vectors/Concurrency::graphics::norm_4::get_zxwy", "amp_short_vectors/Concurrency::graphics::norm_4::set_zy", "amp_short_vectors/Concurrency::graphics::norm_4::xzwy", "amp_short_vectors/Concurrency::graphics::norm_4::bgra", "amp_short_vectors/Concurrency::graphics::norm_4::set_xz", "amp_short_vectors/Concurrency::graphics::norm_4::rbag", "amp_short_vectors/Concurrency::graphics::norm_4::zx", "amp_short_vectors/Concurrency::graphics::norm_4::get_zyx", "amp_short_vectors/Concurrency::graphics::norm_4::zyxw", "amp_short_vectors/Concurrency::graphics::norm_4::set_z", "amp_short_vectors/Concurrency::graphics::norm_4::xw", "amp_short_vectors/Concurrency::graphics::norm_4::set_xywz", "amp_short_vectors/Concurrency::graphics::norm_4::get_yxzw", "amp_short_vectors/Concurrency::graphics::norm_4::get_yx", "amp_short_vectors/Concurrency::graphics::norm_4::get_wzx", "amp_short_vectors/Concurrency::graphics::norm_4::ab", "amp_short_vectors/Concurrency::graphics::norm_4::rb", "amp_short_vectors/Concurrency::graphics::norm_4::get_zywx", "amp_short_vectors/Concurrency::graphics::norm_4::get_wzy", "amp_short_vectors/Concurrency::graphics::norm_4::set_zyx", "amp_short_vectors/Concurrency::graphics::norm_4::wy"] -ms.assetid: d628b2bf-2cdb-4dbb-95c6-cd778f5e991f ---- -# norm_4 Class - -Represents a short vector of four normal numbers. - -## Syntax - -```cpp -class norm_4; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[norm_4 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|norm_4::get_w|| -|norm_4::get_wx|| -|norm_4::get_wxy|| -|norm_4::get_wxyz|| -|norm_4::get_wxz|| -|norm_4::get_wxzy|| -|norm_4::get_wy|| -|norm_4::get_wyx|| -|norm_4::get_wyxz|| -|norm_4::get_wyz|| -|norm_4::get_wyzx|| -|norm_4::get_wz|| -|norm_4::get_wzx|| -|norm_4::get_wzxy|| -|norm_4::get_wzy|| -|norm_4::get_wzyx|| -|norm_4::get_x|| -|norm_4::get_xw|| -|norm_4::get_xwy|| -|norm_4::get_xwyz|| -|norm_4::get_xwz|| -|norm_4::get_xwzy|| -|norm_4::get_xy|| -|norm_4::get_xyw|| -|norm_4::get_xywz|| -|norm_4::get_xyz|| -|norm_4::get_xyzw|| -|norm_4::get_xz|| -|norm_4::get_xzw|| -|norm_4::get_xzwy|| -|norm_4::get_xzy|| -|norm_4::get_xzyw|| -|norm_4::get_y|| -|norm_4::get_yw|| -|norm_4::get_ywx|| -|norm_4::get_ywxz|| -|norm_4::get_ywz|| -|norm_4::get_ywzx|| -|norm_4::get_yx|| -|norm_4::get_yxw|| -|norm_4::get_yxwz|| -|norm_4::get_yxz|| -|norm_4::get_yxzw|| -|norm_4::get_yz|| -|norm_4::get_yzw|| -|norm_4::get_yzwx|| -|norm_4::get_yzx|| -|norm_4::get_yzxw|| -|norm_4::get_z|| -|norm_4::get_zw|| -|norm_4::get_zwx|| -|norm_4::get_zwxy|| -|norm_4::get_zwy|| -|norm_4::get_zwyx|| -|norm_4::get_zx|| -|norm_4::get_zxw|| -|norm_4::get_zxwy|| -|norm_4::get_zxy|| -|norm_4::get_zxyw|| -|norm_4::get_zy|| -|norm_4::get_zyw|| -|norm_4::get_zywx|| -|norm_4::get_zyx|| -|norm_4::get_zyxw|| -|norm_4::ref_a|| -|norm_4::ref_b|| -|norm_4::ref_g|| -|norm_4::ref_r|| -|norm_4::ref_w|| -|norm_4::ref_x|| -|norm_4::ref_y|| -|norm_4::ref_z|| -|norm_4::set_w|| -|norm_4::set_wx|| -|norm_4::set_wxy|| -|norm_4::set_wxyz|| -|norm_4::set_wxz|| -|norm_4::set_wxzy|| -|norm_4::set_wy|| -|norm_4::set_wyx|| -|norm_4::set_wyxz|| -|norm_4::set_wyz|| -|norm_4::set_wyzx|| -|norm_4::set_wz|| -|norm_4::set_wzx|| -|norm_4::set_wzxy|| -|norm_4::set_wzy|| -|norm_4::set_wzyx|| -|norm_4::set_x|| -|norm_4::set_xw|| -|norm_4::set_xwy|| -|norm_4::set_xwyz|| -|norm_4::set_xwz|| -|norm_4::set_xwzy|| -|norm_4::set_xy|| -|norm_4::set_xyw|| -|norm_4::set_xywz|| -|norm_4::set_xyz|| -|norm_4::set_xyzw|| -|norm_4::set_xz|| -|norm_4::set_xzw|| -|norm_4::set_xzwy|| -|norm_4::set_xzy|| -|norm_4::set_xzyw|| -|norm_4::set_y|| -|norm_4::set_yw|| -|norm_4::set_ywx|| -|norm_4::set_ywxz|| -|norm_4::set_ywz|| -|norm_4::set_ywzx|| -|norm_4::set_yx|| -|norm_4::set_yxw|| -|norm_4::set_yxwz|| -|norm_4::set_yxz|| -|norm_4::set_yxzw|| -|norm_4::set_yz|| -|norm_4::set_yzw|| -|norm_4::set_yzwx|| -|norm_4::set_yzx|| -|norm_4::set_yzxw|| -|norm_4::set_z|| -|norm_4::set_zw|| -|norm_4::set_zwx|| -|norm_4::set_zwxy|| -|norm_4::set_zwy|| -|norm_4::set_zwyx|| -|norm_4::set_zx|| -|norm_4::set_zxw|| -|norm_4::set_zxwy|| -|norm_4::set_zxy|| -|norm_4::set_zxyw|| -|norm_4::set_zy|| -|norm_4::set_zyw|| -|norm_4::set_zywx|| -|norm_4::set_zyx|| -|norm_4::set_zyxw|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|norm_4::operator-|| -|norm_4::operator--|| -|norm_4::operator*=|| -|norm_4::operator/=|| -|norm_4::operator++|| -|norm_4::operator+=|| -|norm_4::operator=|| -|norm_4::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#norm_4__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|norm_4::a|| -|norm_4::ab|| -|norm_4::abg|| -|norm_4::abgr|| -|norm_4::abr|| -|norm_4::abrg|| -|norm_4::ag|| -|norm_4::agb|| -|norm_4::agbr|| -|norm_4::agr|| -|norm_4::agrb|| -|norm_4::ar|| -|norm_4::arb|| -|norm_4::arbg|| -|norm_4::arg|| -|norm_4::argb|| -|norm_4::b|| -|norm_4::ba|| -|norm_4::bag|| -|norm_4::bagr|| -|norm_4::bar|| -|norm_4::barg|| -|norm_4::bg|| -|norm_4::bga|| -|norm_4::bgar|| -|norm_4::bgr|| -|norm_4::bgra|| -|norm_4::br|| -|norm_4::bra|| -|norm_4::brag|| -|norm_4::brg|| -|norm_4::brga|| -|norm_4::g|| -|norm_4::ga|| -|norm_4::gab|| -|norm_4::gabr|| -|norm_4::gar|| -|norm_4::garb|| -|norm_4::gb|| -|norm_4::gba|| -|norm_4::gbar|| -|norm_4::gbr|| -|norm_4::gbra|| -|norm_4::gr|| -|norm_4::gra|| -|norm_4::grab|| -|norm_4::grb|| -|norm_4::grba|| -|norm_4::r|| -|norm_4::ra|| -|norm_4::rab|| -|norm_4::rabg|| -|norm_4::rag|| -|norm_4::ragb|| -|norm_4::rb|| -|norm_4::rba|| -|norm_4::rbag|| -|norm_4::rbg|| -|norm_4::rbga|| -|norm_4::rg|| -|norm_4::rga|| -|norm_4::rgab|| -|norm_4::rgb|| -|norm_4::rgba|| -|norm_4::w|| -|norm_4::wx|| -|norm_4::wxy|| -|norm_4::wxyz|| -|norm_4::wxz|| -|norm_4::wxzy|| -|norm_4::wy|| -|norm_4::wyx|| -|norm_4::wyxz|| -|norm_4::wyz|| -|norm_4::wyzx|| -|norm_4::wz|| -|norm_4::wzx|| -|norm_4::wzxy|| -|norm_4::wzy|| -|norm_4::wzyx|| -|norm_4::x|| -|norm_4::xw|| -|norm_4::xwy|| -|norm_4::xwyz|| -|norm_4::xwz|| -|norm_4::xwzy|| -|norm_4::xy|| -|norm_4::xyw|| -|norm_4::xywz|| -|norm_4::xyz|| -|norm_4::xyzw|| -|norm_4::xz|| -|norm_4::xzw|| -|norm_4::xzwy|| -|norm_4::xzy|| -|norm_4::xzyw|| -|norm_4::y|| -|norm_4::yw|| -|norm_4::ywx|| -|norm_4::ywxz|| -|norm_4::ywz|| -|norm_4::ywzx|| -|norm_4::yx|| -|norm_4::yxw|| -|norm_4::yxwz|| -|norm_4::yxz|| -|norm_4::yxzw|| -|norm_4::yz|| -|norm_4::yzw|| -|norm_4::yzwx|| -|norm_4::yzx|| -|norm_4::yzxw|| -|norm_4::z|| -|norm_4::zw|| -|norm_4::zwx|| -|norm_4::zwxy|| -|norm_4::zwy|| -|norm_4::zwyx|| -|norm_4::zx|| -|norm_4::zxw|| -|norm_4::zxwy|| -|norm_4::zxy|| -|norm_4::zxyw|| -|norm_4::zy|| -|norm_4::zyw|| -|norm_4::zywx|| -|norm_4::zyx|| -|norm_4::zyxw|| - -## Inheritance Hierarchy - -`norm_4` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## norm_4 - -Default constructor, initializes all elements with 0. - -```cpp -norm_4() restrict(amp, - cpu); - -norm_4( - norm _V0, - norm _V1, - norm _V2, - norm _V3) restrict(amp, - cpu); - -norm_4( - float _V0, - float _V1, - float _V2, - float _V3) restrict(amp, - cpu); - -norm_4( - unorm _V0, - unorm _V1, - unorm _V2, - unorm _V3) restrict(amp, - cpu); - -norm_4( - norm _V) restrict(amp, - cpu); - -explicit norm_4( - float _V) restrict(amp, - cpu); - -norm_4( - const norm_4& _Other) restrict(amp, - cpu); - -explicit inline norm_4( - const uint_4& _Other) restrict(amp, - cpu); - -explicit inline norm_4( - const int_4& _Other) restrict(amp, - cpu); - -explicit inline norm_4( - const float_4& _Other) restrict(amp, - cpu); - -explicit inline norm_4( - const unorm_4& _Other) restrict(amp, - cpu); - -explicit inline norm_4( - const double_4& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V3*
-The value to initialize element 3. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 4; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/norm-class.md b/docs/parallel/amp/reference/norm-class.md deleted file mode 100644 index 56952e2cf8f..00000000000 --- a/docs/parallel/amp/reference/norm-class.md +++ /dev/null @@ -1,94 +0,0 @@ ---- -description: "Learn more about: norm Class" -title: "norm Class" -ms.date: "11/04/2016" -f1_keywords: ["AMP_SHORT_VECTORS/norm", "AMP_SHORT_VECTORS/Concurrency::graphics::norm Constructor"] -ms.assetid: 73002f3d-c25e-4119-bcd3-4c46c9b6abf1 ---- -# norm Class - -Represent a norm number. Each element is a floating point number in the range of [-1.0f, 1.0f]. - -## Syntax - -```cpp -class norm; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[norm Constructor](#ctor)|Overloaded. Default constructor. Initialize to 0.0f.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|norm::operator-|| -|norm::operator--|| -|norm::operator float|Conversion operator. Convert the norm number to a floating point value.| -|norm::operator*=|| -|norm::operator/=|| -|norm::operator++|| -|norm::operator+=|| -|norm::operator=|| -|norm::operator-=|| - -## Inheritance Hierarchy - -`norm` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## norm - -Default constructor. Initialize to 0.0f. - -```cpp -norm( - void) restrict(amp, - cpu); - -explicit norm( - float _V) restrict(amp, - cpu); - -explicit norm( - unsigned int _V) restrict(amp, - cpu); - -explicit norm( - int _V) restrict(amp, - cpu); - -explicit norm( - double _V) restrict(amp, - cpu); - -norm( - const norm& _Other) restrict(amp, - cpu); - -norm( - const unorm& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V*
-The value used to initialize. - -*_Other*
-The object used to initialize. - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/out-of-memory-class.md b/docs/parallel/amp/reference/out-of-memory-class.md deleted file mode 100644 index c59ef294a0a..00000000000 --- a/docs/parallel/amp/reference/out-of-memory-class.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: "Learn more about: out_of_memory Class" -title: "out_of_memory Class" -ms.date: "11/04/2016" -f1_keywords: ["out_of_memory", "AMPRT/out_of_memory", "AMPRT/Concurrency::out_of_memory::out_of_memory"] -helpviewer_keywords: ["out_of_memory class"] -ms.assetid: 3aa7e682-8f13-4ae6-9188-31fb423956e4 ---- -# out_of_memory Class - -The exception that is thrown when a method fails because of a lack of system or device memory. - -## Syntax - -```cpp -class out_of_memory : public runtime_exception; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[out_of_memory Constructor](#ctor)|Initializes a new instance of the `out_of_memory` class.| - -## Inheritance Hierarchy - -`exception` - -`runtime_exception` - -`out_of_memory` - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## out_of_memory - -Initializes a new instance of the class. - -### Syntax - -```cpp -explicit out_of_memory( - const char * _Message ) throw(); - -out_of_memory () throw(); -``` - -### Parameters - -*_Message*
-A description of the error. - -### Return Value - -A new instance of the `out_of_memory` class. - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/reference-cpp-amp.md b/docs/parallel/amp/reference/reference-cpp-amp.md deleted file mode 100644 index 21e44bd2a83..00000000000 --- a/docs/parallel/amp/reference/reference-cpp-amp.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -description: "Learn more about: Reference (C++ AMP)" -title: "Reference (C++ AMP)" -ms.date: "11/04/2016" -f1_keywords: ["amp/Concurrency::Reference (C++ AMP)"] -helpviewer_keywords: ["C++ Accelerated Massive Parallelism, reference"] -ms.assetid: 372a8aed-8a53-48c9-996f-9c3cf09c9fa8 ---- -# Reference (C++ AMP) - -This section contains reference information for the C++ Accelerated Massive Parallelism (C++ AMP) runtime. - -> [!NOTE] -> The C++ language standard reserves the use of identifiers that begin with an underscore (`_`) character for implementations such as libraries. Do not use names beginning with an underscore in your code. The behavior of code elements whose names follow this convention are not guaranteed and are subject to change in future releases. For these reasons, such code elements are omitted from this documentation. - -## In This Section - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md)
-Provides classes and functions that enable the acceleration of C++ code on data parallel hardware. - -[Concurrency::direct3d Namespace](concurrency-direct3d-namespace.md)
-Provides functions that support D3D interoperability. Enables seamless use of D3D resources for compute in AMP code and the use of resources created in AMP in D3D code, without creating redundant intermediate copies. You can use C++ AMP to incrementally accelerate the compute-intensive sections of your DirectX applications and use the D3D API on data produced from AMP computations. - -[Concurrency::fast_math Namespace](concurrency-fast-math-namespace.md)
-Functions in the `fast_math` namespace are not C99-conformant. Only single-precision versions of each function are provided. These functions use the DirectX intrinsic functions, which are faster than the corresponding functions in the `precise_math` namespace and do not require extended double-precision support on the accelerator, but they are less accurate. There are two versions of each function for source-level compatibility with C99 code; both versions take and return single-precision values. - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md)
-Provides types and functions that are designed for graphics programming. - -[Concurrency::precise_math Namespace](concurrency-precise-math-namespace.md)
-Functions in the `precise_math` namespace are C99 conformant. Both single-precision and double-precision versions of each function are included. These functions—this includes the single-precision functions—require extended double-precision support on the accelerator. - -## Related Sections - -[C++ AMP (C++ Accelerated Massive Parallelism)](../../../parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md)
-C++ AMP 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. diff --git a/docs/parallel/amp/reference/runtime-exception-class.md b/docs/parallel/amp/reference/runtime-exception-class.md deleted file mode 100644 index 663c5148d04..00000000000 --- a/docs/parallel/amp/reference/runtime-exception-class.md +++ /dev/null @@ -1,130 +0,0 @@ ---- -description: "Learn more about: runtime_exception Class" -title: "runtime_exception Class" -ms.date: "03/27/2019" -f1_keywords: ["runtime_exception", "AMPRT/runtime_exception", "AMPRT/Concurrency::runtime_exception", "AMPRT/Concurrency::runtime_exception::get_error_code"] -helpviewer_keywords: ["runtime_exception class"] -ms.assetid: 8fe3ce2c-3d4c-4b9c-95e8-e592f37adefd ---- -# runtime_exception Class - -The base type for exceptions in the C++ Accelerated Massive Parallelism (AMP) library. - -### Syntax - -```cpp -class runtime_exception : public std::exception; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[runtime_exception Constructor](#ctor)|Initializes a new instance of the `runtime_exception` class.| -|[~runtime_exception Destructor](#dtor)|Destroys the `runtime_exception` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[get_error_code](#get_error_code)|Returns the error code that caused the exception.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator=](#operator_eq)|Copies the contents of the specified `runtime_exception` object into this one.| - -## Inheritance Hierarchy - -`exception` - -`runtime_exception` - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## runtime_exception Constructor - -Initializes a new instance of the class. - -### Syntax - -```cpp -runtime_exception( - const char * _Message, - HRESULT _Hresult ) throw(); - -explicit runtime_exception( - HRESULT _Hresult ) throw(); - -runtime_exception( - const runtime_exception & _Other ) throw(); -``` - -### Parameters - -*_Message*
-A description of the error that caused the exception. - -*_Hresult*
-The HRESULT of error that caused the exception. - -*_Other*
-The `runtime_exception` object to copy. - -### Return Value - -The `runtime_exception` object. - -## ~runtime_exception Destructor - -Destroys the object. - -### Syntax - -```cpp -virtual ~runtime_exception() throw(); -``` - -## get_error_code - -Returns the error code that caused the exception. - -### Syntax - -```cpp -HRESULT get_error_code() const throw(); -``` - -### Return Value - -The HRESULT of error that caused the exception. - -## operator= - -Copies the contents of the specified `runtime_exception` object into this one. - -### Syntax - -```cpp -runtime_exception & operator= ( const runtime_exception & _Other ) throw(); -``` - -### Parameters - -*_Other*
-The `runtime_exception` object to copy. - -### Return Value - -A reference to this `runtime_exception` object. - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/sampler-class.md b/docs/parallel/amp/reference/sampler-class.md deleted file mode 100644 index ade1f10b703..00000000000 --- a/docs/parallel/amp/reference/sampler-class.md +++ /dev/null @@ -1,197 +0,0 @@ ---- -description: "Learn more about: sampler Class" -title: "sampler Class" -ms.date: "06/28/2018" -f1_keywords: ["sampler", "AMP_GRAPHICS/sampler", "AMP_GRAPHICS/concurrency::sampler::graphics::sampler", "AMP_GRAPHICS/concurrency::sampler::graphics::get_address_mode", "AMP_GRAPHICS/concurrency::sampler::graphics::get_border_color", "AMP_GRAPHICS/concurrency::sampler::graphics::get_filter_mode", "AMP_GRAPHICS/concurrency::sampler::graphics::address_mode", "AMP_GRAPHICS/concurrency::sampler::graphics::border_color", "AMP_GRAPHICS/concurrency::sampler::graphics::filter_mode"] -ms.assetid: 9a6a9807-497d-402d-b092-8c4d86275b80 ---- -# sampler Class - -The sampler class aggregates sampling configuration information to be used for texture sampling. - -## Syntax - -```cpp -class sampler; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[sampler Constructor](#ctor)|Overloaded. Constructs a sampler instance.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[get_address_mode](#get_address_mode)|Returns the `address_mode` that’s associated with the sampler object.| -|[get_border_color](#get_border_color)|Returns the border color that’s associated with the sampler object.| -|[get_filter_mode](#get_filter_mode)|Returns the `filter_mode` that’s associated with the sampler object.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator=](#operator_eq)|Overloaded. Assignment operator.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[address_mode](#address_mode)|Gets the address mode of the `sampler` object.| -|[border_color](#border_color)|Gets the border color of the `sampler` object.| -|[filter_mode](#filter_mode)|Gets the filter mode of the `sampler` object.| - -## Inheritance Hierarchy - -`sampler` - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** concurrency::graphics - -## sampler - -Constructs an instance of the [sampler Class](sampler-class.md). - -```cpp -sampler() restrict(cpu); // [1] default constructor - -sampler( // [2] constructor - filter_mode _Filter_mode) restrict(cpu); - -sampler( // [3] constructor - address_mode _Address_mode, - float_4 _Border_color = float_4(0.0f, - 0.0f, - 0.0f, - 0.0f)) restrict(cpu); - -sampler( // [4] constructor - filter_mode _Filter_mode, - address_mode _Address_mode, - float_4 _Border_color = float_4(0.0f, - 0.0f, - 0.0f, - 0.0f)) restrict(cpu); - -sampler( // [5] copy constructor - const sampler& _Other) restrict(amp, - cpu); - -sampler( // [6] move constructor - sampler&& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_Filter_mode*
-The filter mode to be used in sampling. - -*_Address_mode*
-The addressing mode to be used in sampling for all dimensions. - -*_Border_color*
-The border color to be used if the address mode is address_border. The default value is `float_4(0.0f, 0.0f, 0.0f, 0.0f)`. - -*_Other*
-[5] Copy Constructor -The `sampler` object to copy into the new `sampler` instance. - -[6] Move Constructor -The `sampler` object to move into the new `sampler` instance. - -## address_mode - -Gets the address mode of the `sampler` object. - -```cpp -__declspec(property(get= get_address_mode)) Concurrency::graphics::address_mode address_mode; -``` - -## border_color - -Gets the border color of the `sampler` object. - -```cpp -__declspec(property(get= get_border_color)) Concurrency::graphics::float_4 border_color; -``` - -## filter_mode - -Gets the filter mode of the `sampler` object. - -```cpp -__declspec(property(get= get_filter_mode)) Concurrency::graphics::filter_mode filter_mode; -``` - -## get_address_mode - -Returns the filter mode that’s configured for this `sampler`. - -```cpp -Concurrency::graphics::address_mode get_address_mode() const __GPU; -``` - -### Return Value - -The address mode that’s configured for the sampler. - -## get_border_color - -Returns the border color that’s configured for this `sampler`. - -```cpp -Concurrency::graphics::float_4 get_border_color() const restrict(amp, cpu); -``` - -### Return Value - -A float_4 that contains the border color. - -## get_filter_mode - -Returns the filter mode that’s configured for this `sampler`. - -```cpp -Concurrency::graphics::filter_mode get_filter_mode() const restrict(amp, cpu); -``` - -### Return Value - -The filter mode that’s configured for the sampler. - -## operator= - -Assigns the value of another sampler object to an existing sampler. - -```cpp -sampler& operator= ( // [1] copy assignment operator - const sampler& _Other) restrict(amp, cpu); - -sampler& operator= ( // [2] move assignment operator - sampler&& _Other) restrict(amp, cpu); -``` - -### Parameters - -*_Other*
-[1] Copy Assignment Operator -The `sampler` object to copy into this `sampler`. - -[2] Move Assignment Operator -The `sampler` object to move into this `sampler`. - -### Return Value - -A reference to this sampler instance. - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/scoped-d3d-access-lock-class.md b/docs/parallel/amp/reference/scoped-d3d-access-lock-class.md deleted file mode 100644 index 8a6888a479a..00000000000 --- a/docs/parallel/amp/reference/scoped-d3d-access-lock-class.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -description: "Learn more about: scoped_d3d_access_lock Class" -title: "scoped_d3d_access_lock Class" -ms.date: "11/04/2016" -f1_keywords: ["scoped_d3d_access_lock", "AMPRT/scoped_d3d_access_lock", "AMPRT/concurrency::direct3d::scoped_d3d_access_lock::scoped_d3d_access_lock"] -ms.assetid: 0ad333e6-9839-4736-a722-16d95d70c4b1 ---- -# scoped_d3d_access_lock Class - -RAII wrapper for a D3D access lock on an accelerator_view object. - -## Syntax - -```cpp -class scoped_d3d_access_lock; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[scoped_d3d_access_lock Constructor](#ctor)|Overloaded. Constructs a `scoped_d3d_access_lock` object. The lock is released when this object goes out of scope.| -|[~scoped_d3d_access_lock Destructor](#dtor)|Releases the D3D access lock on the associated `accelerator_view` object.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator=](#operator_eq)|Takes ownership of a lock from another `scoped_d3d_access_lock`.| - -## Inheritance Hierarchy - -`scoped_d3d_access_lock` - -## Requirements - -**Header:** amprt.h - -**Namespace:** concurrency::direct3d - -## scoped_d3d_access_lock - -Constructs a `scoped_d3d_access_lock` object. The lock is released when this object goes out of scope. - -```cpp -explicit scoped_d3d_access_lock(// [1] constructor - accelerator_view& _Av); - -explicit scoped_d3d_access_lock(// [2] constructor - accelerator_view& _Av, - adopt_d3d_access_lock_t _T); - -scoped_d3d_access_lock(// [3] move constructor - scoped_d3d_access_lock&& _Other); -``` - -### Parameters - -*_Av*
-The `accelerator_view` for the lock to adopt. - -*_T*
-The `adopt_d3d_access_lock_t` object. - -*_Other*
-The `scoped_d3d_access_lock` object from which to move an existing lock. - -## Construction - -[1] Constructor -Acquires a D3D access lock on the given [accelerator_view](accelerator-view-class.md) object. Construction blocks until the lock is acquired. - -[2] Constructor -Adopt a D3D access lock from the given [accelerator_view](accelerator-view-class.md) object. - -[3] Move Constructor -Takes an existing D3D access lock from another `scoped_d3d_access_lock` object. Construction does not block. - -## ~scoped_d3d_access_lock - -Releases the D3D access lock on the associated `accelerator_view` object. - -```cpp -~scoped_d3d_access_lock(); -``` - -## operator= - -Takes ownership of a D3D access lock from another `scoped_d3d_access_lock` object, releasing the previous lock. - -```cpp -scoped_d3d_access_lock& operator= (scoped_d3d_access_lock&& _Other); -``` - -### Parameters - -*_Other*
-The accelerator_view from which to move the D3D access lock. - -### Return Value - -A reference to this `scoped_accelerator_view_lock`. - -## See also - -[Concurrency::direct3d Namespace](concurrency-direct3d-namespace.md) diff --git a/docs/parallel/amp/reference/short-vector-structure.md b/docs/parallel/amp/reference/short-vector-structure.md deleted file mode 100644 index f35a36cbd38..00000000000 --- a/docs/parallel/amp/reference/short-vector-structure.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -description: "Learn more about: short_vector Structure" -title: "short_vector Structure" -ms.date: "11/04/2016" -f1_keywords: ["short_vector", "AMP_SHORT_VECTORS/short_vector", "AMP_SHORT_VECTORS/Concurrency::graphics::short_vector::short_vector Constructor"] -ms.assetid: e4f50b8f-1150-437d-b58c-79c5fb883708 ---- -# short_vector Structure - -short_vector provides metaprogramming definitions which are useful for programming short vectors generically. - -## Syntax - -```cpp -template< - typename _Scalar_type, - int _Size -> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -template<> -struct short_vector; -``` - -### Parameters - -*_Scalar_type*
- -*_Size*
- -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[short_vector::short_vector Constructor](#ctor)|| - -## Inheritance Hierarchy - -`short_vector` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## short_vector::short_vector Constructor - -```cpp -short_vector(); -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/short-vector-traits-structure.md b/docs/parallel/amp/reference/short-vector-traits-structure.md deleted file mode 100644 index 671761e5cdf..00000000000 --- a/docs/parallel/amp/reference/short-vector-traits-structure.md +++ /dev/null @@ -1,117 +0,0 @@ ---- -description: "Learn more about: short_vector_traits Structure" -title: "short_vector_traits Structure" -ms.date: "11/04/2016" -f1_keywords: ["short_vector_traits", "AMP_SHORT_VECTORS/short_vector_traits", "AMP_SHORT_VECTORS/Concurrency::graphics::short_vector_traits::short_vector_traits", "AMP_SHORT_VECTORS/Concurrency::graphics::short_vector_traits::size Constant"] -ms.assetid: cd9492da-9e02-4a6e-9d50-b61252cdb460 ---- -# short_vector_traits Structure - -short_vector_traits allows retrieval of the underlying vector length and scalar type of a short vector type or a scalar type - -## Syntax - -```cpp -template< - typename T -> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -template<> -struct short_vector_traits; -``` - -### Parameters - -`T` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[short_vector_traits::short_vector_traits Constructor](#ctor)|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[short_vector_traits::size Constant](#size)|| - -## Inheritance Hierarchy - -`short_vector_traits` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## short_vector_traits::short_vector_traits Constructor - -```cpp -short_vector_traits(); -``` - -## short_vector_traits::size Constant - -```cpp -static int const size = 1; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/texture-class.md b/docs/parallel/amp/reference/texture-class.md deleted file mode 100644 index f99e078681b..00000000000 --- a/docs/parallel/amp/reference/texture-class.md +++ /dev/null @@ -1,580 +0,0 @@ ---- -description: "Learn more about: texture Class" -title: "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. - -## Syntax - -```cpp -template -class texture; -``` - -### Parameters - -*value_type*
-The type of the elements in the texture. - -*_Rank*
-The rank of the texture. - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`scalar_type`|Scalar types.| -|`value_type`|Value types.| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[texture Constructor](#ctor)|Initializes a new instance of the `texture` class.| -|[~texture Destructor](#ctor)|Destroys the `texture` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[copy_to](#copy_to)|Copies the `texture` object to the destination, by doing a deep copy.| -|[data](#data)|Returns a CPU pointer to the raw data of this texture.| -|[get](#get)|Returns the value of the element at the specified index.| -|[get_associated_accelerator_view](#get_associated_accelerator_view)|Returns the [accelerator_view](accelerator-view-class.md) that is the preferred target for this texture to be copied to.| -|[get_depth_pitch](#get_depth_pitch)|Returns the number of bytes between each depth slice in a 3D staging texture on the CPU.| -|[get_row_pitch](#get_row_pitch)|Returns the number of bytes between each row in a 2D or 3D staging texture on the CPU.| -|[set](#set)|Sets the value of the element at the specified index.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator()](#operator_call)|Returns the element value that is specified by the parameters.| -|[operator\[\]](#operator_at)|Returns the element that is at the specified index.| -|[operator=](#operator_eq)|Copies the specified [texture](texture-class.md) object to this one.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[rank Constant](#rank)|Gets the rank of the `texture` object.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[associated_accelerator_view](#associated_accelerator_view)|Gets the [accelerator_view](accelerator-view-class.md) that is the preferred target for this texture to be copied to.| -|[depth_pitch](#depth_pitch)|Gets the number of bytes between each depth slice in a 3D staging texture on the CPU.| -|[row_pitch](#row_pitch)|Gets the number of bytes between each row in a 2D or 3D staging texture on the CPU.| - -## Inheritance Hierarchy - -`_Texture_base` - -`texture` - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** Concurrency::graphics - -## ~texture - -Destroys the `texture` object. - -```cpp -~texture() restrict(cpu); -``` - -## associated_accelerator_view - -Gets the [accelerator_view](accelerator-view-class.md) that is the preferred target for this texture to be copied to. - -```cpp -__declspec(property(get= get_associated_accelerator_view)) Concurrency::accelerator_view associated_accelerator_view; -``` - -## copy_to - -Copies the `texture` object to the destination, by doing a deep copy. - -```cpp -void copy_to(texture& _Dest) const; -void copy_to(writeonly_texture_view& _Dest) const; -``` - -### Parameters - -*_Dest*
-The object to copy to. - -*_Rank*
-The rank of the texture. - -*value_type*
-The type of the elements in the texture. - -## data - -Returns a CPU pointer to the raw data of this texture. - -```cpp -void* data() restrict(cpu); - -const void* data() const restrict(cpu); -``` - -### Return Value - -A pointer to the raw data of the texture. - -## depth_pitch - -Gets the number of bytes between each depth slice in a 3D staging texture on the CPU. - -```cpp -__declspec(property(get= get_depth_pitch)) unsigned int depth_pitch; -``` - -## get - -Returns the value of the element at the specified index. - -```cpp -const value_type get(const index<_Rank>& _Index) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index of the element. - -### Return Value - -The value of the element at the specified index. - -## get_associated_accelerator_view - -Returns the accelerator_view that is the preferred target for this texture to be copied to. - -```cpp -Concurrency::accelerator_view get_associated_accelerator_view() const restrict(cpu); -``` - -### Return Value - -The [accelerator_view](accelerator-view-class.md) that is the preferred target for this texture to be copied to. - -## get_depth_pitch - -Returns the number of bytes between each depth slice in a 3D staging texture on the CPU. - -```cpp -unsigned int get_depth_pitch() const restrict(cpu); -``` - -### Return Value - -The number of bytes between each depth slice in a 3D staging texture on the CPU. - -## get_row_pitch - -Returns the number of bytes between each row in a 2-dimensional staging texture, or between each row of a depth slice in 3-dimensional staging texture. - -```cpp -unsigned int get_row_pitch() const restrict(cpu); -``` - -### Return Value - -The number of bytes between each row in a 2-dimensional staging texture, or between each row of a depth slice in 3-dimensional staging texture. - -## operator() - -Returns the element value that is specified by the parameters. - -```cpp -const value_type operator() ( - const index<_Rank>& _Index) const restrict(amp); - -const value_type operator() ( - int _I0) const restrict(amp); - -const value_type operator() ( - int _I0, - int _I1) const restrict(amp); - -const value_type operator() ( - int _I0, - int _I1, - int _I2) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index. - -*_I0*
-The most-significant component of the index. - -*_I1*
-The next-to-most-significant component of the index. - -*_I2*
-The least-significant component of the index. - -*_Rank*
-The rank of the index. - -### Return Value - -The element value that is specified by the parameters. - -## operator[] - -Returns the element that is at the specified index. - -```cpp -const value_type operator[] (const index<_Rank>& _Index) const restrict(amp); - -const value_type operator[] (int _I0) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index. - -*_I0*
-The index. - -### Return Value - -The element that is at the specified index. - -## operator= - -Copies the specified [texture](texture-class.md) object to this one. - -```cpp -texture& operator= ( - const texture& _Other); - -texture& operator= ( - texture&& _Other); -``` - -### Parameters - -*_Other*
-The `texture` object to copy from. - -### Return Value - -A reference to this `texture` object. - -## rank - -Gets the rank of the `texture` object. - -```cpp -static const int rank = _Rank; -``` - -## row_pitch - -Gets the number of bytes between each row in a 2D or 3D staging texture on the CPU. - -```cpp -__declspec(property(get= get_row_pitch)) unsigned int row_pitch; -``` - -## set - -Sets the value of the element at the specified index. - -```cpp -void set( - const index<_Rank>& _Index, - const value_type& value) restrict(amp); -``` - -### Parameters - -*_Index*
-The index of the element. - -*_Rank*
-The rank of the index. - -*value*
-The new value of the element. - -## texture - -Initializes a new instance of the `texture` class. - -```cpp -texture(const Concurrency::extent<_Rank>& _Ext) restrict(cpu); - -texture(int _E0) restrict(cpu); - -texture(int _E0, int _E1) restrict(cpu); - -texture(int _E0, int _E1, int _E2) restrict(cpu); - -texture( - const Concurrency::extent<_Rank>& _Ext, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - int _E0, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - int _E0, - int _E1, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - int _E0, - int _E1, - int _E2, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -template -texture( - const Concurrency::extent<_Rank>& _Ext, - _Input_iterator _Src_first, - _Input_iterator _Src_last) restrict(cpu); - -template -texture( - int _E0, _Input_iterator _Src_first, _Input_iterator _Src_last) restrict(cpu); - -template -texture( - int _E0, - int _E1, - _Input_iterator _Src_first, - _Input_iterator _Src_last) restrict(cpu); - -template -texture( - int _E0, - int _E1, - int _E2, - _Input_iterator _Src_first, - _Input_iterator _Src_last) restrict(cpu); - -template -texture( - const Concurrency::extent<_Rank>& _Ext, - _Input_iterator _Src_first, - _Input_iterator _Src_last, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -template -texture( - int _E0, - _Input_iterator _Src_first, - _Input_iterator _Src_last, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -template -texture( - int _E0, - int _E1, - _Input_iterator _Src_first, - _Input_iterator _Src_last, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -template -texture( - int _E0, - int _E1, - int _E2, - _Input_iterator _Src_first, - _Input_iterator _Src_last, - const Concurrency::accelerator_view& _Av) restrict(cpu)) ; - -texture( - int _E0, - unsigned int _Bits_per_scalar_element) restrict(cpu); - -texture( - int _E0, - int _E1, - unsigned int _Bits_per_scalar_element) restrict(cpu); - -texture( - int _E0, - int _E1, - int _E2, - unsigned int _Bits_per_scalar_element) restrict(cpu); - -texture( - const Concurrency::extent<_Rank>& _Ext, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - int _E0, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) ; - -texture( - int _E0, - int _E1, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - int _E0, - int _E1, - int _E2, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - const Concurrency::extent<_Rank>& _Ext, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element) restrict(cpu); - -texture( - int _E0, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element) restrict(cpu); - -texture( - int _E0, - int _E1, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element) restrict(cpu); - -texture( - int _E0, - int _E1, - int _E2, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element) restrict(cpu); - -texture( - const Concurrency::extent<_Rank>& _Ext, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) ; - -texture( - int _E0, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - int _E0, - int _E1, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - int _E0, - int _E1, - int _E2, - _In_ void* _Source, - unsigned int _Src_byte_size, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av) restrict(cpu); - -texture( - const texture& _Src, - const Concurrency::accelerator_view& _Acc_view); - -texture( - texture&& _Other); - -texture( - const Concurrency::extent<_Rank>& _Ext, - unsigned int _Bits_per_scalar_element, - const Concurrency::accelerator_view& _Av); - -texture( - const texture& _Src); -``` - -### Parameters - -*_Acc_view*
-The [accelerator_view](accelerator-view-class.md) that specifies the location of the texture. - -*_Av*
-The [accelerator_view](accelerator-view-class.md) that specifies the location of the texture. - -*_Associated_av*
-An accelerator_view that specifies the preferred target for copies to or from this texture. - -*_Bits_per_scalar_element*
-The number of bits per each scalar element in the underlying scalar type of the texture. In general, supported value are 8, 16, 32, and 64. If 0 is specified, the number of bits is the same as the underlying scalar_type. 64 is only valid for double-based textures. - -*_Ext*
-The extent in each dimension of the texture. - -*_E0*
-The most significant component of the texture. - -*_E1*
-The next-to-most-significant component of the texture. - -*_E2*
-The least significant component of the extent of the texture. - -*_Input_iterator*
-The type of the input iterator. - -*_Mipmap_levels*
-The number of mipmap levels in the underlying texture. If 0 is specified, the texture will have the full range of mipmap levels down to the smallest possible size for the specified extent. - -*_Rank*
-The rank of the extent. - -*_Source*
-A pointer to a host buffer. - -*_Src*
-To texture to copy. - -*_Src_byte_size*
-The number of bytes in the source buffer. - -*_Src_first*
-A beginning iterator into the source container. - -*_Src_last*
-An ending iterator into the source container. - -*_Other*
-Other data source. - -*_Rank*
-The rank of the section. - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/texture-view-class.md b/docs/parallel/amp/reference/texture-view-class.md deleted file mode 100644 index 610f6fedf52..00000000000 --- a/docs/parallel/amp/reference/texture-view-class.md +++ /dev/null @@ -1,479 +0,0 @@ ---- -description: "Learn more about: texture_view Class" -title: "texture_view Class" -ms.date: "11/04/2016" -f1_keywords: ["texture_view", "AMP_GRAPHICS/texture_view", "AMP_GRAPHICS/Concurrency::graphics::texture_view::texture_view", "AMP_GRAPHICS/Concurrency::graphics::texture_view::gather_alpha", "AMP_GRAPHICS/Concurrency::graphics::texture_view::gather_blue", "AMP_GRAPHICS/Concurrency::graphics::texture_view::gather_green", "AMP_GRAPHICS/Concurrency::graphics::texture_view::gather_red", "AMP_GRAPHICS/Concurrency::graphics::texture_view::get", "AMP_GRAPHICS/Concurrency::graphics::texture_view::sample", "AMP_GRAPHICS/Concurrency::graphics::texture_view::set", "AMP_GRAPHICS/Concurrency::graphics::texture_view::value_type"] -ms.assetid: 6ec2e289-1626-4727-9592-07981cf1d27d ---- -# texture_view Class - -Provides read access and write access to a texture. `texture_view` can only be used to read textures whose value type is **`int`**, **`unsigned int`**, or **`float`** that have default 32-bit bpse. To read other texture formats, use `texture_view`. - -## Syntax - -```cpp -template -class texture_view; - -template -class texture_view - : public details::_Texture_base; - -template -class texture_view - : public details::_Texture_base; -``` - -### Parameters - -*value_type*
-The type of the elements in the texture aggregate. - -*_Rank*
-The rank of the `texture_view`. - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`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.| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[texture_view Constructor](#ctor)|Overloaded. Constructs a `texture_view` instance.| -|[~texture_view Destructor](#ctor)|Destroys the `texture_view` instance.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[gather_alpha](#gather_alpha)|Overloaded. Samples the texture at the specified coordinates by using the specified sampling configuration and returns the alpha (w) components of the four sampled texels.| -|[gather_blue](#gather_blue)|Overloaded. Samples the texture at the specified coordinates by using the specified sampling configuration and returns the blue (z) components of the four sampled texels.| -|[gather_green](#gather_green)|Overloaded. Samples the texture at the specified coordinates by using the specified sampling configuration and returns the green (y) components of the four sampled texels.| -|[gather_red](#gather_red)|Overloaded. Samples the texture at the specified coordinates by using the specified sampling configuration and returns the red (x) components of the four sampled texels.| -|[get](#get)|Overloaded. Gets the element value by index.| -|[sample](#sample)|Overloaded. Samples the texture at the specified coordinates and level of detail by using the specified sampling configuration.| -|[set](#set)|Sets the value of an element by index.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator()](#operator_call)|Overloaded. Gets the element value by index.| -|[operator\[\]](#operator_at)|Overloaded. Gets the element value by index.| -|[operator=](#operator_eq)|Overloaded. Assignment operator.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[value_type](#value_type)|The value type of the elements of the `texture_view`.| - -## Inheritance Hierarchy - -`_Texture_base` - -`texture_view` - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** concurrency::graphics - -## ~texture_view - -Destroys the `texture_view` instance. - -```cpp -~texture_view() restrict(amp, cpu); -``` - -## texture_view - -Constructs a `texture_view` instance. - -```cpp -texture_view(// [1] constructor - texture& _Src) restrict(amp); - -texture_view(// [2] constructor - texture& _Src, - unsigned int _Mipmap_level = 0) restrict(cpu); - -texture_view(// [3] constructor - const texture& _Src) restrict(amp); - -texture_view(// [4] constructor - const texture& _Src, - unsigned int _Most_detailed_mip, - unsigned int _Mip_levels) restrict(cpu); - -texture_view(// [5] copy constructor - const texture_view& _Other) restrict(amp, cpu); - -texture_view(// [6] copy constructor - const texture_view& _Other) restrict(amp, cpu); - -texture_view(// [7] copy constructor - const texture_view& _Other, - unsigned int _Most_detailed_mip, - unsigned int _Mip_levels) restrict(cpu); -``` - -### Parameters - -*_Src*
-[1, 2] Constructor -The `texture` on which the writable `texture_view` is created. - -[3, 4] Constructor -The `texture` on which the non-writable `texture_view` is created. - -*_Other*
-[5] Copy Constructor -The source writable `texture_view`. - -[6, 7] Copy Constructor -The source non-writable `texture_view`. - -*_Mipmap_level*
-The specific mipmap level on the source `texture` that this writeable `texture_view` binds to. The default value is 0, which represents the top level (most detailed) mip level. - -*_Most_detailed_mip*
-Top level (most detailed) mip level for the view, relative to the specified `texture_view` object. - -*_Mip_levels*
-The number of mipmap levels accessible through the `texture_view`. - -## gather_red - -Samples the texture at the specified coordinates by using the specified sampling configuration and returns the red (x) components of the four sampled texels. - -```cpp -const gather_return_type gather_red( - const sampler& _Sampler, - const coordinates_type& _Coord) const restrict(amp); - -template< - address_mode _Address_mode = address_clamp -> -const gather_return_type gather_red( - const coordinates_type& _Coord) const restrict(amp); -``` - -### Parameters - -*_Address_mode*
-The address mode to use to sample the `texture_view`. The address mode is the same for all dimensions. - -*_Sampler*
-The sampler configuration to use to sample the `texture_view`. - -*_Coord*
-The coordinates to take the sample from. Fractional coordinate values are used to interpolate between sample texels. - -### Return Value - -A rank 4 short vector containing the red (x) component of the 4 sampled texel values. - -## gather_green - -Samples the texture at the specified coordinates by using the specified sampling configuration and returns the green (y) components of the four sampled texels. - -```cpp -const gather_return_type gather_green( - const sampler& _Sampler, - const coordinates_type& _Coord) const restrict(amp); - -template< - address_mode _Address_mode = address_clamp -> -const gather_return_type gather_green( - const coordinates_type& _Coord) const restrict(amp); -``` - -### Parameters - -*_Address_mode*
-The address mode to use to sample the `texture_view`. The address mode is the same for all dimensions. - -*_Sampler*
-The sampler configuration to use to sample the `texture_view`. - -*_Coord*
-The coordinates to take the sample from. Fractional coordinate values are used to interpolate between sample texels. - -### Return Value - -A rank 4 short vector containing the green (y) component of the 4 sampled texel values. - -## gather_blue - -Samples the texture at the specified coordinates by using the specified sampling configuration and returns the blue (z) components of the four sampled texels. - -```cpp -const gather_return_type gather_blue( - const sampler& _Sampler, - const coordinates_type& _Coord) const restrict(amp); - -template< - address_mode _Address_mode = address_clamp -> -const gather_return_type gather_blue( - const coordinates_type& _Coord) const restrict(amp); -``` - -### Parameters - -*_Address_mode*
-The address mode to use to sample the `texture_view`. The address mode is the same for all dimensions. - -*_Sampler*
-The sampler configuration to use to sample the `texture_view`. - -*_Coord*
-The coordinates to take the sample from. Fractional coordinate values are used to interpolate between sample texels. - -### Return Value - -A rank 4 short vector containing the red (x) component of the 4 sampled texel values. - -## gather_alpha - -Samples the texture at the specified coordinates by using the specified sampling configuration and returns the alpha (w) components of the four sampled texels. - -```cpp -const gather_return_type gather_alpha( - const sampler& _Sampler, - const coordinates_type& _Coord) const restrict(amp); - -template< - address_mode _Address_mode = address_clamp -> -const gather_return_type gather_alpha( - const coordinates_type& _Coord) const restrict(amp); -``` - -### Parameters - -*_Address_mode*
-The address mode to use to sample the `texture_view`. The address mode is the same for all dimensions. - -*_Sampler*
-The sampler configuration to use to sample the `texture_view`. - -*_Coord*
-The coordinates to take the sample from. Fractional coordinate values are used to interpolate between sample texels. - -### Return Value - -A rank 4 short vector containing the alpha (w) component of the 4 sampled texel values. - -## get - -Gets the value of the element at the specified index. - -```cpp -const value_type get( - const index<_Rank>& _Index) const restrict(amp); - -value_type get( - const index<_Rank>& _Index, - unsigned int _Mip_level = 0) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index of the element to get, possibly multi-dimensional. - -*_Mip_level*
-The mipmap level from which we should get the value. The default value 0 represents the most detailed mipmap level. - -### Return Value - -The value of the element. - -## operator= - -Assigns a view of the same texture as the specified `texture_view` to this `texture_view` instance. - -```cpp -texture_view& operator= (// [1] copy constructor - const texture_view& _Other) restrict(amp, cpu); - -texture_view& operator= (// [2] copy constructor - const texture_view& _Other) restrict(cpu); - -texture_view& operator= (// [3] copy constructor - const texture_view& _Other) restrict(amp, cpu); -``` - -### Parameters - -*_Other*
-[1, 2] Copy Constructor -A writable `texture_view` object. - -[3] Copy Constructor -A non-writable `texture_view` object. - -### Return Value - -A reference to this `texture_view` instance. - -## operator[] - -Returns the element value by index. - -```cpp -const value_type operator[] (const index<_Rank>& _Index) const restrict(amp); - -const value_type operator[] (int _I0) const restrict(amp); - -value_type operator[] (const index<_Rank>& _Index) const restrict(amp); - -value_type operator[] (int _I0) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index, possibly multi-dimensional. - -*_I0*
-The one-dimensional index. - -### Return Value - -The element value indexed by `_Index`. - -## operator() - -Returns the element value by index. - -```cpp -const value_type operator() ( - const index<_Rank>& _Index) const restrict(amp); - -const value_type operator() ( - int _I0) const restrict(amp); - -const value_type operator() ( - int _I0, int _I1) const restrict(amp); - -const value_type operator() ( - int _I0, - int _I1, - int _I2) const restrict(amp); - -value_type operator() ( - const index<_Rank>& _Index) const restrict(amp); - -value_type operator() ( - int _I0) const restrict(amp); - -value_type operator() ( - int _I0, - int _I1) const restrict(amp); - -value_type operator() ( - int _I0, - int _I1, - int _I2) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index, possibly multi-dimensional. - -*_I0*
-The most-significant component of the index. - -*_I1*
-The next-to-most-significant component of the index. - -*_I2*
-The least-significant component of the index. - -### Return Value - -The element value indexed by `_Index`. - -## sample - -Samples the texture at the specified coordinates and level of detail by using the specified sampling configuration. - -```cpp -value_type sample( - const sampler& _Sampler, - const coordinates_type& _Coord, - float _Level_of_detail = 0.0f) const restrict(amp); - -template< - filter_mode _Filter_mode = filter_linear, - address_mode _Address_mode = address_clamp -> -value_type sample( - const coordinates_type& _Coord, - float _Level_of_detail = 0.0f) const restrict(amp); -``` - -### Parameters - -*_Filter_mode*
-The filter mode to use to sample the texture_view. The filter mode is the same for the minimization, maximization, and mipmap filters. - -*_Address_mode*
-The address mode to use to sample the texture_view. The address mode is the same for all dimensions. - -*_Sampler*
-The sampler configuration to use to sample the texture_view. - -*_Coord*
-The coordinates to take the sample from. Fractional coordinate values are used to interpolate between texel values. - -*_Level_of_detail*
-The value specifies the mipmap level to sample from. Fractional values are used to interpolate between two mipmap levels. The default level of detail is 0, which represents the most detailed mip level. - -### Return Value - -The interpolated sample value. - -## set - -Sets the value of the element at the specified index to the specified value. - -```cpp -void set( - const index<_Rank>& _Index, - const value_type& value) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index of the element to set, possibly multi-dimensional. - -*value*
-The value to set the element to. - -## value_type - -The value type of the elements of the texture_view. - -```cpp -typedef typename const value_type value_type; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/tile-barrier-class.md b/docs/parallel/amp/reference/tile-barrier-class.md deleted file mode 100644 index 95119110e9a..00000000000 --- a/docs/parallel/amp/reference/tile-barrier-class.md +++ /dev/null @@ -1,104 +0,0 @@ ---- -description: "Learn more about: tile_barrier Class" -title: "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 - -Synchronizes the execution of threads that are running in the thread group (the tile) by using `wait` methods. Only the runtime can instantiate this class. - -## Syntax - -```cpp -class tile_barrier; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[tile_barrier Constructor](#ctor)|Initializes a new instance of the `tile_barrier` class.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[wait](#wait)|Instructs all threads in the thread group (tile) to stop executing until all threads in the tile have finished waiting.| -|[wait_with_all_memory_fence](#wait_with_all_memory_fence)|Blocks execution of all threads in a tile until all memory accesses have been completed and all threads in the tile have reached this call.| -|[wait_with_global_memory_fence](#wait_with_global_memory_fence)|Blocks execution of all threads in a tile until all global memory accesses have been completed and all threads in the tile have reached this call.| -|[wait_with_tile_static_memory_fence](#wait_with_tile_static_memory_fence)|Blocks execution of all threads in a tile until all `tile_static` memory accesses have been completed and all threads in the tile have reached this call.| - -## Inheritance Hierarchy - -`tile_barrier` - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## tile_barrier Constructor - -Initializes a new instance of the class by copying an existing one. - -### Syntax - -```cpp -tile_barrier( - const tile_barrier& _Other ) restrict(amp,cpu); -``` - -### Parameters - -*_Other*
-The `tile_barrier` object to copy. - -## wait - -Instructs all threads in the thread group (tile) to stop execution until all threads in the tile have finished waiting. - -### Syntax - -```cpp -void wait() const restrict(amp); -``` - -## wait_with_all_memory_fence - -Blocks execution of all threads in a tile until all threads in a tile have reached this call. This ensures that all memory accesses are visible to other threads in the thread tile, and have been executed in program order. - -### Syntax - -```cpp -void wait_with_all_memory_fence() const restrict(amp); -``` - -## 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. - -### Syntax - -```cpp -void wait_with_global_memory_fence() const restrict(amp); -``` - -## 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. - -### Syntax - -```cpp -void wait_with_tile_static_memory_fence() const restrict(amp); -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/tiled-extent-class.md b/docs/parallel/amp/reference/tiled-extent-class.md deleted file mode 100644 index ba3df5b31f3..00000000000 --- a/docs/parallel/amp/reference/tiled-extent-class.md +++ /dev/null @@ -1,218 +0,0 @@ ---- -description: "Learn more about: tiled_extent Class" -title: "tiled_extent Class" -ms.date: "11/04/2016" -f1_keywords: ["tiled_extent", "AMP/tiled_extent", "AMP/Concurrency::tiled_extent::tiled_extent", "AMP/Concurrency::tiled_extent::get_tile_extent", "AMP/Concurrency::tiled_extent::pad", "AMP/Concurrency::tiled_extent::truncate", "AMP/Concurrency::tiled_extent::tile_dim0", "AMP/Concurrency::tiled_extent::tile_dim1", "AMP/Concurrency::tiled_extent::tile_dim2", "AMP/Concurrency::tiled_extent::tile_extent"] -ms.assetid: 671ecaf8-c7b0-4ac8-bbdc-e30bd92da7c0 ---- -# tiled_extent Class - -A `tiled_extent` object is an `extent` object of one to three dimensions that subdivides the extent space into one-, two-, or three-dimensional tiles. - -## Syntax - -```cpp -template < - int _Dim0, - int _Dim1, - int _Dim2 -> -class tiled_extent : public Concurrency::extent<3>; - -template < - int _Dim0, - int _Dim1 -> -class tiled_extent<_Dim0, _Dim1, 0> : public Concurrency::extent<2>; - -template < - int _Dim0 -> -class tiled_extent<_Dim0, 0, 0> : public Concurrency::extent<1>; -``` - -### Parameters - -*_Dim0*
-The length of the most significant dimension. - -*_Dim1*
-The length of the next-to-most significant dimension. - -*_Dim2*
-The length of the least significant dimension. - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[tiled_extent Constructor](#ctor)|Initializes a new instance of the `tiled_extent` class.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[get_tile_extent](#get_tile_extent)|Returns an `extent` object that captures the values of the `tiled_extent` template arguments `_Dim0`, `_Dim1`, and `_Dim2`.| -|[pad](#pad)|Returns a new `tiled_extent` object with extents adjusted up to be evenly divisible by the tile dimensions.| -|[truncate](#truncate)|Returns a new `tiled_extent` object with extents adjusted down to be evenly divisible by the tile dimensions.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator=](#operator_eq)|Copies the contents of the specified `tiled_index` object into this one.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[tile_dim0 Constant](#tile_dim0)|Stores the length of the most significant dimension.| -|[tile_dim1 Constant](#tile_dim1)|Stores the length of the next-to-most significant dimension.| -|[tile_dim2 Constant](#tile_dim2)|Stores the length of the least significant dimension.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[tile_extent](#tile_extent)|Gets an `extent` object that captures the values of the `tiled_extent` template arguments `_Dim0`, `_Dim1`, and `_Dim2`.| - -## Inheritance Hierarchy - -`extent` - -`tiled_extent` - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## tiled_extent Constructor - -Initializes a new instance of the `tiled_extent` class. - -### Syntax - -```cpp -tiled_extent(); - -tiled_extent( - const Concurrency::extent& _Other ); - -tiled_extent( - const tiled_extent& _Other ); -``` - -### Parameters - -*_Other*
-The `extent` or `tiled_extent` object to copy. - -## get_tile_extent - -Returns an `extent` object that captures the values of the `tiled_extent` template arguments `_Dim0`, `_Dim1`, and `_Dim2`. - -### Syntax - -```cpp -Concurrency::extent get_tile_extent() const restrict(amp,cpu); -``` - -### Return Value - -An `extent` object that captures the dimensions of this `tiled_extent` instance. - -## pad - -Returns a new `tiled_extent` object with extents adjusted up to be evenly divisible by the tile dimensions. - -### Syntax - -```cpp -tiled_extent pad() const; -``` - -### Return Value - -The new `tiled_extent` object, by value. - -## truncate - -Returns a new `tiled_extent` object with extents adjusted down to be evenly divisible by the tile dimensions. - -### Syntax - -```cpp -tiled_extent truncate() const; -``` - -### Return Value - -Returns a new `tiled_extent` object with extents adjusted down to be evenly divisible by the tile dimensions. - -## operator= - -Copies the contents of the specified `tiled_index` object into this one. - -### Syntax - -```cpp -tiled_extent& operator= ( - const tiled_extent& _Other ) restrict (amp, cpu); -``` - -### Parameters - -*_Other*
-The `tiled_index` object to copy from. - -### Return Value - -A reference to this `tiled_index` instance. - -## tile_dim0 - -Stores the length of the most significant dimension. - -### Syntax - -```cpp -static const int tile_dim0 = _Dim0; -``` - -## tile_dim1 - -Stores the length of the next-to-most significant dimension. - -### Syntax - -```cpp -static const int tile_dim1 = _Dim1; -``` - -## tile_dim2 - -Stores the length of the least significant dimension. - -### Syntax - -```cpp -static const int tile_dim2 = _Dim2; -``` - -## tile_extent - -Gets an `extent` object that captures the values of the `tiled_extent` template arguments `_Dim0`, `_Dim1`, and `_Dim2`. - -### Syntax - -```cpp -__declspec(property(get= get_tile_extent)) Concurrency::extent tile_extent; -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/tiled-index-class.md b/docs/parallel/amp/reference/tiled-index-class.md deleted file mode 100644 index 0ce0b17509e..00000000000 --- a/docs/parallel/amp/reference/tiled-index-class.md +++ /dev/null @@ -1,253 +0,0 @@ ---- -description: "Learn more about: tiled_index Class" -title: "tiled_index Class" -ms.date: "03/27/2019" -f1_keywords: ["tiled_index", "AMP/tiled_index", "AMP/Concurrency::tiled_index::tiled_index", "AMP/Concurrency::tiled_index::get_tile_extent", "AMP/Concurrency::tiled_index::barrier", "AMP/Concurrency::tiled_index::global", "AMP/Concurrency::tiled_index::local", "AMP/Concurrency::tiled_index::rank", "AMP/Concurrency::tiled_index::tile", "AMP/Concurrency::tiled_index::tile_dim0", "AMP/Concurrency::tiled_index::tile_dim1", "AMP/Concurrency::tiled_index::tile_dim2", "AMP/Concurrency::tiled_index::tile_origin", "AMP/Concurrency::tiled_index::tile_extent"] -helpviewer_keywords: ["tiled_index class"] -ms.assetid: 0ce2ae26-f1bb-4436-b473-a9e1b619bb38 ---- -# tiled_index Class - -Provides an index into a [tiled_extent](tiled-extent-class.md) object. This class has properties to access elements relative to the local tile origin and relative to the global origin. For more information about tiled spaces, see [Using Tiles](../../../parallel/amp/using-tiles.md). - -## Syntax - -```cpp -template < - int _Dim0, - int _Dim1 = 0, - int _Dim2 = 0 -> -class tiled_index : public _Tiled_index_base<3>; - -template < - int _Dim0, - int _Dim1 -> -class tiled_index<_Dim0, _Dim1, 0> : public _Tiled_index_base<2>; - -template < - int _Dim0 -> -class tiled_index<_Dim0, 0, 0> : public _Tiled_index_base<1>; -``` - -### Parameters - -*_Dim0*
-The length of the most significant dimension. - -*_Dim1*
-The length of the next-to-most significant dimension. - -*_Dim2*
-The length of the least significant dimension. - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[tiled_index Constructor](#ctor)|Initializes a new instance of the `tile_index` class.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[get_tile_extent](#tiled_index__get_tile_extent)|Returns an [extent](extent-class.md) object that has the values of the `tiled_index` template arguments `_Dim0`, `_Dim1`, and `_Dim2`.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[barrier Constant](#tiled_index__barrier)|Stores a [tile_barrier](tile-barrier-class.md) object that represents a barrier in the current tile of threads.| -|[global Constant](#tiled_index__global)|Stores an [index](index-class.md) object of rank 1, 2, or 3 that represents the global index in a grid object.| -|[local Constant](#tiled_index__local)|Stores an `index` object of rank 1, 2, or 3 that represents the relative index in the current tile of a [tiled_extent](tiled-extent-class.md) object.| -|[rank Constant](#tiled_index__rank)|Stores the rank of the `tiled_index` object.| -|[tile Constant](#tiled_index__tile)|Stores an `index` object of rank 1, 2, or 3 that represents the coordinates of the current tile of a `tiled_extent` object.| -|[tile_dim0 Constant](#tiled_index__tile_dim0)|Stores the length of the most significant dimension.| -|[tile_dim1 Constant](#tiled_index__tile_dim1)|Stores the length of the next-to-most significant dimension.| -|[tile_dim2 Constant](#tiled_index__tile_dim2)|Stores the length of the least significant dimension.| -|[tile_origin Constant](#tiled_index__tile_origin)|Stores an `index` object of rank 1, 2, or 3 that represents the global coordinates of the origin of the current tile in a `tiled_extent` object.| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|[tile_extent](#tile_extent)|Gets an [extent](extent-class.md) object that has the values of the `tiled_index` template arguments `tiled_index` template arguments `_Dim0`, `_Dim1`, and `_Dim2`.| - -## Inheritance Hierarchy - -`_Tiled_index_base` - -`tiled_index` - -## Requirements - -**Header:** amp.h - -**Namespace:** Concurrency - -## tiled_index Constructor - -Initializes a new instance of the `tiled_index` class. - -### Syntax - -```cpp -tiled_index( - const index& _Global, - const index& _Local, - const index& _Tile, - const index& _Tile_origin, - const tile_barrier& _Barrier ) restrict(amp,cpu); - -tiled_index( - const tiled_index& _Other ) restrict(amp,cpu); -``` - -### Parameters - -*_Global*
-The global [index](index-class.md) of the constructed `tiled_index`. - -*_Local*
-The local [index](index-class.md) of the constructed `tiled_index` - -*_Tile*
-The tile [index](index-class.md) of the constructed `tiled_index` - -*_Tile_origin*
-The tile origin [index](index-class.md) of the constructed `tiled_index` - -*_Barrier*
-The [tile_barrier](tile-barrier-class.md) object of the constructed `tiled_index`. - -*_Other*
-The `tile_index` object to be copied to the constructed `tiled_index`. - -### Overloads - -|Name|Description| -|-|-| -|`tiled_index(const index& _Global, const index& _Local, const index& _Tile, const index& _Tile_origin, const tile_barrier& _Barrier restrict(amp,cpu);`|Initializes a new instance of the `tile_index` class from the index of the tile in global coordinates and the relative position in the tile in local coordinates. The `_Global` and `_Tile_origin` parameters are computed.| -|`tiled_index( const tiled_index& _Other) restrict(amp,cpu);`|Initializes a new instance of the `tile_index` class by copying the specified `tiled_index` object.| - -## get_tile_extent - -Returns an [extent](extent-class.md) object that has the values of the `tiled_index` template arguments `_Dim0`, `_Dim1`, and `_Dim2`. - -### Syntax - -```cpp -extent get_tile_extent()restrict(amp,cpu); -``` - -### Return Value - -An `extent` object that has the values of the `tiled_index` template arguments `_Dim0`, `_Dim1`, and `_Dim2`. - -## barrier - -Stores a [tile_barrier](tile-barrier-class.md) object that represents a barrier in the current tile of threads. - -### Syntax - -```cpp -const tile_barrier barrier; -``` - -## global - -Stores an [index](index-class.md) object of rank 1, 2, or 3 that represents the global index of an object. - -### Syntax - -```cpp -const index global; -``` - -## local - -Stores an [index](index-class.md) object of rank 1, 2, or 3 that represents the relative index in the current tile of a [tiled_extent](tiled-extent-class.md) object. - -### Syntax - -```cpp -const index local; -``` - -## rank - -Stores the rank of the `tiled_index` object. - -### Syntax - -```cpp -static const int rank = _Rank; -``` - -## tile - -Stores an [index](index-class.md) object of rank 1, 2, or 3 that represents the coordinates of the current tile of a [tiled_extent](tiled-extent-class.md) object. - -### Syntax - -```cpp -const index tile; -``` - -## tile_dim0 - -Stores the length of the most significant dimension. - -### Syntax - -```cpp -static const int tile_dim0 = _Dim0; -``` - -## tile_dim1 - -Stores the length of the next-to-most significant dimension. - -### Syntax - -```cpp -static const int tile_dim1 = _Dim1; -``` - -## tile_dim2 - -Stores the length of the least significant dimension. - -### Syntax - -```cpp -static const int tile_dim2 = _Dim2; -``` - -## tile_origin - -Stores an [index](index-class.md) object of rank 1, 2, or 3 that represents the global coordinates of the origin of the current tile within a [tiled_extent](tiled-extent-class.md) object. - -### Syntax - -```cpp -const index tile_origin -``` - -## tile_extent - -Gets an [extent](extent-class.md) object that has the values of the `tiled_index` template arguments `tiled_index` template arguments `_Dim0`, `_Dim1`, and `_Dim2`. - -### Syntax - -```cpp -__declspec(property(get= get_tile_extent)) extent tile_extent; -``` - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/uint-2-class.md b/docs/parallel/amp/reference/uint-2-class.md deleted file mode 100644 index b94c30a56f3..00000000000 --- a/docs/parallel/amp/reference/uint-2-class.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -description: "Learn more about: uint_2 Class" -title: "uint_2 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::uint_2::set_xy", "amp_short_vectors/Concurrency::graphics::uint_2::y", "amp_short_vectors/Concurrency::graphics::uint_2::gr", "amp_short_vectors/Concurrency::graphics::uint_2::operator-", "amp_short_vectors/Concurrency::graphics::uint_2::get_x", "amp_short_vectors/Concurrency::graphics::uint_2::operator-=", "amp_short_vectors/Concurrency::graphics::uint_2::r", "amp_short_vectors/Concurrency::graphics::uint_2::yx", "amp_short_vectors/Concurrency::graphics::uint_2::operator--", "amp_short_vectors/Concurrency::graphics::uint_2::set_yx", "amp_short_vectors/Concurrency::graphics::uint_2::operator=", "amp_short_vectors/Concurrency::graphics::uint_2::set_x", "amp_short_vectors/Concurrency::graphics::uint_2::operator+=", "amp_short_vectors/Concurrency::graphics::uint_2::get_y", "amp_short_vectors/Concurrency::graphics::uint_2::xy", "amp_short_vectors/Concurrency::graphics::uint_2::x", "amp_short_vectors/Concurrency::graphics::uint_2::get_xy", "amp_short_vectors/Concurrency::graphics::uint_2::set_y", "amp_short_vectors/Concurrency::graphics::uint_2", "amp_short_vectors/Concurrency::graphics::uint_2::operator*=", "amp_short_vectors/Concurrency::graphics::uint_2::get_yx", "amp_short_vectors/Concurrency::graphics::uint_2::operator/=", "amp_short_vectors/Concurrency::graphics::uint_2::g", "amp_short_vectors/Concurrency::graphics::uint_2::operator++", "amp_short_vectors/Concurrency::graphics::uint_2::rg"] -ms.assetid: 9fcc9129-72b1-4da7-9012-4d3be15f1c52 ---- -# uint_2 Class - -Represents a short vector of two unsigned integers. - -## Syntax - -```cpp -class uint_2; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[uint_2 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|uint_2::get_x|| -|uint_2::get_xy|| -|uint_2::get_y|| -|uint_2::get_yx|| -|uint_2::ref_g_Method|| -|uint_2::ref_r_Method|| -|uint_2::ref_x_Method|| -|uint_2::ref_y_Method|| -|uint_2::set_x|| -|uint_2::set_xy|| -|uint_2::set_y|| -|uint_2::set_yx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|uint_2::operator--|| -|uint_2::operator%=|| -|uint_2::operator&=|| -|uint_2::operator*=|| -|uint_2::operator/=|| -|uint_2::operator^=|| -|uint_2::operator\|=|| -|uint_2::operator~|| -|uint_2::operator++|| -|uint_2::operator+=|| -|uint_2::operator<\<=|| -|uint_2::operator=|| -|uint_2::operator-=|| -|uint_2::operator>>=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#uint_2__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|uint_2::g|| -|uint_2::gr|| -|uint_2::r|| -|uint_2::rg|| -|uint_2::x|| -|uint_2::xy|| -|uint_2::y|| -|uint_2::yx|| - -## Inheritance Hierarchy - -`uint_2` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## uint_2 - -Default constructor, initializes all elements with 0. - -```cpp -uint_2() restrict(amp, - cpu); - -uint_2( - unsigned int _V0, - unsigned int _V1) restrict(amp, - cpu); - -uint_2( - unsigned int _V) restrict(amp, - cpu); - -uint_2( - const uint_2& _Other) restrict(amp, - cpu); - -explicit inline uint_2( - const int_2& _Other) restrict(amp, - cpu); - -explicit inline uint_2( - const float_2& _Other) restrict(amp, - cpu); - -explicit inline uint_2( - const unorm_2& _Other) restrict(amp, - cpu); - -explicit inline uint_2( - const norm_2& _Other) restrict(amp, - cpu); - -explicit inline uint_2( - const double_2& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 2; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/uint-3-class.md b/docs/parallel/amp/reference/uint-3-class.md deleted file mode 100644 index f6eba197139..00000000000 --- a/docs/parallel/amp/reference/uint-3-class.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -description: "Learn more about: uint_3 Class" -title: "uint_3 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::uint_3::get_xz", "amp_short_vectors/Concurrency::graphics::uint_3::set_yzx", "amp_short_vectors/Concurrency::graphics::uint_3::get_y", "amp_short_vectors/Concurrency::graphics::uint_3::get_yzx", "amp_short_vectors/Concurrency::graphics::uint_3::get_yz", "amp_short_vectors/Concurrency::graphics::uint_3::yzx", "amp_short_vectors/Concurrency::graphics::uint_3::get_z", "amp_short_vectors/Concurrency::graphics::uint_3::z", "amp_short_vectors/Concurrency::graphics::uint_3::xy", "amp_short_vectors/Concurrency::graphics::uint_3::gr", "amp_short_vectors/Concurrency::graphics::uint_3::operator=", "amp_short_vectors/Concurrency::graphics::uint_3::x", "amp_short_vectors/Concurrency::graphics::uint_3::gbr", "amp_short_vectors/Concurrency::graphics::uint_3::set_xy", "amp_short_vectors/Concurrency::graphics::uint_3::g", "amp_short_vectors/Concurrency::graphics::uint_3::set_yz", "amp_short_vectors/Concurrency::graphics::uint_3::br", "amp_short_vectors/Concurrency::graphics::uint_3::get_xyz", "amp_short_vectors/Concurrency::graphics::uint_3::b", "amp_short_vectors/Concurrency::graphics::uint_3::get_yxz", "amp_short_vectors/Concurrency::graphics::uint_3::set_zyx", "amp_short_vectors/Concurrency::graphics::uint_3::get_x", "amp_short_vectors/Concurrency::graphics::uint_3::rgb", "amp_short_vectors/Concurrency::graphics::uint_3::set_zy", "amp_short_vectors/Concurrency::graphics::uint_3::brg", "amp_short_vectors/Concurrency::graphics::uint_3::set_xyz", "amp_short_vectors/Concurrency::graphics::uint_3::xyz", "amp_short_vectors/Concurrency::graphics::uint_3::set_zxy", "amp_short_vectors/Concurrency::graphics::uint_3", "amp_short_vectors/Concurrency::graphics::uint_3::get_xy", "amp_short_vectors/Concurrency::graphics::uint_3::set_yx", "amp_short_vectors/Concurrency::graphics::uint_3::get_zyx", "amp_short_vectors/Concurrency::graphics::uint_3::get_zxy", "amp_short_vectors/Concurrency::graphics::uint_3::set_y", "amp_short_vectors/Concurrency::graphics::uint_3::yx", "amp_short_vectors/Concurrency::graphics::uint_3::grb", "amp_short_vectors/Concurrency::graphics::uint_3::operator+=", "amp_short_vectors/Concurrency::graphics::uint_3::set_x", "amp_short_vectors/Concurrency::graphics::uint_3::operator/=", "amp_short_vectors/Concurrency::graphics::uint_3::rbg", "amp_short_vectors/Concurrency::graphics::uint_3::set_zx", "amp_short_vectors/Concurrency::graphics::uint_3::set_z", "amp_short_vectors/Concurrency::graphics::uint_3::get_zx", "amp_short_vectors/Concurrency::graphics::uint_3::bgr", "amp_short_vectors/Concurrency::graphics::uint_3::get_xzy", "amp_short_vectors/Concurrency::graphics::uint_3::get_yx", "amp_short_vectors/Concurrency::graphics::uint_3::bg", "amp_short_vectors/Concurrency::graphics::uint_3::r", "amp_short_vectors/Concurrency::graphics::uint_3::xzy", "amp_short_vectors/Concurrency::graphics::uint_3::zyx", "amp_short_vectors/Concurrency::graphics::uint_3::set_xz", "amp_short_vectors/Concurrency::graphics::uint_3::rg", "amp_short_vectors/Concurrency::graphics::uint_3::zxy", "amp_short_vectors/Concurrency::graphics::uint_3::zy", "amp_short_vectors/Concurrency::graphics::uint_3::yz", "amp_short_vectors/Concurrency::graphics::uint_3::zx", "amp_short_vectors/Concurrency::graphics::uint_3::gb", "amp_short_vectors/Concurrency::graphics::uint_3::operator--", "amp_short_vectors/Concurrency::graphics::uint_3::set_yxz", "amp_short_vectors/Concurrency::graphics::uint_3::get_zy", "amp_short_vectors/Concurrency::graphics::uint_3::operator++", "amp_short_vectors/Concurrency::graphics::uint_3::operator-", "amp_short_vectors/Concurrency::graphics::uint_3::y", "amp_short_vectors/Concurrency::graphics::uint_3::xz", "amp_short_vectors/Concurrency::graphics::uint_3::rb", "amp_short_vectors/Concurrency::graphics::uint_3::operator*=", "amp_short_vectors/Concurrency::graphics::uint_3::yxz", "amp_short_vectors/Concurrency::graphics::uint_3::set_xzy", "amp_short_vectors/Concurrency::graphics::uint_3::operator-="] -ms.assetid: 5e22c277-9d4f-4a3a-b38c-a83d5fcab33c ---- -# uint_3 Class - -Represents a short vector of three unsigned integers. - -## Syntax - -```cpp -class uint_3; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[uint_3 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|uint_3::get_x|| -|uint_3::get_xy|| -|uint_3::get_xyz|| -|uint_3::get_xz|| -|uint_3::get_xzy|| -|uint_3::get_y|| -|uint_3::get_yx|| -|uint_3::get_yxz|| -|uint_3::get_yz|| -|uint_3::get_yzx|| -|uint_3::get_z|| -|uint_3::get_zx|| -|uint_3::get_zxy|| -|uint_3::get_zy|| -|uint_3::get_zyx|| -|uint_t::ref_b|| -|uint_t::ref_g|| -|uint_t::ref_r|| -|uint_t::ref_x|| -|uint_t::ref_y|| -|uint_t::ref_z|| -|uint_3::set_x|| -|uint_3::set_xy|| -|uint_3::set_xyz|| -|uint_3::set_xz|| -|uint_3::set_xzy|| -|uint_3::set_y|| -|uint_3::set_yx|| -|uint_3::set_yxz|| -|uint_3::set_yz|| -|uint_3::set_yzx|| -|uint_3::set_z|| -|uint_3::set_zx|| -|uint_3::set_zxy|| -|uint_3::set_zy|| -|uint_3::set_zyx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|uint_3::operator--|| -|uint_3::operator%=|| -|uint_3::operator&=|| -|uint_3::operator*=|| -|uint_3::operator/=|| -|uint_3::operator^=|| -|uint_3::operator\|=|| -|uint_3::operator~|| -|uint_3::operator++|| -|uint_3::operator+=|| -|uint_3::operator<\<=|| -|uint_3::operator=|| -|uint_3::operator-=|| -|uint_3::operator>>=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#uint_3__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|uint_3::b|| -|uint_3::bg|| -|uint_3::bgr|| -|uint_3::br|| -|uint_3::brg|| -|uint_3::g|| -|uint_3::gb|| -|uint_3::gbr|| -|uint_3::gr|| -|uint_3::grb|| -|uint_3::r|| -|uint_3::rb|| -|uint_3::rbg|| -|uint_3::rg|| -|uint_3::rgb|| -|uint_3::x|| -|uint_3::xy|| -|uint_3::xyz|| -|uint_3::xz|| -|uint_3::xzy|| -|uint_3::y|| -|uint_3::yx|| -|uint_3::yxz|| -|uint_3::yz|| -|uint_3::yzx|| -|uint_3::z|| -|uint_3::zx|| -|uint_3::zxy|| -|uint_3::zy|| -|uint_3::zyx|| - -## Inheritance Hierarchy - -`uint_3` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## uint_3 - -Default constructor, initializes all elements with 0. - -```cpp -uint_3() restrict(amp, - cpu); - -uint_3( - unsigned int _V0, - unsigned int _V1, - unsigned int _V2) restrict(amp, - cpu); - -uint_3( - unsigned int _V) restrict(amp, - cpu); - -uint_3( - const uint_3& _Other) restrict(amp, - cpu); - -explicit inline uint_3( - const int_3& _Other) restrict(amp, - cpu); - -explicit inline uint_3( - const float_3& _Other) restrict(amp, - cpu); - -explicit inline uint_3( - const unorm_3& _Other) restrict(amp, - cpu); - -explicit inline uint_3( - const norm_3& _Other) restrict(amp, - cpu); - -explicit inline uint_3( - const double_3& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 3; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/uint-4-class.md b/docs/parallel/amp/reference/uint-4-class.md deleted file mode 100644 index 52c3c56b77a..00000000000 --- a/docs/parallel/amp/reference/uint-4-class.md +++ /dev/null @@ -1,402 +0,0 @@ ---- -description: "Learn more about: uint_4 Class" -title: "uint_4 Class" -ms.date: "03/27/2019" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::uint_4::ywx", "amp_short_vectors/Concurrency::graphics::uint_4::get_yxw", "amp_short_vectors/Concurrency::graphics::uint_4::xw", "amp_short_vectors/Concurrency::graphics::uint_4::brga", "amp_short_vectors/Concurrency::graphics::uint_4::get_zw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wzyx", "amp_short_vectors/Concurrency::graphics::uint_4::operator+=", "amp_short_vectors/Concurrency::graphics::uint_4::zw", "amp_short_vectors/Concurrency::graphics::uint_4::set_zy", "amp_short_vectors/Concurrency::graphics::uint_4::rgba", "amp_short_vectors/Concurrency::graphics::uint_4::grab", "amp_short_vectors/Concurrency::graphics::uint_4::xzwy", "amp_short_vectors/Concurrency::graphics::uint_4::get_ywzx", "amp_short_vectors/Concurrency::graphics::uint_4::set_xzwy", "amp_short_vectors/Concurrency::graphics::uint_4::set_wz", "amp_short_vectors/Concurrency::graphics::uint_4::ab", "amp_short_vectors/Concurrency::graphics::uint_4::set_zxy", "amp_short_vectors/Concurrency::graphics::uint_4::gabr", "amp_short_vectors/Concurrency::graphics::uint_4::agrb", "amp_short_vectors/Concurrency::graphics::uint_4::zxy", "amp_short_vectors/Concurrency::graphics::uint_4::br", "amp_short_vectors/Concurrency::graphics::uint_4::ragb", "amp_short_vectors/Concurrency::graphics::uint_4::rgb", "amp_short_vectors/Concurrency::graphics::uint_4::arb", "amp_short_vectors/Concurrency::graphics::uint_4::xyzw", "amp_short_vectors/Concurrency::graphics::uint_4::wzyx", "amp_short_vectors/Concurrency::graphics::uint_4::zxwy", "amp_short_vectors/Concurrency::graphics::uint_4::set_yzxw", "amp_short_vectors/Concurrency::graphics::uint_4::zwxy", "amp_short_vectors/Concurrency::graphics::uint_4::operator*=", "amp_short_vectors/Concurrency::graphics::uint_4::yzwx", "amp_short_vectors/Concurrency::graphics::uint_4::bg", "amp_short_vectors/Concurrency::graphics::uint_4::set_yz", "amp_short_vectors/Concurrency::graphics::uint_4::x", "amp_short_vectors/Concurrency::graphics::uint_4::set_z", "amp_short_vectors/Concurrency::graphics::uint_4::grba", "amp_short_vectors/Concurrency::graphics::uint_4::zwy", "amp_short_vectors/Concurrency::graphics::uint_4::get_yzwx", "amp_short_vectors/Concurrency::graphics::uint_4::xz", "amp_short_vectors/Concurrency::graphics::uint_4::set_wxyz", "amp_short_vectors/Concurrency::graphics::uint_4::b", "amp_short_vectors/Concurrency::graphics::uint_4::set_zx", "amp_short_vectors/Concurrency::graphics::uint_4::set_wyzx", "amp_short_vectors/Concurrency::graphics::uint_4::get_xyw", "amp_short_vectors/Concurrency::graphics::uint_4::get_ywz", "amp_short_vectors/Concurrency::graphics::uint_4::g", "amp_short_vectors/Concurrency::graphics::uint_4::get_zwxy", "amp_short_vectors/Concurrency::graphics::uint_4::yxzw", "amp_short_vectors/Concurrency::graphics::uint_4::set_ywx", "amp_short_vectors/Concurrency::graphics::uint_4::ar", "amp_short_vectors/Concurrency::graphics::uint_4::get_zyxw", "amp_short_vectors/Concurrency::graphics::uint_4::get_yxz", "amp_short_vectors/Concurrency::graphics::uint_4::set_xy", "amp_short_vectors/Concurrency::graphics::uint_4::get_y", "amp_short_vectors/Concurrency::graphics::uint_4::ga", "amp_short_vectors/Concurrency::graphics::uint_4::zyx", "amp_short_vectors/Concurrency::graphics::uint_4::get_zyx", "amp_short_vectors/Concurrency::graphics::uint_4::get_zxyw", "amp_short_vectors/Concurrency::graphics::uint_4::wy", "amp_short_vectors/Concurrency::graphics::uint_4::set_y", "amp_short_vectors/Concurrency::graphics::uint_4::bgr", "amp_short_vectors/Concurrency::graphics::uint_4::gbr", "amp_short_vectors/Concurrency::graphics::uint_4::wzxy", "amp_short_vectors/Concurrency::graphics::uint_4::set_wxz", "amp_short_vectors/Concurrency::graphics::uint_4::get_wxy", "amp_short_vectors/Concurrency::graphics::uint_4::set_zxyw", "amp_short_vectors/Concurrency::graphics::uint_4::bagr", "amp_short_vectors/Concurrency::graphics::uint_4::zxw", "amp_short_vectors/Concurrency::graphics::uint_4::operator/=", "amp_short_vectors/Concurrency::graphics::uint_4::rabg", "amp_short_vectors/Concurrency::graphics::uint_4::get_xwzy", "amp_short_vectors/Concurrency::graphics::uint_4::get_xzwy", "amp_short_vectors/Concurrency::graphics::uint_4::xywz", "amp_short_vectors/Concurrency::graphics::uint_4::get_ywxz", "amp_short_vectors/Concurrency::graphics::uint_4::get_z", "amp_short_vectors/Concurrency::graphics::uint_4::set_xyw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wxzy", "amp_short_vectors/Concurrency::graphics::uint_4::get_yxzw", "amp_short_vectors/Concurrency::graphics::uint_4::z", "amp_short_vectors/Concurrency::graphics::uint_4::operator=", "amp_short_vectors/Concurrency::graphics::uint_4::wxyz", "amp_short_vectors/Concurrency::graphics::uint_4::set_xwzy", "amp_short_vectors/Concurrency::graphics::uint_4::set_yw", "amp_short_vectors/Concurrency::graphics::uint_4::a", "amp_short_vectors/Concurrency::graphics::uint_4::set_zwyx", "amp_short_vectors/Concurrency::graphics::uint_4::xy", "amp_short_vectors/Concurrency::graphics::uint_4::get_yzx", "amp_short_vectors/Concurrency::graphics::uint_4::rg", "amp_short_vectors/Concurrency::graphics::uint_4::rgab", "amp_short_vectors/Concurrency::graphics::uint_4::set_xwz", "amp_short_vectors/Concurrency::graphics::uint_4::set_zyxw", "amp_short_vectors/Concurrency::graphics::uint_4::gra", "amp_short_vectors/Concurrency::graphics::uint_4::rbg", "amp_short_vectors/Concurrency::graphics::uint_4::set_zwxy", "amp_short_vectors/Concurrency::graphics::uint_4::get_wzxy", "amp_short_vectors/Concurrency::graphics::uint_4::zyxw", "amp_short_vectors/Concurrency::graphics::uint_4::set_wzxy", "amp_short_vectors/Concurrency::graphics::uint_4::set_yxw", "amp_short_vectors/Concurrency::graphics::uint_4::yz", "amp_short_vectors/Concurrency::graphics::uint_4::zwx", "amp_short_vectors/Concurrency::graphics::uint_4::w", "amp_short_vectors/Concurrency::graphics::uint_4::get_xwyz", "amp_short_vectors/Concurrency::graphics::uint_4::rab", "amp_short_vectors/Concurrency::graphics::uint_4::set_wzy", "amp_short_vectors/Concurrency::graphics::uint_4::get_xwy", "amp_short_vectors/Concurrency::graphics::uint_4::get_zywx", "amp_short_vectors/Concurrency::graphics::uint_4::set_wx", "amp_short_vectors/Concurrency::graphics::uint_4::set_wxy", "amp_short_vectors/Concurrency::graphics::uint_4::get_ywx", "amp_short_vectors/Concurrency::graphics::uint_4::set_wyx", "amp_short_vectors/Concurrency::graphics::uint_4::bag", "amp_short_vectors/Concurrency::graphics::uint_4::zyw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wx", "amp_short_vectors/Concurrency::graphics::uint_4::get_xyzw", "amp_short_vectors/Concurrency::graphics::uint_4::abg", "amp_short_vectors/Concurrency::graphics::uint_4::bra", "amp_short_vectors/Concurrency::graphics::uint_4::get_zx", "amp_short_vectors/Concurrency::graphics::uint_4::gab", "amp_short_vectors/Concurrency::graphics::uint_4::barg", "amp_short_vectors/Concurrency::graphics::uint_4::agbr", "amp_short_vectors/Concurrency::graphics::uint_4::yzxw", "amp_short_vectors/Concurrency::graphics::uint_4::set_xwyz", "amp_short_vectors/Concurrency::graphics::uint_4::get_zyw", "amp_short_vectors/Concurrency::graphics::uint_4::ag", "amp_short_vectors/Concurrency::graphics::uint_4::zxyw", "amp_short_vectors/Concurrency::graphics::uint_4::operator++", "amp_short_vectors/Concurrency::graphics::uint_4::wxy", "amp_short_vectors/Concurrency::graphics::uint_4::set_xyz", "amp_short_vectors/Concurrency::graphics::uint_4::grb", "amp_short_vectors/Concurrency::graphics::uint_4", "amp_short_vectors/Concurrency::graphics::uint_4::wyz", "amp_short_vectors/Concurrency::graphics::uint_4::gr", "amp_short_vectors/Concurrency::graphics::uint_4::get_zxw", "amp_short_vectors/Concurrency::graphics::uint_4::set_zwx", "amp_short_vectors/Concurrency::graphics::uint_4::ra", "amp_short_vectors/Concurrency::graphics::uint_4::bgar", "amp_short_vectors/Concurrency::graphics::uint_4::get_yz", "amp_short_vectors/Concurrency::graphics::uint_4::abrg", "amp_short_vectors/Concurrency::graphics::uint_4::zywx", "amp_short_vectors/Concurrency::graphics::uint_4::set_yxwz", "amp_short_vectors/Concurrency::graphics::uint_4::get_wzy", "amp_short_vectors/Concurrency::graphics::uint_4::set_zxw", "amp_short_vectors/Concurrency::graphics::uint_4::get_xzy", "amp_short_vectors/Concurrency::graphics::uint_4::agr", "amp_short_vectors/Concurrency::graphics::uint_4::set_wzyx", "amp_short_vectors/Concurrency::graphics::uint_4::r", "amp_short_vectors/Concurrency::graphics::uint_4::operator-=", "amp_short_vectors/Concurrency::graphics::uint_4::set_wxzy", "amp_short_vectors/Concurrency::graphics::uint_4::set_yxzw", "amp_short_vectors/Concurrency::graphics::uint_4::agb", "amp_short_vectors/Concurrency::graphics::uint_4::set_zyx", "amp_short_vectors/Concurrency::graphics::uint_4::get_zwyx", "amp_short_vectors/Concurrency::graphics::uint_4::get_yzw", "amp_short_vectors/Concurrency::graphics::uint_4::set_wy", "amp_short_vectors/Concurrency::graphics::uint_4::xwzy", "amp_short_vectors/Concurrency::graphics::uint_4::set_zyw", "amp_short_vectors/Concurrency::graphics::uint_4::wyx", "amp_short_vectors/Concurrency::graphics::uint_4::zx", "amp_short_vectors/Concurrency::graphics::uint_4::yx", "amp_short_vectors/Concurrency::graphics::uint_4::get_xyz", "amp_short_vectors/Concurrency::graphics::uint_4::get_wy", "amp_short_vectors/Concurrency::graphics::uint_4::get_xzw", "amp_short_vectors/Concurrency::graphics::uint_4::set_yzw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wz", "amp_short_vectors/Concurrency::graphics::uint_4::xzy", "amp_short_vectors/Concurrency::graphics::uint_4::bar", "amp_short_vectors/Concurrency::graphics::uint_4::set_xzyw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wyx", "amp_short_vectors/Concurrency::graphics::uint_4::wxz", "amp_short_vectors/Concurrency::graphics::uint_4::yzw", "amp_short_vectors/Concurrency::graphics::uint_4::get_xwz", "amp_short_vectors/Concurrency::graphics::uint_4::ywxz", "amp_short_vectors/Concurrency::graphics::uint_4::wyzx", "amp_short_vectors/Concurrency::graphics::uint_4::set_xz", "amp_short_vectors/Concurrency::graphics::uint_4::get_yxwz", "amp_short_vectors/Concurrency::graphics::uint_4::get_yx", "amp_short_vectors/Concurrency::graphics::uint_4::zwyx", "amp_short_vectors/Concurrency::graphics::uint_4::arg", "amp_short_vectors/Concurrency::graphics::uint_4::wzx", "amp_short_vectors/Concurrency::graphics::uint_4::rbga", "amp_short_vectors/Concurrency::graphics::uint_4::set_zwy", "amp_short_vectors/Concurrency::graphics::uint_4::get_xzyw", "amp_short_vectors/Concurrency::graphics::uint_4::get_xywz", "amp_short_vectors/Concurrency::graphics::uint_4::yxz", "amp_short_vectors/Concurrency::graphics::uint_4::rbag", "amp_short_vectors/Concurrency::graphics::uint_4::yzx", "amp_short_vectors/Concurrency::graphics::uint_4::set_zw", "amp_short_vectors/Concurrency::graphics::uint_4::wzy", "amp_short_vectors/Concurrency::graphics::uint_4::get_zxy", "amp_short_vectors/Concurrency::graphics::uint_4::get_zy", "amp_short_vectors/Concurrency::graphics::uint_4::abr", "amp_short_vectors/Concurrency::graphics::uint_4::gbra", "amp_short_vectors/Concurrency::graphics::uint_4::xzyw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wxz", "amp_short_vectors/Concurrency::graphics::uint_4::xwy", "amp_short_vectors/Concurrency::graphics::uint_4::set_ywzx", "amp_short_vectors/Concurrency::graphics::uint_4::set_zywx", "amp_short_vectors/Concurrency::graphics::uint_4::wyxz", "amp_short_vectors/Concurrency::graphics::uint_4::set_x", "amp_short_vectors/Concurrency::graphics::uint_4::gb", "amp_short_vectors/Concurrency::graphics::uint_4::ba", "amp_short_vectors/Concurrency::graphics::uint_4::set_ywxz", "amp_short_vectors/Concurrency::graphics::uint_4::get_xy", "amp_short_vectors/Concurrency::graphics::uint_4::get_wzx", "amp_short_vectors/Concurrency::graphics::uint_4::bga", "amp_short_vectors/Concurrency::graphics::uint_4::get_x", "amp_short_vectors/Concurrency::graphics::uint_4::get_wyzx", "amp_short_vectors/Concurrency::graphics::uint_4::set_xwy", "amp_short_vectors/Concurrency::graphics::uint_4::set_xzy", "amp_short_vectors/Concurrency::graphics::uint_4::wxzy", "amp_short_vectors/Concurrency::graphics::uint_4::set_wzx", "amp_short_vectors/Concurrency::graphics::uint_4::set_ywz", "amp_short_vectors/Concurrency::graphics::uint_4::set_yx", "amp_short_vectors/Concurrency::graphics::uint_4::get_wyxz", "amp_short_vectors/Concurrency::graphics::uint_4::rga", "amp_short_vectors/Concurrency::graphics::uint_4::set_xw", "amp_short_vectors/Concurrency::graphics::uint_4::get_zwx", "amp_short_vectors/Concurrency::graphics::uint_4::get_w", "amp_short_vectors/Concurrency::graphics::uint_4::get_xw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wxyz", "amp_short_vectors/Concurrency::graphics::uint_4::garb", "amp_short_vectors/Concurrency::graphics::uint_4::y", "amp_short_vectors/Concurrency::graphics::uint_4::get_xz", "amp_short_vectors/Concurrency::graphics::uint_4::yxw", "amp_short_vectors/Concurrency::graphics::uint_4::xzw", "amp_short_vectors/Concurrency::graphics::uint_4::set_xzw", "amp_short_vectors/Concurrency::graphics::uint_4::get_zxwy", "amp_short_vectors/Concurrency::graphics::uint_4::arbg", "amp_short_vectors/Concurrency::graphics::uint_4::ywzx", "amp_short_vectors/Concurrency::graphics::uint_4::zy", "amp_short_vectors/Concurrency::graphics::uint_4::brg", "amp_short_vectors/Concurrency::graphics::uint_4::gar", "amp_short_vectors/Concurrency::graphics::uint_4::get_yzxw", "amp_short_vectors/Concurrency::graphics::uint_4::bgra", "amp_short_vectors/Concurrency::graphics::uint_4::xwyz", "amp_short_vectors/Concurrency::graphics::uint_4::ywz", "amp_short_vectors/Concurrency::graphics::uint_4::yxwz", "amp_short_vectors/Concurrency::graphics::uint_4::set_zxwy", "amp_short_vectors/Concurrency::graphics::uint_4::wz", "amp_short_vectors/Concurrency::graphics::uint_4::set_yzwx", "amp_short_vectors/Concurrency::graphics::uint_4::get_zwy", "amp_short_vectors/Concurrency::graphics::uint_4::abgr", "amp_short_vectors/Concurrency::graphics::uint_4::brag", "amp_short_vectors/Concurrency::graphics::uint_4::set_w", "amp_short_vectors/Concurrency::graphics::uint_4::set_wyz", "amp_short_vectors/Concurrency::graphics::uint_4::gba", "amp_short_vectors/Concurrency::graphics::uint_4::rb", "amp_short_vectors/Concurrency::graphics::uint_4::gbar", "amp_short_vectors/Concurrency::graphics::uint_4::xyz", "amp_short_vectors/Concurrency::graphics::uint_4::yw", "amp_short_vectors/Concurrency::graphics::uint_4::operator-", "amp_short_vectors/Concurrency::graphics::uint_4::get_yw", "amp_short_vectors/Concurrency::graphics::uint_4::wx", "amp_short_vectors/Concurrency::graphics::uint_4::set_wyxz", "amp_short_vectors/Concurrency::graphics::uint_4::xwz", "amp_short_vectors/Concurrency::graphics::uint_4::operator--", "amp_short_vectors/Concurrency::graphics::uint_4::set_xyzw", "amp_short_vectors/Concurrency::graphics::uint_4::xyw", "amp_short_vectors/Concurrency::graphics::uint_4::get_wyz", "amp_short_vectors/Concurrency::graphics::uint_4::rag", "amp_short_vectors/Concurrency::graphics::uint_4::argb", "amp_short_vectors/Concurrency::graphics::uint_4::set_yxz", "amp_short_vectors/Concurrency::graphics::uint_4::set_xywz", "amp_short_vectors/Concurrency::graphics::uint_4::rba", "amp_short_vectors/Concurrency::graphics::uint_4::set_yzx"] -ms.assetid: 1cda9e2c-5970-4ced-ae54-d7ff3c6746f4 ---- -# uint_4 Class - -Represents a short vector of four unsigned integers. - -## Syntax - -```cpp -class uint_4; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[uint_4 Constructor](#uint_4__ctor) |Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|uint_4::get_w|| -|uint_4::get_wx|| -|uint_4::get_wxy|| -|uint_4::get_wxyz|| -|uint_4::get_wxz|| -|uint_4::get_wxzy|| -|uint_4::get_wy|| -|uint_4::get_wyx|| -|uint_4::get_wyxz|| -|uint_4::get_wyz|| -|uint_4::get_wyzx|| -|uint_4::get_wz|| -|uint_4::get_wzx|| -|uint_4::get_wzxy|| -|uint_4::get_wzy|| -|uint_4::get_wzyx|| -|uint_4::get_x|| -|uint_4::get_xw|| -|uint_4::get_xwy|| -|uint_4::get_xwyz|| -|uint_4::get_xwz|| -|uint_4::get_xwzy|| -|uint_4::get_xy|| -|uint_4::get_xyw|| -|uint_4::get_xywz|| -|uint_4::get_xyz|| -|uint_4::get_xyzw|| -|uint_4::get_xz|| -|uint_4::get_xzw|| -|uint_4::get_xzwy|| -|uint_4::get_xzy|| -|uint_4::get_xzyw|| -|uint_4::get_y|| -|uint_4::get_yw|| -|uint_4::get_ywx|| -|uint_4::get_ywxz|| -|uint_4::get_ywz|| -|uint_4::get_ywzx|| -|uint_4::get_yx|| -|uint_4::get_yxw|| -|uint_4::get_yxwz|| -|uint_4::get_yxz|| -|uint_4::get_yxzw|| -|uint_4::get_yz|| -|uint_4::get_yzw|| -|uint_4::get_yzwx|| -|uint_4::get_yzx|| -|uint_4::get_yzxw|| -|uint_4::get_z|| -|uint_4::get_zw|| -|uint_4::get_zwx|| -|uint_4::get_zwxy|| -|uint_4::get_zwy|| -|uint_4::get_zwyx|| -|uint_4::get_zx|| -|uint_4::get_zxw|| -|uint_4::get_zxwy|| -|uint_4::get_zxy|| -|uint_4::get_zxyw|| -|uint_4::get_zy|| -|uint_4::get_zyw|| -|uint_4::get_zywx|| -|uint_4::get_zyx|| -|uint_4::get_zyxw|| -|uint_4::ref_a|| -|uint_4::ref_b|| -|uint_4::ref_g|| -|uint_4::ref_r|| -|uint_4::ref_w|| -|uint_4::ref_x|| -|uint_4::ref_y|| -|uint_4::ref_z|| -|uint_4::set_w|| -|uint_4::set_wx|| -|uint_4::set_wxy|| -|uint_4::set_wxyz|| -|uint_4::set_wxz|| -|uint_4::set_wxzy|| -|uint_4::set_wy|| -|uint_4::set_wyx|| -|uint_4::set_wyxz|| -|uint_4::set_wyz|| -|uint_4::set_wyzx|| -|uint_4::set_wz|| -|uint_4::set_wzx|| -|uint_4::set_wzxy|| -|uint_4::set_wzy|| -|uint_4::set_wzyx|| -|uint_4::set_x|| -|uint_4::set_xw|| -|uint_4::set_xwy|| -|uint_4::set_xwyz|| -|uint_4::set_xwz|| -|uint_4::set_xwzy|| -|uint_4::set_xy|| -|uint_4::set_xyw|| -|uint_4::set_xywz|| -|uint_4::set_xyz|| -|uint_4::set_xyzw|| -|uint_4::set_xz|| -|uint_4::set_xzw|| -|uint_4::set_xzwy|| -|uint_4::set_xzy|| -|uint_4::set_xzyw|| -|uint_4::set_y|| -|uint_4::set_yw|| -|uint_4::set_ywx|| -|uint_4::set_ywxz|| -|uint_4::set_ywz|| -|uint_4::set_ywzx|| -|uint_4::set_yx|| -|uint_4::set_yxw|| -|uint_4::set_yxwz|| -|uint_4::set_yxz|| -|uint_4::set_yxzw|| -|uint_4::set_yz|| -|uint_4::set_yzw|| -|uint_4::set_yzwx|| -|uint_4::set_yzx|| -|uint_4::set_yzxw|| -|uint_4::set_z|| -|uint_4::set_zw|| -|uint_4::set_zwx|| -|uint_4::set_zwxy|| -|uint_4::set_zwy|| -|uint_4::set_zwyx|| -|uint_4::set_zx|| -|uint_4::set_zxw|| -|uint_4::set_zxwy|| -|uint_4::set_zxy|| -|uint_4::set_zxyw|| -|uint_4::set_zy|| -|uint_4::set_zyw|| -|uint_4::set_zywx|| -|uint_4::set_zyx|| -|uint_4::set_zyxw|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|uint_4::operator-|| -|uint_4::operator--|| -|uint_4::operator*=|| -|uint_4::operator/=|| -|uint_4::operator++|| -|uint_4::operator+=|| -|uint_4::operator=|| -|uint_4::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|uint_4::a|| -|uint_4::ab|| -|uint_4::abg|| -|uint_4::abgr|| -|uint_4::abr|| -|uint_4::abrg|| -|uint_4::ag|| -|uint_4::agb|| -|uint_4::agbr|| -|uint_4::agr|| -|uint_4::agrb|| -|uint_4::ar|| -|uint_4::arb|| -|uint_4::arbg|| -|uint_4::arg|| -|uint_4::argb|| -|uint_4::b|| -|uint_4::ba|| -|uint_4::bag|| -|uint_4::bagr|| -|uint_4::bar|| -|uint_4::barg|| -|uint_4::bg|| -|uint_4::bga|| -|uint_4::bgar|| -|uint_4::bgr|| -|uint_4::bgra|| -|uint_4::br|| -|uint_4::bra|| -|uint_4::brag|| -|uint_4::brg|| -|uint_4::brga|| -|uint_4::g|| -|uint_4::ga|| -|uint_4::gab|| -|uint_4::gabr|| -|uint_4::gar|| -|uint_4::garb|| -|uint_4::gb|| -|uint_4::gba|| -|uint_4::gbar|| -|uint_4::gbr|| -|uint_4::gbra|| -|uint_4::gr|| -|uint_4::gra|| -|uint_4::grab|| -|uint_4::grb|| -|uint_4::grba|| -|uint_4::r|| -|uint_4::ra|| -|uint_4::rab|| -|uint_4::rabg|| -|uint_4::rag|| -|uint_4::ragb|| -|uint_4::rb|| -|uint_4::rba|| -|uint_4::rbag|| -|uint_4::rbg|| -|uint_4::rbga|| -|uint_4::rg|| -|uint_4::rga|| -|uint_4::rgab|| -|uint_4::rgb|| -|uint_4::rgba|| -|uint_4::w|| -|uint_4::wx|| -|uint_4::wxy|| -|uint_4::wxyz|| -|uint_4::wxz|| -|uint_4::wxzy|| -|uint_4::wy|| -|uint_4::wyx|| -|uint_4::wyxz|| -|uint_4::wyz|| -|uint_4::wyzx|| -|uint_4::wz|| -|uint_4::wzx|| -|uint_4::wzxy|| -|uint_4::wzy|| -|uint_4::wzyx|| -|uint_4::x|| -|uint_4::xw|| -|uint_4::xwy|| -|uint_4::xwyz|| -|uint_4::xwz|| -|uint_4::xwzy|| -|uint_4::xy|| -|uint_4::xyw|| -|uint_4::xywz|| -|uint_4::xyz|| -|uint_4::xyzw|| -|uint_4::xz|| -|uint_4::xzw|| -|uint_4::xzwy|| -|uint_4::xzy|| -|uint_4::xzyw|| -|uint_4::y|| -|uint_4::yw|| -|uint_4::ywx|| -|uint_4::ywxz|| -|uint_4::ywz|| -|uint_4::ywzx|| -|uint_4::yx|| -|uint_4::yxw|| -|uint_4::yxwz|| -|uint_4::yxz|| -|uint_4::yxzw|| -|uint_4::yz|| -|uint_4::yzw|| -|uint_4::yzwx|| -|uint_4::yzx|| -|uint_4::yzxw|| -|uint_4::z|| -|uint_4::zw|| -|uint_4::zwx|| -|uint_4::zwxy|| -|uint_4::zwy|| -|uint_4::zwyx|| -|uint_4::zx|| -|uint_4::zxw|| -|uint_4::zxwy|| -|uint_4::zxy|| -|uint_4::zxyw|| -|uint_4::zy|| -|uint_4::zyw|| -|uint_4::zywx|| -|uint_4::zyx|| -|uint_4::zyxw|| - -## Inheritance Hierarchy - -`uint_4` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## uint_4 - -Default constructor, initializes all elements with 0. - -### Syntax - -```cpp -uint_4() restrict(amp,cpu); -uint_4( - unsigned int _V0, - unsigned int _V1, - unsigned int _V2, - unsigned int _V3 -) restrict(amp,cpu); -uint_4( - unsigned int _V -) restrict(amp,cpu); -uint_4( - const uint_4& _Other -) restrict(amp,cpu); -explicit inline uint_4( - const int_4& _Other -) restrict(amp,cpu); -explicit inline uint_4( - const float_4& _Other -) restrict(amp,cpu); -explicit inline uint_4( - const unorm_4& _Other -) restrict(amp,cpu); -explicit inline uint_4( - const norm_4& _Other -) restrict(amp,cpu); -explicit inline uint_4( - const double_4& _Other -) restrict(amp,cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V3*
-The value to initialize element 3. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -### Syntax - -```cpp -static const int size = 4; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/uninitialized-object-class.md b/docs/parallel/amp/reference/uninitialized-object-class.md deleted file mode 100644 index bfa77321403..00000000000 --- a/docs/parallel/amp/reference/uninitialized-object-class.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: "Learn more about: uninitialized_object Class" -title: "uninitialized_object Class" -ms.date: "03/27/2019" -f1_keywords: ["uninitialized_object", "AMPRT/uninitialized_object", "AMPRT/Concurrency::uninitialized_object"] -helpviewer_keywords: ["uninitialized_object class"] -ms.assetid: 6ae3c4e8-64a6-4511-a158-03be197b63af ---- -# uninitialized_object Class - -The exception that is thrown when an uninitialized object is used. - -## Syntax - -```cpp -class uninitialized_object : public runtime_exception; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[uninitialized_object Constructor](#uninitialized_object)|Initializes a new instance of the `uninitialized_object` class.| - -## Inheritance Hierarchy - -`exception` - -`runtime_exception` - -`uninitialized_object` - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## uninitialized_object - -Constructs a new instance of the `uninitialized_object` exception. - -### Syntax - -```cpp -explicit uninitialized_object( - const char * _Message ) throw(); - -uninitialized_object() throw(); -``` - -### Parameters - -*_Message*
-A description of the error. - -### Return Value - -The `uninitialized_object` exception object. - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/unorm-2-class.md b/docs/parallel/amp/reference/unorm-2-class.md deleted file mode 100644 index 56ca540fa1a..00000000000 --- a/docs/parallel/amp/reference/unorm-2-class.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -description: "Learn more about: unorm_2 Class" -title: "unorm_2 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::unnorm_2::operator+=", "amp_short_vectors/Concurrency::graphics::unnorm_2::y", "amp_short_vectors/Concurrency::graphics::unnorm_2::set_y", "amp_short_vectors/Concurrency::graphics::unnorm_2::x", "amp_short_vectors/Concurrency::graphics::unnorm_2::get_yx", "amp_short_vectors/Concurrency::graphics::unnorm_2::operator--", "amp_short_vectors/Concurrency::graphics::unnorm_2::set_xy", "amp_short_vectors/Concurrency::graphics::unnorm_2::operator*=", "amp_short_vectors/Concurrency::graphics::unnorm_2::xy", "amp_short_vectors/Concurrency::graphics::unnorm_2::get_y", "amp_short_vectors/Concurrency::graphics::unnorm_2::operator=", "amp_short_vectors/Concurrency::graphics::unnorm_2::set_x", "amp_short_vectors/Concurrency::graphics::unnorm_2::rg", "amp_short_vectors/Concurrency::graphics::unorm_2", "amp_short_vectors/Concurrency::graphics::unnorm_2::operator-=", "amp_short_vectors/Concurrency::graphics::unnorm_2::operator/=", "amp_short_vectors/Concurrency::graphics::unnorm_2::get_xy", "amp_short_vectors/Concurrency::graphics::unnorm_2::set_yx", "amp_short_vectors/Concurrency::graphics::unnorm_2::yx", "amp_short_vectors/Concurrency::graphics::unnorm_2::gr", "amp_short_vectors/Concurrency::graphics::unnorm_2::r", "amp_short_vectors/Concurrency::graphics::unnorm_2::operator-", "amp_short_vectors/Concurrency::graphics::unnorm_2::get_x", "amp_short_vectors/Concurrency::graphics::unnorm_2::g", "amp_short_vectors/Concurrency::graphics::unnorm_2::operator++"] -ms.assetid: 62e88ea7-e29f-4f62-95ce-61a1f39f5e34 ---- -# unorm_2 Class - -Represents a short vector of two unsigned normal numbers. - -## Syntax - -```cpp -class unorm_2; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[unorm_2 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|unorm_2::get_x|| -|unorm_2::get_xy|| -|unorm_2::get_y|| -|unorm_2::get_yx|| -|unorm_2::ref_g|| -|unorm_2::ref_r|| -|unorm_2::ref_x|| -|unorm_2::ref_y|| -|unorm_2::set_x|| -|unorm_2::set_xy|| -|unorm_2::set_y|| -|unorm_2::set_yx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|unorm_2::operator--|| -|unorm_2::operator*=|| -|unorm_2::operator/=|| -|unorm_2::operator++|| -|unorm_2::operator+=|| -|unorm_2::operator=|| -|unorm_2::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|unorm_2::size Constant|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|unorm_2::g|| -|unorm_2::gr|| -|unorm_2::r|| -|unorm_2::rg|| -|unorm_2::x|| -|unorm_2::xy|| -|unorm_2::y|| -|unorm_2::yx|| - -## Inheritance Hierarchy - -`unorm_2` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## unorm_2 - -Default constructor, initializes all elements with 0. - -```cpp -unorm_2() restrict(amp, - cpu); - -unorm_2( - unorm _V0, - unorm _V1) restrict(amp, - cpu); - -unorm_2( - float _V0, - float _V1) restrict(amp, - cpu); - -unorm_2( - unorm _V) restrict(amp, - cpu); - -explicit unorm_2( - float _V) restrict(amp, - cpu); - -unorm_2( - const unorm_2& _Other) restrict(amp, - cpu); - -explicit inline unorm_2( - const uint_2& _Other) restrict(amp, - cpu); - -explicit inline unorm_2( - const int_2& _Other) restrict(amp, - cpu); - -explicit inline unorm_2( - const float_2& _Other) restrict(amp, - cpu); - -explicit inline unorm_2( - const norm_2& _Other) restrict(amp, - cpu); - -explicit inline unorm_2( - const double_2& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 2; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/unorm-3-class.md b/docs/parallel/amp/reference/unorm-3-class.md deleted file mode 100644 index d79203d802b..00000000000 --- a/docs/parallel/amp/reference/unorm-3-class.md +++ /dev/null @@ -1,214 +0,0 @@ ---- -description: "Learn more about: unorm_3 Class" -title: "unorm_3 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::unorm_3::set_zy", "amp_short_vectors/Concurrency::graphics::unorm_3::zxy", "amp_short_vectors/Concurrency::graphics::unorm_3::set_zyx", "amp_short_vectors/Concurrency::graphics::unorm_3::operator-=", "amp_short_vectors/Concurrency::graphics::unorm_3::xzy", "amp_short_vectors/Concurrency::graphics::unorm_3::get_xzy", "amp_short_vectors/Concurrency::graphics::unorm_3::zyx", "amp_short_vectors/Concurrency::graphics::unorm_3::rgb", "amp_short_vectors/Concurrency::graphics::unorm_3::set_xz", "amp_short_vectors/Concurrency::graphics::unorm_3::set_yxz", "amp_short_vectors/Concurrency::graphics::unorm_3::set_yx", "amp_short_vectors/Concurrency::graphics::unorm_3::br", "amp_short_vectors/Concurrency::graphics::unorm_3::get_zy", "amp_short_vectors/Concurrency::graphics::unorm_3::set_zx", "amp_short_vectors/Concurrency::graphics::unorm_3::get_xyz", "amp_short_vectors/Concurrency::graphics::unorm_3::b", "amp_short_vectors/Concurrency::graphics::unorm_3::set_xyz", "amp_short_vectors/Concurrency::graphics::unorm_3", "amp_short_vectors/Concurrency::graphics::unorm_3::set_z", "amp_short_vectors/Concurrency::graphics::unorm_3::set_xy", "amp_short_vectors/Concurrency::graphics::unorm_3::get_zyx", "amp_short_vectors/Concurrency::graphics::unorm_3::get_xy", "amp_short_vectors/Concurrency::graphics::unorm_3::x", "amp_short_vectors/Concurrency::graphics::unorm_3::get_zxy", "amp_short_vectors/Concurrency::graphics::unorm_3::z", "amp_short_vectors/Concurrency::graphics::unorm_3::get_x", "amp_short_vectors/Concurrency::graphics::unorm_3::operator=", "amp_short_vectors/Concurrency::graphics::unorm_3::yxz", "amp_short_vectors/Concurrency::graphics::unorm_3::get_yx", "amp_short_vectors/Concurrency::graphics::unorm_3::gbr", "amp_short_vectors/Concurrency::graphics::unorm_3::get_yxz", "amp_short_vectors/Concurrency::graphics::unorm_3::operator--", "amp_short_vectors/Concurrency::graphics::unorm_3::operator/=", "amp_short_vectors/Concurrency::graphics::unorm_3::brg", "amp_short_vectors/Concurrency::graphics::unorm_3::gb", "amp_short_vectors/Concurrency::graphics::unorm_3::zy", "amp_short_vectors/Concurrency::graphics::unorm_3::set_xzy", "amp_short_vectors/Concurrency::graphics::unorm_3::get_yzx", "amp_short_vectors/Concurrency::graphics::unorm_3::rb", "amp_short_vectors/Concurrency::graphics::unorm_3::gr", "amp_short_vectors/Concurrency::graphics::unorm_3::zx", "amp_short_vectors/Concurrency::graphics::unorm_3::r", "amp_short_vectors/Concurrency::graphics::unorm_3::xyz", "amp_short_vectors/Concurrency::graphics::unorm_3::grb", "amp_short_vectors/Concurrency::graphics::unorm_3::bg", "amp_short_vectors/Concurrency::graphics::unorm_3::get_y", "amp_short_vectors/Concurrency::graphics::unorm_3::g", "amp_short_vectors/Concurrency::graphics::unorm_3::yz", "amp_short_vectors/Concurrency::graphics::unorm_3::yx", "amp_short_vectors/Concurrency::graphics::unorm_3::get_xz", "amp_short_vectors/Concurrency::graphics::unorm_3::set_zxy", "amp_short_vectors/Concurrency::graphics::unorm_3::get_z", "amp_short_vectors/Concurrency::graphics::unorm_3::bgr", "amp_short_vectors/Concurrency::graphics::unorm_3::set_x", "amp_short_vectors/Concurrency::graphics::unorm_3::operator-", "amp_short_vectors/Concurrency::graphics::unorm_3::y", "amp_short_vectors/Concurrency::graphics::unorm_3::set_yzx", "amp_short_vectors/Concurrency::graphics::unorm_3::get_zx", "amp_short_vectors/Concurrency::graphics::unorm_3::yzx", "amp_short_vectors/Concurrency::graphics::unorm_3::operator++", "amp_short_vectors/Concurrency::graphics::unorm_3::set_yz", "amp_short_vectors/Concurrency::graphics::unorm_3::operator+=", "amp_short_vectors/Concurrency::graphics::unorm_3::xz", "amp_short_vectors/Concurrency::graphics::unorm_3::rg", "amp_short_vectors/Concurrency::graphics::unorm_3::xy", "amp_short_vectors/Concurrency::graphics::unorm_3::operator*=", "amp_short_vectors/Concurrency::graphics::unorm_3::set_y", "amp_short_vectors/Concurrency::graphics::unorm_3::get_yz", "amp_short_vectors/Concurrency::graphics::unorm_3::rbg"] -ms.assetid: ea4e7a17-5256-464c-af28-8b01962564c0 ---- -# unorm_3 Class - -Represents a short vector of three unsigned normal numbers. - -## Syntax - -```cpp -class unorm_3; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[unorm_3 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|unorm_3::get_x|| -|unorm_3::get_xy|| -|unorm_3::get_xyz|| -|unorm_3::get_xz|| -|unorm_3::get_xzy|| -|unorm_3::get_y|| -|unorm_3::get_yx|| -|unorm_3::get_yxz|| -|unorm_3::get_yz|| -|unorm_3::get_yzx|| -|unorm_3::get_z|| -|unorm_3::get_zx|| -|unorm_3::get_zxy|| -|unorm_3::get_zy|| -|unorm_3::get_zyx|| -|Unorm_3::ref_b|| -|Unorm_3::ref_g|| -|Unorm_3::ref_r|| -|Unorm_3::ref_x|| -|Unorm_3::ref_y|| -|Unorm_3::ref_z|| -|unorm_3::set_x|| -|unorm_3::set_xy|| -|unorm_3::set_xyz|| -|unorm_3::set_xz|| -|unorm_3::set_xzy|| -|unorm_3::set_y|| -|unorm_3::set_yx|| -|unorm_3::set_yxz|| -|unorm_3::set_yz|| -|unorm_3::set_yzx|| -|unorm_3::set_z|| -|unorm_3::set_zx|| -|unorm_3::set_zxy|| -|unorm_3::set_zy|| -|unorm_3::set_zyx|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|unorm_3::operator--|| -|unorm_3::operator*=|| -|unorm_3::operator/=|| -|unorm_3::operator++|| -|unorm_3::operator+=|| -|unorm_3::operator=|| -|unorm_3::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#unorm_3__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|unorm_3::b|| -|unorm_3::bg|| -|unorm_3::bgr|| -|unorm_3::br|| -|unorm_3::brg|| -|unorm_3::g|| -|unorm_3::gb|| -|unorm_3::gbr|| -|unorm_3::gr|| -|unorm_3::grb|| -|unorm_3::r|| -|unorm_3::rb|| -|unorm_3::rbg|| -|unorm_3::rg|| -|unorm_3::rgb|| -|unorm_3::x|| -|unorm_3::xy|| -|unorm_3::xyz|| -|unorm_3::xz|| -|unorm_3::xzy|| -|unorm_3::y|| -|unorm_3::yx|| -|unorm_3::yxz|| -|unorm_3::yz|| -|unorm_3::yzx|| -|unorm_3::z|| -|unorm_3::zx|| -|unorm_3::zxy|| -|unorm_3::zy|| -|unorm_3::zyx|| - -## Inheritance Hierarchy - -`unorm_3` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## unorm_3 - -Default constructor, initializes all elements with 0. - -```cpp -unorm_3() restrict(amp, - cpu); - -unorm_3( - unorm _V0, - unorm _V1, - unorm _V2) restrict(amp, - cpu); - -unorm_3( - float _V0, - float _V1, - float _V2) restrict(amp, - cpu); - -unorm_3( - unorm _V) restrict(amp, - cpu); - -explicit unorm_3( - float _V) restrict(amp, - cpu); - -unorm_3( - const unorm_3& _Other) restrict(amp, - cpu); - -explicit inline unorm_3( - const uint_3& _Other) restrict(amp, - cpu); - -explicit inline unorm_3( - const int_3& _Other) restrict(amp, - cpu); - -explicit inline unorm_3( - const float_3& _Other) restrict(amp, - cpu); - -explicit inline unorm_3( - const norm_3& _Other) restrict(amp, - cpu); - -explicit inline unorm_3( - const double_3& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 3; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/unorm-4-class.md b/docs/parallel/amp/reference/unorm-4-class.md deleted file mode 100644 index 1726971da23..00000000000 --- a/docs/parallel/amp/reference/unorm-4-class.md +++ /dev/null @@ -1,418 +0,0 @@ ---- -description: "Learn more about: unorm_4 Class" -title: "unorm_4 Class" -ms.date: "11/04/2016" -f1_keywords: ["amp_short_vectors/Concurrency::graphics::unorm_4::set_yxzw", "amp_short_vectors/Concurrency::graphics::unorm_4::gbra", "amp_short_vectors/Concurrency::graphics::unorm_4::abg", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xzyw", "amp_short_vectors/Concurrency::graphics::unorm_4::brag", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zywx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xwy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_x", "amp_short_vectors/Concurrency::graphics::unorm_4::ra", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xyw", "amp_short_vectors/Concurrency::graphics::unorm_4::rg", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yxwz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xw", "amp_short_vectors/Concurrency::graphics::unorm_4::get_z", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wxyz", "amp_short_vectors/Concurrency::graphics::unorm_4::operator*=", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zyw", "amp_short_vectors/Concurrency::graphics::unorm_4::b", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wyzx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wyz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wyzx", "amp_short_vectors/Concurrency::graphics::unorm_4::ywx", "amp_short_vectors/Concurrency::graphics::unorm_4::ragb", "amp_short_vectors/Concurrency::graphics::unorm_4::yxzw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wzy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_y", "amp_short_vectors/Concurrency::graphics::unorm_4::rag", "amp_short_vectors/Concurrency::graphics::unorm_4::zwxy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wyxz", "amp_short_vectors/Concurrency::graphics::unorm_4::gab", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yzw", "amp_short_vectors/Concurrency::graphics::unorm_4::rgb", "amp_short_vectors/Concurrency::graphics::unorm_4::arbg", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wyx", "amp_short_vectors/Concurrency::graphics::unorm_4::y", "amp_short_vectors/Concurrency::graphics::unorm_4::wz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yxwz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xw", "amp_short_vectors/Concurrency::graphics::unorm_4::bgra", "amp_short_vectors/Concurrency::graphics::unorm_4::grb", "amp_short_vectors/Concurrency::graphics::unorm_4::wzx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_ywzx", "amp_short_vectors/Concurrency::graphics::unorm_4::yz", "amp_short_vectors/Concurrency::graphics::unorm_4::xywz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xzwy", "amp_short_vectors/Concurrency::graphics::unorm_4::rba", "amp_short_vectors/Concurrency::graphics::unorm_4::set_ywx", "amp_short_vectors/Concurrency::graphics::unorm_4::wzy", "amp_short_vectors/Concurrency::graphics::unorm_4::bg", "amp_short_vectors/Concurrency::graphics::unorm_4::agb", "amp_short_vectors/Concurrency::graphics::unorm_4::get_w", "amp_short_vectors/Concurrency::graphics::unorm_4::bag", "amp_short_vectors/Concurrency::graphics::unorm_4::bga", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wx", "amp_short_vectors/Concurrency::graphics::unorm_4::arb", "amp_short_vectors/Concurrency::graphics::unorm_4::get_ywz", "amp_short_vectors/Concurrency::graphics::unorm_4::a", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zxyw", "amp_short_vectors/Concurrency::graphics::unorm_4::operator/=", "amp_short_vectors/Concurrency::graphics::unorm_4::w", "amp_short_vectors/Concurrency::graphics::unorm_4::operator++", "amp_short_vectors/Concurrency::graphics::unorm_4::wyxz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yzx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zyx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xywz", "amp_short_vectors/Concurrency::graphics::unorm_4::xyzw", "amp_short_vectors/Concurrency::graphics::unorm_4::rbag", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wxy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xwzy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wxzy", "amp_short_vectors/Concurrency::graphics::unorm_4::gabr", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xyzw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xyz", "amp_short_vectors/Concurrency::graphics::unorm_4::br", "amp_short_vectors/Concurrency::graphics::unorm_4::yw", "amp_short_vectors/Concurrency::graphics::unorm_4::zxyw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wxzy", "amp_short_vectors/Concurrency::graphics::unorm_4::argb", "amp_short_vectors/Concurrency::graphics::unorm_4::x", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wzxy", "amp_short_vectors/Concurrency::graphics::unorm_4::ab", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yzwx", "amp_short_vectors/Concurrency::graphics::unorm_4::xyz", "amp_short_vectors/Concurrency::graphics::unorm_4::gbr", "amp_short_vectors/Concurrency::graphics::unorm_4::rab", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xy", "amp_short_vectors/Concurrency::graphics::unorm_4::operator--", "amp_short_vectors/Concurrency::graphics::unorm_4::gba", "amp_short_vectors/Concurrency::graphics::unorm_4::bra", "amp_short_vectors/Concurrency::graphics::unorm_4::garb", "amp_short_vectors/Concurrency::graphics::unorm_4::zwyx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_ywx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_ywzx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xwy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_ywxz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zxwy", "amp_short_vectors/Concurrency::graphics::unorm_4::agr", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wzx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zxyw", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yxz", "amp_short_vectors/Concurrency::graphics::unorm_4::zxy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zxw", "amp_short_vectors/Concurrency::graphics::unorm_4::ga", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zyw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wxyz", "amp_short_vectors/Concurrency::graphics::unorm_4::wxy", "amp_short_vectors/Concurrency::graphics::unorm_4::wzxy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zwy", "amp_short_vectors/Concurrency::graphics::unorm_4::xwz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wzx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xzwy", "amp_short_vectors/Concurrency::graphics::unorm_4::ywxz", "amp_short_vectors/Concurrency::graphics::unorm_4::yx", "amp_short_vectors/Concurrency::graphics::unorm_4::xzy", "amp_short_vectors/Concurrency::graphics::unorm_4::zy", "amp_short_vectors/Concurrency::graphics::unorm_4::bgar", "amp_short_vectors/Concurrency::graphics::unorm_4::set_y", "amp_short_vectors/Concurrency::graphics::unorm_4::xw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xwyz", "amp_short_vectors/Concurrency::graphics::unorm_4::xzyw", "amp_short_vectors/Concurrency::graphics::unorm_4::ar", "amp_short_vectors/Concurrency::graphics::unorm_4::rgba", "amp_short_vectors/Concurrency::graphics::unorm_4::gra", "amp_short_vectors/Concurrency::graphics::unorm_4::ba", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zyx", "amp_short_vectors/Concurrency::graphics::unorm_4::operator=", "amp_short_vectors/Concurrency::graphics::unorm_4::set_x", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xzw", "amp_short_vectors/Concurrency::graphics::unorm_4::rga", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_z", "amp_short_vectors/Concurrency::graphics::unorm_4::yzx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yzx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zwx", "amp_short_vectors/Concurrency::graphics::unorm_4::xwzy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zwxy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yxz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xzy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xwyz", "amp_short_vectors/Concurrency::graphics::unorm_4::yzwx", "amp_short_vectors/Concurrency::graphics::unorm_4::bagr", "amp_short_vectors/Concurrency::graphics::unorm_4::yxwz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xyz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zyxw", "amp_short_vectors/Concurrency::graphics::unorm_4::bar", "amp_short_vectors/Concurrency::graphics::unorm_4::zyw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wxz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zxy", "amp_short_vectors/Concurrency::graphics::unorm_4::yzw", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wyxz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zwyx", "amp_short_vectors/Concurrency::graphics::unorm_4::wyzx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zwy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wx", "amp_short_vectors/Concurrency::graphics::unorm_4::zyxw", "amp_short_vectors/Concurrency::graphics::unorm_4::rbga", "amp_short_vectors/Concurrency::graphics::unorm_4::rabg", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zwxy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zxy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xwz", "amp_short_vectors/Concurrency::graphics::unorm_4::abr", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zwyx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yzxw", "amp_short_vectors/Concurrency::graphics::unorm_4::zywx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yzwx", "amp_short_vectors/Concurrency::graphics::unorm_4::zyx", "amp_short_vectors/Concurrency::graphics::unorm_4::g", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xwz", "amp_short_vectors/Concurrency::graphics::unorm_4::zwy", "amp_short_vectors/Concurrency::graphics::unorm_4::gbar", "amp_short_vectors/Concurrency::graphics::unorm_4::zx", "amp_short_vectors/Concurrency::graphics::unorm_4::xzwy", "amp_short_vectors/Concurrency::graphics::unorm_4::bgr", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xwzy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_w", "amp_short_vectors/Concurrency::graphics::unorm_4::set_yxw", "amp_short_vectors/Concurrency::graphics::unorm_4::wxzy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zywx", "amp_short_vectors/Concurrency::graphics::unorm_4::agrb", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zxwy", "amp_short_vectors/Concurrency::graphics::unorm_4::zxw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xywz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yzw", "amp_short_vectors/Concurrency::graphics::unorm_4::ywzx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wxy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yxzw", "amp_short_vectors/Concurrency::graphics::unorm_4::rgab", "amp_short_vectors/Concurrency::graphics::unorm_4::yxz", "amp_short_vectors/Concurrency::graphics::unorm_4::rbg", "amp_short_vectors/Concurrency::graphics::unorm_4::set_ywz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yzxw", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wy", "amp_short_vectors/Concurrency::graphics::unorm_4::zxwy", "amp_short_vectors/Concurrency::graphics::unorm_4::gr", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xzyw", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wzy", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xzw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zwx", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zy", "amp_short_vectors/Concurrency::graphics::unorm_4::zw", "amp_short_vectors/Concurrency::graphics::unorm_4::xz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zyxw", "amp_short_vectors/Concurrency::graphics::unorm_4::agbr", "amp_short_vectors/Concurrency::graphics::unorm_4::gb", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yxw", "amp_short_vectors/Concurrency::graphics::unorm_4::get_yz", "amp_short_vectors/Concurrency::graphics::unorm_4::operator+=", "amp_short_vectors/Concurrency::graphics::unorm_4::ag", "amp_short_vectors/Concurrency::graphics::unorm_4::grab", "amp_short_vectors/Concurrency::graphics::unorm_4::barg", "amp_short_vectors/Concurrency::graphics::unorm_4::r", "amp_short_vectors/Concurrency::graphics::unorm_4::wx", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wyx", "amp_short_vectors/Concurrency::graphics::unorm_4::abgr", "amp_short_vectors/Concurrency::graphics::unorm_4::yxw", "amp_short_vectors/Concurrency::graphics::unorm_4::z", "amp_short_vectors/Concurrency::graphics::unorm_4::grba", "amp_short_vectors/Concurrency::graphics::unorm_4::operator-=", "amp_short_vectors/Concurrency::graphics::unorm_4::gar", "amp_short_vectors/Concurrency::graphics::unorm_4::operator-", "amp_short_vectors/Concurrency::graphics::unorm_4::xyw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xyw", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wzxy", "amp_short_vectors/Concurrency::graphics::unorm_4::brg", "amp_short_vectors/Concurrency::graphics::unorm_4::wy", "amp_short_vectors/Concurrency::graphics::unorm_4::wxz", "amp_short_vectors/Concurrency::graphics::unorm_4::wxyz", "amp_short_vectors/Concurrency::graphics::unorm_4::wyz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wxz", "amp_short_vectors/Concurrency::graphics::unorm_4::get_xyzw", "amp_short_vectors/Concurrency::graphics::unorm_4::xzw", "amp_short_vectors/Concurrency::graphics::unorm_4::xwyz", "amp_short_vectors/Concurrency::graphics::unorm_4::zwx", "amp_short_vectors/Concurrency::graphics::unorm_4::xy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_zx", "amp_short_vectors/Concurrency::graphics::unorm_4::brga", "amp_short_vectors/Concurrency::graphics::unorm_4::get_zxw", "amp_short_vectors/Concurrency::graphics::unorm_4", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wzyx", "amp_short_vectors/Concurrency::graphics::unorm_4::wzyx", "amp_short_vectors/Concurrency::graphics::unorm_4::yzxw", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wz", "amp_short_vectors/Concurrency::graphics::unorm_4::xwy", "amp_short_vectors/Concurrency::graphics::unorm_4::set_ywxz", "amp_short_vectors/Concurrency::graphics::unorm_4::set_xzy", "amp_short_vectors/Concurrency::graphics::unorm_4::arg", "amp_short_vectors/Concurrency::graphics::unorm_4::set_wyz", "amp_short_vectors/Concurrency::graphics::unorm_4::ywz", "amp_short_vectors/Concurrency::graphics::unorm_4::abrg", "amp_short_vectors/Concurrency::graphics::unorm_4::wyx", "amp_short_vectors/Concurrency::graphics::unorm_4::rb", "amp_short_vectors/Concurrency::graphics::unorm_4::get_wzyx"] -ms.assetid: dd216a9d-95f7-4978-8e78-6cb9c781a7e9 ---- -# unorm_4 Class - -Represents a short vector of four unsigned normal numbers. - -## Syntax - -```cpp -class unorm_4; -``` - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`value_type`|| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[unorm_4 Constructor](#ctor)|Overloaded. Default constructor, initializes all elements with 0.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|unorm_4::get_w|| -|unorm_4::get_wx|| -|unorm_4::get_wxy|| -|unorm_4::get_wxyz|| -|unorm_4::get_wxz|| -|unorm_4::get_wxzy|| -|unorm_4::get_wy|| -|unorm_4::get_wyx|| -|unorm_4::get_wyxz|| -|unorm_4::get_wyz|| -|unorm_4::get_wyzx|| -|unorm_4::get_wz|| -|unorm_4::get_wzx|| -|unorm_4::get_wzxy|| -|unorm_4::get_wzy|| -|unorm_4::get_wzyx|| -|unorm_4::get_x|| -|unorm_4::get_xw|| -|unorm_4::get_xwy|| -|unorm_4::get_xwyz|| -|unorm_4::get_xwz|| -|unorm_4::get_xwzy|| -|unorm_4::get_xy|| -|unorm_4::get_xyw|| -|unorm_4::get_xywz|| -|unorm_4::get_xyz|| -|unorm_4::get_xyzw|| -|unorm_4::get_xz|| -|unorm_4::get_xzw|| -|unorm_4::get_xzwy|| -|unorm_4::get_xzy|| -|unorm_4::get_xzyw|| -|unorm_4::get_y|| -|unorm_4::get_yw|| -|unorm_4::get_ywx|| -|unorm_4::get_ywxz|| -|unorm_4::get_ywz|| -|unorm_4::get_ywzx|| -|unorm_4::get_yx|| -|unorm_4::get_yxw|| -|unorm_4::get_yxwz|| -|unorm_4::get_yxz|| -|unorm_4::get_yxzw|| -|unorm_4::get_yz|| -|unorm_4::get_yzw|| -|unorm_4::get_yzwx|| -|unorm_4::get_yzx|| -|unorm_4::get_yzxw|| -|unorm_4::get_z|| -|unorm_4::get_zw|| -|unorm_4::get_zwx|| -|unorm_4::get_zwxy|| -|unorm_4::get_zwy|| -|unorm_4::get_zwyx|| -|unorm_4::get_zx|| -|unorm_4::get_zxw|| -|unorm_4::get_zxwy|| -|unorm_4::get_zxy|| -|unorm_4::get_zxyw|| -|unorm_4::get_zy|| -|unorm_4::get_zyw|| -|unorm_4::get_zywx|| -|unorm_4::get_zyx|| -|unorm_4::get_zyxw|| -|unorm_4::ref_a|| -|unorm_4::ref_b|| -|unorm_4::ref_g|| -|unorm_4::ref_r|| -|unorm_4::ref_w|| -|unorm_4::ref_x|| -|unorm_4::ref_y|| -|unorm_4::ref_z|| -|unorm_4::set_w|| -|unorm_4::set_wx|| -|unorm_4::set_wxy|| -|unorm_4::set_wxyz|| -|unorm_4::set_wxz|| -|unorm_4::set_wxzy|| -|unorm_4::set_wy|| -|unorm_4::set_wyx|| -|unorm_4::set_wyxz|| -|unorm_4::set_wyz|| -|unorm_4::set_wyzx|| -|unorm_4::set_wz|| -|unorm_4::set_wzx|| -|unorm_4::set_wzxy|| -|unorm_4::set_wzy|| -|unorm_4::set_wzyx|| -|unorm_4::set_x|| -|unorm_4::set_xw|| -|unorm_4::set_xwy|| -|unorm_4::set_xwyz|| -|unorm_4::set_xwz|| -|unorm_4::set_xwzy|| -|unorm_4::set_xy|| -|unorm_4::set_xyw|| -|unorm_4::set_xywz|| -|unorm_4::set_xyz|| -|unorm_4::set_xyzw|| -|unorm_4::set_xz|| -|unorm_4::set_xzw|| -|unorm_4::set_xzwy|| -|unorm_4::set_xzy|| -|unorm_4::set_xzyw|| -|unorm_4::set_y|| -|unorm_4::set_yw|| -|unorm_4::set_ywx|| -|unorm_4::set_ywxz|| -|unorm_4::set_ywz|| -|unorm_4::set_ywzx|| -|unorm_4::set_yx|| -|unorm_4::set_yxw|| -|unorm_4::set_yxwz|| -|unorm_4::set_yxz|| -|unorm_4::set_yxzw|| -|unorm_4::set_yz|| -|unorm_4::set_yzw|| -|unorm_4::set_yzwx|| -|unorm_4::set_yzx|| -|unorm_4::set_yzxw|| -|unorm_4::set_z|| -|unorm_4::set_zw|| -|unorm_4::set_zwx|| -|unorm_4::set_zwxy|| -|unorm_4::set_zwy|| -|unorm_4::set_zwyx|| -|unorm_4::set_zx|| -|unorm_4::set_zxw|| -|unorm_4::set_zxwy|| -|unorm_4::set_zxy|| -|unorm_4::set_zxyw|| -|unorm_4::set_zy|| -|unorm_4::set_zyw|| -|unorm_4::set_zywx|| -|unorm_4::set_zyx|| -|unorm_4::set_zyxw|| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|unorm_4::operator-|| -|unorm_4::operator--|| -|unorm_4::operator*=|| -|unorm_4::operator/=|| -|unorm_4::operator++|| -|unorm_4::operator+=|| -|unorm_4::operator=|| -|unorm_4::operator-=|| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[size Constant](#unorm_4__size)|| - -### Public Data Members - -|Name|Description| -|----------|-----------------| -|unorm_4::a|| -|unorm_4::ab|| -|unorm_4::abg|| -|unorm_4::abgr|| -|unorm_4::abr|| -|unorm_4::abrg|| -|unorm_4::ag|| -|unorm_4::agb|| -|unorm_4::agbr|| -|unorm_4::agr|| -|unorm_4::agrb|| -|unorm_4::ar|| -|unorm_4::arb|| -|unorm_4::arbg|| -|unorm_4::arg|| -|unorm_4::argb|| -|unorm_4::b|| -|unorm_4::ba|| -|unorm_4::bag|| -|unorm_4::bagr|| -|unorm_4::bar|| -|unorm_4::barg|| -|unorm_4::bg|| -|unorm_4::bga|| -|unorm_4::bgar|| -|unorm_4::bgr|| -|unorm_4::bgra|| -|unorm_4::br|| -|unorm_4::bra|| -|unorm_4::brag|| -|unorm_4::brg|| -|unorm_4::brga|| -|unorm_4::g|| -|unorm_4::ga|| -|unorm_4::gab|| -|unorm_4::gabr|| -|unorm_4::gar|| -|unorm_4::garb|| -|unorm_4::gb|| -|unorm_4::gba|| -|unorm_4::gbar|| -|unorm_4::gbr|| -|unorm_4::gbra|| -|unorm_4::gr|| -|unorm_4::gra|| -|unorm_4::grab|| -|unorm_4::grb|| -|unorm_4::grba|| -|unorm_4::r|| -|unorm_4::ra|| -|unorm_4::rab|| -|unorm_4::rabg|| -|unorm_4::rag|| -|unorm_4::ragb|| -|unorm_4::rb|| -|unorm_4::rba|| -|unorm_4::rbag|| -|unorm_4::rbg|| -|unorm_4::rbga|| -|unorm_4::rg|| -|unorm_4::rga|| -|unorm_4::rgab|| -|unorm_4::rgb|| -|unorm_4::rgba|| -|unorm_4::w|| -|unorm_4::wx|| -|unorm_4::wxy|| -|unorm_4::wxyz|| -|unorm_4::wxz|| -|unorm_4::wxzy|| -|unorm_4::wy|| -|unorm_4::wyx|| -|unorm_4::wyxz|| -|unorm_4::wyz|| -|unorm_4::wyzx|| -|unorm_4::wz|| -|unorm_4::wzx|| -|unorm_4::wzxy|| -|unorm_4::wzy|| -|unorm_4::wzyx|| -|unorm_4::x|| -|unorm_4::xw|| -|unorm_4::xwy|| -|unorm_4::xwyz|| -|unorm_4::xwz|| -|unorm_4::xwzy|| -|unorm_4::xy|| -|unorm_4::xyw|| -|unorm_4::xywz|| -|unorm_4::xyz|| -|unorm_4::xyzw|| -|unorm_4::xz|| -|unorm_4::xzw|| -|unorm_4::xzwy|| -|unorm_4::xzy|| -|unorm_4::xzyw|| -|unorm_4::y|| -|unorm_4::yw|| -|unorm_4::ywx|| -|unorm_4::ywxz|| -|unorm_4::ywz|| -|unorm_4::ywzx|| -|unorm_4::yx|| -|unorm_4::yxw|| -|unorm_4::yxwz|| -|unorm_4::yxz|| -|unorm_4::yxzw|| -|unorm_4::yz|| -|unorm_4::yzw|| -|unorm_4::yzwx|| -|unorm_4::yzx|| -|unorm_4::yzxw|| -|unorm_4::z|| -|unorm_4::zw|| -|unorm_4::zwx|| -|unorm_4::zwxy|| -|unorm_4::zwy|| -|unorm_4::zwyx|| -|unorm_4::zx|| -|unorm_4::zxw|| -|unorm_4::zxwy|| -|unorm_4::zxy|| -|unorm_4::zxyw|| -|unorm_4::zy|| -|unorm_4::zyw|| -|unorm_4::zywx|| -|unorm_4::zyx|| -|unorm_4::zyxw|| - -## Inheritance Hierarchy - -`unorm_4` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## unorm_4 - -Default constructor, initializes all elements with 0. - -```cpp -unorm_4() restrict(amp, - cpu); - -unorm_4( - unorm _V0, - unorm _V1, - unorm _V2, - unorm _V3) restrict(amp, - cpu); - -unorm_4( - float _V0, - float _V1, - float _V2, - float _V3) restrict(amp, - cpu); - -unorm_4( - unorm _V) restrict(amp, - cpu); - -explicit unorm_4( - float _V) restrict(amp, - cpu); - -unorm_4( - const unorm_4& _Other) restrict(amp, - cpu); - -explicit inline unorm_4( - const uint_4& _Other) restrict(amp, - cpu); - -explicit inline unorm_4( - const int_4& _Other) restrict(amp, - cpu); - -explicit inline unorm_4( - const float_4& _Other) restrict(amp, - cpu); - -explicit inline unorm_4( - const norm_4& _Other) restrict(amp, - cpu); - -explicit inline unorm_4( - const double_4& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V0*
-The value to initialize element 0. - -*_V1*
-The value to initialize element 1. - -*_V2*
-The value to initialize element 2. - -*_V3*
-The value to initialize element 3. - -*_V*
-The value for initialization. - -*_Other*
-The object used to initialize. - -## size - -```cpp -static const int size = 4; -``` - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/unorm-class.md b/docs/parallel/amp/reference/unorm-class.md deleted file mode 100644 index a59ea39f7c5..00000000000 --- a/docs/parallel/amp/reference/unorm-class.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -description: "Learn more about: unorm Class" -title: "unorm Class" -ms.date: "11/04/2016" -f1_keywords: ["unorm", "AMP_SHORT_VECTORS/unorm", "AMP_SHORT_VECTORS/Concurrency::graphics::unorm Constructor"] -ms.assetid: bc30bd20-6452-4d5f-9158-3b11c4c16ed2 ---- -# unorm Class - -Represent a unorm number. Each element is a floating point number in the range of [0.0f, 1.0f]. - -## Syntax - -```cpp -class unorm; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[unorm Constructor](#ctor)|Overloaded. Default constructor. Initialize to 0.0f.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|unorm::operator--|| -|unorm::operator float|Conversion operator. Convert the unorm number to a floating point value.| -|unorm::operator*=|| -|unorm::operator/=|| -|unorm::operator++|| -|unorm::operator+=|| -|unorm::operator=|| -|unorm::operator-=|| - -## Inheritance Hierarchy - -`unorm` - -## Requirements - -**Header:** amp_short_vectors.h - -**Namespace:** Concurrency::graphics - -## unorm - -Default constructor. Initialize to 0.0f. - -```cpp -unorm( - void) restrict(amp, - cpu); - -explicit unorm( - float _V) restrict(amp, - cpu); - -explicit unorm( - unsigned int _V) restrict(amp, - cpu); - -explicit unorm( - int _V) restrict(amp, - cpu); - -explicit unorm( - double _V) restrict(amp, - cpu); - -unorm( - const unorm& _Other) restrict(amp, - cpu); - -inline explicit unorm( - const norm& _Other) restrict(amp, - cpu); -``` - -### Parameters - -*_V*
-The value used to initialize. - -*_Other*
-The norm object used to initialize. - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/reference/unsupported-feature-class.md b/docs/parallel/amp/reference/unsupported-feature-class.md deleted file mode 100644 index 637c3551bbd..00000000000 --- a/docs/parallel/amp/reference/unsupported-feature-class.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -description: "Learn more about: unsupported_feature Class" -title: "unsupported_feature Class" -ms.date: "03/27/2019" -f1_keywords: ["unsupported_feature", "AMPRT/unsupported_feature", "AMPRT/Concurrency::unsupported_feature"] -helpviewer_keywords: ["unsupported_feature class"] -ms.assetid: 6b1ab917-df13-48c7-9648-7cb2465a0ff5 ---- -# unsupported_feature Class - -The exception that is thrown when an unsupported feature is used. - -## Syntax - -```cpp -class unsupported_feature : public runtime_exception; -``` - -## Members - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[unsupported_feature Constructor](#unsupported_feature)|Constructs a new instance of the `unsupported_feature` exception.| - -## Inheritance Hierarchy - -`exception` - -`runtime_exception` - -`unsupported_feature` - -## unsupported_feature - - Constructs a new instance of the `unsupported_feature` exception. - -### Syntax - -```cpp -explicit unsupported_feature( - const char * _Message ) throw(); - -unsupported_feature() throw(); -``` - -### Parameters - -*_Message*
-A description of the error. - -### Return Value - -The `unsupported_feature` object. - -## Requirements - -**Header:** amprt.h - -**Namespace:** Concurrency - -## See also - -[Concurrency Namespace (C++ AMP)](concurrency-namespace-cpp-amp.md) diff --git a/docs/parallel/amp/reference/writeonly-texture-view-class.md b/docs/parallel/amp/reference/writeonly-texture-view-class.md deleted file mode 100644 index cedd6714dc1..00000000000 --- a/docs/parallel/amp/reference/writeonly-texture-view-class.md +++ /dev/null @@ -1,161 +0,0 @@ ---- -description: "Learn more about: writeonly_texture_view Class" -title: "writeonly_texture_view Class" -ms.date: "11/04/2016" -f1_keywords: ["writeonly_texture_view", "AMP_GRAPHICS/writeonly_texture_view", "AMP_GRAPHICS/Concurrency::graphics::writeonly_texture_view", "AMP_GRAPHICS/Concurrency::graphics::writeonly_texture_view::set", "AMP_GRAPHICS/Concurrency::graphics::rank Constant"] -ms.assetid: 8d117ad3-0a1c-41ae-b29c-7c95fdd4d04d ---- -# writeonly_texture_view Class - -Provides writeonly access to a texture. - -## Syntax - -```cpp -template < - typename value_type, - int _Rank -> -class writeonly_texture_view; - -template < - typename value_type, - int _Rank -> -class writeonly_texture_view : public details::_Texture_base; -``` - -### Parameters - -*value_type*
-The type of the elements in the texture. - -*_Rank*
-The rank of the texture. - -## Members - -### Public Typedefs - -|Name|Description| -|----------|-----------------| -|`scalar_type`|| -|`value_type`|The type of the elements in the texture.| - -### Public Constructors - -|Name|Description| -|----------|-----------------| -|[writeonly_texture_view Constructor](#ctor)|Initializes a new instance of the `writeonly_texture_view` class.| -|[~writeonly_texture_view Destructor](#ctor)|Destroys the `writeonly_texture_view` object.| - -### Public Methods - -|Name|Description| -|----------|-----------------| -|[set](#set)|Sets the value of the element at the specified index.| - -### Public Operators - -|Name|Description| -|----------|-----------------| -|[operator=](#operator_eq)|Copies the specified `writeonly_texture_view` object to this one.| - -### Public Constants - -|Name|Description| -|----------|-----------------| -|[rank Constant](#rank)|Gets the rank of the `writeonly_texture_view` object.| - -## Inheritance Hierarchy - -`_Texture_base` - -`writeonly_texture_view` - -## Requirements - -**Header:** amp_graphics.h - -**Namespace:** Concurrency::graphics - -## ~writeonly_texture_view - -Destroys the `writeonly_texture_view` object. - -```cpp -~writeonly_texture_view() restrict(amp,cpu); -``` - -## operator= - -Copies the specified `writeonly_texture_view` object to this one. - -```cpp -writeonly_texture_view& operator= ( - const writeonly_texture_view& _Other) restrict(amp,cpu); -``` - -### Parameters - -*_Other*
-`writeonly_texture_view` object to copy from. - -### Return Value - -A reference to this `writeonly_texture_view` object. - -## rank - -Gets the rank of the `writeonly_texture_view` object. - -```cpp -static const int rank = _Rank; -``` - -## set - -Sets the value of the element at the specified index. - -```cpp -void set( - const index<_Rank>& _Index, - const value_type& value) const restrict(amp); -``` - -### Parameters - -*_Index*
-The index of the element. - -*value*
-The new value of the element. - -## writeonly_texture_view - -Initializes a new instance of the `writeonly_texture_view` class. - -```cpp -writeonly_texture_view( - texture& _Src) restrict(amp); - -writeonly_texture_view( - const writeonly_texture_view& _Src) restrict(amp,cpu); -``` - -### Parameters - -*_Rank*
-The rank of the texture. - -*value_type*
-The type of the elements in the texture. - -*_Src*
-The texture that is used to create the `writeonly_texture_view`. - -## See also - -[Concurrency::graphics Namespace](concurrency-graphics-namespace.md) diff --git a/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md b/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md deleted file mode 100644 index 7561a885f87..00000000000 --- a/docs/parallel/amp/using-accelerator-and-accelerator-view-objects.md +++ /dev/null @@ -1,180 +0,0 @@ ---- -description: "Learn more about: Using accelerator and accelerator_view Objects" -title: "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. - -## Using the Default Accelerator - -The C++ AMP runtime picks a default accelerator, unless you write code to pick a specific one. The runtime chooses the default accelerator as follows: - -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. - -3. Otherwise, a non-emulated device. - -4. Otherwise, the device that has the greatest amount of available memory. - -5. Otherwise, a device that's not attached to the display. - -Additionally, the runtime specifies an `access_type` of `access_type_auto` for the default accelerator. This means that the default accelerator uses shared memory if it’s supported and if its performance characteristics (bandwidth and latency) are known to be the same as dedicated (non-shared) memory. - -You can determine the properties of the default accelerator by constructing the default accelerator and examining its properties. The following code example prints the path, amount of accelerator memory, shared memory support, double-precision support, and limited double-precision support of the default accelerator. - -```cpp -void default_properties() { - accelerator default_acc; - std::wcout << default_acc.device_path << "\n"; - std::wcout << default_acc.dedicated_memory << "\n"; - std::wcout << (accs[i].supports_cpu_shared_memory ? - "CPU shared memory: true" : "CPU shared memory: false") << "\n"; - std::wcout << (accs[i].supports_double_precision ? - "double precision: true" : "double precision: false") << "\n"; - std::wcout << (accs[i].supports_limited_double_precision ? - "limited double precision: true" : "limited double precision: false") << "\n"; -} -``` - -### 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. - -```cpp -void list_all_accelerators() -{ - std::vector accs = accelerator::get_all(); - - for (int i = 0; i accs = accelerator::get_all(); - accelerator acc_chosen = accs[0]; - - for (int i = 0; i acc_chosen.dedicated_memory) { - acc_chosen = accs[i]; - } - } - - std::wcout << "The accelerator with the most memory is " - << acc_chosen.device_path << "\n" - << acc_chosen.dedicated_memory << ".\n"; -} -``` - -> [!NOTE] -> One of the accelerators that are returned by `accelerator::get_all` is the CPU accelerator. You cannot execute code on the CPU accelerator. To filter out the CPU accelerator, compare the value of the [device_path](reference/accelerator-class.md#device_path) property of the accelerator that's returned by `accelerator::get_all` with the value of the [accelerator::cpu_accelerator](reference/accelerator-class.md#cpu_accelerator). For more information, see the "Special Accelerators" section in this article. - -## Shared Memory - -Shared memory is memory that can be accessed by both the CPU and the accelerator. The use of shared memory eliminates or significantly reduces the overhead of copying data between the CPU and the accelerator. Although the memory is shared, it cannot be accessed concurrently by both the CPU and the accelerator, and doing so causes undefined behavior. The accelerator property [supports_cpu_shared_memory](reference/accelerator-class.md#supports_cpu_shared_memory) returns **`true`** if the accelerator supports shared memory, and the [default_cpu_access_type](reference/accelerator-class.md#default_cpu_access_type) property gets the default [access_type](reference/concurrency-namespace-enums-amp.md#access_type) for memory allocated on the `accelerator`—for example, **array**s associated with the `accelerator`, or `array_view` objects accessed on the `accelerator`. - -The C++ AMP runtime automatically chooses the best default `access_type` for each `accelerator`, but the performance characteristics (bandwidth and latency) of shared memory can be worse than those of dedicated (non-shared) accelerator memory when reading from the CPU, writing from the CPU, or both. If shared memory performs as well as dedicated memory for reading and writing from the CPU, the runtime defaults to `access_type_read_write`; otherwise, the runtime chooses a more conservative default `access_type`, and allows the app to override it if the memory access patterns of its computation kernels benefit from a different `access_type`. - -The following code example shows how to determine whether the default accelerator supports shared memory, and then overrides its default access type and creates an `accelerator_view` from it. - -```cpp -#include -#include - -using namespace Concurrency; - -int main() -{ - accelerator acc = accelerator(accelerator::default_accelerator); - - // Early out if the default accelerator doesn’t support shared memory. - if (!acc.supports_cpu_shared_memory) - { - std::cout << "The default accelerator does not support shared memory" << std::endl; - return 1; - } - - // Override the default CPU access type. - acc.set_default_cpu_access_type(access_type_read_write); - - // Create an accelerator_view from the default accelerator. The - // accelerator_view reflects the default_cpu_access_type of the - // accelerator it’s associated with. - accelerator_view acc_v = acc.default_view; -} -``` - -An `accelerator_view` always reflects the `default_cpu_access_type` of the `accelerator` it’s associated with, and it provides no interface to override or change its `access_type`. - -## Changing the Default Accelerator - -You can change the default accelerator by calling the `accelerator::set_default` method. You can change the default accelerator only once per app execution and you must change it before any code is executed on the GPU. Any subsequent function calls to change the accelerator return **`false`**. If you want to use a different accelerator in a call to `parallel_for_each`, read the "Using Multiple Accelerators" section in this article. The following code example sets the default accelerator to one that is not emulated, is not connected to a display, and supports double-precision. - -```cpp -bool pick_accelerator() -{ - std::vector accs = accelerator::get_all(); - accelerator chosen_one; - - auto result = std::find_if(accs.begin(), accs.end(), - [] (const accelerator& acc) { - return !acc.is_emulated && - acc.supports_double_precision && - !acc.has_display; - }); - - if (result != accs.end()) { - chosen_one = *(result); - } - - std::wcout < -[Debugging GPU Code](/visualstudio/debugger/debugging-gpu-code)
-[accelerator_view Class](../../parallel/amp/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 deleted file mode 100644 index 6737d1ba3a4..00000000000 --- a/docs/parallel/amp/using-cpp-amp-in-windows-store-apps.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -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. - -## Performance considerations - -If you're using Visual C++ component extensions C++/CX to create your Universal Windows Platform (UWP) app, we recommend that you use plain-old-data (POD) types together with contiguous storage—for example, `std::vector` or C-style arrays—for data that will be used with C++ AMP. This can help you achieve higher performance than by using non-POD types or Windows RT containers because no marshaling has to occur. - -In a C++ AMP kernel, to access data that’s stored in this way, just wrap the `std::vector` or array storage in a `concurrency::array_view` and then use the array view in a `concurrency::parallel_for_each` loop: - -```cpp -// simple vector addition example -std::vector data0(1024, 1); -std::vector data1(1024, 2); -std::vector data_out(data0.size(), 0); - -concurrency::array_view av0(data0.size(), data0); -concurrency::array_view av1(data1.size(), data1); -concurrency::array_view av2(data_out.size(), data2); - -av2.discard_data(); - -concurrency::parallel_for_each(av0.extent, [=](concurrency::index<1> idx) restrict(amp) - { - av2[idx] = av0[idx] + av1[idx]; - }); -``` - -## Marshaling Windows Runtime types - -When you work with Windows Runtime APIs, you might want to use C++ AMP on data that's stored in a Windows Runtime container such as a `Platform::Array^` or in complex data types such as classes or structs that are declared by using the **ref** keyword or the **value** keyword. In these situations, you have to do some extra work to make the data available to C++ AMP. - -### Platform::Array\^, where T is a POD type - -When you encounter a `Platform::Array^` and T is a POD type, you can access its underlying storage just by using the `get` member function: - -```cpp -Platform::Array^ arr; // Assume that this was returned by a Windows Runtime API -concurrency::array_view av(arr->Length, &arr->get(0)); -``` - -If T is not a POD type, use the technique that's described in the following section to use the data with C++ AMP. - -### Windows Runtime types: ref classes and value classes - -C++ AMP doesn't support complex data types. This includes non-POD types and any types that are declared by using the **ref** keyword or the **value** keyword. If an unsupported type is used in a `restrict(amp)` context, a compile-time error is generated. - -When you encounter an unsupported type, you can copy interesting parts of its data into a `concurrency::array` object. In addition to making the data available for C++ AMP to consume, this manual-copy approach can also improve performance by maximizing data locality, and by ensuring that data that won't be used isn't copied to the accelerator. You can improve performance further by using a *staging array*, which is a special form of `concurrency::array` that provides a hint to the AMP runtime that the array should be optimized for frequent transfer between it and other arrays on the specified accelerator. - -```cpp -// pixel_color.h -ref class pixel_color sealed -{ -public: - pixel_color(Platform::String^ color_name, int red, int green, int blue) - { - name = color_name; - r = red; - g = green; - b = blue; - } - - property Platform::String^ name; - property int r; - property int g; - property int b; -}; - -// Some other file - -std::vector pixels (256); - -for (pixel_color ^pixel : pixels) -{ - pixels.push_back(ref new pixel_color("blue", 0, 0, 255)); -} - -// Create the accelerators -auto cpuAccelerator = concurrency::accelerator(concurrency::accelerator::cpu_accelerator); -auto devAccelerator = concurrency::accelerator(concurrency::accelerator::default_accelerator); - -// Create the staging arrays -concurrency::array red_vec(256, cpuAccelerator.default_view, devAccelerator.default_view); -concurrency::array blue_vec(256, cpuAccelerator.default_view, devAccelerator.default_view); - -// Extract data from the complex array of structs into staging arrays. -concurrency::parallel_for(0, 256, [&](int i) - { - red_vec[i] = pixels[i]->r; - blue_vec[i] = pixels[i]->b; - }); - -// Array views are still used to copy data to the accelerator -concurrency::array_view av_red(red_vec); -concurrency::array_view av_blue(blue_vec); - -// Change all pixels from blue to red. -concurrency::parallel_for_each(av_red.extent, [=](index<1> idx) restrict(amp) - { - av_red[idx] = 255; - av_blue[idx] = 0; - }); -``` - -## See also - -[Create your first UWP app using C++](/windows/uwp/get-started/create-a-basic-windows-10-app-in-cpp)
-[Creating Windows Runtime Components in C++](/windows/uwp/winrt-components/creating-windows-runtime-components-in-cpp) 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 deleted file mode 100644 index a8e3b67b6a9..00000000000 --- a/docs/parallel/amp/using-lambdas-function-objects-and-restricted-functions.md +++ /dev/null @@ -1,159 +0,0 @@ ---- -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. - -```cpp -void CpuMethod() { - - int aCPP[] = {1, 2, 3, 4, 5}; - int bCPP[] = {6, 7, 8, 9, 10}; - int sumCPP[5]; - - for (int idx = 0; idx <5; idx++) - { - sumCPP[idx] = aCPP[idx] + bCPP[idx]; - } - - for (int idx = 0; idx <5; idx++) - { - std::cout < a(5, aCPP); - - array_view b(5, bCPP); - - array_view sum(5, sumCPP); - - sum.discard_data(); - - parallel_for_each( - sum.extent, - [=](index<1> idx) restrict(amp) - { - sum[idx] = a[idx] + b[idx]; - }); - - for (int i = 0; i <5; i++) { - std::cout <& a, - const array_view& b, - const array_view& sum) - : a(a), b(b), sum(sum) - { - } - - void operator()(index<1> idx) restrict(amp) - { - sum[idx] = a[idx] + b[idx]; - } - -private: - array_view a; - array_view b; - array_view sum; -}; - -void AddArraysWithFunctionObject() { - int aCPP[] = {1, 2, 3, 4, 5}; - int bCPP[] = {6, 7, 8, 9, 10}; - int sumCPP[5]; - - array_view a(5, aCPP); - - array_view b(5, bCPP); - - array_view sum(5, sumCPP); - - sum.discard_data(); - - parallel_for_each( - sum.extent, - AdditionFunctionObject(a, b, sum)); - - for (int i = 0; i <5; i++) { - std::cout < idx, array_view sum, array_view a, array_view b) restrict(amp) -{ - sum[idx] = a[idx] + b[idx]; -} - -void AddArraysWithFunction() { - - int aCPP[] = {1, 2, 3, 4, 5}; - int bCPP[] = {6, 7, 8, 9, 10}; - int sumCPP[5]; - - array_view a(5, aCPP); - - array_view b(5, bCPP); - - array_view sum(5, sumCPP); - - sum.discard_data(); - - parallel_for_each( - sum.extent, - [=](index<1> idx) restrict(amp) - { - AddElementsWithRestrictedFunction(idx, sum, a, b); - }); - - for (int i = 0; i <5; i++) { - std::cout < -[Lambda Expression Syntax](../../cpp/lambda-expression-syntax.md)
-[Function Call](../../cpp/function-call-cpp.md)
-[Function Objects in the C++ Standard Library](../../standard-library/function-objects-in-the-stl.md)
-[restrict (C++ AMP)](../../cpp/restrict-cpp-amp.md) diff --git a/docs/parallel/amp/using-tiles.md b/docs/parallel/amp/using-tiles.md deleted file mode 100644 index f315d7bc8cf..00000000000 --- a/docs/parallel/amp/using-tiles.md +++ /dev/null @@ -1,330 +0,0 @@ ---- -description: "Learn more about: Using Tiles" -title: "Using Tiles" -ms.date: "11/19/2018" -ms.assetid: acb86a86-2b7f-43f1-8fcf-bcc79b21d9a8 ---- -# Using Tiles - -You can use tiling to maximize the acceleration of your app. Tiling divides threads into equal rectangular subsets or *tiles*. If you use an appropriate tile size and tiled algorithm, you can get even more acceleration from your C++ AMP code. The basic components of tiling are: - -- `tile_static` variables. The primary benefit of tiling is the performance gain from `tile_static` access. Access to data in `tile_static` memory can be significantly faster than access to data in the global space (`array` or `array_view` objects). An instance of a `tile_static` variable is created for each tile, and all threads in the tile have access to the variable. In a typical tiled algorithm, data is copied into `tile_static` memory once from global memory and then accessed many times from the `tile_static` memory. - -- [tile_barrier::wait Method](reference/tile-barrier-class.md#wait). A call to `tile_barrier::wait` suspends execution of the current thread until all of the threads in the same tile reach the call to `tile_barrier::wait`. You cannot guarantee the order that the threads will run in, only that no threads in the tile will execute past the call to `tile_barrier::wait` until all of the threads have reached the call. This means that by using the `tile_barrier::wait` method, you can perform tasks on a tile-by-tile basis rather than a thread-by-thread basis. A typical tiling algorithm has code to initialize the `tile_static` memory for the whole tile followed by a call to `tile_barrier::wait`. Code that follows `tile_barrier::wait` contains computations that require access to all the `tile_static` values. - -- Local and global indexing. You have access to the index of the thread relative to the entire `array_view` or `array` object and the index relative to the tile. Using the local index can make your code easier to read and debug. Typically, you use local indexing to access `tile_static` variables, and global indexing to access `array` and `array_view` variables. - -- [tiled_extent Class](../../parallel/amp/reference/tiled-extent-class.md) and [tiled_index Class](../../parallel/amp/reference/tiled-index-class.md). You use a `tiled_extent` object instead of an `extent` object in the `parallel_for_each` call. You use a `tiled_index` object instead of an `index` object in the `parallel_for_each` call. - -To take advantage of tiling, your algorithm must partition the compute domain into tiles and then copy the tile data into `tile_static` variables for faster access. - -## Example of Global, Tile, and Local Indices - -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) - -The following example displays the global, tile, and local indices of this tiled matrix. An `array_view` object is created by using elements of type `Description`. The `Description` holds the global, tile, and local indices of the element in the matrix. The code in the call to `parallel_for_each` sets the values of the global, tile, and local indices of each element. The output displays the values in the `Description` structures. - -```cpp -#include -#include -#include -#include -using namespace concurrency; - -const int ROWS = 8; -const int COLS = 9; - -// tileRow and tileColumn specify the tile that each thread is in. -// globalRow and globalColumn specify the location of the thread in the array_view. -// localRow and localColumn specify the location of the thread relative to the tile. -struct Description { - int value; - int tileRow; - int tileColumn; - int globalRow; - int globalColumn; - int localRow; - int localColumn; -}; - -// A helper function for formatting the output. -void SetConsoleColor(int color) { - int colorValue = (color == 0) 4 : 2; - SetConsoleTextAttribute(GetStdHandle(STD_OUTPUT_HANDLE), colorValue); -} - -// A helper function for formatting the output. -void SetConsoleSize(int height, int width) { - COORD coord; - - coord.X = width; - coord.Y = height; - SetConsoleScreenBufferSize(GetStdHandle(STD_OUTPUT_HANDLE), coord); - - SMALL_RECT* rect = new SMALL_RECT(); - rect->Left = 0; - rect->Top = 0; - rect->Right = width; - rect->Bottom = height; - SetConsoleWindowInfo(GetStdHandle(STD_OUTPUT_HANDLE), true, rect); -} - -// This method creates an 8x9 matrix of Description structures. -// In the call to parallel_for_each, the structure is updated -// with tile, global, and local indices. -void TilingDescription() { - // Create 72 (8x9) Description structures. - std::vector descs; - for (int i = 0; i < ROWS * COLS; i++) { - Description d = {i, 0, 0, 0, 0, 0, 0}; - descs.push_back(d); - } - - // Create an array_view from the Description structures. - extent<2> matrix(ROWS, COLS); - array_view descriptions(matrix, descs); - - // Update each Description with the tile, global, and local indices. - parallel_for_each(descriptions.extent.tile< 2, 3>(), - [=] (tiled_index< 2, 3> t_idx) restrict(amp) - { - descriptions[t_idx].globalRow = t_idx.global[0]; - descriptions[t_idx].globalColumn = t_idx.global[1]; - descriptions[t_idx].tileRow = t_idx.tile[0]; - descriptions[t_idx].tileColumn = t_idx.tile[1]; - descriptions[t_idx].localRow = t_idx.local[0]; - descriptions[t_idx].localColumn= t_idx.local[1]; - }); - - // Print out the Description structure for each element in the matrix. - // Tiles are displayed in red and green to distinguish them from each other. - SetConsoleSize(100, 150); - for (int row = 0; row < ROWS; row++) { - for (int column = 0; column < COLS; column++) { - SetConsoleColor((descriptions(row, column).tileRow + descriptions(row, column).tileColumn) % 2); - std::cout << "Value: " << std::setw(2) << descriptions(row, column).value << " "; - } - std::cout << "\n"; - - for (int column = 0; column < COLS; column++) { - SetConsoleColor((descriptions(row, column).tileRow + descriptions(row, column).tileColumn) % 2); - std::cout << "Tile: " << "(" << descriptions(row, column).tileRow << "," << descriptions(row, column).tileColumn << ") "; - } - std::cout << "\n"; - - for (int column = 0; column < COLS; column++) { - SetConsoleColor((descriptions(row, column).tileRow + descriptions(row, column).tileColumn) % 2); - std::cout << "Global: " << "(" << descriptions(row, column).globalRow << "," << descriptions(row, column).globalColumn << ") "; - } - std::cout << "\n"; - - for (int column = 0; column < COLS; column++) { - SetConsoleColor((descriptions(row, column).tileRow + descriptions(row, column).tileColumn) % 2); - std::cout << "Local: " << "(" << descriptions(row, column).localRow << "," << descriptions(row, column).localColumn << ") "; - } - std::cout << "\n"; - std::cout << "\n"; - } -} - -int main() { - TilingDescription(); - char wait; - std::cin >> wait; -} -``` - -The main work of the example is in the definition of the `array_view` object and the call to `parallel_for_each`. - -1. The vector of `Description` structures is copied into an 8x9 `array_view` object. - -2. The `parallel_for_each` method is called with a `tiled_extent` object as the compute domain. The `tiled_extent` object is created by calling the `extent::tile()` method of the `descriptions` variable. The type parameters of the call to `extent::tile()`, `<2,3>`, specify that 2x3 tiles are created. Thus, the 8x9 matrix is tiled into 12 tiles, four rows and three columns. - -3. The `parallel_for_each` method is called by using a `tiled_index<2,3>` object (`t_idx`) as the index. The type parameters of the index (`t_idx`) must match the type parameters of the compute domain (`descriptions.extent.tile< 2, 3>()`). - -4. When each thread is executed, the index `t_idx` returns information about which tile the thread is in (`tiled_index::tile` property) and the location of the thread within the tile (`tiled_index::local` property). - -## Tile Synchronization—tile_static and tile_barrier::wait - -The previous example illustrates the tile layout and indices, but is not in itself very useful. Tiling becomes useful when the tiles are integral to the algorithm and exploit `tile_static` variables. Because all threads in a tile have access to `tile_static` variables, calls to `tile_barrier::wait` are used to synchronize access to the `tile_static` variables. Although all of the threads in a tile have access to the `tile_static` variables, there is no guaranteed order of execution of threads in the tile. The following example shows how to use `tile_static` variables and the `tile_barrier::wait` method to calculate the average value of each tile. Here are the keys to understanding the example: - -1. The rawData is stored in an 8x8 matrix. - -2. The tile size is 2x2. This creates a 4x4 grid of tiles and the averages can be stored in a 4x4 matrix by using an `array` object. There are only a limited number of types that you can capture by reference in an AMP-restricted function. The `array` class is one of them. - -3. The matrix size and sample size are defined by using `#define` statements, because the type parameters to `array`, `array_view`, `extent`, and `tiled_index` must be constant values. You can also use `const int static` declarations. As an additional benefit, it is trivial to change the sample size to calculate the average over 4x4 tiles. - -4. A `tile_static` 2x2 array of float values is declared for each tile. Although the declaration is in the code path for every thread, only one array is created for each tile in the matrix. - -5. There is a line of code to copy the values in each tile to the `tile_static` array. For each thread, after the value is copied to the array, execution on the thread stops due to the call to `tile_barrier::wait`. - -6. When all of the threads in a tile have reached the barrier, the average can be calculated. Because the code executes for every thread, there is an `if` statement to only calculate the average on one thread. The average is stored in the averages variable. The barrier is essentially the construct that controls calculations by tile, much as you might use a **`for`** loop. - -7. The data in the `averages` variable, because it is an `array` object, must be copied back to the host. This example uses the vector conversion operator. - -8. In the complete example, you can change SAMPLESIZE to 4 and the code executes correctly without any other changes. - -```cpp -#include -#include -using namespace concurrency; - -#define SAMPLESIZE 2 -#define MATRIXSIZE 8 -void SamplingExample() { - - // Create data and array_view for the matrix. - std::vector rawData; - for (int i = 0; i < MATRIXSIZE * MATRIXSIZE; i++) { - rawData.push_back((float)i); - } - extent<2> dataExtent(MATRIXSIZE, MATRIXSIZE); - array_view matrix(dataExtent, rawData); - - // Create the array for the averages. - // There is one element in the output for each tile in the data. - std::vector outputData; - int outputSize = MATRIXSIZE / SAMPLESIZE; - for (int j = 0; j < outputSize * outputSize; j++) { - outputData.push_back((float)0); - } - extent<2> outputExtent(MATRIXSIZE / SAMPLESIZE, MATRIXSIZE / SAMPLESIZE); - array averages(outputExtent, outputData.begin(), outputData.end()); - - // Use tiles that are SAMPLESIZE x SAMPLESIZE. - // Find the average of the values in each tile. - // The only reference-type variable you can pass into the parallel_for_each call - // is a concurrency::array. - parallel_for_each(matrix.extent.tile(), - [=, &averages] (tiled_index t_idx) restrict(amp) - { - // Copy the values of the tile into a tile-sized array. - tile_static float tileValues[SAMPLESIZE][SAMPLESIZE]; - tileValues[t_idx.local[0]][t_idx.local[1]] = matrix[t_idx]; - - // Wait for the tile-sized array to load before you calculate the average. - t_idx.barrier.wait(); - - // If you remove the if statement, then the calculation executes for every - // thread in the tile, and makes the same assignment to averages each time. - if (t_idx.local[0] == 0 && t_idx.local[1] == 0) { - for (int trow = 0; trow < SAMPLESIZE; trow++) { - for (int tcol = 0; tcol < SAMPLESIZE; tcol++) { - averages(t_idx.tile[0],t_idx.tile[1]) += tileValues[trow][tcol]; - } - } - averages(t_idx.tile[0],t_idx.tile[1]) /= (float) (SAMPLESIZE * SAMPLESIZE); - } - }); - - // Print out the results. - // You cannot access the values in averages directly. You must copy them - // back to a CPU variable. - outputData = averages; - for (int row = 0; row < outputSize; row++) { - for (int col = 0; col < outputSize; col++) { - std::cout << outputData[row*outputSize + col] << " "; - } - std::cout << "\n"; - } - // Output for SAMPLESIZE = 2 is: - // 4.5 6.5 8.5 10.5 - // 20.5 22.5 24.5 26.5 - // 36.5 38.5 40.5 42.5 - // 52.5 54.5 56.5 58.5 - - // Output for SAMPLESIZE = 4 is: - // 13.5 17.5 - // 45.5 49.5 -} - -int main() { - SamplingExample(); -} -``` - -## Race Conditions - -It might be tempting to create a `tile_static` variable named `total` and increment that variable for each thread, like this: - -```cpp -// Do not do this. -tile_static float total; -total += matrix[t_idx]; -t_idx.barrier.wait(); - -averages(t_idx.tile[0],t_idx.tile[1]) /= (float) (SAMPLESIZE* SAMPLESIZE); -``` - -The first problem with this approach is that `tile_static` variables cannot have initializers. The second problem is that there is a race condition on the assignment to `total`, because all of the threads in the tile have access to the variable in no particular order. You could program an algorithm to only allow one thread to access the total at each barrier, as shown next. However, this solution is not extensible. - -```cpp -// Do not do this. -tile_static float total; -if (t_idx.local[0] == 0&& t_idx.local[1] == 0) { - total = matrix[t_idx]; -} -t_idx.barrier.wait(); - -if (t_idx.local[0] == 0&& t_idx.local[1] == 1) { - total += matrix[t_idx]; -} -t_idx.barrier.wait(); - -// etc. -``` - -## Memory Fences - -There are two kinds of memory accesses that must be synchronized—global memory access and `tile_static` memory access. A `concurrency::array` object allocates only global memory. A `concurrency::array_view` can reference global memory, `tile_static` memory, or both, depending on how it was constructed. There are two kinds of memory that must be synchronized: - -- global memory - -- `tile_static` - -A *memory fence* ensures that memory accesses are available to other threads in the thread tile, and that memory accesses are executed according to program order. To ensure this, compilers and processors do not reorder reads and writes across the fence. In C++ AMP, a memory fence is created by a call to one of these methods: - -- [tile_barrier::wait Method](reference/tile-barrier-class.md#wait): Creates a fence around both global and `tile_static` memory. - -- [tile_barrier::wait_with_all_memory_fence Method](reference/tile-barrier-class.md#wait_with_all_memory_fence): Creates a fence around both global and `tile_static` memory. - -- [tile_barrier::wait_with_global_memory_fence Method](reference/tile-barrier-class.md#wait_with_global_memory_fence): Creates a fence around only global memory. - -- [tile_barrier::wait_with_tile_static_memory_fence Method](reference/tile-barrier-class.md#wait_with_tile_static_memory_fence): Creates a fence around only `tile_static` memory. - -Calling the specific fence that you require can improve the performance of your app. The barrier type affects how the compiler and the hardware reorder statements. For example, if you use a global memory fence, it applies only to global memory accesses and therefore, the compiler and the hardware might reorder reads and writes to `tile_static` variables on the two sides of the fence. - -In the next example, the barrier synchronizes the writes to `tileValues`, a `tile_static` variable. In this example, `tile_barrier::wait_with_tile_static_memory_fence` is called instead of `tile_barrier::wait`. - -```cpp -// Using a tile_static memory fence. -parallel_for_each(matrix.extent.tile(), - [=, &averages] (tiled_index t_idx) restrict(amp) -{ - // Copy the values of the tile into a tile-sized array. - tile_static float tileValues[SAMPLESIZE][SAMPLESIZE]; - tileValues[t_idx.local[0]][t_idx.local[1]] = matrix[t_idx]; - - // Wait for the tile-sized array to load before calculating the average. - t_idx.barrier.wait_with_tile_static_memory_fence(); - - // If you remove the if statement, then the calculation executes - // for every thread in the tile, and makes the same assignment to - // averages each time. - if (t_idx.local[0] == 0&& t_idx.local[1] == 0) { - for (int trow = 0; trow -[tile_static Keyword](../../cpp/tile-static-keyword.md) diff --git a/docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md b/docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md deleted file mode 100644 index ea0a3d6bc94..00000000000 --- a/docs/parallel/amp/walkthrough-debugging-a-cpp-amp-application.md +++ /dev/null @@ -1,408 +0,0 @@ ---- -description: "Learn more about: Walkthrough: Debugging a C++ AMP application" -title: "Walkthrough: Debugging a C++ AMP application" -ms.date: 10/27/2021 -helpviewer_keywords: ["debugging, C++ Accelerated Massive Parallelism", "C++ AMP, debugging", "C++ Accelerated Massive Parallelism, debugging", "debugging, C++ AMP"] ---- -# Walkthrough: Debugging a C++ AMP application - -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). - -- 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)] - -### To create the sample project - -The instructions for creating a project vary depending on which version of Visual Studio you're using. Make sure you have the correct documentation version selected above the table of contents on this page. - -::: moniker range=">=msvc-160" - -### To create the sample project in Visual Studio - -1. On the menu bar, choose **File** > **New** > **Project** to open the **Create a New Project** dialog box. - -1. At the top of the dialog, set **Language** to **C++**, set **Platform** to **Windows**, and set **Project type** to **Console**. - -1. From the filtered list of project types, choose **Console App** then choose **Next**. In the next page, enter `AMPMapReduce` in the **Name** box to specify a name for the project, and specify the project location if you want a different one. - - ![Screenshot showing the Create a new project dialog with the Console App template selected.](../../build/media/mathclient-project-name-2019.png) - -1. Choose the **Create** button to create the client project. - -::: moniker-end - -::: moniker range="<=msvc-150" - -### To create the sample project in Visual Studio 2017 or Visual Studio 2015 - -1. Start Visual Studio. - -1. On the menu bar, choose **File** > **New** > **Project**. - -1. Under **Installed** in the templates pane, choose **Visual C++**. - -1. Choose **Win32 Console Application**, type `AMPMapReduce` in the **Name** box, and then choose the **OK** button. - -1. Choose the **Next** button. - -1. Clear the **Precompiled header** check box, and then choose the **Finish** button. - -1. In **Solution Explorer**, delete *stdafx.h*, *targetver.h*, and *stdafx.cpp* from the project. - -::: moniker-end - -Next: - -1. Open AMPMapReduce.cpp and replace its content with the following code. - - ```cpp - // AMPMapReduce.cpp defines the entry point for the program. - // The program performs a parallel-sum reduction that computes the sum of an array of integers. - - #include - #include - #include - - const int BLOCK_DIM = 32; - - using namespace concurrency; - - void sum_kernel_tiled(tiled_index t_idx, array &A, int stride_size) restrict(amp) - { - tile_static int localA[BLOCK_DIM]; - - index<1> globalIdx = t_idx.global * stride_size; - index<1> localIdx = t_idx.local; - - localA[localIdx[0]] = A[globalIdx]; - - t_idx.barrier.wait(); - - // Aggregate all elements in one tile into the first element. - for (int i = BLOCK_DIM / 2; i > 0; i /= 2) - { - if (localIdx[0] < i) - { - - localA[localIdx[0]] += localA[localIdx[0] + i]; - } - - t_idx.barrier.wait(); - } - - if (localIdx[0] == 0) - { - A[globalIdx] = localA[0]; - } - } - - int size_after_padding(int n) - { - // The extent might have to be slightly bigger than num_stride to - // be evenly divisible by BLOCK_DIM. You can do this by padding with zeros. - // The calculation to do this is BLOCK_DIM * ceil(n / BLOCK_DIM) - return ((n - 1) / BLOCK_DIM + 1) * BLOCK_DIM; - } - - int reduction_sum_gpu_kernel(array input) - { - int len = input.extent[0]; - - //Tree-based reduction control that uses the CPU. - for (int stride_size = 1; stride_size < len; stride_size *= BLOCK_DIM) - { - // Number of useful values in the array, given the current - // stride size. - int num_strides = len / stride_size; - - extent<1> e(size_after_padding(num_strides)); - - // The sum kernel that uses the GPU. - parallel_for_each(extent<1>(e).tile(), [&input, stride_size] (tiled_index idx) restrict(amp) - { - sum_kernel_tiled(idx, input, stride_size); - }); - } - - array_view output = input.section(extent<1>(1)); - return output[0]; - } - - int cpu_sum(const std::vector &arr) { - int sum = 0; - for (size_t i = 0; i < arr.size(); i++) { - sum += arr[i]; - } - return sum; - } - - std::vector rand_vector(unsigned int size) { - srand(2011); - - std::vector vec(size); - for (size_t i = 0; i < size; i++) { - vec[i] = rand(); - } - return vec; - } - - array vector_to_array(const std::vector &vec) { - array arr(vec.size()); - copy(vec.begin(), vec.end(), arr); - return arr; - } - - int _tmain(int argc, _TCHAR* argv[]) - { - std::vector vec = rand_vector(10000); - array arr = vector_to_array(vec); - - int expected = cpu_sum(vec); - int actual = reduction_sum_gpu_kernel(arr); - - bool passed = (expected == actual); - if (!passed) { - printf("Actual (GPU): %d, Expected (CPU): %d", actual, expected); - } - printf("sum: %s\n", passed ? "Passed!" : "Failed!"); - - getchar(); - - return 0; - } - ``` - -1. On the menu bar, choose **File** > **Save All**. - -1. In **Solution Explorer**, open the shortcut menu for **AMPMapReduce**, and then choose **Properties**. - -1. In the **Property Pages** dialog box, under **Configuration Properties**, choose **C/C++** > **Precompiled Headers**. - -1. For the **Precompiled Header** property, select **Not Using Precompiled Headers**, and then choose the **OK** button. - -1. On the menu bar, choose **Build** > **Build Solution**. - -## Debugging the CPU Code - -In this procedure, you'll use the Local Windows Debugger to make sure that the CPU code in this application is correct. The segment of the CPU code in this application that is especially interesting is the **`for`** loop in the `reduction_sum_gpu_kernel` function. It controls the tree-based parallel reduction that is run on the GPU. - -### To debug the CPU code - -1. In **Solution Explorer**, open the shortcut menu for **AMPMapReduce**, and then choose **Properties**. - -2. In the **Property Pages** dialog box, under **Configuration Properties**, choose **Debugging**. Verify that **Local Windows Debugger** is selected in the **Debugger to launch** list. - -3. Return to the **Code Editor**. - -4. Set breakpoints on the lines of code shown in the following illustration (approximately lines 67 line 70). - - ![CPU breakpoints marked next to lines of code in the editor.](../../parallel/amp/media/campcpubreakpoints.png "CPU breakpoints")
- CPU breakpoints - -5. On the menu bar, choose **Debug** > **Start Debugging**. - -6. In the **Locals** window, observe the value for `stride_size` until the breakpoint at line 70 is reached. - -7. On the menu bar, choose **Debug** > **Stop Debugging**. - -## Debugging the GPU Code - -This section shows how to debug the GPU code, which is the code contained in the `sum_kernel_tiled` function. The GPU code computes the sum of integers for each "block" in parallel. - -### To debug the GPU code - -1. In **Solution Explorer**, open the shortcut menu for **AMPMapReduce**, and then choose **Properties**. - -2. In the **Property Pages** dialog box, under **Configuration Properties**, choose **Debugging**. - -3. In the **Debugger to launch** list, select **Local Windows Debugger**. - -4. In the **Debugger Type** list, verify that **Auto** is selected. - - **Auto** is the default value. In versions before Windows 10, **GPU Only** is the required value instead of **Auto**. - -5. Choose the **OK** button. - -6. Set a breakpoint at line 30, as shown in the following illustration. - - ![GPU breakpoints marked next to a line of code in the editor.](../../parallel/amp/media/campgpubreakpoints.png "GPU breakpoints")
- GPU breakpoint - -7. On the menu bar, choose **Debug** > **Start Debugging**. The breakpoints in the CPU code at lines 67 and 70 don't get executed during GPU debugging because those lines of code run on the CPU. - -### To use the GPU Threads window - -1. To open the **GPU Threads** window, on the menu bar, choose **Debug** > **Windows** > **GPU Threads**. - - You can inspect the state the GPU threads in the **GPU Threads** window that appears. - -2. Dock the **GPU Threads** window at the bottom of Visual Studio. Choose the **Expand Thread Switch** button to display the tile and thread text boxes. The **GPU Threads** window shows the total number of active and blocked GPU threads, as shown in the following illustration. - - ![GPU Threads window with 4 active threads.](../../parallel/amp/media/campc.png "GPU Threads window with 4 active threads")
- GPU Threads window - - 313 tiles get allocated for this computation. Each tile contains 32 threads. Because local GPU debugging occurs on a software emulator, there are four active GPU threads. The four threads execute the instructions simultaneously and then move on together to the next instruction. - - In the **GPU Threads** window, there are four GPU threads active and 28 GPU threads blocked at the [tile_barrier::wait](reference/tile-barrier-class.md#wait) statement defined at about line 21 (`t_idx.barrier.wait();`). All 32 GPU threads belong to the first tile, `tile[0]`. An arrow points to the row that includes the current thread. To switch to a different thread, use one of the following methods: - - - In the row for the thread to switch to in the **GPU Threads** window, open the shortcut menu and choose **Switch To Thread**. If the row represents more than one thread, you'll switch to the first thread according to the thread coordinates. - - - Enter the tile and thread values of the thread in the corresponding text boxes and then choose the **Switch Thread** button. - - The **Call Stack** window displays the call stack of the current GPU thread. - -### To use the Parallel Stacks window - -1. To open the **Parallel Stacks** window, on the menu bar, choose **Debug** > **Windows** > **Parallel Stacks**. - - You can use the **Parallel Stacks** window to simultaneously inspect the stack frames of multiple GPU threads. - -2. Dock the **Parallel Stacks** window at the bottom of Visual Studio. - -3. Make sure that **Threads** is selected in the list in the upper-left corner. In the following illustration, the **Parallel Stacks** window shows a call-stack focused view of the GPU threads that you saw in the **GPU Threads** window. - - ![Parallel Stacks window with 4 active threads.](../../parallel/amp/media/campd.png "Parallel Stacks window with 4 active threads")
- Parallel Stacks window - - 32 threads went from `_kernel_stub` to the lambda statement in the `parallel_for_each` function call and then to the `sum_kernel_tiled` function, where the parallel reduction occurs. 28 out of the 32 threads have progressed to the [`tile_barrier::wait`](reference/tile-barrier-class.md#wait) statement and remain blocked at line 22, while the other four threads remain active in the `sum_kernel_tiled` function at line 30. - - You can inspect the properties of a GPU thread. They're available in the **GPU Threads** window in the rich DataTip of the **Parallel Stacks** window. To see them, hover the pointer on the stack frame of `sum_kernel_tiled`. The following illustration shows the DataTip. - - ![DataTip for Parallel Stacks window.](../../parallel/amp/media/campe.png "DataTip for Parallel Stacks window")
- GPU thread DataTip - - For more information about the **Parallel Stacks** window, see [Using the Parallel Stacks Window](/visualstudio/debugger/using-the-parallel-stacks-window). - -### To use the Parallel Watch window - -1. To open the **Parallel Watch** window, on the menu bar, choose **Debug** > **Windows** > **Parallel Watch** > **Parallel Watch 1**. - - You can use the **Parallel Watch** window to inspect the values of an expression across multiple threads. - -2. Dock the **Parallel Watch 1** window to the bottom of Visual Studio. There are 32 rows in the table of the **Parallel Watch** window. Each corresponds to a GPU thread that appeared in both the GPU Threads window and the **Parallel Stacks** window. Now, you can enter expressions whose values you want to inspect across all 32 GPU threads. - -3. Select the **Add Watch** column header, enter `localIdx`, and then choose the **Enter** key. - -4. Select the **Add Watch** column header again, type `globalIdx`, and then choose the **Enter** key. - -5. Select the **Add Watch** column header again, type `localA[localIdx[0]]`, and then choose the **Enter** key. - - You can sort by a specified expression by selecting its corresponding column header. - - Select the **localA[localIdx[0]]** column header to sort the column. The following illustration shows the results of sorting by **localA[localIdx[0]]**. - - ![Parallel Watch window with sorted results.](../../parallel/amp/media/campf.png "Parallel Watch window with sorted results")
- Results of sort - - You can export the content in the **Parallel Watch** window to Excel by choosing the **Excel** button and then choosing **Open in Excel**. If you have Excel installed on your development computer, the button opens an Excel worksheet that contains the content. - -6. In the upper-right corner of the **Parallel Watch** window, there's a filter control that you can use to filter the content by using Boolean expressions. Enter `localA[localIdx[0]] > 20000` in the filter control text box and then choose the **Enter** key. - - The window now contains only threads on which the `localA[localIdx[0]]` value is greater than 20000. The content is still sorted by the `localA[localIdx[0]]` column, which is the sorting action you chose earlier. - -## Flagging GPU Threads - -You can mark specific GPU threads by flagging them in the **GPU Threads** window, the **Parallel Watch** window, or the DataTip in the **Parallel Stacks** window. If a row in the GPU Threads window contains more than one thread, flagging that row flags all threads contained in the row. - -### To flag GPU threads - -1. Select the **[Thread]** column header in the **Parallel Watch 1** window to sort by tile index and thread index. - -2. On the menu bar, choose **Debug** > **Continue**, which causes the four threads that were active to progress to the next barrier (defined at line 32 of AMPMapReduce.cpp). - -3. Choose the flag symbol on the left side of the row that contains the four threads that are now active. - - The following illustration shows the four active flagged threads in the **GPU Threads** window. - - ![GPU Threads window with flagged threads.](../../parallel/amp/media/campg.png "GPU Threads window with flagged threads")
- Active threads in the GPU Threads window - - The **Parallel Watch** window and the DataTip of the **Parallel Stacks** window both indicate the flagged threads. - -4. If you want to focus on the four threads that you flagged, you can choose to show only the flagged threads. It limits what you see in the **GPU Threads**, **Parallel Watch**, and **Parallel Stacks** windows. - - Choose the **Show Flagged Only** button on any of the windows or on the **Debug Location** toolbar. The following illustration shows the **Show Flagged Only** button on the **Debug Location** toolbar. - - ![Debug Location toolbar with Show Only Flagged icon.](../../parallel/amp/media/camph.png "Debug Location toolbar with Show Only Flagged icon")
- **Show Flagged Only** button - - Now the **GPU Threads**, **Parallel Watch**, and **Parallel Stacks** windows display only the flagged threads. - -## Freezing and Thawing GPU Threads - -You can freeze (suspend) and thaw (resume) GPU threads from either the **GPU Threads** window or the **Parallel Watch** window. You can freeze and thaw CPU threads the same way; for information, see [How to: Use the Threads Window](/visualstudio/debugger/how-to-use-the-threads-window). - -### To freeze and thaw GPU threads - -1. Choose the **Show Flagged Only** button to display all the threads. - -2. On the menu bar, choose **Debug** > **Continue**. - -3. Open the shortcut menu for the active row and then choose **Freeze**. - - The following illustration of the **GPU Threads** window shows that all four threads are frozen. - - ![GPU Threads windows showing frozen threads.](../../parallel/amp/media/campk.png "GPU Threads windows showing frozen threads")
- Frozen threads in the **GPU Threads** window - - Similarly, the **Parallel Watch** window shows that all four threads are frozen. - -4. On the menu bar, choose **Debug** > **Continue** to allow the next four GPU threads to progress past the barrier at line 22 and to reach the breakpoint at line 30. The **GPU Threads** window shows that the four previously frozen threads remain frozen and in the active state. - -5. On the menu bar, choose **Debug**, **Continue**. - -6. From the **Parallel Watch** window, you can also thaw individual or multiple GPU threads. - -### To group GPU threads - -1. On the shortcut menu for one of the threads in the **GPU Threads** window, choose **Group By**, **Address**. - - The threads in the **GPU Threads** window are grouped by address. The address corresponds to the instruction in disassembly where each group of threads is located. 24 threads are at line 22 where the [tile_barrier::wait Method](reference/tile-barrier-class.md#wait) is executed. 12 threads are at the instruction for the barrier at line 32. Four of these threads are flagged. Eight threads are at the breakpoint at line 30. Four of these threads are frozen. The following illustration shows the grouped threads in the **GPU Threads** window. - - ![GPU Threads window with threads grouped by Address.](../../parallel/amp/media/campl.png "GPU Threads window with threads grouped by Address")
- Grouped threads in the **GPU Threads** window - -2. You can also do the **Group By** operation by opening the shortcut menu for the **Parallel Watch** window's data grid. Select **Group By**, and then choose the menu item that corresponds to how you want to group the threads. - -## Running All Threads to a Specific Location in Code - -You run all the threads in a given tile to the line that contains the cursor by using **Run Current Tile To Cursor**. - -### To run all threads to the location marked by the cursor - -1. On the shortcut menu for the frozen threads, choose **Thaw**. - -2. In the **Code Editor**, put the cursor in line 30. - -3. On the shortcut menu for the **Code Editor**, choose **Run Current Tile To Cursor**. - - The 24 threads that were previously blocked at the barrier at line 21 have progressed to line 32. It's shown in the **GPU Threads** window. - -## See also - -[C++ AMP overview](../../parallel/amp/cpp-amp-overview.md)\ -[Debugging GPU code](/visualstudio/debugger/debugging-gpu-code)\ -[How to: Use the GPU Threads window](/visualstudio/debugger/how-to-use-the-gpu-threads-window)\ -[How to: Use the Parallel Watch window](/visualstudio/debugger/how-to-use-the-parallel-watch-window)\ -[Analyzing C++ AMP code with the Concurrency Visualizer](/archive/blogs/nativeconcurrency/analyzing-c-amp-code-with-the-concurrency-visualizer) diff --git a/docs/parallel/amp/walkthrough-matrix-multiplication.md b/docs/parallel/amp/walkthrough-matrix-multiplication.md deleted file mode 100644 index 731c343fa8e..00000000000 --- a/docs/parallel/amp/walkthrough-matrix-multiplication.md +++ /dev/null @@ -1,321 +0,0 @@ ---- -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 - -This step-by-step walkthrough demonstrates how to use C++ AMP to accelerate the execution of matrix multiplication. Two algorithms are presented, one without tiling and one with tiling. - -## Prerequisites - -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. - -### 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. - -::: moniker range=">=msvc-160" - -### To create the project in Visual Studio - -1. On the menu bar, choose **File** > **New** > **Project** to open the **Create a New Project** dialog box. - -1. At the top of the dialog, set **Language** to **C++**, set **Platform** to **Windows**, and set **Project type** to **Console**. - -1. From the filtered list of project types, choose **Empty Project** then choose **Next**. In the next page, enter *MatrixMultiply* in the **Name** box to specify a name for the project, and specify the project location if desired. - - ![Screenshot showing the Create a new project dialog with the Console App template selected.](../../build/media/mathclient-project-name-2019.png) - -1. Choose the **Create** button to create the client project. - -1. In **Solution Explorer**, open the shortcut menu for **Source Files**, and then choose **Add** > **New Item**. - -1. In the **Add New Item** dialog box, select **C++ File (.cpp)**, enter *MatrixMultiply.cpp* in the **Name** box, and then choose the **Add** button. - -::: moniker-end - -::: moniker range="<=msvc-150" - -### To create a project in Visual Studio 2017 or 2015 - -1. On the menu bar in Visual Studio, choose **File** > **New** > **Project**. - -1. Under **Installed** in the templates pane, select **Visual C++**. - -1. Select **Empty Project**, enter *MatrixMultiply* in the **Name** box, and then choose the **OK** button. - -1. Choose the **Next** button. - -1. In **Solution Explorer**, open the shortcut menu for **Source Files**, and then choose **Add** > **New Item**. - -1. In the **Add New Item** dialog box, select **C++ File (.cpp)**, enter *MatrixMultiply.cpp* in the **Name** box, and then choose the **Add** button. - -::: moniker-end - -## Multiplication without tiling - -In this section, consider the multiplication of two matrices, A and B, which are defined as follows: - -![Diagram showing 3 by 2 matrix A.](../../parallel/amp/media/campmatrixanontiled.png) - -![Diagram showing 2 by 3 matrix B.](../../parallel/amp/media/campmatrixbnontiled.png) - -A is a 3-by-2 matrix and B is a 2-by-3 matrix. The product of multiplying A by B is the following 3-by-3 matrix. The product is calculated by multiplying the rows of A by the columns of B element by element. - -![Diagram showing the result 3 by 3 product matrix.](../../parallel/amp/media/campmatrixproductnontiled.png) - -### To multiply without using C++ AMP - -1. Open MatrixMultiply.cpp and use the following code to replace the existing code. - - ```cpp - #include - - void MultiplyWithOutAMP() { - int aMatrix[3][2] = {{1, 4}, {2, 5}, {3, 6}}; - int bMatrix[2][3] = {{7, 8, 9}, {10, 11, 12}}; - int product[3][3] = {{0, 0, 0}, {0, 0, 0}, {0, 0, 0}}; - - for (int row = 0; row < 3; row++) { - for (int col = 0; col < 3; col++) { - // Multiply the row of A by the column of B to get the row, column of product. - for (int inner = 0; inner < 2; inner++) { - product[row][col] += aMatrix[row][inner] * bMatrix[inner][col]; - } - std::cout << product[row][col] << " "; - } - std::cout << "\n"; - } - } - - int main() { - MultiplyWithOutAMP(); - getchar(); - } - ``` - - The algorithm is a straightforward implementation of the definition of matrix multiplication. It does not use any parallel or threaded algorithms to reduce the computation time. - -1. On the menu bar, choose **File** > **Save All**. - -1. Choose the **F5** keyboard shortcut to start debugging and verify that the output is correct. - -1. Choose **Enter** to exit the application. - -### To multiply by using C++ AMP - -1. In MatrixMultiply.cpp, add the following code before the `main` method. - - ```cpp - void MultiplyWithAMP() { - int aMatrix[] = { 1, 4, 2, 5, 3, 6 }; - int bMatrix[] = { 7, 8, 9, 10, 11, 12 }; - int productMatrix[] = { 0, 0, 0, 0, 0, 0, 0, 0, 0 }; - - array_view a(3, 2, aMatrix); - - array_view b(2, 3, bMatrix); - - array_view product(3, 3, productMatrix); - - parallel_for_each(product.extent, - [=] (index<2> idx) restrict(amp) { - int row = idx[0]; - int col = idx[1]; - for (int inner = 0; inner <2; inner++) { - product[idx] += a(row, inner)* b(inner, col); - } - }); - - product.synchronize(); - - for (int row = 0; row <3; row++) { - for (int col = 0; col <3; col++) { - //std::cout << productMatrix[row*3 + col] << " "; - std::cout << product(row, col) << " "; - } - std::cout << "\n"; - } - } - ``` - - The AMP code resembles the non-AMP code. The call to `parallel_for_each` starts one thread for each element in `product.extent`, and replaces the **`for`** loops for row and column. The value of the cell at the row and column is available in `idx`. You can access the elements of an `array_view` object by using either the `[]` operator and an index variable, or the `()` operator and the row and column variables. The example demonstrates both methods. The `array_view::synchronize` method copies the values of the `product` variable back to the `productMatrix` variable. - -1. Add the following `include` and **`using`** statements at the top of MatrixMultiply.cpp. - - ```cpp - #include - using namespace concurrency; - ``` - -1. Modify the `main` method to call the `MultiplyWithAMP` method. - - ```cpp - int main() { - MultiplyWithOutAMP(); - MultiplyWithAMP(); - getchar(); - } - ``` - -1. Press the **Ctrl**+**F5** keyboard shortcut to start debugging and verify that the output is correct. - -1. Press the **Spacebar** to exit the application. - -## Multiplication with tiling - -Tiling is a technique in which you partition data into equal-sized subsets, which are known as tiles. Three things change when you use tiling. - -- You can create `tile_static` variables. Access to data in `tile_static` space can be many times faster than access to data in the global space. An instance of a `tile_static` variable is created for each tile, and all threads in the tile have access to the variable. The primary benefit of tiling is the performance gain due to `tile_static` access. - -- You can call the [tile_barrier::wait](reference/tile-barrier-class.md#wait) method to stop all of the threads in one tile at a specified line of code. You cannot guarantee the order that the threads will run in, only that all of the threads in one tile will stop at the call to `tile_barrier::wait` before they continue execution. - -- You have access to the index of the thread relative to the entire `array_view` object and the index relative to the tile. By using the local index, you can make your code easier to read and debug. - -To take advantage of tiling in matrix multiplication, the algorithm must partition the matrix into tiles and then copy the tile data into `tile_static` variables for faster access. In this example, the matrix is partitioned into submatrices of equal size. The product is found by multiplying the submatrices. The two matrices and their product in this example are: - -![Diagram showing 4 by 4 matrix A.](../../parallel/amp/media/campmatrixatiled.png) - -![Diagram showing 4 by 4 matrix B.](../../parallel/amp/media/campmatrixbtiled.png) - -![Diagram showing result 4 by 4 product matrix.](../../parallel/amp/media/campmatrixproducttiled.png) - -The matrices are partitioned into four 2x2 matrices, which are defined as follows: - -![Diagram showing 4 by 4 matrix A partitioned into 2 by 2 sub matrices.](../../parallel/amp/media/campmatrixapartitioned.png) - -![Diagram showing 4 by 4 matrix B partitioned into 2 by 2 sub matrices.](../../parallel/amp/media/campmatrixbpartitioned.png) - -The product of A and B can now be written and calculated as follows: - -![Diagram showing 4 by 4 matrix A B partitioned into 2 by 2 sub matrices.](../../parallel/amp/media/campmatrixproductpartitioned.png) - -Because matrices `a` through `h` are 2x2 matrices, all of the products and sums of them are also 2x2 matrices. It also follows that the product of A and B is a 4x4 matrix, as expected. To quickly check the algorithm, calculate the value of the element in the first row, first column in the product. In the example, that would be the value of the element in the first row and first column of `ae + bg`. You only have to calculate the first column, first row of `ae` and `bg` for each term. That value for `ae` is `(1 * 1) + (2 * 5) = 11`. The value for `bg` is `(3 * 1) + (4 * 5) = 23`. The final value is `11 + 23 = 34`, which is correct. - -To implement this algorithm, the code: - -- Uses a `tiled_extent` object instead of an `extent` object in the `parallel_for_each` call. - -- Uses a `tiled_index` object instead of an `index` object in the `parallel_for_each` call. - -- Creates `tile_static` variables to hold the submatrices. - -- Uses the `tile_barrier::wait` method to stop the threads for the calculation of the products of the submatrices. - -### To multiply by using AMP and tiling - -1. In MatrixMultiply.cpp, add the following code before the `main` method. - - ```cpp - void MultiplyWithTiling() { - // The tile size is 2. - static const int TS = 2; - - // The raw data. - int aMatrix[] = { 1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3, 4, 5, 6, 7, 8 }; - int bMatrix[] = { 1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3, 4, 5, 6, 7, 8 }; - int productMatrix[] = { 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0 }; - - // Create the array_view objects. - array_view a(4, 4, aMatrix); - array_view b(4, 4, bMatrix); - array_view product(4, 4, productMatrix); - - // Call parallel_for_each by using 2x2 tiles. - parallel_for_each(product.extent.tile(), - [=] (tiled_index t_idx) restrict(amp) - { - // Get the location of the thread relative to the tile (row, col) - // and the entire array_view (rowGlobal, colGlobal). - int row = t_idx.local[0]; - int col = t_idx.local[1]; - int rowGlobal = t_idx.global[0]; - int colGlobal = t_idx.global[1]; - int sum = 0; - - // Given a 4x4 matrix and a 2x2 tile size, this loop executes twice for each thread. - // For the first tile and the first loop, it copies a into locA and e into locB. - // For the first tile and the second loop, it copies b into locA and g into locB. - for (int i = 0; i < 4; i += TS) { - tile_static int locA[TS][TS]; - tile_static int locB[TS][TS]; - locA[row][col] = a(rowGlobal, col + i); - locB[row][col] = b(row + i, colGlobal); - // The threads in the tile all wait here until locA and locB are filled. - t_idx.barrier.wait(); - - // Return the product for the thread. The sum is retained across - // both iterations of the loop, in effect adding the two products - // together, for example, a*e. - for (int k = 0; k < TS; k++) { - sum += locA[row][k] * locB[k][col]; - } - - // All threads must wait until the sums are calculated. If any threads - // moved ahead, the values in locA and locB would change. - t_idx.barrier.wait(); - // Now go on to the next iteration of the loop. - } - - // After both iterations of the loop, copy the sum to the product variable by using the global location. - product[t_idx.global] = sum; - }); - - // Copy the contents of product back to the productMatrix variable. - product.synchronize(); - - for (int row = 0; row <4; row++) { - for (int col = 0; col <4; col++) { - // The results are available from both the product and productMatrix variables. - //std::cout << productMatrix[row*3 + col] << " "; - std::cout << product(row, col) << " "; - } - std::cout << "\n"; - } - } - ``` - - This example is significantly different than the example without tiling. The code uses these conceptual steps: - 1. Copy the elements of tile[0,0] of `a` into `locA`. Copy the elements of tile[0,0] of `b` into `locB`. Notice that `product` is tiled, not `a` and `b`. Therefore, you use global indices to access `a, b`, and `product`. The call to `tile_barrier::wait` is essential. It stops all of the threads in the tile until both `locA` and `locB` are filled. - - 1. Multiply `locA` and `locB` and put the results in `product`. - - 1. Copy the elements of tile[0,1] of `a` into `locA`. Copy the elements of tile [1,0] of `b` into `locB`. - - 1. Multiply `locA` and `locB` and add them to the results that are already in `product`. - - 1. The multiplication of tile[0,0] is complete. - - 1. Repeat for the other four tiles. There is no indexing specifically for the tiles and the threads can execute in any order. As each thread executes, the `tile_static` variables are created for each tile appropriately and the call to `tile_barrier::wait` controls the program flow. - - 1. As you examine the algorithm closely, notice that each submatrix is loaded into a `tile_static` memory twice. That data transfer does take time. However, once the data is in `tile_static` memory, access to the data is much faster. Because calculating the products requires repeated access to the values in the submatrices, there is an overall performance gain. For each algorithm, experimentation is required to find the optimal algorithm and tile size. - - In the non-AMP and non-tile examples, each element of A and B is accessed four times from the global memory to calculate the product. In the tile example, each element is accessed twice from the global memory and four times from the `tile_static` memory. That is not a significant performance gain. However, if the A and B were 1024x1024 matrices and the tile size were 16, there would be a significant performance gain. In that case, each element would be copied into `tile_static` memory only 16 times and accessed from `tile_static` memory 1024 times. - -1. Modify the main method to call the `MultiplyWithTiling` method, as shown. - - ```cpp - int main() { - MultiplyWithOutAMP(); - MultiplyWithAMP(); - MultiplyWithTiling(); - getchar(); - } - ``` - -1. Press the **Ctrl**+**F5** keyboard shortcut to start debugging and verify that the output is correct. - -1. Press the **Space** bar to exit the application. - -## See also - -[C++ AMP (C++ Accelerated Massive Parallelism)](../../parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md)
-[Walkthrough: Debugging a C++ AMP Application](../../parallel/amp/walkthrough-debugging-a-cpp-amp-application.md) diff --git a/docs/parallel/auto-parallelization-and-auto-vectorization.md b/docs/parallel/auto-parallelization-and-auto-vectorization.md index b6239866e8b..47ed363f7b8 100644 --- a/docs/parallel/auto-parallelization-and-auto-vectorization.md +++ b/docs/parallel/auto-parallelization-and-auto-vectorization.md @@ -19,7 +19,7 @@ void loop_test(int u) { } ``` -Because `u` could be a small value, the compiler won’t automatically parallelize this loop. However, you might still want it parallelized because you know that `u` will always be large. To enable the auto-parallelization, specify [#pragma loop(hint_parallel(n))](../preprocessor/loop.md), where `n` is the number of threads to parallelize across. In the following example, the compiler will attempt to parallelize the loop across 8 threads. +Because `u` could be a small value, the compiler won't automatically parallelize this loop. However, you might still want it parallelized because you know that `u` will always be large. To enable the auto-parallelization, specify [#pragma loop(hint_parallel(n))](../preprocessor/loop.md), where `n` is the number of threads to parallelize across. In the following example, the compiler will attempt to parallelize the loop across 8 threads. ```cpp void loop_test(int u) { @@ -31,7 +31,7 @@ void loop_test(int u) { As with all [pragma directives](../preprocessor/pragma-directives-and-the-pragma-keyword.md), the alternate pragma syntax `__pragma(loop(hint_parallel(n)))` is also supported. -There are some loops that the compiler can’t parallelize even if you want it to. Here's an example: +There are some loops that the compiler can't parallelize even if you want it to. Here's an example: ```cpp #pragma loop(hint_parallel(8)) @@ -39,7 +39,7 @@ for (int i=0; i timer Class -The concurrency::[timer class](../../parallel/concrt/reference/timer-class.md) acts as a message source. A `timer` object sends a message to a target after a specified period of time has elapsed. The `timer` class is useful when you must delay sending a message or you want to send a message at a regular interval. +The [concurrency::timer class](../../parallel/concrt/reference/timer-class.md) acts as a message source. A `timer` object sends a message to a target after a specified period of time has elapsed. The `timer` class is useful when you must delay sending a message or you want to send a message at a regular interval. The `timer` class sends its message to just one target. If you set the `_PTarget` parameter in the constructor to `NULL`, you can later specify the target by calling the [concurrency::ISource::link_target](reference/source-block-class.md#link_target) method. diff --git a/docs/parallel/concrt/best-practices-in-the-asynchronous-agents-library.md b/docs/parallel/concrt/best-practices-in-the-asynchronous-agents-library.md index 88a23f3247a..f41406f07f4 100644 --- a/docs/parallel/concrt/best-practices-in-the-asynchronous-agents-library.md +++ b/docs/parallel/concrt/best-practices-in-the-asynchronous-agents-library.md @@ -4,6 +4,7 @@ title: "Best Practices in the Asynchronous Agents Library" ms.date: 08/25/2021 helpviewer_keywords: ["best practices, Asynchronous Agents Library", "Asynchronous Agents Library, best practices", "Asynchronous Agents Library, practices to avoid", "practices to avoid, Asynchronous Agents Library"] ms.assetid: 85f52354-41eb-4b0d-98c5-f7344ee8a8cf +ms.topic: best-practice --- # Best Practices in the Asynchronous Agents Library diff --git a/docs/parallel/concrt/best-practices-in-the-parallel-patterns-library.md b/docs/parallel/concrt/best-practices-in-the-parallel-patterns-library.md index 6a1a2286785..34ef2be1166 100644 --- a/docs/parallel/concrt/best-practices-in-the-parallel-patterns-library.md +++ b/docs/parallel/concrt/best-practices-in-the-parallel-patterns-library.md @@ -4,6 +4,7 @@ title: "Best Practices in the Parallel Patterns Library" ms.date: "11/04/2016" helpviewer_keywords: ["Parallel Patterns Library, practices to avoid", "practices to avoid, Parallel Patterns Library", "best practices, Parallel Patterns Library", "Parallel Patterns Library, best practices"] ms.assetid: e43e0304-4d54-4bd8-a3b3-b8673559a9d7 +ms.topic: best-practice --- # Best Practices in the Parallel Patterns Library diff --git a/docs/parallel/concrt/cancellation-in-the-ppl.md b/docs/parallel/concrt/cancellation-in-the-ppl.md index 3d97190376d..66e4150037a 100644 --- a/docs/parallel/concrt/cancellation-in-the-ppl.md +++ b/docs/parallel/concrt/cancellation-in-the-ppl.md @@ -215,7 +215,7 @@ This example produces the following output. Caught 50 ``` -The following example uses a Boolean flag to coordinate cancellation in a `parallel_for` loop. Every task runs because this example does not use the `cancel` method or exception handling to cancel the overall set of tasks. Therefore, this technique can have more computational overhead than a cancelation mechanism. +The following example uses a Boolean flag to coordinate cancellation in a `parallel_for` loop. Every task runs because this example does not use the `cancel` method or exception handling to cancel the overall set of tasks. Therefore, this technique can have more computational overhead than a cancellation mechanism. [!code-cpp[concrt-task-tree#8](../../parallel/concrt/codesnippet/cpp/cancellation-in-the-ppl_14.cpp)] diff --git a/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_12.cpp b/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_12.cpp index 54a60e82783..93413d211ca 100644 --- a/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_12.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_12.cpp @@ -1,4 +1,4 @@ - // To enable cancelation, call parallel_for in a task group. + // To enable cancellation, call parallel_for in a task group. structured_task_group tg; task_group_status status = tg.run_and_wait([&] { diff --git a/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_14.cpp b/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_14.cpp index 501bef3171f..20dc01ea24a 100644 --- a/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_14.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_14.cpp @@ -1,4 +1,4 @@ - // Create a Boolean flag to coordinate cancelation. + // Create a Boolean flag to coordinate cancellation. bool canceled = false; parallel_for(0, 100, [&](int i) { diff --git a/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_6.cpp b/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_6.cpp index a2fd7307692..64bd96b60aa 100644 --- a/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_6.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/cancellation-in-the-ppl_6.cpp @@ -23,7 +23,7 @@ for (int i = 0; i < 1000; ++i) { // To reduce overhead, occasionally check for - // cancelation. + // cancellation. if ((i%100) == 0) { if (tg2.is_canceling()) diff --git a/docs/parallel/concrt/codesnippet/CPP/exception-handling-in-the-concurrency-runtime_6.cpp b/docs/parallel/concrt/codesnippet/CPP/exception-handling-in-the-concurrency-runtime_6.cpp index ca2b028026c..516134985e6 100644 --- a/docs/parallel/concrt/codesnippet/CPP/exception-handling-in-the-concurrency-runtime_6.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/exception-handling-in-the-concurrency-runtime_6.cpp @@ -18,7 +18,7 @@ int wmain() { parallel_for(-5, 20, [min,max](int i) { - // Throw an exeception if the input value is less than the + // Throw an exception if the input value is less than the // minimum or greater than the maximum. // Otherwise, print the value to the console. diff --git a/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_1.cpp b/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_1.cpp index 19ec97fbf8d..07d9a402d18 100644 --- a/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_1.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_1.cpp @@ -28,7 +28,7 @@ task complete_after(unsigned int timeout) }); } -// Cancels the provided task after the specifed delay, if the task +// Cancels the provided task after the specified delay, if the task // did not complete. template task cancel_after_timeout(task t, cancellation_token_source cts, unsigned int timeout) diff --git a/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_3.cpp b/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_3.cpp index 05fa30ae3d4..efdf43e9507 100644 --- a/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_3.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/how-to-create-a-task-that-completes-after-a-delay_3.cpp @@ -38,7 +38,7 @@ task complete_after(unsigned int timeout) }); } -// Cancels the provided task after the specifed delay, if the task +// Cancels the provided task after the specified delay, if the task // did not complete. template task cancel_after_timeout(task t, cancellation_token_source cts, unsigned int timeout) diff --git a/docs/parallel/concrt/codesnippet/CPP/how-to-write-a-parallel-for-each-loop_1.cpp b/docs/parallel/concrt/codesnippet/CPP/how-to-write-a-parallel-for-each-loop_1.cpp index d29a9cf0d7c..f6008df0639 100644 --- a/docs/parallel/concrt/codesnippet/CPP/how-to-write-a-parallel-for-each-loop_1.cpp +++ b/docs/parallel/concrt/codesnippet/CPP/how-to-write-a-parallel-for-each-loop_1.cpp @@ -9,66 +9,78 @@ using namespace concurrency; using namespace std; -// Calls the provided work function and returns the number of milliseconds -// that it takes to call that function. +// Returns the number of milliseconds that it takes to call the passed in function. template __int64 time_call(Function&& f) { - __int64 begin = GetTickCount(); - f(); - return GetTickCount() - begin; + __int64 begin = GetTickCount(); + f(); + return GetTickCount() - begin; } -// Determines whether the input value is prime. +// Determines whether the input is a prime. bool is_prime(int n) { - if (n < 2) - return false; - for (int i = 2; i < n; ++i) - { - if ((n % i) == 0) - return false; - } - return true; + if (n < 2) + { + return false; + } + + for (int i = 2; i < int(std::sqrt(n)) + 1; ++i) + { + if (n % i == 0) + { + return false; + } + } + return true; } int wmain() { - // Create an array object that contains 200000 integers. - array a; + // Create an array object that contains 200000 integers. + array a; - // Initialize the array such that a[i] == i. - int n = 0; - generate(begin(a), end(a), [&] { - return n++; - }); + // Initialize the array such that a[i] == i. + int n = 0; + generate(begin(a), end(a), [&] + { + return n++; + }); - LONG prime_count; - __int64 elapsed; + // Use the for_each algorithm to count, serially, the number + // of prime numbers in the array. + LONG prime_count = 0L; + __int64 elapsed = time_call([&] + { + for_each(begin(a), end(a), [&](int n) + { + if (is_prime(n)) + { + ++prime_count; + } + }); + }); + + wcout << L"serial version: " << endl + << L"found " << prime_count << L" prime numbers" << endl + << L"took " << elapsed << L" ms" << endl << endl; - // Use the for_each algorithm to count the number of prime numbers - // in the array serially. - prime_count = 0L; - elapsed = time_call([&] { - for_each (begin(a), end(a), [&](int n ) { - if (is_prime(n)) - ++prime_count; - }); - }); - wcout << L"serial version: " << endl - << L"found " << prime_count << L" prime numbers" << endl - << L"took " << elapsed << L" ms" << endl << endl; + // Use the parallel_for_each algorithm to count, in parallel, the number + // of prime numbers in the array. + prime_count = 0L; + elapsed = time_call([&] + { + parallel_for_each(begin(a), end(a), [&](int n) + { + if (is_prime(n)) + { + InterlockedIncrement(&prime_count); + } + }); + }); - // Use the parallel_for_each algorithm to count the number of prime numbers - // in the array in parallel. - prime_count = 0L; - elapsed = time_call([&] { - parallel_for_each (begin(a), end(a), [&](int n ) { - if (is_prime(n)) - InterlockedIncrement(&prime_count); - }); - }); - wcout << L"parallel version: " << endl - << L"found " << prime_count << L" prime numbers" << endl - << L"took " << elapsed << L" ms" << endl << endl; + wcout << L"parallel version: " << endl + << L"found " << prime_count << L" prime numbers" << endl + << L"took " << elapsed << L" ms" << endl << endl; } \ No newline at end of file diff --git a/docs/parallel/concrt/codesnippet/CPP/walkthrough-creating-a-dataflow-agent_2.cpp b/docs/parallel/concrt/codesnippet/CPP/walkthrough-creating-a-dataflow-agent_2.cpp index 3e692feda1c..d5c65363dd5 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/comparing-synchronization-data-structures-to-the-windows-api.md b/docs/parallel/concrt/comparing-synchronization-data-structures-to-the-windows-api.md index db3fe945cdf..bd772a4ef62 100644 --- a/docs/parallel/concrt/comparing-synchronization-data-structures-to-the-windows-api.md +++ b/docs/parallel/concrt/comparing-synchronization-data-structures-to-the-windows-api.md @@ -4,6 +4,7 @@ title: "Comparing Synchronization Data Structures to the Windows API" ms.date: "11/04/2016" helpviewer_keywords: ["synchronization data structures, compared to Windows API", "event class, example"] ms.assetid: 8b0b1a3a-ef80-408c-91fa-93e6af920b4e +ms.topic: concept-article --- # Comparing Synchronization Data Structures to the Windows API diff --git a/docs/parallel/concrt/comparing-the-concurrency-runtime-to-other-concurrency-models.md b/docs/parallel/concrt/comparing-the-concurrency-runtime-to-other-concurrency-models.md index 6ed662fcd00..6b4db8e930f 100644 --- a/docs/parallel/concrt/comparing-the-concurrency-runtime-to-other-concurrency-models.md +++ b/docs/parallel/concrt/comparing-the-concurrency-runtime-to-other-concurrency-models.md @@ -4,6 +4,7 @@ title: "Comparing the Concurrency Runtime to Other Concurrency Models" ms.date: "11/04/2016" helpviewer_keywords: ["Concurrency Runtime, compared to other models"] ms.assetid: d8b9a1f4-f15f-43c3-a5b4-c0991edf9c86 +ms.topic: concept-article --- # Comparing the Concurrency Runtime to Other Concurrency Models diff --git a/docs/parallel/concrt/concurrency-runtime-best-practices.md b/docs/parallel/concrt/concurrency-runtime-best-practices.md index a3406772d9e..17e5f8d963c 100644 --- a/docs/parallel/concrt/concurrency-runtime-best-practices.md +++ b/docs/parallel/concrt/concurrency-runtime-best-practices.md @@ -4,6 +4,7 @@ title: "Concurrency Runtime Best Practices" ms.date: "11/04/2016" helpviewer_keywords: ["best practices [Concurrency Runtime]", "Concurrency Runtime, practices to avoid", "practices to avoid [Concurrency Runtime]", "Concurrency Runtime, best practices"] ms.assetid: 7231d4be-d1e3-401d-8b66-94fd51b587c9 +ms.topic: best-practice --- # Concurrency Runtime Best Practices diff --git a/docs/parallel/concrt/contexts.md b/docs/parallel/concrt/contexts.md index 47042ab9efe..371b1142c8d 100644 --- a/docs/parallel/concrt/contexts.md +++ b/docs/parallel/concrt/contexts.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: Contexts" title: "Contexts" -ms.date: "11/04/2016" +description: "Learn more about: Contexts" +ms.date: 11/04/2016 helpviewer_keywords: ["contexts [Concurrency Runtime]"] -ms.assetid: 10c1d861-8fbb-4ba0-b2ec-61876b11176e --- # Contexts -This document describes the role of contexts in the Concurrency Runtime. A thread that is attached to a scheduler is known as an *execution context*, or just *context*. The [concurrency::wait](reference/concurrency-namespace-functions.md#wait) function and the concurrency::[Context class](../../parallel/concrt/reference/context-class.md) enable you to control the behavior of contexts. Use the `wait` function to suspend the current context for a specified time. Use the `Context` class when you need more control over when contexts block, unblock, and yield, or when you want to oversubscribe the current context. +This document describes the role of contexts in the Concurrency Runtime. A thread that is attached to a scheduler is known as an *execution context*, or just *context*. The [concurrency::wait](reference/concurrency-namespace-functions.md#wait) function and the [concurrency::Context class](../../parallel/concrt/reference/context-class.md) enable you to control the behavior of contexts. Use the `wait` function to suspend the current context for a specified time. Use the `Context` class when you need more control over when contexts block, unblock, and yield, or when you want to oversubscribe the current context. > [!TIP] > The Concurrency Runtime provides a default scheduler, and therefore you are not required to create one in your application. Because the Task Scheduler helps you fine-tune the performance of your applications, we recommend that you start with the [Parallel Patterns Library (PPL)](../../parallel/concrt/parallel-patterns-library-ppl.md) or the [Asynchronous Agents Library](../../parallel/concrt/asynchronous-agents-library.md) if you are new to the Concurrency Runtime. @@ -24,7 +23,7 @@ For an example that uses the `wait` function to yield the current context, and t ## The Context Class -The concurrency::[Context class](../../parallel/concrt/reference/context-class.md) provides a programming abstraction for an execution context and offers two important features: the ability to cooperatively block, unblock, and yield the current context, and the ability to oversubscribe the current context. +The [concurrency::Context class](../../parallel/concrt/reference/context-class.md) provides a programming abstraction for an execution context and offers two important features: the ability to cooperatively block, unblock, and yield the current context, and the ability to oversubscribe the current context. ### Cooperative Blocking diff --git a/docs/parallel/concrt/convert-an-openmp-loop-that-uses-a-reduction-variable.md b/docs/parallel/concrt/convert-an-openmp-loop-that-uses-a-reduction-variable.md index 456c664ae94..610f700e892 100644 --- a/docs/parallel/concrt/convert-an-openmp-loop-that-uses-a-reduction-variable.md +++ b/docs/parallel/concrt/convert-an-openmp-loop-that-uses-a-reduction-variable.md @@ -4,6 +4,7 @@ title: "How to: Convert an OpenMP Loop that Uses a Reduction Variable to Use the ms.date: "11/04/2016" helpviewer_keywords: ["converting from OpenMP to the Concurrency Runtime, reduction variables", "reduction variables, converting from OpenMP to the Concurrency Runtime"] ms.assetid: 96623f36-5e57-4d3f-8c13-669e6cd535b1 +ms.topic: how-to --- # How to: Convert an OpenMP Loop that Uses a Reduction Variable to Use the Concurrency Runtime diff --git a/docs/parallel/concrt/convert-an-openmp-loop-that-uses-cancellation.md b/docs/parallel/concrt/convert-an-openmp-loop-that-uses-cancellation.md index 2bb78350f39..0afc5284349 100644 --- a/docs/parallel/concrt/convert-an-openmp-loop-that-uses-cancellation.md +++ b/docs/parallel/concrt/convert-an-openmp-loop-that-uses-cancellation.md @@ -4,6 +4,7 @@ title: "How to: Convert an OpenMP Loop that Uses Cancellation to Use the Concurr ms.date: "11/04/2016" helpviewer_keywords: ["converting from OpenMP to the Concurrency Runtime, cancellation", "cancellation, converting from OpenMP to the Concurrency Runtime"] ms.assetid: 4b0b3c33-bfa9-4e96-ae08-aef245a39cbb +ms.topic: how-to --- # How to: Convert an OpenMP Loop that Uses Cancellation to Use the Concurrency Runtime diff --git a/docs/parallel/concrt/convert-an-openmp-loop-that-uses-exception-handling.md b/docs/parallel/concrt/convert-an-openmp-loop-that-uses-exception-handling.md index 7ccc8056816..2b4ed57d1bd 100644 --- a/docs/parallel/concrt/convert-an-openmp-loop-that-uses-exception-handling.md +++ b/docs/parallel/concrt/convert-an-openmp-loop-that-uses-exception-handling.md @@ -4,6 +4,7 @@ title: "How to: Convert an OpenMP Loop that Uses Exception Handling to Use the C ms.date: "11/04/2016" helpviewer_keywords: ["exception handling, converting from OpenMP to the Concurrency Runtime", "converting from OpenMP to the Concurrency Runtime, exception handling"] ms.assetid: 03c28196-21ba-439e-8641-afab1c283e1a +ms.topic: how-to --- # How to: Convert an OpenMP Loop that Uses Exception Handling to Use the Concurrency Runtime diff --git a/docs/parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md b/docs/parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md index 99750f5ce7c..ab148345553 100644 --- a/docs/parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md +++ b/docs/parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md @@ -4,6 +4,7 @@ title: "Creating Asynchronous Operations in C++ for UWP Apps" ms.date: "11/19/2018" helpviewer_keywords: ["Windows 8.x apps, creating C++ async operations", "Creating C++ async operations"] ms.assetid: a57cecf4-394a-4391-a957-1d52ed2e5494 +ms.topic: concept-article --- # Creating Asynchronous Operations in C++ for UWP Apps diff --git a/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md b/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md index e364db3f15d..222c1f490b9 100644 --- a/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md +++ b/docs/parallel/concrt/exception-handling-in-the-concurrency-runtime.md @@ -53,7 +53,7 @@ A task-based continuation enables you to handle any exception that is thrown by We recommend that you use task-based continuations to catch exceptions that you are able to handle. Because task-based continuations always run, consider whether to add a task-based continuation at the end of your continuation chain. This can help guarantee that your code observes all exceptions. The following example shows a basic value-based continuation chain. The third task in the chain throws, and therefore any value-based continuations that follow it are not run. However, the final continuation is task-based, and therefore always runs. This final continuation handles the exception that is thrown by the third task. -We recommend that you catch the most specific exceptions that you can. You can omit this final task-based continuation if you don’t have specific exceptions to catch. Any exception will remain unhandled and can terminate the app. +We recommend that you catch the most specific exceptions that you can. You can omit this final task-based continuation if you don't have specific exceptions to catch. Any exception will remain unhandled and can terminate the app. [!code-cpp[concrt-eh-task-chain#1](../../parallel/concrt/codesnippet/cpp/exception-handling-in-the-concurrency-runtime_3.cpp)] diff --git a/docs/parallel/concrt/general-best-practices-in-the-concurrency-runtime.md b/docs/parallel/concrt/general-best-practices-in-the-concurrency-runtime.md index cd72bb5c728..8e933fe5010 100644 --- a/docs/parallel/concrt/general-best-practices-in-the-concurrency-runtime.md +++ b/docs/parallel/concrt/general-best-practices-in-the-concurrency-runtime.md @@ -4,6 +4,7 @@ title: "General Best Practices in the Concurrency Runtime" ms.date: "11/04/2016" helpviewer_keywords: ["Concurrency Runtime, general best practices"] ms.assetid: ce5c784c-051e-44a6-be84-8b3e1139c18b +ms.topic: best-practice --- # General Best Practices in the Concurrency Runtime diff --git a/docs/parallel/concrt/how-to-send-a-message-at-a-regular-interval.md b/docs/parallel/concrt/how-to-send-a-message-at-a-regular-interval.md index 296c70f1280..b1eca2fb42f 100644 --- a/docs/parallel/concrt/how-to-send-a-message-at-a-regular-interval.md +++ b/docs/parallel/concrt/how-to-send-a-message-at-a-regular-interval.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: How to: Send a Message at a Regular Interval" title: "How to: Send a Message at a Regular Interval" -ms.date: "11/04/2016" +description: "Learn more about: How to: Send a Message at a Regular Interval" +ms.date: 11/04/2016 helpviewer_keywords: ["timer class, example", "sending messages at regular intervals [Concurrency Runtime]"] -ms.assetid: 4b60ea6c-97c8-4d69-9f7b-ad79f3548026 --- # How to: Send a Message at a Regular Interval -This example shows how to use the concurrency::[timer class](../../parallel/concrt/reference/timer-class.md) to send a message at a regular interval. +This example shows how to use the [concurrency::timer class](../../parallel/concrt/reference/timer-class.md) to send a message at a regular interval. ## Example diff --git a/docs/parallel/concrt/how-to-use-exception-handling-to-break-from-a-parallel-loop.md b/docs/parallel/concrt/how-to-use-exception-handling-to-break-from-a-parallel-loop.md index bf77fcfa780..19797cae521 100644 --- a/docs/parallel/concrt/how-to-use-exception-handling-to-break-from-a-parallel-loop.md +++ b/docs/parallel/concrt/how-to-use-exception-handling-to-break-from-a-parallel-loop.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: How to: Use Exception Handling to Break from a Parallel Loop" title: "How to: Use Exception Handling to Break from a Parallel Loop" -ms.date: "11/04/2016" +description: "Learn more about: How to: Use Exception Handling to Break from a Parallel Loop" +ms.date: 11/04/2016 helpviewer_keywords: ["search algorithm, writing [Concurrency Runtime]", "writing a search algorithm [Concurrency Runtime]"] -ms.assetid: 16d7278c-2d10-4014-9f58-f1899e719ff9 --- # How to: Use Exception Handling to Break from a Parallel Loop @@ -23,7 +22,7 @@ The following example shows the `for_all` method. It uses the [concurrency::para [!code-cpp[concrt-task-tree-search#1](../../parallel/concrt/codesnippet/cpp/how-to-use-exception-handling-to-break-from-a-parallel-loop_2.cpp)] -## Example: Search the tree for a value +## Example: Search the tree for a value The following example shows the `search_for_value` function, which searches for a value in the provided `tree` object. This function passes to the `for_all` method a work function that throws when it finds a tree node that contains the provided value. diff --git a/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md b/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md index 403e3bf2d78..78bf3601353 100644 --- a/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md +++ b/docs/parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md @@ -38,27 +38,27 @@ This section describes how to use the `parallel_invoke` algorithm to perform the 1. Add a `#include` directive for the header file ppl.h. -[!code-cpp[concrt-parallel-bitonic-sort#10](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_2.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#10](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_2.cpp)] 1. Add a **`using`** directive for the `concurrency` namespace. -[!code-cpp[concrt-parallel-bitonic-sort#11](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_3.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#11](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_3.cpp)] 1. Create a new function, called `parallel_bitonic_mege`, which uses the `parallel_invoke` algorithm to merge the sequences in parallel if there is sufficient amount of work to do. Otherwise, call `bitonic_merge` to merge the sequences serially. -[!code-cpp[concrt-parallel-bitonic-sort#2](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_4.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#2](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_4.cpp)] 1. Perform a process that resembles the one in the previous step, but for the `bitonic_sort` function. -[!code-cpp[concrt-parallel-bitonic-sort#3](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_5.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#3](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_5.cpp)] 1. Create an overloaded version of the `parallel_bitonic_sort` function that sorts the array in increasing order. -[!code-cpp[concrt-parallel-bitonic-sort#4](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_6.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#4](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_6.cpp)] -The `parallel_invoke` algorithm reduces overhead by performing the last of the series of tasks on the calling context. For example, in the `parallel_bitonic_sort` function, the first task runs on a separate context, and the second task runs on the calling context. + The `parallel_invoke` algorithm reduces overhead by performing the last of the series of tasks on the calling context. For example, in the `parallel_bitonic_sort` function, the first task runs on a separate context, and the second task runs on the calling context. -[!code-cpp[concrt-parallel-bitonic-sort#5](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_7.cpp)] + [!code-cpp[concrt-parallel-bitonic-sort#5](../../parallel/concrt/codesnippet/cpp/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine_7.cpp)] The following complete example performs both the serial and the parallel versions of the bitonic sort algorithm. The example also prints to the console the time that is required to perform each computation. diff --git a/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md b/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md index d7a5805ed78..3351136b798 100644 --- a/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md +++ b/docs/parallel/concrt/how-to-write-a-parallel-for-each-loop.md @@ -1,30 +1,29 @@ --- -description: "Learn more about: How to: Write a parallel_for_each Loop" -title: "How to: Write a parallel_for_each Loop" -ms.date: "11/04/2016" +description: "Learn more about how to write a parallel_for_each Loop" +title: "How to: write a parallel_for_each Loop" +ms.date: 09/12/2022 helpviewer_keywords: ["writing a parallel_for_each loop [Concurrency Runtime]", "parallel_for_each function, example"] -ms.assetid: fa9c0ba6-ace0-4f88-8681-c7c1f52aff20 --- -# How to: Write a parallel_for_each Loop +# How to: Write a `parallel_for_each` Loop -This example shows how to use the [concurrency::parallel_for_each](reference/concurrency-namespace-functions.md#parallel_for_each) algorithm to compute the count of prime numbers in a [std::array](../../standard-library/array-class-stl.md) object in parallel. +This example shows how to use the [`concurrency::parallel_for_each`](reference/concurrency-namespace-functions.md#parallel_for_each) algorithm to compute the count of prime numbers in a [`std::array`](../../standard-library/array-class-stl.md) object in parallel. ## Example -The following example computes the count of prime numbers in an array two times. The example first uses the [std::for_each](../../standard-library/algorithm-functions.md#for_each) algorithm to compute the count serially. The example then uses the `parallel_for_each` algorithm to perform the same task in parallel. The example also prints to the console the time that is required to perform both computations. +The following example computes the count of prime numbers in an array two times. The example first uses the [`std::for_each`](../../standard-library/algorithm-functions.md#for_each) algorithm to compute the count serially. The example then uses the `parallel_for_each` algorithm to perform the same task in parallel. The example also prints to the console the time that is required to perform both computations. [!code-cpp[concrt-parallel-count-primes#1](../../parallel/concrt/codesnippet/cpp/how-to-write-a-parallel-for-each-loop_1.cpp)] -The following sample output is for a computer that has four processors. +The following sample output is for a computer that has four cores. ```Output serial version: found 17984 prime numbers -took 6115 ms +took 125 ms parallel version: found 17984 prime numbers -took 1653 ms +took 63 ms ``` ## Compiling the Code @@ -35,9 +34,9 @@ To compile the code, copy it and then paste it in a Visual Studio project, or pa ## Robust Programming -The lambda expression that the example passes to the `parallel_for_each` algorithm uses the `InterlockedIncrement` function to enable parallel iterations of the loop to increment the counter simultaneously. If you use functions such as `InterlockedIncrement` to synchronize access to shared resources, you can present performance bottlenecks in your code. You can use a lock-free synchronization mechanism, for example, the [concurrency::combinable](../../parallel/concrt/reference/combinable-class.md) class, to eliminate simultaneous access to shared resources. For an example that uses the `combinable` class in this manner, see [How to: Use combinable to Improve Performance](../../parallel/concrt/how-to-use-combinable-to-improve-performance.md). +The lambda expression that the example passes to the `parallel_for_each` algorithm uses the `InterlockedIncrement` function to enable parallel iterations of the loop to increment the counter simultaneously. If you use functions such as `InterlockedIncrement` to synchronize access to shared resources, you can present performance bottlenecks in your code. You can use a lock-free synchronization mechanism, for example, the [`concurrency::combinable`](../../parallel/concrt/reference/combinable-class.md) class, to eliminate simultaneous access to shared resources. For an example that uses the `combinable` class in this manner, see [How to: Use combinable to improve performance](../../parallel/concrt/how-to-use-combinable-to-improve-performance.md). ## See also -[Parallel Algorithms](../../parallel/concrt/parallel-algorithms.md)
-[parallel_for_each Function](reference/concurrency-namespace-functions.md#parallel_for_each) +[Parallel algorithms](../../parallel/concrt/parallel-algorithms.md)\ +[`parallel_for_each` Function](reference/concurrency-namespace-functions.md#parallel_for_each) diff --git a/docs/parallel/concrt/migrating-from-openmp-to-the-concurrency-runtime.md b/docs/parallel/concrt/migrating-from-openmp-to-the-concurrency-runtime.md index 15d2ff642bd..8cce219c996 100644 --- a/docs/parallel/concrt/migrating-from-openmp-to-the-concurrency-runtime.md +++ b/docs/parallel/concrt/migrating-from-openmp-to-the-concurrency-runtime.md @@ -5,6 +5,7 @@ ms.date: "11/04/2016" helpviewer_keywords: ["Concurrency Runtime, migrating from OpenMP", "OpenMP, migrating to the Concurrency Runtime"] ms.assetid: 9bab7bb1-e45d-44b2-8509-3b226be2c93b ms.custom: intro-migration +ms.topic: upgrade-and-migration-article --- # Migrating from OpenMP to the Concurrency Runtime diff --git a/docs/parallel/concrt/overview-of-the-concurrency-runtime.md b/docs/parallel/concrt/overview-of-the-concurrency-runtime.md index e36669177c0..5c241631492 100644 --- a/docs/parallel/concrt/overview-of-the-concurrency-runtime.md +++ b/docs/parallel/concrt/overview-of-the-concurrency-runtime.md @@ -4,6 +4,7 @@ title: "Overview of the Concurrency Runtime" ms.date: "11/19/2018" helpviewer_keywords: ["Concurrency Runtime, requirements", "Concurrency Runtime, architecture", "Concurrency Runtime, overview", "Concurrency Runtime, lambda expressions"] ms.assetid: 56237d96-10b0-494a-9cb4-f5c5090436c5 +ms.topic: concept-article --- # Overview of the Concurrency Runtime diff --git a/docs/parallel/concrt/parallel-algorithms.md b/docs/parallel/concrt/parallel-algorithms.md index d6513e3a85c..8fb96cb02df 100644 --- a/docs/parallel/concrt/parallel-algorithms.md +++ b/docs/parallel/concrt/parallel-algorithms.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Parallel Algorithms" title: "Parallel Algorithms" -ms.date: "11/19/2018" +description: "Learn more about: Parallel Algorithms" +ms.date: 11/19/2018 helpviewer_keywords: ["parallel algorithms [Concurrency Runtime]"] -ms.assetid: 045dca7b-4d73-4558-a44c-383b88a28473 +ms.topic: how-to --- # Parallel Algorithms @@ -143,7 +143,7 @@ You can use the `parallel transform` algorithm to perform many data parallelizat - Perform 3-D ray tracing, where each iteration refers to one pixel that must be rendered. -The following example shows the basic structure that is used to call the `parallel_transform` algorithm. This example negates each element of a std::[vector](../../standard-library/vector-class.md) object in two ways. The first way uses a lambda expression. The second way uses [std::negate](../../standard-library/negate-struct.md), which derives from [std::unary_function](../../standard-library/unary-function-struct.md). +The following example shows the basic structure that is used to call the `parallel_transform` algorithm. This example negates each element of a [std::vector](../../standard-library/vector-class.md) object in two ways. The first way uses a lambda expression. The second way uses [std::negate](../../standard-library/negate-struct.md), which derives from [std::unary_function](../../standard-library/unary-function-struct.md). [!code-cpp[concrt-basic-parallel-transform#1](../../parallel/concrt/codesnippet/cpp/parallel-algorithms_4.cpp)] @@ -206,7 +206,7 @@ Divides work into ranges such that each range has at least the number of iterati Divides work into a fixed number of ranges (typically the number of worker threads that are available to work on the loop). This partitioner type can improve performance because it does not use work-stealing and therefore has less overhead. Use this partitioner type when each iteration of a parallel loop performs a fixed and uniform amount of work and you do not require support for cancellation or forward cooperative blocking. > [!WARNING] -> The `parallel_for_each` and `parallel_transform` algorithms support only containers that use random access iterators (such as std::[vector](../../standard-library/vector-class.md)) for the static, simple, and affinity partitioners. The use of containers that use bidirectional and forward iterators produces a compile-time error. The default partitioner, `auto_partitioner`, supports all three of these iterator types. +> The `parallel_for_each` and `parallel_transform` algorithms support only containers that use random access iterators (such as [std::vector](../../standard-library/vector-class.md)) for the static, simple, and affinity partitioners. The use of containers that use bidirectional and forward iterators produces a compile-time error. The default partitioner, `auto_partitioner`, supports all three of these iterator types. Typically, these partitioners are used in the same way, except for `affinity_partitioner`. Most partitioner types do not maintain state and are not modified by the runtime. Therefore you can create these partitioner objects at the call site, as shown in the following example. @@ -262,10 +262,10 @@ This example shows how to provide a hash function to the `parallel_radixsort` al For illustration, this example uses a relatively small data set. You can increase the initial size of the vector to experiment with performance improvements over larger sets of data. -This example uses a lambda expression as the hash function. You can also use one of the built-in implementations of the std::[hash class](../../standard-library/hash-class.md) or define your own specialization. You can also use a custom hash function object, as shown in this example: +This example uses a lambda expression as the hash function. You can also use one of the built-in implementations of the [std::hash class](../../standard-library/hash-class.md) or define your own specialization. You can also use a custom hash function object, as shown in this example: [!code-cpp[concrt-parallel-sort-points#2](../../parallel/concrt/codesnippet/cpp/parallel-algorithms_13.cpp)] - +  [!code-cpp[concrt-parallel-sort-points#3](../../parallel/concrt/codesnippet/cpp/parallel-algorithms_14.cpp)] The hash function must return an integral type ([std::is_integral::value](../../standard-library/is-integral-class.md) must be **`true`**). This integral type must be convertible to type `size_t`. diff --git a/docs/parallel/concrt/reference/concurrency-namespace-constants1.md b/docs/parallel/concrt/reference/concurrency-namespace-constants1.md index 2cad1ace3d7..38f2288982e 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace-constants1.md +++ b/docs/parallel/concrt/reference/concurrency-namespace-constants1.md @@ -1,38 +1,12 @@ --- -description: "Learn more about: concurrency namespace constants" title: "concurrency namespace constants" -ms.date: "11/04/2016" +description: "Learn more about: concurrency namespace constants" +ms.date: 11/04/2016 f1_keywords: ["concrt/concurrency::AgentEventGuid", "concrt/concurrency::COOPERATIVE_TIMEOUT_INFINITE", "concrt/concurrency::COOPERATIVE_WAIT_TIMEOUT", "concrt/concurrency::ConcRTEventGuid", "concrt/concurrency::ConcRT_ProviderGuid", "concrt/concurrency::INHERIT_THREAD_PRIORITY", "concrt/concurrency::LockEventGuid", "concrt/concurrency::PPLParallelForEventGuid", "concrt/concurrency::PPLParallelForeachEventGuid", "concrt/concurrency::ResourceManagerEventGuid", "concrt/concurrency::ScheduleGroupEventGuid", "concrt/concurrency::VirtualProcessorEventGuid"] -ms.assetid: 6f81fc4c-b10c-479e-8717-9c292360d5a0 --- # concurrency namespace constants -:::row::: - :::column span=""::: - [`AgentEventGuid`](#agenteventguid)\ - [`CONCRT_RM_VERSION_1`](#concrt_rm_version_1)\ - [`COOPERATIVE_TIMEOUT_INFINITE`](#cooperative_timeout_infinite)\ - [`COOPERATIVE_WAIT_TIMEOUT`](#cooperative_wait_timeout)\ - [`ChoreEventGuid`](#choreeventguid)\ - [`ConcRTEventGuid`](#concrteventguid) - :::column-end::: - :::column span=""::: - [`ConcRT_ProviderGuid`](#concrt_providerguid)\ - [`ContextEventGuid`](#contexteventguid)\ - [`INHERIT_THREAD_PRIORITY`](#inherit_thread_priority)\ - [`LockEventGuid`](#lockeventguid)\ - [`MaxExecutionResources`](#maxexecutionresources)\ - [`PPLParallelForEventGuid`](#pplparallelforeventguid) - :::column-end::: - :::column span=""::: - [`PPLParallelForeachEventGuid`](#pplparallelforeacheventguid)\ - [`PPLParallelInvokeEventGuid`](#pplparallelinvokeeventguid)\ - [`ResourceManagerEventGuid`](#resourcemanagereventguid)\ - [`ScheduleGroupEventGuid`](#schedulegroupeventguid)\ - [`SchedulerEventGuid`](#schedulereventguid)\ - [`VirtualProcessorEventGuid`](#virtualprocessoreventguid) - :::column-end::: -:::row-end::: +The following constants are defined in the `concurrency` namespace: ## AgentEventGuid diff --git a/docs/parallel/concrt/reference/concurrency-namespace-enums.md b/docs/parallel/concrt/reference/concurrency-namespace-enums.md index 6d6ed28540c..c3502ea9299 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace-enums.md +++ b/docs/parallel/concrt/reference/concurrency-namespace-enums.md @@ -1,34 +1,12 @@ --- -description: "Learn more about: concurrency namespace enums" title: "concurrency namespace enums" -ms.date: "11/04/2016" +description: "Learn more about: concurrency namespace enums" +ms.date: 11/04/2016 f1_keywords: ["CONCRT/concurrency::Agents_EventType", "CONCRT/concurrency::Concrt_TraceFlags", "CONCRT/concurrency::CriticalRegionType", "CONCRT/concurrency::PolicyElementKey", "CONCRT/concurrency::SchedulerType", "CONCRT/concurrency::SwitchingProxyState", "CONCRT/concurrency::WinRTInitializationType", "CONCRT/concurrency::join_type", "CONCRT/concurrency::message_status Enumeration"] -ms.assetid: a40e3b2d-ad21-4229-9880-2cfa84f7ab8f --- # concurrency namespace enums -:::row::: - :::column span=""::: - [`agent_status`](#agent_status)\ - [`Agents_EventType`](#agents_eventtype)\ - [`ConcRT_EventType`](#concrt_eventtype)\ - [`Concrt_TraceFlags`](#concrt_traceflags)\ - [`CriticalRegionType`](#criticalregiontype) - :::column-end::: - :::column span=""::: - [`DynamicProgressFeedbackType`](#dynamicprogressfeedbacktype)\ - [`join_type`](#join_type)\ - [`message_status`](#message_status)\ - [`PolicyElementKey`](#policyelementkey)\ - [`SchedulerType`](#schedulertype) - :::column-end::: - :::column span=""::: - [`SchedulingProtocolType`](#schedulingprotocoltype)\ - [`SwitchingProxyState`](#switchingproxystate)\ - [`task_group_status`](#task_group_status)\ - [`WinRTInitializationType`](#winrtinitializationtype) - :::column-end::: -:::row-end::: +The following enumerations are available in the `concurrency` namespace: ## agent_status Enumeration diff --git a/docs/parallel/concrt/reference/concurrency-namespace-functions.md b/docs/parallel/concrt/reference/concurrency-namespace-functions.md index f1aea9adb84..03771f4a1aa 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace-functions.md +++ b/docs/parallel/concrt/reference/concurrency-namespace-functions.md @@ -1,64 +1,12 @@ --- -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 -:::row::: - :::column span=""::: - [`Alloc`](#alloc)\ - [`asend`](#asend)\ - [`cancel_current_task`](#cancel_current_task)\ - [`clear`](#clear)\ - [`create_async`](#create_async)\ - [`create_task`](#create_task)\ - [`CreateResourceManager`](#createresourcemanager)\ - [`DisableTracing`](#disabletracing)\ - [`EnableTracing`](#enabletracing)\ - [`Free`](#free)\ - [`get_ambient_scheduler`](#get_ambient_scheduler)\ - [`GetExecutionContextId`](#getexecutioncontextid)\ - [`GetOSVersion`](#getosversion)\ - [`GetProcessorCount`](#getprocessorcount)\ - [`GetProcessorNodeCount`](#getprocessornodecount) - :::column-end::: - :::column span=""::: - [`GetSchedulerId`](#getschedulerid)\ - [`internal_assign_iterators`](#internal_assign_iterators)\ - [`interruption_point`](#interruption_point)\ - [`is_current_task_group_canceling`](#is_current_task_group_canceling)\ - [`make_choice`](#make_choice)\ - [`make_greedy_join`](#make_greedy_join)\ - [`make_join`](#make_join)\ - [`make_task`](#make_task)\ - [`parallel_buffered_sort`](#parallel_buffered_sort)\ - [`parallel_for_each`](#parallel_for_each)\ - [`parallel_for`](#parallel_for)\ - [`parallel_invoke`](#parallel_invoke)\ - [`parallel_radixsort`](#parallel_radixsort)\ - [`parallel_reduce`](#parallel_reduce)\ - [`parallel_sort`](#parallel_sort) - :::column-end::: - :::column span=""::: - [`parallel_transform`](#parallel_transform)\ - [`receive`](#receive)\ - [`run_with_cancellation_token`](#run_with_cancellation_token)\ - [`send`](#send)\ - [`set_ambient_scheduler`](#set_ambient_scheduler)\ - [`set_task_execution_resources`](#set_task_execution_resources)\ - [`swap`](#swap)\ - [`task_from_exception`](#task_from_exception)\ - [`task_from_result`](#task_from_result)\ - [`Trace_agents_register_name`](#trace_agents_register_name)\ - [`try_receive`](#try_receive)\ - [`wait`](#wait)\ - [`when_all`](#when_all)\ - [`when_any`](#when_any) - :::column-end::: -:::row-end::: +The following functions are available in the `concurrency` namespace: ## Alloc @@ -169,13 +117,13 @@ The return type of the lambda determines whether the construct is an action or a Lambdas that return void cause the creation of actions. Lambdas that return a result of type `TResult` cause the creation of operations of TResult. -The lambda may also return a `task` which encapsulates the aysnchronous work within itself or is the continuation of a chain of tasks that represent the asynchronous work. In this case, the lambda itself is executed inline, since the tasks are the ones that execute asynchronously, and the return type of the lambda is unwrapped to produce the asynchronous construct returned by `create_async`. This implies that a lambda that returns a task\ will cause the creation of actions, and a lambda that returns a task\ will cause the creation of operations of TResult. +The lambda may also return a `task` which encapsulates the asynchronous work within itself or is the continuation of a chain of tasks that represent the asynchronous work. In this case, the lambda itself is executed inline, since the tasks are the ones that execute asynchronously, and the return type of the lambda is unwrapped to produce the asynchronous construct returned by `create_async`. This implies that a lambda that returns a task\ will cause the creation of actions, and a lambda that returns a task\ will cause the creation of operations of TResult. The lambda may take either zero, one or two arguments. The valid arguments are `progress_reporter` and `cancellation_token`, in that order if both are used. A lambda without arguments causes the creation of an asynchronous construct without the capability for progress reporting. A lambda that takes a progress_reporter\ will cause `create_async` to return an asynchronous construct which reports progress of type TProgress each time the `report` method of the progress_reporter object is called. A lambda that takes a cancellation_token may use that token to check for cancellation, or pass it to tasks that it creates so that cancellation of the asynchronous construct causes cancellation of those tasks. -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 or function object returns a result (and not a task\), the lambda 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 +1480,7 @@ The concurrent vector providing the elements to be swapped, or the vector whose ### Remarks -The template function is an algorithm specialized on the container class `concurrent_vector` to execute the member function `_A`. [concurrent_vector::swap](concurrent-vector-class.md#swap)( `_B`). These are instances of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, `template void swap(T&, T&)`, in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. +The template function is an algorithm specialized on the container class `concurrent_vector` to execute the member function `_A`. [concurrent_vector::swap](concurrent-vector-class.md#swap)(`_B`). These are instances of the partial ordering of function templates by the compiler. When template functions are overloaded in such a way that the match of the template with the function call is not unique, then the compiler will select the most specialized version of the template function. The general version of the template function, `template void swap(T&, T&)`, in the algorithm class works by assignment and is a slow operation. The specialized version in each container is much faster as it can work with the internal representation of the container class. This method is not concurrency-safe. You must ensure that no other threads are performing operations on either of the concurrent vectors when you call this method. diff --git a/docs/parallel/concrt/reference/concurrency-namespace-operators.md b/docs/parallel/concrt/reference/concurrency-namespace-operators.md index d3deea034e0..cb9e6005079 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace-operators.md +++ b/docs/parallel/concrt/reference/concurrency-namespace-operators.md @@ -1,30 +1,12 @@ --- -description: "Learn more about: concurrency namespace Operators" title: "concurrency namespace Operators" -ms.date: "11/04/2016" +description: "Learn more about: concurrency namespace Operators" +ms.date: 11/04/2016 f1_keywords: ["concrt/concurrency::operator!=", "concrt/concurrency::operator&&"] -ms.assetid: 8e373f23-fc8e-49f7-82e6-ba0c57b822f8 --- # concurrency namespace Operators -:::row::: - :::column span=""::: - [`operator||`](#operator_lor)\ - [`operator&&`](#operator_amp_amp) - :::column-end::: - :::column span=""::: - [`operator==`](#operator_eq_eq)\ - [`operator!=`](#operator_neq) - :::column-end::: - :::column span=""::: - [`operator<`](#operator_lt)\ - [`operator<=`](#operator_lt_eq) - :::column-end::: - :::column span=""::: - [`operator>`](#operator_gt)\ - [`operator>=`](#operator_gt_eq) - :::column-end::: -:::row-end::: +The following operators are available in the `concurrency` namespace: ## `operator||` Operator diff --git a/docs/parallel/concrt/reference/concurrency-namespace.md b/docs/parallel/concrt/reference/concurrency-namespace.md index a336049731c..db453f19ce6 100644 --- a/docs/parallel/concrt/reference/concurrency-namespace.md +++ b/docs/parallel/concrt/reference/concurrency-namespace.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: concurrency Namespace" title: "concurrency Namespace" -ms.date: "11/04/2016" +description: "Learn more about: concurrency Namespace" +ms.date: 11/04/2016 f1_keywords: ["concurrent_priority_queue/concurrency", "agents/concurrency", "concurrent_vector/concurrency", "concrt/concurrency", "internal_split_ordered_list/concurrency", "concurrent_queue/concurrency", "pplcancellation_token/concurrency", "pplinterface/concurrency", "ppltasks/concurrency", "ppl/concurrency", "concurrent_unordered_map/concurrency", "concrtrm/concurrency", "concurrent_unordered_set/concurrency", "pplconcrt/concurrency", "internal_concurrent_hash/concurrency"] helpviewer_keywords: ["Concurrency namespace"] -ms.assetid: f1d33ca2-679b-4442-b140-22a9d9df61d1 --- # concurrency Namespace @@ -208,7 +207,7 @@ namespace concurrency; |[operator<=](concurrency-namespace-operators.md#operator_lt_eq)|Tests if the `concurrent_vector` object on the left side of the operator is less than or equal to the `concurrent_vector` object on the right side.| |[operator==](concurrency-namespace-operators.md#operator_eq_eq)|Tests if the `concurrent_vector` object on the left side of the operator is equal to the `concurrent_vector` object on the right side.| |[operator>](concurrency-namespace-operators.md#operator_gt)|Tests if the `concurrent_vector` object on the left side of the operator is greater than the `concurrent_vector` object on the right side.| -|[operator>=](concurrency-namespace-operators.md#operator_lt_eq)|Tests if the `concurrent_vector` object on the left side of the operator is greater than or equal to the `concurrent_vector` object on the right side.| +|[operator>=](concurrency-namespace-operators.md#operator_gt_eq)|Tests if the `concurrent_vector` object on the left side of the operator is greater than or equal to the `concurrent_vector` object on the right side.| ### Constants diff --git a/docs/parallel/concrt/reference/concurrent-priority-queue-class.md b/docs/parallel/concrt/reference/concurrent-priority-queue-class.md index 8e190a3606a..5a6ba9ae4e4 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 c9e47fc292c..b777495b547 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 9ede5be1d2e..a28357a21e9 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 3684631591c..487bba17809 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 52f91b4cfab..5265d958e55 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 af0edeecb83..1bdeb6f2c0c 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/event-class.md b/docs/parallel/concrt/reference/event-class.md index 699ecf71814..0be9869316a 100644 --- a/docs/parallel/concrt/reference/event-class.md +++ b/docs/parallel/concrt/reference/event-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: event Class" title: "event Class" -ms.date: "11/04/2016" +description: "Learn more about: event Class" +ms.date: 11/04/2016 f1_keywords: ["CONCRT/concurrency::event", "CONCRT/concurrency::event::reset", "CONCRT/concurrency::event::set", "CONCRT/concurrency::event::wait", "CONCRT/concurrency::event::wait_for_multiple", "CONCRT/concurrency::event::timeout_infinite"] helpviewer_keywords: ["event class"] -ms.assetid: fba35a53-6568-4bfa-9aaf-07c0928cf73d --- # event Class @@ -61,8 +60,6 @@ Constructs a new event. _CRTIMP event(); ``` -### Remarks - ## ~event Destroys an event. 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 b88cbe2494f..eb5b16e0959 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 111cc7fea26..8fbbc42ddfb 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 eba54f6f742..ef5263b57d2 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 d3ab18135c1..ce7031d8161 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 5f90e1fb296..18fabb896ca 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 b5e9aa9241c..f5674f3eea4 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/schedule-groups.md b/docs/parallel/concrt/schedule-groups.md index 72566cc7114..b50caaa5999 100644 --- a/docs/parallel/concrt/schedule-groups.md +++ b/docs/parallel/concrt/schedule-groups.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Schedule Groups" title: "Schedule Groups" -ms.date: "11/04/2016" +description: "Learn more about: Schedule Groups" +ms.date: 11/04/2016 helpviewer_keywords: ["schedule groups"] -ms.assetid: 03523572-5891-4d17-89ce-fa795605f28b --- # Schedule Groups @@ -18,7 +17,7 @@ The `SchedulingProtocol` scheduler policy influences the order in which the sche The runtime uses the [concurrency::ScheduleGroup](../../parallel/concrt/reference/schedulegroup-class.md) class to represent schedule groups. To create a `ScheduleGroup` object, call the [concurrency::CurrentScheduler::CreateScheduleGroup](reference/currentscheduler-class.md#createschedulegroup) or [concurrency::Scheduler::CreateScheduleGroup](reference/scheduler-class.md#createschedulegroup) method. The runtime uses a reference-counting mechanism to control the lifetime of `ScheduleGroup` objects, just as it does with `Scheduler` objects. When you create a `ScheduleGroup` object, the runtime sets the reference counter to one. The [concurrency::ScheduleGroup::Reference](reference/schedulegroup-class.md#reference) method increments the reference counter by one. The [concurrency::ScheduleGroup::Release](reference/schedulegroup-class.md#release) method decrements the reference counter by one. -Many types in the Concurrency Runtime let you associate an object together with a schedule group. For example, the [concurrency::agent](../../parallel/concrt/reference/agent-class.md) class and message block classes such as [concurrency::unbounded_buffer](reference/unbounded-buffer-class.md), [concurrency::join](../../parallel/concrt/reference/join-class.md), and concurrency::[timer](reference/timer-class.md), provide overloaded versions of the constructor that take a `ScheduleGroup` object. The runtime uses the `Scheduler` object that is associated with this `ScheduleGroup` object to schedule the task. +Many types in the Concurrency Runtime let you associate an object together with a schedule group. For example, the [concurrency::agent](../../parallel/concrt/reference/agent-class.md) class and message block classes such as [concurrency::unbounded_buffer](reference/unbounded-buffer-class.md), [concurrency::join](../../parallel/concrt/reference/join-class.md), and [concurrency::timer](reference/timer-class.md), provide overloaded versions of the constructor that take a `ScheduleGroup` object. The runtime uses the `Scheduler` object that is associated with this `ScheduleGroup` object to schedule the task. You can also use the [concurrency::ScheduleGroup::ScheduleTask](reference/schedulegroup-class.md#scheduletask) method to schedule a lightweight task. For more information about lightweight tasks, see [Lightweight Tasks](../../parallel/concrt/lightweight-tasks.md). diff --git a/docs/parallel/concrt/task-parallelism-concurrency-runtime.md b/docs/parallel/concrt/task-parallelism-concurrency-runtime.md index 06706486753..d6ab7f02cc6 100644 --- a/docs/parallel/concrt/task-parallelism-concurrency-runtime.md +++ b/docs/parallel/concrt/task-parallelism-concurrency-runtime.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: Task Parallelism (Concurrency Runtime)" title: "Task Parallelism (Concurrency Runtime)" -ms.date: "11/04/2016" +description: "Learn more about: Task Parallelism (Concurrency Runtime)" +ms.date: 11/04/2016 helpviewer_keywords: ["structured task groups [Concurrency Runtime]", "structured tasks [Concurrency Runtime]", "task groups [Concurrency Runtime]", "task parallelism", "tasks [Concurrency Runtime]"] -ms.assetid: 42f05ac3-2098-494a-ba84-737fcdcad077 +ms.topic: how-to --- # Task Parallelism (Concurrency Runtime) @@ -150,7 +150,7 @@ This section describes the [concurrency::when_all](reference/concurrency-namespa ### The when_all Function -The `when_all` function produces a task that completes after a set of tasks complete. This function returns a std::[vector](../../standard-library/vector-class.md) object that contains the result of each task in the set. The following basic example uses `when_all` to create a task that represents the completion of three other tasks. +The `when_all` function produces a task that completes after a set of tasks complete. This function returns a [std::vector](../../standard-library/vector-class.md) object that contains the result of each task in the set. The following basic example uses `when_all` to create a task that represents the completion of three other tasks. [!code-cpp[concrt-join-tasks#1](../../parallel/concrt/codesnippet/cpp/task-parallelism-concurrency-runtime_8.cpp)] @@ -257,7 +257,7 @@ The runtime also provides an exception-handling model that enables you to throw Although we recommend that you use `task_group` or `parallel_invoke` instead of the `structured_task_group` class, there are cases where you want to use `structured_task_group`, for example, when you write a parallel algorithm that performs a variable number of tasks or requires support for cancellation. This section explains the differences between the `task_group` and `structured_task_group` classes. -The `task_group` class is thread-safe. Therefore you can add tasks to a `task_group` object from multiple threads and wait on or cancel a `task_group` object from multiple threads. The construction and destruction of a `structured_task_group` object must occur in the same lexical scope. In addition, all operations on a `structured_task_group` object must occur on the same thread. The exception to this rule is the [concurrency::structured_task_group::cancel](reference/structured-task-group-class.md#cancel) and [concurrency::structured_task_group::is_canceling](reference/structured-task-group-class.md#is_canceling) methods. A child task can call these methods to cancel the parent task group or check for cancelation at any time. +The `task_group` class is thread-safe. Therefore you can add tasks to a `task_group` object from multiple threads and wait on or cancel a `task_group` object from multiple threads. The construction and destruction of a `structured_task_group` object must occur in the same lexical scope. In addition, all operations on a `structured_task_group` object must occur on the same thread. The exception to this rule is the [concurrency::structured_task_group::cancel](reference/structured-task-group-class.md#cancel) and [concurrency::structured_task_group::is_canceling](reference/structured-task-group-class.md#is_canceling) methods. A child task can call these methods to cancel the parent task group or check for cancellation at any time. You can run additional tasks on a `task_group` object after you call the [concurrency::task_group::wait](reference/task-group-class.md#wait) or [concurrency::task_group::run_and_wait](reference/task-group-class.md#run_and_wait) method. Conversely, if you run additional tasks on a `structured_task_group` object after you call the [concurrency::structured_task_group::wait](reference/structured-task-group-class.md#wait) or [concurrency::structured_task_group::run_and_wait](reference/structured-task-group-class.md#run_and_wait) methods, then the behavior is undefined. @@ -269,7 +269,7 @@ Unstructured task groups and structured task groups work with task handles in di [!code-cpp[concrt-make-task-structure#1](../../parallel/concrt/codesnippet/cpp/task-parallelism-concurrency-runtime_16.cpp)] -To manage task handles for cases where you have a variable number of tasks, use a stack-allocation routine such as [_malloca](../../c-runtime-library/reference/malloca.md) or a container class, such as std::[vector](../../standard-library/vector-class.md). +To manage task handles for cases where you have a variable number of tasks, use a stack-allocation routine such as [_malloca](../../c-runtime-library/reference/malloca.md) or a container class, such as [std::vector](../../standard-library/vector-class.md). Both `task_group` and `structured_task_group` support cancellation. For more information about cancellation, see [Cancellation in the PPL](cancellation-in-the-ppl.md). diff --git a/docs/parallel/concrt/task-scheduler-concurrency-runtime.md b/docs/parallel/concrt/task-scheduler-concurrency-runtime.md index 4d42336b9f1..d2ebbf48db1 100644 --- a/docs/parallel/concrt/task-scheduler-concurrency-runtime.md +++ b/docs/parallel/concrt/task-scheduler-concurrency-runtime.md @@ -7,7 +7,7 @@ ms.assetid: 9aba278c-e0c9-4ede-b7c6-fedf7a365d90 --- # Task Scheduler (Concurrency Runtime) -The topics in this part of the documentation describe the important features of the Concurrency Runtime Task Scheduler. The Task Scheduler is useful when you want fine-tune the performance of your existing code that uses the Concurrency Runtime. +The topics in this part of the documentation describe the important features of the Concurrency Runtime Task Scheduler. The Task Scheduler is useful when you want to fine-tune the performance of your existing code that uses the Concurrency Runtime. > [!IMPORTANT] > The Task Scheduler is not available from a Universal Windows Platform (UWP) app. For more information, see [Creating Asynchronous Operations in C++ for UWP Apps](../../parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md). diff --git a/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md b/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md index 480505f81e3..1ff8dab877d 100644 --- a/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md +++ b/docs/parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md @@ -29,7 +29,7 @@ UWP support is optional in Visual Studio 2017 and later. To install it, open the When you use the `IXMLHTTPRequest2` interface to create web requests over HTTP, you implement the `IXMLHTTPRequest2Callback` interface to receive the server response and react to other events. This example defines the `HttpRequest` class to create web requests, and the `HttpRequestBuffersCallback` and `HttpRequestStringCallback` classes to process responses. The `HttpRequestBuffersCallback` and `HttpRequestStringCallback` classes support the `HttpRequest` class; you work only with the `HttpRequest` class from application code. -The `GetAsync`, `PostAsync` methods of the `HttpRequest` class enable you to start HTTP GET and POST operations, respectively. These methods use the `HttpRequestStringCallback` class to read the server response as a string. The `SendAsync` and `ReadAsync` methods enable you to stream large content in chunks. These methods each return [concurrency::task](../../parallel/concrt/reference/task-class.md) to represent the operation. The `GetAsync` and `PostAsync` methods produce `task` value, where the `wstring` part represents the server’s response. The `SendAsync` and `ReadAsync` methods produce `task` values; these tasks complete when the send and read operations complete. +The `GetAsync`, `PostAsync` methods of the `HttpRequest` class enable you to start HTTP GET and POST operations, respectively. These methods use the `HttpRequestStringCallback` class to read the server response as a string. The `SendAsync` and `ReadAsync` methods enable you to stream large content in chunks. These methods each return [concurrency::task](../../parallel/concrt/reference/task-class.md) to represent the operation. The `GetAsync` and `PostAsync` methods produce `task` value, where the `wstring` part represents the server's response. The `SendAsync` and `ReadAsync` methods produce `task` values; these tasks complete when the send and read operations complete. Because the `IXMLHTTPRequest2` interfaces act asynchronously, this example uses [concurrency::task_completion_event](../../parallel/concrt/reference/task-completion-event-class.md) to create a task that completes after the callback object completes or cancels the download operation. The `HttpRequest` class creates a task-based continuation from this task to set the final result. The `HttpRequest` class uses a task-based continuation to ensure that the continuation task runs even if the previous task produces an error or is canceled. For more information about task-based continuations, see [Task Parallelism](../../parallel/concrt/task-parallelism-concurrency-runtime.md) diff --git a/docs/parallel/concrt/walkthrough-creating-a-custom-message-block.md b/docs/parallel/concrt/walkthrough-creating-a-custom-message-block.md index debf678980b..c34f0946a6c 100644 --- a/docs/parallel/concrt/walkthrough-creating-a-custom-message-block.md +++ b/docs/parallel/concrt/walkthrough-creating-a-custom-message-block.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Walkthrough: Creating a Custom Message Block" title: "Walkthrough: Creating a Custom Message Block" -ms.date: "04/25/2019" +description: "Learn more about: Walkthrough: Creating a Custom Message Block" +ms.date: 04/25/2019 helpviewer_keywords: ["creating custom message blocks Concurrency Runtime]", "custom message blocks, creating [Concurrency Runtime]"] -ms.assetid: 4c6477ad-613c-4cac-8e94-2c9e63cd43a1 --- # Walkthrough: Creating a Custom Message Block @@ -57,7 +56,7 @@ The runtime calls the `propagate_message` method to asynchronously transfer a me The `priority_buffer` class is a custom message block type that orders incoming messages first by priority, and then by the order in which messages are received. The `priority_buffer` class resembles the [concurrency::unbounded_buffer](reference/unbounded-buffer-class.md) class because it holds a queue of messages, and also because it acts as both a source and a target message block and can have both multiple sources and multiple targets. However, `unbounded_buffer` bases message propagation only on the order in which it receives messages from its sources. -The `priority_buffer` class receives messages of type std::[tuple](../../standard-library/tuple-class.md) that contain `PriorityType` and `Type` elements. `PriorityType` refers to the type that holds the priority of each message; `Type` refers to the data portion of the message. The `priority_buffer` class sends messages of type `Type`. The `priority_buffer` class also manages two message queues: a [std::priority_queue](../../standard-library/priority-queue-class.md) object for incoming messages and a std::[queue](../../standard-library/queue-class.md) object for outgoing messages. Ordering messages by priority is useful when a `priority_buffer` object receives multiple messages simultaneously or when it receives multiple messages before any messages are read by consumers. +The `priority_buffer` class receives messages of type [std::tuple](../../standard-library/tuple-class.md) that contain `PriorityType` and `Type` elements. `PriorityType` refers to the type that holds the priority of each message; `Type` refers to the data portion of the message. The `priority_buffer` class sends messages of type `Type`. The `priority_buffer` class also manages two message queues: a [std::priority_queue](../../standard-library/priority-queue-class.md) object for incoming messages and a [std::queue](../../standard-library/queue-class.md) object for outgoing messages. Ordering messages by priority is useful when a `priority_buffer` object receives multiple messages simultaneously or when it receives multiple messages before any messages are read by consumers. In addition to the seven methods that a class that derives from `propagator_block` must implement, the `priority_buffer` class also overrides the `link_target_notification` and `send_message` methods. The `priority_buffer` class also defines two public helper methods, `enqueue` and `dequeue`, and a private helper method, `propagate_priority_order`. @@ -71,7 +70,7 @@ The following procedure describes how to implement the `priority_buffer` class. [!code-cpp[concrt-priority-buffer#1](../../parallel/concrt/codesnippet/cpp/walkthrough-creating-a-custom-message-block_2.h)] -1. In the `std` namespace, define specializations of [std::less](../../standard-library/less-struct.md) and [std::greater](../../standard-library/greater-struct.md) that act on concurrency::[message](../../parallel/concrt/reference/message-class.md) objects. +1. In the `std` namespace, define specializations of [std::less](../../standard-library/less-struct.md) and [std::greater](../../standard-library/greater-struct.md) that act on [concurrency::message](../../parallel/concrt/reference/message-class.md) objects. [!code-cpp[concrt-priority-buffer#2](../../parallel/concrt/codesnippet/cpp/walkthrough-creating-a-custom-message-block_3.h)] diff --git a/docs/parallel/concrt/walkthrough-implementing-futures.md b/docs/parallel/concrt/walkthrough-implementing-futures.md index 0eeeb8f2e62..0634c431d40 100644 --- a/docs/parallel/concrt/walkthrough-implementing-futures.md +++ b/docs/parallel/concrt/walkthrough-implementing-futures.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Walkthrough: Implementing Futures" title: "Walkthrough: Implementing Futures" -ms.date: "04/25/2019" +description: "Learn more about: Walkthrough: Implementing Futures" +ms.date: 04/25/2019 helpviewer_keywords: ["implementing futures [Concurrency Runtime]", "futures, implementing [Concurrency Runtime]"] -ms.assetid: 82ea75cc-aaec-4452-b10d-8abce0a87e5b --- # Walkthrough: Implementing Futures @@ -42,7 +41,7 @@ To implement futures, this topic defines the `async_future` class. The `async_fu ### Description -The following example shows the complete `async_future` class and an example of its usage. The `wmain` function creates a std::[vector](../../standard-library/vector-class.md) object that contains 10,000 random integer values. It then uses `async_future` objects to find the smallest and largest values that are contained in the `vector` object. +The following example shows the complete `async_future` class and an example of its usage. The `wmain` function creates a [std::vector](../../standard-library/vector-class.md) object that contains 10,000 random integer values. It then uses `async_future` objects to find the smallest and largest values that are contained in the `vector` object. ### Code diff --git a/docs/parallel/multithreading-and-locales.md b/docs/parallel/multithreading-and-locales.md index 9c370107b00..2cdb9b4db2f 100644 --- a/docs/parallel/multithreading-and-locales.md +++ b/docs/parallel/multithreading-and-locales.md @@ -4,6 +4,7 @@ title: "Multithreading and Locales" ms.date: "11/04/2016" helpviewer_keywords: ["locales [C++], multithreading", "multithreading [C++], locales", "threading [C++], locales", "per-thread locale"] ms.assetid: d6fb159a-eaca-4130-a51a-f95d62f71485 +ms.topic: concept-article --- # Multithreading and Locales @@ -13,20 +14,20 @@ Both the C Runtime Library and the C++ Standard Library provide support for chan With the C Runtime Library, you can create multithreaded applications using the `_beginthread` and `_beginthreadex` functions. This topic only covers multithreaded applications created using these functions. For more information, see [_beginthread, _beginthreadex](../c-runtime-library/reference/beginthread-beginthreadex.md). -To change the locale using the C Runtime Library, use the [setlocale](../preprocessor/setlocale.md) function. In previous versions of Visual C++, this function would always modify the locale throughout the entire application. There is now support for setting the locale on a per-thread basis. This is done using the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function. To specify that [setlocale](../preprocessor/setlocale.md) should only change the locale in the current thread, call `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)` in that thread. Conversely, calling `_configthreadlocale(_DISABLE_PER_THREAD_LOCALE)` will cause that thread to use the global locale, and any call to [setlocale](../preprocessor/setlocale.md) in that thread will change the locale in all threads that have not explicitly enabled per-thread locale. +To change the locale using the C Runtime Library, use the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function. In previous versions of Visual C++, this function would always modify the locale throughout the entire application. There is now support for setting the locale on a per-thread basis. This is done using the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function. To specify that [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) should only change the locale in the current thread, call `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)` in that thread. Conversely, calling `_configthreadlocale(_DISABLE_PER_THREAD_LOCALE)` will cause that thread to use the global locale, and any call to [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) in that thread will change the locale in all threads that have not explicitly enabled per-thread locale. To change the locale using the C++ Runtime Library, use the [locale Class](../standard-library/locale-class.md). By calling the [locale::global](../standard-library/locale-class.md#global) method, you change the locale in every thread that has not explicitly enabled per-thread locale. To change the locale in a single thread or portion of an application, simply create an instance of a `locale` object in that thread or portion of code. > [!NOTE] -> Calling [locale::global](../standard-library/locale-class.md#global) changes the locale for both the C++ Standard Library and the C Runtime Library. However, calling [setlocale](../preprocessor/setlocale.md) only changes the locale for the C Runtime Library; the C++ Standard Library is not affected. +> Calling [locale::global](../standard-library/locale-class.md#global) changes the locale for both the C++ Standard Library and the C Runtime Library. However, calling [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) only changes the locale for the C Runtime Library; the C++ Standard Library is not affected. -The following examples show how to use the [setlocale](../preprocessor/setlocale.md) function, the [locale Class](../standard-library/locale-class.md), and the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function to change the locale of an application in several different scenarios. +The following examples show how to use the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function, the [locale Class](../standard-library/locale-class.md), and the [_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md) function to change the locale of an application in several different scenarios. ## Example: Change locale with per-thread locale enabled -In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread A then proceeds to change the locale using the [setlocale](../preprocessor/setlocale.md) function of the C Runtime Library. +In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread A then proceeds to change the locale using the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function of the C Runtime Library. -Since Thread A has per-thread locale enabled, only the C Runtime Library functions in Thread A start using the "french" locale. The C Runtime Library functions in Thread B and in the main thread continue to use the "C" locale. Also, since [setlocale](../preprocessor/setlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. +Since Thread A has per-thread locale enabled, only the C Runtime Library functions in Thread A start using the "french" locale. The C Runtime Library functions in Thread B and in the main thread continue to use the "C" locale. Also, since [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. ```cpp // multithread_locale_1.cpp @@ -222,9 +223,9 @@ unsigned __stdcall RunThreadB(void *params) ## Example: Change locale without per-thread locale enabled -In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread B then proceeds to change the locale using the [setlocale](../preprocessor/setlocale.md) function of the C Runtime Library. +In this example, the main thread spawns two child threads. The first thread, Thread A, enables per-thread locale by calling `_configthreadlocale(_ENABLE_PER_THREAD_LOCALE)`. The second thread, Thread B, as well as the main thread, do not enable per-thread locale. Thread B then proceeds to change the locale using the [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) function of the C Runtime Library. -Since Thread B does not have per-thread locale enabled, the C Runtime Library functions in Thread B and in the main thread start using the "french" locale. The C Runtime Library functions in Thread A continue to use the "C" locale because Thread A has per-thread locale enabled. Also, since [setlocale](../preprocessor/setlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. +Since Thread B does not have per-thread locale enabled, the C Runtime Library functions in Thread B and in the main thread start using the "french" locale. The C Runtime Library functions in Thread A continue to use the "C" locale because Thread A has per-thread locale enabled. Also, since [setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md) does not affect the C++ Standard Library locale, all C++ Standard Library objects continue to use the "C" locale. ```cpp // multithread_locale_3.cpp @@ -431,7 +432,7 @@ unsigned __stdcall RunThreadB(void *params) [Multithreading Support for Older Code (Visual C++)](multithreading-support-for-older-code-visual-cpp.md)
[_beginthread, _beginthreadex](../c-runtime-library/reference/beginthread-beginthreadex.md)
[_configthreadlocale](../c-runtime-library/reference/configthreadlocale.md)
-[setlocale](../preprocessor/setlocale.md)
+[setlocale](../c-runtime-library/reference/setlocale-wsetlocale.md)
[Internationalization](../c-runtime-library/internationalization.md)
[Locale](../c-runtime-library/locale.md)
[\](../standard-library/clocale.md)
diff --git a/docs/parallel/multithreading-creating-user-interface-threads.md b/docs/parallel/multithreading-creating-user-interface-threads.md index fa1abe4c069..093e592a9ab 100644 --- a/docs/parallel/multithreading-creating-user-interface-threads.md +++ b/docs/parallel/multithreading-creating-user-interface-threads.md @@ -5,6 +5,7 @@ ms.date: "08/27/2018" f1_keywords: ["CREATE_SUSPENDED", "SECURITY_ATTRIBUTES"] helpviewer_keywords: ["multithreading [C++], user interface threads", "threading [C++], creating threads", "threading [C++], user interface threads", "user interface threads [C++]", "threading [MFC], user interface threads"] ms.assetid: 446925c1-db59-46ea-ae5b-d5ae5d5b91d8 +ms.topic: how-to --- # Multithreading: Creating MFC User-Interface Threads diff --git a/docs/parallel/multithreading-creating-worker-threads.md b/docs/parallel/multithreading-creating-worker-threads.md index c967eda95e8..00d5e3f3426 100644 --- a/docs/parallel/multithreading-creating-worker-threads.md +++ b/docs/parallel/multithreading-creating-worker-threads.md @@ -4,6 +4,7 @@ title: "Multithreading: Creating Worker Threads in MFC" ms.date: "11/04/2016" helpviewer_keywords: ["multithreading [C++], worker threads", "background tasks [C++]", "threading [C++], worker threads", "worker threads [C++]", "threading [C++], creating threads", "threading [MFC], worker threads", "threading [C++], user input not required"] ms.assetid: 670adbfe-041c-4450-a3ed-be14aab15234 +ms.topic: how-to --- # Multithreading: Creating Worker Threads in MFC diff --git a/docs/parallel/multithreading-how-to-use-the-synchronization-classes.md b/docs/parallel/multithreading-how-to-use-the-synchronization-classes.md index af8f3e3a13e..ffbc5183f2a 100644 --- a/docs/parallel/multithreading-how-to-use-the-synchronization-classes.md +++ b/docs/parallel/multithreading-how-to-use-the-synchronization-classes.md @@ -4,6 +4,7 @@ title: "Multithreading: How to Use the MFC Synchronization Classes" ms.date: "08/27/2018" helpviewer_keywords: ["MFC [C++], multithreading", "threading [MFC], synchronization classes", "resources [C++], multithreading", "thread-safe classes [C++]", "synchronization classes [C++]", "synchronization [C++], multithreading", "threading [MFC], thread-safe class design", "threading [C++], synchronization", "multithreading [C++], synchronization classes", "threading [C++], thread-safe class design"] ms.assetid: f266d4c6-0454-4bda-9758-26157ef74cc5 +ms.topic: how-to --- # Multithreading: How to Use the MFC Synchronization Classes diff --git a/docs/parallel/multithreading-programming-tips.md b/docs/parallel/multithreading-programming-tips.md index 1017d68873a..8048068fc7c 100644 --- a/docs/parallel/multithreading-programming-tips.md +++ b/docs/parallel/multithreading-programming-tips.md @@ -4,6 +4,7 @@ title: "Multithreading: MFC Programming Tips" ms.date: "08/27/2018" helpviewer_keywords: ["multithreading [C++], programming tips", "handle maps [C++]", "access control [C++], multithreading", "objects [C++], multiple threads and", "non-MFC threads [C++]", "threading [MFC], programming tips", "critical sections [C++]", "synchronization [C++], multithreading", "programming [C++], multithreaded", "communications [C++], between threads", "threading [C++], best practices", "troubleshooting [C++], multithreading", "Windows handle maps [C++]"] ms.assetid: ad14cc70-c91c-4c24-942f-13a75e58bf8a +ms.topic: concept-article --- # Multithreading: MFC Programming Tips diff --git a/docs/parallel/multithreading-support-for-older-code-visual-cpp.md b/docs/parallel/multithreading-support-for-older-code-visual-cpp.md index 43071cb689d..b2c9fea8356 100644 --- a/docs/parallel/multithreading-support-for-older-code-visual-cpp.md +++ b/docs/parallel/multithreading-support-for-older-code-visual-cpp.md @@ -4,6 +4,7 @@ title: "Multithreading Support for Older Code (Visual C++)" ms.date: "08/27/2018" helpviewer_keywords: ["threading [C++]", "multiple threads", "concurrent programming [C++]", "programming [C++], multithreaded", "multithreading [C++], about multithreading", "multiple concurrent threads", "multithreading [C++]"] ms.assetid: 24425b1f-5031-4c6b-aac7-017115a40e7c +ms.topic: concept-article --- # Multithreading Support for Older Code (Visual C++) diff --git a/docs/parallel/multithreading-terminating-threads.md b/docs/parallel/multithreading-terminating-threads.md index 5f530d673ad..64fb21623d0 100644 --- a/docs/parallel/multithreading-terminating-threads.md +++ b/docs/parallel/multithreading-terminating-threads.md @@ -4,6 +4,7 @@ title: "Multithreading: Terminating Threads in MFC" ms.date: "08/27/2018" helpviewer_keywords: ["premature thread termination", "starting threads", "threading [MFC], terminating threads", "multithreading [C++], terminating threads", "threading [C++], stopping threads", "terminating threads", "stopping threads", "AfxEndThread method"] ms.assetid: 4c0a8c6d-c02f-456d-bd02-0a8c8d006ecb +ms.topic: how-to --- # Multithreading: Terminating Threads in MFC diff --git a/docs/parallel/multithreading-when-to-use-the-synchronization-classes.md b/docs/parallel/multithreading-when-to-use-the-synchronization-classes.md index 7fad93900e2..0a7c3a15d87 100644 --- a/docs/parallel/multithreading-when-to-use-the-synchronization-classes.md +++ b/docs/parallel/multithreading-when-to-use-the-synchronization-classes.md @@ -4,6 +4,7 @@ title: "Multithreading: When to Use the MFC Synchronization Classes" ms.date: "08/27/2018" helpviewer_keywords: ["threading [MFC], synchronization classes", "resources [C++], multithreading", "synchronization classes [C++]", "synchronization [C++], multithreading", "controlled resource access [C++]", "synchronization access classes [C++]", "threading [C++], synchronization", "multithreading [C++], synchronization classes"] ms.assetid: 4914f54e-68ac-438f-93c9-c013455a657e +ms.topic: how-to --- # Multithreading: When to Use the MFC Synchronization Classes diff --git a/docs/parallel/multithreading-with-c-and-win32.md b/docs/parallel/multithreading-with-c-and-win32.md index 6381e9ba552..e3f2f9335b2 100644 --- a/docs/parallel/multithreading-with-c-and-win32.md +++ b/docs/parallel/multithreading-with-c-and-win32.md @@ -4,6 +4,7 @@ title: "Multithreading with C and Win32" ms.date: "08/09/2019" helpviewer_keywords: ["Windows API [C++], multithreading", "multithreading [C++], C and Win32", "Visual C, multithreading", "Win32 applications [C++], multithreading", "threading [C++], C and Win32", "Win32 [C++], multithreading", "threading [C]"] ms.assetid: 67cdc99e-1ad9-452b-a042-ed246b70040e +ms.topic: concept-article --- # Multithreading with C and Win32 diff --git a/docs/parallel/multithreading-with-cpp-and-mfc.md b/docs/parallel/multithreading-with-cpp-and-mfc.md index 9421b44d6b2..286a5155131 100644 --- a/docs/parallel/multithreading-with-cpp-and-mfc.md +++ b/docs/parallel/multithreading-with-cpp-and-mfc.md @@ -3,10 +3,13 @@ description: "Learn more about: Multithreading with C++ and MFC" title: "Multithreading with C++ and MFC" ms.date: "08/27/2018" helpviewer_keywords: ["MFC [C++], multithreading", "threading [C++], MFC", "worker threads [C++]", "synchronization classes [C++]", "synchronization [C++], multithreading", "threading [MFC], about threading", "CWinThread class, purpose of", "multithreading [C++], MFC", "threading [MFC]", "user interface threads [C++]"] -ms.assetid: 979605f8-3988-44b5-ac9c-b8cce7fcce14 +ms.topic: concept-article --- # Multithreading with C++ and MFC +>[!NOTE] +> The Microsoft Foundation Classes (MFC) library continues to be supported. However, we're no longer adding features or updating the documentation. + The Microsoft Foundation Class (MFC) library provides support for multithreaded applications. This topic describes processes and threads and the MFC approach to multithreading. A process is an executing instance of an application. For example, when you double-click the Notepad icon, you start a process that runs Notepad. diff --git a/docs/parallel/openmp/1-introduction.md b/docs/parallel/openmp/1-introduction.md index 577e1556d99..3e819472bde 100644 --- a/docs/parallel/openmp/1-introduction.md +++ b/docs/parallel/openmp/1-introduction.md @@ -3,6 +3,7 @@ description: "Learn more about: 1. Introduction" title: "1. Introduction" ms.date: "01/16/2019" ms.assetid: c42e72bc-0e31-4b1c-b670-cd82673c0c5a +ms.topic: concept-article --- # 1. Introduction diff --git a/docs/parallel/openmp/2-directives.md b/docs/parallel/openmp/2-directives.md index b949f5b496f..6ff80f4fbb6 100644 --- a/docs/parallel/openmp/2-directives.md +++ b/docs/parallel/openmp/2-directives.md @@ -798,7 +798,6 @@ The restrictions to the `reduction` clause are as follows: The `copyin` clause provides a mechanism to assign the same value to `threadprivate` variables for each thread in the team executing the parallel region. For each variable specified in a `copyin` clause, the value of the variable in the master thread of the team is copied, as if by assignment, to the thread-private copies at the beginning of the parallel region. The syntax of the `copyin` clause is as follows: ```cpp - copyin( variable-list ) @@ -817,7 +816,6 @@ The `copyprivate` clause provides a mechanism to use a private variable to broad The syntax of the `copyprivate` clause is as follows: ```cpp - copyprivate( variable-list ) diff --git a/docs/parallel/openmp/a-examples.md b/docs/parallel/openmp/a-examples.md index dabdf0bc972..43499f5d100 100644 --- a/docs/parallel/openmp/a-examples.md +++ b/docs/parallel/openmp/a-examples.md @@ -1,8 +1,7 @@ --- -description: "Learn more about: A. Examples" title: "A. Examples" -ms.date: "01/18/2019" -ms.assetid: c0f6192f-a205-449b-b84c-cb30dbcc8b8f +description: "Learn more about: A. Examples" +ms.date: 01/18/2019 --- # A. Examples @@ -854,7 +853,7 @@ The following example demonstrates the [num_threads](2-directives.md#23-parallel ```cpp #include -main() +int main() { omp_set_dynamic(1); ... 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 6221091b690..3e5249b640a 100644 --- a/docs/parallel/openmp/c-openmp-c-and-cpp-grammar.md +++ b/docs/parallel/openmp/c-openmp-c-and-cpp-grammar.md @@ -1,15 +1,13 @@ --- -description: "Learn more about: C. OpenMP C and C++ grammar" title: "C. OpenMP C and C++ grammar" -ms.date: "01/16/2019" -ms.assetid: 97a878ce-1533-47f7-a134-66fcbff48524 +description: "Learn more about: C. OpenMP C and C++ grammar" +ms.date: 01/16/2019 --- # C. OpenMP C and C++ grammar -[C.1 Notation](#c1-notation)
-[C.2 Rules](#c2-rules) +Learn about the grammar rules and syntax extensions in C and C++ for OpenMP, a parallel programming framework. -## C.1 Notation +## C.1 notation The grammar rules consist of the name for a non-terminal, followed by a colon, followed by replacement alternatives on separate lines. @@ -18,214 +16,214 @@ The syntactic expression termopt indicates that the term is optional The syntactic expression *term*optseq is equivalent to *term-seq*opt with the following additional rules: *term-seq*: -    *term*
-    *term-seq* *term*
-    *term-seq* `,` *term* + *term*\ + *term-seq* *term*\ + *term-seq* `,` *term* -## C.2 Rules +## C.2 rules The notation is described in section 6.1 of the C standard. This grammar appendix shows the extensions to the base language grammar for the OpenMP C and C++ directives. **/\* in C++ (ISO/IEC 14882:1998) \*/** -*statement-seq*:
-    *statement*
-    *openmp-directive*
-    *statement-seq statement*
-    *statement-seq openmp-directive* +*statement-seq*:\ + *statement*\ + *openmp-directive*\ + *statement-seq statement*\ + *statement-seq openmp-directive* **/\* in C90 (ISO/IEC 9899:1990) \*/** -*statement-list*:
-    *statement*
-    *openmp-directive*
-    *statement-list statement*
-    *statement-list openmp-directive* +*statement-list*:\ + *statement*\ + *openmp-directive*\ + *statement-list statement*\ + *statement-list openmp-directive* **/\* in C99 (ISO/IEC 9899:1999) \*/** -*block-item*:
-    *declaration*
-    *statement*
-    *openmp-directive* +*block-item*:\ + *declaration*\ + *statement*\ + *openmp-directive* **/\* standard statements \*/** -*statement*:
-    *openmp-construct* +*statement*:\ + *openmp-construct* -*openmp-construct*:
-    *parallel-construct*
-    *for-construct*
-    *sections-construct*
-    *single-construct*
-    *parallel-for-construct*
-    *parallel-sections-construct*
-    *master-construct*
-    *critical-construct*
-    *atomic-construct*
-    *ordered-construct* +*openmp-construct*:\ + *parallel-construct*\ + *for-construct*\ + *sections-construct*\ + *single-construct*\ + *parallel-for-construct*\ + *parallel-sections-construct*\ + *master-construct*\ + *critical-construct*\ + *atomic-construct*\ + *ordered-construct* -*openmp-directive*:
-    *barrier-directive*
-    *flush-directive* +*openmp-directive*:\ + *barrier-directive*\ + *flush-directive* -*structured-block*:
-    *statement* +*structured-block*:\ + *statement* -*parallel-construct*:
-    *parallel-directive structured-block* +*parallel-construct*:\ + *parallel-directive structured-block* -*parallel-directive*:
-     `# pragma omp parallel` *parallel-clause*optseq *new-line* +*parallel-directive*:\ +  `# pragma omp parallel` *parallel-clause*optseq *new-line* -*parallel-clause*:
-    *unique-parallel-clause*
-    *data-clause* +*parallel-clause*:\ + *unique-parallel-clause*\ + *data-clause* -*unique-parallel-clause*:
-     `if (` *expression* `)`
-     `num_threads (` *expression* `)` +*unique-parallel-clause*:\ +  `if (` *expression* `)`\ +  `num_threads (` *expression* `)` -*for-construct*:
-    *for-directive iteration-statement* +*for-construct*:\ + *for-directive iteration-statement* -*for-directive*:
-     `# pragma omp for` *for-clause*optseq *new-line* +*for-directive*:\ +  `# pragma omp for` *for-clause*optseq *new-line* -*for-clause*:
-    *unique-for-clause*
-    *data-clause*
-     `nowait` +*for-clause*:\ + *unique-for-clause*\ + *data-clause*\ +  `nowait` -*unique-for-clause*:
-     `ordered`
-     `schedule (` *schedule-kind* `)`
-     `schedule (` *schedule-kind* `,` *expression* `)` +*unique-for-clause*:\ +  `ordered`\ +  `schedule (` *schedule-kind* `)`\ +  `schedule (` *schedule-kind* `,` *expression* `)` -*schedule-kind*:
-     `static`
-     `dynamic`
-     `guided`
-     `runtime` +*schedule-kind*:\ +  `static`\ +  `dynamic`\ +  `guided`\ +  `runtime` -*sections-construct*:
-    *sections-directive section-scope* +*sections-construct*:\ + *sections-directive section-scope* -*sections-directive*:
-     `# pragma omp sections` *sections-clause*optseq *new-line* +*sections-directive*:\ +  `# pragma omp sections` *sections-clause*optseq *new-line* -*sections-clause*:
-    *data-clause*
-     `nowait` +*sections-clause*:\ + *data-clause*\ +  `nowait` -*section-scope*:
-    *{ section-sequence }* +*section-scope*:\ + *{ section-sequence }* -*section-sequence*:
-    *section-directive*opt *structured-block*
-    *section-sequence section-directive structured-block* +*section-sequence*:\ + *section-directive*opt *structured-block*\ + *section-sequence section-directive structured-block* -*section-directive*:
-     `# pragma omp section` *new-line* +*section-directive*:\ +  `# pragma omp section` *new-line* -*single-construct*:
-    *single-directive structured-block* +*single-construct*:\ + *single-directive structured-block* -*single-directive*:
-     `# pragma omp single` *single-clause*optseq *new-line* +*single-directive*:\ +  `# pragma omp single` *single-clause*optseq *new-line* -*single-clause*:
-    *data-clause*
-     `nowait` +*single-clause*:\ + *data-clause*\ +  `nowait` -*parallel-for-construct*:
-    *parallel-for-directive iteration-statement* +*parallel-for-construct*:\ + *parallel-for-directive iteration-statement* -*parallel-for-directive*:
-     `# pragma omp parallel for` *parallel-for-clause*optseq *new-line* +*parallel-for-directive*:\ +  `# pragma omp parallel for` *parallel-for-clause*optseq *new-line* -*parallel-for-clause*:
-    *unique-parallel-clause*
-    *unique-for-clause*
-    *data-clause* +*parallel-for-clause*:\ + *unique-parallel-clause*\ + *unique-for-clause*\ + *data-clause* -*parallel-sections-construct*:
-    *parallel-sections-directive section-scope* +*parallel-sections-construct*:\ + *parallel-sections-directive section-scope* -*parallel-sections-directive*:
-     `# pragma omp parallel sections` *parallel-sections-clause*optseq *new-line* +*parallel-sections-directive*:\ +  `# pragma omp parallel sections` *parallel-sections-clause*optseq *new-line* -*parallel-sections-clause*:
-    *unique-parallel-clause*
-    *data-clause* +*parallel-sections-clause*:\ + *unique-parallel-clause*\ + *data-clause* -*master-construct*:
-    *master-directive structured-block* +*master-construct*:\ + *master-directive structured-block* -*master-directive*:
-     `# pragma omp master` *new-line* +*master-directive*:\ +  `# pragma omp master` *new-line* -*critical-construct*:
-    *critical-directive structured-block* +*critical-construct*:\ + *critical-directive structured-block* -*critical-directive*:
-     `# pragma omp critical` *region-phrase*opt *new-line* +*critical-directive*:\ +  `# pragma omp critical` *region-phrase*opt *new-line* -*region-phrase*:
-    *(identifier)* +*region-phrase*:\ + *(identifier)* -*barrier-directive*:
-     `# pragma omp barrier` *new-line* +*barrier-directive*:\ +  `# pragma omp barrier` *new-line* -*atomic-construct*:
-    *atomic-directive expression-statement* +*atomic-construct*:\ + *atomic-directive expression-statement* -*atomic-directive*:
-     `# pragma omp atomic` *new-line* +*atomic-directive*:\ +  `# pragma omp atomic` *new-line* -*flush-directive*:
-     `# pragma omp flush` *flush-vars*opt *new-line* +*flush-directive*:\ +  `# pragma omp flush` *flush-vars*opt *new-line* -*flush-vars*:
-    *(variable-list)* +*flush-vars*:\ + *(variable-list)* -*ordered-construct*:
-    *ordered-directive structured-block* +*ordered-construct*:\ + *ordered-directive structured-block* -*ordered-directive*:
-     `# pragma omp ordered` *new-line* +*ordered-directive*:\ +  `# pragma omp ordered` *new-line* **/\* standard declarations \*/** -*declaration*:
-    *threadprivate-directive* +*declaration*:\ + *threadprivate-directive* -*threadprivate-directive*:
-     `# pragma omp threadprivate (` *variable-list* `)` *new-line* +*threadprivate-directive*:\ +  `# pragma omp threadprivate (` *variable-list* `)` *new-line* -*data-clause*:
-     `private (` *variable-list* `)`
-     `copyprivate (` *variable-list* `)`
-     `firstprivate (` *variable-list* `)`
-     `lastprivate (` *variable-list* `)`
-     `shared (` *variable-list* `)`
-     `default ( shared )`
-     `default ( none )`
-     `reduction (` *reduction-operator* `:` *variable-list* `)`
-     `copyin (` *variable-list* `)` +*data-clause*:\ +  `private (` *variable-list* `)`\ +  `copyprivate (` *variable-list* `)`\ +  `firstprivate (` *variable-list* `)`\ +  `lastprivate (` *variable-list* `)`\ +  `shared (` *variable-list* `)`\ +  `default ( shared )`\ +  `default ( none )`\ +  `reduction (` *reduction-operator* `:` *variable-list* `)`\ +  `copyin (` *variable-list* `)` -*reduction-operator*:
-    One of: `+ \* - & ^ | && ||` +*reduction-operator*:\ + One of: `+ \* - & ^ | && ||` **/\* in C \*/** -*variable-list*:
-    *identifier*
-    *variable-list* `,` *identifier* +*variable-list*:\ + *identifier*\ + *variable-list* `,` *identifier* **/\* in C++ \*/** -*variable-list*:
-    *id-expression*
-    *variable-list* `,` *id-expression* +*variable-list*:\ + *id-expression*\ + *variable-list* `,` *id-expression* diff --git a/docs/parallel/openmp/openmp-simd.md b/docs/parallel/openmp/openmp-simd.md index 23675f53b61..e263b9427e1 100644 --- a/docs/parallel/openmp/openmp-simd.md +++ b/docs/parallel/openmp/openmp-simd.md @@ -17,7 +17,7 @@ For more information, see [SIMD Extension to C++ OpenMP in Visual Studio](https: ## OpenMP SIMD in Visual C++ -OpenMP SIMD, introduced in the OpenMP 4.0 standard, targets making vector-friendly loops. By using the `simd` directive before a loop, the compiler can ignore vector dependencies, make the loop as vector-friendly as possible, and respect the users’ intention to have multiple loop iterations executed simultaneously. +OpenMP SIMD, introduced in the OpenMP 4.0 standard, targets making vector-friendly loops. By using the `simd` directive before a loop, the compiler can ignore vector dependencies, make the loop as vector-friendly as possible, and respect the users' intention to have multiple loop iterations executed simultaneously. ```c #pragma omp simd diff --git a/docs/parallel/openmp/reference/openmp-directives.md b/docs/parallel/openmp/reference/openmp-directives.md index 2e841d21386..ef1fd1944d8 100644 --- a/docs/parallel/openmp/reference/openmp-directives.md +++ b/docs/parallel/openmp/reference/openmp-directives.md @@ -28,7 +28,7 @@ For main thread and synchronization: |[master](#master)|Specifies that only the main thread should execute a section of the program.| |[critical](#critical)|Specifies that code is only executed on one thread at a time.| |[barrier](#barrier)|Synchronizes all threads in a team; all threads pause at the barrier, until all threads execute the barrier.| -|[atomic](#atomic)|Specifies that a memory location that will be updated atomically.| +|[atomic](#atomic)|Specifies that a memory location will be updated atomically.| |[flush](#flush-openmp)|Specifies that all threads have the same view of memory for all shared objects.| |[ordered](#ordered-openmp-directives)|Specifies that code under a parallelized `for` loop should be executed like a sequential loop.| diff --git a/docs/parallel/parallel-programming-in-visual-cpp.md b/docs/parallel/parallel-programming-in-visual-cpp.md index 9a0a35d7c76..2aec9538eb0 100644 --- a/docs/parallel/parallel-programming-in-visual-cpp.md +++ b/docs/parallel/parallel-programming-in-visual-cpp.md @@ -1,8 +1,7 @@ --- description: "Learn more about: Parallel Programming in Visual C++" title: "Parallel Programming in Visual C++" -ms.date: "11/04/2016" -ms.assetid: f5c28ab6-a1d9-492f-b207-05e8aee73e96 +ms.date: 03/24/2026 ms.topic: "overview" ms.custom: intro-overview --- @@ -12,11 +11,23 @@ Visual C++ provides the following technologies to help you create multi-threaded ## Related Articles +::: moniker range="<=msvc-160" |Title|Description| |-----------|-----------------| |[Auto-Parallelization and Auto-Vectorization](auto-parallelization-and-auto-vectorization.md)|Compiler optimizations that speed up code.| |[Concurrency Runtime](concrt/concurrency-runtime.md)|Classes that simplify the writing of programs that use data parallelism or task parallelism.| -|[C++ AMP (C++ Accelerated Massive Parallelism)](amp/cpp-amp-cpp-accelerated-massive-parallelism.md)|Classes that enable the use of modern graphics processors for general purpose programming.| |[Multithreading Support for Older Code (Visual C++)](multithreading-support-for-older-code-visual-cpp.md)|Older technologies that may be useful in older applications. For new apps, use the Concurrency Runtime or C++ AMP.| |[OpenMP](openmp/openmp-in-visual-cpp.md)|The Microsoft implementation of the OpenMP API.| |[C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md)|This section of the documentation contains information about most of the features of Visual C++.| +|[C++ AMP (C++ Accelerated Massive Parallelism)](amp/cpp-amp-cpp-accelerated-massive-parallelism.md)|Classes that enable the use of modern graphics processors for general purpose programming.| +:::moniker-end +::: moniker range=">msvc-160" +|Title|Description| +|-----------|-----------------| +|[Auto-Parallelization and Auto-Vectorization](auto-parallelization-and-auto-vectorization.md)|Compiler optimizations that speed up code.| +|[Concurrency Runtime](concrt/concurrency-runtime.md)|Classes that simplify the writing of programs that use data parallelism or task parallelism.| +|[Multithreading Support for Older Code (Visual C++)](multithreading-support-for-older-code-visual-cpp.md)|Older technologies that may be useful in older applications. For new apps, use the Concurrency Runtime.| +|[OpenMP](openmp/openmp-in-visual-cpp.md)|The Microsoft implementation of the OpenMP API.| +|[C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md)|This section of the documentation contains information about most of the features of Visual C++.| +:::moniker-end + diff --git a/docs/parallel/sample-multithread-c-program.md b/docs/parallel/sample-multithread-c-program.md index f76e104bd1d..7be0bc3381a 100644 --- a/docs/parallel/sample-multithread-c-program.md +++ b/docs/parallel/sample-multithread-c-program.md @@ -2,6 +2,7 @@ description: "Learn more about: Sample Multithread C Program" title: "Sample Multithread C Program" ms.date: 04/07/2022 +ms.topic: how-to --- # Sample Multithread C Program diff --git a/docs/parallel/thread-local-storage-tls.md b/docs/parallel/thread-local-storage-tls.md index 42ccaa72774..fbcd5b93e33 100644 --- a/docs/parallel/thread-local-storage-tls.md +++ b/docs/parallel/thread-local-storage-tls.md @@ -4,6 +4,7 @@ title: "Thread Local Storage (TLS)" ms.date: "08/09/2019" helpviewer_keywords: ["multithreading [C++], Thread Local Storage", "TLS [C++]", "threading [C++], Thread Local Storage", "storing thread-specific data", "thread attribute", "Thread Local Storage [C++]"] ms.assetid: 80801907-d792-45ca-b776-df0cf2e9f197 +ms.topic: how-to --- # Thread Local Storage (TLS) diff --git a/docs/parallel/toc.yml b/docs/parallel/toc.yml index d8a0ae92833..0543f1e5c49 100644 --- a/docs/parallel/toc.yml +++ b/docs/parallel/toc.yml @@ -1,659 +1,495 @@ -items: +items: - name: Parallel programming in MSVC href: ../parallel/parallel-programming-in-visual-cpp.md - name: Auto-parallelization and auto-vectorization href: ../parallel/auto-parallelization-and-auto-vectorization.md -- name: C++ Accelerated Massive Parallelism (AMP) - expanded: false - items: - - name: C++ AMP (C++ Accelerated Massive Parallelism) - href: ../parallel/amp/cpp-amp-cpp-accelerated-massive-parallelism.md - - name: C++ AMP overview - href: ../parallel/amp/cpp-amp-overview.md - - name: Using tiles - href: ../parallel/amp/using-tiles.md - - name: Using C++ AMP in UWP apps - href: ../parallel/amp/using-cpp-amp-in-windows-store-apps.md - - name: "Walkthrough: Matrix multiplication" - href: ../parallel/amp/walkthrough-matrix-multiplication.md - - name: "Walkthrough: Debugging a C++ AMP application" - href: ../parallel/amp/walkthrough-debugging-a-cpp-amp-application.md - - name: Using lambdas, function objects, and restricted functions - href: ../parallel/amp/using-lambdas-function-objects-and-restricted-functions.md - - name: Graphics (C++ AMP) - href: ../parallel/amp/graphics-cpp-amp.md - - name: Using accelerator and accelerator_view objects - href: ../parallel/amp/using-accelerator-and-accelerator-view-objects.md - - name: Reference (C++ AMP) - expanded: false - items: - - name: Reference (C++ AMP) - href: ../parallel/amp/reference/reference-cpp-amp.md - - name: Concurrency namespace (C++ AMP) - expanded: false - items: - - name: Concurrency namespace (C++ AMP) - href: ../parallel/amp/reference/concurrency-namespace-cpp-amp.md - - name: Concurrency namespace functions (AMP) - href: ../parallel/amp/reference/concurrency-namespace-functions-amp.md - - name: Concurrency namespace enums (AMP) - href: ../parallel/amp/reference/concurrency-namespace-enums-amp.md - - name: Concurrency namespace operators (AMP) - href: ../parallel/amp/reference/concurrency-namespace-operators-amp.md - - name: Concurrency namespace constants (AMP) - href: ../parallel/amp/reference/concurrency-namespace-constants-amp.md - - name: accelerator class - href: ../parallel/amp/reference/accelerator-class.md - - name: accelerator_view class - href: ../parallel/amp/reference/accelerator-view-class.md - - name: accelerator_view_removed class - href: ../parallel/amp/reference/accelerator-view-removed-class.md - - name: array class - href: ../parallel/amp/reference/array-class.md - - name: array_view class - href: ../parallel/amp/reference/array-view-class.md - - name: completion_future class - href: ../parallel/amp/reference/completion-future-class.md - - name: extent class (C++ AMP) - href: ../parallel/amp/reference/extent-class.md - - name: index class - href: ../parallel/amp/reference/index-class.md - - name: invalid_compute_domain class - href: ../parallel/amp/reference/invalid-compute-domain-class.md - - name: out_of_memory class - href: ../parallel/amp/reference/out-of-memory-class.md - - name: runtime_exception class - href: ../parallel/amp/reference/runtime-exception-class.md - - name: tile_barrier class - href: ../parallel/amp/reference/tile-barrier-class.md - - name: tiled_extent class - href: ../parallel/amp/reference/tiled-extent-class.md - - name: tiled_index class - href: ../parallel/amp/reference/tiled-index-class.md - - name: uninitialized_object class - href: ../parallel/amp/reference/uninitialized-object-class.md - - name: unsupported_feature class - href: ../parallel/amp/reference/unsupported-feature-class.md - - name: "Concurrency::direct3d Namespace" - expanded: false - items: - - name: "Concurrency::direct3d Namespace" - href: ../parallel/amp/reference/concurrency-direct3d-namespace.md - - name: "Concurrency::direct3d namespace functions (AMP)" - href: ../parallel/amp/reference/concurrency-direct3d-namespace-functions-amp.md - - name: adopt_d3d_access_lock_t Structure - href: ../parallel/amp/reference/adopt-d3d-access-lock-t-structure.md - - name: scoped_d3d_access_lock class - href: ../parallel/amp/reference/scoped-d3d-access-lock-class.md - - name: "Concurrency::fast_math Namespace" - expanded: false - items: - - name: "Concurrency::fast_math Namespace" - href: ../parallel/amp/reference/concurrency-fast-math-namespace.md - - name: "Concurrency::fast_math namespace functions" - href: ../parallel/amp/reference/concurrency-fast-math-namespace-functions.md - - name: "Concurrency::graphics Namespace" - expanded: false - items: - - name: "Concurrency::graphics Namespace" - href: ../parallel/amp/reference/concurrency-graphics-namespace.md - - name: "Concurrency::graphics::direct3d namespace" - expanded: false - items: - - name: "Concurrency::graphics::direct3d namespace" - href: ../parallel/amp/reference/concurrency-graphics-direct3d-namespace.md - - name: "Concurrency::graphics::direct3d namespace functions" - href: ../parallel/amp/reference/concurrency-graphics-direct3d-namespace-functions.md - - name: "Concurrency::graphics namespace functions" - href: ../parallel/amp/reference/concurrency-graphics-namespace-functions.md - - name: "Concurrency::graphics namespace enums" - href: ../parallel/amp/reference/concurrency-graphics-namespace-enums.md - - name: double_2 class - href: ../parallel/amp/reference/double-2-class.md - - name: double_3 class - href: ../parallel/amp/reference/double-3-class.md - - name: double_4 class - href: ../parallel/amp/reference/double-4-class.md - - name: float_2 class - href: ../parallel/amp/reference/float-2-class.md - - name: float_3 class - href: ../parallel/amp/reference/float-3-class.md - - name: float_4 class - href: ../parallel/amp/reference/float-4-class.md - - name: int_2 class - href: ../parallel/amp/reference/int-2-class.md - - name: int_3 class - href: ../parallel/amp/reference/int-3-class.md - - name: int_4 class - href: ../parallel/amp/reference/int-4-class.md - - name: norm class - href: ../parallel/amp/reference/norm-class.md - - name: norm_2 class - href: ../parallel/amp/reference/norm-2-class.md - - name: norm_3 class - href: ../parallel/amp/reference/norm-3-class.md - - name: norm_4 class - href: ../parallel/amp/reference/norm-4-class.md - - name: sampler class - href: ../parallel/amp/reference/sampler-class.md - - name: short_vector Structure - href: ../parallel/amp/reference/short-vector-structure.md - - name: short_vector_traits Structure - href: ../parallel/amp/reference/short-vector-traits-structure.md - - name: texture class - href: ../parallel/amp/reference/texture-class.md - - name: texture_view class - href: ../parallel/amp/reference/texture-view-class.md - - name: writeonly_texture_view class - href: ../parallel/amp/reference/writeonly-texture-view-class.md - - name: uint_2 class - href: ../parallel/amp/reference/uint-2-class.md - - name: uint_3 class - href: ../parallel/amp/reference/uint-3-class.md - - name: uint_4 class - href: ../parallel/amp/reference/uint-4-class.md - - name: unorm class - href: ../parallel/amp/reference/unorm-class.md - - name: unorm_2 class - href: ../parallel/amp/reference/unorm-2-class.md - - name: unorm_3 class - href: ../parallel/amp/reference/unorm-3-class.md - - name: unorm_4 class - href: ../parallel/amp/reference/unorm-4-class.md - - name: "Concurrency::precise_math namespace" - expanded: false - items: - - name: "Concurrency::precise_math namespace" - href: ../parallel/amp/reference/concurrency-precise-math-namespace.md - - name: "Concurrency::precise_math namespace functions" - href: ../parallel/amp/reference/concurrency-precise-math-namespace-functions.md - name: Concurrency Runtime (ConcRT) - expanded: false items: - - name: Concurrency Runtime - href: ../parallel/concrt/concurrency-runtime.md - - name: Overview of the Concurrency Runtime - href: ../parallel/concrt/overview-of-the-concurrency-runtime.md - - name: Exception handling in the Concurrency Runtime - href: ../parallel/concrt/exception-handling-in-the-concurrency-runtime.md - - name: Parallel diagnostic tools (Concurrency Runtime) - href: ../parallel/concrt/parallel-diagnostic-tools-concurrency-runtime.md - - name: Creating asynchronous operations in C++ for UWP apps - href: ../parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md + - name: Concurrency Runtime + href: ../parallel/concrt/concurrency-runtime.md + - name: Overview of the Concurrency Runtime + href: ../parallel/concrt/overview-of-the-concurrency-runtime.md + - name: Exception handling in the Concurrency Runtime + href: ../parallel/concrt/exception-handling-in-the-concurrency-runtime.md + - name: Parallel diagnostic tools (Concurrency Runtime) + href: ../parallel/concrt/parallel-diagnostic-tools-concurrency-runtime.md + - name: Creating asynchronous operations in C++ for UWP apps + href: ../parallel/concrt/creating-asynchronous-operations-in-cpp-for-windows-store-apps.md + - name: Comparing the Concurrency Runtime to other concurrency models + items: - name: Comparing the Concurrency Runtime to other concurrency models + href: ../parallel/concrt/comparing-the-concurrency-runtime-to-other-concurrency-models.md + - name: Migrating from OpenMP to the Concurrency Runtime + items: + - name: Migrating from OpenMP to the Concurrency Runtime + href: ../parallel/concrt/migrating-from-openmp-to-the-concurrency-runtime.md + - name: 'How to: Convert an OpenMP parallel for loop to use the Concurrency Runtime' + href: ../parallel/concrt/how-to-convert-an-openmp-parallel-for-loop-to-use-the-concurrency-runtime.md + - name: 'How to: Convert an OpenMP loop that uses cancellation to use the Concurrency Runtime' + href: ../parallel/concrt/convert-an-openmp-loop-that-uses-cancellation.md + - name: 'How to: Convert an OpenMP loop that uses exception handling to use the Concurrency Runtime' + href: ../parallel/concrt/convert-an-openmp-loop-that-uses-exception-handling.md + - name: 'How to: Convert an OpenMP loop that uses a reduction variable to use the Concurrency Runtime' + href: ../parallel/concrt/convert-an-openmp-loop-that-uses-a-reduction-variable.md expanded: false - items: - - name: Comparing the Concurrency Runtime to other concurrency models - href: ../parallel/concrt/comparing-the-concurrency-runtime-to-other-concurrency-models.md - - name: Migrating from OpenMP to the Concurrency Runtime - expanded: false - items: - - name: Migrating from OpenMP to the Concurrency Runtime - href: ../parallel/concrt/migrating-from-openmp-to-the-concurrency-runtime.md - - name: "How to: Convert an OpenMP parallel for loop to use the Concurrency Runtime" - href: ../parallel/concrt/how-to-convert-an-openmp-parallel-for-loop-to-use-the-concurrency-runtime.md - - name: "How to: Convert an OpenMP loop that uses cancellation to use the Concurrency Runtime" - href: ../parallel/concrt/convert-an-openmp-loop-that-uses-cancellation.md - - name: "How to: Convert an OpenMP loop that uses exception handling to use the Concurrency Runtime" - href: ../parallel/concrt/convert-an-openmp-loop-that-uses-exception-handling.md - - name: "How to: Convert an OpenMP loop that uses a reduction variable to use the Concurrency Runtime" - href: ../parallel/concrt/convert-an-openmp-loop-that-uses-a-reduction-variable.md + expanded: false + - name: Parallel Patterns Library (PPL) + items: - name: Parallel Patterns Library (PPL) + href: ../parallel/concrt/parallel-patterns-library-ppl.md + - name: Task parallelism (Concurrency Runtime) + items: + - name: Task parallelism (Concurrency Runtime) + href: ../parallel/concrt/task-parallelism-concurrency-runtime.md + - name: 'How to: Use parallel_invoke to write a parallel sort routine' + href: ../parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md + - name: 'How to: Use parallel_invoke to execute parallel operations' + href: ../parallel/concrt/how-to-use-parallel-invoke-to-execute-parallel-operations.md + - name: 'How to: Create a task that completes after a delay' + href: ../parallel/concrt/how-to-create-a-task-that-completes-after-a-delay.md expanded: false - items: - - name: Parallel Patterns Library (PPL) - href: ../parallel/concrt/parallel-patterns-library-ppl.md - - name: Task parallelism (Concurrency Runtime) - expanded: false - items: - - name: Task parallelism (Concurrency Runtime) - href: ../parallel/concrt/task-parallelism-concurrency-runtime.md - - name: "How to: Use parallel_invoke to write a parallel sort routine" - href: ../parallel/concrt/how-to-use-parallel-invoke-to-write-a-parallel-sort-routine.md - - name: "How to: Use parallel_invoke to execute parallel operations" - href: ../parallel/concrt/how-to-use-parallel-invoke-to-execute-parallel-operations.md - - name: "How to: Create a task that completes after a delay" - href: ../parallel/concrt/how-to-create-a-task-that-completes-after-a-delay.md - - name: Parallel algorithms - expanded: false - items: - - name: Parallel algorithms - href: ../parallel/concrt/parallel-algorithms.md - - name: "How to: Write a parallel_for loop" - href: ../parallel/concrt/how-to-write-a-parallel-for-loop.md - - name: "How to: Write a parallel_for_each loop" - href: ../parallel/concrt/how-to-write-a-parallel-for-each-loop.md - - name: "How to: Perform map and reduce operations in parallel" - href: ../parallel/concrt/how-to-perform-map-and-reduce-operations-in-parallel.md - - name: Parallel containers and objects - expanded: false - items: - - name: Parallel containers and objects - href: ../parallel/concrt/parallel-containers-and-objects.md - - name: "How to: Use parallel containers to increase efficiency" - href: ../parallel/concrt/how-to-use-parallel-containers-to-increase-efficiency.md - - name: "How to: Use combinable to improve performance" - href: ../parallel/concrt/how-to-use-combinable-to-improve-performance.md - - name: "How to: Use combinable to combine sets" - href: ../parallel/concrt/how-to-use-combinable-to-combine-sets.md - - name: Cancellation in the PPL - expanded: false - items: - - name: Cancellation in the PPL - href: ../parallel/concrt/cancellation-in-the-ppl.md - - name: "How to: Use cancellation to break from a parallel loop" - href: ../parallel/concrt/how-to-use-cancellation-to-break-from-a-parallel-loop.md - - name: "How to: Use exception handling to break from a parallel loop" - href: ../parallel/concrt/how-to-use-exception-handling-to-break-from-a-parallel-loop.md - - name: Asynchronous Agents Library + - name: Parallel algorithms + items: + - name: Parallel algorithms + href: ../parallel/concrt/parallel-algorithms.md + - name: 'How to: Write a parallel_for loop' + href: ../parallel/concrt/how-to-write-a-parallel-for-loop.md + - name: 'How to: Write a parallel_for_each loop' + href: ../parallel/concrt/how-to-write-a-parallel-for-each-loop.md + - name: 'How to: Perform map and reduce operations in parallel' + href: ../parallel/concrt/how-to-perform-map-and-reduce-operations-in-parallel.md expanded: false - items: - - name: Asynchronous Agents Library - href: ../parallel/concrt/asynchronous-agents-library.md - - name: Asynchronous agents - href: ../parallel/concrt/asynchronous-agents.md - - name: Asynchronous message blocks - href: ../parallel/concrt/asynchronous-message-blocks.md - - name: Message passing functions - href: ../parallel/concrt/message-passing-functions.md - - name: "How to: Implement various producer-consumer patterns" - href: ../parallel/concrt/how-to-implement-various-producer-consumer-patterns.md - - name: "How to: Provide work functions to the call and transformer classes" - href: ../parallel/concrt/how-to-provide-work-functions-to-the-call-and-transformer-classes.md - - name: "How to: Use transformer in a data pipeline" - href: ../parallel/concrt/how-to-use-transformer-in-a-data-pipeline.md - - name: "How to: Select among completed tasks" - href: ../parallel/concrt/how-to-select-among-completed-tasks.md - - name: "How to: Send a message at a regular interval" - href: ../parallel/concrt/how-to-send-a-message-at-a-regular-interval.md - - name: "How to: Use a message block filter" - href: ../parallel/concrt/how-to-use-a-message-block-filter.md - - name: Synchronization data structures + - name: Parallel containers and objects + items: + - name: Parallel containers and objects + href: ../parallel/concrt/parallel-containers-and-objects.md + - name: 'How to: Use parallel containers to increase efficiency' + href: ../parallel/concrt/how-to-use-parallel-containers-to-increase-efficiency.md + - name: 'How to: Use combinable to improve performance' + href: ../parallel/concrt/how-to-use-combinable-to-improve-performance.md + - name: 'How to: Use combinable to combine sets' + href: ../parallel/concrt/how-to-use-combinable-to-combine-sets.md + expanded: false + - name: Cancellation in the PPL + items: + - name: Cancellation in the PPL + href: ../parallel/concrt/cancellation-in-the-ppl.md + - name: 'How to: Use cancellation to break from a parallel loop' + href: ../parallel/concrt/how-to-use-cancellation-to-break-from-a-parallel-loop.md + - name: 'How to: Use exception handling to break from a parallel loop' + href: ../parallel/concrt/how-to-use-exception-handling-to-break-from-a-parallel-loop.md expanded: false - items: - - name: Synchronization data structures - href: ../parallel/concrt/synchronization-data-structures.md - - name: Comparing synchronization data structures to the Windows API - href: ../parallel/concrt/comparing-synchronization-data-structures-to-the-windows-api.md + expanded: false + - name: Asynchronous Agents Library + items: + - name: Asynchronous Agents Library + href: ../parallel/concrt/asynchronous-agents-library.md + - name: Asynchronous agents + href: ../parallel/concrt/asynchronous-agents.md + - name: Asynchronous message blocks + href: ../parallel/concrt/asynchronous-message-blocks.md + - name: Message passing functions + href: ../parallel/concrt/message-passing-functions.md + - name: 'How to: Implement various producer-consumer patterns' + href: ../parallel/concrt/how-to-implement-various-producer-consumer-patterns.md + - name: 'How to: Provide work functions to the call and transformer classes' + href: ../parallel/concrt/how-to-provide-work-functions-to-the-call-and-transformer-classes.md + - name: 'How to: Use transformer in a data pipeline' + href: ../parallel/concrt/how-to-use-transformer-in-a-data-pipeline.md + - name: 'How to: Select among completed tasks' + href: ../parallel/concrt/how-to-select-among-completed-tasks.md + - name: 'How to: Send a message at a regular interval' + href: ../parallel/concrt/how-to-send-a-message-at-a-regular-interval.md + - name: 'How to: Use a message block filter' + href: ../parallel/concrt/how-to-use-a-message-block-filter.md + expanded: false + - name: Synchronization data structures + items: + - name: Synchronization data structures + href: ../parallel/concrt/synchronization-data-structures.md + - name: Comparing synchronization data structures to the Windows API + href: ../parallel/concrt/comparing-synchronization-data-structures-to-the-windows-api.md + expanded: false + - name: Task scheduler (Concurrency Runtime) + items: - name: Task scheduler (Concurrency Runtime) + href: ../parallel/concrt/task-scheduler-concurrency-runtime.md + - name: Scheduler instances + items: + - name: Scheduler instances + href: ../parallel/concrt/scheduler-instances.md + - name: 'How to: Manage a scheduler instance' + href: ../parallel/concrt/how-to-manage-a-scheduler-instance.md expanded: false - items: - - name: Task scheduler (Concurrency Runtime) - href: ../parallel/concrt/task-scheduler-concurrency-runtime.md - - name: Scheduler instances - expanded: false - items: - - name: Scheduler instances - href: ../parallel/concrt/scheduler-instances.md - - name: "How to: Manage a scheduler instance" - href: ../parallel/concrt/how-to-manage-a-scheduler-instance.md - - name: Scheduler policies - expanded: false - items: - - name: Scheduler policies - href: ../parallel/concrt/scheduler-policies.md - - name: "How to: Specify specific scheduler policies" - href: ../parallel/concrt/how-to-specify-specific-scheduler-policies.md - - name: "How to: Create agents that use specific scheduler policies" - href: ../parallel/concrt/how-to-create-agents-that-use-specific-scheduler-policies.md - - name: Schedule groups - expanded: false - items: - - name: Schedule groups - href: ../parallel/concrt/schedule-groups.md - - name: "How to: Use schedule groups to influence order of execution" - href: ../parallel/concrt/how-to-use-schedule-groups-to-influence-order-of-execution.md - - name: Lightweight tasks - href: ../parallel/concrt/lightweight-tasks.md - - name: Contexts - expanded: false - items: - - name: Contexts - href: ../parallel/concrt/contexts.md - - name: "How to: Use the Context class to implement a cooperative semaphore" - href: ../parallel/concrt/how-to-use-the-context-class-to-implement-a-cooperative-semaphore.md - - name: "How to: Use oversubscription to offset latency" - href: ../parallel/concrt/how-to-use-oversubscription-to-offset-latency.md - - name: Memory management functions - expanded: false - items: - - name: Memory management functions - href: ../parallel/concrt/memory-management-functions.md - - name: "How to: Use Alloc and Free to improve memory performance" - href: ../parallel/concrt/how-to-use-alloc-and-free-to-improve-memory-performance.md - - name: Concurrency Runtime walkthroughs + - name: Scheduler policies + items: + - name: Scheduler policies + href: ../parallel/concrt/scheduler-policies.md + - name: 'How to: Specify specific scheduler policies' + href: ../parallel/concrt/how-to-specify-specific-scheduler-policies.md + - name: 'How to: Create agents that use specific scheduler policies' + href: ../parallel/concrt/how-to-create-agents-that-use-specific-scheduler-policies.md + expanded: false + - name: Schedule groups + items: + - name: Schedule groups + href: ../parallel/concrt/schedule-groups.md + - name: 'How to: Use schedule groups to influence order of execution' + href: ../parallel/concrt/how-to-use-schedule-groups-to-influence-order-of-execution.md + expanded: false + - name: Lightweight tasks + href: ../parallel/concrt/lightweight-tasks.md + - name: Contexts + items: + - name: Contexts + href: ../parallel/concrt/contexts.md + - name: 'How to: Use the Context class to implement a cooperative semaphore' + href: ../parallel/concrt/how-to-use-the-context-class-to-implement-a-cooperative-semaphore.md + - name: 'How to: Use oversubscription to offset latency' + href: ../parallel/concrt/how-to-use-oversubscription-to-offset-latency.md + expanded: false + - name: Memory management functions + items: + - name: Memory management functions + href: ../parallel/concrt/memory-management-functions.md + - name: 'How to: Use Alloc and Free to improve memory performance' + href: ../parallel/concrt/how-to-use-alloc-and-free-to-improve-memory-performance.md expanded: false - items: - - name: Concurrency Runtime walkthroughs - href: ../parallel/concrt/concurrency-runtime-walkthroughs.md - - name: "Walkthrough: Connecting using tasks and xml http requests" - href: ../parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md - - name: "Walkthrough: Creating an agent-based application" - href: ../parallel/concrt/walkthrough-creating-an-agent-based-application.md - - name: "Walkthrough: Creating a dataflow agent" - href: ../parallel/concrt/walkthrough-creating-a-dataflow-agent.md - - name: "Walkthrough: Creating an image-processing network" - href: ../parallel/concrt/walkthrough-creating-an-image-processing-network.md - - name: "Walkthrough: Implementing futures" - href: ../parallel/concrt/walkthrough-implementing-futures.md - - name: "Walkthrough: Using join to prevent deadlock" - href: ../parallel/concrt/walkthrough-using-join-to-prevent-deadlock.md - - name: "Walkthrough: Removing work from a user-interface thread" - href: ../parallel/concrt/walkthrough-removing-work-from-a-user-interface-thread.md - - name: "Walkthrough: Using the Concurrency Runtime in a COM-enabled application" - href: ../parallel/concrt/walkthrough-using-the-concurrency-runtime-in-a-com-enabled-application.md - - name: "Walkthrough: Adapting existing code to use lightweight tasks" - href: ../parallel/concrt/walkthrough-adapting-existing-code-to-use-lightweight-tasks.md - - name: "Walkthrough: Creating a custom message block" - href: ../parallel/concrt/walkthrough-creating-a-custom-message-block.md + expanded: false + - name: Concurrency Runtime walkthroughs + items: + - name: Concurrency Runtime walkthroughs + href: ../parallel/concrt/concurrency-runtime-walkthroughs.md + - name: 'Walkthrough: Connecting using tasks and xml http requests' + href: ../parallel/concrt/walkthrough-connecting-using-tasks-and-xml-http-requests.md + - name: 'Walkthrough: Creating an agent-based application' + href: ../parallel/concrt/walkthrough-creating-an-agent-based-application.md + - name: 'Walkthrough: Creating a dataflow agent' + href: ../parallel/concrt/walkthrough-creating-a-dataflow-agent.md + - name: 'Walkthrough: Creating an image-processing network' + href: ../parallel/concrt/walkthrough-creating-an-image-processing-network.md + - name: 'Walkthrough: Implementing futures' + href: ../parallel/concrt/walkthrough-implementing-futures.md + - name: 'Walkthrough: Using join to prevent deadlock' + href: ../parallel/concrt/walkthrough-using-join-to-prevent-deadlock.md + - name: 'Walkthrough: Removing work from a user-interface thread' + href: ../parallel/concrt/walkthrough-removing-work-from-a-user-interface-thread.md + - name: 'Walkthrough: Using the Concurrency Runtime in a COM-enabled application' + href: ../parallel/concrt/walkthrough-using-the-concurrency-runtime-in-a-com-enabled-application.md + - name: 'Walkthrough: Adapting existing code to use lightweight tasks' + href: ../parallel/concrt/walkthrough-adapting-existing-code-to-use-lightweight-tasks.md + - name: 'Walkthrough: Creating a custom message block' + href: ../parallel/concrt/walkthrough-creating-a-custom-message-block.md + expanded: false + - name: Concurrency Runtime best practices + items: - name: Concurrency Runtime best practices + href: ../parallel/concrt/concurrency-runtime-best-practices.md + - name: Best practices in the Parallel Patterns Library + href: ../parallel/concrt/best-practices-in-the-parallel-patterns-library.md + - name: Best practices in the Asynchronous Agents Library + href: ../parallel/concrt/best-practices-in-the-asynchronous-agents-library.md + - name: General best practices in the Concurrency Runtime + href: ../parallel/concrt/general-best-practices-in-the-concurrency-runtime.md + expanded: false + - name: Reference + items: + - name: Reference (Concurrency Runtime) + href: ../parallel/concrt/reference/reference-concurrency-runtime.md + - name: concurrency namespace + items: + - name: concurrency namespace + href: ../parallel/concrt/reference/concurrency-namespace.md + - name: concurrency namespace functions + href: ../parallel/concrt/reference/concurrency-namespace-functions.md + - name: concurrency namespace Operators + href: ../parallel/concrt/reference/concurrency-namespace-operators.md + - name: concurrency namespace constants1 + href: ../parallel/concrt/reference/concurrency-namespace-constants1.md + - name: concurrency namespace enums + href: ../parallel/concrt/reference/concurrency-namespace-enums.md + - name: affinity_partitioner class + href: ../parallel/concrt/reference/affinity-partitioner-class.md + - name: agent class + href: ../parallel/concrt/reference/agent-class.md + - name: auto_partitioner class + href: ../parallel/concrt/reference/auto-partitioner-class.md + - name: bad_target class + href: ../parallel/concrt/reference/bad-target-class.md + - name: call class + href: ../parallel/concrt/reference/call-class.md + - name: cancellation_token class + href: ../parallel/concrt/reference/cancellation-token-class.md + - name: cancellation_token_registration class + href: ../parallel/concrt/reference/cancellation-token-registration-class.md + - name: cancellation_token_source class + href: ../parallel/concrt/reference/cancellation-token-source-class.md + - name: choice class + href: ../parallel/concrt/reference/choice-class.md + - name: combinable class + href: ../parallel/concrt/reference/combinable-class.md + - name: concurrent_priority_queue class + href: ../parallel/concrt/reference/concurrent-priority-queue-class.md + - name: concurrent_queue class + href: ../parallel/concrt/reference/concurrent-queue-class.md + - name: concurrent_unordered_map class + href: ../parallel/concrt/reference/concurrent-unordered-map-class.md + - name: concurrent_unordered_multimap class + href: ../parallel/concrt/reference/concurrent-unordered-multimap-class.md + - name: concurrent_unordered_multiset class + href: ../parallel/concrt/reference/concurrent-unordered-multiset-class.md + - name: concurrent_unordered_set class + href: ../parallel/concrt/reference/concurrent-unordered-set-class.md + - name: concurrent_vector class + href: ../parallel/concrt/reference/concurrent-vector-class.md + - name: Context class + href: ../parallel/concrt/reference/context-class.md + - name: context_self_unblock class + href: ../parallel/concrt/reference/context-self-unblock-class.md + - name: context_unblock_unbalanced class + href: ../parallel/concrt/reference/context-unblock-unbalanced-class.md + - name: critical_section class + href: ../parallel/concrt/reference/critical-section-class.md + - name: CurrentScheduler class + href: ../parallel/concrt/reference/currentscheduler-class.md + - name: default_scheduler_exists class + href: ../parallel/concrt/reference/default-scheduler-exists-class.md + - name: DispatchState Structure + href: ../parallel/concrt/reference/dispatchstate-structure.md + - name: event class + href: ../parallel/concrt/reference/event-class.md + - name: IExecutionContext Structure + href: ../parallel/concrt/reference/iexecutioncontext-structure.md + - name: IExecutionResource Structure + href: ../parallel/concrt/reference/iexecutionresource-structure.md + - name: improper_lock class + href: ../parallel/concrt/reference/improper-lock-class.md + - name: improper_scheduler_attach class + href: ../parallel/concrt/reference/improper-scheduler-attach-class.md + - name: improper_scheduler_detach class + href: ../parallel/concrt/reference/improper-scheduler-detach-class.md + - name: improper_scheduler_reference class + href: ../parallel/concrt/reference/improper-scheduler-reference-class.md + - name: invalid_link_target class + href: ../parallel/concrt/reference/invalid-link-target-class.md + - name: invalid_multiple_scheduling class + href: ../parallel/concrt/reference/invalid-multiple-scheduling-class.md + - name: invalid_operation class + href: ../parallel/concrt/reference/invalid-operation-class.md + - name: invalid_oversubscribe_operation class + href: ../parallel/concrt/reference/invalid-oversubscribe-operation-class.md + - name: invalid_scheduler_policy_key class + href: ../parallel/concrt/reference/invalid-scheduler-policy-key-class.md + - name: invalid_scheduler_policy_thread_specification class + href: ../parallel/concrt/reference/invalid-scheduler-policy-thread-specification-class.md + - name: invalid_scheduler_policy_value class + href: ../parallel/concrt/reference/invalid-scheduler-policy-value-class.md + - name: IResourceManager Structure + href: ../parallel/concrt/reference/iresourcemanager-structure.md + - name: IScheduler Structure + href: ../parallel/concrt/reference/ischeduler-structure.md + - name: ISchedulerProxy Structure + href: ../parallel/concrt/reference/ischedulerproxy-structure.md + - name: ISource class + href: ../parallel/concrt/reference/isource-class.md + - name: ITarget class + href: ../parallel/concrt/reference/itarget-class.md + - name: IThreadProxy Structure + href: ../parallel/concrt/reference/ithreadproxy-structure.md + - name: ITopologyExecutionResource Structure + href: ../parallel/concrt/reference/itopologyexecutionresource-structure.md + - name: ITopologyNode Structure + href: ../parallel/concrt/reference/itopologynode-structure.md + - name: IUMSCompletionList Structure + href: ../parallel/concrt/reference/iumscompletionlist-structure.md + - name: IUMSScheduler Structure + href: ../parallel/concrt/reference/iumsscheduler-structure.md + - name: IUMSThreadProxy Structure + href: ../parallel/concrt/reference/iumsthreadproxy-structure.md + - name: IUMSUnblockNotification Structure + href: ../parallel/concrt/reference/iumsunblocknotification-structure.md + - name: IVirtualProcessorRoot Structure + href: ../parallel/concrt/reference/ivirtualprocessorroot-structure.md + - name: join class + href: ../parallel/concrt/reference/join-class.md + - name: location class + href: ../parallel/concrt/reference/location-class.md + - name: message class + href: ../parallel/concrt/reference/message-class.md + - name: message_not_found class + href: ../parallel/concrt/reference/message-not-found-class.md + - name: message_processor class + href: ../parallel/concrt/reference/message-processor-class.md + - name: missing_wait class + href: ../parallel/concrt/reference/missing-wait-class.md + - name: multi_link_registry class + href: ../parallel/concrt/reference/multi-link-registry-class.md + - name: multitype_join class + href: ../parallel/concrt/reference/multitype-join-class.md + - name: nested_scheduler_missing_detach class + href: ../parallel/concrt/reference/nested-scheduler-missing-detach-class.md + - name: network_link_registry class + href: ../parallel/concrt/reference/network-link-registry-class.md + - name: operation_timed_out class + href: ../parallel/concrt/reference/operation-timed-out-class.md + - name: ordered_message_processor class + href: ../parallel/concrt/reference/ordered-message-processor-class.md + - name: overwrite_buffer class + href: ../parallel/concrt/reference/overwrite-buffer-class.md + - name: progress_reporter class + href: ../parallel/concrt/reference/progress-reporter-class.md + - name: propagator_block class + href: ../parallel/concrt/reference/propagator-block-class.md + - name: reader_writer_lock class + href: ../parallel/concrt/reference/reader-writer-lock-class.md + - name: ScheduleGroup class + href: ../parallel/concrt/reference/schedulegroup-class.md + - name: Scheduler class + href: ../parallel/concrt/reference/scheduler-class.md + - name: scheduler_interface Structure + href: ../parallel/concrt/reference/scheduler-interface-structure.md + - name: scheduler_not_attached class + href: ../parallel/concrt/reference/scheduler-not-attached-class.md + - name: scheduler_ptr Structure (Concurrency Runtime) + href: ../parallel/concrt/reference/scheduler-ptr-structure-concurrency-runtime.md + - name: scheduler_resource_allocation_error class + href: ../parallel/concrt/reference/scheduler-resource-allocation-error-class.md + - name: scheduler_worker_creation_error class + href: ../parallel/concrt/reference/scheduler-worker-creation-error-class.md + - name: SchedulerPolicy class + href: ../parallel/concrt/reference/schedulerpolicy-class.md + - name: simple_partitioner class + href: ../parallel/concrt/reference/simple-partitioner-class.md + - name: single_assignment class + href: ../parallel/concrt/reference/single-assignment-class.md + - name: single_link_registry class + href: ../parallel/concrt/reference/single-link-registry-class.md + - name: source_block class + href: ../parallel/concrt/reference/source-block-class.md + - name: source_link_manager class + href: ../parallel/concrt/reference/source-link-manager-class.md + - name: static_partitioner class + href: ../parallel/concrt/reference/static-partitioner-class.md + - name: structured_task_group class + href: ../parallel/concrt/reference/structured-task-group-class.md + - name: target_block class + href: ../parallel/concrt/reference/target-block-class.md + - name: task class (Concurrency Runtime) + href: ../parallel/concrt/reference/task-class.md + - name: task_canceled class + href: ../parallel/concrt/reference/task-canceled-class.md + - name: task_completion_event class + href: ../parallel/concrt/reference/task-completion-event-class.md + - name: task_continuation_context class + href: ../parallel/concrt/reference/task-continuation-context-class.md + - name: task_group class + href: ../parallel/concrt/reference/task-group-class.md + - name: task_handle class + href: ../parallel/concrt/reference/task-handle-class.md + - name: task_options class (Concurrency Runtime) + href: ../parallel/concrt/reference/task-options-class-concurrency-runtime.md + - name: timer class + href: ../parallel/concrt/reference/timer-class.md + - name: transformer class + href: ../parallel/concrt/reference/transformer-class.md + - name: unbounded_buffer class + href: ../parallel/concrt/reference/unbounded-buffer-class.md + - name: unsupported_os class + href: ../parallel/concrt/reference/unsupported-os-class.md expanded: false - items: - - name: Concurrency Runtime best practices - href: ../parallel/concrt/concurrency-runtime-best-practices.md - - name: Best practices in the Parallel Patterns Library - href: ../parallel/concrt/best-practices-in-the-parallel-patterns-library.md - - name: Best practices in the Asynchronous Agents Library - href: ../parallel/concrt/best-practices-in-the-asynchronous-agents-library.md - - name: General best practices in the Concurrency Runtime - href: ../parallel/concrt/general-best-practices-in-the-concurrency-runtime.md - - name: Reference + - name: std namespace + items: + - name: std namespace + href: ../parallel/concrt/reference/std-namespace.md + - name: make_exception_ptr function + href: ../parallel/concrt/reference/make-exception-ptr-function.md expanded: false - items: - - name: Reference (Concurrency Runtime) - href: ../parallel/concrt/reference/reference-concurrency-runtime.md - - name: concurrency namespace - expanded: false - items: - - name: concurrency namespace - href: ../parallel/concrt/reference/concurrency-namespace.md - - name: concurrency namespace functions - href: ../parallel/concrt/reference/concurrency-namespace-functions.md - - name: concurrency namespace Operators - href: ../parallel/concrt/reference/concurrency-namespace-operators.md - - name: concurrency namespace constants1 - href: ../parallel/concrt/reference/concurrency-namespace-constants1.md - - name: concurrency namespace enums - href: ../parallel/concrt/reference/concurrency-namespace-enums.md - - name: affinity_partitioner class - href: ../parallel/concrt/reference/affinity-partitioner-class.md - - name: agent class - href: ../parallel/concrt/reference/agent-class.md - - name: auto_partitioner class - href: ../parallel/concrt/reference/auto-partitioner-class.md - - name: bad_target class - href: ../parallel/concrt/reference/bad-target-class.md - - name: call class - href: ../parallel/concrt/reference/call-class.md - - name: cancellation_token class - href: ../parallel/concrt/reference/cancellation-token-class.md - - name: cancellation_token_registration class - href: ../parallel/concrt/reference/cancellation-token-registration-class.md - - name: cancellation_token_source class - href: ../parallel/concrt/reference/cancellation-token-source-class.md - - name: choice class - href: ../parallel/concrt/reference/choice-class.md - - name: combinable class - href: ../parallel/concrt/reference/combinable-class.md - - name: concurrent_priority_queue class - href: ../parallel/concrt/reference/concurrent-priority-queue-class.md - - name: concurrent_queue class - href: ../parallel/concrt/reference/concurrent-queue-class.md - - name: concurrent_unordered_map class - href: ../parallel/concrt/reference/concurrent-unordered-map-class.md - - name: concurrent_unordered_multimap class - href: ../parallel/concrt/reference/concurrent-unordered-multimap-class.md - - name: concurrent_unordered_multiset class - href: ../parallel/concrt/reference/concurrent-unordered-multiset-class.md - - name: concurrent_unordered_set class - href: ../parallel/concrt/reference/concurrent-unordered-set-class.md - - name: concurrent_vector class - href: ../parallel/concrt/reference/concurrent-vector-class.md - - name: Context class - href: ../parallel/concrt/reference/context-class.md - - name: context_self_unblock class - href: ../parallel/concrt/reference/context-self-unblock-class.md - - name: context_unblock_unbalanced class - href: ../parallel/concrt/reference/context-unblock-unbalanced-class.md - - name: critical_section class - href: ../parallel/concrt/reference/critical-section-class.md - - name: CurrentScheduler class - href: ../parallel/concrt/reference/currentscheduler-class.md - - name: default_scheduler_exists class - href: ../parallel/concrt/reference/default-scheduler-exists-class.md - - name: DispatchState Structure - href: ../parallel/concrt/reference/dispatchstate-structure.md - - name: event class - href: ../parallel/concrt/reference/event-class.md - - name: IExecutionContext Structure - href: ../parallel/concrt/reference/iexecutioncontext-structure.md - - name: IExecutionResource Structure - href: ../parallel/concrt/reference/iexecutionresource-structure.md - - name: improper_lock class - href: ../parallel/concrt/reference/improper-lock-class.md - - name: improper_scheduler_attach class - href: ../parallel/concrt/reference/improper-scheduler-attach-class.md - - name: improper_scheduler_detach class - href: ../parallel/concrt/reference/improper-scheduler-detach-class.md - - name: improper_scheduler_reference class - href: ../parallel/concrt/reference/improper-scheduler-reference-class.md - - name: invalid_link_target class - href: ../parallel/concrt/reference/invalid-link-target-class.md - - name: invalid_multiple_scheduling class - href: ../parallel/concrt/reference/invalid-multiple-scheduling-class.md - - name: invalid_operation class - href: ../parallel/concrt/reference/invalid-operation-class.md - - name: invalid_oversubscribe_operation class - href: ../parallel/concrt/reference/invalid-oversubscribe-operation-class.md - - name: invalid_scheduler_policy_key class - href: ../parallel/concrt/reference/invalid-scheduler-policy-key-class.md - - name: invalid_scheduler_policy_thread_specification class - href: ../parallel/concrt/reference/invalid-scheduler-policy-thread-specification-class.md - - name: invalid_scheduler_policy_value class - href: ../parallel/concrt/reference/invalid-scheduler-policy-value-class.md - - name: IResourceManager Structure - href: ../parallel/concrt/reference/iresourcemanager-structure.md - - name: IScheduler Structure - href: ../parallel/concrt/reference/ischeduler-structure.md - - name: ISchedulerProxy Structure - href: ../parallel/concrt/reference/ischedulerproxy-structure.md - - name: ISource class - href: ../parallel/concrt/reference/isource-class.md - - name: ITarget class - href: ../parallel/concrt/reference/itarget-class.md - - name: IThreadProxy Structure - href: ../parallel/concrt/reference/ithreadproxy-structure.md - - name: ITopologyExecutionResource Structure - href: ../parallel/concrt/reference/itopologyexecutionresource-structure.md - - name: ITopologyNode Structure - href: ../parallel/concrt/reference/itopologynode-structure.md - - name: IUMSCompletionList Structure - href: ../parallel/concrt/reference/iumscompletionlist-structure.md - - name: IUMSScheduler Structure - href: ../parallel/concrt/reference/iumsscheduler-structure.md - - name: IUMSThreadProxy Structure - href: ../parallel/concrt/reference/iumsthreadproxy-structure.md - - name: IUMSUnblockNotification Structure - href: ../parallel/concrt/reference/iumsunblocknotification-structure.md - - name: IVirtualProcessorRoot Structure - href: ../parallel/concrt/reference/ivirtualprocessorroot-structure.md - - name: join class - href: ../parallel/concrt/reference/join-class.md - - name: location class - href: ../parallel/concrt/reference/location-class.md - - name: message class - href: ../parallel/concrt/reference/message-class.md - - name: message_not_found class - href: ../parallel/concrt/reference/message-not-found-class.md - - name: message_processor class - href: ../parallel/concrt/reference/message-processor-class.md - - name: missing_wait class - href: ../parallel/concrt/reference/missing-wait-class.md - - name: multi_link_registry class - href: ../parallel/concrt/reference/multi-link-registry-class.md - - name: multitype_join class - href: ../parallel/concrt/reference/multitype-join-class.md - - name: nested_scheduler_missing_detach class - href: ../parallel/concrt/reference/nested-scheduler-missing-detach-class.md - - name: network_link_registry class - href: ../parallel/concrt/reference/network-link-registry-class.md - - name: operation_timed_out class - href: ../parallel/concrt/reference/operation-timed-out-class.md - - name: ordered_message_processor class - href: ../parallel/concrt/reference/ordered-message-processor-class.md - - name: overwrite_buffer class - href: ../parallel/concrt/reference/overwrite-buffer-class.md - - name: progress_reporter class - href: ../parallel/concrt/reference/progress-reporter-class.md - - name: propagator_block class - href: ../parallel/concrt/reference/propagator-block-class.md - - name: reader_writer_lock class - href: ../parallel/concrt/reference/reader-writer-lock-class.md - - name: ScheduleGroup class - href: ../parallel/concrt/reference/schedulegroup-class.md - - name: Scheduler class - href: ../parallel/concrt/reference/scheduler-class.md - - name: scheduler_interface Structure - href: ../parallel/concrt/reference/scheduler-interface-structure.md - - name: scheduler_not_attached class - href: ../parallel/concrt/reference/scheduler-not-attached-class.md - - name: scheduler_ptr Structure (Concurrency Runtime) - href: ../parallel/concrt/reference/scheduler-ptr-structure-concurrency-runtime.md - - name: scheduler_resource_allocation_error class - href: ../parallel/concrt/reference/scheduler-resource-allocation-error-class.md - - name: scheduler_worker_creation_error class - href: ../parallel/concrt/reference/scheduler-worker-creation-error-class.md - - name: SchedulerPolicy class - href: ../parallel/concrt/reference/schedulerpolicy-class.md - - name: simple_partitioner class - href: ../parallel/concrt/reference/simple-partitioner-class.md - - name: single_assignment class - href: ../parallel/concrt/reference/single-assignment-class.md - - name: single_link_registry class - href: ../parallel/concrt/reference/single-link-registry-class.md - - name: source_block class - href: ../parallel/concrt/reference/source-block-class.md - - name: source_link_manager class - href: ../parallel/concrt/reference/source-link-manager-class.md - - name: static_partitioner class - href: ../parallel/concrt/reference/static-partitioner-class.md - - name: structured_task_group class - href: ../parallel/concrt/reference/structured-task-group-class.md - - name: target_block class - href: ../parallel/concrt/reference/target-block-class.md - - name: task class (Concurrency Runtime) - href: ../parallel/concrt/reference/task-class.md - - name: task_canceled class - href: ../parallel/concrt/reference/task-canceled-class.md - - name: task_completion_event class - href: ../parallel/concrt/reference/task-completion-event-class.md - - name: task_continuation_context class - href: ../parallel/concrt/reference/task-continuation-context-class.md - - name: task_group class - href: ../parallel/concrt/reference/task-group-class.md - - name: task_handle class - href: ../parallel/concrt/reference/task-handle-class.md - - name: task_options class (Concurrency Runtime) - href: ../parallel/concrt/reference/task-options-class-concurrency-runtime.md - - name: timer class - href: ../parallel/concrt/reference/timer-class.md - - name: transformer class - href: ../parallel/concrt/reference/transformer-class.md - - name: unbounded_buffer class - href: ../parallel/concrt/reference/unbounded-buffer-class.md - - name: unsupported_os class - href: ../parallel/concrt/reference/unsupported-os-class.md - - name: std namespace - expanded: false - items: - - name: std namespace - href: ../parallel/concrt/reference/std-namespace.md - - name: make_exception_ptr function - href: ../parallel/concrt/reference/make-exception-ptr-function.md - - name: stdx namespace - expanded: false - items: - - name: stdx namespace - href: ../parallel/concrt/reference/stdx-namespace.md - - name: declval function - href: ../parallel/concrt/reference/declval-function.md -- name: OpenMP + - name: stdx namespace + items: + - name: stdx namespace + href: ../parallel/concrt/reference/stdx-namespace.md + - name: declval function + href: ../parallel/concrt/reference/declval-function.md + expanded: false + expanded: false expanded: false +- name: OpenMP items: - - name: OpenMP in MSVC - href: ../parallel/openmp/openmp-in-visual-cpp.md - - name: SIMD Extension - href: ../parallel/openmp/openmp-simd.md + - name: OpenMP in MSVC + href: ../parallel/openmp/openmp-in-visual-cpp.md + - name: SIMD Extension + href: ../parallel/openmp/openmp-simd.md + - name: OpenMP C and C++ Application Program Interface + items: - name: OpenMP C and C++ Application Program Interface - expanded: false - items: - - name: OpenMP C and C++ Application Program Interface - href: ../parallel/openmp/openmp-c-and-cpp-application-program-interface.md - - name: Introduction - href: ../parallel/openmp/1-introduction.md - - name: Directives - href: ../parallel/openmp/2-directives.md - - name: Run-time library functions - href: ../parallel/openmp/3-run-time-library-functions.md - - name: Environment variables - href: ../parallel/openmp/4-environment-variables.md - - name: Appendices - items: - - name: Examples - href: ../parallel/openmp/a-examples.md - - name: Stubs for run-time library functions - href: ../parallel/openmp/b-stubs-for-run-time-library-functions.md - - name: OpenMP C and C++ grammar - href: ../parallel/openmp/c-openmp-c-and-cpp-grammar.md - - name: The schedule clause - href: ../parallel/openmp/d-using-the-schedule-clause.md - - name: Implementation-defined behaviors in OpenMP C/C++ - href: ../parallel/openmp/e-implementation-defined-behaviors-in-openmp-c-cpp.md - - name: New features and clarifications in version 2.0 - href: ../parallel/openmp/f-new-features-and-clarifications-in-version-2-0.md + href: ../parallel/openmp/openmp-c-and-cpp-application-program-interface.md + - name: Introduction + href: ../parallel/openmp/1-introduction.md + - name: Directives + href: ../parallel/openmp/2-directives.md + - name: Run-time library functions + href: ../parallel/openmp/3-run-time-library-functions.md + - name: Environment variables + href: ../parallel/openmp/4-environment-variables.md + - name: Appendices + items: + - name: Examples + href: ../parallel/openmp/a-examples.md + - name: Stubs for run-time library functions + href: ../parallel/openmp/b-stubs-for-run-time-library-functions.md + - name: OpenMP C and C++ grammar + href: ../parallel/openmp/c-openmp-c-and-cpp-grammar.md + - name: The schedule clause + href: ../parallel/openmp/d-using-the-schedule-clause.md + - name: Implementation-defined behaviors in OpenMP C/C++ + href: ../parallel/openmp/e-implementation-defined-behaviors-in-openmp-c-cpp.md + - name: New features and clarifications in version 2.0 + href: ../parallel/openmp/f-new-features-and-clarifications-in-version-2-0.md + expanded: false + - name: OpenMP library reference + items: - name: OpenMP library reference - expanded: false - items: - - name: OpenMP library reference - href: ../parallel/openmp/reference/openmp-library-reference.md - - name: Directives - href: ../parallel/openmp/reference/openmp-directives.md - - name: Clauses - href: ../parallel/openmp/reference/openmp-clauses.md - - name: Functions - href: ../parallel/openmp/reference/openmp-functions.md - - name: Environment variables - href: ../parallel/openmp/reference/openmp-environment-variables.md -- name: Multithreading support for older code (C++) + href: ../parallel/openmp/reference/openmp-library-reference.md + - name: Directives + href: ../parallel/openmp/reference/openmp-directives.md + - name: Clauses + href: ../parallel/openmp/reference/openmp-clauses.md + - name: Functions + href: ../parallel/openmp/reference/openmp-functions.md + - name: Environment variables + href: ../parallel/openmp/reference/openmp-environment-variables.md + expanded: false expanded: false - items: - - name: Multithreading support for older code (C++) - href: ../parallel/multithreading-support-for-older-code-visual-cpp.md +- name: Multithreading support for older code (C++) + items: + - name: Multithreading support for older code (C++) + href: ../parallel/multithreading-support-for-older-code-visual-cpp.md + - name: Multithreading with C and Win32 + items: - name: Multithreading with C and Win32 - expanded: false - items: - - name: Multithreading with C and Win32 - href: ../parallel/multithreading-with-c-and-win32.md - - name: Sample multithread C program - href: ../parallel/sample-multithread-c-program.md - - name: Thread local storage (TLS) - href: ../parallel/thread-local-storage-tls.md + href: ../parallel/multithreading-with-c-and-win32.md + - name: Sample multithread C program + href: ../parallel/sample-multithread-c-program.md + - name: Thread local storage (TLS) + href: ../parallel/thread-local-storage-tls.md + expanded: false + - name: Multithreading with C++ and MFC + items: - name: Multithreading with C++ and MFC - expanded: false - items: - - name: Multithreading with C++ and MFC - href: ../parallel/multithreading-with-cpp-and-mfc.md - - name: "Multithreading: Creating user-interface threads" - href: ../parallel/multithreading-creating-user-interface-threads.md - - name: "Multithreading: Creating worker threads" - href: ../parallel/multithreading-creating-worker-threads.md - - name: "Multithreading: When to use the synchronization classes" - href: ../parallel/multithreading-when-to-use-the-synchronization-classes.md - - name: "Multithreading: How to use the synchronization classes" - href: ../parallel/multithreading-how-to-use-the-synchronization-classes.md - - name: "Multithreading: Terminating threads" - href: ../parallel/multithreading-terminating-threads.md - - name: "Multithreading: Programming tips" - href: ../parallel/multithreading-programming-tips.md - - name: Multithreading and locales - href: ../parallel/multithreading-and-locales.md + href: ../parallel/multithreading-with-cpp-and-mfc.md + - name: 'Multithreading: Creating user-interface threads' + href: ../parallel/multithreading-creating-user-interface-threads.md + - name: 'Multithreading: Creating worker threads' + href: ../parallel/multithreading-creating-worker-threads.md + - name: 'Multithreading: When to use the synchronization classes' + href: ../parallel/multithreading-when-to-use-the-synchronization-classes.md + - name: 'Multithreading: How to use the synchronization classes' + href: ../parallel/multithreading-how-to-use-the-synchronization-classes.md + - name: 'Multithreading: Terminating threads' + href: ../parallel/multithreading-terminating-threads.md + - name: 'Multithreading: Programming tips' + href: ../parallel/multithreading-programming-tips.md + expanded: false + - name: Multithreading and locales + href: ../parallel/multithreading-and-locales.md + expanded: false diff --git a/docs/porting/binary-compat-2015-2017.md b/docs/porting/binary-compat-2015-2017.md index 636e0f31f9a..19797a108d1 100644 --- a/docs/porting/binary-compat-2015-2017.md +++ b/docs/porting/binary-compat-2015-2017.md @@ -1,30 +1,31 @@ --- -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 +title: "C++ binary compatibility 2015-2026" +description: "Describes how binary compatibility works between compiled C++ files in Visual Studio 2015, 2017, 2019, 2022, and 2026. One Microsoft Visual C++ Redistributable package works for all these versions." +ms.date: 10/29/2025 helpviewer_keywords: ["binary compatibility, Visual C++"] --- # C++ binary compatibility between Visual Studio versions -The Microsoft C++ (MSVC) compiler toolsets in Visual Studio 2013 and earlier don't guarantee binary compatibility across major versions. You can't link object files, static libraries, dynamic libraries, and executables built by different versions of these toolsets. The ABIs, object formats, and runtime libraries are incompatible. +The Microsoft C++ (MSVC) Build Tools in Visual Studio 2013 and earlier don't guarantee binary compatibility across major versions. You can't link object files, static libraries, dynamic libraries, and executables built by different versions of these build tools. The ABIs, object formats, and runtime libraries are incompatible. -We've changed this behavior in Visual Studio 2015 and later versions. The runtime libraries and apps compiled by any of these versions of the compiler are binary-compatible. It's reflected in the C++ toolset major number, which starts with 14 for all versions since Visual Studio 2015. (The toolset version is v140 for Visual Studio 2015, v141 for 2017, v142 for 2019, and v143 for 2022). Say you have third-party libraries built by Visual Studio 2015. You can still use them in an application built by Visual Studio 2017, 2019, or 2022. There's no need to recompile with a matching toolset. The latest version of the Microsoft Visual C++ Redistributable package (the Redistributable) works for all of them. +We've changed this behavior in Visual Studio 2015 and later versions. The runtime libraries and apps compiled by any of these versions of the compiler are binary-compatible. It's reflected in the MSVC Build Tools major number, which starts with 14 for all versions since Visual Studio 2015. (The build tools version is v140 for Visual Studio 2015, v141 for 2017, v142 for 2019, and v143 for 2022). Say you have third-party libraries built by Visual Studio 2015. You can still use them in an application built by Visual Studio 2017, 2019, 2022, or 2026. There's no need to recompile with a matching version. The latest version of the Microsoft Visual C++ Redistributable package (the Redistributable) works for all of them. ## Restrictions on binary compatibility -There are three important restrictions on binary compatibility between the v140, v141, v142, and v143 toolsets and minor numbered version updates: +There are three important restrictions on binary compatibility between the v140, v141, v142, v143, and v145 build tools 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. - -- 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). +- Binaries created with different versions of the v140, v141, v142, v143, and v145 build tools can be combined. The key rule is that the linker should only work with inputs built by build tools that are 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 build tools can be linked using an earlier version of the build tools--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 the 2017 build tools (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 build tools. + - Apps and libraries built using VS 2015, 2017, 2019, 2022, and 2026 can be linked together, but the linking must be done using a version of the build tools that is as recent as, or more recent than, the most recent build tools used to build any of the binaries you pass to the linker. For example, given three binaries built with build tools from VS 2015 version 14.3, VS 2017 version 15.9, and VS 2019 version 16.11, you can link them using any build tools version that is 16.11 or later. + - If a DLL is built with newer build tools, the import library can sometimes be used with older build tools 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 older build tools. +- The Redistributable your app uses has a similar binary-compatibility restriction. When you mix binaries built by different supported versions of the build tools, the Redistributable version must be at least as new as the latest build tools 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 build tools for the compile and the final link. For example, code built by using **`/GL`** in the Visual Studio 2019 version 16.7 build tools can't be linked to code built by using **`/GL`** in the Visual Studio 2019 version 16.8 build tools. 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 -We've kept the Microsoft Visual C++ Redistributable major version number the same for Visual Studio 2015, 2017, 2019, and 2022. That means only one instance of the Redistributable can be installed at a time. A newer version overwrites any older version that's already installed. For example, one app may install the Redistributable from Visual Studio 2015. Then, another app installs the Redistributable from Visual Studio 2022. The 2022 version overwrites the older version, but because they're binary-compatible, the earlier app still works fine. We make sure the latest version of the Redistributable has all the newest features, security updates, and bug fixes. That's why we always recommend you upgrade to the latest available version. +We've kept the Microsoft Visual C++ Redistributable major version number the same for Visual Studio 2015, 2017, 2019, 2022, and 2026. That means only one instance of the Redistributable can be installed at a time. A newer version overwrites any older version that's already installed. For example, one app may install the Redistributable from Visual Studio 2015. Then, another app installs the Redistributable from Visual Studio 2026. The 2026 version overwrites the older version, but because they're binary-compatible, the earlier app still works fine. We make sure the latest version of the Redistributable has all the newest features, security updates, and bug fixes. That's why we always recommend you upgrade to the latest available version. -Similarly, you can't install an older Redistributable when a newer version is already installed. The installer reports an error if you try. You'll see an error like this if you install the 2017 or 2019 Redistributable on a machine that already has the 2022 version: +Similarly, you can't install an older Redistributable when a newer version is already installed. The installer reports an error if you try. For example, you'll see an error like this if you install the 2022 Redistributable on a machine that already has the 2026 version: ```Output 0x80070666 - Another version of this product is already installed. Installation of this version cannot continue. To configure or remove the existing version of this product, use Add/Remove Programs on the Control Panel. @@ -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 257ad65325a..afde5d89f65 100644 --- a/docs/porting/build-system-changes.md +++ b/docs/porting/build-system-changes.md @@ -1,13 +1,13 @@ --- 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 --- # VCBuild vs. MSBuild: Build system changes in Visual Studio 2010 -The MSBuild system for C++ projects was introduced in Visual Studio 2010. In Visual Studio 2008 and earlier releases, the VCBuild system was used. Certain file types and concepts that depended on VCBuild either do not exist or are represented differently in MSBuild. This document discusses the differences in the current build system. To convert a Visual Studio 2008 project to MSBuild, you must use Visual Studio 2010. After the project is converted, you should use the latest version of Visual Studio to upgrade to the current IDE and compiler toolset. For more information, including how to obtain Visual Studio 2010, see [Instructions for Visual Studio 2008](use-native-multi-targeting.md#instructions-for-visual-studio-2008). +The MSBuild system for C++ projects was introduced in Visual Studio 2010. In Visual Studio 2008 and earlier releases, the VCBuild system was used. Certain file types and concepts that depended on VCBuild either do not exist or are represented differently in MSBuild. This document discusses the differences in the current build system. To convert a Visual Studio 2008 project to MSBuild, you must use Visual Studio 2010. After the project is converted, you should use the latest version of Visual Studio to upgrade to the current IDE and build tools. For more information, including how to obtain Visual Studio 2010, see [Instructions for Visual Studio 2008](use-native-multi-targeting.md#instructions-for-visual-studio-2008). The following sections summarize the changes from VCBuild to MSBuild. If your VCBuild project has custom build rules or macros that aren't recognized by MSBuild, see [Visual Studio Projects - C++](../build/creating-and-managing-visual-cpp-projects.md) to learn how to translate those instructions to the MSBuild system. The initial conversion from VCBuild to MSBuild is just an intermediate step. It isn't necessary to get the project file completely correct or to get the program to compile without errors. You are only using Visual Studio 2010 to convert the project to MSBuild format so that you get the project working in the latest version of Visual Studio. diff --git a/docs/porting/copilot-app-modernization-cpp.md b/docs/porting/copilot-app-modernization-cpp.md new file mode 100644 index 00000000000..d6e23461baf --- /dev/null +++ b/docs/porting/copilot-app-modernization-cpp.md @@ -0,0 +1,100 @@ +--- +title: "Modernize your C++ project with GitHub Copilot modernization" +description: "Instructions on effectively using GitHub Copilot modernization in your C++ projects" +ms.date: 03/12/2026 +ms.topic: upgrade-and-migration-article +author: michaelbprice +ms.author: miprice +--- + +# Using GitHub Copilot modernization for C++ + +GitHub Copilot modernization for C++ helps you upgrade C++ projects to newer MSVC Build Tools versions. If necessary, Copilot will upgrade your project's settings to use the latest MSVC, and then conduct a thorough assessment of the impact of those changes after executing a build. It develops a plan on how to address each identified problem. Once you approve the plan, the agent completes a sequence of tasks and validates that any changes resolved the identified problems. If there remains work to be done, the agent continues iterating until the problems are resolved or you discontinue the conversation. + +> [!NOTE] +> GitHub Copilot modernization for C++ is currently in preview. + +## Requirements + +- Visual Studio 2026 version 18.3 or later +- A GitHub Copilot account +- A MSBuild-based codebase (`.sln`, `.vcxproj`) OR a CMake-based codebase + +## Enable GitHub Copilot modernization for C++ + +GitHub Copilot modernization for C++ is enabled by default. To disable or explicitly enable the feature, follow these steps. + +1. From Visual Studio, select **Tools > Options...** to open the **Options** window. +1. Navigate to **All Settings > GitHub > Copilot > C/C++**. +1. Select (to enable) or clear (to disable) the checkbox for **Enable GitHub Copilot modernization for C++ (preview)**. +1. Restart Visual Studio for the setting change to take effect. + +:::image type="content" source="media/enable-copilot-app-modernization-cpp.png" alt-text="Screenshot of Visual Studio Options dialog. GitHub > Copilot > C/C++ settings are visible. The modernization for C++ checkbox is enabled." lightbox="media/enable-copilot-app-modernization-cpp.png"::: + +## Upgrade your codebase by using GitHub Copilot modernization for C++ + +This section describes how to start the Modernize agent and the stages it goes through to upgrade your codebase. + +### Start the Modernize agent + +GitHub Copilot modernization is an agent that operates inside the GitHub Copilot Chat window. You can start the agent in any of the following ways: + +- **From the Solution Explorer context menu**: Right-click on the solution or a loaded project in the Solution Explorer, and choose **Modernize** from the context menu. This automatically launches a GitHub Copilot Chat window, activates the Modernize agent, and provides you with relevant prompts to choose from to get you started. + +:::image type="content" source="media/copilot-app-modernization-context-menu.png" alt-text="Screenshot of Visual Studio Solution Explorer showing a right-click context menu with Modernize selected to start the Copilot agent."::: + +- **From GitHub Copilot Chat**: Open the GitHub Copilot Chat Window by selecting **View > GitHub Copilot Chat**. After the GitHub Copilot Chat window opens, mention `@Modernize` in a prompt to activate the Modernize agent. For example, type this prompt: + + `Use @Modernize to update MSVC Build Tools.` + +#### For MSBuild-based codebases targeting an earlier version of MSVC Build Tools + +The first time that you load a `.vcxproj` project that targets an earlier version of the MSVC Build Tools, you see an option to [upgrade project settings to use a newer version of the MSVC Build Tools](/visualstudio/install/setup-assistant). If you retarget any of your projects to a new version of MSVC Build Tools and GitHub Copilot modernization for C++ is enabled, you receive an infobar in Visual Studio prompting you to use GitHub Copilot modernization for C++ to resolve any newly introduced build problems. Selecting **Run GitHub Copilot modernization for C++** launches the GitHub Copilot Chat window, activates the Modernize agent, and provides you with relevant prompts to choose from to get you started. + +### Start the upgrade + +Once the Modernize agent is active, you can instruct it via a prompt to upgrade your MSVC Build Tools, or select the already constructed prompt from the list shown in the window. If you launched the agent directly in the GitHub Copilot Chat window by mentioning `@Modernize` in your prompt, you probably don't need to provide more prompting. + +:::row::: +:::column::: + +**MSBuild Projects** + +:::column-end::: +:::column::: + +**CMake Projects** + +:::column-end::: +:::row-end::: +:::row::: +:::column::: + +:::image type="content" source="media/app-modernization-msbuild-ice-breaker.png" alt-text="Screenshot of GitHub Copilot Chat window. The dropdown is set to Modernize experience and Upgrade MSVC Build Tools to the latest version is highlighted."::: + +:::column-end::: +:::column::: + +:::image type="content" source="media/app-modernization-cmake-ice-breaker.png" alt-text="Screenshot of GitHub Copilot Chat window. The dropdown is set to Modernize experience and Resolve build issues by migrating to modern alternatives is highlighted."::: + +:::column-end::: +:::row-end::: + + +### Assessment stage + +The agent first assesses what kinds of problems show up after upgrading. If you didn't already upgrade the project, the agent guides you through that process before creating its assessment. After ensuring that your project is upgraded, the agent builds your codebase, analyzes the reported warnings and errors, and generates an `assessment.md` file that describes the problems that it found, their severity, and other useful information. This is your opportunity to tell the agent any other context that could help it make a plan. + +One of the things you might choose to do here is to tell the agent not to fix certain discovered problems, because you know that resolving them involves some strategic decisions or because they were preexisting warnings that you decided are acceptable for your project. You should carefully read through the plan, making sure to provide that extra context where it is needed. Once you approve the assessment, the agent moves on to creating a concrete plan on addressing the problems. + +### Planning stage + +Based on the approved assessment and any other context or instructions you provide, the agent creates a `plan.md` file that proposes a detailed plan for resolving each of the identified problems. If the agent produces a plan that doesn't match your organization's coding style or practices, you can provide that guidance to the agent and have it solve the problem differently. After you agree on the plan, the agent moves to the execution stage. + +### Execution stage + +Now that the agent has a plan, it breaks down the necessary tasks to execute the plan. You can define these tasks as finely as you want. The tasks can even include steps to work on a branch or to commit specific changes together in the same commit. After making any changes, the agent builds the project again to confirm that the problems are resolved. If the problems aren't resolved, the agent iterates with you until they're resolved to your satisfaction. + +### Post-upgrade validation + +When the agent finishes, run the changes through any testing infrastructure you have. Have a colleague review the changes in a pull request. Since this feature is currently in preview, you might receive an infobar to complete a product survey to let the product team know how the agent performed on your codebase. The product team looks forward to hearing how they can improve the agent to solve your problems and accelerate your upgrade and modernization efforts. \ No newline at end of file diff --git a/docs/porting/features-deprecated-in-visual-studio.md b/docs/porting/features-deprecated-in-visual-studio.md index 71383dbc034..21848bb9152 100644 --- a/docs/porting/features-deprecated-in-visual-studio.md +++ b/docs/porting/features-deprecated-in-visual-studio.md @@ -1,21 +1,61 @@ --- -description: "Learn more about: C++ features deprecated in Visual Studio" -title: "C++ features deprecated in Visual Studio" -ms.date: 04/07/2022 -helpviewer_keywords: ["Features deprecated in Visual Studio"] +description: "Learn more about: C++ features deprecated or removed from Visual Studio" +title: "C++ features deprecated or removed from Visual Studio" +ms.date: 05/11/2026 +helpviewer_keywords: ["Features deprecated or removed from Visual Studio"] --- -# C++ features deprecated in Visual Studio +# C++ features deprecated or removed from Visual Studio -This article is a non-exhaustive list of C++ features deprecated in Visual Studio 2019 and 2022. For information on breaking changes and conformance improvements for C++ in the latest version of Visual Studio, see [C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md). +This article is a nonexhaustive list of C++ features deprecated or removed from Visual Studio 2019 and later. For information on breaking changes and conformance improvements for C++ in the latest version of Visual Studio, see [C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md). -## Deprecated in Visual Studio 2019 +### Support for Windows XP development -- Support for Windows XP development +Visual Studio 2019 and later versions don't include current build tools support for creating code for Windows XP. Support for Windows XP development by using the v141_xp build tools that shipped in Visual Studio 2017 is still available as an optional component in the Visual Studio Installer. For information on how to install the v141_xp Windows XP platform toolset, see [Configuring programs for Windows XP](../build/configuring-programs-for-windows-xp.md). - Visual Studio 2019 and later versions don't include current toolset support for creating code for Windows XP. Support for Windows XP development by using the v141_xp toolset that shipped in Visual Studio 2017 is still available as an optional component in the Visual Studio Installer. For information on how to install the v141_xp Windows XP platform toolset, see [Configuring programs for Windows XP](../build/configuring-programs-for-windows-xp.md). +## Visual Studio 2026 (MSVC 14.51) -## Deprecated in Visual Studio 2022 +- The following experimental coroutine headers are now deprecated: ``, ``, and ``. Transition to standard C++20 coroutines using the `` header. -- Support for project upgrade from Visual C++ 6 - - Visual Studio 2022 and later versions don't support upgrades from Visual C++ 6 Workspace (*`.dsw`*) and Project (*`.dsp`*) files. Visual Studio no longer registers the *`.dsw`* and *`.dsp`* file extensions as Visual Studio file types. To upgrade a project with these extensions, first use Visual Studio 2019 to upgrade the project to modern Solution (*`.sln`*) and C++ Project (*`.vcxproj`*) files. Then use the current version of Visual Studio to upgrade the project again. +### Removed features + +The following long-deprecated non-Standard features are removed: + +- **TR1** including the `std::tr1` namespace, old `array::assign()`, and old `` engines and distributions. Deprecated since VS 2017 15.5 (December 2017). +- **`_ALLOW_RTCc_IN_STL`** macro removed. The Standard Template Library doesn't support the `/RTCc` compiler option, but `/RTCs` and `/RTCu`/`/RTC1` remain supported. +- **`` and ``**. Deprecated since VS 2015 (July 2015). +- **``**. Deprecated since VS 2019 16.3 (September 2019). +- **`stdext::checked_array_iterator` and `stdext::unchecked_array_iterator`**. Deprecated since VS 2022 17.8 (November 2023) for C++17 and later. +- **`basic_istream::ipfx()`/`isfx()` and `basic_ostream::opfx()`/`osfx()`**. Deprecated since VS 2022 17.9 (February 2024) for C++17 and later. +- **`locale::empty()`**. Deprecated since VS 2022 17.14 (May 2025). + +## Visual Studio 2022 + +### Support for project upgrade from Visual C++ 6 + +Visual Studio 2022 and later versions don't support upgrades from Visual C++ 6 Workspace (*`.dsw`*) and Project (*`.dsp`*) files. Visual Studio no longer registers the *`.dsw`* and *`.dsp`* file extensions as Visual Studio file types. To upgrade a project with these extensions, first use Visual Studio 2019 to upgrade the project to modern Solution (*`.sln`*) and C++ Project (*`.vcxproj`*) files. Then upgrade the project again using the current version of Visual Studio. + +## Visual Studio 2026 + +### Support for C++AMP, ARM32 toolchain, and `/DEBUG:FASTLINK` + +Visual Studio 2026 and later versions don't support C++AMP, the ARM32 toolchain, and /DEBUG:FASTLINK. If you're utilizing `/DEBUG:FASTLINK`, switch to [`/DEBUG:FULL`](/cpp/build/reference/debug-generate-debug-info) for improved debugging support. Developers needing to target ARM32 can continue using the Visual Studio 2022 v143 build tools as detailed in this [Microsoft blog post](https://devblogs.microsoft.com/cppblog/side-by-side-minor-version-msvc-toolsets-in-visual-studio-2019/). + +### Deprecation of `/await` + +The MSVC compiler switch `/await` is being deprecated and will be removed in a future release. This switch enabled an early draft implementation of C++ coroutines using the `` header. Developers should transition to standard C++ coroutines by using the `` header available in C++20 and later. For C++14/17 projects, use `/await:strict` (which isn't being deprecated) to access the standard `` header without enabling other C++20 features. + +### Support for Windows 7, 8, and 8.1 for Microsoft C++ Build Tools + +In Visual Studio 2026, the Microsoft C++ (MSVC) Build Tools raised the minimum supported operating system requirements. With this release, the Build Tools no longer target: + +- Windows 7 / Windows Server 2008 R2 +- Windows 8 / Windows Server 2012 +- Windows 8.1 / Windows Server 2012 R2 + +To build applications using the latest C++ tools, your target platform must be **Windows 10** or **Windows Server 2016** (or later). + +These changes allow for better performance, enhanced security, and alignment with the most recent Windows platform capabilities. + +### Support for Mobile development with C++ and Embedded and IoT tools + +Starting with Visual Studio 2026 (version 18.0), the **Mobile development with C++** workload for iOS and Android targeting in the Visual Studio installer and the **Embedded and IoT tools**--including RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import--are no longer supported and will be removed in a future update. However, the Android NDKs listed in the Mobile development with C++ workload continue to be supported. diff --git a/docs/porting/fix-your-dependencies-on-library-internals.md b/docs/porting/fix-your-dependencies-on-library-internals.md index da55c80f3cb..432dff02a01 100644 --- a/docs/porting/fix-your-dependencies-on-library-internals.md +++ b/docs/porting/fix-your-dependencies-on-library-internals.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Fix your dependencies on C++ library internals" title: "Fix your dependencies on C++ library internals" -ms.date: "05/24/2017" +description: "Learn more about: Fix your dependencies on C++ library internals" +ms.date: 05/24/2017 helpviewer_keywords: ["library internals in an upgraded Visual Studio C++ project", "_Hash_seq in an upgraded Visual Studio C++ project"] -ms.assetid: 493e0452-6ecb-4edc-ae20-b6fce2d7d3c5 --- # Fix your dependencies on C++ library internals @@ -13,13 +12,13 @@ In most cases, the What's New or Breaking Changes document for each release of V ## _Hash_seq -The internal hash function `std::_Hash_seq(const unsigned char *, size_t)`, used to implement `std::hash` on some string types, was visible in recent versions of the Standard Library. This function implemented an [FNV-1a hash]( https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) on a character sequence. +The internal hash function `std::_Hash_seq(const unsigned char *, size_t)`, used to implement `std::hash` on some string types, was visible in recent versions of the Standard Library. This function implemented an [FNV-1a hash](https://en.wikipedia.org/wiki/Fowler%E2%80%93Noll%E2%80%93Vo_hash_function) on a character sequence. To remove this dependency, you have a couple of options. - If your intent is to put a `const char *` sequence into an unordered container by using the same hash code machinery as `basic_string`, you can do that by using the `std::hash` template overload that takes a `std::string_view`, which returns that hash code in a portable way. The string library code may or may not rely on use of an FNV-1a hash in the future, so this is the best way to avoid a dependency on a particular hash algorithm. -- If your intent is to generate an FNV-1a hash over arbitrary memory, we've made that code available on GitHub in the [VCSamples]( https://github.com/Microsoft/vcsamples) repository in a stand-alone header file, [fnv1a.hpp](https://github.com/Microsoft/VCSamples/tree/master/VC2015Samples/_Hash_seq), under an [MIT license](https://github.com/Microsoft/VCSamples/blob/master/license.txt). We've also included a copy here for your convenience. You can copy this code into a header file, add the header to any affected code, and then find and replace `_Hash_seq` by `fnv1a_hash_bytes`. You'll get identical behavior to the internal implementation in `_Hash_seq`. +- If your intent is to generate an FNV-1a hash over arbitrary memory, we've made that code available on GitHub in the [VCSamples](https://github.com/Microsoft/vcsamples) repository in a stand-alone header file, [fnv1a.hpp](https://github.com/Microsoft/VCSamples/tree/master/VC2015Samples/_Hash_seq), under an [MIT license](https://github.com/Microsoft/VCSamples/blob/master/license.txt). We've also included a copy here for your convenience. You can copy this code into a header file, add the header to any affected code, and then find and replace `_Hash_seq` by `fnv1a_hash_bytes`. You'll get identical behavior to the internal implementation in `_Hash_seq`. ```cpp /* diff --git a/docs/porting/floating-point-migration-issues.md b/docs/porting/floating-point-migration-issues.md index c35a83ae9c3..6393e435c75 100644 --- a/docs/porting/floating-point-migration-issues.md +++ b/docs/porting/floating-point-migration-issues.md @@ -2,27 +2,26 @@ description: "Learn more about: Floating-point migration issues" title: "Floating-point migration issues" ms.date: "05/17/2017" -ms.assetid: 36a1b552-2f2b-4919-bc9d-c17f42434954 --- # Floating-point migration issues -Sometimes when you upgrade your projects to a newer version of Visual Studio, you may find that the results of certain floating-point operations have changed. This generally happens for one of two reasons: Code generation changes that take better advantage of the available processor, and bug fixes or changes to the algorithms used in math functions in the C runtime library (CRT). In general, the new results are correct to within the limits specified by the language standard. Read on to find out what's changed, and if it's important, how to get the same results your functions got before. +Sometimes when you upgrade your projects to a newer version of Visual Studio, you may notice changes in the results of certain floating-point operations. This generally happens for one of two reasons: Code generation changes that take better advantage of the available processor, and bug fixes or changes to the algorithms used in math functions in the C runtime library (CRT). In general, the new results are correct to within the limits specified by the language standard. Read on to find out what's changed, and if it's important, how to get the same results your functions got before. ## New math functions and Universal CRT changes -Most CRT math functions have been available in Visual Studio for years, but starting in Visual Studio 2013, all of the functions required by ISO C99 are included. These functions are implemented to balance performance with correctness. Because producing the correctly rounded result in every case may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 unit of least precision, or *ulp*, of the correctly rounded result, though there may be cases where there is greater inaccuracy. If you were using a different math library to get these functions before, implementation differences may be responsible for the change in your results. +Most CRT math functions have been available in Visual Studio for years, but starting in Visual Studio 2013, all of the functions required by ISO C99 are included. These functions are implemented to balance performance with correctness. Because producing the correctly rounded result in every case may be prohibitively expensive, these functions are designed to efficiently produce a close approximation to the correctly rounded result. In most cases, the result produced is within +/-1 unit of least precision, or *ulp*, of the correctly rounded result, though there may be cases where there's greater inaccuracy. If you used a different math library to obtain these functions earlier, implementation differences might explain the change in your results. -When the math functions were moved to the Universal CRT in Visual Studio 2015, some new algorithms were used, and several bugs in the implementation of the functions that were new in Visual Studio 2013 were fixed. These changes can lead to detectable differences in the results of floating-point calculations that use these functions. The functions that had bug issues were erf, exp2, remainder, remquo, scalbln, and scalbn, and their float and long double variants. Other changes in Visual Studio 2015 fixed issues in preserving floating point status word and exception state information in _clear87, _clearfp, fegetenv, fesetenv, and feholdexcept functions. +When the math functions were moved to the Universal CRT in Visual Studio 2015, some new algorithms were used, and several bugs in the implementation of the functions that were new in Visual Studio 2013 were fixed. These changes can lead to detectable differences in the results of floating-point calculations that use these functions. The functions that had bug issues were `erf`, `exp2`, `remainder`, `remquo`, `scalbln`, and `scalbn`, and their float and long double variants. Other changes in Visual Studio 2015 fixed issues in preserving floating point status word and exception state information in `_clear87`, `_clearfp`, `fegetenv`, `fesetenv`, and `feholdexcept` functions. ## Processor differences and compiler flags -Many of the floating point math library functions have different implementations for different CPU architectures. For example, the 32-bit x86 CRT may have a different implementation than the 64-bit x64 CRT. In addition, some of the functions may have multiple implementations for a given CPU architecture. The most efficient implementation is selected dynamically at run-time depending on the instruction sets supported by the CPU. For example, in the 32-bit x86 CRT, some functions have both an x87 implementation and an SSE2 implementation. When running on a CPU that supports SSE2, the faster SSE2 implementation is used. When running on a CPU that does not support SSE2, the slower x87 implementation is used. You may see this when migrating old code, because the default x86 compiler architecture option changed to [/arch:SSE2](../build/reference/arch-x86.md) in Visual Studio 2012. 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 on different platforms. 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. You may see this when migrating old code, because the default x86 compiler architecture option changed to [/arch:SSE2](../build/reference/arch-x86.md) in Visual Studio 2012. 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 on different platforms. In most cases, the results are within +/-1 ulp of the correctly rounded result, but the actual results may vary across CPUs. -Code-generation correctness improvements in different floating point modes in Visual Studio can also affect the results of floating-point operations when old code is compared to new code, even when using the same compiler flags. For example, the code generated by Visual Studio 2010 when [/fp:precise](../build/reference/fp-specify-floating-point-behavior.md) (the default) or `/fp:strict` was specified may not have propagated intermediate not-a-number (NaN) values through expressions correctly. Thus, some expressions that gave a numeric result in older compilers may now correctly produce a NaN result. You may also see differences because the code optimizations enabled for `/fp:fast` now take advantage of more processor features. These optimizations can use fewer instructions, but may impact the generated results because some previously visible intermediate operations have been removed. +Code-generation improvements in various floating-point modes can also alter floating-point results when comparing old code to new code, even with identical compiler flags. For example, the code generated by Visual Studio 2010 when [/fp:precise](../build/reference/fp-specify-floating-point-behavior.md) (the default) or `/fp:strict` was specified might not propagate intermediate not-a-number (NaN) values through expressions correctly. Thus, some expressions that gave a numeric result in older compilers may now correctly produce a NaN result. You may also see differences because the code optimizations enabled for `/fp:fast` now take advantage of more processor features. These optimizations can use fewer instructions, but may impact the generated results because some previously visible intermediate operations have been removed. ## How to get identical results -In most cases, the floating-point changes in the newest compilers and libraries result in faster or more correct behavior, or both. You may even see better processor power performance when SSE2 instructions replace x87 instructions. However, if you have code that must precisely replicate the floating point behavior of an older compiler, consider using Visual Studio native multi-targeting capabilities, and build the affected project with the older toolset. For more information, see [Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md). +In most cases, the floating-point changes in the newest compilers and libraries result in faster or more correct behavior, or both. You may even see better processor power performance when SSE2 instructions replace x87 instructions. However, if you have code that must precisely replicate the floating point behavior of an older compiler, consider using Visual Studio native multi-targeting capabilities, and build the affected project with the older build tools. For more information, see [Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md). ## See also diff --git a/docs/porting/ide-tools-for-upgrading-code.md b/docs/porting/ide-tools-for-upgrading-code.md index 1ce1e805274..f94f44ac1cb 100644 --- a/docs/porting/ide-tools-for-upgrading-code.md +++ b/docs/porting/ide-tools-for-upgrading-code.md @@ -1,14 +1,14 @@ --- title: "Visual Studio IDE tools for upgrading C++ code" description: "The C++ code editor and code analysis tools in Visual Studio help you to modernize your C++ code base." -ms.date: "11/13/2019" -ms.topic: "conceptual" +ms.date: "11/06/2025" +ms.topic: "concept-article" --- # Visual Studio IDE tools for upgrading C++ code Visual Studio helps you upgrade legacy C++ code with compiler options, code analysis warnings, and editor features such as Quick Fixes, Quick Info, and the enhanced scroll bar. The term "legacy code" refers to any of these categories: -- Code that was formerly allowed by the Microsoft C++ compiler (MSVC) but never conformed to the C++ standard. +- Code that was formerly allowed by the Microsoft C++ (MSVC) compiler but never conformed to the C++ standard. To upgrade older non-conforming MSVC code, turn on the [`/permissive-`](../build/reference/permissive-standards-conformance.md) compiler option. All instances of non-conforming usages are underlined with red squiggles in the code editor. The error messages in the **Error List** window include a recommendation for how to fix the error. Click on the error code to go to its help page in the documentation. If fixing all the errors at once is impractical, you can upgrade non-conforming code in stages by turning on the **`/permissive-`** option, fixing some errors, then turning the option off again. The code will compile with the new improvements, and you can go back and fix the remaining issues at a later time. See the [`/permissive-`](../build/reference/permissive-standards-conformance.md) page for examples of non-conforming MSVC code. @@ -22,19 +22,15 @@ Visual Studio helps you upgrade legacy C++ code with compiler options, code anal ## Open and convert a legacy project -If your legacy project is based on an older version of Visual Studio, you can open it in Visual Studio 2017 or Visual Studio 2019. Visual Studio automatically converts it to the current project schema with support for all the latest compiler and IDE features. +If your legacy projects are based on an older version of Visual Studio, you can still load them in a newer version and work on it there while maintaining backwards compatibility with the older version. When you are ready to permanently move to the new version of Visual Studio, you can retarget your projects. This will enable you to use the latest build tools and project features in the IDE, but you will no longer be able to load the retargeted projects in the older version of Visual Studio. -![Screenshot of the Upgrade a project dialog.](media/upgrade-dialog-v142.png "Upgrade a project") +To retarget projects to the Visual Studio 2026 format, you can use the setup assistant which appears the first time you open a solution containing older projects. You can also access it by right-clicking the solution in **Solution Explorer** and selecting **Retarget solution**. -For more information, see [Upgrade C++ projects from earlier versions of Visual Studio](upgrading-projects-from-earlier-versions-of-visual-cpp.md). - -## Search the code base +![Screenshot of the Visual Studio 2026 setup assistant showing a list of projects selected for retargeting to the latest MSVC Build Tools and v145 Platform Toolset.](media/vs-2026-setup-assistant.png "Upgrade projects") -Upgrading a code base often involves searching through multiple files. To search for anything in your code base, press **Ctrl+T** to bring up the **Go to All** search box. +The setup assistant then gives you the choice to either stay on the older version and install any missing build tools or Windows SDKs necessary to build, or retarget the projects to upgrade them. You can make retargeting selections for each project in the solution or select **Retarget all** > **Apply** to upgrade. -![Screenshot of the Go to all dialog.](media/go-to-all.png "Go to all") - -To narrow the search scope, type one of the 1-letter filters, followed by a space and then the thing you are looking for. +For more information, see [Upgrade C++ projects from earlier versions of Visual Studio](upgrading-projects-from-earlier-versions-of-visual-cpp.md). ## Error List diff --git a/docs/porting/introduction-to-visual-cpp-for-unix-users.md b/docs/porting/introduction-to-visual-cpp-for-unix-users.md index 87dc4245886..e70d60b5806 100644 --- a/docs/porting/introduction-to-visual-cpp-for-unix-users.md +++ b/docs/porting/introduction-to-visual-cpp-for-unix-users.md @@ -3,12 +3,15 @@ description: "Learn more about: Introduction to Microsoft C++ for UNIX Users" title: "Introduction to Microsoft C++ for UNIX Users" ms.date: 06/22/2021 helpviewer_keywords: ["UNIX [C++]"] -ms.assetid: 36108b31-e7fa-49a8-a1f7-7077fcbec873 +ms.topic: concept-article --- # Introduction to Microsoft C++ for UNIX Users This topic provides information for users of all flavors of UNIX who are new to Visual Studio and want to become productive with C++ either from the command line or by using Visual Studio. You can use Visual Studio with the Microsoft C++ compiler to target Windows. You can also use the Visual Studio IDE with GCC or Clang in UNIX environments such as remote Linux machines, MinGW-w64, and Windows Subsystem for Linux. To use C++ in Visual Studio, the **Desktop Development with C++** workload must be installed. Open the Visual Studio Installer to install the workload or add or remove optional components. Also install the **Linux Development with C++** workload if you'll be targeting a remote Linux machine. For Android or iOS development, install the **Mobile Development with C++** workload. +> [!IMPORTANT] +> Starting with Visual Studio 2026 (version 18.0), the Mobile development with C++ workload for iOS and Android, as well as the Embedded and IoT tools (RTOS Viewer, Serial Monitor, Peripheral Viewer, and ST Project Import), are no longer supported and will be removed in a future update. The Android NDKs included in the Mobile development with C++ workload remain supported. + ## Getting started on the command line You can use the Microsoft C++ compiler from the command line in a similar way that you would use a UNIX command-line environment. You compile from the command prompt by using the command-line C and C++ compiler (CL.EXE), linker (LINK.EXE), and other tools, including NMAKE.EXE, the Microsoft version of the UNIX make utility. diff --git a/docs/porting/media/app-modernization-cmake-ice-breaker.png b/docs/porting/media/app-modernization-cmake-ice-breaker.png new file mode 100644 index 00000000000..676e21dbbc5 Binary files /dev/null and b/docs/porting/media/app-modernization-cmake-ice-breaker.png differ diff --git a/docs/porting/media/app-modernization-msbuild-ice-breaker.png b/docs/porting/media/app-modernization-msbuild-ice-breaker.png new file mode 100644 index 00000000000..0820fec37c1 Binary files /dev/null and b/docs/porting/media/app-modernization-msbuild-ice-breaker.png differ diff --git a/docs/porting/media/copilot-app-modernization-context-menu.png b/docs/porting/media/copilot-app-modernization-context-menu.png new file mode 100644 index 00000000000..9b671eadc33 Binary files /dev/null and b/docs/porting/media/copilot-app-modernization-context-menu.png differ diff --git a/docs/porting/media/enable-copilot-app-modernization-cpp.png b/docs/porting/media/enable-copilot-app-modernization-cpp.png new file mode 100644 index 00000000000..2a9c9601913 Binary files /dev/null and b/docs/porting/media/enable-copilot-app-modernization-cpp.png differ diff --git a/docs/porting/media/upgrade-cpp.png b/docs/porting/media/upgrade-cpp.png new file mode 100644 index 00000000000..02870caa060 Binary files /dev/null and b/docs/porting/media/upgrade-cpp.png differ diff --git a/docs/porting/media/vs-2026-setup-assistant.png b/docs/porting/media/vs-2026-setup-assistant.png new file mode 100644 index 00000000000..85fe9817386 Binary files /dev/null and b/docs/porting/media/vs-2026-setup-assistant.png differ diff --git a/docs/porting/modifying-winver-and-win32-winnt.md b/docs/porting/modifying-winver-and-win32-winnt.md index 6c6e1fe1556..79fb1051490 100644 --- a/docs/porting/modifying-winver-and-win32-winnt.md +++ b/docs/porting/modifying-winver-and-win32-winnt.md @@ -4,10 +4,11 @@ description: "When and how to update WINVER and _WIN32_WINNT macros in upgraded ms.date: "06/19/2020" helpviewer_keywords: ["WINVER in an upgraded Visual Studio C++ project", "_WIN32_WINNT in an upgraded Visual Studio C++ project"] ms.assetid: 6a1f1d66-ae0e-48a7-81c3-524d8e8f3447 +ms.topic: how-to --- # Update WINVER and _WIN32_WINNT -When you use the Windows SDK, you can specify which versions of Windows your code can run on. The preprocessor macros **WINVER** and **_WIN32_WINNT** specify the minimum operating system version your code supports. Visual Studio and the Microsoft C++ compiler support targeting Windows 7 SP1 and later. Older toolsets include support for Windows XP SP2, Windows Server 2003 SP1, Vista, and Windows Server 2008. Windows 95, Windows 98, Windows ME, Windows NT, and Windows 2000 are unsupported. +When you use the Windows SDK, you can specify which versions of Windows your code can run on. The preprocessor macros **WINVER** and **_WIN32_WINNT** specify the minimum operating system version your code supports. Visual Studio and the Microsoft C++ compiler support targeting Windows 7 SP1 and later. Older build tools include support for Windows XP SP2, Windows Server 2003 SP1, Vista, and Windows Server 2008. Windows 95, Windows 98, Windows ME, Windows NT, and Windows 2000 are unsupported. When you upgrade an older project, you may need to update your **WINVER** or **_WIN32_WINNT** macros. If they're assigned values for an unsupported version of Windows, you may see compilation errors related to these macros. diff --git a/docs/porting/overview-of-potential-upgrade-issues-visual-cpp.md b/docs/porting/overview-of-potential-upgrade-issues-visual-cpp.md index d6167c1c635..49014006de0 100644 --- a/docs/porting/overview-of-potential-upgrade-issues-visual-cpp.md +++ b/docs/porting/overview-of-potential-upgrade-issues-visual-cpp.md @@ -1,40 +1,41 @@ --- -description: "Learn more about: Overview of potential upgrade issues (Visual C++)" -title: "Overview of potential upgrade issues (Visual C++)" -ms.date: 10/22/2021 +description: "Learn more about: Overview of potential upgrade issues (Microsoft C++)" +title: "Overview of potential upgrade issues (Microsoft C++)" +ms.date: 10/29/2025 ms.assetid: 2c99a8cb-098f-4a9d-bf2c-b80fd06ace43 +ms.topic: upgrade-and-migration-article --- -# Overview of potential upgrade issues (Visual C++) +# Overview of potential upgrade issues (Microsoft C++) -Over the years, the Microsoft C++ compiler has undergone many changes, along with changes in the C++ language itself, the C++ Standard Library, the C runtime (CRT), and other libraries such as MFC and ATL. As a result, when you upgrade an application from an earlier version of Visual Studio you might see compiler and linker errors and warnings in code that previously compiled cleanly. The older the original code base, the greater the potential for such errors. This overview summarizes the most common classes of issues you're likely to see, and provides links to more detailed information. +Over the years, the Microsoft C++ (MSVC) compiler has undergone many changes, along with changes in the C++ language itself, the C++ Standard Library (STL), the C runtime (CRT), and other libraries such as MFC and ATL. As a result, when you upgrade an application from an earlier version of Visual Studio you might see compiler and linker errors and warnings in code that previously compiled cleanly. The older the original code base, the greater the potential for such errors. This overview summarizes the most common classes of issues you're likely to see, and provides links to more detailed information. > [!NOTE] > In the past, we've recommended that upgrades that span several versions of Visual Studio should be performed incrementally one version at a time. We no longer recommend this approach. We've found that it's almost always simpler to upgrade to the most current version of Visual Studio no matter how old the code base. Questions or comments about the upgrade process can be sent to vcupgrade@microsoft.com. -## Library and toolset dependencies +## Library and build tools dependencies > [!NOTE] -> This section applies to applications and libraries built with Visual Studio 2013 and earlier. The toolsets used in Visual Studio 2015, Visual Studio 2017 and Visual Studio 2019 are binary compatible. For more information, see [C++ Binary Compatibility between Visual Studio versions](binary-compat-2015-2017.md). +> This section applies to applications and libraries built with Visual Studio 2013 and earlier. The build tools used in Visual Studio 2015, Visual Studio 2017 and Visual Studio 2019 are binary compatible. For more information, see [C++ Binary Compatibility between Visual Studio versions](binary-compat-2015-2017.md). When you upgrade an app from Visual Studio 2013 or before to a newer version, it's often both advisable and necessary to upgrade all libraries and DLLs the app links to. Either you must have access to the source code, or the library vendor must provide new binary files compiled with the same major version of the compiler. If one of these conditions is true, then you can skip this section, which deals with the details of binary compatibility. If neither is the case, then the libraries might not work in your upgraded app. The information in this section will help you understand whether you can continue with the upgrade. -### Toolset +### Build tools -The *`.obj`* and *`.lib`* file formats are well defined and rarely change. Sometimes additions are made to these file formats, but these additions generally don't affect the ability of newer toolsets to consume object files and libraries produced by older toolsets. The major exception is if you compile using [`/GL` (Whole Program Optimization)](../build/reference/gl-whole-program-optimization.md). If you compile using `/GL`, you can only link the resulting object file by using the same toolset that was used to produce it. So, if you produce an object file with `/GL` and use a Visual Studio 2017 (v141) compiler, you must link it using the Visual Studio 2017 (v141) linker. It's because the internal data structures within the object files aren't stable across major versions of the toolset. Newer toolsets don't understand the older data formats. +The *`.obj`* and *`.lib`* file formats are well defined and rarely change. Sometimes additions are made to these file formats, but these additions generally don't affect the ability of newer build tools to consume object files and libraries produced by older build tools. The major exception is if you compile using [`/GL` (Whole Program Optimization)](../build/reference/gl-whole-program-optimization.md). If you compile using `/GL`, you can only link the resulting object file by using the same build tools that were used to produce it. So, if you produce an object file with `/GL` and use a Visual Studio 2017 (v141) compiler, you must link it using the Visual Studio 2017 (v141) linker. It's because the internal data structures within the object files aren't stable across major versions of the build tools. Newer build tools don't understand the older data formats. -C++ doesn't have a stable application binary interface (ABI). But Visual Studio maintains a stable C++ ABI for all minor versions of a release. Visual Studio 2015 (v140), Visual Studio 2017 (v141), Visual Studio 2019 (v142), and Visual Studio 2022 (v143) toolsets vary only in their minor version. They all have the same major version number, which is 14. For more information, see [C++ Binary Compatibility between Visual Studio versions](binary-compat-2015-2017.md). +C++ doesn't have a stable application binary interface (ABI). But Visual Studio maintains a stable C++ ABI for all minor versions of a release. Visual Studio 2015 (v140), Visual Studio 2017 (v141), Visual Studio 2019 (v142), Visual Studio 2022 (v143), and Visual Studio 2026 (v145) build tools vary only in their minor version. They all have the same major version number, which is 14. For more information, see [C++ Binary Compatibility between Visual Studio versions](binary-compat-2015-2017.md). -If you have an object file that has external symbols with C++ linkage, that object file may not link correctly with object files produced by a different major version of the toolset. There are many possible outcomes: the link might fail entirely (for example, if name decoration changed). The link could succeed, but the app could fail at runtime (for example, if type layouts changed). Or your app might continue to work and nothing will go wrong. Also note, while the C++ ABI isn't stable, the C ABI and the subset of the C++ ABI required for COM are stable. +If you have an object file that has external symbols with C++ linkage, that object file may not link correctly with object files produced by a different major version of the build tools. There are many possible outcomes: the link might fail entirely (for example, if name decoration changed). The link could succeed, but the app could fail at runtime (for example, if type layouts changed). Or your app might continue to work and nothing will go wrong. Also note, while the C++ ABI isn't stable, the C ABI and the subset of the C++ ABI required for COM are stable. -If you link to an import library, any later version of the Visual Studio redistributable libraries that preserve ABI compatibility may be used at runtime. For example, if you compile and link your app by using the Visual Studio 2015 Update 3 toolset, you can use any later redistributable. That's because the 2015, 2017, 2019, and 2022 libraries have preserved backward binary compatibility. The reverse isn't true: You can't use a redistributable for an earlier version of the toolset than you used to build any component of your code. +If you link to an import library, any later version of the Visual Studio redistributable libraries that preserve ABI compatibility may be used at runtime. For example, if you compile and link your app by using the Visual Studio 2015 Update 3 build tools, you can use any later redistributable. That's because the 2015, 2017, 2019, 2022, and 2026 libraries have preserved backward binary compatibility. The reverse isn't true: You can't use a redistributable for an earlier version of the build tools than you used to build any component of your code. ### Libraries If you `#include` a particular version of the header files, you must link the resulting object file to the same version of the libraries. So, for example, if your source file includes the Visual Studio 2015 Update 3 ``, you must link with the Visual Studio 2015 Update 3 *`vcruntime`* library. Similarly, if your source file includes the Visual Studio 2017 version 15.5 ``, you must link with the Visual Studio 2017 version 15.5 Standard C++ library, *`msvcprt`*. Mixing-and-matching isn't supported. -For the C++ Standard Library, mixing-and-matching has been explicitly disallowed by use of `#pragma detect_mismatch` in the standard headers since Visual Studio 2010. If you try to link incompatible object files, or if you link with the wrong standard library, the link fails. +For the Microsoft C++ Standard Library (STL), mixing-and-matching has been explicitly disallowed by use of `#pragma detect_mismatch` in the standard headers since Visual Studio 2010. If you try to link incompatible object files, or if you link with the wrong standard library, the link fails. Older CRT version mixing-and-matching was never supported, but it often just worked because the API surface didn't change much over time. The Universal CRT broke backwards compatibility so that in the future we can maintain backwards compatibility. We have no plans to introduce new, versioned Universal CRT binaries in the future. Instead, the existing Universal CRT is now updated in-place. @@ -46,7 +47,7 @@ If you have a static library built by using an older version of the C Runtime he 1. If you can't (or don't want to) rebuild the static library, you may try linking with *`legacy_stdio_definitions.lib`*. If it satisfies the link-time dependencies of your static library, you'll want to thoroughly test the static library as it's used in the binary. Make sure it isn't adversely affected by any of the [behavioral changes that were made to the Universal CRT](visual-cpp-change-history-2003-2015.md#BK_CRT). -1. Perhaps your static library's dependencies aren't satisfied by *`legacy_stdio_definitions.lib`* or the library doesn't work with the Universal CRT because of behavior changes. In this case, we recommend you encapsulate your static library into a DLL that you link with the required version of the Microsoft C Runtime. For example, if the static library was built using Visual Studio 2013, build this DLL using the Visual Studio 2013 toolset and C++ libraries as well. By building the library into a DLL, you encapsulate the implementation detail that is its dependency on a particular version of the Microsoft C Runtime. Be careful the DLL interface doesn't leak details of which C Runtime it uses, for example, if it returns a `FILE*` across the DLL boundary, or a `malloc`-allocated pointer the caller must `free`. +1. Perhaps your static library's dependencies aren't satisfied by *`legacy_stdio_definitions.lib`* or the library doesn't work with the Universal CRT because of behavior changes. In this case, we recommend you encapsulate your static library into a DLL that you link with the required version of the Microsoft C Runtime. For example, if the static library was built using Visual Studio 2013, build this DLL using the Visual Studio 2013 build tools and C++ libraries as well. By building the library into a DLL, you encapsulate the implementation detail that is its dependency on a particular version of the Microsoft C Runtime. Be careful the DLL interface doesn't leak details of which C Runtime it uses, for example, if it returns a `FILE*` across the DLL boundary, or a `malloc`-allocated pointer the caller must `free`. Use of multiple CRTs in a single process isn't in and of itself problematic. (In fact, most processes load multiple CRT DLLs. For example, Windows operating system components depend on *`msvcrt.dll`*, and the CLR depends on its own private CRT.) Problems arise when you jumble state from different CRTs. For example, you shouldn't allocate memory using `msvcr110.dll!malloc` and attempt to deallocate that memory using `msvcr120.dll!free`, and you shouldn't attempt to open a FILE using `msvcr110!fopen` and attempt to read from that FILE using `msvcr120!fread`. As long as you don't jumble state from different CRTs, you can safely have multiple CRTs loaded in a single process. @@ -71,7 +72,7 @@ For unresolved symbols, you might need to fix up your project settings. - If the external is defined in a *`.lib`* file, have you specified the lib path in the project properties, and is the correct version of the *`.lib`* file located there? -- Are you attempting to link to a *`.lib`* file that was compiled with a different version of Visual Studio? If so, see the previous section on library and toolset dependencies. +- Are you attempting to link to a *`.lib`* file that was compiled with a different version of Visual Studio? If so, see the previous section on library and build tools dependencies. - Do the types of the arguments at the call site actually match an existing overload of the function? Verify the underlying types are what you expect, both for any typedefs in the function's signature and in the code that calls the function. @@ -154,7 +155,7 @@ Windows API documentation lists the minimum or maximum supported operating syste ### Windows version -When upgrading a program that uses the Windows API either directly or indirectly, you need to decide the minimum Windows version to support. In most cases, Windows 7 is a good choice. For more information, see [Header file problems](porting-guide-spy-increment.md#header_file_problems). The `WINVER` macro defines the oldest version of Windows that your program is designed to run on. If your MFC program sets `WINVER` to 0x0501 (Windows XP) you'll get a warning because MFC no longer supports XP, even if the compiler toolset itself has an XP mode. Compiler toolset support for Windows XP ended in Visual Studio 2017. +When upgrading a program that uses the Windows API either directly or indirectly, you need to decide the minimum Windows version to support. In most cases, Windows 7 is a good choice. For more information, see [Header file problems](porting-guide-spy-increment.md#header_file_problems). The `WINVER` macro defines the oldest version of Windows that your program is designed to run on. If your MFC program sets `WINVER` to 0x0501 (Windows XP) you'll get a warning because MFC no longer supports XP, even if the build tools have an XP mode. Build tools support for Windows XP ended in Visual Studio 2017, and support for Windows 7, 8.0 and 8.1 ended in Visual Studio 2026. For more information, see [Updating the target windows version](porting-guide-spy-increment.md#updating_winver) and [More outdated header files](porting-guide-spy-increment.md#outdated_header_files). @@ -170,15 +171,15 @@ This error can occur in MFC applications. It indicates an ordering issue between If your original code is compiled for 32-bit systems, you have the option of creating a 64-bit version instead of (or in addition to) a new 32-bit app. In general, you should get your program compiling in 32-bit mode first, and then attempt 64-bit. Compiling for 64-bit is straightforward, but in some cases it can reveal bugs that were hidden by 32-bit builds. -Also, you should be aware of possible compile-time and runtime issues relating to pointer size, time and size values, and size-specific format specifiers in `printf` and `scanf` functions. For more information, see [Configure Visual C++ for 64-bit, x64 targets](../build/configuring-programs-for-64-bit-visual-cpp.md) and [Common Visual C++ 64-bit migration issues](../build/common-visual-cpp-64-bit-migration-issues.md). For more migration tips, see [Programming guide for 64-bit Windows](/windows/win32/WinProg64/programming-guide-for-64-bit-windows). +Also, you should be aware of possible compile-time and runtime issues relating to pointer size, time and size values, and size-specific format specifiers in `printf` and `scanf` functions. For more information, see [Configure Microsoft C++ for 64-bit, x64 targets](../build/configuring-programs-for-64-bit-visual-cpp.md) and [Common Microsoft C++ 64-bit migration issues](../build/common-visual-cpp-64-bit-migration-issues.md). For more migration tips, see [Programming guide for 64-bit Windows](/windows/win32/WinProg64/programming-guide-for-64-bit-windows). ## Unicode vs MBCS/ASCII Before Unicode was standardized, many programs used the Multibyte Character Set (MBCS) to represent characters that weren't included in the ASCII character set. In older MFC projects, MBCS was the default setting. When you upgrade such a program, you'll see warnings that advise to use Unicode instead. If you decide the conversion to Unicode isn't worth the development cost, you may choose to disable or ignore the warning. To disable it for all projects in your solution, open **View** > **Property Manager**, select all projects for which you want to disable the warning, then right-click on the selected items and choose **Properties**. In the **Property Pages** dialog, select **Configuration Properties** > **C/C++** > **Advanced**. In the **Disable Specific Warnings** property, open the drop-down arrow, and then choose **Edit**. Enter 4996 into the text box. (Don't include the 'C' prefix.) Choose **OK** to save the property, then choose **OK** to save your changes. -For more information, see [Porting from MBCS to Unicode](porting-guide-spy-increment.md#porting_to_unicode). For general information about MBCS vs. Unicode, see [Text and Strings in Visual C++](../text/text-and-strings-in-visual-cpp.md) and [Internationalization](../c-runtime-library/internationalization.md) . +For more information, see [Porting from MBCS to Unicode](porting-guide-spy-increment.md#porting_to_unicode). For general information about MBCS vs. Unicode, see [Text and Strings in Microsoft C++](../text/text-and-strings-in-visual-cpp.md) and [Internationalization](../c-runtime-library/internationalization.md) . ## See also -[Upgrading projects from earlier versions of Visual C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)
+[Upgrading projects from earlier versions of Microsoft C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)
[C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md) diff --git a/docs/porting/porting-and-upgrading-examples-and-case-studies.md b/docs/porting/porting-and-upgrading-examples-and-case-studies.md index 84abafd2e48..d4e1d1b4855 100644 --- a/docs/porting/porting-and-upgrading-examples-and-case-studies.md +++ b/docs/porting/porting-and-upgrading-examples-and-case-studies.md @@ -3,6 +3,7 @@ description: "Learn more about: Porting and Upgrading: Examples and Case Studies title: "Porting and Upgrading: Examples and Case Studies" ms.date: "11/04/2016" ms.assetid: d48bbff9-1ea7-467f-8c8b-758601f01573 +ms.topic: concept-article --- # Porting and Upgrading: Examples and Case Studies diff --git a/docs/porting/porting-from-unix-to-win32.md b/docs/porting/porting-from-unix-to-win32.md index db38c1d6212..379d9fc43da 100644 --- a/docs/porting/porting-from-unix-to-win32.md +++ b/docs/porting/porting-from-unix-to-win32.md @@ -4,6 +4,7 @@ title: "Running Linux programs on Windows" ms.date: "07/31/2019" helpviewer_keywords: ["Linux [C++], porting to Win32"] ms.assetid: 3837e4fe-3f96-4f24-b2a1-7be94718a881 +ms.topic: concept-article --- # Running Linux programs on Windows diff --git a/docs/porting/porting-guide-com-spy.md b/docs/porting/porting-guide-com-spy.md index 787bf8c9a80..3df4ffa9163 100644 --- a/docs/porting/porting-guide-com-spy.md +++ b/docs/porting/porting-guide-com-spy.md @@ -3,6 +3,7 @@ description: "Learn more about: Porting Guide: COM Spy" title: "Porting Guide: COM Spy" ms.date: "11/04/2016" ms.assetid: 24aa0d52-4014-4acb-8052-f4e2e4bbc3bb +ms.topic: concept-article --- # Porting Guide: COM Spy diff --git a/docs/porting/porting-guide-mfc-scribble.md b/docs/porting/porting-guide-mfc-scribble.md index a2b0182ad99..8545e8fa71c 100644 --- a/docs/porting/porting-guide-mfc-scribble.md +++ b/docs/porting/porting-guide-mfc-scribble.md @@ -3,6 +3,7 @@ description: "Learn more about: Porting Guide: MFC Scribble" title: "Porting Guide: MFC Scribble" ms.date: "10/23/2019" ms.assetid: 8ddb517d-89ba-41a1-ab0d-4d2c6d9047e8 +ms.topic: concept-article --- # Porting Guide: MFC Scribble diff --git a/docs/porting/porting-guide-spy-increment.md b/docs/porting/porting-guide-spy-increment.md index 208342a0315..d216108360d 100644 --- a/docs/porting/porting-guide-spy-increment.md +++ b/docs/porting/porting-guide-spy-increment.md @@ -1,8 +1,8 @@ --- -description: "Learn more about: Porting Guide: Spy++" title: "Porting Guide: Spy++" -ms.date: "10/23/2019" -ms.assetid: e558f759-3017-48a7-95a9-b5b779d5e51d +description: "Learn more about: Porting Guide: Spy++" +ms.date: 10/23/2019 +ms.topic: concept-article --- # Porting Guide: Spy++ @@ -14,7 +14,7 @@ Spy++ is a widely used GUI diagnostic tool for the Windows desktop that provides We considered this case to be typical for porting Windows desktop applications that use MFC and the Win32 API, especially for old projects that have not been updated with each release of Visual C++ since Visual C++ 6.0. -## Step 1. Converting the project file. +## Step 1. Converting the project file The project file, two old .dsw files from Visual C++ 6.0, converted easily with no issues that require further attention. One project is the Spy++ application. The other is SpyHk, written in C, a supporting DLL. More complex projects might not upgrade as easily, as discussed [here](../porting/visual-cpp-porting-and-upgrading-guide.md). diff --git a/docs/porting/porting-third-party-libraries.md b/docs/porting/porting-third-party-libraries.md index 35c6bb06825..d4dab9694be 100644 --- a/docs/porting/porting-third-party-libraries.md +++ b/docs/porting/porting-third-party-libraries.md @@ -1,24 +1,26 @@ --- description: "Learn more about: Porting third-party libraries" title: "Porting Third-Party Libraries" -ms.date: 10/22/2021 -helpviewer_keywords: ["3rd-party libraries", "vspkg"] +ms.date: 10/29/2025 +helpviewer_keywords: ["3rd-party libraries", "vcpkg"] ms.assetid: b055ed20-8a9e-45b2-ac2a-e3d94271c009 +ms.topic: concept-article --- # Porting third-party libraries -When you upgrade a project from Visual Studio 2013 or earlier to the current version of Visual C++, you also have to upgrade any libraries that the project uses. The library and your project must be built by compatible versions and targets of the compiler toolset. If you don't have access to the library source code, and the library isn't available through vcpkg, then you must obtain an updated binary from the library vendor. For more information, see [Overview of potential upgrade issues](overview-of-potential-upgrade-issues-visual-cpp.md). +When you upgrade a project from Visual Studio 2013 or earlier to the current version of Microsoft C++ (MSVC) Build Tools, you also have to upgrade any libraries that the project uses. The library and your project must be built by compatible versions and targets of the build tools. If you don't have access to the library source code, and the library isn't available through vcpkg, then you must obtain an updated binary from the library vendor. For more information, see [Overview of potential upgrade issues](overview-of-potential-upgrade-issues-visual-cpp.md). When you upgrade an application from Visual Studio 2015 or later, it isn't necessary to upgrade dependencies because the code generated by those versions is binary-compatible. For more information, see [C++ binary compatibility between Visual Studio versions](binary-compat-2015-2017.md). ## 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 Microsoft C++ team has created a command-line tool called **[vcpkg](https://vcpkg.io)**. This tool has a searchable catalog (known as the curated registry) of many popular C/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/). You can either install [vcpkg from GitHub](https://github.com/microsoft/vcpkg/) or use the built-in version that ships with Visual Studio 2022 or later. To learn more about vcpkg, see the [vcpkg documentation](/vcpkg). ## Reporting issues -If your open-source library isn't found in the **vcpkg** catalog, you can open an issue on the [GitHub repo](https://github.com/Microsoft/vcpkg/issues). That's where the community and the Visual C++ team can see it and potentially create the port file for this library. +If your open-source library isn't found in the **vcpkg** curated registry, you can open an issue on the [GitHub repo](https://github.com/Microsoft/vcpkg/issues). That's where the community and the Microsoft C++ team can see it and potentially create the port file for this library. ## See also -[Visual C++ Porting and Upgrading Guide](visual-cpp-porting-and-upgrading-guide.md) +[Microsoft C++ Porting and Upgrading Guide](visual-cpp-porting-and-upgrading-guide.md) +[vcpkg Documentation](/vcpkg) diff --git a/docs/porting/porting-to-the-universal-windows-platform-cpp.md b/docs/porting/porting-to-the-universal-windows-platform-cpp.md index d6ac9d6883d..83aeac60192 100644 --- a/docs/porting/porting-to-the-universal-windows-platform-cpp.md +++ b/docs/porting/porting-to-the-universal-windows-platform-cpp.md @@ -3,6 +3,7 @@ description: "Learn more about: Porting to the Universal Windows Platform (C++)" title: "Porting to the Universal Windows Platform (C++)" ms.date: "10/23/2019" ms.assetid: f662d2e4-8940-418d-8109-cb76cb8f8569 +ms.topic: how-to --- # Porting to the Universal Windows Platform (C++) @@ -103,5 +104,5 @@ If you created a new UWP project using Visual Studio, you should not see this er ## See also -[Visual C++ Porting Guide](../porting/porting-to-the-universal-windows-platform-cpp.md)
+[Microsoft C++ Porting Guide](../porting/porting-to-the-universal-windows-platform-cpp.md)
[Develop apps for the Universal Windows Platform (UWP)](/visualstudio/cross-platform/develop-apps-for-the-universal-windows-platform-uwp) diff --git a/docs/porting/toc.yml b/docs/porting/toc.yml index 890de59b9b7..6f05b7a6724 100644 --- a/docs/porting/toc.yml +++ b/docs/porting/toc.yml @@ -9,6 +9,8 @@ items: href: ../porting/overview-of-potential-upgrade-issues-visual-cpp.md - name: Upgrade your code to the Universal CRT href: ../porting/upgrade-your-code-to-the-universal-crt.md + - name: Modernize your C++ project with GitHub Copilot modernization + href: ../porting/copilot-app-modernization-cpp.md - name: Update WINVER and _WIN32_WINNT href: ../porting/modifying-winver-and-win32-winnt.md - name: Fix your dependencies on library internals @@ -17,7 +19,7 @@ items: href: ../porting/floating-point-migration-issues.md - name: Use native multi-targeting in Visual Studio to build old projects href: ../porting/use-native-multi-targeting.md - - name: C++ features deprecated in Visual Studio 2019 + - name: C++ features deprecated in Visual Studio href: ../porting/features-deprecated-in-visual-studio.md - name: VCBuild vs. MSBuild href: ../porting/build-system-changes.md diff --git a/docs/porting/upgrade-your-code-to-the-universal-crt.md b/docs/porting/upgrade-your-code-to-the-universal-crt.md index 03e27d4e2a3..bebc69a3fac 100644 --- a/docs/porting/upgrade-your-code-to-the-universal-crt.md +++ b/docs/porting/upgrade-your-code-to-the-universal-crt.md @@ -1,14 +1,15 @@ --- description: "Learn more about: Upgrade your code to the Universal CRT" title: "Upgrade your code to the Universal CRT" -ms.date: 06/28/2022 +ms.date: 10/29/2025 ms.assetid: eaf34c1b-da98-4058-a059-a10db693a5ce +ms.topic: upgrade-and-migration-article --- # Upgrade your code to the Universal CRT The Microsoft C Runtime Library (CRT) was refactored in Visual Studio 2015. The Standard C Library, POSIX extensions and Microsoft-specific functions, macros, and global variables were moved into a new library, the Universal C Runtime Library (Universal CRT or UCRT). The compiler-specific components of the CRT were moved into a new vcruntime library. -The UCRT is now a Windows component, and ships as part of Windows 10 and later. The UCRT supports a stable ABI based on C calling conventions, and it conforms closely to the ISO C99 standard, with only a few exceptions. It's no longer tied to a specific version of the compiler. You can use the UCRT on any version of Windows supported by Visual Studio 2015 or Visual Studio 2017. The benefit is that you no longer need to update your builds to target a new version of the CRT with every upgrade of Visual Studio. +The UCRT is now a Windows component, and ships as part of Windows 10 and later. The UCRT supports a stable ABI based on C calling conventions, and it conforms closely to the ISO C99 standard, with only a few exceptions. It's no longer tied to a specific version of the compiler. You can use the UCRT on any version of Windows supported by Visual Studio 2015 or later. The benefit is that you no longer need to update your builds to target a new version of the CRT with every upgrade of Visual Studio. This refactoring has changed the names or locations of many CRT header files, library files, and Redistributable files, and the deployment methods required for your code. Many functions and macros in the UCRT were also added or changed to improve standards conformance. To take advantage of these changes, you must update your existing code and project build systems. @@ -24,11 +25,13 @@ The retail and debug UCRT DLLs are found in separate locations. The retail DLLs ## Where to find the standard libraries and headers -The C and C++ compiler-specific runtime support library, `vcruntime`, contains the code required to support program startup and features such as exception handling and intrinsics. The library and its header files are still found in the version-specific Microsoft Visual Studio folder in your *Program Files* or *Program files (x86)* directory. +The C and C++ compiler-specific runtime support library, `vcruntime`, contains the code required to support program startup and features such as exception handling and intrinsics. The library and its header files are still found in the version-specific Microsoft Visual Studio folder in your *Program Files* or *Program Files (x86)* directory. -In Visual Studio 2017, 2019, and 2022, the header files are found under `Microsoft Visual Studio\[year]\[edition]\VC\Tools\MSVC\[lib-version]\include`. Here, `[year]` is the version of Visual Studio, `[edition]` is the edition or nickname for Visual Studio, and `[lib-version]` is the build version of the libraries. +In Visual Studio 2017-2022, the header files are found under `Microsoft Visual Studio\[year]\[edition]\VC\Tools\MSVC\[lib-version]\include`. Here, `[year]` is the version of Visual Studio, `[edition]` is the edition or nickname for Visual Studio, and `[lib-version]` is the build version of the libraries. -The link libraries are found under `Microsoft Visual Studio\[year]\[edition]\VC\Tools\MSVC\[lib-version]\lib\[architecture]`, where `[year]` is the version of Visual Studio, `[edition]` is the edition or nickname for Visual Studio, `[lib-version]` is the build version of the libraries, and `[architecture]` is the target processor architecture. Link libraries for OneCore and Store are also found in the libraries folder. +In Visual Studio 2026, the header files are found under `Microsoft Visual Studio\[version]\[channel]\VC\Tools\MSVC\[lib-version]\include`. Here, `[version]` is the major version number, `[channel]` is Insiders or Stable (depending on your Visual Studio build), and `[lib-version]` is the build version of the libraries. + +The link libraries are found under `Microsoft Visual Studio\[version]\[edition]\VC\Tools\MSVC\[lib-version]\lib\[architecture]`, where `[version]` is the year (Visual Studio 2017 - 2022) or major version number (Visual Studio 2026 or later), `[edition]` is the edition or nickname for Visual Studio, `[lib-version]` is the build version of the libraries, and `[architecture]` is the target processor architecture. Link libraries for OneCore and Store are also found in the libraries folder. The retail and debug versions of the static library are `libvcruntime.lib` and `libvcruntimed.lib`. The dynamic link retail and debug stub libraries are `vcruntime.lib` and `vcruntimed.lib`, respectively. @@ -38,18 +41,18 @@ When you update your Visual Studio C++ projects, if you have set the project's * Because the UCRT is now a Microsoft Windows operating system component, it's included as part of the operating system in Windows 10 and later. It's available through Windows Update for older operating systems, Windows Vista through Windows 8.1. A Redistributable version is available for Windows XP. As an operating system component, UCRT updates and servicing are managed by Windows Update independently of Visual Studio and Microsoft C++ compiler versions. Because the UCRT is a Windows component, for security and ease of updates, and a smaller image size, we strongly recommend you use the Redistributable package to do central deployment of the UCRT for your app. -You can use the UCRT on any version of Windows supported by Visual Studio 2015 or later. You can redistribute it using a `vcredist` package for supported versions of Windows before Windows 10. The `vcredist` packages include the UCRT components and automatically install them on Windows operating systems that don't have them installed by default. For more information, see [Redistributing Visual C++ Files](../windows/redistributing-visual-cpp-files.md). +You can use the UCRT on any version of Windows supported by Visual Studio 2015 or later. You can redistribute it using a `vcredist` package for supported versions of Windows before Windows 10. The `vcredist` packages include the UCRT components and automatically install them on Windows operating systems that don't have them installed by default. For more information, see [Redistributing Microsoft C++ Files](../windows/redistributing-visual-cpp-files.md). -App-local deployment of the UCRT is supported, though not recommended for both performance and security reasons. The DLLs for app-local deployment of the UCRT are included as part of the Windows SDK, under the *`redist`* subdirectory. The DLLs required include `ucrtbase.dll` and a set of **APISet forwarder** DLLs named `api-ms-win-[subset].dll`. The set of DLLs required on each operating system varies, so we recommended that you include all of the DLLs when you use app-local deployment. For more information and recommendations about app-local deployment, see [Deployment in Visual C++](../windows/deployment-in-visual-cpp.md). +App-local deployment of the UCRT is supported, though not recommended for both performance and security reasons. The DLLs for app-local deployment of the UCRT are included as part of the Windows SDK, under the *`redist`* subdirectory. The DLLs required include `ucrtbase.dll` and a set of **APISet forwarder** DLLs named `api-ms-win-[subset].dll`. The set of DLLs required on each operating system varies, so we recommended that you include all of the DLLs when you use app-local deployment. For more information and recommendations about app-local deployment, see [Deployment in Microsoft C++](../windows/deployment-in-visual-cpp.md). ## Changes to the Universal CRT functions and macros -Many functions were added or updated in the UCRT to improve ISO C99 conformance, and to address code quality and security issues. In some cases, this required breaking changes to the library. Your code that compiled cleanly when using an older version of the CRT may break when you compile it using the UCRT. If so, you must change your code to take advantage of UCRT updates and features. For a detailed listing of the breaking changes and updates to the CRT found in the Universal CRT, see the [C Runtime Library (CRT)](visual-cpp-change-history-2003-2015.md#BK_CRT) section of the Visual C++ change history. It includes a list of affected headers and functions that you can use to identify the changes needed in your code. +Many functions were added or updated in the UCRT to improve ISO C99 conformance, and to address code quality and security issues. In some cases, this required breaking changes to the library. Your code that compiled cleanly when using an older version of the CRT may break when you compile it using the UCRT. If so, you must change your code to take advantage of UCRT updates and features. For a detailed listing of the breaking changes and updates to the CRT found in the Universal CRT, see the [C Runtime Library (CRT)](visual-cpp-change-history-2003-2015.md#BK_CRT) section of the Microsoft C++ change history. It includes a list of affected headers and functions that you can use to identify the changes needed in your code. ## See also -[Visual C++ porting and upgrading guide](visual-cpp-porting-and-upgrading-guide.md)\ -[Overview of potential upgrade issues (Visual C++)](overview-of-potential-upgrade-issues-visual-cpp.md)\ -[Upgrading projects from earlier versions of Visual C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)\ +[Microsoft C++ porting and upgrading guide](visual-cpp-porting-and-upgrading-guide.md)\ +[Overview of potential upgrade issues (Microsoft C++)](overview-of-potential-upgrade-issues-visual-cpp.md)\ +[Upgrading projects from earlier versions of Microsoft C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)\ [Visual C++ change history 2003 - 2015](visual-cpp-change-history-2003-2015.md)\ [C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md) diff --git a/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md b/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md index bfa7c30e343..471d6105610 100644 --- a/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md +++ b/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md @@ -1,20 +1,21 @@ --- title: "Upgrade C++ projects from earlier versions of Visual Studio" description: "How to upgrade Microsoft C++ projects from older versions of Visual Studio." -ms.date: 04/07/2022 +ms.date: 11/05/2025 helpviewer_keywords: ["32-bit code porting", "upgrading Visual C++ applications, 32-bit code"] ms.assetid: 18cdacaa-4742-43db-9e4c-2d9e73d8cc84 +ms.topic: upgrade-and-migration-article --- # Upgrade C++ projects from earlier versions of Visual Studio -To upgrade a project created in an earlier version of Visual Studio, just open the project in the latest version of Visual Studio. Visual Studio offers to upgrade the project to the current schema. +To upgrade a project created in an earlier version of Visual Studio, open the project in the latest version of Visual Studio. If you're still using an older version of Visual Studio side-by-side, you can choose not to upgrade your projects until you're ready to maintain compatibility with both versions. -If you choose **No**, the project doesn't get upgraded. For projects created in Visual Studio 2010 and later, you can still use the project in the newer version of Visual Studio. Just set your project properties to continue to target the older toolset. If you leave the older version of Visual Studio on your computer, its toolset is available in later versions. For example, if your project must continue to run on Windows XP, you can upgrade to Visual Studio 2019. You then specify the toolset as v141_xp or earlier in your project properties. For more information, see [Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md). +In Visual Studio 2026, this experience is enhanced with a setup assistant. The setup assistant offers to install missing tools using the Visual Studio installer, and to stay on an older version or retarget your projects to the latest version. You can open the setup assistant in **Solution Explorer** by right-clicking your solution and selecting **Retarget solution**. -If you choose **Yes**, then the project gets upgraded in place. It can't be converted back to the earlier version. In upgrade scenarios, that's why it's good practice to make a backup copy of the existing project and solution files. +With the setup assistant open, choose an action for each target or select **Retarget all** to set all projects at once. Then select **Apply** to complete the upgrade in place. Once your projects are retargeted, they can't be converted back to the earlier version. It's good practice to make a backup copy of the existing project and solution files before upgrading them. > [!NOTE] -> Visual Studio 2022 has deprecated support for the upgrade of project types that have *`.dsw`* or *`.dsp`* extensions. You can use an earlier version of Visual Studio, such as Visual Studio 2019, to upgrade these projects, then upgrade them in Visual Studio 2022 to use the latest tools and features of Visual Studio. +> Visual Studio 2022 and later have deprecated support for the upgrade of project types that have *`.dsw`* or *`.dsp`* extensions. You can use an earlier version of Visual Studio, such as Visual Studio 2019, to upgrade these projects, then upgrade them again in Visual Studio 2022 or later to use the latest tools and features of Visual Studio. ## Upgrade reports @@ -36,7 +37,7 @@ When you upgrade a project, you get an upgrade report. The report is also saved - Runtime errors or unexpected results because of behavior changes. -- Errors that were introduced in the tools. If you find an issue, report it to the Visual C++ team through your normal support channels or by using the [Visual Studio C++ Developer Community](https://aka.ms/feedback/report?space=62) page. +- Errors that were introduced in the tools. If you find an issue, report it to the Microsoft C++ team through your normal support channels or by using the [Visual Studio C++ Developer Community](https://aka.ms/feedback/report?space=62) page. Some upgraded projects and solutions can be built successfully without modification. However, most projects will likely require changes to both project settings and your source code. There's no single correct way to go about fixing these issues, but we recommend using a phased approach. Before you start, review [Overview of potential upgrade issues](../porting/overview-of-potential-upgrade-issues-visual-cpp.md) for more information on many kinds of common errors. @@ -56,7 +57,7 @@ Some upgraded projects and solutions can be built successfully without modificat 1. Consider other opportunities for modernizing the code. For example, replace custom data structures and algorithms with ones from the C++ standard library, or the Boost open-source library. By using standard features, you make it easier for others to maintain the code. You can be confident that this code has been well-tested and reviewed by many experts on the standards committee and the broader C++ community. -For hard-to-fix errors, you can search for solutions or post a question on [Microsoft Docs Q&A](/answers/topics/c%2B%2B.html). For problems in the C++ compiler and tools, try the [C++ Developer Community](https://aka.ms/vsfeedback/browsecpp) website. +For hard-to-fix errors, you can search for solutions or post a question on [Microsoft Learn Q&A](/answers/topics/c%2B%2B.html). For problems in the C++ compiler and tools, try the [C++ Developer Community](https://aka.ms/vsfeedback/browsecpp) website. ## In this section @@ -71,7 +72,7 @@ For hard-to-fix errors, you can search for solutions or post a question on [Micr ## See also -[What's New for Visual C++ in Visual Studio](../overview/what-s-new-for-visual-cpp-in-visual-studio.md)\ +[What's New for Microsoft C++ in Visual Studio](../overview/what-s-new-for-visual-cpp-in-visual-studio.md)\ [Visual C++ change history 2003 - 2015](../porting/visual-cpp-change-history-2003-2015.md)\ [Nonstandard Behavior](../cpp/nonstandard-behavior.md)\ [Port data applications](../data/data-access-programming-mfc-atl.md) diff --git a/docs/porting/use-native-multi-targeting.md b/docs/porting/use-native-multi-targeting.md index 280f53a6c89..6d57a353278 100644 --- a/docs/porting/use-native-multi-targeting.md +++ b/docs/porting/use-native-multi-targeting.md @@ -1,29 +1,33 @@ --- description: "Learn more about: Use native multi-targeting in Visual Studio to build old projects" title: "Use native multi-targeting in Visual Studio to build old projects" -ms.date: 02/22/2022 +ms.date: 10/29/2025 helpviewer_keywords: ["C++ native multi-targeting", "upgrading Visual C++ applications, retargeting"] ms.assetid: b115aabe-a9dc-4525-90d3-367d97ea20c9 --- # Use native multi-targeting in Visual Studio to build old projects -Normally, we recommend that you update your projects when you install the latest version of Visual Studio. The cost of updating your projects and code is often more than offset by the benefits of the new IDE, compiler, libraries, and tools. However, we know that you may not be able to update some projects. You may have binaries that are tied to older libraries or platforms that for maintenance reasons you can't upgrade. Your code may use non-standard language constructs that would break if you moved to a more recent compiler. Your code might rely on third-party libraries compiled for a specific version of Visual C++. Or you may produce libraries for others that must target a specific older version of Visual C++. +Normally, we recommend that you update your projects when you install the latest version of Visual Studio. The cost of updating your projects and code is often more than offset by the benefits of the new IDE, compiler, libraries, and tools. However, we know that you may not be able to update some projects. You may have binaries that are tied to older libraries or platforms that for maintenance reasons you can't upgrade. Your code may use non-standard language constructs that would break if you moved to a more recent compiler. Your code might rely on third-party libraries compiled for a specific version of Microsoft C++ (MSVC). Or you may produce libraries for others that must target a specific older version of MSVC. -Fortunately, you can use Visual Studio to build projects that target older compiler toolsets and libraries. If you still have the original tools installed, you don't have to upgrade a project from as far back as Visual Studio 2010 to take advantage of new features in the IDE: +Fortunately, you can use Visual Studio to build projects that target older build tools and libraries. If you still have the original tools installed, you don't have to upgrade a project from as far back as Visual Studio 2010 to take advantage of new features in the IDE: -- New C++ refactoring capabilities and editor experimental features +- New C++ refactoring capabilities and editor features - New Diagnostics tools debugger window and Error List window - Revamped breakpoints, exceptions window and new PerfTips - New code navigation and search tools -- New C++ Quick fixes and the Productivity Power Tools extensions. +- New C++ Quick fixes You can also target Visual Studio 2008 projects, but they can't be used unchanged. For details, see the **Instructions for Visual Studio 2008** section. -The latest versions of Visual Studio support native multi-targeting and round-tripping of projects. Native multi-targeting is the ability of the latest IDE to build using toolsets installed by previous versions of Visual Studio. Round-tripping is the ability of the latest IDE to load projects created by a previous IDE version without making any changes to the project. If you install the latest version of Visual Studio side-by-side with your existing version, you can use the new version of the IDE with the compiler and tools from the existing version to build your projects. Other members of your team can continue to use the projects in the older version of Visual Studio. +The latest versions of Visual Studio support native multi-targeting and round-tripping of projects. Native multi-targeting is the ability of the latest IDE to build using build tools installed by previous versions of Visual Studio. Round-tripping is the ability of the latest IDE to load projects created by a previous IDE version without making any changes to the project. If you install the latest version of Visual Studio side-by-side with your existing version, you can use the new version of the IDE with the compiler and tools from the existing version to build your projects. Other members of your team can continue to use the projects in the older version of Visual Studio. -When you use an older toolset, you can take advantage of many of the latest IDE features, but not the latest advances in the C++ compiler, libraries and build tools. For example, you won't be able to use the new language conformance improvements, new debugging and code analysis features, or get the faster build throughput of the latest toolset. There are also some IDE features that are incompatible with older toolsets. For example, type information may be missing in the Memory Profiler, and the refactoring operation **Convert to Raw string literals** generates C++11-conformant code that won't compile when you use Visual Studio 2012 or older toolsets. +When you use an older build tools version, you can take advantage of many of the latest IDE features, but not the latest advances in the C++ compiler, libraries and build tools. For example, you won't be able to use the new language conformance improvements, new debugging and code analysis features, or get the faster build throughput of the latest build tools. There are also some IDE features that are incompatible with older build tools. For example, type information may be missing in the Memory Profiler, and the refactoring operation **Convert to Raw string literals** generates C++11-conformant code that won't compile when you use Visual Studio 2012 or older build tools. -## How to use native multi-targeting in Visual Studio +## How to use native multi-targeting in Visual Studio 2026 + +Visual Studio 2026 includes a new **Setup assistant**. You can load an existing solution, and in **Solution Explorer** select **Retarget solution** to open the assistant. You can use the assistant to install missing C++ build tools (MSVC components and Windows SDKs) compatible with the projects you are loading, including tools originally shipped with older Visual Studio versions. This allows you to continue working with your existing projects without losing compatibility with your previous Visual Studio version. Later, when you are ready to fully upgrade, you can use the assistant to retarget these projects to the newest version of the IDE. + +## How to use native multi-targeting in Visual Studio 2010-2022 Once you have installed Visual Studio side-by-side with your older version, open your existing project in the new version of Visual Studio. When the project is loaded, Visual Studio asks you whether you want to upgrade it to use the latest C++ compiler and libraries. Since you want the project to keep the older compiler and libraries, choose the **Cancel** button. @@ -44,23 +48,23 @@ First, in addition to the current version of Visual Studio, you must install Vis Next, you must update your Visual Studio 2008 solution and projects to the current version of Visual Studio. We recommend you create a backup of your projects and solution files before the upgrade. To start the upgrade process, open the solution in the current version of Visual Studio. When you get the upgrade prompt, review the information presented, and then choose **OK** to start the upgrade. If the solution has more than one project, you must update each project. The wizard creates new *`.vcxproj`* project files side-by-side with the existing *`.vcproj`* files. As long as you also have a copy of the original *`.sln`* file, the upgrade has no other effect on your existing Visual Studio 2008 projects. > [!NOTE] -> The following steps apply to multi-targeting scenarios only. If you intend to permanently upgrade the project to a later toolset, then your next step is to save the project, open it in the latest version of Visual Studio, and address the build issues that appear there. +> The following steps apply to multi-targeting scenarios only. If you intend to permanently upgrade the project to a later build tools version, then your next step is to save the project, open it in the latest version of Visual Studio, and address the build issues that appear there. When the upgrade completes, if the log report has errors or warnings for any of your projects, review them carefully. The conversion from **VCBuild** to **MSBuild** can cause issues. Make sure you understand and implement any action items listed in the report. For more information on the upgrade log report and issues that may occur when converting **VCBuild** to **MSBuild**, see the [C++ Native Multi-Targeting](https://devblogs.microsoft.com/cppblog/c-native-multi-targeting/) blog post. -When the upgrade is complete and you've fixed any issues in the log file, your solution now targets the latest toolset. As the final step, change the properties for each project in the solution to use the Visual Studio 2008 toolset. With the solution loaded in the current version of Visual Studio, for each project in the solution, open the Project **Property Pages** dialog box: Right-click on the project in **Solution Explorer** and then select **Properties**. In the **Property Pages** dialog box, change the **Configuration** drop-down value to **All Configurations**. In **Configuration Properties**, select **General**, and then change **Platform Toolset** to **Visual Studio 2008 (v90)**. +When the upgrade is complete and you've fixed any issues in the log file, your solution now targets the latest build tools. As the final step, change the properties for each project in the solution to use the Visual Studio 2008 build tools. With the solution loaded in the current version of Visual Studio, for each project in the solution, open the Project **Property Pages** dialog box: Right-click on the project in **Solution Explorer** and then select **Properties**. In the **Property Pages** dialog box, change the **Configuration** drop-down value to **All Configurations**. In **Configuration Properties**, select **General**, and then change **Platform Toolset** to **Visual Studio 2008 (v90)**. After this change, the Visual Studio 2008 compiler and libraries are used to generate project binaries when you build the solution in the current version of Visual Studio. -## Install an older Visual Studio toolset +## Install older Visual Studio build tools -You may have an old Visual Studio C++ project that you can't or don't want to upgrade. To build it, you need the platform toolset version that matches your project. To get the toolset, you can install the free Visual Studio Community or Express edition of the version you need. Every version of Visual Studio from Visual Studio 2008 on can install the compiler, tools, and libraries you need to target that version from the current Visual Studio. Search the Microsoft Download Center to find and download a particular version of Visual Studio. Make sure you choose the C++ installation options during setup. After setup completes, run that version of Visual Studio to install any updates. Also check for any Windows Update changes that might be required. This update check process may need to be repeated more than once to get every update. +You may have an old Visual Studio C++ project that you can't or don't want to upgrade. To build it, you need the build tools version that matches your project. To get the build tools, you can install the free Visual Studio Community or Express edition of the version you need. Every version of Visual Studio from Visual Studio 2008 on can install the compiler, libraries, and other build tools you need to target that version from the current Visual Studio. Search the Microsoft Download Center to find and download a particular version of Visual Studio. Make sure you choose the C++ installation options during setup. After setup completes, run that version of Visual Studio to install any updates. Also check for any Windows Update changes that might be required. This update check process may need to be repeated more than once to get every update. For the currently available downloads, see [Download older Visual Studio software](https://visualstudio.microsoft.com/vs/older-downloads/). -When these products are installed, the **Platform Toolset** property drop-down in the **Property Pages** dialog box is automatically updated to show the available toolsets. You can now use the latest version of Visual Studio to build projects that use an older version of the toolset: no conversion or upgrade required. +When these products are installed, the **MSVC Build Tools Version** property drop-down in the **Property Pages** dialog box is automatically updated to show the available build tools versions. In some cases, there may also be new choices for the **Platform Toolset** property. You can now use the latest version of Visual Studio to build projects that use an older version of the build tools: no conversion or upgrade required. ## See also -[Upgrading projects from earlier versions of Visual C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)\ +[Upgrading projects from earlier versions of Microsoft C++](upgrading-projects-from-earlier-versions-of-visual-cpp.md)\ [C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md) diff --git a/docs/porting/visual-cpp-change-history-2003-2015.md b/docs/porting/visual-cpp-change-history-2003-2015.md index 41bf40e21d4..83f15d02849 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) @@ -403,7 +404,7 @@ When upgrading code from previous versions, you might also encounter compiler er In Visual Studio 2015, ongoing improvements to compiler conformance can sometimes change how the compiler understands your existing source code. As a result, you might encounter new or different errors during your build, or even behavioral differences in code that previously built and seemed to run correctly. -Fortunately, these differences have little or no impact on most of your source code. When source code or other changes are needed to address these differences, the fixes tend to be small and straight-forward. We've included many examples of previously acceptable source code that might need to be changed *(before)* and the fixes to correct them *(after)*. +Fortunately, these differences have little or no impact on most of your source code. When source code or other changes are needed to address these differences, the fixes tend to be small and straight-forward. We've included many examples of previously acceptable source code that might need to be changed *(before)* and the fixes to correct them *(after)*. Although these differences can affect your source code or other build artifacts, they don't affect binary compatibility between updates to Visual Studio versions. A *breaking change* is more severe, and can affect binary compatibility, but these kinds of binary compatibility breaks only occur between major versions of Visual Studio, for example, between Visual Studio 2013 and Visual Studio 2015. For information on the breaking changes that occurred between Visual Studio 2013 and Visual Studio 2015, see [Visual Studio 2015 Conformance Changes](#VC_2015). @@ -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: @@ -1973,7 +1974,7 @@ Although these differences can affect your source code or other build artifacts, case settings::bit0 | settings::bit1: // warning C4063 break; } - }; + } ``` Example of C4063 (after) @@ -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-porting-and-upgrading-guide.md b/docs/porting/visual-cpp-porting-and-upgrading-guide.md index a37ba527a58..64aa8a53e5e 100644 --- a/docs/porting/visual-cpp-porting-and-upgrading-guide.md +++ b/docs/porting/visual-cpp-porting-and-upgrading-guide.md @@ -1,60 +1,153 @@ --- title: "Microsoft C++ porting and upgrading guide" -description: "Upgrade Microsoft C++ code to the latest version of Visual Studio." -ms.date: 09/10/2020 -ms.assetid: f5fbcc3d-aa72-41a6-ad9a-a706af2166fb +description: "Your comprehensive hub for upgrading and modernizing Microsoft C++ code to the latest version of Visual Studio. Find tools, guides, success stories, and best practices." +ms.date: 11/06/2025 ms.topic: "overview" -ms.custom: intro-overview +ms.custom: intro-hub +author: tylermsft +ms.author: twhitney --- -# Microsoft C++ porting and upgrading guide - -This article provides a guide for upgrading Microsoft C++ code to the latest version of Visual Studio. For projects created in Visual Studio 2010 through 2017, just open the project in Visual Studio 2019. You can upgrade a Visual Studio 2008 or earlier project in two steps. Use Visual Studio 2010 to convert the project to MSBuild format first. Then open the project in Visual Studio 2019. For complete instructions, see [Upgrading C++ projects from earlier versions of Visual Studio](upgrading-projects-from-earlier-versions-of-visual-cpp.md). - -The toolsets in Visual Studio 2015, Visual Studio 2017, and Visual Studio 2019 are binary-compatible. Now you can upgrade to a more recent version of the compiler without having to upgrade your library dependencies. For more information, see [C++ binary compatibility between Visual Studio versions](binary-compat-2015-2017.md). - -When upgrading projects that use open-source libraries or are meant to run on multiple platforms, we recommended migrating to a CMake-based project. For more information, see [CMake projects in Visual Studio](../build/cmake-projects-in-visual-studio.md) - -## Reasons to upgrade C++ code - -If a legacy application is running satisfactorily, in a secure environment, and isn't under active development, there might not be much incentive to upgrade it. However, consider an upgrade in these cases: Your application requires ongoing maintenance. Or, you're doing new feature development, or making performance or security improvements. An upgrade brings these benefits: - -- The same code can run faster, because we've improved compiler optimizations. - -- Modern C++ features and programming practices eliminate many common causes of bugs, and produce code that's far easier to maintain than older C-style idioms. - -- Build times are faster, because of performance improvements in the compiler and linker. -- Better standards conformance. The [/permissive-](../build/reference/permissive-standards-conformance.md) compiler option helps you identify code that doesn't conform to the current C++ standard. The [new preprocessor](../preprocessor/preprocessor-experimental-overview.md) supports code conformance, too. - -- Better run-time security, including more secure [C Runtime library](../c-runtime-library/security-features-in-the-crt.md) features. And, compiler features such as [guard checking](../build/reference/guard-enable-guard-checks.md) and address sanitizers (new in Visual Studio 2019 version 16.4). - -## Multitargeting vs. upgrading - -Perhaps upgrading your code base to a new toolset isn't an option for you. You can still use the latest Visual Studio to build and edit projects that use older toolsets and libraries. In Visual Studio 2019, you can take advantage of features such as: - -- modern static analysis tools, including the C++ Core Guidelines checkers and Clang-Tidy, to help identify potential problems in your source code. - -- automatic formatting according to your choice of modern styles can help make legacy code much more readable. - -For more information, see [Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md). - -## In this section +# Microsoft C++ porting and upgrading guide -| Title | Description | -|--|--| -| [Upgrading C++ projects from earlier versions of Visual Studio](upgrading-projects-from-earlier-versions-of-visual-cpp.md) | How to upgrade your code base to the latest version of Visual Studio and the compiler. | -| [IDE tools for upgrading C++ code](ide-tools-for-upgrading-code.md) | Useful IDE features that help in the upgrade process. | -| [C++ binary compatibility between Visual Studio versions](binary-compat-2015-2017.md) | Consume v140 and later libraries as-is from v140 and later projects. | -| [Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md) | Use Visual Studio with older compilers and libraries. | -| [Visual C++ change history 2003 - 2015](visual-cpp-change-history-2003-2015.md) | A list of all the changes in the Microsoft C++ libraries and build tools from Visual Studio 2003 through 2015 that might require changes in your code. | -| [Visual C++ What's New 2003 through 2015](visual-cpp-what-s-new-2003-through-2015.md) | All the "what's new" information for Microsoft C++ from Visual Studio 2003 through Visual Studio 2015. | -| [Porting and Upgrading: Examples and Case Studies](porting-and-upgrading-examples-and-case-studies.md) | For this section, we ported and upgrades several samples and applications and discussed the experiences and results. These articles give you a sense of what's involved in the porting and upgrading process. Throughout the process, we discuss tips and tricks for upgrading and show how specific errors were fixed. | -| [Porting to the Universal Windows Platform](porting-to-the-universal-windows-platform-cpp.md) | Contains information about porting app code to Windows 10 and later | -| [Introduction to Visual C++ for UNIX Users](introduction-to-visual-cpp-for-unix-users.md) | Provides information for UNIX users who are new to Visual C++ and want to become productive with it. | -| [Running Linux programs on Windows](porting-from-unix-to-win32.md) | Discusses options for migrating UNIX applications to Windows. | +**Transform your legacy C++ applications with confidence.** Whether you're upgrading from Visual Studio 2008 or modernizing to take advantage of the latest C++ features, this comprehensive guide provides everything you need for a successful upgrade journey. + +:::row::: +:::column span=""::: +:::column-end::: +:::column span="2"::: +![C++ logo with an upward arrow and abstract code on a blue background suggesting improvements from upgrading.](media/upgrade-cpp.png) +:::column-end::: +:::column span=""::: +:::column-end::: +:::row-end::: + +:::row::: +:::column span="2"::: +## 🚀 Quick start + +**Most projects upgrade seamlessly:** For projects created in Visual Studio 2010-2017, simply open them in the latest Visual Studio. For Visual Studio 2008 or earlier projects, use our [two-step upgrade process](upgrading-projects-from-earlier-versions-of-visual-cpp.md). + +**Binary compatibility:** Visual Studio 2015, 2017, 2019, 2022, and 2026 build tools are binary-compatible, so you can upgrade without rebuilding library dependencies. [Learn more](binary-compat-2015-2017.md). + +**CMake projects:** For projects using open-source libraries or targeting multiple platforms, consider migrating to CMake. [Learn more](../build/cmake-projects-in-visual-studio.md). +:::column-end::: +:::column span="2"::: +## 💡 Why upgrade? + +- **🏃‍♂️ Better Performance:** Faster execution and build times +- **🔒 Enhanced Security:** Address sanitizers and security features +- **📐 Standards Compliance:** Modern C++ features and conformance +- **🛠️ Better Tools:** Advanced debugging and analysis capabilities +:::column-end::: +:::row-end::: + +## 🎯 Choose your upgrade path + +:::row::: +:::column::: +### 📋 Assess & plan +**Evaluate your current codebase and plan your strategy** + +- [🔍 Overview of potential upgrade issues](overview-of-potential-upgrade-issues-visual-cpp.md) +- [🔗 C++ binary compatibility between versions](binary-compat-2015-2017.md) +- [📜 Visual C++ change history 2003-2015](visual-cpp-change-history-2003-2015.md) +- [⚠️ Features deprecated in Visual Studio](features-deprecated-in-visual-studio.md) +- [🎯 Use native multi-targeting for old projects](use-native-multi-targeting.md) +:::column-end::: +:::column::: +### 🔧 Upgrade & modernize +**Step-by-step guides and tools for upgrading** + +- [⬆️ Upgrading C++ Projects to Visual Studio 2026](https://devblogs.microsoft.com/cppblog/upgrading-c-projects-to-visual-studio-2026/) +- [⬆️ Upgrade projects from earlier versions](upgrading-projects-from-earlier-versions-of-visual-cpp.md) +- [🤖 Upgrade with an AI agent (preview)](copilot-app-modernization-cpp.md) +- [🛠️ IDE tools for upgrading C++ code](ide-tools-for-upgrading-code.md) +- [🔄 Upgrade to Universal CRT](upgrade-your-code-to-the-universal-crt.md) +- [🔧 Update WINVER and _WIN32_WINNT](modifying-winver-and-win32-winnt.md) +- [🔗 Fix dependencies on library internals](fix-your-dependencies-on-library-internals.md) +- [📊 Floating-point migration issues](floating-point-migration-issues.md) +:::column-end::: +:::row-end::: + +:::row::: +:::column::: +### 🌐 Platform migration +**Move your applications to modern platforms** + +- [📱 Port to Universal Windows Platform](porting-to-the-universal-windows-platform-cpp.md) +- [🔗 Use existing C++ code in UWP apps](how-to-use-existing-cpp-code-in-a-universal-windows-platform-app.md) +- [🐧 Visual C++ for UNIX users](introduction-to-visual-cpp-for-unix-users.md) +- [🪟 Running Linux programs on Windows](porting-from-unix-to-win32.md) +- [📦 Port third-party libraries](porting-third-party-libraries.md) +:::column-end::: +:::column::: +### ✨ Success stories & examples +**Learn from real-world upgrade experiences** + +- [📖 Examples and case studies overview](porting-and-upgrading-examples-and-case-studies.md) +- [📝 Case study: MFC Scribble upgrade](porting-guide-mfc-scribble.md) +- [🕵️ Case study: COM Spy upgrade](porting-guide-com-spy.md) +- [🔍 Case study: Spy++ upgrade](porting-guide-spy-increment.md) +- [🏗️ VCBuild vs. MSBuild migration](build-system-changes.md) +:::column-end::: +:::row-end::: + +[📚 Read more case studies](porting-and-upgrading-examples-and-case-studies.md) + +## 🛠️ Upgrade benefits + +:::row::: +:::column span="2"::: +### Performance & optimization +- **Faster execution** with improved compiler optimizations +- **Reduced build times** through compiler and linker improvements +- **Better memory usage** with modern runtime optimizations +:::column-end::: +:::column span="2"::: +### Security & reliability +- **Enhanced security** with address sanitizers and [guard checking](../build/reference/guard-enable-guard-checks.md) +- **Secure runtime libraries** with improved [CRT security features](../c-runtime-library/security-features-in-the-crt.md)) +- **Better error detection** with static analysis tools +:::column-end::: +:::row-end::: + +:::row::: +:::column span="2"::: +### Developer experience +- **Modern IDE features** with IntelliSense improvements +- **Advanced debugging** with better visualizers and diagnostics +- **Code analysis** with Core Guidelines checkers and Clang-Tidy +:::column-end::: +:::column span="2"::: +### Standards & compatibility +- **Better C++ standards conformance** with [`/permissive-`](../build/reference/permissive-standards-conformance.md) mode +- **Modern preprocessor** for improved code conformance. [Learn more](../preprocessor/preprocessor-experimental-overview.md) +- **Cross-platform support** with CMake integration +:::column-end::: +:::row-end::: + +## 🤔 Multitargeting vs. upgrading + +**Not ready for a full upgrade?** You can still use the latest Visual Studio with older build tools and libraries: + +- ✅ **Modern static analysis tools** including C++ Core Guidelines checkers and Clang-Tidy +- ✅ **Automatic code formatting** to improve legacy code readability +- ✅ **Latest IDE features** while maintaining compatibility + +[Learn about native multi-targeting →](use-native-multi-targeting.md) + +## 🚀 Ready to start? + +1. **📊 Assess your current project** with our [upgrade issues overview](overview-of-potential-upgrade-issues-visual-cpp.md) +2. **🔄 Follow our step-by-step guide** to [upgrade from earlier versions](upgrading-projects-from-earlier-versions-of-visual-cpp.md) +3. **🛠️ Use our IDE tools** to [streamline the upgrade process](ide-tools-for-upgrading-code.md) +4. **📖 Learn from others** with our [real-world case studies](porting-and-upgrading-examples-and-case-studies.md) + +**Questions?** Join the conversation in [Microsoft Learn Q&A](/answers/topics/c%2B%2B.html) or check out the [C++ Team Blog](https://devblogs.microsoft.com/cppblog/) for the latest updates. ## See also -[C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md)
-[What's New for The C++ compiler in Visual Studio](../overview/what-s-new-for-visual-cpp-in-visual-studio.md)
-[C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md)
+[C++ in Visual Studio](../overview/visual-cpp-in-visual-studio.md)\ +[What's new for the C++ compiler in Visual Studio](../overview/what-s-new-for-visual-cpp-in-visual-studio.md)\ +[C++ conformance improvements in Visual Studio](../overview/cpp-conformance-improvements.md) \ No newline at end of file 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 e1f77ffdffd..039c2b627c3 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,8 @@ --- -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 +ms.topic: whats-new --- # Visual C++ What's New 2003 through 2015 @@ -15,7 +15,7 @@ This page gathers all the "What's New" pages for all versions of Visual C++ from In Visual Studio 2015 and later, ongoing improvements to compiler conformance can sometimes change how the compiler understands your existing source code. When this happens, you might encounter new or different errors during your build, or even behavioral differences in code that previously built and seemed to run correctly. -Fortunately, these differences have little or no impact on most of your source code and when source code or other changes are needed to address these differences, fixes are usually small and straight-forward. We've included many examples of previously-acceptable source code that might need to be changed *(before)* and the fixes to correct them *(after)*. +Fortunately, these differences have little or no impact on most of your source code and when source code or other changes are needed to address these differences, fixes are usually small and straight-forward. We've included many examples of previously-acceptable source code that might need to be changed *(before)* and the fixes to correct them *(after)*. Although these differences can affect your source code or other build artifacts, they don't affect binary compatibility between updates to Visual C++ versions. A more-severe kind of change, the *breaking change* can affect binary compatibility, but these kinds of binary compatibility breaks only occur between major versions of Visual C++. For example, between Visual C++ 2013 and Visual C++ 2015. For information on the breaking changes that occurred between Visual C++ 2013 and Visual C++ 2015, see [Visual C++ change history 2003 - 2015](../porting/visual-cpp-change-history-2003-2015.md). @@ -227,14 +227,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"; @@ -785,7 +784,7 @@ Although these differences can affect your source code or other build artifacts, case settings::bit0 | settings::bit1: // warning C4063 break; } - }; + } ``` Example of C4063 (after) @@ -2206,7 +2205,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 33cf7b507fd..546130842ed 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 17cbf84eb95..e09e8a00d50 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: 02/22/2022 +description: "Learn more about: Compiler warnings that are off by default" +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,10 +97,11 @@ 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 | +| [C4711](../error-messages/compiler-warnings/compiler-warning-level-1-c4711.md) (level 1) | function '*function*' selected for inline expansion | | [C4738](../error-messages/compiler-warnings/compiler-warning-level-3-c4738.md) (level 3) | storing 32-bit float result in memory, possible loss of performance | | [C4746](../error-messages/compiler-warnings/compiler-warning-c4746.md) | volatile access of '*expression*' is subject to /volatile:\ setting; consider using __iso_volatile_load/store intrinsic functions | | C4749 (level 4) | conditionally supported: offsetof applied to non-standard-layout type '*type*' | @@ -111,11 +113,11 @@ The following warnings are turned off by default in Visual Studio 2015 and later | [C4820](../error-messages/compiler-warnings/compiler-warning-level-4-c4820.md) (level 4) | '*bytes*' bytes padding added after construct '*member_name*' | | [C4822](../error-messages/compiler-warnings/compiler-warning-level-1-c4822.md) (level 1) | '*member*': local class member function does not have a body | | C4826 (level 2) | Conversion from '*type1*' to '*type2*' is sign-extended. This may cause unexpected runtime behavior. | -| C4837 (level 4) | trigraph detected: '??*character*' replaced by '*character*' | +| C4837 (level 4) | trigraph detected: '`??`*character*' replaced by '*character*' | | [C4841](../error-messages/compiler-warnings/c4841.md) (level 4) | non-standard extension used: compound member designator used in offsetof | | C4842 (level 4) | the result of 'offsetof' applied to a type using multiple inheritance is not guaranteed to be consistent between compiler releases | | [C4866](../error-messages/compiler-warnings/c4866.md) (level 4) | '*file*(*line-number*)' compiler may not enforce left-to-right evaluation order for call to *operator* | -| [C4868](../error-messages/compiler-warnings/compiler-warning-c4868.md) (level 4) | '_file_(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | +| [C4868](../error-messages/compiler-warnings/compiler-warning-c4868.md) (level 4) | '*file*(*line_number*)' compiler may not enforce left-to-right evaluation order in braced initialization list | | [C4905](../error-messages/compiler-warnings/compiler-warning-level-1-c4905.md) (level 1) | wide string literal cast to 'LPSTR' | | [C4906](../error-messages/compiler-warnings/compiler-warning-level-1-c4906.md) (level 1) | string literal cast to 'LPWSTR' | | [C4917](../error-messages/compiler-warnings/compiler-warning-level-1-c4917.md) (level 1) | '*declarator*': a GUID can only be associated with a class, interface, or namespace | @@ -135,15 +137,29 @@ The following warnings are turned off by default in Visual Studio 2015 and later | C5029 (level 4) | nonstandard extension used: alignment attributes in C++ apply to variables, data members and tag types only | | C5031 (level 4) | #pragma warning(pop): likely mismatch, popping warning state pushed in different file 14.1 | | C5032 (level 4) | detected #pragma warning(push) with no corresponding #pragma warning(pop) 14.1 | + +### Visual Studio 2017 and later versions + +The following warnings are turned off by default in Visual Studio 2017 and later versions: + +| Warning | Message | +|--|--| | C5034 | use of intrinsic '*intrinsic*' causes function *function-name* to be compiled as guest code 15.3 | | C5035 | use of feature '*feature*' causes function *function-name* to be compiled as guest code 15.3 | | C5036 (level 1) | varargs function pointer conversion when compiling with /hybrid:x86arm64 '*type1*' to '*type2*' 15.3 | | [C5038](../error-messages/compiler-warnings/c5038.md) (level 4) | data member '*member1*' will be initialized after data member '*member2*' 15.3 | -| C5039 (level 4) | '*function*': pointer or reference to potentially throwing function passed to extern C function under -EHc. Undefined behavior may occur if this function throws an exception. 15.5 | +| C5039 (level 4) | '*function*': pointer or reference to potentially throwing function passed to extern C function under `-EHc`. Undefined behavior may occur if this function throws an exception. 15.5 | | C5041 (level 4) | '*member-name*': out-of-line definition for constexpr static data member is not needed and is deprecated in C++17. 15.2 | | C5042 (level 3) | '*function*': function declarations at block scope cannot be specified 'inline' in standard C++; remove 'inline' specifier 15.5 | | [C5045](../error-messages/compiler-warnings/c5045.md) | Compiler will insert Spectre mitigation for memory load if /Qspectre switch specified 15.7 | -| C5052 (level 3) | Keyword '*keyword-name*' was introduced in C++*version* and requires use of the '*option*' command-line option` 16.1 | + +### Visual Studio 2019 and later versions + +The following warnings are turned off by default in Visual Studio 2019 and later versions: + +| Warning | Message | +|--|--| +| C5052 (level 3) | Keyword '*keyword-name*' was introduced in C++ *version* and requires use of the '*option*' command-line option 16.1 | | C5204 (level 3) | A class with virtual functions has non-virtual trivial destructor. 16.5 | | C5214 (level 4) | applying '*keyword*' to an operand with a volatile qualified type is deprecated in C++20 16.7 | | C5215 (level 4) | '*function-parameter*' a function parameter with a volatile qualified type is deprecated in C++20 16.7 | @@ -153,15 +169,30 @@ The following warnings are turned off by default in Visual Studio 2015 and later | C5220 (level 4) | '*member*': a non-static data member with a volatile qualified type no longer implies that
compiler generated copy/move constructors and copy/move assignment operators are not trivial 16.7 | | C5233 (level 4) | explicit lambda capture '*identifier*' is not used 16.10 | | [C5240 (level 4)](../error-messages/compiler-warnings/c5240.md) | '*attribute-name*': attribute is ignored in this syntactic position 16.10 | -| [C5243 (level 1)](../error-messages/compiler-warnings/c5247.md) | '*type-name*': using incomplete class '*class-name*' can cause potential one definition rule violation due to ABI limitation 16.10 | +| [C5243 (level 1)](../error-messages/compiler-warnings/c5243.md) | '*type-name*': using incomplete class '*class-name*' can cause potential one definition rule violation due to ABI limitation 16.10 | | C5245 (level 4) | '*function*': unreferenced function with internal linkage has been removed | | C5246 (level 1) | '*member*': the initialization of a subobject should be wrapped in braces 16.10 | | [C5247 (level 1)](../error-messages/compiler-warnings/c5247.md) | Section '*section-name*' is reserved for C++ dynamic initialization. Manually creating the section will interfere with C++ dynamic initialization and may lead to undefined behavior 16.11 | | [C5248 (level 1)](../error-messages/compiler-warnings/c5248.md) | Section '*section-name*' is reserved for C++ dynamic initialization. Variable manually put into the section may be optimized out and its order relative to compiler generated dynamic initializers is unspecified 16.11 | + +### Visual Studio 2022 and later versions + +The following warnings are turned off by default in Visual Studio 2022 and later versions: + +| Warning | Message | +|--|--| | C5249 (level 1) | '*bitfield*' of type '*enumeration_name*' has named enumerators with values that cannot be represented in the given bit field width of '*bitfield_width*'. 17.0 | | C5250 (level 3) | '*function_name*': intrinsic function not declared. 17.0 | | C5251 (level 4) | *segment-name* changed after including header 17.1 | | C5254 (level 4) | language feature 'terse static assert' requires compiler flag '/std:c++17' 17.1 | +| C5256 (level 1) | '*enumeration*': a non-defining declaration of an enumeration with a fixed underlying type is only permitted as a standalone declaration 17.2 | +| C5258 (level 4) | explicit capture of '*symbol*' is not required for this use 17.2 | +| C5259 (level 4) | '*specialized-type*': explicit specialization requires '`template <>`' 17.3 | +| [C5262](../error-messages/compiler-warnings/c5262.md) (level 1, error) | implicit fall-through occurs here; are you missing a `break` statement? Use `[[fallthrough]]` when a `break` statement is intentionally omitted between cases 17.4 | +| C5263 (level 4) | calling '`std::move`' on a temporary object prevents copy elision 17.4 | +| C5264 (level 4) | '*variable-name*': 'const' variable is not used 17.4 | +| [C5266 (level 4)](../error-messages/compiler-warnings/compiler-warning-level-4-c5266.md) | 'const' qualifier on return type has no effect 17.6 | +| [C5267](../error-messages/compiler-warnings/c5267.md) (level 4) | definition of implicit copy constructor/assignment operator for '*type*' is deprecated because it has a user-provided assignment operator/copy constructor 17.7 | 14.1 This warning is available starting in Visual Studio 2015 Update 1.\ 14.3 This warning is available starting in Visual Studio 2015 Update 3.\ @@ -177,6 +208,12 @@ The following warnings are turned off by default in Visual Studio 2015 and later 16.11 This warning is available starting in Visual Studio 2019 version 16.11.\ 17.0 This warning is available starting in Visual Studio 2022 version 17.0.\ 17.1 This warning is available starting in Visual Studio 2022 version 17.1.\ +17.2 This warning is available starting in Visual Studio 2022 version 17.2.\ +17.3 This warning is available starting in Visual Studio 2022 version 17.3.\ +17.4 This warning is available starting in Visual Studio 2022 version 17.4.\ +17.5 This warning is available starting in Visual Studio 2022 version 17.5.\ +17.6 This warning is available starting in Visual Studio 2022 version 17.6.\ +17.7 This warning is available starting in Visual Studio 2022 version 17.7.\ Perm This warning is off unless the [`/permissive-`](../build/reference/permissive-standards-conformance.md) compiler option is set. ## Warnings off by default in earlier versions diff --git a/docs/preprocessor/hash-error-directive-c-cpp.md b/docs/preprocessor/hash-error-directive-c-cpp.md index 2a5ec7bfe95..f98fd41b1fd 100644 --- a/docs/preprocessor/hash-error-directive-c-cpp.md +++ b/docs/preprocessor/hash-error-directive-c-cpp.md @@ -4,11 +4,10 @@ title: "#error directive (C/C++)" ms.date: "08/29/2019" f1_keywords: ["#error"] helpviewer_keywords: ["#error directive", "preprocessor, directives", "error directive (#error directive)"] -ms.assetid: d550a802-ff19-4347-9597-688935d23b2b --- # #error directive (C/C++) -The **#error** directive emits a user-specified error message at compile time, and then terminates the compilation. +The `#error` directive emits a user-specified error message at compile time. Then it terminates the compilation. ## Syntax @@ -26,4 +25,5 @@ The error message that this directive emits includes the *token-string* paramete ## See also -[Preprocessor directives](../preprocessor/preprocessor-directives.md) +[Preprocessor directives](../preprocessor/preprocessor-directives.md)\ +[#warning directive](../preprocessor/hash-warning-directive-c-cpp.md) 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 894ce0562fd..f05009b7f6e 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 82e80881160..83b1bc8afb5 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 170e412c402..a417e3cdc88 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/hash-warning-directive-c-cpp.md b/docs/preprocessor/hash-warning-directive-c-cpp.md new file mode 100644 index 00000000000..83c36ab7418 --- /dev/null +++ b/docs/preprocessor/hash-warning-directive-c-cpp.md @@ -0,0 +1,33 @@ +--- +description: "Learn more about: #warning directive (C/C++)" +title: "#warning directive (C/C++)" +ms.date: 10/15/2025 +f1_keywords: ["#warning"] +helpviewer_keywords: ["#warning directive", "preprocessor, directives", "warning directive (#warning directive)"] +--- +# #warning directive (C/C++) + +The **#warning** directive emits a user-specified warning message at compile time. It doesn't stop compilation. This directive is available starting in C23 and C++23. + +## Syntax + +> **#warning** *token-string* + +## Remarks + +The warning message is the *token-string* parameter. The *token-string* parameter isn't subject to macro expansion and can be optionally enclosed in quotes. + +Use this directive to inform the developer of a nonfatal issue or to communicate other important information during compilation. + +The following example shows how to use the **#warning** directive: + +```cpp +#if defined(_LEGACY_FEATURE_FLAG) +#warning "_LEGACY_FEATURE is deprecated and should not be used." +#endif +``` + +## See also + +[Preprocessor directives](../preprocessor/preprocessor-directives.md)\ +[#error directive](../preprocessor/hash-error-directive-c-cpp.md) \ No newline at end of file diff --git a/docs/preprocessor/intrinsic.md b/docs/preprocessor/intrinsic.md index f03f0cc8158..8e5aa4f007b 100644 --- a/docs/preprocessor/intrinsic.md +++ b/docs/preprocessor/intrinsic.md @@ -29,28 +29,28 @@ The following functions have intrinsic forms, and the intrinsic forms are used w [`_enable`](../intrinsics/enable.md)\ [`fabs`](../c-runtime-library/reference/fabs-fabsf-fabsl.md)\ [`_inp`](../c-runtime-library/inp-inpw-inpd.md)\ - [`_inpw`](../c-runtime-library/inp-inpw-inpd.md)\ + [`_inpw`](../c-runtime-library/inp-inpw-inpd.md) :::column-end::: :::column span=""::: [`labs`](../c-runtime-library/reference/abs-labs-llabs-abs64.md)\ [`_lrotl`](../c-runtime-library/reference/lrotl-lrotr.md)\ [`_lrotr`](../c-runtime-library/reference/lrotl-lrotr.md)\ [`memcmp`](../c-runtime-library/reference/memcmp-wmemcmp.md)\ - [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md)\ + [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) :::column-end::: :::column span=""::: [`memset`](../c-runtime-library/reference/memset-wmemset.md)\ [`_outp`](../c-runtime-library/outp-outpw-outpd.md)\ [`_outpw`](../c-runtime-library/outp-outpw-outpd.md)\ [`_rotl`](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md)\ - [`_rotr`](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md)\ + [`_rotr`](../c-runtime-library/reference/rotl-rotl64-rotr-rotr64.md) :::column-end::: :::column span=""::: [`strcat`](../c-runtime-library/reference/strcat-wcscat-mbscat.md)\ [`strcmp`](../c-runtime-library/reference/strcmp-wcscmp-mbscmp.md)\ [`strcpy`](../c-runtime-library/reference/strcpy-wcscpy-mbscpy.md)\ [`strlen`](../c-runtime-library/reference/strlen-wcslen-mbslen-mbslen-l-mbstrlen-mbstrlen-l.md)\ - [`_strset`](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md)\ + [`_strset`](../c-runtime-library/reference/strset-strset-l-wcsset-wcsset-l-mbsset-mbsset-l.md) :::column-end::: :::row-end::: @@ -84,18 +84,18 @@ These floating-point functions don't have true intrinsic forms. Instead, they ha :::row::: :::column span=""::: [`acos`](../c-runtime-library/reference/acos-acosf-acosl.md)\ - [`asin`](../c-runtime-library/reference/asin-asinf-asinl.md)\ + [`asin`](../c-runtime-library/reference/asin-asinf-asinl.md) :::column-end::: :::column span=""::: [`cosh`](../c-runtime-library/reference/cosh-coshf-coshl.md)\ - [`fmod`](../c-runtime-library/reference/fmod-fmodf.md)\ + [`fmod`](../c-runtime-library/reference/fmod-fmodf.md) :::column-end::: :::column span=""::: [`pow`](../c-runtime-library/reference/pow-powf-powl.md)\ - [`sinh`](../c-runtime-library/reference/sinh-sinhf-sinhl.md)\ + [`sinh`](../c-runtime-library/reference/sinh-sinhf-sinhl.md) :::column-end::: :::column span=""::: - [`tanh`](../c-runtime-library/reference/tanh-tanhf-tanhl.md)\ + [`tanh`](../c-runtime-library/reference/tanh-tanhf-tanhl.md) :::column-end::: :::row-end::: @@ -105,19 +105,19 @@ These floating-point functions have true intrinsic forms when you specify [`/Oi` :::column span=""::: [`atan`](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)\ [`atan2`](../c-runtime-library/reference/atan-atanf-atanl-atan2-atan2f-atan2l.md)\ - [`cos`](../c-runtime-library/reference/cos-cosf-cosl.md)\ + [`cos`](../c-runtime-library/reference/cos-cosf-cosl.md) :::column-end::: :::column span=""::: [`exp`](../c-runtime-library/reference/exp-expf.md)\ - [`log`](../c-runtime-library/reference/log-logf-log10-log10f.md)\ + [`log`](../c-runtime-library/reference/log-logf-log10-log10f.md) :::column-end::: :::column span=""::: [`log10`](../c-runtime-library/reference/log-logf-log10-log10f.md)\ - [`sin`](../c-runtime-library/reference/sin-sinf-sinl.md)\ + [`sin`](../c-runtime-library/reference/sin-sinf-sinl.md) :::column-end::: :::column span=""::: [`sqrt`](../c-runtime-library/reference/sqrt-sqrtf-sqrtl.md)\ - [`tan`](../c-runtime-library/reference/tan-tanf-tanl.md)\ + [`tan`](../c-runtime-library/reference/tan-tanf-tanl.md) :::column-end::: :::row-end::: diff --git a/docs/preprocessor/message.md b/docs/preprocessor/message.md index 038997d72b7..1eec0299a7b 100644 --- a/docs/preprocessor/message.md +++ b/docs/preprocessor/message.md @@ -42,7 +42,7 @@ The following code fragment uses the **`message`** pragma to display messages du #define STRING2(x) #x #define STRING(x) STRING2(x) -#pragma message (__FILE__ "[" STRING(__LINE__) "]: test") +#pragma message (__FILE__ "(" STRING(__LINE__) "): test") #pragma message("") ``` diff --git a/docs/preprocessor/optimize.md b/docs/preprocessor/optimize.md index ddcd04b8333..f8dd4c96252 100644 --- a/docs/preprocessor/optimize.md +++ b/docs/preprocessor/optimize.md @@ -1,7 +1,7 @@ --- description: "Learn more about: optimize pragma" title: "optimize pragma" -ms.date: 01/22/2021 +ms.date: 07/25/2025 f1_keywords: ["vc-pragma.optimize", "optimize_CPP"] helpviewer_keywords: ["pragma, optimize", "optimize pragma"] no-loc: ["pragma"] @@ -25,8 +25,8 @@ The *optimization-list* can be zero or more of the parameters shown in the follo | Parameter(s) | Type of optimization | |--------------------|--------------------------| | **`g`** | Enable global optimizations. Deprecated. For more information, see [`/Og` (Global optimizations)](../build/reference/og-global-optimizations.md). | -| **`s`** or **`t`** | Specify short or fast sequences of machine code. | -| **`y`** | Generate frame pointers on the program stack. | +| **`s`** or **`t`** | Favor short or fast sequences of machine code. | +| **`y`** | Omit frame pointers on the program stack. | These parameters are the same letters used with the [`/O`](../build/reference/o-options-optimize-code.md) compiler options. For example, the following pragma is equivalent to the **`/Os`** compiler option: diff --git a/docs/preprocessor/pack.md b/docs/preprocessor/pack.md index cd667b98791..9941cdcd092 100644 --- a/docs/preprocessor/pack.md +++ b/docs/preprocessor/pack.md @@ -1,6 +1,6 @@ --- -description: "Learn more about the pack pragma directive in Microsoft C/C++" title: "pack pragma" +description: "Learn more about the pack pragma directive in Microsoft C/C++" ms.date: 01/22/2021 f1_keywords: ["pack_CPP", "vc-pragma.pack"] helpviewer_keywords: ["pragma, pack", "pack pragma"] @@ -38,7 +38,7 @@ The statement `#pragma pack (pop, r1, 2)` is equivalent to `#pragma pack (pop, r ## Remarks -To *pack* a class is to place its members directly after each other in memory. It can mean that some or all members can be aligned on a boundary smaller than the default alignment of the target architecture. **`pack`** gives control at the data-declaration level. It differs from compiler option [`/Zp`](../build/reference/zp-struct-member-alignment.md), which only provides module-level control. **pack** takes effect at the first **`struct`**, **`union`**, or **`class`** declaration after the pragma is seen. **`pack`** has no effect on definitions. Calling **`pack`** with no arguments sets *`n`* to the value set in the compiler option **`/Zp`**. If the compiler option isn't set, the default value is 8 for x86, ARM, and ARM64. The default is 16 for x64 native. +To *pack* a class is to place its members directly after each other in memory. It can mean that some or all members can be aligned on a boundary smaller than the default alignment of the target architecture. **`pack`** gives control at the data-declaration level. It differs from compiler option [`/Zp`](../build/reference/zp-struct-member-alignment.md), which only provides module-level control. **pack** takes effect at the first **`struct`**, **`union`**, or **`class`** declaration after the pragma is seen. **`pack`** has no effect on definitions. Calling **`pack`** with no arguments sets *`n`* to the value set in the compiler option **`/Zp`**. If the compiler option isn't set, the default value is 8 for x86, ARM, and ARM64. The default is 16 for x64 native and ARM64EC. If you change the alignment of a structure, it may not use as much space in memory. However, you may see a loss of performance or even get a hardware-generated exception for unaligned access. You can modify this exception behavior by using [`SetErrorMode`](/windows/win32/api/errhandlingapi/nf-errhandlingapi-seterrormode). @@ -107,7 +107,7 @@ The following sample shows how to use the *push*, *pop*, and *show* syntax. // pop to the identifier and then set // the value of the current packing alignment: -#pragma pack(pop, r1, 2) // n = 2 , stack popped +#pragma pack(pop, r1, 2) // n = 2, stack popped #pragma pack(show) // C4810 ``` diff --git a/docs/preprocessor/predefined-macros.md b/docs/preprocessor/predefined-macros.md index 6bb493b470e..4c1b0170f87 100644 --- a/docs/preprocessor/predefined-macros.md +++ b/docs/preprocessor/predefined-macros.md @@ -2,17 +2,19 @@ title: "Predefined macros" description: "Lists and describes the Microsoft C++ compiler predefined preprocessor macros." ms.custom: "update_every_version" -ms.date: 12/09/2021 -f1_keywords: ["_ATL_VER", "__ATOM__", "__AVX__", "__AVX2__", "__AVX512BW__", "__AVX512CD__", "__AVX512DQ__", "__AVX512F__", "__AVX512VL__", "_CHAR_UNSIGNED", "__CLR_VER", "_CONTROL_FLOW_GUARD", "__COUNTER__", "__cplusplus", "__cplusplus_cli", "__cplusplus_winrt", "_CPPRTTI", "_CPPUNWIND", "__DATE__", "_DEBUG", "_DLL", "__FILE__", "__FUNCDNAME__", "__FUNCSIG__", "__FUNCTION__", "_INTEGRAL_MAX_BITS", "_ISO_VOLATILE", "_KERNEL_MODE", "__LINE__", "_M_AMD64", "_M_ARM", "_M_ARM_ARMV7VE", "_M_ARM_FP", "_M_ARM64", "_M_CEE", "_M_CEE_PURE", "_M_CEE_SAFE", "_M_FP_EXCEPT", "_M_FP_FAST", "_M_FP_PRECISE", "_M_FP_STRICT", "_M_IX86", "_M_IX86_FP", "_M_X64", "_MANAGED", "_MFC_VER", "_MSC_BUILD", "_MSC_EXTENSIONS", "_MSC_FULL_VER", "_MSC_VER", "_MSVC_LANG", "__MSVC_RUNTIME_CHECKS", "_MT", "_NATIVE_WCHAR_T_DEFINED", "_NO_SIZED_DEALLOCATION", "_OPENMP", "_PREFAST_", "_RESUMABLE_FUNCTIONS_SUPPORTED", "_RTC_CONVERSION_CHECKS_ENABLED", "__SANITIZE_ADDRESS__", "__STDC__", "__STDC_HOSTED__", "__STDC_NO_ATOMICS__", "__STDC_NO_COMPLEX__", "__STDC_NO_THREADS__", "__STDC_NO_VLA__", "__STDC_VERSION__", "__STDCPP_THREADS__", "__TIME__", "__TIMESTAMP__", "__VA_ARGS__", "_VC_NODEFAULTLIB", "_WCHAR_T_DEFINED", "_WIN32", "_WIN64", "_WINRT_DLL"] -helpviewer_keywords: ["timestamps, preprocessor macro", "cl.exe compiler, version number", "version numbers, C/C++ compiler (cl.exe)", "macros, predefined C++", "preprocessor, macros", "predefined macros", "_ATL_VER macro", "__ATOM__ macro", "__AVX__ macro", "__AVX2__ macro", "__AVX512BW__ macro", "__AVX512CD__ macro", "__AVX512DQ__ macro", "__AVX512F__ macro", "__AVX512VL__ macro", "_CHAR_UNSIGNED macro", "__CLR_VER macro", "_CONTROL_FLOW_GUARD macro", "__COUNTER__ macro", "__cplusplus macro", "__cplusplus_cli macro", "__cplusplus_winrt macro", "_CPPRTTI macro", "_CPPUNWIND macro", "__DATE__ macro", "_DEBUG macro", "_DLL macro", "__FILE__ macro", "__FUNCDNAME__ macro", "__FUNCSIG__ macro", "__FUNCTION__ macro", "_INTEGRAL_MAX_BITS macro", "_ISO_VOLATILE macro", "_KERNEL_MODE macro", "__LINE__ macro", "_M_AMD64 macro", "_M_ARM macro", "_M_ARM_ARMV7VE macro", "_M_ARM_FP macro", "_M_ARM64 macro", "_M_CEE macro", "_M_CEE_PURE macro", "_M_CEE_SAFE macro", "_M_FP_EXCEPT macro", "_M_FP_FAST macro", "_M_FP_PRECISE macro", "_M_FP_STRICT macro", "_M_IX86 macro", "_M_IX86_FP macro", "_M_X64 macro", "_MANAGED macro", "_MFC_VER macro", "_MSC_BUILD macro", "_MSC_EXTENSIONS macro", "_MSC_FULL_VER macro", "_MSC_VER macro", "_MSVC_LANG macro", "__MSVC_RUNTIME_CHECKS macro", "_MT macro", "_NATIVE_WCHAR_T_DEFINED macro", "_NO_SIZED_DEALLOCATION macro", "_OPENMP macro", "_PREFAST_ macro", "_RESUMABLE_FUNCTIONS_SUPPORTED macro", "_RTC_CONVERSION_CHECKS_ENABLED macro", "__SANITIZE_ADDRESS__ macro", "__STDC__ macro", "__STDC_HOSTED__ macro", "__STDC_NO_ATOMICS__ macro", "__STDC_NO_COMPLEX__ macro", "__STDC_NO_THREADS__ macro", "__STDC_NO_VLA__ macro", "__STDC_VERSION__ macro", "__STDCPP_THREADS__ macro", "__TIME__ macro", "__TIMESTAMP__ macro", "__VA_ARGS__ macro", "_VC_NODEFAULTLIB macro", "_WCHAR_T_DEFINED macro", "_WIN32 macro", "_WIN64 macro", "_WINRT_DLL macro", "__func__ identifier"] +ms.date: 05/12/2026 +f1_keywords: ["__APX_F__", "__ARM_ARCH", "_ATL_VER", "__ATOM__", "__AVX__", "__AVX2__", "__AVX512BW__", "__AVX512CD__", "__AVX512DQ__", "__AVX512F__", "__AVX512VL__", "__CCMP__", "__CF__", "_CHAR_UNSIGNED", "__CLR_VER", "_CONTROL_FLOW_GUARD", "__COUNTER__", "__cplusplus", "__cplusplus_cli", "__cplusplus_winrt", "_CPPRTTI", "_CPPUNWIND", "__DATE__", "_DEBUG", "_DLL", "__EGPR__", "__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", "__NDD__", "__NF__", "_NO_SIZED_DEALLOCATION", "_OPENMP", "__PPX__", "_PREFAST_", "__PUSH2POP2__", "_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", "__ZU__"] +helpviewer_keywords: ["__APX_F__ macro", "__ARM_ARCH macro", "_ATL_VER macro", "__ATOM__ macro", "__AVX__ macro", "__AVX2__ macro", "__AVX512BW__ macro", "__AVX512CD__ macro", "__AVX512DQ__ macro", "__AVX512F__ macro", "__AVX512VL__ macro", "__CCMP__ macro", "__CF__ macro", "_CHAR_UNSIGNED macro", "cl.exe compiler, version number", "__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", "__EGPR__ macro", "__FILE__ macro", "__func__ identifier", "__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", "macros, predefined C++", "_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", "__NDD__ macro", "__NF__ macro", "_NO_SIZED_DEALLOCATION macro", "_OPENMP macro", "__PPX__ macro", "predefined macros", "_PREFAST_ macro", "preprocessor, macros", "__PUSH2POP2__ 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", "timestamps, preprocessor macro", "__VA_ARGS__ macro", "_VC_NODEFAULTLIB macro", "version numbers, C/C++ compiler (cl.exe)", "_WCHAR_T_DEFINED macro", "_WIN32 macro", "_WIN64 macro", "_WINRT_DLL macro", "__ZU__ macro"] ms.assetid: 1cc5f70a-a225-469c-aed0-fe766238e23f -no-loc: [_ATL_VER, __ATOM__, __AVX__, __AVX2__, __AVX512BW__, __AVX512CD__, __AVX512DQ__, __AVX512F__, __AVX512VL__, _CHAR_UNSIGNED, __CLR_VER, _CONTROL_FLOW_GUARD, __COUNTER__, __cplusplus, __cplusplus_cli, __cplusplus_winrt, _CPPRTTI, _CPPUNWIND, __DATE__, _DEBUG, _DLL, __FILE__, __FUNCDNAME__, __FUNCSIG__, __FUNCTION__, _INTEGRAL_MAX_BITS, _ISO_VOLATILE, _KERNEL_MODE, __LINE__, _M_AMD64, _M_ARM, _M_ARM_ARMV7VE, _M_ARM_FP, _M_ARM64, _M_CEE, _M_CEE_PURE, _M_CEE_SAFE, _M_FP_EXCEPT, _M_FP_FAST, _M_FP_PRECISE, _M_FP_STRICT, _M_IX86, _M_IX86_FP, _M_X64, _MANAGED, _MFC_VER, _MSC_BUILD, _MSC_EXTENSIONS, _MSC_FULL_VER, _MSC_VER, _MSVC_LANG, __MSVC_RUNTIME_CHECKS, _MT, _NATIVE_WCHAR_T_DEFINED, _NO_SIZED_DEALLOCATION, _OPENMP, _PREFAST_, _RESUMABLE_FUNCTIONS_SUPPORTED, _RTC_CONVERSION_CHECKS_ENABLED, __SANITIZE_ADDRESS__, __STDC__, __STDC_HOSTED__, __STDC_NO_ATOMICS__, __STDC_NO_COMPLEX__, __STDC_NO_THREADS__, __STDC_NO_VLA__, __STDC_VERSION__, __STDCPP_THREADS__, __TIME__, __TIMESTAMP__, __VA_ARGS__, _VC_NODEFAULTLIB, _WCHAR_T_DEFINED, _WIN32, _WIN64, _WINRT_DLL, __func__] +no-loc: [_ATL_VER, __ATOM__, __AVX__, __AVX2__, __AVX512BW__, __AVX512CD__, __AVX512DQ__, __AVX512F__, __AVX512VL__, _CHAR_UNSIGNED, __CLR_VER, _CONTROL_FLOW_GUARD, __COUNTER__, __cplusplus, __cplusplus_cli, __cplusplus_winrt, _CPPRTTI, _CPPUNWIND, __DATE__, _DEBUG, _DLL, __FILE__, __FUNCDNAME__, __FUNCSIG__, __FUNCTION__, _INTEGRAL_MAX_BITS, _ISO_VOLATILE, _KERNEL_MODE, __LINE__, _M_AMD64, _M_ARM, _M_ARM_ARMV7VE, _M_ARM_FP, _M_ARM64, _M_ARM64EC, _M_CEE, _M_CEE_PURE, _M_CEE_SAFE, _M_FP_EXCEPT, _M_FP_FAST, _M_FP_PRECISE, _M_FP_STRICT, _M_IX86, _M_IX86_FP, _M_X64, _MANAGED, _MFC_VER, _MSC_BUILD, _MSC_EXTENSIONS, _MSC_FULL_VER, _MSC_VER, _MSVC_LANG, __MSVC_RUNTIME_CHECKS, _MT, _NATIVE_WCHAR_T_DEFINED, _NO_SIZED_DEALLOCATION, _OPENMP, _PREFAST_, _RESUMABLE_FUNCTIONS_SUPPORTED, _RTC_CONVERSION_CHECKS_ENABLED, __SANITIZE_ADDRESS__, __STDC__, __STDC_HOSTED__, __STDC_NO_ATOMICS__, __STDC_NO_COMPLEX__, __STDC_NO_THREADS__, __STDC_NO_VLA__, __STDC_VERSION__, __STDCPP_DEFAULT_NEW_ALIGNMENT__, __STDCPP_THREADS__, __TIME__, __TIMESTAMP__, __VA_ARGS__, _VC_NODEFAULTLIB, _WCHAR_T_DEFINED, _WIN32, _WIN64, _WINRT_DLL, __func__] --- # Predefined macros -The Microsoft C/C++ compiler (MSVC) predefines certain preprocessor macros, depending on the language (C or C++), the compilation target, and the chosen compiler options. +The Microsoft C/C++ compiler (MSVC) predefines certain preprocessor macros depending on the language (C or C++), the compilation target, and the chosen compiler options. -MSVC supports the predefined preprocessor macros required by the ANSI/ISO C99, C11, and C17 standards, and the ISO C++14, 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 [`/Zc:__STDC__`](../build/reference/zc-stdc.md) compiler option is specified. Otherwise, undefined. - `__STDC_HOSTED__` Defined as 1 if the implementation is a *hosted implementation*, one that supports the entire required standard library. Otherwise, defined as 0. @@ -52,29 +55,41 @@ The compiler supports these predefined macros specified by the ISO C99, C11, C17 - `__STDC_VERSION__` Defined when compiled as C and one of the **`/std`** C11 or C17 options is specified. It expands to `201112L` for [`/std:c11`](../build/reference/std-specify-language-standard-version.md), and `201710L` for [`/std:c17`](../build/reference/std-specify-language-standard-version.md). +- `__STDCPP_DEFAULT_NEW_ALIGNMENT__` When [`/std:c17`](../build/reference/std-specify-language-standard-version.md) or later is specified, this macro expands to a `size_t` literal that has the value of the alignment guaranteed by a call to alignment-unaware `operator new`. Larger alignments are passed to an alignment-aware overload, such as `operator new(std::size_t, std::align_val_t)`. For more information, see [`/Zc:alignedNew` (C++17 over-aligned allocation)](../build/reference/zc-alignednew.md). + - `__STDCPP_THREADS__` Defined as 1 if and only if a program can have more than one thread of execution, and compiled as C++. Otherwise, undefined. - `__TIME__` The time of translation of the preprocessed translation unit. The time is a character string literal of the form *hh:mm:ss*, the same as the time returned by the CRT [asctime](../c-runtime-library/reference/asctime-wasctime.md) function. This macro is always defined. ## Microsoft-specific predefined macros -MSVC supports these additional predefined macros. +MSVC supports other predefined macros: + +- `__APX_F__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + +- `__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), [`/arch:AVX10.1`](../build/reference/arch-x86.md), or [`/arch:AVX10.2`](../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) or [`/arch:AVX512`](../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), [`/arch:AVX512`](../build/reference/arch-x86.md), [`/arch:AVX10.1`](../build/reference/arch-x86.md), or [`/arch:AVX10.2`](../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. +- `__AVX512BW__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md), [`/arch:AVX10.1`](../build/reference/arch-x86.md), or [`/arch:AVX10.2`](../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. +- `__AVX512CD__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md), [`/arch:AVX10.1`](../build/reference/arch-x86.md), or [`/arch:AVX10.2`](../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. +- `__AVX512DQ__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md), [`/arch:AVX10.1`](../build/reference/arch-x86.md), or [`/arch:AVX10.2`](../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. +- `__AVX512F__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md), [`/arch:AVX10.1`](../build/reference/arch-x86.md), or [`/arch:AVX10.2`](../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. +- `__AVX512VL__` Defined as 1 when the [`/arch:AVX512`](../build/reference/arch-x86.md), [`/arch:AVX10.1`](../build/reference/arch-x86.md), or [`/arch:AVX10.2`](../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) or [`/arch:AVX10.2`](../build/reference/arch-x86.md) compiler option is set and the compiler target is x86 or x64. Otherwise, undefined. + +- `__CCMP__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + +- `__CF__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. - `_CHAR_UNSIGNED` Defined as 1 if the default **`char`** type is unsigned. This value is defined when the [**`/J`** (Default char type is unsigned)](../build/reference/j-default-char-type-is-unsigned.md) compiler option is set. Otherwise, undefined. @@ -91,7 +106,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: @@ -160,6 +175,8 @@ MSVC supports these additional predefined macros. - `_DLL` Defined as 1 when the [`/MD`](../build/reference/md-mt-ld-use-run-time-library.md) or [`/MDd`](../build/reference/md-mt-ld-use-run-time-library.md) (Multithreaded DLL) compiler option is set. Otherwise, undefined. +- `__EGPR__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + - `__FUNCDNAME__` Defined as a string literal that contains the [decorated name](../build/reference/decorated-names.md) of the enclosing function. The macro is defined only within a function. The `__FUNCDNAME__` macro isn't expanded if you use the [`/EP`](../build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md) or [`/P`](../build/reference/p-preprocess-to-a-file.md) compiler option. This example uses the `__FUNCDNAME__`, `__FUNCSIG__`, and `__FUNCTION__` macros to display function information. @@ -170,7 +187,7 @@ MSVC supports these additional predefined macros. - `__FUNCTION__` Defined as a string literal that contains the undecorated name of the enclosing function. The macro is defined only within a function. The `__FUNCTION__` macro isn't expanded if you use the [`/EP`](../build/reference/ep-preprocess-to-stdout-without-hash-line-directives.md) or [`/P`](../build/reference/p-preprocess-to-a-file.md) compiler option. For an example of usage, see the `__FUNCDNAME__` macro. -- `_INTEGRAL_MAX_BITS` Defined as the integer literal value 64, the maximum size (in bits) for a non-vector integral type. This macro is always defined. +- `_INTEGRAL_MAX_BITS` Defined as the integer literal value 64, the maximum size (in bits) for a nonvector integral type. This macro is always defined. ```cpp // integral_max_bits.cpp @@ -186,9 +203,9 @@ MSVC supports these additional predefined macros. - `_KERNEL_MODE` Defined as 1 if the [**`/kernel`** (Create Kernel Mode Binary)](../build/reference/kernel-create-kernel-mode-binary.md) compiler option is set. Otherwise, undefined. -- `_M_AMD64` Defined as the integer literal value 100 for compilations that target x64 processors. Otherwise, undefined. +- `_M_AMD64` Defined as the integer literal value 100 for compilations that target x64 processors or ARM64EC. Otherwise, undefined. -- `_M_ARM` Defined as the integer literal value 7 for compilations that target ARM processors. Otherwise, undefined. +- `_M_ARM` Defined as the integer literal value 7 for compilations that target ARM processors. Undefined for ARM64, ARM64EC, and other targets. - `_M_ARM_ARMV7VE` Defined as 1 when the [`/arch:ARMv7VE`](../build/reference/arch-arm.md) compiler option is set for compilations that target ARM processors. Otherwise, undefined. @@ -200,7 +217,9 @@ MSVC supports these additional predefined macros. - For more information, see [**`/arch`** (ARM)](../build/reference/arch-arm.md). -- `_M_ARM64` Defined as 1 for compilations that target 64-bit ARM processors. Otherwise, undefined. +- `_M_ARM64` Defined as 1 for compilations that target ARM64. Otherwise, undefined. + +- `_M_ARM64EC` Defined as 1 for compilations that target ARM64EC. Otherwise, undefined. - `_M_CEE` Defined as 001 if any [**`/clr`** (Common Language Runtime Compilation)](../build/reference/clr-common-language-runtime-compilation.md) compiler option is set. Otherwise, undefined. @@ -223,58 +242,26 @@ MSVC supports these additional predefined macros. - `_M_IX86_FP` Defined as an integer literal value that indicates the [`/arch`](../build/reference/arch-arm.md) compiler option that was set, or the default. This macro is always defined when the compilation target is an x86 processor. Otherwise, undefined. When defined, the value is: - 0 if the `/arch:IA32` compiler option was set. - - 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`, `/arch:AVX10.1`, or `/arch:AVX10.2` 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` or `/arch:AVX10.2` is specified, `__AVX__`, `__AVX2__`, `__AVX512BW__`, `__AVX512CD__`, `__AVX512DQ__`, `__AVX512F__`, `__AVX512VL__` and `__AVX10_VER__` are also defined. - For more information, see [**`/arch`** (x86)](../build/reference/arch-x86.md). -- `_M_X64` Defined as the integer literal value 100 for compilations that target x64 processors. Otherwise, undefined. +- `_M_X64` Defined as the integer literal value 100 for compilations that target x64 processors or ARM64EC. Otherwise, undefined. - `_MANAGED` Defined as 1 when the [`/clr`](../build/reference/clr-common-language-runtime-compilation.md) compiler option is set. Otherwise, undefined. -- `_MSC_BUILD` Defined as an integer literal that contains the revision number element of the compiler's version number. The revision number is the fourth element of the period-delimited version number. For example, if the version number of the Microsoft C/C++ compiler is 15.00.20706.01, the `_MSC_BUILD` macro evaluates to 1. This macro is always defined. +- `_MSC_BUILD` Defined as an integer literal that contains the revision number element of the compiler's version number. The revision number is the last element of the period-delimited version number. For example, if the version number of the Microsoft C/C++ compiler is 15.00.20706.01, the `_MSC_BUILD` macro is 1. This macro is always defined. - `_MSC_EXTENSIONS` Defined as 1 if the on-by-default [**`/Ze`** (Enable Language Extensions)](../build/reference/za-ze-disable-language-extensions.md) compiler option is set. Otherwise, undefined. -- `_MSC_FULL_VER` Defined as an integer literal that encodes the major, minor, and build number elements of the compiler's version number. The major number is the first element of the period-delimited version number, the minor number is the second element, and the build number is the third element. For example, if the version number of the Microsoft C/C++ compiler is 15.00.20706.01, the `_MSC_FULL_VER` macro evaluates to 150020706. Enter `cl /?` at the command line to view the compiler's version number. This macro is always defined. - -- `_MSC_VER` Defined as an integer literal that encodes the major and minor number elements of the compiler's version number. The major number is the first element of the period-delimited version number and the minor number is the second element. For example, if the version number of the Microsoft C/C++ compiler is 17.00.51106.1, the `_MSC_VER` macro evaluates to 1700. Enter `cl /?` at the command line to view the compiler's version number. This macro is always defined. - - | Visual Studio version | `_MSC_VER` | - |--|--| - | Visual Studio 6.0 | 1200 | - | Visual Studio .NET 2002 (7.0) | 1300 | - | Visual Studio .NET 2003 (7.1) | 1310 | - | Visual Studio 2005 (8.0) | 1400 | - | Visual Studio 2008 (9.0) | 1500 | - | Visual Studio 2010 (10.0) | 1600 | - | Visual Studio 2012 (11.0) | 1700 | - | Visual Studio 2013 (12.0) | 1800 | - | Visual Studio 2015 (14.0) | 1900 | - | Visual Studio 2017 RTW (15.0) | 1910 | - | Visual Studio 2017 version 15.3 | 1911 | - | Visual Studio 2017 version 15.5 | 1912 | - | Visual Studio 2017 version 15.6 | 1913 | - | Visual Studio 2017 version 15.7 | 1914 | - | Visual Studio 2017 version 15.8 | 1915 | - | Visual Studio 2017 version 15.9 | 1916 | - | Visual Studio 2019 RTW (16.0) | 1920 | - | Visual Studio 2019 version 16.1 | 1921 | - | Visual Studio 2019 version 16.2 | 1922 | - | Visual Studio 2019 version 16.3 | 1923 | - | Visual Studio 2019 version 16.4 | 1924 | - | Visual Studio 2019 version 16.5 | 1925 | - | Visual Studio 2019 version 16.6 | 1926 | - | Visual Studio 2019 version 16.7 | 1927 | - | Visual Studio 2019 version 16.8, 16.9 | 1928 | - | Visual Studio 2019 version 16.10, 16.11 | 1929 | - | Visual Studio 2022 RTW (17.0) | 1930 | - | 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 @@ -286,11 +273,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. @@ -308,6 +295,10 @@ MSVC supports these additional predefined macros. - `_MT` Defined as 1 when [**`/MD`** or **`/MDd`** (Multithreaded DLL)](../build/reference/md-mt-ld-use-run-time-library.md) or [**`/MT`** or **`/MTd`** (Multithreaded)](../build/reference/md-mt-ld-use-run-time-library.md) is specified. Otherwise, undefined. +- `__NDD__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + +- `__NF__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + - `_NATIVE_WCHAR_T_DEFINED` Defined as 1 when the [`/Zc:wchar_t`](../build/reference/zc-wchar-t-wchar-t-is-native-type.md) compiler option is set. Otherwise, undefined. - `_OPENMP` Defined as integer literal 200203, if the [**`/openmp`** (Enable OpenMP 2.0 Support)](../build/reference/openmp-enable-openmp-2-0-support.md) compiler option is set. This value represents the date of the OpenMP specification implemented by MSVC. Otherwise, undefined. @@ -321,8 +312,12 @@ MSVC supports these additional predefined macros. } ``` +- `__PPX__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + - `_PREFAST_` Defined as 1 when the [`/analyze`](../build/reference/analyze-code-analysis.md) compiler option is set. Otherwise, undefined. +- `__PUSH2POP2__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + - `__SANITIZE_ADDRESS__` Available beginning with Visual Studio 2019 version 16.9. Defined as 1 when the [`/fsanitize=address`](../build/reference/fsanitize.md) compiler option is set. Otherwise, undefined. - `__TIMESTAMP__` Defined as a string literal that contains the date and time of the last modification of the current source file, in the abbreviated, constant length form returned by the CRT [`asctime`](../c-runtime-library/reference/asctime-wasctime.md) function, for example, `Fri 19 Aug 13:32:58 2016`. This macro is always defined. @@ -331,17 +326,19 @@ MSVC supports these additional predefined macros. - `_WCHAR_T_DEFINED` Defined as 1 when the default [`/Zc:wchar_t`](../build/reference/zc-wchar-t-wchar-t-is-native-type.md) compiler option is set. The `_WCHAR_T_DEFINED` macro is defined but has no value if the **`/Zc:wchar_t-`** compiler option is set, and **`wchar_t`** is defined in a system header file included in your project. Otherwise, undefined. -- `_WIN32` Defined as 1 when the compilation target is 32-bit ARM, 64-bit ARM, x86, or x64. Otherwise, undefined. +- `_WIN32` Defined as 1 when the compilation target is 32-bit ARM, 64-bit ARM, x86, x64, or ARM64EC. Otherwise, undefined. -- `_WIN64` Defined as 1 when the compilation target is 64-bit ARM or x64. Otherwise, undefined. +- `_WIN64` Defined as 1 when the compilation target is 64-bit ARM, x64, or ARM64EC. Otherwise, undefined. - `_WINRT_DLL` Defined as 1 when compiled as C++ and both [**`/ZW`** (Windows Runtime Compilation)](../build/reference/zw-windows-runtime-compilation.md) and [**`/LD`** or **`/LDd`**](../build/reference/md-mt-ld-use-run-time-library.md) compiler options are set. Otherwise, undefined. +- `__ZU__` Defined as 1 when the [`/feature:APX`](../build/reference/feature-x64.md) compiler option is set and the compiler target is x64. Otherwise, undefined. + No preprocessor macros that identify the ATL or MFC library version are predefined by the compiler. ATL and MFC library headers define these version macros internally. They're undefined in preprocessor directives made before the required header is included. -- `_ATL_VER` Defined in \ as an integer literal that encodes the ATL version number. +- `_ATL_VER` Defined in `` as an integer literal that encodes the ATL version number. -- `_MFC_VER` Defined in \ as an integer literal that encodes the MFC version number. +- `_MFC_VER` Defined in `` as an integer literal that encodes the MFC version number. ## See also diff --git a/docs/preprocessor/preprocessor-directives.md b/docs/preprocessor/preprocessor-directives.md index 38d13833a81..f3c11dd326f 100644 --- a/docs/preprocessor/preprocessor-directives.md +++ b/docs/preprocessor/preprocessor-directives.md @@ -1,13 +1,12 @@ --- description: "Learn more about: Preprocessor directives" title: "Preprocessor directives" -ms.date: "08/29/2019" +ms.date: 10/15/2025 helpviewer_keywords: ["directives, preprocessor", "preprocessor, directives"] -ms.assetid: e0fc4564-b6cf-4a36-bf51-6ccd7abd0a94 --- # Preprocessor directives -Preprocessor directives, such as `#define` and `#ifdef`, are typically used to make source programs easy to change and easy to compile in different execution environments. Directives in the source file tell the preprocessor to take specific actions. For example, the preprocessor can replace tokens in the text, insert the contents of other files into the source file, or suppress compilation of part of the file by removing sections of text. Preprocessor lines are recognized and carried out before macro expansion. Therefore, if a macro expands into something that looks like a preprocessor command, it isn't recognized by the preprocessor. +Preprocessor directives, such as `#define` and `#ifdef`, are used to make source programs easy to change and compile in different execution environments. Directives in the source file tell the preprocessor to take specific actions. For example, the preprocessor can replace tokens in the text, insert the contents of other files into the source file, or suppress compilation of part of the file by removing sections of text. Preprocessor directives are processed before macro expansion. Therefore, if a macro expands into something that looks like a preprocessor command, it isn't recognized by the preprocessor. Preprocessor statements use the same character set as source file statements, with the exception that escape sequences aren't supported. The character set used in preprocessor statements is the same as the execution character set. The preprocessor also recognizes negative character values. @@ -29,7 +28,8 @@ The preprocessor recognizes the following directives: :::column span=""::: [`#import`](../preprocessor/hash-import-directive-cpp.md)\ [`#include`](../preprocessor/hash-include-directive-c-cpp.md)\ - [`#line`](../preprocessor/hash-line-directive-c-cpp.md) + [`#line`](../preprocessor/hash-line-directive-c-cpp.md)\ + [`#warning`](../preprocessor/hash-warning-directive-c-cpp.md) :::column-end::: :::column span=""::: [`#pragma`](../preprocessor/pragma-directives-and-the-pragma-keyword.md)\ diff --git a/docs/preprocessor/setlocale.md b/docs/preprocessor/setlocale.md index 05ec71345c2..b77c44ff443 100644 --- a/docs/preprocessor/setlocale.md +++ b/docs/preprocessor/setlocale.md @@ -8,7 +8,7 @@ no-loc: ["pragma"] --- # `setlocale` pragma -Defines the *locale*, the country, region, and language to use when translating wide-character constants and string literals. +Defines the *locale*, the country/region and language to use when translating wide-character constants and string literals. ## Syntax diff --git a/docs/preprocessor/toc.yml b/docs/preprocessor/toc.yml index a2121985ada..aa4066ec4e0 100644 --- a/docs/preprocessor/toc.yml +++ b/docs/preprocessor/toc.yml @@ -7,7 +7,7 @@ items: - name: Preprocessor href: ../preprocessor/preprocessor.md - name: New preprocessor overview - href: ../preprocessor/preprocessor-experimental-overview.md + href: ../preprocessor/preprocessor-experimental-overview.md - name: Phases of translation href: ../preprocessor/phases-of-translation.md - name: Preprocessor directives @@ -92,6 +92,8 @@ items: href: ../preprocessor/hash-undef-directive-c-cpp.md - name: "#using directive (C++/CLI)" href: ../preprocessor/hash-using-directive-cpp.md + - name: "#warning directive (C/C++)" + href: ../preprocessor/hash-warning-directive-c-cpp.md - name: Preprocessor operators expanded: false items: diff --git a/docs/preprocessor/warning.md b/docs/preprocessor/warning.md index a76695c9688..4a731996c3e 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,40 @@ 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. | +| `justification` | Optional string describing the reason for disabling or suppressing the warning. Introduced in Visual Studio 2022 version 17.14. | 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" ) +``` + +Use the **`justification`** field to explain why a warning is being disabled or +suppressed. The **`justification`** field is only supported for the **`disable`** and **`suppress`** *`warning-specifier`*. The justification appears in the Static Analysis Results Interchange Format ([SARIF](https://sarif.info/)) output when the `/analyze:log:includesuppressed` option is specified. Its value is a UTF-8 encoded narrow string literal. To generate a SARIF file, use the `/analyze:log:format:sarif` compiler option. + 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 +68,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 } ``` @@ -103,8 +115,16 @@ When you write header files, you can use `push` and `pop` to guarantee that warn #pragma warning( pop ) ``` +**Choosing between `#pragma warning` and `[[gsl::suppress]]`** + +Both `#pragma warning(suppress)` and `[[gsl::suppress]]` offer fine-grained control over warning suppression: +- `[[gsl::suppress]]` only suppresses warnings emitted by Microsoft C++ Code Analysis. Use it with the C++ Core Guidelines checks, which can be applied to a scope or a specific declaration. +- `#pragma warning(suppress)` can be used for any compiler warning. It’s useful when you need to suppress a warning in a specific code block without altering the code’s structure significantly. + +Whenever possible, use [`[[gsl::suppress]]`](../cpp/attributes.md#gslsuppresstag--justification-narrow-string-literal) for suppressing Microsoft C++ Code Analysis warnings. + For more information about compiler options that help you suppress warnings, see [`/FI`](../build/reference/fi-name-forced-include-file.md) and [`/w`](../build/reference/compiler-option-warning-level.md). ## See also -[Pragma directives and the `__pragma` and `_Pragma` keywords](./pragma-directives-and-the-pragma-keyword.md) +[Pragma directives and the `__pragma` and `_Pragma` keywords](pragma-directives-and-the-pragma-keyword.md) \ No newline at end of file diff --git a/docs/safeint/safeint-class.md b/docs/safeint/safeint-class.md index b9cd5d95024..b2f07081dfd 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 805a889550c..a4fa4cd5814 100644 --- a/docs/sanitizers/asan-building.md +++ b/docs/sanitizers/asan-building.md @@ -1,30 +1,32 @@ --- -title: "AddressSanitizer language, build, and debugging reference" -description: "Technical description of building for the AddressSanitizer" -ms.date: 09/15/2021 +title: "MSVC AddressSanitizer language, build, and debugging reference" +description: "Technical description of building for the MSVC AddressSanitizer" +ms.date: 02/05/2024 +ms.topic: overview f1_keywords: ["__SANITIZE_ADDRESS__", "ASAN_VCASAN_DEBUGGING"] -helpviewer_keywords: ["ASan reference", "AddressSanitizer reference", "Address Sanitizer reference"] +helpviewer_keywords: ["ASan reference", "MSVC AddressSanitizer reference", "MSVC Address Sanitizer reference"] --- -# AddressSanitizer language, build, and debugging reference +# MSVC 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 MSVC AddressSanitizer language specification, compiler options, linker options, and the options that control Visual Studio debugger integration specific to the MSVC 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 MSVC 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 MSVC AddressSanitizer failures, see the [crash dump reference](asan-offline-crash-dumps.md). ## Language specification ### `__SANITIZE_ADDRESS__` -The `__SANITIZE_ADDRESS__` preprocessor macro is defined as `1` when [`/fsanitize=address`](../build/reference/fsanitize.md) is set. This macro is useful for advanced users to conditionally specify source code for the presence of the AddressSanitizer runtime. +The `__SANITIZE_ADDRESS__` preprocessor macro is defined as `1` when [`/fsanitize=address`](../build/reference/fsanitize.md) is set. This macro is useful to conditionally specify source code for the presence of the MSVC AddressSanitizer runtime. ```cpp #include -int main() { +int main() +{ #ifdef __SANITIZE_ADDRESS__ - printf("Address sanitizer enabled"); + printf("MSVC AddressSanitizer enabled"); #else - printf("Address sanitizer not enabled"); + printf("MSVC AddressSanitizer not enabled"); #endif return 1; } @@ -35,19 +37,30 @@ int main() { The [`__declspec(no_sanitize_address)`](../cpp/no-sanitize-address.md) specifier can be used to selectively disable the sanitizer on functions, local variables, or global variables. This `__declspec` affects _compiler_ behavior, not _runtime_ behavior. ```cpp -__declspec(no_sanitize_address) -void test1() { +#ifdef __SANITIZE_ADDRESS__ +// no_sanitize_address is only defined when compiling with MSVC AddressSanitizer. +// Guard against this by checking if `__SANITIZE_ADDRESS__` is defined. +#define NO_SANITIZE_ADDRESS __declspec(no_sanitize_address) +#else +#define NO_SANITIZE_ADDRESS +#endif + +NO_SANITIZE_ADDRESS +void test1() +{ int x[100]; x[100] = 5; // ASan exception not caught } -void test2() { - __declspec(no_sanitize_address) int x[100]; +void test2() +{ + NO_SANITIZE_ADDRESS int x[100]; x[100] = 5; // ASan exception not caught } -__declspec(no_sanitize_address) int g[100]; -void test3() { +NO_SANITIZE_ADDRESS int g[100]; +void test3() +{ g[100] = 5; // ASan exception not caught } ``` @@ -56,11 +69,11 @@ 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 [MSVC 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). +For examples of code that demonstrates several kinds of error detection, see [MSVC AddressSanitizer error examples](asan-error-examples.md). ### `/fsanitize=fuzzer` compiler option (experimental) @@ -82,7 +95,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 | |--|--| @@ -95,39 +108,62 @@ If you specify **`/NODEFAULTLIB`** and you don't specify one of these libraries, ### `/fsanitize-address-use-after-return` compiler option (experimental) -By default, the MSVC compiler (unlike Clang) doesn't generate code to allocate frames in the heap to catch use-after-return errors. To catch these errors using AddressSanitizer, you must: +By default, the MSVC compiler (unlike Clang) doesn't generate code to allocate frames in the heap to catch use-after-return errors. To catch these errors using MSVC AddressSanitizer, you must: 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 MSVC 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. -| Runtime option | DLL or EXE | AddressSanitizer runtime libraries | +| CRT option | MSVC AddressSanitizer runtime library (.lib) | Address runtime binary (.dll) |--|--|--| -| **`/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}`* | -| **`/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}`* | +| `/MT` or `/MTd` | *`clang_rt.asan_dynamic-{arch}.lib`*, *`/wholearchive:clang_rt.asan_static_runtime_thunk-{arch}.lib`* | *`clang_rt.asan_dynamic-{arch}.dll`* +| `/MD` or `/MDd` | *`clang_rt.asan_dynamic-{arch}.lib`*, *`/wholearchive:clang_rt.asan_dynamic_runtime_thunk-{arch}.lib`* | *`clang_rt.asan_dynamic-{arch}.dll`* -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. +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. The runtime thunk libraries **must** be linked with the `/wholearchive` option applied. + +**Previous Versions** + +Prior to Visual Studio 17.7 Preview 3, statically linked (**`/MT`** or **`/MTd`**) builds didn't use a DLL dependency. Instead, the MSVC 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 AddressSanitizer – One DLL for all Runtime Configurations](https://devblogs.microsoft.com/cppblog/msvc-address-sanitizer-one-dll-for-all-runtime-configurations/). + +| CRT runtime option | DLL or EXE | MSVC AddressSanitizer runtime libraries | +|--|--|--| +| **`/MT`** | EXE | *`/wholearchive:clang_rt.asan-{arch}.lib`*, *`clang_rt.asan_cxx-{arch}.lib`* | +| **`/MT`** | DLL | *`/wholearchive:clang_rt.asan_dll_thunk-{arch}.lib`* | +| **`/MD`** | Either | *`clang_rt.asan_dynamic-{arch}.lib`*, *`/wholearchive:clang_rt.asan_dynamic_runtime_thunk-{arch}.lib`* | +| **`/MTd`** | EXE | *`/wholearchive:clang_rt.asan_dbg-{arch}.lib`*, *`clang_rt.asan_cxx_dbg-{arch}.lib`* | +| **`/MTd`** | DLL | *`/wholearchive:clang_rt.asan_dbg_dll_thunk-{arch}.lib`* | +| **`/MDd`** | Either | *`/wholearchive:clang_rt.asan_dbg_dynamic-{arch}.lib`*, *`clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}.lib`* | ## 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 MSVC AddressSanitizer exception is thrown. These libraries are called **VCAsan**. The libraries enable Visual Studio to display MSVC AddressSanitizer errors on your source code. They also enable the executable to generate crash dumps when an MSVC AddressSanitizer error report is created. For more information, see [Visual Studio MSVC AddressSanitizer extended functionality library](asan-debugger-integration.md). The library chosen depends on the compiler options, and is automatically linked in. @@ -138,7 +174,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 +191,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) +[MSVC AddressSanitizer overview](asan.md)\ +[MSVC AddressSanitizer known issues](asan-known-issues.md)\ +[MSVC AddressSanitizer runtime reference](asan-runtime.md)\ +[MSVC AddressSanitizer shadow bytes](asan-shadow-bytes.md)\ +[MSVC AddressSanitizer cloud or distributed testing](asan-offline-crash-dumps.md)\ +[MSVC AddressSanitizer debugger integration](asan-debugger-integration.md)\ +[MSVC 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 00000000000..f89ab731aea --- /dev/null +++ b/docs/sanitizers/asan-continue-on-error.md @@ -0,0 +1,354 @@ +--- +title: "Walkthrough: Use AddressSanitizer Continue On Error to find memory safety issues" +description: "Learn how to use AddressSanitizer 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 AddressSanitizer 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. AddressSanitizer (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 `-fsanitize=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 AddressSanitizer 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 AddressSanitizer 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 AddressSanitizer runtime behavior terminates the app after reporting the first error it finds. It doesn't allow the "bad" machine instruction to execute. The new AddressSanitizer 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 AddressSanitizer 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 f75d648ac4b..8232ebff548 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-flags.md b/docs/sanitizers/asan-flags.md new file mode 100644 index 00000000000..5b526a8cf1b --- /dev/null +++ b/docs/sanitizers/asan-flags.md @@ -0,0 +1,74 @@ +--- +title: "AddressSanitizer Runtime Options" +description: "List of runtime options for the Microsoft C/C++ AddressSanitizer" +ms.date: 8/08/2025 +helpviewer_keywords: ["AddressSanitizer options", "AddressSanitizer flags", "Address sanitizer options", "Address sanitizer flags", "asan options", "asan flags", "sanitizer flags", "asan_options", "AddressSanitizerFlags", "SanitizerCommonFlags"] +--- + +# AddressSanitizer Runtime Options + +The following table lists the options for the AddressSanitizer. Enable them via the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function described [here](asan-runtime.md#runtime-options). + +> [!NOTE] +> These descriptions account for Microsoft Visual C++ (MSVC) specific behaviors, which may vary from Clang's runtime options. + +| Flag | Default value | Description | +|------|---------------|-------------| +|`abort_on_error` | `false` | If `true`, ASan calls `abort()` instead of `_exit()` after printing the error report.| +|`alloc_dealloc_mismatch` | `false` | Detects mismatched memory operations such as `malloc`/`delete`, `new[]`/`free`, and so on.| +|`allocator_frees_and_returns_null_on_realloc_zero` | `true` | If set to `true`, `realloc(p, 0)` is the same as `free(p)` by default (which is the same as the POSIX standard). If set to `false`, `realloc(p, 0)` returns a pointer to an allocated space that can't be used. | +|`allocator_may_return_null` | `false` | If `true`, the allocator returns `nullptr` when out of memory. Instead of crashing, ASan emits a warning about the allocator's failure and execution continues.| +|`allow_user_poisoning` | `true` | If `true`, you may manually mark memory regions as poisoned or unpoisoned using the [Manual AddressSanitizer poisoning interface](asan-runtime.md#poisoning).| +|`check_initialization_order` | `false` | If `true`, attempts to catch initialization order issues.| +|`continue_on_error` | 0 | Allows an application to continue running while reporting memory safety errors.
0-disabled.
1-enabled; errors are sent to `stdout`.
2-enabled; errors are sent to `stderr`.
For more information, see [continue_on_error](asan-continue-on-error.md).| +|`detect_container_overflow` | `true` | If `true`, honor the container overflow annotations. For more information, see [ContainerOverflow](error-container-overflow.md).| +|`detect_invalid_pointer_pairs` | `false` | If `true`, ASan detects operations like `<`, `<=`, `>`, `>=`, and `-` on invalid pointer pairs such as pointers that belong to different objects.| +|`detect_stack_use_after_return` | `false` | Experimental. If `true`, ASan enables `stack-use-after-return` checking at runtime. Requires `/fsanitize-address-use-after-return`. For more information, see [stack-use-after-return](error-stack-use-after-return.md).| +|`exitcode` | 1 | Overrides the program exit status with this value if ASan finds an error.| +|`external_symbolizer_path` | "" | Path to the external symbolizer. If empty, ASan searches `$PATH` for the symbolizer.| +|`fast_unwind_on_malloc` | `true` | If available, ASan uses the fast frame-pointer-based unwinder on `malloc`/`free`.| +|`halt_on_error` | `true` | Not supported. Use `continue_on_error` instead.| +|`handle_segv` | `true` | If `true`, ASan handles `SEGV` errors.| +|`handle_sigfpe` | `true` | If `true`, ASan handles `SIGFPE` errors.| +|`handle_sigill` | `true` | If `true`, ASan handles `SIGILL` errors.| +|`help` | `false` | If `true`, ASan prints the flag options to the console.| +|`iat_overwrite`|`error`|`error` - reports an error whenever an overwrite is detected.
`protect` - tries to avoid using the overwritten definition.
`ignore` - doesn't try to correct any overwritten functions. For more information, see [`iat_overwrite`](asan-runtime.md#msvc-specific-addresssanitizer-runtime-options).| +|`include_if_exists` | "" | Reads options from the specified file. ASan doesn't fail if the file doesn't exist.| +|`intercept_strpbrk` | `true` | If `true`, uses custom wrappers for `strpbrk` to find more errors.| +|`intercept_strspn` | `true` | If `true`, uses custom wrappers for `strspn` and `strcspn` to find more errors.| +|`intercept_strstr` | `true` | If `true`, uses custom wrappers for `strstr` and `strcasestr` to find more errors.| +|`malloc_context_size` | 1 | Maximum number of stack frames to keep for each allocation/deallocation.| +|`malloc_fill_byte` | `0xbe` | Value used to fill newly allocated memory.| +|`max_malloc_fill_size` | 4096 | The ASan allocator fills an allocation with `malloc_fill_byte` up to `max_malloc_fill_size` on a call to `malloc`.| +|`max_redzone` | 2048 | Maximum size (in bytes) of redzones around heap objects.| +|`new_delete_type_mismatch` | `true` | Report errors on mismatch between the size of `new` and `delete`. For more information, see [`new-delete-type-mismatch`](error-new-delete-type-mismatch.md).| +|`poison_heap` | `true` | If `true`, poison the heap memory on allocation and deallocation. `false` is useful for benchmarking the allocator or instrumentator.| +|`poison_partial` | `true` | If `true`, poison partially addressable 8-byte aligned words. This flag affects heap and global buffers, but not stack buffers.| +|`print_cmdline` | `false` | Print the command line on crash. With `continue_on_error` set >= 1, prints the current working directory and is `UTF-16` aware.| +|`print_legend` | `true` | If `true`, print the shadow memory map legend to accompany the ASan report. | +|`print_stats`| `false` | If `true`, print allocator stats after printing ASan report. | +|`print_summary` | `true` | If `false`, disables showing error summaries that accompany error reports.| +|`quarantine_size_mb` | -1 | Size (in Mb) of quarantine used to detect `use-after-free` errors. A lower value may increase the chance of false negatives.| +|`redzone` | 16 | Minimum size (in bytes) of redzones around heap objects. Requirement: `redzone >= 16` and must be a power of two.| +|`replace_str` | `true` | If `true`, uses custom wrappers and replacements for `libc` string functions to find more errors.| +|`report_globals` | 1 | How to respond to buffer overflow for globals:
0-don't detect buffer overflow on globals.
1 - detect buffer overflow.
2 - detect buffer overflow and print registered globals data.| +|`sleep_before_dying` | 0 | Number of seconds to sleep between printing an error report and terminating the program.| +|`stack_trace_format` | `DEFAULT` | Format string used to render stack frames. `DEFAULT` - ` #%n %p %F %L`. List of available placeholders:
`%%` - represents a `'%'` character
`%n` - frame number (copy of `frame_no`)
`%p` - `PC`
`%m` - path to module
`%o` - offset in the module
`%f` - function name
`%q` - if available, offset in the function
`%s` - path to source file
`%l` - line in the source file
`%c` - column in the source file
`%F` - if the function is known, ASan prints `in ` followed by the offset in this function if source is unknown
`%S` - ASan prints file/line/column information
`%L` - If file information is available, ASan prints the file name, line, and column. If module information is available, ASan prints the module name, offset, and architecture. If neither are available, ASan prints `()`
`%M` - If known, ASan prints module basename and offset, or `PC`| +|`strict_memcmp` | `true` | If `true`, assumes that `memcmp(p1, p2, n)` always reads `n` bytes before comparing `p1` and `p2`.| +|`strict_string_checks` | `false` | If `true`, checks that string arguments are properly null-terminated.| +|`strip_path_prefix` | "" | Strips this prefix from file paths in error reports.| +|`symbolize` | `true` | If `true`, use the `llvm-symbolizer` to turn virtual addresses into file or line locations.| +|`symbolize_inline_frames` | `true` | Print inlined frames in stacktraces.| +|`verbosity` | 0 | Verbosity level:
0 - default verbosity.
1 - more output.
2 - even more output.
3 - maximum verbosity. | +|`windows_fast_fail_on_error`| `false` | If `true`, the process can terminate with a `__fastfail(71)` after printing the error report. For more information, see [`windows_fast_fail_on_error`](asan-runtime.md#msvc-specific-addresssanitizer-runtime-options).| +|`windows_hook_legacy_allocators`| `true` |If `true`, enables hooking of (`Global`/`Local`)(`Alloc`/`Free`/`Size`/`ReAlloc`/`Lock`/`Unlock`) functions.| + +## See also + +[AddressSanitizer overview](asan.md)\ +[AddressSanitizer known issues](asan-known-issues.md)\ +[AddressSanitizer build and language reference](asan-building.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-known-issues.md b/docs/sanitizers/asan-known-issues.md index da50d277f3b..7d3b22a2e7a 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: 11/19/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. @@ -23,12 +23,13 @@ These options and functionality are incompatible with [`/fsanitize=address`](../ - [C++ AMP](../parallel/amp/cpp-amp-overview.md) is unsupported, and should be disabled. - [Universal Windows Platform](../cppcx/universal-windows-apps-cpp.md) (UWP) applications are unsupported. - [Special case list](https://clang.llvm.org/docs/SanitizerSpecialCaseList.html) files are unsupported. +- [Precompiled headers built without `/fsanitize=address`](../build/creating-precompiled-header-files.md#consistency-rules-for-yc-and-yu) are unsupported. ## 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 Microsoft Visual C++ (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're 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: @@ -36,7 +37,8 @@ This example demonstrates the lack of precision and the benefits of enabling ann // Compile with: cl /fsanitize=address /Zi #include -int main() { +int main() +{ // Create a vector of size 10, but with a capacity of 20. std::vector v(10); v.reserve(20); @@ -54,30 +56,61 @@ int main() { } ``` -## Windows versions +## Overriding `operator new` and `delete` -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. +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). Run the linker with [`/INFERASANLIBS`](../build/reference/inferasanlibs.md) to ensure that ASan's `new`/`delete` override has lower precedence, so that the linker chooses `operator new` or `operator delete` overrides in other libraries over ASan's custom versions. When this happens, ASan might not 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`. When Microsoft Foundation Classes (MFC) overrides are used instead of the ASan provided `operator new` and `operator delete`, ASan might miss errors entirely or classify them incorrectly as a result. The following errors may be missed or incorrectly classified: + - [`alloc_dealloc_mismatch`](error-alloc-dealloc-mismatch.md) + - [`double-free`](error-double-free.md) + - [`heap-use-after-free`](error-heap-use-after-free.md) + - [`heap-buffer-overflow`](error-heap-buffer-overflow.md) + - [`new-delete-type-mismatch`](error-new-delete-type-mismatch.md) ## 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 so that the memory isn't all allocated up front. From the OS's point of view, it may look like there's a memory leak. ## 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 AddressSanitizer** property (``) is shown, the build doesn't honor it. The build doesn't honor it 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. + +## Custom code skips normal function return sequence + +Using custom code or assembly language to leave the current stack frame without honoring the usual return mechanisms isn't supported. For example, leaving the current stack frame via a long jump may generate false positives. + +Instead, before invoking custom long jump-like code, call [`__asan_handle_no_return()`](https://github.com/llvm/llvm-project/blob/ba84d0c8d762f093c6ef6d5ef5a446a42a8548a5/compiler-rt/include/sanitizer/asan_interface.h#L325-L330) . This function clears all of the shadow bytes associated with the current thread's stack, which results in some lost coverage and introduces the risk of false negatives. But your program can then safely unwind the stack without running into false positives due to stale stack shadow bytes. + +## 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 compiled with ASan is loaded into a process that contains code not compiled with ASan. In this case, ASan attempts to categorize allocations that took place before ASan initialization. Once those allocations are reallocated, ASan tries to own and monitor the lifetime of the memory. + +If all of the DLLs 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 don't unload modules compiled with ASan after they enter the process. + +Please report any bugs to our [Developer Community](https://aka.ms/feedback/report?space=62). + +## ASan 64-bit first chance exceptions + +On x64, MSVC ASan's [shadow bytes](./asan-shadow-bytes.md) region occupies several terabytes of virtual address space. ASan doesn't pre-commit this memory. Instead, it uses on-demand paging. When a shadow page is accessed for the first time, a first-chance page fault exception occurs and is handled by ASan, which commits the page. -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). +The Visual Studio debugger handles this gracefully, and doesn't show these traces. However, debuggers like WinDbgX may break on every exception by default. Disabling breaking on first-chance exceptions is recommended. For example, in WinDbgX, this corresponds to the [`sxd av`](/windows-hardware/drivers/debuggercmds/sx--sxd--sxe--sxi--sxn--sxr--sx---set-exceptions-) command. ## 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 9e5242c6050..4ac0c904d8c 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -1,35 +1,69 @@ --- 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"] --- # AddressSanitizer 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). +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_dynamic-x86_64.dll. +:::image-end::: + +Even when statically linking, the ASan runtime DLL must be present at runtime--unlike other C Runtime components. + +### Previous versions + +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. -| 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}`* | +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 AddressSanitizer – One DLL for all Runtime Configurations](https://devblogs.microsoft.com/cppblog/msvc-address-sanitizer-one-dll-for-all-runtime-configurations/). -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. +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. +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. Interception isn't guaranteed to succeed. If a function prologue is too short for a `jmp` to be written, interception can fail. If an interception failure occurs, the program throws a `debugbreak` and halts. If you attach a debugger, it makes the cause of the interception issue clear. If you have this problem, [report a bug](https://aka.ms/feedback/report?space=62). @@ -38,7 +72,7 @@ Interception isn't guaranteed to succeed. If a function prologue is too short fo ## Custom allocators and the AddressSanitizer runtime -The AddressSanitizer runtime provides interceptors for common allocator interfaces, `malloc`/`free`, `new`/`delete`, `HeapAlloc`/`HeapFree` (via `RtlAllocateHeap`/`RtlFreeHeap`). Many programs make use of custom allocators for one reason or another, an example would be any program using `dlmalloc` or a solution using the `std::allocator` interface and `VirtualAlloc()`. The compiler is unable to automatically add shadow-memory management calls to a custom allocator. It's the user's responsibility to use the [provided manual poisoning interface](#poisoning). This API enables these allocators to function properly with the existing AddressSanitizer runtime and [shadow byte](./asan-shadow-bytes.md) conventions. +The AddressSanitizer runtime provides interceptors for common allocator interfaces, `malloc`/`free`, `new`/`delete`, `HeapAlloc`/`HeapFree` (via `RtlAllocateHeap`/`RtlFreeHeap`). Many programs make use of custom allocators for one reason or another, an example would be any program using `dlmalloc` or a solution using the `std::allocator` interface and `VirtualAlloc()`. The compiler is unable to automatically add shadow-memory management calls to a custom allocator. It's the user's responsibility to use the [provided manual poisoning interface](#poisoning). This API enables these allocators to function properly with the existing AddressSanitizer runtime and [shadow byte](asan-shadow-bytes.md) conventions. ## Manual AddressSanitizer poisoning interface @@ -56,39 +90,86 @@ For convenience, the [AddressSanitizer interface header file](https://github.com #define ASAN_UNPOISON_MEMORY_REGION(addr, size) ``` +> [!NOTE] +> If you manually poison memory, you must unpoison it before reuse. This is especially important for stack addresses, such as for a local variable, which are frequently reused during program execution. You risk introducing `use-after-poison` false positives in manually poisoned stack addresses if you don't unpoison them before their stack frame is removed. + ## Alignment requirements for AddressSanitizer poisoning Any manual poisoning of shadow bytes must consider the alignment requirements. The user must add padding if necessary so the shadow bytes end on a byte boundary in the shadow memory. Each bit in the AddressSanitizer shadow memory encodes the state of a single byte in the application's memory. This encoding means the total size of each allocation, including any padding, must align to an 8-byte boundary. If the alignment requirement isn't satisfied, it can lead to incorrect bug reporting. The incorrect reporting could manifest as missing reports (false negatives) or reports on non-errors (false-positives). For an illustration of the alignment requirement and potential issues, see the provided [ASan alignment examples](https://github.com/mcgov/asan_alignment_example). One is a small program to show what can go wrong with manual shadow memory poisoning. The second is an example implementation of manual poisoning using the `std::allocator` interface. -## Run-time options +## Runtime options + +MSVC AddressSanitizer is a regularly synced fork of the [Clang AddressSanitizer runtime](https://github.com/llvm/llvm-project). As a result, MSVC implicitly inherits many of Clang's ASan runtime options. A complete list of options that we actively maintain and test can be found [here](./asan-flags.md). If you discover options that don't function as expected, [report a bug](https://aka.ms/feedback/report?space=62). + + +### Configure runtime options + +ASan runtime options are set in one of two ways: +- The `ASAN_OPTIONS` environment variable +- The `__asan_default_options` user function -Microsoft C/C++ (MSVC) uses a runtime based on the [Clang AddressSanitizer runtime from the llvm-project repository](https://github.com/llvm/llvm-project). Because of this, most runtime options are shared between the two versions. [A complete list of the public Clang runtime options is available here](https://github.com/google/sanitizers/wiki/SanitizerCommonFlags). We document some differences in the sections that follow. If you discover options that don't function as expected, [report a bug](https://aka.ms/feedback/report?space=62). +If the environment variable and the user function specify conflicting options, the options in the `ASAN_OPTIONS` environment variable take precedence. + +Multiple options are specified by separating them with a colon (`:`). + +The following example sets [`alloc_dealloc_mismatch`](error-alloc-dealloc-mismatch.md) to one and `symbolize` to zero: + +```cmd +set ASAN_OPTIONS=alloc_dealloc_mismatch=1:symbolize=0 +``` + +Or add the following function to your code: + +```cpp +extern "C" const char* __asan_default_options() +{ + return "alloc_dealloc_mismatch=1:symbolize=0"; +} +``` ### Unsupported AddressSanitizer options -- detect_container_overflow -- unmap_shadow_on_exit +- `detect_container_overflow` +- `unmap_shadow_on_exit` > [!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 +- [`continue_on_error`](asan-continue-on-error.md) Boolean, set to `false` by default. When set to `true`, it allows the program to continue executing after a memory violation is reported, allowing you to collect multiple error reports. + + + +- `iat_overwrite` + String, set to `"error"` by default. Other possible values are `"protect"` and `"ignore"`. Some modules may overwrite the [`import address table`](/windows/win32/debug/pe-format#import-address-table) of other modules to customize implementations of certain functions. For example, drivers commonly provide custom implementations for specific hardware. The `iat_overwrite` option manages the AddressSanitizer runtime's protection against overwrites for specific [`memoryapi.h`](/windows/win32/api/memoryapi/) functions. The runtime currently tracks the [`VirtualAlloc`](/windows/win32/api/memoryapi/nf-memoryapi-virtualalloc), [`VirtualProtect`](/windows/win32/api/memoryapi/nf-memoryapi-virtualprotect), and [`VirtualQuery`](/windows/win32/api/memoryapi/nf-memoryapi-virtualquery) functions for protection. This option is available in Visual Studio 2022 version 17.5 Preview 1 and later versions. The following `iat_overwrite` values control how the runtime reacts when protected functions are overwritten: + + - If set to `"error"` (the default), the runtime reports an error whenever an overwrite is detected. + - If set to `"protect"`, the runtime attempts to avoid using the overwritten definition and proceeds. Effectively, the original `memoryapi` definition of the function is used from inside the runtime to avoid infinite recursion. Other modules in the process still use the overwritten definition. + - If set to `"ignore"`, the runtime doesn't attempt to correct any overwritten functions and proceeds with execution. + +- `windows_fast_fail_on_error` + Boolean (`false` by default), set to `true` to enable the process to terminate with a `__fastfail(71)` after printing the error report. + + > [!NOTE] + > When `abort_on_error` value is set to `true`, on Windows the program terminates with an `exit(3)`. In order to not change current behavior we decided to introduce this new option instead. If both `abort_on_error` and `windows_fast_fail_on_error` are `true`, the program will exit with the `__fastfail`. + - `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. 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`. -> [!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. ## 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 @@ -138,7 +219,7 @@ The AddressSanitizer runtime hot-patches many functions to enable memory safety - [`realloc`](../c-runtime-library/reference/realloc.md) - [`RtlAllocateHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlallocateheap) - [`RtlCreateHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlcreateheap) -- [`RtlDestroyHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlcreateheap) +- [`RtlDestroyHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtldestroyheap) - [`RtlFreeHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlfreeheap) - [`RtlRaiseException`](/windows/win32/api/rtlsupportapi/nf-rtlsupportapi-rtlraiseexception) - `RtlReAllocateHeap` (undocumented) @@ -165,30 +246,30 @@ 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) -- [`GlobalHandle`](/windows/win32/api/winbase/nf-winbase-GlobalHandle) -- [`GlobalLock`](/windows/win32/api/winbase/nf-winbase-GlobalLock) -- [`GlobalReAlloc`](/windows/win32/api/winbase/nf-winbase-GlobalReAlloc) -- [`GlobalSize`](/windows/win32/api/winbase/nf-winbase-GlobalSize) -- [`GlobalUnlock`](/windows/win32/api/winbase/nf-winbase-GlobalUnlock) -- [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-LocalAlloc) -- [`LocalFree`](/windows/win32/api/winbase/nf-winbase-LocalFree) -- [`LocalHandle`](/windows/win32/api/winbase/nf-winbase-LocalHandle) -- [`LocalLock`](/windows/win32/api/winbase/nf-winbase-LocalLock) -- [`LocalReAlloc`](/windows/win32/api/winbase/nf-winbase-LocalReAlloc) -- [`LocalSize`](/windows/win32/api/winbase/nf-winbase-LocalSize) -- [`LocalUnlock`](/windows/win32/api/winbase/nf-winbase-LocalUnlock) +- [`GlobalFree`](/windows/win32/api/winbase/nf-winbase-globalfree) +- [`GlobalHandle`](/windows/win32/api/winbase/nf-winbase-globalhandle) +- [`GlobalLock`](/windows/win32/api/winbase/nf-winbase-globallock) +- [`GlobalReAlloc`](/windows/win32/api/winbase/nf-winbase-globalrealloc) +- [`GlobalSize`](/windows/win32/api/winbase/nf-winbase-globalsize) +- [`GlobalUnlock`](/windows/win32/api/winbase/nf-winbase-globalunlock) +- [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-localalloc) +- [`LocalFree`](/windows/win32/api/winbase/nf-winbase-localfree) +- [`LocalHandle`](/windows/win32/api/winbase/nf-winbase-localhandle) +- [`LocalLock`](/windows/win32/api/winbase/nf-winbase-locallock) +- [`LocalReAlloc`](/windows/win32/api/winbase/nf-winbase-localrealloc) +- [`LocalSize`](/windows/win32/api/winbase/nf-winbase-localsize) +- [`LocalUnlock`](/windows/win32/api/winbase/nf-winbase-localunlock) ## See also -[AddressSanitizer overview](./asan.md)\ -[AddressSanitizer known issues](./asan-known-issues.md)\ -[AddressSanitizer build and language reference](./asan-building.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 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-shadow-bytes.md b/docs/sanitizers/asan-shadow-bytes.md index 6d53b91270c..a59597629b8 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 @@ -19,6 +19,9 @@ One shadow byte describes how many bytes are currently accessible as follows: - 1-7 means one to seven bytes - Negative numbers encode context for the runtime to use for reporting diagnostics. +> [!NOTE] +> By default, entries in the shadow memory are zero-initialized. Therefore, ASan assumes that the memory is _addressable_ by default, i.e. valid to read and write. The shadow bytes will be populated with non-zero values as the program executes and the lifetime of variables and other allocations come to an end. + ### Shadow byte legend Consider this shadow byte legend where all negative numbers are defined: diff --git a/docs/sanitizers/asan.md b/docs/sanitizers/asan.md index 01e13bfd87d..63d7c1cb7f2 100644 --- a/docs/sanitizers/asan.md +++ b/docs/sanitizers/asan.md @@ -1,7 +1,8 @@ --- title: "AddressSanitizer" description: "Top-level description of the AddressSanitizer feature for Microsoft C/C++." -ms.date: 03/05/2021 +ms.date: 09/06/2024 +ms.topic: overview f1_keywords: ["AddressSanitizer"] helpviewer_keywords: ["ASan", "AddressSanitizer", "Address Sanitizer", "compiling for AddressSanitizer"] --- @@ -10,7 +11,7 @@ helpviewer_keywords: ["ASan", "AddressSanitizer", "Address Sanitizer", "compilin ## Overview -The C & C++ languages are powerful, but can suffer from a class of bugs that affect program correctness and program security. Starting in Visual Studio 2019 version 16.9, the Microsoft C/C++ compiler (MSVC) and IDE supports the *AddressSanitizer*. AddressSanitizer (ASan) is a compiler and runtime technology that exposes many hard-to-find bugs with **zero** false positives: +The C & C++ languages are powerful, but can suffer from a class of bugs that affect program correctness and program security. Starting in Visual Studio 2019 version 16.9, the Microsoft C/C++ compiler (MSVC) and IDE supports the *AddressSanitizer* sanitizer. AddressSanitizer (ASan) is a compiler and runtime technology that exposes many hard-to-find bugs with **zero** false positives: - [Alloc/dealloc mismatches](error-alloc-dealloc-mismatch.md) and [`new`/`delete` type mismatches](error-new-delete-type-mismatch.md) - [Allocations too large for the heap](error-allocation-size-too-big.md) @@ -32,30 +33,28 @@ Use AddressSanitizer to reduce your time spent on: - Stress testing - Integrating new code -AddressSanitizer, originally [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany), is a powerful alternative to both [`/RTC` (Runtime error checks)](../build/reference/rtc-run-time-error-checks.md) and [`/analyze` (Static analysis)](../build/reference/analyze-code-analysis.md). It provides run-time bug-finding technologies that use your existing build systems and existing test assets directly. +AddressSanitizer, originally [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany), provides runtime bug-finding technologies that use your existing build systems and existing test assets directly. -AddressSanitizer is integrated with the Visual Studio project system, the CMake build system, and the IDE. Projects can enable AddressSanitizer by setting a project property, or by using one extra compiler option: **`/fsanitize=address`**. The new option is compatible with all levels of optimization and configurations of x86 and x64. However, it's incompatible with [edit-and-continue](/visualstudio/debugger/edit-and-continue-visual-cpp), [incremental linking](../build/reference/incremental-link-incrementally.md), and [`/RTC`](../build/reference/rtc-run-time-error-checks.md). +AddressSanitizer is integrated with the Visual Studio project system, the CMake build system, and the IDE. Projects can enable AddressSanitizer by setting a project property, or by using one extra compiler option: **`/fsanitize=address`**. The new option is compatible with all levels of optimization and configurations of x86 and x64. However, it isn't compatible with [edit-and-continue](/visualstudio/debugger/edit-and-continue-visual-cpp), [incremental linking](../build/reference/incremental-link-incrementally.md), and [`/RTC`](../build/reference/rtc-run-time-error-checks.md). -Starting in Visual Studio 2019 version 16.9, Microsoft's AddressSanitizer technology enables integration with the Visual Studio IDE. The functionality can optionally create a crash dump file when the sanitizer finds a bug at runtime. If you set the `ASAN_SAVE_DUMPS=MyFileName.dmp` environment variable before you run your program, a crash dump file gets created with extra metadata for efficient [post-mortem debugging](#crash-dumps) of precisely diagnosed bugs. These dump files make extended use of the AddressSanitizer easier for: +Starting in Visual Studio 2019 version 16.9, Microsoft's AddressSanitizer technology enables integration with the Visual Studio IDE. The functionality can optionally create a crash dump file when the sanitizer finds a bug at runtime. If you set the `ASAN_SAVE_DUMPS=MyFileName.dmp` environment variable before you run your program, a crash dump file is created with extra metadata for efficient [post-mortem debugging](#crash-dumps) of precisely diagnosed bugs. These dump files make extended use of AddressSanitizer easier for: -- Local machine testing, -- On-premise distributed testing, and -- Cloud-based workflows for testing. +- Local machine testing +- On-premises distributed testing +- Cloud-based workflows for testing -### Install the AddressSanitizer +### Install AddressSanitizer -The AddressSanitizer IDE integration and libraries get installed by default with C++ workloads in the Visual Studio Installer. However, if you're upgrading from an older version of Visual Studio 2019, use the Installer to enable ASan support after the upgrade: +C++ workloads in the Visual Studio Installer install the AddressSanitizer libraries and IDE integration by default. However, if you're upgrading from an older version of Visual Studio 2019, use the Installer to enable ASan support after the upgrade. You can open the installer from the Visual Studio main menu via **Tools** > **Get Tools and Features...** Choose **Modify** on your existing Visual Studio installation from the Visual Studio Installer to get to the following screen. -:::image type="content" source="media/asan-installer-option.png" alt-text="Visual Studio Installer screenshot highlighting the C++ AddressSanitizer component"::: - -You can choose **Modify** on your existing Visual Studio installation from the Visual Studio Installer to get to the screen above. +:::image type="content" source="media/asan-installer-option.png" alt-text="Screenshot of the Visual Studio Installer. The C++ AddressSanitizer component, under the Optional section, is highlighted."::: > [!NOTE] > If you run Visual Studio on the new update but haven't installed ASan, you'll get an error when you run your code: > > LNK1356: cannot find library 'clang_rt.asan_dynamic-i386.lib' -### Use the AddressSanitizer +### Use AddressSanitizer Start building your executables with the **`/fsanitize=address`** compiler option using any of these common development methods: @@ -65,7 +64,7 @@ Start building your executables with the **`/fsanitize=address`** compiler optio Recompile, then run your program normally. This code generation exposes [many types of precisely diagnosed bugs](#error-types). These errors get reported in three ways: in the debugger IDE, on the command line, or stored in a [new type of dump file](#crash-dumps) for precise off-line processing. -Microsoft recommends using the AddressSanitizer in these three standard workflows: +Microsoft recommends you use AddressSanitizer in these three standard workflows: - **Developer inner loop** - Visual Studio - [Command line](#command-prompt) @@ -79,16 +78,19 @@ Microsoft recommends using the AddressSanitizer in these three standard workflow - [Azure OneFuzz](https://www.microsoft.com/security/blog/2020/09/15/microsoft-onefuzz-framework-open-source-developer-tool-fix-bugs/) - Local Machine -This article covers the information you require to enable the three workflows listed above. The information is specific to the **platform-dependent** Windows 10 implementation of the AddressSanitizer. This documentation supplements the excellent documentation from [Google, Apple, and GCC](#external-docs) already published. +This article covers the information you require to enable the three workflows listed previously. The information is specific to the **platform-dependent** Windows 10 (and later) implementation of AddressSanitizer. This documentation supplements the excellent documentation from [Google, Apple, and GCC](#external-docs) already published. > [!NOTE] -> Current support is limited to x86 and x64 on Windows 10. [Send us feedback](https://aka.ms/vsfeedback/browsecpp) on what you'd like to see in future releases. Your feedback helps us prioritize other sanitizers for the future, such as **`/fsanitize=thread`**, **`/fsanitize=leak`**, **`/fsanitize=memory`**, **`/fsanitize=undefined`**, or **`/fsanitize=hwaddress`**. You can [report bugs here](https://aka.ms/feedback/report?space=62) if you run into issues. +> Support is limited to x86 and x64 on Windows 10 and later. [Send us feedback](https://aka.ms/vsfeedback/browsecpp) on what you'd like to see in future releases. Your feedback helps us prioritize other sanitizers for the future, such as **`/fsanitize=thread`**, **`/fsanitize=leak`**, **`/fsanitize=memory`**, **`/fsanitize=undefined`**, or **`/fsanitize=hwaddress`**. You can [report bugs here](https://aka.ms/feedback/report?space=62) if you run into issues. + +## Use AddressSanitizer from a developer command prompt -## Use the AddressSanitizer from a developer command prompt +Use the **`/fsanitize=address`** compiler option in a [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts) to enable compiling for the AddressSanitizer runtime. The **`/fsanitize=address`** option is compatible with existing C++ or C optimization levels (for example, `/Od`, `/O1`, `/O2`, and `/O2 /GL`). The option works with static and dynamic CRTs (for example, `/MD`, `/MDd`, `/MT`, and `/MTd`). It works whether you create an EXE or a DLL. Debug information is required for optimal formatting of call stacks. In the following example, `cl /fsanitize=address /Zi` is passed on the command line. -Use the **`/fsanitize=address`** compiler option in a [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts) to enable compiling for the AddressSanitizer runtime. The **`/fsanitize=address`** option is compatible with all existing C++ or C optimization levels (for example, `/Od`, `/O1`, `/O2`, `/O2 /GL`, and `PGO`). The option works with static and dynamic CRTs (for example, `/MD`, `/MDd`, `/MT`, and `/MTd`). It works whether you create an EXE or a DLL. Debug information is required for optimal formatting of call stacks. In the example below, `cl /fsanitize=address /Zi` is passed on the command line. +> [!NOTE] +> AddressSanitizer doesn't support Profile-guided optimization (PGO). AddressSanitizer shouldn't be used in production. -The AddressSanitizer libraries (.lib files) get linked for you automatically. For more information, see [AddressSanitizer language, build, and debugging reference](asan-building.md). +The AddressSanitizer libraries (.lib files) are linked for you automatically. For more information, see [AddressSanitizer language, build, and debugging reference](asan-building.md). ### Example - basic global buffer overflow @@ -105,13 +107,15 @@ int main() { Using a developer command prompt for Visual Studio 2019, compile *`main.cpp`* using `/fsanitize=address /Zi` -:::image type="content" source="media/asan-command-basic-global-overflow.png" alt-text="Screenshot of a command prompt showing the command to compile with AddressSanitizer options."::: +:::image type="content" source="media/asan-command-basic-global-overflow.png" alt-text="Screenshot of a command prompt showing the command to compile with AddressSanitizer options. The command is: `cl main.cpp -faanitize-address /Zi`."::: -When you run the resulting *`main.exe`* at the command line, it creates the formatted error report seen below. +When you run the resulting *`main.exe`* at the command line, it creates the formatted error report that follows. Consider the overlaid, red boxes that highlight seven key pieces of information: -:::image type="content" source="media/asan-basic-global-overflow.png" alt-text="Screenshot of the debugger showing a basic global overflow error."::: +:::image type="complex" source="media/asan-basic-global-overflow.png" alt-text="Screenshot of the debugger showing a basic global overflow error."::: +There are seven red highlights identifying key pieces of information in the error report. They map to the numbered list that follows this screenshot. The numbered boxes highlight the following text: 1) global-buffer-overflow 2) WRITE of size 4 3) basic-global-overflow.cpp 7 4) to the right of global variable 'x' defined in 'basic-global-overflow.cpp:3:8' 5) of size 400 6) 00 00[f9]f9 f9 7) Box is in the shadow byte legend area and contains Global redzone: f9 +:::image-end::: ### Red highlights, from top to bottom @@ -126,49 +130,103 @@ Consider the overlaid, red boxes that highlight seven key pieces of information: > [!NOTE] > The function names in the call stack are produced through the [LLVM symbolizer](https://llvm.org/docs/CommandGuide/llvm-symbolizer.html) that's invoked by the runtime upon error. -## Use the AddressSanitizer in Visual Studio +## Use AddressSanitizer in Visual Studio -AddressSanitizer is integrated with the Visual Studio IDE. To turn on the AddressSanitizer for an MSBuild project, right-click on the project in Solution Explorer and choose **Properties**. In the **Property Pages** dialog, select **Configuration Properties** > **C/C++** > **General**, then modify the **Enable AddressSanitizer** property. Choose **OK** to save your changes. +AddressSanitizer is integrated with the Visual Studio IDE. To turn on AddressSanitizer for an MSBuild project, right-click on the project in Solution Explorer and choose **Properties**. In the **Property Pages** dialog, select **Configuration Properties** > **C/C++** > **General**, then modify the **Enable AddressSanitizer** property. Choose **OK** to save your changes. :::image type="content" source="media/asan-project-system-dialog.png" alt-text="Screenshot of the Property Pages dialog showing the Enable AddressSanitizer property."::: To build from the IDE, opt out of any [incompatible options](./asan-known-issues.md#incompatible-options). For an existing project compiled by using **`/Od`** (or Debug mode), you may need to turn off these options: -- Turn off [edit and continue](/visualstudio/debugger/how-to-enable-and-disable-edit-and-continue) +- Turn off [`/ZI` (Debug Information Format)](../build/reference/z7-zi-zi-debug-information-format.md) - Turn off [`/RTC1` (runtime checks)](../build/reference/rtc-run-time-error-checks.md) - Turn off [`/INCREMENTAL` (incremental linking)](../build/reference/incremental-link-incrementally.md) -To build and run the debugger, enter **F5**. You'll see this window in Visual Studio: +To build and run the debugger, press **F5**. An **Exception Thrown** window appears in Visual Studio: :::image type="content" source="media/asan-global-buffer-overflow-F5.png" alt-text="Screenshot of the debugger showing a global buffer overflow error."::: -## Using the AddressSanitizer from Visual Studio: CMake +## Use AddressSanitizer from Visual Studio: CMake -To enable the AddressSanitizer for [a CMake project created to target Windows](../build/cmake-projects-in-visual-studio.md), take these steps: +To enable AddressSanitizer for a [CMake project created to target Windows](../build/cmake-projects-in-visual-studio.md), follow these steps: 1. Open the **Configurations** dropdown in the toolbar at the top of the IDE and select **Manage Configurations**. - :::image type="content" source="media/asan-cmake-configuration-dropdown.png" alt-text="Screenshot of the CMake configuration dropdown."::: + :::image type="content" source="media/asan-cmake-configuration-drop-down.png" alt-text="Screenshot of the CMake configuration dropdown. It displays options like x64 Debug, x64 Release, and so on. At the bottom of the list, Manage Configurations... is highlighted."::: - That selection opens the CMake Project Settings editor, which is saved in a CMakeSettings.json file. + That opens the CMake Project Settings editor, which reflects the contents of your project's `CMakeSettings.json` file. 1. Choose the **Edit JSON** link in the editor. This selection switches the view to raw JSON. -1. Add the property: **“addressSanitizerEnabled”: true** - - This image is of CMakeSettings.json after that change: - - :::image type="content" source="media/asan-cmake-json.png" alt-text="Screenshot of the text editor view of CMakeSettings.json."::: - -1. Enter **Ctrl+S** to save this JSON file, then enter **F5** to recompile and run under the debugger. - -This screenshot captures the error from the CMake build. - -:::image type="content" source="media/asan-cmake-error-f5.png" alt-text="Screenshot of the CMake build error message."::: - +1. Add the following snippet to the `"windows-base"` preset, inside `"configurePresets":` to turn on AddressSanitizer: + + ```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. AddressSanitizer doesn't work if edit-and-continue is specified (`/ZI`), which is enabled by default for new CMake projects. In `CMakeLists.txt`, comment out (prefix with `#`) the line that starts with `set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT"`. That line looks something like this, afterwards: + + ```json + # set(CMAKE_MSVC_DEBUG_INFORMATION_FORMAT "$,$>,$<$:EditAndContinue>,$<$:ProgramDatabase>>") + ``` + +1. Enter **Ctrl+S** to save this JSON file +1. Clear your CMake cache directory and reconfigure by choosing from the Visual Studio menu: **Project** > **Delete cache and Reconfigure**. Choose **Yes** when the prompt appears to clear your cache directory and reconfigure. +1. Replace the contents of the source file (for example, `CMakeProject1.cpp`) with the following: + + ```cpp + // CMakeProject1.cpp : Defines the entry point for the application + + #include + + int x[100]; + + int main() + { + printf("Hello!\n"); + x[100] = 5; // Boom! + return 0; + } + ``` + +1. Choose **F5** to recompile and run under the debugger. + + This screenshot captures the error from the CMake build. + + :::image type="content" source="media/asan-cmake-error-f5.png" alt-text="Screenshot of an exception that says: Address Sanitizer Error: Global buffer overflow. In the background, address sanitizer output is visible in command window."::: + ## AddressSanitizer crash dumps -We introduced new functionality in the AddressSanitizer for use with cloud and distributed workflows. This functionality allows offline viewing of an AddressSanitizer error in the IDE. The error gets overlaid on top of your source, just as you would experience in a live debug session. +We introduced new functionality in AddressSanitizer for use with cloud and distributed workflows. This functionality allows offline viewing of an AddressSanitizer error in the IDE. The error gets overlaid on top of your source, just as you would experience in a live debug session. These new dump files can lead to efficiencies when analyzing a bug. You don't need to rerun, or find remote data or look for a machine that went off-line. @@ -222,7 +280,7 @@ Features that could lead to false positives in Visual Studio 2019 16.9 weren't i - [Container Overflow](https://github.com/google/sanitizers/wiki/AddressSanitizerContainerOverflow) - [Pointer Subtraction/Comparison](https://gcc.gnu.org/onlinedocs/gcc/Instrumentation-Options.html) -For more information, see [Building for the AddressSanitizer with MSVC](./asan-building.md). +For more information, see [Building for AddressSanitizer with MSVC](./asan-building.md). ## Existing industry documentation @@ -232,7 +290,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 906017a981d..2e717e964f2 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,44 @@ 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[]`. +## Remarks + +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 example of `alloc_dealloc_mismatch`: ```cmd cl example1.cpp /fsanitize=address /Zi @@ -48,17 +54,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 9e5e7a02d22..8cfe9d85383 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"] @@ -10,6 +10,8 @@ helpviewer_keywords: ["allocation-size-too-big error", "AddressSanitizer error a > Address Sanitizer Error: allocation-size-too-big +## Remarks + This example shows the error found when an allocation is too large for the heap. Example sourced from [LLVM compiler-rt test suite](https://github.com/llvm/llvm-project/tree/main/compiler-rt/test/asan/TestCases). ## Example @@ -50,11 +52,11 @@ devenv /debugexe example1.exe ## 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-calloc-overflow.md b/docs/sanitizers/error-calloc-overflow.md index 5c7ee450593..eff22183f37 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["calloc-overflow error", "AddressSanitizer error calloc-ov > Address Sanitizer Error: calloc-overflow +## Remarks + The CRT function [`calloc`](../c-runtime-library/reference/calloc.md) creates an array in memory with elements initialized to 0. The arguments can create an internal error that leads to a NULL pointer as the return value. ## Example @@ -45,11 +47,11 @@ devenv /debugexe example1.exe ## 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-container-overflow.md b/docs/sanitizers/error-container-overflow.md index 0d8efc036e6..39b471251df 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,22 @@ 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: +## Remarks + +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 +51,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,13 +62,41 @@ 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)\ -[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-double-free.md b/docs/sanitizers/error-double-free.md index c60b825c648..7623468b3fe 100644 --- a/docs/sanitizers/error-double-free.md +++ b/docs/sanitizers/error-double-free.md @@ -1,15 +1,18 @@ --- 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"] +ms.custom: sfi-image-nochange --- # Error: `double-free` > Address Sanitizer Error: Deallocation of freed memory +## Remarks + In C, you can call `free` erroneously. In C++, you can call `delete` more than once. In these examples, we show errors with `delete`, `free`, and `HeapCreate`. ## Example C++ - double `operator delete` @@ -105,11 +108,11 @@ devenv /debugexe example3.exe ## 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-dynamic-stack-buffer-overflow.md b/docs/sanitizers/error-dynamic-stack-buffer-overflow.md index 980851d524a..3ff4780ae61 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["dynamic-stack-buffer-overflow error", "AddressSanitizer e > Address Sanitizer Error: dynamic-stack-buffer-overflow +## Remarks + This example shows the error that results from a buffer access outside the bounds of a stack-allocated object. ## Example - `alloca` overflow (right) @@ -170,11 +172,11 @@ devenv /debugexe example3.exe ## 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-global-buffer-overflow.md b/docs/sanitizers/error-global-buffer-overflow.md index 0ac93be56aa..68f2fbb17d9 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["global-buffer-overflow error", "AddressSanitizer error gl > Address Sanitizer Error: Global buffer overflow +## Remarks + The compiler generates metadata for any variable in the `.data` or `.bss` sections. These variables have language scope of global or file static. They're allocated in memory before `main()` starts. Global variables in C are treated much differently than in C++. This difference is because of the complex rules for linking C. In C, a global variable can be declared in several source files, and each definition can have different types. The compiler can't see all the possible definitions at once, but the linker can. For C, the linker defaults to selecting the largest-sized variable out of all the different declarations. @@ -126,9 +128,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"; @@ -151,11 +154,11 @@ devenv /debugexe example3.exe -l ## 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-heap-buffer-overflow.md b/docs/sanitizers/error-heap-buffer-overflow.md index 10600d88071..728edfe0575 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["heap-buffer-overflow error", "AddressSanitizer error heap > Address Sanitizer Error: Heap buffer overflow +## Remarks + This example demonstrates the error that results when a memory access occurs outside the bounds of a heap-allocated object. ## Example - classic heap buffer overflow @@ -109,11 +111,11 @@ devenv /debugexe example3.exe ## 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-heap-use-after-free.md b/docs/sanitizers/error-heap-use-after-free.md index 03b4b0fef3d..6ddd65cbb5e 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"] --- @@ -9,6 +9,8 @@ helpviewer_keywords: ["heap-use-after-free error", "AddressSanitizer error heap- > Address Sanitizer Error: Use of deallocated memory +## Remarks + We show three examples where storage in the heap can be allocated via `malloc`, `realloc` (C), and `new` (C++), along with a mistaken use of `volatile`. ## Example - `malloc` @@ -35,9 +37,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 +70,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 +103,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,17 +136,21 @@ 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 -[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-invalid-allocation-alignment.md b/docs/sanitizers/error-invalid-allocation-alignment.md index 2197383c97a..bb3a05c022f 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["invalid-allocation-alignment error", "AddressSanitizer er > Address Sanitizer Error: invalid-allocation-alignment +## Remarks + The [`_aligned_malloc`](../c-runtime-library/reference/aligned-malloc.md) function requires a power of 2 for expressing the alignment. We simulate the "external" calculation of some alignment factor using an unoptimized global variable. ## Example @@ -42,11 +44,11 @@ devenv /debugexe example1.exe ## 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-memcpy-param-overlap.md b/docs/sanitizers/error-memcpy-param-overlap.md index 9d9d475d2a0..005bde29ac8 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"] @@ -9,6 +9,11 @@ helpviewer_keywords: ["memcpy-param-overlap error", "AddressSanitizer error memc > Address Sanitizer Error: memcpy-param-overlap +## Remarks + +> [!NOTE] +> The `/Oi` flag is required to reliably detect `memcpy-param-overlap` errors. This flag tells the compiler to treat `memcpy` and other functions as intrinsics, which is necessary because some versions of the standard library implement them as such. Since ASan is a dynamic analysis tool, it can only detect errors with an observable runtime effect. Note that when `/O2` is also set, ASan may not be able to reliably detect `memcpy-param-overlap` errors because the intrinsic variant of these functions isn't guaranteed to be used. For more information, see [`/Oi` (Generate Intrinsic Functions)](../build/reference/oi-generate-intrinsic-functions.md). + The CRT function [`memcpy`](../c-runtime-library/reference/memcpy-wmemcpy.md) **doesn't support** overlapping memory. The CRT provides an alternative to `memcpy` that does support overlapping memory: [`memmove`](../c-runtime-library/reference/memmove-wmemmove.md). A common error is to treat `memmove` as being semantically equivalent to `memcpy`. @@ -35,7 +40,7 @@ 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 ``` @@ -45,11 +50,11 @@ devenv /debugexe example1.exe ## 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-new-delete-type-mismatch.md b/docs/sanitizers/error-new-delete-type-mismatch.md index 5a72252cecd..daff0ec1c11 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["new-delete-type-mismatch error", "AddressSanitizer error > Address Sanitizer Error: Deallocation size different from allocation size +## Remarks + In this example, only `~Base`, and not `~Derived`, is called. The compiler generates a call to `~Base()` because the `Base` destructor isn't **`virtual`**. When we call `delete b`, the object's destructor is bound to the default definition. The code deletes an empty base class (or 1 byte on Windows). A missing **`virtual`** keyword on the destructor declaration is a common C++ error when using inheritance. ## Example - virtual destructor @@ -48,7 +50,7 @@ To fix the example, add: ```cpp struct Base { virtual ~Base() = default; -} +}; ``` 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): @@ -64,11 +66,11 @@ devenv /debugexe example1.exe ## 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-stack-buffer-overflow.md b/docs/sanitizers/error-stack-buffer-overflow.md index 10246dc07cb..403ee7b16bb 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["stack-buffer-overflow error", "AddressSanitizer error sta > Address Sanitizer Error: Stack buffer overflow +## Remarks + A stack buffer overflow can happen many ways in C or C++. We provide several examples for this category of error that you can catch by a simple recompile. ## Example - stack buffer overflow @@ -86,7 +88,7 @@ public: class Child : public Parent { public: - int extra_field; + volatile int extra_field; }; int main(void) { @@ -95,7 +97,7 @@ int main(void) { Child *c = (Child*)&p; c->extra_field = 42; // Boom ! - return 0; + return (c->extra_field == 42); } ``` @@ -112,11 +114,11 @@ devenv /debugexe example3.exe ## 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-stack-buffer-underflow.md b/docs/sanitizers/error-stack-buffer-underflow.md index 79971d52a59..c8cf463ff24 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["stack-buffer-underflow error", "AddressSanitizer error st > Address Sanitizer Error: Stack buffer underflow +## Remarks + These error messages indicate a memory access to somewhere before the beginning of a stack variable. ## Example - local array underflow @@ -31,10 +33,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."::: @@ -72,17 +76,17 @@ cl example2.cpp /fsanitize=address /Zi devenv /debugexe example2.exe ``` -### Resulting error - stack underflow on thread +### Resulting error - stack underflow on thread :::image type="content" source="media/stack-buffer-underflow-example-2.png" alt-text="Screenshot of debugger displaying stack-buffer-underflow error in example 2."::: ## 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-stack-use-after-return.md b/docs/sanitizers/error-stack-use-after-return.md index fa5fa706353..6ddd807d4a8 100644 --- a/docs/sanitizers/error-stack-use-after-return.md +++ b/docs/sanitizers/error-stack-use-after-return.md @@ -1,13 +1,15 @@ --- 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 AddressSanitizer 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"] --- # Error: `stack-use-after-return` -> Address Sanitizer Error: Use of stack memory after return +> AddressSanitizer Error: Use of stack memory after return + +## Remarks This check requires code generation that's activated by an extra compiler option, [`/fsanitize-address-use-after-return`](../build/reference/fsanitize.md), and by setting the environment variable `ASAN_OPTIONS=detect_stack_use_after_return=1`. @@ -21,7 +23,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 +35,7 @@ int main() { foo(); *x = 42; // Boom! - return 0; + return (*x == 42); } ``` @@ -96,22 +98,24 @@ 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."::: ## 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-stack-use-after-scope.md b/docs/sanitizers/error-stack-use-after-scope.md index 597d31a11d9..951ca39bb4c 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["stack-use-after-scope error", "AddressSanitizer error sta > Address Sanitizer Error: Use of out-of-scope stack memory +## Remarks + The use of a stack address outside the lexical scope of a variable's lifetime can happen many ways in C or C++. ## Example 1 - simple nested local @@ -80,7 +82,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 +140,7 @@ void temp_from_conversion() { a.print(); } -void main() { +int main() { explicit_temp(); temp_from_conversion(); } @@ -147,21 +149,23 @@ 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."::: ## 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-strncat-param-overlap.md b/docs/sanitizers/error-strncat-param-overlap.md index 3e183956787..e5569f4faba 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["strncat-param-overlap error", "AddressSanitizer error str > Address Sanitizer Error: strncat-param-overlap +## Remarks + Code that moves memory in overlapping buffer can cause hard-to-diagnose errors. ## Example @@ -47,11 +49,11 @@ devenv /debugexe example1.exe ## 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-use-after-poison.md b/docs/sanitizers/error-use-after-poison.md index 9ef09bd0dc6..d8347318d35 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"] @@ -9,6 +9,8 @@ helpviewer_keywords: ["use-after-poison error", "AddressSanitizer error use-afte > Address Sanitizer Error: Use of poisoned memory +## Remarks + A developer can manually poison memory to customize debugging. ## Example @@ -45,11 +47,11 @@ devenv /debugexe example1.exe ## 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/index.yml b/docs/sanitizers/index.yml index e5db71f5df7..8e8e85e21f4 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 9fcfed85761..3c87f05a036 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 00000000000..dea084d7050 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 78f93cca0af..00000000000 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 abdba93bdc8..c82b594749d 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 fefbc2ca27e..00000000000 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 442f84c23dd..6aa808aa5a5 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 00000000000..1186091bbcd 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 00000000000..7601d818ecc 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 08c82d9d2d8..61d01b04fd9 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 29f4d3ef614..da37249486d 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 9b0c33f9bab..898bef6cf75 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 a1cafb8e9af..f6251f889df 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 75e93087fa5..0db8ff36f64 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 00000000000..3298a14be9f 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 9bd6b4ffcde..ac16359f797 100644 --- a/docs/sanitizers/toc.yml +++ b/docs/sanitizers/toc.yml @@ -6,8 +6,12 @@ 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 options" + href: ../sanitizers/asan-flags.md - name: "Runtime reference" href: ../sanitizers/asan-runtime.md - name: "Debugger integration" @@ -57,5 +61,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/running-as-a-member-of-the-users-group.md b/docs/security/running-as-a-member-of-the-users-group.md index 833678cb72d..0fec514075e 100644 --- a/docs/security/running-as-a-member-of-the-users-group.md +++ b/docs/security/running-as-a-member-of-the-users-group.md @@ -4,6 +4,7 @@ title: "Running as a Member of the Users Group" ms.date: "11/04/2016" helpviewer_keywords: ["Users Group [C++]", "security [C++], Users Group", "Windows accounts [C++]", "non administrator users [C++]", "user accounts [C++]", "administrator (not running as) [C++]"] ms.assetid: e48a03ec-d345-49f6-809a-1a291eecbc81 +ms.topic: concept-article --- # Running as a Member of the Users Group diff --git a/docs/security/security-best-practices-for-cpp.md b/docs/security/security-best-practices-for-cpp.md index 3774d170834..83ffc267e8e 100644 --- a/docs/security/security-best-practices-for-cpp.md +++ b/docs/security/security-best-practices-for-cpp.md @@ -1,35 +1,35 @@ --- -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 +ms.topic: best-practice --- # Security Best Practices for C++ This article contains information about security tools and practices. Using them does not make applications immune from attack, but it makes successful attacks less likely. -## Visual C++ Security Features +## Microsoft C++ Security Features 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 +86,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 c606889e2fa..65b150d64e8 100644 --- a/docs/standard-library/algorithm-functions.md +++ b/docs/standard-library/algorithm-functions.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: functions" title: " functions" +description: "Learn more about: functions" ms.date: 06/07/2022 f1_keywords: ["algorithm/std::adjacent_find", "algorithm/std::all_of", "algorithm/std::any_of", "algorithm/std::binary_search", "algorithm/std::copy", "algorithm/std::copy_backward", "algorithm/std::copy_if", "algorithm/std::copy_n", "algorithm/std::equal", "algorithm/std::equal_range", "algorithm/std::fill", "algorithm/std::fill_n", "algorithm/std::find", "algorithm/std::find_end", "algorithm/std::find_first_of", "algorithm/std::find_if", "algorithm/std::find_if_not", "algorithm/std::for_each", "algorithm/std::generate", "algorithm/std::generate_n", "algorithm/std::includes", "algorithm/std::inplace_merge", "algorithm/std::is_heap", "algorithm/std::is_heap_until", "algorithm/std::is_partitioned", "algorithm/std::is_permutation", "algorithm/std::is_sorted", "algorithm/std::is_sorted_until", "algorithm/std::iter_swap", "algorithm/std::lexicographical_compare", "algorithm/std::lower_bound", "algorithm/std::make_heap", "algorithm/std::max", "algorithm/std::max_element", "algorithm/std::merge", "algorithm/std::min", "algorithm/std::minmax", "algorithm/std::minmax_element", "algorithm/std::min_element", "algorithm/std::mismatch", "algorithm/std::move", "algorithm/std::move_backward", "algorithm/std::next_permutation", "algorithm/std::none_of", "algorithm/std::nth_element", "algorithm/std::partial_sort", "algorithm/std::partial_sort_copy", "algorithm/std::partition", "algorithm/std::partition_point", "algorithm/std::pop_heap", "algorithm/std::prev_permutation", "algorithm/std::push_heap", "algorithm/std::random_shuffle", "algorithm/std::remove", "algorithm/std::remove_copy", "algorithm/std::remove_copy_if", "algorithm/std::remove_if", "algorithm/std::replace", "algorithm/std::replace_copy", "algorithm/std::replace_copy_if", "algorithm/std::replace_if", "algorithm/std::reverse", "algorithm/std::reverse_copy", "algorithm/std::rotate", "algorithm/std::rotate_copy", "algorithm/std::search", "algorithm/std::search_n", "algorithm/std::set_difference", "algorithm/std::set_intersection", "algorithm/std::set_symmetric_difference", "algorithm/std::set_union", "algorithm/std::shuffle", "algorithm/std::sort", "algorithm/std::sort_heap", "algorithm/std::stable_partition", "algorithm/std::stable_sort", "algorithm/std::swap_ranges", "algorithm/std::transform", "algorithm/std::unique", "algorithm/std::unique_copy", "algorithm/std::upper_bound", "xutility/std::copy", "xutility/std::copy_backward", "xutility/std::copy_n", "xutility/std::count", "xutility/std::equal", "xutility/std::fill", "xutility/std::fill_n", "xutility/std::find", "xutility/std::is_permutation", "xutility/std::lexicographical_compare", "xutility/std::move", "xutility/std::move_backward", "xutility/std::reverse", "xutility/std::rotate", "algorithm/std::count_if", "algorithm/std::partition_copy", "algorithm/std::swap"] helpviewer_keywords: ["std::adjacent_find [C++]", "std::all_of [C++]", "std::any_of [C++]", "std::binary_search [C++]", "std::copy [C++]", "std::copy_backward [C++]", "std::copy_if [C++]", "std::copy_n [C++]", "std::equal [C++]", "std::equal_range [C++]", "std::fill [C++]", "std::fill_n [C++]", "std::find [C++]", "std::find_end [C++]", "std::find_first_of [C++]", "std::find_if [C++]", "std::find_if_not [C++]", "std::for_each [C++]", "std::generate [C++]", "std::generate_n [C++]", "std::includes [C++]", "std::inplace_merge [C++]", "std::is_heap [C++]", "std::is_heap_until [C++]", "std::is_partitioned [C++]", "std::is_permutation [C++]", "std::is_sorted [C++]", "std::is_sorted_until [C++]", "std::iter_swap [C++]", "std::lexicographical_compare [C++]", "std::lower_bound [C++]", "std::make_heap [C++]", "std::max [C++]", "std::max_element [C++]", "std::merge [C++]", "std::min [C++]", "std::minmax [C++]", "std::minmax_element [C++]", "std::min_element [C++]", "std::mismatch [C++]", "std::move [C++]", "std::move_backward [C++]", "std::next_permutation [C++]", "std::none_of [C++]", "std::nth_element [C++]", "std::partial_sort [C++]", "std::partial_sort_copy [C++]", "std::partition [C++]", "std::partition_point [C++]", "std::pop_heap [C++]", "std::prev_permutation [C++]", "std::push_heap [C++]", "std::random_shuffle [C++]", "std::remove [C++]", "std::remove_copy [C++]", "std::remove_copy_if [C++]", "std::remove_if [C++]", "std::replace [C++]", "std::replace_copy [C++]", "std::replace_copy_if [C++]", "std::replace_if [C++]", "std::reverse [C++]", "std::reverse_copy [C++]", "std::rotate [C++]", "std::rotate_copy [C++]", "std::search [C++]", "std::search_n [C++]", "std::set_difference [C++]", "std::set_intersection [C++]", "std::set_symmetric_difference [C++]", "std::set_union [C++]", "std::shuffle [C++]", "std::sort [C++]", "std::sort_heap [C++]", "std::stable_partition [C++]", "std::stable_sort [C++]", "std::swap_ranges [C++]", "std::transform [C++]", "std::unique [C++]", "std::unique_copy [C++]", "std::upper_bound [C++]", "std::copy [C++]", "std::copy_backward [C++]", "std::copy_n [C++]", "std::count [C++]", "std::equal [C++]", "std::fill [C++]", "std::fill_n [C++]", "std::find [C++]", "std::is_permutation [C++]", "std::lexicographical_compare [C++]", "std::move [C++]", "std::move_backward [C++]", "std::reverse [C++]", "std::rotate [C++]", "std::count_if [C++]", "std::partition_copy [C++]", "std::swap [C++]"] @@ -8,6 +8,8 @@ ms.custom: devdivchpfy22 --- # `` functions +The `` header provides the following functions: + ## `adjacent_find` Searches for two adjacent elements that are either equal or satisfy a specified condition. @@ -326,7 +328,7 @@ The source ranges aren't modified by `binary_search`. The value types of the forward iterators must be less-than comparable to be ordered. That is, given two elements, you can determine either that one is less than the other, or that they're equivalent. (Here, equivalent means that neither is less than the other.) This comparison results in an ordering between the nonequivalent elements. -The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last` - `first`). +The complexity of the algorithm is logarithmic for random-access iterators and linear otherwise, with the number of steps proportional to (`last-first`). ### Example @@ -593,7 +595,7 @@ An output iterator addressing the position that is one past the final element in The source range must be valid and there must be sufficient space at the destination to hold all the elements being copied. -The `copy_backward` algorithm imposes more stringent requirements than that the `copy` algorithm. Both its input and output iterators must be bidirectional. +The `copy_backward` algorithm imposes more stringent requirements than the `copy` algorithm. Both its input and output iterators must be bidirectional. The `copy_backward` and [`move_backward`](algorithm-functions.md#move_backward) algorithms are the only C++ Standard Library algorithms designating the output range with an iterator pointing to the end of the destination range. @@ -906,13 +908,13 @@ int main() vector::iterator::difference_type result; result = count(v1.begin(), v1.end(), 10); - cout << "The number of 10s in v2 is: " << result << "." << endl; + cout << "The number of 10s in v1 is: " << result << "." << endl; } ``` ```Output v1 = ( 10 20 10 40 10 ) -The number of 10s in v2 is: 3. +The number of 10s in v1 is: 3. ``` ## `count_if` @@ -1336,8 +1338,7 @@ Vector sorted by the binary predicate shorter_than: fun cute blah fluffy kittens meowmeowmeow Result of equal_range with value = fred: - fun [ cute blah ] fluffy kittens meowmeowmeow - + fun [ cute blah ] fluffy kittens meowmeowmeow ``` ## `fill` @@ -2148,7 +2149,7 @@ public: { } - // The function call to process the next elment + // The function call to process the next element void operator( ) ( int elem ) { num++; // Increment the element count @@ -2291,7 +2292,7 @@ public: } }; -// Utility to display the contents of a vector +// Utility to display the contents of a vector template void print_vector(const std::vector &vec) { std::cout << "( "; @@ -2382,7 +2383,7 @@ The function object is invoked for each element in the range and doesn't need to The range referenced must be valid. All pointers must be dereferenceable and, within the sequence, the last position must be reachable from the first by incrementation. -The complexity is linear, with exactly `last` - `first` calls made to the generator. +The complexity is linear, with exactly `last - first` calls made to the generator. ### Example @@ -2685,7 +2686,7 @@ int main() cout << *Iter3b << " "; cout << ")." << endl; - // To test for inclusion under an asscending order + // To test for inclusion under an ascending order // with the default binary predicate less( ) bool Result1; Result1 = includes ( v1a.begin( ), v1a.end( ), @@ -2891,7 +2892,7 @@ int main() // Applying a user defined (UD) binary predicate mod_lesser inplace_merge ( v3.begin( ), break3, v3.end( ), mod_lesser ); cout << "Merged inplace with binary predicate mod_lesser specified,\n " - << "vector v3mod = ( " ; ; + << "vector v3mod = ( " ; for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ ) cout << *Iter3 << " "; cout << ")" << endl; @@ -4423,7 +4424,7 @@ int main() { merge ( v3a.begin( ), v3a.end( ), v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser ); cout << "Merged inplace with binary predicate mod_lesser specified,\n " - << "vector v3mod = ( " ; ; + << "vector v3mod = ( " ; for ( Iter3 = v3.begin( ) ; Iter3 != v3.end( ) ; Iter3++ ) cout << *Iter3 << " "; cout << ")." << endl; @@ -4948,13 +4949,14 @@ Use the dual-range overloads in C++14 code because the overloads that only take ```cpp template -pair> +pair mismatch( InputIterator1 first1, InputIterator1 last1, InputIterator2 first2 ); -template pair> +template +pair mismatch( InputIterator1 first1, InputIterator1 last1, @@ -4963,14 +4965,15 @@ mismatch( //C++14 template -pair> +pair mismatch( InputIterator1 first1, InputIterator1 last1, InputIterator2 first2, InputIterator2 last2 ); -template pair> +template +pair mismatch( InputIterator1 first1, InputIterator1 last1, @@ -5092,7 +5095,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 }; @@ -5585,7 +5587,7 @@ template void partial_sort( RandomAccessIterator first, RandomAccessIterator sortEnd, - RandomAccessIterator last + RandomAccessIterator last, Compare pred); template @@ -5933,7 +5935,7 @@ int main() cout << *Iter1 << " "; cout << ")." << endl; - // Partition the range with predicate greater10 + // Partition the range with predicate greater5 partition ( v1.begin( ), v1.end( ), greater5 ); cout << "The partitioned set of elements in v1 is: ( " ; for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) @@ -6660,7 +6662,7 @@ Vector v2 is a copy of v1 with the value 7 removed: ## `remove_copy_if` -Copies elements from a source range to a destination range, except for elements that satisfy a predicate. Elements are copied without disturbing the order of the remaining elements. Returns the end of a new destination range. +Copies elements from a source range to a destination range, except for elements that satisfy a predicate. Elements are copied without disturbing the order of the remaining elements. Returns the end of a new destination range. ```cpp template @@ -6694,7 +6696,7 @@ An input iterator addressing the position one past the final element in the rang An output iterator addressing the position of the first element in the destination range to which elements are being removed. *`pred`*\ -The unary predicate that must be satisfied is the value of an element is to be replaced. +The unary predicate that must be satisfied if the value of an element is to be replaced. ### Return value @@ -6751,7 +6753,7 @@ int main() new_end = remove_copy_if ( v1.begin( ), v1.end( ), v2.begin( ), greater6 ); - cout << "After the appliation of remove_copy_if to v1,\n " + cout << "After the application of remove_copy_if to v1,\n " << "vector v1 is left unchanged as ( " ; for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) cout << *Iter1 << " "; @@ -6767,7 +6769,7 @@ int main() ```Output The original vector v1 is: ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). -After the appliation of remove_copy_if to v1, +After the application of remove_copy_if to v1, vector v1 is left unchanged as ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). Vector v2 is a copy of v1 with values greater than 6 removed: ( 4 0 5 1 6 3 2 ). @@ -6804,7 +6806,7 @@ A forward iterator pointing to the position of the first element in the range fr A forward iterator pointing to the position one past the final element in the range from which elements are being removed. *`pred`*\ -The unary predicate that must be satisfied is the value of an element is to be replaced. +The unary predicate that must be satisfied if the value of an element is to be replaced. ### Return value @@ -6941,39 +6943,42 @@ The complexity is linear. It makes (`last` - `first`) comparisons for equality a int main() { - using namespace std; - vector v1; - vector::iterator Iter1; + std::vector v; - int i; - for ( i = 0 ; i <= 9 ; i++ ) - v1.push_back( i ); + for (int i = 0; i < 10; i++) + { + v.push_back(i); + } - int ii; - for ( ii = 0 ; ii <= 3 ; ii++ ) - v1.push_back( 7 ); + for (int i = 0; i < 3; i++) + { + v.push_back(7); + } - random_shuffle (v1.begin( ), v1.end( ) ); - cout << "The original vector v1 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; - cout << ")." << endl; + std::cout << "The original vector v is:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + std::cout << *iter << " "; + } + std::cout << ")." << std::endl; // Replace elements with a value of 7 with a value of 700 - replace (v1.begin( ), v1.end( ), 7 , 700); + replace(v.begin(), v.end(), 7, 700); - cout << "The vector v1 with a value 700 replacing that of 7 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; - cout << ")." << endl; + std::cout << "The vector v with 7s replaced with 700s:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + std::cout << *iter << " "; + } + std::cout << ")." << std::endl; } ``` ```Output -The original vector v1 is: - ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). -The vector v1 with a value 700 replacing that of 7 is: - ( 4 700 700 700 0 5 700 1 6 9 3 700 8 2 ). +The original vector v is: + ( 0 1 2 3 4 5 6 7 8 9 7 7 7 ). +The vector v with 7s replaced with 700s: + ( 0 1 2 3 4 5 6 700 8 9 700 700 700 ). ``` ## `replace_copy` @@ -7031,7 +7036,7 @@ The order of the elements not replaced remains stable. The `operator==` used to determine the equality between elements must impose an equivalence relation between its operands. -The complexity is linear. It makes (`last` - `first`) comparisons for equality and at most (`last` - `first`) assignments of new values. +The complexity is linear. It makes (`last - first`) comparisons for equality and at most (`last - first`) assignments of new values. ### Example @@ -7046,58 +7051,65 @@ The complexity is linear. It makes (`last` - `first`) comparisons for equality a int main() { using namespace std; - vector v1; - list L1 (15); - vector::iterator Iter1; - list::iterator L_Iter1; + vector theVector; + list theList(15); - int i; - for ( i = 0 ; i <= 9 ; i++ ) - v1.push_back( i ); - - int ii; - for ( ii = 0 ; ii <= 3 ; ii++ ) - v1.push_back( 7 ); + for (int i = 0; i <= 9; i++) + { + theVector.push_back(i); + } - random_shuffle ( v1.begin( ), v1.end( ) ); + for (int i = 0; i <= 3; i++) + { + theVector.push_back(7); + } - int iii; - for ( iii = 0 ; iii <= 15 ; iii++ ) - v1.push_back( 1 ); + random_shuffle(theVector.begin(), theVector.end()); + + for (int i = 0; i <= 15; i++) + { + theVector.push_back(1); + } - cout << "The original vector v1 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; + cout << "The shuffled vector:\n ( "; + for (auto iter = theVector.begin(); iter != theVector.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; - // Replace elements in one part of a vector with a value of 7 - // with a value of 70 and copy into another part of the vector - replace_copy ( v1.begin( ), v1.begin( ) + 14,v1.end( ) -15, 7 , 70); + // Replace the 7s in part of the vector with 70s + // and copy into another part of the vector + replace_copy(theVector.begin(), theVector.begin() + 14, theVector.end() - 15, 7, 70); - cout << "The vector v1 with a value 70 replacing that of 7 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; + cout << "The vector with instances of 7 replaced with 70 starting at position 14:\n ( "; + for (auto iter = theVector.begin(); iter != theVector.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; - // Replace elements in a vector with a value of 70 - // with a value of 1 and copy into a list - replace_copy ( v1.begin( ), v1.begin( ) + 14,L1.begin( ), 7 , 1); + // Replace 7s found in the first 14 positions in the vector with 1s and then copy the result into a list + replace_copy(theVector.begin(), theVector.begin() + 14, theList.begin(), 7, 1); - cout << "The list copy L1 of v1 with the value 0 replacing " - << "that of 7 is:\n ( " ; - for ( L_Iter1 = L1.begin( ) ; L_Iter1 != L1.end( ) ; L_Iter1++ ) - cout << *L_Iter1 << " "; + cout << "List containing the contents of the vector but 7s replaced with 1s.\n ( "; + for (auto iter = theList.begin(); iter != theList.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; } ``` +Because of the `random_shuffle()` call in the preceding code, your output may be different. + ```Output -The original vector v1 is: - ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). -The vector v1 with a value 70 replacing that of 7 is: - ( 4 70 70 70 0 5 70 1 6 9 3 70 8 2 ). -The list copy L1 of v1 with the value 0 replacing that of 7 is: - ( 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 ). +The shuffled vector: + ( 7 1 9 2 0 7 7 3 4 6 8 5 7 7 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 ). +The vector with instances of 7 replaced with 70 starting at position 14: + ( 7 1 9 2 0 7 7 3 4 6 8 5 7 7 1 70 1 9 2 0 70 70 3 4 6 8 5 70 70 1 ). +List containing the contents of the vector but 7s replaced with 1s. + ( 1 1 9 2 0 1 1 3 4 6 8 5 1 1 0 ). ``` ## `replace_copy_if` @@ -7138,7 +7150,7 @@ An input iterator pointing to the position one past the final element in the ran An output iterator pointing to the position of the first element in the destination range to which elements are being copied. *`pred`*\ -The unary predicate that must be satisfied is the value of an element is to be replaced. +The unary predicate that must be satisfied if the value of an element is to be replaced. *`value`*\ The new value being assigned to the elements whose old value satisfies the predicate. @@ -7267,7 +7279,7 @@ A forward iterator pointing to the position of the first element in the range fr An iterator pointing to the position one past the final element in the range from which elements are being replaced. *`pred`*\ -The unary predicate that must be satisfied is the value of an element is to be replaced. +The unary predicate that must be satisfied if the value of an element is to be replaced. *`value`*\ The new value being assigned to the elements whose old value satisfies the predicate. @@ -7293,7 +7305,7 @@ The complexity is linear. It makes (`last` - `first`) comparisons for equality a #include #include -bool greater6 ( int value ) +bool greater6(int value) { return value > 6; } @@ -7301,41 +7313,40 @@ bool greater6 ( int value ) int main() { using namespace std; - vector v1; - vector::iterator Iter1; - - int i; - for ( i = 0 ; i <= 9 ; i++ ) - v1.push_back( i ); + vector v; - int ii; - for ( ii = 0 ; ii <= 3 ; ii++ ) - v1.push_back( 7 ); + for (int i = 0; i <= 10; i++) + { + v.push_back(i); + } - random_shuffle ( v1.begin( ), v1.end( ) ); - cout << "The original vector v1 is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; + cout << "The original vector v:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + cout << *iter << " "; + } cout << ")." << endl; // Replace elements satisfying the predicate greater6 // with a value of 70 - replace_if ( v1.begin( ), v1.end( ), greater6 , 70); + replace_if(v.begin(), v.end(), greater6, 70); - cout << "The vector v1 with a value 70 replacing those\n " - << "elements satisfying the greater6 predicate is:\n ( " ; - for ( Iter1 = v1.begin( ) ; Iter1 != v1.end( ) ; Iter1++ ) - cout << *Iter1 << " "; - cout << ")." << endl; + cout << "The vector v with a value 70 replacing those\n " + << "elements satisfying the greater6 predicate is:\n ( "; + for (auto iter = v.begin(); iter != v.end(); iter++) + { + cout << *iter << " "; + } + cout << ")."; } ``` ```Output -The original vector v1 is: - ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). -The vector v1 with a value 70 replacing those +The original vector v: + ( 0 1 2 3 4 5 6 7 8 9 10 ). +The vector v with a value 70 replacing those elements satisfying the greater6 predicate is: - ( 4 7 7 7 0 5 7 1 6 9 3 7 8 2 ). + ( 0 1 2 3 4 5 6 70 70 70 70 ). ``` ## `reverse` @@ -7776,7 +7787,7 @@ ForwardIterator1 search( ForwardIterator1 first1, ForwardIterator1 last1, ForwardIterator2 first2, - ForwardIterator2 last2 + ForwardIterator2 last2, BinaryPredicate pred); template @@ -8260,7 +8271,7 @@ int main() cout << *Iter3b << " "; cout << ")." << endl; - // To combine into a difference in asscending + // To combine into a difference in ascending // order with the default binary predicate less( ) Result1 = set_difference ( v1a.begin( ), v1a.end( ), v1b.begin( ), v1b.end( ), v1.begin( ) ); @@ -8285,7 +8296,7 @@ int main() Result3 = set_difference ( v3a.begin( ), v3a.end( ), v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser ); cout << "Set_difference of source ranges with binary " - << "predicate mod_lesser specified,\n vector v3mod = ( " ; ; + << "predicate mod_lesser specified,\n vector v3mod = ( " ; for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; Iter3++ ) cout << *Iter3 << " "; cout << ")." << endl; @@ -8479,7 +8490,7 @@ int main() cout << *Iter3b << " "; cout << ")." << endl; - // To combine into an intersection in asscending order with the + // To combine into an intersection in ascending order with the // default binary predicate less( ) Result1 = set_intersection ( v1a.begin( ), v1a.end( ), v1b.begin( ), v1b.end( ), v1.begin( ) ); @@ -8504,7 +8515,7 @@ int main() Result3 = set_intersection ( v3a.begin( ), v3a.end( ), v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser ); cout << "Intersection of source ranges with binary predicate " - << "mod_lesser specified,\n vector v3mod = ( " ; ; + << "mod_lesser specified,\n vector v3mod = ( " ; for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; ++Iter3 ) cout << *Iter3 << " "; cout << ")." << endl; @@ -8727,7 +8738,7 @@ int main() Result3 = set_symmetric_difference ( v3a.begin( ), v3a.end( ), v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser ); cout << "Set_symmetric_difference of source ranges with binary " - << "predicate mod_lesser specified,\n vector v3mod = ( " ; ; + << "predicate mod_lesser specified,\n vector v3mod = ( " ; for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; Iter3++ ) cout << *Iter3 << " "; cout << ")." << endl; @@ -8950,7 +8961,7 @@ int main() Result3 = set_union ( v3a.begin( ), v3a.end( ), v3b.begin( ), v3b.end( ), v3.begin( ), mod_lesser ); cout << "Union of source ranges with binary predicate " - << "mod_lesser specified,\n vector v3mod = ( " ; ; + << "mod_lesser specified,\n vector v3mod = ( " ; for ( Iter3 = v3.begin( ) ; Iter3 != Result3 ; Iter3++ ) cout << *Iter3 << " "; cout << ")." << endl; @@ -9161,7 +9172,7 @@ Heaps have two properties: - Elements may be added or removed in logarithmic time. -After the application if this algorithm, the range it was applied to is no longer a heap. +After the application of this algorithm, the range it was applied to is no longer a heap. `sort_heap` isn't a stable sort because the relative order of equivalent elements isn't necessarily preserved. @@ -9576,7 +9587,7 @@ A forward iterator pointing to one past the final position of the second range w The ranges referenced must be valid; all pointers must be dereferenceable and within each sequence the last position is reachable from the first by incrementation. The second range has to be as large as the first range. -The complexity is linear with *last1* - *first1* swaps performed. If elements from containers of the same type are being swapped, them the `swap` member function from that container should be used, because the member function typically has constant complexity. +The complexity is linear with *last1* - *first1* swaps performed. If elements from containers of the same type are being swapped, then the `swap` member function from that container should be used, because the member function typically has constant complexity. ### Example @@ -9913,7 +9924,7 @@ int main() cout << *v1_Iter1 << " "; cout << ")." << endl; - // Remove consecutive duplicates under the binary prediate mod_equals + // Remove consecutive duplicates under the binary predicate mod_equals v1_NewEnd2 = unique ( v1.begin( ), v1_NewEnd1 , mod_equal ); cout << "Removing adjacent duplicates from vector v1 under the\n " @@ -10069,7 +10080,7 @@ int main() { for ( iv = 0 ; iv <= 7 ; iv++ ) v1.push_back( 10 ); - // Remove consecutive duplicates under the binary prediate mod_equals + // Remove consecutive duplicates under the binary predicate mod_equals v1_NewEnd2 = unique_copy ( v1.begin( ), v1.begin( ) + 14, v1.begin( ) + 14 , mod_equal ); @@ -10242,4 +10253,4 @@ Original vector v3 with range sorted by the The upper_bound in v1 for the element with a value of 3 is: 4. The upper_bound in v2 for the element with a value of 3 is: 2. The upper_bound in v3 for the element with a value of 3 is: 4. -``` \ No newline at end of file +``` diff --git a/docs/standard-library/algorithm.md b/docs/standard-library/algorithm.md index 8ab79fbea5e..7db53924b19 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 8fc2d50ed5a..b79a77b3b30 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/allocator-class.md b/docs/standard-library/allocator-class.md index 86e07e0e632..8c090dd434b 100644 --- a/docs/standard-library/allocator-class.md +++ b/docs/standard-library/allocator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: allocator Class" title: "allocator Class" -ms.date: "11/04/2016" +description: "Learn more about: allocator Class" +ms.date: 11/04/2016 f1_keywords: ["memory/std::allocator", "memory/std::allocator::const_pointer", "memory/std::allocator::const_reference", "memory/std::allocator::difference_type", "memory/std::allocator::pointer", "memory/std::allocator::reference", "memory/std::allocator::size_type", "memory/std::allocator::value_type", "memory/std::allocator::address", "memory/std::allocator::allocate", "memory/std::allocator::construct", "memory/std::allocator::deallocate", "memory/std::allocator::destroy", "memory/std::allocator::max_size", "memory/std::allocator::rebind"] helpviewer_keywords: ["std::allocator [C++]", "std::allocator [C++], const_pointer", "std::allocator [C++], const_reference", "std::allocator [C++], difference_type", "std::allocator [C++], pointer", "std::allocator [C++], reference", "std::allocator [C++], size_type", "std::allocator [C++], value_type", "std::allocator [C++], address", "std::allocator [C++], allocate", "std::allocator [C++], construct", "std::allocator [C++], deallocate", "std::allocator [C++], destroy", "std::allocator [C++], max_size", "std::allocator [C++], rebind"] -ms.assetid: 3fd58076-56cc-43bb-ad58-b4b7c9c6b410 --- # allocator Class @@ -396,7 +395,7 @@ int main( ) // vcref = 150; // but the value of the first element could be modified through // its nonconst iterator and the const reference would remain valid -*vfIter = 175; + *vfIter = 175; cout << "The value of the element referred to by vcref," <<"\n after nofication through its nonconst iterator, is: " << vcref << "." << endl; @@ -1024,7 +1023,7 @@ int main( ) vfIter = v.begin( ); allocator::value_type vecVal = 150.0; -*vfIter = vecVal; + *vfIter = vecVal; cout << "The value of the element addressed by vfIter is: " << *vfIter << ",\n the first element in the vector." << endl; diff --git a/docs/standard-library/allocators-functions.md b/docs/standard-library/allocators-functions.md index adcaabbd4e9..47258c46189 100644 --- a/docs/standard-library/allocators-functions.md +++ b/docs/standard-library/allocators-functions.md @@ -1,28 +1,13 @@ --- -description: "Learn more about: macros" title: " macros" -ms.date: "11/04/2016" +description: "Learn more about: macros" +ms.date: 11/04/2016 f1_keywords: ["allocators/std::ALLOCATOR_DECL", "allocators/std::CACHE_CHUNKLIST", "allocators/std::CACHE_FREELIST", "allocators/std::CACHE_SUBALLOC", "allocators/std::SYNC_DEFAULT"] -ms.assetid: 9cb5ee07-1ff9-4594-ae32-3c8c6efb511a helpviewer_keywords: ["std::ALLOCATOR_DECL [C++]", "std::CACHE_CHUNKLIST [C++]", "std::CACHE_FREELIST [C++]", "std::CACHE_SUBALLOC [C++]", "std::SYNC_DEFAULT [C++]"] --- # `` macros -:::row::: - :::column span=""::: - [`ALLOCATOR_DECL`](#allocator_decl)\ - [`CACHE_CHUNKLIST`](#cache_chunklist) - :::column-end::: - :::column span=""::: - [`CACHE_FREELIST`](#cache_freelist) - :::column-end::: - :::column span=""::: - [`CACHE_SUBALLOC`](#cache_suballoc) - :::column-end::: - :::column span=""::: - [`SYNC_DEFAULT`](#sync_default) - :::column-end::: -:::row-end::: +The `` header provides the following macros: ## ALLOCATOR_DECL @@ -72,8 +57,6 @@ Yields `stdext::allocators::cache_chunklist`. #define CACHE_CHUNKLIST ``` -### Remarks - ## CACHE_FREELIST Yields `stdext::allocators::cache_freelist`. @@ -82,8 +65,6 @@ Yields `stdext::allocators::cache_freelist`. #define CACHE_FREELIST(max) ``` -### Remarks - ## CACHE_SUBALLOC Yields `stdext::allocators::cache_suballoc`. @@ -92,8 +73,6 @@ Yields `stdext::allocators::cache_suballoc`. #define CACHE_SUBALLOC ``` -### Remarks - ## SYNC_DEFAULT Yields a synchronization filter. diff --git a/docs/standard-library/allocators-operators.md b/docs/standard-library/allocators-operators.md index 90936ade68c..8deacf84301 100644 --- a/docs/standard-library/allocators-operators.md +++ b/docs/standard-library/allocators-operators.md @@ -1,18 +1,14 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 11/04/2016 f1_keywords: ["allocators/std::operator!=", "allocators/std::operator=="] -ms.assetid: b55d67cb-3c69-46bf-ad40-e845fb096c4e --- # `` operators These are the global template operator functions defined in ``. For class member operator functions, see the class documentation. -[operator!=](#op_neq)\ -[operator==](#op_eq_eq) - -## operator!= +## `operator!=` Tests for inequality between allocator objects of a specified class. @@ -25,10 +21,10 @@ bool operator!=( ### Parameters -*left*\ +*`left`*\ One of the allocator objects to be tested for inequality. -*right*\ +*`right`*\ One of the allocator objects to be tested for inequality. ### Return Value @@ -39,7 +35,7 @@ One of the allocator objects to be tested for inequality. The template operator returns `!(left == right)`. -## operator== +## `operator==` Tests for equality between allocator objects of a specified class. @@ -52,10 +48,10 @@ bool operator==( ### Parameters -*left*\ +*`left`*\ One of the allocator objects to be tested for equality. -*right*\ +*`right`*\ One of the allocator objects to be tested for equality. ### Return Value @@ -68,4 +64,4 @@ This template operator returns `left.equals(right)`. ## See also -[\](allocators-header.md) +[``](allocators-header.md) diff --git a/docs/standard-library/ambiguous-local-time.md b/docs/standard-library/ambiguous-local-time.md index ba8c48c825b..d90b87dcedc 100644 --- a/docs/standard-library/ambiguous-local-time.md +++ b/docs/standard-library/ambiguous-local-time.md @@ -1,9 +1,9 @@ --- -description: "Learn more about: ambiguous_local_time class" title: "ambiguous_local_time class" +description: "Learn more about: ambiguous_local_time class" ms.date: 10/08/2021 f1_keywords: ["chrono/std::chrono::ambiguous_local_time", "chrono/std::chrono::ambiguous_local_time::what"] -helpviewer_keywords: ["std::chrono [C++], ambiguous_local_time"] +helpviewer_keywords: ["std::chrono [C++], ambiguous_local_time"] dev_langs: ["C++"] --- @@ -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-functions.md b/docs/standard-library/any-functions.md index 27ebce791b9..aa9ef35d532 100644 --- a/docs/standard-library/any-functions.md +++ b/docs/standard-library/any-functions.md @@ -1,6 +1,6 @@ --- -description: "Learn more about the free functions for use with the std::any class in the C++ Standard Library." title: " functions" +description: "Learn more about the free functions for use with the std::any class in the C++ Standard Library." ms.date: 09/20/2021 f1_keywords: ["any/std::any_cast", "any/std::make_any", "any/std::swap"] no-loc: ["any", "std", "class"] @@ -11,7 +11,7 @@ The [``](any.md) header declares several free functions for working with th ## Functions -|   |   | +| Name | Description | |--|--| | [`any_cast`](#any_cast) | Makes an object into an `any`. | | [`make_any`](#make_any) | Takes values and creates an `any` object. | diff --git a/docs/standard-library/any.md b/docs/standard-library/any.md index d1302376e5d..752a8bda88a 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 d3380f16f9c..29f281de652 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-functions.md b/docs/standard-library/array-functions.md index a670f42c5bf..8ba4d4fcbca 100644 --- a/docs/standard-library/array-functions.md +++ b/docs/standard-library/array-functions.md @@ -1,45 +1,46 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" -f1_keywords: ["array/std::array::get", "array/std::get", "array/std::swap"] -ms.assetid: e0700a33-a833-4655-8735-16e71175efc8 -helpviewer_keywords: ["std::array [C++], get", "std::get [C++]", "std::swap [C++]"] +description: "Learn more about: functions" +ms.date: 08/20/2025 +f1_keywords: ["array/std::array::get", "array/std::get", "array/std::swap", "array/std::to_array"] +helpviewer_keywords: ["std::array [C++], get", "std::get [C++]", "std::swap [C++]", "std::to_array [C++]"] --- # `` functions -The \ header includes two non-member functions, `get` and `swap`, that operate on **array** objects. - -[get](#get)\ -[swap](#swap) +The `` header includes three non-member functions, `get`, `swap`, and `to_array` that operate on **array** objects. -## get +## `get` Returns a reference to the specified element of the array. ```cpp -template -constexpr T& get(array& arr) noexcept; +template +constexpr Type& get(std::array& arr) noexcept; -template -constexpr const T& get(const array& arr) noexcept; +template +constexpr const Type& get(const std::array& arr) noexcept; -template -constexpr T&& get(array&& arr) noexcept; +template +constexpr Type&& get(std::array&& arr) noexcept; + +template +constexpr const Type&& get(const std::array&& arr) noexcept; ``` -### Parameters +### Template parameters -*Index*\ +*`Index`*\ The element offset. -*T*\ +*`Type`*\ The type of an element. -*N*\ +*`Size`*\ The number of elements in the array. -*arr*\ +### Parameters + +*`arr`*\ The array to select from. ### Example @@ -74,27 +75,29 @@ int main() 1 3 ``` -## swap +## `swap` A non-member template specialization of `std::swap` that swaps two **array** objects. ```cpp -template -void swap(array& left, array& right); +template +void swap(std::array& left, std::array& right); ``` -### Parameters +### Template parameters -*Ty*\ +*`Type`*\ The type of an element. -*N*\ +*`Size`*\ The size of the array. -*left*\ +### Parameters + +*`left`*\ The first array to swap. -*right*\ +*`right`*\ The second array to swap. ### Remarks @@ -147,6 +150,74 @@ int main() 0 1 2 3 ``` +## `to_array` + +Converts a built-in array to a `std::array` object. + +```cpp +// C++20 +template +constexpr std::array, Size> to_array(Type (&arr)[Size]); + +// C++20 +template +constexpr std::array, Size> to_array(Type (&&arr)[Size]); +``` + +### Template parameters + +*`Type`*\ +The type of an element. + +*`Size`*\ +The size of the input array. + +### Parameters + +*`arr`*\ +The input array used for conversion. + +### Example + +```cpp +// std_to_array.cpp +// Requires /std:c++20 or later + +#include +#include + +int main() +{ + int arr1[]{ 1, 2, 3 }; + std::array arr2 = std::to_array(arr1); + + std::cout << "std::to_array(arr1):\n"; + for (const auto& i : arr2) + { + std::cout << i << " "; + } + std::cout << std::endl; + + // The size is 7 as it includes the null terminator + std::array arr3 = std::to_array("string"); + + std::cout << "\nstd::to_array(\"string\"):\n"; + for (const auto& i : arr3) + { + std::cout << i << " "; + } + std::cout << std::endl; +} +``` + +```Output +std::to_array(arr1): +1 2 3 + +std::to_array("string"): +s t r i n g +``` + ## See also -[\](../standard-library/array.md) +[``](array.md) diff --git a/docs/standard-library/array-operators.md b/docs/standard-library/array-operators.md index 866d09f22ef..64b0e538b99 100644 --- a/docs/standard-library/array-operators.md +++ b/docs/standard-library/array-operators.md @@ -1,27 +1,19 @@ --- -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 -The \ header includes these **array** non-member comparison template functions. - -[operator!=](#op_neq)\ -[`operator>`](#op_gt)\ -[`operator>=`](#op_gt_eq)\ -[`operator<`](#op_lt)\ -[`operator<=`](#op_lt_eq)\ -[operator==](#op_eq_eq) +The `` header includes these **array** non-member comparison template functions. -## operator!= +## `operator!=` Array comparison, not equal. ```cpp -template +template bool operator!=( const array& left, const array& right); @@ -29,16 +21,16 @@ bool operator!=( ### Parameters -*Ty*\ +*`Ty`*\ The type of an element. -*N*\ +*`N`*\ The size of the array. -*left*\ +*`left`*\ Left container to compare. -*right*\ +*`right`*\ Right container to compare. ### Remarks @@ -94,7 +86,7 @@ true Array comparison, less than. ```cpp -template +template bool operator<( const array& left, const array& right); @@ -102,21 +94,21 @@ bool operator<( ### Parameters -*Ty*\ +*`Ty`*\ The type of an element. -*N*\ +*`N`*\ The size of the array. -*left*\ +*`left`*\ Left container to compare. -*right*\ +*`right`*\ 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 @@ -167,7 +159,7 @@ true Array comparison, less than or equal. ```cpp -template +template bool operator<=( const array& left, const array& right); @@ -175,16 +167,16 @@ bool operator<=( ### Parameters -*Ty*\ +*`Ty`*\ The type of an element. -*N*\ +*`N`*\ The size of the array. -*left*\ +*`left`*\ Left container to compare. -*right*\ +*`right`*\ Right container to compare. ### Remarks @@ -235,12 +227,12 @@ true false ``` -## operator== +## `operator==` Array comparison, equal. ```cpp -template +template bool operator==( const array& left, const array& right); @@ -248,21 +240,21 @@ bool operator==( ### Parameters -*Ty*\ +*`Ty`*\ The type of an element. -*N*\ +*`N`*\ The size of the array. -*left*\ +*`left`*\ Left container to compare. -*right*\ +*`right`*\ 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 @@ -313,7 +305,7 @@ false Array comparison, greater than. ```cpp -template +template bool operator>( const array& left, const array& right); @@ -321,16 +313,16 @@ bool operator>( ### Parameters -*Ty*\ +*`Ty`*\ The type of an element. -*N*\ +*`N`*\ The size of the array. -*left*\ +*`left`*\ Left container to compare. -*right*\ +*`right`*\ Right container to compare. ### Remarks @@ -386,7 +378,7 @@ true Array comparison, greater than or equal. ```cpp -template +template bool operator>=( const array& left, const array& right); @@ -394,16 +386,16 @@ bool operator>=( ### Parameters -*Ty*\ +*`Ty`*\ The type of an element. -*N*\ +*`N`*\ The size of the array. -*left*\ +*`left`*\ Left container to compare. -*right*\ +*`right`*\ Right container to compare. ### Remarks @@ -456,4 +448,4 @@ false ## See also -[\](../standard-library/array.md) +[``](../standard-library/array.md) diff --git a/docs/standard-library/array.md b/docs/standard-library/array.md index 85273440ba3..331316ee9e2 100644 --- a/docs/standard-library/array.md +++ b/docs/standard-library/array.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: ["array header"] --- @@ -45,6 +45,7 @@ Defines the container class template **array** and several supporting templates. |-|-| |[get](../standard-library/array-functions.md#get)|Get specified array element.| |[swap](../standard-library/array-functions.md#swap)|Exchanges the contents of one array with the contents of another array.| +| [`to_array`](array-functions.md#to_array) | Converts a built-in array to a `std::array` object. | ## See also diff --git a/docs/standard-library/atomic-functions.md b/docs/standard-library/atomic-functions.md index a8a8db35d41..9dcd5b5baed 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 03e99234bc7..9ee633323fe 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 31235b6c2d7..3eda9ff3615 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). @@ -21,8 +20,7 @@ For more information about `throw()` and exception handling, see [Exception Spec class auto_ptr { typedef Type element_type; explicit auto_ptr(Type* ptr = 0) throw(); - auto_ptr(auto_ptr& right) throw() - ; + auto_ptr(auto_ptr& right) throw(); template operator auto_ptr() throw(); template @@ -41,10 +39,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 +57,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 +100,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 +133,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 +210,11 @@ public: { x = i; cout << "Constructing " << ( void* )this << " Value: " << x << endl; - }; + } ~Int( ) { cout << "Destructing " << ( void* )this << " Value: " << x << endl; - }; + } int x; @@ -242,7 +240,7 @@ pi2 == pi3 Destructing 00311B88 Value: 6 ``` -### operator= +### `operator=` An assignment operator that transfers ownership from one `auto_ptr` object to another. @@ -255,7 +253,7 @@ auto_ptr& operator=(auto_ptr_ref right) throw(); #### Parameters -*right*\ +*`right`*\ An object of type `auto_ptr`. #### Return Value @@ -264,13 +262,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 +282,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 +302,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 +319,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 +349,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 +376,7 @@ public: int m_i; }; void f(auto_ptr arg) { -}; +} int main() { const auto_ptr ciap(new C(1)); @@ -401,7 +399,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 +432,10 @@ public: { x = i; cout << "Constructing " << (void*)this << " Value: " << x << endl; - }; + } ~Int() { cout << "Destructing " << (void*)this << " Value: " << x << endl; - }; + } int x; @@ -463,7 +461,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 +471,7 @@ void reset(Type* ptr = 0); #### Parameters -*ptr*\ +*`ptr`*\ The pointer specified to replace the stored pointer `myptr`. #### Example @@ -494,11 +492,11 @@ public: { x = i; cout << "Constructing " << (void*)this << " Value: " << x << endl; - }; + } ~Int() { cout << "Destructing " << (void*)this << " Value: " << x << endl; - }; + } int x; }; @@ -525,4 +523,4 @@ Destructing 00311B88 Value: 6 ## See also -[unique_ptr Class](../standard-library/unique-ptr-class.md) +[`unique_ptr Class`](../standard-library/unique-ptr-class.md) diff --git a/docs/standard-library/back-insert-iterator-class.md b/docs/standard-library/back-insert-iterator-class.md index 41038cc72eb..2134ccf1b15 100644 --- a/docs/standard-library/back-insert-iterator-class.md +++ b/docs/standard-library/back-insert-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: back_insert_iterator Class" title: "back_insert_iterator Class" +description: "Learn more about: back_insert_iterator Class" ms.date: 06/07/2022 f1_keywords: ["iterator/std::back_insert_iterator", "iterator/std::back_insert_iterator::container_type", "iterator/std::back_insert_iterator::reference"] helpviewer_keywords: ["std::back_insert_iterator [C++]", "std::back_insert_iterator [C++], container_type", "std::back_insert_iterator [C++], reference"] -ms.assetid: a1ee07f2-cf9f-46a1-8608-cfaf207f9713 ms.custom: devdivchpfy22 --- # back_insert_iterator Class @@ -103,9 +102,9 @@ int main( ) // Alternatively, insertions can be done with template function back_insert_iterator > backiter ( vec ); -*backiter = 600; + *backiter = 600; backiter++; -*backiter = 700; + *backiter = 700; cout << "After the insertions, the vector vec is: ( "; for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++) @@ -216,9 +215,9 @@ int main( ) cout << ")." << endl; back_insert_iterator > backiter ( vec ); -*backiter = 10; + *backiter = 10; backiter++; // Increment to the next element -*backiter = 20; + *backiter = 20; backiter++; cout << "After the insertions, the vector vec becomes: ( "; @@ -277,9 +276,9 @@ int main( ) cout << ")." << endl; back_insert_iterator > backiter ( vec ); -*backiter = 30; + *backiter = 30; backiter++; // Increment to the next element -*backiter = 40; + *backiter = 40; backiter++; cout << "After the insertions, the vector vec becomes: ( "; @@ -349,9 +348,9 @@ int main( ) cout << ")." << endl; back_insert_iterator > backiter ( vec ); -*backiter = 10; + *backiter = 10; backiter++; // Increment to the next element -*backiter = 20; + *backiter = 20; backiter++; cout << "After the insertions, the vector vec becomes: ( "; diff --git a/docs/standard-library/bad-alloc-class.md b/docs/standard-library/bad-alloc-class.md index 9cd3cc8bd87..f18b4ca87ec 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 7ddc445a518..3a9f9883a8c 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-ios-class.md b/docs/standard-library/basic-ios-class.md index c5682baed39..28cdc9a600c 100644 --- a/docs/standard-library/basic-ios-class.md +++ b/docs/standard-library/basic-ios-class.md @@ -13,7 +13,6 @@ The class template describes the storage and member functions common to both inp ## Syntax ```cpp - template class basic_ios : public ios_base ``` diff --git a/docs/standard-library/basic-istream-class.md b/docs/standard-library/basic-istream-class.md index 26641c85049..a5ebefeccee 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"] @@ -119,7 +119,7 @@ See the example for [`basic_ifstream` Class](../standard-library/basic-ifstream- |[`swap`](#swap)|Exchanges this `basic_istream` object for the provided `basic_istream` object parameter.| |[`sync`](#sync)|Synchronizes the stream's associated input device with the stream's buffer.| |[`tellg`](#tellg)|Reports the current read position in the stream.| -|[u`nget](#unget)|Puts the most recently read character back into the stream.| +|[`unget`](#unget)|Puts the most recently read character back into the stream.| ### Operators @@ -161,7 +161,7 @@ A `basic_istream` object to copy. The first constructor initializes the base class by calling `init(strbuf)`. It also stores zero in the extraction count. For more information, see [`init`](../standard-library/basic-ios-class.md#init). And for more information about this extraction count, see the Remarks section of the [`basic_istream` Class](../standard-library/basic-istream-class.md) overview. -The second constructor initializes the base class by calling `move(right)`. It also stores `right.gcount()` in the extraction count and stores zero in the extraction count for *`right`**. +The second constructor initializes the base class by calling `move(right)`. It also stores `right.gcount()` in the extraction count and stores zero in the extraction count for *`right`*. ### Example @@ -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 new file mode 100644 index 00000000000..e1aa2cc2930 --- /dev/null +++ b/docs/standard-library/basic-istream-view-class.md @@ -0,0 +1,214 @@ +--- +title: basic_istream_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) basic_istream_view class, which reads (using operator>>) successive elements from an input stream. Also includes the istream_view and wistream_view specializations." +ms.date: 11/07/2022 +f1_keywords: ["ranges/std::basic_istream_view", "ranges/std::istream_view", "ranges/std::wistream_view", "ranges/std::basic_istream_view::begin", "ranges/std::basic_istream_view::end", "ranges/std::istream_view::begin", "ranges/std::istream_view::end", "ranges/std::wistream_view::begin", "ranges/std::wistream_view::end"] +helpviewer_keywords: ["std::ranges::basic_istream_view [C++]", "std::ranges::istream_view [C++]", "std::ranges::wistream_view [C++]", "std::ranges::basic_istream_view::base [C++]", "std::ranges::basic_istream_view::begin [C++]", "std::ranges::basic_istream_view::end [C++]", ] +dev_langs: ["C++"] +--- +# `basic_istream_view` class (C++ Standard Library) + +A view of successive elements from an input stream. + +## Syntax + +```cpp +template + requires default_initializable && + stream_extractable +class basic_istream_view : public view_interface>; +``` + +### Template parameters + +*`CharT`*\ +The character type of the stream. + +*`Traits`*\ +Optional. Provides details about the character type of the stream regarding comparing characters, determining the length of a string made up of that character type, and so on. An example trait is [`char_traits`](char-traits-wchar-t-struct.md). If not specified, defaults to `char_traits`. + +*`Val`*\ +The type of the elements to extract. For example, `double` given a stream of: `"1.1 2.2 3.3"` + +`stream_extractable` refers to the requirement (concept) that the type `Val` can be extracted from a stream using the `operator>>` function. It's equivalent to: + +```cpp +template +concept stream_extractable = + requires(std::basic_istream& is, Val& t) { + is >> t; + }; +``` + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`istream`](range-adaptors.md#istream) | +| **Underlying range** | None | +| **Element type** |The same as `Val` | +| **View iterator category** | [`input_range`](range-concepts.md#input_range) | +| **Sized** | No | +| **Is `const`-iterable** | No | +| **Common range** | No | +| **Borrowed range** | No | + +## Specializations:`istream_view` and `wistream_view` + +Convenience alias templates are provided for `char` and `wchar_t` streams, as follows: + +```cpp +1) template +using istream_view = ranges::basic_istream_view; + +2) template +using wistream_view = ranges::basic_istream_view; +``` + +1\) Reads elements from an input stream composed of `char` characters.\ +2\) Reads elements from an input stream composed of `wchar_t` characters. + +For 1) and 2), `Val` refers to the type of the elements to extract. For example, `Val` is `double` given a stream of: `"1.1 2.2 3.3"` + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `basic_istream_view`. | +| [`begin`](#begin)C++20 | Read the first value and get an iterator for the view. | +| [`end`](#end)C++20 | Returns `std::default_sentinel` | + +No member functions are inherited from `view_interface`. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `basic_istream_view`. + +```cpp +constexpr explicit +basic_istream_view(std::basic_istream& stream); +``` + +### Parameters + +*`stream`*\ +The stream to read from. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `basic_istream_view` instance. The `basic_istream_view` internal stream pointer is initialized to `addressof(stream)`. + +### Remarks + +The best way to create a `basic_istream_view` is by using the [`views::istream`](range-adaptors.md#istream) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +### Example: `basic_istream_view`, `istream_view`, and `wistream_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + // range adaptor + std::istringstream streamOfdoubles{ "1.1 2.2 3.3 4.4 5.5" }; + for (const auto& elem : std::views::istream(streamOfdoubles)) + { + std::cout << elem << ' '; // 1.1 2.2 3.3 4.4 5.5 + } + std::cout << '\n'; + + // range adaptor - create a wistream_view + std::wistringstream streamOfInts{ L"1 2 3 4 5" }; + for (const auto& elem : std::views::istream(streamOfInts)) + { + std::cout << elem << ' '; // 1 2 3 4 5 + } + std::cout << '\n'; + + // istream_view alias + std::istringstream cpu1{ "8 0 8 0" }; + // equivalent std::ranges::istream_view + for (const auto& elem : std::ranges::istream_view{cpu1}) + { + std::cout << elem; // 8080 + } + std::cout << '\n'; + + // wistream_view alias + std::wistringstream cpu2{ L"6 5 0 2" }; + // equivalent std::ranges::istream_view + for (const auto& elem : std::ranges::wistream_view{cpu2}) + { + std::cout << elem; // 6502 + } + std::cout << '\n'; + + // specify all template arguments + std::wistringstream misc(L"S T L"); + std::ranges::basic_istream_view> basic{misc}; + for (const auto& elem : basic) + { + std::wcout << elem << ' '; // S T L + } +} +``` + +```output +1.1 2.2 3.3 4.4 5.5 +1 2 3 4 5 +8080 +6502 +S T L +``` + +## `begin` + +Read the first value and get an iterator to the view. + +```cpp +constexpr auto begin(); +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `basic_istream_view`. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr std::default_sentinel_t end() const noexcept; +``` + +### Parameters + +None. + +### Return value + +`default_sentinel_t` + +## See also + +[``](ranges.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/basic-istringstream-class.md b/docs/standard-library/basic-istringstream-class.md index 65784d35920..ddae99f87f7 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 --- @@ -103,7 +102,7 @@ An rvalue reference of a `basic_istringstream` object. ### Remarks -The first constructor initializes the base class by calling `basic_istream]( sb )`, where `sb` is the stored object of class `basic_stringbuf< Elem, Tr, Alloc>`. It also initializes `sb` by calling `basic_stringbuf< Elem, Tr, Alloc >( _Mode | ios_base::in )`. For more information, see [`basic_istream`](../standard-library/basic-istream-class.md) and [`basic_stringbuf`](../standard-library/basic-stringbuf-class.md). +The first constructor initializes the base class by calling `basic_istream( sb )`, where `sb` is the stored object of class `basic_stringbuf< Elem, Tr, Alloc>`. It also initializes `sb` by calling `basic_stringbuf< Elem, Tr, Alloc >( _Mode | ios_base::in )`. For more information, see [`basic_istream`](../standard-library/basic-istream-class.md) and [`basic_stringbuf`](../standard-library/basic-stringbuf-class.md). The second constructor initializes the base class by calling `basic_istream( sb )`. It also initializes `sb` by calling `basic_stringbuf< Elem, Tr, Alloc >( str, _Mode | ios_base::in )`. @@ -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 6365780620d..a2b1b7e6520 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 1b79c1a3d2a..29ff6874a72 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 e6720817633..4a543f3fef7 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 d1bb3eb2dfe..d91955cfbfc 100644 --- a/docs/standard-library/basic-string-class.md +++ b/docs/standard-library/basic-string-class.md @@ -1,13 +1,13 @@ --- -title: "basic_string Class" +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 --- -# `basic_string` Class +# `basic_string` class The sequences controlled by an object of type `basic_string` are the Standard C++ string class and are referred to as strings, but they shouldn't be confused with the null-terminated C-style strings used throughout the C++ Standard Library. The Standard C++ string is a container that enables the use of strings as normal types, such as comparison and concatenation operations, iterators, C++ Standard Library algorithms, and copying and assigning with class allocator-managed memory. If you need to convert a Standard C++ string to a null-terminated C-style string, use the [`basic_string::c_str`](#c_str) member. @@ -18,13 +18,13 @@ template , class Allocator class basic_string; ``` -### Parameters +### Template parameters *`CharType`*\ -The data type of a single character to be stored in the string. The C++ Standard Library provides specializations of this class template, with the type definitions [`string`](../standard-library/string-typedefs.md#string) for elements of type `char`, [`wstring`](../standard-library/string-typedefs.md#wstring), for `wchar_t`, [`u16string`](../standard-library/string-typedefs.md#u16string) for `char16_t`, and [`u32string`](../standard-library/string-typedefs.md#u32string) for `char32_t`. +The data type of a single character to be stored in the string. The C++ Standard Library provides specializations of this class template, with the type definitions [`string`](string-typedefs.md#string) for elements of type `char`, [`wstring`](string-typedefs.md#wstring), for `wchar_t`, [`u16string`](string-typedefs.md#u16string) for `char16_t`, and [`u32string`](string-typedefs.md#u32string) for `char32_t`. *`Traits`*\ -Various important properties of the `CharType` elements in a basic_string specialization are described by the class `Traits`. The default value is `char_traits`<`CharType`>. +Various important properties of the `CharType` elements in a `basic_string` specialization are described by the class `Traits`. The default value is `char_traits`<`CharType`>. *`Allocator`*\ The type that represents the stored allocator object that encapsulates details about the string's allocation and deallocation of memory. The default value is `allocator`. @@ -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.| @@ -117,22 +117,22 @@ The headers that define `basic_string` also define the following [user-defined l | Declaration | Description | |--|--| | `inline string operator"" s(const char* str, size_t len)` | Returns: `string(str, len)` | -| `inline string operator"" s(const wchar_t* str, size_t len)` | Returns: `wstring(str, len)` | +| `inline wstring operator"" s(const wchar_t* str, size_t len)` | Returns: `wstring(str, len)` | | `inline basic_string operator"" s(const char8_t* str, size_t len)` | Returns: `basic_string(str, len)` | | `inline u16string operator"" s(const char16_t* str, size_t len)` | Returns: `u16string(str, len)` | | `inline u32string operator"" s(const char32_t* str, size_t len)` | Returns: `u32string(str, len)` | ## Remarks -If a function is asked to generate a sequence longer than [`max_size`](#max_size) elements, the function reports a length error by throwing an object of type [`length_error`](../standard-library/length-error-class.md). +If a function is asked to generate a sequence longer than [`max_size`](#max_size) elements, the function reports a length error by throwing an object of type [`length_error`](length-error-class.md). References, pointers, and iterators that designate elements of the controlled sequence can become invalid after any call to a function that alters the controlled sequence, or after the first call to a non-`const` member function. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## `basic_string::allocator_type` @@ -279,12 +279,12 @@ int main( ) // appending one string to another in two ways, // comparing append and operator [ ] string str1d ( "Hello " ), str2d ( "Wide " ), str3d ( "World " ); - cout << "The string str2d is: " << str2d << endl; + cout << "The string str2d is: " << str2d << endl; str1d.append ( str2d ); cout << "The appended string str1d is: " << str1d << "." << endl; str1d += str3d; - cout << "The doubly appended strig str1 is: " + cout << "The doubly appended string str1 is: " << str1d << "." << endl << endl; // The fifth member function @@ -316,9 +316,9 @@ Appending the 1st part of the C-string cstr1b to string str1 gives: Hello Out. The string str2c is: Wide World The appended string str1 is: Hello World. -The string str2d is: Wide +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 !!!! @@ -379,10 +379,10 @@ The source string whose characters are to be assigned to the target string. The character value to be assigned. *`first`*\ -An input iterator, const_pointer, or const_iterator addressing the first character in the range of the source string to be assigned to the target range. +An input iterator, `const_pointer`, or `const_iterator` addressing the first character in the range of the source string to be assigned to the target range. *`last`*\ -An input iterator, const_pointer, or const_iterator addressing the one beyond the last character in the range of the source string to be assigned to the target range. +An input iterator, `const_pointer`, or `const_iterator` addressing the one beyond the last character in the range of the source string to be assigned to the target range. *`off`*\ The position at which new characters will start to be assigned. @@ -417,7 +417,7 @@ int main( ) << str1a << "." << endl << endl; // The second member function assigning a specific - // number of the of characters a C-string to a string + // number of characters of a C-string to a string string str1b; const char *cstr1b = "Out There"; cout << "The C-string cstr1b is: " << cstr1b << endl; @@ -452,7 +452,7 @@ int main( ) // number of characters of a certain value to a string string str1e ( "Hello " ); str1e.assign ( 4 , '!' ); - cout << "The string str1 assigned with eclamations is: " + cout << "The string str1 assigned with exclamations is: " << str1e << endl << endl; // The sixth member function assigning the value from @@ -481,7 +481,7 @@ The string str1 newly assigned with string str2d is: Wide. The string str3d is: World. The string str1 reassigned with string str3d is: World. -The string str1 assigned with eclamations is: !!!! +The string str1 assigned with exclamations is: !!!! The string str2f is: Wide World The string str1 assigned a range of string str2f is: World. @@ -512,7 +512,7 @@ The first element of the string has an index of zero and the following elements The member [`operator[]`](#op_at) is faster than the member function `at` for providing read and write access to the elements of a string. -The member `operator[]` doesn't check whether the index passed as a parameter is valid but the member function `at` does and so should be used if the validity isn't certain. An invalid index, which is an index less that zero or greater than or equal to the size of the string, passed to the member function `at` throws an [`out_of_range` Class](../standard-library/out-of-range-class.md) exception. An invalid index passed to the `operator[]` results in undefined behavior, but the index equal to the length of the string is a valid index for const strings and the operator returns the null-character when passed this index. +The member `operator[]` doesn't check whether the index passed as a parameter is valid but the member function `at` does and so should be used if the validity isn't certain. An invalid index, which is an index less than zero or greater than or equal to the size of the string, passed to the member function `at` throws an [`out_of_range` Class](out-of-range-class.md) exception. An invalid index passed to the `operator[]` results in undefined behavior, but the index equal to the length of the string is a valid index for const strings and the operator returns the null-character when passed this index. The reference returned may be invalidated by string reallocations or modifications for the non-`const` strings. @@ -569,8 +569,6 @@ reference back(); A reference to the last element of the string, which must be non-empty. -### Remarks - ## `basic_string::basic_string` Constructs a string that is empty, initialized by specific characters, or is a copy of all or part of another string object or C style (null-terminated) string. @@ -664,10 +662,10 @@ The index of a character in a string that is the first to be used to initialize The character value to be copied into the string being constructed. *`first`*\ -An input iterator, const_pointer, or const_iterator addressing the first element in the source range to be inserted. +An input iterator, `const_pointer`, or `const_iterator` addressing the first element in the source range to be inserted. *`last`*\ -An input iterator, const_pointer, or const_iterator addressing the position of the one beyond the last element in the source range to be inserted. +An input iterator, `const_pointer`, or `const_iterator` addressing the position of the one beyond the last element in the source range to be inserted. ### Return value @@ -677,7 +675,7 @@ A reference to the string object that is being constructed by the constructors. All constructors store a [`basic_string::allocator_type`](#allocator_type) and initialize the controlled sequence. The allocator object is the argument `al`, if present. For the copy constructor, it's `right.get_allocator()`, a call to [`basic_string::get_allocator`](#get_allocator). Otherwise, the allocator is `Alloc()`. -The controlled sequence is initialized to a copy of the operand sequence specified by the remaining operands. A constructor without an operand sequence specifies an empty initial controlled sequence. If `InputIterator` is an integer type in a template constructor, the operand sequence `first, last` behaves the same as `(size_type) first, (value_type) last`. +The controlled sequence is initialized to a copy of the operand sequence specified by the remaining operands. A constructor without an operand sequence specifies an empty initial controlled sequence. If `InputIterator` is an integer type in a template constructor, the operand sequence `first, last` behaves the same as `(size_type) first, (value_type) last`. ### Example @@ -762,7 +760,7 @@ int main( ) { cout << "The full original string str1 is: " << str1 << endl; // The dereferenced iterator can be used to modify a character -*str1_Iter = 'G'; + *str1_Iter = 'G'; cout << "The first character of the modified str1 is now: " << *str1_Iter << endl; cout << "The full modified string str1 is now: " << str1 << endl; @@ -1048,7 +1046,7 @@ int compare( int compare( size_type position_1, size_type number_1, - const value_type* ptr + const value_type* ptr, size_type number_2) const; ``` @@ -1081,7 +1079,7 @@ A negative value if the operand string is less than the parameter string; zero i ### Remarks -The `compare` member functions compare either all, or part, of the parameter and operand strings depending on which in used. +The `compare` member functions compare either all, or part, of the parameter and operand strings depending on which is used. The comparison is case-sensitive. @@ -1473,8 +1471,6 @@ const_reverse_iterator crend() const; A `const` reverse iterator that addresses the location succeeding the last element in a reversed string (the location that had preceded the first element in the unreversed string). -### Remarks - ## `basic_string::_Copy_s` Copies at most a specified number of characters from an indexed position in a source string to a target character array. @@ -1508,6 +1504,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 @@ -1781,7 +1778,7 @@ int main( ) if ( str2.begin( ) == str2.end ( ) ) cout << "The string str2 is empty." << endl; else - cout << "The stringstr2 is not empty." << endl; + cout << "The string str2 is not empty." << endl; } ``` @@ -1829,7 +1826,7 @@ See [`starts_with`](#starts_with) to check if a string starts with the specified ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -2450,7 +2447,7 @@ int main( ) << "position is: " << indexCh3b << endl << endl; else cout << "Elements of the substring '5G' were not " - << "found in str3\n after the first occurrrence." + << "found in str3\n after the first occurrence." << endl << endl; // The fourth member function searches a string @@ -2884,8 +2881,6 @@ reference front(); A reference to the first element of the string, which must be non-empty. -### Remarks - ## `basic_string::get_allocator` Returns a copy of the allocator object used to construct the string. @@ -2958,12 +2953,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, @@ -3207,7 +3200,7 @@ The maximum number of characters a string could contain. ### Remarks -An exception of type [`length_error` Class](../standard-library/length-error-class.md) is thrown when an operation produces a string with a length greater than the maximum size. +An exception of type [`length_error` Class](length-error-class.md) is thrown when an operation produces a string with a length greater than the maximum size. ### Example @@ -3351,7 +3344,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 +3358,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=` @@ -3486,11 +3479,11 @@ The first element of the string has an index of zero, and the following elements `operator[]` is faster than the member function [`at`](#at) for providing read and write access to the elements of a string. -`operator[]` doesn't check whether the index passed as a parameter is valid, but the member function `at` does and so should be used in the validity isn't certain. An invalid index (an index less that zero or greater than or equal to the size of the string) passed to the member function `at` throws an [`out_of_range` Class](../standard-library/out-of-range-class.md) exception. An invalid index passed to `operator[]` results in undefined behavior, but the index equal to the length of the string is a valid index for const strings and the operator returns the null character when passed this index. +`operator[]` doesn't check whether the index passed as a parameter is valid, but the member function `at` does and so should be used if the validity isn't certain. An invalid index (an index less than zero or greater than or equal to the size of the string) passed to the member function `at` throws an [`out_of_range` Class](out-of-range-class.md) exception. An invalid index passed to `operator[]` results in undefined behavior, but the index equal to the length of the string is a valid index for const strings and the operator returns the null character when passed this index. The reference returned may be invalidated by string reallocations or modifications for the non-`const` strings. -When compiling with [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) set to 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the string. For more information, see [Checked Iterators](../standard-library/checked-iterators.md). +When compiling with [`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md) set to 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the string. For more information, see [Checked Iterators](checked-iterators.md). ### Example @@ -3697,7 +3690,7 @@ int main( ) if ( str2.rbegin( ) == str2.rend ( ) ) cout << "The string str2 is empty." << endl; else - cout << "The stringstr2 is not empty." << endl; + cout << "The string str2 is not empty." << endl; } ``` @@ -3795,7 +3788,7 @@ int main( ) if ( str2.rbegin( ) == str2.rend ( ) ) cout << "The string str2 is empty." << endl; else - cout << "The stringstr2 is not empty." << endl; + cout << "The string str2 is not empty." << endl; } ``` @@ -3915,10 +3908,10 @@ An iterator addressing the first character to be removed in the operand string. An iterator addressing the last character to be removed in the operand string. *`first`*\ -An iterator, const_pointer, or const_iterator addressing the first character to be copied in the parameter string. +An iterator, `const_pointer`, or `const_iterator` addressing the first character to be copied in the parameter string. *`last`*\ -An iterator, const_pointer, or const_iterator addressing the last character to be copied in the parameter string. +An iterator, `const_pointer`, or `const_iterator` addressing the last character to be copied in the parameter string. *`count`*\ The number of times *`char_value`* is copied into the operand string. @@ -4158,7 +4151,7 @@ int main( ) sizerStr1 = str1.size ( ); caprStr1 = str1.capacity ( ); - cout << "The string str1with augmented capacity is: " + cout << "The string str1 with augmented capacity is: " << str1 << endl; cout << "The current size of string str1 is: " << sizerStr1 << "." << endl; @@ -4187,7 +4180,7 @@ The original string str1 is: Hello world The current size of original string str1 is: 11. The capacity of original string str1 is: 15. -The string str1with augmented capacity is: Hello world +The string str1 with augmented capacity is: Hello world The current size of string str1 is: 11. The new capacity of string str1 is: 47. @@ -4202,7 +4195,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, @@ -4653,7 +4646,7 @@ See [`ends_with`](#ends_with) to see if a string ends with the specified suffix. ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -4812,7 +4805,7 @@ For type `string`, it's equivalent to `char_traits`. ### Example -See the example for [`copy`](../standard-library/char-traits-struct.md#copy) for an example of how to declare and use `traits_type`. +See the example for [`copy`](char-traits-struct.md#copy) for an example of how to declare and use `traits_type`. ## `basic_string::value_type` @@ -4854,5 +4847,5 @@ The character ch2 is: H. ## See also -[``](../standard-library/string.md)\ -[Thread safety in the C++ standard library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[``](string.md)\ +[Thread safety in the C++ standard library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/basic-string-view-class.md b/docs/standard-library/basic-string-view-class.md index b2e31912c4f..c92f5cb34cf 100644 --- a/docs/standard-library/basic-string-view-class.md +++ b/docs/standard-library/basic-string-view-class.md @@ -1,13 +1,13 @@ --- title: "basic_string_view Class" -description: "API reference for `basic_string_view` which refers to a constant contiguous sequence of char-like objects." -ms.date: "9/8/2020" +description: "API reference for `basic_string_view`, which refers to a constant contiguous sequence of char-like objects." +ms.date: 9/8/2020 f1_keywords: ["xstring/std::basic_string_view", "xstring/std::basic_string_view::allocator_type", "xstring/std::basic_string_view::const_iterator", "xstring/std::basic_string_view::const_pointer", "xstring/std::basic_string_view::const_reference", "xstring/std::basic_string_view::const_reverse_iterator", "xstring/std::basic_string_view::difference_type", "xstring/std::basic_string_view::ends_with", "xstring/std::basic_string_view::starts_with", "xstring/std::basic_string_view::iterator", "xstring/std::basic_string_view::npos", "xstring/std::basic_string_view::pointer", "xstring/std::basic_string_view::reference", "xstring/std::basic_string_view::reverse_iterator", "xstring/std::basic_string_view::size_type", "xstring/std::basic_string_view::traits_type", "xstring/std::basic_string_view::value_type", "xstring/std::basic_string_view::append", "xstring/std::basic_string_view::assign", "xstring/std::basic_string_view::at", "xstring/std::basic_string_view::back", "xstring/std::basic_string_view::begin", "xstring/std::basic_string_view::c_str", "xstring/std::basic_string_view::capacity", "xstring/std::basic_string_view::cbegin", "xstring/std::basic_string_view::cend", "xstring/std::basic_string_view::clear", "xstring/std::basic_string_view::compare", "xstring/std::basic_string_view::copy", "xstring/std::basic_string_view::_Copy_s", "xstring/std::basic_string_view::crbegin", "xstring/std::basic_string_view::crend", "xstring/std::basic_string_view::data", "xstring/std::basic_string_view::empty", "xstring/std::basic_string_view::end", "xstring/std::basic_string_view::erase", "xstring/std::basic_string_view::find", "xstring/std::basic_string_view::find_first_not_of", "xstring/std::basic_string_view::find_first_of", "xstring/std::basic_string_view::find_last_not_of", "xstring/std::basic_string_view::find_last_of", "xstring/std::basic_string_view::front", "xstring/std::basic_string_view::get_allocator", "xstring/std::basic_string_view::insert", "xstring/std::basic_string_view::length", "xstring/std::basic_string_view::max_size", "xstring/std::basic_string_view::pop_back", "xstring/std::basic_string_view::push_back", "xstring/std::basic_string_view::rbegin", "xstring/std::basic_string_view::rend", "xstring/std::basic_string_view::remove_prefix","xstring/std::basic_string_view::remove_suffix", "xstring/std::basic_string_view::replace", "xstring/std::basic_string_view::reserve", "xstring/std::basic_string_view::resize", "xstring/std::basic_string_view::rfind", "xstring/std::basic_string_view::shrink_to_fit", "xstring/std::basic_string_view::size", "xstring/std::basic_string_view::substr", "xstring/std::basic_string_view::swap"] -helpviewer_keywords: ["std::basic_string_view", "std::basic_string_view, allocator_type", "std::basic_string_view, const_iterator", "std::basic_string_view, const_pointer", "std::basic_string_view, const_reference", "std::basic_string_view, const_reverse_iterator", "std::basic_string_view, difference_type", "std::basic_string_view, iterator", "std::basic_string_view, npos", "std::basic_string_view, pointer", "std::basic_string_view, reference", "std::basic_string_view, reverse_iterator", "std::basic_string_view, size_type", "std::basic_string_view, traits_type", "std::basic_string_view, value_type", "std::basic_string_view, append", "std::basic_string_view, assign", "std::basic_string_view, at", "std::basic_string_view, back", "std::basic_string_view, begin", "std::basic_string_view, c_str", "std::basic_string_view, capacity", "std::basic_string_view, cbegin", "std::basic_string_view, cend", "std::basic_string_view, clear", "std::basic_string_view, compare", "std::basic_string_view, copy", "std::basic_string_view, crbegin", "std::basic_string_view, crend", "std::basic_string_view, data", "std::basic_string_view, empty", "std::basic_string_view, end", "std::basic_string_view, ends_with", "std::basic_string_view, erase", "std::basic_string_view, find", "std::basic_string_view, find_first_not_of", "std::basic_string_view, find_first_of", "std::basic_string_view, find_last_not_of", "std::basic_string_view, find_last_of", "std::basic_string_view, front", "std::basic_string_view, get_allocator", "std::basic_string_view, insert", "std::basic_string_view, length", "std::basic_string_view, max_size", "std::basic_string_view, pop_back", "std::basic_string_view, push_back", "std::basic_string_view, rbegin", "std::basic_string_view, rend", "std::basic_string_view, remove_prefix","std::basic_string_view, remove_suffix","std::basic_string_view, replace", "std::basic_string_view, reserve", "std::basic_string_view, resize", "std::basic_string_view, rfind", "std::basic_string_view, shrink_to_fit", "std::basic_string_view, size", "std::basic_string_view, starts_with", "std::basic_string_view, substr", "std::basic_string_view, swap"] +helpviewer_keywords: ["std::basic_string_view", "std::basic_string_view, allocator_type", "std::basic_string_view, const_iterator", "std::basic_string_view, const_pointer", "std::basic_string_view, const_reference", "std::basic_string_view, const_reverse_iterator", "std::basic_string_view, difference_type", "std::basic_string_view, iterator", "std::basic_string_view, npos", "std::basic_string_view, pointer", "std::basic_string_view, reference", "std::basic_string_view, reverse_iterator", "std::basic_string_view, size_type", "std::basic_string_view, traits_type", "std::basic_string_view, value_type", "std::basic_string_view, append", "std::basic_string_view, assign", "std::basic_string_view, at", "std::basic_string_view, back", "std::basic_string_view, begin", "std::basic_string_view, c_str", "std::basic_string_view, capacity", "std::basic_string_view, cbegin", "std::basic_string_view, cend", "std::basic_string_view, clear", "std::basic_string_view, compare", "std::basic_string_view, copy", "std::basic_string_view, crbegin", "std::basic_string_view, crend", "std::basic_string_view, data", "std::basic_string_view, empty", "std::basic_string_view, end", "std::basic_string_view, ends_with", "std::basic_string_view, erase", "std::basic_string_view, find", "std::basic_string_view, find_first_not_of", "std::basic_string_view, find_first_of", "std::basic_string_view, find_last_not_of", "std::basic_string_view, find_last_of", "std::basic_string_view, front", "std::basic_string_view, get_allocator", "std::basic_string_view, insert", "std::basic_string_view, length", "std::basic_string_view, max_size", "std::basic_string_view, pop_back", "std::basic_string_view, push_back", "std::basic_string_view, rbegin", "std::basic_string_view, rend", "std::basic_string_view, remove_prefix","std::basic_string_view, remove_suffix","std::basic_string_view, replace", "std::basic_string_view, reserve", "std::basic_string_view, resize", "std::basic_string_view, rfind", "std::basic_string_view, shrink_to_fit", "std::basic_string_view, size", "std::basic_string_view, starts_with", "std::basic_string_view, substr", "std::basic_string_view, swap"] --- -# `basic_string_view` Class +# `basic_string_view` class -The class template `basic_string_view` was added in C++17 to serve as a safe and efficient way for a function to accept various unrelated string types without the function having to be templatized on those types. The class holds a non-owning pointer to a contiguous sequence of character data, and a length that specifies the number of characters in the sequence. No assumption is made with respect to whether the sequence is null-terminated. +The class template `basic_string_view` was added in C++17 to serve as a safe and efficient way for a function to accept various unrelated string types without the function having to be templatized on those types. The class holds a non-owning pointer to a contiguous sequence of character data, and a length that specifies the number of characters in the sequence. No assumption is made about whether the sequence is null-terminated. The standard library defines several specializations based on the type of the elements: @@ -138,7 +138,7 @@ If a function is asked to generate a sequence longer than [`max_size`](#max_size ## Requirements -[`std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. +[`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. **Header:** `` @@ -146,7 +146,7 @@ If a function is asked to generate a sequence longer than [`max_size`](#max_size ## `basic_string_view::at` -Returns a `const_reference` to the character at the specified 0-based index. +Returns a `const_reference` to the character at the specified zero-based index. ```cpp constexpr const_reference at(size_type offset) const; @@ -157,7 +157,7 @@ constexpr const_reference at(size_type offset) const; *`offset`*\ The index of the element to be referenced. -### Return Value +### Return value A `const_reference` to the character at the position specified by the parameter index. @@ -167,7 +167,7 @@ The first element has an index of zero and the following elements are indexed co In general, we recommend that **`at`** for sequences such as `std::vector` and `basic_string_view` should never be used. An invalid index passed to a sequence is a logic error that should be discovered and fixed during development. If a program isn't certain that its indices are valid, it should test them, not call `at()` and rely on exceptions to defend against careless programming. -See [`basic_string_view::operator[]`](#op_at) for more information. +For more information, see [`basic_string_view::operator[]`](#op_at). ### Example @@ -194,7 +194,7 @@ Returns a `const_reference` to the last element. constexpr const_reference back() const; ``` -### Return Value +### Return value A `const_reference` to the last element in the `basic_string_view`. @@ -255,7 +255,7 @@ Same as [`cbegin`](#cbegin). constexpr const_iterator begin() const noexcept; ``` -### Return Value +### Return value Returns a `const_iterator` addressing the first element. @@ -267,7 +267,7 @@ Returns a `const_iterator` that addresses the first element in the range. constexpr const_iterator cbegin() const noexcept; ``` -### Return Value +### Return value A **`const`** random-access iterator that points at the first element of the range, or the location just beyond the end of an empty range (for an empty range, `cbegin() == cend()`). @@ -279,7 +279,7 @@ Returns a `const_iterator` that addresses the location just beyond the last elem constexpr const_iterator cend() const noexcept; ``` -### Return Value +### Return value A **`const`** random-access iterator that points just beyond the end of the range. @@ -320,7 +320,7 @@ The index of *`strv`* at which the comparison begins. *`ptr`*\ The C string to be compared to this `basic_string_view`. -### Return Value +### Return value - A negative value if this `basic_string_view` is less than *`strv`* or *`ptr`* - Zero if the two character sequences are equal @@ -457,7 +457,7 @@ The number of characters to be copied, at most, from the source `basic_string_vi *`offset`*\ The beginning position in the source `basic_string_view` from which copies are to be made. -### Return Value +### Return value The number of characters copied. @@ -491,7 +491,7 @@ The number of characters to be copied, at most, from the source string. *`_Off`*\ The beginning position in the source string from which copies are to be made. -### Return Value +### Return value The number of characters copied. @@ -509,7 +509,7 @@ Returns a `const_reverse_iterator` that addresses the first element in a reverse constexpr const_reverse_iterator crbegin() const noexcept; ``` -### Return Value +### Return value A `const_reverse_iterator` that addresses the first element in a reversed `basic_string_view`. @@ -521,7 +521,7 @@ Same as [`rend`](#rend). constexpr const_reverse_iterator crend() const noexcept; ``` -### Return Value +### Return value Returns a `const_reverse_iterator` that addresses one past the end of a reversed `basic_string_view`. @@ -533,13 +533,13 @@ Returns a raw non-owning pointer to the const character sequence of the object t constexpr value_type *data() const noexcept; ``` -### Return Value +### Return value A pointer-to-const to the first element of the character sequence. ### Remarks -The pointer can’t modify the characters. +The pointer can't modify the characters. A sequence of `basic_string_view` characters isn't necessarily null-terminated. The return type for `data` isn't a valid C string, because no null character gets appended. The null character `\0` has no special meaning in an object of type `basic_string_view` and may be a part of the `basic_string_view` object just like any other character. @@ -551,7 +551,7 @@ Tests whether the `basic_string_view` contains characters or not. constexpr bool empty() const noexcept; ``` -### Return Value +### Return value **`true`** if the `basic_string_view` object contains no characters; **`false`** if it has at least one character. @@ -567,7 +567,7 @@ Returns a random-access `const_iterator` that points to one past the last elemen constexpr const_iterator end() const noexcept; ``` -### Return Value +### Return value Returns a random-access `const_iterator` that points to one past the last element. @@ -597,7 +597,7 @@ You can pass a `std::basic_string`, which converts to a `basic_string_view`. *`x`*\ Null-terminated character string containing the suffix to look for. -### Return Value +### Return value `true` if the string view ends with the specified suffix; `false` otherwise. @@ -610,7 +610,7 @@ See [`starts_with`](#starts_with) to check if a string view starts with the spec ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -661,7 +661,7 @@ The C string for which the member function is to search. *`count`*\ The number of characters in *`ptr`*, counting forward from the first character. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `npos`. @@ -693,7 +693,7 @@ The C string for which the member function is to search. *`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `npos`. @@ -725,7 +725,7 @@ The number of characters, counting forward from the first character, in the C st *`str`*\ The `basic_string_view` for which the member function is to search. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `npos`. @@ -757,7 +757,7 @@ The C string for which the member function is to search. *`count`*\ The number of characters, counting forward from the first character, in *`ptr`*. -### Return Value +### Return value The index of the first character of the substring searched for when successful; otherwise `string_view::npos`. @@ -789,7 +789,7 @@ The C string for which the member function is to search. *`count`*\ The number of characters, counting forward from the first character, in the C string for which the member function is to search. -### Return Value +### Return value The index of the last character of the substring searched for when successful; otherwise `npos`. @@ -801,7 +801,7 @@ Returns a `const_reference` to the first element. constexpr const_reference front() const; ``` -### Return Value +### Return value A `const_reference` to the first element. @@ -829,7 +829,7 @@ Returns the maximum number of characters a `basic_string_view` can contain. constexpr size_type max_size() const noexcept; ``` -### Return Value +### Return value The maximum number of characters a `basic_string_view` can contain. @@ -865,7 +865,7 @@ constexpr const_reference operator[](size_type offset) const; *`offset`*\ The index of the element to be referenced. -### Return Value +### Return value A `const_reference` to the character at the position specified by the parameter index. @@ -889,7 +889,7 @@ Returns a `const` iterator to the first element in a reversed `basic_string_view constexpr const_reverse_iterator rbegin() const noexcept; ``` -### Return Value +### Return value Returns a random-access iterator to the first element in a reversed `basic_string_view`, addressing what would be the last element in the corresponding unreversed `basic_string_view`. @@ -929,7 +929,7 @@ Returns a `const` iterator that points to one past the last element in a reverse constexpr reverse_iterator rend() const noexcept; ``` -### Return Value +### Return value A `const` reverse random-access iterator that points to one past the last element in a reversed `basic_string_view`. @@ -965,7 +965,7 @@ The number of characters, counting forward from the first character, in the C st *`str`*\ The `basic_string_view` for which the member function is to search. -### Return Value +### Return value The index of the first character of the substring when successful; otherwise `npos`. @@ -977,7 +977,7 @@ Returns the number of elements in the `basic_string_view`. constexpr size_type size() const noexcept; ``` -### Return Value +### Return value The length of the `basic_string_view`. @@ -1007,20 +1007,20 @@ You can pass a `std::basic_string`, which converts to a string view. *`x`*\ Null-terminated character string containing the prefix to look for. -### Return Value +### Return value `true` if the string starts with the specified prefix; `false` otherwise. ### Remarks -`starts_with()` is new in C++20. To use it, specify the [`std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. +`starts_with()` is new in C++20. To use it, specify the [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later compiler option. See [`ends_with`](#ends_with) to see if a string ends with a suffix. ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -1059,7 +1059,7 @@ An index locating the element at the position from which the copy is made, with *`count`*\ The number of characters to include in the substring, if they're present. -### Return Value +### Return value A `basic_string_view` object that represents the specified subsequence of elements. diff --git a/docs/standard-library/basic-stringbuf-class.md b/docs/standard-library/basic-stringbuf-class.md index 465e997c4f4..7fde918659b 100644 --- a/docs/standard-library/basic-stringbuf-class.md +++ b/docs/standard-library/basic-stringbuf-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: basic_stringbuf Class" title: "basic_stringbuf Class" +description: "Learn more about: basic_stringbuf Class" ms.date: 06/10/2022 f1_keywords: ["sstream/std::basic_stringbuf", "sstream/std::basic_stringbuf::allocator_type", "sstream/std::basic_stringbuf::char_type", "sstream/std::basic_stringbuf::int_type", "sstream/std::basic_stringbuf::off_type", "sstream/std::basic_stringbuf::pos_type", "sstream/std::basic_stringbuf::traits_type", "sstream/std::basic_stringbuf::overflow", "sstream/std::basic_stringbuf::pbackfail", "sstream/std::basic_stringbuf::seekoff", "sstream/std::basic_stringbuf::seekpos", "sstream/std::basic_stringbuf::str", "sstream/std::basic_stringbuf::underflow"] helpviewer_keywords: ["std::basic_stringbuf [C++]", "std::basic_stringbuf [C++], allocator_type", "std::basic_stringbuf [C++], char_type", "std::basic_stringbuf [C++], int_type", "std::basic_stringbuf [C++], off_type", "std::basic_stringbuf [C++], pos_type", "std::basic_stringbuf [C++], traits_type", "std::basic_stringbuf [C++], overflow", "std::basic_stringbuf [C++], pbackfail", "std::basic_stringbuf [C++], seekoff", "std::basic_stringbuf [C++], seekpos", "std::basic_stringbuf [C++], str", "std::basic_stringbuf [C++], underflow"] -ms.assetid: 40c85f9e-42a5-4a65-af5c-23c8e3bf8113 ms.custom: devdivchpfy22 --- @@ -365,8 +364,6 @@ void basic_stringbuf::swap(basic_stringbuf& other) *other*\ The basic_stringbuf whose contents will be swapped with this basic_stringbuf. -### Remarks - ## basic_stringbuf::operator= Assigns the contents of the basic_stringbuf on the right side of the operator to the basic_stringbuf on the left side. @@ -380,8 +377,6 @@ basic_stringbuf& basic_stringbuf:: operator=(const basic_stringbuf& other) *other*\ A basic_stringbuf whose contents, including locale traits, will be assigned to the stringbuf on the left side of the operator. -### Remarks - ## See also [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ diff --git a/docs/standard-library/basic-stringstream-class.md b/docs/standard-library/basic-stringstream-class.md index 998bc38cb28..6b834225d75 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 0737a964d0d..bd94744c715 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/binary-function-struct.md b/docs/standard-library/binary-function-struct.md index 719614bb1a7..510df3fc07f 100644 --- a/docs/standard-library/binary-function-struct.md +++ b/docs/standard-library/binary-function-struct.md @@ -13,6 +13,7 @@ An empty base struct that defines types that may be inherited by derived classes ## Syntax ```cpp +template struct binary_function { typedef Arg1 first_argument_type; typedef Arg2 second_argument_type; diff --git a/docs/standard-library/bit-functions.md b/docs/standard-library/bit-functions.md index 9563428d96e..a989e550d7d 100644 --- a/docs/standard-library/bit-functions.md +++ b/docs/standard-library/bit-functions.md @@ -1,7 +1,7 @@ --- title: " functions" description: "Functions to access, manipulate, and process individual bits and sequences of bits" -ms.date: "08/28/2020" +ms.date: 08/28/2020 f1_keywords: ["bit/std::bit_cast", "bit/std::has_single_bit", "bit/std::bit_ceil", "bit/std::bit_floor", "bit/std::bit_width", "bit/std::rotl", "bit/std::rotr", "bit/std::countl_zero", "bit/std::countl_one","bit/std::countr_zero","bit/std::countr_one","bit/std::popcount"] helpviewer_keywords: ["std::bit [C++], bit_cast", "std::bit [C++], has_single_bit", "std::bit [C++], bit_ceil", "std::bit [C++], bit_floor", "std::bit [C++], bit_width", "std::bit [C++], rotl", "std::bit [C++], rotr", "std::bit [C++], countl_zero", "std::bit [C++], countl_one", "std::bit [C++], countr_zero", "std::bit [C++], countr_one", "std::bit [C++], popcount"] --- @@ -24,7 +24,7 @@ The `` header includes the following non-member template functions: |[`rotl`](#rotl) | Compute the result of a bitwise left rotation. | |[`rotr`](#rotr) | Compute the result of a bitwise right rotation. | -## `bit_cast` +## `bit_cast` Copy a bit pattern from an object of type `From` to a new object of type `To`. @@ -92,7 +92,7 @@ This function template is `constexpr` if and only if `To`, `From`, and the types - Not volatile-qualified - Have no non-static data member that is a reference type -## `bit_ceil` +## `bit_ceil` Find the smallest power of two greater than or equal to a value. For example, given `3`, returns `4`. @@ -142,7 +142,7 @@ bit_ceil(0b0101) = 0b1000 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `bit_floor` +## `bit_floor` Find the largest power of two not greater than a value. For example, given `5`, returns `4`. @@ -193,7 +193,7 @@ bit_floor(0b0101) = 0b0100 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `bit_width` +## `bit_width` Find the smallest number of bits needed to represent a value. @@ -247,7 +247,7 @@ bit_width(8) = 4 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `countl_zero` +## `countl_zero` Count the number of consecutive bits set to zero, starting from the most significant bit. @@ -300,7 +300,7 @@ countl_zero(0b10000000) = 0 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `countl_one` +## `countl_one` Count the number of consecutive bits set to one, starting from the most significant bit. @@ -353,7 +353,7 @@ countl_one(0b11111111) = 8 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `countr_zero` +## `countr_zero` Count the number of consecutive bits set to zero, starting from the least significant bit. @@ -407,7 +407,7 @@ countr_zero(0b10000000) = 7 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `countr_one` +## `countr_one` Count the number of consecutive bits set to one, starting from the least significant bit. @@ -460,7 +460,7 @@ countr_one(0b11111111) = 8 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `has_single_bit` +## `has_single_bit` Check if a value has only one bit set.This is the same as testing whether a value is a power of two. @@ -514,7 +514,7 @@ has_single_bit(0b1001) = false This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `popcount` +## `popcount` Count the number of bits set to one in an unsigned integer value. @@ -573,7 +573,7 @@ popcount(0b1111) = 4 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `rotl` +## `rotl` Rotates the bits of an unsigned integer value left the specified number of times. Bits that "fall out" of the leftmost bit are rotated into the rightmost bit. @@ -635,7 +635,7 @@ rotl(0b00000001,-1) = 0b10000000 This template function only participates in overload resolution if `T` is an unsigned integer type. For example: `unsigned int`, `unsigned long`, `unsigned short`, `unsigned char`, and so on. -## `rotr` +## `rotr` Rotates the bits of `value` right the specified number of times. Bits that 'fall out' of the rightmost bit are rotated back into the leftmost bit. diff --git a/docs/standard-library/bit.md b/docs/standard-library/bit.md index ed42bc8ac34..5f6ca69bb1f 100644 --- a/docs/standard-library/bit.md +++ b/docs/standard-library/bit.md @@ -1,7 +1,7 @@ --- title: "" description: "Functions to access, manipulate, and process individual bits and sequences of bits." -ms.date: "08/28/2020" +ms.date: 08/28/2020 f1_keywords: [""] helpviewer_keywords: ["bit header"] --- @@ -13,9 +13,9 @@ For example, there are functions to rotate bits, find the number of consecutive ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. @@ -25,24 +25,24 @@ For example, there are functions to rotate bits, find the number of consecutive | Type | Description | |--------|----------| -| [endian](bit-enum.md) | Specifies the endianness of scalar types. | +| [`endian`](bit-enum.md) | Specifies the endianness of scalar types. | ### Functions | Function | Description | |-----|-----| -|[bit_cast](bit-functions.md#bit_cast) | Reinterpret the object representation from one type to another. | -|[bit_ceil](bit-functions.md#bit_ceil) | Find the smallest power of two greater than or equal to a value. | -|[bit_floor](bit-functions.md#bit_floor) | Find the largest integral power of two not greater than a value. | -|[bit_width](bit-functions.md#bit_width) | Find the smallest number of bits needed to represent a value. | -|[countl_zero](bit-functions.md#countl_zero) | Count the number of consecutive bits set to zero, starting from the most significant bit. | -|[countl_one](bit-functions.md#countl_one) | Count the number of consecutive bits set to one, starting from the most significant bit. | -|[countr_zero](bit-functions.md#countr_zero) | Count the number of consecutive bits set to zero, starting from the least significant bit. | -|[countr_one](bit-functions.md#countl_one) | Count the number of consecutive bits set to one, starting from the least significant bit. | -|[has_single_bit](bit-functions.md#has_single_bit) | Check if a value has only a single bit set to one. This is the same as testing whether a value is a power of two. | -|[popcount](bit-functions.md#popcount) | Count the number of bits set to one. | -|[rotl](bit-functions.md#rotl) | Compute the result of a bitwise left-rotation. | -|[rotr](bit-functions.md#rotr) | Compute the result of a bitwise right-rotation. | +|[`bit_cast`](bit-functions.md#bit_cast) | Reinterpret the object representation from one type to another. | +|[`bit_ceil`](bit-functions.md#bit_ceil) | Find the smallest power of two greater than or equal to a value. | +|[`bit_floor`](bit-functions.md#bit_floor) | Find the largest integral power of two not greater than a value. | +|[`bit_width`](bit-functions.md#bit_width) | Find the smallest number of bits needed to represent a value. | +|[`countl_zero`](bit-functions.md#countl_zero) | Count the number of consecutive bits set to zero, starting from the most significant bit. | +|[`countl_one`](bit-functions.md#countl_one) | Count the number of consecutive bits set to one, starting from the most significant bit. | +|[`countr_zero`](bit-functions.md#countr_zero) | Count the number of consecutive bits set to zero, starting from the least significant bit. | +|[`countr_one`](bit-functions.md#countr_one) | Count the number of consecutive bits set to one, starting from the least significant bit. | +|[`has_single_bit`](bit-functions.md#has_single_bit) | Check if a value has only a single bit set to one. This is the same as testing whether a value is a power of two. | +|[`popcount`](bit-functions.md#popcount) | Count the number of bits set to one. | +|[`rotl`](bit-functions.md#rotl) | Compute the result of a bitwise left-rotation. | +|[`rotr`](bit-functions.md#rotr) | Compute the result of a bitwise right-rotation. | ## See also diff --git a/docs/standard-library/bitset-class.md b/docs/standard-library/bitset-class.md index 01a33ffdc05..a70a5b0f934 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 bab7cc6b244..b042e2cccc1 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/boyer-moore-horspool-searcher-class.md b/docs/standard-library/boyer-moore-horspool-searcher-class.md index 626ebc3ef11..85c81a6e6c2 100644 --- a/docs/standard-library/boyer-moore-horspool-searcher-class.md +++ b/docs/standard-library/boyer-moore-horspool-searcher-class.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["std::boyer_moore_horspool_searcher [C++]"] --- # boyer_moore_horspool_searcher class -The `boyer_moore_horspool_searcher` class is a function object type that uses the Boyer-Moore-Horspool algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object’s function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). +The `boyer_moore_horspool_searcher` class is a function object type that uses the Boyer-Moore-Horspool algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object's function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). ## Syntax diff --git a/docs/standard-library/boyer-moore-searcher-class.md b/docs/standard-library/boyer-moore-searcher-class.md index 60f0320639c..aa23e6cb1b0 100644 --- a/docs/standard-library/boyer-moore-searcher-class.md +++ b/docs/standard-library/boyer-moore-searcher-class.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["std::boyer_moore_searcher [C++]"] --- # boyer_moore_searcher class -The `boyer_moore_searcher` class is a function object type that uses the Boyer-Moore algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object’s function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). +The `boyer_moore_searcher` class is a function object type that uses the Boyer-Moore algorithm to search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object's function call operator. This class is passed as a parameter to one of the overloads of [std::search](algorithm-functions.md#search). ## Syntax diff --git a/docs/standard-library/cache-chunklist-class.md b/docs/standard-library/cache-chunklist-class.md index 914921951d3..e2de788bc76 100644 --- a/docs/standard-library/cache-chunklist-class.md +++ b/docs/standard-library/cache-chunklist-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: cache_chunklist Class" title: "cache_chunklist Class" -ms.date: "11/04/2016" +description: "Learn more about: cache_chunklist Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::cache_chunklist", "allocators/stdext::cache_chunklist::allocate", "allocators/stdext::cache_chunklist::deallocate"] helpviewer_keywords: ["stdext::cache_chunklist", "stdext::cache_chunklist [C++], allocate", "stdext::cache_chunklist [C++], deallocate"] -ms.assetid: af19eccc-4ae7-4a34-bbb2-81e397424cb9 --- # cache_chunklist Class @@ -64,8 +63,6 @@ The number of elements in the array to be allocated. A pointer to the allocated object. -### Remarks - ## cache_chunklist::cache_chunklist Constructs an object of type `cache_chunklist`. @@ -74,8 +71,6 @@ Constructs an object of type `cache_chunklist`. cache_chunklist(); ``` -### Remarks - ## cache_chunklist::deallocate Frees a specified number of objects from storage beginning at a specified position. @@ -92,8 +87,6 @@ A pointer to the first object to be deallocated from storage. *count*\ The number of objects to be deallocated from storage. -### Remarks - ## See also [\](../standard-library/allocators-header.md) diff --git a/docs/standard-library/cache-freelist-class.md b/docs/standard-library/cache-freelist-class.md index 1df5612d0d3..71faf8ebc05 100644 --- a/docs/standard-library/cache-freelist-class.md +++ b/docs/standard-library/cache-freelist-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: cache_freelist Class" title: "cache_freelist Class" -ms.date: "11/04/2016" +description: "Learn more about: cache_freelist Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::cache_freelist", "allocators/stdext::cache_freelist::allocate", "allocators/stdext::cache_freelist::deallocate"] helpviewer_keywords: ["stdext::cache_freelist", "stdext::cache_freelist [C++], allocate", "stdext::cache_freelist [C++], deallocate"] -ms.assetid: 840694de-36ba-470f-8dae-2b723d5a8cd9 --- # cache_freelist Class @@ -67,8 +66,6 @@ The number of elements in the array to be allocated. A pointer to the allocated object. -### Remarks - ## cache_freelist::cache_freelist Constructs an object of type `cache_freelist`. @@ -77,8 +74,6 @@ Constructs an object of type `cache_freelist`. cache_freelist(); ``` -### Remarks - ## cache_freelist::deallocate Frees a specified number of objects from storage beginning at a specified position. @@ -95,8 +90,6 @@ A pointer to the first object to be deallocated from storage. *count*\ The number of objects to be deallocated from storage. -### Remarks - ## See also [\](../standard-library/allocators-header.md) diff --git a/docs/standard-library/cache-suballoc-class.md b/docs/standard-library/cache-suballoc-class.md index 26c070fcad5..12f111137d7 100644 --- a/docs/standard-library/cache-suballoc-class.md +++ b/docs/standard-library/cache-suballoc-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: cache_suballoc Class" title: "cache_suballoc Class" -ms.date: "11/04/2016" +description: "Learn more about: cache_suballoc Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::cache_suballoc", "allocators/stdext::cache_suballoc::allocate", "allocators/stdext::cache_suballoc::deallocate"] helpviewer_keywords: ["stdext::cache_suballoc", "stdext::cache_suballoc [C++], allocate", "stdext::cache_suballoc [C++], deallocate"] -ms.assetid: 9ea9c5e9-1dcc-45d0-b3a7-a56a93d88898 --- # cache_suballoc Class @@ -64,8 +63,6 @@ The number of elements in the array to be allocated. A pointer to the allocated object. -### Remarks - ## cache_suballoc::cache_suballoc Constructs an object of type `cache_suballoc`. @@ -74,8 +71,6 @@ Constructs an object of type `cache_suballoc`. cache_suballoc(); ``` -### Remarks - ## cache_suballoc::deallocate Frees a specified number of objects from storage beginning at a specified position. @@ -92,8 +87,6 @@ A pointer to the first object to be deallocated from storage. *count*\ The number of objects to be deallocated from storage. -### Remarks - ## See also [\](../standard-library/allocators-header.md) diff --git a/docs/standard-library/char-traits-char-struct.md b/docs/standard-library/char-traits-char-struct.md index 22aa1ee35da..fbdc3d0c807 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 dcbd8702db4..065c8cf7d2a 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 296364799d2..8f601eef05e 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/checked-iterators.md b/docs/standard-library/checked-iterators.md index 719992a7af8..3022398c426 100644 --- a/docs/standard-library/checked-iterators.md +++ b/docs/standard-library/checked-iterators.md @@ -1,29 +1,28 @@ --- -description: "Learn more about: Checked Iterators" title: "Checked Iterators" -ms.date: "11/04/2016" +description: "Learn more about: Checked Iterators" +ms.date: 11/04/2016 f1_keywords: ["_SECURE_SCL_THROWS"] helpviewer_keywords: ["Safe Libraries", "Safe Libraries, C++ Standard Library", "Safe C++ Standard Library", "iterators, checked", "checked iterators"] -ms.assetid: cfc87df8-e3d9-403b-ab78-e9483247d940 --- # Checked Iterators -Checked iterators ensure that the bounds of your container are not overwritten. Checked iterators apply to both release builds and debug builds. For more information about how to use debug iterators when you compile in debug mode, see [Debug Iterator Support](../standard-library/debug-iterator-support.md). +Checked iterators ensure that the bounds of your container are not overwritten. Checked iterators apply to both release builds and debug builds. For more information about how to use debug iterators when you compile in debug mode, see [Debug Iterator Support](debug-iterator-support.md). ## Remarks -For information about how to disable warnings that are generated by checked iterators, see [_SCL_SECURE_NO_WARNINGS](../standard-library/scl-secure-no-warnings.md). +For information about how to disable warnings that are generated by checked iterators, see [`_SCL_SECURE_NO_WARNINGS`](scl-secure-no-warnings.md). -You can use the [\_ITERATOR\_DEBUG\_LEVEL](../standard-library/iterator-debug-level.md) preprocessor macro to enable or disable the checked iterators feature. If _ITERATOR_DEBUG_LEVEL is defined as 1 or 2, unsafe use of iterators causes a runtime error and the program is terminated. If defined as 0, checked iterators are disabled. By default, the value for _ITERATOR_DEBUG_LEVEL is 0 for release builds and 2 for debug builds. +You can use the [`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md) preprocessor macro to enable or disable the checked iterators feature. If `_ITERATOR_DEBUG_LEVEL` is defined as 1 or 2, unsafe use of iterators causes a runtime error and the program is terminated. If defined as 0, checked iterators are disabled. By default, the value for `_ITERATOR_DEBUG_LEVEL` is 0 for release builds and 2 for debug builds. > [!IMPORTANT] -> Older documentation and source code may refer to the [_SECURE_SCL](../standard-library/secure-scl.md) macro. Use _ITERATOR_DEBUG_LEVEL to control _SECURE_SCL. For more information, see [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md). +> Older documentation and source code may refer to the [`_SECURE_SCL`](secure-scl.md) macro. Use `_ITERATOR_DEBUG_LEVEL` to control `_SECURE_SCL`. For more information, see [`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md). -When _ITERATOR_DEBUG_LEVEL is defined as 1 or 2, these iterator checks are performed: +When `_ITERATOR_DEBUG_LEVEL` is defined as 1 or 2, these iterator checks are performed: -- All standard iterators (for example, [vector::iterator](../standard-library/vector-class.md#iterator)) are checked. +- All standard iterators (for example, [`vector::iterator`](vector-class.md#iterator)) are checked. -- If an output iterator is a checked iterator, calls to standard library functions such as [std::copy](../standard-library/algorithm-functions.md#copy) get checked behavior. +- If an output iterator is a checked iterator, calls to standard library functions such as [`std::copy`](algorithm-functions.md#copy) get checked behavior. - If an output iterator is an unchecked iterator, calls to standard library functions cause compiler warnings. @@ -31,26 +30,26 @@ When _ITERATOR_DEBUG_LEVEL is defined as 1 or 2, these iterator checks are perfo :::row::: :::column span=""::: -   [`basic_string::operator[]`](../standard-library/basic-string-class.md#op_at)\ -   [`bitset::operator[]`](../standard-library/bitset-class.md#op_at)\ -   [`deque::back`](../standard-library/deque-class.md#back)\ -   [`deque::front`](../standard-library/deque-class.md#front) + [`basic_string::operator[]`](basic-string-class.md#op_at)\ + [`bitset::operator[]`](bitset-class.md#op_at)\ + [`deque::back`](deque-class.md#back)\ + [`deque::front`](deque-class.md#front) :::column-end::: :::column span=""::: - [`deque::operator[]`](../standard-library/deque-class.md#op_at)\ - [`list::back`](../standard-library/list-class.md#back)\ - [`list::front`](../standard-library/list-class.md#front)\ - [`queue::back`](../standard-library/queue-class.md#back) + [`deque::operator[]`](deque-class.md#op_at)\ + [`list::back`](list-class.md#back)\ + [`list::front`](list-class.md#front)\ + [`queue::back`](queue-class.md#back) :::column-end::: :::column span=""::: - [`queue::front`](../standard-library/queue-class.md#front)\ - [`vector::back`](../standard-library/vector-class.md#back)\ - [`vector::front`](../standard-library/vector-class.md#front)\ - [`vector::operator[]`](../standard-library/vector-class.md#op_at) + [`queue::front`](queue-class.md#front)\ + [`vector::back`](vector-class.md#back)\ + [`vector::front`](vector-class.md#front)\ + [`vector::operator[]`](vector-class.md#op_at) :::column-end::: :::row-end::: -When _ITERATOR_DEBUG_LEVEL is defined as 0: +When `_ITERATOR_DEBUG_LEVEL` is defined as 0: - All standard iterators are unchecked. Iterators can move beyond the container boundaries, which leads to undefined behavior. @@ -60,11 +59,11 @@ When _ITERATOR_DEBUG_LEVEL is defined as 0: A checked iterator refers to an iterator that calls `invalid_parameter_handler` if you attempt to move past the boundaries of the container. For more information about `invalid_parameter_handler`, see [Parameter Validation](../c-runtime-library/parameter-validation.md). -The iterator adaptors that support checked iterators are [checked_array_iterator Class](../standard-library/checked-array-iterator-class.md) and [unchecked_array_iterator Class](../standard-library/unchecked-array-iterator-class.md). +The iterator adaptors that support checked iterators are [`checked_array_iterator` Class](checked-array-iterator-class.md) and [`unchecked_array_iterator` Class](unchecked-array-iterator-class.md). ## Examples -When you compile by using _ITERATOR_DEBUG_LEVEL set to 1 or 2, a runtime error will occur if you attempt to access an element that is outside the bounds of the container by using the indexing operator of certain classes. +When you compile by using `_ITERATOR_DEBUG_LEVEL` set to 1 or 2, a runtime error will occur if you attempt to access an element that is outside the bounds of the container by using the indexing operator of certain classes. ```cpp // checked_iterators_1.cpp @@ -79,19 +78,19 @@ using namespace std; int main() { - vector v; - v.push_back(67); + vector v; + v.push_back(67); - int i = v[0]; - cout << i << endl; + int i = v[0]; + cout << i << endl; - i = v[1]; //triggers invalid parameter handler + i = v[1]; //triggers invalid parameter handler } ``` This program prints "67" then pops up an assertion failure dialog box with additional information about the failure. -Similarly, when you compile by using _ITERATOR_DEBUG_LEVEL set to 1 or 2, a runtime error will occur if you attempt to access an element by using `front` or `back` in container classes when the container is empty. +Similarly, when you compile by using `_ITERATOR_DEBUG_LEVEL` set to 1 or 2, a runtime error will occur if you attempt to access an element by using `front` or `back` in container classes when the container is empty. ```cpp // checked_iterators_2.cpp @@ -105,15 +104,15 @@ using namespace std; int main() { - vector v; + vector v; - int& i = v.front(); // triggers invalid parameter handler + int& i = v.front(); // triggers invalid parameter handler } ``` This program pops up an assertion failure dialog box with additional information about the failure. -The following code demonstrates various iterator use-case scenarios with comments about each. By default, _ITERATOR_DEBUG_LEVEL is set to 2 in Debug builds, and to 0 in Retail builds. +The following code demonstrates various iterator use-case scenarios with comments about each. By default, `_ITERATOR_DEBUG_LEVEL` is set to 2 in Debug builds, and to 0 in Retail builds. ```cpp // checked_iterators_3.cpp @@ -134,7 +133,8 @@ void print(const string& s, const C& c) { cout << s; - for (const auto& e : c) { + for (const auto& e : c) + { cout << e << " "; } @@ -219,5 +219,5 @@ a8: 0 8 16 24 32 40 48 56 64 72 80 88 96 104 112 120 ## See also -[C++ Standard Library Overview](../standard-library/cpp-standard-library-overview.md)\ -[Debug Iterator Support](../standard-library/debug-iterator-support.md) +[C++ Standard Library Overview](cpp-standard-library-overview.md)\ +[Debug Iterator Support](debug-iterator-support.md) diff --git a/docs/standard-library/choose-enum.md b/docs/standard-library/choose-enum.md index dedf8adda93..3a4c9f7b2a0 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 52f3dcb0d5c..80bc5412963 100644 --- a/docs/standard-library/chrono-functions.md +++ b/docs/standard-library/chrono-functions.md @@ -1,9 +1,9 @@ --- -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"] +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"] --- # `` functions @@ -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 @@ -347,7 +347,7 @@ If the parse fails, `is.setstate`(`ios_base::failbit`) is called and the output ```cpp // 1) day - C++20 -template> +template> basic_istream& from_stream( basic_istream& is, const charT* fmt, @@ -563,7 +563,7 @@ int main() ### Remarks -**7)** If `%Z` is used and successfully parsed, that value will be assigned to `*abbrev `if `abbrev` is non-null. If `%z` (or a modified variant) is used and successfully parsed, that value will be assigned to `*offset` if `offset` is non-null. +**7)** If `%Z` is used and successfully parsed, that value will be assigned to `*abbrev` if `abbrev` is non-null. If `%z` (or a modified variant) is used and successfully parsed, that value will be assigned to `*offset` if `offset` is non-null. **12)** If `%Z` is used and successfully parsed, that value will be assigned to `*abbrev` if `abbrev` is non-null. If `%z` (or a modified variant) is used and successfully parsed, that value will be assigned to `*offset` if `offset` is non-null. @@ -577,21 +577,21 @@ The format may be one of these strings: |--|--| | `%D` | Equivalent to `%m/%d/%y` | | `%F`
`%`*N*`F` | Equivalent to `%Y-%m-%d`. If modified with a width `N`, the width is applied to only `%Y`. | -| `%x`
`%Ex` | The locale’s date representation.
`%Ex` parses the locale’s alternate date representation.[1](#notice) | +| `%x`
`%Ex` | The locale's date representation.
`%Ex` parses the locale's alternate date representation.[1](#notice) | #### Day | Specifier | Description | |--|--| -| `%d`
`%Od`
`%`*N*`d`
`%e`
`%Oe`
`%`*N*`e` | The day of the month as a decimal number.
`%`*N*`d` specifies the maximum number of characters to read, for example `%1d`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Od` (letter `O`, not zero) interprets the locale’s alternative representation of the day of the month.[1](#notice)
`%e` is equivalent to `%d` and can be modified like `%d`.[1](#notice) | +| `%d`
`%Od`
`%`*N*`d`
`%e`
`%Oe`
`%`*N*`e` | The day of the month as a decimal number.
`%`*N*`d` specifies the maximum number of characters to read, for example `%1d`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Od` (letter `O`, not zero) interprets the locale's alternative representation of the day of the month.[1](#notice)
`%e` is equivalent to `%d` and can be modified like `%d`.[1](#notice) | #### Day of the week | Specifier | Description | |--|--| -| `%a`
`%A` | The locale’s full or abbreviated case-insensitive weekday name.
`%A` is equivalent to `%a` | +| `%a`
`%A` | The locale's full or abbreviated case-insensitive weekday name.
`%A` is equivalent to `%a` | | `%u`
`%`*N*`u` | The ISO weekday as a decimal number (1-7), where Monday is 1.
`%`*N*`u` specifies the maximum number of characters to read, for example `%2u`. If *N* isn't specified, the default is 1. Leading zeros are permitted but not required. | -| `%w`
`%`*N*`w`
`%Ow` | The weekday as a decimal number (0-6), where Sunday is 0.
`%`*N*`w` specifies the maximum number of characters to read, for example `%2w`. If *N* isn't specified, the default is 1.
Leading zeroes are permitted but not required.
`%Ow` (letter `O`, not zero) interprets the locale’s alternative representation.[1](#notice) | +| `%w`
`%`*N*`w`
`%Ow` | The weekday as a decimal number (0-6), where Sunday is 0.
`%`*N*`w` specifies the maximum number of characters to read, for example `%2w`. If *N* isn't specified, the default is 1.
Leading zeroes are permitted but not required.
`%Ow` (letter `O`, not zero) interprets the locale's alternative representation.[1](#notice) | #### Week/day of the year @@ -605,30 +605,30 @@ The format may be one of these strings: | Specifier | Description | |--|--| -| `%H`
`%`*N*`H`
`%OH` | The hour (24-hour clock) as a decimal number. If the result is a single digit, it's prefixed with a `0` (zero).
`%`*N*`H` specifies the maximum number of characters to read, for example, `%1H`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OH` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -| `%I`
`%`*N*`I`
`%OI` | The hour (12-hour clock) as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`I` specifies the maximum number of characters to read, for example, `%1I`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OI` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -| `%M`
`%`*N*`M`
`%OM` | The minutes as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`M` specifies the maximum number of characters to read, for example `%3M`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OM` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -|`%S`
`%`*N*`S`
`%OS` | Seconds as a decimal number. If the number of seconds is less than 10, the result is prefixed with `0` (zero). If the precision of the input can't be exactly represented with seconds, then the format is a decimal floating-point number with a fixed format. It has a microseconds precision if the function can't convert the floating-point decimal seconds within 18 fractional digits. Otherwise, its precision matches the precision of the input. The character for the decimal point is localized according to the locale.
`%`*N*`S` specifies the maximum number of characters to read, for example `%3S`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OS` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | -| `%p` | The locale’s equivalent of the AM/PM designations associated with a 12-hour clock. | -| `%r` | The locale’s 12-hour clock time. | +| `%H`
`%`*N*`H`
`%OH` | The hour (24-hour clock) as a decimal number. If the result is a single digit, it's prefixed with a `0` (zero).
`%`*N*`H` specifies the maximum number of characters to read, for example, `%1H`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OH` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +| `%I`
`%`*N*`I`
`%OI` | The hour (12-hour clock) as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`I` specifies the maximum number of characters to read, for example, `%1I`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OI` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +| `%M`
`%`*N*`M`
`%OM` | The minutes as a decimal number. If the result is a single digit, it's prefixed with `0` (zero).
`%`*N*`M` specifies the maximum number of characters to read, for example `%3M`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OM` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +|`%S`
`%`*N*`S`
`%OS` | Seconds as a decimal number. If the number of seconds is less than 10, the result is prefixed with `0` (zero). If the precision of the input can't be exactly represented with seconds, then the format is a decimal floating-point number with a fixed format. It has a microseconds precision if the function can't convert the floating-point decimal seconds within 18 fractional digits. Otherwise, its precision matches the precision of the input. The character for the decimal point is localized according to the locale.
`%`*N*`S` specifies the maximum number of characters to read, for example `%3S`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%OS` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | +| `%p` | The locale's equivalent of the AM/PM designations associated with a 12-hour clock. | +| `%r` | The locale's 12-hour clock time. | | `%R` | Equivalent to `%H:%M`. | | `%T`| Equivalent to `"%H:%M:%S"`. | -| `%X`, `%EX` | The locale’s time representation.
`%EX` parses the alternate locale’s time representation.[1](#notice) | +| `%X`, `%EX` | The locale's time representation.
`%EX` parses the alternate locale's time representation.[1](#notice) | #### Month | Specifier | Description | |--|--| -|`%b`, `%B`, `%h`| The locale’s full or abbreviated month name. If the value doesn't contain a valid month, a `format_error` exception is thrown.
`%h` is equivalent to `%b`. | -| `%m`, `%`*N*`m`, `%Om` | The month as a decimal number. Jan is 1.
`%`*N*`m` specifies the maximum number of characters to read, for example, `%3m`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Om` (letter `O`, not zero) interprets the locale’s alternative representation.[1](#notice) | +|`%b`, `%B`, `%h`| The locale's full or abbreviated month name. If the value doesn't contain a valid month, a `format_error` exception is thrown.
`%h` is equivalent to `%b`. | +| `%m`, `%`*N*`m`, `%Om` | The month as a decimal number. Jan is 1.
`%`*N*`m` specifies the maximum number of characters to read, for example, `%3m`. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Om` (letter `O`, not zero) interprets the locale's alternative representation.[1](#notice) | #### Year | Specifier | Description | |--|--| -|`%C`, `%`*N*`C`, `%EC`| The century as a decimal number.
`%`*N*`C` specifies the maximum number of characters to read, for example, `%1N`. If *N* isn't specified, the default is 2. Leading zeroes are permitted but not required.
`%EC` interprets the locale’s alternative representation of the century. | -|`%y`, `%`*N*`y`, `%Ey`, `%Oy` | The last two decimal digits of the year. If the century isn't otherwise specified (for example, by using `%C`), values in the range `[69, 99]` are presumed to refer to the years 1969 to 1999, and values in the range `[00, 68]` are presumed to refer to the years 2000 to 2068.
`%`*N*`y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Ey` and `%Oy` (letter `O`, not zero) interpret the locale’s alternative representation.[1](#notice) | -| `%Y`, `%`*N*`Y`, `%EY`, | The year as a decimal number. If the result is fewer than four digits, it's left-padded with `0` (zero) to four digits.
`%`*N*`Y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 4.
`%EY` parses the locale’s alternative full year representation.[1](#notice) | +|`%C`, `%`*N*`C`, `%EC`| The century as a decimal number.
`%`*N*`C` specifies the maximum number of characters to read, for example, `%1N`. If *N* isn't specified, the default is 2. Leading zeroes are permitted but not required.
`%EC` interprets the locale's alternative representation of the century. | +|`%y`, `%`*N*`y`, `%Ey`, `%Oy` | The last two decimal digits of the year. If the century isn't otherwise specified (for example, by using `%C`), values in the range `[69, 99]` are presumed to refer to the years 1969 to 1999, and values in the range `[00, 68]` are presumed to refer to the years 2000 to 2068.
`%`*N*`y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 2.
Leading zeroes are permitted but not required.
`%Ey` and `%Oy` (letter `O`, not zero) interpret the locale's alternative representation.[1](#notice) | +| `%Y`, `%`*N*`Y`, `%EY`, | The year as a decimal number. If the result is fewer than four digits, it's left-padded with `0` (zero) to four digits.
`%`*N*`Y` specifies the maximum number of characters to read. If *N* isn't specified, the default is 4.
`%EY` parses the locale's alternative full year representation.[1](#notice) | #### ISO 8601 week-based year @@ -638,18 +638,18 @@ In ISO 8601, weeks begin with Monday. The first week of the year must include Ja |:---------:|:------------------------------------------| | `%g`
`%`*N*`g`| The last two decimal digits of the ISO week-based year. If the result is a single digit, is prefixed by `0` (zero). `%`*N*`g` specifies the maximum number of characters to read, for example, `%1g`. If *N* isn't specified, the default is 2 | | `%G`
`%`*N*`G`| The ISO week-based year as a decimal number. If the result is fewer than four digits, it's left-padded with `0` (zero) to four digits. `%`*N*`G` specifies the maximum number of characters to read, for example, `%1G`. If *N* isn't specified, the default is 4| -| `%V`
`%OV`
`%`*N*`V`| The ISO week-based week number as a decimal number. If the result is a single digit, it's prefixed with `0` (zero). `%`*N*`V` specifies the maximum number of characters to read, for example, `%1V`. If *N* isn't specified, the default is 2
`%OV` (letter `O`, not zero) parses the locale’s alternative representation.[1](#notice) | +| `%V`
`%OV`
`%`*N*`V`| The ISO week-based week number as a decimal number. If the result is a single digit, it's prefixed with `0` (zero). `%`*N*`V` specifies the maximum number of characters to read, for example, `%1V`. If *N* isn't specified, the default is 2
`%OV` (letter `O`, not zero) parses the locale's alternative representation.[1](#notice) | #### General | Specifier | Replacement | |:-:|:-| | `%%` | Matches the % character | -| `%c`
`%Ec`| The locale’s date and time representation.
`%Ec` interprets the locale’s alternate date and time representation.[1](#notice) | +| `%c`
`%Ec`| The locale's date and time representation.
`%Ec` interprets the locale's alternate date and time representation.[1](#notice) | | `%n` | Matches a new-line character | | `%t` | Matches zero or one whitespace character | | `%z`
`%Ez`
`%Oz` | The offset from UTC in the format `[+|-]hh[mm]`. For example, `-0430` refers to 4 hours 30 minutes behind UTC, and `04` refers to 4 hours ahead of UTC.
`%Ez` and `%Oz` (letter `O`, not zero) parse a `:` between the hours and minutes and render leading zeroes on the hour field optional[1](#notice): `[+|-]h[h][:mm]`. For example, `-04:30` refers to 4 hours 30 minutes behind UTC, and 4 refers to 4 hours ahead of UTC. | -| `%Z` | The time zone abbreviation or name. A single word is parsed. This word can only contain alphanumeric characters from the basic source character set, or one of `_`, `/`, `-’`, or `+`. +| `%Z` | The time zone abbreviation or name. A single word is parsed. This word can only contain alphanumeric characters from the basic source character set, or one of `_`, `/`, `-`, or `+`. #### Flags by type @@ -674,7 +674,7 @@ In ISO 8601, weeks begin with Monday. The first week of the year must include Ja | `utc_time` | Z, z, c, x, X, D, F, g, G, j, U, V, W, Y, y, C, b, h, B, m, d, e, a, A, u, w, H, I, M, S, r, R, T, p | | [`weekday`](weekday-class.md) | a, A, u, w | | [`weekday_indexed`](weekdayindexed-class.md) | a, A, u, w | -| [`weekday_last`]() | a, A, u, w | +| [`weekday_last`](weekdaylast-class.md) | a, A, u, w | | [`year`](year-class.md) | Y, y, C | | `year_month` | Y, y, B, g, G, h, C, b, m | | `year_month_day` | D, F, g, G, j, U, V, W, Y, y, C, b, h, B, m, d, e, a, A, u, w | @@ -704,7 +704,7 @@ The source `utc_time` to get the `leap_second_info` for. ### Return value -Returns a `leap_second_info` whose member `is_leap_second` is **`true`** if *`ut`* is during a positive leap second insertion; otherwise, **`false`**. The `elapsed` member holds the sum of leap seconds between the epoch date `1970-01-01`and *`ut`*. If `is_leap_second` is **`true`**, the leap second referred to by *`ut`* is included in the `elapsed` sum. +Returns a `leap_second_info` whose member `is_leap_second` is **`true`** if *`ut`* is during a positive leap second insertion; otherwise, **`false`**. The `elapsed` member holds the sum of leap seconds between the epoch date `1970-01-01` and *`ut`*. If `is_leap_second` is **`true`**, the leap second referred to by *`ut`* is included in the `elapsed` sum. ## `get_tzdb` @@ -987,4 +987,4 @@ Unless `ToDuration` is a specialization of [`duration`](../standard-library/dura [`chrono` operators](./chrono-operators.md)\ [`duration` class](./duration-class.md)\ [`time_point` class](./time-point-class.md)\ -[`time_zone` class](./time-zone-class.md) \ No newline at end of file +[`time_zone` class](./time-zone-class.md) diff --git a/docs/standard-library/chrono-literals.md b/docs/standard-library/chrono-literals.md index 532aa1c1150..3bea9a5b934 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 666a207afe7..deb72801957 100644 --- a/docs/standard-library/chrono-operators.md +++ b/docs/standard-library/chrono-operators.md @@ -1,8 +1,8 @@ --- -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<<"] +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<<"] --- # `` operators @@ -23,7 +23,7 @@ Addition operator for the following types: - [`year_month_weekday_last`](year-month-weekday-last-class.md) ```cpp -1) +1) template constexpr typename common_type, duration>::type 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 @@ -107,7 +107,7 @@ constexpr year_month_weekday_last operator+(const years& dy, const year_month_we 2-3\) Return a `time_point` object that represents a point in time that is displaced by the interval *`Dur`* from the point in time *`Time`*. -4\) Returns the result of `d+ds.count()`. If the result is out of the range [0, 255], then the result is unspecified. +4\) Returns the result of `d+ds.count()`. If the result is out of the range [0, 255], then the result is unspecified. 5\) Returns the result of `m+ms.count()`. If the result is out of the range [1, 12], it's reduced modulo 12 and then +1. @@ -117,13 +117,13 @@ constexpr year_month_weekday_last operator+(const years& dy, const year_month_we 8\) Returns the result of adding the number of months and years to the specified month and year. -9\) Returns the result of adding months or years to a `year_month_day`. If `ymd.month()` is `February` and `ymd.day()` is not in the range [1d, 28d], `ok()` may return `false` for the result of the addition. +9\) Returns the result of adding months or years to a `year_month_day`. If `ymd.month()` is `February` and `ymd.day()` is not in the range [1d, 28d], `ok()` may return `false` for the result of the addition. 10\) Returns `(ymdl.year() / ymdl.month() + dm) / last`. Note: The `/` used here isn't a division operator. It's the date operator. 11\) Returns `ymdl + dm`. -12\) Returns `{ymdl.year()+dy, ymdl.month_day_last()}` +12\) Returns `{ymdl.year()+dy, ymdl.month_day_last()}` 13\) Returns `ymwd + dm.count()`. @@ -163,12 +163,12 @@ int main() // year_month_weekday year_month_weekday ymw{ year(1997) / January / Wednesday[1] }; std::cout << ymw + months{1} << '\n'; // 1997/Feb/Wed[1] - std::cout << ymw + years{1} << '\n'; // 1998/Jan/Wed[1] + std::cout << ymw + years{1} << '\n'; // 1998/Jan/Wed[1] // year_month_weekday_last year_month_weekday_last ymwl{ year(1997) / January / Wednesday[last] }; std::cout << ymwl + months{ 1 } << '\n'; // 1997/Feb/Wed[last] - std::cout << ymwl + years{ 1 } << '\n'; // 1998/Jan/Wed[last] + std::cout << ymwl + years{ 1 } << '\n'; // 1998/Jan/Wed[last] return 0; } @@ -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 @@ -295,7 +295,7 @@ constexpr year_month_weekday_last operator-(const year_month_weekday_last& ymwdl 4\) Returns the result of `d-ds.count()`. If the result is out of the range [0, 255], then the result is unspecified. -5\) If `m.ok() == true` and `ms.ok() == true`, returns the result of subtracting the two month values, or subtracting the number of months. The result will be in the range [1, 12]. If the result is negative, it wraps around. For example, subtracting one month from January (`month m1{1} - months{1};` results in 12 (December). +5\) If `m.ok() == true` and `ms.ok() == true`, returns the result of subtracting the two month values, or subtracting the number of months. The result will be in the range [1, 12]. If the result is negative, it wraps around. For example, subtracting one month from January (`month m1{1} - months{1};` results in 12 (December). 6\) Returns the difference in months between *`Left`* and *`Right`* @@ -303,7 +303,7 @@ constexpr year_month_weekday_last operator-(const year_month_weekday_last& ymwdl 8\) Returns the number of days between two weekdays. -9\) Returns `year(int(y)-ys.count)())` +9\) Returns `year(int(y)-ys.count())` 10\) Returns `years(int(y) - int(y2))`. Subtracting two `year` values results in a `std::chrono::years`, which represents the difference in years between `y` and `y2`. For example, `2021y-2000y` produces `years(21)`. @@ -336,10 +336,10 @@ int main() { // day day d{10}; - d = d - days(5); + d = d - days(5); std::cout << d << '\n'; // 05 - // month + // month month m{2}; m = m - months{1}; std::cout << m << '\n'; // Jan @@ -362,18 +362,18 @@ int main() // year_month_day_last year_month_day_last ymdl = June / last / 2021; - std::cout << ymdl - years{1} - months{1} << '\n'; // 2022/Jul/last + std::cout << ymdl - years{1} - months{1} << '\n'; // 2020/May/last // year_month_weekday year_month_weekday ymw{ year(1997) / January / Wednesday[1] }; std::cout << ymw - months{1} << '\n'; // 1996/Dec/Wed[1] - std::cout << ymw - years{1} << '\n'; // 1996/Jan/Wed[1] + std::cout << ymw - years{1} << '\n'; // 1996/Jan/Wed[1] // year_month_weekday_last year_month_weekday_last ymwl{ year(1997) / January / Wednesday[last] }; std::cout << ymwl - months{ 1 } << '\n'; // 1996/Dec/Wed[last] std::cout << ymwl - years{ 1 } << '\n'; // 1996/Jan/Wed[last] - + return 0; } ``` @@ -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 +// 17) year_month_weekday_last +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,8 +668,8 @@ 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*`.\ -19\) Returns **`true`** if `Left.get_time_zone() == _Right.get_time_zone() && Left.get_sys_time() == Right.get_sys_time();` +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>` @@ -678,7 +678,7 @@ The right object to compare. 2\) Determines if the point in time since the epoch of the `Left`[`time_point`](../standard-library/time-point-class.md) is greater than the time since the epoch of the `time_point` in `Right`. ```cpp -1) +1) template constexpr bool operator>( const duration& Left, @@ -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 @@ -786,7 +786,7 @@ strong_ordering operator<=>(const time_zone_link& Left, const time_zone_link& Ri ### Parameters *`Left`, `Right`*\ -The [`day`](day-class.md), [`duration`](duration-class.md), [`month`](month-class.md), [`month_day`](month-day-class.md), [`month_day_last`](month-day-last-class.md), [`time_point`](time-point-class.md), [`time_zone_link`](time-zone-link-class.md), [`year`](year-class.md), [`year_month`](year-month-class.md), [`year_month_day`](year-month-day-class.md), [`year_month_day_last`](year-month-day-last-class.md) to compare. +The [`day`](day-class.md), [`duration`](duration-class.md), [`month`](month-class.md), [`month_day`](month-day-class.md), [`month_day_last`](month-day-last-class.md), [`time_point`](time-point-class.md), [`time_zone_link`](time-zone-link-class.md), [`year`](year-class.md), [`year_month`](year-month-class.md), [`year_month_day`](year-month-day-class.md), [`year_month_day_last`](year-month-day-last-class.md) to compare. ### Return value @@ -846,8 +846,8 @@ int main() ``` ```output -d1 < d2 -true true false +d1 > d2 +true true false ``` ## `operator<<` @@ -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 @@ -1118,7 +1118,7 @@ The output stream you passed in, `os` 21\) In Microsoft's implementation, a `sys_info` is output as its `begin`, `end`, `offset`, `save`, and `abbrev` fields. For example: `begin: 2021-03-14 10:00:00, end: 2021-11-07 09:00:00, offset: -25200s, save: 60min, abbrev: PDT` -22\) In Microsoft's implementation, a `local_info` is output as yyyy-mm-dd hh:mm::ss.ssssss. For example, `2021-09-17 13:55:59.6590120` +22\) In Microsoft's implementation, a `local_info` is output as yyyy-mm-dd hh:mm:ss.ssssss. For example, `2021-09-17 13:55:59.6590120` 23\) The local time in the `zoned_time` (obtained as `zt.get_local_time()`) is output using the format yyyy-mm-dd hh:mm:ss timezone. For example, `2021-09-15 10:45:00 GMT-6` @@ -1160,7 +1160,7 @@ constexpr duration::type 2) template -constexpr typename common_type, duration>::type +constexpr typename common_type, duration>::type operator%( const duration& Left, const duration& Right); @@ -1214,7 +1214,7 @@ A `duration` object. *`Div`*\ An integral value. -*`Left`*\w +*`Left`*\ The left `duration` object. *`Right`*\ @@ -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 @@ -1438,7 +1438,7 @@ operator/(const month_weekday_last& mwdl, int y) noexcept; // C++ 20 The day. Provided either as an integer in the range [1,31], or as a [`day`](day-class.md). *`lastspec`*\ -An empty tag type that indicates the last item in s sequence. For example, `2021y/May/last` is the last day of May 2021. +An empty tag type that indicates the last item in a sequence. For example, `2021y/May/last` is the last day of May 2021. *`m`*\ The month. Provided either as an integer in the range [1,12], or as a [`month`](month-class.md). @@ -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 5127822f117..f2fdb6b4b75 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"] --- @@ -44,7 +44,7 @@ Using the time-zone facilities on older versions of Windows results in a runtime | [`month` class](month-class.md) | A month of a year. For example, July. | | [`month_day` class](month-day-class.md) | A specific day of a specific month. For example, July 30. | | [`month_day_last` class](month-day-last-class.md) | The last day of a month. | -| [`month_weekday` class](month-day-last-class.md) | The nth weekday of a specific month. | +| [`month_weekday` class](month-weekday-class.md) | The nth weekday of a specific month. | | [`month_weekday_last` class](month-weekday-last-class.md) | The nth weekday of a specific month. | | [`time_point` class](time-point-class.md) | A point in time. | | [`weekday` class](weekday-class.md) | A day of the week. | @@ -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 4f5ff0e47e6..188c50e8ea1 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 @@ -94,14 +94,14 @@ utc_time operator()(const sys_time& t) const; ### Parameters -**`t`** +*`t`*\ The `time_point` to convert. ### Return value 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 72eeb2d1cb4..43d007c8bbd 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 3c79d0aaad5..c63a9c25268 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 fd516200e4d..b391fc83bc5 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 new file mode 100644 index 00000000000..1480712afdd --- /dev/null +++ b/docs/standard-library/common-view-class.md @@ -0,0 +1,156 @@ +--- +title: common_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) common_view class, which takes a view that has different iterator and sentinel types and creates a view that has the same iterator and sentinel type." +ms.date: 09/27/2022 +f1_keywords: ["ranges/std::common_view", "ranges/std::common_view::base", "ranges/std::common_view::begin", "ranges/std::common_view::end", "ranges/std::common_view::size", "ranges/std::common_view::empty", "ranges/std::common_view::operator bool", "ranges/std::common_view::data", "ranges/std::common_view::back", "ranges/std::common_view::front", "ranges/std::common_view::operator[]"] +helpviewer_keywords: ["std::ranges::common_view [C++]", "std::ranges::common_view [C++], base", "std::ranges::common_view [C++], begin", "std::ranges::common_view [C++], end", "std::ranges::common_view [C++], size", "std::ranges::common_view [C++], data", "std::ranges::common_view [C++], empty", "std::ranges::common_view [C++], operator bool", "std::ranges::common_view [C++], front", "std::ranges::common_view [C++], back", "std::ranges::common_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `common_view` class (C++ Standard Library) + +Take a range that may have different iterator and sentinel types and create a view that has the same iterator and sentinel type. This is useful for calling STL algorithms that accept ranges specified by iterator pairs. + +## Syntax + +```cpp +template + requires (!ranges::common_range && std::copyable>) +class common_view : public ranges::view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::common`](range-adaptors.md#common) | +| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | `forward_range` or [`random_access_range`](range-concepts.md#random_access_range) when the underlying range satisfies `random_access_range` and [`sized_range`](range-concepts.md#sized_range) | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable | +| **Common range** | Yes | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `common_view`. | +| [`base`](#base)C++20 | Get the underlying view. | +| [`begin`](#begin) C++20| Get an iterator to the first element in the view. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements in the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +The best way to create a `common_view` is by using the [`views::common`](range-adaptors.md#common) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +This view is useful for passing a range that has different iterator/sentinel types to a legacy algorithm that expects them to be the same. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `common_view`. + +```cpp +1) common_view() = default; +2) constexpr explicit common_view(V v); +``` + +### Parameters + +*`v`*\ + The underlying view. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +1\) Default constructs the `common_view`.\ +2\) Constructs a `common_view` from the underlying view using `std::move(v)`. An error will result if `V` is a common range to avoid misuse that would negatively impact performance. + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +## `begin` + +Get an iterator to the first element. + +```cpp +constexpr auto begin(); +constexpr auto begin() const requires range; +``` + +### Return value + +An iterator pointing at the first element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end(); +constexpr auto end() const requires ranges::range; +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the view. + +## See also + +[``](ranges.md)\ +[`common` range adaptor](range-adaptors.md#common)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/complex-double.md b/docs/standard-library/complex-double.md index 386c66d380f..a2dd59629c7 100644 --- a/docs/standard-library/complex-double.md +++ b/docs/standard-library/complex-double.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: complex" title: "complex" -ms.date: "11/04/2016" +description: "Learn more about: complex" +ms.date: 11/04/2016 f1_keywords: ["complex/std::complex"] helpviewer_keywords: ["complex function"] -ms.assetid: 0d0b9d2a-9b9b-410b-82a0-86b6df127e47 --- # `complex` @@ -29,13 +28,13 @@ constexpr explicit complex(const complex& complexNum); ### Parameters -*RealVal*\ +*`RealVal`*\ The value of type **`double`** for the real part of the complex number being constructed. -*ImagVal*\ +*`ImagVal`*\ The value of type **`double`** for the imaginary part of the complex number being constructed. -*complexNum*\ +*`complexNum`*\ The complex number of type **`float`** or of type **`long double`** whose real and imaginary parts are used to initialize a complex number of type **`double`** being constructed. ## Return Value @@ -46,7 +45,7 @@ A complex number of type **`double`**. The explicit specialization of the class template complex to a complex class of type **`double`** differs from the class template only in the constructors it defines. The conversion from **`float`** to **`double`** is allowed to be implicit, but the conversion from **`long double`** to **`double`** is required to be **`explicit`**. The use of **`explicit`** rules out the initiation with type conversion using assignment syntax. -For more information on the class template `complex`, see [complex Class](../standard-library/complex-class.md). For a list of members of the class template `complex`, see . +For more information on the class template `complex` and its members, see [`complex` Class](complex-class.md). ## Example @@ -105,11 +104,11 @@ arg ( c3 ) = 0.896055 radians, which is 51.3402 degrees. ## Requirements -**Header**: \ +**Header**: `` -**Namespace:** std +**Namespace:** `std` ## See also -[complex Class](../standard-library/complex-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`complex` Class](complex-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/complex-float.md b/docs/standard-library/complex-float.md index d6672b4dfbe..3a2537bc63e 100644 --- a/docs/standard-library/complex-float.md +++ b/docs/standard-library/complex-float.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: complex" title: "complex" -ms.date: "11/04/2016" +description: "Learn more about: complex" +ms.date: 11/04/2016 f1_keywords: ["complex/std::complex"] helpviewer_keywords: ["complex function"] -ms.assetid: 1178eb1e-39bd-4017-89cd-aea95f813939 --- # `complex` @@ -34,13 +33,13 @@ constexpr complex( ### Parameters -*_RealVal*\ +*`_RealVal`*\ The value of type **`float`** for the real part of the complex number being constructed. -*_ImagVal*\ +*`_ImagVal`*\ The value of type **`float`** for the imaginary part of the complex number being constructed. -*complexNum*\ +*`complexNum`*\ The complex number of type **`double`** or of type **`long double`** whose real and imaginary parts are used to initialize a complex number of type **`float`** being constructed. ## Return Value @@ -51,7 +50,7 @@ A complex number of type **`float`**. The explicit specialization of the class template complex to a complex class of type **`float`** differs from the class template only in the constructors it defines. The conversion from **`float`** to **`double`** is allowed to be implicit, but the less safe conversion from **`float`** to **`long double`** is required to be **`explicit`**. The use of **`explicit`** rules out the initiation with type conversion using assignment syntax. -For more information on the class template `complex`, see [complex Class](../standard-library/complex-class.md). For a list of members of the class template `complex`, see . +For more information on the class template `complex` and its members, see [`complex` Class](complex-class.md). ## Example @@ -111,11 +110,11 @@ arg ( c3 ) = 0.927295 radians, which is 53.1301 degrees. ## Requirements -**Header**: \ +**Header**: `` -**Namespace:** std +**Namespace:** `std` ## See also -[complex Class](../standard-library/complex-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`complex` Class](complex-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/complex-long-double.md b/docs/standard-library/complex-long-double.md index b84606143bb..1ef66888470 100644 --- a/docs/standard-library/complex-long-double.md +++ b/docs/standard-library/complex-long-double.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: complex" title: "complex" -ms.date: "11/04/2016" +description: "Learn more about: complex" +ms.date: 11/04/2016 f1_keywords: ["std::complex", "complex", "std.complex"] helpviewer_keywords: ["complex function"] -ms.assetid: 37591991-b385-46e9-b727-d534dbc10432 --- # `complex` @@ -29,13 +28,13 @@ complex( ### Parameters -*_RealVal*\ +*`_RealVal`*\ The value of type **`long double`** for the real part of the complex number being constructed. -*_ImagVal*\ +*`_ImagVal`*\ The value of type **`long double`** for the imaginary part of the complex number being constructed. -*complexNum*\ +*`complexNum`*\ The complex number of type **`double`** or of type **`float`** whose real and imaginary parts are used to initialize a complex number of type **`long double`** being constructed. ## Return Value @@ -46,7 +45,7 @@ A complex number of type **`long double`**. The explicit specialization of the class template `complex` to a complex class of type **`long double`** differs from the class template only in the constructors it defines. The conversion from **`long double`** to **`float`** is allowed to be implicit, but the conversion from **`double`** to **`long double`** is required to be **`explicit`**. The use of **`explicit`** rules out the initiation with type conversion using assignment syntax. -For more information on the class template `complex` and its members, see [complex Class](../standard-library/complex-class.md). +For more information on the class template `complex` and its members, see [`complex` Class](complex-class.md). **Microsoft-specific**: The **`long double`** and **`double`** types have the same representation, but are distinct types. For more information, see [Built-in types](../cpp/fundamental-types-cpp.md). @@ -108,11 +107,11 @@ arg( c3 ) = 0.927295 radians, which is 53.1301 degrees. ## Requirements -**Header**: \ +**Header**: `` -**Namespace:** std +**Namespace:** `std` ## See also -[complex Class](../standard-library/complex-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`complex` Class](complex-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/condition-variable-enums.md b/docs/standard-library/condition-variable-enums.md index 2f2e3e650ba..23501c7ec38 100644 --- a/docs/standard-library/condition-variable-enums.md +++ b/docs/standard-library/condition-variable-enums.md @@ -1,17 +1,21 @@ --- -description: "Learn more about: enums" title: " enums" -ms.date: "11/04/2016" +description: "Learn more about: enums" +ms.date: 11/04/2016 f1_keywords: ["condition_variable/std::cv_status"] -ms.assetid: f261ad79-e25b-4afa-9f8a-909ce697e0d8 --- # `` enums -## cv_status +The `` header provides the following enums: + +## `cv_status` -Supplies symbolic names for the return values of the methods of class template [condition_variable](../standard-library/condition-variable-class.md). +Supplies symbolic names for the return values of the methods of class template [`condition_variable`](condition-variable-class.md). -class cv_status { - no_timeout - timeout +```cpp +enum class cv_status +{ + no_timeout, + timeout }; +``` diff --git a/docs/standard-library/container-class-begin.md b/docs/standard-library/container-class-begin.md deleted file mode 100644 index 18f29cf3dc1..00000000000 --- a/docs/standard-library/container-class-begin.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: "Learn more about: Container Class::begin" -title: "Container Class::begin" -ms.date: "05/07/2019" -helpviewer_keywords: ["begin method"] -ms.assetid: 633708cb-17fe-488b-9fb1-1b5f2da0f46c ---- -# Container Class::begin - -> [!NOTE] -> This topic is in the Visual Studio C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Returns an iterator that points at the first element of the sequence (or just beyond the end of an empty sequence). - -## Syntax - -```cpp -const_iterator begin() const; - -iterator begin(); -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-clear.md b/docs/standard-library/container-class-clear.md deleted file mode 100644 index ff6627e9ed9..00000000000 --- a/docs/standard-library/container-class-clear.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: "Learn more about: Container Class::clear" -title: "Container Class::clear" -ms.date: "11/04/2016" -helpviewer_keywords: ["clear method"] -ms.assetid: 725f2717-5dc2-428f-a19a-05f046aafb2b ---- -# Container Class::clear - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Calls [erase](../standard-library/container-class-erase.md)([begin](../standard-library/container-class-begin.md), [end](../standard-library/container-class-end.md)). - -## Syntax - -```cpp -void clear(); -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-const-iterator.md b/docs/standard-library/container-class-const-iterator.md deleted file mode 100644 index b54276698fb..00000000000 --- a/docs/standard-library/container-class-const-iterator.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::const_iterator" -title: "Container Class::const_iterator" -ms.date: "11/04/2016" -helpviewer_keywords: ["const_iterator method"] -ms.assetid: e68c9e30-fc4c-4c2e-8724-06d1fe8b8ccb ---- -# Container Class::const_iterator - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can serve as a constant iterator for the controlled sequence. - -## Syntax - -```cpp -typedef T6 const_iterator; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T6`. - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-const-reference.md b/docs/standard-library/container-class-const-reference.md deleted file mode 100644 index 9c926215247..00000000000 --- a/docs/standard-library/container-class-const-reference.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::const_reference" -title: "Container Class::const_reference" -ms.date: "11/04/2016" -helpviewer_keywords: ["const_reference method"] -ms.assetid: 7a5cfddb-3abf-4c98-b4ad-bbe4da9a5c1b ---- -# Container Class::const_reference - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can serve as a constant reference to an element of the controlled sequence. - -## Syntax - -```cpp -typedef T3 const_reference; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T3` (typically `Alloc::const_reference`). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-const-reverse-iterator.md b/docs/standard-library/container-class-const-reverse-iterator.md deleted file mode 100644 index 274c0dae9c9..00000000000 --- a/docs/standard-library/container-class-const-reverse-iterator.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::const_reverse_iterator" -title: "Container Class::const_reverse_iterator" -ms.date: "11/04/2016" -helpviewer_keywords: ["const_reverse_iterator method"] -ms.assetid: ceac84d5-a40f-4bbf-81e0-a96aa2bd8ee8 ---- -# Container Class::const_reverse_iterator - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can serve as a constant reverse iterator for the controlled sequence. - -## Syntax - -```cpp -typedef T8 const_reverse_iterator; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T8` (typically [reverse_iterator](../standard-library/container-class-reverse-iterator.md) <[const_iterator](../standard-library/container-class-const-iterator.md)`>`). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-difference-type.md b/docs/standard-library/container-class-difference-type.md deleted file mode 100644 index 3a271d8bfd4..00000000000 --- a/docs/standard-library/container-class-difference-type.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::difference_type" -title: "Container Class::difference_type" -ms.date: "11/04/2016" -helpviewer_keywords: ["difference_type typedef"] -ms.assetid: fae52485-d424-484e-9856-13505cfe528c ---- -# Container Class::difference_type - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can represent the difference between the addresses of any two elements in the controlled sequence. - -## Syntax - -```cpp -typedef T1 difference_type; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T1` (typically `Alloc::difference_type`). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-empty.md b/docs/standard-library/container-class-empty.md deleted file mode 100644 index f4064bbd769..00000000000 --- a/docs/standard-library/container-class-empty.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: "Learn more about: Container Class::empty" -title: "Container Class::empty" -ms.date: "11/04/2016" -helpviewer_keywords: ["empty method"] -ms.assetid: 2055418d-3c42-4d28-a7db-111586119ed9 ---- -# Container Class::empty - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Returns **`true`** for an empty controlled sequence. - -## Syntax - -```cpp -bool empty() const; -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-end.md b/docs/standard-library/container-class-end.md deleted file mode 100644 index b5da84d78d4..00000000000 --- a/docs/standard-library/container-class-end.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: "Learn more about: Container Class::end" -title: "Container Class::end" -ms.date: "11/04/2016" -helpviewer_keywords: ["end method"] -ms.assetid: 6fa38a20-3798-4387-9c6e-20fc3e90d813 ---- -# Container Class::end - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Returns an iterator that points just beyond the end of the sequence. - -## Syntax - -```cpp -const_iterator end() const; - -iterator end(); -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-erase.md b/docs/standard-library/container-class-erase.md deleted file mode 100644 index 2101b201e4d..00000000000 --- a/docs/standard-library/container-class-erase.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -description: "Learn more about: Container Class::erase" -title: "Container Class::erase" -ms.date: "11/04/2016" -helpviewer_keywords: ["erase method"] -ms.assetid: abc091c5-5a80-4bd8-93a8-a2d9bde2efec ---- -# Container Class::erase - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Erases an element. - -## Syntax - -```cpp -iterator erase( - iterator _Where); - -iterator erase( - iterator first, - iterator last); -``` - -## Remarks - -The first member function removes the element of the controlled sequence pointed to by *_Where*. The second member function removes the elements of the controlled sequence in the range [`first`, `last`). Both return an iterator that designates the first element remaining beyond any elements removed, or [end](../standard-library/container-class-end.md) if no such element exists. - -The member functions throw an exception only if a copy operation throws an exception. - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-iterator.md b/docs/standard-library/container-class-iterator.md deleted file mode 100644 index 1b778bdd2a4..00000000000 --- a/docs/standard-library/container-class-iterator.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::iterator" -title: "Container Class::iterator" -ms.date: "11/04/2016" -helpviewer_keywords: ["iterator method"] -ms.assetid: f9c49d1c-17cb-4b17-8e54-09e3ea41ca26 ---- -# Container Class::iterator - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can serve as an iterator for the controlled sequence. - -## Syntax - -```cpp -typedef T5 iterator; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T5`. An object of type `iterator` can be cast to an object of type [const_iterator](../standard-library/container-class-const-iterator.md). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-max-size.md b/docs/standard-library/container-class-max-size.md deleted file mode 100644 index 7cf4e3fa353..00000000000 --- a/docs/standard-library/container-class-max-size.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: "Learn more about: Container Class::max_size" -title: "Container Class::max_size" -ms.date: "11/04/2016" -helpviewer_keywords: ["max_size method"] -ms.assetid: 56754753-9911-48fd-b463-ac06b2fa1aab ---- -# Container Class::max_size - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Returns the length of the longest sequence that the object can control, in constant time regardless of the length of the controlled sequence. - -## Syntax - -```cpp -size_type max_size() const; -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-rbegin.md b/docs/standard-library/container-class-rbegin.md deleted file mode 100644 index b4fb7e06e48..00000000000 --- a/docs/standard-library/container-class-rbegin.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: "Learn more about: Container Class::rbegin" -title: "Container Class::rbegin" -ms.date: "11/04/2016" -helpviewer_keywords: ["rbegin method"] -ms.assetid: c1f0d60c-93aa-4313-81b9-04e3f9c796c2 ---- -# Container Class::rbegin - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Returns a reverse iterator that points just beyond the end of the controlled sequence, designating the beginning of the reverse sequence. - -## Syntax - -```cpp -const_reverse_iterator rbegin() const; - -reverse_iterator rbegin(); -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-reference.md b/docs/standard-library/container-class-reference.md deleted file mode 100644 index d595948cd5b..00000000000 --- a/docs/standard-library/container-class-reference.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::reference" -title: "Container Class::reference" -ms.date: "11/04/2016" -helpviewer_keywords: ["reference method"] -ms.assetid: ab85a9fb-c628-4761-9a5f-a0231fad7690 ---- -# Container Class::reference - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can serve as a reference to an element of the controlled sequence. - -## Syntax - -```cpp -typedef T2 reference; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T2` (typically `Alloc::reference`). An object of type `reference` can be cast to an object of type [const_reference](../standard-library/container-class-const-reference.md). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-rend.md b/docs/standard-library/container-class-rend.md deleted file mode 100644 index 82a170fc152..00000000000 --- a/docs/standard-library/container-class-rend.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -description: "Learn more about: Container Class::rend" -title: "Container Class::rend" -ms.date: "11/04/2016" -helpviewer_keywords: ["rend method"] -ms.assetid: 80f3dd04-dd2c-4b52-b0ed-d567ec5d186c ---- -# Container Class::rend - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -The member function returns a reverse iterator that points at the first element of the sequence (or just beyond the end of an empty sequence), designating the end of the reverse sequence. - -## Syntax - -```cpp -const_reverse_iterator rend() const; - -reverse_iterator rend(); -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-reverse-iterator.md b/docs/standard-library/container-class-reverse-iterator.md deleted file mode 100644 index 73a36729007..00000000000 --- a/docs/standard-library/container-class-reverse-iterator.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::reverse_iterator" -title: "Container Class::reverse_iterator" -ms.date: "11/04/2016" -helpviewer_keywords: ["reverse_iterator method"] -ms.assetid: 1d190c41-56b1-462e-b564-793b2a883c26 ---- -# Container Class::reverse_iterator - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can serve as a reverse iterator for the controlled sequence. - -## Syntax - -```cpp -typedef T7 reverse_iterator; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T7` (typically `reverse_iterator` **\<**[iterator](../standard-library/container-class-iterator.md)**>**). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-size-type.md b/docs/standard-library/container-class-size-type.md deleted file mode 100644 index 458b57a0582..00000000000 --- a/docs/standard-library/container-class-size-type.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::size_type" -title: "Container Class::size_type" -ms.date: "11/04/2016" -helpviewer_keywords: ["size_type typedef"] -ms.assetid: e02de8af-e175-45a2-b006-835814a40e68 ---- -# Container Class::size_type - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that can represent the length of any controlled sequence. - -## Syntax - -```cpp -typedef T0 size_type; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T0` (typically `Alloc::size_type`). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-size.md b/docs/standard-library/container-class-size.md deleted file mode 100644 index 07a0e4ea210..00000000000 --- a/docs/standard-library/container-class-size.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -description: "Learn more about: Container Class::size" -title: "Container Class::size" -ms.date: "11/04/2016" -helpviewer_keywords: ["size method"] -ms.assetid: 67073661-2699-4534-ad3b-31a906658dc5 ---- -# Container Class::size - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Returns the length of the controlled sequence, in constant time regardless of the length of the controlled sequence. - -## Syntax - -```cpp -size_type size() const; -``` - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-swap.md b/docs/standard-library/container-class-swap.md deleted file mode 100644 index 1e976af3713..00000000000 --- a/docs/standard-library/container-class-swap.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -description: "Learn more about: Container Class::swap" -title: "Container Class::swap" -ms.date: 06/10/2022 -helpviewer_keywords: ["swap method"] -ms.assetid: 898c219c-bc8e-4d14-a149-6240426c693f -ms.custom: devdivchpfy22 ---- - -# Container Class::swap - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Swaps the controlled sequences between `*this` and its argument. - -## Syntax - -```cpp -void swap(Container& right); -``` - -## Remarks - -If `*this.get_allocator == right.get_allocator`, it does a swap in constant time. Otherwise, it performs element assignments and constructor calls proportional to the number of elements in the two controlled sequences. - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/container-class-value-type.md b/docs/standard-library/container-class-value-type.md deleted file mode 100644 index 9ff7647669d..00000000000 --- a/docs/standard-library/container-class-value-type.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: Container Class::value_type" -title: "Container Class::value_type" -ms.date: "11/04/2016" -helpviewer_keywords: ["value_type typedef"] -ms.assetid: e89d5a71-b48c-47fa-aa78-682243e6e97f ---- -# Container Class::value_type - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Acts a synonym for the template parameter *Ty*. - -## Syntax - -```cpp -typedef T4 value_type; -``` - -## Remarks - -It is described here as a synonym for the unspecified type `T4` (typically `Alloc::value_type`). - -## See also - -[Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/cpp-standard-library-header-files.md b/docs/standard-library/cpp-standard-library-header-files.md index 42ef673a990..969be33da60 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: 03/05/2026 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,27 @@ 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 | +| Container views | ``23, [``](span.md)20 | +| Diagnostics | ``23 | | [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 | -| [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 | +| General utilities | [``](any.md)17, [``](bit.md)20, [``](bitset.md), [``](cstdlib.md), [``](execution.md)17, ``23, [``](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, ``20, [``](fstream.md), [``](iomanip.md), [``](ios.md), [``](iosfwd.md), [``](iostream.md), [``](istream.md), [``](ostream.md), ``23, ``23, [``](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 | +| Language support | [``](cfloat.md), [``](climits.md), [``](codecvt.md)11 a, ``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), ``20, ``23, [``](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 | -| Multithreading | [``](atomic.md)11, [``](condition-variable.md)11, [``](future.md)11, [``](mutex.md)11, [``](shared-mutex.md)14, [``](thread.md)11 | -| Ranges | ``20 | +| Math and numerics | [``](bit.md)20, [``](cfenv.md)11, [``](cmath.md), [``](complex.md), [``](cstdlib.md), [``](limits.md), ``20, [``](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, ``20, [``](condition-variable.md)11, [``](future.md)11, ``20, [``](mutex.md)11, ``20, [``](shared-mutex.md)14, ``20, [``](thread.md)11 | +| Ranges | ``23, [``](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) | @@ -42,9 +42,10 @@ Header files for the C++ standard library and extensions, by category. 11 Added in the C++11 standard.\ 14 Added in the C++14 standard.\ 17 Added in the C++17 standard.\ -20 Added in the draft C++20 standard.\ +20 Added in the C++20 standard.\ +23 Added in the C++23 standard.\ a Deprecated in the C++17 standard.\ -b Removed in the draft C++20 standard.\ +b Removed in the C++20 standard.\ c Deprecated in the C++98 standard. ::: moniker-end @@ -53,13 +54,13 @@ 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)| -|Adaptor containers|[``](queue.md), [``](stack.md)| +|Container adaptors|[``](queue.md), [``](stack.md)| |[Errors and exception handling](../cpp/errors-and-exception-handling-modern-cpp.md)|[``](exception.md), [``](stdexcept.md), [``](system-error.md)| |[I/O and formatting](../text/string-and-i-o-formatting-modern-cpp.md)|[``](filesystem.md), [``](fstream.md), [``](iomanip.md), [``](ios.md), [``](iosfwd.md), [``](iostream.md), [``](istream.md), [``](ostream.md), [``](sstream.md), [``](streambuf.md), [``](strstream.md)| |Iterators|[``](iterator.md)| diff --git a/docs/standard-library/cpp-standard-library-overview.md b/docs/standard-library/cpp-standard-library-overview.md index d973bef5be6..f32d1019593 100644 --- a/docs/standard-library/cpp-standard-library-overview.md +++ b/docs/standard-library/cpp-standard-library-overview.md @@ -1,55 +1,74 @@ --- -description: "Learn more about: C++ Standard Library Overview" -title: "C++ Standard Library Overview" -ms.date: "11/04/2016" -helpviewer_keywords: ["headers, C++ library", "C++ Standard Library", "libraries, Standard C++", "C++ Standard Library, headers"] -ms.assetid: 7acb83a4-da73-4ad3-bc30-a71289db7f60 +description: "Learn more about: C++ Standard Library (STL) Overview" +title: "C++ Standard Library Overview (STL)" +ms.date: "08/18/2022" +helpviewer_keywords: ["headers, C++ library", "C++ Standard Library", "libraries, Standard C++", "C++ Standard Library, headers", "STL", "Standard template library, headers"] --- -# C++ Standard Library Overview +# C++ Standard Library (STL) overview -All C++ library entities are declared or defined in one or more standard headers. This implementation includes two additional headers, `` and ``, that are not required by the C++ Standard. For a complete list of headers that this implementation supports, see [Header Files Reference](../standard-library/cpp-standard-library-header-files.md). +All C++ library entities are declared or defined in one or more standard headers. This implementation includes two other headers, `` and ``, that aren't required by the C++ Standard. For a complete list of headers that this implementation supports, see [Header files reference](../standard-library/cpp-standard-library-header-files.md). -A freestanding implementation of the C++ library provides only a subset of these headers: +The C++ standard defines two kinds of conforming libraries: +- A *hosted implementation*, which supports all of the required standard library headers described by the C++ ISO standard. +- A *freestanding implementation*, which requires only a subset of the standard library headers. The required subset is: -[``](../standard-library/cstdarg.md)\ -[``](../standard-library/cstddef.md)\ -[``](../standard-library/cstdlib.md) (declaring at least the functions `abort`, `atexit`, and `exit`)\ -[``](../standard-library/exception.md)\ -[``](../standard-library/limits.md)\ -[``](../standard-library/new.md) +| Freestanding header subset |   |   | +|--|--|--| +| [``](../standard-library/atomic.md) (declaring at least `atomic_signed_lock_free` and `atomic_unsigned_lock_free`) | [``](../standard-library/cstdint.md) | [``](../standard-library/ranges.md) | +| [``](../standard-library/bit.md) | [``](../standard-library/cstdlib.md) (declaring at least `abort`, `atexit`, `at_quick_exit`, `exit`, `quick_exit`) | [``](../standard-library/ratio.md) | +| [``](../standard-library/cfloat.md) | [``](../standard-library/exception.md) | [``](../standard-library/tuple.md) | +| [``](../standard-library/climits.md) | [``](../standard-library/functional.md) | [``](../standard-library/typeinfo.md) | +| `` | [``](../standard-library/initializer-list.md) | `` | +| `` | [``](../standard-library/iterator.md) | [``](../standard-library/type-traits.md) | +| `` | [``](../standard-library/limits.md) | [``](../standard-library/utility.md) | +| [``](../standard-library/cstdarg.md) | [``](../standard-library/memory.md) | `` | +| [``](../standard-library/cstddef.md) | [``](../standard-library/new.md) | | + +The following headers are deprecated since C++11: [``](../standard-library/ciso646.md), [``](../standard-library/cstdalign.md), and [``](../standard-library/cstdbool.md). + +Other differences between freestanding and hosted implementations are: + +- Hosted implementations require a global function named `main`. A freestanding implementation can define its own startup and termination functions. +- Hosted implementations must support more than one thread running at the same time. Implementors of freestanding implementations decide whether their library supports concurrent threads. + +The Microsoft C++ standard library satisfies both freestanding and hosted requirements. The C++ library headers have two broader subdivisions: - [iostreams](../standard-library/iostreams-conventions.md) conventions. -- [C++ Standard Library Reference](../standard-library/cpp-standard-library-reference.md) conventions. +- [C++ Standard library (STL) reference](../standard-library/cpp-standard-library-reference.md) conventions. This section contains the following sections: -- [Using C++ Library Headers](../standard-library/using-cpp-library-headers.md) +- [Using C++ library headers](../standard-library/using-cpp-library-headers.md) -- [C++ Library Conventions](../standard-library/cpp-library-conventions.md) +- [C++ library conventions](../standard-library/cpp-library-conventions.md) - [iostreams Conventions](../standard-library/iostreams-conventions.md) -- [C++ Program Startup and Termination](../standard-library/cpp-program-startup-and-termination.md) +- [C++ program startup and termination](../standard-library/cpp-program-startup-and-termination.md) -- [Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md) +- [Safe libraries: C++ standard library](../standard-library/safe-libraries-cpp-standard-library.md) -- [Checked Iterators](../standard-library/checked-iterators.md) +- [Checked iterators](../standard-library/checked-iterators.md) -- [Debug Iterator Support](../standard-library/debug-iterator-support.md) +- [Debug iterator support](../standard-library/debug-iterator-support.md) -- [C++ Standard Library Reference](../standard-library/cpp-standard-library-reference.md) +- [C++ standard library (STL) reference](../standard-library/cpp-standard-library-reference.md) -- [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +- [Thread safety in the C++ standard library](../standard-library/thread-safety-in-the-cpp-standard-library.md) -- [stdext Namespace](../standard-library/stdext-namespace.md) +- [stdext namespace](../standard-library/stdext-namespace.md) -- [Regular Expressions (C++)](../standard-library/regular-expressions-cpp.md) +- [Regular expressions (C++)](../standard-library/regular-expressions-cpp.md) For more information about Visual C++ run-time libraries, see [CRT Library Features](../c-runtime-library/crt-library-features.md). +> [!NOTE] +> Microsoft's implementation of the C++ Standard Library is often referred to as the *STL* or *Standard Template Library*. Although *C++ Standard Library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation. +From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ Standard Library, along with the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is also used to refer to the containers and algorithms parts of the C++ Standard Library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ Standard Library as a whole. + ## See also [C++ Standard Library](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/standard-library/cpp-standard-library-reference.md b/docs/standard-library/cpp-standard-library-reference.md index 2066af80948..6ae574d37e9 100644 --- a/docs/standard-library/cpp-standard-library-reference.md +++ b/docs/standard-library/cpp-standard-library-reference.md @@ -1,23 +1,28 @@ --- -description: "Learn more about: C++ Standard Library Reference" title: "C++ Standard Library Reference" -ms.date: "3/5/2021" -helpviewer_keywords: ["C++ Standard Library, reference", "C++ Standard Library", "template libraries", "libraries, Standard C++"] +description: "Learn more about: C++ Standard Library Reference (STL)" +ms.date: 3/5/2021 +helpviewer_keywords: ["C++ Standard Library, reference", "C++ Standard Library", "template libraries", "libraries, Standard C++", "Microsoft standard template library, reference", "Microsoft STL, reference"] --- -# C++ Standard Library reference +# C++ Standard Library reference (STL) A C++ program can call on a large number of functions from this conforming implementation of the C++ Standard Library. These functions perform services such as input and output and provide efficient implementations of frequently used operations. For more information about linking with the appropriate Visual C++ runtime `.lib` file, see [C runtime (CRT) and C++ Standard Library (STL) `.lib` files](../c-runtime-library/crt-library-features.md). +> [!NOTE] +> Microsoft's implementation of the C++ Standard Library is often referred to as the *STL* or *Standard Template Library*. Although *C++ Standard Library* is the official name of the library as defined in ISO 14882, due to the popular use of "STL" and "Standard Template Library" in search engines, we occasionally use those names to make it easier to find our documentation. + +From a historical perspective, "STL" originally referred to the Standard Template Library written by Alexander Stepanov. Parts of that library were standardized in the C++ Standard Library, along with the ISO C runtime library, parts of the Boost library, and other functionality. Sometimes "STL" is used to refer to the containers and algorithms parts of the C++ Standard Library adapted from Stepanov's STL. In this documentation, Standard Template Library (STL) refers to the C++ Standard Library as a whole. + ## In this section -[C++ Standard Library overview](../standard-library/cpp-standard-library-overview.md)\ +[C++ Standard Library overview](cpp-standard-library-overview.md)\ Provides an overview of the Microsoft implementation of the C++ Standard Library. -[`iostream` Programming](../standard-library/iostream-programming.md)\ +[`iostream` programming](iostream-programming.md)\ Provides an overview of `iostream` programming. -[Header files reference](../standard-library/cpp-standard-library-header-files.md)\ +[Header files reference](cpp-standard-library-header-files.md)\ Provides links to reference topics about the C++ Standard Library header files, with code examples. diff --git a/docs/standard-library/ctgmath.md b/docs/standard-library/ctgmath.md index 52245a16f9d..3a562793151 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 f8c4a596674..b959d0f6018 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 32beff1c351..8a0c452ec94 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 @@ -108,7 +107,7 @@ The explicit specialization differs from the class template in several ways: - The static member object `table_size` specifies the minimum number of elements in a ctype mask table. -- The protected static member function `classic_table`( returns the ctype mask table appropriate to the "C" locale. +- The protected static member function `classic_table` returns the ctype mask table appropriate to the "C" locale. - There are no protected virtual member functions [do_is](../standard-library/ctype-class.md#do_is), [do_scan_is](../standard-library/ctype-class.md#do_scan_is), or [do_scan_not](../standard-library/ctype-class.md#do_scan_not). The corresponding public member functions perform the equivalent operations themselves. diff --git a/docs/standard-library/ctype-class.md b/docs/standard-library/ctype-class.md index 3a43c74acff..4d69b959369 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,8 +465,8 @@ 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 58d5cc7cc31..09f8a4bcb6a 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 3ce22b8c32e..c2ca25ac7e7 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 b3a963ab303..e97739f9488 100644 --- a/docs/standard-library/day-class.md +++ b/docs/standard-library/day-class.md @@ -1,19 +1,19 @@ --- -description: "Learn more about: day Class" title: "day class" +description: "Learn more about: day Class" ms.date: 09/07/2021 -f1_keywords: ["chrono/std::chrono::day", "chrono/std::chrono::day::ok", "chrono/std::chrono::day:operator++", "chrono/std::chrono::day::operator--", "chrono/std::chrono::day::operator unsigned"] +f1_keywords: ["chrono/std::chrono::day", "chrono/std::chrono::day::ok", "chrono/std::chrono::day::operator++", "chrono/std::chrono::day::operator--", "chrono/std::chrono::day::operator unsigned"] helpviewer_keywords: ["std::chrono [C++], day"] dev_langs: ["C++"] --- -# `day` class +# `day` class 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/debug-iterator-support.md b/docs/standard-library/debug-iterator-support.md index 66a3ccf04de..fa3a18b7bcd 100644 --- a/docs/standard-library/debug-iterator-support.md +++ b/docs/standard-library/debug-iterator-support.md @@ -3,7 +3,6 @@ description: "Learn more about: Debug Iterator Support" title: "Debug Iterator Support" ms.date: "09/13/2018" helpviewer_keywords: ["Safe Libraries", "Safe Libraries, C++ Standard Library", "Safe C++ Standard Library", "C++ Standard Library, debug iterator support", "iterators, debug iterator support", "iterators, incompatible", "incompatible iterators", "debug iterator support"] -ms.assetid: f3f5bd15-4be8-4d64-a4d0-8bc0761c68b6 --- # Debug Iterator Support @@ -43,7 +42,7 @@ int main() { ## Using _ITERATOR_DEBUG_LEVEL -You can use the preprocessor macro [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) to turn off the iterator debugging feature in a debug build. This program does not assert, but still triggers undefined behavior. +You can use the preprocessor macro [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md) to turn off the iterator debugging feature in a debug build. This program doesn't assert, but still triggers undefined behavior. ```cpp // iterator_debugging_1.cpp @@ -74,9 +73,9 @@ int main() { -572662307 ``` -## Unitialized iterators +## Uninitialized iterators -An assert also occurs if you attempt to use an iterator before it is initialized, as shown here: +An assert also occurs if you attempt to use an iterator before it's initialized, as shown here: ```cpp // iterator_debugging_2.cpp @@ -113,7 +112,7 @@ int main() } ``` -Notice that this example uses the lambda expression `[] (int& elem) { elem *= 2; }` instead of a functor. Although this choice has no bearing on the assert failure—a similar functor would cause the same failure—lambdas are a very useful way to accomplish compact function object tasks. For more information about lambda expressions, see [Lambda Expressions](../cpp/lambda-expressions-in-cpp.md). +Notice that this example uses the lambda expression `[] (int& elem) { elem *= 2; }` instead of a functor. Although this choice has no bearing on the assert failure—a similar functor would cause the same failure—lambdas are a way to write a short block of code. For more information about lambda expressions, see [Lambda expressions](../cpp/lambda-expressions-in-cpp.md). ## Iterators going out of scope @@ -135,7 +134,7 @@ int main() { ## Destructors for debug iterators -Debug iterators have non-trivial destructors. If a destructor does not run but the object's memory is freed, access violations and data corruption might occur. Consider this example: +Debug iterators have non-trivial destructors. If a destructor doesn't run but the object's memory is freed, access violations and data corruption might occur. Consider this example: ```cpp // iterator_debugging_5.cpp diff --git a/docs/standard-library/default-searcher-class.md b/docs/standard-library/default-searcher-class.md index c73289aaea7..05072631862 100644 --- a/docs/standard-library/default-searcher-class.md +++ b/docs/standard-library/default-searcher-class.md @@ -7,7 +7,7 @@ helpviewer_keywords: ["std::default_searcher [C++]"] --- # default_searcher Class -A `default_searcher` is a function object type for operations that search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object’s function call operator. The `default_searcher` invokes [std::search](algorithm-functions.md#search) to perform the search. +A `default_searcher` is a function object type for operations that search for a sequence specified in the object's constructor. The search is done within another sequence provided to the object's function call operator. The `default_searcher` invokes [std::search](algorithm-functions.md#search) to perform the search. ## Syntax diff --git a/docs/standard-library/deque-class.md b/docs/standard-library/deque-class.md index 96b13c7fd9d..775b92a2d87 100644 --- a/docs/standard-library/deque-class.md +++ b/docs/standard-library/deque-class.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: deque Class" title: "deque Class" -ms.date: "11/04/2016" +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`.| @@ -237,7 +237,7 @@ If *`pos`* is greater than the size of the `deque`, `at` throws an exception. ### Remarks -If the return value of `at` is assigned to a `const_reference`, the `deque` object can’t be modified. If the return value of `at` is assigned to a `reference`, the `deque` object can be modified. +If the return value of `at` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `at` is assigned to a `reference`, the `deque` object can be modified. ### Example @@ -282,7 +282,7 @@ The last element of the `deque`. If the `deque` is empty, the return value is un ### Remarks -If the return value of `back` is assigned to a `const_reference`, the `deque` object can’t be modified. If the return value of `back` is assigned to a `reference`, the `deque` object can be modified. +If the return value of `back` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `back` is assigned to a `reference`, the `deque` object can be modified. When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element in an empty `deque`. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. @@ -331,7 +331,7 @@ A random-access iterator addressing the first element in the `deque` or to the l ### Remarks -If the return value of `begin` is assigned to a `const_iterator`, the `deque` object can’t be modified. If the return value of `begin` is assigned to an `iterator`, the `deque` object can be modified. +If the return value of `begin` is assigned to a `const_iterator`, the `deque` object can't be modified. If the return value of `begin` is assigned to an `iterator`, the `deque` object can be modified. ### Example @@ -354,7 +354,7 @@ int main( ) c1_Iter = c1.begin( ); cout << "The first element of c1 is " << *c1_Iter << endl; -*c1_Iter = 20; + *c1_Iter = 20; c1_Iter = c1.begin( ); cout << "The first element of c1 is now " << *c1_Iter << endl; @@ -382,7 +382,7 @@ A **`const`** random-access iterator that points at the first element of the ran ### Remarks -With the return value of `cbegin`, the elements in the range can’t be modified. +With the return value of `cbegin`, the elements in the range can't be modified. You can use this member function in place of the `begin()` member function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container of any kind that supports `begin()` and `cbegin()`. @@ -468,7 +468,7 @@ typedef implementation-defined const_iterator; ### Remarks -A type `const_iterator` can’t be used to modify the value of an element. +A type `const_iterator` can't be used to modify the value of an element. ### Example @@ -484,7 +484,7 @@ typedef typename Allocator::const_pointer const_pointer; ### Remarks -A type `const_pointer` can’t be used to modify the value of an element. An [`iterator`](#iterator) is more commonly used to access a `deque` element. +A type `const_pointer` can't be used to modify the value of an element. An [`iterator`](#iterator) is more commonly used to access a `deque` element. ## `const_reference` @@ -496,7 +496,7 @@ typedef typename Allocator::const_reference const_reference; ### Remarks -A type `const_reference` can’t be used to modify the value of an element. +A type `const_reference` can't be used to modify the value of an element. ### Example @@ -540,7 +540,7 @@ typedef std::reverse_iterator const_reverse_iterator; ### Remarks -A type `const_reverse_iterator` can’t modify the value of an element and is used to iterate through the `deque` in reverse. +A type `const_reverse_iterator` can't modify the value of an element and is used to iterate through the `deque` in reverse. ### Example @@ -560,7 +560,7 @@ A `const` reverse random-access iterator addressing the first element in a rever ### Remarks -With the return value of `crbegin`, the `deque` object can’t be modified. +With the return value of `crbegin`, the `deque` object can't be modified. ### Example @@ -611,7 +611,7 @@ A `const` reverse random-access iterator that addresses the location succeeding `crend` is used with a reversed `deque` just as [`array::cend`](../standard-library/array-class-stl.md#cend) is used with a `deque`. -With the return value of `crend` (suitably decremented), the `deque` object can’t be modified. +With the return value of `crend` (suitably decremented), the `deque` object can't be modified. `crend` can be used to test to whether a reverse iterator has reached the end of its `deque`. @@ -720,7 +720,7 @@ None of the constructors perform any interim reallocations. ### Example ```cpp -/ compile with: /EHsc +// compile with: /EHsc #include #include #include @@ -1328,7 +1328,7 @@ If the `deque` is empty, the return is undefined. ### Remarks -If the return value of `front` is assigned to a `const_reference`, the `deque` object can’t be modified. If the return value of `front` is assigned to a `reference`, the `deque` object can be modified. +If the return value of `front` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `front` is assigned to a `reference`, the `deque` object can be modified. When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element in an empty `deque`. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. @@ -1526,7 +1526,7 @@ A reference to the element whose position is specified in the argument. If the p ### Remarks -If the return value of `operator[]` is assigned to a `const_reference`, the `deque` object can’t be modified. If the return value of `operator[]` is assigned to a `reference`, the `deque` object can be modified. +If the return value of `operator[]` is assigned to a `const_reference`, the `deque` object can't be modified. If the return value of `operator[]` is assigned to a `reference`, the `deque` object can be modified. When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-debug-level.md) defined as 1 or 2, a runtime error will occur if you attempt to access an element outside the bounds of the `deque`. See [Checked Iterators](../standard-library/checked-iterators.md) for more information. @@ -1604,7 +1604,7 @@ template struct S { MyDeque::const_iterator iter; for (iter = d.cbegin(); iter != d.cend(); iter++) cout << *iter << " "; -cout << " via unnamed rvalue reference " << endl; + cout << " via unnamed rvalue reference " << endl; } }; @@ -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; ``` @@ -1818,7 +1818,7 @@ A reverse random-access iterator addressing the first element in a reversed `deq `rbegin` is used with a reversed `deque` just as [`begin`](#begin) is used with a `deque`. -If the return value of `rbegin` is assigned to a `const_reverse_iterator`, the `deque` object can’t be modified. If the return value of `rbegin` is assigned to a `reverse_iterator`, the `deque` object can be modified. +If the return value of `rbegin` is assigned to a `const_reverse_iterator`, the `deque` object can't be modified. If the return value of `rbegin` is assigned to a `reverse_iterator`, the `deque` object can be modified. `rbegin` can be used to iterate through a `deque` backwards. @@ -1930,7 +1930,7 @@ A reverse random-access iterator that addresses the location succeeding the last `rend` is used with a reversed `deque` just as [`end`](#end) is used with a `deque`. -If the return value of `rend` is assigned to a `const_reverse_iterator`, the `deque` object can’t be modified. If the return value of `rend` is assigned to a `reverse_iterator`, the `deque` object can be modified. +If the return value of `rend` is assigned to a `const_reverse_iterator`, the `deque` object can't be modified. If the return value of `rend` is assigned to a `reverse_iterator`, the `deque` object can be modified. `rend` can be used to test whether a reverse iterator has reached the end of its `deque`. diff --git a/docs/standard-library/deque-functions.md b/docs/standard-library/deque-functions.md index db96fab9930..ed6244dc98f 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/deque.md b/docs/standard-library/deque.md index 4a56c8107b7..30e85cc0034 100644 --- a/docs/standard-library/deque.md +++ b/docs/standard-library/deque.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["deque header"] -ms.assetid: 4521fe92-5a91-4853-9e9f-59600bf9e46f --- # `` @@ -25,7 +24,7 @@ Defines the container class template deque and several supporting templates. |-|-| |[operator!=](../standard-library/deque-operators.md#op_neq)|Tests if the deque object on the left side of the operator is not equal to the deque object on the right side.| |[operator<](../standard-library/deque-operators.md#op_lt)|Tests if the deque object on the left side of the operator is less than the deque object on the right side.| -|[operator\<=](../standard-library/deque-operators.md#op_gt_eq)|Tests if the deque object on the left side of the operator is less than or equal to the deque object on the right side.| +|[operator\<=](../standard-library/deque-operators.md#op_lt_eq)|Tests if the deque object on the left side of the operator is less than or equal to the deque object on the right side.| |[operator==](../standard-library/deque-operators.md#op_eq_eq)|Tests if the deque object on the left side of the operator is equal to the deque object on the right side.| |[operator>](../standard-library/deque-operators.md#op_gt)|Tests if the deque object on the left side of the operator is greater than the deque object on the right side.| |[operator>=](../standard-library/deque-operators.md#op_gt_eq)|Tests if the deque object on the left side of the operator is greater than or equal to the deque object on the right side.| diff --git a/docs/standard-library/directory-iterator-class.md b/docs/standard-library/directory-iterator-class.md index 20425e83c4a..b377693eee2 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/domain-error-class.md b/docs/standard-library/domain-error-class.md index fe6bc72dfe1..c976e9d9d67 100644 --- a/docs/standard-library/domain-error-class.md +++ b/docs/standard-library/domain-error-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: domain_error Class" -title: "domain_error Class" -ms.date: "09/09/2021" +title: "domain_error class" +description: "Learn more about: domain_error class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::domain_error"] helpviewer_keywords: ["domain_error class"] -ms.assetid: a1d8245d-61c2-4d1e-973f-073bd5dd5fa3 --- -# domain_error Class +# `domain_error` class The class serves as the base class for all exceptions thrown to report a domain error (as in mathematics, not networking). @@ -18,13 +17,12 @@ public: explicit domain_error(const string& message); explicit domain_error(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). `domain_error` isn't thrown by any functions in the Microsoft implementation of the C++ Standard Library, but it might be thrown by third-party libraries or user code. @@ -51,19 +49,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: Your domain is in error! Type: class std::domain_error -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[logic_error Class](../standard-library/logic-error-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`logic_error` class](logic-error-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/drop-view-class.md b/docs/standard-library/drop-view-class.md new file mode 100644 index 00000000000..337a2b4cd44 --- /dev/null +++ b/docs/standard-library/drop-view-class.md @@ -0,0 +1,207 @@ +--- +title: drop_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) drop_view class, which creates a view from another view, skipping the first count elements." +ms.date: 10/19/2022 +f1_keywords: ["ranges/std::drop_view", "ranges/std::drop_view::base", "ranges/std::drop_view::begin", "ranges/std::drop_view::data", "ranges/std::drop_view::empty", "ranges/std::drop_view::end", "ranges/std::drop_view::size", "ranges/std::drop_view::operator bool", "ranges/std::drop_view::back", "ranges/std::drop_view::front", "ranges/std::drop_view::operator[]"] +helpviewer_keywords: ["std::ranges::drop_view [C++]", "std::ranges::drop_view::base [C++]", "std::ranges::drop_view::begin [C++]", "std::ranges::drop_view::data [C++]", "std::ranges::drop_view::empty [C++]", "std::ranges::drop_view::end [C++]", "std::ranges::drop_view::size [C++]", "std::ranges::drop_view::back [C++]", "std::ranges::drop_view::front [C++]", "std::ranges::drop_view::operator[] [C++]", "std::ranges::drop_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `drop_view` class (C++ Standard Library) + +Create a view that excludes the first *N* elements of a range. + +## Syntax + +```cpp +template +class drop_view : public ranges::view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::drop`](range-adaptors.md#drop) | +| **Underlying range** | Must satisfy [`output_range`](range-concepts.md#output_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable and satisfies [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range) | +| **Common range** | Only if the underlying range is a [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `drop_view`. | +| [`base`](#base)C++20 | Get the underlying view. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements in this view. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `drop_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `drop_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `drop_view` + +```cpp +template +class drop_view : public ranges::view_interface> +``` + +### Template parameters + +*`V`*\ +The type of the underlying view. + +### Return value + +A view of the underlying range, excluding the specified number of elements from the front.\ +If you specify more elements to drop than exist in the underlying range, then an `empty_view` is returned. + +### Remarks + +The best way to create a `drop_view` is by using the [`views::drop`](range-adaptors.md#drop) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +### Example: `drop_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 1, 2, 3, 4, 5 }; + auto newView = std::views::drop(v, 3); + for (auto e : newView) // outputs 4 5 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + auto numbers = std::views::iota(0) | std::views::take(10); // generate a view of 10 integers + for (auto i : numbers | std::views::drop(5)) // use the '|' syntax to create a drop_view + { + std::cout << i << ' '; // outputs 5 6 7 8 9 + } +} +``` + +```output +4 5 +5 6 7 8 9 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `drop_view`. + +```cpp +constexpr auto begin() + requires (!(Simple_view && ranges::random_access_range && ranges::sized_range)); + +constexpr auto begin() const + requires ranges::random_access_range && ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `drop_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `drop_view` + +```cpp +constexpr auto end() requires (!Simple_view); +constexpr auto end() const requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `drop_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the `drop_view`. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `drop_view`. + +### Remarks + +The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). + +## See also + +[``](ranges.md)\ +[`drop` range adaptor](range-adaptors.md#drop)\ +[`take_while()`](range-adaptors.md#take_while)\ +[`take_while_view`](take-while-view-class.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/drop-while-view-class.md b/docs/standard-library/drop-while-view-class.md new file mode 100644 index 00000000000..be9e17fff82 --- /dev/null +++ b/docs/standard-library/drop-while-view-class.md @@ -0,0 +1,231 @@ +--- +title: drop_while_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) drop_while_view class, which is a view that contains those elements of a range that remain once the leading elements that match a predicate are dropped." +ms.date: 08/04/2022 +f1_keywords: ["ranges/std::drop_while_view", "ranges/std::drop_while_view::base", "ranges/std::drop_while_view::begin", "ranges/std::drop_while_view::data", "ranges/std::drop_while_view::empty", "ranges/std::drop_while_view::end", "ranges/std::drop_while_view::size", "ranges/std::drop_while_view::operator bool", "ranges/std::drop_while_view::pred", "ranges/std::drop_while_view::back", "ranges/std::drop_while_view::front", "ranges/std::drop_while_view::operator[]"] +helpviewer_keywords: ["std::ranges::drop_while_view [C++]", "std::ranges::drop_while_view::base [C++]", "std::ranges::drop_while_view::begin [C++]", "std::ranges::drop_while_view::data [C++]", "std::ranges::drop_while_view::empty [C++]", "std::ranges::drop_while_view::size [C++]", "std::ranges::drop_while_view::end [C++]", +"std::ranges::drop_while_view::pred [C++]", "std::ranges::drop_while_view::back [C++]", "std::ranges::drop_while_view::front [C++]", "std::ranges::drop_while_view::operator[] [C++]", "std::ranges::drop_while_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `drop_while_view` class (C++ Standard Library) + +A view that contains the elements of a range that remain once the leading elements that match a predicate are dropped. + +## Syntax + +```cpp +template + requires ranges::input_range && + std::is_object_v

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

= default; +``` + +### Parameters + +*`base`*\ +The underlying range. + +*`pred`*\ +The predicate that determines the leading elements to drop. + +For information about the template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `drop_while_view` instance. + +### Remarks + +The best way to create a `drop_while_view` is by using the [`views::drop_while`](range-adaptors.md#drop_while) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Move constructs the `drop_while_view` from a *`base`* view and a *`pred`* predicate. Both *`base`* and *`pred`* are moved via `std::move()`.\ +2\) Default-constructs a `drop_while_view`. + +### Example: `drop_while_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto v) +{ + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto myView = std::views::drop_while( + v, + [](int i) {return i >= 0; }); + print(myView); // -4 5 6 + + auto myView2 = v | std::views::drop_while( + [](int i) {return i < 5; }); + print(myView2); // 5 6 +} +``` + +```output +-4 5 6 +5 6 +``` + +## `base` + +Get the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses std::move() to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end() +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `pred` + +Get a reference to the predicate that determines which leading elements to drop. + +```cpp +constexpr const Pred& pred() const; +``` + +### Return value + + A reference to the predicate. + +### Remarks + +If the view doesn't store a predicate, the behavior is undefined. + +### Example `pred` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto mv = v | std::views::drop_while( + [](int i) {return i < 5; }); // drop the leading elements < 5 + std::cout << std::boolalpha << mv.pred()(v[6]); // outputs "false" because v[6] = 6 and 6 is not less than 5 (the predicate) +} +``` + +```Output +false +``` + +## See also + +[``](ranges.md)\ +[`drop_while` range adaptor](range-adaptors.md#drop_while)\ +[`take_while` range adaptor](range-adaptors.md#take_while)\ +[`take_while_view`](take-while-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/duration-class.md b/docs/standard-library/duration-class.md index d0fa6d8e030..e3269876783 100644 --- a/docs/standard-library/duration-class.md +++ b/docs/standard-library/duration-class.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: duration class" title: "duration Class" +description: "Learn more about: duration class" ms.date: 01/05/2022 f1_keywords: ["chrono/std::chrono::duration", "chrono/std::chrono::duration::duration", "chrono/std::chrono::duration::count", "chrono/std::chrono::duration::max", "chrono/std::chrono::duration::min", "chrono/std::chrono::duration::zero","chrono/std::chrono::duration::operator-", "chrono/std::chrono::duration::operator--", "chrono/std::chrono::duration::operator%=", "chrono/std::chrono::duration::operator*=", "chrono/std::chrono::duration::operator+", "chrono/std::chrono::duration::operator++", "chrono/std::chrono::duration::operator+=", "chrono/std::chrono::duration::operator-=", "chrono/std::chrono::duration::operator="] helpviewer_keywords: ["std::chrono [C++], duration"] @@ -156,7 +156,7 @@ A duration type `D1` is *incommensurable* with another duration type `D2` if `D2 Unless *`Rep2`* is implicitly convertible to `rep` and either `treat_as_floating_point`*holds true* or `treat_as_floating_point`*holds false*, the second constructor doesn't participate in overload resolution. For more information, see [](type-traits.md). -Unless no overflow is induced in the conversion and `treat_as_floating_point`*holds true*, or both `ratio_divide::den` equals 1 and `treat_as_floating_point`*holds false*, the third constructor doesn't participate in overload resolution. For more information, see [](type-traits.md). +Unless no overflow is induced in the conversion and `treat_as_floating_point`*holds true*, or both `ratio_divide::den` equals 1 and `treat_as_floating_point`*holds false*, the third constructor doesn't participate in overload resolution. For more information, see [](type-traits.md). ## Example: Create a `duration` diff --git a/docs/standard-library/elements-view-class.md b/docs/standard-library/elements-view-class.md new file mode 100644 index 00000000000..86cbc8b57e8 --- /dev/null +++ b/docs/standard-library/elements-view-class.md @@ -0,0 +1,263 @@ +--- +title: elements_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) elements_view class, which provides a view over the selected index into each tuple-like value in a range." +ms.date: 09/27/2022 +f1_keywords: ["ranges/std::elements_view", "ranges/std::elements_view::base", "ranges/std::elements_view::begin", "ranges/std::elements_view::empty", "ranges/std::elements_view::end", "ranges/std::elements_view::size", "ranges/std::elements_view::operator bool", "ranges/std::elements_view::back", "ranges/std::elements_view::front", "ranges/std::elements_view::operator[]"] +helpviewer_keywords: ["std::ranges::elements_view [C++]", "std::ranges::elements_view::base [C++]", "std::ranges::elements_view::begin [C++]", "std::ranges::elements_view::empty [C++]", "std::ranges::elements_view::end [C++]", "std::ranges::elements_view::size [C++]", "std::ranges::elements_view::back [C++]", "std::ranges::elements_view::front [C++]", "std::ranges::elements_view::operator[] [C++]", "std::ranges::elements_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `elements_view` class (C++ Standard Library) + +A view over the elements at a selected index in each tuple-like value in a range. For example, given a range of `std::tuple`, create a view consisting of the `string` elements from each tuple. + +## Syntax + +```cpp +template +class elements_view : public view_interface>; +``` + +### Template parameters + +*`N`*\ +The index of the element to select for the view. + +*`V`*\ + The type of the underlying range. This type must satisfy `ranges::input_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::elements`](range-adaptors.md#elements) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the type of the indexed tuple element | +| **View iterator category** | [`forward_range`](range-concepts.md#forward_range), [`bidirectional_range`](range-concepts.md#bidirectional_range), or [`random_access_range`](range-concepts.md#random_access_range) | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `elements_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements in this view. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `elements_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `elements_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Remarks + +The tuple-like types that you can use with `elements_view` are [`std::tuple`](tuple.md), [`std::pair`](pair-structure.md), and [`std::array`](array.md). + +## Constructors + +Construct an instance of a `elements_view`. + +```cpp +1) constexpr elements_view(V base); +2) elements_view() requires std::default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +An `elements_view` instance. + +### Remarks + +The best way to create an `elements_view` is by using the [`elements`](range-adaptors.md#elements) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create an `elements_view` from the specified view.\ +2\) Default construct an `elements_view`. + +### Example: `elements_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include +#include +#include + +int main() +{ + // ========== work with a std::map + + std::map cpp_standards + { + {"C++98", 1988}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // create an elements_view of all the string elements (<1>) from each tuple + for (int const year : std::views::elements<1>(cpp_standards)) + { + std::cout << year << ' '; // 2003 2011 2014 2017 1988 2020 + } + + std::cout << '\n'; + + // Another way to call the range adaptor using pipe (|) syntax + for (auto&& name : cpp_standards | std::views::elements<0>) + { + std::cout << name << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 + } + std::cout << '\n'; + + // ========== working with arrays + + std::array, 3> arr = { {{0,1,2,3}, {4,5,6,7}, {8,9,10,11}} }; + for (int& fourth : arr | std::views::elements<3>) + { + std::cout << fourth << ' '; // 3 7 11 + } + std::cout << '\n'; + + // ========== work with a std::pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 98", 1998}, + {"Windows 2000", 2000} + }; + + for (int year : std::views::elements<1>(windows)) + { + std::cout << year << ' '; // 1985 1987 1990 1992 1993 1995 1996 1998 2000 + } +} +``` + +```output +2003 2011 2014 2017 1988 2020 +C++03 C++11 C++14 C++17 C++98 c++20 +3 7 11 +1985 1987 1990 1992 1993 1995 1996 1998 2000 +``` + +## `base` + +Gets a copy of the underlying range. + +```cpp +// Uses a copy constructor to return the underlying range +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying range +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying range. + +## `begin` + +Get an iterator to the first element in the `elements_view`. + +```cpp +1) constexpr auto begin() requires (!Simple_view); +2) constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `elements_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `elements_view` + +```cpp +1) constexpr auto end() requires (!Simple_view && !ranges::common_range); +2) constexpr auto end() requires (!Simple_view && ranges::common_range); +3) constexpr auto end() const requires ranges::range; +4) constexpr auto end() const requires ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `elements_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires sized_range; +constexpr auto size() const requires sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `elements_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[`keys_view`](keys-view-class.md)\ +[`values_view`](values-view-class.md)\ +[View classes](view-classes.md)\ +[``](ranges.md) diff --git a/docs/standard-library/empty-view-class.md b/docs/standard-library/empty-view-class.md new file mode 100644 index 00000000000..8811f1dd2fb --- /dev/null +++ b/docs/standard-library/empty-view-class.md @@ -0,0 +1,303 @@ +--- +title: empty_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) empty_view class, which is a view that has no elements. This view is useful for test purposes such as calling code that needs to be provided with a view but doesn't need to access its underlying data." +ms.date: 10/18/2022 +f1_keywords: ["ranges/std::empty_view", "ranges/std::empty_view::base", "ranges/std::empty_view::begin", "ranges/std::empty_view::end", "ranges/std::empty_view::size", "ranges/std::empty_view::empty", "ranges/std::empty_view::operator bool", "ranges/std::empty_view::data", "ranges/std::empty_view::back", "ranges/std::empty_view::front", "ranges/std::empty_view::operator[]"] +helpviewer_keywords: ["std::ranges::empty_view [C++]", "std::ranges::empty_view [C++], base", "std::ranges::empty_view [C++], begin", "std::ranges::empty_view [C++], end", "std::ranges::empty_view [C++], size", "std::ranges::empty_view [C++], data", "std::ranges::empty_view [C++], empty", "std::ranges::empty_view [C++], operator bool", "std::ranges::empty_view [C++], front", "std::ranges::empty_view [C++], back", "std::ranges::empty_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `empty_view` class (C++ Standard Library) + +A view with no elements. This view is useful for test purposes such as calling code that needs to be provided with a view but doesn't need to access its underlying data. + +## Syntax + +```cpp +template + requires std::is_object_v +class empty_view : public ranges::view_interface>; +``` + +### Template parameters + +*`T`*\ +The type of the element. Even though there are no elements in an `empty_view`, all ranges are homogeneous. That is, they have elements of a particular type. So even though an `empty_view` has no elements, it still has a type, such as an `empty_view` of `int`, or `strings`, etc. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::empty`](range-adaptors.md#empty) | +| **Underlying range** | None | +| **Element type** | As specified when the `empty_view` is created | +| **View iterator category** | `contiguous_range` | +| **Sized** | Yes. Always returns 0 | +| **Is `const`-iterable** | Yes | +| **Common range** | Yes | +| **Borrowed range** | Yes | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct an `empty_view`. | +| [`begin`](#begin) C++20| Returns `nullptr`. | +| [`end`](#end)C++20 | Returns `nullptr`. | +| [`size`](#size)C++20 | Returns 0 | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](#back)C++20 | Results in undefined behavior. | +| [`data`](#data)C++20 | Returns `nullptr`. | +| [`empty`](#empty)C++20 | Returns `true`. | +| [`front`](#front)C++20 | Results in undefined behavior. | +| [`operator[]`](#op_at)C++20 | Results in undefined behavior. | +| [`operator bool`](#op_bool)C++20 | Returns `false`. | + +## Remarks + +The best way to create a `empty_view` is by using the [`empty`](range-adaptors.md#empty) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +Because there can never be any elements in an `empty_view`, certain compiler optimizations are possible. For example, the compiler will eliminate `for (auto e : std::views::empty) {...}` because it knows that there's nothing to iterate over. + +Another use for `empty_view` is splitting a [`split_view`](split-view-class.md) with an `empty_view` delimiter, which results in a range of single element ranges. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `empty_view`. + +```cpp +template +inline constexpr empty_view empty{}; +``` + +### Parameters + +*`T`*\ + The type of the underlying element, of which there is none. + +### Remarks + +The best way to create a `empty_view` is by using the [`empty`](range-adaptors.md#empty) range adaptor. + +### Example `empty_view` + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + auto anEmptyView = std::views::empty; + bool isNotEmpty = (bool)anEmptyView; + std::cout << std::boolalpha << isNotEmpty << "\n"; // false + std::cout << std::boolalpha << anEmptyView.empty(); // true +} +``` + +```output +false +true +``` + +## `back` + +Results in undefined behavior. + +```cpp +constexpr auto back() + requires ranges::bidirectional_range && ranges::common_range; + +constexpr auto back() const + requires ranges::bidirectional_range && ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +None. + +### Remarks + +Calling this function in a debug build raises an assertion that the function has been called on an empty `view_interface`. + +## `begin` + +Returns `nullptr` because there isn't a first element in the view. + +```cpp +static constexpr T* begin() noexcept +``` + +### Return value + +`nullptr` + +## `data` + +Returns `nullptr` because there isn't a first element in the view to get a pointer to. + +```cpp +static constexpr T* data() noexcept +``` + +### Return value + +`nullptr`. + +## `empty` + +Test whether the derived view is empty. + +```cpp +static constexpr bool empty() noexcept +``` + +### Parameters + +None. + +### Return value + +Returns `true`. + +## `end` + +Returns `nullptr` because there aren't any elements in the view. + +```cpp +static constexpr T* end() noexcept +``` + +### Return value + +`nullptr`. + +## `front` + +Results in undefined behavior. + +```cpp +constexpr auto front() + requires ranges::forward_range; +constexpr auto front() const + requires ranges::forward_range; +``` + +### Parameters + +None. + +### Return value + +None. + +### Remarks + +Calling this function in a debug build raises an assertion that the function has been called on an empty `view_interface`. + +## `operator[]` + +Results in undefined behavior. + +```cpp +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos); + +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos) const; +``` + +### Parameters + +*`pos`*\ +The position, relative to the beginning iterator, of the element to return. + +### Return value + +None. + +### Remarks + +Calling this function in a debug build raises an assertion that index is out of range for `view_interface`. + +## `operator bool` + +Test whether the derived view isn't empty. + +```cpp +constexpr explicit operator bool() +requires requires { ranges::empty(T ()); }; + +constexpr explicit operator bool() const +requires requires { ranges::empty(T ()); }; +``` + +### Parameters + +None. + +### Return value + +Returns `false`. + +### Example `(bool)` + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + auto anEmptyView = std::views::empty; + + if (anEmptyView) // check if anEmptyView isn't empty + { + std::cout << "Error: why does an empty_view have elements?\n"; + } + else + { + std::cout << "Correct: an empty_view is not not empty\n"; + } +} +``` + +```output +Correct: an empty_view is not not empty +``` + +## `size` + +Get the number of elements in the view, which will always be 0. + +```cpp +static constexpr size_t size() +``` + +### Parameters + +None. + +### Return value + +`0`. + +## See also + +[``](ranges.md)\ +[`empty` range adaptor](range-adaptors.md#common)\ +[`single_view`](single-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/error-category-class.md b/docs/standard-library/error-category-class.md index 953f7753f93..0eabf941a98 100644 --- a/docs/standard-library/error-category-class.md +++ b/docs/standard-library/error-category-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: error_category Class" title: "error_category Class" +description: "Learn more about: error_category Class" ms.date: 06/15/2022 f1_keywords: ["system_error/std::error_category", "system_error/std::error_category::value_type", "system_error/std::error_category::default_error_condition", "system_error/std::error_category::equivalent", "system_error/std::error_category::message", "system_error/std::error_category::name"] helpviewer_keywords: ["std::error_category", "std::error_category::value_type", "std::error_category::default_error_condition", "std::error_category::equivalent", "std::error_category::message", "std::error_category::name"] -ms.assetid: e0a71e14-852d-4905-acd6-5f8ed426706d ms.custom: devdivchpfy22 --- @@ -71,8 +70,6 @@ The error code value to store in the [error_condition](../standard-library/error Returns `error_condition(_Errval, *this)`. -### Remarks - ### equivalent Returns a value that specifies whether error objects are equivalent. @@ -129,8 +126,6 @@ The error code value to describe. Returns a descriptive name of the error code *val* for the category. If the error code is unrecognized, returns `"unknown error"`. -#### Remarks - ### name Returns the name of the category. diff --git a/docs/standard-library/error-code-class.md b/docs/standard-library/error-code-class.md index 9026b35dca2..f7cc93b6fb3 100644 --- a/docs/standard-library/error-code-class.md +++ b/docs/standard-library/error-code-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: error_code Class" title: "error_code Class" -ms.date: "11/04/2016" +description: "Learn more about: error_code Class" +ms.date: 11/04/2016 f1_keywords: ["system_error/std::error_code", "system_error/std::error_code::value_type", "system_error/std::error_code::assign", "system_error/std::error_code::category", "system_error/std::error_code::clear", "system_error/std::error_code::default_error_condition", "system_error/std::error_code::message", "system_error/std::error_code::operator bool"] helpviewer_keywords: ["std::error_code", "std::error_code::value_type", "std::error_code::assign", "std::error_code::category", "std::error_code::clear", "std::error_code::default_error_condition", "std::error_code::message"] -ms.assetid: c09b4a96-cb14-4281-a319-63543f9b2b4a --- # error_code Class @@ -82,8 +81,6 @@ Returns the error category. const error_category& category() const; ``` -#### Remarks - ### clear Clears the error code value and category. diff --git a/docs/standard-library/error-condition-class.md b/docs/standard-library/error-condition-class.md index 71767a0471c..ffa0030a441 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 @@ -85,8 +84,6 @@ const error_category& category() const; A reference to the stored error category -#### Remarks - ### clear Clears the error code value and category. @@ -160,7 +157,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 @@ -265,8 +262,6 @@ value_type value() const; The stored error code value of type [value_type](#value_type). -#### Remarks - ### value_type A type that represents the stored error code value. diff --git a/docs/standard-library/exception-typedefs.md b/docs/standard-library/exception-typedefs.md index 2385a803553..f25b44b6dde 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 28b59cda444..ced783fe124 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 ebb53bbfff0..6f9b2251cec 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 +description: "Learn more about: file_clock class" +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,12 +12,12 @@ 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 -In the Microsoft implementation, the epoch, or the time from which the `file_clock` starts measuring time, is 1/1/1601 00:00:00. +In the Microsoft implementation, the epoch, or the time from which the `file_clock` starts measuring time, is 1/1/1601 00:00:00. The ISO C++ Standard provides a choice between providing `to_sys()` and `from_sys()`, or `to_utc()` and `from_utc()`. The Microsoft implementation chose [to_utc](#to_utc) and [from_utc](#from_utc). diff --git a/docs/standard-library/file-status-class.md b/docs/standard-library/file-status-class.md index 1dbed5fb4bb..02d399d3cd9 100644 --- a/docs/standard-library/file-status-class.md +++ b/docs/standard-library/file-status-class.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: file_status Class" title: "file_status Class" -ms.date: "09/10/2018" +description: "Learn more about: file_status Class" +ms.date: 09/10/2018 f1_keywords: ["filesystem/std::experimental::filesystem::file_status", "filesystem/std::experimental::filesystem::file_status::operator=", "filesystem/std::experimental::filesystem::file_status::type", "filesystem/std::experimental::filesystem::file_status::permissions"] -ms.assetid: 9781840e-ad22-44dd-ad79-0fabaa94bac4 helpviewer_keywords: ["std::experimental::filesystem::file_status", "std::experimental::filesystem::file_status::operator=", "std::experimental::filesystem::file_status::type", "std::experimental::filesystem::file_status::permissions"] --- # file_status Class @@ -74,7 +73,7 @@ The defaulted member assignment operators behave as expected. ```cpp file_status& operator=(const file_status&) noexcept = default; -file_status& operator=(file_status&&) nexcept = default; +file_status& operator=(file_status&&) noexcept = default; ``` ### Parameters diff --git a/docs/standard-library/filesystem-functions.md b/docs/standard-library/filesystem-functions.md index eef418109a7..2c642f3180a 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 new file mode 100644 index 00000000000..2e36ae8a983 --- /dev/null +++ b/docs/standard-library/filter-view-class.md @@ -0,0 +1,219 @@ +--- +title: "filter_view class (C++ Standard Library)" +description: "API reference for the Standard Template Library (STL) filter_view class, which is a view that filters out elements of a range that don't match a predicate." +ms.date: 09/27/2022 +f1_keywords: ["ranges/std::filter_view", "ranges/std::filter_view::base", "ranges/std::filter_view::begin", "ranges/std::filter_view::empty", "ranges/std::filter_view::end", "ranges/std::filter_view::operator bool", "ranges/std::filter_view::pred", "ranges/std::filter_view::back", "ranges/std::filter_view::front"] +helpviewer_keywords: ["std::ranges::filter_view [C++]", "std::ranges::filter_view::base [C++]", "std::ranges::filter_view::begin [C++]", "std::ranges::filter_view::empty [C++]", "std::ranges::filter_view::end [C++]", "std::ranges::filter_view::pred [C++]", "std::ranges::filter_view::back [C++]", "std::ranges::filter_view::front [C++]", "std::ranges::filter_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `filter_view` class (C++ Standard Library) + +A view that filters out the elements of a range that don't match the predicate. + +## Syntax + +```cpp +template> Pred> + requires view && is_object_v +class filter_view : public view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying range. + +*`Pred`*\ +The type of the predicate that determines which elements to keep. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::filter`](range-adaptors.md#filter) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | `input_range`, [`forward_range`](range-concepts.md#forward_range), or [`bidirectional_range`](range-concepts.md#bidirectional_range) depending on the underlying range | +| **Sized** | No | +| **Is `const`-iterable** | No | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`pred`](#pred)C++20| Get a reference to the predicate that determines which elements to drop. | +| **Inherited from [view_interface](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `filter_view` + +```cpp +1) constexpr filter_view(V base, P pred); +2) filter_view() requires default_initializable && default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`pred`*\ +The predicate that determines which elements to keep from the underlying view. + +For information about the template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `filter_view` instance. + +### Remarks + +The best way to create a `filter_view` is by using the [`views::filter`](range-adaptors.md#filter) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create a value-initialized `filter_view`. The predicate and the underlying view must be default-initializable.\ +2\) Move constructs the `filter_view` from a *`base`* view and a *`pred`* predicate. Both *`base`* and *`pred`* are moved via `std::move()`. + +### Example: `filter_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto v) +{ + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{0, 1, -2, 3, -4, -5, 6}; + auto myView = std::views::filter(v, [](int i) {return i > 0; }); + print(myView); // outputs 1 3 6 + + auto myView2 = v | std::views::filter([](int i) {return i < 3; }); + print(myView2); // outputs 0 1 -2 -4 -5 +} +``` + +```output +1 3 6 +0 1 -2 -4 -5 +``` + +## `base` + +Gets the underlying range. + +```cpp +// Uses a copy constructor to return the underlying range +constexpr V base() const& requires std::copy_constructible; + +// Uses std::move() to return the underlying range +constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end() +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `pred` + +Get a reference to the predicate that determines which leading elements to drop. + +```cpp +constexpr const Pred& pred() const; +``` + +### Return value + + A reference to the predicate. + +### Remarks + +If the class doesn't store a predicate, the behavior is undefined. + +### Example `pred` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto mv = v | std::views::filter( + [](int i) {return i < 5; }); // keep the elements < 5 + + std::cout << std::boolalpha << mv.pred()(v[6]); // outputs "false" because v[6] = 6 and 6 is not less than 5 (the predicate) +} +``` + +## See also + +[``](ranges.md)\ +[`filter` range adaptor](range-adaptors.md#filter)\ +[`drop_while()`](range-adaptors.md#drop_while)\ +[`take_while()`](range-adaptors.md#take_while)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/forward-list-class.md b/docs/standard-library/forward-list-class.md index 67b197ffe76..65e5db60422 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. @@ -168,9 +168,7 @@ iterator before_begin(); A forward iterator that points just before the first element of the sequence (or just before the end of an empty sequence). -### Remarks - -## begin +## `begin` Returns an iterator addressing the first element in a forward list. @@ -183,9 +181,7 @@ iterator begin(); A forward iterator that points at the first element of the sequence (or just beyond the end of an empty sequence). -### Remarks - -## cbefore_begin +## `cbefore_begin` Returns a const iterator addressing the position before the first element in a forward list. @@ -197,9 +193,7 @@ const_iterator cbefore_begin() const; A forward iterator that points just before the first element of the sequence (or just before the end of an empty sequence). -### Remarks - -## cbegin +## `cbegin` Returns a **`const`** iterator that addresses the first element in the range. @@ -215,7 +209,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 +218,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 +234,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 +246,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 +256,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 +270,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. @@ -285,9 +279,7 @@ typedef typename Allocator::const_pointer const_pointer; ``` -### Remarks - -## const_reference +## `const_reference` A type that provides a constant reference to an element in the forward list. @@ -295,9 +287,7 @@ A type that provides a constant reference to an element in the forward list. 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 +299,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 +310,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 +322,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 +335,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 +356,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 +369,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 +380,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 +403,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 +426,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 +463,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 +476,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 +486,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 +503,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 +527,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 +543,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 +555,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. @@ -577,9 +567,7 @@ size_type max_size() const; 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 +579,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 +591,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 +607,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 +629,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 +643,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 +654,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 +669,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 +679,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 +688,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 +699,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 +719,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 +737,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 +749,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 +761,7 @@ void sort(Predicate pred); ### Parameters -*pred*\ +*`pred`*\ The ordering predicate. ### Remarks @@ -782,11 +770,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 +801,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 +901,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 +911,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 +930,7 @@ void unique(BinaryPredicate comp); ### Parameters -*comp*\ +*`comp`*\ The binary predicate used to compare successive elements. ### Remarks @@ -955,7 +943,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 333f3280e64..f221e375767 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/forward-list.md b/docs/standard-library/forward-list.md index c7400192b6a..3a614d21840 100644 --- a/docs/standard-library/forward-list.md +++ b/docs/standard-library/forward-list.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: [""] -ms.assetid: 8b4ab09e-1475-434a-b4e0-fdbc07a08b5b --- # `` @@ -30,7 +29,7 @@ Defines the container class template forward_list and several supporting templat |[operator<](../standard-library/forward-list-operators.md#op_lt)|Tests if the forward list object on the left side of the operator is less than the forward list object on the right side.| |[operator<=](../standard-library/forward-list-operators.md#op_lt_eq)|Tests if the forward list object on the left side of the operator is less than or equal to the forward list object on the right side.| |[operator>](../standard-library/forward-list-operators.md#op_gt)|Tests if the forward list object on the left side of the operator is greater than the forward list object on the right side.| -|[operator>=](../standard-library/forward-list-operators.md#op_lt_eq)|Tests if the forward list object on the left side of the operator is greater than or equal to the forward list object on the right side.| +|[operator>=](../standard-library/forward-list-operators.md#op_gt_eq)|Tests if the forward list object on the left side of the operator is greater than or equal to the forward list object on the right side.| ### Functions diff --git a/docs/standard-library/freelist-class.md b/docs/standard-library/freelist-class.md index 743dececd8a..2d3d4286e5e 100644 --- a/docs/standard-library/freelist-class.md +++ b/docs/standard-library/freelist-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: freelist Class" title: "freelist Class" -ms.date: "11/04/2016" +description: "Learn more about: freelist Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::freelist", "allocators/stdext::freelist::pop", "allocators/stdext::freelist::push"] helpviewer_keywords: ["stdext::freelist", "stdext::freelist [C++], pop", "stdext::freelist [C++], push"] -ms.assetid: 8ad7e35c-4c80-4479-8ede-1a2497b06d71 --- # freelist Class @@ -56,8 +55,6 @@ Constructs an object of type `freelist`. freelist(); ``` -### Remarks - ## freelist::pop Removes the first memory block from the free list. diff --git a/docs/standard-library/front-insert-iterator-class.md b/docs/standard-library/front-insert-iterator-class.md index 3ca56a1eb32..9a5859e8455 100644 --- a/docs/standard-library/front-insert-iterator-class.md +++ b/docs/standard-library/front-insert-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: front_insert_iterator Class" title: "front_insert_iterator Class" +description: "Learn more about: front_insert_iterator Class" ms.date: 06/15/2022 f1_keywords: ["iterator/std::front_insert_iterator", "iterator/std::front_insert_iterator::container_type", "iterator/std::front_insert_iterator::reference"] helpviewer_keywords: ["std::front_insert_iterator [C++]", "std::front_insert_iterator [C++], container_type", "std::front_insert_iterator [C++], reference"] -ms.assetid: a9a9c075-136a-4419-928b-c4871afa033c ms.custom: devdivchpfy22 --- @@ -254,11 +253,11 @@ int main( ) list L1; front_insert_iterator > iter ( L1 ); -*iter = 10; + *iter = 10; iter++; -*iter = 20; + *iter = 20; iter++; -*iter = 30; + *iter = 30; iter++; list ::iterator vIter; @@ -316,11 +315,11 @@ int main( ) list L1; front_insert_iterator > iter ( L1 ); -*iter = 10; + *iter = 10; iter++; -*iter = 20; + *iter = 20; iter++; -*iter = 30; + *iter = 30; iter++; list ::iterator vIter; diff --git a/docs/standard-library/fstream-typedefs.md b/docs/standard-library/fstream-typedefs.md index 0676590e457..4006ded8a5e 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 7a26df53f2e..3bb04096594 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/function-objects-in-the-stl.md b/docs/standard-library/function-objects-in-the-stl.md index e1055bf6f6d..4289ec032ea 100644 --- a/docs/standard-library/function-objects-in-the-stl.md +++ b/docs/standard-library/function-objects-in-the-stl.md @@ -1,25 +1,24 @@ --- -description: "Learn more about: Function Objects in the C++ Standard Library" title: "Function Objects in the C++ Standard Library" -ms.date: "03/15/2019" +description: "Learn more about: Function Objects in the C++ Standard Library" +ms.date: 06/22/2025 helpviewer_keywords: ["functors", "C++ Standard Library, functors", "C++ Standard Library, function objects", "function objects"] -ms.assetid: 85f8a735-2c7b-4f10-9c4d-95c666ec4192 --- # Function Objects in the C++ Standard Library -A *function object*, or *functor*, is any type that implements operator(). This operator is referred to as the *call operator* or sometimes the *application operator*. The C++ Standard Library uses function objects primarily as sorting criteria for containers and in algorithms. +A *function object*, or *functor*, is any type that implements `operator()`. This operator is referred to as the *call operator* or sometimes the *application operator*. The C++ Standard Library uses function objects primarily as sorting criteria for containers and in algorithms. -Function objects provide two main advantages over a straight function call. The first is that a function object can contain state. The second is that a function object is a type and therefore can be used as a template parameter. +Function objects provide two main advantages over a regular function call. The first is that a function object can contain state. The second is that a function object is a type and therefore can be used as a template parameter. ## Creating a Function Object -To create a function object, create a type and implement operator(), such as: +To create a function object, create a type and implement `operator()`, such as: ```cpp -class Functor +class LessThanFunctor { public: - int operator()(int a, int b) + bool operator()(int a, int b) { return a < b; } @@ -27,42 +26,42 @@ public: int main() { - Functor f; + LessThanFunctor less_than; int a = 5; int b = 7; - int ans = f(a, b); + bool ans = less_than(a, b); } ``` -The last line of the `main` function shows how you call the function object. This call looks like a call to a function, but it's actually calling operator() of the Functor type. This similarity between calling a function object and a function is how the term function object came about. +The last line of the `main` function shows how you call the function object. This call looks like a call to a function, but it's actually calling `operator()` of the `LessThanFunctor` type. This similarity between calling a function object and a function is how the term function object came about. ## Function Objects and Containers -The C++ Standard Library contains several function objects in the [``](../standard-library/functional.md) header file. One use of these function objects is as a sorting criterion for containers. For example, the `set` container is declared as follows: +The C++ Standard Library contains several function objects in the [``](functional.md) header file. One use of these function objects is as a sorting criterion for containers. For example, the [`set`](set-class.md) container is declared as follows: ```cpp template , - class Allocator=allocator> -class set + class Compare = std::less, + class Allocator = std::allocator> +class set; ``` -The second template argument is the function object `less`. This function object returns **`true`** if the first parameter is less than the second parameter. Since some containers sort their elements, the container needs a way of comparing two elements. The comparison is done by using the function object. You can define your own sorting criteria for containers by creating a function object and specifying it in the template list for the container. +The second template argument is the function object [`less`](less-struct.md). This function object returns **`true`** if the first parameter is less than the second parameter. Since some containers sort their elements, the container needs a way of comparing two elements. The comparison is done by using the function object. You can define your own sorting criteria for containers by creating a function object and specifying it in the template list for the container. ## Function Objects and Algorithms -Another use of functional objects is in algorithms. For example, the `remove_if` algorithm is declared as follows: +Another use of function objects is in algorithms. For example, the [`remove_if`](algorithm-functions.md#remove_if) algorithm is declared as follows: ```cpp -template +template ForwardIterator remove_if( ForwardIterator first, ForwardIterator last, - Predicate pred); + UnaryPredicate pred); ``` -The last argument to `remove_if` is a function object that returns a boolean value (a *predicate*). If the result of the function object is **`true`**, then the element is removed from the container being accessed by the iterators `first` and `last`. You can use any of the function objects declared in the [``](../standard-library/functional.md) header for the argument `pred` or you can create your own. +The last argument to `remove_if` is a function object that returns a boolean value (a *predicate*). If the result of the function object is **`true`**, then the element is shifted such that it's beyond the new end returned by `remove_if`. You can use any of the function objects declared in the [``](functional.md) header for the argument `pred` or you can create your own. ## See also -[C++ Standard Library Reference](../standard-library/cpp-standard-library-reference.md) +[C++ Standard Library Reference](cpp-standard-library-reference.md) diff --git a/docs/standard-library/functional.md b/docs/standard-library/functional.md index c1ac8dd5bcd..6a8aa9bfbcc 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 087f8291808..565311c0645 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 c40c313f2d6..24e91bd0bff 100644 --- a/docs/standard-library/future-functions.md +++ b/docs/standard-library/future-functions.md @@ -1,17 +1,13 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "08/17/2021" +description: "Learn more about: functions" +ms.date: 09/11/2024 f1_keywords: ["future/std::async", "future/std::future_category", "future/std::make_error_code", "future/std::make_error_condition", "future/std::swap"] helpviewer_keywords: ["std::async [C++]", "std::future_category [C++]", "std::make_error_code [C++]", "std::make_error_condition [C++]", "std::swap [C++]"] --- # `` functions -[`async`](#async)\ -[`future_category`](#future_category)\ -[`make_error_code`](#make_error_code)\ -[`make_error_condition`](#make_error_condition)\ -[`swap`](#swap)| +The `` header provides the following functions: ## `async` @@ -29,7 +25,7 @@ future::type> ### Parameters -*policy*\ +*`policy`*\ A [`launch`](../standard-library/future-enums.md#launch) value. ### Remarks @@ -48,24 +44,28 @@ The second function returns a `future` object whose *associated asynchronous Unless `decay::type` is a type other than launch, the second function doesn't participate in overload resolution. -The C++ standard states that if policy is launch::async, the function creates a new thread. However the Microsoft implementation is currently non-conforming. It obtains its threads from the Windows ThreadPool, which in some cases may provide a recycled thread rather than a new one. This means that the `launch::async` policy is implemented as `launch::async|launch::deferred`. Another implication of the ThreadPool-based implementation is that there's no guarantee that thread-local variables will be destroyed when the thread completes. If the thread is recycled and provided to a new call to `async`, the old variables will still exist. We recommend that you don't use thread-local variables with `async`. +The C++ standard states that if the policy is `launch::async`, the function behaves as if it invokes the callable object in a new thread. This means that while it typically results in creating a new thread, the implementation may use other mechanisms to achieve equivalent behavior. However, the Microsoft implementation currently doesn't conform strictly to this behavior. It obtains threads from the Windows ThreadPool, which may provide a recycled thread rather than a new one. This means that the `launch::async` policy is effectively implemented as `launch::async|launch::deferred`. Another implication of the ThreadPool-based implementation is that there's no guarantee that thread-local variables are destroyed when the thread completes. If the thread is recycled and provided to a new call to `async`, the old variables still exist. We recommend that you avoid using thread-local variables with `async`. -If *policy* is `launch::deferred`, the function marks its associated asynchronous state as holding a *deferred function* and returns. The first call to any non-timed function that waits for the associated asynchronous state to be ready in effect calls the deferred function by evaluating `INVOKE(dfn, dargs..., Ty)`. +If *`policy`* is `launch::deferred`, the function marks its associated asynchronous state as holding a *deferred function* and returns. The first call to any nontimed function that waits for the associated asynchronous state to be ready in effect calls the deferred function by evaluating `INVOKE(dfn, dargs..., Ty)`. -In all cases, the associated asynchronous state of the `future` object isn't set to *ready* until the evaluation of `INVOKE(dfn, dargs..., Ty)` completes, either by throwing an exception or by returning normally. The result of the associated asynchronous state is an exception if one was thrown, or any value that's returned by the evaluation. +In all cases, the associated asynchronous state of the `future` object isn't set to *ready* until the evaluation of `INVOKE(dfn, dargs..., Ty)` completes, either by throwing an exception or by returning normally. The result of the associated asynchronous state is an exception if one was thrown, or the value the evaluation returns. > [!NOTE] > For a `future`—or the last [`shared_future`](../standard-library/shared-future-class.md)—that's attached to a task started with `std::async`, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call `.get()` or `.wait()` and the task is still running. If a `future` obtained from `std::async` is moved outside the local scope, other code that uses it must be aware that its destructor may block for the shared state to become ready. The pseudo-function `INVOKE` is defined in [``](../standard-library/functional.md). -### Microsoft Specific +**Microsoft specific** + +When the passed function is executed asynchronously, it executes on the Windows Thread Pool. For more information, see [Thread Pools](/windows/win32/procthread/thread-pools). The number of concurrent threads is limited to the thread pool default, which is 500 threads. + +Before Windows 11 and Windows Server 2022, applications were limited by default to a single processor group having at most 64 logical processors. This limited the number of concurrently executing threads to 64. For more information, see [Processor Groups](/windows/win32/procthread/processor-groups). -When the passed function is executed asynchronously, it's executed on Windows Thread Pool; see [Thread Pools](/windows/win32/procthread/thread-pools). The number of concurrent threads is limited to the thread pool default (currently 500). The number of threads concurrently executing on hardware is currently limited by the number of logical processor in the process's processor group, so it's effectively limited to 64; see [Processor Groups](/windows/win32/procthread/processor-groups). +Starting with Windows 11 and Windows Server 2022, processes and their threads have processor affinities that by default span all processors in the system and across multiple groups on machines with more than 64 processors. The limit on the number of concurrent threads is now the total number of logical processors in the system. ## `future_category` -Returns a reference to the [error_category](../standard-library/error-category-class.md) object that characterizes errors that are associated with `future` objects. +Returns a reference to the [`error_category`](../standard-library/error-category-class.md) object that characterizes errors that are associated with `future` objects. ```cpp const error_category& future_category() noexcept; @@ -82,7 +82,7 @@ inline error_code make_error_code(future_errc Errno) noexcept; ### Parameters *`Errno`*\ -A [future_errc](../standard-library/future-enums.md#future_errc) value that identifies the reported error. +A [`future_errc`](../standard-library/future-enums.md#future_errc) value that identifies the reported error. ### Return Value @@ -90,7 +90,7 @@ A [future_errc](../standard-library/future-enums.md#future_errc) value that iden ## `make_error_condition` -Creates an [error_condition](../standard-library/error-condition-class.md) together with the [error_category](../standard-library/error-category-class.md) object that characterizes [future](../standard-library/future-class.md) errors. +Creates an [`error_condition`](../standard-library/error-condition-class.md) together with the [`error_category`](../standard-library/error-category-class.md) object that characterizes [`future`](../standard-library/future-class.md) errors. ```cpp inline error_condition make_error_condition(future_errc Errno) noexcept; @@ -99,7 +99,7 @@ inline error_condition make_error_condition(future_errc Errno) noexcept; ### Parameters *`Errno`*\ -A [future_errc](../standard-library/future-enums.md#future_errc) value that identifies the reported error. +A [`future_errc`](../standard-library/future-enums.md#future_errc) value that identifies the reported error. ### Return Value diff --git a/docs/standard-library/future.md b/docs/standard-library/future.md index 5eccafbbeaa..80e8f7c7904 100644 --- a/docs/standard-library/future.md +++ b/docs/standard-library/future.md @@ -34,7 +34,7 @@ The template function `async` and the class templates `promise` and `packaged_ta Each of the class templates `promise`, `future`, and `shared_future` has a specialization for the type **`void`** and a partial specialization for storing and retrieving a value by reference. These specializations differ from the primary template only in the signatures and semantics of the functions that store and retrieve the returned value. -The class templates `future` and `shared_future` never block in their destructors, except in one case that's preserved for backward compatibility: Unlike all other futures, for a `future`—or the last `shared_future`—that's attached to a task started with `std::async`, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call `.get()` or `.wait()` and the task is still running. The following usability note has been added to the description of `std::async` in the draft standard: "[Note: If a future obtained from std::async is moved outside the local scope, other code that uses the future must be aware that the future’s destructor may block for the shared state to become ready.—end note]" In all other cases, `future` and `shared_future` destructors are required and are guaranteed to never block. +The class templates `future` and `shared_future` never block in their destructors, except in one case that's preserved for backward compatibility: Unlike all other futures, for a `future`—or the last `shared_future`—that's attached to a task started with `std::async`, the destructor blocks if the task has not completed; that is, it blocks if this thread did not yet call `.get()` or `.wait()` and the task is still running. The following usability note has been added to the description of `std::async` in the draft standard: "[Note: If a future obtained from std::async is moved outside the local scope, other code that uses the future must be aware that the future's destructor may block for the shared state to become ready.—end note]" In all other cases, `future` and `shared_future` destructors are required and are guaranteed to never block. ## Members diff --git a/docs/standard-library/greater-equal-struct.md b/docs/standard-library/greater-equal-struct.md index cf301ae814c..dd3921c8768 100644 --- a/docs/standard-library/greater-equal-struct.md +++ b/docs/standard-library/greater-equal-struct.md @@ -24,7 +24,7 @@ template <> struct greater_equal { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left)>= std::forward(Right)); }; ``` diff --git a/docs/standard-library/gslice-array-class.md b/docs/standard-library/gslice-array-class.md index 727afddc3f6..22e90f11d0b 100644 --- a/docs/standard-library/gslice-array-class.md +++ b/docs/standard-library/gslice-array-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: gslice_array class" title: "gslice_array class" +description: "Learn more about: gslice_array class" ms.date: 01/12/2022 f1_keywords: ["valarray/std::gslice_array"] helpviewer_keywords: ["gslice_array class"] -ms.assetid: ad1b4514-b14a-4baf-a293-d5a8e8674c75 --- # `gslice_array` class @@ -42,7 +41,7 @@ public: void operator>>=(const valarray& x) const; // The rest is private or implementation defined -} +}; ``` ## Remarks diff --git a/docs/standard-library/hash-compare-class.md b/docs/standard-library/hash-compare-class.md index 35008b665d2..dde3f260d68 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 00d1c506db3..e7f121e5543 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,11 +58,11 @@ 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. -The actual order of elements in the controlled sequence depends on the hash function, the ordering function, and the current size of the hash table stored in the container object. You can’t determine the current size of the hash table, so you can’t in general predict the order of elements in the controlled sequence. Inserting elements invalidates no iterators, and removing elements invalidates only those iterators that had specifically pointed at the removed elements. +The actual order of elements in the controlled sequence depends on the hash function, the ordering function, and the current size of the hash table stored in the container object. You can't determine the current size of the hash table, so you can't in general predict the order of elements in the controlled sequence. Inserting elements invalidates no iterators, and removing elements invalidates only those iterators that had specifically pointed at the removed elements. The iterator provided by the `hash_map` class is a bidirectional iterator, but the class member functions [`insert`](#insert) and [`hash_map`](#hash_map) have versions that take as template parameters a weaker input iterator, whose functionality requirements are more minimal than those guaranteed by the class of bidirectional iterators. The different iterator concepts form a family related by refinements in their functionality. Each iterator concept has its own set of requirements, and the algorithms that work with them must limit their assumptions to the requirements provided by that type of iterator. It may be assumed that an input iterator may be dereferenced to refer to some object and that it may be incremented to the next iterator in the sequence. This is a minimal set of functionality, but it's enough to be able to talk meaningfully about a range of iterators `[First, Last)` in the context of the class member functions. @@ -371,8 +371,6 @@ Erases all the elements of a `hash_map`. void clear(); ``` -### Remarks - ### Example The following example demonstrates the use of the `hash_map::clear` member function. @@ -423,7 +421,7 @@ typedef list::cons ### Remarks -A type `const_iterator` can’t be used to modify the value of an element. +A type `const_iterator` can't be used to modify the value of an element. The `const_iterator` defined by `hash_map` points to elements that are objects of [`value_type`](#value_type), that is of type `pair< const Key, Type >`, whose first member is the key to the element and whose second member is the mapped datum held by the element. @@ -448,7 +446,7 @@ typedef list::co ### Remarks -A type `const_pointer` can’t be used to modify the value of an element. +A type `const_pointer` can't be used to modify the value of an element. In most cases, an [`iterator`](#iterator) should be used to access the elements in a `hash_map` object. @@ -463,8 +461,6 @@ A type that provides a reference to a **`const`** element stored in a `hash_map` typedef list::const_reference const_reference; ``` -### Remarks - ### Example ```cpp @@ -516,12 +512,12 @@ 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 -A type `const_reverse_iterator` can’t modify the value of an element and is used to iterate through the `hash_map` in reverse. +A type `const_reverse_iterator` can't modify the value of an element and is used to iterate through the `hash_map` in reverse. The `const_reverse_iterator` defined by `hash_map` points to elements that are objects of [`value_type`](#value_type), that is of type `pair< const Key, Type >`, whose first member is the key to the element and whose second member is the mapped datum held by the element. @@ -625,7 +621,7 @@ A `const` reverse bidirectional iterator addressing the first element in a rever `crbegin` is used with a reversed `hash_map` just as [`begin`](#begin) is used with a `hash_map`. -With the return value of `crbegin`, the `hash_map` object can’t be modified. +With the return value of `crbegin`, the `hash_map` object can't be modified. `crbegin` can be used to iterate through a `hash_map` backwards. @@ -677,7 +673,7 @@ A `const` reverse bidirectional iterator that addresses the location succeeding `crend` is used with a reversed `hash_map` just as [`hash_map::end`](#end) is used with a `hash_map`. -With the return value of `crend`, the `hash_map` object can’t be modified. +With the return value of `crend`, the `hash_map` object can't be modified. `crend` can be used to test to whether a reverse iterator has reached the end of its `hash_map`. @@ -817,8 +813,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 +874,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() @@ -917,8 +913,6 @@ bool empty() const; **`true`** if the `hash_map` is empty; **`false`** if the `hash_map` is nonempty. -### Remarks - ### Example ```cpp @@ -1048,8 +1042,6 @@ A pair of iterators such that the first is the [`lower_bound`](#lower_bound) of 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 - ### Example ```cpp @@ -1261,7 +1253,7 @@ An iterator that addresses the location of an element with a specified key, or t `find` returns an iterator that addresses an element in the `hash_map` whose sort key is equivalent to the argument key under a binary predicate that induces an ordering based on a less than comparability relation. -If the return value of `find` is assigned to a [`const_iterator`](#const_iterator), the `hash_map` object can’t be modified. If the return value of `find` is assigned to an [`iterator`](#iterator), the `hash_map` object can be modified +If the return value of `find` is assigned to a [`const_iterator`](#const_iterator), the `hash_map` object can't be modified. If the return value of `find` is assigned to an [`iterator`](#iterator), the `hash_map` object can be modified ### Example @@ -1526,7 +1518,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 +1537,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() @@ -1813,9 +1805,7 @@ The argument key value to be compared with the sort key of an element from the ` An [`iterator`](#iterator) or [`const_iterator`](#const_iterator) that addresses the location of an element in a `hash_map` that with a key that is equal to or greater than the argument key, or that addresses the location succeeding the last element in the `hash_map` if no match is found for the key. -If the return value of `lower_bound` is assigned to a `const_iterator`, the `hash_map` object can’t be modified. If the return value of `lower_bound` is assigned to a `iterator`, the `hash_map` object can be modified. - -### Remarks +If the return value of `lower_bound` is assigned to a `const_iterator`, the `hash_map` object can't be modified. If the return value of `lower_bound` is assigned to a `iterator`, the `hash_map` object can be modified. ### Example @@ -1904,8 +1894,6 @@ size_type max_size() const; The maximum possible length of the `hash_map`. -### Remarks - ### Example ```cpp @@ -2122,7 +2110,7 @@ A reverse bidirectional iterator addressing the first element in a reversed `has `rbegin` is used with a reversed `hash_map` just as [`begin`](#begin) is used with a `hash_map`. -If the return value of `rbegin` is assigned to a [`const_reverse_iterator`](#const_reverse_iterator), then the `hash_map` object can’t be modified. If the return value of `rbegin` is assigned to a [`reverse_iterator`](#reverse_iterator), then the `hash_map` object can be modified. +If the return value of `rbegin` is assigned to a [`const_reverse_iterator`](#const_reverse_iterator), then the `hash_map` object can't be modified. If the return value of `rbegin` is assigned to a [`reverse_iterator`](#reverse_iterator), then the `hash_map` object can be modified. `rbegin` can be used to iterate through a `hash_map` backwards. @@ -2196,8 +2184,6 @@ A type that provides a reference to an element stored in a `hash_map`. typedef list::reference reference; ``` -### Remarks - ### Example ```cpp @@ -2269,7 +2255,7 @@ A reverse bidirectional iterator that addresses the location succeeding the last `rend` is used with a reversed `hash_map` just as [`end`](#end) is used with a `hash_map`. -If the return value of `rend` is assigned to a [`const_reverse_iterator`](#const_reverse_iterator), then the `hash_map` object can’t be modified. If the return value of `rend` is assigned to a [`reverse_iterator`](#reverse_iterator), then the `hash_map` object can be modified. +If the return value of `rend` is assigned to a [`const_reverse_iterator`](#const_reverse_iterator), then the `hash_map` object can't be modified. If the return value of `rend` is assigned to a [`reverse_iterator`](#reverse_iterator), then the `hash_map` object can be modified. `rend` can be used to test to whether a reverse iterator has reached the end of its `hash_map`. @@ -2351,7 +2337,7 @@ typedef list::reve ### Remarks -A type `reverse_iterator` can’t modify the value of an element and is used to iterate through the `hash_map` in reverse. +A type `reverse_iterator` can't modify the value of an element and is used to iterate through the `hash_map` in reverse. The `reverse_iterator` defined by `hash_map` points to elements that are objects of [value_type](#value_type), that is of type `pair`, whose first member is the key to the element and whose second member is the mapped datum held by the element. @@ -2378,8 +2364,6 @@ size_type size() const; The current length of the `hash_map`. -### Remarks - ### Example The following example demonstrates the use of the `hash_map::size` member function. @@ -2424,8 +2408,6 @@ An unsigned integer type that can represent the number of elements in a `hash_ma typedef list::size_type size_type; ``` -### Remarks - ### Example See example for [`size`](#size) for an example of how to declare and use `size_type` @@ -2526,9 +2508,7 @@ The argument key value to be compared with the sort key value of an element from An [`iterator`](#iterator) or [`const_iterator`](#const_iterator) that addresses the location of an element in a `hash_map` that with a key that is greater than the argument key, or that addresses the location succeeding the last element in the `hash_map` if no match is found for the key. -If the return value is assigned to a `const_iterator`, the `hash_map` object can’t be modified. If the return value is assigned to an `iterator`, the `hash_map` object can be modified. - -### Remarks +If the return value is assigned to a `const_iterator`, the `hash_map` object can't be modified. If the return value is assigned to an `iterator`, the `hash_map` object can be modified. ### Example diff --git a/docs/standard-library/hash-map-functions.md b/docs/standard-library/hash-map-functions.md index 8cfca3016b1..023610dd7e4 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 4367ddecbe4..e3da8726961 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!= @@ -215,7 +211,7 @@ The hash_multimaps hm1 and hm2 are not equal. The hash_multimaps hm1 and hm3 are equal. ``` -## operator== (hash_multimap) +## operator== (hash_multimap) > [!NOTE] > This API is obsolete. The alternative is [unordered_multimap Class](unordered-multimap-class.md). diff --git a/docs/standard-library/hash-multimap-class.md b/docs/standard-library/hash-multimap-class.md index ca2f5e5b1f1..eaa3fad497d 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 @@ -327,8 +326,6 @@ Erases all the elements of a hash_multimap. void clear(); ``` -### Remarks - ### Example The following example demonstrates the use of the hash_multimap::clear member function. @@ -419,8 +416,6 @@ A type that provides a reference to a **`const`** element stored in a hash_multi typedef list::const_reference const_reference; ``` -### Remarks - ### Example ```cpp @@ -776,8 +771,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 +832,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() @@ -876,8 +871,6 @@ bool empty() const; **`true`** if the hash_multimap is empty; **`false`** if the hash_multimap is nonempty. -### Remarks - ### Example ```cpp @@ -1005,9 +998,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**). - -### Remarks +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 @@ -1686,8 +1677,6 @@ An [iterator](#iterator) or [const_iterator](#const_iterator) that addresses the If the return value of `lower_bound` is assigned to a `const_iterator`, the hash_multimap object cannot be modified. If the return value of `lower_bound` is assigned to an `iterator`, the hash_multimap object can be modified. -### Remarks - ### Example ```cpp @@ -1793,8 +1782,6 @@ size_type max_size() const; The maximum possible length of the hash_multimap. -### Remarks - ### Example ```cpp @@ -1989,8 +1976,6 @@ A type that provides a reference to an element stored in a hash_multimap. typedef list::reference reference; ``` -### Remarks - ### Example ```cpp @@ -2165,8 +2150,6 @@ size_type size() const; The current length of the hash_multimap. -### Remarks - ### Example The following example demonstrates the use of the hash_multimap::size member function. @@ -2211,8 +2194,6 @@ An unsigned integer type that counts the number of elements in a hash_multimap. typedef list::size_type size_type; ``` -### Remarks - ### Example See the example for [size](#size) for an example of how to declare and use `size_type` @@ -2313,8 +2294,6 @@ An [iterator](#iterator) or [const_iterator](#const_iterator) that addresses the If the return value of `upper_bound` is assigned to a `const_iterator`, the hash_multimap object cannot be modified. If the return value of `upper_bound` is assigned to a `iterator`, the hash_multimap object can be modified. -### Remarks - ### Example ```cpp diff --git a/docs/standard-library/hash-multiset-class.md b/docs/standard-library/hash-multiset-class.md index 4c18f9e9e58..8be4252e168 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 @@ -309,8 +308,6 @@ Erases all the elements of a hash_multiset. void clear(); ``` -### Remarks - ### Example ```cpp @@ -389,8 +386,6 @@ A type that provides a reference to a **`const`** element stored in a hash_multi typedef list::const_reference const_reference; ``` -### Remarks - ### Example ```cpp @@ -713,8 +708,6 @@ The value of an element to be inserted into the [hash_multiset](../standard-libr The `emplace` member function returns an iterator that points to the position where the new element was inserted. -### Remarks - ### Example ```cpp @@ -812,8 +805,6 @@ bool empty() const; **`true`** if the hash_multiset is empty; **`false`** if the hash_multiset is nonempty. -### Remarks - ### Example ```cpp @@ -931,7 +922,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 +1286,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); @@ -1592,8 +1583,6 @@ The argument key to be compared with the sort key of an element from the hash_mu An [iterator](#iterator) or [const_iterator](#const_iterator) that addresses the location of the first element in a hash_multiset with a key that is equal to or greater than the argument key, or that addresses the location succeeding the last element in the hash_multiset if no match is found for the key. -### Remarks - ### Example ```cpp @@ -1652,8 +1641,6 @@ size_type max_size() const; The maximum possible length of the hash_multiset. -### Remarks - ### Example ```cpp @@ -1846,8 +1833,6 @@ A type that provides a reference to an element stored in a hash_multiset. typedef list::reference reference; ``` -### Remarks - ### Example ```cpp @@ -2005,8 +1990,6 @@ size_type size() const; The current length of the hash_multiset. -### Remarks - ### Example ```cpp @@ -2048,8 +2031,6 @@ An unsigned integer type that can represent the number of elements in a hash_mul typedef list::size_type size_type; ``` -### Remarks - ### Example See example for [size](#size) for an example of how to declare and use `size_type` @@ -2150,8 +2131,6 @@ The argument key to be compared with the sort key of an element from the hash_mu An [iterator](#iterator) or [const_iterator](#const_iterator) that addresses the location of the first element in a hash_multiset with a key greater than the argument key, or that addresses the location succeeding the last element in the hash_multiset if no match is found for the key. -### Remarks - ### Example ```cpp diff --git a/docs/standard-library/hash-set-class.md b/docs/standard-library/hash-set-class.md index 703cd2f9c44..642b9a71996 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 @@ -317,8 +316,6 @@ Erases all the elements of a hash_set. void clear(); ``` -### Remarks - ### Example ```cpp @@ -397,8 +394,6 @@ A type that provides a reference to a **`const`** element stored in a hash_set f typedef list::const_reference const_reference; ``` -### Remarks - ### Example ```cpp @@ -721,8 +716,6 @@ The value of an element to be inserted into the [hash_set](../standard-library/h The `emplace` member function returns a pair whose **`bool`** component returns **`true`** if an insertion was make and **`false`** if the `hash_set` 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. -### Remarks - ### Example ```cpp @@ -820,8 +813,6 @@ bool empty() const; **`true`** if the hash_set is empty; **`false`** if the hash_set is nonempty. -### Remarks - ### Example ```cpp @@ -939,9 +930,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**). - -### Remarks +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 @@ -1355,7 +1344,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`. @@ -1584,8 +1573,6 @@ The argument key to be compared with the sort key of an element from the hash_se An `iterator` or `const_iterator` that addresses the location of an element in a hash_set that with a key that is equal to or greater than the argument key or that addresses the location succeeding the last element in the hash_set if no match is found for the key. -### Remarks - ### Example ```cpp @@ -1651,8 +1638,6 @@ size_type max_size() const; The maximum possible length of the hash_set. -### Remarks - ### Example ```cpp @@ -1845,8 +1830,6 @@ A type that provides a reference to an element stored in a hash_set. typedef list::reference reference; ``` -### Remarks - ### Example ```cpp @@ -2004,8 +1987,6 @@ size_type size() const; The current length of the hash_set. -### Remarks - ### Example ```cpp @@ -2047,8 +2028,6 @@ An unsigned integer type that can represent the number of elements in a hash_set typedef list::size_type size_type; ``` -### Remarks - ### Example See the example for [size](#size) for an example of how to declare and use `size_type` @@ -2149,8 +2128,6 @@ The argument key to be compared with the sort key of an element from the hash_se An `iterator` or `const_iterator` that addresses the location of an element in a hash_set that with a key that is equal to or greater than the argument key, or that addresses the location succeeding the last element in the hash_set if no match is found for the key. -### Remarks - ### Example ```cpp diff --git a/docs/standard-library/hash-set-functions.md b/docs/standard-library/hash-set-functions.md index 2dd96536c7b..43faa5b3061 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 dc6d86cb066..3ed14584a27 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-set.md b/docs/standard-library/hash-set.md index 9f11c054220..e0581915841 100644 --- a/docs/standard-library/hash-set.md +++ b/docs/standard-library/hash-set.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["hash_set header"] -ms.assetid: 6b556967-c808-4869-9b4d-f9e030864435 --- # `` @@ -19,8 +18,6 @@ Defines the container class templates hash_set and hash_multiset and their suppo #include ``` -## Remarks - ### Operators |Hash_set version|Hash_multiset version|Description| diff --git a/docs/standard-library/hash-structure-stl.md b/docs/standard-library/hash-structure-stl.md index 979d001806f..38eea051e4f 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 33a8873cd92..070d29c7327 100644 --- a/docs/standard-library/high-resolution-clock-struct.md +++ b/docs/standard-library/high-resolution-clock-struct.md @@ -1,15 +1,13 @@ --- +title: high_resolution_clock struct description: "Learn more about: high_resolution_clock struct" -title: "high_resolution_clock struct | Microsoft Docs" 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"] +f1_keywords: ["chrono/std::chrono::high_resolution_clock", "chrono/std::chrono::high_resolution_clock::now", "chrono/std::chrono::high_resolution_clock::is_steady constant"] helpviewer_keywords: ["std::chrono [C++], high_resolution_clock"] dev_langs: ["C++"] -author: "corob-msft" -ms.author: "corob" +author: "tylermsft" ms.workload: ["cplusplus"] --- # `high_resolution_clock` struct @@ -57,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/identity-structure.md b/docs/standard-library/identity-structure.md index bfb04dac3b2..252785219fc 100644 --- a/docs/standard-library/identity-structure.md +++ b/docs/standard-library/identity-structure.md @@ -1,31 +1,96 @@ --- description: "Learn more about: identity Structure" title: "identity Structure" -ms.date: "11/04/2016" +ms.date: 04/11/2026 f1_keywords: ["utility/std::identity"] helpviewer_keywords: ["identity class", "identity structure"] -ms.assetid: 990756fd-7969-4b39-ad7e-0878e8dac8fd +ai-usage: ai-assisted --- -# identity Structure +# `identity` Structure -A struct that provides a type definition as the template parameter. +`std::identity` (introduced in C++20) is a function object whose `operator()` returns its argument unchanged. -## Syntax +> [!NOTE] +> There's a Microsoft-specific `identity` structure from `` that is deprecated and isn't available in later versions of Visual Studio. For C++20 and later, use `std::identity` from [``](functional.md) instead, which is the standard-conforming equivalent described below. + +## `std::identity` (C++20) + +Many standard library APIs take a callable argument such as a projection or transformation function. If you need to pass a callable but don't want to change the data, pass `std::identity`. This is common in ranges algorithms. Many `` ranges overloads have a projection parameter that defaults to `std::identity{}`. + +### Syntax ```cpp -struct identity { - typedef Type type; - Type operator()(const Type& left) const; +struct identity +{ + template + _NODISCARD constexpr T&& operator()(T&& t) const noexcept; + using is_transparent = int; }; ``` -### Parameters +### Remarks + +The `is_transparent` member type is a tag that marks `std::identity` as a transparent function object. Its presence indicates that algorithms can perform comparisons or projections without needing to convert types to a common form first. This is useful for associative containers and algorithms that support heterogeneous lookup, allowing them to compare different types directly without constructing temporary objects. -*left*\ -The value to identify. +### Examples -## Remarks +```cpp +#include +#include +#include +#include +#include + +int main() +{ + std::vector v{3, 1, 4, 1, 5, 9, 2, 6}; -The class contains the public type definition `type`, which is the same as the template parameter Type. It is used in conjunction with template function [forward](../standard-library/utility-functions.md#forward) to ensure that a function parameter has the desired type. + // Ranges algorithms can apply a projection before comparison. + // But if you don't want to apply a projection, i.e. you don't want to modify the data + // before comparison, you can use std::identity to leave each element unchanged. + // Here, std::identity{} means "project each element as itself". + // So the comparator sees the original int values unchanged. + std::ranges::sort(v, std::less{}, std::identity{}); -For compatibility with older code, the class also defines the identity function `operator()` which returns its argument *left*. + // This call is equivalent because std::identity{} is the default projection. + // In both calls, elements are sorted directly; no field extraction or + // value transformation happens first. + std::ranges::sort(v); + + for (int n : v) + { + std::cout << n << ' '; + } + std::cout << '\n'; + // Output: 1 1 2 3 4 5 6 9 +} +``` + +This example searches a `std::vector` with a `std::string_view` key. Because `std::identity` has the `is_transparent` member, the algorithm knows to compare these types directly. This way the key doesn't get converted to a temporary `std::string` just to do the comparison. + +```cpp +#include +#include +#include +#include +#include +#include +#include + +int main() +{ + std::vector words{"apple", "banana", "cherry", "date"}; + std::string_view key = "cherry"; + + // `std::less<>` is transparent, so it can compare `std::string` and + // `std::string_view` directly. + // `std::identity` is also marked transparent (`is_transparent`), so the + // projection stays type-flexible instead of forcing one fixed type. + auto it = std::ranges::lower_bound(words, key, std::less<>{}, std::identity{}); + + if (it != words.end() && *it == key) + { + std::cout << "Found: " << *it << '\n'; + } +} +``` diff --git a/docs/standard-library/in-place-t-struct.md b/docs/standard-library/in-place-t-struct.md index 4e2312570fb..b7c4cecc593 100644 --- a/docs/standard-library/in-place-t-struct.md +++ b/docs/standard-library/in-place-t-struct.md @@ -1,32 +1,108 @@ --- -description: "Learn more about: in_place_t Struct" -title: "in_place_t Struct" -ms.date: "11/04/2016" -f1_keywords: ["utility", "utility/std::in_place_t"] -helpviewer_keywords: ["utility struct"] +description: "Learn more about: in_place_t, in_place_type_t, in_place_index_t" +title: "in_place_t, in_place_type_t, in_place_index_t" +ms.date: 11/14/2024 +f1_keywords: ["utility/utility", "utility/std::in_place_t", "utility/utility", "utility/std::in_place_type_t", "utility", "utility/std::in_place_index_t"] +helpviewer_keywords: ["utility struct", "utility struct", "utility::in_place_type_t struct", "utility struct", "utility::in_place_index_t struct"] --- -# in_place_t Struct +# `in_place_t`, `in_place_type_t`, `in_place_index_t` struct + +Introduced in C++17. + +The `in_place_t`, `in_place_type_t`, and `in_place_index_t` tag types are used to select the overloaded constructor that creates the object in place in the desired way. For the types that use these tag types, they can also help avoid temporary copy or move operations. ## Syntax ```cpp -struct in_place_t { +struct in_place_t +{ explicit in_place_t() = default; }; inline constexpr in_place_t in_place{}; template - struct in_place_type_t { - explicit in_place_type_t() = default; - }; +struct in_place_type_t +{ + explicit in_place_type_t() = default; +}; -template inline constexpr in_place_type_t in_place_type{}; +template +constexpr in_place_type_t in_place_type{}; template - struct in_place_index_t { - explicit in_place_index_t() = default; - }; +struct in_place_index_t +{ + explicit in_place_index_t() = default; +}; -template inline constexpr in_place_index_t in_place_index{}; +template +constexpr in_place_index_t in_place_index{}; ``` + +## Parameters + +*`I`*\ +The index where the object is created in place. + +*`T`*\ +The type of object to create. + +## Remarks + +- `in_place_t` indicates in-place construction of an object. Used to create objects in place inside a `std::optional`. +- `in_place_type_t` indicates in-place construction of an object of a specific type. It's useful with `std::any` because `std::any` can hold any kind of type, so we need to specify the type it holds. +- `in_place_index_t` indicates in-place construction of an object at a specific index. Use with `std::variant` to specify the index where the object is created. + +The following class types use these structs in their constructors: `expected`, [`optional`](optional-class.md), [`single_view`](single-view-class.md), [`any`](any-class.md) or [`variant`](variant-class.md). + +## Example + +```cpp +#include +#include +#include +#include + +// compile with /std:c++17 + +struct MyStruct +{ + double value; + MyStruct(double v0, double v1 = 0) : value(v0 + v1) {} +}; + +int main() +{ + // Construct a MyStruct directly inside opt + std::optional opt(std::in_place, 29.0, 13.0); + + // Construct a MyStruct object inside an any object + std::any a(std::in_place_type, 3.14); + + // Construct a MyStruct object inside a vector at index 0 + std::variant v(std::in_place_index<0>, 2.718); + + if (opt) + { + std::cout << opt->value << ", "; + } + + std::cout << std::any_cast(a).value << ", " + << std::get<0>(v).value; + + return 0; +} +``` + +```output +42, 3.14, 2.718 +``` + +## Requirements + +**Header:** `` + +**Namespace:** `std` + +**Compiler Option:** [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. \ No newline at end of file diff --git a/docs/standard-library/indirect-array-class.md b/docs/standard-library/indirect-array-class.md index 90054b40f03..8b49ff5f8fe 100644 --- a/docs/standard-library/indirect-array-class.md +++ b/docs/standard-library/indirect-array-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: indirect_array class" title: "indirect_array class" +description: "Learn more about: indirect_array class" ms.date: 01/12/2022 f1_keywords: ["valarray/std::indirect_array"] helpviewer_keywords: ["indirect_array class"] -ms.assetid: 10e1eaea-ba5a-405c-a25e-7bdd3eee7fc7 --- # `indirect_array` class @@ -20,7 +19,7 @@ You construct an `indirect_array` object only by writing an expression of The sequence consists of [`xa.size`](../standard-library/valarray-class.md#size) elements, where element `I` becomes the index `xa[I]` within `va`. -## Example: +## Example ```cpp // indirect_array.cpp diff --git a/docs/standard-library/input-iterator-tag-struct.md b/docs/standard-library/input-iterator-tag-struct.md index 8e903ec94b3..b83a8863af1 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 73196c26377..591880c48df 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 --- @@ -268,11 +267,11 @@ int main( ) cout << ")." << endl; insert_iterator > ii ( vec, vec.begin ( ) ); -*ii = 30; + *ii = 30; ii++; -*ii = 40; + *ii = 40; ii++; -*ii = 50; + *ii = 50; cout << "After the insertions, the vector vec becomes:\n ( "; for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++ ) @@ -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 ef27dfffbe1..acd72f03963 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/invalid-argument-class.md b/docs/standard-library/invalid-argument-class.md index 9a3babf927a..f2a22f505cb 100644 --- a/docs/standard-library/invalid-argument-class.md +++ b/docs/standard-library/invalid-argument-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: invalid_argument Class" -title: "invalid_argument Class" -ms.date: "09/09/2021" +title: "invalid_argument class" +description: "Learn more about: invalid_argument class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::invalid_argument"] helpviewer_keywords: ["invalid_argument class"] -ms.assetid: af6c227d-ad7c-4e63-9dee-67af81d83506 --- -# invalid_argument Class +# `invalid_argument` class The class serves as the base class for all exceptions thrown to report an invalid argument. @@ -18,13 +17,12 @@ public: explicit invalid_argument(const string& message); explicit invalid_argument(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). ## Example @@ -49,19 +47,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: invalid bitset char Type: class std::invalid_argument -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[logic_error Class](../standard-library/logic-error-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`logic_error` class](logic-error-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/iomanip-functions.md b/docs/standard-library/iomanip-functions.md index 3c821d8b77a..64bf5ddc618 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-base-class.md b/docs/standard-library/ios-base-class.md index c8e5762d83e..f84b995bda4 100644 --- a/docs/standard-library/ios-base-class.md +++ b/docs/standard-library/ios-base-class.md @@ -665,7 +665,7 @@ void callback1( ios_base::event e, ios_base& stream, int arg ) case ios_base::copyfmt_event: cout << "an copyfmt event" << endl; break; - }; + } } void callback2( ios_base::event e, ios_base& stream, int arg ) @@ -682,7 +682,7 @@ void callback2( ios_base::event e, ios_base& stream, int arg ) case ios_base::copyfmt_event: cout << "an copyfmt event" << endl; break; - }; + } } int main( ) diff --git a/docs/standard-library/ios-functions.md b/docs/standard-library/ios-functions.md index 2b635a87266..458210579ae 100644 --- a/docs/standard-library/ios-functions.md +++ b/docs/standard-library/ios-functions.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["xiosbase/std::defaultfloat", "xiosbase/std::boolalpha", "xiosbase/std::dec", "ios/std::fixed", "ios/std::hex", "ios/std::internal", "ios/std::left", "ios/std::noboolalpha", "ios/std::noshowbase", "ios/std::noshowpoint", "ios/std::noshowpos", "ios/std::noskipws", "ios/std::nounitbuf", "ios/std::nouppercase", "ios/std::oct", "ios/std::right", "ios/std::scientific", "ios/std::showbase", "ios/std::showpoint", "ios/std::showpos", "ios/std::skipws", "ios/std::unitbuf", "ios/std::uppercase"] -ms.assetid: 1382d53f-e531-4b41-adf6-6a1543512e51 helpviewer_keywords: ["std::defaultfloat [C++]", "std::boolalpha [C++]", "std::dec [C++]", "std::fixed [C++]", "std::hex [C++]", "std::hexfloat [C++]", "std::io_errc [C++]", "std::internal [C++]", "std::iostream_category [C++]", "std::is_error_code_enum [C++]", "std::left [C++]", "std::make_error_code [C++]", "std::make_error_condition [C++]", "std::noboolalpha [C++]", "std::noshowbase [C++]", "std::noshowpoint [C++]", "std::noshowpos [C++]", "std::noskipws [C++]", "std::nounitbuf [C++]", "std::nouppercase [C++]", "std::oct [C++]", "std::right [C++]", "std::scientific [C++]", "std::showbase [C++]", "std::showpoint [C++]", "std::showpos [C++]", "std::skipws [C++]", "std::unitbuf [C++]", "std::uppercase [C++]"] --- # `` functions @@ -29,7 +28,7 @@ A reference to the object from which *str* is derived. By default, variables of type **`bool`** are displayed as 1 or 0. -`boolalpha` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)( `ios_base::boolalpha`), and then returns *str*. +`boolalpha` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)(`ios_base::boolalpha`), and then returns *str*. [noboolalpha](../standard-library/ios-functions.md#noboolalpha) reverses the effect of `boolalpha`. @@ -81,7 +80,7 @@ A reference to the object from which *str* is derived. By default, integer variables are displayed in base 10. -`dec` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)( `ios_base::dec`, `ios_base::basefield`), and then returns *str*. +`dec` effectively calls `str.`[setf](../standard-library/ios-base-class.md#setf)(`ios_base::dec`, `ios_base::basefield`), and then returns *str*. ### Example @@ -151,7 +150,7 @@ A reference to the object from which *str* is derived. `fixed` is the default display notation for floating-point numbers. [scientific](../standard-library/ios-functions.md#scientific) causes floating-point numbers to be displayed using scientific notation. -The manipulator effectively calls *str*.[setf](../standard-library/ios-base-class.md#setf)( `ios_base::fixed`, `ios_base::floatfield` ), and then returns *str*. +The manipulator effectively calls *str*.[setf](../standard-library/ios-base-class.md#setf)(`ios_base::fixed`, `ios_base::floatfield`), and then returns *str*. ### Example @@ -199,7 +198,7 @@ A reference to the object from which *str* is derived. By default, integer variables are displayed in base 10 notation. [dec](../standard-library/ios-functions.md#dec) and [oct](../standard-library/ios-functions.md#oct) also change the way integer variables appear. -The manipulator effectively calls `str`**.**[setf](../standard-library/ios-base-class.md#setf)( `ios_base::hex`, `ios_base::basefield`), and then returns *str*. +The manipulator effectively calls `str`**.**[setf](../standard-library/ios-base-class.md#setf)(`ios_base::hex`, `ios_base::basefield`), and then returns *str*. ### Example @@ -456,7 +455,7 @@ A reference to the object from which *str* is derived. `noshowpos` is on by default. -The manipulator effectively calls `str.`[unsetf](../standard-library/ios-base-class.md#unsetf)`(ios_base::showps)`, then returns *str*. +The manipulator effectively calls `str.`[unsetf](../standard-library/ios-base-class.md#unsetf)`(ios_base::showpos)`, then returns *str*. ### Example diff --git a/docs/standard-library/iostreams-conventions.md b/docs/standard-library/iostreams-conventions.md index bfc1b389ddd..33f3588d273 100644 --- a/docs/standard-library/iostreams-conventions.md +++ b/docs/standard-library/iostreams-conventions.md @@ -1,33 +1,32 @@ --- -description: "Learn more about: iostreams Conventions" title: "iostreams Conventions" -ms.date: "11/04/2016" +description: "Learn more about: iostreams Conventions" +ms.date: 11/04/2016 helpviewer_keywords: ["iostream header", "C++ Standard Library, iostreams"] -ms.assetid: 9fe5ded0-37a1-48d1-9671-c81ffc4760ad --- # iostreams Conventions The iostreams headers support conversions between text and encoded forms, and input and output to external files: -[\](../standard-library/fstream.md)\ -[\](../standard-library/iomanip.md)\ -[\](../standard-library/ios.md)\ -[\](../standard-library/iosfwd.md)\ -[\](../standard-library/iostream.md)\ -[\](../standard-library/istream.md)\ -[\](../standard-library/ostream.md)\ -[\](../standard-library/sstream.md)\ -[\](../standard-library/streambuf.md)\ -[\](../standard-library/strstream.md) +[``](fstream.md)\ +[``](iomanip.md)\ +[``](ios.md)\ +[``](iosfwd.md)\ +[``](iostream.md)\ +[``](istream.md)\ +[``](ostream.md)\ +[``](sstream.md)\ +[``](streambuf.md)\ +[``](strstream.md) -The simplest use of iostreams requires only that you include the header [\](../standard-library/iostream.md). You can then extract values from [cin](../standard-library/iostream.md#cin) or [wcin](../standard-library/iostream.md#wcin) to read the standard input. The rules for doing so are outlined in the description of the class [basic_istream Class](../standard-library/basic-istream-class.md). You can also insert values to [cout](../standard-library/iostream.md#cout) or [wcout](../standard-library/iostream.md#wcout) to write the standard output. The rules for doing so are outlined in the description of the class [basic_ostream Class](../standard-library/basic-ostream-class.md). Format control common to both extractors and insertors is managed by the class [basic_ios Class](../standard-library/basic-ios-class.md). Manipulating this format information in the guise of extracting and inserting objects is the province of several manipulators. +The simplest use of iostreams requires only that you include the header [``](iostream.md). You can then extract values from [`cin`](iostream.md#cin) or [`wcin`](iostream.md#wcin) to read the standard input. The rules for doing so are outlined in the description of the [`basic_istream` class](basic-istream-class.md). You can also insert values to [`cout`](iostream.md#cout) or [`wcout`](iostream.md#wcout) to write the standard output. The rules for doing so are outlined in the description of the [`basic_ostream` class](basic-ostream-class.md). Format control common to both extractors and insertors is managed by the [`basic_ios` class](basic-ios-class.md). Manipulating this format information in the guise of extracting and inserting objects is the province of several manipulators. -You can perform the same iostreams operations on files that you open by name, using the classes declared in [\](../standard-library/fstream.md). To convert between iostreams and objects of class [basic_string Class](../standard-library/basic-string-class.md), use the classes declared in [\](../standard-library/sstream.md). To do the same with C strings, use the classes declared in [\](../standard-library/strstream.md). +You can perform the same iostreams operations on files that you open by name, using the classes declared in [``](fstream.md). To convert between iostreams and objects of [`basic_string` class](basic-string-class.md), use the classes declared in [``](sstream.md). To do the same with C strings, use the classes declared in [``](strstream.md). The remaining headers provide support services, typically of direct interest to only the most advanced users of the iostreams classes. ## See also -[C++ Standard Library Overview](../standard-library/cpp-standard-library-overview.md)\ -[iostream Programming](../standard-library/iostream-programming.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[C++ Standard Library Overview](cpp-standard-library-overview.md)\ +[`iostream` Programming](iostream-programming.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/iota-view-class.md b/docs/standard-library/iota-view-class.md new file mode 100644 index 00000000000..f33113e8cb6 --- /dev/null +++ b/docs/standard-library/iota-view-class.md @@ -0,0 +1,204 @@ +--- +title: iota_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) iota_view class: a factory that generates a view from a bounded or unbounded series of repeatedly incrementing values." +ms.date: 11/04/2022 +f1_keywords: ["ranges/std::iota_view", "ranges/std::iota_view::base", "ranges/std::iota_view::begin", "ranges/std::iota_view::end", "ranges/std::iota_view::size", "ranges/std::iota_view::empty", "ranges/std::iota_view::operator bool", "ranges/std::iota_view::back", "ranges/std::iota_view::front", "ranges/std::iota_view::operator[]"] +helpviewer_keywords: ["std::ranges::iota_view [C++]", "std::ranges::iota_view [C++], base", "std::ranges::iota_view [C++], begin", "std::ranges::iota_view [C++], end", "std::ranges::iota_view [C++], size", "std::ranges::iota_view [C++], empty", "std::ranges::iota_view [C++], operator bool", "std::ranges::iota_view [C++], front", "std::ranges::iota_view [C++], back", "std::ranges::iota_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `iota_view` class (C++ Standard Library) + +Generates a view of a sequence of elements by repeatedly incrementing an initial value. The sequence can be bounded or unbounded. + +## Syntax + +```cpp +template + requires __WeaklyEqualityComparableWith && std::copyable +class iota_view : public ranges::view_interface>; +``` + +### Template parameters + +*`W`*\ + The type of the values in the sequence. The specified type must support `operator++`. + +*`Bound`*\ +The type of the end value. If *`Bound`* is `std::unreachable_sentinel_t` (the default value), then the view is unbounded. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::iota`](range-adaptors.md#iota) | +| **Underlying range** | Not applicable because this view generates its members | +| **Element type** | Same as the template parameter `W` | +| **View iterator category** | Supports [`input_range`](range-concepts.md#input_range) up to [`random_access_range`](range-concepts.md#random_access_range), depending on the type of `W` | +| **Sized** | Only if the range has an end value, that is, it isn't an infinite series | +| **Is `const`-iterable** | Yes | +| **Common range** | Only if `Bound` is the same type as `W` | +| **Borrowed range** | Yes | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) C++20| Construct the view. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +A good way to create a `iota_view` is by using the [`iota`](range-adaptors.md#iota) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +The sequence of values can be integral values such as 1,2,3 or 'a', 'b', 'c' or consecutive elements from a range. + +This view is typically used to iterate over a series of values. For example: + +```cpp +for (int i : iota_view{1, 10}) // iterate over a view of the integers 1 through 9 +{ + std::cout << i << ' '; // 1 2 3 4 5 6 7 8 9 +} +``` + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of an `iota_view`. + +```cpp +1) iota_view() requires std::default_initializable = default; +2) constexpr explicit iota_view(W value); +3) constexpr iota_view(std::type_identity_t value, std::type_identity_t bound); +4) constexpr iota_view( /*iterator*/ first, /*sentinel*/ last ); +``` + +### Parameters + +*`value`*\ +The starting value for the series. + +*`bound`*\ +The bound of the series. It's one greater than the last value in the series. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +1\) Create an `iota_view` with a starting and ending value determined by the default-initialized template type `W`.\ +2\) Create an `iota_view` with the specified starting value and ending value determined by the value-initialized type `W`.\ +3\) Create a bounded `iota_view` with the specified starting value and ending value. The ending value is one less than the last value specified.\ +4\) Used to create subviews. For example, `std::ranges::iota_view(start, end);` where `start` and `end` are iterators to the start and end of the subview. + +Rather than create this class directly, an easy way to create a `iota_view` is by using the [`iota`](range-adaptors.md#iota) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +If the bound's type is `unreachable_sentinel_t`, the resulting view is bounded. + +When you use one of the constructors that value-initializes the bound, the bound will be the default-initialized value for that type. For example, `iota_view{}` is an empty range of `int` since the default-constructed int value and bound are both `0`. Also, `iota_view{-4}` is `-4, -3, -2, -1` because the default-constructed `int` bound is `0`. + +## `iota_view` constructor example + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::ranges::iota_view iv; // create an iota_view with an unbounded range, starting at 0 + std::ranges::iota_view iv2(5); // create an iota_view with an unbounded range, starting at 5. + std::ranges::iota_view iv3{5, 10}; // create an iota_view with a bounded range, starting at 5 and ending at 9 + + std::vector v{10, 20, 35, 45, 50, 66, 77, 82, 90, 100}; + auto start = std::ranges::find(v, 35); + auto end = std::ranges::find(v, 82); + for (auto &&val : std::ranges::iota_view(start, end)) + { + std::cout << *val << ' '; // outputs 35 45 50 66 77 + } +} +``` + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +## `end` + +Get the end sentinel at the end of the view. + +```cpp +constexpr auto end(); +constexpr auto end() const requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +If the `iota_view` is unbounded, returns `std::unreachable_sentinel`. + +If the `iota_view` is bounded, returns an iterator pointing at the sentinel past the last value in the sequence. + +## `size` + +Get the number of elements in the view. The `iota_view` must be bounded. + +```cpp +constexpr auto size() requires + (same_as && advanceable ) || + (integral && integral) || + sized_sentinel_for; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `iota_view`. + +### Remarks + +You can't call `size()` on an unbounded `iota_view`. + +## See also + +[``](ranges.md)\ +[`iota()` range adaptor](range-adaptors.md#iota)\ +[`std::numerics::iota`](numeric-functions.md#iota)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/is-clock-struct.md b/docs/standard-library/is-clock-struct.md index 88dd66a67d0..86d02a8daa1 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 320d487d286..68b900c9dd4 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 cf277036fe6..f5599c93e10 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 847f67bb93e..b5e7684077a 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 5393a82b019..5b0e2c372b6 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 @@ -39,7 +37,8 @@ A stream. Skips white space in the stream. ```cpp -template class basic_istream& ws(basic_istream& _Istr); +template +basic_istream& ws(basic_istream& _Istr); ``` ### Parameters diff --git a/docs/standard-library/istream-iterator-class.md b/docs/standard-library/istream-iterator-class.md index 51710e020e3..4961861016a 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 2fb9ef751ec..9d43bdeaa16 100644 --- a/docs/standard-library/istream-typedefs.md +++ b/docs/standard-library/istream-typedefs.md @@ -1,16 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["istream/std::iostream", "istream/std::istream", "istream/std::wiostream", "istream/std::wistream"] -ms.assetid: 55bc1f84-53a7-46ca-a36f-ac6ef75d0374 --- # `` typedefs -[iostream](#iostream)\ -[istream](#istream)\ -[wiostream](#wiostream)\ -[wistream](#wistream) +The `` header provides the following typedefs: ## iostream diff --git a/docs/standard-library/istreambuf-iterator-class.md b/docs/standard-library/istreambuf-iterator-class.md index 9b05304ed12..13b7a13fc70 100644 --- a/docs/standard-library/istreambuf-iterator-class.md +++ b/docs/standard-library/istreambuf-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: istreambuf_iterator Class" title: "istreambuf_iterator Class" +description: "Learn more about: istreambuf_iterator Class" ms.date: 06/15/2022 f1_keywords: ["streambuf/std::istreambuf_iterator", "iterator/std::istreambuf_iterator::char_type", "iterator/std::istreambuf_iterator::int_type", "iterator/std::istreambuf_iterator::istream_type", "iterator/std::istreambuf_iterator::streambuf_type", "iterator/std::istreambuf_iterator::traits_type", "iterator/std::istreambuf_iterator::equal"] helpviewer_keywords: ["std::istreambuf_iterator [C++]", "std::istreambuf_iterator [C++], char_type", "std::istreambuf_iterator [C++], int_type", "std::istreambuf_iterator [C++], istream_type", "std::istreambuf_iterator [C++], streambuf_type", "std::istreambuf_iterator [C++], traits_type", "std::istreambuf_iterator [C++], equal"] -ms.assetid: 39002da2-61a6-48a5-9d0c-5df8271f6038 ms.custom: devdivchpfy22 --- @@ -15,7 +14,7 @@ The class template istreambuf_iterator describes an input iterator object that e ## Syntax ```cpp -template > +template > class istreambuf_iterator : public iterator ``` @@ -341,7 +340,7 @@ int main( ) ostreambuf_iterator outpos ( cout ); while ( inpos != endpos ) { -*outpos = *inpos; + *outpos = *inpos; ++inpos; //Increment istreambuf_iterator ++outpos; } diff --git a/docs/standard-library/iterator-concepts.md b/docs/standard-library/iterator-concepts.md new file mode 100644 index 00000000000..a5e205079fb --- /dev/null +++ b/docs/standard-library/iterator-concepts.md @@ -0,0 +1,482 @@ +--- +title: "Iterator concepts" +description: "Learn more about iterator concepts." +ms.date: 12/16/2022 +f1_keywords: ["ranges/std::ranges::range", "ranges/std::ranges::bidirectional_iterator", "ranges/std::ranges::borrowed_iterator", "ranges/std::ranges::common_iterator", "ranges/std::ranges::contiguous_iterator", "ranges/std::ranges::forward_iterator", "ranges/std::ranges::input_iterator", "ranges/std::ranges::output_iterator", "ranges/std::ranges::random_access_iterator", "ranges/std::ranges::simple_view", "ranges/std::ranges::sized_iterator", "ranges/std::ranges::view", "ranges/std::ranges::viewable_iterator"] +helpviewer_keywords: ["std::ranges [C++], ranges::range", "std::ranges [C++], ranges::bidirectional_iterator", "std::ranges [C++], ranges::borrowed_iterator", "std::ranges [C++], ranges::common_iterator", "std::ranges [C++], ranges::contiguous_iterator", "std::ranges [C++], ranges::forward_iterator", "std::ranges [C++], ranges::input_iterator", "std::ranges [C++], ranges::output_iterator", "std::ranges [C++], ranges::random_access_iterator", "std::ranges [C++], ranges::simple_view", "std::ranges [C++], ranges::sized_iterator", "std::ranges [C++], ranges::view", "std::ranges [C++], ranges::viewable_iterator"] +--- +# Iterator concepts + +Concepts are a C++20 language feature that constrain template parameters at compile time. They help prevent incorrect template instantiation, specify template argument requirements in a readable form, and provide more succinct template related compiler errors. + +Consider the following example, which defines a concept to prevent instantiating the template with a type that doesn't support division: + +```cpp +// requires /std:c++20 or later +#include + +// Definition of dividable concept which requires +// that arguments a & b of type T support division +template +concept dividable = requires (T a, T b) +{ + a / b; +}; + +// Apply the concept to a template. +// The template will only be instantiated if argument T supports division. +// This prevents the template from being instantiated with types that don't support division. +// This could have been applied to the parameter of a template function, but because +// most of the concepts in the library are applied to classes, this form is demonstrated. +template requires dividable +class DivideEmUp +{ +public: + T Divide(T x, T y) + { + return x / y; + } +}; + +int main() +{ + DivideEmUp dividerOfInts; + std::cout << dividerOfInts.Divide(6, 3); // outputs 2 + // The following line will not compile because the template can't be instantiated + // with char* because char* can be divided + DivideEmUp dividerOfCharPtrs; // compiler error: cannot deduce template arguments +} +``` + +When you pass the compiler switch `/diagnostics:caret` to Visual Studio 2022 version 17.4 preview 4 or later, the error that concept `dividable` evaluated to false will point directly to the expression requirement `(a / b)` that failed. + +Iterator concepts are defined in the `std` namespace, and are declared in the `` header file. They're used in the declarations of [range adaptors](range-adaptors.md), [views](view-classes.md), and so on. + +There are six categories of iterators. They're directly related to the categories of ranges listed under [Range concepts](ranges.md#range-concepts). + +The following iterator concepts are listed in order of increasing capability. `input_or_output_iterator` is at the low end of the capability hierarchy, and `contiguous_iterator` is at the high end. Iterators higher in the hierarchy can generally be used in place of those that are lower, but not vice-versa. For example, a `random_access_iterator` iterator can be used in place of a `forward_iterator`, but not the other way around. An exception is `input_iterator`, which can't be used in place of `output_iterator` because it can't write. + +:::image type="content" source="media/iterator-hiearchy.svg" alt-text="Diagram of the iterator hierarchy. input_or_output_iterator is the base. input_iterator and output_iterator are shown as refining input_or_output_iterator. forward_iterator is next and refines both input_iterator and output_iterator. bidirectional_iterator refines forward_iterator. random_access_iterator refines bidirectional_iterator. Finally, contiguous_iterator refines random_access_iterator"::: + +In the following table, "Multi-pass" refers to whether the iterator can revisit the same element more than once. For example, `vector::iterator` is a multi-pass iterator because you can make a copy of the iterator, read the elements in the collection, and then restore the iterator to the value in the copy, and revisit the same elements again. If an iterator is single-pass, you can only visit the elements in the collection once. + +In the following table, "Example types" refers to collections/iterators that satisfy the concept. + +| Iterator concept | Description | Direction | Read/write | Multi-pass | Example types | +|--|--|--|--|--|--| +| [`input_or_output_iterator`](#input_or_output_iterator)C++20 | The basis of the iterator concept taxonomy. | Forward | Read/write | no | `istream_iterator`, `ostream_iterator` | +| [`output_iterator`](#output_iterator)C++20 | Specifies an iterator that you can write to. | Forward | Write | no | `ostream`, `inserter` | +| [`input_iterator`](#input_iterator)C++20 | Specifies an iterator that you can read from once. | Forward | Read | no | `istream`, `istreambuf_iterator` | +| [`forward_iterator`](#forward_iterator)C++20 | Specifies an iterator that can read (and possibly write) multiple times. | Forward | Read/write | yes | `vector`, `list` | +| [`bidirectional_iterator`](#bidirectional_iterator)C++20 | Specifies an iterator that you can read and write both forwards and backwards. | Forward or backward | Read/write | yes | `list`, `set`, `multiset`, `map`, and `multimap`. | +| [`random_access_iterator`](#random_access_iterator)C++20 | Specifies an iterator that you can read and write by index. | Forward or backward | Read/write | yes | `vector`, `array`, `deque` | +| [`contiguous_iterator`](#contiguous_iterator)C++20 | Specifies an iterator whose elements are sequential in memory, are the same size, and can be accessed using pointer arithmetic. | Forward or backward | Read/write | yes | `array`, `vector`, `string`.| + +Other iterator concepts include: + +| Iterator concept | Description | +|--|--| +| [`sentinel_for`](#sentinel_for)C++20 | Specifies that a type is a sentinel for an iterator type. | +| [`sized_sentinel_for`](#sized_sentinel_for)C++20 | Specifies that an iterator and its sentinel can be subtracted (using `-`) to find their difference in constant time. | + +## `bidirectional_iterator` + +A `bidirectional_iterator` supports reading and writing forwards and backwards. + +```cpp +template +concept bidirectional_iterator = + forward_iterator && + derived_from && + requires(I i) { + {--i} -> same_as; + {i--} -> same_as; +}; +``` + +### Parameters + +*`I`*\ +The iterator to test to see if it's a `bidirectional_iterator`. + +### Remarks + +A `bidirectional_iterator` has the capabilities of a `forward_iterator`, but can also iterate backwards. + +Some examples of containers that can be used with a `bidirectional_iterator` are `set`, `multiset`, `map`, `multimap`, `vector`, and `list`. + +### Example: `bidirectional_iterator` + +The following example uses the `bidirectional_iterator` concept to show that `vector` has a `bidirectional_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + std::cout << std::boolalpha << std::bidirectional_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::contiguous_iterator; // outputs true +} +``` + +## `contiguous_iterator` + +Specifies an iterator whose elements are sequential in memory, are the same size, and can be accessed using pointer arithmetic. + +```cpp +template + concept contiguous_iterator = + random_access_iterator && + derived_from && + is_lvalue_reference_v> && + same_as, remove_cvref_t>> && + requires(const I& i) { + { to_address(i) } -> same_as>>; + }; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's a `contiguous_iterator`. + +### Remarks + +A `contiguous_iterator` can be accessed by pointer arithmetic because the elements are laid out sequentially in memory and are the same size. Some examples of a `contiguous_iterator` are `array`, `vector`, and `string`. + +### Example: `contiguous_iterator` + +The following example uses the `contiguous_iterator` concept to show that a `vector` has a `contiguous_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has a contiguous_iterator + std::cout << std::boolalpha << std::contiguous_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::contiguous_iterator; // outputs true +} +``` + +## `forward_iterator` + +Has the capabilities of an `input_iterator` and an `output_iterator`. Supports iterating over a collection multiple times. + +```cpp +template + concept forward_iterator = + input_iterator && + derived_from && + incrementable && + sentinel_for; +``` + +### Parameters + +*`I`*\ +The iterator to test to see if it's a `forward_iterator`. + +### Remarks + +A `forward_iterator` can only move forward. + +Some examples of containers that can be used with a `forward_iterator` are `vector`, `list`, `unordered_set`, `unordered_multiset`, `unordered_map`, and `unordered_multimap`. + +### Example: `forward_iterator` + +The following example uses the `forward_iterator` concept to show that a `vector` has a `forward_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has a forward_iterator + std::cout << std::boolalpha << std::forward_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::forward_iterator; // outputs true +} +``` + +## `input_iterator` + +An `input_iterator` is an iterator that you can read from at least once. + +```cpp +template +concept input_iterator = + input_or_output_iterator && + indirectly_readable && + requires { typename ITER_CONCEPT(I); } && + derived_from; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's an `input_iterator`. + +### Remarks + +Calling `begin()` on an `input_iterator` more than once results in undefined behavior. A type that only models `input_iterator` isn't multi-pass. Consider reading from standard input (`cin`) for example. In this case, you can only read the current element once and you can't re-read characters you've already read. An `input_iterator` only reads forward, not backwards. + +### Example: `input_iterator` + +The following example uses the `input_iterator` concept to show that an `istream_iterator` has an `input_iterator`: + +```cpp +// requires /std:c++20 or later +#include + +int main() +{ + // Show that a istream_iterator has an input_iterator + std::cout << std::boolalpha << std::input_iterator>; // outputs true +} +``` + +## `input_or_output_iterator` + +An `input_or_output_iterator` is the basis of the iterator concept taxonomy. It supports dereferencing and incrementing +an iterator. Every iterator models `input_or_output_iterator`. + +```cpp +template +concept input_or_output_iterator = + requires(I i) { + { *i } -> can-reference; + } && + weakly_incrementable; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's an `input_or_output_iterator`. + +### Remarks + +The concept `can-reference` means that the type `I` is a reference, a pointer, or a type that can be implicitly converted to a reference. + +### Example: `input_or_output_iterator` + +The following example uses the `input_or_output_iterator` concept to show that `vector` has an `input_or_output_iterator`: + +```cpp +// requires /std:c++20 or later +#include + +int main() +{ + // Show that a vector has an input_or_output_iterator + std::cout << std::boolalpha << std::input_or_output_iterator::iterator> << '\n'; // outputs true + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::input_or_output_iterator; // outputs true +} +``` + +## `output_iterator` + +An `output_iterator` is an iterator that you can write to. + +```cpp +template +concept output_iterator = + input_or_output_iterator && + indirectly_writable && + requires(I i, T&& t) { + *i++ = std::forward(t); + }; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's an `output_iterator`. + +*`T`*\ +The type of the values to write. + +### Remarks + +An `output_iterator` is single pass. That is, it can only write to the same element once. + +### Example: `output_iterator` + +The following example uses the `output_iterator` concept to show that `vector` has an `output_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has an output_iterator + std::cout << std::boolalpha << std::output_iterator::iterator, int> << "\n"; // outputs "true" + + // another way to test + std::vector v = {0,1,2,3,4,5}; + std::cout << std::boolalpha << std::output_iterator; // outputs true +} +``` + +## `random_access_iterator` + +A `random_access_iterator` can read or write by index. + +```cpp +template +concept random_access_iterator = + bidirectional_iterator && + derived_from && + totally_ordered && + sized_sentinel_for && + requires(I i, const I j, const iter_difference_t n) { + { i += n } -> same_as; + { j + n } -> same_as; + { n + j } -> same_as; + { i -= n } -> same_as; + { j - n } -> same_as; + { j[n] } -> same_as>; + }; +``` + +### Parameters + +*`I`*\ +The type to test to see if it's a `random_access_iterator`. + +### Remarks + +A `random_access_iterator` has the capabilities of an `input_iterator`, `output_iterator`, `forward_iterator`, and `bidirectional_iterator`. + +Some examples of a `random_access_iterator` are `vector`, `array`, and `deque`. + +### Example: `random_access_iterator` + +The following example shows that a `vector` has a `random_access_iterator`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + // Show that vector has a random_access_iterator + std::cout << std::boolalpha << std::random_access_iterator::iterator> << '\n'; // outputs "true" + + // another way to test + std::vector v = {0,1,2}; + std::cout << std::boolalpha << std::random_access_iterator; // outputs true +} +``` + +## `sentinel_for` + +Specifies that a type is a sentinel for an iterator. + +```cpp +template +concept sentinel_for = + semiregular && + input_or_output_iterator && + weakly-equality-comparable-with ; +``` + +### Parameters + +*`I`*\ +The iterator type. + +*`S`*\ +The type to test to see if it's a sentinel for `I`. + +### Remarks + +A sentinel is a type that can be compared to an iterator to determine if the iterator has reached the end. This concept determines if a type is a sentinel for one of the `input_or_output_iterator` types, which includes `input_iterator`, `output_iterator`, `forward_iterator`, `bidirectional_iterator`, `random_access_iterator`, and `contiguous_iterator`. + +### Example: `sentinel_for` + +The following example uses the `sentinel_for` concept to show that `vector::iterator` is a sentinel for `vector`: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + std::vector v = {0, 1, 2}; + std::vector::iterator i = v.begin(); + // show that vector::iterator is a sentinel for vector + std::cout << std::boolalpha << std::sentinel_for::iterator, decltype(i)>; // outputs true +} +``` + +## `sized_sentinel_for` + +Test that an iterator and its sentinel can be subtracted using `-` to find the difference, in constant time. + +```cpp +template +concept sized_sentinel_for = + sentinel_for && + !disable_sized_sentinel_for, remove_cv_t> && + requires(const I& i, const S& s) { + {s - i} -> same_as>; + {i - s} -> same_as>; + }; +``` + +### Parameters + +*`I`*\ +The iterator type. + +*`S`*\ +The sentinel type to test. + +### Example: `sized_sentinel_for` + +The following example uses the `sized_sentinel_for` concept to verify that the sentinel for a `vector` can be subtracted from the vectors iterator in constant time: + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + std::vector v = { 1, 2, 3 }; + std::vector::iterator i = v.begin(); + std::vector::iterator end = v.end(); + // use the sized_sentinel_for concept to verify that i can be subtracted from end in constant time + std::cout << std::boolalpha << std::sized_sentinel_for << "\n"; // outputs true + std::cout << end - i; // outputs 3 +} +``` + +## See also + +[Range concepts](range-concepts.md)\ +[Range adaptors](range-adaptors.md)\ +[View classes](view-classes.md) \ No newline at end of file diff --git a/docs/standard-library/iterator-functions.md b/docs/standard-library/iterator-functions.md index feb86fe2e25..e758db8a27e 100644 --- a/docs/standard-library/iterator-functions.md +++ b/docs/standard-library/iterator-functions.md @@ -1,35 +1,34 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["xutility/std::advance", "xutility/std::back_inserter", "xutility/std::begin", "xutility/std::cbegin", "xutility/std::cend", "xutility/std::distance", "xutility/std::end", "xutility/std::front_inserter", "xutility/std::inserter", "xutility/std::make_checked_array_iterator", "xutility/std::make_move_iterator", "xutility/std::make_unchecked_array_iterator", "xutility/std::next", "xutility/std::prev"] -ms.assetid: 4a57c9a3-7e36-411f-8655-e0be2eec88e7 helpviewer_keywords: ["std::advance [C++]", "std::back_inserter [C++]", "std::begin [C++]", "std::cbegin [C++]", "std::cend [C++]", "std::distance [C++]", "std::end [C++]", "std::front_inserter [C++]", "std::inserter [C++]", "std::make_checked_array_iterator [C++]", "std::make_move_iterator [C++]", "std::make_unchecked_array_iterator [C++]", "std::next [C++]", "std::prev [C++]"] --- # `` functions -## advance +## `advance` Increments an iterator by a specified number of positions. ```cpp template - void advance(InputIterator& InIt, Distance Off); +void advance(InputIterator& InIt, Distance Off); ``` ### Parameters -*InIt*\ +*`InIt`*\ The iterator that is to be incremented and that must satisfy the requirements for an input iterator. -*Off*\ +*`Off`*\ An integral type that is convertible to the iterator's difference type and that specifies the number of increments the position of the iterator is to be advanced. ### Remarks -The range advanced through must be nonsingular, where the iterators must be dereferenceable or past the end. +The range must be nonsingular, where the iterators must be dereferenceable or past the end. -If the `InputIterator` satisfies the requirements for a bidirectional iterator type, then *Off* may be negative. If `InputIterator` is an input or forward iterator type, *Off* must be nonnegative. +If the `InputIterator` satisfies the requirements for a bidirectional iterator type, then *`Off`* may be negative. If `InputIterator` is an input or forward iterator type, *`Off`* must be nonnegative. The advance function has constant complexity when `InputIterator` satisfies the requirements for a random-access iterator; otherwise, it has linear complexity and so is potentially expensive. @@ -42,33 +41,34 @@ The advance function has constant complexity when `InputIterator` satisfies the #include #include -int main( ) +int main() { - using namespace std; - int i; - - list L; - for ( i = 1 ; i < 9 ; ++i ) - { - L.push_back ( i ); - } - list ::iterator L_Iter, LPOS = L.begin ( ); - - cout << "The list L is: ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; - - cout << "The iterator LPOS initially points to the first element: " + using namespace std; + + list L; + for (int i = 1; i < 9; ++i) + { + L.push_back(i); + } + list::iterator LPOS = L.begin(); + + cout << "The list L is: ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + cout << "The iterator LPOS initially points to the first element: " << *LPOS << "." << endl; - advance ( LPOS , 4 ); - cout << "LPOS is advanced 4 steps forward to point" + advance(LPOS, 4); + cout << "LPOS is advanced 4 steps forward to point" << " to the fifth element: " << *LPOS << "." << endl; - advance ( LPOS , -3 ); - cout << "LPOS is moved 3 steps back to point to the " + advance(LPOS, -3); + cout << "LPOS is moved 3 steps back to point to the " << "2nd element: " << *LPOS << "." << endl; } ``` @@ -80,27 +80,27 @@ LPOS is advanced 4 steps forward to point to the fifth element: 5. LPOS is moved 3 steps back to point to the 2nd element: 2. ``` -## back_inserter +## `back_inserter` Creates an iterator that can insert elements at the back of a specified container. ```cpp template -back_insert_iterator back_inserter(Container& _Cont); +back_insert_iterator back_inserter(Container& Cont); ``` ### Parameters -*_Cont*\ +*`Cont`*\ The container into which the back insertion is to be executed. ### Return Value -A `back_insert_iterator` associated with the container object *_Cont*. +A `back_insert_iterator` associated with the container object *`Cont`*. ### Remarks -Within the C++ Standard Library, the argument must refer to one of the three sequence containers that have the member function `push_back`: [deque Class](../standard-library/deque-class.md), [list Class](../standard-library/list-class.md), or [vector Class](../standard-library/vector-class.md). +Within the C++ Standard Library, the argument must refer to one of the three sequence containers that have the member function `push_back`: [`deque` Class](../standard-library/deque-class.md), [`list` Class](../standard-library/list-class.md), or [`vector` Class](../standard-library/vector-class.md). ### Example @@ -111,38 +111,40 @@ Within the C++ Standard Library, the argument must refer to one of the three seq #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 0 ; i < 3 ; ++i ) - { - vec.push_back ( i ); - } - - vector ::iterator vIter; - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - // Insertions can be done with template function - back_insert_iterator > backiter ( vec ); -*backiter = 30; - backiter++; -*backiter = 40; - - // Alternatively, insertions can be done with the - // back_insert_iterator member function - back_inserter ( vec ) = 500; - back_inserter ( vec ) = 600; - - cout << "After the insertions, the vector vec is: ( "; - for ( vIter = vec.begin ( ) ; vIter != vec.end ( ); vIter++ ) - cout << *vIter << " "; - cout << ")." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 3; ++i) + { + vec.push_back(i); + } + + cout << "The initial vector vec is: ( "; + for (auto vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Insertions can be done with template function + back_insert_iterator > backiter(vec); + *backiter = 30; + backiter++; + *backiter = 40; + + // Alternatively, insertions can be done with the + // back_insert_iterator member function + back_inserter(vec) = 500; + back_inserter(vec) = 600; + + cout << "After the insertions, the vector vec is: ( "; + for (auto vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; } ``` @@ -151,17 +153,17 @@ The initial vector vec is: ( 0 1 2 ). After the insertions, the vector vec is: ( 0 1 2 30 40 500 600 ). ``` -## begin +## `begin` Retrieves an iterator to the first element in a specified container. ```cpp template -auto begin(Container& cont) ` +auto begin(Container& cont) -> decltype(cont.begin()); template -auto begin(const Container& cont) ` +auto begin(const Container& cont) -> decltype(cont.begin()); template @@ -170,17 +172,17 @@ Ty *begin(Ty (& array)[Size]); ### Parameters -*cont*\ +*`cont`*\ A container. -*array*\ +*`array`*\ An array of objects of type `Ty`. ### Return Value The first two template functions return `cont.begin()`. The first function is non-constant; the second one is constant. -The third template function returns *array*. +The third template function returns *`array`*. ### Example @@ -194,22 +196,22 @@ We recommend that you use this template function in place of container member `b #include #include -template void reverse_sort(C& c) { - using std::begin; - using std::end; - - std::sort(begin(c), end(c), std::greater<>()); +template void reverse_sort(C& c) +{ + std::sort(std::begin(c), std::end(c), std::greater<>()); } -template void print(const C& c) { - for (const auto& e : c) { +template void print(const C& c) +{ + for (const auto& e : c) + { std::cout << e << " "; } - std::cout << "\n"; } -int main() { +int main() +{ std::vector v = { 11, 34, 17, 52, 26, 13, 40, 20, 10, 5, 16, 8, 4, 2, 1 }; print(v); @@ -234,7 +236,7 @@ int main() { 160 106 80 70 53 40 35 23 20 16 10 8 5 4 2 1 ``` -The function `reverse_sort` supports containers of any kind, in addition to regular arrays, because it calls the non-member version of `begin()`. If `reverse_sort` were coded to use the container member `begin()`: +The function `reverse_sort` supports containers of any kind, in addition to regular arrays, because it calls the non-member version of `begin()`. Coding `reverse_sort` to use the container member `begin()`: ```cpp template @@ -247,15 +249,15 @@ void reverse_sort(C& c) { } ``` -Then sending an array to it would cause this compiler error: +Then sending an array to it, causes this compiler error: ```Output error C2228: left of '.begin' must have class/struct/union ``` -## cbegin +## `cbegin` -Retrieves a const iterator to the first element in a specified container. +Retrieves a const (read-only) iterator to the first element in a specified container. ```cpp template @@ -265,8 +267,8 @@ auto cbegin(const Container& cont) ### Parameters -*cont*\ -A container or initializer_list. +*`cont`*\ +A container or `initializer_list`. ### Return Value @@ -274,9 +276,9 @@ A constant `cont.begin()`. ### Remarks -This function works with all C++ Standard Library containers and with [initializer_list](../standard-library/initializer-list-class.md). +This function works with all C++ Standard Library containers and with [`initializer_list`](../standard-library/initializer-list-class.md). -You can use this member function in place of the `begin()` template function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `begin()` and `cbegin()`. +You can use this member function in place of the `begin()` template function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `begin()` and `cbegin()`. ```cpp auto i1 = Container.begin(); @@ -286,9 +288,9 @@ auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` -## cend +## `cend` -Retrieves a const iterator to the element that follows the last element in the specified container. +Retrieves a const (read-only) iterator to the element that follows the last element in the specified container. ```cpp template @@ -298,8 +300,8 @@ auto cend(const Container& cont) ### Parameters -*cont*\ -A container or initializer_list. +*`cont`*\ +A container or `initializer_list`. ### Return Value @@ -307,9 +309,9 @@ A constant `cont.end()`. ### Remarks -This function works with all C++ Standard Library containers and with [initializer_list](../standard-library/initializer-list-class.md). +This function works with all C++ Standard Library containers and with [`initializer_list`](../standard-library/initializer-list-class.md). -You can use this member function in place of the [end()](../standard-library/iterator-functions.md#end) template function to guarantee that the return value is `const_iterator`. Typically, it's used in conjunction with the [auto](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `end()` and `cend()`. +You can use this member function in place of the [`end()`](../standard-library/iterator-functions.md#end) template function to guarantee that the return value is `const_iterator`. Typically, it's used with the [`auto`](../cpp/auto-cpp.md) type deduction keyword, as shown in the following example. In the example, consider `Container` to be a modifiable (non- **`const`**) container or `initializer_list` of any kind that supports `end()` and `cend()`. ```cpp auto i1 = Container.end(); @@ -319,28 +321,152 @@ auto i2 = Container.cend(); // i2 is Container::const_iterator ``` -## crbegin +## `crbegin` + +Get a reverse read-only iterator to the elements of the container, starting at the end of the container. ```cpp template constexpr auto crbegin(const C& c) -> decltype(std::rbegin(c)); ``` -## crend +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +This iterator returns the elements of the container in reverse order, starting at the end of the container. + +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: + +### Example: `crbegin` + +```cpp +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + for (auto i = std::crbegin(v); i != std::crend(v); ++i) + { + std::cout << *i << ' '; // outputs 30 20 10 + } + // v[1] = 100; // error because the iterator is const +} +``` + +```output +30 20 10 +``` + +## `crend` + +Get the sentinel at the end of a read-only reversed sequence of elements. ```cpp template constexpr auto crend(const C& c) -> decltype(std::rend(c)); ``` -## data +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +The sentinel follows the last element in a reversed view of the container. + +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: + +### `crend` example ```cpp -template constexpr auto data(C& c) -> decltype(c.data()); -template constexpr auto data(const C& c) -> decltype(c.data()); -template constexpr T* data(T (&array)[N]) noexcept; -template constexpr const E* data(initializer_list il) noexcept; +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::crend(v); + --vi; // get off the sentinel and onto the last element in the reversed range + std::cout << *vi; // outputs 10 + // vi[0] = 300; // error because the iterator is const +} +``` + +```output +10 +``` + +## `data` + +Get a pointer to the first element in the container. + +```cpp +1) template constexpr auto data(C& c) -> decltype(c.data()); +2) template constexpr auto data(const C& c) -> decltype(c.data()); +3) template constexpr T* data(T (&array)[N]) noexcept; +4) template constexpr const E* data(initializer_list il) noexcept; +``` + +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +An instance of a container. + +*`E`*\ +The element type of the initializer list. + +*`il`*\ +An initializer list. + +*`N`*\ +The number of elements in the array. + +*`T`*\ +The type of the data in the array. + +### Return value + +1, 2\) A pointer, based on the type of the container, to the first element. For example, if the container is a vector of integers, the type of the return value is an `int *`. + +3\) A pointer to the first element as an array. + +4\) A pointer to the first element of the initializer list. + +### Example `data` + +```cpp +#include +#include + +int main() +{ + std::vector v{ 10, 20, 30 }; + std::string src{ "a string" }; + + const char *charPtr = std::data(src); + int* intPtr = std::data(v); + std::cout << charPtr << ", " << *intPtr << '\n'; // a string, 10 +} ``` -## distance +```output +a string, 10 +``` + +## `distance` Determines the number of increments between the positions addressed by two iterators. @@ -351,15 +477,15 @@ typename iterator_traits::difference_type distance(InputIterator ### Parameters -*first*\ +*`first`*\ The first iterator whose distance from the second is to be determined. -*last*\ +*`last`*\ The second iterator whose distance from the first is to be determined. ### Return Value -The number of times that *first* must be incremented until it equal *last*. +The number of times that *`first`* must be incremented until it equals *`last`*. ### Remarks @@ -374,34 +500,35 @@ The distance function has constant complexity when `InputIterator` satisfies the #include #include -int main( ) +int main() { - using namespace std; - int i; - - list L; - for ( i = -1 ; i < 9 ; ++i ) - { - L.push_back ( 2 * i ); - } - list ::iterator L_Iter, LPOS = L.begin ( ); - - cout << "The list L is: ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ ) - cout << *L_Iter << " "; - cout << ")." << endl; - - cout << "The iterator LPOS initially points to the first element: " - << *LPOS << "." << endl; + using namespace std; + + list L; + for (int i = -1; i < 9; ++i) + { + L.push_back(2 * i); + } + list ::iterator L_Iter, LPOS = L.begin(); + + cout << "The list L is: ( "; + for (L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + cout << "The iterator LPOS initially points to the first element: " + << *LPOS << "." << endl; - advance ( LPOS , 7 ); - cout << "LPOS is advanced 7 steps forward to point " + advance(LPOS, 7); + cout << "LPOS is advanced 7 steps forward to point " << " to the eighth element: " << *LPOS << "." << endl; - list::difference_type Ldiff ; - Ldiff = distance ( L.begin ( ) , LPOS ); - cout << "The distance from L.begin( ) to LPOS is: " + list::difference_type Ldiff; + Ldiff = distance(L.begin(), LPOS); + cout << "The distance from L.begin( ) to LPOS is: " << Ldiff << "." << endl; } ``` @@ -413,7 +540,7 @@ LPOS is advanced 7 steps forward to point to the eighth element: 12. The distance from L.begin( ) to LPOS is: 7. ``` -## empty +## `empty` ```cpp template constexpr auto empty(const C& c) -> decltype(c.empty()); @@ -421,7 +548,51 @@ template constexpr bool empty(const T (&array)[N]) noexcept; template constexpr bool empty(initializer_list il) noexcept; ``` -## end +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +An instance of a container. + +*`E`*\ +The element type of the initializer list. + +*`il`*\ +An initializer list. + +*`N`*\ +The number of elements in the array. + +*`T`*\ +The type of the data in the array. + +### Return value + +Returns `true` if the container has no elements; otherwise `false`. + +### Example + +```cpp +#include +#include + +int main() +{ + std::vector v{ 10,20,30 }; + std::vector v2; + + std::cout << std::boolalpha << std::empty(v); // outputs false + std::cout << std::boolalpha << ", " << std::empty(v2); // outputs true +} +``` + +```output +false, true +``` + +## `end` Retrieves an iterator to the element that follows the last element in the specified container. @@ -440,10 +611,10 @@ Ty *end(Ty (& array)[Size]); ### Parameters -*cont*\ +*`cont`*\ A container. -*array*\ +*`array`*\ An array of objects of type `Ty`. ### Return Value @@ -454,25 +625,25 @@ The third template function returns `array + Size`. ### Remarks -For a code example, see [begin](../standard-library/iterator-functions.md#begin). +For a code example, see [`begin`](../standard-library/iterator-functions.md#begin). -## front_inserter +## `front_inserter` Creates an iterator that can insert elements at the front of a specified container. ```cpp template -front_insert_iterator front_inserter(Container& _Cont); +front_insert_iterator front_inserter(Container& Cont); ``` ### Parameters -*_Cont*\ +*`Cont`*\ The container object whose front is having an element inserted. ### Return Value -A `front_insert_iterator` associated with the container object *_Cont*. +A `front_insert_iterator` associated with the container object *`Cont`*. ### Remarks @@ -489,34 +660,36 @@ Within the C++ Standard Library, the argument must refer to one of the two seque #include #include -int main( ) +int main() { - using namespace std; - int i; - list ::iterator L_Iter; - - list L; - for ( i = -1 ; i < 9 ; ++i ) - { - L.push_back ( i ); - } - - cout << "The list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; - - // Using the template function to insert an element - front_insert_iterator< list < int> > Iter(L); -*Iter = 100; - - // Alternatively, you may use the front_insert member function - front_inserter ( L ) = 200; - - cout << "After the front insertions, the list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; + using namespace std; + + list L; + for (int i = -1; i < 9; ++i) + { + L.push_back(i); + } + + cout << "The list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + // Using the template function to insert an element + front_insert_iterator> Iter(L); + *Iter = 100; + + // Alternatively, you may use the front_insert member function + front_inserter(L) = 200; + + cout << "After the front insertions, the list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; } ``` @@ -527,29 +700,29 @@ After the front insertions, the list L is: ( 200 100 -1 0 1 2 3 4 5 6 7 8 ). ``` -## inserter +## `inserter` -A helper template function that lets you use `inserter(_Cont, _Where)` instead of `insert_iterator(_Cont, _Where)`. +A helper template function that lets you use `inserter(Cont, Where)` instead of `insert_iterator(Cont, Where)`. ```cpp template insert_iterator inserter( - Container& _Cont, - typename Container::iterator _Where); + Container& Cont, + typename Container::iterator Where); ``` ### Parameters -*_Cont*\ +*`Cont`*\ The container to which new elements are to be added. -*_Where*\ +*`Where`*\ An iterator locating the point of insertion. ### Remarks -The template function returns [insert_iterator](../standard-library/insert-iterator-class.md#insert_iterator)`(_Cont, _Where)`. +The template function returns [`insert_iterator`](../standard-library/insert-iterator-class.md#insert_iterator)`(Cont, Where)`. ### Example @@ -560,34 +733,36 @@ The template function returns [insert_iterator](../standard-library/insert-itera #include #include -int main( ) +int main() { - using namespace std; - int i; - list ::iterator L_Iter; - - list L; - for (i = 2 ; i < 5 ; ++i ) - { - L.push_back ( 10 * i ); - } - - cout << "The list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++ ) - cout << *L_Iter << " "; - cout << ")." << endl; - - // Using the template version to insert an element - insert_iterator > Iter( L, L.begin ( ) ); -*Iter = 1; - - // Alternatively, using the member function to insert an element - inserter ( L, L.end ( ) ) = 500; - - cout << "After the insertions, the list L is:\n ( "; - for ( L_Iter = L.begin( ) ; L_Iter != L.end( ); L_Iter++) - cout << *L_Iter << " "; - cout << ")." << endl; + using namespace std; + + list L; + for (int i = 2; i < 5; ++i) + { + L.push_back(10 * i); + } + + cout << "The list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; + + // Using the template version to insert an element + insert_iterator> Iter(L, L.begin()); + *Iter = 1; + + // Alternatively, using the member function to insert an element + inserter(L, L.end()) = 500; + + cout << "After the insertions, the list L is:\n ( "; + for (auto L_Iter = L.begin(); L_Iter != L.end(); L_Iter++) + { + cout << *L_Iter << " "; + } + cout << ")." << endl; } ``` @@ -598,7 +773,7 @@ After the insertions, the list L is: ( 1 20 30 40 500 ). ``` -## make_checked_array_iterator +## `make_checked_array_iterator` Creates a [checked_array_iterator](../standard-library/checked-array-iterator-class.md) that can be used by other algorithms. @@ -616,13 +791,13 @@ Iter Ptr, ### Parameters -*Ptr*\ +*`Ptr`*\ A pointer to the destination array. -*Size*\ +*`Size`*\ The size of the destination array. -*Index*\ +*`Index`*\ Optional index into the array. ### Return Value @@ -652,10 +827,12 @@ In the following example, a [vector](../standard-library/vector-class.md) is cre using namespace std; -template void print(const string& s, const C& c) { +template void print(const string& s, const C& c) +{ cout << s; - for (const auto& e : c) { + for (const auto& e : c) + { cout << e << " "; } @@ -672,7 +849,8 @@ int main() vector v; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { v.push_back(i); } print("vector v: ", v); @@ -680,38 +858,40 @@ int main() copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size)); cout << "int array dest: "; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { cout << dest[i] << " "; } cout << endl; // Add another element to the vector to force an overrun. v.push_back(10); - // The next line causes a debug assertion when it executes. + + // ! The next line causes a debug assertion when it executes. copy(v.begin(), v.end(), stdext::make_checked_array_iterator(dest, dest_size)); } ``` -## make_move_iterator +## `make_move_iterator` Creates a `move iterator` that contains the provided iterator as the `stored` iterator. ```cpp template move_iterator -make_move_iterator(const Iterator& _It); +make_move_iterator(const Iterator& It); ``` ### Parameters -*_It*\ +*`It`*\ The iterator stored in the new move iterator. ### Remarks The template function returns `move_iterator` `(_It)`. -## make_unchecked_array_iterator +## `make_unchecked_array_iterator` Creates an [unchecked_array_iterator](../standard-library/unchecked-array-iterator-class.md) that can be used by other algorithms. @@ -726,7 +906,7 @@ unchecked_array_iterator ### Parameters -*Ptr*\ +*`Ptr`*\ A pointer to the destination array. ### Return Value @@ -755,10 +935,12 @@ In the following example, a [vector](../standard-library/vector-class.md) is cre using namespace std; -template void print(const string& s, const C& c) { +template void print(const string& s, const C& c) +{ cout << s; - for (const auto& e : c) { + for (const auto& e : c) + { cout << e << " "; } @@ -768,10 +950,11 @@ template void print(const string& s, const C& c) { int main() { const size_t dest_size = 10; - int *dest = new int[dest_size]; + int* dest = new int[dest_size]; vector v; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { v.push_back(i); } print("vector v: ", v); @@ -781,7 +964,8 @@ int main() copy(v.begin(), v.end(), stdext::make_unchecked_array_iterator(dest)); cout << "int array dest: "; - for (int i = 0; i < dest_size; ++i) { + for (int i = 0; i < dest_size; ++i) + { cout << dest[i] << " "; } cout << endl; @@ -790,7 +974,12 @@ int main() } ``` -## next +```output +vector v: 0 1 2 3 4 5 6 7 8 9 +int array dest: 0 1 2 3 4 5 6 7 8 9 +``` + +## `next` Iterates a specified number of times and returns the new iterator position. @@ -798,26 +987,26 @@ Iterates a specified number of times and returns the new iterator position. template InputIterator next( InputIterator first, - typename iterator_traits::difference_type _Off = 1); + typename iterator_traits::difference_type off = 1); ``` ### Parameters -*first*\ +*`first`*\ The current position. -*_Off*\ +*`off`*\ The number of times to iterate. ### Return Value -Returns the new iterator position after iterating *_Off* times. +Returns the new iterator position after iterating *`off`* times. ### Remarks -The template function returns `next` incremented *_Off* times +The template function returns `next` incremented *`off`* times -## prev +## `prev` Iterates in reverse a specified number of times and returns the new iterator position. @@ -825,38 +1014,147 @@ Iterates in reverse a specified number of times and returns the new iterator pos template BidirectionalIterator prev( BidirectionalIterator first, - typename iterator_traits::difference_type _Off = 1); + typename iterator_traits::difference_type off = 1); ``` ### Parameters -*first*\ +*`first`*\ The current position. -*_Off*\ +*`off`*\ The number of times to iterate. ### Remarks The template function returns `next` decremented `off` times. -## rbegin +## `rbegin` + +Get an iterator, which returns the elements of the container in reverse order. ```cpp template constexpr auto rbegin(C& c) -> decltype(c.rbegin()); template constexpr auto rbegin(const C& c) -> decltype(c.rbegin()); ``` -## rend +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +The returned iterator presents the elements of the container in reverse order, starting at the end of the reversed range. + +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: + +### Example `rbegin` ```cpp -template constexpr auto rend(C& c) -> decltype(c.rend()); +#include +#include + +int main() +{ + std::vector v{ 10, 20, 30 }; + + for (auto e = std::rbegin(v); e != std::rend(v); ++e) + { + std::cout << *e << ' '; // outputs 30 20 10 + } +} +``` + +```output +30 20 10 +``` + +## `rend` + +Get the sentinel at the end of a reversed sequence of elements. + +```cpp +template constexpr auto rend(C& c)-> decltype(c.rend()); template constexpr auto rend(const C& c) -> decltype(c.rend()); ``` -## size +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +A container instance. + +### Return value + +A reverse iterator to the sentinel at the end of the container. The sentinel follows the last element in the reversed view of the container: + +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: + +### `rend` example + +```cpp +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + auto vi = std::rend(v); + --vi; // get off the sentinel and onto the last element in the reversed range + std::cout << *vi; // outputs 10 +} +``` + +```output +10 +``` + +## `size` ```cpp -template constexpr auto size(const C& c) -> decltype(c.size()); +template constexpr auto size(const C& c) + -> decltype(c.size()); template constexpr size_t size(const T (&array)[N]) noexcept; ``` + +### Parameters + +*`C`*\ +The type of the container. + +*`c`*\ +An instance of a container. + +*`N`*\ +The number of elements in the array. + +*`T`*\ +The type of the data in the array. + +### Return value + +The number of elements in the container as an unsigned integer-like value. + +### Example `size` + +```cpp +#include +#include + +int main() +{ + std::vector v{ 10, 20, 30 }; + size_t s = std::size(v); + std::cout << s; // outputs 3 +} +``` + +```output +3 +``` \ No newline at end of file diff --git a/docs/standard-library/iterator-operators.md b/docs/standard-library/iterator-operators.md index 800e404386c..27086c18f8b 100644 --- a/docs/standard-library/iterator-operators.md +++ b/docs/standard-library/iterator-operators.md @@ -1,16 +1,15 @@ --- -description: "Learn more about: operators" title: " operators" -ms.date: "11/04/2016" +description: "Learn more about: operators" +ms.date: 09/30/2022 f1_keywords: ["xutility/std::operator!=", "xutility/std::operator>", "xutility/std::operator>=", "xutility/std::operator<", "xutility/std::operator<=", "xutility/std::operator+", "xutility/std::operator-", "xutility/std::operator=="] -ms.assetid: b7c664f0-49d4-4993-b5d1-9ac4859fdddc helpviewer_keywords: ["std::operator!= (iterator)", "std::operator> (iterator)", "std::operator>= (iterator)", "std::operator< (iterator)", "std::operator<= (iterator), std::operator== (iterator)"] --- # `` operators -## operator!= +## `operator!=` -Tests if the iterator object on the left side of the operator is not equal to the iterator object on the right side. +Tests if the iterator object on the left side of the operator isn't equal to the iterator object on the right side. ```cpp template @@ -25,69 +24,76 @@ bool operator!=(const istreambuf_iterator& left, const istream ### Parameters -*left*\ +*`left`*\ An object of type `iterator`. -*right*\ +*`right`*\ An object of type `iterator`. ### Return Value -**`true`** if the iterator objects are not equal; **`false`** if the iterator objects are equal. +**`true`** if the iterator objects aren't equal; **`false`** if the iterator objects are equal. ### Remarks -One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they are not equal. +One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they aren't equal. ### Example ```cpp -// iterator_op_ne.cpp +/// iterator_op_ne.cpp // compile with: /EHsc #include #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 1 ; i < 9 ; ++i ) - { - vec.push_back ( i ); - } - - vector ::iterator vIter; - - cout << "The vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++ ) - cout << *vIter << " "; - cout << ")." << endl; - - // Initializing reverse_iterators to the last element - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to the first " + using namespace std; + + vector vec; + for (int i = 1; i < 9; ++i) + { + vec.push_back(i); + } + + cout << "The vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Initializing reverse_iterators to the last element + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to the first " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 != rVPOS2 ) - cout << "The iterators are not equal." << endl; - else - cout << "The iterators are equal." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " + if (rVPOS1 != rVPOS2) + { + cout << "The iterators are not equal." << endl; + } + else + { + cout << "The iterators are equal." << endl; + } + + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 != rVPOS2 ) - cout << "The iterators are not equal." << endl; - else - cout << "The iterators are equal." << endl; + if (rVPOS1 != rVPOS2) + { + cout << "The iterators are not equal." << endl; + } + else + { + cout << "The iterators are equal." << endl; + } } ``` @@ -101,7 +107,7 @@ in the reversed sequence: 7. The iterators are not equal. ``` -## operator== +## `operator==` Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side. @@ -129,21 +135,21 @@ bool operator==( ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator objects are equal; **`false`** if the iterator objects are not equal. +**`true`** if the iterator objects are equal; **`false`** if the iterator objects aren't equal. ### Remarks -One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they are not equal. +One iterator object is equal to another if they address the same elements in a container. If two iterators point to different elements in a container, then they aren't equal. -The first two template operators return true only if both *left* and *right* store the same iterator. The third template operator returns true only if both *left* and *right* store the same stream pointer. The fourth template operator returns `left.equal (right)`. +The first two template operators return true only if both *`left`* and *`right`* store the same iterator. The third template operator returns true only if both *`left`* and *`right`* store the same stream pointer. The fourth template operator returns `left.equal (right)`. ### Example @@ -154,46 +160,53 @@ The first two template operators return true only if both *left* and *right* sto #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 1 ; i < 6 ; ++i ) - { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - // Initializing reverse_iterators to the last element - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to the first " + using namespace std; + + vector vec; + for (int i = 1; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Initializing reverse_iterators to the last element + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to the first " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 == rVPOS2 ) - cout << "The iterators are equal." << endl; - else - cout << "The iterators are not equal." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " + if (rVPOS1 == rVPOS2) + { + cout << "The iterators are equal." << endl; + } + else + { + cout << "The iterators are not equal." << endl; + } + + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " << "element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - if ( rVPOS1 == rVPOS2 ) - cout << "The iterators are equal." << endl; - else - cout << "The iterators are not equal." << endl; + if (rVPOS1 == rVPOS2) + { + cout << "The iterators are equal." << endl; + } + else + { + cout << "The iterators are not equal." << endl; + } } ``` @@ -218,19 +231,19 @@ bool operator<(const reverse_iterator& left, const reverse_itera ### Parameters -*left*\ +*`left`*\ An object of type `iterator`. -*right*\ +*`right`*\ An object of type `iterator`. ### Return Value -**`true`** if the iterator on the left side of the expression is less than the iterator on the right side of the expression; **`false`** if it is greater than or equal to the iterator on the right. +**`true`** if the iterator on the left side of the expression is less than the iterator on the right side of the expression; **`false`** if it's greater than or equal to the iterator on the right. ### Remarks -One iterator object is less than another if it addresses an element that occurs earlier in the container than the element addressed by the other iterator object. One iterator object is not less than another if it addresses either the same element as the other iterator object or an element that occurs later in the container than the element addressed by the other iterator object. +One iterator object is less than another if it addresses an element that occurs earlier in the container than the element addressed by the other iterator object. One iterator object isn't less than another if it addresses either the same element as the other iterator object or an element that occurs later in the container than the element addressed by the other iterator object. ### Example @@ -241,50 +254,57 @@ One iterator object is less than another if it addresses an element that occurs #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for ( i = 0 ; i < 6 ; ++i ) - { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - // Initializing reverse_iterators to the last element - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterators rVPOS1& rVPOS2 initially point to the " - << "first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 < rVPOS2 ) - cout << "The iterator rVPOS1 is less than" - << " the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is not less than" - << " the iterator rVPOS2." << endl; - - rVPOS2++; - cout << "The iterator rVPOS2 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 < rVPOS2 ) - cout << "The iterator rVPOS1 is less than" - << " the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is not less than" - << " the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + // Initializing reverse_iterators to the last element + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterators rVPOS1& rVPOS2 initially point to the " + << "first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 < rVPOS2) + { + cout << "The iterator rVPOS1 is less than" + << " the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is not less than" + << " the iterator rVPOS2." << endl; + + rVPOS2++; + cout << "The iterator rVPOS2 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 < rVPOS2) + { + cout << "The iterator rVPOS1 is less than" + << " the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is not less than" + << " the iterator rVPOS2." << endl; + } + } } ``` @@ -309,15 +329,15 @@ bool operator<=(const reverse_iterator& left, const reverse_iter ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator on the left side of the expression is less than or equal to the iterator on the right side of the expression; **`false`** if it is greater than the iterator on the right. +**`true`** if the iterator on the left side of the expression is less than or equal to the iterator on the right side of the expression; **`false`** if it's greater than the iterator on the right. ### Remarks @@ -332,52 +352,60 @@ One iterator object is less than or equal to another if it addresses the same el #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ) + 1, - rVPOS2 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to the " - << "second element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - cout << "The iterator rVPOS2 initially points to the " - << "first element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 <= rVPOS2 ) - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; - - rVPOS2++; - cout << "The iterator rVPOS2 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 <= rVPOS2 ) - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin() + 1, + rVPOS2 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to the " + << "second element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + cout << "The iterator rVPOS2 initially points to the " + << "first element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 <= rVPOS2) + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } + + rVPOS2++; + cout << "The iterator rVPOS2 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 <= rVPOS2) + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } } ``` @@ -404,19 +432,19 @@ bool operator>(const reverse_iterator& left, const reverse_itera ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator on the left side of the expression is greater than the iterator on the right side of the expression; **`false`** if it is less than or equal to the iterator on the right. +**`true`** if the iterator on the left side of the expression is greater than the iterator on the right side of the expression; **`false`** if it's less than or equal to the iterator on the right. ### Remarks -One iterator object is greater than another if it addresses an element that occurs later in the container than the element addressed by the other iterator object. One iterator object is not greater than another if it addresses either the same element as the other iterator object or an element that occurs earlier in the container than the element addressed by the other iterator object. +One iterator object is greater than another if it addresses an element that occurs later in the container than the element addressed by the other iterator object. One iterator object isn't greater than another if it addresses either the same element as the other iterator object or an element that occurs earlier in the container than the element addressed by the other iterator object. ### Example @@ -427,48 +455,55 @@ One iterator object is greater than another if it addresses an element that occu #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); - - cout << "The iterators rVPOS1 & rVPOS2 initially point to " - << "the first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 > rVPOS2 ) - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 > rVPOS2 ) - cout << "The iterator rVPOS1 is greater than " - << "the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than or " - << "equal to the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); + + cout << "The iterators rVPOS1 & rVPOS2 initially point to " + << "the first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 > rVPOS2) + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } + + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 > rVPOS2) + { + cout << "The iterator rVPOS1 is greater than " + << "the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than or " + << "equal to the iterator rVPOS2." << endl; + } } ``` @@ -493,15 +528,15 @@ bool operator>=(const reverse_iterator& left, const reverse_iter ### Parameters -*left*\ +*`left`*\ An object of type iterator. -*right*\ +*`right`*\ An object of type iterator. ### Return Value -**`true`** if the iterator on the left side of the expression is greater than or equal to the iterator on the right side of the expression; **`false`** if it is less than the iterator on the right. +**`true`** if the iterator on the left side of the expression is greater than or equal to the iterator on the right side of the expression; **`false`** if it's less than the iterator on the right. ### Remarks @@ -516,52 +551,59 @@ One iterator object is greater than or equal to another if it addresses the same #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ) + 1; - - cout << "The iterator rVPOS1 initially points to the " - << "first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - cout << "The iterator rVPOS2 initially points to the " - << "second element\n in the reversed sequence: " - << *rVPOS2 << "." << endl; - - if ( rVPOS1 >= rVPOS2 ) - cout << "The iterator rVPOS1 is greater than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than " - << "the iterator rVPOS2." << endl; - - rVPOS1++; - cout << "The iterator rVPOS1 now points to the second " - << "element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; - - if ( rVPOS1 >= rVPOS2 ) - cout << "The iterator rVPOS1 is greater than or " - << "equal to the iterator rVPOS2." << endl; - else - cout << "The iterator rVPOS1 is less than " - << "the iterator rVPOS2." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin() + 1; + + cout << "The iterator rVPOS1 initially points to the " + << "first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + cout << "The iterator rVPOS2 initially points to the " + << "second element\n in the reversed sequence: " + << *rVPOS2 << "." << endl; + + if (rVPOS1 >= rVPOS2) + { + cout << "The iterator rVPOS1 is greater than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than " + << "the iterator rVPOS2." << endl; + } + rVPOS1++; + cout << "The iterator rVPOS1 now points to the second " + << "element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; + + if (rVPOS1 >= rVPOS2) + { + cout << "The iterator rVPOS1 is greater than or " + << "equal to the iterator rVPOS2." << endl; + } + else + { + cout << "The iterator rVPOS1 is less than " + << "the iterator rVPOS2." << endl; + } } ``` @@ -577,7 +619,7 @@ in the reversed sequence: 8. The iterator rVPOS1 is greater than or equal to the iterator rVPOS2. ``` -## operator+ +## `operator+` Adds an offset to an iterator and returns a `move_iterator` or a `reverse_iterator` addressing the inserted element at the new offset position. @@ -597,15 +639,15 @@ operator+( ### Parameters -*_Off*\ +*`Off`*\ The number of positions the const move_iterator or const reverse_iterator is to be offset. -*right*\ +*`right`*\ The iterator to be offset. ### Return Value -Returns the sum *right* + *_Off*. +Returns the sum *`right`* + *`Off`*. ### Example @@ -616,35 +658,35 @@ Returns the sum *right* + *_Off*. #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) { - vec.push_back ( 2 * i ); - } - - vector ::iterator vIter; - - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; - - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ); - - cout << "The iterator rVPOS1 initially points to " - << "the first element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; + using namespace std; + + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } + + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; + + vector ::reverse_iterator rVPOS1 = vec.rbegin(); + + cout << "The iterator rVPOS1 initially points to " + << "the first element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; - vector::difference_type diff = 4; - rVPOS1 = diff +rVPOS1; + vector::difference_type diff = 4; + rVPOS1 = diff + rVPOS1; - cout << "The iterator rVPOS1 now points to the fifth " - << "element\n in the reversed sequence: " - << *rVPOS1 << "." << endl; + cout << "The iterator rVPOS1 now points to the fifth " + << "element\n in the reversed sequence: " + << *rVPOS1 << "." << endl; } ``` @@ -656,7 +698,7 @@ The iterator rVPOS1 now points to the fifth element in the reversed sequence: 2. ``` -## operator- +## `operator-` Subtracts one iterator from another and returns the difference. @@ -674,15 +716,15 @@ Tdiff operator-( ### Parameters -*left*\ +*`left`*\ An iterator. -*right*\ +*`right`*\ An iterator. ### Return Value -The difference between two iterators `.` +The difference between two iterators. ### Remarks @@ -690,7 +732,7 @@ The first template operator returns `left.base() - right.base()`. The second template operator returns `right.current - left.current`. -`Tdiff` is determined by the type of the returned expression. Otherwise, it is `RandomIterator1::difference_type`. +`Tdiff` is determined by the type of the returned expression. Otherwise, it's `RandomIterator1::difference_type`. ### Example @@ -701,41 +743,41 @@ The second template operator returns `right.current - left.current`. #include #include -int main( ) +int main() { - using namespace std; - int i; - - vector vec; - for (i = 0 ; i < 6 ; ++i ) - { - vec.push_back ( 2 * i ); - } + using namespace std; - vector ::iterator vIter; + vector vec; + for (int i = 0; i < 6; ++i) + { + vec.push_back(2 * i); + } - cout << "The initial vector vec is: ( "; - for ( vIter = vec.begin( ) ; vIter != vec.end( ); vIter++) - cout << *vIter << " "; - cout << ")." << endl; + cout << "The initial vector vec is: ( "; + for (vector ::iterator vIter = vec.begin(); vIter != vec.end(); vIter++) + { + cout << *vIter << " "; + } + cout << ")." << endl; - vector ::reverse_iterator rVPOS1 = vec.rbegin ( ), - rVPOS2 = vec.rbegin ( ); + vector ::reverse_iterator rVPOS1 = vec.rbegin(), + rVPOS2 = vec.rbegin(); - cout << "The iterators rVPOS1 & rVPOS2 initially point to " + cout << "The iterators rVPOS1 & rVPOS2 initially point to " << "the first element\n in the reversed sequence: " << *rVPOS1 << "." << endl; - for (i = 1; i < 5; ++i) - { - rVPOS2++; - } - cout << "The iterator rVPOS2 now points to the fifth " + for (int i = 1; i < 5; ++i) + { + rVPOS2++; + } + + cout << "The iterator rVPOS2 now points to the fifth " << "element\n in the reversed sequence: " << *rVPOS2 << "." << endl; - vector::difference_type diff = rVPOS2 - rVPOS1; - cout << "The difference: rVPOS2 - rVPOS1= " + vector::difference_type diff = rVPOS2 - rVPOS1; + cout << "The difference: rVPOS2 - rVPOS1= " << diff << "." << endl; } ``` diff --git a/docs/standard-library/iterator-traits-struct.md b/docs/standard-library/iterator-traits-struct.md index 7e027f479c5..b47a2146074 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" -ms.date: "11/04/2016" +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`. @@ -89,7 +88,7 @@ function( it i1, it i2 ) x = *i1; cout << x << " "; i1++; - }; + } cout << endl; }; diff --git a/docs/standard-library/iterator.md b/docs/standard-library/iterator.md index 6c368dae392..f5ac9540c1b 100644 --- a/docs/standard-library/iterator.md +++ b/docs/standard-library/iterator.md @@ -1,38 +1,27 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 12/14/2022 f1_keywords: [""] helpviewer_keywords: ["iterator header"] -ms.assetid: c61a3962-f3ed-411a-b5a3-e8b3c2b500bd --- # `` -Defines the iterator primitives, predefined iterators and stream iterators, as well as several supporting templates. The predefined iterators include insert and reverse adaptors. There are three classes of insert iterator adaptors: front, back, and general. They provide insert semantics rather than the overwrite semantics that the container member function iterators provide. +Defines predefined iterators and stream iterators, iterator primitives, and supporting templates. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## Remarks -Iterators are a generalization of pointers, abstracting from their requirements in a way that allows a C++ program to work with different data structures in a uniform manner. Iterators act as intermediaries between containers and generic algorithms. Instead of operating on specific data types, algorithms are defined to operate on a range specified by a type of iterator. Any data structure that satisfies the requirements of the iterator may then be operated on by the algorithm. There are five types or categories of iterator, each with its own set of requirements and resulting functionality: - -- Output: forward moving, may store but not retrieve values, provided by ostream and inserter. - -- Input: forward moving, may retrieve but not store values, provided by istream. - -- Forward: forward moving, may store and retrieve values. - -- Bidirectional: forward and backward moving, may store and retrieve values, provided by list, set, multiset, map, and multimap. - -- Random access: elements accessed in any order, may store and retrieve values, provided by vector, deque, string, and array. +Iterators are a generalization of pointers that allow a C++ program to work with different data structures in a uniform way. Instead of operating on specific data types, algorithms operate on a range of values as specified by a kind of iterator. Algorithms can operate on any data structure that satisfies the requirements of the iterator. -Iterators that have greater requirements and so more powerful access to elements may be used in place of iterators with fewer requirements. For example, if a forward iterator is called for, then a random-access iterator may used instead. +In C++20, there are six categories of iterators. Iterators are arranged in a hierarchy of capability. Their capabilities are specified by C++20 concepts. For a description of the various iterators and their capabilities, see [Iterator concepts](iterator-concepts.md) -Visual Studio has added extensions to C++ Standard Library iterators to support a variety of debug mode situations for checked and unchecked iterators. For more information, see [Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md). +Visual Studio has added extensions to C++ Standard Library iterators to support debugging for checked and unchecked iterators. For more information, see [Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md). ## Members @@ -40,63 +29,79 @@ Visual Studio has added extensions to C++ Standard Library iterators to support |Name|Description| |-|-| -|[advance](../standard-library/iterator-functions.md#advance)|Increments an iterator by a specified number of positions.| -|[back_inserter](../standard-library/iterator-functions.md#back_inserter)|Creates an iterator that can insert elements at the back of a specified container.| -|[begin](../standard-library/iterator-functions.md#begin)|Retrieves an iterator to the first element in a specified container.| -|[cbegin](../standard-library/iterator-functions.md#cbegin)|Retrieves a constant iterator to the first element in a specified container.| -|[cend](../standard-library/iterator-functions.md#cend)|Retrieves a constant iterator to the element that follows the last element in the specified container.| -|[crbegin](../standard-library/iterator-functions.md#crbegin)|| -|[crend](../standard-library/iterator-functions.md#crend)|| -|[data](../standard-library/iterator-functions.md#data)|| -|[distance](../standard-library/iterator-functions.md#distance)|Determines the number of increments between the positions addressed by two iterators.| -|[end](../standard-library/iterator-functions.md#end)|Retrieves an iterator to the element that follows the last element in the specified container.| -|[empty](../standard-library/iterator-functions.md#empty)|| -|[front_inserter](../standard-library/iterator-functions.md#front_inserter)|Creates an iterator that can insert elements at the front of a specified container.| -|[inserter](../standard-library/iterator-functions.md#inserter)|An iterator adaptor that adds a new element to a container at a specified point of insertion.| -|[make_checked_array_iterator](../standard-library/iterator-functions.md#make_checked_array_iterator)|Creates a [checked_array_iterator](../standard-library/checked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| -|[make_move_iterator](../standard-library/iterator-functions.md#make_move_iterator)|Returns a move iterator containing the provided iterator as its stored base iterator.| -|[make_unchecked_array_iterator](../standard-library/iterator-functions.md#make_unchecked_array_iterator)|Creates an [unchecked_array_iterator](../standard-library/unchecked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| -|[next](../standard-library/iterator-functions.md#next)|Iterates a specified number of times and returns the new iterator position.| -|[prev](../standard-library/iterator-functions.md#prev)|Iterates in reverse a specified number of times and returns the new iterator position.| -|[rbegin](../standard-library/iterator-functions.md#rbegin)|| -|[rend](../standard-library/iterator-functions.md#rend)|| -|[size](../standard-library/iterator-functions.md#size)|| +|[`advance`](../standard-library/iterator-functions.md#advance)|Increments an iterator by a specified number of positions.| +|[`back_inserter`](../standard-library/iterator-functions.md#back_inserter)|Creates an iterator that can insert elements at the back of a specified container.| +|[`begin`](../standard-library/iterator-functions.md#begin)|Retrieves an iterator to the first element in a specified container.| +|[`cbegin`](../standard-library/iterator-functions.md#cbegin)|Retrieves a read-only iterator to the first element in a specified container.| +|[`cend`](../standard-library/iterator-functions.md#cend)|Retrieves a read-only iterator to the element that follows the last element in the specified container.| +|[`crbegin`](../standard-library/iterator-functions.md#crbegin)| Get a reverse read-only iterator to the beginning of the specified container.| +|[`crend`](../standard-library/iterator-functions.md#crend)| Get the sentinel at the end of what `crbegin()` returns.| +|[`data`](../standard-library/iterator-functions.md#data)| Get a pointer to the first element in the specified container.| +|[`distance`](../standard-library/iterator-functions.md#distance)|Determines the number of increments between the positions addressed by two iterators.| +|[`end`](../standard-library/iterator-functions.md#end)|Retrieves an iterator to the element that follows the last element in the specified container.| +|[`empty`](../standard-library/iterator-functions.md#empty)| Test if the specified container is empty.| +|[`front_inserter`](../standard-library/iterator-functions.md#front_inserter)|Creates an iterator that can insert elements at the front of a specified container.| +|[`inserter`](../standard-library/iterator-functions.md#inserter)|An iterator adaptor that adds a new element to a container at a specified point of insertion.| +|[`make_checked_array_iterator`](../standard-library/iterator-functions.md#make_checked_array_iterator)|Creates a [`checked_array_iterator`](../standard-library/checked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| +|[`make_move_iterator`](../standard-library/iterator-functions.md#make_move_iterator)|Returns a move iterator containing the provided iterator as its stored base iterator.| +|[`make_unchecked_array_iterator`](../standard-library/iterator-functions.md#make_unchecked_array_iterator)|Creates an [`unchecked_array_iterator`](../standard-library/unchecked-array-iterator-class.md) that can be used by other algorithms. **Note:** This function is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| +|[`next`](../standard-library/iterator-functions.md#next)|Iterates a specified number of times and returns the new iterator position.| +|[`prev`](../standard-library/iterator-functions.md#prev)|Iterates in reverse a specified number of times and returns the new iterator position.| +|[`rbegin`](../standard-library/iterator-functions.md#rbegin)|Get a reverse iterator to the beginning of the specified container. | +|[`rend`](../standard-library/iterator-functions.md#rend)| Get a reverse iterator to the sentinel at the end of the specified container.| +|[`size`](../standard-library/iterator-functions.md#size)| Get the number of elements.| ### Operators |Name|Description| |-|-| -|[operator!=](../standard-library/iterator-operators.md#op_neq)|Tests if the iterator object on the left side of the operator is not equal to the iterator object on the right side.| -|[operator==](../standard-library/iterator-operators.md#op_eq_eq)|Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side.| -|[operator<](../standard-library/iterator-operators.md#op_lt)|Tests if the iterator object on the left side of the operator is less than the iterator object on the right side.| -|[operator\<=](../standard-library/iterator-operators.md#op_gt_eq)|Tests if the iterator object on the left side of the operator is less than or equal to the iterator object on the right side.| -|[operator>](../standard-library/iterator-operators.md#op_gt)|Tests if the iterator object on the left side of the operator is greater than the iterator object on the right side.| -|[operator>=](../standard-library/iterator-operators.md#op_gt_eq)|Tests if the iterator object on the left side of the operator is greater than or equal to the iterator object on the right side.| -|[operator+](../standard-library/iterator-operators.md#op_add)|Adds an offset to an iterator and returns the new `reverse_iterator` addressing the inserted element at the new offset position.| -|[operator-](../standard-library/iterator-operators.md#operator-)|Subtracts one iterator from another and returns the difference.| +|[`operator!=`](../standard-library/iterator-operators.md#op_neq)|Tests if the iterator object on the left side of the operator isn't equal to the iterator object on the right side.| +|[`operator==`](../standard-library/iterator-operators.md#op_eq_eq)|Tests if the iterator object on the left side of the operator is equal to the iterator object on the right side.| +|[`operator<`](../standard-library/iterator-operators.md#op_lt)|Tests if the iterator object on the left side of the operator is less than the iterator object on the right side.| +|[`operator<=`](../standard-library/iterator-operators.md#op_lt_eq)|Tests if the iterator object on the left side of the operator is less than or equal to the iterator object on the right side.| +|[`operator>`](../standard-library/iterator-operators.md#op_gt)|Tests if the iterator object on the left side of the operator is greater than the iterator object on the right side.| +|[`operator>=`](../standard-library/iterator-operators.md#op_gt_eq)|Tests if the iterator object on the left side of the operator is greater than or equal to the iterator object on the right side.| +|[`operator+`](../standard-library/iterator-operators.md#op_add)|Adds an offset to an iterator and returns the new `reverse_iterator` addressing the inserted element at the new offset position.| +|[`operator-`](../standard-library/iterator-operators.md#operator-)|Subtracts one iterator from another and returns the difference.| ### Classes |Name|Description| |-|-| -|[back_insert_iterator](../standard-library/back-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| -|[bidirectional_iterator_tag](../standard-library/bidirectional-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a bidirectional iterator.| -|[checked_array_iterator](../standard-library/checked-array-iterator-class.md)|A class that accesses an array using a random access, checked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| -|[forward_iterator_tag](../standard-library/forward-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a forward iterator.| -|[front_insert_iterator](../standard-library/front-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| -|[input_iterator_tag](../standard-library/input-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents an input iterator.| -|[insert_iterator](../standard-library/insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container. It also stores the protected `iterator` object, of class `Container::iterator`, called `iter`.| -|[istream_iterator](../standard-library/istream-iterator-class.md)|The class template describes an input iterator object. It extracts objects of class `Ty` from an input stream, which it accesses through an object it stores, of type pointer to `basic_istream`\<**Elem**, **Tr**>.| -|[istreambuf_iterator](../standard-library/istreambuf-iterator-class.md)|The class template describes an input iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type `pointer` to `basic_streambuf`\<**Elem**, **Tr**>.| -|[iterator](../standard-library/iterator-struct.md)|The class template is used as a base type for all iterators.| -|[iterator_traits](../standard-library/iterator-traits-struct.md)|A template helper class providing critical types that are associated with different iterator types so that they can be referred to in the same way.| -|[move_iterator](../standard-library/move-iterator-class.md)|A `move_iterator` object stores a random-access iterator of type `RandomIterator`. It behaves like a random-access iterator, except when dereferenced. The result of `operator*` is implicitly cast to `value_type&&:` to make an `rvalue reference`.| -|[ostream_iterator](../standard-library/ostream-iterator-class.md)|The class template describes an output iterator object. It inserts objects of class `Type` into an output stream, which it accesses through an object it stores, of type `pointer` to `basic_ostream`\<**Elem**, **Tr**>.| -|[ostreambuf_iterator Class](../standard-library/ostreambuf-iterator-class.md)|The class template describes an output iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type pointer to `basic_streambuf`\<**Elem**, **Tr**>.| -|[output_iterator_tag](../standard-library/output-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents an output iterator.| -|[random_access_iterator_tag](../standard-library/random-access-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents a random-access iterator.| -|[reverse_iterator](../standard-library/reverse-iterator-class.md)|The class template describes an object that behaves like a random-access iterator, only in reverse.| -|[unchecked_array_iterator](../standard-library/unchecked-array-iterator-class.md)|A class that accesses an array using a random access, unchecked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function is not portable to C++ Standard build environments that do not support this Microsoft extension.| +|[`back_insert_iterator`](../standard-library/back-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| +|[`bidirectional_iterator_tag`](../standard-library/bidirectional-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a bidirectional iterator.| +|[`checked_array_iterator`](../standard-library/checked-array-iterator-class.md)|A class that accesses an array using a random access, checked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| +|[`forward_iterator_tag`](../standard-library/forward-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents a forward iterator.| +|[`front_insert_iterator`](../standard-library/front-insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container.| +|[`input_iterator_tag`](../standard-library/input-iterator-tag-struct.md)|A class that provides a return type for an `iterator_category` function that represents an input iterator.| +|[`insert_iterator`](../standard-library/insert-iterator-class.md)|The class template describes an output iterator object. It inserts elements into a container of type `Container`, which it accesses through the protected `pointer` object it stores called container. It also stores the protected `iterator` object, of class `Container::iterator`, called `iter`.| +|[`istream_iterator`](../standard-library/istream-iterator-class.md)|The class template describes an input iterator object. It extracts objects of class `Ty` from an input stream, which it accesses through an object it stores, of type pointer to `basic_istream`.| +|[`istreambuf_iterator`](../standard-library/istreambuf-iterator-class.md)|The class template describes an input iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type `pointer` to `basic_streambuf`.| +|[`iterator`](../standard-library/iterator-struct.md)|The class template is used as a base type for all iterators.| +|[`iterator_traits`](../standard-library/iterator-traits-struct.md)|A template helper class providing critical types that are associated with different iterator types so that they can be referred to in the same way.| +|[`move_iterator`](../standard-library/move-iterator-class.md)|A `move_iterator` object stores a random-access iterator of type `RandomIterator`. It behaves like a random-access iterator, except when dereferenced. The result of `operator*` is implicitly cast to `value_type&&:` to make an `rvalue reference`.| +|[`ostream_iterator`](../standard-library/ostream-iterator-class.md)|The class template describes an output iterator object. It inserts objects of class `Type` into an output stream, which it accesses through an object it stores, of type `pointer` to `basic_ostream`.| +|[`ostreambuf_iterator`](../standard-library/ostreambuf-iterator-class.md)|The class template describes an output iterator object. It inserts elements of class `Elem` into an output stream buffer, which it accesses through an object it stores, of type pointer to `basic_streambuf`.| +|[`output_iterator_tag`](../standard-library/output-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents an output iterator.| +|[`random_access_iterator_tag`](../standard-library/random-access-iterator-tag-struct.md)|A class that provides a return type for `iterator_category` function that represents a random-access iterator.| +|[`reverse_iterator`](../standard-library/reverse-iterator-class.md)|The class template describes an object that behaves like a random-access iterator, only in reverse.| +|[`unchecked_array_iterator`](../standard-library/unchecked-array-iterator-class.md)|A class that accesses an array using a random access, unchecked iterator. **Note:** This class is a Microsoft extension of the C++ Standard Library. Code implemented by using this function isn't portable to C++ Standard build environments that don't support this Microsoft extension.| + +## Concepts + +The following concepts are defined in the `std` namespace. They apply to iterators, and are also related to the iterator categories for ranges described in [`` concepts](range-concepts.md). + +| Iterator concept | Description | +|--|--| +| [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator)C++20 | Specifies an iterator that can read and write both forwards and backwards. | +| [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator)C++20 | Specifies an iterator whose elements are sequential in memory, the same size, and can be accessed using pointer arithmetic. | +| [`forward_iterator`](iterator-concepts.md#forward_iterator)C++20 | Specifies an iterator that can read (and possibly write) multiple times. | +| [`input_iterator`](iterator-concepts.md#input_iterator)C++20 | Specifies an iterator that you can read from at least once. | +| [`input_or_output_iterator`](iterator-concepts.md#input_or_output_iterator)C++20 | The basis of the iterator concept taxonomy. | +| [`output_iterator`](iterator-concepts.md#output_iterator) | Specifies an iterator that you can write to. | +| [`random_access_iterator`](iterator-concepts.md#random_access_iterator)C++20 | Specifies an iterator that you can read and write by index. | +| [`sentinel_for`](iterator-concepts.md#sentinel_for)C++20 | Specifies a sentinel for an iterator type. | +| [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for)C++20 | Specifies that an iterator and its sentinel can be subtracted (using `-`) to find their difference in constant time. | ## See also diff --git a/docs/standard-library/join-view-class.md b/docs/standard-library/join-view-class.md new file mode 100644 index 00000000000..0f94798f81d --- /dev/null +++ b/docs/standard-library/join-view-class.md @@ -0,0 +1,182 @@ +--- +title: join_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) join_view class, which combines the elements of multiple ranges into a single view." +ms.date: 09/28/2022 +f1_keywords: ["ranges/std::join_view", "ranges/std::join_view::base", "ranges/std::join_view::begin", "ranges/std::join_view::end", "ranges/std::join_view::empty", "ranges/std::join_view::operator bool", "ranges/std::join_view::back", "ranges/std::join_view::front"] +helpviewer_keywords: ["std::ranges::join_view [C++]", "std::ranges::join_view [C++], base", "std::ranges::join_view [C++], begin", "std::ranges::join_view [C++], end", "std::ranges::join_view [C++], empty", "std::ranges::join_view [C++], operator bool", "std::ranges::join_view [C++], front", "std::ranges::join_view [C++], back"] +dev_langs: ["C++"] +--- +# `join_view` class (C++ Standard Library) + +Combines the elements of a range of ranges into a single view. + +## Syntax + +```cpp +template requires view && input_range> && + (is_reference_v> || view>) +class join_view : public view_interface>; +``` + +### Template parameters + +*`R`*\ +The type of the underlying range. Must satisfy [`input_range`](range-concepts.md#input_range) or higher. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::join`](range-adaptors.md#join) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | `input_range` up to [`bidirectional_range`](range-concepts.md#bidirectional_range) depending on the underlying range being iterated | +| **Sized** | No | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct an `join_view`. | +| [`base`](#base)C++20 | Get a reference to the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +The best way to create a `join_view` is by using the [`views::join`](range-adaptors.md#join) range adaptor. Range adaptors are the intended way to access view classes. The view types are exposed in case you want to create your own custom view type. + +This view is useful when you want to combine multiple ranges into a single view. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `join_view`. + +```cpp +1) join_view() = default; +2) constexpr explicit join_view(R base) +``` + +### Parameters + +*`base`*\ +The underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +1\) Default-constructs a `join_view`.\ +2\) Constructs the `join_view` from *`base`*. + +### Example: `join_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg1{1, 2, 3, 4}; + std::vector rg2{5, 6, 7}; + std::vector rg3{8, 9, 10, 11, 12, 13}; + std::vector rangeOfRanges[] {rg1, rg2, rg3}; + + auto jv = std::ranges::join_view(rangeOfRanges); + + for (auto& e : jv) + { + std::cout << e << " "; + } +} +``` + +```output +1 2 3 4 5 6 7 8 9 10 11 12 13 +``` + +## `base` + +Get the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +1) The returned view is copy constructed. +2) The returned view is move constructed. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +constexpr auto begin() const + requires ranges::input_range && std::is_reference_v>; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr sentinel_t end(); +constexpr auto end() const requires range +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## See also + +[`join` range adaptor](range-adaptors.md#join)\ +[``](ranges.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/keys-view-class.md b/docs/standard-library/keys-view-class.md new file mode 100644 index 00000000000..6108fac74f2 --- /dev/null +++ b/docs/standard-library/keys-view-class.md @@ -0,0 +1,247 @@ +--- +title: keys_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) keys_view class, which provides a view over the first index into each tuple-like value in a collection. It's useful for extracting keys from associative containers." +ms.date: 09/28/2022 +f1_keywords: ["ranges/std::keys_view", "ranges/std::keys_view::base", "ranges/std::keys_view::begin", "ranges/std::keys_view::empty", "ranges/std::keys_view::end", "ranges/std::keys_view::size", "ranges/std::keys_view::operator bool", "ranges/std::keys_view::back", "ranges/std::keys_view::front", "ranges/std::keys_view::operator[]"] +helpviewer_keywords: ["std::ranges::keys_view [C++]", "std::ranges::keys_view::base [C++]", "std::ranges::keys_view::begin [C++]", "std::ranges::keys_view::empty [C++]", "std::ranges::keys_view::end [C++]", "std::ranges::keys_view::size [C++]", "std::ranges::keys_view::back [C++]", "std::ranges::keys_view::front [C++]", "std::ranges::keys_view::operator[] [C++]", "std::ranges::keys_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `keys_view` class (C++ Standard Library) + +A view over the first index into each tuple-like value in a collection. For example, given a range of `std::tuple`, create a view consisting of all the `string` elements from each tuple. + +`keys_view` is an alias for [`elements_view`](elements-view-class.md) and is useful for making of view of the keys from associative containers like [`std::map`](map.md) or [`std::unordered_map`](unordered-map-class.md). + +## Syntax + +```cpp +template +using keys_view = ranges::elements_view; +``` + +### Template parameters + +`R`\ + The type of the underlying range. This type must satisfy `ranges::input_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::keys`](range-adaptors.md#keys) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the type of the first tuple element of the underlying range | +| **View iterator category** | [`random_access_range`](range-concepts.md#random_access_range) if the underlying range is contiguous, otherwise the same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +The following list of member functions refers to the `keys_view` class. Recall that this is an alias for an [`element_view`](elements-view-class.md) class template instantiation. + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `keys_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `keys_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `keys_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Remarks + +The tuple-like types that you can use with `keys_view` are [`std::tuple`](tuple.md), [`std::pair`](pair-structure.md), and [`std::array`](array.md). + +## Constructors + +Construct an instance of a `keys_view`. + +```cpp +1) constexpr keys_view(V base); +2) keys_view() requires std::default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `keys_view` instance. + +### Remarks + +The best way to create an `keys_view` is by using the [`keys`](range-adaptors.md#keys) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create a `keys_view` from the specified view.\ +2\) The default constructor creates an empty `keys_view`. + +### Example: `keys_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include +#include + +int main() +{ + // ========== work with a std::map + + std::map cpp_standards + { + {"C++98", 1988}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the keys from the map + for (const std::string& standards : std::views::keys(cpp_standards)) + { + std::cout << standards << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 + } + std::cout << '\n'; + + // ========== work with a range of std::pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor using '|': create an keys_view from each pair + for (const std::string& version : windows | std::views::keys) + { + std::cout << version << ' '; // Windows 1.0 Windows 2.0 Windows 3.0 ... + } +} +``` + +```output +C++03 C++11 C++14 C++17 C++98 c++20 +Windows 1.0 Windows 2.0 Windows 3.0 Windows 3.1 Windows NT 3.1 Windows 95 Windows NT 4.0 Windows 95 Windows 98 Windows 1.0 Windows 2000 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `keys_view`. + +```cpp +1) constexpr auto begin() requires (!Simple_view); +2) constexpr auto begin() const requires (Simple_view) // or put another way, requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `keys_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `keys_view` + +```cpp +1) constexpr auto end() requires (!Simple_view && !ranges::common_range); +2) constexpr auto end() requires (!Simple_view && ranges::common_range); +3) constexpr auto end() const requires ranges::range; +4) constexpr auto end() const requires ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `keys_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires sized_range +constexpr auto size() const requires sized_range +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `keys_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[`elements_view`](elements-view-class.md)\ +[`values_view`](values-view-class.md)\ +[``](ranges.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/lazy-split-view-class.md b/docs/standard-library/lazy-split-view-class.md new file mode 100644 index 00000000000..1736de4824c --- /dev/null +++ b/docs/standard-library/lazy-split-view-class.md @@ -0,0 +1,241 @@ +--- +title: lazy_split_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) lazy_split_view class. Splits a view into subranges based on a delimiter." +ms.date: 10/18/2022 +f1_keywords: ["ranges/std::lazy_split_view", "ranges/std::lazy_split_view::base", "ranges/std::lazy_split_view::begin", "ranges/std::lazy_split_view::data", "ranges/std::lazy_split_view::empty", "ranges/std::lazy_split_view::end", "ranges/std::lazy_split_view::size", "ranges/std::lazy_split_view::operator bool", "ranges/std::lazy_split_view::back", "ranges/std::lazy_split_view::front", "ranges/std::lazy_split_view::operator[]"] +helpviewer_keywords: ["std::ranges::lazy_split_view [C++]", "std::ranges::lazy_split_view::base [C++]", "std::ranges::lazy_split_view::begin [C++]", "std::ranges::lazy_split_view::data [C++]", "std::ranges::lazy_split_view::empty [C++]", "std::ranges::lazy_split_view::size [C++]", "std::ranges::lazy_split_view::end [C++]", +"std::ranges::lazy_split_view::back [C++]", "std::ranges::lazy_split_view::front [C++]", "std::ranges::lazy_split_view::operator[] [C++]", "std::ranges::lazy_split_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `lazy_split_view` class (C++ Standard Library) + +Splits a range into subranges based on a delimiter. The delimiter can be a single element or a view of elements. The delimiter isn't part of the resulting subranges. + +The primary differences between a [`split_view`](split-view-class.md) and a `lazy_split_view` are: + +| **View** | **Can split a `const` range** | **range type** | +|--|--| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher. | +| `lazy_split_view` | yes | Supports [`input_range`](range-concepts.md#input_range) or higher. | + +What makes a `lazy_split_view` "lazy" is that it doesn't lookahead for the next delimiter. That means it can support [`input_range`](range-concepts.md#input_range) whereas `split_view` requires at least `forward_range`. This is because `input_range` is single-pass whereas `forward_range` allows multi-pass iteration. + +Prefer `split_view` because it's more efficient--unless you must split a range that is `const`. Regarding performance, `split_view` is more efficient. + +A `lazy_split_view` has less efficient iterator increment and comparison than `split_view`, but is still O(1). A `split_view` has better performance when the distance between delimiters is small enough for subranges to fit in the CPU cache, in which case the delimiter lookahead effectively pre-caches the next subrange. + +## Syntax + +```cpp +template + requires view && view && + indirectly_comparable, iterator_t, ranges::equal_to> && + (forward_range || tiny_range) +class lazy_split_view : public view_interface> +``` + +### Template parameters + +*`Pattern`*\ +The type of the view that specifies a delimiter sequence.\ +The `(forward_range || tiny-range )` requirement means that when the underlying range isn't [`forward_range`](range-concepts.md#forward_range), the delimiter must be a `tiny_range`. A `tiny_range` is a range with static extent whose size is 0 or 1. `tiny_range` requires `sized_range`, and `T::size()` must be a constant-expression that's less than or equal to 1. + +*`V`*\ + The type of the underlying view. + +## Characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +**Range adaptor:** [`lazy_split`](range-adaptors.md#lazy_split) +**Underlying range:** must satisfy [`input_range`](range-concepts.md#input_range) or higher +**View iterator category:** same as the underlying range +**Element type:** collection of `range_reference_t` +**Sized:** no +**Common range:** Yes when the underlying range is both [`forward_range`](range-concepts.md#forward_range) and `common`. +**Borrowed range:** no +**Is `const`-iterable:** only if the underlying range satisfies `forward_range` and is `const`-iterable + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element in the view. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `lazy_split_view` + +```cpp +1) lazy_split_view() = default; +2) constexpr lazy_split_view(V base, Pattern pattern); +3) template requires constructible_from> && + constructible_from>> + constexpr lazy_split_view(R&& rg, range_value_t e); +``` + +### Template parameters + +*`Pattern`*\ +The type of the delimiter. + +*`R`*\ +The type of the range. + +*`V`*\ +The type of the underlying view. + +### Parameters + +*`e`* +A single element that identifies where to split the view. The element isn't part of the resulting subranges. + +*`base`*\ +The underlying view. + +*`pattern`*\ +The view of elements that identifies where to split the view. The view of elements isn't part of the resulting subranges. + +*`rg`*\ +The range to split. + +### Return value + +A `lazy_split_view` instance that contains one or more `subrange`s. + +### Remarks + +The best way to create a `lazy_split_view` is by using the [`views::lazy_split`](range-adaptors.md#lazy_split) range adaptor. Range adaptors are the intended way to create view classes. The view types are only exposed in case you want to create your own custom view type. + +1\) Create a `lazy_split_view` that has no elements. The underlying view is default constructed. `base()` returns a copy of `V()`.\ +2\) Create a `lazy_split_view` by splitting the view using a delimiter sequence.\ +3\) Create a `lazy_split_view` by splitting the view using a delimiter element. + +### Example: `lazy_split_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{ 1, 2, 3, 1, 2, 3, 4, 5, 6 }; + + // pipe syntax using range adaptor + for (const auto& subrange : rg | std::views::split(3)) + { + // Outputs: + // 1 2 + // 1 2 + // 4 5 6 + for (const auto& elem : subrange) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + int delimiters[] = {2, 3}; + for (auto splitRange : std::views::split(rg, delimiters)) // ctor syntax + { + // outputs 1 1 4 5 6 + for (auto& i : splitRange) + { + std::cout << i << " "; + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const & requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +constexpr auto begin() const requires forward_range && forward_range +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +1) constexpr auto end() const; +2) constexpr auto end() requires forward_range && common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +2\) The `forward_range` requirement means that the view *`V`* has at least a forward iterator. For more information about range iterators, see [View class characteristics](view-classes.md#view-classes-characteristics). The `common_range` requirement means that the view *`V`* has identical iterator and sentinel types. + +## See also + +[``](ranges.md)\ +[`lazy_split` range adaptor](range-adaptors.md#lazy_split)\ +[`split_view` class](split-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/leap-second-info-struct.md b/docs/standard-library/leap-second-info-struct.md index 3f2508e2192..fe7095c8415 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/length-error-class.md b/docs/standard-library/length-error-class.md index 7df63ed20bc..7230d8b628f 100644 --- a/docs/standard-library/length-error-class.md +++ b/docs/standard-library/length-error-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: length_error Class" -title: "length_error Class" -ms.date: "09/09/2021" +title: "length_error class" +description: "Learn more about: length_error class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::length_error"] helpviewer_keywords: ["length_error class"] -ms.assetid: d53c46c5-4626-400d-bd76-bf3e1e0f64ae --- -# length_error Class +# `length_error` class The class serves as the base class for all exceptions thrown to report an attempt to generate an object too long to be specified. @@ -18,13 +17,12 @@ public: explicit length_error(const string& message); explicit length_error(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). ## Example @@ -50,19 +48,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: vector too long Type: class std::length_error -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[logic_error Class](../standard-library/logic-error-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`logic_error` class](logic-error-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/less-struct.md b/docs/standard-library/less-struct.md index 380355a2562..d4c3d3ac567 100644 --- a/docs/standard-library/less-struct.md +++ b/docs/standard-library/less-struct.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: less Struct" title: "less Struct" -ms.date: "11/04/2016" +description: "Learn more about: less Struct" +ms.date: 11/04/2016 f1_keywords: ["functional/std::less"] helpviewer_keywords: ["less struct", "less function"] -ms.assetid: 39349da3-11cd-4774-b2cc-b46af5aae5d7 --- # less Struct @@ -80,7 +79,7 @@ int main() { cout << "Original vector v1 = ( " ; for ( Iter1 = v1.begin() ; Iter1 != v1.end() ; Iter1++ ) -cout << Iter1->m_i << " "; + cout << Iter1->m_i << " "; cout << ")" << endl; // To sort in ascending order, @@ -88,7 +87,7 @@ cout << Iter1->m_i << " "; cout << "Sorted vector v1 = ( " ; for ( Iter1 = v1.begin() ; Iter1 != v1.end() ; Iter1++ ) -cout << Iter1->m_i << " "; + cout << Iter1->m_i << " "; cout << ")" << endl; } ``` diff --git a/docs/standard-library/limits-enums.md b/docs/standard-library/limits-enums.md index b94c4afc328..791135fc348 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-class.md b/docs/standard-library/list-class.md index 3e8d6dbc987..e2c7a17216c 100644 --- a/docs/standard-library/list-class.md +++ b/docs/standard-library/list-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: list Class" title: "list Class" -ms.date: "11/04/2016" +description: "Learn more about: list Class" +ms.date: 11/04/2016 f1_keywords: ["list/std::list", "list/std::list::allocator_type", "list/std::list::const_iterator", "list/std::list::const_pointer", "list/std::list::const_reference", "list/std::list::const_reverse_iterator", "list/std::list::difference_type", "list/std::list::iterator", "list/std::list::pointer", "list/std::list::reference", "list/std::list::reverse_iterator", "list/std::list::size_type", "list/std::list::value_type", "list/std::list::assign", "list/std::list::back", "list/std::list::begin", "list/std::list::cbegin", "list/std::list::cend", "list/std::list::clear", "list/std::list::crbegin", "list/std::list::crend", "list/std::list::emplace", "list/std::list::emplace_back", "list/std::list::emplace_front", "list/std::list::empty", "list/std::list::end", "list/std::list::erase", "list/std::list::front", "list/std::list::get_allocator", "list/std::list::insert", "list/std::list::max_size", "list/std::list::merge", "list/std::list::pop_back", "list/std::list::pop_front", "list/std::list::push_back", "list/std::list::push_front", "list/std::list::rbegin", "list/std::list::remove", "list/std::list::remove_if", "list/std::list::rend", "list/std::list::resize", "list/std::list::reverse", "list/std::list::size", "list/std::list::sort", "list/std::list::splice", "list/std::list::swap", "list/std::list::unique"] helpviewer_keywords: ["std::list [C++]", "std::list [C++], allocator_type", "std::list [C++], const_iterator", "std::list [C++], const_pointer", "std::list [C++], const_reference", "std::list [C++], const_reverse_iterator", "std::list [C++], difference_type", "std::list [C++], iterator", "std::list [C++], pointer", "std::list [C++], reference", "std::list [C++], reverse_iterator", "std::list [C++], size_type", "std::list [C++], value_type", "std::list [C++], assign", "std::list [C++], back", "std::list [C++], begin", "std::list [C++], cbegin", "std::list [C++], cend", "std::list [C++], clear", "std::list [C++], crbegin", "std::list [C++], crend", "std::list [C++], emplace", "std::list [C++], emplace_back", "std::list [C++], emplace_front", "std::list [C++], empty", "std::list [C++], end", "std::list [C++], erase", "std::list [C++], front", "std::list [C++], get_allocator", "std::list [C++], insert", "std::list [C++], max_size", "std::list [C++], merge", "std::list [C++], pop_back", "std::list [C++], pop_front", "std::list [C++], push_back", "std::list [C++], push_front", "std::list [C++], rbegin", "std::list [C++], remove", "std::list [C++], remove_if", "std::list [C++], rend", "std::list [C++], resize", "std::list [C++], reverse", "std::list [C++], size", "std::list [C++], sort", "std::list [C++], splice", "std::list [C++], swap", "std::list [C++], unique"] -ms.assetid: d3707f4a-10fd-444f-b856-f9ca2077c1cd --- # `list` Class @@ -303,7 +302,7 @@ int main( ) c1_Iter = c1.begin( ); cout << "The first element of c1 is " << *c1_Iter << endl; -*c1_Iter = 20; + *c1_Iter = 20; c1_Iter = c1.begin( ); cout << "The first element of c1 is now " << *c1_Iter << endl; @@ -851,7 +850,7 @@ int main( ) cout << "The last integer of c1 is " << *c1_Iter << endl; c1_Iter--; -*c1_Iter = 400; + *c1_Iter = 400; cout << "The new next-to-last integer of c1 is " << *c1_Iter << endl; @@ -1754,7 +1753,7 @@ int main( ) cout << endl; c1_rIter = c1.rbegin( ); -*c1_rIter = 40; + *c1_rIter = 40; cout << "The last element in the list is now " << *c1_rIter << "." << endl; } ``` diff --git a/docs/standard-library/list-functions.md b/docs/standard-library/list-functions.md index 8f55935efc0..3827916e5b6 100644 --- a/docs/standard-library/list-functions.md +++ b/docs/standard-library/list-functions.md @@ -1,8 +1,8 @@ --- +title: " functions" description: "Learn more about: functions" -title: " functions | Microsoft Docs" +ms.date: 11/04/2016 ms.custom: "" -ms.date: "11/04/2016" ms.topic: "reference" f1_keywords: ["list/std::swap"] --- diff --git a/docs/standard-library/list.md b/docs/standard-library/list.md index 389e03c2301..6d8ef3944f2 100644 --- a/docs/standard-library/list.md +++ b/docs/standard-library/list.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["list header"] -ms.assetid: 2345823b-5612-44d8-95d3-aa96ed076d17 --- # `` @@ -27,7 +26,7 @@ Defines the container class template list and several supporting templates. |-|-| |[operator!=](../standard-library/list-operators.md#op_neq)|Tests if the list object on the left side of the operator is not equal to the list object on the right side.| |[operator<](../standard-library/list-operators.md#op_lt)|Tests if the list object on the left side of the operator is less than the list object on the right side.| -|[operator\<=](../standard-library/list-operators.md#op_gt_eq)|Tests if the list object on the left side of the operator is less than or equal to the list object on the right side.| +|[operator\<=](../standard-library/list-operators.md#op_lt_eq)|Tests if the list object on the left side of the operator is less than or equal to the list object on the right side.| |[operator==](../standard-library/list-operators.md#op_eq_eq)|Tests if the list object on the left side of the operator is equal to the list object on the right side.| |[operator>](../standard-library/list-operators.md#op_gt)|Tests if the list object on the left side of the operator is greater than the list object on the right side.| |[operator>=](../standard-library/list-operators.md#op_gt_eq)|Tests if the list object on the left side of the operator is greater than or equal to the list object on the right side.| diff --git a/docs/standard-library/local_t.md b/docs/standard-library/local_t.md index e856ae1976e..f90b3ac8b44 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-class.md b/docs/standard-library/locale-class.md index b627b01ac3b..96b2151a0f3 100644 --- a/docs/standard-library/locale-class.md +++ b/docs/standard-library/locale-class.md @@ -1,10 +1,9 @@ --- description: "Learn more about: locale Class" title: "locale Class" -ms.date: 06/15/2022 +ms.date: 11/13/2025 f1_keywords: ["xlocale/std::locale", "xlocale/std::locale::category", "xlocale/std::locale::combine", "xlocale/std::locale::name", "xlocale/std::locale::classic", "xlocale/std::locale::global", "xlocale/std::locale::operator( )", "xlocale/std::locale::facet", "xlocale/std::locale::id"] helpviewer_keywords: ["std::locale [C++]", "std::locale [C++], category", "std::locale [C++], combine", "std::locale [C++], name", "std::locale [C++], classic", "std::locale [C++], global", "std::locale [C++], facet", "std::locale [C++], id"] -ms.assetid: 7dd6d271-472d-4750-8fb5-ea8f55fbef62 ms.custom: devdivchpfy22 --- @@ -92,15 +91,16 @@ messages Some of these predefined facets are used by the `iostream` classes, to control the conversion of numeric values to and from text sequences. -An object of class locale also stores a locale name as an object of class [string](../standard-library/string-typedefs.md#string). Using an invalid locale name to construct a locale facet or a locale object throws an object of class [runtime_error](../standard-library/runtime-error-class.md). The stored locale name is `"*"` if the locale object can't be certain that a C-style locale corresponds exactly to the one represented by the object. Otherwise, you can establish a matching locale within the Standard C Library, for some locale object `locale_object`, by calling `setlocale(LC_ALL , locale_object.`[name](#name)`().c_str())`. - -In this implementation, you can also call the static member function: +An object of class `locale` also stores a locale name as an object of class [string](../standard-library/string-typedefs.md#string). Using an invalid locale name to construct a locale facet or a locale object throws an object of class [runtime_error](../standard-library/runtime-error-class.md). The stored locale name is `"*"` if the locale object can't be certain that a C-style locale corresponds exactly to the one represented by the object. Otherwise, you can establish a matching locale within the Standard C Library, for some locale object `locale_object`, by calling `setlocale(LC_ALL , locale_object.`[name](#name)`().c_str())`. ```cpp static locale empty(); ``` -to construct a locale object that has no facets. It's also a transparent locale. If the template functions [has_facet](../standard-library/locale-functions.md#has_facet) and [use_facet](../standard-library/locale-functions.md#use_facet) can't find the requested facet in a transparent locale, they consult first the global locale and then, if that is transparent, the classic locale. So, you can write: +> [!NOTE] +> `locale::empty()` was deprecated starting with Visual Studio 2022 17.14. It'll be removed starting with MSVC Build Tools 14.51. For more information, see [#5834](https://github.com/microsoft/STL/pull/5834). + +In this implementation, you can also call the static member function `empty()` to construct a locale object that has no facets. It's also a transparent locale. If the template functions [has_facet](../standard-library/locale-functions.md#has_facet) and [use_facet](../standard-library/locale-functions.md#use_facet) can't find the requested facet in a transparent locale, they consult first the global locale and then, if that is transparent, the classic locale. So, you can write: ```cpp cout.imbue(locale::empty()); diff --git a/docs/standard-library/locale-functions.md b/docs/standard-library/locale-functions.md index cf168fad5d7..5a616e7085a 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 @@ -918,9 +903,10 @@ int main( ) { locale loc1 ( "German_Germany" ), loc2 ( "English_Australia" ); bool result1 = use_facet > ( loc1 ).is( - ctype_base::alpha, 'a' -); - bool result2 = use_facet > ( loc2 ).is( ctype_base::alpha, '!' + ctype_base::alpha, 'a' + ); + bool result2 = use_facet > ( loc2 ).is( + ctype_base::alpha, '!' ); if ( result1 ) diff --git a/docs/standard-library/logic-error-class.md b/docs/standard-library/logic-error-class.md index 63f9e82219b..6d096245bda 100644 --- a/docs/standard-library/logic-error-class.md +++ b/docs/standard-library/logic-error-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: logic_error Class" -title: "logic_error Class" -ms.date: "09/09/2021" +title: "logic_error class" +description: "Learn more about: logic_error class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::logic_error"] helpviewer_keywords: ["logic_error class"] -ms.assetid: b290d73d-94e1-4288-af86-2bb5d71f677a --- -# logic_error Class +# `logic_error` class The class serves as the base class for all exceptions thrown to report errors presumably detectable before the program executes, such as violations of logical preconditions. @@ -18,13 +17,12 @@ public: explicit logic_error(const string& message); explicit logic_error(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). ## Example @@ -49,19 +47,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: Does not compute! Type: class std::logic_error -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[exception Class](../standard-library/exception-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`exception` class](exception-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/logical-and-struct.md b/docs/standard-library/logical-and-struct.md index b3db5ad28eb..9cc55e98bae 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 4bd846b9b4e..88ae5469ff1 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 96c90c4fc50..47d9f120cb2 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 1a115a74e0c..6cc7a34dabd 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,12 +552,12 @@ 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 ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include #include @@ -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 29e85f2cf33..6567b76e850 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/media/begin-end-sentinel.png b/docs/standard-library/media/begin-end-sentinel.png new file mode 100644 index 00000000000..7ead7b7cb3e Binary files /dev/null and b/docs/standard-library/media/begin-end-sentinel.png differ diff --git a/docs/standard-library/media/range_functions/cbegin-cend-sentinel.png b/docs/standard-library/media/cbegin-cend-sentinel.png similarity index 100% rename from docs/standard-library/media/range_functions/cbegin-cend-sentinel.png rename to docs/standard-library/media/cbegin-cend-sentinel.png diff --git a/docs/standard-library/media/range_functions/crbegin-crend-sentinel.png b/docs/standard-library/media/crbegin-crend-sentinel.png similarity index 100% rename from docs/standard-library/media/range_functions/crbegin-crend-sentinel.png rename to docs/standard-library/media/crbegin-crend-sentinel.png diff --git a/docs/standard-library/media/iterator-hiearchy.svg b/docs/standard-library/media/iterator-hiearchy.svg new file mode 100644 index 00000000000..b843e51f959 --- /dev/null +++ b/docs/standard-library/media/iterator-hiearchy.svg @@ -0,0 +1,185 @@ + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Rectangle.1 + input_or_output_iterator + + + + + + + input_or_output_iterator + + Rectangle.3 + input_iterator + + + + + + + input_iterator + + Rectangle.4 + output_iterator + + + + + + + output_iterator + + Rectangle.5 + forward_iterator + + + + + + + forward_iterator + + Rectangle.6 + contiguous_iterator + + + + + + + contiguous_iterator + + Rectangle.7 + random_access_iterator + + + + + + + random_access_iterator + + Rectangle.8 + bidirectional_iterator + + + + + + + bidirectional_iterator + + Line Arrow.17 + + + + + + + + + + + Line Arrow.18 + + + + + + + + + + + Line Arrow.21 + + + + + + + + + + + Line Arrow.22 + + + + + + + + + + + Line Arrow.23 + + + + + + + + + + + Line Arrow.24 + + + + + + + + + + + Line Arrow.25 + + + + + + + + + + + diff --git a/docs/standard-library/media/range_functions/begin-end-sentinel.png b/docs/standard-library/media/range_functions/begin-end-sentinel.png deleted file mode 100644 index f12f2c649f9..00000000000 Binary files a/docs/standard-library/media/range_functions/begin-end-sentinel.png and /dev/null differ diff --git a/docs/standard-library/media/range_functions/rcbegin-rcend-sentinel.png b/docs/standard-library/media/range_functions/rcbegin-rcend-sentinel.png deleted file mode 100644 index cbd0853d245..00000000000 Binary files a/docs/standard-library/media/range_functions/rcbegin-rcend-sentinel.png and /dev/null differ diff --git a/docs/standard-library/media/ranges-iterator-hiearchy.svg b/docs/standard-library/media/ranges-iterator-hiearchy.svg new file mode 100644 index 00000000000..f16fab6d54c --- /dev/null +++ b/docs/standard-library/media/ranges-iterator-hiearchy.svg @@ -0,0 +1,153 @@ + + + + + + + + + + + + + + + + + + + + + + + + Page-1 + + + + Rectangle.3 + input_range + + + + + + + input_range + + Rectangle.4 + output_range + + + + + + + output_range + + Rectangle.5 + forward_range + + + + + + + forward_range + + Rectangle.6 + contiguous_range + + + + + + + contiguous_range + + Rectangle.7 + random_access_range + + + + + + + random_access_range + + Rectangle.8 + bidirectional_range + + + + + + + bidirectional_range + + Line Arrow.17 + + + + + + + + + + + Line Arrow.18 + + + + + + + + + + + Line Arrow.21 + + + + + + + + + + + Line Arrow.22 + + + + + + + + + + + Line Arrow.23 + + + + + + + + + + + diff --git a/docs/standard-library/media/range_functions/rbegin-rend-sentinel.png b/docs/standard-library/media/rbegin-rend-sentinel.png similarity index 100% rename from docs/standard-library/media/range_functions/rbegin-rend-sentinel.png rename to docs/standard-library/media/rbegin-rend-sentinel.png diff --git a/docs/standard-library/media/range_functions/src/begin-end-sentinel.pdn b/docs/standard-library/media/src/begin-end-sentinel.pdn similarity index 100% rename from docs/standard-library/media/range_functions/src/begin-end-sentinel.pdn rename to docs/standard-library/media/src/begin-end-sentinel.pdn diff --git a/docs/standard-library/media/range_functions/src/cbegin-cend-sentinel.pdn b/docs/standard-library/media/src/cbegin-cend-sentinel.pdn similarity index 100% rename from docs/standard-library/media/range_functions/src/cbegin-cend-sentinel.pdn rename to docs/standard-library/media/src/cbegin-cend-sentinel.pdn diff --git a/docs/standard-library/media/range_functions/src/crbegin-crend-sentinel.pdn b/docs/standard-library/media/src/crbegin-crend-sentinel.pdn similarity index 100% rename from docs/standard-library/media/range_functions/src/crbegin-crend-sentinel.pdn rename to docs/standard-library/media/src/crbegin-crend-sentinel.pdn diff --git a/docs/standard-library/media/src/iterator-hiearchy.vsdx b/docs/standard-library/media/src/iterator-hiearchy.vsdx new file mode 100644 index 00000000000..2b4b1e22373 Binary files /dev/null and b/docs/standard-library/media/src/iterator-hiearchy.vsdx differ diff --git a/docs/standard-library/media/src/range-iterator-hiearchy.vsdx b/docs/standard-library/media/src/range-iterator-hiearchy.vsdx new file mode 100644 index 00000000000..c37b38a7e5b Binary files /dev/null and b/docs/standard-library/media/src/range-iterator-hiearchy.vsdx differ diff --git a/docs/standard-library/media/range_functions/src/rbegin-rend-sentinel.pdn b/docs/standard-library/media/src/rbegin-rend-sentinel.pdn similarity index 100% rename from docs/standard-library/media/range_functions/src/rbegin-rend-sentinel.pdn rename to docs/standard-library/media/src/rbegin-rend-sentinel.pdn diff --git a/docs/standard-library/memory-functions.md b/docs/standard-library/memory-functions.md index 084121f88e6..5de848e295b 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. @@ -35,8 +36,6 @@ The object or function for which to obtain the true address. The actual address of the object or function referenced by *`value`*, even if an overloaded `operator&()` exists. -### Remarks - ## `align` Fits storage of the given size, aligned by the given alignment specification, into the first possible address of the given storage. @@ -768,6 +767,7 @@ struct owner_less> template struct owner_less> +{ bool operator()( const weak_ptr& left, const weak_ptr& right) const noexcept; @@ -982,7 +982,6 @@ template void swap( weak_ptr& left, weak_ptr& right) noexcept; - ``` ### Parameters diff --git a/docs/standard-library/memory-operators.md b/docs/standard-library/memory-operators.md index 0ae10aa886c..6fb628d3e2a 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/memory.md b/docs/standard-library/memory.md index 336706d3f92..5e3a65200e2 100644 --- a/docs/standard-library/memory.md +++ b/docs/standard-library/memory.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: " title: "" -ms.date: "08/04/2019" +description: "Learn more about: " +ms.date: 08/04/2019 f1_keywords: [""] helpviewer_keywords: ["memory header"] --- @@ -74,7 +74,7 @@ Defines a class, an operator, and several templates that help allocate and free |[operator==](../standard-library/memory-operators.md#op_eq_eq)|Tests for equality between allocator objects of a specified class.| |[operator>=](../standard-library/memory-operators.md#op_gt_eq)|Tests for one allocator object being greater than or equal to a second allocator object, of a specified class.| |[operator<](../standard-library/memory-operators.md#op_lt)|Tests for one object being less than a second object of a specified class.| -|[operator\<=](../standard-library/memory-operators.md#op_gt_eq)|Tests for one object being less than or equal to a second object of a specified class.| +|[operator\<=](../standard-library/memory-operators.md#op_lt_eq)|Tests for one object being less than or equal to a second object of a specified class.| |[operator>](../standard-library/memory-operators.md#op_gt)|Tests for one object being greater than a second object of a specified class.| |[operator<<](../standard-library/memory-operators.md#op_lt_lt)|`shared_ptr` inserter.| diff --git a/docs/standard-library/messages-byname-class.md b/docs/standard-library/messages-byname-class.md index cf22a906dd6..fe6b2c1f59e 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 7468f6fb3c1..4797d927f91 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 17bbcfff3e2..2651c1f9818 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 82b6ce9572c..1697f2a73a2 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 3adbf050df9..275a645404d 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 b6133994842..af0388fc0bb 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 701923e297c..9fb1ed976d7 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 04d76312616..2e5d3962502 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 8ff4fedf0f9..f43deea25ab 100644 --- a/docs/standard-library/month-class.md +++ b/docs/standard-library/month-class.md @@ -1,19 +1,19 @@ --- -description: "Learn more about: month Class" title: "month class" -ms.date: "6/25/2021" +description: "Learn more about: month Class" +ms.date: 6/25/2021 f1_keywords: ["chrono/std::chrono::month", "chrono/std::chrono::month::January", "chrono/std::chrono::month::February", "chrono/std::chrono::month::March","chrono/std::chrono::month::April","chrono/std::chrono::month::May","chrono/std::chrono::month::June","chrono/std::chrono::month::July","chrono/std::chrono::month::August","chrono/std::chrono::month::September","chrono/std::chrono::month::October","chrono/std::chrono::month::November","chrono/std::chrono::month::December","chrono/std::chrono::month::operator++", "chrono/std::chrono::month::operator--", "chrono/std::chrono::month::operator unsigned", "chrono/std::chrono::month::ok"] helpviewer_keywords: ["std::chrono [C++], month"] dev_langs: ["C++"] --- -# `month` class +# `month` class Represents a month of a year. For example, July. ## Syntax ```cpp -class month; // C++ 20 +class month; // C++20 ``` ## Remarks @@ -26,7 +26,7 @@ See [Month constants](#month-constants), below, for constants that you can use w |Name|Description| |----------|-----------------| | [Constructors](#month) | Construct a `month`. | -| [`ok`](#ok) | Verify that the month value is in the valid range [1,31]. | +| [`ok`](#ok) | Verify that the month value is in the valid range [1,12]. | | [`operator++`](#op_++) | Increment the `month`. | | [`operator+=`](#op_+=) | Add the specified number of months to this `month`. | | [`operator--`](#op_--) | Decrement this `month`. | @@ -272,4 +272,4 @@ inline constexpr month December{12}; [`month_day` Class](month-day-class.md)\ [`month_day_last` Class](month-day-last-class.md)\ [`month_weekday` Class](month-weekday-class.md)\ -[`month_weekday_last` class](month-weekday-last-class.md) \ No newline at end of file +[`month_weekday_last` class](month-weekday-last-class.md) diff --git a/docs/standard-library/month-day-class.md b/docs/standard-library/month-day-class.md index 0d1b6cd5a03..f8f80f65f9a 100644 --- a/docs/standard-library/month-day-class.md +++ b/docs/standard-library/month-day-class.md @@ -1,13 +1,13 @@ --- -description: "Learn more about: month_day Class" title: "month_day class" -ms.date: "6/28/2021" +description: "Learn more about: month_day Class" +ms.date: 6/28/2021 f1_keywords: ["chrono/std::chrono::month_day", "chrono/std::chrono::month_day::day", "chrono/std::chrono::month_day::month", "chrono/std::chrono::month_day::ok"] helpviewer_keywords: ["std::chrono [C++], month_day"] dev_langs: ["C++"] --- -# `month_day` class +# `month_day` class Represents a specific day of a specific month. The year isn't specified. @@ -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 2cf606f60e7..bc2a97a90bc 100644 --- a/docs/standard-library/month-day-last-class.md +++ b/docs/standard-library/month-day-last-class.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: month_day_last Class" title: "month_day_last class" -ms.date: "06/28/2021" +description: "Learn more about: month_day_last Class" +ms.date: 06/28/2021 f1_keywords: ["chrono/std::chrono::month_day_last", "chrono/std::chrono::month_day_last::month", "chrono/std::chrono::month_day_last::ok"] helpviewer_keywords: ["std::chrono [C++], month_day_last"] dev_langs: ["C++"] --- -# `month_day_last` class +# `month_day_last` class Represents the last day of a month. ## 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 c7e61138f76..a82659be430 100644 --- a/docs/standard-library/month-weekday-class.md +++ b/docs/standard-library/month-weekday-class.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: month_weekday Class" title: "month_weekday class" -ms.date: "06/28/2021" +description: "Learn more about: month_weekday Class" +ms.date: 06/28/2021 f1_keywords: ["chrono/std::chrono::month_weekday", "chrono/std::chrono::month_weekday::weekday", "chrono/std::chrono::month_weekday::month", "chrono/std::chrono::month_weekday::ok", "chrono/std::chrono::month_weekday::weekday_indexed"] helpviewer_keywords: ["std::chrono [C++], month_weekday"] dev_langs: ["C++"] --- -# `month_weekday` class +# `month_weekday` class 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 deb38d37357..9af2b50a786 100644 --- a/docs/standard-library/month-weekday-last-class.md +++ b/docs/standard-library/month-weekday-last-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: month_weekday_last Class" title: "month_weekday_last class" -ms.date: "6/28/2021" +description: "Learn more about: month_weekday_last Class" +ms.date: 6/28/2021 f1_keywords: ["chrono/std::chrono::month_weekday_last", "chrono/std::chrono::month_weekday_last::ok", "std::chrono::month_weekday_last::month_weekday_last", "chrono/std::chrono::month_weekday_last::ok", "chrono/std::chrono::month_weekday_last::month"] helpviewer_keywords: ["std::chrono [C++], month_weekday_last"] dev_langs: ["C++"] --- -# `month_weekday_last` class +# `month_weekday_last` class Represents the last weekday of a month. @@ -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 935f94c5cb5..ca1f45c9067 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 d0ce3cc3e52..3db0788cc5f 100644 --- a/docs/standard-library/multimap-class.md +++ b/docs/standard-library/multimap-class.md @@ -1,7 +1,7 @@ --- title: "multimap Class" description: "API reference for the C++ Standard Template Library (STL) `multimap` 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/9/2020" +ms.date: 9/9/2020 f1_keywords: ["map/std::multimap", "map/std::multimap::allocator_type", "map/std::multimap::const_iterator", "map/std::multimap::const_pointer", "map/std::multimap::const_reference", "map/std::multimap::const_reverse_iterator", "map/std::multimap::difference_type", "map/std::multimap::iterator", "map/std::multimap::key_compare", "map/std::multimap::key_type", "map/std::multimap::mapped_type", "map/std::multimap::pointer", "map/std::multimap::reference", "map/std::multimap::reverse_iterator", "map/std::multimap::size_type", "map/std::multimap::value_type", "map/std::multimap::begin", "map/std::multimap::cbegin", "map/std::multimap::cend", "map/std::multimap::clear", "map/std::multimap::contains", "map/std::multimap::count", "map/std::multimap::crbegin", "map/std::multimap::crend", "map/std::multimap::emplace", "map/std::multimap::emplace_hint", "map/std::multimap::empty", "map/std::multimap::end", "map/std::multimap::equal_range", "map/std::multimap::erase", "map/std::multimap::find", "map/std::multimap::get_allocator", "map/std::multimap::insert", "map/std::multimap::key_comp", "map/std::multimap::lower_bound", "map/std::multimap::max_size", "map/std::multimap::rbegin", "map/std::multimap::rend", "map/std::multimap::size", "map/std::multimap::swap", "map/std::multimap::upper_bound", "map/std::multimap::value_comp"] helpviewer_keywords: ["std::multimap [C++]", "std::multimap [C++], allocator_type", "std::multimap [C++], const_iterator", "std::multimap [C++], const_pointer", "std::multimap [C++], const_reference", "std::multimap [C++], const_reverse_iterator", "std::multimap [C++], difference_type", "std::multimap [C++], iterator", "std::multimap [C++], key_compare", "std::multimap [C++], key_type", "std::multimap [C++], mapped_type", "std::multimap [C++], pointer", "std::multimap [C++], reference", "std::multimap [C++], reverse_iterator", "std::multimap [C++], size_type", "std::multimap [C++], value_type", "std::multimap [C++], begin", "std::multimap [C++], cbegin", "std::multimap [C++], cend", "std::multimap [C++], clear", "std::multimap [C++], contains", "std::multimap [C++], count", "std::multimap [C++], crbegin", "std::multimap [C++], crend", "std::multimap [C++], emplace", "std::multimap [C++], emplace_hint", "std::multimap [C++], empty", "std::multimap [C++], end", "std::multimap [C++], equal_range", "std::multimap [C++], erase", "std::multimap [C++], find", "std::multimap [C++], get_allocator", "std::multimap [C++], insert", "std::multimap [C++], key_comp", "std::multimap [C++], lower_bound", "std::multimap [C++], max_size", "std::multimap [C++], rbegin", "std::multimap [C++], rend", "std::multimap [C++], size", "std::multimap [C++], swap", "std::multimap [C++], upper_bound", "std::multimap [C++], value_comp"] --- @@ -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,12 +430,12 @@ 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 ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include #include @@ -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 cb110701b84..927e7f2403d 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 36de619fe1d..2ee9fe92c5b 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,12 +399,12 @@ 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 ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -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 f28baee7ecd..aa07a6867d6 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 3e8d9f950ec..f0f71b2e538 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 bc3cbae3a88..ce20bc942ef 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 7bcc74e8889..4a7901ce9db 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 0df7cbc0715..49e1184de86 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/new.md b/docs/standard-library/new.md index 79dfcd6b5b4..09baa6795b1 100644 --- a/docs/standard-library/new.md +++ b/docs/standard-library/new.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["new header"] -ms.assetid: 218e2a15-34e8-4ef3-9122-1e90eccf8559 --- # `` @@ -33,7 +32,7 @@ Some of the functions declared in this header are replaceable. The implementatio |Name|Description| |-|-| |[new_handler](../standard-library/new-typedefs.md#new_handler)|A type that points to a function suitable for use as a new handler.| -|[hardware_constructive_interference_size](../standard-library/new-typedefs.md#hardware_destructive_interference_size)|| +|[hardware_constructive_interference_size](../standard-library/new-typedefs.md#hardware_constructive_interference_size)|| |[hardware_destructive_interference_size](../standard-library/new-typedefs.md#hardware_destructive_interference_size)|| ### Functions diff --git a/docs/standard-library/nonexistent-local-time.md b/docs/standard-library/nonexistent-local-time.md index 1b93e23cef5..45529f58209 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/normal-distribution-class.md b/docs/standard-library/normal-distribution-class.md index db8ba64c3be..e9e4be15c45 100644 --- a/docs/standard-library/normal-distribution-class.md +++ b/docs/standard-library/normal-distribution-class.md @@ -83,7 +83,7 @@ using namespace std; void test(const double m, const double s, const int samples) { // uncomment to use a non-deterministic seed - // random_device gen; + // random_device rd; // mt19937 gen(rd()); mt19937 gen(1701); diff --git a/docs/standard-library/not-equal-to-struct.md b/docs/standard-library/not-equal-to-struct.md index c749d9e060b..6324e219440 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 2fecf24e5f0..1a9729edc91 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 7ab66566f44..5d4feb17983 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 d56d1c0b9b0..a0c85da2610 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 e9ec7b1fef7..1ea1eac40b2 100644 --- a/docs/standard-library/once-flag-structure.md +++ b/docs/standard-library/once-flag-structure.md @@ -11,10 +11,12 @@ Represents a **`struct`** that is used with the template function [call_once](.. ## Syntax +```cpp struct once_flag - { +{ constexpr once_flag() noexcept; - }; +}; +``` ## Remarks diff --git a/docs/standard-library/operator-equality-sample-container.md b/docs/standard-library/operator-equality-sample-container.md deleted file mode 100644 index 63715e0da1d..00000000000 --- a/docs/standard-library/operator-equality-sample-container.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: "Learn more about: operator== ()" -title: "operator== ()" -ms.date: "11/04/2016" -f1_keywords: ["std.==", "std::==", "operator==", "std.operator==", "std::operator==", "=="] -helpviewer_keywords: ["operator ==, containers", "operator==, containers", "== operator, with specific standard C++ objects"] -ms.assetid: d3d8754e-5157-4b8b-bf9c-da41856f5eed ---- -# `operator==` (``) - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Overloads `operator==` to compare two objects of class template [Container](../standard-library/sample-container-class.md). - -## Syntax - -```cpp -template -bool operator==( - const Container & left, - const Container & right); -``` - -## Return Value - -Returns `left.`[size](../standard-library/container-class-size.md) `== right.size && equal(left.`[begin](../standard-library/container-class-begin.md)`, left.`[end](../standard-library/container-class-end.md)`, right.begin)`. - -## See also - -[\](../standard-library/sample-container.md) diff --git a/docs/standard-library/operator-greater-or-equal.md b/docs/standard-library/operator-greater-or-equal.md deleted file mode 100644 index 13d31d815af..00000000000 --- a/docs/standard-library/operator-greater-or-equal.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: "Learn more about: operator>=" -title: "operator>=" -ms.date: "11/04/2016" -f1_keywords: ["operator>=", "std::>=", "std.operator>=", ">=", "std.>=", "std::operator>="] -helpviewer_keywords: [">= operator, comparing specific objects", "operator >=", "operator>="] -ms.assetid: 14fbebf5-8b75-4afa-a51b-3112d31c07cf ---- -# `operator>=` - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Overloads **operator>=** to compare two objects of class template [Container](../standard-library/sample-container-class.md). - -## Syntax - -```cpp -template -bool operator>=( - const Container & left, - const Container & right); -``` - -## Return Value - -Returns `!(left < right)`. - -## See also - -[\](../standard-library/sample-container.md) diff --git a/docs/standard-library/operator-greater-than-sample-container.md b/docs/standard-library/operator-greater-than-sample-container.md deleted file mode 100644 index a6bf41df1d3..00000000000 --- a/docs/standard-library/operator-greater-than-sample-container.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: "Learn more about: operator> ()" -title: "operator> ()" -ms.date: "11/04/2016" -f1_keywords: ["std::operator>", "operator>", "std::>", ">"] -helpviewer_keywords: ["> operator, comparing specific objects", "operator >"] -ms.assetid: 49bd417a-3305-4ffa-9884-39d3904ed87d ---- -# `operator>` (``) - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Overloads **operator>** to compare two objects of class template [Container](../standard-library/sample-container-class.md). - -## Syntax - -```cpp -template -bool operator*gt( - const Container & left, - const Container & right); -``` - -## Return Value - -Returns `right < left`. - -## See also - -[\](../standard-library/sample-container.md) diff --git a/docs/standard-library/operator-inequality.md b/docs/standard-library/operator-inequality.md deleted file mode 100644 index 1416a3f3cc3..00000000000 --- a/docs/standard-library/operator-inequality.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: "Learn more about: operator!=" -title: "operator!=" -ms.date: "11/04/2016" -f1_keywords: ["std::!=", "!=", "std::operator!=", "std.operator!=", "std.!=", "operator!="] -helpviewer_keywords: ["!= operator", "operator!=", "operator !="] -ms.assetid: ef2be7f0-1c94-4edc-b65c-731fddd519f4 ---- -# operator!= - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Overloads `operator!=` to compare two objects of class template [Container](../standard-library/sample-container-class.md). - -## Syntax - -```cpp -template -bool operator!=( - const Container & left, - const Container & right); -``` - -## Return Value - -Returns `!(left == right)`. - -## See also - -[\](../standard-library/sample-container.md) diff --git a/docs/standard-library/operator-less-or-equal-sample-container.md b/docs/standard-library/operator-less-or-equal-sample-container.md deleted file mode 100644 index db35e24ec91..00000000000 --- a/docs/standard-library/operator-less-or-equal-sample-container.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: "Learn more about: operator<= ()" -title: "operator<= ()" -ms.date: "11/04/2016" -f1_keywords: ["std::<=", "std.operator<=", "operator<=", "std.<=", "std::operator<=", "<="] -helpviewer_keywords: ["operator<=", "operator <=", "<= operator, with specific objects", "<= operator"] -ms.assetid: 338577dd-dc88-4a2b-9e12-0379c54fc8a2 ---- -# `operator<=` (``) - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Overloads **operator<=** to compare two objects of class template [Container](../standard-library/sample-container-class.md). - -## Syntax - -```cpp -template -bool operator<=( - const Container & left, - const Container & right); -``` - -## Return Value - -Returns `!(right < left)`. - -## See also - -[\](../standard-library/sample-container.md) diff --git a/docs/standard-library/operator-less-than-sample-container.md b/docs/standard-library/operator-less-than-sample-container.md deleted file mode 100644 index cab25748e00..00000000000 --- a/docs/standard-library/operator-less-than-sample-container.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -description: "Learn more about: operator< ()" -title: "operator< ()" -ms.date: "11/04/2016" -f1_keywords: ["std::operator<", "operator<", "std.<", "<", "std.operator<", "std::<"] -helpviewer_keywords: ["< operator, comparing specific objects", "operator<, valarrays", "< operator", "operator <, valarrays"] -ms.assetid: 31027dd6-53be-428b-b950-1dcb25393597 ---- -# `operator<` (``) - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Overloads **operator<** to compare two objects of class template [Container](../standard-library/sample-container-class.md). - -## Syntax - -```cpp -template -bool operator<( - const Container & left, - const Container & right); -``` - -## Return Value - -Returns `lexicographical_compare(left.begin, left.end, right.begin, right.end)`. - -## See also - -[\](../standard-library/sample-container.md)\ -[begin](../standard-library/container-class-begin.md)\ -[end](../standard-library/container-class-end.md) diff --git a/docs/standard-library/optional-class.md b/docs/standard-library/optional-class.md index 91889ce7f7c..4df0c70b5a4 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 839624fd2d7..99a367665fb 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/optional.md b/docs/standard-library/optional.md index 776d8b5da68..5a632e0931e 100644 --- a/docs/standard-library/optional.md +++ b/docs/standard-library/optional.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: " title: "" -ms.date: "08/06/2019" +description: "Learn more about: " +ms.date: 08/06/2019 f1_keywords: [""] helpviewer_keywords: [""] --- @@ -26,7 +26,7 @@ Defines the container class template `optional` and several supporting templates |[operator<](../standard-library/optional-operators.md#op_lt)|Tests if the object on the left is less than the object on the right.| |[operator<=](../standard-library/optional-operators.md#op_lt_eq)|Tests if the object on the left is less than or equal to the object on the right.| |[operator>](../standard-library/optional-operators.md#op_gt)|Tests if the object on the left is greater than the object on the right.| -|[operator>=](../standard-library/optional-operators.md#op_lt_eq)|Tests if the object on the left is greater than or equal to the object on the right.| +|[operator>=](../standard-library/optional-operators.md#op_gt_eq)|Tests if the object on the left is greater than or equal to the object on the right.| > [!NOTE] > In addition to relational compares, \ operators also support comparison with **nullopt** and `T`. diff --git a/docs/standard-library/ostream-functions.md b/docs/standard-library/ostream-functions.md index ce0710b50ca..3721ebdd884 100644 --- a/docs/standard-library/ostream-functions.md +++ b/docs/standard-library/ostream-functions.md @@ -1,48 +1,42 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["ostream/std::swap", "ostream/std::endl", "ostream/std::ends", "ostream/std::flush"] -ms.assetid: d6e56cc0-c8df-4dbe-be10-98e14c35ed3a helpviewer_keywords: ["std::swap [C++]", "std::endl [C++]", "std::ends [C++]", "std::flush [C++]"] --- # `` functions -These are the global template functions defined in ``. For member functions, see the [basic_ostream Class](basic-ostream-class.md) documentation. - -[endl](#endl)\ -[ends](#ends)\ -[flush](#flush)\ -[swap](#swap) +These are the global template functions defined in ``. For member functions, see the [`basic_ostream` Class](basic-ostream-class.md) documentation. -## endl +## `endl` Terminates a line and flushes the buffer. ```cpp -template class +template basic_ostream& endl( basic_ostream& Ostr); ``` ### Parameters -*Elem*\ +*`Elem`*\ The element type. -*Ostr*\ -An object of type **basic_ostream**. +*`Ostr`*\ +An object of type **`basic_ostream`**. -*Tr*\ +*`Tr`*\ Character traits. ### Return Value -An object of type **basic_ostream**. +An object of type **`basic_ostream`**. ### Remarks -The manipulator calls *Ostr*.[put](../standard-library/basic-ostream-class.md#put)(*Ostr*.[widen](../standard-library/basic-ios-class.md#widen)('\n')), and then calls *Ostr*.[flush](../standard-library/basic-ostream-class.md#flush). It returns *Ostr*. +The manipulator calls *`Ostr`*.[`put`](../standard-library/basic-ostream-class.md#put)(*`Ostr`*.[`widen`](../standard-library/basic-ios-class.md#widen)('\n')), and then calls *`Ostr`*.[`flush`](../standard-library/basic-ostream-class.md#flush). It returns *`Ostr`*. ### Example @@ -62,25 +56,25 @@ int main( ) testing ``` -## ends +## `ends` Terminates a string. ```cpp -template class +template basic_ostream& ends( basic_ostream& Ostr); ``` ### Parameters -*Elem*\ +*`Elem`*\ The element type. -*Ostr*\ +*`Ostr`*\ An object of type `basic_ostream`. -*Tr*\ +*`Tr`*\ Character traits. ### Return Value @@ -89,7 +83,7 @@ An object of type `basic_ostream`. ### Remarks -The manipulator calls *Ostr*.[put](../standard-library/basic-ostream-class.md#put)(*Elem*('\0')). It returns *Ostr*. +The manipulator calls *`Ostr`*.[`put`](../standard-library/basic-ostream-class.md#put)(*`Elem`*('\0')). It returns *`Ostr`*. ### Example @@ -111,25 +105,25 @@ int main( ) ab c ``` -## flush +## `flush` Flushes the buffer. ```cpp -template class +template basic_ostream& flush( basic_ostream& Ostr); ``` ### Parameters -*Elem*\ +*`Elem`*\ The element type. -*Ostr*\ +*`Ostr`*\ An object of type `basic_ostream`. -*Tr*\ +*`Tr`*\ Character traits. ### Return Value @@ -138,7 +132,7 @@ An object of type `basic_ostream`. ### Remarks -The manipulator calls *Ostr*.[flush](../standard-library/basic-ostream-class.md#flush). It returns *Ostr*. +The manipulator calls *`Ostr`*.[`flush`](../standard-library/basic-ostream-class.md#flush). It returns *`Ostr`*. ### Example @@ -158,7 +152,7 @@ int main( ) testing ``` -## swap +## `swap` Exchanges the values of two `basic_ostream` objects. @@ -171,16 +165,16 @@ void swap( ### Parameters -*Elem*\ +*`Elem`*\ The element type. -*Tr*\ +*`Tr`*\ Character traits. -*left*\ +*`left`*\ An lvalue reference to a `basic_ostream` object. -*right*\ +*`right`*\ An lvalue reference to a `basic_ostream` object. ### Remarks @@ -189,4 +183,4 @@ The template function `swap` executes `left.swap(right)`. ## See also -[\](../standard-library/ostream.md) +[``](../standard-library/ostream.md) diff --git a/docs/standard-library/ostream-iterator-class.md b/docs/standard-library/ostream-iterator-class.md index de3f56cd39c..aff05930b8f 100644 --- a/docs/standard-library/ostream-iterator-class.md +++ b/docs/standard-library/ostream-iterator-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: ostream_iterator Class" title: "ostream_iterator Class" +description: "Learn more about: ostream_iterator Class" ms.date: 06/17/2022 f1_keywords: ["iterator/std::ostream_iterator", "iterator/std::ostream_iterator::char_type", "iterator/std::ostream_iterator::ostream_type", "iterator/std::ostream_iterator::traits_type"] helpviewer_keywords: ["std::ostream_iterator [C++]", "std::ostream_iterator [C++], char_type", "std::ostream_iterator [C++], ostream_type", "std::ostream_iterator [C++], traits_type"] -ms.assetid: 24d842d3-9f45-4bf6-a697-62f5968f5a03 ms.custom: devdivchpfy22 --- @@ -15,20 +14,20 @@ The class template ostream_iterator describes an output iterator object that wri ## Syntax ```cpp -template > +template > class ostream_iterator ``` ### Parameters -*Type*\ +*`Type`*\ The type of object to be inserted into the output stream. -*CharType*\ +*`CharType`*\ The type that represents the character type for the `ostream_iterator`. This argument is optional and the default value is **`char`**. -*Traits*\ -The type that represents the character type for the `ostream_iterator`. This argument is optional and the default value is `char_traits`\< *CharType>.* +*`Traits`*\ +The type that represents the character type for the `ostream_iterator`. This argument is optional and the default value is `char_traits`.* The ostream_iterator class must satisfy the requirements for an output iterator. Algorithms can be written directly to output streams using an `ostream_iterator`. @@ -36,31 +35,31 @@ The ostream_iterator class must satisfy the requirements for an output iterator. |Constructor|Description| |-|-| -|[ostream_iterator](#ostream_iterator)|Constructs an `ostream_iterator` that is initialized and delimited to write to the output stream.| +|[`ostream_iterator`](#ostream_iterator)|Constructs an `ostream_iterator` that is initialized and delimited to write to the output stream.| ### Typedefs |Type name|Description| |-|-| -|[char_type](#char_type)|A type that provides for the character type of the `ostream_iterator`.| -|[ostream_type](#ostream_type)|A type that provides for the stream type of the `ostream_iterator`.| -|[traits_type](#traits_type)|A type that provides for the character traits type of the `ostream_iterator`.| +|[`char_type`](#char_type)|A type that provides for the character type of the `ostream_iterator`.| +|[`ostream_type`](#ostream_type)|A type that provides for the stream type of the `ostream_iterator`.| +|[`traits_type`](#traits_type)|A type that provides for the character traits type of the `ostream_iterator`.| ### Operators |Operator|Description| |-|-| -|[operator*](#op_star)|Dereferencing operator used to implement the output iterator expression \* `i` = `x`.| -|[operator++](#op_add_add)|A nonfunctional increment operator that returns an `ostream_iterator` to the same object it addressed before the operation was called.| -|[operator=](#op_eq)|Assignment operator used to implement the output iterator expression \* `i` = `x` for writing to an output stream.| +|[`operator*`](#op_star)|Dereferencing operator used to implement the output iterator expression `*i = x`.| +|[`operator++`](#op_add_add)|A nonfunctional increment operator that returns an `ostream_iterator` to the same object it addressed before the operation was called.| +|[`operator=`](#op_eq)|Assignment operator used to implement the output iterator expression `*i = x` for writing to an output stream.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## ostream_iterator::char_type +## `ostream_iterator::char_type` A type that provides for the character type of the iterator. @@ -100,18 +99,19 @@ int main( ) *intOut = 20; *intOut = 30; } -/* Output: +``` + +```output The integers written to the output stream by intOut are: 10 20 30 -*/ ``` ## ostream_iterator::operator* -Dereferencing operator used to implement the output iterator expression \* *ii* = *x*. +Dereferencing operator used to implement the output iterator expression `*ii = x`. ```cpp ostream_iterator& operator*(); @@ -123,7 +123,7 @@ A reference to the `ostream_iterator`. ### Remarks -The requirements for an output iterator that the `ostream_iterator` must satisfy require only the expression \* *ii* = *t* be valid and says nothing about the **`operator`** or the `operator=` on their own. The member operator in this implementation returns **`*this`**. +The requirements for an output iterator that the `ostream_iterator` must satisfy require only the expression `*ii = t` be valid and says nothing about the **`operator`** or the `operator=` on their own. The member operator in this implementation returns `*this`. ### Example @@ -145,20 +145,20 @@ int main( ) // Standard iterator interface for writing // elements to the output stream cout << "Elements written to output stream:" << endl; -*intOut = 10; + *intOut = 10; intOut++; // No effect on iterator position -*intOut = 20; -*intOut = 30; + *intOut = 20; + *intOut = 30; } -/* Output: +``` +```output Elements written to output stream: 10 20 30 -*/ ``` -## ostream_iterator::operator++ +## `ostream_iterator::operator++` A nonfunctional increment operator that returns an `ostream_iterator` to the same object it addressed before the operation was called. @@ -173,7 +173,7 @@ A reference to the `ostream_iterator`. ### Remarks -These member operators both return **`*this`**. +These member operators both return `*this`. ### Example @@ -195,22 +195,23 @@ int main( ) // standard iterator interface for writing // elements to the output stream cout << "Elements written to output stream:" << endl; -*intOut = 10; + *intOut = 10; intOut++; // No effect on iterator position -*intOut = 20; -*intOut = 30; + *intOut = 20; + *intOut = 30; } -/* Output: +``` + +```output Elements written to output stream: 10 20 30 -*/ ``` -## ostream_iterator::operator= +## `ostream_iterator::operator=` -Assignment operator used to implement the output_iterator expression \* `i` = `x` for writing to an output stream. +Assignment operator used to implement the output_iterator expression `*i = x` for writing to an output stream. ```cpp ostream_iterator& operator=(const Type& val); @@ -218,16 +219,16 @@ ostream_iterator& operator=(const Type& val); ### Parameters -*val*\ +*`val`*\ The value of the object of type `Type` to be inserted into the output stream. ### Return Value -The operator inserts *val* into the output stream associated with the object, followed by the delimiter specified in the [ostream_iterator constructor](#ostream_iterator) (if any), and then returns a reference to the `ostream_iterator`. +The operator inserts *`val`* into the output stream associated with the object, followed by the delimiter specified in the [`ostream_iterator constructor`](#ostream_iterator) (if any), and then returns a reference to the `ostream_iterator`. ### Remarks -The requirements for an output iterator that the `ostream_iterator` must satisfy require only the expression \* `ii` = `t` be valid and says nothing about the operator or the operator= on their own. This member operator returns **`*this`**. +The requirements for an output iterator that the `ostream_iterator` must satisfy require only the expression `*ii = t` be valid and says nothing about the operator or the operator= on their own. This member operator returns `*this`. ### Example @@ -249,26 +250,25 @@ int main( ) // Standard iterator interface for writing // elements to the output stream cout << "Elements written to output stream:" << endl; -*intOut = 10; + *intOut = 10; intOut++; // No effect on iterator position -*intOut = 20; -*intOut = 30; + *intOut = 20; + *intOut = 30; } -/* Output: +``` +```output Elements written to output stream: 10 20 30 -*/ ``` -## ostream_iterator::ostream_iterator +## `ostream_iterator::ostream_iterator` Constructs an `ostream_iterator` that is initialized and delimited to write to the output stream. ```cpp -ostream_iterator( - ostream_type& _Ostr); +ostream_iterator(ostream_type& _Ostr); ostream_iterator( ostream_type& _Ostr, @@ -277,17 +277,17 @@ ostream_iterator( ### Parameters -*_Ostr*\ -The output stream of type [ostream_iterator::ostream_type](#ostream_type) to be iterated over. +*`_Ostr`*\ +The output stream of type [`ostream_iterator::ostream_type`](#ostream_type) to be iterated over. -*_Delimiter*\ +*`_Delimiter`*\ The delimiter that is inserted into the output stream between values. ### Remarks The first constructor initializes the output stream pointer with `&_Ostr`. The delimiter string pointer designates an empty string. -The second constructor initializes the output stream pointer with `&_Ostr` and the delimiter string pointer with *_Delimiter*. +The second constructor initializes the output stream pointer with `&_Ostr` and the delimiter string pointer with *`_Delimiter`*. ### Example @@ -304,9 +304,9 @@ int main( ) // ostream_iterator for stream cout ostream_iterator intOut ( cout , "\n" ); -*intOut = 10; + *intOut = 10; intOut++; -*intOut = 20; + *intOut = 20; intOut++; int i; @@ -328,15 +328,16 @@ int main( ) ostream_iterator ( cout, " : " ) ); cout << endl; } -/* Output: +``` + +```ouput 10 20 Elements output without delimiter: 123456 Elements output with delimiter: 1 : 2 : 3 : 4 : 5 : 6 : -*/ ``` -## ostream_iterator::ostream_type +## `ostream_iterator::ostream_type` A type that provides for the stream type of the iterator. @@ -346,13 +347,13 @@ typedef basic_ostream ostream_type; ### Remarks -The type is a synonym for [basic_ostream](../standard-library/basic-ostream-class.md)< `CharType`, `Traits`>, a stream class of the iostream hierarchy that defines objects that can be used for writing. +The type is a synonym for [`basic_ostream`](../standard-library/basic-ostream-class.md)``, a stream class of the iostream hierarchy that defines objects that can be used for writing. ### Example -See [ostream_iterator](#ostream_iterator) for an example of how to declare and use `ostream_type`. +See [`ostream_iterator`](#ostream_iterator) for an example of how to declare and use `ostream_type`. -## ostream_iterator::traits_type +## `ostream_iterator::traits_type` A type that provides for the character traits type of the iterator. @@ -393,17 +394,18 @@ int main( ) *intOut = 10; *intOut = 100; } -/* Output: +``` + +```output The integers written to output stream by intOut are: 1 10 100 -*/ ``` ## See also -[\](../standard-library/iterator.md)\ +[``](../standard-library/iterator.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ [C++ Standard Library Reference](../standard-library/cpp-standard-library-reference.md) diff --git a/docs/standard-library/ostream-operators.md b/docs/standard-library/ostream-operators.md index 6b1d575283a..566531288c6 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 fd4844f2c2e..7ace186c98e 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/ostreambuf-iterator-class.md b/docs/standard-library/ostreambuf-iterator-class.md index dea0af412dd..dd59e727723 100644 --- a/docs/standard-library/ostreambuf-iterator-class.md +++ b/docs/standard-library/ostreambuf-iterator-class.md @@ -1,28 +1,27 @@ --- -description: "Learn more about: ostreambuf_iterator Class" title: "ostreambuf_iterator Class" -ms.date: "11/04/2016" +description: "Learn more about: ostreambuf_iterator Class" +ms.date: 11/04/2016 f1_keywords: ["streambuf/std::ostreambuf_iterator", "iterator/std::ostreambuf_iterator::char_type", "iterator/std::ostreambuf_iterator::ostream_type", "iterator/std::ostreambuf_iterator::streambuf_type", "iterator/std::ostreambuf_iterator::traits_type", "iterator/std::ostreambuf_iterator::failed"] helpviewer_keywords: ["std::ostreambuf_iterator [C++]", "std::ostreambuf_iterator [C++], char_type", "std::ostreambuf_iterator [C++], ostream_type", "std::ostreambuf_iterator [C++], streambuf_type", "std::ostreambuf_iterator [C++], traits_type", "std::ostreambuf_iterator [C++], failed"] -ms.assetid: dad1e624-2f45-4e94-8887-a885e95f9071 --- -# ostreambuf_iterator Class +# `ostreambuf_iterator` class -The class template ostreambuf_iterator describes an output iterator object that writes successive character elements onto the output stream with the extraction **operator>>**. The `ostreambuf_iterator`s differ from those of the [ostream_iterator Class](../standard-library/ostream-iterator-class.md) in having characters instead of a generic type at the type of object being inserted into the output stream. +The class template `ostreambuf_iterator` describes an output iterator object that writes successive character elements onto the output stream with the extraction `operator>>`. The `ostreambuf_iterator`s differ from those of the [`ostream_iterator` Class](../standard-library/ostream-iterator-class.md) in having characters instead of a generic type at the type of object being inserted into the output stream. ## Syntax ```cpp -template > +template > ``` ### Parameters -*CharType*\ +*`CharType`*\ The type that represents the character type for the ostreambuf_iterator. This argument is optional and the default value is **`char`**. -*Traits*\ -The type that represents the character type for the ostreambuf_iterator. This argument is optional and the default value is `char_traits`\< *CharType>.* +*`Traits`*\ +The type that represents the character type for the ostreambuf_iterator. This argument is optional and the default value is `char_traits`. ## Remarks @@ -32,38 +31,38 @@ The ostreambuf_iterator class must satisfy the requirements for an output iterat |Constructor|Description| |-|-| -|[ostreambuf_iterator](#ostreambuf_iterator_ostreambuf_iterator)|Constructs an `ostreambuf_iterator` that is initialized to write characters to the output stream.| +|[`ostreambuf_iterator`](#ostreambuf_iterator_ostreambuf_iterator)|Constructs an `ostreambuf_iterator` that is initialized to write characters to the output stream.| ### Typedefs |Type name|Description| |-|-| -|[char_type](#char_type)|A type that provides for the character type of the `ostreambuf_iterator`.| -|[ostream_type](#ostreambuf_iterator_ostream_type)|A type that provides for the stream type of the `ostream_iterator`.| -|[streambuf_type](#streambuf_type)|A type that provides for the stream type of the `ostreambuf_iterator`.| -|[traits_type](#traits_type)|A type that provides for the character traits type of the `ostream_iterator`.| +|[`char_type`](#char_type)|A type that provides for the character type of the `ostreambuf_iterator`.| +|[`ostream_type`](#ostreambuf_iterator_ostream_type)|A type that provides for the stream type of the `ostream_iterator`.| +|[`streambuf_type`](#streambuf_type)|A type that provides for the stream type of the `ostreambuf_iterator`.| +|[`traits_type`](#traits_type)|A type that provides for the character traits type of the `ostream_iterator`.| ### Member functions |Member function|Description| |-|-| -|[failed](#failed)|Tests for failure of an insertion into the output stream buffer.| +|[`failed`](#failed)|Tests for failure of an insertion into the output stream buffer.| ### Operators |Operator|Description| |-|-| -|[operator*](#op_star)|Dereferencing operator used to implement the output iterator expression \* `i` = `x`.| -|[operator++](#op_add_add)|A nonfunctional increment operator that returns an `ostreambuf_iterator` to the same object it addressed before the operation was called.| -|[operator=](#op_eq)|The operator inserts a character into the associated stream buffer.| +|[`operator*`](#op_star)|Dereferencing operator used to implement the output iterator expression `*i = x`.| +|[`operator++`](#op_add_add)|A nonfunctional increment operator that returns an `ostreambuf_iterator` to the same object it addressed before the operation was called.| +|[`operator=`](#op_eq)|The operator inserts a character into the associated stream buffer.| ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` -## ostreambuf_iterator::char_type +## `ostreambuf_iterator::char_type` A type that provides for the character type of the `ostreambuf_iterator`. @@ -99,21 +98,21 @@ int main( ) // elements to the output streambuf: cout << "The characters written to the output stream\n" << " by charOutBuf are: "; -*charOutBuf = 'O'; + *charOutBuf = 'O'; charOutBuf++; -*charOutBuf = 'U'; + *charOutBuf = 'U'; charOutBuf++; -*charOutBuf = 'T'; + *charOutBuf = 'T'; charOutBuf++; cout << "." << endl; } -/* Output: -The characters written to the output stream -by charOutBuf are: OUT. -*/ ``` -## ostreambuf_iterator::failed +```output +OUT. +``` + +## `ostreambuf_iterator::failed` Tests for failure of an insertion into the output stream buffer. @@ -127,7 +126,7 @@ bool failed() const throw(); ### Remarks -The member function returns **`true`** if, in any prior use of member `operator=`, the call to **subf**_-> `sputc` returned **eof**. +The member function returns **`true`** if any prior attempt to insert a character into the output stream buffer was unsuccessful. ### Example @@ -145,11 +144,11 @@ int main( ) // ostreambuf_iterator for stream cout ostreambuf_iterator charOut ( cout ); -*charOut = 'a'; + *charOut = 'a'; charOut ++; -*charOut = 'b'; + *charOut = 'b'; charOut ++; -*charOut = 'c'; + *charOut = 'c'; cout << " are characters output individually." << endl; bool b1 = charOut.failed ( ); @@ -158,15 +157,16 @@ int main( ) else cout << "No insertions failed." << endl; } -/* Output: +``` + +```output abc are characters output individually. No insertions failed. -*/ ``` -## ostreambuf_iterator::operator\* +## `ostreambuf_iterator::operator*` -A nonfunctional dereferencing operator used to implement the output iterator expression \* *i* = *x*. +A nonfunctional dereferencing operator used to implement the output iterator expression `*i = x`. ```cpp ostreambuf_iterator& operator*(); @@ -178,7 +178,7 @@ The ostreambuf iterator object. ### Remarks -This operator functions only in the output iterator expression \* *i* = *x* to output characters to stream buffer. Applied to an ostreambuf iterator, it returns the iterator; **\*iter** returns **iter**, +This operator functions only in the output iterator expression `*i = x` to output characters to stream buffer. Applied to an `ostreambuf_iterator`, it returns the iterator; `*iter` returns `iter`. ### Example @@ -189,7 +189,7 @@ This operator functions only in the output iterator expression \* *i* = *x* to o #include #include -int main( ) +int main() { using namespace std; @@ -200,20 +200,21 @@ int main( ) // Standard iterator interface for writing // elements to the output stream cout << "Elements written to output stream:" << endl; -*charOutBuf = 'O'; + *charOutBuf = 'O'; charOutBuf++; // no effect on iterator position -*charOutBuf = 'U'; -*charOutBuf = 'T'; + *charOutBuf = 'U'; + *charOutBuf = 'T'; } -/* Output: +``` + +```output Elements written to output stream: OUT -*/ ``` -## ostreambuf_iterator::operator++ +## `ostreambuf_iterator::operator++` -A nonfunctional increment operator that returns an ostream iterator to the same character it addressed before the operation was called. +A nonfunctional increment operator that returns an `ostreambuf_iterator` to the same character it addressed before the operation was called. ```cpp ostreambuf_iterator& operator++(); @@ -222,11 +223,11 @@ ostreambuf_iterator& operator++(int); ### Return Value -A reference to the character originally addressed or to an implementation-defined object that is convertible to `ostreambuf_iterator`\< **CharType**, **Traits**>. +A reference to the character originally addressed or to an implementation-defined object that is convertible to `ostreambuf_iterator< CharType, Traits>`. ### Remarks -The operator is used to implement the output iterator expression \* *i* = *x*. +The operator is used to implement the output iterator expression `*i = x`. ### Example @@ -248,18 +249,19 @@ int main( ) // Standard iterator interface for writing // elements to the output stream cout << "Elements written to output stream:" << endl; -*charOutBuf = 'O'; + *charOutBuf = 'O'; charOutBuf++; // No effect on iterator position -*charOutBuf = 'U'; -*charOutBuf = 'T'; + *charOutBuf = 'U'; + *charOutBuf = 'T'; } -/* Output: +``` + +```output Elements written to output stream: OUT -*/ ``` -## ostreambuf_iterator::operator= +## `ostreambuf_iterator::operator=` The operator inserts a character into the associated stream buffer. @@ -269,7 +271,7 @@ ostreambuf_iterator& operator=(CharType _Char); ### Parameters -*_Char*\ +*`_Char`*\ The character to be inserted into the stream buffer. ### Return Value @@ -278,7 +280,7 @@ A reference to the character inserted into the stream buffer. ### Remarks -Assignment operator used to implement the output iterator expression \* *i* = *x* for writing to an output stream. +Assignment operator used to implement the output iterator expression `*i = x` for writing to an output stream. ### Example @@ -300,18 +302,19 @@ int main( ) // Standard iterator interface for writing // elements to the output stream cout << "Elements written to output stream:" << endl; -*charOutBuf = 'O'; + *charOutBuf = 'O'; charOutBuf++; // No effect on iterator position -*charOutBuf = 'U'; -*charOutBuf = 'T'; + *charOutBuf = 'U'; + *charOutBuf = 'T'; } -/* Output: +``` + +```output Elements written to output stream: OUT -*/ ``` -## ostreambuf_iterator::ostreambuf_iterator +## `ostreambuf_iterator::ostreambuf_iterator` Constructs an `ostreambuf_iterator` that is initialized to write characters to the output stream. @@ -322,17 +325,17 @@ ostreambuf_iterator(ostream_type& Ostr) throw(); ### Parameters -*strbuf*\ +*`strbuf`*\ The output streambuf object used to initialize the output stream-buffer pointer. -*Ostr*\ +*`Ostr`*\ The output stream object used to initialize the output stream-buffer pointer. ### Remarks -The first constructor initializes the output stream-buffer pointer with *strbuf*. +The first constructor initializes the output stream-buffer pointer with *`strbuf`*. -The second constructor initializes the output stream-buffer pointer with `Ostr`. `rdbuf`. The stored pointer must not be a null pointer. +The second constructor initializes the output stream-buffer pointer with *`Ostr.rdbuf`. The stored pointer must not be a null pointer. ### Example @@ -343,31 +346,32 @@ The second constructor initializes the output stream-buffer pointer with `Ostr`. #include #include -int main( ) +int main() { using namespace std; // ostreambuf_iterator for stream cout ostreambuf_iterator charOut ( cout ); -*charOut = 'O'; + *charOut = 'O'; charOut ++; -*charOut = 'U'; + *charOut = 'U'; charOut ++; -*charOut = 'T'; + *charOut = 'T'; cout << " are characters output individually." << endl; ostreambuf_iterator strOut ( cout ); string str = "These characters are being written to the output stream.\n "; copy ( str.begin ( ), str. end ( ), strOut ); } -/* Output: +``` + +```output OUT are characters output individually. These characters are being written to the output stream. -*/ ``` -## ostreambuf_iterator::ostream_type +## `ostreambuf_iterator::ostream_type` A type that provides for the stream type of the `ostream_iterator`. @@ -377,13 +381,13 @@ typedef basicOstream ostream_type; ### Remarks -The type is a synonym for `basicOstream`\< **CharType**, **Traits**> +The type is a synonym for `basicOstream< CharType, Traits>` ### Example -See [ostreambuf_iterator](#ostreambuf_iterator_ostreambuf_iterator) for an example of how to declare and use `ostream_type`. +See [`ostreambuf_iterator`](#ostreambuf_iterator_ostreambuf_iterator) for an example of how to declare and use `ostream_type`. -## ostreambuf_iterator::streambuf_type +## `ostreambuf_iterator::streambuf_type` A type that provides for the stream type of the `ostreambuf_iterator`. @@ -393,13 +397,13 @@ typedef basic_streambuf streambuf_type; ### Remarks -The type is a synonym for `basic_streambuf`\< **CharType**, **Traits**>, a stream class for I/O buffers that becomes `streambuf` when specialized to character type **`char`**. +The type is a synonym for `basic_streambuf< CharType, Traits>`, a stream class for I/O buffers that becomes `streambuf` when specialized to character type **`char`**. ### Example -See [ostreambuf_iterator](#ostreambuf_iterator_ostreambuf_iterator) for an example of how to declare and use `streambuf_type`. +See [`ostreambuf_iterator`](#ostreambuf_iterator_ostreambuf_iterator) for an example of how to declare and use `streambuf_type`. -## ostreambuf_iterator::traits_type +## `ostreambuf_iterator::traits_type` A type that provides for the character traits type of the `ostream_iterator`. @@ -435,18 +439,19 @@ int main( ) // elements to the output streambuf: cout << "The characters written to the output stream\n" << " by charOutBuf are: "; -*charOutBuf = 'O'; + *charOutBuf = 'O'; charOutBuf++; -*charOutBuf = 'U'; + *charOutBuf = 'U'; charOutBuf++; -*charOutBuf = 'T'; + *charOutBuf = 'T'; charOutBuf++; cout << "." << endl; } -/* Output: +``` + +```output The characters written to the output stream by charOutBuf are: OUT. -*/ ``` ## See also diff --git a/docs/standard-library/ostrstream-class.md b/docs/standard-library/ostrstream-class.md index c9b7a0acaf3..567245feb6b 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/other-one-argument-output-stream-manipulators.md b/docs/standard-library/other-one-argument-output-stream-manipulators.md index 0807ff915eb..8495a513707 100644 --- a/docs/standard-library/other-one-argument-output-stream-manipulators.md +++ b/docs/standard-library/other-one-argument-output-stream-manipulators.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Other One-Argument Output Stream Manipulators" title: "Other One-Argument Output Stream Manipulators" -ms.date: "11/04/2016" +description: "Learn more about: Other One-Argument Output Stream Manipulators" +ms.date: 11/04/2016 helpviewer_keywords: ["output streams, one-argument manipulators"] -ms.assetid: e381dee8-6b16-4cef-805a-4a6a1d2b696b --- # Other One-Argument Output Stream Manipulators @@ -51,7 +50,7 @@ void fb( ios_base& os, char * somename ) { for( int i=0; i < l; i++ ) (*pos) << ' '; - }; + } */ } diff --git a/docs/standard-library/out-of-range-class.md b/docs/standard-library/out-of-range-class.md index 0fb2d3cb673..cf5e79dfc81 100644 --- a/docs/standard-library/out-of-range-class.md +++ b/docs/standard-library/out-of-range-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: out_of_range Class" -title: "out_of_range Class" -ms.date: "09/09/2021" +title: "out_of_range class" +description: "Learn more about: out_of_range class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::out_of_range"] helpviewer_keywords: ["out_of_range class"] -ms.assetid: d0e14dc0-065e-4666-9ac9-51e52223c503 --- -# out_of_range Class +# `out_of_range` class The class serves as the base class for all exceptions thrown to report an argument that is out of its valid range. @@ -18,13 +17,12 @@ public: explicit out_of_range(const string& message); explicit out_of_range(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). ## Example @@ -52,19 +50,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: invalid string position Type: class std::out_of_range -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[logic_error Class](../standard-library/logic-error-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`logic_error` class](logic-error-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/output-file-stream-member-functions.md b/docs/standard-library/output-file-stream-member-functions.md index f01b65202bf..6c7902a6244 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 a6e926d4bd9..c4dae468e4b 100644 --- a/docs/standard-library/output-iterator-tag-struct.md +++ b/docs/standard-library/output-iterator-tag-struct.md @@ -12,7 +12,9 @@ A class that provides a return type for `iterator_category` function that repres ## Syntax +```cpp struct output_iterator_tag {}; +``` ## Remarks diff --git a/docs/standard-library/output-stream-manipulators-with-one-argument-int-or-long.md b/docs/standard-library/output-stream-manipulators-with-one-argument-int-or-long.md index 1c3cb51e5e9..ee87da5f214 100644 --- a/docs/standard-library/output-stream-manipulators-with-one-argument-int-or-long.md +++ b/docs/standard-library/output-stream-manipulators-with-one-argument-int-or-long.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: Output Stream Manipulators with One Argument (int or long)" title: "Output Stream Manipulators with One Argument (int or long)" -ms.date: "11/04/2016" +description: "Learn more about: Output Stream Manipulators with One Argument (int or long)" +ms.date: 11/04/2016 helpviewer_keywords: ["output streams, int or long argument manipulators"] -ms.assetid: 338f3164-b5e2-4c5a-a605-7d9dc3629ca1 --- # Output Stream Manipulators with One Argument (int or long) @@ -25,7 +24,7 @@ void fb( ios_base& os, int l ) { for( int i=0; i < l; i++ ) (*pos) << ' '; - }; + } } _Smanip diff --git a/docs/standard-library/overflow-error-class.md b/docs/standard-library/overflow-error-class.md index 0ba3c520d48..b4291d01a31 100644 --- a/docs/standard-library/overflow-error-class.md +++ b/docs/standard-library/overflow-error-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: overflow_error Class" -title: "overflow_error Class" -ms.date: "09/09/2021" +title: "overflow_error class" +description: "Learn more about: overflow_error class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::overflow_error"] helpviewer_keywords: ["overflow_error class"] -ms.assetid: bae7128d-e36b-4a45-84f1-2f89da441d20 --- -# overflow_error Class +# `overflow_error` class The class serves as the base class for all exceptions thrown to report an arithmetic overflow. @@ -18,13 +17,12 @@ public: explicit overflow_error(const string& message); explicit overflow_error(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). ## Example @@ -52,19 +50,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: bitset overflow Type: class std::overflow_error -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[runtime_error Class](../standard-library/runtime-error-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`runtime_error` class](runtime-error-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/owning-view-class.md b/docs/standard-library/owning-view-class.md new file mode 100644 index 00000000000..fec32d4b6b5 --- /dev/null +++ b/docs/standard-library/owning-view-class.md @@ -0,0 +1,309 @@ +--- +title: owning_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) owning_view class, which takes ownership of the elements in a range." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::owning_view", "ranges/std::owning_view::base", "ranges/std::owning_view::begin", "ranges/std::owning_view::end", "ranges/std::owning_view::size", "ranges/std::owning_view::empty", "ranges/std::owning_view::operator bool", "ranges/std::owning_view::data", "ranges/std::owning_view::back", "ranges/std::owning_view::front", "ranges/std::owning_view::operator[]", "ranges/std::owning_view::operator="] +helpviewer_keywords: ["std::ranges::owning_view [C++]", "std::ranges::owning_view [C++], base", "std::ranges::owning_view [C++], begin", "std::ranges::owning_view [C++], end", "std::ranges::owning_view [C++], size", "std::ranges::owning_view [C++], data", "std::ranges::owning_view [C++], empty", "std::ranges::owning_view [C++], operator bool", "std::ranges::owning_view [C++], front", "std::ranges::owning_view [C++], back", "std::ranges::owning_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `owning_view` class (C++ Standard Library) + +A view that takes ownership of the elements in another range. + +## Syntax + +```cpp +template + requires std::movable && (!is-initializer-list) +class owning_view : public ranges::view_interface>; +``` + +### Template parameters + +*`R`*\ +The type of the underlying range. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::all`](range-adaptors.md#all) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct an `owning_view`. | +| [`base`](#base)C++20 | Get a reference to the owned range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`data`](#data)C++20 | Get a pointer to the first element. | +| [`empty`](#empty)C++20 | Test whether the view is empty. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. | +| [`operator=`](#assignment_operator) | Assign (move) the contents from another `owning_view` to this one. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Remarks + +The best way to create an `owning_view` is by using the [`views::all`](range-adaptors.md#all) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +Even though this class owns its elements, it's not expensive to construct because the underlying range is moved using `std::move()`. + +This view is useful when you want a range that doesn't depend on the lifetime of the container providing the elements. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `owning_view`. + +```cpp +1) owning_view() requires default_initializable = default; +2) constexpr owning_view(R&& rg); +3) owning_view(const owning_view& v) = delete; // no copy constructor +4) owning_view(const owning_view&& v) = default; // move constructor +``` + +### Parameters + +*`rg`*\ +The range to move to the `owning_view`. + +*`v`*\ +The `owning_view` to move to the new `owning_view`. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Remarks + +1\) The default constructor creates a default-initialized `owning_view`.\ +2\) Move constructs the `owning_view` from *`rg`*.\ +3\) An `owning_view` can't be copied, only moved.\ +4\) Construct the `owning_view` from another `owning_view`. + +### Example: `owning_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3,4,5,6,7,8,9,10}; + auto myOwningView = std::views::all(std::move(v)); // create an owning_view from a moved vector + std::cout << v.size() << '\n'; // outputs 0 because myOwningView now owns the elements + std::cout << myOwningView.size() << '\n'; // outputs 10 + + std::vector v2 = {1,2,3,4,5}; + std::ranges::owning_view> ov2{std::move(v2)}; + std::cout << v2.size() << '\n'; // outputs 0 because ov2 now owns the elements + std::cout << ov2.size() << '\n'; // outputs 5 +} +``` + +```output +0 +10 +0 +5 +``` + +## `base` + +Gets a reference to the underlying range. + +```cpp +1) constexpr R& base() & noexcept { return r_; } +2) constexpr const R& base() const & noexcept { return r_; } +3) constexpr R&& base() && noexcept { return std::move(r_); } +4) constexpr const R&& base() const && noexcept { return std::move(r_); } +``` + +### Parameters + +None. + +### Return value + +A reference to the underlying range, call it *`rg`*.\ +For 1 & 2, the underlying range is returned via `return rg;`\ +For 3 & 4, the underlying range is returned via `std::move(rg);` + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr iterator_t begin(); +constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `data` + +Get a pointer to the first element in the view. + +```cpp +constexpr auto data() + requires std::contiguous_iterator>; +constexpr auto data() const + requires std::contiguous_iterator>; +``` + +### Parameters + +None. + +### Return value + +A pointer to the first element in the view. + +### Remarks + +The underlying owned range must satisfy `contiguous_range`. + +## `empty` + +Test whether the view is empty. + +```cpp +constexpr bool empty(); +constexpr bool empty() const; +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the underlying range has no elements. Otherwise, returns `false`. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr sentinel_t end(); +constexpr auto end() const requires range +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the view. + +## `operator=` + +Assign (move) the contents from another `owning_view` to this one. + +```cpp +owning_view& operator=(owning_view&&) = default; +``` + +### Parameters + +The `owning_view` to assign (move) to this one. + +### Return value + +`*this` + +### Remarks + +An `owning_view` can't be copied, only moved. + +### Example: `operator=` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v1 = {1,2,3}; + std::ranges::owning_view> ov1{std::move(v1)}; + + std::vector v2 = {4,5,6}; + std::ranges::owning_view> ov2{std::move(v2)}; + + // operator= + ov2 = std::move(ov1); + + // ov1 took ownership of v1, so v1 is empty + // ov2 took ownership of v2, so v2 is empty + // ov2 then took ownership of ov1, so ov1 is empty + // ov2 now owns the elements 1, 2, 3 + + std::cout << std::boolalpha << "v1.empty():" << v1.empty() << " ov1.empty():" << ov1.empty() << '\n'; // v1.empty():true ov1.empty():true + std::cout << "v2.empty():" << v2.empty() << " ov2.size():" << ov2.size() << '\n'; // v2.empty():true ov2.size():3 + + for (auto e : ov2) + { + std::cout << e << ' '; // 1 2 3 + } +} +``` + +```output +v1.empty():true ov1.empty():true +v2.empty():true ov2.size():3 +1 2 3 +``` + +## See also + +[``](ranges.md)\ +[`all` range adaptor](range-adaptors.md#all)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/parallel-policy-class.md b/docs/standard-library/parallel-policy-class.md index 1e5a6cd9cd6..892f8f12a1d 100644 --- a/docs/standard-library/parallel-policy-class.md +++ b/docs/standard-library/parallel-policy-class.md @@ -6,7 +6,7 @@ f1_keywords: ["execution/std::execution::parallel_policy"] --- # parallel_policy Class -Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be parallelized. +Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be parallelized. ## Syntax diff --git a/docs/standard-library/parallel-unsequenced-policy-class.md b/docs/standard-library/parallel-unsequenced-policy-class.md index 53ca538f2e3..d9b3d3d14a0 100644 --- a/docs/standard-library/parallel-unsequenced-policy-class.md +++ b/docs/standard-library/parallel-unsequenced-policy-class.md @@ -6,7 +6,7 @@ f1_keywords: ["execution/std::execution::parallel_unsequenced_policy"] --- # parallel_unsequenced_policy Class -Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm’s execution may be parallelized and vectorized. +Used as a unique type to disambiguate parallel algorithm overloading and indicate that a parallel algorithm's execution may be parallelized and vectorized. ## Syntax diff --git a/docs/standard-library/path-class.md b/docs/standard-library/path-class.md index 51581684455..8f7edbb9c17 100644 --- a/docs/standard-library/path-class.md +++ b/docs/standard-library/path-class.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: path Class" title: "path Class" +description: "Learn more about: path Class" ms.date: 06/17/2022 f1_keywords: ["filesystem/std::experimental::filesystem::path"] -ms.custom: devdivchpfy22 --- # `path` Class @@ -42,7 +41,7 @@ class path; |[`c_str`](#c_str)|Returns a pointer to the first character in `mypath`.| |[`clear`](#clear)|Executes `mypath.clear()`.| |[`compare`](#compare)|Returns comparison values.| -|[`concat`](#compare)|Appends the specified sequence to `mypath`, converted (but not inserting a separator) as needed.| +|[`concat`](#concat)|Appends the specified sequence to `mypath`, converted (but not inserting a separator) as needed.| |[`empty`](#empty)|Returns `mypath.empty()`.| |[`end`](#end)|Returns an end-of-sequence iterator of type `iterator`.| |[`extension`](#extension)|Returns the suffix of `filename()`.| @@ -63,7 +62,7 @@ class path; |[`is_absolute`](#is_absolute)|For Windows, the function returns `has_root_name() && has_root_directory()`. For POSIX, the function returns `has_root_directory()`.| |[`is_relative`](#is_relative)|Returns `!is_absolute()`.| |[`make_preferred`](#make_preferred)|Converts each separator to a `preferred_separator` as needed.| -|[`native`](#native)|Returns `myname`.| +|[`native`](#native)|Returns the native representation of the path.| |[`parent_path`](#parent_path)|Returns the parent path component of `myname`.| |[`preferred_separator`](#preferred_separator)|The constant object gives the preferred character for separating path components, depending on the host operating system. | |[`relative_path`](#relative_path)|Returns the relative path component of `myname`. | @@ -436,12 +435,30 @@ path& make_preferred(); ## `path::native` -Returns `myname`. +Get the native string representation of the path. ```cpp const string_type& native() const noexcept; ``` +### Remarks + +The path is available in a portable generic format (see [`generic_string()`](#generic_string)) or the native format of the path. This function returns the native string. On a POSIX system, the generic format and the native format are the same. + +In the following example running on Windows 11, the generic path string is `c:/t/temp/temp.txt` and the native string is `c:\\t\\temp.txt` + +```cpp +// Compile with /std:c++17 or higher +#include + +int main() +{ + std::filesystem::path p(R"(c:\t\temp.txt)"); + auto native = p.native(); // Windows: L"c:\\t\temp.txt" + auto generic = p.generic_string(); // Windows: "c:/t/temp.txt" +} +``` + ## `path::operator=` Replaces the elements of the path with a copy of another path. diff --git a/docs/standard-library/plus-struct.md b/docs/standard-library/plus-struct.md index 0d6c8c3b368..2224d1cae1d 100644 --- a/docs/standard-library/plus-struct.md +++ b/docs/standard-library/plus-struct.md @@ -24,7 +24,7 @@ template <> struct plus { template - auto operator()(T&& Left, U&& Right) const` + auto operator()(T&& Left, U&& Right) const -> decltype(std::forward(Left) + std::forward(Right)); }; ``` diff --git a/docs/standard-library/priority-queue-class.md b/docs/standard-library/priority-queue-class.md index 8e22659fb47..54de3d14480 100644 --- a/docs/standard-library/priority-queue-class.md +++ b/docs/standard-library/priority-queue-class.md @@ -1,13 +1,13 @@ --- description: "Learn more about: priority_queue Class" title: "priority_queue Class" -ms.date: "11/04/2016" +ms.date: 01/18/2026 f1_keywords: ["queue/std::priority_queue::container_type", "queue/std::priority_queue::size_type", "queue/std::priority_queue::value_type", "queue/std::priority_queue::empty", "queue/std::priority_queue::pop", "queue/std::priority_queue::push", "queue/std::priority_queue::size", "queue/std::priority_queue::top"] helpviewer_keywords: ["std::priority_queue [C++], container_type", "std::priority_queue [C++], size_type", "std::priority_queue [C++], value_type", "std::priority_queue [C++], empty", "std::priority_queue [C++], pop", "std::priority_queue [C++], push", "std::priority_queue [C++], size", "std::priority_queue [C++], top"] --- -# `priority_queue` Class +# `priority_queue` class -A template container adaptor class that provides a restriction of functionality limiting access to the top element of some underlying container type, which is always the largest or of the highest priority. New elements can be added to the `priority_queue` and the top element of the `priority_queue` can be inspected or removed. +A container adaptor that maintains a collection of elements where the largest (or highest priority) element is always accessible at the top. You can add new elements and remove or examine the top element, but you can't directly access elements in the middle of the collection. ## Syntax @@ -19,31 +19,40 @@ class priority_queue ### Parameters *`Type`*\ -The element data type to be stored in the `priority_queue`. +The element data type to store in the `priority_queue`. *`Container`*\ -The type of the underlying container used to implement the `priority_queue`. +The type of the underlying container that stores the elements for the `priority_queue`. *`Compare`*\ -The type that provides a function object that can compare two element values as sort keys to determine their relative order in the `priority_queue`. This argument is optional and the binary predicate `less` is the default value. +The type that provides a function object that compares two element values as sort keys to determine their relative order in the `priority_queue`. This argument is optional. The binary predicate `less` is the default. ## Remarks -The elements of class `Type` stipulated in the first template parameter of a queue object are synonymous with [`value_type`](#value_type) and must match the type of element in the underlying container class `Container` stipulated by the second template parameter. The `Type` must be assignable, so that it's possible to copy objects of that type and to assign values to variables of that type. +Elements of class `Type` specified in the first template parameter of a `priority_queue` object are equivalent to [`value_type`](#value_type) and must match the element type in the underlying container class `Container` specified by the second template parameter. The `Type` must be assignable, which means you can copy objects of that type and assign values to variables of that type. -The `priority_queue` orders the sequence it controls by calling a stored function object of class `Traits`. In general, the elements need be merely less than comparable to establish this order: so that, given any two elements, it may be determined either that they'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. +The `priority_queue` uses a comparison function to determine which elements have higher priority. This comparison function is a function object of class `Traits`. To work with `priority_queue`, your elements only need to support comparison using the less-than operator (`<`) so that it can arrange the elements in order. -Suitable underlying container classes for `priority_queue` include [`deque` Class](../standard-library/deque-class.md) and the default [`vector` Class](../standard-library/vector-class.md) or any other sequence container that supports the operations of `front`, `push_back`, and `pop_back` and a random-access iterator. The underlying container class is encapsulated within the container adaptor, which exposes only the limited set of the sequence container member functions as a public interface. +You can change the underlying container type used by the `priority_queue`. You may want to do that for performance reasons. The default, `vector`, is usually best for cache locality because elements are stored in contiguous storage, and does fewer allocations as it grows. But perhaps you would consider `deque` if you have very large or unbounded queues and moving elements is expensive. For more information about suitable underlying container classes, see [container_type](#container_type). -Adding elements to and removing elements from a `priority_queue` both have logarithmic complexity. Accessing elements in a `priority_queue` has constant complexity. +Adding and removing elements from a `priority_queue` both have logarithmic complexity. Accessing elements in a `priority_queue` has constant complexity. -There are three types of container adaptors defined by the C++ Standard Library: `stack`, `queue`, and `priority_queue`. Each restricts the functionality of some underlying container class to provide a precisely controlled interface to a standard data structure. +The C++ Standard Library defines other container adaptors that you can use to store the elements in your `priority_queue`: `stack`, `queue`, and `priority_queue`: -- The [`stack` Class](../standard-library/stack-class.md) supports a last-in, first-out (LIFO) data structure. A good analogue to keep in mind would be a stack of plates. Elements (plates) may be inserted, inspected, or removed only from the top of the stack, which is the last element at the end of the base container. The restriction to accessing only the top element is the reason for using the `stack` class. +- The [`stack` Class](../standard-library/stack-class.md) supports a last-in, first-out (LIFO) data structure. Consider a stack of plates: you can insert, inspect, or remove elements (plates) only from the top of the stack, which is the last element at the end of the base container. +- The [`queue` Class](../standard-library/queue-class.md) supports a first-in, first-out (FIFO) data structure. Consider people in a line. You add elements (people) to the back of the line and remove them from the front of the line. Both the front and the back of a line can be inspected. +- The `priority_queue` class orders its elements so that the largest element is always at the top. It supports insertion of an element and the inspection and removal of the top element. -- The [`queue` Class](../standard-library/queue-class.md) supports a first-in, first-out (FIFO) data structure. A good analogue to keep in mind would be people lining up for a bank teller. Elements (people) may be added to the back of the line and are removed from the front of the line. Both the front and the back of a line may be inspected. The restriction to accessing only the front and back elements in this way is the reason for using the `queue` class. +## Examples -- The `priority_queue` class orders its elements so that the largest element is always at the top position. It supports insertion of an element and the inspection and removal of the top element. A good analogue to keep in mind would be people lining up where they're arranged by age, height, or some other criterion. +- [Check if the `priority_queue` is empty](#check-if-a-priority_queue-is-empty) +- [Pop elements and check queue size](#pop-elements-and-inspect-size) +- [Use custom containers and comparers](#construct-priority_queue-with-custom-containers-and-comparers) +- [Push elements and read the top](#push-elements-and-read-the-top) +- [Get the number of elements](#get-priority_queue-size) +- [Access the top element](#access-the-top-element) +- [Use the priority_queue value_type alias](#use-the-priority_queue-value_type-alias) +- [Use a user-defined data type](#use-a-user-defined-data-type-with-the-priority_queue) ### Constructors @@ -55,7 +64,7 @@ There are three types of container adaptors defined by the C++ Standard Library: |Type name|Description| |-|-| -|[`container_type`](#container_type)|A type that provides the base container to be adapted by a `priority_queue`.| +|[`container_type`](#container_type)|A type that provides the base container that the `priority_queue` adapts.| |[`size_type`](#size_type)|An unsigned integer type that can represent the number of elements in a `priority_queue`.| |[`value_type`](#value_type)|A type that represents the type of object stored as an element in a `priority_queue`.| @@ -85,13 +94,11 @@ typedef Container container_type; ### Remarks -The type is a synonym for the template parameter `Container`. The C++ Standard Library sequence container class `deque` and the default class `vector` meet the requirements to be used as the base container for a `priority_queue` object. User-defined types satisfying the requirements may also be used. +The type is a synonym for the template parameter `Container`. -For more information on `Container`, see the Remarks section of the [`priority_queue` Class](../standard-library/priority-queue-class.md) topic. +Suitable underlying container classes for `priority_queue` include [`deque` Class](../standard-library/deque-class.md), the default [`vector` Class](../standard-library/vector-class.md), or any other sequence container that supports the operations of `front`, `push_back`, and `pop_back` and a random-access iterator. The container adaptor encapsulates the underlying container class and exposes only a limited set of the sequence container member functions as a public interface. -### Example - -See the example for [`priority_queue`](#priority_queue) for an example of how to declare and use `container_type`. +For an example of how to declare and use `container_type`, see [Use custom containers and comparers](#construct-priority_queue-with-custom-containers-and-comparers) ## `priority_queue::empty` @@ -105,29 +112,28 @@ bool empty() const; **`true`** if the `priority_queue` is empty; **`false`** if the `priority_queue` is nonempty. -### Example +### Example: Check if the `priority_queue` is empty ```cpp -// pqueue_empty.cpp // compile with: /EHsc #include #include -int main( ) +int main() { using namespace std; // Declares priority_queues with default deque base container priority_queue q1, s2; - q1.push( 1 ); + q1.push(1); - if ( q1.empty( ) ) + if (q1.empty()) cout << "The priority_queue q1 is empty." << endl; else cout << "The priority_queue q1 is not empty." << endl; - if ( s2.empty( ) ) + if (s2.empty()) cout << "The priority_queue s2 is empty." << endl; else cout << "The priority_queue s2 is not empty." << endl; @@ -149,42 +155,38 @@ void pop(); ### Remarks -The `priority_queue` must be nonempty to apply the member function. The top of the `priority_queue` is always occupied by the largest element in the container. +The `priority_queue` must be nonempty to use this member function. The top of the `priority_queue` always holds the largest element in the container. -### Example +### Example: Pop elements and check size ```cpp -// pqueue_pop.cpp // compile with: /EHsc #include #include -int main( ) +int main() { using namespace std; priority_queue q1, s2; - q1.push( 10 ); - q1.push( 20 ); - q1.push( 30 ); + q1.push(10); + q1.push(20); + q1.push(30); priority_queue ::size_type i, iii; - i = q1.size( ); + i = q1.size(); cout << "The priority_queue length is " << i << "." << endl; - const int& ii = q1.top( ); - cout << "The element at the top of the priority_queue is " - << ii << "." << endl; + const int& ii = q1.top(); + cout << "The element at the top of the priority_queue is " << ii << "." << endl; - q1.pop( ); + q1.pop(); - iii = q1.size( ); - cout << "After a pop, the priority_queue length is " - << iii << "." << endl; + iii = q1.size(); + cout << "After a pop, the priority_queue length is " << iii << "." << endl; - const int& iv = q1.top( ); - cout << "After a pop, the element at the top of the " - << "priority_queue is " << iv << "." << endl; + const int& iv = q1.top(); + cout << "After a pop, the element at the top of the " << "priority_queue is " << iv << "." << endl; } ``` @@ -197,7 +199,7 @@ After a pop, the element at the top of the priority_queue is 20. ## `priority_queue::priority_queue` -Constructs a `priority_queue` that is empty or that is a copy of a range of a base container object or of another `priority_queue`. +Creates a `priority_queue` that is empty or that copies a range from a base container object or from another `priority_queue`. ```cpp priority_queue(); @@ -243,10 +245,9 @@ The fourth constructor specifies a copy of the `priority_queue right`. The last three constructors copy the range `[first, last)` of some container and use the values to initialize a `priority_queue` with increasing explicitness in specifying the type of comparison function of class `Traits` and `container_type`. -### Example +### Example: Use custom containers and comparers ```cpp -// pqueue_ctor.cpp // compile with: /EHsc #include #include @@ -254,101 +255,94 @@ The last three constructors copy the range `[first, last)` of some container and #include #include -int main( ) +int main() { using namespace std; - // The first member function declares priority_queue - // with a default vector base container + // Declares a priority_queue with a default vector base container priority_queue q1; cout << "q1 = ( "; - while ( !q1.empty( ) ) + while (!q1.empty()) { - cout << q1.top( ) << " "; - q1.pop( ); + cout << q1.top() << " "; + q1.pop(); } cout << ")" << endl; - // Explicitly declares a priority_queue with nondefault - // deque base container - priority_queue > q2; - q2.push( 5 ); - q2.push( 15 ); - q2.push( 10 ); + // Declares a priority_queue with nondefault deque base container + priority_queue > q2; + q2.push(5); + q2.push(15); + q2.push(10); cout << "q2 = ( "; - while ( !q2.empty( ) ) + while (!q2.empty()) { - cout << q2.top( ) << " "; - q2.pop( ); + cout << q2.top() << " "; + q2.pop(); } cout << ")" << endl; - - // This method of printing out the elements of a priority_queue - // removes the elements from the priority queue, leaving it empty - cout << "After printing, q2 has " << q2.size( ) << " elements." << endl; - - // The third member function declares a priority_queue - // with a vector base container and specifies that the comparison - // function greater is to be used for ordering elements - priority_queue , greater > q3; - q3.push( 2 ); - q3.push( 1 ); - q3.push( 3 ); + cout << "After printing, q2 has " << q2.size() << " elements." << endl; + + // Declares a priority_queue with a vector base container and specifies that + // the comparison function greater is to be used for ordering elements + priority_queue , greater> q3; + q3.push(2); + q3.push(1); + q3.push(3); cout << "q3 = ( "; - while ( !q3.empty( ) ) + + while (!q3.empty()) { - cout << q3.top( ) << " "; - q3.pop( ); + cout << q3.top() << " "; + q3.pop(); } cout << ")" << endl; - // The fourth member function declares a priority_queue and - // initializes it with elements copied from another container: - // first, inserting elements into q1, then copying q1 elements into q4 - q1.push( 100 ); - q1.push( 200 ); - priority_queue q4( q1 ); + // Declares a priority_queue and initializes it with elements copied from another + // container by first inserting elements into q1 and then copying q1 elements into q4 + q1.push(100); + q1.push(200); + priority_queue q4(q1); cout << "q4 = ( "; - while ( !q4.empty( ) ) + while (!q4.empty()) { - cout << q4.top( ) << " "; - q4.pop( ); + cout << q4.top() << " "; + q4.pop(); } cout << ")" << endl; // Creates an auxiliary vector object v5 to be used to initialize q5 vector v5; vector ::iterator v5_Iter; - v5.push_back( 10 ); - v5.push_back( 30 ); - v5.push_back( 20 ); + v5.push_back(10); + v5.push_back(30); + v5.push_back(20); cout << "v5 = ( " ; - for ( v5_Iter = v5.begin( ) ; v5_Iter != v5.end( ) ; v5_Iter++ ) + for (v5_Iter = v5.begin() ; v5_Iter != v5.end() ; v5_Iter++) + { cout << *v5_Iter << " "; + } cout << ")" << endl; - // The fifth member function declares and - // initializes a priority_queue q5 by copying the + // Declares and initializes a priority_queue q5 by copying the // range v5[ first, last) from vector v5 - priority_queue q5( v5.begin( ), v5.begin( ) + 2 ); + priority_queue q5(v5.begin(), v5.begin() + 2); cout << "q5 = ( "; - while ( !q5.empty( ) ) + while (!q5.empty()) { - cout << q5.top( ) << " "; - q5.pop( ); + cout << q5.top() << " "; + q5.pop(); } cout << ")" << endl; - // The sixth member function declares a priority_queue q6 - // with a comparison function greater and initializes q6 - // by copying the range v5[ first, last) from vector v5 - priority_queue , greater > - q6( v5.begin( ), v5.begin( ) + 2 ); + // Declares a priority_queue q6 with a comparison function greater and + // initializes q6 by copying the range v5[ first, last) from vector v5 + priority_queue , greater> q6(v5.begin(), v5.begin() + 2); cout << "q6 = ( "; - while ( !q6.empty( ) ) + while (!q6.empty()) { - cout << q6.top( ) << " "; - q6.pop( ); + cout << q6.top() << " "; + q6.pop(); } cout << ")" << endl; } @@ -365,36 +359,34 @@ void push(const Type& val); ### Parameters *`val`*\ -The element added to the top of the `priority_queue`. +The element to add to the top of the `priority_queue`. ### Remarks -The top of the `priority_queue` is the position occupied by the largest element in the container. +The top of the `priority_queue` contains the largest element in the container. -### Example +### Example: Push elements and read the top ```cpp -// pqueue_push.cpp // compile with: /EHsc #include #include -int main( ) +int main() { using namespace std; priority_queue q1; - q1.push( 10 ); - q1.push( 30 ); - q1.push( 20 ); + q1.push(10); + q1.push(30); + q1.push(20); priority_queue::size_type i; - i = q1.size( ); + i = q1.size(); cout << "The priority_queue length is " << i << "." << endl; - const int& ii = q1.top( ); - cout << "The element at the top of the priority_queue is " - << ii << "." << endl; + const int& ii = q1.top(); + cout << "The element at the top of the priority_queue is " << ii << "." << endl; } ``` @@ -415,26 +407,25 @@ size_type size() const; The current length of the `priority_queue`. -### Example +### Example: Get the number of elements in the `priority_queue` ```cpp -// pqueue_size.cpp // compile with: /EHsc #include #include -int main( ) +int main() { using namespace std; priority_queue q1, q2; priority_queue ::size_type i; - q1.push( 1 ); - i = q1.size( ); + q1.push(1); + i = q1.size(); cout << "The priority_queue length is " << i << "." << endl; - q1.push( 2 ); - i = q1.size( ); + q1.push(2); + i = q1.size(); cout << "The priority_queue length is now " << i << "." << endl; } ``` @@ -446,7 +437,7 @@ The priority_queue length is now 2. ## `priority_queue::size_type` -An unsigned integer type that can represent the number of elements in a `priority_queue`. +An unsigned integer type that represents the number of elements in a `priority_queue`. ```cpp typedef typename Container::size_type size_type; @@ -454,11 +445,11 @@ typedef typename Container::size_type size_type; ### Remarks -The type is a synonym for the `size_type` of the base container adapted by the `priority_queue`. +This type is a synonym for the `size_type` of the base container that the `priority_queue` adapts. -### Example +### Example: Access the top element -See the example for [`size`](#size) for an example of how to declare and use `size_type`. +For an example of how to declare and use `size_type`, see [Get the number of elements](#get-priority_queue-size) ## `priority_queue::top` @@ -474,32 +465,30 @@ A reference to the largest element, as determined by the `Traits` function, obje ### Remarks -The `priority_queue` must be nonempty to apply the member function. +The `priority_queue` must be nonempty to use this member function. -### Example +### Example: Get the top element of the `priority_queue` ```cpp -// pqueue_top.cpp // compile with: /EHsc #include #include -int main( ) +int main() { using namespace std; priority_queue q1; - q1.push( 10 ); - q1.push( 30 ); - q1.push( 20 ); + q1.push(10); + q1.push(30); + q1.push(20); priority_queue::size_type i; - i = q1.size( ); + i = q1.size(); cout << "The priority_queue length is " << i << "." << endl; - const int& ii = q1.top( ); - cout << "The element at the top of the priority_queue is " - << ii << "." << endl; + const int& ii = q1.top(); + cout << "The element at the top of the priority_queue is " << ii << "." << endl; } ``` @@ -518,17 +507,16 @@ typedef typename Container::value_type value_type; ### Remarks -The type is a synonym for the `value_type` of the base container adapted by the `priority_queue`. +This type is a synonym for the `value_type` of the base container that the `priority_queue` adapts. -### Example +### Example: Use the priority_queue value_type alias ```cpp -// pqueue_value_type.cpp // compile with: /EHsc #include #include -int main( ) +int main() { using namespace std; @@ -539,9 +527,8 @@ int main( ) cout << "The value_type is AnInt = " << AnInt << endl; priority_queue q1; - q1.push( AnInt ); - cout << "The element at the top of the priority_queue is " - << q1.top( ) << "." << endl; + q1.push(AnInt); + cout << "The element at the top of the priority_queue is " << q1.top() << "." << endl; } ``` @@ -550,6 +537,73 @@ The value_type is AnInt = 69 The element at the top of the priority_queue is 69. ``` +## Example: Use a user-defined data type + +To use `priority_queue` with user-defined type elements, you must provide a way to compare the elements. You can either define `operator<` for your type or provide a custom comparison function object. + +The following example demonstrates a `priority_queue` that stores `Task` objects, ordered by priority level. Tasks with higher priority values are at the top of the queue. + +```cpp +// compile with: /EHsc +#include +#include +#include + +struct Task +{ + int priority; + std::string name; + + // Define operator< for priority_queue ordering + // Returns true if this task has LOWER priority than other + // (priority_queue puts the "largest" element at the top) + bool operator<(const Task& other) const + { + return priority < other.priority; + } +}; + +int main() +{ + std::priority_queue tasks; + + tasks.push({3, "Low priority task"}); + tasks.push({10, "High priority task"}); + tasks.push({5, "Medium priority task"}); + + std::cout << "Processing tasks by priority:\n"; + while (!tasks.empty()) + { + const Task& t = tasks.top(); + std::cout << " Priority " << t.priority << ": " << t.name << "\n"; + tasks.pop(); + } +} +``` + +```Output +Processing tasks by priority: + Priority 10: High priority task + Priority 5: Medium priority task + Priority 3: Low priority task +``` + +### Remarks + +If you want different ordering (for example, lower values first), provide a custom comparator: + +```cpp +struct ComparePriority +{ + bool operator()(const Task& a, const Task& b) + { + return a.priority > b.priority; // Lower priority value means higher priority + } +}; + +std::priority_queue, ComparePriority> minQueue; +``` + ## See also [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ diff --git a/docs/standard-library/queue-operators.md b/docs/standard-library/queue-operators.md index 51f688e8766..9f4929c4a97 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/queue.md b/docs/standard-library/queue.md index cd1709709b5..f580355a8eb 100644 --- a/docs/standard-library/queue.md +++ b/docs/standard-library/queue.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["queue header"] -ms.assetid: 24fcf350-eb0e-48cf-9fef-978be1aeda1f --- # `` @@ -27,7 +26,7 @@ Defines the class templates priority_queue and queue and several supporting temp |-|-| |[operator!=](../standard-library/queue-operators.md#op_neq)|Tests if the queue object on the left side of the operator is not equal to the queue object on the right side.| |[operator<](../standard-library/queue-operators.md#op_lt)|Tests if the queue object on the left side of the operator is less than the queue object on the right side.| -|[operator\<=](../standard-library/queue-operators.md#op_gt_eq)|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.| +|[operator\<=](../standard-library/queue-operators.md#op_lt_eq)|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.| |[operator==](../standard-library/queue-operators.md#op_eq_eq)|Tests if the queue object on the left side of the operator is equal to the queue object on the right side.| |[operator>](../standard-library/queue-operators.md#op_gt)|Tests if the queue object on the left side of the operator is greater than the queue object on the right side.| |[operator>=](../standard-library/queue-operators.md#op_gt_eq)|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.| diff --git a/docs/standard-library/random.md b/docs/standard-library/random.md index 11b4b91e2be..958524b2451 100644 --- a/docs/standard-library/random.md +++ b/docs/standard-library/random.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "08/24/2017" +description: "Learn more about: " +ms.date: 08/24/2017 f1_keywords: [""] helpviewer_keywords: ["random header"] -ms.assetid: 60afc25c-b162-4811-97c1-1b65398d4c57 --- # `` @@ -17,7 +16,7 @@ Defines facilities for random number generation, allowing creation of uniformly **Namespace:** std > [!NOTE] -> The `` library uses the `#include ' statement. +> The `` library uses the `#include ` statement. ## Summary @@ -45,7 +44,7 @@ Here are some tips to keep in mind when using ``: - The most useful pairing for most applications is the `mt19937` engine with `uniform_int_distribution`, as shown in the [code example](#code) later in this article. -There are many options to choose from in the `` header, and any of them is preferable to the outdated C Runtime function `rand()`. For information about what's wrong with `rand()` and how `` addresses these shortcomings, see [this video](/events/goingnative-2013/rand-considered-harmful). +There are many options to choose from in the `` header, and any of them is preferable to the outdated C Runtime function `rand()`. For information about what's wrong with `rand()` and how `` addresses these shortcomings, see [this video](/shows/goingnative-2013/rand-considered-harmful). ## Examples diff --git a/docs/standard-library/range-adaptors.md b/docs/standard-library/range-adaptors.md new file mode 100644 index 00000000000..fd269cd19a8 --- /dev/null +++ b/docs/standard-library/range-adaptors.md @@ -0,0 +1,1509 @@ +--- +title: "Range adaptors" +description: "Learn more about range adaptors, which create views on ranges." +ms.date: 11/3/2022 +f1_keywords: ["ranges/std::all", "ranges/std::all_t", "ranges/std::common", "ranges/std::counted", "ranges/std::drop", "ranges/std::drop_while", "ranges/std::elements", "ranges/std::empty", "ranges/std::filter", "ranges/std::iota", "ranges/std::istream", "ranges/std::join", "ranges/std::keys", "ranges/std::lazy_split", "ranges/std::reverse", "ranges/std::single", "ranges/std::split", "ranges/std::subrange", "ranges/std::take", "ranges/std::take_while", "ranges/std::transform", "ranges/std::values"] +helpviewer_keywords: ["std::ranges [C++], all", "std::ranges [C++], all_t", "std::ranges [C++], common", "std::ranges [C++], counted", "std::ranges [C++], drop", "std::ranges [C++], drop_while", "std::ranges [C++], elements", "std::ranges [C++], empty", "std::ranges [C++], filter", "std::ranges [C++], iota", "std::ranges [C++], istream", "std::ranges [C++], join", "std::ranges [C++], keys", "std::ranges [C++], lazy_split", "std::ranges [C++], reverse", "std::ranges [C++], single", "std::ranges [C++], split", "std::ranges [C++], subrange", "std::ranges [C++], take", "std::ranges [C++], take_while", "std::ranges [C++], transform", "std::ranges [C++], values"] +--- +# Range adaptors + +Range adaptors create a *view* (one of the [View classes](view-classes.md) in the `std::views` namespace) from a range. We recommend that you use an adaptor to create views instead of creating the view types directly. The adaptors are the intended way to access views. They're easier to use, and in some cases more efficient, than creating instances of the view types directly. + +A view is a lightweight object that refers to elements from a range. A view can: + +- Consist of only certain elements from a range. +- Represent a transformation of elements from a range. +- Be the reverse of, or only the first `n` elements of, a range. +- Be a combination of the preceding things. + +A view is cheap, `O(1)`, to copy, assign, and destroy--no matter how many elements are involved. Consider the following example: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto divisible_by_three = [](const int n) {return n % 3 == 0;}; + auto square = [](const int n) {return n * n;}; + + auto x = input | std::views::filter(divisible_by_three) + | std::views::transform(square); + + for (int i : x) + { + std::cout << i << ' '; + } +} +``` + +```output +0 9 36 81 +``` + +The first range adaptor, [`filter`](filter-view-class.md), provides a view that contains the elements from `input` that are divisible by three. The other range adaptor, [`transform`](transform-view-class.md), takes the view that contains the elements divisible by three and provides a view of the square of those elements. + +When a range adaptor produces a view, it doesn't incur the cost of transforming every element in the range to produce that view. The cost to process an element in the view is paid only when you access that element. + +Creating a view is preparation to do work in the future. In the previous example, creating the view doesn't result in finding all the elements divisible by three or squaring those elements. Work happens only when you access an element in the view. + +Elements of a view are usually the actual elements of the range used to create the view. The view usually doesn't own the elements; it just refers to them, with the exception of [`owning_view`](owning-view-class.md). Changing an element changes that element in the range that the view was created from. The following example shows this behavior: + +```cpp +#include +#include +#include + +int main() +{ + int input[] = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto even = [](const int n) { return n % 2 == 0; }; + auto x = input | std::views::filter(even); // create a view of the even elements from input + + for (int &i : x) + { + std::cout << i << ' '; // 0 2 4 6 8 10 + } + std::cout << '\n'; + + std::ranges::fill(x, 42); // changes the evens from input[] to 42 + for (int &i : input) // demonstrates that the even elements in the range are modified + { + std::cout << i << ' '; // // 42 1 42 3 42 5 42 7 42 9 42 + } +} +``` + +Range adaptors come in many forms. For example, there are range adaptors that allow you to produce a view by: + +- Filtering another range based on a predicate ([`filter`](filter-view-class.md)). +- Transforming the elements in a range ([`transform`](transform-view-class.md)). +- Splitting a range ([`split`](split-view-class.md)). + +Range adaptors can be chained together (composed). That's where the power and flexibility of ranges are most apparent. Composing range adaptors allows you to overcome a core problem with the previous Standard Template Library (STL) algorithms, which is that they aren't easy to chain together. + +The following range adaptors are available in the `std::views` namespace. The `std::views` namespace is a convenience alias for `std::ranges::views`. + +| Range adaptor | Description | +|--|--| +| [`all`](#all)C++20 | Create a view that refers to a range and its elements. | +| [`common`](#common)C++20 | Create a view that has the same iterator and sentinel types from a range that doesn't. | +| [`counted`](#counted)C++20 | Create a view of the first *n* elements of a range, starting from the specified location. | +| [`drop`](#drop)C++20 | Create a view from another view, skipping the specified number of elements from the front. | +| [`drop_while`](#drop_while)C++20 | Create a view that contains the elements of a range that remain after the leading elements that match the specified condition are dropped. | +| [`elements`](#elements)C++20 | Create a view of the selected index into each tuple-like value in a range. | +| [`empty`](#empty)C++20 | Create a view that has no elements. | +| [`filter`](#filter)C++20 | Create a view that contains the elements of a range that match the specified condition. | +| [`iota`](#iota)C++20 | Create a view that contains a sequence of increasing values. | +| [`istream`](#istream)C++20 | Create a view over the elements of a stream. | +| [`join`](#join)C++20 | Create a view that combines all the elements of multiple ranges into a single view. | +| [`keys`](#keys)C++20 | Create a view of the first index into each tuple-like value in a collection. | +| [`lazy_split`](#lazy_split)C++20 | Split a view into subranges based on a delimiter. | +| [`reverse`](#reverse)C++20 | Create a view of the elements of a range in reverse order. | +| [`single`](#single)C++20 | Create a view that contains one element. | +| [`split`](#split)C++20 | Split a view into subranges based on a delimiter. | +| [`take`](#take)C++20 | Create a view of the first *n* elements from another view. | +| [`take_while`](#take_while)C++20 | Create a view that contains the leading elements of a range that match the specified condition. | +| [`transform`](#transform)C++20 | Create a view of transformed elements from another view. | +| [`values`](#values)C++20 | Create a view of the second index into each tuple-like value in a collection. | + +In the previous table, a range adaptor is typically described as taking a range and producing a view. To be precise, range adaptors have a range argument that accepts one of the following: + +- The `cv-unqualified` type models [`view`](range-concepts.md#view), and the argument is an rvalue or is copyable. +- When you pass the argument as an lvalue, it must model [`range`](range-concepts.md#range) and live as long as the view. +- When you pass the argument as an rvalue, such as when calling [`owning_view`](owning-view-class.md), it must model `range` and `movable`. + +Range adaptor functions are typically [function objects](https://eel.is/c++draft/function.objects), which look like function calls and enforce constraints on the types that can be passed. + +You can pass range adaptors and the result of pipe operations (`|`) to code that expects function objects. In the following example, the view that the `split` range adaptor creates is passed to the `transform` range adaptor as if by a function call, because the `transform` range adaptor is a function object. + +```cpp +std::map x = {{0, "Hello, world"}, {42, "Goodbye, world"}}; +auto y = x | views::values | views::transform(views::split(' ')); +// y is a range whose elements are ranges of whitespace-delimited strings from each value in x: +// {{"Hello", "world"}, {"Goodbye", "world"}} +``` + +## `all` + +Create a view of all the elements in a range. + +```cpp +template +constexpr ranges::view auto all(R&& rg) const noexcept; +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +- If `rg` is already a view, a copy of `rg`. +- If `rg` is a non-view lvalue, a [`ref_view`](ref-view-class.md) that refers to `rg`. (The lifetime of the view is tied to the lifetime of `rg`.) +- If `rg` is a non-view rvalue such as a temporary object, or is the result of passing the range to `std::move`, an [`owning_view`](owning-view-class.md). + +Use `std::views::all_t` to get the type of the returned view. + +### Remarks + +This range adaptor is the best way to convert a range into a view. One reason to create a view from a range is to pass it by value at low cost, if passing the range by value could be expensive. + +Getting a view for a range is a useful alternative to passing a heavyweight range by value because views are inexpensive to create, copy, and destroy. A possible exception is `owning_view`, which is a view that owns the underlying range. + +In general, the worst-case scenario for destroying a view has `O(N)` complexity for the number of elements in the range. Even if you destroy `K` copies of view with `N` elements, the total complexity is still `O(N)` because the underlying range is destroyed only once. + +### Example: `all` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3,4,5,6,7,8,9,10}; + auto myRefView = std::views::all(v); // create a ref_view of the vector + std::cout << myRefView.size() << '\n'; // 10 + + auto myOwningView = std::views::all(std::move(v)); // create an owning_view from a moved vector + std::cout << myRefView.size() << '\n'; // outputs 0 because myOwningView now owns the elements + std::cout << v.size() << '\n'; // outputs 0 because myOwningView now owns the elements + std::cout << myOwningView.size(); // 10 +} +``` + +```output +10 +0 +0 +10 +``` + +## `common` + +Create a view that has the same begin iterator and sentinel type from a range that might not. + +```cpp +template +constexpr ranges::view auto common(R&& rg) const noexcept; +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +- `views::all(rg)` if `rg` is a range with the same iterator and sentinel type. +- [`common_view(views::all(rg))`](common-view-class.md) if `rg` has different iterator and sentinel types. + +### Remarks + +When an API requires the begin iterator and end sentinel to have the same type, and the view that you're using doesn't meet that requirement (or you don't know if it does), use this range adaptor to create a `common_view`. It guarantees that the type of the begin iterator and the type of the end sentinel are the same. + +### Example: `common` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::list lst{1, 2, 3, 4, 5, 6, 7, 8, 9}; + + auto firstFive = std::views::take(lst, 5); + // firstFive.begin(), firstFive.end() have different types: counted_iterator versus default_sentinel + // auto r = std::accumulate(firstFive.begin(), firstFive.end(), 0); // Error: accumulate() requires firstFive.begin() and firstFive.end() types to be the same. + + auto common = std::views::common(firstFive); // create a common_view that has the same begin/end iterator types + std::cout << std::accumulate(common.begin(), common.end(), 0); // Now you can call the API because the iterator types are the same. Outputs 15 (1+2+3+4+5) +} +``` + +```output +15 +``` + +## `counted` + +Create a view of the first `count` elements of a range, starting from the specified location. + +```cpp +template +constexpr auto counted(Iterator&& it, iter_difference_t count); +``` + +### Parameters + +`DifferenceType`\ +The type of the count. + +`Iterator`\ +The type of the iterator. + +`count`\ +The number of elements to include in the view. Must be non-negative. + +- If `count == 0`, an empty [`span`](span-class.md) is returned. +- If `count` is greater than the number of elements in the range, the behavior is undefined. + +`it`\ +An iterator to the element in the range to start with. The element that the iterator points to is included in the created view. + +### Return value + +A [`span`](span-class.md) is returned if `it` is a [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator) for arrays, vectors, and other containers that store their elements contiguously. Otherwise, a [`subrange`](subrange-class.md) is returned. + +### Remarks + +The included elements are `[it, count)`. + +After the view is created, the number of elements in the view stays the same, even if the range that it was created from changes. However, if the underlying range changes, accessing elements from the view might result in undefined behavior. + +### Example: `counted` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto pos5 = std::ranges::find(v, 5); + auto countedView = std::views::counted(pos5, 5); + for (auto e : countedView) // outputs 5 6 7 8 9 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + // You can pass the range directly if it supports input_or_output_iterator, in which case + // the count starts from the first element + const char chars[] = { 'H','i',' ','t','h','e','r','e' }; + for (char c : std::views::counted(chars, 2)) + { + std::cout << c; // outputs Hi + } +} +``` + +```output +5 6 7 8 9 +Hi +``` + +## `drop` + +Create a view that excludes the first *n* elements of a range. + +```cpp +1) template +constexpr ranges::view auto drop(R&& rg, ranges::range_difference_t count); + +2) template +constexpr /* range closure object */ drop(DifferenceType&& count); +``` + +### Parameters + +`DifferenceType`\ +The type that describes the number of elements to skip. + +`count`\ +The number of elements to drop from the front of `rg`. Must be non-negative. +- If `count == 0`, all the elements in `rg` are returned. +- If `count` is greater than the number of elements in `rg`, an empty view is returned. + +`R`\ +The type of the range. + +`rg`\ +The range that's used to create the view. + +### Return value + +A view of the underlying range, with the specified number of elements dropped from the front. + +If you specify more elements to drop than exist in the underlying range, an [`empty_view`](empty-view-class.md) is returned. + +The returned view is typically, but not always, a specialization of [`drop_view`](drop-view-class.md). That is: + +- If `V` is a specialization of [`empty_view`](empty-view-class.md), or is a specialization of [`span`](span-class.md), [`basic_string_view`](basic-string-view-class.md), [`iota_view`](iota-view-class.md), or [`subrange`](subrange-class.md) that is both [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range), the result is a specialization of `V`. +- Otherwise, the result is a [`drop_view`](drop-view-class.md). + +### Remarks + +After it's created, the number of elements in the view stays the same even if the view that it was created from changes. However, if the underlying view changes, accessing elements in the returned view might result in undefined behavior. + +`drop` is the opposite of [`take`](#take). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | drop(5)`. Or it can be used with function call syntax: `drop(collection, 5)` or `drop(5)(collection)`. + +### Example: `drop` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{1, 2, 3, 4, 5}; + auto newView = std::views::drop(v, 3); + for (auto e : newView) // 4 5 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + auto numbers = std::views::iota(0) | std::views::take(10); // build a view of 10 integers + auto latterHalf = numbers | std::views::drop(5); + for (auto i : latterHalf) + { + std::cout << i << ' '; // 5 6 7 8 9 + } +} +``` + +```output +4 5 +5 6 7 8 9 +``` + +## `drop_while` + +Create a view that contains the elements of a range that remain after the leading elements that match the specified condition are dropped. + +```cpp +1) template +constexpr ranges::view auto drop_while(R&& rg, P&& predicate); + +2) template +constexpr /*range adaptor closure*/ drop_while(P&& predicate); +``` + +### Parameters + +`R`\ +The type of the range. + +`predicate`\ +The conditions that determine which leading elements to drop from the range. + +`rg`\ +The underlying range to create the view from. + +### Return value + +A [`drop_while_view`](drop-while-view-class.md) that consists of the elements that remain when the leading elements that match the predicate are dropped. + +### Remarks + +Stops dropping elements from `rg` as soon as the predicate returns `false`. + +`drop_while` is the opposite of [`take_while`](#take_while). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | drop_while(predicate)`. Or it can be used with function call syntax: `drop_while(collection, predicate)` or `drop_while(predicate)(collection)`. + +### Example: `drop_while` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto myView = std::views::drop_while( + v, + [](int i) {return i >= 0; }); + print(myView); // -4 5 6 + + auto myView2 = v | std::views::drop_while( + [](int i) {return i < 5; }); + print(myView2); // 5 6 +} +``` + +```output +-4 5 6 +5 6 +``` + +## `elements` + +Create an [`elements_view`](elements-view-class.md), which is a view of the selected index into each tuple-like value in a range. For example, given a range of `std::tuple` values, create an `elements_view` of all the `string` elements from each tuple. + +```cpp +template +constexpr ranges::view auto elements(R&& rg); +``` + +### Parameters + +`N`\ +The index of the element to select from each tuple-like value to include in the view. + +`R`\ +The type of the underlying range. + +`rg`\ +The range of tuple-like values to create the view from. + +### Return value + +An [`elements_view`](elements-view-class.md) that consists of the selected index into each tuple-like value in a collection. + +### Example: `elements` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::map cpp_standards + { + {"C++98", 1998}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Create an elements_view of all the string elements from each tuple + for (int const year : std::views::elements<1>(cpp_standards)) + { + std::cout << year << ' '; // 2003 2011 2014 2017 1998 2020 + } + std::cout << '\n'; + + // Another way, using |: create an elements_view of all the int elements from each tuple + for (auto&& name : cpp_standards | std::views::elements<0>) + { + std::cout << name << ' '; // C++03 C++11 C++14 C++17 C++98 c++20 + } +} +``` + +```output +2003 2011 2014 2017 1998 2020 +C++03 C++11 C++14 C++17 C++98 c++20 +``` + +## `empty` + +Create an `empty_view`, which is a view that has no elements. + +```cpp +template +inline constexpr empty_view empty{}; +``` + +### Parameters + +`T`\ +The type of the elements in the view. The view needs an element type, even though there are no elements. + +### Return value + +An [`empty_view`](empty-view-class.md). + +### Remarks + +An `empty_view` can be useful when you're calling code that requires a view but doesn't need to process any of its elements. + +### Example: `empty` + +```cpp +// requires /std:c++20 or later +#include +#include + +int main() +{ + auto anEmptyView = std::views::empty; + bool isNotEmpty = (bool)anEmptyView; + std::cout << boolalpha << isNotEmpty << "\n"; // false +} +``` + +```output +false +``` + +## `filter` + +Create a view that contains the elements of a range that match the specified condition. + +```cpp +1) template + requires {filter_view(forward(rg), forward

(predicate));} +constexpr ranges::view auto filter(R&& rg, P&& predicate); + +2) template +constexpr /*range adaptor closure*/ filter(P&& predicate); +``` + +### Parameters + +`P`\ +The type of the predicate. + +`predicate`\ +The conditions that determine which elements to keep in the range. + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +A [`filter_view`](filter-view-class.md) that contains the elements of a range that match the predicate. + +### Remarks + +For efficiency's sake, when you use `filter` and `transform` together with a pipe `|`, do the `filter` first so that you `transform` only the elements that you intend to keep. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | filter(predicate)`. Or it can be used with function call syntax: `filter(collection, predicate)` or `filter(predicate)(collection)`. + +### Example: `filter` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto myView = std::views::filter(v, [](int i) {return i < 5; }); + print(myView); // 0 1 2 3 -4 + + auto myView2 = v | std::views::filter([](int i) {return i < 5; }); // pipe syntax + print(myView2); // 0 1 2 3 -4 +} +``` + +```output +0 1 2 3 -4 +0 1 2 3 -4 +``` + +## `iota` + +Create a view that contains a sequence of increasing values. The sequence can be bounded or not. + +```cpp +template +constexpr ranges::view auto iota(V&& startValue); // create an unbounded sequence of incrementing values + +template +constexpr ranges::view auto iota(V&& startValue, E&& endValue); // create a bounded sequence of incrementing values +``` + +### Parameters + +`E`\ +The type of the end value. + +`S`\ +The type of the start value. + +`startValue`\ +The first value in the sequence. + +`endValue`\ +This value is one past the last value that will be in the sequence. For example, `std::views::iota(0, 5)` generates a view that has the values `0,1,2,3,4`. + +### Return value + +An [`iota_view`](iota-view-class.md) of a sequence of increasing values. + +### Remarks + +For an unbounded sequence, the behavior is undefined after the maximum value of its datatype is reached. + +### Example: `iota` + +```cpp +// requires /std:c++20 or later +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + // create an iota view with its range adaptor (preferred) + print(std::views::iota(0, 5)); // outputs 0 1 2 3 4 + + // create an iota_view class directly + std::ranges::iota_view letters{'a', 'f'}; + print(letters); // a b c d e +} +``` + +```output +0 1 2 3 4 +a b c d e +``` + +## `istream` + +Create a view over the elements of a stream. + +```cpp +template +views::istream(str); +``` + +### Parameters + +`str`\ +A stream object. Its type is derived from a specialization of `std::basic_istream`. + +`Val`\ +The type of the elements to extract from the stream. + +### Return value + +A [`basic_istream_view`](basic-istream-view-class.md). + +This range adaptor is equivalent to `ranges::basic_istream_view(str)`, where `U` is the type of `str`. + +### Example: `istream` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::istringstream doubles{"1.1 2.2 3.3 4.4 5.5"}; + for (const auto& elem : std::views::istream(doubles)) + { + std::cout << elem << ' '; // 1.1 2.2 3.3 4.4 5.5 + } +} +``` + +```output +1.1 2.2 3.3 4.4 5.5 +``` + +## `join` + +Create a view that combines all the elements of multiple ranges into a single view. + +```cpp +1) template +[[nodiscard]] constexpr ranges::view auto join(R&& rg) const noexcept; + +2) inline constexpr /*range adaptor closure*/ join(); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +A [`join_view`](join-view-class.md) that contains the elements of all the ranges in the underlying range. + +### Example: `join` + +```cpp +#include +#include +#include +#include + +int main() +{ + // a range of two ranges + std::vector rangeOfRanges[2]{{"C++20", "contains:"}, {"ranges", "modules", "concepts & more."}}; + + for (const auto& elem : std::views::join(rangeOfRanges)) + { + std::cout << elem << ' '; + } +} +``` + +```output +C++20 contains: ranges modules concepts & more. +``` + +### Remarks + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | join`. Or it can be used with function call syntax: `join(collection)`. + +## `keys` + +Create a [`keys_view`](keys-view-class.md) of the first index into each tuple-like value in a collection. This is useful for extracting keys from associative containers. For example, given a range of `std::tuple`, create a view that consists of all the `string` elements from each tuple. + +```cpp +template +constexpr auto keys(R&& rg); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +### Return value + +A [`keys_view`](keys-view-class.md) that consists of the first index into each tuple-like value in the range. + +### Example: `keys` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include + +int main() +{ + // ========== extract keys from a map + + std::map cpp_standards + { + {"C++98", 1998}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the keys from the map + for (std::string standards : std::views::keys(cpp_standards)) + { + std::cout << standards << ' '; // C++03 C++11 C++14 C++17 C++98 C++20 + } + std::cout << '\n'; + + // ========== Extract keys from a pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor is by using '|' + for (std::string version : windows | std::views::keys) + { + std::cout << version << ' '; // Windows 1.0 Windows 2.0 Windows 3.0 ... + } +} +``` + +```output +C++03 C++11 C++14 C++17 C++98 C++20 +Windows 1.0 Windows 2.0 Windows 3.0 Windows 3.1 Windows NT 3.1 Windows 95 Windows NT 4.0 Windows 95 Windows 98 Windows 1.0 Windows 2000 +``` + +## `lazy_split` + +Split a range into subranges based on a delimiter. The delimiter can be a single element or a view of elements. + +```cpp +1) template +constexpr view auto lazy_split(R&& rg, Pattern&& delimiter); + +2) template +constexpr /*range adaptor closure*/ lazy_split(Pattern&& delimiter); +``` + +### Parameters + +`delimiter`\ +A single value, or a sequence of values that specify where to split the range. + +`Pattern`\ +The type of the delimiter. + +`R`\ +The type of the range to split. + +`rg`\ +The range to split. + +### Return value + +A [`lazy_split_view`](lazy-split-view-class.md) that contains one or more subranges and is the result of splitting the original range on `delimiter`. + +### Remarks + +The delimiter isn't part of the result. For example, if you split the range `1,2,3` on the value `2`, you get two subranges: `1` and `3`. + +A related adaptor is [`split`](#split). The primary differences between [`split_view`](split-view-class.md) and `lazy_split_view` are: + +| View | Can split a `const` range | Range iterator | +|--|--|--| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher | +| `lazy_split_view` | yes | [`input_range`](range-concepts.md#input_range) or higher | + +Prefer `split_view` because it's more efficient, unless you must split a range that is `const`. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | lazy_split(delimiter)`. Or it can be used with function call syntax: `lazy_split(collection, delimiter)` or `lazy_split(delimiter)(collection)`. + +### Example: `lazy_split` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{1, 2, 3, 1, 2, 3, 4, 5, 6}; + + // split on a single element + for (const auto& sub : rg | std::views::split(3)) + { + // outputs: + // 1 2 + // 1 2 + // 4 5 6 + for (const auto& elem : sub) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + // split on a sequence of elements + int delimiters[] = {2, 3}; + for (const auto& subrange : std::views::split(rg, delimiters)) + { + // outputs 1 1 4 5 6 + for (auto& i : subrange) + { + std::cout << i << " "; + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `reverse` + +Create a view of the elements of a range in reverse order. + +```cpp +1) template +constexpr ranges::view auto reverse(R&& rg); + +2) inline constexpr /*range adaptor closure*/ reverse(); +``` + +### Parameters + +`R`\ +The type of the underlying range to reverse. + +`rg`\ +The range to reverse. + +### Return value + +A view that presents the elements of the underlying range in reverse order. The returned view is typically, but not always, a specialization of [`reverse_view`](reverse-view-class.md). That is: + +- If `V` is a specialization of `reverse_view`, the result is the argument's underlying view. A double-reverse is a no-op (no operation). +- If `V` has the form `subrange, reverse_iterator>`, the result is a [`subrange`](subrange-class.md) of the unwrapped iterators. A double-reverse is a no-op. +- Otherwise, the result is a [`reverse_view`](reverse-view-class.md). + +### Remarks + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | reverse`. Or it can be used with function call syntax: `reverse(collection)`. + +### Example: `reverse` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto rv = v | std::views::reverse; // using the pipe syntax + + for (auto &&e : rv) // outputs 6 5 -4 3 2 1 0 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + // using the range adaptor without using the pipe syntax + auto rv2 = std::views::reverse(v); + for (auto &&e : rv2) // outputs 6 5 -4 3 2 1 0 + { + std::cout << e << ' '; + } +} +``` + +```output +6 5 -4 3 2 1 0 +6 5 -4 3 2 1 0 +``` + +## `single` + +Create a `single_view`, which is a view that contains one element. + +```cpp +template +constexpr ranges::view auto single(T&& t); +``` + +### Parameters + +`T`\ +The type of the element in the view. + +`t`\ +The value of the element to store in the view. + +### Return value + +An [`single_view`](single-view-class.md) that contains `t`. + +### Remarks + +This view is useful for test purposes, for calling code that needs to be provided with a view that has at least one element in it. + +### Example: `single` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + auto sv = std::views::single(7); + std::cout << sv.front() << " " << *sv.data() << "\n"; // 7 7 + + auto sv2 = std::views::single({6502, "8-bit"}); + std::cout << std::get<0>(sv2[0]) << " " << std::get<1>(sv2[0]) << "\n"; // 6502 8-bit +} +``` + +```output +7 7 +6502 8-bit +``` + +## `split` + +Split a view into subranges based on a delimiter. The delimiter can be a single element or a sequence of elements. + +```cpp +1) template +constexpr view auto split(R&& rg, Pattern&& delimiter); + +2) template +constexpr /*range adaptor closure*/ split(Pattern&& delimiter); +``` + +### Parameters + +`delimiter`\ +A single value, or a sequence of values that specify where to split the range. + +`Pattern`\ +The type of the delimiter. + +`R`\ +The type of the underlying range to split. + +`rg`\ +The range to split. + +### Return value + +A [`split_view`](split-view-class.md) that contains one or more subranges. + +### Remarks + +The delimiter isn't part of the result. For example, if you split the range `1,2,3` on the value `2`, you get two subranges: `1` and `3`. + +A related adaptor is [`lazy_split`](#lazy_split). The primary differences between `split_view` and `lazy_split_view` are: + +| View | Can split a `const` range | Range type | +|---|---|---| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher | +| `lazy_split_view` | yes | Supports [`input_range`](range-concepts.md#input_range) or higher | + +Prefer `split_view` because it's more efficient, unless you must split a range that is `const`. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | split(delimiter)`. Or it can be used with function call syntax: `split(collection, 5)` or `split(5)(collection)`. + +### Example: `split` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{ 1, 2, 3, 1, 2, 3, 4, 5, 6 }; + + // split on a single element, 3 + for (const auto& sub : rg | std::views::split(3)) + { + // This prints out: + // 1,2 + // 4,5,6 + for (const auto& elem : sub) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + // split on a sequence of elements, 2,3 + int delimiters[] = {2, 3}; + for (const auto& subrange : std::views::split(rg, delimiters)) + { + // outputs 1 1 4 5 6 + for (auto& i : subrange) + { + std::cout << i << " "; + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `take` + +Create a view that contains the specified number of elements taken from the front of a range. + +```cpp +1) template +constexpr ranges::view auto take(R&& rg, ranges::range_difference_type count); + +2) template +constexpr /*range adaptor closure*/ take(DifferenceType&& count); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +`count`\ +The number of elements to take from the front of `rg`. + +### Return value + +The returned view is typically, but not always, a specialization of [`take_view`](take-view-class.md). Specifically: + +- If `V` is a specialization of [`empty_view`](empty-view-class.md), or is a specialization of [`span`](span-class.md), [`basic_string_view`](basic-string-view-class.md), [`iota_view`](iota-view-class.md), or [`subrange`](subrange-class.md) that is both [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range), the result is a specialization of `V`. +- Otherwise, the result is a [`take_view`](take-view-class.md). + +### Remarks + +If you specify more elements to take than exist in `rg`, all of the elements are taken. + +`take` is the opposite of [`drop`](#drop). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | take(5)`. Or it can be used with function call syntax: `take(5, collection)` or `take(5)(collection)`. + +### Example: `take` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::string s{ "abcdefg" }; + auto myView = std::views::take(s, 3); + for (auto c : myView) + { + std::cout << c << ' '; // a b c + } + + std::cout << std::endl; + + for (auto c : s | std::views::take(3)) // pipe syntax + { + std::cout << c << ' '; // a b c + } +} +``` + +```output +a b c +a b c +``` + +## `take_while` + +Create a view that contains the leading elements of a range that match the specified condition. + +```cpp +1) template +constexpr ranges::view auto take_while(R&& rg, P&& predicate); + +2) template +constexpr /*range adaptor closure*/ take_while(P&& predicate); +``` + +### Parameters + +`P`\ +The type of the predicate. + +`predicate`\ +The conditions that determine which leading elements to copy from the range. + +`R`\ +The type of the underlying range. + +`rg`\ +The range to create the view from. + +### Return value + +A [`take_while_view`](take-while-view-class.md) that consists of the first `count` elements that meet the specified criteria in the range. + +### Remarks + +Stops taking elements from `rg` after the predicate returns `false` or the range runs out of elements. + +`take_while` is the opposite of [`drop_while`](#drop_while). + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | take_while(pred)`. Or it can be used with function call syntax: `take_while(collection, pred)` or `take_while(pred)(collection)`. + +### Example: `take_while` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto myView = std::views::take_while( + v, [](int i) {return i >= 0; }); + print(myView); // 0 1 2 3 + + print(v | std::views::take_while( // 0 1 2 3 -4 + [](int i) {return i < 5; })); // pipe syntax +} +``` + +```output +0 1 2 3 +0 1 2 3 -4 +``` + +## `transform` + +Create a view of elements, each of which is a transformation of an element in the specified range. + +```cpp +1) template +constexpr ranges::view auto transform(R&& rg, F&& fun); + +2) template +constexpr /*range adaptor closure*/ transform(F&& fun); +``` + +### Parameters + +`F`\ +The type of the function object to transform the elements. + +`R`\ +The type of the underlying range. + +`fun`\ +The function that transforms the elements. + +`rg`\ +The range to create the view from. + +### Return value + +A [`transform_view`](transform-view-class.md) that contains the transformed elements of `rg`. + +### Remarks + +For efficiency's sake, when you compose `filter` and `transform`, do the `filter` first so that you `transform` only the elements that you intend to keep. + +The code shown earlier as "2\)" can be used with pipe syntax: `collection | transform(fun)`. Or it can be used with function call syntax: `transform(collection, fun)` or `transform(fun)(collection)`. + +### Example: `transform` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +void print(auto&& v) +{ + for (auto&& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto myView = std::views::transform(v, [](int i) {return i * 2; }); + print(myView); // 0 2 4 6 -8 10 12 + + print(v | std::views::transform( // 0 2 4 6 -8 10 12 + [](int i) {return i * 2; })); // pipe syntax +} +``` + +```output +0 2 4 6 -8 10 12 +0 2 4 6 -8 10 12 +``` + +## `values` + +Create a [`values_view`](values-view-class.md) that consists of the second index into each tuple-like value in a collection. This is useful for making a view of the values in an associative container. For example, given a range of `std::tuple` values, create a view that consists of all the `int` elements from each tuple. + +```cpp +template +constexpr ranges::view auto values(R&& rg); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +`rg`\ +The underlying range of tuple-like values. + +### Return value + +A [`values_view`](values-view-class.md) built from the second index into each tuple-like value in the range. + +### Example: `values` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include + +int main() +{ + // ========== working with a map + + std::map cpp_standards + { + {"C++98", 1998}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the years from the map + for (int years : std::views::values(cpp_standards)) + { + std::cout << years << ' '; // 2003 2011 2014 2017 1998 2020 + } + std::cout << '\n'; + + // ========== working with pairs + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor by using '|' + // Create a values_view that contains the year from each pair + for (int years : windows | std::views::values) + { + std::cout << years << ' '; // 1985 1987 1990 1992 ... + } +} +``` + +```output +2003 2011 2014 2017 1998 2020 +1985 1987 1990 1992 1993 1995 1996 1995 1998 1985 2000 +``` + +## Range adaptor type aliases + +### `all_t` + +Provides the type of the view that [`all`](#all) returns. + +```cpp +template +using all_t = decltype(views::all(std::declval())); +``` + +### Parameters + +`R`\ +The type of the underlying range. + +### Return value + +The type of the view that `all` returns: `decltype(views::all(std::declval()))`. + +### Example: `all_t` + +```cpp +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3,4,5,6,7,8,9,10}; + auto myView = std::views::all(v); + std::views::all_t &viewType = myView; +} +``` + +## See also + +[``](ranges.md)\ +[`` concepts](range-concepts.md)\ +[View classes](view-classes.md) \ No newline at end of file diff --git a/docs/standard-library/range-concepts.md b/docs/standard-library/range-concepts.md new file mode 100644 index 00000000000..dc21a897949 --- /dev/null +++ b/docs/standard-library/range-concepts.md @@ -0,0 +1,424 @@ +--- +title: " concepts" +description: "Learn more about range concepts." +ms.date: 12/16/2022 +f1_keywords: ["ranges/std::ranges::range", "ranges/std::ranges::bidirectional_range", "ranges/std::ranges::borrowed_range", "ranges/std::ranges::common_range", "ranges/std::ranges::contiguous_range", "ranges/std::ranges::forward_range", "ranges/std::ranges::input_range", "ranges/std::ranges::output_range", "ranges/std::ranges::random_access_range", "ranges/std::ranges::simple_view", "ranges/std::ranges::sized_range", "ranges/std::ranges::view", "ranges/std::ranges::viewable_range"] +helpviewer_keywords: ["std::ranges [C++], ranges::range", "std::ranges [C++], ranges::bidirectional_range", "std::ranges [C++], ranges::borrowed_range", "std::ranges [C++], ranges::common_range", "std::ranges [C++], ranges::contiguous_range", "std::ranges [C++], ranges::forward_range", "std::ranges [C++], ranges::input_range", "std::ranges [C++], ranges::output_range", "std::ranges [C++], ranges::random_access_range", "std::ranges [C++], ranges::simple_view", "std::ranges [C++], ranges::sized_range", "std::ranges [C++], ranges::view", "std::ranges [C++], ranges::viewable_range"] +--- +# `` concepts + +Concepts are a C++20 language feature that constrain template parameters at compile time. They help prevent incorrect template instantiation, specify template argument requirements in a readable form, and provide more succinct template related compiler errors. + +Consider the following example, which defines a concept to prevent instantiating a template with a type that doesn't support division: + +```cpp +// requires /std:c++20 or later +#include + +// Definition of dividable concept which requires +// that arguments a & b of type T support division +template +concept dividable = requires (T a, T b) +{ + a / b; +}; + +// Apply the concept to a template. +// The template will only be instantiated if argument T supports division. +// This prevents the template from being instantiated with types that don't support division. +// This could have been applied to the parameter of a template function, but because +// most of the concepts in the library are applied to classes, this form is demonstrated. +template requires dividable +class DivideEmUp +{ +public: + T Divide(T x, T y) + { + return x / y; + } +}; + +int main() +{ + DivideEmUp dividerOfInts; + std::cout << dividerOfInts.Divide(6, 3); // outputs 2 + // The following line will not compile because the template can't be instantiated + // with char* because char* can't be divided + DivideEmUp dividerOfCharPtrs; // compiler error: cannot deduce template arguments +} +``` + +When you pass the compiler switch `/diagnostics:caret` to Visual Studio 2022 version 17.4 preview 4, or later, the error that concept `dividable` evaluated to false will point directly to the expression requirement `(a / b)` that failed. + +Range concepts are defined in the `std::ranges` namespace, and declared in the `` header file. They're used in the declarations of [range adaptors](range-adaptors.md), [views](view-classes.md), and so on. + +There are six categories of ranges. They're related to the categories of iterators listed in [`` concepts](iterator-concepts.md). In order of increasing capability, the categories are: + +| Range concept | Description | +|--|--| +| [`output_range`](#output_range)
[`input_range`](#input_range) | Specifies a range that you can write to.
Specifies a range that you can read from once. | +| [`forward_range`](#forward_range) | Specifies a range that you can read (and possibly write) multiple times. | +| [`bidirectional_range`](#bidirectional_range) | Specifies a range that you can read and write both forwards and backwards. | +| [`random_access_range`](#random_access_range) | Specifies a range that you can read and write by index. | +| [`contiguous_range`](#contiguous_range) | Specifies a range whose elements are sequential in memory, are the same size, and can be accessed using pointer arithmetic. | + +In the preceding table, concepts are listed in order of increasing capability. A range that meets the requirements of a concept generally meets the requirements of the concepts in the rows that precede it. For example, a `random_access_range` has the capability of a `bidirectional_range`, `forward_range`, `input_range`, and `output_range`. The exception is `input_range`, which can't be written to, so it doesn't have the capabilities of `output_range`. + +:::image type="content" source="media/ranges-iterator-hiearchy.svg" alt-text="Diagram of the ranges iterator hierarchy. input_range and output_range are the most basic iterators. forward_range is next and refines both input_range and output_range. bidirectional_range refines forward_range. random_access_range refines bidirectional_range. Finally, contiguous_range refines random_access_range"::: + +Other range concepts include: + +| Range concept | Description | +|--|--| +| [`range`](#range)C++20 | Specifies a type that provides an iterator and a sentinel. | +| [`borrowed_range`](#borrowed_range)C++20 | Specifies that the lifetime of the range's iterators aren't tied to the range's lifetime. | +| [`common_range`](#common_range)C++20 | Specifies that the type of the range's iterator and the type of the range's sentinel are the same. | +| [`Simple_View`](#simple_view)C++20 | Not an official concept defined as part of the standard library, but used as a helper concept on some interfaces. | +| [`sized_range`](#sized_range)C++20 | Specifies a range that can provide its number of elements efficiently. | +| [`view`](#view)C++20 | Specifies a type that has efficient (constant time) move construction, assignment, and destruction. | +| [`viewable_range`](#viewable_range)C++20 | Specifies a type that either is a view or can be converted to one. | + +## `bidirectional_range` + +A `bidirectional_range` supports reading and writing the range forwards and backwards. + +```cpp +template +concept bidirectional_range = + forward_range && bidirectional_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `bidirectional_range`. + +### Remarks + +This kind of range supports [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator) or greater. +A `bidirectional_iterator` has the capabilities of a [`forward_iterator`](iterator-concepts.md#forward_iterator), but can also iterate backwards. + +Some examples of a `bidirectional_range` are `std::set`, `std::vector`, and `std::list`. + +## `borrowed_range` + +A type models `borrowed_range` if the validity of iterators you get from the object can outlive the lifetime of the object. That is, the iterators for a range can be used even when the range no longer exists. + +```cpp +template +concept borrowed_range = + range && + (is_lvalue_reference_v || enable_borrowed_range>); +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `borrowed_range`. + +### Remarks + +The lifetime of an rvalue range can end following a function call whether the range models `borrowed_range` or not. If it's a `borrowed_range`, you may be able to continue to use the iterators with well-defined behavior regardless of when the range's lifetime ends. + +Cases where this isn't true are, for example, for containers like `vector` or `list` because when the container's lifetime ends, the iterators would refer to elements that have been destroyed. + +You can continue to use the iterators for a `borrowed_range`, for example, for a `view` like `iota_view{0, 42}` whose iterators are over set of values that aren't subject to being destroyed because they're generated on demand. + +## `common_range` + +The type of the iterator for a `common_range` is the same as the type of the sentinel. That is, `begin()` and `end()` return the same type. + +```cpp +template +concept common_range = + ranges::range && std::same_as, ranges::sentinel_t>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `common_range`. + +### Remarks + +Getting the type from `std::ranges::begin()` and `std::ranges::end()` is important for algorithms that calculate the distance between two iterators, and for algorithms that accept ranges denoted by iterator pairs. + +The standard containers (for example, `vector`) meet the requirements of `common_range`. + +## `contiguous_range` + +The elements of a `contiguous_range` are stored sequentially in memory and can be accessed using pointer arithmetic. For example, an array is a `contiguous_range`. + +```cpp +template +concept contiguous_range = + random_access_range && contiguous_iterator> && + requires(T& t) {{ ranges::data(t) } -> same_as>>;}; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `contiguous_range`. + +### Remarks + +A `contiguous_range` can be accessed by pointer arithmetic because the elements are laid out sequentially in memory and are the same size. This kind of range supports [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator), which is the most flexible of all the iterators. + +Some examples of a `contiguous_range` are `std::array`, `std::vector`, and `std::string`. + +### Example: `contiguous_range` + +The following example shows using pointer arithmetic to access a `contiguous_range`: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + // Show that vector is a contiguous_range + std::vector v = {0,1,2,3,4,5}; + std::cout << std::boolalpha << std::ranges::contiguous_range << '\n'; // outputs true + + // Show that pointer arithmetic can be used to access the elements of a contiguous_range + auto ptr = v.data(); + ptr += 2; + std::cout << *ptr << '\n'; // outputs 2 +} +``` + +```output +true +2 +``` + +## `forward_range` + +A `forward_range` supports reading (and possibly writing) the range multiple times. + +```cpp +template +concept forward_range = input_range && forward_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `forward_range`. + +### Remarks + +This kind of range supports [`forward_iterator`](iterator-concepts.md#forward_iterator) or greater. A `forward_iterator` can iterate over a range multiple times. + +## `input_range` + +An `input_range` is a range that can be read from once. + +```cpp +template +concept input_range = range && input_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's an `input_range`. + +### Remarks + +When a type meets the requirements of `input_range`: + +- The `ranges::begin()` function returns an [`input_iterator`](iterator-concepts.md#input_iterator). Calling `begin()` more than once on an `input_range` results in undefined behavior. +- You can dereference an `input_iterator` repeatedly, which yields the same value each time. An `input_range` isn't multi-pass. Incrementing an iterator invalidates any copies. +- It can be used with `ranges::for_each`. +- It supports `input_iterator` or greater. + +## `output_range` + +An `output_range` is a range that you can write to. + +```cpp +template +concept output_range = range && output_iterator, T>; +``` + +### Parameters + +*`R`*\ +The type of the range. + +*`T`*\ +The type of the data to write to the range. + +### Remarks + +The meaning of `output_iterator, T>` is that the type provides an iterator that can write values of type `T` to a range of type `R`. In other words, it supports [`output_iterator`](iterator-concepts.md#output_iterator) or greater. + +## `random_access_range` + +A `random_access_range` can read or write a range by index. + +```cpp +template +concept random_access_range = +bidirectional_range && random_access_iterator>; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `random_access_range`. + +### Remarks + +This kind of range supports [`random_access_iterator`](iterator-concepts.md#random_access_iterator) or greater. A `random_access_range` has the capabilities of an `input_range`, `output_range`, `forward_range`, and `bidirectional_range`. A `random_access_range` is sortable. + +Some examples of a `random_access_range` are `std::vector`, `std::array`, and `std::deque`. + +## `range` + +Defines the requirements a type must meet to be a `range`. A `range` provides an iterator and a sentinel, so that you can iterate over its elements. + +```cpp +template +concept range = requires(T& rg) +{ + ranges::begin(rg); + ranges::end(rg); +}; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `range`. + +### Remarks + +The requirements of a `range` are: +- It can be iterated using `std::ranges::begin()` and `std::ranges::end()` +- `ranges::begin()` and `ranges::end()` run in amortized constant time and don't modify the `range`. Amortized constant time doesn't mean O(1), but that the average cost over a series of calls, even in the worst case, is O(n) rather than O(n^2) or worse. +- `[ranges::begin(), ranges::end())` denotes a valid range. + +## `Simple_View` + +A `Simple_View` is an exposition-only concept used on some `ranges` interfaces. It isn't defined in the library. It's only used in the specification to help describe the behavior of some range adaptors. + +```cpp +template + concept Simple_View = // exposition only + ranges::view && ranges::range && + std::same_as, std::ranges::iterator_t> && + std::same_as, std::ranges::sentinel_t>; +``` + +### Parameters + +*`V`*\ +The type to test to see if it's a `Simple_View`. + +### Remarks + +A view `V` is a [`Simple_View`](#simple_view) if all of the following are true: +- `V` is a view +- `const V` is a range +- Both `v` and `const V` have the same iterator and sentinel types. + +## `sized_range` + +A `sized_range` provides the number of elements in the range in amortized constant time. + +```cpp +template + concept sized_range = range && + requires(T& t) { ranges::size(t); }; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a `sized_range`. + +### Remarks + +The requirements of a `sized_range` are that calling `ranges::size` on it: + +- Doesn't modify the range. +- Returns the number of elements in amortized constant time. Amortized constant time doesn't mean O(1), but that the average cost over a series of calls, even in the worst case, is O(n) rather than O(n^2) or worse. + +Some examples of a `sized_range` are `std::list` and `std::vector`. + +### Example: `sized_range` + +The following example shows that a `vector` of `int` is a `sized_range`: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::cout << std::boolalpha << std::ranges::sized_range> << '\n'; // outputs "true" +} +``` + +## `view` + +A `view` has constant time move construction, assignment, and destruction operations--regardless of the number of elements it has. Views don't need to be copy constructible or copy assignable, but if they are, those operations must also run in constant time. + +Because of the constant time requirement, you can efficiently compose views. For example, given a vector of `int` called `input`, a function that determines if a number is divisible by three, and a function that squares a number, the statement `auto x = input | std::views::filter(divisible_by_three) | std::views::transform(square);` efficiently produces a view that contains the squares of the numbers in input that are divisible by three. Connecting views together with `|` is referred to as composing the views. If a type satisfies the [`view`](range-concepts.md#view) concept, then it can be composed efficiently. + +```cpp +template +concept view = ranges::range && std::movable && ranges::enable_view; +``` + +### Parameters + +*`T`*\ +The type to test to see if it's a view. + +### Remarks + +The essential requirement that makes a view composable is that it's cheap to move/copy. This is because the view is moved/copied when it's composed with another view. It must be a movable range. + +`ranges::enable_view` is a trait used to claim conformance to the semantic requirements of the `view` concept. A type can opt in by: +- publicly and unambiguously deriving from a specialization of `ranges::view_interface` +- publicly and unambiguously deriving from the empty class `ranges::view_base`, or +- specializing `ranges::enable_view` to `true` + +Option 1 is preferred because `view_interface` also provides default implementation that saves some boilerplate code you have to write. + +Failing that, option 2 is a little simpler than option 3. + +The advantage of option 3 is that it's possible without changing the definition of the type. + +## `viewable_range` + +A `viewable_range` is a type that either is a view or can be converted to one. + +```cpp +template + concept viewable_range = + range && (borrowed_range || view>); +``` + +### Parameters + +*`T`*\ +The type to test to see if it either is a view or can be converted to one. + +### Remarks + +Use `std::ranges::views::all()` to convert a range to a view. + +## See also + +[``](ranges.md)\ +[Range adaptors](range-adaptors.md)\ +[View classes](view-classes.md) \ No newline at end of file diff --git a/docs/standard-library/range-error-class.md b/docs/standard-library/range-error-class.md index a8b6485bcf3..35559c39d45 100644 --- a/docs/standard-library/range-error-class.md +++ b/docs/standard-library/range-error-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: range_error Class" -title: "range_error Class" -ms.date: "09/09/2021" +title: "range_error class" +description: "Learn more about: range_error class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::range_error"] helpviewer_keywords: ["range_error class"] -ms.assetid: 8afb3e88-fc49-4213-b096-ed63d7aea37c --- -# range_error Class +# `range_error` class The class serves as the base class for all exceptions thrown to report a range error (as in mathematics, not iterators). @@ -22,7 +21,7 @@ public: ## Remarks -The value returned by [what](../standard-library/exception-class.md) is a copy of `message.data()`. For more information, see [basic_string::data](../standard-library/basic-string-class.md#data). +The value returned by [`what`](exception-class.md) is a copy of `message.data()`. For more information, see [`basic_string::data`](basic-string-class.md#data). ## Example @@ -47,19 +46,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: The range is in error! Type: class std::range_error -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[runtime_error Class](../standard-library/runtime-error-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`runtime_error` class](runtime-error-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/range-functions.md b/docs/standard-library/range-functions.md index 37c0ecf3dbe..52c5fffab5f 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"] @@ -19,18 +19,18 @@ The ``C++20 header includes the following non-member helper f | [`crbegin`](#crbegin)C++20 | Get a reverse `const` iterator to the beginning of the range. | | [`crend`](#crend)C++20 | Get the sentinel at the end of what `crbegin()` returns. | | [`data`](#data)C++20 | Get a pointer to the first element in the contiguous range. | -| [`empty`](#empty)C++20 | Determine if the range is empty. | +| [`empty`](#empty)C++20 | Test if the range is empty. | | [`end`](#end)C++20 | Get the sentinel at the end of the range. | | [`rbegin`](#rbegin)C++20 | Get a reverse iterator to the beginning of the range. | | [`rend`](#rend)C++20 | Get a reverse iterator to the sentinel at the end of the range. | | [`size`](#size)C++20 | Get the size of the range as an unsigned value. | | [`ssize`](#ssize)C++20 | Get the size of the range as a signed value. | -Many of these 'functions' are implemented as [customization point objects](https://eel.is/c++draft/customization.point.object) A customization point object is a [function object](https://eel.is/c++draft/function.objects) that can be overloaded on user-defined types, while also enforcing constraints on which kinds of types can be passed to the function object. The net effect is that the compiler figures out if there's a valid customized function to call for the passed in type, or if the default implementation should be used, or if the call is ill-formed. +Many of these 'functions' are implemented as [customization point objects](https://eel.is/c++draft/customization.point.object). A customization point object is a [function object](https://eel.is/c++draft/function.objects) that can be overloaded on user-defined types, while also enforcing constraints on which kinds of types can be passed to the function object. The net effect is that the compiler figures out if there's a valid customized function to call for the passed in type, or if the default implementation should be used, or if the call is ill-formed. Many of these functions have corresponding functions in the `std` namespace. But when working with ranges, use these helper functions instead. These functions use C++20 concepts, which provide better compile time errors. Because they're implemented as customization points, problems related to argument dependent lookup (ADL) and const correctness are avoided. -## `begin` +## `begin` Get an iterator to the first element in the range. @@ -51,7 +51,7 @@ A range. An iterator to the first element in the range: -:::image type="content" source="media/range_functions/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled 'begin()'. The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled 'begin()'. The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: If the range is an array, returns the equivalent of `rg + 0`. If `auto(rg.begin())` yields an iterator, returns the equivalent of `auto(rg.begin())`. If that expression is ill-formed, `auto(begin(rg))` is used if that expression yields an iterator. @@ -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 @@ -76,7 +76,7 @@ int main() } ``` -## `cbegin` +## `cbegin` Get a `const` iterator to the first element in a range. The iterator can access the elements in the range, but can't modify them. @@ -98,7 +98,7 @@ A range. A `const` iterator to the first element in the range: -:::image type="content" source="media/range_functions/cbegin-cend-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled 'cbegin()'. The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled cend()."::: +:::image type="content" source="media/cbegin-cend-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled 'cbegin()'. The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled cend()."::: If the range is an array, returns the equivalent of `rg + 0`. If `auto(rg.cbegin())` yields an iterator, returns the equivalent of `auto(rg.cbegin())`. If that expression is ill-formed, `auto(cbegin(rg))` is used if that expression yields an iterator. @@ -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 @@ -124,7 +124,48 @@ int main() } ``` -## `cend` +## `cdata` + +Get a `const` pointer to the first element in the contiguous range. + +```cpp +template +constexpr std::add_pointer_t> cdata(T&& rg); +``` + +### Parameters + +*`T`*\ +The type of the range. + +*`rg`*\ +A range. + +### Return value + +A `const` pointer, based on the type of the range, to the first element data in the contiguous range. For example, if the range is a vector of integers, the type of the return value is a `const int *`. + +### Example: `cdata` + +```cpp +#include +#include + +int main() +{ + std::vector v{10, 20, 30}; + std::string src{ "a string" }; + + auto c_charPtr = std::ranges::cdata(src); // ptr is a const char * + auto c_intPtr = std::ranges::cdata(v); // ptr2 is a const int * + std::cout << c_charPtr << ", " << *c_intPtr << '\n'; // outputs a string, 10 + + // *c_intPtr = 100; // error - cannot assign to a const pointer + // *charPtr = 'A'; // error - cannot assign to a const pointer +} +``` + +## `cend` Get the sentinel at the end of the `const`-qualified range. The iterator can access the elements in the range, but can't modify them. @@ -146,13 +187,13 @@ A range. The sentinel that follows the last element in the `const`-qualified range: -:::image type="content" source="media/range_functions/cbegin-cend-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled cbegin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled cend()."::: +:::image type="content" source="media/cbegin-cend-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled cbegin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled cend()."::: ### Remarks `ranges::cend()` works on all ranges, whereas `std::cend()` may not. -### `cend` example +### Example: `cend` ```cpp // requires /std:c++20 or later @@ -170,7 +211,7 @@ int main() } ``` -## `crbegin` +## `crbegin` Get a reverse `const` iterator to the first element in a reversed range. A reverse iterator returns the elements of the range in reverse order. @@ -193,7 +234,7 @@ A range. A reverse `const` iterator to the first element in the range. This iterator returns the elements of the range in reverse order, starting at the end of the range: -:::image type="content" source="media/range_functions/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()."::: +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: If the range is an array, returns the equivalent of `reverse_iterator{rg + n}` where `n` is the number of elements in the array. If `auto(rg.crbegin())` yields an iterator, returns the equivalent of `auto(rg.crbegin())`. If that expression is ill-formed, `auto(crbegin(rg))` is used if that expression yields an iterator. @@ -202,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 @@ -219,7 +260,7 @@ int main() } ``` -## `crend` +## `crend` Get the sentinel at the end of what `crbegin()` returns. A reverse iterator returns the elements of the range in reverse order. @@ -242,13 +283,13 @@ A range. The sentinel at the end of what `cbegin()` returns. The sentinel follows the last element in a reversed view of the range: -:::image type="content" source="media/range_functions/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()."::: +:::image type="content" source="media/crbegin-crend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled crend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled crbegin()."::: ### Remarks `ranges::crend()` works on all bidirectional ranges, whereas `std::crend()` may not. -### `crend`example +### `crend` example ```cpp // requires /std:c++20 or later @@ -267,7 +308,7 @@ int main() } ``` -## `data` +## `data` Get a pointer to the first element in a contiguous range. @@ -303,20 +344,20 @@ int main() auto charPtr = std::ranges::data(src); // charPtr is a char * auto intPtr = std::ranges::data(v); // intPtr is an int * - std::cout << charPtr << ", " << *intPtr << '\n'; // outputs: a string, 10 + std::cout << charPtr << ", " << *intPtr << '\n'; // outputs a string, 10 *intPtr = 100; *charPtr = 'A'; - std::cout << charPtr << ", " << *intPtr; // outputs: A string, 100 + std::cout << charPtr << ", " << *intPtr; // outputs A string, 100 } ``` -## `cdata` +## `empty` -Get a `const` pointer to the first element in the contiguous range. +Test if the range is empty. ```cpp template -constexpr std::add_pointer_t> cdata(T&& rg); +constexpr bool empty(T&& rg); ``` ### Parameters @@ -329,9 +370,9 @@ A range. ### Return value -A `const` pointer, based on the type of the range, to the first element data in the contiguous range. For example, if the range is a vector of integers, the type of the return value is a `const int *`. +Returns `true` if the range has no elements; otherwise `false`. -### `cdata` Example +### Example ```cpp // requires /std:c++20 or later @@ -341,19 +382,15 @@ A `const` pointer, based on the type of the range, to the first element data in int main() { - std::vector v{10, 20, 30}; - std::string src{ "a string" }; - - auto c_charPtr = std::ranges::cdata(src); // ptr is a const char * - auto c_intPtr = std::ranges::cdata(v); // ptr2 is a const int * - std::cout << c_charPtr << ", " << *c_intPtr << '\n'; // outputs: a string, 10 + std::vector v{10,20,30}; + std::vector v2; - // *c_intPtr = 100; // error - cannot assign to a const pointer - // *charPtr = 'A'; // error - cannot assign to a const pointer + std::cout << std::boolalpha << std::ranges::empty(v); // outputs false + std::cout << std::boolalpha << ", " << std::ranges::empty(v2); // outputs true } ``` -## `end` +## `end` Get the sentinel at the end of the range. @@ -374,7 +411,7 @@ A range. The sentinel that follows the last element in the range: -:::image type="content" source="media/range_functions/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled cend()."::: +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: ### Remarks @@ -397,46 +434,7 @@ int main() } ``` -## `empty` - -Determine if the range is empty. - -```cpp -template -constexpr bool empty(T&& rg); -``` - -### Parameters - -*`T`*\ -The type of the range. - -*`rg`*\ -A range. - -### Return value - -Returns `true` if the range has no elements; otherwise `false.` - -### Example - -```cpp -// requires /std:c++20 or later -#include -#include -#include - -int main() -{ - std::vector v{10,20,30}; - std::vector v2; - - std::cout << std::boolalpha << std::ranges::empty(v); // outputs: false - std::cout << std::boolalpha << ", " << std::ranges::empty(v2); // outputs: true -} -``` - -## `rbegin` +## `rbegin` Get a reverse iterator to the first element in a reversed range. A reverse iterator returns the elements of the range in reverse order. @@ -459,7 +457,7 @@ A range. A reverse iterator to the first element in the range. This iterator returns the elements of the range in reverse order, starting at the end of the reversed range: -:::image type="content" source="media/range_functions/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()."::: +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: If the range is an array, returns the equivalent of `reverse_iterator{rg + n}` where `n` is the number of elements in the array. If `auto(rg.rbegin())` yields an iterator, returns the equivalent of `auto(rg.rbegin())`. If that expression is ill-formed, `auto(rbegin(rg))` is used if that expression yields an iterator. @@ -484,7 +482,7 @@ int main() } ``` -## `rend` +## `rend` Get a reverse iterator to the sentinel at the end of a reversed view of the range. A reverse iterator returns the elements of the range in reverse order. @@ -508,7 +506,7 @@ A range. A reverse iterator to the sentinel at the end of the range. The sentinel follows the last element in a reversed view of the range: -:::image type="content" source="media/range_functions/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()."::: +:::image type="content" source="media/rbegin-rend-sentinel.png" alt-text="Picture of a vector containing the elements 10, 20, and 30. There's an imaginary box before the leftmost element (the leftmost element contains the number 10) that represents the sentinel. It's labeled rend(). The first element in the vector contains the number 10, and is labeled 'last element'. The rightmost element in the vector contains 30 and is labeled rbegin()."::: ### Remarks @@ -532,7 +530,7 @@ int main() } ``` -## `size` +## `size` Get the number of elements in the range as an unsigned value. @@ -573,7 +571,7 @@ int main() } ``` -## `ssize` +## `ssize` Get the size of the range as a signed value. diff --git a/docs/standard-library/ranges-alias-templates.md b/docs/standard-library/ranges-alias-templates.md new file mode 100644 index 00000000000..8e709eff0ca --- /dev/null +++ b/docs/standard-library/ranges-alias-templates.md @@ -0,0 +1,563 @@ +--- +title: " alias templates" +description: "Learn more about ranges 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 9b9cb2e6c70..68d5e603044 100644 --- a/docs/standard-library/ranges.md +++ b/docs/standard-library/ranges.md @@ -1,24 +1,24 @@ --- title: "" -description: "Overview of the Standard Template Library (STL) ranges library" -ms.date: 06/08/2022 +description: "Get an overview of the Standard Template Library (STL) ranges." +ms.date: 01/27/2023 f1_keywords: [""] helpviewer_keywords: ["ranges"] --- # `` -At a high level, a range is something you can iterate over. A range abstracts iterators in a way that simplifies and amplifies your ability to use the Standard Template Library (STL). +At a high level, a *range* is something that you can iterate over. A range is represented by an iterator that marks the beginning of the range and a sentinel that marks the end of the range. The sentinel may be the same type as the begin iterator, or it may be different. The containers, such as `vector` and `list`, in the C++ Standard Library are ranges. A range abstracts iterators in a way that simplifies and amplifies your ability to use the Standard Template Library (STL). -STL algorithms usually take iterators that point to the portion of the collection they should operate on. Consider how you sort a `vector` using `std::sort()`. You pass two iterators the mark the beginning and end of the `vector`. That provides flexibility, but passing the iterators to the algorithm is extra work since most of the time you just want to sort the whole thing. +STL algorithms usually take iterators that point to the portion of the collection that they should operate on. For example, consider how you sort a `vector` by using `std::sort()`. You pass two iterators that mark the beginning and end of the `vector`. That provides flexibility, but passing the iterators to the algorithm is extra work because you probably just want to sort the whole thing. -With ranges, you can call `std::ranges::sort(myVector);` which is treated as if you had called `std::sort(myVector.begin(), myVector.end());` In range libraries, algorithms take ranges as parameters (although they can also take iterators, if you want). Examples of range algorithms available in `` include `copy`, `copy_n`, `copy_if`, `all_of`, `any_of`, and `none_of`, `find`, `find_if`, and `find_if_not`, `count` and `count_if`, `for_each` and `for_each_n`, `equal` and `mismatch`. +With ranges, you can call `std::ranges::sort(myVector);`, which is treated as if you called `std::sort(myVector.begin(), myVector.end());`. In range libraries, algorithms take ranges as parameters (although they can also take iterators, if you want). They can operate directly on collections. Examples of range algorithms available in `` include `copy`, `copy_n`, `copy_if`, `all_of`, `any_of`, `none_of`, `find`, `find_if`, `find_if_not`, `count`, `count_if`, `for_each`, `for_each_n`, `equal`, and `mismatch`. -But the benefits of ranges go further than this. Perhaps the most important benefit is that you can compose STL algorithms that operate on ranges much more easily. +But perhaps the most important benefit of ranges is that you can compose STL algorithms that operate on ranges in a style that's reminiscent of functional programming. ## A ranges example -Before ranges, if you wanted to transform only the elements of a collection that meet a certain criteria, you'd need to introduce an intermediate step to hold the results between operations. For example, let's say you want to build a vector of squares from only the elements in another vector that are divisible by 3. You'd write something like: +Before ranges, if you wanted to transform the elements of a collection that met a certain criterion, you needed to introduce an intermediate step to hold the results between operations. For example, if you wanted to build a vector of squares from the elements in another vector that are divisible by three, you could write something like: ```cpp std::vector input = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; @@ -31,35 +31,34 @@ std::transform(intermediate.begin(), intermediate.end(), std::back_inserter(outp With ranges, you can accomplish the same thing without needing the `intermediate` vector: ```cpp -// requires /std:c++latest -std::vector input = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; - -auto output = input | std::views::filter([](const int n) {return n % 3 == 0; }) | std::views::transform([](const int n) {return n * n; }); -``` +// requires /std:c++20 +std::vector input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; -Besides being easier to read, it avoids the memory allocation required for the `intermediate` vector and its contents, while also allowing you to compose two operations. +auto output = input + | std::views::filter([](const int n) {return n % 3 == 0; }) + | std::views::transform([](const int n) {return n * n; }); +``` -In the code above, each element that is divisible by three is combined with an operation to square that element. The '`|`' symbol chains the operations together, and is read left to right. +Besides being easier to read, this code avoids the memory allocation that's required for the `intermediate` vector and its contents. It also allows you to compose two operations. -The result, `output`, is itself a type of range called a view, which is discussed next. +In the preceding code, each element that's divisible by three is combined with an operation to square that element. The pipe (`|`) symbol chains the operations together and is read left to right. -> [!NOTE] -> The ranges examples require the [`/std:c++latest`](../build/reference/std-specify-language-standard-version.md) compiler option. Because post-release updates to `` in the C++20 Standard are a work in progress, the features that require `std::views` aren't enabled yet under **`/std:c++20`**. +The result, `output`, is itself a kind of range called a *view*. ## Views -A view is a lightweight range. View operations such as default construction, move construction/assignment, copy construction/assignment (if present), destruction, begin and end, all happen in constant time regardless of the number of elements in the view. +A view is a lightweight range. View operations--such as default construction, move construction/assignment, copy construction/assignment (if present), destruction, begin, and end--all happen in constant time regardless of the number of elements in the view. -Views are created by range adaptors, which are discussed in the following section. +Views are created by range adaptors, which are discussed in the following section. For more information about the classes that implement various views, see [View classes](view-classes.md). -How the elements in the view appear depends on the range adaptor you use to create the view. In the previous example, a range adaptor takes a range and returns a view of only those elements that are divisible by three. The underlying range is unchanged. +How the elements in the view appear depends on the range adaptor that you use to create the view. In the previous example, a range adaptor takes a range and returns a view of the elements divisible by three. The underlying range is unchanged. -Views are composable. In the previous example, the view of vector elements that are divisible by three is combined with the view that squares those elements. +Views are composable, which is powerful. In the previous example, the view of vector elements that are divisible by three is combined with the view that squares those elements. -The elements of a view are evaluated lazily. That is, the transformations you apply to each element in a view aren't evaluated until you ask for the element. For example, if you run the following code in a debugger and put a breakpoint on the lines `auto divisible_by_three = ...` and `auto square = ...`, you'll see that you hit the `divisible_by_three` lambda breakpoint as each element in `input` is tested for divisibility by three. The `square` lambda breakpoint will be hit as the elements that are divisible by three are squared. +The elements of a view are evaluated lazily. That is, the transformations that you apply to each element in a view aren't evaluated until you ask for the element. For example, if you run the following code in a debugger and put a breakpoint on the lines `auto divisible_by_three = ...` and `auto square = ...`, you'll see that you hit the `divisible_by_three` lambda breakpoint as each element in `input` is tested for divisibility by three. The `square` lambda breakpoint will be hit as the elements that are divisible by three are squared. ```cpp -// requires /std:c++latest +// requires /std:c++20 #include #include #include @@ -81,36 +80,87 @@ int main() } ``` +For more information about views, see [`` view classes](view-classes.md). + ## Range adaptors -Range adaptors produce views. In the previous example, the first range adaptor provides a view of `input` that has the elements that are divisible by three. The other range adaptor takes the elements divisible by three, and provides each element's square. +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. -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. The cost to process an element in the view is only incurred when you access that element. +In the previous example, the `filter` range adaptor creates a view named `input` that contains the elements that are divisible by three. The `transform` range adaptor takes the view of elements divisible by three and creates a view of those elements squared. -Range adaptors come in many forms. There are range adaptors that allow you to produce a view by filtering another range based on a predicate (`view::filter`), transforming the elements in a range (`view::transform`), splitting a range (`view::split()`), and more. +Range adaptors can be chained together (composed), which is the heart of the power and flexibility of ranges. Composing range adaptors allows you to overcome the problem that the previous STL algorithms aren't easily composable. -Range adaptors can be chained or composed--which is where the power and flexibility of ranges is most apparent. Composing range adaptors allows you to overcome a core problem with the previous STL algorithms, which aren't easily composable. +For more information about creating views, see [Range adaptors](range-adaptors.md). ## Range algorithms -Range algorithms have been created that take a range argument. For example, `std::ranges::sort(myVector);` +Some range algorithms take a range argument. An example is `std::ranges::sort(myVector);`. + +The range algorithms are almost identical to the corresponding iterator-pair algorithms in the `std` namespace. The difference is that they have [concept-enforced constraints](range-concepts.md), and they accept either range arguments or more iterator-sentinel argument pairs. They can work directly on a container and can be easily chained together. + +## `` 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. | +| [`cbegin`](range-functions.md#cbegin)C++20 | Get a `const` iterator to the first element in the range. | +| [`cend`](range-functions.md#cend)C++20 | Get the sentinel at the end of the `const`-qualified range. | +| [`cdata`](range-functions.md#cdata)C++20 | Get a `const` pointer to the first element in the contiguous range. | +| [`crbegin`](range-functions.md#crbegin)C++20 | Get a reverse `const` iterator to the beginning of the range. | +| [`crend`](range-functions.md#crend)C++20 | Get the sentinel at the end of what `crbegin()` returns. | +| [`data`](range-functions.md#data)C++20 | Get a pointer to the first element in the contiguous range. | +| [`empty`](range-functions.md#empty)C++20 | Determine if the range is empty. | +| [`end`](range-functions.md#end)C++20 | Get the sentinel at the end of the range. | +| [`rbegin`](range-functions.md#rbegin)C++20 | Get a reverse iterator to the beginning of the range. | +| [`rend`](range-functions.md#rend)C++20 | Get a reverse iterator to the sentinel at the end of the range. | +| [`size`](range-functions.md#size)C++20 | Get the size of the range as an unsigned value. | +| [`ssize`](range-functions.md#ssize)C++20 | Get the size of the range as a signed value. | + +For more information, see [`` functions](range-functions.md). -The range algorithms are almost identical to the corresponding iterator-pair algorithms in the `std` namespace, except that they have concept-enforced constraints and accept range arguments or more general iterator-sentinel argument pairs. They can work directly on a container, and can be easily chained together. +## Range concepts -## Types of ranges +How you iterate over the elements of a range depends on its underlying iterator type. Ranges use C++ concepts that specify which iterator they support. -What you can do with a range depends on its underlying iterator type. Range concepts are refinements of the `range` concept. In C++ 20, to say that concept X refines concept Y means that everything that satisfies Y also satisfies X--though not necessarily the other way around. For example, car, bus, and truck all refine vehicle. +In C++20, to say that concept *X* refines concept *Y* means that everything that satisfies concept *Y* also satisfies concept *X*. For example: *car*, *bus*, and *truck* all refine *vehicle*. -The range concepts mirror the hierarchy of iterator categories. This table lists various range concepts, along with the type of container they can be applied to: +Some range concepts mirror the hierarchy of iterator categories. The following table lists the range concepts, along with the types of containers that they can be applied to. | Range concept | Description | Supported containers | |--|--|--| -| `std::ranges::input_range` | Can iterate from beginning to end at least once | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset`
`basic_istream_view` | -| `std::ranges::forward_range` | Can iterate from beginning to end more than once) | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset` | -| `std::ranges::bidirectional_range` | Can iterate forward and backward more than once | `std::list`
`std::map`
`std::multimap`
`std::multiset`
`std::set`| -| `std::ranges::random_access_range` | Can access an arbitrary element (in constant time) using the `[]` operator) | `std::deque` | -| `std::ranges::contiguous_range` | The elements are stored in memory consecutively | `std::array`
`std::string`
`std::vector` | +| [`std::ranges::output_range`](range-concepts.md#output_range) | Can iterate forward. || +| [`std::ranges::input_range`](range-concepts.md#input_range) | Can iterate from beginning to end at least once. | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset`
`basic_istream_view`| +| [`std::ranges::forward_range`](range-concepts.md#forward_range) | Can iterate from beginning to end more than once. | `std::forward_list`
`std::unordered_map`
`std::unordered_multimap`
`std::unordered_set`
`std::unordered_multiset` | +| [`std::ranges::bidirectional_range`](range-concepts.md#bidirectional_range) | Can iterate forward and backward more than once. | `std::list`
`std::map`
`std::multimap`
`std::multiset`
`std::set`| +| [`std::ranges::random_access_range`](range-concepts.md#random_access_range) | Can access an arbitrary element (in constant time) by using the `[]` operator. | `std::deque` | +| [`std::ranges::contiguous_range`](range-concepts.md#contiguous_range) | The elements are stored in memory consecutively. | `std::array`
`std::string`
`std::vector` | + +See [`` concepts](range-concepts.md) for more information about these concepts. + +## `` alias templates + +The following alias templates determine the types of iterators and sentinels for a range: + +| Alias template | Description | +|--|--| +| [`borrowed_iterator_t`](ranges-alias-templates.md#borrowed_iterator_t)C++20 | Determine if an iterator returned for a `range` refers to a range whose lifetime has ended. | +| [`borrowed_subrange_t`](ranges-alias-templates.md#borrowed_subrange_t)C++20 | Determine if an iterator returned for a `subrange` refers to a subrange whose lifetime has ended.| +| [`dangling`](ranges-alias-templates.md#dangling)C++20 | Indicates that the returned iterator of a `range`/`subrange` outlives the lifetime of the `range`/`subrange` it refers to. | +| [`iterator_t`](ranges-alias-templates.md#iterator_t)C++20 | Returns the iterator type of the specified range type. | +| [`range_difference_t`](ranges-alias-templates.md#range_difference_t)C++20 | Returns the difference type of the specified range's iterator type. | +| [`range_reference_t`](ranges-alias-templates.md#range_reference_t)C++20 | Returns the reference type of the specified range's iterator type. | +| [`range_rvalue_reference_t`](ranges-alias-templates.md#range_rvalue_reference_t)C++20 | Returns the rvalue reference type for the specified range's iterator type. In other words, the rvalue reference type of the range's elements. | +| [`range_size_t`](ranges-alias-templates.md#range_size_t)C++20 | Returns the type used to report the specified range's size. | +| [`range_value_t`](ranges-alias-templates.md#range_value_t)C++20 | Returns the value type of the specified range's iterator type. Or in other words, the type of the elements in the range. | +| [`sentinel_t`](ranges-alias-templates.md#sentinel_t)C++20 | Returns the sentinel type of the specified range. | + +For more information about these alias templates, see [`` alias templates](ranges-alias-templates.md). ## See also -[Header Files Reference](../standard-library/cpp-standard-library-header-files.md) +[`` functions](range-functions.md)\ +[`` concepts](range-concepts.md)\ +[Range adaptors](range-adaptors.md)\ +[Header files reference](../standard-library/cpp-standard-library-header-files.md) \ No newline at end of file diff --git a/docs/standard-library/rank-class.md b/docs/standard-library/rank-class.md index 7812e4b0417..f1c39092e5d 100644 --- a/docs/standard-library/rank-class.md +++ b/docs/standard-library/rank-class.md @@ -1,41 +1,41 @@ --- -description: "Learn more about: rank Class" -title: "rank Class" -ms.date: "11/04/2016" +title: "rank class" +description: "Learn more about: rank class" +ms.date: 08/28/2025 f1_keywords: ["type_traits/std::rank"] helpviewer_keywords: ["rank class", "rank"] -ms.assetid: bc9f1b8f-800f-46ca-b6f4-d8579ed5406a --- -# rank Class +# `rank` class Gets number of array dimensions. ## Syntax ```cpp -template +template struct rank; ``` -### Parameters +### Template parameters -*Ty*\ +*`Type`*\ The type to query. ## Remarks -The type query holds the value of the number of dimensions of the array type *Ty*, or 0 if *Ty* is not an array type. +The type query holds the value of the number of dimensions of the array type *`Type`*, or 0 if *`Type`* is not an array type. ## Example ```cpp // std__type_traits__rank.cpp // compile with: /EHsc + #include #include int main() - { +{ std::cout << "rank == " << std::rank::value << std::endl; std::cout << "rank == " @@ -43,23 +43,32 @@ int main() std::cout << "rank == " << std::rank::value << std::endl; - return (0); - } + int single_dim_array[]{ 1, 2, 3 }; + int double_dim_array[2][1]{ { 4 }, { 5 } }; + + std::cout << "\nrank == " + << std::rank::value << std::endl; + std::cout << "rank == " + << std::rank::value << std::endl; +} ``` ```Output rank == 0 rank == 1 rank == 2 + +rank == 1 +rank == 2 ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[](../standard-library/type-traits.md)\ -[extent Class](../standard-library/extent-class.md) +[``](type-traits.md)\ +[`extent` class](extent-class.md) diff --git a/docs/standard-library/ratio.md b/docs/standard-library/ratio.md index 05922b7ff4b..1df9000050b 100644 --- a/docs/standard-library/ratio.md +++ b/docs/standard-library/ratio.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: ["", "ratio/std::mega", "ratio/std::peta", "ratio/std::ratio_greater", "ratio/std::micro", "ratio/std::ratio_add", "ratio/std::ratio_not_equal", "ratio/std::hecto", "ratio/std::nano", "ratio/std::ratio_less_equal", "ratio/std::ratio_less", "ratio/std::centi", "ratio/std::ratio_greater_equal", "ratio/std::ratio_subtract", "ratio/std::atto", "ratio/std::tera", "ratio/std::milli", "ratio/std::ratio_multiply", "ratio/std::kilo", "ratio/std::ratio_divide", "ratio/std::giga", "ratio/std::pico", "ratio/std::femto", "ratio/std::ratio_equal", "ratio/std::ratio", "ratio/std::exa", "ratio/std::deci", "ratio/std::deca"] -ms.assetid: 8543e912-2d84-45ea-b3c0-bd7bfacee405 --- # `` @@ -24,7 +23,7 @@ struct ratio // holds the ratio of Numerator to Denominator static constexpr std::intmax_t num; static constexpr std::intmax_t den; typedef ratio type; -} +}; ``` The template `ratio` defines the static constants `num` and `den` such that `num` / `den` == Numerator / Denominator and `num` and `den` have no common factors. `num` / `den` is the value that is represented by the class template. Therefore, `type` designates the instantiation `ratio`. diff --git a/docs/standard-library/raw-storage-iterator-class.md b/docs/standard-library/raw-storage-iterator-class.md index 3e8ce704732..e4efd88df18 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; @@ -135,9 +134,9 @@ int main( void) { Int *pInt = ( Int* ) malloc( sizeof( Int ) ); memset( pInt, 0, sizeof( Int ) ); // Set bIsConstructed to false; -*pInt = 5; + *pInt = 5; raw_storage_iterator< Int*, Int > it( pInt ); -*it = 5; + *it = 5; } ``` @@ -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; @@ -262,9 +261,9 @@ int main( void ) std::raw_storage_iterator it( pInt ); for ( int i = 0; i < 5; i++, it++ ) { *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/recursive-mutex-class.md b/docs/standard-library/recursive-mutex-class.md index 451a7686a46..68223c40baa 100644 --- a/docs/standard-library/recursive-mutex-class.md +++ b/docs/standard-library/recursive-mutex-class.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: recursive_mutex Class" title: "recursive_mutex Class" -ms.date: "11/04/2016" +description: "Learn more about: recursive_mutex Class" +ms.date: 11/04/2016 f1_keywords: ["mutex/std::recursive_mutex", "mutex/std::recursive_mutex::recursive_mutex", "mutex/std::recursive_mutex::lock", "mutex/std::recursive_mutex::try_lock", "mutex/std::recursive_mutex::unlock"] -ms.assetid: eb5ffd1b-7e78-4559-8391-bb220ead42fc helpviewer_keywords: ["std::recursive_mutex [C++]", "std::recursive_mutex [C++], recursive_mutex", "std::recursive_mutex [C++], lock", "std::recursive_mutex [C++], try_lock", "std::recursive_mutex [C++], unlock"] --- # recursive_mutex Class @@ -59,7 +58,7 @@ Constructs a `recursive_mutex` object that is not locked. recursive_mutex(); ``` -## ~recursive_mutex +## ~recursive_mutex Releases any resources that are used by the object. diff --git a/docs/standard-library/recursive-timed-mutex-class.md b/docs/standard-library/recursive-timed-mutex-class.md index 3728a0eb94d..d105a0a2646 100644 --- a/docs/standard-library/recursive-timed-mutex-class.md +++ b/docs/standard-library/recursive-timed-mutex-class.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: recursive_timed_mutex Class" title: "recursive_timed_mutex Class" -ms.date: "11/04/2016" +description: "Learn more about: recursive_timed_mutex Class" +ms.date: 11/04/2016 f1_keywords: ["mutex/std::recursive_timed_mutex", "mutex/std::recursive_timed_mutex::recursive_timed_mutex", "mutex/std::recursive_timed_mutex::lock", "mutex/std::recursive_timed_mutex::try_lock", "mutex/std::recursive_timed_mutex::try_lock_for", "mutex/std::recursive_timed_mutex::try_lock_until", "mutex/std::recursive_timed_mutex::unlock"] -ms.assetid: 59cc2d5c-ed80-45f3-a0a8-05652a8ead7e helpviewer_keywords: ["std::recursive_timed_mutex [C++]", "std::recursive_timed_mutex [C++], recursive_timed_mutex", "std::recursive_timed_mutex [C++], lock", "std::recursive_timed_mutex [C++], try_lock", "std::recursive_timed_mutex [C++], try_lock_for", "std::recursive_timed_mutex [C++], try_lock_until", "std::recursive_timed_mutex [C++], unlock"] --- # recursive_timed_mutex Class @@ -61,7 +60,7 @@ Constructs a `recursive_timed_mutex` object that is not locked. recursive_timed_mutex(); ``` -## ~recursive_timed_mutex Destructor +## ~recursive_timed_mutex Destructor Releases any resources that are used by the `recursive_timed_mutex` object. diff --git a/docs/standard-library/ref-view-class.md b/docs/standard-library/ref-view-class.md new file mode 100644 index 00000000000..179d45ce0fa --- /dev/null +++ b/docs/standard-library/ref-view-class.md @@ -0,0 +1,216 @@ +--- +title: ref_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) ref_view class, which is a view that references the elements of another range. It's essentially a view of the elements of another range." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::ref_view", "ranges/std::ref_view::base", "ranges/std::ref_view::begin", "ranges/std::ref_view::data", "ranges/std::ref_view::empty", "ranges/std::ref_view::end", "ranges/std::ref_view::size", "ranges/std::ref_view::operator bool", "ranges/std::ref_view::back", "ranges/std::ref_view::front", "ranges/std::ref_view::operator[]"] +helpviewer_keywords: ["std::ranges::ref_view [C++]", "std::ranges::ref_view::base [C++]", "std::ranges::ref_view::begin [C++]", "std::ranges::ref_view::data [C++]", "std::ranges::ref_view::empty [C++]", "std::ranges::ref_view::end [C++]", "std::ranges::ref_view::size [C++]", "std::ranges::ref_view::operator bool [C++]", "std::ranges::ref_view::back [C++]", "std::ranges::ref_view::front [C++]", "std::ranges::ref_view::operator[] [C++]"] +dev_langs: ["C++"] +--- +# `ref_view` class (C++ Standard Library) + + A view that references the elements that belong to another range. + +## Syntax + +```cpp +template + requires std::is_object_v +class ref_view : public ranges::view_interface>; +``` + +### Template parameters + +*`R`*\ + The range to reference. + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `ref_view`. | +| [`base`](#base)C++20 | Get a reference to the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element in the referenced range. | +| [`empty`](#empty)C++20 | Test whether this `ref_view` is empty. | +| [`end`](#end)C++20 | Get the sentinel at the end of this `ref_view`. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether this `ref_view` isn't empty. | + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::all`](range-adaptors.md#all) or [`views::common`](range-adaptors.md#common) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Yes | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Yes | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `ref_view` + +```cpp +// construct a ref_view from a range +template R> +constexpr ref_view(R&& rg); +``` + +### Parameters + +*`rg`*\ +The range to reference. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `ref_view` instance. + +### Remarks + +The best way to create a `ref_view` is by using the [`views::all`](range-adaptors.md#all) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +A `ref_view` is useful for converting a container to a view. For example, you can use `ref_view` to convert a `vector` to a view, which makes it inexpensive to pass the elements of the vector around. + +### Example: `ref_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v = {1,2,3}; + auto refView = std::views::all(v); + std::cout << &refView[1] << " : " << &v[1]; // outputs two identical memory addresses, e.g. 00000239AFAFDF90 : 00000239AFAFDF90 + refView[0] = 10; // modifies v[0] + std::cout << "\n" << v[0]; // 10 +} +``` + +```output +00000239AFAFDF90 : 00000239AFAFDF90 +10 +``` + +## `base` + +Gets a copy of the underlying range. + +```cpp +constexpr R& base() const; +``` + +### Parameters + +None. + +### Return value + +The underlying range. + +## `begin` + +Get an iterator to the first element in the `ref_view`. + +```cpp +constexpr iterator_t begin() const; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in this `ref_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `data` + +Get a pointer to the first element in this `ref_view`. The elements in the range must be contiguous. + +```cpp +constexpr auto data() const requires contiguous_range; +``` + +### Parameters + +None. + +### Return value + +A pointer to the first element. + +## `empty` + +Test whether this `ref_view` is empty. + +```cpp +constexpr bool empty() const +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the `ref_view` contains no elements. Otherwise, `false`. + +## `end` + +Get the sentinel at the end of this `ref_view`. + +```cpp +constexpr sentinel_t end() const +``` + +### Return value + +The sentinel that follows the last element in this `ref_view`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() const requires sized_range +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `ref_view`. + +## See also + +[``](ranges.md)\ +[`all` range adaptor](range-adaptors.md#all)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/regex-constants-class.md b/docs/standard-library/regex-constants-class.md index 63ef9ea01f1..df849bdbf67 100644 --- a/docs/standard-library/regex-constants-class.md +++ b/docs/standard-library/regex-constants-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: regex_constants namespace" title: "regex_constants Class" -ms.date: "09/10/2018" +description: "Learn more about: regex_constants namespace" +ms.date: 09/10/2018 f1_keywords: ["regex/std::regex_constants", "regex/std::regex_constants::error_collate", "regex/std::regex_constants::error_ctype", "regex/std::regex_constants::error_escape", "regex/std::regex_constants::error_backref", "regex/std::regex_constants::error_brack", "regex/std::regex_constants::error_paren", "regex/std::regex_constants::error_brace", "regex/std::regex_constants::error_badbrace", "regex/std::regex_constants::error_range", "regex/std::regex_constants::error_space", "regex/std::regex_constants::error_badrepeat", "regex/std::regex_constants::error_complexity", "regex/std::regex_constants::error_stack", "regex/std::regex_constants::error_parse", "regex/std::regex_constants::error_syntax", "regex/std::regex_constants::match_default", "regex/std::regex_constants::match_not_bol", "regex/std::regex_constants::match_not_eol", "regex/std::regex_constants::match_not_bow", "regex/std::regex_constants::match_not_eow", "regex/std::regex_constants::match_any", "regex/std::regex_constants::match_not_null", "regex/std::regex_constants::match_continuous", "regex/std::regex_constants::match_prev_avail", "regex/std::regex_constants::format_default", "regex/std::regex_constants::format_sed", "regex/std::regex_constants::format_no_copy", "regex/std::regex_constants::format_first_only", "regex/std::regex_constants::ECMAScript", "regex/std::regex_constants::basic", "regex/std::regex_constants::extended", "regex/std::regex_constants::awk", "regex/std::regex_constants::grep", "regex/std::regex_constants::egrep", "regex/std::regex_constants::icase", "regex/std::regex_constants::nosubs", "regex/std::regex_constants::optimize", "regex/std::regex_constants::collate"] helpviewer_keywords: ["std::regex_constants [C++]", "std::regex_constants [C++], error_collate", "std::regex_constants [C++], error_ctype", "std::regex_constants [C++], error_escape", "std::regex_constants [C++], error_backref", "std::regex_constants [C++], error_brack", "std::regex_constants [C++], error_paren", "std::regex_constants [C++], error_brace", "std::regex_constants [C++], error_badbrace", "std::regex_constants [C++], error_range", "std::regex_constants [C++], error_space", "std::regex_constants [C++], error_badrepeat", "std::regex_constants [C++], error_complexity", "std::regex_constants [C++], error_stack", "std::regex_constants [C++], error_parse", "std::regex_constants [C++], error_syntax", "std::regex_constants [C++], match_default", "std::regex_constants [C++], match_not_bol", "std::regex_constants [C++], match_not_eol", "std::regex_constants [C++], match_not_bow", "std::regex_constants [C++], match_not_eow", "std::regex_constants [C++], match_any", "std::regex_constants [C++], match_not_null", "std::regex_constants [C++], match_continuous", "std::regex_constants [C++], match_prev_avail", "std::regex_constants [C++], format_default", "std::regex_constants [C++], format_sed", "std::regex_constants [C++], format_no_copy", "std::regex_constants [C++], format_first_only", "std::regex_constants [C++], ECMAScript", "std::regex_constants [C++], basic", "std::regex_constants [C++], extended", "std::regex_constants [C++], awk", "std::regex_constants [C++], grep", "std::regex_constants [C++], egrep", "std::regex_constants [C++], icase", "std::regex_constants [C++], nosubs", "std::regex_constants [C++], optimize", "std::regex_constants [C++], collate"] -ms.assetid: 4a69c0ba-c46d-46e4-bd29-6f4efb805f26 --- # regex_constants namespace @@ -199,7 +198,7 @@ The syntax modifiers are: `icase` -- make matches case-insensitive -`nosubs` -- the implementaton need not keep track of the contents of capture groups +`nosubs` -- the implementation need not keep track of the contents of capture groups `optimize` -- the implementation should emphasize speed of matching rather than speed of regular expression compilation diff --git a/docs/standard-library/regex-operators.md b/docs/standard-library/regex-operators.md index 093cb93bd7d..f062a76a49b 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 512a4b7093c..95fd141c40e 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 d9d1058fe18..4c7f083ccd4 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 290bf331a60..7a11ed48c83 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_lt_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/regular-expressions-cpp.md b/docs/standard-library/regular-expressions-cpp.md index 8b4505025ce..4704305fde6 100644 --- a/docs/standard-library/regular-expressions-cpp.md +++ b/docs/standard-library/regular-expressions-cpp.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Regular Expressions (C++)" title: "Regular Expressions (C++)" +description: "Learn more about: Regular Expressions (C++)" ms.date: 07/15/2021 helpviewer_keywords: ["regular expressions [C++]"] no-loc: [ECMAScript, basic, extended, awk, grep, egrep] @@ -12,7 +12,7 @@ The C++ standard library supports multiple regular expression grammars. This top ## Regular expression grammar -The regular expression grammar to use is by specified by the use of one of the `std::regex_constants::syntax_option_type` enumeration values. These regular expression grammars are defined in `std::regex_constants`: +The regular expression grammar to use is specified by the use of one of the `std::regex_constants::syntax_option_type` enumeration values. These regular expression grammars are defined in `std::regex_constants`: - ECMAScript: This is closest to the grammar used by JavaScript and the .NET languages. - basic: The POSIX basic regular expressions or BRE. @@ -56,7 +56,7 @@ An element can be one of the following: - An *anchor*. Anchor `^` matches the beginning of the target sequence. Anchor `$` matches the end of the target sequence. -A *capture group* of the form (*subexpression*), or \\(*subexpression*\\) in basic and grep, which matches the sequence of characters in the target sequence that is matched by the pattern between the delimiters. +- A *capture group* of the form (*subexpression*), or \\(*subexpression*\\) in basic and grep, which matches the sequence of characters in the target sequence that is matched by the pattern between the delimiters. - An *identity escape* of the form `\k`, which matches the character `k` in the target sequence. @@ -92,7 +92,7 @@ In ECMAScript, an element can also be one of the following: - A *control escape sequence* of the form `\ck`. Matches the control character that is named by the character `k`. -- A *word boundary assert* of the form`\b`. Matches when the current position in the target sequence is immediately after a *word boundary*. +- A *word boundary assert* of the form `\b`. Matches when the current position in the target sequence is immediately after a *word boundary*. - A *negative word boundary assert* of the form `\B`. Matches when the current position in the target sequence isn't immediately after a *word boundary*. diff --git a/docs/standard-library/reverse-view-class.md b/docs/standard-library/reverse-view-class.md new file mode 100644 index 00000000000..e344fe82ba3 --- /dev/null +++ b/docs/standard-library/reverse-view-class.md @@ -0,0 +1,212 @@ +--- +title: reverse_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) reverse_view class, which returns the elements of a range in reverse order." +ms.date: 10/19/2022 +f1_keywords: ["ranges/std::reverse_view", "ranges/std::reverse_view::base", "ranges/std::reverse_view::begin", "ranges/std::reverse_view::empty", "ranges/std::reverse_view::end", "ranges/std::reverse_view::size", "ranges/std::reverse_view::operator bool", "ranges/std::reverse_view::back", "ranges/std::reverse_view::front", "ranges/std::reverse_view::operator[]"] +helpviewer_keywords: ["std::ranges::reverse_view [C++]", "std::ranges::reverse_view::base [C++]", "std::ranges::reverse_view::begin [C++]", "std::ranges::reverse_view::empty [C++]", "std::ranges::reverse_view::end [C++]", "std::ranges::reverse_view::size [C++]", "std::ranges::reverse_view::back [C++]", "std::ranges::reverse_view::front [C++]", "std::ranges::reverse_view::operator[] [C++]", "std::ranges::reverse_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `reverse_view` class (C++ Standard Library) + +A view of the elements of a range in reverse order. + +## Syntax + +```cpp +template +requires ranges::bidirectional_range +class reverse_view : public ranges::view_interface>; +``` + +### Template parameters + +*`V`*\ +The type of the underlying view.\ +This type must satisfy `ranges::bidirectional_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::reverse`](range-adaptors.md#reverse) | +| **Underlying range** | Must satisfy [`bidirectional_range`](range-concepts.md#bidirectional_range) up to [`random_access_range`](range-concepts.md#random_access_range) | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is a [`common_view`](common-view-class.md) and satisfies `const-iterable` | +| **Common range** | Yes | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `reverse_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the `reverse_view`. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `reverse_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `reverse_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `reverse_view` from a bidirectional view. + +```cpp +1) reverse_view() requires default_initializable = default; // default-constructs the underlying view +2) constexpr explicit reverse_view(V rg); // initializes the underlying view via std::move(r) +``` + +### Parameters + +*`rg`*\ +The view to provide a reversed view of. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A view of the underlying range, in reverse order. + +### Remarks + +The best way to create a `reverse_view` is by using the [`views::reverse`](range-adaptors.md#reverse) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) The default constructor default-initializes a `reverse_view`.\ +2\) Create a `reverse_view` from the specified view. + +### Example: `reverse_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto rv = v | std::views::reverse; + + for (auto e : rv) // 6 5 -4 3 2 1 0 + { + std::cout << e << ' '; + } +} +``` + +```output +6 5 -4 3 2 1 0 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `reverse_view`. + +```cpp +1) constexpr reverse_iterator> begin(); +2) constexpr reverse_iterator> begin() requires common_range; +3) constexpr auto begin() const requires common_range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `reverse_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +After the first call to `begin()`, subsequent calls run in constant time, O(1), no matter how many elements are in the `reverse_view`. This has implications because `reverse_view` caches the value of `last` so it can return it repeatedly from `begin`. This means you shouldn't reuse a view after the underlying container is modified. If the underlying range is modified, generate a new view, which is inexpensive. + +2\) The underlying view must satisfy [`common_range`](range-concepts.md#common_range), which means that the underlying view must have the same begin and end iterator type.\ +3\) The underlying view must satisfy `common_range` for a const view to iterate over a `const reverse_view`. + +## `end` + +Get the sentinel at the end of the `reverse_view` + +```cpp +1) constexpr reverse_iterator> end(); +2) constexpr auto end() const requires common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `reverse_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 2, the underlying view must satisfy [`common_range`](range-concepts.md#common_range) for a const view, which means that the underlying view must have the same begin and end iterator type. + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `reverse_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[``](ranges.md)\ +[`reverse` range adaptor](range-adaptors.md#reverse)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/runtime-error-class.md b/docs/standard-library/runtime-error-class.md index e71e28e5ddf..9ae07afd607 100644 --- a/docs/standard-library/runtime-error-class.md +++ b/docs/standard-library/runtime-error-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: runtime_error Class" -title: "runtime_error Class" -ms.date: "09/09/2021" +title: "runtime_error class" +description: "Learn more about: runtime_error class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::runtime_error"] helpviewer_keywords: ["runtime_error class"] -ms.assetid: 4d0227bf-847b-45a2-a320-2351ebf98368 --- -# runtime_error Class +# `runtime_error` class The class serves as the base class for all exceptions thrown to report errors presumably detectable only when the program executes. @@ -18,13 +17,12 @@ public: explicit runtime_error(const string& message); explicit runtime_error(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). ## Example @@ -49,19 +47,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: bad locale name Type: class std::runtime_error -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[exception Class](../standard-library/exception-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`exception` class](exception-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/sample-container-class.md b/docs/standard-library/sample-container-class.md deleted file mode 100644 index a55cb14fa1a..00000000000 --- a/docs/standard-library/sample-container-class.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -description: "Learn more about: Sample Container Class" -title: "Sample Container Class" -ms.date: "11/04/2016" -helpviewer_keywords: ["container classes [C++]"] -ms.assetid: 5b1451f2-c708-45da-bbf0-9e42fd687a1a ---- -# Sample Container Class - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Describes an object that controls a varying-length sequence of elements, typically of type `Ty`. The sequence is stored in different ways, depending on the actual container. - -A container constructor or member function may find occasion to call the constructor **Ty**(**const Ty&**) or the function **Ty::operator=**(**const Ty&**). If such a call throws an exception, the container object is obliged to maintain its integrity, and to rethrow any exception it catches. You can safely swap, assign to, erase, or destroy a container object after it throws one of these exceptions. In general, however, you cannot otherwise predict the state of the sequence controlled by the container object. - -A few additional caveats: - -- If the expression `~Ty` throws an exception, the resulting state of the container object is undefined. - -- If the container stores an allocator object *al*, and *al* throws an exception other than as a result of a call to `al.allocate`, the resulting state of the container object is undefined. - -- If the container stores a function object *comp*, to determine how to order the controlled sequence, and *comp* throws an exception of any kind, the resulting state of the container object is undefined. - -The container classes defined by C++ Standard Library satisfy several additional requirements, as described in the following paragraphs. - -Container class template [list](../standard-library/list-class.md) provides deterministic, and useful, behavior even in the presence of the exceptions described above. For example, if an exception is thrown during the insertion of one or more elements, the container is left unaltered and the exception is rethrown. - -For *all* the container classes defined by C++ Standard Library, if an exception is thrown during calls to the following member functions, `insert`, `push_back`, or `push_front`, the container is left unaltered and the exception is rethrown. - -For *all* the container classes defined by C++ Standard Library, no exception is thrown during calls to the following member functions: `pop_back`, `pop_front`. - -The member function [erase](../standard-library/container-class-erase.md) throws an exception only if a copy operation (assignment or copy construction) throws an exception. - -Moreover, no exception is thrown while copying an iterator returned by a member function. - -The member function [swap](../standard-library/container-class-swap.md) makes additional promises for *all* container classes defined by C++ Standard Library: - -- The member function throws an exception only if the container stores an allocator object al, and `al` throws an exception when copied. - -- References, pointers, and iterators that designate elements of the controlled sequences being swapped remain valid. - -An object of a container class defined by C++ Standard Library allocates and frees storage for the sequence it controls through a stored object of type `Alloc`, which is typically a template parameter. Such an allocator object must have the same external interface as an object of class `allocator`. In particular, `Alloc` must be the same type as `Alloc::rebind::other` - -For *all* container classes defined by C++ Standard Library, the member function `Alloc get_allocator const;` returns a copy of the stored allocator object. Note that the stored allocator object is *not* copied when the container object is assigned. All constructors initialize the value stored in `allocator`, to `Alloc` if the constructor contains no allocator parameter. - -According to the C++ Standard, a container class defined by the C++ Standard Library can assume that: - -- All objects of class `Alloc` compare equal. - -- Type `Alloc::const_pointer` is the same as `const Ty *`. - -- Type `Alloc::const_reference` is the same as `const Ty&`. - -- Type `Alloc::pointer` is the same as `Ty *`. - -- Type `Alloc::reference` is the same as `Ty&`. - -In this implementation, however, containers do not make such simplifying assumptions. Thus, they work properly with allocator objects that are more ambitious: - -- All objects of class `Alloc` does not need to compare equal. (You can maintain multiple pools of storage.) - -- Type `Alloc::const_pointer` does not need to be the same as `const Ty *`. (A const pointer can be a class.) - -- Type `Alloc::pointer` does not need to be the same as `Ty *`. (A pointer can be a class.) - -## Requirements - -**Header**: \ - -## See also - -[\](../standard-library/sample-container.md) diff --git a/docs/standard-library/sample-container-classes.md b/docs/standard-library/sample-container-classes.md deleted file mode 100644 index 4208b28a6f6..00000000000 --- a/docs/standard-library/sample-container-classes.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: "Learn more about: Classes" -title: " Classes" -ms.date: "11/04/2016" -ms.assetid: ac63ed42-5ae5-4008-99fb-89e045bf98af ---- -# `` Classes - -For more information about the classes in \, see [\](../standard-library/sample-container.md). diff --git a/docs/standard-library/sample-container-member-functions.md b/docs/standard-library/sample-container-member-functions.md deleted file mode 100644 index 8385eee0068..00000000000 --- a/docs/standard-library/sample-container-member-functions.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: "Learn more about: Sample Container Member Functions" -title: "Sample Container Member Functions" -ms.date: "11/04/2016" -ms.assetid: fbd88c16-57e6-435d-ad70-7a195c0103ab ---- -# Sample Container Member Functions - -For more information about the member functions in the sample container class, see [Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/sample-container-members.md b/docs/standard-library/sample-container-members.md deleted file mode 100644 index 18b77c70c3a..00000000000 --- a/docs/standard-library/sample-container-members.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -description: "Learn more about: Sample Container Members" -title: "Sample Container Members" -ms.date: "11/04/2016" -helpviewer_keywords: ["container classes"] -ms.assetid: dc5a1998-a31b-4adf-b888-8abe5b87a4e0 ---- -# Sample Container Members - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -## Reference - -## Typedefs - -|Name|Description| -|-|-| -|[const_iterator](../standard-library/container-class-const-iterator.md)|Describes an object that can serve as a constant iterator for the controlled sequence.| -|[const_reference](../standard-library/container-class-const-reference.md)|Describes an object that can serve as a constant reference to an element of the controlled sequence.| -|[const_reverse_iterator](../standard-library/container-class-const-reverse-iterator.md)|Describes an object that can serve as a constant reverse iterator for the controlled sequence.| -|[difference_type](../standard-library/container-class-difference-type.md)|Describes an object that can represent the difference between the addresses of any two elements in the controlled sequence.| -|[iterator](../standard-library/container-class-iterator.md)|Describes an object that can serve as an iterator for the controlled sequence.| -|[reference](../standard-library/container-class-reference.md)|Describes an object that can serve as a reference to an element of the controlled sequence.| -|[reverse_iterator](../standard-library/container-class-reverse-iterator.md)|Describes an object that can serve as a reverse iterator for the controlled sequence.| -|[size_type](../standard-library/container-class-size-type.md)|Describes an object that can represent the length of any controlled sequence.| -|[value_type](../standard-library/container-class-value-type.md)|Acts a synonym for the template parameter `Ty`.| - -## Member Functions - -|Name|Description| -|-|-| -|[begin](../standard-library/container-class-begin.md)|Returns an iterator that points at the first element of the sequence (or just beyond the end of an empty sequence).| -|[clear](../standard-library/container-class-clear.md)|Calls [erase](../standard-library/container-class-erase.md)( [begin](../standard-library/container-class-begin.md), [end](../standard-library/container-class-end.md)).| -|[empty](../standard-library/container-class-empty.md)|Returns **`true`** for an empty controlled sequence.| -|[end](../standard-library/container-class-end.md)|Returns an iterator that points just beyond the end of the sequence.| -|[erase](../standard-library/container-class-erase.md)|Erases an element.| -|[max_size](../standard-library/container-class-max-size.md)|Returns the length of the longest sequence that the object can control, in constant time regardless of the length of the controlled sequence.| -|[rbegin](../standard-library/container-class-rbegin.md)|Returns a reverse iterator that points just beyond the end of the controlled sequence, designating the beginning of the reverse sequence.| -|[rend](../standard-library/container-class-rend.md)|The member function returns a reverse iterator that points at the first element of the sequence (or just beyond the end of an empty sequence), designating the end of the reverse sequence.| -|[size](../standard-library/container-class-size.md)|Returns the length of the controlled sequence, in constant time regardless of the length of the controlled sequence.| -|[swap](../standard-library/container-class-swap.md) diff --git a/docs/standard-library/sample-container-operators.md b/docs/standard-library/sample-container-operators.md deleted file mode 100644 index e5f5f0aa9f4..00000000000 --- a/docs/standard-library/sample-container-operators.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: "Learn more about: Operators" -title: " Operators" -ms.date: "11/04/2016" -ms.assetid: 6cd28cdc-8318-4941-a06c-2c32758383fd ---- -# `` Operators - -For more information about the operators in \, see [\](../standard-library/sample-container.md). diff --git a/docs/standard-library/sample-container-specialized-template-functions.md b/docs/standard-library/sample-container-specialized-template-functions.md deleted file mode 100644 index eda14ad7267..00000000000 --- a/docs/standard-library/sample-container-specialized-template-functions.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: "Learn more about: Specialized Template Functions" -title: " Specialized Template Functions" -ms.date: "11/04/2016" -ms.assetid: 853d4b30-167a-471b-8325-86a868943568 ---- -# `` Specialized Template Functions - -For more information about the specialized template functions in \, see [\](../standard-library/sample-container.md). diff --git a/docs/standard-library/sample-container-typedefs.md b/docs/standard-library/sample-container-typedefs.md deleted file mode 100644 index 8122280f8aa..00000000000 --- a/docs/standard-library/sample-container-typedefs.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -description: "Learn more about: Sample Container Typedefs" -title: "Sample Container Typedefs" -ms.date: "11/04/2016" -ms.assetid: 9fc02c4c-d835-4266-a391-f12b40ba43fa ---- -# Sample Container Typedefs - -For more information about the typedefs in the sample container class, see [Sample Container Class](../standard-library/sample-container-class.md) diff --git a/docs/standard-library/sample-container.md b/docs/standard-library/sample-container.md deleted file mode 100644 index 667dcef38dc..00000000000 --- a/docs/standard-library/sample-container.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -description: "Learn more about: " -title: "" -ms.date: "11/04/2016" -helpviewer_keywords: ["headers, C++ sample container", "sample container", "container headers"] -ms.assetid: 4ab3dcf9-49c3-4e49-b5d6-1ec573e2aee4 ---- -# `` - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Shows you the structure of the container headers in the C++ Standard Library. - -## Syntax - -```cpp -#include // Nonfunctional header -``` diff --git a/docs/standard-library/scl-secure-no-warnings.md b/docs/standard-library/scl-secure-no-warnings.md index fd9ef309d15..3b64ea9b133 100644 --- a/docs/standard-library/scl-secure-no-warnings.md +++ b/docs/standard-library/scl-secure-no-warnings.md @@ -1,14 +1,13 @@ --- -description: "Learn more about: _SCL_SECURE_NO_WARNINGS" title: "_SCL_SECURE_NO_WARNINGS" -ms.date: "11/04/2016" +description: "Learn more about: _SCL_SECURE_NO_WARNINGS" +ms.date: 11/04/2016 f1_keywords: ["_SCL_SECURE_NO_DEPRECATE", "_SCL_SECURE_NO_WARNINGS"] helpviewer_keywords: ["_SCL_SECURE_NO_DEPRECATE", "_SCL_SECURE_NO_WARNINGS"] -ms.assetid: ef0ddea9-7c62-4b53-8b64-5f4fd369776f --- -# _SCL_SECURE_NO_WARNINGS +# `_SCL_SECURE_NO_WARNINGS` -Calling any of the potentially unsafe methods in the C++ Standard Library results in [Compiler Warning (level 3) C4996](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). To disable this warning, define the macro _SCL_SECURE_NO_WARNINGS in your code: +Calling any of the potentially unsafe methods in the C++ Standard Library results in [Compiler Warning (level 3) C4996](../error-messages/compiler-warnings/compiler-warning-level-3-c4996.md). To disable this warning, define the macro `_SCL_SECURE_NO_WARNINGS` in your code: ```cpp #define _SCL_SECURE_NO_WARNINGS @@ -20,26 +19,32 @@ If you use precompiled headers, put this directive in your precompiled header fi Other ways to disable warning C4996 include: -- Using the [/D (Preprocessor Definitions)](../build/reference/d-preprocessor-definitions.md) compiler option: +- Using the [`/D` (Preprocessor Definitions)](../build/reference/d-preprocessor-definitions.md) compiler option: - > cl /D_SCL_SECURE_NO_WARNINGS [other compiler options] myfile.cpp + ```cmd + cl /D_SCL_SECURE_NO_WARNINGS [other compiler options] myfile.cpp + ``` -- Using the [/w](../build/reference/compiler-option-warning-level.md) compiler option: +- Using the [`/w`](../build/reference/compiler-option-warning-level.md) compiler option: - > cl /wd4996 [other compiler options] myfile.cpp + ```cmd + cl /wd4996 [other compiler options] myfile.cpp + ``` -- Using the [#pragma warning](../preprocessor/warning.md) directive: +- Using the [`#pragma warning`](../preprocessor/warning.md) directive: ```cpp #pragma warning(disable:4996) ``` -Also, you can manually change the level of warning C4996 with the **/w\\** compiler option. For example, to set warning C4996 to level 4: +Also, you can manually change the level of warning C4996 with the `/w` compiler option. For example, to set warning C4996 to level 4: -> cl /w44996 [other compiler options] myfile.cpp +```cmd +cl /w44996 myfile.cpp +``` -For more information, see [/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, see [`/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). ## See also -[Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md) +[Safe Libraries: C++ Standard Library](safe-libraries-cpp-standard-library.md) diff --git a/docs/standard-library/scoped-allocator-adaptor-class.md b/docs/standard-library/scoped-allocator-adaptor-class.md index 334806e703f..b2b7ae1f198 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 9798211db1a..9e8b9098d23 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/scoped-lock-class.md b/docs/standard-library/scoped-lock-class.md index 1cb8e0504b8..58e64719100 100644 --- a/docs/standard-library/scoped-lock-class.md +++ b/docs/standard-library/scoped-lock-class.md @@ -1,21 +1,128 @@ --- -description: "Learn more about: scoped_lock Class" title: "scoped_lock Class" -ms.date: "11/04/2016" +description: "Learn more about: scoped_lock Class" +ms.date: 04/10/2026 f1_keywords: ["mutex/std::scoped_lock"] +ai-usage: ai-generated --- # scoped_lock Class +The `scoped_lock` class acquires one or more mutexes on construction and releases them on destruction. When multiple mutexes are provided, a deadlock-avoidance algorithm (equivalent to `std::lock`) is used to prevent deadlocks. Introduced in C++17. + ## Syntax ```cpp + +// Single mutex type version +template +class _NODISCARD_LOCK scoped_lock<_Mutex> { +public: + using mutex_type = _Mutex; + + explicit scoped_lock(_Mutex& _Mtx) : _MyMutex(_Mtx) { // construct and lock + _MyMutex.lock(); + } + + explicit scoped_lock(adopt_lock_t, _Mutex& _Mtx) noexcept + : _MyMutex(_Mtx) {} // construct but don't lock + + ~scoped_lock() noexcept { + _MyMutex.unlock(); + } + + scoped_lock(const scoped_lock&) = delete; // prevent creating a new scoped_lock by copying an existing one + scoped_lock& operator=(const scoped_lock&) = delete; // prevent assigning one scoped_lock to another +}; + +// multiple mutex types version template class scoped_lock { - using mutex_type = Mutex; // If MutexTypes... consists of the single type Mutex explicit scoped_lock(MutexTypes&... m); explicit scoped_lock(MutexTypes&... m, adopt_lock_t); ~scoped_lock(); - scoped_lock(const scoped_lock&) = delete; - scoped_lock& operator=(const scoped_lock&) = delete; + scoped_lock(const scoped_lock&) = delete; // prevent creating a new scoped_lock by copying an existing one + scoped_lock& operator=(const scoped_lock&) = delete; // prevent assigning one scoped_lock to another +}; +``` + +## Remarks + +`adopt_lock_t` is a tag type that indicates the `scoped_lock` constructor should assume ownership of mutexes that are already locked by the calling thread. This allows you to create a `scoped_lock` object without locking the mutexes again, which can be useful in certain scenarios where you have already acquired the locks and want to manage their lifetime with a `scoped_lock`. + +The `scoped_lock` class manages locking and unlocking of one or more mutexes throughout a scope. When you create a `scoped_lock` object, it acquires ownership of the mutexes passed to it. When the `scoped_lock` object is destroyed (for example, when it goes out of scope), the mutexes are released. This ensures that mutexes are always properly released, even if an exception is thrown. + +If you need to lock only a single mutex, consider using [`lock_guard`](lock-guard-class.md) or [`unique_lock`](unique-lock-class.md). Use `scoped_lock` when you need to lock multiple mutexes simultaneously without risk of deadlock. + +The `scoped_lock` class isn't copyable. + +If only one mutex type is passed to `scoped_lock`, the `scoped_lock` provides a type alias named `mutex_type` that refers to that one mutex type. However, if you create a `scoped_lock` with two or more mutex types, the `mutex_type` alias does not exist because `mutex_type` only makes sense when there is a single underlying mutex type. With multiple mutexes, there isn’t one mutex type to expose. + +### Constructors + +| Constructor | Description | +|---|---| +| `scoped_lock(MutexTypes&... m)` | Constructs a `scoped_lock` object and locks all the supplied mutexes. If multiple mutexes are supplied, they're locked using a deadlock-avoidance algorithm. | +| `scoped_lock(MutexTypes&... m, adopt_lock_t)` | Constructs a `scoped_lock` object and adopts ownership of the supplied mutexes, which must already be locked by the calling thread. | + +### Destructor + +| Destructor | Description | +|---|---| +| `~scoped_lock()` | Destroys the `scoped_lock` object and releases all owned mutexes. | + +## Example + +```cpp +#include +#include +#include +#include + +std::mutex mutex1; +std::mutex mutex2; +int shared_data1 = 0; +int shared_data2 = 0; + +void update_both(int iterations) +{ + for (int i = 0; i < iterations; ++i) + { + // Lock both mutexes simultaneously without risk of deadlock + std::scoped_lock lock(mutex1, mutex2); + ++shared_data1; + ++shared_data2; + } +} + +int main() +{ + std::vector threads; + for (int i = 0; i < 4; ++i) + { + threads.emplace_back(update_both, 1000); + } + + for (auto& t : threads) + { + t.join(); + } + + std::cout << "shared_data1: " << shared_data1 << '\n'; + std::cout << "shared_data2: " << shared_data2 << '\n'; + // Output: + // shared_data1: 4000 + // shared_data2: 4000 } ``` + +## Requirements + +**Header:** `` + +**Namespace:** `std` + +## See also + +[`lock_guard` class](lock-guard-class.md)\ +[`unique_lock` class](unique-lock-class.md)\ +[``](mutex.md) diff --git a/docs/standard-library/secure-scl.md b/docs/standard-library/secure-scl.md index 011c9f2ca77..01a0b851630 100644 --- a/docs/standard-library/secure-scl.md +++ b/docs/standard-library/secure-scl.md @@ -1,37 +1,36 @@ --- -description: "Learn more about: _SECURE_SCL" title: "_SECURE_SCL" -ms.date: "11/04/2016" +description: "Learn more about: _SECURE_SCL" +ms.date: 11/04/2016 f1_keywords: ["_SECURE_SCL"] helpviewer_keywords: ["_SECURE_SCL"] -ms.assetid: 4ffbc788-cc12-4c6a-8cd7-490081675086 --- -# _SECURE_SCL +# `_SECURE_SCL` -Superseded by [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md), this macro defines whether [Checked Iterators](../standard-library/checked-iterators.md) are enabled. By default, checked iterators are enabled in Debug builds, and disabled in Retail builds. +Superseded by [`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md), this macro defines whether [Checked Iterators](checked-iterators.md) are enabled. By default, checked iterators are enabled in Debug builds, and disabled in Retail builds. > [!IMPORTANT] -> Direct use of the _SECURE_SCL macro is deprecated. Instead, use _ITERATOR_DEBUG_LEVEL to control checked iterator settings. For more information, see [_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md). +> Direct use of the `_SECURE_SCL` macro is deprecated. Instead, use `_ITERATOR_DEBUG_LEVEL` to control checked iterator settings. For more information, see [`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md). ## Remarks -When checked iterators are enabled, unsafe iterator use causes a runtime error and the program is terminated. To enable checked iterators, set _ITERATOR_DEBUG_LEVEL to 1 or 2. This is equivalent to a _SECURE_SCL setting of 1, or enabled: +When checked iterators are enabled, unsafe iterator use causes a runtime error and the program is terminated. To enable checked iterators, set `_ITERATOR_DEBUG_LEVEL` to 1 or 2. This is equivalent to a `_SECURE_SCL` setting of 1, or enabled: ```cpp #define _ITERATOR_DEBUG_LEVEL 1 ``` -To disable checked iterators, set _ITERATOR_DEBUG_LEVEL to 0. This is equivalent to a _SECURE_SCL setting of 0, or disabled: +To disable checked iterators, set `_ITERATOR_DEBUG_LEVEL` to 0. This is equivalent to a `_SECURE_SCL` setting of 0, or disabled: ```cpp #define _ITERATOR_DEBUG_LEVEL 0 ``` -For information on how to disable warnings about checked iterators, see [_SCL_SECURE_NO_WARNINGS](../standard-library/scl-secure-no-warnings.md). +For information on how to disable warnings about checked iterators, see [`_SCL_SECURE_NO_WARNINGS`](scl-secure-no-warnings.md). ## See also -[_ITERATOR_DEBUG_LEVEL](../standard-library/iterator-debug-level.md)\ -[Checked Iterators](../standard-library/checked-iterators.md)\ -[Debug Iterator Support](../standard-library/debug-iterator-support.md)\ -[Safe Libraries: C++ Standard Library](../standard-library/safe-libraries-cpp-standard-library.md) +[`_ITERATOR_DEBUG_LEVEL`](iterator-debug-level.md)\ +[Checked Iterators](checked-iterators.md)\ +[Debug Iterator Support](debug-iterator-support.md)\ +[Safe Libraries: C++ Standard Library](safe-libraries-cpp-standard-library.md) diff --git a/docs/standard-library/set-class.md b/docs/standard-library/set-class.md index 13b3f067647..3fb4d1f5de9 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,12 +399,12 @@ 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 ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -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 @@ -1081,71 +1080,58 @@ An iterator that refers to the location of an element with a specified key, or t ### Remarks -The member function returns an iterator that refers to an element in the set whose key is equivalent to the argument *key* under a binary predicate that induces an ordering based on a less than comparability relation. +The member function returns an iterator that points to the element in the set that has a key equal to the argument *key*. If no such element exists, the function returns `end()`. The comparison uses a binary predicate based on a less-than ordering relation. -If the return value of `find` is assigned to a `const_iterator`, the set object can't be modified. If the return value of `find` is assigned to an `iterator`, the set object can be modified +If the return value of `find` is assigned to a `const_iterator`, the set object can't be modified. If the return value of `find` is assigned to an `iterator`, the set object can be modified. -### Example +### Example of set::find() ```cpp // compile with: /EHsc /W4 /MTd #include #include -#include -#include - -using namespace std; - -template void print_elem(const T& t) { - cout << "(" << t << ") "; -} -template void print_collection(const T& t) { - cout << t.size() << " elements: "; - - for (const auto& p : t) { - print_elem(p); - } - cout << endl; -} - -template void findit(const C& c, T val) { - cout << "Trying find() on value " << val << endl; - auto result = c.find(val); - if (result != c.end()) { - cout << "Element found: "; print_elem(*result); cout << endl; - } else { - cout << "Element not found." << endl; - } -} +using namespace std; // std c++ libs implemented in std -int main() +void main() { - set s1({ 40, 45 }); - cout << "The starting set s1 is: " << endl; - print_collection(s1); - - vector v; - v.push_back(43); - v.push_back(41); - v.push_back(46); - v.push_back(42); - v.push_back(44); - v.push_back(44); // attempt a duplicate - - cout << "Inserting the following vector data into s1: " << endl; - print_collection(v); - - s1.insert(v.begin(), v.end()); - - cout << "The modified set s1 is: " << endl; - print_collection(s1); - cout << endl; - findit(s1, 45); - findit(s1, 6); + set, allocator> s1{5, 8, 12}; + + // find() returns an iterator that points to the first element + // that has the same key as the value passed to the find function. + // If no such element exists, the iterator equals end(). + + set, allocator>::iterator it; + + // Is 8 in the set? + it = s1.find(8); + if (it != s1.end()) + { + cout << "Found 8" << endl; + } + else + { + cout << "Didn't find 8" << endl; + } + + // Is 6 in the set? + it = s1.find(6); + if (it != s1.end()) + { + cout << "Found 6" << endl; + } + else + { + cout << "Didn't find 6" << endl; + } } ``` +```output +Found 8 +Didn't find 6 +``` + ## `get_allocator` Returns a copy of the allocator object used to construct the set. @@ -1327,7 +1313,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 ccd5724302b..76fb181cf43 100644 --- a/docs/standard-library/set-functions.md +++ b/docs/standard-library/set-functions.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["set/std::swap (map)", "set/std::swap (multiset)"] -ms.assetid: d1277d14-8502-46c0-b820-bcda820f9406 --- # `` functions -## swap (map) +## swap (set) Exchanges the elements of two sets. @@ -63,4 +62,4 @@ in the algorithm class works by assignment and is a slow operation. The speciali ### Example -See the code example for the member class [multiset::swap](../standard-library/multiset-class.md#swap)for an example of the use of the template version of `swap`. +See the code example for the member class [multiset::swap](../standard-library/multiset-class.md#swap) for an example of the use of the template version of `swap`. diff --git a/docs/standard-library/shared-mutex.md b/docs/standard-library/shared-mutex.md index 4506e8bb917..aa70e3c56c8 100644 --- a/docs/standard-library/shared-mutex.md +++ b/docs/standard-library/shared-mutex.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: " title: "" -ms.date: "03/27/2019" +description: "Learn more about: " +ms.date: 03/27/2019 f1_keywords: ["", "shared_mutex/std::swap", "shared_mutex/std::shared_lock", "shared_mutex/std::shared_lock::shared_lock", "shared_mutex/std::shared_lock::operator=", "shared_mutex/std::shared_lock::operator =", "shared_mutex/std::shared_lock::lock", "shared_mutex/std::shared_lock::try_lock", "shared_mutex/std::shared_lock::try_lock_for", "shared_mutex/std::shared_lock::try_lock_until", "shared_mutex/std::shared_lock::unlock", "shared_mutex/std::shared_lock::swap", "shared_mutex/std::shared_lock::release", "shared_mutex/std::shared_lock::owns_lock", "shared_mutex/std::shared_lock::operator bool", "shared_mutex/std::shared_lock::mutex", "shared_mutex/std::shared_mutex", "shared_mutex/std::shared_mutex::native_handle_type", "shared_mutex/std::shared_mutex::shared_mutex", "shared_mutex/std::shared_mutex::operator=", "shared_mutex/std::shared_mutex::operator =", "shared_mutex/std::shared_mutex::lock", "shared_mutex/std::shared_mutex::try_lock", "shared_mutex/std::shared_mutex::unlock", "shared_mutex/std::shared_mutex::lock_shared", "shared_mutex/std::shared_mutex::try_lock_shared", "shared_mutex/std::shared_mutex::unlock_shared", "shared_mutex/std::shared_mutex::native_handle", "shared_mutex/std::shared_timed_mutex", "shared_mutex/std::shared_timed_mutex::shared_timed_mutex", "shared_mutex/std::shared_timed_mutex::operator=", "shared_mutex/std::shared_timed_mutex::operator =", "shared_mutex/std::shared_timed_mutex::lock", "shared_mutex/std::shared_timed_mutex::try_lock", "shared_mutex/std::shared_timed_mutex::try_lock_for", "shared_mutex/std::shared_timed_mutex::try_lock_until", "shared_mutex/std::shared_timed_mutex::unlock", "shared_mutex/std::shared_timed_mutex::lock_shared", "shared_mutex/std::shared_timed_mutex::try_lock_shared", "shared_mutex/std::shared_timed_mutex::try_lock_shared_for", "shared_mutex/std::shared_timed_mutex::try_lock_shared_until", "shared_mutex/std::shared_timed_mutex::unlock_shared"] -ms.assetid: 0b37a97d-ee5d-4050-b29f-09db9f76beb3 --- # `` @@ -28,9 +27,9 @@ namespace std { class shared_mutex; class shared_timed_mutex; template -class shared_lock; + class shared_lock; template -void swap(shared_lock& x, shared_lock& y) noexcept; + void swap(shared_lock& x, shared_lock& y) noexcept; } ``` diff --git a/docs/standard-library/single-view-class.md b/docs/standard-library/single-view-class.md new file mode 100644 index 00000000000..67ed5341e15 --- /dev/null +++ b/docs/standard-library/single-view-class.md @@ -0,0 +1,196 @@ +--- +title: single_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) single_view class, which is a view that has only one element." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::single_view", "ranges/std::single_view::base", "ranges/std::single_view::begin", "ranges/std::single_view::end", "ranges/std::single_view::size", "ranges/std::single_view::empty", "ranges/std::single_view::operator bool", "ranges/std::single_view::data", "ranges/std::single_view::back", "ranges/std::single_view::front", "ranges/std::single_view::operator[]"] +helpviewer_keywords: ["std::ranges::single_view [C++]", "std::ranges::single_view [C++], base", "std::ranges::single_view [C++], begin", "std::ranges::single_view [C++], end", "std::ranges::single_view [C++], size", "std::ranges::single_view [C++], data", "std::ranges::single_view [C++], empty", "std::ranges::single_view [C++], operator bool", "std::ranges::single_view [C++], front", "std::ranges::single_view [C++], back", "std::ranges::single_view [C++], operator[]"] +dev_langs: ["C++"] +--- +# `single_view` class (C++ Standard Library) + +A view that has only one element. This view is useful for test purposes for calling code that needs to be provided with a view with at least one element in it. + +## Syntax + +```cpp +template + requires std::is_object_v +class single_view : public ranges::view_interface> +``` + +### Template parameters + +*`T`*\ +The type of the element. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::single`](range-adaptors.md#single) | +| **Underlying range** | None | +| **Element type** | Specified when the `single_view` is created | +| **View iterator category** | `contiguous_range` | +| **Sized** | Always returns 1 | +| **Is `const`-iterable** | Yes | +| **Common range** | Yes | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `single_view`. | +| [`begin`](#begin) C++20| Get an iterator to the element. | +| [`data`](#data)C++20 | Get a pointer to the element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. Always returns `1`. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty (always returns `false`). | +| [`front`](view-interface.md#front)C++20 | Get the element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position (only position 0 is valid). | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty (always returns `false`). | + +## Remarks + +The best way to create a `single_view` is by using the [`views::single`](range-adaptors.md#single) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +The value in the `single_view` can be modified unless the template value is `const`. For example: `single_view sv{3.14} // this value can't be modified because it's const`. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create an instance of a `single_view`. + +```cpp +1) single_view() = default; +2) constexpr explicit single_view(const T& t); +3) constexpr explicit single_view(T&& t); +4) template + requires constructible_from + constexpr single_view(in_place_t, Args&&... args); +``` + +### Parameters + +*`t`*\ +The element value. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Remarks + +The best way to create a `single_view` is by using the [`views::single`](range-adaptors.md#single) range adaptor. + +1\) Create a `single_view` with a single element of the specified type that is default constructed. For example, `single_view sv{}` creates a `single_view` with a single element of type `float` that is default constructed to `0.0`.\ +2\) Create a `single_view` with a single element of the specified type that is copy-initialized from the specified argument. For example, `single_view sv{myObject}` creates a `single_view` with a single element of type `myObjectType` that is copy-initialized from the argument.\ +3\) Create a `single_view` with a single element of the specified type that is move-initialized from the argument.\ +4\) Create a `single_view` with a single element of the specified type initialized with `(std::forward(args)...)`. + +### Example `single_view` + +```cpp +/// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + std::ranges::single_view sv{7}; + std::cout << sv.front() << " " << *sv.data() << "\n"; // 7 7 + + std::ranges::single_view> sv2{{6502, "8-bit"}}; + std::cout << std::get<0>(sv2[0]) << " " << std::get<1>(sv2[0]) << "\n"; // 6502 8-bit +} +``` + +```output +7 7 +6502 8-bit +``` + +## `begin` + +Get a pointer to the single element in the view. + +```cpp +constexpr T* begin() noexcept; +constexpr const T* begin() const noexcept; +``` + +### Parameters + +None. + +### Return value + +A pointer to the single element inside the `single_view`. + +## `data` + +Get a pointer to the single element in the `single_view`. + +```cpp +constexpr T* data() noexcept; +constexpr const T* data() const noexcept; +``` + +### Parameters + +None. + +### Return value + +A pointer to the element in the `single_view`. + +## `end` + +Gets a pointer to the sentinel after the element. + +```cpp +constexpr T* end() noexcept; +constexpr const T* end() const noexcept; +``` + +### Parameters + +None. + +### Return value + +A pointer to the sentinel that follows the element. + +## `size` + +Get the number of elements in the view. Always returns `1`. + +```cpp +static constexpr size_t size() noexcept; +``` + +### Parameters + +None. + +### Return value + +`1` + +## See also + +[``](ranges.md)\ +[`single` range adaptor](range-adaptors.md#single)\ +[`empty_view`](empty-view-class.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/slice-array-class.md b/docs/standard-library/slice-array-class.md index 6bcfaec534d..f8520ffb2b5 100644 --- a/docs/standard-library/slice-array-class.md +++ b/docs/standard-library/slice-array-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: slice_array class" title: "slice_array class" +description: "Learn more about: slice_array class" ms.date: 01/12/2022 f1_keywords: ["valarray/std::slice_array"] helpviewer_keywords: ["slice_array class"] -ms.assetid: a182d5f7-f35c-4e76-86f2-b5ac64ddc846 --- # `slice_array` class @@ -30,7 +29,7 @@ public: void operator<<=(const valarray& x) const; void operator>>=(const valarray& x) const; // The rest is private or implementation defined -} +}; ``` ## Remarks diff --git a/docs/standard-library/span-class.md b/docs/standard-library/span-class.md index 8661c026d95..8fc221fe457 100644 --- a/docs/standard-library/span-class.md +++ b/docs/standard-library/span-class.md @@ -1,9 +1,8 @@ --- -title: "span class (C++ Standard Library)| Microsoft Docs" +title: "span class (C++ Standard Library)" description: "API reference for the Standard Template Library (STL) span class, which provides a lightweight view over a contiguous sequence of objects." -ms.date: "05/28/2020" -f1_keywords: ["span/std::span", "span/std::span::const_pointer", "span/std::span::const_reference", "span/std::span::difference_type", "span/std::span::element_type", "span/std::span::iterator", "span/std::span::pointer", "span/std::span::reference", "span/std::span::reverse_iterator", "span/std::span::size_type", "span/std::span::value_type", "span/std::span::at", "span/std::span::assign", "span/std::span::back", "span/std::span::begin", "span/std::span::data", "span/std::span::empty", "span/std::span::end", "span/std::span::front", "span/std::span::rbegin", "span/std::span::rend", -"span/std::span::size", "span/std::span::size_bytes", "span/std::span::operator=", "span/std::span::operator[]"] +ms.date: 05/28/2020 +f1_keywords: ["span/std::span", "span/std::span::const_pointer", "span/std::span::const_reference", "span/std::span::difference_type", "span/std::span::element_type", "span/std::span::iterator", "span/std::span::pointer", "span/std::span::reference", "span/std::span::reverse_iterator", "span/std::span::size_type", "span/std::span::value_type", "span/std::span::at", "span/std::span::assign", "span/std::span::back", "span/std::span::begin", "span/std::span::data", "span/std::span::empty", "span/std::span::end", "span/std::span::front", "span/std::span::rbegin", "span/std::span::rend", "span/std::span::size", "span/std::span::size_bytes", "span/std::span::operator=", "span/std::span::operator[]"] helpviewer_keywords: ["std::span [C++]", "std::span [C++], const_pointer", "std::span [C++], const_reference", "std::span [C++], difference_type", "std::span [C++], element_type", "std::span [C++], iterator", "std::span [C++], pointer", "std::span [C++], reference", "std::span [C++], reverse_iterator", "std::span [C++], size_type", "std::span [C++], value_type", "std::span [C++], assign", "std::span [C++], at", "std::span [C++], back", "std::span [C++], begin", "std::span [C++], data", "std::span [C++], empty", "std::span [C++], end", "std::span [C++], front", "std::span [C++], rbegin", "std::span [C++], rend", "std::span [C++], size", "std::span [C++], size_bytes"] dev_langs: ["C++"] --- @@ -78,7 +77,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` @@ -912,7 +911,7 @@ A `span` doesn't free storage for items in the `span` because it doesn't own the |---------|---------| |`span()` | Construct an empty `span`. Only considered during overload resolution when the template parameter `Extent` is `0` or `dynamic_extent`.| |`span(It first, size_type count)` | Construct a `span` from the first `count` elements from iterator `first`. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. | -|`span(It first, End last)` | Construct a `span` from the elements in iterator `first` until the end `last` is reached. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. `It` must be a `contiguous_iterator`. | +|`span(It first, End last)` | Construct a `span` from the elements in iterator `first` until the end `last` is reached. Only considered during overload resolution when template parameter `Extent` isn't `dynamic_extent`. `It` must be a [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator). | |`span(array& arr) noexcept;`

`span(const array& arr) noexcept;`

`span(type_identity_t (&arr)[N]) noexcept;` | Construct a `span` from `N` elements of the specified array. Only considered during overload resolution when template parameter `Extent` is `dynamic_extent` or equals `N`. | |`span(R&& r)` | Construct a `span` from a range. Only participates in overload resolution if template parameter `Extent` isn't `dynamic_extent`.| |`span(const span& other)` | The compiler-generated copy constructor. A shallow copy of the data pointer is safe because the `span` doesn't allocate the memory to hold the elements. | diff --git a/docs/standard-library/span-functions.md b/docs/standard-library/span-functions.md index 456d5c7133e..581e347c753 100644 --- a/docs/standard-library/span-functions.md +++ b/docs/standard-library/span-functions.md @@ -1,7 +1,7 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "05/28/2020" +description: "Learn more about: functions" +ms.date: 05/28/2020 f1_keywords: ["span/std::span::as_bytes", "span/std::as_writable_bytes"] helpviewer_keywords: ["std::span [C++], as_writable_bytes", "std::as_bytes [C++]"] dev_langs: ["C++"] @@ -15,7 +15,7 @@ The `` header includes the following non-member functions that operate on |[`as_bytes`](#as_bytes) | Get a read-only view of the object representation of the elements in the span. | |[`as_writable_bytes`](#as_writable_bytes) | Get a read/write view of the object representation of the elements in the span. | -## `as_bytes` +## `as_bytes` Get a read-only view of the object representation of the elements in the span. @@ -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); @@ -55,7 +55,7 @@ void main() } ``` -## `as_writable_bytes` +## `as_writable_bytes` If `T` isn't **`const`**, gets a read/write view of the raw byte representation of the elements in the span. @@ -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/span.md b/docs/standard-library/span.md index fb36ff38c35..30efd03eaca 100644 --- a/docs/standard-library/span.md +++ b/docs/standard-library/span.md @@ -9,9 +9,9 @@ dev_langs: ["C++"] # `` -A `span` is a view over a contiguous sequence of objects. It provides fast and bounds-safe access. Unlike `vector` or `array`, it doesn't "own" the elements it provides access to. +A `span` is a view over a contiguous sequence of objects. It provides fast and bounds-safe access. Unlike `vector` or `array`, it doesn't "own" the elements. -See [`span` class](span-class.md) for detailed information. Here's an example of how a span can be used: +See [`span` class](span-class.md) for detailed information. Here's an example of how to use a `span`: ```cpp #include @@ -47,7 +47,6 @@ int main() **Compiler option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. - ## Members ### Classes diff --git a/docs/standard-library/split-view-class.md b/docs/standard-library/split-view-class.md new file mode 100644 index 00000000000..70a26bd73e0 --- /dev/null +++ b/docs/standard-library/split-view-class.md @@ -0,0 +1,221 @@ +--- +title: split_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) split_view class. Splits a view into subranges based on a delimiter. The delimiter can be a single element or a view of elements." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::split_view", "ranges/std::split_view::base", "ranges/std::split_view::begin", "ranges/std::split_view::data", "ranges/std::split_view::empty", "ranges/std::split_view::end", "ranges/std::split_view::size", "ranges/std::split_view::operator bool", "ranges/std::split_view::back", "ranges/std::split_view::front", "ranges/std::split_view::operator[]"] +helpviewer_keywords: ["std::ranges::split_view [C++]", "std::ranges::split_view::base [C++]", "std::ranges::split_view::begin [C++]", "std::ranges::split_view::data [C++]", "std::ranges::split_view::empty [C++]", "std::ranges::split_view::size [C++]", "std::ranges::split_view::end [C++]", +"std::ranges::split_view::back [C++]", "std::ranges::split_view::front [C++]", "std::ranges::split_view::operator[] [C++]", "std::ranges::split_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `split_view` class (C++ Standard Library) + +Splits a view into subranges based on a delimiter. The delimiter can be a single element or a view of elements. The delimiter isn't part of the resulting `split_view`. + +A related view is the [`lazy_split_view`](lazy-split-view-class.md) class. The primary differences between `split_view` and `lazy_split_view` are: + +| **View** | **Can split a `const` range**| **range type** | +|--|--| +| `split_view` | no | Supports [`forward_range`](range-concepts.md#forward_range) or higher. | +| `lazy_split_view` | yes | Supports [`input_range`](range-concepts.md#input_range) or higher. | + +Prefer `split_view` because it's more efficient unless you must split a range that is `const`. + +## Syntax + +```cpp +template + requires view && view && + indirectly_comparable, iterator_t, ranges::equal_to> +class split_view : public view_interface>; +``` + +### Template parameters + +*`Pattern`*\ + The type of the view that specifies the delimiter sequence. + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::split`](range-adaptors.md#split) | +| **Underlying range** | Same as underlying range | +| **Element type** | `range_reference_t` | +| **View iterator category** | Satisfies [`forward_range`](range-concepts.md#forward_range) | +| **Sized** | No | +| **Is `const`-iterable** | No | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `split_view` + +```cpp +1) split_view() requires default_initializable && default_initializable = default; +2) constexpr split_view(V base, Pattern pattern); +3) template requires constructible_from> && + constructible_from>> + constexpr split_view(R&& rg, range_value_t e); +``` + +### Parameters + +*`e`*\ +A single element that identifies where to split the view. The element isn't part of the resulting view. + +*`base`*\ +The underlying view. + +*`pattern`*\ +The view of elements that identifies where to split the view. The view of elements isn't part of the resulting view. + +*`rg`*\ +The range to split. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `split_view` instance that contains one or more subranges. + +### Remarks + +The best way to create a `split_view` is by using the [`views::split`](range-adaptors.md#split) range adaptor. Range adaptors are the intended way to create view classes. The view types are only exposed in case you want to create your own custom view type. + +1\) Create a `split_view` that is default constructed. The underlying view and `pattern` are default constructed. `base()` returns a copy of `V()`.\ +2\) Create a `split_view` by splitting the view using a sequence of delimiters.\ +3\) Create a `split_view` by splitting the view using a single delimiter. + +### Example `split_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector rg{ 1, 2, 3, 1, 2, 3, 4, 5, 6 }; + + // pipe syntax using range adaptor + for (const auto& subrange : rg | std::views::split(3)) + { + // outputs + // 1 2 + // 1 2 + // 4 5 6 + for (const auto& elem : subrange) + { + std::cout << elem << ' '; + } + std::cout << '\n'; + } + + int delimiters[] = {2, 3}; + for (auto splitRange : std::views::split(rg, delimiters)) // ctor syntax + { + for (auto& i : splitRange) + { + std::cout << i << " "; // 1 1 4 5 6 + } + } +} +``` + +```output +1 2 +1 2 +4 5 6 +1 1 4 5 6 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const & requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end(); +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## See also + +[``](ranges.md)\ +[`split_view` range adaptor](range-adaptors.md#split)\ +[`lazy_split_view` class](lazy-split-view-class.md)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/sstream-functions.md b/docs/standard-library/sstream-functions.md index 80c3aab1537..4c47dc0b0fd 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 fb824672c7f..0a392e94bb9 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-class.md b/docs/standard-library/stack-class.md index 12a610f22ee..8a30a18989f 100644 --- a/docs/standard-library/stack-class.md +++ b/docs/standard-library/stack-class.md @@ -377,7 +377,7 @@ int main( ) stack s1; s1.push( 1 ); - s1.push( 2 ); + s1.push( 3 ); int& i = s1.top( ); const int& ii = s1.top( ); @@ -385,13 +385,13 @@ int main( ) cout << "The top integer of the stack s1 is " << i << "." << endl; i--; - cout << "The next integer down is "<< ii << "." << endl; + cout << "The updated top integer is " << ii << "." << endl; } ``` ```Output -The top integer of the stack s1 is 2. -The next integer down is 1. +The top integer of the stack s1 is 3. +The updated top integer is 2. ``` ## `value_type` diff --git a/docs/standard-library/stack-operators.md b/docs/standard-library/stack-operators.md index a8b308ae8a7..9722dbc4eac 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/stdexcept.md b/docs/standard-library/stdexcept.md index 6ad13bbc2dd..ac7cf23aeb6 100644 --- a/docs/standard-library/stdexcept.md +++ b/docs/standard-library/stdexcept.md @@ -1,46 +1,40 @@ --- -description: "Learn more about: " title: "" -ms.date: "11/04/2016" +description: "Learn more about: " +ms.date: 11/04/2016 f1_keywords: [""] helpviewer_keywords: ["stdexcept header"] -ms.assetid: 495c10b1-1e60-4514-9f8f-7fda11a2f522 --- # `` -Defines several standard classes used for reporting exceptions. The classes form a derivation hierarchy all derived from class [exception](../standard-library/exception-class.md) and include two general types of exceptions: logical errors and run-time errors. The logical errors are caused programmer mistakes. They derive from the base class logic_error and include: +Defines several standard classes used for reporting exceptions. The classes form a derivation hierarchy all derived from class [`exception`](exception-class.md) and include two general types of exceptions: logical errors and run-time errors. The logical errors are caused by programmer mistakes. They derive from the base class `logic_error` and include: - `domain_error` - - `invalid_argument` - - `length_error` - - `out_of_range` -The run-time errors occur because of mistakes in either the library functions or in the run-time system. They derive from the base class runtime_error and include: +The run-time errors occur because of mistakes in either the library functions or in the run-time system. They derive from the base class `runtime_error` and include: - `overflow_error` - - `range_error` - - `underflow_error` ### Classes |Class|Description| |-|-| -|[domain_error Class](../standard-library/domain-error-class.md)|The class serves as the base class for all exceptions thrown to report a domain error.| -|[invalid_argument Class](../standard-library/invalid-argument-class.md)|The class serves as the base class for all exceptions thrown to report an invalid argument.| -|[length_error Class](../standard-library/length-error-class.md)|The class serves as the base class for all exceptions thrown to report an attempt to generate an object too long to be specified.| -|[logic_error Class](../standard-library/logic-error-class.md)|The class serves as the base class for all exceptions thrown to report errors presumably detectable before the program executes, such as violations of logical preconditions.| -|[out_of_range Class](../standard-library/out-of-range-class.md)|The class serves as the base class for all exceptions thrown to report an argument that is out of its valid range.| -|[overflow_error Class](../standard-library/overflow-error-class.md)|The class serves as the base class for all exceptions thrown to report an arithmetic overflow.| -|[range_error Class](../standard-library/range-error-class.md)|The class serves as the base class for all exceptions thrown to report a range error.| -|[runtime_error Class](../standard-library/runtime-error-class.md)|The class serves as the base class for all exceptions thrown to report errors presumably detectable only when the program executes.| -|[underflow_error Class](../standard-library/underflow-error-class.md)|The class serves as the base class for all exceptions thrown to report an arithmetic underflow.| +|[`domain_error` class](domain-error-class.md)|The class serves as the base class for all exceptions thrown to report a domain error.| +|[`invalid_argument` class](invalid-argument-class.md)|The class serves as the base class for all exceptions thrown to report an invalid argument.| +|[`length_error` class](length-error-class.md)|The class serves as the base class for all exceptions thrown to report an attempt to generate an object too long to be specified.| +|[`logic_error` class](logic-error-class.md)|The class serves as the base class for all exceptions thrown to report errors presumably detectable before the program executes, such as violations of logical preconditions.| +|[`out_of_range` class](out-of-range-class.md)|The class serves as the base class for all exceptions thrown to report an argument that is out of its valid range.| +|[`overflow_error` class](overflow-error-class.md)|The class serves as the base class for all exceptions thrown to report an arithmetic overflow.| +|[`range_error` class](range-error-class.md)|The class serves as the base class for all exceptions thrown to report a range error.| +|[`runtime_error` class](runtime-error-class.md)|The class serves as the base class for all exceptions thrown to report errors presumably detectable only when the program executes.| +|[`underflow_error` class](underflow-error-class.md)|The class serves as the base class for all exceptions thrown to report an arithmetic underflow.| ## See also -[Header Files Reference](../standard-library/cpp-standard-library-header-files.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[Header Files Reference](cpp-standard-library-header-files.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/steady-clock-struct.md b/docs/standard-library/steady-clock-struct.md index bcb5ea47f5f..27c5ae83a47 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 e682064b545..be656d73146 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. @@ -164,5 +163,4 @@ In C++14 and later, you can compare dissimilar containers and/or dissimilar elem ## See also [Parallel Containers](../parallel/concrt/parallel-containers-and-objects.md)\ -[``](../standard-library/sample-container.md)\ [Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/streambuf-typedefs.md b/docs/standard-library/streambuf-typedefs.md index 842403c4f07..ab98660169a 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 ec9262a46fa..e1f57695e84 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 @@ -162,7 +149,7 @@ The **`double`** value. ### Remarks -The function converts the sequence of elements in *`str`* to a value of type **`double`** as if by calling `strtod( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *`str`* to a value of type **`double`** as if by calling `strtod( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. ## `stof` @@ -192,7 +179,7 @@ The **`float`** value. ### Remarks -The function converts the sequence of elements in *`str`* to a value of type **`float`** as if by calling `strtof( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *`str`* to a value of type **`float`** as if by calling `strtof( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. ## `stoi` @@ -266,7 +253,7 @@ The long-integer value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`long`** as if by calling `strtol( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`long`** as if by calling `strtol( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. ## `stold` @@ -296,7 +283,7 @@ The **`long double`** value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`long double`** as if by calling `strtold( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`long double`** as if by calling `strtold( str.c_str(), _Eptr)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. ## `stoll` @@ -331,7 +318,7 @@ The **`long long`** value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`long long`** as if by calling `strtoll( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`long long`** as if by calling `strtoll( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. ## `stoul` @@ -366,7 +353,7 @@ The unsigned long-integer value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`unsigned long`** as if by calling `strtoul( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`unsigned long`** as if by calling `strtoul( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *idx* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. ## `stoull` @@ -401,7 +388,7 @@ The **`unsigned long long`** value. ### Remarks -The function converts the sequence of elements in *str* to a value of type **`unsigned long long`** as if by calling `strtoull( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. +The function converts the sequence of elements in *str* to a value of type **`unsigned long long`** as if by calling `strtoull( str.c_str(), _Eptr, idx)`, where `_Eptr` is an object internal to the function. If `str.c_str() == *_Eptr`, it throws an object of type `invalid_argument`. If such a call would set `errno`, it throws an object of type `out_of_range`. Otherwise, if *`idx`* isn't a null pointer, the function stores `*_Eptr - str.c_str()` in `*idx` and returns the value. ## `swap` diff --git a/docs/standard-library/string-operators.md b/docs/standard-library/string-operators.md index 337f916ab36..692a728f2da 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 8f4f7bfa125..23ba6e7b509 100644 --- a/docs/standard-library/string-typedefs.md +++ b/docs/standard-library/string-typedefs.md @@ -1,16 +1,12 @@ --- -description: "Learn more about: typedefs" title: " typedefs" -ms.date: "11/04/2016" +description: "Learn more about: typedefs" +ms.date: 11/04/2016 f1_keywords: ["string/std::string", "string/std::u16string", "string/std::u32string", "string/std::wstring"] -ms.assetid: fdca01e9-f2f1-4b59-abda-0093d760b3cc --- # `` typedefs -[`string`](#string)\ -[`u16string`](#u16string)\ -[`u32string`](#u32string)\ -[`wstring`](#wstring) +The `` header provides the following typedefs: ## `string` diff --git a/docs/standard-library/string-view-operators.md b/docs/standard-library/string-view-operators.md index ee8386d9e7b..1f3f4c44dec 100644 --- a/docs/standard-library/string-view-operators.md +++ b/docs/standard-library/string-view-operators.md @@ -1,7 +1,7 @@ --- title: " operators" -description: "API reference for the `string_view` operators, which are used to compare two `string_view` objects, or a `string_view` and some other string object" -ms.date: "01/15/2021" +description: "API reference for the `string_view` operators, which are used to compare two `string_view` objects, or a `string_view` and some other string object" +ms.date: 01/15/2021 f1_keywords: ["xstring/basic_string_view::operator!=", "xstring/basic_string_view::operator>", "xstring/basic_string_view::operator>=", "xstring/basic_string_view::operator<", "xstring/basic_string_view::operator<<", "xstring/basic_string_view::operator<=", "xstring/basic_string_view::operator+", "xstring/basic_string_view::operator==", 'xstring/std::literals::string_view_literals::operator "sv', 'std::literals::string_view_literals::operator sv', 'std::literals::string_view_literals', 'string_view_literals'] helpviewer_keywords: ["std::basic_string_view::operator!=", "std::basic_string_view::operator>", "std::basic_string_view::operator>=", "std::basic_string_view::operator<", "std::basic_string_view::operator<<", "std::basic_string_view::operator<=, std::basic_string_view::operator=="] --- @@ -9,15 +9,6 @@ helpviewer_keywords: ["std::basic_string_view::operator!=", "std::basic_string_v Use these operators to compare two `string_view` objects, or a `string_view` and some other string object (for example [`std::string`](basic-string-class.md), or `char*`) for which an implicit conversion is provided. -[`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)\ -[`operator""sv`](#op_sv) - ## `operator!=` Tests if the object on the left side of the operator is not equal to the object on the right side. @@ -41,10 +32,10 @@ bool operator!=( ### Parameters -*left*\ +*`left`*\ Any convertible string type or an object of type `basic_string_view` to be compared. -*right*\ +*`right`*\ Any convertible string type or an object of type `basic_string_view` to be compared. ### Return Value @@ -80,10 +71,10 @@ bool operator==( ### Parameters -*left*\ +*`left`*\ Any convertible string type or an object of type `basic_string_view` to be compared. -*right*\ +*`right`*\ Any convertible string type or an object of type `basic_string_view` to be compared. ### Return Value @@ -119,10 +110,10 @@ bool operator<( ### Parameters -*left*\ +*`left`*\ Any convertible string type or an object of type `basic_string_view` to be compared. -*right*\ +*`right`*\ Any convertible string type or an object of type `basic_string_view` to be compared. ### Return Value @@ -131,7 +122,7 @@ Any convertible string type or an object of type `basic_string_view` to be compa ### Remarks -An implicit conversion must exist from *convertible_string_type* to the string_view on the other side. +An implicit conversion must exist from *convertible_string_type* to the `string_view` on the other side. The comparison is based on a pairwise lexicographical comparison of the character sequences. When the first unequal pair of characters is encountered, the result of that comparison is returned. If no unequal characters are found, but one sequence is shorter, the shorter sequence is less than the longer one. In other words, "cat" is less than "cats". @@ -180,10 +171,10 @@ bool operator<=( ### Parameters -*left*\ +*`left`*\ Any convertible string type or an object of type `basic_string_view` to be compared. -*right*\ +*`right`*\ Any convertible string type or an object of type `basic_string_view` to be compared. ### Return Value @@ -210,7 +201,7 @@ inline basic_ostream& operator<<( an output stream being written to. *`Str`*\ -The string_view to be entered into an output stream. +The `string_view` to be entered into an output stream. ### Return Value @@ -243,10 +234,10 @@ bool operator>( ### Parameters -*left*\ +*`left`*\ Any convertible string type or an object of type `basic_string_view` to be compared. -*right*\ +*`right`*\ Any convertible string type or an object of type `basic_string_view` to be compared. ### Return Value @@ -301,7 +292,6 @@ Constructs a `string_view` from a string literal. Requires namespace `std::liter ### Example ```cpp - using namespace std; using namespace literals::string_view_literals; diff --git a/docs/standard-library/string-view-typedefs.md b/docs/standard-library/string-view-typedefs.md index 618b7ffee3a..083d68db246 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 48ef23cc2a2..846721c1956 100644 --- a/docs/standard-library/string-view.md +++ b/docs/standard-library/string-view.md @@ -1,12 +1,12 @@ --- title: "" description: "Overview of `basic_string_view`, which refers to a constant contiguous sequence of char-like objects." -ms.date: "9/4/2020" +ms.date: 9/4/2020 helpviewer_keywords: ["string_view header"] --- # `` -Defines the class template `basic_string_view` and related types and operators. (Requires compiler option [`std:c++17`](../build/reference/std-specify-language-standard-version.md) or later.) +Defines the class template `basic_string_view` and related types and operators. (Requires compiler option [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later.) ## Syntax @@ -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.| @@ -60,7 +60,7 @@ The `` operators can compare `string_view` objects to objects of an - **Namespace:** `std` -- **Compiler Option:** [`std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. +- **Compiler Option:** [`/std:c++17`](../build/reference/std-specify-language-standard-version.md) or later. ## See also diff --git a/docs/standard-library/strstream-class.md b/docs/standard-library/strstream-class.md index 3efda849d7e..0a4c9c3d6be 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 new file mode 100644 index 00000000000..98576c1de55 --- /dev/null +++ b/docs/standard-library/subrange-class.md @@ -0,0 +1,542 @@ +--- +title: "subrange class (C++ Standard Library)" +description: "API reference for the Standard Template Library (STL) subrange class, which is a view of the elements of a range as defined by a begin iterator and a sentinel." +ms.date: 10/05/2022 +f1_keywords: ["ranges/std::subrange", "ranges/std::subrange::begin", "ranges/std::subrange::data", "ranges/std::subrange::empty", "ranges/std::subrange::end", "ranges/std::subrange::get", "ranges/std::subrange::size", "ranges/std::subrange::operator bool", "ranges/std::subrange::operator PairLike", "ranges/std::subrange::back", "ranges/std::subrange::front", "ranges/std::subrange::operator[]", "ranges/std::subrange::advance", "ranges/std::subrange::prev", "ranges/std::subrange::next"] +helpviewer_keywords: ["std::ranges::subrange [C++]", "std::ranges::subrange::begin [C++]", "std::ranges::subrange::data [C++]", "std::ranges::subrange::empty [C++]", "std::ranges::subrange::end [C++]", "std::ranges::subrange::size [C++]", "std::ranges::subrange::back [C++]", "std::ranges::subrange::front [C++]", "std::ranges::subrange::advance [C++]", "std::ranges::subrange::prev [C++]", "std::ranges::subrange::next [C++]", "std::ranges::subrange::get [C++]", "std::ranges::subrange::operator[] [C++]", "std::ranges::subrange::operator bool [C++]", "std::ranges::subrange::operator PairLike [C++]"] +dev_langs: ["C++"] +--- +# `subrange` class (C++ Standard Library) + +Provides a view of part of the elements of a range as defined by a begin iterator and sentinel. + +## Syntax + +```cpp +template S, subrange_kind K> + requires (K == subrange_kind::sized || !sized_sentinel_for) +class subrange : public view_interface> +``` + +### Template parameters + +*`I`*\ + The begin iterator type. The [`input_or_output_iterator`](iterator-concepts.md#input_or_output_iterator) concept ensures that *`I`* is an iterator that can read all of the elements. + +*`K`*\ +The kind of subrange: Use `subrange_kind::sized` to specify a sized subrange. Use `sized_sentinel_for` if the iterator and sentinel can be subtracted to yield the size. The requirement `subrange_kind::sized || !sized_sentinel_for` stores the size locally in the subrange object, and requires that you construct the subrange either using the constructor that takes a [`sized_range`](range-concepts.md#sized_range) (for which you would specify `subrange_kind::sized` here) or via the constructor that takes an `iterator`, `sentinel`, and `size` (so you would specify `sized_sentinel_for` here). + +*`S`*\ + The end iterator type. The [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for) concept ensures that *`S`* can be used as a sentinel for *`I`* and that it's possible to compute the distance between the sentinel and the current iterator position in *`I`* in constant time. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::counted`](range-adaptors.md#counted) | +| **Underlying range** | Any range | +| **Element type** | `iter_reference_t` | +| **View iterator category** | Same as *`I`s* category | +| **Sized** | If *`K`* is `subrange::sized` | +| **Is `const`-iterable** | If *`I`* is copyable | +| **Common range** | If *`I`* and *`S`* are the same type. | +| **Borrowed range** | Yes | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `subrange`. | +| [`operator PairLike`](#op_pairlike)C++20 | Convert a `subrange` to a pair-like type. | +| [`advance`](#advance)C++20 | Move the iterator a specified distance. | +| [`begin`](#begin) | Get an iterator to the first element. | +| [`empty`](#empty)C++20 | Test whether the `subrange` is empty. | +| [`end`](#end)C++20 | Get the sentinel at the end of the `subrange`. | +| [`next`](#next)C++20 | Creates a copy of this `subrange` but with the stored iterator moved forward the specified distance. | +| [`prev`](#prev)C++20 | Creates a copy of this `subrange` but with the stored iterator moved back the specified distance. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `subrange` is empty. | + +## Remarks + +A `subrange` is useful when you have a begin and end iterator, but you want to pass a single object instead. For example, if you wanted to call a range adaptor but had begin and end iterators, you could use a `subrange` to wrap them and pass the `subrange` to the range adaptor. + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Create a `subrange`. + +```cpp +1) subrange() requires default_initializable = default; +2) template It> + constexpr subrange(It begin, S end) requires (!Store_size); +3) template It> + constexpr subrange(It begin, S end, const Size_type size) requires (K == subrange_kind::sized); +4) template rg> + requires borrowed_range + && Convertible_to_non_slicing, I> + && convertible_to, S> + constexpr subrange(rg&& r) requires (!_Store_size || sized_range); +5) template + requires Convertible_to_non_slicing, I> && convertible_to, S> + constexpr subrange(rg&& r, const _Size_type sizeHint) requires (K == subrange_kind::sized) +``` + +### Parameters + +*`begin`*\ +Iterator that points to the first element in the subrange. + +*`end`*\ +Sentinel that points to the end of the subrange. The element it points to isn't included in the subrange. + +*`sizeHint`*\ +The size of the range in elements. This is used to optimize the `size` member function and is necessary if you want to make a sized `subrange` from an iterator and sentinel whose types don't model [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for). + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `subrange` instance. + +### Remarks + +1\) Default constructs the stored iterator and sentinel. The size hint is set to 0.\ +2\) Uses `std::move()` to move the `begin` iterator and `end` sentinel to the stored iterator and sentinel.\ +3\) Initializes the stored iterator with `std::move(begin)`, the stored sentinel with `std::move(end)`, and the stored size hint with `size`, which should equal the distance between the first and second arguments.\ +4\) Construct a `subrange` from a range.\ +5\) The behavior isn't defined if `szHint != ranges::distance(rg)`. + +The [`counted`](range-adaptors.md#counted) range adaptor can create a `subrange`. That adaptor takes a begin iterator and a count. + +### Example: `counted` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto pos5 = std::ranges::find(v, 5); + auto countedView = std::views::counted(pos5, 5); + for (auto e : countedView) // outputs 5 6 7 8 9 + { + std::cout << e << ' '; + } + std::cout << '\n'; + + // You can pass the range directly if it supports input_or_output_iterator, in which case, the + // count starts from the first element + const char chars[] = { 'H','i',' ','t','h','e','r','e' }; + for (char c : std::views::counted(chars, 2)) + { + std::cout << c; // outputs Hi + } +} +``` + +```output +5 6 7 8 9 +Hi +``` + +## `operator PairLike` + +Convert a `subrange` to a type that models `pair-like`. + +```cpp +template PairLike> +requires pair-like-convertible-from +constexpr operator PairLike() const; +``` + +### Parameters + +None. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `PairLike` value that is direct-initialized with the stored iterator and sentinel. +The last value in the pair will be the sentinel. + +Remember that the sentinel is *past* the last element in the subrange, as shown in the example below. + +### Remarks + +This conversion is useful with older `Boost::Ranges` code that accepts (first, last) pairs to denote a range.\ +This conversion is useful for converting a subrange to a `pair` or `tuple` or other type that models `pair_like`. Some examples of `pair_like` types are: + +```cpp +std::array +std::pair +std::ranges::subrange +std::tuple +``` + +### Example: `operator PairLike()` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +int main() +{ + constexpr int a[] = {0, 1, 2, 3, 4, 5}; + std::ranges::subrange rg(a); + rg.advance(2); + const std::pair p = rg; + for (auto e : rg) + { + std::cout << e << ' '; + } + + // because the sentinel points after the last element, subtract one to get the last element + std::cout << '\n' << *p.first << ':' << *(p.second - 1) << '\n'; // outputs 2:5 + } +``` + +```output +2 3 4 5 +2:5 +``` + +## `advance` + +Adjust the iterator for this `subrange` by *`n`* elements. + +```cpp +constexpr subrange& advance(const iter_difference_t n); +``` + +### Parameters + +*`n`*\ +How many elements to adjust the iterator. *`n`* can be positive (move forward) or, if *`I`* is bidirectional, negative (move backward). + +### Remarks + +This function modifies the current state of the iterator in the `subrange`. + +If you advance past the end of the `subrange`, the iterator is set to the sentinel at the end of the `subrange`.\ +If you advance past the beginning of the `subrange` (using a negative `n`), you'll get an invalid parameter exception if the range you made the `subrange` from doesn't have an element in the place. + +### Example `advance` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +void print(const std::string &msg, auto &&v) +{ + std::cout << msg << '\n'; + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; + print("Original vector: ", v); // outputs 0 1 2 3 4 5 6 7 8 9 10 + + // create a subrange 3 4 5 6 + std::ranges::subrange theSubrange{ std::ranges::find(v,3), std::ranges::find(v, 7) }; + print("The subrange: ", theSubrange); // outputs 3 4 5 6 + + auto sr = theSubrange.advance(2); // get a subrange 2 positions to the right of the current iterator location + print("theSubrange.advance(2): ", sr); // outputs 5 6 + print("Note that subrange's iterator moved during advance(): ", sr); // outputs 5 6 + sr = theSubrange.advance(-3); // Moving before the subrange, but onto a valid element in the original range + print("theSubrange.advance(-3): ", sr); // outputs 2 3 4 5 6 +} +``` + +```output +Original vector: +0 1 2 3 4 5 6 7 8 9 10 +The subrange: +3 4 5 6 +theSubrange.advance(2): +5 6 +Note that subrange's iterator moved during advance(): +5 6 +theSubrange.advance(-3): +2 3 4 5 6 +``` + +## `begin` + +Get an iterator to the first element in the `subrange`. + +```cpp +1) constexpr I begin() const requires copyable; +2) [[nodiscard]] constexpr I begin() requires (!std::copyable); +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `subrange`. +If the iterator isn't copyable, it's returned with `std::move()`. If the iterator is moved, the state of the stored iterator depends on the implementation of the move constructor for *`I`*. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `empty` + +Test whether the `subrange` is empty. + +```cpp +constexpr bool empty() const; +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the `subrange` has no elements. Otherwise, returns `false`. + +## `end` + +Get the sentinel at the end of the `subrange` + +```cpp +[[nodiscard]] constexpr S end() const; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `subrange`: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +The sentinel is copy-constructed from the stored sentinel. + +## `next` + +Creates a copy of this `subrange` but with the stored iterator moved forward the specified distance. + +```cpp +1) [[nodiscard]] constexpr subrange next(iter_difference_t n = 1) const & requires forward_iterator; +2) [[nodiscard]] constexpr subrange next(iter_difference_t n = 1) &&; +``` + +### Parameters + +*`n`*\ +How many elements to move the iterator forward. Defaults to 1. Must be positive. + +### Return value + +Returns a copy of the `subrange` starting at the *`n`*th element. + +### Remarks + +Unlike `advance()`, `next()` doesn't change the location of the iterator stored in the original `subrange`. +The returned `subrange` has all the elements that the original subrange has, but the iterator is in a different location. + +1\) The return value is the same as: + +```cpp +auto tmp = *this; +tmp.advance(n); +return tmp; +``` + +2\) The return value is the same as: + +```cpp +advance(n); +return std::move(*this); +``` + +### Example: `next` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +void print(const std::string &msg, auto &&v) +{ + std::cout << msg << '\n'; + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v = { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 }; + print("Original vector:", v); // 0 1 2 3 4 5 6 7 8 9 10 + + // create a subrange from the front of v up to (but not including) the element 7 + std::ranges::subrange theSubrange{ std::ranges::find(v,1), std::ranges::find(v, 7) }; + print("The subrange:", theSubrange); // 1 2 3 4 5 6 + + auto forward = theSubrange.advance(3); // get a subrange 3 positions to the right of the current iterator location + print("theSubrange.advance(3):", forward); // 4 5 6 + + // prev() + auto previous = theSubrange.prev(2); // move back 2 + print("theSubrange.prev(2):", previous); // 2 3 4 5 6 + print("Note that the subrange's iterator did *not* move during prev():", theSubrange); // 4 5 6 +} +``` + +```output +Original vector: +0 1 2 3 4 5 6 7 8 9 10 +The subrange: +1 2 3 4 5 6 +theSubrange.next(3): +4 5 6 +Note that the original subrange's iterator did *not* move during next(): +1 2 3 4 5 6 +``` + +## `prev` + +Creates a copy of this `subrange`, but with the stored iterator moved back the specified distance. + +```cpp +[[nodiscard]] constexpr subrange prev(std::iter_difference_t n = 1 ) const + requires std::bidirectional_iterator; +``` + +### Parameters + +*`n`*\ +How many elements to move the iterator back. Defaults to 1. Must be positive. + +### Return value + +Returns a copy of the `subrange` but with the iterator moved back *`n`* elements. + +### Remarks + +Unlike `advance()`, `prev()` doesn't change the location of the iterator stored in the original `subrange`.\ +The returned `subrange` has all the elements that the original subrange has, but the iterator is just in a different location. You can think of the return value as: + +```cpp +auto tmp = *this; +tmp.advance(-n); +return tmp; +``` + +### Example `prev` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +void print(const std::string &msg, auto &&v) +{ + std::cout << msg << '\n'; + for (auto& x : v) + { + std::cout << x << ' '; + } + std::cout << '\n'; +} + +int main() +{ + std::vector v = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + print("Original vector:", v); // 0 1 2 3 4 5 6 7 8 9 10 + + // create a subrange from the front of v up to (but not including) the element 7 + std::ranges::subrange theSubrange{std::ranges::find(v,1), std::ranges::find(v, 7)}; + print("The subrange: ", theSubrange); // 1 2 3 4 5 6 + + auto forward = theSubrange.advance(3); // get a subrange 3 positions to the right of the current iterator location + print("theSubrange.advance(3):", forward); // 4 5 6 + + // prev() + auto previous = theSubrange.prev(2); // move back 2 + print("theSubrange.prev(2):", previous); // 2 3 4 5 6 + print("Note that the subrange's iterator did *not* move during prev():", theSubrange); // 4 5 6 +} +``` + +```output +Original vector: +0 1 2 3 4 5 6 7 8 9 10 +The subrange: +1 2 3 4 5 6 +theSubrange.advance(3): +4 5 6 +theSubrange.prev(2): +2 3 4 5 6 +Note that the subrange's iterator did *not* move during prev(): +4 5 6 +``` + +## `size` + +Get the number of elements in the `subrange`. + +```cpp +constexpr size() const + requires (K == ranges::subrange_kind::sized); +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `subrange`. + +If the size isn't stored, which is the case when the `subrange` is created with `K == ranges::subrange_kind::sized` specified and `std::sized_sentinel_for` isn't satisfied, then the size is returned as the distance between the begin and end iterators. + +Changing the position of the `begin` iterator, with `advance`, for example, changes the reported size. + +## See also + +[``](ranges.md)\ +[`counted`](range-adaptors.md#counted)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/subtract-with-carry-engine-class.md b/docs/standard-library/subtract-with-carry-engine-class.md index 4e2f83f4eb5..4fdbbc41490 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/swap-sample-container.md b/docs/standard-library/swap-sample-container.md deleted file mode 100644 index b90bffdd488..00000000000 --- a/docs/standard-library/swap-sample-container.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: "Learn more about: swap ()" -title: "swap ()" -ms.date: "11/04/2016" -f1_keywords: ["std.swap", "std::swap", "swap"] -helpviewer_keywords: ["swap function"] -ms.assetid: d8dd6436-fb97-46ed-bec5-052cfd710462 ---- -# `swap` (``) - -> [!NOTE] -> This topic is in the Microsoft C++ documentation as a nonfunctional example of containers used in the C++ Standard Library. For more information, see [C++ Standard Library Containers](../standard-library/stl-containers.md). - -Executes `left.`[swap](../standard-library/container-class-swap.md)`(right)`. - -## Syntax - -```cpp -template -void swap( - Container & left, - Container & right); -``` - -## See also - -[\](../standard-library/sample-container.md) diff --git a/docs/standard-library/sync-none-class.md b/docs/standard-library/sync-none-class.md index 1966997f4a5..df55c41667b 100644 --- a/docs/standard-library/sync-none-class.md +++ b/docs/standard-library/sync-none-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: sync_none Class" title: "sync_none Class" -ms.date: "11/04/2016" +description: "Learn more about: sync_none Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::sync_none", "allocators/stdext::sync_none::allocate", "allocators/stdext::sync_none::deallocate", "allocators/stdext::sync_none::equals"] helpviewer_keywords: ["stdext::sync_none", "stdext::sync_none [C++], allocate", "stdext::sync_none [C++], deallocate", "stdext::sync_none [C++], equals"] -ms.assetid: f7473cee-14f3-4fe1-88bc-68cd085e59e1 --- # sync_none Class @@ -93,8 +92,6 @@ The cache object to compare for equality. The member function always returns **`true`**. -### Remarks - ## See also [\](../standard-library/allocators-header.md) diff --git a/docs/standard-library/sync-per-container-class.md b/docs/standard-library/sync-per-container-class.md index 796756f4288..2a164a0a0b1 100644 --- a/docs/standard-library/sync-per-container-class.md +++ b/docs/standard-library/sync-per-container-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: sync_per_container Class" title: "sync_per_container Class" -ms.date: "11/04/2016" +description: "Learn more about: sync_per_container Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::sync_per_container", "allocators/stdext::sync_per_container::equals"] helpviewer_keywords: ["sync_per_container class"] -ms.assetid: 0b4b2904-b668-4d94-a422-d4f919cbffab --- # sync_per_container Class @@ -55,8 +54,6 @@ The cache object to compare for equality. The member function always returns **`false`**. -### Remarks - ## See also [\](../standard-library/allocators-header.md) diff --git a/docs/standard-library/sync-per-thread-class.md b/docs/standard-library/sync-per-thread-class.md index 6a4b0047247..aa715f4c698 100644 --- a/docs/standard-library/sync-per-thread-class.md +++ b/docs/standard-library/sync-per-thread-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: sync_per_thread Class" title: "sync_per_thread Class" -ms.date: "11/04/2016" +description: "Learn more about: sync_per_thread Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::sync_per_thread", "allocators/stdext::sync_per_thread::allocate", "allocators/stdext::sync_per_thread::deallocate", "allocators/stdext::sync_per_thread::equals"] helpviewer_keywords: ["stdext::sync_per_thread", "stdext::sync_per_thread [C++], allocate", "stdext::sync_per_thread [C++], deallocate", "stdext::sync_per_thread [C++], equals"] -ms.assetid: 47bf75f8-5b02-4760-b1d3-3099d08fe14c --- # sync_per_thread Class @@ -97,8 +96,6 @@ The cache object to compare for equality. **`false`** if no cache object has been allocated for this object or for *Other* in the current thread. Otherwise it returns the result of applying `operator==` to the two cache objects. -### Remarks - ## See also [\](../standard-library/allocators-header.md) diff --git a/docs/standard-library/sync-shared-class.md b/docs/standard-library/sync-shared-class.md index 67ae7354c9e..bd722d3a534 100644 --- a/docs/standard-library/sync-shared-class.md +++ b/docs/standard-library/sync-shared-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: sync_shared Class" title: "sync_shared Class" -ms.date: "11/04/2016" +description: "Learn more about: sync_shared Class" +ms.date: 11/04/2016 f1_keywords: ["allocators/stdext::sync_shared", "allocators/stdext::sync_shared::allocate", "allocators/stdext::sync_shared::deallocate", "allocators/stdext::sync_shared::equals"] helpviewer_keywords: ["stdext::sync_shared", "stdext::sync_shared [C++], allocate", "stdext::sync_shared [C++], deallocate", "stdext::sync_shared [C++], equals"] -ms.assetid: cab3af9e-3d1a-4f2c-8580-0f89e5687d8e --- # sync_shared Class @@ -97,8 +96,6 @@ The cache to compare for equality. **`true`** if the result of `cache.equals(Other.cache)`, where `cache` represents the cache object, is **`true`**; otherwise, **`false`**. -### Remarks - ## See also [\](../standard-library/allocators-header.md) diff --git a/docs/standard-library/sys-info-struct.md b/docs/standard-library/sys-info-struct.md index d0e6df8da0c..761b5e488a3 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-clock-structure.md b/docs/standard-library/system-clock-structure.md index d8bff11b411..e4f4f308681 100644 --- a/docs/standard-library/system-clock-structure.md +++ b/docs/standard-library/system-clock-structure.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: system_clock Structure" title: "system_clock Structure" +description: "Learn more about: system_clock Structure" ms.date: 07/26/2021 f1_keywords: ["chrono/std::chrono::system_clock", "chrono/std::chrono::system_clock::from_time_t", "chrono/std::chrono::system_clock::now", "chrono/std::chrono::system_clock::to_time_t", "chrono/std::chrono::system_clock::is_steady constant"] helpviewer_keywords: ["std::chrono [C++], system_clock"] @@ -66,7 +66,7 @@ A clock is *steady* if it is *monotonic* and if the time between clock ticks is **Namespace:** `std::chrono` -## `from_time_t` +## `from_time_t` Static method that returns a [time_point](../standard-library/time-point-class.md) that most closely approximates the time that is represented by *Tm*. @@ -79,7 +79,7 @@ static time_point from_time_t(time_t Tm) noexcept; *`Tm`*\ A [time_t](../c-runtime-library/standard-types.md) object. -## `is_steady` +## `is_steady` A static value that specifies whether the clock type is *steady*. Because the `system_clock` isn't steady, you can't use this clock to take the time before an event, the time after an event, and reliably subtract them to get the duration of the event because the clock may be adjusted during the timing interval. diff --git a/docs/standard-library/system-error-enums.md b/docs/standard-library/system-error-enums.md index 2551b9345a5..9ad2a056960 100644 --- a/docs/standard-library/system-error-enums.md +++ b/docs/standard-library/system-error-enums.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: enums" title: " enums" -ms.date: "11/04/2016" +description: "Learn more about: enums" +ms.date: 11/04/2016 f1_keywords: ["system_error/std::errc", "system_error/std::io_errc"] -ms.assetid: b21321b7-404a-40de-8777-a85b77c6fa58 --- # `` enums @@ -94,8 +93,6 @@ class errc { }; ``` -### Remarks - ## io_errc Provides symbolic names for the error conditions in \. Can be used to create [error_condition](../standard-library/error-condition-class.md) objects to be compared with the value that's returned by the [ios_base::failure](../standard-library/ios-base-class.md#failure)`code()` function. diff --git a/docs/standard-library/system-error-functions.md b/docs/standard-library/system-error-functions.md index af053fb4cb2..6de6c2d6a28 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 ad43985bc57..58a4e804c31 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/system-error.md b/docs/standard-library/system-error.md index 0d12bfef30e..8a633804bff 100644 --- a/docs/standard-library/system-error.md +++ b/docs/standard-library/system-error.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: " title: "" -ms.date: "03/15/2019" +description: "Learn more about: " +ms.date: 03/15/2019 f1_keywords: [""] helpviewer_keywords: ["system_error header"] -ms.assetid: 5e046c6e-48d9-4740-8c8a-05f3727c1215 --- # `` -Include the header \ to define the exception class `system_error` and related templates for processing low-level system errors. +Include the header `` to define the exception class `system_error` and related templates for processing low-level system errors. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## Members @@ -22,45 +21,45 @@ Include the header \ to define the exception class `system_error` |Name|Description| |-|-| -|[generic_category](../standard-library/system-error-functions.md#generic_category)|Represents the category for generic errors.| -|[is_error_code_enum_v](../standard-library/system-error-functions.md#is_error_code_enum_v)|| -|[is_error_condition_enum_v](../standard-library/system-error-functions.md#is_error_condition_enum_v)|| -|[system_category](../standard-library/system-error-functions.md#system_category)|Represents the category for errors caused by low-level system overflows.| +|[`generic_category`](system-error-functions.md#generic_category)|Represents the category for generic errors.| +|[`is_error_code_enum_v`](system-error-functions.md#is_error_code_enum_v)|A helper variable template for the [`is_error_code_enum`](is-error-code-enum-class.md) value.| +|[`is_error_condition_enum_v`](system-error-functions.md#is_error_condition_enum_v)|A helper variable template for the [`is_error_condition_enum`](is-error-condition-enum-class.md) value.| +|[`system_category`](system-error-functions.md#system_category)|Represents the category for operating system errors.| ### Functions |Name|Description| |-|-| -|[make_error_code](../standard-library/system-error-functions.md#make_error_code)|Creates an `error_code` object.| -|[make_error_condition](../standard-library/system-error-functions.md#make_error_condition)|Creates an `error_condition` object.| +|[`make_error_code`](system-error-functions.md#make_error_code)|Creates an [`error_code`](error-code-class.md) object.| +|[`make_error_condition`](system-error-functions.md#make_error_condition)|Creates an [`error_condition`](error-condition-class.md) object.| ### Operators |Name|Description| |-|-| -|[operator==](../standard-library/system-error-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/system-error-operators.md#op_neq)|Tests if the object on the left side of the operator is not equal to the object on the right side.| -|[operator<](../standard-library/system-error-operators.md#op_lt)|Tests if an object is less than the object passed in for comparison.| -|[operator<<](../standard-library/system-error-operators.md#op_ostream)|| +|[`operator==`](system-error-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!=`](system-error-operators.md#op_neq)|Tests if the object on the left side of the operator is not equal to the object on the right side.| +|[`operator<`](system-error-operators.md#op_lt)|Tests if an object is less than the object passed in for comparison.| +|[`operator<<`](system-error-operators.md#op_ostream)|Inserts an [`error_code`](error-code-class.md) object into the output stream.| ### Enums |Name|Description| |-|-| -|[errc](../standard-library/system-error-enums.md#errc)|Provides symbolic names for all the error-code macros defined by POSIX in ``.| +|[`errc`](system-error-enums.md#errc)|Provides symbolic names for all the error-code macros defined by POSIX in ``.| ### Classes and Structs |Name|Description| |-|-| -|[error_category](../standard-library/error-category-class.md)|Represents the abstract, common base for objects that describes a category of error codes.| -|[error_code](../standard-library/error-code-class.md)|Represents low-level system errors that are implementation-specific.| -|[error_condition](../standard-library/error-condition-class.md)|Represents user-defined error codes.| -|[hash](../standard-library/hash-structure.md#system_error)|| -|[is_error_code_enum](../standard-library/is-error-code-enum-class.md)|Represents a type predicate that tests for the [error_code Class](../standard-library/error-code-class.md) enumeration.| -|[is_error_condition_enum](../standard-library/is-error-condition-enum-class.md)|Represents a type predicate that tests for the [error_condition Class](../standard-library/error-condition-class.md) enumeration.| -|[system_error](../standard-library/system-error-class.md)|Represents the base class for all exceptions thrown to report a low-level system overflow.| +|[`error_category`](error-category-class.md)|Represents the abstract, common base for objects that describes a category of error codes.| +|[`error_code`](error-code-class.md)|Represents low-level system errors that are implementation-specific.| +|[`error_condition`](error-condition-class.md)|Represents user-defined error codes.| +|[`hash`](hash-structure.md#system_error)|Template specializations of [`std::hash`](hash-class.md) for [`error_code`](error-code-class.md) and [`error_condition`](error-condition-class.md).| +|[`is_error_code_enum`](is-error-code-enum-class.md)|Represents a type predicate that tests for the [`error_code`](error-code-class.md) enumeration.| +|[`is_error_condition_enum`](is-error-condition-enum-class.md)|Represents a type predicate that tests for the [`error_condition`](error-condition-class.md) enumeration.| +|[`system_error`](system-error-class.md)|Represents the base class for all exceptions thrown to report a low-level system error.| ## See also -[Header Files Reference](../standard-library/cpp-standard-library-header-files.md) +[Header Files Reference](cpp-standard-library-header-files.md) diff --git a/docs/standard-library/take-view-class.md b/docs/standard-library/take-view-class.md new file mode 100644 index 00000000000..a6902be0876 --- /dev/null +++ b/docs/standard-library/take-view-class.md @@ -0,0 +1,223 @@ +--- +title: take_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) take_view class. It's a view that contains the specified number of elements taken from the front of another view." +ms.date: 10/19/2022 +f1_keywords: ["ranges/std::take_view", "ranges/std::take_view::base", "ranges/std::take_view::begin", "ranges/std::take_view::data", "ranges/std::take_view::empty", "ranges/std::take_view::end", "ranges/std::take_view::size", "ranges/std::take_view::operator bool", "ranges/std::take_view::back", "ranges/std::take_view::front", "ranges/std::take_view::operator[]"] +helpviewer_keywords: ["std::ranges::take_view [C++]", "std::ranges::take_view::base [C++]", "std::ranges::take_view::begin [C++]", "std::ranges::take_view::data [C++]", "std::ranges::take_view::empty [C++]", "std::ranges::take_view::size [C++]", "std::ranges::take_view::end [C++]", +"std::ranges::take_view::back [C++]", "std::ranges::take_view::front [C++]", "std::ranges::take_view::operator[] [C++]", "std::ranges::take_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `take_view` class (C++ Standard Library) + +A view of the first *N* elements from another view. + +## Syntax + +```cpp +template +class take_view : public view_interface>; +``` + +### Template parameters + +*`V`*\ + The type of the underlying range. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::take`](range-adaptors.md#take) | +| **Underlying range** | Any range | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | No | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable | +| **Common range** | Only if the underlying range satisfies [`random_access_range`](range-concepts.md#random_access_range) and [`sized_range`](range-concepts.md#sized_range) | +| **Borrowed range** | Only if the underlying range is [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors) | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `take_view` + +```cpp +1) take_view() requires default_initializable = default; +2) constexpr take_view(V base, range_difference_t count); +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`count`*\ +The number of elements to take from the front of the underlying view. If *`count`* is more than the number of elements in the underlying view, the view will contain all the elements in the underlying range. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +A `take_view`, which is a view of the first *N* elements from another view. If you specify more elements to drop than exist in the underlying range, an `empty_view` is returned. + +### Remarks + +The best way to create a `take_view` is by using the [`views::take`](range-adaptors.md#take) range adaptor. Range adaptors are the intended way to create view classes. The view types are only exposed in case you want to create your own custom view type. + +1\) Create a `take_view` that has no elements. The underlying view is default constructed. `base()` returns a copy of `V()`.\ +2\) Create a `take_view` from a *`base`* and a count. *`base`* is moved via `std::move()`. + +If *`count`* is less than the number of elements in the underlying range, then `count` determines the size of the `take_view`.\ +If *`count`* is greater than the number of elements in the underlying range, then the `take_view` includes all of the elements in the underlying range. + +### Example: `take_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, 4, 5, 6}; + + auto newView = std::views::take(v, 3); + + for (auto& e : newView) + { + std::cout << e << ' '; // 0 1 2 + } + std::cout << '\n'; + + // Use the '|' operator to create a take_view + for (auto i : v | std::views::take(3)) + { + std::cout << i << ' '; // 0 1 2 + } +} +``` + +```output +0 1 2 +0 1 2 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const & requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin() requires (!Simple_view); +constexpr auto begin() const requires range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the `Simple_view` requirement means that the view `V` and `const V` must have the same iterator and sentinel types. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +1) constexpr auto end() requires !(Simple_view); +2) constexpr auto end() const requires range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the `Simple_view` requirement means that the view `V` and `const V` must have the same iterator and sentinel types. + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires sized_range; +constexpr auto size() const requires sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `take_view`.\ +If the `take_view` was constructed with an explicit *`count`*: + +- if *`count`* is less than the number of elements in the underlying range, it's returned as the size of the view. +- if *`count`* is greater than the number of elements in the underlying range, then the size of the view is `ranges::size(base)`. + +## See also + +[``](ranges.md)\ +[`take` range adaptor](range-adaptors.md#take)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/take-while-view-class.md b/docs/standard-library/take-while-view-class.md new file mode 100644 index 00000000000..cfbf93e15b8 --- /dev/null +++ b/docs/standard-library/take-while-view-class.md @@ -0,0 +1,242 @@ +--- +title: take_while_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) take_while_view class, which is a view that contains the leading elements of a range that match a predicate." +ms.date: 08/04/2022 +f1_keywords: ["ranges/std::take_while_view", "ranges/std::take_while_view::base", "ranges/std::take_while_view::begin", "ranges/std::take_while_view::data", "ranges/std::take_while_view::empty", "ranges/std::take_while_view::end", "ranges/std::take_while_view::size", "ranges/std::take_while_view::operator bool", "ranges/std::take_while_view::pred", "ranges/std::take_while_view::back", "ranges/std::take_while_view::front", "ranges/std::take_while_view::operator[]"] +helpviewer_keywords: ["std::ranges::take_while_view [C++]", "std::ranges::take_while_view::base [C++]", "std::ranges::take_while_view::begin [C++]", "std::ranges::take_while_view::data [C++]", "std::ranges::take_while_view::empty [C++]", "std::ranges::take_while_view::size [C++]", "std::ranges::take_while_view::end [C++]", +"std::ranges::take_while_view::pred [C++]", "std::ranges::take_while_view::back [C++]", "std::ranges::take_while_view::front [C++]", "std::ranges::take_while_view::operator[] [C++]", "std::ranges::take_while_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `take_while_view` class (C++ Standard Library) + +A view that contains the leading elements of a range that match a predicate. + +## Syntax + +```cpp +template requires + input_range && is_object_v && + indirect_unary_predicate> +class take_while_view : public view_interface>; +``` + +### Template parameters + +*`Pred`*\ +The type of the predicate that determines the leading elements to put in the view. + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::take_while`](range-adaptors.md#take_while) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the underlying range | +| **View iterator category** | Same as the underlying range | +| **Sized** | No | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable and the predicate can work with `const` references. | +| **Common range** | No | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`pred`](#pred)C++20 | Get a reference to the predicate that determines which elements to take. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`data`](view-interface.md#data)C++20 | Get a pointer to the first element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | +| [`size`](view-interface.md#size) | Get the number of elements in the view. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `take_while_view` + +```cpp +1) take_while_view() requires + default_initializable && + default_initializable = default; + +2) constexpr take_while_view(V base, Pred pred); +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`pred`*\ +The predicate that determines the leading elements to put in the view. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `take_while_view` object. + +### Remarks + +The best way to create a `take_while_view` is by using the [`views::take_while`](range-adaptors.md#take_while) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Move constructs the `take_while_view` from a *`base`* view and a *`pred`* predicate. Both *`base`* and *`pred`* are moved via `std::move()`.\ +2\) Constructs an empty `take_while_view`. The underlying view and predicate are default constructed. + +### Example: `take_while_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + auto twv = std::views::take_while(v, [](int i) {return i >= 0; }); + + for (auto& e : twv) + { + std::cout << e << ' '; // 0 1 2 3 + } + std::cout << '\n'; + + // Using the '|' operator to create a take_view + for (auto i : v | std::views::take_while([](int i) {return i < 5; })) + { + std::cout << i << ' '; // 0 1 2 3 -4 + } +} +``` + +```output +0 1 2 3 +0 1 2 3 -4 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +1) constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +2) constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +A copy of the underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +1) constexpr auto begin() requires (!Simple_view); +2) constexpr auto begin() const requires + range && + indirect_unary_predicate> +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the [`Simple_view`](range-concepts.md#simple_view) requirement means that a view *`V`* and `const V` have the same iterator and sentinel types. + +## `end` + +Get the sentinel at the end of the view. + +```cpp +1) constexpr auto end() requires (!Simple_view); +2) constexpr auto end() const requires + range && + indirect_unary_predicate +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the view. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +### Remarks + +For 1, the [`Simple_view`](range-concepts.md#simple_view) requirement means that a view *`V`* and `const V` have the same iterator and sentinel types. + +## `pred` + +Get a reference to the predicate used to select which leading elements will go in the view. + +```cpp +constexpr const Pred& pred() const; +``` + +### Return value + +A reference to the predicate used to select the leading elements to put in the view. + +### Example `pred` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{ 0, 1, 2, 3, -4, 5, 6 }; + auto mv = v | std::views::take_while( + [](int i) {return i < 5; }); + std::cout << std::boolalpha << mv.pred()(v[6]); // outputs false because v[6] = 6 and 6 is not less than 5 (the predicate) +} +``` + +## See also + +[``](ranges.md)\ +[`take_view`](take-view-class.md)\ +[`take_while` range adaptor](range-adaptors.md#take_while)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/thread-class.md b/docs/standard-library/thread-class.md index 91c7a8bd6f6..e16b853338e 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-functions.md b/docs/standard-library/thread-functions.md index eea1f7215e9..ed86df6516b 100644 --- a/docs/standard-library/thread-functions.md +++ b/docs/standard-library/thread-functions.md @@ -1,65 +1,80 @@ --- -description: "Learn more about: functions" title: " functions" -ms.date: "11/04/2016" +description: "Learn more about: functions" +ms.date: 11/04/2016 f1_keywords: ["thread/std::get_id", "thread/std::sleep_for", "thread/std::sleep_until", "thread/std::swap", "thread/std::yield"] -ms.assetid: bb1aa1ef-fe3f-4e2c-8b6e-e22dbf2f5a19 helpviewer_keywords: ["std::get_id [C++]", "std::sleep_for [C++]", "std::sleep_until [C++]", "std::swap [C++]", "std::yield [C++]"] --- # `` functions -## get_id +The `` header provides the following functions: + +## `get_id` Uniquely identifies the current thread of execution. ```cpp -thread::id this_thread::get_id() noexcept; +thread::id get_id() noexcept; ``` ### Return Value -An object of type [thread::id](../standard-library/thread-class.md) that uniquely identifies the current thread of execution. +An object of type [`thread::id`](thread-class.md#id_class) that uniquely identifies the current thread of execution. + +### Example + +```cpp +#include +#include + +int main() +{ + std::thread::id current_thread_id = std::this_thread::get_id(); + std::cout << "Current thread id: " << current_thread_id; +} +``` -## sleep_for +```Output +Current thread id: 16196 +``` + +## `sleep_for` Blocks the calling thread. ```cpp -template -inline void sleep_for(const chrono::duration& Rel_time); +template +void sleep_for(const chrono::duration& Rel_time); ``` ### Parameters -*Rel_time*\ -A [duration](../standard-library/duration-class.md) object that specifies a time interval. +*`Rel_time`*\ +A [`duration`](duration-class.md) object that specifies a time interval. ### Remarks -The function blocks the calling thread for at least the time that's specified by *Rel_time*. This function does not throw any exceptions. +The function blocks the calling thread for at least the time that's specified by *`Rel_time`*. This function does not throw any exceptions. -## sleep_until +## `sleep_until` Blocks the calling thread at least until the specified time. ```cpp template void sleep_until(const chrono::time_point& Abs_time); - -void sleep_until(const xtime *Abs_time); ``` ### Parameters -*Abs_time*\ +*`Abs_time`*\ Represents a point in time. ### Remarks This function does not throw any exceptions. -## swap +## `swap` Swaps the states of two `thread` objects. @@ -69,17 +84,17 @@ void swap(thread& Left, thread& Right) noexcept; ### Parameters -*Left*\ +*`Left`*\ The left `thread` object. -*Right*\ +*`Right`*\ The right `thread` object. ### Remarks The function calls `Left.swap(Right)`. -## yield +## `yield` Signals the operating system to run other threads, even if the current thread would ordinarily continue to run. @@ -89,4 +104,4 @@ inline void yield() noexcept; ## See also -[\](../standard-library/thread.md) +[``](thread.md) diff --git a/docs/standard-library/thread-operators.md b/docs/standard-library/thread-operators.md index ad1f33155d7..485cbf10b5f 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 25750ba6014..abd437c52b7 100644 --- a/docs/standard-library/time-get-byname-class.md +++ b/docs/standard-library/time-get-byname-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: time_get_byname Class" title: "time_get_byname Class" -ms.date: "11/04/2016" +description: "Learn more about: time_get_byname Class" +ms.date: 11/04/2016 f1_keywords: ["xloctime/std::time_get_byname"] helpviewer_keywords: ["time_get_byname class"] -ms.assetid: 6e54153e-da40-4bb9-a942-1a6ce57b30c9 --- # time_get_byname Class @@ -41,7 +40,7 @@ An initial reference count. ## Requirements -Its behavior is determined by the named locale *_Locname*. Each constructor initializes its base object with [time_get](../standard-library/time-get-class.md#time_get)\( `_Refs`). +Its behavior is determined by the named locale *_Locname*. Each constructor initializes its base object with [time_get](../standard-library/time-get-class.md#time_get)\(`_Refs`). **Header:** \ diff --git a/docs/standard-library/time-point-class.md b/docs/standard-library/time-point-class.md index b5b9baf42b6..5535d23dd92 100644 --- a/docs/standard-library/time-point-class.md +++ b/docs/standard-library/time-point-class.md @@ -1,8 +1,8 @@ --- -description: "Learn more about: time_point Class" title: "time_point Class" +description: "Learn more about: time_point Class" ms.date: 01/05/2022 -f1_keywords: ["chrono/std::chrono::time_point", "chrono/std::chrono::time_point::operator +=", "chrono/std::chrono::time_point::operator -=", "chrono/std::chrono::time_point::max", "chrono/std::chrono::time_point::min", "chrono/std::chrono::time_point::time_since_epoch"] +f1_keywords: ["chrono/std::chrono::time_point", "chrono/std::chrono::time_point::operator +=", "chrono/std::chrono::time_point::operator -=", "chrono/std::chrono::time_point::max", "chrono/std::chrono::time_point::min", "chrono/std::chrono::time_point::time_since_epoch"] helpviewer_keywords: ["std::chrono [C++], time_point"] dev_langs: ["C++"] --- diff --git a/docs/standard-library/time-put-class.md b/docs/standard-library/time-put-class.md index 60255f4f25a..7792d1448d1 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 b53f32031ea..bfb970bf6fa 100644 --- a/docs/standard-library/toc.yml +++ b/docs/standard-library/toc.yml @@ -149,7 +149,7 @@ items: href: chrono-operators.md - name: literals href: chrono-literals.md - - name: ambiguous_local_time + - name: ambiguous_local_time class href: ambiguous-local-time.md - name: choose enum href: choose-enum.md @@ -169,11 +169,11 @@ items: href: gps-clock-class.md - name: hh_mm_ss class href: hhmmss-class.md - - name: high_resolution_clock struct + - name: high_resolution_clock struct href: high-resolution-clock-struct.md - - name: is_clock struct + - name: is_clock struct href: is-clock-struct.md - - name: last_spec + - name: last_spec struct href: last-spec-struct.md - name: leap_second class href: leap-second-class.md @@ -193,7 +193,7 @@ items: href: month-weekday-class.md - name: month_weekday_last class href: month-weekday-last-class.md - - name: nonexistent_local_time + - name: nonexistent_local_time class href: nonexistent-local-time.md - name: steady_clock struct href: steady-clock-struct.md @@ -219,7 +219,7 @@ items: href: utc-clock-class.md - name: weekday class href: weekday-class.md - - name: weekday_indexed + - name: weekday_indexed class href: weekdayindexed-class.md - name: weekday_last class href: weekdaylast-class.md @@ -256,11 +256,11 @@ items: href: codecvt.md - name: enums href: codecvt-enums.md - - name: codecvt_utf8 + - name: codecvt_utf8 class href: codecvt-utf8-class.md - - name: codecvt_utf8_utf16 + - name: codecvt_utf8_utf16 class href: codecvt-utf8-utf16-class.md - - name: codecvt_utf16 + - name: codecvt_utf16 class href: codecvt-utf16-class.md - name: expanded: false @@ -592,6 +592,8 @@ items: items: - name: href: iterator.md + - name: concepts + href: iterator-concepts.md - name: functions href: iterator-functions.md - name: operators @@ -795,6 +797,8 @@ items: href: recursive-mutex-class.md - name: recursive_timed_mutex class href: recursive-timed-mutex-class.md + - name: scoped_lock class + href: scoped-lock-class.md - name: timed_mutex class href: timed-mutex-class.md - name: try_to_lock_t struct @@ -926,8 +930,62 @@ items: items: - name: href: ranges.md + - name: concepts + href: range-concepts.md - name: functions href: range-functions.md + - name: view classes + href: view-classes.md + expanded: false + items: + - name: basic_istream_view class + href: basic-istream-view-class.md + - name: common_view class + href: common-view-class.md + - name: drop_view class + href: drop-view-class.md + - name: drop_while_view class + href: drop-while-view-class.md + - name: elements_view class + href: elements-view-class.md + - name: empty_view class + href: empty-view-class.md + - name: filter_view class + href: filter-view-class.md + - name: iota_view class + href: iota-view-class.md + - name: join_view class + href: join-view-class.md + - name: keys_view class + href: keys-view-class.md + - name: lazy_split_view class + href: lazy-split-view-class.md + - name: owning_view class + href: owning-view-class.md + - name: ref_view class + href: ref-view-class.md + - name: reverse_view class + href: reverse-view-class.md + - name: single_view class + href: single-view-class.md + - name: split_view class + href: split-view-class.md + - name: subrange class + href: subrange-class.md + - name: take_view class + href: take-view-class.md + - name: take_while_view class + href: take-while-view-class.md + - name: transform_view class + href: transform-view-class.md + - name: values_view class + href: values-view-class.md + - name: view_interface class + href: view-interface.md + - name: alias templates + href: ranges-alias-templates.md + - name: Range adaptors + href: range-adaptors.md - name: href: ratio.md - name: @@ -1391,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: @@ -1464,6 +1524,8 @@ items: href: using-cpp-library-headers.md - name: C++ Library conventions href: cpp-library-conventions.md + - name: C++ Standard Library containers + href: stl-containers.md - name: C++ program startup and termination href: cpp-program-startup-and-termination.md - name: "Safe libraries: C++ Standard Library" @@ -1492,104 +1554,12 @@ items: href: thread-safety-in-the-cpp-standard-library.md - name: stdext namespace href: stdext-namespace.md -- name: C++ Standard Library containers - expanded: false - items: - - name: C++ Standard Library containers - href: stl-containers.md - - name: - expanded: false - items: - - name: - href: sample-container.md - - name: operators - expanded: false - items: - - name: operators - href: sample-container-operators.md - - name: operator!= - href: operator-inequality.md - - name: operator== () - href: operator-equality-sample-container.md - - name: operator< () - href: operator-less-than-sample-container.md - - name: operator<= () - href: operator-less-or-equal-sample-container.md - - name: operator> () - href: operator-greater-than-sample-container.md - - name: operator>= - href: operator-greater-or-equal.md - - name: specialized template functions - expanded: false - items: - - name: specialized template functions - href: sample-container-specialized-template-functions.md - - name: swap () - href: swap-sample-container.md - - name: classes - expanded: false - items: - - name: classes - href: sample-container-classes.md - - name: Sample container class - expanded: false - items: - - name: Sample container class - href: sample-container-class.md - - name: Sample container members - href: sample-container-members.md - - name: Sample container typedefs - expanded: false - items: - - name: Sample container typedefs - href: sample-container-typedefs.md - - name: "Container class::const_iterator" - href: container-class-const-iterator.md - - name: "Container class::const_reference" - href: container-class-const-reference.md - - name: "Container class::const_reverse_iterator" - href: container-class-const-reverse-iterator.md - - name: "Container class::difference_type" - href: container-class-difference-type.md - - name: "Container class::iterator" - href: container-class-iterator.md - - name: "Container class::reference" - href: container-class-reference.md - - name: "Container class::reverse_iterator" - href: container-class-reverse-iterator.md - - name: "Container class::size_type" - href: container-class-size-type.md - - name: "Container class::value_type" - href: container-class-value-type.md - - name: Sample container member functions - expanded: false - items: - - name: Sample container member functions - href: sample-container-member-functions.md - - name: "Container class::begin" - href: container-class-begin.md - - name: "Container class::clear" - href: container-class-clear.md - - name: "Container class::empty" - href: container-class-empty.md - - name: "Container class::end" - href: container-class-end.md - - name: "Container class::erase" - href: container-class-erase.md - - name: "Container class::max_size" - href: container-class-max-size.md - - name: "Container class::rbegin" - href: container-class-rbegin.md - - name: "Container class::rend" - href: container-class-rend.md - - name: "Container class::size" - href: container-class-size.md - - name: "Container class::swap" - href: container-class-swap.md - name: Iterators href: iterators.md - name: Algorithms href: algorithms.md +- name: Vectorized STL Algorithms + href: vectorized-stl-algorithms.md - name: Allocators href: allocators.md - name: Function objects in the C++ Standard Library diff --git a/docs/standard-library/transform-view-class.md b/docs/standard-library/transform-view-class.md new file mode 100644 index 00000000000..287645db343 --- /dev/null +++ b/docs/standard-library/transform-view-class.md @@ -0,0 +1,250 @@ +--- +title: transform_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) transform_view class, which is a view of an underlying sequence after applying a transformation function to each element." +ms.date: 12/14/2022 +f1_keywords: ["ranges/std::transform_view", "ranges/std::transform_view::base", "ranges/std::transform_view::begin", "ranges/std::transform_view::empty", "ranges/std::transform_view::end", "ranges/std::transform_view::operator bool", "ranges/std::transform_view::back", "ranges/std::transform_view::front", "ranges/std::transform_view::operator[]"] +helpviewer_keywords: ["std::ranges::transform_view [C++]", "std::ranges::transform_view::base [C++]", "std::ranges::transform_view::begin [C++]", "std::ranges::transform_view::empty [C++]", "std::ranges::transform_view::end [C++]", "std::ranges::transform_view::back [C++]", "std::ranges::transform_view::front [C++]", "std::ranges::transform_view::operator bool [C++]", "std::ranges::transform_view::operator[] [C++]"] +dev_langs: ["C++"] +--- +# `transform_view` class (C++ Standard Library) + +A view of elements, each of which is a transformation of an element in the specified range. + +## Syntax + +```cpp +template + requires view && is_object_v && + regular_invocable> && + can-reference>> +class transform_view : public view_interface>; +``` + +### Template parameters + +*`F`*\ +The type of the function object that transforms the elements. + +*`V`*\ + The type of the underlying view. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::transform`](range-adaptors.md#transform) | +| **Underlying range** | Must satisfy [`input_range`](range-concepts.md#input_range) or higher | +| **Element type** | Same as the transformation function's return type. | +| **View iterator category** | Supports [`input_range`](range-concepts.md#input_range) up to [`random_access_range`](range-concepts.md#random_access_range), depending on the underlying range | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range is `const` iterable and the transformation works on `const` references. | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | No | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct the view. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the view. | +| [`size`](#size)C++20 | Get the number of elements. The underlying range must satisfy [`sized_range`](range-concepts.md#sized_range). | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the view is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the view isn't empty. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Constructors + +Construct an instance of a `transform_view` + +```cpp +1) transform_view() requires default_initializable + && default_initializable = default; +2) constexpr transform_view(V base, F func); +``` + +### Parameters + +*`base`*\ +The underlying view. + +*`func`*\ +The function that transforms each element. + +For information about template parameter types, see [Template parameters](#template-parameters). + +### Return value + +A `transform_view` instance. + +### Remarks + +The best way to create a `transform_view` is by using the [`views::transform`](range-adaptors.md#transform) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1\) Create a value-initialized `transform_view`. The transformation function and the underlying view must be default-initializable.\ +2\) Move construct the `transform_view` from a *`base`* view and a transformation function *`func`*. Both *`base`* and *`func`* are moved via `std::move()`. + +### Example: `transform_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include + +using namespace std; +using namespace chrono; + +void print(auto v) +{ + for (auto x : v) + { + cout << x << ' '; + } + cout << '\n'; +} + +struct classes +{ + string className; + weekday startDay; +}; + +int main() +{ + std::vector v{0, 1, 2, 3, -4, 5, 6}; + + // outputs 0 2 4 6 -8 10 12 + print(v | std::views::transform([](int i) {return i * 2; })); + + // ---- Modify the elements in the collection by returning a reference to the element to transform + + std::vector theClasses = { + {"Math", Monday}, + {"English", Wednesday}, + {"History", Monday}, + {"Science", Wednesday}, + {"Art", Friday}, + {"Music", Thursday} + }; + + // lambda to get a reference to the day of the week for a class + auto getDay = [](classes& c) -> weekday& + { + return c.startDay; + }; + + // If a class starts on Monday, change it to Tuesday + for (auto&& startDay : theClasses | std::views::transform(getDay)) + { + // modify the startDay in the collection + if (startDay == Monday) + { + startDay = Tuesday; + } + } + + // output classes and start times + for (auto c : theClasses) + { + std::cout << c.className << " : " << c.startDay << '\n'; + } +} +``` + +```output +0 2 4 6 -8 10 12 +Math : Tue +English : Wed +History : Tue +Science : Wed +Art : Fri +Music : Thu +``` + +## `base` + +Get the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses std::move() to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None. + +### Returns + +The underlying view. + +## `begin` + +Get an iterator to the first element in the view. + +```cpp +constexpr auto begin(); +``` + +### Return value + +An iterator pointing at the first element in the view. +The behavior is undefined if the view doesn't have a predicate. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the view. + +```cpp +constexpr auto end() +``` + +### Return value + +The sentinel that follows the last element in the view: + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements in the view. + +```cpp +constexpr auto size() requires ranges::sized_range; +constexpr auto size() const requires ranges::sized_range; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the view. + +## See also + +[``](ranges.md)\ +[`filter` range adaptor](range-adaptors.md#filter)\ +[view classes](view-classes.md) diff --git a/docs/standard-library/treat-as-floating-point-structure.md b/docs/standard-library/treat-as-floating-point-structure.md index 7389b8620fe..4dbd2818c38 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 e5ed361621c..43ca9b50ea4 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 330d79df38f..1d79412bc5f 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 4bf7fc0c661..1cf5eab06cd 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 b1df31e15f7..95eaa6fc7bc 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/type-traits.md b/docs/standard-library/type-traits.md index 80f42ef05a1..b91cd8884c6 100644 --- a/docs/standard-library/type-traits.md +++ b/docs/standard-library/type-traits.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: " title: "" -ms.date: "02/21/2019" +description: "Learn more about: " +ms.date: 02/21/2019 f1_keywords: [""] helpviewer_keywords: ["typetrait header", "type_traits"] -ms.assetid: 2260b51f-8160-4c66-a82f-00b534cb60d4 --- # `` @@ -44,7 +43,7 @@ These are the provided aliases for the `type` members: `add_rvalue_reference_t`\ `add_volatile_t`\ `aligned_storage_t`\ - `aligned_union_t`\ + `aligned_union_t` :::column-end::: :::column::: `common_type_t`\ @@ -54,7 +53,7 @@ These are the provided aliases for the `type` members: `invoke_result_t`\ `make_signed_t`\ `make_unsigned_t`\ - `remove_all_extents_t`\ + `remove_all_extents_t` :::column-end::: :::column::: `remove_const_t`\ @@ -64,7 +63,7 @@ These are the provided aliases for the `type` members: `remove_reference_t`\ `remove_volatile_t`\ `result_of_t`\ - `underlying_type_t`\ + `underlying_type_t` :::column-end::: :::row-end::: diff --git a/docs/standard-library/tzdb-list-class.md b/docs/standard-library/tzdb-list-class.md index 343c082f3d6..b43b5a4baee 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 811bbb391db..071c37fda03 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/underflow-error-class.md b/docs/standard-library/underflow-error-class.md index eee569a3f7b..3b1d405babc 100644 --- a/docs/standard-library/underflow-error-class.md +++ b/docs/standard-library/underflow-error-class.md @@ -1,12 +1,11 @@ --- -description: "Learn more about: underflow_error Class" -title: "underflow_error Class" -ms.date: "09/09/2021" +title: "underflow_error class" +description: "Learn more about: underflow_error class" +ms.date: 09/09/2021 f1_keywords: ["stdexcept/std::underflow_error"] helpviewer_keywords: ["underflow_error class"] -ms.assetid: d632f1f9-9c6c-4954-b96b-03041bfab22d --- -# underflow_error Class +# `underflow_error` class The class serves as the base class for all exceptions thrown to report an arithmetic underflow. @@ -18,13 +17,12 @@ public: explicit underflow_error(const string& message); explicit underflow_error(const char *message); - }; ``` ## Remarks -The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](../standard-library/exception-class.md) and [`data`](../standard-library/basic-string-class.md#data). +The value returned by `what()` is a copy of `message.data()`. For more information, see [`what`](exception-class.md) and [`data`](basic-string-class.md#data). `underflow_error` isn't thrown by any functions in the Microsoft implementation of the C++ Standard Library, but it might be thrown by third-party libraries or user code. @@ -51,19 +49,20 @@ int main() cerr << "Type: " << typeid(e).name() << endl; } } -/* Output: +``` + +```Output Caught: The number's a bit small, captain! Type: class std::underflow_error -*/ ``` ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## See also -[runtime_error Class](../standard-library/runtime-error-class.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md) +[`runtime_error` class](runtime-error-class.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md) diff --git a/docs/standard-library/unique-lock-class.md b/docs/standard-library/unique-lock-class.md index 612058f1d80..6332a02e08d 100644 --- a/docs/standard-library/unique-lock-class.md +++ b/docs/standard-library/unique-lock-class.md @@ -1,9 +1,8 @@ --- -description: "Learn more about: unique_lock Class" title: "unique_lock Class" +description: "Learn more about: unique_lock Class" ms.date: 06/20/2022 f1_keywords: ["mutex/std::unique_lock"] -ms.assetid: f4ed8ba9-c8af-446f-8ef0-0b356bad14bd ms.custom: devdivchpfy22 --- @@ -298,7 +297,7 @@ The remaining constructors store & *Mtx* as the stored `mutex` pointer. Ownershi |`Rel_time`|Ownership is determined by calling `try_lock_for(Rel_time)`.| |`Abs_time`|Ownership is determined by calling `try_lock_until(Abs_time)`.| -## ~unique_lock Destructor +## ~unique_lock Destructor Releases any resources that are associated with the `unique_lock` object. diff --git a/docs/standard-library/unordered-map-class.md b/docs/standard-library/unordered-map-class.md index 90f5e8ac492..fb8bf60b413 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. @@ -796,7 +795,7 @@ The key value of the element to look for. ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -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 36f731bacf1..20e3941dffc 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 1e4e87c66d0..5913612c659 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 0f61a2cac00..b1071b77809 100644 --- a/docs/standard-library/unordered-multimap-class.md +++ b/docs/standard-library/unordered-multimap-class.md @@ -1,13 +1,9 @@ --- title: "unordered_multimap Class" description: "API overview for the C++ Standard Library container class `unordered_multimap`." -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 +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"] --- # unordered_multimap Class @@ -99,7 +95,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. @@ -750,7 +746,7 @@ The element's key value to look for. ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include diff --git a/docs/standard-library/unordered-multiset-class.md b/docs/standard-library/unordered-multiset-class.md index 1a08ac38ecf..1b6e8fd3651 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. @@ -741,7 +740,7 @@ The element's key value to look for. ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include diff --git a/docs/standard-library/unordered-set-class.md b/docs/standard-library/unordered-set-class.md index ab90d089afb..be1541f0425 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. @@ -744,7 +744,7 @@ The element's key value to look for. ### Example ```cpp -// Requires /std:c++20 or /std:c++latest +// Requires /std:c++20 or later #include #include @@ -1089,7 +1089,7 @@ Key value to search for. ### Remarks -The member function returns a pair of iterators `X` such that`[X.first, X.second)` delimits just those elements of the controlled sequence that have equivalent ordering with *`keyval`*. If no such elements exist, both iterators are `end()`. +The member function returns a pair of iterators `X` such that `[X.first, X.second)` delimits just those elements of the controlled sequence that have equivalent ordering with *`keyval`*. If no such elements exist, both iterators are `end()`. ### Example @@ -2376,7 +2376,7 @@ The `initializer_list` containing the elements to copy. ### Remarks -The first constructor specifies a copy of the sequence controlled by *`Right`*. The second constructor specifies an empty controlled sequence. The third constructor specifies a copy of the sequence by moving *`Right`* The fourth through eighth constructors use an `initializer_list` to specify the elements to copy. The ninth constructor inserts the sequence of element values`[first, last)`. +The first constructor specifies a copy of the sequence controlled by *`Right`*. The second constructor specifies an empty controlled sequence. The third constructor specifies a copy of the sequence by moving *`Right`* The fourth through eighth constructors use an `initializer_list` to specify the elements to copy. The ninth constructor inserts the sequence of element values `[first, last)`. All constructors also initialize several stored values. For the copy constructor, the values are obtained from *`Right`*. Otherwise: diff --git a/docs/standard-library/unordered-set-operators.md b/docs/standard-library/unordered-set-operators.md index 1d57b37d00d..ee5bc48f7d7 100644 --- a/docs/standard-library/unordered-set-operators.md +++ b/docs/standard-library/unordered-set-operators.md @@ -1,15 +1,16 @@ --- -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_set/std::operator!=", "unordered_set/std::operator=="] -ms.assetid: 8653eea6-12f2-4dd7-aa2f-db38a71599a0 --- # `` operators -## operator!= +The `` header provides the following operators: + +## `operator!=` -Tests whether the [unordered_set](../standard-library/unordered-set-class.md) object on the left side of the operator is not equal to the unordered_set object on the right side. +Tests whether the [`unordered_set`](unordered-set-class.md) object on the left side of the operator is not equal to the `unordered_set` object on the right side. ```cpp bool operator!=(const unordered_set & left, const unordered_set & right); @@ -17,19 +18,19 @@ bool operator!=(const unordered_set & left, const un ### Parameters -*left*\ +*`left`*\ An object of type `unordered_set`. -*right*\ +*`right`*\ An object of type `unordered_set`. ### Return Value -**`true`** if the unordered_sets are not equal; **`false`** if they are equal. +**`true`** if the `unordered_set`s are not equal; **`false`** if they are equal. ### Remarks -The comparison between unordered_set objects is not affected by the arbitrary order in which they store their elements. Two unordered_sets are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. +The comparison between `unordered_set` objects is not affected by the arbitrary order in which they store their elements. Two `unordered_set`s are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. ### Example @@ -67,17 +68,15 @@ int main() } ``` -**Output:** - -`c1 != c2: true` - -`c1 != c3: false` - -`c2 != c3: true` +```Output +c1 != c2: true +c1 != c3: false +c2 != c3: true +``` -## operator== +## `operator==` -Tests whether the [unordered_set](../standard-library/unordered-set-class.md) object on the left side of the operator is equal to the unordered_set object on the right side. +Tests whether the [`unordered_set`](unordered-set-class.md) object on the left side of the operator is equal to the `unordered_set` object on the right side. ```cpp bool operator==(const unordered_set & left, const unordered_set & right); @@ -85,19 +84,19 @@ bool operator==(const unordered_set & left, const un ### Parameters -*left*\ +*`left`*\ An object of type `unordered_set`. -*right*\ +*`right`*\ An object of type `unordered_set`. ### Return Value -**`true`** if the unordered_sets are equal; **`false`** if they are not equal. +**`true`** if the `unordered_set`s are equal; **`false`** if they are not equal. ### Remarks -The comparison between unordered_set objects is not affected by the arbitrary order in which they store their elements. Two unordered_sets are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. +The comparison between `unordered_set` objects is not affected by the arbitrary order in which they store their elements. Two `unordered_set`s are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. ### Example @@ -141,9 +140,9 @@ c1 == c3: true c2 == c3: false ``` -## operator!= (multiset) +## `operator!=` (multiset) -Tests whether the [unordered_multiset](../standard-library/unordered-multiset-class.md) object on the left side of the operator is not equal to the unordered_multiset object on the right side. +Tests whether the [`unordered_multiset`](unordered-multiset-class.md) object on the left side of the operator is not equal to the `unordered_multiset` object on the right side. ```cpp bool operator!=(const unordered_multiset & left, const unordered_multiset & right); @@ -151,19 +150,19 @@ bool operator!=(const unordered_multiset & left, con ### Parameters -*left*\ +*`left`*\ An object of type `unordered_multiset`. -*right*\ +*`right`*\ An object of type `unordered_multiset`. ### Return Value -**`true`** if the unordered_multisets are not equal; **`false`** if they are equal. +**`true`** if the `unordered_multiset`s are not equal; **`false`** if they are equal. ### Remarks -The comparison between unordered_multiset objects is not affected by the arbitrary order in which they store their elements. Two unordered_multisets are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. +The comparison between `unordered_multiset` objects is not affected by the arbitrary order in which they store their elements. Two `unordered_multiset`s are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. ### Example @@ -210,9 +209,9 @@ c1 != c3: false c2 != c3: true ``` -## operator== (multiset) +## `operator==` (multiset) -Tests whether the [unordered_multiset](../standard-library/unordered-multiset-class.md) object on the left side of the operator is equal to the unordered_multiset object on the right side. +Tests whether the [`unordered_multiset`](unordered-multiset-class.md) object on the left side of the operator is equal to the `unordered_multiset` object on the right side. ```cpp bool operator==(const unordered_multiset & left, const unordered_multiset & right); @@ -220,19 +219,19 @@ bool operator==(const unordered_multiset & left, con ### Parameters -*left*\ +*`left`*\ An object of type `unordered_multiset`. -*right*\ +*`right`*\ An object of type `unordered_multiset`. ### Return Value -**`true`** if the unordered_multisets are equal; **`false`** if they are not equal. +**`true`** if the `unordered_multiset`s are equal; **`false`** if they are not equal. ### Remarks -The comparison between unordered_multiset objects is not affected by the arbitrary order in which they store their elements. Two unordered_multisets are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. +The comparison between `unordered_multiset` objects is not affected by the arbitrary order in which they store their elements. Two `unordered_multiset`s are equal if they have the same number of elements and the elements in one container are a permutation of the elements in the other container. Otherwise, they are unequal. ### Example 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 561261d4663..359347be9f4 100644 --- a/docs/standard-library/using-insertion-operators-and-controlling-format.md +++ b/docs/standard-library/using-insertion-operators-and-controlling-format.md @@ -1,6 +1,6 @@ --- -description: "Learn more about: Using Insertion Operators and Controlling Format" title: "Using Insertion Operators and Controlling Format" +description: "Learn more about: Using Insertion Operators and Controlling Format" ms.date: 10/07/2021 helpviewer_keywords: ["insertion operators"] --- @@ -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 @@ -165,7 +165,7 @@ Stan 4358.2 If you change the `ios::fixed` flag to `ios::scientific`, the program prints this: -```cpp +```Output Zoot 1.2e+00 Jimmy 3.5e+01 Al 6.5e+02 diff --git a/docs/standard-library/utc-clock-class.md b/docs/standard-library/utc-clock-class.md index 285b3ce5096..1521bfbe8e1 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 f5ce99bc8e0..649d4939345 100644 --- a/docs/standard-library/utility-functions.md +++ b/docs/standard-library/utility-functions.md @@ -43,7 +43,7 @@ The object whose value is copied or moved into `val`. ### Remarks -For complex types, `exchange` avoids copying the old value when a move constructor is available, avoids copying the new value if it’s a temporary object or is moved, and accepts any type as the new value, using any available converting assignment operator. The exchange function is different from [`std::swap`](../standard-library/algorithm-functions.md#swap) in that the left argument isn't moved or copied to the right argument. +For complex types, `exchange` avoids copying the old value when a move constructor is available, avoids copying the new value if it's a temporary object or is moved, and accepts any type as the new value, using any available converting assignment operator. The exchange function is different from [`std::swap`](../standard-library/algorithm-functions.md#swap) in that the left argument isn't moved or copied to the right argument. ### Example @@ -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 253764a553a..c522bcbcd3f 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" +description: "Learn more about: " +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_lt_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 afea2e93f1b..e51df410949 100644 --- a/docs/standard-library/valarray-class.md +++ b/docs/standard-library/valarray-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: valarray Class" title: "valarray class" +description: "Learn more about: valarray Class" ms.date: 06/20/2022 f1_keywords: ["valarray/std::valarray", "valarray/std::valarray::value_type", "valarray/std::valarray::apply", "valarray/std::valarray::cshift", "valarray/std::valarray::free", "valarray/std::valarray::max", "valarray/std::valarray::min", "valarray/std::valarray::resize", "valarray/std::valarray::shift", "valarray/std::valarray::size", "valarray/std::valarray::sum", "valarray/std::valarray::swap"] helpviewer_keywords: ["std::valarray [C++]", "std::valarray [C++], value_type", "std::valarray [C++], apply", "std::valarray [C++], cshift", "std::valarray [C++], free", "std::valarray [C++], max", "std::valarray [C++], min", "std::valarray [C++], resize", "std::valarray [C++], shift", "std::valarray [C++], size", "std::valarray [C++], sum", "std::valarray [C++], swap"] -ms.assetid: 19b862f9-5d09-4003-8844-6ddd02c1a3a7 ms.custom: devdivchpfy22 --- @@ -1143,7 +1142,7 @@ int main( ) for ( i = 0 ; i < 10 ; i += 1 ) va [ i ] = i; for ( i = 0 ; i < 10 ; i+=1 ) - vaR [ i ] = 10 - i; + vaR [ i ] = 10 - i; cout << "The operand valarray va is:"; for ( i = 0 ; i < 10 ; i++ ) @@ -1609,7 +1608,7 @@ int main( ) for ( i = 0 ; i < 10 ; i += 1 ) va1 [ i ] = i; for ( i = 0 ; i < 10 ; i += 1 ) - va2 [ i ] = 10 - i; + va2 [ i ] = 10 - i; cout << "The operand valarray va1(10) is: ( "; for ( i = 0 ; i < 10 ; i++ ) @@ -1962,7 +1961,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 +1973,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 26fe06609e3..47dbac6e275 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/value-compare-class.md b/docs/standard-library/value-compare-class.md index 9777faa45ae..18f66856546 100644 --- a/docs/standard-library/value-compare-class.md +++ b/docs/standard-library/value-compare-class.md @@ -1,20 +1,19 @@ --- -description: "Learn more about: value_compare Class" title: "value_compare Class" -ms.date: "11/04/2016" +description: "Learn more about: value_compare Class" +ms.date: 11/04/2016 f1_keywords: ["hash_map/std::value_compare"] helpviewer_keywords: ["value_compare class"] -ms.assetid: c306c5b9-3505-4357-aa6b-216451b951ed --- -# value_compare Class +# `value_compare` Class -Provides a function object that can compare the elements of a hash_map by comparing the values of their keys to determine their relative order in the hash_map. +Provides a function object that can compare the elements of a `hash_map` by comparing the values of their keys to determine their relative order in the `hash_map`. ## Syntax ```cpp class value_compare - : std::public binary_function + : public binary_function { public: bool operator()( @@ -32,22 +31,22 @@ protected: ## Remarks -The comparison criteria provided by value_compare between `value_types` of whole elements contained by a hash_map is induced from a comparison between the keys of the respective elements by the auxiliary class construction. The member function operator uses the object `comp` of type `key_compare` stored in the function object provided by value_compare to compare the sort-key components of two elements. +The comparison criteria provided by `value_compare` between `value_types` of whole elements contained by a `hash_map` is induced from a comparison between the keys of the respective elements by the auxiliary class construction. The member function operator uses the object `comp` of type `key_compare` stored in the function object provided by `value_compare` to compare the sort-key components of two elements. -For hash_sets and hash_multisets, which are simple containers where the key values are identical to the element values, value_compare is equivalent to `key_compare`; for hash_maps and hash_multimaps they are not, because the value of the type `pair` elements is not identical to the value of the element's key. +For `hash_set`s and `hash_multiset`s, which are simple containers where the key values are identical to the element values, `value_compare` is equivalent to `key_compare`; for `hash_map`s and `hash_multimap`s they are not, because the value of the type `pair` elements is not identical to the value of the element's key. ## Example -See the example for [hash_map::value_comp](../standard-library/hash-map-class.md#value_comp) for an example of how to declare and use value_compare. +See the example for [`hash_map::value_comp`](hash-map-class.md#value_comp) for an example of how to declare and use `value_compare`. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** stdext +**Namespace:** `stdext` ## See also -[binary_function Struct](../standard-library/binary-function-struct.md)\ -[Thread Safety in the C++ Standard Library](../standard-library/thread-safety-in-the-cpp-standard-library.md)\ -[C++ Standard Library Reference](../standard-library/cpp-standard-library-reference.md) +[`binary_function` Struct](binary-function-struct.md)\ +[Thread Safety in the C++ Standard Library](thread-safety-in-the-cpp-standard-library.md)\ +[C++ Standard Library Reference](cpp-standard-library-reference.md) diff --git a/docs/standard-library/values-view-class.md b/docs/standard-library/values-view-class.md new file mode 100644 index 00000000000..d069ff09e66 --- /dev/null +++ b/docs/standard-library/values-view-class.md @@ -0,0 +1,248 @@ +--- +title: values_view class (C++ Standard Library) +description: "API reference for the Standard Template Library (STL) values_view class, which provides a view over the second index into each tuple-like value in a collection. It's useful for extracting values from associative containers." +ms.date: 10/07/2022 +f1_keywords: ["ranges/std::values_view", "ranges/std::values_view::base", "ranges/std::values_view::begin", "ranges/std::values_view::empty", "ranges/std::values_view::end", "ranges/std::values_view::size", "ranges/std::values_view::operator bool", "ranges/std::values_view::back", "ranges/std::values_view::front", "ranges/std::values_view::operator[]"] +helpviewer_keywords: ["std::ranges::values_view [C++]", "std::ranges::values_view::base [C++]", "std::ranges::values_view::begin [C++]", "std::ranges::values_view::empty [C++]", "std::ranges::values_view::end [C++]", "std::ranges::values_view::size [C++]", "std::ranges::values_view::back [C++]", "std::ranges::values_view::front [C++]", "std::ranges::values_view::operator[] [C++]", "std::ranges::values_view::operator bool [C++]"] +dev_langs: ["C++"] +--- +# `values_view` class (C++ Standard Library) + +A view consisting of the second index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view consisting of all the `int` elements from each tuple. + +`values_view` is an alias for `elements_view` and is useful for creating a view of the values in associative containers such as [`std::unordered_map`](unordered-map-class.md). + +## Syntax + +```cpp +template +using values_view = ranges::elements_view; +``` + +### Template parameters + +`R`\ + The type of the underlying range. This type must satisfy `ranges::input_range`. + +## View characteristics + +For a description of the following entries, see [View class characteristics](view-classes.md#view-classes-characteristics) + +| Characteristic | Description | +|--|--| +| **Range adaptor** | [`views::values`](range-adaptors.md#values) | +| **Underlying range** | Must satisfy [`forward_range`](range-concepts.md#forward_range) or higher | +| **Element type** | Same as the type of the second tuple element | +| **View iterator category** | `forward_range`, [`bidirectional_range`](range-concepts.md#bidirectional_range), or [`random_access_range`](range-concepts.md#random_access_range) | +| **Sized** | Only if the underlying range satisfies [`sized_range`](range-concepts.md#sized_range) | +| **Is `const`-iterable** | Only if the underlying range satisfies `const-iterable` | +| **Common range** | Only if the underlying range satisfies [`common_range`](range-concepts.md#common_range) | +| **Borrowed range** | Only if the underlying range satisfies [`borrowed_range`](range-concepts.md#borrowed_range) | + +## Members + +| **Member functions** | **Description** | +|--|--| +| [Constructors](#constructors)C++20 | Construct a `values_view`. | +| [`base`](#base)C++20 | Get the underlying range. | +| [`begin`](#begin)C++20 | Get an iterator to the first element. | +| [`end`](#end)C++20 | Get the sentinel at the end of the `values_view`. | +| [`size`](#size)C++20 | Get the number of elements. | +| **Inherited from [`view_interface`](view-interface.md)** | **Description** | +| [`back`](view-interface.md#back)C++20 | Get the last element. | +| [`empty`](view-interface.md#empty)C++20 | Test whether the `values_view` is empty. | +| [`front`](view-interface.md#front)C++20 | Get the first element. | +| [`operator[]`](view-interface.md#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](view-interface.md#op_bool)C++20 | Test whether the `values_view` isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## Remarks + +Tuple-like types that you can use with `values_view` are [`std::tuple`](tuple.md), [`std::pair`](pair-structure.md), and [`std::array`](array.md). + +## Constructors + +Construct an instance of a `values_view`. + +```cpp +1) constexpr values_view(R base); +2) values_view() requires default_initializable = default; +``` + +### Parameters + +*`base`*\ +The underlying range of tuple-like types. + +For information about the template parameter type, see [Template parameters](#template-parameters). + +### Return value + +An `values_view` instance. + +### Remarks + +The best way to create an `values_view` is by using the [`values`](range-adaptors.md#values) range adaptor. Range adaptors are the intended way to create view classes. The view types are exposed in case you want to create your own custom view type. + +1) Create an `values_view` from the specified view. +2) The default constructor creates a default-constructed `values_view`. + +### Example: `values_view` + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include +#include + +int main() +{ + // ========== work with a std::map + + std::map cpp_standards + { + {"C++98", 1988}, + {"C++03", 2003}, + {"C++11", 2011}, + {"C++14", 2014}, + {"C++17", 2017}, + {"C++20", 2020} + }; + + // Extract all of the values from the map + for (int years : std::views::values(cpp_standards)) + { + std::cout << years << ' '; // 2003 2011 2014 2017 1988 2020 + } + std::cout << '\n'; + + // ========== work with a std::pair + + std::vector> windows + { + {"Windows 1.0", 1985}, + {"Windows 2.0", 1987}, + {"Windows 3.0", 1990}, + {"Windows 3.1", 1992}, + {"Windows NT 3.1", 1993}, + {"Windows 95", 1995}, + {"Windows NT 4.0", 1996}, + {"Windows 95", 1995}, + {"Windows 98", 1998}, + {"Windows 1.0", 1985}, + {"Windows 2000", 2000} + }; + + // Another way to call the range adaptor using '|': create a keys_view from each pair + for (int years : windows | std::views::values) + { + std::cout << years << ' '; // 1985 1987 1990 1992 ... + } +} +``` + +```output +2003 2011 2014 2017 1988 2020 +1985 1987 1990 1992 1993 1995 1996 1995 1998 1985 2000 +``` + +## `base` + +Gets a copy of the underlying view. + +```cpp +// Uses a copy constructor to return the underlying view +constexpr V base() const& requires std::copy_constructible; + +// Uses a move constructor to return the underlying view +constexpr V base() &&; +``` + +### Parameters + +None + +### Return value + +The underlying view. + +## `begin` + +Get an iterator to the first element in the `values_view`. + +```cpp +// returns a non-const iterator +1) constexpr auto begin() requires (!Simple_view); + +// returns a const iterator +2) constexpr auto begin() const requires ranges::range; +``` + +### Parameters + +None. + +### Return value + +An iterator pointing at the first element in the `values_view`. + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `end` + +Get the sentinel at the end of the `values_view` + +```cpp +1) constexpr auto end() requires (!Simple_view && !ranges::common_range); +2) constexpr auto end() requires (!Simple_view && ranges::common_range); +3) constexpr auto end() const requires ranges::range; +4) constexpr auto end() const requires ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The sentinel that follows the last element in the `values_view` + +:::image type="content" source="media/begin-end-sentinel.png" alt-text="Picture of a vector with the elements 10, 20, and 30. The first element contains 10 and is labeled begin(). The last element contains 30 and is labeled 'last element'. An imaginary box after the last element indicates the sentinel and is labeled end()."::: + +## `size` + +Get the number of elements. + +```cpp +constexpr auto size() requires sized_range +constexpr auto size() const requires sized_range +``` + +### Parameters + +None. + +### Return value + +The number of elements in the `values_view`. + +### Remarks + +The size of the view is only available if the underlying range is a [`sized_range`](range-concepts.md#sized_range), or in other words, bounded. + +## See also + +[`elements_view`](elements-view-class.md)\ +[`keys_view`](keys-view-class.md)\ +[``](ranges.md)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/variant.md b/docs/standard-library/variant.md index a95acb0e768..04f6018d139 100644 --- a/docs/standard-library/variant.md +++ b/docs/standard-library/variant.md @@ -1,19 +1,19 @@ --- -description: "Learn more about: " title: "" -ms.date: "04/04/2019" +description: "Learn more about: " +ms.date: 04/04/2019 f1_keywords: [""] helpviewer_keywords: [""] --- # `` -A variant object holds and manages a value. If the variant holds a value, that value’s type has to be one of the template argument types given to variant. These template arguments are called alternatives. +A variant object holds and manages a value. If the variant holds a value, that value's type has to be one of the template argument types given to variant. These template arguments are called alternatives. ## Requirements -**Header:** \ +**Header:** `` -**Namespace:** std +**Namespace:** `std` ## Members @@ -21,46 +21,46 @@ A variant object holds and manages a value. If the variant holds a value, that v |Name|Description| |-|-| -|[operator==](../standard-library/forward-list-operators.md#op_eq_eq)|Tests if the variant object on the left side of the operator is equal to the variant object on the right side.| -|[operator!=](../standard-library/forward-list-operators.md#op_neq)|Tests if the variant object on the left side of the operator is not equal to the variant object on the right side.| -|[operator<](../standard-library/forward-list-operators.md#op_lt)|Tests if the variant object on the left side of the operator is less than the variant object on the right side.| -|[operator<=](../standard-library/forward-list-operators.md#op_lt_eq)|Tests if the variant object on the left side of the operator is less than or equal to the variant object on the right side.| -|[operator>](../standard-library/forward-list-operators.md#op_gt)|Tests if the variant object on the left side of the operator is greater than the variant object on the right side.| -|[operator>=](../standard-library/forward-list-operators.md#op_lt_eq)|Tests if the variant object on the left side of the operator is greater than or equal to the variant object on the right side.| +|[`operator==`](variant-operators.md#op_eq_eq)|Tests if the variant object on the left side of the operator is equal to the variant object on the right side.| +|[`operator!=`](variant-operators.md#op_neq)|Tests if the variant object on the left side of the operator is not equal to the variant object on the right side.| +|[`operator<`](variant-operators.md#op_lt)|Tests if the variant object on the left side of the operator is less than the variant object on the right side.| +|[`operator<=`](variant-operators.md#op_lt_eq)|Tests if the variant object on the left side of the operator is less than or equal to the variant object on the right side.| +|[`operator>`](variant-operators.md#op_gt)|Tests if the variant object on the left side of the operator is greater than the variant object on the right side.| +|[`operator>=`](variant-operators.md#op_gt_eq)|Tests if the variant object on the left side of the operator is greater than or equal to the variant object on the right side.| ### Functions |Name|Description| |-|-| -|[get](../standard-library/variant-functions.md#get)|Gets the variant of an object.| -|[get_if](../standard-library/variant-functions.md#get_if)|Gets the variant of an object if it exists.| -|[holds_alternative](../standard-library/variant-functions.md#holds_alternative)|Return **`true`** if a variant exists.| -|[swap](../standard-library/variant-functions.md#swap)|Swaps a **variant**.| -|[visit](../standard-library/variant-functions.md#visit)|Moves to the next **variant**.| +|[`get`](variant-functions.md#get)|Gets the variant of an object.| +|[`get_if`](variant-functions.md#get_if)|Gets the variant of an object if it exists.| +|[`holds_alternative`](variant-functions.md#holds_alternative)|Return **`true`** if a variant exists.| +|[`swap`](variant-functions.md#swap)|Swaps a **variant**.| +|[`visit`](variant-functions.md#visit)|Moves to the next **variant**.| ### Classes |Name|Description| |-|-| -|[bad_variant_access](../standard-library/bad-variant-access-class.md)|Objects thrown to report invalid accesses to the value of a variant object.| -|[variant](../standard-library/variant.md)|An object to either hold a value of one of its alternative types, or no value.| +|[`bad_variant_access`](bad-variant-access-class.md)|Objects thrown to report invalid accesses to the value of a variant object.| +|[`variant`](variant-class.md)|An object to either hold a value of one of its alternative types, or no value.| ### Structs |Name|Description| |-|-| -|[hash](../standard-library/hash-structure.md)|| -|[monostate](../standard-library/monostate-structure.md)|An alternative type for a variant to make the variant type default constructible.| -|[uses_allocator](../standard-library/uses-allocator-structure.md)|| -|[variant_alternative](../standard-library/variant-alternative-structure.md)|Assists the variant objects.| -|[variant_size](../standard-library/variant-size-structure.md)|Assists the variant objects.| +|[`hash`](hash-structure.md)|| +|[`monostate`](monostate-structure.md)|An alternative type for a variant to make the variant type default constructible.| +|[`uses_allocator`](uses-allocator-structure.md)|| +|[`variant_alternative`](variant-alternative-structure.md)|Assists the variant objects.| +|[`variant_size`](variant-size-structure.md)|Assists the variant objects.| ### Objects |Name|Description| |-|-| -|[variant_npos](../standard-library/variant-functions.md#variant_npos)|| +|[`variant_npos`](variant-functions.md#variant_npos)|| ## See also -[Header Files Reference](../standard-library/cpp-standard-library-header-files.md) +[Header Files Reference](cpp-standard-library-header-files.md) diff --git a/docs/standard-library/vector-bool-class.md b/docs/standard-library/vector-bool-class.md index a020cc17b50..8756473a9ef 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"] --- @@ -138,7 +138,7 @@ If you compile with `_ITERATOR_DEBUG_LEVEL` set, a run-time error occurs if you ### Example -This code example shows the correct use of `vector::operator[]` and two common coding mistakes, which are commented out. These mistakes cause errors because the address of the `vector::reference` object that `vector::operator[]` returns can’t be taken. +This code example shows the correct use of `vector::operator[]` and two common coding mistakes, which are commented out. These mistakes cause errors because the address of the `vector::reference` object that `vector::operator[]` returns can't be taken. ```cpp // cl.exe /EHsc /nologo /W4 /MTd @@ -167,6 +167,13 @@ int main() } ``` +```Output +The second element of vb is false +The held value from the second element of vb is false +The second element of vb is true +The held value from the second element of vb is false +``` + ## `vector::pointer` A type that describes an object that can serve as a pointer to a Boolean element of the sequence contained by the `vector` object. @@ -181,7 +188,7 @@ The `vector::reference` class is a proxy class provided by the [`vector` uses only one bit per element, which can be referenced by using this proxy class. However, the reference simulation isn't complete because certain assignments aren't valid. For example, because the address of the `vector::reference` object can’t be taken, the following code that uses [`vector::operator[]`](#op_at) isn't correct: +A simulated reference is required because C++ doesn't natively allow direct references to bits. `vector` uses only one bit per element, which can be referenced by using this proxy class. However, the reference simulation isn't complete because certain assignments aren't valid. For example, because the address of the `vector::reference` object can't be taken, the following code that uses [`vector::operator[]`](#op_at) isn't correct: ```cpp vector vb; @@ -251,7 +258,7 @@ The Boolean value of the element of the `vector` object. #### Remarks -The `vector` object can’t be modified by this operator. +The `vector` object can't be modified by this operator. ### `vector::reference::operator=` @@ -343,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 94f797a3616..e715fe2ee42 100644 --- a/docs/standard-library/vector-class.md +++ b/docs/standard-library/vector-class.md @@ -1,7 +1,7 @@ --- title: "vector class" description: "Reference for Microsoft C++ Standard library implementation of class vector." -ms.date: "02/23/2021" +ms.date: "08/25/2023" f1_keywords: ["vector/std::vector::allocator_type", "vector/std::vector::const_iterator", "vector/std::vector::const_pointer", "vector/std::vector::const_reference", "vector/std::vector::const_reverse_iterator", "vector/std::vector::difference_type", "vector/std::vector::iterator", "vector/std::vector::pointer", "vector/std::vector::reference", "vector/std::vector::reverse_iterator", "vector/std::vector::size_type", "vector/std::vector::value_type", "vector/std::vector::assign", "vector/std::vector::at", "vector/std::vector::back", "vector/std::vector::begin", "vector/std::vector::capacity", "vector/std::vector::cbegin", "vector/std::vector::cend", "vector/std::vector::crbegin", "vector/std::vector::crend", "vector/std::vector::clear", "vector/std::vector::data", "vector/std::vector::emplace", "vector/std::vector::emplace_back", "vector/std::vector::empty", "vector/std::vector::end", "vector/std::vector::erase", "vector/std::vector::front", "vector/std::vector::get_allocator", "vector/std::vector::insert", "vector/std::vector::max_size", "vector/std::vector::pop_back", "vector/std::vector::push_back", "vector/std::vector::rbegin", "vector/std::vector::rend", "vector/std::vector::reserve", "vector/std::vector::resize", "vector/std::vector::shrink_to_fit", "vector/std::vector::size", "vector/std::vector::swap"] helpviewer_keywords: ["std::vector [C++], allocator_type", "std::vector [C++], const_iterator", "std::vector [C++], const_pointer", "std::vector [C++], const_reference", "std::vector [C++], const_reverse_iterator", "std::vector [C++], difference_type", "std::vector [C++], iterator", "std::vector [C++], pointer", "std::vector [C++], reference", "std::vector [C++], reverse_iterator", "std::vector [C++], size_type", "std::vector [C++], value_type", "std::vector [C++], assign", "std::vector [C++], at", "std::vector [C++], back", "std::vector [C++], begin", "std::vector [C++], capacity", "std::vector [C++], cbegin", "std::vector [C++], cend", "std::vector [C++], crbegin", "std::vector [C++], crend", "std::vector [C++], clear", "std::vector [C++], data", "std::vector [C++], emplace", "std::vector [C++], emplace_back", "std::vector [C++], empty", "std::vector [C++], end", "std::vector [C++], erase", "std::vector [C++], front", "std::vector [C++], get_allocator", "std::vector [C++], insert", "std::vector [C++], max_size", "std::vector [C++], pop_back", "std::vector [C++], push_back", "std::vector [C++], rbegin", "std::vector [C++], rend", "std::vector [C++], reserve", "std::vector [C++], resize", "std::vector [C++], shrink_to_fit", "std::vector [C++], size", "std::vector [C++], swap"] --- @@ -13,13 +13,13 @@ The C++ Standard Library vector class is a class template for sequence container ```cpp template > -class vector +class vector; ``` ### Parameters *`Type`*\ -The element data type to be stored in the vector +The element data type to be stored in the vector. *`Allocator`*\ The type that represents the stored allocator object that encapsulates details about the vector's allocation and deallocation of memory. This argument is optional and the default value is `allocator`. @@ -46,7 +46,7 @@ The [`vector` reference class](../standard-library/vector-bool-class.md#re |Name|Description| |-|-| -|`[allocator_type]`(#allocator_type)|A type that represents the `allocator` class for the vector object.| +|[`allocator_type`](#allocator_type)|A type that represents the `allocator` class for the vector object.| |[`const_iterator`](#const_iterator)|A type that provides a random-access iterator that can read a **`const`** element in a vector.| |[`const_pointer`](#const_pointer)|A type that provides a pointer to a **`const`** element in a vector.| |[`const_reference`](#const_reference)|A type that provides a reference to a **`const`** element stored in a vector. It's used for reading and doing **`const`** operations.| @@ -114,7 +114,7 @@ typedef Allocator allocator_type; ### Example -See the example for [get_allocator](#get_allocator) for an example that uses `allocator_type`. +See the example for [`get_allocator`](#get_allocator) for an example that uses `allocator_type`. ## `assign` @@ -152,7 +152,7 @@ First, `assign` erases any existing elements in a vector. Then, `assign` either ### Example ```cpp -/ vector_assign.cpp +// vector_assign.cpp // compile with: /EHsc #include #include @@ -169,33 +169,45 @@ int main() v1.push_back(50); cout << "v1 = "; - for (auto& v : v1){ + for (auto& v : v1) + { cout << v << " "; } cout << endl; v2.assign(v1.begin(), v1.end()); cout << "v2 = "; - for (auto& v : v2){ + for (auto& v : v2) + { cout << v << " "; } cout << endl; v3.assign(7, 4); cout << "v3 = "; - for (auto& v : v3){ + for (auto& v : v3) + { cout << v << " "; } cout << endl; v3.assign({ 5, 6, 7 }); - for (auto& v : v3){ + cout << "v3 = "; + for (auto& v : v3) + { cout << v << " "; } cout << endl; } ``` +```Output +v1 = 10 20 30 40 50 +v2 = 10 20 30 40 50 +v3 = 4 4 4 4 4 4 4 +v3 = 5 6 7 +``` + ## `at` Returns a reference to the element at a specified location in the vector. @@ -227,18 +239,18 @@ If the return value of `at` is assigned to a `const_reference`, the vector objec #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); + v1.push_back(10); + v1.push_back(20); - const int &i = v1.at( 0 ); - int &j = v1.at( 1 ); - cout << "The first element is " << i << endl; - cout << "The second element is " << j << endl; + const int &i = v1.at(0); + int &j = v1.at(1); + cout << "The first element is " << i << endl; + cout << "The second element is " << j << endl; } ``` @@ -275,22 +287,28 @@ When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-de #include #include -int main() { - using namespace std; - vector v1; +int main() +{ + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 11 ); + v1.push_back(10); + v1.push_back(11); - int& i = v1.back( ); - const int& ii = v1.front( ); + int& i = v1.back(); + const int& ii = v1.front(); - cout << "The last integer of v1 is " << i << endl; - i--; - cout << "The next-to-last integer of v1 is "<< ii << endl; + cout << "The last integer of v1 is " << i << endl; + i--; + cout << "The next-to-last integer of v1 is " << ii << endl; } ``` +```Output +The last integer of v1 is 11 +The next-to-last integer of v1 is 10 +``` + ## `begin` Returns a random-access iterator to the first element in the vector. @@ -378,18 +396,18 @@ The member function [`resize`](#resize) will be more efficient if sufficient mem #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 1 ); - cout << "The length of storage allocated is " - << v1.capacity( ) << "." << endl; + v1.push_back(1); + cout << "The length of storage allocated is " + << v1.capacity() << "." << endl; - v1.push_back( 2 ); - cout << "The length of storage allocated is now " - << v1.capacity( ) << "." << endl; + v1.push_back(2); + cout << "The length of storage allocated is now " + << v1.capacity() << "." << endl; } ``` @@ -419,8 +437,8 @@ You can use this member function in place of the `begin()` member function to gu ```cpp auto i1 = Container.begin(); // i1 is Container::iterator -auto i2 = Container.cbegin(); +auto i2 = Container.cbegin(); // i2 is Container::const_iterator ``` @@ -445,8 +463,8 @@ You can use this member function in place of the `end()` member function to guar ```cpp auto i1 = Container.end(); // i1 is Container::iterator -auto i2 = Container.cend(); +auto i2 = Container.cend(); // i2 is Container::const_iterator ``` @@ -468,18 +486,18 @@ void clear(); #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); - cout << "The size of v1 is " << v1.size( ) << endl; - v1.clear( ); - cout << "The size of v1 after clearing is " << v1.size( ) << endl; + cout << "The size of v1 is " << v1.size() << endl; + v1.clear(); + cout << "The size of v1 after clearing is " << v1.size() << endl; } ``` @@ -538,22 +556,22 @@ A type `const_reference` can't be used to modify the value of an element. #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); + v1.push_back(10); + v1.push_back(20); - const vector v2 = v1; - const int &i = v2.front( ); - const int &j = v2.back( ); - cout << "The first element is " << i << endl; - cout << "The second element is " << j << endl; + const vector v2 = v1; + const int& i = v2.front(); + const int& j = v2.back(); + cout << "The first element is " << i << endl; + cout << "The second element is " << j << endl; - // The following line would cause an error as v2 is const - // v2.push_back( 30 ); + // The following line would cause an error as v2 is const + // v2.push_back(30); } ``` @@ -602,22 +620,22 @@ With the return value of `crbegin`, the `vector` object can't be modified. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator v1_Iter; - vector ::const_reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::iterator v1_Iter; + vector::const_reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - v1_Iter = v1.begin( ); - cout << "The first element of vector is " + v1_Iter = v1.begin(); + cout << "The first element of vector is " << *v1_Iter << "." << endl; - v1_rIter = v1.crbegin( ); - cout << "The first element of the reversed vector is " + v1_rIter = v1.crbegin(); + cout << "The first element of the reversed vector is " << *v1_rIter << "." << endl; } ``` @@ -657,17 +675,17 @@ The value returned by `crend` shouldn't be dereferenced. Only use it for compari #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::const_reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::const_reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - for ( v1_rIter = v1.rbegin( ) ; v1_rIter != v1.rend( ) ; v1_rIter++ ) - cout << *v1_rIter << endl; + for (v1_rIter = v1.rbegin(); v1_rIter != v1.rend(); v1_rIter++) + cout << *v1_rIter << endl; } ``` @@ -755,31 +773,31 @@ An [iterator](#iterator) is more commonly used to access a vector element. #include #include -int main( ) +int main() { - using namespace std; + using namespace std; - vector c1; - vector ::iterator c1_Iter, c2_Iter; + vector c1; + vector::iterator c1_Iter, c2_Iter; - c1.push_back( 30 ); - c1.push_back( 20 ); - c1.push_back( 30 ); - c1.push_back( 10 ); - c1.push_back( 30 ); - c1.push_back( 20 ); + c1.push_back(30); + c1.push_back(20); + c1.push_back(30); + c1.push_back(10); + c1.push_back(30); + c1.push_back(20); - c1_Iter = c1.begin( ); - c2_Iter = c1.end( ); + c1_Iter = c1.begin(); + c2_Iter = c1.end(); - vector ::difference_type df_typ1, df_typ2, df_typ3; + vector::difference_type df_typ1, df_typ2, df_typ3; - df_typ1 = count( c1_Iter, c2_Iter, 10 ); - df_typ2 = count( c1_Iter, c2_Iter, 20 ); - df_typ3 = count( c1_Iter, c2_Iter, 30 ); - cout << "The number '10' is in c1 collection " << df_typ1 << " times.\n"; - cout << "The number '20' is in c1 collection " << df_typ2 << " times.\n"; - cout << "The number '30' is in c1 collection " << df_typ3 << " times.\n"; + df_typ1 = count(c1_Iter, c2_Iter, 10); + df_typ2 = count(c1_Iter, c2_Iter, 20); + df_typ3 = count(c1_Iter, c2_Iter, 30); + cout << "The number '10' is in c1 collection " << df_typ1 << " times.\n"; + cout << "The number '20' is in c1 collection " << df_typ2 << " times.\n"; + cout << "The number '30' is in c1 collection " << df_typ3 << " times.\n"; } ``` @@ -824,32 +842,32 @@ Any insertion operation can be expensive, see [`vector` class](../standard-libra #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator Iter; - - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); - - cout << "v1 =" ; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - -// initialize a vector of vectors by moving v1 - vector < vector > vv1; - - vv1.emplace( vv1.begin(), move( v1 ) ); - if ( vv1.size( ) != 0 && vv1[0].size( ) != 0 ) - { - cout << "vv1[0] ="; - for (Iter = vv1[0].begin( ); Iter != vv1[0].end( ); Iter++ ) - cout << " " << *Iter; - cout << endl; - } + using namespace std; + vector v1; + vector::iterator Iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + // initialize a vector of vectors by moving v1 + vector> vv1; + + vv1.emplace(vv1.begin(), move(v1)); + if (vv1.size() != 0 && vv1[0].size() != 0) + { + cout << "vv1[0] ="; + for (Iter = vv1[0].begin(); Iter != vv1[0].end(); Iter++) + cout << " " << *Iter; + cout << endl; + } } ``` @@ -876,15 +894,16 @@ Constructor arguments. The function infers which constructor overload to invoke ```cpp #include + struct obj { - obj(int, double) {} + obj(int, double) {} }; int main() { - std::vector v; - v.emplace_back(1, 3.14); // obj in created in place in the vector + std::vector v; + v.emplace_back(1, 3.14); // obj in created in place in the vector } ``` @@ -908,17 +927,17 @@ bool empty() const; #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); + v1.push_back(10); - if ( v1.empty( ) ) - cout << "The vector is empty." << endl; - else - cout << "The vector is not empty." << endl; + if (v1.empty()) + cout << "The vector is empty." << endl; + else + cout << "The vector is not empty." << endl; } ``` @@ -951,17 +970,18 @@ If the return value of `end` is assigned to a variable of type `const_iterator`, // compile with: /EHsc #include #include -int main( ) + +int main() { - using namespace std; - vector v1; - vector ::iterator v1_Iter; + using namespace std; + vector v1; + vector::iterator v1_Iter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - for ( v1_Iter = v1.begin( ) ; v1_Iter != v1.end( ) ; v1_Iter++ ) - cout << *v1_Iter << endl; + for (v1_Iter = v1.begin(); v1_Iter != v1.end(); v1_Iter++) + cout << *v1_Iter << endl; } ``` @@ -1006,34 +1026,34 @@ An iterator that designates the first element remaining beyond any elements remo #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator Iter; - - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); - v1.push_back( 40 ); - v1.push_back( 50 ); - - cout << "v1 =" ; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - v1.erase( v1.begin( ) ); - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - v1.erase( v1.begin( ) + 1, v1.begin( ) + 3 ); - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; + using namespace std; + vector v1; + vector::iterator Iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + v1.push_back(40); + v1.push_back(50); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + v1.erase(v1.begin()); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + v1.erase(v1.begin() + 1, v1.begin() + 3); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; } ``` @@ -1071,24 +1091,28 @@ When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-de #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 11 ); + v1.push_back(10); + v1.push_back(11); - int& i = v1.front( ); - const int& ii = v1.front( ); + int& i = v1.front(); - cout << "The first integer of v1 is "<< i << endl; - // by incrementing i, we move the front reference to the second element - i++; - cout << "Now, the first integer of v1 is "<< i << endl; + cout << "The first integer of v1 is " << i << endl; + // by incrementing i, we move the front reference to the second element + i++; + cout << "Now, the first integer of v1 is " << i << endl; } ``` +```Output +The first integer of v1 is 10 +Now, the first integer of v1 is 11 +``` + ## `get_allocator` Returns a copy of the allocator object used to construct the vector. @@ -1111,20 +1135,19 @@ Allocators for the vector class specify how the class manages storage. The defau // vector_get_allocator.cpp // compile with: /EHsc #include -#include -int main( ) +int main() { - using namespace std; - // The following lines declare objects that use the default allocator. - vector v1; - vector > v2 = vector >(allocator( )) ; + using namespace std; + // The following lines declare objects that use the default allocator. + vector v1; + vector> v2 = vector>(allocator()); - // v3 will use the same allocator class as v1 - vector v3( v1.get_allocator( ) ); + // v3 will use the same allocator class as v1 + vector v3(v1.get_allocator()); - vector::allocator_type xvec = v3.get_allocator( ); - // You can now call functions on the allocator class used by vec + vector::allocator_type xvec = v3.get_allocator(); + // You can now call functions on the allocator class used by vec } ``` @@ -1186,51 +1209,51 @@ As a precondition, *`first`* and *`last`* must not be iterators into the vector, #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator Iter; - - v1.push_back( 10 ); - v1.push_back( 20 ); - v1.push_back( 30 ); - - cout << "v1 =" ; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - v1.insert( v1.begin( ) + 1, 40 ); - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - v1.insert( v1.begin( ) + 2, 4, 50 ); - - cout << "v1 ="; - for ( Iter = v1.begin( ) ; Iter != v1.end( ) ; Iter++ ) - cout << " " << *Iter; - cout << endl; - - const auto v2 = v1; - v1.insert( v1.begin( )+1, v2.begin( )+2, v2.begin( )+4 ); - cout << "v1 ="; - for (Iter = v1.begin( ); Iter != v1.end( ); Iter++ ) - cout << " " << *Iter; - cout << endl; - -// initialize a vector of vectors by moving v1 - vector < vector > vv1; - - vv1.insert( vv1.begin(), move( v1 ) ); - if ( vv1.size( ) != 0 && vv1[0].size( ) != 0 ) - { - cout << "vv1[0] ="; - for (Iter = vv1[0].begin( ); Iter != vv1[0].end( ); Iter++ ) - cout << " " << *Iter; - cout << endl; - } + using namespace std; + vector v1; + vector::iterator Iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + v1.insert(v1.begin() + 1, 40); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + v1.insert(v1.begin() + 2, 4, 50); + + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + const auto v2 = v1; + v1.insert(v1.begin() + 1, v2.begin() + 2, v2.begin() + 4); + cout << "v1 ="; + for (Iter = v1.begin(); Iter != v1.end(); Iter++) + cout << " " << *Iter; + cout << endl; + + // initialize a vector of vectors by moving v1 + vector> vv1; + + vv1.insert(vv1.begin(), move(v1)); + if (vv1.size() != 0 && vv1[0].size() != 0) + { + cout << "vv1[0] ="; + for (Iter = vv1[0].begin(); Iter != vv1[0].end(); Iter++) + cout << " " << *Iter; + cout << endl; + } } ``` @@ -1278,17 +1301,21 @@ The maximum possible length of the vector. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::size_type i; + using namespace std; + vector v1; + vector::size_type i; - i = v1.max_size( ); - cout << "The maximum possible length of the vector is " << i << "." << endl; + i = v1.max_size(); + cout << "The maximum possible length of the vector is " << i << "." << endl; } ``` +```Output +The maximum possible length of the vector is 4611686018427387903. +``` + ## `operator[]` Returns a reference to the vector element at a specified position. @@ -1322,19 +1349,23 @@ When compiled by using [`_ITERATOR_DEBUG_LEVEL`](../standard-library/iterator-de #include #include -int main( ) +int main() { - using namespace std; - vector v1; + using namespace std; + vector v1; - v1.push_back( 10 ); - v1.push_back( 20 ); + v1.push_back(10); + v1.push_back(20); - int& i = v1[1]; - cout << "The second integer of v1 is " << i << endl; + int& i = v1[1]; + cout << "The second integer of v1 is " << i << endl; } ``` +```Output +The second integer of v1 is 20 +``` + ## `operator=` Replaces the elements of the vector with a copy of another vector. @@ -1362,39 +1393,45 @@ After erasing any existing elements in a `vector`, `operator=` either copies or #include #include -int main( ) +int main() { - using namespace std; - vector v1, v2, v3; - vector::iterator iter; - - v1.push_back(10); - v1.push_back(20); - v1.push_back(30); - v1.push_back(40); - v1.push_back(50); - - cout << "v1 = " ; - for (iter = v1.begin(); iter != v1.end(); iter++) - cout << *iter << " "; - cout << endl; - - v2 = v1; - cout << "v2 = "; - for (iter = v2.begin(); iter != v2.end(); iter++) - cout << *iter << " "; - cout << endl; - -// move v1 into v2 - v2.clear(); - v2 = move(v1); - cout << "v2 = "; - for (iter = v2.begin(); iter != v2.end(); iter++) - cout << *iter << " "; - cout << endl; + using namespace std; + vector v1, v2, v3; + vector::iterator iter; + + v1.push_back(10); + v1.push_back(20); + v1.push_back(30); + v1.push_back(40); + v1.push_back(50); + + cout << "v1 = "; + for (iter = v1.begin(); iter != v1.end(); iter++) + cout << *iter << " "; + cout << endl; + + v2 = v1; + cout << "v2 = "; + for (iter = v2.begin(); iter != v2.end(); iter++) + cout << *iter << " "; + cout << endl; + + // move v1 into v2 + v2.clear(); + v2 = move(v1); + cout << "v2 = "; + for (iter = v2.begin(); iter != v2.end(); iter++) + cout << *iter << " "; + cout << endl; } ``` +```Output +v1 = 10 20 30 40 50 +v2 = 10 20 30 40 50 +v2 = 10 20 30 40 50 +``` + ## `pointer` A type that provides a pointer to an element in a vector. @@ -1415,12 +1452,12 @@ A type **`pointer`** can be used to modify the value of an element. #include #include -int main( ) +int main() { using namespace std; vector v; - v.push_back( 11 ); - v.push_back( 22 ); + v.push_back(11); + v.push_back(22); vector::pointer ptr = &v[0]; cout << *ptr << endl; @@ -1473,14 +1510,19 @@ The value to assign to the element added to the end of the vector. using namespace std; -template void print_elem(const T& t) { +template +void print_elem(const T& t) +{ cout << "(" << t << ") "; } -template void print_collection(const T& t) { +template +void print_collection(const T& t) +{ cout << " " << t.size() << " elements: "; - for (const auto& p : t) { + for (const auto& p : t) + { print_elem(p); } cout << endl; @@ -1489,7 +1531,8 @@ template void print_collection(const T& t) { int main() { vector v; - for (int i = 0; i < 10; ++i) { + for (int i = 0; i < 10; ++i) + { v.push_back(10 + i); } @@ -1497,13 +1540,31 @@ int main() print_collection(v); // pop_back() until it's empty, printing the last element as we go - while (v.begin() != v.end()) { - cout << "v.back(): "; print_elem(v.back()); cout << endl; + while (v.begin() != v.end()) + { + cout << "v.back(): "; + print_elem(v.back()); + cout << endl; v.pop_back(); } } ``` +```Output +vector data: + 10 elements: (10) (11) (12) (13) (14) (15) (16) (17) (18) (19) +v.back(): (19) +v.back(): (18) +v.back(): (17) +v.back(): (16) +v.back(): (15) +v.back(): (14) +v.back(): (13) +v.back(): (12) +v.back(): (11) +v.back(): (10) +``` + ## `rbegin` Returns an iterator to the first element in a reversed vector. @@ -1529,22 +1590,22 @@ If the return value of `rbegin` is assigned to a `const_reverse_iterator`, the v #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::iterator v1_Iter; - vector ::reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::iterator v1_Iter; + vector::reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - v1_Iter = v1.begin( ); - cout << "The first element of vector is " + v1_Iter = v1.begin(); + cout << "The first element of vector is " << *v1_Iter << "." << endl; - v1_rIter = v1.rbegin( ); - cout << "The first element of the reversed vector is " + v1_rIter = v1.rbegin(); + cout << "The first element of the reversed vector is " << *v1_rIter << "." << endl; } ``` @@ -1597,17 +1658,17 @@ The value returned by `rend` shouldn't be dereferenced. Only use it for comparis #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::reverse_iterator v1_rIter; + using namespace std; + vector v1; + vector::reverse_iterator v1_rIter; - v1.push_back( 1 ); - v1.push_back( 2 ); + v1.push_back(1); + v1.push_back(2); - for ( v1_rIter = v1.rbegin( ) ; v1_rIter != v1.rend( ) ; v1_rIter++ ) - cout << *v1_rIter << endl; + for (v1_rIter = v1.rbegin(); v1_rIter != v1.rend(); v1_rIter++) + cout << *v1_rIter << endl; } ``` @@ -1637,18 +1698,17 @@ The minimum length of storage to be allocated for the vector. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - //vector ::iterator Iter; - - v1.push_back( 1 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; - v1.reserve( 20 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; + using namespace std; + vector v1; + + v1.push_back(1); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; + v1.reserve(20); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; } ``` @@ -1721,16 +1781,20 @@ If the container's size is less than the requested size, *`new_size`*, `resize` using namespace std; -template void print(const string& s, const C& c) { +template +void print(const string& s, const C& c) +{ cout << s; - for (const auto& e : c) { + for (const auto& e : c) + { cout << e << " "; } cout << endl; } -void printvstats(const vector& v) { +void printvstats(const vector& v) +{ cout << " the vector's size is: " << v.size() << endl; cout << " the vector's capacity is: " << v.capacity() << endl; cout << " the vector's maximum size is: " << v.max_size() << endl; @@ -1742,7 +1806,7 @@ int main() vector v; // Show statistics about vector. - cout << endl << "After declaring an empty vector:" << endl; + cout << "After declaring an empty vector:" << endl; printvstats(v); print(" the vector's contents: ", v); @@ -1752,7 +1816,8 @@ int main() printvstats(v); print(" the vector's contents: ", v); - for (int i = 1; i < 10; ++i) { + for (int i = 1; i < 10; ++i) + { v.push_back(i); } cout << endl << "After adding 10 elements:" << endl; @@ -1786,6 +1851,54 @@ int main() } ``` +```Output +After declaring an empty vector: + the vector's size is: 0 + the vector's capacity is: 0 + the vector's maximum size is: 4611686018427387903 + the vector's contents: + +After adding an element: + the vector's size is: 1 + the vector's capacity is: 1 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 + +After adding 10 elements: + the vector's size is: 10 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 6 7 8 9 + +After resizing to 6 elements without an initialization value: + the vector's size is: 6 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 + +After resizing to 9 elements with an initialization value of 999: + the vector's size is: 9 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 999 999 999 + +After resizing to 12 elements without an initialization value: + the vector's size is: 12 + the vector's capacity is: 13 + the vector's maximum size is: 4611686018427387903 + the vector's contents: -1 1 2 3 4 5 999 999 999 0 0 0 + +After vector::reserve(1000): + the vector's size is: 12 + the vector's capacity is: 1000 + the vector's maximum size is: 4611686018427387903 + +After vector::resize(2000): + the vector's size is: 2000 + the vector's capacity is: 2000 + the vector's maximum size is: 4611686018427387903 +``` + ## `reverse_iterator` A type that provides a random-access iterator that can read or modify any element in a reversed vector. @@ -1818,21 +1931,20 @@ void shrink_to_fit(); #include #include -int main( ) +int main() { - using namespace std; - vector v1; - //vector ::iterator Iter; - - v1.push_back( 1 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; - v1.reserve( 20 ); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; - v1.shrink_to_fit(); - cout << "Current capacity of v1 = " - << v1.capacity( ) << endl; + using namespace std; + vector v1; + + v1.push_back(1); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; + v1.reserve(20); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; + v1.shrink_to_fit(); + cout << "Current capacity of v1 = " + << v1.capacity() << endl; } ``` @@ -1862,19 +1974,19 @@ The current length of the vector. #include #include -int main( ) +int main() { - using namespace std; - vector v1; - vector ::size_type i; + using namespace std; + vector v1; + vector::size_type i; - v1.push_back( 1 ); - i = v1.size( ); - cout << "Vector length is " << i << "." << endl; + v1.push_back(1); + i = v1.size(); + cout << "Vector length is " << i << "." << endl; - v1.push_back( 2 ); - i = v1.size( ); - cout << "Vector length is now " << i << "." << endl; + v1.push_back(2); + i = v1.size(); + cout << "Vector length is now " << i << "." << endl; } ``` @@ -1924,26 +2036,26 @@ A vector whose elements are to be exchanged with the elements in the vector *`ri #include #include -int main( ) +int main() { - using namespace std; - vector v1, v2; + using namespace std; + vector v1, v2; - v1.push_back( 1 ); - v1.push_back( 2 ); - v1.push_back( 3 ); + v1.push_back(1); + v1.push_back(2); + v1.push_back(3); - v2.push_back( 10 ); - v2.push_back( 20 ); + v2.push_back(10); + v2.push_back(20); - cout << "The number of elements in v1 = " << v1.size( ) << endl; - cout << "The number of elements in v2 = " << v2.size( ) << endl; - cout << endl; + cout << "The number of elements in v1 = " << v1.size() << endl; + cout << "The number of elements in v2 = " << v2.size() << endl; + cout << endl; - v1.swap( v2 ); + v1.swap(v2); - cout << "The number of elements in v1 = " << v1.size( ) << endl; - cout << "The number of elements in v2 = " << v2.size( ) << endl; + cout << "The number of elements in v1 = " << v1.size() << endl; + cout << "The number of elements in v2 = " << v2.size() << endl; } ``` @@ -1975,12 +2087,12 @@ typedef typename Allocator::value_type value_type; #include #include -int main( ) +int main() { - using namespace std; - vector::value_type AnInt; - AnInt = 44; - cout << AnInt << endl; + using namespace std; + vector::value_type AnInt; + AnInt = 44; + cout << AnInt << endl; } ``` @@ -2061,88 +2173,106 @@ The ninth and tenth constructors copy the range [`first`, `last`) of a vector. int main() { using namespace std; - vector ::iterator v1_Iter, v2_Iter, v3_Iter, v4_Iter, v5_Iter, v6_Iter; + vector::iterator v1_Iter, v2_Iter, v3_Iter, v4_Iter, v5_Iter, v6_Iter; // Create an empty vector v0 - vector v0; + vector v0; // Create a vector v1 with 3 elements of default value 0 - vector v1(3); + vector v1(3); // Create a vector v2 with 5 elements of value 2 - vector v2(5, 2); + vector v2(5, 2); // Create a vector v3 with 3 elements of value 1 and with the allocator // of vector v2 - vector v3(3, 1, v2.get_allocator()); + vector v3(3, 1, v2.get_allocator()); // Create a copy, vector v4, of vector v2 - vector v4(v2); + vector v4(v2); // Create a new temporary vector for demonstrating copying ranges - vector v5(5); - for (auto i : v5) { + vector v5(5); + for (auto i : v5) + { v5[i] = i; } // Create a vector v6 by copying the range v5[ first, last) - vector v6(v5.begin() + 1, v5.begin() + 3); + vector v6(v5.begin() + 1, v5.begin() + 3); cout << "v1 ="; - for (auto& v : v1){ + for (auto& v : v1) + { cout << " " << v; } cout << endl; cout << "v2 ="; - for (auto& v : v2){ + for (auto& v : v2) + { cout << " " << v; } cout << endl; cout << "v3 ="; - for (auto& v : v3){ + for (auto& v : v3) + { cout << " " << v; } cout << endl; + cout << "v4 ="; - for (auto& v : v4){ + for (auto& v : v4) + { cout << " " << v; } cout << endl; cout << "v5 ="; - for (auto& v : v5){ + for (auto& v : v5) + { cout << " " << v; } cout << endl; cout << "v6 ="; - for (auto& v : v6){ + for (auto& v : v6) + { cout << " " << v; } cout << endl; // Move vector v2 to vector v7 - vector v7(move(v2)); - vector ::iterator v7_Iter; + vector v7(move(v2)); + vector::iterator v7_Iter; cout << "v7 ="; - for (auto& v : v7){ + for (auto& v : v7) + { cout << " " << v; } cout << endl; + cout << "v8 ="; vector v8{ { 1, 2, 3, 4 } }; - for (auto& v : v8){ - cout << " " << v ; + for (auto& v : v8) + { + cout << " " << v; } cout << endl; } ``` ```Output -v1 = 0 0 0v2 = 2 2 2 2 2v3 = 1 1 1v4 = 2 2 2 2 2v5 = 0 1 2 3 4v6 = 1 2v7 = 2 2 2 2 21 2 3 4 +v1 = 0 0 0 +v2 = 2 2 2 2 2 +v3 = 1 1 1 +v4 = 2 2 2 2 2 +v5 = 0 0 0 0 0 +v6 = 0 0 +v7 = 2 2 2 2 2 +v8 = 1 2 3 4 ``` ## See also diff --git a/docs/standard-library/vector.md b/docs/standard-library/vector.md index 53f1298f8f2..ab97e690485 100644 --- a/docs/standard-library/vector.md +++ b/docs/standard-library/vector.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: ["vector header"] --- @@ -14,7 +14,7 @@ The `vector` is a container that organizes elements of a given type in a linear > [!NOTE] > The `` library also uses the `#include ` statement. -For more information about the class `vector`, see [`vector` Class](../standard-library/vector-class.md). For information about the specialization `vector`, see [`vector\` Class](../standard-library/vector-bool-class.md). +For more information about the class `vector`, see [`vector` Class](../standard-library/vector-class.md). For information about the specialization `vector`, see [`vector` class](../standard-library/vector-bool-class.md). ## Syntax @@ -87,9 +87,9 @@ The second (right) vector in a compare operation. |Name|Description| |-|-| -|[`operator! =`](../standard-library/vector-operators.md#op_neq)|Tests if the `vector` object on the left side of the operator is not equal to the `vector` object on the right side.| +|[`operator! =`](../standard-library/vector-operators.md#op_neq)|Tests if the `vector` object on the left side of the operator isn't equal to the `vector` object on the right side.| |[`operator<`](../standard-library/vector-operators.md#op_lt)|Tests if the `vector` object on the left side of the operator is less than the `vector` object on the right side.| -|[`operator\<=`](../standard-library/vector-operators.md#op_gt_eq)|Tests if the `vector` object on the left side of the operator is less than or equal to the `vector` object on the right side.| +|[`operator<=`](../standard-library/vector-operators.md#op_lt_eq)|Tests if the `vector` object on the left side of the operator is less than or equal to the `vector` object on the right side.| |[`operator==`](../standard-library/vector-operators.md#op_eq_eq)|Tests if the `vector` object on the left side of the operator is equal to the `vector` object on the right side.| |[`operator>`](../standard-library/vector-operators.md#op_gt)|Tests if the `vector` object on the left side of the operator is greater than the `vector` object on the right side.| |[`operator>=`](../standard-library/vector-operators.md#op_gt_eq)|Tests if the `vector` object on the left side of the operator is greater than or equal to the `vector` object on the right side.| @@ -98,14 +98,14 @@ The second (right) vector in a compare operation. |Name|Description| |-|-| -|[`vector Class`](../standard-library/vector-class.md)|A class template of sequence containers that arrange elements of a given type in a linear arrangement and allow fast random access to any element.| +|[`vector` class](../standard-library/vector-class.md)|A class template of sequence containers that arrange elements of a given type in a linear arrangement and allow fast random access to any element.| ### Specializations |Name|Description| |-|-| |hash|Returns a hash of the vector.| -|[`vector\ Class`](../standard-library/vector-bool-class.md)|A full specialization of the class template vector for elements of type **`bool`** with an allocator for the underlying type used by the specialization.| +|[`vector` class](../standard-library/vector-bool-class.md)|A full specialization of the class template vector for elements of type **`bool`** with an allocator for the underlying type used by the specialization.| ## Requirements diff --git a/docs/standard-library/vectorized-stl-algorithms.md b/docs/standard-library/vectorized-stl-algorithms.md new file mode 100644 index 00000000000..13cad087a01 --- /dev/null +++ b/docs/standard-library/vectorized-stl-algorithms.md @@ -0,0 +1,81 @@ +--- +title: "Vectorized MSVC STL Algorithms" +description: "Learn more about: Vectorized STL Algorithms" +ms.date: 10/03/2025 +f1_keywords: ["_USE_STD_VECTOR_ALGORITHMS", "_USE_STD_VECTOR_FLOATING_ALGORITHMS"] +helpviewer_keywords: ["_USE_STD_VECTOR_ALGORITHMS", "_USE_STD_VECTOR_FLOATING_ALGORITHMS", "Vector Algorithms", "Vectorization", "SIMD"] +--- +# Vectorized MSVC STL Algorithms + +Under specific conditions, algorithms in the MSVC Standard Template Library (STL) can process multiple elements simultaneously on a single CPU core, rather than handling each element individually. This optimization uses single instruction, multiple data (SIMD) instructions provided by the CPU, a technique called vectorization. When this optimization isn't applied, the implementation is referred to as scalar. + +The conditions required for vectorization are: + - The container or range must be contiguous. Examples include `array`, `vector`, and `basic_string`. Types like `span` and `basic_string_view` provide contiguous ranges. Built-in arrays also form contiguous ranges. Containers like `list` and `map` aren't contiguous. + - The target platform must support the necessary SIMD instructions to implement the algorithm for the element types. This is typically true for arithmetic types and simple operations. + - One of these conditions must be met: + - The compiler can emit vectorized machine code for an implementation written as scalar code (auto-vectorization). + - The algorithm's implementation explicitly uses vectorized code (manual vectorization). + +## Auto-vectorization in the MSVC STL + +For more information about automatic vectorization, see [Auto-Vectorizer](../parallel/auto-parallelization-and-auto-vectorization.md#auto-vectorizer) and the discussion in that article about the [`/arch`](../build/reference/arch-minimum-cpu-architecture.md) switch. This applies to the STL implementation code the same way it applies to user code. + +Algorithms like `transform`, `reduce`, and `accumulate` benefit heavily from auto-vectorization. + +## Manual vectorization in the MSVC STL + +Certain algorithms for x64 and x86 include manual vectorization. This implementation is separately compiled and relies on runtime CPU dispatch, so it applies only to suitable CPUs. + +Manually vectorized algorithms use template metaprogramming to detect if the element type is suitable for vectorization. As a result, they're only vectorized for simple types such as standard integer types. + +Programs either benefit in performance from manual vectorization or remain unaffected by it. Disable manual vectorization by defining `_USE_STD_VECTOR_ALGORITHMS=0` in your project. Manually vectorized algorithms are enabled by default on x64 and x86 because `_USE_STD_VECTOR_ALGORITHMS` defaults to 1 on those platforms. + +Assign the same value to `_USE_STD_VECTOR_ALGORITHMS` for all linked translation units that use algorithms. Configure it in the project properties instead of in the source code for consistency. For more information about how to configure it, see [/D (Preprocessor Definitions)](../build/reference/d-preprocessor-definitions.md). + + +The `_USE_STD_VECTOR_ALGORITHMS` macro controls the behavior of these manually vectorized algorithms: + - `contains`, `contains_subrange` + - `find`, `find_last`, `find_end`, `find_first_of`, `adjacent_find` + - `count` + - `mismatch` + - `search`, `search_n` + - `swap_ranges` + - `replace` + - `remove`, `remove_copy` + - `unique`, `unique_copy` + - `reverse`, `reverse_copy` + - `rotate` + - `is_sorted`, `is_sorted_until` + - `lexicographical_compare`, `lexicographical_compare_three_way` + - `max`, `min`, `minmax` + - `max_element`, `min_element`, `minmax_element` + +The `_USE_STD_VECTOR_ALGORITHMS` macro also controls the manual vectorization of: + + - `basic_string` and `basic_string_view` members: + - `find` + - `rfind` + - `find_first_of`, `find_first_not_of` + - `find_last_of`, `find_last_not_of` + - `bitset` constructors from string and `bitset::to_string` + +## Manually vectorized algorithms for floating point types + +Vectorization of floating-point types involves specific considerations: + - Vectorization might reorder operations, which can affect the precision of floating-point results. + - Floating-point types might contain `NaN` values, which don't behave transitively in comparisons. + - Floating-point operations might raise exceptions. + +The STL addresses the first two considerations safely. Only `max_element`, `min_element`, `minmax_element`, `max`, `min`, `minmax`, `is_sorted`, and `is_sorted_until` are manually vectorized. These algorithms: +- Don’t compute new floating-point values. Instead, they compare existing values to ensure that differences in operation order don't impact precision. +- Because these are sorting algorithms, `NaN` values aren't allowed as inputs. + +Use `_USE_STD_VECTOR_FLOATING_ALGORITHMS` to control the use of these vectorized algorithms for floating-point types. Set it to 0 to disable vectorization. `_USE_STD_VECTOR_FLOATING_ALGORITHMS` doesn't affect anything if `_USE_STD_VECTOR_ALGORITHMS` is set to 0. + +The `_USE_STD_VECTOR_FLOATING_ALGORITHMS` macro defaults to 0 when [`/fp:except`](../build/reference/fp-specify-floating-point-behavior.md#except) is set. + +Assign the same value to `_USE_STD_VECTOR_FLOATING_ALGORITHMS` for all linked translation units that use algorithms. Configure it in the project properties instead of in the source code for consistency. For more information about how to configure it, see [/D (Preprocessor Definitions)](../build/reference/d-preprocessor-definitions.md). + +## See also + +[Auto-Vectorizer](../parallel/auto-parallelization-and-auto-vectorization.md#auto-vectorizer) diff --git a/docs/standard-library/view-classes.md b/docs/standard-library/view-classes.md new file mode 100644 index 00000000000..9d03ecae519 --- /dev/null +++ b/docs/standard-library/view-classes.md @@ -0,0 +1,169 @@ +--- +title: "View classes" +description: "Learn more about the ranges view classes, which allow you to inexpensively transform ranges." +ms.date: 12/20/2022 +f1_keywords: ["RANGES/std::ranges::views", "RANGES/std::views"] +helpviewer_keywords: ["RANGES/VIEWS/std", "VIEWS/std"] +--- +# `` view classes + +A *view* is a lightweight range that refers to elements that it doesn't own (except [`owning_view`](owning-view-class.md)). A view is typically based on another range and provides a different way of looking at it, whether by transforming or filtering it. For example, [`std::views::filter`](filter-view-class.md) is a view that uses the criteria that you specify to select elements from another range. + +When you access the elements in a view, it's done "lazily" so that work is done only when you get an element. This makes it possible to combine, or *compose*, views without a performance penalty. + +For example, you could create a view that provides only the even elements from a range and then transform them by squaring them. The work to do the filtering and transformation is done only for the elements that you access, and only when you access them. + +A view can be copied, assigned, and destroyed in constant time no matter how many elements it contains. This is because a view doesn't own the elements that it refers to, so it doesn't need to make a copy. This is why you can compose views without a performance penalty. + +You typically create a view by using a [range adaptor](range-adaptors.md). Range adaptors are the intended way to create a view, are easier to use than instantiating the view classes directly, and are sometimes more efficient than instantiating the view classes directly. The view classes are exposed directly in case you need to create your own custom view type based on an existing view type. + +Here's a brief example of creating a view of the squares of the elements that are divisible by three in a vector: + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector input = {0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10}; + auto divisible_by_three = [](const int n) {return n % 3 == 0;}; + auto square = [](const int n) {return n * n;}; + + auto x = input + | std::views::filter(divisible_by_three) + | std::views::transform(square); + + for (int i : x) + { + std::cout << i << ' '; // 0 9 36 81 + } +} +``` + +```output +0 9 36 81 +``` + +Using a view after the range that it's based on is modified can lead to undefined behavior. For example, a [`reverse_view`](reverse-view-class.md) based on a vector shouldn't be reused if you add or remove elements from the underlying vector. Modifying the underlying vector invalidates the container's `end` iterator--including the copy of the iterator that the view might have made. + +Because views are cheap to create, you should generally re-create a view if you modify the underlying range. The following example demonstrates how to store a view pipeline in a variable so that you can reuse it. + +```cpp +// requires /std:c++20 or later +#include +#include +#include +#include +#include +#include + +template +void show(std::string_view msg, rangeType r) +{ + std::cout << msg; + std::ranges::for_each(r, + [](auto e) + { + std::cout << e << ' '; + }); + std::cout << '\n'; +} + +int main() +{ + std::vector v{ 1, 2, 3, 4 }; + show("v: ", v); + + // You can save a view pipeline + auto rev3 = std::views::take(3) | std::views::reverse; + + show("v | rev3: ", v | rev3); // 3 2 1 + + v.insert(v.begin(), 0); // v = 0 1 2 3 4 + show("v: ", v); + + // Because modifying the vector invalidates its iterators, rebuild the view. + // We are reusing the view pipeline we saved earlier + show("v | rev3(v): ", rev3(v)); +} +``` + +```output +v: 1 2 3 4 +v | rev3: 3 2 1 +v: 0 1 2 3 4 +v | rev3(v): 2 1 0 +``` + +The following view classes are defined in the `std::ranges` namespace. + +| View | Description | +|--|--| +| [`basic_istream_view`](basic-istream-view-class.md)C++20 | A view of successive elements from an input stream. Specializations include `istream_view` and `wistream_view`. | +| [`common_view`](common-view-class.md)C++20 | Adapts a view that has different iterator/sentinel types into a view with the same iterator/sentinel types. | +| [`drop_view`](drop-view-class.md)C++20 | Created from another view, skipping the first `count` elements. | +| [`drop_while_view`](drop-while-view-class.md)C++20 | Created from another view, skipping leading elements as long as a predicate holds. | +| [`elements_view`](elements-view-class.md)C++20 | A view over the selected index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view that consists of all the `string` elements from each tuple. | +| [`empty_view`](empty-view-class.md)C++20 | A view with no elements. | +| [`filter_view`](filter-view-class.md)C++20 | Filters out elements of a range that don't match a predicate. | +| [`iota_view`](iota-view-class.md)C++20 | A generated view that contains a sequence of incrementing values. | +| [`join_view`](join-view-class.md)C++20 | Combines all the elements of multiple ranges into a single view. | +| [`keys_view`](keys-view-class.md)C++20 | A view over the first index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view that consists of the `string` elements from each tuple. | +| [`lazy_split_view`](lazy-split-view-class.md)C++20 | Splits a view into subranges based on a delimiter. | +| [`owning_view`](owning-view-class.md)C++20 | Takes ownership of the elements from another range. | +| [`ref_view`](ref-view-class.md)C++20 | A view that references the elements that belong to another range. | +| [`reverse_view`](reverse-view-class.md)C++20 | Presents the elements of a range in reverse order. | +| [`single_view`](single-view-class.md)C++20 | A view that contains only one element. | +| [`split_view`](split-view-class.md)C++20 | Splits a view into subranges based on a delimiter. | +| [`subrange`](subrange-class.md)C++20 | A view of part of the elements of a range, as defined by a begin iterator and a sentinel. | +| [`take_view`](take-view-class.md)C++20 | Contains the specified number of elements taken from the front of a range. | +| [`take_while_view`](take-while-view-class.md)C++20 | Contains the leading elements of a range that match the given predicate. | +| [`transform_view`](transform-view-class.md)C++20 | A view of an underlying sequence after a transformation function is applied to each element. | +| [`values_view`](values-view-class.md)C++20 | A view over the second index into each tuple-like value in a collection. For example, given a range of `std::tuple` values, create a view that consists of the `int` elements from each tuple. | + +Many of these classes have corresponding [range adaptors](range-adaptors.md) in the `std::views` namespace that creates instances of them. Prefer using an adaptor to create a view instead of creating view classes directly. The range adaptors are the intended way to create views, are easier to use, and in some cases are more efficient. + +## View classes characteristics + +Each view class topic has a **Characteristics** section after the syntax section. The **Characteristics** section has the following entries: + +* **Range adaptor**: A link to the range adaptor that creates the view. You typically use a range adaptor to create a view rather than create a view class directly, so it's listed here for convenience. +* **Underlying range**: Views have different iterator requirements for the kind of underlying range that they can use. See [ranges iterator hierarchy](#ranges-iterator-hierarchy) for more information about the kinds of iterators. +* **View iterator category**: The iterator category of the view. When a view adapts a range, the iterator type for the view is typically the same as the iterator type of the underlying range. However, it might be different for some views. For example, `reverse_view` has a [`bidirectional_iterator`](iterator-concepts.md#bidirectional_iterator), even if the underlying range has a [`random_access_iterator`](iterator-concepts.md#random_access_iterator). +* **Element type**: The type of the elements that the view's iterator returns. +* **Sized**: Whether the view can return the number of elements that it refers to. Not all views can. +* **Common range**: Specifies whether the view is a [`common_range`](range-concepts.md#common_range), which means that the begin iterator and sentinel types are the same. Common ranges are useful for pre-range code that works with iterator pairs. An example is iterator pair constructors for a sequence container, like `vector(ranges::begin(x), ranges::end(x))`. +* **Borrowed range**: Specifies whether the view is a borrowed range. `borrowed_range` means you can use iterators for `T` after `T` is destroyed. + + No standard container is a borrowed range, because destroying the container frees the elements and invalidates any iterators. In that case, we say that the iterators are left "dangling" after destruction. + + For example, `std::ranges::find()` typically returns an iterator to the found element in the range argument. If the range argument is a temporary (rvalue) container, it's a mistake to store the returned iterator and use it later because it's "dangling." + + Range algorithms that return iterators (or subranges) do so only when their arguments are lvalues (non-temporaries) or borrowed ranges. Otherwise, they return a `std::dangling` object, which provides a hint in error messages about what went wrong if you tried to use it like an iterator. +* **Is `const` iterable**: Indicates whether you can iterate over a `const` instance of the view. Not all `const` views can be iterated. If a view isn't `const` iterable, you can't iterate with `for (const auto& element : as_const(theView))` or pass it to a function that takes a `const` reference to the view and then tries to iterate over it. + +### Ranges iterator hierarchy + +In the **Characteristics** section of each view class topic, the iterator category in **Underlying range** and **View iterator category** refers to the kind of iterator that the range/view supports. There are six categories of Ranges iterators, which are identified by C++20 concepts. The hierarchy of range iterators, in increasing order of capability, is: + +| Range iterator concept | Description | +|--|--| +| [`output_range`](range-concepts.md#output_range) | Write-only, only moves forward; single-pass. | +| [`input_range`](range-concepts.md#input_range) | Read-only, only moves forward; single-pass. | +| [`forward_range`](range-concepts.md#forward_range) | Only moves forward; multi-pass. | +| [`bidirectional_range`](range-concepts.md#bidirectional_range) | Can move forward and backward; multi-pass. | +| [`random_access_range`](range-concepts.md#random_access_range) | Can access the collection with an index; multi-pass. | +| [`contiguous_range`](range-concepts.md#contiguous_range) | Can access the collection with an index, and elements are stored contiguously in memory. | + +Generally speaking, an iterator has the capability of the iterators that precede it in the table. For example, [`bidirectional_range`](range-concepts.md#bidirectional_range) has the capabilities of [`forward_range`](range-concepts.md#forward_range), but not vice versa. Except `input_range`, which doesn't have the capability of `output_range` because you can't write to an `input_range`. + +The statement "requires `input_range` or higher" means that the view can be used with an `input_range`, `forward_range`, `bidirectional_range`, `random_access_range`, or `contiguous_range` iterator, because they're all as capable as `input_range`. + +The ranges iterator hierarchy is directly related to the iterator hierarchy. For more information, see [Iterator concepts](iterator-concepts.md). + +## See also + +[``](ranges.md)\ +[Range adaptors](range-adaptors.md) diff --git a/docs/standard-library/view-interface.md b/docs/standard-library/view-interface.md new file mode 100644 index 00000000000..2b77da6fd37 --- /dev/null +++ b/docs/standard-library/view-interface.md @@ -0,0 +1,275 @@ +--- +title: "view_interface class (C++ Standard Library)" +description: "API reference for the Standard Template Library (STL) view_interface class, which is the base class for the ranges view classes." +ms.date: 10/07/2022 +f1_keywords: ["ranges/std::view_interface::back", "ranges/std::view_interface::data","ranges/std::view_interface::empty", "ranges/std::view_interface::front", "ranges/std::view_interface::size", "ranges/std::view_interface::operator[]", "ranges/std::view_interface::operator bool"] +helpviewer_keywords: ["std::ranges::view_interface [C++]", "std::ranges::view_interface [C++], back", "std::ranges::view_interface [C++], data", "std::ranges::view_interface [C++], empty", "std::ranges::view_interface [C++], front", "std::ranges::view_interface [C++], size", "std::ranges::view_interface [C++], operator[]", "std::ranges::view_interface [C++], operator bool"] +dev_langs: ["C++"] +--- +# `view_interface` class (C++ Standard Library) + +The base class for the [view classes](view-classes.md) in the `std::ranges` namespace. This class implements some of the interface for derived view types. Use this as the base class for your own view types to reduce the boilerplate you need to write. + +## Syntax + +```cpp +template + requires std::is_class_v && + std::same_as> +class view_interface; +``` + +### Template parameters + +*`Derived`*\ + The type of the class that is deriving from this base class. + +## Members + +| **Member functions** | **Description** | +|--|--| +| [`back`](#back)C++20 | Get the last element in the derived view. | +| [`data`](#data)C++20 | Get a pointer to the first element in the derived view. | +| [`empty`](#empty)C++20 | Test whether the derived view is empty. | +| [`front`](#front)C++20 | Get the first element in the derived view. | +| [`size`](#size)C++20 | Get the number of elements in the derived view. | +| **Operators** | **Description** | +| [`operator[]`](#op_at)C++20 | Get the element at the specified position. | +| [`operator bool`](#op_bool)C++20 | Test whether the derived view isn't empty. | + +## Requirements + +**Header:** `` (since C++20) + +**Namespace:** `std::ranges` + +**Compiler Option:** [`/std:c++20`](../build/reference/std-specify-language-standard-version.md) or later is required. + +## `back` + +Get the last element in the derived view. + +```cpp +constexpr auto back() + requires ranges::bidirectional_range && + ranges::common_range; + +constexpr auto back() const + requires ranges::bidirectional_range && + ranges::common_range; +``` + +### Parameters + +None. + +### Return value + +The last element in the derived view. + +### Remarks + +The derived view must satisfy [`bidirectional_range`](range-concepts.md#bidirectional_range) and [`common_range`](range-concepts.md#common_range).\ +The behavior of `back()` and `front()` are undefined for any empty view. + +## `data` + +Get a pointer to the first element in the derived view. + +```cpp +constexpr auto data() + requires std::contiguous_iterator>; +constexpr auto data() const + requires ranges::range && + std::contiguous_iterator>; +``` + +### Parameters + +None. + +### Return value + +A pointer to the first element in the derived view. + +### Remarks + +The iterator for the derived view must satisfy [`contiguous_iterator`](iterator-concepts.md#contiguous_iterator). + +## `empty` + +Test whether the derived view is empty. + +```cpp +1) constexpr bool empty() requires ranges::forward_range; +2) constexpr bool empty() const requires ranges::forward_range; +``` + +### Parameters + +None. + +### Return value + +Returns `true` if the derived view has no elements. Otherwise, returns `false`. + +### Remarks + +The derived view must satisfy `std::ranges::forward_range`. + +## `front` + +Get the first element in the derived view. + +```cpp +constexpr auto front() + requires ranges::forward_range; +constexpr auto front() const + requires ranges::forward_range; +``` + +### Parameters + +None. + +### Return value + +The last element in the derived view. + +### Remarks + +The derived view must satisfy [`forward_range`](range-concepts.md#forward_range).\ +The behavior of `front()` is undefined for `std::ranges::empty_view`. + +## `size` + +Get the number of elements in the derived view. + +```cpp +constexpr auto size() requires ranges::forward_range && + std::sized_sentinel_for, + ranges::iterator_t>; +constexpr auto size() const requires ranges::forward_range && + std::sized_sentinel_for, + ranges::iterator_t>; +``` + +### Parameters + +None. + +### Return value + +The number of elements in the derived view. + +### Remarks + +The iterator for the derived view must satisfy [`sized_sentinel_for`](iterator-concepts.md#sized_sentinel_for). + +## `operator[]` + +Get the element at the specified position. + +```cpp +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos); + +template +constexpr decltype(auto) operator[](ranges::range_difference_t pos) const; +``` + +### Parameters + +*`pos`*\ +The position, relative to the beginning iterator, of the element to return. + +### Return value + +The element at the specified position relative to the beginning iterator. + +### Remarks + +The derived view must satisfy [`random_access_range`](range-concepts.md#random_access_range).\ +The behavior of this operator is undefined for `std::ranges::empty_view`. + +### Example: `operator[]` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{1, 2, 3, 4, 5}; + std::ranges::drop_view dv = std::views::drop(v, 2); + + for (auto e : dv) + { + std::cout << e << ' '; // 3 4 5 + } + + std::cout << "\ndv[1] = " << dv[1]; +} +``` + +```output +3 4 5 +dv[1] = 4 +``` + +## `view_interface::operator bool` + +Test whether the derived view isn't empty. + +```cpp +explicit constexpr operator bool(); +explicit constexpr operator bool() const; +``` + +### Parameters + +None. + +### Return value + +Returns `false` if the derived view has no elements (the view is empty). Otherwise, returns `true` (the view isn't empty). + +### Remarks + +The iterator for the derived view must satisfy `std::ranges::forward_iterator`.\ +This operator is equivalent to `!empty()`. This makes it convenient to write `if (someRange) {...}` to test whether there's something in the range to operate on.\ +The behavior of this operator is undefined for `std::ranges::empty_view`. + +### Example: `operator bool` + +```cpp +// requires /std:c++20 or later +#include +#include +#include + +int main() +{ + std::vector v{1, 2, 3, 4, 5}; + std::ranges::filter_view fv = std::views::filter(v, [](int e) { return e > 3; }); + + bool isNotEmpty = static_cast(fv); + std::cout << "Has elements greater than 3: " << std::boolalpha << isNotEmpty << '\n' >>; +} +``` + +```output +Has elements greater than 3: true +``` + +## See also + +[``](ranges.md)\ +[`ranges::begin()`](range-functions.md#begin)\ +[`ranges::data()`](range-functions.md#data)\ +[`ranges::end()`](range-functions.md#end)\ +[`ranges::empty()`](range-functions.md#empty)\ +[`ranges::size()`](range-functions.md#size)\ +[View classes](view-classes.md) diff --git a/docs/standard-library/wbuffer-convert-class.md b/docs/standard-library/wbuffer-convert-class.md index b70a6464113..060e7db84f9 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 14a8ecbe02d..8088e3b8b66 100644 --- a/docs/standard-library/weekday-class.md +++ b/docs/standard-library/weekday-class.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: weekday Class" title: "weekday class" -ms.date: "6/25/2021" +description: "Learn more about: weekday Class" +ms.date: 6/25/2021 f1_keywords: ["chrono/std::chrono::weekday", "chrono/std::chrono::weekday::January", "chrono/std::chrono::weekday::February", "chrono/std::chrono::weekday::March","chrono/std::chrono::weekday::April","chrono/std::chrono::weekday::May","chrono/std::chrono::weekday::June","chrono/std::chrono::weekday::July","chrono/std::chrono::weekday::August","chrono/std::chrono::weekday::September","chrono/std::chrono::weekday::October","chrono/std::chrono::weekday::November","chrono/std::chrono::weekday::December","chrono/std::chrono::weekday::operator++", "chrono/std::chrono::weekday::operator--", "chrono/std::chrono::weekday::operator unsigned", "chrono/std::chrono::weekday::ok", "chrono/std::chrono::weekday::iso_encoding", "chrono/std::chrono::weekday::c_encoding"] helpviewer_keywords: ["std::chrono [C++], weekday"] --- -# `weekday` class +# `weekday` class Represents a day of the week in the [Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar). For example, Tuesday. @@ -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` @@ -238,7 +238,7 @@ constexpr weekday& operator+=(const days& d) noexcept; ### Parameters -`*d*`\ +*`d`*\ The number of days to add. ### Return value @@ -255,7 +255,7 @@ constexpr weekday& operator-=(const days& d) noexcept; ### Parameters -`*d*`\ +*`d`*\ The number of days to subtract. ### Return value @@ -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 43e6c4bf228..0bd80a89203 100644 --- a/docs/standard-library/weekdayindexed-class.md +++ b/docs/standard-library/weekdayindexed-class.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: weekday_indexed Class" title: "weekday_indexed class" -ms.date: "06/25/2021" +description: "Learn more about: weekday_indexed Class" +ms.date: 06/25/2021 f1_keywords: ["chrono/std::chrono::weekday_indexed", "chrono/std::chrono::weekday_indexed::ok", "std::chrono::weekday_indexed::weekday", "std::chrono::weekday_indexed::ok"] helpviewer_keywords: ["std::chrono [C++], weekday_indexed"] --- -# `weekday_indexed` class +# `weekday_indexed` class Combines a weekday, representing a day of the week in the Gregorian calendar, with an index in the range [1, 5] that represents the weekday of the month (1st, 2nd, 3rd, and so on). @@ -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 543bb546885..ab0b3dff1e4 100644 --- a/docs/standard-library/weekdaylast-class.md +++ b/docs/standard-library/weekdaylast-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: weekday_last Class" title: "weekday_last class" -ms.date: "06/28/2021" +description: "Learn more about: weekday_last Class" +ms.date: 06/28/2021 f1_keywords: ["chrono/std::chrono::weekday_last", "chrono/std::chrono::weekday_last::ok", "std::chrono::weekday_last::weekday", "chrono/std::chrono::weekday_last::ok", "chrono/std::chrono::weekday_last::weekday"] helpviewer_keywords: ["std::chrono [C++], weekday_last"] --- -# `weekday_last` class +# `weekday_last` class Represents the last weekday of a month. @@ -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/wstring-convert-class.md b/docs/standard-library/wstring-convert-class.md index 8b6789b1284..41c72fa8559 100644 --- a/docs/standard-library/wstring-convert-class.md +++ b/docs/standard-library/wstring-convert-class.md @@ -1,10 +1,9 @@ --- -description: "Learn more about: wstring_convert Class" title: "wstring_convert Class" -ms.date: "11/04/2016" +description: "Learn more about: wstring_convert Class" +ms.date: 11/04/2016 f1_keywords: ["wstring/stdext::cvt::wstring_convert", "locale/std::wstring_convert::byte_string", "locale/std::wstring_convert::wide_string", "locale/std::wstring_convert::state_type", "locale/std::wstring_convert::int_type", "locale/std::wstring_convert::from_bytes", "locale/std::wstring_convert::to_bytes", "locale/std::wstring_convert::converted", "locale/std::wstring_convert::state"] helpviewer_keywords: ["stdext::cvt [C++], wstring_convert", "std::wstring_convert [C++], byte_string", "std::wstring_convert [C++], wide_string", "std::wstring_convert [C++], state_type", "std::wstring_convert [C++], int_type", "std::wstring_convert [C++], from_bytes", "std::wstring_convert [C++], to_bytes", "std::wstring_convert [C++], converted", "std::wstring_convert [C++], state"] -ms.assetid: e34f5b65-d572-4bdc-ac69-20778712e376 --- # wstring_convert Class @@ -161,8 +160,6 @@ state_type state() const; The [conversion state](../standard-library/wstring-convert-class.md) object that represents the state of the conversion. -### Remarks - ## wstring_convert::state_type A type that represents the conversion state. diff --git a/docs/standard-library/year-class.md b/docs/standard-library/year-class.md index 09d57af2b11..4ada39cf99d 100644 --- a/docs/standard-library/year-class.md +++ b/docs/standard-library/year-class.md @@ -1,11 +1,11 @@ --- -description: "Learn more about: year Class" title: "year class" -ms.date: "06/28/2021" +description: "Learn more about: year Class" +ms.date: 06/28/2021 f1_keywords: ["chrono/std::chrono::year", "chrono/std::chrono::year::operator++", "chrono/std::chrono::year::operator--", "chrono/std::chrono::year::operator+=", "chrono/std::chrono::year::operator-=", "chrono/std::chrono::year::operator int", "chrono/std::chrono::year::is_leap", "chrono/std::chrono::year::max", "chrono/std::chrono::min", "chrono/std::chrono::year::ok"] helpviewer_keywords: ["std::chrono [C++], year"] --- -# `year` class +# `year` class Represents a year in the [Gregorian calendar](https://en.wikipedia.org/wiki/Proleptic_Gregorian_calendar). @@ -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 2996d8cccb3..e76df35fa2c 100644 --- a/docs/standard-library/year-month-class.md +++ b/docs/standard-library/year-month-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: year_month class" title: "year_month class" -ms.date: "06/28/2021" +description: "Learn more about: year_month class" +ms.date: 06/28/2021 f1_keywords: ["chrono/std::chrono::year_month", "chrono/std::chrono::year_month::operator+=", "chrono/std::chrono::year_month::operator-=", "chrono/std::chrono::year_month::ok"] helpviewer_keywords: ["std::chrono [C++], year_month"] dev_langs: ["C++"] --- -# `year_month` class +# `year_month` class Represents a month and year. The day isn't specified. @@ -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 438dfc8fbee..3f40644e579 100644 --- a/docs/standard-library/year-month-day-class.md +++ b/docs/standard-library/year-month-day-class.md @@ -1,19 +1,19 @@ --- -description: "Learn more about: year_month_day class" title: "year_month_day class" -ms.date: "06/28/2021" +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"] --- -# `year_month_day` class +# `year_month_day` class 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 f6d55921c4f..b3bfc146db2 100644 --- a/docs/standard-library/year-month-day-last-class.md +++ b/docs/standard-library/year-month-day-last-class.md @@ -1,12 +1,12 @@ --- -description: "Learn more about: year_month_day_last class" title: "year_month_day_last class" -ms.date: "06/28/2021" +description: "Learn more about: year_month_day_last class" +ms.date: 06/28/2021 f1_keywords: ["chrono/std::chrono::year_month_day_last", "chrono/std::chrono::year_month_day_last::operator+=", "chrono/std::chrono::year_month_day_last::operator-=", "chrono/std::chrono::year_month_day_last::sysdays", "chrono/std::chrono::year_month_day_last::local_days", "chrono/std::chrono::year_month_day_last::day", "chrono/std::chrono::year_month_day_last::year", "chrono/std::chrono::year_month_day_last::ok"] helpviewer_keywords: ["std::chrono [C++], year_month_day_last"] dev_langs: ["C++"] --- -# `year_month_day_last` class +# `year_month_day_last` class Represents the last day of a specific year and month. @@ -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 b44e92b1f04..cb63a01c324 100644 --- a/docs/standard-library/year-month-weekday-class.md +++ b/docs/standard-library/year-month-weekday-class.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: year_month_weekday class" title: "year_month_weekday class" -ms.date: "06/30/2021" +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"] dev_langs: ["C++"] --- -# `year_month_weekday` class +# `year_month_weekday` class 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 @@ -36,7 +36,7 @@ class year_month_weekday; // C++ 20 | [`operator local_days`](#local_days) | Get the count of days from the `system_clock` epoch to this `year_month_weekday` as [`local_days`](chrono.md#typedefs). | | [`operator sys_days`](#sys_days) | Get the count of days from the `system_clock` epoch to this `year_month_weekday` as [`sys_days`](chrono.md#typedefs). | | [`weekday`](#weekday) | Get the weekday. | -| [`weekday_indexed`](#weekday_indexed) | Get the [`weekday_indexed`] stored in this `year_month_weekday`. | +| [`weekday_indexed`](#weekday_indexed) | Get the [`weekday_indexed`](weekdayindexed-class.md) stored in this `year_month_weekday`. | | [`year`](#year) | Get the year. | ## Non-members @@ -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 4e58764f6c3..d7a2a3aba2d 100644 --- a/docs/standard-library/year-month-weekday-last-class.md +++ b/docs/standard-library/year-month-weekday-last-class.md @@ -1,20 +1,20 @@ --- -description: "Learn more about: year_month_weekday_last class" title: "year_month_weekday_last class" -ms.date: "06/30/2021" +description: "Learn more about: year_month_weekday_last class" +ms.date: 06/30/2021 f1_keywords: ["chrono/std::chrono::year_month_weekday_last", "chrono/std::chrono::year_month_weekday_last::month", "chrono/std::chrono::year_month_weekday_last::year", "chrono/std::chrono::year_month_weekday_last::weekday", "chrono/std::chrono::year_month_weekday_last::weekday_last", "chrono/std::chrono::year_month_weekday_last::sys_days", "chrono/std::chrono::year_month_weekday_last::local_days", "chrono/std::chrono::year_month_weekday_last::ok", "chrono/std::chrono::year_month_weekday_last::operator+=", "chrono/std::chrono::year_month_weekday_last::operator-=", "chrono/std::chrono::year_month_weekday_last::operator local_days", "chrono/std::chrono::year_month_weekday_last::operator sys_days"] helpviewer_keywords: ["std::chrono [C++], year_month_weekday_last"] dev_langs: ["C++"] --- -# `year_month_weekday_last` class +# `year_month_weekday_last` class 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 5500c2a5a76..c5b82df46cf 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++"] --- @@ -33,7 +33,7 @@ A `zoned_time` always refers to a valid time zone and represents a point in time |[`get_time_zone`](#get_time_zone) | Gets the [time_zone](time-zone-class.md) stored in this `zoned_time`. | |[`operator=`](#op_=)| Assign the value of another `zoned_time`, or another `zoned_time`'s `local_time` or `sys_time`, to this `zoned_time`.| |[`operator local_time`](#op_local_time)| Combines the `zoned_time`'s time zone with the stored time point to produce the local time in that time zone.| -|[`operator sys_time`](#op_local_time)| Gets the time stored in this `zoned_time` without applying the time zone. | +|[`operator sys_time`](#op_sys_time)| Gets the time stored in this `zoned_time` without applying the time zone. | ## Non-members @@ -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 @@ -345,7 +345,7 @@ int main() 1\) The default copy assignment operator. Copies (doesn't move) the stored [`time_point`](time-point-class.md) and [time_zone](time-zone-class.md) pointer from the other `zoned_time` into this `zoned_time`. 2\) Assigns `st` to the [`time_point`](time-point-class.md) in this `zoned_time`. After the assignment, `*this->get_sys_time() == st;` -3\) Converts `lt` (a `local_time`) to a `sys_time`. It does this essentially as `timeZone->to_sys(lt)`, and assigns the result to the [`time_point`] in this `zoned_time`. After the assignment, `*this->get_local_time() == lt;` +3\) Converts `lt` (a `local_time`) to a `sys_time`. It does this essentially as `timeZone->to_sys(lt)`, and assigns the result to the [`time_point`](time-point-class.md) in this `zoned_time`. After the assignment, `*this->get_local_time() == lt;` ## `operator local_time` @@ -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/buffer-overflow.md b/docs/text/buffer-overflow.md index 6d7dad95dc2..3107fc90eac 100644 --- a/docs/text/buffer-overflow.md +++ b/docs/text/buffer-overflow.md @@ -4,6 +4,7 @@ title: "Buffer Overflow" ms.date: "11/04/2016" helpviewer_keywords: ["buffers [C++], character sizes", "buffer overflows [C++]", "MBCS [C++], buffer overflow"] ms.assetid: f2b7e40a-f02b-46d8-a449-51d26fc0c663 +ms.topic: how-to --- # Buffer Overflow diff --git a/docs/text/character-assignment.md b/docs/text/character-assignment.md index 0f4e4e7a831..81eaad306a9 100644 --- a/docs/text/character-assignment.md +++ b/docs/text/character-assignment.md @@ -4,6 +4,7 @@ title: "Character Assignment" ms.date: "11/04/2016" helpviewer_keywords: ["characters [C++], assignments", "MBCS [C++], character assignments"] ms.assetid: dcc329cd-92df-4e20-817d-364be62ff28f +ms.topic: how-to --- # Character Assignment diff --git a/docs/text/character-comparison.md b/docs/text/character-comparison.md index e7b4890efaf..b03f26e4cc6 100644 --- a/docs/text/character-comparison.md +++ b/docs/text/character-comparison.md @@ -4,6 +4,7 @@ title: "Character Comparison" ms.date: "11/04/2016" helpviewer_keywords: ["comparing characters", "MBCS [C++], character comparison", "characters [C++], comparing"] ms.assetid: 18846e44-3e6e-40c4-9b42-3153fb15db20 +ms.topic: how-to --- # Character Comparison diff --git a/docs/text/how-to-convert-between-various-string-types.md b/docs/text/how-to-convert-between-various-string-types.md index a02e0dcb74d..1f9286f0c49 100644 --- a/docs/text/how-to-convert-between-various-string-types.md +++ b/docs/text/how-to-convert-between-various-string-types.md @@ -2,7 +2,7 @@ description: "Learn more about: How to: Convert Between Various String Types" title: "How to: Convert Between Various String Types" ms.custom: "get-started-article" -ms.date: 05/09/2022 +ms.date: 09/29/2022 helpviewer_keywords: ["converting string types", "string conversion [C++]", "strings [C++], converting"] --- # How to: Convert between various string types @@ -17,7 +17,7 @@ For more background information about converting narrow and wide strings, see [C ## Run the examples -To run the examples in Visual Studio 2022, you can either create a new C++ Windows Console App or, if you have installed C++/CLI support, you can create a CLR Console App (.NET Framework). +To run the examples in Visual Studio 2022, you can create a new C++ Windows Console App. Or, if you've installed C++/CLI support, you can create a CLR Console App (.NET Framework). If you create a CLR Console App, you don't have to make the following changes to the compiler and debugger settings. However, you'll need to add `#include "pch.h"` to the top of each example. @@ -29,12 +29,12 @@ If you create a new C++ Windows Console app to run the examples, make the follow The `/clr` switch conflicts with some compiler switches that are set when you create a C++ Windows Console App project. The following links provide instructions for where in the IDE you can turn off the conflicting switches: -- Turn off [Set Basic Runtime Checks to Default (/RTC1)](../build/reference/rtc-run-time-error-checks.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **Code Generation** > **Basic Runtime Checks** > **Default** -- Turn off [/EHs (Exception handling model)](../build/reference/eh-exception-handling-model.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **Code Generation** > **Enable C++ Exceptions** > **No** -- Exchange [/Zi (Debug information format)](../build/reference/z7-zi-zi-debug-information-format.md#to-set-this-compiler-option-in-the-visual-studio-development-environment) for [/Z7](/cpp/build/reference/z7-zi-zi-debug-information-format#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **General** > **Debug Information Format** > **C7 compatible**. -- Turn off [/JMC (Just My Code debugging)](../build/reference/jmc.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **General** > **Support Just My Code Debugging** > **No** +- Turn off [`/RTC1` (Set Basic Runtime Checks to Default)](../build/reference/rtc-run-time-error-checks.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **Code Generation** > **Basic Runtime Checks** > **Default** +- Turn off [`/EHs` (Exception handling model)](../build/reference/eh-exception-handling-model.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **Code Generation** > **Enable C++ Exceptions** > **No** +- Exchange [`/Zi` (Debug information format)](../build/reference/z7-zi-zi-debug-information-format.md#to-set-this-compiler-option-in-the-visual-studio-development-environment) for [`/Z7`](../build/reference/z7-zi-zi-debug-information-format.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **General** > **Debug Information Format** > **C7 compatible** +- Turn off [`/JMC` (Just My Code debugging)](../build/reference/jmc.md#to-set-this-compiler-option-in-the-visual-studio-development-environment): **Project Properties** > **C/C++** > **General** > **Support Just My Code Debugging** > **No** - Set the debugger type to mixed: **Project Properties** > **Debugging** > **Debugger Type** > **Mixed (.NET framework)** -- Turn on [/ASSEMBLYDEBUG](/cpp/build/reference/assemblydebug-add-debuggableattribute#to-set-this-linker-option-in-the-visual-studio-development-environment): **Project properties** > **Linker** > **Debugging** > **Debuggable Assembly** > **Yes (ASSEMBLYDEBUG)** +- Turn on [`/ASSEMBLYDEBUG`](../build/reference/assemblydebug-add-debuggableattribute.md#to-set-this-linker-option-in-the-visual-studio-development-environment): **Project properties** > **Linker** > **Debugging** > **Debuggable Assembly** > **Yes (ASSEMBLYDEBUG)** ## Example: Convert from `char *` @@ -270,6 +270,7 @@ Hello, World! (System::String) This example demonstrates how to convert from a `_bstr_t` to other string types. The `_bstr_t` object encapsulates wide character `BSTR` strings. A `BSTR` string has a length value and doesn't use a null character to terminate the string, but the string type you convert to may require a terminating null character. For information about running and debugging this example, see [Run the examples](#run-the-examples). + ### Code ```cpp @@ -844,7 +845,7 @@ On an `en-US` language version of Windows, the code page defaults to 1033. If yo There's a mismatch in the way that `CStringA` performs a wide to narrow conversion and the way that `gcnew string(CHAR*)` performs a narrow to wide conversion. `CStringA` passes `CP_THREAD_ACP`, which means to use the current *thread* code page, to the narrowing conversion method. But `string.ctor(sbyte*)` passes `CP_ACP`, which means to use the current *system* code page, to the widening conversion method. If the system and thread code pages don't match, it can cause round-trip data corruption. -To reconcile this difference, use the constant `_CONVERSION_DONT_USE_THREAD_LOCALE`) to get the conversion to use `CP_ACP` (like .NET) instead of `CP_THREAD_ACP`. For more information, see [_CONVERSION_DONT_USE_THREAD_LOCALE](https://social.msdn.microsoft.com/Forums/vstudio/en-US/f3820781-c418-40bf-8c4f-7250001e5b68/visual-studio-2015-update-1-implicit-string-narrow-wide-conversion-and). +To reconcile this difference, use the constant `_CONVERSION_DONT_USE_THREAD_LOCALE`) to get the conversion to use `CP_ACP` (like .NET) instead of `CP_THREAD_ACP`. For more information, see [`_CONVERSION_DONT_USE_THREAD_LOCALE`](https://social.msdn.microsoft.com/Forums/vstudio/en-US/f3820781-c418-40bf-8c4f-7250001e5b68/visual-studio-2015-update-1-implicit-string-narrow-wide-conversion-and). Another approach is to use [`pinvoke`](/dotnet/standard/native-interop/pinvoke) to call [`GetThreadLocale`](/windows/win32/api/winnls/nf-winnls-getthreadlocale). Use the returned `LCID` to create a [`CultureInfo`](/dotnet/api/system.globalization.cultureinfo). Then use `CultureInfo.TextInfo` to get the code page to use in the conversion. @@ -856,8 +857,8 @@ Another approach is to use [`pinvoke`](/dotnet/standard/native-interop/pinvoke) [How to: convert `System::String` to standard `String`](../dotnet/how-to-convert-system-string-to-standard-string.md)\ [How to: convert `System::String` to `wchar_t*` or `char*`](../dotnet/how-to-convert-system-string-to-wchar-t-star-or-char-star.md)\ [Programming with `CComBSTR`](../atl/programming-with-ccombstr-atl.md)\ -[`mbstowcs_s, _mbstowcs_s_l`](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)\ -[`wcstombs_s, _wcstombs_s_l`](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)\ -[`strcpy_s, wcscpy_s, _mbscpy_s`](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md)\ -[`strcat_s, wcscat_s, _mbscat_s`](../c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md)\ +[`mbstowcs_s`, `_mbstowcs_s_l`](../c-runtime-library/reference/mbstowcs-s-mbstowcs-s-l.md)\ +[`wcstombs_s`, `_wcstombs_s_l`](../c-runtime-library/reference/wcstombs-s-wcstombs-s-l.md)\ +[`strcpy_s`, `wcscpy_s`, `_mbscpy_s`](../c-runtime-library/reference/strcpy-s-wcscpy-s-mbscpy-s.md)\ +[`strcat_s`, `wcscat_s`, `_mbscat_s`](../c-runtime-library/reference/strcat-s-wcscat-s-mbscat-s.md)\ [`pin_ptr` (C++/CLI)](../extensions/pin-ptr-cpp-cli.md) diff --git a/docs/text/incrementing-and-decrementing-pointers.md b/docs/text/incrementing-and-decrementing-pointers.md index 932ef317088..9958d4e81ab 100644 --- a/docs/text/incrementing-and-decrementing-pointers.md +++ b/docs/text/incrementing-and-decrementing-pointers.md @@ -4,6 +4,7 @@ title: "Incrementing and Decrementing Pointers" ms.date: "11/04/2016" helpviewer_keywords: ["incrementing pointers", "MBCS [C++], pointers", "pointers [C++], multibyte characters", "decrementing pointers"] ms.assetid: 0872b4a0-e2bd-4004-8319-070efb76f2fd +ms.topic: concept-article --- # Incrementing and Decrementing Pointers diff --git a/docs/text/last-character-in-a-string.md b/docs/text/last-character-in-a-string.md index bb58c45d55b..f0cb71ec368 100644 --- a/docs/text/last-character-in-a-string.md +++ b/docs/text/last-character-in-a-string.md @@ -4,6 +4,7 @@ title: "Last Character in a String" ms.date: "11/04/2016" helpviewer_keywords: ["last character in string", "MBCS [C++], last character in string"] ms.assetid: 0a180376-4e55-41e8-9c64-539c7b6d8047 +ms.topic: how-to --- # Last Character in a String diff --git a/docs/text/string-and-i-o-formatting-modern-cpp.md b/docs/text/string-and-i-o-formatting-modern-cpp.md index 1b44ad8e4c8..a122fef058f 100644 --- a/docs/text/string-and-i-o-formatting-modern-cpp.md +++ b/docs/text/string-and-i-o-formatting-modern-cpp.md @@ -2,7 +2,7 @@ title: "String and I/O Formatting (Modern C++)" description: "Choices for formatted string I/O available in modern C++." ms.date: "05/30/2019" -ms.topic: "conceptual" +ms.topic: "concept-article" ms.assetid: 3954e8de-a59b-4175-89c9-4ee842ab89ed --- # String and I/O Formatting (Modern C++) diff --git a/docs/text/support-for-multibyte-character-sets-mbcss.md b/docs/text/support-for-multibyte-character-sets-mbcss.md index 5b1d9cd4de3..2520d3d343e 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/text/text-and-strings-in-visual-cpp.md b/docs/text/text-and-strings-in-visual-cpp.md index f7802b98794..2334f6557ec 100644 --- a/docs/text/text-and-strings-in-visual-cpp.md +++ b/docs/text/text-and-strings-in-visual-cpp.md @@ -1,13 +1,12 @@ --- -description: "Learn more about: Text and Strings in Visual C++" title: "Text and Strings in Visual C++" -ms.date: "11/04/2016" +description: "Learn more about: Text and Strings in Visual C++" +ms.date: 11/04/2016 helpviewer_keywords: ["globalization [C++], character sets", "programming [C++], international", "multiple language support [C++]", "Unicode [C++]", "international applications [C++], about international applications", "portability [C++]", "translation [C++], character sets", "non-European characters [C++]", "character sets [C++]", "globalization [C++]", "Japanese characters [C++]", "Kanji character support [C++]", "local character sets [C++]", "ASCII characters [C++]", "character sets [C++], about character sets", "localization [C++], character sets", "translating code [C++]", "localization [C++]", "character sets [C++], non-European", "portability [C++], character sets", "MBCS [C++], international programming"] -ms.assetid: a1bb27ac-abe5-4c6b-867d-f761d4b93205 --- # Text and Strings in Visual C++ -An important aspect of developing applications for international markets is the adequate representation of local character sets. The ASCII character set defines characters in the range 0x00 to 0x7F. There are other character sets, primarily European, that define the characters within the range 0x00 to 0x7F identically to the ASCII character set and also define an extended character set from 0x80 to 0xFF. Thus, an 8-bit, single-byte-character set (SBCS) is sufficient to represent the ASCII character set, as well as the character sets for many European languages. However, some non-European character sets, such as Japanese Kanji, include many more characters than a single-byte coding scheme can represent, and therefore require multibyte-character set (MBCS) encoding. +An important aspect of developing applications for international markets is the adequate representation of local character sets. The ASCII character set defines characters in the range 0x00 - 0x7F. There are other character sets, primarily European, that define the characters within the range 0x00 - 0x7F identically to the ASCII character set and also define an extended character set from 0x80 - 0xFF. Thus, an 8-bit, single-byte-character set (SBCS) is sufficient to represent the ASCII character set and the character sets for many European languages. However, some non-European character sets, such as Japanese Kanji, include many more characters than a single-byte coding scheme can represent, and therefore require multibyte-character set (MBCS) encoding. ## In This Section diff --git a/docs/text/using-tchar-h-data-types-with-mbcs-code.md b/docs/text/using-tchar-h-data-types-with-mbcs-code.md index d9d216041f9..c800f793487 100644 --- a/docs/text/using-tchar-h-data-types-with-mbcs-code.md +++ b/docs/text/using-tchar-h-data-types-with-mbcs-code.md @@ -4,6 +4,7 @@ title: "Using TCHAR.H Data Types with _MBCS Code" ms.date: "11/04/2016" helpviewer_keywords: ["mapping generic-text", "generic-text data types [C++]", "generic-text mappings [C++]", "MBCS [C++], generic-text mappings", "TCHAR.H data types, mapping", "mappings [C++], TCHAR.H"] ms.assetid: 298583c5-22c3-40f6-920e-9ec96d42abd8 +ms.topic: concept-article --- # Using TCHAR.H Data Types with _MBCS Code diff --git a/docs/windows/adding-editing-or-deleting-controls.md b/docs/windows/adding-editing-or-deleting-controls.md index e068e19ef64..11e5400f7d9 100644 --- a/docs/windows/adding-editing-or-deleting-controls.md +++ b/docs/windows/adding-editing-or-deleting-controls.md @@ -1,10 +1,10 @@ --- -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 +ms.topic: how-to --- # How To: Add, Edit, or Delete Controls (C++) @@ -204,17 +204,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 7bdc8e9945b..1c2b92daa72 100644 --- a/docs/windows/arrangement-of-controls-on-dialog-boxes.md +++ b/docs/windows/arrangement-of-controls-on-dialog-boxes.md @@ -1,10 +1,11 @@ --- 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"] ms.assetid: 832491cf-98af-42e5-a854-2cb135fd45c6 +ms.topic: how-to --- # How To: Layout Controls (C++) diff --git a/docs/windows/attributes/attributes-alphabetical-reference.md b/docs/windows/attributes/attributes-alphabetical-reference.md index 2e6948ed8f4..375d6a5736d 100644 --- a/docs/windows/attributes/attributes-alphabetical-reference.md +++ b/docs/windows/attributes/attributes-alphabetical-reference.md @@ -3,7 +3,7 @@ description: "Learn more about: Attributes Alphabetical Reference" title: "Attributes Alphabetical Reference" ms.custom: "index-page" ms.date: "10/02/2018" -ms.topic: "conceptual" +ms.topic: "concept-article" f1_keywords: ["vc.attributes"] helpviewer_keywords: ["attributes [C++/CLI]"] ms.assetid: fb2216ef-9fbd-44f4-afed-732aa99450e2 diff --git a/docs/windows/attributes/attributes-by-group.md b/docs/windows/attributes/attributes-by-group.md index e344d58f67a..42a1cd2787f 100644 --- a/docs/windows/attributes/attributes-by-group.md +++ b/docs/windows/attributes/attributes-by-group.md @@ -3,7 +3,7 @@ description: "Learn more about: Attributes by Group" title: "Attributes by Group" ms.custom: "index-page" ms.date: "10/02/2018" -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["attributes [C++/CLI]"] ms.assetid: 9f4dd43f-9909-43d6-91d2-05734643876e --- diff --git a/docs/windows/attributes/attributes-by-usage.md b/docs/windows/attributes/attributes-by-usage.md index ea43dfd652a..628c0a616ba 100644 --- a/docs/windows/attributes/attributes-by-usage.md +++ b/docs/windows/attributes/attributes-by-usage.md @@ -3,7 +3,7 @@ description: "Learn more about: Attributes by Usage" title: "Attributes by Usage" ms.custom: "index-page" ms.date: "10/02/2018" -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["attributes [C++/CLI]"] ms.assetid: 8be2de10-b1ff-4ca4-a114-75318408593c --- diff --git a/docs/windows/attributes/cpp-attributes-com-net.md b/docs/windows/attributes/cpp-attributes-com-net.md index 822412ed440..3ca2ca8b5b9 100644 --- a/docs/windows/attributes/cpp-attributes-com-net.md +++ b/docs/windows/attributes/cpp-attributes-com-net.md @@ -1,11 +1,10 @@ --- -description: "Learn more about: C++ Attributes for COM and .NET" title: "C++ Attributes for COM and .NET" +description: "Learn more about: C++ Attributes for COM and .NET" +ms.date: 11/19/2018 ms.custom: "index-page" -ms.date: "11/19/2018" -ms.topic: "conceptual" +ms.topic: "concept-article" helpviewer_keywords: ["attributes [C++/CLI], reference topics"] -ms.assetid: 613a3611-b3eb-4347-aa38-99b654600e1c --- # C++ Attributes for COM and .NET @@ -52,7 +51,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 +93,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. 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](../../build/reference/fx-merge-injected-code.md), you can create a merged source file that contains original and injected code. + +The **Disassembly** window shows assembly-language instructions that correspond to the source code and the code injected by attributes. In addition, the **Disassembly** window can show the source-code annotation. + +### To turn on Source Annotation + +- Right-click the **Disassembly** window, and choose **Show Source Code** from the shortcut menu. + + If you know the location of an attribute in a source window, you can use the shortcut menu to find the injected code in the **Disassembly** window. + +### To view injected code + +1. The debugger must be in break mode. + +2. In a source code window, place the cursor in front of the attribute whose injected code you want to view. + +3. Right-click, and select **Go To Disassembly** from the shortcut menu. + + If the attribute location is near the current execution point, you can select the **Disassembly** window from the **Debug** menu. + +### To view the disassembly code at the current execution point + +1. The debugger must be in break mode. + +2. From the **Debug** menu, choose **Windows**, and click **Disassembly**. + ## In This Section [Attribute Programming FAQ](attribute-programming-faq.yml)
diff --git a/docs/windows/attributes/db-param.md b/docs/windows/attributes/db-param.md index 51538ad0a29..cebb586d5d6 100644 --- a/docs/windows/attributes/db-param.md +++ b/docs/windows/attributes/db-param.md @@ -5,6 +5,7 @@ ms.date: "10/02/2018" f1_keywords: ["vc-attr.db_param"] helpviewer_keywords: ["db_param attribute"] ms.assetid: a28315f5-4722-459e-92ef-32e83c0b205a +ms.custom: sfi-ropc-nochange --- # db_param diff --git a/docs/windows/attributes/db-source.md b/docs/windows/attributes/db-source.md index 4b5d1ff5a7b..d54e30f8a4f 100644 --- a/docs/windows/attributes/db-source.md +++ b/docs/windows/attributes/db-source.md @@ -5,6 +5,7 @@ ms.date: "10/02/2018" f1_keywords: ["vc-attr.db_source"] helpviewer_keywords: ["db_source attribute"] ms.assetid: 0ec8bbf7-ade2-4899-bf4c-8608b92779bc +ms.custom: sfi-ropc-nochange --- # db_source diff --git a/docs/windows/attributes/module-cpp.md b/docs/windows/attributes/module-cpp.md index 5f6b6ff712d..70f41752407 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 5229957fbb3..768618d8319 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/changing-a-symbol-or-symbol-name-id.md b/docs/windows/changing-a-symbol-or-symbol-name-id.md index 03e9c25ca31..82376571371 100644 --- a/docs/windows/changing-a-symbol-or-symbol-name-id.md +++ b/docs/windows/changing-a-symbol-or-symbol-name-id.md @@ -5,6 +5,7 @@ ms.date: "02/14/2019" f1_keywords: ["vc.editors.symbol.changing", "vc.editors.symbol.restrictions.name", "vc.editors.symbol.changing.value", "vc.editors.symbol.restrictions.value", "vc.editors.symbol.changing.header", "vc.editors.symbol.changing.unassigned", "vc.editors.symbol.shared.calculated"] helpviewer_keywords: ["symbol names", "symbols [C++], names", "restrictions, symbol names", "numeric values", "symbols [C++], numeric values", "numeric values, changing symbols", "symbols [C++], value restrictions", "restrictions, symbol values", "resource files [C++], multiple", "Resource Includes dialog box [C++]", "symbol header files [C++], changing names", "symbols [C++], symbol header files", "Resource.h", "symbols [C++], unassigned", "Change Symbol dialog box [C++]", "unassigned symbols", "symbols [C++], deleting", "symbols [C++], read-only", "symbols [C++], shared", "symbols [C++], calculated", "read-only symbols", "symbol directives", "calculated symbols", "shared symbols"] ms.assetid: 26541832-8dba-4177-b642-e08f94502ea7 +ms.topic: how-to --- # How to: Manage Symbols diff --git a/docs/windows/clickonce-deployment-for-visual-cpp-applications.md b/docs/windows/clickonce-deployment-for-visual-cpp-applications.md index 4a36f96cb66..1824562d2ab 100644 --- a/docs/windows/clickonce-deployment-for-visual-cpp-applications.md +++ b/docs/windows/clickonce-deployment-for-visual-cpp-applications.md @@ -1,30 +1,27 @@ --- -description: "Learn more about: ClickOnce Deployment for Visual C++ Applications" -title: "ClickOnce Deployment for Visual C++ Applications" +description: "Learn more about: ClickOnce Deployment for Microsoft C++ Applications" +title: "ClickOnce Deployment for Microsoft 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 +# ClickOnce Deployment for Microsoft C++ Applications Visual Studio provides two different technologies for deploying Windows applications: ClickOnce deployment or [Windows Installer](/windows/win32/Msi/windows-installer-portal) deployment. ## 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 Microsoft C++ application if it is a dependency of a C# or VB.NET project. For example, if you have a C# project that depends on a C++ project, you can publish the application (including its dependencies) using ClickOnce deployment from the C# development environment. If you have a Visual Basic .NET project that depends on a 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)). +To deploy a 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 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 Microsoft C++ Application](understanding-the-dependencies-of-a-visual-cpp-application.md). You might need to run VCRedist.exe; this utility installs 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 a6c53fd36d9..7dd305bb828 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-a-new-dialog-box.md b/docs/windows/creating-a-new-dialog-box.md index 50d344c9a50..9552cf35923 100644 --- a/docs/windows/creating-a-new-dialog-box.md +++ b/docs/windows/creating-a-new-dialog-box.md @@ -4,6 +4,7 @@ title: "How To: Create a Dialog Box (C++)" ms.date: "02/15/2019" helpviewer_keywords: ["dialog boxes [C++], creating", "Dialog Editor [C++], creating dialog boxes", "modal dialog boxes [C++], logon screens", "logon screens", "Test Dialog command", "testing, dialog boxes", "dialog boxes [C++], testing", "dialog boxes [C++], size", "dialog boxes [C++], positioning"] ms.assetid: 303de801-c4f8-42e1-b622-353f6423f688 +ms.topic: how-to --- # How to: Create a Dialog Box (C++) 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 004896d77c5..5c477289796 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,24 @@ --- -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" +title: "Create an icon or other image" +description: "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 +37,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 +50,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 +99,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 +126,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 +160,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 +174,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 +189,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 +209,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 +227,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 +245,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)